diff --git a/.ci/write-dockerfile.sh b/.ci/write-dockerfile.sh index 63f03ea5e3e..75f89b23868 100755 --- a/.ci/write-dockerfile.sh +++ b/.ci/write-dockerfile.sh @@ -354,7 +354,7 @@ RUN cd /new && rm -rf .git && \ mv src /sage/src; \ cd /sage && ./bootstrap && ./config.status; \ fi; \ - cd /sage && rm -rf /new .git + cd /sage && rm -rf .git; rm -rf /new || echo "(error ignored)" ARG TARGETS="build" $RUN $CHECK_STATUS_THEN make SAGE_SPKG="sage-spkg -y -o" \${USE_MAKEFLAGS} \${TARGETS} $ENDRUN $THEN_SAVE_STATUS diff --git a/.github/workflows/ci-linux-incremental.yml b/.github/workflows/ci-linux-incremental.yml index ce468ff3a42..a7900534b32 100644 --- a/.github/workflows/ci-linux-incremental.yml +++ b/.github/workflows/ci-linux-incremental.yml @@ -124,7 +124,8 @@ jobs: # with only a small number of test failures as of 10.2.rc0 tox_system_factors: >- ["gentoo-python3.11", - "archlinux-latest"] + "archlinux-latest", + "fedora-40"] tox_packages_factors: >- ["standard-sitepackages"] docker_push_repository: ghcr.io/${{ github.repository }}/ diff --git a/.github/workflows/ci-linux.yml b/.github/workflows/ci-linux.yml index 0ce9a1f142b..cae29a27819 100644 --- a/.github/workflows/ci-linux.yml +++ b/.github/workflows/ci-linux.yml @@ -116,8 +116,7 @@ jobs: "debian-sid", "linuxmint-21.1", "linuxmint-21.2", - "fedora-38", - "fedora-39", + "fedora-40", "centos-stream-9-python3.9", "almalinux-8-python3.9", "gentoo-python3.10", diff --git a/build/pkgs/4ti2/distros/fedora.txt b/build/pkgs/4ti2/distros/fedora.txt index 252f9efdbd4..b8cd8817e37 100644 --- a/build/pkgs/4ti2/distros/fedora.txt +++ b/build/pkgs/4ti2/distros/fedora.txt @@ -1 +1,2 @@ 4ti2 +4ti2-devel diff --git a/build/pkgs/_python3.9/distros/fedora.txt b/build/pkgs/_python3.9/distros/fedora.txt index 334e29fce37..0e9352ce64c 100644 --- a/build/pkgs/_python3.9/distros/fedora.txt +++ b/build/pkgs/_python3.9/distros/fedora.txt @@ -1,3 +1,3 @@ python3.9 -python3.9-devel # Except on centos-stream-8 and almalinux-8, where it is called python39 and python39-devel; we special-case this in tox.ini +# python3.9 does not exist any more diff --git a/build/pkgs/beautifulsoup4/distros/fedora.txt b/build/pkgs/beautifulsoup4/distros/fedora.txt index 2e8f9a66b24..dc3b2b6ed9e 100644 --- a/build/pkgs/beautifulsoup4/distros/fedora.txt +++ b/build/pkgs/beautifulsoup4/distros/fedora.txt @@ -1 +1 @@ -python-beautifulsoup4 +python3-beautifulsoup4 diff --git a/build/pkgs/beniget/distros/fedora.txt b/build/pkgs/beniget/distros/fedora.txt new file mode 100644 index 00000000000..90ac5122f63 --- /dev/null +++ b/build/pkgs/beniget/distros/fedora.txt @@ -0,0 +1 @@ +python3-beniget diff --git a/build/pkgs/biopython/distros/fedora.txt b/build/pkgs/biopython/distros/fedora.txt new file mode 100644 index 00000000000..49a99dcc80b --- /dev/null +++ b/build/pkgs/biopython/distros/fedora.txt @@ -0,0 +1 @@ +python3-biopython diff --git a/build/pkgs/bleach/distros/fedora.txt b/build/pkgs/bleach/distros/fedora.txt index c5422ccff0c..6d37c4c79f0 100644 --- a/build/pkgs/bleach/distros/fedora.txt +++ b/build/pkgs/bleach/distros/fedora.txt @@ -1 +1 @@ -python-bleach +python3-bleach diff --git a/build/pkgs/ccache/distros/fedora.txt b/build/pkgs/ccache/distros/fedora.txt new file mode 100644 index 00000000000..812b9efc0c5 --- /dev/null +++ b/build/pkgs/ccache/distros/fedora.txt @@ -0,0 +1 @@ +ccache diff --git a/build/pkgs/cddlib/distros/fedora.txt b/build/pkgs/cddlib/distros/fedora.txt index f9afcc0b330..e80835cf4c4 100644 --- a/build/pkgs/cddlib/distros/fedora.txt +++ b/build/pkgs/cddlib/distros/fedora.txt @@ -1 +1,2 @@ cddlib +cddlib-devel diff --git a/build/pkgs/certifi/distros/fedora.txt b/build/pkgs/certifi/distros/fedora.txt index be421c8b4b2..f585a823bf3 100644 --- a/build/pkgs/certifi/distros/fedora.txt +++ b/build/pkgs/certifi/distros/fedora.txt @@ -1 +1 @@ -python-certifi +python3-certifi diff --git a/build/pkgs/cffi/distros/fedora.txt b/build/pkgs/cffi/distros/fedora.txt new file mode 100644 index 00000000000..68ec4dda5ba --- /dev/null +++ b/build/pkgs/cffi/distros/fedora.txt @@ -0,0 +1 @@ +python3-cffi diff --git a/build/pkgs/charset_normalizer/distros/fedora.txt b/build/pkgs/charset_normalizer/distros/fedora.txt new file mode 100644 index 00000000000..0d65ed70186 --- /dev/null +++ b/build/pkgs/charset_normalizer/distros/fedora.txt @@ -0,0 +1 @@ +python3-charset-normalizer diff --git a/build/pkgs/cocoalib/distros/fedora.txt b/build/pkgs/cocoalib/distros/fedora.txt new file mode 100644 index 00000000000..8eaa0438abe --- /dev/null +++ b/build/pkgs/cocoalib/distros/fedora.txt @@ -0,0 +1,2 @@ +cocoalib +cocoalib-devel diff --git a/build/pkgs/comm/fedora.txt b/build/pkgs/comm/fedora.txt new file mode 100644 index 00000000000..8e049b4f279 --- /dev/null +++ b/build/pkgs/comm/fedora.txt @@ -0,0 +1 @@ +python3-comm diff --git a/build/pkgs/configure/checksums.ini b/build/pkgs/configure/checksums.ini index 4195c94ea50..c0bfcc43e96 100644 --- a/build/pkgs/configure/checksums.ini +++ b/build/pkgs/configure/checksums.ini @@ -1,3 +1,3 @@ tarball=configure-VERSION.tar.gz -sha1=442147504b01035e9cc36d5a726c454fbebd05ba -sha256=ebd714e56d0435cfd0e8faf94d3e9fc27c91a3d7dfeb42efb5b796fda1567a64 +sha1=d21dcef9ea75fb52a89af8592796f8a2d97d3f2f +sha256=ce97f7eecff470cc7dc4c6dce7f0e5e7e85382c2411b23bc6eb9c6934b002ada diff --git a/build/pkgs/configure/package-version.txt b/build/pkgs/configure/package-version.txt index 19a7b2187c8..5b63fa16ca1 100644 --- a/build/pkgs/configure/package-version.txt +++ b/build/pkgs/configure/package-version.txt @@ -1 +1 @@ -238f042e65932c80a81e6841c10e6abcf8ed6e4f +f473d0954b37ab99d3530145c0f4536e4f0d88c9 diff --git a/build/pkgs/contourpy/distros/fedora.txt b/build/pkgs/contourpy/distros/fedora.txt new file mode 100644 index 00000000000..be8588038ac --- /dev/null +++ b/build/pkgs/contourpy/distros/fedora.txt @@ -0,0 +1 @@ +python3-contourpy diff --git a/build/pkgs/cppy/distros/fedora.txt b/build/pkgs/cppy/distros/fedora.txt new file mode 100644 index 00000000000..43b5e0ef3fc --- /dev/null +++ b/build/pkgs/cppy/distros/fedora.txt @@ -0,0 +1 @@ +python3-cppy diff --git a/build/pkgs/csdp/distros/fedora.txt b/build/pkgs/csdp/distros/fedora.txt new file mode 100644 index 00000000000..81b063c46f1 --- /dev/null +++ b/build/pkgs/csdp/distros/fedora.txt @@ -0,0 +1,3 @@ +csdp +csdp-devel +csdp-tools diff --git a/build/pkgs/cvxopt/distros/fedora.txt b/build/pkgs/cvxopt/distros/fedora.txt index f15770f0506..2bb6ad1e834 100644 --- a/build/pkgs/cvxopt/distros/fedora.txt +++ b/build/pkgs/cvxopt/distros/fedora.txt @@ -1 +1 @@ -python-cvxopt +python3-cvxopt diff --git a/build/pkgs/cycler/distros/fedora.txt b/build/pkgs/cycler/distros/fedora.txt index 5727259aca6..c77685dd417 100644 --- a/build/pkgs/cycler/distros/fedora.txt +++ b/build/pkgs/cycler/distros/fedora.txt @@ -1 +1 @@ -python-cycler +python3-cycler diff --git a/build/pkgs/cython/distros/fedora.txt b/build/pkgs/cython/distros/fedora.txt index 002d1b93c6f..a91271fa321 100644 --- a/build/pkgs/cython/distros/fedora.txt +++ b/build/pkgs/cython/distros/fedora.txt @@ -1 +1 @@ -Cython +python3-cython diff --git a/build/pkgs/dateutil/distros/fedora.txt b/build/pkgs/dateutil/distros/fedora.txt index 0f08daace31..2f46170765c 100644 --- a/build/pkgs/dateutil/distros/fedora.txt +++ b/build/pkgs/dateutil/distros/fedora.txt @@ -1 +1 @@ -python-dateutil +python3-dateutil diff --git a/build/pkgs/decorator/distros/fedora.txt b/build/pkgs/decorator/distros/fedora.txt index 079560412f1..46c478e1513 100644 --- a/build/pkgs/decorator/distros/fedora.txt +++ b/build/pkgs/decorator/distros/fedora.txt @@ -1 +1 @@ -python-decorator +python3-decorator diff --git a/build/pkgs/defusedxml/distros/fedora.txt b/build/pkgs/defusedxml/distros/fedora.txt new file mode 100644 index 00000000000..9788c955af5 --- /dev/null +++ b/build/pkgs/defusedxml/distros/fedora.txt @@ -0,0 +1 @@ +python3-defusedxml diff --git a/build/pkgs/docutils/distros/fedora.txt b/build/pkgs/docutils/distros/fedora.txt new file mode 100644 index 00000000000..a4bb792a5a4 --- /dev/null +++ b/build/pkgs/docutils/distros/fedora.txt @@ -0,0 +1 @@ +python3-docutils diff --git a/build/pkgs/dot2tex/distros/fedora.txt b/build/pkgs/dot2tex/distros/fedora.txt new file mode 100644 index 00000000000..4d0a832a550 --- /dev/null +++ b/build/pkgs/dot2tex/distros/fedora.txt @@ -0,0 +1 @@ +dot2tex diff --git a/build/pkgs/editables/distros/fedora.txt b/build/pkgs/editables/distros/fedora.txt new file mode 100644 index 00000000000..359d9f1d8c8 --- /dev/null +++ b/build/pkgs/editables/distros/fedora.txt @@ -0,0 +1 @@ +python3-editables diff --git a/build/pkgs/entrypoints/distros/fedora.txt b/build/pkgs/entrypoints/distros/fedora.txt new file mode 100644 index 00000000000..6e1b57c91e7 --- /dev/null +++ b/build/pkgs/entrypoints/distros/fedora.txt @@ -0,0 +1 @@ +python3-entrypoints diff --git a/build/pkgs/executing/distros/fedora.txt b/build/pkgs/executing/distros/fedora.txt new file mode 100644 index 00000000000..4504024d6da --- /dev/null +++ b/build/pkgs/executing/distros/fedora.txt @@ -0,0 +1 @@ +python3-executing diff --git a/build/pkgs/fastjsonschema/distros/fedora.txt b/build/pkgs/fastjsonschema/distros/fedora.txt index 7a8bdf5369b..aba120db917 100644 --- a/build/pkgs/fastjsonschema/distros/fedora.txt +++ b/build/pkgs/fastjsonschema/distros/fedora.txt @@ -1 +1 @@ -python-fastjsonschema +python3-fastjsonschema diff --git a/build/pkgs/ffmpeg/distros/fedora.txt b/build/pkgs/ffmpeg/distros/fedora.txt index 2034a7b9f77..f5f02b5af1b 100644 --- a/build/pkgs/ffmpeg/distros/fedora.txt +++ b/build/pkgs/ffmpeg/distros/fedora.txt @@ -1,3 +1,5 @@ # ffmpeg is not in the standard Fedora repository # Need "RPM Fusion Free" #ffmpeg +ffmpeg-free +ffmpeg-free-devel diff --git a/build/pkgs/flit_core/distros/fedora.txt b/build/pkgs/flit_core/distros/fedora.txt new file mode 100644 index 00000000000..587eaa96e19 --- /dev/null +++ b/build/pkgs/flit_core/distros/fedora.txt @@ -0,0 +1 @@ +python3-flit-core diff --git a/build/pkgs/fonttools/distros/fedora.txt b/build/pkgs/fonttools/distros/fedora.txt new file mode 100644 index 00000000000..cf25e11afc2 --- /dev/null +++ b/build/pkgs/fonttools/distros/fedora.txt @@ -0,0 +1 @@ +python3-fonttools diff --git a/build/pkgs/fpylll/dependencies b/build/pkgs/fpylll/dependencies index 4837249bcfa..03eb318a449 100644 --- a/build/pkgs/fpylll/dependencies +++ b/build/pkgs/fpylll/dependencies @@ -1,4 +1,4 @@ - cython cysignals numpy fplll | $(PYTHON) + cython cysignals numpy fplll | $(PYTHON_TOOLCHAIN) $(PYTHON) ---------- All lines of this file are ignored except the first. diff --git a/build/pkgs/free_fonts/distros/fedora.txt b/build/pkgs/free_fonts/distros/fedora.txt index 435c13a9578..9f7b4c7ddec 100644 --- a/build/pkgs/free_fonts/distros/fedora.txt +++ b/build/pkgs/free_fonts/distros/fedora.txt @@ -1,3 +1,4 @@ gnu-free-mono-fonts gnu-free-sans-fonts gnu-free-serif-fonts +texlive-gnu-freefont diff --git a/build/pkgs/frobby/distros/fedora.txt b/build/pkgs/frobby/distros/fedora.txt new file mode 100644 index 00000000000..96768b37be5 --- /dev/null +++ b/build/pkgs/frobby/distros/fedora.txt @@ -0,0 +1,3 @@ +frobby +libfrobby +libfrobby-devel diff --git a/build/pkgs/furo/distros/fedora.txt b/build/pkgs/furo/distros/fedora.txt index d274c983622..cf3eeefa6e7 100644 --- a/build/pkgs/furo/distros/fedora.txt +++ b/build/pkgs/furo/distros/fedora.txt @@ -1 +1 @@ -python-furo +python3-furo diff --git a/build/pkgs/gap/distros/fedora.txt b/build/pkgs/gap/distros/fedora.txt index 6c561683bf4..7b8424662a7 100644 --- a/build/pkgs/gap/distros/fedora.txt +++ b/build/pkgs/gap/distros/fedora.txt @@ -1,5 +1,72 @@ +# some packages are missing in Fedora gap gap-core gap-devel gap-libs libgap +xgap +gap-pkg-ace +gap-pkg-aclib +gap-pkg-alnuth +gap-pkg-anupq +gap-pkg-atlasrep +gap-pkg-autodoc +gap-pkg-automata +gap-pkg-autpgrp +gap-pkg-browse +gap-pkg-caratinterface +gap-pkg-circle +gap-pkg-congruence +gap-pkg-crisp +gap-pkg-crypting +gap-pkg-crystcat +gap-pkg-curlinterface +gap-pkg-cvec +gap-pkg-datastructures +gap-pkg-digraphs +gap-pkg-edim +gap-pkg-ferret +gap-pkg-fga +gap-pkg-fining +gap-pkg-float +gap-pkg-format +gap-pkg-forms +gap-pkg-fplsa +gap-pkg-fr +gap-pkg-francy +gap-pkg-genss +gap-pkg-groupoids +gap-pkg-grpconst +gap-pkg-images +gap-pkg-io +gap-pkg-irredsol +gap-pkg-json +gap-pkg-jupyterviz +gap-pkg-lpres +gap-pkg-nq +gap-pkg-openmath +gap-pkg-orb +gap-pkg-permut +gap-pkg-polenta +gap-pkg-polycyclic +gap-pkg-primgrp +gap-pkg-profiling +gap-pkg-radiroot +gap-pkg-recog +gap-pkg-resclasses +gap-pkg-scscp +gap-pkg-semigroups +gap-pkg-singular +gap-pkg-smallgrp +gap-pkg-smallsemi +gap-pkg-sophus +gap-pkg-spinsym +gap-pkg-standardff +gap-pkg-tomlib +gap-pkg-transgrp +gap-pkg-transgrp-data +gap-pkg-utils +gap-pkg-uuid +gap-pkg-xmod +gap-pkg-zeromqinterface + diff --git a/build/pkgs/gap_jupyter/distros/fedora.txt b/build/pkgs/gap_jupyter/distros/fedora.txt new file mode 100644 index 00000000000..0ceec7c99a4 --- /dev/null +++ b/build/pkgs/gap_jupyter/distros/fedora.txt @@ -0,0 +1 @@ +gap-pkg-jupyterkernel diff --git a/build/pkgs/gap_packages/distros/fedora.txt b/build/pkgs/gap_packages/distros/fedora.txt new file mode 100644 index 00000000000..24d6af73b6b --- /dev/null +++ b/build/pkgs/gap_packages/distros/fedora.txt @@ -0,0 +1,27 @@ +gap-pkg-cohomolo +gap-pkg-corelg +gap-pkg-crime +gap-pkg-cryst +gap-pkg-ctbllib +gap-pkg-design +gap-pkg-factint +GAPDoc +gap-pkg-gbnp +gap-pkg-grape +gap-pkg-guava +gap-pkg-hap +gap-pkg-hapcryst +gap-pkg-hecke +gap-pkg-laguna +gap-pkg-liealgdb +gap-pkg-liepring +gap-pkg-liering +gap-pkg-loops +gap-pkg-mapclass +gap-pkg-polymaking +gap-pkg-qpa +gap-pkg-quagroup +gap-pkg-repsn +gap-pkg-sla +gap-pkg-sonata +gap-pkg-toric diff --git a/build/pkgs/gast/distros/fedora.txt b/build/pkgs/gast/distros/fedora.txt new file mode 100644 index 00000000000..40cddc76e37 --- /dev/null +++ b/build/pkgs/gast/distros/fedora.txt @@ -0,0 +1 @@ +python3-gast diff --git a/build/pkgs/gdb/distros/fedora.txt b/build/pkgs/gdb/distros/fedora.txt new file mode 100644 index 00000000000..59ccb367d89 --- /dev/null +++ b/build/pkgs/gdb/distros/fedora.txt @@ -0,0 +1 @@ +gdb diff --git a/build/pkgs/gmpy2/distros/fedora.txt b/build/pkgs/gmpy2/distros/fedora.txt index d4464a5ce2c..afdd6281722 100644 --- a/build/pkgs/gmpy2/distros/fedora.txt +++ b/build/pkgs/gmpy2/distros/fedora.txt @@ -1 +1 @@ -python-gmpy2 +python3-gmpy2 diff --git a/build/pkgs/gp2c/distros/fedora.txt b/build/pkgs/gp2c/distros/fedora.txt new file mode 100644 index 00000000000..f4ab6d425f1 --- /dev/null +++ b/build/pkgs/gp2c/distros/fedora.txt @@ -0,0 +1 @@ +gp2c diff --git a/build/pkgs/hatchling/distros/fedora.txt b/build/pkgs/hatchling/distros/fedora.txt new file mode 100644 index 00000000000..517bb7a854b --- /dev/null +++ b/build/pkgs/hatchling/distros/fedora.txt @@ -0,0 +1 @@ +python3-hatchling diff --git a/build/pkgs/idna/distros/fedora.txt b/build/pkgs/idna/distros/fedora.txt index a73e70cade0..de48e70887b 100644 --- a/build/pkgs/idna/distros/fedora.txt +++ b/build/pkgs/idna/distros/fedora.txt @@ -1 +1 @@ -python-idna +python3-idna diff --git a/build/pkgs/imagesize/distros/fedora.txt b/build/pkgs/imagesize/distros/fedora.txt new file mode 100644 index 00000000000..f482427979f --- /dev/null +++ b/build/pkgs/imagesize/distros/fedora.txt @@ -0,0 +1 @@ +python3-imagesize diff --git a/build/pkgs/importlib_metadata/distros/fedora.txt b/build/pkgs/importlib_metadata/distros/fedora.txt index b3c206287ec..c005bf38793 100644 --- a/build/pkgs/importlib_metadata/distros/fedora.txt +++ b/build/pkgs/importlib_metadata/distros/fedora.txt @@ -1 +1 @@ -python-importlib-metadata +python3-importlib-metadata diff --git a/build/pkgs/ipykernel/distros/fedora.txt b/build/pkgs/ipykernel/distros/fedora.txt index 286458797f7..71e84c46f0e 100644 --- a/build/pkgs/ipykernel/distros/fedora.txt +++ b/build/pkgs/ipykernel/distros/fedora.txt @@ -1 +1 @@ -python-ipykernel +python3-ipykernel diff --git a/build/pkgs/ipython/distros/fedora.txt b/build/pkgs/ipython/distros/fedora.txt index 49a7ffe2a95..c32c6b449cf 100644 --- a/build/pkgs/ipython/distros/fedora.txt +++ b/build/pkgs/ipython/distros/fedora.txt @@ -1 +1 @@ -ipython +python3-ipython diff --git a/build/pkgs/ipython_genutils/distros/fedora.txt b/build/pkgs/ipython_genutils/distros/fedora.txt new file mode 100644 index 00000000000..b553f94d87c --- /dev/null +++ b/build/pkgs/ipython_genutils/distros/fedora.txt @@ -0,0 +1 @@ +python3-ipython_genutils diff --git a/build/pkgs/ipywidgets/distros/fedora.txt b/build/pkgs/ipywidgets/distros/fedora.txt new file mode 100644 index 00000000000..a4cd0d161cf --- /dev/null +++ b/build/pkgs/ipywidgets/distros/fedora.txt @@ -0,0 +1 @@ +python3-ipywidgets diff --git a/build/pkgs/isl/distros/fedora.txt b/build/pkgs/isl/distros/fedora.txt index d54c646d7a7..755b69ce18b 100644 --- a/build/pkgs/isl/distros/fedora.txt +++ b/build/pkgs/isl/distros/fedora.txt @@ -1 +1,2 @@ +isl isl-devel diff --git a/build/pkgs/jedi/distros/fedora.txt b/build/pkgs/jedi/distros/fedora.txt new file mode 100644 index 00000000000..9aefdab6b23 --- /dev/null +++ b/build/pkgs/jedi/distros/fedora.txt @@ -0,0 +1 @@ +python3-jedi diff --git a/build/pkgs/jinja2/distros/fedora.txt b/build/pkgs/jinja2/distros/fedora.txt index f5f3caf99cc..f2db865ab36 100644 --- a/build/pkgs/jinja2/distros/fedora.txt +++ b/build/pkgs/jinja2/distros/fedora.txt @@ -1 +1 @@ -python-jinja2 +python3-jinja2 diff --git a/build/pkgs/jmol/distros/fedora.txt b/build/pkgs/jmol/distros/fedora.txt new file mode 100644 index 00000000000..f07a1f4e035 --- /dev/null +++ b/build/pkgs/jmol/distros/fedora.txt @@ -0,0 +1 @@ +jmol diff --git a/build/pkgs/jsonschema/distros/fedora.txt b/build/pkgs/jsonschema/distros/fedora.txt index 8943c30f9ed..047e6cc5d1d 100644 --- a/build/pkgs/jsonschema/distros/fedora.txt +++ b/build/pkgs/jsonschema/distros/fedora.txt @@ -1 +1 @@ -python-jsonschema +python3-jsonschema diff --git a/build/pkgs/jupymake/distros/fedora.txt b/build/pkgs/jupymake/distros/fedora.txt new file mode 100644 index 00000000000..6077f2bcb60 --- /dev/null +++ b/build/pkgs/jupymake/distros/fedora.txt @@ -0,0 +1 @@ +python3-jupymake diff --git a/build/pkgs/jupyter_client/distros/fedora.txt b/build/pkgs/jupyter_client/distros/fedora.txt new file mode 100644 index 00000000000..0159b2d7b90 --- /dev/null +++ b/build/pkgs/jupyter_client/distros/fedora.txt @@ -0,0 +1 @@ +python3-jupyter-client diff --git a/build/pkgs/jupyter_core/distros/fedora.txt b/build/pkgs/jupyter_core/distros/fedora.txt new file mode 100644 index 00000000000..2f316f2ee07 --- /dev/null +++ b/build/pkgs/jupyter_core/distros/fedora.txt @@ -0,0 +1 @@ +python3-jupyter-core diff --git a/build/pkgs/jupyter_sphinx/distros/fedora.txt b/build/pkgs/jupyter_sphinx/distros/fedora.txt index 95d44e5858f..8eebff3bc90 100644 --- a/build/pkgs/jupyter_sphinx/distros/fedora.txt +++ b/build/pkgs/jupyter_sphinx/distros/fedora.txt @@ -1 +1 @@ -python-jupyter-sphinx +python3-jupyter-sphinx diff --git a/build/pkgs/jupyterlab/distros/fedora.txt b/build/pkgs/jupyterlab/distros/fedora.txt new file mode 100644 index 00000000000..c9356a72837 --- /dev/null +++ b/build/pkgs/jupyterlab/distros/fedora.txt @@ -0,0 +1 @@ +jupyterlab diff --git a/build/pkgs/jupyterlab_pygments/distros/fedora.txt b/build/pkgs/jupyterlab_pygments/distros/fedora.txt new file mode 100644 index 00000000000..979cc3e9c13 --- /dev/null +++ b/build/pkgs/jupyterlab_pygments/distros/fedora.txt @@ -0,0 +1 @@ +python3-jupyterlab_pygments diff --git a/build/pkgs/kissat/distros/fedora.txt b/build/pkgs/kissat/distros/fedora.txt index 18393dcfd49..ecfc46f0815 100644 --- a/build/pkgs/kissat/distros/fedora.txt +++ b/build/pkgs/kissat/distros/fedora.txt @@ -1 +1,2 @@ kissat +kissat-devel diff --git a/build/pkgs/kiwisolver/distros/fedora.txt b/build/pkgs/kiwisolver/distros/fedora.txt new file mode 100644 index 00000000000..aab17cc1272 --- /dev/null +++ b/build/pkgs/kiwisolver/distros/fedora.txt @@ -0,0 +1 @@ +python3-kiwisolver diff --git a/build/pkgs/latte_int/distros/fedora.txt b/build/pkgs/latte_int/distros/fedora.txt new file mode 100644 index 00000000000..2c444214ec4 --- /dev/null +++ b/build/pkgs/latte_int/distros/fedora.txt @@ -0,0 +1 @@ +latte-integrale diff --git a/build/pkgs/libgraphviz/distros/fedora.txt b/build/pkgs/libgraphviz/distros/fedora.txt index 4d95609306f..e14ca4ce8cc 100644 --- a/build/pkgs/libgraphviz/distros/fedora.txt +++ b/build/pkgs/libgraphviz/distros/fedora.txt @@ -1 +1,2 @@ graphviz +graphviz-devel diff --git a/build/pkgs/libnauty/distros/fedora.txt b/build/pkgs/libnauty/distros/fedora.txt index 880ce182eb3..b839ec2a743 100644 --- a/build/pkgs/libnauty/distros/fedora.txt +++ b/build/pkgs/libnauty/distros/fedora.txt @@ -1 +1,2 @@ +libnauty libnauty-devel diff --git a/build/pkgs/libogg/distros/fedora.txt b/build/pkgs/libogg/distros/fedora.txt new file mode 100644 index 00000000000..11a6b96d000 --- /dev/null +++ b/build/pkgs/libogg/distros/fedora.txt @@ -0,0 +1,2 @@ +libogg +libogg-devel diff --git a/build/pkgs/libsemigroups/distros/fedora.txt b/build/pkgs/libsemigroups/distros/fedora.txt new file mode 100644 index 00000000000..45c02ae9d7d --- /dev/null +++ b/build/pkgs/libsemigroups/distros/fedora.txt @@ -0,0 +1,2 @@ +libsemigroups +libsemigroups-devel diff --git a/build/pkgs/libtheora/distros/fedora.txt b/build/pkgs/libtheora/distros/fedora.txt new file mode 100644 index 00000000000..8043f5eea67 --- /dev/null +++ b/build/pkgs/libtheora/distros/fedora.txt @@ -0,0 +1,2 @@ +libtheora +libtheora-devel diff --git a/build/pkgs/linbox/distros/fedora.txt b/build/pkgs/linbox/distros/fedora.txt index e0fb5eb3ccc..93cb9987a09 100644 --- a/build/pkgs/linbox/distros/fedora.txt +++ b/build/pkgs/linbox/distros/fedora.txt @@ -1 +1,2 @@ +linbox linbox-devel diff --git a/build/pkgs/lrcalc_python/distros/fedora.txt b/build/pkgs/lrcalc_python/distros/fedora.txt new file mode 100644 index 00000000000..6d0a5315ae0 --- /dev/null +++ b/build/pkgs/lrcalc_python/distros/fedora.txt @@ -0,0 +1 @@ +python3-lrcalc diff --git a/build/pkgs/lrslib/distros/fedora.txt b/build/pkgs/lrslib/distros/fedora.txt index c762c018aa3..1b3df082e57 100644 --- a/build/pkgs/lrslib/distros/fedora.txt +++ b/build/pkgs/lrslib/distros/fedora.txt @@ -1 +1,2 @@ lrslib +lrslib-devel diff --git a/build/pkgs/markupsafe/distros/fedora.txt b/build/pkgs/markupsafe/distros/fedora.txt new file mode 100644 index 00000000000..426b8a1a4c1 --- /dev/null +++ b/build/pkgs/markupsafe/distros/fedora.txt @@ -0,0 +1 @@ +python3-markupsafe diff --git a/build/pkgs/mathjax/distros/fedora.txt b/build/pkgs/mathjax/distros/fedora.txt new file mode 100644 index 00000000000..9b7fbe7fff9 --- /dev/null +++ b/build/pkgs/mathjax/distros/fedora.txt @@ -0,0 +1 @@ +mathjax3 diff --git a/build/pkgs/matplotlib/distros/fedora.txt b/build/pkgs/matplotlib/distros/fedora.txt index f6d856e585c..13743297213 100644 --- a/build/pkgs/matplotlib/distros/fedora.txt +++ b/build/pkgs/matplotlib/distros/fedora.txt @@ -1 +1 @@ -python-matplotlib +python3-matplotlib diff --git a/build/pkgs/matplotlib_inline/distros/fedora.txt b/build/pkgs/matplotlib_inline/distros/fedora.txt new file mode 100644 index 00000000000..2e46aafab96 --- /dev/null +++ b/build/pkgs/matplotlib_inline/distros/fedora.txt @@ -0,0 +1 @@ +python3-matplotlib-inline diff --git a/build/pkgs/mcqd/distros/fedora.txt b/build/pkgs/mcqd/distros/fedora.txt new file mode 100644 index 00000000000..d851f52f6a0 --- /dev/null +++ b/build/pkgs/mcqd/distros/fedora.txt @@ -0,0 +1,2 @@ +mcqd +mcqd-devel diff --git a/build/pkgs/meson_python/distros/fedora.txt b/build/pkgs/meson_python/distros/fedora.txt index 17b4e0c04c5..93dae9570a4 100644 --- a/build/pkgs/meson_python/distros/fedora.txt +++ b/build/pkgs/meson_python/distros/fedora.txt @@ -1 +1 @@ -python-meson-python +python3-meson-python diff --git a/build/pkgs/mistune/distros/fedora.txt b/build/pkgs/mistune/distros/fedora.txt new file mode 100644 index 00000000000..587df34ac38 --- /dev/null +++ b/build/pkgs/mistune/distros/fedora.txt @@ -0,0 +1 @@ +python3-mistune diff --git a/build/pkgs/mpmath/distros/fedora.txt b/build/pkgs/mpmath/distros/fedora.txt index a7dc8d568f3..fbc82a97e07 100644 --- a/build/pkgs/mpmath/distros/fedora.txt +++ b/build/pkgs/mpmath/distros/fedora.txt @@ -1 +1 @@ -python-mpmath +python3-mpmath diff --git a/build/pkgs/nbclient/distros/fedora.txt b/build/pkgs/nbclient/distros/fedora.txt new file mode 100644 index 00000000000..17730f59437 --- /dev/null +++ b/build/pkgs/nbclient/distros/fedora.txt @@ -0,0 +1 @@ +python3-nbclient diff --git a/build/pkgs/nbconvert/distros/fedora.txt b/build/pkgs/nbconvert/distros/fedora.txt new file mode 100644 index 00000000000..e1f71656c82 --- /dev/null +++ b/build/pkgs/nbconvert/distros/fedora.txt @@ -0,0 +1 @@ +python3-nbconvert diff --git a/build/pkgs/nbformat/distros/fedora.txt b/build/pkgs/nbformat/distros/fedora.txt new file mode 100644 index 00000000000..7521f00141c --- /dev/null +++ b/build/pkgs/nbformat/distros/fedora.txt @@ -0,0 +1 @@ +python3-nbformat diff --git a/build/pkgs/nest_asyncio/distros/fedora.txt b/build/pkgs/nest_asyncio/distros/fedora.txt new file mode 100644 index 00000000000..9b465b8bab8 --- /dev/null +++ b/build/pkgs/nest_asyncio/distros/fedora.txt @@ -0,0 +1 @@ +python3-nest-asyncio diff --git a/build/pkgs/networkx/distros/fedora.txt b/build/pkgs/networkx/distros/fedora.txt index 293f943529a..67790667af2 100644 --- a/build/pkgs/networkx/distros/fedora.txt +++ b/build/pkgs/networkx/distros/fedora.txt @@ -1 +1 @@ -python-networkx +python3-networkx diff --git a/build/pkgs/nibabel/distros/fedora.txt b/build/pkgs/nibabel/distros/fedora.txt new file mode 100644 index 00000000000..19df029d93f --- /dev/null +++ b/build/pkgs/nibabel/distros/fedora.txt @@ -0,0 +1 @@ +python3-nibabel diff --git a/build/pkgs/normaliz/distros/fedora.txt b/build/pkgs/normaliz/distros/fedora.txt index b48a8dfa158..15c4e2a32b2 100644 --- a/build/pkgs/normaliz/distros/fedora.txt +++ b/build/pkgs/normaliz/distros/fedora.txt @@ -1 +1,2 @@ +libnormaliz libnormaliz-devel diff --git a/build/pkgs/notebook/distros/fedora.txt b/build/pkgs/notebook/distros/fedora.txt new file mode 100644 index 00000000000..70e09d9511a --- /dev/null +++ b/build/pkgs/notebook/distros/fedora.txt @@ -0,0 +1 @@ +python3-notebook diff --git a/build/pkgs/numpy/distros/fedora.txt b/build/pkgs/numpy/distros/fedora.txt index c8722b9f663..79d5c5a1429 100644 --- a/build/pkgs/numpy/distros/fedora.txt +++ b/build/pkgs/numpy/distros/fedora.txt @@ -1 +1 @@ -python-numpy +python3-numpy diff --git a/build/pkgs/onetbb/distros/fedora.txt b/build/pkgs/onetbb/distros/fedora.txt index 21e1846951c..118cbf13265 100644 --- a/build/pkgs/onetbb/distros/fedora.txt +++ b/build/pkgs/onetbb/distros/fedora.txt @@ -1 +1,2 @@ +tbb tbb-devel diff --git a/build/pkgs/packaging/distros/fedora.txt b/build/pkgs/packaging/distros/fedora.txt index 02ad855da9a..8f1c0ffc29f 100644 --- a/build/pkgs/packaging/distros/fedora.txt +++ b/build/pkgs/packaging/distros/fedora.txt @@ -1 +1 @@ -python-packaging +python3-packaging diff --git a/build/pkgs/palettable/distros/fedora.txt b/build/pkgs/palettable/distros/fedora.txt new file mode 100644 index 00000000000..b40b0270c2c --- /dev/null +++ b/build/pkgs/palettable/distros/fedora.txt @@ -0,0 +1 @@ +python3-palettable diff --git a/build/pkgs/pandocfilters/distros/fedora.txt b/build/pkgs/pandocfilters/distros/fedora.txt index e7a86d0373c..d0d4c24e15e 100644 --- a/build/pkgs/pandocfilters/distros/fedora.txt +++ b/build/pkgs/pandocfilters/distros/fedora.txt @@ -1 +1 @@ -python-pandocfilters +python3-pandocfilters diff --git a/build/pkgs/pari_jupyter/distros/fedora.txt b/build/pkgs/pari_jupyter/distros/fedora.txt new file mode 100644 index 00000000000..3d44bea1b74 --- /dev/null +++ b/build/pkgs/pari_jupyter/distros/fedora.txt @@ -0,0 +1 @@ +python3-pari-jupyter diff --git a/build/pkgs/parso/distros/fedora.txt b/build/pkgs/parso/distros/fedora.txt new file mode 100644 index 00000000000..72fc6162fb9 --- /dev/null +++ b/build/pkgs/parso/distros/fedora.txt @@ -0,0 +1 @@ +python3-parso diff --git a/build/pkgs/pathspec/distros/fedora.txt b/build/pkgs/pathspec/distros/fedora.txt new file mode 100644 index 00000000000..e519f68e341 --- /dev/null +++ b/build/pkgs/pathspec/distros/fedora.txt @@ -0,0 +1 @@ +python3-pathspec diff --git a/build/pkgs/perl_cpan_polymake_prereq/distros/fedora.txt b/build/pkgs/perl_cpan_polymake_prereq/distros/fedora.txt index da97cd97866..ed4b3c9338a 100644 --- a/build/pkgs/perl_cpan_polymake_prereq/distros/fedora.txt +++ b/build/pkgs/perl_cpan_polymake_prereq/distros/fedora.txt @@ -6,3 +6,4 @@ perl-TermReadKey perl-XML-Writer perl-XML-LibXML perl-XML-LibXSLT +perl-SVG diff --git a/build/pkgs/pexpect/distros/fedora.txt b/build/pkgs/pexpect/distros/fedora.txt index 74d08141569..8d745ee4a07 100644 --- a/build/pkgs/pexpect/distros/fedora.txt +++ b/build/pkgs/pexpect/distros/fedora.txt @@ -1 +1 @@ -python-pexpect +python3-pexpect diff --git a/build/pkgs/pickleshare/distros/fedora.txt b/build/pkgs/pickleshare/distros/fedora.txt index 6d991a27d41..a00907d167b 100644 --- a/build/pkgs/pickleshare/distros/fedora.txt +++ b/build/pkgs/pickleshare/distros/fedora.txt @@ -1 +1 @@ -python-pickleshare +python3-pickleshare diff --git a/build/pkgs/pillow/distros/fedora.txt b/build/pkgs/pillow/distros/fedora.txt index 86dbb1d13b8..3319fcd7e0f 100644 --- a/build/pkgs/pillow/distros/fedora.txt +++ b/build/pkgs/pillow/distros/fedora.txt @@ -1 +1 @@ -python-pillow +python3-pillow diff --git a/build/pkgs/pint/distros/fedora.txt b/build/pkgs/pint/distros/fedora.txt new file mode 100644 index 00000000000..b0f2af45706 --- /dev/null +++ b/build/pkgs/pint/distros/fedora.txt @@ -0,0 +1 @@ +python3-pint diff --git a/build/pkgs/pip/distros/fedora.txt b/build/pkgs/pip/distros/fedora.txt index 311c1b821ca..39bd9fc5097 100644 --- a/build/pkgs/pip/distros/fedora.txt +++ b/build/pkgs/pip/distros/fedora.txt @@ -1 +1 @@ -python-pip +python3-pip diff --git a/build/pkgs/pkgconfig/distros/fedora.txt b/build/pkgs/pkgconfig/distros/fedora.txt index 38a18b3565f..38e5106dd74 100644 --- a/build/pkgs/pkgconfig/distros/fedora.txt +++ b/build/pkgs/pkgconfig/distros/fedora.txt @@ -1 +1 @@ -python-pkgconfig +python3-pkgconfig diff --git a/build/pkgs/plantri/distros/fedora.txt b/build/pkgs/plantri/distros/fedora.txt new file mode 100644 index 00000000000..290ff321e46 --- /dev/null +++ b/build/pkgs/plantri/distros/fedora.txt @@ -0,0 +1 @@ +plantri diff --git a/build/pkgs/platformdirs/distros/fedora.txt b/build/pkgs/platformdirs/distros/fedora.txt new file mode 100644 index 00000000000..d65e921f05e --- /dev/null +++ b/build/pkgs/platformdirs/distros/fedora.txt @@ -0,0 +1 @@ +python3-platformdirs diff --git a/build/pkgs/pluggy/distros/fedora.txt b/build/pkgs/pluggy/distros/fedora.txt index c869e54c551..43a3acf0462 100644 --- a/build/pkgs/pluggy/distros/fedora.txt +++ b/build/pkgs/pluggy/distros/fedora.txt @@ -1 +1 @@ -python-pluggy +python3-pluggy diff --git a/build/pkgs/pplpy/distros/fedora.txt b/build/pkgs/pplpy/distros/fedora.txt index 579bdb042f6..f39eaff76ae 100644 --- a/build/pkgs/pplpy/distros/fedora.txt +++ b/build/pkgs/pplpy/distros/fedora.txt @@ -1 +1 @@ -python-pplpy +python3-pplpy diff --git a/build/pkgs/primecountpy/distros/fedora.txt b/build/pkgs/primecountpy/distros/fedora.txt new file mode 100644 index 00000000000..792a40abfc5 --- /dev/null +++ b/build/pkgs/primecountpy/distros/fedora.txt @@ -0,0 +1 @@ +python3-primecountpy diff --git a/build/pkgs/prometheus_client/distros/fedora.txt b/build/pkgs/prometheus_client/distros/fedora.txt new file mode 100644 index 00000000000..4d7723ec37e --- /dev/null +++ b/build/pkgs/prometheus_client/distros/fedora.txt @@ -0,0 +1 @@ +python3-prometheus_client diff --git a/build/pkgs/prompt_toolkit/distros/fedora.txt b/build/pkgs/prompt_toolkit/distros/fedora.txt index 967f8570d4f..c6d59003df0 100644 --- a/build/pkgs/prompt_toolkit/distros/fedora.txt +++ b/build/pkgs/prompt_toolkit/distros/fedora.txt @@ -1 +1 @@ -python-prompt-toolkit +python3-prompt-toolkit diff --git a/build/pkgs/ptyprocess/distros/fedora.txt b/build/pkgs/ptyprocess/distros/fedora.txt index 911a22468fc..ad4f6db1ca7 100644 --- a/build/pkgs/ptyprocess/distros/fedora.txt +++ b/build/pkgs/ptyprocess/distros/fedora.txt @@ -1 +1 @@ -python-ptyprocess +python3-ptyprocess diff --git a/build/pkgs/pure_eval/distros/fedora.txt b/build/pkgs/pure_eval/distros/fedora.txt new file mode 100644 index 00000000000..0feeff64011 --- /dev/null +++ b/build/pkgs/pure_eval/distros/fedora.txt @@ -0,0 +1 @@ +python3-pure-eval diff --git a/build/pkgs/py/distros/fedora.txt b/build/pkgs/py/distros/fedora.txt index b348d395fbd..81fefe60903 100644 --- a/build/pkgs/py/distros/fedora.txt +++ b/build/pkgs/py/distros/fedora.txt @@ -1 +1 @@ -python-py +python3-py diff --git a/build/pkgs/pybind11/distros/fedora.txt b/build/pkgs/pybind11/distros/fedora.txt new file mode 100644 index 00000000000..ac2d3cb471d --- /dev/null +++ b/build/pkgs/pybind11/distros/fedora.txt @@ -0,0 +1 @@ +python3-pybind11 diff --git a/build/pkgs/pybtex/distros/fedora.txt b/build/pkgs/pybtex/distros/fedora.txt new file mode 100644 index 00000000000..bdd39a48fde --- /dev/null +++ b/build/pkgs/pybtex/distros/fedora.txt @@ -0,0 +1 @@ +python3-pybtex diff --git a/build/pkgs/pycosat/distros/fedora.txt b/build/pkgs/pycosat/distros/fedora.txt index dab3122ef4c..c9ba620944f 100644 --- a/build/pkgs/pycosat/distros/fedora.txt +++ b/build/pkgs/pycosat/distros/fedora.txt @@ -1 +1 @@ -python-pycosat +python3-pycosat diff --git a/build/pkgs/pycparser/distros/fedora.txt b/build/pkgs/pycparser/distros/fedora.txt new file mode 100644 index 00000000000..0ba4f8b19f5 --- /dev/null +++ b/build/pkgs/pycparser/distros/fedora.txt @@ -0,0 +1 @@ +python3-pycparser diff --git a/build/pkgs/pycryptosat/distros/fedora.txt b/build/pkgs/pycryptosat/distros/fedora.txt new file mode 100644 index 00000000000..eb2adec7e72 --- /dev/null +++ b/build/pkgs/pycryptosat/distros/fedora.txt @@ -0,0 +1 @@ +python3-pycryptosat diff --git a/build/pkgs/pygments/distros/fedora.txt b/build/pkgs/pygments/distros/fedora.txt index f3e72a89c38..3ab37929b2c 100644 --- a/build/pkgs/pygments/distros/fedora.txt +++ b/build/pkgs/pygments/distros/fedora.txt @@ -1 +1 @@ -python-pygments +python3-pygments diff --git a/build/pkgs/pygraphviz/distros/fedora.txt b/build/pkgs/pygraphviz/distros/fedora.txt new file mode 100644 index 00000000000..0157eae2581 --- /dev/null +++ b/build/pkgs/pygraphviz/distros/fedora.txt @@ -0,0 +1 @@ +python3-pygraphviz diff --git a/build/pkgs/pyparsing/distros/fedora.txt b/build/pkgs/pyparsing/distros/fedora.txt new file mode 100644 index 00000000000..492a7ce0a69 --- /dev/null +++ b/build/pkgs/pyparsing/distros/fedora.txt @@ -0,0 +1 @@ +python3-pyparsing diff --git a/build/pkgs/pyproject_metadata/distros/fedora.txt b/build/pkgs/pyproject_metadata/distros/fedora.txt new file mode 100644 index 00000000000..5180a07a0cc --- /dev/null +++ b/build/pkgs/pyproject_metadata/distros/fedora.txt @@ -0,0 +1 @@ +python3-pyproject-metadata diff --git a/build/pkgs/pyrsistent/distros/fedora.txt b/build/pkgs/pyrsistent/distros/fedora.txt new file mode 100644 index 00000000000..77485df49f0 --- /dev/null +++ b/build/pkgs/pyrsistent/distros/fedora.txt @@ -0,0 +1 @@ +python3-pyrsistent diff --git a/build/pkgs/pysingular/distros/fedora.txt b/build/pkgs/pysingular/distros/fedora.txt new file mode 100644 index 00000000000..6466894c1c7 --- /dev/null +++ b/build/pkgs/pysingular/distros/fedora.txt @@ -0,0 +1 @@ +python3-pysingular diff --git a/build/pkgs/pytest/distros/fedora.txt b/build/pkgs/pytest/distros/fedora.txt new file mode 100644 index 00000000000..6665fd281bb --- /dev/null +++ b/build/pkgs/pytest/distros/fedora.txt @@ -0,0 +1 @@ +python3-pytest diff --git a/build/pkgs/pytest_xdist/distros/fedora.txt b/build/pkgs/pytest_xdist/distros/fedora.txt new file mode 100644 index 00000000000..e6e6abd74ed --- /dev/null +++ b/build/pkgs/pytest_xdist/distros/fedora.txt @@ -0,0 +1 @@ +python3-pytest-xdist diff --git a/build/pkgs/python_igraph/distros/fedora.txt b/build/pkgs/python_igraph/distros/fedora.txt index 03f8142066f..6b5f452ff56 100644 --- a/build/pkgs/python_igraph/distros/fedora.txt +++ b/build/pkgs/python_igraph/distros/fedora.txt @@ -1 +1,2 @@ python-igraph +python3-igraph-devel diff --git a/build/pkgs/pythran/distros/fedora.txt b/build/pkgs/pythran/distros/fedora.txt new file mode 100644 index 00000000000..86d056b339f --- /dev/null +++ b/build/pkgs/pythran/distros/fedora.txt @@ -0,0 +1 @@ +pythran diff --git a/build/pkgs/pytz/distros/fedora.txt b/build/pkgs/pytz/distros/fedora.txt index 2cccc9e61ec..1b20e1dbb77 100644 --- a/build/pkgs/pytz/distros/fedora.txt +++ b/build/pkgs/pytz/distros/fedora.txt @@ -1 +1 @@ -python-pytz +python3-pytz diff --git a/build/pkgs/pytz_deprecation_shim/distros/fedora.txt b/build/pkgs/pytz_deprecation_shim/distros/fedora.txt new file mode 100644 index 00000000000..f6cc43e10db --- /dev/null +++ b/build/pkgs/pytz_deprecation_shim/distros/fedora.txt @@ -0,0 +1 @@ +python3-pytz-deprecation-shim diff --git a/build/pkgs/pyzmq/distros/fedora.txt b/build/pkgs/pyzmq/distros/fedora.txt index 23f64d1f1a3..265a272130e 100644 --- a/build/pkgs/pyzmq/distros/fedora.txt +++ b/build/pkgs/pyzmq/distros/fedora.txt @@ -1 +1 @@ -python-pyzmq +python3-pyzmq diff --git a/build/pkgs/requests/distros/fedora.txt b/build/pkgs/requests/distros/fedora.txt index 93a7bc19b60..43147b2be74 100644 --- a/build/pkgs/requests/distros/fedora.txt +++ b/build/pkgs/requests/distros/fedora.txt @@ -1 +1 @@ -python-requests +python3-requests diff --git a/build/pkgs/scip/distros/fedora.txt b/build/pkgs/scip/distros/fedora.txt new file mode 100644 index 00000000000..3065c152171 --- /dev/null +++ b/build/pkgs/scip/distros/fedora.txt @@ -0,0 +1 @@ +scip diff --git a/build/pkgs/scipy/distros/fedora.txt b/build/pkgs/scipy/distros/fedora.txt index 7ff2882c1bf..12b366666d6 100644 --- a/build/pkgs/scipy/distros/fedora.txt +++ b/build/pkgs/scipy/distros/fedora.txt @@ -1 +1 @@ -python-scipy +python3-scipy diff --git a/build/pkgs/send2trash/distros/fedora.txt b/build/pkgs/send2trash/distros/fedora.txt new file mode 100644 index 00000000000..2f9abb6f584 --- /dev/null +++ b/build/pkgs/send2trash/distros/fedora.txt @@ -0,0 +1 @@ +python3-send2trash diff --git a/build/pkgs/setuptools_scm/distros/fedora.txt b/build/pkgs/setuptools_scm/distros/fedora.txt index 720fd2897be..2aa5ca12cba 100644 --- a/build/pkgs/setuptools_scm/distros/fedora.txt +++ b/build/pkgs/setuptools_scm/distros/fedora.txt @@ -1 +1 @@ -python-setuptools_scm +python3-setuptools_scm diff --git a/build/pkgs/singular_jupyter/distros/fedora.txt b/build/pkgs/singular_jupyter/distros/fedora.txt new file mode 100644 index 00000000000..b4632d4ad59 --- /dev/null +++ b/build/pkgs/singular_jupyter/distros/fedora.txt @@ -0,0 +1 @@ +python3-jupyter-kernel-singular diff --git a/build/pkgs/sirocco/distros/fedora.txt b/build/pkgs/sirocco/distros/fedora.txt index f2baa26096c..4d66f8f3619 100644 --- a/build/pkgs/sirocco/distros/fedora.txt +++ b/build/pkgs/sirocco/distros/fedora.txt @@ -1 +1,2 @@ sirocco +sirocco-devel diff --git a/build/pkgs/six/distros/fedora.txt b/build/pkgs/six/distros/fedora.txt index 787c5308ea4..68ff8595d0b 100644 --- a/build/pkgs/six/distros/fedora.txt +++ b/build/pkgs/six/distros/fedora.txt @@ -1 +1 @@ -python-six +python3-six diff --git a/build/pkgs/soplex/distros/fedora.txt b/build/pkgs/soplex/distros/fedora.txt new file mode 100644 index 00000000000..3fcd744bc92 --- /dev/null +++ b/build/pkgs/soplex/distros/fedora.txt @@ -0,0 +1 @@ +soplex diff --git a/build/pkgs/soupsieve/distros/fedora.txt b/build/pkgs/soupsieve/distros/fedora.txt new file mode 100644 index 00000000000..338c275caa9 --- /dev/null +++ b/build/pkgs/soupsieve/distros/fedora.txt @@ -0,0 +1 @@ +python3-soupsieve diff --git a/build/pkgs/sphinx/distros/fedora.txt b/build/pkgs/sphinx/distros/fedora.txt index db9f745da4c..7b28855c51b 100644 --- a/build/pkgs/sphinx/distros/fedora.txt +++ b/build/pkgs/sphinx/distros/fedora.txt @@ -1 +1 @@ -python-sphinx +python3-sphinx diff --git a/build/pkgs/sphinx_basic_ng/distros/fedora.txt b/build/pkgs/sphinx_basic_ng/distros/fedora.txt index de43e3bfd58..71ac46b68ce 100644 --- a/build/pkgs/sphinx_basic_ng/distros/fedora.txt +++ b/build/pkgs/sphinx_basic_ng/distros/fedora.txt @@ -1 +1 @@ -python-sphinx-basic-ng +python3-sphinx-basic-ng diff --git a/build/pkgs/sphinx_copybutton/distros/fedora.txt b/build/pkgs/sphinx_copybutton/distros/fedora.txt index 2a99b129e49..576663b4a9d 100644 --- a/build/pkgs/sphinx_copybutton/distros/fedora.txt +++ b/build/pkgs/sphinx_copybutton/distros/fedora.txt @@ -1 +1 @@ -python-sphinx-copybutton +python3-sphinx-copybutton diff --git a/build/pkgs/sphinxcontrib_applehelp/distros/fedora.txt b/build/pkgs/sphinxcontrib_applehelp/distros/fedora.txt deleted file mode 100644 index 3754baa21f5..00000000000 --- a/build/pkgs/sphinxcontrib_applehelp/distros/fedora.txt +++ /dev/null @@ -1 +0,0 @@ -python-sphinxcontrib-applehelp diff --git a/build/pkgs/sphinxcontrib_devhelp/distros/fedora.txt b/build/pkgs/sphinxcontrib_devhelp/distros/fedora.txt index 0b1b3e44a6b..14357dcb071 100644 --- a/build/pkgs/sphinxcontrib_devhelp/distros/fedora.txt +++ b/build/pkgs/sphinxcontrib_devhelp/distros/fedora.txt @@ -1 +1 @@ -python-sphinxcontrib-devhelp +python3-sphinxcontrib-devhelp diff --git a/build/pkgs/sphinxcontrib_htmlhelp/distros/fedora.txt b/build/pkgs/sphinxcontrib_htmlhelp/distros/fedora.txt index 81390fd522f..3362a84ccc8 100644 --- a/build/pkgs/sphinxcontrib_htmlhelp/distros/fedora.txt +++ b/build/pkgs/sphinxcontrib_htmlhelp/distros/fedora.txt @@ -1 +1 @@ -python-sphinxcontrib-htmlhelp +python3-sphinxcontrib-htmlhelp diff --git a/build/pkgs/sphinxcontrib_jsmath/distros/fedora.txt b/build/pkgs/sphinxcontrib_jsmath/distros/fedora.txt deleted file mode 100644 index 2b4927832ac..00000000000 --- a/build/pkgs/sphinxcontrib_jsmath/distros/fedora.txt +++ /dev/null @@ -1 +0,0 @@ -python-sphinxcontrib-jsmath diff --git a/build/pkgs/sphinxcontrib_qthelp/distros/fedora.txt b/build/pkgs/sphinxcontrib_qthelp/distros/fedora.txt index 2c11924a5df..9e8fef277fc 100644 --- a/build/pkgs/sphinxcontrib_qthelp/distros/fedora.txt +++ b/build/pkgs/sphinxcontrib_qthelp/distros/fedora.txt @@ -1 +1 @@ -python-sphinxcontrib-qthelp +python3-sphinxcontrib-qthelp diff --git a/build/pkgs/sphinxcontrib_serializinghtml/distros/fedora.txt b/build/pkgs/sphinxcontrib_serializinghtml/distros/fedora.txt index 46d22be403f..1a8ea8424a7 100644 --- a/build/pkgs/sphinxcontrib_serializinghtml/distros/fedora.txt +++ b/build/pkgs/sphinxcontrib_serializinghtml/distros/fedora.txt @@ -1 +1 @@ -python-sphinxcontrib-serializinghtml +python3-sphinxcontrib-serializinghtml diff --git a/build/pkgs/sphinxcontrib_websupport/distros/fedora.txt b/build/pkgs/sphinxcontrib_websupport/distros/fedora.txt index a9a5a1a1727..2c8e8e8d34d 100644 --- a/build/pkgs/sphinxcontrib_websupport/distros/fedora.txt +++ b/build/pkgs/sphinxcontrib_websupport/distros/fedora.txt @@ -1 +1 @@ -python-sphinxcontrib-websupport +python3-sphinxcontrib-websupport diff --git a/build/pkgs/sqlalchemy/distros/fedora.txt b/build/pkgs/sqlalchemy/distros/fedora.txt new file mode 100644 index 00000000000..943697378a7 --- /dev/null +++ b/build/pkgs/sqlalchemy/distros/fedora.txt @@ -0,0 +1 @@ +python3-sqlalchemy diff --git a/build/pkgs/stack_data/distros/fedora.txt b/build/pkgs/stack_data/distros/fedora.txt new file mode 100644 index 00000000000..b5be058ebaa --- /dev/null +++ b/build/pkgs/stack_data/distros/fedora.txt @@ -0,0 +1 @@ +python3-stack-data diff --git a/build/pkgs/sympy/distros/fedora.txt b/build/pkgs/sympy/distros/fedora.txt index 126c88afd85..db423c87ba7 100644 --- a/build/pkgs/sympy/distros/fedora.txt +++ b/build/pkgs/sympy/distros/fedora.txt @@ -1 +1 @@ -python-sympy +python3-sympy diff --git a/build/pkgs/tachyon/distros/fedora.txt b/build/pkgs/tachyon/distros/fedora.txt index 035020a8d5b..9c9043ce249 100644 --- a/build/pkgs/tachyon/distros/fedora.txt +++ b/build/pkgs/tachyon/distros/fedora.txt @@ -1,2 +1,3 @@ +# deprecated in Fedora 40 tachyon tachyon-devel diff --git a/build/pkgs/tdlib/distros/fedora.txt b/build/pkgs/tdlib/distros/fedora.txt new file mode 100644 index 00000000000..f795385d55d --- /dev/null +++ b/build/pkgs/tdlib/distros/fedora.txt @@ -0,0 +1,2 @@ +python3-tdlib +python3-tdlib-devel diff --git a/build/pkgs/texttable/distros/fedora.txt b/build/pkgs/texttable/distros/fedora.txt index 8d1ccec8c7d..8f8e7e29d7a 100644 --- a/build/pkgs/texttable/distros/fedora.txt +++ b/build/pkgs/texttable/distros/fedora.txt @@ -1 +1 @@ -python-texttable +python3-texttable diff --git a/build/pkgs/tinycss2/distros/fedora.txt b/build/pkgs/tinycss2/distros/fedora.txt index cb5becfe9eb..a2c2cb2f4ab 100644 --- a/build/pkgs/tinycss2/distros/fedora.txt +++ b/build/pkgs/tinycss2/distros/fedora.txt @@ -1 +1 @@ -python-tinycss2 +python3-tinycss2 diff --git a/build/pkgs/tomli/distros/fedora.txt b/build/pkgs/tomli/distros/fedora.txt new file mode 100644 index 00000000000..cfd9f618b76 --- /dev/null +++ b/build/pkgs/tomli/distros/fedora.txt @@ -0,0 +1 @@ +python3-tomli diff --git a/build/pkgs/tornado/distros/fedora.txt b/build/pkgs/tornado/distros/fedora.txt new file mode 100644 index 00000000000..426685be95b --- /dev/null +++ b/build/pkgs/tornado/distros/fedora.txt @@ -0,0 +1 @@ +python3-tornado diff --git a/build/pkgs/trove_classifiers/distros/fedora.txt b/build/pkgs/trove_classifiers/distros/fedora.txt index faa3f51e677..01b98a590f0 100644 --- a/build/pkgs/trove_classifiers/distros/fedora.txt +++ b/build/pkgs/trove_classifiers/distros/fedora.txt @@ -1 +1 @@ -python-trove-classifiers +python3-trove-classifiers diff --git a/build/pkgs/typing_extensions/distros/fedora.txt b/build/pkgs/typing_extensions/distros/fedora.txt index 8c13a4539ac..424ebf1a645 100644 --- a/build/pkgs/typing_extensions/distros/fedora.txt +++ b/build/pkgs/typing_extensions/distros/fedora.txt @@ -1 +1 @@ -python-typing-extensions +python3-typing-extensions diff --git a/build/pkgs/tzdata/distros/fedora.txt b/build/pkgs/tzdata/distros/fedora.txt new file mode 100644 index 00000000000..0883ff0705b --- /dev/null +++ b/build/pkgs/tzdata/distros/fedora.txt @@ -0,0 +1 @@ +tzdata diff --git a/build/pkgs/tzlocal/distros/fedora.txt b/build/pkgs/tzlocal/distros/fedora.txt index 1de39af60b2..95d2d705c05 100644 --- a/build/pkgs/tzlocal/distros/fedora.txt +++ b/build/pkgs/tzlocal/distros/fedora.txt @@ -1 +1 @@ -python-tzlocal +python3-tzlocal diff --git a/build/pkgs/urllib3/distros/fedora.txt b/build/pkgs/urllib3/distros/fedora.txt index af6e58664fb..918569f9677 100644 --- a/build/pkgs/urllib3/distros/fedora.txt +++ b/build/pkgs/urllib3/distros/fedora.txt @@ -1 +1 @@ -python-urllib3 +python3-urllib3 diff --git a/build/pkgs/valgrind/distros/fedora.txt b/build/pkgs/valgrind/distros/fedora.txt new file mode 100644 index 00000000000..19e18cdba88 --- /dev/null +++ b/build/pkgs/valgrind/distros/fedora.txt @@ -0,0 +1,2 @@ +valgrind +vagrind-devel diff --git a/build/pkgs/virtualenv/distros/fedora.txt b/build/pkgs/virtualenv/distros/fedora.txt new file mode 100644 index 00000000000..030879e0d89 --- /dev/null +++ b/build/pkgs/virtualenv/distros/fedora.txt @@ -0,0 +1 @@ +python3-virtualenv diff --git a/build/pkgs/wcwidth/distros/fedora.txt b/build/pkgs/wcwidth/distros/fedora.txt new file mode 100644 index 00000000000..2974220c878 --- /dev/null +++ b/build/pkgs/wcwidth/distros/fedora.txt @@ -0,0 +1 @@ +python3-wcwidth diff --git a/build/pkgs/webencodings/distros/fedora.txt b/build/pkgs/webencodings/distros/fedora.txt index 12ddba901a4..ac30c2f3307 100644 --- a/build/pkgs/webencodings/distros/fedora.txt +++ b/build/pkgs/webencodings/distros/fedora.txt @@ -1 +1 @@ -python-webencodings +python3-webencodings diff --git a/build/pkgs/wheel/distros/fedora.txt b/build/pkgs/wheel/distros/fedora.txt index ae4cbb9f52f..3c066725a1d 100644 --- a/build/pkgs/wheel/distros/fedora.txt +++ b/build/pkgs/wheel/distros/fedora.txt @@ -1 +1 @@ -python-wheel +python3-wheel diff --git a/build/pkgs/widgetsnbextension/distros/fedora.txt b/build/pkgs/widgetsnbextension/distros/fedora.txt index 3483570a543..4faf6e10349 100644 --- a/build/pkgs/widgetsnbextension/distros/fedora.txt +++ b/build/pkgs/widgetsnbextension/distros/fedora.txt @@ -1 +1 @@ -python-widgetsnbextension +python3-widgetsnbextension diff --git a/build/pkgs/xindy/distros/fedora.txt b/build/pkgs/xindy/distros/fedora.txt new file mode 100644 index 00000000000..9b69095e628 --- /dev/null +++ b/build/pkgs/xindy/distros/fedora.txt @@ -0,0 +1 @@ +texlive-xindy diff --git a/build/pkgs/zipp/distros/fedora.txt b/build/pkgs/zipp/distros/fedora.txt new file mode 100644 index 00000000000..029ff9c75da --- /dev/null +++ b/build/pkgs/zipp/distros/fedora.txt @@ -0,0 +1 @@ +python3-zipp diff --git a/src/bin/sage-preparse b/src/bin/sage-preparse index 6392909ce1c..3422d236bf2 100755 --- a/src/bin/sage-preparse +++ b/src/bin/sage-preparse @@ -74,7 +74,7 @@ def do_preparse(f, files_before=[]): - ``f`` -- string: the name of a file - ``files_before`` -- list of strings of previous filenames loaded (to avoid circular loops) - OUTPUT: None (writes a file with extension .sage.py to disk). + OUTPUT: none (writes a file with extension .sage.py to disk) """ if f in files_so_far: return diff --git a/src/doc/common/static/jupyter-sphinx-furo.js b/src/doc/common/static/jupyter-sphinx-furo.js index b63de354db8..ad06a84d5a2 100644 --- a/src/doc/common/static/jupyter-sphinx-furo.js +++ b/src/doc/common/static/jupyter-sphinx-furo.js @@ -109,12 +109,12 @@ function changeVersion() { if (selected_url) { if (window.location.protocol == 'file:') { let pathname = window.location.pathname; - let cutoff_point = pathname.indexOf('doc/sage'); + let cutoff_point = pathname.indexOf('/html'); if (cutoff_point !== -1) { - pathname = pathname.substring(cutoff_point + 8); + pathname = pathname.substring(cutoff_point); window.location.href = selected_url + pathname; } else { - window.location.href = selected_url + 'html/en/index.html'; + window.location.href = selected_url + '/index.html'; } } else { window.location.href = selected_url + window.location.pathname; diff --git a/src/doc/en/installation/conda.rst b/src/doc/en/installation/conda.rst index 49495d60ebf..566fea4ff1a 100644 --- a/src/doc/en/installation/conda.rst +++ b/src/doc/en/installation/conda.rst @@ -27,8 +27,8 @@ follows. In a terminal, * Change channel priority to strict: ``conda config --set channel_priority strict`` -If you installed Miniforge (or Mambaforge), we recommend to use -`mamba `_ in the following, +If you installed Miniforge (or Mambaforge), we recommend to use +`mamba `_ in the following, which uses a faster dependency solver than ``conda``. .. _sec-installation-conda-binary: @@ -70,27 +70,27 @@ Using conda to provide system packages for the Sage distribution If Conda is installed (check by typing ``conda info``), one can install SageMath from source as follows: - - Create a new conda environment including all standard packages - recognized by sage, and activate it:: +- Create a new conda environment including all standard packages + recognized by sage, and activate it:: - $ conda env create --file environment-3.11-linux.yml --name sage-build - $ conda activate sage-build + $ conda env create --file environment-3.11-linux.yml --name sage-build + $ conda activate sage-build - If you use a different architecture, replace ``linux`` by ``macos``. - Alternatively, use ``environment-optional-3.11-linux.yml`` in place of - ``environment-3.11-linux.yml`` to create an environment with all standard and optional - packages recognized by sage. + If you use a different architecture, replace ``linux`` by ``macos``. + Alternatively, use ``environment-optional-3.11-linux.yml`` in place of + ``environment-3.11-linux.yml`` to create an environment with all standard and optional + packages recognized by sage. - A different Python version can be selected by replacing ``3.11`` by ``3.9`` - or ``3.10`` in these commands. + A different Python version can be selected by replacing ``3.11`` by ``3.9`` + or ``3.10`` in these commands. - - Then the SageMath distribution will be built using the compilers provided by Conda - and using many packages installed by Conda:: +- Then the SageMath distribution will be built using the compilers provided by Conda + and using many packages installed by Conda:: - $ ./bootstrap - $ ./configure --with-python=$CONDA_PREFIX/bin/python \ - --prefix=$CONDA_PREFIX - $ make + $ ./bootstrap + $ ./configure --with-python=$CONDA_PREFIX/bin/python \ + --prefix=$CONDA_PREFIX + $ make .. _sec-installation-conda-develop: @@ -105,51 +105,51 @@ environment for Sage development. Here we assume that you are using a git checkout. - - Optionally, set the build parallelism for the Sage library. Use - whatever the meaningful value for your machine is - no more than - the number of cores:: +- Optionally, set the build parallelism for the Sage library. Use + whatever the meaningful value for your machine is - no more than + the number of cores:: - $ export SAGE_NUM_THREADS=24 + $ export SAGE_NUM_THREADS=24 - - Create and activate a new conda environment with the dependencies of Sage - and a few additional developer tools:: +- Create and activate a new conda environment with the dependencies of Sage + and a few additional developer tools: - .. tab:: mamba - - .. code-block:: shell - - $ mamba env create --file src/environment-dev-3.11-linux.yml --name sage-dev - $ conda activate sage-dev - - .. tab:: conda - - .. code-block:: shell - - $ conda env create --file src/environment-dev-3.11-linux.yml --name sage-dev - $ conda activate sage-dev + .. tab:: mamba - Alternatively, you can use ``src/environment-3.11-linux.yml`` or - ``src/environment-optional-3.11-linux.yml``, which will only install standard - (and optional) packages without any additional developer tools. + .. code-block:: shell - A different Python version can be selected by replacing ``3.11`` by ``3.9`` - or ``3.10`` in these commands. + $ mamba env create --file src/environment-dev-3.11-linux.yml --name sage-dev + $ conda activate sage-dev - - Bootstrap the source tree and install the build prerequisites and the Sage library:: + .. tab:: conda - $ ./bootstrap - $ pip install --no-build-isolation --config-settings editable_mode=compat -v -v --editable ./src + .. code-block:: shell - If you encounter any errors, try to install the ``sage-conf`` package first:: + $ conda env create --file src/environment-dev-3.11-linux.yml --name sage-dev + $ conda activate sage-dev - $ pip install --no-build-isolation -v -v --editable ./pkgs/sage-conf_conda + Alternatively, you can use ``src/environment-3.11-linux.yml`` or + ``src/environment-optional-3.11-linux.yml``, which will only install standard + (and optional) packages without any additional developer tools. - and then run the last command again. + A different Python version can be selected by replacing ``3.11`` by ``3.9`` + or ``3.10`` in these commands. - - Verify that Sage has been installed:: +- Bootstrap the source tree and install the build prerequisites and the Sage library:: - $ sage -c 'print(version())' - SageMath version 10.2.beta4, Release Date: 2023-09-24 + $ ./bootstrap + $ pip install --no-build-isolation --config-settings editable_mode=compat -v -v --editable ./src + + If you encounter any errors, try to install the ``sage-conf`` package first:: + + $ pip install --no-build-isolation -v -v --editable ./pkgs/sage-conf_conda + + and then run the last command again. + +- Verify that Sage has been installed:: + + $ sage -c 'print(version())' + SageMath version 10.2.beta4, Release Date: 2023-09-24 Note that ``make`` is not used at all. All dependencies (including all Python packages) are provided by conda. diff --git a/src/doc/en/thematic_tutorials/sandpile.rst b/src/doc/en/thematic_tutorials/sandpile.rst index 22f48a2f560..417f10e4dbd 100644 --- a/src/doc/en/thematic_tutorials/sandpile.rst +++ b/src/doc/en/thematic_tutorials/sandpile.rst @@ -1024,9 +1024,7 @@ INPUT: - ``k`` -- integer -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -1046,9 +1044,7 @@ INPUT: - ``k`` -- integer -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -1068,9 +1064,7 @@ INPUT: - ``multivariable`` -- (default: ``True``) boolean -OUTPUT: - -polynomial +OUTPUT: polynomial EXAMPLES:: @@ -1108,9 +1102,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -Betti numbers for the sandpile +OUTPUT: Betti numbers for the sandpile EXAMPLES:: @@ -1229,9 +1221,7 @@ EXAMPLES:: A script for the minimal burning configuration. -OUTPUT: - -dict +OUTPUT: dict EXAMPLES:: @@ -1284,9 +1274,7 @@ EXAMPLES:: The canonical divisor. This is the divisor with `\deg(v)-2` grains of sand on each vertex (not counting loops). Only for undirected graphs. -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -1309,9 +1297,7 @@ EXAMPLES:: A dictionary of dictionaries representing a directed graph. -OUTPUT: - -dict +OUTPUT: dict EXAMPLES:: @@ -1332,9 +1318,7 @@ EXAMPLES:: The genus: (# non-loop edges) - (# vertices) + 1. Only defined for undirected graphs. -OUTPUT: - -integer +OUTPUT: integer EXAMPLES:: @@ -1352,9 +1336,7 @@ EXAMPLES:: A Groebner basis for the homogeneous toppling ideal. It is computed with respect to the standard sandpile ordering (see ``ring``). -OUTPUT: - -Groebner basis +OUTPUT: Groebner basis EXAMPLES:: @@ -1402,9 +1384,7 @@ EXAMPLES:: The size of the sandpile group. -OUTPUT: - -integer +OUTPUT: integer EXAMPLES:: @@ -1422,9 +1402,7 @@ The number of superstable configurations in each degree. Equivalently, this is the list of first differences of the Hilbert function of the (homogeneous) toppling ideal. -OUTPUT: - -list of nonnegative integers +OUTPUT: list of nonnegative integers EXAMPLES:: @@ -1447,9 +1425,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -printed string +OUTPUT: printed string EXAMPLES:: @@ -1476,9 +1452,7 @@ EXAMPLES:: The Hilbert function of the homogeneous toppling ideal. -OUTPUT: - -list of nonnegative integers +OUTPUT: list of nonnegative integers EXAMPLES:: @@ -1501,9 +1475,7 @@ INPUT: - ``gens`` -- (default: ``False``) boolean -OUTPUT: - -ideal or, optionally, the generators of an ideal +OUTPUT: ideal or, optionally, the generators of an ideal EXAMPLES:: @@ -1555,9 +1527,7 @@ INPUT: - ``v`` -- (optional) vertex name -OUTPUT: - -integer or dict +OUTPUT: integer or dict EXAMPLES:: @@ -1575,9 +1545,7 @@ EXAMPLES:: The invariant factors of the sandpile group. -OUTPUT: - -list of integers +OUTPUT: list of integers EXAMPLES:: @@ -1594,9 +1562,7 @@ EXAMPLES:: Is the underlying graph undirected? ``True`` if `(u,v)` is and edge if and only if `(v,u)` is an edge, each edge with the same weight. -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -1667,9 +1633,7 @@ group is isomorphic to the direct sum of the cyclic group of order The Laplacian matrix of the graph. Its *rows* encode the vertex firing rules. -OUTPUT: - -matrix +OUTPUT: matrix EXAMPLES:: @@ -1824,9 +1788,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -tuple of SandpileConfig +OUTPUT: tuple of SandpileConfig EXAMPLES:: @@ -1860,9 +1822,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -list of SandpileConfig +OUTPUT: list of SandpileConfig EXAMPLES:: @@ -1889,9 +1849,7 @@ EXAMPLES:: The nonsink vertices. -OUTPUT: - -list of vertices +OUTPUT: list of vertices EXAMPLES:: @@ -1951,9 +1909,7 @@ INPUT: - ``v`` - (optional) vertex name -OUTPUT: - -integer or dict +OUTPUT: integer or dict EXAMPLES:: @@ -2001,9 +1957,7 @@ EXAMPLES:: Generators for the multiplicative group of zeros of the sandpile ideal. -OUTPUT: - -list of complex numbers +OUTPUT: list of complex numbers EXAMPLES: @@ -2025,9 +1979,7 @@ single generator for the group of solutions. The postulation number of the toppling ideal. This is the largest weight of a superstable configuration of the graph. -OUTPUT: - -nonnegative integer +OUTPUT: nonnegative integer EXAMPLES:: @@ -2048,9 +2000,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -list of recurrent configurations +OUTPUT: list of recurrent configurations EXAMPLES:: @@ -2086,9 +2036,7 @@ EXAMPLES:: The reduced Laplacian matrix of the graph. -OUTPUT: - -matrix +OUTPUT: matrix EXAMPLES:: @@ -2119,9 +2067,7 @@ A copy of the sandpile with vertex names permuted. After reordering, vertex `u` comes before vertex `v` in the list of vertices if `u` is closer to the sink. -OUTPUT: - -Sandpile +OUTPUT: Sandpile EXAMPLES:: @@ -2149,9 +2095,7 @@ INPUT: - ``verbose`` -- (default: ``False``) boolean -OUTPUT: - -free resolution of the toppling ideal +OUTPUT: free resolution of the toppling ideal EXAMPLES:: @@ -2186,9 +2130,7 @@ EXAMPLES:: The ring containing the homogeneous toppling ideal. -OUTPUT: - -ring +OUTPUT: ring EXAMPLES:: @@ -2248,9 +2190,7 @@ EXAMPLES:: The sink vertex. -OUTPUT: - -sink vertex +OUTPUT: sink vertex EXAMPLES:: @@ -2274,9 +2214,7 @@ matrices `D, U, V` such that `ULV = D` where `L` is the transpose of the Laplacian, `D` is diagonal, and `U` and `V` are invertible over the integers. -OUTPUT: - -list of integer matrices +OUTPUT: list of integer matrices EXAMPLES:: @@ -2299,9 +2237,7 @@ EXAMPLES:: Approximations of the complex affine zeros of the sandpile ideal. -OUTPUT: - -list of complex numbers +OUTPUT: list of complex numbers EXAMPLES:: @@ -2346,9 +2282,7 @@ INPUT: - ``smax`` -- (optional) SandpileConfig or list representing a SandpileConfig -OUTPUT: - -generator for all stable configurations +OUTPUT: generator for all stable configurations EXAMPLES:: @@ -2370,9 +2304,7 @@ EXAMPLES:: The stationary density of the sandpile. -OUTPUT: - -rational number +OUTPUT: rational number EXAMPLES:: @@ -2407,9 +2339,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -list of SandpileConfig +OUTPUT: list of SandpileConfig EXAMPLES:: @@ -2449,9 +2379,7 @@ INPUT: - ``orbits`` - list of lists partitioning the vertices -OUTPUT: - -list of recurrent configurations +OUTPUT: list of recurrent configurations EXAMPLES:: @@ -2486,9 +2414,7 @@ EXAMPLES:: The Tutte polynomial of the underlying graph. Only defined for undirected sandpile graphs. -OUTPUT: - -polynomial +OUTPUT: polynomial EXAMPLES:: @@ -2508,9 +2434,7 @@ EXAMPLES:: The unsaturated, homogeneous toppling ideal. -OUTPUT: - -ideal +OUTPUT: ideal EXAMPLES:: @@ -2528,9 +2452,7 @@ EXAMPLES:: The version number of Sage Sandpiles. -OUTPUT: - -string +OUTPUT: string EXAMPLES:: @@ -2548,9 +2470,7 @@ EXAMPLES:: The all-zero configuration. -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -2566,9 +2486,7 @@ EXAMPLES:: The all-zero divisor. -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -2625,13 +2543,13 @@ SandpileConfig - :ref:`help ` --- List of SandpileConfig methods. -- :ref:`is_recurrent ` --- Is the configuration recurrent? +- :ref:`is_recurrent ` --- Return whether the configuration is recurrent. -- :ref:`is_stable ` --- Is the configuration stable? +- :ref:`is_stable ` --- Return whether the configuration is stable. -- :ref:`is_superstable ` --- Is the configuration superstable? +- :ref:`is_superstable ` --- Return whether the configuration is superstable. -- :ref:`is_symmetric ` --- Is the configuration symmetric? +- :ref:`is_symmetric ` --- Return whether the configuration is symmetric. - :ref:`order ` --- The order of the equivalent recurrent element. @@ -2663,9 +2581,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -2687,9 +2603,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -2717,9 +2631,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -2751,9 +2663,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -2775,9 +2685,7 @@ SandpileConfig The stabilized configuration. - OUTPUT: - - ``SandpileConfig`` + OUTPUT: ``SandpileConfig`` EXAMPLES:: @@ -2799,9 +2707,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -2833,9 +2739,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -2872,9 +2776,7 @@ SandpileConfig - ``other`` -- SandpileConfig or Integer - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -2910,9 +2812,7 @@ SandpileConfig - ``k`` -- SandpileConfig - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -2937,9 +2837,7 @@ SandpileConfig The additive inverse of the configuration. - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -2960,9 +2858,7 @@ SandpileConfig - ``other`` -- SandpileConfig - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -2986,9 +2882,7 @@ INPUT: - ``distrib`` -- (optional) list of nonnegative numbers summing to 1 (representing a prob. dist.) -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -3050,9 +2944,7 @@ INPUT: - ``v`` -- vertex -OUTPUT: - -integer +OUTPUT: integer EXAMPLES:: @@ -3081,9 +2973,7 @@ REFERENCES: The degree of the configuration. -OUTPUT: - -integer +OUTPUT: integer EXAMPLES:: @@ -3100,9 +2990,7 @@ EXAMPLES:: The difference with the maximal stable configuration. -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -3128,9 +3016,7 @@ INPUT: - ``with_firing_vector`` -- (default: ``False``) boolean -OUTPUT: - -SandpileConfig or [SandpileConfig, firing_vector] +OUTPUT: SandpileConfig or [SandpileConfig, firing_vector] EXAMPLES:: @@ -3165,9 +3051,7 @@ INPUT: - ``with_firing_vector`` -- (default: ``False``) boolean -OUTPUT: - -SandpileConfig or [SandpileConfig, firing_vector] +OUTPUT: SandpileConfig or [SandpileConfig, firing_vector] EXAMPLES:: @@ -3202,9 +3086,7 @@ INPUT: - ``sigma`` -- SandpileConfig or (list or dict representing a SandpileConfig) -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -3225,9 +3107,7 @@ EXAMPLES:: Fire all unstable vertices. -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -3248,9 +3128,7 @@ INPUT: - ``v`` -- vertex -OUTPUT: - -SandpileConfig +OUTPUT: SandpileConfig EXAMPLES:: @@ -3271,9 +3149,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -printed string +OUTPUT: printed string EXAMPLES:: @@ -3298,10 +3174,10 @@ EXAMPLES:: fire_unstable -- Fire all unstable vertices. fire_vertex -- Fire the given vertex. help -- List of SandpileConfig methods. - is_recurrent -- Is the configuration recurrent? - is_stable -- Is the configuration stable? - is_superstable -- Is the configuration superstable? - is_symmetric -- Is the configuration symmetric? + is_recurrent -- Return whether the configuration is recurrent. + is_stable -- Return whether the configuration is stable. + is_superstable -- Return whether the configuration is superstable. + is_symmetric -- Return whether the configuration is symmetric. order -- The order of the equivalent recurrent element. sandpile -- The configuration's underlying sandpile. show -- Show the configuration. @@ -3316,11 +3192,9 @@ EXAMPLES:: **is_recurrent()** -Is the configuration recurrent? - -OUTPUT: +Return whether the configuration is recurrent. -boolean +OUTPUT: boolean EXAMPLES:: @@ -3336,11 +3210,9 @@ EXAMPLES:: **is_stable()** -Is the configuration stable? +Return whether the configuration is stable. -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -3358,11 +3230,9 @@ EXAMPLES:: **is_superstable()** -Is the configuration superstable? +Return whether the configuration is superstable. -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -3376,7 +3246,7 @@ EXAMPLES:: **is_symmetric(orbits)** -Is the configuration symmetric? Return ``True`` if the values of the +Return whether the configuration is symmetric. Return ``True`` if the values of the configuration are constant over the vertices in each sublist of ``orbits``. @@ -3384,9 +3254,7 @@ INPUT: - ``orbits`` -- list of lists of vertices -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -3407,9 +3275,7 @@ EXAMPLES:: The order of the equivalent recurrent element. -OUTPUT: - -integer +OUTPUT: integer EXAMPLES:: @@ -3435,9 +3301,7 @@ EXAMPLES:: The configuration's underlying sandpile. -OUTPUT: - -Sandpile +OUTPUT: Sandpile EXAMPLES:: @@ -3489,9 +3353,7 @@ INPUT: - ``with_firing_vector`` -- (default: ``False``) boolean -OUTPUT: - -``SandpileConfig`` or ``[SandpileConfig, firing_vector]`` +OUTPUT: ``SandpileConfig`` or ``[SandpileConfig, firing_vector]`` EXAMPLES:: @@ -3538,9 +3400,7 @@ EXAMPLES:: The unstable vertices. -OUTPUT: - -list of vertices +OUTPUT: list of vertices EXAMPLES:: @@ -3558,9 +3418,7 @@ EXAMPLES:: The values of the configuration as a list. The list is sorted in the order of the vertices. -OUTPUT: - -list of integers +OUTPUT: list of integers boolean @@ -3616,13 +3474,13 @@ SandpileDivisor - :ref:`help ` --- List of SandpileDivisor methods. -- :ref:`is_alive ` --- Is the divisor stabilizable? +- :ref:`is_alive ` --- Return whether the divisor is stabilizable. -- :ref:`is_linearly_equivalent ` --- Is the given divisor linearly equivalent? +- :ref:`is_linearly_equivalent ` --- Return whether the given divisor is linearly equivalent. -- :ref:`is_q_reduced ` --- Is the divisor q-reduced? +- :ref:`is_q_reduced ` --- Return whether the divisor is q-reduced. -- :ref:`is_symmetric ` --- Is the divisor symmetric? +- :ref:`is_symmetric ` --- Return whether the divisor is symmetric. - :ref:`is_weierstrass_pt ` --- Is the given vertex a Weierstrass point? @@ -3672,9 +3530,7 @@ SandpileDivisor - ``other`` -- SandpileDivisor - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -3697,9 +3553,7 @@ SandpileDivisor - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3731,9 +3585,7 @@ SandpileDivisor - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3760,9 +3612,7 @@ SandpileDivisor - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3794,9 +3644,7 @@ SandpileDivisor - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3818,9 +3666,7 @@ SandpileDivisor The additive inverse of the divisor. - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -3841,9 +3687,7 @@ SandpileDivisor - ``other`` -- SandpileDivisor - OUTPUT: - - Difference of ``self`` and ``other`` + OUTPUT: difference of ``self`` and ``other`` EXAMPLES:: @@ -3861,9 +3705,7 @@ SandpileDivisor The support-complex. (See NOTE.) -OUTPUT: - -simplicial complex +OUTPUT: simplicial complex EXAMPLES:: @@ -3893,9 +3735,7 @@ INPUT: - ``distrib`` -- (optional) list of nonnegative numbers representing a probability distribution on the vertices -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -3918,9 +3758,7 @@ EXAMPLES:: The Betti numbers for the support-complex. (See NOTE.) -OUTPUT: - -dictionary of integers +OUTPUT: dictionary of integers EXAMPLES:: @@ -3942,9 +3780,7 @@ EXAMPLES:: The degree of the divisor. -OUTPUT: - -integer +OUTPUT: integer EXAMPLES:: @@ -3961,9 +3797,7 @@ EXAMPLES:: The difference with the maximal stable divisor. -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -4050,9 +3884,7 @@ INPUT: - ``sigma`` -- SandpileDivisor or (list or dict representing a SandpileDivisor) -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -4073,9 +3905,7 @@ EXAMPLES:: Fire all unstable vertices. -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -4096,9 +3926,7 @@ INPUT: - ``v`` -- vertex -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -4119,9 +3947,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -printed string +OUTPUT: printed string EXAMPLES:: @@ -4139,11 +3965,11 @@ EXAMPLES:: fire_unstable -- Fire all unstable vertices. fire_vertex -- Fire the given vertex. help -- List of SandpileDivisor methods. - is_alive -- Is the divisor stabilizable? - is_linearly_equivalent -- Is the given divisor linearly equivalent? - is_q_reduced -- Is the divisor q-reduced? - is_symmetric -- Is the divisor symmetric? - is_weierstrass_pt -- Is the given vertex a Weierstrass point? + is_alive -- Return whether the divisor is stabilizable. + is_linearly_equivalent -- Return whether the given divisor is linearly equivalent. + is_q_reduced -- Return whether the divisor is q-reduced. + is_symmetric -- Return whether the divisor is symmetric. + is_weierstrass_pt -- Return whether the given vertex is a Weierstrass point. polytope -- The polytope determining the complete linear system. polytope_integer_pts -- The integer points inside divisor's polytope. q_reduced -- The linearly equivalent q-reduced divisor. @@ -4166,7 +3992,7 @@ EXAMPLES:: **is_alive(cycle=False)** -Is the divisor stabilizable? In other words, will the divisor stabilize +Return whether the divisor is stabilizable. In other words, will the divisor stabilize under repeated firings of all unstable vertices? Optionally returns the resulting cycle. @@ -4174,9 +4000,7 @@ INPUT: - ``cycle`` -- (default: ``False``) boolean -OUTPUT: - -boolean or optionally, a list of SandpileDivisors +OUTPUT: boolean or optionally, a list of SandpileDivisors EXAMPLES:: @@ -4193,7 +4017,7 @@ EXAMPLES:: **is_linearly_equivalent(D, with_firing_vector=False)** -Is the given divisor linearly equivalent? Optionally, returns the +Return whether the given divisor is linearly equivalent. Optionally, returns the firing vector. (See NOTE.) INPUT: @@ -4202,9 +4026,7 @@ INPUT: - ``with_firing_vector`` -- (default: ``False``) boolean -OUTPUT: - -boolean or integer vector +OUTPUT: boolean or integer vector EXAMPLES:: @@ -4236,12 +4058,10 @@ EXAMPLES:: **is_q_reduced()** -Is the divisor `q`-reduced? This would mean that `self = c + kq` where +Return whether the divisor is `q`-reduced. This would mean that `self = c + kq` where `c` is superstable, `k` is an integer, and `q` is the sink vertex. -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -4276,7 +4096,7 @@ general directed graphs: **is_symmetric(orbits)** -Is the divisor symmetric? Return ``True`` if the values of the +Return whether the divisor is symmetric. Return ``True`` if the values of the configuration are constant over the vertices in each sublist of ``orbits``. @@ -4284,9 +4104,7 @@ INPUT: - ``orbits`` -- list of lists of vertices -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -4307,15 +4125,13 @@ EXAMPLES:: **is_weierstrass_pt(v='sink')** -Is the given vertex a Weierstrass point? +Return whether the given vertex is a Weierstrass point. INPUT: - ``v`` -- (default: ``sink``) vertex -OUTPUT: - -boolean +OUTPUT: boolean EXAMPLES:: @@ -4344,9 +4160,7 @@ EXAMPLES:: The polytope determining the complete linear system. -OUTPUT: - -polytope +OUTPUT: polytope EXAMPLES:: @@ -4381,9 +4195,7 @@ The integer points inside divisor's polytope. The polytope referred to here is the one determining the divisor's complete linear system (see the documentation for ``polytope``). -OUTPUT: - -tuple of integer vectors +OUTPUT: tuple of integer vectors EXAMPLES:: @@ -4412,9 +4224,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -SandpileDivisor or list representing SandpileDivisor +OUTPUT: SandpileDivisor or list representing SandpileDivisor EXAMPLES:: @@ -4499,9 +4309,7 @@ EXAMPLES:: The divisor's underlying sandpile. -OUTPUT: - -Sandpile +OUTPUT: Sandpile EXAMPLES:: @@ -4547,9 +4355,7 @@ INPUT: - ``distrib`` -- (optional) list of nonnegative numbers representing a probability distribution on the vertices -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -4598,9 +4404,7 @@ EXAMPLES:: List of vertices at which the divisor is nonzero. -OUTPUT: - -list representing the support of the divisor +OUTPUT: list representing the support of the divisor EXAMPLES:: @@ -4619,9 +4423,7 @@ EXAMPLES:: The unstable vertices. -OUTPUT: - -list of vertices +OUTPUT: list of vertices EXAMPLES:: @@ -4639,9 +4441,7 @@ EXAMPLES:: The values of the divisor as a list. The list is sorted in the order of the vertices. -OUTPUT: - -list of integers +OUTPUT: list of integers boolean @@ -4671,9 +4471,7 @@ INPUT: - ``verbose`` -- (default: ``True``) boolean -OUTPUT: - -SandpileDivisor +OUTPUT: SandpileDivisor EXAMPLES:: @@ -4777,9 +4575,7 @@ INPUT: - ``v`` -- (default: ``sink``) vertex -OUTPUT: - -tuple of int +OUTPUT: tuple of int EXAMPLES:: @@ -4818,9 +4614,7 @@ Other - ``S`` -- Sandpi - ``eff`` -- list of divisors - OUTPUT: - - DiGraph + OUTPUT: DiGraph EXAMPLES:: @@ -4844,9 +4638,7 @@ Other - ``S`` - Sandpi - ``eff`` - list of divisors - OUTPUT: - - DiGraph + OUTPUT: DiGraph EXAMPLES:: @@ -4939,9 +4731,7 @@ Documentation for each method is available through the Sage online help system: - ``v`` - vertex - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES: diff --git a/src/pyproject.toml b/src/pyproject.toml index f70304534d9..780542733c6 100644 --- a/src/pyproject.toml +++ b/src/pyproject.toml @@ -7,7 +7,7 @@ requires = [ # version constraint for macOS Big Sur support (see https://github.com/sagemath/sage/issues/31050) 'wheel >=0.36.2', 'cypari2 >=2.1.1', - 'cysignals >=1.10.2', + 'cysignals >=1.11.4', # Exclude 3.0.3 because of https://github.com/cython/cython/issues/5748 'cython >=3.0, != 3.0.3, <4.0', 'gmpy2 ~=2.1.b999', diff --git a/src/sage/algebras/affine_nil_temperley_lieb.py b/src/sage/algebras/affine_nil_temperley_lieb.py index ae3e8e87464..958171992d4 100644 --- a/src/sage/algebras/affine_nil_temperley_lieb.py +++ b/src/sage/algebras/affine_nil_temperley_lieb.py @@ -23,7 +23,7 @@ class AffineNilTemperleyLiebTypeA(CombinatorialFreeModule): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer The affine nilTemperley Lieb algebra is generated by `a_i` for `i=0,1,\ldots,n-1` subject to the relations `a_i a_i = a_i a_{i+1} a_i = a_{i+1} a_i a_{i+1} = 0` and @@ -48,7 +48,7 @@ def __init__(self, n, R=ZZ, prefix='a'): EXAMPLES:: - sage: A = AffineNilTemperleyLiebTypeA(3, prefix="a"); A + sage: A = AffineNilTemperleyLiebTypeA(3, prefix='a'); A The affine nilTemperley Lieb algebra A3 over the ring Integer Ring sage: TestSuite(A).run() sage: A = AffineNilTemperleyLiebTypeA(3, QQ); A @@ -67,7 +67,7 @@ def __init__(self, n, R=ZZ, prefix='a'): def _element_constructor_(self, w): """ - Constructs a basis element from an element of the Weyl group. + Construct a basis element from an element of the Weyl group. If `w = w_1 ... w_k` is a reduced word for `w`, then `A(w)` returns zero if `w` contains braid relations. @@ -76,7 +76,7 @@ def _element_constructor_(self, w): EXAMPLES:: - sage: A = AffineNilTemperleyLiebTypeA(3, prefix="a") + sage: A = AffineNilTemperleyLiebTypeA(3, prefix='a') sage: W = A.weyl_group() sage: w = W.from_reduced_word([2,1,2]) sage: A(w) diff --git a/src/sage/algebras/algebra.py b/src/sage/algebras/algebra.py index a63aae4e217..8d9395a3176 100644 --- a/src/sage/algebras/algebra.py +++ b/src/sage/algebras/algebra.py @@ -23,7 +23,7 @@ def is_Algebra(x): r""" - Return True if x is an Algebra. + Return ``True`` if `x` is an Algebra. EXAMPLES:: diff --git a/src/sage/algebras/askey_wilson.py b/src/sage/algebras/askey_wilson.py index f696969763d..f8fc56f5f46 100644 --- a/src/sage/algebras/askey_wilson.py +++ b/src/sage/algebras/askey_wilson.py @@ -800,15 +800,13 @@ def __init__(self, domain, on_generators, position=0, codomain=None, INPUT: - ``domain`` -- an Askey-Wilson algebra - - ``on_generators`` -- a list of length 6 corresponding to + - ``on_generators`` -- list of length 6 corresponding to the images of the generators - ``codomain`` -- (optional) the codomain - - ``position`` -- (default: 0) integer + - ``position`` -- integer (default: 0) - ``category`` -- (optional) category - OUTPUT: - - - module morphism + OUTPUT: module morphism EXAMPLES:: @@ -847,16 +845,14 @@ def __eq__(self, other): def _on_basis(self, c): r""" - Computes the image of this morphism on the basis element + Compute the image of this morphism on the basis element indexed by ``c``. INPUT: - - ``c`` -- a tuple of length 6 - - OUTPUT: + - ``c`` -- tuple of length 6 - - element of the codomain + OUTPUT: element of the codomain EXAMPLES:: diff --git a/src/sage/algebras/associated_graded.py b/src/sage/algebras/associated_graded.py index 681bec7e060..8806a1281ff 100644 --- a/src/sage/algebras/associated_graded.py +++ b/src/sage/algebras/associated_graded.py @@ -286,7 +286,7 @@ def algebra_generators(self): Finite family {'x': bar(U['x']), 'y': bar(U['y']), 'z': bar(U['z'])} """ G = self._A.algebra_generators() - return Family(G.keys(), lambda x: self(G[x]), name="generator") + return Family(G.keys(), lambda x: self(G[x]), name='generator') def degree_on_basis(self, x): """ diff --git a/src/sage/algebras/clifford_algebra.py b/src/sage/algebras/clifford_algebra.py index 8b3dbd9c584..2fe4a873ec6 100644 --- a/src/sage/algebras/clifford_algebra.py +++ b/src/sage/algebras/clifford_algebra.py @@ -991,9 +991,7 @@ def lift_module_morphism(self, m, names=None): - ``names`` -- (default: ``'e'``) the names of the generators of the Clifford algebra of the domain of (the map represented by) ``m`` - OUTPUT: - - The algebra morphism `Cl(m)` from `Cl(W, m(Q))` to ``self``. + OUTPUT: the algebra morphism `Cl(m)` from `Cl(W, m(Q))` to ``self`` EXAMPLES:: @@ -1142,9 +1140,7 @@ def lift_isometry(self, m, names=None): the Clifford algebra of the codomain of (the map represented by) ``m`` - OUTPUT: - - The algebra morphism `Cl(m)` from ``self`` to `Cl(W, m^{-1}(Q))`. + OUTPUT: the algebra morphism `Cl(m)` from ``self`` to `Cl(W, m^{-1}(Q))` EXAMPLES:: @@ -1416,7 +1412,7 @@ class ExteriorAlgebra(CliffordAlgebra): - ``R`` -- the base ring, *or* the free module whose exterior algebra is to be computed - - ``names`` -- a list of strings to name the generators of the + - ``names`` -- list of strings to name the generators of the exterior algebra; this list can either have one entry only (in which case the generators will be called ``e + '0'``, ``e + '1'``, ..., ``e + 'n-1'``, with ``e`` being said entry), or have ``n`` entries @@ -1599,9 +1595,8 @@ def lift_morphism(self, phi, names=None): the Clifford algebra of the domain of (the map represented by) ``phi`` - OUTPUT: - - The algebra morphism `\Lambda(\phi)` from ``self`` to `\Lambda(W)`. + OUTPUT: the algebra morphism `\Lambda(\phi)` from ``self`` to + `\Lambda(W)` EXAMPLES:: @@ -1707,7 +1702,7 @@ def boundary(self, s_coeff): INPUT: - - ``s_coeff`` -- a dictionary whose keys are in `I \times I`, where + - ``s_coeff`` -- dictionary whose keys are in `I \times I`, where `I` is the index set of the underlying vector space `V`, and whose values can be coerced into 1-forms (degree 1 elements) in ``E`` (usually, these values will just be elements of `V`) @@ -1730,7 +1725,7 @@ def coboundary(self, s_coeff): INPUT: - - ``s_coeff`` -- a dictionary whose keys are in `I \times I`, where + - ``s_coeff`` -- dictionary whose keys are in `I \times I`, where `I` is the index set of the underlying vector space `V`, and whose values can be coerced into 1-forms (degree 1 elements) in ``E`` (usually, these values will just be elements of `V`) @@ -1795,7 +1790,6 @@ def coproduct_on_basis(self, a): sage: E.coproduct_on_basis((0,1,2)) 1 # x*y*z + x # y*z - y # x*z + x*y # z + z # x*y - x*z # y + y*z # x + x*y*z # 1 - """ from sage.combinat.combinat import unshuffle_iterator one = self.base_ring().one() @@ -2139,7 +2133,7 @@ def __init__(self, E, s_coeff): We skip the pickling test as there is an infinite recursion when doing equality checks:: - sage: TestSuite(par).run(skip="_test_pickling") + sage: TestSuite(par).run(skip='_test_pickling') Check that it knows it is a finite-dimensional algebra morphism (:issue:`25339`):; @@ -2207,7 +2201,7 @@ class ExteriorAlgebraBoundary(ExteriorAlgebraDifferential): INPUT: - ``E`` -- an exterior algebra of a vector space `L` - - ``s_coeff`` -- a dictionary whose keys are in `I \times I`, where + - ``s_coeff`` -- dictionary whose keys are in `I \times I`, where `I` is the index set of the basis of the vector space `L`, and whose values can be coerced into 1-forms (degree 1 elements) in ``E``; this dictionary will be used to define the Lie algebra structure @@ -2452,7 +2446,7 @@ class ExteriorAlgebraCoboundary(ExteriorAlgebraDifferential): INPUT: - ``E`` -- an exterior algebra of a vector space `L` - - ``s_coeff`` -- a dictionary whose keys are in `I \times I`, where + - ``s_coeff`` -- dictionary whose keys are in `I \times I`, where `I` is the index set of the basis of the vector space `L`, and whose values can be coerced into 1-forms (degree 1 elements) in ``E``; this dictionary will be used to define the Lie algebra structure @@ -2736,7 +2730,7 @@ class ExteriorAlgebraIdeal(Ideal_nc): sage: xbar * ybar 0 """ - def __init__(self, ring, gens, coerce=True, side="twosided"): + def __init__(self, ring, gens, coerce=True, side='twosided'): """ Initialize ``self``. @@ -2747,13 +2741,13 @@ def __init__(self, ring, gens, coerce=True, side="twosided"): sage: E. = ExteriorAlgebra(QQ) sage: I = E.ideal([x*y - x, x*y - 1]) - sage: TestSuite(I).run(skip="_test_category") + sage: TestSuite(I).run(skip='_test_category') sage: I = E.ideal([x*y - 3, 0, 2*3]) - sage: TestSuite(I).run(skip="_test_category") + sage: TestSuite(I).run(skip='_test_category') sage: I = E.ideal([]) - sage: TestSuite(I).run(skip="_test_category") + sage: TestSuite(I).run(skip='_test_category') """ self._groebner_strategy = None self._reduced = False @@ -2795,7 +2789,7 @@ def _contains_(self, f): EXAMPLES:: sage: E. = ExteriorAlgebra(QQ) - sage: I = E.ideal([x, x*y*z + 2*x*z + 3*y*z], side="left") + sage: I = E.ideal([x, x*y*z + 2*x*z + 3*y*z], side='left') sage: I.groebner_basis() (x, y*z) sage: x in I @@ -2848,9 +2842,9 @@ def __richcmp__(self, other, op): sage: E. = ExteriorAlgebra(QQ) sage: p = a + b*c - sage: IT = E.ideal([p], side="twosided") - sage: IR = E.ideal([p], side="right") - sage: IL = E.ideal([p], side="left") + sage: IT = E.ideal([p], side='twosided') + sage: IR = E.ideal([p], side='right') + sage: IL = E.ideal([p], side='left') sage: IR == IL False sage: IR <= IL @@ -2936,7 +2930,7 @@ def __mul__(self, other): sage: E. = ExteriorAlgebra(QQ) - sage: I = E.ideal([a + 1], side="left") + sage: I = E.ideal([a + 1], side='left') sage: J = I * I; J Left Ideal (2*a + 1, a, b, c, d, a*b, a*c, a*d, 2*a*b*c + b*c, 2*a*b*d + b*d, 2*a*c*d + c*d, a*b*c, a*b*d, a*c*d, b*c*d, a*b*c*d) @@ -2955,10 +2949,10 @@ def __mul__(self, other): sage: K = J * I sage: K Left Ideal (-a*b - a*c + b + c) of The exterior algebra of rank 4 over Rational Field - sage: E.ideal([J.gen(0) * d * I.gen(0)], side="left") <= K + sage: E.ideal([J.gen(0) * d * I.gen(0)], side='left') <= K True - sage: J = E.ideal([b + c*d], side="right") + sage: J = E.ideal([b + c*d], side='right') sage: I * J Twosided Ideal (a*c*d + a*b + c*d + b) of The exterior algebra of rank 4 over Rational Field sage: X = J * I; X @@ -2971,7 +2965,7 @@ def __mul__(self, other): sage: a * p # not a left ideal a*c*d + a*b - sage: I = E.ideal([a + 1], side="right") + sage: I = E.ideal([a + 1], side='right') sage: E.ideal([1]) * I Twosided Ideal (a + 1) of The exterior algebra of rank 4 over Rational Field sage: I * E.ideal([1]) @@ -2991,9 +2985,9 @@ def __mul__(self, other): if self.side() == "left" or self.side() == "twosided": if other.side() == "right" or other.side() == "twosided": - return self.ring().ideal(gens, side="twosided") - return self.ring().ideal(gens, side="left") - return self.ring().ideal(gens, side="right") + return self.ring().ideal(gens, side='twosided') + return self.ring().ideal(gens, side='left') + return self.ring().ideal(gens, side='right') def groebner_basis(self, term_order=None, reduced=True): r""" @@ -3004,12 +2998,12 @@ def groebner_basis(self, term_order=None, reduced=True): - ``term_order`` -- the term order used to compute the Gröbner basis; must be one of the following: - * ``"neglex"`` -- (default) negative (read right-to-left) lex order - * ``"degrevlex"`` -- degree reverse lex order - * ``"deglex"`` -- degree lex order + * ``'neglex'`` -- (default) negative (read right-to-left) lex order + * ``'degrevlex'`` -- degree reverse lex order + * ``'deglex'`` -- degree lex order - - ``reduced`` -- (default: ``True``) whether or not to return the - reduced Gröbner basis + - ``reduced`` -- boolean (default: ``True``); whether or not to return + the reduced Gröbner basis EXAMPLES: @@ -3043,7 +3037,7 @@ def groebner_basis(self, term_order=None, reduced=True): -a*c*d + a*c*e - a*d*e + c*d*e) The example above was computed first using M2, which agrees with - the ``"degrevlex"`` ordering:: + the ``'degrevlex'`` ordering:: E = QQ[a..e, SkewCommutative => true] I = ideal( c*d*e - b*d*e + b*c*e - b*c*d, diff --git a/src/sage/algebras/clifford_algebra_element.pyx b/src/sage/algebras/clifford_algebra_element.pyx index 52b994f48af..47a5e8026a2 100644 --- a/src/sage/algebras/clifford_algebra_element.pyx +++ b/src/sage/algebras/clifford_algebra_element.pyx @@ -713,7 +713,7 @@ cdef class ExteriorAlgebraElement(CliffordAlgebraElement): INPUT: - - ``I`` -- a list of exterior algebra elements or an ideal + - ``I`` -- list of exterior algebra elements or an ideal - ``left`` -- boolean; if reduce as a left ideal (``True``) or right ideal (``False``), ignored if ``I`` is an ideal diff --git a/src/sage/algebras/cluster_algebra.py b/src/sage/algebras/cluster_algebra.py index df35e502dbd..43a7bba9816 100644 --- a/src/sage/algebras/cluster_algebra.py +++ b/src/sage/algebras/cluster_algebra.py @@ -638,7 +638,7 @@ class ClusterAlgebraSeed(SageObject): - ``G`` -- the matrix of g-vectors of ``self`` - ``parent`` -- :class:`ClusterAlgebra`; the algebra to which the seed belongs - - ``path`` -- list (default ``[]``); the mutation sequence from the + - ``path`` -- list (default: ``[]``); the mutation sequence from the initial seed of ``parent`` to ``self`` .. WARNING:: @@ -902,7 +902,7 @@ def c_vector(self, j) -> tuple: INPUT: - - ``j`` -- an integer in ``range(self.parent().rank())``; + - ``j`` -- integer in ``range(self.parent().rank())``; the index of the c-vector to return EXAMPLES:: @@ -953,7 +953,7 @@ def g_vector(self, j) -> tuple: INPUT: - - ``j`` -- an integer in ``range(self.parent().rank())``; + - ``j`` -- integer in ``range(self.parent().rank())``; the index of the g-vector to return EXAMPLES:: @@ -984,7 +984,7 @@ def F_polynomial(self, j): INPUT: - - ``j`` -- an integer in ``range(self.parent().rank())``; + - ``j`` -- integer in ``range(self.parent().rank())``; the index of the F-polynomial to return EXAMPLES:: @@ -1015,7 +1015,7 @@ def cluster_variable(self, j): INPUT: - - ``j`` -- an integer in ``range(self.parent().rank())``; + - ``j`` -- integer in ``range(self.parent().rank())``; the index of the cluster variable to return EXAMPLES:: @@ -1055,9 +1055,10 @@ def mutate(self, direction, **kwargs): * an iterable of such integers to mutate along a sequence * a string "sinks" or "sources" to mutate at all sinks or sources simultaneously - - ``inplace`` -- bool (default ``True``); whether to mutate in place or to return a new object + - ``inplace`` -- boolean (default: ``True``); whether to mutate in place + or to return a new object - - ``mutating_F`` -- bool (default ``True``); whether to compute + - ``mutating_F`` -- boolean (default: ``True``); whether to compute F-polynomials while mutating .. NOTE:: @@ -1162,10 +1163,10 @@ def _mutated_F(self, k, old_g_vector): INPUT: - - ``k`` -- an integer in ``range(self.parent().rank())``; + - ``k`` -- an integer in ``range(self.parent().rank())``; the direction in which we are mutating - - ``old_g_vector`` -- tuple; the k-th g-vector of ``self`` + - ``old_g_vector`` -- tuple; the `k`-th g-vector of ``self`` before mutating .. NOTE:: @@ -1219,22 +1220,22 @@ class ClusterAlgebra(Parent, UniqueRepresentation): - ``data`` -- some data defining a cluster algebra; it can be anything that can be parsed by :class:`ClusterQuiver` - - ``scalars`` -- a ring (default `\ZZ`); the scalars over + - ``scalars`` -- a ring (default: `\ZZ`); the scalars over which the cluster algebra is defined - - ``cluster_variable_prefix`` -- string (default ``'x'``); it needs to be + - ``cluster_variable_prefix`` -- string (default: ``'x'``); it needs to be a valid variable name - - ``cluster_variable_names`` -- a list of strings; each element needs + - ``cluster_variable_names`` -- list of strings; each element needs to be a valid variable name; supersedes ``cluster_variable_prefix`` - - ``coefficient_prefix`` -- string (default ``'y'``); it needs to be - a valid variable name. + - ``coefficient_prefix`` -- string (default: ``'y'``); it needs to be + a valid variable name - - ``coefficient_names`` -- a list of strings; each element needs + - ``coefficient_names`` -- list of strings; each element needs to be a valid variable name; supersedes ``cluster_variable_prefix`` - - ``principal_coefficients`` -- bool (default ``False``); supersedes any + - ``principal_coefficients`` -- boolean (default: ``False``); supersedes any coefficient defined by ``data`` ALGORITHM: @@ -1811,7 +1812,7 @@ def g_vectors(self, mutating_F=True): INPUT: - - ``mutating_F`` -- bool (default ``True``); whether to compute + - ``mutating_F`` -- boolean (default: ``True``); whether to compute F-polynomials; disable this for speed considerations ALGORITHM: @@ -1990,12 +1991,13 @@ def F_polynomial(self, g_vector): def find_g_vector(self, g_vector, depth=infinity): r""" - Return a mutation sequence to obtain a seed containing the g-vector ``g_vector`` from the initial seed. + Return a mutation sequence to obtain a seed containing the g-vector + ``g_vector`` from the initial seed. INPUT: - - ``g_vector`` -- a tuple: the g-vector to find - - ``depth`` -- a positive integer or infinity (default ``infinity``); + - ``g_vector`` -- tuple; the g-vector to find + - ``depth`` -- positive integer or infinity (default: ``infinity``); the maximum distance from ``self.current_seed`` to reach OUTPUT: @@ -2111,7 +2113,7 @@ def coefficient(self, j): INPUT: - - ``j`` -- an integer in ``range(self.parent().rank())``; + - ``j`` -- integer in ``range(self.parent().rank())``; the index of the coefficient to return EXAMPLES:: @@ -2167,7 +2169,7 @@ def initial_cluster_variable(self, j): INPUT: - - ``j`` -- an integer in ``range(self.parent().rank())``; + - ``j`` -- integer in ``range(self.parent().rank())``; the index of the cluster variable to return EXAMPLES:: @@ -2212,19 +2214,19 @@ def seeds(self, **kwargs): INPUT: - - ``from_current_seed`` -- bool (default ``False``); whether to start + - ``from_current_seed`` -- boolean (default: ``False``); whether to start the iterator from :meth:`current_seed` or :meth:`initial_seed` - - ``mutating_F`` -- bool (default ``True``); whether to compute + - ``mutating_F`` -- boolean (default: ``True``); whether to compute F-polynomials also; disable this for speed considerations - ``allowed_directions`` -- iterable of integers - (default ``range(self.rank())``); the directions in which to mutate + (default: ``range(self.rank())``); the directions in which to mutate - - ``depth`` -- a positive integer or infinity (default ``infinity``); + - ``depth`` -- positive integer or infinity (default: ``infinity``); the maximum depth at which to stop searching - - ``catch_KeyboardInterrupt`` -- bool (default ``False``); whether to + - ``catch_KeyboardInterrupt`` -- boolean (default: ``False``); whether to catch ``KeyboardInterrupt`` and return it rather then raising an exception -- this allows the iterator returned by this method to be resumed after being interrupted @@ -2319,7 +2321,7 @@ def reset_exploring_iterator(self, mutating_F=True): INPUT: - - ``mutating_F`` -- bool (default ``True``); whether to also compute + - ``mutating_F`` -- boolean (default: ``True``); whether to also compute F-polynomials; disable this for speed considerations EXAMPLES:: @@ -2343,7 +2345,7 @@ def explore_to_depth(self, depth): INPUT: - - ``depth`` -- a positive integer or infinity; the maximum depth + - ``depth`` -- positive integer or infinity; the maximum depth at which to stop searching EXAMPLES:: @@ -2370,7 +2372,7 @@ def cluster_fan(self, depth=infinity): INPUT: - - ``depth`` -- a positive integer or infinity (default ``infinity``); + - ``depth`` -- positive integer or infinity (default: ``infinity``); the maximum depth at which to compute EXAMPLES:: @@ -2401,7 +2403,7 @@ def mutate_initial(self, direction, **kwargs): * an iterable of such integers to mutate along a sequence * a string "sinks" or "sources" to mutate at all sinks or sources simultaneously - - ``mutating_F`` -- bool (default ``True``); whether to compute + - ``mutating_F`` -- boolean (default: ``True``); whether to compute F-polynomials while mutating .. NOTE:: diff --git a/src/sage/algebras/commutative_dga.py b/src/sage/algebras/commutative_dga.py index a027d1c996a..60b80719c53 100644 --- a/src/sage/algebras/commutative_dga.py +++ b/src/sage/algebras/commutative_dga.py @@ -114,11 +114,9 @@ def sorting_keys(element): INPUT: - - ``element`` -- A CohomologyClass + - ``element`` -- a CohomologyClass - OUTPUT: - - Its coordinates in the corresponding ``cohomology_raw`` quotient vector space + OUTPUT: its coordinates in the corresponding ``cohomology_raw`` quotient vector space EXAMPLES:: @@ -261,7 +259,7 @@ def __init__(self, A, im_gens): We skip the category test because homsets/morphisms aren't proper parents/elements yet:: - sage: TestSuite(d).run(skip="_test_category") + sage: TestSuite(d).run(skip='_test_category') An error is raised if the differential `d` does not have degree 1 or if `d \circ d` is not zero:: @@ -433,7 +431,6 @@ def coboundaries(self, n): Vector space of degree 2 and dimension 0 over Rational Field Basis matrix: [] - """ A = self.domain() F = A.base_ring() @@ -614,7 +611,7 @@ def __init__(self, A, im_gens): We skip the category test because homsets/morphisms aren't proper parents/elements yet:: - sage: TestSuite(d).run(skip="_test_category") + sage: TestSuite(d).run(skip='_test_category') """ Differential.__init__(self, A, im_gens) @@ -643,10 +640,10 @@ def differential_matrix_multigraded(self, n, total=False): INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, - return the matrix corresponding to total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, + return the matrix corresponding to total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -686,19 +683,19 @@ def differential_matrix_multigraded(self, n, total=False): def coboundaries(self, n, total=False): """ - The ``n``-th coboundary group of the algebra. + The `n`-th coboundary group of the algebra. This is a vector space over the base field `F`, and it is returned as a subspace of the vector space `F^d`, where the - ``n``-th homogeneous component has dimension `d`. + `n`-th homogeneous component has dimension `d`. INPUT: - ``n`` -- degree - - ``total`` (default ``False``) -- if ``True``, return the - coboundaries in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + coboundaries in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -733,19 +730,19 @@ def coboundaries(self, n, total=False): def cocycles(self, n, total=False): r""" - The ``n``-th cocycle group of the algebra. + The `n`-th cocycle group of the algebra. This is a vector space over the base field `F`, and it is returned as a subspace of the vector space `F^d`, where the - ``n``-th homogeneous component has dimension `d`. + `n`-th homogeneous component has dimension `d`. INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, return the - cocycles in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + cocycles in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -778,7 +775,7 @@ def cocycles(self, n, total=False): def cohomology_raw(self, n, total=False): r""" - The ``n``-th cohomology group of the algebra. + The `n`-th cohomology group of the algebra. This is a vector space over the base ring, and it is returned as the quotient cocycles/coboundaries. @@ -786,10 +783,10 @@ def cohomology_raw(self, n, total=False): INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, return the - cohomology in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + cohomology in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. .. SEEALSO:: @@ -822,7 +819,7 @@ def cohomology_raw(self, n, total=False): def cohomology(self, n, total=False): r""" - The ``n``-th cohomology group of the algebra. + The `n`-th cohomology group of the algebra. This is a vector space over the base ring, defined as the quotient cocycles/coboundaries. The elements of the quotient @@ -832,10 +829,10 @@ def cohomology(self, n, total=False): INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, return the - cohomology in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + cohomology in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. .. SEEALSO:: @@ -889,11 +886,11 @@ class GCAlgebra(UniqueRepresentation, QuotientRing_nc): 1, and if both ``names`` and ``degrees`` are omitted, an error is raised. - - ``R`` (default: None) -- the ring over which the + - ``R`` -- (default: ``None``) the ring over which the algebra is defined: if this is specified, the algebra is defined to be ``R/I``. - - ``I`` (default: None) -- an ideal in ``R``. It is + - ``I`` -- (default: ``None``) an ideal in `R`. It is should include, among other relations, the squares of the generators of odd degree @@ -1086,7 +1083,7 @@ def _repr_(self): @cached_method def _basis_for_free_alg(self, n): r""" - Basis of the associated free commutative DGA in degree ``n``. + Basis of the associated free commutative DGA in degree `n`. That is, ignore the relations when computing the basis: compute the basis of the free commutative DGA with generators @@ -1096,9 +1093,7 @@ def _basis_for_free_alg(self, n): - ``n`` -- integer - OUTPUT: - - Tuple of basis elements in degree ``n``, as tuples of exponents. + OUTPUT: tuple of basis elements in degree `n`, as tuples of exponents EXAMPLES:: @@ -1164,7 +1159,7 @@ def _basis_for_free_alg(self, n): def basis(self, n): """ - Return a basis of the ``n``-th homogeneous component of ``self``. + Return a basis of the `n`-th homogeneous component of ``self``. EXAMPLES:: @@ -1202,7 +1197,7 @@ def quotient(self, I, check=True): - ``I`` -- a two-sided homogeneous ideal of this algebra - - ``check`` -- (default: ``True``) if ``True``, check whether + - ``check`` -- boolean (default: ``True``); if ``True``, check whether ``I`` is generated by homogeneous elements EXAMPLES:: @@ -1350,7 +1345,7 @@ def differential(self, diff): INPUT: - - ``diff`` -- a dictionary defining a differential + - ``diff`` -- dictionary defining a differential The keys of the dictionary are generators of the algebra, and the associated values are their targets under the @@ -1380,7 +1375,7 @@ def cdg_algebra(self, differential): INPUT: - - ``differential`` -- a dictionary defining a differential or + - ``differential`` -- dictionary defining a differential or a map defining a valid differential The keys of the dictionary are generators of the algebra, and @@ -1494,7 +1489,7 @@ def is_homogeneous(self, total=False): INPUT: - - ``total`` -- boolean (default ``False``); only used in the + - ``total`` -- boolean (default: ``False``); only used in the multi-graded case, in which case if ``True``, check to see if ``self`` is homogeneous with respect to total degree @@ -1546,7 +1541,6 @@ def homogeneous_parts(self): Return the homogeneous parts of the element. The result is given as a dictionary indexed by degree. - EXAMPLES:: sage: A. = GradedCommutativeAlgebra(QQ) @@ -1593,9 +1587,7 @@ def __call__(self, *values, **kwargs): - ``values`` -- (optional) either the values in which the variables will be evaluated or a dictionary - OUTPUT: - - this element evaluated at the given values + OUTPUT: this element evaluated at the given values EXAMPLES:: @@ -1663,21 +1655,19 @@ def basis_coefficients(self, total=False): Return the coefficients of this homogeneous element with respect to the basis in its degree. - For example, if this is the sum of the 0th and 2nd basis + For example, if this is the sum of the `0`-th and `2`-nd basis elements, return the list ``[1, 0, 1]``. Raise an error if the element is not homogeneous. INPUT: - - ``total`` -- boolean (default ``False``); this + - ``total`` -- boolean (default: ``False``); this is only used in the multi-graded case, in which case if ``True``, it returns the coefficients with respect to the basis for the total degree of this element - OUTPUT: - - A list of elements of the base field. + OUTPUT: list of elements of the base field EXAMPLES:: @@ -1717,7 +1707,7 @@ class GCAlgebra_multigraded(GCAlgebra): - ``base`` -- the base field - - ``degrees`` -- a tuple or list specifying the degrees of the + - ``degrees`` -- tuple or list specifying the degrees of the generators - ``names`` -- (optional) names of the generators: a list of @@ -1815,7 +1805,7 @@ def quotient(self, I, check=True): - ``I`` -- a two-sided homogeneous ideal of this algebra - - ``check`` -- (default: ``True``) if ``True``, check whether + - ``check`` -- boolean (default: ``True``); if ``True``, check whether ``I`` is generated by homogeneous elements EXAMPLES:: @@ -1870,13 +1860,13 @@ def _coerce_map_from_(self, other): def basis(self, n, total=False): """ - Basis in degree ``n``. + Basis in degree `n`. - ``n`` -- degree or integer - - ``total`` (default: ``False``) -- if True, return the - basis in total degree ``n``. + - ``total`` -- boolean (default: ``False``); if ``True``, return the + basis in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -1887,12 +1877,13 @@ def basis(self, n, total=False): sage: A.basis(2, total=True) [a^2, a*b, b^2, c] - Since 2 is a not a multi-index, we don't need to specify ``total=True``:: + Since 2 is a not a multi-index, we don't need to specify that ``total`` + is ``True``:: sage: A.basis(2) [a^2, a*b, b^2, c] - If ``total==True``, then ``n`` can still be a tuple, list, + If ``total`` is ``True``, then `n` can still be a tuple, list, etc., and its total degree is used instead:: sage: A.basis((1,1), total=True) @@ -1911,7 +1902,7 @@ def differential(self, diff): INPUT: - - ``diff`` -- a dictionary defining a differential + - ``diff`` -- dictionary defining a differential The keys of the dictionary are generators of the algebra, and the associated values are their targets under the @@ -1937,7 +1928,7 @@ def cdg_algebra(self, differential): INPUT: - - ``differential`` -- a dictionary defining a differential or + - ``differential`` -- dictionary defining a differential or a map defining a valid differential The keys of the dictionary are generators of the algebra, and @@ -2091,7 +2082,7 @@ def __classcall__(cls, A, differential): def __init__(self, A, differential): """ - Initialize ``self`` + Initialize ``self``. INPUT: @@ -2137,7 +2128,7 @@ def cdg_algebra(self, differential): INPUT: - - ``differential`` -- a dictionary defining a differential or + - ``differential`` -- dictionary defining a differential or a map defining a valid differential The keys of the dictionary are generators of the algebra, and @@ -2172,7 +2163,6 @@ def cdg_algebra(self, differential): y --> 0 z --> 0 t --> 0 - """ return self.graded_commutative_algebra().cdg_algebra(differential) @@ -2225,7 +2215,7 @@ def quotient(self, I, check=True): - ``I`` -- a two-sided homogeneous ideal of this algebra - - ``check`` -- (default: ``True``) if ``True``, check whether + - ``check`` -- boolean (default: ``True``); if ``True``, check whether ``I`` is generated by homogeneous elements EXAMPLES:: @@ -2289,11 +2279,11 @@ def differential(self, x=None): def coboundaries(self, n): """ - The ``n``-th coboundary group of the algebra. + The `n`-th coboundary group of the algebra. This is a vector space over the base field `F`, and it is returned as a subspace of the vector space `F^d`, where the - ``n``-th homogeneous component has dimension `d`. + `n`-th homogeneous component has dimension `d`. INPUT: @@ -2318,11 +2308,11 @@ def coboundaries(self, n): def cocycles(self, n): """ - The ``n``-th cocycle group of the algebra. + The `n`-th cocycle group of the algebra. This is a vector space over the base field `F`, and it is returned as a subspace of the vector space `F^d`, where the - ``n``-th homogeneous component has dimension `d`. + `n`-th homogeneous component has dimension `d`. INPUT: @@ -2343,7 +2333,7 @@ def cocycles(self, n): def cohomology_raw(self, n): """ - The ``n``-th cohomology group of ``self``. + The `n`-th cohomology group of ``self``. This is a vector space over the base ring, and it is returned as the quotient cocycles/coboundaries. @@ -2375,7 +2365,7 @@ def cohomology_raw(self, n): def cohomology(self, n): """ - The ``n``-th cohomology group of ``self``. + The `n`-th cohomology group of ``self``. This is a vector space over the base ring, defined as the quotient cocycles/coboundaries. The elements of the quotient @@ -2446,7 +2436,7 @@ def cohomology_generators(self, max_degree): ALGORITHM: - Reduce a basis of the `n`'th cohomology modulo all the degree `n` + Reduce a basis of the `n`-th cohomology modulo all the degree `n` products of the lower degree cohomologies. EXAMPLES:: @@ -2500,7 +2490,6 @@ def cohomology_generators(self, max_degree): sage: B = A.cdg_algebra(d) sage: B.cohomology_generators(3) {1: [e1 - e2, e3, e4], 2: [e1*e3, e1*e4]} - """ if not (max_degree in ZZ and max_degree > 0): raise ValueError('the given maximal degree must be a ' @@ -2539,14 +2528,14 @@ def vector_to_element(v, deg): def minimal_model(self, i=3, max_iterations=3, partial_result=False): r""" - Try to compute a map from a ``i``-minimal gcda that is a - ``i``-quasi-isomorphism to self. + Try to compute a map from a `i`-minimal gcda that is a + `i`-quasi-isomorphism to ``self``. INPUT: - ``i`` -- integer (default: `3`); degree to which the result is required to induce an isomorphism in cohomology, and the domain is - required to be minimal. + required to be minimal - ``max_iterations`` -- integer (default: `3`); the number of iterations of the method at each degree. If the algorithm does not @@ -2554,8 +2543,8 @@ def minimal_model(self, i=3, max_iterations=3, partial_result=False): or the partial result computed up to that point is returned, deppending on the ``partial_result`` flag. - - ``partial_result`` -- boolean (default: ``False``); wether to return - the partial result if the ``max_iterations`` limit is reached. + - ``partial_result`` -- boolean (default: ``False``); wether to return + the partial result if the ``max_iterations`` limit is reached OUTPUT: @@ -2742,7 +2731,6 @@ def minimal_model(self, i=3, max_iterations=3, partial_result=False): - [Fel2001]_ - [Man2019]_ - """ max_degree = int(i) if max_degree < 1: @@ -2886,12 +2874,12 @@ def extendy(phi, degree): def cohomology_algebra(self, max_degree=3): """ Compute a CDGA with trivial differential, that is isomorphic to the cohomology of - self up to``max_degree`` + ``self`` up to``max_degree`` INPUT: - ``max_degree`` -- integer (default: `3`); degree to which the result is required to - be isomorphic to self's cohomology. + be isomorphic to ``self``'s cohomology EXAMPLES:: @@ -3005,7 +2993,6 @@ def numerical_invariants(self, max_degree=3, max_iterations=3): REFERENCES: For a precise definition and properties, see [Man2019]_ . - """ self.minimal_model(max_degree, max_iterations) return {i: self._numerical_invariants[i] @@ -3324,19 +3311,19 @@ def _base_repr(self): def coboundaries(self, n, total=False): """ - The ``n``-th coboundary group of the algebra. + The `n`-th coboundary group of the algebra. This is a vector space over the base field `F`, and it is returned as a subspace of the vector space `F^d`, where the - ``n``-th homogeneous component has dimension `d`. + `n`-th homogeneous component has dimension `d`. INPUT: - ``n`` -- degree - - ``total`` (default ``False``) -- if ``True``, return the - coboundaries in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + coboundaries in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -3356,19 +3343,19 @@ def coboundaries(self, n, total=False): def cocycles(self, n, total=False): r""" - The ``n``-th cocycle group of the algebra. + The `n`-th cocycle group of the algebra. This is a vector space over the base field `F`, and it is returned as a subspace of the vector space `F^d`, where the - ``n``-th homogeneous component has dimension `d`. + `n`-th homogeneous component has dimension `d`. INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, return the - cocycles in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + cocycles in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -3388,7 +3375,7 @@ def cocycles(self, n, total=False): def cohomology_raw(self, n, total=False): """ - The ``n``-th cohomology group of the algebra. + The `n`-th cohomology group of the algebra. This is a vector space over the base ring, and it is returned as the quotient cocycles/coboundaries. @@ -3398,10 +3385,10 @@ def cohomology_raw(self, n, total=False): INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, return the - cohomology in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + cohomology in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -3430,7 +3417,7 @@ def cohomology_raw(self, n, total=False): def cohomology(self, n, total=False): """ - The ``n``-th cohomology group of the algebra. + The `n`-th cohomology group of the algebra. This is a vector space over the base ring, defined as the quotient cocycles/coboundaries. The elements of the quotient @@ -3442,10 +3429,10 @@ def cohomology(self, n, total=False): INPUT: - ``n`` -- degree - - ``total`` -- (default: ``False``) if ``True``, return the - cohomology in total degree ``n`` + - ``total`` -- boolean (default: ``False``); if ``True``, return the + cohomology in total degree `n` - If ``n`` is an integer rather than a multi-index, then the + If `n` is an integer rather than a multi-index, then the total degree is used in that case as well. EXAMPLES:: @@ -3506,7 +3493,7 @@ def GradedCommutativeAlgebra(ring, names=None, degrees=None, max_degree=None, - ``ring`` -- a graded commutative algebra - - ``relations`` -- a list or tuple of elements of ``ring`` + - ``relations`` -- list or tuple of elements of ``ring`` EXAMPLES: @@ -3733,7 +3720,7 @@ def __init__(self, parent, im_gens, check=True): Defn: (x, y) --> (x, x) sage: f.is_graded() False - sage: TestSuite(f).run(skip="_test_category") + sage: TestSuite(f).run(skip='_test_category') Since `x^2=0` but `y^2 \neq 0`, the following does not define a valid morphism:: @@ -3795,7 +3782,6 @@ def __init__(self, parent, im_gens, check=True): Graded Commutative Algebra endomorphism of Graded Commutative Algebra with generators ('e1',) in degrees (1,) over Rational Field Defn: (e1,) --> (2*e1,) - """ domain = parent.domain() codomain = parent.codomain() @@ -3891,7 +3877,7 @@ def is_graded(self, total=False): INPUT: - - ``total`` (default: ``False``) -- if ``True``, use + - ``total`` -- boolean (default: ``False``); if ``True``, use the total degree to determine whether the morphism is graded (relevant only in the multigraded case) @@ -4116,7 +4102,6 @@ class CohomologyClass(SageObject, CachedRepresentation): e5 --> e1*e2 e6 --> e1*e2 + e3*e4 Defn: (x1_0, x1_1, x1_2, x1_3, y1_0, y1_1) --> (e1, e2, e3, e4, e5, -e5 + e6) - """ def __init__(self, x, cdga=None): """ @@ -4188,7 +4173,7 @@ def exterior_algebra_basis(n, degrees): - ``degrees`` -- iterable of integers Return list of lists, each list representing exponents for the - corresponding generators. (So each list consists of 0's and 1's.) + corresponding generators. (So each list consists of 0s and 1s.) EXAMPLES:: @@ -4230,7 +4215,7 @@ def total_degree(deg): INPUT: - - ``deg`` -- an element of a free abelian group. + - ``deg`` -- an element of a free abelian group In fact, ``deg`` could be an integer, a Python int, a list, a tuple, a vector, etc. This function returns the sum of the diff --git a/src/sage/algebras/down_up_algebra.py b/src/sage/algebras/down_up_algebra.py index 7b43db7b3a5..1bb35730014 100644 --- a/src/sage/algebras/down_up_algebra.py +++ b/src/sage/algebras/down_up_algebra.py @@ -100,7 +100,7 @@ class DownUpAlgebra(CombinatorialFreeModule): b*u^2*d + a*u*(d*u) + g*u We verify some examples of Proposition 3.5 in [BR1998]_, which states - that the 0-th degree part is commutative:: + that the `0`-th degree part is commutative:: sage: DU0 = [u^i * (d*u)^j * d^i for i,j in ....: cartesian_product([range(3), range(3)])] diff --git a/src/sage/algebras/exterior_algebra_groebner.pyx b/src/sage/algebras/exterior_algebra_groebner.pyx index d296bae64f3..cad3574c8a2 100644 --- a/src/sage/algebras/exterior_algebra_groebner.pyx +++ b/src/sage/algebras/exterior_algebra_groebner.pyx @@ -57,7 +57,7 @@ cdef class GBElement: sage: from sage.algebras.exterior_algebra_groebner import GBElement sage: E. = ExteriorAlgebra(QQ) sage: X = GBElement(a, a.leading_support(), 1) - sage: TestSuite(X).run(skip="_test_pickling") + sage: TestSuite(X).run(skip='_test_pickling') """ self.elt = x self.ls = ls @@ -114,9 +114,9 @@ cdef class GroebnerStrategy: sage: from sage.algebras.exterior_algebra_groebner import GroebnerStrategy sage: E. = ExteriorAlgebra(QQ) - sage: I = E.ideal([a + 1], side="left") + sage: I = E.ideal([a + 1], side='left') sage: G = GroebnerStrategy(I) - sage: TestSuite(G).run(skip="_test_pickling") + sage: TestSuite(G).run(skip='_test_pickling') """ self.ideal = I self.groebner_basis = (None,) @@ -293,18 +293,18 @@ cdef class GroebnerStrategy: EXAMPLES:: sage: E. = ExteriorAlgebra(QQ) - sage: I = E.ideal([x*y - x, x*y - 1], side="left") + sage: I = E.ideal([x*y - x, x*y - 1], side='left') sage: I.groebner_basis() # indirect doctest (1,) - sage: J = E.ideal([x*y - x, 2*x*y - 2], side="left") + sage: J = E.ideal([x*y - x, 2*x*y - 2], side='left') sage: J.groebner_basis() # indirect doctest (1,) sage: E. = ExteriorAlgebra(QQ) - sage: I = E.ideal([a+b*c], side="left") + sage: I = E.ideal([a+b*c], side='left') sage: I.groebner_basis() # indirect doctest (b*c + a,) - sage: I = E.ideal([a+b*c], side="twosided") + sage: I = E.ideal([a+b*c], side='twosided') sage: I.groebner_basis() # indirect doctest (a*b, a*c, b*c + a, a*d) """ diff --git a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra.py b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra.py index a634b546926..da5e18db630 100644 --- a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra.py +++ b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra.py @@ -36,12 +36,12 @@ class FiniteDimensionalAlgebra(UniqueRepresentation, Algebra): - ``k`` -- a field - - ``table`` -- a list of matrices + - ``table`` -- list of matrices - - ``names`` -- (default: ``'e'``) string; names for the basis + - ``names`` -- string (default: ``'e'``); names for the basis elements - - ``assume_associative`` -- (default: ``False``) boolean; if + - ``assume_associative`` -- boolean (default: ``False``); if ``True``, then the category is set to ``category.Associative()`` and methods requiring associativity assume this @@ -310,7 +310,7 @@ def basis(self): def __iter__(self): """ - Iterates over the elements of ``self``. + Iterate over the elements of ``self``. EXAMPLES:: @@ -439,11 +439,11 @@ def ideal(self, gens=None, given_by_matrix=False, side=None): - ``A`` -- a :class:`FiniteDimensionalAlgebra` - - ``gens`` -- (default: None); either an element of ``A`` or a - list of elements of ``A``, given as vectors, matrices, or + - ``gens`` -- (default: ``None``) either an element of `A` or a + list of elements of `A`, given as vectors, matrices, or FiniteDimensionalAlgebraElements. If ``given_by_matrix`` is ``True``, then ``gens`` should instead be a matrix whose rows - form a basis of an ideal of ``A``. + form a basis of an ideal of `A`. - ``given_by_matrix`` -- boolean (default: ``False``); if ``True``, no checking is done @@ -811,7 +811,7 @@ def maximal_ideal(self): - :class:`~sage.algebras.finite_dimensional_algebras.finite_dimensional_algebra_ideal.FiniteDimensionalAlgebraIdeal`; the unique maximal ideal of ``self``. If ``self`` is not a local - algebra, a :class:`ValueError` is raised. + algebra, a :exc:`ValueError` is raised. EXAMPLES:: diff --git a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_element.pyx b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_element.pyx index f1ad68cbe6a..cd101fb4e12 100644 --- a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_element.pyx +++ b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_element.pyx @@ -31,7 +31,6 @@ cpdef FiniteDimensionalAlgebraElement unpickle_FiniteDimensionalAlgebraElement(A sage: x = B([1,2,3]) sage: loads(dumps(x)) == x # indirect doctest True - """ cdef FiniteDimensionalAlgebraElement x = A.element_class.__new__(A.element_class) AlgebraElement.__init__(x, A) @@ -145,7 +144,6 @@ cdef class FiniteDimensionalAlgebraElement(AlgebraElement): True sage: loads(dumps(x)) is x False - """ return unpickle_FiniteDimensionalAlgebraElement, (self._parent, self._vector, self.__matrix) @@ -172,7 +170,6 @@ cdef class FiniteDimensionalAlgebraElement(AlgebraElement): sage: x.vector() (1, 1, 1) - """ self._parent, D = state v = D.pop('_vector') @@ -339,7 +336,7 @@ cdef class FiniteDimensionalAlgebraElement(AlgebraElement): def __getitem__(self, m): """ - Return the `m`-th coefficient of ``self`` + Return the `m`-th coefficient of ``self``. EXAMPLES:: diff --git a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_ideal.py b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_ideal.py index c328b65c5b2..bba15b91366 100644 --- a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_ideal.py +++ b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_ideal.py @@ -36,8 +36,8 @@ class FiniteDimensionalAlgebraIdeal(Ideal_generic): - ``A`` -- a finite-dimensional algebra - ``gens`` -- the generators of this ideal - - ``given_by_matrix`` -- (default: ``False``) whether the basis matrix is - given by ``gens`` + - ``given_by_matrix`` -- boolean (default: ``False``); whether the basis + matrix is given by ``gens`` EXAMPLES:: @@ -57,7 +57,7 @@ def __init__(self, A, gens=None, given_by_matrix=False): ....: Matrix([[0, 1], [0, 0]])], ....: category=cat) sage: I = A.ideal(A([0,1])) - sage: TestSuite(I).run(skip="_test_category") # Currently ideals are not using the category framework + sage: TestSuite(I).run(skip='_test_category') # Currently ideals are not using the category framework """ k = A.base_ring() n = A.degree() @@ -80,7 +80,7 @@ def __init__(self, A, gens=None, given_by_matrix=False): def _richcmp_(self, other, op): r""" - Comparisons + Comparisons. TESTS:: diff --git a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_morphism.py b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_morphism.py index dfcaa1d0341..90c3ae45573 100644 --- a/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_morphism.py +++ b/src/sage/algebras/finite_dimensional_algebras/finite_dimensional_algebra_morphism.py @@ -29,7 +29,7 @@ class FiniteDimensionalAlgebraMorphism(RingHomomorphism_im_gens): - ``f`` -- matrix of the underlying `k`-linear map - ``unitary`` -- boolean (default: ``True``); if ``True`` and ``check`` - is also ``True``, raise a :class:`ValueError` unless ``A`` and ``B`` are + is also ``True``, raise a :exc:`ValueError` unless ``A`` and ``B`` are unitary and ``f`` respects unit elements - ``check`` -- boolean (default: ``True``); check whether the given @@ -67,7 +67,7 @@ def __init__(self, parent, f, check=True, unitary=True): ....: Matrix([[0, 1], [0, 0]])]) sage: H = Hom(A, B) sage: phi = FiniteDimensionalAlgebraMorphism(H, Matrix([[1, 0]])) - sage: TestSuite(phi).run(skip="_test_category") + sage: TestSuite(phi).run(skip='_test_category') """ A = parent.domain() B = parent.codomain() @@ -178,9 +178,7 @@ def inverse_image(self, I): - ``I`` -- ``FiniteDimensionalAlgebraIdeal``, an ideal of ``self.codomain()`` - OUTPUT: - - :class:`FiniteDimensionalAlgebraIdeal`, the inverse image of `I` under ``self``. + OUTPUT: :class:`FiniteDimensionalAlgebraIdeal`, the inverse image of `I` under ``self`` EXAMPLES:: diff --git a/src/sage/algebras/finite_gca.py b/src/sage/algebras/finite_gca.py index a8702c3a47d..0caf51c8ec5 100644 --- a/src/sage/algebras/finite_gca.py +++ b/src/sage/algebras/finite_gca.py @@ -78,12 +78,12 @@ class FiniteGCAlgebra(CombinatorialFreeModule): - ``degrees`` -- (optional) a tuple or list specifying the degrees of the generators; if omitted, each generator is given degree 1, and if both ``names`` and ``degrees`` are omitted, an error is - raised. - - ``max_degree`` -- the maximal degree of the graded algebra. - - ``mul_symbol`` -- (optional) symbol used for multiplication. If omitted, - the string "*" is used. - - ``mul_latex_symbol`` -- (optional) latex symbol used for multiplication. - If omitted, the empty string is used. + raised + - ``max_degree`` -- the maximal degree of the graded algebra + - ``mul_symbol`` -- (optional) symbol used for multiplication; if omitted, + the string "*" is used + - ``mul_latex_symbol`` -- (optional) latex symbol used for multiplication; + if omitted, the empty string is used EXAMPLES:: @@ -132,7 +132,6 @@ class FiniteGCAlgebra(CombinatorialFreeModule): sage: A. = GradedCommutativeAlgebra(QQ, degrees=(1,2,6,6)) sage: type(A) - """ @staticmethod def __classcall_private__(cls, base, names=None, degrees=None, @@ -146,7 +145,7 @@ def __classcall_private__(cls, base, names=None, degrees=None, - ``base`` -- the base ring of the algebra - ``max_degree`` -- the maximal degree of the algebra - ``names`` -- the names of the variables; by default, set to ``x1``, - ``x2``, etc. + ``x2``, etc - ``degrees`` -- the degrees of the generators; by default, set to 1 TESTS:: @@ -155,7 +154,6 @@ def __classcall_private__(cls, base, names=None, degrees=None, sage: A2 = GradedCommutativeAlgebra(GF(2), ['x', 'y'], [3, 6], max_degree=12) sage: A1 is A2 True - """ if max_degree is None: raise TypeError("max_degree must be specified") diff --git a/src/sage/algebras/free_algebra.py b/src/sage/algebras/free_algebra.py index ad04a988f15..6080b82a396 100644 --- a/src/sage/algebras/free_algebra.py +++ b/src/sage/algebras/free_algebra.py @@ -298,7 +298,6 @@ def create_key(self, base_ring, arg1=None, arg2=None, sage: FreeAlgebra.create_key(GF(5),3,'xyz', ....: implementation='letterplace', degrees=[1,2,3]) ((1, 2, 3), Multivariate Polynomial Ring in x, y, z, x_ over Finite Field of size 5) - """ if arg1 is None and arg2 is None and names is None: # this is used for pickling @@ -411,7 +410,7 @@ class FreeAlgebra_generic(CombinatorialFreeModule): INPUT: - ``R`` -- a ring - - ``n`` -- an integer + - ``n`` -- integer - ``names`` -- the generator names - ``degrees`` -- (optional) a tuple or list specifying the degrees of all the generators, if omitted, the algebra is not diff --git a/src/sage/algebras/free_algebra_element.py b/src/sage/algebras/free_algebra_element.py index 815be8858b5..db8880eb262 100644 --- a/src/sage/algebras/free_algebra_element.py +++ b/src/sage/algebras/free_algebra_element.py @@ -84,7 +84,7 @@ def __init__(self, A, x): def _repr_(self): """ - Return string representation of self. + Return string representation of ``self``. EXAMPLES:: @@ -98,7 +98,6 @@ def _repr_(self): sage: with localvars(A, ['a','b','c']): ....: print(-x+3*y*z) -a + 3*b*c - """ v = sorted(self._monomial_coefficients.items()) P = self.parent() @@ -110,7 +109,7 @@ def _repr_(self): def _latex_(self): r""" - Return latex representation of self. + Return latex representation of ``self``. EXAMPLES:: diff --git a/src/sage/algebras/free_algebra_quotient.py b/src/sage/algebras/free_algebra_quotient.py index df19a18e3e8..2d54b35a8e1 100644 --- a/src/sage/algebras/free_algebra_quotient.py +++ b/src/sage/algebras/free_algebra_quotient.py @@ -226,7 +226,7 @@ def gen(self, i): sage: H.gen(2) k - An :class:`IndexError` is raised if an invalid generator is requested:: + An :exc:`IndexError` is raised if an invalid generator is requested:: sage: H.gen(3) Traceback (most recent call last): diff --git a/src/sage/algebras/free_algebra_quotient_element.py b/src/sage/algebras/free_algebra_quotient_element.py index 0523ff4b9dc..b594cc65dec 100644 --- a/src/sage/algebras/free_algebra_quotient_element.py +++ b/src/sage/algebras/free_algebra_quotient_element.py @@ -189,7 +189,7 @@ def _richcmp_(self, right, op): def __neg__(self): """ - Return negative of self. + Return negative of ``self``. EXAMPLES:: diff --git a/src/sage/algebras/free_zinbiel_algebra.py b/src/sage/algebras/free_zinbiel_algebra.py index 720ee803d9b..875fde1fba9 100644 --- a/src/sage/algebras/free_zinbiel_algebra.py +++ b/src/sage/algebras/free_zinbiel_algebra.py @@ -535,7 +535,7 @@ def _coerce_map_from_(self, R): The things that coerce into ``self`` are - free Zinbiel algebras whose set `E` of labels is - a subset of the corresponding self of ``set`, and whose base + a subset of the corresponding ``self`` of ``set``, and whose base ring has a coercion map into ``self.base_ring()`` EXAMPLES:: diff --git a/src/sage/algebras/fusion_rings/f_matrix.py b/src/sage/algebras/fusion_rings/f_matrix.py index 6ec533af939..52e9cfdeb98 100644 --- a/src/sage/algebras/fusion_rings/f_matrix.py +++ b/src/sage/algebras/fusion_rings/f_matrix.py @@ -54,9 +54,9 @@ class FMatrix(SageObject): (see :meth:`FusionRing.fusion_labels`) - ``var_prefix`` -- (optional) a string indicating the desired prefix for variables denoting F-symbols to be solved - - ``inject_variables`` -- (default: ``False``) a boolean indicating - whether to inject variables (:class:`FusionRing` basis element - labels and F-symbols) into the global namespace + - ``inject_variables`` -- boolean (default: ``False``); whether to inject + variables (:class:`FusionRing` basis element labels and F-symbols) into + the global namespace The :class:`FusionRing` or Verlinde algebra is the Grothendieck ring of a modular tensor category [BaKi2001]_. @@ -263,14 +263,14 @@ class FMatrix(SageObject): sage: f.field() # long time Algebraic Field """ - def __init__(self, fusion_ring, fusion_label="f", var_prefix='fx', inject_variables=False): + def __init__(self, fusion_ring, fusion_label='f', var_prefix='fx', inject_variables=False): r""" Initialize ``self``. EXAMPLES:: sage: f = FusionRing("B3", 2).get_fmatrix() - sage: TestSuite(f).run(skip="_test_pickling") + sage: TestSuite(f).run(skip='_test_pickling') """ self._FR = fusion_ring if inject_variables and (self._FR._fusion_labels is None): @@ -472,7 +472,7 @@ def fmatrix(self, a, b, c, d): EXAMPLES:: - sage: fr = FusionRing("A1", 2, fusion_labels="c", inject_variables=True) + sage: fr = FusionRing("A1", 2, fusion_labels='c', inject_variables=True) sage: f = fr.get_fmatrix(new=True) sage: f.fmatrix(c1, c1, c1, c1) [fx0 fx1] @@ -606,7 +606,7 @@ def f_from(self, a, b, c, d): EXAMPLES:: - sage: fr = FusionRing("A1", 3, fusion_labels="a", inject_variables=True) + sage: fr = FusionRing("A1", 3, fusion_labels='a', inject_variables=True) sage: f = fr.get_fmatrix() sage: f.fmatrix(a1, a1, a2, a2) [fx6 fx7] @@ -739,7 +739,7 @@ def get_qqbar_embedding(self): EXAMPLES:: sage: fr = FusionRing("G2", 1) - sage: f = fr.get_fmatrix(fusion_label="g", inject_variables=True, new=True) + sage: f = fr.get_fmatrix(fusion_label='g', inject_variables=True, new=True) creating variables fx1..fx5 Defining fx0, fx1, fx2, fx3, fx4 sage: f.find_orthogonal_solution() @@ -822,7 +822,7 @@ def get_fvars_in_alg_field(self): EXAMPLES:: sage: fr = FusionRing("G2", 1) - sage: f = fr.get_fmatrix(fusion_label="g", inject_variables=True, new=True) + sage: f = fr.get_fmatrix(fusion_label='g', inject_variables=True, new=True) creating variables fx1..fx5 Defining fx0, fx1, fx2, fx3, fx4 sage: f.find_orthogonal_solution(verbose=False) @@ -919,7 +919,7 @@ def get_fvars_by_size(self, n, indices=False): INPUT: - - `n` -- a positive integer + - ``n`` -- positive integer - ``indices`` -- boolean (default: ``False``) If ``indices`` is ``False`` (default), @@ -974,7 +974,7 @@ def save_fvars(self, filename): INPUT: - - ``filename`` -- a string specifying the name of the pickle file + - ``filename`` -- string specifying the name of the pickle file to be used The current directory is used unless an absolute path to a file in @@ -1087,7 +1087,7 @@ def _checkpoint(self, do_chkpt, status, verbose=True): Checkpoint 2 reached! sage: del f sage: f = FusionRing("A1", 3).get_fmatrix(new=True) - sage: f.find_orthogonal_solution(warm_start="fmatrix_solver_checkpoint_A13.pickle") + sage: f.find_orthogonal_solution(warm_start='fmatrix_solver_checkpoint_A13.pickle') Computing F-symbols for The Fusion Ring of Type A1 and level 3 with Integer Ring coefficients with 71 variables... Set up 121 reduced pentagons... Elimination epoch completed... 18 eqns remain in ideal basis @@ -1123,7 +1123,7 @@ def _checkpoint(self, do_chkpt, status, verbose=True): Checkpoint 4 reached! sage: del f sage: f = FusionRing("A1", 2).get_fmatrix(new=True) - sage: f.find_orthogonal_solution(warm_start="fmatrix_solver_checkpoint_A12.pickle") + sage: f.find_orthogonal_solution(warm_start='fmatrix_solver_checkpoint_A12.pickle') Computing F-symbols for The Fusion Ring of Type A1 and level 2 with Integer Ring coefficients with 14 variables... Partitioned 0 equations into 0 components of size: [] @@ -1189,10 +1189,10 @@ def _restore_state(self, filename): TESTS:: sage: f = FusionRing("A1", 3).get_fmatrix(new=True) - sage: f.find_orthogonal_solution(save_results="test.pickle", verbose=False) # long time + sage: f.find_orthogonal_solution(save_results='test.pickle', verbose=False) # long time sage: del f sage: f = FusionRing("A1", 3).get_fmatrix(new=True) - sage: f.find_orthogonal_solution(warm_start="test.pickle") # long time + sage: f.find_orthogonal_solution(warm_start='test.pickle') # long time sage: f._chkpt_status == 7 # long time True sage: os.remove("test.pickle") # long time @@ -1227,14 +1227,11 @@ def start_worker_pool(self, processes=None): INPUT: - - ``processes`` -- an integer indicating the number of workers - in the pool; if left unspecified, the number of workers is + - ``processes`` -- integer indicating the number of workers + in the pool; if left unspecified, the number of workers equals the number of processors available - OUTPUT: - - This method returns a boolean indicating whether a worker pool - was successfully initialized. + OUTPUT: boolean; whether a worker pool was successfully initialized EXAMPLES:: @@ -1399,7 +1396,7 @@ def get_orthogonality_constraints(self, output=True): INPUT: - - ``output`` -- a boolean + - ``output`` -- boolean OUTPUT: @@ -1445,7 +1442,7 @@ def get_defining_equations(self, option, output=True): INPUT: - - ``option`` -- a string determining equations to be set up: + - ``option`` -- string determining equations to be set up: * ``'hexagons'`` -- get equations imposed on the F-matrix by the hexagon relations in the definition of a braided category @@ -1453,7 +1450,7 @@ def get_defining_equations(self, option, output=True): * ``'pentagons'`` -- get equations imposed on the F-matrix by the pentagon relations in the definition of a monoidal category - - ``output`` -- (default: ``True``) a boolean indicating whether + - ``output`` -- boolean (default: ``True``); whether results should be returned, where the equations will be polynomials. Otherwise, the constraints are appended to ``self.ideal_basis``. Constraints are stored in the internal tuple representation. The @@ -1621,7 +1618,7 @@ def equations_graph(self, eqns=None): INPUT: - - ``eqns`` -- a list of polynomials + - ``eqns`` -- list of polynomials Each polynomial is either an object in the ring returned by :meth:`get_poly_ring` or it is a tuple of pairs representing @@ -1727,7 +1724,7 @@ def _partition_eqns(self, eqns=None, verbose=True): print(graph.connected_components_sizes()) return partition - def _par_graph_gb(self, eqns=None, term_order="degrevlex", largest_comp=45, verbose=True): + def _par_graph_gb(self, eqns=None, term_order='degrevlex', largest_comp=45, verbose=True): r""" Compute a Groebner basis for a list of equations partitioned according to their corresponding graph. @@ -1783,8 +1780,8 @@ def _get_component_variety(self, var, eqns): INPUT: - - ``var`` -- a list of variable indices - - ``eqns`` -- a list of polynomial equations in the internal + - ``var`` -- list of variable indices + - ``eqns`` -- list of polynomial equations in the internal tuple of pairs representation EXAMPLES:: @@ -1992,14 +1989,14 @@ def _get_explicit_solution(self, eqns=None, verbose=True): if self._FR._basecoer: self._FR.r_matrix.clear_cache() - def find_orthogonal_solution(self, checkpoint=False, save_results="", warm_start="", use_mp=True, verbose=True): + def find_orthogonal_solution(self, checkpoint=False, save_results='', warm_start='', use_mp=True, verbose=True): r""" Solve the the hexagon and pentagon relations, along with orthogonality constraints, to evaluate an orthogonal F-matrix. INPUT: - - ``checkpoint`` -- (default: ``False``) a boolean indicating whether + - ``checkpoint`` -- boolean (default: ``False``); whether the computation should be checkpointed. Depending on the associated ``CartanType``, the computation may take hours to complete. For large examples, checkpoints are recommended. This method supports @@ -2029,13 +2026,13 @@ def find_orthogonal_solution(self, checkpoint=False, save_results="", warm_start If no file name is provided, the calculation begins from scratch. - - ``use_mp`` -- (default: ``True``) a boolean indicating whether to use + - ``use_mp`` -- boolean (default: ``True``); whether to use multiprocessing to speed up calculation. The default value ``True`` is highly recommended, since parallel processing yields results much more quickly. - - ``verbose`` -- (default: ``True``) a boolean indicating whether the - solver should print out intermediate progress reports. + - ``verbose`` -- boolean (default: ``True``); whether the + solver should print out intermediate progress reports OUTPUT: @@ -2045,7 +2042,7 @@ def find_orthogonal_solution(self, checkpoint=False, save_results="", warm_start EXAMPLES:: - sage: f = FusionRing("B5", 1).get_fmatrix(fusion_label="b", inject_variables=True) + sage: f = FusionRing("B5", 1).get_fmatrix(fusion_label='b', inject_variables=True) creating variables fx1..fx14 Defining fx0, fx1, fx2, fx3, fx4, fx5, fx6, fx7, fx8, fx9, fx10, fx11, fx12, fx13 sage: f.find_orthogonal_solution() @@ -2150,7 +2147,7 @@ def find_orthogonal_solution(self, checkpoint=False, save_results="", warm_start # Set up new equations graph and compute variety for each component if self._chkpt_status < 5: - self.ideal_basis = self._par_graph_gb(term_order="lex", verbose=verbose) + self.ideal_basis = self._par_graph_gb(term_order='lex', verbose=verbose) self.ideal_basis.sort(key=poly_tup_sortkey) self._triangular_elim(verbose=verbose) self._checkpoint(checkpoint, 5, verbose=verbose) @@ -2271,7 +2268,7 @@ def _update_equations(self): self.ideal_basis = {eq.subs(special_values) for eq in self.ideal_basis} self.ideal_basis.discard(0) - def find_cyclotomic_solution(self, equations=None, algorithm="", verbose=True, output=False): + def find_cyclotomic_solution(self, equations=None, algorithm='', verbose=True, output=False): r""" Solve the hexagon and pentagon relations to evaluate the F-matrix. @@ -2286,14 +2283,14 @@ def find_cyclotomic_solution(self, equations=None, algorithm="", verbose=True, o - ``equations`` -- (optional) a set of equations to be solved; defaults to the hexagon and pentagon equations - ``algorithm`` -- (optional) algorithm to compute Groebner Basis - - ``output`` -- (default: ``False``) output a dictionary of + - ``output`` -- boolean (default: ``False``); output a dictionary of F-matrix values; this may be useful to see but may be omitted since this information will be available afterwards via the :meth:`fmatrix` and :meth:`fmat` methods. EXAMPLES:: - sage: fr = FusionRing("A2", 1, fusion_labels="a", inject_variables=True) + sage: fr = FusionRing("A2", 1, fusion_labels='a', inject_variables=True) sage: f = fr.get_fmatrix(inject_variables=True) creating variables fx1..fx8 Defining fx0, fx1, fx2, fx3, fx4, fx5, fx6, fx7 diff --git a/src/sage/algebras/fusion_rings/fast_parallel_fmats_methods.pyx b/src/sage/algebras/fusion_rings/fast_parallel_fmats_methods.pyx index a9b7eb50fab..2627a6f11b1 100644 --- a/src/sage/algebras/fusion_rings/fast_parallel_fmats_methods.pyx +++ b/src/sage/algebras/fusion_rings/fast_parallel_fmats_methods.pyx @@ -406,7 +406,7 @@ cdef list compute_gb(factory, tuple args): for eq_tup in eqns: eq_tup = _unflatten_coeffs(F, eq_tup) polys.append(_tup_to_poly(resize(eq_tup, idx_map, nvars), parent=R)) - gb = Ideal(sorted(polys)).groebner_basis(algorithm="libsingular:slimgb") + gb = Ideal(sorted(polys)).groebner_basis(algorithm='libsingular:slimgb') # Change back to fmats poly ring and append to temp_eqns cdef dict inv_idx_map = {v: k for k, v in idx_map.items()} @@ -460,7 +460,7 @@ cpdef executor(tuple params): INPUT: - - ``params`` -- a tuple ``((fn_name, fmats_id), fn_args)`` where + - ``params`` -- tuple ``((fn_name, fmats_id), fn_args)`` where ``fn_name`` is the name of the function to be executed, ``fmats_id`` is the ``id`` of the :class:`FMatrix` object, and ``fn_args`` is a tuple containing all arguments to be passed to the function ``fn_name``. diff --git a/src/sage/algebras/fusion_rings/fusion_double.py b/src/sage/algebras/fusion_rings/fusion_double.py index 7ce086f70d0..71277561331 100644 --- a/src/sage/algebras/fusion_rings/fusion_double.py +++ b/src/sage/algebras/fusion_rings/fusion_double.py @@ -98,7 +98,7 @@ class FusionDouble(CombinatorialFreeModule): :: sage: G1 = SymmetricGroup(3) - sage: H1 = FusionDouble(G1, prefix="u", inject_variables=True) + sage: H1 = FusionDouble(G1, prefix='u', inject_variables=True) sage: F = H1.get_fmatrix() The above commands create the F-matrix. You can compute all of the @@ -131,13 +131,12 @@ class FusionDouble(CombinatorialFreeModule): EXAMPLES:: sage: G = SmallPermutationGroup(16,9) - sage: F = FusionDouble(G, prefix="b",inject_variables=True) + sage: F = FusionDouble(G, prefix='b', inject_variables=True) sage: b13^2 # long time (4s) b0 + b2 + b4 + b15 + b16 + b17 + b18 + b24 + b26 + b27 - """ @staticmethod - def __classcall_private__(cls, G, prefix="s", inject_variables=False): + def __classcall_private__(cls, G, prefix='s', inject_variables=False): """ Normalize input to ensure a unique representation. @@ -153,7 +152,7 @@ def __classcall_private__(cls, G, prefix="s", inject_variables=False): F.inject_variables() return F - def __init__(self, G, prefix="s"): + def __init__(self, G, prefix='s'): """ EXAMPLES:: @@ -211,7 +210,7 @@ def inject_variables(self): EXAMPLES:: - sage: F = FusionDouble(DiCyclicGroup(3), prefix="d") + sage: F = FusionDouble(DiCyclicGroup(3), prefix='d') sage: F.inject_variables() sage: d0 + d1 + d5 d0 + d1 + d5 @@ -237,22 +236,22 @@ def _char_cache(self, i, g): @cached_method def s_ij(self, i, j, unitary=False, base_coercion=True): r""" - Return the element of the S-matrix of this fusion ring + Return the element of the `S`-matrix of this fusion ring corresponding to the given elements. - Without the unitary option set true, this is the unnormalized S-matrix + Without the unitary option set true, this is the unnormalized `S`-matrix entry, denoted `\tilde{s}_{ij}`, in [BaKi2001]_ Chapter 3. The - normalized S-matrix entries are denoted `s_{ij}`. + normalized `S`-matrix entries are denoted `s_{ij}`. INPUT: - ``i``, ``j``, -- a pair of basis elements - - ``unitary`` -- (default: ``False``) set to ``True`` to obtain - the unitary S-matrix + - ``unitary`` -- boolean (default: ``False``); set to ``True`` to + obtain the unitary `S`-matrix EXAMPLES:: - sage: D = FusionDouble(SymmetricGroup(3), prefix="t", inject_variables=True) + sage: D = FusionDouble(SymmetricGroup(3), prefix='t', inject_variables=True) sage: [D.s_ij(t2, x) for x in D.basis()] [2, 2, 4, 0, 0, -2, -2, -2] sage: [D.s_ij(t2, x, unitary=True) for x in D.basis()] @@ -280,7 +279,7 @@ def s_ij(self, i, j, unitary=False, base_coercion=True): def s_ijconj(self, i, j, unitary=False, base_coercion=True): r""" - Return the conjugate of the element of the S-matrix given by + Return the conjugate of the element of the `S`-matrix given by ``self.s_ij(elt_i, elt_j, base_coercion=base_coercion)``. .. SEEALSO:: @@ -289,7 +288,7 @@ def s_ijconj(self, i, j, unitary=False, base_coercion=True): EXAMPLES:: - sage: P=FusionDouble(CyclicPermutationGroup(3),prefix="p",inject_variables=True) + sage: P=FusionDouble(CyclicPermutationGroup(3),prefix='p',inject_variables=True) sage: P.s_ij(p1,p3) zeta3 sage: P.s_ijconj(p1,p3) @@ -299,12 +298,12 @@ def s_ijconj(self, i, j, unitary=False, base_coercion=True): def s_matrix(self, unitary=False, base_coercion=True): r""" - Return the S-matrix of this fusion ring. + Return the `S`-matrix of this fusion ring. OPTIONAL: - - ``unitary`` -- (default: ``False``) set to ``True`` to obtain - the unitary S-matrix + - ``unitary`` -- boolean (default: ``False``); set to ``True`` to + obtain the unitary `S`-matrix Without the ``unitary`` parameter, this is the matrix denoted `\widetilde{s}` in [BaKi2001]_. @@ -329,7 +328,6 @@ def s_matrix(self, unitary=False, base_coercion=True): [ 1/3 1/3 -1/3 0 0 2/3 -1/3 -1/3] [ 1/3 1/3 -1/3 0 0 -1/3 -1/3 2/3] [ 1/3 1/3 -1/3 0 0 -1/3 2/3 -1/3] - """ b = self.basis() S = matrix([[self.s_ij(b[x], b[y], unitary=unitary, base_coercion=base_coercion) @@ -349,11 +347,11 @@ def N_ijk(self, i, j, k): where `s_0` is the unit element (assuming ``prefix='s'``). Method of computation is through the Verlinde formula, - deducing the values from the known values of the S-matrix. + deducing the values from the known values of the `S`-matrix. EXAMPLES:: - sage: A = FusionDouble(AlternatingGroup(4),prefix="a",inject_variables=True) + sage: A = FusionDouble(AlternatingGroup(4),prefix='a',inject_variables=True) sage: [A.N_ijk(a10,a11,x) for x in A.basis()] [0, 0, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0] @@ -379,7 +377,7 @@ def Nk_ij(self, i, j, k, use_characters=False): INPUT: - ``i``, ``j``, ``k`` -- basis elements - - ``use_characters`` -- (default: ``False``) see the algorithm + - ``use_characters`` -- boolean (default: ``False``); see the algorithm description below ALGORITHM: @@ -423,7 +421,7 @@ def Nk_ij(self, i, j, k, use_characters=False): EXAMPLES:: - sage: A = FusionDouble(AlternatingGroup(4),prefix="aa",inject_variables=True) + sage: A = FusionDouble(AlternatingGroup(4),prefix='aa',inject_variables=True) sage: [A.Nk_ij(aa8,aa10,x) for x in A.basis()] [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 1] @@ -473,7 +471,7 @@ def Nk_ij(self, i, j, k, use_characters=False): @cached_method def field(self): """ - Returns a cyclotomic field large enough to contain the values + Return a cyclotomic field large enough to contain the values of R-matrices and twists that can arise for this fusion ring. EXAMPLES:: @@ -546,7 +544,7 @@ def r_matrix(self, i, j, k, base_coercion=True): EXAMPLES:: - sage: C = FusionDouble(SymmetricGroup(3),prefix="c",inject_variables=True) + sage: C = FusionDouble(SymmetricGroup(3),prefix='c',inject_variables=True) sage: c4*c5 c3 + c4 sage: [C.r_matrix(c4,c5,k) for k in [c3,c4]] @@ -654,7 +652,7 @@ def one_basis(self): EXAMPLES:: - sage: FusionDouble(CyclicPermutationGroup(2), prefix="h").one() + sage: FusionDouble(CyclicPermutationGroup(2), prefix='h').one() h1 """ return self._unit_index @@ -668,7 +666,7 @@ def dual(self, i): EXAMPLES:: - sage: K = FusionDouble(CyclicPermutationGroup(3),prefix="k") + sage: K = FusionDouble(CyclicPermutationGroup(3),prefix='k') sage: [(x,K.dual(x)) for x in K.basis()] [(k0, k0), (k1, k2), @@ -693,11 +691,12 @@ def product_on_basis(self, a, b): INPUT: - - ``a`, ``b`` -- keys for the dictionary ``self._names`` representing simple objects + - ``a``, ``b`` -- keys for the dictionary ``self._names`` representing + simple objects EXAMPLES:: - sage: Q=FusionDouble(SymmetricGroup(3),prefix="q",inject_variables=True) + sage: Q=FusionDouble(SymmetricGroup(3),prefix='q',inject_variables=True) sage: q3*q4 q1 + q2 + q5 + q6 + q7 sage: Q._names @@ -744,7 +743,7 @@ def is_simple_object(self): EXAMPLES:: - sage: H = FusionDouble(CyclicPermutationGroup(2), prefix="g", inject_variables=True) + sage: H = FusionDouble(CyclicPermutationGroup(2), prefix='g', inject_variables=True) sage: [x.is_simple_object() for x in [g0, g1, g0+g1]] [True, True, False] """ @@ -762,7 +761,7 @@ class representative `g` and an irreducible character `\chi` of EXAMPLES:: sage: G = QuaternionGroup() - sage: H = FusionDouble(G, prefix="e", inject_variables=True) + sage: H = FusionDouble(G, prefix='e', inject_variables=True) sage: e10.g() (1,3)(2,4)(5,7)(6,8) sage: e10.char() @@ -784,7 +783,7 @@ class representative `g` and an irreducible character `\chi` of EXAMPLES:: sage: G = DihedralGroup(5) - sage: H = FusionDouble(G, prefix="f", inject_variables=True) + sage: H = FusionDouble(G, prefix='f', inject_variables=True) sage: f10.g() (1,2,3,4,5) sage: f10.char() @@ -854,7 +853,7 @@ def dual(self): EXAMPLES:: sage: G = CyclicPermutationGroup(4) - sage: H = FusionDouble(G, prefix="j") + sage: H = FusionDouble(G, prefix='j') sage: [x for x in H.basis() if x == x.dual()] [j0, j1, j8, j9] diff --git a/src/sage/algebras/fusion_rings/fusion_ring.py b/src/sage/algebras/fusion_rings/fusion_ring.py index 72bc0f8600c..1ce6b920daa 100644 --- a/src/sage/algebras/fusion_rings/fusion_ring.py +++ b/src/sage/algebras/fusion_rings/fusion_ring.py @@ -39,21 +39,21 @@ class FusionRing(WeylCharacterRing): INPUT: - ``ct`` -- the Cartan type of a simple (finite-dimensional) Lie algebra - - ``k`` -- a nonnegative integer - - ``conjugate`` -- (default ``False``) set ``True`` to obtain + - ``k`` -- nonnegative integer + - ``conjugate`` -- (default: ``False``) set ``True`` to obtain the complex conjugate ring - - ``cyclotomic_order`` -- (default computed depending on ``ct`` and ``k``) - - ``fusion_labels`` -- (default None) either a tuple of strings to use as labels of the + - ``cyclotomic_order`` -- (default: computed depending on ``ct`` and ``k``) + - ``fusion_labels`` -- (default: ``None``) either a tuple of strings to use as labels of the basis of simple objects, or a string from which the labels will be constructed - - ``inject_variables`` -- (default ``False``): use with ``fusion_labels``. + - ``inject_variables`` -- (default: ``False``) use with ``fusion_labels``. If ``inject_variables`` is ``True``, the fusion labels will be variables that can be accessed from the command line The cyclotomic order is an integer `N` such that all computations will return elements of the cyclotomic field of `N`-th roots of unity. Normally you will never need to change this but consider changing it - if :meth:`root_of_unity` raises a :class:`ValueError`. + if :meth:`root_of_unity` raises a :exc:`ValueError`. This algebra has a basis (sometimes called *primary fields* but here called *simple objects*) indexed by the weights of level `\leq k`. @@ -136,15 +136,15 @@ class FusionRing(WeylCharacterRing): as the Grothendieck ring of a *modular tensor category* (MTC). These include twist methods :meth:`Element.twist` and :meth:`Element.ribbon` for its elements related to the ribbon structure, and the - S-matrix :meth:`s_ij`. + `S`-matrix :meth:`s_ij`. - There are two natural normalizations of the S-matrix. Both + There are two natural normalizations of the `S`-matrix. Both are explained in Chapter 3 of [BaKi2001]_. The one that is computed by the method :meth:`s_matrix`, or whose individual entries are computed by :meth:`s_ij` is denoted `\tilde{s}` in [BaKi2001]_. It is not unitary. - The unitary S-matrix is `s=D^{-1/2}\tilde{s}` where + The unitary `S`-matrix is `s=D^{-1/2}\tilde{s}` where .. MATH:: @@ -154,7 +154,7 @@ class FusionRing(WeylCharacterRing): `d_i(V)` the *quantum dimension*. We will call quantity `D` the *global quantum dimension* and `\sqrt{D}` the *total quantum order*. They are computed by :meth:`global_q_dimension` - and :meth:`total_q_order`. The unitary S-matrix `s` may be obtained + and :meth:`total_q_order`. The unitary `S`-matrix `s` may be obtained using :meth:`s_matrix` with the option ``unitary=True``. Let us check the Verlinde formula, which is [DFMS1996]_ (16.3). This @@ -166,7 +166,7 @@ class FusionRing(WeylCharacterRing): where `N^k_{ij}` are the fusion coefficients, i.e. the structure constants of the fusion ring, and ``I`` is the unit object. - The S-matrix has the property that if `i*` denotes the dual + The `S`-matrix has the property that if `i*` denotes the dual object of `i`, implemented in Sage as ``i.dual()``, then .. MATH:: @@ -180,7 +180,7 @@ class FusionRing(WeylCharacterRing): N_{ijk} = \sum_l \frac{s(i, \ell)\, s(j, \ell)\, s(k, \ell)}{s(I, \ell)}, - In this formula `s` is the normalized unitary S-matrix + In this formula `s` is the normalized unitary `S`-matrix denoted `s` in [BaKi2001]_. We may define a function that corresponds to the right-hand side, except using `\tilde{s}` instead of `s`:: @@ -257,9 +257,9 @@ class FusionRing(WeylCharacterRing): T = \begin{pmatrix} 1 & 1\\ &1 \end{pmatrix} subject to the relations `(ST)^3 = S^2`, `S^2T = TS^2`, and `S^4 = I`. - Let `s` be the normalized S-matrix, and + Let `s` be the normalized `S`-matrix, and `t` the diagonal matrix whose entries are the twists of the simple - objects. Let `s` the unitary S-matrix and `t` the matrix of twists, + objects. Let `s` the unitary `S`-matrix and `t` the matrix of twists, and `C` the conjugation matrix :meth:`conj_matrix`. Let .. MATH:: @@ -299,7 +299,7 @@ class FusionRing(WeylCharacterRing): True """ @staticmethod - def __classcall__(cls, ct, k, base_ring=ZZ, prefix=None, style="coroots", conjugate=False, cyclotomic_order=None, fusion_labels=None, inject_variables=False): + def __classcall__(cls, ct, k, base_ring=ZZ, prefix=None, style='coroots', conjugate=False, cyclotomic_order=None, fusion_labels=None, inject_variables=False): """ Normalize input to ensure a unique representation. @@ -307,7 +307,7 @@ def __classcall__(cls, ct, k, base_ring=ZZ, prefix=None, style="coroots", conjug sage: F1 = FusionRing('B3', 2) sage: F2 = FusionRing(CartanType('B3'), QQ(2), ZZ) - sage: F3 = FusionRing(CartanType('B3'), int(2), style="coroots") + sage: F3 = FusionRing(CartanType('B3'), int(2), style='coroots') sage: F1 is F2 and F2 is F3 True @@ -387,7 +387,7 @@ def test_braid_representation(self, max_strands=6, anyon=None): INPUT: - - ``max_strands`` -- (default: 6): maximum number of braid group strands + - ``max_strands`` -- (default: 6) maximum number of braid group strands - ``anyon`` -- (optional) run this test on this particular simple object Create a braid group representation using :meth:`get_braid_generators` @@ -442,8 +442,8 @@ def fusion_labels(self, labels=None, inject_variables=False): INPUT: - ``labels`` -- (default: ``None``) a list of strings or string - - ``inject_variables`` -- (default: ``False``) if ``True``, then - inject the variable names into the global namespace; note that + - ``inject_variables`` -- boolean (default: ``False``); if ``True``, + then inject the variable names into the global namespace; note that this could override objects already defined If ``labels`` is a list, the length of the list must equal the @@ -509,7 +509,7 @@ def field(self): r""" Return a cyclotomic field large enough to contain the `2 \ell`-th roots of unity, as well as - all the S-matrix entries. + all the `S`-matrix entries. EXAMPLES:: @@ -554,7 +554,7 @@ def fvars_field(self): EXAMPLES:: - sage: A13 = FusionRing("A1", 3, fusion_labels="a", inject_variables=True) + sage: A13 = FusionRing("A1", 3, fusion_labels='a', inject_variables=True) sage: A13.fvars_field() Cyclotomic Field of order 40 and degree 16 sage: A13.field() @@ -634,7 +634,6 @@ def get_order(self): is *not* cached. Caching of :meth:`CombinatorialFreeModule.get_order` causes inconsistent results after calling :meth:`CombinatorialFreeModule.set_order`. - """ if self._order is None: self.set_order(self.basis().keys().list()) @@ -774,7 +773,7 @@ def N_ijk(self, elt_i, elt_j, elt_k): This is the same as `N_{ij}^{k\ast}`, where `N_{ij}^k` are the structure coefficients of the ring (see :meth:`Nk_ij`), - and `k\ast`` denotes the dual element. The coefficient `N_{ijk}` + and `k\ast` denotes the dual element. The coefficient `N_{ijk}` is unchanged under permutations of the three basis vectors. EXAMPLES:: @@ -815,11 +814,11 @@ def Nk_ij(self, elt_i, elt_j, elt_k): @cached_method def s_ij(self, elt_i, elt_j, base_coercion=True): r""" - Return the element of the S-matrix of this fusion ring corresponding to + Return the element of the `S`-matrix of this fusion ring corresponding to the given elements. - This is the unnormalized S-matrix, denoted `\tilde{s}_{ij}` - in [BaKi2001]_ . To obtain the normalized S-matrix, divide by + This is the unnormalized `S`-matrix, denoted `\tilde{s}_{ij}` + in [BaKi2001]_ . To obtain the normalized `S`-matrix, divide by :meth:`global_q_dimension()` or use :meth:`S_matrix()` with the option ``unitary=True``. @@ -854,7 +853,7 @@ def s_ij(self, elt_i, elt_j, base_coercion=True): def s_ijconj(self, elt_i, elt_j, base_coercion=True): """ - Return the conjugate of the element of the S-matrix given by + Return the conjugate of the element of the `S`-matrix given by ``self.s_ij(elt_i, elt_j, base_coercion=base_coercion)``. See :meth:`s_ij`. @@ -895,12 +894,12 @@ def s_ijconj(self, elt_i, elt_j, base_coercion=True): def s_matrix(self, unitary=False, base_coercion=True): r""" - Return the S-matrix of this fusion ring. + Return the `S`-matrix of this fusion ring. OPTIONAL: - - ``unitary`` -- (default: ``False``) set to ``True`` to obtain - the unitary S-matrix + - ``unitary`` -- boolean (default: ``False``); set to ``True`` to + obtain the unitary `S`-matrix Without the ``unitary`` parameter, this is the matrix denoted `\widetilde{s}` in [BaKi2001]_. @@ -1211,9 +1210,9 @@ def _emap(self, mapper, input_args, worker_pool=None): INPUT: - - ``mapper`` -- a string specifying the name of a function defined + - ``mapper`` -- string specifying the name of a function defined in the ``fast_parallel_fusion_ring_braid_repn`` module - - ``input_args`` -- a tuple of arguments to be passed to mapper + - ``input_args`` -- tuple of arguments to be passed to mapper This method applies the mapper in parallel if a ``worker_pool`` is provided. @@ -1263,8 +1262,8 @@ def get_braid_generators(self, total_charge_anyon, n_strands, checkpoint=False, - save_results="", - warm_start="", + save_results='', + warm_start='', use_mp=True, verbose=True): r""" @@ -1277,8 +1276,8 @@ def get_braid_generators(self, - ``fusing_anyon`` -- a basis element of ``self`` - ``total_charge_anyon`` -- a basis element of ``self`` - - ``n_strands`` -- a positive integer greater than 2 - - ``checkpoint`` -- (default: ``False``) a boolean indicating + - ``n_strands`` -- positive integer greater than 2 + - ``checkpoint`` -- boolean (default: ``False``); whether the F-matrix solver should pickle checkpoints - ``save_results`` -- (optional) a string indicating the name of a file in which to pickle computed F-symbols for later use @@ -1287,10 +1286,10 @@ def get_braid_generators(self, The pickle may be a checkpoint generated by the solver, or a file containing solver results. If all F-symbols are known, we don't run the solver again. - - ``use_mp`` -- (default: ``True``) a boolean indicating whether + - ``use_mp`` -- boolean (default: ``True``); whether to use multiprocessing to speed up the computation; this is highly recommended. - - ``verbose`` -- (default: ``True``) boolean indicating whether + - ``verbose`` -- boolean (default: ``True``); whether to be verbose with the computation For more information on the optional parameters, see @@ -1398,7 +1397,7 @@ def gens_satisfy_braid_gp_rels(self, sig): EXAMPLES:: - sage: F41 = FusionRing("F4", 1, fusion_labels="f", inject_variables=True) + sage: F41 = FusionRing("F4", 1, fusion_labels='f', inject_variables=True) sage: f1*f1 f0 + f1 sage: comp, sig = F41.get_braid_generators(f1, f0, 4, verbose=False) @@ -1465,7 +1464,7 @@ def twist(self, reduced=True): INPUT: - - ``reduced`` -- (default: ``True``) boolean; if ``True`` + - ``reduced`` -- boolean (default: ``True``); if ``True`` then return the twist reduced modulo 2 EXAMPLES:: diff --git a/src/sage/algebras/fusion_rings/poly_tup_engine.pyx b/src/sage/algebras/fusion_rings/poly_tup_engine.pyx index e44fb68b836..f263e47d562 100644 --- a/src/sage/algebras/fusion_rings/poly_tup_engine.pyx +++ b/src/sage/algebras/fusion_rings/poly_tup_engine.pyx @@ -259,7 +259,7 @@ cpdef list get_variables_degrees(list eqns, int nvars): cpdef list variables(tuple eq_tup): """ - Return indices of all variables appearing in eq_tup + Return indices of all variables appearing in ``eq_tup``. EXAMPLES:: @@ -348,9 +348,9 @@ cdef dict subs_squares(dict eq_dict, KSHandler known_sq): INPUT: - - ``eq_dict`` -- a dictionary of ``(ETuple, coeff)`` pairs representing + - ``eq_dict`` -- dictionary of ``(ETuple, coeff)`` pairs representing a polynomial - - ``known_sq`` -- a dictionary of ``(int i, NumberFieldElement a)`` pairs + - ``known_sq`` -- dictionary of ``(int i, NumberFieldElement a)`` pairs such that `x_i^2 - a = 0` OUTPUT: @@ -446,8 +446,8 @@ cpdef dict compute_known_powers(max_degs, dict val_dict, one): - ``max_deg`` -- an ``ETuple`` indicating the maximal degree of each variable - - ``val_dict`` -- a dictionary of ``(var_idx, poly_tup)`` key-value pairs - - ``poly_tup`` -- a tuple of ``(ETuple, coeff)`` pairs reperesenting a + - ``val_dict`` -- dictionary of ``(var_idx, poly_tup)`` key-value pairs + - ``poly_tup`` -- tuple of ``(ETuple, coeff)`` pairs reperesenting a multivariate polynomial EXAMPLES:: diff --git a/src/sage/algebras/fusion_rings/shm_managers.pyx b/src/sage/algebras/fusion_rings/shm_managers.pyx index 40d2eb9c805..94bc24eb4ce 100644 --- a/src/sage/algebras/fusion_rings/shm_managers.pyx +++ b/src/sage/algebras/fusion_rings/shm_managers.pyx @@ -54,9 +54,9 @@ cdef class KSHandler: - ``n_slots`` -- the total number of F-symbols - ``field`` -- F-matrix's base cyclotomic field - - ``use_mp`` -- a boolean indicating whether to construct a shared - memory block to back ``self``. - - ``init_data`` -- a dictionary or :class:`KSHandler` object containing + - ``use_mp`` -- boolean indicating whether to construct a shared + memory block to back ``self`` + - ``init_data`` -- dictionary or :class:`KSHandler` object containing known squares for initialization, e.g., from a solver checkpoint - ``name`` -- the name of a shared memory object (used by child processes for attaching) @@ -177,7 +177,7 @@ cdef class KSHandler: cpdef update(self, list eqns): r""" - Update ```self``'s ``shared_memory``-backed dictionary of known + Update ``self``'s ``shared_memory``-backed dictionary of known squares. Keys are variable indices and corresponding values are the squares. @@ -301,7 +301,7 @@ cdef class KSHandler: def __reduce__(self): r""" - Provide pickling / unpickling support for ``self.`` + Provide pickling / unpickling support for ``self``. TESTS:: @@ -396,10 +396,10 @@ cdef class FvarsHandler: - ``field`` -- base field for polynomial ring - ``idx_to_sextuple`` -- map relating a single integer index to a sextuple of ``FusionRing`` elements - - ``init_data`` -- a dictionary or :class:`FvarsHandler` object containing + - ``init_data`` -- dictionary or :class:`FvarsHandler` object containing known squares for initialization, e.g., from a solver checkpoint - - ``use_mp`` -- an integer indicating the number of child processes - used for multiprocessing; if running serially, use 0. + - ``use_mp`` -- integer indicating the number of child processes + used for multiprocessing; if running serially, use 0 - ``pids_name`` -- the name of a ``ShareableList`` contaning the process ``pid``'s for every process in the pool (including the parent process) @@ -418,7 +418,7 @@ cdef class FvarsHandler: .. NOTE:: - If you ever encounter an :class:`OverflowError` when running the + If you ever encounter an :exc:`OverflowError` when running the :meth:`FMatrix.find_orthogonal_solution` solver, consider increasing the parameter ``n_bytes``. @@ -468,7 +468,7 @@ cdef class FvarsHandler: sage: n_proc = f.pool._processes sage: pids_name = f._pid_list.shm.name sage: fvars = FvarsHandler(8, f._field, f._idx_to_sextuple, use_mp=n_proc, pids_name=pids_name) - sage: TestSuite(fvars).run(skip="_test_pickling") + sage: TestSuite(fvars).run(skip='_test_pickling') sage: fvars.shm.unlink() sage: f.shutdown_worker_pool() """ @@ -710,7 +710,7 @@ cdef class FvarsHandler: def __reduce__(self): r""" - Provide pickling / unpickling support for ``self.`` + Provide pickling / unpickling support for ``self``. TESTS:: @@ -734,7 +734,7 @@ cdef class FvarsHandler: def items(self): r""" - Iterates through key-value pairs in the data structure as if it + Iterate through key-value pairs in the data structure as if it were a Python dict. As in a Python dict, the key-value pairs are yielded in no particular diff --git a/src/sage/algebras/group_algebra.py b/src/sage/algebras/group_algebra.py index 5d9f56cd6d1..eb70b0c699f 100644 --- a/src/sage/algebras/group_algebra.py +++ b/src/sage/algebras/group_algebra.py @@ -51,8 +51,8 @@ def GroupAlgebra(G, R=IntegerRing()): INPUT: - - `G` -- a group - - `R` -- (default: `\ZZ`) a ring + - ``G`` -- a group + - ``R`` -- (default: `\ZZ`) a ring EXAMPLES: diff --git a/src/sage/algebras/hecke_algebras/ariki_koike_algebra.py b/src/sage/algebras/hecke_algebras/ariki_koike_algebra.py index 3bc2e541f7e..3177185c088 100644 --- a/src/sage/algebras/hecke_algebras/ariki_koike_algebra.py +++ b/src/sage/algebras/hecke_algebras/ariki_koike_algebra.py @@ -8,7 +8,7 @@ Soon afterwards, Broué and Malle defined analogues of the Hecke algebras for all complex reflection groups -Fix non-negative integers `r` an `n`. The Ariki-Koike algebras are +Fix nonnegative integers `r` an `n`. The Ariki-Koike algebras are deformations of the group algebra of the complex reflection group `G(r, 1, n) = \ZZ / r\ZZ \wr \mathfrak{S}_n`. If `R` is a ring containing a *Hecke parameter* `q` and *cyclotomic parameters* `u_0, \ldots, u_{r-1}` then @@ -465,7 +465,6 @@ def super_categories(self): [Category of realizations of Ariki-Koike algebra of rank 5 and order 2 with q=q and u=(u0, u1, u2, u3, u4) over ..., Category of finite dimensional algebras with basis over ...] - """ return [Realizations(self.base()), self.base()._category] @@ -935,9 +934,7 @@ def _product_LTwTv(self, L, w, v): - ``w`` -- the permutation ``w`` - ``v`` -- the permutation ``v`` - OUTPUT: - - The corresponding element represented as a ``dict``. + OUTPUT: the corresponding element represented as a ``dict`` EXAMPLES:: @@ -962,8 +959,8 @@ def _product_LTwTv(self, L, w, v): c = ret[p] # We have to flip the side due to Sage's # convention for multiplying permutations - pi = p.apply_simple_reflection(i, side="left") - if p.has_descent(i, side="left"): + pi = p.apply_simple_reflection(i, side='left') + if p.has_descent(i, side='left'): iaxpy(1, {p: c * qm1, pi: c * self._q}, temp) else: iaxpy(1, {pi: c}, temp) @@ -994,7 +991,7 @@ def _product_Tw_L(self, w, L): INPUT: - ``w`` -- a permutation - - ``L`` -- a tuple `(a_1, \ldots, a_n)` + - ``L`` -- tuple `(a_1, \ldots, a_n)` EXAMPLES:: @@ -1557,8 +1554,8 @@ def product_on_basis(self, m1, m2): c = sprod[p] # We have to flip the side due to Sage's # convention for multiplying permutations - pj = p.apply_simple_reflection(j, side="left") - if p.has_descent(j, side="left"): + pj = p.apply_simple_reflection(j, side='left') + if p.has_descent(j, side='left'): iaxpy(1, {p: c * qm1, pj: c * self._q}, temp) else: iaxpy(1, {pj: c}, temp) @@ -1602,9 +1599,7 @@ def _T0_polynomial(self): r""" Return `p` such that `T0^{r-1} - p = \prod_{i=0}^{r-1} (T_0 - u_i)`. - OUTPUT: - - A ``dict`` representing the polynomial `p`. + OUTPUT: a ``dict`` representing the polynomial `p` EXAMPLES:: diff --git a/src/sage/algebras/hecke_algebras/cubic_hecke_algebra.py b/src/sage/algebras/hecke_algebras/cubic_hecke_algebra.py index 4f2a604aa8b..d96b05f43a8 100644 --- a/src/sage/algebras/hecke_algebras/cubic_hecke_algebra.py +++ b/src/sage/algebras/hecke_algebras/cubic_hecke_algebra.py @@ -314,20 +314,20 @@ def matrix(self, subdivide=False, representation_type=None, original=False): INPUT: - - ``subdivide`` -- boolean (default: ``False``): this boolean is passed + - ``subdivide`` -- boolean (default: ``False``); this boolean is passed to the block_matrix function - ``representation_type`` -- instance of enum :class:`RepresentationType`; this can be obtained by the attribute :attr:`CubicHeckeAlgebra.repr_type` of ``self``; the following values are possible: - - ``RegularLeft`` -- (regular left repr. from the above URL) - - ``RegularRight`` -- (regular right repr. from the above URL) + - ``RegularLeft`` -- (regular left repr. from the above URL) + - ``RegularRight`` -- (regular right repr. from the above URL) - ``SplitIrredChevie`` -- (split irred. repr. via CHEVIE) - - ``SplitIrredMarin`` -- (split irred. repr. from the above URL) + - ``SplitIrredMarin`` -- (split irred. repr. from the above URL) - default: ``SplitIrredChevie`` taken if GAP3 and CHEVIE are installed on the system, otherwise the default will be ``SplitIrredMarin`` - - ``original`` -- boolean (default: ``False``): if set to true the base + - ``original`` -- boolean (default: ``False``); if set to ``True`` the base ring of the matrix will be the generic base_ring resp. generic extension ring (for the split versions) of the parent of ``self`` @@ -660,13 +660,13 @@ class CubicHeckeAlgebra(CombinatorialFreeModule): - ``names`` -- string containing the names of the generators as images of the braid group generators - - ``cubic_equation_parameters`` -- tuple ``(u, v, w)`` of three elements + - ``cubic_equation_parameters`` -- tuple ``(u, v, w)`` of three elements in an integral domain used as coefficients in the cubic equation. If this argument is given the base ring will be set to the common parent of ``u, v, w``. In addition a conversion map from the generic base ring is supplied. This keyword can also be used to change the variable names of the generic base ring (see example 3 below) - - ``cubic_equation_roots`` -- tuple ``(a, b, c)`` of three elements in an + - ``cubic_equation_roots`` -- tuple ``(a, b, c)`` of three elements in an integral domain which stand for the roots of the cubic equation. If this argument is given the extension ring will be set to the common parent of ``a, b, c``. In addition a conversion map from the generic extension ring @@ -1125,11 +1125,9 @@ def check_base_ring_embedding(base_ring_embedding): ############################################################################ def _repr_(self): r""" - Return a string representation + Return a string representation. - OUTPUT: - - String describing ``self`` + OUTPUT: string describing ``self`` TESTS:: @@ -1577,7 +1575,7 @@ def product_on_basis(self, g1, g2): ############################################################################ def _basis_tietze(self): r""" - Return the complete finite sub basis as list of Tietze tuples + Return the complete finite sub basis as list of Tietze tuples. EXAMPLES:: @@ -1944,7 +1942,7 @@ def _braid_image_to_filecache(self, braid_tietze, braid_image_vect): INPUT: - - ``braid_tietze`` -- braid in Tietze form + - ``braid_tietze`` -- braid in Tietze form - ``braid_image_vect`` -- image of the given braid in ``self`` in vector representation @@ -1982,9 +1980,7 @@ def _braid_image(self, braid): - ``braid`` -- :class:`~sage.groups.braid.Braid` whose image in ``self`` should be calculated - OUTPUT: - - An instance of the element class of ``self``. + OUTPUT: an instance of the element class of ``self`` EXAMPLES:: @@ -2026,9 +2022,7 @@ def _braid_image_from_reduced_powers(self, braid_tietze): repetitions occur among the entries (i.e. ``(1, 1)`` is not allowed but ``(1, -2, 1)`` is) - OUTPUT: - - The image of the braid as an element of ``self``. + OUTPUT: the image of the braid as an element of ``self`` EXAMPLES:: @@ -2216,9 +2210,7 @@ def _braid_image_by_basis_extension(self, braid_tietze): ``self`` should be computed; he generator exponents in the braid word are assumed to be ``1`` or ``-1`` - OUTPUT: - - An instance of the element class of ``self``. + OUTPUT: an instance of the element class of ``self`` EXAMPLES:: @@ -2521,9 +2513,7 @@ def _cubic_braid_append_to_basis(self, cubic_braid): - ``cubic_braid`` -- :class:`~sage.groups.cubic_braid.CubicBraid` whose image in ``self`` should be appended - OUTPUT: - - The new monomial of ``self``. + OUTPUT: the new monomial of ``self`` EXAMPLES:: @@ -2538,7 +2528,6 @@ def _cubic_braid_append_to_basis(self, cubic_braid): c3*c0 sage: CHA5._basis_extension [[4], [-4], [4, 1]] - """ cbTietze = list(cubic_braid.Tietze()) order = self.get_order() @@ -2573,9 +2562,7 @@ def _cubic_braid_basis_tuple(self, cubic_braid): - ``cubic_braid`` -- :class:`~sage.groups.cubic_braid.CubicBraid` - OUTPUT: - - A tuple from the basis representing the cubic braid. + OUTPUT: a tuple from the basis representing the cubic braid EXAMPLES:: @@ -2617,7 +2604,7 @@ def _cubic_braid_image(self, cubic_braid, check=True): INPUT: - - ``cubic_braid`` -- :class:`~sage.groups.cubic_braid.CubicBraid` + - ``cubic_braid`` -- :class:`~sage.groups.cubic_braid.CubicBraid` whose image in ``self`` should be returned - ``check`` -- boolean (default: ``True``); check if the given cubic braid is already registered in the finite sub basis; if set to @@ -2690,9 +2677,7 @@ def _markov_trace_module(self, extended=False, field_embedding=False): generic extension ring of ``self``. The keyword is meaningless if ``extended=False``. - OUTPUT: - - A :class:`~sage.combinat.free_module.CombinatorialFreeModule`. + OUTPUT: a :class:`~sage.combinat.free_module.CombinatorialFreeModule` EXAMPLES:: @@ -2984,7 +2969,7 @@ def cubic_equation(self, var='h', as_coefficients=False, generic=False): INPUT: - - ``var`` -- string (default ``h``) setting the indeterminate of the + - ``var`` -- string (default: ``'h'``); setting the indeterminate of the equation - ``as_coefficients`` -- boolean (default: ``False``); if set to ``True`` the list of coefficients is returned @@ -3033,9 +3018,7 @@ def cubic_equation_roots(self, generic=False): - ``generic`` -- boolean (default: ``False``); if set to ``True`` the roots are returned as elements of the generic extension ring - OUTPUT: - - A triple consisting of the roots. + OUTPUT: a triple consisting of the roots EXAMPLES:: @@ -3064,9 +3047,7 @@ def cubic_equation_parameters(self, generic=False): - ``generic`` -- boolean (default: ``False``); if set to ``True`` the coefficients are returned as elements of the generic base ring - OUTPUT: - - A tripple consisting of the coefficients. + OUTPUT: a tripple consisting of the coefficients EXAMPLES:: @@ -3248,13 +3229,11 @@ def cubic_hecke_subalgebra(self, nstrands=None): INPUT: - - ``nstrands`` -- integer at least 1 and at most :meth:`strands` giving + - ``nstrands`` -- integer at least 1 and at most :meth:`strands` giving the number of strands for the subgroup; the default is one strand less than ``self`` has - OUTPUT: - - An instance of this class realizing the sub-algebra. + OUTPUT: an instance of this class realizing the sub-algebra EXAMPLES:: @@ -3499,7 +3478,7 @@ def characters(self, irr=None, original=True): - ``irr`` -- (optional) instance of :class:`AbsIrreducibeRep` selecting the irreducible representation corresponding to the character; if not given a list of all characters is returned - - ``original`` -- (default: ``True``) see description above + - ``original`` -- boolean (default: ``True``); see description above OUTPUT: diff --git a/src/sage/algebras/hecke_algebras/cubic_hecke_base_ring.py b/src/sage/algebras/hecke_algebras/cubic_hecke_base_ring.py index 90d6657d309..538d0d9fa1f 100644 --- a/src/sage/algebras/hecke_algebras/cubic_hecke_base_ring.py +++ b/src/sage/algebras/hecke_algebras/cubic_hecke_base_ring.py @@ -194,7 +194,7 @@ class CubicHeckeExtensionRing(LaurentPolynomialRing_mpair): realized as splitting ring via the ``as_splitting_algebra`` method - ``third_unity_root_name`` -- string (default: ``'e3'``); for setting the name of the third root if unity of ``self`` - - ``markov_trace_version`` -- boolean (default: ``False``) if this is + - ``markov_trace_version`` -- boolean (default: ``False``); if this is set to ``True`` then ``self`` contains one invertible indeterminate in addition which is meant to represent the writhe factor of a Markov trace on the cubic Hecke algebra and which default name is ``s`` @@ -442,7 +442,7 @@ def _convert_from_gap3_mvp(self, mvp_expression): INPUT: - - ``string`` -- string produced via GAP3 interface and containing + - ``string`` -- string produced via GAP3 interface and containing Jean Michel's ``MVP`` (multivariate polynomials) EXAMPLES:: @@ -545,9 +545,7 @@ def mirror_involution(self): considered as `\ZZ`-algebra. The base ring elements are transformed by this automorphism. - OUTPUT: - - The involution as automorphism of ``self``. + OUTPUT: the involution as automorphism of ``self`` EXAMPLES:: @@ -592,7 +590,7 @@ def mirror_involution(self): def create_specialization(self, im_cubic_equation_roots, im_writhe_parameter=None, var='T', third_unity_root_name='E3'): r""" Return an appropriate ring containing the elements from the list - ``im_cubic_equation_roots`` defining a conversion map from self mapping + ``im_cubic_equation_roots`` defining a conversion map from ``self`` mapping the cubic equation roots of ``self`` to ``im_cubic_equation_roots``. INPUT: @@ -806,7 +804,7 @@ def field_embedding(self, characteristic=0): INPUT: - - ``characteristic`` -- integer (default: ``0``); the characteristic + - ``characteristic`` -- integer (default: `0`); the characteristic of the field EXAMPLES:: @@ -941,7 +939,7 @@ class CubicHeckeRingOfDefinition(Localization): - ``ring_of_definition`` -- (optional) a :class:`CubicHeckeRingOfDefinition` to specify the generic cubic Hecke base ring over which ``self`` may be realized as splitting ring via the ``as_splitting_algebra`` method - - ``markov_trace_version`` -- boolean (default: ``False``) if this is + - ``markov_trace_version`` -- boolean (default: ``False``); if this is set to ``True`` then ``self`` contains one invertible indeterminate in addition which is meant to represent the writhe factor of a Markov trace on the cubic Hecke algebra and which default name is ``s`` @@ -1133,9 +1131,7 @@ def mirror_involution(self): considered as `\ZZ`-algebra. The base ring elements are transformed by this automorphism. - OUTPUT: - - The involution as automorphism of ``self``. + OUTPUT: the involution as automorphism of ``self`` EXAMPLES:: diff --git a/src/sage/algebras/hecke_algebras/cubic_hecke_matrix_rep.py b/src/sage/algebras/hecke_algebras/cubic_hecke_matrix_rep.py index c0587117753..9964fa4e287 100644 --- a/src/sage/algebras/hecke_algebras/cubic_hecke_matrix_rep.py +++ b/src/sage/algebras/hecke_algebras/cubic_hecke_matrix_rep.py @@ -61,7 +61,7 @@ class RepresentationType(Enum): r""" Enum class to select a representation type for the cubic Hecke algebra. - - ``RegularLeft`` -- left regular representations + - ``RegularLeft`` -- left regular representations - ``RegularRight`` -- right regular representations - ``SplitIrredMarin`` -- split irreducible representations obtained from Ivan Marin's data @@ -551,7 +551,7 @@ def reduce_to_irr_block(self, irr): OUTPUT: - An instance of :class:`Matrix_generic_dense` with exactly one non zero block + An instance of :class:`Matrix_generic_dense` with exactly one nonzero block according to ``irr``. EXAMPLES:: @@ -586,7 +586,7 @@ class CubicHeckeMatrixSpace(MatrixSpace): INPUT: - - ``cubic_hecke_algebra`` -- (optional) + - ``cubic_hecke_algebra`` -- (optional) :class:`~sage.algebras.hecke_algebras.cubic_hecke_algebra.CubicHeckeAlgebra` must be given if ``element`` fails to be an instance of its element class - ``representation_type`` -- (default: ``RepresentationType.SplitIrredChevie``) @@ -594,7 +594,7 @@ class CubicHeckeMatrixSpace(MatrixSpace): - ``subdivide`` -- boolean (default: ``False``); whether or not to subdivide the resulting matrices - - ``original`` -- boolean (default: ``False``) if ``True``, the matrix + - ``original`` -- boolean (default: ``False``); if ``True``, the matrix will have coefficients in the generic base / extension ring EXAMPLES:: @@ -816,9 +816,7 @@ def _specialize_matrix(self, mat): - ``mat`` -- matrix over the original base ring - OUTPUT: - - ``mat`` over the base ring of ``self`` + OUTPUT: matrix over the base ring of ``self`` EXAMPLES:: diff --git a/src/sage/algebras/iwahori_hecke_algebra.py b/src/sage/algebras/iwahori_hecke_algebra.py index a16ff3d5dda..b4dc71825af 100644 --- a/src/sage/algebras/iwahori_hecke_algebra.py +++ b/src/sage/algebras/iwahori_hecke_algebra.py @@ -128,11 +128,8 @@ class IwahoriHeckeAlgebra(Parent, UniqueRepresentation): - ``W`` -- a Coxeter group or Cartan type - ``q1`` -- a parameter - - OPTIONAL ARGUMENTS: - - - ``q2`` -- (default ``-1``) another parameter - - ``base_ring`` -- (default ``q1.parent()``) a ring containing ``q1`` + - ``q2`` -- (default: ``-1``) another parameter + - ``base_ring`` -- (default: ``q1.parent()``) a ring containing ``q1`` and ``q2`` The Iwahori-Hecke algebra [Iwa1964]_ is a deformation of the group algebra of @@ -720,7 +717,7 @@ def __getitem__(self, i): .. WARNING:: - If `i`` is not a reduced expression then the basis element + If ``i`` is not a reduced expression then the basis element indexed by the corresponding element of the algebra is returned rather than the corresponding product of the generators:: @@ -1240,7 +1237,7 @@ def __init__(self, algebra, prefix=None): EXAMPLES:: sage: H = IwahoriHeckeAlgebra("G2",1) - sage: t = H.T(prefix="t") + sage: t = H.T(prefix='t') sage: t[1] t[1] """ @@ -1356,7 +1353,7 @@ class T(_Basis): sage: w0 = T(H.coxeter_group().long_element()) sage: w0 T[1,2,3,1,2,1] - sage: T = H.T(prefix="s") + sage: T = H.T(prefix='s') sage: T.an_element() s[1,2,3] + 2*s[1] + 3*s[2] + 1 @@ -1441,7 +1438,7 @@ def inverse_generators(self): sage: U1*T1,T1*U1 (1, 1) sage: P1. = LaurentPolynomialRing(QQ) - sage: H1 = IwahoriHeckeAlgebra("A2", q, base_ring=P1).T(prefix="V") + sage: H1 = IwahoriHeckeAlgebra("A2", q, base_ring=P1).T(prefix='V') sage: V1,V2 = H1.algebra_generators() sage: W1,W2 = H1.inverse_generators() sage: [W1,W2] @@ -1469,7 +1466,7 @@ def product_on_basis(self, w1, w2): result = self.product_by_generator(result, i) return result - def product_by_generator_on_basis(self, w, i, side="right"): + def product_by_generator_on_basis(self, w, i, side='right'): r""" Return the product `T_w T_i` (resp. `T_i T_w`) if ``side`` is ``'right'`` (resp. ``'left'``). @@ -1498,7 +1495,7 @@ def product_by_generator_on_basis(self, w, i, side="right"): sage: s1,s2 = H.coxeter_group().simple_reflections() sage: [T.product_by_generator_on_basis(w, 1) for w in [s1,s2,s1*s2]] [(q-1)*T[1] + q, T[2,1], T[1,2,1]] - sage: [T.product_by_generator_on_basis(w, 1, side="left") for w in [s1,s2,s1*s2]] + sage: [T.product_by_generator_on_basis(w, 1, side='left') for w in [s1,s2,s1*s2]] [(q-1)*T[1] + q, T[1,2], (q-1)*T[1,2] + q*T[2]] """ wi = w.apply_simple_reflection(i, side=side) @@ -1510,7 +1507,7 @@ def product_by_generator_on_basis(self, w, i, side="right"): else: return self.monomial(wi) - def product_by_generator(self, x, i, side="right"): + def product_by_generator(self, x, i, side='right'): r""" Return `T_i \cdot x`, where `T_i` is the `i`-th generator. This is coded individually for use in ``x._mul_()``. @@ -1704,11 +1701,11 @@ class Element(CombinatorialFreeModule.Element): (q-1)*T[1] + q sage: R. = QQ[] - sage: H = IwahoriHeckeAlgebra("A2", q1, q2=q2).T(prefix="x") + sage: H = IwahoriHeckeAlgebra("A2", q1, q2=q2).T(prefix='x') sage: sum(H.algebra_generators())^2 x[2,1] + x[1,2] + (q1+q2)*x[1] + (q1+q2)*x[2] + (-2*q1*q2) - sage: H = IwahoriHeckeAlgebra("A2", q1, q2=q2).T(prefix="t") + sage: H = IwahoriHeckeAlgebra("A2", q1, q2=q2).T(prefix='t') sage: t1,t2 = H.algebra_generators() sage: (t1-t2)^3 (q1^2-q1*q2+q2^2)*t[1] + (-q1^2+q1*q2-q2^2)*t[2] @@ -2514,7 +2511,7 @@ def __init__(self, IHAlgebra, prefix=None): # Define and register coercions from the A basis to the T basis and back again from_A_to_T = self.module_morphism(self.to_T_basis, codomain=IHAlgebra.T(), - triangular="lower", key=sorting_key, + triangular='lower', key=sorting_key, category=self.category()) from_A_to_T.register_as_coercion() from_T_to_A = ~from_A_to_T @@ -2646,7 +2643,7 @@ def __init__(self, IHAlgebra, prefix=None): # Define and register coercions from the B basis to the T basis and back again from_B_to_T = self.module_morphism(self.to_T_basis, codomain=IHAlgebra.T(), - triangular="lower", key=sorting_key, + triangular='lower', key=sorting_key, category=self.category()) from_B_to_T.register_as_coercion() from_T_to_B = ~from_B_to_T diff --git a/src/sage/algebras/jordan_algebra.py b/src/sage/algebras/jordan_algebra.py index adbcdd53eee..0b6fc0111bf 100644 --- a/src/sage/algebras/jordan_algebra.py +++ b/src/sage/algebras/jordan_algebra.py @@ -426,7 +426,7 @@ def _latex_(self): def __bool__(self) -> bool: """ - Return if ``self`` is non-zero. + Return if ``self`` is nonzero. EXAMPLES:: @@ -583,9 +583,9 @@ def monomial_coefficients(self, copy=True): INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally - represented by a dictionary ``d``, then make a copy of ``d``; - if ``False``, then this can cause undesired behavior by + - ``copy`` -- boolean (default: ``True``); if ``self`` is + internally represented by a dictionary ``d``, then make a copy of + ``d``; if ``False``, then this can cause undesired behavior by mutating ``d`` EXAMPLES:: @@ -851,7 +851,7 @@ def _latex_(self): def __bool__(self) -> bool: """ - Return if ``self`` is non-zero. + Return if ``self`` is nonzero. TESTS:: @@ -1571,7 +1571,7 @@ def _unicode_art_(self): def __bool__(self) -> bool: """ - Return if ``self`` is non-zero. + Return if ``self`` is nonzero. TESTS:: diff --git a/src/sage/algebras/letterplace/free_algebra_element_letterplace.pyx b/src/sage/algebras/letterplace/free_algebra_element_letterplace.pyx index e2ce4445881..5b99c87dd17 100644 --- a/src/sage/algebras/letterplace/free_algebra_element_letterplace.pyx +++ b/src/sage/algebras/letterplace/free_algebra_element_letterplace.pyx @@ -29,7 +29,8 @@ poly_reduce = singular_function("NF") # Free algebra elements cdef class FreeAlgebraElement_letterplace(AlgebraElement): """ - Weighted homogeneous elements of a free associative unital algebra (letterplace implementation) + Weighted homogeneous elements of a free associative unital algebra + (letterplace implementation). EXAMPLES:: @@ -60,17 +61,16 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): z*z*y*x sage: ((x*y)^3).degree() 9 - """ def __init__(self, A, x, check=True): """ INPUT: - - A free associative unital algebra in letterplace implementation, `A`. - - A homogeneous polynomial that can be coerced into the currently - used polynomial ring of `A`. - - ``check`` (optional bool, default ``True``): Do not attempt the - above coercion (for internal use only). + - ``A`` - a free associative unital algebra in letterplace implementation + - ``x`` -- a homogeneous polynomial that can be coerced into the currently + used polynomial ring of `A` + - ``check`` -- boolean (default: ``True``); do not attempt the + above coercion (for internal use only) TESTS:: @@ -85,7 +85,6 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): -x*y + y*x sage: loads(dumps(p)) == p True - """ cdef FreeAlgebra_letterplace P = A if check: @@ -131,7 +130,7 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): def __iter__(self): """ - Iterates over the pairs "tuple of exponents, coefficient". + Iterate over the pairs "tuple of exponents, coefficient". EXAMPLES:: @@ -401,7 +400,7 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): def lm_divides(self, FreeAlgebraElement_letterplace p): """ - Tell whether or not the leading monomial of self divides the + Tell whether or not the leading monomial of ``self`` divides the leading monomial of another element. .. NOTE:: @@ -468,7 +467,6 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): sage: F. = FreeAlgebra(QQ, implementation='letterplace') sage: -(3*x*y+2*z^2) -3*x*y - 2*z*z - """ return FreeAlgebraElement_letterplace(self._parent, -self._poly, check=False) @@ -586,7 +584,6 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): sage: F. = FreeAlgebra(QQ, implementation='letterplace', degrees=[2,1,3]) sage: (x*y+z)*z # indirect doctest x*y*z + z*z - """ cdef FreeAlgebraElement_letterplace left = self cdef FreeAlgebraElement_letterplace right = other @@ -644,9 +641,7 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): the commutative polynomial ring that is currently used to implement the multiplication in the free algebra. - OUTPUT: - - The twosided reduction of this element by the argument. + OUTPUT: the twosided reduction of this element by the argument .. NOTE:: @@ -713,12 +708,10 @@ cdef class FreeAlgebraElement_letterplace(AlgebraElement): INPUT: - A twosided homogeneous ideal `I` of the parent `F` of - this element, `x`. - - OUTPUT: + - ``I`` -- a twosided homogeneous ideal of the parent `F` of + this element, `x` - The normal form of `x` wrt. `I`. + OUTPUT: the normal form of `x` wrt. `I` .. NOTE:: diff --git a/src/sage/algebras/letterplace/free_algebra_letterplace.pyx b/src/sage/algebras/letterplace/free_algebra_letterplace.pyx index 0072fbd1a78..7a57922d24a 100644 --- a/src/sage/algebras/letterplace/free_algebra_letterplace.pyx +++ b/src/sage/algebras/letterplace/free_algebra_letterplace.pyx @@ -149,8 +149,8 @@ cdef MPolynomialRing_libsingular make_letterplace_ring(base_ring, blocks): INPUT: - - ``base_ring``: A multivariate polynomial ring. - - ``blocks``: The number of blocks to be formed. + - ``base_ring`` -- a multivariate polynomial ring + - ``blocks`` -- the number of blocks to be formed OUTPUT: @@ -191,7 +191,7 @@ cdef MPolynomialRing_libsingular make_letterplace_ring(base_ring, blocks): T += T0 names.extend([x + '_' + str(i) for x in names0]) return PolynomialRing(base_ring.base_ring(), names, order=T, - implementation="singular") + implementation='singular') ##################### @@ -234,9 +234,7 @@ cdef class FreeAlgebra_letterplace(Parent): A multivariate polynomial ring of type :class:`~sage.rings.polynomial.multipolynomial_libsingular.MPolynomialRing_libsingular`. - OUTPUT: - - The free associative version of the given commutative ring. + OUTPUT: the free associative version of the given commutative ring .. NOTE:: @@ -328,11 +326,9 @@ cdef class FreeAlgebra_letterplace(Parent): INPUT: - - `i` -- an integer - - OUTPUT: + - ``i`` -- integer - The generator with index `i` + OUTPUT: the generator with index `i` EXAMPLES:: @@ -654,8 +650,8 @@ cdef class FreeAlgebra_letterplace(Parent): INPUT: - - ``g`` -- a list of elements of this free algebra. - - ``d`` -- an integer. + - ``g`` -- list of elements of this free algebra + - ``d`` -- integer OUTPUT: @@ -701,14 +697,14 @@ cdef class FreeAlgebra_letterplace(Parent): # Coercion cpdef _coerce_map_from_(self, S): """ - A ring ``R`` coerces into self, if + A ring ``R`` coerces into ``self``, if: - it coerces into the current polynomial ring, or - it is a free graded algebra in letterplace implementation, the generator names of ``R`` are a proper subset of the - generator names of self, the degrees of equally named + generator names of ``self``, the degrees of equally named generators are equal, and the base ring of ``R`` coerces - into the base ring of self. + into the base ring of ``self``. TESTS: @@ -766,8 +762,8 @@ cdef class FreeAlgebra_letterplace(Parent): # # INPUT: # -# - ``degree`` -- the maximal degree of the output (default 2). -# - ``terms`` -- the maximal number of terms of the output (default 5). +# - ``degree`` -- the maximal degree of the output (default: 2) +# - ``terms`` -- the maximal number of terms of the output (default: 5) # # NOTE: # @@ -788,12 +784,12 @@ cdef class FreeAlgebra_letterplace(Parent): INPUT: - - A dictionary. Keys: tuples of exponents. Values: - The coefficients of the corresponding monomial - in the to-be-created element. - - ``check`` (optional bool, default ``True``): - This is forwarded to the initialisation of - :class:`~sage.algebras.letterplace.free_algebra_element_letterplace.FreeAlgebraElement_letterplace`. + - ``D`` -- dictionary; keys: tuples of exponents, values: + the coefficients of the corresponding monomial + in the to-be-created element + - ``check`` -- boolean (default: ``True``); + this is forwarded to the initialisation of + :class:`~sage.algebras.letterplace.free_algebra_element_letterplace.FreeAlgebraElement_letterplace` TESTS: diff --git a/src/sage/algebras/letterplace/letterplace_ideal.pyx b/src/sage/algebras/letterplace/letterplace_ideal.pyx index eeebf4422a4..77d0107ba07 100644 --- a/src/sage/algebras/letterplace/letterplace_ideal.pyx +++ b/src/sage/algebras/letterplace/letterplace_ideal.pyx @@ -157,16 +157,16 @@ class LetterplaceIdeal(Ideal_nc): sage: (z*I.0-x*y*z).normal_form(I) -y*x*z + z*z """ - def __init__(self, ring, gens, coerce=True, side="twosided"): + def __init__(self, ring, gens, coerce=True, side='twosided'): """ INPUT: - - ``ring``: A free algebra in letterplace implementation. - - ``gens``: List, tuple or sequence of generators. - - ``coerce`` (optional bool, default ``True``): - Shall ``gens`` be coerced first? - - ``side``: optional string, one of ``"twosided"`` (default), - ``"left"`` or ``"right"``. Determines whether the ideal + - ``ring`` -- a free algebra in letterplace implementation + - ``gens`` -- list, tuple or sequence of generators + - ``coerce`` -- boolean (default: ``True``); whether ``gens`` shall be + coerced first + - ``side`` -- string; one of ``'twosided'`` (default), + ``'left'`` or ``'right'``. Determines whether the ideal is a left, right or twosided ideal. Groebner bases or only supported in the twosided case. @@ -189,7 +189,6 @@ class LetterplaceIdeal(Ideal_nc): running ._test_new() . . . pass running ._test_not_implemented_methods() . . . pass running ._test_pickling() . . . pass - """ Ideal_nc.__init__(self, ring, gens, coerce=coerce, side=side) self.__GB = self @@ -201,7 +200,7 @@ class LetterplaceIdeal(Ideal_nc): INPUT: - - ``degbound`` (optional integer, or Infinity): If it is provided, + - ``degbound`` -- (optional) integer or Infinity; if it is provided, a Groebner basis at least out to that degree is returned. By default, the current degree bound of the underlying ring is used. @@ -358,8 +357,8 @@ class LetterplaceIdeal(Ideal_nc): INPUT: - - ``G``: A list or tuple of elements, an ideal, - the ambient algebra, or a single element. + - ``G`` -- a list or tuple of elements, an ideal, + the ambient algebra, or a single element OUTPUT: diff --git a/src/sage/algebras/lie_algebras/classical_lie_algebra.py b/src/sage/algebras/lie_algebras/classical_lie_algebra.py index d1b0a97fe45..ebe892d3436 100644 --- a/src/sage/algebras/lie_algebras/classical_lie_algebra.py +++ b/src/sage/algebras/lie_algebras/classical_lie_algebra.py @@ -978,7 +978,7 @@ def __init__(self, R): We skip the not implemented methods test as it takes too much time:: - sage: TestSuite(g).run(skip="_test_not_implemented_methods") # long time + sage: TestSuite(g).run(skip='_test_not_implemented_methods') # long time """ ct = CartanType(['E', 8]) g = LieAlgebraChevalleyBasis(R, ct) @@ -1642,7 +1642,7 @@ def __classcall_private__(cls, R, cartan_type, epsilon=None): raise ValueError("not a valid Dynkin orientation") else: from sage.graphs.graph import Graph - G = Graph(epsilon, multiedges=True, loops=True, format="list_of_edges") + G = Graph(epsilon, multiedges=True, loops=True, format='list_of_edges') if (G.has_multiple_edges() or G.has_loops() or cartan_type.dynkin_diagram().to_undirected() != G.to_simple()): raise ValueError("not a valid Dynkin orientation") @@ -2098,8 +2098,8 @@ def lie_algebra_generators(self, str_keys=False): INPUT: - - ``str_keys`` -- (default: ``False``) set to ``True`` to have the - indices indexed by strings instead of simple (co)roots + - ``str_keys`` -- boolean (default: ``False``); set to ``True`` to have + the indices indexed by strings instead of simple (co)roots EXAMPLES:: @@ -2197,7 +2197,7 @@ def highest_root_basis_elt(self, pos=True): INPUT: - - ``pos`` -- (default: ``True``) if ``True``, then return + - ``pos`` -- boolean (default: ``True``); if ``True``, then return `e_{\theta}`, otherwise return `f_{\theta}` EXAMPLES:: diff --git a/src/sage/algebras/lie_algebras/examples.py b/src/sage/algebras/lie_algebras/examples.py index 7c3f373f7cd..f2db23d445b 100644 --- a/src/sage/algebras/lie_algebras/examples.py +++ b/src/sage/algebras/lie_algebras/examples.py @@ -211,7 +211,7 @@ def affine_transformations_line(R, names=['X', 'Y'], representation='bracket'): sage: L[X, Y] == Y True sage: TestSuite(L).run() - sage: L = lie_algebras.affine_transformations_line(QQ, representation="matrix") + sage: L = lie_algebras.affine_transformations_line(QQ, representation='matrix') sage: X, Y = L.lie_algebra_generators() sage: L[X, Y] == Y True @@ -264,7 +264,7 @@ def abelian(R, names=None, index_set=None): return AbelianLieAlgebra(R, names=names, index_set=index_set) -def Heisenberg(R, n, representation="structure"): +def Heisenberg(R, n, representation='structure'): """ Return the rank ``n`` Heisenberg algebra in the given representation. @@ -272,10 +272,11 @@ def Heisenberg(R, n, representation="structure"): - ``R`` -- the base ring - ``n`` -- the rank (a nonnegative integer or infinity) - - ``representation`` -- (default: "structure") can be one of the following: + - ``representation`` -- (default: ``'structure'``) can be one of the + following: - - ``"structure"`` -- using structure coefficients - - ``"matrix"`` -- using matrices + - ``'structure'`` -- using structure coefficients + - ``'matrix'`` -- using matrices EXAMPLES:: @@ -322,7 +323,7 @@ def pwitt(R, p): INPUT: - ``R`` -- the base ring - - ``p`` -- a positive integer that is `0` in ``R`` + - ``p`` -- positive integer that is `0` in `R` EXAMPLES:: diff --git a/src/sage/algebras/lie_algebras/free_lie_algebra.py b/src/sage/algebras/lie_algebras/free_lie_algebra.py index f0decd311c3..f5217231263 100644 --- a/src/sage/algebras/lie_algebras/free_lie_algebra.py +++ b/src/sage/algebras/lie_algebras/free_lie_algebra.py @@ -496,9 +496,7 @@ def _generate_hall_set(self, k): """ Generate the Hall set of grade ``k``. - OUTPUT: - - A sorted tuple of :class:`GradedLieBracket` elements. + OUTPUT: a sorted tuple of :class:`GradedLieBracket` elements EXAMPLES:: diff --git a/src/sage/algebras/lie_algebras/heisenberg.py b/src/sage/algebras/lie_algebras/heisenberg.py index 5e4dd1c90ae..de4a6b27562 100644 --- a/src/sage/algebras/lie_algebras/heisenberg.py +++ b/src/sage/algebras/lie_algebras/heisenberg.py @@ -227,7 +227,7 @@ def n(self): sage: H = lie_algebras.Heisenberg(QQ, 3) sage: H.n() 3 - sage: H = lie_algebras.Heisenberg(QQ, 3, representation="matrix") + sage: H = lie_algebras.Heisenberg(QQ, 3, representation='matrix') sage: H.n() 3 """ @@ -313,7 +313,7 @@ def _coerce_map_from_(self, H): EXAMPLES:: sage: HB = lie_algebras.Heisenberg(QQ, 3) - sage: HM = lie_algebras.Heisenberg(QQ, 3, representation="matrix") + sage: HM = lie_algebras.Heisenberg(QQ, 3, representation='matrix') sage: HB.has_coerce_map_from(HM) True sage: HM.has_coerce_map_from(HB) @@ -336,7 +336,7 @@ def _coerce_map_from_(self, H): True sage: HB(HZ.p(2)) p2 - sage: HZ = lie_algebras.Heisenberg(ZZ, 2, representation="matrix") + sage: HZ = lie_algebras.Heisenberg(ZZ, 2, representation='matrix') sage: HB.has_coerce_map_from(HZ) True sage: HB(HZ.p(2)) @@ -548,7 +548,7 @@ def _coerce_map_from_(self, H): True sage: phi(HZ.p(3)).leading_coefficient().parent() Rational Field - sage: HF = lie_algebras.Heisenberg(QQ, 3, representation="matrix") + sage: HF = lie_algebras.Heisenberg(QQ, 3, representation='matrix') sage: H.has_coerce_map_from(HF) True sage: H(HF.p(2)) @@ -631,7 +631,7 @@ class HeisenbergAlgebra_matrix(HeisenbergAlgebra_fd, LieAlgebraFromAssociative): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 1, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 1, representation='matrix') sage: p = L.p(1) sage: q = L.q(1) sage: z = L.bracket(p, q); z @@ -643,7 +643,7 @@ class HeisenbergAlgebra_matrix(HeisenbergAlgebra_fd, LieAlgebraFromAssociative): sage: L.dimension() 3 - sage: L = lie_algebras.Heisenberg(QQ, 2, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 2, representation='matrix') sage: sorted(dict(L.basis()).items()) [( [0 1 0 0] @@ -676,7 +676,7 @@ class HeisenbergAlgebra_matrix(HeisenbergAlgebra_fd, LieAlgebraFromAssociative): 'z', [0 0 0 0] )] - sage: L = lie_algebras.Heisenberg(QQ, 0, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 0, representation='matrix') sage: sorted(dict(L.basis()).items()) [( [0 1] @@ -697,7 +697,7 @@ def __init__(self, R, n): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 2, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 2, representation='matrix') sage: TestSuite(L).run() """ HeisenbergAlgebra_fd.__init__(self, n) @@ -718,7 +718,7 @@ def _repr_(self): EXAMPLES:: - sage: lie_algebras.Heisenberg(QQ, 3, representation="matrix") + sage: lie_algebras.Heisenberg(QQ, 3, representation='matrix') Heisenberg algebra of rank 3 over Rational Field """ return "Heisenberg algebra of rank {} over {}".format(self._n, self.base_ring()) @@ -729,7 +729,7 @@ def p(self, i): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 1, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 1, representation='matrix') sage: L.p(1) [0 1 0] [0 0 0] @@ -743,7 +743,7 @@ def q(self, i): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 1, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 1, representation='matrix') sage: L.q(1) [0 0 0] [0 0 1] @@ -759,7 +759,7 @@ def z(self): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 1, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 1, representation='matrix') sage: L.z() [0 0 1] [0 0 0] @@ -773,7 +773,7 @@ def step(self): EXAMPLES:: - sage: h = lie_algebras.Heisenberg(ZZ, 2, representation="matrix") + sage: h = lie_algebras.Heisenberg(ZZ, 2, representation='matrix') sage: h.step() 2 """ @@ -792,7 +792,7 @@ def monomial_coefficients(self, copy=True): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 3, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 3, representation='matrix') sage: elt = L(Matrix(QQ, [[0, 1, 3, 0, 3], [0, 0, 0, 0, 0], [0, 0, 0, 0, -3], ....: [0, 0, 0, 0, 7], [0, 0, 0, 0, 0]])) sage: elt diff --git a/src/sage/algebras/lie_algebras/lie_algebra.py b/src/sage/algebras/lie_algebras/lie_algebra.py index 885dcf44f0d..12a992bbffd 100644 --- a/src/sage/algebras/lie_algebras/lie_algebra.py +++ b/src/sage/algebras/lie_algebras/lie_algebra.py @@ -276,7 +276,7 @@ class LieAlgebra(Parent, UniqueRepresentation): # IndexedGenerators): sage: L = LieAlgebra(QQ, 'x,y,z'); L Free Lie algebra generated by (x, y, z) over Rational Field - sage: P. = LieAlgebra(QQ, representation="polynomial"); P + sage: P. = LieAlgebra(QQ, representation='polynomial'); P Lie algebra generated by (a, b, c) in Free Algebra on 3 generators (a, b, c) over Rational Field @@ -306,7 +306,7 @@ class LieAlgebra(Parent, UniqueRepresentation): # IndexedGenerators): So the generators of the free Lie algebra are the generators of the free algebra and the Lie bracket is the commutator:: - sage: P. = LieAlgebra(QQ, representation="polynomial"); P + sage: P. = LieAlgebra(QQ, representation='polynomial'); P Lie algebra generated by (a, b, c) in Free Algebra on 3 generators (a, b, c) over Rational Field sage: P.bracket(a, b) + P.bracket(a - c, b + 3*c) @@ -540,7 +540,7 @@ def _element_constructor_(self, x): EXAMPLES:: - sage: L. = LieAlgebra(QQ, representation="polynomial") + sage: L. = LieAlgebra(QQ, representation='polynomial') sage: elt = L([x, y]); elt x*y - y*x sage: elt.parent() is L @@ -581,7 +581,7 @@ def __getitem__(self, x): EXAMPLES:: - sage: L. = LieAlgebra(QQ, representation="polynomial") + sage: L. = LieAlgebra(QQ, representation='polynomial') sage: L[x, [y, x]] -x^2*y + 2*x*y*x - y*x^2 @@ -690,7 +690,7 @@ def zero(self): EXAMPLES:: - sage: L. = LieAlgebra(QQ, representation="polynomial") + sage: L. = LieAlgebra(QQ, representation='polynomial') sage: L.zero() 0 """ @@ -704,14 +704,14 @@ def _from_dict(self, d, coerce=False, remove_zeros=True): INPUT: - - ``d`` -- a dictionary ``{index: coeff}`` where each ``index`` is the + - ``d`` -- dictionary ``{index: coeff}`` where each ``index`` is the index of a basis element and each ``coeff`` belongs to the coefficient ring ``self.base_ring()`` - - ``coerce`` -- a boolean (default: ``False``), whether to coerce the + - ``coerce`` -- boolean (default: ``False``); whether to coerce the ``coeff`` to the coefficient ring - - ``remove_zeros`` -- a boolean (default: ``True``), if some + - ``remove_zeros`` -- boolean (default: ``True``); if some ``coeff`` may be zero and should therefore be removed EXAMPLES:: @@ -816,7 +816,7 @@ def lie_algebra_generators(self): EXAMPLES:: - sage: L. = LieAlgebra(QQ, representation="polynomial") + sage: L. = LieAlgebra(QQ, representation='polynomial') sage: L.lie_algebra_generators() Finite family {'x': x, 'y': y} """ @@ -860,7 +860,7 @@ def indices(self): EXAMPLES:: - sage: L. = LieAlgebra(QQ, representation="polynomial") + sage: L. = LieAlgebra(QQ, representation='polynomial') sage: L.indices() {'x', 'y'} """ @@ -1399,7 +1399,7 @@ def _bracket_(self, rhs): EXAMPLES:: - sage: L. = LieAlgebra(QQ, representation="polynomial") + sage: L. = LieAlgebra(QQ, representation='polynomial') sage: L.bracket(x, y) x*y - y*x @@ -1526,9 +1526,7 @@ def matrix(self): r""" Return ``self`` as element of the underlying matrix algebra. - OUTPUT: - - An instance of the element class of MatrixSpace. + OUTPUT: an instance of the element class of MatrixSpace EXAMPLES:: diff --git a/src/sage/algebras/lie_algebras/lie_algebra_element.pyx b/src/sage/algebras/lie_algebras/lie_algebra_element.pyx index 92aeeaa7959..b24e931b5e8 100644 --- a/src/sage/algebras/lie_algebras/lie_algebra_element.pyx +++ b/src/sage/algebras/lie_algebras/lie_algebra_element.pyx @@ -35,7 +35,7 @@ cdef class LieAlgebraElement(IndexedFreeModuleElement): # Need to bypass the coercion model def __mul__(left, right): """ - If we are multiplying two non-zero elements, automatically + If we are multiplying two nonzero elements, automatically lift up to the universal enveloping algebra. EXAMPLES:: @@ -263,7 +263,7 @@ cdef class LieAlgebraElementWrapper(ElementWrapper): """ def __bool__(self): """ - Return if ``self`` is non-zero. + Return if ``self`` is nonzero. EXAMPLES:: @@ -305,7 +305,7 @@ cdef class LieAlgebraElementWrapper(ElementWrapper): # Need to bypass the coercion model def __mul__(left, right): """ - If we are multiplying two non-zero elements, automatically + If we are multiplying two nonzero elements, automatically lift up to the universal enveloping algebra. .. TODO:: @@ -475,7 +475,7 @@ cdef class LieAlgebraMatrixWrapper(LieAlgebraElementWrapper): EXAMPLES:: - sage: L = lie_algebras.Heisenberg(QQ, 1, representation="matrix") + sage: L = lie_algebras.Heisenberg(QQ, 1, representation='matrix') sage: z = L.z() sage: z.value.is_immutable() True @@ -583,7 +583,7 @@ cdef class LieSubalgebraElementWrapper(LieAlgebraElementWrapper): INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally + - ``copy`` -- boolean (default: ``True``); if ``self`` is internally represented by a dictionary ``d``, then make a copy of ``d``; if ``False``, then this can cause undesired behavior by mutating ``d`` diff --git a/src/sage/algebras/lie_algebras/morphism.py b/src/sage/algebras/lie_algebras/morphism.py index 32b36c26590..0e76f37e37f 100644 --- a/src/sage/algebras/lie_algebras/morphism.py +++ b/src/sage/algebras/lie_algebras/morphism.py @@ -385,7 +385,7 @@ class LieAlgebraMorphism_from_generators(LieAlgebraHomomorphism_im_gens): Note that if base_map is nontrivial then the result will not be a morphism in the category of Lie algebras over the base ring. - - ``check`` -- (default: ``True``) boolean; if ``False`` the + - ``check`` -- boolean (default: ``True``); if ``False`` the values on the Lie brackets implied by ``on_generators`` will not be checked for contradictory values diff --git a/src/sage/algebras/lie_algebras/nilpotent_lie_algebra.py b/src/sage/algebras/lie_algebras/nilpotent_lie_algebra.py index d68d186e0be..062afc42c20 100644 --- a/src/sage/algebras/lie_algebras/nilpotent_lie_algebra.py +++ b/src/sage/algebras/lie_algebras/nilpotent_lie_algebra.py @@ -29,13 +29,13 @@ class NilpotentLieAlgebra_dense(LieAlgebraWithStructureCoefficients): INPUT: - ``R`` -- the base ring - - ``s_coeff`` -- a dictionary of structural coefficients - - ``names`` -- (default:``None``) list of strings to use as names of basis + - ``s_coeff`` -- dictionary of structural coefficients + - ``names`` -- (default: ``None``) list of strings to use as names of basis elements; if ``None``, the names will be inferred from the structural coefficients - - ``index_set`` -- (default:``None``) list of hashable and comparable + - ``index_set`` -- (default: ``None``) list of hashable and comparable elements to use for indexing - - ``step`` -- (optional) an integer; the nilpotency step of the + - ``step`` -- integer (optional); the nilpotency step of the Lie algebra if known; otherwise it will be computed when needed - ``category`` -- (optional) a subcategory of finite dimensional nilpotent Lie algebras with basis @@ -174,9 +174,9 @@ class FreeNilpotentLieAlgebra(NilpotentLieAlgebra_dense): INPUT: - ``R`` -- the base ring - - ``r`` -- an integer; the number of generators - - ``s`` -- an integer; the nilpotency step of the algebra - - ``names`` -- (optional) a string or a list of strings used to name the + - ``r`` -- integer; the number of generators + - ``s`` -- integer; the nilpotency step of the algebra + - ``names`` -- (optional) string or list of strings used to name the basis elements; if ``names`` is a string, then names for the basis will be autogenerated as determined by the ``naming`` parameter - ``naming`` -- (optional) a string; the naming scheme to use for @@ -340,7 +340,7 @@ def __classcall_private__(cls, R, r, s, names=None, naming=None, category=None, def __init__(self, R, r, s, names, naming, category, **kwds): r""" - Initialize ``self`` + Initialize ``self``. EXAMPLES:: diff --git a/src/sage/algebras/lie_algebras/quotient.py b/src/sage/algebras/lie_algebras/quotient.py index 2bb472206c3..06f6d0eb55a 100644 --- a/src/sage/algebras/lie_algebras/quotient.py +++ b/src/sage/algebras/lie_algebras/quotient.py @@ -33,7 +33,7 @@ class LieQuotient_finite_dimensional_with_basis(LieAlgebraWithStructureCoefficie - ``I`` -- an ideal or a list of generators of the ideal - ``ambient`` -- (optional) the Lie algebra to be quotiented; will be deduced from ``I`` if not given - - ``names`` -- (optional) a string or a list of strings; + - ``names`` -- (optional) string or list of strings; names for the basis elements of the quotient. If ``names`` is a string, the basis will be named ``names_1``,...,``names_n``. diff --git a/src/sage/algebras/lie_algebras/representation.py b/src/sage/algebras/lie_algebras/representation.py index bedcb869867..73c492d382f 100644 --- a/src/sage/algebras/lie_algebras/representation.py +++ b/src/sage/algebras/lie_algebras/representation.py @@ -60,9 +60,7 @@ def side(self): r""" Return that ``self`` is a left representation. - OUTPUT: - - - the string ``"left"`` + OUTPUT: the string ``'left'`` EXAMPLES:: @@ -102,7 +100,7 @@ def representation_matrix(self, elt): EXAMPLES:: sage: H1 = lie_algebras.Heisenberg(QQ, 1) - sage: F = H1.faithful_representation(algorithm="minimal") + sage: F = H1.faithful_representation(algorithm='minimal') sage: P1 = F.representation_matrix(H1.gen(0)); P1 [0 0 0] [0 0 0] @@ -144,10 +142,10 @@ class RepresentationByMorphism(CombinatorialFreeModule, Representation_abstract) - ``f`` -- the Lie algebra morphism defining the action of the basis elements of ``lie_algebra`` - ``index_set`` -- (optional) the index set of the module basis - - ``on_basis`` -- (default: ``False``) the function ``f`` defines a + - ``on_basis`` -- boolean (default: ``False``); the function `f` defines a map from the basis elements or from a generic element of ``lie_algebra`` - If ``f`` is encoded as a ``dict`` or ``Family``, then the keys must + If `f` is encoded as a ``dict`` or ``Family``, then the keys must be indices of the basis of ``lie_algebra`` and the values being the corresponding matrix defining the action. This sets ``on_basis=True``. @@ -509,7 +507,7 @@ class FaithfulRepresentationNilpotentPBW(CombinatorialFreeModule, Representation 2*F[1, 0, 0] + 8*F[1, 1, 0] + 3*F[2, 0, 0] + 4*F[0, 1, 0] + 4*F[0, 2, 0] + 4*F[0, 0, 1] - sage: MF = L.faithful_representation(algorithm="minimal") + sage: MF = L.faithful_representation(algorithm='minimal') sage: MF.dimension() 3 sage: [MF.representation_matrix(be) for be in L.basis()] @@ -527,7 +525,7 @@ class FaithfulRepresentationNilpotentPBW(CombinatorialFreeModule, Representation sage: F = L.faithful_representation(); F Faithful 11 dimensional representation of Lie algebra on 4 generators (a, b, c, d) over Rational Field - sage: MF = L.faithful_representation(algorithm="minimal"); MF + sage: MF = L.faithful_representation(algorithm='minimal'); MF Minimal faithful representation of Lie algebra on 4 generators (a, b, c, d) over Rational Field sage: MF.dimension() @@ -551,14 +549,14 @@ def __init__(self, L, minimal=False): sage: H2 = lie_algebras.Heisenberg(QQ, 2) sage: F = H2.faithful_representation() sage: TestSuite(F).run(elements=list(F.basis())) - sage: MF = H2.faithful_representation(algorithm="minimal") + sage: MF = H2.faithful_representation(algorithm='minimal') sage: TestSuite(MF).run(elements=list(MF.basis())) sage: sc = {('a','b'): {'b':-1, 'c':1}, ('a','c'): {'b':-1, 'c':1}} sage: L. = LieAlgebra(QQ, sc) sage: F = L.faithful_representation() sage: TestSuite(F).run(elements=list(F.basis())) - sage: MF = L.faithful_representation(algorithm="minimal") + sage: MF = L.faithful_representation(algorithm='minimal') sage: TestSuite(MF).run(elements=list(MF.basis())) """ LCS = L.lower_central_series() diff --git a/src/sage/algebras/lie_algebras/structure_coefficients.py b/src/sage/algebras/lie_algebras/structure_coefficients.py index 862ee657138..5c0c9c8bcbf 100644 --- a/src/sage/algebras/lie_algebras/structure_coefficients.py +++ b/src/sage/algebras/lie_algebras/structure_coefficients.py @@ -48,7 +48,7 @@ class LieAlgebraWithStructureCoefficients(FinitelyGeneratedLieAlgebra, IndexedGe - ``R`` -- a ring, to be used as the base ring - - ``s_coeff`` -- a dictionary, indexed by pairs of basis indices + - ``s_coeff`` -- dictionary, indexed by pairs of basis indices (see below), and whose values are dictionaries which are indexed by (single) basis indices and whose values are elements of `R` @@ -366,7 +366,7 @@ def _from_dict(self, d, coerce=False, remove_zeros=False): INPUT: - - ``d`` -- a dictionary ``{index: coeff}`` where each ``index`` is the + - ``d`` -- dictionary ``{index: coeff}`` where each ``index`` is the index of a basis element and each ``coeff`` belongs to the coefficient ring ``self.base_ring()`` - ``coerce`` -- ignored @@ -428,7 +428,7 @@ def _sorted_items_for_printing(self): .. WARNING:: The internal representation order is fixed, whereas this - depends on ``"sorting_key"`` print option as it is used + depends on ``'sorting_key'`` print option as it is used only for printing. EXAMPLES:: diff --git a/src/sage/algebras/lie_algebras/subalgebra.py b/src/sage/algebras/lie_algebras/subalgebra.py index a7fe9752856..1dd5444f766 100644 --- a/src/sage/algebras/lie_algebras/subalgebra.py +++ b/src/sage/algebras/lie_algebras/subalgebra.py @@ -35,8 +35,8 @@ class LieSubalgebra_finite_dimensional_with_basis(Parent, UniqueRepresentation): INPUT: - ``ambient`` -- the Lie algebra containing the subalgebra - - ``gens`` -- a list of generators of the subalgebra - - ``ideal`` -- (default: ``False``) a boolean; if ``True``, then ``gens`` + - ``gens`` -- list of generators of the subalgebra + - ``ideal`` -- boolean (default: ``False``); if ``True``, then ``gens`` is interpreted as the generating set of an ideal instead of a subalgebra - ``order`` -- (optional) the key used to sort the indices of ``ambient`` - ``category`` -- (optional) a subcategory of subobjects of finite @@ -311,7 +311,6 @@ def __contains__(self, x): sage: I = L.subalgebra(x) sage: I(x) in I True - """ if x in self._ambient: x = self._ambient(x) @@ -770,7 +769,7 @@ def leading_monomials(self): def from_vector(self, v, order=None, coerce=False): r""" - Return the element of ``self`` corresponding to the vector ``v`` + Return the element of ``self`` corresponding to the vector ``v``. INPUT: diff --git a/src/sage/algebras/lie_algebras/verma_module.py b/src/sage/algebras/lie_algebras/verma_module.py index 71f2ff58a85..778a9486707 100644 --- a/src/sage/algebras/lie_algebras/verma_module.py +++ b/src/sage/algebras/lie_algebras/verma_module.py @@ -436,7 +436,7 @@ def _coerce_map_from_(self, R): - there is a coercion from ``R`` into the base ring; - ``R`` is a Verma module over the same Lie algebra and - there is a non-zero Verma module morphism from ``R`` + there is a nonzero Verma module morphism from ``R`` into ``self``. EXAMPLES:: @@ -731,7 +731,7 @@ def _Hom_(self, Y, category=None, **options): The sole purpose of this method is to construct the homset as a :class:`~sage.algebras.lie_algebras.verma_module.VermaModuleHomset`. If ``category`` is specified and is not a subcategory of - ``self.category()``, a :class:`TypeError` is raised instead. + ``self.category()``, a :exc:`TypeError` is raised instead. This method is not meant to be called directly. Please use :func:`sage.categories.homset.Hom` instead. @@ -1058,7 +1058,7 @@ def _composition_(self, right, homset): INPUT: - ``self``, ``right`` -- maps - - homset -- a homset + - ``homset`` -- a homset ASSUMPTION: diff --git a/src/sage/algebras/lie_algebras/virasoro.py b/src/sage/algebras/lie_algebras/virasoro.py index f1d926b484b..0284a10e5e5 100644 --- a/src/sage/algebras/lie_algebras/virasoro.py +++ b/src/sage/algebras/lie_algebras/virasoro.py @@ -206,7 +206,7 @@ def __init__(self, R, p): matrix over the base ring as part of the test:: sage: L = lie_algebras.pwitt(Zmod(6), 6) - sage: TestSuite(L).run(skip="_test_grading") + sage: TestSuite(L).run(skip='_test_grading') """ if R(p) != 0: raise ValueError("{} is not 0 in {}".format(p, R)) @@ -1017,7 +1017,7 @@ def _monomial(self, index): """ if index in ZZ: if index >= 0: - raise ValueError("sequence must have non-positive entries") + raise ValueError("sequence must have nonpositive entries") index = (index,) return super()._monomial(index) diff --git a/src/sage/algebras/lie_conformal_algebras/abelian_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/abelian_lie_conformal_algebra.py index b70bc9cbbaf..6027dee4a95 100644 --- a/src/sage/algebras/lie_conformal_algebras/abelian_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/abelian_lie_conformal_algebra.py @@ -33,21 +33,20 @@ class AbelianLieConformalAlgebra(GradedLieConformalAlgebra): - ``R`` -- a commutative ring; the base ring of this Lie conformal algebra - - ``ngens`` -- a positive integer (default: ``1``); the number + - ``ngens`` -- positive integer (default: `1`); the number of generators of this Lie conformal algebra - - ``weights`` -- a list of positive rational numbers (default: - ``1`` for each - generator); the weights of the generators. The resulting + - ``weights`` -- list of positive rational numbers (default: + `1` for each generator); the weights of the generators. The resulting Lie conformal algebra is `H`-graded. - ``parity`` -- ``None`` or a list of ``0`` or ``1`` (default: - ``None``); The parity of the generators. If not ``None`` the + ``None``); the parity of the generators. If not ``None`` the resulting Lie Conformal algebra is a Super Lie conformal algebra - - ``names`` -- a tuple of ``str`` or ``None`` (default: ``None`` - ); the list of names of the generators of this algebra. + - ``names`` -- tuple of strings or ``None`` (default: ``None``); + the list of names of the generators of this algebra. - ``index_set`` -- an enumerated set or ``None`` (default: - ``None``); A set indexing the generators of this Lie - conformal algebra. + ``None``); a set indexing the generators of this Lie + conformal algebra OUTPUT: @@ -79,7 +78,7 @@ class AbelianLieConformalAlgebra(GradedLieConformalAlgebra): def __init__(self, R, ngens=1, weights=None, parity=None, names=None, index_set=None): """ - Initialize self. + Initialize ``self``. EXAMPLES:: diff --git a/src/sage/algebras/lie_conformal_algebras/affine_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/affine_lie_conformal_algebra.py index 8c6671aa1a0..a1ccb69653d 100644 --- a/src/sage/algebras/lie_conformal_algebras/affine_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/affine_lie_conformal_algebra.py @@ -43,19 +43,19 @@ class AffineLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - ``R`` -- a commutative Ring; the base ring for this Lie - conformal algebra. + conformal algebra - ``ct`` -- a ``str`` or a :mod:`CartanType`; the Cartan Type for the corresponding finite dimensional Lie algebra. It must correspond to a simple finite dimensional Lie algebra. - - ``names`` -- a list of ``str`` or ``None`` (default: ``None``) - ; alternative names for the generators. If ``None`` the + - ``names`` -- list of ``str`` or ``None`` (default: ``None``); + alternative names for the generators. If ``None`` the generators are labeled by the corresponding root and coroot vectors. - ``prefix`` -- a ``str``; parameter passed to :class:`IndexedGenerators` - ``bracket`` -- a ``str``; parameter passed to - :class:`IndexedGenerators`. + :class:`IndexedGenerators` EXAMPLES:: @@ -83,7 +83,7 @@ class AffineLieConformalAlgebra(GradedLieConformalAlgebra): """ def __init__(self, R, ct, names=None, prefix=None, bracket=None): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/bosonic_ghosts_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/bosonic_ghosts_lie_conformal_algebra.py index 5f88bcded94..2e689ee4c60 100644 --- a/src/sage/algebras/lie_conformal_algebras/bosonic_ghosts_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/bosonic_ghosts_lie_conformal_algebra.py @@ -41,14 +41,14 @@ class BosonicGhostsLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - - ``R`` -- a commutative ring. + - ``R`` -- a commutative ring - ``ngens`` -- an even positive Integer (default: ``2``); the number of non-central generators of this Lie conformal algebra. - - ``names`` -- a list of ``str``; alternative names for the + - ``names`` -- list of ``str``; alternative names for the + generators + - ``index_set`` -- an enumerated set; an indexing set for the generators - - ``index_set`` -- an enumerated set; An indexing set for the - generators. OUTPUT: @@ -81,7 +81,7 @@ class BosonicGhostsLieConformalAlgebra(GradedLieConformalAlgebra): def __init__(self, R, ngens=2, names=None, index_set=None): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/fermionic_ghosts_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/fermionic_ghosts_lie_conformal_algebra.py index 3a029ec96a5..004718d4a5f 100644 --- a/src/sage/algebras/lie_conformal_algebras/fermionic_ghosts_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/fermionic_ghosts_lie_conformal_algebra.py @@ -37,15 +37,15 @@ class FermionicGhostsLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - - ``R`` -- a commutative ring; the base ring of this Lie + - ``R`` -- a commutative ring; the base ring of this Lie conformal algebra - - ``ngens`` -- an even positive Integer (default: ``2``); The + - ``ngens`` -- an even positive Integer (default: ``2``); the number of non-central generators of this Lie conformal - algebra. - - ``names`` -- a tuple of ``str``; alternative names for the + algebra + - ``names`` -- tuple of strings; alternative names for the generators - ``index_set`` -- an enumerated set; alternative indexing - set for the generators. + set for the generators OUTPUT: @@ -74,7 +74,7 @@ class FermionicGhostsLieConformalAlgebra(GradedLieConformalAlgebra): """ def __init__(self,R,ngens=2,names=None,index_set=None): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/finitely_freely_generated_lca.py b/src/sage/algebras/lie_conformal_algebras/finitely_freely_generated_lca.py index d93ec041655..be9afefd29a 100644 --- a/src/sage/algebras/lie_conformal_algebras/finitely_freely_generated_lca.py +++ b/src/sage/algebras/lie_conformal_algebras/finitely_freely_generated_lca.py @@ -35,7 +35,7 @@ def __init__(self, R, index_set=None, central_elements=None, category=None, element_class=None, prefix=None, names=None, latex_names=None, **kwds): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/free_bosons_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/free_bosons_lie_conformal_algebra.py index 677e9ea585d..fe7954e1aea 100644 --- a/src/sage/algebras/lie_conformal_algebras/free_bosons_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/free_bosons_lie_conformal_algebra.py @@ -43,16 +43,16 @@ class FreeBosonsLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - - ``R`` -- a commutative ring. - - ``ngens`` -- a positive Integer (default ``1``); the number of + - ``R`` -- a commutative ring + - ``ngens`` -- a positive Integer (default: `1`); the number of non-central generators of this Lie conformal algebra. - - ``gram_matrix``: a symmetric square matrix with coefficients + - ``gram_matrix`` -- a symmetric square matrix with coefficients in ``R`` (default: ``identity_matrix(ngens)``); the Gram matrix of the inner product - - ``names`` -- a tuple of ``str``; alternative names for the + - ``names`` -- tuple of strings; alternative names for the generators - ``index_set`` -- an enumerated set; alternative indexing set - for the generators. + for the generators OUTPUT: @@ -102,7 +102,7 @@ class FreeBosonsLieConformalAlgebra(GradedLieConformalAlgebra): def __init__(self, R, ngens=None, gram_matrix=None, names=None, index_set=None): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/free_fermions_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/free_fermions_lie_conformal_algebra.py index e952e1b92be..4b8cb428f0b 100644 --- a/src/sage/algebras/lie_conformal_algebras/free_fermions_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/free_fermions_lie_conformal_algebra.py @@ -42,10 +42,10 @@ class FreeFermionsLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - - ``R``: a commutative ring. - - ``ngens``: a positive Integer (default ``1``); the number of - non-central generators of this Lie conformal algebra. - - ``gram_matrix``: a symmetric square matrix with coefficients + - ``R`` -- a commutative ring + - ``ngens`` -- a positive Integer (default: ``1``); the number of + non-central generators of this Lie conformal algebra + - ``gram_matrix`` -- a symmetric square matrix with coefficients in ``R`` (default: ``identity_matrix(ngens)``); the Gram matrix of the inner product @@ -85,7 +85,7 @@ class FreeFermionsLieConformalAlgebra(GradedLieConformalAlgebra): def __init__(self, R, ngens=None, gram_matrix=None, names=None, index_set=None): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/freely_generated_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/freely_generated_lie_conformal_algebra.py index 790d7d5a9cb..0b77dd91854 100644 --- a/src/sage/algebras/lie_conformal_algebras/freely_generated_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/freely_generated_lie_conformal_algebra.py @@ -41,7 +41,7 @@ class FreelyGeneratedLieConformalAlgebra(LieConformalAlgebraWithBasis): def __init__(self, R, index_set=None, central_elements=None, category=None, element_class=None, prefix=None, **kwds): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/graded_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/graded_lie_conformal_algebra.py index 61e38845ca4..2004f54485c 100644 --- a/src/sage/algebras/lie_conformal_algebras/graded_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/graded_lie_conformal_algebra.py @@ -62,31 +62,31 @@ class GradedLieConformalAlgebra(LieConformalAlgebraWithStructureCoefficients): ring of this Lie conformal algebra. Behaviour is undefined if it is not a field of characteristic zero - - ``s_coeff`` -- a dictionary (default: ``None``); as in the + - ``s_coeff`` -- dictionary (default: ``None``); as in the input of :class:`LieConformalAlgebra` - - ``names`` -- tuple of ``str`` (default: ``None``); as in the + - ``names`` -- tuple of strings (default: ``None``); as in the input of :class:`LieConformalAlgebra` - - ``central_elements`` -- tuple of ``str`` (default: ``None``); + - ``central_elements`` -- tuple of strings (default: ``None``); as in the input of :class:`LieConformalAlgebra` - ``index_set`` -- enumerated set (default: ``None``); as in the input of :class:`LieConformalAlgebra` - - ``weights`` -- tuple of non-negative rational numbers + - ``weights`` -- tuple of nonnegative rational numbers (default: tuple of ``1``); a list of degrees for this Lie conformal algebra. This tuple needs to have the same cardinality as ``index_set`` or ``names``. Central elements are assumed to have weight ``0``. - - ``category`` The category that this Lie conformal algebra - belongs to. + - ``category`` -- the category that this Lie conformal algebra + belongs to - - ``parity`` -- tuple of ``0`` or ``1`` (Default: tuple of + - ``parity`` -- tuple of ``0`` or ``1`` (default: tuple of ``0``); a tuple specifying the parity of each non-central - generator. + generator EXAMPLES:: @@ -105,7 +105,7 @@ def __init__(self, R, s_coeff, index_set=None, central_elements=None, category=None, prefix=None, names=None, latex_names=None, parity=None, weights=None, **kwds): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra.py index 19ab2b41dbc..2631d965307 100644 --- a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra.py @@ -42,7 +42,7 @@ `T` is usually called the *translation operation* or the *derivative*. For an element `a \in L` we will say that `Ta` is the *derivative of* - `a`. We define the *n-th products* `a_{(n)} b` for `a,b \in L` by + `a`. We define the *`n`-th products* `a_{(n)} b` for `a,b \in L` by .. MATH:: @@ -63,8 +63,7 @@ .. NOTE:: In the literature arbitrary gradings are allowed. In this - implementation we only support non-negative rational gradings. - + implementation we only support nonnegative rational gradings. EXAMPLES: @@ -190,7 +189,7 @@ class LieConformalAlgebra(UniqueRepresentation, Parent): ring of this Lie conformal algebra. Behaviour is undefined if it is not a field of characteristic zero. - - ``arg0`` -- a dictionary (default: ``None``); + - ``arg0`` -- dictionary (default: ``None``); a dictionary containing the `\lambda` brackets of the generators of this Lie conformal algebra. The keys of this dictionary are pairs of either names or indices of the @@ -198,7 +197,7 @@ class LieConformalAlgebra(UniqueRepresentation, Parent): pair of generators ``'a'`` and ``'b'``, the value of ``arg0[('a','b')]`` is a dictionary whose keys are positive integer numbers and the corresponding value for the - key ``j`` is a dictionary itself representing the j-th product + key ``j`` is a dictionary itself representing the `j`-th product `a_{(j)}b`. Thus, for a positive integer number `j`, the value of ``arg0[('a','b')][j]`` is a dictionary whose entries are pairs ``('c',n)`` where ``'c'`` is the name of a generator @@ -216,19 +215,18 @@ class LieConformalAlgebra(UniqueRepresentation, Parent): pair (besides the ones defined by skew-symmetry) is assumed to have vanishing `\lambda`-bracket. - - ``names`` -- tuple of ``str`` (default: ``None``); the list of + - ``names`` -- tuple of strings (default: ``None``); the list of names for generators of this Lie conformal algebra. Do not include central elements in this list. - - ``central_elements`` -- tuple of ``str`` (default: ``None``); - A list of names for central elements of this Lie conformal - algebra. + - ``central_elements`` -- tuple of strings (default: ``None``); + a list of names for central elements of this Lie conformal algebra - ``index_set`` -- enumerated set (default: ``None``); an indexing set for the generators of this Lie conformal algebra. Do not include central elements in this list. - - ``weights`` -- tuple of non-negative rational numbers + - ``weights`` -- tuple of nonnegative rational numbers (default: ``None``); a list of degrees for this Lie conformal algebra. The returned Lie conformal algebra is H-Graded. This tuple @@ -244,18 +242,18 @@ class LieConformalAlgebra(UniqueRepresentation, Parent): ``LieConformalAlgebras(R).Super()``, even if all generators are even. - - ``category`` The category that this Lie conformal algebra - belongs to. + - ``category`` -- the category that this Lie conformal algebra + belongs to In addition we accept the following keywords: - - ``graded`` -- a boolean (default: ``False``); + - ``graded`` -- boolean (default: ``False``); if ``True``, the returned algebra is H-Graded. If ``weights`` is not specified, all non-central generators are assigned degree `1`. This keyword is ignored if ``weights`` is specified - - ``super`` -- a boolean (default: ``False``); + - ``super`` -- boolean (default: ``False``); if ``True``, the returned algebra is a super Lie conformal algebra even if all generators are even. If ``parity`` is not specified, all generators are diff --git a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_element.py b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_element.py index bf08362ae92..27796941d2b 100644 --- a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_element.py +++ b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_element.py @@ -29,12 +29,12 @@ class LCAWithGeneratorsElement(IndexedFreeModuleElement): """ def T(self, n=1): r""" - The n-th derivative of this element. + The `n`-th derivative of this element. INPUT: - - ``n`` -- a non-negative integer (default:``1``); how many - times to apply `T` to this element. + - ``n`` -- nonnegative integer (default: `1`); how many + times to apply `T` to this element We use the *divided powers* notation `T^{(j)} = \frac{T^j}{j!}`. @@ -97,7 +97,7 @@ def _bracket_(self, right): """ The lambda bracket of these two elements. - The result is a dictionary with non-negative integer keys. + The result is a dictionary with nonnegative integer keys. The value corresponding to the entry `j` is ``self_{(j)}right``. EXAMPLES:: diff --git a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_basis.py b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_basis.py index d95c99978b3..254eeac64e6 100644 --- a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_basis.py +++ b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_basis.py @@ -55,7 +55,7 @@ class LieConformalAlgebraWithBasis(CombinatorialFreeModule): def __init__(self, R, basis_keys=None, element_class=None, category=None, prefix=None, **kwds): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_structure_coefs.py b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_structure_coefs.py index 25b688b19ff..4fe54a98963 100644 --- a/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_structure_coefs.py +++ b/src/sage/algebras/lie_conformal_algebras/lie_conformal_algebra_with_structure_coefs.py @@ -35,11 +35,11 @@ class LieConformalAlgebraWithStructureCoefficients( INPUT: - - ``R`` -- a ring (Default: ``None``); The base ring of this Lie + - ``R`` -- a ring (default: ``None``); the base ring of this Lie conformal algebra. Behaviour is undefined if it is not a field of characteristic zero. - - ``s_coeff`` -- Dictionary (Default: ``None``); + - ``s_coeff`` -- dictionary (default: ``None``); a dictionary containing the `\lambda` brackets of the generators of this Lie conformal algebra. The family encodes a dictionary whose keys @@ -48,7 +48,7 @@ class LieConformalAlgebraWithStructureCoefficients( generators `a` and `b`, the value of ``s_coeff[('a','b')]`` is a dictionary whose keys are positive integer numbers and the corresponding value for the key `j` is a dictionary itself - representing the j-th product `a_{(j)}b`. + representing the `j`-th product `a_{(j)}b`. Thus, for a positive integer number `j`, the value of ``s_coeff[('a','b')][j]`` is a dictionary whose entries are pairs ``('c',n)`` where ``'c'`` is the name of a generator @@ -66,21 +66,20 @@ class LieConformalAlgebraWithStructureCoefficients( defined by skew-symmetry) is assumed to have vanishing `\lambda`-bracket. - - ``names`` -- tuple of ``str`` (Default: ``None``); The list of + - ``names`` -- tuple of strings (default: ``None``); the list of names for generators of this Lie conformal algebra. Do not include central elements in this list. - - ``central_elements`` -- tuple of ``str`` (Default: ``None``); - A list of names for central - elements of this Lie conformal algebra. + - ``central_elements`` -- tuple of strings (default: ``None``); + a list of names for central elements of this Lie conformal algebra - - ``index_set`` -- enumerated set (Default: ``None``); + - ``index_set`` -- enumerated set (default: ``None``); an indexing set for the generators of this Lie conformal algebra. Do not include central elements in this list. - - ``parity`` -- tuple of `0` or `1` (Default: tuple of `0`); - a tuple specifying the parity of each non-central generator. + - ``parity`` -- tuple of `0` or `1` (default: tuple of `0`); + a tuple specifying the parity of each non-central generator EXAMPLES: @@ -121,14 +120,14 @@ def _standardize_s_coeff(s_coeff, index_set, ce, parity=None): INPUT: - - ``s_coeff`` -- a dictionary as in - :class:`~sage.algebras.lie_conformal_algebras.lie_conformal_algebra_with_structure_coefficients.LieConformalAlgebraWithStructureCoefficients`. + - ``s_coeff`` -- dictionary as in + :class:`~sage.algebras.lie_conformal_algebras.lie_conformal_algebra_with_structure_coefficients.LieConformalAlgebraWithStructureCoefficients` - ``index_set`` -- a finite enumerated set indexing the generators (not counting the central elements). - - ``ce`` -- a tuple of ``str``; a list of names for the central + - ``ce`` -- tuple of strings; a list of names for the central generators of this Lie conformal algebra - - ``parity`` -- a tuple of `0` or `1` (Default: tuple of `0`); - this tuple specifies the parity of each non-central generator. + - ``parity`` -- tuple of `0` or `1` (default: tuple of `0`); + this tuple specifies the parity of each non-central generator OUTPUT: @@ -206,7 +205,7 @@ def __init__(self, R, s_coeff, index_set=None, central_elements=None, category=None, element_class=None, prefix=None, names=None, latex_names=None, parity=None, **kwds): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/n2_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/n2_lie_conformal_algebra.py index baf7a896144..1abce4b5c76 100644 --- a/src/sage/algebras/lie_conformal_algebras/n2_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/n2_lie_conformal_algebra.py @@ -40,7 +40,7 @@ class N2LieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - ``R`` -- a commutative ring; the base ring of this super - Lie conformal algebra. + Lie conformal algebra EXAMPLES:: @@ -75,7 +75,7 @@ class N2LieConformalAlgebra(GradedLieConformalAlgebra): """ def __init__(self, R): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/neveu_schwarz_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/neveu_schwarz_lie_conformal_algebra.py index 7bf03e30dea..323c08ee958 100644 --- a/src/sage/algebras/lie_conformal_algebras/neveu_schwarz_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/neveu_schwarz_lie_conformal_algebra.py @@ -35,7 +35,7 @@ class NeveuSchwarzLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - ``R`` -- a commutative Ring; the base ring of this Lie - conformal algebra. + conformal algebra EXAMPLES:: @@ -52,7 +52,7 @@ class NeveuSchwarzLieConformalAlgebra(GradedLieConformalAlgebra): """ def __init__(self, R): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/virasoro_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/virasoro_lie_conformal_algebra.py index f0867dae808..edaf039be55 100644 --- a/src/sage/algebras/lie_conformal_algebras/virasoro_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/virasoro_lie_conformal_algebra.py @@ -36,7 +36,7 @@ class VirasoroLieConformalAlgebra(GradedLieConformalAlgebra): INPUT: - ``R`` -- a commutative ring; behaviour is undefined if `R` is - not a Field of characteristic zero. + not a Field of characteristic zero EXAMPLES:: @@ -55,7 +55,7 @@ class VirasoroLieConformalAlgebra(GradedLieConformalAlgebra): """ def __init__(self, R): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/lie_conformal_algebras/weyl_lie_conformal_algebra.py b/src/sage/algebras/lie_conformal_algebras/weyl_lie_conformal_algebra.py index 3c319db7ca3..82e0c326547 100644 --- a/src/sage/algebras/lie_conformal_algebras/weyl_lie_conformal_algebra.py +++ b/src/sage/algebras/lie_conformal_algebras/weyl_lie_conformal_algebra.py @@ -47,17 +47,16 @@ class WeylLieConformalAlgebra(LieConformalAlgebraWithStructureCoefficients): INPUT: - ``R`` -- a commutative ring; the base ring of this Lie - conformal algebra. - - ``ngens``: an even positive Integer (default `2`); The number - of non-central generators of this Lie conformal algebra. - - ``gram_matrix``: a matrix (default: ``None``); A non-singular - skew-symmetric square matrix with coefficients in `R`. - - ``names`` -- a list or tuple of ``str``; alternative names + conformal algebra + - ``ngens`` -- an even positive Integer (default: `2`); the number + of non-central generators of this Lie conformal algebra + - ``gram_matrix`` -- a matrix (default: ``None``); a non-singular + skew-symmetric square matrix with coefficients in `R` + - ``names`` -- list or tuple of strings; alternative names for the generators - ``index_set`` -- an enumerated set; alternative indexing set for the generators - OUTPUT: The Weyl Lie conformal algebra with generators @@ -124,7 +123,7 @@ class WeylLieConformalAlgebra(LieConformalAlgebraWithStructureCoefficients): def __init__(self, R, ngens=None, gram_matrix=None, names=None, index_set=None): """ - Initialize self. + Initialize ``self``. TESTS:: diff --git a/src/sage/algebras/nil_coxeter_algebra.py b/src/sage/algebras/nil_coxeter_algebra.py index b470d16f971..8b47e6fd49b 100644 --- a/src/sage/algebras/nil_coxeter_algebra.py +++ b/src/sage/algebras/nil_coxeter_algebra.py @@ -28,11 +28,8 @@ class NilCoxeterAlgebra(IwahoriHeckeAlgebra.T): INPUT: - ``W`` -- a Weyl group - - OPTIONAL ARGUMENTS: - - - ``base_ring`` -- a ring (default is the rational numbers) - - ``prefix`` -- a label for the generators (default "u") + - ``base_ring`` -- a ring (default: rational numbers) + - ``prefix`` -- a label for the generators (default: ``'u'``) EXAMPLES:: @@ -80,14 +77,14 @@ def _repr_(self): def homogeneous_generator_noncommutative_variables(self, r): r""" - Give the `r^{th}` homogeneous function inside the Nil-Coxeter algebra. + Give the `r`-th homogeneous function inside the Nil-Coxeter algebra. In finite type `A` this is the sum of all decreasing elements of length `r`. In affine type `A` this is the sum of all cyclically decreasing elements of length `r`. This is only defined in finite type `A`, `B` and affine types `A^{(1)}`, `B^{(1)}`, `C^{(1)}`, `D^{(1)}`. INPUT: - - ``r`` -- a positive integer at most the rank of the Weyl group + - ``r`` -- positive integer at most the rank of the Weyl group EXAMPLES:: @@ -141,7 +138,6 @@ def homogeneous_noncommutative_variables(self, la): sage: U = NilCoxeterAlgebra(WeylGroup(['B',2,1])) sage: U.homogeneous_noncommutative_variables([]) 1 - """ return prod(self.homogeneous_generator_noncommutative_variables(p) for p in la) @@ -183,8 +179,6 @@ def k_schur_noncommutative_variables(self, la): Traceback (most recent call last): ... AssertionError: Weyl Group of type ['C', 3, 1] (as a matrix group acting on the root space) is not affine type A. - - """ assert self._cartan_type[0] == 'A' and len(self._cartan_type) == 3 and self._cartan_type[2] == 1, "%s is not affine type A." % (self._W) assert la in Partitions(), "%s is not a partition." % (la) diff --git a/src/sage/algebras/octonion_algebra.pyx b/src/sage/algebras/octonion_algebra.pyx index 3c1d28c2106..c38250b0be7 100644 --- a/src/sage/algebras/octonion_algebra.pyx +++ b/src/sage/algebras/octonion_algebra.pyx @@ -89,7 +89,7 @@ cdef class Octonion_generic(AlgebraElement): def __bool__(self): r""" - Return if ``self`` is non-zero or not. + Return if ``self`` is nonzero or not. EXAMPLES:: @@ -451,9 +451,7 @@ cdef class Octonion_generic(AlgebraElement): r""" Return the real part of ``self``. - OUTPUT: - - The real part of ``self`` as an element in the base ring. + OUTPUT: the real part of ``self`` as an element in the base ring EXAMPLES:: @@ -471,9 +469,7 @@ cdef class Octonion_generic(AlgebraElement): r""" Return the imginary part of ``self``. - OUTPUT: - - The imaginary part of ``self`` as an element in the octonion algebra. + OUTPUT: the imaginary part of ``self`` as an element in the octonion algebra EXAMPLES:: diff --git a/src/sage/algebras/orlik_solomon.py b/src/sage/algebras/orlik_solomon.py index 12e8518a2b0..7302b430738 100644 --- a/src/sage/algebras/orlik_solomon.py +++ b/src/sage/algebras/orlik_solomon.py @@ -25,7 +25,7 @@ class OrlikSolomonAlgebra(CombinatorialFreeModule): r""" An Orlik-Solomon algebra. - Let `R` be a commutative ring. Let `M` be a matroid with ground set + Let `R` be a commutative ring. Let `M` be a matroid with groundset `X`. Let `C(M)` denote the set of circuits of `M`. Let `E` denote the exterior algebra over `R` generated by `\{ e_x \mid x \in X \}`. The *Orlik-Solomon ideal* `J(M)` is the ideal of `E` generated by @@ -60,7 +60,7 @@ class OrlikSolomonAlgebra(CombinatorialFreeModule): - ``R`` -- the base ring - ``M`` -- the defining matroid - - ``ordering`` -- (optional) an ordering of the ground set + - ``ordering`` -- (optional) an ordering of the groundset EXAMPLES: @@ -202,7 +202,7 @@ def algebra_generators(self): r""" Return the algebra generators of ``self``. - These form a family indexed by the ground set `X` of `M`. For + These form a family indexed by the groundset `X` of `M`. For each `x \in X`, the `x`-th element is `e_x`. EXAMPLES:: @@ -255,7 +255,7 @@ def product_on_basis(self, a, b): TESTS: Let us check that `e_{s_1} e_{s_2} \cdots e_{s_k} = e_S` for any - subset `S = \{ s_1 < s_2 < \cdots < s_k \}` of the ground set:: + subset `S = \{ s_1 < s_2 < \cdots < s_k \}` of the groundset:: sage: # needs sage.graphs sage: G = Graph([[1,2],[1,2],[2,3],[3,4],[4,2]], multiedges=True) @@ -311,11 +311,11 @@ def product_on_basis(self, a, b): def subset_image(self, S): """ Return the element `e_S` of `A(M)` (``== self``) corresponding to - a subset `S` of the ground set of `M`. + a subset `S` of the groundset of `M`. INPUT: - - ``S`` -- a frozenset which is a subset of the ground set of `M` + - ``S`` -- frozenset which is a subset of the groundset of `M` EXAMPLES:: diff --git a/src/sage/algebras/orlik_terao.py b/src/sage/algebras/orlik_terao.py index 222e2152739..707b7f51060 100644 --- a/src/sage/algebras/orlik_terao.py +++ b/src/sage/algebras/orlik_terao.py @@ -359,7 +359,7 @@ def subset_image(self, S): INPUT: - - ``S`` -- a frozenset which is a subset of the groundset of `M` + - ``S`` -- frozenset which is a subset of the groundset of `M` EXAMPLES:: @@ -613,7 +613,6 @@ class OrlikTeraoInvariantAlgebra(FiniteDimensionalInvariantModule): Finite family {0: B[0], 1: B[1]} sage: [OTG.lift(b) for b in OTG.basis()] [OT{}, OT{0} + OT{1} + OT{2} + OT{3} + OT{4} + OT{5}] - """ def __init__(self, R, M, G, action_on_groundset=None, *args, **kwargs): r""" @@ -630,7 +629,6 @@ def __init__(self, R, M, G, action_on_groundset=None, *args, **kwargs): sage: import __main__; __main__.on_groundset = on_groundset sage: OTG = M.orlik_terao_algebra(QQ, invariant = (G,on_groundset)) sage: TestSuite(OTG).run() - """ ordering = kwargs.pop('ordering', None) OT = OrlikTeraoAlgebra(R, M, ordering) diff --git a/src/sage/algebras/q_commuting_polynomials.py b/src/sage/algebras/q_commuting_polynomials.py index 10f5f55a987..f19eaa042e4 100644 --- a/src/sage/algebras/q_commuting_polynomials.py +++ b/src/sage/algebras/q_commuting_polynomials.py @@ -173,7 +173,7 @@ def algebra_generators(self): Finite family {'x': x, 'y': y, 'z': z} """ d = {v: self.gen(i) for i, v in enumerate(self.variable_names())} - return Family(self.variable_names(), d.__getitem__, name="generator") + return Family(self.variable_names(), d.__getitem__, name='generator') def degree_on_basis(self, m): r""" diff --git a/src/sage/algebras/quantum_clifford.py b/src/sage/algebras/quantum_clifford.py index 89fea14c495..ff888ba5aaa 100644 --- a/src/sage/algebras/quantum_clifford.py +++ b/src/sage/algebras/quantum_clifford.py @@ -489,7 +489,7 @@ def product_on_basis(self, m1, m2): if p1[i] != 0: # We make pairings 1-based because we cannot distinguish 0 and -0 pairings.append((i+1) * p1[i]) - # we know p1[i] != p2[i] if non-zero, so their sum is -1, 0, 1 + # we know p1[i] != p2[i] if nonzero, so their sum is -1, 0, 1 p[i] = p1[i] + p2[i] supported.append(self._n-1) # To get between the last support and the end diff --git a/src/sage/algebras/quantum_groups/fock_space.py b/src/sage/algebras/quantum_groups/fock_space.py index aff82cd445f..8a7ce3e9386 100644 --- a/src/sage/algebras/quantum_groups/fock_space.py +++ b/src/sage/algebras/quantum_groups/fock_space.py @@ -41,7 +41,7 @@ class FockSpaceOptions(GlobalOptions): r""" - Sets and displays the global options for elements of the Fock + Set and display the global options for elements of the Fock space classes. If no parameters are set, then the function returns a copy of the options dictionary. @@ -444,7 +444,7 @@ def inject_shorthands(self, verbose=True): INPUT: - - ``verbose`` -- boolean (default ``True``) if ``True``, prints + - ``verbose`` -- boolean (default: ``True``); if ``True``, prints the defined shorthands EXAMPLES:: @@ -759,7 +759,7 @@ def e(self, *data): INPUT: - - ``*data`` -- a list of indices or pairs `(i, p)` + - ``*data`` -- list of indices or pairs `(i, p)` EXAMPLES:: @@ -855,7 +855,7 @@ def f(self, *data): INPUT: - - ``*data`` -- a list of indices or pairs `(i, p)` + - ``*data`` -- list of indices or pairs `(i, p)` EXAMPLES:: @@ -1819,7 +1819,7 @@ class A(CombinatorialFreeModule, BindableClass): INPUT: - - ``algorithm`` -- (default ``'GW'``) the algorithm to use when + - ``algorithm`` -- (default: ``'GW'``) the algorithm to use when computing this basis in the Fock space; the possible values are: * ``'GW'`` -- use the algorithm given by Goodman and Wenzl @@ -2020,7 +2020,7 @@ def _A_to_fock_basis(self, la): # For non-interior partitions # Construct the d's and the partition ``a`` - a = list(la) + [0]*(k - 1 - len(la)) # Add 0's to get the correct length + a = list(la) + [0]*(k - 1 - len(la)) # Add 0s to get the correct length a = [a[i] + (k - 1 - i) for i in range(k-1)] # Shift the diagram #shifted = list(a) # Make a copy of the shifted partition in case we need it later d = [(a[i] - a[i+1]) % n for i in range(k-2)] diff --git a/src/sage/algebras/quantum_groups/quantum_group_gap.py b/src/sage/algebras/quantum_groups/quantum_group_gap.py index 997fe0f3b04..05e4e1b6982 100644 --- a/src/sage/algebras/quantum_groups/quantum_group_gap.py +++ b/src/sage/algebras/quantum_groups/quantum_group_gap.py @@ -371,7 +371,7 @@ def __init__(self, cartan_type, q): sage: TestSuite(Q).run() # long time """ self._cartan_type = cartan_type - GapPackage("QuaGroup", spkg="gap_package_quagroup").require() + GapPackage("QuaGroup", spkg='gap_package_quagroup').require() libgap.LoadPackage('QuaGroup') R = libgap.eval('RootSystem("%s",%s)' % (cartan_type.type(), cartan_type.rank())) Q = self._cartan_type.root_system().root_lattice() @@ -1084,7 +1084,7 @@ def __init__(self, parent, im_gens, check=True): sage: Q = QuantumGroup(['A',1]) sage: F, K, Ki, E = Q.gens() sage: phi = Q.hom([E, Ki, K, F]) - sage: TestSuite(phi).run(skip="_test_category") + sage: TestSuite(phi).run(skip='_test_category') """ self._repr_type_str = "Quantum group homomorphism" Morphism.__init__(self, parent) @@ -1699,7 +1699,7 @@ def crystal_graph(self): G = DiGraph([vertices, edges], format='vertices_and_edges') from sage.graphs.dot2tex_utils import have_dot2tex if have_dot2tex(): - G.set_latex_options(format="dot2tex", + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=self._cartan_type._index_set_coloring) return G @@ -2073,7 +2073,7 @@ def lift(self): + q^-1*(F[a1+a2]*v0F[a1]*v0) + 1*(F[a1+a2]*v0F[a1+a2]*v0) """ return self.module_morphism(self._ambient_basis_map.__getitem__, - codomain=self._ambient, unitriangular="lower") + codomain=self._ambient, unitriangular='lower') def retract(self, elt): """ @@ -2153,7 +2153,7 @@ def crystal_graph(self, use_ambient=True): G = DiGraph([vertices, edges], format='vertices_and_edges') from sage.graphs.dot2tex_utils import have_dot2tex if have_dot2tex(): - G.set_latex_options(format="dot2tex", + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=self._cartan_type._index_set_coloring) return G @@ -2364,7 +2364,7 @@ def basis(self): F[a1]*F[a2]^(4) """ I = cartesian_product([NonNegativeIntegers()]*len(self._pos_roots)) - return Family(I, self._construct_monomial, name="monomial") + return Family(I, self._construct_monomial, name='monomial') def _construct_canonical_basis_elts(self, k): r""" diff --git a/src/sage/algebras/quantum_matrix_coordinate_algebra.py b/src/sage/algebras/quantum_matrix_coordinate_algebra.py index 4b08c36f45f..9ddde4376c8 100644 --- a/src/sage/algebras/quantum_matrix_coordinate_algebra.py +++ b/src/sage/algebras/quantum_matrix_coordinate_algebra.py @@ -983,11 +983,9 @@ def _generator_key(t): INPUT: - a tuple (index, exponent) + - ``t`` -- tuple (index, exponent) - OUTPUT: - - a tuple made from the index only + OUTPUT: a tuple made from the index only EXAMPLES:: diff --git a/src/sage/algebras/quatalg/quaternion_algebra.py b/src/sage/algebras/quatalg/quaternion_algebra.py index 93e22abd6fd..32353a688b6 100644 --- a/src/sage/algebras/quatalg/quaternion_algebra.py +++ b/src/sage/algebras/quatalg/quaternion_algebra.py @@ -287,7 +287,6 @@ def create_object(self, version, key, **extra_args): sage: QuaternionAlgebra.create_object("6.0", (QQ, -1, -1, ('i', 'j', 'k'))) Quaternion Algebra (-1, -1) with base ring Rational Field - """ K, a, b, names = key return QuaternionAlgebra_ab(K, a, b, names=names) @@ -451,7 +450,6 @@ def is_matrix_ring(self) -> bool: Traceback (most recent call last): ... NotImplementedError: base field must be rational numbers - """ if not isinstance(self.base_ring(), RationalField): raise NotImplementedError("base field must be rational numbers") @@ -630,7 +628,7 @@ class QuaternionAlgebra_ab(QuaternionAlgebra_abstract): - ``base_ring`` -- a commutative ring `K` in which 2 is invertible - ``a``, ``b`` -- units of `K` - - ``names`` -- string (default: ``'i,j,k'``) names of the generators + - ``names`` -- string (default: ``'i,j,k'``); names of the generators OUTPUT: @@ -706,16 +704,14 @@ def maximal_order(self, take_shortcuts=True, order_basis=None): INPUT: - - ``take_shortcuts`` -- (default: ``True``) if the discriminant is + - ``take_shortcuts`` -- boolean (default: ``True``); if the discriminant is prime and the invariants of the algebra are of a nice form, use Proposition 5.2 of [Piz1980]_. - ``order_basis`` -- (default: ``None``) a basis of an order of this quaternion algebra - OUTPUT: - - A maximal order in this quaternion algebra. + OUTPUT: a maximal order in this quaternion algebra EXAMPLES:: @@ -1050,7 +1046,7 @@ def invariants(self): def is_definite(self): """ - Checks whether the quaternion algebra ``self`` is definite, i.e. whether it ramifies at the + Check whether the quaternion algebra ``self`` is definite, i.e. whether it ramifies at the unique Archimedean place of its base field QQ. This is the case if and only if both invariants of ``self`` are negative. @@ -1073,7 +1069,7 @@ def is_definite(self): def __eq__(self, other): """ - Compare self and other. + Compare ``self`` and ``other``. EXAMPLES:: @@ -1089,7 +1085,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Compare self and other. + Compare ``self`` and ``other``. EXAMPLES:: @@ -1116,7 +1112,7 @@ def __hash__(self): def gen(self, i=0): """ - Return the `i^{th}` generator of ``self``. + Return the `i`-th generator of ``self``. INPUT: @@ -1320,7 +1316,7 @@ def quaternion_order(self, basis, check=True): INPUT: - ``basis`` -- list of 4 elements of ``self`` - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) EXAMPLES:: @@ -1348,9 +1344,9 @@ def ideal(self, gens, left_order=None, right_order=None, check=True, **kwds): INPUT: - - ``gens`` -- a list of elements of this quaternion order + - ``gens`` -- list of elements of this quaternion order - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - ``left_order`` -- a quaternion order or ``None`` @@ -1386,11 +1382,9 @@ def modp_splitting_data(self, p): INPUT: - - `p` -- unramified odd prime + - ``p`` -- unramified odd prime - OUTPUT: - - - 2-tuple of matrices over finite field + OUTPUT: 2-tuple of matrices over finite field EXAMPLES:: @@ -1489,7 +1483,7 @@ def modp_splitting_map(self, p): INPUT: - - `p` -- prime number + - ``p`` -- prime number EXAMPLES:: @@ -1517,7 +1511,7 @@ def phi(q): ############################################################ def unpickle_QuaternionAlgebra_v0(*key): """ - The 0th version of pickling for quaternion algebras. + The `0`-th version of pickling for quaternion algebras. EXAMPLES:: @@ -1683,7 +1677,6 @@ def _element_constructor_(self, x): False sage: j/2 in O False - """ y = self.quaternion_algebra()(x) if y not in self.unit_ideal(): @@ -1725,11 +1718,11 @@ def ngens(self): def gen(self, n): """ - Return the n-th generator. + Return the `n`-th generator. INPUT: - - ``n`` -- an integer between 0 and 3, inclusive. + - ``n`` -- integer between 0 and 3, inclusive EXAMPLES:: @@ -1926,9 +1919,7 @@ def free_module(self): inside the vector space corresponding to the ambient quaternion algebra. - OUTPUT: - - A free `\ZZ`-module of rank 4. + OUTPUT: a free `\ZZ`-module of rank 4 EXAMPLES:: @@ -2013,9 +2004,7 @@ def _left_ideal_basis(self, gens): - ``gens`` -- list of elements of ``self`` - OUTPUT: - - A list of four elements of ``self``. + OUTPUT: list of four elements of ``self`` EXAMPLES:: @@ -2080,12 +2069,12 @@ def left_ideal(self, gens, check=True, *, is_basis=False): INPUT: - - ``gens`` -- a list of elements of this quaternion order + - ``gens`` -- list of elements of this quaternion order - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - - ``is_basis`` -- bool (default: ``False``); if ``True`` then ``gens`` - must be a `\ZZ`-basis of the ideal + - ``is_basis`` -- boolean (default: ``False``); if ``True`` then + ``gens`` must be a `\ZZ`-basis of the ideal EXAMPLES:: @@ -2123,12 +2112,12 @@ def right_ideal(self, gens, check=True, *, is_basis=False): INPUT: - - ``gens`` -- a list of elements of this quaternion order + - ``gens`` -- list of elements of this quaternion order - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - - ``is_basis`` -- bool (default: ``False``); if ``True`` then ``gens`` - must be a `\ZZ`-basis of the ideal + - ``is_basis`` -- boolean (default: ``False``); if ``True`` then + ``gens`` must be a `\ZZ`-basis of the ideal EXAMPLES:: @@ -2268,12 +2257,10 @@ def ternary_quadratic_form(self, include_basis=False): INPUT: - - ``include_basis`` -- bool (default: ``False``), if True also + - ``include_basis`` -- boolean (default: ``False``); if ``True`` also return a basis for the dimension 3 subspace `G` - OUTPUT: - - - QuadraticForm + OUTPUT: QuadraticForm - optional basis for dimension 3 subspace @@ -2337,13 +2324,13 @@ def isomorphism_to(self, other, *, conjugator=False, B=10): INPUT: - - ``conjugator`` -- bool (default: ``False``), if True this + - ``conjugator`` -- boolean (default: ``False``); if ``True`` this method returns a single quaternion `\gamma \in O \cap O'` of minimal norm such that `O' = \gamma^{-1} O \gamma`, - rather than the ring isomorphism it defines. + rather than the ring isomorphism it defines - - ``B`` -- postive integer, bound on theta series - coefficients to rule out non isomorphic orders. + - ``B`` -- positive integer; bound on theta series + coefficients to rule out non isomorphic orders .. NOTE:: @@ -2575,7 +2562,7 @@ class QuaternionFractionalIdeal_rational(QuaternionFractionalIdeal): - ``basis`` -- tuple of length 4 of elements in of ambient quaternion algebra whose `\\ZZ`-span is an ideal - - ``check`` -- bool (default: ``True``); if ``False``, do no type + - ``check`` -- boolean (default: ``True``); if ``False``, do no type checking. """ def __init__(self, Q, basis, left_order=None, right_order=None, check=True): @@ -2622,12 +2609,10 @@ def scale(self, alpha, left=False): - `\alpha` -- element of quaternion algebra - - ``left`` -- bool (default: ``False``); if true multiply + - ``left`` -- boolean (default: ``False``); if ``True`` multiply `\alpha` on the left, otherwise multiply `\alpha` on the right - OUTPUT: - - - a new fractional ideal + OUTPUT: a new fractional ideal EXAMPLES:: @@ -2701,11 +2686,9 @@ def _compute_order(self, side='left'): INPUT: - - ``side`` -- 'left' or 'right' - - OUTPUT: + - ``side`` -- ``'left'`` or ``'right'`` - The left order if side='left'; the right order if side='right'. + OUTPUT: the left order if ``side='left'``; the right order if ``side='right'`` EXAMPLES:: @@ -2939,12 +2922,12 @@ def __hash__(self): @cached_method def basis_matrix(self): r""" - Return basis matrix `M` in Hermite normal form for self as a + Return basis matrix `M` in Hermite normal form for ``self`` as a matrix with rational entries. If `Q` is the ambient quaternion algebra, then the `\ZZ`-span of the rows of `M` viewed as linear combinations of Q.basis() = - `[1,i,j,k]` is the fractional ideal self. Also, + `[1,i,j,k]` is the fractional ideal ``self``. Also, ``M * M.denominator()`` is an integer matrix in Hermite normal form. OUTPUT: matrix over `\QQ` @@ -2963,12 +2946,11 @@ def basis_matrix(self): def reduced_basis(self): r""" - Let `I` = ``self`` be a fractional ideal in a (rational) definite quaternion algebra. - This function returns an LLL reduced basis of I. + Let `I` = ``self`` be a fractional ideal in a (rational) definite + quaternion algebra. This function returns an LLL reduced basis of `I`. - OUTPUT: - - - A tuple of four elements in I forming an LLL reduced basis of I as a lattice + OUTPUT: a tuple of four elements in `I` forming an LLL reduced basis of + `I` as a lattice EXAMPLES:: @@ -2997,15 +2979,13 @@ def reduced_basis(self): def theta_series_vector(self, B): r""" Return theta series coefficients of ``self``, as a vector - of ``B`` integers. + of `B` integers. INPUT: - ``B`` -- positive integer - OUTPUT: - - Vector over `\ZZ` with ``B`` entries. + OUTPUT: vector over `\ZZ` with `B` entries EXAMPLES:: @@ -3104,7 +3084,7 @@ def theta_series(self, B, var='q'): INPUT: - ``B`` -- positive integer - - ``var`` -- string (default: 'q') + - ``var`` -- string (default: ``'q'``) OUTPUT: power series @@ -3141,7 +3121,7 @@ def gram_matrix(self): r""" Return the Gram matrix of this fractional ideal. - OUTPUT: `4 \times 4` matrix over `\QQ`. + OUTPUT: `4 \times 4` matrix over `\QQ` EXAMPLES:: @@ -3200,7 +3180,7 @@ def norm(self): def conjugate(self): """ - Return the ideal with generators the conjugates of the generators for self. + Return the ideal with generators the conjugates of the generators for ``self``. OUTPUT: a quaternionic fractional ideal @@ -3219,7 +3199,7 @@ def __mul__(self, right): """ Return the product of the fractional ideals ``self`` and ``right``. - .. note:: + .. NOTE:: We do not keep track of left or right order structure. @@ -3290,9 +3270,7 @@ def free_module(self): r""" Return the underlying free `\ZZ`-module corresponding to this ideal. - OUTPUT: - - Free `\ZZ`-module of rank 4 embedded in an ambient `\QQ^4`. + OUTPUT: free `\ZZ`-module of rank 4 embedded in an ambient `\QQ^4` EXAMPLES:: @@ -3350,14 +3328,13 @@ def free_module(self): def intersection(self, J): """ - Return the intersection of the ideals self and `J`. + Return the intersection of the ideals ``self`` and `J`. EXAMPLES:: sage: X = BrandtModule(3,5).right_ideals() sage: I = X[0].intersection(X[1]); I Fractional ideal (2 + 6*j + 4*k, 2*i + 4*j + 34*k, 8*j + 32*k, 40*k) - """ V = self.free_module().intersection(J.free_module()) H, d = V.basis_matrix()._clear_denom() @@ -3367,13 +3344,13 @@ def intersection(self, J): def multiply_by_conjugate(self, J): """ - Return product of self and the conjugate Jbar of `J`. + Return product of ``self`` and the conjugate Jbar of `J`. INPUT: - - ``J`` -- a quaternion ideal. + - ``J`` -- a quaternion ideal - OUTPUT: a quaternionic fractional ideal. + OUTPUT: a quaternionic fractional ideal EXAMPLES:: @@ -3400,7 +3377,7 @@ def pushforward(self, J, side=None): - ``J`` -- a fractional quaternion ideal with norm coprime to ``self`` and either the same left order or right order as ``self`` - - ``side`` -- string (default: ``None``) set to ``"left"`` or ``"right"`` to + - ``side`` -- string (default: ``None``); set to ``'left'`` or ``'right'`` to perform pushforward of left or right ideals respectively. If ``None`` the side is determined by the matching left or right orders @@ -3414,7 +3391,7 @@ def pushforward(self, J, side=None): sage: I2 = B.ideal([1/2 + 9/2*j, 1/2*i + 9/2*k, 5*j, 5*k]) sage: I1.left_order() == I2.left_order() True - sage: I1.pushforward(I2, side="left") + sage: I1.pushforward(I2, side='left') Fractional ideal (1/2 + 3/2*j + 5*k, 1/10*i + 2*j + 39/10*k, 3*j, 15*k) TESTS:: @@ -3432,22 +3409,22 @@ def pushforward(self, J, side=None): sage: I2 = B.ideal([1/2 + 9/2*j, 1/2*i + 9/2*k, 5*j, 5*k]) sage: I1.pushforward(I2) Fractional ideal (1/2 + 3/2*j + 5*k, 1/10*i + 2*j + 39/10*k, 3*j, 15*k) - sage: I1.pushforward(I2, side="right") + sage: I1.pushforward(I2, side='right') Traceback (most recent call last): ... ValueError: self and J must have the same right orders sage: I1.conjugate().pushforward(I2.conjugate()) Fractional ideal (1/2 + 3/2*j + 10*k, 1/10*i + 2*j + 39/10*k, 3*j, 15*k) - sage: I1.conjugate().pushforward(I2.conjugate(), side="left") + sage: I1.conjugate().pushforward(I2.conjugate(), side='left') Traceback (most recent call last): ... ValueError: self and J must have the same left orders - sage: I1.pushforward(I1, side="left") + sage: I1.pushforward(I1, side='left') Traceback (most recent call last): ... ValueError: self and J must have coprime norms sage: I3 = B.ideal([1/2 + 13/2*j + 6*k, 1/2*i + 3*j + 13/2*k, 9*j, 9*k]) - sage: I3.pushforward(I3*(1/3), side="left") + sage: I3.pushforward(I3*(1/3), side='left') Traceback (most recent call last): ... NotImplementedError: quaternion ideal pushforward not implemented for non-integral ideals @@ -3468,7 +3445,7 @@ def pushforward(self, J, side=None): if side == "right": if self.right_order() != J.right_order(): raise ValueError("self and J must have the same right orders") - return self.conjugate().pushforward(J.conjugate(), side="left").conjugate() + return self.conjugate().pushforward(J.conjugate(), side='left').conjugate() if side is None: same_left_order = bool(self.left_order() == J.left_order()) @@ -3478,8 +3455,8 @@ def pushforward(self, J, side=None): if same_left_order and same_right_order: raise ValueError("self and J have same left and right orders, side of pushforward must be specified") if same_left_order: - return self.pushforward(J, side="left") - return self.pushforward(J, side="right") + return self.pushforward(J, side='left') + return self.pushforward(J, side='right') raise ValueError('side must be "left", "right" or None') @@ -3494,7 +3471,7 @@ def pullback(self, J, side=None): - ``J`` -- a fractional quaternion ideal with norm coprime to ``self`` and either left order equal to the right order of ``self``, or vice versa - - ``side`` -- string (default: ``None``) set to ``"left"`` or ``"right"`` to + - ``side`` -- string (default: ``None``); set to ``'left'`` or ``'right'`` to perform pullback of left or right ideals respectively. If ``None`` the side is determined by the matching left and right orders @@ -3506,10 +3483,10 @@ def pullback(self, J, side=None): sage: i,j,k = B.gens() sage: I1 = B.ideal([1/2 + 3/2*j + 2*k, 1/2*i + j + 3/2*k, 3*j, 3*k]) sage: I2 = B.ideal([1/2 + 9/2*j, 1/2*i + 9/2*k, 5*j, 5*k]) - sage: I3 = I1.pushforward(I2, side="left") + sage: I3 = I1.pushforward(I2, side='left') sage: I3.left_order() == I2.right_order() True - sage: I3.pullback(I2, side="left") == I1 + sage: I3.pullback(I2, side='left') == I1 True TESTS:: @@ -3527,22 +3504,22 @@ def pullback(self, J, side=None): sage: I2 = B.ideal([1/2 + 15/2*j + 2*k, 1/6*i + 43/3*j + 5/2*k, 15*j, 5*k]) sage: I2.pullback(I1) Fractional ideal (1/2 + 5/2*j + 2*k, 1/2*i + 3*j + 5/2*k, 5*j, 5*k) - sage: I2.pullback(I1, side="right") + sage: I2.pullback(I1, side='right') Traceback (most recent call last): ... ValueError: right order of self should be left order of J - sage: I2.conjugate().pullback(I1.conjugate(), side="right") + sage: I2.conjugate().pullback(I1.conjugate(), side='right') Fractional ideal (1/2 + 5/2*j + 3*k, 1/2*i + 3*j + 5/2*k, 5*j, 5*k) - sage: I2.conjugate().pullback(I1.conjugate(), side="left") + sage: I2.conjugate().pullback(I1.conjugate(), side='left') Traceback (most recent call last): ... ValueError: left order of self should be right order of J - sage: I1.pullback(I1.conjugate(), side="left") + sage: I1.pullback(I1.conjugate(), side='left') Traceback (most recent call last): ... ValueError: self and J must have coprime norms sage: I3 = B.ideal([1/2 + 13/2*j + 6*k, 1/2*i + 3*j + 13/2*k, 9*j, 9*k]) - sage: I3.pullback(I3.conjugate()*(1/3), side="left") + sage: I3.pullback(I3.conjugate()*(1/3), side='left') Traceback (most recent call last): ... NotImplementedError: quaternion ideal pullback not implemented for non-integral ideals @@ -3563,7 +3540,7 @@ def pullback(self, J, side=None): if side == "right": if self.right_order() != J.left_order(): raise ValueError("right order of self should be left order of J") - return self.conjugate().pullback(J.conjugate(), side="left").conjugate() + return self.conjugate().pullback(J.conjugate(), side='left').conjugate() if side is None: is_side_left = bool(self.left_order() == J.right_order()) @@ -3573,14 +3550,14 @@ def pullback(self, J, side=None): if is_side_left and is_side_right: raise ValueError("self and J have same left and right orders, side of pullback must be specified") if is_side_left: - return self.pullback(J, side="left") - return self.pullback(J, side="right") + return self.pullback(J, side='left') + return self.pullback(J, side='right') raise ValueError('side must be "left", "right" or None') def is_equivalent(self, J, B=10, certificate=False, side=None): r""" - Checks whether ``self`` and ``J`` are equivalent as ideals. + Check whether ``self`` and ``J`` are equivalent as ideals. Tests equivalence as right ideals by default. Requires the underlying rational quaternion algebra to be definite. @@ -3594,10 +3571,10 @@ def is_equivalent(self, J, B=10, certificate=False, side=None): - ``certificate`` -- if ``True`` returns an element alpha such that alpha*J = I or J*alpha = I for right and left ideals respectively - - ``side`` -- If ``'left'`` performs left equivalence test. If ``'right' + - ``side`` -- if ``'left'`` performs left equivalence test. If ``'right' ``or ``None`` performs right ideal equivalence test - OUTPUT: bool, or (bool, alpha) if ``certificate`` is ``True`` + OUTPUT: boolean, or (boolean, alpha) if ``certificate`` is ``True`` EXAMPLES:: @@ -3622,7 +3599,7 @@ def is_equivalent(self, J, B=10, certificate=False, side=None): def is_left_equivalent(self, J, B=10, certificate=False): r""" - Checks whether ``self`` and ``J`` are equivalent as left ideals. + Check whether ``self`` and ``J`` are equivalent as left ideals. Requires the underlying rational quaternion algebra to be definite. INPUT: @@ -3634,7 +3611,7 @@ def is_left_equivalent(self, J, B=10, certificate=False): - ``certificate`` -- if ``True`` returns an element alpha such that J*alpha=I - OUTPUT: bool, or (bool, alpha) if ``certificate`` is ``True`` + OUTPUT: boolean, or (boolean, alpha) if ``certificate`` is ``True`` """ if certificate: is_equiv, cert = self.conjugate().is_right_equivalent(J.conjugate(), B, True) @@ -3645,7 +3622,7 @@ def is_left_equivalent(self, J, B=10, certificate=False): def is_right_equivalent(self, J, B=10, certificate=False): r""" - Checks whether ``self`` and ``J`` are equivalent as right ideals. + Check whether ``self`` and ``J`` are equivalent as right ideals. Requires the underlying rational quaternion algebra to be definite. INPUT: @@ -3657,7 +3634,7 @@ def is_right_equivalent(self, J, B=10, certificate=False): - ``certificate`` -- if ``True`` returns an element alpha such that alpha*J=I - OUTPUT: bool, or (bool, alpha) if ``certificate`` is ``True`` + OUTPUT: boolean, or (boolean, alpha) if ``certificate`` is ``True`` EXAMPLES:: @@ -3717,16 +3694,16 @@ def is_right_equivalent(self, J, B=10, certificate=False): def is_principal(self, certificate=False): r""" - Checks whether ``self`` is principal as a full rank quaternion ideal. + Check whether ``self`` is principal as a full rank quaternion ideal. Requires the underlying quaternion algebra to be definite. Independent of whether ``self`` is a left or a right ideal. INPUT: - - ``certificate`` -- if ``True`` returns a generator alpha s.t. I = alpha*O - where O is the right order of I. + - ``certificate`` -- if ``True`` returns a generator alpha s.t. + `I = \alpha O` where `O` is the right order of `I` - OUTPUT: bool, or (bool, alpha) if ``certificate`` is ``True`` + OUTPUT: boolean, or (boolean, alpha) if ``certificate`` is ``True`` EXAMPLES:: @@ -3756,7 +3733,7 @@ def is_principal(self, certificate=False): def __contains__(self, x): """ - Return whether x is in self. + Return whether ``x`` is in ``self``. EXAMPLES:: @@ -3793,17 +3770,15 @@ def cyclic_right_subideals(self, p, alpha=None): ideals `J`. More precisely the `J`'s are the right annihilators of `(1,0) \alpha^i` for `i=0,1,2,...,p` - OUTPUT: - - - list of right ideals + OUTPUT: list of right ideals .. NOTE:: Currently, `p` must satisfy a bunch of conditions, or a - :class:`NotImplementedError` is raised. In particular, `p` must + :exc:`NotImplementedError` is raised. In particular, `p` must be odd and unramified in the quaternion algebra, must be coprime to the index of the right order in the maximal - order, and also coprime to the normal of self. (The Brandt + order, and also coprime to the normal of ``self``. (The Brandt modules code has a more general algorithm in some cases.) EXAMPLES:: @@ -3939,7 +3914,6 @@ def is_integral(self) -> bool: sage: I = R.ideal([1/2 + 2*j + 140*k, 2*i + 4*j + 150*k, 8*j + 104*k, 152*k]) sage: I.is_integral() False - """ if self.__left_order is not None: return self.free_module() <= self.left_order().free_module() @@ -4020,7 +3994,6 @@ def is_primitive(self) -> bool: True sage: (2*I).is_primitive() False - """ _, g = self.primitive_decomposition() return g.is_one() @@ -4055,7 +4028,6 @@ def basis_for_quaternion_lattice(gens, reverse=None): sage: basis_for_quaternion_lattice([A(1),i,j,k]) [1, i, j, k] - """ if reverse is None: from sage.misc.superseded import deprecation @@ -4133,8 +4105,8 @@ def normalize_basis_at_p(e, p, B=QuaternionAlgebraElement_abstract.pair): INPUT: - - ``e`` -- list; basis of a `\ZZ` module. - WARNING: will be modified! + - ``e`` -- list; basis of a `\ZZ` module + (WARNING: will be modified!) - ``p`` -- prime for at which the basis should be normalized @@ -4273,9 +4245,7 @@ def maxord_solve_aux_eq(a, b, p): - ``p`` -- even prime ideal (actually only ``p=ZZ(2)`` is implemented) - OUTPUT: - - - A tuple `(y, z, w)` + OUTPUT: a tuple `(y, z, w)` EXAMPLES:: diff --git a/src/sage/algebras/quatalg/quaternion_algebra_cython.pyx b/src/sage/algebras/quatalg/quaternion_algebra_cython.pyx index a0182d304ba..2b9b230242c 100644 --- a/src/sage/algebras/quatalg/quaternion_algebra_cython.pyx +++ b/src/sage/algebras/quatalg/quaternion_algebra_cython.pyx @@ -51,7 +51,7 @@ def integral_matrix_and_denom_from_rational_quaternions(v, reverse=False): INPUT: - - ``v`` -- a list of quaternions in a rational quaternion algebra + - ``v`` -- list of quaternions in a rational quaternion algebra - ``reverse`` -- whether order of the coordinates as well as the order of the list ``v`` should be reversed @@ -131,13 +131,11 @@ def rational_matrix_from_rational_quaternions(v, reverse=False): INPUT: - - ``v`` -- a list of quaternions in a rational quaternion algebra + - ``v`` -- list of quaternions in a rational quaternion algebra - ``reverse`` -- whether order of the coordinates as well as the order of the list ``v`` should be reversed - OUTPUT: - - - a matrix over `\QQ` + OUTPUT: a matrix over `\QQ` EXAMPLES:: diff --git a/src/sage/algebras/quatalg/quaternion_algebra_element.pyx b/src/sage/algebras/quatalg/quaternion_algebra_element.pyx index d17566c8c22..c7faef1a27f 100644 --- a/src/sage/algebras/quatalg/quaternion_algebra_element.pyx +++ b/src/sage/algebras/quatalg/quaternion_algebra_element.pyx @@ -144,8 +144,8 @@ cdef to_quaternion(R, x): INPUT: - - R -- callable - - x -- element or 4-tuple + - ``R`` -- callable + - ``x`` -- element or 4-tuple Given a callable R and an x that defines a quaternion, which can be a 4-tuple, list of length 4, or something that coerces to R, return @@ -168,9 +168,9 @@ cdef inline print_coeff(y, i, bint atomic): INPUT: - - y -- coefficient - - i -- string (name of a generator) - - atomic -- boolean int; whether or not elements of base ring + - ``y`` -- coefficient + - ``i`` -- string (name of a generator) + - ``atomic`` -- boolean int; whether or not elements of base ring print atomically EXAMPLES:: @@ -222,11 +222,10 @@ cdef class QuaternionAlgebraElement_abstract(AlgebraElement): cpdef bint is_constant(self) noexcept: """ - Return True if this quaternion is constant, i.e., has no i, j, or k term. + Return ``True`` if this quaternion is constant, i.e., has no `i`, `j`, + or `k` term. - OUTPUT: - - bool + OUTPUT: boolean EXAMPLES:: @@ -541,7 +540,7 @@ cdef class QuaternionAlgebraElement_abstract(AlgebraElement): cpdef _div_(self, right): """ - Return quotient of self by right. + Return quotient of ``self`` by ``right``. EXAMPLES:: @@ -564,7 +563,8 @@ cdef class QuaternionAlgebraElement_abstract(AlgebraElement): INPUT: - - var -- string (default: 'x'); indeterminate of characteristic polynomial + - ``var`` -- string (default: ``'x'``); indeterminate of characteristic + polynomial EXAMPLES:: @@ -585,19 +585,17 @@ cdef class QuaternionAlgebraElement_abstract(AlgebraElement): def matrix(self, action='right'): """ - Return the matrix of right or left multiplication of self on + Return the matrix of right or left multiplication of ``self`` on the basis for the ambient quaternion algebra. - In particular, if action is 'right' (the default), returns the - matrix of the mapping sending x to x*self. + In particular, if action is ``'right'`` (the default), returns the + matrix of the mapping sending ``x`` to ``x*self``. INPUT: - - ``action`` -- (default: 'right') 'right' or 'left'. - - OUTPUT: + - ``action`` -- (default: ``'right'``) ``'right'`` or ``'left'`` - - a matrix + OUTPUT: a matrix EXAMPLES:: @@ -661,9 +659,9 @@ cdef class QuaternionAlgebraElement_abstract(AlgebraElement): def pair(self, right): """ - Return the result of pairing self and right, which should both + Return the result of pairing ``self`` and ``right``, which should both be elements of a quaternion algebra. The pairing is - (x,y) = (x.conjugate()*y).reduced_trace(). + ``(x,y) = (x.conjugate()*y).reduced_trace()``. INPUT: @@ -796,7 +794,7 @@ cdef class QuaternionAlgebraElement_generic(QuaternionAlgebraElement_abstract): cpdef _add_(self, _right): """ - Return the sum of self and _right. + Return the sum of ``self`` and ``_right``. EXAMPLES:: @@ -812,7 +810,7 @@ cdef class QuaternionAlgebraElement_generic(QuaternionAlgebraElement_abstract): cpdef _sub_(self, _right): """ - Return the difference of self and _right. + Return the difference of ``self`` and ``_right``. EXAMPLES:: @@ -827,7 +825,7 @@ cdef class QuaternionAlgebraElement_generic(QuaternionAlgebraElement_abstract): cpdef _mul_(self, _right): """ - Return the product of self and _right. + Return the product of ``self`` and ``_right``. EXAMPLES:: @@ -955,11 +953,10 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst cpdef bint is_constant(self) noexcept: """ - Return True if this quaternion is constant, i.e., has no i, j, or k term. + Return ``True`` if this quaternion is constant, i.e., has no `i`, `j`, + or `k` term. - OUTPUT: - - bool + OUTPUT: boolean EXAMPLES:: @@ -977,7 +974,7 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst def __bool__(self): """ - Return True if this quaternion is nonzero. + Return ``True`` if this quaternion is nonzero. EXAMPLES:: @@ -1145,7 +1142,6 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst sage: loads(dumps(theta)) == theta True - """ return (unpickle_QuaternionAlgebraElement_rational_field_v0, (self._parent, (self[0], self[1], self[2], self[3]))) @@ -1436,7 +1432,7 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst """ Return the reduced trace of ``self``. - This is `2x` if self is `x+iy+zj+wk`. + This is `2x` if ``self`` is `x+iy+zj+wk`. EXAMPLES:: @@ -1523,9 +1519,7 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst is equal to `(x + yi + zj + wk)/d` and x, y, z, w do not share a common factor with d. - OUTPUT: - - 5-tuple of Integers + OUTPUT: 5-tuple of Integers EXAMPLES:: @@ -1551,9 +1545,7 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst """ Return the integer part of this quaternion, ignoring the common denominator. - OUTPUT: - - 4-tuple of Integers + OUTPUT: 4-tuple of Integers EXAMPLES:: @@ -1606,7 +1598,7 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst def _multiply_by_integer(self, Integer n): """ - Return the product of self times the integer n. + Return the product of ``self`` times the integer `n`. EXAMPLES:: @@ -1643,7 +1635,7 @@ cdef class QuaternionAlgebraElement_rational_field(QuaternionAlgebraElement_abst def _divide_by_integer(self, Integer n): """ - Return the quotient of self by the integer n. + Return the quotient of ``self`` by the integer `n`. EXAMPLES:: @@ -1814,7 +1806,7 @@ cdef class QuaternionAlgebraElement_number_field(QuaternionAlgebraElement_abstra cpdef _add_(self, _right): """ - Add self and _right: + Add ``self`` and ``_right``: EXAMPLES:: @@ -1888,7 +1880,7 @@ cdef class QuaternionAlgebraElement_number_field(QuaternionAlgebraElement_abstra cpdef _sub_(self, _right): """ - Subtract _right from self. + Subtract ``_right`` from ``self``. EXAMPLES:: @@ -1939,7 +1931,7 @@ cdef class QuaternionAlgebraElement_number_field(QuaternionAlgebraElement_abstra cpdef _mul_(self, _right): """ - Multiply self and _right. + Multiply ``self`` and ``_right``. EXAMPLES:: diff --git a/src/sage/algebras/quaternion_algebra.py b/src/sage/algebras/quaternion_algebra.py index 4e92b73de69..a9fd6aff827 100644 --- a/src/sage/algebras/quaternion_algebra.py +++ b/src/sage/algebras/quaternion_algebra.py @@ -6,7 +6,7 @@ def unpickle_QuaternionAlgebra_v0(*key): """ - The 0th version of pickling for quaternion algebras. + The `0`-th version of pickling for quaternion algebras. EXAMPLES:: diff --git a/src/sage/algebras/schur_algebra.py b/src/sage/algebras/schur_algebra.py index 6e0b6ad8583..b967064e565 100644 --- a/src/sage/algebras/schur_algebra.py +++ b/src/sage/algebras/schur_algebra.py @@ -155,9 +155,7 @@ def schur_representative_from_index(i0, i1): - A pair of tuples of length `r` with elements in `\{1,\dots,n\}` - OUTPUT: - - - The corresponding pair of tuples ordered correctly. + OUTPUT: the corresponding pair of tuples ordered correctly EXAMPLES:: @@ -182,7 +180,7 @@ class SchurAlgebra(CombinatorialFreeModule): A Schur algebra. Let `R` be a commutative ring, `n` be a positive integer, and `r` - be a non-negative integer. Define `A_R(n,r)` to be the set of + be a nonnegative integer. Define `A_R(n,r)` to be the set of homogeneous polynomials of degree `r` in `n^2` variables `x_{ij}`. Therefore we can write `R[x_{ij}] = \bigoplus_{r \geq 0} A_R(n,r)`, and `R[x_{ij}]` is known to be a bialgebra with coproduct given by @@ -225,7 +223,7 @@ def __init__(self, R, n, r): sage: SchurAlgebra(ZZ, 2, -2) Traceback (most recent call last): ... - ValueError: r (=-2) must be a non-negative integer + ValueError: r (=-2) must be a nonnegative integer sage: SchurAlgebra('niet', 2, 2) Traceback (most recent call last): ... @@ -234,7 +232,7 @@ def __init__(self, R, n, r): if n not in ZZ or n <= 0: raise ValueError("n (={}) must be a positive integer".format(n)) if r not in ZZ or r < 0: - raise ValueError("r (={}) must be a non-negative integer".format(r)) + raise ValueError("r (={}) must be a nonnegative integer".format(r)) if R not in Rings.Commutative(): raise ValueError("R (={}) must be a commutative ring".format(R)) @@ -543,13 +541,11 @@ def GL_irreducible_character(n, mu, KK): INPUT: - - ``n`` -- a positive integer - - ``mu`` -- a partition of at most ``n`` parts + - ``n`` -- positive integer + - ``mu`` -- a partition of at most `n` parts - ``KK`` -- a field - OUTPUT: - - a symmetric function which should be interpreted in ``n`` + OUTPUT: a symmetric function which should be interpreted in `n` variables to be meaningful as a character EXAMPLES: diff --git a/src/sage/algebras/shuffle_algebra.py b/src/sage/algebras/shuffle_algebra.py index 2db55513d66..adee056035c 100644 --- a/src/sage/algebras/shuffle_algebra.py +++ b/src/sage/algebras/shuffle_algebra.py @@ -171,7 +171,7 @@ def __init__(self, R, names, prefix): self.__ngens = self._alphabet.cardinality() cat = GradedHopfAlgebrasWithBasis(R).Commutative().Connected() CombinatorialFreeModule.__init__(self, R, Words(names, infinite=False), - latex_prefix="", prefix=prefix, + latex_prefix='', prefix=prefix, category=cat) def variable_names(self): @@ -241,7 +241,7 @@ def product_on_basis(self, w1, w2): INPUT: - - ``w1``, ``w2`` -- Basis elements + - ``w1``, ``w2`` -- basis elements EXAMPLES:: @@ -285,7 +285,7 @@ def gen(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: diff --git a/src/sage/algebras/splitting_algebra.py b/src/sage/algebras/splitting_algebra.py index 1ba73baf9cb..6fe2880d825 100644 --- a/src/sage/algebras/splitting_algebra.py +++ b/src/sage/algebras/splitting_algebra.py @@ -138,11 +138,11 @@ class SplittingAlgebra(PolynomialQuotientRing_domain): INPUT: - ``monic_polynomial`` -- the monic polynomial which should be split - - ``names`` -- names for the indeterminates to be adjoined to the + - ``names`` -- names for the indeterminates to be adjoined to the base ring of ``monic_polynomial`` - - ``warning`` -- (default: ``True``) can be used (by setting to ``False``) - to suppress a warning which will be thrown whenever it cannot be - checked that the Galois group of ``monic_polynomial`` is maximal + - ``warning`` -- boolean (default: ``True``); can be used (by setting to + ``False``) to suppress a warning which will be thrown whenever it cannot + be checked that the Galois group of ``monic_polynomial`` is maximal EXAMPLES:: @@ -524,7 +524,8 @@ def hom(self, im_gens, codomain=None, check=True, base_map=None): def is_completely_split(self): r""" - Return True if the defining polynomial of ``self`` splits into linear factors over ``self``. + Return ``True`` if the defining polynomial of ``self`` splits into + linear factors over ``self``. EXAMPLES:: @@ -576,7 +577,7 @@ def splitting_roots(self): @cached_method def scalar_base_ring(self): r""" - Return the ring of scalars of ``self`` (considered as an algebra) + Return the ring of scalars of ``self`` (considered as an algebra). EXAMPLES:: @@ -637,16 +638,16 @@ def solve_with_extension(monic_polynomial, root_names=None, var='x', flatten=Fal INPUT: - ``monic_polynomial`` -- the monic polynomial whose roots should be created - - ``root_names`` -- names for the indeterminates needed to define the + - ``root_names`` -- names for the indeterminates needed to define the splitting algebra of the ``monic_polynomial`` (if necessary and possible) - - ``var`` -- (default: ``'x'``) for the indeterminate needed to define the + - ``var`` -- (default: ``'x'``) for the indeterminate needed to define the splitting field of the ``monic_polynomial`` (if necessary and possible) - - ``flatten`` -- (default: ``True``) if ``True`` the roots will not be - given as a list of pairs ``(root, multiplicity)`` but as a list of + - ``flatten`` -- boolean (default: ``True``); if ``True`` the roots will + not be given as a list of pairs ``(root, multiplicity)`` but as a list of roots repeated according to their multiplicity - - ``warning`` -- (default: ``True``) can be used (by setting to ``False``) - to suppress a warning which will be thrown whenever it cannot be checked - that the Galois group of ``monic_polynomial`` is maximal + - ``warning`` -- boolean (default: ``True``); can be used (by setting to + ``False``) to suppress a warning which will be thrown whenever it cannot + be checked that the Galois group of ``monic_polynomial`` is maximal OUTPUT: @@ -682,9 +683,10 @@ def create_roots(monic_polynomial, warning=True): - ``monic_polynomial`` -- the monic polynomial whose roots should be created - - ``warning`` -- (default: ``True``) can be used (by setting to ``False``) - to suppress a warning which will be thrown whenever it cannot be - checked that the Galois group of ``monic_polynomial`` is maximal + - ``warning`` -- boolean (default: ``True``); can be used (by setting + to ``False``) to suppress a warning which will be thrown whenever it + cannot be checked that the Galois group of ``monic_polynomial`` is + maximal """ parent = monic_polynomial.parent() base_ring = parent.base_ring() diff --git a/src/sage/algebras/steenrod/steenrod_algebra.py b/src/sage/algebras/steenrod/steenrod_algebra.py index f559e9380bc..7e4c3dc014f 100644 --- a/src/sage/algebras/steenrod/steenrod_algebra.py +++ b/src/sage/algebras/steenrod/steenrod_algebra.py @@ -23,7 +23,7 @@ `\mathbf{F}_p`-algebra; when `p=2`, it is generated by elements `\text{Sq}^i` for `i\geq 0` (the *Steenrod squares*), and when `p` is odd, it is generated by elements `\mathcal{P}^i` for `i \geq 0` (the -*Steenrod reduced pth powers*) along with an element `\beta` (the *mod +*Steenrod reduced `p`-th powers*) along with an element `\beta` (the *mod p Bockstein*). The Steenrod algebra is graded: `\text{Sq}^i` is in degree `i` for each `i`, `\beta` is in degree 1, and `\mathcal{P}^i` is in degree `2(p-1)i`. @@ -55,10 +55,10 @@ - The *Milnor basis*. When `p=2`, the Milnor basis consists of symbols of the form `\text{Sq}(m_1, m_2, ..., m_t)`, where each `m_i` is a - non-negative integer and if `t>1`, then the last entry `m_t > 0`. + nonnegative integer and if `t>1`, then the last entry `m_t > 0`. When `p` is odd, the Milnor basis consists of symbols of the form `Q_{e_1} Q_{e_2} ... \mathcal{P}(m_1, m_2, ..., m_t)`, where `0 \leq - e_1 < e_2 < ...`, each `m_i` is a non-negative integer, and if + e_1 < e_2 < ...`, each `m_i` is a nonnegative integer, and if `t>1`, then the last entry `m_t > 0`. When `p=2`, it can be convenient to use the notation @@ -78,12 +78,12 @@ exceptions are the `P^s_t`-bases and the commutator bases, which are defined at all primes. -- *Wood's Y basis*. For pairs of non-negative integers `(m,k)`, let +- *Wood's Y basis*. For pairs of nonnegative integers `(m,k)`, let `w(m,k) = \text{Sq}^{2^m (2^{k+1}-1)}`. Wood's `Y` basis consists of monomials `w(m_0,k_0) ... w(m_t, k_t)` with `(m_i,k_i) > (m_{i+1},k_{i+1})`, in left lex order. -- *Wood's Z basis*. For pairs of non-negative integers `(m,k)`, let +- *Wood's Z basis*. For pairs of nonnegative integers `(m,k)`, let `w(m,k) = \text{Sq}^{2^m (2^{k+1}-1)}`. Wood's `Z` basis consists of monomials `w(m_0,k_0) ... w(m_t, k_t)` with `(m_i+k_i,m_i) > (m_{i+1}+k_{i+1},m_{i+1})`, in left lex order. @@ -184,8 +184,8 @@ A_* /(\xi_1^{2^{e_1}}, \xi_2^{2^{e_2}}, \xi_3^{2^{e_3}}, ...). The list of exponents `(e_1, e_2, ...)` may be considered a function -`e` from the positive integers to the extended non-negative integers -(the non-negative integers and `\infty`); this is called the *profile +`e` from the positive integers to the extended nonnegative integers +(the nonnegative integers and `\infty`); this is called the *profile function* for the sub-Hopf algebra. The profile function must satisfy the condition @@ -205,7 +205,7 @@ A_* / (\xi_1^{p^{e_1}}, \xi_2^{p^{e_2}}, ...; \tau_0^{k_0}, \tau_1^{k_1}, ...). Here the profile function has two pieces, `e` as at the prime 2, and -`k`, which maps the non-negative integers to the set `\{1, 2\}`. +`k`, which maps the nonnegative integers to the set `\{1, 2\}`. These must satisfy the following conditions: - `e(r) \geq \min( e(r-i) - i, e(i))` for all `0 < i < r`. @@ -232,7 +232,7 @@ Sq(1,2) + Sq(4,1) sage: Sq(4) * Sq(1,2) Sq(1,1,1) + Sq(2,3) + Sq(5,2) - sage: z**2 # non-negative exponents work as they should + sage: z**2 # nonnegative exponents work as they should Sq(1,2,1) + Sq(4,1,1) sage: z**0 1 @@ -680,7 +680,7 @@ def _basis_key_iterator(self): def prime(self): r""" - The prime associated to self. + The prime associated to ``self``. EXAMPLES:: @@ -693,7 +693,7 @@ def prime(self): def basis_name(self): r""" - The basis name associated to self. + The basis name associated to ``self``. EXAMPLES:: @@ -708,7 +708,7 @@ def basis_name(self): def _has_nontrivial_profile(self): r""" - True if the profile function for this algebra seems to be that + Return ``True`` if the profile function for this algebra seems to be that for a proper sub-Hopf algebra of the Steenrod algebra. EXAMPLES:: @@ -818,7 +818,7 @@ def _repr_term(self, t): INPUT: - - ``t`` -- tuple, representing basis element in the current basis. + - ``t`` -- tuple, representing basis element in the current basis OUTPUT: string @@ -909,7 +909,7 @@ def _latex_term(self, t): INPUT: - - ``t`` -- tuple, representing basis element in the current basis. + - ``t`` -- tuple, representing basis element in the current basis OUTPUT: string @@ -957,8 +957,8 @@ def profile(self, i, component=0): INPUT: - - `i` -- integer - - ``component`` -- either 0 or 1, optional (default 0) + - ``i`` -- integer + - ``component`` -- either 0 or 1 (default: 0) OUTPUT: integer or `\infty` @@ -972,7 +972,7 @@ def profile(self, i, component=0): of the aforementioned documentation), corresponding, respectively to ``component=0`` and ``component=1``. So when `p` is odd and ``component`` is 0, `i` must be positive, while - when ``component`` is 1, `i` must be non-negative. + when ``component`` is 1, `i` must be nonnegative. EXAMPLES:: @@ -1034,15 +1034,13 @@ def profile(self, i, component=0): def homogeneous_component(self, n): """ - Return the nth homogeneous piece of the Steenrod algebra. + Return the `n`-th homogeneous piece of the Steenrod algebra. INPUT: - - `n` -- integer + - ``n`` -- integer - OUTPUT: - - a vector space spanned by the basis for this algebra in dimension `n` + OUTPUT: a vector space spanned by the basis for this algebra in dimension `n` EXAMPLES:: @@ -1127,7 +1125,7 @@ def one_basis(self): def product_on_basis(self, t1, t2): """ - The product of two basis elements of this algebra + The product of two basis elements of this algebra. INPUT: @@ -1230,7 +1228,7 @@ def product_on_basis(self, t1, t2): def coproduct_on_basis(self, t, algorithm=None): r""" - The coproduct of a basis element of this algebra + The coproduct of a basis element of this algebra. INPUT: @@ -1279,7 +1277,7 @@ def coproduct_on_basis(self, t, algorithm=None): """ def coprod_list(t): """ - if t = (n0, n1, ...), then return list of terms (i0, i1, + If t = (n0, n1, ...), then return list of terms (i0, i1, ...) where ik <= nk for each k. From each such term, can recover the second factor in the coproduct. """ @@ -1437,7 +1435,7 @@ def coprod(x): def antipode_on_basis(self, t): r""" - The antipode of a basis element of this algebra + The antipode of a basis element of this algebra. INPUT: @@ -1565,7 +1563,7 @@ def _milnor_on_basis(self, t): INPUT: - - ``t`` -- tuple, representing basis element in the current basis. + - ``t`` -- tuple, representing basis element in the current basis OUTPUT: element of the Steenrod algebra with the Milnor basis @@ -1718,11 +1716,11 @@ def _milnor_on_basis(self, t): @lazy_attribute def milnor(self): """ - Convert an element of this algebra to the Milnor basis + Convert an element of this algebra to the Milnor basis. INPUT: - - x -- an element of this algebra + - ``x`` -- an element of this algebra OUTPUT: x converted to the Milnor basis @@ -1744,12 +1742,12 @@ def _change_basis_on_basis(self, t, basis='milnor'): INPUT: - - ``t`` -- tuple, representing basis element in the current basis. + - ``t`` -- tuple, representing basis element in the current basis - ``basis`` -- string, the basis to which to convert, optional - (default 'milnor') + (default: ``'milnor'``) - OUTPUT: an element of the Steenrod algebra with basis ``basis``. + OUTPUT: an element of the Steenrod algebra with basis ``basis`` ALGORITHM: it's straightforward to convert to the Milnor basis (using :meth:`milnor` or :meth:`_milnor_on_basis`), so it's @@ -1822,16 +1820,16 @@ def _change_basis_on_basis(self, t, basis='milnor'): def _change_basis(self, x, basis='milnor'): """ - Convert an element of this algebra to the specified basis + Convert an element of this algebra to the specified basis. INPUT: - - ``x`` -- an element of this algebra. + - ``x`` -- an element of this algebra - ``basis`` -- string, the basis to which to convert, optional - (default 'milnor') + (default: ``'milnor'``) - OUTPUT: an element of the Steenrod algebra with basis ``basis``. + OUTPUT: an element of the Steenrod algebra with basis ``basis`` ALGORITHM: use :meth:`_change_basis_on_basis` and linearity @@ -1862,9 +1860,9 @@ def degree_on_basis(self, t): INPUT: - - ``t`` -- tuple, representing basis element in the current basis. + - ``t`` -- tuple, representing basis element in the current basis - OUTPUT: integer, the degree of the corresponding element. + OUTPUT: integer, the degree of the corresponding element The degree of `\text{Sq}(i_1,i_2,i_3,...)` is @@ -1993,11 +1991,12 @@ def q_degree(m, prime=3): def _coerce_map_from_(self, S): r""" - True if there is a coercion from ``S`` to ``self``, False otherwise. + Return ``True`` if there is a coercion from ``S`` to ``self``, ``False`` + otherwise. INPUT: - - ``S`` -- a Sage object. + - ``S`` -- a Sage object The algebras that coerce into the mod p Steenrod algebra are: @@ -2090,7 +2089,7 @@ def _element_constructor_(self, x): - ``x`` -- an element of some Steenrod algebra or an element of `\ZZ` or `\GF{p}` or a dict - OUTPUT: ``x`` as a member of ``self``. + OUTPUT: ``x`` as a member of ``self`` If ``x`` is a dict, then call :meth:`_from_dict` on it, coercing the coefficients into the base field. That is, treat @@ -2136,7 +2135,7 @@ def _element_constructor_(self, x): def __contains__(self, x): r""" - True if self contains x. + Return ``True`` if ``self`` contains `x`. EXAMPLES:: @@ -2192,7 +2191,7 @@ def basis(self, d=None): INPUT: - - `d` -- integer or ``None``, optional (default ``None``) + - ``d`` -- integer or ``None`` (default: ``None``) OUTPUT: @@ -2263,12 +2262,12 @@ def basis(self, d=None): def _check_profile_on_basis(self, t): """ - True if the element specified by the tuple ``t`` is in this + Return ``True`` if the element specified by the tuple ``t`` is in this algebra. INPUT: - - ``t`` -- tuple of ... + - ``t`` -- tuple EXAMPLES:: @@ -2310,11 +2309,11 @@ def _check_profile_on_basis(self, t): def P(self, *nums): r""" - The element `P(a, b, c, ...)` + The element `P(a, b, c, \ldots)`. INPUT: - - ``a``, ``b``, ``c``, ... -- non-negative integers + - ``a``, ``b``, ``c``, ... -- nonnegative integers OUTPUT: @@ -2335,7 +2334,7 @@ def P(self, *nums): sage: B.P(1,1,-12,1) Traceback (most recent call last): ... - TypeError: entries must be non-negative integers + TypeError: entries must be nonnegative integers sage: SteenrodAlgebra(basis='serre-cartan').P(0,1) Sq^2 Sq^1 + Sq^3 @@ -2353,7 +2352,7 @@ def P(self, *nums): try: assert Integer(i) >= 0 except (TypeError, AssertionError): - raise TypeError("entries must be non-negative integers") + raise TypeError("entries must be nonnegative integers") if not self._generic: t = nums @@ -2374,7 +2373,7 @@ def Q_exp(self, *nums): - ``e0``, ``e1``, ... -- sequence of 0s and 1s - OUTPUT: The element `Q_0^{e_0} Q_1^{e_1} ...` + OUTPUT: the element `Q_0^{e_0} Q_1^{e_1} ...` Note that at the prime 2, `Q_n` is the element `\text{Sq}(0,0,...,1)` , where the 1 is in the @@ -2401,7 +2400,7 @@ def Q_exp(self, *nums): """ if not all(x in (0, 1) for x in nums): raise ValueError("The tuple %s should consist " % (nums,) + - "only of 0's and 1's") + "only of 0s and 1s") else: if self.basis_name() != 'milnor': return self(SteenrodAlgebra(p=self.prime(), @@ -2426,9 +2425,9 @@ def Q(self, *nums): INPUT: - - ``n0``, ``n1``, ... -- non-negative integers + - ``n0``, ``n1``, ... -- nonnegative integers - OUTPUT: The element `Q_{n0} Q_{n1} ...` + OUTPUT: the element `Q_{n0} Q_{n1} ...` Note that at the prime 2, `Q_n` is the element `\text{Sq}(0,0,...,1)` , where the 1 is in the @@ -2540,11 +2539,11 @@ def pst(self,s,t): INPUT: - - ``s`` -- non-negative integer + - ``s`` -- nonnegative integer - - ``t`` -- positive integer + - ``t`` -- positive integer - - ``p`` -- positive prime number + - ``p`` -- positive prime number OUTPUT: element of the Steenrod algebra @@ -2567,7 +2566,7 @@ def pst(self,s,t): if self.basis_name() != 'milnor': return self(SteenrodAlgebra(p=self.prime(),generic=self._generic).pst(s,t)) if not isinstance(s, (Integer, int)) and s >= 0: - raise ValueError("%s is not a non-negative integer" % s) + raise ValueError("%s is not a nonnegative integer" % s) if not isinstance(t, (Integer, int)) and t > 0: raise ValueError("%s is not a positive integer" % t) nums = (0,)*(t-1) + (self.prime()**s,) @@ -2690,17 +2689,17 @@ def gens(self): def gen(self, i=0): r""" - The ith generator of this algebra. + The `i`-th generator of this algebra. INPUT: - - ``i`` -- non-negative integer + - ``i`` -- nonnegative integer - OUTPUT: the ith generator of this algebra + OUTPUT: the `i`-th generator of this algebra - For the full Steenrod algebra, the `i^{th}` generator is - `\text{Sq}(2^i)` at the prime 2; when `p` is odd, the 0th generator - is `\beta = Q(0)`, and for `i>0`, the `i^{th}` generator is + For the full Steenrod algebra, the `i`-th generator is + `\text{Sq}(2^i)` at the prime 2; when `p` is odd, the `0`-th generator + is `\beta = Q(0)`, and for `i>0`, the `i`-th generator is `P(p^{i-1})`. For sub-Hopf algebras of the Steenrod algebra, it is not @@ -2758,7 +2757,7 @@ def gen(self, i=0): from sage.rings.integer import Integer p = self.prime() if not isinstance(i, (Integer, int)) and i >= 0: - raise ValueError("%s is not a non-negative integer" % i) + raise ValueError("%s is not a nonnegative integer" % i) num = self.ngens() if num < Infinity: if i >= num: @@ -2830,7 +2829,7 @@ def gen(self, i=0): def is_commutative(self): r""" - True if ``self`` is graded commutative, as determined by the + Return ``True`` if ``self`` is graded commutative, as determined by the profile function. In particular, a sub-Hopf algebra of the mod 2 Steenrod algebra is commutative if and only if there is an integer `n>0` so that its profile function `e` satisfies @@ -2882,7 +2881,7 @@ def is_commutative(self): def is_finite(self): r""" - True if this algebra is finite-dimensional. + Return ``True`` if this algebra is finite-dimensional. Therefore true if the profile function is finite, and in particular the ``truncation_type`` must be finite. @@ -3131,7 +3130,7 @@ class Element(CombinatorialFreeModule.Element): """ def prime(self): """ - The prime associated to self. + The prime associated to ``self``. EXAMPLES:: @@ -3150,7 +3149,7 @@ def prime(self): def basis_name(self): """ - The basis name associated to self. + The basis name associated to ``self``. EXAMPLES:: @@ -3171,7 +3170,7 @@ def basis_name(self): def is_homogeneous(self): """ - Return True iff this element is homogeneous. + Return ``True`` iff this element is homogeneous. EXAMPLES:: @@ -3194,7 +3193,7 @@ def is_homogeneous(self): def degree(self): r""" - The degree of self. + The degree of ``self``. The degree of `\text{Sq}(i_1,i_2,i_3,...)` is @@ -3288,9 +3287,9 @@ def change_basis(self, basis='milnor'): INPUT: - - ``basis`` -- string, basis in which to work. + - ``basis`` -- string; basis in which to work - OUTPUT: representation of self in given basis + OUTPUT: representation of ``self`` in given basis The choices for ``basis`` are: @@ -3332,7 +3331,7 @@ def change_basis(self, basis='milnor'): def _basis_dictionary(self, basis): r""" - Convert self to ``basis``, returning a dictionary of terms of + Convert ``self`` to ``basis``, returning a dictionary of terms of the form (mono: coeff), where mono is a monomial in the given basis. @@ -3460,7 +3459,7 @@ def excess(self): r""" Excess of element. - OUTPUT: ``excess`` -- non-negative integer + OUTPUT: ``excess`` -- nonnegative integer The excess of a Milnor basis element `\text{Sq}(a,b,c,...)` is `a + b + c + \cdots`. When `p` is odd, the excess of `Q_{0}^{e_0} @@ -3517,9 +3516,9 @@ def excess_odd(mono): return min(excesses) def is_unit(self): - """ - True if element has a nonzero scalar multiple of P(0) as a summand, - False otherwise. + r""" + Return ``True`` if element has a nonzero scalar multiple of + `P(0)` as a summand, ``False`` otherwise. EXAMPLES:: @@ -3540,7 +3539,7 @@ def is_unit(self): def is_nilpotent(self): """ - True if element is not a unit, False otherwise. + Return ``True`` if element is not a unit, ``False`` otherwise. EXAMPLES:: @@ -3559,7 +3558,7 @@ def may_weight(self): r""" May's 'weight' of element. - OUTPUT: ``weight`` -- non-negative integer + OUTPUT: ``weight`` -- nonnegative integer If we let `F_* (A)` be the May filtration of the Steenrod algebra, the weight of an element `x` is the integer `k` so @@ -3635,10 +3634,10 @@ def may_weight(self): def is_decomposable(self): r""" - Return True if element is decomposable, False otherwise. + Return ``True`` if element is decomposable, ``False`` otherwise. That is, if element is in the square of the augmentation ideal, - return True; otherwise, return False. + return ``True``; otherwise, return ``False``. OUTPUT: boolean @@ -3685,12 +3684,12 @@ def wall_height(self): r""" Wall's 'height' of element. - OUTPUT: list of non-negative integers + OUTPUT: list of nonnegative integers The height of an element of the mod 2 Steenrod algebra is a - list of non-negative integers, defined as follows: if the + list of nonnegative integers, defined as follows: if the element is a monomial in the generators `\text{Sq}(2^i)`, then - the `i^{th}` entry in the list is the number of times + the `i`-th entry in the list is the number of times `\text{Sq}(2^i)` appears. For an arbitrary element, write it as a sum of such monomials; then its height is the maximum, ordered right-lexicographically, of the heights of those @@ -3702,7 +3701,7 @@ def wall_height(self): basis element `\text{Sq}(r_1, r_2, ...)` is obtained as follows: write each `r_i` in binary as `r_i = \sum_j 2^j r_{ij}`. Then each nonzero binary digit `r_{ij}` contributes 1 - to the `k^{th}` entry in the height, for `j \leq k \leq + to the `k`-th entry in the height, for `j \leq k \leq i+j-1`. EXAMPLES:: @@ -3777,7 +3776,7 @@ def Sq(self, *nums): INPUT: - - ``a``, ``b``, ``c``, ... -- non-negative integers + - ``a``, ``b``, ``c``, ... -- nonnegative integers OUTPUT: element of the Steenrod algebra @@ -3792,7 +3791,7 @@ def Sq(self, *nums): sage: A.Sq(5,0,2) Sq(5,0,2) - Entries must be non-negative integers; otherwise, an error + Entries must be nonnegative integers; otherwise, an error results. """ if self.prime() == 2: @@ -3803,7 +3802,7 @@ def Sq(self, *nums): def SteenrodAlgebra(p=2, basis='milnor', generic='auto', **kwds): r""" - The mod `p` Steenrod algebra + The mod `p` Steenrod algebra. INPUT: @@ -3983,7 +3982,7 @@ def SteenrodAlgebra(p=2, basis='milnor', generic='auto', **kwds): ``profile`` argument specifies the profile function for this algebra. Any sub-Hopf algebra of the Steenrod algebra is determined by its *profile function*. When `p=2`, this is a map `e` - from the positive integers to the set of non-negative integers, + from the positive integers to the set of nonnegative integers, plus `\infty`, corresponding to the sub-Hopf algebra dual to this quotient of the dual Steenrod algebra: @@ -4002,10 +4001,10 @@ def SteenrodAlgebra(p=2, basis='milnor', generic='auto', **kwds): - a list or tuple, e.g., ``[3,2,1]``, corresponding to the function sending 1 to 3, 2 to 2, 3 to 1, and all other integers to the value of ``truncation_type``. - - a function from positive integers to non-negative integers (and + - a function from positive integers to nonnegative integers (and `\infty`), e.g., ``lambda n: n+2``. - ``None`` or ``Infinity`` -- use this for the profile function for - the whole Steenrod algebra. + the whole Steenrod algebra In the first and third cases, ``precision`` is ignored. In the second case, this function is converted to a tuple of length one @@ -4023,7 +4022,7 @@ def SteenrodAlgebra(p=2, basis='milnor', generic='auto', **kwds): following:: sage: A2 = SteenrodAlgebra(profile=[3,2,1]) - sage: B2 = SteenrodAlgebra(profile=[3,2,1,0,0]) # trailing 0's ignored + sage: B2 = SteenrodAlgebra(profile=[3,2,1,0,0]) # trailing 0s ignored sage: A2 == B2 True sage: C2 = SteenrodAlgebra(profile=lambda n: max(4-n, 0), truncation_type=0) @@ -4078,12 +4077,12 @@ def SteenrodAlgebra(p=2, basis='milnor', generic='auto', **kwds): the set `\{1,2\}`, e.g., ``([3,2,1,1], [1,1,2,2,1])``. - a pair of functions, one from the positive integers to - non-negative integers (and `\infty`), one from the non-negative + nonnegative integers (and `\infty`), one from the nonnegative integers to the set `\{1,2\}`, e.g., ``(lambda n: n+2, lambda n: 1 if n<3 else 2)``. - ``None`` or ``Infinity`` -- use this for the profile function for - the whole Steenrod algebra. + the whole Steenrod algebra You can also mix and match the first two, passing a pair with first entry a list and second entry a function, for instance. The @@ -4186,8 +4185,8 @@ def AA(n=None, p=2): INPUT: - - `n` -- non-negative integer, optional (default ``None``) - - `p` -- prime number, optional (default 2) + - ``n`` -- nonnegative integer (default: ``None``) + - ``p`` -- prime number (default: 2) OUTPUT: @@ -4226,12 +4225,11 @@ def Sq(*nums): INPUT: - - ``a``, ``b``, ``c``, ... -- non-negative integers + - ``a``, ``b``, ``c``, ... -- nonnegative integers OUTPUT: element of the Steenrod algebra - This returns the Milnor basis element - `\text{Sq}(a, b, c, ...)`. + This returns the Milnor basis element `\text{Sq}(a, b, c, ...)`. EXAMPLES:: @@ -4242,7 +4240,7 @@ def Sq(*nums): sage: (Sq(4,3) + Sq(7,2)).degree() 13 - Entries must be non-negative integers; otherwise, an error + Entries must be nonnegative integers; otherwise, an error results. This function is a good way to define elements of the Steenrod diff --git a/src/sage/algebras/steenrod/steenrod_algebra_bases.py b/src/sage/algebras/steenrod/steenrod_algebra_bases.py index 070043a08d8..06f9a5b87ad 100644 --- a/src/sage/algebras/steenrod/steenrod_algebra_bases.py +++ b/src/sage/algebras/steenrod/steenrod_algebra_bases.py @@ -20,29 +20,29 @@ Monks [Mon1998]_ and Wood [Woo1998]_ for more information about them. For commutator bases, see the preprint by Palmieri and Zhang [PZ2008]_. -- ``'milnor'``: Milnor basis. +- ``'milnor'`` -- Milnor basis -- ``'serre-cartan'`` or ``'adem'`` or ``'admissible'``: Serre-Cartan basis. +- ``'serre-cartan'`` or ``'adem'`` or ``'admissible'`` -- Serre-Cartan basis Most of the rest of the bases are only defined when `p=2`. The only exceptions are the `P^s_t`-bases and the commutator bases, which are defined at all primes. -- ``'wood_y'``: Wood's Y basis. +- ``'wood_y'`` -- Wood's Y basis -- ``'wood_z'``: Wood's Z basis. +- ``'wood_z'`` -- Wood's Z basis -- ``'wall'``, ``'wall_long'``: Wall's basis. +- ``'wall'``, ``'wall_long'`` -- Wall's basis -- ``'arnon_a'``, ``'arnon_a_long'``: Arnon's A basis. +- ``'arnon_a'``, ``'arnon_a_long'`` -- Arnon's A basis -- ``'arnon_c'``: Arnon's C basis. +- ``'arnon_c'`` -- Arnon's C basis -- ``'pst'``, ``'pst_rlex'``, ``'pst_llex'``, ``'pst_deg'``, ``'pst_revz'``: - various `P^s_t`-bases. +- ``'pst'``, ``'pst_rlex'``, ``'pst_llex'``, ``'pst_deg'``, ``'pst_revz'`` -- + various `P^s_t`-bases -- ``'comm'``, ``'comm_rlex'``, ``'comm_llex'``, ``'comm_deg'``, ``'comm_revz'``, - or these with ``'_long'`` appended: various commutator bases. +- ``'comm'``, ``'comm_rlex'``, ``'comm_llex'``, ``'comm_deg'``, ``'comm_revz'``, + or these with ``'_long'`` appended -- various commutator bases The main functions provided here are @@ -122,7 +122,7 @@ def convert_to_milnor_matrix(n, basis, p=2, generic='auto'): INPUT: - - ``n`` -- non-negative integer, the dimension + - ``n`` -- nonnegative integer, the dimension - ``basis`` -- string, the basis from which to convert - ``p`` -- positive prime number (default: 2) @@ -190,7 +190,7 @@ def convert_from_milnor_matrix(n, basis, p=2, generic='auto'): INPUT: - - ``n`` -- non-negative integer, the dimension + - ``n`` -- nonnegative integer, the dimension - ``basis`` -- string, the basis to which to convert @@ -200,7 +200,7 @@ def convert_from_milnor_matrix(n, basis, p=2, generic='auto'): ``matrix`` -- change-of-basis matrix, a square matrix over `\GF{p}` - .. note:: + .. NOTE:: This is called internally. It is not intended for casual users, so no error checking is made on the integer `n`, the @@ -263,14 +263,14 @@ def steenrod_algebra_basis(n, basis='milnor', p=2, **kwds): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``basis`` -- string, which basis to use (default: ``'milnor'``) - ``p`` -- positive prime number (default: 2) - - ``profile`` -- profile function (default: ``None``). This + - ``profile`` -- profile function (default: ``None``); this is just passed on to the functions :func:`milnor_basis` and - :func:`pst_basis`. - - ``truncation_type`` -- truncation type, either 0 or Infinity - (default: Infinity if no profile function is specified, + :func:`pst_basis` + - ``truncation_type`` -- truncation type, either 0 or ``Infinity`` + (default: ``Infinity`` if no profile function is specified, 0 otherwise). This is just passed on to the function :func:`milnor_basis`. - ``generic`` -- boolean (default: ``None``) @@ -284,20 +284,20 @@ def steenrod_algebra_basis(n, basis='milnor', p=2, **kwds): documentation for :mod:`sage.algebras.steenrod.steenrod_algebra` for details on each basis: - - ``'milnor'``: Milnor basis. - - ``'serre-cartan'`` or ``'adem'`` or ``'admissible'``: Serre-Cartan basis. - - ``'pst'``, ``'pst_rlex'``, ``'pst_llex'``, ``'pst_deg'``, ``'pst_revz'``: - various `P^s_t`-bases. + - ``'milnor'`` -- Milnor basis + - ``'serre-cartan'`` or ``'adem'`` or ``'admissible'`` -- Serre-Cartan basis + - ``'pst'``, ``'pst_rlex'``, ``'pst_llex'``, ``'pst_deg'``, ``'pst_revz'`` -- + various `P^s_t`-bases - ``'comm'``, ``'comm_rlex'``, ``'comm_llex'``, ``'comm_deg'``, ``'comm_revz'``, or - any of these with ``'_long'`` appended: various commutator bases. + any of these with ``'_long'`` appended -- various commutator bases The rest of these bases are only defined when `p=2`. - - ``'wood_y'``: Wood's Y basis. - - ``'wood_z'``: Wood's Z basis. - - ``'wall'`` or ``'wall_long'``: Wall's basis. - - ``'arnon_a'`` or ``'arnon_a_long'``: Arnon's A basis. - - ``'arnon_c'``: Arnon's C basis. + - ``'wood_y'`` -- Wood's Y basis + - ``'wood_z'`` -- Wood's Z basis + - ``'wall'`` or ``'wall_long'`` -- Wall's basis + - ``'arnon_a'`` or ``'arnon_a_long'`` -- Arnon's A basis + - ``'arnon_c'`` -- Arnon's C basis EXAMPLES:: @@ -385,9 +385,9 @@ def restricted_partitions(n, l, no_repeats=False): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``l`` -- list of positive integers - - ``no_repeats`` -- boolean (default: ``False``), if ``True``, + - ``no_repeats`` -- boolean (default: ``False``); if ``True``, only return partitions with no repeated parts OUTPUT: iterator of lists @@ -462,10 +462,10 @@ def xi_degrees(n, p=2, reverse=True): INPUT: - ``n`` -- integer - - ``p`` -- prime number, optional (default: 2) - - ``reverse`` -- bool, optional (default: ``True``) + - ``p`` -- prime number (default: 2) + - ``reverse`` -- boolean (default: ``True``) - OUTPUT: ``list`` -- list of integers + OUTPUT: list of integers When `p=2`: decreasing list of the degrees of the `\xi_i`'s with degree at most `n`. @@ -513,7 +513,7 @@ def milnor_basis(n, p=2, **kwds): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``p`` -- positive prime number (default: 2) @@ -525,19 +525,19 @@ def milnor_basis(n, p=2, **kwds): :func:`SteenrodAlgebra ` for information on profile functions. - - ``truncation_type`` -- truncation type, either 0 or Infinity - (default: Infinity if no profile function is specified, + - ``truncation_type`` -- truncation type, either 0 or ``Infinity`` + (default: ``Infinity`` if no profile function is specified, 0 otherwise) OUTPUT: tuple of mod `p` Milnor basis elements in dimension `n` At the prime 2, the Milnor basis consists of symbols of the form `\text{Sq}(m_1, m_2, ..., m_t)`, where each - `m_i` is a non-negative integer and if `t>1`, then + `m_i` is a nonnegative integer and if `t>1`, then `m_t \neq 0`. At odd primes, it consists of symbols of the form `Q_{e_1} Q_{e_2} ... P(m_1, m_2, ..., m_t)`, where `0 \leq e_1 < e_2 < ...`, each `m_i` is a - non-negative integer, and if `t>1`, then + nonnegative integer, and if `t>1`, then `m_t \neq 0`. EXAMPLES:: @@ -678,7 +678,7 @@ def serre_cartan_basis(n, p=2, bound=1, **kwds): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``bound`` -- positive integer (optional) - ``prime`` -- positive prime number (default: 2) @@ -763,7 +763,7 @@ def atomic_basis(n, basis, **kwds): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``basis`` -- string, the name of the basis @@ -774,8 +774,8 @@ def atomic_basis(n, basis, **kwds): :mod:`sage.algebras.steenrod.steenrod_algebra` and :func:`SteenrodAlgebra` for information on profile functions. - - ``truncation_type`` -- truncation type, either 0 or Infinity - (default: Infinity if no profile function is specified, + - ``truncation_type`` -- truncation type, either 0 or ``Infinity`` + (default: ``Infinity`` if no profile function is specified, 0 otherwise). OUTPUT: tuple of basis elements in dimension `n` @@ -943,7 +943,7 @@ def arnonC_basis(n, bound=1): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``bound`` -- positive integer (optional) @@ -992,7 +992,7 @@ def atomic_basis_odd(n, basis, p, **kwds): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - ``basis`` -- string, the name of the basis @@ -1005,8 +1005,8 @@ def atomic_basis_odd(n, basis, p, **kwds): :mod:`sage.algebras.steenrod.steenrod_algebra` and :func:`SteenrodAlgebra` for information on profile functions. - - ``truncation_type`` -- truncation type, either 0 or Infinity - (default: Infinity if no profile function is specified, + - ``truncation_type`` -- truncation type, either 0 or ``Infinity`` + (default: ``Infinity`` if no profile function is specified, 0 otherwise). OUTPUT: tuple of basis elements in dimension `n` @@ -1107,10 +1107,10 @@ def steenrod_basis_error_check(dim, p, **kwds): INPUT: - - ``dim`` -- non-negative integer + - ``dim`` -- nonnegative integer - ``p`` -- positive prime number - OUTPUT: None + OUTPUT: none This checks to see if the different bases have the same length, and if the change-of-basis matrices are invertible. If something goes diff --git a/src/sage/algebras/steenrod/steenrod_algebra_misc.py b/src/sage/algebras/steenrod/steenrod_algebra_misc.py index a57372f52c3..1bf8e278502 100644 --- a/src/sage/algebras/steenrod/steenrod_algebra_misc.py +++ b/src/sage/algebras/steenrod/steenrod_algebra_misc.py @@ -54,11 +54,9 @@ def get_basis_name(basis, p, generic=None): - ``p`` -- positive prime number - - ``generic`` -- boolean, optional, default to 'None' + - ``generic`` -- boolean (default: 'None') - OUTPUT: - - - ``basis_name`` -- string + OUTPUT: ``basis_name`` -- string Specify the names of the implemented bases. The input is converted to lower-case, then processed to return the canonical @@ -187,7 +185,7 @@ def get_basis_name(basis, p, generic=None): def is_valid_profile(profile, truncation_type, p=2, generic=None): r""" - True if ``profile``, together with ``truncation_type``, is a valid + Return ``True`` if ``profile``, together with ``truncation_type``, is a valid profile at the prime `p`. INPUT: @@ -197,11 +195,11 @@ def is_valid_profile(profile, truncation_type, p=2, generic=None): - ``truncation_type`` -- either 0 or `\infty` - - `p` -- prime number, optional, default 2 + - ``p`` -- prime number (default: 2) - - `generic` -- boolean, optional, default None + - ``generic`` -- boolean (default: ``None``) - OUTPUT: True if the profile function is valid, False otherwise. + OUTPUT: ``True`` if the profile function is valid, ``False`` otherwise See the documentation for :mod:`sage.algebras.steenrod.steenrod_algebra` for descriptions of profile functions and how they correspond to @@ -306,10 +304,10 @@ def normalize_profile(profile, precision=None, truncation_type='auto', p=2, gene INPUT: - ``profile`` -- a profile function in form specified below - - ``precision`` -- integer or ``None``, optional, default ``None`` - - ``truncation_type`` -- 0 or `\infty` or 'auto', optional, default 'auto' - - `p` -- prime, optional, default 2 - - `generic` -- boolean, optional, default ``None`` + - ``precision`` -- integer or ``None`` (default: ``None``) + - ``truncation_type`` -- 0 or `\infty` or 'auto' (default: 'auto') + - ``p`` -- prime (default: 2) + - ``generic`` -- boolean (default: ``None``) OUTPUT: @@ -329,7 +327,7 @@ def normalize_profile(profile, precision=None, truncation_type='auto', p=2, gene function, and it may be entered in any of the following forms: - a list or tuple, e.g., ``[3,2,1,1]`` - - a function from positive integers to non-negative integers (and + - a function from positive integers to nonnegative integers (and `\infty`), e.g., ``lambda n: n+2``. This corresponds to the list ``[3, 4, 5, ...]``. - ``None`` or ``Infinity`` -- use this for the profile function for @@ -340,7 +338,7 @@ def normalize_profile(profile, precision=None, truncation_type='auto', p=2, gene case it is clear how to do this; also in this case, ``precision`` is set to be one more than the length of this tuple. In the second case, construct a tuple of length one less than - ``precision`` (default value 100). In the last case, the empty + ``precision`` (default: 100). In the last case, the empty tuple is returned and ``precision`` is set to 1. Once a sub-Hopf algebra of the Steenrod algebra has been defined @@ -359,8 +357,8 @@ def normalize_profile(profile, precision=None, truncation_type='auto', p=2, gene the set `\{1,2\}`, e.g., ``([3,2,1,1], [1,1,2,2,1])``. - a pair of functions, one (called `e`) from positive integers to - non-negative integers (and `\infty`), one (called `k`) from - non-negative integers to the set `\{1,2\}`, e.g., + nonnegative integers (and `\infty`), one (called `k`) from + nonnegative integers to the set `\{1,2\}`, e.g., ``(lambda n: n+2, lambda n: 1)``. This corresponds to the pair ``([3, 4, 5, ...], [1, 1, 1, ...])``. @@ -576,11 +574,11 @@ def milnor_mono_to_string(mono, latex=False, generic=False): INPUT: - - ``mono`` -- if `generic=False`, tuple of non-negative integers (a,b,c,...); - if `generic=True`, pair of tuples of non-negative integers ((e0, e1, e2, + - ``mono`` -- if `generic=False`, tuple of nonnegative integers (a,b,c,...); + if `generic=True`, pair of tuples of nonnegative integers ((e0, e1, e2, ...), (r1, r2, ...)) - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string - ``generic`` -- whether to format generically, or for the prime 2 (default) @@ -654,7 +652,7 @@ def serre_cartan_mono_to_string(mono, latex=False, generic=False): or tuple (e0, n1, e1, n2, ...) when `generic=True`, where each ei is 0 or 1, and each ni is positive - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string - ``generic`` -- whether to format generically, or for the prime 2 (default) @@ -666,7 +664,6 @@ def serre_cartan_mono_to_string(mono, latex=False, generic=False): ``\beta^{e0} P^{n1} \beta^{e1} P^{n2} ...`` when `generic=True`. is odd. - EXAMPLES:: sage: from sage.algebras.steenrod.steenrod_algebra_misc import serre_cartan_mono_to_string @@ -730,9 +727,9 @@ def wood_mono_to_string(mono, latex=False): INPUT: - - ``mono`` -- tuple of pairs of non-negative integers (s,t) + - ``mono`` -- tuple of pairs of nonnegative integers (s,t) - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string OUTPUT: @@ -775,10 +772,10 @@ def wall_mono_to_string(mono, latex=False): INPUT: - - ``mono`` -- tuple of pairs of non-negative integers (m,k) with `m + - ``mono`` -- tuple of pairs of nonnegative integers (m,k) with `m >= k` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string OUTPUT: @@ -816,10 +813,10 @@ def wall_long_mono_to_string(mono, latex=False): INPUT: - - ``mono`` -- tuple of pairs of non-negative integers (m,k) with `m + - ``mono`` -- tuple of pairs of nonnegative integers (m,k) with `m >= k` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string OUTPUT: @@ -861,16 +858,14 @@ def arnonA_mono_to_string(mono, latex=False, p=2): INPUT: - - ``mono`` -- tuple of pairs of non-negative integers + - ``mono`` -- tuple of pairs of nonnegative integers (m,k) with `m >= k` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string - OUTPUT: - - ``string`` -- concatenation of strings of the form ``X^{m}_{k}`` - for each pair (m,k) + OUTPUT: concatenation of strings of the form ``X^{m}_{k}`` for each pair + (m,k) EXAMPLES:: @@ -903,10 +898,10 @@ def arnonA_long_mono_to_string(mono, latex=False, p=2): INPUT: - - ``mono`` -- tuple of pairs of non-negative integers (m,k) with `m + - ``mono`` -- tuple of pairs of nonnegative integers (m,k) with `m >= k` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string OUTPUT: @@ -951,7 +946,7 @@ def pst_mono_to_string(mono, latex=False, generic=False): - ``mono`` -- tuple of pairs of integers (s,t) with `s >= 0`, `t > 0` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string - ``generic`` -- whether to format generically, or for the prime 2 (default) @@ -1014,7 +1009,7 @@ def comm_mono_to_string(mono, latex=False, generic=False): - ``mono`` -- tuple of pairs of integers (s,t) with `s >= 0`, `t > 0` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string - ``generic`` -- whether to format generically, or for the prime 2 (default) @@ -1077,7 +1072,7 @@ def comm_long_mono_to_string(mono, p, latex=False, generic=False): - ``mono`` -- tuple of pairs of integers (s,t) with `s >= 0`, `t > 0` - - ``latex`` -- boolean (default: ``False``), if true, output + - ``latex`` -- boolean (default: ``False``); if ``True``, output LaTeX string - ``generic`` -- whether to format generically, or for the prime 2 (default) @@ -1140,12 +1135,12 @@ def comm_long_mono_to_string(mono, p, latex=False, generic=False): def convert_perm(m): """ - Convert tuple m of non-negative integers to a permutation in + Convert tuple m of nonnegative integers to a permutation in one-line form. INPUT: - - ``m`` -- tuple of non-negative integers with no repetitions + - ``m`` -- tuple of nonnegative integers with no repetitions OUTPUT: diff --git a/src/sage/algebras/steenrod/steenrod_algebra_mult.py b/src/sage/algebras/steenrod/steenrod_algebra_mult.py index 3cd534d0b4e..c087bb65ba4 100644 --- a/src/sage/algebras/steenrod/steenrod_algebra_mult.py +++ b/src/sage/algebras/steenrod/steenrod_algebra_mult.py @@ -47,17 +47,17 @@ both have a summand of 2.) Now, for each matrix with multinomial coefficient 1, let `t_n` be -the sum of the nth diagonal in the matrix; then +the sum of the `n`-th diagonal in the matrix; then .. MATH:: \text{Sq}(r_1, r_2, ...) \text{Sq}(s_1, s_2, ...) = \sum \text{Sq}(t_1, t_2, ...) The function :func:`milnor_multiplication` takes as input two tuples -of non-negative integers, `r` and `s`, which represent +of nonnegative integers, `r` and `s`, which represent `\text{Sq}(r)=\text{Sq}(r_1, r_2, ...)` and `\text{Sq}(s)=\text{Sq}(s_1, s_2, ...)`; it returns as output a -dictionary whose keys are tuples `t=(t_1, t_2, ...)` of non-negative +dictionary whose keys are tuples `t=(t_1, t_2, ...)` of nonnegative integers, and for each tuple the associated value is the coefficient of `\text{Sq}(t)` in the product formula. (Since we are working mod 2, this coefficient is 1 -- if it is zero, the element is omitted from @@ -128,10 +128,10 @@ \mathcal{P}(5) \mathcal{P}(1,1) = \mathcal{P}(6,1) + 2 \mathcal{P}(0,2). The function :func:`milnor_multiplication` takes as input two pairs of -tuples of non-negative integers, `(g,q)` and `(f,s)`, which represent +tuples of nonnegative integers, `(g,q)` and `(f,s)`, which represent `Q_{g_1} Q_{g_2} ... \mathcal{P}(q_1, q_2, ...)` and `Q_{f_1} Q_{f_2} ... \mathcal{P}(s_1, s_2, ...)`. It returns as output a -dictionary whose keys are pairs of tuples `(e,t)` of non-negative +dictionary whose keys are pairs of tuples `(e,t)` of nonnegative integers, and for each tuple the associated value is the coefficient in the product formula. @@ -158,7 +158,7 @@ process terminates in a finite number of steps, and therefore gives a procedure for multiplying elements of the Serre-Cartan basis. -At an odd prime `p`, the Steenrod algebra is generated by the pth +At an odd prime `p`, the Steenrod algebra is generated by the `p`-th power operations `\mathcal{P}^a` (the same as `\mathcal{P}(a)` in the Milnor basis) and the Bockstein operation `\beta` (= `Q_0` in the Milnor basis). The odd primary *Adem relations* are as follows: if `a @@ -190,7 +190,7 @@ The main function for this is :func:`make_mono_admissible`, which converts a product of Steenrod -squares or pth power operations and Bocksteins into a dictionary +squares or `p`-th power operations and Bocksteins into a dictionary representing a sum of admissible monomials. """ @@ -210,13 +210,13 @@ def milnor_multiplication(r,s): INPUT: - - r -- tuple of non-negative integers - - s -- tuple of non-negative integers + - ``r`` -- tuple of nonnegative integers + - ``s`` -- tuple of nonnegative integers OUTPUT: Dictionary of terms of the form (tuple: coeff), where - 'tuple' is a tuple of non-negative integers and 'coeff' is 1. + 'tuple' is a tuple of nonnegative integers and 'coeff' is 1. This computes Milnor matrices for the product of `\text{Sq}(r)` and `\text{Sq}(s)`, computes their multinomial coefficients, and @@ -324,11 +324,9 @@ def multinomial(list): INPUT: - - list -- list of integers + - ``list`` -- list of integers - OUTPUT: - - None if the multinomial coefficient is 0, or sum of list if it is 1 + OUTPUT: none if the multinomial coefficient is 0, or sum of list if it is 1 Given the input `[n_1, n_2, n_3, ...]`, this computes the multinomial coefficient `(n_1 + n_2 + n_3 + ...)! / (n_1! n_2! @@ -380,10 +378,10 @@ def milnor_multiplication_odd(m1,m2,p): INPUT: - - m1 -- pair of tuples (e,r), where e is an increasing tuple of - non-negative integers and r is a tuple of non-negative integers - - m2 -- pair of tuples (f,s), same format as m1 - - p -- odd prime number + - ``m1`` -- pair of tuples (e,r), where e is an increasing tuple of + nonnegative integers and r is a tuple of nonnegative integers + - ``m2`` -- pair of tuples (f,s), same format as m1 + - ``p`` -- odd prime number OUTPUT: @@ -576,12 +574,10 @@ def multinomial_odd(list,p): INPUT: - - list -- list of integers - - p -- a prime number - - OUTPUT: + - ``list`` -- list of integers + - ``p`` -- a prime number - Associated multinomial coefficient, mod p + OUTPUT: associated multinomial coefficient, mod p Given the input `[n_1, n_2, n_3, ...]`, this computes the multinomial coefficient `(n_1 + n_2 + n_3 + ...)! / (n_1! n_2! @@ -647,9 +643,7 @@ def binomial_mod2(n,k): - `n`, `k` -- integers - OUTPUT: - - `n` choose `k`, mod 2 + OUTPUT: `n` choose `k`, mod 2 EXAMPLES:: @@ -678,11 +672,9 @@ def binomial_modp(n,k,p): INPUT: - `n`, `k` -- integers - - `p` -- prime number - - OUTPUT: + - ``p`` -- prime number - `n` choose `k`, mod `p` + OUTPUT: `n` choose `k`, mod `p` EXAMPLES:: @@ -700,14 +692,14 @@ def binomial_modp(n,k,p): @cached_function def adem(a, b, c=0, p=2, generic=None): r""" - The mod `p` Adem relations + The mod `p` Adem relations. INPUT: - - `a`, `b`, `c` (optional) -- nonnegative integers, corresponding + - `a`, `b`, `c` -- nonnegative integers (optional); corresponding to either `P^a P^b` or (if `c` present) to `P^a \beta^b P^c` - - `p` -- positive prime number (default: 2) - - `generic` -- whether to use the generic Steenrod algebra, (default: depends on prime) + - ``p`` -- positive prime number (default: 2) + - ``generic`` -- whether to use the generic Steenrod algebra, (default: depends on prime) OUTPUT: @@ -854,14 +846,14 @@ def make_mono_admissible(mono, p=2, generic=None): INPUT: - - ``mono`` -- a tuple of non-negative integers - - `p` -- prime number, optional (default 2) - - `generic` -- whether to use the generic Steenrod algebra, (default: depends on prime) + - ``mono`` -- tuple of nonnegative integers + - ``p`` -- prime number (default: 2) + - ``generic`` -- whether to use the generic Steenrod algebra (default: depends on prime) OUTPUT: Dictionary of terms of the form (tuple: coeff), where - 'tuple' is an admissible tuple of non-negative integers and + 'tuple' is an admissible tuple of nonnegative integers and 'coeff' is its coefficient. This corresponds to a linear combination of admissible monomials. When `p` is odd, each tuple must have an odd length: it should be of the form `(e_1, i_1, e_2, diff --git a/src/sage/algebras/weyl_algebra.py b/src/sage/algebras/weyl_algebra.py index 247b6107e0f..ac554795cfd 100644 --- a/src/sage/algebras/weyl_algebra.py +++ b/src/sage/algebras/weyl_algebra.py @@ -43,12 +43,12 @@ def repr_from_monomials(monomials, term_repr, use_latex=False) -> str: INPUT: - - ``monomials`` -- a list of pairs ``[m, c]`` where ``m`` is the index + - ``monomials`` -- list of pairs ``[m, c]`` where ``m`` is the index and ``c`` is the coefficient - ``term_repr`` -- a function which returns a string given an index (can be ``repr`` or ``latex``, for example) - - ``use_latex`` -- (default: ``False``) if ``True`` then the output is - in latex format + - ``use_latex`` -- boolean (default: ``False``); if ``True`` then the + output is in latex format EXAMPLES:: @@ -728,7 +728,7 @@ def _repr_(self) -> str: # add options to class class options(GlobalOptions): r""" - Sets the global options for elements of the differential Weyl + Set the global options for elements of the differential Weyl algebra class. The default is to have the factored representations turned off. diff --git a/src/sage/algebras/yangian.py b/src/sage/algebras/yangian.py index 8e19b92ba07..b17a1de0554 100644 --- a/src/sage/algebras/yangian.py +++ b/src/sage/algebras/yangian.py @@ -228,7 +228,7 @@ def __init__(self, base_ring, n, variable_name, filtration): EXAMPLES:: sage: Y = Yangian(QQ, 4, filtration='loop') - sage: TestSuite(Y).run(skip="_test_antipode") # Not implemented + sage: TestSuite(Y).run(skip='_test_antipode') # Not implemented sage: Y = Yangian(QQ, 4, filtration='natural') sage: G = Y.algebra_generators() sage: elts = [Y.one(), G[1,2,2], G[1,1,4], G[3,3,1], G[1,2,1]*G[2,1,4]] @@ -395,7 +395,7 @@ def algebra_generators(self): Lazy family (generator(i))_{i in The Cartesian product of (Positive integers, {1, 2, 3, 4}, {1, 2, 3, 4})} """ - return Family(self._indices._indices, self.gen, name="generator") + return Family(self._indices._indices, self.gen, name='generator') @cached_method def one_basis(self): @@ -657,7 +657,7 @@ def __init__(self, base_ring, n, level, variable_name, filtration): EXAMPLES:: sage: Y = Yangian(QQ, 4, 3) - sage: TestSuite(Y).run(skip="_test_antipode") + sage: TestSuite(Y).run(skip='_test_antipode') """ self._level = level self._n = n diff --git a/src/sage/algebras/yokonuma_hecke_algebra.py b/src/sage/algebras/yokonuma_hecke_algebra.py index 67ee66a653e..8f366ff3401 100644 --- a/src/sage/algebras/yokonuma_hecke_algebra.py +++ b/src/sage/algebras/yokonuma_hecke_algebra.py @@ -416,8 +416,8 @@ def _product_by_basis_gen(self, m, i): - (q^-1-q)*t1^2*t2^3*t3^2*g[1] - (q^-1-q)*t1^3*t2^2*t3^2*g[1] """ t, w = m - wi = w.apply_simple_reflection(i, side="right") - if not w.has_descent(i, side="right"): + wi = w.apply_simple_reflection(i, side='right') + if not w.has_descent(i, side='right'): return self.monomial((t, wi)) R = self.base_ring() diff --git a/src/sage/arith/functions.pyx b/src/sage/arith/functions.pyx index 92dbc709897..c87dc1e67c7 100644 --- a/src/sage/arith/functions.pyx +++ b/src/sage/arith/functions.pyx @@ -30,7 +30,7 @@ def lcm(a, b=None): - ``a``, ``b`` -- two elements of a ring with lcm or - - ``a`` -- a list, tuple or iterable of elements of a ring with lcm + - ``a`` -- list; tuple or iterable of elements of a ring with lcm OUTPUT: diff --git a/src/sage/arith/long.pxd b/src/sage/arith/long.pxd index 44923f802da..5330776b3bf 100644 --- a/src/sage/arith/long.pxd +++ b/src/sage/arith/long.pxd @@ -31,9 +31,9 @@ cdef inline long pyobject_to_long(x) except? LONG_MIN: r""" Given a Python object ``x`` cast it quickly to a C long. - A :class:`TypeError` is raised if the input cannot be converted to + A :exc:`TypeError` is raised if the input cannot be converted to an integer or - an :class:`OverflowError` is raised if it does not fit into a C long. + an :exc:`OverflowError` is raised if it does not fit into a C long. TESTS: @@ -96,18 +96,18 @@ cdef inline bint integer_check_long(x, long* value, int* err) except -1: Possible errors when returning ``True``: - - ``0``: ``x`` was successfully converted to a C long and its value - is stored in ``*value``. + - ``0`` -- ``x`` was successfully converted to a C long and its value + is stored in ``*value`` - - ``ERR_OVERFLOW``: ``x`` is an integer type but too large to store - in a C long. + - ``ERR_OVERFLOW`` -- ``x`` is an integer type but too large to store + in a C long Possible errors when returning ``False``: - - ``ERR_TYPE``: ``x`` is not an integer type of any kind. + - ``ERR_TYPE`` -- ``x`` is not an integer type of any kind - - ``ERR_INDEX``: ``x`` implements ``__index__`` but a :class:`TypeError` - was raised calling ``__index__()``. + - ``ERR_INDEX`` -- ``x`` implements ``__index__`` but a :exc:`TypeError` + was raised calling ``__index__()`` - Other exceptions in ``__index__`` are simply propagated. This is the only way this function can raise an exception. @@ -225,7 +225,7 @@ cdef inline long dig(const digit* D, int n) noexcept: cdef inline bint integer_check_long_py(x, long* value, int* err) noexcept: """ - Return whether ``x`` is a python object of type ``int``. + Return whether ``x`` is a Python object of type ``int``. If possible, compute the value of this integer as C long and store it in ``*value``. @@ -235,15 +235,15 @@ cdef inline bint integer_check_long_py(x, long* value, int* err) noexcept: Possible errors when returning ``True``: - - ``0``: ``x`` was successfully converted to a C long and its value - is stored in ``*value``. + - ``0`` -- ``x`` was successfully converted to a C long and its value + is stored in ``*value`` - - ``ERR_OVERFLOW``: ``x`` is a python object of type ``int`` but - too large to store in a C long. + - ``ERR_OVERFLOW`` -- ``x`` is a Python object of type ``int`` but + too large to store in a C long Possible errors when returning ``False``: - - ``ERR_TYPE``: ``x`` is not a python object of type ``int``. + - ``ERR_TYPE`` -- ``x`` is not a Python object of type ``int`` EXAMPLES: diff --git a/src/sage/arith/misc.py b/src/sage/arith/misc.py index d184c52bf19..4ffd60ca845 100644 --- a/src/sage/arith/misc.py +++ b/src/sage/arith/misc.py @@ -57,7 +57,7 @@ def algdep(z, degree, known_bits=None, use_bits=None, known_digits=None, is not found, then ``None`` will be returned. If ``proof=True`` then the result is returned only if it can be proved correct (i.e. the only possible minimal polynomial satisfying the height bound, or no - such polynomial exists). Otherwise a :class:`ValueError` is raised + such polynomial exists). Otherwise a :exc:`ValueError` is raised indicating that higher precision is required. ALGORITHM: Uses LLL for real/complex inputs, PARI C-library @@ -67,16 +67,14 @@ def algdep(z, degree, known_bits=None, use_bits=None, known_digits=None, INPUT: + - ``z`` -- real, complex, or `p`-adic number - - ``z`` -- real, complex, or `p`-adic number + - ``degree`` -- integer - - ``degree`` -- an integer - - - ``height_bound`` -- an integer (default: ``None``) specifying the maximum - coefficient size for the returned polynomial - - - ``proof`` -- a boolean (default: ``False``), requires height_bound to be set + - ``height_bound`` -- integer (default: ``None``); specifying the maximum + coefficient size for the returned polynomial + - ``proof`` -- boolean (default: ``False``); requires height_bound to be set EXAMPLES:: @@ -252,7 +250,7 @@ def norm(v): if max(abs(a) for a in coeffs) > height_bound: if proof: # Given an LLL reduced basis $b_1, ..., b_n$, we only - # know that $|b_1| <= 2^((n-1)/2) |x|$ for non-zero $x \in L$. + # know that $|b_1| <= 2^((n-1)/2) |x|$ for nonzero $x \in L$. if norm(LLL[0]) <= 2**((n - 1) / 2) * n.sqrt() * height_bound: raise ValueError("insufficient precision for non-existence proof") return None @@ -280,11 +278,11 @@ def norm(v): def bernoulli(n, algorithm='default', num_threads=1): r""" - Return the n-th Bernoulli number, as a rational number. + Return the `n`-th Bernoulli number, as a rational number. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``algorithm``: - ``'default'`` -- use 'flint' for n <= 20000, then 'arb' for n <= 300000 @@ -404,15 +402,15 @@ def factorial(n, algorithm='gmp'): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``algorithm`` -- string (default: 'gmp'): + - ``algorithm`` -- string (default: ``'gmp'``): - - ``'gmp'`` -- use the GMP C-library factorial function + - ``'gmp'`` -- use the GMP C-library factorial function - - ``'pari'`` -- use PARI's factorial function + - ``'pari'`` -- use PARI's factorial function - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -575,15 +573,15 @@ def is_prime(n) -> bool: def is_pseudoprime(n): r""" - Test whether ``n`` is a pseudo-prime + Test whether ``n`` is a pseudo-prime. The result is *NOT* proven correct - *this is a pseudo-primality test!*. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - .. note:: + .. NOTE:: We do not consider negatives of prime numbers as prime. @@ -610,14 +608,14 @@ def is_pseudoprime(n): def is_prime_power(n, get_data=False): r""" - Test whether ``n`` is a positive power of a prime number + Test whether ``n`` is a positive power of a prime number. This function simply calls the method :meth:`Integer.is_prime_power() ` of Integers. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``get_data`` -- if set to ``True``, return a pair ``(p,k)`` such that this integer equals ``p^k`` instead of ``True`` or ``(self,0)`` instead of @@ -688,10 +686,11 @@ def is_pseudoprime_power(n, get_data=False): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``get_data`` -- (boolean) instead of a boolean return a pair `(p,k)` so - that ``n`` equals `p^k` and `p` is a pseudoprime or `(n,0)` otherwise. + - ``get_data`` -- boolean (default: ``False``); instead of a boolean return + a pair `(p,k)` so that ``n`` equals `p^k` and `p` is a pseudoprime or + `(n,0)` otherwise EXAMPLES:: @@ -814,12 +813,12 @@ def prime_powers(start, stop=None): INPUT: - - ``start`` -- an integer. If two inputs are given, a lower bound + - ``start`` -- integer; if two inputs are given, a lower bound for the returned set of prime powers. If this is the only input, then it is an upper bound. - - ``stop`` -- an integer (default: ``None``). An upper bound for the - returned set of prime powers. + - ``stop`` -- integer (default: ``None``); an upper bound for the + returned set of prime powers OUTPUT: @@ -934,11 +933,9 @@ def primes_first_n(n, leave_pari=False): INPUT: - - `n` -- a nonnegative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - a list of the first `n` prime numbers. + OUTPUT: list of the first `n` prime numbers EXAMPLES:: @@ -970,11 +967,9 @@ def eratosthenes(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - - a list of primes less than or equal to n. + OUTPUT: list of primes less than or equal to `n` EXAMPLES:: @@ -1038,21 +1033,18 @@ def primes(start=2, stop=None, proof=None): INPUT: - - ``start`` -- an integer (default: 2) lower bound for the primes + - ``start`` -- integer (default: 2); lower bound for the primes - - ``stop`` -- an integer (or infinity) upper (open) bound for the + - ``stop`` -- integer (or infinity); upper (open) bound for the primes - - ``proof`` -- bool or ``None`` (default: ``None``) If ``True``, the + - ``proof`` -- boolean or ``None`` (default: ``None``); if ``True``, the function yields only proven primes. If ``False``, the function uses a pseudo-primality test, which is much faster for really big numbers but does not provide a proof of primality. If ``None``, uses the global default (see :mod:`sage.structure.proof.proof`) - OUTPUT: - - - an iterator over primes from ``start`` to ``stop-1``, inclusive - + OUTPUT: an iterator over primes from ``start`` to ``stop-1``, inclusive EXAMPLES:: @@ -1178,9 +1170,7 @@ def next_probable_prime(n): INPUT: - - - ``n`` -- an integer - + - ``n`` -- integer EXAMPLES:: @@ -1208,19 +1198,17 @@ def next_probable_prime(n): def next_prime(n, proof=None): """ - The next prime greater than the integer n. If n is prime, then this - function does not return n, but the next prime after n. If the - optional argument proof is False, this function only returns a + The next prime greater than the integer `n`. If `n` is prime, then this + function does not return `n`, but the next prime after `n`. If the + optional argument proof is ``False``, this function only returns a pseudo-prime, as defined by the PARI nextprime function. If it is - None, uses the global default (see :mod:`sage.structure.proof.proof`) + ``None``, uses the global default (see :mod:`sage.structure.proof.proof`) INPUT: + - ``n`` -- integer - - ``n`` -- integer - - - ``proof`` -- bool or None (default: None) - + - ``proof`` -- boolean or ``None`` (default: ``None``) EXAMPLES:: @@ -1260,7 +1248,7 @@ def next_prime(n, proof=None): def previous_prime(n): """ The largest prime < n. The result is provably correct. If n <= 1, - this function raises a ValueError. + this function raises a :exc:`ValueError`. EXAMPLES:: @@ -1395,14 +1383,14 @@ def random_prime(n, proof=None, lbound=2): INPUT: - - ``n`` -- an integer `\geq 2`. + - ``n`` -- integer `\geq 2` - - ``proof`` -- bool or ``None`` (default: ``None``) If ``False``, the function uses a - pseudo-primality test, which is much faster for really big numbers but - does not provide a proof of primality. If ``None``, uses the global default - (see :mod:`sage.structure.proof.proof`) + - ``proof`` -- boolean or ``None`` (default: ``None``); if ``False``, the function uses a + pseudo-primality test, which is much faster for really big numbers but + does not provide a proof of primality. If ``None``, uses the global default + (see :mod:`sage.structure.proof.proof`) - - ``lbound`` -- an integer `\geq 2`, lower bound for the chosen primes + - ``lbound`` -- integer; `\geq 2`, lower bound for the chosen primes EXAMPLES:: @@ -1507,7 +1495,7 @@ def divisors(n): INPUT: - - ``n`` -- the element + - ``n`` -- the element EXAMPLES: @@ -1590,15 +1578,13 @@ def divisors(n): class Sigma: """ - Return the sum of the k-th powers of the divisors of n. + Return the sum of the `k`-th powers of the divisors of `n`. INPUT: + - ``n`` -- integer - - ``n`` -- integer - - - ``k`` -- integer (default: 1) - + - ``k`` -- integer (default: 1) OUTPUT: integer @@ -1615,7 +1601,7 @@ class Sigma: sage: P = plot(sigma, 1, 100) # needs sage.plot - This method also works with k-th powers. + This method also works with `k`-th powers. :: @@ -1654,7 +1640,7 @@ class Sigma: def __repr__(self): """ A description of this class, which computes the sum of the - k-th powers of the divisors of n. + `k`-th powers of the divisors of `n`. EXAMPLES:: @@ -1666,7 +1652,7 @@ def __repr__(self): def __call__(self, n, k=1): """ - Computes the sum of (the k-th powers of) the divisors of n. + Compute the sum of (the `k`-th powers of) the divisors of `n`. EXAMPLES:: @@ -1693,25 +1679,23 @@ def __call__(self, n, k=1): def plot(self, xmin=1, xmax=50, k=1, pointsize=30, rgbcolor=(0,0,1), join=True, **kwds): """ - Plot the sigma (sum of k-th powers of divisors) function. + Plot the sigma (sum of `k`-th powers of divisors) function. INPUT: + - ``xmin`` -- (default: 1) - - ``xmin`` -- default: 1 + - ``xmax`` -- (default: 50) - - ``xmax`` -- default: 50 + - ``k`` -- (default: 1) - - ``k`` -- default: 1 + - ``pointsize`` -- (default: 30) - - ``pointsize`` -- default: 30 + - ``rgbcolor`` -- (default: (0,0,1)) - - ``rgbcolor`` -- default: (0,0,1) + - ``join`` -- (default: ``True``) whether to join the points - - ``join`` -- default: ``True``; whether to join the - points. - - - ``**kwds`` -- passed on + - ``**kwds`` -- passed on EXAMPLES:: @@ -1742,7 +1726,7 @@ def gcd(a, b=None, **kwargs): - ``a``, ``b`` -- two elements of a ring with gcd or - - ``a`` -- a list or tuple of elements of a ring with gcd + - ``a`` -- list or tuple of elements of a ring with gcd Additional keyword arguments are passed to the respectively called methods. @@ -1869,15 +1853,13 @@ def gcd(a, b=None, **kwargs): def __GCD_sequence(v, **kwargs): """ - Internal function returning the gcd of the elements of a sequence + Internal function returning the gcd of the elements of a sequence. INPUT: + - ``v`` -- a sequence (possibly empty) - - ``v`` -- A sequence (possibly empty) - - - OUTPUT: The gcd of the elements of the sequence as an element of + OUTPUT: the gcd of the elements of the sequence as an element of the sequence's universe, or the integer 0 if the sequence is empty. @@ -1970,12 +1952,10 @@ def xgcd(a, b): INPUT: - - ``a, b`` -- integers or more generally, element of a ring for which the - xgcd make sense (e.g. a field or univariate polynomials). - - OUTPUT: + - ``a``, ``b`` -- integers or more generally, element of a ring for which + the xgcd make sense (e.g. a field or univariate polynomials) - - ``g, s, t`` -- such that `g = s\cdot a + t\cdot b` + OUTPUT: ``g``, ``s``, ``t`` -- such that `g = s\cdot a + t\cdot b` .. NOTE:: @@ -2098,7 +2078,7 @@ def xkcd(n=""): INPUT: - - ``n`` -- an integer (optional) + - ``n`` -- integer (optional) OUTPUT: a fragment of HTML @@ -2319,7 +2299,7 @@ def rational_reconstruction(a, m, algorithm='fast'): lowest terms such that the reduction of `x/y` modulo `m` is equal to `a` and the absolute values of `x` and `y` are both `\le \sqrt{m/2}`. If such `x/y` exists, that pair is unique and this function returns it. If no - such pair exists, this function raises ZeroDivisionError. + such pair exists, this function raises :exc:`ZeroDivisionError`. An efficient algorithm for computing rational reconstruction is very similar to the extended Euclidean algorithm. For more details, @@ -2327,14 +2307,14 @@ def rational_reconstruction(a, m, algorithm='fast'): INPUT: - - ``a`` -- an integer + - ``a`` -- integer - ``m`` -- a modulus - - ``algorithm`` -- (default: 'fast') + - ``algorithm`` -- string (default: ``'fast'``) - - ``'fast'`` -- a fast implementation using direct GMP library calls - in Cython. + - ``'fast'`` -- a fast implementation using direct GMP library calls + in Cython OUTPUT: @@ -2391,7 +2371,7 @@ def rational_reconstruction(a, m, algorithm='fast'): Traceback (most recent call last): ... ZeroDivisionError: rational reconstruction with zero modulus - sage: rational_reconstruction(0, 1, algorithm="foobar") + sage: rational_reconstruction(0, 1, algorithm='foobar') Traceback (most recent call last): ... ValueError: unknown algorithm 'foobar' @@ -2419,7 +2399,7 @@ def mqrr_rational_reconstruction(u, m, T): INPUT: - - ``u``, ``m``, ``T`` -- integers such that `m > u \ge 0`, `T > 0` + - ``u``, ``m``, ``T`` -- integers such that `m > u \ge 0`, `T > 0` OUTPUT: @@ -2472,22 +2452,19 @@ def mqrr_rational_reconstruction(u, m, T): def trial_division(n, bound=None): - """ - Return the smallest prime divisor <= bound of the positive integer - n, or n if there is no such prime. If the optional argument bound - is omitted, then bound <= n. + r""" + Return the smallest prime divisor less than or equal to ``bound`` of the + positive integer `n`, or `n` if there is no such prime. If the optional + argument bound is omitted, then bound `\leq n`. INPUT: - - ``n`` -- a positive integer - - - ``bound`` -- (optional) a positive integer + - ``n`` -- positive integer - OUTPUT: - - - ``int`` -- a prime p=bound that divides n, or n if - there is no such prime. + - ``bound`` -- (optional) positive integer + OUTPUT: a prime ``p=bound`` that divides `n`, or `n` if + there is no such prime EXAMPLES:: @@ -2546,29 +2523,27 @@ def factor(n, proof=None, int_=False, algorithm='pari', verbose=0, **kwds): INPUT: - - ``n`` -- a nonzero integer + - ``n`` -- nonzero integer - - ``proof`` -- bool or ``None`` (default: ``None``) + - ``proof`` -- boolean or ``None`` (default: ``None``) - - ``int_`` -- bool (default: ``False``) whether to return - answers as Python ints + - ``int_`` -- boolean (default: ``False``); whether to return + answers as Python integers - - ``algorithm`` -- string + - ``algorithm`` -- string - - ``'pari'`` -- (default) use the PARI c library + - ``'pari'`` -- (default) use the PARI C library - ``'kash'`` -- use KASH computer algebra system (requires that kash be installed) - ``'magma'`` -- use Magma (requires magma be installed) - - ``verbose`` -- integer (default: 0); PARI's debug - variable is set to this; e.g., set to 4 or 8 to see lots of output - during factorization. + - ``verbose`` -- integer (default: 0); PARI's debug + variable is set to this. E.g., set to 4 or 8 to see lots of output + during factorization. - OUTPUT: - - - factorization of `n` + OUTPUT: factorization of `n` The qsieve and ecm commands give access to highly optimized implementations of algorithms for doing certain integer @@ -2845,17 +2820,17 @@ def odd_part(n): def prime_to_m_part(n, m): """ - Return the prime-to-``m`` part of ``n``. + Return the prime-to-`m` part of `n`. - This is the largest divisor of ``n`` that is coprime to ``m``. + This is the largest divisor of `n` that is coprime to `m`. INPUT: - - ``n`` -- Integer (nonzero) + - ``n`` -- integer (nonzero) - - ``m`` -- Integer + - ``m`` -- integer - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -2887,14 +2862,14 @@ def prime_to_m_part(n, m): def is_square(n, root=False): """ - Return whether or not ``n`` is square. + Return whether or not `n` is square. - If ``n`` is a square also return the square root. - If ``n`` is not square, also return ``None``. + If `n` is a square also return the square root. + If `n` is not square, also return ``None``. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``root`` -- whether or not to also return a square root (default: ``False``) @@ -2904,7 +2879,7 @@ def is_square(n, root=False): - ``bool`` -- whether or not a square - ``object`` -- (optional) an actual square if found, - and ``None`` otherwise. + and ``None`` otherwise EXAMPLES:: @@ -3032,16 +3007,14 @@ def is_squarefree(n): ################################################################# class Euler_Phi: r""" - Return the value of the Euler phi function on the integer n. We + Return the value of the Euler phi function on the integer `n`. We defined this to be the number of positive integers <= n that are - relatively prime to n. Thus if n<=0 then + relatively prime to `n`. Thus if `n \leq 0` then ``euler_phi(n)`` is defined and equals 0. INPUT: - - - ``n`` -- an integer - + - ``n`` -- integer EXAMPLES:: @@ -3056,10 +3029,7 @@ class Euler_Phi: sage: euler_phi(37) # needs sage.libs.pari 36 - Notice that euler_phi is defined to be 0 on negative numbers and - 0. - - :: + Notice that ``euler_phi`` is defined to be 0 on negative numbers and 0:: sage: euler_phi(-1) 0 @@ -3068,26 +3038,20 @@ class Euler_Phi: sage: type(euler_phi(0)) - We verify directly that the phi function is correct for 21. - - :: + We verify directly that the phi function is correct for 21:: sage: euler_phi(21) # needs sage.libs.pari 12 sage: [i for i in range(21) if gcd(21,i) == 1] [1, 2, 4, 5, 8, 10, 11, 13, 16, 17, 19, 20] - The length of the list of integers 'i' in range(n) such that the - gcd(i,n) == 1 equals euler_phi(n). - - :: + The length of the list of integers 'i' in ``range(n)`` such that the + ``gcd(i,n) == 1`` equals ``euler_phi(n)``:: sage: len([i for i in range(21) if gcd(21,i) == 1]) == euler_phi(21) # needs sage.libs.pari True - The phi function also has a special plotting method. - - :: + The phi function also has a special plotting method:: sage: P = plot(euler_phi, -3, 71) # needs sage.libs.pari sage.plot @@ -3120,7 +3084,7 @@ def __repr__(self): def __call__(self, n): """ - Calls the euler_phi function. + Call the ``euler_phi`` function. EXAMPLES:: @@ -3144,19 +3108,17 @@ def plot(self, xmin=1, xmax=50, pointsize=30, rgbcolor=(0, 0, 1), INPUT: + - ``xmin`` -- (default: 1) - - ``xmin`` -- default: 1 - - - ``xmax`` -- default: 50 + - ``xmax`` -- (default: 50) - - ``pointsize`` -- default: 30 + - ``pointsize`` -- (default: 30) - - ``rgbcolor`` -- default: (0,0,1) + - ``rgbcolor`` -- (default: (0,0,1)) - - ``join`` -- default: ``True``; whether to join the - points. + - ``join`` -- boolean (default: ``True``); whether to join the points - - ``**kwds`` -- passed on + - ``**kwds`` -- passed on EXAMPLES:: @@ -3187,11 +3149,9 @@ def carmichael_lambda(n): INPUT: - - ``n`` -- a positive integer. + - ``n`` -- positive integer - OUTPUT: - - - The Carmichael function of ``n``. + OUTPUT: the Carmichael function of ``n`` ALGORITHM: @@ -3334,9 +3294,9 @@ def crt(a, b, m=None, n=None): - ``a``, ``b`` -- two residues (elements of some ring for which extended gcd is available), or two lists, one of residues and - one of moduli. + one of moduli - - ``m``, ``n`` -- (default: ``None``) two moduli, or ``None``. + - ``m``, ``n`` -- (default: ``None``) two moduli, or ``None`` OUTPUT: @@ -3577,7 +3537,7 @@ def CRT_basis(moduli): INPUT: - ``moduli`` -- list of pairwise coprime moduli `m` which admit an - extended Euclidean algorithm + extended Euclidean algorithm OUTPUT: @@ -3626,13 +3586,11 @@ def CRT_vectors(X, moduli): INPUT: - - ``X`` -- list or tuple, consisting of lists/tuples/vectors/etc of - integers of the same length - - ``moduli`` -- list of len(X) moduli + - ``X`` -- list or tuple, consisting of lists/tuples/vectors/etc of + integers of the same length + - ``moduli`` -- list of len(X) moduli - OUTPUT: - - - ``list`` -- application of CRT componentwise. + OUTPUT: list; application of CRT componentwise EXAMPLES:: @@ -3655,7 +3613,7 @@ def CRT_vectors(X, moduli): def binomial(x, m, **kwds): r""" - Return the binomial coefficient + Return the binomial coefficient. .. MATH:: @@ -3673,8 +3631,8 @@ def binomial(x, m, **kwds): INPUT: - - ``x``, ``m`` -- numbers or symbolic expressions. Either ``m`` - or ``x-m`` must be an integer. + - ``x``, ``m`` -- numbers or symbolic expressions; either ``m`` + or ``x-m`` must be an integer OUTPUT: number or symbolic expression (if input is symbolic) @@ -3799,7 +3757,7 @@ def binomial(x, m, **kwds): sage: binomial(n,2) # needs sage.symbolic 1/2*(n - 1)*n - Test p-adic numbers:: + Test `p`-adic numbers:: sage: binomial(Qp(3)(-1/2),4) # p-adic number with valuation >= 0 1 + 3 + 2*3^2 + 3^3 + 2*3^4 + 3^6 + 3^7 + 3^8 + 3^11 + 2*3^14 + 2*3^16 + 2*3^17 + 2*3^19 + O(3^20) @@ -3933,9 +3891,7 @@ def multinomial(*ks): - either an arbitrary number of integer arguments `k_1,\dots,k_n` - or an iterable (e.g. a list) of integers `[k_1,\dots,k_n]` - OUTPUT: - - Return the integer: + OUTPUT: the integer: .. MATH:: @@ -4002,11 +3958,9 @@ def binomial_coefficients(n): INPUT: + - ``n`` -- integer - - ``n`` -- an integer - - - OUTPUT: dict + OUTPUT: dictionary EXAMPLES:: @@ -4050,10 +4004,10 @@ def multinomial_coefficients(m, n): INPUT: - - ``m`` -- integer - - ``n`` -- integer + - ``m`` -- integer + - ``n`` -- integer - OUTPUT: dict + OUTPUT: dictionary EXAMPLES:: @@ -4161,9 +4115,7 @@ def kronecker_symbol(x,y): - ``y`` -- integer - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -4205,18 +4157,16 @@ def legendre_symbol(x, p): r""" The Legendre symbol `(x|p)`, for `p` prime. - .. note:: + .. NOTE:: The :func:`kronecker_symbol` command extends the Legendre symbol to composite moduli and `p=2`. INPUT: + - ``x`` -- integer - - ``x`` -- integer - - - ``p`` -- an odd prime number - + - ``p`` -- odd prime number EXAMPLES:: @@ -4257,12 +4207,12 @@ def legendre_symbol(x, p): def jacobi_symbol(a, b): r""" - The Jacobi symbol of integers a and b, where b is odd. + The Jacobi symbol of integers `a` and `b`, where `b` is odd. - .. note:: + .. NOTE:: The :func:`kronecker_symbol` command extends the Jacobi - symbol to all integers b. + symbol to all integers `b`. If @@ -4274,12 +4224,11 @@ def jacobi_symbol(a, b): where `(a|p_j)` are Legendre Symbols. - INPUT: - - ``a`` -- an integer + - ``a`` -- integer - - ``b`` -- an odd integer + - ``b`` -- odd integer EXAMPLES:: @@ -4311,15 +4260,15 @@ def primitive_root(n, check=True): """ Return a positive integer that generates the multiplicative group of integers modulo `n`, if one exists; otherwise, raise a - :class:`ValueError`. + :exc:`ValueError`. A primitive root exists if `n=4` or `n=p^k` or `n=2p^k`, where `p` is an odd prime and `k` is a nonnegative number. INPUT: - - ``n`` -- a non-zero integer - - ``check`` -- bool (default: ``True``); if False, then `n` is assumed + - ``n`` -- nonzero integer + - ``check`` -- boolean (default: ``True``); if ``False``, then `n` is assumed to be a positive integer possessing a primitive root, and behavior is undefined otherwise. @@ -4430,16 +4379,13 @@ def primitive_root(n, check=True): def nth_prime(n): """ - - Return the n-th prime number (1-indexed, so that 2 is the 1st prime.) + Return the `n`-th prime number (1-indexed, so that 2 is the 1st prime). INPUT: - - ``n`` -- a positive integer - - OUTPUT: + - ``n`` -- positive integer - - the n-th prime number + OUTPUT: the `n`-th prime number EXAMPLES:: @@ -4455,7 +4401,7 @@ def nth_prime(n): sage: nth_prime(0) Traceback (most recent call last): ... - ValueError: nth prime meaningless for non-positive n (=0) + ValueError: nth prime meaningless for nonpositive n (=0) TESTS:: @@ -4469,7 +4415,7 @@ def nth_prime(n): 29 """ if n <= 0: - raise ValueError("nth prime meaningless for non-positive n (=%s)" % n) + raise ValueError("nth prime meaningless for nonpositive n (=%s)" % n) from sage.libs.pari.all import pari return ZZ(pari.prime(n)) @@ -4523,9 +4469,7 @@ class Moebius: INPUT: - - - ``n`` -- anything that can be factored. - + - ``n`` -- anything that can be factored OUTPUT: 0, 1, or -1 @@ -4613,19 +4557,18 @@ def plot(self, xmin=0, xmax=50, pointsize=30, rgbcolor=(0,0,1), join=True, INPUT: + - ``xmin`` -- (default: 0) - - ``xmin`` -- default: 0 - - - ``xmax`` -- default: 50 + - ``xmax`` -- (default: 50) - - ``pointsize`` -- default: 30 + - ``pointsize`` -- (default: 30) - - ``rgbcolor`` -- default: (0,0,1) + - ``rgbcolor`` -- (default: (0,0,1)) - - ``join`` -- default: ``True``; whether to join the points - (very helpful in seeing their order). + - ``join`` -- (default: ``True``) whether to join the points + (very helpful in seeing their order) - - ``**kwds`` -- passed on + - ``**kwds`` -- passed on EXAMPLES:: @@ -4710,8 +4653,8 @@ def continuant(v, n=None): INPUT: - - ``v`` -- list or tuple of elements of a ring - - ``n`` -- optional integer + - ``v`` -- list or tuple of elements of a ring + - ``n`` -- (optional) integer OUTPUT: element of ring (integer, polynomial, etcetera). @@ -4778,16 +4721,14 @@ def continuant(v, n=None): def number_of_divisors(n): - """ - Return the number of divisors of the integer n. + r""" + Return the number of divisors of the integer `n`. INPUT: - - ``n`` -- a nonzero integer + - ``n`` -- nonzero integer - OUTPUT: - - - an integer, the number of divisors of n + OUTPUT: integer; the number of divisors of `n` EXAMPLES:: @@ -4812,7 +4753,7 @@ def number_of_divisors(n): return ZZ(pari(m).numdiv()) -def hilbert_symbol(a, b, p, algorithm="pari"): +def hilbert_symbol(a, b, p, algorithm='pari'): """ Return 1 if `ax^2 + by^2` `p`-adically represents a nonzero square, otherwise returns `-1`. If either a or b @@ -4820,22 +4761,20 @@ def hilbert_symbol(a, b, p, algorithm="pari"): INPUT: + - ``a``, ``b`` -- integers - - ``a, b`` -- integers - - - ``p`` -- integer; either prime or -1 (which - represents the archimedean place) + - ``p`` -- integer; either prime or -1 (which + represents the archimedean place) - - ``algorithm`` -- string + - ``algorithm`` -- string - - ``'pari'`` -- (default) use the PARI C library + - ``'pari'`` -- (default) use the PARI C library - - ``'direct'`` -- use a Python implementation + - ``'direct'`` -- use a Python implementation - - ``'all'`` -- use both PARI and direct and check that + - ``'all'`` -- use both PARI and direct and check that the results agree, then return the common answer - OUTPUT: integer (0, -1, or 1) EXAMPLES:: @@ -4940,9 +4879,7 @@ def hilbert_conductor(a, b): - ``a``, ``b`` -- integers - OUTPUT: - - squarefree positive integer + OUTPUT: squarefree positive integer EXAMPLES:: @@ -5087,11 +5024,11 @@ def falling_factorial(x, a): INPUT: - - ``x`` -- element of a ring + - ``x`` -- element of a ring - - ``a`` -- a non-negative integer or + - ``a`` -- nonnegative integer or - - ``x and a`` -- any numbers + - ``x``, ``a`` -- any numbers OUTPUT: the falling factorial @@ -5191,11 +5128,11 @@ def rising_factorial(x, a): INPUT: - - ``x`` -- element of a ring + - ``x`` -- element of a ring - - ``a`` -- a non-negative integer or + - ``a`` -- nonnegative integer or - - ``x and a`` -- any numbers + - ``x``, ``a`` -- any numbers OUTPUT: the rising factorial @@ -5304,10 +5241,10 @@ def integer_floor(x): INPUT: - - ``x`` -- an object that has a floor method or is - coercible to int + - ``x`` -- an object that has a floor method or is + coercible to integer - OUTPUT: an Integer + OUTPUT: integer EXAMPLES:: @@ -5346,7 +5283,7 @@ def integer_floor(x): def integer_trunc(i): """ - Truncate to the integer closer to zero + Truncate to the integer closer to zero. EXAMPLES:: @@ -5365,13 +5302,13 @@ def integer_trunc(i): def two_squares(n): """ Write the integer `n` as a sum of two integer squares if possible; - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - OUTPUT: a tuple `(a,b)` of non-negative integers such that + OUTPUT: a tuple `(a,b)` of nonnegative integers such that `n = a^2 + b^2` with `a <= b`. EXAMPLES:: @@ -5487,13 +5424,13 @@ def two_squares(n): def three_squares(n): """ Write the integer `n` as a sum of three integer squares if possible; - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - OUTPUT: a tuple `(a,b,c)` of non-negative integers such that + OUTPUT: a tuple `(a,b,c)` of nonnegative integers such that `n = a^2 + b^2 + c^2` with `a <= b <= c`. EXAMPLES:: @@ -5636,9 +5573,9 @@ def four_squares(n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - OUTPUT: a tuple `(a,b,c,d)` of non-negative integers such that + OUTPUT: a tuple `(a,b,c,d)` of nonnegative integers such that `n = a^2 + b^2 + c^2 + d^2` with `a <= b <= c <= d`. EXAMPLES:: @@ -5708,15 +5645,15 @@ def four_squares(n): def sum_of_k_squares(k, n): """ Write the integer `n` as a sum of `k` integer squares if possible; - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. INPUT: - - ``k`` -- a non-negative integer + - ``k`` -- nonnegative integer - - ``n`` -- an integer + - ``n`` -- integer - OUTPUT: a tuple `(x_1, ..., x_k)` of non-negative integers such that + OUTPUT: a tuple `(x_1, ..., x_k)` of nonnegative integers such that their squares sum to `n`. EXAMPLES:: @@ -5762,7 +5699,7 @@ def sum_of_k_squares(k, n): sage: sum_of_k_squares(-1, 0) Traceback (most recent call last): ... - ValueError: k = -1 must be non-negative + ValueError: k = -1 must be nonnegative Tests with numpy and gmpy2 numbers:: @@ -5793,7 +5730,7 @@ def sum_of_k_squares(k, n): if n == 0: return tuple() raise ValueError("%s is not a sum of 0 squares" % n) - raise ValueError("k = %s must be non-negative" % k) + raise ValueError("k = %s must be nonnegative" % k) if n < 0: raise ValueError("%s is not a sum of %s squares" % (n,k)) @@ -5817,15 +5754,9 @@ def subfactorial(n): INPUT: + - ``n`` -- nonnegative integer - - ``n`` -- non negative integer - - - OUTPUT: - - - - ``integer`` -- function value - + OUTPUT: integer EXAMPLES:: @@ -5854,15 +5785,13 @@ def subfactorial(n): def is_power_of_two(n): r""" - Return whether ``n`` is a power of 2. + Return whether `n` is a power of 2. INPUT: - - ``n`` -- integer - - OUTPUT: + - ``n`` -- integer - boolean + OUTPUT: boolean EXAMPLES:: @@ -6041,11 +5970,9 @@ def fundamental_discriminant(D): INPUT: - - ``D`` -- an integer + - ``D`` -- integer - OUTPUT: - - - an integer, the fundamental discriminant + OUTPUT: integer; the fundamental discriminant EXAMPLES:: @@ -6084,8 +6011,8 @@ def squarefree_divisors(x): INPUT: - - x -- an element of any ring for which the prime_divisors - function works. + - ``x`` -- an element of any ring for which the prime_divisors + function works EXAMPLES: @@ -6155,12 +6082,12 @@ def dedekind_sum(p, q, algorithm='default'): INPUT: - - ``p``, ``q`` -- integers - - ``algorithm`` -- must be one of the following + - ``p``, ``q`` -- integers + - ``algorithm`` -- must be one of the following - - ``'default'`` -- (default) use FLINT - - ``'flint'`` -- use FLINT - - ``'pari'`` -- use PARI (gives different results if `p` and `q` + - ``'default'`` -- (default) use FLINT + - ``'flint'`` -- use FLINT + - ``'pari'`` -- use PARI (gives different results if `p` and `q` are not coprime) OUTPUT: a rational number @@ -6361,11 +6288,9 @@ def dedekind_psi(N): INPUT: - - ``N`` -- a positive integer + - ``N`` -- positive integer - OUTPUT: - - an integer + OUTPUT: integer The Dedekind psi function is the multiplicative function defined by diff --git a/src/sage/arith/multi_modular.pyx b/src/sage/arith/multi_modular.pyx index 583cf6cd9cc..1d5e9a46221 100644 --- a/src/sage/arith/multi_modular.pyx +++ b/src/sage/arith/multi_modular.pyx @@ -134,10 +134,8 @@ cdef class MultiModularBasis_base(): (their product will be at least 2*val) as list, tuple or generator a list of prime moduli to start with - - ``l_bound`` -- an integer: lower bound for the random primes - (default: 2^10) - - ``u_bound`` -- an integer: upper bound for the random primes - (default: 2^15) + - ``l_bound`` -- integer (default: 2^10); lower bound for the random primes + - ``u_bound`` -- integer (default: 2^15); upper bound for the random primes EXAMPLES:: @@ -186,13 +184,13 @@ cdef class MultiModularBasis_base(): cdef mod_int _new_random_prime(self, set known_primes) except 1: """ Choose a new random prime for inclusion in the list of moduli, - or raise a :class:`RuntimeError` if there are no more primes. + or raise a :exc:`RuntimeError` if there are no more primes. INPUT: - ``known_primes`` -- Python set of already known primes in the allowed interval; we will not return a prime in - known_primes. + known_primes """ cdef mod_int p while True: @@ -504,8 +502,8 @@ cdef class MultiModularBasis_base(): INPUT: - ``z`` -- the integer being reduced - - ``b`` -- array to hold the reductions mod each m_i. - It MUST be allocated and have length at least len + - ``b`` -- array to hold the reductions mod each `m_i`; + it *must* be allocated and have length at least len - ``offset`` -- first prime in list to reduce against - ``len`` -- number of primes in list to reduce against """ @@ -524,13 +522,12 @@ cdef class MultiModularBasis_base(): INPUT: - - ``z`` -- an array of integers being reduced - - ``b`` -- array to hold the reductions mod each m_i. - It MUST be fully allocated and each - have length at least len - - ``vn`` -- length of z and each b[i] + - ``z`` -- an array of integers being reduced + - ``b`` -- array to hold the reductions mod each m_i. + It *must* be fully allocated and each have length at least len. + - ``vn`` -- length of z and each b[i] - ``offset`` -- first prime in list to reduce against - - ``len`` -- number of primes in list to reduce against + - ``len`` -- number of primes in list to reduce against """ cdef int i, j cdef mod_int* m @@ -552,12 +549,12 @@ cdef class MultiModularBasis_base(): INPUT: - - ``z`` -- a placeholder for the constructed integer - z MUST be initialized IF and ONLY IF offset > 0 - - ``b`` -- array holding the reductions mod each m_i. - It MUST have length at least len + - ``z`` -- a placeholder for the constructed integer; *must* be + initialized if and only if ``offset > 0`` + - ``b`` -- array holding the reductions mod each m_i; *must* have + length at least ``len`` - ``offset`` -- first prime in list to reduce against - - ``len`` -- number of primes in list to reduce against + - ``len`` -- number of primes in list to reduce against """ cdef int i, s cdef mpz_t u @@ -568,7 +565,7 @@ cdef class MultiModularBasis_base(): s = 1 mpz_init_set_si(z, b[0]) if b[0] == 0: - while s < len and b[s] == 0: # fast forward to first non-zero + while s < len and b[s] == 0: # fast forward to first nonzero s += 1 else: s = 0 @@ -594,14 +591,14 @@ cdef class MultiModularBasis_base(): INPUT: - - ``z`` -- a placeholder for the constructed integers - z MUST be allocated and have length at least vc - z[j] MUST be initialized IF and ONLY IF offset > 0 - - ``b`` -- array holding the reductions mod each m_i. - MUST have length at least len - - ``vn`` -- length of z and each b[i] + - ``z`` -- a placeholder for the constructed integers; *must* be + allocated and have length at least ``vc``. z[j] *must* be initialized + if and only if ``offset > 0``. + - ``b`` -- array holding the reductions mod each m_i. *must* have + length at least ``len``. + - ``vn`` -- length of z and each b[i] - ``offset`` -- first prime in list to reduce against - - ``len`` -- number of primes in list to reduce against + - ``len`` -- number of primes in list to reduce against """ cdef int i, j cdef mpz_t u @@ -619,7 +616,7 @@ cdef class MultiModularBasis_base(): if offset == 0: mpz_set_si(z[j], b[0][j]) if b[0][j] == 0: - while i < len and b[i][j] == 0: # fast forward to first non-zero + while i < len and b[i][j] == 0: # fast forward to first nonzero i += 1 while i < len: mpz_set_si(u, ((b[i][j] + m[i] - mpz_fdiv_ui(z[j], m[i])) * self.C[i]) % m[i]) # u = ((b_i - z) * C_i) % m_i @@ -647,7 +644,7 @@ cdef class MultiModularBasis_base(): INPUT: - - ``b`` -- a list of length at most self.n + - ``b`` -- list of length at most self.n OUTPUT: @@ -667,7 +664,6 @@ cdef class MultiModularBasis_base(): 7 sage: res % 10039 9 - """ cdef int i, n n = len(b) @@ -723,7 +719,6 @@ cdef class MultiModularBasis_base(): Traceback (most recent call last): ... IndexError: negative index not valid - """ if n >= self.n: raise IndexError("beyond bound for multi-modular prime list") @@ -866,8 +861,8 @@ cdef class MultiModularBasis(MultiModularBasis_base): INPUT: - ``z`` -- the integer being reduced - - ``b`` -- array to hold the reductions mod each m_i. - It MUST be allocated and have length at least len + - ``b`` -- array to hold the reductions mod each `m_i`; it *must* be + allocated and have length at least len """ self.mpz_reduce_tail(z, b, 0, self.n) @@ -880,10 +875,9 @@ cdef class MultiModularBasis(MultiModularBasis_base): INPUT: - ``z`` -- an array of integers being reduced - - ``b`` -- array to hold the reductions mod each m_i. - It MUST be fully allocated and each - have length at least len - - ``vn`` -- length of z and each b[i] + - ``b`` -- array to hold the reductions mod each `m_i`; it *must* be + fully allocated and each have length at least len + - ``vn`` -- length of ``z`` and each ``b[i]`` """ self.mpz_reduce_vec_tail(z, b, vn, 0, self.n) @@ -895,10 +889,10 @@ cdef class MultiModularBasis(MultiModularBasis_base): INPUT: - - ``z`` -- a placeholder for the constructed integer - z MUST NOT be initialized - - ``b`` -- array holding the reductions mod each `m_i`. - It MUST have length at least len(self) + - ``z`` -- a placeholder for the constructed integer; *must not* be + initialized + - ``b`` -- array holding the reductions mod each `m_i`; it *must* have + length at least ``len(self)`` """ self.mpz_crt_tail(z, b, 0, self.n) @@ -910,12 +904,12 @@ cdef class MultiModularBasis(MultiModularBasis_base): INPUT: - - ``z`` -- a placeholder for the constructed integers - z MUST be allocated and have length at least vn, - but each z[j] MUST NOT be initialized - - ``b`` -- array holding the reductions mod each `m_i`. - It MUST have length at least len(self) - - ``vn`` -- length of z and each b[i] + - ``z`` -- a placeholder for the constructed integers; *must* be + allocated and have length at least vn,but each z[j] *must not* be + initialized + - ``b`` -- array holding the reductions mod each `m_i`; it *must* have + length at least ``len(self)`` + - ``vn`` -- length of ``z`` and each ``b[i]`` """ self.mpz_crt_vec_tail(z, b, vn, 0, self.n) diff --git a/src/sage/arith/rational_reconstruction.pyx b/src/sage/arith/rational_reconstruction.pyx index bd07977411a..6806cda3a00 100644 --- a/src/sage/arith/rational_reconstruction.pyx +++ b/src/sage/arith/rational_reconstruction.pyx @@ -35,7 +35,7 @@ cdef int mpq_rational_reconstruction(mpq_t answer, mpz_t a, mpz_t m) except -1: sqrt(m/2). If `m` is zero, raise :class`ZeroDivisionError`. If the rational - reconstruction does not exist, raise :class:`ValueError`. + reconstruction does not exist, raise :exc:`ValueError`. We assume that ``mpq_init`` has been called on ``answer``. diff --git a/src/sage/arith/srange.pyx b/src/sage/arith/srange.pyx index 51855f9646d..63a109c4b58 100644 --- a/src/sage/arith/srange.pyx +++ b/src/sage/arith/srange.pyx @@ -203,9 +203,9 @@ def srange(*args, **kwds): the form ``start + k*step`` for some integer `k`. ` ``endpoint_tolerance`` -- used to determine whether or not the - endpoint is hit for inexact rings (default 1e-5) + endpoint is hit for inexact rings (default: ``1e-5``) - OUTPUT: a list + OUTPUT: list .. NOTE:: diff --git a/src/sage/calculus/calculus.py b/src/sage/calculus/calculus.py index 57a72736ce9..6d765144e23 100644 --- a/src/sage/calculus/calculus.py +++ b/src/sage/calculus/calculus.py @@ -388,7 +388,7 @@ the giac version, we simplify it (see :issue:`34037`). :: sage: t = SR.var('t') - sage: integrate(exp(t)/(t + 1)^2, t, algorithm="giac").full_simplify() + sage: integrate(exp(t)/(t + 1)^2, t, algorithm='giac').full_simplify() ((t + 1)*Ei(t + 1) - e^(t + 1))/(t*e + e) Check if maxima has redundant variables defined after initialization, @@ -468,7 +468,7 @@ def symbolic_sum(expression, v, a, b, algorithm='maxima', hold=False): - ``'sympy'`` -- use SymPy - - ``hold`` -- (default: ``False``) if ``True``, don't evaluate + - ``hold`` -- boolean (default: ``False``); if ``True``, don't evaluate EXAMPLES:: @@ -609,7 +609,7 @@ def symbolic_sum(expression, v, a, b, algorithm='maxima', hold=False): sage: sum (n^3 * x^n, n, 0, infinity) (x^3 + 4*x^2 + x)/(x^4 - 4*x^3 + 6*x^2 - 4*x + 1) - .. note:: + .. NOTE:: Sage can currently only understand a subset of the output of Maxima, Maple and Mathematica, so even if the chosen backend can perform @@ -700,9 +700,7 @@ def nintegral(ex, x, a, b, - ``maximum_num_subintervals`` -- (default: 200) maximal number of subintervals - OUTPUT: - - - float: approximation to the integral + OUTPUT: float; approximation to the integral - float: estimated absolute error of the approximation @@ -851,7 +849,7 @@ def symbolic_product(expression, v, a, b, algorithm='maxima', hold=False): - ``'mathematica'`` -- (optional) use Mathematica - - ``hold`` -- (default: ``False``) if ``True``, don't evaluate + - ``hold`` -- boolean (default: ``False``); if ``True``, don't evaluate EXAMPLES:: @@ -880,7 +878,6 @@ def symbolic_product(expression, v, a, b, algorithm='maxima', hold=False): sage: symbolic_product(-x^2,x,1,n) (-1)^n*factorial(n)^2 - """ if not (isinstance(v, Expression) and v.is_symbol()): if isinstance(v, str): @@ -941,7 +938,7 @@ def minpoly(ex, var='x', algorithm=None, bits=None, degree=None, epsilon=0): INPUT: - - ``var`` -- polynomial variable name (default 'x') + - ``var`` -- polynomial variable name (default: ``'x'``) - ``algorithm`` -- ``'algebraic'`` or ``'numerical'`` (default both, but with numerical first) @@ -952,7 +949,7 @@ def minpoly(ex, var='x', algorithm=None, bits=None, degree=None, epsilon=0): - ``degree`` -- the expected algebraic degree - ``epsilon`` -- return without error as long as - f(self) epsilon, in the case that the result cannot be proven. + f(self) epsilon, in the case that the result cannot be proven All of the above parameters are optional, with epsilon=0, ``bits`` and ``degree`` tested up to 1000 and 24 by default respectively. The @@ -960,16 +957,15 @@ def minpoly(ex, var='x', algorithm=None, bits=None, degree=None, epsilon=0): explicitly. The algebraic algorithm ignores the last three parameters. - - OUTPUT: The minimal polynomial of ``self``. If the numerical algorithm + OUTPUT: the minimal polynomial of ``self``. If the numerical algorithm is used, then it is proved symbolically when ``epsilon=0`` (default). If the minimal polynomial could not be found, two distinct kinds of errors are raised. If no reasonable candidate was found with the - given ``bits``/``degree`` parameters, a :class:`ValueError` will be + given ``bits``/``degree`` parameters, a :exc:`ValueError` will be raised. If a reasonable candidate was found but (perhaps due to limits in the underlying symbolic package) was unable to be proved - correct, a :class:`NotImplementedError` will be raised. + correct, a :exc:`NotImplementedError` will be raised. ALGORITHM: Two distinct algorithms are used, depending on the algorithm parameter. By default, the numerical algorithm is @@ -988,11 +984,11 @@ def minpoly(ex, var='x', algorithm=None, bits=None, degree=None, epsilon=0): minpoly `f`. If `f(\mathtt{self})`, evaluated to a higher precision, is close enough to 0 then evaluate `f(\mathtt{self})` symbolically, attempting to prove - vanishing. If this fails, and ``epsilon`` is non-zero, + vanishing. If this fails, and ``epsilon`` is nonzero, return `f` if and only if `f(\mathtt{self}) < \mathtt{epsilon}`. - Otherwise raise a :class:`ValueError` (if no suitable - candidate was found) or a :class:`NotImplementedError` (if a + Otherwise raise a :exc:`ValueError` (if no suitable + candidate was found) or a :exc:`NotImplementedError` (if a likely candidate was found but could not be proved correct). EXAMPLES: First some simple examples:: @@ -1103,7 +1099,7 @@ def minpoly(ex, var='x', algorithm=None, bits=None, degree=None, epsilon=0): ... ValueError: Could not find minimal polynomial (1000 bits, degree 24). - .. note:: + .. NOTE:: Of course, failure to produce a minimal polynomial does not necessarily indicate that this number is transcendental. @@ -1171,18 +1167,18 @@ def limit(ex, dir=None, taylor=False, algorithm='maxima', **argv): INPUT: - - ``dir`` -- (default: ``None``); may have the value + - ``dir`` -- (default: ``None``) may have the value ``'plus'`` (or ``'+'`` or ``'right'`` or ``'above'``) for a limit from above, ``'minus'`` (or ``'-'`` or ``'left'`` or ``'below'``) for a limit from below, or may be omitted (implying a two-sided limit is to be computed). - - ``taylor`` -- (default: ``False``); if ``True``, use Taylor + - ``taylor`` -- (default: ``False``) if ``True``, use Taylor series, which allows more limits to be computed (but may also crash in some obscure cases due to bugs in Maxima). - ``**argv`` -- 1 named parameter - .. note:: + .. NOTE:: The output may also use ``und`` (undefined), ``ind`` (indefinite but bounded), and ``infinity`` (complex @@ -1642,7 +1638,7 @@ def laplace(ex, t, s, algorithm='maxima'): sage: p1 = plot(xt, 0, 1/2, rgbcolor=(1,0,0)) # needs sage.plot sage: p2 = plot(yt, 0, 1/2, rgbcolor=(0,1,0)) # needs sage.plot sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # needs sage.plot + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # needs sage.plot ....: (p1 + p2).save(f.name) Another example:: @@ -2019,7 +2015,6 @@ def at(ex, *args, **kwds): sage: from sage.calculus.calculus import at sage: at(int(1), x=1) 1 - """ if not isinstance(ex, (Expression, Function)): ex = SR(ex) @@ -2114,7 +2109,7 @@ def dummy_inverse_laplace(*args): def dummy_pochhammer(*args): """ - This function is called to create formal wrappers of Pochhammer symbols + This function is called to create formal wrappers of Pochhammer symbols. EXAMPLES:: @@ -2148,7 +2143,6 @@ def _laplace_latex_(self, *args): '\\mathcal{L}\\left(f\\left(t\\right), t, s\\right)' sage: latex(laplace(f, t, s)) \mathcal{L}\left(f\left(t\right), t, s\right) - """ return "\\mathcal{L}\\left(%s\\right)" % (', '.join(latex(x) for x in args)) @@ -2236,13 +2230,13 @@ def symbolic_expression_from_maxima_string(x, equals_sub=False, maxima=maxima): INPUT: - - ``x`` -- a string + - ``x`` -- string - - ``equals_sub`` -- (default: ``False``) if ``True``, replace + - ``equals_sub`` -- boolean (default: ``False``); if ``True``, replace '=' by '==' in self - ``maxima`` -- (default: the calculus package's copy of - Maxima) the Maxima interpreter to use. + Maxima) the Maxima interpreter to use EXAMPLES:: @@ -2429,7 +2423,7 @@ def mapped_opts(v): - ``v`` -- an object - OUTPUT: a string. + OUTPUT: string The main use of this is to turn Python bools into lower case strings. @@ -2560,13 +2554,13 @@ def symbolic_expression_from_string(s, syms=None, accept_sequence=False, *, pars INPUT: - - ``s`` -- a string + - ``s`` -- string - ``syms`` -- (default: ``{}``) dictionary of strings to be regarded as symbols or functions; keys are pairs (string, number of arguments) - - ``accept_sequence`` -- (default: ``False``) controls whether + - ``accept_sequence`` -- boolean (default: ``False``); controls whether to allow a (possibly nested) set of lists and tuples as input diff --git a/src/sage/calculus/desolvers.py b/src/sage/calculus/desolvers.py index 9f9d7534845..48dad835671 100644 --- a/src/sage/calculus/desolvers.py +++ b/src/sage/calculus/desolvers.py @@ -14,40 +14,40 @@ Commands: -- :func:`desolve` -- Compute the "general solution" to a 1st or 2nd order - ODE via Maxima. +- :func:`desolve` -- compute the "general solution" to a 1st or 2nd order + ODE via Maxima -- :func:`desolve_laplace` -- Solve an ODE using Laplace transforms via - Maxima. Initial conditions are optional. +- :func:`desolve_laplace` -- solve an ODE using Laplace transforms via + Maxima. Initial conditions are optional -- :func:`desolve_rk4` -- Solve numerically an IVP for one first order - equation, return list of points or plot. +- :func:`desolve_rk4` -- solve numerically an IVP for one first order + equation, return list of points or plot -- :func:`desolve_system_rk4` -- Solve numerically an IVP for a system of first - order equations, return list of points. +- :func:`desolve_system_rk4` -- solve numerically an IVP for a system of first + order equations, return list of points -- :func:`desolve_odeint` -- Solve numerically a system of first-order ordinary +- :func:`desolve_odeint` -- solve numerically a system of first-order ordinary differential equations using :func:`~scipy:scipy.integrate.odeint` from the module :mod:`scipy:scipy.integrate`. -- :func:`desolve_system` -- Solve a system of 1st order ODEs of any size using - Maxima. Initial conditions are optional. +- :func:`desolve_system` -- solve a system of 1st order ODEs of any size using + Maxima. Initial conditions are optional -- :func:`eulers_method` -- Approximate solution to a 1st order DE, - presented as a table. +- :func:`eulers_method` -- approximate solution to a 1st order DE, + presented as a table -- :func:`eulers_method_2x2` -- Approximate solution to a 1st order system - of DEs, presented as a table. +- :func:`eulers_method_2x2` -- approximate solution to a 1st order system + of DEs, presented as a table -- :func:`eulers_method_2x2_plot` -- Plot the sequence of points obtained - from Euler's method. +- :func:`eulers_method_2x2_plot` -- plot the sequence of points obtained + from Euler's method The following functions require the optional package ``tides``: -- :func:`desolve_mintides` -- Numerical solution of a system of 1st order ODEs via - the Taylor series integrator method implemented in TIDES. +- :func:`desolve_mintides` -- numerical solution of a system of 1st order ODEs via + the Taylor series integrator method implemented in TIDES -- :func:`desolve_tides_mpfr` -- Arbitrary precision Taylor series integrator implemented in TIDES. +- :func:`desolve_tides_mpfr` -- arbitrary precision Taylor series integrator implemented in TIDES AUTHORS: @@ -93,10 +93,10 @@ def fricas_desolve(de, dvar, ics, ivar): sage: x = var('x') sage: y = function('y')(x) - sage: desolve(diff(y,x) + y - 1, y, algorithm="fricas") # optional - fricas + sage: desolve(diff(y,x) + y - 1, y, algorithm='fricas') # optional - fricas _C0*e^(-x) + 1 - sage: desolve(diff(y, x) + y == y^3*sin(x), y, algorithm="fricas") # optional - fricas + sage: desolve(diff(y, x) + y == y^3*sin(x), y, algorithm='fricas') # optional - fricas -1/5*(2*cos(x)*y(x)^2 + 4*sin(x)*y(x)^2 - 5)*e^(-2*x)/y(x)^2 TESTS:: @@ -133,11 +133,11 @@ def fricas_desolve_system(des, dvars, ics, ivar): sage: y = function('y')(t) sage: de1 = diff(x,t) + y - 1 == 0 sage: de2 = diff(y,t) - x + 1 == 0 - sage: desolve_system([de1, de2], [x, y], algorithm="fricas") # optional - fricas + sage: desolve_system([de1, de2], [x, y], algorithm='fricas') # optional - fricas [x(t) == _C0*cos(t) + cos(t)^2 + _C1*sin(t) + sin(t)^2, y(t) == -_C1*cos(t) + _C0*sin(t) + 1] - sage: desolve_system([de1, de2], [x,y], [0,1,2], algorithm="fricas") # optional - fricas + sage: desolve_system([de1, de2], [x,y], [0,1,2], algorithm='fricas') # optional - fricas [x(t) == cos(t)^2 + sin(t)^2 - sin(t), y(t) == cos(t) + 1] TESTS:: @@ -154,7 +154,6 @@ def fricas_desolve_system(des, dvars, ics, ivar): sage: sol = fricas_desolve_system([de1,de2], [x,y], [0,1,-1], t) # optional - fricas sage: sol # optional - fricas [x(t) == cos(t)^2 + sin(t)^2 + 2*sin(t), y(t) == -2*cos(t) + 1] - """ from sage.interfaces.fricas import fricas from sage.symbolic.ring import SR @@ -178,7 +177,7 @@ def fricas_desolve_system(des, dvars, ics, ivar): def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False, - algorithm="maxima"): + algorithm='maxima'): r""" Solve a 1st or 2nd order linear ODE, including IVP and BVP. @@ -473,20 +472,20 @@ def desolve(de, dvar, ics=None, ivar=None, show_method=False, contrib_ode=False, order linear equations:: sage: de = x^3*diff(y, x, 3) + x^2*diff(y, x, 2) - 2*x*diff(y, x) + 2*y - 2*x^4 - sage: Y = desolve(de, y, algorithm="fricas"); Y # optional - fricas + sage: Y = desolve(de, y, algorithm='fricas'); Y # optional - fricas (2*x^3 - 3*x^2 + 1)*_C0/x + (x^3 - 1)*_C1/x + (x^3 - 3*x^2 - 1)*_C2/x + 1/15*(x^5 - 10*x^3 + 20*x^2 + 4)/x The initial conditions are then interpreted as `[x_0, y(x_0), y'(x_0), \ldots, y^(n)(x_0)]`:: - sage: Y = desolve(de, y, ics=[1,3,7], algorithm="fricas"); Y # optional - fricas + sage: Y = desolve(de, y, ics=[1,3,7], algorithm='fricas'); Y # optional - fricas 1/15*(x^5 + 15*x^3 + 50*x^2 - 21)/x FriCAS can also solve some non-linear equations:: sage: de = diff(y, x) == y / (x+y*log(y)) - sage: Y = desolve(de, y, algorithm="fricas"); Y # optional - fricas + sage: Y = desolve(de, y, algorithm='fricas'); Y # optional - fricas 1/2*(log(y(x))^2*y(x) - 2*x)/y(x) TESTS: @@ -674,12 +673,10 @@ def desolve_laplace(de, dvar, ics=None, ivar=None): `x`), which must be specified if there is more than one independent variable in the equation. - - ``ics`` -- a list of numbers representing initial conditions, (e.g. + - ``ics`` -- list of numbers representing initial conditions, (e.g. ``f(0)=1``, ``f'(0)=2`` corresponds to ``ics = [0,1,2]``) - OUTPUT: - - Solution of the ODE as symbolic expression + OUTPUT: solution of the ODE as symbolic expression EXAMPLES:: @@ -789,7 +786,7 @@ def sanitize_var(exprs): return soln -def desolve_system(des, vars, ics=None, ivar=None, algorithm="maxima"): +def desolve_system(des, vars, ics=None, ivar=None, algorithm='maxima'): r""" Solve a system of any size of 1st order ODEs. Initial conditions are optional. @@ -950,7 +947,7 @@ def desolve_system(des, vars, ics=None, ivar=None, algorithm="maxima"): return soln -def eulers_method(f, x0, y0, h, x1, algorithm="table"): +def eulers_method(f, x0, y0, h, x1, algorithm='table'): r""" This implements Euler's method for finding numerically the solution of the 1st order ODE `y' = f(x,y)`, `y(a)=c`. The ``x`` @@ -976,7 +973,7 @@ def eulers_method(f, x0, y0, h, x1, algorithm="table"): :: sage: x,y = PolynomialRing(QQ,2,"xy").gens() - sage: eulers_method(5*x+y-5,0,1,1/2,1,algorithm="none") + sage: eulers_method(5*x+y-5,0,1,1/2,1,algorithm='none') [[0, 1], [1/2, -1], [1, -11/4], [3/2, -33/8]] :: @@ -1008,12 +1005,12 @@ def eulers_method(f, x0, y0, h, x1, algorithm="table"): :: - sage: eulers_method(5*x+y-5,0,1,1/2,1,algorithm="none") + sage: eulers_method(5*x+y-5,0,1,1/2,1,algorithm='none') [[0, 1], [1/2, -1], [1, -11/4], [3/2, -33/8]] :: - sage: pts = eulers_method(5*x+y-5,0,1,1/2,1,algorithm="none") + sage: pts = eulers_method(5*x+y-5,0,1,1/2,1,algorithm='none') sage: P1 = list_plot(pts) # needs sage.plot sage: P2 = line(pts) # needs sage.plot sage: (P1 + P2).show() # needs sage.plot @@ -1038,7 +1035,7 @@ def eulers_method(f, x0, y0, h, x1, algorithm="table"): return soln -def eulers_method_2x2(f, g, t0, x0, y0, h, t1, algorithm="table"): +def eulers_method_2x2(f, g, t0, x0, y0, h, t1, algorithm='table'): r""" This implements Euler's method for finding numerically the solution of the 1st order system of two ODEs @@ -1066,7 +1063,7 @@ def eulers_method_2x2(f, g, t0, x0, y0, h, t1, algorithm="table"): sage: from sage.calculus.desolvers import eulers_method_2x2 sage: t, x, y = PolynomialRing(QQ,3,"txy").gens() sage: f = x+y+t; g = x-y - sage: eulers_method_2x2(f,g, 0, 0, 0, 1/3, 1,algorithm="none") + sage: eulers_method_2x2(f,g, 0, 0, 0, 1/3, 1,algorithm='none') [[0, 0, 0], [1/3, 0, 0], [2/3, 1/9, 0], [1, 10/27, 1/27], [4/3, 68/81, 4/27]] :: @@ -1217,7 +1214,6 @@ def desolve_rk4_determine_bounds(ics, end_points=None): sage: desolve_rk4_determine_bounds([0,2],[-2,4]) (-2, 4) - """ if end_points is None: return ics[0], ics[0] + 10 @@ -1264,7 +1260,7 @@ def desolve_rk4(de, dvar, ics=None, ivar=None, end_points=None, step=0.1, output - if end_points is [a,b] we integrate between ``min(ics[0], a)`` and ``max(ics[0], b)`` - - ``step`` -- (default:0.1) the length of the step (positive number) + - ``step`` -- (default: 0.1) the length of the step (positive number) - ``output`` -- (default: ``'list'``) one of ``'list'``, ``'plot'``, ``'slope_field'`` (graph of the solution with slope field) @@ -1305,7 +1301,7 @@ def desolve_rk4(de, dvar, ics=None, ivar=None, end_points=None, step=0.1, output ALGORITHM: - 4th order Runge-Kutta method. Wrapper for command ``rk`` in + `4`-th order Runge-Kutta method. Wrapper for command ``rk`` in Maxima's dynamics package. Perhaps could be faster by using fast_float instead. @@ -1390,12 +1386,12 @@ def desolve_rk4_inner(de, dvar): def desolve_system_rk4(des, vars, ics=None, ivar=None, end_points=None, step=0.1): r""" Solve numerically a system of first-order ordinary differential - equations using the 4th order Runge-Kutta method. Wrapper for + equations using the `4`-th order Runge-Kutta method. Wrapper for Maxima command ``rk``. INPUT: - input is similar to desolve_system and desolve_rk4 commands + Input is similar to ``desolve_system`` and ``desolve_rk4`` commands - ``des`` -- right hand sides of the system @@ -1416,9 +1412,7 @@ def desolve_system_rk4(des, vars, ics=None, ivar=None, end_points=None, step=0.1 - ``step`` -- (default: 0.1) the length of the step - OUTPUT: - - Return a list of points. + OUTPUT: a list of points .. SEEALSO:: @@ -1442,7 +1436,7 @@ def desolve_system_rk4(des, vars, ics=None, ivar=None, end_points=None, step=0.1 ALGORITHM: - 4th order Runge-Kutta method. Wrapper for command ``rk`` in Maxima's + `4`-th order Runge-Kutta method. Wrapper for command ``rk`` in Maxima's dynamics package. Perhaps could be faster by using ``fast_float`` instead. @@ -1503,19 +1497,20 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=() INPUT: - - ``des`` -- right hand sides of the system + - ``des`` -- right hand sides of the system - - ``ics`` -- initial conditions + - ``ics`` -- initial conditions - ``times`` -- a sequence of time points in which the solution must be found - ``dvars`` -- dependent variables. ATTENTION: the order must be the same as in ``des``, that means: ``d(dvars[i])/dt=des[i]`` - - ``ivar`` -- independent variable, optional. + - ``ivar`` -- independent variable, optional - - ``compute_jac`` -- boolean. If True, the Jacobian of ``des`` is computed and - used during the integration of stiff systems. Default value is False. + - ``compute_jac`` -- boolean (default: ``False``); if ``True``, the + Jacobian of ``des`` is computed and used during the integration of stiff + systems Other Parameters (taken from the documentation of the :func:`~scipy:scipy.integrate.odeint` function from @@ -1564,9 +1559,7 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=() - ``mxords`` : integer, (0: solver-determined) Maximum order to be allowed for the stiff (BDF) method. - OUTPUT: - - Return a list with the solution of the system at each time in ``times``. + OUTPUT: a list with the solution of the system at each time in ``times`` EXAMPLES: @@ -1700,26 +1693,22 @@ def desolve_mintides(f, ics, initial, final, delta, tolrel=1e-16, tolabs=1e-16): INPUT: - - ``f`` -- symbolic function. Its first argument will be the independent - variable. Its output should be de derivatives of the dependent variables. - - - ``ics`` -- a list or tuple with the initial conditions. - - - ``initial`` -- the starting value for the independent variable. + - ``f`` -- symbolic function; its first argument will be the independent + variable, . Its output should be de derivatives of the dependent variables. - - ``final`` -- the final value for the independent value. + - ``ics`` -- list or tuple with the initial conditions - - ``delta`` -- the size of the steps in the output. + - ``initial`` -- the starting value for the independent variable - - ``tolrel`` -- the relative tolerance for the method. + - ``final`` -- the final value for the independent value - - ``tolabs`` -- the absolute tolerance for the method. + - ``delta`` -- the size of the steps in the output + - ``tolrel`` -- the relative tolerance for the method - OUTPUT: - - - A list with the positions of the IVP. + - ``tolabs`` -- the absolute tolerance for the method + OUTPUT: list with the positions of the IVP EXAMPLES: @@ -1791,28 +1780,24 @@ def desolve_tides_mpfr(f, ics, initial, final, delta, tolrel=1e-16, tolabs=1e-16 INPUT: - - ``f`` -- symbolic function. Its first argument will be the independent + - ``f`` -- symbolic function; its first argument will be the independent variable. Its output should be de derivatives of the dependent variables. - - ``ics`` -- a list or tuple with the initial conditions. + - ``ics`` -- list or tuple with the initial conditions - - ``initial`` -- the starting value for the independent variable. + - ``initial`` -- the starting value for the independent variable - - ``final`` -- the final value for the independent value. + - ``final`` -- the final value for the independent value - - ``delta`` -- the size of the steps in the output. + - ``delta`` -- the size of the steps in the output - - ``tolrel`` -- the relative tolerance for the method. + - ``tolrel`` -- the relative tolerance for the method - - ``tolabs`` -- the absolute tolerance for the method. - - - ``digits`` -- the digits of precision used in the computation. - - - OUTPUT: + - ``tolabs`` -- the absolute tolerance for the method - - A list with the positions of the IVP. + - ``digits`` -- the digits of precision used in the computation + OUTPUT: list with the positions of the IVP EXAMPLES: diff --git a/src/sage/calculus/expr.py b/src/sage/calculus/expr.py index 7e56c888cac..f36d56b6c40 100644 --- a/src/sage/calculus/expr.py +++ b/src/sage/calculus/expr.py @@ -19,9 +19,7 @@ def symbolic_expression(x): - ``x`` - an object - OUTPUT: - - - a symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: diff --git a/src/sage/calculus/functional.py b/src/sage/calculus/functional.py index 6bd480c20e0..8747e1df790 100644 --- a/src/sage/calculus/functional.py +++ b/src/sage/calculus/functional.py @@ -29,7 +29,7 @@ from sage.structure.element import Expression -def simplify(f, algorithm="maxima", **kwds): +def simplify(f, algorithm='maxima', **kwds): r""" Simplify the expression `f`. @@ -53,7 +53,7 @@ def simplify(f, algorithm="maxima", **kwds): sage: ex = 1/2*I*x + 1/2*I*sqrt(x^2 - 1) + 1/2/(I*x + I*sqrt(x^2 - 1)) sage: simplify(ex) 1/2*I*x + 1/2*I*sqrt(x^2 - 1) + 1/(2*I*x + 2*I*sqrt(x^2 - 1)) - sage: simplify(ex, algorithm="giac") + sage: simplify(ex, algorithm='giac') I*sqrt(x^2 - 1) """ try: @@ -158,7 +158,6 @@ def derivative(f, *args, **kwds): 2-form da on the 2-dimensional differentiable manifold M sage: derivative(a).display() da = 2 dx∧dy - """ try: return f.derivative(*args, **kwds) @@ -336,14 +335,14 @@ def limit(f, dir=None, taylor=False, **argv): INPUT: - - ``dir`` -- (default: None); dir may have the value - 'plus' (or 'above') for a limit from above, 'minus' (or 'below') - for a limit from below, or may be omitted (implying a two-sided - limit is to be computed). + - ``dir`` -- (default: ``None``) dir may have the value ``'plus'`` (or + ``'above'``) for a limit from above, ``'minus'`` (or ``'below'``) for a + limit from below, or may be omitted (implying a two-sided limit is to be + computed). - - ``taylor`` -- (default: ``False``); if True, use Taylor - series, which allows more limits to be computed (but may also - crash in some obscure cases due to bugs in Maxima). + - ``taylor`` -- (default: ``False``) if ``True``, use Taylor + series, which allows more limits to be computed (but may also + crash in some obscure cases due to bugs in Maxima). - ``\*\*argv`` -- 1 named parameter @@ -381,7 +380,7 @@ def limit(f, dir=None, taylor=False, **argv): def taylor(f, *args): """ - Expands self in a truncated Taylor or Laurent series in the + Expand ``self`` in a truncated Taylor or Laurent series in the variable `v` around the point `a`, containing terms through `(x - a)^n`. Functions in more variables are also supported. diff --git a/src/sage/calculus/functions.py b/src/sage/calculus/functions.py index efb8926b317..c044cc0a968 100644 --- a/src/sage/calculus/functions.py +++ b/src/sage/calculus/functions.py @@ -25,7 +25,7 @@ def wronskian(*args): function. The Wronskian of a list of functions is a determinant of derivatives. - The nth row (starting from 0) is a list of the nth derivatives of the + The `n`-th row (starting from 0) is a list of the `n`-th derivatives of the given functions. For two functions:: diff --git a/src/sage/calculus/integration.pyx b/src/sage/calculus/integration.pyx index f0cd3a9f1ca..f746f8aa04a 100644 --- a/src/sage/calculus/integration.pyx +++ b/src/sage/calculus/integration.pyx @@ -72,7 +72,7 @@ def numerical_integral(func, a, b=None, INPUT: - - ``a``, ``b`` -- The interval of integration, specified as two + - ``a``, ``b`` -- the interval of integration, specified as two numbers or as a tuple/list with the first element the lower bound and the second element the upper bound. Use ``+Infinity`` and ``-Infinity`` for plus or minus infinity. @@ -87,7 +87,7 @@ def numerical_integral(func, a, b=None, - ``eps_abs``, ``eps_rel`` -- sets the absolute and relative error tolerances which satisfies the relation ``|RESULT - I| <= max(eps_abs, eps_rel * |I|)``, where ``I = \int_a^b f(x) d x``. - - ``rule`` -- This controls the Gauss-Kronrod rule used in the adaptive integration: + - ``rule`` -- this controls the Gauss-Kronrod rule used in the adaptive integration: * rule=1 -- 15 point rule * rule=2 -- 21 point rule @@ -253,7 +253,6 @@ def numerical_integral(func, a, b=None, sage: h(x) = x sage: numerical_integral(h,0,1)[0] # abs tol 1e-8 0.5 - """ cdef double abs_err # step size cdef double result diff --git a/src/sage/calculus/interpolation.pyx b/src/sage/calculus/interpolation.pyx index c2acab64fd9..230bedda658 100644 --- a/src/sage/calculus/interpolation.pyx +++ b/src/sage/calculus/interpolation.pyx @@ -173,7 +173,6 @@ cdef class Spline: [(2, 3), (4, 5), (5, 5)] sage: S(3) 4.25 - """ del self.v[i] self.stop_interp() @@ -195,7 +194,6 @@ cdef class Spline: [(1, 1), (2, 3), (4, 5), (5, 5)] sage: S(3) 4.375 - """ self.v.append(xy) self.stop_interp() @@ -219,7 +217,6 @@ cdef class Spline: [(1, 1), (2, 3), (3, 2)] sage: S.list() [(1, 1), (2, 3), (4, 5)] - """ return self.v[:] @@ -309,9 +306,9 @@ cdef class Spline: INPUT: - - ``x`` -- value at which to evaluate the derivative. + - ``x`` -- value at which to evaluate the derivative - - ``order`` (default: 1) -- order of the derivative. Must be 1 or 2. + - ``order`` -- (default: 1) order of the derivative; must be 1 or 2 EXAMPLES: @@ -329,7 +326,6 @@ cdef class Spline: -1.125 sage: s.derivative(3, order=2) -1.125 - """ if (order!=1) and (order!=2): raise ValueError("Order of derivative must be 1 or 2.") @@ -352,9 +348,9 @@ cdef class Spline: INPUT: - - ``a`` -- Lower bound for the integral. + - ``a`` -- lower bound for the integral - - ``b`` -- Upper bound for the integral. + - ``b`` -- upper bound for the integral EXAMPLES: @@ -370,7 +366,6 @@ cdef class Spline: 3.75 sage: s.definite_integral(2, 0) -3.75 - """ # GSL chokes when the upper bound is smaller than the lower bound bounds_swapped = False diff --git a/src/sage/calculus/interpolators.pyx b/src/sage/calculus/interpolators.pyx index bb0be7bab0c..c13fcff8f93 100644 --- a/src/sage/calculus/interpolators.pyx +++ b/src/sage/calculus/interpolators.pyx @@ -36,14 +36,13 @@ cdef double TWOPI = 2*pi def polygon_spline(pts): """ - Creates a polygon from a set of complex or `(x,y)` points. The polygon + Create a polygon from a set of complex or `(x,y)` points. The polygon will be a parametric curve from 0 to 2*pi. The returned values will be complex, not `(x,y)`. INPUT: - - ``pts`` -- A list or array of complex numbers of tuples of the form - `(x,y)`. + - ``pts`` -- list or array of complex numbers of tuples of the form `(x,y)` EXAMPLES: @@ -109,8 +108,8 @@ cdef class PSpline: INPUT: - - ``t`` -- double, the parameter value for the parameterized curve, - between 0 and 2*pi. + - ``t`` -- double; the parameter value for the parameterized curve, + between 0 and 2*pi OUTPUT: @@ -142,8 +141,8 @@ cdef class PSpline: INPUT: - - ``t`` -- double, the parameter value for the parameterized curve, - between 0 and 2*pi. + - ``t`` -- double; the parameter value for the parameterized curve, + between 0 and 2*pi OUTPUT: @@ -172,14 +171,13 @@ cdef class PSpline: def complex_cubic_spline(pts): """ - Creates a cubic spline interpolated figure from a set of complex or + Create a cubic spline interpolated figure from a set of complex or `(x,y)` points. The figure will be a parametric curve from 0 to 2*pi. The returned values will be complex, not `(x,y)`. INPUT: - - ``pts`` -- A list or array of complex numbers, or tuples of the form - `(x,y)`. + - ``pts`` -- list or array of complex numbers, or tuples of the form `(x,y)` EXAMPLES: @@ -267,8 +265,8 @@ cdef class CCSpline: INPUT: - - ``t`` -- double, the parameter value for the parameterized curve, - between 0 and 2*pi. + - ``t`` -- double; the parameter value for the parameterized curve, + between 0 and 2*pi OUTPUT: @@ -301,8 +299,8 @@ cdef class CCSpline: INPUT: - - ``t`` -- double, the parameter value for the parameterized curve, - between 0 and 2*pi. + - ``t`` -- double; the parameter value for the parameterized curve, + between 0 and 2*pi OUTPUT: diff --git a/src/sage/calculus/ode.pyx b/src/sage/calculus/ode.pyx index 0db64d86fe0..646b937e2e4 100644 --- a/src/sage/calculus/ode.pyx +++ b/src/sage/calculus/ode.pyx @@ -143,13 +143,13 @@ class ode_solver(): - ``'rk2'`` -- embedded Runge-Kutta (2,3) - - ``'rk4'`` -- 4th order classical Runge-Kutta + - ``'rk4'`` -- `4`-th order classical Runge-Kutta - ``'rk8pd'`` -- Runge-Kutta Prince-Dormand (8,9) - ``'rk2imp'`` -- implicit 2nd order Runge-Kutta at gaussian points - - ``'rk4imp'`` -- implicit 4th order Runge-Kutta at gaussian points + - ``'rk4imp'`` -- implicit `4`-th order Runge-Kutta at gaussian points - ``'bsimp'`` -- implicit Burlisch-Stoer (requires jacobian) @@ -242,7 +242,7 @@ class ode_solver(): sage: T.jacobian = j_1 sage: T.ode_solve(y_0=[1,0], t_span=[0,100], params=[10.0], num_points=1000) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # needs sage.plot + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # needs sage.plot ....: T.plot_solution(filename=f.name) The solver line is equivalent to:: @@ -267,7 +267,7 @@ class ode_solver(): By default ``T.plot_solution()`` plots the `y_0`; to plot general `y_i`, use:: - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # needs sage.plot + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # needs sage.plot ....: T.plot_solution(i=0, filename=f.name) ....: T.plot_solution(i=1, filename=f.name) ....: T.plot_solution(i=2, filename=f.name) @@ -292,7 +292,7 @@ class ode_solver(): ode_solver. The previous example can be rewritten as:: sage: T = ode_solver(g_1, y_0=[0,1,1], scale_abs=[1e-4,1e-4,1e-5], - ....: error_rel=1e-4, algorithm="rk8pd") + ....: error_rel=1e-4, algorithm='rk8pd') sage: T.ode_solve(t_span=[0,12], num_points=100) sage: f = T.interpolate_solution() sage: f(pi) @@ -338,10 +338,10 @@ class ode_solver(): sage: T.ode_solve(y_0=[1, 0], t_span=[0, 2000], ....: num_points=1000) sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(suffix=".png") as f: + sage: with NamedTemporaryFile(suffix='.png') as f: ....: T.plot_solution(i=0, filename=f.name) """ - def __init__(self, function=None, jacobian=None, h=1e-2, error_abs=1e-10, error_rel=1e-10, a=False, a_dydt=False, scale_abs=False, algorithm="rkf45", y_0=None, t_span=None, params=[]): + def __init__(self, function=None, jacobian=None, h=1e-2, error_abs=1e-10, error_rel=1e-10, a=False, a_dydt=False, scale_abs=False, algorithm='rkf45', y_0=None, t_span=None, params=[]): self.function = function self.jacobian = jacobian self.h = h @@ -371,9 +371,9 @@ class ode_solver(): INPUT: - - ``i`` -- (non-negative integer) composant of the projection + - ``i`` -- nonnegative integer; composant of the projection - - ``filename`` -- (string or ``None``) whether to plot the picture or + - ``filename`` -- string or ``None``; whether to plot the picture or save it in a file - ``interpolate`` -- whether to interpolate between the points of the diff --git a/src/sage/calculus/riemann.pyx b/src/sage/calculus/riemann.pyx index c09d93c4260..385aa7a09f8 100644 --- a/src/sage/calculus/riemann.pyx +++ b/src/sage/calculus/riemann.pyx @@ -89,43 +89,42 @@ cdef class Riemann_Map: INPUT: - - ``fs`` -- A list of the boundaries of the region, given as + - ``fs`` -- list of the boundaries of the region, given as complex-valued functions with domain `0` to `2*pi`. Note that the outer boundary must be parameterized counter clockwise (i.e. ``e^(I*t)``) while the inner boundaries must be clockwise (i.e. ``e^(-I*t)``). - - ``fprimes`` -- A list of the derivatives of the boundary functions. - Must be in the same order as ``fs``. + - ``fprimes`` -- list of the derivatives of the boundary functions + (Must be in the same order as ``fs``) - - ``a`` -- Complex, the center of the Riemann map. Will be mapped to + - ``a`` -- complex, the center of the Riemann map. Will be mapped to the origin of the unit disc. Note that ``a`` MUST be within the region in order for the results to be mathematically valid. The following inputs may be passed in as named parameters: - - ``N`` -- integer (default: ``500``), the number of collocation points + - ``N`` -- integer (default: `500`); the number of collocation points used to compute the map. More points will give more accurate results, especially near the boundaries, but will take longer to compute. - - ``exterior`` -- boolean (default: ``False``), if set to ``True``, the + - ``exterior`` -- boolean (default: ``False``); if set to ``True``, the exterior map will be computed, mapping the exterior of the region to the exterior of the unit circle. The following inputs may be passed as named parameters in unusual circumstances: - - ``ncorners`` -- integer (default: ``4``), if mapping a figure with + - ``ncorners`` -- integer (default: `4`); if mapping a figure with (equally t-spaced) corners -- corners that make a significant change in the direction of the boundary -- better results may be sometimes obtained by accurately giving this parameter. Used to add the proper constant to the theta correspondence function. - - ``opp`` -- boolean (default: ``False``), set to ``True`` in very rare + - ``opp`` -- boolean (default: ``False``); set to ``True`` in very rare cases where the theta correspondence function is off by ``pi``, that is, if red is mapped left of the origin in the color plot. - EXAMPLES: The unit circle identity map:: @@ -190,8 +189,6 @@ cdef class Riemann_Map: This class computes the Riemann Map via the Szego kernel using an adaptation of the method described by [KT1986]_. - - """ cdef int N, B, ncorners cdef f @@ -205,9 +202,8 @@ cdef class Riemann_Map: def __init__(self, fs, fprimes, COMPLEX_T a, int N=500, int ncorners=4, opp=False, exterior = False): - """ - Initializes the ``Riemann_Map`` class. See the class :class:`Riemann_Map` + Initialize the ``Riemann_Map`` class. See the class :class:`Riemann_Map` for full documentation on the input of this initialization method. TESTS:: @@ -388,12 +384,12 @@ cdef class Riemann_Map: The following inputs may be passed in as named parameters: - - ``boundary`` -- integer (default: ``-1``) if < 0, + - ``boundary`` -- integer (default: `-1`); if < 0, :meth:`get_theta_points` will return the points for all boundaries. If >= 0, :meth:`get_theta_points` will return only the points for the boundary specified. - - ``absolute_value`` -- boolean (default: ``False``) if ``True``, will + - ``absolute_value`` -- boolean (default: ``False``); if ``True``, will return the absolute value of the (complex valued) Szego kernel instead of the kernel itself. Useful for plotting. @@ -468,7 +464,7 @@ cdef class Riemann_Map: The following input must all be passed in as named parameters: - - ``boundary`` -- integer (default: ``-1``) if < 0, + - ``boundary`` -- integer (default: `-1`); if < 0, ``get_theta_points()`` will return the points for all boundaries. If >= 0, ``get_theta_points()`` will return only the points for the boundary specified. @@ -583,8 +579,8 @@ cdef class Riemann_Map: INPUT: - - ``pt`` -- A complex number representing the point to be - inverse mapped. + - ``pt`` -- a complex number representing the point to be + inverse mapped OUTPUT: @@ -670,12 +666,10 @@ cdef class Riemann_Map: INPUT: - - ``pt`` -- A complex number (usually with absolute value <= 1) - representing the point to be inverse mapped. + - ``pt`` -- a complex number (usually with absolute value <= 1) + representing the point to be inverse mapped - OUTPUT: - - The point on the region that Riemann maps to the input point. + OUTPUT: the point on the region that Riemann maps to the input point EXAMPLES: @@ -721,17 +715,17 @@ cdef class Riemann_Map: The following inputs may be passed in as named parameters: - - ``plotjoined`` -- boolean (default: ``True``) If ``False``, + - ``plotjoined`` -- boolean (default: ``True``); if ``False``, discrete points will be drawn; otherwise they will be connected by lines. In this case, if ``plotjoined=False``, the points shown will be the original collocation points used to generate the Riemann map. - ``rgbcolor`` -- float array (default: ``[0,0,0]``) the - red-green-blue color of the boundary. + red-green-blue color of the boundary - ``thickness`` -- positive float (default: ``1``) the thickness of - the lines or points in the boundary. + the lines or points in the boundary EXAMPLES: @@ -775,12 +769,12 @@ cdef class Riemann_Map: INPUT: - - ``plot_range`` -- a tuple of the form ``[xmin, xmax, ymin, ymax]``. - If the value is ``[]``, the default plotting window of the map will - be used. + - ``plot_range`` -- tuple of the form ``[xmin, xmax, ymin, ymax]``; + if the value is ``[]``, the default plotting window of the map will + be used - - ``x_points`` -- int, the size of the grid in the x direction - The number of points in the y_direction is scaled accordingly + - ``x_points`` -- integer; the size of the grid in the x direction; + the number of points in the y direction is scaled accordingly OUTPUT: @@ -856,42 +850,43 @@ cdef class Riemann_Map: The following inputs may be passed in as named parameters: - - ``spokes`` -- integer (default: ``16``) the number of equally - spaced radial lines to plot. + - ``spokes`` -- integer (default: 16); the number of equally + spaced radial lines to plot - - ``circles`` -- integer (default: ``4``) the number of equally - spaced circles about the center to plot. + - ``circles`` -- integer (default: 4); the number of equally + spaced circles about the center to plot - - ``pts`` -- integer (default: ``32``) the number of points to + - ``pts`` -- integer (default: 32); the number of points to plot. Each radial line is made by ``1*pts`` points, each circle has ``2*pts`` points. Note that high values may cause erratic behavior of the radial lines near the boundaries. - only for simply connected domains - - ``linescale`` -- float between 0 and 1. Shrinks the radial lines - away from the boundary to reduce erratic behavior. + - ``linescale`` -- float between 0 and 1; shrinks the radial lines + away from the boundary to reduce erratic behavior - only for simply connected domains - - ``rgbcolor`` -- float array (default: ``[0,0,0]``) the - red-green-blue color of the spiderweb. + - ``rgbcolor`` -- float array (default: ``[0,0,0]``); the + red-green-blue color of the spiderweb - - ``thickness`` -- positive float (default: ``1``) the thickness of - the lines or points in the spiderweb. + - ``thickness`` -- positive float (default: 1); the thickness of + the lines or points in the spiderweb - - ``plotjoined`` -- boolean (default: ``True``) If ``False``, + - ``plotjoined`` -- boolean (default: ``True``); if ``False``, discrete points will be drawn; otherwise they will be connected - by lines. + by lines - only for simply connected domains - - ``withcolor`` -- boolean (default: ``False``) If ``True``, - The spiderweb will be overlaid on the basic color plot. + - ``withcolor`` -- boolean (default: ``False``); if ``True``, + the spiderweb will be overlaid on the basic color plot - - ``plot_points`` -- integer (default: ``200``) the size of the grid in the x direction - The number of points in the y_direction is scaled accordingly. - Note that very large values can cause this function to run slowly. + - ``plot_points`` -- integer (default: 200); the size of the grid + in the x direction. The number of points in the y_direction is scaled + accordingly. Note that very large values can cause this function to + run slowly. - only for multiply connected domains - - ``min_mag`` -- float (default: ``0.001``) The magnitude cutoff + - ``min_mag`` -- float (default: 0.001); the magnitude cutoff below which spiderweb points are not drawn. This only applies to multiply connected domains and is designed to prevent "fuzz" at the edge of the domain. Some complicated multiply @@ -1021,12 +1016,11 @@ cdef class Riemann_Map: ``(xmin, xmax, ymin, ymax)``. Declare if you do not want the plot to use the default range for the figure. - - ``plot_points`` -- integer (default: ``100``), number of points to + - ``plot_points`` -- integer (default: 100); number of points to plot in the x direction. Points in the y direction are scaled accordingly. Note that very large values can cause this function to run slowly. - EXAMPLES: Given a Riemann map m, general usage:: @@ -1075,10 +1069,10 @@ cdef comp_pt(clist, loop=True): INPUT: - - ``clist`` -- a list of complex numbers. + - ``clist`` -- list of complex numbers - - ``loop`` -- boolean (default: ``True``) controls whether or not the - first point will be added as the last to plot a closed circle. + - ``loop`` -- boolean (default: ``True``); controls whether or not the + first point will be added as the last to plot a closed circle EXAMPLES: @@ -1098,7 +1092,7 @@ cdef comp_pt(clist, loop=True): cpdef get_derivatives(np.ndarray[COMPLEX_T, ndim=2] z_values, FLOAT_T xstep, FLOAT_T ystep): """ - Computes the r*e^(I*theta) form of derivatives from the grid of points. The + Compute the r*e^(I*theta) form of derivatives from the grid of points. The derivatives are computed using quick-and-dirty taylor expansion and assuming analyticity. As such ``get_derivatives`` is primarily intended to be used for comparisons in ``plot_spiderweb`` and not for @@ -1106,8 +1100,8 @@ cpdef get_derivatives(np.ndarray[COMPLEX_T, ndim=2] z_values, FLOAT_T xstep, INPUT: - - ``z_values`` -- The values for a complex function evaluated on a grid - in the complex plane, usually from ``compute_on_grid``. + - ``z_values`` -- the values for a complex function evaluated on a grid + in the complex plane, usually from ``compute_on_grid`` - ``xstep`` -- float, the spacing of the grid points in the real direction @@ -1154,34 +1148,34 @@ cpdef complex_to_spiderweb(np.ndarray[COMPLEX_T, ndim = 2] z_values, np.ndarray[FLOAT_T, ndim = 2] dr, np.ndarray[FLOAT_T, ndim = 2] dtheta, spokes, circles, rgbcolor, thickness, withcolor, min_mag): """ - Converts a grid of complex numbers into a matrix containing rgb data + Convert a grid of complex numbers into a matrix containing rgb data for the Riemann spiderweb plot. INPUT: - - ``z_values`` -- A grid of complex numbers, as a list of lists. + - ``z_values`` -- a grid of complex numbers, as a list of lists - - ``dr`` -- grid of floats, the r derivative of ``z_values``. - Used to determine precision. + - ``dr`` -- grid of floats, the r derivative of ``z_values`` + Used to determine precision - - ``dtheta`` -- grid of floats, the theta derivative of ``z_values``. - Used to determine precision. + - ``dtheta`` -- grid of floats, the theta derivative of ``z_values`` + Used to determine precision - - ``spokes`` -- integer; the number of equally spaced radial lines to plot. + - ``spokes`` -- integer; the number of equally spaced radial lines to plot - ``circles`` -- integer; the number of equally spaced circles about the - center to plot. + center to plot - ``rgbcolor`` -- float array; the red-green-blue color of the - lines of the spiderweb. + lines of the spiderweb - ``thickness`` -- positive float; the thickness of the lines or points - in the spiderweb. + in the spiderweb - - ``withcolor`` -- boolean; If ``True`` the spiderweb will be overlaid - on the basic color plot. + - ``withcolor`` -- boolean; if ``True`` the spiderweb will be overlaid + on the basic color plot - - ``min_mag`` -- float; The magnitude cutoff below which spiderweb + - ``min_mag`` -- float; the magnitude cutoff below which spiderweb points are not drawn. This only applies to multiply connected domains and is designed to prevent "fuzz" at the edge of the domain. Some complicated multiply connected domains (particularly @@ -1277,7 +1271,7 @@ cpdef complex_to_rgb(np.ndarray[COMPLEX_T, ndim = 2] z_values): INPUT: - - ``z_values`` -- A Numpy array of complex numbers. + - ``z_values`` -- numpy array of complex numbers OUTPUT: @@ -1375,18 +1369,19 @@ cpdef complex_to_rgb(np.ndarray[COMPLEX_T, ndim = 2] z_values): return rgb cpdef analytic_boundary(FLOAT_T t, int n, FLOAT_T epsilon): - """ - Provides an exact (for n = infinity) Riemann boundary - correspondence for the ellipse with axes 1 + epsilon and 1 - epsilon. The - boundary is therefore given by e^(I*t)+epsilon*e^(-I*t). It is primarily - useful for testing the accuracy of the numerical :class:`Riemann_Map`. + r""" + Provides an exact (for `n = \infty`) Riemann boundary + correspondence for the ellipse with axes `1 + \epsilon` and `1 - \epsilon`. + The boundary is therefore given by `\exp(I t)+\epsilon\exp(-I t)`. It is + primarily useful for testing the accuracy of the numerical + :class:`Riemann_Map`. INPUT: - - ``t`` -- The boundary parameter, from 0 to 2*pi + - ``t`` -- the boundary parameter, from `0` to `2 \pi` - - ``n`` -- integer; the number of terms to include. - 10 is fairly accurate, 20 is very accurate. + - ``n`` -- integer; the number of terms to include + (10 is fairly accurate, 20 is very accurate) - ``epsilon`` -- float; the skew of the ellipse (0 is circular) @@ -1429,16 +1424,16 @@ cpdef cauchy_kernel(t, args): INPUT: - - ``t`` -- The boundary parameter, meant to be integrated over + - ``t`` -- the boundary parameter, meant to be integrated over - - ``args`` -- a tuple containing: + - ``args`` -- tuple containing: - ``epsilon`` -- float; the skew of the ellipse (0 is circular) - - ``z`` -- complex; the point to be mapped. + - ``z`` -- complex; the point to be mapped - - ``n`` -- integer; the number of terms to include. - 10 is fairly accurate, 20 is very accurate. + - ``n`` -- integer; the number of terms to include + (10 is fairly accurate, 20 is very accurate) - ``part`` -- will return the real ('r'), imaginary ('i') or complex ('c') value of the kernel @@ -1477,10 +1472,10 @@ cpdef analytic_interior(COMPLEX_T z, int n, FLOAT_T epsilon): INPUT: - - ``z`` -- complex; the point to be mapped. + - ``z`` -- complex; the point to be mapped - - ``n`` -- integer; the number of terms to include. - 10 is fairly accurate, 20 is very accurate. + - ``n`` -- integer; the number of terms to include + (10 is fairly accurate, 20 is very accurate) TESTS: diff --git a/src/sage/calculus/transforms/dft.py b/src/sage/calculus/transforms/dft.py index cd0c76bfc07..bccfbcb8017 100644 --- a/src/sage/calculus/transforms/dft.py +++ b/src/sage/calculus/transforms/dft.py @@ -93,11 +93,11 @@ class IndexedSequence(SageObject): INPUT: - - ``L`` -- A list + - ``L`` -- list - - ``index_object`` must be a Sage object with an ``__iter__`` method + - ``index_object`` -- must be a Sage object with an ``__iter__`` method containing the same number of elements as ``self``, which is a - list of elements taken from a field. + list of elements taken from a field """ def __init__(self, L, index_object): r""" @@ -203,7 +203,7 @@ def index_object(self): def _repr_(self): """ - Implements print method. + Implement print method. EXAMPLES:: @@ -474,12 +474,10 @@ def convolution(self, other): INPUT: - - ``other`` -- a collection of elements of a ring with + - ``other`` -- a collection of elements of a ring with index set a finite abelian group (under `+`) - OUTPUT: - - The Dirichlet convolution of ``self`` and ``other``. + OUTPUT: the Dirichlet convolution of ``self`` and ``other`` EXAMPLES:: @@ -533,11 +531,9 @@ def convolution_periodic(self, other): INPUT: - - ``other`` -- a sequence of elements of `\CC`, `\RR` or `\GF{q}` - - OUTPUT: + - ``other`` -- a sequence of elements of `\CC`, `\RR` or `\GF{q}` - The Dirichlet convolution of ``self`` and ``other``. + OUTPUT: the Dirichlet convolution of ``self`` and ``other`` EXAMPLES:: @@ -578,7 +574,7 @@ def convolution_periodic(self, other): def __mul__(self, other): """ - Implements scalar multiplication (on the right). + Implement scalar multiplication (on the right). EXAMPLES:: @@ -598,7 +594,7 @@ def __mul__(self, other): def __eq__(self, other): """ - Implements boolean equals. + Implement boolean equals. EXAMPLES:: @@ -668,7 +664,7 @@ def fft(self): def ifft(self): """ - Implements the gsl ``FastFourierTransform.inverse`` in + Implement the gsl ``FastFourierTransform.inverse`` in :mod:`~sage.calculus.transforms.fft`. If the number of sample points in the input is a power of 2 @@ -703,7 +699,7 @@ def ifft(self): a.inverse_transform() return IndexedSequence([a[j][0] + I * a[j][1] for j in J], J) - def dwt(self, other="haar", wavelet_k=2): + def dwt(self, other='haar', wavelet_k=2): r""" Wraps the gsl ``WaveletTransform.forward`` in :mod:`~sage.calculus.transforms.dwt` (written by Joshua Kantor). Assumes the length of the sample is a @@ -720,9 +716,9 @@ def dwt(self, other="haar", wavelet_k=2): * ``'bspline'`` * ``'bspline_centered'`` - - ``wavelet_k`` -- For daubechies wavelets, ``wavelet_k`` specifies a - daubechie wavelet with `k/2` vanishing moments. - `k = 4,6,...,20` for `k` even are the only ones implemented. + - ``wavelet_k`` -- for daubechies wavelets, ``wavelet_k`` specifies a + daubechie wavelet with `k/2` vanishing moments; + `k = 4,6,...,20` for `k` even are the only ones implemented For Haar wavelets, ``wavelet_k`` must be 2. @@ -767,9 +763,9 @@ def dwt(self, other="haar", wavelet_k=2): a.forward_transform() return IndexedSequence([RR(a[j]) for j in J], J) - def idwt(self, other="haar", wavelet_k=2): + def idwt(self, other='haar', wavelet_k=2): r""" - Implements the gsl ``WaveletTransform.backward()`` in + Implement the gsl ``WaveletTransform.backward()`` in :mod:`~sage.calculus.transforms.dwt`. Assumes the length of the sample is a power of 2. Uses the @@ -777,18 +773,18 @@ def idwt(self, other="haar", wavelet_k=2): INPUT: - - ``other`` -- Must be one of the following: + - ``other`` -- must be one of the following: - * ``"haar"`` - * ``"daubechies"`` - * ``"daubechies_centered"`` - * ``"haar_centered"`` - * ``"bspline"`` - * ``"bspline_centered"`` + * ``'haar'`` + * ``'daubechies'`` + * ``'daubechies_centered'`` + * ``'haar_centered'`` + * ``'bspline'`` + * ``'bspline_centered'`` - - ``wavelet_k`` -- For daubechies wavelets, ``wavelet_k`` specifies a - daubechie wavelet with `k/2` vanishing moments. - `k = 4,6,...,20` for `k` even are the only ones implemented. + - ``wavelet_k`` -- for daubechies wavelets, ``wavelet_k`` specifies a + daubechie wavelet with `k/2` vanishing moments; + `k = 4,6,...,20` for `k` even are the only ones implemented For Haar wavelets, ``wavelet_k`` must be 2. diff --git a/src/sage/calculus/transforms/dwt.pyx b/src/sage/calculus/transforms/dwt.pyx index c88cd12d17f..fdb68153a8b 100644 --- a/src/sage/calculus/transforms/dwt.pyx +++ b/src/sage/calculus/transforms/dwt.pyx @@ -28,7 +28,7 @@ def WaveletTransform(n, wavelet_type, wavelet_k): INPUT: - - ``n`` -- a power of 2 + - ``n`` -- a power of 2 - ``T`` -- the data in the GSLDoubleArray must be real - ``wavelet_type`` -- the name of the type of wavelet, valid choices are: diff --git a/src/sage/calculus/transforms/fft.pyx b/src/sage/calculus/transforms/fft.pyx index ca7fd73cb64..1f190f00685 100644 --- a/src/sage/calculus/transforms/fft.pyx +++ b/src/sage/calculus/transforms/fft.pyx @@ -32,8 +32,8 @@ def FastFourierTransform(size, base_ring=None): INPUT: - - ``size`` -- The size of the array - - ``base_ring`` -- Unused (2013-03) + - ``size`` -- the size of the array + - ``base_ring`` -- unused (2013-03) EXAMPLES: @@ -72,7 +72,6 @@ def FastFourierTransform(size, base_ring=None): sage: a.plot().show(ymin=0) # needs sage.plot sage: a.forward_transform() sage: a.plot().show() # needs sage.plot - """ return FastFourierTransform_complex(int(size)) @@ -95,8 +94,8 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): INPUT: - - ``n`` -- An integer, the size of the array - - ``stride`` -- The stride to be applied when manipulating the array. + - ``n`` -- integer, the size of the array + - ``stride`` -- the stride to be applied when manipulating the array EXAMPLES:: @@ -126,14 +125,13 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): """ Return the size of the array. - OUTPUT: The size of the array. + OUTPUT: the size of the array EXAMPLES:: sage: a = FastFourierTransform(48) sage: len(a) 48 - """ return self.n @@ -146,8 +144,8 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): INPUT: - - ``i`` -- An integer, the index. - - ``xy`` -- An object to store as `i`-th element of the array ``self[i]``. + - ``i`` -- integer; the index + - ``xy`` -- an object to store as `i`-th element of the array ``self[i]`` EXAMPLES:: @@ -177,15 +175,13 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): def __getitem__(self, i): """ - Gets the `i`-th element of the array. + Get the `i`-th element of the array. INPUT: - - ``i``: An integer. - - OUTPUT: + - ``i`` -- integer - - The `i`-th element of the array ``self[i]``. + OUTPUT: the `i`-th element of the array ``self[i]`` EXAMPLES:: @@ -195,7 +191,6 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): sage: a[0] = 1 sage: a[0] == (1,0) True - """ if isinstance(i, slice): start, stop, step = i.indices(self.n) @@ -220,7 +215,6 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): sage: for i in range(4): a[i] = i sage: a [(0.0, 0.0), (1.0, 0.0), (2.0, 0.0), (3.0, 0.0)] - """ return str(list(self)) @@ -230,13 +224,11 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): INPUT: - - ``xmin`` -- The lower bound of the slice to plot. - - ``xmax`` -- The upper bound of the slice to plot. - - ``**args`` -- passed on to the line plotting function. + - ``xmin`` -- the lower bound of the slice to plot + - ``xmax`` -- the upper bound of the slice to plot + - ``**args`` -- passed on to the line plotting function - OUTPUT: - - - A plot of the array interpreting each element as polar coordinates. + OUTPUT: a plot of the array interpreting each element as polar coordinates This method should not be called directly. See :meth:`plot` for the details. @@ -245,7 +237,6 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): sage: a = FastFourierTransform(4) sage: a._plot_polar(0,2) # needs sage.plot sage.symbolic Graphics object consisting of 2 graphics primitives - """ from sage.plot.point import point from sage.symbolic.constants import pi, I @@ -270,13 +261,11 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): INPUT: - - ``xmin`` -- The lower bound of the slice to plot. - - ``xmax`` -- The upper bound of the slice to plot. - - ``**args`` -- passed on to the line plotting function. - - OUTPUT: + - ``xmin`` -- the lower bound of the slice to plot + - ``xmax`` -- the upper bound of the slice to plot + - ``**args`` -- passed on to the line plotting function - - A plot of the array. + OUTPUT: a plot of the array This method should not be called directly. See :meth:`plot` for the details. @@ -302,20 +291,18 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): """ Plot a slice of the array. - - ``style`` -- Style of the plot, options are ``"rect"`` or ``"polar"`` + - ``style`` -- style of the plot, options are ``'rect'`` or ``'polar'`` - - ``"rect"`` -- height represents real part, color represents - imaginary part. - - ``"polar"`` -- height represents absolute value, color - represents argument. + - ``'rect'`` -- height represents real part, color represents + imaginary part + - ``'polar'`` -- height represents absolute value, color + represents argument - - ``xmin`` -- The lower bound of the slice to plot. 0 by default. - - ``xmax`` -- The upper bound of the slice to plot. ``len(self)`` by default. - - ``**args`` -- passed on to the line plotting function. + - ``xmin`` -- the lower bound of the slice to plot; 0 by default + - ``xmax`` -- the upper bound of the slice to plot; ``len(self)`` by default + - ``**args`` -- passed on to the line plotting function - OUTPUT: - - - A plot of the array. + OUTPUT: a plot of the array EXAMPLES:: @@ -336,7 +323,6 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): sage: a.inverse_transform() sage: a.plot() + b.plot() Graphics object consisting of 250 graphics primitives - """ if xmin is None: xmin = 0 @@ -358,9 +344,7 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): Compute the in-place forward Fourier transform of this data using the Cooley-Tukey algorithm. - OUTPUT: - - - None, the transformation is done in-place. + OUTPUT: none, the transformation is done in-place If the number of sample points in the input is a power of 2 then the gsl function ``gsl_fft_complex_radix2_forward`` is automatically called. @@ -373,7 +357,6 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): sage: a.forward_transform() sage: a #abs tol 1e-2 [(6.0, 0.0), (-2.0, 2.0), (-2.0, 0.0), (-2.0, -2.0)] - """ cdef gsl_fft_complex_wavetable * wt cdef gsl_fft_complex_workspace * mem @@ -393,9 +376,7 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): Compute the in-place inverse Fourier transform of this data using the Cooley-Tukey algorithm. - OUTPUT: - - - None, the transformation is done in-place. + OUTPUT: none, the transformation is done in-place If the number of sample points in the input is a power of 2 then the function ``gsl_fft_complex_radix2_inverse`` is automatically called. @@ -427,7 +408,6 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): sage: a.inverse_transform() sage: a.plot() + b.plot() # needs sage.plot Graphics object consisting of 256 graphics primitives - """ cdef gsl_fft_complex_wavetable * wt cdef gsl_fft_complex_workspace * mem @@ -447,9 +427,7 @@ cdef class FastFourierTransform_complex(FastFourierTransform_base): Compute the in-place backwards Fourier transform of this data using the Cooley-Tukey algorithm. - OUTPUT: - - - None, the transformation is done in-place. + OUTPUT: none, the transformation is done in-place This is the same as :meth:`inverse_transform` but lacks normalization so that ``f.forward_transform().backward_transform() == n*f``. Where diff --git a/src/sage/calculus/var.pyx b/src/sage/calculus/var.pyx index 97170624389..4967bb9bd9a 100644 --- a/src/sage/calculus/var.pyx +++ b/src/sage/calculus/var.pyx @@ -13,7 +13,7 @@ def var(*args, **kwds): INPUT: - - ``args`` -- A single string ``var('x y')``, a list of strings + - ``args`` -- a single string ``var('x y')``, a list of strings ``var(['x','y'])``, or multiple strings ``var('x', 'y')``. A single string can be either a single variable name, or a space or comma separated list of variable names. In a list or tuple of @@ -22,7 +22,7 @@ def var(*args, **kwds): before or after variable names are ignored. - ``kwds`` -- keyword arguments can be given to specify domain and - custom latex_name for variables. See EXAMPLES for usage. + custom latex_name for variables; see EXAMPLES for usage .. NOTE:: @@ -36,7 +36,7 @@ def var(*args, **kwds): If a single symbolic variable was created, the variable itself. Otherwise, a tuple of symbolic variables. The variable names are checked to be valid Python identifiers and a - :class:`ValueError` is raised otherwise. + :exc:`ValueError` is raised otherwise. EXAMPLES: @@ -77,12 +77,12 @@ def var(*args, **kwds): Custom latex expression can be assigned to variable:: - sage: x = var('sui', latex_name="s_{u,i}"); x._latex_() + sage: x = var('sui', latex_name='s_{u,i}'); x._latex_() '{s_{u,i}}' In notebook, we can also colorize latex expression:: - sage: x = var('sui', latex_name="\\color{red}{s_{u,i}}"); x._latex_() + sage: x = var('sui', latex_name='\\color{red}{s_{u,i}}'); x._latex_() '{\\color{red}{s_{u,i}}}' We can substitute a new variable name for n:: @@ -139,11 +139,11 @@ def function(s, **kwds): - ``nargs=0`` -- number of arguments the function accepts, defaults to variable number of arguments, or 0 - ``latex_name`` -- name used when printing in latex mode - - ``conversions`` -- a dictionary specifying names of this function in + - ``conversions`` -- dictionary specifying names of this function in other systems, this is used by the interfaces internally during conversion - ``eval_func`` -- method used for automatic evaluation - ``evalf_func`` -- method used for numeric evaluation - - ``evalf_params_first`` -- bool to indicate if parameters should be + - ``evalf_params_first`` -- boolean to indicate if parameters should be evaluated numerically before calling the custom evalf function - ``conjugate_func`` -- method used for complex conjugation - ``real_part_func`` -- method used when taking real parts @@ -215,7 +215,7 @@ def function(s, **kwds): Custom typesetting of symbolic functions in LaTeX, either using latex_name keyword:: - sage: function('riemann', latex_name="\\mathcal{R}") + sage: function('riemann', latex_name='\\mathcal{R}') riemann sage: latex(riemann(x)) \mathcal{R}\left(x\right) diff --git a/src/sage/categories/action.pyx b/src/sage/categories/action.pyx index 0f49a368f3e..73be8d625bf 100644 --- a/src/sage/categories/action.pyx +++ b/src/sage/categories/action.pyx @@ -85,7 +85,7 @@ cdef class Action(Functor): - ``S`` -- a parent or Python type - - ``is_left`` -- (boolean, default: ``True``) whether elements of + - ``is_left`` -- boolean (default: ``True``); whether elements of ``G`` are on the left - ``op`` -- (default: ``None``) operation. This is not used by @@ -200,9 +200,9 @@ cdef class Action(Functor): INPUT: - - ``g`` -- an object with parent ``self.G``. + - ``g`` -- an object with parent ``self.G`` - - ``x`` -- an object with parent ``self.US()``. + - ``x`` -- an object with parent ``self.US()`` .. WARNING:: diff --git a/src/sage/categories/additive_magmas.py b/src/sage/categories/additive_magmas.py index 00f7f80cd9b..691486e03d4 100644 --- a/src/sage/categories/additive_magmas.py +++ b/src/sage/categories/additive_magmas.py @@ -60,7 +60,6 @@ class AdditiveMagmas(Category_singleton): sage: C = AdditiveMagmas() sage: TestSuite(C).run() - """ def super_categories(self): @@ -176,7 +175,7 @@ def summation(self, x, y): INPUT: - - ``x``, ``y`` -- elements of this additive magma + - ``x``, ``y`` -- elements of this additive magma EXAMPLES:: @@ -401,9 +400,7 @@ def _add_(self, right): - ``self``, ``right`` -- two elements with the same parent - OUTPUT: - - - an element of the same parent + OUTPUT: an element of the same parent EXAMPLES:: @@ -425,9 +422,7 @@ def _add_parent(self, other): - ``other`` -- an element of the parent of ``self`` - OUTPUT: - - - an element of the parent of ``self`` + OUTPUT: an element of the parent of ``self`` EXAMPLES:: @@ -656,7 +651,7 @@ class ParentMethods: def _test_zero(self, **options): r""" - Test that ``self.zero()`` is an element of self and + Test that ``self.zero()`` is an element of ``self`` and is neutral for the addition. INPUT: @@ -778,7 +773,7 @@ def __bool__(self): All parents in the category ``CommutativeAdditiveMonoids()`` should implement this method. - .. note:: This is currently not useful because this method is + .. NOTE:: This is currently not useful because this method is overridden by ``Element``. TESTS:: @@ -955,7 +950,7 @@ def extra_super_categories(self): class ParentMethods: def zero(self): r""" - Returns the zero of this group + Return the zero of this group. EXAMPLES:: diff --git a/src/sage/categories/additive_monoids.py b/src/sage/categories/additive_monoids.py index 3d76c87113b..70a195f582e 100644 --- a/src/sage/categories/additive_monoids.py +++ b/src/sage/categories/additive_monoids.py @@ -56,7 +56,7 @@ def sum(self, args): INPUT: - - ``args`` -- a list (or iterable) of elements of ``self`` + - ``args`` -- list (or iterable) of elements of ``self`` EXAMPLES:: diff --git a/src/sage/categories/affine_weyl_groups.py b/src/sage/categories/affine_weyl_groups.py index 9a26f8c5590..71dfcd2350a 100644 --- a/src/sage/categories/affine_weyl_groups.py +++ b/src/sage/categories/affine_weyl_groups.py @@ -17,7 +17,7 @@ class AffineWeylGroups(Category_singleton): """ - The category of affine Weyl groups + The category of affine Weyl groups. .. TODO:: add a description of this category @@ -125,9 +125,9 @@ def select_length(pair): def succ(pair): u, length = pair - for i in u.descents(positive=True, side="left"): + for i in u.descents(positive=True, side='left'): u1 = u.apply_simple_reflection(i, "left") - if (length < k and i == u1.first_descent(side="left") and + if (length < k and i == u1.first_descent(side='left') and u1.is_affine_grassmannian()): yield (u1, length + 1) return @@ -220,9 +220,7 @@ def affine_grassmannian_to_partition(self): - ``self`` is affine Grassmannian element of the affine Weyl group of type `A_k^{(1)}` (i.e. all reduced words end in 0) - OUTPUT: - - - `k`-bounded partition + OUTPUT: `k`-bounded partition .. SEEALSO:: :meth:`affine_grassmannian_to_core` diff --git a/src/sage/categories/algebra_functor.py b/src/sage/categories/algebra_functor.py index ec3c2ba8616..0d6cb19b0e1 100644 --- a/src/sage/categories/algebra_functor.py +++ b/src/sage/categories/algebra_functor.py @@ -592,9 +592,7 @@ def _apply_functor(self, base_ring): - ``base_ring`` -- the base ring of the group algebra - OUTPUT: - - A group algebra. + OUTPUT: a group algebra EXAMPLES:: @@ -615,9 +613,7 @@ def _apply_functor_to_morphism(self, f): - ``f`` -- a morphism of rings - OUTPUT: - - A morphism of group algebras. + OUTPUT: a morphism of group algebras EXAMPLES:: diff --git a/src/sage/categories/algebra_ideals.py b/src/sage/categories/algebra_ideals.py index c973743adc1..22719fb9974 100644 --- a/src/sage/categories/algebra_ideals.py +++ b/src/sage/categories/algebra_ideals.py @@ -85,7 +85,6 @@ def super_categories(self): sage: C = AlgebraIdeals(FreeAlgebra(QQ, 2, 'a,b')) # needs sage.combinat sage.modules sage: C.super_categories() # needs sage.combinat sage.modules [] - """ R = self.algebra() try: diff --git a/src/sage/categories/algebra_modules.py b/src/sage/categories/algebra_modules.py index 8a84fa109d7..64a7ca3014a 100644 --- a/src/sage/categories/algebra_modules.py +++ b/src/sage/categories/algebra_modules.py @@ -32,7 +32,6 @@ class AlgebraModules(Category_module): the categories of left and right modules are isomorphic. Feedback and use cases for potential generalizations to the non commutative case are welcome. - """ def __init__(self, A): """ @@ -67,7 +66,7 @@ def __init__(self, A): @classmethod def an_instance(cls): """ - Returns an instance of this class + Return an instance of this class. EXAMPLES:: diff --git a/src/sage/categories/algebras.py b/src/sage/categories/algebras.py index 7dcf02467ff..3a2bf0f5c3e 100644 --- a/src/sage/categories/algebras.py +++ b/src/sage/categories/algebras.py @@ -62,7 +62,7 @@ class Algebras(CategoryWithAxiom_over_base_ring): # For backward compatibility? def __contains__(self, x): """ - Membership testing + Membership testing. EXAMPLES:: @@ -224,7 +224,7 @@ class ElementMethods: # TODO: move the content of AlgebraElement here or higher in the category hierarchy def _div_(self, y): """ - Division by invertible elements + Division by invertible elements. # TODO: move in Monoids @@ -273,7 +273,7 @@ def algebra_generators(self): class CartesianProducts(CartesianProductsCategory): """ - The category of algebras constructed as Cartesian products of algebras + The category of algebras constructed as Cartesian products of algebras. This construction gives the direct product of algebras. See discussion on: @@ -327,7 +327,7 @@ class DualObjects(DualObjectsCategory): def extra_super_categories(self): r""" - Return the dual category + Return the dual category. EXAMPLES: diff --git a/src/sage/categories/algebras_with_basis.py b/src/sage/categories/algebras_with_basis.py index e0ebfb46184..73383dd329b 100644 --- a/src/sage/categories/algebras_with_basis.py +++ b/src/sage/categories/algebras_with_basis.py @@ -309,7 +309,7 @@ class ParentMethods: @cached_method def one_basis(self): """ - Returns the index of the one of this tensor product of + Return the index of the one of this tensor product of algebras, as per ``AlgebrasWithBasis.ParentMethods.one_basis`` It is the tuple whose operands are the indices of the @@ -372,6 +372,6 @@ def product_on_basis(self, t1, t2): class ElementMethods: """ - Implements operations on elements of tensor products of algebras with basis + Implement operations on elements of tensor products of algebras with basis """ pass diff --git a/src/sage/categories/bialgebras.py b/src/sage/categories/bialgebras.py index eeb89f4f61b..87b5bc5afe6 100644 --- a/src/sage/categories/bialgebras.py +++ b/src/sage/categories/bialgebras.py @@ -20,7 +20,7 @@ class Bialgebras(Category_over_base_ring): """ - The category of bialgebras + The category of bialgebras. EXAMPLES:: diff --git a/src/sage/categories/bialgebras_with_basis.py b/src/sage/categories/bialgebras_with_basis.py index 8b392b05984..10e829fd7fb 100644 --- a/src/sage/categories/bialgebras_with_basis.py +++ b/src/sage/categories/bialgebras_with_basis.py @@ -156,11 +156,9 @@ def convolution_power_of_id(self, n): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - the image of ``self`` under the convolution power `\mathrm{Id}^{*n}` + OUTPUT: the image of ``self`` under the convolution power `\mathrm{Id}^{*n}` .. NOTE:: @@ -249,9 +247,7 @@ def convolution_product(self, *maps): \ldots, f_n` on ``self.parent()``; or a single ``list`` or ``tuple`` of such maps - OUTPUT: - - - the convolution product of ``maps`` applied to ``self`` + OUTPUT: the convolution product of ``maps`` applied to ``self`` AUTHORS: diff --git a/src/sage/categories/bimodules.py b/src/sage/categories/bimodules.py index 5cf247fd6b5..eab8a1ad43d 100644 --- a/src/sage/categories/bimodules.py +++ b/src/sage/categories/bimodules.py @@ -24,7 +24,7 @@ class Bimodules(CategoryWithParameters): """ - The category of `(R,S)`-bimodules + The category of `(R,S)`-bimodules. For `R` and `S` rings, a `(R,S)`-bimodule `X` is a left `R`-module and right `S`-module such that the left and right actions commute: diff --git a/src/sage/categories/cartesian_product.py b/src/sage/categories/cartesian_product.py index 9e83183a287..2da692abc3c 100644 --- a/src/sage/categories/cartesian_product.py +++ b/src/sage/categories/cartesian_product.py @@ -105,7 +105,6 @@ class CartesianProductFunctor(CovariantFunctorialConstruction, MultivariateConst ` of ``Monoids(QQ)``. This nested class is itself a subclass of :class:`CartesianProductsCategory`. - """ _functor_name = "cartesian_product" _functor_category = "CartesianProducts" @@ -242,7 +241,6 @@ def _repr_object_names(self): sage: ModulesWithBasis(QQ).CartesianProducts() # indirect doctest Category of Cartesian products of vector spaces with basis over Rational Field - """ # This method is only required for the capital `C` return "Cartesian products of %s" % (self.base_category()._repr_object_names()) diff --git a/src/sage/categories/category.py b/src/sage/categories/category.py index 7ed37217378..b534f7be794 100644 --- a/src/sage/categories/category.py +++ b/src/sage/categories/category.py @@ -71,7 +71,7 @@ A parent ``P`` is in a category ``C`` if ``P.category()`` is a subcategory of ``C``. -.. note:: +.. NOTE:: Any object of a category should be an instance of :class:`~sage.structure.category_object.CategoryObject`. @@ -127,9 +127,9 @@ class Category(UniqueRepresentation, SageObject): r""" The base class for modeling mathematical categories, like for example: - - ``Groups()``: the category of groups - - ``EuclideanDomains()``: the category of euclidean rings - - ``VectorSpaces(QQ)``: the category of vector spaces over the field of + - ``Groups()`` -- the category of groups + - ``EuclideanDomains()`` -- the category of euclidean rings + - ``VectorSpaces(QQ)`` -- the category of vector spaces over the field of rationals See :mod:`sage.categories.primer` for an introduction to @@ -200,10 +200,10 @@ class inheritance from ``C.parent_class``. We define a hierarchy of four categories ``As()``, ``Bs()``, ``Cs()``, ``Ds()`` with a diamond inheritance. Think for example: - - ``As()``: the category of sets - - ``Bs()``: the category of additive groups - - ``Cs()``: the category of multiplicative monoids - - ``Ds()``: the category of rings + - ``As()`` -- the category of sets + - ``Bs()`` -- the category of additive groups + - ``Cs()`` -- the category of multiplicative monoids + - ``Ds()`` -- the category of rings :: @@ -491,7 +491,6 @@ def _label(self): sage: Rings()._label 'Rings' - """ t = str(self.__class__.__base__) t = t[t.rfind('.') + 1:] @@ -566,7 +565,7 @@ def an_instance(cls): def __call__(self, x, *args, **opts): """ Construct an object in this category from the data in ``x``, - or throw :class:`TypeError` or :class:`NotImplementedError`. + or throw :exc:`TypeError` or :exc:`NotImplementedError`. If ``x`` is readily in ``self`` it is returned unchanged. Categories wishing to extend this minimal behavior should @@ -584,7 +583,7 @@ def __call__(self, x, *args, **opts): def _call_(self, x): """ Construct an object in this category from the data in ``x``, - or throw :class:`NotImplementedError`. + or throw :exc:`NotImplementedError`. EXAMPLES:: @@ -608,7 +607,7 @@ def _repr_(self): def _latex_(self): r""" - Returns the latex representation of this category. + Return the latex representation of this category. EXAMPLES:: @@ -682,7 +681,7 @@ def _subcategory_hook_(self, category): def __contains__(self, x): """ - Membership testing + Membership testing. Returns whether ``x`` is an object in this category, that is if the category of ``x`` is a subcategory of ``self``. @@ -701,7 +700,7 @@ def __contains__(self, x): @staticmethod def __classcontains__(cls, x): """ - Membership testing, without arguments + Membership testing, without arguments. INPUT: @@ -785,7 +784,7 @@ def is_abelian(self): def category_graph(self): r""" - Returns the graph of all super categories of this category + Return the graph of all super categories of this category. EXAMPLES:: @@ -807,9 +806,7 @@ def super_categories(self): """ Return the *immediate* super categories of ``self``. - OUTPUT: - - - a duplicate-free list of categories. + OUTPUT: a duplicate-free list of categories Every category should implement this method. @@ -843,9 +840,9 @@ def _all_super_categories(self): .. SEEALSO:: :meth:`all_super_categories` - .. note:: this attribute is likely to eventually become a tuple. + .. NOTE:: this attribute is likely to eventually become a tuple. - .. note:: this sets :meth:`_super_categories_for_classes` as a side effect + .. NOTE:: this sets :meth:`_super_categories_for_classes` as a side effect EXAMPLES:: @@ -878,7 +875,7 @@ def _all_super_categories_proper(self): .. SEEALSO:: :meth:`all_super_categories` - .. note:: this attribute is likely to eventually become a tuple. + .. NOTE:: this attribute is likely to eventually become a tuple. EXAMPLES:: @@ -898,7 +895,7 @@ def _set_of_super_categories(self): """ The frozen set of all proper super categories of this category. - .. note:: this is used for speeding up category containment tests. + .. NOTE:: this is used for speeding up category containment tests. .. SEEALSO:: :meth:`all_super_categories` @@ -928,16 +925,16 @@ def _set_of_super_categories(self): def all_super_categories(self, proper=False): """ - Returns the list of all super categories of this category. + Return the list of all super categories of this category. INPUT: - - ``proper`` -- a boolean (default: ``False``); whether to exclude this category. + - ``proper`` -- boolean (default: ``False``); whether to exclude this category Since :issue:`11943`, the order of super categories is determined by Python's method resolution order C3 algorithm. - .. note:: + .. NOTE:: Whenever speed matters, the developers are advised to use instead the lazy attributes :meth:`_all_super_categories`, @@ -972,7 +969,6 @@ def all_super_categories(self, proper=False): True sage: Sets().all_super_categories(proper=True) is Sets()._all_super_categories_proper True - """ if proper: return self._all_super_categories_proper @@ -1374,9 +1370,9 @@ def full_super_categories(self): def _test_category_graph(self, **options): """ - Check that the category graph matches with Python's method resolution order + Check that the category graph matches with Python's method resolution order. - .. note:: + .. NOTE:: By :issue:`11943`, the list of categories returned by :meth:`all_super_categories` is supposed to match with the @@ -1393,7 +1389,6 @@ def _test_category_graph(self, **options): sage: C.element_class.mro() == [X.element_class for X in C._all_super_categories] + [object] True sage: TestSuite(C).run() # indirect doctest - """ tester = self._tester(**options) tester.assertEqual(self.parent_class.mro(), [C.parent_class for C in self._all_super_categories] + [object]) @@ -1401,7 +1396,7 @@ def _test_category_graph(self, **options): def _test_category(self, **options): r""" - Run generic tests on this category + Run generic tests on this category. .. SEEALSO:: :class:`TestSuite`. @@ -1470,15 +1465,15 @@ def _make_named_class(self, name, method_provider, cache=False, picklable=True): INPUT: - - ``name`` -- a string; the name of the class as an attribute of - ``self``. E.g. "parent_class" - - ``method_provider`` -- a string; the name of an attribute of + - ``name`` -- string; the name of the class as an attribute of + ``self`` (e.g. "parent_class") + - ``method_provider`` -- string; the name of an attribute of ``self`` that provides methods for the new class (in - addition to those coming from the super categories). - E.g. "ParentMethods" - - ``cache`` -- a boolean or ``ignore_reduction`` (default: ``False``) + addition to those coming from the super categories, + e.g. "ParentMethods") + - ``cache`` -- boolean or ``ignore_reduction`` (default: ``False``) (passed down to dynamic_class; for internal use only) - - ``picklable`` -- a boolean (default: ``True``) + - ``picklable`` -- boolean (default: ``True``) ASSUMPTION: @@ -1626,7 +1621,6 @@ def subcategory_class(self): sage: type(cls) - """ return self._make_named_class('subcategory_class', 'SubcategoryMethods', cache=False, picklable=False) @@ -1748,7 +1742,7 @@ def morphism_class(self): def required_methods(self): """ - Returns the methods that are required and optional for parents + Return the methods that are required and optional for parents in this category and their elements. EXAMPLES:: @@ -1763,7 +1757,7 @@ def required_methods(self): # Operations on the lattice of categories def is_subcategory(self, c): """ - Returns True if self is naturally embedded as a subcategory of c. + Return ``True`` if ``self`` is naturally embedded as a subcategory of `c`. EXAMPLES:: @@ -1818,11 +1812,9 @@ def or_subcategory(self, category=None, join=False): - ``category`` -- a sub category of ``self``, tuple/list thereof, or ``None`` - - ``join`` -- a boolean (default: ``False``) - - OUTPUT: + - ``join`` -- boolean (default: ``False``) - - a category + OUTPUT: a category EXAMPLES:: @@ -1884,7 +1876,7 @@ def _is_subclass(self, c): @cached_method def _meet_(self, other): """ - Returns the largest common subcategory of self and other: + Return the largest common subcategory of ``self`` and ``other``. EXAMPLES:: @@ -1917,7 +1909,7 @@ def _meet_(self, other): distributivity. For the meet computation, there may be several lowest common - sub categories of self and other, in which case, we need to + sub categories of ``self`` and ``other``, in which case, we need to take the join of them all. FIXME: @@ -1941,7 +1933,7 @@ def _meet_(self, other): @staticmethod def meet(categories): """ - Returns the meet of a list of categories + Return the meet of a list of categories. INPUT: @@ -1999,7 +1991,7 @@ def _with_axiom_as_tuple(self, axiom): INPUT: - - ``axiom`` -- a string, the name of an axiom + - ``axiom`` -- string, the name of an axiom This is a lazy version of :meth:`_with_axiom` which is used to avoid recursion loops during join calculations. @@ -2056,7 +2048,7 @@ def _with_axiom(self, axiom): INPUT: - - ``axiom`` -- a string, the name of an axiom + - ``axiom`` -- string, the name of an axiom EXAMPLES:: @@ -2087,7 +2079,7 @@ def _with_axioms(self, axioms): INPUT: - - ``axioms`` -- a list of strings, the names of the axioms + - ``axioms`` -- list of strings; the names of the axioms EXAMPLES:: @@ -2184,7 +2176,7 @@ def _without_axioms(self, named=False): INPUT: - - ``named`` -- a boolean (default: ``False``) + - ``named`` -- boolean (default: ``False``) .. TODO:: Improve this explanation. @@ -2217,11 +2209,9 @@ def _sort(categories): INPUT: - - ``categories`` -- a list (or iterable) of non-join categories + - ``categories`` -- list (or iterable) of non-join categories - OUTPUT: - - A sorted tuple of categories, possibly with repeats. + OUTPUT: a sorted tuple of categories, possibly with repeats .. NOTE:: @@ -2300,10 +2290,10 @@ def join(categories, as_list=False, ignore_axioms=(), axioms=()): INPUT: - - ``categories`` -- a list (or iterable) of categories - - ``as_list`` -- a boolean (default: ``False``); + - ``categories`` -- list (or iterable) of categories + - ``as_list`` -- boolean (default: ``False``); whether the result should be returned as a list - - ``axioms`` -- a tuple of strings; the names of some + - ``axioms`` -- tuple of strings; the names of some supplementary axioms .. SEEALSO:: :meth:`__and__` for a shortcut @@ -2510,7 +2500,7 @@ def category(self): def example(self, *args, **keywords): """ - Returns an object in this category. Most of the time, this is a parent. + Return an object in this category. Most of the time, this is a parent. This serves three purposes: @@ -2567,7 +2557,7 @@ def example(self, *args, **keywords): def is_Category(x): """ - Returns True if x is a category. + Return ``True`` if `x` is a category. EXAMPLES:: @@ -2628,7 +2618,7 @@ def category_graph(categories=None): INPUT: - - ``categories`` -- a list (or iterable) of categories + - ``categories`` -- list (or iterable) of categories If ``categories`` is specified, then the graph contains the mentioned categories together with all their super @@ -2716,13 +2706,13 @@ def _make_named_class(self, name, method_provider, cache=False, **options): INPUT: - - ``name`` -- a string; the name of the class as an attribute + - ``name`` -- string; the name of the class as an attribute of ``self`` - - ``method_provider`` -- a string; the name of an attribute of + - ``method_provider`` -- string; the name of an attribute of ``self`` that provides methods for the new class (in addition to what comes from the super categories) - ``**options`` -- other named options to pass down to - :meth:`Category._make_named_class`. + :meth:`Category._make_named_class` ASSUMPTION: @@ -2830,7 +2820,7 @@ def _make_named_class_key(self, name): INPUT: - - ``name`` -- a string; the name of the class as an attribute + - ``name`` -- string; the name of the class as an attribute of ``self`` .. SEEALSO:: @@ -2946,13 +2936,13 @@ class JoinCategory(CategoryWithParameters): def __init__(self, super_categories, **kwds): """ - Initializes this JoinCategory + Initialize this JoinCategory. INPUT: - - ``super_categories`` -- Categories to join. This category will + - ``super_categories`` -- categories to join; this category will consist of objects and morphisms that lie in all of these - categories. + categories - ``name`` -- ignored @@ -3006,7 +2996,7 @@ def _make_named_class_key(self, name): def super_categories(self): """ - Returns the immediate super categories, as per :meth:`Category.super_categories`. + Return the immediate super categories, as per :meth:`Category.super_categories`. EXAMPLES:: @@ -3032,13 +3022,13 @@ def additional_structure(self): def _subcategory_hook_(self, category): """ - Returns whether ``category`` is a subcategory of this join category + Return whether ``category`` is a subcategory of this join category. INPUT: - - ``category`` -- a category. + - ``category`` -- a category - .. note:: + .. NOTE:: ``category`` is a sub-category of this join category if and only if it is a sub-category of all super categories @@ -3143,7 +3133,7 @@ def _without_axioms(self, named=False): INPUT: - - ``named`` -- a boolean (default: ``False``) + - ``named`` -- boolean (default: ``False``) See :meth:`Category._without_axioms` for the description of the ``named`` parameter. @@ -3229,7 +3219,7 @@ def _repr_(self, as_join=False): INPUT: - - ``as_join`` -- a boolean (default: ``False``) + - ``as_join`` -- boolean (default: ``False``) EXAMPLES:: diff --git a/src/sage/categories/category_cy_helper.pyx b/src/sage/categories/category_cy_helper.pyx index 913a1c4d2b7..28600da136f 100644 --- a/src/sage/categories/category_cy_helper.pyx +++ b/src/sage/categories/category_cy_helper.pyx @@ -47,7 +47,7 @@ cpdef tuple _sort_uniq(categories): INPUT: - - ``categories`` -- a list (or iterable) of categories + - ``categories`` -- list (or iterable) of categories OUTPUT: a sorted tuple of mutually incomparable categories @@ -79,9 +79,9 @@ cpdef tuple _flatten_categories(categories, ClasscallMetaclass JoinCategory): INPUT: - - ``categories`` -- a list (or iterable) of categories + - ``categories`` -- list (or iterable) of categories - - ``JoinCategory`` -- A type such that instances of that type will be + - ``JoinCategory`` -- a type such that instances of that type will be replaced by its super categories. Usually, this type is :class:`JoinCategory`. @@ -122,12 +122,12 @@ cpdef tuple join_as_tuple(tuple categories, tuple axioms, tuple ignore_axioms): INPUT: - - ``categories`` -- tuple of categories to be joined, + - ``categories`` -- tuple of categories to be joined - ``axioms`` -- tuple of strings; the names of some - supplementary axioms. + supplementary axioms - ``ignore_axioms`` -- tuple of pairs ``(cat, axiom)``, such that ``axiom`` will not be applied to ``cat``, should ``cat`` - occur in the algorithm. + occur in the algorithm EXAMPLES:: @@ -294,7 +294,7 @@ cpdef tuple canonicalize_axioms(AxiomContainer all_axioms, axioms): - ``all_axioms`` -- all available axioms - - ``axioms`` -- a set (or iterable) of axioms + - ``axioms`` -- set (or iterable) of axioms .. NOTE:: diff --git a/src/sage/categories/category_singleton.pyx b/src/sage/categories/category_singleton.pyx index d907eedb9e8..ae38bdd2462 100644 --- a/src/sage/categories/category_singleton.pyx +++ b/src/sage/categories/category_singleton.pyx @@ -24,7 +24,7 @@ from cpython.type cimport PyType_IsSubtype cdef class Category_contains_method_by_parent_class: """ - Returns whether ``x`` is an object in this category. + Return whether ``x`` is an object in this category. More specifically, returns ``True`` if and only if ``x`` has a category which is a subcategory of this one. @@ -85,7 +85,7 @@ cdef class Category_contains_method_by_parent_class: class Category_singleton(Category): """ - A base class for implementing singleton category + A base class for implementing singleton category. A *singleton* category is a category whose class takes no parameters like ``Fields()`` or ``Rings()``. See also the @@ -218,9 +218,9 @@ class Category_singleton(Category): , , , + , , , - , , , , @@ -260,7 +260,6 @@ class Category_singleton(Category): False Oh well; it's not really relevant for those tests. - """ # That is just an optimized constant cached_method diff --git a/src/sage/categories/category_types.py b/src/sage/categories/category_types.py index ed4fdce2c62..de62a0109f0 100644 --- a/src/sage/categories/category_types.py +++ b/src/sage/categories/category_types.py @@ -62,7 +62,7 @@ def __init__(self, object): @classmethod def an_instance(cls): """ - Returns an instance of this class + Return an instance of this class. EXAMPLES:: @@ -147,7 +147,7 @@ def _latex_(self): ############################################################# class Category_over_base(CategoryWithParameters): r""" - A base class for categories over some base object + A base class for categories over some base object. INPUT: @@ -253,7 +253,7 @@ def _make_named_class_key(self, name): @classmethod def an_instance(cls): """ - Returns an instance of this class + Return an instance of this class. EXAMPLES:: @@ -386,7 +386,7 @@ def _subcategory_hook_(self, C): OUTPUT: A boolean if it is certain that ``C`` is (or is not) a - subcategory of self. :obj:`~sage.misc.unknown.Unknown` + subcategory of ``self``. :obj:`~sage.misc.unknown.Unknown` otherwise. EXAMPLES: @@ -514,7 +514,6 @@ def __contains__(self, x): sage: QQ['x'] in Algebras(Fields()) # todo: not implemented True - """ try: # The issubclass test handles extension types or when the @@ -616,8 +615,8 @@ def __contains__(self, x): """ if super().__contains__(x): return True - from sage.rings.ideal import is_Ideal - return is_Ideal(x) and x.ring() == self.ring() + from sage.rings.ideal import Ideal_generic + return isinstance(x, Ideal_generic) and x.ring() == self.ring() def __call__(self, v): """ diff --git a/src/sage/categories/category_with_axiom.py b/src/sage/categories/category_with_axiom.py index 19e3b2a9e91..d5bd98633a3 100644 --- a/src/sage/categories/category_with_axiom.py +++ b/src/sage/categories/category_with_axiom.py @@ -2219,7 +2219,7 @@ def _repr_object_names_static(category, axioms): INPUT: - ``base_category`` -- a category - - ``axioms`` -- a list or iterable of strings + - ``axioms`` -- list or iterable of strings EXAMPLES:: diff --git a/src/sage/categories/chain_complexes.py b/src/sage/categories/chain_complexes.py index 6e6448f3d38..562d21d0c49 100644 --- a/src/sage/categories/chain_complexes.py +++ b/src/sage/categories/chain_complexes.py @@ -37,7 +37,6 @@ class ChainComplexes(Category_module): TESTS:: sage: TestSuite(ChainComplexes(RationalField())).run() - """ def super_categories(self): @@ -46,7 +45,6 @@ def super_categories(self): sage: ChainComplexes(Integers(9)).super_categories() [Category of modules over Ring of integers modulo 9] - """ from sage.categories.fields import Fields from sage.categories.modules import Modules @@ -93,7 +91,6 @@ def homology(self, n=None): Free module generated by {} over Rational Field sage: C.homology(4) Free module generated by {[x^2], [y^2]} over Rational Field - """ @abstract_method @@ -118,7 +115,6 @@ def differential(self, *args, **kwargs): Defn: x --> 0 y --> 0 z --> x*y - """ @abstract_method(optional=True) @@ -146,7 +142,6 @@ def reduce_to_homology(self, x, n=None): - ``n`` -- (default: ``None``) degree of the homology; if none is provided, the direct sum homology will be used - EXAMPLES:: sage: # needs sage.symbolic @@ -211,7 +206,6 @@ class HomologyFunctor(Functor): Generic morphism: From: Z To: Z - """ def __init__(self, domain, n=None): r""" @@ -222,7 +216,6 @@ def __init__(self, domain, n=None): sage: H = HomologyFunctor(ChainComplexes(QQ), 1); H Functor from Category of chain complexes over Rational Field to Category of commutative additive groups - """ if not isinstance(domain, ChainComplexes): raise TypeError(f'{domain} must be a category of chain complexes') @@ -240,7 +233,6 @@ def _apply_functor(self, x): sage: H = HomologyFunctor(ChainComplexes(ZZ), 1) sage: H._apply_functor(C) # needs sage.modules Z x C3 - """ return x.homology(self._n) diff --git a/src/sage/categories/classical_crystals.py b/src/sage/categories/classical_crystals.py index 777eb16dddc..42dc02bdb2f 100644 --- a/src/sage/categories/classical_crystals.py +++ b/src/sage/categories/classical_crystals.py @@ -82,7 +82,7 @@ def super_categories(self): def example(self, n=3): """ - Returns an example of highest weight crystals, as per + Return an example of highest weight crystals, as per :meth:`Category.example`. EXAMPLES:: @@ -191,7 +191,7 @@ def demazure_character(self, w, f=None): def character(self, R=None): """ - Returns the character of this crystal. + Return the character of this crystal. INPUT: @@ -214,7 +214,7 @@ def character(self, R=None): One may specify an alternate :class:`WeylCharacterRing`:: - sage: R = WeylCharacterRing("A2", style="coroots") + sage: R = WeylCharacterRing("A2", style='coroots') sage: chiT = T.character(R); chiT A2(0,0) + 2*A2(1,1) + A2(0,3) + A2(3,0) + A2(2,2) sage: chiT in R @@ -223,12 +223,11 @@ def character(self, R=None): It should have the same Cartan type and use the same realization of the weight lattice as ``self``:: - sage: R = WeylCharacterRing("A3", style="coroots") + sage: R = WeylCharacterRing("A3", style='coroots') sage: T.character(R) Traceback (most recent call last): ... ValueError: Weyl character ring does not have the right Cartan type - """ from sage.combinat.root_system.weyl_characters import WeylCharacterRing if R is None: @@ -241,7 +240,7 @@ def character(self, R=None): def __iter__(self): r""" - Returns an iterator over the elements of this crystal. + Return an iterator over the elements of this crystal. This iterator uses little memory, storing only one element of the crystal at a time. For details on the complexity, see @@ -385,7 +384,7 @@ def __iter__(self): def _test_fast_iter(self, **options): r""" - Tests whether the elements returned by :meth:`.__iter__` + Test whether the elements returned by :meth:`.__iter__` and ``Crystal.list(self)`` are the same (the two algorithms are different). @@ -403,7 +402,7 @@ def _test_fast_iter(self, **options): def cardinality(self): r""" - Returns the number of elements of the crystal, using Weyl's + Return the number of elements of the crystal, using Weyl's dimension formula on each connected component. EXAMPLES:: diff --git a/src/sage/categories/coalgebras.py b/src/sage/categories/coalgebras.py index 7db6b72a6d4..c037ed0c6a1 100644 --- a/src/sage/categories/coalgebras.py +++ b/src/sage/categories/coalgebras.py @@ -27,7 +27,7 @@ class Coalgebras(Category_over_base_ring): """ - The category of coalgebras + The category of coalgebras. EXAMPLES:: diff --git a/src/sage/categories/coalgebras_with_basis.py b/src/sage/categories/coalgebras_with_basis.py index 7e111e727f6..33f532cfc95 100644 --- a/src/sage/categories/coalgebras_with_basis.py +++ b/src/sage/categories/coalgebras_with_basis.py @@ -92,7 +92,6 @@ def coproduct(self): (B[(1,2,3)], B[(1,2,3)] # B[(1,2,3)]) sage: b, A.coproduct(b) (B[(1,3)], B[(1,3)] # B[(1,3)]) - """ if self.coproduct_on_basis is not NotImplemented: # TODO: if self is a Hopf algebra, then one would want @@ -145,7 +144,6 @@ def counit(self): (B[(1,2,3)], 1) sage: b, A.counit(b) (B[(1,3)], 1) - """ if self.counit_on_basis is not NotImplemented: return self.module_morphism(self.counit_on_basis,codomain=self.base_ring()) diff --git a/src/sage/categories/coercion_methods.pyx b/src/sage/categories/coercion_methods.pyx index 0084b39d5eb..7640ea2aba5 100644 --- a/src/sage/categories/coercion_methods.pyx +++ b/src/sage/categories/coercion_methods.pyx @@ -24,9 +24,7 @@ def _mul_parent(self, other): - ``other`` -- an element of the parent of ``self`` - OUTPUT: - - - an element of the parent of ``self`` + OUTPUT: an element of the parent of ``self`` EXAMPLES:: diff --git a/src/sage/categories/commutative_rings.py b/src/sage/categories/commutative_rings.py index 0c00abea30d..6c47efacfe0 100644 --- a/src/sage/categories/commutative_rings.py +++ b/src/sage/categories/commutative_rings.py @@ -19,7 +19,7 @@ class CommutativeRings(CategoryWithAxiom): """ - The category of commutative rings + The category of commutative rings. commutative rings with unity, i.e. rings with commutative * and a multiplicative identity @@ -46,7 +46,6 @@ class CommutativeRings(CategoryWithAxiom): sage: GroupAlgebra(CyclicPermutationGroup(3), QQ) in CommutativeRings() # not implemented, needs sage.groups sage.modules True - """ class ParentMethods: def is_commutative(self) -> bool: @@ -149,14 +148,14 @@ def over(self, base=None, gen=None, gens=None, name=None, names=None): morphism - ``gen`` -- a generator of this extension (over its base) or ``None`` - (default: ``None``); + (default: ``None``) - - ``gens`` -- a list of generators of this extension (over its base) - or ``None`` (default: ``None``); + - ``gens`` -- list of generators of this extension (over its base) + or ``None`` (default: ``None``) - ``name`` -- a variable name or ``None`` (default: ``None``) - - ``names`` -- a list or a tuple of variable names or ``None`` + - ``names`` -- list or a tuple of variable names or ``None`` (default: ``None``) EXAMPLES: @@ -275,7 +274,7 @@ def frobenius_endomorphism(self, n=1): INPUT: - - ``n`` -- a nonnegative integer (default: 1) + - ``n`` -- nonnegative integer (default: 1) OUTPUT: @@ -391,7 +390,6 @@ def derivation_module(self, codomain=None, twist=None): .. SEEALSO:: :meth:`derivation` - """ from sage.rings.derivation import RingDerivationModule if codomain is None: @@ -461,7 +459,6 @@ def derivation(self, arg=None, twist=None): [x |--> x^2, y |--> y^2, z |--> z^2] - id sage: R.derivation(x, twist=theta) # needs sage.modules x*([x |--> x^2, y |--> y^2, z |--> z^2] - id) - """ if isinstance(arg, (list, tuple)): codomain = Sequence([self(0)] + list(arg)).universe() @@ -534,9 +531,7 @@ def cyclotomic_cosets(self, q, cosets=None): provided, the function only return the list of cosets that contain some element from ``cosets``. - OUTPUT: - - A list of lists. + OUTPUT: list of lists EXAMPLES:: diff --git a/src/sage/categories/complete_discrete_valuation.py b/src/sage/categories/complete_discrete_valuation.py index 7f291c43e37..40c1c51b77e 100644 --- a/src/sage/categories/complete_discrete_valuation.py +++ b/src/sage/categories/complete_discrete_valuation.py @@ -22,7 +22,7 @@ class CompleteDiscreteValuationRings(Category_singleton): """ - The category of complete discrete valuation rings + The category of complete discrete valuation rings. EXAMPLES:: @@ -138,7 +138,7 @@ def lift_to_precision(self, absprec=None): INPUT: - - ``absprec`` -- an integer or ``None`` (default: ``None``), the + - ``absprec`` -- integer or ``None`` (default: ``None``); the absolute precision of the result. If ``None``, lifts to the maximum precision allowed. @@ -168,13 +168,12 @@ def lift_to_precision(self, absprec=None): 2 + 3*5 + O(5^8) sage: c.lift_to_precision().precision_relative() == R.precision_cap() # needs sage.rings.padics True - """ class CompleteDiscreteValuationFields(Category_singleton): """ - The category of complete discrete valuation fields + The category of complete discrete valuation fields. EXAMPLES:: diff --git a/src/sage/categories/complex_reflection_or_generalized_coxeter_groups.py b/src/sage/categories/complex_reflection_or_generalized_coxeter_groups.py index efa0ddbeccd..242a9144243 100644 --- a/src/sage/categories/complex_reflection_or_generalized_coxeter_groups.py +++ b/src/sage/categories/complex_reflection_or_generalized_coxeter_groups.py @@ -53,7 +53,7 @@ class ComplexReflectionOrGeneralizedCoxeterGroups(Category_singleton): - A collection of *reflections* which are the conjugates of all the non trivial powers of the simple reflections. - The usual notions of reduced words, length, irreducibility, etc + The usual notions of reduced words, length, irreducibility, etc., can be canonically defined from the above. The following methods must be implemented: @@ -560,7 +560,7 @@ def distinguished_reflection(self, i): INPUT: - - ``i`` -- an element of the index set of the distinguished reflections. + - ``i`` -- an element of the index set of the distinguished reflections .. SEEALSO:: @@ -650,7 +650,7 @@ def from_reduced_word(self, word, word_type='simple'): INPUT: - - ``word`` -- a list (or iterable) of elements of the + - ``word`` -- list (or iterable) of elements of the index set of ``self`` (resp. of the distinguished or of all reflections) - ``word_type`` -- (default: ``'simple'``): @@ -773,7 +773,7 @@ def irreducible_component_index_sets(self): [[i,j] for i,j in itertools.combinations(I,2) if s[i]*s[j] != s[j]*s[i] ]], - format="vertices_and_edges") + format='vertices_and_edges') return G.connected_components(sort=False) @abstract_method(optional=True) @@ -942,7 +942,7 @@ def apply_simple_reflection(self, i, side='right'): INPUT: - ``i`` -- an element of the index set - - ``side`` -- (default: ``"right"``) ``"left"`` or ``"right"`` + - ``side`` -- (default: ``'right'``) ``'left'`` or ``'right'`` This default implementation simply calls :meth:`apply_simple_reflection_left` or @@ -953,20 +953,20 @@ def apply_simple_reflection(self, i, side='right'): sage: W = CoxeterGroups().example() sage: w = W.an_element(); w (1, 2, 3, 0) - sage: w.apply_simple_reflection(0, side="left") + sage: w.apply_simple_reflection(0, side='left') (0, 2, 3, 1) - sage: w.apply_simple_reflection(1, side="left") + sage: w.apply_simple_reflection(1, side='left') (2, 1, 3, 0) - sage: w.apply_simple_reflection(2, side="left") + sage: w.apply_simple_reflection(2, side='left') (1, 3, 2, 0) - sage: w.apply_simple_reflection(0, side="right") + sage: w.apply_simple_reflection(0, side='right') (2, 1, 3, 0) - sage: w.apply_simple_reflection(1, side="right") + sage: w.apply_simple_reflection(1, side='right') (1, 3, 2, 0) - sage: w.apply_simple_reflection(2, side="right") + sage: w.apply_simple_reflection(2, side='right') (1, 2, 0, 3) - By default, ``side`` is ``"right"``:: + By default, ``side`` is ``'right'``:: sage: w.apply_simple_reflection(0) (2, 1, 3, 0) @@ -979,17 +979,17 @@ def apply_simple_reflection(self, i, side='right'): 5-colored permutations of size 3 sage: w = W.an_element(); w [[1, 0, 0], [3, 1, 2]] - sage: w.apply_simple_reflection(1, side="left") + sage: w.apply_simple_reflection(1, side='left') [[0, 1, 0], [1, 3, 2]] - sage: w.apply_simple_reflection(2, side="left") + sage: w.apply_simple_reflection(2, side='left') [[1, 0, 0], [3, 2, 1]] - sage: w.apply_simple_reflection(3, side="left") + sage: w.apply_simple_reflection(3, side='left') [[1, 0, 1], [3, 1, 2]] - sage: w.apply_simple_reflection(1, side="right") + sage: w.apply_simple_reflection(1, side='right') [[1, 0, 0], [3, 2, 1]] - sage: w.apply_simple_reflection(2, side="right") + sage: w.apply_simple_reflection(2, side='right') [[1, 0, 0], [2, 1, 3]] - sage: w.apply_simple_reflection(3, side="right") + sage: w.apply_simple_reflection(3, side='right') [[2, 0, 0], [3, 1, 2]] TESTS:: @@ -1119,7 +1119,7 @@ def apply_reflections(self, word, side='right', word_type='all'): def _mul_(self, other): r""" - Return the product of ``self`` and ``other`` + Return the product of ``self`` and ``other``. This default implementation computes a reduced word of ``other`` using :meth:`reduced_word`, and applies the diff --git a/src/sage/categories/covariant_functorial_construction.py b/src/sage/categories/covariant_functorial_construction.py index 9cfbf82ae76..aee0d22a6af 100644 --- a/src/sage/categories/covariant_functorial_construction.py +++ b/src/sage/categories/covariant_functorial_construction.py @@ -93,14 +93,14 @@ class CovariantFunctorialConstruction(UniqueRepresentation, SageObject): In practice, each subclass of this class should provide the following attributes: - - ``_functor_category`` -- a string which should match the name of - the nested category class to be used in each category to - specify information and generic operations for elements of this - category. + - ``_functor_category`` -- string which should match the name of + the nested category class to be used in each category to + specify information and generic operations for elements of this + category - - ``_functor_name`` -- a string which specifies the name of the - functor, and also (when relevant) of the method on parents and - elements used for calling the construction. + - ``_functor_name`` -- string which specifies the name of the + functor, and also (when relevant) of the method on parents and + elements used for calling the construction TODO: What syntax do we want for `F_{Cat}`? For example, for the tensor product construction, which one do we want among (see @@ -131,8 +131,8 @@ def category_from_parents(self, parents): INPUT: - - self: a functor F - - parents: a list (or iterable) of parents. + - ``self`` -- a functor `F` + - ``parents`` -- a list (or iterable) of parents EXAMPLES:: @@ -157,8 +157,8 @@ def category_from_categories(self, categories): INPUT: - - ``self``: a functor `F` - - ``categories``: a non empty tuple of categories + - ``self`` -- a functor `F` + - ``categories`` -- a non empty tuple of categories EXAMPLES:: @@ -182,8 +182,8 @@ def category_from_category(self, category): INPUT: - - ``self``: a functor `F` - - ``category``: a category + - ``self`` -- a functor `F` + - ``category`` -- a category EXAMPLES:: @@ -205,18 +205,18 @@ def _repr_(self): def __call__(self, args, **kwargs): """ - Functorial construction application + Functorial construction application. INPUT: - - ``self``: a covariant functorial construction `F` - - ``args``: a tuple (or iterable) of parents or elements + - ``self`` -- a covariant functorial construction `F` + - ``args`` -- a tuple (or iterable) of parents or elements Returns `F(args)` EXAMPLES:: - sage: E = CombinatorialFreeModule(QQ, ["a", "b", "c"]); E.rename("E") # needs sage.modules + sage: E = CombinatorialFreeModule(QQ, ["a", "b", "c"]); E.rename('E') # needs sage.modules sage: tensor((E, E, E)) # needs sage.modules E # E # E """ @@ -237,9 +237,7 @@ def _base_category_class(cls): """ Recover the class of the base category. - OUTPUT: - - A *tuple* whose single entry is the base category class. + OUTPUT: a *tuple* whose single entry is the base category class .. WARNING:: @@ -396,9 +394,9 @@ def category_of(cls, category, *args): INPUT: - - ``cls`` -- the category class for the functorial construction `F` - - ``category`` -- a category `Cat` - - ``*args`` -- further arguments for the functor + - ``cls`` -- the category class for the functorial construction `F` + - ``category`` -- a category `Cat` + - ``*args`` -- further arguments for the functor EXAMPLES:: @@ -527,9 +525,9 @@ def default_super_categories(cls, category, *args): INPUT: - - ``cls`` -- the category class for the functor `F` - - ``category`` -- a category `Cat` - - ``*args`` -- further arguments for the functor + - ``cls`` -- the category class for the functor `F` + - ``category`` -- a category `Cat` + - ``*args`` -- further arguments for the functor OUTPUT: a (join) category @@ -677,9 +675,7 @@ def default_super_categories(cls, category, *args): - ``category`` -- a category `Cat` - ``*args`` -- further arguments for the functor - OUTPUT: - - A join category. + OUTPUT: a join category This implements the property that an induced subcategory is a subcategory. diff --git a/src/sage/categories/coxeter_group_algebras.py b/src/sage/categories/coxeter_group_algebras.py index 03b6b39d71e..32fe0292bb5 100644 --- a/src/sage/categories/coxeter_group_algebras.py +++ b/src/sage/categories/coxeter_group_algebras.py @@ -13,7 +13,7 @@ class CoxeterGroupAlgebras(AlgebrasCategory): class ParentMethods: def demazure_lusztig_operator_on_basis(self, w, i, q1, q2, - side="right"): + side='right'): r""" Return the result of applying the `i`-th Demazure Lusztig operator on ``w``. @@ -23,7 +23,7 @@ def demazure_lusztig_operator_on_basis(self, w, i, q1, q2, - ``w`` -- an element of the Coxeter group - ``i`` -- an element of the index set - ``q1``, ``q2`` -- two elements of the ground ring - - ``bar`` -- a boolean (default ``False``) + - ``bar`` -- boolean (default: ``False``) See :meth:`demazure_lusztig_operators` for details. @@ -70,16 +70,16 @@ def demazure_lusztig_operator_on_basis(self, w, i, q1, q2, """ return (q1+q2) * self.monomial(w.apply_simple_projection(i,side=side)) - self.term(w.apply_simple_reflection(i, side=side), q2) - def demazure_lusztig_operators(self, q1, q2, side="right", affine=True): + def demazure_lusztig_operators(self, q1, q2, side='right', affine=True): r""" Return the Demazure Lusztig operators acting on ``self``. INPUT: - ``q1``, ``q2`` -- two elements of the ground ring `K` - - ``side`` -- ``"left"`` or ``"right"`` (default: ``"right"``); + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``); which side to act upon - - ``affine`` -- a boolean (default: ``True``) + - ``affine`` -- boolean (default: ``True``) The Demazure-Lusztig operator `T_i` is the linear map `R \to R` obtained by interpolating between the diff --git a/src/sage/categories/coxeter_groups.py b/src/sage/categories/coxeter_groups.py index 0c1d32fec05..9f71cfdcf90 100644 --- a/src/sage/categories/coxeter_groups.py +++ b/src/sage/categories/coxeter_groups.py @@ -170,7 +170,7 @@ def coxeter_diagram(self): EXAMPLES:: sage: # needs sage.combinat sage.graphs sage.groups - sage: W = CoxeterGroup(['H', 3], implementation="reflection") + sage: W = CoxeterGroup(['H', 3], implementation='reflection') sage: G = W.coxeter_diagram(); G Graph on 3 vertices sage: G.edges(sort=True) @@ -262,7 +262,7 @@ def braid_orbit_iter(self, word): INPUT: - - ``word`` -- a list (or iterable) of indices in + - ``word`` -- list (or iterable) of indices in ``self.index_set()`` OUTPUT: @@ -309,7 +309,7 @@ def braid_orbit(self, word): INPUT: - - ``word``: a list (or iterable) of indices in + - ``word`` -- a list (or iterable) of indices in ``self.index_set()`` OUTPUT: @@ -410,9 +410,9 @@ def _element_constructor_(self, x, **args): EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W1 = WeylGroup("G2", prefix="s") + sage: W1 = WeylGroup("G2", prefix='s') sage: W2 = CoxeterGroup("G2") - sage: W3 = CoxeterGroup("G2", implementation="permutation") + sage: W3 = CoxeterGroup("G2", implementation='permutation') sage: W1(W2.an_element()) s1*s2 sage: W2(W1.an_element()) @@ -437,15 +437,15 @@ def _element_constructor_(self, x, **args): pass return self.element_class(self, x, **args) - def weak_order_ideal(self, predicate, side="right", category=None): + def weak_order_ideal(self, predicate, side='right', category=None): """ - Return a weak order ideal defined by a predicate + Return a weak order ideal defined by a predicate. INPUT: - - ``predicate``: a predicate on the elements of ``self`` defining an + - ``predicate`` -- a predicate on the elements of ``self`` defining an weak order ideal in ``self`` - - ``side``: "left" or "right" (default: "right") + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) OUTPUT: an enumerated set @@ -592,7 +592,7 @@ def standard_coxeter_elements(self): r""" Return all standard Coxeter elements in ``self``. - This is the set of all elements in self obtained from any + This is the set of all elements in ``self`` obtained from any product of the simple reflections in ``self``. .. NOTE:: @@ -636,14 +636,14 @@ class is not unique and we only obtain one such class. return {self.from_reduced_word(w) for w in Permutations(self.index_set())} - def grassmannian_elements(self, side="right"): + def grassmannian_elements(self, side='right'): """ Return the left or right Grassmannian elements of ``self`` as an enumerated set. INPUT: - - ``side`` -- (default: ``"right"``) ``"left"`` or ``"right"`` + - ``side`` -- (default: ``'right'``) ``'left'`` or ``'right'`` EXAMPLES:: @@ -741,7 +741,6 @@ def simple_projection(self, i, side='right', length_increasing=True): (1, 2, 3, 0) sage: d0(pi) (1, 2, 3, 0) - """ if not (i in self.index_set() or i == 0): raise ValueError("%s is not 0 and not in the Dynkin node set %s" % (i, self.index_set())) @@ -892,9 +891,9 @@ def simple_projections(self, side='right', length_increasing=True): INPUT: - ``self`` -- a Coxeter group `W` - - ``side`` -- 'left' or 'right' (default: 'right') - - ``length_increasing`` -- a boolean (default: ``True``) specifying - whether the operator increases or decreases length + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) + - ``length_increasing`` -- boolean (default: ``True``); whether + the operator increases or decreases length This returns the simple projections of `W`, as a family. @@ -965,7 +964,7 @@ def sign_representation(self, base_ring=None): from sage.modules.with_basis.representation import SignRepresentationCoxeterGroup return SignRepresentationCoxeterGroup(self, base_ring) - def reflection_representation(self, base_ring=None, side="left"): + def reflection_representation(self, base_ring=None, side='left'): r""" Return the reflection representation of ``self``. @@ -1010,7 +1009,7 @@ def demazure_product(self, Q): INPUT: - - ``Q`` is a list of elements from the index set of ``self``. + - ``Q`` -- list of elements from the index set of ``self`` This returns the Coxeter group element that represents the composition of 0-Hecke or Demazure operators. @@ -1041,14 +1040,14 @@ def bruhat_interval(self, x, y): EXAMPLES:: - sage: W = WeylGroup("A3", prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup("A3", prefix='s') # needs sage.combinat sage.groups sage: s1, s2, s3 = W.simple_reflections() # needs sage.combinat sage.groups sage: W.bruhat_interval(s2, s1*s3*s2*s1*s3) # needs sage.combinat sage.groups [s1*s2*s3*s2*s1, s2*s3*s2*s1, s3*s1*s2*s1, s1*s2*s3*s1, s1*s2*s3*s2, s3*s2*s1, s2*s3*s1, s2*s3*s2, s1*s2*s1, s3*s1*s2, s1*s2*s3, s2*s1, s3*s2, s2*s3, s1*s2, s2] - sage: W = WeylGroup(['A', 2, 1], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 2, 1], prefix='s') # needs sage.combinat sage.groups sage: s0, s1, s2 = W.simple_reflections() # needs sage.combinat sage.groups sage: W.bruhat_interval(1, s0*s1*s2) # needs sage.combinat sage.groups [s0*s1*s2, s1*s2, s0*s2, s0*s1, s2, s1, s0, 1] @@ -1080,12 +1079,12 @@ def bruhat_interval_poset(self, x, y, facade=False): EXAMPLES:: - sage: W = WeylGroup("A3", prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup("A3", prefix='s') # needs sage.combinat sage.groups sage: s1, s2, s3 = W.simple_reflections() # needs sage.combinat sage.groups sage: W.bruhat_interval_poset(s2, s1*s3*s2*s1*s3) # needs sage.combinat sage.groups Finite poset containing 16 elements - sage: W = WeylGroup(['A', 2, 1], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 2, 1], prefix='s') # needs sage.combinat sage.groups sage: s0, s1, s2 = W.simple_reflections() # needs sage.combinat sage.groups sage: W.bruhat_interval_poset(1, s0*s1*s2) # needs sage.combinat sage.groups Finite poset containing 8 elements @@ -1159,7 +1158,7 @@ def bruhat_graph(self, x=None, y=None, edge_labels=False): sage: W.bruhat_graph(s1, s3*s2*s3) Digraph on 0 vertices - sage: W = WeylGroup("A3", prefix="s") # needs sage.combinat sage.graphs sage.groups + sage: W = WeylGroup("A3", prefix='s') # needs sage.combinat sage.graphs sage.groups sage: s1, s2, s3 = W.simple_reflections() # needs sage.combinat sage.graphs sage.groups sage: G = W.bruhat_graph(s1*s3, s1*s2*s3*s2*s1); G # needs sage.combinat sage.graphs sage.groups Digraph on 10 vertices @@ -1292,7 +1291,7 @@ def random_element_of_length(self, n): def _test_simple_projections(self, **options): """ - Runs sanity checks on :meth:`.simple_projections` + Run sanity checks on :meth:`.simple_projections` and :meth:`CoxeterGroups.ElementMethods.apply_simple_projection` EXAMPLES:: @@ -1318,7 +1317,7 @@ def _test_has_descent(self, **options): """ Run sanity checks on the method :meth:`CoxeterGroups.ElementMethods.has_descent` of the - elements of self. + elements of ``self``. EXAMPLES:: @@ -1430,7 +1429,7 @@ def _test_coxeter_relations(self, **options): class ElementMethods: def has_descent(self, i, side='right', positive=False): """ - Return whether i is a (left/right) descent of self. + Return whether `i` is a (left/right) descent of ``self``. See :meth:`.descents` for a description of the options. @@ -1462,7 +1461,7 @@ def has_descent(self, i, side='right', positive=False): # @abstract_method(optional = True) def has_right_descent(self, i): """ - Return whether ``i`` is a right descent of self. + Return whether `i` is a right descent of ``self``. EXAMPLES:: @@ -1481,7 +1480,7 @@ def has_right_descent(self, i): def has_left_descent(self, i): """ - Return whether `i` is a left descent of self. + Return whether `i` is a left descent of ``self``. This default implementation uses that a left descent of `w` is a right descent of `w^{-1}`. @@ -1543,8 +1542,8 @@ def descents(self, side='right', index_set=None, positive=False): - ``index_set`` -- a subset (as a list or iterable) of the nodes of the Dynkin diagram; (default: all of them) - - ``side`` -- 'left' or 'right' (default: 'right') - - ``positive`` -- a boolean (default: ``False``) + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) + - ``positive`` -- boolean (default: ``False``) The ``index_set`` option can be used to restrict to the parabolic subgroup indexed by ``index_set``. @@ -1578,13 +1577,13 @@ def descents(self, side='right', index_set=None, positive=False): return [i for i in index_set if self.has_descent(i, side=side, positive=positive)] - def is_grassmannian(self, side="right") -> bool: + def is_grassmannian(self, side='right') -> bool: """ Return whether ``self`` is Grassmannian. INPUT: - - ``side`` -- "left" or "right" (default: "right") + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) An element is Grassmannian if it has at most one descent on the right (resp. on the left). @@ -1605,9 +1604,9 @@ def is_grassmannian(self, side="right") -> bool: sage: (s[1]*s[2]*s[1]).is_grassmannian() False - sage: (s[0]*s[2]*s[1]).is_grassmannian(side="left") + sage: (s[0]*s[2]*s[1]).is_grassmannian(side='left') False - sage: (s[0]*s[2]*s[1]).is_grassmannian(side="right") + sage: (s[0]*s[2]*s[1]).is_grassmannian(side='right') True sage: (s[0]*s[2]*s[1]).is_grassmannian() True @@ -1810,9 +1809,7 @@ def support(self): Return the support of ``self``, that is the simple reflections that appear in the reduced expressions of ``self``. - OUTPUT: - - The support of ``self`` as a set of integers + OUTPUT: the support of ``self`` as a set of integers EXAMPLES:: @@ -1924,7 +1921,7 @@ def reduced_word_graph(self): or x[j + m:] != y[j + m:]): continue edges.append([x, y, m]) - G = Graph(edges, immutable=True, format="list_of_edges") + G = Graph(edges, immutable=True, format='list_of_edges') colors = {2: 'blue', 3: 'red', 4: 'green'} G.set_latex_options(edge_labels=True, color_by_label=lambda x: colors[x]) @@ -1990,7 +1987,6 @@ def reflection_length(self): sage: s = W.simple_reflections() # needs sage.groups sage: (s[3]*s[2]*s[3]).reflection_length() # needs sage.combinat sage.groups 1 - """ return self.absolute_length() @@ -2281,7 +2277,7 @@ def coset_representative(self, index_set, side='right'): INPUT: - ``index_set`` -- a subset (or iterable) of the nodes of the Dynkin diagram - - ``side`` -- 'left' or 'right' + - ``side`` -- ``'left'`` or ``'right'`` EXAMPLES:: @@ -2312,7 +2308,6 @@ def coset_representative(self, index_set, side='right'): [1] sage: w.coset_representative([1,2,3], side='left').reduced_word() [] - """ while True: i = self.first_descent(side=side, index_set=index_set) @@ -2328,9 +2323,9 @@ def apply_simple_projection(self, i, side='right', length_increasing=True): INPUT: - ``i`` -- an element of the index set of the Coxeter group - - ``side`` -- 'left' or 'right' (default: 'right') - - ``length_increasing`` -- a boolean (default: ``True``) specifying - the direction of the projection + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) + - ``length_increasing`` -- boolean (default: ``True``); + specifying the direction of the projection See :meth:`CoxeterGroups.ParentMethods.simple_projections` for the definition of the simple projections. @@ -2347,7 +2342,7 @@ def apply_simple_projection(self, i, side='right', length_increasing=True): (1, 2, 0, 3) sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['C', 4], prefix="s") + sage: W = WeylGroup(['C', 4], prefix='s') sage: v = W.from_reduced_word([1,2,3,4,3,1]) sage: v s1*s2*s3*s4*s3*s1 @@ -2357,7 +2352,6 @@ def apply_simple_projection(self, i, side='right', length_increasing=True): s1*s2*s3*s4*s3*s1 sage: v.apply_simple_projection(1, length_increasing=False) s1*s2*s3*s4*s3 - """ if self.has_descent(i, side=side, positive=length_increasing): return self.apply_simple_reflection(i, side=side) @@ -2371,10 +2365,10 @@ def binary_factorizations(self, predicate=ConstantFunction(True)): Iterating through this set is Constant Amortized Time (counting arithmetic operations in the Coxeter group as constant time) complexity, and memory linear in the length - of `self`. + of ``self``. One can pass as optional argument a predicate p such that - `p(u)` implies `p(u')` for any `u` left factor of `self` + `p(u)` implies `p(u')` for any `u` left factor of ``self`` and `u'` left factor of `u`. Then this returns only the factorizations `self = uv` such `p(u)` holds. @@ -2474,7 +2468,7 @@ def bruhat_lower_covers(self): sage: w = W.from_reduced_word([0,2]) sage: print([v.reduced_word() for v in w.bruhat_lower_covers()]) [[2], [0]] - sage: W = WeylGroup("A3", prefix="s", implementation="permutation") + sage: W = WeylGroup("A3", prefix='s', implementation='permutation') sage: s1, s2, s3 = W.simple_reflections() sage: (s1*s2*s3*s1).bruhat_lower_covers() [s2*s1*s3, s1*s2*s1, s1*s2*s3] @@ -2513,7 +2507,7 @@ def bruhat_upper_covers(self): EXAMPLES:: - sage: W = WeylGroup(['A', 3, 1], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 3, 1], prefix='s') # needs sage.combinat sage.groups sage: w = W.from_reduced_word([1,2,1]) # needs sage.combinat sage.groups sage: w.bruhat_upper_covers() # needs sage.combinat sage.groups [s1*s2*s1*s0, s1*s2*s0*s1, s0*s1*s2*s1, s3*s1*s2*s1, s2*s3*s1*s2, s1*s2*s3*s1] @@ -2552,7 +2546,7 @@ def bruhat_lower_covers_reflections(self): EXAMPLES:: - sage: W = WeylGroup(['A', 3], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 3], prefix='s') # needs sage.combinat sage.groups sage: w = W.from_reduced_word([3,1,2,1]) # needs sage.combinat sage.groups sage: w.bruhat_lower_covers_reflections() # needs sage.combinat sage.groups [(s1*s2*s1, s1*s2*s3*s2*s1), (s3*s2*s1, s2), (s3*s1*s2, s1)] @@ -2586,13 +2580,12 @@ def lower_cover_reflections(self, side='right'): EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['A', 3],prefix="s") + sage: W = WeylGroup(['A', 3],prefix='s') sage: w = W.from_reduced_word([3,1,2,1]) sage: w.lower_cover_reflections() [s1*s2*s3*s2*s1, s2, s1] sage: w.lower_cover_reflections(side='left') [s2*s3*s2, s3, s1] - """ if side == 'left': self = self.inverse() @@ -2609,7 +2602,7 @@ def bruhat_upper_covers_reflections(self): EXAMPLES:: - sage: W = WeylGroup(['A', 4], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 4], prefix='s') # needs sage.combinat sage.groups sage: w = W.from_reduced_word([3,1,2,1]) # needs sage.combinat sage.groups sage: w.bruhat_upper_covers_reflections() # needs sage.combinat sage.groups [(s1*s2*s3*s2*s1, s3), (s2*s3*s1*s2*s1, s2*s3*s2), @@ -2634,13 +2627,12 @@ def cover_reflections(self, side='right'): EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['A', 4], prefix="s") + sage: W = WeylGroup(['A', 4], prefix='s') sage: w = W.from_reduced_word([3,1,2,1]) sage: w.cover_reflections() [s3, s2*s3*s2, s4, s1*s2*s3*s4*s3*s2*s1] sage: w.cover_reflections(side='left') [s4, s2, s1*s2*s1, s3*s4*s3] - """ if side == 'left': self = self.inverse() @@ -2653,9 +2645,9 @@ def bruhat_le(self, other): INPUT: - - other -- an element of the same Coxeter group + - ``other`` -- an element of the same Coxeter group - OUTPUT: a boolean + OUTPUT: boolean EXAMPLES:: @@ -2730,7 +2722,7 @@ def weak_le(self, other, side='right'): - ``other`` -- an element of the same Coxeter group - ``side`` -- string (default: ``'right'``); ``'left'`` or ``'right'`` - OUTPUT: a boolean + OUTPUT: boolean This returns whether `u \leq v`, where `u` is ``self`` and `v` is ``other``, in left (resp. right) weak order, that is if `v` @@ -2798,11 +2790,11 @@ def weak_covers(self, side='right', index_set=None, positive=False): INPUT: - - side -- 'left' or 'right' (default: 'right') - - positive -- a boolean (default: ``False``) - - index_set -- a list of indices or None + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) + - ``positive`` -- boolean (default: ``False``) + - ``index_set`` -- list of indices or None - OUTPUT: a list + OUTPUT: list EXAMPLES:: @@ -2846,11 +2838,9 @@ def coxeter_sorting_word(self, c): INPUT: - - ``c`` -- a Coxeter element. + - ``c`` -- a Coxeter element - OUTPUT: - - the ``c``-sorting word of ``self`` as a list of integers. + OUTPUT: the ``c``-sorting word of ``self`` as a list of integers EXAMPLES:: @@ -2890,13 +2880,9 @@ def is_coxeter_sortable(self, c, sorting_word=None): INPUT: - - ``c`` -- a Coxeter element. - - ``sorting_word`` -- sorting word (default: None) used to - not recompute the ``c``-sorting word if already computed. - - OUTPUT: - - is ``self`` ``c``-sortable + - ``c`` -- a Coxeter element + - ``sorting_word`` -- sorting word (default: ``None``); used to + not recompute the `c`-sorting word if already computed EXAMPLES:: @@ -2966,18 +2952,18 @@ def apply_demazure_product(self, element, side='right', reduced word) of elements from the index set of the Coxeter group. - - ``side`` -- 'left' or 'right' (default: 'right'); the + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``); the side of ``self`` on which the element should be applied. If ``side`` is 'left' then the operation is applied on the left. - - ``length_increasing`` -- a boolean (default: ``True``) + - ``length_increasing`` -- boolean (default: ``True``) whether to act length increasingly or decreasingly EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['C', 4], prefix="s") + sage: W = WeylGroup(['C', 4], prefix='s') sage: v = W.from_reduced_word([1,2,3,4,3,1]) sage: v.apply_demazure_product([1,3,4,3,3]) s4*s1*s2*s3*s4*s3*s1 @@ -2987,7 +2973,6 @@ def apply_demazure_product(self, element, side='right', s3*s4*s1*s2*s3*s4*s2*s3*s1 sage: v.apply_demazure_product(v) s2*s3*s4*s1*s2*s3*s4*s2*s3*s2*s1 - """ # if self and element have the same parent if self.parent().is_parent_of(element): @@ -3012,16 +2997,20 @@ def apply_demazure_product(self, element, side='right', def min_demazure_product_greater(self, element): r""" - Find the unique Bruhat-minimum element ``u`` such that ``v`` `\le` ``w`` * ``u`` where ``v`` is ``self``, ``w`` is ``element`` and ``*`` is the Demazure product. + Find the unique Bruhat-minimum element ``u`` such that ``v`` `\le` + ``w`` * ``u`` where ``v`` is ``self``, ``w`` is ``element`` and + ``*`` is the Demazure product. INPUT: - - ``element`` is either an element of the same Coxeter group as ``self`` or a list (such as a reduced word) of elements from the index set of the Coxeter group. + - ``element`` -- is either an element of the same Coxeter group as + ``self`` or a list (such as a reduced word) of elements from the + index set of the Coxeter group EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['A', 4], prefix="s") + sage: W = WeylGroup(['A', 4], prefix='s') sage: v = W.from_reduced_word([2,3,4,1,2]) sage: u = W.from_reduced_word([2,3,2,1]) sage: v.min_demazure_product_greater(u) @@ -3030,7 +3019,6 @@ def min_demazure_product_greater(self, element): s4*s2 sage: v.min_demazure_product_greater((2,3,2,1)) s4*s2 - """ # if self and element have the same parent if self.parent().is_parent_of(element): @@ -3054,8 +3042,9 @@ def deodhar_factor_element(self, w, index_set): INPUT: - - ``w`` is an element of the same Coxeter group ``W`` as ``self`` - - ``index_set`` is a subset of Dynkin nodes defining a parabolic subgroup ``W'`` of ``W`` + - ``w`` -- an element of the same Coxeter group ``W`` as ``self`` + - ``index_set`` -- a subset of Dynkin nodes defining a parabolic + subgroup ``W'`` of ``W`` It is assumed that ``v = self`` and ``w`` are minimum length coset representatives for ``W/W'`` such that ``v`` `\le` ``w`` in Bruhat order. @@ -3069,7 +3058,7 @@ def deodhar_factor_element(self, w, index_set): EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['A', 5], prefix="s") + sage: W = WeylGroup(['A', 5], prefix='s') sage: v = W.from_reduced_word([5]) sage: w = W.from_reduced_word([4,5,2,3,1,2]) sage: v.deodhar_factor_element(w, [1,3,4]) @@ -3113,8 +3102,9 @@ def deodhar_lift_up(self, w, index_set): INPUT: - - ``w`` is an element of the same Coxeter group ``W`` as ``self``. - - ``index_set`` is a subset of Dynkin nodes defining a parabolic subgroup ``W'``. + - ``w`` -- an element of the same Coxeter group ``W`` as ``self`` + - ``index_set`` -- a subset of Dynkin nodes defining a parabolic + subgroup ``W'`` OUTPUT: @@ -3126,7 +3116,7 @@ def deodhar_lift_up(self, w, index_set): EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['A', 3], prefix="s") + sage: W = WeylGroup(['A', 3], prefix='s') sage: v = W.from_reduced_word([1,2,3]) sage: w = W.from_reduced_word([1,3,2]) sage: v.deodhar_lift_up(w, [3]) @@ -3148,8 +3138,8 @@ def deodhar_lift_down(self, w, index_set): INPUT: - - ``w`` is an element of the same Coxeter group ``W`` as ``self``. - - ``index_set`` is a subset of Dynkin nodes defining a parabolic subgroup ``W'``. + - ``w`` -- an element of the same Coxeter group ``W`` as ``self`` + - ``index_set`` -- a subset of Dynkin nodes defining a parabolic subgroup ``W'`` OUTPUT: @@ -3161,12 +3151,11 @@ def deodhar_lift_down(self, w, index_set): EXAMPLES:: sage: # needs sage.combinat sage.groups - sage: W = WeylGroup(['A', 3], prefix="s") + sage: W = WeylGroup(['A', 3], prefix='s') sage: v = W.from_reduced_word([1,2,3,2]) sage: w = W.from_reduced_word([3,2]) sage: v.deodhar_lift_down(w, [3]) s2*s3*s2 - """ vmin = self.coset_representative(index_set) wmin = w.coset_representative(index_set) @@ -3184,7 +3173,7 @@ def inversions_as_reflections(self): EXAMPLES:: - sage: W = WeylGroup(['A', 3], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 3], prefix='s') # needs sage.combinat sage.groups sage: w = W.from_reduced_word([3,1,2,1]) # needs sage.combinat sage.groups sage: w.inversions_as_reflections() # needs sage.combinat sage.groups [s1, s1*s2*s1, s2, s1*s2*s3*s2*s1] @@ -3201,7 +3190,7 @@ def left_inversions_as_reflections(self): EXAMPLES:: - sage: W = WeylGroup(['A', 3], prefix="s") # needs sage.combinat sage.groups + sage: W = WeylGroup(['A', 3], prefix='s') # needs sage.combinat sage.groups sage: w = W.from_reduced_word([3,1,2,1]) # needs sage.combinat sage.groups sage: w.left_inversions_as_reflections() # needs sage.combinat sage.groups [s1, s3, s1*s2*s3*s2*s1, s2*s3*s2] @@ -3215,9 +3204,9 @@ def lower_covers(self, side='right', index_set=None): INPUT: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``index_set`` -- a list of indices or ``None`` + - ``index_set`` -- list of indices or ``None`` - OUTPUT: a list + OUTPUT: list EXAMPLES:: @@ -3251,9 +3240,9 @@ def upper_covers(self, side='right', index_set=None): INPUT: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``index_set`` -- a list of indices or ``None`` + - ``index_set`` -- list of indices or ``None`` - OUTPUT: a list + OUTPUT: list EXAMPLES:: diff --git a/src/sage/categories/crystals.py b/src/sage/categories/crystals.py index d8687f7e72a..c822bbd50fc 100644 --- a/src/sage/categories/crystals.py +++ b/src/sage/categories/crystals.py @@ -116,20 +116,20 @@ def super_categories(self): """ return [EnumeratedSets()] - def example(self, choice="highwt", **kwds): + def example(self, choice='highwt', **kwds): r""" - Returns an example of a crystal, as per + Return an example of a crystal, as per :meth:`Category.example() `. INPUT: - - ``choice`` -- str [default: 'highwt']. Can be either 'highwt' - for the highest weight crystal of type A, or 'naive' for an - example of a broken crystal. + - ``choice`` -- string (default: ``'highwt'``); can be either ``'highwt'`` + for the highest weight crystal of type A, or ``'naive'`` for an + example of a broken crystal - ``**kwds`` -- keyword arguments passed onto the constructor for the - chosen crystal. + chosen crystal EXAMPLES:: @@ -237,7 +237,7 @@ class ParentMethods: def an_element(self): """ - Returns an element of ``self`` + Return an element of ``self``. sage: C = crystals.Letters(['A', 5]) sage: C.an_element() @@ -309,7 +309,7 @@ def weight_lattice_realization(self): def cartan_type(self): """ - Returns the Cartan type of the crystal + Return the Cartan type of the crystal. EXAMPLES:: @@ -322,7 +322,7 @@ def cartan_type(self): @cached_method def index_set(self): """ - Returns the index set of the Dynkin diagram underlying the crystal + Return the index set of the Dynkin diagram underlying the crystal. EXAMPLES:: @@ -334,7 +334,7 @@ def index_set(self): def Lambda(self): """ - Returns the fundamental weights in the weight lattice + Return the fundamental weights in the weight lattice realization for the root system associated with the crystal EXAMPLES:: @@ -351,10 +351,10 @@ def __iter__(self, index_set=None, max_depth=float('inf')): INPUT: - - ``index_set`` -- (Default: ``None``) the index set; if ``None`` + - ``index_set`` -- (default: ``None``) the index set; if ``None`` then use the index set of the crystal - - ``max_depth`` -- (Default: infinity) the maximum depth to build + - ``max_depth`` -- (default: infinity) the maximum depth to build The iteration order is not specified except that, if ``max_depth`` is finite, then the iteration goes depth by @@ -382,7 +382,6 @@ def __iter__(self, index_set=None, max_depth=float('inf')): [(-Lambda[0] + Lambda[2],), (Lambda[0] - Lambda[1] + delta,), (Lambda[1] - Lambda[2],)] - """ if index_set is None: index_set = self.index_set() @@ -391,8 +390,8 @@ def __iter__(self, index_set=None, max_depth=float('inf')): R = RecursivelyEnumeratedSet(self.module_generators, succ, structure=None) return R.breadth_first_search_iterator(max_depth) - def subcrystal(self, index_set=None, generators=None, max_depth=float("inf"), - direction="both", contained=None, + def subcrystal(self, index_set=None, generators=None, max_depth=float('inf'), + direction='both', contained=None, virtualization=None, scaling_factors=None, cartan_type=None, category=None): r""" @@ -580,7 +579,7 @@ def _Hom_(self, Y, category=None, **options): The sole purpose of this method is to construct the homset as a :class:`~sage.categories.crystals.CrystalHomset`. If ``category`` is specified and is not a subcategory of - :class:`Crystals`, a :class:`TypeError` is raised instead. + :class:`Crystals`, a :exc:`TypeError` is raised instead. This method is not meant to be called directly. Please use :func:`sage.categories.homset.Hom` instead. @@ -634,8 +633,8 @@ def crystal_morphism(self, on_gens, codomain=None, default are all scaling factors to be one - ``category`` -- (optional) the category for the crystal morphism; the default is the category of :class:`Crystals`. - - ``check`` -- (default: ``True``) check if the crystal morphism - is valid + - ``check`` -- boolean (default: ``True``); check if the crystal + morphism is valid .. SEEALSO:: @@ -914,7 +913,7 @@ def digraph(self, subset=None, index_set=None): G = DiGraph(d) from sage.graphs.dot2tex_utils import have_dot2tex if have_dot2tex(): - G.set_latex_options(format="dot2tex", + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=self.cartan_type()._index_set_coloring) return G @@ -955,7 +954,7 @@ def latex_file(self, filename): def _latex_(self, **options): r""" - Returns the crystal graph as a latex string. This can be exported + Return the crystal graph as a latex string. This can be exported to a file with ``self.latex_file('filename')``. EXAMPLES:: @@ -1008,14 +1007,15 @@ def metapost(self, filename, thicklines=False, labels=True, scaling_factor=1.0, - ``filename`` -- name of the output file, e.g., ``'filename.mp'`` - - ``thicklines`` -- (default: ``True``) for thicker edges + - ``thicklines`` -- boolean (default: ``True``); for thicker edges - - ``labels`` -- (default: ``False``) to suppress labeling of the vertices + - ``labels`` -- boolean (default: ``False``); whether to suppress + labeling of the vertices - - ``scaling_factor`` -- (default: ``1.0``) Increasing or decreasing the + - ``scaling_factor`` -- (default: ``1.0``) increasing or decreasing the scaling factor changes the size of the image - - ``tallness`` -- (default: ``1.0``) Increasing makes the image taller + - ``tallness`` -- (default: ``1.0``) increasing makes the image taller without increasing the width EXAMPLES:: @@ -1330,7 +1330,7 @@ def index_set(self): def cartan_type(self): """ - Returns the Cartan type associated to ``self`` + Return the Cartan type associated to ``self``. EXAMPLES:: @@ -1550,7 +1550,7 @@ def is_highest_weight(self, index_set=None): def is_lowest_weight(self, index_set=None): r""" - Returns ``True`` if ``self`` is a lowest weight. + Return ``True`` if ``self`` is a lowest weight. Specifying the option ``index_set`` to be a subset `I` of the index set of the underlying crystal, finds all lowest weight vectors for arrows in `I`. @@ -1699,7 +1699,7 @@ def all_paths_to_highest_weight(self, index_set=None): if hw: yield [] - def subcrystal(self, index_set=None, max_depth=float("inf"), direction="both", + def subcrystal(self, index_set=None, max_depth=float("inf"), direction='both', contained=None, cartan_type=None, category=None): r""" Construct the subcrystal generated by ``self`` using `e_i` and/or @@ -2046,7 +2046,8 @@ class CrystalMorphismByGenerators(CrystalMorphism): for the weight, `\varepsilon` and `\varphi` - ``gens`` -- (optional) a finite list of generators to define the morphism; the default is to use the highest weight vectors of the crystal - - ``check`` -- (default: ``True``) check if the crystal morphism is valid + - ``check`` -- boolean (default: ``True``); check if the crystal morphism + is valid .. SEEALSO:: @@ -2201,7 +2202,7 @@ def _call_(self, x): def __bool__(self) -> bool: """ - Return if ``self`` is a non-zero morphism. + Return if ``self`` is a nonzero morphism. EXAMPLES:: @@ -2222,9 +2223,7 @@ def to_module_generator(self, x): Return a generator ``mg`` and a path of `e_i` and `f_i` operations to ``mg``. - OUTPUT: - - A tuple consisting of: + OUTPUT: a tuple consisting of: - a module generator, - a list of ``'e'`` and ``'f'`` to denote which operation, and diff --git a/src/sage/categories/discrete_valuation.py b/src/sage/categories/discrete_valuation.py index 1d13c49cd83..77267664bb2 100644 --- a/src/sage/categories/discrete_valuation.py +++ b/src/sage/categories/discrete_valuation.py @@ -18,7 +18,7 @@ class DiscreteValuationRings(Category_singleton): """ - The category of discrete valuation rings + The category of discrete valuation rings. EXAMPLES:: @@ -97,10 +97,10 @@ def _matrix_charpoly(self, M, var): sage: M.charpoly() x^3 + (4 + 4*t^2 + 4*t^4 + O(t^25))*x^2 + (4*t + O(t^24))*x - Another example over the p-adics:: + Another example over the `p`-adics:: sage: # needs sage.modules sage.rings.padics - sage: R = Zp(5, print_mode="digits", prec=5) + sage: R = Zp(5, print_mode='digits', prec=5) sage: M = matrix(R, 3, 3, range(9)) sage: M [ 0 ...00001 ...00002] @@ -138,7 +138,6 @@ def euclidean_degree(self): Traceback (most recent call last): ... ValueError: Euclidean degree of the zero element not defined - """ if not self: raise ValueError("Euclidean degree of the zero element not defined") @@ -199,7 +198,7 @@ def is_unit(self): def gcd(self,other): """ - Return the greatest common divisor of self and other, + Return the greatest common divisor of ``self`` and ``other``, normalized so that it is a power of the distinguished uniformizer. """ @@ -212,7 +211,7 @@ def gcd(self,other): def lcm(self,other): """ - Return the least common multiple of self and other, + Return the least common multiple of ``self`` and ``other``, normalized so that it is a power of the distinguished uniformizer. """ @@ -226,7 +225,7 @@ def lcm(self,other): class DiscreteValuationFields(Category_singleton): """ - The category of discrete valuation fields + The category of discrete valuation fields. EXAMPLES:: @@ -295,10 +294,10 @@ def _matrix_hessenbergize(self, H): [ O(t^10) O(t^10) O(t^10) O(t^10)] [ O(t^10) O(t^10) O(t^10) O(t^10)] - Another example over the p-adics:: + Another example over the `p`-adics:: sage: # needs sage.modules sage.rings.padics - sage: K = Qp(5, print_mode="digits", prec=5) + sage: K = Qp(5, print_mode='digits', prec=5) sage: H = matrix(K, 3, 3, range(9)); H [ 0 ...00001 ...00002] [ ...00003 ...00004 ...000010] diff --git a/src/sage/categories/division_rings.py b/src/sage/categories/division_rings.py index 3e6eb7c6c1c..fd3797fccc6 100644 --- a/src/sage/categories/division_rings.py +++ b/src/sage/categories/division_rings.py @@ -16,10 +16,10 @@ class DivisionRings(CategoryWithAxiom): """ - The category of division rings + The category of division rings. A division ring (or skew field) is a not necessarily commutative - ring where all non-zero elements have multiplicative inverses + ring where all nonzero elements have multiplicative inverses EXAMPLES:: diff --git a/src/sage/categories/domains.py b/src/sage/categories/domains.py index 052cc9a795c..de1cb009a08 100644 --- a/src/sage/categories/domains.py +++ b/src/sage/categories/domains.py @@ -17,7 +17,7 @@ class Domains(CategoryWithAxiom): """ - The category of domains + The category of domains. A domain (or non-commutative integral domain), is a ring, not necessarily commutative, with no nonzero zero divisors. @@ -77,7 +77,6 @@ def _test_zero_divisors(self, **options): sage: ZZ._test_zero_divisors() sage: ZpFM(5)._test_zero_divisors() # needs sage.rings.padics - """ if not self.is_exact(): return # Can't check on inexact rings diff --git a/src/sage/categories/drinfeld_modules.py b/src/sage/categories/drinfeld_modules.py index c2ba86e9f2f..aca5675497a 100644 --- a/src/sage/categories/drinfeld_modules.py +++ b/src/sage/categories/drinfeld_modules.py @@ -205,14 +205,14 @@ class DrinfeldModules(Category_over_base_ring): def __init__(self, base_field, name='t'): r""" - Initialize `self`. + Initialize ``self``. INPUT: - ``base_field`` -- the base field, which is a ring extension over a base - - ``name`` (default: ``'t'``) -- the name of the Ore polynomial + - ``name`` -- (default: ``'t'``) the name of the Ore polynomial variable TESTS:: @@ -290,7 +290,7 @@ def _latex_(self): r""" Return a latex representation of the category. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -310,7 +310,7 @@ def _repr_(self): r""" Return a string representation of the category. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -506,7 +506,7 @@ def object(self, gen): def ore_polring(self): r""" - Return the Ore polynomial ring of the category + Return the Ore polynomial ring of the category. EXAMPLES:: @@ -527,7 +527,7 @@ def random_object(self, rank): INPUT: - - ``rank`` -- an integer, the rank of the Drinfeld module + - ``rank`` -- integer; the rank of the Drinfeld module EXAMPLES:: @@ -785,6 +785,5 @@ def ore_variable(self): Ore Polynomial Ring in t over Finite Field in z12 of size 5^12 over its base twisted by Frob^2 sage: phi.ore_variable() t - """ return self.category().ore_polring().gen() diff --git a/src/sage/categories/enumerated_sets.py b/src/sage/categories/enumerated_sets.py index 5526bdb0235..68a830c289d 100644 --- a/src/sage/categories/enumerated_sets.py +++ b/src/sage/categories/enumerated_sets.py @@ -21,7 +21,7 @@ class EnumeratedSets(CategoryWithAxiom): """ - The category of enumerated sets + The category of enumerated sets. An *enumerated set* is a *finite* or *countable* set or multiset `S` together with a canonical enumeration of its elements; @@ -40,36 +40,36 @@ class EnumeratedSets(CategoryWithAxiom): The standard methods for an enumerated set ``S`` are: - - ``S.cardinality()``: the number of elements of the set. This + - ``S.cardinality()`` -- the number of elements of the set. This is the equivalent for ``len`` on a list except that the return value is specified to be a Sage :class:`Integer` or ``infinity``, instead of a Python ``int``. - - ``iter(S)``: an iterator for the elements of the set; + - ``iter(S)`` -- an iterator for the elements of the set; - - ``S.list()``: a fresh list of the elements of the set, when - possible; raises a :class:`NotImplementedError` if the list is + - ``S.list()`` -- a fresh list of the elements of the set, when + possible; raises a :exc:`NotImplementedError` if the list is predictably too large to be expanded in memory. - - ``S.tuple()``: a tuple of the elements of the set, when - possible; raises a :class:`NotImplementedError` if the tuple is + - ``S.tuple()`` -- a tuple of the elements of the set, when + possible; raises a :exc:`NotImplementedError` if the tuple is predictably too large to be expanded in memory. - - ``S.unrank(n)``: the ``n``-th element of the set when ``n`` is a sage + - ``S.unrank(n)`` -- the ``n``-th element of the set when ``n`` is a sage ``Integer``. This is the equivalent for ``l[n]`` on a list. - - ``S.rank(e)``: the position of the element ``e`` in the set; + - ``S.rank(e)`` -- the position of the element ``e`` in the set; This is equivalent to ``l.index(e)`` for a list except that the return value is specified to be a Sage :class:`Integer`, instead of a Python ``int``. - - ``S.first()``: the first object of the set; it is equivalent to + - ``S.first()`` -- the first object of the set; it is equivalent to ``S.unrank(0)``. - - ``S.next(e)``: the object of the set which follows ``e``; it is + - ``S.next(e)`` -- the object of the set which follows ``e``; it is equivalent to ``S.unrank(S.rank(e) + 1)``. - - ``S.random_element()``: a random generator for an element of + - ``S.random_element()`` -- a random generator for an element of the set. Unless otherwise stated, and for finite enumerated sets, the probability is uniform. @@ -78,7 +78,6 @@ class EnumeratedSets(CategoryWithAxiom): - ``FiniteEnumeratedSets().example()`` - ``InfiniteEnumeratedSets().example()`` - EXAMPLES:: sage: EnumeratedSets() @@ -184,7 +183,7 @@ def __iter__(self): the methods of the first column are defined using ``__iter__`` If none of these are provided, this raises - a :class:`NotImplementedError`. + a :exc:`NotImplementedError`. EXAMPLES: @@ -229,7 +228,6 @@ def __iter__(self): ....: return [5, 6, 7] sage: it = iter(set_list()); [next(it), next(it), next(it)] [5, 6, 7] - """ # Check if .first() and .next(x) are overridden in the subclass if ( self.first != self._first_from_iterator and @@ -710,7 +708,7 @@ def _next_from_iterator(self, obj): def _unrank_from_iterator(self, r): """ - The ``r``-th element of ``self`` + The ``r``-th element of ``self``. ``self.unrank(r)`` returns the ``r``-th element of ``self``, where ``r`` is an integer between ``0`` and ``n-1`` where ``n`` is the @@ -748,12 +746,12 @@ def _unrank_from_iterator(self, r): def _rank_from_iterator(self, x): """ - The rank of an element of ``self`` + The rank of an element of ``self``. ``self.rank(x)`` returns the rank of `x`, that is its position in the enumeration of ``self``. This is an integer between ``0`` and ``n-1`` where ``n`` is the - cardinality of ``self``, or None if `x` is not in `self`. + cardinality of ``self``, or None if `x` is not in ``self``. This is the default (brute force) implementation from the category ``EnumeratedSets()`` which can be used when the @@ -862,7 +860,7 @@ def _iterator_from_unrank(self): @cached_method def _an_element_from_iterator(self): """ - Return the first element of ``self`` returned by :meth:`__iter__` + Return the first element of ``self`` returned by :meth:`__iter__`. If ``self`` is empty, the exception :class:`~sage.categories.sets_cat.EmptySetError` is raised instead. @@ -930,7 +928,7 @@ def random_element(self): the probability is uniform. This is a generic implementation from the category - ``EnumeratedSets()``. It raises a :class:`NotImplementedError` + ``EnumeratedSets()``. It raises a :exc:`NotImplementedError` since one does not know whether the set is finite. EXAMPLES:: @@ -952,8 +950,8 @@ def map(self, f, name=None, *, is_injective=True): INPUT: - - ``is_injective`` -- boolean (default: ``True``) whether to assume - that ``f`` is injective. + - ``is_injective`` -- boolean (default: ``True``); whether to assume + that `f` is injective EXAMPLES:: @@ -1003,7 +1001,7 @@ def map(self, f, name=None, *, is_injective=True): # def _test_enumerated_set_contains(self, **options): """ - Checks that the methods :meth:`.__contains__` and :meth:`.__iter__` are consistent. + Check that the methods :meth:`.__contains__` and :meth:`.__iter__` are consistent. See also :class:`TestSuite`. @@ -1039,7 +1037,7 @@ def _test_enumerated_set_contains(self, **options): def _test_enumerated_set_iter_list(self, **options): """ - Checks that the methods :meth:`.list` and :meth:`.__iter__` are consistent. + Check that the methods :meth:`.list` and :meth:`.__iter__` are consistent. See also: :class:`TestSuite`. diff --git a/src/sage/categories/euclidean_domains.py b/src/sage/categories/euclidean_domains.py index 87e2edf5002..4c0459c8cdd 100644 --- a/src/sage/categories/euclidean_domains.py +++ b/src/sage/categories/euclidean_domains.py @@ -40,7 +40,6 @@ class EuclideanDomains(Category_singleton): TESTS:: sage: TestSuite(EuclideanDomains()).run() - """ def super_categories(self): """ @@ -60,7 +59,6 @@ def is_euclidean_domain(self): sage: Parent(QQ,category=EuclideanDomains()).is_euclidean_domain() True - """ return True @@ -71,7 +69,7 @@ def gcd_free_basis(self, elts): INPUT: - - ``elts`` -- A sequence of elements of ``self``. + - ``elts`` -- a sequence of elements of ``self`` OUTPUT: @@ -213,7 +211,7 @@ def euclidean_degree(self): OUTPUT: - For non-zero elements, a natural number. For the zero element, this + For nonzero elements, a natural number. For the zero element, this might raise an exception or produce some other output, depending on the implementation. @@ -257,15 +255,13 @@ def gcd(self, other): def quo_rem(self, other): r""" Return the quotient and remainder of the division of this element - by the non-zero element ``other``. + by the nonzero element ``other``. INPUT: - ``other`` -- an element in the same euclidean domain - OUTPUT: - - a pair of elements + OUTPUT: a pair of elements EXAMPLES:: diff --git a/src/sage/categories/examples/algebras_with_basis.py b/src/sage/categories/examples/algebras_with_basis.py index 2521aadae04..5abdc3d6942 100644 --- a/src/sage/categories/examples/algebras_with_basis.py +++ b/src/sage/categories/examples/algebras_with_basis.py @@ -19,7 +19,7 @@ class FreeAlgebra(CombinatorialFreeModule): r""" - An example of an algebra with basis: the free algebra + An example of an algebra with basis: the free algebra. This class illustrates a minimal implementation of an algebra with basis. """ @@ -31,7 +31,6 @@ def __init__(self, R, alphabet=("a", "b", "c")): sage: A = AlgebrasWithBasis(QQ).example(); A # needs sage.modules An example of an algebra with basis: the free algebra on the generators ('a', 'b', 'c') over Rational Field sage: TestSuite(A).run() # needs sage.modules - """ self._alphabet = alphabet CombinatorialFreeModule.__init__(self, R, @@ -50,7 +49,7 @@ def _repr_(self): @cached_method def one_basis(self): """ - Returns the empty word, which index the one of this algebra, + Return the empty word, which index the one of this algebra, as per :meth:`AlgebrasWithBasis.ParentMethods.one_basis`. EXAMPLES::r diff --git a/src/sage/categories/examples/commutative_additive_monoids.py b/src/sage/categories/examples/commutative_additive_monoids.py index eb98d91237c..5a99ccffee2 100644 --- a/src/sage/categories/examples/commutative_additive_monoids.py +++ b/src/sage/categories/examples/commutative_additive_monoids.py @@ -17,7 +17,7 @@ class FreeCommutativeAdditiveMonoid(FreeCommutativeAdditiveSemigroup): r""" - An example of a commutative additive monoid: the free commutative monoid + An example of a commutative additive monoid: the free commutative monoid. This class illustrates a minimal implementation of a commutative monoid. @@ -69,11 +69,11 @@ class FreeCommutativeAdditiveMonoid(FreeCommutativeAdditiveSemigroup): def __init__(self, alphabet=('a','b','c','d')): r""" - The free commutative monoid + The free commutative monoid. INPUT: - - ``alphabet`` -- a tuple of strings: the generators of the monoid + - ``alphabet`` -- tuple of strings; the generators of the monoid EXAMPLES:: @@ -83,7 +83,6 @@ def __init__(self, alphabet=('a','b','c','d')): TESTS:: sage: TestSuite(M).run() - """ self.alphabet = alphabet Parent.__init__(self, category=CommutativeAdditiveMonoids()) @@ -95,14 +94,13 @@ def _repr_(self): sage: M = CommutativeAdditiveMonoids().example(alphabet=('a','b','c')) sage: M._repr_() "An example of a commutative monoid: the free commutative monoid generated by ('a', 'b', 'c')" - """ return "An example of a commutative monoid: the free commutative monoid generated by %s" % (self.alphabet,) @cached_method def zero(self): r""" - Returns the zero of this additive monoid, as per :meth:`CommutativeAdditiveMonoids.ParentMethods.zero`. + Return the zero of this additive monoid, as per :meth:`CommutativeAdditiveMonoids.ParentMethods.zero`. EXAMPLES:: diff --git a/src/sage/categories/examples/commutative_additive_semigroups.py b/src/sage/categories/examples/commutative_additive_semigroups.py index 34e2ebfd0d8..78f0eedb2d0 100644 --- a/src/sage/categories/examples/commutative_additive_semigroups.py +++ b/src/sage/categories/examples/commutative_additive_semigroups.py @@ -19,7 +19,7 @@ class FreeCommutativeAdditiveSemigroup(UniqueRepresentation, Parent): r""" - An example of a commutative additive monoid: the free commutative monoid + An example of a commutative additive monoid: the free commutative monoid. This class illustrates a minimal implementation of a commutative additive monoid. @@ -69,11 +69,11 @@ class FreeCommutativeAdditiveSemigroup(UniqueRepresentation, Parent): def __init__(self, alphabet=('a','b','c','d')): r""" - The free commutative monoid + The free commutative monoid. INPUT: - - ``alphabet`` -- a tuple of strings: the generators of the semigroup + - ``alphabet`` -- tuple of strings; the generators of the semigroup EXAMPLES:: @@ -94,13 +94,12 @@ def _repr_(self): sage: M = CommutativeAdditiveSemigroups().example(alphabet=('a','b','c')) sage: M._repr_() "An example of a commutative semigroup: the free commutative semigroup generated by ('a', 'b', 'c')" - """ return "An example of a commutative semigroup: the free commutative semigroup generated by %s" % (self.alphabet,) def summation(self, x, y): r""" - Returns the product of ``x`` and ``y`` in the semigroup, as per + Return the product of ``x`` and ``y`` in the semigroup, as per :meth:`CommutativeAdditiveSemigroups.ParentMethods.summation`. EXAMPLES:: @@ -119,7 +118,7 @@ def summation(self, x, y): @cached_method def additive_semigroup_generators(self): r""" - Returns the generators of the semigroup. + Return the generators of the semigroup. EXAMPLES:: @@ -134,7 +133,7 @@ def additive_semigroup_generators(self): def an_element(self): r""" - Returns an element of the semigroup. + Return an element of the semigroup. EXAMPLES:: diff --git a/src/sage/categories/examples/crystals.py b/src/sage/categories/examples/crystals.py index 4786a4ed6fd..dedad2c47d5 100644 --- a/src/sage/categories/examples/crystals.py +++ b/src/sage/categories/examples/crystals.py @@ -127,7 +127,7 @@ class Element(ElementWrapper): def e(self, i): r""" - Returns the action of `e_i` on ``self``. + Return the action of `e_i` on ``self``. EXAMPLES:: @@ -143,7 +143,7 @@ def e(self, i): def f(self, i): r""" - Returns the action of `f_i` on ``self``. + Return the action of `f_i` on ``self``. EXAMPLES:: @@ -204,7 +204,7 @@ def __repr__(self): class Element(ElementWrapper): def e(self, i): r""" - Returns the action of `e_i` on ``self``. + Return the action of `e_i` on ``self``. EXAMPLES:: @@ -220,7 +220,7 @@ def e(self, i): def f(self, i): r""" - Returns the action of `f_i` on ``self``. + Return the action of `f_i` on ``self``. EXAMPLES:: diff --git a/src/sage/categories/examples/facade_sets.py b/src/sage/categories/examples/facade_sets.py index 3108ba967c0..a26e23834ee 100644 --- a/src/sage/categories/examples/facade_sets.py +++ b/src/sage/categories/examples/facade_sets.py @@ -81,13 +81,12 @@ def _repr_(self): EXAMPLES:: sage: S = Sets().Facade().example() # indirect doctest - """ return "An example of facade set: the monoid of positive integers" def _element_constructor_(self, object): r""" - Construction of elements + Construction of elements. Since ``self`` is a strict subset of the parent it is a facade for, it is mandatory to override this method. This method diff --git a/src/sage/categories/examples/filtered_algebras_with_basis.py b/src/sage/categories/examples/filtered_algebras_with_basis.py index 9b982e7123f..6de8f87edc0 100644 --- a/src/sage/categories/examples/filtered_algebras_with_basis.py +++ b/src/sage/categories/examples/filtered_algebras_with_basis.py @@ -34,17 +34,17 @@ class PBWBasisCrossProduct(CombinatorialFreeModule): The implementation involves the following: - - A set of algebra generators -- the set of generators `x,y,z`. + - A set of algebra generators -- the set of generators `x,y,z` - The index of the unit element -- the unit element in the monoid - of monomials. + of monomials - A product -- this is given on basis elements by using - :meth:`product_on_basis`. + :meth:`product_on_basis` - A degree function -- this is determined on the basis elements by using :meth:`degree_on_basis` which returns the sum of exponents - of the monomial. + of the monomial """ def __init__(self, base_ring): """ @@ -127,7 +127,7 @@ def degree_on_basis(self, m): - ``m`` -- an element of the free abelian monoid - OUTPUT: an integer, the degree of the corresponding basis element + OUTPUT: integer; the degree of the corresponding basis element EXAMPLES:: diff --git a/src/sage/categories/examples/filtered_modules_with_basis.py b/src/sage/categories/examples/filtered_modules_with_basis.py index d62c3d906ff..4dbe78dc5eb 100644 --- a/src/sage/categories/examples/filtered_modules_with_basis.py +++ b/src/sage/categories/examples/filtered_modules_with_basis.py @@ -108,7 +108,7 @@ def degree_on_basis(self, t): - ``t`` -- the index of an element of the basis of this module, i.e. a partition - OUTPUT: an integer, the degree of the corresponding basis element + OUTPUT: integer; the degree of the corresponding basis element EXAMPLES:: diff --git a/src/sage/categories/examples/finite_coxeter_groups.py b/src/sage/categories/examples/finite_coxeter_groups.py index 9abf9304929..b84da8d221a 100644 --- a/src/sage/categories/examples/finite_coxeter_groups.py +++ b/src/sage/categories/examples/finite_coxeter_groups.py @@ -92,7 +92,7 @@ def __init__(self, n=5): INPUT: - - `n` -- an integer with `n \geq 2` + - ``n`` -- integer with `n \geq 2` EXAMPLES:: @@ -117,7 +117,7 @@ def _repr_(self): def __contains__(self, x): r""" - Check in the element x is in the mathematical parent self. + Check if the element ``x`` is in the mathematical parent ``self``. EXAMPLES:: @@ -135,7 +135,7 @@ def __contains__(self, x): @cached_method def one(self): r""" - Implements :meth:`Monoids.ParentMethods.one`. + Implement :meth:`Monoids.ParentMethods.one`. EXAMPLES:: @@ -147,7 +147,7 @@ def one(self): def index_set(self): r""" - Implements :meth:`CoxeterGroups.ParentMethods.index_set`. + Implement :meth:`CoxeterGroups.ParentMethods.index_set`. EXAMPLES:: @@ -185,9 +185,9 @@ class Element(ElementWrapper): wrapped_class = tuple __lt__ = ElementWrapper._lt_by_value - def has_right_descent(self, i, positive=False, side="right"): + def has_right_descent(self, i, positive=False, side='right'): r""" - Implements :meth:`SemiGroups.ElementMethods.has_right_descent`. + Implement :meth:`SemiGroups.ElementMethods.has_right_descent`. EXAMPLES:: @@ -222,7 +222,7 @@ def has_right_descent(self, i, positive=False, side="right"): def apply_simple_reflection_right(self, i): r""" - Implements :meth:`CoxeterGroups.ElementMethods.apply_simple_reflection`. + Implement :meth:`CoxeterGroups.ElementMethods.apply_simple_reflection`. EXAMPLES:: diff --git a/src/sage/categories/examples/finite_enumerated_sets.py b/src/sage/categories/examples/finite_enumerated_sets.py index 264b9bc13ba..a4a1ea6fdd6 100644 --- a/src/sage/categories/examples/finite_enumerated_sets.py +++ b/src/sage/categories/examples/finite_enumerated_sets.py @@ -17,7 +17,7 @@ class Example(UniqueRepresentation, Parent): r""" - An example of a finite enumerated set: `\{1,2,3\}` + An example of a finite enumerated set: `\{1,2,3\}`. This class provides a minimal implementation of a finite enumerated set. @@ -107,7 +107,6 @@ def __iter__(self): sage: list(FiniteEnumeratedSets().example()) # indirect doctest [1, 2, 3] - """ return iter(self._set) @@ -131,7 +130,7 @@ def __init__(self, ambient=Example()): def ambient(self): """ - Returns the ambient space for ``self``, as per + Return the ambient space for ``self``, as per :meth:`Sets.Subquotients.ParentMethods.ambient() `. diff --git a/src/sage/categories/examples/finite_monoids.py b/src/sage/categories/examples/finite_monoids.py index 20119abac66..3190daba74e 100644 --- a/src/sage/categories/examples/finite_monoids.py +++ b/src/sage/categories/examples/finite_monoids.py @@ -21,7 +21,7 @@ class IntegerModMonoid(UniqueRepresentation, Parent): r""" - An example of a finite monoid: the integers mod `n` + An example of a finite monoid: the integers mod `n`. This class illustrates a minimal implementation of a finite monoid. @@ -115,7 +115,6 @@ def one(self): sage: M = FiniteMonoids().example() sage: M.one() 1 - """ return self(ZZ.one()) @@ -134,7 +133,7 @@ def product(self, x, y): def an_element(self): r""" - Returns an element of the monoid, as per :meth:`Sets.ParentMethods.an_element`. + Return an element of the monoid, as per :meth:`Sets.ParentMethods.an_element`. EXAMPLES:: diff --git a/src/sage/categories/examples/finite_semigroups.py b/src/sage/categories/examples/finite_semigroups.py index d019e6895e4..a70fe35cabb 100644 --- a/src/sage/categories/examples/finite_semigroups.py +++ b/src/sage/categories/examples/finite_semigroups.py @@ -19,7 +19,7 @@ class LeftRegularBand(UniqueRepresentation, Parent): r""" - An example of a finite semigroup + An example of a finite semigroup. This class provides a minimal implementation of a finite semigroup. @@ -71,7 +71,7 @@ class LeftRegularBand(UniqueRepresentation, Parent): Now, let us look at the structure of the semigroup:: sage: S = FiniteSemigroups().example(alphabet = ('a','b','c')) - sage: S.cayley_graph(side="left", simple=True).plot() # needs sage.graphs sage.plot + sage: S.cayley_graph(side='left', simple=True).plot() # needs sage.graphs sage.plot Graphics object consisting of 60 graphics primitives sage: S.j_transversal_of_idempotents() # random (arbitrary choice) # needs sage.graphs ['acb', 'ac', 'ab', 'bc', 'a', 'c', 'b'] @@ -134,7 +134,7 @@ def _repr_(self): def product(self, x, y): r""" - Returns the product of two elements of the semigroup. + Return the product of two elements of the semigroup. EXAMPLES:: @@ -145,7 +145,6 @@ def product(self, x, y): 'ab' sage: S('a') * S('a') 'a' - """ assert x in self assert y in self @@ -156,20 +155,19 @@ def product(self, x, y): @cached_method def semigroup_generators(self): r""" - Returns the generators of the semigroup. + Return the generators of the semigroup. EXAMPLES:: sage: S = FiniteSemigroups().example(alphabet=('x','y')) sage: S.semigroup_generators() Family ('x', 'y') - """ return Family([self(i) for i in self.alphabet]) def an_element(self): r""" - Returns an element of the semigroup. + Return an element of the semigroup. EXAMPLES:: diff --git a/src/sage/categories/examples/finite_weyl_groups.py b/src/sage/categories/examples/finite_weyl_groups.py index b3321bdb58b..91be348f3d1 100644 --- a/src/sage/categories/examples/finite_weyl_groups.py +++ b/src/sage/categories/examples/finite_weyl_groups.py @@ -61,7 +61,7 @@ class SymmetricGroup(UniqueRepresentation, Parent): 24 sage: S.long_element() (3, 2, 1, 0) - sage: S.cayley_graph(side="left").plot() # needs sage.graphs sage.plot + sage: S.cayley_graph(side='left').plot() # needs sage.graphs sage.plot Graphics object consisting of 120 graphics primitives Alternatively, one could have implemented @@ -91,14 +91,13 @@ def _repr_(self): sage: FiniteWeylGroups().example() The symmetric group on {0, ..., 3} - """ return "The symmetric group on {0, ..., %s}" % (self.n-1) @cached_method def one(self): """ - Implements :meth:`Monoids.ParentMethods.one`. + Implement :meth:`Monoids.ParentMethods.one`. EXAMPLES:: @@ -109,7 +108,7 @@ def one(self): def index_set(self): """ - Implements :meth:`CoxeterGroups.ParentMethods.index_set`. + Implement :meth:`CoxeterGroups.ParentMethods.index_set`. EXAMPLES:: @@ -147,7 +146,7 @@ def cartan_type(self): def product(self, x, y): """ - Implements :meth:`Semigroups.ParentMethods.product`. + Implement :meth:`Semigroups.ParentMethods.product`. EXAMPLES:: @@ -176,7 +175,7 @@ class Element(ElementWrapper): def has_right_descent(self, i): """ - Implements :meth:`CoxeterGroups.ElementMethods.has_right_descent`. + Implement :meth:`CoxeterGroups.ElementMethods.has_right_descent`. EXAMPLES:: diff --git a/src/sage/categories/examples/graded_connected_hopf_algebras_with_basis.py b/src/sage/categories/examples/graded_connected_hopf_algebras_with_basis.py index 28699e17256..ae91a374489 100644 --- a/src/sage/categories/examples/graded_connected_hopf_algebras_with_basis.py +++ b/src/sage/categories/examples/graded_connected_hopf_algebras_with_basis.py @@ -21,7 +21,7 @@ class GradedConnectedCombinatorialHopfAlgebraWithPrimitiveGenerator(Combinatoria r""" This class illustrates an implementation of a graded Hopf algebra with basis that has one primitive generator of degree 1 and basis - elements indexed by non-negative integers. + elements indexed by nonnegative integers. This Hopf algebra example differs from what topologists refer to as a graded Hopf algebra because the twist operation in the tensor rule @@ -33,7 +33,6 @@ class GradedConnectedCombinatorialHopfAlgebraWithPrimitiveGenerator(Combinatoria (\Delta \otimes \Delta) = \Delta \circ \mu where `\tau(x\otimes y) = y\otimes x`. - """ def __init__(self, base_ring): """ @@ -41,7 +40,6 @@ def __init__(self, base_ring): sage: H = GradedHopfAlgebrasWithBasis(QQ).Connected().example() sage: TestSuite(H).run() - """ CombinatorialFreeModule.__init__(self, base_ring, NonNegativeIntegers(), category=GradedHopfAlgebrasWithBasis(base_ring).Connected()) @@ -49,11 +47,9 @@ def __init__(self, base_ring): @cached_method def one_basis(self): """ - Returns 0, which index the unit of the Hopf algebra. - - OUTPUT: + Return 0, which index the unit of the Hopf algebra. - - the non-negative integer 0 + OUTPUT: the nonnegative integer 0 EXAMPLES:: @@ -62,40 +58,35 @@ def one_basis(self): 0 sage: H.one() P0 - """ return self.basis().keys()(0) def degree_on_basis(self, i): """ - The degree of a non-negative integer is itself + The degree of a nonnegative integer is itself. INPUT: - - ``i`` -- a non-negative integer - - OUTPUT: + - ``i`` -- nonnegative integer - - a non-negative integer + OUTPUT: nonnegative integer TESTS:: sage: H = GradedHopfAlgebrasWithBasis(QQ).Connected().example() sage: H.degree_on_basis(45) 45 - """ return i def _repr_(self): """ - Representation of the graded connected Hopf algebra + Representation of the graded connected Hopf algebra. EXAMPLES:: sage: GradedHopfAlgebrasWithBasis(QQ).Connected().example() An example of a graded connected Hopf algebra with basis over Rational Field - """ return "An example of a graded connected Hopf algebra with basis over %s" % self.base_ring() @@ -108,7 +99,6 @@ def _repr_term(self, i): sage: H = GradedHopfAlgebrasWithBasis(QQ).Connected().example() sage: H._repr_term(45) 'P45' - """ return 'P' + repr(i) @@ -121,18 +111,15 @@ def product_on_basis(self, i, j): INPUT: - - ``i``, ``j`` -- non-negative integers - - OUTPUT: + - ``i``, ``j`` -- nonnegative integers - - a basis element indexed by ``i+j`` + OUTPUT: a basis element indexed by ``i+j`` TESTS:: sage: H = GradedHopfAlgebrasWithBasis(QQ).Connected().example() sage: H.monomial(4) * H.monomial(5) P9 - """ return self.monomial(i+j) @@ -146,11 +133,9 @@ def coproduct_on_basis(self, i): INPUT: - - ``i`` -- a non-negative integer - - OUTPUT: + - ``i`` -- nonnegative integer - - an element of the tensor square of ``self`` + OUTPUT: an element of the tensor square of ``self`` TESTS:: diff --git a/src/sage/categories/examples/graded_modules_with_basis.py b/src/sage/categories/examples/graded_modules_with_basis.py index 348bc5b9568..7443a48a7af 100644 --- a/src/sage/categories/examples/graded_modules_with_basis.py +++ b/src/sage/categories/examples/graded_modules_with_basis.py @@ -38,7 +38,7 @@ class GradedPartitionModule(CombinatorialFreeModule): sage: A = GradedModulesWithBasis(QQ).example() # needs sage.modules - - A basis function - this module is graded by the non-negative + - A basis function - this module is graded by the nonnegative integers, so there is a function defined in this module, creatively called :func:`basis`, which takes an integer `d` as input and returns a family of partitions representing a basis @@ -122,7 +122,7 @@ def degree_on_basis(self, t): - ``t`` -- the index of an element of the basis of this module, i.e. a partition - OUTPUT: an integer, the degree of the corresponding basis element + OUTPUT: integer, the degree of the corresponding basis element EXAMPLES:: @@ -139,7 +139,7 @@ def degree_on_basis(self, t): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: diff --git a/src/sage/categories/examples/hopf_algebras_with_basis.py b/src/sage/categories/examples/hopf_algebras_with_basis.py index b9eb6ffac81..a2d8c88e074 100644 --- a/src/sage/categories/examples/hopf_algebras_with_basis.py +++ b/src/sage/categories/examples/hopf_algebras_with_basis.py @@ -19,7 +19,7 @@ class MyGroupAlgebra(CombinatorialFreeModule): r""" - An example of a Hopf algebra with basis: the group algebra of a group + An example of a Hopf algebra with basis: the group algebra of a group. This class illustrates a minimal implementation of a Hopf algebra with basis. """ @@ -50,7 +50,7 @@ def _repr_(self): @cached_method def one_basis(self): """ - Returns the one of the group, which index the one of this algebra, + Return the one of the group, which index the one of this algebra, as per :meth:`AlgebrasWithBasis.ParentMethods.one_basis`. EXAMPLES:: diff --git a/src/sage/categories/examples/infinite_enumerated_sets.py b/src/sage/categories/examples/infinite_enumerated_sets.py index 8f23d276988..82f12b4691c 100644 --- a/src/sage/categories/examples/infinite_enumerated_sets.py +++ b/src/sage/categories/examples/infinite_enumerated_sets.py @@ -17,7 +17,7 @@ class NonNegativeIntegers(UniqueRepresentation, Parent): r""" - An example of infinite enumerated set: the non negative integers + An example of infinite enumerated set: the nonnegative integers. This class provides a minimal implementation of an infinite enumerated set. @@ -25,7 +25,7 @@ class NonNegativeIntegers(UniqueRepresentation, Parent): sage: NN = InfiniteEnumeratedSets().example() sage: NN - An example of an infinite enumerated set: the non negative integers + An example of an infinite enumerated set: the nonnegative integers sage: NN.cardinality() +Infinity sage: NN.list() @@ -85,7 +85,7 @@ def __init__(self): sage: NN = InfiniteEnumeratedSets().example() sage: NN - An example of an infinite enumerated set: the non negative integers + An example of an infinite enumerated set: the nonnegative integers sage: NN.category() Category of infinite enumerated sets sage: TestSuite(NN).run() @@ -97,9 +97,9 @@ def _repr_(self): TESTS:: sage: InfiniteEnumeratedSets().example() # indirect doctest - An example of an infinite enumerated set: the non negative integers + An example of an infinite enumerated set: the nonnegative integers """ - return "An example of an infinite enumerated set: the non negative integers" + return "An example of an infinite enumerated set: the nonnegative integers" def __contains__(self, elt): """ @@ -139,11 +139,11 @@ def __call__(self, elt): sage: NN(-1) Traceback (most recent call last): ... - ValueError: Value -1 is not a non negative integer. + ValueError: Value -1 is not a nonnegative integer. """ if elt in self: return self._element_constructor_(elt) - raise ValueError("Value %s is not a non negative integer." % (elt)) + raise ValueError("Value %s is not a nonnegative integer." % (elt)) def an_element(self): """ diff --git a/src/sage/categories/examples/lie_algebras.py b/src/sage/categories/examples/lie_algebras.py index b8a3f9c8e21..ac70705f41f 100644 --- a/src/sage/categories/examples/lie_algebras.py +++ b/src/sage/categories/examples/lie_algebras.py @@ -216,7 +216,7 @@ def __hash__(self): def __bool__(self) -> bool: """ - Check non-zero. + Check nonzero. EXAMPLES:: diff --git a/src/sage/categories/examples/magmas.py b/src/sage/categories/examples/magmas.py index 538929c70a0..c11248b7d80 100644 --- a/src/sage/categories/examples/magmas.py +++ b/src/sage/categories/examples/magmas.py @@ -56,7 +56,7 @@ def __init__(self, alphabet=('a', 'b', 'c', 'd')): INPUT: - - ``alphabet`` -- a tuple of strings; the generators of the magma + - ``alphabet`` -- tuple of strings; the generators of the magma EXAMPLES:: @@ -136,7 +136,7 @@ def _element_constructor_(self, x): INPUT: - - ``x`` -- a string + - ``x`` -- string EXAMPLES:: diff --git a/src/sage/categories/examples/monoids.py b/src/sage/categories/examples/monoids.py index 27da0cf418c..cbeaea058c5 100644 --- a/src/sage/categories/examples/monoids.py +++ b/src/sage/categories/examples/monoids.py @@ -19,7 +19,7 @@ class FreeMonoid(FreeSemigroup): r""" - An example of a monoid: the free monoid + An example of a monoid: the free monoid. This class illustrates a minimal implementation of a monoid. For a full featured implementation of free monoids, see :func:`FreeMonoid`. @@ -78,11 +78,11 @@ class FreeMonoid(FreeSemigroup): def __init__(self, alphabet=('a','b','c','d')): r""" - The free monoid + The free monoid. INPUT: - - ``alphabet`` -- a tuple of strings: the generators of the monoid + - ``alphabet`` -- tuple of strings; the generators of the monoid EXAMPLES:: @@ -92,7 +92,6 @@ def __init__(self, alphabet=('a','b','c','d')): TESTS:: sage: TestSuite(M).run() - """ self.alphabet = alphabet Parent.__init__(self, category=Monoids()) @@ -104,14 +103,13 @@ def _repr_(self): sage: M = Monoids().example(alphabet=('a','b','c')) sage: M._repr_() "An example of a monoid: the free monoid generated by ('a', 'b', 'c')" - """ return "An example of a monoid: the free monoid generated by %s" % (self.alphabet,) @cached_method def one(self): r""" - Returns the one of the monoid, as per :meth:`Monoids.ParentMethods.one`. + Return the one of the monoid, as per :meth:`Monoids.ParentMethods.one`. EXAMPLES:: @@ -119,7 +117,6 @@ def one(self): An example of a monoid: the free monoid generated by ('a', 'b', 'c', 'd') sage: M.one() '' - """ return self("") diff --git a/src/sage/categories/examples/posets.py b/src/sage/categories/examples/posets.py index 639ec9c6bc8..9e67b294fee 100644 --- a/src/sage/categories/examples/posets.py +++ b/src/sage/categories/examples/posets.py @@ -19,7 +19,7 @@ class FiniteSetsOrderedByInclusion(UniqueRepresentation, Parent): r""" - An example of a poset: finite sets ordered by inclusion + An example of a poset: finite sets ordered by inclusion. This class provides a minimal implementation of a poset @@ -80,7 +80,7 @@ def _repr_(self): def le(self, x, y): r""" - Returns whether `x` is a subset of `y` + Return whether `x` is a subset of `y`. EXAMPLES:: @@ -96,7 +96,7 @@ def le(self, x, y): def an_element(self): r""" - Returns an element of this poset + Return an element of this poset. EXAMPLES:: @@ -113,7 +113,7 @@ class Element(ElementWrapper): class PositiveIntegersOrderedByDivisibilityFacade(UniqueRepresentation, Parent): r""" - An example of a facade poset: the positive integers ordered by divisibility + An example of a facade poset: the positive integers ordered by divisibility. This class provides a minimal implementation of a facade poset @@ -163,7 +163,7 @@ def _repr_(self): def le(self, x, y): r""" - Returns whether `x` is divisible by `y` + Return whether `x` is divisible by `y`. EXAMPLES:: diff --git a/src/sage/categories/examples/semigroups.py b/src/sage/categories/examples/semigroups.py index 6aceee5fe13..49b5bd164f6 100644 --- a/src/sage/categories/examples/semigroups.py +++ b/src/sage/categories/examples/semigroups.py @@ -70,7 +70,7 @@ class LeftZeroSemigroup(UniqueRepresentation, Parent): """ def __init__(self): r""" - The left zero semigroup + The left zero semigroup. EXAMPLES:: @@ -85,18 +85,16 @@ def __init__(self): def _repr_(self): r""" - EXAMPLES:: sage: Semigroups().example()._repr_() 'An example of a semigroup: the left zero semigroup' - """ return "An example of a semigroup: the left zero semigroup" def product(self, x, y): r""" - Returns the product of ``x`` and ``y`` in the semigroup, as per + Return the product of ``x`` and ``y`` in the semigroup, as per :meth:`Semigroups.ParentMethods.product`. EXAMPLES:: @@ -106,7 +104,6 @@ def product(self, x, y): 'hello' sage: S(3)*S(1)*S(2) 3 - """ assert x in self assert y in self @@ -114,25 +111,23 @@ def product(self, x, y): def an_element(self): r""" - Returns an element of the semigroup. + Return an element of the semigroup. EXAMPLES:: sage: Semigroups().example().an_element() 42 - """ return self(42) def some_elements(self): r""" - Returns a list of some elements of the semigroup. + Return a list of some elements of the semigroup. EXAMPLES:: sage: Semigroups().example().some_elements() [3, 42, 'a', 3.4, 'raton laveur'] - """ return [self(i) for i in [3, 42, "a", 3.4, "raton laveur"]] @@ -149,7 +144,6 @@ def is_idempotent(self): True sage: S(17).is_idempotent() True - """ return True @@ -186,7 +180,7 @@ def __init__(self, alphabet=('a','b','c','d')): INPUT: - - ``alphabet`` -- a tuple of strings: the generators of the semigroup + - ``alphabet`` -- tuple of strings; the generators of the semigroup EXAMPLES:: @@ -209,13 +203,12 @@ def _repr_(self): sage: from sage.categories.examples.semigroups import FreeSemigroup sage: FreeSemigroup(('a','b','c'))._repr_() "An example of a semigroup: the free semigroup generated by ('a', 'b', 'c')" - """ return "An example of a semigroup: the free semigroup generated by %s" % (self.alphabet,) def product(self, x, y): r""" - Returns the product of ``x`` and ``y`` in the semigroup, as per + Return the product of ``x`` and ``y`` in the semigroup, as per :meth:`Semigroups.ParentMethods.product`. EXAMPLES:: @@ -223,7 +216,6 @@ def product(self, x, y): sage: F = Semigroups().example('free') sage: F.an_element() * F('a')^5 'abcdaaaaa' - """ assert x in self assert y in self @@ -232,27 +224,25 @@ def product(self, x, y): @cached_method def semigroup_generators(self): r""" - Returns the generators of the semigroup. + Return the generators of the semigroup. EXAMPLES:: sage: F = Semigroups().example('free') sage: F.semigroup_generators() Family ('a', 'b', 'c', 'd') - """ return Family([self(i) for i in self.alphabet]) def an_element(self): r""" - Returns an element of the semigroup. + Return an element of the semigroup. EXAMPLES:: sage: F = Semigroups().example('free') sage: F.an_element() 'abcd' - """ return self(''.join(self.alphabet)) @@ -262,7 +252,7 @@ def _element_constructor_(self, x): INPUT: - - ``x`` -- a string + - ``x`` -- string EXAMPLES:: @@ -288,7 +278,6 @@ def _element_constructor_(self, x): sage: S = Semigroups().Subquotients().example() sage: type(S._element_constructor_(17)) - """ for a in x: assert a in self.alphabet @@ -303,7 +292,7 @@ class Element(ElementWrapper): class QuotientOfLeftZeroSemigroup(UniqueRepresentation, Parent): r""" - Example of a quotient semigroup + Example of a quotient semigroup. EXAMPLES:: @@ -368,7 +357,6 @@ def _element_constructor_(self, x): sage: S = Semigroups().Subquotients().example() sage: type(S._element_constructor_(17)) - """ return self.retract(self.ambient()(x)) @@ -405,20 +393,18 @@ def _repr_(self): sage: Semigroups().Subquotients().example()._repr_() 'An example of a (sub)quotient semigroup: a quotient of the left zero semigroup' - """ return "An example of a (sub)quotient semigroup: a quotient of the left zero semigroup" def ambient(self): r""" - Returns the ambient semigroup. + Return the ambient semigroup. EXAMPLES:: sage: S = Semigroups().Subquotients().example() sage: S.ambient() An example of a semigroup: the left zero semigroup - """ return Semigroups().example() @@ -428,7 +414,7 @@ def lift(self, x): INPUT: - - ``x`` -- an element of ``self``. + - ``x`` -- an element of ``self`` OUTPUT: @@ -447,14 +433,13 @@ def lift(self, x): 100 sage: S.lift(S(y)) 42 - """ assert x in self return x.value def the_answer(self): r""" - Returns the Answer to Life, the Universe, and Everything as an + Return the Answer to Life, the Universe, and Everything as an element of this semigroup. EXAMPLES:: @@ -462,48 +447,43 @@ def the_answer(self): sage: S = Semigroups().Subquotients().example() sage: S.the_answer() 42 - """ return self.retract(self.ambient()(42)) def an_element(self): r""" - Returns an element of the semigroup. + Return an element of the semigroup. EXAMPLES:: sage: S = Semigroups().Subquotients().example() sage: S.an_element() 42 - """ return self.the_answer() def some_elements(self): r""" - Returns a list of some elements of the semigroup. + Return a list of some elements of the semigroup. EXAMPLES:: sage: S = Semigroups().Subquotients().example() sage: S.some_elements() [1, 2, 3, 8, 42, 42] - """ return [self.retract(self.ambient()(i)) for i in [1, 2, 3, 8, 42, 100]] def retract(self, x): r""" - Returns the retract ``x`` onto an element of this semigroup. + Return the retract ``x`` onto an element of this semigroup. INPUT: - - ``x`` -- an element of the ambient semigroup (``self.ambient()``). - - OUTPUT: + - ``x`` -- an element of the ambient semigroup (``self.ambient()``) - - an element of ``self``. + OUTPUT: an element of ``self`` EXAMPLES:: @@ -520,7 +500,6 @@ def retract(self, x): sage: S.retract(L(171)) in S True - """ from sage.rings.integer_ring import ZZ assert x in self.ambient() and x.value in ZZ @@ -535,7 +514,7 @@ class Element(ElementWrapper): class IncompleteSubquotientSemigroup(UniqueRepresentation,Parent): def __init__(self, category=None): r""" - An incompletely implemented subquotient semigroup, for testing purposes + An incompletely implemented subquotient semigroup, for testing purposes. EXAMPLES:: @@ -587,14 +566,13 @@ def __init__(self, category=None): def ambient(self): r""" - Returns the ambient semigroup. + Return the ambient semigroup. EXAMPLES:: sage: S = Semigroups().Subquotients().example() sage: S.ambient() An example of a semigroup: the left zero semigroup - """ return Semigroups().example() diff --git a/src/sage/categories/examples/semigroups_cython.pyx b/src/sage/categories/examples/semigroups_cython.pyx index 4f7a6990586..3c7f28777f5 100644 --- a/src/sage/categories/examples/semigroups_cython.pyx +++ b/src/sage/categories/examples/semigroups_cython.pyx @@ -128,7 +128,7 @@ cdef class LeftZeroSemigroupElement(Element): class LeftZeroSemigroup(LeftZeroSemigroupPython): r""" - An example of semigroup + An example of semigroup. This class illustrates a minimal implementation of a semi-group where the element class is an extension type, and still gets code diff --git a/src/sage/categories/examples/sets_cat.py b/src/sage/categories/examples/sets_cat.py index 30d63ec9c73..003a4b04a5f 100644 --- a/src/sage/categories/examples/sets_cat.py +++ b/src/sage/categories/examples/sets_cat.py @@ -106,7 +106,7 @@ def _repr_(self): def an_element(self): """ - Implements :meth:`Sets.ParentMethods.an_element`. + Implement :meth:`Sets.ParentMethods.an_element`. TESTS:: @@ -186,7 +186,7 @@ def _repr_(self): def an_element(self): """ - Implements :meth:`Sets.ParentMethods.an_element`. + Implement :meth:`Sets.ParentMethods.an_element`. TESTS:: @@ -200,7 +200,7 @@ def an_element(self): def _element_constructor_(self, i): """ - Constructs an element of self from an integer, testing that + Construct an element of ``self`` from an integer, testing that this integer is indeed prime. EXAMPLES:: @@ -221,7 +221,7 @@ def _element_constructor_(self, i): @abstract_method def _from_integer_(self, i): """ - Fast construction of an element of self from an integer. + Fast construction of an element of ``self`` from an integer. No prime checking is performed. To be defined. diff --git a/src/sage/categories/examples/with_realizations.py b/src/sage/categories/examples/with_realizations.py index 4a4896026e7..b3b27d87d2f 100644 --- a/src/sage/categories/examples/with_realizations.py +++ b/src/sage/categories/examples/with_realizations.py @@ -25,7 +25,7 @@ class SubsetAlgebra(UniqueRepresentation, Parent): r""" - An example of parent endowed with several realizations + An example of parent endowed with several realizations. We consider an algebra `A(S)` whose bases are indexed by the subsets `s` of a given set `S`. We consider three natural basis of @@ -121,7 +121,6 @@ class SubsetAlgebra(UniqueRepresentation, Parent): sage: (1 + Out[1]) * In[2,3] Out[{}] + 2*Out[{1}] + 2*Out[{2}] + 2*Out[{3}] + 2*Out[{1, 2}] + 2*Out[{1, 3}] + 4*Out[{2, 3}] + 4*Out[{1, 2, 3}] - """ def __init__(self, R, S): @@ -202,7 +201,7 @@ def __init__(self, R, S): def a_realization(self): r""" - Returns the default realization of ``self`` + Return the default realization of ``self``. EXAMPLES:: @@ -257,7 +256,7 @@ def indices_key(self, x): def supsets(self, set): r""" - Returns all the subsets of `S` containing ``set`` + Return all the subsets of `S` containing ``set``. INPUT: @@ -363,7 +362,7 @@ def _repr_(self): @cached_method def one(self): r""" - Returns the unit of this algebra. + Return the unit of this algebra. This default implementation takes the unit in the fundamental basis, and coerces it in ``self``. @@ -382,7 +381,7 @@ def one(self): class Fundamental(CombinatorialFreeModule, BindableClass): r""" - The Subset algebra, in the fundamental basis + The Subset algebra, in the fundamental basis. INPUT: @@ -436,7 +435,7 @@ def product_on_basis(self, left, right): def one_basis(self): r""" - Returns the index of the basis element which is equal to '1'. + Return the index of the basis element which is equal to '1'. EXAMPLES:: @@ -458,7 +457,7 @@ def one_basis(self): class In(CombinatorialFreeModule, BindableClass): r""" - The Subset Algebra, in the ``In`` basis + The Subset Algebra, in the ``In`` basis. INPUT: @@ -501,7 +500,7 @@ def __init__(self, A): class Out(CombinatorialFreeModule, BindableClass): r""" - The Subset Algebra, in the `Out` basis + The Subset Algebra, in the `Out` basis. INPUT: diff --git a/src/sage/categories/facade_sets.py b/src/sage/categories/facade_sets.py index ecb32a25835..e832068fa97 100644 --- a/src/sage/categories/facade_sets.py +++ b/src/sage/categories/facade_sets.py @@ -17,13 +17,13 @@ class FacadeSets(CategoryWithAxiom): def example(self, choice='subset'): r""" - Returns an example of facade set, as per + Return an example of facade set, as per :meth:`Category.example() `. INPUT: - - ``choice`` -- 'union' or 'subset' (default: 'subset'). + - ``choice`` -- 'union' or 'subset' (default: ``'subset'``) EXAMPLES:: @@ -46,14 +46,14 @@ class ParentMethods: def _element_constructor_(self, element): """ - Coerce ``element`` into ``self`` + Coerce ``element`` into ``self``. INPUT: - ``element`` -- any object This default implementation returns ``element`` if - ``self`` is a facade for ``parent(element)`. Otherwise it + ``self`` is a facade for ``parent(element)``. Otherwise it attempts in turn to coerce ``element`` into each parent ``self`` is a facade for. @@ -106,12 +106,12 @@ def _element_constructor_(self, element): def facade_for(self): """ - Returns the parents this set is a facade for + Return the parents this set is a facade for. This default implementation assumes that ``self`` has an attribute ``_facade_for``, typically initialized by :meth:`Parent.__init__`. If the attribute is not present, the method - raises a NotImplementedError. + raises a :exc:`NotImplementedError`. EXAMPLES:: @@ -138,7 +138,7 @@ def facade_for(self): def is_parent_of(self, element): """ - Returns whether ``self`` is the parent of ``element`` + Return whether ``self`` is the parent of ``element``. INPUT: @@ -183,7 +183,7 @@ def is_parent_of(self, element): def __contains__(self, element): """ - Membership testing + Membership testing. Returns whether ``element`` is in one of the parents ``self`` is a facade for. @@ -212,7 +212,7 @@ def _an_element_(self): For each parent ``self`` is a facade for, this default implementation tries the method ``an_element`` until it finds an element in ``self``. If none is found, this raises a - :class:`NotImplementedError`. + :exc:`NotImplementedError`. EXAMPLES:: diff --git a/src/sage/categories/fields.py b/src/sage/categories/fields.py index 1a069f4d5e9..33a86e33244 100644 --- a/src/sage/categories/fields.py +++ b/src/sage/categories/fields.py @@ -27,7 +27,7 @@ class Fields(CategoryWithAxiom): """ The category of (commutative) fields, i.e. commutative rings where - all non-zero elements have multiplicative inverses + all nonzero elements have multiplicative inverses EXAMPLES:: @@ -125,7 +125,6 @@ def __contains__(self, x): sage: len([X for X in gc.get_objects() ....: if isinstance(X, sage.rings.finite_rings.integer_mod_ring.IntegerModRing_generic)]) - n 0 - """ from sage.rings.ring import _is_Field try: @@ -160,13 +159,12 @@ def _contains_helper(cls): True sage: F._contains_helper(Q) True - """ return Category_contains_method_by_parent_class(cls()) def _call_(self, x): """ - Construct a field from the data in ``x`` + Construct a field from the data in ``x``. EXAMPLES:: @@ -197,7 +195,7 @@ class ParentMethods: def is_field( self, proof=True ): r""" - Returns True as ``self`` is a field. + Return ``True`` as ``self`` is a field. EXAMPLES:: @@ -413,7 +411,6 @@ def is_perfect(self): True sage: FunctionField(GF(2), 'x').is_perfect() False - """ if self.characteristic() == 0: return True @@ -452,7 +449,7 @@ def _test_characteristic_fields(self, **options): def fraction_field(self): r""" - Returns the *fraction field* of ``self``, which is ``self``. + Return the *fraction field* of ``self``, which is ``self``. EXAMPLES:: @@ -470,7 +467,7 @@ def _squarefree_decomposition_univariate_polynomial(self, f): INPUT: - - ``f`` -- a univariate non-zero polynomial over this field + - ``f`` -- a univariate nonzero polynomial over this field ALGORITHM: For rings of characteristic zero, we use the algorithm described in [Yun1976]_. Other fields may provide their own @@ -520,7 +517,7 @@ def _squarefree_decomposition_univariate_polynomial(self, f): def vector_space(self, *args, **kwds): r""" - Gives an isomorphism of this field with a vector space over a subfield. + Give an isomorphism of this field with a vector space over a subfield. This method is an alias for ``free_module``, which may have more documentation. @@ -590,7 +587,7 @@ def quo_rem(self, other): def is_unit( self ): r""" - Returns True if ``self`` has a multiplicative inverse. + Return ``True`` if ``self`` has a multiplicative inverse. EXAMPLES:: @@ -749,7 +746,7 @@ def xgcd(self, other): sage: GF(5)(0).xgcd(GF(5)(0)) (0, 0, 0) - The xgcd of non-zero floating point numbers will be a triple of + The xgcd of nonzero floating point numbers will be a triple of floating points. But if the input are two integral floating points the result is a floating point version of the standard gcd on `\ZZ`:: @@ -814,7 +811,7 @@ def inverse_of_unit(self): 1/2 Trying to invert the zero element typically raises a - :class:`ZeroDivisionError`:: + :exc:`ZeroDivisionError`:: sage: QQ(0).inverse_of_unit() Traceback (most recent call last): diff --git a/src/sage/categories/filtered_algebras_with_basis.py b/src/sage/categories/filtered_algebras_with_basis.py index 068aa37e52e..98795bdd08a 100644 --- a/src/sage/categories/filtered_algebras_with_basis.py +++ b/src/sage/categories/filtered_algebras_with_basis.py @@ -241,9 +241,7 @@ def induced_graded_map(self, other, f): - ``f`` -- a filtration-preserving linear map from ``self`` to ``other`` (can be given as a morphism or as a function) - OUTPUT: - - The graded linear map `\operatorname{gr} f`. + OUTPUT: the graded linear map `\operatorname{gr} f` EXAMPLES: diff --git a/src/sage/categories/filtered_modules_with_basis.py b/src/sage/categories/filtered_modules_with_basis.py index cb1df2f0bba..454f31e5070 100644 --- a/src/sage/categories/filtered_modules_with_basis.py +++ b/src/sage/categories/filtered_modules_with_basis.py @@ -159,7 +159,7 @@ def basis(self, d=None): over Integer Ring(i))_{i in Partitions} Checking this method on a filtered algebra. Note that this - will typically raise a :class:`NotImplementedError` when this + will typically raise a :exc:`NotImplementedError` when this feature is not implemented. :: sage: A = AlgebrasWithBasis(ZZ).Filtered().example() @@ -481,9 +481,7 @@ def induced_graded_map(self, other, f): - ``f`` -- a filtration-preserving linear map from ``self`` to ``other`` (can be given as a morphism or as a function) - OUTPUT: - - The graded linear map `\operatorname{gr} f`. + OUTPUT: the graded linear map `\operatorname{gr} f` EXAMPLES: diff --git a/src/sage/categories/finite_complex_reflection_groups.py b/src/sage/categories/finite_complex_reflection_groups.py index 20f03360322..c834ccbef21 100644 --- a/src/sage/categories/finite_complex_reflection_groups.py +++ b/src/sage/categories/finite_complex_reflection_groups.py @@ -731,8 +731,8 @@ def reflection_length(self, in_unitary_group=False): INPUT: - - ``in_unitary_group`` -- (default: ``False``) if ``True``, - the reflection length is computed in the unitary group + - ``in_unitary_group`` -- boolean (default: ``False``); if + ``True``, the reflection length is computed in the unitary group which is the dimension of the move space of ``self`` EXAMPLES:: @@ -838,14 +838,14 @@ def absolute_order_ideal(self, gens=None, Otherwise, the standard Coxeter element is used as unique maximal element. - - ``in_unitary_group`` (default:``True``) determines the + - ``in_unitary_group`` -- (default: ``True``) determines the length function used to compute the order. For real groups, both possible orders coincide, and for complex non-real groups, the order in the unitary group is much faster to compute. - - ``return_lengths`` (default:``False``) whether or not - to also return the lengths of the elements. + - ``return_lengths`` -- (default: ``False``) whether or not + to also return the lengths of the elements EXAMPLES:: @@ -920,8 +920,8 @@ def noncrossing_partition_lattice(self, c=None, L=None, of ``self`` is given, it is used as the underlying set (only cover relations are checked). - - ``in_unitary_group`` -- (default: ``False``) if ``False``, the - relation is given by `\sigma \leq \tau` if + - ``in_unitary_group`` -- boolean (default: ``False``); if + ``False``, the relation is given by `\sigma \leq \tau` if `l_R(\sigma) + l_R(\sigma^{-1}\tau) = l_R(\tau)`; if ``True``, the relation is given by `\sigma \leq \tau` if `\dim(\mathrm{Fix}(\sigma)) + \dim(\mathrm{Fix}(\sigma^{-1}\tau)) @@ -980,7 +980,7 @@ def noncrossing_partition_lattice(self, c=None, L=None, def generalized_noncrossing_partitions(self, m, c=None, positive=False): r""" - Return the set of all chains of length ``m`` in the + Return the set of all chains of length `m` in the noncrossing partition lattice of ``self``, see :meth:`noncrossing_partition_lattice`. @@ -990,11 +990,12 @@ def generalized_noncrossing_partitions(self, m, c=None, positive=False): INPUT: - - ``c`` -- (default: ``None``) if an element ``c`` in ``self`` + - ``c`` -- (default: ``None``) if an element `c` in ``self`` is given, it is used as the maximal element in the interval - - ``positive`` -- (default: ``False``) if ``True``, only those - generalized noncrossing partitions of full support are returned + - ``positive`` -- boolean (default: ``False``); if ``True``, + only those generalized noncrossing partitions of full support + are returned EXAMPLES:: @@ -1067,8 +1068,8 @@ def absolute_poset(self, in_unitary_group=False): INPUT: - - ``in_unitary_group`` -- (default: ``False``) if ``False``, - the relation is given by ``\sigma \leq \tau`` if + - ``in_unitary_group`` -- boolean (default: ``False``); if + ``False``, the relation is given by ``\sigma \leq \tau`` if `l_R(\sigma) + l_R(\sigma^{-1}\tau) = l_R(\tau)` If ``True``, the relation is given by `\sigma \leq \tau` if `\dim(\mathrm{Fix}(\sigma)) + \dim(\mathrm{Fix}(\sigma^{-1}\tau)) @@ -1332,7 +1333,7 @@ def rational_catalan_number(self, p, polynomial=False): INPUT: - - ``polynomial`` -- optional boolean (default ``False``) + - ``polynomial`` -- boolean (default: ``False``); if ``True``, return instead the `q`-analogue as a polynomial in `q` @@ -1388,12 +1389,11 @@ def fuss_catalan_number(self, m, positive=False, INPUT: - - ``positive`` -- optional boolean (default ``False``) - if ``True``, return instead the positive Fuss-Catalan - number - - ``polynomial`` -- optional boolean (default ``False``) - if ``True``, return instead the `q`-analogue as a - polynomial in `q` + - ``positive`` -- boolean (default: ``False``); if + ``True``, return instead the positive Fuss-Catalan number + - ``polynomial`` -- boolean (default: ``False``); if + ``True``, return instead the `q`-analogue as a polynomial + in `q` See [Ar2006]_ for further information. @@ -1465,12 +1465,11 @@ def catalan_number(self, positive=False, polynomial=False): INPUT: - - ``positive`` -- optional boolean (default ``False``) - if ``True``, return instead the positive Catalan - number - - ``polynomial`` -- optional boolean (default ``False``) - if ``True``, return instead the `q`-analogue as a - polynomial in `q` + - ``positive`` -- boolean (default: ``False``); if + ``True``, return instead the positive Catalan number + - ``polynomial`` -- boolean (default: ``False``); if + ``True``, return instead the `q`-analogue as a polynomial + in `q` .. NOTE:: diff --git a/src/sage/categories/finite_coxeter_groups.py b/src/sage/categories/finite_coxeter_groups.py index 2095783728b..0ed2e0b5994 100644 --- a/src/sage/categories/finite_coxeter_groups.py +++ b/src/sage/categories/finite_coxeter_groups.py @@ -113,8 +113,8 @@ def long_element(self, index_set=None, as_word=False): - ``index_set`` -- a subset (as a list or iterable) of the nodes of the Dynkin diagram; (default: all of them) - - ``as_word`` -- boolean (default ``False``). If ``True``, then - return instead a reduced decomposition of the longest element. + - ``as_word`` -- boolean (default: ``False``); if ``True``, then + return instead a reduced decomposition of the longest element Should this method be called maximal_element? longest_element? @@ -394,12 +394,12 @@ def codegrees(self): return tuple(d - 2 for d in self.degrees()) @cached_method - def weak_poset(self, side="right", facade=False): + def weak_poset(self, side='right', facade=False): """ INPUT: - - ``side`` -- "left", "right", or "twosided" (default: "right") - - ``facade`` -- a boolean (default: ``False``) + - ``side`` -- "left", "right", or "twosided" (default: ``'right'``) + - ``facade`` -- boolean (default: ``False``) Returns the left (resp. right) poset for weak order. In this poset, `u` is smaller than `v` if some reduced word @@ -479,7 +479,7 @@ def weak_poset(self, side="right", facade=False): from sage.combinat.posets.posets import Poset from sage.combinat.posets.lattices import LatticePoset if side == "twosided": - covers = tuple([u, v] for u in self for v in u.upper_covers(side="left") + u.upper_covers(side="right")) + covers = tuple([u, v] for u in self for v in u.upper_covers(side='left') + u.upper_covers(side='right')) return Poset((self, covers), cover_relations=True, facade=facade) covers = tuple([u, v] for u in self for v in u.upper_covers(side=side)) @@ -499,7 +499,7 @@ def inversion_sequence(self, word): INPUT: - ``word`` -- a word in the indices of the simple - generators of ``self``. + generators of ``self`` EXAMPLES:: @@ -511,7 +511,6 @@ def inversion_sequence(self, word): sage: [t.reduced_word() for t in CoxeterGroup(["A",3]).inversion_sequence([2,1,3,2,1,3])] [[2], [1, 2, 1], [2, 3, 2], [1, 2, 3, 2, 1], [3], [1]] - """ return [self.from_reduced_word(word[:i+1]+list(reversed(word[:i]))) for i in range(len(word))] @@ -552,12 +551,12 @@ def m_cambrian_lattice(self, c, m=1, on_roots=False): INPUT: - - `c` -- a Coxeter element of ``self`` (as a tuple, or + - ``c`` -- a Coxeter element of ``self`` (as a tuple, or as an element of ``self``) - - `m` -- a positive integer (default: 1) + - ``m`` -- positive integer (default: 1) - - ``on_roots`` (default: ``False``) -- if + - ``on_roots`` -- boolean (default: ``False``); if ``on_roots`` is ``True``, the lattice is realized on roots rather than on reflections. In order for this to work, the ElementMethod ``reflection_to_root`` must be @@ -637,14 +636,14 @@ def cambrian_lattice(self, c, on_roots=False): See :arxiv:`1503.00710` and :arxiv:`math/0611106`. Delta sequences are certain 2-colored minimal factorizations - of ``c`` into reflections. + of `c` into reflections. INPUT: - ``c`` -- a standard Coxeter element in ``self`` (as a tuple, or as an element of ``self``) - - ``on_roots`` (default: ``False``) -- if + - ``on_roots`` -- boolean (default: ``False``); if ``on_roots`` is ``True``, the lattice is realized on roots rather than on reflections. In order for this to work, the ElementMethod ``reflection_to_root`` must be @@ -678,7 +677,7 @@ def is_real(self): def permutahedron(self, point=None, base_ring=None): r""" - Return the permutahedron of ``self``, + Return the permutahedron of ``self``. This is the convex hull of the point ``point`` in the weight basis under the action of ``self`` on the underlying vector @@ -690,9 +689,9 @@ def permutahedron(self, point=None, base_ring=None): INPUT: - - ``point`` -- optional, a point given by its coordinates in - the weight basis (default is `(1, 1, 1, \ldots)`) - - ``base_ring`` -- optional, the base ring of the polytope + - ``point`` -- (optional) a point given by its coordinates in + the weight basis (default: `(1, 1, 1, \ldots)`) + - ``base_ring`` -- (optional) the base ring of the polytope .. NOTE:: @@ -741,7 +740,6 @@ def permutahedron(self, point=None, base_ring=None): W = CoxeterGroup(['I',7]) p = W.permutahedron() sphinx_plot(p) - """ n = self.one().canonical_matrix().rank() weights = self.fundamental_weights() @@ -801,7 +799,7 @@ def coxeter_poset(self): 3 sage: # optional - gap3 - sage: W = CoxeterGroup(['H', 3], implementation="permutation") + sage: W = CoxeterGroup(['H', 3], implementation='permutation') sage: P = W.coxeter_poset() sage: P Finite meet-semilattice containing 363 elements @@ -874,7 +872,7 @@ def coxeter_complex(self): {0: 0, 1: 0, 2: Z} sage: # optional - gap3 - sage: W = CoxeterGroup(['H', 3], implementation="permutation") + sage: W = CoxeterGroup(['H', 3], implementation='permutation') sage: C = W.coxeter_complex() sage: C Simplicial complex with 62 vertices and 120 facets @@ -943,7 +941,7 @@ def absolute_length(self): @cached_in_parent_method def bruhat_upper_covers(self): r""" - Returns all the elements that cover ``self`` in Bruhat order. + Return all the elements that cover ``self`` in Bruhat order. EXAMPLES:: diff --git a/src/sage/categories/finite_crystals.py b/src/sage/categories/finite_crystals.py index 97fd31c1968..d1a436f4d6c 100644 --- a/src/sage/categories/finite_crystals.py +++ b/src/sage/categories/finite_crystals.py @@ -76,7 +76,7 @@ def extra_super_categories(self): def example(self, n=3): """ - Returns an example of highest weight crystals, as per + Return an example of highest weight crystals, as per :meth:`Category.example`. EXAMPLES:: diff --git a/src/sage/categories/finite_dimensional_algebras_with_basis.py b/src/sage/categories/finite_dimensional_algebras_with_basis.py index 4df8a265f06..03ae127de8f 100644 --- a/src/sage/categories/finite_dimensional_algebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_algebras_with_basis.py @@ -74,9 +74,7 @@ def radical_basis(self): characteristic `p` in which we can compute `x^{1/p}` [FR1985]_, [Eb1989]_. - OUTPUT: - - - a list of elements of ``self``. + OUTPUT: list of elements of ``self`` .. SEEALSO:: :meth:`radical`, :class:`Algebras.Semisimple` @@ -348,9 +346,7 @@ def center_basis(self): r""" Return a basis of the center of ``self``. - OUTPUT: - - - a list of elements of ``self``. + OUTPUT: list of elements of ``self`` .. SEEALSO:: :meth:`center` @@ -656,7 +652,7 @@ def idempotent_lift(self, x): INPUT: - - `x` -- an element of `A` that projects on an idempotent + - ``x`` -- an element of `A` that projects on an idempotent `\overline x` of the semisimple quotient of `A`. Alternatively one may give as input the idempotent `\overline{x}`, in which case some lift thereof will be @@ -703,7 +699,7 @@ def cartan_invariants_matrix(self): r""" Return the Cartan invariants matrix of the algebra. - OUTPUT: a matrix of non negative integers + OUTPUT: a matrix of nonnegative integers Let `A` be this finite dimensional algebra and `(S_i)_{i\in I}` be representatives of the right simple @@ -718,7 +714,7 @@ def cartan_invariants_matrix(self): `S_i=\operatorname{top} P^R_i`. The *Cartan invariant matrix* `(C_{i,j})_{i,j\in I}` is a - matrix of non negative integers that encodes much of the + matrix of nonnegative integers that encodes much of the representation theory of `A`; namely: - `C_{i,j}` counts how many times `S_i^*\otimes S_j` @@ -851,9 +847,9 @@ def isotypic_projective_modules(self, side='left'): INPUT: - - ``side`` -- 'left' or 'right' (default: 'left') + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'left'``) - OUTPUT: a list of subspaces of ``self``. + OUTPUT: list of subspaces of ``self`` EXAMPLES:: @@ -862,7 +858,7 @@ def isotypic_projective_modules(self, side='left'): An example of a finite dimensional algebra with basis: the path algebra of the Kronecker quiver (containing the arrows a:x->y and b:x->y) over Rational Field - sage: Q = A.isotypic_projective_modules(side="left"); Q + sage: Q = A.isotypic_projective_modules(side='left'); Q [Free module generated by {0} over Rational Field, Free module generated by {0, 1, 2} over Rational Field] sage: [[x.lift() for x in Qi.basis()] @@ -895,7 +891,7 @@ def peirce_summand(self, ei, ej): - ``ei``, ``ej`` -- two idempotents of `A` - OUTPUT: `e_i A e_j`, as a subspace of `A`. + OUTPUT: `e_i A e_j`, as a subspace of `A` .. SEEALSO:: @@ -963,13 +959,13 @@ def peirce_decomposition(self, idempotents=None, check=True): INPUT: - - ``idempotents`` -- a list of orthogonal idempotents + - ``idempotents`` -- list of orthogonal idempotents `(e_i)_{i=0,\ldots,n}` of the algebra that sum to `1` (default: the idempotents returned by :meth:`orthogonal_idempotents_central_mod_radical`) - - ``check`` -- (default: ``True``) whether to check that the - idempotents are indeed orthogonal and idempotent and + - ``check`` -- boolean (default: ``True``); whether to check that + the idempotents are indeed orthogonal and idempotent and sum to `1` OUTPUT: @@ -1039,7 +1035,7 @@ def is_identity_decomposition_into_orthogonal_idempotents(self, l): INPUT: - - ``l`` -- a list or iterable of elements of ``self`` + - ``l`` -- list or iterable of elements of ``self`` EXAMPLES:: @@ -1175,7 +1171,7 @@ def to_matrix(self, base_ring=None, action=operator.mul, side='left'): - ``base_ring`` -- the base ring for the matrix to be constructed - ``action`` -- a bivariate function (default: :func:`operator.mul`) - - ``side`` -- 'left' or 'right' (default: 'left') + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'left'``) EXAMPLES:: @@ -1196,7 +1192,7 @@ def to_matrix(self, base_ring=None, action=operator.mul, side='left'): [0 1 0 0 0 0] [0 0 0 0 0 1] [0 0 0 0 1 0] - sage: a.to_matrix(base_ring=RDF, side="left") + sage: a.to_matrix(base_ring=RDF, side='left') [0.0 0.0 1.0 0.0 0.0 0.0] [0.0 0.0 0.0 0.0 1.0 0.0] [1.0 0.0 0.0 0.0 0.0 0.0] diff --git a/src/sage/categories/finite_dimensional_bialgebras_with_basis.py b/src/sage/categories/finite_dimensional_bialgebras_with_basis.py index 321d98568e3..c0e25dec7fe 100644 --- a/src/sage/categories/finite_dimensional_bialgebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_bialgebras_with_basis.py @@ -13,7 +13,7 @@ def FiniteDimensionalBialgebrasWithBasis(base_ring): """ - The category of finite dimensional bialgebras with a distinguished basis + The category of finite dimensional bialgebras with a distinguished basis. EXAMPLES:: diff --git a/src/sage/categories/finite_dimensional_coalgebras_with_basis.py b/src/sage/categories/finite_dimensional_coalgebras_with_basis.py index 520177b0e8f..489d943f75c 100644 --- a/src/sage/categories/finite_dimensional_coalgebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_coalgebras_with_basis.py @@ -13,7 +13,7 @@ def FiniteDimensionalCoalgebrasWithBasis(base_ring): """ - The category of finite dimensional coalgebras with a distinguished basis + The category of finite dimensional coalgebras with a distinguished basis. EXAMPLES:: diff --git a/src/sage/categories/finite_dimensional_graded_lie_algebras_with_basis.py b/src/sage/categories/finite_dimensional_graded_lie_algebras_with_basis.py index fa53cb36ed2..fccea88f2fb 100644 --- a/src/sage/categories/finite_dimensional_graded_lie_algebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_graded_lie_algebras_with_basis.py @@ -48,11 +48,11 @@ class FiniteDimensionalGradedLieAlgebrasWithBasis(CategoryWithAxiom_over_base_ri class ParentMethods: def _test_grading(self, **options): r""" - Tests that the Lie bracket respects the grading. + Test that the Lie bracket respects the grading. INPUT: - - ``options`` -- any keyword arguments accepted by :meth:`_tester`. + - ``options`` -- any keyword arguments accepted by :meth:`_tester` EXAMPLES:: @@ -138,7 +138,7 @@ class Stratified(CategoryWithAxiom_over_base_ring): class ParentMethods: def _test_generated_by_degree_one(self, **options): r""" - Tests that the Lie algebra is generated by the homogeneous + Test that the Lie algebra is generated by the homogeneous component of degree one. INPUT: diff --git a/src/sage/categories/finite_dimensional_lie_algebras_with_basis.py b/src/sage/categories/finite_dimensional_lie_algebras_with_basis.py index 39363f5fb18..270ea045898 100644 --- a/src/sage/categories/finite_dimensional_lie_algebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_lie_algebras_with_basis.py @@ -378,8 +378,8 @@ def structure_coefficients(self, include_zeros=False): INPUT: - - ``include_zeros`` -- (default: ``False``) if ``True``, then - include the `[x, y] = 0` pairs in the output + - ``include_zeros`` -- boolean (default: ``False``); if ``True``, + then include the `[x, y] = 0` pairs in the output OUTPUT: @@ -1007,7 +1007,7 @@ def subalgebra(self, *gens, **kwds): INPUT: - - ``gens`` -- a list of generators of the subalgebra + - ``gens`` -- list of generators of the subalgebra - ``category`` -- (optional) a subcategory of subobjects of finite dimensional Lie algebras with basis @@ -1048,7 +1048,7 @@ def ideal(self, *gens, **kwds): INPUT: - - ``gens`` -- a list of generators of the ideal + - ``gens`` -- list of generators of the ideal - ``category`` -- (optional) a subcategory of subobjects of finite dimensional Lie algebras with basis @@ -1131,7 +1131,7 @@ def quotient(self, I, names=None, category=None): INPUT: - ``I`` -- an ideal or a list of generators of the ideal - - ``names`` -- (optional) a string or a list of strings; + - ``names`` -- (optional) string or list of strings; names for the basis elements of the quotient. If ``names`` is a string, the basis will be named ``names_1``,...,``names_n``. @@ -1179,8 +1179,8 @@ def product_space(self, L, submodule=False): INPUT: - ``L`` -- a Lie subalgebra of ``self`` - - ``submodule`` -- (default: ``False``) if ``True``, then the - result is forced to be a submodule of ``self`` + - ``submodule`` -- boolean (default: ``False``); if ``True``, then + the result is forced to be a submodule of ``self`` EXAMPLES:: @@ -1359,8 +1359,8 @@ def lower_central_series(self, submodule=False): INPUT: - - ``submodule`` -- (default: ``False``) if ``True``, then the - result is given as submodules of ``self`` + - ``submodule`` -- boolean (default: ``False``); if ``True``, then + the result is given as submodules of ``self`` We define the lower central series of a Lie algebra `\mathfrak{g}` recursively by `\mathfrak{g}_0 := \mathfrak{g}` and @@ -1638,9 +1638,9 @@ def chevalley_eilenberg_complex(self, M=None, dual=False, sparse=True, ncpus=Non are matrices representing a Lie algebra homomorphism defining the representation - - ``dual`` -- (default: ``False``) if ``True``, causes + - ``dual`` -- boolean (default: ``False``); if ``True``, causes the dual of the complex to be computed - - ``sparse`` -- (default: ``True``) whether to use sparse + - ``sparse`` -- boolean (default: ``True``); whether to use sparse or dense matrices - ``ncpus`` -- (optional) how many cpus to use @@ -1877,7 +1877,7 @@ def homology(self, deg=None, M=None, sparse=True, ncpus=None): - ``deg`` -- the degree of the homology (optional) - ``M`` -- (default: the trivial module) a right module of ``self`` - - ``sparse`` -- (default: ``True``) whether to use sparse + - ``sparse`` -- boolean (default: ``True``); whether to use sparse matrices for the Chevalley-Eilenberg chain complex - ``ncpus`` -- (optional) how many cpus to use when computing the Chevalley-Eilenberg chain complex @@ -1945,7 +1945,7 @@ def cohomology(self, deg=None, M=None, sparse=True, ncpus=None): - ``deg`` -- the degree of the homology (optional) - ``M`` -- (default: the trivial module) a right module of ``self`` - - ``sparse`` -- (default: ``True``) whether to use sparse + - ``sparse`` -- boolean (default: ``True``); whether to use sparse matrices for the Chevalley-Eilenberg chain complex - ``ncpus`` -- (optional) how many cpus to use when computing the Chevalley-Eilenberg chain complex @@ -2041,7 +2041,7 @@ def morphism(self, on_generators, codomain=None, base_map=None, check=True): from the values of ``on_generators`` if not given - ``base_map`` -- a homomorphism from the base ring to something coercing into the codomain - - ``check`` -- (default: ``True``) boolean; if ``False`` the + - ``check`` -- boolean (default: ``True``); if ``False`` the values on the Lie brackets implied by ``on_generators`` will not be checked for contradictory values @@ -2234,11 +2234,12 @@ def casimir_element(self, order=2, UEA=None, force_generic=False, basis=False): - ``order`` -- (default: ``2``) the order of the Casimir element - ``UEA`` -- (optional) the universal enveloping algebra implementation to return the result in - - ``force_generic`` -- (default: ``False``) if ``True`` for the - quadratic order, then this uses the default algorithm; otherwise - this is ignored - - ``basis`` -- (default: ``False``) if ``True``, this returns a - basis of all Casimir elements of order ``order`` as a list + - ``force_generic`` -- boolean (default: ``False``); if ``True`` + for the quadratic order, then this uses the default algorithm + (otherwise this is ignored) + - ``basis`` -- boolean (default: ``False``); if ``True``, this + returns a basis of all Casimir elements of order ``order`` as a + list ALGORITHM: @@ -2445,12 +2446,12 @@ def faithful_representation(self, algorithm=None): sage: F = H2.faithful_representation(); F Faithful 16 dimensional representation of Heisenberg algebra of rank 2 over Rational Field - sage: M = H2.faithful_representation(algorithm="minimal"); M + sage: M = H2.faithful_representation(algorithm='minimal'); M Minimal faithful representation of Heisenberg algebra of rank 2 over Rational Field sage: M.dimension() 4 - sage: H2.faithful_representation(algorithm="invalid") + sage: H2.faithful_representation(algorithm='invalid') Traceback (most recent call last): ... ValueError: invalid algorithm 'invalid' diff --git a/src/sage/categories/finite_dimensional_modules_with_basis.py b/src/sage/categories/finite_dimensional_modules_with_basis.py index c5566fc0f20..ee5b6490346 100644 --- a/src/sage/categories/finite_dimensional_modules_with_basis.py +++ b/src/sage/categories/finite_dimensional_modules_with_basis.py @@ -21,7 +21,7 @@ class FiniteDimensionalModulesWithBasis(CategoryWithAxiom_over_base_ring): """ - The category of finite dimensional modules with a distinguished basis + The category of finite dimensional modules with a distinguished basis. EXAMPLES:: @@ -44,9 +44,7 @@ def gens(self) -> tuple: """ Return the generators of ``self``. - OUTPUT: - - A tuple containing the basis elements of ``self``. + OUTPUT: a tuple containing the basis elements of ``self`` EXAMPLES:: @@ -66,7 +64,7 @@ def annihilator(self, S, action=operator.mul, side='right', category=None): - ``action`` -- a function (default: :obj:`operator.mul`) - - ``side`` -- 'left' or 'right' (default: 'right') + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - ``category`` -- a category @@ -121,10 +119,10 @@ def annihilator(self, S, action=operator.mul, side='right', category=None): Taking annihilator is order reversing for inclusion:: sage: # needs sage.modules - sage: A = F.annihilator([]); A .rename("A") - sage: Ax = F.annihilator([x]); Ax .rename("Ax") - sage: Ay = F.annihilator([y]); Ay .rename("Ay") - sage: Axy = F.annihilator([x,y]); Axy.rename("Axy") + sage: A = F.annihilator([]); A .rename('A') + sage: Ax = F.annihilator([x]); Ax .rename('Ax') + sage: Ay = F.annihilator([y]); Ay .rename('Ay') + sage: Axy = F.annihilator([x,y]); Axy.rename('Axy') sage: P = Poset(([A, Ax, Ay, Axy], attrcall("is_submodule"))) # needs sage.graphs sage: sorted(P.cover_relations(), key=str) # needs sage.graphs [[Ax, A], [Axy, Ax], [Axy, Ay], [Ay, A]] @@ -143,8 +141,8 @@ def annihilator_basis(self, S, action=operator.mul, side='right'): - ``action`` -- a function (default: :obj:`operator.mul`) - - ``side`` -- 'left' or 'right' (default: 'right'): - on which side of ``self`` the elements of `S` acts. + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``): + on which side of ``self`` the elements of `S` acts See :meth:`annihilator` for the assumptions and definition of the annihilator. @@ -198,15 +196,15 @@ def annihilator_basis(self, S, action=operator.mul, side='right'): roles of `x` and `y`:: sage: # needs sage.graphs sage.modules - sage: F.annihilator_basis([y], side="left") + sage: F.annihilator_basis([y], side='left') (x, a, b) - sage: F.annihilator_basis([a], side="left") + sage: F.annihilator_basis([a], side='left') (x, a, b) - sage: F.annihilator_basis([b], side="left") + sage: F.annihilator_basis([b], side='left') (x, a, b) - sage: F.annihilator_basis([x], side="left") + sage: F.annihilator_basis([x], side='left') (y,) - sage: F.annihilator_basis([a + 3*b + 2*x], side="left") + sage: F.annihilator_basis([a + 3*b + 2*x], side='left') (-1/2*a - 3/2*b + y,) By specifying an inner product, this method can be used to @@ -310,9 +308,9 @@ def echelon_form(self, elements, row_reduced=False, order=None): INPUT: - - ``elements`` -- a list or finite iterable of elements of ``self`` - - ``row_reduced`` -- (default: ``False``) whether to compute the - basis for the row reduced echelon form + - ``elements`` -- list or finite iterable of elements of ``self`` + - ``row_reduced`` -- boolean (default: ``False``); whether to + compute the basis for the row reduced echelon form - ``order`` -- (optional) either something that can be converted into a tuple or a key function @@ -325,7 +323,7 @@ def echelon_form(self, elements, row_reduced=False, order=None): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x") + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x') sage: x = X.basis() sage: V = X.echelon_form([x[0]-x[1], x[0]-x[2], x[1]-x[2]]); V [x[0] - x[2], x[1] - x[2]] @@ -394,7 +392,7 @@ def echelon_form(self, elements, row_reduced=False, order=None): return ret def invariant_module(self, S, action=operator.mul, action_on_basis=None, - side="left", **kwargs): + side='left', **kwargs): r""" Return the submodule of ``self`` invariant under the action of ``S``. @@ -415,9 +413,7 @@ def invariant_module(self, S, action=operator.mul, action_on_basis=None, - ``action_on_basis`` -- (optional) define the action of ``S`` on the basis of ``self`` - OUTPUT: - - - :class:`~sage.modules.with_basis.invariant.FiniteDimensionalInvariantModule` + OUTPUT: :class:`~sage.modules.with_basis.invariant.FiniteDimensionalInvariantModule` EXAMPLES: @@ -485,7 +481,7 @@ def twisted_invariant_module(self, G, chi, INPUT: - ``G`` -- a finitely-generated group - - ``chi`` -- a list/tuple of character values or an instance of + - ``chi`` -- list/tuple of character values or an instance of :class:`~sage.groups.class_function.ClassFunction_gap` - ``action`` -- a function (default: :obj:`operator.mul`) - ``action_on_basis`` -- (optional) define the action of ``g`` @@ -493,9 +489,7 @@ def twisted_invariant_module(self, G, chi, - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``); which side of ``self`` the elements of ``S`` acts - OUTPUT: - - - :class:`~sage.modules.with_basis.invariant.FiniteDimensionalTwistedInvariantModule` + OUTPUT: :class:`~sage.modules.with_basis.invariant.FiniteDimensionalTwistedInvariantModule` EXAMPLES:: @@ -576,7 +570,7 @@ def _vector_(self, order=None): coerce=True, copy=False) class MorphismMethods: - def matrix(self, base_ring=None, side="left"): + def matrix(self, base_ring=None, side='left'): r""" Return the matrix of this morphism in the distinguished bases of the domain and codomain. @@ -586,7 +580,7 @@ def matrix(self, base_ring=None, side="left"): - ``base_ring`` -- a ring (default: ``None``, meaning the base ring of the codomain) - - ``side`` -- "left" or "right" (default: "left") + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'left'``) If ``side`` is "left", this morphism is considered as acting on the left; i.e. each column of the matrix @@ -609,7 +603,7 @@ def matrix(self, base_ring=None, side="left"): sage: phi.matrix() [1 2] [3 5] - sage: phi.matrix(side="right") + sage: phi.matrix(side='right') [1 3] [2 5] @@ -784,8 +778,8 @@ def __invert__(self): sage: # needs sage.modules sage: category = FiniteDimensionalModulesWithBasis(ZZ) - sage: X = CombinatorialFreeModule(ZZ, [1,2], category=category); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(ZZ, [3,4], category=category); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(ZZ, [1,2], category=category); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(ZZ, [3,4], category=category); Y.rename('Y'); y = Y.basis() sage: phi = X.module_morphism(on_basis={1: y[3] + 3*y[4], 2: 2*y[3] + 5*y[4]}.__getitem__, ....: codomain=Y, category=category) sage: psi = ~phi @@ -1069,6 +1063,5 @@ def extra_super_categories(self): sage: C.FiniteDimensional() Category of tensor products of finite dimensional modules with basis over Integer Ring - """ return [self.base_category()] diff --git a/src/sage/categories/finite_dimensional_nilpotent_lie_algebras_with_basis.py b/src/sage/categories/finite_dimensional_nilpotent_lie_algebras_with_basis.py index ae3a38d9dda..0d6cfd0f3a8 100644 --- a/src/sage/categories/finite_dimensional_nilpotent_lie_algebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_nilpotent_lie_algebras_with_basis.py @@ -52,7 +52,7 @@ class ParentMethods: def _test_nilpotency(self, **options): r""" - Tests that ``self`` is nilpotent and has the correct step. + Test that ``self`` is nilpotent and has the correct step. INPUT: @@ -75,7 +75,7 @@ def _test_nilpotency(self, **options): sage: L._test_nilpotency() Traceback (most recent call last): ... - AssertionError: final term of lower central series is non-zero + AssertionError: final term of lower central series is nonzero See the documentation for :class:`TestSuite` for more information. """ @@ -83,7 +83,7 @@ def _test_nilpotency(self, **options): lcs = self.lower_central_series(submodule=True) tester.assertEqual(lcs[-1].dimension(), 0, - msg="final term of lower central series is non-zero") + msg="final term of lower central series is nonzero") step = self.step() tester.assertEqual(len(lcs) - 1, step, diff --git a/src/sage/categories/finite_dimensional_semisimple_algebras_with_basis.py b/src/sage/categories/finite_dimensional_semisimple_algebras_with_basis.py index 2057b5c38de..83c0d6d17d8 100644 --- a/src/sage/categories/finite_dimensional_semisimple_algebras_with_basis.py +++ b/src/sage/categories/finite_dimensional_semisimple_algebras_with_basis.py @@ -18,7 +18,7 @@ class FiniteDimensionalSemisimpleAlgebrasWithBasis(CategoryWithAxiom_over_base_ring): """ - The category of finite dimensional semisimple algebras with a distinguished basis + The category of finite dimensional semisimple algebras with a distinguished basis. EXAMPLES:: @@ -45,9 +45,9 @@ def radical_basis(self, **keywords): r""" Return a basis of the Jacobson radical of this algebra. - - ``keywords`` -- for compatibility; ignored. + - ``keywords`` -- for compatibility; ignored - OUTPUT: the empty list since this algebra is semisimple. + OUTPUT: the empty list since this algebra is semisimple EXAMPLES:: @@ -121,12 +121,10 @@ def _orthogonal_decomposition(self, generators=None): INPUT: - - ``generators`` -- a list of generators of + - ``generators`` -- list of generators of ``self`` (default: the basis of ``self``) - OUTPUT: - - A list of quasi-idempotent elements of ``self``. + OUTPUT: list of quasi-idempotent elements of ``self`` Each quasi-idempotent `e` spans a one dimensional (non unital) subalgebra of @@ -146,7 +144,7 @@ def _orthogonal_decomposition(self, generators=None): dimension 1 subalgebras. The algorithm is recursive and proceeds as follows: - 0. If `A` is of dimension 1, return a non zero + 0. If `A` is of dimension 1, return a nonzero element. 1. Otherwise: find one of the generators such @@ -217,9 +215,7 @@ def central_orthogonal_idempotents(self): of the identity into primitive orthogonal idempotents. - OUTPUT: - - A list of orthogonal idempotents of ``self``. + OUTPUT: list of orthogonal idempotents of ``self`` EXAMPLES:: diff --git a/src/sage/categories/finite_enumerated_sets.py b/src/sage/categories/finite_enumerated_sets.py index 0cb4aabb650..d3438e43d37 100644 --- a/src/sage/categories/finite_enumerated_sets.py +++ b/src/sage/categories/finite_enumerated_sets.py @@ -22,7 +22,7 @@ class FiniteEnumeratedSets(CategoryWithAxiom): """ - The category of finite enumerated sets + The category of finite enumerated sets. EXAMPLES:: @@ -116,7 +116,7 @@ def _cardinality_from_iterator(self, *ignored_args, **ignored_kwds): sage: from sage.categories.examples.finite_enumerated_sets import Example sage: class FreshExample(Example): pass - sage: C = FreshExample(); C.rename("FreshExample") + sage: C = FreshExample(); C.rename('FreshExample') sage: C.cardinality @@ -191,15 +191,15 @@ def _cardinality_from_list(self, *ignored_args, **ignored_kwds): return Integer(len(self.tuple())) def _unrank_from_list(self, r): - """ - The ``r``-th element of ``self`` + r""" + The `r`-th element of ``self``. INPUT: - - ``r`` -- an integer between ``0`` and ``n-1``, - where ``n`` is the cardinality of ``self``. + - ``r`` -- integer between `0` and `n-1`, + where `n` is the cardinality of ``self`` - OUTPUT: the ``r``-th element of ``self`` + OUTPUT: the `r`-th element of ``self`` This implementation of :meth:`unrank` uses the method :meth:`list` (which is cached). Reciprocally, calling @@ -310,7 +310,7 @@ def _list_from_iterator(self): sage: from sage.categories.examples.finite_enumerated_sets import Example sage: class FreshExample(Example): pass - sage: C = FreshExample(); C.rename("FreshExample") + sage: C = FreshExample(); C.rename('FreshExample') sage: C.list sage: C.unrank @@ -528,7 +528,7 @@ def _last_from_unrank(self): def _test_enumerated_set_iter_cardinality(self, **options): """ - Checks that the methods :meth:`.cardinality` and + Check that the methods :meth:`.cardinality` and :meth:`.__iter__` are consistent. Also checks that :meth:`.cardinality` returns an ``Integer``. @@ -609,7 +609,7 @@ class ParentMethods: def last(self): r""" - Return the last element + Return the last element. EXAMPLES:: @@ -678,12 +678,12 @@ def rank(self, x): def unrank(self, i): r""" - Return the ``i``-th element of this Cartesian product. + Return the `i`-th element of this Cartesian product. INPUT: - - ``i`` -- integer between ``0`` and ``n-1`` where - ``n`` is the cardinality of this set. + - ``i`` -- integer between `0` and `n-1` where + `n` is the cardinality of this set .. SEEALSO:: @@ -711,7 +711,7 @@ def unrank(self, i): from sage.rings.integer_ring import ZZ i = ZZ(i) if i < 0: - raise IndexError("i (={}) must be a non-negative integer") + raise IndexError("i (={}) must be a nonnegative integer") elt = [] for c in reversed(self.cartesian_factors()): card = c.cardinality() @@ -725,7 +725,7 @@ class IsomorphicObjects(IsomorphicObjectsCategory): def example(self): """ - Returns an example of isomorphic object of a finite + Return an example of isomorphic object of a finite enumerated set, as per :meth:`Category.example `. @@ -741,7 +741,7 @@ class ParentMethods: def cardinality(self): r""" - Returns the cardinality of ``self`` which is the same + Return the cardinality of ``self`` which is the same as that of the ambient set ``self`` is isomorphic to. EXAMPLES:: @@ -755,7 +755,7 @@ def cardinality(self): def __iter__(self): r""" - Returns an iterator over ``self``, using the bijection + Return an iterator over ``self``, using the bijection with the ambient space. EXAMPLES:: diff --git a/src/sage/categories/finite_groups.py b/src/sage/categories/finite_groups.py index 8ef8541bdbf..88cce2fbae0 100644 --- a/src/sage/categories/finite_groups.py +++ b/src/sage/categories/finite_groups.py @@ -81,7 +81,7 @@ def monoid_generators(self): def cardinality(self): """ - Returns the cardinality of ``self``, as per + Return the cardinality of ``self``, as per :meth:`EnumeratedSets.ParentMethods.cardinality`. This default implementation calls :meth:`.order` if @@ -152,7 +152,7 @@ def conjugacy_classes(self): This will eventually be a fall-back method for groups not defined over GAP. Right now, it just raises a - :class:`NotImplementedError`, until we include a non-GAP + :exc:`NotImplementedError`, until we include a non-GAP way of listing the conjugacy classes representatives. EXAMPLES:: diff --git a/src/sage/categories/finite_lattice_posets.py b/src/sage/categories/finite_lattice_posets.py index cb0e41a2ba8..3ad8c3e81fa 100644 --- a/src/sage/categories/finite_lattice_posets.py +++ b/src/sage/categories/finite_lattice_posets.py @@ -36,7 +36,6 @@ class FiniteLatticePosets(CategoryWithAxiom): sage: C is FiniteLatticePosets().Finite() True sage: TestSuite(C).run() - """ class ParentMethods: diff --git a/src/sage/categories/finite_monoids.py b/src/sage/categories/finite_monoids.py index f4211d81bd2..169477871bd 100644 --- a/src/sage/categories/finite_monoids.py +++ b/src/sage/categories/finite_monoids.py @@ -47,7 +47,7 @@ def nerve(self): a_1 * a_2 * \cdots * a_k - The 0th face of this is obtained by deleting `a_1`, and + The `0`-th face of this is obtained by deleting `a_1`, and the `k`-th face is obtained by deleting `a_k`. The other faces are obtained by multiplying elements: the 1st face is @@ -170,7 +170,7 @@ def rhodes_radical_congruence(self, base_ring=None): INPUT: - - ``base_ring`` (default: `\QQ`) a field + - ``base_ring`` -- (default: `\QQ`) a field OUTPUT: @@ -186,7 +186,7 @@ def rhodes_radical_congruence(self, base_ring=None): sage: # needs sage.combinat sage.groups sage.modules sage: from sage.monoids.hecke_monoid import HeckeMonoid sage: H3 = HeckeMonoid(SymmetricGroup(3)) - sage: H3.repr_element_method(style="reduced") + sage: H3.repr_element_method(style='reduced') sage: H3.rhodes_radical_congruence() [([1, 2], [2, 1]), ([1, 2], [1, 2, 1]), ([2, 1], [1, 2, 1])] diff --git a/src/sage/categories/finite_permutation_groups.py b/src/sage/categories/finite_permutation_groups.py index 476f8b4a200..28edb0a2d4d 100644 --- a/src/sage/categories/finite_permutation_groups.py +++ b/src/sage/categories/finite_permutation_groups.py @@ -78,7 +78,7 @@ class FinitePermutationGroups(CategoryWithAxiom): def example(self): """ - Returns an example of finite permutation group, as per + Return an example of finite permutation group, as per :meth:`Category.example`. EXAMPLES:: @@ -111,10 +111,10 @@ def cycle_index(self, parent=None): INPUT: - - ``self`` -- a permutation group `G` - - ``parent`` -- a free module with basis indexed by partitions, - or behave as such, with a ``term`` and ``sum`` method - (default: the symmetric functions over the rational field in the `p` basis) + - ``self`` -- a permutation group `G` + - ``parent`` -- a free module with basis indexed by partitions, + or behave as such, with a ``term`` and ``sum`` method + (default: the symmetric functions over the rational field in the `p` basis) The *cycle index* of a permutation group `G` (:wikipedia:`Cycle_index`) is a gadget counting the @@ -288,24 +288,25 @@ def profile_series(self, variable='z'): def profile(self, n, using_polya=True): r""" - Return the value in ``n`` of the profile of the group ``self``. + Return the value in `n` of the profile of the group ``self``. Optional argument ``using_polya`` allows to change the default method. INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - - ``using_polya`` (optional) -- a boolean: if ``True`` (default), the computation - uses Pólya enumeration (and all values of the profile are cached, so this - should be the method used in case several of them are needed); - if ``False``, uses the GAP interface to compute the orbit. + - ``using_polya`` -- boolean (default: ``True``); if ``True``, the + computation uses Pólya enumeration (and all values of the profile + are cached, so this should be the method used in case several of + them are needed); if ``False``, uses the GAP interface to compute + the orbit. OUTPUT: - - A nonnegative integer that is the number of orbits of ``n``-subsets + - A nonnegative integer that is the number of orbits of `n`-subsets under the action induced by ``self`` on the subsets of its domain - (i.e. the value of the profile of ``self`` in ``n``) + (i.e. the value of the profile of ``self`` in `n`) .. SEEALSO:: @@ -321,7 +322,6 @@ def profile(self, n, using_polya=True): sage: D8 = DihedralGroup(8) sage: D8.profile(4, using_polya=False) 8 - """ if using_polya: diff --git a/src/sage/categories/finite_posets.py b/src/sage/categories/finite_posets.py index c1a008d1c12..04eff9e9205 100644 --- a/src/sage/categories/finite_posets.py +++ b/src/sage/categories/finite_posets.py @@ -44,7 +44,6 @@ class FinitePosets(CategoryWithAxiom): sage: C is Posets().Finite() True sage: TestSuite(C).run() - """ class ParentMethods: @@ -181,7 +180,7 @@ def is_poset_isomorphism(self, f, codomain): sage: B.is_poset_isomorphism(f, D) False - .. note:: since ``D`` and ``B`` are not facade posets, ``f`` is + .. NOTE:: since ``D`` and ``B`` are not facade posets, ``f`` is responsible for the conversions between integers and subsets to elements of ``D`` and ``B`` and back. @@ -229,7 +228,7 @@ def is_poset_morphism(self, f, codomain): sage: B.is_poset_morphism(f, D) True - .. note:: since ``D`` and ``B`` are not facade posets, ``f`` is responsible + .. NOTE:: since ``D`` and ``B`` are not facade posets, ``f`` is responsible for the conversions between integers and subsets to elements of ``D`` and ``B`` and back. @@ -265,7 +264,6 @@ def is_poset_morphism(self, f, codomain): Finite poset containing 0 elements sage: P.is_poset_morphism(f, P) True - """ for x in self: for y in self.upper_covers(x): @@ -287,9 +285,9 @@ def order_ideal_generators(self, ideal, direction='down'): of ``self``, as a list (or iterable); this should be an order ideal if ``direction`` is set to ``'down'``, and an order filter if ``direction`` is set to - ``'up'``. + ``'up'`` - ``direction`` -- ``'up'`` or ``'down'`` (default: - ``'down'``). + ``'down'``) The antichain of (minimal) generators of an order ideal `I` in a poset `P` is the set of all minimal elements of @@ -312,7 +310,7 @@ def order_ideal_generators(self, ideal, direction='down'): sage: sorted(sorted(p) for p in gen) [[1, 2], [2, 3]] - If ``direction`` is 'up', then this instead computes + If ``direction`` is ``'up'``, then this instead computes the minimal generators for an order filter:: sage: I = P.order_filter([Set([1,2]), Set([2,3]), Set([1])]) @@ -336,7 +334,7 @@ def order_ideal_generators(self, ideal, direction='down'): def order_filter_generators(self, filter): r""" - Generators for an order filter + Generators for an order filter. INPUT: @@ -386,7 +384,7 @@ def order_ideal_complement_generators(self, antichain, direction='up'): - ``antichain`` -- an antichain of ``self``, as a list (or iterable), or, more generally, generators of an order ideal (resp. order filter) - - ``direction`` -- 'up' or 'down' (default: 'up') + - ``direction`` -- ``'up'`` or ``'down'`` (default: ``'up'``) OUTPUT: @@ -406,13 +404,13 @@ def order_ideal_complement_generators(self, antichain, direction='up'): sage: P.order_ideal_complement_generators([1,2,3]) set() - sage: P.order_ideal_complement_generators([1], direction="down") + sage: P.order_ideal_complement_generators([1], direction='down') {2} - sage: P.order_ideal_complement_generators([3], direction="down") + sage: P.order_ideal_complement_generators([3], direction='down') {1, 2} - sage: P.order_ideal_complement_generators([1,2], direction="down") + sage: P.order_ideal_complement_generators([1,2], direction='down') set() - sage: P.order_ideal_complement_generators([1,2,3], direction="down") + sage: P.order_ideal_complement_generators([1,2,3], direction='down') set() .. WARNING:: @@ -452,9 +450,7 @@ def rowmotion(self, order_ideal): - ``order_ideal`` -- an order ideal of ``self``, as a set - OUTPUT: - - - the image of ``order_ideal`` under rowmotion, as a set again + OUTPUT: the image of ``order_ideal`` under rowmotion, as a set again EXAMPLES:: @@ -597,7 +593,7 @@ def birational_free_labelling(self, linear_extension=None, field of the labelling, because the latter will have indeterminates adjoined! - - ``reduced`` -- (default: ``False``) if set to + - ``reduced`` -- boolean (default: ``False``); if set to ``True``, the result will be the *reduced* birational free labelling, which differs from the regular one by having `0` and `1` both sent to `1` instead of `a` and @@ -608,7 +604,7 @@ def birational_free_labelling(self, linear_extension=None, names of extra variables to be adjoined to the ground field (these don't have an effect on the labels) - - ``labels`` -- (default: ``'x'``) Either a function + - ``labels`` -- (default: ``'x'``) either a function that takes an element of the poset and returns a name for the indeterminate corresponding to that element, or a string containing a comma-separated list of @@ -666,7 +662,7 @@ def birational_free_labelling(self, linear_extension=None, [(1, x1), (2, x3), (3, x2)] sage: l = P.birational_free_labelling(linear_extension=[1, 3, 2], - ....: prefix="wut", reduced=True, + ....: prefix='wut', reduced=True, ....: addvars="spam, eggs"); l (Fraction Field of Multivariate Polynomial Ring in wut1, wut2, wut3, spam, eggs over Rational Field, @@ -703,7 +699,7 @@ def birational_free_labelling(self, linear_extension=None, sage: P = posets.ChainPoset(2).product(posets.ChainPoset(2)) # needs sage.modules sage: l = P.birational_free_labelling(labels=x_label, - ....: min_label="lambda", max_label="mu") + ....: min_label='lambda', max_label='mu') sage: sorted(l[1].items()) [((0, 0), x_00), ((0, 1), x_01), ((1, 0), x_10), ((1, 1), x_11)] sage: l[2] @@ -747,7 +743,7 @@ def birational_free_labelling(self, linear_extension=None, sage: P = posets.SSTPoset([2,1]) sage: lext = sorted(P) sage: l = P.birational_free_labelling(linear_extension=lext, - ....: addvars="ohai"); l + ....: addvars='ohai'); l (Fraction Field of Multivariate Polynomial Ring in a, x1, x2, x3, x4, x5, x6, x7, x8, b, ohai over Rational Field, {...}, @@ -773,7 +769,7 @@ def birational_free_labelling(self, linear_extension=None, Finite lattice containing 6 elements sage: lex = [(1,0),(0,0),(1,1),(0,1),(1,2),(0,2)] sage: l = P.birational_free_labelling(linear_extension=lex, - ....: prefix="u", reduced=True) + ....: prefix='u', reduced=True) sage: l (Fraction Field of Multivariate Polynomial Ring in u1, u2, u3, u4, u5, u6 over Rational Field, {...}, @@ -790,7 +786,7 @@ def birational_free_labelling(self, linear_extension=None, For comparison, the standard linear extension:: sage: # needs sage.modules - sage: l = P.birational_free_labelling(prefix="u", reduced=True); l + sage: l = P.birational_free_labelling(prefix='u', reduced=True); l (Fraction Field of Multivariate Polynomial Ring in u1, u2, u3, u4, u5, u6 over Rational Field, {...}, 1, @@ -810,7 +806,7 @@ def birational_free_labelling(self, linear_extension=None, sage: # needs sage.modules sage: lex = [(0,0),(0,1),(1,0),(1,1),(0,2),(1,2)] sage: l = P.birational_free_labelling(linear_extension=P.linear_extension(lex), - ....: prefix="u", reduced=True) + ....: prefix='u', reduced=True) sage: l (Fraction Field of Multivariate Polynomial Ring in u1, u2, u3, u4, u5, u6 over Rational Field, {...}, @@ -829,7 +825,7 @@ def birational_free_labelling(self, linear_extension=None, sage: P = Poset({1: [3], 2: [3,4]}) sage: lex = [1, 2, 4, 3] sage: l = P.birational_free_labelling(linear_extension=lex, - ....: prefix="aaa", + ....: prefix='aaa', ....: base_field=Zmod(13)) sage: l (Fraction Field of Multivariate Polynomial Ring in a, aaa1, aaa2, aaa3, aaa4, b over Ring of integers modulo 13, @@ -857,12 +853,12 @@ def birational_free_labelling(self, linear_extension=None, {}, 1, 1) - sage: P.birational_free_labelling(prefix="zzz") + sage: P.birational_free_labelling(prefix='zzz') (Fraction Field of Multivariate Polynomial Ring in a, b over Rational Field, {}, a, b) - sage: P.birational_free_labelling(labels="x,y,z", min_label="spam", max_label="eggs") + sage: P.birational_free_labelling(labels='x,y,z', min_label='spam', max_label='eggs') (Fraction Field of Multivariate Polynomial Ring in spam, eggs over Rational Field, {}, spam, @@ -933,7 +929,7 @@ def birational_toggle(self, v, labelling): encoded to be understood by Sage. This implementation allows `\mathbf{K}` to be a semifield, not just a field. The birational `v`-toggle is only a rational map, so an exception (most - likely, :class:`ZeroDivisionError`) will be thrown if the + likely, :exc:`ZeroDivisionError`) will be thrown if the denominator is zero. INPUT: @@ -1154,7 +1150,7 @@ def birational_toggles(self, vs, labelling): encoded to be understood by Sage. This implementation allows `\mathbf{K}` to be a semifield, not just a field. The birational `v`-toggle is only a rational map, so an exception (most - likely, :class:`ZeroDivisionError`) will be thrown if the + likely, :exc:`ZeroDivisionError`) will be thrown if the denominator is zero. INPUT: @@ -1233,7 +1229,7 @@ def birational_rowmotion(self, labelling): by Sage. This implementation allows `\mathbf{K}` to be a semifield, not just a field. Birational rowmotion is only a rational map, so an exception (most likely, - :class:`ZeroDivisionError`) will be thrown if the + :exc:`ZeroDivisionError`) will be thrown if the denominator is zero. INPUT: @@ -1364,10 +1360,10 @@ def panyushev_orbits(self, element_constructor=set): INPUT: - - ``element_constructor`` (defaults to ``set``) -- a type + - ``element_constructor`` -- (default: ``set``) a type constructor (``set``, ``tuple``, ``list``, ``frozenset``, ``iter``, etc.) which is to be applied to the antichains - before they are returned. + before they are returned OUTPUT: @@ -1426,10 +1422,10 @@ def rowmotion_orbits(self, element_constructor=set): INPUT: - - ``element_constructor`` (defaults to ``set``) -- a type + - ``element_constructor`` -- (default: ``set``) a type constructor (``set``, ``tuple``, ``list``, ``frozenset``, ``iter``, etc.) which is to be applied to the antichains - before they are returned. + before they are returned OUTPUT: @@ -1477,7 +1473,6 @@ def rowmotion_orbits_plots(self): sage: P = Poset({}) sage: P.rowmotion_orbits_plots() Graphics Array of size 1 x 1 - """ from sage.plot.plot import graphics_array plot_of_orb_plots = [] @@ -1512,15 +1507,15 @@ def toggling_orbits(self, vs, element_constructor=set): INPUT: - - ``vs``: a list (or other iterable) of elements of ``self`` + - ``vs`` -- a list (or other iterable) of elements of ``self`` (but since the output depends on the order, sets should not be used as ``vs``). OUTPUT: - - a partition of the order ideals of ``self``, as a list of - sets ``L`` such that for each ``L`` and ``i``, cyclically: - ``self.order_ideal_toggles(L[i], vs) == L[i+1]``. + A partition of the order ideals of ``self``, as a list of + sets ``L`` such that for each ``L`` and ``i``, cyclically: + ``self.order_ideal_toggles(L[i], vs) == L[i+1]``. EXAMPLES:: @@ -1564,7 +1559,6 @@ def toggling_orbits_plots(self, vs): sage: P = Poset({}) sage: P.toggling_orbits_plots([]) Graphics Array of size 1 x 1 - """ from sage.plot.plot import graphics_array plot_of_orb_plots = [] @@ -1592,21 +1586,19 @@ def panyushev_orbit_iter(self, antichain, element_constructor=set, INPUT: - ``antichain`` -- an antichain of ``self``, given as an - iterable. + iterable - - ``element_constructor`` (defaults to ``set``) -- a type - constructor (``set``, ``tuple``, ``list``, ``frozenset``, - ``iter``, etc.) which is to be applied to the antichains - before they are yielded. + - ``element_constructor`` -- a type constructor (default: ``set``). + Can be ``set``, ``tuple``, ``list``, ``frozenset``, ``iter``, + etc. To be applied to the antichains before they are yielded. - - ``stop`` -- a Boolean (default: ``True``) determining - whether the iterator should stop once it completes its - cycle (this happens when it is set to ``True``) or go on - forever (this happens when it is set to ``False``). + - ``stop`` -- boolean (default: ``True``); whether the iterator + should stop once it completes its cycle (this happens when it is + set to ``True``) or go on forever (this happens when it is set to + ``False``). - - ``check`` -- a Boolean (default: ``True``) determining - whether ``antichain`` should be checked for being an - antichain. + - ``check`` -- boolean (default: ``True``); whether to check + ``antichain`` for being an antichain OUTPUT: @@ -1682,21 +1674,21 @@ def rowmotion_orbit_iter(self, oideal, element_constructor=set, stop=True, check INPUT: - ``oideal`` -- an order ideal of ``self``, given as an - iterable. + iterable - - ``element_constructor`` (defaults to ``set``) -- a type + - ``element_constructor`` -- (defaults to ``set``) a type constructor (``set``, ``tuple``, ``list``, ``frozenset``, ``iter``, etc.) which is to be applied to the order - ideals before they are yielded. + ideals before they are yielded - - ``stop`` -- a Boolean (default: ``True``) determining + - ``stop`` -- boolean (default: ``True``); whether the iterator should stop once it completes its cycle (this happens when it is set to ``True``) or go on - forever (this happens when it is set to ``False``). + forever (this happens when it is set to ``False``) - - ``check`` -- a Boolean (default: ``True``) determining + - ``check`` -- boolean (default: ``True``); whether ``oideal`` should be checked for being an - order ideal. + order ideal OUTPUT: @@ -1786,24 +1778,24 @@ def toggling_orbit_iter(self, vs, oideal, element_constructor=set, stop=True, ch INPUT: - - ``vs``: a list (or other iterable) of elements of ``self`` + - ``vs`` -- list (or other iterable) of elements of ``self`` (but since the output depends on the order, sets should not be used as ``vs``). - ``oideal`` -- an order ideal of ``self``, given as an - iterable. + iterable - - ``element_constructor`` (defaults to ``set``) -- a type + - ``element_constructor`` -- (default: ``set``) a type constructor (``set``, ``tuple``, ``list``, ``frozenset``, ``iter``, etc.) which is to be applied to the order ideals before they are yielded. - - ``stop`` -- a Boolean (default: ``True``) determining + - ``stop`` -- boolean (default: ``True``); whether the iterator should stop once it completes its cycle (this happens when it is set to ``True``) or go on forever (this happens when it is set to ``False``). - - ``check`` -- a Boolean (default: ``True``) determining + - ``check`` -- boolean (default: ``True``); whether ``oideal`` should be checked for being an order ideal. @@ -1898,10 +1890,10 @@ def order_ideals_lattice(self, as_ideals=True, facade=None): INPUT: - - ``as_ideals`` -- Boolean, if ``True`` (default) returns + - ``as_ideals`` -- boolean (default: ``True``); if ``True`` returns a poset on the set of order ideals, otherwise on the set of antichains - - ``facade`` -- Boolean or ``None`` (default). Whether to + - ``facade`` -- boolean or ``None`` (default); whether to return a facade lattice or not. By default return facade lattice if the poset is a facade poset. @@ -1978,13 +1970,13 @@ def directed_subsets(self, direction): r""" Return the order filters (resp. order ideals) of ``self``, as lists. - If ``direction`` is 'up', returns the order filters (upper sets). + If ``direction`` is ``'up'``, returns the order filters (upper sets). - If ``direction`` is 'down', returns the order ideals (lower sets). + If ``direction`` is ``'down'``, returns the order ideals (lower sets). INPUT: - - ``direction`` -- 'up' or 'down' + - ``direction`` -- ``'up'`` or ``'down'`` EXAMPLES:: diff --git a/src/sage/categories/finite_semigroups.py b/src/sage/categories/finite_semigroups.py index b699e33c9ab..831da9308bc 100644 --- a/src/sage/categories/finite_semigroups.py +++ b/src/sage/categories/finite_semigroups.py @@ -63,7 +63,7 @@ class FiniteSemigroups(CategoryWithAxiom): class ParentMethods: def idempotents(self): r""" - Returns the idempotents of the semigroup + Return the idempotents of the semigroup. EXAMPLES:: @@ -76,7 +76,7 @@ def idempotents(self): @cached_method def j_classes(self): r""" - Returns the `J`-classes of the semigroup. + Return the `J`-classes of the semigroup. Two elements `u` and `v` of a monoid are in the same `J`-class if `u` divides `v` and `v` divides `u`. @@ -92,16 +92,14 @@ def j_classes(self): [['a'], ['ab', 'ba'], ['abc', 'acb', 'bac', 'bca', 'cab', 'cba'], ['ac', 'ca'], ['b'], ['bc', 'cb'], ['c']] """ - return self.cayley_graph(side="twosided", simple=True).strongly_connected_components() + return self.cayley_graph(side='twosided', simple=True).strongly_connected_components() @cached_method def j_classes_of_idempotents(self): r""" - Returns all the idempotents of self, grouped by J-class. + Return all the idempotents of self, grouped by J-class. - OUTPUT: - - a list of lists. + OUTPUT: list of lists EXAMPLES:: @@ -115,7 +113,7 @@ def j_classes_of_idempotents(self): @cached_method def j_transversal_of_idempotents(self): r""" - Returns a list of one idempotent per regular J-class + Return a list of one idempotent per regular J-class. EXAMPLES:: diff --git a/src/sage/categories/finitely_generated_semigroups.py b/src/sage/categories/finitely_generated_semigroups.py index b3e2a46f3a4..1b3189970d8 100644 --- a/src/sage/categories/finitely_generated_semigroups.py +++ b/src/sage/categories/finitely_generated_semigroups.py @@ -58,7 +58,6 @@ def extra_super_categories(self): sage: Semigroups().FinitelyGenerated().extra_super_categories() [Category of enumerated sets] - """ return [EnumeratedSets()] @@ -93,7 +92,7 @@ def semigroup_generators(self): # TODO: update transitive ideal - def succ_generators(self, side="twosided"): + def succ_generators(self, side='twosided'): r""" Return the successor function of the ``side``-sided Cayley graph of ``self``. @@ -105,7 +104,7 @@ def succ_generators(self, side="twosided"): INPUT: - - ``side``: "left", "right", or "twosided" + - ``side`` -- ``'left'``, ``'right'``, or ``'twosided'`` (default) .. TODO:: Design choice: @@ -121,7 +120,6 @@ def succ_generators(self, side="twosided"): ('ca', 'cab', 'ca', 'cad') sage: S.succ_generators("twosided" )(S('ca')) ('ac', 'bca', 'ca', 'dca', 'ca', 'cab', 'ca', 'cad') - """ left = (side == "left" or side == "twosided") right = (side == "right" or side == "twosided") @@ -146,10 +144,10 @@ def __iter__(self): """ from sage.sets.recursively_enumerated_set import RecursivelyEnumeratedSet return iter(RecursivelyEnumeratedSet(self.semigroup_generators(), - self.succ_generators(side="right"), + self.succ_generators(side='right'), enumeration='breadth')) - def ideal(self, gens, side="twosided"): + def ideal(self, gens, side='twosided'): r""" Return the ``side``-sided ideal generated by ``gens``. @@ -161,21 +159,21 @@ def ideal(self, gens, side="twosided"): INPUT: - - ``gens`` -- a list (or iterable) of elements of ``self`` + - ``gens`` -- list (or iterable) of elements of ``self`` - ``side`` -- [default: "twosided"] "left", "right" or "twosided" EXAMPLES:: sage: S = FiniteSemigroups().example() - sage: sorted(S.ideal([S('cab')], side="left")) + sage: sorted(S.ideal([S('cab')], side='left')) ['abc', 'abcd', 'abdc', 'acb', 'acbd', 'acdb', 'adbc', 'adcb', 'bac', 'bacd', 'badc', 'bca', 'bcad', 'bcda', 'bdac', 'bdca', 'cab', 'cabd', 'cadb', 'cba', 'cbad', 'cbda', 'cdab', 'cdba', 'dabc', 'dacb', 'dbac', 'dbca', 'dcab', 'dcba'] - sage: list(S.ideal([S('cab')], side="right")) + sage: list(S.ideal([S('cab')], side='right')) ['cab', 'cabd'] - sage: sorted(S.ideal([S('cab')], side="twosided")) + sage: sorted(S.ideal([S('cab')], side='twosided')) ['abc', 'abcd', 'abdc', 'acb', 'acbd', 'acdb', 'adbc', 'adcb', 'bac', 'bacd', 'badc', 'bca', 'bcad', 'bcda', 'bdac', 'bdca', 'cab', 'cabd', 'cadb', 'cba', 'cbad', @@ -199,7 +197,7 @@ def some_elements(self): r""" Return an iterable containing some elements of the semigroup. - OUTPUT: the ten first elements of the semigroup, if they exist. + OUTPUT: the ten first elements of the semigroup, if they exist EXAMPLES:: diff --git a/src/sage/categories/function_fields.py b/src/sage/categories/function_fields.py index 649b5973af5..5207a9da3ad 100644 --- a/src/sage/categories/function_fields.py +++ b/src/sage/categories/function_fields.py @@ -36,7 +36,7 @@ class FunctionFields(Category): @cached_method def super_categories(self): """ - Returns the Category of which this is a direct sub-Category + Return the Category of which this is a direct sub-Category For a list off all super categories see all_super_categories EXAMPLES:: @@ -48,8 +48,8 @@ def super_categories(self): def _call_(self, x): r""" - Constructs an object in this category from the data in ``x``, - or throws a TypeError. + Construct an object in this category from the data in ``x``, + or throw a :exc:`TypeError`. EXAMPLES:: diff --git a/src/sage/categories/functor.pyx b/src/sage/categories/functor.pyx index 2ca369c2ef5..9b491ee0b94 100644 --- a/src/sage/categories/functor.pyx +++ b/src/sage/categories/functor.pyx @@ -52,7 +52,6 @@ def _Functor_unpickle(Cl, D, domain, codomain): True sage: F.domain(), loads(dumps(F)).domain() (Category of rings, Category of rings) - """ F = Functor.__new__(Cl) Functor.__init__(F, domain, codomain) @@ -63,7 +62,7 @@ def _Functor_unpickle(Cl, D, domain, codomain): cdef class Functor(SageObject): """ - A class for functors between two categories + A class for functors between two categories. NOTE: @@ -73,17 +72,15 @@ cdef class Functor(SageObject): Instead, one should implement three methods, which are composed in the default call method: - - ``_coerce_into_domain(self, x)``: Return an object of ``self``'s - domain, corresponding to ``x``, or raise a :class:`TypeError`. - - - Default: Raise :class:`TypeError` if ``x`` is not in ``self``'s domain. + - ``_coerce_into_domain(self, x)`` -- return an object of ``self``'s + domain, corresponding to ``x``, or raise a :exc:`TypeError`. + - Default: Raise :exc:`TypeError` if ``x`` is not in ``self``'s domain. - - ``_apply_functor(self, x)``: Apply ``self`` to an object ``x`` of + - ``_apply_functor(self, x)`` -- apply ``self`` to an object ``x`` of ``self``'s domain. - - Default: Conversion into ``self``'s codomain. - - ``_apply_functor_to_morphism(self, f)``: Apply ``self`` to a morphism + - ``_apply_functor_to_morphism(self, f)`` -- apply ``self`` to a morphism ``f`` in ``self``'s domain. - Default: Return ``self(f.domain()).hom(f,self(f.codomain()))``. @@ -163,7 +160,6 @@ cdef class Functor(SageObject): sage: F(f)(p) (-a^2 - 2*a*b - b^2 + a + b)*t^2 + (a^2 + 2*a*b + b^2 - a - b)*t - 4*a^2 - 8*a*b - 4*b^2 - a - b + 1 - """ def __init__(self, domain, codomain): """ @@ -177,7 +173,6 @@ cdef class Functor(SageObject): Rational Field sage: F(GF(2)) Finite Field of size 2 - """ if not isinstance(domain, category.Category): raise TypeError("domain (=%s) must be a category" % domain) @@ -234,7 +229,6 @@ cdef class Functor(SageObject): sage: F = Functor(FiniteFields(), Fields()) sage: F._apply_functor(ZZ) Rational Field - """ return self.__codomain(x) @@ -277,16 +271,16 @@ cdef class Functor(SageObject): def _coerce_into_domain(self, x): """ - Interprete the argument as an object of self's domain. + Interpret the argument as an object of ``self``'s domain. NOTE: A subclass of :class:`Functor` may overload this method. It should - return an object of self's domain, and should raise a - :class:`TypeError` if this is impossible. + return an object of ``self``'s domain, and should raise a + :exc:`TypeError` if this is impossible. By default, the argument will not be changed, but a - :class:`TypeError` will be raised if the argument does not + :exc:`TypeError` will be raised if the argument does not belong to the domain. TESTS:: @@ -383,7 +377,6 @@ cdef class Functor(SageObject): TypeError: Functor from Category of rings to Category of rings is ill-defined, since it sends x (=Rational Field) to something that is not in Category of rings. - """ from sage.categories.morphism import Morphism if isinstance(x, Morphism): @@ -395,27 +388,25 @@ cdef class Functor(SageObject): def domain(self): """ - The domain of self + The domain of ``self``. EXAMPLES:: sage: F = ForgetfulFunctor(FiniteFields(), Fields()) sage: F.domain() Category of finite enumerated fields - """ return self.__domain def codomain(self): """ - The codomain of self + The codomain of ``self``. EXAMPLES:: sage: F = ForgetfulFunctor(FiniteFields(), Fields()) sage: F.codomain() Category of fields - """ return self.__codomain @@ -445,7 +436,6 @@ def is_Functor(x): The forgetful functor from Category of fields to Category of rings sage: is_Functor(F2) True - """ from sage.misc.superseded import deprecation deprecation(38184, @@ -477,7 +467,6 @@ class ForgetfulFunctor_generic(Functor): to Category of fields sage: F(GF(3)) Finite Field of size 3 - """ def __reduce__(self): """ @@ -497,7 +486,6 @@ class ForgetfulFunctor_generic(Functor): sage: F # indirect doctest The forgetful functor from Category of finite enumerated fields to Category of fields - """ return "The forgetful functor from %s to %s" % (self.domain(), self.codomain()) @@ -508,7 +496,7 @@ class ForgetfulFunctor_generic(Functor): It is tested whether the second argument belongs to the class of forgetful functors and has the same domain and codomain as - self. If the second argument is a functor of a different class + ``self``. If the second argument is a functor of a different class but happens to be a forgetful functor, both arguments will still be considered as being *different*. @@ -552,7 +540,7 @@ class ForgetfulFunctor_generic(Functor): class IdentityFunctor_generic(ForgetfulFunctor_generic): """ - Generic identity functor on any category + Generic identity functor on any category. NOTE: @@ -591,7 +579,6 @@ class IdentityFunctor_generic(ForgetfulFunctor_generic): True sage: F The identity functor on Category of groups - """ ForgetfulFunctor_generic.__init__(self, C, C) @@ -632,7 +619,6 @@ class IdentityFunctor_generic(ForgetfulFunctor_generic): sage: F._apply_functor(ZZ) Integer Ring - """ return x @@ -643,11 +629,9 @@ def IdentityFunctor(C): INPUT: - A category, ``C``. - - OUTPUT: + - ``C`` -- a category - The identity functor in ``C``. + OUTPUT: the identity functor in ``C`` EXAMPLES:: @@ -665,7 +649,7 @@ def ForgetfulFunctor(domain, codomain): INPUT: - ``C``, ``D`` -- two categories + - ``C``, ``D`` -- two categories OUTPUT: diff --git a/src/sage/categories/g_sets.py b/src/sage/categories/g_sets.py index d49f790a9e0..f6388d8c496 100644 --- a/src/sage/categories/g_sets.py +++ b/src/sage/categories/g_sets.py @@ -65,7 +65,7 @@ def super_categories(self): @classmethod def an_instance(cls): """ - Returns an instance of this class. + Return an instance of this class. EXAMPLES:: diff --git a/src/sage/categories/graded_algebras.py b/src/sage/categories/graded_algebras.py index 082be147748..8d20019bafd 100644 --- a/src/sage/categories/graded_algebras.py +++ b/src/sage/categories/graded_algebras.py @@ -17,7 +17,7 @@ class GradedAlgebras(GradedModulesCategory): """ - The category of graded algebras + The category of graded algebras. EXAMPLES:: diff --git a/src/sage/categories/graded_algebras_with_basis.py b/src/sage/categories/graded_algebras_with_basis.py index 37c23ebfd82..793e19c848b 100644 --- a/src/sage/categories/graded_algebras_with_basis.py +++ b/src/sage/categories/graded_algebras_with_basis.py @@ -17,7 +17,7 @@ class GradedAlgebrasWithBasis(GradedModulesCategory): """ - The category of graded algebras with a distinguished basis + The category of graded algebras with a distinguished basis. EXAMPLES:: @@ -89,7 +89,7 @@ def graded_algebra(self): def free_graded_module(self, generator_degrees, names=None): """ - Create a finitely generated free graded module over ``self`` + Create a finitely generated free graded module over ``self``. INPUT: @@ -175,7 +175,7 @@ def extra_super_categories(self): class ParentMethods: """ - Implements operations on tensor products of super algebras + Implement operations on tensor products of super algebras with basis. """ @cached_method diff --git a/src/sage/categories/graded_bialgebras.py b/src/sage/categories/graded_bialgebras.py index 7af567076ac..e7079ee1e5f 100644 --- a/src/sage/categories/graded_bialgebras.py +++ b/src/sage/categories/graded_bialgebras.py @@ -13,7 +13,7 @@ def GradedBialgebras(base_ring): """ - The category of graded bialgebras + The category of graded bialgebras. EXAMPLES:: diff --git a/src/sage/categories/graded_bialgebras_with_basis.py b/src/sage/categories/graded_bialgebras_with_basis.py index e98b44ecb9d..9828a25797f 100644 --- a/src/sage/categories/graded_bialgebras_with_basis.py +++ b/src/sage/categories/graded_bialgebras_with_basis.py @@ -13,7 +13,7 @@ def GradedBialgebrasWithBasis(base_ring): """ - The category of graded bialgebras with a distinguished basis + The category of graded bialgebras with a distinguished basis. EXAMPLES:: diff --git a/src/sage/categories/graded_coalgebras.py b/src/sage/categories/graded_coalgebras.py index 9e36b48dbe5..d229e7a228a 100644 --- a/src/sage/categories/graded_coalgebras.py +++ b/src/sage/categories/graded_coalgebras.py @@ -17,7 +17,7 @@ class GradedCoalgebras(GradedModulesCategory): """ - The category of graded coalgebras + The category of graded coalgebras. EXAMPLES:: diff --git a/src/sage/categories/graded_hopf_algebras_with_basis.py b/src/sage/categories/graded_hopf_algebras_with_basis.py index 3c0458c0e03..2687cbd03be 100644 --- a/src/sage/categories/graded_hopf_algebras_with_basis.py +++ b/src/sage/categories/graded_hopf_algebras_with_basis.py @@ -72,7 +72,6 @@ def super_categories(self): TESTS:: sage: TestSuite(GradedHopfAlgebrasWithBasis(QQ).WithRealizations()).run() - """ from sage.categories.graded_hopf_algebras import GradedHopfAlgebras R = self.base_category().base_ring() @@ -102,9 +101,7 @@ def counit_on_basis(self, i): - ``i`` -- an element of the index set - OUTPUT: - - - an element of the base ring + OUTPUT: an element of the base ring .. MATH:: diff --git a/src/sage/categories/graded_lie_algebras.py b/src/sage/categories/graded_lie_algebras.py index 501d5e7feea..eb60c7e5fca 100644 --- a/src/sage/categories/graded_lie_algebras.py +++ b/src/sage/categories/graded_lie_algebras.py @@ -74,7 +74,7 @@ class FiniteDimensional(CategoryWithAxiom_over_base_ring): """ def extra_super_categories(self): """ - Implements the fact that a finite dimensional stratified Lie + Implement the fact that a finite dimensional stratified Lie algebra is nilpotent. EXAMPLES:: diff --git a/src/sage/categories/graded_modules_with_basis.py b/src/sage/categories/graded_modules_with_basis.py index 5cba7e5f016..a4d66e9c753 100644 --- a/src/sage/categories/graded_modules_with_basis.py +++ b/src/sage/categories/graded_modules_with_basis.py @@ -78,13 +78,13 @@ def submodule(self, gens, check=True, already_echelonized=False, INPUT: - - ``gens`` -- a list or family of elements of ``self`` - - ``check`` -- (default: ``True``) whether to verify that the - elements of ``gens`` are in ``self`` - - ``already_echelonized`` -- (default: ``False``) whether + - ``gens`` -- list or family of elements of ``self`` + - ``check`` -- boolean (default: ``True``); whether to verify that + the elements of ``gens`` are in ``self`` + - ``already_echelonized`` -- boolean (default: ``False``); whether the elements of ``gens`` are already in (not necessarily reduced) echelon form - - ``unitriangular`` -- (default: ``False``) whether + - ``unitriangular`` -- boolean (default: ``False``); whether the lift morphism is unitriangular - ``support_order`` -- (optional) either something that can be converted into a tuple or a key function diff --git a/src/sage/categories/group_algebras.py b/src/sage/categories/group_algebras.py index e02d01b8803..e83de9263d3 100644 --- a/src/sage/categories/group_algebras.py +++ b/src/sage/categories/group_algebras.py @@ -189,9 +189,7 @@ def center_basis(self): classes of the group, and `f_\sigma` is the sum of the elements in the conjugacy class of `\sigma`. - OUTPUT: - - - ``tuple`` of elements of ``self`` + OUTPUT: tuple of elements of ``self`` .. WARNING:: diff --git a/src/sage/categories/groupoid.py b/src/sage/categories/groupoid.py index 0f67bd47608..b197c092be5 100644 --- a/src/sage/categories/groupoid.py +++ b/src/sage/categories/groupoid.py @@ -67,7 +67,6 @@ def _make_named_class_key(self, name): sage: Groupoid(DihedralGroup(3)).parent_class is Groupoid(ZZ).parent_class True - """ return None @@ -83,7 +82,7 @@ def super_categories(self): @classmethod def an_instance(cls): """ - Returns an instance of this class. + Return an instance of this class. EXAMPLES:: diff --git a/src/sage/categories/groups.py b/src/sage/categories/groups.py index ae0721c0a55..bc7bb6b7c66 100644 --- a/src/sage/categories/groups.py +++ b/src/sage/categories/groups.py @@ -60,7 +60,7 @@ def free(index_set=None, names=None, **kwds): - ``index_set`` -- (optional) an index set for the generators; if an integer, then this represents `\{0, 1, \ldots, n-1\}` - - ``names`` -- a string or list/tuple/iterable of strings + - ``names`` -- string or list/tuple/iterable of strings (default: ``'x'``); the generator names or name prefix When the index set is an integer or only variable names are given, @@ -155,7 +155,7 @@ def _test_inverse(self, **options): def semidirect_product(self, N, mapping, check=True): r""" - The semi-direct product of two groups + The semi-direct product of two groups. EXAMPLES:: @@ -171,7 +171,7 @@ def semidirect_product(self, N, mapping, check=True): def holomorph(self): r""" - The holomorph of a group + The holomorph of a group. The holomorph of a group `G` is the semidirect product `G \rtimes_{id} Aut(G)`, where `id` is the identity function @@ -195,7 +195,7 @@ def cayley_table(self, names='letters', elements=None): Return the "multiplication" table of this multiplicative group, which is also known as the "Cayley table". - .. note:: The order of the elements in the row and column + .. NOTE:: The order of the elements in the row and column headings is equal to the order given by the table's :meth:`~sage.matrix.operation_table.OperationTable.column_keys` method. The association between the actual elements and the @@ -225,7 +225,7 @@ def cayley_table(self, names='letters', elements=None): * a list - a list of strings, where the length of the list equals the number of elements. - - ``elements`` -- (default = ``None``); A list of + - ``elements`` -- (default: ``None``) a list of elements of the group, in forms that can be coerced into the structure, eg. their string representations. This may be used to impose an @@ -430,7 +430,6 @@ class provides even greater flexibility, including changing AUTHOR: - Rob Beezer (2010-03-15) - """ from sage.matrix.operation_table import OperationTable import operator @@ -510,7 +509,7 @@ def free(index_set=None, names=None, **kwds): - ``index_set`` -- (optional) an index set for the generators; if an integer, then this represents `\{0, 1, \ldots, n-1\}` - - ``names`` -- a string or list/tuple/iterable of strings + - ``names`` -- string or list/tuple/iterable of strings (default: ``'x'``); the generator names or name prefix EXAMPLES:: @@ -627,7 +626,7 @@ def lift(i, gen): gens_prod = cartesian_product([Family(G.group_generators(), lambda g: (i, g)) for i, G in enumerate(F)]) - return Family(gens_prod, lift, name="gen") + return Family(gens_prod, lift, name='gen') def order(self): r""" diff --git a/src/sage/categories/h_trivial_semigroups.py b/src/sage/categories/h_trivial_semigroups.py index 51b2502f3e4..4988bed8cbc 100644 --- a/src/sage/categories/h_trivial_semigroups.py +++ b/src/sage/categories/h_trivial_semigroups.py @@ -19,7 +19,7 @@ class HTrivialSemigroups(CategoryWithAxiom): def Finite_extra_super_categories(self): r""" - Implement the fact that a finite `H`-trivial is aperiodic + Implement the fact that a finite `H`-trivial is aperiodic. EXAMPLES:: diff --git a/src/sage/categories/hecke_modules.py b/src/sage/categories/hecke_modules.py index 20b9829adac..99ce981eb03 100644 --- a/src/sage/categories/hecke_modules.py +++ b/src/sage/categories/hecke_modules.py @@ -104,7 +104,7 @@ class ParentMethods: def _Hom_(self, Y, category): r""" - Return the homset from ``self`` to ``Y`` in the category ``category`` + Return the homset from ``self`` to ``Y`` in the category ``category``. INPUT: @@ -115,7 +115,7 @@ def _Hom_(self, Y, category): The sole purpose of this method is to construct the homset as a :class:`~sage.modular.hecke.homspace.HeckeModuleHomspace`. If ``category`` is specified and is not a subcategory of - :class:`HeckeModules`, a :class:`TypeError` is raised instead + :class:`HeckeModules`, a :exc:`TypeError` is raised instead This method is not meant to be called directly. Please use :func:`sage.categories.homset.Hom` instead. diff --git a/src/sage/categories/highest_weight_crystals.py b/src/sage/categories/highest_weight_crystals.py index f80d177d917..db7600755bb 100644 --- a/src/sage/categories/highest_weight_crystals.py +++ b/src/sage/categories/highest_weight_crystals.py @@ -80,7 +80,7 @@ def super_categories(self): def example(self): """ - Returns an example of highest weight crystals, as per + Return an example of highest weight crystals, as per :meth:`Category.example`. EXAMPLES:: @@ -114,14 +114,13 @@ class ParentMethods: @cached_method def highest_weight_vectors(self): r""" - Returns the highest weight vectors of ``self`` + Return the highest weight vectors of ``self``. This default implementation selects among the module generators those that are highest weight, and caches the result. A crystal element `b` is highest weight if `e_i(b)=0` for all `i` in the index set. - EXAMPLES:: sage: C = crystals.Letters(['A',5]) @@ -140,7 +139,7 @@ def highest_weight_vectors(self): def highest_weight_vector(self): r""" - Returns the highest weight vector if there is a single one; + Return the highest weight vector if there is a single one; otherwise, raises an error. Caveat: this assumes that :meth:`.highest_weight_vectors` @@ -191,10 +190,10 @@ def __iter__(self, index_set=None, max_depth=float("inf")): INPUT: - - ``index_set`` -- (Default: ``None``) The index set; if ``None`` + - ``index_set`` -- (default: ``None``) the index set; if ``None`` then use the index set of the crystal - - ``max_depth`` -- (Default: infinity) The maximum depth to build + - ``max_depth`` -- (default: infinity) the maximum depth to build EXAMPLES:: @@ -254,13 +253,13 @@ def q_dimension(self, q=None, prec=None, use_product=False): - ``q`` -- the (generic) parameter `q` - - ``prec`` -- (default: ``None``) The precision of the power + - ``prec`` -- (default: ``None``) the precision of the power series ring to use if the crystal is not known to be finite (i.e. the number of terms returned). If ``None``, then the result is returned as a lazy power series. - - ``use_product`` -- (default: ``False``) if we have a finite - crystal and ``True``, use the product formula + - ``use_product`` -- boolean (default: ``False``); if we have a + finite crystal and ``True``, use the product formula EXAMPLES:: @@ -412,7 +411,7 @@ def _Hom_(self, Y, category=None, **options): The sole purpose of this method is to construct the homset as a :class:`~sage.categories.highest_weight_crystals.HighestWeightCrystalHomset`. If ``category`` is specified and is not a subcategory of - :class:`HighestWeightCrystals`, a :class:`TypeError` is raised + :class:`HighestWeightCrystals`, a :exc:`TypeError` is raised instead This method is not meant to be called directly. Please use @@ -522,7 +521,7 @@ def digraph(self, subset=None, index_set=None, depth=None): G = DiGraph(d) from sage.graphs.dot2tex_utils import have_dot2tex if have_dot2tex(): - G.set_latex_options(format="dot2tex", + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=self.cartan_type()._index_set_coloring) return G @@ -670,7 +669,7 @@ def extra_super_categories(self): class ParentMethods: """ - Implements operations on tensor products of crystals. + Implement operations on tensor products of crystals. """ @cached_method def highest_weight_vectors(self): @@ -855,7 +854,8 @@ class HighestWeightCrystalMorphism(CrystalMorphismByGenerators): for the weight, `\varepsilon` and `\varphi` - ``gens`` -- (optional) a list of generators to define the morphism; the default is to use the highest weight vectors of the crystal - - ``check`` -- (default: ``True``) check if the crystal morphism is valid + - ``check`` -- boolean (default: ``True``); check if the crystal morphism + is valid """ def __init__(self, parent, on_gens, cartan_type=None, virtualization=None, scaling_factors=None, diff --git a/src/sage/categories/homset.py b/src/sage/categories/homset.py index c0be4dedfdc..1b05cca4a52 100644 --- a/src/sage/categories/homset.py +++ b/src/sage/categories/homset.py @@ -94,11 +94,11 @@ def Hom(X, Y, category=None, check=True): - ``Y`` -- an object of a category - - ``category`` -- a category in which the morphisms must be. - (default: the meet of the categories of ``X`` and ``Y``) - Both ``X`` and ``Y`` must belong to that category. + - ``category`` -- a category in which the morphisms must be + (default: the meet of the categories of ``X`` and ``Y``); + both ``X`` and ``Y`` must belong to that category - - ``check`` -- a boolean (default: ``True``): whether to check the + - ``check`` -- boolean (default: ``True``); whether to check the input, and in particular that ``X`` and ``Y`` belong to ``category``. @@ -179,7 +179,7 @@ def Hom(X, Y, category=None, check=True): A parent (or a parent class of a category) may specify how to construct certain homsets by implementing a method ``_Hom_(self, codomain, category)``. This method should either construct the - requested homset or raise a :class:`TypeError`. This hook is currently + requested homset or raise a :exc:`TypeError`. This hook is currently mostly used to create homsets in some specific subclass of :class:`Homset` (e.g. :class:`sage.rings.homset.RingHomset`):: @@ -303,7 +303,7 @@ def Hom(X, Y, category=None, check=True): category. Case of a non parent:: sage: # needs sage.graphs - sage: S = SimplicialComplex([[1,2], [1,4]]); S.rename("S") + sage: S = SimplicialComplex([[1,2], [1,4]]); S.rename('S') sage: Hom(S, S, SimplicialComplexes()) Set of Morphisms from S to S in Category of finite simplicial complexes sage: Hom(Set(), S, Sets()) @@ -323,7 +323,7 @@ def Hom(X, Y, category=None, check=True): sage: class PermissiveCategory(Category): ....: def super_categories(self): return [Objects()] ....: def __contains__(self, X): return True - sage: C = PermissiveCategory(); C.rename("Permissive category") + sage: C = PermissiveCategory(); C.rename('Permissive category') sage: S.category().is_subcategory(C) False sage: S in C @@ -500,13 +500,11 @@ def End(X, category=None): INPUT: - - ``X`` -- anything + - ``X`` -- anything - - ``category`` -- (optional) category in which to coerce ``X`` + - ``category`` -- (optional) category in which to coerce ``X`` - OUTPUT: - - A set of endomorphisms in category + OUTPUT: a set of endomorphisms in category EXAMPLES:: @@ -613,8 +611,8 @@ def __init__(self, X, Y, category=None, base=None, check=True): r""" TESTS:: - sage: X = ZZ['x']; X.rename("X") - sage: Y = ZZ['y']; Y.rename("Y") + sage: X = ZZ['x']; X.rename('X') + sage: Y = ZZ['y']; Y.rename('Y') sage: f = X.hom([0], Y) sage: class MyHomset(Homset): ....: def _an_element_(self): @@ -931,7 +929,7 @@ def _element_constructor_(self, x, check=None, **options): Set of Morphisms from Free Group on generators {x, y, z} to Free Group on generators {x, y, z} in Category of infinite groups sage: HH = Hom(H, H) - sage: HH(HH.identity(), foo="bar") + sage: HH(HH.identity(), foo='bar') Traceback (most recent call last): ... NotImplementedError: no keywords are implemented for @@ -1270,8 +1268,8 @@ def __init__(self, X, Y, category=None, check=True, base=None): r""" TESTS:: - sage: X = ZZ['x']; X.rename("X") - sage: Y = ZZ['y']; Y.rename("Y") + sage: X = ZZ['x']; X.rename('X') + sage: Y = ZZ['y']; Y.rename('Y') sage: f = X.hom([0], Y) sage: class MyHomset(HomsetWithBase): ....: def _an_element_(self): diff --git a/src/sage/categories/homsets.py b/src/sage/categories/homsets.py index 9fce08733d6..d930e5a3fd2 100644 --- a/src/sage/categories/homsets.py +++ b/src/sage/categories/homsets.py @@ -27,8 +27,8 @@ def default_super_categories(cls, category): INPUT: - - ``cls`` -- the category class for the functor `F` - - ``category`` -- a category `Cat` + - ``cls`` -- the category class for the functor `F` + - ``category`` -- a category `Cat` OUTPUT: a category @@ -122,7 +122,7 @@ def default_super_categories(cls, category): def _test_homsets_category(self, **options): r""" - Run generic tests on this homsets category + Run generic tests on this homsets category. .. SEEALSO:: :class:`TestSuite`. @@ -148,7 +148,6 @@ def base(self): sage: ModulesWithBasis(ZZ).Homsets().base() Integer Ring - """ from sage.categories.category_types import Category_over_base for C in self._all_super_categories_proper: diff --git a/src/sage/categories/hopf_algebras.py b/src/sage/categories/hopf_algebras.py index acc85774aff..d6dd6024ecb 100644 --- a/src/sage/categories/hopf_algebras.py +++ b/src/sage/categories/hopf_algebras.py @@ -46,7 +46,7 @@ def super_categories(self): def dual(self): """ - Return the dual category + Return the dual category. EXAMPLES: @@ -64,7 +64,7 @@ class ElementMethods: def antipode(self): """ - Return the antipode of self + Return the antipode of ``self``. EXAMPLES:: @@ -199,7 +199,7 @@ class ParentMethods: # HopfAlgebras.ParentMethods. def antipode_by_coercion(self, x): """ - Returns the image of ``x`` by the antipode + Return the image of ``x`` by the antipode. This default implementation coerces to the default realization, computes the antipode there, and coerces the diff --git a/src/sage/categories/hopf_algebras_with_basis.py b/src/sage/categories/hopf_algebras_with_basis.py index 60e30bde8d3..ea61bbac184 100644 --- a/src/sage/categories/hopf_algebras_with_basis.py +++ b/src/sage/categories/hopf_algebras_with_basis.py @@ -20,7 +20,7 @@ class HopfAlgebrasWithBasis(CategoryWithAxiom_over_base_ring): """ - The category of Hopf algebras with a distinguished basis + The category of Hopf algebras with a distinguished basis. EXAMPLES:: @@ -37,7 +37,7 @@ class HopfAlgebrasWithBasis(CategoryWithAxiom_over_base_ring): sage: A = C.example(); A # needs sage.groups An example of Hopf algebra with basis: the group algebra of the Dihedral group of order 6 as a permutation group over Rational Field - sage: A.rename("A") # needs sage.groups + sage: A.rename('A') # needs sage.groups sage: A.category() # needs sage.groups Category of finite dimensional Hopf algebras with basis over Rational Field @@ -121,7 +121,7 @@ class HopfAlgebrasWithBasis(CategoryWithAxiom_over_base_ring): def example(self, G=None): """ - Returns an example of algebra with basis:: + Return an example of algebra with basis:: sage: HopfAlgebrasWithBasis(QQ['x']).example() # needs sage.groups An example of Hopf algebra with basis: the group algebra of the @@ -169,11 +169,11 @@ class ParentMethods: @abstract_method(optional=True) def antipode_on_basis(self, x): """ - The antipode of the Hopf algebra on the basis (optional) + The antipode of the Hopf algebra on the basis (optional). INPUT: - - ``x`` -- an index of an element of the basis of ``self`` + - ``x`` -- an index of an element of the basis of ``self`` Returns the antipode of the basis element indexed by ``x``. @@ -256,7 +256,6 @@ def _test_antipode(self, **options): sage: s = SymmetricFunctions(QQ).schur() # needs sage.combinat sage.modules sage: s._test_antipode() # needs lrcalc_python sage.combinat sage.modules - """ tester = self._tester(**options) diff --git a/src/sage/categories/infinite_enumerated_sets.py b/src/sage/categories/infinite_enumerated_sets.py index fbd1413cabb..8a6618a4fe6 100644 --- a/src/sage/categories/infinite_enumerated_sets.py +++ b/src/sage/categories/infinite_enumerated_sets.py @@ -19,7 +19,7 @@ class InfiniteEnumeratedSets(CategoryWithAxiom): """ - The category of infinite enumerated sets + The category of infinite enumerated sets. An infinite enumerated sets is a countable set together with a canonical enumeration of its elements. @@ -102,7 +102,7 @@ def _test_enumerated_set_iter_cardinality(self, **options): * :meth:`.cardinality` is supposed to return ``infinity`` - * :meth:`.list` is supposed to raise a :class:`NotImplementedError`. + * :meth:`.list` is supposed to raise a :exc:`NotImplementedError`. EXAMPLES:: diff --git a/src/sage/categories/integral_domains.py b/src/sage/categories/integral_domains.py index a0577a194b0..173a14cf25f 100644 --- a/src/sage/categories/integral_domains.py +++ b/src/sage/categories/integral_domains.py @@ -20,7 +20,7 @@ class IntegralDomains(CategoryWithAxiom): """ - The category of integral domains + The category of integral domains. An integral domain is commutative ring with no zero divisors, or equivalently a commutative domain. @@ -130,7 +130,6 @@ def _test_fraction_field(self, **options): EXAMPLES:: sage: ZZ._test_fraction_field() - """ tester = self._tester(**options) try: diff --git a/src/sage/categories/isomorphic_objects.py b/src/sage/categories/isomorphic_objects.py index e85f0a8d6da..98af7c4ae7a 100644 --- a/src/sage/categories/isomorphic_objects.py +++ b/src/sage/categories/isomorphic_objects.py @@ -24,7 +24,7 @@ class IsomorphicObjectsCategory(RegressiveCovariantConstructionCategory): @classmethod def default_super_categories(cls, category): """ - Returns the default super categories of ``category.IsomorphicObjects()`` + Return the default super categories of ``category.IsomorphicObjects()``. Mathematical meaning: if `A` is the image of `B` by an isomorphism in the category `C`, then `A` is both a subobject @@ -32,8 +32,8 @@ def default_super_categories(cls, category): INPUT: - - ``cls`` -- the class ``IsomorphicObjectsCategory`` - - ``category`` -- a category `Cat` + - ``cls`` -- the class ``IsomorphicObjectsCategory`` + - ``category`` -- a category `Cat` OUTPUT: a (join) category diff --git a/src/sage/categories/lambda_bracket_algebras.py b/src/sage/categories/lambda_bracket_algebras.py index 9c93d417489..b291086e25e 100644 --- a/src/sage/categories/lambda_bracket_algebras.py +++ b/src/sage/categories/lambda_bracket_algebras.py @@ -34,15 +34,14 @@ class LambdaBracketAlgebras(Category_over_base_ring): This is an abstract base category for Lie conformal algebras and super Lie conformal algebras. - """ @staticmethod def __classcall_private__(cls, R, check=True): r""" INPUT: - - `R` -- a commutative ring - - ``check`` -- a boolean (default: ``True``); whether to check + - ``R`` -- a commutative ring + - ``check`` -- boolean (default: ``True``); whether to check that `R` is a commutative ring EXAMPLES:: @@ -251,7 +250,7 @@ def T(self, n=1): INPUT: - - ``n`` -- integer (default:``1``); how many times + - ``n`` -- integer (default: `1`); how many times to apply `T` to this element OUTPUT: diff --git a/src/sage/categories/lattice_posets.py b/src/sage/categories/lattice_posets.py index 1477e0972e5..7bdc5bfc0de 100644 --- a/src/sage/categories/lattice_posets.py +++ b/src/sage/categories/lattice_posets.py @@ -38,12 +38,11 @@ class LatticePosets(Category): sage: C = LatticePosets() sage: TestSuite(C).run() - """ @cached_method def super_categories(self): r""" - Returns a list of the (immediate) super categories of + Return a list of the (immediate) super categories of ``self``, as per :meth:`Category.super_categories`. EXAMPLES:: @@ -60,11 +59,11 @@ class ParentMethods: @abstract_method def meet(self, x, y): """ - Returns the meet of `x` and `y` in this lattice + Return the meet of `x` and `y` in this lattice. INPUT: - - ``x``, ``y`` -- elements of ``self`` + - ``x``, ``y`` -- elements of ``self`` EXAMPLES:: @@ -76,11 +75,11 @@ def meet(self, x, y): @abstract_method def join(self, x, y): """ - Returns the join of `x` and `y` in this lattice + Return the join of `x` and `y` in this lattice. INPUT: - - ``x``, ``y`` -- elements of ``self`` + - ``x``, ``y`` -- elements of ``self`` EXAMPLES:: diff --git a/src/sage/categories/lie_algebras.py b/src/sage/categories/lie_algebras.py index 0f8fde4936f..f134cfded5b 100644 --- a/src/sage/categories/lie_algebras.py +++ b/src/sage/categories/lie_algebras.py @@ -178,7 +178,7 @@ class FiniteDimensional(CategoryWithAxiom_over_base_ring): def extra_super_categories(self): """ - Implements the fact that a finite dimensional Lie algebra over + Implement the fact that a finite dimensional Lie algebra over a finite ring is finite. EXAMPLES:: @@ -645,7 +645,7 @@ def bch(self, X, Y, prec=None): - ``X`` -- an element of ``self`` - ``Y`` -- an element of ``self`` - - ``prec`` -- an integer; the maximum length of Lie brackets to be + - ``prec`` -- integer; the maximum length of Lie brackets to be considered in the formula EXAMPLES: @@ -781,7 +781,7 @@ def _test_jacobi_identity(self, **options): INPUT: - - ``options`` -- any keyword arguments accepted by :meth:`_tester`. + - ``options`` -- any keyword arguments accepted by :meth:`_tester` EXAMPLES: @@ -820,7 +820,7 @@ def _test_antisymmetry(self, **options): INPUT: - - ``options`` -- any keyword arguments accepted by :meth:`_tester`. + - ``options`` -- any keyword arguments accepted by :meth:`_tester` EXAMPLES: @@ -852,7 +852,7 @@ def _test_distributivity(self, **options): INPUT: - - ``options`` -- any keyword arguments accepted by :meth:`_tester`. + - ``options`` -- any keyword arguments accepted by :meth:`_tester` TESTS:: @@ -864,7 +864,7 @@ def _test_distributivity(self, **options): By default, this method runs the tests only on the elements returned by ``self.some_elements()``:: - sage: L = LieAlgebra(QQ, 3, 'x,y,z', representation="polynomial") # needs sage.combinat sage.modules + sage: L = LieAlgebra(QQ, 3, 'x,y,z', representation='polynomial') # needs sage.combinat sage.modules sage: L.some_elements() # needs sage.combinat sage.modules [x + y + z] sage: L._test_distributivity() # needs sage.combinat sage.modules @@ -1043,7 +1043,7 @@ def __init__(self, domain, codomain): We skip the category test since this is currently not an element of a homspace:: - sage: TestSuite(f).run(skip="_test_category") # needs sage.combinat sage.libs.singular sage.modules + sage: TestSuite(f).run(skip='_test_category') # needs sage.combinat sage.libs.singular sage.modules """ Morphism.__init__(self, Hom(domain, codomain)) diff --git a/src/sage/categories/lie_algebras_with_basis.py b/src/sage/categories/lie_algebras_with_basis.py index 9518113ce23..6db83cbe61d 100644 --- a/src/sage/categories/lie_algebras_with_basis.py +++ b/src/sage/categories/lie_algebras_with_basis.py @@ -44,7 +44,7 @@ def example(self, gens=None): sage: LieAlgebras(QQ).WithBasis().example(Compositions()) # needs sage.combinat sage.modules An example of a Lie algebra: the abelian Lie algebra on the - generators indexed by Compositions of non-negative integers + generators indexed by Compositions of nonnegative integers over Rational Field """ if gens is None: diff --git a/src/sage/categories/lie_conformal_algebras.py b/src/sage/categories/lie_conformal_algebras.py index 561d9e1e693..13c4f3e7c5b 100644 --- a/src/sage/categories/lie_conformal_algebras.py +++ b/src/sage/categories/lie_conformal_algebras.py @@ -60,8 +60,7 @@ .. NOTE:: In the literature arbitrary gradings are allowed. In this - implementation we only support non-negative rational gradings. - + implementation we only support nonnegative rational gradings. EXAMPLES: diff --git a/src/sage/categories/lie_groups.py b/src/sage/categories/lie_groups.py index 1512a599e04..792b87bad39 100644 --- a/src/sage/categories/lie_groups.py +++ b/src/sage/categories/lie_groups.py @@ -30,7 +30,7 @@ class LieGroups(Category_over_base_ring): TESTS:: - sage: TestSuite(C).run(skip="_test_category_over_bases") + sage: TestSuite(C).run(skip='_test_category_over_bases') """ @cached_method def super_categories(self): diff --git a/src/sage/categories/loop_crystals.py b/src/sage/categories/loop_crystals.py index fbf4afd3f58..e6bf9126876 100644 --- a/src/sage/categories/loop_crystals.py +++ b/src/sage/categories/loop_crystals.py @@ -822,7 +822,7 @@ def one_dimensional_configuration_sum(self, q=None, group_components=True): - ``q`` -- (default: ``None``) a variable or ``None``; if ``None``, a variable `q` is set in the code - - ``group_components`` -- (default: ``True``) boolean; if + - ``group_components`` -- boolean (default: ``True``); if ``True``, then the terms are grouped by classical component The one-dimensional configuration sum is the sum of the @@ -924,7 +924,7 @@ def energy_function(self, algorithm=None): factors are perfect of the same level and otherwise this uses ``'definition'`` - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -1021,7 +1021,7 @@ def affine_grading(self): :meth:`e_string_to_ground_state`) and counting the number of affine Kashiwara operators `e_0` applied on the way. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/categories/magmas.py b/src/sage/categories/magmas.py index 2fa35e45b49..ea491b2caf7 100644 --- a/src/sage/categories/magmas.py +++ b/src/sage/categories/magmas.py @@ -380,7 +380,7 @@ def is_field(self, proof=True): Return ``True`` if ``self`` is a field. For a magma algebra `RS` this is always false unless - `S` is trivial and the base ring `R`` is a field. + `S` is trivial and the base ring `R` is a field. EXAMPLES:: @@ -835,9 +835,9 @@ def __init_extra__(self): def multiplication_table(self, names='letters', elements=None): r""" - Returns a table describing the multiplication operation. + Return a table describing the multiplication operation. - .. note:: The order of the elements in the row and column + .. NOTE:: The order of the elements in the row and column headings is equal to the order given by the table's :meth:`~sage.matrix.operation_table.OperationTable.list` method. The association can also be retrieved with the @@ -861,7 +861,7 @@ def multiplication_table(self, names='letters', elements=None): of the elements themselves. * a list - a list of strings, where the length of the list equals the number of elements. - - ``elements`` -- default = ``None``. A list of + - ``elements`` -- (default: ``None``) a list of elements of the magma, in forms that can be coerced into the structure, eg. their string representations. This may be used to impose an @@ -987,15 +987,13 @@ class ElementMethods: @abstract_method(optional=True) def _mul_(self, right): """ - Product of two elements + Product of two elements. INPUT: - ``self``, ``right`` -- two elements with the same parent - OUTPUT: - - - an element of the same parent + OUTPUT: an element of the same parent EXAMPLES:: @@ -1031,7 +1029,6 @@ def is_idempotent(self): 'x' sage: x.is_idempotent() True - """ return self * self == self @@ -1180,7 +1177,6 @@ def product_by_coercion(self, left, right): sage: y = Out.an_element() sage: Out.product(x, y) Out[{}] + 4*Out[{1}] + 9*Out[{2}] + Out[{1, 2}] - """ R = self.realization_of().a_realization() return self(R(left) * R(right)) diff --git a/src/sage/categories/magmatic_algebras.py b/src/sage/categories/magmatic_algebras.py index 60da61a4983..0b45887d254 100644 --- a/src/sage/categories/magmatic_algebras.py +++ b/src/sage/categories/magmatic_algebras.py @@ -65,7 +65,6 @@ def super_categories(self): sage: from sage.categories.additive_semigroups import AdditiveSemigroups sage: MA.is_subcategory((AdditiveSemigroups() & Magmas()).Distributive()) True - """ R = self.base_ring() # Note: The specifications impose `self` to be a subcategory @@ -219,7 +218,6 @@ def _product_from_product_on_basis_multiply( self, left, right ): sage: a, b, c = A.algebra_generators() # needs sage.combinat sage.modules sage: A._product_from_product_on_basis_multiply(a*b + 2*c, a - b) # needs sage.combinat sage.modules B[word: aba] - B[word: abb] + 2*B[word: ca] - 2*B[word: cb] - """ return self.linear_combination((self.product_on_basis(mon_left, mon_right), coeff_left * coeff_right ) for (mon_left, coeff_left) in left.monomial_coefficients(copy=False).items() diff --git a/src/sage/categories/manifolds.py b/src/sage/categories/manifolds.py index 22138cca200..95e4dd928d9 100644 --- a/src/sage/categories/manifolds.py +++ b/src/sage/categories/manifolds.py @@ -36,7 +36,7 @@ class Manifolds(Category_over_base_ring): TESTS:: - sage: TestSuite(C).run(skip="_test_category_over_bases") # needs sage.rings.real_mpfr + sage: TestSuite(C).run(skip='_test_category_over_bases') # needs sage.rings.real_mpfr """ def __init__(self, base, name=None): r""" @@ -46,7 +46,7 @@ def __init__(self, base, name=None): sage: from sage.categories.manifolds import Manifolds sage: C = Manifolds(RR) - sage: TestSuite(C).run(skip="_test_category_over_bases") + sage: TestSuite(C).run(skip='_test_category_over_bases') """ if base not in Fields().Topological(): raise ValueError("base must be a topological field") @@ -318,7 +318,7 @@ class FiniteDimensional(CategoryWithAxiom_over_base_ring): sage: from sage.categories.manifolds import Manifolds sage: C = Manifolds(RR).FiniteDimensional() - sage: TestSuite(C).run(skip="_test_category_over_bases") + sage: TestSuite(C).run(skip='_test_category_over_bases') """ class Connected(CategoryWithAxiom_over_base_ring): @@ -329,7 +329,7 @@ class Connected(CategoryWithAxiom_over_base_ring): sage: from sage.categories.manifolds import Manifolds sage: C = Manifolds(RR).Connected() - sage: TestSuite(C).run(skip="_test_category_over_bases") + sage: TestSuite(C).run(skip='_test_category_over_bases') """ diff --git a/src/sage/categories/map.pyx b/src/sage/categories/map.pyx index b420adb4d76..3ee42fc0157 100644 --- a/src/sage/categories/map.pyx +++ b/src/sage/categories/map.pyx @@ -401,10 +401,10 @@ cdef class Map(Element): INPUT: - - ``slots`` -- A dictionary of slots to be updated. - The dictionary must have the keys ``'_domain'`` and + - ``slots`` -- dictionary of slots to be updated; + the dictionary must have the keys ``'_domain'`` and ``'_codomain'``, and may have the keys ``'_repr_type_str'`` - and ``'_is_coercion'``. + and ``'_is_coercion'`` TESTS: @@ -509,7 +509,7 @@ cdef class Map(Element): .. NOTE:: - By default, the string ``"Generic"`` is returned. Subclasses may overload this method. + By default, the string ``'Generic'`` is returned. Subclasses may overload this method. EXAMPLES:: @@ -634,7 +634,7 @@ cdef class Map(Element): def category_for(self): """ - Returns the category self is a morphism for. + Return the category ``self`` is a morphism for. .. NOTE:: @@ -857,7 +857,7 @@ cdef class Map(Element): def __mul__(self, right): r""" - The multiplication * operator is operator composition + The multiplication * operator is operator composition. IMPLEMENTATION: @@ -937,7 +937,7 @@ cdef class Map(Element): INPUT: - - ``self`` -- a Map in some ``Hom(Y, Z, category_left)`` + - ``self`` -- a Map in some ``Hom(Y, Z, category_left)`` - ``right`` -- a Map in some ``Hom(X, Y, category_right)`` OUTPUT: @@ -977,7 +977,7 @@ cdef class Map(Element): INPUT: - ``self``, ``right`` -- maps - - homset -- a homset + - ``homset`` -- a homset ASSUMPTION: @@ -1139,7 +1139,7 @@ cdef class Map(Element): OUTPUT: An element of Hom(X, Z) obtained by composing self with `\phi`. If - no canonical `\phi` exists, a :class:`TypeError` is raised. + no canonical `\phi` exists, a :exc:`TypeError` is raised. EXAMPLES:: @@ -1183,8 +1183,8 @@ cdef class Map(Element): OUTPUT: - An element of Hom(X, Z) obtained by composing self with `\phi`. If - no canonical `\phi` exists, a :class:`TypeError` is raised. + An element of Hom(X, Z) obtained by composing ``self`` with `\phi`. If + no canonical `\phi` exists, a :exc:`TypeError` is raised. EXAMPLES:: @@ -1357,7 +1357,7 @@ cdef class Section(Map): """ INPUT: - A map. + - ``map`` -- a map TESTS:: @@ -1499,9 +1499,9 @@ cdef class FormalCompositeMap(Map): """ INPUT: - - ``parent``: a homset - - ``first``: a map or a list of maps - - ``second``: a map or None + - ``parent`` -- a homset + - ``first`` -- a map or a list of maps + - ``second`` -- a map or None .. NOTE:: @@ -1711,13 +1711,12 @@ cdef class FormalCompositeMap(Map): Traceback (most recent call last): ... IndexError: list index out of range - """ return self.__list[i] cpdef Element _call_(self, x): """ - Call with a single argument + Call with a single argument. TESTS:: @@ -1766,7 +1765,7 @@ cdef class FormalCompositeMap(Map): def _repr_type(self): """ - Return a string describing the type of ``self``, namely "Composite" + Return a string describing the type of ``self``, namely "Composite". TESTS:: @@ -1792,7 +1791,7 @@ cdef class FormalCompositeMap(Map): def _repr_defn(self): """ - Return a string describing the definition of ``self`` + Return a string describing the definition of ``self``. The return value is obtained from the string representations of the two constituents. @@ -1887,7 +1886,7 @@ cdef class FormalCompositeMap(Map): """ Tell whether ``self`` is injective. - It raises :class:`NotImplementedError` if it cannot be determined. + It raises :exc:`NotImplementedError` if it cannot be determined. EXAMPLES:: @@ -1932,7 +1931,6 @@ cdef class FormalCompositeMap(Map): sage: f = QQ.hom(QQbar) * ZZ.hom(QQ) # needs sage.rings.number_field sage: f.is_injective() # needs sage.rings.number_field True - """ try: # we try the category first @@ -1962,7 +1960,7 @@ cdef class FormalCompositeMap(Map): """ Tell whether ``self`` is surjective. - It raises :class:`NotImplementedError` if it cannot be determined. + It raises :exc:`NotImplementedError` if it cannot be determined. EXAMPLES:: diff --git a/src/sage/categories/metric_spaces.py b/src/sage/categories/metric_spaces.py index c8e36669601..e53ebe7bfee 100644 --- a/src/sage/categories/metric_spaces.py +++ b/src/sage/categories/metric_spaces.py @@ -227,7 +227,7 @@ def dist(self, b): class Homsets(HomsetsCategory): """ - The category of homsets of metric spaces + The category of homsets of metric spaces. It consists of the metric maps, that is, the Lipschitz functions with Lipschitz constant 1. diff --git a/src/sage/categories/modules.py b/src/sage/categories/modules.py index 990fcdfb456..d6d63b4df0a 100644 --- a/src/sage/categories/modules.py +++ b/src/sage/categories/modules.py @@ -45,7 +45,7 @@ class Modules(Category_module): INPUT: - ``base_ring`` -- a ring `R` or subcategory of ``Rings()`` - - ``dispatch`` -- a boolean (for internal use; default: ``True``) + - ``dispatch`` -- boolean (for internal use; default: ``True``) When the base ring is a field, the category of vector spaces is returned instead (unless ``dispatch == False``). @@ -558,7 +558,6 @@ def extra_super_categories(self): sage: Modules(QQ).FiniteDimensional().TensorProducts().FiniteDimensional() Category of tensor products of finite dimensional vector spaces over Rational Field - """ return [self.base_category()] @@ -637,7 +636,7 @@ def linear_combination(self, iter_of_elements_coeff, factor_on_left=True): @cached_method def tensor_square(self): """ - Returns the tensor square of ``self`` + Return the tensor square of ``self``. EXAMPLES:: @@ -660,7 +659,7 @@ def module_morphism(self, *, function, category=None, codomain, **keywords): INPUT: - - ``self`` -- a parent `X` in ``Modules(R)``. + - ``self`` -- a parent `X` in ``Modules(R)`` - ``function`` -- a function `f` from `X` to `Y` @@ -681,7 +680,6 @@ def module_morphism(self, *, function, category=None, codomain, **keywords): 2-dimensional vector space over the Rational Field sage: neg(e[0]) Element -e_0 of the 2-dimensional vector space over the Rational Field - """ # Make sure that we only create a module morphism, even if # domain and codomain have more structure @@ -699,7 +697,7 @@ def quotient(self, submodule, check=True, **kwds): something that can be turned into one via ``self.submodule(submodule)`` - - ``check``, other keyword arguments: passed on to + - ``check``, other keyword arguments -- passed on to :meth:`quotient_module`. This method just delegates to :meth:`quotient_module`. @@ -717,7 +715,6 @@ def quotient(self, submodule, check=True, **kwds): - """ return self.quotient_module(submodule, check=check, **kwds) @@ -837,7 +834,7 @@ def extra_super_categories(self): class CartesianProducts(CartesianProductsCategory): """ - The category of modules constructed as Cartesian products of modules + The category of modules constructed as Cartesian products of modules. This construction gives the direct product of modules. The implementation is based on the following resources: @@ -988,9 +985,9 @@ def tensor_factors(self): sage: # needs sage.modules sage: F = CombinatorialFreeModule(ZZ, [1,2]) - sage: F.rename("F") + sage: F.rename('F') sage: G = CombinatorialFreeModule(ZZ, [3,4]) - sage: G.rename("G") + sage: G.rename('G') sage: T = tensor([F, G]); T F # G sage: T.tensor_factors() diff --git a/src/sage/categories/modules_with_basis.py b/src/sage/categories/modules_with_basis.py index ea691177704..7b51d82c7ba 100644 --- a/src/sage/categories/modules_with_basis.py +++ b/src/sage/categories/modules_with_basis.py @@ -68,8 +68,8 @@ class ModulesWithBasis(CategoryWithAxiom_over_base_ring): Let `X` and `Y` be two modules with basis. We can build `Hom(X,Y)`:: - sage: X = CombinatorialFreeModule(QQ, [1,2]); X.rename("X") # needs sage.modules - sage: Y = CombinatorialFreeModule(QQ, [3,4]); Y.rename("Y") # needs sage.modules + sage: X = CombinatorialFreeModule(QQ, [1,2]); X.rename('X') # needs sage.modules + sage: Y = CombinatorialFreeModule(QQ, [3,4]); Y.rename('Y') # needs sage.modules sage: H = Hom(X, Y); H # needs sage.modules Set of Morphisms from X to Y in Category of finite dimensional vector spaces with basis over Rational Field @@ -139,7 +139,6 @@ class ModulesWithBasis(CategoryWithAxiom_over_base_ring): 0 sage: TestSuite(ModulesWithBasis(ZZ)).run() - """ def _call_(self, x): @@ -241,7 +240,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, INPUT: - ``self`` -- a parent `X` in ``ModulesWithBasis(R)`` with - basis `x=(x_i)_{i\in I}`. + basis `x=(x_i)_{i\in I}` Exactly one of the four following options must be specified in order to define the morphism: @@ -249,7 +248,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, - ``on_basis`` -- a function `f` from `I` to `Y` - ``diagonal`` -- a function `d` from `I` to `R` - ``function`` -- a function `f` from `X` to `Y` - - ``matrix`` -- a matrix of size `\dim Y \times \dim X` + - ``matrix`` -- a matrix of size `\dim Y \times \dim X` (if the keyword ``side`` is set to ``'left'``) or `\dim Y \times \dim X` (if this keyword is ``'right'``) @@ -264,28 +263,28 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, can be used (with care) to define affine maps. Only meaningful with ``on_basis``. - - ``position`` -- a non-negative integer specifying which + - ``position`` -- nonnegative integer specifying which positional argument is used as the input of the function `f` (default: 0); this is currently only used with ``on_basis``. - - ``triangular`` -- (default: ``None``) ``"upper"`` or - ``"lower"`` or ``None``: + - ``triangular`` -- (default: ``None``) ``'upper'`` or + ``'lower'`` or ``None``: - * ``"upper"`` -- if the + * ``'upper'`` -- if the :meth:`~ModulesWithBasis.ElementMethods.leading_support` of the image of the basis vector `x_i` is `i`, or - * ``"lower"`` -- if the + * ``'lower'`` -- if the :meth:`~ModulesWithBasis.ElementMethods.trailing_support` of the image of the basis vector `x_i` is `i`. - - ``unitriangular`` -- (default: ``False``) a boolean. - Only meaningful for a triangular morphism. + - ``unitriangular`` -- boolean (default: ``False``); + only meaningful for a triangular morphism. As a shorthand, one may use ``unitriangular="lower"`` - for ``triangular="lower", unitriangular=True``. + for ``triangular='lower', unitriangular=True``. - - ``side`` -- "left" or "right" (default: "left") - Only meaningful for a morphism built from a matrix. + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'left'``); + only meaningful for a morphism built from a matrix EXAMPLES: @@ -302,8 +301,8 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, :: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename("X") - sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename("Y") + sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename('X') + sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename('Y') sage: def f(i): ....: return Y.monomial(i) + 2*Y.monomial(i+1) sage: phi = X.module_morphism(f, codomain=Y) @@ -437,7 +436,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, and `Y` have the same index set `I`:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(ZZ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(ZZ, [1, 2, 3]); X.rename('X') sage: from sage.arith.misc import factorial sage: phi = X.module_morphism(diagonal=factorial, codomain=X) sage: x = X.basis() @@ -451,9 +450,9 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, and `Y` is `m`:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename("X") + sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename('X') sage: x = X.basis() - sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename("Y") + sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename('Y') sage: y = Y.basis() sage: m = matrix([[0,1,2], [3,5,0]]) sage: phi = X.module_morphism(matrix=m, codomain=Y) @@ -473,10 +472,10 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, sage: # needs sage.modules sage: I = list(range(1, 200)) - sage: X = CombinatorialFreeModule(QQ, I); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(QQ, I); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(QQ, I); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(QQ, I); Y.rename('Y'); y = Y.basis() sage: f = Y.sum_of_monomials * divisors - sage: phi = X.module_morphism(f, triangular="upper", codomain=Y) + sage: phi = X.module_morphism(f, triangular='upper', codomain=Y) sage: phi(x[2]) B[1] + B[2] sage: phi(x[6]) @@ -500,7 +499,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, sage: from sage.modules.with_basis.morphism import TriangularModuleMorphismFromFunction sage: def f(x): return x + X.term(0, sum(x.coefficients())) sage: phi = X.module_morphism(function=f, codomain=X, - ....: triangular="upper") + ....: triangular='upper') sage: phi(x[2] + 3*x[4]) 4*B[0] + B[2] + 3*B[4] sage: phi.preimage(_) @@ -526,7 +525,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, TESTS:: - sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename('X') # needs sage.modules sage: phi = X.module_morphism(codomain=X) # needs sage.modules Traceback (most recent call last): ... @@ -535,7 +534,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, :: - sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename('X') # needs sage.modules sage: phi = X.module_morphism(diagonal=factorial, matrix=matrix(), # needs sage.modules ....: codomain=X) Traceback (most recent call last): @@ -545,7 +544,7 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, :: - sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename('X') # needs sage.modules sage: phi = X.module_morphism(matrix=factorial, codomain=X) # needs sage.modules Traceback (most recent call last): ... @@ -553,12 +552,11 @@ def module_morphism(self, on_basis=None, matrix=None, function=None, :: - sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename('X') # needs sage.modules sage: phi = X.module_morphism(diagonal=3, codomain=X) # needs sage.modules Traceback (most recent call last): ... ValueError: diagonal (=3) should be a function - """ if len([x for x in [matrix, on_basis, function, diagonal] if x is not None]) != 1: raise ValueError("module_morphism() takes exactly one option out of `matrix`, `on_basis`, `function`, `diagonal`") @@ -599,7 +597,7 @@ def _repr_(self): Free module generated by {1, 2, 3} over Rational Field sage: C._name = "foobar"; C foobar over Rational Field - sage: C.rename("barfoo"); C + sage: C.rename('barfoo'); C barfoo sage: class FooBar(Parent): @@ -682,9 +680,9 @@ def echelon_form(self, elements, row_reduced=False, order=None): INPUT: - - ``elements`` -- a list or finite iterable of elements of ``self`` - - ``row_reduced`` -- (default: ``False``) whether to compute the - basis for the row reduced echelon form + - ``elements`` -- list or finite iterable of elements of ``self`` + - ``row_reduced`` -- boolean (default: ``False``); whether to + compute the basis for the row reduced echelon form - ``order`` -- (optional) either something that can be converted into a tuple or a key function @@ -736,13 +734,13 @@ def submodule(self, gens, check=True, already_echelonized=False, INPUT: - - ``gens`` -- a list or family of elements of ``self`` - - ``check`` -- (default: ``True``) whether to verify that the - elements of ``gens`` are in ``self`` - - ``already_echelonized`` -- (default: ``False``) whether + - ``gens`` -- list or family of elements of ``self`` + - ``check`` -- boolean (default: ``True``); whether to verify that + the elements of ``gens`` are in ``self`` + - ``already_echelonized`` -- boolean (default: ``False``); whether the elements of ``gens`` are already in (not necessarily reduced) echelon form - - ``unitriangular`` -- (default: ``False``) whether + - ``unitriangular`` -- boolean (default: ``False``); whether the lift morphism is unitriangular - ``support_order`` -- (optional) either something that can be converted into a tuple or a key function @@ -779,7 +777,7 @@ def submodule(self, gens, check=True, already_echelonized=False, `y_1 - x_1 - x_2`, and its basis elements are indexed by `0` and `1`:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x") + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x') sage: x = X.basis() sage: gens = [x[0] - x[1], x[1] - x[2]]; gens [x[0] - x[1], x[1] - x[2]] @@ -802,7 +800,7 @@ def submodule(self, gens, check=True, already_echelonized=False, submodule whose index set coincides with the index set of the family:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x") + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x') sage: x = X.basis() sage: gens = Family({1: x[0] - x[1], 3: x[1] - x[2]}); gens Finite family {1: x[0] - x[1], 3: x[1] - x[2]} @@ -827,7 +825,7 @@ def submodule(self, gens, check=True, already_echelonized=False, a basis (an explicit basis will be computed):: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x") + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x') sage: x = X.basis() sage: gens = [x[0] - x[1], 2*x[1] - 2*x[2], x[0] - x[2]]; gens [x[0] - x[1], 2*x[1] - 2*x[2], x[0] - x[2]] @@ -942,7 +940,7 @@ def quotient_module(self, submodule, check=True, already_echelonized=False, cate EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x") + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x') sage: x = X.basis() sage: Y = X.quotient_module([x[0] - x[1], x[1] - x[2]], ....: already_echelonized=True) @@ -983,7 +981,7 @@ def tensor(*parents, **kwargs): EXAMPLES:: sage: C = AlgebrasWithBasis(QQ) - sage: A = C.example(); A.rename("A") # needs sage.combinat sage.modules + sage: A = C.example(); A.rename('A') # needs sage.combinat sage.modules sage: A.tensor(A, A) # needs sage.combinat sage.modules A # A # A sage: A.rename(None) # needs sage.combinat sage.modules @@ -1127,7 +1125,7 @@ def sum_of_monomials(self): INPUT: - - ``indices`` -- a list (or iterable) of indices of basis + - ``indices`` -- list (or iterable) of indices of basis elements EXAMPLES:: @@ -1170,9 +1168,7 @@ def term(self, index, coeff=None): - ``index`` -- the index of a basis element - ``coeff`` -- an element of the coefficient ring (default: one) - OUTPUT: - - ``coeff * B[index]``, where ``B`` is the basis of ``self``. + OUTPUT: ``coeff * B[index]``, where ``B`` is the basis of ``self`` EXAMPLES:: @@ -1193,7 +1189,7 @@ def sum_of_terms(self, terms): INPUT: - - ``terms`` -- a list (or iterable) of pairs ``(index, coeff)`` + - ``terms`` -- list (or iterable) of pairs ``(index, coeff)`` OUTPUT: @@ -1368,7 +1364,7 @@ def random_element(self, n=2): ALGORITHM: - Return a sum of ``n`` terms, each of which is formed by + Return a sum of `n` terms, each of which is formed by multiplying a random element of the base ring by a random element of the group. @@ -1409,7 +1405,6 @@ def random_element(self, n=2): sage: F = Foo(QQ, tuple(), category=C) # needs sage.modules sage: F.random_element() == F.zero() # needs sage.modules True - """ indices = self.basis().keys() a = self.zero() @@ -1440,9 +1435,9 @@ def monomial_coefficients(self, copy=True): INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally - represented by a dictionary ``d``, then make a copy of ``d``; - if ``False``, then this can cause undesired behavior by + - ``copy`` -- boolean (default: ``True``); if ``self`` is + internally represented by a dictionary ``d``, then make a copy of + ``d``; if ``False``, then this can cause undesired behavior by mutating ``d`` EXAMPLES:: @@ -1657,7 +1652,7 @@ def support(self): """ Return an iterable of the objects indexing the basis of ``self.parent()`` whose corresponding coefficients of - ``self`` are non-zero. + ``self`` are nonzero. This method returns these objects in an arbitrary order. @@ -1698,7 +1693,7 @@ def monomials(self): The monomials of an element `a` are defined to be the basis elements whose corresponding coefficients of `a` are - non-zero. + nonzero. EXAMPLES:: @@ -1717,7 +1712,7 @@ def monomials(self): def terms(self): """ - Return a list of the (non-zero) terms of ``self`` (in an + Return a list of the (nonzero) terms of ``self`` (in an arbitrary order). .. SEEALSO:: :meth:`monomials` @@ -1739,12 +1734,12 @@ def terms(self): def coefficients(self, sort=True): """ - Return a list of the (non-zero) coefficients appearing on + Return a list of the (nonzero) coefficients appearing on the basis elements in ``self`` (in an arbitrary order). INPUT: - - ``sort`` -- (default: ``True``) to sort the coefficients + - ``sort`` -- boolean (default: ``True``); to sort the coefficients based upon the default ordering of the indexing set .. SEEALSO:: @@ -1786,7 +1781,7 @@ def support_of_term(self): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, [1,2,3,4]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(QQ, [1,2,3,4]); X.rename('X') # needs sage.modules sage: X.monomial(2).support_of_term() # needs sage.modules 2 sage: X.term(3, 2).support_of_term() # needs sage.modules @@ -1818,7 +1813,7 @@ def leading_support(self, *args, **kwds): sage: # needs sage.modules sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]) - sage: X.rename("X"); x = X.basis() + sage: X.rename('X'); x = X.basis() sage: x = 3*X.monomial(1) + 2*X.monomial(2) + 4*X.monomial(3) sage: x.leading_support() 3 @@ -1853,7 +1848,7 @@ def leading_item(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + 4*X.monomial(3) sage: x.leading_item() (3, 4) @@ -1883,7 +1878,7 @@ def leading_monomial(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.leading_monomial() B[3] @@ -1912,7 +1907,7 @@ def leading_coefficient(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.leading_coefficient() 1 @@ -1941,7 +1936,7 @@ def leading_term(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.leading_term() B[3] @@ -1967,7 +1962,7 @@ def trailing_support(self, *args, **kwds): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') # needs sage.modules sage: x = 3*X.monomial(1) + 2*X.monomial(2) + 4*X.monomial(3) # needs sage.modules sage: x.trailing_support() # needs sage.modules 1 @@ -1998,7 +1993,7 @@ def trailing_item(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.trailing_item() (1, 3) @@ -2028,7 +2023,7 @@ def trailing_monomial(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.trailing_monomial() B[1] @@ -2057,7 +2052,7 @@ def trailing_coefficient(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.trailing_coefficient() 3 @@ -2086,7 +2081,7 @@ def trailing_term(self, *args, **kwds): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = 3*X.monomial(1) + 2*X.monomial(2) + X.monomial(3) sage: x.trailing_term() 3*B[1] @@ -2103,7 +2098,7 @@ def trailing_term(self, *args, **kwds): def map_coefficients(self, f, new_base_ring=None): """ - Return the element obtained by applying ``f`` to the non-zero + Return the element obtained by applying ``f`` to the nonzero coefficients of ``self``. If ``f`` is a :class:`sage.categories.map.Map`, then the resulting @@ -2167,7 +2162,6 @@ def map_coefficients(self, f, new_base_ring=None): 0 sage: B['a'].map_coefficients(lambda c: GF(2)(c), QQ) B['a'] - """ R = self.parent() if isinstance(f, Map): @@ -2334,8 +2328,8 @@ def __call_on_basis__(self, **options): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename("X") - sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename("Y") + sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename('X') + sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename('Y') sage: H = Hom(X, Y) sage: x = X.basis() sage: def on_basis(i): @@ -2351,9 +2345,9 @@ def __call_on_basis__(self, **options): Diagonal functions can be constructed using the ``diagonal`` option:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1,2,3,4]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1,2,3,4]); X.rename('X') sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4], - ....: key="Y"); Y.rename("Y") + ....: key='Y'); Y.rename('Y') sage: H = Hom(X, Y) sage: x = X.basis() sage: phi = H(diagonal=lambda x: x^2) @@ -2374,8 +2368,8 @@ def __call_on_basis__(self, **options): We check that the homset category is properly set up:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename("X") - sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename("Y") + sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename('X') + sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename('Y') sage: H = Hom(X, Y) sage: H.zero().category_for() Category of finite dimensional vector spaces with basis over Rational Field @@ -2397,8 +2391,8 @@ def on_basis(self): EXAMPLES:: sage: # needs sage.modules - sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename("X") - sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename("Y") + sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename('X') + sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4]); Y.rename('Y') sage: H = Hom(X, Y) sage: x = X.basis() sage: f = H(lambda x: Y.zero()).on_basis() @@ -2423,7 +2417,7 @@ def _on_basis(self, i): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename("X") # needs sage.modules + sage: X = CombinatorialFreeModule(QQ, [1,2,3]); X.rename('X') # needs sage.modules sage: phi = End(X)(lambda x: 2*x) # needs sage.modules sage: phi._on_basis(3) # needs sage.modules 2*B[3] @@ -2496,13 +2490,13 @@ def extra_super_categories(self): class ParentMethods: """ - Implements operations on tensor products of modules with basis. + Implement operations on tensor products of modules with basis. """ pass class ElementMethods: """ - Implements operations on elements of tensor products of modules + Implement operations on elements of tensor products of modules with basis. """ @@ -2533,10 +2527,10 @@ def apply_multilinear_morphism(self, f, codomain=None): examples, with two modules `A` and `B`:: sage: # needs sage.modules - sage: A = CombinatorialFreeModule(ZZ, [1,2], prefix="A") - sage: A.rename("A") - sage: B = CombinatorialFreeModule(ZZ, [3,4], prefix="B") - sage: B.rename("B") + sage: A = CombinatorialFreeModule(ZZ, [1,2], prefix='A') + sage: A.rename('A') + sage: B = CombinatorialFreeModule(ZZ, [3,4], prefix='B') + sage: B.rename('B') and `f` the bilinear morphism `(a,b) \mapsto b \otimes a` from `A \times B` to `B \otimes A`:: @@ -2586,8 +2580,8 @@ def apply_multilinear_morphism(self, f, codomain=None): module with basis with a different base ring:: sage: # needs sage.modules - sage: C = CombinatorialFreeModule(QQ, [(1,3),(2,4)], prefix="C") - sage: C.rename("C") + sage: C = CombinatorialFreeModule(QQ, [(1,3),(2,4)], prefix='C') + sage: C.rename('C') sage: def f(a, b): ....: return C.sum_of_terms([((1,3), QQ(a[1]*b[3])), ....: ((2,4), QQ(a[2]*b[4]))]) diff --git a/src/sage/categories/monoids.py b/src/sage/categories/monoids.py index 654bb195172..877e9026199 100644 --- a/src/sage/categories/monoids.py +++ b/src/sage/categories/monoids.py @@ -94,7 +94,7 @@ def free(index_set=None, names=None, **kwds): - ``index_set`` -- (optional) an index set for the generators; if an integer, then this represents `\{0, 1, \ldots, n-1\}` - - ``names`` -- a string or list/tuple/iterable of strings + - ``names`` -- string or list/tuple/iterable of strings (default: ``'x'``); the generator names or name prefix EXAMPLES:: @@ -148,7 +148,7 @@ def prod(self, args): INPUT: - - ``args`` -- a list (or iterable) of elements of ``self`` + - ``args`` -- list (or iterable) of elements of ``self`` Returns the product of the elements in ``args``, as an element of ``self``. @@ -292,11 +292,11 @@ def is_one(self): def _pow_int(self, n): r""" - Return ``self`` to the `n^{th}` power. + Return ``self`` to the `n`-th power. INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -308,11 +308,11 @@ def _pow_int(self, n): def _pow_naive(self, n): r""" - Return ``self`` to the `n^{th}` power (naive implementation). + Return ``self`` to the `n`-th power (naive implementation). INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer This naive implementation does not use binary exponentiation; there are cases where this is actually @@ -411,7 +411,7 @@ def free(index_set=None, names=None, **kwds): - ``index_set`` -- (optional) an index set for the generators; if an integer, then this represents `\{0, 1, \ldots, n-1\}` - - ``names`` -- a string or list/tuple/iterable of strings + - ``names`` -- string or list/tuple/iterable of strings (default: ``'x'``); the generator names or name prefix EXAMPLES:: @@ -472,7 +472,7 @@ class ParentMethods: def one(self): """ - Returns the multiplicative unit of this monoid, + Return the multiplicative unit of this monoid, obtained by retracting that of the ambient monoid. EXAMPLES:: @@ -677,7 +677,7 @@ def lift(i, gen): gens_prod = cartesian_product([Family(M.monoid_generators(), lambda g: (i, g)) for i, M in enumerate(F)]) - return Family(gens_prod, lift, name="gen") + return Family(gens_prod, lift, name='gen') class ElementMethods: def multiplicative_order(self): diff --git a/src/sage/categories/morphism.pyx b/src/sage/categories/morphism.pyx index 30fe12271c3..2ed9514a469 100644 --- a/src/sage/categories/morphism.pyx +++ b/src/sage/categories/morphism.pyx @@ -297,13 +297,12 @@ cdef class Morphism(Map): AssertionError: coercion from Univariate Polynomial Ring in x over Integer Ring to Univariate Polynomial Ring in z over Integer Ring already registered or discovered - """ self._codomain.register_coercion(self) def register_as_conversion(self): r""" - Register this morphism as a conversion to Sage's coercion model + Register this morphism as a conversion to Sage's coercion model. (see :mod:`sage.structure.coerce`). @@ -442,7 +441,6 @@ cdef class Morphism(Map): sage: f = Hom(ZZ,Zmod(1)).an_element() sage: bool(f) # indirect doctest False - """ try: return self._is_nonzero() @@ -575,7 +573,7 @@ cdef class SetMorphism(Morphism): - ``parent`` -- a Homset - ``function`` -- a Python function that takes elements - of the domain as input and returns elements of the codomain. + of the domain as input and returns elements of the codomain EXAMPLES:: @@ -628,7 +626,6 @@ cdef class SetMorphism(Morphism): sage: f(2,'hello world',test=1) # indirect doctest foo called with ('hello world',) {'test': 1} 2 - """ try: return self._function(x, *args, **kwds) @@ -637,11 +634,11 @@ cdef class SetMorphism(Morphism): cdef dict _extra_slots(self): """ - INPUT: + Extend the dictionary with extra slots for this class. - - ``_slots`` -- a dictionary + INPUT: - Extends the dictionary with extra slots for this class. + - ``_slots`` -- dictionary EXAMPLES:: @@ -661,7 +658,7 @@ cdef class SetMorphism(Morphism): """ INPUT: - - ``_slots`` -- a dictionary + - ``_slots`` -- dictionary Updates the slots of ``self`` from the data in the dictionary @@ -688,7 +685,7 @@ cdef class SetMorphism(Morphism): cpdef bint _eq_c_impl(self, Element other) noexcept: """ - Equality test + Equality test. EXAMPLES:: @@ -704,7 +701,6 @@ cdef class SetMorphism(Morphism): False sage: f._eq_c_impl(1) False - """ return isinstance(other, SetMorphism) and self.parent() == other.parent() and self._function == (other)._function @@ -712,9 +708,9 @@ cdef class SetMorphism(Morphism): """ INPUT: - - ``self`` -- SetMorphism + - ``self`` -- SetMorphism - ``right`` -- any object - - ``op`` -- integer + - ``op`` -- integer EXAMPLES:: @@ -751,7 +747,7 @@ cdef class SetIsomorphism(SetMorphism): - ``parent`` -- a Homset - ``function`` -- a Python function that takes elements - of the domain as input and returns elements of the codomain. + of the domain as input and returns elements of the codomain EXAMPLES:: @@ -808,7 +804,7 @@ cdef class SetIsomorphism(SetMorphism): INPUT: - - ``_slots`` -- a dictionary + - ``_slots`` -- dictionary EXAMPLES:: @@ -833,7 +829,7 @@ cdef class SetIsomorphism(SetMorphism): INPUT: - - ``_slots`` -- a dictionary + - ``_slots`` -- dictionary EXAMPLES:: diff --git a/src/sage/categories/noetherian_rings.py b/src/sage/categories/noetherian_rings.py index 231d3e8192c..fe0e80acc06 100644 --- a/src/sage/categories/noetherian_rings.py +++ b/src/sage/categories/noetherian_rings.py @@ -30,7 +30,7 @@ class NoetherianRings(Category): """ - The category of Noetherian rings + The category of Noetherian rings. A Noetherian ring is a commutative ring in which every ideal is finitely generated. diff --git a/src/sage/categories/number_fields.py b/src/sage/categories/number_fields.py index 8c6ed11d4c3..cc5571b5c07 100644 --- a/src/sage/categories/number_fields.py +++ b/src/sage/categories/number_fields.py @@ -96,7 +96,7 @@ def __contains__(self, x): def _call_(self, x): r""" Construct an object in this category from the data in ``x``, - or raise a :class:`TypeError`. + or raise a :exc:`TypeError`. EXAMPLES:: @@ -134,21 +134,22 @@ def zeta_function(self, prec=53, INPUT: - - ``prec`` -- optional integer (default 53) bits precision + - ``prec`` -- integer (default: 53); bits of precision - - ``max_imaginary_part`` -- optional real number (default 0) + - ``max_imaginary_part`` -- real (default: 0) - - ``max_asymp_coeffs`` -- optional integer (default 40) + - ``max_asymp_coeffs`` -- integer (default: 40) - - ``algorithm`` -- optional (default "pari") either "gp" or "pari" + - ``algorithm`` -- (default: ``'pari'``) either ``'gp'`` or + ``'pari'`` - OUTPUT: The zeta function of this number field. + OUTPUT: the zeta function of this number field - If algorithm is "gp", this returns an interface to Tim - Dokchitser's gp script for computing with L-functions. + If algorithm is ``'gp'``, this returns an interface to Tim + Dokchitser's gp script for computing with `L`-functions. - If algorithm is "pari", this returns instead an interface to Pari's - own general implementation of L-functions. + If algorithm is ``'pari'``, this returns instead an interface to Pari's + own general implementation of `L`-functions. EXAMPLES:: @@ -168,13 +169,13 @@ def zeta_function(self, prec=53, Using the algorithm "pari":: sage: K. = NumberField(ZZ['x'].0^2 + ZZ['x'].0 - 1) # needs sage.rings.number_field - sage: Z = K.zeta_function(algorithm="pari") # needs sage.rings.number_field sage.symbolic + sage: Z = K.zeta_function(algorithm='pari') # needs sage.rings.number_field sage.symbolic sage: Z(-1) # needs sage.rings.number_field sage.symbolic 0.0333333333333333 sage: x = polygen(QQ, 'x') sage: L. = NumberField([x^2 - 5, x^2 + 3, x^2 + 1]) # needs sage.rings.number_field - sage: Z = L.zeta_function(algorithm="pari") # needs sage.rings.number_field sage.symbolic + sage: Z = L.zeta_function(algorithm='pari') # needs sage.rings.number_field sage.symbolic sage: Z(5) # needs sage.rings.number_field sage.symbolic 1.00199015670185 diff --git a/src/sage/categories/objects.py b/src/sage/categories/objects.py index 3668827f5bd..bad56fcb0f8 100644 --- a/src/sage/categories/objects.py +++ b/src/sage/categories/objects.py @@ -41,7 +41,7 @@ class Objects(Category_singleton): def additional_structure(self): """ - Return ``None`` + Return ``None``. Indeed, by convention, the category of objects defines no additional structure. diff --git a/src/sage/categories/poor_man_map.py b/src/sage/categories/poor_man_map.py index ac05114699c..3195f14bab8 100644 --- a/src/sage/categories/poor_man_map.py +++ b/src/sage/categories/poor_man_map.py @@ -17,9 +17,9 @@ class PoorManMap(sage.structure.sage_object.SageObject): """ - A class for maps between sets which are not (yet) modeled by parents + A class for maps between sets which are not (yet) modeled by parents. - Could possibly disappear when all combinatorial classes / enumerated sets will be parents + Could possibly disappear when all combinatorial classes / enumerated sets will be parents. INPUT: @@ -56,7 +56,6 @@ class PoorManMap(sage.structure.sage_object.SageObject): sage: h = PoorManMap(sqrt, domain=(1, 4, 9), codomain=(1, 2, 3)) sage: i == g*h True - """ def __init__(self, function, domain=None, codomain=None, name=None): """ @@ -68,7 +67,6 @@ def __init__(self, function, domain=None, codomain=None, name=None): sage: TestSuite(f).run() sage: TestSuite(f*g).run() - """ from collections.abc import Iterable if not isinstance(function, Iterable): @@ -110,7 +108,7 @@ def domain(self): def codomain(self): """ - Returns the codomain of ``self`` + Return the codomain of ``self``. EXAMPLES:: @@ -135,7 +133,6 @@ def __eq__(self, other): sage: h4 = PoorManMap(lambda x: x, domain=(1,2,3), codomain=(1,2,6)) sage: f == g, f == h1, f == h2, f == h3, f == h4, f == 1, 1 == f (True, False, False, False, False, False, False) - """ if isinstance(other, PoorManMap): return (self._functions == other._functions @@ -160,7 +157,6 @@ def __ne__(self, other): sage: h4 = PoorManMap(lambda x: x, domain=(1,2,3), codomain=(1,2,6)) sage: f != g, f != h1, f != h2, f != h3, f != h4, f != 1, 1 != f (False, True, True, True, True, True, True) - """ return not (self == other) @@ -175,20 +171,19 @@ def __hash__(self): sage: g = PoorManMap(factorial, domain=(1,2,3), codomain=(1,2,6)) sage: hash(f) == hash(g) True - """ return hash((self._functions, self._domain, self._codomain, self._name)) def __mul__(self, other): r""" - Composition + Composition. INPUT: - - ``self`` -- a map `f` - - ``other`` -- a map `g` + - ``self`` -- a map `f` + - ``other`` -- a map `g` - Returns the composition map `f\circ g` of `f`` and `g` + Returns the composition map `f\circ g` of `f` and `g` EXAMPLES:: @@ -255,7 +250,6 @@ def __call__(self, *args): sage: g = PoorManMap(lambda x: -x, domain=(2,3,4), codomain=(-2,-3,-4)) sage: (g*f)(2) -3 - """ for function in reversed(self._functions): args = [function(*args)] diff --git a/src/sage/categories/posets.py b/src/sage/categories/posets.py index 0d846648e6f..9b30798d0d4 100644 --- a/src/sage/categories/posets.py +++ b/src/sage/categories/posets.py @@ -88,7 +88,6 @@ class Posets(Category): sage: C = Posets() sage: TestSuite(C).run() - """ @cached_method def super_categories(self): @@ -165,7 +164,7 @@ def le(self, x, y): INPUT: - - ``x``, ``y`` -- elements of ``self``. + - ``x``, ``y`` -- elements of ``self`` EXAMPLES:: @@ -184,7 +183,7 @@ def lt(self, x, y): INPUT: - - ``x``, ``y`` -- elements of ``self``. + - ``x``, ``y`` -- elements of ``self`` This default implementation delegates the work to :meth:`le`. @@ -206,7 +205,7 @@ def ge(self, x, y): INPUT: - - ``x``, ``y`` -- elements of ``self``. + - ``x``, ``y`` -- elements of ``self`` This default implementation delegates the work to :meth:`le`. @@ -228,7 +227,7 @@ def gt(self, x, y): INPUT: - - ``x``, ``y`` -- elements of ``self``. + - ``x``, ``y`` -- elements of ``self`` This default implementation delegates the work to :meth:`lt`. @@ -310,17 +309,17 @@ def directed_subset(self, elements, direction): Return the order filter or the order ideal generated by a list of elements. - If ``direction`` is 'up', the order filter (upper set) is + If ``direction`` is ``'up'``, the order filter (upper set) is being returned. - If ``direction`` is 'down', the order ideal (lower set) is + If ``direction`` is ``'down'``, the order ideal (lower set) is being returned. INPUT: - - elements -- a list of elements. + - ``elements`` -- list of elements - - direction -- 'up' or 'down'. + - ``direction`` -- ``'up'`` or ``'down'`` EXAMPLES:: @@ -456,7 +455,7 @@ def is_order_ideal(self, o): INPUT: - - ``o`` -- a list (or set, or tuple) containing some elements of ``self`` + - ``o`` -- list (or set, or tuple) containing some elements of ``self`` EXAMPLES:: @@ -472,7 +471,6 @@ def is_order_ideal(self, o): True sage: P.is_order_ideal([1, 3, 4]) False - """ return all((u in self and all(x in o for x in self.lower_covers(u))) for u in o) @@ -483,7 +481,7 @@ def is_order_filter(self, o): INPUT: - - ``o`` -- a list (or set, or tuple) containing some elements of ``self`` + - ``o`` -- list (or set, or tuple) containing some elements of ``self`` EXAMPLES:: @@ -499,7 +497,6 @@ def is_order_filter(self, o): False sage: P.is_order_filter({3, 6, 12}) True - """ return all((u in self and all(x in o for x in self.upper_covers(u))) for u in o) @@ -515,9 +512,8 @@ def is_chain_of_poset(self, o, ordered=False): - ``o`` -- an iterable (e. g., list, set, or tuple) containing some elements of ``self`` - - ``ordered`` -- a Boolean (default: ``False``) which - decides whether the notion of a chain includes being - ordered + - ``ordered`` -- a Boolean (default: ``False``); decides + whether the notion of a chain includes being ordered OUTPUT: diff --git a/src/sage/categories/primer.py b/src/sage/categories/primer.py index aa8b134ac23..6afdc8f31d9 100644 --- a/src/sage/categories/primer.py +++ b/src/sage/categories/primer.py @@ -118,7 +118,7 @@ What makes binary powering work in the above examples? In both cases, we have *a set* endowed with a *multiplicative binary operation* which is *associative* and which has a unit element. Such a set is called a -*monoid*, and binary powering (to a non-negative power) works generally +*monoid*, and binary powering (to a nonnegative power) works generally for any monoid. Sage knows about monoids:: @@ -193,7 +193,7 @@ Those can be viewed graphically:: sage: g = Groups().category_graph() # needs sage.graphs - sage: g.set_latex_options(format="dot2tex") # needs sage.graphs sage.modules sage.plot + sage: g.set_latex_options(format='dot2tex') # needs sage.graphs sage.modules sage.plot sage: view(g) # not tested # needs sage.graphs sage.modules sage.plot In case ``dot2tex`` is not available, you can use instead:: @@ -203,7 +203,7 @@ Here is an overview of all categories in Sage:: sage: g = sage.categories.category.category_graph() # needs sage.graphs sage.groups sage.modules - sage: g.set_latex_options(format="dot2tex") # needs sage.graphs sage.modules sage.plot + sage: g.set_latex_options(format='dot2tex') # needs sage.graphs sage.modules sage.plot sage: view(g) # not tested # needs sage.graphs sage.modules sage.plot Wrap-up: generic algorithms in Sage are organized in a hierarchy of @@ -379,7 +379,7 @@ Category of objects] sage: g = EuclideanDomains().category_graph() # needs sage.graphs - sage: g.set_latex_options(format="dot2tex") # needs sage.graphs sage.plot + sage: g.set_latex_options(format='dot2tex') # needs sage.graphs sage.plot sage: view(g) # not tested # needs sage.graphs sage.plot A bit of help from computer science @@ -498,7 +498,7 @@ class implements: The full hierarchy is best viewed graphically:: sage: g = class_graph(m.__class__) # needs sage.combinat sage.graphs - sage: g.set_latex_options(format="dot2tex") # needs sage.combinat sage.graphs sage.plot + sage: g.set_latex_options(format='dot2tex') # needs sage.combinat sage.graphs sage.plot sage: view(g) # not tested # needs sage.combinat sage.graphs sage.plot Parallel hierarchy of classes for parents @@ -554,7 +554,7 @@ class implements: sage: # needs sage.combinat sage.graphs sage.modules sage.plot sage: g = class_graph(m.__class__) sage: g.relabel(lambda x: x.replace("_",r"\_")) - sage: g.set_latex_options(format="dot2tex") + sage: g.set_latex_options(format='dot2tex') sage: view(g) # not tested .. NOTE:: @@ -1114,8 +1114,8 @@ class SubcategoryMethods: Let for example `A` and `B` be two parents, and let us construct the Cartesian product `A \times B \times B`:: - sage: A = AlgebrasWithBasis(QQ).example(); A.rename("A") # needs sage.combinat sage.modules - sage: B = HopfAlgebrasWithBasis(QQ).example(); B.rename("B") # needs sage.groups sage.modules + sage: A = AlgebrasWithBasis(QQ).example(); A.rename('A') # needs sage.combinat sage.modules + sage: B = HopfAlgebrasWithBasis(QQ).example(); B.rename('B') # needs sage.groups sage.modules sage: C = cartesian_product([A, B, B]); C # needs sage.combinat sage.groups sage.modules A (+) B (+) B @@ -1368,7 +1368,7 @@ class naming and introspection. Sage currently works around the How far should this be pushed? :class:`Fields` should definitely stay, but should :class:`FiniteGroups` or :class:`DivisionRings` be removed from the global namespace? Do we want to further - completely deprecate the notation ``FiniteGroups()` in favor of + completely deprecate the notation ``FiniteGroups()`` in favor of ``Groups().Finite()``? .. _category-primer-axioms-explosion: @@ -1405,7 +1405,7 @@ class naming and introspection. Sage currently works around the or for more advanced categories:: sage: g = HopfAlgebras(QQ).WithBasis().Graded().Connected().category_graph() # needs sage.graphs - sage: g.set_latex_options(format="dot2tex") # needs sage.graphs sage.plot + sage: g.set_latex_options(format='dot2tex') # needs sage.graphs sage.plot sage: view(g) # not tested # needs sage.graphs sage.plot Difference between axioms and regressive covariant functorial constructions diff --git a/src/sage/categories/principal_ideal_domains.py b/src/sage/categories/principal_ideal_domains.py index 89c25cc374f..c86d4f6ddf7 100644 --- a/src/sage/categories/principal_ideal_domains.py +++ b/src/sage/categories/principal_ideal_domains.py @@ -15,7 +15,7 @@ class PrincipalIdealDomains(Category_singleton): """ - The category of (constructive) principal ideal domains + The category of (constructive) principal ideal domains. By constructive, we mean that a single generator can be constructively found for any ideal given by a finite set of diff --git a/src/sage/categories/pushout.py b/src/sage/categories/pushout.py index 1b98e358511..0b5f0a85cdc 100644 --- a/src/sage/categories/pushout.py +++ b/src/sage/categories/pushout.py @@ -123,7 +123,6 @@ class ConstructionFunctor(Functor): b |--> a - b sage: F(f)(F(A)(x)*a) (a + b)*x - """ def __mul__(self, other): """ @@ -151,7 +150,6 @@ def __mul__(self, other): True sage: F*I is F True - """ if not isinstance(self, ConstructionFunctor) and not isinstance(other, ConstructionFunctor): raise CoercionException("Non-constructive product") @@ -179,7 +177,6 @@ def pushout(self, other): Poly[t](FractionField(...)) sage: P.pushout(F) Poly[t](FractionField(...)) - """ if self.rank > other.rank: return self * other @@ -253,7 +250,6 @@ def _repr_(self): sage: Q = ZZ.quo(2).construction()[0] sage: Q # indirect doctest QuotientFunctor - """ s = str(type(self)) import re @@ -278,7 +274,6 @@ def merge(self, other): sage: P.merge(F) sage: P.merge(P) Poly[t] - """ if self == other: return self @@ -307,7 +302,6 @@ def commutes(self, other): False sage: F.commutes(F) False - """ return False @@ -331,7 +325,6 @@ def expand(self): sage: FP = F*P sage: FP.expand() [FractionField, Poly[t]] - """ return [self] @@ -351,12 +344,12 @@ def common_base(self, other_functor, self_bases, other_bases): INPUT: - - ``other_functor`` -- a construction functor. + - ``other_functor`` -- a construction functor - - ``self_bases`` -- the arguments passed to this functor. + - ``self_bases`` -- the arguments passed to this functor - ``other_bases`` -- the arguments passed to the functor - ``other_functor``. + ``other_functor`` OUTPUT: @@ -389,14 +382,14 @@ def _raise_common_base_exception_(self, other_functor, INPUT: - - ``other_functor`` -- a functor. + - ``other_functor`` -- a functor - - ``self_bases`` -- the arguments passed to this functor. + - ``self_bases`` -- the arguments passed to this functor - ``other_bases`` -- the arguments passed to the functor - ``other_functor``. + ``other_functor`` - - ``reason`` -- a string or ``None`` (default). + - ``reason`` -- string or ``None`` (default) TESTS:: @@ -428,8 +421,8 @@ class CompositeConstructionFunctor(ConstructionFunctor): INPUT: - ``F1, F2,...``: A list of Construction Functors. The result is the - composition ``F1`` followed by ``F2`` followed by ... + - ``F1, F2,...`` -- a list of Construction Functors. The result is the + composition ``F1`` followed by ``F2`` followed by ... EXAMPLES:: @@ -459,7 +452,6 @@ def __init__(self, *args): Poly[y](FractionField(Poly[x](FractionField(...)))) sage: F == CompositeConstructionFunctor(*F.all) True - """ self.all = [] for c in args: @@ -491,7 +483,6 @@ def _apply_functor_to_morphism(self, f): Ring endomorphism of Fraction Field of Multivariate Polynomial Ring in a, b over Rational Field Defn: a |--> a + b b |--> a - b - """ for c in self.all: f = c(f) @@ -508,7 +499,6 @@ def _apply_functor(self, R): sage: R. = QQ[] sage: F(R) # indirect doctest Univariate Polynomial Ring in y over Fraction Field of Univariate Polynomial Ring in x over Fraction Field of Multivariate Polynomial Ring in a, b over Rational Field - """ for c in self.all: R = c(R) @@ -559,7 +549,6 @@ def __mul__(self, other): sage: F2 = CompositeConstructionFunctor(QQ.construction()[0],ZZ['y'].construction()[0]) sage: F1*F2 Poly[x](FractionField(Poly[y](FractionField(...)))) - """ if isinstance(self, CompositeConstructionFunctor): all = [other] + self.all @@ -577,7 +566,6 @@ def _repr_(self): sage: F = CompositeConstructionFunctor(QQ.construction()[0],ZZ['x'].construction()[0],QQ.construction()[0],ZZ['y'].construction()[0]) sage: F # indirect doctest Poly[y](FractionField(Poly[x](FractionField(...)))) - """ s = "..." for c in self.all: @@ -604,7 +592,6 @@ def expand(self): Poly[y](FractionField(Poly[x](FractionField(...)))) sage: prod(F.expand()) == F True - """ return list(reversed(self.all)) @@ -621,7 +608,6 @@ class IdentityConstructionFunctor(ConstructionFunctor): True sage: I == loads(dumps(I)) True - """ rank = -100 @@ -635,7 +621,6 @@ def __init__(self): True sage: I(RR) is RR True - """ from sage.categories.sets_cat import Sets ConstructionFunctor.__init__(self, Sets(), Sets()) @@ -724,7 +709,6 @@ def __mul__(self, other): True sage: P*I is P True - """ if isinstance(self, IdentityConstructionFunctor): return other @@ -759,16 +743,14 @@ def common_base(self, other_functor, self_bases, other_bases): INPUT: - - ``other_functor`` -- a construction functor. + - ``other_functor`` -- a construction functor - - ``self_bases`` -- the arguments passed to this functor. + - ``self_bases`` -- the arguments passed to this functor - ``other_bases`` -- the arguments passed to the functor - ``other_functor``. + ``other_functor`` - OUTPUT: - - A parent. + OUTPUT: a parent If no common base is found a :class:`sage.structure.coerce_exceptions.CoercionException` is raised. @@ -840,7 +822,6 @@ class PolynomialFunctor(ConstructionFunctor): Univariate Polynomial Ring in x over Finite Field of size 5 sage: (S.0 + R.0).parent().is_sparse() False - """ rank = 9 @@ -861,7 +842,6 @@ def __init__(self, var, multi_variate=False, sparse=False, implementation=None): Univariate Polynomial Ring in x over Integer Ring sage: Q == P True - """ from .rings import Rings Functor.__init__(self, Rings(), Rings()) @@ -879,7 +859,6 @@ def _apply_functor(self, R): sage: P = ZZ['x'].construction()[0] sage: P(GF(3)) # indirect doctest Univariate Polynomial Ring in x over Finite Field of size 3 - """ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing kwds = {} @@ -973,7 +952,6 @@ def merge(self, other): sage: P.merge(Q) sage: P.merge(P) is P True - """ if isinstance(other, MultiPolynomialFunctor): return other.merge(self) @@ -992,7 +970,6 @@ def _repr_(self): sage: P = ZZ['x'].construction()[0] sage: P # indirect doctest Poly[x] - """ return "Poly[%s]" % self.var @@ -1020,7 +997,6 @@ class MultiPolynomialFunctor(ConstructionFunctor): b |--> a - b sage: F(f)(F(A)(x)*a) (a + b)*x - """ rank = 9 @@ -1278,7 +1254,6 @@ class InfinitePolynomialFunctor(ConstructionFunctor): w_2 + z_3 sage: _.parent() is P True - """ # We do provide merging with polynomial rings. However, it seems that it is better @@ -1295,7 +1270,6 @@ def __init__(self, gens, order, implementation): InfPoly{[a,b,x], "degrevlex", "sparse"} sage: F == loads(dumps(F)) True - """ if not gens: raise ValueError("Infinite Polynomial Rings have at least one generator") @@ -1330,7 +1304,6 @@ def _apply_functor(self, R): InfPoly{[a,b,x], "degrevlex", "sparse"} sage: F(QQ['t']) # indirect doctest Infinite polynomial ring in a, b, x over Univariate Polynomial Ring in t over Rational Field - """ from sage.rings.polynomial.infinite_polynomial_ring import ( InfinitePolynomialRing, @@ -1343,7 +1316,6 @@ def _repr_(self): sage: F = sage.categories.pushout.InfinitePolynomialFunctor(['a','b','x'],'degrevlex','sparse'); F # indirect doctest InfPoly{[a,b,x], "degrevlex", "sparse"} - """ return 'InfPoly{[%s], "%s", "%s"}' % (','.join(self._gens), self._order, self._imple) @@ -1405,7 +1377,6 @@ def __mul__(self, other): sage: F4 = sage.categories.pushout.FractionField() sage: F2*F4 InfPoly{[x,y], "degrevlex", "dense"}(FractionField(...)) - """ if isinstance(other, IdentityConstructionFunctor): return self @@ -1510,7 +1481,6 @@ def merge(self, other): x_2 + y_3 sage: _.parent().construction() [InfPoly{[x,y], "degrevlex", "dense"}, Rational Field] - """ # Merging is only done if the ranks of self and other are the same. # It may happen that other is a substructure of self up to the monomial order @@ -1565,7 +1535,6 @@ def expand(self): InfPoly{[x], "degrevlex", "dense"}] sage: prod(F.expand())==F True - """ if len(self._gens) == 1: return [self] @@ -1603,7 +1572,6 @@ class MatrixFunctor(ConstructionFunctor): sage: F(f)(M) [ x + y x - y] [x^2 - y^2 2*x] - """ rank = 10 @@ -1652,7 +1620,6 @@ def _apply_functor(self, R): Full MatrixSpace of 2 by 3 dense matrices over Real Field with 53 bits of precision sage: F(RR) in F.codomain() # needs sage.modules True - """ from sage.matrix.matrix_space import MatrixSpace return MatrixSpace(R, self.nrows, self.ncols, sparse=self.is_sparse) @@ -1711,7 +1678,6 @@ def merge(self, other): True sage: F3.merge(F3).is_sparse True - """ if self != other: return None @@ -1746,7 +1712,6 @@ class LaurentPolynomialFunctor(ConstructionFunctor): y |--> 3*x - y sage: F(f)(x*F(P).gen()^-2 + y*F(P).gen()^3) (x + 2*y)*t^-2 + (3*x - y)*t^3 - """ rank = 9 @@ -1754,10 +1719,10 @@ def __init__(self, var, multi_variate=False): """ INPUT: - - ``var``, a string or a list of strings - - ``multi_variate``, optional bool, default ``False`` if ``var`` is a string - and ``True`` otherwise: If ``True``, application to a Laurent polynomial - ring yields a multivariate Laurent polynomial ring. + - ``var`` -- string or list of strings + - ``multi_variate`` -- boolean (default: ``False``); if ``var`` is a + string and ``True`` otherwise: If ``True``, application to a Laurent + polynomial ring yields a multivariate Laurent polynomial ring. TESTS:: @@ -1772,7 +1737,6 @@ def __init__(self, var, multi_variate=False): Multivariate Laurent Polynomial Ring in t, s over Rational Field sage: F3(QQ) # needs sage.modules Multivariate Laurent Polynomial Ring in s, t over Rational Field - """ Functor.__init__(self, Rings(), Rings()) if not isinstance(var, (str, tuple, list)): @@ -1797,7 +1761,6 @@ def _apply_functor(self, R): Multivariate Laurent Polynomial Ring in t, s over Rational Field sage: F3(QQ) # needs sage.modules Multivariate Laurent Polynomial Ring in s, t over Rational Field - """ from sage.rings.polynomial.laurent_polynomial_ring import LaurentPolynomialRing from sage.rings.polynomial.laurent_polynomial_ring_base import ( @@ -1870,7 +1833,6 @@ def merge(self, other): sage: F1.merge(F1)(LaurentPolynomialRing(GF(2), 'a')) Univariate Laurent Polynomial Ring in t over Univariate Laurent Polynomial Ring in a over Finite Field of size 2 - """ if self == other or isinstance(other, PolynomialFunctor) and self.var == other.var: return LaurentPolynomialFunctor(self.var, (self.multi_variate or other.multi_variate)) @@ -1901,11 +1863,12 @@ def __init__(self, n=None, is_sparse=False, inner_product_matrix=None, *, """ INPUT: - - ``n``, the rank of the to-be-created modules (non-negative integer) - - ``is_sparse`` (optional bool, default ``False``), create sparse implementation of modules - - ``inner_product_matrix``: ``n`` by ``n`` matrix, used to compute inner products in the + - ``n`` -- the rank of the to-be-created modules (nonnegative integer) + - ``is_sparse`` -- boolean (default: ``False``); create sparse + implementation of modules + - ``inner_product_matrix`` -- ``n`` by ``n`` matrix, used to compute inner products in the to-be-created modules - - ``name_mapping``, ``latex_name_mapping``: Dictionaries from base rings to names + - ``name_mapping``, ``latex_name_mapping`` -- Dictionaries from base rings to names - other keywords: see :func:`~sage.modules.free_module.FreeModule` TESTS:: @@ -1929,7 +1892,6 @@ def __init__(self, n=None, is_sparse=False, inner_product_matrix=None, *, sage: M2 = F2(QQ); M2; M2.is_sparse() Sparse vector space of dimension 3 over Rational Field True - """ # Functor.__init__(self, Rings(), FreeModules()) # FreeModules() takes a base ring # Functor.__init__(self, Objects(), Objects()) # Object() makes no sense, since FreeModule raises an error, e.g., on Set(['a',1]). @@ -1979,18 +1941,17 @@ def _apply_functor(self, R): sage: M_QQ = pushout(M, QQ) sage: latex(M_QQ) M \otimes \Bold{Q} - """ from sage.modules.free_module import FreeModule name = self.name_mapping.get(R, None) latex_name = self.latex_name_mapping.get(R, None) if name is None: - for base_ring, name in self.name_mapping.items(): + for name in self.name_mapping.values(): name = f'{name}_base_ext' break if latex_name is None: from sage.misc.latex import latex - for base_ring, latex_name in self.latex_name_mapping.items(): + for latex_name in self.latex_name_mapping.values(): latex_name = fr'{latex_name} \otimes {latex(R)}' break if name is None and latex_name is None: @@ -2214,7 +2175,6 @@ class SubspaceFunctor(ConstructionFunctor): User basis matrix: [1 0 1] [0 1 0] - """ rank = 11 # ranking of functor, not rank of module @@ -2226,7 +2186,7 @@ def __init__(self, basis): """ INPUT: - ``basis``: a list of elements of a free module. + - ``basis`` -- list of elements of a free module TESTS:: @@ -2340,7 +2300,6 @@ def __eq__(self, other): sage: F1 == F4 == F3 # needs sage.modules True - """ if not isinstance(other, SubspaceFunctor): return False @@ -2411,7 +2370,6 @@ def merge(self, other): [1 0 0] [0 1 0] [0 0 1] - """ if isinstance(other, SubspaceFunctor): # in order to remove linear dependencies, and in @@ -2466,7 +2424,6 @@ class FractionField(ConstructionFunctor): 1/(x + 2*y) sage: F == loads(dumps(F)) True - """ rank = 5 @@ -2540,7 +2497,6 @@ class CompletionFunctor(ConstructionFunctor): (1 + O(5^20))*a + 1 + O(5^40) sage: 1/2 + a (1 + O(5^20))*a + 3 + 2*5 + 2*5^2 + 2*5^3 + 2*5^4 + 2*5^5 + 2*5^6 + 2*5^7 + 2*5^8 + 2*5^9 + 2*5^10 + 2*5^11 + 2*5^12 + 2*5^13 + 2*5^14 + 2*5^15 + 2*5^16 + 2*5^17 + 2*5^18 + 2*5^19 + O(5^20) - """ rank = 4 _real_types = ['Interval', 'Ball', 'MPFR', 'RDF', 'RLF', 'RR'] @@ -2550,14 +2506,15 @@ def __init__(self, p, prec, extras=None): """ INPUT: - - ``p``: A prime number, the generator of a univariate polynomial ring, or ``+Infinity`` + - ``p`` -- prime number, the generator of a univariate polynomial ring, + or ``+Infinity`` - - ``prec``: an integer, yielding the precision in bits. Note that + - ``prec`` -- integer; yielding the precision in bits. Note that if ``p`` is prime then the ``prec`` is the *capped* precision, while it is the *set* precision if ``p`` is ``+Infinity``. In the ``lattice-cap`` precision case, ``prec`` will be a tuple instead. - - ``extras`` (optional dictionary): Information on how to print elements, etc. + - ``extras`` -- dictionary (optional); information on how to print elements, etc. If 'type' is given as a key, the corresponding value should be a string among the following: @@ -2629,7 +2586,6 @@ def _apply_functor(self, R): True sage: F1(QQ) 5-adic Field with capped relative precision 20 - """ try: if not self.extras: @@ -2900,15 +2856,15 @@ def __init__(self, I, names=None, as_field=False, domain=None, """ INPUT: - - ``I``, an ideal (the modulus) - - ``names`` (optional string or list of strings), the names for the + - ``I`` -- an ideal (the modulus) + - ``names`` -- string or list of strings (optional); the names for the quotient ring generators - - ``as_field`` (optional bool, default false), return the quotient - ring as field (if available). - - ``domain`` (optional category, default ``Rings()``), the domain of - this functor. - - ``codomain`` (optional category, default ``Rings()``), the codomain - of this functor. + - ``as_field`` -- boolean (default: ``False``); return the quotient + ring as field (if available) + - ``domain`` -- category (default: ``Rings()``); the domain of + this functor + - ``codomain`` -- category (default: ``Rings()``); the codomain + of this functor - Further named arguments. In particular, an implementation of the quotient can be suggested here. These named arguments are passed to the quotient construction. @@ -2937,7 +2893,6 @@ def __init__(self, I, names=None, as_field=False, domain=None, sage: F = QuotientFunctor([5] * ZZ) sage: F(ZZ) Ring of integers modulo 5 - """ if domain is None: domain = Rings() @@ -3075,7 +3030,6 @@ def merge(self, other): sage: pushout(GF(5), Integers(5)) # needs sage.libs.pari Finite Field of size 5 - """ if type(self) is not type(other): return None @@ -3205,7 +3159,6 @@ class AlgebraicExtensionFunctor(ConstructionFunctor): Residue field of Integers modulo 17 sage: F(CyclotomicField(49)) Residue field in zbar of Fractional ideal (17) - """ rank = 3 @@ -3235,11 +3188,11 @@ def __init__(self, polys, names, embeddings=None, structures=None, cyclotomic field, rather than just a number field. - ``precs`` -- (optional) list of integers. If it is provided, - it is used to determine the precision of p-adic extensions. + it is used to determine the precision of `p`-adic extensions. - ``implementations`` -- (optional) list of strings. If it is provided, it is used to determine an implementation in the - p-adic case. + `p`-adic case. - ``residue`` -- (optional) prime ideal of an order in a number field, determining a residue field. If it is provided, @@ -3390,7 +3343,6 @@ def _apply_functor(self, R): sage: AEF = AlgebraicExtensionFunctor([a^2 - 3], ['a'], [None]) sage: AEF(K) 3-adic Eisenstein Extension Field in a defined by a^2 - 3 - """ from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ @@ -3466,7 +3418,7 @@ def merge(self, other): INPUT: - - ``other`` -- Construction Functor. + - ``other`` -- Construction Functor OUTPUT: @@ -3552,7 +3504,6 @@ def merge(self, other): CoercionException: ('Ambiguous Base Extension', Number Field in a with defining polynomial x^3 - 2 with a = -0.6299605249474365? + 1.091123635971722?*I, Number Field in b with defining polynomial x^6 - 2 with b = 1.122462048309373?) - """ if isinstance(other, AlgebraicClosureFunctor): return other @@ -3627,7 +3578,6 @@ def __mul__(self, other): sage: F, R = L.construction() sage: prod(F.expand())(R) == L #indirect doctest True - """ if isinstance(other, IdentityConstructionFunctor): return self @@ -3693,7 +3643,6 @@ class AlgebraicClosureFunctor(ConstructionFunctor): Complex Field with 53 bits of precision sage: F(F(QQ)) is F(QQ) True - """ rank = 3 @@ -3709,7 +3658,6 @@ def __init__(self): Complex Field with 53 bits of precision sage: F == loads(dumps(F)) True - """ Functor.__init__(self, Rings(), Rings()) @@ -3745,7 +3693,6 @@ def merge(self, other): True sage: CDF.construction()[0].merge(CDF.construction()[0]) # needs sage.rings.complex_double AlgebraicClosureFunctor - """ if self == other: return self @@ -4030,7 +3977,6 @@ def _apply_functor(self, R): sage: F = BlackBoxConstructionFunctor(f) sage: F(ZZ) # indirect doctest # needs sage.modules Ambient free module of rank 2 over the principal ideal domain Integer Ring - """ return self.box(R) @@ -4651,7 +4597,6 @@ def pushout_lattice(R, S): AUTHOR: - Robert Bradshaw - """ R_tower = construction_tower(R) S_tower = construction_tower(S) @@ -4804,7 +4749,7 @@ def construction_tower(R): INPUT: - An object + - ``R`` -- an object OUTPUT: @@ -4822,7 +4767,6 @@ def construction_tower(R): of Univariate Polynomial Ring in t over Rational Field), (FractionField, Univariate Polynomial Ring in t over Rational Field), (Poly[t], Rational Field), (FractionField, Integer Ring)] - """ tower = [(None, R)] c = R.construction() @@ -4844,11 +4788,10 @@ def expand_tower(tower): INPUT: - A construction tower as returned by :func:`construction_tower`. + - ``tower`` -- a construction tower as returned by + :func:`construction_tower` - OUTPUT: - - A new construction tower with all the construction functors expanded. + OUTPUT: a new construction tower with all the construction functors expanded EXAMPLES:: @@ -4884,11 +4827,9 @@ def type_to_parent(P): INPUT: - A type - - OUTPUT: + - ``P`` -- a type - A Sage parent structure corresponding to the given type + OUTPUT: a Sage parent structure corresponding to the given type TESTS:: diff --git a/src/sage/categories/quotient_fields.py b/src/sage/categories/quotient_fields.py index ba6476ee89c..76f0570a819 100644 --- a/src/sage/categories/quotient_fields.py +++ b/src/sage/categories/quotient_fields.py @@ -18,7 +18,7 @@ class QuotientFields(Category_singleton): """ - The category of quotient fields over an integral domain + The category of quotient fields over an integral domain. EXAMPLES:: @@ -57,7 +57,7 @@ def denominator(self): @coerce_binop def gcd(self, other): """ - Greatest common divisor + Greatest common divisor. .. NOTE:: @@ -141,7 +141,7 @@ def gcd(self, other): @coerce_binop def lcm(self, other): """ - Least common multiple + Least common multiple. In a field, the least common multiple is not very informative, as it is only determined up to a unit. But in the fraction field of an @@ -343,12 +343,10 @@ def factor(self, *args, **kwds): INPUT: - - ``*args`` -- Arbitrary arguments suitable over the base ring - - ``**kwds`` -- Arbitrary keyword arguments suitable over the base ring + - ``*args`` -- arbitrary arguments suitable over the base ring + - ``**kwds`` -- arbitrary keyword arguments suitable over the base ring - OUTPUT: - - - Factorization of ``self`` over the base ring + OUTPUT: factorization of ``self`` over the base ring EXAMPLES:: @@ -380,9 +378,7 @@ def partial_fraction_decomposition(self, decompose_powers=True): whether to decompose prime power denominators as opposed to having a single term for each irreducible factor of the denominator - OUTPUT: - - Partial fraction decomposition of ``self`` over the base ring. + OUTPUT: partial fraction decomposition of ``self`` over the base ring AUTHORS: @@ -632,7 +628,7 @@ def derivative(self, *args): def _derivative(self, var=None): r""" - Returns the derivative of this rational function with respect to the + Return the derivative of this rational function with respect to the variable ``var``. Over a ring with a working gcd implementation, the derivative of a @@ -642,11 +638,9 @@ def _derivative(self, var=None): INPUT: - - ``var`` -- Variable with respect to which the derivative is computed - - OUTPUT: + - ``var`` -- variable with respect to which the derivative is computed - - Derivative of ``self`` with respect to ``var`` + OUTPUT: derivative of ``self`` with respect to ``var`` .. SEEALSO:: diff --git a/src/sage/categories/quotients.py b/src/sage/categories/quotients.py index 120d00f80b0..fa5fd3513db 100644 --- a/src/sage/categories/quotients.py +++ b/src/sage/categories/quotients.py @@ -24,7 +24,7 @@ class QuotientsCategory(RegressiveCovariantConstructionCategory): @classmethod def default_super_categories(cls, category): """ - Returns the default super categories of ``category.Quotients()`` + Return the default super categories of ``category.Quotients()``. Mathematical meaning: if `A` is a quotient of `B` in the category `C`, then `A` is also a subquotient of `B` in the @@ -32,8 +32,8 @@ def default_super_categories(cls, category): INPUT: - - ``cls`` -- the class ``QuotientsCategory`` - - ``category`` -- a category `Cat` + - ``cls`` -- the class ``QuotientsCategory`` + - ``category`` -- a category `Cat` OUTPUT: a (join) category diff --git a/src/sage/categories/realizations.py b/src/sage/categories/realizations.py index 7ebeaf2ce57..762bb277e51 100644 --- a/src/sage/categories/realizations.py +++ b/src/sage/categories/realizations.py @@ -25,7 +25,7 @@ class RealizationsCategory(RegressiveCovariantConstructionCategory): """ - An abstract base class for all categories of realizations category + An abstract base class for all categories of realizations category. Relization are implemented as :class:`~sage.categories.covariant_functorial_construction.RegressiveCovariantConstructionCategory`. @@ -111,7 +111,7 @@ def Realizations(self): class Category_realization_of_parent(Category_over_base, BindableClass): """ - An abstract base class for categories of all realizations of a given parent + An abstract base class for categories of all realizations of a given parent. INPUT: @@ -163,7 +163,7 @@ def __init__(self, parent_with_realization): def _get_name(self): """ - Return a human readable string specifying which kind of bases this category is for + Return a human readable string specifying which kind of bases this category is for. It is obtained by splitting and lower casing the last part of the class name. @@ -173,7 +173,7 @@ def _get_name(self): sage: from sage.categories.realizations import Category_realization_of_parent sage: class MultiplicativeBasesOnPrimitiveElements(Category_realization_of_parent): ....: def super_categories(self): return [Objects()] - sage: Sym = SymmetricFunctions(QQ); Sym.rename("Sym") # needs sage.combinat sage.modules + sage: Sym = SymmetricFunctions(QQ); Sym.rename('Sym') # needs sage.combinat sage.modules sage: MultiplicativeBasesOnPrimitiveElements(Sym)._get_name() # needs sage.combinat sage.modules 'multiplicative bases on primitive elements' """ @@ -191,7 +191,7 @@ def _repr_object_names(self): sage: from sage.categories.realizations import Category_realization_of_parent sage: class MultiplicativeBasesOnPrimitiveElements(Category_realization_of_parent): ....: def super_categories(self): return [Objects()] - sage: Sym = SymmetricFunctions(QQ); Sym.rename("Sym") # needs sage.combinat sage.modules + sage: Sym = SymmetricFunctions(QQ); Sym.rename('Sym') # needs sage.combinat sage.modules sage: C = MultiplicativeBasesOnPrimitiveElements(Sym); C # needs sage.combinat sage.modules Category of multiplicative bases on primitive elements of Sym sage: C._repr_object_names() # needs sage.combinat sage.modules diff --git a/src/sage/categories/regular_crystals.py b/src/sage/categories/regular_crystals.py index 8b5a56b8ce2..506be6ba4ec 100644 --- a/src/sage/categories/regular_crystals.py +++ b/src/sage/categories/regular_crystals.py @@ -98,7 +98,7 @@ def super_categories(self): def example(self, n=3): """ - Returns an example of highest weight crystals, as per + Return an example of highest weight crystals, as per :meth:`Category.example`. EXAMPLES:: @@ -170,7 +170,7 @@ class ParentMethods: # sage: m.demazure_operator([1,4,2]) def demazure_operator(self, element, reduced_word): r""" - Returns the application of Demazure operators `D_i` for `i` from + Return the application of Demazure operators `D_i` for `i` from ``reduced_word`` on ``element``. INPUT: @@ -180,9 +180,7 @@ def demazure_operator(self, element, reduced_word): - ``reduced_word`` -- a reduced word of the Weyl group of the same type as the underlying crystal - OUTPUT: - - - an element of the free module indexed by the underlying crystal + OUTPUT: an element of the free module indexed by the underlying crystal EXAMPLES:: @@ -229,12 +227,10 @@ def demazure_subcrystal(self, element, reduced_word, only_support=True): underlying crystal - ``reduced_word`` -- a reduced word of the Weyl group of the same type as the underlying crystal - - ``only_support`` -- (default: ``True``) only include arrows - corresponding to the support of ``reduced_word`` - - OUTPUT: + - ``only_support`` -- boolean (default: ``True``); only include + arrows corresponding to the support of ``reduced_word`` - - the Demazure subcrystal + OUTPUT: the Demazure subcrystal EXAMPLES:: @@ -375,7 +371,7 @@ def dual_equivalence_graph(self, X=None, index_set=None, directed=True): (default: the whole index set of ``self``); this has to be a subset of the index set of ``self`` (as a list or tuple) - - ``directed`` -- (default: ``True``) whether to have the + - ``directed`` -- boolean (default: ``True``); whether to have the dual equivalence graph be directed, where the head of an edge `b - b'` is `b` and the tail is `b' = f_{i-1} f_i e_{i-1} e_i b`) @@ -453,10 +449,10 @@ def wt_zero(x): if checker(y): edges.append([x, y, i]) from sage.graphs.digraph import DiGraph - G = DiGraph([X, edges], format="vertices_and_edges", immutable=True) + G = DiGraph([X, edges], format='vertices_and_edges', immutable=True) from sage.graphs.dot2tex_utils import have_dot2tex if have_dot2tex(): - G.set_latex_options(format="dot2tex", edge_labels=True, + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=self.cartan_type()._index_set_coloring) return G @@ -878,11 +874,11 @@ def dual_equivalence_class(self, index_set=None): if y not in visited: todo.add(y) from sage.graphs.graph import Graph - G = Graph([visited, edges], format="vertices_and_edges", + G = Graph([visited, edges], format='vertices_and_edges', immutable=True, multiedges=True) from sage.graphs.dot2tex_utils import have_dot2tex if have_dot2tex(): - G.set_latex_options(format="dot2tex", edge_labels=True, + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=self.cartan_type()._index_set_coloring) return G diff --git a/src/sage/categories/regular_supercrystals.py b/src/sage/categories/regular_supercrystals.py index f7f6f3fa80e..0e4ae6bad27 100644 --- a/src/sage/categories/regular_supercrystals.py +++ b/src/sage/categories/regular_supercrystals.py @@ -39,7 +39,7 @@ class RegularSuperCrystals(Category_singleton): - either an attribute ``_cartan_type`` or a method ``cartan_type`` - - ``module_generators``: a list (or container) of distinct elements + - ``module_generators`` -- a list (or container) of distinct elements that generate the crystal using `f_i` and `e_i` Furthermore, their elements ``x`` should implement the following diff --git a/src/sage/categories/rings.py b/src/sage/categories/rings.py index 47777ce5711..5ae70e2ea7f 100644 --- a/src/sage/categories/rings.py +++ b/src/sage/categories/rings.py @@ -22,7 +22,7 @@ class Rings(CategoryWithAxiom): """ - The category of rings + The category of rings. Associative rings with unit, not necessarily commutative @@ -137,7 +137,6 @@ def is_injective(self) -> bool: sage: R = ZpFM(3) # needs sage.rings.padics sage: R.fraction_field().coerce_map_from(R).is_injective() True - """ if self.domain().is_zero(): return True @@ -289,7 +288,7 @@ def Division(self): """ Return the full subcategory of the division objects of ``self``. - A ring satisfies the *division axiom* if all non-zero + A ring satisfies the *division axiom* if all nonzero elements have multiplicative inverses. EXAMPLES:: @@ -346,8 +345,8 @@ def is_integral_domain(self, proof=True) -> bool: INPUT: - - ``proof`` -- (default: ``True``) Determines what to do in unknown - cases + - ``proof`` -- boolean (default: ``True``); determine what to do + in unknown cases ALGORITHM: @@ -500,7 +499,7 @@ def _Hom_(self, Y, category): The sole purpose of this method is to construct the homset as a :class:`~sage.rings.homset.RingHomset`. If ``category`` is specified and is not a subcategory of - :class:`Rings() `, a :class:`TypeError` is raised instead + :class:`Rings() `, a :exc:`TypeError` is raised instead This method is not meant to be called directly. Please use :func:`sage.categories.homset.Hom` instead. @@ -767,13 +766,13 @@ def ideal(self, *args, **kwds): INPUT: - - An element or a list/tuple/sequence of elements. - - ``coerce`` (optional bool, default ``True``): - First coerce the elements into this ring. - - ``side``, optional string, one of ``"twosided"`` - (default), ``"left"``, ``"right"``: determines + - an element or a list/tuple/sequence of elements + - ``coerce`` -- boolean (default: ``True``); + first coerce the elements into this ring + - ``side`` -- (optional) string, one of ``'twosided'`` + (default), ``'left'``, ``'right'``; determines whether the resulting ideal is twosided, a left - ideal or a right ideal. + ideal or a right ideal EXAMPLES:: @@ -872,7 +871,7 @@ def quotient(self, I, names=None, **kwds): INPUT: - - ``I`` -- A twosided ideal of this ring. + - ``I`` -- a twosided ideal of this ring - ``names`` -- (optional) names of the generators of the quotient (if there are multiple generators, you can specify a single character string and the generators are named in sequence starting with 0). @@ -1012,9 +1011,7 @@ def quotient_ring(self, I, names=None, **kwds): - further named arguments that may be passed to the quotient ring constructor. - OUTPUT: - - - ``R/I`` -- the quotient ring of `R` by the ideal `I` + OUTPUT: ``R/I`` -- the quotient ring of `R` by the ideal `I` EXAMPLES:: @@ -1368,12 +1365,10 @@ def free_module(self, base=None, basis=None, map=True): - ``basis`` -- (optional) a basis for this ring over the base - - ``map`` -- boolean (default ``True``), whether to return + - ``map`` -- boolean (default: ``True``); whether to return `R`-linear maps to and from `V` - OUTPUT: - - - A finite-rank free `R`-module `V` + OUTPUT: a finite-rank free `R`-module `V` - An `R`-module isomorphism from `V` to this ring (only included if ``map`` is ``True``) @@ -1425,10 +1420,10 @@ def free_module(self, base=None, basis=None, map=True): def _random_nonzero_element(self, *args, **kwds): """ - Return a random non-zero element in this ring. + Return a random nonzero element in this ring. The default behaviour of this method is to repeatedly call the - ``random_element`` method until a non-zero element is obtained. + ``random_element`` method until a nonzero element is obtained. In this implementation, all parameters are simply pushed forward to the ``random_element`` method. @@ -1484,9 +1479,7 @@ def inverse_of_unit(self): r""" Return the inverse of this element if it is a unit. - OUTPUT: - - An element in the same ring as this element. + OUTPUT: an element in the same ring as this element EXAMPLES:: @@ -1536,7 +1529,7 @@ def inverse_of_unit(self): def _divide_if_possible(self, y): """ Divide ``self`` by ``y`` if possible and raise a - :class:`ValueError` otherwise. + :exc:`ValueError` otherwise. EXAMPLES:: diff --git a/src/sage/categories/schemes.py b/src/sage/categories/schemes.py index d0b99f271eb..b8f117c0da1 100644 --- a/src/sage/categories/schemes.py +++ b/src/sage/categories/schemes.py @@ -94,7 +94,7 @@ def super_categories(self): def _call_(self, x): """ - Construct a scheme from the data in ``x`` + Construct a scheme from the data in ``x``. EXAMPLES: @@ -138,7 +138,6 @@ def _call_(self, x): Defn: Natural morphism: From: Integer Ring To: Rational Field - """ from sage.schemes.generic.scheme import Scheme if isinstance(x, Scheme): diff --git a/src/sage/categories/semigroups.py b/src/sage/categories/semigroups.py index 744be185fb8..7114761aaac 100644 --- a/src/sage/categories/semigroups.py +++ b/src/sage/categories/semigroups.py @@ -60,18 +60,18 @@ class Semigroups(CategoryWithAxiom): """ _base_category_class_and_axiom = (Magmas, "Associative") - def example(self, choice="leftzero", **kwds): + def example(self, choice='leftzero', **kwds): r""" - Returns an example of a semigroup, as per + Return an example of a semigroup, as per :meth:`Category.example() `. INPUT: - - ``choice`` -- str (default: 'leftzero'). Can be either 'leftzero' - for the left zero semigroup, or 'free' for the free semigroup. + - ``choice`` -- string (default: ``'leftzero'``); can be either 'leftzero' + for the left zero semigroup, or 'free' for the free semigroup - ``**kwds`` -- keyword arguments passed onto the constructor for the - chosen semigroup. + chosen semigroup EXAMPLES:: @@ -81,7 +81,6 @@ def example(self, choice="leftzero", **kwds): An example of a semigroup: the free semigroup generated by ('a', 'b', 'c', 'd') sage: Semigroups().example(choice='free', alphabet=('a','b')) An example of a semigroup: the free semigroup generated by ('a', 'b') - """ import sage.categories.examples.semigroups as examples if choice == "leftzero": @@ -114,7 +113,6 @@ def _test_associativity(self, **options): sage: L._test_associativity(elements = (L(1), L(2), L(3))) See the documentation for :class:`TestSuite` for more information. - """ tester = self._tester(**options) S = tester.some_elements() @@ -173,26 +171,23 @@ def prod(self, args): assert len(args) > 0, "Cannot compute an empty product in a semigroup" return prod(args[1:], args[0]) - def cayley_graph(self, side="right", simple=False, elements=None, + def cayley_graph(self, side='right', simple=False, elements=None, generators=None, connecting_set=None): r""" Return the Cayley graph for this finite semigroup. INPUT: - - ``side`` -- "left", "right", or "twosided": - the side on which the generators act (default:"right") - - ``simple`` -- boolean (default: ``False``): - if True, returns a simple graph (no loops, no labels, - no multiple edges) - - ``generators`` -- a list, tuple, or family of elements + - ``side`` -- ``'left'``, ``'right'``, or ``'twosided'``: + the side on which the generators act (default: ``'right'``) + - ``simple`` -- boolean (default: ``False``); if ``True``, returns + a simple graph (no loops, no labels, no multiple edges) + - ``generators`` -- list; tuple, or family of elements of ``self`` (default: ``self.semigroup_generators()``) - ``connecting_set`` -- alias for ``generators``; deprecated - - ``elements`` -- a list (or iterable) of elements of ``self`` - - OUTPUT: + - ``elements`` -- list (or iterable) of elements of ``self`` - - :class:`DiGraph` + OUTPUT: :class:`DiGraph` EXAMPLES: @@ -263,7 +258,7 @@ def cayley_graph(self, side="right", simple=False, elements=None, :: - sage: g = S.cayley_graph(side="left", simple=True) # needs sage.graphs + sage: g = S.cayley_graph(side='left', simple=True) # needs sage.graphs sage: g.vertices(sort=True) # needs sage.graphs ['a', 'ab', 'b', 'ba'] sage: g.edges(sort=True) # needs sage.graphs @@ -272,7 +267,7 @@ def cayley_graph(self, side="right", simple=False, elements=None, :: - sage: g = S.cayley_graph(side="twosided", simple=True) # needs sage.graphs + sage: g = S.cayley_graph(side='twosided', simple=True) # needs sage.graphs sage: g.vertices(sort=True) # needs sage.graphs ['a', 'ab', 'b', 'ba'] sage: g.edges(sort=True) # needs sage.graphs @@ -281,7 +276,7 @@ def cayley_graph(self, side="right", simple=False, elements=None, :: - sage: g = S.cayley_graph(side="twosided") # needs sage.graphs + sage: g = S.cayley_graph(side='twosided') # needs sage.graphs sage: g.vertices(sort=True) # needs sage.graphs ['a', 'ab', 'b', 'ba'] sage: g.edges(sort=True) # needs sage.graphs @@ -295,7 +290,7 @@ def cayley_graph(self, side="right", simple=False, elements=None, TESTS:: - sage: SymmetricGroup(2).cayley_graph(side="both") # needs sage.graphs sage.groups + sage: SymmetricGroup(2).cayley_graph(side='both') # needs sage.graphs sage.groups Traceback (most recent call last): ... ValueError: option 'side' must be 'left', 'right' or 'twosided' @@ -379,7 +374,7 @@ def subsemigroup(self, generators, one=None, category=None): ``self``, or a list, iterable, ... that can be converted into one (see :class:`Family`). - - ``one`` -- a unit for the subsemigroup, or ``None``. + - ``one`` -- a unit for the subsemigroup, or ``None`` - ``category`` -- a category @@ -457,7 +452,7 @@ def subsemigroup(self, generators, one=None, category=None): return AutomaticSemigroup(generators, ambient=self, one=one, category=category) - def trivial_representation(self, base_ring=None, side="twosided"): + def trivial_representation(self, base_ring=None, side='twosided'): r""" Return the trivial representation of ``self`` over ``base_ring``. @@ -479,12 +474,12 @@ def trivial_representation(self, base_ring=None, side="twosided"): from sage.modules.with_basis.representation import TrivialRepresentation return TrivialRepresentation(self, base_ring) - def regular_representation(self, base_ring=None, side="left"): + def regular_representation(self, base_ring=None, side='left'): """ Return the regular representation of ``self`` over ``base_ring``. - - ``side`` -- (default: ``"left"``) whether this is the - ``"left"`` or ``"right"`` regular representation + - ``side`` -- (default: ``'left'``) whether this is the + ``'left'`` or ``'right'`` regular representation EXAMPLES:: @@ -499,7 +494,7 @@ def regular_representation(self, base_ring=None, side="left"): from sage.modules.with_basis.representation import RegularRepresentation return RegularRepresentation(self, base_ring, side) - def representation(self, module, on_basis, side="left", *args, **kwargs): + def representation(self, module, on_basis, side='left', *args, **kwargs): r""" Return a representation of ``self`` on ``module`` with the action given by ``on_basis``. @@ -511,8 +506,8 @@ def representation(self, module, on_basis, side="left", *args, **kwargs): ``g`` is an element of the semigroup and ``m`` is an element of the indexing set for the basis, and returns the result of ``g`` acting on ``m`` - - ``side`` -- (default: ``"left"``) whether this is a - ``"left"`` or ``"right"`` representation + - ``side`` -- (default: ``'left'``) whether this is a + ``'left'`` or ``'right'`` representation EXAMPLES:: @@ -533,11 +528,11 @@ class ElementMethods: def _pow_int(self, n): """ - Return ``self`` to the `n^{th}` power. + Return ``self`` to the `n`-th power. INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -830,7 +825,7 @@ class Subquotients(SubquotientsCategory): def example(self): """ - Returns an example of subquotient of a semigroup, as per + Return an example of subquotient of a semigroup, as per :meth:`Category.example() `. @@ -1006,7 +1001,7 @@ def product_on_basis(self, g1, g2): """ return self.monomial(g1 * g2) - def trivial_representation(self, side="twosided"): + def trivial_representation(self, side='twosided'): """ Return the trivial representation of ``self``. @@ -1026,14 +1021,14 @@ def trivial_representation(self, side="twosided"): S = self.basis().keys() return S.trivial_representation(self.base_ring()) - def regular_representation(self, side="left"): + def regular_representation(self, side='left'): """ Return the regular representation of ``self``. INPUT: - - ``side`` -- (default: ``"left"``) whether this is the - ``"left"`` or ``"right"`` regular representation + - ``side`` -- (default: ``'left'``) whether this is the + ``'left'`` or ``'right'`` regular representation EXAMPLES:: @@ -1047,7 +1042,7 @@ def regular_representation(self, side="left"): S = self.basis().keys() return S.regular_representation(self.base_ring(), side) - def representation(self, module, on_basis, side="left", *args, **kwargs): + def representation(self, module, on_basis, side='left', *args, **kwargs): r""" Return a representation of ``self`` on ``module`` with the action of the semigroup given by ``on_basis``. @@ -1059,8 +1054,8 @@ def representation(self, module, on_basis, side="left", *args, **kwargs): ``g`` is an element of the semigroup and ``m`` is an element of the indexing set for the basis, and returns the result of ``g`` acting on ``m`` - - ``side`` -- (default: ``"left"``) whether this is a - ``"left"`` or ``"right"`` representation + - ``side`` -- (default: ``'left'``) whether this is a + ``'left'`` or ``'right'`` representation EXAMPLES:: diff --git a/src/sage/categories/semisimple_algebras.py b/src/sage/categories/semisimple_algebras.py index 5f889ea0e16..90fa3828d09 100644 --- a/src/sage/categories/semisimple_algebras.py +++ b/src/sage/categories/semisimple_algebras.py @@ -92,9 +92,9 @@ def radical_basis(self, **keywords): r""" Return a basis of the Jacobson radical of this algebra. - - ``keywords`` -- for compatibility; ignored. + - ``keywords`` -- for compatibility; ignored - OUTPUT: the empty list since this algebra is semisimple. + OUTPUT: the empty list since this algebra is semisimple EXAMPLES:: diff --git a/src/sage/categories/sets_cat.py b/src/sage/categories/sets_cat.py index 51eb9b14453..2d58d1c6514 100644 --- a/src/sage/categories/sets_cat.py +++ b/src/sage/categories/sets_cat.py @@ -71,7 +71,6 @@ def print_compare(x, y): 1 != 2 sage: print_compare(1,1) 1 == 1 - """ if x == y: return LazyFormat("%s == %s") % (x, y) @@ -136,9 +135,9 @@ class Sets(Category_singleton): + - @@ -212,7 +211,6 @@ class Sets(Category_singleton): TESTS:: sage: TestSuite(Sets()).run() - """ def super_categories(self): @@ -573,7 +571,6 @@ def Subobjects(self): sage: Semigroups().Subobjects().is_subcategory(Semigroups().Subquotients()) True sage: TestSuite(C).run() - """ return SubobjectsCategory.category_of(self) @@ -1064,7 +1061,7 @@ def an_element(self): This is used both for illustration and testing purposes. If the set ``self`` is empty, :meth:`an_element` should raise the exception - :class:`EmptySetError`. + :exc:`EmptySetError`. This default implementation calls :meth:`_an_element_` and caches the result. Any parent should implement either @@ -1207,7 +1204,6 @@ def _test_elements_eq_reflexive(self, **options): We restore ``P.element_class`` in a proper state for further tests:: sage: P.element_class.__eq__ = eq - """ tester = self._tester(**options) S = list(tester.some_elements()) + [None, 0] @@ -1246,7 +1242,6 @@ def _test_elements_eq_symmetric(self, **options): We restore ``P.element_class`` in a proper state for further tests:: sage: P.element_class.__eq__ = eq - """ tester = self._tester(**options) S = list(tester.some_elements()) + [None, 0] @@ -1278,7 +1273,6 @@ def _test_elements_eq_transitive(self, **options): ... AssertionError: non transitive equality: 3 + O(3^2) == O(3) and O(3) == 0 but 3 + O(3^2) != 0 - """ tester = self._tester(**options) S = list(tester.some_elements()) @@ -1525,7 +1519,6 @@ def _test_construction(self, **options): sage: F(R) == QQ True sage: TestSuite(QQ).run() # indirect doctest - """ tester = self._tester(**options) FO = self.construction() @@ -1541,7 +1534,7 @@ def cartesian_product(*parents, **kwargs): INPUT: - - ``parents`` -- a list (or other iterable) of parents. + - ``parents`` -- list (or other iterable) of parents - ``category`` -- (default: ``None``) the category the Cartesian product belongs to. If ``None`` is passed, @@ -1557,14 +1550,12 @@ def cartesian_product(*parents, **kwargs): for this Cartesian product (see also :class:`~sage.sets.cartesian_product.CartesianProduct`). - OUTPUT: - - The Cartesian product. + OUTPUT: the Cartesian product EXAMPLES:: sage: C = AlgebrasWithBasis(QQ) - sage: A = C.example(); A.rename("A") # needs sage.combinat sage.modules + sage: A = C.example(); A.rename('A') # needs sage.combinat sage.modules sage: A.cartesian_product(A, A) # needs sage.combinat sage.modules A (+) A (+) A sage: ZZ.cartesian_product(GF(2), FiniteEnumeratedSet([1,2,3])) @@ -1832,7 +1823,7 @@ def __invert__(self): .. NOTE:: This is an optional method. A default implementation - raising :class:`NotImplementedError` could be provided instead. + raising :exc:`NotImplementedError` could be provided instead. """ def is_injective(self): @@ -2187,7 +2178,7 @@ class CartesianProducts(CartesianProductsCategory): sage: C = Sets().CartesianProducts().example() sage: C The Cartesian product of (Set of prime numbers (basic implementation), - An example of an infinite enumerated set: the non negative integers, + An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) sage: C.category() Category of Cartesian products of sets @@ -2217,7 +2208,7 @@ def example(self): sage: Sets().CartesianProducts().example() The Cartesian product of (Set of prime numbers (basic implementation), - An example of an infinite enumerated set: the non negative integers, + An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) """ from .finite_enumerated_sets import FiniteEnumeratedSets @@ -2362,7 +2353,7 @@ def an_element(self): sage: C = Sets().CartesianProducts().example(); C The Cartesian product of (Set of prime numbers (basic implementation), - An example of an infinite enumerated set: the non negative integers, + An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) sage: C.an_element() (47, 42, 1) @@ -2415,7 +2406,7 @@ def is_finite(self): def cardinality(self): r""" - Return the cardinality of self. + Return the cardinality of ``self``. EXAMPLES:: @@ -2523,7 +2514,7 @@ def cartesian_projection(self, i): sage: C = Sets().CartesianProducts().example(); C The Cartesian product of (Set of prime numbers (basic implementation), - An example of an infinite enumerated set: the non negative integers, + An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) sage: x = C.an_element(); x (47, 42, 1) @@ -2600,8 +2591,8 @@ def cartesian_projection(self, i): EXAMPLES:: sage: # needs sage.modules - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') sage: S = cartesian_product([F, G]) sage: x = (S.monomial((0,4)) + 2 * S.monomial((0,5)) ....: + 3 * S.monomial((1,6))) @@ -2619,9 +2610,9 @@ def cartesian_factors(self): EXAMPLES:: sage: # needs sage.modules - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") - sage: H = CombinatorialFreeModule(ZZ, [4,7]); H.rename("H") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') + sage: H = CombinatorialFreeModule(ZZ, [4,7]); H.rename('H') sage: S = cartesian_product([F, G, H]) sage: x = (S.monomial((0,4)) + 2 * S.monomial((0,5)) ....: + 3 * S.monomial((1,6)) + 4 * S.monomial((2,4)) @@ -2657,7 +2648,6 @@ def extra_super_categories(self): Category of modules with basis over Integer Ring, ... Category of objects] - """ from sage.categories.modules_with_basis import ModulesWithBasis return [ModulesWithBasis(self.base_ring())] @@ -2696,7 +2686,7 @@ def construction(self): def _repr_(self): r""" - Return the string representation of `self`. + Return the string representation of ``self``. EXAMPLES:: @@ -2824,9 +2814,10 @@ def inject_shorthands(self, shorthands=None, verbose=True): INPUT: - - ``shorthands`` -- a list (or iterable) of strings (default: ``self._shorthands``) - or ``"all"`` (for ``self._shorthands_all``) - - ``verbose`` -- boolean (default ``True``); + - ``shorthands`` -- list (or iterable) of strings + (default: ``self._shorthands``) + or ``'all'`` (for ``self._shorthands_all``) + - ``verbose`` -- boolean (default: ``True``); whether to print the defined shorthands EXAMPLES: diff --git a/src/sage/categories/sets_with_grading.py b/src/sage/categories/sets_with_grading.py index 9f9037e94b5..9777c0fd68c 100644 --- a/src/sage/categories/sets_with_grading.py +++ b/src/sage/categories/sets_with_grading.py @@ -22,7 +22,7 @@ class SetsWithGrading(Category): A *set with a grading* is a set `S` equipped with a grading by some other set `I` (by default the set `\NN` of the - non-negative integers): + nonnegative integers): .. MATH:: @@ -54,7 +54,7 @@ class SetsWithGrading(Category): EXAMPLES: - A typical example of a set with a grading is the set of non-negative + A typical example of a set with a grading is the set of nonnegative integers graded by themselves:: sage: N = SetsWithGrading().example(); N @@ -137,7 +137,7 @@ def _test_graded_components(self, **options): def grading_set(self): """ Return the set ``self`` is graded by. By default, this is - the set of non-negative integers. + the set of nonnegative integers. EXAMPLES:: @@ -203,9 +203,7 @@ def generating_series(self): """ Default implementation for generating series. - OUTPUT: - - A series, indexed by the grading set. + OUTPUT: a series, indexed by the grading set EXAMPLES:: @@ -225,7 +223,7 @@ def generating_series(self): from sage.rings.lazy_series_ring import LazyPowerSeriesRing from sage.sets.non_negative_integers import NonNegativeIntegers if isinstance(self.grading_set(), NonNegativeIntegers): - R = LazyPowerSeriesRing(ZZ, names="z") + R = LazyPowerSeriesRing(ZZ, names='z') return R(lambda n: self.graded_component(n).cardinality()) raise NotImplementedError diff --git a/src/sage/categories/sets_with_partial_maps.py b/src/sage/categories/sets_with_partial_maps.py index 01993c2fb82..8fb38cf894b 100644 --- a/src/sage/categories/sets_with_partial_maps.py +++ b/src/sage/categories/sets_with_partial_maps.py @@ -18,7 +18,7 @@ class SetsWithPartialMaps(Category_singleton): """ The category whose objects are sets and whose morphisms are - maps that are allowed to raise a :class:`ValueError` on some inputs. + maps that are allowed to raise a :exc:`ValueError` on some inputs. This category is equivalent to the category of pointed sets, via the equivalence sending an object X to X union {error}, diff --git a/src/sage/categories/simplicial_sets.py b/src/sage/categories/simplicial_sets.py index e714a4571c4..aabd3cdbb4f 100644 --- a/src/sage/categories/simplicial_sets.py +++ b/src/sage/categories/simplicial_sets.py @@ -30,7 +30,7 @@ class SimplicialSets(Category_singleton): The category of simplicial sets. A simplicial set `X` is a collection of sets `X_i`, indexed by - the non-negative integers, together with maps + the nonnegative integers, together with maps .. math:: @@ -203,7 +203,7 @@ class Pointed(CategoryWithAxiom): class ParentMethods: def base_point(self): """ - Return this simplicial set's base point + Return this simplicial set's base point. EXAMPLES:: @@ -229,11 +229,11 @@ def base_point_map(self, domain=None): INPUT: - - ``domain`` -- optional, default ``None``. Use - this to specify a particular one-point space as - the domain. The default behavior is to use the - :func:`sage.topology.simplicial_set.Point` - function to use a standard one-point space. + - ``domain`` -- (default: ``None``) use this to specify a + particular one-point space as the domain. The default + behavior is to use the + :func:`sage.topology.simplicial_set.Point` function to use a + standard one-point space. EXAMPLES:: @@ -278,7 +278,7 @@ def fundamental_group(self, simplify=True): INPUT: - - ``simplify`` (bool, optional ``True``) -- if + - ``simplify`` -- boolean (default: ``True``); if ``False``, then return a presentation of the group in terms of generators and relations. If ``True``, the default, simplify as much as GAP is able to. @@ -420,7 +420,6 @@ def universal_cover_map(self): (f, e): ((1, 1), (1, e)), (f * f, 1): ((f, e), s_0 (1, 1), (f, 1)), (f * f, e): ((f, 1), s_0 (1, e), (f, e))} - """ edges = self.n_cells(1) if not edges: @@ -439,8 +438,7 @@ def covering_map(self, character): INPUT: - - ``character`` -- a dictionary - + - ``character`` -- dictionary EXAMPLES:: @@ -527,7 +525,7 @@ def cover(self, character): INPUT: - - ``character`` -- a dictionary + - ``character`` -- dictionary EXAMPLES:: @@ -602,7 +600,6 @@ def _canonical_twisting_operator(self): {f: F1bar} sage: list(d2.values())[0].parent() Quotient of Univariate Laurent Polynomial Ring in F1 over Integer Ring by the ideal (-1 + F1^2) - """ G, d = self._universal_cover_dict() phi = G.abelianization_map() @@ -624,7 +621,7 @@ def twisted_chain_complex(self, twisting_operator=None, dimensions=None, augment INPUT: - - ``twisting_operator`` -- a dictionary, associating the twist of each + - ``twisting_operator`` -- dictionary, associating the twist of each simplex. If it is not given, the canonical one (associated to the laurent polynomial ring abelianization of the fundamental group, ignoring torsion) is used. @@ -634,20 +631,20 @@ def twisted_chain_complex(self, twisting_operator=None, dimensions=None, augment chain complex in those dimensions, setting the chain groups in all other dimensions to zero. - - ``augmented`` (default: ``False``) -- if ``True``, + - ``augmented`` -- boolean (default: ``False``); if ``True``, return the augmented chain complex (that is, include a class in dimension `-1` corresponding to the empty cell). - - ``cochain`` (default: ``False``) -- if ``True``, + - ``cochain`` -- boolean (default: ``False``); if ``True``, return the cochain complex (that is, the dual of the chain complex). - - ``verbose`` (default: ``False``) -- ignored. + - ``verbose`` -- boolean (default: ``False``); ignored - - ``subcomplex`` (default: ``None``) -- if present, - compute the chain complex relative to this subcomplex. + - ``subcomplex`` -- (default: ``None``) if present, + compute the chain complex relative to this subcomplex - - ``check`` (default: ``False``) -- If ``True``, make + - ``check`` -- boolean (default: ``False``); if ``True``, make sure that the chain complex is actually a chain complex: the differentials are composable and their product is zero. @@ -696,7 +693,6 @@ def twisted_chain_complex(self, twisting_operator=None, dimensions=None, augment [1 + F1] sage: C.differential(3) [] - """ from sage.homology.chain_complex import ChainComplex from sage.structure.element import get_coercion_model @@ -825,10 +821,10 @@ def twisted_homology(self, n, reduced=False): INPUT: - - ``n`` -- a positive integer. + - ``n`` -- positive integer - - ``reduced`` -- (default: ``False``) if set to True, the presentation matrix - will be reduced. + - ``reduced`` -- boolean (default: ``False``); if set to True, + the presentation matrix will be reduced EXAMPLES:: @@ -893,7 +889,6 @@ def twisted_homology(self, n, reduced=False): sage: X.universal_cover().homology(2) Z^5 sage: from sage.libs.singular.function import singular_function - """ from sage.libs.singular.function import singular_function from sage.libs.singular.option import opt_verb diff --git a/src/sage/categories/subobjects.py b/src/sage/categories/subobjects.py index db64d84d9c4..47a81f1c9a9 100644 --- a/src/sage/categories/subobjects.py +++ b/src/sage/categories/subobjects.py @@ -24,7 +24,7 @@ class SubobjectsCategory(RegressiveCovariantConstructionCategory): @classmethod def default_super_categories(cls, category): """ - Returns the default super categories of ``category.Subobjects()`` + Return the default super categories of ``category.Subobjects()``. Mathematical meaning: if `A` is a subobject of `B` in the category `C`, then `A` is also a subquotient of `B` in the @@ -32,8 +32,8 @@ def default_super_categories(cls, category): INPUT: - - ``cls`` -- the class ``SubobjectsCategory`` - - ``category`` -- a category `Cat` + - ``cls`` -- the class ``SubobjectsCategory`` + - ``category`` -- a category `Cat` OUTPUT: a (join) category diff --git a/src/sage/categories/super_algebras.py b/src/sage/categories/super_algebras.py index abb2d404002..658dfebd2d8 100644 --- a/src/sage/categories/super_algebras.py +++ b/src/sage/categories/super_algebras.py @@ -78,7 +78,7 @@ def tensor(*parents, **kwargs): EXAMPLES:: sage: # needs sage.combinat sage.modules - sage: A. = ExteriorAlgebra(ZZ); A.rename("A") + sage: A. = ExteriorAlgebra(ZZ); A.rename('A') sage: T = A.tensor(A,A); T A # A # A sage: T in Algebras(ZZ).Graded().SignedTensorProducts() diff --git a/src/sage/categories/super_algebras_with_basis.py b/src/sage/categories/super_algebras_with_basis.py index 46731a1609f..aa0de0004ef 100644 --- a/src/sage/categories/super_algebras_with_basis.py +++ b/src/sage/categories/super_algebras_with_basis.py @@ -16,7 +16,7 @@ class SuperAlgebrasWithBasis(SuperModulesCategory): """ - The category of super algebras with a distinguished basis + The category of super algebras with a distinguished basis. EXAMPLES:: diff --git a/src/sage/categories/super_modules.py b/src/sage/categories/super_modules.py index fe44beff26b..4e02ccbae30 100644 --- a/src/sage/categories/super_modules.py +++ b/src/sage/categories/super_modules.py @@ -38,9 +38,7 @@ def default_super_categories(cls, category, *args): - ``category`` -- a category `Cat` - ``*args`` -- further arguments for the functor - OUTPUT: - - A join category. + OUTPUT: a join category This implements the property that subcategories constructed by the set of whitelisted axioms is a subcategory. @@ -134,7 +132,7 @@ def super_categories(self): def extra_super_categories(self): r""" - Adds :class:`VectorSpaces` to the super categories of ``self`` if + Add :class:`VectorSpaces` to the super categories of ``self`` if the base ring is a field. EXAMPLES:: diff --git a/src/sage/categories/supercrystals.py b/src/sage/categories/supercrystals.py index fdc074a37d9..09b924e0ad6 100644 --- a/src/sage/categories/supercrystals.py +++ b/src/sage/categories/supercrystals.py @@ -121,7 +121,7 @@ def edge_options(data): edge_opts['label'] = LatexExpr(str(l)) return edge_opts - G.set_latex_options(format="dot2tex", edge_labels=True, edge_options=edge_options) + G.set_latex_options(format='dot2tex', edge_labels=True, edge_options=edge_options) return G def genuine_highest_weight_vectors(self): diff --git a/src/sage/categories/tensor.py b/src/sage/categories/tensor.py index 11e470e378f..c9de28aecfd 100644 --- a/src/sage/categories/tensor.py +++ b/src/sage/categories/tensor.py @@ -55,8 +55,6 @@ class TensorProductFunctor(CovariantFunctorialConstruction): tensor = TensorProductFunctor() - - """ The tensor product functorial construction @@ -71,7 +69,7 @@ class TensorProductFunctor(CovariantFunctorialConstruction): class TensorProductsCategory(CovariantConstructionCategory): r""" - An abstract base class for all TensorProducts's categories + An abstract base class for all TensorProducts's categories. TESTS:: @@ -88,7 +86,7 @@ class TensorProductsCategory(CovariantConstructionCategory): def TensorProducts(self): """ - Returns the category of tensor products of objects of ``self`` + Return the category of tensor products of objects of ``self``. By associativity of tensor products, this is ``self`` (a tensor product of tensor products of `Cat`'s is a tensor product of `Cat`'s) diff --git a/src/sage/categories/triangular_kac_moody_algebras.py b/src/sage/categories/triangular_kac_moody_algebras.py index 677b20e06f4..19ff3846b67 100644 --- a/src/sage/categories/triangular_kac_moody_algebras.py +++ b/src/sage/categories/triangular_kac_moody_algebras.py @@ -42,7 +42,6 @@ def super_categories(self): sage: TriangularKacMoodyAlgebras(QQ).super_categories() [Join of Category of graded Lie algebras with basis over Rational Field and Category of kac moody algebras over Rational Field] - """ # We do not also derive from (Magmatic) algebras since we don't want * # to be our Lie bracket @@ -313,7 +312,7 @@ def part(self): EXAMPLES:: sage: # needs sage.combinat sage.modules - sage: L = LieAlgebra(QQ, cartan_type="F4") + sage: L = LieAlgebra(QQ, cartan_type='F4') sage: L.inject_variables() Defining e1, e2, e3, e4, f1, f2, f3, f4, h1, h2, h3, h4 sage: e1.part() diff --git a/src/sage/categories/unique_factorization_domains.py b/src/sage/categories/unique_factorization_domains.py index a4a66111f4b..0189898f6d0 100644 --- a/src/sage/categories/unique_factorization_domains.py +++ b/src/sage/categories/unique_factorization_domains.py @@ -34,7 +34,6 @@ class UniqueFactorizationDomains(Category_singleton): TESTS:: sage: TestSuite(UniqueFactorizationDomains()).run() - """ def super_categories(self): @@ -127,7 +126,6 @@ def is_unique_factorization_domain(self, proof=True): sage: UFD = UniqueFactorizationDomains() sage: Parent(QQ, category=UFD).is_unique_factorization_domain() True - """ return True @@ -137,7 +135,7 @@ def _gcd_univariate_polynomial(self, f, g): INPUT: - - ``f``, ``g`` -- two polynomials defined over this UFD. + - ``f``, ``g`` -- two polynomials defined over this UFD .. NOTE:: @@ -169,7 +167,6 @@ def _gcd_univariate_polynomial(self, f, g): sage: g = 4*x + 2 sage: f.gcd(g).parent() is R True - """ if f.degree() < g.degree(): A,B = g, f @@ -294,7 +291,6 @@ def squarefree_part(self): sage: squarefree_part(pol) 37*x^3 - 1369/21*x^2 + 703/21*x - 37/7 - """ decomp = self.squarefree_decomposition() return prod(fac for fac, mult in decomp if mult % 2 == 1) diff --git a/src/sage/categories/vector_bundles.py b/src/sage/categories/vector_bundles.py index bd6e569ba36..4d87464bd18 100644 --- a/src/sage/categories/vector_bundles.py +++ b/src/sage/categories/vector_bundles.py @@ -35,8 +35,7 @@ class VectorBundles(Category_over_base_ring): TESTS:: - sage: TestSuite(C).run(skip="_test_category_over_bases") - + sage: TestSuite(C).run(skip='_test_category_over_bases') """ def __init__(self, base_space, base_field, name=None): r""" @@ -47,8 +46,7 @@ def __init__(self, base_space, base_field, name=None): sage: M = Manifold(2, 'M') sage: from sage.categories.vector_bundles import VectorBundles sage: C = VectorBundles(M, RR) - sage: TestSuite(C).run(skip="_test_category_over_bases") - + sage: TestSuite(C).run(skip='_test_category_over_bases') """ if base_field not in Fields().Topological(): raise ValueError("base field must be a topological field") @@ -64,7 +62,6 @@ def super_categories(self): sage: from sage.categories.vector_bundles import VectorBundles sage: VectorBundles(M, RR).super_categories() [Category of topological spaces] - """ return [Sets().Topological()] @@ -78,7 +75,6 @@ def base_space(self): sage: from sage.categories.vector_bundles import VectorBundles sage: VectorBundles(M, RR).base_space() 2-dimensional topological manifold M - """ return self._base_space @@ -95,7 +91,6 @@ def _repr_object_names(self): sage: VectorBundles(M, RR)._repr_object_names() 'vector bundles over Real Field with 53 bits of precision with base space 2-dimensional differentiable manifold M' - """ base_space = self._base_space return Category_over_base_ring._repr_object_names(self) + \ @@ -122,7 +117,6 @@ def Differentiable(self): sage: TestSuite(VectorBundles(M, RR).Differentiable()).run() sage: VectorBundles(M, RR).Differentiable.__module__ 'sage.categories.vector_bundles' - """ return self._with_axiom('Differentiable') diff --git a/src/sage/categories/vector_spaces.py b/src/sage/categories/vector_spaces.py index 84286a83bc4..d0da56da108 100644 --- a/src/sage/categories/vector_spaces.py +++ b/src/sage/categories/vector_spaces.py @@ -27,7 +27,7 @@ class VectorSpaces(Category_module): """ - The category of (abstract) vector spaces over a given field + The category of (abstract) vector spaces over a given field. ??? with an embedding in an ambient vector space ??? @@ -43,8 +43,9 @@ def __classcall_private__(cls, K, check=True): """ INPUT: - - `K` -- a field - - ``check`` -- a boolean (default: ``True``) whether to check that `K` is a field. + - ``K`` -- a field + - ``check`` -- boolean (default: ``True``); whether to check that `K` + is a field EXAMPLES:: @@ -92,7 +93,7 @@ def __init__(self, K): def _call_(self, x): """ - Try to coerce ``x`` into an object of this category + Try to coerce ``x`` into an object of this category. EXAMPLES:: @@ -106,7 +107,6 @@ def _call_(self, x): sage: Q3 = FiniteRankFreeModule(QQ, 3) # needs sage.modules sage: Modules(QQ)(Q3) is Q3 # needs sage.modules True - """ try: V = x.vector_space(self.base_field()) @@ -118,7 +118,7 @@ def _call_(self, x): def base_field(self): """ - Returns the base field over which the vector spaces of this + Return the base field over which the vector spaces of this category are all defined. EXAMPLES:: @@ -174,7 +174,6 @@ def dimension(self): 3 sage: M.tensor_module(1, 2).dimension() # needs sage.modules 27 - """ return self.rank() @@ -239,7 +238,6 @@ def extra_super_categories(self): [Category of finite dimensional vector spaces with basis over Rational Field] sage: VectorSpaces(QQ).WithBasis().FiniteDimensional().TensorProducts().FiniteDimensional() Category of tensor products of finite dimensional vector spaces with basis over Rational Field - """ return [self.base_category()] @@ -300,7 +298,6 @@ def extra_super_categories(self): [Category of finite dimensional vector spaces over Rational Field] sage: VectorSpaces(QQ).FiniteDimensional().TensorProducts().FiniteDimensional() Category of tensor products of finite dimensional vector spaces over Rational Field - """ return [self.base_category()] @@ -308,7 +305,7 @@ class DualObjects(DualObjectsCategory): def extra_super_categories(self): r""" - Returns the dual category + Return the dual category. EXAMPLES: diff --git a/src/sage/categories/weyl_groups.py b/src/sage/categories/weyl_groups.py index aa2d4cd6f11..8472aaa455c 100644 --- a/src/sage/categories/weyl_groups.py +++ b/src/sage/categories/weyl_groups.py @@ -18,7 +18,7 @@ class WeylGroups(Category_singleton): r""" - The category of Weyl groups + The category of Weyl groups. See the :wikipedia:`Wikipedia page of Weyl Groups `. @@ -94,7 +94,7 @@ def coxeter_matrix(self): def pieri_factors(self, *args, **keywords): r""" - Returns the set of Pieri factors in this Weyl group. + Return the set of Pieri factors in this Weyl group. For any type, the set of Pieri factors forms a lower ideal in Bruhat order, generated by all the conjugates of some @@ -171,7 +171,7 @@ def bruhat_cone(self, x, y, side='upper', backend='cdd'): - ``y`` -- an element in the group `W` - - ``side`` (default: ``'upper'``) -- must be one of the following: + - ``side`` -- (default: ``'upper'``) must be one of the following: * ``'upper'`` -- return the upper Bruhat cone of the interval [``x``, ``y``] * ``'lower'`` -- return the lower Bruhat cone of the interval [``x``, ``y``] @@ -243,7 +243,7 @@ def quantum_bruhat_graph(self, index_set=()): EXAMPLES:: - sage: W = WeylGroup(['A',3], prefix="s") + sage: W = WeylGroup(['A',3], prefix='s') sage: g = W.quantum_bruhat_graph((1,3)) sage: g Parabolic Quantum Bruhat Graph of Weyl Group of type ['A', 3] @@ -260,7 +260,7 @@ def quantum_bruhat_graph(self, index_set=()): (s2, s1*s2, alpha[1] + alpha[2]), (s2, s3*s2, alpha[2] + alpha[3]), (1, s2, alpha[2])] - sage: W = WeylGroup(['A',3,1], prefix="s") + sage: W = WeylGroup(['A',3,1], prefix='s') sage: g = W.quantum_bruhat_graph() Traceback (most recent call last): ... @@ -317,14 +317,14 @@ def length(x): from sage.graphs.digraph import DiGraph return DiGraph(visited, name="Parabolic Quantum Bruhat Graph of %s for nodes %s" % (self, index_set), - format="dict_of_dicts", - data_structure="static_sparse") + format='dict_of_dicts', + data_structure='static_sparse') class ElementMethods: def is_pieri_factor(self): r""" - Returns whether ``self`` is a Pieri factor, as used for + Return whether ``self`` is a Pieri factor, as used for computing Stanley symmetric functions. .. SEEALSO:: @@ -357,7 +357,7 @@ def is_pieri_factor(self): def left_pieri_factorizations(self, max_length=None): r""" - Returns all factorizations of ``self`` as `uv`, where `u` + Return all factorizations of ``self`` as `uv`, where `u` is a Pieri factor and `v` is an element of the Weyl group. .. SEEALSO:: @@ -426,7 +426,7 @@ def predicate(u): @cached_in_parent_method def stanley_symmetric_function_as_polynomial(self, max_length=None): r""" - Returns a multivariate generating function for the number + Return a multivariate generating function for the number of factorizations of a Weyl group element into Pieri factors of decreasing length, weighted by a statistic on Pieri factors. @@ -440,7 +440,7 @@ def stanley_symmetric_function_as_polynomial(self, max_length=None): INPUT: - ``self`` -- an element `w` of a Weyl group `W` - - ``max_length`` -- a non negative integer or infinity (default: infinity) + - ``max_length`` -- nonnegative integer or infinity (default: infinity) Returns the generating series for the Pieri factorizations `w = u_1 \cdots u_k`, where `u_i` is a Pieri factor for @@ -585,7 +585,7 @@ def reflection_to_root(self): EXAMPLES:: - sage: W = WeylGroup(['C',2],prefix="s") + sage: W = WeylGroup(['C',2], prefix='s') sage: W.from_reduced_word([1,2,1]).reflection_to_root() 2*alpha[1] + alpha[2] sage: W.from_reduced_word([1,2]).reflection_to_root() @@ -614,7 +614,7 @@ def reflection_to_coroot(self): EXAMPLES:: - sage: W = WeylGroup(['C',2],prefix="s") + sage: W = WeylGroup(['C',2], prefix='s') sage: W.from_reduced_word([1,2,1]).reflection_to_coroot() alphacheck[1] + alphacheck[2] sage: W.from_reduced_word([1,2]).reflection_to_coroot() @@ -655,7 +655,7 @@ def inversions(self, side='right', inversion_type='reflections'): EXAMPLES:: - sage: W = WeylGroup(['C',2], prefix="s") + sage: W = WeylGroup(['C',2], prefix='s') sage: w = W.from_reduced_word([1,2]) sage: w.inversions() [s2, s2*s1*s2] @@ -743,7 +743,7 @@ def bruhat_lower_covers_coroots(self): EXAMPLES:: - sage: W = WeylGroup(['A',3], prefix="s") + sage: W = WeylGroup(['A',3], prefix='s') sage: w = W.from_reduced_word([3,1,2,1]) sage: w.bruhat_lower_covers_coroots() [(s1*s2*s1, alphacheck[1] + alphacheck[2] + alphacheck[3]), @@ -754,7 +754,7 @@ def bruhat_lower_covers_coroots(self): def bruhat_upper_covers_coroots(self): r""" - Returns all 2-tuples (``v``, `\alpha`) where ``v`` is covers ``self`` and `\alpha` + Return all 2-tuples (``v``, `\alpha`) where ``v`` is covers ``self`` and `\alpha` is the positive coroot such that ``self`` = ``v`` `s_\alpha` where `s_\alpha` is the reflection orthogonal to `\alpha`. @@ -764,7 +764,7 @@ def bruhat_upper_covers_coroots(self): EXAMPLES:: - sage: W = WeylGroup(['A',4], prefix="s") + sage: W = WeylGroup(['A',4], prefix='s') sage: w = W.from_reduced_word([3,1,2,1]) sage: w.bruhat_upper_covers_coroots() [(s1*s2*s3*s2*s1, alphacheck[3]), @@ -791,17 +791,17 @@ def quantum_bruhat_successors(self, index_set=None, roots=False, quantum_only=Fa simple reflections used to generate the parabolic subgroup; the default value indicates that the subgroup is the identity - - ``roots`` -- (default: ``False``) if ``True``, returns the - list of 2-tuples (``w``, `\alpha`) where ``w`` is a successor + - ``roots`` -- boolean (default: ``False``); if ``True``, returns + the list of 2-tuples (``w``, `\alpha`) where ``w`` is a successor and `\alpha` is the positive root associated with the successor relation - - ``quantum_only`` -- (default: ``False``) if ``True``, returns - only the quantum successors + - ``quantum_only`` -- boolean (default: ``False``); if ``True``, + returns only the quantum successors EXAMPLES:: - sage: W = WeylGroup(['A',3], prefix="s") + sage: W = WeylGroup(['A',3], prefix='s') sage: w = W.from_reduced_word([3,1,2]) sage: w.quantum_bruhat_successors([1], roots = True) [(s3, alpha[2]), (s1*s2*s3*s2, alpha[3]), diff --git a/src/sage/coding/abstract_code.py b/src/sage/coding/abstract_code.py index ca46d40327b..d94eb1ca309 100644 --- a/src/sage/coding/abstract_code.py +++ b/src/sage/coding/abstract_code.py @@ -205,7 +205,7 @@ class AbstractCode(Parent): def __init__(self, length, default_encoder_name=None, default_decoder_name=None, metric='Hamming'): r""" - Initializes mandatory parameters that any code shares. + Initialize mandatory parameters that any code shares. This method only exists for inheritance purposes as it initializes parameters that need to be known by every code. The class @@ -281,19 +281,19 @@ def __init__(self, length, default_encoder_name=None, ... ValueError: length must be a Python int or a Sage Integer - If the length of the code is not a non-zero positive integer + If the length of the code is not a nonzero positive integer (See :issue:`21326`), it will raise an exception:: sage: C = MyCodeFamily(0) Traceback (most recent call last): ... - ValueError: length must be a non-zero positive integer + ValueError: length must be a nonzero positive integer """ if not isinstance(length, (int, Integer)): raise ValueError("length must be a Python int or a Sage Integer") if length <= 0: - raise ValueError("length must be a non-zero positive integer") + raise ValueError("length must be a nonzero positive integer") self._length = length self._metric = metric @@ -398,7 +398,7 @@ def ambient_space(self): def __call__(self, m): r""" - Returns either ``m`` if it is a codeword or ``self.encode(m)`` + Return either ``m`` if it is a codeword or ``self.encode(m)`` if it is an element of the message space of the encoder used by ``encode``. @@ -516,7 +516,7 @@ def list(self): def length(self): r""" - Returns the length of this code. + Return the length of this code. EXAMPLES:: @@ -542,7 +542,7 @@ def metric(self): def add_decoder(self, name, decoder): r""" - Adds an decoder to the list of registered decoders of ``self``. + Add an decoder to the list of registered decoders of ``self``. .. NOTE:: @@ -604,7 +604,7 @@ def add_decoder(self, name, decoder): def add_encoder(self, name, encoder): r""" - Adds an encoder to the list of registered encoders of ``self``. + Add an encoder to the list of registered encoders of ``self``. .. NOTE:: @@ -672,15 +672,13 @@ def decode_to_code(self, word, decoder_name=None, *args, **kwargs): - ``word`` -- an element in the ambient space as ``self`` - - ``decoder_name`` -- (default: ``None``) Name of the decoder which will be used + - ``decoder_name`` -- (default: ``None``) name of the decoder which will be used to decode ``word``. The default decoder of ``self`` will be used if default value is kept. - ``args``, ``kwargs`` -- all additional arguments are forwarded to :meth:`decoder` - OUTPUT: - - - A vector of ``self``. + OUTPUT: a vector of ``self`` EXAMPLES:: @@ -710,15 +708,13 @@ def decode_to_message(self, word, decoder_name=None, *args, **kwargs): - ``word`` -- an element in the ambient space as ``self`` - - ``decoder_name`` -- (default: ``None``) Name of the decoder which will be used + - ``decoder_name`` -- (default: ``None``) name of the decoder which will be used to decode ``word``. The default decoder of ``self`` will be used if default value is kept. - ``args``, ``kwargs`` -- all additional arguments are forwarded to :meth:`decoder` - OUTPUT: - - - A vector of the message space of ``self``. + OUTPUT: a vector of the message space of ``self`` EXAMPLES:: @@ -752,9 +748,7 @@ def decoder(self, decoder_name=None, *args, **kwargs): - ``args``, ``kwargs`` -- all additional arguments will be forwarded to the constructor of the decoder that will be returned by this method - OUTPUT: - - - a decoder object + OUTPUT: a decoder object Besides creating the decoder and returning it, this method also stores the decoder in a cache. With this behaviour, each decoder will be created @@ -810,7 +804,6 @@ def decoder(self, decoder_name=None, *args, **kwargs): It accepts unspecified arguments as well. See the documentation of sage.coding.information_set_decoder.LinearCodeInformationSetDecoder for more details. - """ if not self._default_decoder_name: raise NotImplementedError("No decoder implemented for this code.") @@ -832,15 +825,15 @@ def decoder(self, decoder_name=None, *args, **kwargs): def decoders_available(self, classes=False): r""" - Returns a list of the available decoders' names for ``self``. + Return a list of the available decoders' names for ``self``. INPUT: - - ``classes`` -- (default: ``False``) if ``classes`` is set to ``True``, - return instead a :class:`dict` mapping available decoder name to the - associated decoder class. + - ``classes`` -- boolean (default: ``False``); if ``classes`` is set to + ``True``, return instead a :class:`dict` mapping available decoder + name to the associated decoder class - OUTPUT: a list of strings, or a :class:`dict` mapping strings to classes. + OUTPUT: list of strings, or a :class:`dict` mapping strings to classes EXAMPLES:: @@ -863,26 +856,24 @@ def decoders_available(self, classes=False): def encode(self, word, encoder_name=None, *args, **kwargs): r""" - Transforms an element of a message space into a codeword. + Transform an element of a message space into a codeword. INPUT: - ``word`` -- an element of a message space of the code - - ``encoder_name`` -- (default: ``None``) Name of the encoder which will be used - to encode ``word``. The default encoder of ``self`` will be used if - default value is kept. + - ``encoder_name`` -- (default: ``None``) name of the encoder which + will be used to encode ``word``. The default encoder of ``self`` will + be used if default value is kept. - - ``args``, ``kwargs`` -- all additional arguments are forwarded to the construction of the - encoder that is used.. + - ``args``, ``kwargs`` -- all additional arguments are forwarded to the + construction of the encoder that is used One can use the following shortcut to encode a word :: C(word) - OUTPUT: - - - a vector of ``self``. + OUTPUT: a vector of ``self`` EXAMPLES:: @@ -909,7 +900,7 @@ def encode(self, word, encoder_name=None, *args, **kwargs): @cached_method def encoder(self, encoder_name=None, *args, **kwargs): r""" - Returns an encoder of ``self``. + Return an encoder of ``self``. The returned encoder provided by this method is cached. @@ -923,12 +914,10 @@ def encoder(self, encoder_name=None, *args, **kwargs): returned. The default encoder of ``self`` will be used if default value is kept. - - ``args``, ``kwargs`` -- all additional arguments are forwarded to the constructor of the encoder - this method will return. - - OUTPUT: + - ``args``, ``kwargs`` -- all additional arguments are forwarded to the + constructor of the encoder this method will return - - an Encoder object. + OUTPUT: an Encoder object .. NOTE:: @@ -1011,15 +1000,15 @@ def encoder(self, encoder_name=None, *args, **kwargs): def encoders_available(self, classes=False): r""" - Returns a list of the available encoders' names for ``self``. + Return a list of the available encoders' names for ``self``. INPUT: - - ``classes`` -- (default: ``False``) if ``classes`` is set to ``True``, - return instead a :class:`dict` mapping available encoder name to the - associated encoder class. + - ``classes`` -- boolean (default: ``False``); if ``classes`` is set to + ``True``, return instead a :class:`dict` mapping available encoder + name to the associated encoder class - OUTPUT: a list of strings, or a :class:`dict` mapping strings to classes. + OUTPUT: list of strings, or a :class:`dict` mapping strings to classes EXAMPLES:: @@ -1040,29 +1029,28 @@ def encoders_available(self, classes=False): def unencode(self, c, encoder_name=None, nocheck=False, **kwargs): r""" - Returns the message corresponding to ``c``. + Return the message corresponding to ``c``. This is the inverse of :meth:`encode`. INPUT: - - ``c`` -- a codeword of ``self``. + - ``c`` -- a codeword of ``self`` - ``encoder_name`` -- (default: ``None``) name of the decoder which will be used to decode ``word``. The default decoder of ``self`` will be used if default value is kept. - - ``nocheck`` -- (default: ``False``) checks if ``c`` is in ``self``. You might set - this to ``True`` to disable the check for saving computation. Note that if ``c`` is - not in ``self`` and ``nocheck = True``, then the output of :meth:`unencode` is - not defined (except that it will be in the message space of ``self``). + - ``nocheck`` -- boolean (default: ``False``); checks if ``c`` is in + ``self``. You might set this to ``True`` to disable the check for + saving computation. Note that if ``c`` is not in ``self`` and + ``nocheck = True``, then the output of :meth:`unencode` is not + defined (except that it will be in the message space of ``self``). - ``kwargs`` -- all additional arguments are forwarded to the construction of the - encoder that is used. + encoder that is used - OUTPUT: - - - an element of the message space of ``encoder_name`` of ``self``. + OUTPUT: an element of the message space of ``encoder_name`` of ``self`` EXAMPLES:: @@ -1078,12 +1066,10 @@ def unencode(self, c, encoder_name=None, nocheck=False, **kwargs): def random_element(self, *args, **kwds): """ - Returns a random codeword; passes other positional and keyword + Return a random codeword; passes other positional and keyword arguments to ``random_element()`` method of vector space. - OUTPUT: - - - Random element of the vector space of this code + OUTPUT: random element of the vector space of this code EXAMPLES:: diff --git a/src/sage/coding/ag_code.py b/src/sage/coding/ag_code.py index a29cbe7e7d0..5f77b346fa4 100644 --- a/src/sage/coding/ag_code.py +++ b/src/sage/coding/ag_code.py @@ -120,7 +120,7 @@ class EvaluationAGCode(AGCode): INPUT: - - ``pls`` -- a list of rational places of a function field + - ``pls`` -- list of rational places of a function field - ``G`` -- a divisor whose support is disjoint from ``pls`` @@ -331,7 +331,7 @@ def designed_distance(self): """ Return the designed distance of the AG code. - If the code is of dimension zero, then a :class:`ValueError` is raised. + If the code is of dimension zero, then a :exc:`ValueError` is raised. EXAMPLES:: @@ -355,11 +355,11 @@ def designed_distance(self): class DifferentialAGCode(AGCode): """ - Differential AG code defined by rational places ``pls`` and a divisor ``G`` + Differential AG code defined by rational places ``pls`` and a divisor ``G``. INPUT: - - ``pls`` -- a list of rational places of a function field + - ``pls`` -- list of rational places of a function field - ``G`` -- a divisor whose support is disjoint from ``pls`` @@ -575,7 +575,7 @@ def designed_distance(self): """ Return the designed distance of the differential AG code. - If the code is of dimension zero, then a :class:`ValueError` is raised. + If the code is of dimension zero, then a :exc:`ValueError` is raised. EXAMPLES:: @@ -603,7 +603,7 @@ class CartierCode(AGCode): INPUT: - - ``pls`` -- a list of rational places + - ``pls`` -- list of rational places - ``G`` -- a divisor whose support is disjoint from ``pls`` @@ -611,7 +611,7 @@ class CartierCode(AGCode): - ``name`` -- string; name of the generator of the subfield `\GF{p^r}` - OUTPUT: Cartier code over `\GF{p^r}` where `p` is the characteristic of the + OUTPUT: cartier code over `\GF{p^r}` where `p` is the characteristic of the base constant field of the function field Note that if ``r`` is 1 the default, then ``name`` can be omitted. diff --git a/src/sage/coding/ag_code_decoders.pyx b/src/sage/coding/ag_code_decoders.pyx index ceb3eb327fd..df59bad740d 100644 --- a/src/sage/coding/ag_code_decoders.pyx +++ b/src/sage/coding/ag_code_decoders.pyx @@ -76,7 +76,7 @@ from sage.rings.polynomial.polynomial_element cimport Polynomial class EvaluationAGCodeEncoder(Encoder): """ - Encoder of an evaluation AG code + Encoder of an evaluation AG code. INPUT: @@ -1464,7 +1464,7 @@ cdef class Decoder_K(): - ``detect_Q_polynomial`` -- boolean; if ``True``, a Q-polynomial is detected for fast decoding - If decoding fails for some reason, ``DecodingError`` is raised. The + If decoding fails for some reason, :exc:`DecodingError` is raised. The message contained in the exception indicates the type of the decoding failure. @@ -1811,13 +1811,13 @@ cdef class EvaluationAGCodeDecoder_K(Decoder_K): INPUT: - - ``pls`` -- a list of places of a function field + - ``pls`` -- list of places of a function field - ``G`` -- a divisor of the function field - ``Q`` -- a rational place not in ``pls`` - - ``verbose`` -- if ``True``, verbose information is printed. + - ``verbose`` -- if ``True``, verbose information is printed EXAMPLES:: @@ -2066,7 +2066,7 @@ cdef class DifferentialAGCodeDecoder_K(Decoder_K): INPUT: - - ``pls`` -- a list of places of a function field + - ``pls`` -- list of places of a function field - ``G`` -- a divisor of the function field @@ -2320,7 +2320,7 @@ cdef class Decoder_K_extension(): INPUT: - - ``pls`` -- a list of places of a function field + - ``pls`` -- list of places of a function field - ``G`` -- a divisor of the function field @@ -2538,7 +2538,7 @@ cdef class EvaluationAGCodeDecoder_K_extension(Decoder_K_extension): INPUT: - - ``pls`` -- a list of places of a function field + - ``pls`` -- list of places of a function field - ``G`` -- a divisor of the function field @@ -2592,7 +2592,7 @@ cdef class DifferentialAGCodeDecoder_K_extension(Decoder_K_extension): INPUT: - - ``pls`` -- a list of places of a function field + - ``pls`` -- list of places of a function field - ``G`` -- a divisor of the function field diff --git a/src/sage/coding/bch_code.py b/src/sage/coding/bch_code.py index 1344ba42f65..aeecdc01318 100644 --- a/src/sage/coding/bch_code.py +++ b/src/sage/coding/bch_code.py @@ -140,7 +140,7 @@ def __init__(self, base_field, length, designed_distance, def __eq__(self, other): r""" - Tests equality between BCH Code objects. + Test equality between BCH Code objects. EXAMPLES:: @@ -262,15 +262,15 @@ class BCHUnderlyingGRSDecoder(Decoder): INPUT: - - ``code`` -- The associated code of this decoder. + - ``code`` -- the associated code of this decoder - - ``grs_decoder`` -- The string name of the decoder to use over the + - ``grs_decoder`` -- the string name of the decoder to use over the underlying GRS code - - ``**kwargs`` -- All extra arguments are forwarded to the GRS decoder + - ``**kwargs`` -- all extra arguments are forwarded to the GRS decoder """ - def __init__(self, code, grs_decoder="KeyEquationSyndrome", **kwargs): + def __init__(self, code, grs_decoder='KeyEquationSyndrome', **kwargs): r""" EXAMPLES:: diff --git a/src/sage/coding/binary_code.pyx b/src/sage/coding/binary_code.pyx index 421422c7746..3c73e0f7176 100644 --- a/src/sage/coding/binary_code.pyx +++ b/src/sage/coding/binary_code.pyx @@ -88,7 +88,7 @@ cdef int *hamming_weights() noexcept: def weight_dist(M): """ - Computes the weight distribution of the row space of `M`. + Compute the weight distribution of the row space of `M`. EXAMPLES:: @@ -119,7 +119,6 @@ def weight_dist(M): ....: [0,0,0,0,0,0,0,1,0,0,1,1,1,1,0,0,1]]) sage: weight_dist(M) [1, 0, 0, 0, 0, 0, 68, 0, 85, 0, 68, 0, 34, 0, 0, 0, 0, 0] - """ cdef bitset_t word cdef int i,j,k, dim=M.nrows(), deg=M.ncols() @@ -193,7 +192,6 @@ def test_word_perms(t_limit=5.0): sage: from sage.coding.binary_code import test_word_perms sage: test_word_perms() # long time (5s on sage.math, 2011) - """ cdef WordPermutation *g cdef WordPermutation *h @@ -557,7 +555,6 @@ def test_expand_to_ortho_basis(B=None): 0000100001 0000010001 0000001001 - """ cdef codeword *output cdef int k=0, i @@ -581,8 +578,8 @@ cdef codeword *expand_to_ortho_basis(BinaryCode B, int n) noexcept: r""" INPUT: - - B -- a BinaryCode in standard form - - n -- the degree + - ``B`` -- a BinaryCode in standard form + - ``n`` -- the degree OUTPUT: @@ -738,7 +735,6 @@ cdef class BinaryCode: sage: B Binary [32,1] linear code, generator matrix [11111111111111111111111111111111] - """ def __cinit__(self, arg1, arg2=None): """ @@ -848,7 +844,6 @@ cdef class BinaryCode: sage: B = BinaryCode(M) sage: loads(dumps(B)) == B True - """ return BinaryCode, (self.matrix(),) @@ -882,7 +877,6 @@ cdef class BinaryCode: sage: B.matrix() [1 1 1 1 0 0] [0 0 1 1 1 1] - """ cdef int i, j from sage.matrix.constructor import matrix @@ -1016,7 +1010,6 @@ cdef class BinaryCode: [00111100] [00001111] [10101010] - """ cdef int i, j s = 'Binary [%d,%d] linear code, generator matrix\n'%(self.ncols, self.nrows) @@ -1026,9 +1019,9 @@ cdef class BinaryCode: def _word(self, coords): """ - Considering coords as an integer in binary, think of the 0's and 1's as - coefficients of the basis given by self.matrix(). This function returns - a string representation of that word. + Considering ``coords`` as an integer in binary, think of the 0s and 1s + as coefficients of the basis given by ``self.matrix()``. This function + returns a string representation of that word. EXAMPLES:: @@ -1042,7 +1035,6 @@ cdef class BinaryCode: Note that behavior under input which does not represent a word in the code is unspecified (gives nonsense). - """ s = '' for j from 0 <= j < self.ncols: @@ -1051,7 +1043,7 @@ cdef class BinaryCode: def _is_one(self, word, col): """ - Returns the col-th letter of word, i.e. 0 or 1. Words are expressed + Return the col-th letter of word, i.e. 0 or 1. Words are expressed as integers, which represent linear combinations of the rows of the generator matrix of the code. @@ -1073,7 +1065,6 @@ cdef class BinaryCode: 1 sage: B._is_automorphism([1,0,3,2,4,5,6,7], [0, 1, 2, 3, 4, 5, 6, 7, 9, 8, 11, 10, 13, 12, 15, 14]) 1 - """ return self.is_one(word, col) != 0 @@ -1086,10 +1077,10 @@ cdef class BinaryCode: INPUT: - - col_gamma -- permutation sending i |--> col_gamma[i] acting - on the columns. - - word_gamma -- permutation sending i |--> word_gamma[i] acting - on the words. + - ``col_gamma`` -- permutation sending i |--> col_gamma[i] acting + on the columns + - ``word_gamma`` -- permutation sending i |--> word_gamma[i] acting + on the words EXAMPLES:: @@ -1105,7 +1096,6 @@ cdef class BinaryCode: [10101010] sage: B._is_automorphism([1,0,3,2,4,5,6,7], [0, 1, 2, 3, 4, 5, 6, 7, 9, 8, 11, 10, 13, 12, 15, 14]) 1 - """ cdef int i cdef int *_col_gamma @@ -1141,7 +1131,7 @@ cdef class BinaryCode: INPUT: - - labeling -- a list permutation of the columns + - ``labeling`` -- list permutation of the columns EXAMPLES:: @@ -1176,7 +1166,6 @@ cdef class BinaryCode: [001000000000001011011110] [010000000000101110001101] [100000000000010111000111] - """ # Tests for this function implicitly test _apply_permutation_to_basis # and _update_words_from_basis. These functions should not be used @@ -1273,7 +1262,6 @@ cdef class OrbitPartition: cell of the partition, and the size of the partition. See :wikipedia:`Disjoint-set_data_structure` - """ def __cinit__(self, int nrows, int ncols): """ @@ -1347,7 +1335,6 @@ cdef class OrbitPartition: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15 Columns: 0,1,2,3,4,5,6,7 - """ cdef int i cdef int j @@ -1371,7 +1358,7 @@ cdef class OrbitPartition: def _wd_find(self, word): """ - Returns the root of word. + Return the root of word. EXAMPLES:: @@ -1386,7 +1373,6 @@ cdef class OrbitPartition: 0,1,2,3,4,5,6,7 sage: O._wd_find(12) 12 - """ return self.wd_find(word) @@ -1421,7 +1407,6 @@ cdef class OrbitPartition: 0,1,2,3,4,5,6,7 sage: O._wd_find(10) 1 - """ self.wd_union(x, y) @@ -1445,7 +1430,7 @@ cdef class OrbitPartition: def _col_find(self, col): """ - Returns the root of col. + Return the root of col. EXAMPLES:: @@ -1460,7 +1445,6 @@ cdef class OrbitPartition: 0,1,2,3,4,5,6,7 sage: O._col_find(6) 6 - """ return self.col_find(col) @@ -1495,7 +1479,6 @@ cdef class OrbitPartition: 0,1,2,3,1,5,6,7 sage: O._col_find(4) 1 - """ self.col_union(x, y) @@ -1519,7 +1502,7 @@ cdef class OrbitPartition: def _merge_perm(self, col_gamma, wd_gamma): """ - Merges the cells of self under the given permutation. If gamma[a] = b, + Merges the cells of ``self`` under the given permutation. If gamma[a] = b, then after merge_perm, a and b will be in the same cell. Returns 0 if nothing was done, otherwise returns 1. @@ -1542,7 +1525,6 @@ cdef class OrbitPartition: 0,1,2,3,4,5,6,7,8,8,10,10,12,12,14,14 Columns: 0,0,2,2,4,5,6,7 - """ cdef int i cdef int *_col_gamma @@ -1707,7 +1689,7 @@ cdef class PartitionStack: def print_data(self): """ - Prints all data for self. + Print all data for ``self``. EXAMPLES:: @@ -1780,7 +1762,6 @@ cdef class PartitionStack: 0 0 0 - """ cdef int i, j s = '' @@ -1829,7 +1810,7 @@ cdef class PartitionStack: def __repr__(self): """ - Return a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -1838,7 +1819,6 @@ cdef class PartitionStack: sage: P = PartitionStack(2, 6) sage: P ({0,1,2,3}) ({0,1,2,3,4,5}) - """ cdef int i, j, k s = '' @@ -1853,7 +1833,7 @@ cdef class PartitionStack: def _repr_at_k(self, k): """ - Gives a string representing the partition at level k: + Give a string representing the partition at level k. EXAMPLES:: @@ -1862,7 +1842,6 @@ cdef class PartitionStack: ({0,1,2,3}) ({0,1,2,3,4,5}) sage: P._repr_at_k(0) '({0,1,2,3}) ({0,1,2,3,4,5})\n' - """ s = '({' for j from 0 <= j < self.nwords: @@ -1884,7 +1863,7 @@ cdef class PartitionStack: def _is_discrete(self, k): """ - Returns whether the partition at level k is discrete. + Return whether the partition at level k is discrete. EXAMPLES:: @@ -1906,7 +1885,6 @@ cdef class PartitionStack: 0 sage: P._is_discrete(5) 1 - """ return self.is_discrete(k) @@ -1924,7 +1902,7 @@ cdef class PartitionStack: def _num_cells(self, k): """ - Returns the number of cells in the partition at level k. + Return the number of cells in the partition at level k. EXAMPLES:: @@ -1942,7 +1920,6 @@ cdef class PartitionStack: ({0,1,2,3}) ({0},{1},{2},{3},{4},{5}) sage: P._num_cells(3) 5 - """ return self.num_cells(k) @@ -1960,7 +1937,7 @@ cdef class PartitionStack: def _sat_225(self, k): """ - Returns whether the partition at level k satisfies the hypotheses of + Return whether the partition at level k satisfies the hypotheses of Lemma 2.25 in Brendan McKay's Practical Graph Isomorphism paper (see sage/graphs/graph_isom.pyx. @@ -1982,7 +1959,6 @@ cdef class PartitionStack: ({0,1,2,3}) ({0},{1},{2},{3,4,5}) ({0,1,2,3}) ({0},{1},{2},{3},{4,5}) ({0,1,2,3}) ({0},{1},{2},{3},{4},{5}) - """ return self.sat_225(k) @@ -2262,7 +2238,6 @@ cdef class PartitionStack: ({4,3,5},{6}) ({99},{99,99,99,99,99}) ({4,3},{5},{6}) ({99},{99,99},{99,99,99}) ({4},{3},{5},{6}) ({99},{99},{99},{99},{99,99}) - """ cdef int i for i from 0 <= i < len(col_ents): @@ -2296,7 +2271,6 @@ cdef class PartitionStack: ({0},{3},{2,1}) ({0},{5,4,3,2,1}) ({0},{3},{2},{1}) ({0},{5},{4},{3,2,1}) ({0},{3},{2},{1}) ({0},{5},{4},{3},{2},{1}) - """ self.col_percolate(start, end) @@ -2331,7 +2305,6 @@ cdef class PartitionStack: ({0},{3},{2,1}) ({0},{5,4,3,2,1}) ({0},{3},{2},{1}) ({0},{5},{4},{3,2,1}) ({0},{3},{2},{1}) ({0},{5},{4},{3},{2},{1}) - """ self.wd_percolate(start, end) @@ -2430,7 +2403,6 @@ cdef class PartitionStack: ({0,1,2,3}) ({0},{1},{2},{3,4,5}) ({0,1,2,3}) ({0},{1},{2},{3},{4,5}) ({0,1,2,3}) ({0},{1},{2},{3},{4},{5}) - """ return self.split_vertex(v, k) @@ -2471,7 +2443,7 @@ cdef class PartitionStack: def _col_degree(self, C, col, wd_ptr, k): """ - Returns the number of words in the cell specified by wd_ptr that have a + Return the number of words in the cell specified by wd_ptr that have a 1 in the col-th column. EXAMPLES:: @@ -2496,7 +2468,6 @@ cdef class PartitionStack: ({0,1,2,3}) ({0},{1},{2},{3},{4},{5}) sage: P._col_degree(B, 2, 0, 2) 2 - """ return self.col_degree(C, col, wd_ptr, k) @@ -2512,7 +2483,7 @@ cdef class PartitionStack: def _wd_degree(self, C, wd, col_ptr, k): """ - Returns the number of columns in the cell specified by col_ptr that are + Return the number of columns in the cell specified by col_ptr that are 1 in wd. EXAMPLES:: @@ -2537,7 +2508,6 @@ cdef class PartitionStack: ({0,1,2,3}) ({0},{1},{2},{3},{4},{5}) sage: P._wd_degree(B, 1, 1, 1) 3 - """ cdef int *ham_wts = hamming_weights() result = self.wd_degree(C, wd, col_ptr, k, ham_wts) @@ -2561,9 +2531,9 @@ cdef class PartitionStack: INPUT: - - start -- location of the beginning of the cell - - k -- at what level of refinement the partition of interest lies - - degrees -- the counts to sort by + - ``start`` -- location of the beginning of the cell + - ``k`` -- at what level of refinement the partition of interest lies + - ``degrees`` -- the counts to sort by EXAMPLES:: @@ -2577,7 +2547,6 @@ cdef class PartitionStack: sage: P ({0,1,2,3}) ({0,1,4,5,2,3}) ({0,1,2,3}) ({0},{1},{4,5},{2,3}) - """ cdef int i for i from 0 <= i < len(degrees): @@ -2633,9 +2602,9 @@ cdef class PartitionStack: INPUT: - - start -- location of the beginning of the cell - - k -- at what level of refinement the partition of interest lies - - degrees -- the counts to sort by + - ``start`` -- location of the beginning of the cell + - ``k`` -- at what level of refinement the partition of interest lies + - ``degrees`` -- the counts to sort by EXAMPLES:: @@ -2647,7 +2616,6 @@ cdef class PartitionStack: sage: P ({0,1,6,7,2,3,4,5}) ({0,1,2,3,4,5}) ({0,1},{6,7},{2,3,4,5}) ({0,1,2,3,4,5}) - """ cdef int i for i from 0 <= i < len(degrees): @@ -2742,7 +2710,6 @@ cdef class PartitionStack: ({0},{4},{6,2},{13,9},{11,15},{10,14},{12,8},{7,3},{1},{5}) ({0},{1},{2},{3,4,7,6,5}) ({0},{4},{6,2},{13,9},{11,15},{10,14},{12,8},{7,3},{1},{5}) ({0},{1},{2},{3},{4,7,6,5}) ({0},{4},{6},{2},{13},{9},{11},{15},{10},{14},{12},{8},{7},{3},{1},{5}) ({0},{1},{2},{3},{4},{7},{6},{5}) - """ cdef int i, alpha_length = len(alpha) cdef int *_alpha = sig_malloc( (self.nwords + self.ncols) * sizeof(int) ) @@ -2858,7 +2825,6 @@ cdef class PartitionStack: sage: P ({0,1,2,3}) ({0,1,2,3,4,5}) ({0,1,2,3}) ({0},{1,2,3,4,5}) - """ self.clear(k) @@ -2959,7 +2925,6 @@ cdef class PartitionStack: 8 0 11 - """ cdef int i, j if self.basis_locations: @@ -2993,7 +2958,6 @@ cdef class PartitionStack: 8 0 11 - """ cdef int i cdef int *ham_wts = hamming_weights() @@ -3060,7 +3024,6 @@ cdef class PartitionStack: 1 sage: P._get_permutation(Q) ([0, 1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 8, 9, 10, 11], [0, 1, 2, 3, 5, 4, 7, 6]) - """ cdef int i cdef int *word_g = sig_malloc( self.nwords * sizeof(int) ) @@ -3182,17 +3145,18 @@ cdef class BinaryCodeClassifier: INPUT: - ``CC`` -- a BinaryCode object - - ``verbosity`` -- a nonnegative integer + - ``verbosity`` -- nonnegative integer OUTPUT: - a tuple, (gens, labeling, size, base) - gens -- a list of permutations (in list form) representing generators - of the permutation automorphism group of the code CC. - labeling -- a permutation representing the canonical labeling of the - code. mostly for internal use; entries describe the relabeling - on the columns. - size -- the order of the automorphism group. - base -- a set of cols whose action determines the action on all cols + + a tuple, (gens, labeling, size, base) + - gens; list of permutations (in list form) representing generators + of the permutation automorphism group of the code CC + - labeling; a permutation representing the canonical labeling of the + code. mostly for internal use; entries describe the relabeling + on the columns. + - size; the order of the automorphism group + - base; a set of cols whose action determines the action on all cols EXAMPLES:: @@ -3329,7 +3293,6 @@ cdef class BinaryCodeClassifier: sage: BC = BinaryCodeClassifier() sage: BC._aut_gp_and_can_label(B)[2] 442368 - """ cdef int i, j cdef BinaryCode C = CC @@ -3943,7 +3906,6 @@ cdef class BinaryCodeClassifier: [000000000100010011011110] [000000000010001011110101] [000000000001001101101110] - """ aut_gp_gens, labeling, size, base = self._aut_gp_and_can_label(B) B._apply_permutation_to_basis(labeling) @@ -4003,7 +3965,6 @@ cdef class BinaryCodeClassifier: n=10 : 0 1 1 1 0 0 n=11 : 0 0 1 1 0 0 n=12 : 1 2 3 4 2 0 - """ cdef BinaryCode m cdef codeword *ortho_basis diff --git a/src/sage/coding/channel.py b/src/sage/coding/channel.py index f197bc607d2..0b584c3c117 100644 --- a/src/sage/coding/channel.py +++ b/src/sage/coding/channel.py @@ -62,7 +62,7 @@ def random_error_vector(n, F, error_positions): r""" - Return a vector of length ``n`` over ``F`` filled with random non-zero coefficients + Return a vector of length ``n`` over ``F`` filled with random nonzero coefficients at the positions given by ``error_positions``. .. NOTE:: @@ -75,11 +75,9 @@ def random_error_vector(n, F, error_positions): - ``F`` -- the field over which the vector is defined - - ``error_positions`` -- the non-zero positions of the vector + - ``error_positions`` -- the nonzero positions of the vector - OUTPUT: - - - a vector of ``F`` + OUTPUT: a vector of ``F`` AUTHORS: @@ -109,11 +107,9 @@ def format_interval(t): INPUT: - - ``t`` -- a list or a tuple - - OUTPUT: + - ``t`` -- list or a tuple - - a string + OUTPUT: string TESTS:: @@ -125,7 +121,6 @@ def format_interval(t): sage: t = (2, 10) sage: format_interval(t) 'between 2 and 10' - """ return str(t[0]) if t[0] == t[1] else 'between %s and %s' % (t[0], t[1]) @@ -155,7 +150,7 @@ class Channel(SageObject): def __init__(self, input_space, output_space): r""" - Initializes parameters for a Channel object. + Initialize parameters for a Channel object. This is a private method, which should be called by the constructor of every encoder, as it automatically initializes the mandatory @@ -204,9 +199,7 @@ def transmit(self, message): - ``message`` -- a vector - OUTPUT: - - - a vector of the output space of ``self`` + OUTPUT: a vector of the output space of ``self`` EXAMPLES:: @@ -255,7 +248,6 @@ def input_space(self): sage: Chan = channels.StaticErrorRateChannel(GF(59)^6, n_err) sage: Chan.input_space() Vector space of dimension 6 over Finite Field of size 59 - """ return self._input_space @@ -395,9 +387,7 @@ def transmit_unsafe(self, message): - ``message`` -- a vector - OUTPUT: - - - a vector of the output space + OUTPUT: a vector of the output space EXAMPLES:: @@ -490,8 +480,6 @@ class ErrorErasureChannel(Channel): def __init__(self, space, number_errors, number_erasures): r""" - - TESTS: If the sum of number of errors and number of erasures @@ -579,9 +567,7 @@ def transmit_unsafe(self, message): - ``message`` -- a vector - OUTPUT: - - - a couple of vectors, namely: + OUTPUT: a couple of vectors, namely: - the transmitted message, which is ``message`` with erroneous and erased positions @@ -666,10 +652,10 @@ class QarySymmetricChannel(Channel): INPUT: - - ``space`` -- the input and output space of the channel. It has to be - `\GF{q}^n` for some finite field `\GF{q}`. + - ``space`` -- the input and output space of the channel; it has to be + `\GF{q}^n` for some finite field `\GF{q}` - - ``epsilon`` -- the transmission error probability of the individual elements. + - ``epsilon`` -- the transmission error probability of the individual elements EXAMPLES: @@ -798,7 +784,7 @@ def probability_of_exactly_t_errors(self, t): INPUT: - - ``t`` -- an integer + - ``t`` -- integer EXAMPLES:: @@ -818,7 +804,7 @@ def probability_of_at_most_t_errors(self, t): INPUT: - - ``t`` -- an integer + - ``t`` -- integer EXAMPLES:: diff --git a/src/sage/coding/code_bounds.py b/src/sage/coding/code_bounds.py index fd4e36561ef..a4771995a47 100644 --- a/src/sage/coding/code_bounds.py +++ b/src/sage/coding/code_bounds.py @@ -50,7 +50,7 @@ where `0` is a distinguished element of `F`; in particular it is `0` of the field if `F` is a field. The minimum distance of -a linear code is the smallest non-zero weight of a codeword in `C`. The +a linear code is the smallest nonzero weight of a codeword in `C`. The relatively minimum distance is denoted @@ -108,47 +108,42 @@ This module implements: -- ``codesize_upper_bound(n,d,q)``, for the best known (as of May, - 2006) upper bound `A(n,d)` for the size of a code of length `n`, - minimum distance `d` over a field of size `q`. +- ``codesize_upper_bound(n,d,q)``, for the best known (as of May, 2006) upper + bound `A(n,d)` for the size of a code of length `n`, minimum distance `d` + over a field of size `q`. -- ``dimension_upper_bound(n,d,q)``, an upper bound - `B(n,d)=B_q(n,d)` for the dimension of a linear code of - length `n`, minimum distance `d` over a field of size `q`. +- ``dimension_upper_bound(n,d,q)``, an upper bound `B(n,d)=B_q(n,d)` for the + dimension of a linear code of length `n`, minimum distance `d` over a field + of size `q`. -- ``gilbert_lower_bound(n,q,d)``, a lower bound for number of - elements in the largest code of min distance `d` in - `\GF{q}^n`. +- ``gilbert_lower_bound(n,q,d)``, a lower bound for number of elements in the + largest code of min distance `d` in `\GF{q}^n`. -- ``gv_info_rate(n,delta,q)``, `log_q(GLB)/n`, where GLB is - the Gilbert lower bound and `\delta = d/n`. +- ``gv_info_rate(n,delta,q)``, `log_q(GLB)/n`, where GLB is the Gilbert lower + bound and `\delta = d/n`. -- ``gv_bound_asymp(delta,q)``, asymptotic analog of Gilbert lower - bound. +- ``gv_bound_asymp(delta,q)``, asymptotic analog of Gilbert lower bound. -- ``plotkin_upper_bound(n,q,d)`` +- ``plotkin_upper_bound(n,q,d)`` -- ``plotkin_bound_asymp(delta,q)``, asymptotic analog of Plotkin - bound. +- ``plotkin_bound_asymp(delta,q)``, asymptotic analog of Plotkin bound. -- ``griesmer_upper_bound(n,q,d)`` +- ``griesmer_upper_bound(n,q,d)`` -- ``elias_upper_bound(n,q,d)`` +- ``elias_upper_bound(n,q,d)`` -- ``elias_bound_asymp(delta,q)``, asymptotic analog of Elias bound. +- ``elias_bound_asymp(delta,q)``, asymptotic analog of Elias bound. -- ``hamming_upper_bound(n,q,d)`` +- ``hamming_upper_bound(n,q,d)`` -- ``hamming_bound_asymp(delta,q)``, asymptotic analog of Hamming - bound. +- ``hamming_bound_asymp(delta,q)``, asymptotic analog of Hamming bound. -- ``singleton_upper_bound(n,q,d)`` +- ``singleton_upper_bound(n,q,d)`` -- ``singleton_bound_asymp(delta,q)``, asymptotic analog of Singleton - bound. +- ``singleton_bound_asymp(delta,q)``, asymptotic analog of Singleton bound. -- ``mrrw1_bound_asymp(delta,q)``, "first" asymptotic - McEliese-Rumsey-Rodemich-Welsh bound for the information rate. +- ``mrrw1_bound_asymp(delta,q)``, "first" asymptotic + McEliese-Rumsey-Rodemich-Welsh bound for the information rate. - Delsarte (a.k.a. Linear Programming (LP)) upper bounds. @@ -195,7 +190,7 @@ def _check_n_q_d(n, q, d, field_based=True): More precisely, this checks that the parameters are positive integers, that `q` is a prime power for codes over a field, or, more generally, that `q` is of size at least 2, and that `n >= d`. - This raises a :class:`ValueError` otherwise. + This raises a :exc:`ValueError` otherwise. TESTS:: @@ -254,15 +249,15 @@ def codesize_upper_bound(n, d, q, algorithm=None): sage: codes.bounds.codesize_upper_bound(10, 3, 2) 93 - sage: codes.bounds.codesize_upper_bound(24, 8, 2, algorithm="LP") # needs sage.numerical.mip + sage: codes.bounds.codesize_upper_bound(24, 8, 2, algorithm='LP') # needs sage.numerical.mip 4096 - sage: codes.bounds.codesize_upper_bound(10, 3, 2, algorithm="gap") # optional - gap_package_guava + sage: codes.bounds.codesize_upper_bound(10, 3, 2, algorithm='gap') # optional - gap_package_guava 85 sage: codes.bounds.codesize_upper_bound(11, 3, 4, algorithm=None) # needs sage.symbolic 123361 - sage: codes.bounds.codesize_upper_bound(11, 3, 4, algorithm="gap") # optional - gap_package_guava + sage: codes.bounds.codesize_upper_bound(11, 3, 4, algorithm='gap') # optional - gap_package_guava 123361 - sage: codes.bounds.codesize_upper_bound(11, 3, 4, algorithm="LP") # needs sage.numerical.mip + sage: codes.bounds.codesize_upper_bound(11, 3, 4, algorithm='LP') # needs sage.numerical.mip 109226 TESTS: @@ -271,7 +266,7 @@ def codesize_upper_bound(n, d, q, algorithm=None): sage: codes.bounds.codesize_upper_bound(19, 10, 2) 20 - sage: codes.bounds.codesize_upper_bound(19, 10, 2, algorithm="gap") # optional - gap_package_guava + sage: codes.bounds.codesize_upper_bound(19, 10, 2, algorithm='gap') # optional - gap_package_guava 20 Meaningless parameters are rejected:: @@ -283,7 +278,7 @@ def codesize_upper_bound(n, d, q, algorithm=None): """ _check_n_q_d(n, q, d, field_based=False) if algorithm == "gap": - GapPackage("guava", spkg="gap_packages").require() + GapPackage("guava", spkg='gap_packages').require() libgap.load_package('guava') return int(libgap.UpperBound(n, d, q)) if algorithm == "LP": @@ -313,7 +308,7 @@ def dimension_upper_bound(n, d, q, algorithm=None): 6 sage: codes.bounds.dimension_upper_bound(30,15,4) # needs sage.libs.pari sage.symbolic 13 - sage: codes.bounds.dimension_upper_bound(30,15,4,algorithm="LP") # needs sage.libs.pari sage.numerical.mip + sage: codes.bounds.dimension_upper_bound(30,15,4,algorithm='LP') # needs sage.libs.pari sage.numerical.mip 12 TESTS: @@ -380,12 +375,12 @@ def plotkin_upper_bound(n,q,d, algorithm=None): sage: codes.bounds.plotkin_upper_bound(10,2,3) 192 - sage: codes.bounds.plotkin_upper_bound(10,2,3,algorithm="gap") # optional - gap_package_guava + sage: codes.bounds.plotkin_upper_bound(10,2,3,algorithm='gap') # optional - gap_package_guava 192 """ _check_n_q_d(n, q, d, field_based=False) if algorithm == "gap": - GapPackage("guava", spkg="gap_packages").require() + GapPackage("guava", spkg='gap_packages').require() libgap.load_package("guava") return QQ(libgap.UpperBoundPlotkin(n, d, q)) else: @@ -417,7 +412,6 @@ def griesmer_upper_bound(n,q,d,algorithm=None): `n\geq \sum_{i=0}^{k-1} \lceil d/q^i \rceil.` - EXAMPLES: The bound is reached for the ternary Golay codes:: @@ -431,7 +425,7 @@ def griesmer_upper_bound(n,q,d,algorithm=None): sage: codes.bounds.griesmer_upper_bound(10,2,3) # needs sage.libs.pari 128 - sage: codes.bounds.griesmer_upper_bound(10,2,3,algorithm="gap") # optional - gap_package_guava, needs sage.libs.pari + sage: codes.bounds.griesmer_upper_bound(10,2,3,algorithm='gap') # optional - gap_package_guava, needs sage.libs.pari 128 TESTS:: @@ -443,7 +437,7 @@ def griesmer_upper_bound(n,q,d,algorithm=None): """ _check_n_q_d(n, q, d) if algorithm == "gap": - GapPackage("guava", spkg="gap_packages").require() + GapPackage("guava", spkg='gap_packages').require() libgap.load_package("guava") return QQ(libgap.UpperBoundGriesmer(n, d, q)) else: @@ -472,13 +466,13 @@ def elias_upper_bound(n,q,d,algorithm=None): sage: codes.bounds.elias_upper_bound(10,2,3) 232 - sage: codes.bounds.elias_upper_bound(10,2,3,algorithm="gap") # optional - gap_package_guava + sage: codes.bounds.elias_upper_bound(10,2,3,algorithm='gap') # optional - gap_package_guava 232 """ _check_n_q_d(n, q, d, field_based=False) r = 1-1/q if algorithm == "gap": - GapPackage("guava", spkg="gap_packages").require() + GapPackage("guava", spkg='gap_packages').require() libgap.load_package("guava") return QQ(libgap.UpperBoundElias(n, d, q)) else: @@ -577,10 +571,10 @@ def entropy(x, q=2): INPUT: - - ``x`` -- real number in the interval `[0, 1]`. + - ``x`` -- real number in the interval `[0, 1]` - - ``q`` -- (default: 2) integer greater than 1. This is the base of the - logarithm. + - ``q`` -- (default: 2) integer greater than 1; this is the base of the + logarithm EXAMPLES:: @@ -622,10 +616,10 @@ def entropy_inverse(x, q=2): INPUT: - - ``x`` -- real number in the interval `[0, 1]`. + - ``x`` -- real number in the interval `[0, 1]` - - ``q`` -- (default: 2) integer greater than 1. This is the base of the - logarithm. + - ``q`` -- (default: 2) integer greater than 1; this is the base of the + logarithm OUTPUT: diff --git a/src/sage/coding/code_constructions.py b/src/sage/coding/code_constructions.py index a3569938e40..5767872b3e2 100644 --- a/src/sage/coding/code_constructions.py +++ b/src/sage/coding/code_constructions.py @@ -180,7 +180,9 @@ def _is_a_splitting(S1, S2, n, return_automorphism=False): def _lift2smallest_field(a): """ - INPUT: a is an element of a finite field GF(q) + INPUT: + + - ``a`` -- an element of a finite field GF(q) OUTPUT: the element b of the smallest subfield F of GF(q) for which F(b)=a. @@ -216,7 +218,7 @@ def _lift2smallest_field(a): def permutation_action(g, v): r""" - Returns permutation of rows `g * v`. + Return permutation of rows `g * v`. Works on lists, matrices, sequences and vectors (by permuting coordinates). The code requires @@ -327,7 +329,7 @@ def walsh_matrix(m0): def DuadicCodeEvenPair(F,S1,S2): r""" - Constructs the "even pair" of duadic codes associated to the + Construct the "even pair" of duadic codes associated to the "splitting" (see the docstring for ``_is_a_splitting`` for the definition) S1, S2 of n. @@ -376,7 +378,7 @@ def DuadicCodeEvenPair(F,S1,S2): def DuadicCodeOddPair(F,S1,S2): """ - Constructs the "odd pair" of duadic codes associated to the + Construct the "odd pair" of duadic codes associated to the "splitting" S1, S2 of n. .. warning:: @@ -438,14 +440,12 @@ def ExtendedQuadraticResidueCode(n,F): INPUT: + - ``n`` -- an odd prime - - ``n`` -- an odd prime - - - ``F`` -- a finite prime field whose order must be a - quadratic residue modulo `n`. - + - ``F`` -- a finite prime field whose order must be a + quadratic residue modulo `n` - OUTPUT: Returns an extended quadratic residue code. + OUTPUT: an extended quadratic residue code EXAMPLES:: @@ -499,7 +499,7 @@ def QuadraticResidueCode(n,F): A quadratic residue code (or QR code) is a cyclic code whose generator polynomial is the product of the polynomials `x-\alpha^i` (`\alpha` is a primitive - `n`'th root of unity; `i` ranges over the set of + `n`-th root of unity; `i` ranges over the set of quadratic residues modulo `n`). See :class:`QuadraticResidueCodeEvenPair` and @@ -507,14 +507,12 @@ def QuadraticResidueCode(n,F): INPUT: + - ``n`` -- an odd prime - - ``n`` -- an odd prime + - ``F`` -- a finite prime field whose order must be a + quadratic residue modulo `n` - - ``F`` -- a finite prime field whose order must be a - quadratic residue modulo `n`. - - - OUTPUT: Returns a quadratic residue code. + OUTPUT: a quadratic residue code EXAMPLES:: @@ -548,7 +546,7 @@ def QuadraticResidueCodeEvenPair(n,F): quadratic residue mod `n`. They are constructed as "even-like" duadic codes associated the - splitting `(Q,N)` mod `n`, where `Q` is the set of non-zero quadratic + splitting `(Q,N)` mod `n`, where `Q` is the set of nonzero quadratic residues and `N` is the non-residues. EXAMPLES:: @@ -598,8 +596,8 @@ def QuadraticResidueCodeEvenPair(n,F): if n <= 2 or not n.is_prime(): raise ValueError("the argument n must be an odd prime") Q = quadratic_residues(n) - Q.remove(0) # non-zero quad residues - N = [x for x in srange(1, n) if x not in Q] # non-zero quad non-residues + Q.remove(0) # nonzero quad residues + N = [x for x in srange(1, n) if x not in Q] # nonzero quad non-residues if q not in Q: raise ValueError("the order of the finite field must be a quadratic residue modulo n") return DuadicCodeEvenPair(F,Q,N) @@ -614,7 +612,7 @@ def QuadraticResidueCodeOddPair(n,F): quadratic residue mod `n`. They are constructed as "odd-like" duadic codes associated the - splitting `(Q,N)` mod `n`, where `Q` is the set of non-zero quadratic + splitting `(Q,N)` mod `n`, where `Q` is the set of nonzero quadratic residues and `N` is the non-residues. EXAMPLES:: @@ -658,8 +656,8 @@ def QuadraticResidueCodeOddPair(n,F): if n <= 2 or not n.is_prime(): raise ValueError("the argument n must be an odd prime") Q = quadratic_residues(n) - Q.remove(0) # non-zero quad residues - N = [x for x in srange(1, n) if x not in Q] # non-zero quad non-residues + Q.remove(0) # nonzero quad residues + N = [x for x in srange(1, n) if x not in Q] # nonzero quad non-residues if q not in Q: raise ValueError("the order of the finite field must be a quadratic residue modulo n") return DuadicCodeOddPair(F,Q,N) @@ -714,15 +712,12 @@ def ToricCode(P,F): INPUT: + - ``P`` -- all the integer lattice points in a polytope + defining the toric variety - - ``P`` -- all the integer lattice points in a polytope - defining the toric variety. - - - ``F`` -- a finite field. - + - ``F`` -- a finite field - OUTPUT: Returns toric code with length n = , dimension k over field - F. + OUTPUT: toric code with length `n`, dimension `k` over field `F` EXAMPLES:: @@ -731,7 +726,7 @@ def ToricCode(P,F): [36, 5] linear code over GF(7) sage: C.minimum_distance() # needs sage.groups 24 - sage: C.minimum_distance(algorithm="guava") # optional - gap_package_guava + sage: C.minimum_distance(algorithm='guava') # optional - gap_package_guava ...24 sage: C = codes.ToricCode([[-2,-2],[-1,-2],[-1,-1],[-1,0], ....: [0,-1],[0,0],[0,1],[1,-1],[1,0]], GF(5)) @@ -739,7 +734,7 @@ def ToricCode(P,F): [16, 9] linear code over GF(5) sage: C.minimum_distance() # needs sage.groups 6 - sage: C.minimum_distance(algorithm="guava") # optional - gap_package_guava + sage: C.minimum_distance(algorithm='guava') # optional - gap_package_guava 6 sage: C = codes.ToricCode([[0,0],[1,1],[1,2],[1,3],[1,4],[2,1], ....: [2,2],[2,3],[3,1],[3,2],[4,1]], GF(8,"a")) diff --git a/src/sage/coding/codecan/autgroup_can_label.pyx b/src/sage/coding/codecan/autgroup_can_label.pyx index 7f7f8504b49..e54e64a20a9 100644 --- a/src/sage/coding/codecan/autgroup_can_label.pyx +++ b/src/sage/coding/codecan/autgroup_can_label.pyx @@ -81,13 +81,13 @@ columns do share the same coloring:: We can also restrict the group action to linear isometries:: - sage: P = LinearCodeAutGroupCanLabel(C, algorithm_type="linear") + sage: P = LinearCodeAutGroupCanLabel(C, algorithm_type='linear') sage: P.get_autom_order() == GL(3, GF(4, 'a')).order() True and to the action of the symmetric group only:: - sage: P = LinearCodeAutGroupCanLabel(C, algorithm_type="permutational") + sage: P = LinearCodeAutGroupCanLabel(C, algorithm_type='permutational') sage: P.get_autom_order() == C.permutation_automorphism_group().order() True """ @@ -184,18 +184,18 @@ class LinearCodeAutGroupCanLabel: True """ - def __init__(self, C, P=None, algorithm_type="semilinear"): + def __init__(self, C, P=None, algorithm_type='semilinear'): """ - see :class:`LinearCodeAutGroupCanLabel` + See :class:`LinearCodeAutGroupCanLabel`. INPUT: - ``C`` -- a linear code - - ``P`` (optional) -- a coloring of the coordinates i.e. a partition + - ``P`` -- (optional) a coloring of the coordinates i.e. a partition (list of disjoint lists) of [0 , ..., C.length()-1 ] - - ``algorithm_type`` (optional) -- which defines the acting group, either + - ``algorithm_type`` -- (optional) defines the acting group, either * ``permutational`` @@ -213,7 +213,7 @@ class LinearCodeAutGroupCanLabel: [0 1 0 1 0 1 1] [0 0 1 1 1 1 0] sage: P2 = LinearCodeAutGroupCanLabel(C, P=[[0,3,5],[1,2,4,6]], - ....: algorithm_type="permutational") + ....: algorithm_type='permutational') sage: P2.get_canonical_form().generator_matrix() [1 1 1 0 0 0 1] [0 1 0 1 1 0 1] @@ -294,7 +294,7 @@ class LinearCodeAutGroupCanLabel: # this command allows you some advanced debugging # it prints the backtrack tree -> must be activated when installing - # pr._latex_view(title="MyTitle") #this will provide you some visual representation of what is going on + # pr._latex_view(title='MyTitle') #this will provide you some visual representation of what is going on can_transp = pr.get_transporter() can_col_set = pr.get_canonical_form().columns() @@ -405,19 +405,19 @@ class LinearCodeAutGroupCanLabel: - ``normalization_inverse`` -- the inverse of ``normalization`` - - ``col2pos`` -- a list of disjoint indices in ``range(n)`` + - ``col2pos`` -- list of disjoint indices in ``range(n)`` - ``col2P`` -- an increasing list of integers, with ``len(col2P) == len(col2pos)`` with ``col2P[i] == col2P[j]`` if and only if the indices ``col2pos[i]`` and ``col2pos[j]`` are in the same partition - - ``zero_column_case`` (boolean) -- set to ``True`` iff we are dealing + - ``zero_column_case`` -- boolean; set to ``True`` iff we are dealing with the zero column OUTPUT: - - a list of generators in `S` + - list of generators in `S` - the order of this group @@ -478,7 +478,7 @@ class LinearCodeAutGroupCanLabel: INPUT: - - ``gens`` -- a list of semimonomial transformation group elements of length `m` + - ``gens`` -- list of semimonomial transformation group elements of length `m` - ``normalization`` -- a semimonomial transformation of length `n` diff --git a/src/sage/coding/codecan/codecan.pyx b/src/sage/coding/codecan/codecan.pyx index af8d82e660a..c66a93a0f7d 100644 --- a/src/sage/coding/codecan/codecan.pyx +++ b/src/sage/coding/codecan/codecan.pyx @@ -111,10 +111,10 @@ cdef class InnerGroup: Those stabilizers can be stored as triples: - - ``rank`` -- an integer in `\{0, \ldots, k\}` + - ``rank`` -- integer in `\{0, \ldots, k\}` - ``row_partition`` -- a partition of `\{0, \ldots, k-1\}` with - discrete cells for all integers `i` `\geq` ``rank``. - - ``frob_pow`` -- an integer `s` in `\{0, \ldots, r-1\}` if `q = p^r` + discrete cells for all integers `i` `\geq` ``rank`` + - ``frob_pow`` -- integer `s` in `\{0, \ldots, r-1\}` if `q = p^r` The group `G_{\Pi^{(I)}(x)}` contains all elements `(A, \varphi, \alpha) \in G`, where @@ -132,13 +132,13 @@ cdef class InnerGroup: See [Feu2009]_ for more details. """ - def __cinit__(self, k=0, algorithm="semilinear", **kwds): + def __cinit__(self, k=0, algorithm='semilinear', **kwds): r""" - See :class:`sage.coding.codecan.codecan.InnerGroup` + See :class:`sage.coding.codecan.codecan.InnerGroup`. INPUT: - - ``k`` -- an integer, gives the dimension of the matrix component + - ``k`` -- integer; gives the dimension of the matrix component - ``algorithm`` -- either * "semilinear" -- full group @@ -146,7 +146,7 @@ cdef class InnerGroup: * "permutational -- no field automorphisms and no column multiplications i.e. `G = GL(k,q)` - - ``transporter`` (optional) -- set to an element of the group + - ``transporter`` -- (optional) set to an element of the group :class:`sage.groups.semimonomial_transformations.semimonomial_transformation_group.SemimonomialTransformationGroup` if you would like to modify this element simultaneously @@ -186,7 +186,7 @@ cdef class InnerGroup: def __dealloc__(self): r""" - Deallocates ``self``. + Deallocate ``self``. """ OP_dealloc(self.row_partition) @@ -198,7 +198,7 @@ cdef class InnerGroup: cdef bint has_semilinear_action(self) noexcept: """ - Returns ``True`` iff the field automorphism group component of ``self`` + Return ``True`` iff the field automorphism group component of ``self`` is non-trivial. """ return (self.frob_pow > 0) @@ -505,7 +505,7 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic): self._nr_of_point_refine_calls = 0 self._stored_states = dict() - def __init__(self, n, generator_matrix, P=None, algorithm_type="semilinear"): + def __init__(self, n, generator_matrix, P=None, algorithm_type='semilinear'): r""" Initialization, we immediately start the algorithm (see :mod:`sage.coding.codecan.codecan`) @@ -514,13 +514,13 @@ cdef class PartitionRefinementLinearCode(PartitionRefinement_generic): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``generator_matrix`` -- a `k \times n` matrix over `\GF{q}` of full row rank, - i.e. `k last modified: 2002-03-20 - This function raises an :class:`IOError` if an error occurs downloading data or - parsing it. It raises a :class:`ValueError` if the ``q`` input is invalid. + This function raises an :exc:`IOError` if an error occurs downloading data or + parsing it. It raises a :exc:`ValueError` if the ``q`` input is invalid. AUTHORS: @@ -188,29 +182,29 @@ def best_linear_code_in_codetables_dot_de(n, k, F, verbose=False): def self_orthogonal_binary_codes(n, k, b=2, parent=None, BC=None, equal=False, in_test=None): """ - Returns a Python iterator which generates a complete set of + Return a Python iterator which generates a complete set of representatives of all permutation equivalence classes of self-orthogonal binary linear codes of length in ``[1..n]`` and dimension in ``[1..k]``. INPUT: - - ``n`` -- Integer, maximal length + - ``n`` -- integer; maximal length - - ``k`` -- Integer, maximal dimension + - ``k`` -- integer; maximal dimension - - ``b`` -- Integer, requires that the generators all have weight divisible - by ``b`` (if ``b=2``, all self-orthogonal codes are generated, and if - ``b=4``, all doubly even codes are generated). Must be an even positive - integer. + - ``b`` -- integer; requires that the generators all have weight divisible + by ``b`` (if ``b=2``, all self-orthogonal codes are generated, and if + ``b=4``, all doubly even codes are generated). Must be an even positive + integer. - - ``parent`` -- Used in recursion (default: ``None``) + - ``parent`` -- used in recursion (default: ``None``) - - ``BC`` -- Used in recursion (default: ``None``) + - ``BC`` -- used in recursion (default: ``None``) - - ``equal`` -- If ``True``, generates only [n, k] codes (default: ``False``) + - ``equal`` -- if ``True``, generates only [n, k] codes (default: ``False``) - - ``in_test`` -- Used in recursion (default: ``None``) + - ``in_test`` -- used in recursion (default: ``None``) EXAMPLES: diff --git a/src/sage/coding/decoder.py b/src/sage/coding/decoder.py index a7a2a8629ed..d5b112b821d 100644 --- a/src/sage/coding/decoder.py +++ b/src/sage/coding/decoder.py @@ -52,7 +52,7 @@ class Decoder(SageObject): @classmethod def decoder_type(cls): r""" - Returns the set of types of ``self``. + Return the set of types of ``self``. This method can be called on both an uninstantiated decoder class, or on an instance of a decoder class. @@ -98,7 +98,6 @@ def decoder_type(cls): works for specific channels. ====================== ================================================ - EXAMPLES: We call it on a class:: @@ -134,7 +133,7 @@ def _instance_decoder_type(self): def __init__(self, code, input_space, connected_encoder_name): r""" - Initializes mandatory parameters for :class:`Decoder` objects. + Initialize mandatory parameters for :class:`Decoder` objects. This method only exists for inheritance purposes as it initializes parameters that need to be known by every decoder. An abstract @@ -183,7 +182,7 @@ def __init__(self, code, input_space, connected_encoder_name): def __hash__(self): r""" - Returns the hash value of ``self``. + Return the hash value of ``self``. This is a generic implementation which should be overwritten on decoders with extra arguments. @@ -202,9 +201,10 @@ def __hash__(self): def __ne__(self, other): r""" - Tests inequality of ``self`` and ``other``. + Test inequality of ``self`` and ``other``. - This is a generic implementation, which returns the inverse of ``__eq__`` for self. + This is a generic implementation, which returns the inverse of + ``__eq__`` for ``self``. EXAMPLES:: @@ -229,11 +229,9 @@ def decode_to_code(self, r): INPUT: - - ``r`` -- a element of the input space of ``self``. - - OUTPUT: + - ``r`` -- a element of the input space of ``self`` - - a vector of :meth:`code`. + OUTPUT: a vector of :meth:`code` EXAMPLES:: @@ -281,11 +279,9 @@ def decode_to_message(self, r): INPUT: - - ``r`` -- a element of the input space of ``self``. - - OUTPUT: + - ``r`` -- a element of the input space of ``self`` - - a vector of :meth:`message_space`. + OUTPUT: a vector of :meth:`message_space` EXAMPLES:: diff --git a/src/sage/coding/delsarte_bounds.py b/src/sage/coding/delsarte_bounds.py index 2b64738b76f..a7cc35e058d 100644 --- a/src/sage/coding/delsarte_bounds.py +++ b/src/sage/coding/delsarte_bounds.py @@ -50,7 +50,7 @@ def krawtchouk(n, q, l, x, check=True): - ``n``, ``q``, ``x`` -- arbitrary numbers - - ``l`` -- a nonnegative integer + - ``l`` -- nonnegative integer - ``check`` -- check the input for correctness. ``True`` by default. Otherwise, pass it as it is. Use ``check=False`` at @@ -135,7 +135,7 @@ def eberlein(n, w, k, u, check=True): - ``w``, ``k``, ``x`` -- arbitrary numbers - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``check`` -- check the input for correctness. ``True`` by default. Otherwise, pass it as it is. Use ``check=False`` at @@ -233,7 +233,7 @@ def _delsarte_LP_building(n, d, d_star, q, isinteger, solver, maxc=0): def _delsarte_cwc_LP_building(n, d, w, solver, isinteger): r""" - LP builder for Delsarte's LP for constant weight codes + LP builder for Delsarte's LP for constant weight codes. It is used in :func:`delsarte_bound_constant_weight_code`; not exported. @@ -290,7 +290,7 @@ def _q(k, i): def delsarte_bound_constant_weight_code(n, d, w, return_data=False, - solver="PPL", isinteger=False): + solver='PPL', isinteger=False): r""" Find the Delsarte bound on a constant weight code. @@ -362,9 +362,9 @@ def delsarte_bound_constant_weight_code(n, d, w, return_data=False, def delsarte_bound_hamming_space(n, d, q, return_data=False, - solver="PPL", isinteger=False): + solver='PPL', isinteger=False): r""" - Find the Delsarte bound on codes in ``H_q^n`` of minimal distance ``d`` + Find the Delsarte bound on codes in ``H_q^n`` of minimal distance ``d``. Find the Delsarte bound [De1973]_ on the size of codes in the Hamming space ``H_q^n`` of minimal distance ``d``. @@ -446,14 +446,14 @@ def delsarte_bound_hamming_space(n, d, q, return_data=False, def delsarte_bound_additive_hamming_space(n, d, q, d_star=1, q_base=0, return_data=False, - solver="PPL", isinteger=False): + solver='PPL', isinteger=False): r""" Find a modified Delsarte bound on additive codes in Hamming space `H_q^n` of minimal distance `d`. Find the Delsarte LP bound on ``F_{q_base}``-dimension of additive codes in Hamming space `H_q^n` of minimal distance ``d`` with minimal distance of the dual code at least ``d_star``. If - ``q_base`` is set to non-zero, then ``q`` is a power of + ``q_base`` is set to nonzero, then ``q`` is a power of ``q_base``, and the code is, formally, linear over ``F_{q_base}``. Otherwise it is assumed that ``q_base==q``. @@ -466,10 +466,10 @@ def delsarte_bound_additive_hamming_space(n, d, q, d_star=1, q_base=0, return_da - ``q`` -- the size of the alphabet - ``d_star`` -- the (lower bound on) minimal distance of the dual code; - only makes sense for additive codes. + only makes sense for additive codes - ``q_base`` -- if ``0``, the code is assumed to be linear. Otherwise, - ``q=q_base^m`` and the code is linear over ``F_{q_base}``. + ``q=q_base^m`` and the code is linear over ``F_{q_base}`` - ``return_data`` -- if ``True``, return a triple ``(W,LP,bound)``, where ``W`` is a weights vector, and ``LP`` the Delsarte bound @@ -483,7 +483,7 @@ def delsarte_bound_additive_hamming_space(n, d, q, d_star=1, q_base=0, return_da list), you are on your own! - ``isinteger`` -- if ``True``, uses an integer programming solver (ILP), - rather that an LP solver. Can be very slow if set to ``True``. + rather that an LP solver (can be very slow if set to ``True``) EXAMPLES: @@ -640,7 +640,7 @@ def _delsarte_Q_LP_building(q, d, solver, isinteger): def delsarte_bound_Q_matrix(q, d, return_data=False, - solver="PPL", isinteger=False): + solver='PPL', isinteger=False): r""" Delsarte bound on a code with Q matrix ``q`` and lower bound on min. dist. ``d``. diff --git a/src/sage/coding/encoder.py b/src/sage/coding/encoder.py index 8b992ee9662..6ad764935c7 100644 --- a/src/sage/coding/encoder.py +++ b/src/sage/coding/encoder.py @@ -61,7 +61,7 @@ class Encoder(SageObject): def __init__(self, code): r""" - Initializes mandatory parameters for an :class:`Encoder` object. + Initialize mandatory parameters for an :class:`Encoder` object. This method only exists for inheritance purposes as it initializes parameters that need to be known by every linear code. An abstract @@ -95,9 +95,10 @@ def __init__(self, code): def __ne__(self, other): r""" - Tests inequality of ``self`` and ``other``. + Test inequality of ``self`` and ``other``. - This is a generic implementation, which returns the inverse of ``__eq__`` for self. + This is a generic implementation, which returns the inverse of + ``__eq__`` for ``self``. EXAMPLES:: @@ -115,7 +116,7 @@ def __ne__(self, other): def encode(self, word): r""" - Transforms an element of the message space into a codeword. + Transform an element of the message space into a codeword. This is a default implementation which assumes that the message space of the encoder is `F^{k}`, where `F` is @@ -126,7 +127,7 @@ def encode(self, word): .. NOTE:: :meth:`encode` might be a partial function over ``self``'s :meth:`message_space`. - One should use the exception :class:`EncodingError` to catch attempts + One should use the exception :exc:`EncodingError` to catch attempts to encode words that are outside of the message space. One can use the following shortcut to encode a word with an encoder ``E``:: @@ -135,11 +136,9 @@ def encode(self, word): INPUT: - - ``word`` -- a vector of the message space of the ``self``. + - ``word`` -- a vector of the message space of the ``self`` - OUTPUT: - - - a vector of :meth:`code`. + OUTPUT: a vector of :meth:`code` EXAMPLES:: @@ -167,14 +166,14 @@ def encode(self, word): def __call__(self, m): r""" - Transforms an element of the message space into a codeword. + Transform an element of the message space into a codeword. This behaves the same as `self.encode`. See `sage.coding.encoder.Encoder.encode` for details. INPUT: - - ``word`` -- a vector of the message space of the ``self``. + - ``word`` -- a vector of the message space of the ``self`` EXAMPLES:: @@ -204,16 +203,15 @@ def unencode(self, c, nocheck=False): INPUT: - - ``c`` -- a codeword of :meth:`code`. - - - ``nocheck`` -- (default: ``False``) checks if ``c`` is in :meth:`code`. You might set - this to ``True`` to disable the check for saving computation. Note that if ``c`` is - not in :meth:`self` and ``nocheck = True``, then the output of :meth:`unencode` is - not defined (except that it will be in the message space of ``self``). + - ``c`` -- a codeword of :meth:`code` - OUTPUT: + - ``nocheck`` -- boolean (default: ``False``); checks if ``c`` is in + :meth:`code`. You might set this to ``True`` to disable the check for + saving computation. Note that if ``c`` is not in :meth:`self` and + ``nocheck = True``, then the output of :meth:`unencode` is not + defined (except that it will be in the message space of ``self``). - - an element of the message space of ``self`` + OUTPUT: an element of the message space of ``self`` EXAMPLES:: @@ -246,7 +244,7 @@ def unencode(self, c, nocheck=False): sage: C = LinearCode(G) Traceback (most recent call last): ... - ValueError: length must be a non-zero positive integer + ValueError: length must be a nonzero positive integer """ if not nocheck and c not in self.code(): raise EncodingError("Given word is not in the code") @@ -283,7 +281,7 @@ def _unencoder_matrix(self): def unencode_nocheck(self, c): r""" - Returns the message corresponding to ``c``. + Return the message corresponding to ``c``. When ``c`` is not a codeword, the output is unspecified. @@ -293,12 +291,9 @@ def unencode_nocheck(self, c): INPUT: + - ``c`` -- a codeword of :meth:`code` - - ``c`` -- a codeword of :meth:`code`. - - OUTPUT: - - - an element of the message space of ``self``. + OUTPUT: an element of the message space of ``self`` EXAMPLES:: @@ -332,7 +327,7 @@ def unencode_nocheck(self, c): def code(self): r""" - Returns the code for this :class:`Encoder`. + Return the code for this :class:`Encoder`. EXAMPLES:: @@ -347,7 +342,7 @@ def code(self): def message_space(self): r""" - Returns the ambient space of allowed input to :meth:`encode`. + Return the ambient space of allowed input to :meth:`encode`. Note that :meth:`encode` is possibly a partial function over the ambient space. @@ -365,7 +360,7 @@ def message_space(self): @abstract_method(optional=True) def generator_matrix(self): r""" - Returns a generator matrix of the associated code of ``self``. + Return a generator matrix of the associated code of ``self``. This is an abstract method and it should be implemented separately. Reimplementing this for each subclass of :class:`Encoder` is not mandatory diff --git a/src/sage/coding/extended_code.py b/src/sage/coding/extended_code.py index a9d582b2a67..45557b1277e 100644 --- a/src/sage/coding/extended_code.py +++ b/src/sage/coding/extended_code.py @@ -37,7 +37,7 @@ class ExtendedCode(AbstractLinearCode): INPUT: - - ``C`` -- A linear code + - ``C`` -- a linear code EXAMPLES:: @@ -71,7 +71,7 @@ def __init__(self, C): def __eq__(self, other): r""" - Tests equality between two extended codes. + Test equality between two extended codes. EXAMPLES:: @@ -186,7 +186,7 @@ class ExtendedCodeExtendedMatrixEncoder(Encoder): INPUT: - - ``code`` -- The associated code of ``self``. + - ``code`` -- the associated code of ``self`` """ def __init__(self, code): @@ -234,7 +234,7 @@ def _latex_(self): def __eq__(self, other): r""" - Tests equality between GRSEvaluationVectorEncoder objects. + Test equality between GRSEvaluationVectorEncoder objects. EXAMPLES:: @@ -285,7 +285,7 @@ class ExtendedCodeOriginalCodeDecoder(Decoder): INPUT: - - ``code`` -- The associated code of this decoder + - ``code`` -- the associated code of this decoder - ``original_decoder`` -- (default: ``None``) the decoder that will be used over the original code. It has to be a decoder object over the original code. @@ -444,7 +444,7 @@ def decoding_radius(self, *args, **kwargs): INPUT: - ``*args``, ``**kwargs`` -- arguments and optional arguments are - forwarded to original decoder's ``decoding_radius`` method. + forwarded to original decoder's ``decoding_radius`` method EXAMPLES:: diff --git a/src/sage/coding/gabidulin_code.py b/src/sage/coding/gabidulin_code.py index 341b9b89f5d..cce8fcfc7d5 100644 --- a/src/sage/coding/gabidulin_code.py +++ b/src/sage/coding/gabidulin_code.py @@ -257,9 +257,7 @@ def __eq__(self, other): - ``other`` -- another Gabidulin Code object - OUTPUT: - - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -399,7 +397,7 @@ def __init__(self, code): INPUT: - - ``code`` -- the associated code of this encoder. + - ``code`` -- the associated code of this encoder EXAMPLES:: @@ -467,9 +465,7 @@ def __eq__(self, other): - ``other`` -- another Gabidulin Generator Matrix Encoder - OUTPUT: - - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -625,9 +621,7 @@ def __eq__(self, other): - ``other`` -- another Gabidulin Polynomial Evaluation Encoder - OUTPUT: - - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -666,7 +660,7 @@ def message_space(self): C = self.code() return C.base_field()['x', C.twisting_homomorphism()] - def encode(self, p, form="vector"): + def encode(self, p, form='vector'): """ Transform the polynomial ``p`` into a codeword of :meth:`code`. @@ -680,11 +674,9 @@ def encode(self, p, form="vector"): - ``form`` -- type parameter taking strings "vector" or "matrix" as values and converting the output codeword into the respective form - (default: "vector") - - OUTPUT: + (default: ``'vector'``) - - a codeword corresponding to `p` in vector or matrix form + OUTPUT: a codeword corresponding to `p` in vector or matrix form EXAMPLES:: @@ -855,9 +847,7 @@ def __eq__(self, other) -> bool: - ``other`` -- another Gabidulin Gao Decoder - OUTPUT: - - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -894,9 +884,7 @@ def _partial_xgcd(self, a, b, d_stop): - ``d_stop`` -- the number of iterations for which the algorithm is to be run - OUTPUT: - - - ``r_c`` -- right linearized remainder of `a` and `b` + OUTPUT: ``r_c`` -- right linearized remainder of `a` and `b` - ``u_c`` -- right linearized quotient of `a` and `b` @@ -995,9 +983,7 @@ def decode_to_code(self, r): - ``r`` -- received codeword - OUTPUT: - - - the decoded codeword corresponding to the received codeword + OUTPUT: the decoded codeword corresponding to the received codeword EXAMPLES:: @@ -1028,9 +1014,7 @@ def decode_to_message(self, r): - ``r`` -- received codeword - OUTPUT: - - - the message corresponding to the received codeword + OUTPUT: the message corresponding to the received codeword EXAMPLES:: diff --git a/src/sage/coding/golay_code.py b/src/sage/coding/golay_code.py index 7690962b4b7..3d52dade619 100644 --- a/src/sage/coding/golay_code.py +++ b/src/sage/coding/golay_code.py @@ -38,11 +38,11 @@ class GolayCode(AbstractLinearCode): INPUT: - - ``base_field`` -- The base field over which the code is defined. - Can only be ``GF(2)`` or ``GF(3)``. + - ``base_field`` -- the base field over which the code is defined; + can only be ``GF(2)`` or ``GF(3)`` - - ``extended`` -- (default: ``True``) if set to ``True``, creates an extended Golay - code. + - ``extended`` -- boolean (default: ``True``); if set to ``True``, creates + an extended Golay code EXAMPLES:: @@ -238,7 +238,7 @@ def covering_radius(self): def weight_distribution(self): r""" - Return the list whose `i`'th entry is the number of words of weight `i` + Return the list whose `i`-th entry is the number of words of weight `i` in ``self``. The weight distribution of all Golay codes are known, and are thus returned @@ -282,7 +282,7 @@ def weight_distribution(self): def generator_matrix(self): r""" - Return a generator matrix of ``self`` + Return a generator matrix of ``self``. Generator matrices of all Golay codes are known, and are thus returned by this method without performing any computation diff --git a/src/sage/coding/goppa_code.py b/src/sage/coding/goppa_code.py index 9a87078c619..f61be9e7afb 100644 --- a/src/sage/coding/goppa_code.py +++ b/src/sage/coding/goppa_code.py @@ -79,7 +79,7 @@ class GoppaCode(AbstractLinearCode): - ``generating_pol`` -- a monic polynomial with coefficients in a finite field `\GF{p^m}`, the code is defined over `\GF{p}`, `p` must be a prime number - - ``defining_set`` -- a set of elements of `\GF{p^m}` that are not roots + - ``defining_set`` -- set of elements of `\GF{p^m}` that are not roots of `g`, its cardinality is the length of the code EXAMPLES:: @@ -126,7 +126,7 @@ def __init__(self, generating_pol, defining_set): def _repr_(self): """ - Representation of a Goppa code + Representation of a Goppa code. EXAMPLES:: @@ -315,7 +315,7 @@ def distance_bound(self): class GoppaCodeEncoder(Encoder): r""" - Encoder for Goppa codes + Encoder for Goppa codes. Encodes words represented as vectors of length `k`, where `k` is the dimension of ``self``, with entries from `\GF{p}`, the prime field of @@ -393,7 +393,7 @@ def _latex_(self): def __eq__(self, other): """ - Test equality with ``other`` + Test equality with ``other``. EXAMPLES:: @@ -412,7 +412,7 @@ def __eq__(self, other): def generator_matrix(self): r""" - A generator matrix for ``self`` + A generator matrix for ``self``. Dimension of resulting matrix is `k \times n`, where `k` is the dimension of ``self`` and `n` is the length of ``self``. diff --git a/src/sage/coding/grs_code.py b/src/sage/coding/grs_code.py index 17f5e06114f..ee1c47e07eb 100644 --- a/src/sage/coding/grs_code.py +++ b/src/sage/coding/grs_code.py @@ -11,7 +11,7 @@ \{ (f(\alpha_1), \ldots, f(\alpha_n)) \mid f \in F[x], \deg f < k \} An RS code is often called "classical" if `\alpha_i = \alpha^{i-1}` and `\alpha` -is a primitive `n`'th root of unity. +is a primitive `n`-th root of unity. More generally, given also `n` "column multipliers" `\beta_1, \dots, \beta_n`, the corresponding Generalized Reed-Solomon code (GRS code) of dimension `k` is @@ -76,18 +76,18 @@ class GeneralizedReedSolomonCode(AbstractLinearCode): INPUT: - - ``evaluation_points`` -- a list of distinct elements of some + - ``evaluation_points`` -- list of distinct elements of some finite field `F` - ``dimension`` -- the dimension of the resulting code - - ``column_multipliers`` -- (default: ``None``) list of non-zero + - ``column_multipliers`` -- (default: ``None``) list of nonzero elements of `F`; all column multipliers are set to 1 if default value is kept EXAMPLES: - Often, one constructs a Reed-Solomon code by taking all non-zero elements of + Often, one constructs a Reed-Solomon code by taking all nonzero elements of the field as evaluation points, and specifying no column multipliers (see also :func:`ReedSolomonCode` for constructing classical Reed-Solomon codes directly):: @@ -192,7 +192,7 @@ def __init__(self, evaluation_points, dimension, column_multipliers=None): sage: C = codes.GeneralizedReedSolomonCode(F.list()[:n], k, F.list()[:n]) Traceback (most recent call last): ... - ValueError: All column multipliers must be non-zero + ValueError: All column multipliers must be nonzero And all the evaluation points must be different. Note that they should be different after converting into the same field:: @@ -240,7 +240,7 @@ def __init__(self, evaluation_points, dimension, column_multipliers=None): self._dimension = dimension if F.zero() in self._column_multipliers: - raise ValueError("All column multipliers must be non-zero") + raise ValueError("All column multipliers must be nonzero") if len(self._evaluation_points) != len(set(self._evaluation_points)): raise ValueError("All evaluation points must be different") @@ -503,7 +503,7 @@ def covering_radius(self): @cached_method def weight_distribution(self): r""" - Return the list whose `i`'th entry is the number of words of weight `i` + Return the list whose `i`-th entry is the number of words of weight `i` in ``self``. Computing the weight distribution for a GRS code is very fast. Note that @@ -550,7 +550,7 @@ def _punctured_form(self, points): INPUT: - - ``points`` -- a set of positions where to puncture ``self`` + - ``points`` -- set of positions where to puncture ``self`` EXAMPLES:: @@ -579,7 +579,7 @@ def ReedSolomonCode(base_field, length, dimension, primitive_root=None): A classical `[n,k]` Reed-Solomon code over `\GF{q}` with `1 \le k \le n` and `n | (q-1)` is a Reed-Solomon code whose evaluation points are the - consecutive powers of a primitive `n`'th root of unity `\alpha`, i.e. + consecutive powers of a primitive `n`-th root of unity `\alpha`, i.e. `\alpha_i = \alpha^{i-1}`, where `\alpha_1, \ldots, \alpha_n` are the evaluation points. A classical Reed-Solomon codes has all column multipliers equal `1`. @@ -593,17 +593,17 @@ def ReedSolomonCode(base_field, length, dimension, primitive_root=None): INPUT: - ``base_field`` -- the finite field for which to build the classical - Reed-Solomon code. + Reed-Solomon code - ``length`` -- the length of the classical Reed-Solomon code. Must divide - `q-1` where `q` is the cardinality of ``base_field``. + `q-1` where `q` is the cardinality of ``base_field`` - - ``dimension`` -- the dimension of the resulting code. + - ``dimension`` -- the dimension of the resulting code - - ``primitive_root`` -- (default: ``None``) a primitive `n`'th root of unity - to use for constructing the classical Reed-Solomon code. If not supplied, + - ``primitive_root`` -- (default: ``None``) a primitive `n`-th root of unity + to use for constructing the classical Reed-Solomon code; if not supplied, one will be computed and can be recovered as ``C.evaluation_points()[1]`` - where `C` is the code returned by this method. + where `C` is the code returned by this method EXAMPLES:: @@ -623,12 +623,12 @@ def ReedSolomonCode(base_field, length, dimension, primitive_root=None): sage: C = codes.ReedSolomonCode(GF(64,'a'), 9, 4); C [9, 4, 6] Reed-Solomon Code over GF(64) - The primitive `n`'th root of unity can be recovered as the 2nd evaluation point of the code:: + The primitive `n`-th root of unity can be recovered as the 2nd evaluation point of the code:: sage: alpha = C.evaluation_points()[1]; alpha a^5 + a^4 + a^2 + a - We can also supply a different primitive `n`'th root of unity:: + We can also supply a different primitive `n`-th root of unity:: sage: beta = alpha^2; beta a^4 + a @@ -759,7 +759,7 @@ def _latex_(self): @cached_method def generator_matrix(self): r""" - Return a generator matrix of ``self`` + Return a generator matrix of ``self``. Considering a GRS code of length `n`, dimension `k`, with evaluation points `(\alpha_1, \dots, \alpha_n)` and column multipliers @@ -872,7 +872,6 @@ def __init__(self, code, polynomial_ring=None): Traceback (most recent call last): ... ValueError: polynomial_ring's base field has to be the same as code's - """ from sage.rings.polynomial.polynomial_ring import PolynomialRing_commutative super().__init__(code) @@ -956,9 +955,7 @@ def encode(self, p): - ``p`` -- a polynomial from the message space of ``self`` of degree less than ``self.code().dimension()`` - OUTPUT: - - - a codeword in associated code of ``self`` + OUTPUT: a codeword in associated code of ``self`` EXAMPLES:: @@ -1056,7 +1053,6 @@ def unencode_nocheck(self, c): 6*x^4 + 6*x^3 + 2*x^2 sage: E.encode(p) == c False - """ C = self.code() alphas = C.evaluation_points() @@ -1070,7 +1066,7 @@ def unencode_nocheck(self, c): def message_space(self): r""" - Return the message space of ``self`` + Return the message space of ``self``. EXAMPLES:: @@ -1269,9 +1265,7 @@ def decode_to_message(self, r): - ``r`` -- a codeword of ``self`` - OUTPUT: - - - a vector of ``self`` message space + OUTPUT: a vector of ``self`` message space EXAMPLES:: @@ -1381,9 +1375,7 @@ def decoding_radius(self): r""" Return maximal number of errors that ``self`` can decode. - OUTPUT: - - - the number of errors as an integer + OUTPUT: the number of errors as an integer EXAMPLES:: @@ -1464,7 +1456,7 @@ def __eq__(self, other): def __hash__(self): """ - Return the hash of self. + Return the hash of ``self``. EXAMPLES:: @@ -1519,9 +1511,7 @@ def _polynomial_vanishing_at_alphas(self, PolRing): - ``PolRing`` -- polynomial ring of the output - OUTPUT: - - - a polynomial over ``PolRing`` + OUTPUT: a polynomial over ``PolRing`` EXAMPLES:: @@ -1541,7 +1531,7 @@ def _polynomial_vanishing_at_alphas(self, PolRing): def _partial_xgcd(self, a, b, PolRing): r""" - Performs an Euclidean algorithm on ``a`` and ``b`` until a remainder + Perform an Euclidean algorithm on ``a`` and ``b`` until a remainder has degree less than `\frac{n+k}{2}`, `n` being the dimension of the code, `k` its dimension, and returns `(r, s)` such that in the step just before termination, `r = a s + b t`. @@ -1652,9 +1642,7 @@ def decode_to_message(self, r): - ``r`` -- a codeword of ``self`` - OUTPUT: - - - a vector of ``self`` message space + OUTPUT: a vector of ``self`` message space EXAMPLES:: @@ -1764,11 +1752,9 @@ def decode_to_code(self, r): def decoding_radius(self): r""" - Return maximal number of errors that ``self`` can decode - - OUTPUT: + Return maximal number of errors that ``self`` can decode. - - the number of errors as an integer + OUTPUT: the number of errors as an integer EXAMPLES:: @@ -1898,7 +1884,7 @@ def decode_to_message(self, word_and_erasure_vector): INPUT: - - ``word_and_erasure_vector`` -- a tuple whose: + - ``word_and_erasure_vector`` -- tuple whose: * first element is an element of the ambient space of the code * second element is a vector over `\GF{2}` whose length is the @@ -1914,9 +1900,7 @@ def decode_to_message(self, word_and_erasure_vector): In either case, if ``r`` is not a codeword, the output is unspecified. - OUTPUT: - - - a vector of ``self`` message space + OUTPUT: a vector of ``self`` message space EXAMPLES:: @@ -1993,9 +1977,7 @@ def decoding_radius(self, number_erasures): - ``number_erasures`` -- the number of erasures when we try to decode - OUTPUT: - - - the number of errors as an integer + OUTPUT: the number of errors as an integer EXAMPLES:: @@ -2032,7 +2014,7 @@ class GRSKeyEquationSyndromeDecoder(Decoder): INPUT: - - ``code`` -- The associated code of this decoder. + - ``code`` -- the associated code of this decoder EXAMPLES:: @@ -2130,7 +2112,7 @@ def _latex_(self): def _partial_xgcd(self, a, b, PolRing): r""" - Performs an Euclidean algorithm on ``a`` and ``b`` until a remainder + Perform a Euclidean algorithm on ``a`` and ``b`` until a remainder has degree less than `\frac{n+k}{2}`, `n` being the dimension of the code, `k` its dimension, and returns `(r, t)` such that in the step just before termination, `r = a s + b t`. @@ -2177,9 +2159,7 @@ def _syndrome(self, r): - ``r`` -- a vector of the ambient space of ``self.code()`` - OUTPUT: - - - a list + OUTPUT: list EXAMPLES:: @@ -2214,9 +2194,7 @@ def _forney_formula(self, error_evaluator, error_locator): - ``error_evaluator``, ``error_locator`` -- two polynomials - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -2322,7 +2300,7 @@ def decode_to_code(self, r): def decode_to_message(self, r): r""" - Decode ``r`` to an element in message space of ``self`` + Decode ``r`` to an element in message space of ``self``. .. NOTE:: @@ -2334,9 +2312,7 @@ def decode_to_message(self, r): - ``r`` -- a codeword of ``self`` - OUTPUT: - - - a vector of ``self`` message space + OUTPUT: a vector of ``self`` message space EXAMPLES:: @@ -2358,11 +2334,9 @@ def decode_to_message(self, r): def decoding_radius(self): r""" - Return maximal number of errors that ``self`` can decode - - OUTPUT: + Return maximal number of errors that ``self`` can decode. - - the number of errors as an integer + OUTPUT: the number of errors as an integer EXAMPLES:: diff --git a/src/sage/coding/guava.py b/src/sage/coding/guava.py index 4dbe39e85b8..8a375af4bef 100644 --- a/src/sage/coding/guava.py +++ b/src/sage/coding/guava.py @@ -52,11 +52,9 @@ def QuasiQuadraticResidueCode(p): INPUT: - - ``p`` -- a prime `>2`. + - ``p`` -- a prime `>2` - OUTPUT: - - Returns a QQR code of length `2p`. + OUTPUT: a QQR code of length `2p` EXAMPLES:: @@ -67,8 +65,8 @@ def QuasiQuadraticResidueCode(p): AUTHOR: David Joyner (11-2005) """ - GapPackage("guava", spkg="gap_packages").require() - libgap.load_package("guava") + GapPackage('guava', spkg='gap_packages').require() + libgap.load_package('guava') C = libgap.QQRCode(p) G = C.GeneratorMat() MS = MatrixSpace(GF(2), len(G), len(G[0])) @@ -85,11 +83,9 @@ def RandomLinearCodeGuava(n, k, F): INPUT: - - ``n``, ``k`` -- integers with `n>k>1`. - - OUTPUT: + - ``n``, ``k`` -- integers with `n>k>1` - Returns a "random" linear code with length `n`, dimension `k` over field `F`. + OUTPUT: a "random" linear code with length `n`, dimension `k` over field `F` EXAMPLES:: @@ -102,8 +98,8 @@ def RandomLinearCodeGuava(n, k, F): """ current_randstate().set_seed_gap() - GapPackage("guava", spkg="gap_packages").require() - libgap.load_package("guava") + GapPackage('guava', spkg='gap_packages').require() + libgap.load_package('guava') C = libgap.RandomLinearCode(n,k,F) G = C.GeneratorMat() MS = MatrixSpace(F, len(G), len(G[0])) diff --git a/src/sage/coding/guruswami_sudan/gs_decoder.py b/src/sage/coding/guruswami_sudan/gs_decoder.py index 2cd680b5da0..6a91949234f 100644 --- a/src/sage/coding/guruswami_sudan/gs_decoder.py +++ b/src/sage/coding/guruswami_sudan/gs_decoder.py @@ -48,14 +48,14 @@ def n_k_params(C, n_k): INPUT: - - ``C`` -- A GRS code or ``None`` + - ``C`` -- a GRS code or ``None`` - - ``n_k`` -- A tuple `(n,k)` being length and dimension of a GRS code, or - ``None``. + - ``n_k`` -- tuple `(n,k)` being length and dimension of a GRS code, or + ``None`` OUTPUT: - - ``n_k`` -- A tuple `(n,k)` being length and dimension of a GRS code. + - ``n_k`` -- tuple `(n,k)` being length and dimension of a GRS code EXAMPLES:: @@ -102,7 +102,7 @@ def roth_ruckenstein_root_finder(p, maxd=None, precision=None): gens = p.parent().gens() if len(gens) == 2: p = p.polynomial(gens[1]) - return p.roots(multiplicities=False, degree_bound=maxd, algorithm="Roth-Ruckenstein") + return p.roots(multiplicities=False, degree_bound=maxd, algorithm='Roth-Ruckenstein') def alekhnovich_root_finder(p, maxd=None, precision=None): """ @@ -121,7 +121,7 @@ def alekhnovich_root_finder(p, maxd=None, precision=None): gens = p.parent().gens() if len(gens) == 2: p = p.polynomial(gens[1]) - return p.roots(multiplicities=False, degree_bound=maxd, algorithm="Alekhnovich") + return p.roots(multiplicities=False, degree_bound=maxd, algorithm='Alekhnovich') class GRSGuruswamiSudanDecoder(Decoder): r""" @@ -152,10 +152,10 @@ class GRSGuruswamiSudanDecoder(Decoder): INPUT: - - ``code`` -- A code associated to this decoder. + - ``code`` -- a code associated to this decoder - - ``tau`` -- (default: ``None``) an integer, the number of errors one wants the - Guruswami-Sudan algorithm to correct. + - ``tau`` -- integer (default: ``None``); the number of errors one wants the + Guruswami-Sudan algorithm to correct - ``parameters`` -- (default: ``None``) a pair of integers, where: @@ -165,8 +165,8 @@ class GRSGuruswamiSudanDecoder(Decoder): - ``interpolation_alg`` -- (default: ``None``) the interpolation algorithm that will be used. The following possibilities are currently available: - * ``"LinearAlgebra"`` -- uses a linear system solver. - * ``"LeeOSullivan"`` -- uses Lee O'Sullivan method based on row reduction + * ``'LinearAlgebra'`` -- uses a linear system solver. + * ``'LeeOSullivan'`` -- uses Lee O'Sullivan method based on row reduction of a matrix * ``None`` -- one of the above will be chosen based on the size of the code and the parameters. @@ -177,9 +177,9 @@ class GRSGuruswamiSudanDecoder(Decoder): - ``root_finder`` -- (default: ``None``) the rootfinding algorithm that will be used. The following possibilities are currently available: - * ``"Alekhnovich"`` -- uses Alekhnovich's algorithm. + * ``'Alekhnovich'`` -- uses Alekhnovich's algorithm. - * ``"RothRuckenstein"`` -- uses Roth-Ruckenstein algorithm. + * ``'RothRuckenstein'`` -- uses Roth-Ruckenstein algorithm. * ``None`` -- one of the above will be chosen based on the size of the code and the parameters. @@ -231,7 +231,7 @@ class GRSGuruswamiSudanDecoder(Decoder): sage: D = codes.decoders.GRSGuruswamiSudanDecoder(C, parameters=(1,2), - ....: root_finder="RothRuckenstein"); D + ....: root_finder='RothRuckenstein'); D Guruswami-Sudan decoder for [250, 70, 181] Reed-Solomon Code over GF(251) decoding 97 errors with parameters (1, 2) @@ -252,7 +252,7 @@ def parameters_given_tau(tau, C=None, n_k=None): INPUT: - - ``tau`` -- an integer, number of errors one wants the Guruswami-Sudan + - ``tau`` -- integer; number of errors one wants the Guruswami-Sudan algorithm to correct - ``C`` -- (default: ``None``) a :class:`GeneralizedReedSolomonCode` - ``n_k`` -- (default: ``None``) a pair of integers, respectively the @@ -331,8 +331,9 @@ def guruswami_sudan_decoding_radius(C=None, n_k=None, l=None, s=None): - ``C`` -- (default: ``None``) a :class:`GeneralizedReedSolomonCode` - ``n_k`` -- (default: ``None``) a pair of integers, respectively the length and the dimension of the :class:`GeneralizedReedSolomonCode` - - ``s`` -- (default: ``None``) an integer, the multiplicity parameter of Guruswami-Sudan algorithm - - ``l`` -- (default: ``None``) an integer, the list size parameter + - ``s`` -- integer (default: ``None``); the multiplicity parameter of + Guruswami-Sudan algorithm + - ``l`` -- integer (default: ``None``); the list size parameter .. NOTE:: @@ -427,7 +428,7 @@ def _suitable_parameters_given_tau(tau, C=None, n_k=None): INPUT: - - ``tau`` -- an integer, number of errors one wants the Guruswami-Sudan + - ``tau`` -- integer; number of errors one wants the Guruswami-Sudan algorithm to correct - ``C`` -- (default: ``None``) a :class:`GeneralizedReedSolomonCode` - ``n_k`` -- (default: ``None``) a pair of integers, respectively the @@ -497,10 +498,10 @@ def gs_satisfactory(tau, s, l, C=None, n_k=None): INPUT: - - ``tau`` -- an integer, number of errors one expects Guruswami-Sudan algorithm + - ``tau`` -- integer; number of errors one expects Guruswami-Sudan algorithm to correct - - ``s`` -- an integer, multiplicity parameter of Guruswami-Sudan algorithm - - ``l`` -- an integer, list size parameter + - ``s`` -- integer; multiplicity parameter of Guruswami-Sudan algorithm + - ``l`` -- integer; list size parameter - ``C`` -- (default: ``None``) a :class:`GeneralizedReedSolomonCode` - ``n_k`` -- (default: ``None``) a tuple of integers, respectively the length and the dimension of the :class:`GeneralizedReedSolomonCode` @@ -576,7 +577,7 @@ def __init__(self, code, tau=None, parameters=None, interpolation_alg=None, root Same thing for ``root_finder``:: sage: C = codes.GeneralizedReedSolomonCode(GF(251).list()[:250], 70) - sage: D = GSD(C, tau=97, root_finder="FortyTwo") + sage: D = GSD(C, tau=97, root_finder='FortyTwo') Traceback (most recent call last): ... ValueError: Please provide a method or one of the allowed strings for root_finder @@ -660,7 +661,7 @@ def _latex_(self): def __eq__(self, other): r""" - Tests equality between GRSGuruswamiSudanDecoder objects. + Test equality between GRSGuruswamiSudanDecoder objects. EXAMPLES:: @@ -762,7 +763,7 @@ def decode_to_message(self, r): INPUT: - ``r`` -- a received word, i.e. a vector in `F^n` where `F` and `n` are - the base field respectively length of :meth:`self.code`. + the base field respectively length of :meth:`self.code` EXAMPLES:: @@ -807,7 +808,7 @@ def decode_to_code(self, r): INPUT: - ``r`` -- a received word, i.e. a vector in `F^n` where `F` and `n` are - the base field respectively length of :meth:`self.code`. + the base field respectively length of :meth:`self.code` EXAMPLES:: diff --git a/src/sage/coding/guruswami_sudan/interpolation.py b/src/sage/coding/guruswami_sudan/interpolation.py index ec4307a500b..c7855af3381 100644 --- a/src/sage/coding/guruswami_sudan/interpolation.py +++ b/src/sage/coding/guruswami_sudan/interpolation.py @@ -36,7 +36,7 @@ def _flatten_once(lstlst): INPUT: - - ``lstlst`` -- a list of lists. + - ``lstlst`` -- list of lists EXAMPLES:: @@ -54,16 +54,14 @@ def _flatten_once(lstlst): def _monomial_list(maxdeg, l, wy): r""" - Returns a list of all non-negative integer pairs `(i,j)` such that ``i + wy + Return a list of all nonnegative integer pairs `(i,j)` such that ``i + wy * j < maxdeg`` and ``j \geq l``. INPUT: - - ``maxdeg``, ``l``, ``wy`` -- integers. + - ``maxdeg``, ``l``, ``wy`` -- integers - OUTPUT: - - - a list of pairs of integers. + OUTPUT: list of pairs of integers EXAMPLES:: @@ -90,7 +88,7 @@ def _monomial_list(maxdeg, l, wy): def _interpolation_matrix_given_monomials(points, s, monomials): r""" - Returns a matrix whose nullspace is a basis for all interpolation + Return a matrix whose nullspace is a basis for all interpolation polynomials, each polynomial having its coefficients laid out according to the given list of monomials. @@ -100,11 +98,11 @@ def _interpolation_matrix_given_monomials(points, s, monomials): INPUT: - - ``points`` -- a list of pairs of field elements, the interpolation points. + - ``points`` -- list of pairs of field elements, the interpolation points - - ``s`` -- an integer, the multiplicity parameter from Guruswami-Sudan algorithm. + - ``s`` -- integer; the multiplicity parameter from Guruswami-Sudan algorithm - - ``monomials`` -- a list of monomials, each represented by the powers as an integer pair `(i,j)`. + - ``monomials`` -- list of monomials, each represented by the powers as an integer pair `(i,j)` EXAMPLES:: @@ -160,25 +158,25 @@ def _interpolation_max_weighted_deg(n, tau, s): def _interpolation_matrix_problem(points, tau, parameters, wy): r""" - Returns the linear system of equations which ``Q`` should be a solution to. + Return the linear system of equations which ``Q`` should be a solution to. This linear system is returned as a matrix ``M`` and a list of monomials ``monomials``, where a vector in the right nullspace of ``M`` corresponds to an - interpolation polynomial `Q`, by mapping the `t`'th element of such a vector - to the coefficient to `x^iy^j`, where `(i,j)` is the `t`'th element of ``monomials``. + interpolation polynomial `Q`, by mapping the `t`-th element of such a vector + to the coefficient to `x^iy^j`, where `(i,j)` is the `t`-th element of ``monomials``. INPUT: - - ``points`` -- a list of interpolation points, as pairs of field elements. + - ``points`` -- list of interpolation points, as pairs of field elements - - ``tau`` -- an integer, the number of errors one wants to decode. + - ``tau`` -- integer; the number of errors one wants to decode - ``parameters`` -- (default: ``None``) a pair of integers, where: - the first integer is the multiplicity parameter of Guruswami-Sudan algorithm and - the second integer is the list size parameter. - - ``wy`` -- an integer specifying the `y`-weighted degree that is to be + - ``wy`` -- integer; specifying the `y`-weighted degree that is to be minimised in the interpolation polynomial. In Guruswami-Sudan, this is `k-1`, where `k` is the dimension of the GRS code. @@ -235,10 +233,10 @@ def gs_interpolation_linalg(points, tau, parameters, wy): INPUT: - - ``points`` -- a list of tuples ``(xi, yi)`` such that we seek ``Q`` with - ``(xi,yi)`` being a root of ``Q`` with multiplicity ``s``. + - ``points`` -- list of tuples ``(xi, yi)`` such that we seek ``Q`` with + ``(xi,yi)`` being a root of ``Q`` with multiplicity ``s`` - - ``tau`` -- an integer, the number of errors one wants to decode. + - ``tau`` -- integer; the number of errors one wants to decode - ``parameters`` -- (default: ``None``) a pair of integers, where: @@ -246,8 +244,8 @@ def gs_interpolation_linalg(points, tau, parameters, wy): algorithm and - the second integer is the list size parameter. - - ``wy`` -- an integer, the `y`-weight, where we seek `Q` of low - ``(1, wy)``-weighted degree. + - ``wy`` -- integer; the `y`-weight, where we seek `Q` of low + ``(1, wy)``-weighted degree EXAMPLES: @@ -279,7 +277,7 @@ def gs_interpolation_linalg(points, tau, parameters, wy): """ M, monomials = _interpolation_matrix_problem(points, tau, parameters, wy) Ker = M.right_kernel() - # Pick a non-zero element from the right kernel + # Pick a nonzero element from the right kernel sol = Ker.basis()[0] # Construct the Q polynomial PF = M.base_ring()['x', 'y'] #make that ring a ring in @@ -298,7 +296,7 @@ def lee_osullivan_module(points, parameters, wy): The module is constructed in the following way: Let `R(x)` be the Lagrange interpolation polynomial through the sought interpolation points `(x_i, y_i)`, i.e. `R(x_i) = y_i`. Let `G(x) = \prod_{i=1}^n (x-x_i)`. Then the - `i`'th row of the basis matrix of the module is the coefficient-vector of + `i`-th row of the basis matrix of the module is the coefficient-vector of the following polynomial in `\GF{q}[x][y]`: `P_i(x,y) = G(x)^{[i-s]} (y - R(x))^{i - [i-s]} y^{[i-s]}` , @@ -310,8 +308,8 @@ def lee_osullivan_module(points, parameters, wy): INPUT: - - ``points`` -- a list of tuples ``(xi, yi)`` such that we seek `Q` with - ``(xi,yi)`` being a root of `Q` with multiplicity `s`. + - ``points`` -- list of tuples ``(xi, yi)`` such that we seek `Q` with + ``(xi,yi)`` being a root of `Q` with multiplicity `s` - ``parameters`` -- (default: ``None``) a pair of integers, where: @@ -319,8 +317,8 @@ def lee_osullivan_module(points, parameters, wy): algorithm and - the second integer is the list size parameter. - - ``wy`` -- an integer, the `y`-weight, where we seek `Q` of low - ``(1,wy)`` weighted degree. + - ``wy`` -- integer; the `y`-weight, where we seek `Q` of low + ``(1,wy)`` weighted degree EXAMPLES:: @@ -353,7 +351,7 @@ def pad(lst): def gs_interpolation_lee_osullivan(points, tau, parameters, wy): r""" - Returns an interpolation polynomial Q(x,y) for the given input using the + Return an interpolation polynomial Q(x,y) for the given input using the module-based algorithm of Lee and O'Sullivan. This algorithm constructs an explicit `(\ell+1) \times (\ell+1)` polynomial @@ -364,10 +362,10 @@ def gs_interpolation_lee_osullivan(points, tau, parameters, wy): INPUT: - - ``points`` -- a list of tuples ``(xi, yi)`` such that we seek ``Q`` with - ``(xi,yi)`` being a root of ``Q`` with multiplicity ``s``. + - ``points`` -- list of tuples ``(xi, yi)`` such that we seek ``Q`` with + ``(xi,yi)`` being a root of ``Q`` with multiplicity ``s`` - - ``tau`` -- an integer, the number of errors one wants to decode. + - ``tau`` -- integer; the number of errors one wants to decode - ``parameters`` -- (default: ``None``) a pair of integers, where: @@ -375,8 +373,8 @@ def gs_interpolation_lee_osullivan(points, tau, parameters, wy): algorithm and - the second integer is the list size parameter. - - ``wy`` -- an integer, the `y`-weight, where we seek ``Q`` of low - ``(1,wy)`` weighted degree. + - ``wy`` -- integer; the `y`-weight, where we seek ``Q`` of low + ``(1,wy)`` weighted degree EXAMPLES:: diff --git a/src/sage/coding/guruswami_sudan/utils.py b/src/sage/coding/guruswami_sudan/utils.py index f29d4eac46f..31bfdf85e64 100644 --- a/src/sage/coding/guruswami_sudan/utils.py +++ b/src/sage/coding/guruswami_sudan/utils.py @@ -29,14 +29,14 @@ def polynomial_to_list(p, len): r""" - Returns ``p`` as a list of its coefficients of length ``len``. + Return ``p`` as a list of its coefficients of length ``len``. INPUT: - ``p`` -- a polynomial - - ``len`` -- an integer. If ``len`` is smaller than the degree of ``p``, the - returned list will be of size degree of ``p``, else it will be of size ``len``. + - ``len`` -- integer; if ``len`` is smaller than the degree of ``p``, the + returned list will be of size degree of ``p``, else it will be of size ``len`` EXAMPLES:: @@ -51,14 +51,14 @@ def polynomial_to_list(p, len): def johnson_radius(n, d): r""" - Returns the Johnson-radius for the code length `n` and the minimum distance `d`. + Return the Johnson-radius for the code length `n` and the minimum distance `d`. The Johnson radius is defined as `n - \sqrt(n(n-d))`. INPUT: - - ``n`` -- an integer, the length of the code - - ``d`` -- an integer, the minimum distance of the code + - ``n`` -- integer; the length of the code + - ``d`` -- integer; the minimum distance of the code EXAMPLES:: @@ -70,7 +70,7 @@ def johnson_radius(n, d): def ligt(x): r""" - Returns the least integer greater than ``x``. + Return the least integer greater than ``x``. EXAMPLES:: @@ -88,7 +88,7 @@ def ligt(x): def gilt(x): r""" - Returns the greatest integer smaller than ``x``. + Return the greatest integer smaller than ``x``. EXAMPLES:: @@ -109,16 +109,17 @@ def gilt(x): def solve_degree2_to_integer_range(a, b, c): r""" - Returns the greatest integer range `[i_1, i_2]` such that - `i_1 > x_1` and `i_2 < x_2` where `x_1, x_2` are the two zeroes of the equation in `x`: - `ax^2+bx+c=0`. + Return the greatest integer range `[i_1, i_2]` such that + `i_1 > x_1` and `i_2 < x_2` where `x_1, x_2` are the two zeroes of the + equation in `x`: `ax^2+bx+c=0`. - If there is no real solution to the equation, it returns an empty range with negative coefficients. + If there is no real solution to the equation, it returns an empty range + with negative coefficients. INPUT: - - ``a``, ``b`` and ``c`` -- coefficients of a second degree equation, ``a`` being the coefficient of - the higher degree term. + - ``a``, ``b`` and ``c`` -- coefficients of a second degree equation, ``a`` + being the coefficient of the higher degree term EXAMPLES:: @@ -145,11 +146,11 @@ def solve_degree2_to_integer_range(a, b, c): def _degree_of_vector(v, shifts=None): r""" - Returns the greatest degree among the entries of the polynomial vector `v`. + Return the greatest degree among the entries of the polynomial vector `v`. INPUT: - - ``v`` -- a vector of polynomials. + - ``v`` -- a vector of polynomials - ``shifts`` -- (default: ``None``) a list of integer shifts to consider ``v`` under, i.e. compute `\max(\deg v_i + s_i)`, where `s_1,\ldots, s_n` diff --git a/src/sage/coding/hamming_code.py b/src/sage/coding/hamming_code.py index 184023e3c29..431e660fae7 100644 --- a/src/sage/coding/hamming_code.py +++ b/src/sage/coding/hamming_code.py @@ -33,9 +33,9 @@ class HammingCode(AbstractLinearCode): INPUT: - - ``base_field`` -- the base field over which ``self`` is defined. + - ``base_field`` -- the base field over which ``self`` is defined - - ``order`` -- the order of ``self``. + - ``order`` -- the order of ``self`` EXAMPLES:: @@ -147,7 +147,6 @@ def parity_check_matrix(self): [1 0 1 1 0 1 0 1 1 1 0 1 1] [0 1 1 2 0 0 1 1 2 0 1 1 2] [0 0 0 0 1 1 1 1 1 2 2 2 2] - """ n = self.length() F = self.base_field() diff --git a/src/sage/coding/information_set_decoder.py b/src/sage/coding/information_set_decoder.py index 32bce3225e9..00f4816c37a 100644 --- a/src/sage/coding/information_set_decoder.py +++ b/src/sage/coding/information_set_decoder.py @@ -78,14 +78,14 @@ class InformationSetAlgorithm(SageObject): INPUT: - - ``code`` -- A linear code for which to decode. + - ``code`` -- a linear code for which to decode - - ``number_errors`` -- an integer, the maximal number of errors to accept as + - ``number_errors`` -- integer; the maximal number of errors to accept as correct decoding. An interval can also be specified by giving a pair of integers, where both end values are taken to be in the interval. - - ``algorithm_name`` -- A name for the specific ISD algorithm used (used for - printing). + - ``algorithm_name`` -- a name for the specific ISD algorithm used (used for + printing) - ``parameters`` -- (optional) A dictionary for setting the parameters of this ISD algorithm. Note that sanity checking this dictionary for the @@ -269,7 +269,7 @@ def parameters(self): def __eq__(self, other): r""" - Tests equality between ISD algorithm objects. + Test equality between ISD algorithm objects. EXAMPLES:: @@ -301,7 +301,7 @@ def __eq__(self, other): def __hash__(self): r""" - Returns the hash value of ``self``. + Return the hash value of ``self``. EXAMPLES:: @@ -319,7 +319,7 @@ def __hash__(self): def _repr_(self): r""" - Returns a string representation of this ISD algorithm. + Return a string representation of this ISD algorithm. EXAMPLES:: @@ -333,7 +333,7 @@ def _repr_(self): def _latex_(self): r""" - Returns a latex representation of this ISD algorithm. + Return a latex representation of this ISD algorithm. EXAMPLES:: @@ -372,10 +372,10 @@ class LeeBrickellISDAlgorithm(InformationSetAlgorithm): INPUT: - - ``code`` -- A linear code for which to decode. + - ``code`` -- a linear code for which to decode - ``decoding_interval`` -- a pair of integers specifying an interval of - number of errors to correct. Includes both end values. + number of errors to correct; includes both end values - ``search_size`` -- (optional) the size of subsets to use on step 3 of the algorithm as described above. Usually a small number. It has to be at most @@ -439,10 +439,10 @@ def decode(self, r): INPUT: - - `r` -- a received word, i.e. a vector in the ambient space of - :meth:`decoder.Decoder.code`. + - ``r`` -- a received word, i.e. a vector in the ambient space of + :meth:`decoder.Decoder.code` - OUTPUT: A codeword whose distance to `r` satisfies ``self.decoding_interval()``. + OUTPUT: a codeword whose distance to `r` satisfies ``self.decoding_interval()``. EXAMPLES:: @@ -518,10 +518,10 @@ def calibrate(self): computations similar to those done by the decoding algorithm. We don't explicitly estimate `\rho`. - OUTPUT: Does not output anything but sets private fields used by + OUTPUT: does not output anything but sets private fields used by :meth:`sage.coding.information_set_decoder.InformationSetAlgorithm.parameters()` and - :meth:`sage.coding.information_set_decoder.InformationSetAlgorithm.time_estimate()``. + :meth:`sage.coding.information_set_decoder.InformationSetAlgorithm.time_estimate()`. EXAMPLES:: @@ -606,10 +606,10 @@ def _calibrate_select(self, estimates): INPUT: - - `estimates` -- list of time estimates, for the search size set to the - index of the list entry. + - ``estimates`` -- list of time estimates, for the search size set to the + index of the list entry - OUTPUT: None, but sets the private fields `self._parameters` and + OUTPUT: none, but sets the private fields `self._parameters` and `self._time_estimate`. TESTS:: @@ -668,9 +668,9 @@ class LinearCodeInformationSetDecoder(Decoder): INPUT: - - ``code`` -- A linear code for which to decode. + - ``code`` -- a linear code for which to decode - - ``number_errors`` -- an integer, the maximal number of errors to accept as + - ``number_errors`` -- integer; the maximal number of errors to accept as correct decoding. An interval can also be specified by giving a pair of integers, where both end values are taken to be in the interval. @@ -697,7 +697,7 @@ class LinearCodeInformationSetDecoder(Decoder): :meth:`sage.code.linear_code.AbstractLinearCode.decoder` method:: sage: C = codes.GolayCode(GF(3)) - sage: D = C.decoder("InformationSet", 2); D + sage: D = C.decoder('InformationSet', 2); D Information-set decoder (Lee-Brickell) for [12, 6, 6] Extended Golay code over GF(3) decoding up to 2 errors @@ -705,7 +705,7 @@ class LinearCodeInformationSetDecoder(Decoder): order to pass special parameters to it:: sage: C = codes.GolayCode(GF(3)) - sage: D2 = C.decoder("InformationSet", 2, algorithm="Lee-Brickell", search_size=2); D2 + sage: D2 = C.decoder('InformationSet', 2, algorithm='Lee-Brickell', search_size=2); D2 Information-set decoder (Lee-Brickell) for [12, 6, 6] Extended Golay code over GF(3) decoding up to 2 errors sage: D2.algorithm() @@ -716,7 +716,7 @@ class LinearCodeInformationSetDecoder(Decoder): If you specify an algorithm which is not known, you get a friendly error message:: - sage: C.decoder("InformationSet", 2, algorithm="NoSuchThing") + sage: C.decoder('InformationSet', 2, algorithm="NoSuchThing") Traceback (most recent call last): ... ValueError: Unknown ISD algorithm 'NoSuchThing'. @@ -727,14 +727,14 @@ class LinearCodeInformationSetDecoder(Decoder): sage: from sage.coding.information_set_decoder import LeeBrickellISDAlgorithm sage: A = LeeBrickellISDAlgorithm(C, (0, 2)) - sage: D = C.decoder("InformationSet", 2, algorithm=A); D + sage: D = C.decoder('InformationSet', 2, algorithm=A); D Information-set decoder (Lee-Brickell) for [12, 6, 6] Extended Golay code over GF(3) decoding up to 2 errors When passing an already constructed ISD algorithm, you can't also pass parameters to the ISD algorithm when constructing the decoder:: - sage: C.decoder("InformationSet", 2, algorithm=A, search_size=2) + sage: C.decoder('InformationSet', 2, algorithm=A, search_size=2) Traceback (most recent call last): ... ValueError: ISD algorithm arguments are not allowed @@ -743,7 +743,7 @@ class LinearCodeInformationSetDecoder(Decoder): We can also information-set decode non-binary codes:: sage: C = codes.GolayCode(GF(3)) - sage: D = C.decoder("InformationSet", 2); D + sage: D = C.decoder('InformationSet', 2); D Information-set decoder (Lee-Brickell) for [12, 6, 6] Extended Golay code over GF(3) decoding up to 2 errors @@ -766,7 +766,7 @@ def __init__(self, code, number_errors, algorithm=None, **kwargs): or an Integer/int:: sage: C = codes.GolayCode(GF(2)) - sage: D = C.decoder("InformationSet", "aa") + sage: D = C.decoder('InformationSet', "aa") Traceback (most recent call last): ... ValueError: number_errors should be an integer or a pair of integers @@ -775,14 +775,14 @@ def __init__(self, code, number_errors, algorithm=None, **kwargs): two values, the first one being at most the second one:: sage: C = codes.GolayCode(GF(2)) - sage: D = C.decoder("InformationSet", (4, 2)) + sage: D = C.decoder('InformationSet', (4, 2)) Traceback (most recent call last): ... ValueError: number_errors should be a positive integer or a valid interval within the positive integers You cannot ask the decoder to correct more errors than the code length:: - sage: D = C.decoder("InformationSet", 25) + sage: D = C.decoder('InformationSet', 25) Traceback (most recent call last): ... ValueError: The provided number of errors should be at most the code's length @@ -790,7 +790,7 @@ def __init__(self, code, number_errors, algorithm=None, **kwargs): If ``algorithm`` is not set, additional parameters cannot be passed to the ISD algorithm:: - sage: D = C.decoder("InformationSet", 2, search_size=2) + sage: D = C.decoder('InformationSet', 2, search_size=2) Traceback (most recent call last): ... ValueError: Additional arguments to an information-set decoder algorithm are only allowed if a specific algorithm is selected by setting the algorithm keyword @@ -800,7 +800,7 @@ def __init__(self, code, number_errors, algorithm=None, **kwargs): sage: from sage.coding.information_set_decoder import LeeBrickellISDAlgorithm sage: A = LeeBrickellISDAlgorithm(C, (0, 2)) - sage: D = C.decoder("InformationSet", 2, A, search_size=3) + sage: D = C.decoder('InformationSet', 2, A, search_size=3) Traceback (most recent call last): ... ValueError: ISD algorithm arguments are not allowed when supplying a constructed ISD algorithm @@ -812,11 +812,11 @@ def __init__(self, code, number_errors, algorithm=None, **kwargs): sage: C = codes.GolayCode(GF(2)) sage: from sage.coding.information_set_decoder import LeeBrickellISDAlgorithm sage: A = LeeBrickellISDAlgorithm(C, (0, 2)) - sage: D = C.decoder("InformationSet", 2, A); D + sage: D = C.decoder('InformationSet', 2, A); D Information-set decoder (Lee-Brickell) for [24, 12, 8] Extended Golay code over GF(2) decoding up to 2 errors - sage: D = C.decoder("InformationSet", (0,2), A); D + sage: D = C.decoder('InformationSet', (0,2), A); D Information-set decoder (Lee-Brickell) for [24, 12, 8] Extended Golay code over GF(2) decoding up to 2 errors - sage: D = C.decoder("InformationSet", 3, A); D + sage: D = C.decoder('InformationSet', 3, A); D Traceback (most recent call last): ... ValueError: number_errors must match that of the passed ISD algorithm @@ -878,10 +878,10 @@ def known_algorithms(dictionary=False): INPUT: - - ``dictionary`` -- optional. If set to ``True``, return a ``dict`` - mapping decoding algorithm name to its class. + - ``dictionary`` -- boolean (default: ``False``); if set to ``True``, + return a ``dict`` mapping decoding algorithm name to its class - OUTPUT: a list of strings or a ``dict`` from string to ISD algorithm class. + OUTPUT: list of strings or a ``dict`` from string to ISD algorithm class EXAMPLES:: @@ -901,7 +901,7 @@ def algorithm(self): EXAMPLES:: sage: C = codes.GolayCode(GF(2)) - sage: D = C.decoder("InformationSet", (2,4), "Lee-Brickell") + sage: D = C.decoder('InformationSet', (2,4), "Lee-Brickell") sage: D.algorithm() ISD Algorithm (Lee-Brickell) for [24, 12, 8] Extended Golay code over GF(2) decoding between 2 and 4 errors @@ -921,9 +921,9 @@ def decode_to_code(self, r): INPUT: - - ``r`` -- a vector in the ambient space of :meth:`decoder.Decoder.code`. + - ``r`` -- a vector in the ambient space of :meth:`decoder.Decoder.code` - OUTPUT: a codeword of :meth:`decoder.Decoder.code`. + OUTPUT: a codeword of :meth:`decoder.Decoder.code` EXAMPLES:: @@ -976,7 +976,7 @@ def decoding_radius(self): EXAMPLES:: sage: C = codes.GolayCode(GF(2)) - sage: D = C.decoder("InformationSet", 2) + sage: D = C.decoder('InformationSet', 2) sage: D.decoding_radius() 2 """ @@ -992,7 +992,7 @@ def decoding_interval(self): EXAMPLES:: sage: C = codes.GolayCode(GF(2)) - sage: D = C.decoder("InformationSet", 2) + sage: D = C.decoder('InformationSet', 2) sage: D.decoding_interval() (0, 2) """ @@ -1000,12 +1000,12 @@ def decoding_interval(self): def _repr_(self): r""" - Returns a string representation of this decoding algorithm. + Return a string representation of this decoding algorithm. EXAMPLES:: sage: C = codes.GolayCode(GF(2)) - sage: D = C.decoder("InformationSet", 2) + sage: D = C.decoder('InformationSet', 2) sage: D Information-set decoder (Lee-Brickell) for [24, 12, 8] Extended Golay code over GF(2) decoding up to 2 errors """ @@ -1013,13 +1013,13 @@ def _repr_(self): def _latex_(self): r""" - Returns a latex representation of this decoding algorithm. + Return a latex representation of this decoding algorithm. EXAMPLES:: sage: C = codes.GolayCode(GF(2)) sage: from sage.coding.information_set_decoder import LeeBrickellISDAlgorithm - sage: D = C.decoder("InformationSet", 2) + sage: D = C.decoder('InformationSet', 2) sage: latex(D) \textnormal{Information-set decoder (Lee-Brickell) for }[24, 12, 8] \textnormal{ Extended Golay Code over } \Bold{F}_{2} \textnormal{decoding up to 2 errors} """ diff --git a/src/sage/coding/kasami_codes.pyx b/src/sage/coding/kasami_codes.pyx index ef70ec676fd..835806fd808 100644 --- a/src/sage/coding/kasami_codes.pyx +++ b/src/sage/coding/kasami_codes.pyx @@ -90,10 +90,10 @@ class KasamiCode(AbstractLinearCode): INPUT: - - ``s``, ``t`` -- (integer) the parameters of the Kasami code + - ``s``, ``t`` -- integer; the parameters of the Kasami code - - ``extended`` -- (default: ``True``) if set to ``True``, - creates an extended Kasami code. + - ``extended`` -- boolean (default: ``True``); if set to ``True``, + creates an extended Kasami code EXAMPLES:: diff --git a/src/sage/coding/linear_code.py b/src/sage/coding/linear_code.py index 91e2855fd79..a9e3813b474 100644 --- a/src/sage/coding/linear_code.py +++ b/src/sage/coding/linear_code.py @@ -18,7 +18,7 @@ parity check matrix for `C`. We commonly endow `F^n` with the Hamming metric, i.e. the weight of a vector is -the number of non-zero elements in it. The central operation of a linear code +the number of nonzero elements in it. The central operation of a linear code is then "decoding": given a linear code `C \subset F^n` and a "received word" `r \in F^n` , retrieve the codeword `c \in C` such that the Hamming distance between `r` and `c` is minimal. @@ -253,9 +253,7 @@ def _dump_code_in_leon_format(C): - ``C`` -- a linear code (over GF(p), p < 11) - OUTPUT: - - - Absolute path to the file written + OUTPUT: absolute path to the file written EXAMPLES:: @@ -272,7 +270,6 @@ def _dump_code_in_leon_format(C): )); FINISH; sage: f.close() - """ from sage.misc.temporary_file import tmp_filename F = C.base_ring() @@ -346,14 +343,13 @@ class AbstractLinearCode(AbstractLinearCodeNoMetric): A lot of methods of the abstract class rely on the knowledge of a generator matrix. It is thus strongly recommended to set an encoder with a generator matrix implemented as a default encoder. - """ _registered_encoders = {} _registered_decoders = {} def __init__(self, base_field, length, default_encoder_name, default_decoder_name): """ - Initializes mandatory parameters that any linear code shares. + Initialize mandatory parameters that any linear code shares. This method only exists for inheritance purposes as it initializes parameters that need to be known by every linear code. The class @@ -441,19 +437,19 @@ def _an_element_(self): """ return self.gens()[0] - def automorphism_group_gens(self, equivalence="semilinear"): + def automorphism_group_gens(self, equivalence='semilinear'): r""" Return generators of the automorphism group of ``self``. INPUT: - - ``equivalence`` (optional) -- which defines the acting group, either + - ``equivalence`` -- (optional) defines the acting group, either - * ``"permutational"`` + * ``'permutational'`` - * ``"linear"`` + * ``'linear'`` - * ``"semilinear"`` + * ``'semilinear'`` OUTPUT: @@ -486,7 +482,7 @@ def automorphism_group_gens(self, equivalence="semilinear"): Ring endomorphism of Finite Field in z of size 2^2 Defn: z |--> z)], 362880) - sage: C.automorphism_group_gens(equivalence="linear") + sage: C.automorphism_group_gens(equivalence='linear') ([((z, 1, z + 1, z + 1, 1, z + 1, z, 1, z + 1, z + 1, 1, z, 1, z + 1, z, 1, z, 1, z + 1, 1, 1); (1,12,11,10,6,8,9,20,13,21,5,14,3,16,17,19,7,4,2,15,18), @@ -503,7 +499,7 @@ def automorphism_group_gens(self, equivalence="semilinear"): Ring endomorphism of Finite Field in z of size 2^2 Defn: z |--> z)], 181440) - sage: C.automorphism_group_gens(equivalence="permutational") + sage: C.automorphism_group_gens(equivalence='permutational') ([((1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1); (1,11)(3,10)(4,9)(5,7)(12,21)(14,20)(15,19)(16,17), Ring endomorphism of Finite Field in z of size 2^2 @@ -579,7 +575,7 @@ def assmus_mattson_designs(self, t, mode=None): `C=C^*` in this case, so this info is extraneous). The test fails to produce 6-designs (ie, the hypotheses of the theorem fail to hold, not that the 6-designs definitely don't exist). The command - ``assmus_mattson_designs(C,5,mode="verbose")`` returns the same value + ``assmus_mattson_designs(C,5,mode='verbose')`` returns the same value but prints out more detailed information. The second example below illustrates the blocks of the 5-(24, 8, 1) @@ -636,10 +632,10 @@ def assmus_mattson_designs(self, t, mode=None): # S. Pancratz, 19 Jan 2010: In the doctests below, I removed the example # ``C.binomial_moment(3)``, which was also marked as ``#long``. This way, # we shorten the doctests time while still maintaining a zero and a - # non-zero example. + # nonzero example. def binomial_moment(self, i): r""" - Return the i-th binomial moment of the `[n,k,d]_q`-code `C`: + Return the `i`-th binomial moment of the `[n,k,d]_q`-code `C`: .. MATH:: @@ -734,7 +730,7 @@ def _canonize(self, equivalence): from sage.coding.codecan.autgroup_can_label import LinearCodeAutGroupCanLabel return LinearCodeAutGroupCanLabel(self, algorithm_type=equivalence) - def canonical_representative(self, equivalence="semilinear"): + def canonical_representative(self, equivalence='semilinear'): r""" Compute a canonical orbit representative under the action of the semimonomial transformation group. @@ -747,13 +743,13 @@ def canonical_representative(self, equivalence="semilinear"): INPUT: - - ``equivalence`` (optional) -- which defines the acting group, either + - ``equivalence`` -- (optional) defines the acting group, either - * ``"permutational"`` + * ``'permutational'`` - * ``"linear"`` + * ``'linear'`` - * ``"semilinear"`` + * ``'semilinear'`` OUTPUT: @@ -927,8 +923,8 @@ def covering_radius(self): is limited to computing with fields of size at most 256 """ from sage.libs.gap.libgap import libgap - GapPackage("guava", spkg="gap_packages").require() - libgap.LoadPackage("guava") + GapPackage('guava', spkg='gap_packages').require() + libgap.LoadPackage('guava') F = self.base_ring() if F.cardinality() > 256: raise NotImplementedError("the GAP algorithm that Sage is using " @@ -1043,7 +1039,7 @@ def direct_sum(self, other): def juxtapose(self, other): """ - Juxtaposition of ``self`` and ``other`` + Juxtaposition of ``self`` and ``other``. The two codes must have equal dimension. @@ -1114,7 +1110,6 @@ def product_code(self, other): True sage: A.minimum_distance() == C.minimum_distance()*D.minimum_distance() # needs sage.libs.gap True - """ G1 = self.generator_matrix() G2 = other.generator_matrix() @@ -1286,7 +1281,7 @@ def is_permutation_equivalent(self,other,algorithm=None): [7, 4] Hamming Code over GF(2) sage: C1.is_permutation_equivalent(C2) True - sage: C1.is_permutation_equivalent(C2, algorithm="verbose") # needs sage.groups + sage: C1.is_permutation_equivalent(C2, algorithm='verbose') # needs sage.groups (True, (3,4)(5,7,6)) sage: C1 = codes.random_linear_code(GF(2), 10, 5) sage: C2 = codes.random_linear_code(GF(3), 10, 5) @@ -1318,7 +1313,7 @@ def is_permutation_equivalent(self,other,algorithm=None): def is_galois_closed(self): r""" - Checks if ``self`` is equal to its Galois closure. + Check if ``self`` is equal to its Galois closure. EXAMPLES:: @@ -1350,22 +1345,20 @@ def minimum_distance(self, algorithm=None): .. NOTE:: - When using GAP, this raises a :class:`NotImplementedError` if + When using GAP, this raises a :exc:`NotImplementedError` if the base field of the code has size greater than 256 due to limitations in GAP. INPUT: - - ``algorithm`` -- (default: ``None``) the name of the algorithm to use - to perform minimum distance computation. ``algorithm`` can be: + - ``algorithm`` -- (default: ``None``) the name of the algorithm to use + to perform minimum distance computation. ``algorithm`` can be: - - ``None``, to use GAP methods (but not Guava) + - ``None``, to use GAP methods (but not Guava) - - ``"Guava"``, to use the optional GAP package Guava + - ``'guava'``, to use the optional GAP package Guava - OUTPUT: - - - Integer, minimum distance of this code + OUTPUT: integer; minimum distance of this code EXAMPLES:: @@ -1378,10 +1371,10 @@ def minimum_distance(self, algorithm=None): If ``algorithm`` is provided, then the minimum distance will be recomputed even if there is a stored value from a previous run.:: - sage: C.minimum_distance(algorithm="gap") # needs sage.libs.gap + sage: C.minimum_distance(algorithm='gap') # needs sage.libs.gap 3 sage: libgap.SetAllInfoLevels(0) # to suppress extra info messages # needs sage.libs.gap - sage: C.minimum_distance(algorithm="guava") # optional - gap_package_guava + sage: C.minimum_distance(algorithm='guava') # optional - gap_package_guava ...3 TESTS:: @@ -1401,13 +1394,13 @@ def minimum_distance(self, algorithm=None): NotImplementedError: the GAP algorithm that Sage is using is limited to computing with fields of size at most 256 """ - if algorithm == "guava": - GapPackage("guava", spkg="gap_packages").require() + if algorithm == 'guava': + GapPackage('guava', spkg='gap_packages').require() # If the minimum distance has already been computed or provided by # the user then simply return the stored value. # This is done only if algorithm is None. - if algorithm not in (None, "gap", "guava"): + if algorithm not in (None, 'gap', 'guava'): raise ValueError("The algorithm argument must be one of None, " "'gap' or 'guava'; got '{0}'".format(algorithm)) @@ -1419,9 +1412,9 @@ def minimum_distance(self, algorithm=None): "of size at most 256") G = self.generator_matrix() - if (q == 2 or q == 3) and algorithm == "guava": + if (q == 2 or q == 3) and algorithm == 'guava': from sage.libs.gap.libgap import libgap - libgap.LoadPackage("guava") + libgap.LoadPackage('guava') C = libgap(G).GeneratorMatCode(libgap(F)) d = C.MinimumWeight() return ZZ(d) @@ -1433,10 +1426,10 @@ def _minimum_weight_codeword(self, algorithm=None): INPUT: - - ``algorithm`` -- (default: ``None``) the name of the algorithm to use - to perform minimum weight codeword search. If set to ``None``, - a search using GAP methods will be done. ``algorithm`` can be: - - ``"Guava"``, which will use optional GAP package Guava + - ``algorithm`` -- (default: ``None``) the name of the algorithm to use + to perform minimum weight codeword search. If set to ``None``, + a search using GAP methods will be done. ``algorithm`` can be + ``'guava'``, which will use the optional GAP package Guava. REMARKS: @@ -1472,9 +1465,9 @@ def _minimum_weight_codeword(self, algorithm=None): current_randstate().set_seed_gap() - if algorithm == "guava": - GapPackage("guava", spkg="gap_packages").require() - libgap.LoadPackage("guava") + if algorithm == 'guava': + GapPackage('guava', spkg='gap_packages').require() + libgap.LoadPackage('guava') C = Gmat.GeneratorMatCode(F) cg = C.MinimumDistanceCodeword() c = [cg[j].sage(ring=F) for j in range(n)] @@ -1538,7 +1531,7 @@ def module_composition_factors(self, gp): # M_gap.MTX.CompositionFactors() yet return libgap.eval('MTX.CompositionFactors('+str(M_gap)+')') - def permutation_automorphism_group(self, algorithm="partition"): + def permutation_automorphism_group(self, algorithm='partition'): r""" If `C` is an `[n,k,d]` code over `F`, this function computes the subgroup `Aut(C) \subset S_n` of all permutation automorphisms of `C`. @@ -1552,21 +1545,19 @@ def permutation_automorphism_group(self, algorithm="partition"): INPUT: - - ``algorithm`` -- If ``"gap"`` then GAP's MatrixAutomorphism function + - ``algorithm`` -- if ``'gap'`` then GAP's MatrixAutomorphism function (written by Thomas Breuer) is used. The implementation combines an idea of mine with an improvement suggested by Cary Huffman. If - ``"gap+verbose"`` then code-theoretic data is printed out at - several stages of the computation. If ``"partition"`` then the + ``'gap+verbose'`` then code-theoretic data is printed out at + several stages of the computation. If ``'partition'`` then the (default) partition refinement algorithm of Robert Miller is used. - Finally, if ``"codecan"`` then the partition refinement algorithm + Finally, if ``'codecan'`` then the partition refinement algorithm of Thomas Feulner is used, which also computes a canonical representative of ``self`` (call :meth:`~sage.coding.linear_code.LinearCode.canonical_representative` to access it). - OUTPUT: - - - Permutation automorphism group + OUTPUT: permutation automorphism group EXAMPLES:: @@ -1615,19 +1606,19 @@ def permutation_automorphism_group(self, algorithm="partition"): 9999360 sage: C = codes.HammingCode(GF(3), 2); C [4, 2] Hamming Code over GF(3) - sage: C.permutation_automorphism_group(algorithm="partition") + sage: C.permutation_automorphism_group(algorithm='partition') Permutation Group with generators [(1,3,4)] sage: C = codes.HammingCode(GF(4,"z"), 2); C [5, 3] Hamming Code over GF(4) - sage: G = C.permutation_automorphism_group(algorithm="partition"); G + sage: G = C.permutation_automorphism_group(algorithm='partition'); G Permutation Group with generators [(1,3)(4,5), (1,4)(3,5)] - sage: GG = C.permutation_automorphism_group(algorithm="codecan") # long time + sage: GG = C.permutation_automorphism_group(algorithm='codecan') # long time sage: GG == G # long time True - sage: C.permutation_automorphism_group(algorithm="gap") # optional - gap_package_guava + sage: C.permutation_automorphism_group(algorithm='gap') # optional - gap_package_guava Permutation Group with generators [(1,3)(4,5), (1,4)(3,5)] sage: C = codes.GolayCode(GF(3), True) - sage: C.permutation_automorphism_group(algorithm="gap") # optional - gap_package_guava + sage: C.permutation_automorphism_group(algorithm='gap') # optional - gap_package_guava Permutation Group with generators [(5,7)(6,11)(8,9)(10,12), (4,6,11)(5,8,12)(7,10,9), (3,4)(6,8)(9,11)(10,12), (2,3)(6,11)(8,12)(9,10), (1,2)(5,10)(7,12)(8,9)] @@ -1640,7 +1631,7 @@ def permutation_automorphism_group(self, algorithm="partition"): Using the 132 codewords of weight 5 Supergroup size: 39916800 in addition to the output of - ``C.permutation_automorphism_group(algorithm="gap")``. + ``C.permutation_automorphism_group(algorithm='gap')``. """ F = self.base_ring() q = F.order() @@ -1648,7 +1639,7 @@ def permutation_automorphism_group(self, algorithm="partition"): n = len(G.columns()) if "gap" in algorithm: from sage.libs.gap.libgap import libgap - GapPackage("guava", spkg="gap_packages").require() + GapPackage('guava', spkg='gap_packages').require() libgap.LoadPackage('guava') wts = self.weight_distribution() # bottleneck 1 nonzerowts = [i for i in range(len(wts)) if wts[i] != 0] @@ -1725,11 +1716,9 @@ def punctured(self, L): INPUT: - - ``L`` -- List of positions to puncture + - ``L`` -- list of positions to puncture - OUTPUT: - - - an instance of :class:`sage.coding.punctured_code` + OUTPUT: an instance of :class:`sage.coding.punctured_code` EXAMPLES:: @@ -1742,11 +1731,11 @@ def punctured(self, L): def _punctured_form(self, points): r""" - Return a representation of self as a :class:`LinearCode` punctured in ``points``. + Return a representation of ``self`` as a :class:`LinearCode` punctured in ``points``. INPUT: - - ``points`` -- a set of positions where to puncture ``self`` + - ``points`` -- set of positions where to puncture ``self`` EXAMPLES:: @@ -1790,11 +1779,9 @@ def shortened(self, L): INPUT: - - ``L`` -- Subset of `\{1,...,n\}`, where `n` is the length of this code - - OUTPUT: + - ``L`` -- subset of `\{1,...,n\}`, where `n` is the length of this code - - Linear code, the shortened code described above + OUTPUT: linear code, the shortened code described above EXAMPLES:: @@ -1816,15 +1803,13 @@ def weight_distribution(self, algorithm=None): INPUT: - - ``algorithm`` -- (default: ``None``) If set to ``"gap"``, - call GAP. If set to ``"leon"``, call the option GAP package GUAVA and + - ``algorithm`` -- (default: ``None``) if set to ``'gap'``, + call GAP. If set to ``'leon'``, call the option GAP package GUAVA and call a function therein by Jeffrey Leon (see warning below). If set to - ``"binary"``, use an algorithm optimized for binary codes. The default - is to use ``"binary"`` for binary codes and ``"gap"`` otherwise. + ``'binary'``, use an algorithm optimized for binary codes. The default + is to use ``'binary'`` for binary codes and ``'gap'`` otherwise. - OUTPUT: - - - A list of non-negative integers: the weight distribution. + OUTPUT: list of nonnegative integers; the weight distribution .. WARNING:: @@ -1848,27 +1833,26 @@ def weight_distribution(self, algorithm=None): [1, 0, 0, 30, 15, 18] sage: C = codes.HammingCode(GF(2), 3); C [7, 4] Hamming Code over GF(2) - sage: C.weight_distribution(algorithm="leon") # optional - gap_package_guava + sage: C.weight_distribution(algorithm='leon') # optional - gap_package_guava [1, 0, 0, 7, 7, 0, 0, 1] - sage: C.weight_distribution(algorithm="gap") # needs sage.libs.gap + sage: C.weight_distribution(algorithm='gap') # needs sage.libs.gap [1, 0, 0, 7, 7, 0, 0, 1] - sage: C.weight_distribution(algorithm="binary") + sage: C.weight_distribution(algorithm='binary') [1, 0, 0, 7, 7, 0, 0, 1] sage: # optional - gap_package_guava sage: C = codes.HammingCode(GF(3), 3); C [13, 10] Hamming Code over GF(3) - sage: C.weight_distribution() == C.weight_distribution(algorithm="leon") + sage: C.weight_distribution() == C.weight_distribution(algorithm='leon') True sage: C = codes.HammingCode(GF(5), 2); C [6, 4] Hamming Code over GF(5) - sage: C.weight_distribution() == C.weight_distribution(algorithm="leon") + sage: C.weight_distribution() == C.weight_distribution(algorithm='leon') True sage: C = codes.HammingCode(GF(7), 2); C [8, 6] Hamming Code over GF(7) - sage: C.weight_distribution() == C.weight_distribution(algorithm="leon") + sage: C.weight_distribution() == C.weight_distribution(algorithm='leon') True - """ if algorithm is None: if self.base_ring().order() == 2: @@ -1893,7 +1877,7 @@ def weight_distribution(self, algorithm=None): # The GAP command DirectoriesPackageLibrary tells the location of the latest # version of the Guava libraries, so gives us the location of the Guava binaries too. from sage.libs.gap.libgap import libgap - guava_bin_dir = libgap.DirectoriesPackagePrograms("guava")[0].Filename("").sage() + guava_bin_dir = libgap.DirectoriesPackagePrograms('guava')[0].Filename("").sage() input = _dump_code_in_leon_format(self) + "::code" lines = subprocess.check_output([os.path.join(guava_bin_dir, 'wtdist'), input]) # to use the already present output parser @@ -1916,9 +1900,7 @@ def support(self): Return the set of indices `j` where `A_j` is nonzero, where `A_j` is the number of codewords in ``self`` of Hamming weight `j`. - OUTPUT: - - - List of integers + OUTPUT: list of integers EXAMPLES:: @@ -1943,25 +1925,23 @@ def weight_enumerator(self, names=None, bivariate=True): INPUT: - - ``names`` -- (default: ``"xy"``) The names of the variables in the + - ``names`` -- (default: ``'xy'``) the names of the variables in the homogeneous polynomial. Can be given as a single string of length 2, or a single string with a comma, or as a tuple or list of two strings. - - ``bivariate`` -- (default: ``True``) Whether to return a bivariate, - homogeneous polynomial or just a univariate polynomial. If set to - ``False``, then ``names`` will be interpreted as a single variable - name and default to ``"x"``. - - OUTPUT: + - ``bivariate`` -- boolean (default: ``True``); whether to return a + bivariate, homogeneous polynomial or just a univariate polynomial. If + set to ``False``, then ``names`` will be interpreted as a single + variable name and default to ``'x'``. - - The weight enumerator polynomial over `\ZZ`. + OUTPUT: the weight enumerator polynomial over `\ZZ` EXAMPLES:: sage: C = codes.HammingCode(GF(2), 3) sage: C.weight_enumerator() x^7 + 7*x^4*y^3 + 7*x^3*y^4 + y^7 - sage: C.weight_enumerator(names="st") + sage: C.weight_enumerator(names='st') s^7 + 7*s^4*t^3 + 7*s^3*t^4 + t^7 sage: C.weight_enumerator(names="var1, var2") var1^7 + 7*var1^4*var2^3 + 7*var1^3*var2^4 + var2^7 @@ -1992,7 +1972,7 @@ def weight_enumerator(self, names=None, bivariate=True): x, = R.gens() return sum(spec[i]*x**i for i in range(n+1)) - def zeta_polynomial(self, name="T"): + def zeta_polynomial(self, name='T'): r""" Return the Duursma zeta polynomial of this code. @@ -2001,11 +1981,9 @@ def zeta_polynomial(self, name="T"): INPUT: - - ``name`` -- String, variable name (default: ``"T"``) + - ``name`` -- string (default: ``'T'``); variable name - OUTPUT: - - - Polynomial over `\QQ` + OUTPUT: polynomial over `\QQ` EXAMPLES:: @@ -2063,13 +2041,13 @@ def zeta_polynomial(self, name="T"): P = sum([P_coeffs[i]*T**i for i in range(r+1)]) return RT(P) / RT(P)(1) - def zeta_function(self, name="T"): + def zeta_function(self, name='T'): r""" Return the Duursma zeta function of the code. INPUT: - - ``name`` -- String, variable name (default: ``"T"``) + - ``name`` -- string (default: ``'T'``); variable name OUTPUT: @@ -2223,7 +2201,7 @@ class LinearCode(AbstractLinearCode): - ``generator`` -- a generator matrix over a finite field (``G`` can be defined over a finite ring but the matrices over that ring must have - certain attributes, such as ``rank``); or a code over a finite field + certain attributes, such as ``rank``) or a code over a finite field - ``d`` -- (default: ``None``) the minimum distance of the code @@ -2344,7 +2322,7 @@ def __init__(self, generator, d=None): sage: C = LinearCode(G) Traceback (most recent call last): ... - ValueError: this linear code contains no non-zero vector + ValueError: this linear code contains no nonzero vector """ base_ring = generator.base_ring() @@ -2362,7 +2340,7 @@ def __init__(self, generator, d=None): from sage.matrix.constructor import matrix generator = matrix(base_ring, basis) if generator.nrows() == 0: - raise ValueError("this linear code contains no non-zero vector") + raise ValueError("this linear code contains no nonzero vector") except AttributeError: # Assume input is an AbstractLinearCode, extract its generator matrix generator = generator.generator_matrix() @@ -2422,7 +2400,7 @@ def generator_matrix(self, encoder_name=None, **kwargs): will be returned if default value is kept. - ``kwargs`` -- all additional arguments are forwarded to the construction of the - encoder that is used. + encoder that is used EXAMPLES:: @@ -2451,7 +2429,7 @@ class LinearCodeGeneratorMatrixEncoder(Encoder): INPUT: - - ``code`` -- The associated :class:`LinearCode` of this encoder. + - ``code`` -- the associated :class:`LinearCode` of this encoder """ def __init__(self, code): @@ -2468,7 +2446,7 @@ def __init__(self, code): def __eq__(self, other): r""" - Tests equality between LinearCodeGeneratorMatrixEncoder objects. + Test equality between LinearCodeGeneratorMatrixEncoder objects. EXAMPLES:: @@ -2535,7 +2513,7 @@ def generator_matrix(self): class LinearCodeSyndromeDecoder(Decoder): r""" - Constructs a decoder for Linear Codes based on syndrome lookup table. + Construct a decoder for Linear Codes based on syndrome lookup table. The decoding algorithm works as follows: @@ -2566,7 +2544,7 @@ class LinearCodeSyndromeDecoder(Decoder): INPUT: - - ``code`` -- A code associated to this decoder + - ``code`` -- a code associated to this decoder - ``maximum_error_weight`` -- (default: ``None``) the maximum number of errors to look for when building the table. An error is raised if it is @@ -2703,7 +2681,7 @@ def __init__(self, code, maximum_error_weight=None): def __eq__(self, other): r""" - Tests equality between LinearCodeSyndromeDecoder objects. + Test equality between LinearCodeSyndromeDecoder objects. EXAMPLES:: @@ -2719,7 +2697,7 @@ def __eq__(self, other): def __hash__(self): """ - Return the hash of self. + Return the hash of ``self``. EXAMPLES:: @@ -2762,7 +2740,7 @@ def _latex_(self): @cached_method def _build_lookup_table(self): r""" - Builds lookup table for all possible error patterns of weight up to :meth:`maximum_error_weight`. + Build lookup table for all possible error patterns of weight up to :meth:`maximum_error_weight`. EXAMPLES:: @@ -2889,9 +2867,7 @@ def decode_to_code(self, r): - ``r`` -- a codeword of ``self`` - OUTPUT: - - - a vector of ``self``'s message space + OUTPUT: a vector of ``self``'s message space EXAMPLES:: @@ -2984,7 +2960,7 @@ class LinearCodeNearestNeighborDecoder(Decoder): INPUT: - - ``code`` -- A code associated to this decoder + - ``code`` -- a code associated to this decoder """ def __init__(self, code): @@ -3001,7 +2977,7 @@ def __init__(self, code): def __eq__(self, other): r""" - Tests equality between LinearCodeNearestNeighborDecoder objects. + Test equality between LinearCodeNearestNeighborDecoder objects. EXAMPLES:: @@ -3050,9 +3026,7 @@ def decode_to_code(self, r): - ``r`` -- a codeword of ``self`` - OUTPUT: - - - a vector of ``self``'s message space + OUTPUT: a vector of ``self``'s message space EXAMPLES:: diff --git a/src/sage/coding/linear_code_no_metric.py b/src/sage/coding/linear_code_no_metric.py index bd7727b7794..49c30a415c8 100644 --- a/src/sage/coding/linear_code_no_metric.py +++ b/src/sage/coding/linear_code_no_metric.py @@ -140,7 +140,7 @@ class AbstractLinearCodeNoMetric(AbstractCode, Module): def __init__(self, base_field, length, default_encoder_name, default_decoder_name, metric='Hamming'): """ - Initializes mandatory parameters that any linear code shares. + Initialize mandatory parameters that any linear code shares. This method only exists for inheritance purposes as it initializes parameters that need to be known by every linear code. The class @@ -231,7 +231,7 @@ def generator_matrix(self, encoder_name=None, **kwargs): will be used if default value is kept. - ``kwargs`` -- all additional arguments are forwarded to the construction of the - encoder that is used. + encoder that is used EXAMPLES:: @@ -246,7 +246,7 @@ def generator_matrix(self, encoder_name=None, **kwargs): def __eq__(self, other): r""" - Tests equality between two linear codes. + Test equality between two linear codes. EXAMPLES:: @@ -282,9 +282,10 @@ def __eq__(self, other): def __ne__(self, other): r""" - Tests inequality of ``self`` and ``other``. + Test inequality of ``self`` and ``other``. - This is a generic implementation, which returns the inverse of ``__eq__`` for self. + This is a generic implementation, which returns the inverse of + ``__eq__`` for ``self``. EXAMPLES:: @@ -390,9 +391,7 @@ def basis(self): r""" Return a basis of ``self``. - OUTPUT: - - - ``Sequence`` -- an immutable sequence whose universe is ambient space of ``self``. + OUTPUT: ``Sequence`` -- an immutable sequence whose universe is ambient space of ``self`` EXAMPLES:: @@ -463,9 +462,7 @@ def syndrome(self, r): - ``r`` -- a vector of the same length as ``self`` - OUTPUT: - - - a column vector + OUTPUT: a column vector EXAMPLES:: @@ -497,7 +494,8 @@ def syndrome(self, r): def __contains__(self, v): r""" - Return True if `v` can be coerced into ``self``. Otherwise, returns False. + Return ``True`` if `v` can be coerced into ``self``. + Otherwise, return ``False``. EXAMPLES:: @@ -560,14 +558,12 @@ def standard_form(self, return_permutation=True): INPUT: - - ``return_permutation`` -- (default: ``True``) if ``True``, the column - permutation which brings ``self`` into the returned code is also - returned. + - ``return_permutation`` -- boolean (default: ``True``); if ``True``, + the column permutation which brings ``self`` into the returned code + is also returned - OUTPUT: - - - A :class:`LinearCode` whose :meth:`systematic_generator_matrix` is - guaranteed to be of the form `[I \vert A]`. + OUTPUT: a :class:`LinearCode` whose :meth:`systematic_generator_matrix` + is guaranteed to be of the form `[I \vert A]`. EXAMPLES:: @@ -656,9 +652,7 @@ def information_set(self): is called an information set if the corresponding columns form a square matrix of full rank. - OUTPUT: - - - Information set of a systematic generator matrix of the code. + OUTPUT: information set of a systematic generator matrix of the code EXAMPLES:: @@ -682,10 +676,7 @@ def is_information_set(self, positions): - A list of positions, i.e. integers in the range 0 to `n-1` where `n` is the length of ``self``. - OUTPUT: - - - A boolean indicating whether the positions form an information set. - + OUTPUT: boolean indicating whether the positions form an information set EXAMPLES:: @@ -722,7 +713,6 @@ def __iter__(self): sage: L = list(C) sage: L[10].is_immutable() True - """ from sage.modules.finite_submodule_iter import \ FiniteFieldsubspace_iterator @@ -755,7 +745,7 @@ def __getitem__(self, i): ``[i*a^0 * G[0] + a^0*G[1] for i in range(p)]``, and so on. - Hence the `i`-th element can be obtained by the p-adic expansion + Hence the `i`-th element can be obtained by the `p`-adic expansion of `i` as ``[i_0, i_1, ...,i_{m-1}, i_m, i_{m+1}, ..., i_{km-1}].`` The element that is generated is: @@ -800,7 +790,6 @@ def __getitem__(self, i): sage: C[0].is_immutable() True - """ # IMPORTANT: If the __iter__() function implementation is changed # then the implementation here must also be changed so that @@ -1050,14 +1039,14 @@ class LinearCodeSystematicEncoder(Encoder): INPUT: - - ``code`` -- The associated code of this encoder. + - ``code`` -- the associated code of this encoder - ``systematic_positions`` -- (default: ``None``) the positions in codewords that should correspond to the message symbols. A list of `k` distinct integers in the range 0 to `n-1` where `n` is the length of the code and `k` its - dimension. The 0th symbol of a message will then be at position + dimension. The `0`-th symbol of a message will then be at position ``systematic_positions[0]``, the 1st index at position - ``systematic_positions[1]``, etc. A :class:`ValueError` is raised at + ``systematic_positions[1]``, etc. A :exc:`ValueError` is raised at construction time if the supplied indices do not form an information set. EXAMPLES: @@ -1153,7 +1142,7 @@ def __init__(self, code, systematic_positions=None): def __eq__(self, other): r""" - Tests equality between LinearCodeSystematicEncoder objects. + Test equality between LinearCodeSystematicEncoder objects. EXAMPLES:: @@ -1285,7 +1274,7 @@ def generator_matrix(self): def systematic_permutation(self): r""" - Return a permutation which would take the systematic positions into [0,..,k-1] + Return a permutation which would take the systematic positions into [0,..,k-1]. EXAMPLES:: diff --git a/src/sage/coding/linear_rank_metric.py b/src/sage/coding/linear_rank_metric.py index 2c7154c9e42..ff5f0c897b3 100644 --- a/src/sage/coding/linear_rank_metric.py +++ b/src/sage/coding/linear_rank_metric.py @@ -142,8 +142,8 @@ def to_matrix_representation(v, sub_field=None, basis=None): - ``v`` -- a vector over some field `\GF{q^m}` - - ``sub_field`` -- (default: ``None``) a sub field of `\GF{q^m}`. If not - specified, it is the prime subfield `\GF{p}` of `\GF{q^m}`. + - ``sub_field`` -- (default: ``None``) a sub field of `\GF{q^m}`; if not + specified, it is the prime subfield `\GF{p}` of `\GF{q^m}` - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over ``sub_field``. If not specified, given that `q = p^s`, let @@ -235,8 +235,8 @@ def rank_weight(c, sub_field=None, basis=None): - ``c`` -- a vector over some field `\GF{q^m}`; or a matrix over `\GF{q}` - - ``sub_field`` -- (default: ``None``) a sub field of `\GF{q^m}`. If not - specified, it is the prime subfield `\GF{p}` of `\GF{q^m}`. + - ``sub_field`` -- (default: ``None``) a sub field of `\GF{q^m}`; if not + specified, it is the prime subfield `\GF{p}` of `\GF{q^m}` - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over ``sub_field``. If not specified, given that `q = p^s`, let @@ -272,8 +272,8 @@ def rank_distance(a, b, sub_field=None, basis=None): - ``b`` -- a vector over some field `\GF{q^m}` - - ``sub_field`` -- (default: ``None``) a sub field of `\GF{q^m}`. If not - specified, it is the prime subfield `\GF{p}` of `\GF{q^m}`. + - ``sub_field`` -- (default: ``None``) a sub field of `\GF{q^m}`; if not + specified, it is the prime subfield `\GF{p}` of `\GF{q^m}` - ``basis`` -- (default: ``None``) a basis of `\GF{q^m}` as a vector space over ``sub_field``. If not specified, given that `q = p^s`, let @@ -706,7 +706,7 @@ def __init__(self, generator, sub_field=None, basis=None): from sage.matrix.constructor import matrix generator = matrix(base_field, gen_basis) if generator.nrows() == 0: - raise ValueError("this linear code contains no non-zero vector") + raise ValueError("this linear code contains no nonzero vector") except AttributeError: # Assume input is an AbstractLinearRankMetricCode, extract its generator matrix generator = generator.generator_matrix() @@ -759,7 +759,7 @@ def generator_matrix(self, encoder_name=None, **kwargs): will be returned if default value is kept. - ``kwargs`` -- all additional arguments are forwarded to the construction of the - encoder that is used. + encoder that is used EXAMPLES:: @@ -790,7 +790,7 @@ def __init__(self, code): INPUT: - - ``code`` -- A code associated to this decoder + - ``code`` -- a code associated to this decoder EXAMPLES:: @@ -854,9 +854,7 @@ def decode_to_code(self, r): - ``r`` -- a codeword of ``self`` - OUTPUT: - - - a vector of ``self``'s message space + OUTPUT: a vector of ``self``'s message space EXAMPLES:: diff --git a/src/sage/coding/parity_check_code.py b/src/sage/coding/parity_check_code.py index 73e7c9b7816..589c1c6f391 100644 --- a/src/sage/coding/parity_check_code.py +++ b/src/sage/coding/parity_check_code.py @@ -40,9 +40,9 @@ class ParityCheckCode(AbstractLinearCode): INPUT: - - ``base_field`` -- the base field over which ``self`` is defined. + - ``base_field`` -- the base field over which ``self`` is defined - - ``dimension`` -- the dimension of ``self``. + - ``dimension`` -- the dimension of ``self`` EXAMPLES:: @@ -61,9 +61,9 @@ def __init__(self, base_field=GF(2), dimension=7): INPUT: - ``base_field`` -- the base field over which ``self`` is defined - or GF(2) if no base_field. + or GF(2) if no base_field - - ``dimension`` -- the dimension of ``self`` or 7 if no dimension. + - ``dimension`` -- the dimension of ``self`` or 7 if no dimension EXAMPLES:: @@ -148,7 +148,7 @@ class ParityCheckCodeGeneratorMatrixEncoder(LinearCodeGeneratorMatrixEncoder): INPUT: - - ``code`` -- the associated code of this encoder. + - ``code`` -- the associated code of this encoder EXAMPLES:: @@ -212,7 +212,7 @@ class ParityCheckCodeStraightforwardEncoder(Encoder): INPUT: - - ``code`` -- the associated code of this encoder. + - ``code`` -- the associated code of this encoder EXAMPLES:: @@ -290,12 +290,10 @@ def encode(self, message): INPUT: - - ``message`` -- A ``self.code().dimension()``-vector from the message - space of ``self``. + - ``message`` -- a ``self.code().dimension()``-vector from the message + space of ``self`` - OUTPUT: - - - A codeword in associated code of ``self``. + OUTPUT: a codeword in associated code of ``self`` EXAMPLES:: @@ -318,13 +316,11 @@ def unencode_nocheck(self, word): INPUT: - - ``word`` -- A ``self.code().length()``-vector from the ambiant space - of ``self``. - - OUTPUT: + - ``word`` -- a ``self.code().length()``-vector from the ambiant space + of ``self`` - - A vector corresponding to the ``self.code().dimension()``-first - symbols in ``word``. + OUTPUT: a vector corresponding to the ``self.code().dimension()``-first + symbols in ``word`` EXAMPLES:: diff --git a/src/sage/coding/punctured_code.py b/src/sage/coding/punctured_code.py index e7658e18f34..c56dccf3df3 100644 --- a/src/sage/coding/punctured_code.py +++ b/src/sage/coding/punctured_code.py @@ -35,7 +35,7 @@ def _puncture(v, points): - ``v`` -- a vector or a list of vectors - - ``points`` -- a set of integers, or an integer + - ``points`` -- set of integers, or an integer EXAMPLES:: @@ -65,9 +65,9 @@ def _insert_punctured_positions(l, punctured_points, value=None): INPUT: - - ``l`` -- a list + - ``l`` -- list - - ``punctured_points`` -- a set of integers + - ``punctured_points`` -- set of integers - ``value`` -- (default: ``None``) an element to insert in every position given in``punctured_points``. If it is let to ``None``, a random value @@ -98,11 +98,12 @@ class PuncturedCode(AbstractLinearCode): r""" Representation of a punctured code. - - ``C`` -- A linear code + - ``C`` -- a linear code - - ``positions`` -- the positions where ``C`` will be punctured. It can be either an integer - if one need to puncture only one position, a list or a set of positions to puncture. - If the same position is passed several times, it will be considered only once. + - ``positions`` -- the positions where ``C`` will be punctured. It can be + either an integer if one need to puncture only one position, a list or a + set of positions to puncture. If the same position is passed several + times, it will be considered only once. EXAMPLES:: @@ -151,7 +152,7 @@ def __init__(self, C, positions): def __eq__(self, other): r""" - Tests equality between two Punctured codes. + Test equality between two Punctured codes. EXAMPLES:: @@ -246,7 +247,7 @@ def random_element(self, *args, **kwds): INPUT: - ``agrs``, ``kwds`` -- extra positional arguments passed to - :meth:`sage.modules.free_module.random_element`. + :meth:`sage.modules.free_module.random_element` EXAMPLES:: @@ -262,23 +263,22 @@ def random_element(self, *args, **kwds): def encode(self, m, original_encode=False, encoder_name=None, **kwargs): r""" - Transforms an element of the message space into an element of the code. + Transform an element of the message space into an element of the code. INPUT: - - ``m`` -- a vector of the message space of the code. + - ``m`` -- a vector of the message space of the code - - ``original_encode`` -- (default: ``False``) if this is set to ``True``, - ``m`` will be encoded using an Encoder of ``self``'s :meth:`original_code`. - This allow to avoid the computation of a generator matrix for ``self``. + - ``original_encode`` -- boolean (default: ``False``); if this is set + to ``True``, ``m`` will be encoded using an Encoder of ``self``'s + :meth:`original_code`. This allow to avoid the computation of a + generator matrix for ``self``. - - ``encoder_name`` -- (default: ``None``) Name of the encoder which will be used + - ``encoder_name`` -- (default: ``None``) name of the encoder which will be used to encode ``word``. The default encoder of ``self`` will be used if - default value is kept + default value is kept. - OUTPUT: - - - an element of ``self`` + OUTPUT: an element of ``self`` EXAMPLES:: @@ -346,7 +346,7 @@ class PuncturedCodePuncturedMatrixEncoder(Encoder): INPUT: - - ``code`` -- The associated code of this encoder. + - ``code`` -- the associated code of this encoder EXAMPLES:: @@ -437,7 +437,7 @@ class PuncturedCodeOriginalCodeDecoder(Decoder): INPUT: - - ``code`` -- The associated code of this encoder + - ``code`` -- the associated code of this encoder - ``strategy`` -- (default: ``None``) the strategy used to decode. The available strategies are: @@ -480,7 +480,7 @@ class PuncturedCodeOriginalCodeDecoder(Decoder): sage: C = codes.GeneralizedReedSolomonCode(GF(16, 'a').list()[:15], 7) sage: Cp = codes.PuncturedCode(C, 3) - sage: D = codes.decoders.PuncturedCodeOriginalCodeDecoder(Cp, strategy="try-all") + sage: D = codes.decoders.PuncturedCodeOriginalCodeDecoder(Cp, strategy='try-all') sage: "error-erasure" in D.decoder_type() False @@ -491,7 +491,7 @@ class PuncturedCodeOriginalCodeDecoder(Decoder): sage: Cp = codes.PuncturedCode(C, 3) sage: Dor = C.decoder("Gao") sage: D = codes.decoders.PuncturedCodeOriginalCodeDecoder(Cp, original_decoder=Dor, - ....: strategy="error-erasure") + ....: strategy='error-erasure') sage: D.original_decoder() == Dor True """ @@ -579,7 +579,6 @@ def _repr_(self): sage: D = codes.decoders.PuncturedCodeOriginalCodeDecoder(Cp) sage: D Decoder of Puncturing of [15, 7, 9] Reed-Solomon Code over GF(16) on position(s) [3] through Error-Erasure decoder for [15, 7, 9] Reed-Solomon Code over GF(16) - """ return "Decoder of %s through %s" % (self.code(), self.original_decoder()) diff --git a/src/sage/coding/reed_muller_code.py b/src/sage/coding/reed_muller_code.py index 6e35d530c39..64258f48927 100644 --- a/src/sage/coding/reed_muller_code.py +++ b/src/sage/coding/reed_muller_code.py @@ -79,13 +79,13 @@ def _multivariate_polynomial_interpolation(evaluation, order, polynomial_ring): INPUT: - - ``evaluation`` -- A vector or a list of evaluation of the polynomial at all the points. + - ``evaluation`` -- a vector or a list of evaluation of the polynomial at all the points - - ``num_of_var`` -- The number of variables used in the polynomial to interpolate + - ``num_of_var`` -- the number of variables used in the polynomial to interpolate - - ``order`` -- The degree of the polynomial to interpolate + - ``order`` -- the degree of the polynomial to interpolate - - ``polynomial_ring`` -- The Polynomial Ring the polynomial in question is from + - ``polynomial_ring`` -- the Polynomial Ring the polynomial in question is from EXAMPLES:: @@ -143,12 +143,12 @@ def ReedMullerCode(base_field, order, num_of_var): INPUT: - - ``base_field`` -- The finite field `F` over which the code is built. + - ``base_field`` -- the finite field `F` over which the code is built - - ``order`` -- The order of the Reed-Muller Code, which is the maximum - degree of the polynomial to be used in the code. + - ``order`` -- the order of the Reed-Muller Code, which is the maximum + degree of the polynomial to be used in the code - - ``num_of_var`` -- The number of variables used in polynomial. + - ``num_of_var`` -- the number of variables used in polynomial .. WARNING:: @@ -205,12 +205,12 @@ class directly, as :meth:`ReedMullerCode` creates either a binary or a INPUT: - - ``base_field`` -- A finite field, which is the base field of the code. + - ``base_field`` -- a finite field, which is the base field of the code - - ``order`` -- The order of the Reed-Muller Code, i.e., the maximum degree - of the polynomial to be used in the code. + - ``order`` -- the order of the Reed-Muller Code, i.e., the maximum degree + of the polynomial to be used in the code - - ``num_of_var`` -- The number of variables used in polynomial. + - ``num_of_var`` -- the number of variables used in polynomial .. WARNING:: @@ -354,7 +354,7 @@ def _latex_(self): def __eq__(self, other): r""" - Tests equality between Reed-Muller Code objects. + Test equality between Reed-Muller Code objects. EXAMPLES:: @@ -389,10 +389,10 @@ class directly, as :meth:`ReedMullerCode` creates either a binary or a INPUT: - - ``order`` -- The order of the Reed-Muller Code, i.e., the maximum degree - of the polynomial to be used in the code. + - ``order`` -- the order of the Reed-Muller Code, i.e., the maximum degree + of the polynomial to be used in the code - - ``num_of_var`` -- The number of variables used in the polynomial. + - ``num_of_var`` -- the number of variables used in the polynomial EXAMPLES: @@ -508,7 +508,7 @@ def _latex_(self): def __eq__(self, other): r""" - Tests equality between Reed-Muller Code objects. + Test equality between Reed-Muller Code objects. EXAMPLES:: @@ -548,7 +548,7 @@ class ReedMullerVectorEncoder(Encoder): INPUT: - - ``code`` -- The associated code of this encoder. + - ``code`` -- the associated code of this encoder EXAMPLES:: @@ -623,7 +623,7 @@ def _latex_(self): def __eq__(self, other): r""" - Tests equality between ReedMullerVectorEncoder objects. + Test equality between ReedMullerVectorEncoder objects. EXAMPLES:: @@ -642,7 +642,7 @@ def __eq__(self, other): @cached_method def generator_matrix(self): r""" - Return a generator matrix of ``self`` + Return a generator matrix of ``self``. EXAMPLES:: @@ -717,11 +717,11 @@ class ReedMullerPolynomialEncoder(Encoder): INPUT: - - ``code`` -- The associated code of this encoder. + - ``code`` -- the associated code of this encoder - - ``polynomial_ring`` -- (default:``None``) The polynomial ring from which - the message is chosen. If this is set to ``None``, a polynomial ring in - `x` will be built from the code parameters. + - ``polynomial_ring`` -- (default: ``None``) the polynomial ring from which + the message is chosen; if this is set to ``None``, a polynomial ring in + `x` will be built from the code parameters EXAMPLES:: @@ -822,7 +822,7 @@ def _latex_(self): def __eq__(self, other): r""" - Tests equality between ReedMullerVectorEncoder objects. + Test equality between ReedMullerVectorEncoder objects. EXAMPLES:: @@ -840,16 +840,14 @@ def __eq__(self, other): def encode(self, p): r""" - Transforms the polynomial ``p`` into a codeword of :meth:`code`. + Transform the polynomial ``p`` into a codeword of :meth:`code`. INPUT: - - ``p`` -- A polynomial from the message space of ``self`` of degree - less than ``self.code().order()``. + - ``p`` -- a polynomial from the message space of ``self`` of degree + less than ``self.code().order()`` - OUTPUT: - - - A codeword in associated code of ``self`` + OUTPUT: a codeword in associated code of ``self`` EXAMPLES:: @@ -902,7 +900,7 @@ def unencode_nocheck(self, c): INPUT: - - ``c`` -- A codeword of :meth:`code`. + - ``c`` -- a codeword of :meth:`code` OUTPUT: @@ -931,7 +929,6 @@ def unencode_nocheck(self, c): -x0*x1 - x1^2 + x0 + 1 sage: E.encode(p) == c False - """ return _multivariate_polynomial_interpolation( c, @@ -940,7 +937,7 @@ def unencode_nocheck(self, c): def message_space(self): r""" - Return the message space of ``self`` + Return the message space of ``self``. EXAMPLES:: @@ -954,7 +951,7 @@ def message_space(self): def polynomial_ring(self): r""" - Return the polynomial ring associated with ``self`` + Return the polynomial ring associated with ``self``. EXAMPLES:: diff --git a/src/sage/coding/self_dual_codes.py b/src/sage/coding/self_dual_codes.py index f797a6b09d3..9270aa5f240 100644 --- a/src/sage/coding/self_dual_codes.py +++ b/src/sage/coding/self_dual_codes.py @@ -6,18 +6,18 @@ The main function is ``self_dual_binary_codes``, which is a case-by-case list of entries, each represented by a Python dictionary. -Format of each entry: a Python dictionary with keys ``"order autgp"``, ``"spectrum"``, -``"code"``, ``"Comment"``, ``"Type"``, where +Format of each entry: a Python dictionary with keys ``'order autgp'``, ``'spectrum'``, +``'code'``, ``'Comment'``, ``'Type'``, where -- ``"code"`` -- a sd code `C` of length `n`, dim `n/2`, over `\GF{2}` +- ``'code'`` -- a sd code `C` of length `n`, dim `n/2`, over `\GF{2}` -- ``"order autgp"`` -- order of the permutation automorphism group of `C` +- ``'order autgp'`` -- order of the permutation automorphism group of `C` -- ``"Type"`` -- the type of `C` (which can be ``"I"`` or ``"II"``, in the binary case) +- ``'Type'`` -- the type of `C` (which can be ``'I'`` or ``'II'``, in the binary case) -- ``"spectrum"`` -- the spectrum `[A_0,A_1,...,A_n]` +- ``'spectrum'`` -- the spectrum `[A_0,A_1,...,A_n]` -- ``"Comment"`` -- possibly an empty string. +- ``'Comment'`` -- possibly an empty string Python dictionaries were used since they seemed to be both human-readable and allow others to update the database easiest. @@ -54,10 +54,10 @@ case: For even `m`, let `A_m` denote the `m\times m` matrix over `\GF{2}` -given by adding the all 1's matrix to the identity matrix (in +given by adding the all 1s matrix to the identity matrix (in ``MatrixSpace(GF(2),m,m)`` of course). If `M_1, ..., M_r` are square matrices, let `diag(M_1,M_2,...,M_r)` denote the "block diagonal" -matrix with the matrices `M_i` on the diagonal and 0's elsewhere. Let +matrix with the matrices `M_i` on the diagonal and 0s elsewhere. Let `C(m_1,...,m_r,s)` denote the linear code with generator matrix having block form `G = (I, A)`, where `A = diag(A_{m_1},A_{m_2},...,A_{m_r},I_s)`, for some @@ -179,7 +179,7 @@ def _MS2(n): def _I2(n): r""" - Internal function + Internal function. EXAMPLES:: @@ -526,7 +526,7 @@ def self_dual_binary_codes(n): # "(1,5)(2,6)(3,7)(4,8)(10,14)(11,15)(12,16)(13,17)" ] ) spectrum = [1, 0, 1, 0, 28, 0, 28, 0, 198, 0, 198, 0, 28, 0, 28, 0, 1, 0, 1] self_dual_codes_18_3 = {"order autgp":7225344,"code":LinearCode(genmat),"spectrum":spectrum, - "Type":"I","Comment": "Large aut gp. Unique codeword of smallest non-zero wt.\ + "Type":"I","Comment": "Large aut gp. Unique codeword of smallest nonzero wt.\ Same spectrum as '[18,4]' sd code."} # [18,4]: genmat = _I2(n).augment(block_diagonal_matrix([_matA(n)[8],_matId(n)[8]])) @@ -534,7 +534,7 @@ def self_dual_binary_codes(n): # "(5,6)(14,15)", "(4,5)(13,14)", "(3,4)(12,13)", "(2,3)(11,12)", "(1,2)(10,11)" ] ) spectrum = [1, 0, 1, 0, 28, 0, 28, 0, 198, 0, 198, 0, 28, 0, 28, 0, 1, 0, 1] self_dual_codes_18_4 = {"order autgp":10321920,"code":LinearCode(genmat),"spectrum":spectrum, - "Type":"I","Comment": "Huge aut gp. Unique codeword of smallest non-zero wt.\ + "Type":"I","Comment": "Huge aut gp. Unique codeword of smallest nonzero wt.\ Same spectrum as '[18,3]' sd code."} # [18,5]: C = self_dual_binary_codes(n-2)["%s" % (n-2)]["5"]["code"] @@ -558,7 +558,7 @@ def self_dual_binary_codes(n): "(1,4)(2,6)(3,7)(5,17)(8,14)(10,13)(11,15)(12,16)" ] ) spectrum = [1, 0, 1, 0, 12, 0, 76, 0, 166, 0, 166, 0, 76, 0, 12, 0, 1, 0, 1] self_dual_codes_18_6 = {"order autgp":147456,"code":LinearCode(genmat),"spectrum":spectrum, - "Type":"I","Comment": "'Exceptional'. Unique codeword of smallest non-zero wt."} + "Type":"I","Comment": "'Exceptional'. Unique codeword of smallest nonzero wt."} # [18,7] (equiv to H18 in [P]) genmat = _MS(n)([[1,0,0,0,0,0,0,0,0,1,1,1,1,1,1,1,0,0], [0,1,0,0,0,0,0,0,0,0,0,0,1,1,1,1,0,1], diff --git a/src/sage/coding/source_coding/huffman.py b/src/sage/coding/source_coding/huffman.py index bb25e4cc47d..df4e0b96eff 100644 --- a/src/sage/coding/source_coding/huffman.py +++ b/src/sage/coding/source_coding/huffman.py @@ -45,7 +45,7 @@ def frequency_table(string): INPUT: - - ``string`` -- a string of symbols over some alphabet. + - ``string`` -- string of symbols over some alphabet OUTPUT: @@ -108,7 +108,7 @@ class Huffman(SageObject): - A dictionary that associates to each symbol of an alphabet a numeric value. If we consider the frequency of each alphabetic symbol, then ``source`` is considered as the frequency table of the alphabet with - each numeric (non-negative integer) value being the number of + each numeric (nonnegative integer) value being the number of occurrences of a symbol. The numeric values can also represent weights of the symbols. In that case, the numeric values are not necessarily integers, but can be real numbers. @@ -258,7 +258,7 @@ def __init__(self, source): def _build_code_from_tree(self, tree, d, prefix): r""" - Builds the Huffman code corresponding to a given tree and prefix. + Build the Huffman code corresponding to a given tree and prefix. INPUT: @@ -266,7 +266,7 @@ def _build_code_from_tree(self, tree, d, prefix): - ``d`` -- the dictionary to fill - - ``prefix`` (string) -- binary string which is the prefix + - ``prefix`` -- string; binary string which is the prefix of any element of the tree EXAMPLES:: @@ -292,15 +292,15 @@ def _build_code_from_tree(self, tree, d, prefix): def _build_code(self, dic): r""" - Constructs a Huffman code corresponding to an alphabet with the given + Construct a Huffman code corresponding to an alphabet with the given weight table. INPUT: - - ``dic`` -- a dictionary that associates to each symbol of an alphabet + - ``dic`` -- dictionary that associates to each symbol of an alphabet a numeric value. If we consider the frequency of each alphabetic symbol, then ``dic`` is considered as the frequency table of the - alphabet with each numeric (non-negative integer) value being the + alphabet with each numeric (nonnegative integer) value being the number of occurrences of a symbol. The numeric values can also represent weights of the symbols. In that case, the numeric values are not necessarily integers, but can be real numbers. In general, @@ -377,11 +377,9 @@ def encode(self, string): INPUT: - - ``string`` -- a string of symbols over an alphabet. + - ``string`` -- string of symbols over an alphabet - OUTPUT: - - - A Huffman encoding of ``string``. + OUTPUT: a Huffman encoding of ``string`` EXAMPLES: @@ -404,11 +402,9 @@ def decode(self, string): INPUT: - - ``string`` -- a string of Huffman encodings. - - OUTPUT: + - ``string`` -- string of Huffman encodings - - The Huffman decoding of ``string``. + OUTPUT: the Huffman decoding of ``string`` EXAMPLES: @@ -453,15 +449,13 @@ def decode(self, string): def encoding_table(self): r""" - Returns the current encoding table. + Return the current encoding table. INPUT: - None. - OUTPUT: - - - A dictionary associating an alphabetic symbol to a Huffman encoding. + OUTPUT: a dictionary associating an alphabetic symbol to a Huffman encoding EXAMPLES:: @@ -496,15 +490,13 @@ def encoding_table(self): def tree(self): r""" - Returns the Huffman tree corresponding to the current encoding. + Return the Huffman tree corresponding to the current encoding. INPUT: - None. - OUTPUT: - - - The binary tree representing a Huffman code. + OUTPUT: the binary tree representing a Huffman code EXAMPLES:: @@ -521,24 +513,22 @@ def tree(self): g.add_edges(self._generate_edges(self._tree)) return g - def _generate_edges(self, tree, parent="", bit=""): + def _generate_edges(self, tree, parent='', bit=''): """ Generate the edges of the given Huffman tree. INPUT: - - ``tree`` -- a Huffman binary tree. + - ``tree`` -- a Huffman binary tree - ``parent`` -- (default: empty string) a parent vertex with exactly - two children. + two children - ``bit`` -- (default: empty string) the bit signifying either the - left or right branch. The bit "0" denotes the left branch and "1" - denotes the right branch. - - OUTPUT: + left or right branch; the bit '0' denotes the left branch and '1' + denotes the right branch - - An edge list of the Huffman binary tree. + OUTPUT: an edge list of the Huffman binary tree EXAMPLES:: @@ -554,8 +544,8 @@ def _generate_edges(self, tree, parent="", bit=""): u = parent s = "".join([parent, bit]) try: - left = self._generate_edges(tree[0], parent=s, bit="0") - right = self._generate_edges(tree[1], parent=s, bit="1") + left = self._generate_edges(tree[0], parent=s, bit='0') + right = self._generate_edges(tree[1], parent=s, bit='1') L = [(u, s)] if s != "" else [] return left + right + L except TypeError: diff --git a/src/sage/coding/subfield_subcode.py b/src/sage/coding/subfield_subcode.py index eac8b3ace1f..970221ec24e 100644 --- a/src/sage/coding/subfield_subcode.py +++ b/src/sage/coding/subfield_subcode.py @@ -34,9 +34,9 @@ class SubfieldSubcode(AbstractLinearCode): INPUT: - - ``original_code`` -- the code ``self`` comes from. + - ``original_code`` -- the code ``self`` comes from - - ``subfield`` -- the base field of ``self``. + - ``subfield`` -- the base field of ``self`` - ``embedding`` -- (default: ``None``) a homomorphism from ``subfield`` to ``original_code``'s base field. If ``None`` is provided, it will default @@ -71,7 +71,6 @@ def __init__(self, original_code, subfield, embedding=None): Traceback (most recent call last): ... ValueError: subfield has to be a subfield of the base field of the original code - """ if not isinstance(original_code, AbstractLinearCode): raise ValueError("original_code must be a linear code") @@ -98,7 +97,7 @@ def __init__(self, original_code, subfield, embedding=None): def __eq__(self, other): r""" - Tests equality between Subfield Subcode objects. + Test equality between Subfield Subcode objects. EXAMPLES:: @@ -266,14 +265,14 @@ class SubfieldSubcodeOriginalCodeDecoder(Decoder): INPUT: - - ``code`` -- The associated code of this decoder + - ``code`` -- the associated code of this decoder - - ``original_decoder`` -- (default: ``None``) The decoder that will be used + - ``original_decoder`` -- (default: ``None``) the decoder that will be used over the original code. It has to be a decoder object over the original code. If it is set to ``None``, the default decoder over the original code will be used. - - ``**kwargs`` -- All extra arguments are forwarded to original code's decoder + - ``**kwargs`` -- all extra arguments are forwarded to original code's decoder EXAMPLES:: @@ -403,8 +402,8 @@ def decoding_radius(self, **kwargs): INPUT: - - ``kwargs`` -- Optional arguments are forwarded to original decoder's - :meth:`sage.coding.decoder.Decoder.decoding_radius` method. + - ``kwargs`` -- optional arguments are forwarded to original decoder's + :meth:`sage.coding.decoder.Decoder.decoding_radius` method EXAMPLES:: diff --git a/src/sage/combinat/abstract_tree.py b/src/sage/combinat/abstract_tree.py index 126185b4eb4..8ea604428f1 100644 --- a/src/sage/combinat/abstract_tree.py +++ b/src/sage/combinat/abstract_tree.py @@ -737,8 +737,8 @@ def paths_at_depth(self, depth, path=[]): INPUT: - - depth -- an integer - - path -- optional given path (as a list) used in the recursion + - ``depth`` -- integer + - ``path`` -- (optional) list; given path used in the recursion .. WARNING:: @@ -790,7 +790,7 @@ def node_number_at_depth(self, depth): INPUT: - - depth -- an integer + - ``depth`` -- integer .. SEEALSO:: @@ -1958,7 +1958,7 @@ def __getitem__(self, idx): INPUT: - - ``idx`` -- an integer, or a valid path in ``self`` identifying a node + - ``idx`` -- integer; or a valid path in ``self`` identifying a node .. NOTE:: @@ -2192,7 +2192,7 @@ def leaf_labels(self): def __eq__(self, other): """ - Test if ``self`` is equal to ``other`` + Test if ``self`` is equal to ``other``. TESTS:: @@ -2216,7 +2216,7 @@ def __eq__(self, other): def _hash_(self): """ - Return the hash value for ``self`` + Return the hash value for ``self``. TESTS:: @@ -2304,7 +2304,7 @@ def as_digraph(self): from sage.graphs.digraph import DiGraph resu = {self.label(): [t.label() for t in self if not t.is_empty()]} - resu = DiGraph(resu, format="dict_of_lists") + resu = DiGraph(resu, format='dict_of_lists') for t in self: if not t.is_empty(): resu = resu.union(t.as_digraph()) @@ -2314,7 +2314,7 @@ def as_digraph(self): class AbstractLabelledClonableTree(AbstractLabelledTree, AbstractClonableTree): """ - Abstract Labelled Clonable Tree + Abstract Labelled Clonable Tree. This class takes care of modification for the label by the clone protocol. @@ -2327,9 +2327,11 @@ def set_root_label(self, label): """ Set the label of the root of ``self``. - INPUT: ``label`` -- any Sage object + INPUT: + + - ``label`` -- any Sage object - OUTPUT: ``None``, ``self`` is modified in place + OUTPUT: none, ``self`` is modified in place .. NOTE:: @@ -2386,11 +2388,11 @@ def set_label(self, path, label): INPUT: - ``path`` -- ``None`` (default) or a path (list or tuple of children - index in the tree) + index in the tree) - ``label`` -- any sage object - OUTPUT: Nothing, ``self`` is modified in place + OUTPUT: nothing, ``self`` is modified in place .. NOTE:: @@ -2432,7 +2434,7 @@ def set_label(self, path, label): def map_labels(self, f): """ - Apply the function `f` to the labels of ``self`` + Apply the function `f` to the labels of ``self``. This method returns a copy of ``self`` on which the function `f` has been applied on all labels (a label `x` is replaced by `f(x)`). @@ -2515,7 +2517,7 @@ def _from_hexacode_aux(ch, parent, label='@'): - ``ch`` -- a hexadecimal string - - ``parent`` -- kind of trees to be produced. + - ``parent`` -- kind of trees to be produced - ``label`` -- a label (default: ``'@'``) to be used for every vertex of the tree diff --git a/src/sage/combinat/affine_permutation.py b/src/sage/combinat/affine_permutation.py index 3a6b935d0cc..74113055d13 100644 --- a/src/sage/combinat/affine_permutation.py +++ b/src/sage/combinat/affine_permutation.py @@ -47,7 +47,7 @@ class AffinePermutation(ClonableArray): def __init__(self, parent, lst, check=True): r""" - Initialize ``self`` + Initialize ``self``. INPUT: @@ -149,7 +149,7 @@ def __mul__(self, q): INPUT: - - ``q`` -- An element of ``self.parent()`` + - ``q`` -- an element of ``self.parent()`` EXAMPLES:: @@ -159,7 +159,6 @@ def __mul__(self, q): Type A affine permutation with window [-1, 3, 0, 6, 5, 4, 10, 9] sage: p.apply_simple_reflection(1, 'right') Type A affine permutation with window [-1, 3, 0, 6, 5, 4, 10, 9] - """ return self.__rmul__(q) @@ -183,7 +182,7 @@ def apply_simple_reflection(self, i, side='right'): INPUT: - - ``i`` -- an integer + - ``i`` -- integer - ``side`` -- (default: ``'right'``) determines whether to apply the reflection on the ``'right'`` or ``'left'`` @@ -219,7 +218,7 @@ def __call__(self, i): """ return self.value(i) - def is_i_grassmannian(self, i=0, side="right") -> bool: + def is_i_grassmannian(self, i=0, side='right') -> bool: r""" Test whether ``self`` is `i`-grassmannian, i.e., either is the identity or has ``i`` as the sole descent. @@ -258,7 +257,7 @@ def index_set(self): """ return tuple(range(self.k+1)) - def lower_covers(self,side="right"): + def lower_covers(self, side='right'): r""" Return lower covers of ``self``. @@ -281,7 +280,7 @@ def lower_covers(self,side="right"): def is_one(self) -> bool: r""" - Tests whether the affine permutation is the identity. + Test whether the affine permutation is the identity. EXAMPLES:: @@ -297,7 +296,7 @@ def is_one(self) -> bool: def reduced_word(self): r""" - Returns a reduced word for the affine permutation. + Return a reduced word for the affine permutation. EXAMPLES:: @@ -500,7 +499,7 @@ def apply_simple_reflection_right(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -579,7 +578,7 @@ def has_right_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -599,7 +598,7 @@ def has_left_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -675,11 +674,11 @@ def maximal_cyclic_factor(self, typ='decreasing', side='right', verbose=False): (default: ``'decreasing'``); chooses whether to find increasing or decreasing sets - - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``) chooses + - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``); chooses whether to find maximal sets starting from the left or the right - - ``verbose`` -- True or False. If True, outputs information about how - the cyclically increasing element was found. + - ``verbose`` -- boolean; if ``True``, outputs information about how + the cyclically increasing element was found EXAMPLES:: @@ -743,8 +742,8 @@ def maximal_cyclic_decomposition(self, typ='decreasing', side='right', verbose=F - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``) chooses whether to find maximal sets starting from the left or the right - - ``verbose`` -- (default: ``False``) print extra information while - finding the decomposition + - ``verbose`` -- boolean (default: ``False``); print extra information + while finding the decomposition EXAMPLES:: @@ -906,7 +905,7 @@ def is_fully_commutative(self) -> bool: if m != -1 and c[i] - (i - m) >= c[m]: return False m = i - # now check m (the last non-zero) against first non-zero. + # now check m (the last nonzero) against first nonzero. d = self.n - (m - firstnonzero) return not c[firstnonzero] - d >= c[m] @@ -917,11 +916,11 @@ def to_bounded_partition(self, typ='decreasing', side='right'): INPUT: - - ``typ`` -- ``'increasing'`` or ``'decreasing'`` (default: ``'decreasing'``.) - Chooses whether to find increasing or decreasing sets. + - ``typ`` -- ``'increasing'`` or ``'decreasing'`` (default: ``'decreasing'``); + chooses whether to find increasing or decreasing sets - - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``.) Chooses whether to - find maximal sets starting from the left or the right. + - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``); chooses + whether to find maximal sets starting from the left or the right EXAMPLES:: @@ -936,7 +935,7 @@ def to_bounded_partition(self, typ='decreasing', side='right'): def to_core(self, typ='decreasing', side='right'): r""" - Returns the core associated to the dominant element obtained by sorting + Return the core associated to the dominant element obtained by sorting the Lehmer code. INPUT: @@ -944,7 +943,7 @@ def to_core(self, typ='decreasing', side='right'): - ``typ`` -- ``'increasing'`` or ``'decreasing'`` (default: ``'decreasing'``.) - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``.) Chooses whether to - find maximal sets starting from the left or the right. + find maximal sets starting from the left or the right EXAMPLES:: @@ -1119,7 +1118,7 @@ def value(self, i): def position(self, i): r""" - Find the position `j` such the ``self.value(j)=i`` + Find the position `j` such the ``self.value(j)=i``. EXAMPLES:: @@ -1231,7 +1230,7 @@ def has_right_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1252,7 +1251,7 @@ def has_left_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1414,7 +1413,7 @@ def has_right_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1433,7 +1432,7 @@ def has_left_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1589,7 +1588,7 @@ def has_right_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1610,7 +1609,7 @@ def has_left_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1791,7 +1790,7 @@ def has_right_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1812,7 +1811,7 @@ def has_left_descent(self, i) -> bool: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -2067,7 +2066,7 @@ def _test_enumeration(self, n=4, **options): def weyl_group(self): r""" - Returns the Weyl Group of the same type as ``self``. + Return the Weyl Group of the same type as ``self``. EXAMPLES:: @@ -2079,7 +2078,7 @@ def weyl_group(self): def classical(self): r""" - Returns the finite permutation group. + Return the finite permutation group. EXAMPLES:: @@ -2093,7 +2092,7 @@ def classical(self): def cartan_type(self): r""" - Returns the Cartan type of ``self``. + Return the Cartan type of ``self``. EXAMPLES:: @@ -2104,7 +2103,7 @@ def cartan_type(self): def cartan_matrix(self): r""" - Returns the Cartan matrix of ``self``. + Return the Cartan matrix of ``self``. EXAMPLES:: @@ -2167,7 +2166,7 @@ def random_element(self, n=None): Return a random affine permutation of length ``n``. If ``n`` is not specified, then ``n`` is chosen as a random - non-negative integer in `[0, 1000]`. + nonnegative integer in `[0, 1000]`. Starts at the identity, then chooses an upper cover at random. Not very uniform: actually constructs a uniformly random reduced word @@ -2192,7 +2191,7 @@ def random_element(self, n=None): def from_word(self, w): r""" - Builds an affine permutation from a given word. + Build an affine permutation from a given word. Note: Already in category as ``from_reduced_word``, but this is less typing! @@ -2208,7 +2207,7 @@ def from_word(self, w): @cached_method def _an_element_(self): r""" - Returns a Coxeter element. + Return a Coxeter element. EXAMPLES:: diff --git a/src/sage/combinat/all.py b/src/sage/combinat/all.py index c55f8e01c48..901bca30fd2 100644 --- a/src/sage/combinat/all.py +++ b/src/sage/combinat/all.py @@ -72,7 +72,7 @@ from sage.combinat.dlx import DLXMatrix, AllExactCovers, OneExactCover -# block designs, etc +# block designs, etc. from sage.combinat.designs.all import * # Free modules and friends diff --git a/src/sage/combinat/alternating_sign_matrix.py b/src/sage/combinat/alternating_sign_matrix.py index 944091eb74e..230c9a8aae7 100644 --- a/src/sage/combinat/alternating_sign_matrix.py +++ b/src/sage/combinat/alternating_sign_matrix.py @@ -84,7 +84,7 @@ class AlternatingSignMatrix(Element, An alternating sign matrix. An alternating sign matrix is a square matrix of `0`'s, `1`'s and `-1`'s - such that the sum of each row and column is `1` and the non-zero + such that the sum of each row and column is `1` and the nonzero entries in each row and column alternate in sign. These were introduced in [MRR1983]_. @@ -519,18 +519,17 @@ def to_fully_packed_loop(self): sage: asm = AlternatingSignMatrix([[1,0,0],[0,1,0],[0,0,1]]) sage: fpl = asm.to_fully_packed_loop() sage: fpl - | | - | | - + + -- + - | | - | | - -- + + + -- - | | - | | - + -- + + - | | - | | - + │ │ + │ │ + + + ── + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + ── + + + │ │ + │ │ """ from sage.combinat.fully_packed_loop import FullyPackedLoop return FullyPackedLoop(self) @@ -695,7 +694,7 @@ def ASM_compatible_bigger(self): Given an `n \times n` alternating sign matrix `A`, there are as many ASM's of size `n+1` compatible with `A` as 2 raised to the power of - the number of 1's in `A` [EKLP1992]_. + the number of 1s in `A` [EKLP1992]_. EXAMPLES:: @@ -777,7 +776,6 @@ def ASM_compatible_smaller(self): [1 0] [0 1] ] - """ n = self.parent()._n M = AlternatingSignMatrices(n-1) @@ -1020,14 +1018,14 @@ class AlternatingSignMatrices(UniqueRepresentation, Parent): An alternating sign matrix of size `n` is an `n \times n` matrix of `0`'s, `1`'s and `-1`'s such that the sum of each row and column is `1` and the - non-zero entries in each row and column alternate in sign. + nonzero entries in each row and column alternate in sign. Alternating sign matrices of size `n` are in bijection with :class:`monotone triangles ` with `n` rows. INPUT: - - `n` -- an integer, the size of the matrices. + - ``n`` -- integer; the size of the matrices EXAMPLES: @@ -1547,7 +1545,6 @@ def cover_relations(self): [0 0 1] [0 1 0] [1 0 0], [1 0 0] ) - """ return iter(self._lattice_initializer()[1]) @@ -1562,7 +1559,6 @@ def lattice(self): sage: L = A.lattice() sage: L Finite lattice containing 7 elements - """ return LatticePoset(self._lattice_initializer(), cover_relations=True, check=False) @@ -1635,7 +1631,7 @@ class MonotoneTriangles(GelfandTsetlinPatternsTopRow): INPUT: - - ``n`` -- The number of rows in the monotone triangles + - ``n`` -- the number of rows in the monotone triangles EXAMPLES: diff --git a/src/sage/combinat/backtrack.py b/src/sage/combinat/backtrack.py index 1fd90caa9d3..223d3de1db5 100644 --- a/src/sage/combinat/backtrack.py +++ b/src/sage/combinat/backtrack.py @@ -152,7 +152,7 @@ def roots(self): def children(self, x): r""" - Return the single child ``x+1`` of the integer ``x`` + Return the single child ``x+1`` of the integer ``x``. EXAMPLES:: diff --git a/src/sage/combinat/baxter_permutations.py b/src/sage/combinat/baxter_permutations.py index 648ce9c6a26..08b67b96540 100644 --- a/src/sage/combinat/baxter_permutations.py +++ b/src/sage/combinat/baxter_permutations.py @@ -25,8 +25,8 @@ class BaxterPermutations(UniqueRepresentation, Parent): INPUT: - - ``n`` -- (default: ``None``) a nonnegative integer, the size of - the permutations. + - ``n`` -- nonnegative integer (default: ``None``); the size of + the permutations OUTPUT: @@ -85,7 +85,7 @@ def __init__(self, n): def _repr_(self): """ - Return a string representation of ``self`` + Return a string representation of ``self``. EXAMPLES:: @@ -102,7 +102,7 @@ def __contains__(self, x): INPUT: - - ``x`` -- a permutation. + - ``x`` -- a permutation EXAMPLES:: @@ -150,9 +150,7 @@ def __iter__(self): r""" Efficient generation of Baxter permutations. - OUTPUT: - - An iterator over the Baxter permutations of size ``self._n``. + OUTPUT: an iterator over the Baxter permutations of size ``self._n`` EXAMPLES:: @@ -287,7 +285,7 @@ def __contains__(self, x): INPUT: - - ``x`` -- any object. + - ``x`` -- any object EXAMPLES:: @@ -312,7 +310,7 @@ def to_pair_of_twin_binary_trees(self, p): INPUT: - - ``p`` -- a Baxter permutation. + - ``p`` -- a Baxter permutation OUTPUT: diff --git a/src/sage/combinat/bijectionist.py b/src/sage/combinat/bijectionist.py index 2bb02e31aac..ce1bf8aca13 100644 --- a/src/sage/combinat/bijectionist.py +++ b/src/sage/combinat/bijectionist.py @@ -481,7 +481,6 @@ class Bijectionist(SageObject): :meth:`set_statistics`, :meth:`set_intertwining_relations`, :meth:`set_constant_blocks`, etc., is irrelevant. Calling any of these methods a second time overrides the previous specification. - """ def __init__(self, A, B, tau=None, alpha_beta=tuple(), P=None, pi_rho=tuple(), phi_psi=tuple(), Q=None, @@ -565,7 +564,7 @@ def set_constant_blocks(self, P): INPUT: - - ``P`` -- a set partition of `A`, singletons may be omitted + - ``P`` -- set partition of `A`, singletons may be omitted EXAMPLES: @@ -605,7 +604,6 @@ def set_constant_blocks(self, P): Traceback (most recent call last): ... StopIteration - """ self._bmilp = None self._P = DisjointSet(self._A) @@ -623,10 +621,10 @@ def constant_blocks(self, singletons=False, optimal=False): INPUT: - - ``singletons`` -- (default: ``False``) whether or not to + - ``singletons`` -- boolean (default: ``False``); whether or not to include singleton blocks in the output - - ``optimal`` -- (default: ``False``) whether or not to + - ``optimal`` -- boolean (default: ``False``); whether or not to compute the coarsest possible partition .. NOTE:: @@ -645,7 +643,6 @@ def constant_blocks(self, singletons=False, optimal=False): sage: bij.constant_blocks(singletons=True) {{'a', 'b'}, {'c'}} - """ if optimal: self._forced_constant_blocks() @@ -748,7 +745,6 @@ def set_statistics(self, *alpha_beta): {[]: 2, [1]: 0, [1, 2]: 0, [2, 1]: 1} {[]: 2, [1]: 0, [1, 2]: 1, [2, 1]: 0} {[]: 2, [1]: 1, [1, 2]: 0, [2, 1]: 0} - """ self._bmilp = None self._n_statistics = len(alpha_beta) @@ -815,7 +811,6 @@ def statistics_fibers(self): (3, 2, 1) [[1, 3, 2], [2, 1, 3], [3, 2, 1]] [[1, 3, 2], [2, 1, 3], [2, 3, 1]] (3, 2, 0) [[2, 3, 1]] [[3, 1, 2]] (3, 1, 0) [[3, 1, 2]] [[1, 2, 3]] - """ return self._statistics_fibers @@ -827,7 +822,7 @@ def statistics_table(self, header=True): INPUT: - - ``header`` -- (default: ``True``) whether to include a + - ``header`` -- boolean (default: ``True``); whether to include a header with the standard Greek letters OUTPUT: @@ -940,7 +935,6 @@ def statistics_table(self, header=True): [['b', 'τ'], [[], 0], [[1], 1], [[1, 2], 2], [[2, 1], 1]] sage: bij.statistics_table(header=False)[1] [[[], 0], [[1], 1], [[1, 2], 2], [[2, 1], 1]] - """ # table for alpha n_statistics = self._n_statistics @@ -1059,7 +1053,6 @@ def set_value_restrictions(self, *value_restrictions): Traceback (most recent call last): ... AssertionError: element (1, 2) was not found in A - """ # it might be much cheaper to construct the sets as subsets # of _statistics_possible_values - however, we do not want to @@ -1078,7 +1071,7 @@ def _compute_possible_block_values(self): This has to be called whenever ``self._P`` was modified. - It raises a :class:`ValueError`, if the restrictions on a + It raises a :exc:`ValueError`, if the restrictions on a block are contradictory. TESTS:: @@ -1091,7 +1084,6 @@ def _compute_possible_block_values(self): Traceback (most recent call last): ... ValueError: no possible values found for singleton block [[1, 2]] - """ self._possible_block_values = {} # P -> Power(Z) for p, block in self._P.root_to_elements_dict().items(): @@ -1254,7 +1246,6 @@ def set_distributions(self, *elements_distributions): Note that the same error occurs when an element that is not the first element of the list is not in `A`. - """ self._bmilp = None for tA, tZ in elements_distributions: @@ -1382,7 +1373,6 @@ def set_intertwining_relations(self, *pi_rho): sage: bij.set_intertwining_relations((2, concat, lambda x, y: x + y), (2, skew_concat, lambda x, y: x + y)) sage: list(bij.solutions_iterator()) [] - """ self._bmilp = None Pi_Rho = namedtuple("Pi_Rho", "numargs pi rho domain") @@ -1420,7 +1410,6 @@ def set_quadratic_relation(self, *phi_psi): and `\psi:Z\to A`. Note that, in particular, `\phi` must be constant on blocks. - EXAMPLES:: sage: A = B = DyckWords(3) @@ -1447,7 +1436,6 @@ def set_quadratic_relation(self, *phi_psi): ( [ /\ ] ) ] ( [ / \ ] ) ] ( [ / \ ], [ /\/\/\ ] ) ] - """ self._bmilp = None self._phi_psi = phi_psi @@ -1459,7 +1447,7 @@ def set_homomesic(self, Q): INPUT: - - ``Q`` -- a set partition of ``A`` + - ``Q`` -- set partition of ``A`` EXAMPLES:: @@ -1468,7 +1456,6 @@ def set_homomesic(self, Q): sage: bij.set_homomesic([[1,2], [3]]) sage: list(bij.solutions_iterator()) [{1: 2, 2: 0, 3: 1}, {1: 0, 2: 2, 3: 1}] - """ self._bmilp = None if Q is None: @@ -1640,7 +1627,6 @@ def _forced_constant_blocks(self): {{'a', 'b'}} sage: bij.constant_blocks(optimal=True) {{'a', 'b'}, {'c', 'd'}} - """ if self._bmilp is None: self._bmilp = _BijectionistMILP(self) @@ -1709,7 +1695,7 @@ def possible_values(self, p=None, optimal=False): - ``p`` -- (optional) a block of `P`, or an element of a block of `P`, or a list of these - - ``optimal`` -- (default: ``False``) whether or not to + - ``optimal`` -- boolean (default: ``False``); whether or not to compute the minimal possible set of statistic values .. NOTE:: @@ -1748,7 +1734,7 @@ def possible_values(self, p=None, optimal=False): Test if all formats are really possible:: - sage: bij.possible_values(p="a") + sage: bij.possible_values(p='a') {'a': {1, 2}, 'b': {1, 2}} sage: bij.possible_values(p=["a", "b"]) {'a': {1, 2}, 'b': {1, 2}} @@ -1762,9 +1748,9 @@ def possible_values(self, p=None, optimal=False): sage: A = B = 'ab' sage: bij = Bijectionist(A, B, lambda x: B.index(x) % 2) sage: bij.set_constant_blocks([['a', 'b']]) - sage: bij.possible_values(p="a") + sage: bij.possible_values(p='a') {'a': {0, 1}, 'b': {0, 1}} - sage: bij.possible_values(p="a", optimal=True) + sage: bij.possible_values(p='a', optimal=True) {'a': set(), 'b': set()} """ # convert input to set of block representatives @@ -1893,7 +1879,7 @@ def minimal_subdistributions_iterator(self): # add constraint that not all of these can be 1, thus vetoing # the current solution minimal_subdistribution.add_constraint(sum(active_vars) <= len(active_vars) - 1, - name="veto") + name='veto') else: s = new_s @@ -1929,7 +1915,6 @@ def _find_counterexample(self, P, s0, d, on_blocks): sage: d = {'a': 1, 'b': 0, 'c': 0, 'd': 0, 'e': 0} sage: bij._find_counterexample(bij._A, s0, d, False) {'a': 2, 'b': 2, 'c': 1, 'd': 3, 'e': 1} - """ bmilp = self._bmilp for z in self._Z: @@ -2065,7 +2050,6 @@ def minimal_subdistributions_blocks_iterator(self): sage: sorted(D) in [d for d, _ in bij.minimal_subdistributions_iterator()] True - """ # see # https://mathoverflow.net/questions/406751/find-a-subdistribution/406975 @@ -2110,7 +2094,7 @@ def add_counter_example_constraint(s): support = [X[p] for p in P if d[p]] # add constraint that the support is different minimal_subdistribution.add_constraint(sum(support) <= len(support) - 1, - name="veto") + name='veto') else: s = new_s add_counter_example_constraint(s) @@ -2168,7 +2152,6 @@ def _preprocess_intertwining_relations(self): sage: bij._preprocess_intertwining_relations() sage: bij._P {{[1, 2, 3]}, {[1, 3, 2]}, {[2, 1, 3]}, {[2, 3, 1]}, {[3, 1, 2]}, {[3, 2, 1]}} - """ A = self._A P = self._P @@ -2207,7 +2190,7 @@ def solutions_iterator(self): r""" An iterator over all solutions of the problem. - OUTPUT: An iterator over all possible mappings `s: A\to Z` + OUTPUT: an iterator over all possible mappings `s: A\to Z` ALGORITHM: @@ -2274,7 +2257,7 @@ def solutions_iterator(self): EXAMPLES:: sage: A = B = 'abc' - sage: bij = Bijectionist(A, B, lambda x: B.index(x) % 2, solver="GLPK") + sage: bij = Bijectionist(A, B, lambda x: B.index(x) % 2, solver='GLPK') sage: next(bij.solutions_iterator()) {'a': 0, 'b': 1, 'c': 0} @@ -2303,7 +2286,7 @@ def solutions_iterator(self): sage: P = [list(a) for n in range(N) for a in Permutations(n).conjugacy_classes()] - sage: bij = Bijectionist(A, B, tau, solver="GLPK") + sage: bij = Bijectionist(A, B, tau, solver='GLPK') sage: bij.set_statistics((len, len)) sage: bij.set_constant_blocks(P) sage: for solution in bij.solutions_iterator(): @@ -2447,7 +2430,6 @@ def solutions_iterator(self): sage: s1_3 = next(iterator1) sage: len(set([tuple(sorted(s.items())) for s in [s1_1, s1_2, s1_3]])) 3 - """ if self._bmilp is None: self._bmilp = _BijectionistMILP(self) @@ -2467,7 +2449,7 @@ def __init__(self, bijectionist: Bijectionist, solutions=None): INPUT: - - ``bijectionist`` -- an instance of :class:`Bijectionist`. + - ``bijectionist`` -- an instance of :class:`Bijectionist` - ``solutions`` -- (optional) a list of solutions of the problem, each provided as a dictionary mapping `(a, z)` to @@ -2486,7 +2468,6 @@ def __init__(self, bijectionist: Bijectionist, solutions=None): sage: from sage.combinat.bijectionist import _BijectionistMILP sage: _BijectionistMILP(bij) - """ # the attributes of the bijectionist class we actually use: # _possible_block_values @@ -2534,7 +2515,7 @@ def show(self, variables=True): EXAMPLES:: sage: A = B = ["a", "b", "c"] - sage: bij = Bijectionist(A, B, lambda x: A.index(x) % 2, solver="GLPK") + sage: bij = Bijectionist(A, B, lambda x: A.index(x) % 2, solver='GLPK') sage: bij.set_constant_blocks([["a", "b"]]) sage: next(bij.solutions_iterator()) {'a': 0, 'b': 0, 'c': 1} @@ -2550,7 +2531,6 @@ def show(self, variables=True): x_1: s(a) = s(b) = 1 x_2: s(c) = 0 x_3: s(c) = 1 - """ print("Constraints are:") b = self.milp.get_backend() @@ -2609,7 +2589,6 @@ def _prepare_solution(self, on_blocks, solution): sage: bmilp = bij._bmilp sage: bmilp._prepare_solution(True, bmilp._solution_cache[0]) {'a': 0, 'c': 0} - """ P = self._bijectionist._P tZ = self._bijectionist._possible_block_values @@ -2631,16 +2610,16 @@ def solutions_iterator(self, on_blocks, additional_constraints): INPUT: - - ``additional_constraints`` -- a list of constraints for the + - ``additional_constraints`` -- list of constraints for the underlying MILP - - ``on_blocks``, whether to return the solution on blocks or + - ``on_blocks`` -- whether to return the solution on blocks or on all elements TESTS:: sage: A = B = 'abc' - sage: bij = Bijectionist(A, B, lambda x: B.index(x) % 2, solver="GLPK") + sage: bij = Bijectionist(A, B, lambda x: B.index(x) % 2, solver='GLPK') sage: from sage.combinat.bijectionist import _BijectionistMILP sage: bmilp = _BijectionistMILP(bij) sage: it = bmilp.solutions_iterator(False, []) @@ -2653,7 +2632,6 @@ def solutions_iterator(self, on_blocks, additional_constraints): {'a': 0, 'b': 0, 'c': 1} sage: next(it) {'a': 1, 'b': 0, 'c': 0} - """ i = 0 # the first unconsidered element of _solution_cache while True: @@ -2700,7 +2678,7 @@ def _add_solution(self, solution): INPUT: - - ``solution`` -- a dictionary from the indices of the MILP to + - ``solution`` -- dictionary from the indices of the MILP to a boolean EXAMPLES:: @@ -2722,14 +2700,13 @@ def _add_solution(self, solution): x_1: s(a) = a x_2: s(b) = b x_3: s(b) = a - """ active_vars = [self._x[p, z] for p in _disjoint_set_roots(self._bijectionist._P) for z in self._bijectionist._possible_block_values[p] if solution[(p, z)]] self.milp.add_constraint(sum(active_vars) <= len(active_vars) - 1, - name="veto") + name='veto') self._solution_cache.append(solution) def _is_solution(self, constraint, values): @@ -2739,7 +2716,7 @@ def _is_solution(self, constraint, values): INPUT: - ``constraint`` -- a - :class:`sage.numerical.linear_functions.LinearConstraint`. + :class:`sage.numerical.linear_functions.LinearConstraint` - ``values`` -- a candidate for a solution of the MILP as a dictionary from pairs `(a, z)\in A\times Z` to `0` or `1`, @@ -2825,7 +2802,7 @@ def add_alpha_beta_constraints(self): for w in range(len(W)): for z in range(len(Z)): self.milp.add_constraint(AZ_matrix[z][w] == B_matrix[z][w], - name="statistics") + name='statistics') def add_distribution_constraints(self): r""" @@ -2856,7 +2833,6 @@ def add_distribution_constraints(self): [2, 3, 1]: 2, [3, 1, 2]: 2, [3, 2, 1]: 2} - """ Z = self._bijectionist._Z Z_dict = {z: i for i, z in enumerate(Z)} @@ -2998,7 +2974,6 @@ def add_quadratic_relation_constraints(self): ( [ /\ ] ) ] ( [ / \ ] ) ] ( [ / \ ], [ /\/\/\ ] ) ] - """ P = self._bijectionist._P for phi, psi in self._bijectionist._phi_psi: @@ -3060,7 +3035,7 @@ def _invert_dict(d): INPUT: - - ``d`` -- a dict + - ``d`` -- dictionary EXAMPLES:: @@ -3115,7 +3090,6 @@ def _non_copying_intersection(sets): sage: A = set([1,2]); B = set([2,3]) sage: _non_copying_intersection([A, B]) {2} - """ sets = sorted(sets, key=len) result = set.intersection(*sets) diff --git a/src/sage/combinat/binary_recurrence_sequences.py b/src/sage/combinat/binary_recurrence_sequences.py index 76765b38aab..df8de0ada86 100644 --- a/src/sage/combinat/binary_recurrence_sequences.py +++ b/src/sage/combinat/binary_recurrence_sequences.py @@ -76,25 +76,22 @@ class BinaryRecurrenceSequence(SageObject): - """ Create a linear binary recurrence sequence defined by initial conditions `u_0` and `u_1` and recurrence relation `u_{n+2} = b*u_{n+1}+c*u_n`. INPUT: - - ``b`` -- an integer (partially determining the recurrence relation) - - - ``c`` -- an integer (partially determining the recurrence relation) - - - ``u0`` -- an integer (the 0th term of the binary recurrence sequence) + - ``b`` -- integer; (partially determining the recurrence relation) - - ``u1`` -- an integer (the 1st term of the binary recurrence sequence) + - ``c`` -- integer; (partially determining the recurrence relation) + - ``u0`` -- integer; (the `0`-th term of the binary recurrence sequence) - OUTPUT: + - ``u1`` -- integer; (the `1`-st term of the binary recurrence sequence) - - An integral linear binary recurrence sequence defined by ``u0``, ``u1``, and `u_{n+2} = b*u_{n+1}+c*u_n` + OUTPUT: an integral linear binary recurrence sequence defined by `u_0`, + `u_1`, and `u_{n+2} = b u_{n+1}+c u_n` .. SEEALSO:: @@ -106,7 +103,6 @@ class BinaryRecurrenceSequence(SageObject): sage: R Binary recurrence sequence defined by: u_n = 3 * u_{n-1} + 3 * u_{n-2}; With initial conditions: u_0 = 2, and u_1 = 1 - """ def __init__(self, b, c, u0=0, u1=1): @@ -164,17 +160,17 @@ def __eq__(self, other) -> bool: def __call__(self, n, modulus=0): """ - Give the nth term of a binary recurrence sequence, possibly mod some modulus. + Give the `n`-th term of a binary recurrence sequence, possibly mod some modulus. INPUT: - - ``n`` -- an integer (the index of the term in the binary recurrence sequence) + - ``n`` -- integer; the index of the term in the binary recurrence sequence - ``modulus`` -- a natural number (optional -- default value is 0) OUTPUT: - - An integer (the nth term of the binary recurrence sequence modulo ``modulus``) + - An integer (the `n`-th term of the binary recurrence sequence modulo ``modulus``) EXAMPLES:: @@ -208,13 +204,20 @@ def is_degenerate(self) -> bool: More concretely, there are 4 classes of degeneracy, that can all be formulated in terms of the matrix `F = [[0,1], [c, b]]`. - - `F` is singular -- this corresponds to ``c`` = 0, and thus `\\alpha*\\beta = 0`. This sequence is geometric after term ``u0`` and so we call it ``quasigeometric``. + - `F` is singular -- this corresponds to ``c`` = 0, and thus + `\\alpha*\\beta = 0`. This sequence is geometric after term ``u0`` + and so we call it ``quasigeometric`` - - `v = [[u_0], [u_1]]` is an eigenvector of `F` -- this corresponds to a ``geometric`` sequence with `a*b = 0`. + - `v = [[u_0], [u_1]]` is an eigenvector of `F` -- this corresponds to + a ``geometric`` sequence with `a*b = 0` - - `F` is nondiagonalizable -- this corresponds to `\\alpha = \\beta`. This sequence will be the point-wise product of an arithmetic and geometric sequence. + - `F` is nondiagonalizable -- this corresponds to `\\alpha = \\beta`. + This sequence will be the point-wise product of an arithmetic and + geometric sequence. - - `F^k` is scalar, for some `k>1` -- this corresponds to `\\alpha/\\beta` a `k` th root of unity. This sequence is a union of several geometric sequences, and so we again call it ``quasigeometric``. + - `F^k` is scalar, for some `k>1` -- this corresponds to + `\\alpha/\\beta` a `k` th root of unity. This sequence is a union of + several geometric sequences, and so we again call it ``quasigeometric``. EXAMPLES:: @@ -355,11 +358,9 @@ def period(self, m): INPUT: - - ``m`` -- an integer (modulo which the period of the recurrence relation is calculated). - - OUTPUT: + - ``m`` -- integer; modulo which the period of the recurrence relation is calculated - - The integer (the period of the sequence modulo m) + OUTPUT: integer (the period of the sequence modulo m) EXAMPLES: @@ -498,23 +499,24 @@ def period(self, m): def pthpowers(self, p, Bound): """ - Find the indices of proveably all pth powers in the recurrence sequence bounded by Bound. + Find the indices of proveably all `p`-th powers in the recurrence sequence + bounded by Bound. - Let `u_n` be a binary recurrence sequence. A ``p`` th power in `u_n` is a solution - to `u_n = y^p` for some integer `y`. There are only finitely many ``p`` th powers in - any recurrence sequence [SS1983]_. + Let `u_n` be a binary recurrence sequence. A ``p`` th power in `u_n` + is a solution to `u_n = y^p` for some integer `y`. There are only + finitely many ``p`` th powers in any recurrence sequence [SS1983]_. INPUT: - ``p`` -- a rational prime integer (the fixed p in `u_n = y^p`) - - ``Bound`` -- a natural number (the maximum index `n` in `u_n = y^p` that is checked). + - ``Bound`` -- a natural number (the maximum index `n` in `u_n = y^p` that is checked) OUTPUT: - - A list of the indices of all ``p`` th powers less bounded by - ``Bound``. If the sequence is degenerate and there are many - ``p`` th powers, raises :class:`ValueError`. + A list of the indices of all ``p`` th powers less bounded by + ``Bound``. If the sequence is degenerate and there are many + ``p`` th powers, raises :exc:`ValueError`. EXAMPLES:: @@ -531,7 +533,7 @@ def pthpowers(self, p, Bound): [1] If the sequence is degenerate, and there are no ``p`` th powers, returns `[]`. Otherwise, if - there are many ``p`` th powers, raises :class:`ValueError`. + there are many ``p`` th powers, raises :exc:`ValueError`. :: @@ -745,19 +747,17 @@ def pthpowers(self, p, Bound): def _prime_powers(N): - """ - Find the prime powers dividing ``N``. + r""" + Find the prime powers dividing `N`. - In other words, if `N = q_1^(e_1)q_2^(e_2)...q_n^(e_n)`, it returns - `[q_1^(e_1),q_2^(e_2),...,q_n^(e_n)]`. + In other words, if `N = q_1^{e_1} q_2^{e_2} \cdots q_n^{e_n}`, it returns + `[q_1^{e_1}, q_2^{e_2}, \ldots, q_n^{e_n}]`. INPUT: - - ``N`` -- an integer - - OUTPUT: + - ``N`` -- integer - - A list of the prime powers dividing N. + OUTPUT: list of the prime powers dividing N EXAMPLES:: @@ -772,15 +772,13 @@ def _prime_powers(N): def _largest_ppower_divisor(N): """ - Find the largest prime power divisor of N. + Find the largest prime power divisor of `N`. INPUT: - - ``N`` -- an integer - - OUTPUT: + - ``N`` -- integer - The largest prime power dividing ``N``. + OUTPUT: the largest prime power dividing `N` EXAMPLES:: @@ -794,12 +792,12 @@ def _largest_ppower_divisor(N): def _goodness(n, R, p): """ - Return the goodness of ``n`` for the sequence ``R`` and the prime ``p`` -- that is the largest - non-``p`` prime power dividing ``period(n)``. + Return the goodness of `n` for the sequence `R` and the prime `p` -- that is the largest + non-`p` prime power dividing ``period(n)``. INPUT: - - ``n`` -- an integer + - ``n`` -- an integer - ``R`` -- an object in the class ``BinaryRecurrenceSequence`` @@ -827,9 +825,9 @@ def _goodness(n, R, p): def _next_good_prime(p, R, qq, patience, qqold): - """ - Find the next prime `\\ell` which is good by ``qq`` but not by ``qqold``, 1 mod ``p``, and for which - ``b^2+4*c`` is a square mod `\\ell`, for the sequence ``R`` if it is possible in runtime patience. + r""" + Find the next prime `\ell` which is good by ``qq`` but not by ``qqold``, 1 mod ``p``, and for which + ``b^2+4*c`` is a square mod `\ell`, for the sequence ``R`` if it is possible in runtime patience. INPUT: @@ -841,12 +839,11 @@ def _next_good_prime(p, R, qq, patience, qqold): - ``patience`` -- a real number - - ``qqold`` -- a perfect power less than or equal to ``qq`` - - OUTPUT: - - - A prime `\\ell` such that `\\ell` is 1 mod ``p``, ``b^2+4*c`` is a square mod `\\ell` and the period of `\\ell` has ``goodness`` by ``qq`` but not ``qqold``, if patience has not be surpased. Otherwise ``False``. + - ``qqold`` -- a perfect power less than or equal to ``qq`` + OUTPUT: a prime `\ell` such that `\ell` is 1 mod `p`, `b^2+4 c` is a + square mod `\ell` and the period of `\ell` has ``goodness`` by ``qq`` but + not ``qqold``, if patience has not be surpased; otherwise ``False`` EXAMPLES:: @@ -857,7 +854,6 @@ def _next_good_prime(p, R, qq, patience, qqold): 29 sage: sage.combinat.binary_recurrence_sequences._next_good_prime(7,R,2,100,2) #ran out of patience, as qqold == qq, so no primes work False - """ # We are looking for pth powers in R. # Our primes must be good by qq, but not qqold. @@ -928,15 +924,13 @@ def _is_p_power_mod(a, p, N): INPUT: - - ``a`` -- an integer + - ``a`` -- integer - ``p`` -- a rational prime number - - ``N`` -- a positive integer - - OUTPUT: + - ``N`` -- positive integer - - True if ``a`` is a ``p`` th power modulo ``N``; False otherwise. + OUTPUT: ``True`` if `a` is a `p`-th power modulo `N`; ``False`` otherwise EXAMPLES:: @@ -1028,17 +1022,15 @@ def _estimated_time(M2, M1, length, p): INPUT: - - ``M2`` -- an integer (the new modulus) - - - ``M1`` -- an integer (the old modulus) + - ``M2`` -- integer; (the new modulus) - - ``length`` -- a list (the current length of the list of congruences mod ``M1``) + - ``M1`` -- integer; (the old modulus) - - ``p`` -- a prime + - ``length`` -- list (the current length of the list of congruences mod ``M1``) - OUTPUT: + - ``p`` -- a prime - - The estimated run time of the "CRT" step to combine consistent congruences. + OUTPUT: the estimated run time of the "CRT" step to combine consistent congruences EXAMPLES:: @@ -1113,17 +1105,15 @@ def _find_cong1(p, R, ell): def _is_p_power(a, p) -> bool: """ - Determine whether ``a`` is a perfect ``p`` th power. + Determine whether `a` is a perfect `p`-th power. INPUT: - - ``a`` -- an integer + - ``a`` -- integer - ``p`` -- a prime number - OUTPUT: - - boolean, whether ``a`` is a ``p`` th power + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/combinat/binary_tree.py b/src/sage/combinat/binary_tree.py index 8373ae72ad1..0d018c18b00 100644 --- a/src/sage/combinat/binary_tree.py +++ b/src/sage/combinat/binary_tree.py @@ -65,8 +65,8 @@ class BinaryTree(AbstractClonableTree, ClonableArray, be shortened to ``BinaryTree([None,None])``. It is also allowed to abbreviate ``[None, None]`` by ``[]``. - - ``check`` -- (default: ``True``) whether check for binary should be - performed or not. + - ``check`` -- boolean (default: ``True``); whether check for binary should + be performed or not EXAMPLES:: @@ -707,10 +707,9 @@ def graph(self, with_leaves=True): INPUT: - - ``with_leaves`` -- (default: ``True``) a Boolean, determining - whether the resulting graph will be formed from the leaves - and the nodes of ``self`` (if ``True``), or only from the - nodes of ``self`` (if ``False``) + - ``with_leaves`` -- boolean (default: ``True``); whether the resulting + graph will be formed from the leaves and the nodes of ``self`` (if + ``True``), or only from the nodes of ``self`` (if ``False``) EXAMPLES:: @@ -870,7 +869,7 @@ def show(self, with_leaves=False): sage: t1.show() # needs sage.plot """ try: - self.graph(with_leaves=with_leaves).show(layout='tree', tree_root=0, tree_orientation="down") + self.graph(with_leaves=with_leaves).show(layout='tree', tree_root=0, tree_orientation='down') except RuntimeError: # This is for the border case BinaryTree().show(). self.graph(with_leaves=with_leaves).show() @@ -943,7 +942,7 @@ def make_leaf(self): self._require_mutable() self.__init__(self.parent(), None) - def _to_dyck_word_rec(self, usemap="1L0R"): + def _to_dyck_word_rec(self, usemap='1L0R'): r""" EXAMPLES:: @@ -1149,7 +1148,7 @@ def tamari_join(self, other): b = other.to_132_avoiding_permutation() return a.permutohedron_join(b).binary_search_tree_shape(left_to_right=False) - def tamari_meet(self, other, side="right"): + def tamari_meet(self, other, side='right'): r""" Return the meet of the binary trees ``self`` and ``other`` (of equal size) in the `n`-th Tamari poset (where `n` is @@ -1238,13 +1237,14 @@ def tamari_meet(self, other, side="right"): return from_tamari_sorting_tuple(meet) @combinatorial_map(name="to Dyck paths: up step, left tree, down step, right tree") - def to_dyck_word(self, usemap="1L0R"): + def to_dyck_word(self, usemap='1L0R'): r""" Return the Dyck word associated with ``self`` using the given map. INPUT: - - ``usemap`` -- a string, either ``1L0R``, ``1R0L``, ``L1R0``, ``R1L0`` + - ``usemap`` -- string; either ``'1L0R'``, ``'1R0L'``, ``'L1R0'``, + ``'R1L0'`` The bijection is defined recursively as follows: @@ -1294,7 +1294,7 @@ def to_dyck_word(self, usemap="1L0R"): raise ValueError("%s is not a correct map" % usemap) return DyckWord(self._to_dyck_word_rec(usemap)) - def _to_ordered_tree(self, bijection="left", root=None): + def _to_ordered_tree(self, bijection='left', root=None): r""" Internal recursive method to obtain an ordered tree from a binary tree. @@ -1304,16 +1304,16 @@ def _to_ordered_tree(self, bijection="left", root=None): sage: bt = BinaryTree([[],[]]) sage: bt._to_ordered_tree() [[], [[]]] - sage: bt._to_ordered_tree(bijection="right") + sage: bt._to_ordered_tree(bijection='right') [[[]], []] - sage: bt._to_ordered_tree(bijection="none") + sage: bt._to_ordered_tree(bijection='none') Traceback (most recent call last): ... ValueError: the bijection argument should be either left or right sage: bt = BinaryTree([[[], [[], None]], [[], []]]) sage: bt._to_ordered_tree() [[], [[], []], [[], [[]]]] - sage: bt._to_ordered_tree(bijection="right") + sage: bt._to_ordered_tree(bijection='right') [[[[]], [[]]], [[]], []] """ close_root = False @@ -1378,7 +1378,7 @@ def to_ordered_tree_right_branch(self): sage: bt.to_ordered_tree_right_branch() [[[[]], [[]]], [[]], []] """ - return self._to_ordered_tree(bijection="right") + return self._to_ordered_tree(bijection='right') def _postfix_word(self, left_first=True, start=1): r""" @@ -1426,7 +1426,7 @@ def tamari_sorting_tuple(self, reverse=False): INPUT: - - ``reverse`` -- boolean (default ``False``) if ``True``, + - ``reverse`` -- boolean (default: ``False``); if ``True``, return instead the result for the left-right symmetric of the binary tree @@ -1544,10 +1544,10 @@ def to_undirected_graph(self, with_leaves=False): INPUT: - - ``with_leaves`` -- (default: ``False``) a Boolean, determining - whether the resulting graph will be formed from the leaves - and the nodes of ``self`` (if ``True``), or only from the - nodes of ``self`` (if ``False``) + - ``with_leaves`` -- boolean (default: ``False``); whether the + resulting graph will be formed from the leaves and the nodes of + ``self`` (if ``True``), or only from the nodes of ``self`` (if + ``False``) EXAMPLES:: @@ -1592,9 +1592,7 @@ def to_tilting(self): method provides the coordinates of this depiction, with the root as the top-left vertex. - OUTPUT: - - a list of pairs of integers. + OUTPUT: list of pairs of integers Every vertex of the binary tree is mapped to a pair of integers. The conventions are the following. The root has @@ -1634,11 +1632,9 @@ def _to_tilting_rec(self, shift=0): INPUT: - - ``shift`` -- an integer (default 0) - - OUTPUT: + - ``shift`` -- integer (default: 0) - list of tilting coordinates and number of leaves + OUTPUT: list of tilting coordinates and number of leaves EXAMPLES:: @@ -1674,13 +1670,13 @@ def to_poset(self, with_leaves=False, root_to_leaf=False): INPUT: - - ``with_leaves`` -- (default: ``False``) a Boolean, determining - whether the resulting poset will be formed from the leaves - and the nodes of ``self`` (if ``True``), or only from the - nodes of ``self`` (if ``False``) - - ``root_to_leaf`` -- (default: ``False``) a Boolean, - determining whether the poset orientation should be from root - to leaves (if ``True``) or from leaves to root (if ``False``). + - ``with_leaves`` -- boolean (default: ``False``); whether the + resulting poset will be formed from the leaves and the nodes of + ``self`` (if ``True``), or only from the nodes of ``self`` (if + ``False``) + - ``root_to_leaf`` -- boolean (default: ``False``); whether the poset + orientation should be from root to leaves (if ``True``) or from + leaves to root (if ``False``) EXAMPLES:: @@ -2529,12 +2525,10 @@ def comb(self, side='left'): INPUT: - - ``side`` -- (default: 'left') set to 'left' to obtain a left - comb, and to 'right' to obtain a right comb. + - ``side`` -- (default: ``'left'``) set to ``'left'`` to obtain a left + comb, and to ``'right'`` to obtain a right comb - OUTPUT: - - A list of binary trees. + OUTPUT: list of binary trees .. SEEALSO:: @@ -2671,9 +2665,7 @@ def twisting_number(self): composing it. A left (resp. right) branch is maximal if it is not included in a strictly longer left (resp. right) branch. - OUTPUT: - - A list of two integers + OUTPUT: list of two integers EXAMPLES:: @@ -2822,7 +2814,7 @@ def q_hook_length_fraction(self, q=None, q_factor=False): set to be the indeterminate `q` in the polynomial ring `\ZZ[q]`) - - ``q_factor`` -- a Boolean (default: ``False``) which + - ``q_factor`` -- a Boolean (default: ``False``); which determines whether to compute `h_{q} (T)` or to compute `f_{q} (T)` (namely, `h_{q} (T)` is obtained when ``q_factor == False``, and `f_{q} (T)` is obtained when @@ -3674,9 +3666,7 @@ def to_full(self): `T` which does not have 2 children. The resulting tree will have `2n + 1` nodes. - OUTPUT: - - A full binary tree. See :meth:`is_full` for the definition of full. + OUTPUT: a full binary tree. See :meth:`is_full` for the definition of full .. SEEALSO:: @@ -3716,7 +3706,6 @@ def to_full(self): sage: BinaryTree(None).to_full() [., .] - """ if self.is_empty(): return BinaryTree("[.,.]") @@ -3738,9 +3727,7 @@ def prune(self): bt == bt.prune().to_full() - OUTPUT: - - A binary tree. + OUTPUT: a binary tree .. SEEALSO:: @@ -3938,8 +3925,8 @@ class BinaryTrees(UniqueRepresentation, Parent): INPUT: - - ``size`` -- (optional) an integer - - ``full`` -- (optional) a boolean + - ``size`` -- integer (optional) + - ``full`` -- boolean (optional) OUTPUT: @@ -4051,7 +4038,7 @@ def from_tamari_sorting_tuple(key): INPUT: - - ``key`` -- a tuple of integers + - ``key`` -- tuple of integers EXAMPLES:: @@ -4238,7 +4225,7 @@ def _an_element_(self): def cardinality(self): """ - The cardinality of ``self`` + The cardinality of ``self``. This is a Catalan number. @@ -4487,7 +4474,7 @@ def _an_element_(self): def cardinality(self): r""" - The cardinality of ``self`` + The cardinality of ``self``. This is a Catalan number. @@ -4641,10 +4628,10 @@ class LabelledBinaryTree(AbstractLabelledClonableTree, BinaryTree): anyway!). - ``label`` -- (default: ``None``) the label to be put on the root - of this tree. + of this tree - - ``check`` -- (default: ``True``) whether checks should be - performed or not. + - ``check`` -- boolean (default: ``True``); whether checks should be + performed or not .. TODO:: @@ -4656,7 +4643,7 @@ class LabelledBinaryTree(AbstractLabelledClonableTree, BinaryTree): sage: LabelledBinaryTree(None) . - sage: LabelledBinaryTree(None, label="ae") # not well supported + sage: LabelledBinaryTree(None, label='ae') # not well supported 'ae' sage: LabelledBinaryTree([]) None[., .] @@ -5195,7 +5182,7 @@ def _an_element_(self): t = LT([], label=3) t1 = LT([t, t], label=42) t2 = LT([[], []], label=5) - return LT([t1, t2], label="toto") + return LT([t1, t2], label='toto') def unlabelled_trees(self): """ @@ -5241,9 +5228,9 @@ def binary_search_tree_shape(w, left_to_right=True): INPUT: - - ``w`` -- a list of integers + - ``w`` -- list of integers - - ``left_to_right`` -- boolean (default ``True``) + - ``left_to_right`` -- boolean (default: ``True``) OUTPUT: a non labelled binary tree diff --git a/src/sage/combinat/cartesian_product.py b/src/sage/combinat/cartesian_product.py index ef151e55ffa..7bf3590550f 100644 --- a/src/sage/combinat/cartesian_product.py +++ b/src/sage/combinat/cartesian_product.py @@ -170,7 +170,7 @@ def __repr__(self): def cardinality(self): r""" - Returns the number of elements in the Cartesian product of + Return the number of elements in the Cartesian product of everything in \*iters. EXAMPLES:: @@ -200,7 +200,7 @@ def __len__(self): An ``int``, the number of elements in the Cartesian product. If the number of elements is infinite or does not fit into a python ``int``, a - :class:`TypeError` is raised. + :exc:`TypeError` is raised. .. SEEALSO:: @@ -225,7 +225,7 @@ def __len__(self): def list(self): """ - Returns + Return. EXAMPLES:: diff --git a/src/sage/combinat/chas/fsym.py b/src/sage/combinat/chas/fsym.py index 10210028932..b28307e1ed9 100644 --- a/src/sage/combinat/chas/fsym.py +++ b/src/sage/combinat/chas/fsym.py @@ -72,7 +72,7 @@ def __init__(self, alg, graded=True): CombinatorialFreeModule.__init__(self, alg.base_ring(), StandardTableaux(), category=FSymBases(alg), - bracket="", prefix=self._prefix) + bracket='', prefix=self._prefix) def _coerce_map_from_(self, R): r""" @@ -269,7 +269,7 @@ def basis(self, degree=None): r""" The basis elements (optionally: of the specified degree). - OUTPUT: Family + OUTPUT: family EXAMPLES:: @@ -351,7 +351,7 @@ def duality_pairing_matrix(self, basis, degree): INPUT: - ``basis`` -- a basis of the dual Hopf algebra - - ``degree`` -- a non-negative integer + - ``degree`` -- nonnegative integer OUTPUT: diff --git a/src/sage/combinat/chas/wqsym.py b/src/sage/combinat/chas/wqsym.py index 567e1f1b9f5..50811f08cb8 100644 --- a/src/sage/combinat/chas/wqsym.py +++ b/src/sage/combinat/chas/wqsym.py @@ -75,7 +75,7 @@ def sorting_key(X): OrderedSetPartitions(), category=WQSymBases(alg, graded), sorting_key=sorting_key, - bracket="", prefix=self._prefix) + bracket='', prefix=self._prefix) def _repr_term(self, osp): r""" @@ -549,12 +549,12 @@ class options(GlobalOptions): NAME = 'WordQuasiSymmetricFunctions element' module = 'sage.combinat.chas.wqsym' option_class = 'WordQuasiSymmetricFunctions' - objects = dict(default="compositions", + objects = dict(default='compositions', description='Specifies how basis elements of WordQuasiSymmetricFunctions should be indexed', values=dict(compositions="Indexing the basis by ordered set partitions", words="Indexing the basis by packed words"), case_sensitive=False) - display = dict(default="normal", + display = dict(default='normal', description='Specifies how basis elements of WordQuasiSymmetricFunctions should be printed', values=dict(normal="Using the normal representation", tight="Dropping spaces after commas", @@ -918,7 +918,7 @@ def __init__(self, alg): WQSymBasis_abstract.__init__(self, alg) X = self.realization_of().X() - phi = self.module_morphism(self._C_to_X, codomain=X, unitriangular="upper") + phi = self.module_morphism(self._C_to_X, codomain=X, unitriangular='upper') phi.register_as_coercion() inv_phi = ~phi inv_phi.register_as_coercion() @@ -1067,9 +1067,9 @@ def __init__(self, alg): WQSymBasis_abstract.__init__(self, alg) M = self.realization_of().M() - phi = self.module_morphism(self._Q_to_M, codomain=M, unitriangular="lower") + phi = self.module_morphism(self._Q_to_M, codomain=M, unitriangular='lower') phi.register_as_coercion() - phi_inv = M.module_morphism(self._M_to_Q, codomain=self, unitriangular="lower") + phi_inv = M.module_morphism(self._M_to_Q, codomain=self, unitriangular='lower') phi_inv.register_as_coercion() def some_elements(self): @@ -1449,9 +1449,9 @@ def __init__(self, alg): WQSymBasis_abstract.__init__(self, alg) M = self.realization_of().M() - phi = self.module_morphism(self._Phi_to_M, codomain=M, unitriangular="lower") + phi = self.module_morphism(self._Phi_to_M, codomain=M, unitriangular='lower') phi.register_as_coercion() - phi_inv = M.module_morphism(self._M_to_Phi, codomain=self, unitriangular="lower") + phi_inv = M.module_morphism(self._M_to_Phi, codomain=self, unitriangular='lower') phi_inv.register_as_coercion() def some_elements(self): @@ -2572,9 +2572,7 @@ def to_quasisymmetric_function(self): sizes of the blocks of `P`. This `\pi` is a ring homomorphism. - OUTPUT: - - - an element of the quasisymmetric functions in the monomial basis + OUTPUT: an element of the quasisymmetric functions in the monomial basis EXAMPLES:: diff --git a/src/sage/combinat/cluster_algebra_quiver/cluster_seed.py b/src/sage/combinat/cluster_algebra_quiver/cluster_seed.py index f26523cc60c..5ab85f84208 100644 --- a/src/sage/combinat/cluster_algebra_quiver/cluster_seed.py +++ b/src/sage/combinat/cluster_algebra_quiver/cluster_seed.py @@ -70,7 +70,7 @@ class ClusterSeed(SageObject): * :class:`QuiverMutationType` - * :class:`str` -- a string representing a :class:`QuiverMutationType` + * :class:`str` -- string representing a :class:`QuiverMutationType` or a common quiver type (see Examples) * :class:`ClusterQuiver` @@ -387,14 +387,16 @@ def __init__(self, data, frozen=None, is_principal=False, user_labels=None, user def use_c_vectors(self, use=True, bot_is_c=False, force=False): r""" - Reconstruct c-vectors from other data or initialize if no usable data exists. + Reconstruct `c`-vectors from other data or initialize if no usable data + exists. Warning: Initialization may lead to inconsistent data. INPUT: - - ``use`` -- (default: ``True``) If ``True``, will use c-vectors - - ``bot_is_c`` -- (default: ``False``) If ``True`` and + - ``use`` -- boolean (default: ``True``); if ``True``, will use + `c`-vectors + - ``bot_is_c`` -- boolean (default: ``False``); if ``True`` and :class:`ClusterSeed` ``self`` has ``self._m == self._n``, then will assume bottom half of the extended exchange matrix is the c-matrix. If ``True``, lets the :class:`ClusterSeed` know c-vectors can be @@ -470,7 +472,8 @@ def use_c_vectors(self, use=True, bot_is_c=False, force=False): def use_g_vectors(self, use=True, force=False): r""" - Reconstruct g-vectors from other data or initialize if no usable data exists. + Reconstruct g-vectors from other data or initialize if no usable data + exists. .. warning:: @@ -478,7 +481,8 @@ def use_g_vectors(self, use=True, force=False): INPUT: - - ``use`` -- (default: ``True``) If ``True``, will use g-vectors + - ``use`` -- boolean (default: ``True``); if ``True``, will use + g-vectors EXAMPLES:: @@ -554,7 +558,8 @@ def use_g_vectors(self, use=True, force=False): def use_d_vectors(self, use=True, force=False): r""" - Reconstruct d-vectors from other data or initialize if no usable data exists. + Reconstruct `d`-vectors from other data or initialize if no usable data + exists. .. warning:: @@ -562,7 +567,8 @@ def use_d_vectors(self, use=True, force=False): INPUT: - - ``use`` -- (default: ``True``) If ``True``, will use d-vectors + - ``use`` -- boolean (default: ``True``); if ``True``, will use + `d`-vectors EXAMPLES:: @@ -640,17 +646,18 @@ def use_d_vectors(self, use=True, force=False): def use_fpolys(self, use=True, user_labels=None, user_labels_prefix=None): r""" - Use F-polynomials in our Cluster Seed + Use `F`-polynomials in our Cluster Seed. Note: This will automatically try to recompute the cluster variables if possible INPUT: - - ``use`` -- (default: ``True``) If ``True``, will use F-polynomials - - ``user_labels`` -- (default: ``None``) If set, will overwrite the - default cluster variable labels - - ``user_labels_prefix`` -- (default: ``None``) If set, will overwrite + - ``use`` -- boolean (default: ``True``); if ``True``, will use + `F`-polynomials + - ``user_labels`` -- (default: ``None``) if set, will overwrite the + default cluster variable ``labels`` + - ``user_labels_prefix`` -- (default: ``None``) if set, will overwrite the default EXAMPLES:: @@ -746,7 +753,8 @@ def track_mutations(self, use=True): INPUT: - - ``use`` -- (default: ``True``) If ``True``, will begin filling the mutation path + - ``use`` -- boolean (default: ``True``); if ``True``, will begin + filling the mutation path EXAMPLES:: @@ -801,8 +809,8 @@ def _sanitize_init_vars(self, user_labels, user_labels_prefix='x'): INPUT: - - ``user_labels`` -- The labels that need sanitizing - - ``user_labels_prefix`` -- (default: ``'x'``) The prefix to use + - ``user_labels`` -- the labels that need sanitizing + - ``user_labels_prefix`` -- (default: ``'x'``) the prefix to use for labels if integers given for labels EXAMPLES:: @@ -870,9 +878,9 @@ def set_c_matrix(self, data): INPUT: - - ``data`` -- The matrix to set the c-matrix to. Also allowed + - ``data`` -- the matrix to set the c-matrix to; also allowed to be a quiver or cluster seed, in which case the b-matrix - is used. + is used EXAMPLES:: @@ -1026,18 +1034,18 @@ def plot(self, circular=False, mark=None, save_pos=False, force_c=False, with_gr INPUT: - - ``circular`` -- (default: ``False``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used - ``mark`` -- (default: ``None``) if set to i, the vertex i is - highlighted. - - ``save_pos`` -- (default: ``False``) if ``True``, the positions - of the vertices are saved. - - ``force_c`` -- (default: ``False``) if ``True``, will show the frozen - vertices even if they were never initialized - - ``with_greens`` -- (default: ``False``) if ``True``, will display - the green vertices in green - - ``add_labels`` -- (default: ``False``) if ``True``, will use the - initial variables as labels + highlighted + - ``save_pos`` -- boolean (default: ``False``); if ``True``, the + positions of the vertices are saved + - ``force_c`` -- boolean (default: ``False``); if ``True``, will show + the frozen vertices even if they were never initialized + - ``with_greens`` -- boolean (default: ``False``); if ``True``, will + display the green vertices in green + - ``add_labels`` -- boolean (default: ``False``); if ``True``, will use + the initial variables as labels EXAMPLES:: @@ -1071,19 +1079,19 @@ def show(self, fig_size=1, circular=False, mark=None, save_pos=False, force_c=Fa INPUT: - ``fig_size`` -- (default: 1) factor by which the size of the plot - is multiplied. - - ``circular`` -- (default: ``False``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. + is multiplied + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used - ``mark`` -- (default: ``None``) if set to i, the vertex i is - highlighted. - - ``save_pos`` -- (default: ``False``) if ``True``, the positions - of the vertices are saved. - - ``force_c`` -- (default: ``False``) if ``True``, will show the frozen - vertices even if they were never initialized - - ``with_greens`` -- (default: ``False``) if ``True``, will display the - green vertices in green - - ``add_labels`` -- (default: ``False``) if ``True``, will use the - initial variables as labels + highlighted + - ``save_pos`` -- boolean (default: ``False``); if ``True``, the + positions of the vertices are saved + - ``force_c`` -- boolean (default: ``False``); if ``True``, will show + the frozen vertices even if they were never initialized + - ``with_greens`` -- boolean (default: ``False``); if ``True``, will + display the green vertices in green + - ``add_labels`` -- boolean (default: ``False``); if ``True``, will use + the initial variables as labels TESTS:: @@ -1114,10 +1122,10 @@ def interact(self, fig_size=1, circular=True): INPUT: - ``fig_size`` -- (default: 1) factor by which the size of the - plot is multiplied. + plot is multiplied - - ``circular`` -- (default: ``True``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. + - ``circular`` -- boolean (default: ``True``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used TESTS:: @@ -1133,18 +1141,19 @@ def save_image(self, filename, circular=False, mark=None, save_pos=False): INPUT: - - ``filename`` -- the filename the image is saved to. - - ``circular`` -- (default: ``False``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. - - ``mark`` -- (default: ``None``) if set to i, the vertex i is highlighted. - - ``save_pos`` -- (default: ``False``) if ``True``, the positions - of the vertices are saved. + - ``filename`` -- the filename the image is saved to + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used + - ``mark`` -- (default: ``None``) if set to i, the vertex i is + highlighted + - ``save_pos`` -- boolean (default: ``False``); if ``True``, the + positions of the vertices are saved EXAMPLES:: sage: S = ClusterSeed(['F',4,[1,2]]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # needs sage.plot sage.symbolic + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # needs sage.plot sage.symbolic ....: S.save_image(f.name) """ graph_plot = self.plot(circular=circular, mark=mark, save_pos=save_pos) @@ -1212,7 +1221,7 @@ def x(self, k): sage: S.x(2) x2 - sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format="list_of_edges") + sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format='list_of_edges') sage: S = ClusterSeed(dg, frozen=['c']) sage: S.x(0) a @@ -1251,7 +1260,7 @@ def y(self, k): sage: S.y(2) y2 - sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format="list_of_edges") + sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format='list_of_edges') sage: S = ClusterSeed(dg, frozen=['c']) sage: S.y(0) c @@ -1358,7 +1367,7 @@ def mutations(self): def cluster_variable(self, k): r""" - Generates a cluster variable using F-polynomials + Generates a cluster variable using F-polynomials. EXAMPLES:: @@ -1708,7 +1717,6 @@ def c_vector(self, k): A seed for a cluster algebra of rank 2 with 2 frozen variables sage: S.c_vector(0) (1, -1) - """ if k not in range(self._n): raise ValueError("The cluster seed does not have a c-vector of index %s." % k) @@ -1858,7 +1866,6 @@ def _d_mutate(self, k): [ 0 0 -1] sage: S.d_vector(0) (1, 0, 0) - """ B = self.b_matrix() D = copy(self._D) @@ -1953,12 +1960,13 @@ def is_acyclic(self) -> bool: def is_bipartite(self, return_bipartition=False): r""" - Return ``True`` iff ``self`` is bipartite (i.e., if the underlying quiver is bipartite). + Return ``True`` iff ``self`` is bipartite (i.e., if the underlying + quiver is bipartite). INPUT: - - ``return_bipartition`` -- (default: ``False``) if ``True``, the - bipartition is returned in the case of ``self`` being bipartite. + - ``return_bipartition`` -- boolean (default: ``False``); if ``True``, + the bipartition is returned in the case of ``self`` being bipartite EXAMPLES:: @@ -1974,12 +1982,10 @@ def green_vertices(self): r""" Return the list of green vertices of ``self``. - A vertex is defined to be green if its c-vector has all non-positive + A vertex is defined to be green if its c-vector has all nonpositive entries. More information on green vertices can be found at [BDP2013]_ - OUTPUT: - - The green vertices as a list of integers. + OUTPUT: the green vertices as a list of integers EXAMPLES:: @@ -2000,7 +2006,7 @@ def first_green_vertex(self): r""" Return the first green vertex of ``self``. - A vertex is defined to be green if its c-vector has all non-positive entries. + A vertex is defined to be green if its c-vector has all nonpositive entries. More information on green vertices can be found at [BDP2013]_ EXAMPLES:: @@ -2025,12 +2031,10 @@ def red_vertices(self): r""" Return the list of red vertices of ``self``. - A vertex is defined to be red if its c-vector has all non-negative entries. + A vertex is defined to be red if its c-vector has all nonnegative entries. More information on red vertices can be found at [BDP2013]_. - OUTPUT: - - The red vertices as a list of integers. + OUTPUT: the red vertices as a list of integers EXAMPLES:: @@ -2044,7 +2048,6 @@ def red_vertices(self): sage: Q.mutate(1) sage: Q.red_vertices() [1] - """ # Make sure we have c vectors on if not self._use_c_vec: @@ -2056,7 +2059,7 @@ def first_red_vertex(self): r""" Return the first red vertex of ``self``. - A vertex is defined to be red if its c-vector has all non-negative entries. + A vertex is defined to be red if its c-vector has all nonnegative entries. More information on red vertices can be found at [BDP2013]_. EXAMPLES:: @@ -2069,7 +2072,6 @@ def first_red_vertex(self): sage: Q.mutate(1) sage: Q.first_red_vertex() 1 - """ # Make sure we have c vectors if not self._use_c_vec: @@ -2090,7 +2092,8 @@ def urban_renewals(self, return_first=False): INPUT: - - ``return_first`` -- (default: ``False``) if ``True``, will return the first urban renewal + - ``return_first`` -- boolean (default: ``False``); if ``True``, will + return the first urban renewal OUTPUT: @@ -2132,11 +2135,9 @@ def highest_degree_denominator(self, filter=None): INPUT: - - ``filter`` -- a list or iterable - - OUTPUT: + - ``filter`` -- list or iterable - An integer. + OUTPUT: integer EXAMPLES:: @@ -2181,7 +2182,7 @@ def smallest_c_vector(self): r""" Return the vertex with the smallest c-vector. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -2209,7 +2210,7 @@ def smallest_c_vector(self): def most_decreased_edge_after_mutation(self): r""" - Return the vertex that will produce the least degrees after mutation + Return the vertex that will produce the least degrees after mutation. EXAMPLES:: @@ -2237,7 +2238,7 @@ def most_decreased_edge_after_mutation(self): def most_decreased_denominator_after_mutation(self): r""" - Return the vertex that will produce the most decrease in denominator degrees after mutation + Return the vertex that will produce the most decrease in denominator degrees after mutation. EXAMPLES:: @@ -2273,32 +2274,32 @@ def mutate(self, sequence, inplace=True, input_type=None): ``self``, a function which takes in the :class:`ClusterSeed` and returns a vertex or an iterator of vertices, or a string representing a type of vertices to mutate - - ``inplace`` -- (default: ``True``) if ``False``, the result is - returned, otherwise ``self`` is modified + - ``inplace`` -- boolean (default: ``True``); if ``False``, the result + is returned, otherwise ``self`` is modified - ``input_type`` -- (default: ``None``) indicates the type of data contained in the sequence Possible values for vertex types in ``sequence`` are: - - ``"first_source"``: mutates at first found source vertex, - - ``"sources"``: mutates at all sources, - - ``"first_sink"``: mutates at first sink, - - ``"sinks"``: mutates at all sink vertices, - - ``"green"``: mutates at the first green vertex, - - ``"red"``: mutates at the first red vertex, - - ``"urban_renewal"`` or ``"urban"``: mutates at first urban renewal vertex, - - ``"all_urban_renewals"`` or ``"all_urban"``: mutates at all - urban renewal vertices. + - ``'first_source'`` -- mutates at first found source vertex + - ``'sources'`` -- mutates at all sources + - ``'first_sink'`` -- mutates at first sink + - ``'sinks'`` -- mutates at all sink vertices + - ``'green'`` -- mutates at the first green vertex + - ``'red'`` -- mutates at the first red vertex + - ``'urban_renewal'`` or ``'urban'`` -- mutates at first urban renewal vertex + - ``'all_urban_renewals'`` or ``'all_urban'`` -- mutates at all + urban renewal vertices For ``input_type``, if no value is given, preference will be given to vertex names, then indices, then cluster variables. If all input is not of the same type, an error is given. Possible values for ``input_type`` are: - - ``"vertices"``: interprets the input sequence as vertices - - ``"indices"``: interprets the input sequence as indices - - ``"cluster_vars"``: interprets the input sequence as cluster variables - this must be selected if inputting a sequence of cluster variables. + - ``'vertices'`` -- interprets the input sequence as vertices + - ``'indices'`` -- interprets the input sequence as indices + - ``'cluster_vars'`` -- interprets the input sequence as cluster variables. + This must be selected if inputting a sequence of cluster variables. EXAMPLES:: @@ -2431,7 +2432,7 @@ def mutate(self, sequence, inplace=True, input_type=None): Mutating at vertices by default. sage: S.cluster() [(x2 + 1)/x1, x2, c] - sage: S.mutate(1, input_type="indices") + sage: S.mutate(1, input_type='indices') sage: S.cluster() [(x2 + 1)/x1, (x2*c + x1 + c)/(x1*x2), c] @@ -2444,7 +2445,7 @@ def mutate(self, sequence, inplace=True, input_type=None): Mutating at vertices by default. sage: S.cluster() [(a*c*d + 1)/b, a, c, d] - sage: S.mutate('a', input_type="cluster_vars") + sage: S.mutate('a', input_type='cluster_vars') sage: S.cluster() [(a*c*d + 1)/b, (a*c*d + b + 1)/(a*b), c, d] sage: S.mutate(['(a*c*d + 1)/b', 'd']) @@ -2608,7 +2609,7 @@ def mutate(self, sequence, inplace=True, input_type=None): index_list = [] for cluster_var in seqq: new_index = mutation_seed.cluster_index(cluster_var) - mutation_seed.mutate(new_index, input_type="indices") + mutation_seed.mutate(new_index, input_type='indices') index_list.append(new_index) except (ValueError, TypeError): raise ValueError('input interpreted as cluster variables,' @@ -2677,9 +2678,7 @@ def cluster_index(self, cluster_str): - ``cluster_str`` -- the string to look for in the cluster - OUTPUT: - - An integer or ``None`` if the string is not a cluster variable + OUTPUT: integer or ``None`` if the string is not a cluster variable EXAMPLES:: @@ -2687,7 +2686,6 @@ def cluster_index(self, cluster_str): sage: S.cluster_index('x') sage: S.cluster_index('(y+1)/x') 0 - """ if self._use_fpolys and isinstance(cluster_str, str): c = FractionField(self._R)(cluster_str) @@ -2709,24 +2707,24 @@ def mutation_sequence(self, sequence, show_sequence=False, INPUT: - - ``sequence`` -- an iterable of vertices of self. + - ``sequence`` -- an iterable of vertices of self - - ``show_sequence`` -- (default: ``False``) if ``True``, a png - containing the associated quivers is shown. + - ``show_sequence`` -- boolean (default: ``False``); if ``True``, a png + containing the associated quivers is shown - ``fig_size`` -- (default: 1.2) factor by which the size of - the plot is multiplied. + the plot is multiplied - ``return_output`` -- (default: ``'seed'``) determines what output is to be returned: * if ``'seed'``, outputs all the cluster seeds obtained - by the ``sequence`` of mutations. + by the ``sequence`` of mutations - * if ``'matrix'``, outputs a list of exchange matrices. + * if ``'matrix'``, outputs a list of exchange matrices * if ``'var'``, outputs a list of new cluster variables obtained - at each step. + at each step EXAMPLES:: @@ -2768,34 +2766,35 @@ def mutation_sequence(self, sequence, show_sequence=False, def mutation_analysis(self, options=['all'], filter=None): r""" - Runs an analysis of all potential mutation options. Note that this might take a long time on large seeds. + Run an analysis of all potential mutation options. Note that this might + take a long time on large seeds. - .. note:: + .. NOTE:: Edges are only returned if we have a non-valued quiver. Green and red vertices are only returned if the cluster is principal. INPUT: - - ``options`` -- (default: ``['all']``) a list of mutation options. - - ``filter`` -- (default: ``None``) A vertex or interval of vertices to limit our search to + - ``options`` -- (default: ``['all']``) a list of mutation options + - ``filter`` -- (default: ``None``) a vertex or interval of vertices to limit our search to Possible options are: - - ``"all"`` -- All options below - - ``"edges"`` -- Number of edges (works with skew-symmetric quivers) - - ``"edge_diff"`` -- Edges added/deleted (works with skew-symmetric quivers) - - ``"green_vertices"`` -- List of green vertices (works with principals) - - ``"green_vertices_diff"`` -- Green vertices added/removed (works with principals) - - ``"red_vertices"`` -- List of red vertices (works with principals) - - ``"red_vertices_diff"`` -- Red vertices added/removed (works with principals) - - ``"urban_renewals"`` -- List of urban renewal vertices - - ``"urban_renewals_diff"`` -- Urban renewal vertices added/removed - - ``"sources"`` -- List of source vertices - - ``"sources_diff"`` -- Source vertices added/removed - - ``"sinks"`` -- List of sink vertices - - ``"sinks_diff"`` -- Sink vertices added/removed - - ``"denominators"`` -- List of all denominators of the cluster variables + - ``'all'`` -- all options below + - ``'edges'`` -- number of edges (works with skew-symmetric quivers) + - ``'edge_diff'`` -- edges added/deleted (works with skew-symmetric quivers) + - ``'green_vertices'`` -- list of green vertices (works with principals) + - ``'green_vertices_diff'`` -- green vertices added/removed (works with principals) + - ``'red_vertices'`` -- list of red vertices (works with principals) + - ``'red_vertices_diff'`` -- red vertices added/removed (works with principals) + - ``'urban_renewals'`` -- list of urban renewal vertices + - ``'urban_renewals_diff'`` -- urban renewal vertices added/removed + - ``'sources'`` -- list of source vertices + - ``'sources_diff'`` -- source vertices added/removed + - ``'sinks'`` -- list of sink vertices + - ``'sinks_diff'`` -- sink vertices added/removed + - ``'denominators'`` -- list of all denominators of the cluster variables OUTPUT: @@ -3022,7 +3021,6 @@ def exchangeable_part(self): sage: T.exchangeable_part().quiver().digraph().edges(sort=True) [(0, 1, (1, -1)), (2, 1, (1, -1))] - """ from sage.combinat.cluster_algebra_quiver.mutation_class import _principal_part eval_dict = {self.y(i): 1 for i in range(self._m)} @@ -3259,7 +3257,7 @@ def reorient(self, data): def set_cluster(self, cluster, force=False): r""" - Sets the cluster for ``self`` to ``cluster``. + Set the cluster for ``self`` to ``cluster``. .. warning:: @@ -3267,7 +3265,7 @@ def set_cluster(self, cluster, force=False): INPUT: - - ``cluster`` -- an iterable defining a cluster for ``self``. + - ``cluster`` -- an iterable defining a cluster for ``self`` EXAMPLES:: @@ -3420,16 +3418,17 @@ def mutation_class_iter(self, depth=infinity, show_depth=False, INPUT: - ``depth`` -- (default: infinity) integer or infinity, only seeds with - distance at most ``depth`` from ``self`` are returned. - - ``show_depth`` -- (default: ``False``) if ``True``, the current depth - of the mutation is shown while computing. - - ``return_paths`` -- (default: ``False``) if ``True``, a shortest path - of mutations from ``self`` to the given quiver is returned as well. - - ``up_to_equivalence`` -- (default: ``True``) if ``True``, only one - seed up to simultaneous permutation of rows and columns of the - exchange matrix is recorded. - - ``sink_source`` -- (default: ``False``) if ``True``, only mutations - at sinks and sources are applied. + distance at most ``depth`` from ``self`` are returned + - ``show_depth`` -- boolean (default: ``False``); if ``True``, the + current depth of the mutation is shown while computing + - ``return_paths`` -- boolean (default: ``False``); if ``True``, a + shortest path of mutations from ``self`` to the given quiver is + returned as well + - ``up_to_equivalence`` -- boolean (default: ``True``); if ``True``, + only one seed up to simultaneous permutation of rows and columns of + the exchange matrix is recorded + - ``sink_source`` -- boolean (default: ``False``); if ``True``, only + mutations at sinks and sources are applied EXAMPLES: @@ -3577,7 +3576,7 @@ def mutation_class_iter(self, depth=infinity, show_depth=False, # If we aren't only sinking the source if not only_sink_source or all(entry >= 0 for entry in sd[0]._M.row(i)) or all(entry <= 0 for entry in sd[0]._M.row(i)): # do an inplace mutation on our cluster (sd[0]) - sd2 = sd[0].mutate(i, inplace=False, input_type="indices") + sd2 = sd[0].mutate(i, inplace=False, input_type='indices') # set up our new cluster variables if up_to_equivalence: @@ -3624,17 +3623,17 @@ def mutation_class(self, depth=infinity, show_depth=False, return_paths=False, INPUT: - - ``depth`` -- (default: ``infinity`) integer, only seeds with + - ``depth`` -- (default: ``infinity``) integer, only seeds with distance at most depth from ``self`` are returned - - ``show_depth`` -- (default: ``False``) if ``True``, the actual depth - of the mutation is shown - - ``return_paths`` -- (default: ``False``) if ``True``, a shortest - path of mutation sequences from self to the given quiver is + - ``show_depth`` -- boolean (default: ``False``); if ``True``, the + actual depth of the mutation is shown + - ``return_paths`` -- boolean (default: ``False``); if ``True``, a + shortest path of mutation sequences from self to the given quiver is returned as well - - ``up_to_equivalence`` -- (default: ``True``) if ``True``, only - seeds up to equivalence are considered - - ``sink_source`` -- (default: ``False``) if ``True``, only mutations - at sinks and sources are applied + - ``up_to_equivalence`` -- boolean (default: ``True``); if ``True``, + only seeds up to equivalence are considered + - ``sink_source`` -- boolean (default: ``False``); if ``True``, only + mutations at sinks and sources are applied EXAMPLES: @@ -3656,11 +3655,12 @@ def cluster_class_iter(self, depth=infinity, show_depth=False, up_to_equivalence - ``depth`` -- (default: infinity) integer or infinity, only seeds with distance at most ``depth`` from ``self`` are returned - - ``show_depth`` -- (default: ``False``) if ``True``, ignored if - ``depth`` is set; returns the depth of the mutation class, i.e., the - maximal distance from ``self`` of an element in the mutation class - - ``up_to_equivalence`` -- (default: ``True``) if ``True``, only - clusters up to equivalence are considered. + - ``show_depth`` -- boolean (default: ``False``); if ``True``, ignored + if ``depth`` is set; returns the depth of the mutation class, i.e., + the maximal distance from ``self`` of an element in the mutation + class + - ``up_to_equivalence`` -- boolean (default: ``True``); if ``True``, + only clusters up to equivalence are considered EXAMPLES: @@ -3735,7 +3735,7 @@ def cluster_class_iter(self, depth=infinity, show_depth=False, up_to_equivalence For a cluster seed from an arbitrarily labelled digraph:: - sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format="list_of_edges") + sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format='list_of_edges') sage: S = ClusterSeed(dg, frozen=['b']) sage: S.cluster_class() [[a, c], [a, (b + 1)/c], [(b + 1)/a, c], [(b + 1)/a, (b + 1)/c]] @@ -3756,11 +3756,11 @@ def cluster_class(self, depth=infinity, show_depth=False, up_to_equivalence=True - ``depth`` -- (default: infinity) integer, only seeds with distance at most ``depth`` from ``self`` are returned - - ``return_depth`` -- (default: ``False``); if ``True``, ignored if + - ``return_depth`` -- (default: ``False``) if ``True``, ignored if ``depth`` is set; returns the depth of the mutation class, i.e., the maximal distance from ``self`` of an element in the mutation class - - ``up_to_equivalence`` -- (default: ``True``); if ``True``, only - clusters up to equivalence are considered. + - ``up_to_equivalence`` -- (default: ``True``) if ``True``, only + clusters up to equivalence are considered EXAMPLES: @@ -3777,14 +3777,15 @@ def cluster_class(self, depth=infinity, show_depth=False, up_to_equivalence=True def b_matrix_class_iter(self, depth=infinity, up_to_equivalence=True): r""" - Return an iterator through all `B`-matrices in the mutation class of ``self``. + Return an iterator through all `B`-matrices in the mutation class of + ``self``. INPUT: - - ``depth`` -- (default:infinity) integer or infinity, only seeds + - ``depth`` -- (default: infinity) integer or infinity, only seeds with distance at most ``depth`` from ``self`` are returned - - ``up_to_equivalence`` -- (default: ``True``) if ``True``, only - `B`-matrices up to equivalence are considered. + - ``up_to_equivalence`` -- boolean (default: ``True``); if ``True``, + only `B`-matrices up to equivalence are considered EXAMPLES: @@ -3868,7 +3869,7 @@ def b_matrix_class_iter(self, depth=infinity, up_to_equivalence=True): For a cluster seed from an arbitrarily labelled digraph:: - sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format="list_of_edges") + sage: dg = DiGraph([['a', 'b'], ['b', 'c']], format='list_of_edges') sage: S = ClusterSeed(dg, frozen=['b']) sage: S.b_matrix_class() [ @@ -3888,8 +3889,8 @@ def b_matrix_class(self, depth=infinity, up_to_equivalence=True): - ``depth`` -- (default: infinity) integer or infinity, only seeds with distance at most ``depth`` from ``self`` are returned - - ``up_to_equivalence`` -- (default: ``True``) if ``True``, only - `B`-matrices up to equivalence are considered. + - ``up_to_equivalence`` -- boolean (default: ``True``); if ``True``, + only `B`-matrices up to equivalence are considered EXAMPLES: @@ -3907,14 +3908,15 @@ def b_matrix_class(self, depth=infinity, up_to_equivalence=True): def variable_class_iter(self, depth=infinity, ignore_bipartite_belt=False): r""" - Return an iterator for all cluster variables in the mutation class of ``self``. + Return an iterator for all cluster variables in the mutation class of + ``self``. INPUT: - ``depth`` -- (default: infinity) integer, only seeds with distance at most ``depth`` from ``self`` are returned - - ``ignore_bipartite_belt`` -- (default: ``False``) if ``True``, - the algorithm does not use the bipartite belt + - ``ignore_bipartite_belt`` -- boolean (default: ``False``); if + ``True``, the algorithm does not use the bipartite belt EXAMPLES: @@ -4044,8 +4046,8 @@ def variable_class(self, depth=infinity, ignore_bipartite_belt=False): - ``depth`` -- (default: infinity) integer, only seeds with distance at most ``depth`` from ``self`` are returned - - ``ignore_bipartite_belt`` -- (default: ``False``) if ``True``, the - algorithm does not use the bipartite belt + - ``ignore_bipartite_belt`` -- boolean (default: ``False``); if + ``True``, the algorithm does not use the bipartite belt EXAMPLES: @@ -4089,15 +4091,15 @@ def is_finite(self) -> bool: def is_mutation_finite(self, nr_of_checks=None, return_path=False): r""" - Return True if ``self`` is of finite mutation type. + Return ``True`` if ``self`` is of finite mutation type. INPUT: - - ``nr_of_checks`` -- (default: ``None``) number of mutations applied. - Standard is 500 times the number of vertices of ``self``. - - ``return_path`` -- (default: ``False``) if ``True``, in case of - ``self`` not being mutation finite, a path from ``self`` to a quiver - with an edge label `(a,-b)` and `a*b > 4` is returned. + - ``nr_of_checks`` -- (default: ``None``) number of mutations applied; + standard is 500 times the number of vertices of ``self`` + - ``return_path`` -- boolean (default: ``False``); if ``True``, in case + of ``self`` not being mutation finite, a path from ``self`` to a + quiver with an edge label `(a,-b)` and `a*b > 4` is returned ALGORITHM: @@ -4200,7 +4202,7 @@ def mutation_type(self): def greedy(self, a1, a2, algorithm='by_recursion'): r""" - Return the greedy element `x[a_1,a_2]` assuming that self is rank two. + Return the greedy element `x[a_1,a_2]` assuming that ``self`` is rank two. The third input can be ``'by_recursion'``, ``'by_combinatorics'``, or ``'just_numbers'`` to specify if the user wants the element @@ -4373,8 +4375,8 @@ def find_upper_bound(self, verbose=False): INPUT: - - ``verbose`` -- (default: ``False``) if ``True``, prints output - during the computation. + - ``verbose`` -- boolean (default: ``False``); if ``True``, prints + output during the computation EXAMPLES: @@ -4463,19 +4465,19 @@ def find_upper_bound(self, verbose=False): def get_upper_cluster_algebra_element(self, a): r""" - Compute an element in the upper cluster algebra of `B` corresponding to the vector `a \in \ZZ^n`. + Compute an element in the upper cluster algebra of `B` corresponding to + the vector `a \in \ZZ^n`. See [LLM2014]_ for more details. INPUT: - ``B`` -- a skew-symmetric matrix. Must have the same number of columns - as the length of the vectors in `vd`. - - ``a`` -- a vector in `\ZZ^n` where `n` is the number of columns in `B`. + as the length of the vectors in `vd` + - ``a`` -- a vector in `\ZZ^n` where `n` is the number of columns in `B` - OUTPUT: - - Return an element in the upper cluster algebra. Depending on the input it may or may not be irreducible. + OUTPUT: an element in the upper cluster algebra. Depending on the input + it may or may not be irreducible EXAMPLES:: @@ -4519,13 +4521,11 @@ def LLM_gen_set(self, size_limit=-1): INPUT: - - ``B`` -- a skew-symmetric matrix. + - ``B`` -- a skew-symmetric matrix - ``size_limit`` -- a limit on how many vectors you want - the function to return. - - OUTPUT: + the function to return - An array of elements in the upper cluster algebra. + OUTPUT: an array of elements in the upper cluster algebra EXAMPLES:: @@ -4563,14 +4563,13 @@ def _compute_compatible_vectors(self, vd): INPUT: - ``B`` -- a skew-symmetric matrix. Must have the same number of columns - as the length of the vectors in ``vd``. + as the length of the vectors in ``vd`` - ``vd`` -- a collection of tuples `(v,z)` with `v \in \{0,1\}^n` and `z \in \ZZ`. `n` must be the number of columns in `B`. Taken from the output of :func:`_vector_decomposition`. - OUTPUT: - - a 2-dimensional array containing all the vectors compatible with each vector in ``vd.`` + OUTPUT: a 2-dimensional array containing all the vectors compatible + with each vector in ``vd.`` .. NOTE:: @@ -4640,7 +4639,7 @@ def _compute_compatible_vectors(self, vd): if any(am < 0 for am in a[0]): compatibleList.append([]) continue - # If the vector a in vd is non-positive, it is not compatible + # If the vector a in vd is nonpositive, it is not compatible # with any vector. 0 vector will pass this check but will be # handled later. clist = [] @@ -4660,7 +4659,8 @@ def _compute_compatible_vectors(self, vd): def _produce_upper_cluster_algebra_element(self, vd, cList): r""" - Takes the compatible vectors and uses them to produce a Laurent polynomial in the upper cluster algebra. + Take the compatible vectors and uses them to produce a Laurent + polynomial in the upper cluster algebra. EXAMPLES:: @@ -4899,7 +4899,7 @@ def get_green_vertices(C): INPUT: - - ``C`` -- The C-matrix to check + - ``C`` -- the C-matrix to check EXAMPLES:: @@ -4920,7 +4920,7 @@ def get_red_vertices(C): INPUT: - - ``C`` -- The C-matrix to check + - ``C`` -- the C-matrix to check EXAMPLES:: @@ -4938,7 +4938,7 @@ def _vector_decomposition(a, length): INPUT: - - `a` -- a vector in `\ZZ^n` + - ``a`` -- a vector in `\ZZ^n` OUTPUT: @@ -5029,7 +5029,7 @@ def _power_set(n): INPUT: - - `n` -- an integer. + - ``n`` -- integer OUTPUT: @@ -5089,12 +5089,10 @@ def _multi_concatenate(l1, l2): INPUT: - -`l1` -- a 2-dimensional array. - -`l2` -- a single array. - - OUTPUT: + - ``l1`` -- a 2-dimensional array + - ``l2`` -- a single array - A 2-dimensional array. + OUTPUT: a 2-dimensional array EXAMPLES:: diff --git a/src/sage/combinat/cluster_algebra_quiver/interact.py b/src/sage/combinat/cluster_algebra_quiver/interact.py index 695e3d1d449..834e8a38d44 100644 --- a/src/sage/combinat/cluster_algebra_quiver/interact.py +++ b/src/sage/combinat/cluster_algebra_quiver/interact.py @@ -16,12 +16,12 @@ def cluster_interact(self, fig_size=1, circular=True, kind='seed'): INPUT: - ``fig_size`` -- (default: 1) factor by which the size of the - plot is multiplied. + plot is multiplied - - ``circular`` -- (default: ``True``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. + - ``circular`` -- boolean (default: ``True``); if ``True``, the circular + plot is chosen, otherwise >>spring<< is used - - ``kind`` -- either ``"seed"`` (default) or ``"quiver"`` + - ``kind`` -- either ``'seed'`` (default) or ``'quiver'`` TESTS:: diff --git a/src/sage/combinat/cluster_algebra_quiver/mutation_class.py b/src/sage/combinat/cluster_algebra_quiver/mutation_class.py index 7d7b2720695..9a85542100f 100644 --- a/src/sage/combinat/cluster_algebra_quiver/mutation_class.py +++ b/src/sage/combinat/cluster_algebra_quiver/mutation_class.py @@ -35,9 +35,7 @@ def _principal_part(mat): - ``mat`` -- a matrix with at least as many rows as columns - OUTPUT: - - The top square part of the matrix ``mat``. + OUTPUT: the top square part of the matrix ``mat`` EXAMPLES:: @@ -70,7 +68,7 @@ def _digraph_mutate(dg, k, frozen=None): - ``dg`` -- a digraph with integral edge labels with ``n+m`` vertices - ``k`` -- the vertex at which ``dg`` is mutated - - ``frozen`` -- the list of frozen vertices (default is the empty list) + - ``frozen`` -- the list of frozen vertices (default: empty list) EXAMPLES:: @@ -199,9 +197,7 @@ def _dg_canonical_form(dg, frozen=None): - ``frozen`` -- list (default: ``[]``) of frozen vertices - OUTPUT: - - - dictionary {original label: canonical label} + OUTPUT: dictionary {original label: canonical label} - list of orbits of mutable vertices (using canonical labels) @@ -283,12 +279,17 @@ def _mutation_class_iter( dg, n, m, depth=infinity, return_dig6=False, show_dept INPUT: - - ``dg`` -- a digraph with n+m vertices - - ``depth`` -- a positive integer or infinity specifying (roughly) how many steps away from the initial seed to mutate - - ``return_dig6`` -- indicates whether to convert digraph data to dig6 string data - - ``show_depth`` -- if True, indicates that a running count of the depth is to be displayed - - ``up_to_equivalence`` -- if True, only one digraph for each graph-isomorphism class is recorded - - ``sink_source`` -- if True, only mutations at sinks or sources are applied + - ``dg`` -- a digraph with `n+m` vertices + - ``depth`` -- positive integer or infinity specifying (roughly) how many + steps away from the initial seed to mutate + - ``return_dig6`` -- indicates whether to convert digraph data to dig6 + string data + - ``show_depth`` -- if ``True``, indicates that a running count of the + depth is to be displayed + - ``up_to_equivalence`` -- if ``True``, only one digraph for each + graph-isomorphism class is recorded + - ``sink_source`` -- if ``True``, only mutations at sinks or sources are + applied EXAMPLES:: @@ -387,7 +388,8 @@ def _digraph_to_dig6(dg, hashable=False): INPUT: - ``dg`` -- a digraph - - ``hashable`` -- (Boolean; optional; default: ``False``) if ``True``, the edge labels are turned into a dict. + - ``hashable`` -- boolean (default: ``False``); if ``True``, the edge + labels are turned into a dict EXAMPLES:: @@ -467,7 +469,7 @@ def _dig6_to_matrix( dig6 ): def _dg_is_sink_source( dg, v ): """ - Return True iff the digraph dg has a sink or a source at vertex v. + Return ``True`` iff the digraph dg has a sink or a source at vertex `v`. INPUT: @@ -540,7 +542,7 @@ def _graph_without_edge_labels(dg, vertices): def _has_two_cycles( dg ): """ - Return True if the input digraph has a 2-cycle and False otherwise. + Return ``True`` if the input digraph has a 2-cycle and ``False`` otherwise. EXAMPLES:: @@ -560,11 +562,13 @@ def _has_two_cycles( dg ): def _is_valid_digraph_edge_set( edges, frozen=0 ): """ - Return True if the input data is the edge set of a digraph for a quiver (no loops, no 2-cycles, edge-labels of the specified format), and returns False otherwise. + Return ``True`` if the input data is the edge set of a digraph for a quiver + (no loops, no 2-cycles, edge-labels of the specified format), and return + ``False`` otherwise. INPUT: - - ``frozen`` -- (integer; default:0) The number of frozen vertices. + - ``frozen`` -- integer (default: 0); the number of frozen vertices EXAMPLES:: diff --git a/src/sage/combinat/cluster_algebra_quiver/mutation_type.py b/src/sage/combinat/cluster_algebra_quiver/mutation_type.py index 6c5edc6aa3f..8a366c81053 100644 --- a/src/sage/combinat/cluster_algebra_quiver/mutation_type.py +++ b/src/sage/combinat/cluster_algebra_quiver/mutation_type.py @@ -44,7 +44,8 @@ def is_mutation_finite(M, nr_of_checks=None): INPUT: - - ``nr_of_checks`` -- (default: ``None``) number of mutations applied. Standard is 500*(number of vertices of self). + - ``nr_of_checks`` -- number of mutations applied (default: ``None``); + standard is 500*(number of vertices of self) ALGORITHM: @@ -809,9 +810,9 @@ def _connected_mutation_type_AAtildeD(dg, ret_conn_vert=False): INPUT: - - ``ret_conn_vert`` -- boolean (default: ``False``). If ``True``, + - ``ret_conn_vert`` -- boolean (default: ``False``); if ``True``, returns 'connecting vertices', technical information that is - used in the algorithm. + used in the algorithm A brief description of the algorithm:: @@ -1245,7 +1246,7 @@ def load_data(n, user=True): INPUT: - - ``user`` -- boolean (default: ``True``) whether to look at user + - ``user`` -- boolean (default: ``True``); whether to look at user data. If not, only consider the optional package. EXAMPLES:: @@ -1336,10 +1337,10 @@ def _mutation_type_from_data(n, dig6, compute_if_necessary=True): def _mutation_type_test(n): """ - Tests all quivers (of the given types) of rank n to check that + Test all quivers (of the given types) of rank n to check that mutation_type() works. - Affine type D does not return True since this test is not implemented. + Affine type D does not return ``True`` since this test is not implemented. EXAMPLES:: @@ -1418,10 +1419,10 @@ def _random_tests(mt, k, mut_class=None, nr_mut=5): INPUT: - - ``mt`` something that can be turned into a QuiverMutationType - - ``k`` (integer) the number of tests performed for each quiver of rank ``n`` - - ``mut_class`` is given, this mutation class is used - - ``nr_mut`` (integer, default:5) the number of mutations performed before + - ``mt`` something that can be turned into a ``QuiverMutationType`` + - ``k`` -- integer; the number of tests performed for each quiver of rank ``n`` + - ``mut_class`` -- if given, this mutation class is used + - ``nr_mut`` -- integer (default: 5); the number of mutations performed before testing The idea of this random test is to start with a mutation type @@ -1512,9 +1513,9 @@ def _random_multi_tests(n, k, nr_mut=5): INPUT: - - ``n`` (integer) -- the rank of the mutation types to test - - ``k`` (integer) -- the number of tests performed for each quiver of rank ``n`` - - ``nr_mut`` (integer, default:5) -- the number of mutations performed before testing + - ``n`` -- integer; the rank of the mutation types to test + - ``k`` -- integer; the number of tests performed for each quiver of rank ``n`` + - ``nr_mut`` -- integer (default: 5); the number of mutations performed before testing TESTS:: diff --git a/src/sage/combinat/cluster_algebra_quiver/quiver.py b/src/sage/combinat/cluster_algebra_quiver/quiver.py index b42210db18c..93cdfef5c8a 100644 --- a/src/sage/combinat/cluster_algebra_quiver/quiver.py +++ b/src/sage/combinat/cluster_algebra_quiver/quiver.py @@ -69,7 +69,7 @@ class ClusterQuiver(SageObject): - ``data`` -- can be any of the following:: * :class:`QuiverMutationType` - * :class:`str` -- a string representing a :class:`QuiverMutationType` or a common quiver type (see Examples) + * :class:`str` -- string representing a :class:`QuiverMutationType` or a common quiver type (see Examples) * :class:`ClusterQuiver` * :class:`Matrix` -- a skew-symmetrizable matrix * :class:`DiGraph` -- must be the input data for a quiver @@ -78,7 +78,7 @@ class ClusterQuiver(SageObject): - ``frozen`` -- (default: ``None``) sets the list of frozen variables if the input type is a :class:`DiGraph`, it is ignored otherwise - - ``user_labels`` -- (default:``None``) sets the names of the labels for + - ``user_labels`` -- (default: ``None``) sets the names of the labels for the vertices of the quiver if the input type is not a :class:`DiGraph`; otherwise it is ignored @@ -534,16 +534,16 @@ def plot(self, circular=True, center=(0, 0), directed=True, mark=None, INPUT: - - ``circular`` -- (default: ``True``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. - - ``center`` -- (default:(0,0)) sets the center of the circular plot, - otherwise it is ignored. - - ``directed`` -- (default: ``True``) if ``True``, the directed - version is shown, otherwise the undirected. + - ``circular`` -- boolean (default: ``True``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used + - ``center`` -- (default: (0,0)) sets the center of the circular plot, + otherwise it is ignored + - ``directed`` -- boolean (default: ``True``); if ``True``, the + directed version is shown, otherwise the undirected - ``mark`` -- (default: ``None``) if set to i, the vertex i is - highlighted. - - ``save_pos`` -- (default: ``False``) if ``True``, the positions - of the vertices are saved. + highlighted + - ``save_pos`` -- boolean (default: ``False``); if ``True``, the + positions of the vertices are saved - ``greens`` -- (default: ``[]``) if set to a list, will display the green vertices as green @@ -661,16 +661,17 @@ def show(self, fig_size=1, circular=False, directed=True, mark=None, save_pos=Fa INPUT: - ``fig_size`` -- (default: 1) factor by which the size of the plot - is multiplied. - - ``circular`` -- (default: ``False``) if True, the circular plot is - chosen, otherwise >>spring<< is used. - - ``directed`` -- (default: ``True``) if True, the directed version is - shown, otherwise the undirected. - - ``mark`` -- (default: None) if set to i, the vertex i is highlighted. - - ``save_pos`` -- (default: ``False``) if True, the positions of the - vertices are saved. - - ``greens`` -- (default:[]) if set to a list, will display the green - vertices as green + is multiplied + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used + - ``directed`` -- boolean (default: ``True``); if ``True``, the directed + version is shown, otherwise the undirected + - ``mark`` -- boolean (default: ``None``); if set to i, the vertex i is + highlighted + - ``save_pos`` -- boolean (default: ``False``); if ``True``, the + positions of the vertices are saved + - ``greens`` -- (default: ``[]``) if set to a list, will display the + green vertices as green TESTS:: @@ -693,10 +694,10 @@ def interact(self, fig_size=1, circular=True): INPUT: - ``fig_size`` -- (default: 1) factor by which the size of the - plot is multiplied. + plot is multiplied - - ``circular`` -- (default: ``True``) if ``True``, the circular plot - is chosen, otherwise >>spring<< is used. + - ``circular`` -- boolean (default: ``True``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used TESTS:: @@ -704,7 +705,7 @@ def interact(self, fig_size=1, circular=True): sage: S.interact() # needs sage.plot sage.symbolic ...VBox(children=... """ - return cluster_interact(self, fig_size, circular, kind="quiver") + return cluster_interact(self, fig_size, circular, kind='quiver') def save_image(self, filename, circular=False): """ @@ -712,14 +713,15 @@ def save_image(self, filename, circular=False): INPUT: - - ``filename`` -- the filename the image is saved to. - - ``circular`` -- (default: ``False``) if True, the circular plot is chosen, otherwise >>spring<< is used. + - ``filename`` -- the filename the image is saved to + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used EXAMPLES:: sage: Q = ClusterQuiver(['F',4,[1,2]]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # needs sage.plot sage.symbolic + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # needs sage.plot sage.symbolic ....: Q.save_image(f.name) """ graph_plot = self.plot(circular=circular) @@ -735,7 +737,7 @@ def qmu_save(self, filename=None): INPUT: - - ``filename`` -- the filename the image is saved to. + - ``filename`` -- the filename the image is saved to If a filename is not specified, the default name is ``from_sage.qmu`` in the current sage directory. @@ -744,7 +746,7 @@ def qmu_save(self, filename=None): sage: Q = ClusterQuiver(['F',4,[1,2]]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".qmu") as f: # needs sage.plot sage.symbolic + sage: with tempfile.NamedTemporaryFile(suffix='.qmu') as f: # needs sage.plot sage.symbolic ....: Q.qmu_save(f.name) Make sure we can save quivers with `m != n` frozen variables, see :issue:`14851`:: @@ -753,7 +755,7 @@ def qmu_save(self, filename=None): sage: T1 = S.principal_extension() sage: Q = T1.quiver() sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".qmu") as f: # needs sage.plot sage.symbolic + sage: with tempfile.NamedTemporaryFile(suffix='.qmu') as f: # needs sage.plot sage.symbolic ....: Q.qmu_save(f.name) """ M = self.b_matrix() @@ -879,8 +881,9 @@ def mutation_type(self): """ Return the mutation type of ``self``. - Return the mutation_type of each connected component of self if it can be determined, - otherwise, the mutation type of this component is set to be unknown. + Return the mutation_type of each connected component of ``self`` if it + can be determined, otherwise, the mutation type of this component is + set to be unknown. The mutation types of the components are ordered by vertex labels. @@ -1119,9 +1122,9 @@ def canonical_label(self, certificate=False): INPUT: - - ``certificate`` -- boolean (default: ``False``) if True, the dictionary - from ``self.vertices()`` to the vertices of the returned quiver - is returned as well. + - ``certificate`` -- boolean (default: ``False``); if ``True``, the + dictionary from ``self.vertices()`` to the vertices of the returned + quiver is returned as well EXAMPLES:: @@ -1295,7 +1298,7 @@ def sinks(self): def first_source(self): r""" - Return the first vertex of ``self`` that is a source + Return the first vertex of ``self`` that is a source. EXAMPLES:: @@ -1334,11 +1337,13 @@ def mutate(self, data, inplace=True): INPUT: - - ``sequence`` -- a vertex of ``self``, an iterator of vertices of ``self``, - a function which takes in the ClusterQuiver and returns a vertex or an iterator of vertices, - or a string of the parameter wanting to be called on ClusterQuiver that will return a vertex or - an iterator of vertices. - - ``inplace`` -- (default: ``True``) if False, the result is returned, otherwise ``self`` is modified. + - ``sequence`` -- a vertex of ``self``, an iterator of vertices of + ``self``, a function which takes in the ClusterQuiver and returns a + vertex or an iterator of vertices, or a string of the parameter + wanting to be called on ClusterQuiver that will return a vertex or + an iterator of vertices + - ``inplace`` -- boolean (default: ``True``); if ``False``, the result + is returned, otherwise ``self`` is modified EXAMPLES:: @@ -1471,13 +1476,16 @@ def mutate(self, data, inplace=True): def mutation_sequence(self, sequence, show_sequence=False, fig_size=1.2 ): """ - Return a list containing the sequence of quivers obtained from ``self`` by a sequence of mutations on vertices. + Return a list containing the sequence of quivers obtained from ``self`` + by a sequence of mutations on vertices. INPUT: - - ``sequence`` -- a list or tuple of vertices of ``self``. - - ``show_sequence`` -- (default: ``False``) if ``True``, a png containing the mutation sequence is shown. - - ``fig_size`` -- (default: 1.2) factor by which the size of the sequence is expanded. + - ``sequence`` -- list or tuple of vertices of ``self`` + - ``show_sequence`` -- boolean (default: ``False``); if ``True``, a png + containing the mutation sequence is shown + - ``fig_size`` -- (default: 1.2) factor by which the size of the + sequence is expanded EXAMPLES:: @@ -1616,17 +1624,21 @@ def reorient(self, data): raise ValueError('not a total order on the vertices of the quiver or a list of edges to be oriented') def mutation_class_iter(self, depth=infinity, show_depth=False, - return_paths=False, data_type="quiver", + return_paths=False, data_type='quiver', up_to_equivalence=True, sink_source=False): """ Return an iterator for the mutation class of ``self`` together with certain constraints. INPUT: - - ``depth`` -- (default: infinity) integer, only quivers with distance at most depth from self are returned. - - ``show_depth`` -- (default: ``False``) if True, the actual depth of the mutation is shown. - - ``return_paths`` -- (default: ``False``) if True, a shortest path of mutation sequences from self to the given quiver is returned as well. - - ``data_type`` -- (default: "quiver") can be one of the following:: + - ``depth`` -- integer (default: infinity); only quivers with distance + at most depth from ``self`` are returned. + - ``show_depth`` -- boolean (default: ``False``); if ``True``, the + actual depth of the mutation is shown + - ``return_paths`` -- boolean (default: ``False``); if ``True``, a + shortest path of mutation sequences from ``self`` to the given quiver + is returned as well + - ``data_type`` -- (default: ``'quiver'``) can be one of the following:: * "quiver" * "matrix" @@ -1634,8 +1646,10 @@ def mutation_class_iter(self, depth=infinity, show_depth=False, * "dig6" * "path" - - ``up_to_equivalence`` -- (default: ``True``) if True, only one quiver for each graph-isomorphism class is recorded. - - ``sink_source`` -- (default: ``False``) if True, only mutations at sinks and sources are applied. + - ``up_to_equivalence`` -- boolean (default: ``True``); if ``True``, + only one quiver for each graph-isomorphism class is recorded + - ``sink_source`` -- boolean (default: ``False``); if ``True``, only + mutations at sinks and sources are applied EXAMPLES:: @@ -1751,29 +1765,29 @@ def mutation_class_iter(self, depth=infinity, show_depth=False, yield next_element def mutation_class(self, depth=infinity, show_depth=False, return_paths=False, - data_type="quiver", up_to_equivalence=True, sink_source=False): + data_type='quiver', up_to_equivalence=True, sink_source=False): """ Return the mutation class of ``self`` together with certain constraints. INPUT: - - ``depth`` -- (default: ``infinity`) integer, only seeds with + - ``depth`` -- (default: ``infinity``) integer, only seeds with distance at most depth from ``self`` are returned - - ``show_depth`` -- (default: ``False``) if ``True``, the actual depth - of the mutation is shown - - ``return_paths`` -- (default: ``False``) if ``True``, a shortest - path of mutation sequences from self to the given quiver is + - ``show_depth`` -- boolean (default: ``False``); if ``True``, the + actual depth of the mutation is shown + - ``return_paths`` -- boolean (default: ``False``); if ``True``, a + shortest path of mutation sequences from ``self`` to the given quiver is returned as well - - ``data_type`` -- (default: ``"quiver"``) can be one of + - ``data_type`` -- (default: ``'quiver'``) can be one of the following: - * ``"quiver"`` -- the quiver is returned - * ``"dig6"`` -- the dig6-data is returned - * ``"path"`` -- shortest paths of mutation sequences from + * ``'quiver'`` -- the quiver is returned + * ``'dig6'`` -- the dig6-data is returned + * ``'path'`` -- shortest paths of mutation sequences from ``self`` are returned - - ``sink_source`` -- (default: ``False``) if ``True``, only mutations - at sinks and sources are applied + - ``sink_source`` -- boolean (default: ``False``); if ``True``, only + mutations at sinks and sources are applied EXAMPLES:: @@ -1904,12 +1918,16 @@ def is_finite(self): def is_mutation_finite( self, nr_of_checks=None, return_path=False ): """ - Uses a non-deterministic method by random mutations in various directions. Can result in a wrong answer. + Uses a non-deterministic method by random mutations in various + directions. Can result in a wrong answer. INPUT: - - ``nr_of_checks`` -- (default: None) number of mutations applied. Standard is 500*(number of vertices of self). - - ``return_path`` -- (default: ``False``) if True, in case of self not being mutation finite, a path from self to a quiver with an edge label (a,-b) and a*b > 4 is returned. + - ``nr_of_checks`` -- (default: ``None``) number of mutations applied; + Standard is 500*(number of vertices of ``self``) + - ``return_path`` -- (default: ``False``) if ``True``, in case of + ``self`` not being mutation finite, a path from ``self`` to a quiver + with an edge label `(a,-b)` and `a*b > 4` is returned ALGORITHM: @@ -1951,14 +1969,12 @@ def is_mutation_finite( self, nr_of_checks=None, return_path=False ): def number_of_edges(self): r""" - Return the total number of edges on the quiver + Return the total number of edges on the quiver. Note: This only works with non-valued quivers. If used on a non-valued quiver then the positive value is taken to be the number of edges added - OUTPUT: - - An integer of the number of edges. + OUTPUT: integer of the number of edges EXAMPLES:: @@ -1978,14 +1994,15 @@ def number_of_edges(self): def relabel(self, relabelling, inplace=True): r""" - Return the quiver after doing a relabelling + Return the quiver after doing a relabelling. - Will relabel the vertices of the quiver + Will relabel the vertices of the quiver. INPUT: - - ``relabelling`` -- Dictionary of labels to move around - - ``inplace`` -- (default: ``True``) if True, will return a duplicate of the quiver + - ``relabelling`` -- dictionary of labels to move around + - ``inplace`` -- boolean (default: ``True``); if ``True``, will return + a duplicate of the quiver EXAMPLES:: diff --git a/src/sage/combinat/cluster_algebra_quiver/quiver_mutation_type.py b/src/sage/combinat/cluster_algebra_quiver/quiver_mutation_type.py index d4b99fc9c23..25610dff117 100644 --- a/src/sage/combinat/cluster_algebra_quiver/quiver_mutation_type.py +++ b/src/sage/combinat/cluster_algebra_quiver/quiver_mutation_type.py @@ -680,11 +680,11 @@ def plot(self, circular=False, directed=True): INPUT: - - ``circular`` -- (default: ``False``) if ``True``, the - circular plot is chosen, otherwise >>spring<< is used. + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used - - ``directed`` -- (default: ``True``) if ``True``, the - directed version is shown, otherwise the undirected. + - ``directed`` -- boolean (default: ``True``); if ``True``, the + directed version is shown, otherwise the undirected EXAMPLES:: @@ -700,15 +700,15 @@ def show(self, circular=False, directed=True): INPUT: - - ``circular`` -- (default:``False``) if ``True``, the - circular plot is chosen, otherwise >>spring<< is used. + - ``circular`` -- boolean (default: ``False``); if ``True``, the + circular plot is chosen, otherwise >>spring<< is used - - ``directed`` -- (default: ``True``) if ``True``, the - directed version is shown, otherwise the undirected. + - ``directed`` -- boolean (default: ``True``); if ``True``, the + directed version is shown, otherwise the undirected TESTS:: - sage: QMT = QuiverMutationType(['A',5]) + sage: QMT = QuiverMutationType(['A', 5]) sage: QMT.show() # long time # needs sage.plot sage.symbolic """ self.plot(circular=circular, directed=directed).show() @@ -1973,8 +1973,8 @@ def __init__(self, *args): INPUT: - - ``data`` -- a list each of whose entries is a - QuiverMutationType_Irreducible + - ``data`` -- list; each of whose entries is a + :class:`QuiverMutationType_Irreducible` EXAMPLES:: @@ -2287,7 +2287,7 @@ def _save_data_dig6(n, types='ClassicalExceptional', verbose=False): def save_quiver_data(n, up_to=True, types='ClassicalExceptional', verbose=True): r""" Save mutation classes of certain quivers of ranks up to and equal - to ``n`` or equal to ``n`` to + to `n` or equal to `n` to ``DOT_SAGE/cluster_algebra_quiver/mutation_classes_n.dig6``. This data will then be used to determine quiver mutation types. @@ -2295,16 +2295,16 @@ def save_quiver_data(n, up_to=True, types='ClassicalExceptional', verbose=True): INPUT: - ``n`` -- the rank (or the upper limit on the rank) of the mutation - classes that are being saved. + classes that are being saved - - ``up_to`` -- (default:``True``) if ``True``, saves data for - ranks smaller than or equal to ``n``. If ``False``, saves data - for rank exactly ``n``. + - ``up_to`` -- (default: ``True``) if ``True``, saves data for + ranks smaller than or equal to `n`; if ``False``, saves data + for rank exactly `n` - - ``types`` -- (default:'ClassicalExceptional') if all, saves data + - ``types`` -- (default: ``'ClassicalExceptional'``) if all, saves data for both exceptional mutation-finite quivers and for classical - quiver. The input 'Exceptional' or 'Classical' is also allowed - to save only part of this data. + quiver; the input 'Exceptional' or 'Classical' is also allowed + to save only part of this data TESTS:: diff --git a/src/sage/combinat/cluster_complex.py b/src/sage/combinat/cluster_complex.py index 70a88878987..c99dc0df6f3 100644 --- a/src/sage/combinat/cluster_complex.py +++ b/src/sage/combinat/cluster_complex.py @@ -74,14 +74,14 @@ def cluster(self): """ if self.parent().k() != 1: raise NotImplementedError("not working for multi-cluster complexes") - F = self.parent().greedy_facet(side="positive") + F = self.parent().greedy_facet(side='positive') R = F.extended_root_configuration() N = len(list(F)) return [-R[i] if i < N else R[i] for i in self] def upper_cluster(self): """ - Return the part of the cluster that contains positive roots + Return the part of the cluster that contains positive roots. EXAMPLES:: @@ -173,7 +173,7 @@ class ClusterComplex(SubwordComplex): """ @staticmethod - def __classcall__(cls, W, k=1, coxeter_element=None, algorithm="inductive"): + def __classcall__(cls, W, k=1, coxeter_element=None, algorithm='inductive'): r""" Standardize input to ensure a unique representation. @@ -184,7 +184,7 @@ def __classcall__(cls, W, k=1, coxeter_element=None, algorithm="inductive"): sage: S2 = ClusterComplex(W) sage: S3 = ClusterComplex(CoxeterMatrix('B2'), coxeter_element=(1,2)) sage: w = W.from_reduced_word([1,2]) - sage: S4 = ClusterComplex('B2', coxeter_element=w, algorithm="inductive") + sage: S4 = ClusterComplex('B2', coxeter_element=w, algorithm='inductive') sage: S1 is S2 and S2 is S3 and S3 is S4 True """ @@ -238,9 +238,7 @@ def __call__(self, F, facet_test=True): - ``facet_test`` -- boolean (default: ``True``); tells whether or not the facet ``F`` should be tested before creation - OUTPUT: - - The facet of ``self`` at positions given by ``F``. + OUTPUT: the facet of ``self`` at positions given by ``F`` EXAMPLES:: diff --git a/src/sage/combinat/colored_permutations.py b/src/sage/combinat/colored_permutations.py index 91075c7a423..1accb8f46ee 100644 --- a/src/sage/combinat/colored_permutations.py +++ b/src/sage/combinat/colored_permutations.py @@ -815,8 +815,8 @@ def _element_constructor_(self, x): INPUT: - Either a list of pairs ``(color, element)`` - or a pair of lists ``(colors, elements)``. + - ``x`` -- either a list of pairs ``(color, element)`` or a pair of + lists ``(colors, elements)`` TESTS:: @@ -1460,13 +1460,13 @@ def to_cycles(self, singletons=True, use_min=True, negative_cycles=True): INPUT: - - ``singletons`` -- (default: ``True``) whether to include singleton - cycles or not - - ``use_min`` -- (default: ``True``) if ``False``, the cycles are - returned in the order of increasing *largest* (not smallest) + - ``singletons`` -- boolean (default: ``True``); whether to include + singleton cycles or not + - ``use_min`` -- boolean (default: ``True``); if ``False``, the cycles + are returned in the order of increasing *largest* (not smallest) elements, and each cycle starts with its largest element - - ``negative_cycles`` -- (default: ``True``) if ``False``, for any - two cycles `C^{\pm} = \{\pm c_1, \ldots, \pm c_k\}` such that + - ``negative_cycles`` -- boolean (default: ``True``); if ``False``, for + any two cycles `C^{\pm} = \{\pm c_1, \ldots, \pm c_k\}` such that `C^+ \neq C^-`, this does not include the cycle `C^-` .. WARNING:: diff --git a/src/sage/combinat/combinat.py b/src/sage/combinat/combinat.py index 0604d4620b9..19677532d98 100644 --- a/src/sage/combinat/combinat.py +++ b/src/sage/combinat/combinat.py @@ -197,17 +197,17 @@ def bell_number(n, algorithm='flint', **options) -> Integer: INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``algorithm`` -- (Default: ``'flint'``) any one of the following: + - ``algorithm`` -- (default: ``'flint'``) any one of the following: - - ``'dobinski'`` -- Use Dobinski's formula implemented in Sage + - ``'dobinski'`` -- use Dobinski's formula implemented in Sage - - ``'flint'`` -- Wrap FLINT's ``arith_bell_number`` + - ``'flint'`` -- wrap FLINT's ``arith_bell_number`` - - ``'gap'`` -- Wrap GAP's ``Bell`` + - ``'gap'`` -- wrap GAP's ``Bell`` - - ``'mpmath'`` -- Wrap mpmath's ``bell`` + - ``'mpmath'`` -- wrap mpmath's ``bell`` .. WARNING:: @@ -466,9 +466,7 @@ def catalan_number(n): - ``n`` -- integer - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -505,13 +503,11 @@ def narayana_number(n: Integer, k: Integer) -> Integer: INPUT: - - ``n`` -- an integer - - - ``k`` -- an integer between ``0`` and ``n - 1`` + - ``n`` -- integer - OUTPUT: + - ``k`` -- integer between ``0`` and ``n - 1`` - an integer + OUTPUT: integer EXAMPLES:: @@ -537,13 +533,13 @@ def euler_number(n, algorithm='flint') -> Integer: INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``algorithm`` -- (Default: ``'flint'``) any one of the following: + - ``algorithm`` -- (default: ``'flint'``) any one of the following: - - ``'maxima'`` -- Wraps Maxima's ``euler``. + - ``'maxima'`` -- wraps Maxima's ``euler`` - - ``'flint'`` -- Wrap FLINT's ``arith_euler_number`` + - ``'flint'`` -- wrap FLINT's ``arith_euler_number`` EXAMPLES:: @@ -593,11 +589,9 @@ def eulerian_number(n, k, algorithm='recursive') -> Integer: - ``k`` -- integer between ``0`` and ``n - 1`` - - ``algorithm`` -- ``"recursive"`` (default) or ``"formula"`` + - ``algorithm`` -- ``'recursive'`` (default) or ``'formula'`` - OUTPUT: - - an integer + OUTPUT: integer .. SEEALSO:: :func:`eulerian_polynomial` @@ -637,13 +631,11 @@ def eulerian_polynomial(n, algorithm='derivative'): INPUT: - - ``n`` -- an integer - - - ``algorithm`` -- ``"derivative"`` (default) or ``"coeffs"`` + - ``n`` -- integer - OUTPUT: + - ``algorithm`` -- ``'derivative'`` (default) or ``'coeffs'`` - polynomial in one variable ``t`` + OUTPUT: polynomial in one variable ``t`` .. SEEALSO:: :func:`eulerian_number` @@ -679,7 +671,7 @@ def eulerian_polynomial(n, algorithm='derivative'): return R([eulerian_number(n, k, "formula") for k in range(n)]) -def fibonacci(n, algorithm="pari") -> Integer: +def fibonacci(n, algorithm='pari') -> Integer: """ Return the `n`-th Fibonacci number. @@ -691,12 +683,12 @@ def fibonacci(n, algorithm="pari") -> Integer: INPUT: - - ``algorithm`` -- a string: + - ``algorithm`` -- string; one of - * ``"pari"`` -- (default) use the PARI C library's + * ``'pari'`` -- (default) use the PARI C library's :pari:`fibo` function - * ``"gap"`` -- use GAP's Fibonacci function + * ``'gap'`` -- use GAP's Fibonacci function .. NOTE:: @@ -750,9 +742,9 @@ def lucas_number1(n, P, Q): INPUT: - - ``n`` -- integer + - ``n`` -- integer - - ``P, Q`` -- integer or rational numbers + - ``P``, ``Q`` -- integer or rational numbers OUTPUT: integer or rational number @@ -817,11 +809,9 @@ def lucas_number2(n, P, Q): INPUT: + - ``n`` -- integer - - ``n`` -- integer - - - ``P, Q`` -- integer or rational numbers - + - ``P``, ``Q`` -- integer or rational numbers OUTPUT: integer or rational number @@ -857,7 +847,7 @@ def lucas_number2(n, P, Q): return libgap.Lucas(P, Q, n)[1].sage() -def stirling_number1(n, k, algorithm="gap") -> Integer: +def stirling_number1(n, k, algorithm='gap') -> Integer: r""" Return the `n`-th Stirling number `S_1(n,k)` of the first kind. @@ -871,8 +861,8 @@ def stirling_number1(n, k, algorithm="gap") -> Integer: - ``k`` -- nonnegative machine-size integer - ``algorithm``: - * ``"gap"`` (default) -- use GAP's ``Stirling1`` function - * ``"flint"`` -- use flint's ``arith_stirling_number_1u`` function + * ``'gap'`` -- default; use GAP's ``Stirling1`` function + * ``'flint'`` -- use flint's ``arith_stirling_number_1u`` function EXAMPLES:: @@ -893,7 +883,7 @@ def stirling_number1(n, k, algorithm="gap") -> Integer: sage: stirling_number1(10,5, algorithm='flint') # needs sage.libs.flint 269325 - sage: s_sage = stirling_number1(50,3, algorithm="mutta") + sage: s_sage = stirling_number1(50,3, algorithm='mutta') Traceback (most recent call last): ... ValueError: unknown algorithm: mutta @@ -921,14 +911,14 @@ def stirling_number2(n, k, algorithm=None) -> Integer: INPUT: - - ``n`` -- nonnegative machine-size integer - - ``k`` -- nonnegative machine-size integer + - ``n`` -- nonnegative machine-size integer + - ``k`` -- nonnegative machine-size integer - ``algorithm``: - * ``None`` (default) -- use native implementation - * ``"flint"`` -- use flint's ``arith_stirling_number_2`` function - * ``"gap"`` -- use GAP's ``Stirling2`` function - * ``"maxima"`` -- use Maxima's ``stirling2`` function + * ``None`` -- default; use native implementation + * ``'flint'`` -- use flint's ``arith_stirling_number_2`` function + * ``'gap'`` -- use GAP's ``Stirling2`` function + * ``'maxima'`` -- use Maxima's ``stirling2`` function EXAMPLES: @@ -1016,10 +1006,10 @@ def stirling_number2(n, k, algorithm=None) -> Integer: ....: if not (s_sage == s_flint and s_sage == s_gap): ....: print("Error with n<200") - sage: stirling_number2(20, 3, algorithm="maxima") # needs sage.symbolic + sage: stirling_number2(20, 3, algorithm='maxima') # needs sage.symbolic 580606446 - sage: s_sage = stirling_number2(5, 3, algorithm="namba") + sage: s_sage = stirling_number2(5, 3, algorithm='namba') Traceback (most recent call last): ... ValueError: unknown algorithm: namba @@ -1060,7 +1050,7 @@ def polygonal_number(s, n): - ``n`` -- integer; the index of the returned `s`-gonal number - OUTPUT: an integer + OUTPUT: integer EXAMPLES: @@ -1142,12 +1132,12 @@ def __init__(self, l, copy=True): INPUT: - - ``l`` -- a list or any object that can be converted to a - list by calling ``list()``. + - ``l`` -- list or any object that can be converted to a + list by calling ``list()`` - - ``copy`` -- (boolean, default ``True``) if ``False``, then + - ``copy`` -- boolean (default: ``True``); if ``False``, then ``l`` must be a ``list``, which is assigned to ``self._list`` - without copying. + without copying EXAMPLES:: @@ -1386,7 +1376,7 @@ def __hash__(self): def __bool__(self) -> bool: """ - Return ``True`` if ``self`` is non-zero. + Return ``True`` if ``self`` is nonzero. We consider a list to be zero if it has length zero. @@ -1425,7 +1415,6 @@ def __bool__(self) -> bool: sage: b = Bar([4]) sage: not b False - """ return bool(self._list) @@ -1507,10 +1496,10 @@ class CombinatorialElement(CombinatorialObject, Element, INPUT: - - ``parent`` -- the :class:`Parent` class for this element. + - ``parent`` -- the :class:`Parent` class for this element - - ``lst`` -- a list or any object that can be converted to a - list by calling ``list()``. + - ``lst`` -- list or any object that can be converted to a + list by calling ``list()`` EXAMPLES:: @@ -1660,7 +1649,7 @@ def _tuples_native(S, k): Return a list of all `k`-tuples of elements of a given set ``S``. This is a helper method used in :meth:`tuples`. It returns the - same as ``tuples(S, k, algorithm="native")``. + same as ``tuples(S, k, algorithm='native')``. EXAMPLES:: @@ -1711,16 +1700,16 @@ def number_of_tuples(S, k, algorithm='naive') -> Integer: sage: S = [1,2,3,4,5] sage: number_of_tuples(S,2) 25 - sage: number_of_tuples(S,2, algorithm="gap") # needs sage.libs.gap + sage: number_of_tuples(S,2, algorithm='gap') # needs sage.libs.gap 25 sage: S = [1,1,2,3,4,5] sage: number_of_tuples(S,2) 25 - sage: number_of_tuples(S,2, algorithm="gap") # needs sage.libs.gap + sage: number_of_tuples(S,2, algorithm='gap') # needs sage.libs.gap 25 sage: number_of_tuples(S,0) 1 - sage: number_of_tuples(S,0, algorithm="gap") # needs sage.libs.gap + sage: number_of_tuples(S,0, algorithm='gap') # needs sage.libs.gap 1 """ if algorithm == 'naive': @@ -1827,16 +1816,16 @@ def number_of_unordered_tuples(S, k, algorithm='naive') -> Integer: sage: S = [1,2,3,4,5] sage: number_of_unordered_tuples(S,2) 15 - sage: number_of_unordered_tuples(S,2, algorithm="gap") # needs sage.libs.gap + sage: number_of_unordered_tuples(S,2, algorithm='gap') # needs sage.libs.gap 15 sage: S = [1,1,2,3,4,5] sage: number_of_unordered_tuples(S,2) 15 - sage: number_of_unordered_tuples(S,2, algorithm="gap") # needs sage.libs.gap + sage: number_of_unordered_tuples(S,2, algorithm='gap') # needs sage.libs.gap 15 sage: number_of_unordered_tuples(S,0) 1 - sage: number_of_unordered_tuples(S,0, algorithm="gap") # needs sage.libs.gap + sage: number_of_unordered_tuples(S,0, algorithm='gap') # needs sage.libs.gap 1 """ if algorithm == 'naive': @@ -1971,7 +1960,7 @@ def bell_polynomial(n: Integer, k=None, ordinary=False): - ``k`` -- (optional) if specified, returns the partial Bell polynomial, otherwise returns the complete Bell polynomial - - ``ordinary`` -- (default: ``False``) if ``True``, returns the + - ``ordinary`` -- boolean (default: ``False``); if ``True``, returns the (partial) ordinary Bell polynomial, otherwise returns the (partial) exponential Bell polynomial @@ -2107,13 +2096,12 @@ def fibonacci_sequence(start, stop=None, algorithm=None) -> Iterator: INPUT: - - ``start`` -- starting value + - ``start`` -- starting value - - ``stop`` -- stopping value + - ``stop`` -- stopping value - - ``algorithm`` -- (default: ``None``) passed on to - fibonacci function (or not passed on if None, i.e., use the - default) + - ``algorithm`` -- (default: ``None``) passed on to fibonacci function (or + not passed on if ``None``, i.e., use the default) EXAMPLES:: @@ -2268,7 +2256,7 @@ def bernoulli_polynomial(x, n: Integer): if n < 0: raise TypeError except TypeError: - raise ValueError("the second argument must be a non-negative integer") + raise ValueError("the second argument must be a nonnegative integer") if n == 0: return x**0 # result should be in the parent of x diff --git a/src/sage/combinat/combinatorial_map.py b/src/sage/combinat/combinatorial_map.py index 84876e52f56..ded649a41da 100644 --- a/src/sage/combinat/combinatorial_map.py +++ b/src/sage/combinat/combinatorial_map.py @@ -57,7 +57,7 @@ def combinatorial_map_trivial(f=None, order=None, name=None): r""" - Combinatorial map decorator + Combinatorial map decorator. See :ref:`sage.combinat.combinatorial_map` for a description of this decorator and its purpose. This default implementation does @@ -65,14 +65,11 @@ def combinatorial_map_trivial(f=None, order=None, name=None): INPUT: - - ``f`` -- (default: ``None``, if combinatorial_map is used as a decorator) a function - ``name`` -- (default: ``None``) the name for nicer outputs on combinatorial maps - ``order`` -- (default: ``None``) the order of the combinatorial map, if it is known. Is not used, but might be helpful later - OUTPUT: - - - ``f`` unchanged + OUTPUT: ``f`` unchanged EXAMPLES:: @@ -119,9 +116,7 @@ def combinatorial_map_wrapper(f=None, order=None, name=None): - ``name`` -- (default: ``None``) the name for nicer outputs on combinatorial maps - ``order`` -- (default: ``None``) the order of the combinatorial map, if it is known. Is not used, but might be helpful later - OUTPUT: - - - A combinatorial map. This is an instance of the :class:`CombinatorialMap`. + OUTPUT: a combinatorial map; this is an instance of the :class:`CombinatorialMap` EXAMPLES: @@ -182,7 +177,6 @@ def combinatorial_map_wrapper(f=None, order=None, name=None): sage: combinatorial_map(major_index) Combinatorial map: major_index - """ if f is None: return lambda f: CombinatorialMap(f, order=order, name=name) @@ -276,7 +270,7 @@ def _sage_src_lines_(self): def __get__(self, inst, cls=None): """ - Bounds the method of self to the given instance. + Bounds the method of ``self`` to the given instance. EXAMPLES:: @@ -292,7 +286,7 @@ def __get__(self, inst, cls=None): def __call__(self, *args, **kwds): """ - Calls the combinatorial map. + Call the combinatorial map. EXAMPLES:: @@ -336,7 +330,7 @@ def unbounded_map(self): def order(self): """ - Returns the order of ``self``, or ``None`` if the order is not known. + Return the order of ``self``, or ``None`` if the order is not known. EXAMPLES:: @@ -355,7 +349,7 @@ def order(self): def name(self): """ - Returns the name of a combinatorial map. + Return the name of a combinatorial map. This is used for the string representation of ``self``. EXAMPLES:: diff --git a/src/sage/combinat/composition.py b/src/sage/combinat/composition.py index fd3a7f55b8b..173590cfd74 100644 --- a/src/sage/combinat/composition.py +++ b/src/sage/combinat/composition.py @@ -51,7 +51,7 @@ class Composition(CombinatorialElement): r""" - Integer compositions + Integer compositions. A composition of a nonnegative integer `n` is a list `(i_1, \ldots, i_k)` of positive integers with total sum `n`. @@ -209,7 +209,7 @@ def _ascii_art_(self): [ * ** * * ] [ * * ** *** * ** * ] [ *, * , * , * , **, ** , ***, **** ] - sage: Partitions.options(diagram_str='#', convention="French") + sage: Partitions.options(diagram_str='#', convention='French') sage: ascii_art(Compositions(4).list()) [ # ] [ # # # ## ] @@ -231,7 +231,7 @@ def _unicode_art_(self): ⎢ ├┤ ├┼┘ ┌┼┤ ┌┬┬┐ ├┤ ┌┬┐ ┌┐ ⎥ ⎢ ├┤ ├┤ ├┼┘ ├┼┴┘ ┌┼┤ ┌┼┼┘ ┌┬┼┤ ┌┬┬┬┐ ⎥ ⎣ └┘, └┘ , └┘ , └┘ , └┴┘, └┴┘ , └┴┴┘, └┴┴┴┘ ⎦ - sage: Partitions.options(diagram_str='#', convention="French") + sage: Partitions.options(diagram_str='#', convention='French') sage: unicode_art(Compositions(4).list()) ⎡ ┌┐ ⎤ ⎢ ├┤ ┌┐ ┌┐ ┌┬┐ ⎥ @@ -392,7 +392,7 @@ def sum(compositions) -> Composition: INPUT: - - ``compositions`` -- a list (or iterable) of compositions + - ``compositions`` -- list (or iterable) of compositions EXAMPLES:: @@ -473,8 +473,8 @@ def ribbon_decomposition(self, other, check=True): - ``other`` -- composition of same size as ``self`` - - ``check`` -- (default: ``True``) a Boolean determining whether - to check the input compositions for having the same size + - ``check`` -- boolean (default: ``True``); whether to check the input + compositions for having the same size OUTPUT: @@ -585,12 +585,10 @@ def join(self, other, check=True) -> Composition: - ``other`` -- composition of same size as ``self`` - - ``check`` -- (default: ``True``) a Boolean determining whether - to check the input compositions for having the same size + - ``check`` -- boolean (default: ``True``); whether to check the input + compositions for having the same size - OUTPUT: - - - the join of the compositions ``self`` and ``other`` + OUTPUT: the join of the compositions ``self`` and ``other`` EXAMPLES:: @@ -710,12 +708,10 @@ def meet(self, other, check=True) -> Composition: - ``other`` -- composition of same size as ``self`` - - ``check`` -- (default: ``True``) a Boolean determining whether - to check the input compositions for having the same size - - OUTPUT: + - ``check`` -- boolean (default: ``True``); whether to check the input + compositions for having the same size - - the meet of the compositions ``self`` and ``other`` + OUTPUT: the meet of the compositions ``self`` and ``other`` EXAMPLES:: @@ -952,7 +948,7 @@ def refinement_splitting(self, J) -> list[Composition]: INPUT: - - ``J`` -- A composition such that ``self`` is finer than ``J`` + - ``J`` -- a composition such that ``self`` is finer than ``J`` OUTPUT: @@ -1080,8 +1076,8 @@ def partial_sums(self, final=True) -> list: INPUT: - - ``final`` -- (default: ``True``) whether or not to include the final - partial sum, which is always the size of the composition. + - ``final`` -- boolean (default: ``True``); whether or not to include + the final partial sum, which is always the size of the composition .. SEEALSO:: @@ -1116,8 +1112,8 @@ def to_subset(self, final=False): INPUT: - - ``final`` -- (default: ``False``) whether or not to include the final - partial sum, which is always the size of the composition. + - ``final`` -- boolean (default: ``False``); whether or not to include + the final partial sum, which is always the size of the composition .. SEEALSO:: @@ -1169,7 +1165,7 @@ def descents(self, final_descent=False) -> list: INPUT: - - ``final_descent`` -- (Default: ``False``) a boolean integer + - ``final_descent`` -- boolean (default: ``False``) OUTPUT: @@ -1282,10 +1278,10 @@ def shuffle_product(self, other, overlap=False): INPUT: - - ``other`` -- composition + - ``other`` -- composition - - ``overlap`` -- boolean (default: ``False``); if ``True``, the - overlapping shuffle product is returned. + - ``overlap`` -- boolean (default: ``False``); if ``True``, the + overlapping shuffle product is returned OUTPUT: @@ -1510,10 +1506,10 @@ class Compositions(UniqueRepresentation, Parent): [1, 2, 1] If `n` is not specified, this returns the combinatorial class of - all (non-negative) integer compositions:: + all (nonnegative) integer compositions:: sage: Compositions() - Compositions of non-negative integers + Compositions of nonnegative integers sage: [] in Compositions() True sage: [2,3,1] in Compositions() @@ -1826,7 +1822,7 @@ def from_descents(self, descents, nps=None) -> Composition: - ``descents`` -- an iterable - - ``nps`` -- (default: ``None``) an integer or ``None`` + - ``nps`` -- integer or ``None`` (default: ``None``) OUTPUT: @@ -1861,7 +1857,7 @@ def from_subset(self, S, n) -> Composition: - ``S`` -- an iterable, a subset of `\{1, 2, \ldots, n-1\}` - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -1976,9 +1972,9 @@ def _repr_(self) -> str: TESTS:: sage: repr(Compositions()) - 'Compositions of non-negative integers' + 'Compositions of nonnegative integers' """ - return "Compositions of non-negative integers" + return "Compositions of nonnegative integers" def subset(self, size=None): """ @@ -2161,7 +2157,7 @@ def __iter__(self): def composition_iterator_fast(n): """ - Iterator over compositions of ``n`` yielded as lists. + Iterator over compositions of `n` yielded as lists. TESTS:: diff --git a/src/sage/combinat/composition_tableau.py b/src/sage/combinat/composition_tableau.py index 8ee363fb275..e90fe55f6a5 100644 --- a/src/sage/combinat/composition_tableau.py +++ b/src/sage/combinat/composition_tableau.py @@ -37,7 +37,7 @@ class CompositionTableau(CombinatorialElement, metaclass=ClasscallMetaclass): INPUT: - - ``t`` -- A list of lists + - ``t`` -- list of lists EXAMPLES:: @@ -278,16 +278,12 @@ class CompositionTableaux(UniqueRepresentation, Parent): INPUT: - Keyword arguments: - - ``size`` -- the size of the composition tableaux - ``shape`` -- the shape of the composition tableaux - ``max_entry`` -- the maximum entry for the composition tableaux - Positional arguments: - - - The first argument is interpreted as ``size`` or ``shape`` depending on - whether it is an integer or a composition. + The first argument is interpreted as ``size`` or ``shape`` depending on + whether it is an integer or a composition. EXAMPLES:: @@ -403,7 +399,7 @@ def __classcall_private__(cls, *args, **kwargs): if not isinstance(size, (int, Integer)): raise ValueError("size must be an integer") elif size < 0: - raise ValueError("size must be non-negative") + raise ValueError("size must be nonnegative") if shape is not None: # use in (and not isinstance) below so that lists can be used as @@ -411,7 +407,7 @@ def __classcall_private__(cls, *args, **kwargs): if shape not in Compositions(): raise ValueError("shape must be a composition") if any(i == 0 for i in shape): - raise ValueError("shape must have non-zero parts") + raise ValueError("shape must have nonzero parts") shape = Composition(shape) if (size is not None) and (shape is not None): @@ -460,9 +456,7 @@ def _element_constructor_(self, t): - ``t`` -- data which can be interpreted as a composition tableau - OUTPUT: - - - The corresponding CompositionTableau object + OUTPUT: the corresponding CompositionTableau object TESTS:: @@ -572,17 +566,15 @@ class CompositionTableaux_size(CompositionTableaux): INPUT: - - ``n`` -- a nonnegative integer. - - ``max_entry`` -- a nonnegative integer. This keyword argument defaults to ``n``. - - OUTPUT: + - ``n`` -- nonnegative integer + - ``max_entry`` -- nonnegative integer (default: `n`) - - The class of composition tableaux of size ``n``. + OUTPUT: the class of composition tableaux of size `n` """ def __init__(self, n, max_entry=None): r""" - Initializes the class of composition tableaux of size ``n``. + Initialize the class of composition tableaux of size `n`. TESTS:: @@ -674,9 +666,8 @@ class CompositionTableaux_shape(CompositionTableaux): INPUT: - - ``comp`` -- a composition. - - ``max_entry`` -- a nonnegative integer. This keyword argument defaults - to the size of ``comp``. + - ``comp`` -- a composition + - ``max_entry`` -- nonnegative integer (default: size of ``comp``) """ def __init__(self, comp, max_entry=None): """ diff --git a/src/sage/combinat/constellation.py b/src/sage/combinat/constellation.py index b4c3bfa4333..e22c3428bb4 100644 --- a/src/sage/combinat/constellation.py +++ b/src/sage/combinat/constellation.py @@ -129,19 +129,20 @@ def Constellations(*data, **options): def Constellation(g=None, mutable=False, connected=True, check=True): r""" - Constellation + Constellation. INPUT: - - ``g`` -- a list of permutations + - ``g`` -- list of permutations - - ``mutable`` -- whether the result is mutable or not. Default is ``False``. + - ``mutable`` -- boolean (default: ``False``); whether the result is + mutable or not - - ``connected`` -- whether the result should be connected. Default is - ``True``. + - ``connected`` -- boolean (default: ``True``); whether the result should + be connected - - ``check`` -- whether or not to check. If it is ``True``, then the - list ``g`` must contains no ``None``. + - ``check`` -- boolean (default: ``True``); whether or not to check. If it + is ``True``, then the list ``g`` must contain no ``None``. EXAMPLES: @@ -181,7 +182,7 @@ def Constellation(g=None, mutable=False, connected=True, check=True): class Constellation_class(Element): r""" - Constellation + Constellation. A constellation or a tuple of permutations `(g_0,g_1,...,g_k)` such that the product `g_0 g_1 ... g_k` is the identity. @@ -360,7 +361,8 @@ def genus(self): def _check(self): r""" - Check that the constellation is valid and if not raise ValueError. + Check that the constellation is valid and if not raise + :exc:`ValueError`. TESTS:: @@ -447,9 +449,7 @@ def connected_components(self): """ Return the connected components. - OUTPUT: - - A list of connected constellations. + OUTPUT: list of connected constellations EXAMPLES:: @@ -675,7 +675,7 @@ def g(self, i=None): INPUT: - - i -- integer or ``None`` (default) + - ``i`` -- integer or ``None`` (default) If ``None`` , return instead the list of all `g_i`. @@ -932,9 +932,9 @@ def __init__(self, length, degree, sym=None, connected=True): self._length = length self._degree = degree if self._length < 0: - raise ValueError("length should be a non-negative integer") + raise ValueError("length should be a nonnegative integer") if self._degree < 0: - raise ValueError("degree should be a non-negative integer") + raise ValueError("degree should be a nonnegative integer") self._sym = sym @@ -1187,9 +1187,7 @@ def braid_group_action(self): Return a list of graphs that corresponds to the braid group action on ``self`` up to isomorphism. - OUTPUT: - - - list of graphs + OUTPUT: list of graphs EXAMPLES:: @@ -1278,10 +1276,10 @@ def __init__(self, profile, domain=None, connected=True): r""" OPTIONS: - - ``profile`` -- a list of integer partitions of the same integer + - ``profile`` -- list of integer partitions of the same integer - - ``connected`` -- a boolean (default: ``True``) that specify - if we consider only connected constellations. + - ``connected`` -- boolean (default: ``True``); whether we consider + only connected constellations TESTS:: @@ -1469,7 +1467,7 @@ def perms_sym_init(g, sym=None): - ``sym`` -- a symmetric group - - ``gg`` -- a list of permutations + - ``gg`` -- list of permutations EXAMPLES:: @@ -1520,13 +1518,13 @@ def perms_sym_init(g, sym=None): def perms_are_connected(g, n): """ - Checks that the action of the generated group is transitive + Check that the action of the generated group is transitive. INPUT: - - a list of permutations of `[0, n-1]` (in a SymmetricGroup) + - ``g`` -- list of permutations of `[0, n-1]` (in a SymmetricGroup) - - an integer `n` + - ``n`` -- integer EXAMPLES:: @@ -1547,7 +1545,7 @@ def perms_are_connected(g, n): def perms_canonical_labels_from(x, y, j0, verbose=False): r""" - Return canonical labels for ``x``, ``y`` that starts at ``j0`` + Return canonical labels for ``x``, ``y`` that starts at ``j0``. .. WARNING:: @@ -1562,9 +1560,7 @@ def perms_canonical_labels_from(x, y, j0, verbose=False): - ``j0`` -- an index in [0, ..., n] - OUTPUT: - - mapping: a permutation that specify the new labels + OUTPUT: mapping: a permutation that specify the new labels EXAMPLES:: @@ -1636,11 +1632,9 @@ def perm_invert(p): INPUT: - a permutation of {0,..,n-1} given by a list of values - - OUTPUT: + - ``p`` -- a permutation of {0,..,n-1} given by a list of values - a permutation of {0,..,n-1} given by a list of values + OUTPUT: a permutation of {0,..,n-1} given by a list of values EXAMPLES:: @@ -1656,15 +1650,13 @@ def perm_invert(p): def perm_conjugate(p, s): """ - Return the conjugate of the permutation `p` by the permutation `s`. + Return the conjugate of the permutation `p` by the permutation `s`. INPUT: - two permutations of {0,..,n-1} given by lists of values - - OUTPUT: + - ``p``, ``s`` -- two permutations of {0,..,n-1} given by lists of values - a permutation of {0,..,n-1} given by a list of values + OUTPUT: a permutation of {0,..,n-1} given by a list of values EXAMPLES:: @@ -1685,16 +1677,14 @@ def perms_canonical_labels(p, e=None): INPUT: - - ``p`` is a list of at least 2 permutations + - ``p`` -- list of at least 2 permutations - - ``e`` is None or a list of integer in the domain of the + - ``e`` -- ``None`` or a list of integer in the domain of the permutations. If provided, then the renumbering algorithm is only performed from the elements of ``e``. - OUTPUT: - - - a pair made of a list of permutations (as a list of lists) and a - list that corresponds to the conjugacy used. + OUTPUT: a pair made of a list of permutations (as a list of lists) and a + list that corresponds to the conjugacy used. EXAMPLES:: diff --git a/src/sage/combinat/core.py b/src/sage/combinat/core.py index 41265d793db..d6775040c48 100644 --- a/src/sage/combinat/core.py +++ b/src/sage/combinat/core.py @@ -346,11 +346,13 @@ def affine_symmetric_group_action(self, w, transposition=False): INPUT: - - ``w`` is a tuple of integers `[w_1,\ldots,w_m]` with `0\le w_j= l2 >= 0``. If - ``l1`` and ``l2` are integers, this will produce a crystal + ``l1`` and ``l2`` are integers, this will produce a crystal isomorphic to the one obtained by ``crystals.Tableaux(type, shape=[l1,l2])``. Furthermore ``crystals.FastRankTwo(['B', 2], l1+1/2, l2+1/2)`` produces a crystal @@ -101,9 +101,9 @@ class FastCrystal(UniqueRepresentation, Parent): [2, 1, 0]] """ @staticmethod - def __classcall__(cls, cartan_type, shape, format="string"): + def __classcall__(cls, cartan_type, shape, format='string'): """ - Normalize the input arguments to ensure unique representation + Normalize the input arguments to ensure unique representation. EXAMPLES:: @@ -261,7 +261,7 @@ def __call__(self, value): def digraph(self): """ - Return the digraph associated to self. + Return the digraph associated to ``self``. EXAMPLES:: @@ -273,7 +273,7 @@ def digraph(self): def cmp_elements(self, x,y): r""" - Return True if and only if there is a path from x to y in the + Return ``True`` if and only if there is a path from `x` to `y` in the crystal graph. Because the crystal graph is classical, it is a directed acyclic @@ -318,7 +318,7 @@ def __init__(self, parent, value, format): def weight(self): """ - Return the weight of self. + Return the weight of ``self``. EXAMPLES:: @@ -403,7 +403,7 @@ def _richcmp_(self, other, op): def e(self, i): """ - Return the action of `e_i` on self. + Return the action of `e_i` on ``self``. EXAMPLES:: @@ -422,7 +422,7 @@ def e(self, i): def f(self, i): """ - Return the action of `f_i` on self. + Return the action of `f_i` on ``self``. EXAMPLES:: diff --git a/src/sage/combinat/crystals/fully_commutative_stable_grothendieck.py b/src/sage/combinat/crystals/fully_commutative_stable_grothendieck.py index 5e33395086d..9ba9e3c1e0a 100644 --- a/src/sage/combinat/crystals/fully_commutative_stable_grothendieck.py +++ b/src/sage/combinat/crystals/fully_commutative_stable_grothendieck.py @@ -76,7 +76,7 @@ class DecreasingHeckeFactorization(Element, metaclass=InheritComparisonClasscall @staticmethod def __classcall_private__(self, t, max_value=None, parent=None): """ - Assign the correct parent for ``t`` and call ``t`` as an element of that parent + Assign the correct parent for ``t`` and call ``t`` as an element of that parent. EXAMPLES:: @@ -209,7 +209,7 @@ def __hash__(self): def __eq__(self, other): """ - Return True if ``self`` equals ``other`` and False otherwise. + Return ``True`` if ``self`` equals ``other`` and ``False`` otherwise. EXAMPLES:: @@ -224,7 +224,8 @@ def __eq__(self, other): def __lt__(self,other): """ - Return True if ``self`` comes before ``other`` and False otherwise. + Return ``True`` if ``self`` comes before ``other`` and ``False`` + otherwise. We say that `h_1` comes before `h_2` if either weight of `h_1 <` weight of `h_2` lexicographically, or if both weights of `h_1` and `h_2` are equal, @@ -446,9 +447,11 @@ class FullyCommutativeStableGrothendieckCrystal(UniqueRepresentation, Parent): - ``factors`` -- the number of factors in the factorization - - ``excess`` -- the total number of letters in the factorization minus the length of a reduced word for ``w`` + - ``excess`` -- the total number of letters in the factorization minus the + length of a reduced word for ``w`` - - ``shape`` -- (default: ``False``) indicator for input ``w``, True if ``w`` is entered as a (skew) shape and False otherwise. + - ``shape`` -- boolean (default: ``False``); indicator for input ``w``, + ``True`` if ``w`` is entered as a (skew) shape and ``False`` otherwise EXAMPLES:: @@ -847,9 +850,9 @@ def _generate_decreasing_hecke_factorizations(w, factors, ex, weight=None, paren - ``ex`` -- number of extra letters in each decreasing factorizations - - ``weight`` -- (default: None) if None, returns all possible decreasing - factorizations, otherwise return all those with the - specified weight + - ``weight`` -- (default: ``None``) if ``None``, returns all possible + decreasing factorizations, otherwise return all those with the specified + weight EXAMPLES:: @@ -962,7 +965,8 @@ def _lowest_weights(w, factors, ex, parent=None): - ``ex`` -- number of extra letters in each decreasing factorizations - - ``parent`` -- (default: None) parent of the decreasing factorizations, automatically assigned if it is None + - ``parent`` -- (default: ``None``) parent of the decreasing + factorizations, automatically assigned if it is None EXAMPLES:: @@ -1143,27 +1147,27 @@ def _apply_relations(word, position, move): sage: from sage.combinat.crystals.fully_commutative_stable_grothendieck import _apply_relations sage: w = [2, 1, 3, 4] - sage: _apply_relations(w, position=1, move="pq=qp") + sage: _apply_relations(w, position=1, move='pq=qp') [2, 3, 1, 4] sage: w = [1, 3, 2, 1, 2, 4] - sage: _apply_relations(w, position=2, move="pqp=qpq") + sage: _apply_relations(w, position=2, move='pqp=qpq') [1, 3, 1, 2, 1, 4] sage: w = [2, 3, 1, 2, 2, 3] - sage: _apply_relations(w, position=3, move="pp=p") + sage: _apply_relations(w, position=3, move='pp=p') [2, 3, 1, 2, 3] sage: w = [2, 3, 1, 2, 3] - sage: _apply_relations(w, position=3, move="p=pp") + sage: _apply_relations(w, position=3, move='p=pp') [2, 3, 1, 2, 2, 3] sage: w = [2, 3, 1, 2, 2, 3] - sage: _apply_relations(w, position=2, move="pqq=ppq") + sage: _apply_relations(w, position=2, move='pqq=ppq') [2, 3, 1, 1, 2, 3] sage: w = [2, 3, 1, 1, 2, 3] - sage: _apply_relations(w, position=2, move="ppq=pqq") + sage: _apply_relations(w, position=2, move='ppq=pqq') [2, 3, 1, 2, 2, 3] """ w = list(word) diff --git a/src/sage/combinat/crystals/generalized_young_walls.py b/src/sage/combinat/crystals/generalized_young_walls.py index d88a200eaf0..65e1af9b61b 100644 --- a/src/sage/combinat/crystals/generalized_young_walls.py +++ b/src/sage/combinat/crystals/generalized_young_walls.py @@ -247,8 +247,8 @@ def _sig_sort(self, a): INPUT: - - `a` -- list of the form ``['s',j,k]`` where `s` is a string, `j` is an integer - and `k` is an integer + - ``a`` -- list of the form ``['s',j,k]`` where `s` is a string, `j` is + an integer and `k` is an integer EXAMPLES:: @@ -547,7 +547,7 @@ def weight(self, root_lattice=False): INPUT: - ``root_lattice`` -- boolean determining whether weight should appear - in root lattice or not in extended affine weight lattice. + in root lattice or not in extended affine weight lattice EXAMPLES:: diff --git a/src/sage/combinat/crystals/highest_weight_crystals.py b/src/sage/combinat/crystals/highest_weight_crystals.py index 96d7377c029..ef731d57692 100644 --- a/src/sage/combinat/crystals/highest_weight_crystals.py +++ b/src/sage/combinat/crystals/highest_weight_crystals.py @@ -192,7 +192,6 @@ def HighestWeightCrystal(dominant_weight, model=None): ....: C1 = crystals.HighestWeight(wt.to_ambient().to_weight_space(ZZ), model=model) ....: C2 = crystals.HighestWeight(wt, model=model) ....: assert C1 == C2 - """ cartan_type = dominant_weight.parent().cartan_type() if model is None: @@ -310,8 +309,8 @@ def _repr_(self): def module_generator(self): """ - This yields the module generator (or highest weight element) of the classical - crystal of given dominant weight in self. + Yield the module generator (or highest weight element) of the classical + crystal of given dominant weight in ``self``. EXAMPLES:: diff --git a/src/sage/combinat/crystals/induced_structure.py b/src/sage/combinat/crystals/induced_structure.py index 95ed85bf5f8..094a0e7a37b 100644 --- a/src/sage/combinat/crystals/induced_structure.py +++ b/src/sage/combinat/crystals/induced_structure.py @@ -47,8 +47,8 @@ class InducedCrystal(UniqueRepresentation, Parent): - ``X`` -- the base set - ``phi`` -- the map `\Phi` - ``inverse`` -- (optional) the inverse map `\Phi^{-1}` - - ``from_crystal`` -- (default: ``False``) if the induced structure is - of the second type `\Phi : C \to X` + - ``from_crystal`` -- boolean (default: ``False``); if the induced + structure is of the second type `\Phi : C \to X` EXAMPLES: diff --git a/src/sage/combinat/crystals/infinity_crystals.py b/src/sage/combinat/crystals/infinity_crystals.py index 8b2053bec8b..a7f98a369fb 100644 --- a/src/sage/combinat/crystals/infinity_crystals.py +++ b/src/sage/combinat/crystals/infinity_crystals.py @@ -130,7 +130,7 @@ class InfinityCrystalOfTableaux(CrystalOfWords): INPUT: - - ``cartan_type`` -- One of ``['A',n]``, ``['B',n]``, ``['C',n]``, + - ``cartan_type`` -- one of ``['A',n]``, ``['B',n]``, ``['C',n]``, ``['D',n]``, or ``['G',2]``, where ``n`` is a positive integer EXAMPLES:: @@ -307,7 +307,7 @@ def phi(self,i): INPUT: - - ``i`` -- An element of the index set + - ``i`` -- an element of the index set EXAMPLES:: @@ -448,7 +448,7 @@ def reduced_form(self): def seg(self): r""" - Returns the statistic `\mathrm{seg}` of ``self.`` + Return the statistic `\mathrm{seg}` of ``self``. More precisely, following [LS2012]_, define a `k`-segment of a tableau `T` in `\mathcal{B}(\infty)` to be a maximal string diff --git a/src/sage/combinat/crystals/kirillov_reshetikhin.py b/src/sage/combinat/crystals/kirillov_reshetikhin.py index 3f3a2eaf0a7..18b1882014d 100644 --- a/src/sage/combinat/crystals/kirillov_reshetikhin.py +++ b/src/sage/combinat/crystals/kirillov_reshetikhin.py @@ -164,7 +164,7 @@ def KirillovReshetikhinCrystal(cartan_type, r, s, model='KN'): - ``r`` -- a label of finite Dynkin diagram - - ``s`` -- a positive integer + - ``s`` -- positive integer - ``model`` -- (default: ``'KN'``) can be one of the following: @@ -434,7 +434,7 @@ class KirillovReshetikhinGenericCrystal(AffineCrystalFromClassical): def __init__(self, cartan_type, r, s, dual=None): r""" - Initializes a generic Kirillov-Reshetikhin crystal. + Initialize a generic Kirillov-Reshetikhin crystal. TESTS:: @@ -932,8 +932,8 @@ def dynkin_diagram_automorphism(self, i): return aut[i] def promotion_on_highest_weight_vector(self, b): - """ - Calculates promotion on a `{2,3,...,n}` highest weight vector ``b``. + r""" + Calculate promotion on a `{2, 3, \ldots, n}` highest weight vector `b`. EXAMPLES:: @@ -1887,7 +1887,7 @@ class KR_type_box(KirillovReshetikhinGenericCrystal, AffineCrystalFromClassical) def __init__(self, cartan_type, r, s): r""" - Initializes a Kirillov-Reshetikhin crystal ``self``. + Initialize a Kirillov-Reshetikhin crystal ``self``. TESTS:: @@ -1984,7 +1984,7 @@ def ambient_highest_weight_dict(self): def similarity_factor(self): r""" - Sets the similarity factor used to map to the ambient crystal. + Set the similarity factor used to map to the ambient crystal. EXAMPLES:: @@ -2274,7 +2274,7 @@ def ambient_highest_weight_dict(self): def similarity_factor(self): r""" - Sets the similarity factor used to map to the ambient crystal. + Set the similarity factor used to map to the ambient crystal. EXAMPLES:: @@ -2290,7 +2290,7 @@ def similarity_factor(self): @cached_method def to_ambient_crystal(self): r""" - Return a map from self to the ambient crystal of type `A_{2n-1}^{(2)}`. + Return a map from ``self`` to the ambient crystal of type `A_{2n-1}^{(2)}`. EXAMPLES:: @@ -2735,7 +2735,6 @@ def from_highest_weight_vector_to_pm_diagram(self, b): sage: hw = [ b for b in T if all(b.epsilon(i)==0 for i in [2,3]) ] sage: all(K.from_pm_diagram_to_highest_weight_vector(K.from_highest_weight_vector_to_pm_diagram(b)) == b for b in hw) True - """ n = self.cartan_type().rank() - 1 s = self.s() @@ -3836,7 +3835,7 @@ def pp(self): def inner_shape(self): """ - Return the inner shape of the pm diagram + Return the inner shape of the pm diagram. EXAMPLES:: @@ -3857,7 +3856,7 @@ def inner_shape(self): def outer_shape(self): r""" - Return the outer shape of the `\pm` diagram + Return the outer shape of the `\pm` diagram. EXAMPLES:: @@ -3883,7 +3882,8 @@ def outer_shape(self): def intermediate_shape(self): """ - Return the intermediate shape of the pm diagram (inner shape plus positions of plusses) + Return the intermediate shape of the pm diagram (inner shape plus + positions of plusses). EXAMPLES:: @@ -4104,7 +4104,7 @@ class CrystalDiagramAutomorphism(CrystalMorphism): weight elements - ``index_set`` -- (default: the empty set) the index set - ``automorphism`` -- (default: the identity) the twisting automorphism - - ``cache`` -- (default: ``True``) cache the result + - ``cache`` -- boolean (default: ``True``); cache the result """ def __init__(self, C, on_hw, index_set=None, automorphism=None, cache=True): diff --git a/src/sage/combinat/crystals/letters.pyx b/src/sage/combinat/crystals/letters.pyx index f54a4705047..93434bc1bd7 100644 --- a/src/sage/combinat/crystals/letters.pyx +++ b/src/sage/combinat/crystals/letters.pyx @@ -1360,7 +1360,7 @@ cdef class LetterTuple(Element): cpdef _richcmp_(left, right, int op): """ - Check comparison between ``left`` and ``right`` based on ``op`` + Check comparison between ``left`` and ``right`` based on ``op``. EXAMPLES:: @@ -2825,7 +2825,7 @@ cdef class LetterWrapped(Element): cpdef _richcmp_(left, right, int op): """ - Check comparison between ``left`` and ``right`` based on ``op`` + Check comparison between ``left`` and ``right`` based on ``op``. EXAMPLES:: diff --git a/src/sage/combinat/crystals/littelmann_path.py b/src/sage/combinat/crystals/littelmann_path.py index 2bc8396f7a4..c9fa7cb7933 100644 --- a/src/sage/combinat/crystals/littelmann_path.py +++ b/src/sage/combinat/crystals/littelmann_path.py @@ -760,7 +760,7 @@ def one_dimensional_configuration_sum(self, q=None, group_components=True): - ``q`` -- (default: ``None``) a variable or ``None``; if ``None``, a variable ``q`` is set in the code - - ``group_components`` -- (default: ``True``) boolean; if ``True``, + - ``group_components`` -- boolean (default: ``True``); if ``True``, then the terms are grouped by classical component The one-dimensional configuration sum is the sum of the weights @@ -997,7 +997,7 @@ def weyl_group_representation(self): """ cartan = self.parent().weight.parent().cartan_type().classical() I = cartan.index_set() - W = WeylGroup(cartan, prefix='s', implementation="permutation") + W = WeylGroup(cartan, prefix='s', implementation='permutation') return [W.from_reduced_word(x.to_dominant_chamber(index_set=I, reduced_word=True)[1]) for x in self.value] @cached_in_parent_method @@ -1151,7 +1151,7 @@ def energy_function(self): ct = P.cartan_type() cartan = ct.classical() Qv = RootSystem(cartan).coroot_lattice() - W = WeylGroup(cartan, prefix='s', implementation="permutation") + W = WeylGroup(cartan, prefix='s', implementation='permutation') J = tuple(weight.weyl_stabilizer()) L = self.weyl_group_representation() if ct.is_untwisted_affine() or ct.type() == 'BC': @@ -1160,7 +1160,7 @@ def energy_function(self): else: untwisted = False cartan_dual = cartan.dual() - Wd = WeylGroup(cartan_dual, prefix='s', implementation="permutation") + Wd = WeylGroup(cartan_dual, prefix='s', implementation='permutation') G = Wd.quantum_bruhat_graph(J) Qd = RootSystem(cartan_dual).root_lattice() @@ -1305,7 +1305,7 @@ def e(self, i, power=1, length_only=False): - ``i`` -- element of the index set - ``power`` -- (default: 1) positive integer; specifies the power of the lowering operator to be applied - - ``length_only`` -- (default: ``False``) boolean; if ``True``, + - ``length_only`` -- boolean (default: ``False``); if ``True``, then return the distance to the anti-dominant end of the `i`-string of ``self`` @@ -1382,7 +1382,7 @@ def f(self, i, power=1, length_only=False): - ``i`` -- element of the index set - ``power`` -- (default: 1) positive integer; specifies the power of the lowering operator to be applied - - ``length_only`` -- (default: ``False``) boolean; if ``True``, + - ``length_only`` -- boolean (default: ``False``); if ``True``, then return the distance to the anti-dominant end of the `i`-string of ``self`` diff --git a/src/sage/combinat/crystals/monomial_crystals.py b/src/sage/combinat/crystals/monomial_crystals.py index 48804bd9c15..567f3c4aa3d 100644 --- a/src/sage/combinat/crystals/monomial_crystals.py +++ b/src/sage/combinat/crystals/monomial_crystals.py @@ -135,7 +135,7 @@ def __init__(self, parent, Y, A): r""" INPUT: - - ``d`` -- a dictionary of with pairs of the form ``{(i,k): y}`` + - ``d`` -- dictionary of with pairs of the form ``{(i,k): y}`` EXAMPLES:: @@ -700,7 +700,7 @@ class InfinityCrystalOfNakajimaMonomials(UniqueRepresentation, Parent): where `\{h_i : i \in I\}` and `\{\Lambda_i : i \in I \}` are the simple coroots and fundamental weights, respectively. With a chosen set of - non-negative integers `C = (c_{ij})_{i\neq j}` such that + nonnegative integers `C = (c_{ij})_{i\neq j}` such that `c_{ij} + c_{ji} = 1`, one defines .. MATH:: @@ -792,12 +792,12 @@ def _normalize_c(c, n): sage: C = InfinityCrystalOfNakajimaMonomials._normalize_c(c, 2) Traceback (most recent call last): ... - ValueError: the c matrix must have 0's on the diagonal + ValueError: the c matrix must have 0s on the diagonal sage: c = matrix([[0,2],[-1,0]]) sage: C = InfinityCrystalOfNakajimaMonomials._normalize_c(c, 2) Traceback (most recent call last): ... - ValueError: the c matrix must have non-negative entries + ValueError: the c matrix must have nonnegative entries sage: c = matrix([[0,1],[1,0]]) sage: C = InfinityCrystalOfNakajimaMonomials._normalize_c(c, 2) Traceback (most recent call last): @@ -811,11 +811,11 @@ def _normalize_c(c, n): c = MS(c) c.set_immutable() if any(c[i,i] != 0 for i in range(n)): - raise ValueError("the c matrix must have 0's on the diagonal") + raise ValueError("the c matrix must have 0s on the diagonal") if any(c[i,j] + c[j,i] != 1 for i in range(n) for j in range(i)): raise ValueError("transpose entries do not sum to 1") if any(c[i,j] < 0 or c[j,i] < 0 for i in range(n) for j in range(i)): - raise ValueError("the c matrix must have non-negative entries") + raise ValueError("the c matrix must have nonnegative entries") return c @staticmethod @@ -864,9 +864,9 @@ def _element_constructor_(self, Y=None, A=None): INPUT: - - ``Y`` -- a dictionary whose key is a pair and whose value + - ``Y`` -- dictionary whose key is a pair and whose value is an integer - - ``A`` -- a dictionary whose key is a pair and whose value + - ``A`` -- dictionary whose key is a pair and whose value is an integer EXAMPLES:: diff --git a/src/sage/combinat/crystals/pbw_datum.pyx b/src/sage/combinat/crystals/pbw_datum.pyx index 2adcb09d902..03a7aee51d9 100644 --- a/src/sage/combinat/crystals/pbw_datum.pyx +++ b/src/sage/combinat/crystals/pbw_datum.pyx @@ -44,7 +44,7 @@ class PBWDatum(): sage: from sage.combinat.crystals.pbw_datum import PBWData, PBWDatum sage: P = PBWData("A2") sage: L = PBWDatum(P, (1,2,1), (1,4,7)) - sage: TestSuite(L).run(skip="_test_pickling") + sage: TestSuite(L).run(skip='_test_pickling') """ self.parent = parent self.long_word = tuple(long_word) @@ -195,7 +195,7 @@ class PBWData(): # UniqueRepresentation? sage: from sage.combinat.crystals.pbw_datum import PBWData sage: P = PBWData(["A",2]) - sage: TestSuite(P).run(skip="_test_pickling") + sage: TestSuite(P).run(skip='_test_pickling') """ self.cartan_type = CartanType(cartan_type) self.root_system = RootSystem(self.cartan_type) @@ -243,7 +243,7 @@ class PBWData(): # UniqueRepresentation? INPUT: - - ``reduced_word`` -- a tuple corresponding to a reduced word + - ``reduced_word`` -- tuple corresponding to a reduced word EXAMPLES:: @@ -422,10 +422,10 @@ cpdef list enhance_braid_move_chain(braid_move_chain, cartan_type): ``(interval_of_change, cartan_sub_matrix)`` where - ``interval_of_change`` is the (half-open) interval of indices where - the braid move occurs; this is `None` for the first tuple + the braid move occurs; this is ``None`` for the first tuple - ``cartan_sub_matrix`` is the off-diagonal entries of the `2 \times 2` submatrix of the Cartan matrix corresponding to the braid move; - this is `None` for the first tuple + this is ``None`` for the first tuple For a matrix:: diff --git a/src/sage/combinat/crystals/spins.pyx b/src/sage/combinat/crystals/spins.pyx index 869447915c4..5ff109602d0 100644 --- a/src/sage/combinat/crystals/spins.pyx +++ b/src/sage/combinat/crystals/spins.pyx @@ -73,7 +73,7 @@ def CrystalOfSpins(ct): INPUT: - - ``['B', n]`` -- A Cartan type `B_n`. + - ``['B', n]`` -- a Cartan type `B_n` EXAMPLES:: @@ -113,7 +113,7 @@ def CrystalOfSpinsPlus(ct): INPUT: - - ``['D', n]`` -- A Cartan type `D_n`. + - ``['D', n]`` -- a Cartan type `D_n` EXAMPLES:: @@ -146,7 +146,7 @@ def CrystalOfSpinsMinus(ct): INPUT: - - ``['D', n]`` -- A Cartan type `D_n`. + - ``['D', n]`` -- a Cartan type `D_n` EXAMPLES:: @@ -494,7 +494,7 @@ cdef class Spin(Element): def _latex_(self): r""" - Gives the latex output of a spin column. + Give the latex output of a spin column. EXAMPLES:: diff --git a/src/sage/combinat/crystals/tensor_product.py b/src/sage/combinat/crystals/tensor_product.py index e0482ec74eb..8d35ecd8c90 100644 --- a/src/sage/combinat/crystals/tensor_product.py +++ b/src/sage/combinat/crystals/tensor_product.py @@ -196,7 +196,7 @@ class TensorProductOfCrystals(CrystalOfWords): .. RUBRIC:: Regular crystals Now if all crystals `B_k` are regular crystals, all `\varepsilon_i` and - `\varphi_i` are non-negative and we can + `\varphi_i` are nonnegative and we can define tensor product by the *signature rule*. We start by writing a word in `+` and `-` as follows: @@ -408,7 +408,7 @@ def __classcall_private__(cls, *crystals, **options): # add options to class class options(GlobalOptions): r""" - Sets the global options for tensor products of crystals. The default is to + Set the global options for tensor products of crystals. The default is to use the anti-Kashiwara convention. There are two conventions for how `e_i` and `f_i` act on tensor products, @@ -447,11 +447,11 @@ class options(GlobalOptions): """ NAME = 'TensorProductOfCrystals' module = 'sage.combinat.crystals' - convention = dict(default="antiKashiwara", + convention = dict(default='antiKashiwara', description='Sets the convention used for displaying/inputting tensor product of crystals', values=dict(antiKashiwara='use the anti-Kashiwara convention', Kashiwara='use the Kashiwara convention'), - alias=dict(anti="antiKashiwara", opposite="antiKashiwara"), + alias=dict(anti='antiKashiwara', opposite='antiKashiwara'), case_sensitive=False) def _element_constructor_(self, *crystalElements): @@ -705,13 +705,13 @@ class Element(TensorProductOfQueerSuperCrystalsElement): class CrystalOfTableaux(CrystalOfWords): r""" - A class for crystals of tableaux with integer valued shapes + A class for crystals of tableaux with integer valued shapes. INPUT: - ``cartan_type`` -- a Cartan type - ``shape`` -- a partition of length at most ``cartan_type.rank()`` - - ``shapes`` -- a list of such partitions + - ``shapes`` -- list of such partitions This constructs a classical crystal with the given Cartan type and highest weight(s) corresponding to the given shape(s). @@ -886,13 +886,12 @@ class CrystalOfTableaux(CrystalOfWords): Traceback (most recent call last): ... ValueError: entries of each shape must be weakly decreasing - """ @staticmethod def __classcall_private__(cls, cartan_type, shapes=None, shape=None): """ - Normalizes the input arguments to ensure unique representation, + Normalize the input arguments to ensure unique representation, and to delegate the construction of spin tableaux. EXAMPLES:: @@ -909,7 +908,6 @@ def __classcall_private__(cls, cartan_type, shapes=None, shape=None): sage: T2 = crystals.Tableaux(['A', [1,1]], [3,1,1,1]) sage: T1 is T2 True - """ cartan_type = CartanType(cartan_type) if cartan_type.letter == 'A' and isinstance(cartan_type, SuperCartanType_standard): @@ -979,8 +977,8 @@ def __init__(self, cartan_type, shapes): INPUT: - ``cartan_type`` -- (data coercible into) a Cartan type - - ``shapes`` -- a list (or iterable) of shapes - - ``shape`` -- a shape + - ``shapes`` -- list (or iterable) of shapes + - ``shape`` -- a shape Shapes themselves are lists (or iterable) of integers. @@ -999,7 +997,7 @@ def __init__(self, cartan_type, shapes): def cartan_type(self): """ - Returns the Cartan type of the associated crystal + Return the Cartan type of the associated crystal. EXAMPLES:: @@ -1071,7 +1069,7 @@ class CrystalOfQueerTableaux(CrystalOfWords, QueerSuperCrystalsMixin): INPUT: - ``cartan_type`` -- a Cartan type - - ``shape`` -- a shape + - ``shape`` -- a shape """ def __init__(self, cartan_type, shape): diff --git a/src/sage/combinat/crystals/tensor_product_element.pyx b/src/sage/combinat/crystals/tensor_product_element.pyx index 42a7f271092..607dcc2a8dc 100644 --- a/src/sage/combinat/crystals/tensor_product_element.pyx +++ b/src/sage/combinat/crystals/tensor_product_element.pyx @@ -42,7 +42,7 @@ from sage.rings.integer_ring import ZZ cdef class ImmutableListWithParent(ClonableArray): r""" - A class for lists having a parent + A class for lists having a parent. Specification: any subclass ``C`` should implement ``__init__`` which accepts the following form ``C(parent, list=list)`` @@ -76,7 +76,7 @@ cdef class ImmutableListWithParent(ClonableArray): cpdef _set_index(self, k, value): r""" Return a sibling of ``self`` obtained by setting the - `k^{th}` entry of self to value. + `k`-th entry of ``self`` to value. EXAMPLES:: @@ -948,7 +948,6 @@ cdef class CrystalOfTableauxElement(TensorProductOfRegularCrystalsElement): [2, 1] sage: x.shape() [2, 1] - """ return self.to_tableau().shape() diff --git a/src/sage/combinat/crystals/virtual_crystal.py b/src/sage/combinat/crystals/virtual_crystal.py index e7286e58c01..5373e277bbd 100644 --- a/src/sage/combinat/crystals/virtual_crystal.py +++ b/src/sage/combinat/crystals/virtual_crystal.py @@ -64,9 +64,9 @@ class VirtualCrystal(Subcrystal): INPUT: - ``ambient`` -- the ambient crystal - - ``virtualization`` -- a dictionary whose key `i` corresponds + - ``virtualization`` -- dictionary whose key `i` corresponds to the set `\sigma_i` - - ``scaling_factors`` -- a dictionary whose key `i` corresponds to + - ``scaling_factors`` -- dictionary whose key `i` corresponds to the scaling factor `\gamma_i` - ``contained`` -- (optional) a set (or function) which specifies when an element is contained in the subcrystal; the default is everything diff --git a/src/sage/combinat/cyclic_sieving_phenomenon.py b/src/sage/combinat/cyclic_sieving_phenomenon.py index 8ad3bfc1f0c..ce6d6e58454 100644 --- a/src/sage/combinat/cyclic_sieving_phenomenon.py +++ b/src/sage/combinat/cyclic_sieving_phenomenon.py @@ -42,14 +42,14 @@ def CyclicSievingPolynomial(L, cyc_act=None, order=None, get_order=False): - ``L`` -- if ``cyc_act`` is ``None``: list of orbit sizes, otherwise list of objects - - ``cyc_act`` -- (default:``None``) bijective function from ``L`` to ``L`` + - ``cyc_act`` -- (default: ``None``) bijective function from ``L`` to ``L`` - - ``order`` -- (default:``None``) if set to an integer, this + - ``order`` -- (default: ``None``) if set to an integer, this cyclic order of ``cyc_act`` is used (must be an integer multiple of the order of ``cyc_act``) otherwise, the order of ``cyc_action`` is used - - ``get_order`` -- (default:``False``) if ``True``, a tuple ``[p,n]`` + - ``get_order`` -- (default: ``False``) if ``True``, a tuple ``[p,n]`` is returned where ``p`` is as above, and ``n`` is the order EXAMPLES:: @@ -132,9 +132,9 @@ def CyclicSievingCheck(L, cyc_act, f, order=None) -> bool: - ``L`` -- if ``cyc_act`` is ``None``: list of orbit sizes, otherwise list of objects - - ``cyc_act`` -- (default:``None``) bijective function from ``L`` to ``L`` + - ``cyc_act`` -- (default: ``None``) bijective function from ``L`` to ``L`` - - ``order`` -- (default:``None``) if set to an integer, this + - ``order`` -- (default: ``None``) if set to an integer, this cyclic order of ``cyc_act`` is used (must be an integer multiple of the order of ``cyc_act``) otherwise, the order of ``cyc_action`` is used @@ -173,9 +173,7 @@ def orbit_decomposition(L, cyc_act) -> list[list]: - ``cyc_act`` -- bijective function from ``L`` to ``L`` - OUTPUT: - - - a list of lists, the orbits under the cyc_act acting on ``L`` + OUTPUT: list of lists, the orbits under the cyc_act acting on ``L`` EXAMPLES:: diff --git a/src/sage/combinat/debruijn_sequence.pyx b/src/sage/combinat/debruijn_sequence.pyx index 01dbf826c90..54a58dc734b 100644 --- a/src/sage/combinat/debruijn_sequence.pyx +++ b/src/sage/combinat/debruijn_sequence.pyx @@ -74,9 +74,9 @@ def debruijn_sequence(int k, int n): INPUT: - - ``k`` -- Arity. Must be an integer. + - ``k`` -- arity; must be an integer - - ``n`` -- Substring length. Must be an integer. + - ``n`` -- substring length; must be an integer EXAMPLES:: @@ -113,14 +113,14 @@ cdef gen(int t, int p, k, n): def is_debruijn_sequence(seq, k, n): r""" - Given a sequence of integer elements in `0..k-1`, tests whether it + Given a sequence of integer elements in `0, \ldots, k-1`, tests whether it corresponds to a De Bruijn sequence of parameters `k` and `n`. INPUT: - - ``seq`` -- Sequence of elements in `0..k-1`. + - ``seq`` -- sequence of elements in `0, \ldots, k-1` - - ``n``, ``k`` -- Integers. + - ``n``, ``k`` -- integers EXAMPLES:: @@ -193,8 +193,8 @@ from sage.rings.integer_ring import ZZ class DeBruijnSequences(UniqueRepresentation, Parent): - """ - Represents the De Bruijn sequences of given parameters `k` and `n`. + r""" + Represent the De Bruijn sequences of given parameters `k` and `n`. A De Bruijn sequence of parameters `k` and `n` is defined as the shortest cyclic sequence that incorporates all substrings of length `n` a `k`-ary @@ -206,10 +206,10 @@ class DeBruijnSequences(UniqueRepresentation, Parent): INPUT: - - ``k`` -- A natural number to define arity. The letters used are the - integers `0..k-1`. + - ``k`` -- a natural number to define arity; the letters used are the + integers `0, \ldots, k-1` - - ``n`` -- A natural number that defines the length of the substring. + - ``n`` -- a natural number that defines the length of the substring EXAMPLES: @@ -263,7 +263,7 @@ class DeBruijnSequences(UniqueRepresentation, Parent): TESTS: Setting ``n`` or ``k`` to anything under 1 will return - a :class:`ValueError`:: + a :exc:`ValueError`:: sage: DeBruijnSequences(3, 0).an_element() Traceback (most recent call last): @@ -271,7 +271,7 @@ class DeBruijnSequences(UniqueRepresentation, Parent): ValueError: k and n cannot be under 1 Setting ``n`` or ``k`` to any type except an integer will return a - :class:`TypeError`:: + :exc:`TypeError`:: sage: DeBruijnSequences(2.5, 3).an_element() Traceback (most recent call last): @@ -302,7 +302,7 @@ class DeBruijnSequences(UniqueRepresentation, Parent): def an_element(self): """ - Returns the lexicographically smallest De Bruijn sequence with the given + Return the lexicographically smallest De Bruijn sequence with the given parameters. ALGORITHM: @@ -320,12 +320,12 @@ class DeBruijnSequences(UniqueRepresentation, Parent): def __contains__(self, seq): r""" - Tests whether the given sequence is a De Bruijn sequence with + Test whether the given sequence is a De Bruijn sequence with the current object's parameters. INPUT: - - ``seq`` -- A sequence of integers. + - ``seq`` -- a sequence of integers EXAMPLES:: @@ -337,7 +337,7 @@ class DeBruijnSequences(UniqueRepresentation, Parent): def cardinality(self): """ - Returns the number of distinct De Bruijn sequences for the object's + Return the number of distinct De Bruijn sequences for the object's parameters. EXAMPLES:: diff --git a/src/sage/combinat/decorated_permutation.py b/src/sage/combinat/decorated_permutation.py index 817be65223d..01b3b112caa 100644 --- a/src/sage/combinat/decorated_permutation.py +++ b/src/sage/combinat/decorated_permutation.py @@ -71,7 +71,6 @@ def __classcall_private__(cls, pi): sage: hash(elt1) # random 915443076393556996 - """ pi = list(pi) return DecoratedPermutations(len(pi))(pi) @@ -137,7 +136,7 @@ class DecoratedPermutations(UniqueRepresentation, Parent): INPUT: - - `n` -- an integer, the size of the decorated permutations. + - ``n`` -- integer; the size of the decorated permutations EXAMPLES: @@ -148,7 +147,6 @@ class DecoratedPermutations(UniqueRepresentation, Parent): Decorated permutations of size 3 sage: S.cardinality() 16 - """ def __init__(self, n): @@ -230,7 +228,6 @@ def _an_element_(self): sage: S = DecoratedPermutations(3) sage: S._an_element_() [1, 2, 3] - """ return self.element_class(self, list(range(1, self._n + 1))) diff --git a/src/sage/combinat/degree_sequences.pyx b/src/sage/combinat/degree_sequences.pyx index 6a0b070a44e..4e0d282d068 100644 --- a/src/sage/combinat/degree_sequences.pyx +++ b/src/sage/combinat/degree_sequences.pyx @@ -286,7 +286,7 @@ class DegreeSequences: def __init__(self, n): r""" - Degree Sequences + Degree Sequences. An instance of this class represents the degree sequences of graphs on a given number `n` of vertices. It can be used to list and count them, as @@ -383,7 +383,7 @@ class DegreeSequences: def __repr__(self): """ - Representing the element + Representing the element. TESTS:: @@ -416,7 +416,7 @@ class DegreeSequences: cdef init(int n): """ - Initializes the memory and starts the enumeration algorithm. + Initialize the memory and starts the enumeration algorithm. """ global seq global N diff --git a/src/sage/combinat/derangements.py b/src/sage/combinat/derangements.py index 6b2d868b90d..53398e6b727 100644 --- a/src/sage/combinat/derangements.py +++ b/src/sage/combinat/derangements.py @@ -89,7 +89,7 @@ class Derangements(UniqueRepresentation, Parent): INPUT: - - ``x`` -- Can be an integer which corresponds to derangements of + - ``x`` -- can be an integer which corresponds to derangements of `\{1, 2, 3, \ldots, x\}`, a list, or a string REFERENCES: diff --git a/src/sage/combinat/descent_algebra.py b/src/sage/combinat/descent_algebra.py index 8ab3886012f..617e0d615a2 100644 --- a/src/sage/combinat/descent_algebra.py +++ b/src/sage/combinat/descent_algebra.py @@ -66,7 +66,7 @@ class DescentAlgebra(UniqueRepresentation, Parent): - ``R`` -- the base ring - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer REFERENCES: @@ -219,7 +219,7 @@ class D(CombinatorialFreeModule, BindableClass): [D{}] """ - def __init__(self, alg, prefix="D"): + def __init__(self, alg, prefix='D'): r""" Initialize ``self``. @@ -232,7 +232,7 @@ def __init__(self, alg, prefix="D"): CombinatorialFreeModule.__init__(self, alg.base_ring(), SubsetsSorted(range(1, alg._n)), category=DescentAlgebraBases(alg), - bracket="", prefix=prefix) + bracket='', prefix=prefix) # Change of basis: B = alg.B() @@ -422,7 +422,7 @@ class B(CombinatorialFreeModule, BindableClass): The basis element `B_p` is denoted `\Xi^p` in [Sch2004]_. By using compositions of `n`, the product `B_p B_q` becomes a - sum over the non-negative-integer matrices `M` with row sum `p` + sum over the nonnegative-integer matrices `M` with row sum `p` and column sum `q`. The summand corresponding to `M` is `B_c`, where `c` is the composition obtained by reading `M` row-by-row from left-to-right and top-to-bottom and removing all zeroes. @@ -438,7 +438,7 @@ class B(CombinatorialFreeModule, BindableClass): B[2, 1, 1], B[2, 2], B[3, 1], B[4]] """ - def __init__(self, alg, prefix="B"): + def __init__(self, alg, prefix='B'): r""" Initialize ``self``. @@ -451,7 +451,7 @@ def __init__(self, alg, prefix="B"): CombinatorialFreeModule.__init__(self, alg.base_ring(), Compositions(alg._n), category=DescentAlgebraBases(alg), - bracket="", prefix=prefix) + bracket='', prefix=prefix) S = NonCommutativeSymmetricFunctions(alg.base_ring()).Complete() self.module_morphism(self.to_nsym, @@ -671,7 +671,7 @@ class I(CombinatorialFreeModule, BindableClass): [I[1, 1, 1, 1], I[1, 1, 2], I[1, 2, 1], I[1, 3], I[2, 1, 1], I[2, 2], I[3, 1], I[4]] """ - def __init__(self, alg, prefix="I"): + def __init__(self, alg, prefix='I'): r""" Initialize ``self``. @@ -684,7 +684,7 @@ def __init__(self, alg, prefix="I"): CombinatorialFreeModule.__init__(self, alg.base_ring(), Compositions(alg._n), category=DescentAlgebraBases(alg), - bracket="", prefix=prefix) + bracket='', prefix=prefix) # Change of basis: B = alg.B() @@ -743,7 +743,7 @@ def one(self): def one_basis(self): """ The element `1` is not (generally) a basis vector in the `I` - basis, thus this raises a :class:`TypeError`. + basis, thus this raises a :exc:`TypeError`. EXAMPLES:: diff --git a/src/sage/combinat/designs/MOLS_handbook_data.py b/src/sage/combinat/designs/MOLS_handbook_data.py index cc555400101..7c56f13f5d2 100644 --- a/src/sage/combinat/designs/MOLS_handbook_data.py +++ b/src/sage/combinat/designs/MOLS_handbook_data.py @@ -565,6 +565,5 @@ def lower_bound(order: int) -> int: sage: from sage.combinat.designs import MOLS_handbook_data sage: MOLS_handbook_data.lower_bound(0) 0 - """ return _LOWER_BOUNDS[order] diff --git a/src/sage/combinat/designs/bibd.py b/src/sage/combinat/designs/bibd.py index 48e24b4ac75..1ccd1a02ada 100644 --- a/src/sage/combinat/designs/bibd.py +++ b/src/sage/combinat/designs/bibd.py @@ -71,16 +71,16 @@ def biplane(n, existence=False): INPUT: - - ``n`` -- (integer) order of the biplane + - ``n`` -- integer; order of the biplane - - ``existence`` (boolean) -- instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - - ``True`` -- meaning that Sage knows how to build the design + - ``True`` -- meaning that Sage knows how to build the design - - ``Unknown`` -- meaning that Sage does not know how to build the - design, but that the design may exist (see :mod:`sage.misc.unknown`). + - ``Unknown`` -- meaning that Sage does not know how to build the + design, but that the design may exist (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that the design does not exist. + - ``False`` -- meaning that the design does not exist .. SEEALSO:: @@ -127,16 +127,16 @@ def balanced_incomplete_block_design(v, k, lambd=1, existence=False, use_LJCR=Fa - ``v``, ``k``, ``lambd`` -- integers - - ``existence`` (boolean) -- instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - ``True`` -- meaning that Sage knows how to build the design - ``Unknown`` -- meaning that Sage does not know how to build the - design, but that the design may exist (see :mod:`sage.misc.unknown`). + design, but that the design may exist (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that the design does not exist. + - ``False`` -- meaning that the design does not exist - - ``use_LJCR`` (boolean) -- whether to query the La Jolla Covering + - ``use_LJCR`` -- boolean; whether to query the La Jolla Covering Repository for the design when Sage does not know how to build it (see :func:`~sage.combinat.designs.covering_design.best_known_covering_design_www`). This requires internet. @@ -373,9 +373,7 @@ def BruckRyserChowla_check(v, k, lambd): - ``v``, ``k``, ``lambd`` -- integers; parameters to check - OUTPUT: - - - ``True`` -- the parameters satisfy the theorem + OUTPUT: ``True`` -- the parameters satisfy the theorem - ``False`` -- the theorem fails for the given parameters @@ -418,7 +416,6 @@ def BruckRyserChowla_check(v, k, lambd): sage: from sage.combinat.designs.bibd import BruckRyserChowla_check sage: BruckRyserChowla_check(13,25,50) # needs sage.schemes True - """ from sage.rings.rational_field import QQ @@ -438,7 +435,7 @@ def BruckRyserChowla_check(v, k, lambd): def steiner_triple_system(n): r""" - Return a Steiner Triple System + Return a Steiner Triple System. A Steiner Triple System (STS) of a set `\{0,...,n-1\}` is a family `S` of 3-sets such that for any `i \not = j` @@ -455,7 +452,7 @@ def steiner_triple_system(n): INPUT: - - ``n`` return a Steiner Triple System of `\{0,...,n-1\}` + - ``n`` -- return a Steiner Triple System of `\{0,...,n-1\}` EXAMPLES: @@ -528,9 +525,9 @@ def BIBD_from_TD(v,k,existence=False): INPUT: - - ``v``, ``k`` -- (integers) computes a `(v,k,1)`-BIBD. + - ``v``, ``k`` -- integers; computes a `(v,k,1)`-BIBD - - ``existence`` -- (boolean) instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - ``True`` -- meaning that Sage knows how to build the design @@ -683,12 +680,12 @@ def BIBD_from_difference_family(G, D, lambd=None, check=True): - ``G`` -- a finite additive Abelian group - - ``D`` -- a difference family on ``G`` (short blocks are allowed). + - ``D`` -- a difference family on ``G`` (short blocks are allowed) - ``lambd`` -- the `\lambda` parameter (optional, only used if ``check`` is ``True``) - - ``check`` -- whether or not we check the output (default: ``True``) + - ``check`` -- boolean (default: ``True``); whether or not we check the output EXAMPLES:: @@ -766,12 +763,11 @@ def v_4_1_BIBD(v, check=True): INPUT: - - ``v`` (integer) -- number of points. + - ``v`` -- integer; number of points - - ``check`` (boolean) -- whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -852,17 +848,16 @@ def BIBD_from_PBD(PBD, v, k, check=True, base_cases=None): INPUT: - - ``v``, ``k`` -- integers. + - ``v``, ``k`` -- integers - - ``PBD`` -- A PBD on `r=(v-1)/(k-1)` points, such that for any block of - ``PBD`` of size `s` there must exist a `((k-1)s+1,k,1)`-BIBD. + - ``PBD`` -- a PBD on `r=(v-1)/(k-1)` points, such that for any block of + ``PBD`` of size `s` there must exist a `((k-1)s+1,k,1)`-BIBD - - ``check`` (boolean) -- whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. - - ``base_cases`` -- caching system, for internal use. + - ``base_cases`` -- caching system, for internal use EXAMPLES:: @@ -897,17 +892,17 @@ def BIBD_from_PBD(PBD, v, k, check=True, base_cases=None): def _relabel_bibd(B,n,p=None): r""" - Relabels the BIBD on `n` points and blocks of size k such that + Relabel the BIBD on `n` points and blocks of size k such that `\{0,...,k-2,n-1\},\{k-1,...,2k-3,n-1\},...,\{n-k,...,n-2,n-1\}` are blocks of the BIBD. INPUT: - - ``B`` -- a list of blocks. + - ``B`` -- list of blocks - - ``n`` (integer) -- number of points. + - ``n`` -- integer; number of points - - ``p`` (optional) -- the point that will be labeled with `n-1`. + - ``p`` -- (optional) the point that will be labeled with `n-1` EXAMPLES:: @@ -944,12 +939,11 @@ def PBD_4_5_8_9_12(v, check=True): INPUT: - - ``v`` -- an integer congruent to `0` or `1` modulo `4`. + - ``v`` -- integer congruent to `0` or `1` modulo `4` - - ``check`` (boolean) -- whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -1083,7 +1077,7 @@ def _get_t_u(v): INPUT: - - ``v`` (integer) + - ``v`` -- integer EXAMPLES:: @@ -1115,7 +1109,7 @@ def v_5_1_BIBD(v, check=True): INPUT: - - ``v`` (integer) + - ``v`` -- integer .. SEEALSO:: @@ -1183,13 +1177,13 @@ def v_5_1_BIBD(v, check=True): def _get_r_s_t_u(v): r""" - Implements the table from [ClaytonSmith]_ + Implement the table from [ClaytonSmith]_. Return the parameters ``r,s,t,u`` associated with an integer ``v``. INPUT: - - ``v`` (integer) + - ``v`` -- integer EXAMPLES:: @@ -1233,7 +1227,7 @@ def PBD_from_TD(k,t,u): INPUT: - - ``k``, ``t``, ``u`` -- integers such that `0\leq u \leq t`. + - ``k``, ``t``, ``u`` -- integers such that `0\leq u \leq t` EXAMPLES:: @@ -1243,7 +1237,6 @@ def PBD_from_TD(k,t,u): [[0, 2, 4], [0, 3], [1, 2], [1, 3, 4], [0, 1], [2, 3]] sage: is_pairwise_balanced_design(PBD,2*2+1,[2,3]) True - """ from .orthogonal_arrays import transversal_design TD = transversal_design(k+bool(u),t, check=False) @@ -1262,7 +1255,7 @@ def BIBD_5q_5_for_q_prime_power(q): INPUT: - - ``q`` (integer) -- a prime power such that `q\equiv 1\pmod 4`. + - ``q`` -- integer; a prime power such that `q\equiv 1\pmod 4` EXAMPLES:: @@ -1308,9 +1301,9 @@ def BIBD_from_arc_in_desarguesian_projective_plane(n,k,existence=False): INPUT: - - ``n``, ``k`` (integers) -- must be powers of two (among other restrictions). + - ``n``, ``k`` -- integers; must be powers of two (among other restrictions) - - ``existence`` (boolean) -- whether to return the BIBD obtained through + - ``existence`` -- boolean; whether to return the BIBD obtained through this construction (default), or to merely indicate with a boolean return value whether this method *can* build the requested BIBD. @@ -1353,7 +1346,6 @@ def BIBD_from_arc_in_desarguesian_projective_plane(n,k,existence=False): Some maximal arcs in finite projective planes. Journal of Combinatorial Theory 6, no. 3 (1969): 317-319. :doi:`10.1016/S0021-9800(69)80095-5` - """ q = (n-1)//(k-1)-1 if (k % 2 or @@ -1404,7 +1396,7 @@ def BIBD_from_arc_in_desarguesian_projective_plane(n,k,existence=False): class PairwiseBalancedDesign(GroupDivisibleDesign): r""" - Pairwise Balanced Design (PBD) + Pairwise Balanced Design (PBD). A Pairwise Balanced Design, or `(v,K,\lambda)`-PBD, is a collection `\mathcal B` of blocks defined on a set `X` of size `v`, such that any block @@ -1414,34 +1406,32 @@ class PairwiseBalancedDesign(GroupDivisibleDesign): INPUT: - - ``points`` -- the underlying set. If ``points`` is an integer `v`, then - the set is considered to be `\{0, ..., v-1\}`. + - ``points`` -- the underlying set; if ``points`` is an integer `v`, then + the set is considered to be `\{0, ..., v-1\}` - ``blocks`` -- collection of blocks - ``K`` -- list of integers of which the sizes of the blocks must be - elements. Set to ``None`` (automatic guess) by default. + elements; set to ``None`` (automatic guess) by default - - ``lambd`` (integer) -- value of `\lambda`, set to `1` by default. + - ``lambd`` -- integer; value of `\lambda`, set to `1` by default - - ``check`` (boolean) -- whether to check that the design is a `PBD` with - the right parameters. + - ``check`` -- boolean; whether to check that the design is a `PBD` with + the right parameters - ``copy`` -- (use with caution) if set to ``False`` then ``blocks`` must be a list of lists of integers. The list will not be copied but will be modified in place (each block is sorted, and the whole list is sorted). Your ``blocks`` object will become the instance's internal data. - """ def __init__(self, points, blocks, K=None, lambd=1, check=True, copy=True,**kwds): r""" - Constructor + Constructor. EXAMPLES:: sage: designs.balanced_incomplete_block_design(13,3) # indirect doctest (13,3,1)-Balanced Incomplete Block Design - """ try: i = int(points) @@ -1462,7 +1452,7 @@ def __init__(self, points, blocks, K=None, lambd=1, check=True, copy=True,**kwds def __repr__(self): r""" - Return a string describing the PBD + Return a string describing the PBD. EXAMPLES:: @@ -1475,22 +1465,22 @@ def __repr__(self): class BalancedIncompleteBlockDesign(PairwiseBalancedDesign): r""" - Balanced Incomplete Block Design (BIBD) + Balanced Incomplete Block Design (BIBD). INPUT: - ``points`` -- the underlying set. If ``points`` is an integer `v`, then - the set is considered to be `\{0, ..., v-1\}`. + the set is considered to be `\{0, ..., v-1\}` - ``blocks`` -- collection of blocks - - ``k`` (integer) -- size of the blocks. Set to ``None`` (automatic guess) - by default. + - ``k`` -- integer; size of the blocks. Set to ``None`` (automatic guess) + by default - - ``lambd`` (integer) -- value of `\lambda`, set to `1` by default. + - ``lambd`` -- integer; value of `\lambda`, set to `1` by default - - ``check`` (boolean) -- whether to check that the design is a `PBD` with - the right parameters. + - ``check`` -- boolean; whether to check that the design is a `PBD` with + the right parameters - ``copy`` -- (use with caution) if set to ``False`` then ``blocks`` must be a list of lists of integers. The list will not be copied but will be @@ -1504,7 +1494,7 @@ class BalancedIncompleteBlockDesign(PairwiseBalancedDesign): """ def __init__(self, points, blocks, k=None, lambd=1, check=True, copy=True,**kwds): r""" - Constructor + Constructor. EXAMPLES:: @@ -1522,7 +1512,7 @@ def __init__(self, points, blocks, k=None, lambd=1, check=True, copy=True,**kwds def __repr__(self): r""" - A string to describe self + A string to describe ``self``. EXAMPLES:: @@ -1553,10 +1543,10 @@ def arc(self, s=2, solver=None, verbose=0, *, integrality_tolerance=1e-3): INPUT: - - ``s`` -- (default to ``2``) the maximum number of points from the arc + - ``s`` -- (default: `2`) the maximum number of points from the arc in each block - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1564,7 +1554,7 @@ def arc(self, s=2, solver=None, verbose=0, *, integrality_tolerance=1e-3): :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``). Sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- parameter for use with MILP solvers over diff --git a/src/sage/combinat/designs/block_design.py b/src/sage/combinat/designs/block_design.py index 96a4fc6e17c..e5faaa11602 100644 --- a/src/sage/combinat/designs/block_design.py +++ b/src/sage/combinat/designs/block_design.py @@ -196,9 +196,9 @@ def ProjectiveGeometryDesign(n, d, F, algorithm=None, point_coordinates=True, ch - ``n`` -- the projective dimension - - ``d`` -- the dimension of the subspaces which make up the blocks. + - ``d`` -- the dimension of the subspaces which make up the blocks - - ``F`` -- a finite field or a prime power. + - ``F`` -- a finite field or a prime power - ``algorithm`` -- set to ``None`` by default, which results in using Sage's own implementation. In order to use GAP's implementation instead (i.e. its @@ -210,7 +210,7 @@ def ProjectiveGeometryDesign(n, d, F, algorithm=None, point_coordinates=True, ch ``algorithm="gap"``. If ``True``, the ground set is indexed by coordinates in `\GF{q}^{n+1}`. Otherwise the ground set is indexed by integers. - - ``check`` -- (default: ``True``) whether to check the output. + - ``check`` -- boolean (default: ``True``); whether to check the output EXAMPLES: @@ -245,7 +245,7 @@ def ProjectiveGeometryDesign(n, d, F, algorithm=None, point_coordinates=True, ch Check that the constructor using gap also works:: - sage: BD = designs.ProjectiveGeometryDesign(2, 1, GF(2), algorithm="gap") # optional - gap_package_design + sage: BD = designs.ProjectiveGeometryDesign(2, 1, GF(2), algorithm='gap') # optional - gap_package_design sage: BD.is_t_design(return_parameters=True) # optional - gap_package_design (True, (2, 7, 3, 1)) """ @@ -270,7 +270,7 @@ def ProjectiveGeometryDesign(n, d, F, algorithm=None, point_coordinates=True, ch m.set_immutable() b.append(points[m]) blocks.append(b) - B = BlockDesign(len(points), blocks, name="ProjectiveGeometryDesign", check=check) + B = BlockDesign(len(points), blocks, name='ProjectiveGeometryDesign', check=check) if point_coordinates: B.relabel({i:p[0] for p,i in points.items()}) @@ -282,7 +282,7 @@ def ProjectiveGeometryDesign(n, d, F, algorithm=None, point_coordinates=True, ch gB = [] for b in gblcks: gB.append([x - 1 for x in b]) - B = BlockDesign(v, gB, name="ProjectiveGeometryDesign", check=check) + B = BlockDesign(v, gB, name='ProjectiveGeometryDesign', check=check) if check: from sage.combinat.q_analogues import q_binomial @@ -305,15 +305,14 @@ def DesarguesianProjectivePlaneDesign(n, point_coordinates=True, check=True): INPUT: - - ``n`` -- an integer which must be a power of a prime number + - ``n`` -- integer which must be a power of a prime number - - ``point_coordinates`` -- (boolean) whether to label the points with their - homogeneous coordinates (default) or with integers. + - ``point_coordinates`` -- boolean (default: ``True``); whether to label the + points with their homogeneous coordinates (default) or with integers - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. .. SEEALSO:: @@ -333,7 +332,6 @@ def DesarguesianProjectivePlaneDesign(n, point_coordinates=True, check=True): Traceback (most recent call last): ... ValueError: the order of a finite field must be a prime power - """ K = FiniteField(n, 'a') n2 = n**2 @@ -345,7 +343,7 @@ def DesarguesianProjectivePlaneDesign(n, point_coordinates=True, check=True): # plane into an affine plane, an affine line and a point. At the same time, # we relabel the points with the integers from 0 to n^2 + n as follows: # - the affine plane is the set of points [x:y:1] (i.e. the third coordinate - # is non-zero) and gets relabeled from 0 to n^2-1 + # is nonzero) and gets relabeled from 0 to n^2-1 affine_plane = lambda x,y: relabel[x] + n * relabel[y] # - the affine line is the set of points [x:1:0] (i.e. the third coordinate is @@ -522,10 +520,9 @@ def HughesPlane(q2, check=True): - ``q2`` -- an even power of an odd prime number - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -636,13 +633,12 @@ def projective_plane_to_OA(pplane, pt=None, check=True): - ``pplane`` -- a projective plane as a 2-design - - ``pt`` -- a point in the projective plane ``pplane``. If it is not provided, - then it is set to `n^2 + n`. + - ``pt`` -- a point in the projective plane ``pplane``; if it is not provided, + then it is set to `n^2 + n` - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -697,9 +693,9 @@ def projective_plane(n, check=True, existence=False): `n^2+n+1` points. For more information on finite projective planes, see the :wikipedia:`Projective_plane#Finite_projective_planes`. - If no construction is possible, then the function raises a :class:`EmptySetError`, + If no construction is possible, then the function raises a :exc:`EmptySetError`, whereas if no construction is available, the function raises a - :class:`NotImplementedError`. + :exc:`NotImplementedError`. INPUT: @@ -803,18 +799,18 @@ def AffineGeometryDesign(n, d, F, point_coordinates=True, check=True): INPUT: - - ``n`` (integer) -- the Euclidean dimension. The number of points of the - design is `v=|\GF{q}^n|`. + - ``n`` -- integer; the Euclidean dimension. The number of points of the + design is `v=|\GF{q}^n|` - - ``d`` (integer) -- the dimension of the (affine) subspaces of `\GF{q}^n` - which make up the blocks. + - ``d`` -- integer; the dimension of the (affine) subspaces of `\GF{q}^n` + which make up the blocks - - ``F`` -- a finite field or a prime power. + - ``F`` -- a finite field or a prime power - - ``point_coordinates`` -- (default: ``True``) whether we use - coordinates in `\GF{q}^n` or plain integers for the points of the design. + - ``point_coordinates`` -- boolean (default: ``True``); whether we use + coordinates in `\GF{q}^n` or plain integers for the points of the design - - ``check`` -- (default: ``True``) whether to check the output. + - ``check`` -- boolean (default: ``True``); whether to check the output EXAMPLES:: @@ -875,7 +871,7 @@ def AffineGeometryDesign(n, d, F, point_coordinates=True, check=True): b.append(points[m]) blocks.append(b) - B = BlockDesign(len(points), blocks, name="AffineGeometryDesign", check=check) + B = BlockDesign(len(points), blocks, name='AffineGeometryDesign', check=check) if point_coordinates: rd = {i: p[0][1:] for p, i in points.items()} @@ -923,7 +919,7 @@ def WittDesign(n): """ INPUT: - - ``n`` is in `9,10,11,12,21,22,23,24`. + - ``n`` -- integer in `9,10,11,12,21,22,23,24` Wraps GAP Design's WittDesign. If ``n=24`` then this function returns the large Witt design `W_{24}`, the unique (up to isomorphism) `5-(24,8,1)` @@ -950,7 +946,7 @@ def WittDesign(n): B = libgap.WittDesign(n) v = B['v'].sage() gB = [[x - 1 for x in b] for b in B['blocks'].sage()] - return BlockDesign(v, gB, name="WittDesign", check=True) + return BlockDesign(v, gB, name='WittDesign', check=True) def HadamardDesign(n): @@ -999,7 +995,7 @@ def HadamardDesign(n): MS = J.parent() A = MS((H2+J)/2) # convert -1's to 0's; coerce entries to ZZ # A is the incidence matrix of the block design - return IncidenceStructure(incidence_matrix=A,name="HadamardDesign") + return IncidenceStructure(incidence_matrix=A,name='HadamardDesign') def Hadamard3Design(n): @@ -1012,7 +1008,7 @@ def Hadamard3Design(n): INPUT: - - ``n`` (integer) -- a multiple of 4 such that `n>4`. + - ``n`` -- integer; a multiple of 4 such that `n>4` EXAMPLES:: @@ -1062,4 +1058,4 @@ def Hadamard3Design(n): A1 = (H1+J)/2 A2 = (J-H1)/2 A = block_matrix(1, 2, [A1, A2]) #the incidence matrix of the design. - return IncidenceStructure(incidence_matrix=A, name="HadamardThreeDesign") + return IncidenceStructure(incidence_matrix=A, name='HadamardThreeDesign') diff --git a/src/sage/combinat/designs/covering_design.py b/src/sage/combinat/designs/covering_design.py index a855dc601dc..30bbeafb708 100644 --- a/src/sage/combinat/designs/covering_design.py +++ b/src/sage/combinat/designs/covering_design.py @@ -63,11 +63,11 @@ def schonheim(v, k, t): INPUT: - - ``v`` -- integer, size of point set + - ``v`` -- integer; size of point set - - ``k`` -- integer, cardinality of each block + - ``k`` -- integer; cardinality of each block - - ``t`` -- integer, cardinality of sets being covered + - ``t`` -- integer; cardinality of sets being covered OUTPUT: @@ -95,11 +95,11 @@ def trivial_covering_design(v, k, t): INPUT: - - ``v`` -- integer, size of point set + - ``v`` -- integer; size of point set - - ``k`` -- integer, cardinality of each block + - ``k`` -- integer; cardinality of each block - - ``t`` -- integer, cardinality of sets being covered + - ``t`` -- integer; cardinality of sets being covered OUTPUT: @@ -141,7 +141,6 @@ def trivial_covering_design(v, k, t): `k` does not divide `v`. * anything else: Just use every `k`-subset of `[0, 1,..., v-1]`. - """ if t == 0: # single block [0, ..., k-1] blk = list(range(k)) @@ -171,13 +170,13 @@ class CoveringDesign(SageObject): - ``v``, ``k``, ``t`` -- integer parameters of the covering design - - ``size`` (integer) + - ``size`` -- integer - - ``points`` -- list of points (default points are `[0, ..., v-1]`) + - ``points`` -- list of points (default: `[0, ..., v-1]`) - ``blocks`` - - ``low_bd`` (integer) -- lower bound for such a design + - ``low_bd`` -- integer; lower bound for such a design - ``method``, ``creator``, ``timestamp`` -- database information """ @@ -335,7 +334,7 @@ def v(self): def k(self): """ - Return `k`, the size of blocks of the covering design + Return `k`, the size of blocks of the covering design. EXAMPLES:: @@ -366,7 +365,7 @@ def t(self): def size(self): """ - Return the number of blocks in the covering design + Return the number of blocks in the covering design. EXAMPLES:: @@ -418,7 +417,7 @@ def method(self): def creator(self): """ - Return the creator of the covering design + Return the creator of the covering design. This field is optional, and is used in a database to give attribution for the covering design It can refer to the person @@ -437,7 +436,7 @@ def creator(self): def timestamp(self): """ - Return the time that the covering was submitted to the database + Return the time that the covering was submitted to the database. EXAMPLES:: @@ -467,7 +466,6 @@ def incidence_structure(self): sage: D.blocks() [[0, 1, 2], [0, 3, 4], [0, 5, 6], [1, 3, 5], [1, 4, 6], [2, 3, 6], [2, 4, 5]] - """ return self.__incidence_structure @@ -481,13 +479,13 @@ def best_known_covering_design_www(v, k, t, verbose=False): INPUT: - - ``v`` -- integer, the size of the point set for the design + - ``v`` -- integer; the size of the point set for the design - - ``k`` -- integer, the number of points per block + - ``k`` -- integer; the number of points per block - - ``t`` -- integer, the size of sets covered by the blocks + - ``t`` -- integer; the size of sets covered by the blocks - - ``verbose`` -- bool (default: ``False``), print verbose message + - ``verbose`` -- boolean (default: ``False``); print verbose message OUTPUT: @@ -511,7 +509,7 @@ def best_known_covering_design_www(v, k, t, verbose=False): 2 3 6 2 4 5 - A :class:`ValueError` is raised if the ``(v, k, t)`` parameters are not + A :exc:`ValueError` is raised if the ``(v, k, t)`` parameters are not found in the database. """ v = int(v) diff --git a/src/sage/combinat/designs/database.py b/src/sage/combinat/designs/database.py index 943f7c9ba22..24684b4c3fb 100644 --- a/src/sage/combinat/designs/database.py +++ b/src/sage/combinat/designs/database.py @@ -68,15 +68,15 @@ def _MOLS_from_string(s,k): r""" - Return MOLS from a string + Return MOLS from a string. INPUT: - - ``s`` (string) -- represents the MOLS with entries in a-z. To understand + - ``s`` -- string; represents the MOLS with entries in a-z; to understand how the string should be formatted, read the source code of a constructor - that uses it. + that uses it - - ``k`` (integer) -- the number of MOLS encoded by the string. + - ``k`` -- integer; the number of MOLS encoded by the string EXAMPLES:: @@ -91,7 +91,7 @@ def _MOLS_from_string(s,k): def MOLS_10_2(): r""" - Return a pair of MOLS of order 10 + Return a pair of MOLS of order 10. Data obtained from ``_ @@ -134,7 +134,7 @@ def MOLS_10_2(): def MOLS_12_5(): r""" - Return 5 MOLS of order 12 + Return 5 MOLS of order 12. These MOLS have been found by Brendan McKay. @@ -165,7 +165,7 @@ def MOLS_12_5(): def MOLS_14_4(): r""" - Return four MOLS of order 14 + Return four MOLS of order 14. These MOLS were shared by Ian Wanless. The first proof of existence was given in [Todorov12]_. @@ -310,7 +310,7 @@ def MOLS_18_3(): def OA_7_18(): r""" - Return an OA(7,18) + Return an OA(7,18). Proved in [JulianAbel13]_. @@ -364,7 +364,7 @@ def OA_7_18(): def OA_9_40(): r""" - Return an OA(9,40) + Return an OA(9,40). As explained in the Handbook III.3.62 [DesignHandbook]_. Uses the fact that `40 = 2^3 \times 5` and that `5` is prime. @@ -404,7 +404,7 @@ def OA_9_40(): def OA_7_66(): r""" - Return an OA(7,66) + Return an OA(7,66). Construction shared by Julian R. Abel. @@ -444,7 +444,7 @@ def OA_7_66(): def OA_7_68(): r""" - Return an OA(7,68) + Return an OA(7,68). Construction shared by Julian R. Abel. @@ -484,7 +484,7 @@ def OA_7_68(): def OA_8_69(): r""" - Return an OA(8,69) + Return an OA(8,69). Construction shared by Julian R. Abel. @@ -556,7 +556,7 @@ def OA_8_69(): def OA_7_74(): r""" - Return an OA(7,74) + Return an OA(7,74). Construction shared by Julian R. Abel. @@ -596,7 +596,7 @@ def OA_7_74(): def OA_8_76(): r""" - Return an OA(8,76) + Return an OA(8,76). Construction shared by Julian R. Abel. @@ -663,7 +663,7 @@ def OA_8_76(): def OA_11_80(): r""" - Return an OA(11,80) + Return an OA(11,80). As explained in the Handbook III.3.76 [DesignHandbook]_. Uses the fact that `80 = 2^4 \times 5` and that `5` is prime. @@ -705,7 +705,7 @@ def OA_11_80(): def OA_15_112(): r""" - Returns an OA(15,112) + Return an OA(15,112). Published by Julian R. Abel in [Ab1995]_. Uses the fact that 112 = `2^4 \times 7` and that `7` is prime. @@ -751,7 +751,7 @@ def OA_15_112(): def OA_9_120(): r""" - Return an OA(9,120) + Return an OA(9,120). Construction shared by Julian R. Abel: @@ -797,7 +797,7 @@ def OA_9_120(): def OA_9_135(): r""" - Return an OA(9,135) + Return an OA(9,135). Construction shared by Julian R. Abel: @@ -882,7 +882,7 @@ def OA_9_135(): def OA_11_160(): r""" - Returns an OA(11,160) + Return an OA(11,160). Published by Julian R. Abel in [Ab1995]_. Uses the fact that `160 = 2^5 \times 5` is a product of a power of `2` and a prime number. @@ -925,7 +925,7 @@ def OA_11_160(): def OA_16_176(): r""" - Returns an OA(16,176) + Return an OA(16,176). Published by Julian R. Abel in [Ab1995]_. Uses the fact that `176 = 2^4 \times 11` is a product of a power of `2` and a prime number. @@ -979,7 +979,7 @@ def OA_16_176(): def OA_11_185(): r""" - Returns an OA(11,185) + Return an OA(11,185). The construction is given in [Greig99]_. In Julian R. Abel's words: @@ -1005,7 +1005,6 @@ def OA_11_185(): sage: designs.orthogonal_arrays.is_available(11,185) # needs sage.schemes True - """ from sage.combinat.designs.difference_family import difference_family @@ -1124,7 +1123,7 @@ def OA_10_205(): def OA_16_208(): r""" - Returns an OA(16,208) + Return an OA(16,208). Published by Julian R. Abel in [Ab1995]_. Uses the fact that `208 = 2^4 \times 13` is a product of `2` and a prime number. @@ -1183,7 +1182,7 @@ def OA_16_208(): def OA_15_224(): r""" - Returns an OA(15,224) + Return an OA(15,224). Published by Julian R. Abel in [Ab1995]_ (uses the fact that `224=2^5 \times 7` is a product of a power of `2` and a prime number). @@ -1230,7 +1229,7 @@ def OA_15_224(): def OA_11_254(): r""" - Return an OA(11,254) + Return an OA(11,254). This constructions appears in [Greig99]_. @@ -1269,7 +1268,7 @@ def OA_11_254(): def OA_20_352(): r""" - Returns an OA(20,352) + Return an OA(20,352). Published by Julian R. Abel in [Ab1995]_ (uses the fact that `352=2^5 \times 11` is the product of a power of `2` and a prime number). @@ -1328,7 +1327,7 @@ def OA_20_352(): def OA_20_416(): r""" - Returns an OA(20,416) + Return an OA(20,416). Published by Julian R. Abel in [Ab1995]_ (uses the fact that `416=2^5 \times 13` is the product of a power of `2` and a prime number). @@ -1388,7 +1387,7 @@ def OA_20_416(): def OA_20_544(): r""" - Returns an OA(20,544) + Return an OA(20,544). Published by Julian R. Abel in [Ab1995]_ (uses the fact that `544=2^5 \times 17` is the product of a power of `2` and a prime number). @@ -1457,7 +1456,7 @@ def OA_20_544(): def OA_17_560(): r""" - Returns an OA(17,560) + Return an OA(17,560). This OA is built in Corollary 2.2 of [Thwarts]_. @@ -1516,7 +1515,7 @@ def OA_17_560(): def OA_11_640(): r""" - Returns an OA(11,640) + Return an OA(11,640). Published by Julian R. Abel in [Ab1995]_ (uses the fact that `640=2^7 \times 5` is the product of a power of `2` and a prime number). @@ -1558,7 +1557,7 @@ def OA_11_640(): def OA_10_796(): r""" - Returns an OA(10,796) + Return an OA(10,796). Construction shared by Julian R. Abel, from [AC07]_: @@ -1629,7 +1628,7 @@ def OA_10_796(): def OA_10_469(): r""" - Return an OA(10,469) + Return an OA(10,469). This construction appears in [Brouwer80]_. It is based on the same technique used in @@ -1740,7 +1739,6 @@ def OA_520_plus_x(x): sage: OA = OA_520_plus_x(0) # not tested (already tested in OA_10_520) sage: is_orthogonal_array(OA,10,520,2) # not tested (already tested in OA_10_520) True - """ from .orthogonal_arrays import incomplete_orthogonal_array k = 9+x+1 @@ -1799,7 +1797,7 @@ def OA_10_520(): def OA_12_522(): r""" - Return an OA(12,522) + Return an OA(12,522). This design is built by the slightly more general construction :func:`OA_520_plus_x`. @@ -1821,7 +1819,7 @@ def OA_12_522(): def OA_14_524(): r""" - Return an OA(14,524) + Return an OA(14,524). This design is built by the slightly more general construction :func:`OA_520_plus_x`. @@ -1843,7 +1841,7 @@ def OA_14_524(): def OA_15_896(): r""" - Returns an OA(15,896) + Return an OA(15,896). Uses the fact that `896 = 2^7 \times 7` is the product of a power of `2` and a prime number. @@ -1890,7 +1888,7 @@ def OA_15_896(): def OA_9_1078(): r""" - Returns an OA(9,1078) + Return an OA(9,1078). This is obtained through the generalized Brouwer-van Rees construction. Indeed, `1078 = 89.11 + (99=9.11)` and there exists an @@ -1920,7 +1918,7 @@ def OA_9_1078(): def OA_25_1262(): r""" - Returns an OA(25,1262) + Return an OA(25,1262). The construction is given in [Greig99]_. In Julian R. Abel's words: @@ -1957,7 +1955,7 @@ def OA_25_1262(): def OA_9_1612(): r""" - Returns an OA(9,1612) + Return an OA(9,1612). This is obtained through the generalized Brouwer-van Rees construction. Indeed, `1612 = 89.17 + (99=9.11)` and there exists an @@ -1987,7 +1985,7 @@ def OA_9_1612(): def OA_10_1620(): r""" - Returns an OA(10,1620) + Return an OA(10,1620). This is obtained through the generalized Brouwer-van Rees construction. Indeed, `1620 = 144.11+(36=4.9)` and there exists an @@ -2712,7 +2710,7 @@ def QDM_57_9_1_1_8(): for m in _all_m) r""" -Tests for the Vmt vectors +Test for the Vmt vectors EXAMPLES:: @@ -3877,7 +3875,6 @@ def DM_60_6_1(): http://onlinelibrary.wiley.com/doi/10.1002/jcd.21384/abstract - EXAMPLES:: sage: from sage.combinat.designs.designs_pyx import is_difference_matrix @@ -4053,7 +4050,7 @@ def DM_993_32_1(): def RBIBD_120_8_1(): r""" - Return a resolvable `BIBD(120,8,1)` + Return a resolvable `BIBD(120,8,1)`. This function output a list ``L`` of `17\times 15` blocks such that ``L[i*15:(i+1)*15]`` is a partition of `120`. @@ -4143,8 +4140,8 @@ def BIBD_45_9_8(from_code=False): INPUT: - - ``from_code`` (boolean) -- whether to build the design from hardcoded data - (default) or from the code object (much longer). + - ``from_code`` -- boolean; whether to build the design from hardcoded data + (default) or from the code object (much longer) EXAMPLES:: diff --git a/src/sage/combinat/designs/designs_pyx.pyx b/src/sage/combinat/designs/designs_pyx.pyx index 054e5782930..20839d9c8aa 100644 --- a/src/sage/combinat/designs/designs_pyx.pyx +++ b/src/sage/combinat/designs/designs_pyx.pyx @@ -24,20 +24,20 @@ def is_covering_array(array, strength=None, levels=None, verbose=False, paramete INPUT: - - ``array`` -- the Covering Array to be tested. + - ``array`` -- the Covering Array to be tested - - ``strength`` (integer) -- the parameter `t` of the covering array, + - ``strength`` -- integer; the parameter `t` of the covering array, such that in any selection of `t` columns of the array, every `t` -tuple appears at least once. If set to None then all t > 0 are tested to and the maximal strength is used. - - ``levels`` -- the number of symbols that appear in ``array``. - If set to None, then each unique entry in ``array`` is counted. + - ``levels`` -- the number of symbols that appear in ``array`` + If set to None, then each unique entry in ``array`` is counted - - ``verbose`` (boolean) -- whether to display some information about - the covering array. + - ``verbose`` -- boolean; whether to display some information about + the covering array - - ``parameters`` (boolean) -- whether to return the parameters of + - ``parameters`` -- boolean; whether to return the parameters of the Covering Array. If set to ``True``, the function returns a pair ``(boolean_answer,(N,t,k,v))``. @@ -145,7 +145,6 @@ def is_covering_array(array, strength=None, levels=None, verbose=False, paramete ....: [0, 1, 1, 2, 0, 2, 2, 1]] sage: is_covering_array(C,strength=2,parameters=True) (False, (8, 0, 8, 3)) - """ from itertools import product, combinations @@ -211,7 +210,7 @@ def is_covering_array(array, strength=None, levels=None, verbose=False, paramete return result -def is_orthogonal_array(OA, int k, int n, int t=2, verbose=False, terminology="OA"): +def is_orthogonal_array(OA, int k, int n, int t=2, verbose=False, terminology='OA'): r""" Check that the integer matrix `OA` is an `OA(k,n,t)`. @@ -222,13 +221,13 @@ def is_orthogonal_array(OA, int k, int n, int t=2, verbose=False, terminology="O - ``OA`` -- the Orthogonal Array to be tested - - ``k``, ``n``, ``t`` (integers) -- only implemented for `t=2`. + - ``k``, ``n``, ``t`` -- integers; only implemented for `t=2` - - ``verbose`` (boolean) -- whether to display some information when ``OA`` - is not an orthogonal array `OA(k,n)`. + - ``verbose`` -- boolean; whether to display some information when ``OA`` + is not an orthogonal array `OA(k,n)` - - ``terminology`` (string) -- how to phrase the information when ``verbose = - True``. Possible values are `"OA"`, `"MOLS"`. + - ``terminology`` -- string; how to phrase the information when ``verbose = + True``. Possible values are `"OA"`, `"MOLS"` EXAMPLES:: @@ -245,7 +244,7 @@ def is_orthogonal_array(OA, int k, int n, int t=2, verbose=False, terminology="O sage: is_orthogonal_array(OA,8,9,verbose=True) Columns 0 and 3 are not orthogonal False - sage: is_orthogonal_array(OA,8,9, verbose=True, terminology="MOLS") + sage: is_orthogonal_array(OA,8,9, verbose=True, terminology='MOLS') Squares 0 and 3 are not orthogonal False @@ -259,13 +258,13 @@ def is_orthogonal_array(OA, int k, int n, int t=2, verbose=False, terminology="O sage: is_orthogonal_array([[3]*8],8,9, verbose=True) The number of rows is 1 instead of 9^2=81 False - sage: is_orthogonal_array([[3]*8],8,9, verbose=True, terminology="MOLS") + sage: is_orthogonal_array([[3]*8],8,9, verbose=True, terminology='MOLS') All squares do not have dimension n^2=9^2 False sage: is_orthogonal_array([[3]*7],8,9, verbose=True) Some row does not have length 8 False - sage: is_orthogonal_array([[3]*7],8,9, verbose=True, terminology="MOLS") + sage: is_orthogonal_array([[3]*7],8,9, verbose=True, terminology='MOLS') The number of squares is not 6 False @@ -353,7 +352,7 @@ def is_orthogonal_array(OA, int k, int n, int t=2, verbose=False, terminology="O def is_group_divisible_design(groups,blocks,v,G=None,K=None,lambd=1,verbose=False): r""" - Checks that input is a Group Divisible Design on `\{0,...,v-1\}` + Check that input is a Group Divisible Design on `\{0, \ldots, v-1\}`. For more information on Group Divisible Designs, see :class:`~sage.combinat.designs.group_divisible_designs.GroupDivisibleDesign`. @@ -366,18 +365,18 @@ def is_group_divisible_design(groups,blocks,v,G=None,K=None,lambd=1,verbose=Fals - ``blocks`` -- collection of blocks - - ``v`` (integers) -- size of the ground set assumed to be `X=\{0,...,v-1\}`. + - ``v`` -- integers; size of the ground set assumed to be `X=\{0,...,v-1\}` - ``G`` -- list of integers of which the sizes of the groups must be - elements. Set to ``None`` (automatic guess) by default. + elements. Set to ``None`` (automatic guess) by default - ``K`` -- list of integers of which the sizes of the blocks must be - elements. Set to ``None`` (automatic guess) by default. + elements. Set to ``None`` (automatic guess) by default - - ``lambd`` -- value of `\lambda`. Set to `1` by default. + - ``lambd`` -- value of `\lambda`. Set to `1` by default - - ``verbose`` (boolean) -- whether to display some information when the - design is not a GDD. + - ``verbose`` -- boolean; whether to display some information when the + design is not a GDD EXAMPLES:: @@ -430,7 +429,7 @@ def is_group_divisible_design(groups,blocks,v,G=None,K=None,lambd=1,verbose=Fals if v < 0 or lambd < 0: if verbose: - print("v={} and lambda={} must be non-negative integers".format(v,l)) + print("v={} and lambda={} must be nonnegative integers".format(v,l)) return False # Block sizes are element of K @@ -537,7 +536,7 @@ def is_group_divisible_design(groups,blocks,v,G=None,K=None,lambd=1,verbose=Fals def is_pairwise_balanced_design(blocks,v,K=None,lambd=1,verbose=False): r""" - Checks that input is a Pairwise Balanced Design (PBD) on `\{0,...,v-1\}` + Check that input is a Pairwise Balanced Design (PBD) on `\{0, \ldots, v-1\}`. For more information on Pairwise Balanced Designs (PBD), see :class:`~sage.combinat.designs.bibd.PairwiseBalancedDesign`. @@ -546,15 +545,15 @@ def is_pairwise_balanced_design(blocks,v,K=None,lambd=1,verbose=False): - ``blocks`` -- collection of blocks - - ``v`` (integers) -- size of the ground set assumed to be `X=\{0,...,v-1\}`. + - ``v`` -- integers; size of the ground set assumed to be `X=\{0,...,v-1\}` - ``K`` -- list of integers of which the sizes of the blocks must be - elements. Set to ``None`` (automatic guess) by default. + elements; set to ``None`` (automatic guess) by default - - ``lambd`` -- value of `\lambda`. Set to `1` by default. + - ``lambd`` -- value of `\lambda` (default: `1`) - - ``verbose`` (boolean) -- whether to display some information when the - design is not a PBD. + - ``verbose`` -- boolean; whether to display some information when the + design is not a PBD EXAMPLES:: @@ -593,7 +592,7 @@ def is_pairwise_balanced_design(blocks,v,K=None,lambd=1,verbose=False): def is_projective_plane(blocks, verbose=False): r""" - Test whether the blocks form a projective plane on `\{0,...,v-1\}` + Test whether the blocks form a projective plane on `\{0,...,v-1\}`. A *projective plane* is an incidence structure that has the following properties: @@ -612,7 +611,6 @@ def is_projective_plane(blocks, verbose=False): - ``verbose`` -- whether to print additional information - EXAMPLES:: sage: from sage.combinat.designs.designs_pyx import is_projective_plane @@ -681,10 +679,10 @@ def is_difference_matrix(M,G,k,lmbda=1,verbose=False): - ``k`` -- integer - - ``lmbda`` (integer) -- set to `1` by default. + - ``lmbda`` -- integer (default: `1`) - - ``verbose`` (boolean) -- whether to print some information when the answer - is ``False``. + - ``verbose`` -- boolean; whether to print some information when the answer + is ``False`` EXAMPLES:: @@ -732,7 +730,7 @@ def is_difference_matrix(M,G,k,lmbda=1,verbose=False): def is_quasi_difference_matrix(M,G,int k,int lmbda,int mu,int u,verbose=False): r""" - Test if the matrix is a `(G,k;\lambda,\mu;u)`-quasi-difference matrix + Test if the matrix is a `(G,k;\lambda,\mu;u)`-quasi-difference matrix. Let `G` be an abelian group of order `n`. A `(n,k;\lambda,\mu;u)`-quasi-difference matrix (QDM) is a matrix `Q_{ij}` @@ -757,8 +755,8 @@ def is_quasi_difference_matrix(M,G,int k,int lmbda,int mu,int u,verbose=False): - ``k``, ``lmbda``, ``mu``, ``u`` -- integers - - ``verbose`` (boolean) -- whether to print some information when the answer - is ``False``. + - ``verbose`` -- boolean; whether to print some information when the answer + is ``False`` EXAMPLES: @@ -954,15 +952,15 @@ _OA_cache[0].max_true = -1 _OA_cache[1].max_true = -1 _OA_cache_size = 2 -cpdef _OA_cache_set(int k,int n,truth_value): +cpdef _OA_cache_set(int k, int n, truth_value): r""" - Sets a value in the OA cache of existence results + Set a value in the OA cache of existence results. INPUT: - - ``k``, ``n`` (integers) + - ``k``, ``n`` -- integers - - ``truth_value`` -- one of ``True,False,Unknown`` + - ``truth_value`` -- one of ``True``, ``False``, ``Unknown`` """ global _OA_cache, _OA_cache_size cdef int i @@ -991,7 +989,7 @@ cpdef _OA_cache_set(int k,int n,truth_value): cpdef _OA_cache_get(int k,int n): r""" - Gets a value from the OA cache of existence results + Get a value from the OA cache of existence results. INPUT: @@ -1010,7 +1008,7 @@ cpdef _OA_cache_get(int k,int n): cpdef _OA_cache_construction_available(int k,int n): r""" - Tests if a construction is implemented using the cache's information + Test if a construction is implemented using the cache's information. INPUT: diff --git a/src/sage/combinat/designs/difference_family.py b/src/sage/combinat/designs/difference_family.py index eb45720a67d..bb8bb30d5bc 100644 --- a/src/sage/combinat/designs/difference_family.py +++ b/src/sage/combinat/designs/difference_family.py @@ -135,8 +135,8 @@ def is_difference_family(G, D, v=None, k=None, l=None, verbose=False): INPUT: - ``G`` -- group of cardinality ``v`` - - ``D`` -- a set of ``k``-subsets of ``G`` - - ``v``, ``k`` and ``l`` -- optional parameters of the difference family + - ``D`` -- set of ``k``-subsets of ``G`` + - ``v``, ``k``, ``l`` -- (optional) parameters of the difference family - ``verbose`` -- boolean (default: ``False``); whether to print additional information @@ -710,11 +710,9 @@ def one_radical_difference_family(K, k): INPUT: - ``K`` -- a finite field of cardinality `q` - - ``k`` -- a positive integer so that `k(k-1)` divides `q-1` + - ``k`` -- positive integer so that `k(k-1)` divides `q-1` - OUTPUT: - - Either a difference family or ``None`` if it does not exist. + OUTPUT: either a difference family or ``None`` if it does not exist ALGORITHM: @@ -834,7 +832,7 @@ def radical_difference_family(K, k, l=1, existence=False, check=True): - ``K`` -- a finite field - ``k`` -- positive integer; the size of the blocks - - ``l`` -- integer (default: ``1``); the `\lambda` parameter + - ``l`` -- integer (default: `1`); the `\lambda` parameter - ``existence`` -- if ``True``, then return either ``True`` if Sage knows how to build such design, ``Unknown`` if it does not and ``False`` if it knows that the design does not exist @@ -992,7 +990,7 @@ def are_mcfarland_1973_parameters(v, k, lmbda, return_parameters=False): INPUT: - ``v``, ``k``, ``lmbda`` -- integers; parameters of the difference family - - ``return_parameters`` -- boolean (default ``False``); if ``True``, return a + - ``return_parameters`` -- boolean (default: ``False``); if ``True``, return a pair ``(True, (q, s))`` so that ``(q,s)`` can be used in the function :func:`mcfarland_1973_construction` to actually build a ``(v,k,lmbda)``-difference family. Or ``(False, None)`` if the @@ -1143,7 +1141,7 @@ def hadamard_difference_set_product_parameters(N): Check whether a product construction is available for Hadamard difference set with parameter ``N``. - This function looks for two integers `N_1` and `N_2`` greater than `1` + This function looks for two integers `N_1` and `N_2` greater than `1` and so that `N = 2 N_1 N_2` and there exists Hadamard difference set with parameters `(4 N_i^2, 2N_i^2 - N_i, N_i^2 - N_i)`. If such pair exists, the output is the pair ``(N_1, N_2)`` otherwise it is ``None``. @@ -1329,7 +1327,6 @@ def _create_m_sequence(q, n, check=True): Traceback (most recent call last): ... ValueError: q must be a prime power - """ from sage.rings.finite_rings.finite_field_constructor import GF @@ -1475,8 +1472,8 @@ def relative_difference_set_from_homomorphism(q, N, d, check=True, return_group= INPUT: - ``q`` -- a prime power - - ``N`` -- an integer greater than 1 - - ``d`` -- an integer which divides `q-1` + - ``N`` -- integer greater than 1 + - ``d`` -- integer which divides `q-1` - ``check`` -- boolean (default: ``True``); if ``True``, check that the result is a relative difference set before returning it - ``return_group`` -- boolean (default: ``False``); if ``True``, the function @@ -1561,7 +1558,7 @@ def is_relative_difference_set(R, G, H, params, verbose=False): - ``R`` -- list; the relative diffeence set of length `k` - ``G`` -- an additive abelian group of order `mn` - ``H`` -- list; a submodule of ``G`` of order `n` - - ``params`` -- a tuple in the form `(m, n, k, d)` + - ``params`` -- tuple in the form `(m, n, k, d)` - ``verbose`` -- boolean (default: ``False``); if ``True``, the function will be verbose when the sequences do not satisfy the contraints @@ -1638,7 +1635,7 @@ def is_supplementary_difference_set(Ks, v=None, lmbda=None, G=None, verbose=Fals INPUT: - - ``Ks`` -- a list of sets to be checked + - ``Ks`` -- list of sets to be checked - ``v`` -- integer; the parameter `v` of the supplementary difference sets - ``lmbda`` -- integer; the parameter `\lambda` of the supplementary difference sets - ``G`` -- a group of order `v` @@ -1733,9 +1730,9 @@ def supplementary_difference_set_from_rel_diff_set(q, existence=False, check=Tru INPUT: - ``q`` -- an odd prime power - - ``existence`` -- boolean (default: ``False``); If ``True``, only check + - ``existence`` -- boolean (default: ``False``); if ``True``, only check whether the supplementary difference sets can be constructed - - ``check`` -- boolean (default: ``True``); If ``True``, check that the sets + - ``check`` -- boolean (default: ``True``); if ``True``, check that the sets are supplementary difference sets before returning them OUTPUT: @@ -1989,9 +1986,9 @@ def is_fixed_relative_difference_set(R, q): INPUT: - - ``R`` -- a list containing elements of an abelian group; the relative + - ``R`` -- list containing elements of an abelian group; the relative difference set - - ``q`` -- an integer + - ``q`` -- integer EXAMPLES:: @@ -3065,8 +3062,8 @@ def are_complementary_difference_sets(G, A, B, verbose=False): INPUT: - ``G`` -- a group of odd order - - ``A`` -- a set of elements of ``G`` - - ``B`` -- a set of elements of ``G`` + - ``A`` -- set of elements of ``G`` + - ``B`` -- set of elements of ``G`` - ``verbose`` -- boolean (default: ``False``); if ``True`` the function will be verbose when the sets do not satisfy the contraints @@ -3127,7 +3124,7 @@ def complementary_difference_setsI(n, check=True): Construct complementary difference sets in a group of order `n \cong 3 \mod 4`, `n` a prime power. Let `G` be a Galois Field of order `n`, where `n` satisfies the requirements - above. Let `A` be the set of non-zero quadratic elements in `G`, and `B = A`. + above. Let `A` be the set of nonzero quadratic elements in `G`, and `B = A`. Then `A` and `B` are complementary difference sets over a group of order `n`. This construction is described in [Sze1971]_. @@ -3192,11 +3189,11 @@ def complementary_difference_setsII(n, check=True): the corresponding multiplicative group. Then, there are two different constructions, depending on whether `t` is even or odd. - If `t \cong 2 \mod 4`, let `C_0` be the set of non-zero octic residues in `G`, + If `t \cong 2 \mod 4`, let `C_0` be the set of nonzero octic residues in `G`, and let `C_i = \rho^i C_0` for `1 \le i \le 7`. Then, `A = C_0 \cup C_1 \cup C_2 \cup C_3` and `B = C_0 \cup C_1 \cup C_6 \cup C_7`. - If `t` is odd, let `C_0` be the set of non-zero fourth powers in `G`, and let + If `t` is odd, let `C_0` be the set of nonzero fourth powers in `G`, and let `C_i = \rho^i C_0` for `1 \le i \le 3`. Then, `A = C_0 \cup C_1` and `B = C_0 \cup C_3`. @@ -3277,7 +3274,7 @@ def complementary_difference_setsIII(n, check=True): Construct complementary difference sets in a group of order `n = 2m + 1`, where `4m + 3` is a prime power. Consider a finite field `G` of order `n` and let `\rho` be a primite element - of this group. Now let `Q` be the set of non zero quadratic residues in `G`, + of this group. Now let `Q` be the set of nonzero quadratic residues in `G`, and let `A = \{ a | \rho^{2a} - 1 \in Q\}`, `B' = \{ b | -(\rho^{2b} + 1) \in Q\}`. Then `A` and `B = Q \setminus B'` are complementary difference sets over the ring of integers modulo `n`. For more details, see [Sz1969]_. @@ -3457,8 +3454,8 @@ def difference_family(v, k, l=1, existence=False, explain_construction=False, ch See also :wikipedia:`Difference_set`. - If there is no such difference family, an ``EmptySetError`` is raised and - if there is no construction at the moment :class:`NotImplementedError` + If there is no such difference family, an :exc:`EmptySetError` is raised and + if there is no construction at the moment :exc:`NotImplementedError` is raised. INPUT: @@ -3477,7 +3474,7 @@ def difference_family(v, k, l=1, existence=False, explain_construction=False, ch OUTPUT: A pair ``(G,D)`` made of a group `G` and a difference family `D` on that - group. Or, if ``existence=True``` a troolean or if + group. Or, if ``existence=True`` a troolean or if ``explain_construction=True`` a string. EXAMPLES:: diff --git a/src/sage/combinat/designs/difference_matrices.py b/src/sage/combinat/designs/difference_matrices.py index 9be65fb4e65..5cebb84e439 100644 --- a/src/sage/combinat/designs/difference_matrices.py +++ b/src/sage/combinat/designs/difference_matrices.py @@ -123,7 +123,7 @@ def difference_matrix_product(k, M1, G1, lmbda1, M2, G2, lmbda2, check=True): def difference_matrix(g,k,lmbda=1,existence=False,check=True): r""" - Return a `(g,k,\lambda)`-difference matrix + Return a `(g,k,\lambda)`-difference matrix. A matrix `M` is a `(g,k,\lambda)`-difference matrix if it has size `\lambda g\times k`, its entries belong to the group `G` of cardinality `g`, and @@ -132,27 +132,26 @@ def difference_matrix(g,k,lmbda=1,existence=False,check=True): INPUT: - - ``k`` -- (integer) number of columns. If ``k=None`` it is set to the - largest value available. + - ``k`` -- integer; number of columns. If ``k`` is ``None`` it is set to the + largest value available - - ``g`` -- (integer) cardinality of the group `G` + - ``g`` -- integer; cardinality of the group `G` - - ``lmbda`` -- (integer; default: 1) -- number of times each element of `G` - appears as a difference. + - ``lmbda`` -- integer (default: 1); number of times each element of `G` + appears as a difference - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. - - ``existence`` (boolean) -- instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - ``True`` -- meaning that Sage knows how to build the design - ``Unknown`` -- meaning that Sage does not know how to build the - design, but that the design may exist (see :mod:`sage.misc.unknown`). + design, but that the design may exist (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that the design does not exist. + - ``False`` -- meaning that the design does not exist .. NOTE:: diff --git a/src/sage/combinat/designs/evenly_distributed_sets.pyx b/src/sage/combinat/designs/evenly_distributed_sets.pyx index 75704f995c8..744cb4e3513 100644 --- a/src/sage/combinat/designs/evenly_distributed_sets.pyx +++ b/src/sage/combinat/designs/evenly_distributed_sets.pyx @@ -64,14 +64,14 @@ cdef class EvenlyDistributedSetsBacktracker: - ``K`` -- a finite field of cardinality `q` - - ``k`` -- a positive integer such that `k(k-1)` divides `q-1` + - ``k`` -- positive integer such that `k(k-1)` divides `q-1` - - ``up_to_isomorphism`` -- (boolean, default ``True``) whether only consider + - ``up_to_isomorphism`` -- boolean (default: ``True``); whether only consider evenly distributed sets up to automorphisms of the field of the form `x \mapsto ax + b`. If set to ``False`` then the iteration is over all evenly distributed sets that contain ``0`` and ``1``. - - ``check`` -- boolean (default is ``False``). Whether you want to check + - ``check`` -- boolean (default: ``False``); whether you want to check intermediate steps of the iterator. This is mainly intended for debugging purpose. Setting it to ``True`` will considerably slow the iteration. @@ -284,7 +284,7 @@ cdef class EvenlyDistributedSetsBacktracker: - ``B`` -- an evenly distributed set - - ``check`` -- (boolean, default ``True``) whether to check the result + - ``check`` -- boolean (default: ``True``); whether to check the result EXAMPLES:: @@ -410,9 +410,7 @@ cdef class EvenlyDistributedSetsBacktracker: This is an internal function and should only be call by the backtracker implemented in the method `__iter__`. - OUTPUT: - - - ``False`` if ``self.B`` is not minimal + OUTPUT: ``False`` if ``self.B`` is not minimal - the list of evenly distributed sets isomorphic to ``self.B`` given as a list of tuples if ``self.up_to_isom=0`` or list diff --git a/src/sage/combinat/designs/ext_rep.py b/src/sage/combinat/designs/ext_rep.py index a6c5a43db5f..9d04b4f5c66 100644 --- a/src/sage/combinat/designs/ext_rep.py +++ b/src/sage/combinat/designs/ext_rep.py @@ -611,7 +611,7 @@ class XTree: - ``t.attribute`` -- attribute named - ``t.child`` -- first child named - - ``t[i]`` -- i-th child + - ``t[i]`` -- `i`-th child - ``for child in t:`` -- iterate over ``t``'s children - ``len(t)`` -- number of ``t``'s children diff --git a/src/sage/combinat/designs/gen_quadrangles_with_spread.pyx b/src/sage/combinat/designs/gen_quadrangles_with_spread.pyx index 5edc2ff8a57..f5912e83690 100644 --- a/src/sage/combinat/designs/gen_quadrangles_with_spread.pyx +++ b/src/sage/combinat/designs/gen_quadrangles_with_spread.pyx @@ -91,7 +91,6 @@ def generalised_quadrangle_with_spread(const int s, const int t, RuntimeError: Sage can't build a GQ of order (3, 4) with a spread sage: designs.generalised_quadrangle_with_spread(3, 4, existence=True) Unknown - """ from sage.combinat.designs.incidence_structures import IncidenceStructure from sage.misc.unknown import Unknown @@ -187,9 +186,7 @@ def dual_GQ_ovoid(GQ, O): - ``O`` -- iterable; the iterable of blocks we want to compute the dual - OUTPUT: - - A pair ``(D, S)`` where ``D`` is the dual of ``GQ`` and + OUTPUT: a pair ``(D, S)`` where ``D`` is the dual of ``GQ`` and ``S`` is the dual of ``O`` EXAMPLES:: @@ -215,7 +212,6 @@ def dual_GQ_ovoid(GQ, O): (2, 4) sage: is_GQ_with_spread(*t) True - """ from sage.combinat.designs.incidence_structures import IncidenceStructure @@ -248,7 +244,7 @@ def generalised_quadrangle_hermitian_with_ovoid(const int q): A pair ``(D, O)`` where ``D`` is an IncidenceStructure representing the generalised quadrangle and ``O`` is a list of points of ``D`` which - constitute an ovoid of ``D`` + constitute an ovoid of ``D``. EXAMPLES:: diff --git a/src/sage/combinat/designs/group_divisible_designs.py b/src/sage/combinat/designs/group_divisible_designs.py index a583dd2607e..6bff9bffe2e 100644 --- a/src/sage/combinat/designs/group_divisible_designs.py +++ b/src/sage/combinat/designs/group_divisible_designs.py @@ -57,23 +57,22 @@ def group_divisible_design(v, K, G, existence=False, check=False): INPUT: - - ``v`` (integer) + - ``v`` -- integer - - ``K``, ``G`` (sets of integers) + - ``K``, ``G`` -- sets of integers - - ``existence`` (boolean) -- instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - ``True`` -- meaning that Sage knows how to build the design - ``Unknown`` -- meaning that Sage does not know how to build the - design, but that the design may exist (see :mod:`sage.misc.unknown`). + design, but that the design may exist (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that the design does not exist. + - ``False`` -- meaning that the design does not exist - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. .. NOTE:: @@ -139,21 +138,20 @@ def GDD_4_2(q, existence=False, check=True): INPUT: - - ``q`` (integer) + - ``q`` -- integer - - ``existence`` (boolean) -- instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - ``True`` -- meaning that Sage knows how to build the design - ``Unknown`` -- meaning that Sage does not know how to build the - design, but that the design may exist (see :mod:`sage.misc.unknown`). + design, but that the design may exist (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that the design does not exist. + - ``False`` -- meaning that the design does not exist - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -201,7 +199,7 @@ def GDD_4_2(q, existence=False, check=True): class GroupDivisibleDesign(IncidenceStructure): r""" - Group Divisible Design (GDD) + Group Divisible Design (GDD). Let `K` and `G` be sets of positive integers and let `\lambda` be a positive integer. A Group Divisible Design of index `\lambda` and order `v` is a @@ -222,23 +220,23 @@ class GroupDivisibleDesign(IncidenceStructure): INPUT: - ``points`` -- the underlying set. If ``points`` is an integer `v`, then - the set is considered to be `\{0, ..., v-1\}`. + the set is considered to be `\{0, ..., v-1\}` - ``groups`` -- the groups of the design. Set to ``None`` for an automatic - guess (this triggers ``check=True`` and can thus cost some time). + guess (this triggers ``check=True`` and can thus cost some time) - ``blocks`` -- collection of blocks - ``G`` -- list of integers of which the sizes of the groups must be - elements. Set to ``None`` (automatic guess) by default. + elements. Set to ``None`` (automatic guess) by default - ``K`` -- list of integers of which the sizes of the blocks must be - elements. Set to ``None`` (automatic guess) by default. + elements. Set to ``None`` (automatic guess) by default - - ``lambd`` (integer) -- value of `\lambda`, set to `1` by default. + - ``lambd`` -- integer (default: `1`); value of `\lambda` - - ``check`` (boolean) -- whether to check that the design is indeed a `GDD` - with the right parameters. Set to ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that the design is indeed a `GDD` + with the right parameters - ``copy`` -- (use with caution) if set to ``False`` then ``blocks`` must be a list of lists of integers. The list will not be copied but will be @@ -264,7 +262,7 @@ class GroupDivisibleDesign(IncidenceStructure): def __init__(self, points, groups, blocks, G=None, K=None, lambd=1, check=True, copy=True, **kwds): r""" - Constructor function + Constructor function. EXAMPLES:: diff --git a/src/sage/combinat/designs/incidence_structures.py b/src/sage/combinat/designs/incidence_structures.py index 2ae9f79a80f..148cc11fdfa 100644 --- a/src/sage/combinat/designs/incidence_structures.py +++ b/src/sage/combinat/designs/incidence_structures.py @@ -73,12 +73,12 @@ class IncidenceStructure: ['a', 'b', 'c', 'd', 'e'] - ``blocks`` -- (i.e. edges, i.e. sets) the blocks defining the incidence - structure. Can be any iterable. + structure; can be any iterable - - ``incidence_matrix`` -- a binary incidence matrix. Each column represents - a set. + - ``incidence_matrix`` -- a binary incidence matrix; each column represents + a set - - ``name`` (a string, such as "Fano plane"). + - ``name`` -- string (such as "Fano plane") - ``check`` -- whether to check the input @@ -336,11 +336,11 @@ def __ne__(self, other): def __contains__(self, block): r""" - Tests if a block belongs to the incidence structure + Test if a block belongs to the incidence structure. INPUT: - - ``block`` -- a block. + - ``block`` -- a block EXAMPLES:: @@ -422,11 +422,10 @@ def is_isomorphic(self, other, certificate=False): INPUT: - - ``other`` -- an incidence structure. + - ``other`` -- an incidence structure - - ``certificate`` (boolean) -- whether to return an - isomorphism from ``self`` to ``other`` instead of a boolean - answer. + - ``certificate`` -- boolean (default: ``False``); whether to return an + isomorphism from ``self`` to ``other`` instead of a boolean answer EXAMPLES:: @@ -473,7 +472,6 @@ def is_isomorphic(self, other, certificate=False): True sage: IS1._canonical_label is None or IS2._canonical_label is None False - """ if (self.num_points() != other.num_points() or self.num_blocks() != other.num_blocks() or @@ -497,7 +495,7 @@ def is_isomorphic(self, other, certificate=False): def isomorphic_substructures_iterator(self, H2,induced=False): r""" - Iterates over all copies of ``H2`` contained in ``self``. + Iterate over all copies of ``H2`` contained in ``self``. A hypergraph `H_1` contains an isomorphic copy of a hypergraph `H_2` if there exists an injection `f:V(H_2)\mapsto V(H_1)` such that for any set @@ -514,10 +512,10 @@ def isomorphic_substructures_iterator(self, H2,induced=False): INPUT: - - ``H2`` an :class:`IncidenceStructure` object. + - ``H2`` -- an :class:`IncidenceStructure` object - - ``induced`` (boolean) -- whether to require the copies to be - induced. Set to ``False`` by default. + - ``induced`` -- boolean (default: ``False``); whether to require the copies to be + induced EXAMPLES: @@ -570,7 +568,7 @@ def copy(self): EXAMPLES:: - sage: IS = IncidenceStructure([[1,2,3,"e"]],name="Test") + sage: IS = IncidenceStructure([[1,2,3,"e"]], name='Test') sage: IS Incidence structure with 4 points and 1 blocks sage: copy(IS) @@ -600,7 +598,7 @@ def induced_substructure(self, points): INPUT: - - ``points`` -- a set of points. + - ``points`` -- set of points .. NOTE:: @@ -661,13 +659,13 @@ def trace(self, points, min_size=1, multiset=True): INPUT: - - ``points`` -- a set of points. + - ``points`` -- set of points - - ``min_size`` (integer; default 1) -- minimum size of the sets to - keep. By default all empty sets are discarded, i.e. ``min_size=1``. + - ``min_size`` -- integer (default: 1); minimum size of the sets to + keep. By default all empty sets are discarded, i.e. ``min_size=1`` - - ``multiset`` (boolean; default ``True``) -- whether to keep multiple - copies of the same set. + - ``multiset`` -- boolean (default: ``True``); whether to keep multiple + copies of the same set .. NOTE:: @@ -776,7 +774,6 @@ def blocks(self): sage: BD = IncidenceStructure(7,[[0,1,2],[0,3,4],[0,5,6],[1,3,5],[1,4,6],[2,3,6],[2,4,5]]) sage: BD.blocks() [[0, 1, 2], [0, 3, 4], [0, 5, 6], [1, 3, 5], [1, 4, 6], [2, 3, 6], [2, 4, 5]] - """ if self._point_to_index is None: return [b[:] for b in self._blocks] @@ -807,10 +804,10 @@ def degree(self, p=None, subset=False): INPUT: - - ``p`` -- a point (or a set of points) of the incidence structure. + - ``p`` -- a point (or a set of points) of the incidence structure - - ``subset`` (boolean) -- whether to interpret the argument as a set of - point (``subset=True``) or as a point (``subset=False``, default). + - ``subset`` -- boolean (default: ``False``); whether to interpret the + argument as a set of point or as a point (default) EXAMPLES:: @@ -856,7 +853,7 @@ def degrees(self, size=None): INPUT: - - ``size`` (integer) -- return the degree of all subsets of points of + - ``size`` -- integer; return the degree of all subsets of points of cardinality ``size``. When ``size=None``, the function outputs the degree of all points. @@ -866,9 +863,7 @@ def degrees(self, size=None): ``size=1`` it is indexed by tuples of size 1. This is the same information, stored slightly differently. - OUTPUT: - - A dictionary whose values are degrees and keys are either: + OUTPUT: a dictionary whose values are degrees and keys are either: - the points of the incidence structure if ``size=None`` (default) @@ -923,7 +918,7 @@ def is_regular(self, r=None) -> bool | int: INPUT: - - ``r`` (integer) + - ``r`` -- integer OUTPUT: @@ -974,7 +969,7 @@ def is_uniform(self, k=None) -> bool | int: INPUT: - - ``k`` (integer) + - ``k`` -- integer OUTPUT: @@ -1094,7 +1089,7 @@ def intersection_graph(self, sizes=None): INPUT: - - ``sizes`` -- a list/set of integers. For convenience, setting + - ``sizes`` -- list/set of integers; for convenience, setting ``sizes`` to ``5`` has the same effect as ``sizes=[5]``. When set to ``None`` (default), behaves as ``sizes=PositiveIntegers()``. @@ -1157,17 +1152,17 @@ def incidence_matrix(self): def incidence_graph(self,labels=False): r""" - Return the incidence graph of the incidence structure + Return the incidence graph of the incidence structure. A point and a block are adjacent in this graph whenever they are incident. INPUT: - - ``labels`` (boolean) -- whether to return a graph whose vertices are - integers, or labelled elements. + - ``labels`` -- boolean; whether to return a graph whose vertices are + integers, or labelled elements - - ``labels is False`` (default) -- in this case the first vertices + - ``labels is False`` -- default; in this case the first vertices of the graphs are the elements of :meth:`ground_set`, and appear in the same order. Similarly, the following vertices represent the elements of :meth:`blocks`, and appear in the same order. @@ -1257,7 +1252,7 @@ def complement(self,uniform=False): INPUT: - - ``uniform`` (boolean) -- + - ``uniform`` -- boolean - if set to ``False`` (default), returns the incidence structure whose blocks are the complements of all blocks of the incidence structure. @@ -1326,7 +1321,7 @@ def complement(self,uniform=False): def relabel(self, perm=None, inplace=True): r""" - Relabel the ground set + Relabel the ground set. INPUT: @@ -1340,11 +1335,10 @@ def relabel(self, perm=None, inplace=True): ``l[1]``, ... - ``None`` -- the incidence structure is relabeled to be on - `\{0,1,...,n-1\}` in the ordering given by :meth:`ground_set`. - - - ``inplace`` -- If ``True`` then return a relabeled graph and does not - touch ``self`` (default is ``False``). + `\{0,1,...,n-1\}` in the ordering given by :meth:`ground_set` + - ``inplace`` -- boolean (default: ``False``); if ``True`` then return + a relabeled graph and does not touch ``self`` EXAMPLES:: @@ -1417,7 +1411,7 @@ def relabel(self, perm=None, inplace=True): def packing(self, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Return a maximum packing + Return a maximum packing. A maximum packing in a hypergraph is collection of disjoint sets/blocks of maximal cardinality. This problem is NP-complete in general, and in @@ -1428,7 +1422,7 @@ def packing(self, solver=None, verbose=0, *, integrality_tolerance=1e-3): INPUT: - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`solve @@ -1436,7 +1430,7 @@ def packing(self, solver=None, verbose=0, *, integrality_tolerance=1e-3): :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``). Sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- parameter for use with MILP solvers over @@ -1486,12 +1480,12 @@ def is_t_design(self, t=None, v=None, k=None, l=None, return_parameters=False): INPUT: - - ``t``, ``v``, ``k``, ``l`` (integers) -- their value is set to + - ``t``, ``v``, ``k``, ``l`` -- integers; their value is set to ``None`` by default. The function tests whether the design is a `t-(v,k,l)` design using the provided values and guesses the others. Note that ``l`` cannot be specified if ``t`` is not. - - ``return_parameters`` (boolean)-- whether to return the parameters of + - ``return_parameters`` -- boolean; whether to return the parameters of the `t`-design. If set to ``True``, the function returns a pair ``(boolean_answer,(t,v,k,l))``. @@ -1703,10 +1697,10 @@ def is_generalized_quadrangle(self, verbose=False, parameters=False): INPUT: - - ``verbose`` (boolean) -- whether to print an explanation when the - instance is not a generalized quadrangle. + - ``verbose`` -- boolean; whether to print an explanation when the + instance is not a generalized quadrangle - - ``parameters`` (boolean; ``False``) -- if set to ``True``, the + - ``parameters`` -- (boolean; ``False``); if set to ``True``, the function returns a pair ``(s,t)`` instead of ``True`` answers. In this case, `s` and `t` are the integers defined above if they exist (each can be set to ``False`` otherwise). @@ -1777,11 +1771,11 @@ def dual(self, algorithm=None): INPUT: - ``algorithm`` -- whether to use Sage's implementation - (``algorithm=None``, default) or use GAP's (``algorithm="gap"``). + (``algorithm=None``, default) or use GAP's (``algorithm='gap'``) .. NOTE:: - The ``algorithm="gap"`` option requires GAP's Design package + The ``algorithm='gap'`` option requires GAP's Design package (included in the ``gap_packages`` Sage spkg). EXAMPLES: @@ -1798,12 +1792,12 @@ def dual(self, algorithm=None): Incidence structure with 4 points and 3 blocks sage: D.dual() # needs sage.modules Incidence structure with 3 points and 4 blocks - sage: print(D.dual(algorithm="gap")) # optional - gap_package_design + sage: print(D.dual(algorithm='gap')) # optional - gap_package_design Incidence structure with 3 points and 4 blocks sage: blocks = [[0,1,2],[0,3,4],[0,5,6],[1,3,5],[1,4,6],[2,3,6],[2,4,5]] - sage: BD = IncidenceStructure(7, blocks, name="FanoPlane"); BD + sage: BD = IncidenceStructure(7, blocks, name='FanoPlane'); BD Incidence structure with 7 points and 7 blocks - sage: print(BD.dual(algorithm="gap")) # optional - gap_package_design + sage: print(BD.dual(algorithm='gap')) # optional - gap_package_design Incidence structure with 7 points and 7 blocks sage: BD.dual() # needs sage.modules Incidence structure with 7 points and 7 blocks @@ -1879,7 +1873,7 @@ def automorphism_group(self): def is_resolvable(self, certificate=False, solver=None, verbose=0, check=True, *, integrality_tolerance=1e-3): r""" - Test whether the hypergraph is resolvable + Test whether the hypergraph is resolvable. A hypergraph is said to be resolvable if its sets can be partitionned into classes, each of which is a partition of the ground set. @@ -1893,10 +1887,10 @@ def is_resolvable(self, certificate=False, solver=None, verbose=0, check=True, INPUT: - - ``certificate`` (boolean) -- whether to return the classes along with - the binary answer (see examples below). + - ``certificate`` -- boolean; whether to return the classes along with + the binary answer (see examples below) - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1904,17 +1898,15 @@ def is_resolvable(self, certificate=False, solver=None, verbose=0, check=True, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``). Sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - - ``check`` (boolean) -- whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that + output is correct before returning it. As this is expected to be + useless, you may want to disable it whenever you want speed. - ``integrality_tolerance`` -- parameter for use with MILP solvers over - an inexact base ring; see - :meth:`MixedIntegerLinearProgram.get_values`. + an inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` EXAMPLES: @@ -2026,18 +2018,18 @@ def is_resolvable(self, certificate=False, solver=None, verbose=0, check=True, def coloring(self, k=None, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Compute a (weak) `k`-coloring of the hypergraph + Compute a (weak) `k`-coloring of the hypergraph. A weak coloring of a hypergraph `\mathcal H` is an assignment of colors to its vertices such that no set is monochromatic. INPUT: - - ``k`` (integer) -- compute a coloring with `k` colors if an integer is + - ``k`` -- integer; compute a coloring with `k` colors if an integer is provided, otherwise returns an optimal coloring (i.e. with the minimum possible number of colors). - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -2045,15 +2037,14 @@ def coloring(self, k=None, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- non-negative integer (default: ``0``). Set the level + - ``verbose`` -- nonnegative integer (default: `0`); set the level of verbosity you want from the linear program solver. Since the problem is `NP`-complete, its solving may take some time depending on - the graph. A value of 0 means that there will be no message printed by + the graph. A value of `0` means that there will be no message printed by the solver. - ``integrality_tolerance`` -- parameter for use with MILP solvers over - an inexact base ring; see - :meth:`MixedIntegerLinearProgram.get_values`. + an inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` EXAMPLES: @@ -2130,9 +2121,7 @@ def edge_coloring(self): receive different colors. The coloring returned minimizes the number of colors. - OUTPUT: - - A partition of the sets into color classes. + OUTPUT: a partition of the sets into color classes EXAMPLES:: @@ -2150,7 +2139,7 @@ def edge_coloring(self): g = Graph([list(range(self.num_blocks())), lambda x, y: len(blocks_sets[x] & blocks_sets[y])], loops=False) - return [[blocks[i] for i in C] for C in g.coloring(algorithm="MILP")] + return [[blocks[i] for i in C] for C in g.coloring(algorithm='MILP')] def _spring_layout(self): r""" @@ -2204,7 +2193,7 @@ def _spring_layout(self): def _latex_(self): r""" - Return a TikZ representation of the incidence structure + Return a TikZ representation of the incidence structure. EXAMPLES:: @@ -2236,7 +2225,6 @@ def _latex_(self): \draw node...; \draw node...; \end{tikzpicture} - """ from sage.functions.trig import arctan2 diff --git a/src/sage/combinat/designs/latin_squares.py b/src/sage/combinat/designs/latin_squares.py index e05816e8977..c8b61827e90 100644 --- a/src/sage/combinat/designs/latin_squares.py +++ b/src/sage/combinat/designs/latin_squares.py @@ -21,7 +21,7 @@ :meth:`mutually_orthogonal_latin_squares` | Return `k` Mutually Orthogonal `n\times n` Latin Squares. :meth:`are_mutually_orthogonal_latin_squares` | Check that the list ``l`` of matrices in are MOLS. :meth:`latin_square_product` | Return the product of two (or more) latin squares. - :meth:`MOLS_table` | Prints the MOLS table. + :meth:`MOLS_table` | Print the MOLS table. **Table of MOLS** @@ -199,7 +199,7 @@ def are_mutually_orthogonal_latin_squares(l, verbose=False): return False from .designs_pyx import is_orthogonal_array - return is_orthogonal_array(list(zip(*[[x for R in M for x in R] for M in l])),k,n, verbose=verbose, terminology="MOLS") + return is_orthogonal_array(list(zip(*[[x for R in M for x in R] for M in l])),k,n, verbose=verbose, terminology='MOLS') def mutually_orthogonal_latin_squares(k, n, partitions=False, check=True): @@ -211,12 +211,12 @@ def mutually_orthogonal_latin_squares(k, n, partitions=False, check=True): INPUT: - - ``k`` (integer) -- number of MOLS. If ``k=None`` it is set to the largest - value available. + - ``k`` -- integer; number of MOLS. If ``k`` is ``None`` it is set to the largest + value available - - ``n`` (integer) -- size of the latin square. + - ``n`` -- integer; size of the latin square - - ``partitions`` (boolean) -- a Latin Square can be seen as 3 partitions of + - ``partitions`` -- boolean; a Latin Square can be seen as 3 partitions of the `n^2` cells of the array into `n` sets of size `n`, respectively: * The partition of rows @@ -231,10 +231,9 @@ def mutually_orthogonal_latin_squares(k, n, partitions=False, check=True): partitions satisfying this intersection property instead of the `k+2` MOLS (though the data is exactly the same in both cases). - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -299,7 +298,7 @@ def mutually_orthogonal_latin_squares(k, n, partitions=False, check=True): Unknown If you ask for such a MOLS then you will respectively get an informative - ``EmptySetError`` or :class:`NotImplementedError`:: + :exc:`EmptySetError` or :exc:`NotImplementedError`:: sage: designs.mutually_orthogonal_latin_squares(5, 5) Traceback (most recent call last): @@ -425,7 +424,8 @@ def latin_square_product(M, N, *others): INPUT: - An arbitrary number of latin squares (greater than 2). + - ``M``, ``N``, ``*others`` -- an arbitrary number of latin squares + (greater than or equal to 2) EXAMPLES:: @@ -456,20 +456,20 @@ def latin_square_product(M, N, *others): def MOLS_table(start,stop=None,compare=False,width=None): r""" - Prints the MOLS table that Sage can produce. + Print the MOLS table that Sage can produce. INPUT: - - ``start``, ``stop`` (integers) -- print the table of MOLS for value of + - ``start``, ``stop`` -- integers; print the table of MOLS for value of `n` such that ``start<=n`. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` .. SEEALSO:: @@ -1481,11 +1474,11 @@ def OA_relabel(OA, k, n, blocks=tuple(), matrix=None, symbol_list=None): INPUT: - ``OA`` -- an OA, or rather a list of blocks of length `k`, each - of which contains integers from `0` to `n-1`. + of which contains integers from `0` to `n-1` - - ``k``, ``n`` (integers) + - ``k``, ``n`` -- integers - - ``blocks`` (list of blocks) -- relabels the integers of the OA + - ``blocks`` -- list of blocks; relabels the integers of the OA from `[0..n-1]` into `[0..n-1]` in such a way that the `i` blocks from ``block`` are respectively relabeled as ``[n-i,...,n-i]``, ..., ``[n-1,...,n-1]``. Thus, the blocks from @@ -1503,7 +1496,7 @@ def OA_relabel(OA, k, n, blocks=tuple(), matrix=None, symbol_list=None): If set to ``None`` (default) no such relabelling is performed. - - ``symbol_list`` -- a list of the desired symbols for the + - ``symbol_list`` -- list of the desired symbols for the relabelled OA. If this is not ``None``, the same relabelling is done on all blocks such that the index of an element in symbol_list is its preimage in the relabelling map. @@ -1544,7 +1537,6 @@ def OA_relabel(OA, k, n, blocks=tuple(), matrix=None, symbol_list=None): Traceback (most recent call last): ... RuntimeError: Two block have the same coordinate for one of the k dimensions - """ if blocks: l = [] @@ -1571,8 +1563,8 @@ def OA_standard_label(OA): INPUT: - - ``OA`` -- a list of lists with symbols as entries that are not - necessarily integers. + - ``OA`` -- list of lists with symbols as entries that are not + necessarily integers EXAMPLES:: @@ -1584,7 +1576,6 @@ def OA_standard_label(OA): ....: ['b', 'b', 'b', 'b']] sage: OA_standard_label(C) [[0, 0, 0, 1], [0, 0, 1, 0], [0, 1, 0, 0], [1, 0, 0, 0], [1, 1, 1, 1]] - """ symbol_list = sorted({x for l in OA for x in l}) mapping = {symbol: index for index, symbol in enumerate(symbol_list)} @@ -1631,10 +1622,9 @@ def OA_n_times_2_pow_c_from_matrix(k,c,G,A,Y,check=True): - ``Y`` -- a vector with entries in `GF(2^c)` - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. .. NOTE:: @@ -1752,7 +1742,7 @@ def OA_n_times_2_pow_c_from_matrix(k,c,G,A,Y,check=True): def OA_from_quasi_difference_matrix(M,G,add_col=True,fill_hole=True): r""" - Return an Orthogonal Array from a Quasi-Difference matrix + Return an Orthogonal Array from a Quasi-Difference matrix. **Difference Matrices** @@ -1816,10 +1806,10 @@ def OA_from_quasi_difference_matrix(M,G,add_col=True,fill_hole=True): - ``G`` -- a group - - ``add_col`` (boolean) -- whether to add a column to the final OA equal to - `(x_1,\dots,x_g,x_1,\dots,x_g,\dots)` where `G=\{x_1,\dots,x_g\}`. + - ``add_col`` -- boolean; whether to add a column to the final OA equal to + `(x_1,\dots,x_g,x_1,\dots,x_g,\dots)` where `G=\{x_1,\dots,x_g\}` - - ``fill_hole`` (boolean) -- whether to return the incomplete orthogonal + - ``fill_hole`` -- boolean; whether to return the incomplete orthogonal array, or complete it with the `OA(k,u)` (default). When ``fill_hole is None``, no block of the incomplete OA contains more than one value `\geq |G|`. @@ -1872,13 +1862,13 @@ def OA_from_quasi_difference_matrix(M,G,add_col=True,fill_hole=True): def OA_from_Vmt(m,t,V): r""" - Return an Orthogonal Array from a `V(m,t)` + Return an Orthogonal Array from a `V(m,t)`. INPUT: - - ``m``, ``t`` (integers) + - ``m``, ``t`` -- integers - - ``V`` -- the vector `V(m,t)`. + - ``V`` -- the vector `V(m,t)` .. SEEALSO:: @@ -1896,7 +1886,7 @@ def OA_from_Vmt(m,t,V): def QDM_from_Vmt(m,t,V): r""" - Return a QDM from a `V(m,t)` + Return a QDM from a `V(m,t)`. **Definition** @@ -1927,9 +1917,9 @@ def QDM_from_Vmt(m,t,V): INPUT: - - ``m``, ``t`` (integers) + - ``m``, ``t`` -- integers - - ``V`` -- the vector `V(m,t)`. + - ``V`` -- the vector `V(m,t)` .. SEEALSO:: @@ -1960,7 +1950,7 @@ def QDM_from_Vmt(m,t,V): def OA_from_PBD(k,n,PBD, check=True): r""" - Return an `OA(k,n)` from a PBD + Return an `OA(k,n)` from a PBD. **Construction** @@ -1980,9 +1970,9 @@ def OA_from_PBD(k,n,PBD, check=True): INPUT: - - ``k``, ``n`` (integers) + - ``k``, ``n`` -- integers - - ``PBD`` -- a PBD on `0,...,n-1`. + - ``PBD`` -- a PBD on `0, \ldots, n-1` EXAMPLES: @@ -2049,9 +2039,9 @@ def OA_from_wider_OA(OA,k): INPUT: - - ``OA`` -- an orthogonal array. + - ``OA`` -- an orthogonal array - - ``k`` (integer) + - ``k`` -- integer EXAMPLES:: @@ -2059,7 +2049,6 @@ def OA_from_wider_OA(OA,k): sage: OA_from_wider_OA(designs.orthogonal_arrays.build(6,20,2),1)[:5] [(19,), (19,), (19,), (19,), (19,)] sage: _ = designs.orthogonal_arrays.build(5,46) # indirect doctest - """ if len(OA[0]) == k: return OA @@ -2114,8 +2103,8 @@ class OAMainFunctions: 6 If you ask for an orthogonal array that does not exist, then you will - either obtain an ``EmptySetError`` (if it knows that such an orthogonal - array does not exist) or a :class:`NotImplementedError`:: + either obtain an :exc:`EmptySetError` (if it knows that such an orthogonal + array does not exist) or a :exc:`NotImplementedError`:: sage: designs.orthogonal_arrays.build(4,2) Traceback (most recent call last): @@ -2144,11 +2133,11 @@ def __init__(self,*args,**kwds): @staticmethod def explain_construction(k,n,t=2): r""" - Return a string describing how to builds an `OA(k,n)` + Return a string describing how to builds an `OA(k,n)`. INPUT: - - ``k``, ``n``, ``t`` (integers) -- parameters of the orthogonal array. + - ``k``, ``n``, ``t`` -- integers; parameters of the orthogonal array EXAMPLES:: @@ -2162,7 +2151,7 @@ def explain_construction(k,n,t=2): @staticmethod def build(k,n,t=2,resolvable=False): r""" - Return an `OA(k,n)` of strength `t` + Return an `OA(k,n)` of strength `t`. An orthogonal array of parameters `k,n,t` is a matrix with `k` columns filled with integers from `[n]` in such a way that for any @@ -2177,12 +2166,12 @@ def build(k,n,t=2,resolvable=False): INPUT: - - ``k``, ``n``, ``t`` (integers) -- parameters of the orthogonal array. + - ``k``, ``n``, ``t`` -- integers; parameters of the orthogonal array - - ``resolvable`` (boolean) -- set to ``True`` if you want the design to be - resolvable. The `n` classes of the resolvable design are obtained as the - first `n` blocks, then the next `n` blocks, etc ... Set to ``False`` by - default. + - ``resolvable`` -- boolean (default: ``False``); set to ``True`` if + you want the design to be resolvable. The `n` classes of the + resolvable design are obtained as the first `n` blocks, then the next + `n` blocks, etc. EXAMPLES:: @@ -2197,18 +2186,17 @@ def build(k,n,t=2,resolvable=False): [1, 0, 2], [2, 2, 0]] sage: OA_7_50 = designs.orthogonal_arrays.build(7,50) # indirect doctest - """ return orthogonal_array(k,n,t,resolvable=resolvable) @staticmethod def exists(k,n,t=2): r""" - Return the existence status of an `OA(k,n)` + Return the existence status of an `OA(k,n)`. INPUT: - - ``k``, ``n``, ``t`` (integers) -- parameters of the orthogonal array. + - ``k``, ``n``, ``t`` -- integers; parameters of the orthogonal array .. WARNING:: @@ -2237,7 +2225,7 @@ def is_available(k,n,t=2): INPUT: - - ``k``, ``n``, ``t`` (integers) -- parameters of the orthogonal array. + - ``k``, ``n``, ``t`` -- integers; parameters of the orthogonal array .. SEEALSO:: diff --git a/src/sage/combinat/designs/orthogonal_arrays_build_recursive.py b/src/sage/combinat/designs/orthogonal_arrays_build_recursive.py index b828caaaadf..5d71fbb12c8 100644 --- a/src/sage/combinat/designs/orthogonal_arrays_build_recursive.py +++ b/src/sage/combinat/designs/orthogonal_arrays_build_recursive.py @@ -23,10 +23,10 @@ :func:`~sage.combinat.designs.orthogonal_arrays_build_recursive.construction_3_6` | Return a `OA(k,nm+i)`. :func:`~sage.combinat.designs.orthogonal_arrays_build_recursive.construction_q_x` | Return an `OA(k,(q-1)*(q-x)+x+2)` using the `q-x` construction. :func:`OA_and_oval` | Return a `OA(q+1,q)` whose blocks contains `\leq 2` zeroes in the last `q` columns. - :func:`thwart_lemma_3_5` | Returns an `OA(k,nm+a+b+c+d)`. - :func:`thwart_lemma_4_1` | Returns an `OA(k,nm+4(n-2))`. - :func:`three_factor_product` | Returns an `OA(k+1,n_1n_2n_3)`. - :func:`brouwer_separable_design` | Returns a `OA(k,t(q^2+q+1)+x)` using Brouwer's result on separable designs. + :func:`thwart_lemma_3_5` | Return an `OA(k,nm+a+b+c+d)`. + :func:`thwart_lemma_4_1` | Return an `OA(k,nm+4(n-2))`. + :func:`three_factor_product` | Return an `OA(k+1,n_1n_2n_3)`. + :func:`brouwer_separable_design` | Return a `OA(k,t(q^2+q+1)+x)` using Brouwer's result on separable designs. Functions --------- @@ -49,11 +49,11 @@ def construction_3_3(k,n,m,i,explain_construction=False): INPUT: - - ``k``, ``n``, ``m``, ``i`` (integers) such that the following designs are - available: `OA(k,n)`, `OA(k,m)`, `OA(k,m+1)`, `OA(k,r)`. + - ``k``, ``n``, ``m``, ``i`` -- integers such that the following designs are + available: `OA(k,n)`, `OA(k,m)`, `OA(k,m+1)`, `OA(k,r)` - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: @@ -123,8 +123,8 @@ def construction_3_4(k,n,m,r,s,explain_construction=False): `OA(k,m+1)`, `OA(k,m+2)`, `OA(k,s)`. Additionally, it requires either a `OA(k,m+r)` or a `OA(k,m+r+1)`. - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: @@ -190,13 +190,13 @@ def construction_3_5(k,n,m,r,s,t,explain_construction=False): INPUT: - - ``k``, ``n``, ``m`` (integers) + - ``k``, ``n``, ``m`` -- integers - - ``r``, ``s``, ``t`` (integers) -- sizes of the three truncated groups, - such that `r\leq s` and `(q-r-1)(q-s) \geq (q-s-1)*(q-r)`. + - ``r``, ``s``, ``t`` -- integers; sizes of the three truncated groups, + such that `r\leq s` and `(q-r-1)(q-s) \geq (q-s-1)*(q-r)` - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction The following designs must be available : `OA(k,n)`, `OA(k,r)`, `OA(k,s)`, `OA(k,t)`, `OA(k,m+1)`, `OA(k,m+2)`, `OA(k,m+3)`. @@ -220,7 +220,6 @@ def construction_3_5(k,n,m,r,s,t,explain_construction=False): Concerning eight mutually orthogonal latin squares, Vol. 15, n.3, pp. 255-261, Journal of Combinatorial Designs, 2007 - """ from .orthogonal_arrays import wilson_construction, OA_relabel assert r <= s @@ -275,7 +274,7 @@ def construction_3_5(k,n,m,r,s,t,explain_construction=False): def construction_3_6(k,n,m,i,explain_construction=False): r""" - Return a `OA(k,nm+i)` + Return a `OA(k,nm+i)`. This is Wilson's construction with `r` columns of order `1`, in which each block intersects at most two truncated columns. Such a design exists when @@ -283,12 +282,12 @@ def construction_3_6(k,n,m,i,explain_construction=False): INPUT: - - ``k``, ``n``, ``m``, ``i`` (integers) -- `n` must be a prime power. The + - ``k``, ``n``, ``m``, ``i`` -- integers; `n` must be a prime power. The following designs must be available: `OA(k+r,q)`, `OA(k,m)`, `OA(k,m+1)`, - `OA(k,m+2)`. + `OA(k,m+2)` - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction This is construction 3.6 from [AC07]_. @@ -346,7 +345,7 @@ def OA_and_oval(q, *, solver=None, integrality_tolerance=1e-3): - ``q`` -- a prime power - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -355,7 +354,7 @@ def OA_and_oval(q, *, solver=None, integrality_tolerance=1e-3): `. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` .. NOTE:: @@ -366,7 +365,6 @@ def OA_and_oval(q, *, solver=None, integrality_tolerance=1e-3): sage: from sage.combinat.designs.orthogonal_arrays_build_recursive import OA_and_oval sage: _ = OA_and_oval - """ from sage.arith.misc import is_prime_power from sage.combinat.designs.block_design import projective_plane @@ -482,13 +480,12 @@ def construction_q_x(k, q, x, check=True, explain_construction=False): - `OA(k,q)-q.OA(k,1)` - `OA(k,x+2)` - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: @@ -579,7 +576,7 @@ def construction_q_x(k, q, x, check=True, explain_construction=False): def thwart_lemma_3_5(k,n,m,a,b,c,d=0,complement=False,explain_construction=False): r""" - Returns an `OA(k,nm+a+b+c+d)` + Return an `OA(k,nm+a+b+c+d)`. *(When `d=0`)* @@ -637,14 +634,14 @@ def thwart_lemma_3_5(k,n,m,a,b,c,d=0,complement=False,explain_construction=False INPUT: - ``k``, ``n``, ``m``, ``a``, ``b``, ``c``, ``d`` -- integers which must - satisfy the constraints above. In particular, `a+b+c\leq n+1` must hold. + satisfy the constraints above. In particular, `a+b+c\leq n+1` must hold By default, `d=0`. - - ``complement`` (boolean) -- whether to complement the sets, i.e. follow - the `n-a,n-b,n-c` variant described above. + - ``complement`` -- boolean; whether to complement the sets, i.e. follow + the `n-a,n-b,n-c` variant described above - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: @@ -757,7 +754,7 @@ def thwart_lemma_3_5(k,n,m,a,b,c,d=0,complement=False,explain_construction=False def thwart_lemma_4_1(k,n,m,explain_construction=False): r""" - Returns an `OA(k,nm+4(n-2))`. + Return an `OA(k,nm+4(n-2))`. Implements Lemma 4.1 from [Thwarts]_. @@ -777,10 +774,10 @@ def thwart_lemma_4_1(k,n,m,explain_construction=False): INPUT: - - ``k``, ``n``, ``m`` (integers) + - ``k``, ``n``, ``m`` -- integers - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: @@ -885,7 +882,7 @@ def thwart_lemma_4_1(k,n,m,explain_construction=False): def three_factor_product(k,n1,n2,n3,check=False,explain_construction=False): r""" - Returns an `OA(k+1,n_1n_2n_3)` + Return an `OA(k+1,n_1n_2n_3)`. The three factor product construction from [DukesLing14]_ does the following: @@ -949,14 +946,14 @@ def three_factor_product(k,n1,n2,n3,check=False,explain_construction=False): INPUT: - - ``k``, ``n1``, ``n2``, ``n3`` (integers) + - ``k``, ``n1``, ``n2``, ``n3`` -- integers - - ``check`` -- (boolean) Whether to check that everything is going smoothly + - ``check`` -- boolean; whether to check that everything is going smoothly while the design is being built. It is disabled by default, as the constructor of orthogonal arrays checks the final design anyway. - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: @@ -1020,11 +1017,11 @@ def assert_c_partition(classs,k,n,c): def product_with_parallel_classes(OA1,k,g1,g2,g1_parall,parall,check=True): r""" - Returns the product of two OA while keeping track of parallel classes + Return the product of two OA while keeping track of parallel classes. INPUT: - - ``OA1`` (an `OA(k,g_1)` + - ``OA1`` -- (an `OA(k,g_1)` - ``k``, ``g1``, ``g2`` -- integers @@ -1040,7 +1037,7 @@ def product_with_parallel_classes(OA1,k,g1,g2,g1_parall,parall,check=True): Two lists of classes ``g1_parall`` and ``parallel`` which are respectively `g_1`-parallel and parallel classes such that ``g1_parall+parallel`` is an - `OA(k,g1*g2)``. + ``OA(k,g1*g2)``. """ if check: for classs in g1_parall: @@ -1187,7 +1184,7 @@ def _reorder_matrix(matrix): g.add_edges((x,N+i) for i,S in enumerate(matrix) for x in S) matrix = [] for _ in range(k): - matching = g.matching(algorithm="LP") + matching = g.matching(algorithm='LP') col = [0]*N for x,i,_ in matching: if i < N: @@ -1200,7 +1197,7 @@ def _reorder_matrix(matrix): def brouwer_separable_design(k,t,q,x,check=False,verbose=False,explain_construction=False): r""" - Returns a `OA(k,t(q^2+q+1)+x)` using Brouwer's result on separable designs. + Return a `OA(k,t(q^2+q+1)+x)` using Brouwer's result on separable designs. This method is an implementation of Brouwer's construction presented in [Brouwer80]_. It consists in a systematic application of the usual @@ -1323,16 +1320,16 @@ def brouwer_separable_design(k,t,q,x,check=False,verbose=False,explain_construct INPUT: - - ``k``, ``t``, ``q``, ``x`` (integers) + - ``k``, ``t``, ``q``, ``x`` -- integers - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. Set to ``False`` by default. + - ``check`` -- boolean (default: ``False``); whether to check that output + is correct before returning it - - ``verbose`` (boolean) -- whether to print some information on the - construction and parameters being used. + - ``verbose`` -- boolean; whether to print some information on the + construction and parameters being used - - ``explain_construction`` (boolean) -- return a string describing - the construction. + - ``explain_construction`` -- boolean; return a string describing + the construction .. SEEALSO:: diff --git a/src/sage/combinat/designs/orthogonal_arrays_find_recursive.pyx b/src/sage/combinat/designs/orthogonal_arrays_find_recursive.pyx index 5690b681de1..2fa1c414e91 100644 --- a/src/sage/combinat/designs/orthogonal_arrays_find_recursive.pyx +++ b/src/sage/combinat/designs/orthogonal_arrays_find_recursive.pyx @@ -55,7 +55,7 @@ from sage.arith.misc import prime_powers @cached_function def find_recursive_construction(k, n): r""" - Find a recursive construction of an `OA(k,n)` (calls all others ``find_*`` functions) + Find a recursive construction of an `OA(k,n)` (calls all others ``find_*`` functions). This determines whether an `OA(k,n)` can be built through the following constructions: @@ -272,7 +272,7 @@ cpdef find_wilson_decomposition_with_two_truncated_groups(int k,int n): cpdef find_construction_3_3(int k,int n): r""" - Find a decomposition for construction 3.3 from [AC07]_ + Find a decomposition for construction 3.3 from [AC07]_. INPUT: @@ -311,7 +311,7 @@ cpdef find_construction_3_3(int k,int n): cpdef find_construction_3_4(int k,int n): r""" - Find a decomposition for construction 3.4 from [AC07]_ + Find a decomposition for construction 3.4 from [AC07]_. INPUT: @@ -354,7 +354,7 @@ cpdef find_construction_3_4(int k,int n): cpdef find_construction_3_5(int k,int n): r""" - Find a decomposition for construction 3.5 from [AC07]_ + Find a decomposition for construction 3.5 from [AC07]_. INPUT: @@ -404,7 +404,7 @@ cpdef find_construction_3_5(int k,int n): cpdef find_construction_3_6(int k,int n): r""" - Find a decomposition for construction 3.6 from [AC07]_ + Find a decomposition for construction 3.6 from [AC07]_. INPUT: @@ -668,7 +668,7 @@ cpdef find_thwart_lemma_4_1(int k,int n): cpdef find_three_factor_product(int k,int n): r""" - Find `n_1n_2n_3=n` to obtain an `OA(k,n)` by the three-factor product from [DukesLing14]_ + Find `n_1n_2n_3=n` to obtain an `OA(k,n)` by the three-factor product from [DukesLing14]_. INPUT: @@ -818,11 +818,11 @@ def int_as_sum(int value, list S, int k_max): INPUT: - - ``value`` (integer) + - ``value`` -- integer - - ``S`` -- a list of integers + - ``S`` -- list of integers - - ``k_max`` (integer) + - ``k_max`` -- integer EXAMPLES:: diff --git a/src/sage/combinat/designs/resolvable_bibd.py b/src/sage/combinat/designs/resolvable_bibd.py index 55afd031183..27a5bdcae32 100644 --- a/src/sage/combinat/designs/resolvable_bibd.py +++ b/src/sage/combinat/designs/resolvable_bibd.py @@ -65,16 +65,16 @@ def resolvable_balanced_incomplete_block_design(v,k,existence=False): INPUT: - - ``v``, ``k`` (integers) + - ``v``, ``k`` -- integers - - ``existence`` (boolean) -- instead of building the design, return: + - ``existence`` -- boolean; instead of building the design, return: - ``True`` -- meaning that Sage knows how to build the design - ``Unknown`` -- meaning that Sage does not know how to build the - design, but that the design may exist (see :mod:`sage.misc.unknown`). + design, but that the design may exist (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that the design does not exist. + - ``False`` -- meaning that the design does not exist .. SEEALSO:: @@ -150,10 +150,10 @@ def kirkman_triple_system(v,existence=False): INPUT: - - `n` (integer) + - ``n`` -- integer - - ``existence`` (boolean; ``False`` by default) -- whether to build the - `KTS(n)` or only answer whether it exists. + - ``existence`` -- boolean (default: ``False``); whether to build the + `KTS(n)` or only answer whether it exists .. SEEALSO:: @@ -374,10 +374,10 @@ def v_4_1_rbibd(v,existence=False): INPUT: - - `n` (integer) + - ``n`` -- integer - - ``existence`` (boolean; ``False`` by default) -- whether to build the - design or only answer whether it exists. + - ``existence`` -- boolean (default: ``False``); whether to build the + design or only answer whether it exists .. SEEALSO:: @@ -441,7 +441,7 @@ def v_4_1_rbibd(v,existence=False): def PBD_4_7(v,check=True, existence=False): r""" - Return a `(v,\{4,7\})`-PBD + Return a `(v,\{4,7\})`-PBD. For all `v` such that `n\equiv 1\pmod{3}` and `n\neq 10,19, 31` there exists a `(v,\{4,7\})`-PBD. This is proved in Proposition IX.4.5 from [BJL99]_, @@ -704,12 +704,11 @@ def PBD_4_7_from_Y(gdd,check=True): INPUT: - - ``gdd`` -- a `(v,\{4,5,7\},Y)`-GDD where `Y=\NN-\{3,6,10\}`. + - ``gdd`` -- a `(v,\{4,5,7\},Y)`-GDD where `Y=\NN-\{3,6,10\}` - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: diff --git a/src/sage/combinat/designs/steiner_quadruple_systems.py b/src/sage/combinat/designs/steiner_quadruple_systems.py index 7c7819c4138..cf1834e88db 100644 --- a/src/sage/combinat/designs/steiner_quadruple_systems.py +++ b/src/sage/combinat/designs/steiner_quadruple_systems.py @@ -70,7 +70,7 @@ def two_n(B): INPUT: - - ``B`` -- A Steiner Quadruple System on `n` points. + - ``B`` -- a Steiner Quadruple System on `n` points EXAMPLES:: @@ -80,7 +80,6 @@ def two_n(B): ....: sqs = designs.steiner_quadruple_system(n) ....: if not two_n(sqs).is_t_design(3,2*n,4,1): ....: print("Something is wrong !") - """ n = B.num_points() Y = [] @@ -107,7 +106,7 @@ def three_n_minus_two(B): INPUT: - - ``B`` -- A Steiner Quadruple System on `n` points. + - ``B`` -- a Steiner Quadruple System on `n` points EXAMPLES:: @@ -162,7 +161,7 @@ def three_n_minus_eight(B): INPUT: - - ``B`` -- A Steiner Quadruple System on `n` points. + - ``B`` -- a Steiner Quadruple System on `n` points EXAMPLES:: @@ -172,7 +171,6 @@ def three_n_minus_eight(B): ....: sqs = designs.steiner_quadruple_system(n) ....: if not three_n_minus_eight(sqs).is_t_design(3,3*n-8,4,1): ....: print("Something is wrong !") - """ n = B.num_points() @@ -222,8 +220,8 @@ def three_n_minus_four(B): INPUT: - - ``B`` -- A Steiner Quadruple System on `n` points where `n\equiv - 10\pmod{12}`. + - ``B`` -- a Steiner Quadruple System on `n` points where `n\equiv + 10\pmod{12}` EXAMPLES:: @@ -233,7 +231,6 @@ def three_n_minus_four(B): ....: sqs = designs.steiner_quadruple_system(n) ....: if not three_n_minus_four(sqs).is_t_design(3,3*n-4,4,1): ....: print("Something is wrong !") - """ n = B.num_points() @@ -287,7 +284,7 @@ def four_n_minus_six(B): INPUT: - - ``B`` -- A Steiner Quadruple System on `n` points. + - ``B`` -- a Steiner Quadruple System on `n` points EXAMPLES:: @@ -297,7 +294,6 @@ def four_n_minus_six(B): ....: sqs = designs.steiner_quadruple_system(n) ....: if not four_n_minus_six(sqs).is_t_design(3,4*n-6,4,1): ....: print("Something is wrong !") - """ n = B.num_points() f = n-2 @@ -359,7 +355,7 @@ def twelve_n_minus_ten(B): INPUT: - - ``B`` -- A Steiner Quadruple System on `n` points. + - ``B`` -- a Steiner Quadruple System on `n` points EXAMPLES:: @@ -369,7 +365,6 @@ def twelve_n_minus_ten(B): ....: sqs = designs.steiner_quadruple_system(n) ....: if not twelve_n_minus_ten(sqs).is_t_design(3,12*n-10,4,1): ....: print("Something is wrong !") - """ n = B.num_points() B14 = steiner_quadruple_system(14) @@ -453,11 +448,11 @@ def twelve_n_minus_ten(B): def relabel_system(B): r""" - Relabels the set so that `\{n-4, n-3, n-2, n-1\}` is in `B`. + Relabel the set so that `\{n-4, n-3, n-2, n-1\}` is in `B`. INPUT: - - ``B`` -- a list of 4-uples on `0,...,n-1`. + - ``B`` -- list of 4-uples on `0,...,n-1` EXAMPLES:: @@ -489,7 +484,7 @@ def get_label(x): def P(alpha, m): r""" - Return the collection of pairs `P_{\alpha}(m)` + Return the collection of pairs `P_{\alpha}(m)`. For more information on this system, see [Han1960]_. @@ -552,7 +547,7 @@ def _missing_pair(n,l): def barP(eps, m): r""" - Return the collection of pairs `\overline P_{\alpha}(m)` + Return the collection of pairs `\overline P_{\alpha}(m)`. For more information on this system, see [Han1960]_. @@ -567,7 +562,7 @@ def barP(eps, m): @cached_function def barP_system(m): r""" - Return the 1-factorization of `K_{2m}` `\overline P(m)` + Return the 1-factorization of `K_{2m}` `\overline P(m)`. For more information on this system, see [Han1960]_. @@ -683,10 +678,10 @@ def steiner_quadruple_system(n, check=False): INPUT: - - ``n`` -- an integer such that `n\equiv 2,4\pmod 6` + - ``n`` -- integer such that `n\equiv 2,4\pmod 6` - - ``check`` (boolean) -- whether to check that the system is a Steiner - Quadruple System before returning it (`False` by default) + - ``check`` -- boolean (default: ``False``); whether to check that the + system is a Steiner Quadruple System before returning it EXAMPLES:: diff --git a/src/sage/combinat/designs/subhypergraph_search.pyx b/src/sage/combinat/designs/subhypergraph_search.pyx index 968159b9012..b7a71a17b86 100644 --- a/src/sage/combinat/designs/subhypergraph_search.pyx +++ b/src/sage/combinat/designs/subhypergraph_search.pyx @@ -31,20 +31,20 @@ over `|V(H_1)|` points. In particular, two sets of distinct cardinalities require the same memory space. A hypergraph is a C struct with the following fields: -* ``n,m`` (``int``) -- number of points and edges. +* ``n``, ``m`` -- (``int``) number of points and edges -* ``limbs`` (``int``) -- number of 64-bits blocks per set. +* ``limbs`` -- (``int``) number of 64-bits blocks per set -* ``set_space`` (``uint64_t *``) -- address of the memory used to store the - sets. +* ``set_space`` -- (``uint64_t *``) address of the memory used to store the + sets -* ``sets`` (``uint64_t **``) -- ``sets[i]`` points toward the ``limbs`` +* ``sets`` -- (``uint64_t **``) ``sets[i]`` points toward the ``limbs`` blocks encoding set `i`. Note also that ``sets[i][limbs]`` is equal to the cardinality of ``set[i]``, so that ``sets`` has length ``m*(limbs+1)*sizeof(uint64_t)``. -* ``names`` (``int *``) -- associates an integer 'name' to each of the ``n`` - points. +* ``names`` -- (``int *``) associates an integer 'name' to each of the ``n`` + points The operations used on this data structure are: @@ -249,7 +249,7 @@ cdef induced_hypergraph(hypergraph * h, int n, hypergraph * tmp): cdef void trace_hypergraph64(hypergraph * h, int n, hypergraph * tmp) noexcept: r""" - Stores in `tmp` the trace of the sets on {0,...,n-1} in h1. + Store in `tmp` the trace of the sets on `\{0, \ldots, n-1\}` in h1. Note that the size of the sets are kept as they are, i.e. the size of a set stored in tmp is what it was in h. This is useful information we use to cut @@ -426,7 +426,7 @@ cdef class SubHypergraphSearch: def relabel_heuristic(self): r""" - Relabels `H_2` in order to make the algorithm faster. + Relabel `H_2` in order to make the algorithm faster. Objective: we try to pick an ordering `p_1,...,p_k` of the points of `H_2` that maximizes the number of sets involving the first points in @@ -474,7 +474,7 @@ cdef class SubHypergraphSearch: def __iter__(self): r""" - Iterates over all copies of h2 in h1. + Iterate over all copies of h2 in h1. EXAMPLES: diff --git a/src/sage/combinat/designs/twographs.py b/src/sage/combinat/designs/twographs.py index 2bbd4d8d308..281f4fac153 100644 --- a/src/sage/combinat/designs/twographs.py +++ b/src/sage/combinat/designs/twographs.py @@ -36,9 +36,9 @@ :widths: 30, 70 :delim: | - :meth:`~TwoGraph.is_regular_twograph` | tests if ``self`` is a regular two-graph, i.e. a 2-design - :meth:`~TwoGraph.complement` | returns the complement of ``self`` - :meth:`~TwoGraph.descendant` | returns the descendant graph at `w` + :meth:`~TwoGraph.is_regular_twograph` | Test if ``self`` is a regular two-graph, i.e. a 2-design + :meth:`~TwoGraph.complement` | Return the complement of ``self`` + :meth:`~TwoGraph.descendant` | Return the descendant graph at `w` This module's functions are the following: @@ -47,9 +47,9 @@ :widths: 30, 70 :delim: | - :func:`~taylor_twograph` | constructs Taylor's two-graph for `U_3(q)` - :func:`~is_twograph` | checks that the incidence system is a two-graph - :func:`~twograph_descendant` | returns the descendant graph w.r.t. a given vertex of the two-graph of a given graph + :func:`~taylor_twograph` | Construct Taylor's two-graph for `U_3(q)` + :func:`~is_twograph` | Check that the incidence system is a two-graph + :func:`~twograph_descendant` | Return the descendant graph w.r.t. a given vertex of the two-graph of a given graph Methods --------- @@ -68,12 +68,11 @@ class TwoGraph(IncidenceStructure): of size four contains an even number of elements of `T`. For more information, see the documentation of the :mod:`~sage.combinat.designs.twographs` module. - """ def __init__(self, points=None, blocks=None, incidence_matrix=None, name=None, check=False, copy=True): r""" - Constructor of the class + Constructor of the class. TESTS:: @@ -103,8 +102,8 @@ def is_regular_twograph(self, alpha=False): INPUT: - - ``alpha`` -- (default: ``False``) return the value of - ``alpha``, if possible. + - ``alpha`` -- boolean (default: ``False``); return the value of + ``alpha``, if possible EXAMPLES:: @@ -127,7 +126,7 @@ def is_regular_twograph(self, alpha=False): def descendant(self, v): """ - The descendant :class:`graph ` at ``v`` + The descendant :class:`graph ` at ``v``. The :mod:`switching class of graphs ` corresponding to ``self`` contains a graph ``D`` with ``v`` its own connected @@ -150,7 +149,7 @@ def descendant(self, v): def complement(self): """ - The two-graph which is the complement of ``self`` + The two-graph which is the complement of ``self``. That is, the two-graph consisting exactly of triples not in ``self``. Note that this is different from :meth:`complement @@ -175,7 +174,7 @@ def complement(self): def taylor_twograph(q): r""" - constructing Taylor's two-graph for `U_3(q)`, `q` odd prime power + Constructing Taylor's two-graph for `U_3(q)`, `q` odd prime power. The Taylor's two-graph `T` has the `q^3+1` points of the projective plane over `F_{q^2}` singular w.r.t. the non-degenerate Hermitean form `S` preserved by `U_3(q)` as its ground set; @@ -258,7 +257,7 @@ def has_triple(x_y_z): def twograph_descendant(G, v, name=None): r""" - Return the descendant graph w.r.t. vertex `v` of the two-graph of `G` + Return the descendant graph w.r.t. vertex `v` of the two-graph of `G`. In the :mod:`switching class ` of `G`, construct a graph `\Delta` with `v` an isolated vertex, and return the subgraph @@ -272,7 +271,7 @@ def twograph_descendant(G, v, name=None): - ``v`` -- a vertex of ``G`` - - ``name`` -- (default: ``None``); no name, otherwise derive from the construction + - ``name`` -- (default: ``None``) no name, otherwise derive from the construction EXAMPLES: diff --git a/src/sage/combinat/diagram.py b/src/sage/combinat/diagram.py index 61a97249779..f5b8f9ad864 100644 --- a/src/sage/combinat/diagram.py +++ b/src/sage/combinat/diagram.py @@ -481,7 +481,7 @@ def check(self): sage: D = Diagram([(0,0), (0,-3), (2,2), (2,4)]) Traceback (most recent call last): ... - ValueError: diagrams must be indexed by non-negative integers + ValueError: diagrams must be indexed by nonnegative integers The next example fails because one cell is indexed by rational numbers:: @@ -489,12 +489,12 @@ def check(self): sage: D = Diagram([(0,0), (0,3), (2/3,2), (2,4)]) Traceback (most recent call last): ... - ValueError: diagrams must be indexed by non-negative integers + ValueError: diagrams must be indexed by nonnegative integers """ from sage.sets.non_negative_integers import NonNegativeIntegers NN = NonNegativeIntegers() if not all(i in NN for c in self._cells for i in c): - raise ValueError("diagrams must be indexed by non-negative integers") + raise ValueError("diagrams must be indexed by nonnegative integers") def specht_module(self, base_ring=None): r""" @@ -553,7 +553,6 @@ class Diagrams(UniqueRepresentation, Parent): sage: D = Dgms([(0,0), (0,3), (2,2), (2,4)]) sage: D.parent() Combinatorial diagrams - """ def __init__(self, category=None): @@ -891,7 +890,7 @@ def check(self): sage: NorthwestDiagram([(0,1/2)]) Traceback (most recent call last): ... - ValueError: diagrams must be indexed by non-negative integers + ValueError: diagrams must be indexed by nonnegative integers """ from itertools import combinations Diagram.check(self) diff --git a/src/sage/combinat/diagram_algebras.py b/src/sage/combinat/diagram_algebras.py index a31b5817144..364a55c74c9 100644 --- a/src/sage/combinat/diagram_algebras.py +++ b/src/sage/combinat/diagram_algebras.py @@ -116,7 +116,7 @@ def brauer_diagrams(k): INPUT: - - ``k`` -- the order of the Brauer diagrams + - ``k`` -- the order of the Brauer diagrams EXAMPLES:: @@ -449,9 +449,7 @@ def base_diagram(self): r""" Return the underlying implementation of the diagram. - OUTPUT: - - - tuple of tuples of integers + OUTPUT: tuple of tuples of integers EXAMPLES:: @@ -532,7 +530,7 @@ def count_blocks_of_size(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -936,14 +934,14 @@ class options(GlobalOptions): The compact representation ``[A/B;pi]`` of the Brauer algebra diagram (see [GL1996]_) has the following components: - - ``A`` -- is a list of pairs of positive elements (upper row) that - are connected, + - ``A`` -- list of pairs of positive elements (upper row) that + are connected - - ``B`` -- is a list of pairs of negative elements (lower row) that - are connected, and + - ``B`` -- list of pairs of negative elements (lower row) that + are connected - - ``pi`` -- is a permutation that is to be interpreted as the relative - order of the remaining elements in the top row and the bottom row. + - ``pi`` -- a permutation that is to be interpreted as the relative + order of the remaining elements in the top row and the bottom row EXAMPLES:: @@ -965,7 +963,7 @@ class options(GlobalOptions): NAME = 'Brauer diagram' module = 'sage.combinat.diagram_algebras' option_class = 'BrauerDiagram' - display = dict(default="normal", + display = dict(default='normal', description='Specifies how the Brauer diagrams should be printed', values=dict(normal="Using the normal representation", compact="Using the compact representation"), @@ -1021,9 +1019,9 @@ def involution_permutation_triple(self, curt=True): INPUT: - - ``curt`` -- (default: ``True``) if ``True``, then return bijection - on free nodes as a one-line notation (standardized to look like a - permutation), else, return the honest mapping, a list of pairs + - ``curt`` -- boolean (default: ``True``); if ``True``, then return + bijection on free nodes as a one-line notation (standardized to look + like a permutation), else, return the honest mapping, a list of pairs `(i, -j)` describing the bijection on free nodes EXAMPLES:: @@ -1147,7 +1145,7 @@ class AbstractPartitionDiagrams(Parent, UniqueRepresentation): INPUT: - ``order`` -- integer or integer `+ 1/2`; the order of the diagrams - - ``category`` -- (default: ``FiniteEnumeratedSets()``); the category + - ``category`` -- (default: ``FiniteEnumeratedSets()``) the category All concrete classes should implement attributes @@ -1501,7 +1499,6 @@ def __contains__(self, obj): sage: bd = da.BrauerDiagrams(3/2) sage: bd.an_element() in bd True - """ if self.order in ZZ: r = ZZ(self.order) @@ -1589,7 +1586,7 @@ def from_involution_permutation_triple(self, D1_D2_pi): INPUT: - - ``D1_D2_pi`` -- a list or tuple where the first entry is a list of + - ``D1_D2_pi`` -- list or tuple where the first entry is a list of arcs on the top of the diagram, the second entry is a list of arcs on the bottom of the diagram, and the third entry is a permutation on the free nodes. @@ -2286,12 +2283,10 @@ class PartitionAlgebra(DiagramBasis, UnitDiagramMixin): - ``q`` -- the deformation parameter `q` - OPTIONAL ARGUMENTS: - - - ``base_ring`` -- (default ``None``) a ring containing ``q``; if + - ``base_ring`` -- (default: ``None``) a ring containing ``q``; if ``None``, then Sage automatically chooses the parent of ``q`` - - ``prefix`` -- (default ``"P"``) a label for the basis elements + - ``prefix`` -- (default: ``'P'``) a label for the basis elements EXAMPLES: @@ -2516,7 +2511,7 @@ class PartitionAlgebra(DiagramBasis, UnitDiagramMixin): True """ @staticmethod - def __classcall_private__(cls, k, q, base_ring=None, prefix="P"): + def __classcall_private__(cls, k, q, base_ring=None, prefix='P'): r""" Standardize the input by getting the base ring from the parent of the parameter ``q`` if no ``base_ring`` is given. @@ -2751,7 +2746,7 @@ def a(self, i): INPUT: - - ``i`` -- an integer between 1 and `k-1` + - ``i`` -- integer between 1 and `k-1` EXAMPLES:: @@ -2792,7 +2787,7 @@ def e(self, i): INPUT: - - ``i`` -- a half integer between 1/2 and `k-1/2` + - ``i`` -- half integer between `1/2` and `k-1/2` EXAMPLES:: @@ -2851,7 +2846,7 @@ def s(self, i): INPUT: - - ``i`` -- an integer between 1 and `k-1` + - ``i`` -- integer between 1 and `k-1` EXAMPLES:: @@ -2885,7 +2880,7 @@ def sigma(self, i): INPUT: - - ``i`` -- a half integer between 1/2 and `k-1/2` + - ``i`` -- half integer between `1/2` and `k-1/2` .. NOTE:: @@ -2981,7 +2976,7 @@ def jucys_murphy_element(self, i): INPUT: - - ``i`` -- a half integer between 1/2 and `k` + - ``i`` -- half integer between `1/2` and `k` ALGORITHM: @@ -3119,7 +3114,7 @@ def potts_representation(self, y=None): INPUT: - - ``y`` -- (option) an integer between 1 and `d`; ignored + - ``y`` -- (optional) an integer between 1 and `d`; ignored if the order of ``self`` is an integer, otherwise the default is `1` @@ -3203,7 +3198,7 @@ class OrbitBasis(DiagramAlgebra): O_\pi = \sum_{\tau \geq \pi} \mu_{2k}(\pi, \tau) D_\tau. - If `\tau` is a partition of `\ell` blocks and the `i^{th}` block of + If `\tau` is a partition of `\ell` blocks and the `i`-th block of `\tau` is a union of `b_i` blocks of `\pi`, then .. MATH:: @@ -3715,12 +3710,10 @@ class BrauerAlgebra(SubPartitionAlgebra, UnitDiagramMixin): - ``q`` -- the deformation parameter `q` - OPTIONAL ARGUMENTS: - - - ``base_ring`` -- (default ``None``) a ring containing ``q``; if ``None`` + - ``base_ring`` -- (default: ``None``) a ring containing ``q``; if ``None`` then just takes the parent of ``q`` - - ``prefix`` -- (default ``"B"``) a label for the basis elements + - ``prefix`` -- (default: ``'B'``) a label for the basis elements EXAMPLES: @@ -3760,7 +3753,7 @@ class BrauerAlgebra(SubPartitionAlgebra, UnitDiagramMixin): """ @staticmethod - def __classcall_private__(cls, k, q, base_ring=None, prefix="B"): + def __classcall_private__(cls, k, q, base_ring=None, prefix='B'): r""" Standardize the input by getting the base ring from the parent of the parameter ``q`` if no ``base_ring`` is given. @@ -4156,12 +4149,10 @@ class TemperleyLiebAlgebra(SubPartitionAlgebra, UnitDiagramMixin): - ``q`` -- the deformation parameter `q` - OPTIONAL ARGUMENTS: - - - ``base_ring`` -- (default ``None``) a ring containing ``q``; if ``None`` + - ``base_ring`` -- (default: ``None``) a ring containing ``q``; if ``None`` then just takes the parent of ``q`` - - ``prefix`` -- (default ``"T"``) a label for the basis elements + - ``prefix`` -- (default: ``'T'``) a label for the basis elements EXAMPLES: @@ -4245,7 +4236,7 @@ class TemperleyLiebAlgebra(SubPartitionAlgebra, UnitDiagramMixin): 1 7 20 21 13 """ @staticmethod - def __classcall_private__(cls, k, q, base_ring=None, prefix="T"): + def __classcall_private__(cls, k, q, base_ring=None, prefix='T'): r""" Standardize the input by getting the base ring from the parent of the parameter ``q`` if no ``base_ring`` is given. @@ -4523,12 +4514,10 @@ class PlanarAlgebra(SubPartitionAlgebra, UnitDiagramMixin): - ``q`` -- the deformation parameter `q` - OPTIONAL ARGUMENTS: - - - ``base_ring`` -- (default ``None``) a ring containing ``q``; if ``None`` + - ``base_ring`` -- (default: ``None``) a ring containing ``q``; if ``None`` then just takes the parent of ``q`` - - ``prefix`` -- (default ``"Pl"``) a label for the basis elements + - ``prefix`` -- (default: ``'Pl'``) a label for the basis elements EXAMPLES: @@ -4564,7 +4553,7 @@ class PlanarAlgebra(SubPartitionAlgebra, UnitDiagramMixin): True """ @staticmethod - def __classcall_private__(cls, k, q, base_ring=None, prefix="Pl"): + def __classcall_private__(cls, k, q, base_ring=None, prefix='Pl'): r""" Standardize the input by getting the base ring from the parent of the parameter ``q`` if no ``base_ring`` is given. @@ -4653,7 +4642,7 @@ class PropagatingIdeal(SubPartitionAlgebra): True """ @staticmethod - def __classcall_private__(cls, k, q, base_ring=None, prefix="I"): + def __classcall_private__(cls, k, q, base_ring=None, prefix='I'): r""" Standardize the input by getting the base ring from the parent of the parameter ``q`` if no ``base_ring`` is given. @@ -4711,7 +4700,7 @@ def __pow__(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -4736,9 +4725,9 @@ def TL_diagram_ascii_art(diagram, use_unicode=False, blobs=[]): INPUT: - - ``diagram`` -- a list of pairs of matchings of the set + - ``diagram`` -- list of pairs of matchings of the set `\{-1, \ldots, -n, 1, \ldots, n\}` - - ``use_unicode`` -- (default: ``False``): whether or not + - ``use_unicode`` -- boolean (default: ``False``); whether or not to use unicode art instead of ascii art - ``blobs`` -- (optional) a list of matchings with blobs on them @@ -5786,7 +5775,7 @@ def propagating_number(sp): def to_set_partition(l, k=None): r""" - Convert input to a set partition of `\{1, \ldots, k, -1, \ldots, -k\}` + Convert input to a set partition of `\{1, \ldots, k, -1, \ldots, -k\}`. Convert a list of a list of numbers to a set partitions. Each list of numbers in the outer list specifies the numbers contained in one @@ -5798,12 +5787,10 @@ def to_set_partition(l, k=None): INPUT: - - ``l`` -- a list of lists of integers + - ``l`` -- list of lists of integers - ``k`` -- integer (default: ``None``) - OUTPUT: - - - a list of sets + OUTPUT: list of sets EXAMPLES:: diff --git a/src/sage/combinat/dlx.py b/src/sage/combinat/dlx.py index e34cc7cd7a1..383dda056be 100644 --- a/src/sage/combinat/dlx.py +++ b/src/sage/combinat/dlx.py @@ -55,7 +55,7 @@ def __init__(self, ones, initialsolution=None): described by Knuth. Consider a matrix M with entries of 0 and 1, and compute a subset - of the rows of this matrix which sum to the vector of all 1's. + of the rows of this matrix which sum to the vector of all 1s. The dancing links algorithm works particularly well for sparse matrices, so the input is a list of lists of the form: (note the @@ -119,15 +119,12 @@ def __init__(self, ones, initialsolution=None): def __eq__(self, other): r""" - Return ``True`` if every attribute of - ``other`` matches the attribute of - ``self``. + Return ``True`` if every attribute of ``other`` matches the attribute + of ``self``. INPUT: - - - ``other`` -- a DLX matrix - + - ``other`` -- a DLX matrix EXAMPLES:: @@ -192,7 +189,7 @@ def _constructmatrix(self, ones, initialsolution=None): 'initialsolution' is list of row indexes that are required to be part of the solution. They will be removed from the matrix. - .. NOTE: + .. NOTE:: Rows and cols are 1-indexed ; the zero index is reserved for the root node and column heads. diff --git a/src/sage/combinat/dyck_word.py b/src/sage/combinat/dyck_word.py index f144e9c43c6..612ffa33ed6 100644 --- a/src/sage/combinat/dyck_word.py +++ b/src/sage/combinat/dyck_word.py @@ -126,7 +126,7 @@ def replace_parens(x): - If ``x`` is a closing parenthesis, replace ``x`` with the constant ``close_symbol``. - - Raise a :class:`ValueError` if ``x`` is neither an opening nor a + - Raise a :exc:`ValueError` if ``x`` is neither an opening nor a closing parenthesis. .. SEEALSO:: :func:`replace_symbols` @@ -161,7 +161,7 @@ def replace_symbols(x): INPUT: - - ``x`` -- either ``open_symbol`` or ``close_symbol``. + - ``x`` -- either ``open_symbol`` or ``close_symbol`` OUTPUT: @@ -170,7 +170,7 @@ def replace_symbols(x): - If ``x`` is ``close_symbol``, replace ``x`` with ``')'``. - If ``x`` is neither ``open_symbol`` nor ``close_symbol``, a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. .. SEEALSO:: :func:`replace_parens` @@ -363,28 +363,28 @@ def set_latex_options(self, D): The default values are set in the ``__init__`` function. - - ``tikz_scale`` -- (default: 1) scale for use with the tikz package. + - ``tikz_scale`` -- (default: 1) scale for use with the tikz package - - ``diagonal`` -- (default: ``False``) boolean value to draw the - diagonal or not. + - ``diagonal`` -- boolean (default: ``False``); value to draw the + diagonal or not - ``line width`` -- (default: 2*``tikz_scale``) value representing the - line width. + line width - - ``color`` -- (default: black) the line color. + - ``color`` -- (default: black) the line color - - ``bounce path`` -- (default: ``False``) boolean value to indicate - if the bounce path should be drawn. + - ``bounce path`` -- boolean (default: ``False``); value to indicate + if the bounce path should be drawn - - ``peaks`` -- (default: ``False``) boolean value to indicate if the - peaks should be displayed. + - ``peaks`` -- boolean (default: ``False``); value to indicate if the + peaks should be displayed - - ``valleys`` -- (default: ``False``) boolean value to indicate if the - valleys should be displayed. + - ``valleys`` -- boolean (default: ``False``); value to indicate if the + valleys should be displayed INPUT: - - ``D`` -- a dictionary with a list of latex parameters to change + - ``D`` -- dictionary with a list of latex parameters to change EXAMPLES:: @@ -406,24 +406,24 @@ def latex_options(self): The default values are set using the options. - - ``tikz_scale`` -- (default: 1) scale for use with the tikz package. + - ``tikz_scale`` -- (default: 1) scale for use with the tikz package - - ``diagonal`` -- (default: ``False``) boolean value to draw the - diagonal or not. + - ``diagonal`` -- boolean (default: ``False``); value to draw the + diagonal or not - - ``line width`` -- (default: 2*``tikz_scale``) value representing the - line width. + - ``line width`` -- (default: ``2*tikz_scale``) value representing the + line width - - ``color`` -- (default: black) the line color. + - ``color`` -- (default: black) the line color - - ``bounce path`` -- (default: ``False``) boolean value to indicate - if the bounce path should be drawn. + - ``bounce path`` -- boolean (default: ``False``); value to indicate + if the bounce path should be drawn - - ``peaks`` -- (default: ``False``) boolean value to indicate if the - peaks should be displayed. + - ``peaks`` -- boolean (default: ``False``); value to indicate if the + peaks should be displayed - - ``valleys`` -- (default: ``False``) boolean value to indicate if the - valleys should be displayed. + - ``valleys`` -- boolean (default: ``False``); value to indicate if the + valleys should be displayed EXAMPLES:: @@ -616,7 +616,7 @@ def to_path_string(self, unicode=False) -> str: INPUT: - - ``unicode`` -- boolean (default ``False``) whether to use unicode + - ``unicode`` -- boolean (default: ``False``); whether to use unicode EXAMPLES:: @@ -674,11 +674,11 @@ def pretty_print(self, type=None, labelling=None, underpath=True): south-east steps. - ``labelling`` -- (if type is "N-E") a list of labels assigned to - the up steps in ``self``. + the up steps in ``self`` - - ``underpath`` -- (if type is "N-E", default:``True``) If ``True``, + - ``underpath`` -- (if type is "N-E", default:``True``) if ``True``, the labelling is shown under the path; otherwise, it is shown to - the right of the path. + the right of the path EXAMPLES:: @@ -1215,7 +1215,6 @@ def ascent_prime_decomposition(self) -> list[DyckWord]: sage: DyckWord([1,0,1,0]).ascent_prime_decomposition() [[], [1, 0], [], [1, 0], []] - """ n = self.length() H = self.heights() @@ -1287,9 +1286,7 @@ def number_of_initial_rises(self) -> int: r""" Return the length of the initial run of ``self``. - OUTPUT: - - - a non--negative integer indicating the length of the initial rise + OUTPUT: nonnegative integer indicating the length of the initial rise EXAMPLES:: @@ -1497,9 +1494,7 @@ def touch_points(self) -> list[int]: Note that these abscissae are precisely the entries of :meth:`returns_to_zero` divided by `2`. - OUTPUT: - - - a list of integers indicating where the path touches the diagonal + OUTPUT: list of integers indicating where the path touches the diagonal EXAMPLES:: @@ -1521,9 +1516,7 @@ def touch_composition(self): This assumes ``self`` to be a complete Dyck word. - OUTPUT: - - - a composition of length equal to the length of the Dyck word. + OUTPUT: a composition of length equal to the length of the Dyck word EXAMPLES:: @@ -1547,9 +1540,7 @@ def number_of_touch_points(self) -> int: r""" Return the number of touches of ``self`` at the main diagonal. - OUTPUT: - - - a non--negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -1673,7 +1664,7 @@ def to_tamari_sorting_tuple(self) -> list[int]: return resu @combinatorial_map(name="to binary trees: up step, left tree, down step, right tree") - def to_binary_tree(self, usemap="1L0R"): + def to_binary_tree(self, usemap='1L0R'): r""" Return a binary tree recursively constructed from the Dyck path ``self`` by the map ``usemap``. The default ``usemap`` is ``'1L0R'`` @@ -1686,7 +1677,7 @@ def to_binary_tree(self, usemap="1L0R"): INPUT: - - ``usemap`` -- a string, either ``'1L0R'``, ``'1R0L'``, ``'L1R0'``, + - ``usemap`` -- string, either ``'1L0R'``, ``'1R0L'``, ``'L1R0'``, ``'R1L0'`` Other valid ``usemap`` are ``'1R0L'``, ``'L1R0'``, and ``'R1L0'``. @@ -2057,7 +2048,7 @@ def characteristic_symmetric_function(self, q=None, - ``q`` -- (default: ``q = R('q')``) a parameter for the generating function power - - ``R`` -- (default : ``R = QQ['q','t'].fraction_field()``) the base + - ``R`` -- (default: ``R = QQ['q','t'].fraction_field()``) the base ring to do the calculations over OUTPUT: @@ -2324,13 +2315,13 @@ def to_permutation(self, map) -> Permutation: | x . . | . . . - sage: D.to_permutation(map="Bandlow-Killpatrick") + sage: D.to_permutation(map='Bandlow-Killpatrick') [3, 4, 2, 1] - sage: D.to_permutation(map="Stump") + sage: D.to_permutation(map='Stump') [4, 2, 3, 1] - sage: D.to_permutation(map="Knuth") + sage: D.to_permutation(map='Knuth') [1, 2, 4, 3] - sage: D.to_permutation(map="Krattenthaler") + sage: D.to_permutation(map='Krattenthaler') [2, 1, 3, 4] TESTS:: @@ -2737,7 +2728,7 @@ def number_of_tunnels(self, tunnel_type='centered') -> int: INPUT: - ``tunnel_type`` -- (default: ``'centered'``) can be one of the - following: ``'left'``, ``'right'``, ``'centered'``, or ``'all'``. + following: ``'left'``, ``'right'``, ``'centered'``, or ``'all'`` EXAMPLES:: @@ -3021,7 +3012,6 @@ def bounce_path(self) -> DyckWord: [] sage: DyckWord([1,0]).bounce_path() [1, 0] - """ area_seq = self.to_area_sequence() i = len(area_seq) - 1 @@ -3338,7 +3328,7 @@ class options(GlobalOptions): _| x | x . | . . - sage: DyckWords.options(diagram_style="line") + sage: DyckWords.options(diagram_style='line') sage: D /\/\ / \ @@ -3346,18 +3336,18 @@ class options(GlobalOptions): """ NAME = 'DyckWords' module = 'sage.combinat.dyck_word' - display = dict(default="list", + display = dict(default='list', description='Specifies how Dyck words should be printed', values=dict(list='displayed as a list', lattice='displayed on the lattice defined by ``diagram_style``'), case_sensitive=False) - ascii_art = dict(default="path", + ascii_art = dict(default='path', description='Specifies how the ascii art of Dyck words should be printed', values=dict(path="Using the path string", pretty_output="Using pretty printing"), - alias=dict(pretty_print="pretty_output", path_string="path"), + alias=dict(pretty_print='pretty_output', path_string='path'), case_sensitive=False) - diagram_style = dict(default="grid", + diagram_style = dict(default='grid', values=dict(grid='printing as paths on a grid using N and E steps', line='printing as paths on a line using NE and SE steps',), alias={'N-E': 'grid', 'NE-SE': 'line'}, @@ -3372,7 +3362,7 @@ class options(GlobalOptions): description='The default value for the line width as a ' 'multiple of the tikz scale when latexed', checker=lambda x: True) # More trouble than it's worth to check - latex_color = dict(default="black", + latex_color = dict(default='black', description='The default value for the color when latexed', checker=lambda x: isinstance(x, str)) latex_bounce_path = dict(default=False, @@ -3878,8 +3868,8 @@ def from_area_sequence(self, code) -> DyckWord: INPUT: - - ``code`` -- a list of integers satisfying ``code[0] == 0`` - and ``0 <= code[i+1] <= code[i]+1``. + - ``code`` -- list of integers satisfying ``code[0] == 0`` + and ``0 <= code[i+1] <= code[i]+1`` EXAMPLES:: @@ -4130,7 +4120,7 @@ def random_element(self) -> DyckWord: Return a random complete Dyck word of semilength `n`. The algorithm is based on a classical combinatorial fact. One - chooses at random a word with `n` 0's and `n+1` 1's. One then + chooses at random a word with `n` 0s and `n+1` 1s. One then considers every 1 as an ascending step and every 0 as a descending step, and one finds the lowest point of the path (with respect to a slightly tilted slope). One then cuts the diff --git a/src/sage/combinat/e_one_star.py b/src/sage/combinat/e_one_star.py index c0226123521..dd62dc79ae3 100644 --- a/src/sage/combinat/e_one_star.py +++ b/src/sage/combinat/e_one_star.py @@ -248,7 +248,7 @@ class Face(SageObject): - ``v`` -- tuple of integers - ``t`` -- integer in ``[1, ..., len(v)]``, type of the face. The face of type `i` is orthogonal to the canonical vector `e_i`. - - ``color`` -- color (default: ``None``) color of the face, + - ``color`` -- color (default: ``None``); color of the face, used for plotting only. If ``None``, its value is guessed from the face type. @@ -379,7 +379,7 @@ def __hash__(self) -> int: def __add__(self, other): r""" - Addition of self with a Face, a Patch or a finite iterable of faces. + Addition of ``self`` with a Face, a Patch or a finite iterable of faces. INPUT: @@ -450,9 +450,7 @@ def color(self, color=None): the new color to assign to the face. If ``None``, it returns the color of the face. - OUTPUT: - - color or None + OUTPUT: color or None EXAMPLES:: @@ -480,9 +478,7 @@ def _plot(self, projmat, face_contour, opacity) -> Graphics: the contour of unit faces (used only for faces in three dimensions) - ``opacity`` -- the alpha value for the color of the face - OUTPUT: - - 2D graphic object + OUTPUT: 2D graphic object EXAMPLES:: @@ -561,8 +557,8 @@ class Patch(SageObject): INPUT: - ``faces`` -- finite iterable of faces - - ``face_contour`` -- dict (default:``None``) maps the face - type to vectors describing the contour of unit faces. If None, + - ``face_contour`` -- dictionary (default: ``None``); maps the face + type to vectors describing the contour of unit faces. If ``None``, defaults contour are assumed for faces of type 1, 2, 3 or 1, 2, 3. Used in plotting methods only. @@ -701,9 +697,7 @@ def __len__(self) -> int: r""" Return the number of faces contained in the patch. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -719,9 +713,7 @@ def __iter__(self): r""" Return an iterator over the faces of the patch. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -814,7 +806,7 @@ def __repr__(self) -> str: def union(self, other) -> Patch: r""" - Return a Patch consisting of the union of self and other. + Return a Patch consisting of the union of ``self`` and ``other``. INPUT: @@ -836,7 +828,7 @@ def union(self, other) -> Patch: def difference(self, other) -> Patch: r""" - Return the difference of self and other. + Return the difference of ``self`` and ``other``. INPUT: @@ -858,9 +850,9 @@ def difference(self, other) -> Patch: def dimension(self) -> None | int: r""" - Return the dimension of the vectors of the faces of self + Return the dimension of the vectors of the faces of ``self``. - It returns ``None`` if self is the empty patch. + It returns ``None`` if ``self`` is the empty patch. The dimension of a patch is the length of the vectors of the faces in the patch, which is assumed to be the same for every face in the patch. @@ -942,7 +934,7 @@ def faces_of_color(self, color) -> list[Face]: def translate(self, v) -> Patch: r""" - Return a translated copy of self by vector ``v``. + Return a translated copy of ``self`` by vector `v`. INPUT: @@ -967,9 +959,7 @@ def occurrences_of(self, other) -> list: - ``other`` -- a Patch - OUTPUT: - - a list of vectors + OUTPUT: list of vectors EXAMPLES:: @@ -1005,23 +995,23 @@ def occurrences_of(self, other) -> list: def repaint(self, cmap='Set1') -> None: r""" - Repaint all the faces of self from the given color map. + Repaint all the faces of ``self`` from the given color map. - This only changes the colors of the faces of self. + This only changes the colors of the faces of ``self``. INPUT: - - ``cmap`` -- color map (default: ``'Set1'``). It can be one of the - following: + - ``cmap`` -- color map (default: ``'Set1'``). It can be one of the + following: - - string -- A coloring map. For available coloring map names type: + - ``string`` -- a coloring map; for available coloring map names type: ``sorted(colormaps)`` - - list -- a list of colors to assign cyclically to the faces. - A list of a single color colors all the faces with the same color. - - dict -- a dict of face types mapped to colors, to color the - faces according to their type. + - ``list`` -- list of colors to assign cyclically to the faces + A list of a single color colors all the faces with the same color + - ``dict`` -- dictionary of face types mapped to colors, to color the + faces according to their type - ``{}``, the empty dict -- shortcut for - ``{1:'red', 2:'green', 3:'blue'}``. + ``{1:'red', 2:'green', 3:'blue'}`` EXAMPLES: @@ -1089,7 +1079,7 @@ def plot(self, projmat=None, opacity=0.75) -> Graphics: INPUT: - - ``projmat`` -- matrix (default: ``None``) the projection + - ``projmat`` -- matrix (default: ``None``); the projection matrix. Its number of lines must be two. Its number of columns must equal the dimension of the ambient space of the faces. If ``None``, the isometric projection is used by default. @@ -1201,21 +1191,21 @@ def plot_tikz(self, projmat=None, print_tikz_env=True, edgecolor='black', INPUT: - - ``projmat`` -- matrix (default: ``None``) the projection + - ``projmat`` -- matrix (default: ``None``); the projection matrix. Its number of lines must be two. Its number of columns must equal the dimension of the ambient space of the faces. If ``None``, the isometric projection is used by default. - - ``print_tikz_env`` -- bool (default: ``True``) if ``True``, + - ``print_tikz_env`` -- boolean (default: ``True``); if ``True``, the tikzpicture environment are printed - - ``edgecolor`` -- string (default: ``'black'``) either + - ``edgecolor`` -- string (default: ``'black'``); either ``'black'`` or ``'facecolor'`` (color of unit face edges) - ``scale`` -- real number (default: ``0.25``) scaling constant for the whole figure - - ``drawzero`` -- bool (default: ``False``) if ``True``, + - ``drawzero`` -- boolean (default: ``False``); if ``True``, mark the origin by a black dot - - ``extra_code_before`` -- string (default: ``''``) extra code to + - ``extra_code_before`` -- string (default: ``''``); extra code to include in the tikz picture - - ``extra_code_after`` -- string (default: ``''``) extra code to + - ``extra_code_after`` -- string (default: ``''``); extra code to include in the tikz picture EXAMPLES:: @@ -1359,11 +1349,11 @@ class E1Star(SageObject): INPUT: - ``sigma`` -- unimodular ``WordMorphism``, i.e. such that its incidence - matrix has determinant `\pm 1`. + matrix has determinant `\pm 1` - - ``method`` -- 'prefix' or 'suffix' (default: 'suffix') - Enables to use an alternative definition `E_1^*(\sigma)` substitutions, - where the abelianized of the prefix` is used instead of the suffix. + - ``method`` -- 'prefix' or 'suffix' (default: ``'suffix'``); + enables to use an alternative definition `E_1^*(\sigma)` substitutions, + where the abelianized of the prefix` is used instead of the suffix .. NOTE:: @@ -1478,11 +1468,9 @@ def __call__(self, patch, iterations=1) -> Patch: INPUT: - ``patch`` -- a patch - - ``iterations`` -- integer (default: 1) number of iterations + - ``iterations`` -- integer (default: 1); number of iterations - OUTPUT: - - a patch + OUTPUT: a patch EXAMPLES:: @@ -1529,9 +1517,7 @@ def __mul__(self, other) -> E1Star: - ``other`` -- an instance of E1Star - OUTPUT: - - an instance of E1Star + OUTPUT: an instance of E1Star EXAMPLES:: @@ -1568,12 +1554,9 @@ def _call_on_face(self, face, color=None): INPUT: - ``face`` -- a face - - ``color`` -- string, RGB tuple or color, (default: None) - RGB color + - ``color`` -- string (default: ``None``); RGB tuple or color - OUTPUT: - - iterator of faces + OUTPUT: iterator of faces EXAMPLES:: @@ -1621,7 +1604,6 @@ def inverse_matrix(self): [ 0 1 0] [ 0 0 1] [ 1 -1 -1] - """ return self.matrix().inverse() diff --git a/src/sage/combinat/enumeration_mod_permgroup.pyx b/src/sage/combinat/enumeration_mod_permgroup.pyx index 70b05c6276b..b2f713228ed 100644 --- a/src/sage/combinat/enumeration_mod_permgroup.pyx +++ b/src/sage/combinat/enumeration_mod_permgroup.pyx @@ -15,12 +15,12 @@ from sage.groups.perm_gps.permgroup_element cimport PermutationGroupElement cpdef list all_children(ClonableIntArray v, int max_part): r""" - Returns all the children of an integer vector (:class:`~sage.structure.list_clone.ClonableIntArray`) + Return all the children of an integer vector (:class:`~sage.structure.list_clone.ClonableIntArray`) ``v`` in the tree of enumeration by lexicographic order. The children of an integer vector ``v`` whose entries have the sum `n` are all integer vectors of sum `n+1` which follow ``v`` in the lexicographic order. - That means this function adds `1` on the last non zero entries and the + That means this function adds `1` on the last nonzero entries and the following ones. For an integer vector `v` such that .. MATH:: @@ -92,7 +92,8 @@ cpdef int lex_cmp(ClonableIntArray v1, ClonableIntArray v2) noexcept: INPUT: - Two instances `v_1, v_2` of :class:`~sage.structure.list_clone.ClonableIntArray` + - ``v1``, ``v2`` -- two instances of + :class:`~sage.structure.list_clone.ClonableIntArray` OUTPUT: @@ -118,7 +119,6 @@ cpdef int lex_cmp(ClonableIntArray v1, ClonableIntArray v2) noexcept: -1 sage: lex_cmp(v3, v1) 1 - """ cdef int i cdef int step = min(v1._len,v2._len) @@ -139,7 +139,7 @@ cpdef int lex_cmp(ClonableIntArray v1, ClonableIntArray v2) noexcept: cpdef bint is_canonical(list sgs, ClonableIntArray v) except -1: r""" - Returns ``True`` if the integer vector `v` is maximal with respect to + Return ``True`` if the integer vector `v` is maximal with respect to the lexicographic order in its orbit under the action of the permutation group whose strong generating system is ``sgs``. Such vectors are said to be canonical. @@ -186,7 +186,7 @@ cpdef bint is_canonical(list sgs, ClonableIntArray v) except -1: cpdef ClonableIntArray canonical_representative_of_orbit_of(list sgs, ClonableIntArray v): r""" - Returns the maximal vector for the lexicographic order living in + Return the maximal vector for the lexicographic order living in the orbit of `v` under the action of the permutation group whose strong generating system is ``sgs``. The maximal vector is also called "canonical". Hence, this method returns the canonical @@ -232,7 +232,7 @@ cpdef ClonableIntArray canonical_representative_of_orbit_of(list sgs, ClonableIn cpdef list canonical_children(list sgs, ClonableIntArray v, int max_part): r""" - Returns the canonical children of the integer vector ``v``. This + Return the canonical children of the integer vector ``v``. This function computes all children of the integer vector ``v`` via the function :func:`all_children` and returns from this list only these which are canonicals identified via the function @@ -253,7 +253,7 @@ cpdef list canonical_children(list sgs, ClonableIntArray v, int max_part): cpdef set orbit(list sgs, ClonableIntArray v): r""" - Returns the orbit of the integer vector ``v`` under the action of the + Return the orbit of the integer vector ``v`` under the action of the permutation group whose strong generating system is ``sgs``. NOTE: diff --git a/src/sage/combinat/expnums.pyx b/src/sage/combinat/expnums.pyx index 897a1bd7870..d0e169189ba 100644 --- a/src/sage/combinat/expnums.pyx +++ b/src/sage/combinat/expnums.pyx @@ -7,9 +7,7 @@ AUTHORS: """ from cysignals.memory cimport check_allocarray, sig_free - from sage.libs.gmp.mpz cimport * - from sage.rings.integer cimport Integer @@ -20,13 +18,11 @@ def expnums(int n, int aa): INPUT: + - ``n`` -- C machine int - - ``n`` -- C machine int - - - ``aa`` -- C machine int - + - ``aa`` -- C machine int - OUTPUT: A list of length `n`. + OUTPUT: list of length `n` ALGORITHM: We use the same integer addition algorithm as GAP. This is an extension of Bell's triangle to the general case of diff --git a/src/sage/combinat/fast_vector_partitions.pyx b/src/sage/combinat/fast_vector_partitions.pyx index 4d00d062d96..e9a103f862b 100644 --- a/src/sage/combinat/fast_vector_partitions.pyx +++ b/src/sage/combinat/fast_vector_partitions.pyx @@ -37,7 +37,7 @@ cdef list vector_halve(list v): INPUT: - - ``v`` -- list of non-negative integers, understood as a vector + - ``v`` -- list of nonnegative integers, understood as a vector OUTPUT: @@ -82,11 +82,11 @@ def recursive_within_from_to(list m, list s, list e, bint useS, bint useE): INPUT: - - ``m`` -- list of non-negative integers, understood as a vector - - ``s`` -- list of non-negative integers, understood as a vector - - ``e`` -- list of non-negative integers, understood as a vector - - ``useS`` -- boolean - - ``useE`` -- boolean + - ``m`` -- list of nonnegative integers, understood as a vector + - ``s`` -- list of nonnegative integers, understood as a vector + - ``e`` -- list of nonnegative integers, understood as a vector + - ``useS`` -- boolean + - ``useE`` -- boolean EXAMPLES:: @@ -148,9 +148,9 @@ def within_from_to(list m, list s, list e): INPUT: - - ``m`` -- list of non-negative integers, understood as a vector - - ``s`` -- list of non-negative integers, understood as a vector - - ``e`` -- list of non-negative integers, understood as a vector + - ``m`` -- list of nonnegative integers, understood as a vector + - ``s`` -- list of nonnegative integers, understood as a vector + - ``e`` -- list of nonnegative integers, understood as a vector EXAMPLES:: @@ -253,8 +253,8 @@ def recursive_vector_partitions(list v, list vL): INPUT: - - ``v`` -- list of non-negative integers, understood as a vector - - ``vL`` -- list of non-negative integers, understood as a vector + - ``v`` -- list of nonnegative integers, understood as a vector + - ``vL`` -- list of nonnegative integers, understood as a vector EXAMPLES:: @@ -284,15 +284,13 @@ def fast_vector_partitions(v, min_vals=None): INPUT: - - ``v`` -- list of non-negative integers, understood as the vector + - ``v`` -- list of nonnegative integers, understood as the vector to be partitioned - - ``min_vals`` -- optional list of non-negative integers, of same + - ``min_vals`` -- (optional) list of nonnegative integers, of same length as ``v`` - OUTPUT: - - A list of lists, each representing a vector partition of ``v``. + OUTPUT: list of lists, each representing a vector partition of ``v`` If ``min_vals`` is given, only partitions with parts ``p >= min_vals`` in the lexicographic ordering will appear. diff --git a/src/sage/combinat/finite_state_machine.py b/src/sage/combinat/finite_state_machine.py index 480c4b4f890..96d35859873 100644 --- a/src/sage/combinat/finite_state_machine.py +++ b/src/sage/combinat/finite_state_machine.py @@ -61,10 +61,10 @@ :widths: 30, 70 :delim: | - :meth:`~FiniteStateMachine.empty_copy` | Returns an empty deep copy - :meth:`~FiniteStateMachine.deepcopy` | Returns a deep copy - :meth:`~FiniteStateMachine.relabeled` | Returns a relabeled deep copy - :meth:`Automaton.with_output` | Extends an automaton to a transducer + :meth:`~FiniteStateMachine.empty_copy` | Return an empty deep copy + :meth:`~FiniteStateMachine.deepcopy` | Return a deep copy + :meth:`~FiniteStateMachine.relabeled` | Return a relabeled deep copy + :meth:`Automaton.with_output` | Extend an automaton to a transducer Manipulation @@ -101,18 +101,18 @@ :widths: 30, 70 :delim: | - :meth:`~FiniteStateMachine.has_state` | Checks for a state - :meth:`~FiniteStateMachine.has_initial_state` | Checks for an initial state - :meth:`~FiniteStateMachine.has_initial_states` | Checks for initial states - :meth:`~FiniteStateMachine.has_final_state` | Checks for a final state - :meth:`~FiniteStateMachine.has_final_states` | Checks for final states - :meth:`~FiniteStateMachine.has_transition` | Checks for a transition - :meth:`~FiniteStateMachine.is_deterministic` | Checks for a deterministic machine - :meth:`~FiniteStateMachine.is_complete` | Checks for a complete machine - :meth:`~FiniteStateMachine.is_connected` | Checks for a connected machine - :meth:`Automaton.is_equivalent` | Checks for equivalent automata - :meth:`~FiniteStateMachine.is_Markov_chain` | Checks for a Markov chain - :meth:`~FiniteStateMachine.is_monochromatic` | Checks whether the colors of all states are equal + :meth:`~FiniteStateMachine.has_state` | Check for a state + :meth:`~FiniteStateMachine.has_initial_state` | Check for an initial state + :meth:`~FiniteStateMachine.has_initial_states` | Check for initial states + :meth:`~FiniteStateMachine.has_final_state` | Check for a final state + :meth:`~FiniteStateMachine.has_final_states` | Check for final states + :meth:`~FiniteStateMachine.has_transition` | Check for a transition + :meth:`~FiniteStateMachine.is_deterministic` | Check for a deterministic machine + :meth:`~FiniteStateMachine.is_complete` | Check for a complete machine + :meth:`~FiniteStateMachine.is_connected` | Check for a connected machine + :meth:`Automaton.is_equivalent` | Check for equivalent automata + :meth:`~FiniteStateMachine.is_Markov_chain` | Check for a Markov chain + :meth:`~FiniteStateMachine.is_monochromatic` | Check whether the colors of all states are equal :meth:`~FiniteStateMachine.number_of_words` | Determine the number of successful paths :meth:`~FiniteStateMachine.asymptotic_moments` | Main terms of expectation and variance of sums of labels :meth:`~FiniteStateMachine.moments_waiting_time` | Moments of the waiting time for first true output @@ -211,12 +211,12 @@ :delim: | :attr:`~FSMState.final_word_out` | Final output of a state - :attr:`~FSMState.is_final` | Describes whether a state is final or not - :attr:`~FSMState.is_initial` | Describes whether a state is initial or not + :attr:`~FSMState.is_final` | Describe whether a state is final or not + :attr:`~FSMState.is_initial` | Describe whether a state is initial or not :attr:`~FSMState.initial_probability` | Probability of starting in this state as part of a Markov chain :meth:`~FSMState.label` | Label of a state - :meth:`~FSMState.relabeled` | Returns a relabeled deep copy of a state - :meth:`~FSMState.fully_equal` | Checks whether two states are fully equal (including all attributes) + :meth:`~FSMState.relabeled` | Return a relabeled deep copy of a state + :meth:`~FSMState.fully_equal` | Check whether two states are fully equal (including all attributes) :class:`FSMTransition` @@ -231,7 +231,7 @@ :attr:`~FSMTransition.to_state` | State in which transition ends :attr:`~FSMTransition.word_in` | Input word of the transition :attr:`~FSMTransition.word_out` | Output word of the transition - :meth:`~FSMTransition.deepcopy` | Returns a deep copy of the transition + :meth:`~FSMTransition.deepcopy` | Return a deep copy of the transition :class:`FSMProcessIterator` @@ -242,9 +242,9 @@ :widths: 30, 70 :delim: | - :meth:`~FSMProcessIterator.next` | Makes one step in processing the input tape - :meth:`~FSMProcessIterator.preview_word` | Reads a word from the input tape - :meth:`~FSMProcessIterator.result` | Returns the finished branches during process + :meth:`~FSMProcessIterator.next` | Make one step in processing the input tape + :meth:`~FSMProcessIterator.preview_word` | Read a word from the input tape + :meth:`~FSMProcessIterator.result` | Return the finished branches during process Helper Functions @@ -255,14 +255,14 @@ :widths: 30, 70 :delim: | - :func:`equal` | Checks whether all elements of ``iterator`` are equal + :func:`equal` | Check whether all elements of ``iterator`` are equal :func:`full_group_by` | Group iterable by values of some key :func:`startswith` | Determine whether list starts with the given prefix - :func:`FSMLetterSymbol` | Returns a string associated to the input letter - :func:`FSMWordSymbol` | Returns a string associated to a word - :func:`is_FSMState` | Tests whether an object inherits from :class:`FSMState` - :func:`is_FSMTransition` | Tests whether an object inherits from :class:`FSMTransition` - :func:`is_FiniteStateMachine` | Tests whether an object inherits from :class:`FiniteStateMachine` + :func:`FSMLetterSymbol` | Return a string associated to the input letter + :func:`FSMWordSymbol` | Return a string associated to a word + :func:`is_FSMState` | Test whether an object inherits from :class:`FSMState` + :func:`is_FSMTransition` | Test whether an object inherits from :class:`FSMTransition` + :func:`is_FiniteStateMachine` | Test whether an object inherits from :class:`FiniteStateMachine` :func:`duplicate_transition_ignore` | Default function for handling duplicate transitions :func:`duplicate_transition_raise_error` | Raise error when inserting a duplicate transition :func:`duplicate_transition_add_input` | Add input when inserting a duplicate transition @@ -343,7 +343,7 @@ --------------------------------------- We want to build an automaton which recognizes non-adjacent forms -(NAFs), i.e., sequences which have no adjacent non-zeros. +(NAFs), i.e., sequences which have no adjacent nonzeros. We use `0`, `1`, and `-1` as digits:: sage: NAF = Automaton( @@ -591,7 +591,7 @@ ... ValueError: Invalid input sequence. -The raised :class:`ValueError` means `13` is not divisible by `3`. +The raised :exc:`ValueError` means `13` is not divisible by `3`. .. _finite_state_machine_gray_code_example: @@ -730,7 +730,7 @@ True Finally, we check that this indeed computes the Gray code of the first -10 non-negative integers. +10 nonnegative integers. :: @@ -1023,15 +1023,13 @@ def full_group_by(l, key=None): def equal(iterator): """ - Checks whether all elements of ``iterator`` are equal. + Check whether all elements of ``iterator`` are equal. INPUT: - ``iterator`` -- an iterator of the elements to check - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean This implements ``_. @@ -1073,9 +1071,7 @@ def startswith(list_, prefix): - ``list_`` -- list - ``prefix`` -- list representing the prefix - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean Similar to :meth:`str.startswith`. @@ -1112,7 +1108,7 @@ def FSMLetterSymbol(letter): INPUT: - ``letter`` -- the input letter or ``None`` (representing the - empty word). + empty word) OUTPUT: @@ -1138,11 +1134,9 @@ def FSMWordSymbol(word): INPUT: - - ``word`` -- the input word. - - OUTPUT: + - ``word`` -- the input word - A string of ``word``. + OUTPUT: string of ``word`` EXAMPLES:: @@ -1162,7 +1156,7 @@ def FSMWordSymbol(word): def is_FSMState(S): """ - Tests whether or not ``S`` inherits from :class:`FSMState`. + Test whether or not ``S`` inherits from :class:`FSMState`. TESTS:: @@ -1184,10 +1178,10 @@ class FSMState(SageObject): INPUT: - - ``label`` -- the label of the state. + - ``label`` -- the label of the state - ``word_out`` -- (default: ``None``) a word that is written when - the state is reached. + the state is reached - ``is_initial`` -- (default: ``False``) @@ -1197,10 +1191,10 @@ class FSMState(SageObject): the state is reached as the last state of some input; only for final states. - - ``initial_probability`` -- (default: ``None``) The probability of - starting in this state if it is a state of a Markov chain. + - ``initial_probability`` -- (default: ``None``) the probability of + starting in this state if it is a state of a Markov chain - - ``hook`` -- (default: ``None``) A function which is called when + - ``hook`` -- (default: ``None``) a function which is called when the state is reached during processing input. It takes two input parameters: the first is the current state (to allow using the same hook for several states), the second is the current process @@ -1212,20 +1206,18 @@ class FSMState(SageObject): processing of a finite state machine the input immediately. See also the example below. - - ``color`` -- (default: ``None``) In order to distinguish states, + - ``color`` -- (default: ``None``) in order to distinguish states, they can be given an arbitrary "color" (an arbitrary object). This is used in :meth:`FiniteStateMachine.equivalence_classes`: states of different colors are never considered to be equivalent. Note that :meth:`Automaton.determinisation` requires that ``color`` is hashable. - - ``allow_label_None`` -- (default: ``False``) If ``True`` allows also - ``None`` as label. Note that a state with label ``None`` is used in + - ``allow_label_None`` -- boolean (default: ``False``); if ``True`` allows + also ``None`` as label. Note that a state with label ``None`` is used in :class:`FSMProcessIterator`. - OUTPUT: - - A state of a finite state machine. + OUTPUT: a state of a finite state machine EXAMPLES:: @@ -1437,11 +1429,9 @@ def __lt__(self, other): INPUT: - - `other` -- a state. + - ``other`` -- a state - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -1493,15 +1483,13 @@ def final_word_out(self): @final_word_out.setter def final_word_out(self, final_word_out): """ - Sets the value of the final output word of a final state. + Set the value of the final output word of a final state. INPUT: - - ``final_word_out`` -- a list, any element or ``None``. - - OUTPUT: + - ``final_word_out`` -- list; any element or ``None`` - Nothing. + OUTPUT: nothing TESTS:: @@ -1550,7 +1538,7 @@ def final_word_out(self, final_word_out): @property def is_final(self): """ - Describes whether the state is final or not. + Describe whether the state is final or not. ``True`` if the state is final and ``False`` otherwise. @@ -1576,16 +1564,14 @@ def is_final(self): @is_final.setter def is_final(self, is_final): """ - Defines the state as a final state or a non-final state. + Define the state as a final state or a non-final state. INPUT: - ``is_final`` -- ``True`` if the state should be final and - ``False`` otherwise. - - OUTPUT: + ``False`` otherwise - Nothing. + OUTPUT: nothing TESTS:: @@ -1644,14 +1630,6 @@ def label(self): """ Return the label of the state. - INPUT: - - Nothing. - - OUTPUT: - - The label of the state. - EXAMPLES:: sage: from sage.combinat.finite_state_machine import FSMState @@ -1665,13 +1643,7 @@ def __copy__(self): """ Return a (shallow) copy of the state. - INPUT: - - Nothing. - - OUTPUT: - - A new state. + OUTPUT: a new state EXAMPLES:: @@ -1715,11 +1687,9 @@ def __deepcopy__(self, memo): INPUT: - - ``memo`` -- a dictionary storing already processed elements. + - ``memo`` -- dictionary storing already processed elements - OUTPUT: - - A new state. + OUTPUT: a new state EXAMPLES:: @@ -1748,11 +1718,9 @@ def deepcopy(self, memo=None): INPUT: - ``memo`` -- (default: ``None``) a dictionary storing already - processed elements. + processed elements - OUTPUT: - - A new state. + OUTPUT: a new state EXAMPLES:: @@ -1790,14 +1758,12 @@ def relabeled(self, label, memo=None): INPUT: - - ``label`` -- the label of new state. + - ``label`` -- the label of new state - ``memo`` -- (default: ``None``) a dictionary storing already - processed elements. - - OUTPUT: + processed elements - A new state. + OUTPUT: a new state EXAMPLES:: @@ -1815,13 +1781,7 @@ def __getstate__(self): """ Return state for pickling excluding outgoing transitions. - INPUT: - - None - - OUTPUT: - - A dictionary. + OUTPUT: a dictionary Outgoing transitions are in fact stored in states, but must be pickled by the finite state machine @@ -1862,9 +1822,7 @@ def __hash__(self): """ Return a hash value for the object. - OUTPUT: - - The hash of this state. + OUTPUT: the hash of this state TESTS:: @@ -1879,13 +1837,7 @@ def _repr_(self): """ Return the string "label". - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -1902,13 +1854,11 @@ def __eq__(self, other): INPUT: - - ``self`` -- a state. - - - ``other`` -- a state. + - ``self`` -- a state - OUTPUT: + - ``other`` -- a state - ``True`` or ``False``. + OUTPUT: boolean Note that the hooks and whether the states are initial or final are not checked. To fully compare two states (including @@ -1934,17 +1884,15 @@ def __eq__(self, other): def __ne__(self, other): """ - Tests for inequality, complement of __eq__. + Test for inequality, complement of __eq__. INPUT: - - ``self`` -- a state. - - - ``other`` -- a state. + - ``self`` -- a state - OUTPUT: + - ``other`` -- a state - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -1963,16 +1911,14 @@ def fully_equal(self, other, compare_color=True): INPUT: - - ``self`` -- a state. + - ``self`` -- a state - - ``other`` -- a state. + - ``other`` -- a state - - ``compare_color`` -- If ``True`` (default) colors are - compared as well, otherwise not. + - ``compare_color`` -- boolean (default: ``True``); if ``True`` colors + are compared as well, otherwise not - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean Note that usual comparison by ``==`` does only compare the labels. @@ -2021,11 +1967,9 @@ def _epsilon_successors_(self, fsm=None): INPUT: - ``fsm`` -- the finite state machine to which ``self`` - belongs. + belongs - OUTPUT: - - A dictionary mapping states to a list of output words. + OUTPUT: a dictionary mapping states to a list of output words The states in the output are the epsilon successors of ``self``. Each word of the list of words is an output word @@ -2087,11 +2031,9 @@ def _in_epsilon_cycle_(self, fsm=None): INPUT: - ``fsm`` -- the finite state machine to which ``self`` - belongs. - - OUTPUT: + belongs - ``True`` or ``False``. + OUTPUT: boolean TESTS:: @@ -2118,13 +2060,11 @@ def _epsilon_cycle_output_empty_(self, fsm=None): INPUT: - ``fsm`` -- the finite state machine to which ``self`` - belongs. - - OUTPUT: + belongs - ``True`` or ``False`` + OUTPUT: boolean - A :class:`ValueError` is raised when ``self`` is not in an epsilon + A :exc:`ValueError` is raised when ``self`` is not in an epsilon cycle. TESTS:: @@ -2176,7 +2116,7 @@ def _epsilon_cycle_output_empty_(self, fsm=None): def is_FSMTransition(T): """ - Tests whether or not ``T`` inherits from :class:`FSMTransition`. + Test whether or not ``T`` inherits from :class:`FSMTransition`. TESTS:: @@ -2198,9 +2138,9 @@ class FSMTransition(SageObject): INPUT: - - ``from_state`` -- state from which transition starts. + - ``from_state`` -- state from which transition starts - - ``to_state`` -- state in which transition ends. + - ``to_state`` -- state in which transition ends - ``word_in`` -- the input word of the transitions (when the finite state machine is used as automaton) @@ -2208,9 +2148,7 @@ class FSMTransition(SageObject): - ``word_out`` -- the output word of the transitions (when the finite state machine is used as transducer) - OUTPUT: - - A transition of a finite state machine. + OUTPUT: a transition of a finite state machine EXAMPLES:: @@ -2224,7 +2162,6 @@ class FSMTransition(SageObject): sage: U = FSMTransition('A', 'B', 0) sage: U == T False - """ from_state = None @@ -2282,16 +2219,14 @@ def __init__(self, from_state, to_state, def __lt__(self, other): """ - Return True if ``self`` is less than ``other`` with respect to the + Return ``True`` if ``self`` is less than ``other`` with respect to the key ``(self.from_state, self.word_in, self.to_state, self.word_out)``. INPUT: - - ``other`` -- a transition. + - ``other`` -- a transition - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -2306,9 +2241,7 @@ def __copy__(self): """ Return a (shallow) copy of the transition. - OUTPUT: - - A new transition. + OUTPUT: a new transition EXAMPLES:: @@ -2331,11 +2264,9 @@ def __deepcopy__(self, memo): INPUT: - - ``memo`` -- a dictionary storing already processed elements. + - ``memo`` -- dictionary storing already processed elements - OUTPUT: - - A new transition. + OUTPUT: a new transition EXAMPLES:: @@ -2359,11 +2290,9 @@ def deepcopy(self, memo=None): INPUT: - ``memo`` -- (default: ``None``) a dictionary storing already - processed elements. - - OUTPUT: + processed elements - A new transition. + OUTPUT: a new transition EXAMPLES:: @@ -2379,22 +2308,15 @@ def deepcopy(self, memo=None): def _repr_(self): """ - Represents a transitions as from state to state and input, output. + Represent a transitions as from state to state and input, output. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: sage: from sage.combinat.finite_state_machine import FSMTransition sage: FSMTransition('A', 'B', 0, 0)._repr_() "Transition from 'A' to 'B': 0|0" - """ return "Transition from %s to %s: %s" % (repr(self.from_state), repr(self.to_state), @@ -2404,13 +2326,7 @@ def _in_out_label_(self): """ Return the input and output of a transition as "word_in|word_out". - INPUT: - - Nothing. - - OUTPUT: - - A string of the input and output labels. + OUTPUT: string of the input and output labels EXAMPLES:: @@ -2431,13 +2347,11 @@ def __eq__(self, other): INPUT: - - ``self`` -- a transition. + - ``self`` -- a transition - - ``other`` -- a transition. - - OUTPUT: + - ``other`` -- a transition - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -2461,13 +2375,11 @@ def __ne__(self, other): INPUT: - - ``self`` -- a transition. + - ``self`` -- a transition - - ``other`` -- a transition. + - ``other`` -- a transition - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -2498,7 +2410,7 @@ def __bool__(self): def is_FiniteStateMachine(FSM): """ - Tests whether or not ``FSM`` inherits from :class:`FiniteStateMachine`. + Test whether or not ``FSM`` inherits from :class:`FiniteStateMachine`. TESTS:: @@ -2528,14 +2440,12 @@ def duplicate_transition_ignore(old_transition, new_transition): INPUT: - - ``old_transition`` -- A transition in a finite state machine. + - ``old_transition`` -- a transition in a finite state machine - - ``new_transition`` -- A transition, identical to ``old_transition``, - which is to be inserted into the finite state machine. + - ``new_transition`` -- a transition, identical to ``old_transition``, + which is to be inserted into the finite state machine - OUTPUT: - - The same transition, unchanged. + OUTPUT: the same transition, unchanged EXAMPLES:: @@ -2553,21 +2463,19 @@ def duplicate_transition_raise_error(old_transition, new_transition): Alternative function for handling duplicate transitions in finite state machines. - This implementation raises a :class:`ValueError`. + This implementation raises a :exc:`ValueError`. See the documentation of the ``on_duplicate_transition`` parameter of :class:`FiniteStateMachine`. INPUT: - - ``old_transition`` -- A transition in a finite state machine. - - - ``new_transition`` -- A transition, identical to ``old_transition``, - which is to be inserted into the finite state machine. + - ``old_transition`` -- a transition in a finite state machine - OUTPUT: + - ``new_transition`` -- a transition, identical to ``old_transition``, + which is to be inserted into the finite state machine - Nothing. A :class:`ValueError` is raised. + OUTPUT: nothing. A :exc:`ValueError` is raised EXAMPLES:: @@ -2595,10 +2503,10 @@ def duplicate_transition_add_input(old_transition, new_transition): INPUT: - - ``old_transition`` -- A transition in a finite state machine. + - ``old_transition`` -- a transition in a finite state machine - - ``new_transition`` -- A transition, identical to ``old_transition``, - which is to be inserted into the finite state machine. + - ``new_transition`` -- a transition, identical to ``old_transition``, + which is to be inserted into the finite state machine OUTPUT: @@ -2664,22 +2572,22 @@ class FiniteStateMachine(SageObject): - ``input_alphabet`` and ``output_alphabet`` -- the input and output alphabets of this machine - - ``determine_alphabets`` -- If ``True``, then the function + - ``determine_alphabets`` -- if ``True``, then the function :meth:`.determine_alphabets` is called after ``data`` was read and processed, if ``False``, then not. If it is ``None``, then it is decided during the construction of the finite state machine whether :meth:`.determine_alphabets` should be called. - - ``with_final_word_out`` -- If given (not ``None``), then the + - ``with_final_word_out`` -- if given (not ``None``), then the function :meth:`.with_final_word_out` (more precisely, its inplace pendant :meth:`.construct_final_word_out`) is called with input ``letters=with_final_word_out`` at the end of the creation process. - - ``store_states_dict`` -- If ``True``, then additionally the states - are stored in an internal dictionary for speed up. + - ``store_states_dict`` -- if ``True``, then additionally the states + are stored in an internal dictionary for speed up - - ``on_duplicate_transition`` -- A function which is called when a + - ``on_duplicate_transition`` -- a function which is called when a transition is inserted into ``self`` which already existed (same ``from_state``, same ``to_state``, same ``word_in``, same ``word_out``). @@ -2696,9 +2604,7 @@ class FiniteStateMachine(SageObject): ``duplicate_transition_raise_error`` and ``duplicate_transition_add_input``. - OUTPUT: - - A finite state machine. + OUTPUT: a finite state machine The object creation of :class:`Automaton` and :class:`Transducer` is the same as the one described here (i.e. just replace the word @@ -2828,7 +2734,7 @@ class FiniteStateMachine(SageObject): non-deterministic). If the transition does not exist, the function should raise a - :class:`LookupError` or return an empty list. + :exc:`LookupError` or return an empty list. When constructing a finite state machine in this way, some initial states and an input alphabet have to be specified. @@ -3234,9 +3140,7 @@ def __copy__(self): """ Return a (shallow) copy of the finite state machine. - OUTPUT: - - A new finite state machine. + OUTPUT: a new finite state machine TESTS:: @@ -3257,14 +3161,12 @@ def empty_copy(self, memo=None, new_class=None): INPUT: - - ``memo`` -- a dictionary storing already processed elements. + - ``memo`` -- dictionary storing already processed elements - - ``new_class`` -- a class for the copy. By default - (``None``), the class of ``self`` is used. + - ``new_class`` -- a class for the copy; by default + (``None``), the class of ``self`` is used - OUTPUT: - - A new finite state machine. + OUTPUT: a new finite state machine EXAMPLES:: @@ -3303,11 +3205,9 @@ def __deepcopy__(self, memo): INPUT: - - ``memo`` -- a dictionary storing already processed elements. - - OUTPUT: + - ``memo`` -- dictionary storing already processed elements - A new finite state machine. + OUTPUT: a new finite state machine EXAMPLES:: @@ -3326,11 +3226,9 @@ def deepcopy(self, memo=None): INPUT: - ``memo`` -- (default: ``None``) a dictionary storing already - processed elements. - - OUTPUT: + processed elements - A new finite state machine. + OUTPUT: a new finite state machine EXAMPLES:: @@ -3357,11 +3255,9 @@ def _copy_from_other_(self, other, memo=None, empty=False): INPUT: - - ``other`` -- a :class:`FiniteStateMachine`. + - ``other`` -- a :class:`FiniteStateMachine` - OUTPUT: - - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -3406,9 +3302,7 @@ def __getstate__(self): """ Return state for pickling excluding outgoing transitions. - OUTPUT: - - A dictionary. + OUTPUT: a dictionary Outgoing transitions are in fact stored in states, but must be pickled by the finite state machine @@ -3430,11 +3324,9 @@ def __setstate__(self, d): INPUT: - - `d` -- a dictionary - - OUTPUT: + - ``d`` -- dictionary - None. + OUTPUT: none As transitions are in fact stored in states but not saved by states in order to avoid deep recursion, transitions @@ -3461,15 +3353,13 @@ def relabeled(self, memo=None, labels=None): INPUT: - ``memo`` -- (default: ``None``) a dictionary storing already - processed elements. + processed elements - ``labels`` -- (default: ``None``) a dictionary or callable mapping old labels to new labels. If ``None``, then the new labels are integers starting with 0. - OUTPUT: - - A new finite state machine. + OUTPUT: a new finite state machine EXAMPLES:: @@ -3507,8 +3397,8 @@ def induced_sub_finite_state_machine(self, states): INPUT: - - ``states`` -- a list (or an iterator) of states (either labels or - instances of :class:`FSMState`) of the sub-finite-state-machine. + - ``states`` -- list (or an iterator) of states (either labels or + instances of :class:`FSMState`) of the sub-finite-state-machine OUTPUT: @@ -3562,13 +3452,7 @@ def __hash__(self): Since finite state machines are mutable, they should not be hashable, so we return a type error. - INPUT: - - Nothing. - - OUTPUT: - - The hash of this finite state machine. + OUTPUT: the hash of this finite state machine EXAMPLES:: @@ -3592,11 +3476,9 @@ def __or__(self, other): INPUT: - - ``other`` -- a finite state machine. - - OUTPUT: + - ``other`` -- a finite state machine - A new finite state machine. + OUTPUT: a new finite state machine .. SEEALSO:: @@ -3917,13 +3799,9 @@ def __call__(self, *args, **kwargs): def __bool__(self): """ - Return True if the finite state machine consists of at least + Return ``True`` if the finite state machine consists of at least one state. - OUTPUT: - - True or False. - TESTS:: sage: bool(FiniteStateMachine()) @@ -3938,13 +3816,11 @@ def __eq__(self, other): INPUT: - - ``self`` -- a finite state machine. - - - ``other`` -- a finite state machine. + - ``self`` -- a finite state machine - OUTPUT: + - ``other`` -- a finite state machine - ``True`` or ``False``. + OUTPUT: boolean Note that this function compares all attributes of a state (by using :meth:`FSMState.fully_equal`) except for colors. Colors @@ -4016,17 +3892,15 @@ def __eq__(self, other): def __ne__(self, other): """ - Tests for inequality, complement of :meth:`.__eq__`. + Test for inequality, complement of :meth:`.__eq__`. INPUT: - - ``self`` -- a finite state machine. + - ``self`` -- a finite state machine - - ``other`` -- a finite state machine. - - OUTPUT: + - ``other`` -- a finite state machine - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -4050,11 +3924,9 @@ def __contains__(self, item): INPUT: - - ``item`` -- a state or a transition. + - ``item`` -- a state or a transition - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -4075,7 +3947,7 @@ def __contains__(self, item): def is_Markov_chain(self, is_zero=None): """ - Checks whether ``self`` is a Markov chain where the transition + Check whether ``self`` is a Markov chain where the transition probabilities are modeled as input labels. INPUT: @@ -4087,9 +3959,7 @@ def is_Markov_chain(self, is_zero=None): for zero, e.g. in the case of symbolic probabilities, see the examples below. - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean :attr:`on_duplicate_transition` must be :func:`duplicate_transition_add_input`, the sum of the input weights @@ -4197,16 +4067,10 @@ def default_is_zero(expression): def _repr_(self): """ - Represents the finite state machine as "Finite state machine + Represent the finite state machine as "Finite state machine with n states" where n is the number of states. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -4226,7 +4090,6 @@ def _repr_(self): 43 sage: F Finite state machine with 2 states - """ if not self._states_: return "Empty finite state machine" @@ -4245,7 +4108,7 @@ def format_letter_negative(self, letter): INPUT: - - ``letter`` -- anything. + - ``letter`` -- anything OUTPUT: @@ -4275,7 +4138,7 @@ def format_transition_label_reversed(self, word): INPUT: - - ``word`` -- list of letters. + - ``word`` -- list of letters OUTPUT: @@ -4419,7 +4282,7 @@ def latex_options(self, INPUT: - - ``coordinates`` -- a dictionary or a function mapping labels + - ``coordinates`` -- dictionary or a function mapping labels of states to pairs interpreted as coordinates. If no coordinates are given, states a placed equidistantly on a circle of radius `3`. See also :meth:`.set_coordinates`. @@ -4440,11 +4303,11 @@ def latex_options(self, typesetting in LaTeX's mathematics mode. If not given, :meth:`.default_format_transition_label` is used. - - ``loop_where`` -- a dictionary or a function mapping labels of + - ``loop_where`` -- dictionary or a function mapping labels of initial states to one of ``'above'``, ``'left'``, ``'below'``, ``'right'``. If not given, ``'above'`` is used. - - ``initial_where`` -- a dictionary or a function mapping + - ``initial_where`` -- dictionary or a function mapping labels of initial states to one of ``'above'``, ``'left'``, ``'below'``, ``'right'``. If not given, TikZ' default (currently ``'left'``) is used. @@ -4454,13 +4317,13 @@ def latex_options(self, double'`` is used unless there are non-empty final output words. - - ``accepting_distance`` -- a string giving a LaTeX length + - ``accepting_distance`` -- string giving a LaTeX length used for the length of the arrow leading from a final state. If not given, TikZ' default (currently ``'3ex'``) is used unless there are non-empty final output words, in which case ``'7ex'`` is used. - - ``accepting_where`` -- a dictionary or a function mapping + - ``accepting_where`` -- dictionary or a function mapping labels of final states to one of ``'above'``, ``'left'``, ``'below'``, ``'right'``. If not given, TikZ' default (currently ``'right'``) is used. If the final state has a @@ -4472,9 +4335,7 @@ def latex_options(self, implicitly implies ``accepting_style='accepting by arrow'``. If not given, the default ``False`` is used. - OUTPUT: - - Nothing. + OUTPUT: nothing As TikZ (cf. the :wikipedia:`PGF/TikZ`) is used to typeset the graphics, the syntax is oriented on TikZ' syntax. @@ -4767,9 +4628,7 @@ def _latex_(self): r""" Return a LaTeX code for the graph of the finite state machine. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -4973,9 +4832,7 @@ def _latex_transition_label_(self, transition, - ``format_function`` -- a function formatting the labels - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -4993,16 +4850,14 @@ def set_coordinates(self, coordinates, default=True): INPUT: - - ``coordinates`` -- a dictionary or a function mapping labels - of states to pairs interpreted as coordinates. + - ``coordinates`` -- dictionary or a function mapping labels + of states to pairs interpreted as coordinates - - ``default`` -- If ``True``, then states not given by + - ``default`` -- if ``True``, then states not given by ``coordinates`` get a default position on a circle of radius 3. - OUTPUT: - - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -5076,18 +4931,16 @@ def adjacency_matrix(self, input=None, INPUT: - - ``input`` -- Only transitions with input label ``input`` are - respected. + - ``input`` -- only transitions with input label ``input`` are + respected - - ``entry`` -- The function ``entry`` takes a transition and the + - ``entry`` -- the function ``entry`` takes a transition and the return value is written in the matrix as the entry ``(transition.from_state, transition.to_state)``. The default value (``None``) of entry takes the variable ``x`` to the power of the sum of the output word of the transition. - OUTPUT: - - A matrix. + OUTPUT: a matrix If any label of a state is not an integer, the finite state machine is relabeled at the beginning. If there are more than @@ -5145,7 +4998,6 @@ def adjacency_matrix(self, input=None, [0 1 0] [0 0 1] [1 1 0] - """ if entry is None: @@ -5186,13 +5038,11 @@ def determine_input_alphabet(self, reset=True): INPUT: - - ``reset`` -- a boolean (default: ``True``). If ``True``, then + - ``reset`` -- boolean (default: ``True``); if ``True``, then the existing input alphabet is erased, otherwise new letters are appended to the existing alphabet. - OUTPUT: - - Nothing. + OUTPUT: nothing After this operation the input alphabet of this finite state machine is a list of letters. @@ -5235,13 +5085,11 @@ def determine_output_alphabet(self, reset=True): INPUT: - - ``reset`` -- a boolean (default: ``True``). If ``True``, then + - ``reset`` -- boolean (default: ``True``); if ``True``, then the existing output alphabet is erased, otherwise new letters are appended to the existing alphabet. - OUTPUT: - - Nothing. + OUTPUT: nothing After this operation the output alphabet of this finite state machine is a list of letters. @@ -5288,13 +5136,11 @@ def determine_alphabets(self, reset=True): INPUT: - - ``reset`` -- If reset is ``True``, then the existing input + - ``reset`` -- if reset is ``True``, then the existing input and output alphabets are erased, otherwise new letters are appended to the existing alphabets. - OUTPUT: - - Nothing. + OUTPUT: nothing After this operation the input alphabet and the output alphabet of this finite state machine are a list of letters. @@ -5332,9 +5178,7 @@ def states(self): """ Return the states of the finite state machine. - OUTPUT: - - The states of the finite state machine as list. + OUTPUT: the states of the finite state machine as list EXAMPLES:: @@ -5348,9 +5192,7 @@ def iter_states(self): """ Return an iterator of the states. - OUTPUT: - - An iterator of the states of the finite state machine. + OUTPUT: an iterator of the states of the finite state machine EXAMPLES:: @@ -5366,12 +5208,10 @@ def transitions(self, from_state=None): INPUT: - - ``from_state`` -- (default: ``None``) If ``from_state`` is - given, then a list of transitions starting there is given. + - ``from_state`` -- (default: ``None``) if ``from_state`` is + given, then a list of transitions starting there is given - OUTPUT: - - A list of all transitions. + OUTPUT: list of all transitions EXAMPLES:: @@ -5388,12 +5228,10 @@ def iter_transitions(self, from_state=None): INPUT: - - ``from_state`` -- (default: ``None``) If ``from_state`` is - given, then a list of transitions starting there is given. - - OUTPUT: + - ``from_state`` -- (default: ``None``) if ``from_state`` is + given, then a list of transitions starting there is given - An iterator of all transitions. + OUTPUT: an iterator of all transitions EXAMPLES:: @@ -5417,9 +5255,7 @@ def _iter_transitions_all_(self): """ Return an iterator over all transitions. - OUTPUT: - - An iterator over all transitions. + OUTPUT: an iterator over all transitions EXAMPLES:: @@ -5435,10 +5271,6 @@ def initial_states(self): """ Return a list of all initial states. - OUTPUT: - - A list of all initial states. - EXAMPLES:: sage: from sage.combinat.finite_state_machine import FSMState @@ -5454,9 +5286,7 @@ def iter_initial_states(self): """ Return an iterator of the initial states. - OUTPUT: - - An iterator over all initial states. + OUTPUT: an iterator over all initial states EXAMPLES:: @@ -5473,10 +5303,6 @@ def final_states(self): """ Return a list of all final states. - OUTPUT: - - A list of all final states. - EXAMPLES:: sage: from sage.combinat.finite_state_machine import FSMState @@ -5493,9 +5319,7 @@ def iter_final_states(self): """ Return an iterator of the final states. - OUTPUT: - - An iterator over all initial states. + OUTPUT: an iterator over all initial states EXAMPLES:: @@ -5515,15 +5339,13 @@ def state(self, state): INPUT: - - ``state`` -- If ``state`` is not an instance of + - ``state`` -- if ``state`` is not an instance of :class:`FSMState`, then it is assumed that it is the label of a state. - OUTPUT: - - The state of the finite state machine corresponding to ``state``. + OUTPUT: the state of the finite state machine corresponding to ``state`` - If no state is found, then a :class:`LookupError` is thrown. + If no state is found, then a :exc:`LookupError` is thrown. EXAMPLES:: @@ -5560,16 +5382,14 @@ def transition(self, transition): INPUT: - - ``transition`` -- If ``transition`` is not an instance of + - ``transition`` -- if ``transition`` is not an instance of :class:`FSMTransition`, then it is assumed that it is a - tuple ``(from_state, to_state, word_in, word_out)``. + tuple ``(from_state, to_state, word_in, word_out)`` - OUTPUT: + OUTPUT: the transition of the finite state machine corresponding + to ``transition`` - The transition of the finite state machine corresponding - to ``transition``. - - If no transition is found, then a :class:`LookupError` is thrown. + If no transition is found, then a :exc:`LookupError` is thrown. EXAMPLES:: @@ -5601,9 +5421,7 @@ def has_state(self, state): - ``state`` can be a :class:`FSMState` or a label of a state. - OUTPUT: - - True or False. + OUTPUT: boolean EXAMPLES:: @@ -5625,9 +5443,7 @@ def has_transition(self, transition): - ``transition`` has to be a :class:`FSMTransition`. - OUTPUT: - - True or False. + OUTPUT: boolean EXAMPLES:: @@ -5653,9 +5469,7 @@ def has_initial_state(self, state): - ``state`` can be a :class:`FSMState` or a label. - OUTPUT: - - True or False. + OUTPUT: boolean EXAMPLES:: @@ -5672,9 +5486,7 @@ def has_initial_states(self): """ Return whether the finite state machine has an initial state. - OUTPUT: - - True or False. + OUTPUT: boolean EXAMPLES:: @@ -5692,9 +5504,7 @@ def has_final_state(self, state): - ``state`` can be a :class:`FSMState` or a label. - OUTPUT: - - True or False. + OUTPUT: boolean EXAMPLES:: @@ -5710,9 +5520,7 @@ def has_final_states(self): """ Return whether the finite state machine has a final state. - OUTPUT: - - True or False. + OUTPUT: boolean EXAMPLES:: @@ -5729,9 +5537,7 @@ def is_deterministic(self): """ Return whether the finite finite state machine is deterministic. - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean A finite state machine is considered to be deterministic if each transition has input label of length one and for each @@ -5785,9 +5591,7 @@ def is_complete(self): """ Return whether the finite state machine is complete. - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean A finite state machine is considered to be complete if each transition has an input label of length one and for each @@ -5894,10 +5698,10 @@ def process(self, *args, **kwargs): what to do (e.g. if a non-deterministic machine returns more than one path, then the output is returned in list form). - - ``only_accepted`` -- (default: ``False``) a boolean. If set, - then the first argument in the output is guaranteed to be - ``True`` (if the output is a list, then the first argument - of each element will be ``True``). + - ``only_accepted`` -- boolean (default: ``False``); if set, then the + first argument in the output is guaranteed to be ``True`` (if the + output is a list, then the first argument of each element will be + ``True``) - ``always_include_output`` -- if set (not by default), always include the output. This is inconsequential for a @@ -5909,35 +5713,31 @@ def process(self, *args, **kwargs): output (which is in form of a list) to something more readable. By default (``None``) identity is used here. - - ``check_epsilon_transitions`` -- (default: ``True``) a - boolean. If ``False``, then epsilon transitions are not - taken into consideration during process. + - ``check_epsilon_transitions`` -- boolean (default: ``True``); if + ``False``, then epsilon transitions are not taken into consideration + during process - - ``write_final_word_out`` -- (default: ``True``) a boolean - specifying whether the final output words should be written - or not. + - ``write_final_word_out`` -- boolean (default: ``True``); whether the + final output words should be written or not - - ``use_multitape_input`` -- (default: ``False``) a - boolean. If ``True``, then the multi-tape mode of the - process iterator is activated. See also the notes below for - multi-tape machines. + - ``use_multitape_input`` -- boolean (default: ``False``); if ``True``, + then the multi-tape mode of the process iterator is activated. See + also the notes below for multi-tape machines. - - ``process_all_prefixes_of_input`` -- (default: ``False``) a - boolean. If ``True``, then each prefix of the input word is - processed (instead of processing the whole input word at - once). Consequently, there is an output generated for each - of these prefixes. + - ``process_all_prefixes_of_input`` -- boolean (default: ``False``); if + ``True``, then each prefix of the input word is processed (instead of + processing the whole input word at once). Consequently, there is an + output generated for each of these prefixes. - ``process_iterator_class`` -- (default: ``None``) a class inherited from :class:`FSMProcessIterator`. If ``None``, then :class:`FSMProcessIterator` is taken. An instance of this class is created and is used during the processing. - - ``automatic_output_type`` -- (default: ``False``) a boolean. - If set and the input has a parent, then the - output will have the same parent. If the input does not have - a parent, then the output will be of the same type as the - input. + - ``automatic_output_type`` -- boolean (default: ``False``); if set and + the input has a parent, then the output will have the same parent. If + the input does not have a parent, then the output will be of the same + type as the input. OUTPUT: @@ -6216,13 +6016,11 @@ def _process_convert_output_(self, output_data, **kwargs): INPUT: - - ``output_data`` -- a triple. - - - ``full_output`` -- a boolean. + - ``output_data`` -- a triple - OUTPUT: + - ``full_output`` -- boolean - The converted output. + OUTPUT: the converted output This function is overridden in :class:`Automaton` and :class:`Transducer`. @@ -6252,7 +6050,7 @@ def iter_process(self, input_tape=None, initial_state=None, INPUT: - - ``iterator_type`` -- If ``None`` (default), then + - ``iterator_type`` -- if ``None`` (default), then an instance of :class:`FSMProcessIterator` is returned. If this is ``'simple'`` only an iterator over one output is returned (an exception is raised if this is not the case, i.e., @@ -6260,9 +6058,7 @@ def iter_process(self, input_tape=None, initial_state=None, See :meth:`process` for a description of the other parameters. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES: @@ -6406,16 +6202,14 @@ def iter_process(self, input_tape=None, initial_state=None, def _iter_process_simple_(self, iterator): r""" - Converts a :class:`process iterator ` to a simpler + Convert a :class:`process iterator ` to a simpler iterator, which only outputs the written letters. INPUT: - - ``iterator`` -- in instance of :class:`FSMProcessIterator`. + - ``iterator`` -- in instance of :class:`FSMProcessIterator` - OUTPUT: - - A generator. + OUTPUT: a generator An exception is raised if the process branches. @@ -6498,7 +6292,7 @@ def _iter_process_simple_(self, iterator): def add_state(self, state): """ - Adds a state to the finite state machine and returns the new + Add a state to the finite state machine and returns the new state. If the state already exists, that existing state is returned. @@ -6508,9 +6302,7 @@ def add_state(self, state): :class:`FSMState` or, otherwise, a label of a state. - OUTPUT: - - The new or existing state. + OUTPUT: the new or existing state EXAMPLES:: @@ -6539,15 +6331,13 @@ def add_state(self, state): def add_states(self, states): """ - Adds several states. See add_state for more information. + Add several states. See add_state for more information. INPUT: - - ``states`` -- a list of states or iterator over states. - - OUTPUT: + - ``states`` -- list of states or iterator over states - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -6561,7 +6351,7 @@ def add_states(self, states): def add_transition(self, *args, **kwargs): """ - Adds a transition to the finite state machine and returns the + Add a transition to the finite state machine and returns the new transition. If the transition already exists, the return value of @@ -6650,15 +6440,13 @@ def add_transition(self, *args, **kwargs): def _add_fsm_transition_(self, t): """ - Adds a transition. + Add a transition. INPUT: - - ``t`` -- an instance of :class:`FSMTransition`. + - ``t`` -- an instance of :class:`FSMTransition` - OUTPUT: - - The new transition. + OUTPUT: the new transition TESTS:: @@ -6681,24 +6469,22 @@ def _add_fsm_transition_(self, t): def add_from_transition_function(self, function, initial_states=None, explore_existing_states=True): """ - Constructs a finite state machine from a transition function. + Construct a finite state machine from a transition function. INPUT: - ``function`` may return a tuple (new_state, output_word) or a - list of such tuples. + list of such tuples - - ``initial_states`` -- If no initial states are given, the - already existing initial states of self are taken. + - ``initial_states`` -- if no initial states are given, the + already existing initial states of ``self`` are taken - - If ``explore_existing_states`` is True (default), then - already existing states in self (e.g. already given final - states) will also be processed if they are reachable from - the initial states. - - OUTPUT: + - ``explore_existing_states`` -- boolean (default: ``True``); if + ``True`` (default), then already existing states in ``self`` (e.g. + already given final states) will also be processed if they are + reachable from the initial statess - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -6833,7 +6619,7 @@ def add_from_transition_function(self, function, initial_states=None, def add_transitions_from_function(self, function, labels_as_input=True): """ - Adds one or more transitions if ``function(state, state)`` + Add one or more transitions if ``function(state, state)`` says that there are some. INPUT: @@ -6851,9 +6637,7 @@ def add_transitions_from_function(self, function, labels_as_input=True): - ``label_as_input`` -- (default: ``True``) - OUTPUT: - - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -6897,7 +6681,6 @@ def add_transitions_from_function(self, function, labels_as_input=True): is expected to return a pair (word_in, word_out) or a list of such pairs. For states 0 and 0 however, it returned 1, which is not acceptable. - """ for s_from in self.iter_states(): for s_to in self.iter_states(): @@ -6933,16 +6716,14 @@ def add_transitions_from_function(self, function, labels_as_input=True): def delete_transition(self, t): """ - Deletes a transition by removing it from the list of transitions of + Delete a transition by removing it from the list of transitions of the state, where the transition starts. INPUT: - - ``t`` -- a transition. - - OUTPUT: + - ``t`` -- a transition - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -6956,15 +6737,13 @@ def delete_transition(self, t): def delete_state(self, s): """ - Deletes a state and all transitions coming or going to this state. + Delete a state and all transitions coming or going to this state. INPUT: - - ``s`` -- a label of a state or an :class:`FSMState`. + - ``s`` -- a label of a state or an :class:`FSMState` - OUTPUT: - - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -7015,11 +6794,9 @@ def epsilon_successors(self, state): INPUT: - ``state`` -- the state whose epsilon successors should be - determined. + determined - OUTPUT: - - A dictionary mapping states to a list of output words. + OUTPUT: a dictionary mapping states to a list of output words The states in the output are the epsilon successors of ``state``. Each word of the list of output words is a word @@ -7050,20 +6827,16 @@ def epsilon_successors(self, state): def accessible_components(self): """ Return a new finite state machine with the accessible states - of self and all transitions between those states. - - INPUT: - - Nothing. + of ``self`` and all transitions between those states. OUTPUT: - A finite state machine with the accessible states of self and + A finite state machine with the accessible states of ``self`` and all transitions between those states. A state is accessible if there is a directed path from an - initial state to the state. If self has no initial states then - a copy of the finite state machine self is returned. + initial state to the state. If ``self`` has no initial states then + a copy of the finite state machine ``self`` is returned. EXAMPLES:: @@ -7164,7 +6937,7 @@ def disjoint_union(self, other): INPUT: - - ``other`` -- a :class:`FiniteStateMachine`. + - ``other`` -- a :class:`FiniteStateMachine` OUTPUT: @@ -7323,7 +7096,7 @@ def concatenation(self, other): INPUT: - - ``other`` -- a :class:`FiniteStateMachine`. + - ``other`` -- a :class:`FiniteStateMachine` OUTPUT: @@ -7632,31 +7405,31 @@ def product_FiniteStateMachine(self, other, function, INPUT: - ``other`` -- a finite state machine (for `d=2`) or a list - (or iterable) of `d-1` finite state machines. + (or iterable) of `d-1` finite state machines - ``function`` has to accept `d` transitions from `A_j` to `B_j` for `j\in\{1, \ldots, d\}` and returns a pair ``(word_in, word_out)`` which is the label of the transition `A=(A_1, \ldots, A_d)` to `B=(B_1, \ldots, B_d)`. If there is no transition from `A` to `B`, - then ``function`` should raise a :class:`LookupError`. + then ``function`` should raise a :exc:`LookupError`. - - ``new_input_alphabet`` (optional) -- the new input alphabet - as a list. + - ``new_input_alphabet`` -- (optional) the new input alphabet + as a list - - ``only_accessible_components`` -- If ``True`` (default), then + - ``only_accessible_components`` -- if ``True`` (default), then the result is piped through :meth:`.accessible_components`. If no ``new_input_alphabet`` is given, it is determined by :meth:`.determine_alphabets`. - - ``final_function`` -- A function mapping `d` final states of + - ``final_function`` -- a function mapping `d` final states of the original finite state machines to the final output of the corresponding state in the new finite state machine. By default, the final output is the empty word if both final outputs of the constituent states are empty; otherwise, a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. - - ``new_class`` -- Class of the new finite state machine. By - default (``None``), the class of ``self`` is used. + - ``new_class`` -- class of the new finite state machine. By + default (``None``), the class of ``self`` is used OUTPUT: @@ -7901,7 +7674,7 @@ def composition(self, other, algorithm=None, - ``algorithm`` -- can be one of the following - - ``direct`` -- The composition is calculated directly. + - ``direct`` -- the composition is calculated directly There can be arbitrarily many initial and final states, but the input and output labels must have length `1`. @@ -7910,9 +7683,9 @@ def composition(self, other, algorithm=None, The output of ``other`` is fed into ``self``. - - ``explorative`` -- An explorative algorithm is used. + - ``explorative`` -- an explorative algorithm is used - The input alphabet of self has to be specified. + The input alphabet of ``self`` has to be specified. .. WARNING:: @@ -7923,15 +7696,12 @@ def composition(self, other, algorithm=None, there are output words of ``other`` or input words of ``self`` of length greater than `1`). - OUTPUT: - - A new transducer. + OUTPUT: a new transducer The labels of the new finite state machine are pairs of states of the original finite state machines. The color of a new state is the tuple of colors of the constituent states. - EXAMPLES:: sage: F = Transducer([('A', 'B', 1, 0), ('B', 'A', 0, 1)], @@ -8349,11 +8119,9 @@ def composition_transition(states, input): def input_projection(self): """ Return an automaton where the output of each transition of - self is deleted. + ``self`` is deleted. - OUTPUT: - - An automaton. + OUTPUT: an automaton EXAMPLES:: @@ -8372,9 +8140,7 @@ def output_projection(self): Return a automaton where the input of each transition of self is deleted and the new input is the original output. - OUTPUT: - - An automaton. + OUTPUT: an automaton EXAMPLES:: @@ -8413,11 +8179,9 @@ def projection(self, what='input'): INPUT: - - ``what`` -- (default: ``input``) either ``input`` or ``output``. - - OUTPUT: + - ``what`` -- (default: ``input``) either ``input`` or ``output`` - An automaton. + OUTPUT: an automaton EXAMPLES:: @@ -8480,12 +8244,8 @@ def transposition(self, reverse_output_labels=True): INPUT: - - ``reverse_output_labels`` -- a boolean (default: ``True``): whether to reverse - output labels. - - OUTPUT: - - A new finite state machine. + - ``reverse_output_labels`` -- boolean (default: ``True``); whether to + reverse output labels EXAMPLES:: @@ -8576,13 +8336,11 @@ def transposition(self, reverse_output_labels=True): def split_transitions(self): """ - Return a new transducer, where all transitions in self with input + Return a new transducer, where all transitions in ``self`` with input labels consisting of more than one letter are replaced by a path of the corresponding length. - OUTPUT: - - A new transducer. + OUTPUT: a new transducer EXAMPLES:: @@ -8663,8 +8421,8 @@ def completion(self, sink=None): INPUT: - ``sink`` -- either an instance of :class:`FSMState` or a label - for the sink (default: ``None``). If ``None``, the least - available non-zero integer is used. + for the sink (default: ``None``); if ``None``, the least + available nonzero integer is used OUTPUT: @@ -8817,13 +8575,7 @@ def prepone_output(self): transition to the earliest possible preceding transition of the path. - INPUT: - - Nothing. - - OUTPUT: - - Nothing. + OUTPUT: nothing Apply the following to each state `s` (except initial states) of the finite state machine as often as possible: @@ -8983,10 +8735,6 @@ def equivalence_classes(self): r""" Return a list of equivalence classes of states. - OUTPUT: - - A list of equivalence classes of states. - Two states `a` and `b` are equivalent if and only if there is a bijection `\varphi` between paths starting at `a` and paths starting at `b` with the following properties: Let `p_a` be a @@ -9087,9 +8835,7 @@ def quotient(self, classes): - ``classes`` is a list of equivalence classes of states. - OUTPUT: - - A finite state machine. + OUTPUT: a finite state machine The labels of the new states are tuples of states of the ``self``, corresponding to ``classes``. @@ -9202,10 +8948,6 @@ def merged_transitions(self): Merges transitions which have the same ``from_state``, ``to_state`` and ``word_out`` while adding their ``word_in``. - INPUT: - - Nothing. - OUTPUT: A finite state machine with merged transitions. If no mergers occur, @@ -9273,13 +9015,7 @@ def markov_chain_simplification(self): Consider ``self`` as Markov chain with probabilities as input labels and simplify it. - INPUT: - - Nothing. - - OUTPUT: - - Simplified version of ``self``. + OUTPUT: simplified version of ``self`` EXAMPLES:: @@ -9310,7 +9046,7 @@ def markov_chain_simplification(self): def with_final_word_out(self, letters, allow_non_final=True): """ - Constructs a new finite state machine with final output words + Construct a new finite state machine with final output words for all states by implicitly reading trailing letters until a final state is reached. @@ -9320,15 +9056,12 @@ def with_final_word_out(self, letters, allow_non_final=True): list of such elements. This is repeated cyclically when needed. - - ``allow_non_final`` -- a boolean (default: ``True``) which - indicates whether we allow that some states may be non-final - in the resulting finite state machine. I.e., if ``False`` then - each state has to have a path to a final state with input - label matching ``letters``. - - OUTPUT: + - ``allow_non_final`` -- boolean (default: ``True``); whether we allow + that some states may be non-final in the resulting finite state + machine. I.e., if ``False`` then each state has to have a path to a + final state with input label matching ``letters``. - A finite state machine. + OUTPUT: a finite state machine The inplace version of this function is :meth:`.construct_final_word_out`. @@ -9664,14 +9397,12 @@ def graph(self, edge_labels='words_in_out'): INPUT: - - ``edge_label``: (default: ``'words_in_out'``) can be - - ``'words_in_out'`` (labels will be strings ``'i|o'``) - - a function with which takes as input a transition - and outputs (returns) the label - - OUTPUT: + - ``edge_label`` -- (default: ``'words_in_out'``) can be + - ``'words_in_out'`` (labels will be strings ``'i|o'``) + - a function with which takes as input a transition + and outputs (returns) the label - A :class:`directed graph `. + OUTPUT: a :class:`directed graph ` EXAMPLES:: @@ -9721,13 +9452,7 @@ def plot(self): Plots a graph of the finite state machine with labeled vertices and labeled edges. - INPUT: - - Nothing. - - OUTPUT: - - A plot of the graph of the finite state machine. + OUTPUT: a plot of the graph of the finite state machine TESTS:: @@ -9738,23 +9463,21 @@ def plot(self): def predecessors(self, state, valid_input=None): """ - Lists all predecessors of a state. + List all predecessors of a state. INPUT: - ``state`` -- the state from which the predecessors should be - listed. + listed - - ``valid_input`` -- If ``valid_input`` is a list, then we + - ``valid_input`` -- if ``valid_input`` is a list, then we only consider transitions whose input labels are contained in ``valid_input``. ``state`` has to be a :class:`FSMState` (not a label of a state). If input labels of length larger than `1` are used, then ``valid_input`` has to be a list of lists. - OUTPUT: - - A list of states. + OUTPUT: list of states EXAMPLES:: @@ -9801,14 +9524,12 @@ def number_of_words(self, variable=None, INPUT: - ``variable`` -- a symbol denoting the length of the words, - by default `n`. - - - ``base_ring`` -- Ring (default: ``QQbar``) in which to - compute the eigenvalues. + by default `n` - OUTPUT: + - ``base_ring`` -- ring (default: ``QQbar``) in which to + compute the eigenvalues - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -9945,11 +9666,9 @@ def asymptotic_moments(self, variable=None): INPUT: - ``variable`` -- a symbol denoting the length of the input, - by default `n`. - - OUTPUT: + (default: `n`) - A dictionary consisting of + OUTPUT: a dictionary consisting of - ``expectation`` -- `e n + \operatorname{Order}(1)`, - ``variance`` -- `v n + \operatorname{Order}(1)`, @@ -10441,7 +10160,7 @@ def moments_waiting_time(self, test=bool, is_zero=None, :meth:`is_Markov_chain`. This parameter only affects the input of the Markov chain. - - ``expectation_only`` -- (default: ``False``) if set, the + - ``expectation_only`` -- boolean (default: ``False``); if set, the variance is not computed (in order to save time). By default, the variance is computed. @@ -10790,8 +10509,8 @@ def entry(transition): else: base_ring = transition_matrix.parent().base_ring() from sage.rings.polynomial.multi_polynomial_ring \ - import is_MPolynomialRing - if is_MPolynomialRing(base_ring): + import MPolynomialRing_base + if isinstance(base_ring, MPolynomialRing_base): # if base_ring is already a multivariate polynomial # ring, extend it instead of creating a univariate # polynomial ring over a polynomial ring. This @@ -10819,9 +10538,7 @@ def is_monochromatic(self): """ Check whether the colors of all states are equal. - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: @@ -10842,7 +10559,7 @@ def language(self, max_length=None, **kwargs): INPUT: - - ``max_length`` -- an integer or ``None`` (default). Only + - ``max_length`` -- integer or ``None`` (default). Only output words which come from inputs of length at most ``max_length`` will be considered. If ``None``, then this iterates over all possible words without length restrictions. @@ -10851,9 +10568,7 @@ def language(self, max_length=None, **kwargs): iterator `. See :meth:`process` for a description. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -10935,7 +10650,7 @@ def language(self, max_length=None, **kwargs): def is_Automaton(FSM): """ - Tests whether or not ``FSM`` inherits from :class:`Automaton`. + Test whether or not ``FSM`` inherits from :class:`Automaton`. TESTS:: @@ -11014,16 +10729,10 @@ def __init__(self, *args, **kwargs): def _repr_(self): """ - Represents the finite state machine as "Automaton with n + Represent the finite state machine as "Automaton with n states" where n is the number of states. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -11044,7 +10753,6 @@ def _repr_(self): 43 sage: A Automaton with 2 states - """ if not self._states_: return "Empty automaton" @@ -11064,9 +10772,7 @@ def _latex_transition_label_(self, transition, - ``format_function`` -- a function formatting the labels - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -11098,7 +10804,7 @@ def intersection(self, other, only_accessible_components=True): - ``other`` -- an automaton - - ``only_accessible_components`` -- If ``True`` (default), then + - ``only_accessible_components`` -- if ``True`` (default), then the result is piped through :meth:`.accessible_components`. If no ``new_input_alphabet`` is given, it is determined by :meth:`.determine_alphabets`. @@ -11193,9 +10899,7 @@ def determinisation(self): Return a deterministic automaton which accepts the same input words as the original one. - OUTPUT: - - A new automaton, which is deterministic. + OUTPUT: a new automaton, which is deterministic The labels of the states of the new automaton are frozensets of states of ``self``. The color of a new state is the @@ -11373,15 +11077,13 @@ def minimization(self, algorithm=None): INPUT: - - ``algorithm`` -- Either Moore's algorithm (by + - ``algorithm`` -- either Moore's algorithm (by ``algorithm='Moore'`` or as default for deterministic automata) or Brzozowski's algorithm (when ``algorithm='Brzozowski'`` or when the automaton is not deterministic) is used. - OUTPUT: - - A new automaton. + OUTPUT: a new automaton The resulting automaton is deterministic and has a minimal number of states. @@ -11487,9 +11189,7 @@ def complement(self): r""" Return the complement of this automaton. - OUTPUT: - - An :class:`Automaton`. + OUTPUT: an :class:`Automaton` If this automaton recognizes language `\mathcal{L}` over an input alphabet `\mathcal{A}`, then the complement recognizes @@ -11540,7 +11240,7 @@ def is_equivalent(self, other): INPUT: - - ``other`` -- an :class:`Automaton`. + - ``other`` -- an :class:`Automaton` EXAMPLES:: @@ -11606,12 +11306,12 @@ def process(self, *args, **kwargs): what to do (e.g. if a non-deterministic machine returns more than one path, then the output is returned in list form). - - ``only_accepted`` -- (default: ``False``) a boolean. If set, + - ``only_accepted`` -- boolean (default: ``False``); if set, then the first argument in the output is guaranteed to be ``True`` (if the output is a list, then the first argument of each element will be ``True``). - - ``full_output`` -- (default: ``True``) a boolean. If set, + - ``full_output`` -- boolean (default: ``True``); if set, then the full output is given, otherwise only whether the sequence is accepted or not (the first entry below only). @@ -11625,24 +11325,21 @@ def process(self, *args, **kwargs): output (which is in form of a list) to something more readable. By default (``None``) identity is used here. - - ``check_epsilon_transitions`` -- (default: ``True``) a - boolean. If ``False``, then epsilon transitions are not - taken into consideration during process. + - ``check_epsilon_transitions`` -- boolean (default: ``True``); a + boolean. If ``False``, then epsilon transitions are not taken into + consideration during process. - - ``write_final_word_out`` -- (default: ``True``) a boolean - specifying whether the final output words should be written - or not. + - ``write_final_word_out`` -- boolean (default: ``True``); whether the + final output words should be written or not - - ``use_multitape_input`` -- (default: ``False``) a - boolean. If ``True``, then the multi-tape mode of the - process iterator is activated. See also the notes below for - multi-tape machines. + - ``use_multitape_input`` -- boolean (default: ``False``); if ``True``, + then the multi-tape mode of the process iterator is activated. See + also the notes below for multi-tape machines. - - ``process_all_prefixes_of_input`` -- (default: ``False``) a - boolean. If ``True``, then each prefix of the input word is - processed (instead of processing the whole input word at - once). Consequently, there is an output generated for each - of these prefixes. + - ``process_all_prefixes_of_input`` -- boolean (default: ``False``); if + ``True``, then each prefix of the input word is processed (instead of + processing the whole input word at once). Consequently, there is an + output generated for each of these prefixes. - ``process_iterator_class`` -- (default: ``None``) a class inherited from :class:`FSMProcessIterator`. If ``None``, @@ -11826,17 +11523,15 @@ def _process_convert_output_(self, output_data, **kwargs): INPUT: - - ``output_data`` -- a triple. + - ``output_data`` -- a triple - - ``full_output`` -- a boolean. + - ``full_output`` -- boolean - ``always_include_output`` -- if set (not by default), always return a triple containing the (non-existing) output. This is for compatibility with transducers. - OUTPUT: - - The converted output. + OUTPUT: the converted output TESTS:: @@ -12010,9 +11705,7 @@ def with_output(self, word_out_function=None): If this is ``None``, then the output word will be equal to the input word of each transition. - OUTPUT: - - A transducer. + OUTPUT: a transducer EXAMPLES:: @@ -12098,7 +11791,7 @@ def language(self, max_length=None, **kwargs): INPUT: - - ``max_length`` -- an integer or ``None`` (default). Only + - ``max_length`` -- integer or ``None`` (default). Only inputs of length at most ``max_length`` will be considered. If ``None``, then this iterates over all possible words without length restrictions. @@ -12107,9 +11800,7 @@ def language(self, max_length=None, **kwargs): iterator `. See :meth:`process` for a description. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -12148,7 +11839,7 @@ def language(self, max_length=None, **kwargs): def is_Transducer(FSM): """ - Tests whether or not ``FSM`` inherits from :class:`Transducer`. + Test whether or not ``FSM`` inherits from :class:`Transducer`. TESTS:: @@ -12210,16 +11901,10 @@ class Transducer(FiniteStateMachine): def _repr_(self): """ - Represents the transducer as "Transducer with n states" where + Represent the transducer as "Transducer with n states" where n is the number of states. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -12239,7 +11924,6 @@ def _repr_(self): 43 sage: T Transducer with 2 states - """ if not self._states_: return "Empty transducer" @@ -12259,9 +11943,7 @@ def _latex_transition_label_(self, transition, - ``format_function`` -- a function formatting the labels - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -12294,7 +11976,7 @@ def intersection(self, other, only_accessible_components=True): - ``other`` -- a transducer - - ``only_accessible_components`` -- If ``True`` (default), then + - ``only_accessible_components`` -- if ``True`` (default), then the result is piped through :meth:`.accessible_components`. If no ``new_input_alphabet`` is given, it is determined by :meth:`.determine_alphabets`. @@ -12417,7 +12099,7 @@ def cartesian_product(self, other, only_accessible_components=True): - ``other`` -- a finite state machine (if `d=2`) or a list (or other iterable) of `d-1` finite state machines - - ``only_accessible_components`` -- If ``True`` (default), then + - ``only_accessible_components`` -- if ``True`` (default), then the result is piped through :meth:`.accessible_components`. If no ``new_input_alphabet`` is given, it is determined by :meth:`.determine_alphabets`. @@ -12593,9 +12275,7 @@ def simplification(self): """ Return a simplified transducer. - OUTPUT: - - A new transducer. + OUTPUT: a new transducer This function simplifies a transducer by Moore's algorithm, first moving common output labels of transitions leaving a @@ -12709,15 +12389,15 @@ def process(self, *args, **kwargs): what to do (e.g. if a non-deterministic machine returns more than one path, then the output is returned in list form). - - ``only_accepted`` -- (default: ``False``) a boolean. If set, + - ``only_accepted`` -- boolean (default: ``False``); if set, then the first argument in the output is guaranteed to be ``True`` (if the output is a list, then the first argument of each element will be ``True``). - - ``full_output`` -- (default: ``True``) a boolean. If set, + - ``full_output`` -- boolean (default: ``True``); if set, then the full output is given, otherwise only the generated output (the third entry below only). If the input is not - accepted, a :class:`ValueError` is raised. + accepted, a :exc:`ValueError` is raised. - ``always_include_output`` -- if set (not by default), always include the output. This is inconsequential for a @@ -12729,35 +12409,31 @@ def process(self, *args, **kwargs): output (which is in form of a list) to something more readable. By default (``None``) identity is used here. - - ``check_epsilon_transitions`` -- (default: ``True``) a - boolean. If ``False``, then epsilon transitions are not - taken into consideration during process. + - ``check_epsilon_transitions`` -- boolean (default: ``True``); if + ``False``, then epsilon transitions are not taken into consideration + during process - - ``write_final_word_out`` -- (default: ``True``) a boolean - specifying whether the final output words should be written - or not. + - ``write_final_word_out`` -- boolean (default: ``True``); whether the + final output words should be written or not - - ``use_multitape_input`` -- (default: ``False``) a - boolean. If ``True``, then the multi-tape mode of the - process iterator is activated. See also the notes below for - multi-tape machines. + - ``use_multitape_input`` -- boolean (default: ``False``); if ``True``, + then the multi-tape mode of the process iterator is activated. See + also the notes below for multi-tape machines. - - ``process_all_prefixes_of_input`` -- (default: ``False``) a - boolean. If ``True``, then each prefix of the input word is - processed (instead of processing the whole input word at - once). Consequently, there is an output generated for each - of these prefixes. + - ``process_all_prefixes_of_input`` -- boolean (default: ``False``); if + ``True``, then each prefix of the input word is processed (instead of + processing the whole input word at once). Consequently, there is an + output generated for each of these prefixes. - ``process_iterator_class`` -- (default: ``None``) a class inherited from :class:`FSMProcessIterator`. If ``None``, then :class:`FSMProcessIterator` is taken. An instance of this class is created and is used during the processing. - - ``automatic_output_type`` -- (default: ``False``) a boolean - If set and the input has a parent, then the - output will have the same parent. If the input does not have - a parent, then the output will be of the same type as the - input. + - ``automatic_output_type`` -- boolean (default: ``False``); if set and + the input has a parent, then the output will have the same parent. If + the input does not have a parent, then the output will be of the same + type as the input. OUTPUT: @@ -13006,13 +12682,11 @@ def _process_convert_output_(self, output_data, **kwargs): INPUT: - - ``output_data`` -- a triple. + - ``output_data`` -- a triple - - ``full_output`` -- a boolean. + - ``full_output`` -- boolean - OUTPUT: - - The converted output. + OUTPUT: the converted output TESTS:: @@ -13047,29 +12721,27 @@ class _FSMTapeCache_(SageObject): INPUT: - - ``tape_cache_manager`` -- a list of the existing instances of - :class:`_FSMTapeCache_`. ``self`` will be appended to this list. + - ``tape_cache_manager`` -- list of the existing instances of + :class:`_FSMTapeCache_`. ``self`` will be appended to this list - - ``tape`` -- a tuple or list of the input tracks (iterables). + - ``tape`` -- tuple or list of the input tracks (iterables) - - ``tape_ended`` -- a list of booleans (one for each track of the + - ``tape_ended`` -- list of booleans (one for each track of the tape), which indicate whether the track iterator has already raised - a ``StopIteration`` exception. + a ``StopIteration`` exception - - ``position`` -- a tuple of pairs `(p, t)` marking the current + - ``position`` -- tuple of pairs `(p, t)` marking the current positions of each of the input tracks. There `p` is the number of letter read from track `t`. The pairs of ``position`` are sorted first by `p` (smallest first) and then by `t`, i.e., lexicographically. - - ``is_multitape`` -- If ``True`` each entry of the + - ``is_multitape`` -- if ``True`` each entry of the input-word-tuple of a transition is interpreted as word for the corresponding input track. If ``False`` input-words are interpreted as an iterable of letters. - OUTPUT: - - A tape-cache. + OUTPUT: a tape-cache TESTS:: @@ -13140,9 +12812,7 @@ def _repr_(self): """ Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string Note that this representation depends on the parameter ``is_multitape`` of ``self``. @@ -13198,11 +12868,9 @@ def deepcopy(self, memo=None): INPUT: - - ``memo`` -- a dictionary. + - ``memo`` -- dictionary - OUTPUT: - - An instance of ``_FSMCacheTape_``. + OUTPUT: an instance of ``_FSMCacheTape_`` TESTS:: @@ -13230,7 +12898,7 @@ def read(self, track_number): INPUT: - - ``track_number`` -- an integer. + - ``track_number`` -- integer OUTPUT: @@ -13286,12 +12954,10 @@ def finished(self, track_number=None): INPUT: - - ``track_number`` -- an integer or ``None``. If ``None``, - then ``True`` is returned if all tracks are finished. + - ``track_number`` -- integer or ``None`` (default); if ``None``, + then ``True`` is returned if all tracks are finished - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean TESTS:: @@ -13349,18 +13015,16 @@ def preview_word(self, track_number=None, length=1, return_word=False): INPUT: - - ``track_number`` -- an integer or ``None``. If ``None``, - then a tuple of words (one from each track) is returned. - - - ``length`` -- (default: ``1``) the length of the word(s). + - ``track_number`` -- integer (default: ``None``); if ``None``, + then a tuple of words (one from each track) is returned - - ``return_word`` -- (default: ``False``) a boolean. If set, - then a word is returned, otherwise a single letter (in which - case ``length`` has to be ``1``). + - ``length`` -- (default: ``1``) the length of the word(s) - OUTPUT: + - ``return_word`` -- boolean (default: ``False``); if set, then a word + is returned, otherwise a single letter (in which case ``length`` has + to be ``1``) - A single letter or a word. + OUTPUT: a single letter or a word A :python:`RuntimeError` is thrown if the tape (at least one track) has reached its end. @@ -13450,13 +13114,11 @@ def compare_to_tape(self, track_number, word): INPUT: - - ``track_number`` -- an integer. + - ``track_number`` -- integer - - ``word`` -- a tuple or list of letters. - - OUTPUT: + - ``word`` -- tuple or list of letters - ``True`` or ``False`` + OUTPUT: boolean TESTS:: @@ -13499,11 +13161,9 @@ def forward(self, transition): INPUT: - - ``transition`` -- a transition of a finite state machine. + - ``transition`` -- a transition of a finite state machine - OUTPUT: - - Nothing. + OUTPUT: nothing If ``self.is_multitape`` is ``False``, then this function forwards ``self`` (track `0`) by the number of entries of @@ -13573,16 +13233,14 @@ def length(word): def transition_possible(self, transition): """ - Tests whether the input word of ``transition`` can be read + Test whether the input word of ``transition`` can be read from the tape. INPUT: - - ``transition`` -- a transition of a finite state machine. + - ``transition`` -- a transition of a finite state machine - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean TESTS:: @@ -13622,11 +13280,9 @@ def _transition_possible_epsilon_(self, word_in): INPUT: - - ``word_in`` -- an input word of a transition. - - OUTPUT: + - ``word_in`` -- an input word of a transition - ``True`` or ``False``. + OUTPUT: boolean TESTS:: @@ -13654,11 +13310,9 @@ def _transition_possible_test_(self, word_in): INPUT: - - ``word_in`` -- an input word of a transition. - - OUTPUT: + - ``word_in`` -- an input word of a transition - ``True`` or ``False``. + OUTPUT: boolean This method is usually overridden in inherited classes, cf. :class:`_FSMTapeCacheDetectEpsilon_` and @@ -13750,11 +13404,9 @@ def _transition_possible_test_(self, word_in): INPUT: - - ``word_in`` -- an input word of a transition. - - OUTPUT: + - ``word_in`` -- an input word of a transition - ``True`` or ``False``. + OUTPUT: boolean TESTS:: @@ -13791,13 +13443,11 @@ def compare_to_tape(self, track_number, word): INPUT: - - ``track_number`` -- an integer. + - ``track_number`` -- integer - - ``word`` -- a tuple or list of letters. Only its length is used. + - ``word`` -- tuple or list of letters; only its length is used - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean Note that this method usually returns ``True``. ``False`` can only be returned at the end of the input tape. @@ -13843,11 +13493,9 @@ def tupleofwords_to_wordoftuples(tupleofwords): INPUT: - - ``tupleofwords`` -- a tuple of a list of letters. - - OUTPUT: + - ``tupleofwords`` -- tuple of a list of letters - A list of tuples. + OUTPUT: list of tuples Missing letters in the words are padded with the letter ``None`` (from the empty word). @@ -13869,11 +13517,9 @@ def wordoftuples_to_tupleofwords(wordoftuples): INPUT: - - ``wordoftuples`` -- a list of tuples of letters. - - OUTPUT: + - ``wordoftuples`` -- list of tuples of letters - A tuple of lists. + OUTPUT: a tuple of lists Letters ``None`` (empty word) are removed from each word in the output. @@ -13899,7 +13545,7 @@ def remove_empty_letters(word): def is_FSMProcessIterator(PI): """ - Tests whether or not ``PI`` inherits from :class:`FSMProcessIterator`. + Test whether or not ``PI`` inherits from :class:`FSMProcessIterator`. TESTS:: @@ -13927,7 +13573,7 @@ class FSMProcessIterator(SageObject, Iterator): INPUT: - ``fsm`` -- the finite state machine on which the input should be - processed. + processed - ``input_tape`` -- the input tape can be a list or an iterable with entries from the input alphabet. If we are @@ -13948,28 +13594,23 @@ class FSMProcessIterator(SageObject, Iterator): output (which is in form of a list) to something more readable. By default (``None``) identity is used here. - - ``check_epsilon_transitions`` -- (default: ``True``) a - boolean. If ``False``, then epsilon transitions are not - taken into consideration during process. + - ``check_epsilon_transitions`` -- boolean (default: ``True``); if + ``False``, then epsilon transitions are not taken into consideration + during process - - ``write_final_word_out`` -- (default: ``True``) a boolean - specifying whether the final output words should be written - or not. + - ``write_final_word_out`` -- boolean (default: ``True``); whether the + final output words should be written or not - - ``use_multitape_input`` -- (default: ``False``) a - boolean. If ``True``, then the multi-tape mode of the - process iterator is activated. See also the notes below for - multi-tape machines. + - ``use_multitape_input`` -- boolean (default: ``False``); if ``True``, + then the multi-tape mode of the process iterator is activated. See also + the notes below for multi-tape machines. - - ``process_all_prefixes_of_input`` -- (default: ``False``) a - boolean. If ``True``, then each prefix of the input word is - processed (instead of processing the whole input word at - once). Consequently, there is an output generated for each - of these prefixes. + - ``process_all_prefixes_of_input`` -- boolean (default: ``False``); if + ``True``, then each prefix of the input word is processed (instead of + processing the whole input word at once). Consequently, there is an + output generated for each of these prefixes. - OUTPUT: - - An iterator. + OUTPUT: an iterator In its simplest form, it behaves like an iterator which, in each step, goes from one state to another. To decide which way @@ -14173,9 +13814,7 @@ def __repr__(self): """ Return a nice representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -14313,17 +13952,15 @@ def _push_branch_(self, state, tape_cache, outputs): INPUT: - - ``state`` -- state which has to be processed. + - ``state`` -- state which has to be processed - ``tape_cache`` -- an instance of :class:`_FSMTapeCache_` (storing - information what to read next). + information what to read next) - - ``outputs`` -- a list of output tapes on each of which words - were written until reaching ``state``. - - OUTPUT: + - ``outputs`` -- list of output tapes on each of which words + were written until reaching ``state`` - Nothing. + OUTPUT: nothing .. NOTE:: @@ -14376,7 +14013,6 @@ def _push_branch_(self, state, tape_cache, outputs): sage: T.process([0, 0, 0], format_output=lambda o: ''.join(o)) [(True, 3, 'a:)'), (True, 3, 'd:)'), (True, 3, 'e:)'), (True, 3, 'i:)'), (True, 3, 'l:)'), (True, 3, 'n:)')] - """ import heapq @@ -14407,17 +14043,15 @@ def _push_branches_(self, state, tape_cache, outputs): INPUT: - ``state`` -- state which has to be processed (i.e., the - current state, this branch is in). + current state, this branch is in) - ``tape_cache`` -- an instance of :class:`_FSMTapeCache_` (storing - information what to read next). - - - ``outputs`` -- a list of output tapes on each of which words - were written until reaching ``state``. + information what to read next) - OUTPUT: + - ``outputs`` -- list of output tapes on each of which words + were written until reaching ``state`` - Nothing. + OUTPUT: nothing When this function is called, a branch is updated, which means, stored for further processing. If the state has epsilon @@ -14483,10 +14117,6 @@ def __next__(self): """ Makes one step in processing the input tape. - INPUT: - - Nothing. - OUTPUT: It returns the current status of the iterator (see below). A @@ -14720,18 +14350,16 @@ def preview_word(self, track_number=None, length=1, return_word=False): INPUT: - - ``track_number`` -- an integer or ``None``. If ``None``, - then a tuple of words (one from each track) is returned. - - - ``length`` -- (default: ``1``) the length of the word(s). + - ``track_number`` -- integer (default: ``None``); if ``None``, then + a tuple of words (one from each track) is returned - - ``return_word`` -- (default: ``False``) a boolean. If set, - then a word is returned, otherwise a single letter (in which - case ``length`` has to be ``1``). + - ``length`` -- (default: ``1``) the length of the word(s) - OUTPUT: + - ``return_word`` -- boolean (default: ``False``); if set, then a word + is returned, otherwise a single letter (in which case ``length`` has + to be ``1``) - A single letter or a word. + OUTPUT: a single letter or a word An exception ``StopIteration`` is thrown if the tape (at least one track) has reached its end. @@ -15101,17 +14729,15 @@ def _push_branch_(self, state, tape_cache, outputs): INPUT: - - ``state`` -- state which has to be processed. + - ``state`` -- state which has to be processed - ``tape_cache`` -- an instance of :class:`_FSMTapeCache_` (storing - information what to read next). + information what to read next) - - ``outputs`` -- a list of output tapes on each of which words - were written until reaching ``state``. - - OUTPUT: + - ``outputs`` -- list of output tapes on each of which words + were written until reaching ``state`` - Nothing. + OUTPUT: nothing TESTS:: diff --git a/src/sage/combinat/finite_state_machine_generators.py b/src/sage/combinat/finite_state_machine_generators.py index ae708a195ca..a43391ef509 100644 --- a/src/sage/combinat/finite_state_machine_generators.py +++ b/src/sage/combinat/finite_state_machine_generators.py @@ -39,19 +39,19 @@ :widths: 30, 70 :delim: | - :meth:`~TransducerGenerators.Identity` | Returns a transducer realizing the identity map. - :meth:`~TransducerGenerators.abs` | Returns a transducer realizing absolute value. - :meth:`~TransducerGenerators.map` | Returns a transducer realizing a function. - :meth:`~TransducerGenerators.operator` | Returns a transducer realizing a binary operation. - :meth:`~TransducerGenerators.all` | Returns a transducer realizing logical ``and``. - :meth:`~TransducerGenerators.any` | Returns a transducer realizing logical ``or``. - :meth:`~TransducerGenerators.add` | Returns a transducer realizing addition. - :meth:`~TransducerGenerators.sub` | Returns a transducer realizing subtraction. - :meth:`~TransducerGenerators.CountSubblockOccurrences` | Returns a transducer counting the occurrences of a subblock. - :meth:`~TransducerGenerators.Wait` | Returns a transducer writing ``False`` until first (or k-th) true input is read. - :meth:`~TransducerGenerators.weight` | Returns a transducer realizing the Hamming weight. - :meth:`~TransducerGenerators.GrayCode` | Returns a transducer realizing binary Gray code. - :meth:`~TransducerGenerators.Recursion` | Returns a transducer defined by recursions. + :meth:`~TransducerGenerators.Identity` | Return a transducer realizing the identity map. + :meth:`~TransducerGenerators.abs` | Return a transducer realizing absolute value. + :meth:`~TransducerGenerators.map` | Return a transducer realizing a function. + :meth:`~TransducerGenerators.operator` | Return a transducer realizing a binary operation. + :meth:`~TransducerGenerators.all` | Return a transducer realizing logical ``and``. + :meth:`~TransducerGenerators.any` | Return a transducer realizing logical ``or``. + :meth:`~TransducerGenerators.add` | Return a transducer realizing addition. + :meth:`~TransducerGenerators.sub` | Return a transducer realizing subtraction. + :meth:`~TransducerGenerators.CountSubblockOccurrences` | Return a transducer counting the occurrences of a subblock. + :meth:`~TransducerGenerators.Wait` | Return a transducer writing ``False`` until first (or `k`-th) true input is read. + :meth:`~TransducerGenerators.weight` | Return a transducer realizing the Hamming weight. + :meth:`~TransducerGenerators.GrayCode` | Return a transducer realizing binary Gray code. + :meth:`~TransducerGenerators.Recursion` | Return a transducer defined by recursions. AUTHORS: @@ -120,11 +120,9 @@ def AnyLetter(self, input_alphabet): INPUT: - - ``input_alphabet`` -- a list, the input alphabet + - ``input_alphabet`` -- list; the input alphabet - OUTPUT: - - An :class:`~Automaton`. + OUTPUT: an :class:`~Automaton` EXAMPLES:: @@ -155,11 +153,9 @@ def AnyWord(self, input_alphabet): INPUT: - - ``input_alphabet`` -- a list, the input alphabet - - OUTPUT: + - ``input_alphabet`` -- list; the input alphabet - An :class:`~Automaton`. + OUTPUT: an :class:`~Automaton` EXAMPLES:: @@ -197,12 +193,9 @@ def EmptyWord(self, input_alphabet=None): INPUT: - - ``input_alphabet`` -- (default: ``None``) an iterable - or ``None``. - - OUTPUT: + - ``input_alphabet`` -- iterable or ``None`` (default: ``None``) - An :class:`~Automaton`. + OUTPUT: an :class:`~Automaton` EXAMPLES:: @@ -228,14 +221,12 @@ def Word(self, word, input_alphabet=None): INPUT: - - ``word`` -- an iterable. + - ``word`` -- an iterable - - ``input_alphabet`` -- a list or ``None``. If ``None``, - then the letters occurring in the word are used. + - ``input_alphabet`` -- list or ``None``; if ``None``, + then the letters occurring in the word are used - OUTPUT: - - An :class:`~Automaton`. + OUTPUT: an :class:`~Automaton` EXAMPLES:: @@ -288,15 +279,13 @@ def ContainsWord(self, word, input_alphabet): INPUT: - - ``word`` -- a list (or other iterable) of letters, the - word we are looking for. + - ``word`` -- list (or other iterable) of letters; the + word we are looking for - - ``input_alphabet`` -- a list or other iterable, the input - alphabet. + - ``input_alphabet`` -- list or other iterable; the input + alphabet - OUTPUT: - - An :class:`~Automaton`. + OUTPUT: an :class:`~Automaton` EXAMPLES:: @@ -370,16 +359,14 @@ class TransducerGenerators: def Identity(self, input_alphabet): """ - Returns the identity transducer realizing the identity map. + Return the identity transducer realizing the identity map. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - OUTPUT: - - A transducer mapping each word over ``input_alphabet`` to - itself. + OUTPUT: a transducer mapping each word over ``input_alphabet`` to + itself EXAMPLES:: @@ -397,7 +384,6 @@ def Identity(self, input_alphabet): [0, 1] sage: T([0, 1, 0, 1, 1]) [0, 1, 0, 1, 1] - """ return Transducer( [(0, 0, d, d) for d in input_alphabet], @@ -408,14 +394,14 @@ def Identity(self, input_alphabet): def CountSubblockOccurrences(self, block, input_alphabet): r""" - Returns a transducer counting the number of (possibly + Return a transducer counting the number of (possibly overlapping) occurrences of a block in the input. INPUT: - - ``block`` -- a list (or other iterable) of letters. + - ``block`` -- list (or other iterable) of letters - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable OUTPUT: @@ -533,10 +519,10 @@ def Wait(self, input_alphabet, threshold=1): INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - - ``threshold`` -- a positive integer specifying how many - occurrences of ``True`` inputs are waited for. + - ``threshold`` -- positive integer specifying how many + occurrences of ``True`` inputs are waited for OUTPUT: @@ -576,9 +562,9 @@ def map(self, f, input_alphabet): INPUT: - - ``f`` -- function to realize. + - ``f`` -- function to realize - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable OUTPUT: @@ -616,19 +602,19 @@ def map(self, f, input_alphabet): def operator(self, operator, input_alphabet, number_of_operands=2): r""" - Returns a transducer which realizes an operation + Return a transducer which realizes an operation on tuples over the given input alphabet. INPUT: - - ``operator`` -- operator to realize. It is a function which + - ``operator`` -- operator to realize; it is a function which takes ``number_of_operands`` input arguments (each out of - ``input_alphabet``). + ``input_alphabet``) - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - ``number_of_operands`` -- (default: `2`) it specifies the number - of input arguments the operator takes. + of input arguments the operator takes OUTPUT: @@ -642,7 +628,7 @@ def operator(self, operator, input_alphabet, number_of_operands=2): EXAMPLES: The following binary transducer realizes component-wise - addition (this transducer is also available as :meth:`.add`):: + addition (this transducer is also available as :meth:`add`):: sage: import operator sage: T = transducers.operator(operator.add, [0, 1]) @@ -698,15 +684,15 @@ def transition_function(state, operands): def all(self, input_alphabet, number_of_operands=2): r""" - Returns a transducer which realizes logical ``and`` over the given + Return a transducer which realizes logical ``and`` over the given input alphabet. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - ``number_of_operands`` -- (default: `2`) specifies the number - of input arguments for the ``and`` operation. + of input arguments for the ``and`` operation OUTPUT: @@ -749,15 +735,15 @@ def all(self, input_alphabet, number_of_operands=2): def any(self, input_alphabet, number_of_operands=2): r""" - Returns a transducer which realizes logical ``or`` over the given + Return a transducer which realizes logical ``or`` over the given input alphabet. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - ``number_of_operands`` -- (default: `2`) specifies the number - of input arguments for the ``or`` operation. + of input arguments for the ``or`` operation OUTPUT: @@ -800,15 +786,15 @@ def any(self, input_alphabet, number_of_operands=2): def add(self, input_alphabet, number_of_operands=2): r""" - Returns a transducer which realizes addition on pairs over the + Return a transducer which realizes addition on pairs over the given input alphabet. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - ``number_of_operands`` -- (default: `2`) it specifies the number - of input arguments the operator takes. + of input arguments the operator takes OUTPUT: @@ -854,12 +840,12 @@ def add(self, input_alphabet, number_of_operands=2): def sub(self, input_alphabet): r""" - Returns a transducer which realizes subtraction on pairs over + Return a transducer which realizes subtraction on pairs over the given input alphabet. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable OUTPUT: @@ -893,12 +879,12 @@ def sub(self, input_alphabet): def weight(self, input_alphabet, zero=0): r""" - Returns a transducer which realizes the Hamming weight of the input + Return a transducer which realizes the Hamming weight of the input over the given input alphabet. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable - ``zero`` -- the zero symbol in the alphabet used @@ -906,7 +892,7 @@ def weight(self, input_alphabet, zero=0): A transducer mapping `i_0\ldots i_k` to `(i_0\neq 0)\ldots(i_k\neq 0)`. - The Hamming weight is defined as the number of non-zero digits in the + The Hamming weight is defined as the number of nonzero digits in the input sequence over the alphabet ``input_alphabet`` (see :wikipedia:`Hamming_weight`). The output sequence of the transducer is a unary encoding of the Hamming weight. Thus the sum of the output @@ -959,12 +945,12 @@ def weight(state, input): def abs(self, input_alphabet): r""" - Returns a transducer which realizes the letter-wise + Return a transducer which realizes the letter-wise absolute value of an input word over the given input alphabet. INPUT: - - ``input_alphabet`` -- a list or other iterable. + - ``input_alphabet`` -- list or other iterable OUTPUT: @@ -987,22 +973,15 @@ def abs(self, input_alphabet): [0] sage: T([-1, -1, 0, 1]) [1, 1, 0, 1] - """ return self.map(abs, input_alphabet) def GrayCode(self): """ - Returns a transducer converting the standard binary + Return a transducer converting the standard binary expansion to Gray code. - INPUT: - - Nothing. - - OUTPUT: - - A transducer. + OUTPUT: a transducer Cf. the :wikipedia:`Gray_code` for a description of the Gray code. @@ -1052,24 +1031,24 @@ def _parse_recursion_equation_(self, equation, base, function, var, INPUT: - - ``equation`` -- An equation of the form + - ``equation`` -- an equation of the form - ``f(base^K * n + r) == f(base^k * n + s) + t`` for some integers ``0 <= k < K``, ``r`` and some ``t``---valid for all ``n`` such that the arguments on both sides are - non-negative--- + nonnegative--- or the form - ``f(r) == t`` for some integer ``r`` and some ``t``. - - ``base`` -- see :meth:`~Recursion`. + - ``base`` -- see :meth:`~Recursion` - - ``function`` -- see :meth:`~Recursion`. + - ``function`` -- see :meth:`~Recursion` - - ``var`` -- see :meth:`~Recursion`. + - ``var`` -- see :meth:`~Recursion` - - ``output_rings`` -- see :meth:`~Recursion`. + - ``output_rings`` -- see :meth:`~Recursion` OUTPUT: @@ -1373,7 +1352,7 @@ def Recursion(self, recursions, base, function=None, var=None, - ``f(base^K * n + r) == f(base^k * n + s) + t`` for some integers ``0 <= k < K``, ``r`` and some ``t``---valid for all ``n`` such that the arguments on both sides are - non-negative--- + nonnegative--- or the form @@ -1384,12 +1363,12 @@ def Recursion(self, recursions, base, function=None, var=None, ``r``, ``k``, ``s``, ``t`` as above or a tuple ``(r, t)``. Note that ``t`` *must* be a list in this case. - - ``base`` -- base of the digit expansion. + - ``base`` -- base of the digit expansion - ``function`` -- symbolic function ``f`` occurring in the - recursions. + recursions - - ``var`` -- symbolic variable. + - ``var`` -- symbolic variable - ``input_alphabet`` -- (default: ``None``) a list of digits to be used as the input alphabet. If ``None`` and the base @@ -1405,9 +1384,9 @@ def Recursion(self, recursions, base, function=None, var=None, - ``is_zero`` -- (default: ``None``) a callable. The recursion relations are only well-posed if there is no cycle with - non-zero output and input consisting of zeros. This parameter + nonzero output and input consisting of zeros. This parameter is used to determine whether the output of such a cycle is - non-zero. By default, the output must evaluate to ``False`` as + nonzero. By default, the output must evaluate to ``False`` as a boolean. - ``output_rings`` -- (default: ``[ZZ, QQ]``) a list of @@ -1416,9 +1395,7 @@ def Recursion(self, recursions, base, function=None, var=None, contained in any ring, they remain in whatever ring they are after parsing the recursions, typically the symbolic ring. - OUTPUT: - - A transducer ``T``. + OUTPUT: a transducer ``T`` The transducer is constructed such that ``T(expansion) == f(n)`` if ``expansion`` is the digit expansion of ``n`` to the base @@ -1515,7 +1492,7 @@ def Recursion(self, recursions, base, function=None, var=None, sage: sum(T(binary_expansion)) # needs sage.symbolic 3 - Indeed, the given non-adjacent form has three non-zero + Indeed, the given non-adjacent form has three nonzero digits. - The following example computes the non-adjacent form from the @@ -1856,13 +1833,13 @@ def recursion_transition(carry, level, force_nonnegative_target): INPUT: - - ``carry`` -- integer. + - ``carry`` -- integer - - ``level`` -- integer. + - ``level`` -- integer - - ``force_nonnegative_target`` -- boolean. If ``True``, only - recursion transitions leading to a non-negative carry are - returned. + - ``force_nonnegative_target`` -- boolean; if ``True``, only + recursion transitions leading to a nonnegative carry are + returned OUTPUT: @@ -1895,13 +1872,13 @@ def recursion_transitions(carry, level, force_nonnegative_target): INPUT: - - ``carry`` -- integer. + - ``carry`` -- integer - - ``level`` -- integer. + - ``level`` -- integer - - ``force_nonnegative_target`` -- boolean. If ``True``, only - recursion transitions leading to a non-negative carry are - allowed. + - ``force_nonnegative_target`` -- boolean; if ``True``, only + recursion transitions leading to a nonnegative carry are + allowed OUTPUT: @@ -1928,7 +1905,7 @@ def transition_function(states2, input): carry += input * base**level level += 1 # We now may proceed along recursion transitions - # as long as the carries stay non-negative. + # as long as the carries stay nonnegative. ((carry, level), new_output) = recursion_transitions( carry, level, True) return ((carry, level), output + new_output) @@ -1943,7 +1920,7 @@ def edge_recursion_digraph(n): INPUT: - - ``n`` -- integer. + - ``n`` -- integer OUTPUT: diff --git a/src/sage/combinat/fqsym.py b/src/sage/combinat/fqsym.py index a3898280fc6..e92c6fba45e 100644 --- a/src/sage/combinat/fqsym.py +++ b/src/sage/combinat/fqsym.py @@ -55,7 +55,7 @@ def __init__(self, alg): CombinatorialFreeModule.__init__(self, alg.base_ring(), Permutations(), category=FQSymBases(alg), - bracket="", prefix=self._prefix) + bracket='', prefix=self._prefix) def _coerce_map_from_(self, R): r""" @@ -800,9 +800,7 @@ def _G_to_F_on_basis(self, w): - ``w`` -- a permutation - OUTPUT: - - - An element of the F basis + OUTPUT: an element of the F basis TESTS:: @@ -832,9 +830,7 @@ def _F_to_G_on_basis(self, w): - ``w`` -- a permutation - OUTPUT: - - - An element of the G basis + OUTPUT: an element of the G basis TESTS:: @@ -911,10 +907,10 @@ def __init__(self, alg): F = self.realization_of().F() phi = F.module_morphism(self._F_to_M_on_basis, codomain=self, - unitriangular="lower") + unitriangular='lower') phi.register_as_coercion() phi_i = self.module_morphism(self._M_to_F_on_basis, codomain=F, - unitriangular="lower") + unitriangular='lower') phi_i.register_as_coercion() def _element_constructor_(self, x): @@ -1018,9 +1014,7 @@ def _F_to_M_on_basis(self, w): - ``w`` -- a permutation - OUTPUT: - - - An element of the M basis + OUTPUT: an element of the M basis TESTS:: @@ -1047,9 +1041,7 @@ def _M_to_F_on_basis(self, w): - ``w`` -- a permutation - OUTPUT: - - - An element of the F basis + OUTPUT: an element of the F basis ALGORITHM: @@ -1238,7 +1230,7 @@ class FQSymBases(Category_realization_of_parent): def __init__(self, base): r""" - Initialize the bases of an `FQSym` + Initialize the bases of an `FQSym`. INPUT: diff --git a/src/sage/combinat/free_dendriform_algebra.py b/src/sage/combinat/free_dendriform_algebra.py index 900b9a7ca5d..2acfee1b337 100644 --- a/src/sage/combinat/free_dendriform_algebra.py +++ b/src/sage/combinat/free_dendriform_algebra.py @@ -180,7 +180,7 @@ def __init__(self, R, names=None): cat = HopfAlgebras(R).WithBasis().Graded().Connected() CombinatorialFreeModule.__init__(self, R, Trees, - latex_prefix="", + latex_prefix='', sorting_key=key, category=cat) @@ -224,11 +224,11 @@ def _repr_(self): def gen(self, i): r""" - Return the ``i``-th generator of the algebra. + Return the `i`-th generator of the algebra. INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: diff --git a/src/sage/combinat/free_module.py b/src/sage/combinat/free_module.py index 290bdf4a8dc..639cec54ae4 100644 --- a/src/sage/combinat/free_module.py +++ b/src/sage/combinat/free_module.py @@ -35,13 +35,13 @@ class CombinatorialFreeModule(UniqueRepresentation, Module, IndexedGenerators): r""" - Class for free modules with a named basis + Class for free modules with a named basis. INPUT: - ``R`` -- base ring - - ``basis_keys`` -- list, tuple, family, set, etc. defining the + - ``basis_keys`` -- list; tuple, family, set, etc. defining the indexing set for the basis of this module - ``element_class`` -- the class of which elements of this module @@ -226,8 +226,8 @@ class CombinatorialFreeModule(UniqueRepresentation, Module, IndexedGenerators): involves comparison by equality (not identity). Hence, the last line of the following example used to fail with an assertion error:: - sage: F = CombinatorialFreeModule(ZZ, [1,2,3], prefix="F") - sage: G = CombinatorialFreeModule(ZZ, [1,2,3,4], prefix="G") + sage: F = CombinatorialFreeModule(ZZ, [1,2,3], prefix='F') + sage: G = CombinatorialFreeModule(ZZ, [1,2,3,4], prefix='G') sage: f = F.monomial(1) + 2 * F.monomial(2) sage: g = 2*G.monomial(3) + G.monomial(4) sage: tensor([f, g]) @@ -261,7 +261,7 @@ class CombinatorialFreeModule(UniqueRepresentation, Module, IndexedGenerators): We check that issue :issue:`28681` is fixed:: - sage: F = CombinatorialFreeModule(ZZ, ZZ); F.rename("F") + sage: F = CombinatorialFreeModule(ZZ, ZZ); F.rename('F') sage: FF = tensor((F,F)) sage: cartesian_product((FF,FF)) F # F (+) F # F @@ -337,7 +337,7 @@ def __classcall_private__(cls, base_ring, basis_keys=None, category=None, @lazy_attribute def element_class(self): """ - The (default) class for the elements of this parent + The (default) class for the elements of this parent. Overrides :meth:`Parent.element_class` to force the construction of Python class. This is currently needed to @@ -467,7 +467,7 @@ def __init__(self, R, basis_keys=None, element_class=None, category=None, def construction(self): """ - The construction functor and base ring for self. + The construction functor and base ring for ``self``. EXAMPLES:: @@ -694,8 +694,8 @@ def _element_constructor_(self, x): A coercion between free modules with the same indices exists whenever a coercion map is defined between their base rings:: - sage: F = CombinatorialFreeModule(ZZ, ["a", "b"]); F.rename("F") - sage: G = CombinatorialFreeModule(QQ, ["a", "b"]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, ["a", "b"]); F.rename('F') + sage: G = CombinatorialFreeModule(QQ, ["a", "b"]); G.rename('G') sage: G(F.monomial("a")) B['a'] sage: G(-3*F.monomial("a")) @@ -703,7 +703,7 @@ def _element_constructor_(self, x): Otherwise, there is no conversion between distinct free modules:: - sage: H = CombinatorialFreeModule(ZZ, ["a", "b", "c"]); H.rename("H") + sage: H = CombinatorialFreeModule(ZZ, ["a", "b", "c"]); H.rename('H') sage: H(F.monomial("a")) Traceback (most recent call last): ... @@ -720,7 +720,7 @@ def _element_constructor_(self, x): The following originally used to yield ``p[[2]] # p[[2]]``, and if there was no natural coercion between ``s`` and ``p``, this would - raise a :class:`NotImplementedError`. + raise a :exc:`NotImplementedError`. Since :issue:`15305`, this takes the coercion between ``s`` and ``p`` and lifts it to the tensor product. :: @@ -923,7 +923,7 @@ def set_order(self, order): Set the order of the elements of the basis. If :meth:`set_order` has not been called, then the ordering is - the one used in the generation of the elements of self's + the one used in the generation of the elements of ``self``'s associated enumerated set. .. WARNING:: @@ -1158,8 +1158,8 @@ def sum_of_terms(self, terms, distinct=False): INPUT: - - ``terms`` -- a list (or iterable) of pairs ``(index, coeff)`` - - ``distinct`` -- (default: ``False``) whether the indices are + - ``terms`` -- list (or iterable) of pairs ``(index, coeff)`` + - ``distinct`` -- boolean (default: ``False``); whether the indices are guaranteed to be distinct EXAMPLES:: @@ -1208,14 +1208,14 @@ def _from_dict(self, d, coerce=False, remove_zeros=True): INPUT: - - ``d`` -- a dictionary ``{index: coeff}`` where each ``index`` is + - ``d`` -- dictionary ``{index: coeff}`` where each ``index`` is the index of a basis element and each ``coeff`` belongs to the coefficient ring ``self.base_ring()`` - - ``coerce`` -- a boolean (default: ``False``), whether to coerce + - ``coerce`` -- boolean (default: ``False``); whether to coerce the coefficients ``coeff`` to the coefficient ring - - ``remove_zeros`` -- a boolean (default: ``True``), if some + - ``remove_zeros`` -- boolean (default: ``True``); if some coefficients ``coeff`` may be zero and should therefore be removed EXAMPLES:: @@ -1264,14 +1264,14 @@ def _from_dict(self, d, coerce=False, remove_zeros=True): class CombinatorialFreeModule_Tensor(CombinatorialFreeModule): """ - Tensor Product of Free Modules + Tensor Product of Free Modules. EXAMPLES: We construct two free modules, assign them short names, and construct their tensor product:: - sage: F = CombinatorialFreeModule(ZZ, [1,2]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [3,4]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, [1,2]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [3,4]); G.rename('G') sage: T = tensor([F, G]); T F # G @@ -1306,7 +1306,7 @@ class CombinatorialFreeModule_Tensor(CombinatorialFreeModule): The tensor product is associative and flattens sub tensor products:: - sage: H = CombinatorialFreeModule(ZZ, [5,6]); H.rename("H") + sage: H = CombinatorialFreeModule(ZZ, [5,6]); H.rename('H') sage: tensor([F, tensor([G, H])]) F # G # H sage: tensor([tensor([F, G]), H]) @@ -1396,8 +1396,8 @@ def _repr_(self): sage: F = CombinatorialFreeModule(ZZ, [1,2,3]) sage: G = CombinatorialFreeModule(ZZ, [1,2,3,8]) - sage: F.rename("F") - sage: G.rename("G") + sage: F.rename('F') + sage: G.rename('G') sage: T = tensor([F, G]) sage: T # indirect doctest F # G @@ -1426,9 +1426,9 @@ def tensor_factors(self): EXAMPLES:: sage: F = CombinatorialFreeModule(ZZ, [1,2]) - sage: F.rename("F") + sage: F.rename('F') sage: G = CombinatorialFreeModule(ZZ, [3,4]) - sage: G.rename("G") + sage: G.rename('G') sage: T = tensor([F, G]); T F # G sage: T.tensor_factors() @@ -1441,7 +1441,7 @@ def _ascii_art_(self, term): TESTS:: sage: R = NonCommutativeSymmetricFunctions(QQ).R() # needs sage.combinat - sage: Partitions.options(diagram_str="#", convention="french") # needs sage.combinat + sage: Partitions.options(diagram_str='#', convention='french') # needs sage.combinat sage: s = ascii_art(tensor((R[1,2], R[3,1,2]))); s # needs sage.combinat R # R # ### @@ -1470,7 +1470,7 @@ def _unicode_art_(self, term): TESTS:: sage: R = NonCommutativeSymmetricFunctions(QQ).R() # needs sage.combinat - sage: Partitions.options(diagram_str="#", convention="french") # needs sage.combinat + sage: Partitions.options(diagram_str='#', convention='french') # needs sage.combinat sage: s = unicode_art(tensor((R[1,2], R[3,1,2]))); s # needs sage.combinat R ⊗ R ┌┐ ┌┬┬┐ @@ -1501,8 +1501,8 @@ def _latex_(self): sage: F = CombinatorialFreeModule(ZZ, [1,2,3]) sage: G = CombinatorialFreeModule(ZZ, [1,2,3,8]) - sage: F.rename("F") - sage: G.rename("G") + sage: F.rename('F') + sage: G.rename('G') sage: latex(tensor([F, F, G])) # indirect doctest \text{\texttt{F}} \otimes \text{\texttt{F}} \otimes \text{\texttt{G}} sage: F._latex_ = lambda : "F" @@ -1518,8 +1518,8 @@ def _repr_term(self, term): """ TESTS:: - sage: F = CombinatorialFreeModule(ZZ, [1,2,3], prefix="F") - sage: G = CombinatorialFreeModule(ZZ, [1,2,3,4], prefix="G") + sage: F = CombinatorialFreeModule(ZZ, [1,2,3], prefix='F') + sage: G = CombinatorialFreeModule(ZZ, [1,2,3,4], prefix='G') sage: f = F.monomial(1) + 2 * F.monomial(2) sage: g = 2*G.monomial(3) + G.monomial(4) sage: tensor([f, g]) # indirect doctest @@ -1552,17 +1552,17 @@ def tensor_constructor(self, modules): r""" INPUT: - - ``modules`` -- a tuple `(F_1,\dots,F_n)` of - free modules whose tensor product is self + - ``modules`` -- tuple `(F_1,\dots,F_n)` of + free modules whose tensor product is self Returns the canonical multilinear morphism from `F_1 \times \dots \times F_n` to `F_1 \otimes \dots \otimes F_n` EXAMPLES:: - sage: F = CombinatorialFreeModule(ZZ, [1,2]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [3,4]); G.rename("G") - sage: H = CombinatorialFreeModule(ZZ, [5,6]); H.rename("H") + sage: F = CombinatorialFreeModule(ZZ, [1,2]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [3,4]); G.rename('G') + sage: H = CombinatorialFreeModule(ZZ, [5,6]); H.rename('H') sage: f = F.monomial(1) + 2*F.monomial(2) sage: g = 2*G.monomial(3) + G.monomial(4) @@ -1599,14 +1599,14 @@ def tensor_constructor(self, modules): def _tensor_of_elements(self, elements): """ - Returns the tensor product of the specified elements. + Return the tensor product of the specified elements. The result should be in ``self``. EXAMPLES:: - sage: F = CombinatorialFreeModule(ZZ, [1,2]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [3,4]); G.rename("G") - sage: H = CombinatorialFreeModule(ZZ, [5,6]); H.rename("H") + sage: F = CombinatorialFreeModule(ZZ, [1,2]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [3,4]); G.rename('G') + sage: H = CombinatorialFreeModule(ZZ, [5,6]); H.rename('H') sage: f = F.monomial(1) + 2 * F.monomial(2) sage: g = 2*G.monomial(3) + G.monomial(4) @@ -1702,17 +1702,16 @@ def __init__(self, flatten): """ INPUT: - - ``flatten`` -- a tuple of booleans + - ``flatten`` -- tuple of booleans This constructs a callable which accepts ``len(flatten)`` arguments, and builds a tuple out them. When ``flatten[i]``, - the i-th argument itself should be a tuple which is flattened + the `i`-th argument itself should be a tuple which is flattened in the result. sage: from sage.combinat.free_module import CartesianProductWithFlattening sage: CartesianProductWithFlattening([True, False, True, True]) - """ self._flatten = flatten @@ -1726,7 +1725,6 @@ def __call__(self, *indices): (1, 2, (3, 4), 5, 6, 7, 8) sage: cp((1,2,3), 4, (5,6), (7,8)) (1, 2, 3, 4, 5, 6, 7, 8) - """ return sum((i if flatten else (i,) for (i, flatten) in zip(indices, self._flatten)), ()) @@ -1738,15 +1736,15 @@ def __call__(self, *indices): class CombinatorialFreeModule_CartesianProduct(CombinatorialFreeModule): """ - An implementation of Cartesian products of modules with basis + An implementation of Cartesian products of modules with basis. EXAMPLES: We construct two free modules, assign them short names, and construct their Cartesian product:: - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") - sage: H = CombinatorialFreeModule(ZZ, [4,7]); H.rename("H") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') + sage: H = CombinatorialFreeModule(ZZ, [4,7]); H.rename('H') sage: S = cartesian_product([F, G]) sage: S F (+) G @@ -1801,7 +1799,7 @@ def __init__(self, modules, **options): def _sets_keys(self): """ - In waiting for self._sets.keys() + In waiting for ``self._sets.keys()``. TESTS:: @@ -1820,7 +1818,7 @@ def _repr_(self): sage: F = CombinatorialFreeModule(ZZ, [2,4,5]) sage: CP = cartesian_product([F, F]); CP # indirect doctest Free module generated by {2, 4, 5} over Integer Ring (+) Free module generated by {2, 4, 5} over Integer Ring - sage: F.rename("F"); CP + sage: F.rename('F'); CP F (+) F """ from sage.categories.cartesian_product import cartesian_product @@ -1836,12 +1834,12 @@ def cartesian_embedding(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') sage: S = cartesian_product([F, G]) sage: phi = S.cartesian_embedding(0) sage: phi(F.monomial(4) + 2 * F.monomial(5)) @@ -1870,12 +1868,12 @@ def cartesian_projection(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') sage: S = cartesian_product([F, G]) sage: x = S.monomial((0,4)) + 2 * S.monomial((0,5)) + 3 * S.monomial((1,6)) sage: S.cartesian_projection(0)(x) @@ -1904,8 +1902,8 @@ def _cartesian_product_of_elements(self, elements): EXAMPLES:: - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') sage: S = cartesian_product([F, G]) sage: f = F.monomial(4) + 2*F.monomial(5) sage: g = 2*G.monomial(4) + G.monomial(6) @@ -1943,8 +1941,8 @@ def cartesian_factors(self): EXAMPLES:: - sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename("F") - sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename("G") + sage: F = CombinatorialFreeModule(ZZ, [4,5]); F.rename('F') + sage: G = CombinatorialFreeModule(ZZ, [4,6]); G.rename('G') sage: S = cartesian_product([F, G]) sage: S.cartesian_factors() (F, G) diff --git a/src/sage/combinat/free_prelie_algebra.py b/src/sage/combinat/free_prelie_algebra.py index 88d54b1f443..1ea7d3274a1 100644 --- a/src/sage/combinat/free_prelie_algebra.py +++ b/src/sage/combinat/free_prelie_algebra.py @@ -227,7 +227,7 @@ def __init__(self, R, names=None): cat = MagmaticAlgebras(R).WithBasis().Graded() & LieAlgebras(R).WithBasis().Graded() CombinatorialFreeModule.__init__(self, R, Trees, - latex_prefix="", + latex_prefix='', sorting_key=key, category=cat) @@ -263,7 +263,7 @@ def _repr_(self): sage: enum = EnumeratedSets().Infinite().example() sage: algebras.FreePreLie(QQ, enum) # indirect doctest Free PreLie algebra on generators indexed by An example of an - infinite enumerated set: the non negative integers + infinite enumerated set: the nonnegative integers over Rational Field """ n = self.algebra_generators().cardinality() @@ -289,7 +289,7 @@ def gen(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -337,7 +337,7 @@ def change_ring(self, R): INPUT: - - `R` -- a ring + - ``R`` -- a ring EXAMPLES:: @@ -716,7 +716,7 @@ def _coerce_map_from_(self, R): The things that coerce into ``self`` are - free pre-Lie algebras whose set `E` of labels is - a subset of the corresponding self of ``set`, and whose base + a subset of the corresponding ``self`` of ``set``, and whose base ring has a coercion map into ``self.base_ring()`` EXAMPLES:: @@ -1048,8 +1048,8 @@ def tree_from_sortkey(ch, labels=True): INPUT: - - ``ch`` -- a list of pairs ``(integer, label)`` - - ``labels`` -- (default ``True``) whether to use labelled trees + - ``ch`` -- list of pairs ``(integer, label)`` + - ``labels`` -- boolean (default: ``True``); whether to use labelled trees OUTPUT: @@ -1101,7 +1101,7 @@ def corolla_gen(tx, list_ty, labels=True): INPUT: - ``tx`` -- a tree - - ``list_ty`` -- a list of trees + - ``list_ty`` -- list of trees EXAMPLES:: diff --git a/src/sage/combinat/fully_commutative_elements.py b/src/sage/combinat/fully_commutative_elements.py index 19f3024cac5..4cf13510dd3 100644 --- a/src/sage/combinat/fully_commutative_elements.py +++ b/src/sage/combinat/fully_commutative_elements.py @@ -140,10 +140,10 @@ def is_fully_commutative(self): r""" Check if ``self`` is the reduced word of an FC element. - To check if `self` is FC, we use the well-known characterization that an - element `w` in a Coxeter system `(W,S)` is FC if and only if for every - pair of generators `s,t \in S` for which `m(s,t)>2`, no reduced word of - `w` contains the 'braid' word `sts...` of length `m(s,t)` as a + To check if ``self`` is FC, we use the well-known characterization that + an element `w` in a Coxeter system `(W,S)` is FC if and only if for + every pair of generators `s,t \in S` for which `m(s,t)>2`, no reduced + word of `w` contains the 'braid' word `sts...` of length `m(s,t)` as a contiguous subword. See [Ste1996]_. :func:`check` is an alias of this method, and is called automatically @@ -189,13 +189,13 @@ def heap(self, **kargs): INPUT: - - ``self`` -- list, a reduced word `w=s_0... s_{k-1}` of an FC element + - ``self`` -- list; a reduced word `w=s_0... s_{k-1}` of an FC element - - ``one_index`` -- boolean (default: ``False``). Setting the value to True + - ``one_index`` -- boolean (default: ``False``); setting the value to True will change the underlying set of the poset to `\{1, 2, \dots, n\}` - - ``display_labeling`` -- boolean (default: ``False``). Setting the value to - True will display the label `s_i` for each element `i` of the poset + - ``display_labeling`` -- boolean (default: ``False``); setting the value to + ``True`` will display the label `s_i` for each element `i` of the poset OUTPUT: @@ -387,7 +387,7 @@ def has_descent(self, s, side='left'): - ``side`` -- string (default: ``'left'``); if set to 'right', determine if ``self`` has ``s`` as a right descent - OUTPUT: a boolean value + OUTPUT: boolean EXAMPLES:: @@ -657,7 +657,7 @@ def star_operation(self, J, direction, side='left'): INPUT: - - ``J`` -- a set of two integers representing two noncommuting + - ``J`` -- set of two integers representing two noncommuting generators of the Coxeter system - ``direction`` -- string, ``'upper'`` or ``'lower'``; the function @@ -803,7 +803,7 @@ class FullyCommutativeElements(UniqueRepresentation, Parent): True Attempting to create an element from an input that is not the reduced word - of a fully commutative element throws a :class:`ValueError`:: + of a fully commutative element throws a :exc:`ValueError`:: sage: FC([1,2,1]) Traceback (most recent call last): diff --git a/src/sage/combinat/fully_packed_loop.py b/src/sage/combinat/fully_packed_loop.py index b3ebd206cd2..74a14fa1ecd 100644 --- a/src/sage/combinat/fully_packed_loop.py +++ b/src/sage/combinat/fully_packed_loop.py @@ -131,33 +131,33 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): sage: fpl.link_pattern() [(1, 4), (2, 3), (5, 6)] sage: fpl - | | - | | - + -- + + - | | - | | - -- + + + -- - | | - | | - + + -- + - | | - | | + │ │ + │ │ + + ── + + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + + ── + + │ │ + │ │ sage: B = AlternatingSignMatrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]]) sage: fplb = FullyPackedLoop(B) sage: fplb.link_pattern() [(1, 6), (2, 5), (3, 4)] sage: fplb - | | - | | - + + -- + - | | - | | - -- + + + -- - | | - | | - + -- + + - | | - | | + │ │ + │ │ + + + ── + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + ── + + + │ │ + │ │ The class also has a plot method:: @@ -191,17 +191,17 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): V V V sage: fpl = FullyPackedLoop(S) sage: fpl - | | - | | - + -- + + - | | - | | - -- + + + -- - | | - | | - + + -- + - | | - | | + │ │ + │ │ + + ── + + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + + ── + + │ │ + │ │ Once we have a fully packed loop we can obtain the corresponding alternating sign matrix:: @@ -218,20 +218,20 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): sage: fpl.link_pattern() [(1, 2), (3, 6), (4, 5), (7, 8)] sage: fpl - | | - | | - + -- + -- + + -- - | - | - -- + + -- + -- + - | | - | | - + + + -- + -- - | | | - | | | - -- + + + -- + - | | - | | + │ │ + │ │ + + ── + ── + + ── + │ + │ + ── + + ── + ── + + │ │ + │ │ + + + + ── + ── + │ │ │ + │ │ │ + ── + + + ── + + │ │ + │ │ sage: m = AlternatingSignMatrix([[0,0,1,0,0,0], ....: [1,0,-1,0,1,0], @@ -243,26 +243,26 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): sage: fpl.link_pattern() [(1, 12), (2, 7), (3, 4), (5, 6), (8, 9), (10, 11)] sage: fpl - | | | - | | | - + -- + + + -- + + -- - | | | | - | | | | - -- + -- + + + -- + -- + - | - | - + -- + + -- + -- + + -- - | | | | - | | | | - -- + + + -- + + + - | | | | | - | | | | | - + -- + + -- + + + -- - | | - | | - -- + + -- + -- + + -- + - | | | - | | | + │ │ │ + │ │ │ + + ── + + + ── + + ── + │ │ │ │ + │ │ │ │ + ── + ── + + + ── + ── + + │ + │ + + ── + + ── + ── + + ── + │ │ │ │ + │ │ │ │ + ── + + + ── + + + + │ │ │ │ │ + │ │ │ │ │ + + ── + + ── + + + ── + │ │ + │ │ + ── + + ── + ── + + ── + + │ │ │ + │ │ │ sage: m = AlternatingSignMatrix([[0,1,0,0,0,0,0], ....: [1,-1,0,0,1,0,0], @@ -275,29 +275,29 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): sage: fpl.link_pattern() [(1, 2), (3, 4), (5, 6), (7, 8), (9, 14), (10, 11), (12, 13)] sage: fpl - | | | | - | | | | - + -- + -- + + -- + + -- + - | | - | | - -- + -- + -- + + -- + -- + + -- - | | - | | - + -- + + -- + -- + + -- + - | | | | - | | | | - -- + + + -- + + + + -- - | | | | | | - | | | | | | - + -- + + -- + + + -- + - | | - | | - -- + + -- + -- + + + -- + -- - | | | | - | | | | - + -- + + -- + + + -- + - | | | | - | | | | + │ │ │ │ + │ │ │ │ + + ── + ── + + ── + + ── + + │ │ + │ │ + ── + ── + ── + + ── + ── + + ── + │ │ + │ │ + + ── + + ── + ── + + ── + + │ │ │ │ + │ │ │ │ + ── + + + ── + + + + ── + │ │ │ │ │ │ + │ │ │ │ │ │ + + ── + + ── + + + ── + + │ │ + │ │ + ── + + ── + ── + + + ── + ── + │ │ │ │ + │ │ │ │ + + ── + + ── + + + ── + + │ │ │ │ + │ │ │ │ Gyration on an alternating sign matrix/fully packed loop ``fpl`` of the link pattern corresponding to ``fpl``:: @@ -357,34 +357,34 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): sage: A = AlternatingSignMatrix([[0, 0, 1], [0, 1, 0], [1, 0, 0]]) sage: fpl = FullyPackedLoop(A) sage: fpl - | | - | | - + -- + + - | | - | | - -- + + + -- - | | - | | - + + -- + - | | - | | + │ │ + │ │ + + ── + + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + + ── + + │ │ + │ │ sage: FullyPackedLoops(3)(A) == fpl True We can also input a matrix:: sage: FullyPackedLoop([[0, 0, 1], [0, 1, 0], [1, 0, 0]]) - | | - | | - + -- + + - | | - | | - -- + + + -- - | | - | | - + + -- + - | | - | | + │ │ + │ │ + + ── + + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + + ── + + │ │ + │ │ sage: FullyPackedLoop([[0, 0, 1], [0, 1, 0], [1, 0, 0]]) ==\ ....: FullyPackedLoops(3)([[0, 0, 1], [0, 1, 0], [1, 0, 0]]) True @@ -394,17 +394,17 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): sage: S = SixVertexModel(3, boundary_conditions='ice').from_alternating_sign_matrix(A) sage: fpl = FullyPackedLoop(S) sage: fpl - | | - | | - + -- + + - | | - | | - -- + + + -- - | | - | | - + + -- + - | | - | | + │ │ + │ │ + + ── + + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + + ── + + │ │ + │ │ sage: FullyPackedLoops(3)(S) == FullyPackedLoop(S) True @@ -427,14 +427,14 @@ class FullyPackedLoop(Element, metaclass=InheritComparisonClasscallMetaclass): V V sage: FullyPackedLoop([[3,1],[5,3]]) - | - | - + + -- - | | - | | - -- + + - | - | + │ + │ + + + ── + │ │ + │ │ + ── + + + │ + │ sage: FullyPackedLoops(2)([[3,1],[5,3]]) == FullyPackedLoop([[3,1],[5,3]]) True @@ -494,34 +494,34 @@ def __classcall_private__(cls, generator): sage: A = AlternatingSignMatrix([[1, 0, 0],[0, 1, 0],[0, 0, 1]]) sage: FullyPackedLoop(A) - | | - | | - + + -- + - | | - | | - -- + + + -- - | | - | | - + -- + + - | | - | | + │ │ + │ │ + + + ── + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + ── + + + │ │ + │ │ sage: SVM = SixVertexModel(4, boundary_conditions='ice')[0] sage: FullyPackedLoop(SVM) - | | - | | - + + -- + + -- - | | | - | | | - -- + + + -- + - | | - | | - + -- + + + -- - | | | - | | | - -- + + -- + + - | | - | | + │ │ + │ │ + + + ── + + ── + │ │ │ + │ │ │ + ── + + + ── + + │ │ + │ │ + + ── + + + ── + │ │ │ + │ │ │ + ── + + ── + + + │ │ + │ │ """ if isinstance(generator, AlternatingSignMatrix): SVM = generator.to_six_vertex_model() @@ -559,7 +559,6 @@ def __init__(self, parent, generator): sage: A = AlternatingSignMatrix([[0, 0, 1], [0, 1, 0], [1, 0, 0]]) sage: fpl = FullyPackedLoop(A) sage: TestSuite(fpl).run() - """ if isinstance(generator, AlternatingSignMatrix): self._six_vertex_model = generator.to_six_vertex_model() @@ -577,61 +576,57 @@ def _repr_(self): sage: A = AlternatingSignMatrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]]) sage: fpl = FullyPackedLoop(A) sage: fpl - | | - | | - + + -- + - | | - | | - -- + + + -- - | | - | | - + -- + + - | | - | | + │ │ + │ │ + + + ── + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + ── + + + │ │ + │ │ sage: A = AlternatingSignMatrix([[0,1,0,0],[0,0,1,0],[1,-1,0,1],[0,1,0,0]]) sage: S = SixVertexModel(4, boundary_conditions='ice').from_alternating_sign_matrix(A) sage: fpl = FullyPackedLoop(S) sage: fpl - | | - | | - + -- + -- + + -- - | - | - -- + + -- + -- + - | | - | | - + + + -- + -- - | | | - | | | - -- + + + -- + - | | - | | - + │ │ + │ │ + + ── + ── + + ── + │ + │ + ── + + ── + ── + + │ │ + │ │ + + + + ── + ── + │ │ │ + │ │ │ + ── + + + ── + + │ │ + │ │ """ # List are in the order of URDL # One set of rules for how to draw around even vertex, one set of rules for odd vertex n = len(self._six_vertex_model) - 1 - ascii1 = [[r' ', ' -', r' ', '- '], # LR - [r' | ', ' ', r' ', '- '], # LU - [r' ', ' ', r' | ', '- '], # LD - [r' | ', ' ', r' | ', ' '], # UD - [r' | ', ' -', r' ', ' '], # UR - [r' ', ' -', r' | ', ' ']] # RD - - ascii2 = [[r' | ', ' ', r' | ', ' '], # LR - [r' ', ' -', r' | ', ' '], # LU - [r' | ', ' -', r' ', ' '], # LD - [r' ', ' -', r' ', '- '], # UD - [r' ', ' ', r' | ', '- '], # UR - [r' | ', ' ', r' ', '- ']] # RD + ascii1 = [[r' ', ' ─', r' ', '─ '], # LR + [r' │ ', ' ', r' ', '─ '], # LU + [r' ', ' ', r' │ ', '─ '], # LD + [r' │ ', ' ', r' │ ', ' '], # UD + [r' │ ', ' ─', r' ', ' '], # UR + [r' ', ' ─', r' │ ', ' ']] # RD + + ascii2 = [[r' │ ', ' ', r' │ ', ' '], # LR + [r' ', ' ─', r' │ ', ' '], # LU + [r' │ ', ' ─', r' ', ' '], # LD + [r' ', ' ─', r' ', '─ '], # UD + [r' ', ' ', r' │ ', '─ '], # UR + [r' │ ', ' ', r' ', '─ ']] # RD ret = ' ' # Do the top line for i, entry in enumerate(self._six_vertex_model[0]): - if i % 2 == 0: - ret += ' | ' - else: - ret += ' ' + ret += ' ' if i % 2 else ' │ ' plus_sign = '+' @@ -640,17 +635,17 @@ def _repr_(self): ret += '\n ' # Do the top row for i, entry in enumerate(row): - if (i + j) % 2 == 0: + if not (i + j) % 2: ret += ascii1[entry][0] else: ret += ascii2[entry][0] ret += '\n' # Do the left-most entry - if j % 2 == 0: + if not j % 2: ret += ' ' else: - ret += ' -' + ret += ' ─' # Do the middle row for i, entry in enumerate(row): @@ -660,15 +655,15 @@ def _repr_(self): ret += ascii2[entry][3] + plus_sign + ascii2[entry][1] # Do the right-most entry - if (j+n) % 2 == 0: + if not (j + n) % 2: ret += ' ' else: - ret += '- ' + ret += '─ ' # Do the bottom row ret += '\n ' for i, entry in enumerate(row): - if (i + j) % 2 == 0: + if not (i + j) % 2: ret += ascii1[entry][2] else: ret += ascii2[entry][2] @@ -676,10 +671,7 @@ def _repr_(self): # Do the bottom line ret += '\n ' for i, entry in enumerate(self._six_vertex_model[-1]): - if (i+n+1) % 2 == 0: - ret += ' ' - else: - ret += ' | ' + ret += ' │ ' if (i + n + 1) % 2 else ' ' return ret @@ -753,19 +745,17 @@ def plot(self, **options): INPUT: - - ``link``, ``loop`` -- (boolean, default ``True``) whether to plot the links + - ``link``, ``loop`` -- boolean (default: ``True``); whether to plot the links or the loops - - ``color``, ``link_color``, ``loop_color`` -- (optional, a string or a - RGB triple) + - ``color``, ``link_color``, ``loop_color`` -- (optional) string or RGB triple - - ``colors``, ``link_colors``, ``loop_colors`` -- (optional, list) a list of - colors + - ``colors``, ``link_colors``, ``loop_colors`` -- (optional) list of colors - ``color_map``, ``link_color_map``, ``loop_color_map`` -- (string, optional) a name of a matplotlib color map for the link or the loop - - ``link_color_randomize`` -- (boolean, default ``False``) when + - ``link_color_randomize`` -- boolean (default: ``False``); when ``link_colors`` or ``link_color_map`` is specified it randomizes its order. Setting this option to ``True`` makes it unlikely to have two neighboring links with the same color. @@ -1199,17 +1189,17 @@ def six_vertex_model(self): sage: B = AlternatingSignMatrix([[1, 0, 0], [0, 1, 0], [0, 0, 1]]) sage: fpl = FullyPackedLoop(B) sage: fpl - | | - | | - + + -- + - | | - | | - -- + + + -- - | | - | | - + -- + + - | | - | | + │ │ + │ │ + + + ── + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + ── + + + │ │ + │ │ sage: fpl.six_vertex_model() ^ ^ ^ | | | @@ -1331,20 +1321,20 @@ def _element_constructor_(self, generator): sage: A = AlternatingSignMatrix(M) sage: elt = FullyPackedLoop(A) sage: FPL = FPLs(elt); FPL - | | - | | - + + -- + + -- - | | | - | | | - -- + + + -- + - | | - | | - + -- + + + -- - | | | - | | | - -- + + -- + + - | | - | | + │ │ + │ │ + + + ── + + ── + │ │ │ + │ │ │ + ── + + + ── + + │ │ + │ │ + + ── + + + ── + │ │ │ + │ │ │ + ── + + ── + + + │ │ + │ │ sage: FPLs(A) == FPL True @@ -1360,14 +1350,14 @@ def _element_constructor_(self, generator): sage: FPL = FullyPackedLoops(2) sage: FPL([[3,1],[5,3]]) - | - | - + + -- - | | - | | - -- + + - | - | + │ + │ + + + ── + │ │ + │ │ + ── + + + │ + │ """ if isinstance(generator, AlternatingSignMatrix): SVM = generator.to_six_vertex_model() @@ -1425,17 +1415,17 @@ def _an_element_(self): sage: FPLs = FullyPackedLoops(3) sage: FPLs.an_element() - | | - | | - + + -- + - | | - | | - -- + + + -- - | | - | | - + -- + + - | | - | | + │ │ + │ │ + + + ── + + │ │ + │ │ + ── + + + ── + │ │ + │ │ + + ── + + + │ │ + │ │ """ # ASM = AlternatingSignMatrix(matrix.identity(self._n)) # SVM = ASM.to_six_vertex_model() diff --git a/src/sage/combinat/gelfand_tsetlin_patterns.py b/src/sage/combinat/gelfand_tsetlin_patterns.py index 35b18541356..be4e236b099 100644 --- a/src/sage/combinat/gelfand_tsetlin_patterns.py +++ b/src/sage/combinat/gelfand_tsetlin_patterns.py @@ -479,8 +479,8 @@ def Tokuyama_coefficient(self, name='t'): INPUT: - - ``name`` -- (Default: ``'t'``) An alternative name for the - variable `t`. + - ``name`` -- (default: ``'t'``) an alternative name for the + variable `t` EXAMPLES:: @@ -579,15 +579,15 @@ class GelfandTsetlinPatterns(UniqueRepresentation, Parent): INPUT: - - ``n`` -- The width or depth of the array, also known as the rank + - ``n`` -- the width or depth of the array, also known as the rank - - ``k`` -- (Default: ``None``) If specified, this is the maximum value that + - ``k`` -- (default: ``None``) if specified, this is the maximum value that can occur in the patterns - - ``top_row`` -- (Default: ``None``) If specified, this is the fixed top + - ``top_row`` -- (default: ``None``) if specified, this is the fixed top row of all patterns - - ``strict`` -- (Default: ``False``) Set to ``True`` if all patterns are + - ``strict`` -- (default: ``False``) set to ``True`` if all patterns are strict patterns TESTS: @@ -1018,14 +1018,12 @@ def _toggle_markov_chain(self, chain_state, row, col, direction): INPUT: - - ``chain_state`` -- A GelfandTsetlin pattern represented as a list of lists - - ``row`` -- The row of the cell being modified - - ``col`` -- The column of the cell being modified - - ``direction`` -- The direction to change the cell 1 = increase, 0 = decrease + - ``chain_state`` -- a GelfandTsetlin pattern represented as a list of lists + - ``row`` -- the row of the cell being modified + - ``col`` -- the column of the cell being modified + - ``direction`` -- the direction to change the cell 1 = increase, 0 = decrease - OUTPUT: - - ``chain_state`` is possibly modified. + OUTPUT: ``chain_state`` is possibly modified TESTS: @@ -1341,8 +1339,8 @@ def Tokuyama_formula(self, name='t'): INPUT: - - ``name`` -- (Default: ``'t'``) An alternative name for the - variable `t`. + - ``name`` -- (default: ``'t'``) an alternative name for the + variable `t` EXAMPLES:: diff --git a/src/sage/combinat/gray_codes.py b/src/sage/combinat/gray_codes.py index e2508e0e01c..63e366c2cb5 100644 --- a/src/sage/combinat/gray_codes.py +++ b/src/sage/combinat/gray_codes.py @@ -21,7 +21,7 @@ def product(m): INPUT: - - ``m`` -- a list or tuple of positive integers that correspond to the size + - ``m`` -- list or tuple of positive integers that correspond to the size of the sets in the product EXAMPLES:: @@ -119,9 +119,9 @@ def combinations(n,t): INPUT: - - ``n`` -- (integer or ``Infinity``) -- size of the ground set + - ``n`` -- integer or ``Infinity``; size of the ground set - - ``t`` -- (integer) -- size of the subsets + - ``t`` -- integer; size of the subsets EXAMPLES:: @@ -193,7 +193,6 @@ def combinations(n,t): Traceback (most recent call last): ... AssertionError: t(=6) must be >=0 and <=n(=5) - """ from sage.rings.infinity import Infinity t = int(t) diff --git a/src/sage/combinat/grossman_larson_algebras.py b/src/sage/combinat/grossman_larson_algebras.py index db2f1de5eca..0e68753f52e 100644 --- a/src/sage/combinat/grossman_larson_algebras.py +++ b/src/sage/combinat/grossman_larson_algebras.py @@ -202,7 +202,7 @@ def __init__(self, R, names=None): cat = HopfAlgebras(R).WithBasis().Graded() CombinatorialFreeModule.__init__(self, R, Trees, - latex_prefix="", + latex_prefix='', sorting_key=key, category=cat) @@ -267,7 +267,7 @@ def single_vertex(self, i): INPUT: - - ``i`` -- a nonnegative integer + - ``i`` -- nonnegative integer EXAMPLES:: @@ -336,7 +336,7 @@ def change_ring(self, R): INPUT: - - `R` -- a ring + - ``R`` -- a ring EXAMPLES:: diff --git a/src/sage/combinat/growth.py b/src/sage/combinat/growth.py index 89657cfc2f6..958b664e7cd 100644 --- a/src/sage/combinat/growth.py +++ b/src/sage/combinat/growth.py @@ -27,7 +27,7 @@ Growth diagrams, invented by Sergey Fomin [Fom1994]_, [Fom1995]_, provide a vast generalization of the Robinson-Schensted-Knuth (RSK) -correspondence between matrices with non-negative integer entries and +correspondence between matrices with nonnegative integer entries and pairs of semistandard Young tableaux of the same shape. The main fact is that many correspondences similar to RSK can be @@ -127,7 +127,7 @@ In general, growth diagrams are defined for `0-1`-fillings of arbitrary skew shapes. In the case of the Robinson-Schensted-Knuth -correspondence, even arbitrary non-negative integers are allowed. In +correspondence, even arbitrary nonnegative integers are allowed. In other cases, entries may be either zero or an `r`-th root of unity - for example, :class:`~sage.combinat.growth.RuleDomino` insertion is defined for signed permutations, that is, `r=2`. Traditionally, words @@ -138,7 +138,7 @@ to (signed) entries, where zeros can be omitted. In this case, when the parameter ``shape`` is not explicitly specified, it is assumed to be the minimal rectangle containing the origin and all coordinates -with non-zero entries. +with nonzero entries. For example, consider the following generalized permutation:: @@ -183,8 +183,8 @@ between oscillating tableaux and (partial) perfect matchings. Perfect matchings of `\{1, \ldots, 2r\}` are in bijection with `0-1`-fillings of a triangular shape with `2r-1` rows, such that for -each `k` there is either exactly one non-zero entry in row `k` or -exactly one non-zero entry in column `2r-k`. Explicitly, if `(i,j)` +each `k` there is either exactly one nonzero entry in row `k` or +exactly one nonzero entry in column `2r-k`. Explicitly, if `(i,j)` is a pair in the perfect matching, the entry in column `i-1` and row `2r-j` equals `1`. For example:: @@ -339,7 +339,7 @@ For illustration, let us implement a growth diagram class with the backward rule only. Suppose that the vertices of the graph are the -non-negative integers, the rank is given by the integer itself, and +nonnegative integers, the rank is given by the integer itself, and the backward rule is `(y, z, x) \mapsto (\min(x,y), 0)` if `y = z` or `x = z` and `(y, z, x) \mapsto (\min(x,y), 1)` otherwise. @@ -517,7 +517,7 @@ class GrowthDiagram(SageObject): Growth diagrams were introduced by Sergey Fomin [Fom1994]_, [Fom1995]_ and provide a vast generalization of the Robinson-Schensted-Knuth (RSK) correspondence between matrices - with non-negative integer entries and pairs of semistandard Young + with nonnegative integer entries and pairs of semistandard Young tableaux of the same shape. A growth diagram is based on the notion of *dual graded graphs*, @@ -918,7 +918,6 @@ def P_chain(self): sage: BinaryWord = GrowthDiagram.rules.BinaryWord() sage: BinaryWord(filling = {}).P_chain() [word: ] - """ if not self.is_rectangular(): raise ValueError("the P symbol is only defined for rectangular shapes") @@ -948,7 +947,6 @@ def Q_chain(self): sage: BinaryWord = GrowthDiagram.rules.BinaryWord() sage: BinaryWord(filling = {}).Q_chain() [word: ] - """ if not self.is_rectangular(): raise ValueError("the Q symbol is only defined for rectangular shapes") @@ -1051,7 +1049,7 @@ def to_biword(self): w2.extend([j+1]*v) else: raise ValueError("can only convert fillings with" - " non-negative entries to words") + " nonnegative entries to words") return (w1, w2) def __iter__(self): @@ -1625,9 +1623,9 @@ class Rule(UniqueRepresentation): - ``r`` -- (default: 1) the parameter in the equation `DU - UD = rI` - - ``has_multiple_edges`` -- (default: ``False``) if the dual + - ``has_multiple_edges`` -- boolean (default: ``False``); if the dual graded graph has multiple edges and therefore edges are - triples consisting of two vertices and a label. + triples consisting of two vertices and a label - ``zero_edge`` -- (default: 0) the zero label of the edges of the graphs used for degenerate edges. It is @@ -1636,12 +1634,12 @@ class Rule(UniqueRepresentation): Subclasses may provide the following methods: - ``normalize_vertex`` -- a function that converts its input to a - vertex. + vertex - - ``vertices`` -- a function that takes a non-negative integer - as input and returns the list of vertices on this rank. + - ``vertices`` -- a function that takes a nonnegative integer + as input and returns the list of vertices on this rank - - ``rank`` -- the rank function of the dual graded graphs. + - ``rank`` -- the rank function of the dual graded graphs - ``forward_rule`` -- a function with input ``(y, t, x, content)`` or ``(y, e, t, f, x, content)`` if @@ -1752,7 +1750,7 @@ def _check_duality(self, n): INPUT: - - ``n`` -- a positive integer specifying which rank of + - ``n`` -- positive integer specifying which rank of the graph to test EXAMPLES: @@ -2038,7 +2036,6 @@ def P_symbol(self, P_chain): . . . . 2 . . 1 3 . 4 5 - """ chain = P_chain[::2] shape = chain[-1] @@ -2091,7 +2088,6 @@ def Q_symbol(self, Q_chain): . . . . 2 . . 1 4' . 3' 5' - """ chain = Q_chain shape = chain[-1] @@ -2165,7 +2161,6 @@ def forward_rule(self, y, e, t, f, x, content): sage: Shifted.forward_rule([3], 0, [2], 3, [3], 0) (3, [4], 0) - """ if e != 0: raise ValueError("the P-graph should not be colored") @@ -3212,9 +3207,7 @@ def forward_rule(self, y, t, x, content): - ``content`` -- `0` or `1`; the content of the cell - OUTPUT: - - The fourth binary tree ``z``. + OUTPUT: the fourth binary tree ``z`` EXAMPLES:: @@ -3528,9 +3521,7 @@ def forward_rule(self, y, t, x, content): - ``content`` -- `0` or `1`; the content of the cell - OUTPUT: - - The fourth Fibonacci word. + OUTPUT: the fourth Fibonacci word EXAMPLES:: @@ -3710,7 +3701,7 @@ class RuleRSK(RulePartitions): Partitions of the integer 3 The local rules implemented provide the RSK correspondence - between matrices with non-negative integer entries and pairs of + between matrices with nonnegative integer entries and pairs of semistandard tableaux, the :meth:`~sage.combinat.growth.RulePartitions.P_symbol` and the :meth:`~sage.combinat.growth.RulePartitions.Q_symbol`. For @@ -3770,7 +3761,7 @@ def forward_rule(self, y, t, x, content): t x y - - ``content`` -- a non-negative integer; the content of the cell + - ``content`` -- nonnegative integer; the content of the cell OUTPUT: @@ -3875,7 +3866,7 @@ class RuleBurge(RulePartitions): Partitions of the integer 3 The local rules implemented provide Burge's correspondence - between matrices with non-negative integer entries and pairs of + between matrices with nonnegative integer entries and pairs of semistandard tableaux, the :meth:`~sage.combinat.growth.RulePartitions.P_symbol` and the :meth:`~sage.combinat.growth.RulePartitions.Q_symbol`. For @@ -3922,11 +3913,9 @@ def forward_rule(self, y, t, x, content): t x y - - ``content`` -- a non-negative integer; the content of the cell - - OUTPUT: + - ``content`` -- nonnegative integer; the content of the cell - The fourth partition according to the Burge correspondence. + OUTPUT: the fourth partition according to the Burge correspondence EXAMPLES:: @@ -4217,9 +4206,7 @@ def forward_rule(self, y, t, x, content): - ``content`` -- `-1`, `0` or `1`; the content of the cell - OUTPUT: - - The fourth partition according to domino insertion. + OUTPUT: the fourth partition according to domino insertion EXAMPLES:: diff --git a/src/sage/combinat/hall_polynomial.py b/src/sage/combinat/hall_polynomial.py index 9d2326e60f8..96e23908d37 100644 --- a/src/sage/combinat/hall_polynomial.py +++ b/src/sage/combinat/hall_polynomial.py @@ -171,7 +171,7 @@ def hall_polynomial(nu, mu, la, q=None): for k in range(n): r.append(r[-1] + sum(exp_mu[k:]) - sum(exp_nu[k:])) # Now, r is [r_0, r_1, ..., r_n]. - exp_nu += [0]*(n - len(exp_nu)) # Pad with 0's until it has length n + exp_nu += [0]*(n - len(exp_nu)) # Pad with 0s until it has length n # Note that all -1 for exp_nu is due to indexing t = sum((r[k-2] - r[k-1])*(sum(exp_nu[k-1:]) - r[k-1]) for k in range(2,n+1)) if t < 0: diff --git a/src/sage/combinat/hillman_grassl.py b/src/sage/combinat/hillman_grassl.py index 5a85d4e48d3..c4e0f48088d 100644 --- a/src/sage/combinat/hillman_grassl.py +++ b/src/sage/combinat/hillman_grassl.py @@ -462,7 +462,7 @@ def _repr_(self): def an_element(self): r""" - Returns a particular element of the class. + Return a particular element of the class. TESTS:: @@ -771,9 +771,8 @@ def pak_correspondence(M, copy=True): INPUT: - - ``copy`` (default: ``True``) -- boolean; - if set to ``False``, the algorithm will mutate the - input (but be more efficient) + - ``copy`` -- boolean (default: ``True``); if set to ``False``, the + algorithm will mutate the input (but be more efficient) EXAMPLES:: diff --git a/src/sage/combinat/integer_lists/base.pyx b/src/sage/combinat/integer_lists/base.pyx index 6da2125396e..d2bd5da3b92 100644 --- a/src/sage/combinat/integer_lists/base.pyx +++ b/src/sage/combinat/integer_lists/base.pyx @@ -394,7 +394,7 @@ cdef class Envelope(): inf sage: f.min_slope 1 - sage: TestSuite(f).run(skip="_test_pickling") + sage: TestSuite(f).run(skip='_test_pickling') sage: Envelope(3, sign=1/3, max_slope=-1, min_length=4) Traceback (most recent call last): ... @@ -518,7 +518,6 @@ cdef class Envelope(): sage: Envelope(lambda x: 3, sign=-1, min_part=2).limit_start() == Infinity True - """ return self.f_limit_start @@ -526,7 +525,7 @@ cdef class Envelope(): r""" Return a bound on the limit of ``self``. - OUTPUT: a nonnegative integer or `\infty` + OUTPUT: nonnegative integer or `\infty` This returns some upper bound for the accumulation points of this upper envelope. For a lower envelope, a lower bound is @@ -605,9 +604,9 @@ cdef class Envelope(): INPUT: - - ``m`` -- a nonnegative integer (starting value) + - ``m`` -- nonnegative integer (starting value) - - ``j`` -- a nonnegative integer (position) + - ``j`` -- nonnegative integer (position) This method adapts this envelope to the additional local constraint imposed by having a part `m` at position `j`. diff --git a/src/sage/combinat/integer_lists/invlex.pyx b/src/sage/combinat/integer_lists/invlex.pyx index d8ab12b0a3d..6bef85031ce 100644 --- a/src/sage/combinat/integer_lists/invlex.pyx +++ b/src/sage/combinat/integer_lists/invlex.pyx @@ -62,64 +62,64 @@ class IntegerListsLex(IntegerLists, metaclass=ClasscallMetaclass): INPUT: - - ``min_sum`` -- a nonnegative integer (default: 0): - a lower bound on ``sum(l)``. + - ``min_sum`` -- nonnegative integer (default: 0); + a lower bound on ``sum(l)`` - - ``max_sum`` -- a nonnegative integer or `\infty` (default: `\infty`): - an upper bound on ``sum(l)``. + - ``max_sum`` -- nonnegative integer or `\infty` (default: `\infty`); + an upper bound on ``sum(l)`` - - ``n`` -- a nonnegative integer (optional): if specified, this - overrides ``min_sum`` and ``max_sum``. + - ``n`` -- nonnegative integer (optional); if specified, this + overrides ``min_sum`` and ``max_sum`` - - ``min_length`` -- a nonnegative integer (default: `0`): a lower - bound on ``len(l)``. + - ``min_length`` -- nonnegative integer (default: `0`); a lower + bound on ``len(l)`` - - ``max_length`` -- a nonnegative integer or `\infty` (default: - `\infty`): an upper bound on ``len(l)``. + - ``max_length`` -- nonnegative integer or `\infty` (default: + `\infty`); an upper bound on ``len(l)`` - - ``length`` -- an integer (optional); overrides ``min_length`` - and ``max_length`` if specified; + - ``length`` -- integer (optional); overrides ``min_length`` + and ``max_length`` if specified - - ``min_part`` -- a nonnegative integer: a lower bounds on all - parts: ``min_part <= l[i]`` for ``0 <= i < len(l)``. + - ``min_part`` -- nonnegative integer; a lower bounds on all + parts: ``min_part <= l[i]`` for ``0 <= i < len(l)`` - - ``floor`` -- a list of nonnegative integers or a function: lower - bounds on the individual parts `l[i]`. + - ``floor`` -- list of nonnegative integers or a function; lower + bounds on the individual parts `l[i]` If ``floor`` is a list of integers, then ``floor<=l[i]`` for ``0 <= i < min(len(l), len(floor)``. Similarly, if ``floor`` is a function, then ``floor(i) <= l[i]`` for ``0 <= i < len(l)``. - - ``max_part`` -- a nonnegative integer or `\infty`: an upper - bound on all parts: ``l[i] <= max_part`` for ``0 <= i < len(l)``. + - ``max_part`` -- nonnegative integer or `\infty`; an upper + bound on all parts: ``l[i] <= max_part`` for ``0 <= i < len(l)`` - ``ceiling`` -- upper bounds on the individual parts ``l[i]``; this takes the same type of input as ``floor``, except that `\infty` is allowed in addition to integers, and the default value is `\infty`. - - ``min_slope`` -- an integer or `-\infty` (default: `-\infty`): + - ``min_slope`` -- integer or `-\infty` (default: `-\infty`); a lower bound on the slope between consecutive parts: ``min_slope <= l[i+1]-l[i]`` for ``0 <= i < len(l)-1`` - - ``max_slope`` -- an integer or `+\infty` (defaults: `+\infty`) + - ``max_slope`` -- integer or `+\infty` (defaults: `+\infty`); an upper bound on the slope between consecutive parts: ``l[i+1]-l[i] <= max_slope`` for ``0 <= i < len(l)-1`` - ``category`` -- a category (default: :class:`FiniteEnumeratedSets`) - - ``check`` -- boolean (default: ``True``): whether to display the + - ``check`` -- boolean (default: ``True``); whether to display the warnings raised when functions are given as input to ``floor`` or ``ceiling`` and the errors raised when there is no proper enumeration. - - ``name`` -- a string or ``None`` (default: ``None``) if set, + - ``name`` -- string or ``None`` (default: ``None``); if set, this will be passed down to :meth:`Parent.rename` to specify the name of ``self``. It is recommended to use rename method directly because this feature may become deprecated. - ``element_constructor`` -- a function (or callable) that creates - elements of ``self`` from a list. See also :class:`Parent`. + elements of ``self`` from a list. See also :class:`Parent` - ``element_class`` -- a class for the elements of ``self`` (default: `ClonableArray`). This merely sets the attribute @@ -862,7 +862,7 @@ If you know what you are doing, you can set check=False to skip this warning.""" ``None`` if this method finds a proof that there exists an upper bound on the length. Otherwise a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. EXAMPLES:: @@ -1101,8 +1101,8 @@ class IntegerListsLexIter(builtins.object): - ``_current_sum`` -- the sum of the parts of ``_current_list``; - - ``_search_ranges`` -- a list of same length as - ``_current_list``: the range for each part. + - ``_search_ranges`` -- list of same length as + ``_current_list``: the range for each part Furthermore, we assume that there is no obvious contradiction in the constraints: @@ -1177,7 +1177,7 @@ class IntegerListsLexIter(builtins.object): The push may fail if it is discovered that ``self._current_list`` cannot be extended in a valid way. - OUTPUT: a boolean: whether the push succeeded + OUTPUT: boolean; whether the push succeeded EXAMPLES:: @@ -1388,11 +1388,11 @@ class IntegerListsLexIter(builtins.object): INPUT: - - ``i`` -- a nonnegative integer (position) + - ``i`` -- nonnegative integer (position) - - ``max_sum`` -- a nonnegative integer or ``+oo`` + - ``max_sum`` -- nonnegative integer or ``+oo`` - - ``prev`` -- a nonnegative integer or ``None`` + - ``prev`` -- nonnegative integer or ``None`` Return coarse lower and upper bounds for the value ``m`` of the part at position ``i`` so that there could exists diff --git a/src/sage/combinat/integer_lists/lists.py b/src/sage/combinat/integer_lists/lists.py index 8e121461056..6a4c3cb35a3 100644 --- a/src/sage/combinat/integer_lists/lists.py +++ b/src/sage/combinat/integer_lists/lists.py @@ -280,7 +280,7 @@ def __contains__(self, item): def _element_constructor_default(self, l): """ - Default element constructor + Default element constructor. EXAMPLES:: diff --git a/src/sage/combinat/integer_matrices.py b/src/sage/combinat/integer_matrices.py index db8105dd6ba..f97691338ff 100644 --- a/src/sage/combinat/integer_matrices.py +++ b/src/sage/combinat/integer_matrices.py @@ -1,8 +1,8 @@ # sage.doctest: needs sage.combinat sage.modules r""" -Counting, generating, and manipulating non-negative integer matrices +Counting, generating, and manipulating nonnegative integer matrices -Counting, generating, and manipulating non-negative integer matrices with +Counting, generating, and manipulating nonnegative integer matrices with prescribed row sums and column sums. AUTHORS: @@ -26,7 +26,7 @@ class IntegerMatrices(UniqueRepresentation, Parent): r""" - The class of non-negative integer matrices with + The class of nonnegative integer matrices with prescribed row sums and column sums. An *integer matrix* `m` with column sums `c := (c_1,...,c_k)` and row @@ -51,7 +51,6 @@ class IntegerMatrices(UniqueRepresentation, Parent): ] sage: IM.cardinality() 6 - """ @staticmethod def __classcall__(cls, row_sums, column_sums): @@ -72,7 +71,6 @@ def __classcall__(cls, row_sums, column_sums): Non-negative integer matrices with row sums [4, 4, 5] and column sums [3, 7, 1, 2] sage: IM = IntegerMatrices(Composition([4,4,5]), Composition([3,7,1,2])); IM Non-negative integer matrices with row sums [4, 4, 5] and column sums [3, 7, 1, 2] - """ from sage.combinat.composition import Composition row_sums = Composition(row_sums) @@ -134,14 +132,13 @@ def __iter__(self): [1 0] [0 1] [0 1], [1 0] ] - """ for x in integer_matrices_generator(self._row_sums, self._col_sums): yield matrix(ZZ, x) def __contains__(self, x): r""" - Tests if ``x`` is an element of ``self``. + Test if ``x`` is an element of ``self``. INPUT: @@ -218,7 +215,6 @@ def cardinality(self): 0 sage: len(IntegerMatrices([0], [0]).list()) 1 - """ from sage.combinat.sf.sf import SymmetricFunctions from sage.combinat.partition import Partition @@ -231,9 +227,7 @@ def row_sums(self): r""" The row sums of the integer matrices in ``self``. - OUTPUT: - - - Composition + OUTPUT: Composition EXAMPLES:: @@ -248,9 +242,7 @@ def column_sums(self): r""" The column sums of the integer matrices in ``self``. - OUTPUT: - - - Composition + OUTPUT: Composition EXAMPLES:: @@ -306,9 +298,7 @@ def integer_matrices_generator(row_sums, column_sums): - ``row_sums`` -- list or tuple - ``column_sums`` -- list or tuple - OUTPUT: - - - an iterator producing a list of lists + OUTPUT: an iterator producing a list of lists EXAMPLES:: diff --git a/src/sage/combinat/integer_vector.py b/src/sage/combinat/integer_vector.py index 3f4b59974a4..516d2114ffc 100644 --- a/src/sage/combinat/integer_vector.py +++ b/src/sage/combinat/integer_vector.py @@ -49,7 +49,7 @@ def is_gale_ryser(r, s): r""" - Tests whether the given sequences satisfy the condition + Test whether the given sequences satisfy the condition of the Gale-Ryser theorem. Given a binary matrix `B` of dimension `n\times m`, the @@ -59,14 +59,14 @@ def is_gale_ryser(r, s): If, given a binary matrix, these two vectors are easy to compute, the Gale-Ryser theorem lets us decide whether, given two - non-negative vectors `r,s`, there exists a binary matrix + nonnegative vectors `r,s`, there exists a binary matrix whose row/column sums vectors are `r` and `s`. This functions answers accordingly. INPUT: - - ``r``, ``s`` -- lists of non-negative integers. + - ``r``, ``s`` -- lists of nonnegative integers ALGORITHM: @@ -103,7 +103,7 @@ def is_gale_ryser(r, s): generic-sounding) term ''realizable sequence''. """ - # The sequences only contain non-negative integers + # The sequences only contain nonnegative integers if [x for x in r if x < 0] or [x for x in s if x < 0]: return False @@ -123,10 +123,10 @@ def is_gale_ryser(r, s): return len(rstar) <= len(s2) and sum(r2) == sum(s2) and rstar.dominates(s) -def gale_ryser_theorem(p1, p2, algorithm="gale", +def gale_ryser_theorem(p1, p2, algorithm='gale', *, solver=None, integrality_tolerance=1e-3): r""" - Returns the binary matrix given by the Gale-Ryser theorem. + Return the binary matrix given by the Gale-Ryser theorem. The Gale Ryser theorem asserts that if `p_1,p_2` are two partitions of `n` of respective lengths `k_1,k_2`, then there is @@ -144,7 +144,7 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", - ``'ryser'`` implements the construction due to Ryser [Ryser63]_. - ``'gale'`` (default) implements the construction due to Gale [Gale57]_. - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -153,11 +153,9 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", :class:`MixedIntegerLinearProgram `. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` - OUTPUT: - - A binary matrix if it exists, ``None`` otherwise. + OUTPUT: a binary matrix if it exists, ``None`` otherwise Gale's Algorithm: @@ -179,7 +177,7 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", * Construct the `m \times n` matrix `B` from `r` by defining the `i`-th row of `B` to be the vector whose first `r_i` - entries are `1`, and the remainder are 0's, `1 \leq i \leq m`. + entries are `1`, and the remainder are 0s, `1 \leq i \leq m`. This maximal matrix `B` with row sum `r` and ones left justified has column sum `r^{*}`. @@ -225,27 +223,27 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", sage: from sage.combinat.integer_vector import gale_ryser_theorem sage: p1 = [3,3,1,1] sage: p2 = [3,3,1,1] - sage: gale_ryser_theorem(p1, p2, algorithm="ryser") + sage: gale_ryser_theorem(p1, p2, algorithm='ryser') [1 1 1 0] [1 1 0 1] [1 0 0 0] [0 1 0 0] sage: p1 = [4,2,2] sage: p2 = [3,3,1,1] - sage: gale_ryser_theorem(p1, p2, algorithm="ryser") + sage: gale_ryser_theorem(p1, p2, algorithm='ryser') [1 1 1 1] [1 1 0 0] [1 1 0 0] sage: p1 = [4,2,2,0] sage: p2 = [3,3,1,1,0,0] - sage: gale_ryser_theorem(p1, p2, algorithm="ryser") + sage: gale_ryser_theorem(p1, p2, algorithm='ryser') [1 1 1 1 0 0] [1 1 0 0 0 0] [1 1 0 0 0 0] [0 0 0 0 0 0] sage: p1 = [3,3,2,1] sage: p2 = [3,2,2,1,1] - sage: print(gale_ryser_theorem(p1, p2, algorithm="gale")) # not tested + sage: print(gale_ryser_theorem(p1, p2, algorithm='gale')) # not tested [1 1 1 0 0] [1 1 0 0 1] [1 0 1 0 0] @@ -254,7 +252,7 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", With `0` in the sequences, and with unordered inputs:: sage: from sage.combinat.integer_vector import gale_ryser_theorem - sage: gale_ryser_theorem([3,3,0,1,1,0], [3,1,3,1,0], algorithm="ryser") # needs sage.combinat sage.modules + sage: gale_ryser_theorem([3,3,0,1,1,0], [3,1,3,1,0], algorithm='ryser') # needs sage.combinat sage.modules [1 1 1 0 0] [1 0 1 1 0] [0 0 0 0 0] @@ -262,7 +260,7 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", [0 0 1 0 0] [0 0 0 0 0] sage: p1 = [3,1,1,1,1]; p2 = [3,2,2,0] - sage: gale_ryser_theorem(p1, p2, algorithm="ryser") # needs sage.combinat sage.modules + sage: gale_ryser_theorem(p1, p2, algorithm='ryser') # needs sage.combinat sage.modules [1 1 1 0] [1 0 0 0] [1 0 0 0] @@ -295,11 +293,11 @@ def gale_ryser_theorem(p1, p2, algorithm="gale", Null matrix:: - sage: gale_ryser_theorem([0,0,0],[0,0,0,0], algorithm="gale") # needs sage.combinat sage.modules + sage: gale_ryser_theorem([0,0,0],[0,0,0,0], algorithm='gale') # needs sage.combinat sage.modules [0 0 0 0] [0 0 0 0] [0 0 0 0] - sage: gale_ryser_theorem([0,0,0],[0,0,0,0], algorithm="ryser") # needs sage.combinat sage.modules + sage: gale_ryser_theorem([0,0,0],[0,0,0,0], algorithm='ryser') # needs sage.combinat sage.modules [0 0 0 0] [0 0 0 0] [0 0 0 0] @@ -451,7 +449,7 @@ class IntegerVector(ClonableArray): def check(self): """ Check to make sure this is a valid integer vector by making sure - all entries are non-negative. + all entries are nonnegative. EXAMPLES:: @@ -478,7 +476,7 @@ def check(self): ValueError: [2, 2] doesn't satisfy correct constraints """ if any(x < 0 for x in self): - raise ValueError("all entries must be non-negative") + raise ValueError("all entries must be nonnegative") if self not in self.parent(): raise ValueError(f"{self} doesn't satisfy correct constraints") @@ -553,7 +551,7 @@ def specht_module_dimension(self, base_ring=None): class IntegerVectors(Parent, metaclass=ClasscallMetaclass): """ - The class of (non-negative) integer vectors. + The class of (nonnegative) integer vectors. INPUT: @@ -566,7 +564,7 @@ class IntegerVectors(Parent, metaclass=ClasscallMetaclass): .. NOTE:: - The entries are non-negative integers. + The entries are nonnegative integers. EXAMPLES: @@ -581,7 +579,7 @@ class IntegerVectors(Parent, metaclass=ClasscallMetaclass): sage: [1, 0, 0] in IntegerVectors() True - Entries are non-negative:: + Entries are nonnegative:: sage: [-1, 2] in IntegerVectors() False @@ -785,9 +783,8 @@ def _unrank_helper(self, x, rtn): INPUT: - - ``x`` -- a nonnegative integer - - ``rtn`` -- a list of nonnegative integers - + - ``x`` -- nonnegative integer + - ``rtn`` -- list of nonnegative integers EXAMPLES:: @@ -943,7 +940,7 @@ def rank(self, x): INPUT: - - ``x`` -- a list with ``sum(x) == n`` + - ``x`` -- list with ``sum(x) == n`` EXAMPLES:: @@ -968,7 +965,7 @@ def unrank(self, x): INPUT: - - ``x`` -- an integer. + - ``x`` -- integer EXAMPLES:: @@ -1078,7 +1075,7 @@ def rank(self, x): INPUT: - - ``x`` -- a list with ``len(x) == k`` + - ``x`` -- list with ``len(x) == k`` EXAMPLES:: @@ -1103,7 +1100,7 @@ def unrank(self, x): INPUT: - - ``x`` -- an integer such that x < self.cardinality()`` + - ``x`` -- integer such that ``x < self.cardinality()`` EXAMPLES:: @@ -1170,9 +1167,9 @@ def _list_rec(self, n, k): INPUT: - - ``n`` -- degree (must be 0) + - ``n`` -- degree (must be 0) - - ``k`` -- length of exponent tuples (must be 0) + - ``k`` -- length of exponent tuples (must be 0) EXAMPLES:: @@ -1315,7 +1312,7 @@ def rank(self, x): INPUT: - - ``x`` -- a list with ``sum(x) == n`` and ``len(x) == k`` + - ``x`` -- list with ``sum(x) == n`` and ``len(x) == k`` TESTS:: @@ -1338,7 +1335,7 @@ def unrank(self, x): INPUT: - - ``x`` -- an integer such that ``x < self.cardinality()`` + - ``x`` -- integer such that ``x < self.cardinality()`` EXAMPLES:: @@ -1376,9 +1373,9 @@ class IntegerVectors_nnondescents(UniqueRepresentation, IntegerVectors): The grading parameters on the integer vector `v` are: - - `n` -- the sum of the parts of `v`, + - ``n`` -- the sum of the parts of `v` - - `c` -- the non descents composition of `v`. + - ``c`` -- the non descents composition of `v` In other words: the length of `v` equals `c_1 + \cdots + c_k`, and `v` is decreasing in the consecutive blocs of length `c_1, \ldots, c_k`, diff --git a/src/sage/combinat/integer_vector_weighted.py b/src/sage/combinat/integer_vector_weighted.py index f3675d83e0f..ec074058b81 100644 --- a/src/sage/combinat/integer_vector_weighted.py +++ b/src/sage/combinat/integer_vector_weighted.py @@ -39,9 +39,9 @@ class WeightedIntegerVectors(Parent, UniqueRepresentation): INPUT: - - ``n`` -- a non negative integer (optional) + - ``n`` -- nonnegative integer (optional) - - ``weight`` -- a tuple (or list or iterable) of positive integers + - ``weight`` -- tuple (or list or iterable) of positive integers EXAMPLES:: @@ -134,7 +134,6 @@ def _element_constructor_(self, lst): ... ValueError: cannot convert [1, 2, 0] into Integer vectors of 3 weighted by [2, 1, 1] - """ if isinstance(lst, IntegerVector): if lst.parent() is self: @@ -350,7 +349,7 @@ def iterator_fast(n, l): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``l`` -- the weights in weakly decreasing order EXAMPLES:: diff --git a/src/sage/combinat/integer_vectors_mod_permgroup.py b/src/sage/combinat/integer_vectors_mod_permgroup.py index 5cdd65f2897..38e6f5af829 100644 --- a/src/sage/combinat/integer_vectors_mod_permgroup.py +++ b/src/sage/combinat/integer_vectors_mod_permgroup.py @@ -68,10 +68,10 @@ class IntegerVectorsModPermutationGroup(UniqueRepresentation): INPUT: - ``G`` -- a permutation group - - ``sum`` -- (default: None) - a nonnegative integer - - ``max_part`` -- (default: None) - a nonnegative integer setting the + - ``sum`` -- (default: ``None``) - a nonnegative integer + - ``max_part`` -- (default: ``None``) - a nonnegative integer setting the maximum value for every element - - ``sgs`` -- (default: None) - a strong generating system of the + - ``sgs`` -- (default: ``None``) - a strong generating system of the group `G`. If you do not provide it, it will be calculated at the creation of the parent @@ -243,7 +243,6 @@ class IntegerVectorsModPermutationGroup(UniqueRepresentation): 792 1287 2002 - """ @staticmethod def __classcall__(cls, G, sum=None, max_part=None, sgs=None): @@ -417,7 +416,7 @@ def retract(self, elt): def roots(self): r""" - Returns the root of generation of ``self``. This method is + Return the root of generation of ``self``. This method is required to build the tree structure of ``self`` which inherits from the class :class:`~sage.sets.recursively_enumerated_set.RecursivelyEnumeratedSet_forest`. @@ -431,7 +430,7 @@ def roots(self): def children(self, x): r""" - Returns the list of children of the element ``x``. This method + Return the list of children of the element ``x``. This method is required to build the tree structure of ``self`` which inherits from the class :class:`~sage.sets.recursively_enumerated_set.RecursivelyEnumeratedSet_forest`. @@ -445,7 +444,7 @@ def children(self, x): def permutation_group(self): r""" - Returns the permutation group given to define ``self``. + Return the permutation group given to define ``self``. EXAMPLES:: @@ -457,7 +456,7 @@ def permutation_group(self): def is_canonical(self, v, check=True): r""" - Returns ``True`` if the integer list ``v`` is maximal in its + Return ``True`` if the integer list ``v`` is maximal in its orbit under the action of the permutation group given to define ``self``. Such integer vectors are said to be canonical. A vector `v` is canonical if and only if @@ -508,7 +507,7 @@ def __contains__(self, v): def __call__(self, v, check=True): r""" - Returns an element of ``self`` constructed from ``v`` if + Return an element of ``self`` constructed from ``v`` if possible. TESTS:: @@ -527,7 +526,7 @@ def __call__(self, v, check=True): def orbit(self, v): r""" - Returns the orbit of the integer vector ``v`` under the action of the + Return the orbit of the integer vector ``v`` under the action of the permutation group defining ``self``. The result is a set. EXAMPLES: @@ -557,7 +556,7 @@ def orbit(self, v): def subset(self, sum=None, max_part=None): r""" - Returns the subset of ``self`` containing integer vectors + Return the subset of ``self`` containing integer vectors whose entries sum to ``sum``. EXAMPLES:: @@ -591,7 +590,7 @@ class Element(ClonableIntArray): def check(self): r""" - Checks that ``self`` verify the invariants needed for + Check that ``self`` verify the invariants needed for living in ``self.parent()``. EXAMPLES:: @@ -832,7 +831,6 @@ def __iter__(self): sage: I = IntegerVectorsModPermutationGroup(G, sum=3) sage: list(iter(I)) [] - """ # Special cases when domain is empty. if self.n == 0: @@ -945,7 +943,6 @@ def cardinality(self): 10 sage: IntegerVectorsModPermutationGroup(T10, 100).cardinality() 4263421511271 - """ G = self._permgroup k = G.degree() # Vector length @@ -1129,7 +1126,7 @@ def an_element(self): r""" Return an element of ``self``. - Raises an :class:`EmptySetError` when ``self`` is empty. + Raises an :exc:`EmptySetError` when ``self`` is empty. EXAMPLES:: @@ -1178,7 +1175,7 @@ def orbit(self, v): INPUT: - ``v`` -- an element of ``self`` or any list of length the - degree of the permutation group. + degree of the permutation group EXAMPLES: diff --git a/src/sage/combinat/interval_posets.py b/src/sage/combinat/interval_posets.py index 52e45090701..24084d03b82 100644 --- a/src/sage/combinat/interval_posets.py +++ b/src/sage/combinat/interval_posets.py @@ -95,15 +95,15 @@ class TamariIntervalPoset(Element, INPUT: - - ``size`` -- an integer, the size of the interval-posets (number of + - ``size`` -- integer; the size of the interval-posets (number of vertices) - - ``relations`` -- a list (or tuple) of pairs ``(a,b)`` (themselves + - ``relations`` -- list (or tuple) of pairs ``(a,b)`` (themselves lists or tuples), each representing a relation of the form - '`a` precedes `b`' in the poset. + '`a` precedes `b`' in the poset - - ``check`` -- (default: ``True``) whether to check the interval-poset - condition or not. + - ``check`` -- boolean (default: ``True``); whether to check the + interval-poset condition or not .. WARNING:: @@ -274,7 +274,7 @@ def set_latex_options(self, D): INPUT: - - ``D`` -- a dictionary with a list of latex parameters to change + - ``D`` -- dictionary with a list of latex parameters to change EXAMPLES:: @@ -722,7 +722,7 @@ def increasing_children(self, v) -> list[int]: INPUT: - - ``v`` -- an integer representing a vertex of ``self`` + - ``v`` -- integer representing a vertex of ``self`` (between 1 and ``size``) OUTPUT: @@ -761,7 +761,7 @@ def increasing_parent(self, v) -> None | int: INPUT: - - ``v`` -- an integer representing a vertex of ``self`` + - ``v`` -- integer representing a vertex of ``self`` (between 1 and ``size``) EXAMPLES:: @@ -858,7 +858,7 @@ def decreasing_children(self, v) -> list[int]: INPUT: - - ``v`` -- an integer representing a vertex of ``self`` + - ``v`` -- integer representing a vertex of ``self`` (between 1 and ``size``) OUTPUT: @@ -897,7 +897,7 @@ def decreasing_parent(self, v) -> None | int: INPUT: - - ``v`` -- an integer representing a vertex of ``self`` (between + - ``v`` -- integer representing a vertex of ``self`` (between 1 and ``size``) EXAMPLES:: @@ -1944,8 +1944,8 @@ def subposet(self, start, end) -> TIP: INPUT: - - ``start`` -- an integer, the starting vertex (inclusive) - - ``end`` -- an integer, the ending vertex (not inclusive) + - ``start`` -- integer; the starting vertex (inclusive) + - ``end`` -- integer; the ending vertex (not inclusive) EXAMPLES:: @@ -2511,9 +2511,7 @@ def new_decomposition(self) -> list[TIP]: For the number of terms, you can use instead the method :meth:`number_of_new_components`. - OUTPUT: - - a list of new interval-posets. + OUTPUT: list of new interval-posets .. SEEALSO:: @@ -2861,7 +2859,7 @@ class TamariIntervalPosets(UniqueRepresentation, Parent): INPUT: - - ``size`` -- (optional) an integer + - ``size`` -- integer (optional) OUTPUT: @@ -2942,10 +2940,10 @@ class options(GlobalOptions): description='the default value for the line width as a' 'multiple of the tikz scale when latexed', checker=lambda x: True) # More trouble than it's worth to check - latex_color_decreasing = dict(default="red", + latex_color_decreasing = dict(default='red', description='the default color of decreasing relations when latexed', checker=lambda x: True) # More trouble than it's worth to check - latex_color_increasing = dict(default="blue", + latex_color_increasing = dict(default='blue', description='the default color of increasing relations when latexed', checker=lambda x: True) # More trouble than it's worth to check latex_hspace = dict(default=1, @@ -3409,8 +3407,8 @@ def from_minimal_schnyder_wood(graph) -> TIP: INPUT: - a minimal Schnyder wood, given as a graph with colored and - oriented edges, without the three exterior unoriented edges + - ``graph`` -- a minimal Schnyder wood, given as a graph with colored + and oriented edges, without the three exterior unoriented edges The three boundary vertices must be -1, -2 and -3. @@ -3420,9 +3418,7 @@ def from_minimal_schnyder_wood(graph) -> TIP: Beware that the embedding convention used here is the opposite of the one used by the plot method. - OUTPUT: - - a Tamari interval-poset + OUTPUT: a Tamari interval-poset EXAMPLES: @@ -3557,7 +3553,7 @@ def profil(gr, vertex): def __call__(self, *args, **keywords): r""" - Allows for a poset to be directly transformed into an interval-poset. + Allow for a poset to be directly transformed into an interval-poset. It is some kind of coercion but cannot be made through the coercion system because posets do not have parents. diff --git a/src/sage/combinat/k_tableau.py b/src/sage/combinat/k_tableau.py index 0b35435c517..2c048fe38fc 100644 --- a/src/sage/combinat/k_tableau.py +++ b/src/sage/combinat/k_tableau.py @@ -51,7 +51,7 @@ lazy_import('sage.combinat.root_system.weyl_group', 'WeylGroup') -def WeakTableau(t, k, inner_shape=[], representation="core"): +def WeakTableau(t, k, inner_shape=[], representation='core'): r""" This is the dispatcher method for the element class of weak `k`-tableaux. @@ -85,7 +85,7 @@ def WeakTableau(t, k, inner_shape=[], representation="core"): (default: ``[]``) - ``representation`` -- 'core', 'bounded', or 'factorized_permutation' - (default: 'core') + (default: ``'core'``) EXAMPLES: @@ -111,7 +111,7 @@ def WeakTableau(t, k, inner_shape=[], representation="core"): Next we create the analogue of the first example in bounded representation:: - sage: tb = WeakTableau([[1,1,2],[2,3],[3]], 3, representation="bounded") + sage: tb = WeakTableau([[1,1,2],[2,3],[3]], 3, representation='bounded') sage: tb.shape() [3, 2, 1] sage: tb.weight() @@ -196,7 +196,7 @@ def WeakTableau(t, k, inner_shape=[], representation="core"): raise NotImplementedError("The representation option needs to be 'core', 'bounded', or 'factorized_permutation'") -def WeakTableaux(k, shape , weight, representation="core"): +def WeakTableaux(k, shape , weight, representation='core'): r""" This is the dispatcher method for the parent class of weak `k`-tableaux. @@ -360,7 +360,7 @@ def size(self): ([5, 2, 1], [1, 1]) sage: t.size() 4 - sage: t = WeakTableau([[1,1,2],[2,3],[3]], 3, representation="bounded") + sage: t = WeakTableau([[1,1,2],[2,3],[3]], 3, representation='bounded') sage: t.shape() [3, 2, 1] sage: t.size() @@ -486,7 +486,7 @@ def representation(self, representation='core'): INPUT: - - ``representation`` -- 'core', 'bounded', or 'factorized_permutation' (default: 'core') + - ``representation`` -- 'core', 'bounded', or 'factorized_permutation' (default: ``'core'``) EXAMPLES:: @@ -614,7 +614,7 @@ def representation(self, representation='core'): INPUT: - - ``representation`` -- 'core', 'bounded', or 'factorized_permutation' (default: 'core') + - ``representation`` -- 'core', 'bounded', or 'factorized_permutation' (default: ``'core'``) EXAMPLES:: @@ -670,8 +670,9 @@ class WeakTableau_core(WeakTableau_abstract): @staticmethod def __classcall_private__(cls, t, k): r""" - Implements the shortcut ``WeakTableau_core(t, k)`` to ``WeakTableaux_core(k, shape , weight)(t)`` - where ``shape`` is the shape of the tableau and ``weight`` is its weight. + Implement the shortcut ``WeakTableau_core(t, k)`` to + ``WeakTableaux_core(k, shape , weight)(t)`` where ``shape`` is the + shape of the tableau and ``weight`` is its weight. TESTS:: @@ -911,9 +912,7 @@ def residues_of_entries(self, v): - ``v`` -- a label of a cell in ``self`` - OUTPUT: - - - a list of residues + OUTPUT: list of residues EXAMPLES:: @@ -940,9 +939,7 @@ def dictionary_of_coordinates_at_residues(self, v): - ``v`` -- a label of a cell in ``self`` - OUTPUT: - - - dictionary assigning coordinates in ``self`` to residues + OUTPUT: dictionary assigning coordinates in ``self`` to residues EXAMPLES:: @@ -975,9 +972,7 @@ def list_of_standard_cells(self): - ``self`` -- a weak `k`-tableau in core representation with partition weight - OUTPUT: - - - a list of lists of coordinates + OUTPUT: list of lists of coordinates .. WARNING:: @@ -1036,18 +1031,16 @@ def list_of_standard_cells(self): out.append(standard_cells) return out - def k_charge(self, algorithm="I"): + def k_charge(self, algorithm='I'): r""" Return the `k`-charge of ``self``. INPUT: - - ``algorithm`` -- (default: "I") if "I", computes `k`-charge using the `I` + - ``algorithm`` -- (default: ``'I'``) if "I", computes `k`-charge using the `I` algorithm, otherwise uses the `J`-algorithm - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer For the definition of `k`-charge and the various algorithms to compute it see Section 3.3 of [LLMSSZ2013]_. @@ -1084,9 +1077,7 @@ def k_charge_I(self): For the definition of `k`-charge and the `I`-algorithm see Section 3.3 of [LLMSSZ2013]_. - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer .. SEEALSO:: :meth:`k_charge` and :meth:`k_charge_J` @@ -1130,9 +1121,7 @@ def k_charge_J(self): For the definition of `k`-charge and the `J`-algorithm see Section 3.3 of [LLMSSZ2013]_. - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer .. SEEALSO:: :meth:`k_charge` and :meth:`k_charge_I` @@ -1189,9 +1178,7 @@ def _height_of_restricted_subword(self, sw, r): - ``sw`` -- one of the subwords of standard cells of ``self`` - ``r`` -- nonnegative integer - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -1265,7 +1252,7 @@ def __classcall_private__(cls, k, shape, weight): def __init__(self, k, shape, weight): r""" - Initializes the parent class of (skew) weak `k`-tableaux in core representation. + Initialize the parent class of (skew) weak `k`-tableaux in core representation. INPUT: @@ -1334,9 +1321,7 @@ def diag(self, c, ha): - ``c`` -- a cell in the lattice - ``ha`` -- another cell in the lattice with bigger row and smaller column than `c` - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -1354,9 +1339,7 @@ def circular_distance(self, cr, r): - ``cr``, ``r`` -- nonnegative integers between `0` and `k` - OUTPUT: - - - a positive integer + OUTPUT: positive integer EXAMPLES:: @@ -1381,8 +1364,9 @@ class WeakTableau_bounded(WeakTableau_abstract): @staticmethod def __classcall_private__(cls, t, k): r""" - Implements the shortcut ``WeakTableau_bounded(t, k)`` to ``WeakTableaux_bounded(k, shape, weight)(t)`` - where ``shape`` is the shape of the tableau and ``weight`` is its weight. + Implement the shortcut ``WeakTableau_bounded(t, k)`` to + ``WeakTableaux_bounded(k, shape, weight)(t)`` where ``shape`` is the + shape of the tableau and ``weight`` is its weight. TESTS:: @@ -1564,7 +1548,7 @@ def check(self): def _is_k_tableau(self): r""" - Checks whether ``self`` is a valid weak `k`-tableau. + Check whether ``self`` is a valid weak `k`-tableau. EXAMPLES:: @@ -1662,12 +1646,10 @@ def k_charge(self, algorithm='I'): INPUT: - - ``algorithm`` -- (default: "I") if "I", computes `k`-charge using the `I` + - ``algorithm`` -- (default: ``'I'``) if "I", computes `k`-charge using the `I` algorithm, otherwise uses the `J`-algorithm - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer For the definition of `k`-charge and the various algorithms to compute it see Section 3.3 of [LLMSSZ2013]_. @@ -1733,7 +1715,7 @@ def __classcall_private__(cls, k, shape, weight): def __init__(self, k, shape, weight): r""" - Initializes the parent class of (skew) weak `k`-tableaux in bounded representation. + Initialize the parent class of (skew) weak `k`-tableaux in bounded representation. INPUT: @@ -1809,9 +1791,9 @@ def straighten_input(t, k): INPUT: - - ``t`` -- a list of reduced words or a list of elements in the Weyl group of type + - ``t`` -- list of reduced words or a list of elements in the Weyl group of type `A_k^{(1)}` - - ``k`` -- a positive integer + - ``k`` -- positive integer EXAMPLES:: @@ -1842,7 +1824,7 @@ def straighten_input(t, k): @staticmethod def __classcall_private__(cls, t, k, inner_shape=[]): r""" - Implements the shortcut ``WeakTableau_factorized_permutation(t, k)`` to + Implement the shortcut ``WeakTableau_factorized_permutation(t, k)`` to ``WeakTableaux_factorized_permutation(k, shape, weight)(t)`` where ``shape`` is the shape of the tableau as a `(k+1)`-core (or a tuple of `(k+1)`-cores if the tableau is skew) and ``weight`` is its weight. @@ -2003,7 +1985,7 @@ def check(self): def _is_k_tableau(self): r""" - Checks whether ``self`` is a valid weak `k`-tableau. + Check whether ``self`` is a valid weak `k`-tableau. EXAMPLES:: @@ -2094,9 +2076,7 @@ def k_charge(self, algorithm='I'): r""" Return the `k`-charge of ``self``. - OUTPUT: - - - a nonnegative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -2156,7 +2136,7 @@ def __classcall_private__(cls, k, shape, weight): def __init__(self, k, shape, weight): r""" - Initializes the parent class of weak `k`-tableaux in factorized permutation representation. + Initialize the parent class of weak `k`-tableaux in factorized permutation representation. INPUT: @@ -2490,11 +2470,9 @@ def _is_valid_marked( self ): INPUT: - - ``self`` -- a list of lists representing a potential *standard* marked tableau + - ``self`` -- list of lists representing a potential *standard* marked tableau - OUTPUT: - - - a boolean, ``True`` if the marks are properly placed in the tableau + OUTPUT: boolean; ``True`` if the marks are properly placed in the tableau EXAMPLES:: @@ -2551,9 +2529,7 @@ def _is_valid_standard( self ): less than or equal to `i` for each `i`) is a `k+1`-core and that the length of the `i+1`-restricted core is the length of the `i`-restricted core plus 1. - OUTPUT: - - - a boolean, ``True`` means the standard strong marked tableau is valid + OUTPUT: boolean; ``True`` means the standard strong marked tableau is valid EXAMPLES:: @@ -2595,9 +2571,8 @@ def is_column_strict_with_weight( self, mu ): - ``mu`` -- a vector of weights - OUTPUT: - - - a boolean, ``True`` means the underlying column strict strong marked tableau is valid + OUTPUT: boolean; ``True`` means the underlying column strict strong + marked tableau is valid EXAMPLES:: @@ -2684,18 +2659,18 @@ def _repr_(self): sage: T = StrongTableau([[-1,-2,3],[-3]],2) sage: T [[-1, -2, 3], [-3]] - sage: Tableaux.options(display="diagram") + sage: Tableaux.options(display='diagram') sage: T -1 -2 3 -3 - sage: Tableaux.options(convention="French") + sage: Tableaux.options(convention='French') sage: T -3 -1 -2 3 - sage: Tableaux.options(display="compact") + sage: Tableaux.options(display='compact') sage: T -1,-2,3/-3 - sage: Tableaux.options(display="list",convention="English") + sage: Tableaux.options(display='list',convention='English') """ return self.parent().options._dispatch(self, '_repr_', 'display') @@ -2709,11 +2684,9 @@ def cell_of_marked_head(self, v): INPUT: - - ``v`` -- an integer representing the label in the standard tableau + - ``v`` -- integer representing the label in the standard tableau - OUTPUT: - - - a pair of the coordinates of the marked cell with entry ``v`` + OUTPUT: a pair of the coordinates of the marked cell with entry ``v`` EXAMPLES:: @@ -2748,11 +2721,9 @@ def content_of_marked_head(self, v): INPUT: - - ``v`` -- an integer representing the label in the standard tableau - - OUTPUT: + - ``v`` -- integer representing the label in the standard tableau - - an integer representing the residue of the location of the mark + OUTPUT: integer representing the residue of the location of the mark EXAMPLES:: @@ -2839,12 +2810,10 @@ def cell_of_highest_head( self, v ): INPUT: - - ``v`` -- an integer indicating the label in the standard tableau + - ``v`` -- integer indicating the label in the standard tableau - OUTPUT: - - - a pair of integers indicating the coordinates of the head of the highest - ribbon with label ``v`` + OUTPUT: a pair of integers indicating the coordinates of the head of + the highest ribbon with label ``v`` EXAMPLES:: @@ -2883,12 +2852,10 @@ def content_of_highest_head( self, v ): INPUT: - - ``v`` -- an integer representing the label in the standard tableau - - OUTPUT: + - ``v`` -- integer representing the label in the standard tableau - - an integer representing the content of the head of the highest - ribbon with label ``v`` + OUTPUT: an integer representing the content of the head of the highest + ribbon with label ``v`` EXAMPLES:: @@ -2959,12 +2926,10 @@ def cells_of_heads(self, v): INPUT: - - ``v`` -- an integer label - - OUTPUT: + - ``v`` -- integer label - - a list of pairs of integers of the coordinates of the heads of the ribbons - with label ``v`` + OUTPUT: a list of pairs of integers of the coordinates of the heads of + the ribbons with label ``v`` EXAMPLES:: @@ -3003,11 +2968,10 @@ def contents_of_heads(self, v): INPUT: - - ``v`` -- an integer label + - ``v`` -- integer label - OUTPUT: - - - a list of integers of the content of the heads of the ribbons with label ``v`` + OUTPUT: list of integers of the content of the heads of the ribbons + with label ``v`` EXAMPLES:: @@ -3043,11 +3007,9 @@ def entries_by_content(self, diag): INPUT: - - ``diag`` -- an integer indicating the diagonal - - OUTPUT: + - ``diag`` -- integer indicating the diagonal - - a list (perhaps empty) of labels on the diagonal ``diag`` + OUTPUT: list (perhaps empty) of labels on the diagonal ``diag`` EXAMPLES:: @@ -3080,11 +3042,9 @@ def entries_by_content_standard(self, diag): INPUT: - - ``diag`` -- an integer indicating the diagonal + - ``diag`` -- integer indicating the diagonal - OUTPUT: - - - a list (perhaps empty) of labels on the diagonal ``diag`` + OUTPUT: list (perhaps empty) of labels on the diagonal ``diag`` EXAMPLES:: @@ -3161,10 +3121,8 @@ def height_of_ribbon(self, v): - ``v`` -- the label of the standard marked tableau - OUTPUT: - - - a non-negative integer representing the number of rows - occupied by the ribbon which is marked + OUTPUT: nonnegative integer representing the number of rows + occupied by the ribbon which is marked EXAMPLES:: @@ -3202,10 +3160,8 @@ def number_of_connected_components(self, v): - ``v`` -- the label of the standard marked tableau - OUTPUT: - - - a non-negative integer representing the number of connected - components + OUTPUT: nonnegative integer representing the number of connected + components EXAMPLES:: @@ -3248,9 +3204,7 @@ def intermediate_shapes(self): recover the strong tableau one would need the intermediate shapes and the :meth:`content_of_marked_head` for each pair of adjacent shapes in the list. - OUTPUT: - - - a list of lists of integers representing `k+1`-cores + OUTPUT: list of lists of integers representing `k+1`-cores EXAMPLES:: @@ -3292,7 +3246,7 @@ def pp( self ): 3 3 3 - sage: Tableaux.options(convention="French") + sage: Tableaux.options(convention='French') sage: T.pp() 3 3 @@ -3302,7 +3256,7 @@ def pp( self ): -1 -2 . . . . -1 -2 - sage: Tableaux.options(convention="English") + sage: Tableaux.options(convention='English') """ print(self._repr_diagram()) @@ -3371,11 +3325,11 @@ def shape( self ): INPUT: - - ``form`` -- optional argument to indicate 'inner', 'outer' or 'skew' (default : 'outer') + - ``form`` -- argument to indicate ``'inner'``, ``'outer'`` or + ``'skew'`` (default: ``'outer'``) - OUTPUT: - - - a `k+1`-core or a pair of `k+1`-cores if form is not 'inner' or 'outer' + OUTPUT: a `k+1`-core or a pair of `k+1`-cores if form is not + ``'inner'`` or ``'outer'`` EXAMPLES:: @@ -3400,12 +3354,10 @@ def weight( self ): r""" Return the weight of the tableau. - The weight is a list of non-negative integers indicating the number of 1s, + The weight is a list of nonnegative integers indicating the number of 1s, number of 2s, number of 3s, etc. - OUTPUT: - - - a list of non-negative integers + OUTPUT: list of nonnegative integers EXAMPLES:: @@ -3435,9 +3387,7 @@ def size( self ): .. SEEALSO:: :meth:`sage.combinat.core.Core.length` - OUTPUT: - - - a non-negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -3459,9 +3409,7 @@ def to_list( self ): """ Return the marked column strict (possibly skew) tableau as a list of lists. - OUTPUT: - - - a list of lists of integers or ``None`` + OUTPUT: list of lists of integers or ``None`` EXAMPLES:: @@ -3494,9 +3442,7 @@ def to_unmarked_list( self ): Return the list of lists of the rows of the tableau where the markings have been removed. - OUTPUT: - - - a list of lists of integers or ``None`` + OUTPUT: list of lists of integers or ``None`` EXAMPLES:: @@ -3525,9 +3471,7 @@ def to_standard_list(self): Internally, for a strong tableau the standard strong tableau and its weight is stored separately. This method returns the underlying standard part. - OUTPUT: - - - a list of lists of integers or ``None`` + OUTPUT: list of lists of integers or ``None`` EXAMPLES:: @@ -3553,9 +3497,7 @@ def to_standard_tableau(self): is stored separately. This method returns the underlying standard part as a ``StrongTableau``. - OUTPUT: - - - a strong tableau with standard weight + OUTPUT: a strong tableau with standard weight EXAMPLES:: @@ -3583,9 +3525,7 @@ def to_unmarked_standard_list( self ): Return the list of lists of the rows of the tableau where the markings have been removed. - OUTPUT: - - - a list of lists of integers or ``None`` + OUTPUT: list of lists of integers or ``None`` EXAMPLES:: @@ -3650,11 +3590,9 @@ def restrict( self, r ): INPUT: - - ``r`` -- an integer - - OUTPUT: + - ``r`` -- integer - - A strong tableau + OUTPUT: a strong tableau EXAMPLES:: @@ -3683,7 +3621,7 @@ def restrict( self, r ): def set_weight( self, mu ): """ - Sets a new weight ``mu`` for ``self``. + Set a new weight ``mu`` for ``self``. This method first tests if the underlying standard tableau is column-strict with respect to the weight ``mu``. If it is, then it changes the weight and returns @@ -3691,7 +3629,7 @@ def set_weight( self, mu ): INPUT: - - ``mu`` -- a list of non-negative integers representing the new weight + - ``mu`` -- list of nonnegative integers representing the new weight EXAMPLES:: @@ -3728,11 +3666,9 @@ def left_action( self, tij ): INPUT: - - ``tij`` -- a transposition represented as a pair `(i, j)`. + - ``tij`` -- a transposition represented as a pair `(i, j)` - OUTPUT: - - - ``self`` after it has been modified by the action of the transposition ``tij`` + OUTPUT: ``self`` after it has been modified by the action of the transposition ``tij`` EXAMPLES:: @@ -3769,9 +3705,7 @@ def follows_tableau( self ): Return list of all strong tableaux obtained from ``self`` by extending to a core which follows the shape of ``self`` in the strong order. - OUTPUT: - - - a list of strong tableaux which follow ``self`` in strong order + OUTPUT: list of strong tableaux which follow ``self`` in strong order EXAMPLES:: @@ -3817,9 +3751,7 @@ def spin_of_ribbon( self, v ): - ``v`` -- a label of the standard part of the tableau - OUTPUT: - - - an integer value representing the spin of the ribbon with label ``v``. + OUTPUT: integer value representing the spin of the ribbon with label ``v`` EXAMPLES:: @@ -3860,9 +3792,7 @@ def spin( self ): where the sum is over all column strict marked strong `k`-tableaux of shape `\lambda` and partition content. - OUTPUT: - - - an integer value representing the spin. + OUTPUT: integer value representing the spin EXAMPLES:: @@ -3901,9 +3831,7 @@ def to_transposition_sequence( self ): which when applied to the left of an empty tableau gives the corresponding strong standard tableau. - OUTPUT: - - - a list of pairs of values ``[i,j]`` representing the transpositions `t_{ij}` + OUTPUT: list of pairs of values ``[i,j]`` representing the transpositions `t_{ij}` EXAMPLES:: @@ -4014,9 +3942,7 @@ def outer_shape(self): r""" Return the outer shape of the class of strong tableaux. - OUTPUT: - - - a `k+1`-core + OUTPUT: a `k+1`-core EXAMPLES:: @@ -4033,9 +3959,7 @@ def inner_shape(self): r""" Return the inner shape of the class of strong tableaux. - OUTPUT: - - - a `k+1`-core + OUTPUT: a `k+1`-core EXAMPLES:: @@ -4055,9 +3979,7 @@ def shape(self): If the ``self`` has an inner shape return a pair consisting of an inner and an outer shape. If the inner shape is empty then return only the outer shape. - OUTPUT: - - - a `k+1`-core or a pair of `k+1`-cores + OUTPUT: a `k+1`-core or a pair of `k+1`-cores EXAMPLES:: @@ -4125,8 +4047,8 @@ def standard_unmarked_iterator( cls, k, size, outer_shape=None, inner_shape=[] ) INPUT: - ``k``, ``size`` -- positive integers - - ``outer_shape`` -- a list representing a `k+1`-core (default: ``None``) - - ``inner_shape`` -- a list representing a `k+1`-core (default: ``[]``) + - ``outer_shape`` -- list representing a `k+1`-core (default: ``None``) + - ``inner_shape`` -- list representing a `k+1`-core (default: ``[]``) OUTPUT: @@ -4174,13 +4096,11 @@ def marked_given_unmarked_and_weight_iterator(cls, unmarkedT, k, weight): INPUT: - - ``unmarkedT`` -- a list of lists representing a strong unmarked tableau - - ``k`` -- a positive integer - - ``weight`` -- a list of non-negative integers indicating the weight - - OUTPUT: + - ``unmarkedT`` -- list of lists representing a strong unmarked tableau + - ``k`` -- positive integer + - ``weight`` -- list of nonnegative integers indicating the weight - - an iterator that returns ``StrongTableau`` objects + OUTPUT: an iterator that returns ``StrongTableau`` objects EXAMPLES:: @@ -4234,14 +4154,12 @@ def add_marking( cls, unmarkedT, marking, k, weight ): INPUT: - - ``unmarkedT`` -- a list of lists which is a partially marked strong `k`-tableau - - ``marking`` -- a list of pairs of coordinates where cells are to be marked - - ``k`` -- a positive integer - - ``weight`` -- a tuple of the weight of the output tableau - - OUTPUT: + - ``unmarkedT`` -- list of lists which is a partially marked strong `k`-tableau + - ``marking`` -- list of pairs of coordinates where cells are to be marked + - ``k`` -- positive integer + - ``weight`` -- tuple of the weight of the output tableau - - a ``StrongTableau`` object + OUTPUT: a ``StrongTableau`` object EXAMPLES:: @@ -4280,11 +4198,9 @@ def _left_action_list( cls, Tlist, tij, v, k ): - ``Tlist`` -- a partial standard strong `k`-tableau as a list of lists - ``tij`` -- a pair of integers representing a transposition - ``v`` -- the label to add to the tableau - - ``k`` -- a positive integer - - OUTPUT: + - ``k`` -- positive integer - - a list of lists, in particular, it is ``Tlist`` + OUTPUT: list of lists, in particular, it is ``Tlist`` EXAMPLES:: @@ -4331,11 +4247,9 @@ def follows_tableau_unsigned_standard( cls, Tlist, k ): INPUT: - ``Tlist`` -- a filling of a `k+1`-core as a list of lists - - ``k`` -- an integer + - ``k`` -- integer - OUTPUT: - - - a list of strong tableaux which follow ``Tlist`` in strong order + OUTPUT: list of strong tableaux which follow ``Tlist`` in strong order EXAMPLES:: @@ -4378,10 +4292,10 @@ def standard_marked_iterator( cls, k, size, outer_shape=None, inner_shape=[] ): INPUT: - - ``k`` -- a positive integer - - ``size`` -- a positive integer - - ``outer_shape`` -- a list which is a `k+1`-core (default: ``None``) - - ``inner_shape`` -- a list which is a `k+1`-core (default: ``[]``) + - ``k`` -- positive integer + - ``size`` -- positive integer + - ``outer_shape`` -- list which is a `k+1`-core (default: ``None``) + - ``inner_shape`` -- list which is a `k+1`-core (default: ``[]``) OUTPUT: @@ -4483,11 +4397,9 @@ def marked_CST_to_transposition_sequence(self, T, k): INPUT: - ``T`` -- a non-empty column strict tableau as a list of lists - - ``k`` -- a positive integer - - OUTPUT: + - ``k`` -- positive integer - - a list of pairs of values ``[i,j]`` representing the transpositions `t_{ij}` + OUTPUT: list of pairs of values ``[i,j]`` representing the transpositions `t_{ij}` EXAMPLES:: @@ -4561,13 +4473,11 @@ def transpositions_to_standard_strong( self, transeq, k, emptyTableau=[] ): INPUT: - - ``transeq`` -- a sequence of transpositions `t_{ij}` (a list of pairs). + - ``transeq`` -- a sequence of transpositions `t_{ij}` (a list of pairs) - ``emptyTableau`` -- (default: ``[]``) an empty list or a skew strong tableau possibly consisting of ``None`` entries - OUTPUT: - - - a ``StrongTableau`` object + OUTPUT: a ``StrongTableau`` object EXAMPLES:: @@ -4607,9 +4517,7 @@ def nabs(v): - ``v`` -- either an integer or ``None`` - OUTPUT: - - - either a non-negative integer or ``None`` + OUTPUT: either a nonnegative integer or ``None`` EXAMPLES:: @@ -4633,9 +4541,7 @@ def intermediate_shapes(t): shapes, where the `i`-th shape is given by the shape of the subtableau on letters `1, 2, \ldots, i`. The output is the list of these shapes. - OUTPUT: - - - a list of lists representing partitions + OUTPUT: list of lists representing partitions EXAMPLES:: diff --git a/src/sage/combinat/kazhdan_lusztig.py b/src/sage/combinat/kazhdan_lusztig.py index eca077cd815..0014af47b73 100644 --- a/src/sage/combinat/kazhdan_lusztig.py +++ b/src/sage/combinat/kazhdan_lusztig.py @@ -46,7 +46,7 @@ class KazhdanLusztigPolynomial(UniqueRepresentation, SageObject): EXAMPLES:: - sage: W = WeylGroup("B3",prefix="s") + sage: W = WeylGroup("B3",prefix='s') sage: [s1,s2,s3] = W.simple_reflections() sage: R. = LaurentPolynomialRing(QQ) sage: KL = KazhdanLusztigPolynomial(W,q) @@ -66,7 +66,7 @@ def __init__(self, W, q, trace=False): EXAMPLES:: - sage: W = WeylGroup("B3",prefix="s") + sage: W = WeylGroup("B3",prefix='s') sage: R. = LaurentPolynomialRing(QQ) sage: KL = KazhdanLusztigPolynomial(W,q) sage: TestSuite(KL).run() @@ -95,7 +95,7 @@ def R(self, x, y): EXAMPLES:: sage: R.=QQ[] - sage: W = WeylGroup("A2", prefix="s") + sage: W = WeylGroup("A2", prefix='s') sage: [s1,s2]=W.simple_reflections() sage: KL = KazhdanLusztigPolynomial(W, q) sage: [KL.R(x,s2*s1) for x in [1,s1,s2,s1*s2]] @@ -114,7 +114,7 @@ def R(self, x, y): return self._base_ring.one() else: return self._base_ring.zero() - s = self._coxeter_group.simple_reflection(y.first_descent(side="left")) + s = self._coxeter_group.simple_reflection(y.first_descent(side='left')) if (s*x).length() < x.length(): ret = self.R(s*x,s*y) if self._trace: @@ -141,7 +141,7 @@ def R_tilde(self, x, y): EXAMPLES:: sage: R. = QQ[] - sage: W = WeylGroup("A2", prefix="s") + sage: W = WeylGroup("A2", prefix='s') sage: [s1,s2] = W.simple_reflections() sage: KL = KazhdanLusztigPolynomial(W, q) sage: [KL.R_tilde(x,s2*s1) for x in [1,s1,s2,s1*s2]] @@ -155,7 +155,7 @@ def R_tilde(self, x, y): return self._base_ring.zero() if x == y: return self._base_ring.one() - s = self._coxeter_group.simple_reflection(y.first_descent(side="right")) + s = self._coxeter_group.simple_reflection(y.first_descent(side='right')) if (x * s).length() < x.length(): ret = self.R_tilde(x * s, y * s) if self._trace: @@ -187,7 +187,7 @@ def P(self, x, y): EXAMPLES:: sage: R. = QQ[] - sage: W = WeylGroup("A3", prefix="s") + sage: W = WeylGroup("A3", prefix='s') sage: [s1,s2,s3] = W.simple_reflections() sage: KL = KazhdanLusztigPolynomial(W, q) sage: KL.P(s2,s2*s1*s3*s2) diff --git a/src/sage/combinat/key_polynomial.py b/src/sage/combinat/key_polynomial.py index 43db18cc72f..1b65f5bc063 100644 --- a/src/sage/combinat/key_polynomial.py +++ b/src/sage/combinat/key_polynomial.py @@ -649,7 +649,6 @@ def from_polynomial(self, f): sage: T = crystals.Tableaux(['A', 4], shape=[4,2,1,1]) sage: k.from_polynomial(T.demazure_character([2])) k[4, 1, 2, 1] - """ if f not in self._polynomial_ring: try: # to accept elements of SymbolicRing diff --git a/src/sage/combinat/knutson_tao_puzzles.py b/src/sage/combinat/knutson_tao_puzzles.py index b8b62c6a440..e1e4f746f42 100644 --- a/src/sage/combinat/knutson_tao_puzzles.py +++ b/src/sage/combinat/knutson_tao_puzzles.py @@ -308,9 +308,7 @@ def clockwise_rotation(self) -> NablaPiece: r""" Rotate the Nabla piece by 120 degree clockwise. - OUTPUT: - - - Nabla piece + OUTPUT: Nabla piece EXAMPLES:: @@ -327,9 +325,7 @@ def half_turn_rotation(self) -> DeltaPiece: r""" Rotate the Nabla piece by 180 degree. - OUTPUT: - - - Delta piece + OUTPUT: Delta piece EXAMPLES:: @@ -430,9 +426,7 @@ def clockwise_rotation(self) -> DeltaPiece: r""" Rotate the Delta piece by 120 degree clockwise. - OUTPUT: - - - Delta piece + OUTPUT: Delta piece EXAMPLES:: @@ -449,9 +443,7 @@ def half_turn_rotation(self) -> NablaPiece: r""" Rotate the Delta piece by 180 degree. - OUTPUT: - - - Nabla piece + OUTPUT: Nabla piece EXAMPLES:: @@ -1052,7 +1044,6 @@ def BK_pieces(max_letter): sage: BK_pieces(3) Nablas : [1\1/1, 1\2(1)/2, 1\3(1)/3, 2(1)\2/1, 2\1/2(1), 2\2/2, 2\3(2)/3, 3(1)\3/1, 3(2)\3/2, 3\1/3(1), 3\2/3(2), 3\3/3] Deltas : [1/1\1, 1/2\2(1), 1/3\3(1), 2(1)/1\2, 2/2(1)\1, 2/2\2, 2/3\3(2), 3(1)/1\3, 3(2)/2\3, 3/3(1)\1, 3/3(2)\2, 3/3\3] - """ forbidden_border_labels = ['%s(%s)' % (i, j) for i in range(1, max_letter + 1) @@ -1358,7 +1349,7 @@ def __iter__(self): for k in range(d + 1): yield self[k + 1, self._n - d + k] - def plot(self, labels=True, style="fill"): + def plot(self, labels=True, style='fill'): r""" Plot completed puzzle. @@ -1496,8 +1487,8 @@ class KnutsonTaoPuzzleSolver(UniqueRepresentation): - ``HT2step`` -- equivariant cohomology of the *2-step* Grassmannian - ``BK`` -- Belkale-Kumar puzzle pieces - - ``max_letter`` -- (default: None) None or a positive integer. This is - only required only for Belkale-Kumar puzzles. + - ``max_letter`` -- ``None`` or a positive integer(default: ``None``); this + is only required for Belkale-Kumar puzzles EXAMPLES: @@ -1570,7 +1561,7 @@ class KnutsonTaoPuzzleSolver(UniqueRepresentation): (3, 4): 1/\0 0\/1, (4, 4): 1/1\1}] - The pieces in a puzzle filling are indexed by pairs of non-negative + The pieces in a puzzle filling are indexed by pairs of nonnegative integers `(i, j)` with `1 \leq i \leq j \leq n`, where `n` is the length of the word labelling the triangle edge. The pieces indexed by `(i, i)` are the triangles along the south edge of the puzzle. :: @@ -2064,9 +2055,7 @@ def _fill_piece(self, nw_label, ne_label, pieces) -> list[PuzzlePiece]: - ``nw_label``, ``nw_label`` -- label - ``pieces`` -- puzzle pieces used for the filling - OUTPUT: - - - list of the fillings + OUTPUT: list of the fillings EXAMPLES:: @@ -2094,9 +2083,7 @@ def _fill_strip(self, nw_labels, ne_label, pieces, final_pieces=None): - ``pieces`` -- puzzle pieces used for the filling - ``final_pieces`` -- pieces used for the last piece to be filled in - OUTPUT: - - - list of lists of the fillings + OUTPUT: list of lists of the fillings EXAMPLES:: @@ -2227,9 +2214,9 @@ def structure_constants(self, lamda, mu, nu=None): - ``pieces`` -- puzzle pieces to be used - ``lambda``, ``mu`` -- edge labels of puzzle for northwest and north east side - - ``nu`` -- (default: ``None``) If ``nu`` is not specified a dictionary is returned with + - ``nu`` -- (default: ``None``) if ``nu`` is not specified a dictionary is returned with the structure coefficients corresponding to all south labels; if ``nu`` is given, only - the coefficients with the specified label is returned. + the coefficients with the specified label is returned OUTPUT: dictionary diff --git a/src/sage/combinat/lr_tableau.py b/src/sage/combinat/lr_tableau.py index 90d60beda3b..9a5e7a0ef03 100644 --- a/src/sage/combinat/lr_tableau.py +++ b/src/sage/combinat/lr_tableau.py @@ -56,7 +56,7 @@ class LittlewoodRichardsonTableau(SemistandardTableau): @staticmethod def __classcall_private__(cls, t, weight): r""" - Implements the shortcut ``LittlewoodRichardsonTableau(t, weight)`` to + Implement the shortcut ``LittlewoodRichardsonTableau(t, weight)`` to ``LittlewoodRichardsonTableaux(shape , weight)(t)`` where ``shape`` is the shape of the tableau. @@ -179,7 +179,7 @@ def __classcall_private__(cls, shape, weight): def __init__(self, shape, weight): r""" - Initializes the parent class of Littlewood-Richardson tableaux. + Initialize the parent class of Littlewood-Richardson tableaux. INPUT: diff --git a/src/sage/combinat/matrices/dancing_links.pyx b/src/sage/combinat/matrices/dancing_links.pyx index 5035bb0480b..475b5ef3e1b 100644 --- a/src/sage/combinat/matrices/dancing_links.pyx +++ b/src/sage/combinat/matrices/dancing_links.pyx @@ -145,14 +145,13 @@ cdef class dancing_linksWrapper: sage: x = dlx_solver([]) sage: x.get_solution() [] - """ self._rows = [row for row in rows] self._initialize() def _initialize(self): r""" - Initialization of the search algorithm + Initialization of the search algorithm. This adds the rows to the instance of dancing_links. This method is used by `__init__` and `reinitialize` methods and should not be @@ -173,7 +172,6 @@ cdef class dancing_linksWrapper: sage: x.reinitialize() # indirect doctest sage: x.get_solution() if x.search() else None [0, 1] - """ cdef vector[int] v cdef vector[vector[int]] vv @@ -190,7 +188,7 @@ cdef class dancing_linksWrapper: def reinitialize(self): r""" - Reinitialization of the search algorithm + Reinitialization of the search algorithm. This recreates an empty ``dancing_links`` object and adds the rows to the instance of ``dancing_links.`` @@ -226,7 +224,6 @@ cdef class dancing_linksWrapper: sage: x.get_solution() if x.search() else None [4, 5] sage: x.get_solution() if x.search() else None - """ sig_on() self._x = dancing_links() @@ -410,11 +407,9 @@ cdef class dancing_linksWrapper: INPUT: - - ``indices`` -- list, row indices to be found in the solution + - ``indices`` -- list; row indices to be found in the solution - OUTPUT: - - dancing links solver + OUTPUT: dancing links solver EXAMPLES:: @@ -426,7 +421,7 @@ cdef class dancing_linksWrapper: sage: sorted(map(sorted, d.solutions_iterator())) [[0, 1], [2, 3], [4, 5]] - To impose that the 0th row is part of the solution, the rows of the new + To impose that the `0`-th row is part of the solution, the rows of the new problem are:: sage: d_using_0 = d.restrict([0]) @@ -443,7 +438,7 @@ cdef class dancing_linksWrapper: sage: d.restrict([2]).rows() [[0, 1, 2], [3, 4, 5], [0, 1, 6], [2, 3, 4, 5], [0], [1, 2, 3, 4, 5]] - This method allows to find solutions where the 0th row is part of a + This method allows to find solutions where the `0`-th row is part of a solution:: sage: sorted(map(sorted, d.restrict([0]).solutions_iterator())) @@ -458,7 +453,7 @@ cdef class dancing_linksWrapper: sage: sorted(map(sorted, d.restrict([3]).solutions_iterator())) [[2, 3]] - Here there are no solution using both 0th and 3rd row:: + Here there are no solutions using both 0th and 3rd row:: sage: list(d.restrict([0,3]).solutions_iterator()) [] @@ -488,12 +483,10 @@ cdef class dancing_linksWrapper: INPUT: - - ``column`` -- integer, the column used to split the problem into + - ``column`` -- integer; the column used to split the problem into independent subproblems - OUTPUT: - - dict where keys are row numbers and values are dlx solvers + OUTPUT: dict where keys are row numbers and values are dlx solvers EXAMPLES:: @@ -582,18 +575,16 @@ cdef class dancing_linksWrapper: INPUT: - - ``ncpus`` -- integer (default: ``None``), maximal number of + - ``ncpus`` -- integer (default: ``None``); maximal number of subprocesses to use at the same time. If ``None``, it detects the number of effective CPUs in the system using :func:`sage.parallel.ncpus.ncpus()`. If ``ncpus=1``, the first solution is searched serially. - - ``column`` -- integer (default: ``None``), the column used to split + - ``column`` -- integer (default: ``None``); the column used to split the problem (see :meth:`restrict`). If ``None``, a random column is chosen. This argument is ignored if ``ncpus=1``. - OUTPUT: - - list of rows or ``None`` if no solution is found + OUTPUT: list of rows or ``None`` if no solution is found .. NOTE:: @@ -685,16 +676,14 @@ cdef class dancing_linksWrapper: INPUT: - - ``ncpus`` -- integer (default: ``None``), maximal number of + - ``ncpus`` -- integer (default: ``None``); maximal number of subprocesses to use at the same time. If ``None``, it detects the number of effective CPUs in the system using :func:`sage.parallel.ncpus.ncpus()`. - - ``column`` -- integer (default: ``None``), the column used to split + - ``column`` -- integer (default: ``None``); the column used to split the problem, if ``None`` a random column is chosen - OUTPUT: - - list of solutions + OUTPUT: list of solutions EXAMPLES:: @@ -802,19 +791,17 @@ cdef class dancing_linksWrapper: INPUT: - - ``ncpus`` -- integer (default: ``None``), maximal number of + - ``ncpus`` -- integer (default: ``None``); maximal number of subprocesses to use at the same time. If ``ncpus>1`` the dancing links problem is split into independent subproblems to allow parallel computation. If ``None``, it detects the number of effective CPUs in the system using :func:`sage.parallel.ncpus.ncpus()`. - - ``column`` -- integer (default: ``None``), the column used to split + - ``column`` -- integer (default: ``None``); the column used to split the problem, if ``None`` a random column is chosen (this argument is ignored if ``ncpus`` is ``1``) - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -910,9 +897,7 @@ cdef class dancing_linksWrapper: possible values include ``'picosat'``, ``'cryptominisat'``, ``'LP'``, ``'glucose'``, ``'glucose-syrup'``. - OUTPUT: - - SAT solver instance + OUTPUT: SAT solver instance EXAMPLES:: @@ -925,7 +910,6 @@ cdef class dancing_linksWrapper: sage: x.to_sat_solver('cryptominisat') # optional - pycryptosat # needs sage.sat CryptoMiniSat solver: 4 variables, 7 clauses. - """ from sage.sat.solvers.satsolver import SAT s = SAT(solver) @@ -960,9 +944,7 @@ cdef class dancing_linksWrapper: possible values include ``'picosat'``, ``'cryptominisat'``, ``'LP'``, ``'glucose'``, ``'glucose-syrup'``. - OUTPUT: - - list of rows or ``None`` if no solution is found + OUTPUT: list of rows or ``None`` if no solution is found .. NOTE:: @@ -1010,10 +992,10 @@ cdef class dancing_linksWrapper: INPUT: - - ``solver`` -- string or ``None`` (default: ``None``), possible + - ``solver`` -- string or ``None`` (default: ``None``); possible values include ``'GLPK'``, ``'GLPK/exact'``, ``'Coin'``, ``'CPLEX'``, ``'Gurobi'``, ``'CVXOPT'``, ``'PPL'``, - ``'InteractiveLP'``. + ``'InteractiveLP'`` OUTPUT: @@ -1031,8 +1013,8 @@ cdef class dancing_linksWrapper: sage: x # needs sage.numerical.mip MIPVariable with 4 binary components - In the reduction, the boolean variable x_i is True if and only if - the i-th row is in the solution:: + In the reduction, the boolean variable `x_i` is ``True`` if and only if + the `i`-th row is in the solution:: sage: p.show() # needs sage.numerical.mip Maximization: @@ -1054,7 +1036,6 @@ cdef class dancing_linksWrapper: sage: d.to_milp('gurobi') # optional - gurobi sage_numerical_backends_gurobi, needs sage.numerical.mip (Boolean Program (no objective, 4 variables, 4 constraints), MIPVariable with 4 binary components) - """ from sage.numerical.mip import MixedIntegerLinearProgram p = MixedIntegerLinearProgram(solver=solver) @@ -1082,14 +1063,12 @@ cdef class dancing_linksWrapper: INPUT: - - ``solver`` -- string or ``None`` (default: ``None``), possible + - ``solver`` -- string or ``None`` (default: ``None``); possible values include ``'GLPK'``, ``'GLPK/exact'``, ``'Coin'``, ``'CPLEX'``, ``'Gurobi'``, ``'CVXOPT'``, ``'PPL'``, - ``'InteractiveLP'``. - - OUTPUT: + ``'InteractiveLP'`` - list of rows or ``None`` if no solution is found + OUTPUT: list of rows or ``None`` if no solution is found .. NOTE:: diff --git a/src/sage/combinat/matrices/dlxcpp.py b/src/sage/combinat/matrices/dlxcpp.py index 3cdc3774d76..15c6eddbbdc 100644 --- a/src/sage/combinat/matrices/dlxcpp.py +++ b/src/sage/combinat/matrices/dlxcpp.py @@ -24,11 +24,11 @@ def DLXCPP(rows): """ - Solves the Exact Cover problem by using the Dancing Links algorithm + Solve the Exact Cover problem by using the Dancing Links algorithm described by Knuth. Consider a matrix M with entries of 0 and 1, and compute a subset - of the rows of this matrix which sum to the vector of all 1's. + of the rows of this matrix which sum to the vector of all 1s. The dancing links algorithm works particularly well for sparse matrices, so the input is a list of lists of the form:: @@ -89,7 +89,7 @@ def DLXCPP(rows): def AllExactCovers(M): """ - Solves the exact cover problem on the matrix M (treated as a dense + Solve the exact cover problem on the matrix M (treated as a dense binary matrix). EXAMPLES: No exact covers:: @@ -117,7 +117,7 @@ def AllExactCovers(M): def OneExactCover(M): """ - Solves the exact cover problem on the matrix M (treated as a dense + Solve the exact cover problem on the matrix M (treated as a dense binary matrix). EXAMPLES:: diff --git a/src/sage/combinat/matrices/hadamard_matrix.py b/src/sage/combinat/matrices/hadamard_matrix.py index 34b12f6577e..c08812c5a83 100644 --- a/src/sage/combinat/matrices/hadamard_matrix.py +++ b/src/sage/combinat/matrices/hadamard_matrix.py @@ -125,7 +125,7 @@ def normalise_hadamard(H, skew=False): sage: is_hadamard_matrix(H, skew=True, normalized=True) True - If ``skew`` is True but the Hadamard matrix is not skew, the matrix returned + If ``skew`` is ``True`` but the Hadamard matrix is not skew, the matrix returned will not be normalized:: sage: H = normalise_hadamard(hadamard_matrix(92), skew=True) @@ -710,8 +710,7 @@ def construction_four_symbol_delta_code_I(X, Y, Z, W): - ``Z`` -- list; the third sequence (length `n`) - ``W`` -- list; the fourth sequence (length `n`) - OUTPUT: - A tuple containing the 4-symbol `\delta` code of length `2n+1`. + OUTPUT: tuple containing the 4-symbol `\delta` code of length `2n+1` EXAMPLES:: @@ -780,8 +779,7 @@ def construction_four_symbol_delta_code_II(X, Y, Z, W): - ``Z`` -- list; the third sequence (length `n`) - ``W`` -- list; the fourth sequence (length `n`) - OUTPUT: - A tuple containing the four 4-symbol `\delta` code of length `4n+3`. + OUTPUT: tuple containing the four 4-symbol `\delta` code of length `4n+3` EXAMPLES:: @@ -802,7 +800,6 @@ def construction_four_symbol_delta_code_II(X, Y, Z, W): Traceback (most recent call last): ... AssertionError - """ n = len(Z) @@ -909,10 +906,10 @@ def _construction_goethals_seidel_matrix(A, B, C, D): INPUT: - - ``A`` -- The first matrix used in the construction - - ``B`` -- The second matrix used in the construction - - ``C`` -- The third matrix used in the construction - - ``D`` -- The fourth matrix used in the construction + - ``A`` -- the first matrix used in the construction + - ``B`` -- the second matrix used in the construction + - ``C`` -- the third matrix used in the construction + - ``D`` -- the fourth matrix used in the construction TESTS:: @@ -1050,7 +1047,7 @@ def hadamard_matrix_cooper_wallis_construction(x1, x2, x3, x4, A, B, C, D, check - ``C`` -- the matrix described above - ``D`` -- the matrix described above - ``check`` -- boolean (default: ``True``); if ``True``, check that the resulting - matrix is Hadamard before returing it. + matrix is Hadamard before returing it EXAMPLES:: @@ -1127,7 +1124,7 @@ def hadamard_matrix_cooper_wallis_smallcases(n, check=True, existence=False): - ``check`` -- boolean (default: ``True``); if ``True``, check that the matrix is a Hadamard matrix before returning - ``existence`` -- boolean (default: ``False``); if ``True``, only check if - the matrix exists. + the matrix exists OUTPUT: @@ -1293,10 +1290,10 @@ def hadamard_matrix_turyn_type(a, b, c, d, e1, e2, e3, e4, check=True): - ``b`` -- 1,-1 list; the 1st row of `B` - ``d`` -- 1,-1 list; the 1st row of `C` - ``c`` -- 1,-1 list; the 1st row of `D` - - ``e1`` -- Matrix; the first Baumert-Hall unit - - ``e2`` -- Matrix; the second Baumert-Hall unit - - ``e3`` -- Matrix; the third Baumert-Hall unit - - ``e4`` -- Matrix; the fourth Baumert-Hall unit + - ``e1`` -- matrix; the first Baumert-Hall unit + - ``e2`` -- matrix; the second Baumert-Hall unit + - ``e3`` -- matrix; the third Baumert-Hall unit + - ``e4`` -- matrix; the fourth Baumert-Hall unit - ``check`` -- boolean (default: ``True``); whether to check that the output is a Hadamard matrix before returning it @@ -1362,9 +1359,9 @@ def turyn_type_hadamard_matrix_smallcases(n, existence=False, check=True): INPUT: - ``n`` -- integer; the order of the matrix to be constructed - - ``existence`` -- boolean (default: ``False``): if ``True``, only check if + - ``existence`` -- boolean (default: ``False``); if ``True``, only check if the matrix exists - - ``check`` -- boolean (default: ``True``): if ``True``, check that the matrix + - ``check`` -- boolean (default: ``True``); if ``True``, check that the matrix is a Hadamard matrix before returning EXAMPLES:: @@ -1643,7 +1640,7 @@ def is_skew_hadamard_matrix(M, normalized=False, verbose=False): @matrix_method def hadamard_matrix(n, existence=False, check=True, construction_name=False): r""" - Tries to construct a Hadamard matrix using the available methods. + Try to construct a Hadamard matrix using the available methods. Currently all orders `\le 1200` for which a construction is known are implemented. For `n > 1200`, only some orders are available. @@ -1658,11 +1655,11 @@ def hadamard_matrix(n, existence=False, check=True, construction_name=False): - ``True`` -- meaning that Sage knows how to build the matrix - ``Unknown`` -- meaning that Sage does not know how to build the matrix, although the matrix may exist (see :mod:`sage.misc.unknown`). - - ``False`` -- meaning that the matrix does not exist. + - ``False`` -- meaning that the matrix does not exist - - ``check`` -- boolean (default: ``True``); whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. - ``construction_name`` -- boolean (default: ``False``); if it is ``True``, ``existence`` is ``True``, and a matrix exists, output the construction name. It has no effect if ``existence`` is set to ``False``. @@ -2205,7 +2202,7 @@ def rshcd_from_close_prime_powers(n): INPUT: - - ``n`` -- an integer congruent to `0\pmod{4}` + - ``n`` -- integer congruent to `0\pmod{4}` .. SEEALSO:: @@ -2259,7 +2256,7 @@ def rshcd_from_close_prime_powers(n): def williamson_goethals_seidel_skew_hadamard_matrix(a, b, c, d, check=True): r""" - Williamson-Goethals-Seidel construction of a skew Hadamard matrix + Williamson-Goethals-Seidel construction of a skew Hadamard matrix. Given `n\times n` (anti)circulant matrices `A`, `B`, `C`, `D` with 1,-1 entries, and satisfying `A+A^\top = 2I`, `AA^\top + BB^\top + CC^\top + DD^\top = 4nI`, @@ -2271,7 +2268,7 @@ def williamson_goethals_seidel_skew_hadamard_matrix(a, b, c, d, check=True): - ``b`` -- 1,-1 list; the 1st row of `B` - ``d`` -- 1,-1 list; the 1st row of `C` - ``c`` -- 1,-1 list; the 1st row of `D` - - ``check`` -- boolean (default: ``True``); if ``True``, check that the + - ``check`` -- boolean (default: ``True``); if ``True``, check that the resulting matrix is skew Hadamard before returning it EXAMPLES:: @@ -2314,7 +2311,7 @@ def skew_hadamard_matrix_spence_construction(n, check=True): INPUT: - ``n`` -- positive integer - - ``check`` -- boolean (default: ``True``); if ``True``, check that the + - ``check`` -- boolean (default: ``True``); if ``True``, check that the resulting matrix is Hadamard before returning it OUTPUT: @@ -2512,7 +2509,7 @@ def get_fixed_set(s, G, q): def GS_skew_hadamard_smallcases(n, existence=False, check=True): r""" - Data for Williamson-Goethals-Seidel construction of skew Hadamard matrices + Data for Williamson-Goethals-Seidel construction of skew Hadamard matrices. Here we keep the data for this construction. Namely, it needs 4 circulant matrices with extra properties, as described in @@ -2534,7 +2531,7 @@ def GS_skew_hadamard_smallcases(n, existence=False, check=True): - ``n`` -- integer; the order of the matrix - ``existence`` -- boolean (default: ``True``); if ``True``, only check that we can do the construction - - ``check`` -- boolean (default: ``False``): if ``True``, check the result + - ``check`` -- boolean (default: ``False``); if ``True``, check the result TESTS:: @@ -2801,7 +2798,7 @@ def skew_hadamard_matrix_whiteman_construction(n, existence=False, check=True): INPUT: - ``n`` -- positive integer; the order of the matrix to be constructed - - ``existence`` -- boolean (default: ``False``); If ``True``, only return + - ``existence`` -- boolean (default: ``False``); if ``True``, only return whether the Hadamard matrix can be constructed - ``check`` -- boolean (default: ``True``); if ``True``, check that the result is a skew Hadamard matrix before returning it @@ -2992,9 +2989,9 @@ def skew_hadamard_matrix_from_good_matrices_smallcases(n, existence=False, check INPUT: - ``n`` -- integer; the order of the skew Hadamard matrix to be constructed - - ``existence`` -- boolean (default: ``False``); If ``True``, only return + - ``existence`` -- boolean (default: ``False``); if ``True``, only return whether the Hadamard matrix can be constructed - - ``check`` -- boolean (default: ``True``): if ``True``, check that the matrix + - ``check`` -- boolean (default: ``True``); if ``True``, check that the matrix is a Hadamard matrix before returning it OUTPUT: @@ -3084,7 +3081,7 @@ def pm_to_good_matrix(s, sign=1): def skew_hadamard_matrix(n, existence=False, skew_normalize=True, check=True, construction_name=False): r""" - Tries to construct a skew Hadamard matrix. + Try to construct a skew Hadamard matrix. A Hadamard matrix `H` is called skew if `H=S-I`, for `I` the identity matrix and `-S=S^\top`. Currently all orders `\le 1200` for which a construction is @@ -3100,13 +3097,13 @@ def skew_hadamard_matrix(n, existence=False, skew_normalize=True, check=True, - ``True`` -- meaning that Sage knows how to build the matrix - ``Unknown`` -- meaning that Sage does not know how to build the matrix, but that the design may exist (see :mod:`sage.misc.unknown`). - - ``False`` -- meaning that the matrix does not exist. + - ``False`` -- meaning that the matrix does not exist - ``skew_normalize`` -- boolean (default: ``True``); whether to make the 1st row all-one, and adjust the 1st column accordingly - ``check`` -- boolean (default: ``True``); whether to check that output is - correct before returning it. As this is expected to be useless (but we are - cautious guys), you may want to disable it whenever you want speed + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. - ``construction_name`` -- boolean (default: ``False``); if it is ``True``, ``existence`` is ``True``, and a matrix exists, output the construction name. It has no effect if ``existence`` is set to ``False``. @@ -3267,7 +3264,7 @@ def true(nam): def symmetric_conference_matrix(n, check=True): r""" - Tries to construct a symmetric conference matrix + Try to construct a symmetric conference matrix. A conference matrix is an `n\times n` matrix `C` with 0s on the main diagonal and 1s and -1s elsewhere, satisfying `CC^\top=(n-1)I`. @@ -3280,8 +3277,8 @@ def symmetric_conference_matrix(n, check=True): - ``n`` -- integer; dimension of the matrix - ``check`` -- boolean (default: ``True``); whether to check that output is - correct before returning it. As this is expected to be useless (but we are - cautious guys), you may want to disable it whenever you want speed + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES:: @@ -3313,7 +3310,7 @@ def symmetric_conference_matrix(n, check=True): def szekeres_difference_set_pair(m, check=True): r""" - Construct Szekeres `(2m+1,m,1)`-cyclic difference family + Construct Szekeres `(2m+1,m,1)`-cyclic difference family. Let `4m+3` be a prime power. Theorem 3 in [Sz1969]_ contains a construction of a pair of *complementary difference sets* `A`, `B` in the subgroup `G` of the quadratic @@ -3363,7 +3360,7 @@ def szekeres_difference_set_pair(m, check=True): def typeI_matrix_difference_set(G, A): r""" - (1,-1)-incidence type I matrix of a difference set `A` in `G` + (1,-1)-incidence type I matrix of a difference set `A` in `G`. Let `A` be a difference set in a group `G` of order `n`. Return `n\times n` matrix `M` with `M_{ij}=1` if `A_i A_j^{-1} \in A`, and `M_{ij}=-1` otherwise. @@ -3386,7 +3383,7 @@ def typeI_matrix_difference_set(G, A): def rshcd_from_prime_power_and_conference_matrix(n): r""" - Return a `((n-1)^2,1)`-RSHCD if `n` is prime power, and symmetric `(n-1)`-conference matrix exists + Return a `((n-1)^2,1)`-RSHCD if `n` is prime power, and symmetric `(n-1)`-conference matrix exists. The construction implemented here is Theorem 16 (and Corollary 17) from [WW1972]_. @@ -3401,7 +3398,7 @@ def rshcd_from_prime_power_and_conference_matrix(n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer .. SEEALSO:: @@ -3477,7 +3474,7 @@ def are_amicable_hadamard_matrices(M, N, verbose=False): - ``M`` -- a square matrix - ``N`` -- a square matrix - - ``verbose`` -- boolean (default ``False``); whether to be verbose when the + - ``verbose`` -- boolean (default: ``False``); whether to be verbose when the matrices are not amicable Hadamard matrices EXAMPLES:: diff --git a/src/sage/combinat/matrices/latin.py b/src/sage/combinat/matrices/latin.py index 936edcc6ea4..e2d818e9480 100644 --- a/src/sage/combinat/matrices/latin.py +++ b/src/sage/combinat/matrices/latin.py @@ -331,7 +331,7 @@ def __copy__(self): def clear_cells(self): """ - Mark every cell in self as being empty. + Mark every cell in ``self`` as being empty. EXAMPLES:: @@ -406,7 +406,7 @@ def list(self): def nr_filled_cells(self): """ Return the number of filled cells (i.e. cells with a positive - value) in the partial latin square self. + value) in the partial latin square ``self``. EXAMPLES:: @@ -459,7 +459,7 @@ def actual_row_col_sym_sizes(self): def is_empty_column(self, c): """ - Check if column c of the partial latin square self is empty. + Check if column c of the partial latin square ``self`` is empty. EXAMPLES:: @@ -475,7 +475,7 @@ def is_empty_column(self, c): def is_empty_row(self, r): """ - Check if row r of the partial latin square self is empty. + Check if row r of the partial latin square ``self`` is empty. EXAMPLES:: @@ -492,7 +492,7 @@ def is_empty_row(self, r): def nr_distinct_symbols(self): """ Return the number of distinct symbols in the partial latin square - self. + ``self``. EXAMPLES:: @@ -513,7 +513,7 @@ def nr_distinct_symbols(self): def apply_isotopism(self, row_perm, col_perm, sym_perm): """ An isotopism is a permutation of the rows, columns, and symbols of - a partial latin square self. Use isotopism() to convert a tuple + a partial latin square ``self``. Use isotopism() to convert a tuple (indexed from 0) to a Permutation object. EXAMPLES:: @@ -554,11 +554,11 @@ def apply_isotopism(self, row_perm, col_perm, sym_perm): def filled_cells_map(self): """ - Number the filled cells of self with integers from {1, 2, 3, ...}. + Number the filled cells of ``self`` with integers from {1, 2, 3, ...}. INPUT: - - ``self`` -- partial latin square self (empty cells + - ``self`` -- partial latin square ``self`` (empty cells have negative values) OUTPUT: @@ -619,12 +619,12 @@ def filled_cells_map(self): def top_left_empty_cell(self): """ - Return the least [r, c] such that self[r, c] is an empty cell. If - all cells are filled then we return None. + Return the least ``[r, c]`` such that ``self[r, c]`` is an empty cell. + If all cells are filled then we return ``None``. INPUT: - - ``self`` -- LatinSquare + - ``self`` -- LatinSquare EXAMPLES:: @@ -643,7 +643,7 @@ def top_left_empty_cell(self): def is_partial_latin_square(self): """ - self is a partial latin square if it is an n by n matrix, and each + ``self`` is a partial latin square if it is an n by n matrix, and each symbol in [0, 1, ..., n-1] appears at most once in each row, and at most once in each column. @@ -704,7 +704,7 @@ def is_partial_latin_square(self): def is_latin_square(self): """ - self is a latin square if it is an n by n matrix, and each symbol + ``self`` is a latin square if it is an n by n matrix, and each symbol in [0, 1, ..., n-1] appears exactly once in each row, and exactly once in each column. @@ -736,16 +736,16 @@ def is_latin_square(self): def permissable_values(self, r, c): """ Find all values that do not appear in row r and column c of the - latin square self. If self[r, c] is filled then we return the empty - list. + latin square ``self``. If ``self[r, c]`` is filled then we return the + empty list. INPUT: - - ``self`` -- LatinSquare + - ``self`` -- LatinSquare - - ``r`` -- int; row of the latin square + - ``r`` -- integer; row of the latin square - - ``c`` -- int; column of the latin square + - ``c`` -- integer; column of the latin square EXAMPLES:: @@ -788,7 +788,7 @@ def random_empty_cell(self): INPUT: - - ``self`` -- LatinSquare + - ``self`` -- LatinSquare OUTPUT: @@ -822,7 +822,7 @@ def random_empty_cell(self): def is_uniquely_completable(self): """ - Return True if the partial latin square self has exactly one + Return ``True`` if the partial latin square ``self`` has exactly one completion to a latin square. This is just a wrapper for the current best-known algorithm, Dancing Links by Knuth. See dancing_links.spyx @@ -850,7 +850,7 @@ def is_uniquely_completable(self): def is_completable(self): """ - Return True if the partial latin square can be completed to a + Return ``True`` if the partial latin square can be completed to a latin square. EXAMPLES: @@ -888,7 +888,7 @@ def is_completable(self): def gcs(self): """ - A greedy critical set of a latin square self is found by + A greedy critical set of a latin square ``self`` is found by successively removing elements in a row-wise (bottom-up) manner, checking for unique completion at each step. @@ -934,7 +934,7 @@ def gcs(self): def dlxcpp_has_unique_completion(self): """ - Check if the partial latin square self of order n can be embedded + Check if the partial latin square ``self`` of order n can be embedded in precisely one latin square of order n. EXAMPLES:: @@ -953,7 +953,7 @@ def dlxcpp_has_unique_completion(self): def vals_in_row(self, r): """ - Return a dictionary with key e if and only if row r of self has + Return a dictionary with key e if and only if row r of ``self`` has the symbol e. EXAMPLES:: @@ -977,7 +977,7 @@ def vals_in_row(self, r): def vals_in_col(self, c): """ - Return a dictionary with key e if and only if column c of self has + Return a dictionary with key e if and only if column c of ``self`` has the symbol e. EXAMPLES:: @@ -1278,7 +1278,7 @@ def find_disjoint_mates(self, nr_to_find=None, allow_subtrade=False): def contained_in(self, Q): r""" - Return True if self is a subset of Q? + Return ``True`` if ``self`` is a subset of `Q`. EXAMPLES:: @@ -1467,20 +1467,20 @@ def isotopism(p): According to the type of input (see examples below): - - an integer `n` -- the function returns the identity on `1,...,n`. + - an integer `n` -- the function returns the identity on `1,...,n` - a string representing a permutation in disjoint cycles notation, e.g. `(0,1,2)(3,4,5)` -- the corresponding permutation is returned, - shifted by 1 to act on `1,...,n`. + shifted by 1 to act on `1,...,n` - list/tuple of tuples -- assumes disjoint cycle notation, see previous - entry. + entry - a list of integers -- the function adds `1` to each member of the - list, and returns the corresponding permutation. + list, and returns the corresponding permutation - a :class:`PermutationGroupElement` ``p`` -- returns a permutation - describing ``p`` **without** any shift. + describing ``p`` **without** any shift EXAMPLES:: @@ -1550,7 +1550,7 @@ def cells_map_as_square(cells_map, n): Return a LatinSquare with cells numbered from 1, 2, ... to given the dictionary cells_map. - .. note:: + .. NOTE:: The value n should be the maximum of the number of rows and columns of the original partial latin square @@ -1596,13 +1596,11 @@ def beta1(rce, T1, T2): INPUT: + - ``rce`` -- tuple (or list) (r, c, e) in T1 - - ``rce`` -- tuple (or list) (r, c, e) in T1 + - ``T1``, ``T2`` -- latin bitrade - - ``T1, T2`` -- latin bitrade - - - OUTPUT: (x, c, e) in T2. + OUTPUT: (x, c, e) in T2 EXAMPLES:: @@ -1637,14 +1635,11 @@ def beta2(rce, T1, T2): INPUT: - - ``rce`` -- tuple (or list) (r, c, e) in T1 - - - ``T1, T2`` -- latin bitrade + - ``rce`` -- tuple (or list) (r, c, e) in T1 + - ``T1``, ``T2`` -- latin bitrade - OUTPUT: - - - (r, x, e) in T2. + OUTPUT: (r, x, e) in T2 EXAMPLES:: @@ -1679,15 +1674,11 @@ def beta3(rce, T1, T2): INPUT: + - ``rce`` -- tuple (or list) (r, c, e) in T1 - - ``rce`` -- tuple (or list) (r, c, e) in T1 - - - ``T1, T2`` -- latin bitrade - - - OUTPUT: + - ``T1, T2`` -- latin bitrade - - (r, c, x) in T2. + OUTPUT: (r, c, x) in T2. EXAMPLES:: @@ -1728,7 +1719,7 @@ def tau1(T1, T2, cells_map): \tau_1 = \beta_2^{-1} \beta_3 where the composition is left to right and `\beta_i : T2 \rightarrow T1` - changes just the `i^{th}` coordinate of a triple. + changes just the `i`-th coordinate of a triple. EXAMPLES:: @@ -1782,7 +1773,7 @@ def tau2(T1, T2, cells_map): \tau_2 = \beta_3^{-1} \beta_1 where the composition is left to right and `\beta_i : T2 \rightarrow T1` - changes just the `i^{th}` coordinate of a triple. + changes just the `i`-th coordinate of a triple. EXAMPLES:: @@ -1836,7 +1827,7 @@ def tau3(T1, T2, cells_map): \tau_3 = \beta_1^{-1} \beta_2 where the composition is left to right and `\beta_i : T2 \rightarrow T1` - changes just the `i^{th}` coordinate of a triple. + changes just the `i`-th coordinate of a triple. EXAMPLES:: @@ -1887,7 +1878,7 @@ def back_circulant(n): INPUT: - - ``n`` -- int; order of the latin square. + - ``n`` -- integer; order of the latin square EXAMPLES:: @@ -1917,7 +1908,7 @@ def forward_circulant(n): INPUT: - - ``n`` -- int; order of the latin square. + - ``n`` -- integer; order of the latin square EXAMPLES:: @@ -1993,7 +1984,7 @@ def elementary_abelian_2group(s): INPUT: - - ``s`` -- int; order of the latin square will be 2s. + - ``s`` -- integer; order of the latin square will be 2s EXAMPLES:: @@ -2035,7 +2026,7 @@ def elementary_abelian_2group(s): def coin(): """ - Simulate a fair coin (returns True or False) using + Simulate a fair coin (returns ``True`` or ``False``) using ZZ.random_element(2). EXAMPLES:: diff --git a/src/sage/combinat/misc.py b/src/sage/combinat/misc.py index 2a4341e8f4c..404c032a8dc 100644 --- a/src/sage/combinat/misc.py +++ b/src/sage/combinat/misc.py @@ -181,7 +181,7 @@ def prev(self, j): def _monomial_exponent_to_lower_factorial(me, x): r""" - Converts a tuple of exponents to the monomial obtained by replacing + Convert a tuple of exponents to the monomial obtained by replacing each me[i] with `x_i*(x_i - 1)*\cdots*(x_i - a_i + 1)` EXAMPLES:: @@ -211,7 +211,7 @@ def _monomial_exponent_to_lower_factorial(me, x): def umbral_operation(poly): r""" - Returns the umbral operation `\downarrow` applied to poly. + Return the umbral operation `\downarrow` applied to poly. The umbral operation replaces each instance of `x_i^{a_i}` with diff --git a/src/sage/combinat/multiset_partition_into_sets_ordered.py b/src/sage/combinat/multiset_partition_into_sets_ordered.py index f6d8c5cb4ec..aae1cd569a2 100755 --- a/src/sage/combinat/multiset_partition_into_sets_ordered.py +++ b/src/sage/combinat/multiset_partition_into_sets_ordered.py @@ -96,7 +96,7 @@ class OrderedMultisetPartitionIntoSets(ClonableArray, metaclass=InheritComparisonClasscallMetaclass): r""" - Ordered Multiset Partition into sets + Ordered Multiset Partition into sets. An *ordered multiset partition into sets* `c` of a multiset `X` is a list `[c_1, \ldots, c_r]` of nonempty subsets of `X` (note: not @@ -224,7 +224,7 @@ def check(self): def _repr_(self): """ - Return a string representation of ``self.`` + Return a string representation of ``self``. EXAMPLES:: @@ -432,7 +432,7 @@ def multiset(self, as_dict=False): INPUT: - - ``as_dict`` -- (default: ``False``) whether to return the multiset + - ``as_dict`` -- boolean (default: ``False``); whether to return the multiset as a tuple of a dict of multiplicities EXAMPLES:: @@ -1127,7 +1127,7 @@ class OrderedMultisetPartitionsIntoSets(UniqueRepresentation, Parent): - Two Arguments: - + `A` -- a list (representing allowable letters within blocks of `c`), + + `A` -- list (representing allowable letters within blocks of `c`), or a positive integer (representing the maximal allowable letter) + `n` -- a nonnegative integer (the total number of letters within `c`) @@ -1912,7 +1912,7 @@ def subset(self, size): INPUT: - - ``size`` -- an integer representing a slice of all ordered + - ``size`` -- integer representing a slice of all ordered multiset partitions into sets The slice alluded to above is taken with respect to length, or @@ -3089,7 +3089,7 @@ def _refine_block(S, strong=False): def _is_initial_segment(lst): r""" - Return True if ``lst`` is an interval in `\ZZ` of the form `[0, 1, \ldots, n]`. + Return ``True`` if ``lst`` is an interval in `\ZZ` of the form `[0, 1, \ldots, n]`. EXAMPLES:: @@ -3148,7 +3148,7 @@ def _to_minimaj_blocks(T): INPUT: - - ``T`` -- a sequence of row words corresponding to (skew-)tableaux. + - ``T`` -- a sequence of row words corresponding to (skew-)tableaux OUTPUT: @@ -3416,7 +3416,7 @@ class Element(ElementWrapper): Minimaj elements `b` are stored internally as pairs ``(w, breaks)``, where: - - ``w`` is a word of length ``self.parent().ell`` over the + - ``w`` -- a word of length ``self.parent().ell`` over the letters `1` up to ``self.parent().n``; - ``breaks`` is a list of de-concatenation points to turn ``w`` into a list of row words of (skew-)tableaux that represent diff --git a/src/sage/combinat/ncsf_qsym/combinatorics.py b/src/sage/combinat/ncsf_qsym/combinatorics.py index d85efe38719..ef930596ab8 100644 --- a/src/sage/combinat/ncsf_qsym/combinatorics.py +++ b/src/sage/combinat/ncsf_qsym/combinatorics.py @@ -31,7 +31,7 @@ def coeff_pi(J, I): r""" - Returns the coefficient `\pi_{J,I}` as defined in [NCSF]_. + Return the coefficient `\pi_{J,I}` as defined in [NCSF]_. INPUT: @@ -53,7 +53,7 @@ def coeff_pi(J, I): def coeff_lp(J,I): r""" - Returns the coefficient `lp_{J,I}` as defined in [NCSF]_. + Return the coefficient `lp_{J,I}` as defined in [NCSF]_. INPUT: @@ -75,7 +75,7 @@ def coeff_lp(J,I): def coeff_ell(J,I): r""" - Returns the coefficient `\ell_{J,I}` as defined in [NCSF]_. + Return the coefficient `\ell_{J,I}` as defined in [NCSF]_. INPUT: @@ -97,7 +97,7 @@ def coeff_ell(J,I): def coeff_sp(J, I): r""" - Returns the coefficient `sp_{J,I}` as defined in [NCSF]_. + Return the coefficient `sp_{J,I}` as defined in [NCSF]_. INPUT: @@ -155,12 +155,10 @@ def compositions_order(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - - A list of the compositions of ``n`` sorted into decreasing order - by `\rhd` + OUTPUT: list of the compositions of `n` sorted into decreasing order + by `\rhd` EXAMPLES:: @@ -185,7 +183,7 @@ def m_to_s_stat(R, I, K): INPUT: - - ``R`` -- A ring, supposed to be a `\QQ`-algebra + - ``R`` -- a ring; supposed to be a `\QQ`-algebra - ``I``, ``K`` -- compositions OUTPUT: @@ -226,9 +224,7 @@ def number_of_fCT(content_comp, shape_comp): - ``content_comp``, ``shape_comp`` -- compositions - OUTPUT: - - - An integer + OUTPUT: integer EXAMPLES:: @@ -274,9 +270,7 @@ def number_of_SSRCT(content_comp, shape_comp): - ``content_comp``, ``shape_comp`` -- compositions - OUTPUT: - - - An integer + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/combinat/ncsf_qsym/generic_basis_code.py b/src/sage/combinat/ncsf_qsym/generic_basis_code.py index 4fe908d727c..7b2260f3be9 100644 --- a/src/sage/combinat/ncsf_qsym/generic_basis_code.py +++ b/src/sage/combinat/ncsf_qsym/generic_basis_code.py @@ -57,7 +57,6 @@ def _repr_object_names(self): 'bases of Non-Commutative Symmetric Functions or Quasisymmetric functions over the Rational Field' sage: C Category of bases of Non-Commutative Symmetric Functions or Quasisymmetric functions over the Rational Field - """ return "bases of Non-Commutative Symmetric Functions or Quasisymmetric functions over the %s" % self.base().base_ring() @@ -132,9 +131,7 @@ def one_basis(self): r""" Return the empty composition. - OUTPUT: - - - The empty composition. + OUTPUT: the empty composition EXAMPLES:: @@ -209,7 +206,7 @@ def alternating_sum_of_compositions(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -243,7 +240,7 @@ def alternating_sum_of_finer_compositions(self, composition, conjugate=False): INPUT: - ``composition`` -- a composition - - ``conjugate`` -- (default: ``False``) a boolean + - ``conjugate`` -- boolean (default: ``False``) OUTPUT: @@ -633,8 +630,8 @@ def duality_pairing_matrix(self, basis, degree): INPUT: - - ``basis`` -- A basis of the dual Hopf algebra - - ``degree`` -- a non-negative integer + - ``basis`` -- a basis of the dual Hopf algebra + - ``degree`` -- nonnegative integer OUTPUT: @@ -857,9 +854,7 @@ def duality_pairing(self, y): - ``y`` -- an element of the dual Hopf algebra of ``self`` - OUTPUT: - - - The result of pairing ``self`` with ``y``. + OUTPUT: the result of pairing ``self`` with ``y`` EXAMPLES:: @@ -878,7 +873,6 @@ def duality_pairing(self, y): 0 sage: L[1,1,1].duality_pairing(F[1,2]) 1 - """ return self.parent().duality_pairing(self, y) @@ -893,11 +887,9 @@ def skew_by(self, y, side='left'): INPUT: - ``y`` -- an element of the dual Hopf algebra of ``self`` - - ``side`` -- (Default='left') Either 'left' or 'right' + - ``side`` -- (default: ``'left'``) either ``'left'`` or ``'right'`` - OUTPUT: - - - The result of skewing ``self`` by ``y``, on the side ``side`` + OUTPUT: the result of skewing ``self`` by ``y``, on the side ``side`` EXAMPLES: @@ -1008,13 +1000,11 @@ def __init__(self, domain, on_generators, position=0, codomain=None, category=No - ``domain`` -- an algebra with a multiplicative basis - ``on_generators`` -- a function defined on the index set of the generators - ``codomain`` -- the codomain - - ``position`` -- integer; default is 0 - - ``category`` -- a category; defaults to None - - ``anti`` -- a boolean; defaults to False - - OUTPUT: + - ``position`` -- integer (default: 0) + - ``category`` -- a category (default: ``None``) + - ``anti`` -- boolean (default: ``False``) - - module morphism + OUTPUT: module morphism EXAMPLES: @@ -1132,16 +1122,14 @@ def __ne__(self, other): def _on_basis(self, c): r""" - Computes the image of this morphism on the basis element indexed by + Compute the image of this morphism on the basis element indexed by ``c``. INPUT: - ``c`` -- an iterable that spits out generators - OUTPUT: - - - element of the codomain + OUTPUT: element of the codomain EXAMPLES:: @@ -1152,7 +1140,6 @@ def _on_basis(self, c): sage: f = AlgebraMorphism(Psi, lambda i : Phi[i,i], codomain=Phi) sage: f._on_basis([ 3, 2 ]) Phi[3, 3, 2, 2] - """ if self._anti: c = reversed(c) @@ -1161,7 +1148,7 @@ def _on_basis(self, c): class GradedModulesWithInternalProduct(Category_over_base_ring): r""" - Constructs the class of modules with internal product. This is used to give an internal + Construct the class of modules with internal product. This is used to give an internal product structure to the non-commutative symmetric functions. EXAMPLES:: @@ -1194,7 +1181,7 @@ def internal_product_on_basis(self, I, J): INPUT: - - ``I``, ``J`` -- compositions indexing two elements of the basis of self + - ``I``, ``J`` -- compositions indexing two elements of the basis of self Returns the internal product of the corresponding basis elements. If this method is implemented, the internal product is defined from @@ -1247,7 +1234,6 @@ def internal_product(self): R[2] sage: R.internal_product(R[2,2], R[1,2]) 0 - """ if self.internal_product_on_basis is not NotImplemented: return self.module_morphism( @@ -1426,9 +1412,7 @@ def internal_product_by_coercion(self, left, right): - ``left`` -- an element of the non-commutative symmetric functions - ``right`` -- an element of the non-commutative symmetric functions - OUTPUT: - - - The internal product of ``left`` and ``right``. + OUTPUT: the internal product of ``left`` and ``right`` EXAMPLES:: diff --git a/src/sage/combinat/ncsf_qsym/ncsf.py b/src/sage/combinat/ncsf_qsym/ncsf.py index dbab31a0080..c1c1ef90306 100644 --- a/src/sage/combinat/ncsf_qsym/ncsf.py +++ b/src/sage/combinat/ncsf_qsym/ncsf.py @@ -78,7 +78,7 @@ class NonCommutativeSymmetricFunctions(UniqueRepresentation, Parent): We use the Sage standard renaming idiom to get shorter outputs:: - sage: NCSF.rename("NCSF") + sage: NCSF.rename('NCSF') sage: NCSF NCSF @@ -101,9 +101,9 @@ class NonCommutativeSymmetricFunctions(UniqueRepresentation, Parent): The basis itself is accessible through:: sage: Psi.basis() - Lazy family (Term map from Compositions of non-negative integers... + Lazy family (Term map from Compositions of nonnegative integers... sage: Psi.basis().keys() - Compositions of non-negative integers + Compositions of nonnegative integers To construct an element one can therefore do:: @@ -401,7 +401,6 @@ class NonCommutativeSymmetricFunctions(UniqueRepresentation, Parent): sage: TestSuite(Phi).run() sage: TestSuite(Psi).run() sage: TestSuite(complete).run() - """ def __init__(self, R): @@ -458,7 +457,7 @@ def _repr_(self): # could be taken care of by the category def a_realization(self): r""" - Gives a realization of the algebra of non-commutative symmetric functions. This + Give a realization of the algebra of non-commutative symmetric functions. This particular realization is the complete basis of non-commutative symmetric functions. OUTPUT: @@ -512,9 +511,7 @@ def super_categories(self): Return the super categories of the category of bases of the non-commutative symmetric functions. - OUTPUT: - - - list + OUTPUT: list TESTS:: @@ -522,7 +519,6 @@ def super_categories(self): sage: N.Bases().super_categories() [Category of bases of Non-Commutative Symmetric Functions or Quasisymmetric functions over the Rational Field, Category of realizations of graded modules with internal product over Rational Field] - """ R = self.base().base_ring() from .generic_basis_code import GradedModulesWithInternalProduct @@ -781,7 +777,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -1680,9 +1676,7 @@ def to_symmetric_function(self): r""" Return the commutative image of a non-commutative symmetric function. - OUTPUT: - - - The commutative image of ``self``. This will be a symmetric function. + OUTPUT: the commutative image of ``self``; this will be a symmetric function EXAMPLES:: @@ -1922,20 +1916,18 @@ def to_fsym(self): def expand(self, n, alphabet='x'): r""" Expand the noncommutative symmetric function into an - element of a free algebra in ``n`` indeterminates of + element of a free algebra in `n` indeterminates of an alphabet, which by default is ``'x'``. INPUT: - - ``n`` -- a nonnegative integer; the number of variables + - ``n`` -- nonnegative integer; the number of variables in the expansion - - ``alphabet`` -- (default: ``'x'``); the alphabet in + - ``alphabet`` -- (default: ``'x'``) the alphabet in which ``self`` is to be expanded - OUTPUT: - - - An expansion of ``self`` into the ``n`` variables - specified by ``alphabet``. + OUTPUT: an expansion of ``self`` into the `n` variables + specified by ``alphabet`` EXAMPLES:: @@ -1962,7 +1954,7 @@ def expand(self, n, alphabet='x'): One can use a different set of variables by adding an optional argument ``alphabet=...``:: - sage: L[3].expand(4, alphabet="y") + sage: L[3].expand(4, alphabet='y') y2*y1*y0 + y3*y1*y0 + y3*y2*y0 + y3*y2*y1 TESTS:: @@ -2028,16 +2020,13 @@ def super_categories(self): Return the super categories of the category of multiplicative bases of the non-commutative symmetric functions. - OUTPUT: - - - list + OUTPUT: list TESTS:: sage: N = NonCommutativeSymmetricFunctions(QQ) sage: N.MultiplicativeBases().super_categories() [Category of bases of Non-Commutative Symmetric Functions over the Rational Field] - """ return [self.base().Bases()] @@ -2049,9 +2038,7 @@ def algebra_generators(self): Return the algebra generators of a given multiplicative basis of non-commutative symmetric functions. - OUTPUT: - - - The family of generators of the multiplicative basis ``self``. + OUTPUT: the family of generators of the multiplicative basis ``self`` EXAMPLES:: @@ -2104,8 +2091,8 @@ def algebra_morphism(self, on_generators, **keywords): - ``on_generators`` -- a function defined on the index set of the generators (that is, on the positive integers) - - ``anti`` -- a boolean; defaults to ``False`` - - ``category`` -- a category; defaults to ``None`` + - ``anti`` -- boolean (default: ``False``) + - ``category`` -- a category (default: ``None``) OUTPUT: @@ -2303,9 +2290,7 @@ def super_categories(self): bases of group-like elements of the non-commutative symmetric functions. - OUTPUT: - - - list + OUTPUT: list TESTS:: @@ -2351,17 +2336,15 @@ def antipode_on_basis(self, composition): # @cached_method? def coproduct_on_generators(self, i): r""" - Return the image of the `i^{th}` generator of the algebra under + Return the image of the `i`-th generator of the algebra under the coproduct. INPUT: - - ``i`` -- a positive integer - - OUTPUT: + - ``i`` -- positive integer - - The result of applying the coproduct to the `i^{th}` - generator of ``self``. + OUTPUT: the result of applying the coproduct to the `i`-th + generator of ``self`` EXAMPLES:: @@ -2426,9 +2409,7 @@ def super_categories(self): bases of primitive elements of the non-commutative symmetric functions. - OUTPUT: - - - list + OUTPUT: list TESTS:: @@ -2448,13 +2429,13 @@ def antipode_on_generators(self, i): INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer OUTPUT: - - The image of the `i`-th generator of the multiplicative - basis ``self`` under the antipode of the algebra of - non-commutative symmetric functions. + The image of the `i`-th generator of the multiplicative basis + ``self`` under the antipode of the algebra of non-commutative + symmetric functions. EXAMPLES:: @@ -2475,17 +2456,15 @@ def antipode_on_generators(self, i): def coproduct_on_generators(self, i): r""" - Return the image of the `i^{th}` generator of the + Return the image of the `i`-th generator of the multiplicative basis ``self`` under the coproduct. INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer - OUTPUT: - - - The result of applying the coproduct to the - `i^{th}` generator of ``self``. + OUTPUT: the result of applying the coproduct to the + `i`-th generator of ``self`` EXAMPLES:: @@ -2587,9 +2566,7 @@ def dual(self): Return the dual basis to the ribbon basis of the non-commutative symmetric functions. This is the Fundamental basis of the quasi-symmetric functions. - OUTPUT: - - - The fundamental basis of the quasi-symmetric functions. + OUTPUT: the fundamental basis of the quasi-symmetric functions EXAMPLES:: @@ -2608,9 +2585,7 @@ def product_on_basis(self, I, J): - ``I``, ``J`` -- compositions - OUTPUT: - - - The product of the ribbon functions indexed by ``I`` and ``J``. + OUTPUT: the product of the ribbon functions indexed by ``I`` and ``J`` EXAMPLES:: @@ -2777,7 +2752,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -2985,9 +2960,7 @@ def dual(self): Return the dual basis to the complete basis of non-commutative symmetric functions. This is the Monomial basis of quasi-symmetric functions. - OUTPUT: - - - The Monomial basis of quasi-symmetric functions. + OUTPUT: the Monomial basis of quasi-symmetric functions EXAMPLES:: @@ -3030,7 +3003,7 @@ def internal_product_on_basis(self, I, J): def to_symmetric_function_on_basis(self, I): r""" - The commutative image of a complete element + The commutative image of a complete element. The commutative image of a basis element is obtained by sorting the indexing composition of the basis element and the output @@ -3353,7 +3326,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -3680,12 +3653,10 @@ def _from_complete_on_generators(self, n): INPUT: - - ``n`` -- a positive integer - - OUTPUT: + - ``n`` -- positive integer - - The expansion of the complete generator indexed by ``n`` into the - Psi basis. + OUTPUT: the expansion of the complete generator indexed by ``n`` + into the Psi basis TESTS:: @@ -3720,12 +3691,10 @@ def _to_complete_on_generators(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - - The expansion of the `\Psi` function indexed by ``n`` in the - complete basis. + OUTPUT: the expansion of the `\Psi` function indexed by ``n`` in + the complete basis TESTS:: @@ -3994,7 +3963,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -4114,7 +4083,6 @@ def __init__(self, NCSF): True sage: all(Phi(S(Phi[comp])) == Phi[comp] for comp in Compositions(5)) True - """ CombinatorialFreeModule.__init__(self, NCSF.base_ring(), Compositions(), prefix='Phi', bracket=False, @@ -4127,12 +4095,10 @@ def _from_complete_on_generators(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - - The expansion of the complete function indexed by ``n`` in the - `\Phi` basis. + OUTPUT: the expansion of the complete function indexed by ``n`` in + the `\Phi` basis TESTS:: @@ -4157,12 +4123,10 @@ def _to_complete_on_generators(self, n): INPUT: - - ``n`` -- a positive integer - - OUTPUT: + - ``n`` -- positive integer - - The expansion of the `\Phi` function indexed by ``n`` in the - complete basis. + OUTPUT: the expansion of the `\Phi` function indexed by ``n`` in + the complete basis TESTS:: @@ -4255,7 +4219,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -4513,7 +4477,6 @@ def __init__(self, NCSF): True sage: all(nM(S(nM[comp])) == nM[comp] for comp in Compositions(5)) True - """ CombinatorialFreeModule.__init__(self, NCSF.base_ring(), Compositions(), prefix='nM', bracket=False, @@ -4675,7 +4638,6 @@ def __init__(self, NCSF): True sage: all(I(S(I[comp])) == I[comp] for comp in Compositions(5)) True - """ CombinatorialFreeModule.__init__(self, NCSF.base_ring(), Compositions(), prefix='I', bracket=False, @@ -4713,7 +4675,7 @@ def _H(self, alpha): INPUT: - - ``alpha`` -- a list + - ``alpha`` -- list OUTPUT: @@ -4807,9 +4769,7 @@ def dual(self): The basis returned is the dualImmaculate basis of QSym. - OUTPUT: - - - The dualImmaculate basis of the quasi-symmetric functions. + OUTPUT: the dualImmaculate basis of the quasi-symmetric functions EXAMPLES:: @@ -4872,7 +4832,7 @@ def bernstein_creation_operator(self, n): sage: S(elt).bernstein_creation_operator(1) == S(elt.bernstein_creation_operator(1)) True - Check on non-positive values of `n`:: + Check on nonpositive values of `n`:: sage: I[2,2,2].bernstein_creation_operator(-1) I[1, 1, 1, 2] + I[1, 1, 2, 1] + I[1, 2, 1, 1] - I[1, 2, 2] @@ -5001,11 +4961,9 @@ def _to_complete_transition_matrix(self, n): INPUT: - - ``n`` -- an integer - - OUTPUT: + - ``n`` -- integer - - a pair of a square matrix and the ordered list of compositions + OUTPUT: a pair of a square matrix and the ordered list of compositions EXAMPLES:: @@ -5040,9 +4998,7 @@ def _to_complete_on_basis(self, comp): - ``comp`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the complete basis + OUTPUT: a quasi-symmetric function in the complete basis EXAMPLES:: @@ -5097,9 +5053,7 @@ def dual(self): :class:`~sage.combinat.ncsf_qsym.qsym.QuasiSymmetricFunctions.Quasisymmetric_Schur` basis of QSym. - OUTPUT: - - - the Quasisymmetric-Schur basis of the quasi-symmetric functions + OUTPUT: the Quasisymmetric-Schur basis of the quasi-symmetric functions EXAMPLES:: @@ -5117,7 +5071,7 @@ def dual(self): def to_symmetric_function_on_basis(self, I): r""" - The commutative image of a dual quasi-symmetric Schur element + The commutative image of a dual quasi-symmetric Schur element. The commutative image of a basis element is obtained by sorting the indexing composition of the basis element. @@ -5236,9 +5190,7 @@ def _to_complete_on_basis(self, comp): - ``comp`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the complete basis + OUTPUT: a quasi-symmetric function in the complete basis EXAMPLES:: @@ -5286,9 +5238,7 @@ def dual(self): :class:`~sage.combinat.ncsf_qsym.qsym.QuasiSymmetricFunctions.Quasisymmetric_Schur` basis of QSym. - OUTPUT: - - - the Young Quasisymmetric-Schur basis of quasi-symmetric functions + OUTPUT: the Young Quasisymmetric-Schur basis of quasi-symmetric functions EXAMPLES:: @@ -5428,7 +5378,7 @@ def _to_complete_on_generator(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -5604,7 +5554,7 @@ def _to_complete_on_generator(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: diff --git a/src/sage/combinat/ncsf_qsym/qsym.py b/src/sage/combinat/ncsf_qsym/qsym.py index 23a9003b506..26b029810cd 100644 --- a/src/sage/combinat/ncsf_qsym/qsym.py +++ b/src/sage/combinat/ncsf_qsym/qsym.py @@ -623,9 +623,7 @@ def a_realization(self): r""" Return the realization of the Monomial basis of the ring of quasi-symmetric functions. - OUTPUT: - - - The Monomial basis of quasi-symmetric functions. + OUTPUT: the Monomial basis of quasi-symmetric functions EXAMPLES:: @@ -641,9 +639,7 @@ def dual(self): Return the dual Hopf algebra of the quasi-symmetric functions, which is the non-commutative symmetric functions. - OUTPUT: - - - The non-commutative symmetric functions. + OUTPUT: the non-commutative symmetric functions EXAMPLES:: @@ -663,12 +659,10 @@ def from_polynomial(self, f, check=True): - ``f`` -- a polynomial in finitely many variables over the same base ring as ``self``. It is assumed that this polynomial is quasi-symmetric. - - ``check`` -- boolean (default: ``True``), checks whether the - polynomial is indeed quasi-symmetric. - - OUTPUT: + - ``check`` -- boolean (default: ``True``); checks whether the + polynomial is indeed quasi-symmetric - - quasi-symmetric function in the Monomial basis + OUTPUT: quasi-symmetric function in the Monomial basis EXAMPLES:: @@ -729,9 +723,7 @@ def super_categories(self): r""" Return the super categories of bases of the Quasi-symmetric functions. - OUTPUT: - - - a list of categories + OUTPUT: list of categories TESTS:: @@ -760,12 +752,10 @@ def from_polynomial(self, f, check=True): - ``f`` -- a polynomial in finitely many variables over the same base ring as ``self``. It is assumed that this polynomial is quasi-symmetric. - - ``check`` -- boolean (default: ``True``), checks whether the - polynomial is indeed quasi-symmetric. + - ``check`` -- boolean (default: ``True``); checks whether the + polynomial is indeed quasi-symmetric - OUTPUT: - - - quasi-symmetric function + OUTPUT: quasi-symmetric function EXAMPLES:: @@ -876,7 +866,7 @@ def internal_coproduct(self): #. If `I` is a composition, then a `(0, I)`-matrix will mean a matrix whose entries are nonnegative integers such that no row and no column of this matrix is zero, and such that if - all the non-zero entries of the matrix are read (row by row, + all the nonzero entries of the matrix are read (row by row, starting at the topmost row, reading every row from left to right), then the reading word obtained is `I`. If `A` is a `(0, I)`-matrix, then `\mathrm{row}(A)` will denote the @@ -1108,7 +1098,7 @@ def adams_operator(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -1576,15 +1566,13 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- A nonnegative integer; the number of variables + - ``n`` -- nonnegative integer; the number of variables in the expansion - - ``alphabet`` -- (default: ``'x'``); the alphabet in + - ``alphabet`` -- (default: ``'x'``) the alphabet in which ``self`` is to be expanded - OUTPUT: - - - An expansion of ``self`` into the ``n`` variables specified - by ``alphabet``. + OUTPUT: an expansion of ``self`` into the ``n`` variables + specified by ``alphabet`` EXAMPLES:: @@ -1723,9 +1711,7 @@ def dual(self): Return the dual basis to the Monomial basis. This is the complete basis of the non-commutative symmetric functions. - OUTPUT: - - - The complete basis of the non-commutative symmetric functions. + OUTPUT: the complete basis of the non-commutative symmetric functions EXAMPLES:: @@ -2011,13 +1997,11 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- an integer - - ``alphabet`` -- (default: ``'x'``) a string + - ``n`` -- integer + - ``alphabet`` -- string (default: ``'x'``) - OUTPUT: - - - The quasi-symmetric function ``self`` expressed in the ``n`` variables - described by ``alphabet``. + OUTPUT: the quasi-symmetric function ``self`` expressed in the + `n` variables described by ``alphabet`` .. TODO:: accept an *alphabet* as input @@ -2207,7 +2191,7 @@ def __init__(self, QSym): def _from_schur_on_basis(self, la): r""" - Maps the Schur symmetric function indexed by ``la`` to the + Map the Schur symmetric function indexed by ``la`` to the Fundamental basis. EXAMPLES:: @@ -2237,9 +2221,7 @@ def dual(self): Return the dual basis to the Fundamental basis. This is the ribbon basis of the non-commutative symmetric functions. - OUTPUT: - - - The ribbon basis of the non-commutative symmetric functions. + OUTPUT: the ribbon basis of the non-commutative symmetric functions EXAMPLES:: @@ -2454,7 +2436,7 @@ def internal_coproduct(self): #. If `I` is a composition, then a `(0, I)`-matrix will mean a matrix whose entries are nonnegative integers such that no row and no column of this matrix is zero, and such that if - all the non-zero entries of the matrix are read (row by row, + all the nonzero entries of the matrix are read (row by row, starting at the topmost row, reading every row from left to right), then the reading word obtained is `I`. If `A` is a `(0, I)`-matrix, then `\mathrm{row}(A)` will denote the @@ -2886,11 +2868,9 @@ def _from_monomial_transition_matrix(self, n): INPUT: - - ``n`` -- an integer - - OUTPUT: + - ``n`` -- integer - - a pair of a square matrix and the ordered list of compositions + OUTPUT: a pair of a square matrix and the ordered list of compositions EXAMPLES:: @@ -2917,16 +2897,14 @@ def _from_monomial_transition_matrix(self, n): @cached_method def _from_monomial_on_basis(self, comp): r""" - Maps the Monomial quasi-symmetric function indexed by + Map the Monomial quasi-symmetric function indexed by ``comp`` to the Quasisymmetric Schur basis. INPUT: - ``comp`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the Quasisymmetric Schur basis + OUTPUT: a quasi-symmetric function in the Quasisymmetric Schur basis EXAMPLES:: @@ -2960,9 +2938,7 @@ def _to_monomial_on_basis(self, comp_shape): - ``comp_shape`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the Monomial basis + OUTPUT: a quasi-symmetric function in the Monomial basis EXAMPLES:: @@ -3082,9 +3058,7 @@ def _to_monomial_on_basis(self, comp): - ``comp`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the Monomial basis + OUTPUT: a quasi-symmetric function in the Monomial basis EXAMPLES:: @@ -3108,9 +3082,7 @@ def _from_monomial_on_basis(self, comp): - ``comp`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the Young Quasisymmetric Schur basis + OUTPUT: a quasi-symmetric function in the Young Quasisymmetric Schur basis EXAMPLES:: @@ -3163,9 +3135,7 @@ def _to_Monomial_on_basis(self, J): - ``J`` -- a composition - OUTPUT: - - - A quasi-symmetric function in the monomial basis. + OUTPUT: a quasi-symmetric function in the monomial basis EXAMPLES:: @@ -3231,9 +3201,7 @@ def _from_Monomial_on_basis(self, J): - ``J`` -- a composition - OUTPUT: - - - A quasi-symmetric function in the dual immaculate basis. + OUTPUT: a quasi-symmetric function in the dual immaculate basis EXAMPLES:: @@ -3718,9 +3686,7 @@ def _to_Monomial_on_basis(self, J): - ``J`` -- a composition - OUTPUT: - - - A quasi-symmetric function in the Monomial basis. + OUTPUT: a quasi-symmetric function in the Monomial basis EXAMPLES:: @@ -3742,9 +3708,7 @@ def _from_Monomial_on_basis(self, J): - ``J`` -- a composition - OUTPUT: - - - A quasi-symmetric function in the Hazewinkel lambda basis. + OUTPUT: a quasi-symmetric function in the Hazewinkel lambda basis EXAMPLES:: @@ -3907,9 +3871,7 @@ def _from_Monomial_on_basis(self, I): - ``I`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the `\psi` basis + OUTPUT: a quasi-symmetric function in the `\psi` basis TESTS:: @@ -3935,9 +3897,7 @@ def _to_Monomial_on_basis(self, I): - ``I`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the Monomial basis + OUTPUT: a quasi-symmetric function in the Monomial basis TESTS:: @@ -4050,9 +4010,7 @@ def _from_Monomial_on_basis(self, I): - ``I`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the `\psi` basis + OUTPUT: a quasi-symmetric function in the `\psi` basis TESTS:: @@ -4078,9 +4036,7 @@ def _to_Monomial_on_basis(self, I): - ``I`` -- a composition - OUTPUT: - - - a quasi-symmetric function in the Monomial basis + OUTPUT: a quasi-symmetric function in the Monomial basis TESTS:: diff --git a/src/sage/combinat/ncsym/bases.py b/src/sage/combinat/ncsym/bases.py index 466d1ad42e5..b04afcdbd47 100644 --- a/src/sage/combinat/ncsym/bases.py +++ b/src/sage/combinat/ncsym/bases.py @@ -37,7 +37,7 @@ def _element_constructor_(self, x): INPUT: - - ``x`` -- a set partition or list of lists of integers + - ``x`` -- set partition or list of lists of integers EXAMPLES:: @@ -63,9 +63,7 @@ def super_categories(self): Return the super categories of bases of (the Hopf dual of) the symmetric functions in non-commuting variables. - OUTPUT: - - - a list of categories + OUTPUT: list of categories TESTS:: @@ -124,11 +122,11 @@ def _repr_(self): def __getitem__(self, i): """ - Return the basis element indexed by ``i``. + Return the basis element indexed by `i`. INPUT: - - ``i`` -- a set partition or a list of list of integers + - ``i`` -- set partition or a list of list of integers EXAMPLES:: @@ -153,9 +151,7 @@ def one_basis(self): r""" Return the index of the basis element containing `1`. - OUTPUT: - - - The empty set partition + OUTPUT: the empty set partition EXAMPLES:: @@ -175,11 +171,9 @@ def counit_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - either the ``0`` or the ``1`` of the base ring of ``self`` + OUTPUT: either the `0` or the `1` of the base ring of ``self`` EXAMPLES:: @@ -213,9 +207,7 @@ def duality_pairing(self, x, y): - ``y`` -- an element of the dual of symmetric functions in non-commuting variables - OUTPUT: - - - an element of the base ring of ``self`` + OUTPUT: an element of the base ring of ``self`` EXAMPLES:: @@ -244,12 +236,12 @@ def duality_pairing_matrix(self, basis, degree): INPUT: - ``basis`` -- a basis of the dual Hopf algebra - - ``degree`` -- a non-negative integer + - ``degree`` -- nonnegative integer OUTPUT: - - the matrix of scalar products between the basis ``self`` and the - basis ``basis`` in the dual Hopf algebra of degree ``degree`` + The matrix of scalar products between the basis ``self`` and the + basis ``basis`` in the dual Hopf algebra of degree ``degree``. EXAMPLES: @@ -351,9 +343,7 @@ def super_categories(self): Return the super categories of bases of the Hopf dual of the symmetric functions in non-commuting variables. - OUTPUT: - - - a list of categories + OUTPUT: list of categories TESTS:: @@ -395,9 +385,7 @@ def from_symmetric_function(self, f): - ``f`` -- a symmetric function - OUTPUT: - - - an element of ``self`` + OUTPUT: an element of ``self`` EXAMPLES:: @@ -444,12 +432,10 @@ def primitive(self, A, i=1): INPUT: - - ``A`` -- a set partition - - ``i`` -- a positive integer + - ``A`` -- set partition + - ``i`` -- positive integer - OUTPUT: - - - an element of ``self`` + OUTPUT: an element of ``self`` EXAMPLES:: @@ -471,9 +457,7 @@ def internal_coproduct_on_basis(self, i): - ``i`` -- the indices of an element of the basis of ``self`` - OUTPUT: - - - an element of the tensor squared of ``self`` + OUTPUT: an element of the tensor squared of ``self`` EXAMPLES:: @@ -492,9 +476,7 @@ def internal_coproduct(self): `\otimes` ``self`` by extending it by linearity. Otherwise, this uses :meth:`internal_coproduct_by_coercion()`, if available. - OUTPUT: - - - an element of the tensor squared of ``self`` + OUTPUT: an element of the tensor squared of ``self`` EXAMPLES:: @@ -517,9 +499,7 @@ def internal_coproduct_by_coercion(self, x): - ``x`` -- an element of ``self`` - OUTPUT: - - - an element of the tensor squared of ``self`` + OUTPUT: an element of the tensor squared of ``self`` EXAMPLES:: @@ -587,9 +567,7 @@ def to_symmetric_function(self): multiplicity of `i` in `\mu`. For other bases this map is extended linearly. - OUTPUT: - - - an element of the symmetric functions in the monomial basis + OUTPUT: an element of the symmetric functions in the monomial basis EXAMPLES:: @@ -681,9 +659,7 @@ def internal_coproduct(self): and the map is extended linearly. - OUTPUT: - - - an element of the tensor square of the basis of ``self`` + OUTPUT: an element of the tensor square of the basis of ``self`` EXAMPLES:: @@ -706,9 +682,7 @@ def omega(self): and the result is extended linearly. - OUTPUT: - - - an element in the same basis as ``self`` + OUTPUT: an element in the same basis as ``self`` EXAMPLES:: @@ -753,9 +727,7 @@ def super_categories(self): Return the super categories of bases of the Hopf dual of the symmetric functions in non-commuting variables. - OUTPUT: - - - a list of categories + OUTPUT: list of categories TESTS:: @@ -795,9 +767,7 @@ def product_on_basis(self, A, B): - ``A``, ``B`` -- set partitions - OUTPUT: - - - an element in the basis ``self`` + OUTPUT: an element in the basis ``self`` EXAMPLES:: @@ -858,9 +828,7 @@ def super_categories(self): Return the super categories of bases of the Hopf dual of the symmetric functions in non-commuting variables. - OUTPUT: - - - a list of categories + OUTPUT: list of categories TESTS:: diff --git a/src/sage/combinat/ncsym/dual.py b/src/sage/combinat/ncsym/dual.py index b9a230de61d..520bf5b2d0e 100644 --- a/src/sage/combinat/ncsym/dual.py +++ b/src/sage/combinat/ncsym/dual.py @@ -164,9 +164,8 @@ def dual_basis(self): The dual basis to the `\mathbf{w}` basis is the monomial basis of the symmetric functions in non-commuting variables. - OUTPUT: - - - the monomial basis of the symmetric functions in non-commuting variables + OUTPUT: the monomial basis of the symmetric functions in + non-commuting variables EXAMPLES:: @@ -198,9 +197,7 @@ def product_on_basis(self, A, B): - ``A``, ``B`` -- set partitions - OUTPUT: - - - an element of the `\mathbf{w}` basis + OUTPUT: an element of the `\mathbf{w}` basis EXAMPLES:: @@ -257,7 +254,7 @@ def coproduct_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition OUTPUT: @@ -286,11 +283,9 @@ def antipode_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - an element in the basis ``self`` + OUTPUT: an element in the basis ``self`` EXAMPLES:: @@ -321,9 +316,7 @@ def duality_pairing(self, x, y): - ``y`` -- an element of the symmetric functions in non-commuting variables - OUTPUT: - - - an element of the base ring of ``self`` + OUTPUT: an element of the base ring of ``self`` EXAMPLES:: @@ -360,11 +353,9 @@ def sum_of_partitions(self, la): INPUT: - - ``la`` -- an integer partition - - OUTPUT: + - ``la`` -- integer partition - - an element of ``self`` + OUTPUT: an element of ``self`` EXAMPLES:: @@ -393,7 +384,7 @@ def _set_par_to_par(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition EXAMPLES:: @@ -443,8 +434,8 @@ def expand(self, n, letter='x'): INPUT: - - ``n`` -- an integer - - ``letter`` -- (default: ``'x'``) a string + - ``n`` -- integer + - ``letter`` -- string (default: ``'x'``) OUTPUT: diff --git a/src/sage/combinat/ncsym/ncsym.py b/src/sage/combinat/ncsym/ncsym.py index 8ebc0b899bd..1bcbb7cf1e3 100644 --- a/src/sage/combinat/ncsym/ncsym.py +++ b/src/sage/combinat/ncsym/ncsym.py @@ -322,9 +322,7 @@ def a_realization(self): r""" Return the realization of the powersum basis of ``self``. - OUTPUT: - - - The powersum basis of symmetric functions in non-commuting variables. + OUTPUT: the powersum basis of symmetric functions in non-commuting variables EXAMPLES:: @@ -386,11 +384,9 @@ def _m_to_p_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the powersum basis + OUTPUT: an element of the powersum basis TESTS:: @@ -420,11 +416,9 @@ def _m_to_cp_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the `\mathbf{cp}` basis + OUTPUT: an element of the `\mathbf{cp}` basis TESTS:: @@ -457,9 +451,7 @@ def from_symmetric_function(self, f): - ``f`` -- an element of the symmetric functions - OUTPUT: - - - An element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis EXAMPLES:: @@ -500,9 +492,7 @@ def dual_basis(self): r""" Return the dual basis to the monomial basis. - OUTPUT: - - - the `\mathbf{w}` basis of the dual Hopf algebra + OUTPUT: the `\mathbf{w}` basis of the dual Hopf algebra EXAMPLES:: @@ -524,9 +514,7 @@ def duality_pairing(self, x, y): - ``y`` -- an element of the dual of symmetric functions in non-commuting variables - OUTPUT: - - - an element of the base ring of ``self`` + OUTPUT: an element of the base ring of ``self`` EXAMPLES:: @@ -564,9 +552,7 @@ def product_on_basis(self, A, B): - ``A``, ``B`` -- set partitions - OUTPUT: - - - an element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis EXAMPLES:: @@ -621,7 +607,7 @@ def coproduct_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition OUTPUT: @@ -695,11 +681,9 @@ def internal_coproduct_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - an element of the tensor square of the `\mathbf{m}` basis + OUTPUT: an element of the tensor square of the `\mathbf{m}` basis EXAMPLES:: @@ -746,11 +730,9 @@ def sum_of_partitions(self, la): INPUT: - - ``la`` -- an integer partition - - OUTPUT: + - ``la`` -- integer partition - - an element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis EXAMPLES:: @@ -789,8 +771,8 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- an integer - - ``alphabet`` -- (default: ``'x'``) a string + - ``n`` -- integer + - ``alphabet`` -- string (default: ``'x'``) OUTPUT: @@ -845,9 +827,7 @@ def to_symmetric_function(self): taking the sizes of the parts and `n_i(\mu)` is the multiplicity of `i` in `\mu`. - OUTPUT: - - - an element of the symmetric functions in the monomial basis + OUTPUT: an element of the symmetric functions in the monomial basis EXAMPLES:: @@ -894,15 +874,15 @@ def __init__(self, NCSym): # get the coercion path m -> p -> e p = NCSym.p() self.module_morphism(self._e_to_p_on_basis, codomain=p, - triangular="upper").register_as_coercion() + triangular='upper').register_as_coercion() p.module_morphism(p._p_to_e_on_basis, codomain=self, - triangular="upper").register_as_coercion() + triangular='upper').register_as_coercion() # homogeneous h = NCSym.h() self.module_morphism(self._e_to_h_on_basis, codomain=h, - triangular="upper").register_as_coercion() + triangular='upper').register_as_coercion() h.module_morphism(h._h_to_e_on_basis, codomain=self, - triangular="upper").register_as_coercion() + triangular='upper').register_as_coercion() @cached_method def _e_to_m_on_basis(self, A): @@ -911,11 +891,9 @@ def _e_to_m_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - An element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis TESTS:: @@ -940,11 +918,9 @@ def _e_to_h_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - An element of the `\mathbf{h}` basis + OUTPUT: an element of the `\mathbf{h}` basis TESTS:: @@ -968,11 +944,9 @@ def _e_to_p_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the `\mathbf{p}` basis + OUTPUT: an element of the `\mathbf{p}` basis TESTS:: @@ -1000,9 +974,7 @@ def omega(self): The involution `\omega` on `NCSym` is defined by `\omega(\mathbf{e}_A) = \mathbf{h}_A`. - OUTPUT: - - - an element in the basis ``self`` + OUTPUT: an element in the basis ``self`` EXAMPLES:: @@ -1038,9 +1010,7 @@ def to_symmetric_function(self): where `\lambda(A)` is the partition associated with `A` by taking the sizes of the parts. - OUTPUT: - - - An element of the symmetric functions in the elementary basis + OUTPUT: an element of the symmetric functions in the elementary basis EXAMPLES:: @@ -1096,11 +1066,9 @@ def _h_to_m_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis TESTS:: @@ -1124,11 +1092,9 @@ def _h_to_e_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the `\mathbf{e}` basis + OUTPUT: an element of the `\mathbf{e}` basis TESTS:: @@ -1153,11 +1119,9 @@ def _h_to_p_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - An element of the `\mathbf{p}` basis + OUTPUT: an element of the `\mathbf{p}` basis TESTS:: @@ -1185,9 +1149,7 @@ def omega(self): The involution `\omega` on `NCSym` is defined by `\omega(\mathbf{h}_A) = \mathbf{e}_A`. - OUTPUT: - - - an element in the basis ``self`` + OUTPUT: an element in the basis ``self`` EXAMPLES:: @@ -1223,9 +1185,7 @@ def to_symmetric_function(self): where `\lambda(A)` is the partition associated with `A` by taking the sizes of the parts. - OUTPUT: - - - An element of the symmetric functions in the complete basis + OUTPUT: an element of the symmetric functions in the complete basis EXAMPLES:: @@ -1283,14 +1243,14 @@ def __init__(self, NCSym): # Register coercions m = NCSym.m() self.module_morphism(self._p_to_m_on_basis, codomain=m, - unitriangular="lower").register_as_coercion() + unitriangular='lower').register_as_coercion() m.module_morphism(m._m_to_p_on_basis, codomain=self, - unitriangular="lower").register_as_coercion() + unitriangular='lower').register_as_coercion() x = NCSym.x() self.module_morphism(self._p_to_x_on_basis, codomain=x, - unitriangular="upper").register_as_coercion() + unitriangular='upper').register_as_coercion() x.module_morphism(x._x_to_p_on_basis, codomain=self, - unitriangular="upper").register_as_coercion() + unitriangular='upper').register_as_coercion() @cached_method def _p_to_m_on_basis(self, A): @@ -1299,11 +1259,9 @@ def _p_to_m_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - An element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis TESTS:: @@ -1324,11 +1282,9 @@ def _p_to_e_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the `\mathbf{e}` basis + OUTPUT: an element of the `\mathbf{e}` basis TESTS:: @@ -1352,11 +1308,9 @@ def _p_to_h_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - An element of the `\mathbf{h}` basis + OUTPUT: an element of the `\mathbf{h}` basis TESTS:: @@ -1380,11 +1334,9 @@ def _p_to_x_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - An element of the `\mathbf{x}` basis + OUTPUT: an element of the `\mathbf{x}` basis TESTS:: @@ -1405,7 +1357,7 @@ def coproduct_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition OUTPUT: @@ -1469,11 +1421,9 @@ def internal_coproduct_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - an element of the tensor square of ``self`` + OUTPUT: an element of the tensor square of ``self`` EXAMPLES:: @@ -1507,11 +1457,9 @@ def antipode_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - an element in the basis ``self`` + OUTPUT: an element in the basis ``self`` EXAMPLES:: @@ -1571,13 +1519,11 @@ def primitive(self, A, i=1): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - ``i`` -- (default: 1) index in the base set for ``A`` specifying which set of primitives this belongs to - OUTPUT: - - - an element in the basis ``self`` + OUTPUT: an element in the basis ``self`` EXAMPLES:: @@ -1621,9 +1567,7 @@ def to_symmetric_function(self): where `\lambda(A)` is the partition associated with `A` by taking the sizes of the parts. - OUTPUT: - - - an element of symmetric functions in the power sum basis + OUTPUT: an element of symmetric functions in the power sum basis EXAMPLES:: @@ -1696,9 +1640,9 @@ def __init__(self, NCSym): # Register coercions m = NCSym.m() self.module_morphism(self._cp_to_m_on_basis, codomain=m, - unitriangular="lower").register_as_coercion() + unitriangular='lower').register_as_coercion() m.module_morphism(m._m_to_cp_on_basis, codomain=self, - unitriangular="lower").register_as_coercion() + unitriangular='lower').register_as_coercion() @cached_method def _cp_to_m_on_basis(self, A): @@ -1707,11 +1651,9 @@ def _cp_to_m_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - an element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis TESTS:: @@ -1776,11 +1718,9 @@ def _x_to_p_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - an element of the `\mathbf{p}` basis + OUTPUT: an element of the `\mathbf{p}` basis TESTS:: @@ -1904,11 +1844,9 @@ def _rho_to_m_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - an element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis TESTS:: @@ -1933,11 +1871,9 @@ def _m_to_rho_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - an element of the `\rho` basis + OUTPUT: an element of the `\rho` basis TESTS:: @@ -2050,11 +1986,9 @@ def _chi_to_m_on_basis(self, A): INPUT: - - ``A`` -- a set partition + - ``A`` -- set partition - OUTPUT: - - - an element of the `\mathbf{m}` basis + OUTPUT: an element of the `\mathbf{m}` basis TESTS:: @@ -2117,11 +2051,9 @@ def _m_to_chi_on_basis(self, A): INPUT: - - ``A`` -- a set partition - - OUTPUT: + - ``A`` -- set partition - - an element of the `\chi` basis + OUTPUT: an element of the `\chi` basis TESTS:: diff --git a/src/sage/combinat/necklace.py b/src/sage/combinat/necklace.py index 9cfbe719cdc..3ac4bccf5e2 100644 --- a/src/sage/combinat/necklace.py +++ b/src/sage/combinat/necklace.py @@ -47,7 +47,7 @@ def Necklaces(content): INPUT: - - ``content`` -- a list or tuple of non-negative integers + - ``content`` -- list or tuple of nonnegative integers EXAMPLES:: @@ -75,7 +75,7 @@ class Necklaces_evaluation(UniqueRepresentation, Parent): INPUT: - - ``content`` -- a list or tuple of non-negative integers + - ``content`` -- list or tuple of nonnegative integers """ @staticmethod def __classcall_private__(cls, content): @@ -134,7 +134,7 @@ def __contains__(self, x) -> bool: INPUT: - - ``x`` -- a list of integers + - ``x`` -- list of integers EXAMPLES:: @@ -456,12 +456,12 @@ def _sfc(content, equality=False): INPUT: - - ``content`` -- a list of non-negative integers with no leading 0s + - ``content`` -- list of nonnegative integers with no leading 0s - ``equality`` -- boolean (default: ``True``) .. WARNING:: - You will get incorrect results if there are leading 0's in ``content``. + You will get incorrect results if there are leading 0s in ``content``. See :issue:`12997` and :issue:`17436`. EXAMPLES:: diff --git a/src/sage/combinat/non_decreasing_parking_function.py b/src/sage/combinat/non_decreasing_parking_function.py index 532b4bf8762..dc6bf59e3e2 100644 --- a/src/sage/combinat/non_decreasing_parking_function.py +++ b/src/sage/combinat/non_decreasing_parking_function.py @@ -189,11 +189,11 @@ def __init__(self, lst): def __getitem__(self, n): """ - Return the `n^{th}` item in the underlying list. + Return the `n`-th item in the underlying list. - .. note:: + .. NOTE:: - Note that this is different than the image of ``n`` under + Note that this is different than the image of `n` under function. It is "off by one". EXAMPLES:: @@ -410,7 +410,7 @@ def __contains__(self, x) -> bool: def __iter__(self): """ - An iterator + An iterator. TESTS:: @@ -478,7 +478,7 @@ def __init__(self, n): """ n = Integer(n) if n < 0: - raise ValueError('%s is not a non-negative integer' % n) + raise ValueError('%s is not a nonnegative integer' % n) self.n = n Parent.__init__(self, category=Monoids().Enumerated().Finite()) diff --git a/src/sage/combinat/nu_dyck_word.py b/src/sage/combinat/nu_dyck_word.py index c52e07b8469..26f54ea8900 100644 --- a/src/sage/combinat/nu_dyck_word.py +++ b/src/sage/combinat/nu_dyck_word.py @@ -93,7 +93,7 @@ def replace_dyck_char(x): - If ``x`` is a closing character, replace ``x`` with the constant ``ndw_close_symbol``. - - Raise a :class:`ValueError` if ``x`` is neither an opening nor a + - Raise a :exc:`ValueError` if ``x`` is neither an opening nor a closing character. .. SEEALSO:: :func:`replace_dyck_symbol` @@ -128,20 +128,18 @@ def replace_dyck_symbol(x, open_char='N', close_char='E') -> str: INPUT: - - ``x`` -- either ``ndw_open_symbol`` or ``ndw_close_symbol``. + - ``x`` -- either ``ndw_open_symbol`` or ``ndw_close_symbol`` - - ``open_char`` -- str (optional) default ``'N'`` + - ``open_char`` -- string (optional) default ``'N'`` - - ``close_char`` -- str (optional) default ``'E'`` + - ``close_char`` -- string (optional) default ``'E'`` - OUTPUT: - - - If ``x`` is ``ndw_open_symbol``, replace ``x`` with ``open_char``. + OUTPUT: if ``x`` is ``ndw_open_symbol``, replace ``x`` with ``open_char`` - If ``x`` is ``ndw_close_symbol``, replace ``x`` with ``close_char``. - If ``x`` is neither ``ndw_open_symbol`` nor ``ndw_close_symbol``, a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. .. SEEALSO:: :func:`replace_dyck_char` @@ -178,9 +176,9 @@ class NuDyckWord(CombinatorialElement): INPUT: - - k1 -- A path for the `\nu`-Dyck word + - ``k1`` -- a path for the `\nu`-Dyck word - - k2 -- A path for `\nu` + - ``k2`` -- a path for `\nu` EXAMPLES:: @@ -324,7 +322,6 @@ def __le__(self, other): True sage: ND3 <= ND1 True - """ if self._nu == other._nu: return path_weakly_above_other(other._path, self._path) @@ -332,7 +329,7 @@ def __le__(self, other): def __lt__(self, other): """ - Return if one path is strictly included in another + Return if one path is strictly included in another. EXAMPLES:: @@ -354,7 +351,7 @@ def __lt__(self, other): def __ge__(self, other): """ - Return if one path is included in another + Return if one path is included in another. EXAMPLES:: @@ -378,7 +375,7 @@ def __ge__(self, other): def __gt__(self, other): """ - Return if one path is strictly included in another + Return if one path is strictly included in another. EXAMPLES:: @@ -428,32 +425,32 @@ def set_latex_options(self, D): The default values are set in the ``__init__`` function. - - ``color`` -- (default: black) the line color. + - ``color`` -- (default: black) the line color - ``line width`` -- (default: `2 \times` ``tikz_scale``) value - representing the line width. + representing the line width - ``nu_options`` -- (default: ``'rounded corners=1, color=red, line - width=1'``) str to indicate what the tikz options should be for path - of `\nu`. + width=1'``) string to indicate what the tikz options should be for + path of `\nu` - ``points_color`` -- (default: ``'black'``) str to indicate color - points should be drawn with. + points should be drawn with - - ``show_grid`` -- (default: ``True``) boolean value to indicate if - grid should be shown. + - ``show_grid`` -- boolean (default: ``True``); value to indicate if + grid should be shown - - ``show_nu`` -- (default: ``True``) boolean value to indicate if `\nu` - should be shown. + - ``show_nu`` -- boolean (default: ``True``); value to indicate if `\nu` + should be shown - - ``show_points`` -- (default: ``False``) boolean value to indicate - if points should be shown on path. + - ``show_points`` -- boolean (default: ``False``); value to indicate + if points should be shown on path - - ``tikz_scale`` -- (default: 1) scale for use with the tikz package. + - ``tikz_scale`` -- (default: 1) scale for use with the tikz package INPUT: - - ``D`` -- a dictionary with a list of latex parameters to change + - ``D`` -- dictionary with a list of latex parameters to change EXAMPLES:: @@ -475,28 +472,28 @@ def latex_options(self) -> dict: The default values are set using the options. - - ``color`` -- (default: black) the line color. + - ``color`` -- (default: black) the line color - ``line width`` -- (default: 2*``tikz_scale``) value representing the - line width. + line width - ``nu_options`` -- (default: ``'rounded corners=1, color=red, line - width=1'``) str to indicate what the tikz options should be for path - of `\nu`. + width=1'``) string to indicate what the tikz options should be for + path of `\nu` - ``points_color`` -- (default: ``'black'``) str to indicate color - points should be drawn with. + points should be drawn with - - ``show_grid`` -- (default: ``True``) boolean value to indicate if - grid should be shown. + - ``show_grid`` -- boolean (default: ``True``); value to indicate if + grid should be shown - - ``show_nu`` -- (default: ``True``) boolean value to indicate if `\nu` - should be shown. + - ``show_nu`` -- boolean (default: ``True``); value to indicate if `\nu` + should be shown - - ``show_points`` -- (default: ``False``) boolean value to indicate - if points should be shown on path. + - ``show_points`` -- boolean (default: ``False``); value to indicate + if points should be shown on path - - ``tikz_scale`` -- (default: 1) scale for use with the tikz package. + - ``tikz_scale`` -- (default: 1) scale for use with the tikz package EXAMPLES:: @@ -668,7 +665,6 @@ def _ascii_art_(self): ___| . . . . . | . . . . . . . ______| . . . . . . . - """ from sage.typeset.ascii_art import AsciiArt rep = self.parent().options.ascii_art @@ -708,10 +704,10 @@ def pretty_print(self, style=None, labelling=None): - "N-E" to show ``self`` as a path of north and east steps, or - ``labelling`` -- (if style is "N-E") a list of labels assigned to - the up steps in ``self``. + the up steps in ``self`` - - ``underpath`` -- (if style is "N-E", default: ``True``) If ``True``, - an ``x`` to show the boxes between `\nu` and the `\nu`-Dyck Path. + - ``underpath`` -- (if style is "N-E", default: ``True``) if ``True``, + an ``x`` to show the boxes between `\nu` and the `\nu`-Dyck Path EXAMPLES:: @@ -1050,9 +1046,7 @@ def can_mutate(self, i) -> bool | int: Can only mutate if an east step is followed by a north step at height `i`. - OUTPUT: - - Whether we can mutate at height of `i`. + OUTPUT: whether we can mutate at height of `i` EXAMPLES:: @@ -1142,7 +1136,7 @@ class NuDyckWords(Parent): INPUT: - - ``nu`` -- the base lattice path. + - ``nu`` -- the base lattice path EXAMPLES:: @@ -1404,9 +1398,7 @@ def to_word_path(word): - ``word`` -- word to convert to wordpath - OUTPUT: - - - A ``FiniteWordPath_north_east`` object. + OUTPUT: a ``FiniteWordPath_north_east`` object EXAMPLES:: @@ -1449,13 +1441,11 @@ def path_weakly_above_other(path, other) -> bool: INPUT: - - ``path`` -- The path to verify is weakly above the other path. + - ``path`` -- the path to verify is weakly above the other path - - ``other`` -- The other path to verify is weakly below the path. - - OUTPUT: + - ``other`` -- the other path to verify is weakly below the path - bool + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/combinat/nu_tamari_lattice.py b/src/sage/combinat/nu_tamari_lattice.py index 036de27126d..7a7a9ef3d78 100644 --- a/src/sage/combinat/nu_tamari_lattice.py +++ b/src/sage/combinat/nu_tamari_lattice.py @@ -76,11 +76,9 @@ def NuTamariLattice(nu): INPUT: - - `\nu` -- a list of 0s and 1s or a string of 0s and 1s. + - `\nu` -- list of 0s and 1s or a string of 0s and 1s - OUTPUT: - - a finite lattice + OUTPUT: a finite lattice The elements of the lattice are :func:`\nu-Dyck paths` weakly above @@ -133,13 +131,11 @@ def delta_swap(p, k, delta): - ``p`` -- a `\nu`-Dyck word - - ``k`` -- an integer between `0` and ``p.length()-1`` - - - ``delta`` -- a list of nonnegative integers of length ``p.height()`` + - ``k`` -- integer between `0` and ``p.length()-1`` - OUTPUT: + - ``delta`` -- list of nonnegative integers of length ``p.height()`` - - a `\nu`-Dyck word + OUTPUT: a `\nu`-Dyck word EXAMPLES:: @@ -209,13 +205,11 @@ def AltNuTamariLattice(nu, delta=None): INPUT: - - `\nu` -- a list of 0s and 1s or a string of 0s and 1s. - - - `\delta` -- a list of nonnegative integers. + - `\nu` -- list of 0s and 1s or a string of 0s and 1s - OUTPUT: + - `\delta` -- list of nonnegative integers - - a finite lattice + OUTPUT: a finite lattice EXAMPLES:: diff --git a/src/sage/combinat/ordered_tree.py b/src/sage/combinat/ordered_tree.py index 17e391450c2..492a0b72956 100644 --- a/src/sage/combinat/ordered_tree.py +++ b/src/sage/combinat/ordered_tree.py @@ -277,7 +277,7 @@ def is_empty(self): """ return False - def _to_binary_tree_rec(self, bijection="left"): + def _to_binary_tree_rec(self, bijection='left'): r""" Internal recursive method to obtain a binary tree from an ordered tree. @@ -290,12 +290,12 @@ def _to_binary_tree_rec(self, bijection="left"): sage: T = OrderedTree([[],[]]) sage: T._to_binary_tree_rec() [[., .], .] - sage: T._to_binary_tree_rec(bijection="right") + sage: T._to_binary_tree_rec(bijection='right') [., [., .]] sage: T = OrderedTree([[], [[], []], [[], [[]]]]) sage: T._to_binary_tree_rec() [[[., .], [[., .], .]], [[., .], [., .]]] - sage: T._to_binary_tree_rec(bijection="right") + sage: T._to_binary_tree_rec(bijection='right') [., [[., [., .]], [[., [[., .], .]], .]]] """ from sage.combinat.binary_tree import BinaryTree @@ -493,7 +493,7 @@ def to_binary_tree_right_branch(self): sage: T == T.to_binary_tree_right_branch().to_ordered_tree_right_branch() True """ - return self._to_binary_tree_rec(bijection="right") + return self._to_binary_tree_rec(bijection='right') @combinatorial_map(name="To Dyck path") def to_dyck_word(self): @@ -591,8 +591,8 @@ def to_poset(self, root_to_leaf=False): INPUT: - - ``root_to_leaf`` -- boolean, true if the poset orientation should - be from root to leaves. It is false by default. + - ``root_to_leaf`` -- boolean (default: ``False``); ``True`` if the + poset orientation should be from root to leaves EXAMPLES:: @@ -709,8 +709,7 @@ def plot(self): except AttributeError: root = 1 g = self.canonical_labelling().to_undirected_graph() - return g.plot(layout='tree', tree_root=root, - tree_orientation="down") + return g.plot(layout='tree', tree_root=root, tree_orientation='down') def sort_key(self): """ @@ -775,7 +774,7 @@ def normalize(self, inplace=False): INPUT: - - ``inplace`` -- boolean, (default ``False``) if ``True``, + - ``inplace`` -- boolean (default: ``False``); if ``True``, then ``self`` is modified and nothing returned. Otherwise the normalized tree is returned. @@ -835,11 +834,11 @@ def normalize(self, inplace=False): # Abstract class to serve as a Factory no instance are created. class OrderedTrees(UniqueRepresentation, Parent): """ - Factory for ordered trees + Factory for ordered trees. INPUT: - - ``size`` -- (optional) an integer + - ``size`` -- integer (optional) OUTPUT: @@ -881,13 +880,13 @@ def __classcall_private__(cls, n=None): return OrderedTrees_all() else: if not (isinstance(n, (Integer, int)) and n >= 0): - raise ValueError("n must be a non negative integer") + raise ValueError("n must be a nonnegative integer") return OrderedTrees_size(Integer(n)) @cached_method def leaf(self): """ - Return a leaf tree with ``self`` as parent + Return a leaf tree with ``self`` as parent. EXAMPLES:: @@ -963,7 +962,7 @@ def __contains__(self, x): def unlabelled_trees(self): """ - Return the set of unlabelled trees associated to ``self`` + Return the set of unlabelled trees associated to ``self``. EXAMPLES:: @@ -974,7 +973,7 @@ def unlabelled_trees(self): def labelled_trees(self): """ - Return the set of labelled trees associated to ``self`` + Return the set of labelled trees associated to ``self``. EXAMPLES:: @@ -1006,7 +1005,7 @@ def _element_constructor_(self, *args, **keywords): class OrderedTrees_size(OrderedTrees): """ - The enumerated sets of binary trees of a given size + The enumerated sets of binary trees of a given size. EXAMPLES:: @@ -1063,7 +1062,7 @@ def _an_element_(self): def cardinality(self): """ - The cardinality of ``self`` + The cardinality of ``self``. This is a Catalan number. @@ -1112,7 +1111,7 @@ def random_element(self): def __iter__(self): """ - A basic generator + A basic generator. .. TODO:: could be optimized. @@ -1138,7 +1137,7 @@ def __iter__(self): @lazy_attribute def _parent_for(self): """ - Return the parent of the element generated by ``self`` + Return the parent of the element generated by ``self``. TESTS:: @@ -1150,7 +1149,7 @@ def _parent_for(self): @lazy_attribute def element_class(self): """ - The class of the element of ``self`` + The class of the element of ``self``. EXAMPLES:: @@ -1192,7 +1191,7 @@ class LabelledOrderedTree(AbstractLabelledClonableTree, OrderedTree): INPUT: - - ``children`` -- a list or tuple or more generally any iterable + - ``children`` -- list or tuple or more generally any iterable of trees or object convertible to trees - ``label`` -- any Sage object (default: ``None``) @@ -1398,7 +1397,7 @@ def _an_element_(self): t = LT([], label=3) t1 = LT([t, t], label=42) t2 = LT([[]], label=5) - return LT([t, t1, t2], label="toto") + return LT([t, t1, t2], label='toto') def _element_constructor_(self, *args, **keywords): """ diff --git a/src/sage/combinat/output.py b/src/sage/combinat/output.py index 7f223921d7e..1e2725448f9 100644 --- a/src/sage/combinat/output.py +++ b/src/sage/combinat/output.py @@ -24,13 +24,14 @@ def tex_from_array(array, with_lines=True): r""" - Return a latex string for a two dimensional array of partition, composition or skew composition shape + Return a latex string for a two dimensional array of partition, composition + or skew composition shape. INPUT: - - ``array`` -- a list of list - - ``with_lines`` -- a boolean (default: ``True``) - Whether to draw a line to separate the entries in the array. + - ``array`` -- list of list + - ``with_lines`` -- boolean (default: ``True``); whether to draw a line to + separate the entries in the array Empty rows are allowed; however, such rows should be given as ``[None]`` rather than ``[]``. @@ -248,9 +249,9 @@ def tex_from_array_tuple(a_tuple, with_lines=True): INPUT: - - ``a_tuple`` -- a tuple of lists of lists - - ``with_lines`` -- a boolean (default: ``True``) - Whether to draw lines to separate the entries in the components of ``a_tuple``. + - ``a_tuple`` -- tuple of lists of lists + - ``with_lines`` -- boolean (default: ``True``); whether to draw lines to + separate the entries in the components of ``a_tuple`` .. SEEALSO:: :meth:`tex_from_array` for the description of each array @@ -347,12 +348,12 @@ def tex_from_skew_array(array, with_lines=False, align='b'): INPUT: - - ``array`` -- The array + - ``array`` -- the array - - ``with_lines`` -- (Default: ``False``) If ``True`` lines are drawn, if + - ``with_lines`` -- (default: ``False``) if ``True`` lines are drawn, if ``False`` they are not - - ``align`` -- (Default: ``'b'``) Determines the alignment on the latex + - ``align`` -- (default: ``'b'``) determine the alignment on the latex array environments EXAMPLES:: @@ -412,7 +413,7 @@ def end_line(r): return tex+r'\end{array}$'+raisebox_end -def ascii_art_table(data, use_unicode=False, convention="English"): +def ascii_art_table(data, use_unicode=False, convention='English'): r""" Return an ascii art table of ``data``. @@ -772,7 +773,7 @@ def box_exists(tab, i, j): INPUT: - - ``tab`` -- a list of lists + - ``tab`` -- list of lists - ``i`` -- first coordinate - ``j`` -- second coordinate diff --git a/src/sage/combinat/parallelogram_polyomino.py b/src/sage/combinat/parallelogram_polyomino.py index 53d35bca831..ed9308e82e9 100644 --- a/src/sage/combinat/parallelogram_polyomino.py +++ b/src/sage/combinat/parallelogram_polyomino.py @@ -62,7 +62,7 @@ class LocalOptions: INPUT: - - ``name`` -- The name of the LocalOptions + - ``name`` -- the name of the LocalOptions - ``=dict(...)`` -- dictionary specifying an option @@ -73,7 +73,7 @@ class LocalOptions: - ``checker`` -- a function for checking whether a particular value for the option is valid - ``default`` -- the default value of the option - - ``values`` -- a dictionary of the legal values for this option (this + - ``values`` -- dictionary of the legal values for this option (this automatically defines the corresponding ``checker``); this dictionary gives the possible options, as keys, together with a brief description of them @@ -111,7 +111,7 @@ def __init__(self, name='', **options): INPUT: - - ``name`` -- The name of the LocalOptions + - ``name`` -- the name of the LocalOptions - ``=dict(...)`` -- dictionary specifying an option @@ -122,7 +122,7 @@ def __init__(self, name='', **options): - ``checker`` -- a function for checking whether a particular value for the option is valid - ``default`` -- the default value of the option - - ``values`` -- a dictionary of the legal values for this option (this + - ``values`` -- dictionary of the legal values for this option (this automatically defines the corresponding ``checker``); this dictionary gives the possible options, as keys, together with a brief description of them. @@ -135,14 +135,14 @@ def __init__(self, name='', **options): sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -168,14 +168,14 @@ def __repr__(self) -> str: sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -205,9 +205,9 @@ def __setitem__(self, key, value): INPUT: - - ``key`` -- An option. + - ``key`` -- an option - - ``value`` -- The value. + - ``value`` -- the value EXAMPLES:: @@ -217,14 +217,14 @@ def __setitem__(self, key, value): sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -251,7 +251,6 @@ def __setitem__(self, key, value): sage: o("size") 3 sage: o["size"]=-6 - """ assert (key in self._available_options) if value == "?": @@ -274,10 +273,10 @@ def __call__(self, *get_values, **options): INPUT: - - ``get_values`` -- The options to be printed. + - ``get_values`` -- the options to be printed - ``=dict(...)`` -- dictionary specifying an option see - :class:`LocalOptions` for more details. + :class:`LocalOptions` for more details EXAMPLES:: @@ -287,14 +286,14 @@ def __call__(self, *get_values, **options): sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -303,15 +302,14 @@ def __call__(self, *get_values, **options): ....: ) sage: o("display") 'list' - sage: o(display="diagram") + sage: o(display='diagram') sage: o("display") 'diagram' - sage: o(display="?") + sage: o(display='?') Current value : diagram {'default': 'list', 'values': {'diagram': 'diagram representation', 'list': 'list representation'}} - """ for key in options: value = options[key] @@ -325,7 +323,7 @@ def __getitem__(self, key): INPUT: - - ``key`` -- An option. + - ``key`` -- an option EXAMPLES:: @@ -335,14 +333,14 @@ def __getitem__(self, key): sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -366,14 +364,14 @@ def __iter__(self): sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -397,14 +395,14 @@ def keys(self) -> list[str]: sage: o = LocalOptions( ....: "Name Example", ....: tikz_options=dict( - ....: default="toto", + ....: default='toto', ....: values=dict( - ....: toto="name", + ....: toto='name', ....: x="3" ....: ) ....: ), ....: display=dict( - ....: default="list", + ....: default='list', ....: values=dict( ....: list="list representation", ....: diagram="diagram representation" @@ -497,14 +495,14 @@ def _dispatch(self, obj, dispatch_to, option, *get_values, **set_values): ) ), display=dict( - default="list", + default='list', values=dict( list='displayed as list', drawing='as a drawing', ) ), latex=dict( - default="drawing", + default='drawing', values=dict( list='displayed as list', drawing='as a drawing', @@ -595,7 +593,6 @@ class _drawing_tool: sage: dt.draw_line([1, 1], [-1, -1]) '\n \\draw[color=black, line width=1] (-1.000000, 1.000000) -- (1.000000, -1.000000);' - """ def __init__(self, options, XY=lambda v: v): @@ -606,8 +603,8 @@ def __init__(self, options, XY=lambda v: v): - ``options`` -- drawing options - - ``XY`` -- A user function to convert vector in other vector. - (default : identity function) + - ``XY`` -- a user function to convert vector in other vector + (default: identity function) EXAMPLES:: @@ -643,11 +640,9 @@ def XY(self, v): INPUT: - - ``v`` -- The vector to transform. + - ``v`` -- the vector to transform - OUTPUT: - - A list of 2 floats encoding a vector. + OUTPUT: list of 2 floats encoding a vector EXAMPLES:: @@ -677,9 +672,9 @@ def translate(pos, v): INPUT: - - ``pos`` -- The position to translate. + - ``pos`` -- the position to translate - - ``v`` -- The translation vector. + - ``v`` -- the translation vector OUTPUT: @@ -693,9 +688,9 @@ def rotate(pos, angle): INPUT: - - ``pos`` -- The position to rotate. + - ``pos`` -- the position to rotate - - ``angle`` -- The angle of rotation. + - ``angle`` -- the angle of rotation OUTPUT: @@ -710,9 +705,9 @@ def mirror(pos, axe): INPUT: - - ``pos`` -- The position to mirror. + - ``pos`` -- the position to mirror - - ``axe`` -- The axe vector. + - ``axe`` -- the axe vector OUTPUT: @@ -747,21 +742,19 @@ def draw_line(self, v1, v2, color=None, size=None): INPUT: - - ``v1`` -- point, The first point of the line. + - ``v1`` -- point, The first point of the line - - ``v2`` -- point, The second point of the line. + - ``v2`` -- point, The second point of the line - - ``color`` -- string (default:``None``), The color of the line. + - ``color`` -- string (default: ``None``); the color of the line. If set to ``None``, the color is chosen according the drawing option given by ``_drawing_tool``. - - ``size`` -- integer (default:``None``), The size of the line. + - ``size`` -- integer (default: ``None``); the size of the line. If set to ``None``, the size is chosen according the drawing option given by ``_drawing_tool``. - OUTPUT: - - The code of a line in TIKZ. + OUTPUT: the code of a line in TIKZ EXAMPLES:: @@ -790,19 +783,17 @@ def draw_polyline(self, list_of_vertices, color=None, size=None): INPUT: - - ``list_of_vertices`` -- A list of points + - ``list_of_vertices`` -- list of points - - ``color`` -- string (default:``None``), The color of the line. + - ``color`` -- string (default: ``None``); the color of the line. If set to ``None``, the color is chosen according the drawing option given by ``_drawing_tool``. - - ``size`` -- integer (default:``None``), The size of the line. + - ``size`` -- integer (default: ``None``); the size of the line. If set to ``None``, the size is chosen according the drawing option given by ``_drawing_tool``. - OUTPUT: - - The code of a polyline in TIKZ. + OUTPUT: the code of a polyline in TIKZ EXAMPLES:: @@ -826,22 +817,19 @@ def draw_point(self, p1, color=None, size=None): r""" Return the TIKZ code for a point. - INPUT: - - ``p1`` -- A point + - ``p1`` -- a point - - ``color`` -- string (default:``None``), The color of the line. + - ``color`` -- string (default: ``None``); the color of the line. If set to ``None``, the color is chosen according the drawing option given by ``_drawing_tool``. - - ``size`` -- integer (default:``None``), The size of the line. + - ``size`` -- integer (default: ``None``); the size of the line. If set to ``None``, the size is chosen according the drawing option given by ``_drawing_tool``. - OUTPUT: - - The code of a point in TIKZ. + OUTPUT: the code of a point in TIKZ EXAMPLES:: @@ -1124,7 +1112,7 @@ def __hash__(self): def __copy__(self): r""" - Copy a parallelogram Polyomino + Copy a parallelogram Polyomino. EXAMPLES:: @@ -1250,7 +1238,6 @@ def _to_dyck_delest_viennot(self): sage: pp = ParallelogramPolyomino([[1], [1]]) sage: pp._to_dyck_delest_viennot() [] - """ from sage.combinat.dyck_word import DyckWord dyck = [] @@ -1306,14 +1293,12 @@ def to_dyck_word(self, bijection=None): INPUT: - - ``bijection`` -- string or ``None`` (default:``None``) The name of + - ``bijection`` -- string or ``None`` (default: ``None``); the name of the bijection. If it is set to ``None`` then the ``'Delest-Viennot'`` bijection is used. Expected values are ``None``, ``'Delest-Viennot'``, or ``'Delest-Viennot-beta'``. - OUTPUT: - - a Dyck word + OUTPUT: a Dyck word EXAMPLES:: @@ -1346,9 +1331,7 @@ def _from_dyck_word_delest_viennot(dyck): - ``dyck`` -- a Dyck word - OUTPUT: - - A parallelogram polyomino. + OUTPUT: a parallelogram polyomino EXAMPLES:: @@ -1384,9 +1367,7 @@ def _from_dyck_word_delest_viennot_peaks_valleys(dyck): - ``dyck`` -- a Dyck word - OUTPUT: - - A parallelogram polyomino. + OUTPUT: a parallelogram polyomino EXAMPLES:: @@ -1436,12 +1417,10 @@ def from_dyck_word(dyck, bijection=None): - ``dyck`` -- a Dyck word - - ``bijection`` -- string or ``None`` (default:``None``) the bijection - to use. See :meth:`to_dyck_word` for more details. - - OUTPUT: + - ``bijection`` -- string or ``None`` (default: ``None``); the + bijection to use. See :meth:`to_dyck_word` for more details. - A parallelogram polyomino. + OUTPUT: a parallelogram polyomino EXAMPLES:: @@ -1472,8 +1451,8 @@ def _to_binary_tree_Aval_Boussicault(self, position=None): INPUT: - - ``position`` -- the cell position. This is a recursive parameter. - It should not be used directly. + - ``position`` -- the cell position; this is a recursive parameter + It should not be used directly EXAMPLES:: @@ -1529,7 +1508,7 @@ def to_binary_tree(self, bijection=None): INPUT: - - ``bijection`` -- string or ``None`` (default:``None``) The name of + - ``bijection`` -- string or ``None`` (default: ``None``); the name of bijection to use for the conversion. The possible values are ``None`` or ``'Aval-Boussicault'``. The ``None`` value is equivalent to ``'Aval-Boussicault'``. @@ -1722,7 +1701,7 @@ def to_ordered_tree(self, bijection=None): INPUT: - - ``bijection`` -- string or ``None`` (default:``None``) The name of + - ``bijection`` -- string or ``None`` (default: ``None``); the name of bijection to use for the conversion. The possible value are ``None``, ``'Boussicault-Socci'`` or ``'via dyck and Delest-Viennot'``. The ``None`` value is equivalent to the ``'Boussicault-Socci'`` @@ -1871,13 +1850,11 @@ def _prefix_lengths(word, up): INPUT: - - ``word`` -- a word of 0 and 1. + - ``word`` -- a word of 0 and 1 - ``up`` -- 0 or 1 (a letter of the word) - OUTPUT: - - A list of integers + OUTPUT: list of integers EXAMPLES:: @@ -1904,9 +1881,7 @@ def upper_heights(self): Return the list of heights associated to each vertical step of the parallelogram polyomino's upper path. - OUTPUT: - - A list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -1924,9 +1899,7 @@ def lower_heights(self): Return the list of heights associated to each vertical step of the parallelogram polyomino's lower path. - OUTPUT: - - A list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -1944,9 +1917,7 @@ def upper_widths(self): Return the list of widths associated to each horizontal step of the parallelogram polyomino's upper path. - OUTPUT: - - A list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -1964,9 +1935,7 @@ def lower_widths(self): Return the list of widths associated to each horizontal step of the parallelogram polyomino's lower path. - OUTPUT: - - A list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -2088,7 +2057,7 @@ def is_k_directed(self, k) -> bool: INPUT: - - ``k`` -- A non negative integer. + - ``k`` -- nonnegative integer EXAMPLES:: @@ -2216,9 +2185,9 @@ def cell_is_inside(self, w, h): INPUT: - - ``w`` -- The x coordinate of the box position. + - ``w`` -- the x coordinate of the box position - - ``h`` -- The y coordinate of the box position. + - ``h`` -- the y coordinate of the box position OUTPUT: @@ -2314,7 +2283,7 @@ class _polyomino_row: def __init__(self, polyomino, row): r""" - The constructor of the class + The constructor of the class. EXAMPLES:: @@ -2502,7 +2471,7 @@ def bounce_path(self, direction=1): INPUT: - ``direction`` -- the initial direction of the bounce path (see above - for the definition). + for the definition) EXAMPLES:: @@ -2589,7 +2558,7 @@ def bounce(self, direction=1): INPUT: - ``direction`` -- the initial direction of the bounce path - (see :meth:`bounce_path` for the definition). + (see :meth:`bounce_path` for the definition) EXAMPLES:: @@ -2763,7 +2732,6 @@ def _to_tikz_diagram(self): (3.000000, 2.000000); \draw[color=black, line width=1] (1.000000, 1.000000) -- (3.000000, 1.000000); - """ tikz_options = self.get_tikz_options() grid_width = self.width() + 1 @@ -2984,9 +2952,7 @@ def _get_node_position_at_row(self, row): - ``row`` -- the index of the row - OUTPUT: - - A [row,column] position of the cell. + OUTPUT: a [row,column] position of the cell EXAMPLES:: @@ -3031,9 +2997,7 @@ def _get_node_position_at_column(self, column): - ``column`` -- the index of the column - OUTPUT: - - A [row,column] position of the cell. + OUTPUT: a [row,column] position of the cell EXAMPLES:: @@ -3082,16 +3046,14 @@ def get_node_position_from_box(self, box_position, direction, nb_crossed_nodes=N INPUT: - - ``box_position`` -- the position of the statring cell. + - ``box_position`` -- the position of the statring cell - - ``direction`` -- the direction (0 or 1). + - ``direction`` -- the direction (0 or 1) - ``nb_crossed_nodes`` -- ``[0]`` (default) a list containing just one - integer. + integer - OUTPUT: - - A [row,column] position of the cell. + OUTPUT: a [row,column] position of the cell EXAMPLES:: @@ -3149,7 +3111,7 @@ def get_node_position_from_box(self, box_position, direction, nb_crossed_nodes=N def box_is_node(self, pos) -> bool: r""" - Return True if the box contains a node in the context of the + Return ``True`` if the box contains a node in the context of the Aval-Boussicault bijection between parallelogram polyomino and binary tree. @@ -3158,11 +3120,9 @@ def box_is_node(self, pos) -> bool: INPUT: - - ``pos`` -- the [x,y] coordinate of the box. - - OUTPUT: + - ``pos`` -- the [x,y] coordinate of the box - A boolean + OUTPUT: boolean EXAMPLES:: @@ -3198,7 +3158,7 @@ def box_is_root(self, box) -> bool: INPUT: - - ``box`` -- the x,y coordinate of the cell. + - ``box`` -- the x,y coordinate of the cell EXAMPLES:: @@ -3232,9 +3192,9 @@ def _get_number_of_nodes_in_the_bounding_path(self, box, direction): INPUT: - ``box`` -- the x,y coordinate of the starting point of the bounding - path. + path - ``direction`` -- the initial direction of the bounding path (1 or 0, - 1 for left and 0 for top). + 1 for left and 0 for top) EXAMPLES:: @@ -3314,11 +3274,9 @@ def _get_path_in_pair_of_tree_from_row(self, line): INPUT: - - ``line`` -- the x coordinate of the line. - - OUTPUT: + - ``line`` -- the x coordinate of the line - A list of integers + OUTPUT: list of integers EXAMPLES:: @@ -3349,7 +3307,6 @@ def _get_path_in_pair_of_tree_from_row(self, line): [0] sage: pp._get_path_in_pair_of_tree_from_row(0) [] - """ pos = self._get_node_position_at_row(line) return self._get_number_of_nodes_in_the_bounding_path(pos, 0) @@ -3375,11 +3332,9 @@ def _get_path_in_pair_of_tree_from_column(self, column): INPUT: - - ``column`` -- the y coordinate of the column. - - OUTPUT: + - ``column`` -- the y coordinate of the column - A list of integers + OUTPUT: list of integers EXAMPLES:: @@ -3496,9 +3451,7 @@ def get_left_BS_nodes(self): the Boussicault-Socci bijection between parallelogram polyominoes and pair of ordered trees. - OUTPUT: - - A list of [row,column] position of cells. + OUTPUT: list of [row,column] position of cells EXAMPLES:: @@ -3696,7 +3649,7 @@ def geometry(self) -> list: def _plot_diagram(self): r""" - Return a plot of the diagram representing ``self`` + Return a plot of the diagram representing ``self``. TESTS:: @@ -3748,7 +3701,7 @@ def _plot_bounce(self, directions=None): INPUT: - - ``directions`` -- direction(s) `0` and/or `1` of the bounce paths. + - ``directions`` -- direction(s) `0` and/or `1` of the bounce paths TESTS:: @@ -3764,7 +3717,6 @@ def _plot_bounce(self, directions=None): ....: ]) sage: pp._plot_bounce(directions=[0,1]) # needs sage.plot Graphics object consisting of 9 graphics primitives - """ if directions is None: directions = [0, 1] @@ -4009,7 +3961,7 @@ def __call__(self, size=None, policy=None): INPUT: - - ``size`` -- integer (default: ``None``), the size of the parallelogram + - ``size`` -- integer (default: ``None``); the size of the parallelogram polyominoes contained in the family. If set to ``None``, the family returned contains all the parallelogram polyominoes. diff --git a/src/sage/combinat/parking_functions.py b/src/sage/combinat/parking_functions.py index fc677e47f90..c42787d9d28 100644 --- a/src/sage/combinat/parking_functions.py +++ b/src/sage/combinat/parking_functions.py @@ -132,12 +132,10 @@ class ParkingFunction(ClonableArray, metaclass=InheritComparisonClasscallMetacla - ``area_sequence`` -- (default: ``None``) an area sequence of a Dyck path - - ``labelled_dyck_word`` -- (default: ``None``) a Dyck word with 1's + - ``labelled_dyck_word`` -- (default: ``None``) a Dyck word with 1s replaced by labelling - OUTPUT: - - A parking function + OUTPUT: a parking function EXAMPLES:: @@ -364,7 +362,6 @@ def cars_permutation(self) -> Permutation: means that car 2 takes spots 1, car 4 takes spot 2, ..., car 1 takes spot 6 and car 7 takes spot 7. - OUTPUT: - the permutation of cars corresponding to the parking function @@ -403,7 +400,6 @@ def jump_list(self) -> list: # cars displacements car 5 had to park one spot farther (jumped or was displaced by one spot), car 6 had to jump 3 spots, and car 7 had to jump two spots. - OUTPUT: - the displacements sequence of parked cars which corresponds @@ -462,10 +458,7 @@ def lucky_cars(self): # the set of cars that can park in their preferred spo ``lucky_cars(PF) = [1, 2, 7]`` means that cars 1, 2 and 7 parked in their preferred spots and all the other cars did not. - - OUTPUT: - - - the cars that can park in their preferred spots + OUTPUT: the cars that can park in their preferred spots EXAMPLES:: @@ -490,9 +483,7 @@ def luck(self) -> Integer: # the number of lucky cars Return the number of cars that parked in their preferred parking spots (see [Shin]_ p. 33). - OUTPUT: - - - the number of cars that parked in their preferred parking spots + OUTPUT: the number of cars that parked in their preferred parking spots EXAMPLES:: @@ -518,8 +509,8 @@ def primary_dinversion_pairs(self) -> list[tuple[int, int]]: OUTPUT: - - the pairs `(i, j)` such that `i < j`, and `i^{th}` area = `j^{th}` area, - and `i^{th}` label < `j^{th}` label + The pairs `(i, j)` such that `i < j`, and `i`-th area = `j`-th area, + and `i`-th label < `j`-th label EXAMPLES:: @@ -548,8 +539,8 @@ def secondary_dinversion_pairs(self) -> list[tuple[int, int]]: OUTPUT: - - the pairs `(i, j)` such that `i < j`, and `i^{th}` area = `j^{th}` area +1, - and `i^{th}` label > `j^{th}` label + The pairs `(i, j)` such that `i < j`, and `i`-th area = `j`-th area +1, + and `i`-th label > `j`-th label EXAMPLES:: @@ -576,9 +567,7 @@ def dinversion_pairs(self) -> list[tuple[int, int]]: Return the descent inversion pairs of a labelled Dyck path corresponding to the parking function. - OUTPUT: - - - the primary and secondary diversion pairs + OUTPUT: the primary and secondary diversion pairs EXAMPLES:: @@ -604,9 +593,7 @@ def dinv(self) -> int: Same as the cardinality of :meth:`dinversion_pairs`. - OUTPUT: - - - the number of dinversion pairs + OUTPUT: the number of dinversion pairs EXAMPLES:: @@ -795,9 +782,7 @@ def to_labelling_permutation(self) -> Permutation: r""" Return the labelling of the support Dyck path of the parking function. - OUTPUT: - - - the labelling of the Dyck path + OUTPUT: the labelling of the Dyck path EXAMPLES:: @@ -822,9 +807,7 @@ def to_area_sequence(self) -> list: Return the area sequence of the support Dyck path of the parking function. - OUTPUT: - - - the area sequence of the Dyck path + OUTPUT: the area sequence of the Dyck path EXAMPLES:: @@ -879,9 +862,7 @@ def to_dyck_word(self) -> DyckWord: r""" Return the support Dyck word of the parking function. - OUTPUT: - - - the Dyck word of the corresponding parking function + OUTPUT: the Dyck word of the corresponding parking function .. SEEALSO:: :meth:`DyckWord` @@ -972,9 +953,7 @@ def to_NonDecreasingParkingFunction(self) -> PF: Return the non-decreasing parking function which underlies the parking function. - OUTPUT: - - - a sorted parking function + OUTPUT: a sorted parking function .. SEEALSO:: :meth:`NonDecreasingParkingFunction` @@ -1016,9 +995,7 @@ def characteristic_quasisymmetric_function(self, q=None, - ``R`` -- (default: ``R = QQ['q','t'].fraction_field()``) the base ring to do the calculations over - OUTPUT: - - - an element of the quasisymmetric functions over the ring ``R`` + OUTPUT: an element of the quasisymmetric functions over the ring ``R`` EXAMPLES:: @@ -1063,7 +1040,7 @@ def pretty_print(self, underpath=True): - ``underpath`` -- if the length of the parking function is less than or equal to 9 then display the labels under the - path if ``underpath`` is True otherwise display them to the + path if ``underpath`` is ``True`` otherwise display them to the right of the path (default: ``True``) EXAMPLES:: @@ -1330,7 +1307,7 @@ def __classcall_private__(cls, n=None): return ParkingFunctions_all() if not isinstance(n, (Integer, int)) or n < 0: - raise ValueError("%s is not a non-negative integer" % n) + raise ValueError("%s is not a nonnegative integer" % n) return ParkingFunctions_n(n) diff --git a/src/sage/combinat/partition.py b/src/sage/combinat/partition.py index 8f3222f804b..defa29342dc 100644 --- a/src/sage/combinat/partition.py +++ b/src/sage/combinat/partition.py @@ -6,8 +6,8 @@ partition) with total sum `n`. A partition can be depicted by a diagram made of rows of cells, -where the number of cells in the `i^{th}` row starting from -the top is the `i^{th}` part of the partition. +where the number of cells in the `i`-th row starting from +the top is the `i`-th part of the partition. The coordinate system related to a partition applies from the top to the bottom and from left to right. So, the corners of the @@ -330,7 +330,7 @@ class Partition(CombinatorialElement): A partition is often represented as a diagram consisting of **cells**, or **boxes**, placed in rows on top of each other such that the number of - cells in the `i^{th}` row, reading from top to bottom, is the `i^{th}` + cells in the `i`-th row, reading from top to bottom, is the `i`-th part of the partition. The rows are left-justified (and become shorter and shorter the farther down one goes). This diagram is called the **Young diagram** of the partition, or more precisely its Young diagram @@ -520,7 +520,7 @@ def __init__(self, parent, mu): Initialize ``self``. We assume that ``mu`` is a weakly decreasing list of - non-negative elements in ``ZZ``. + nonnegative elements in ``ZZ``. EXAMPLES:: @@ -851,7 +851,7 @@ def _latex_(self) -> str: \end{array}$} } - sage: Partitions.options(latex="young_diagram", convention="french") + sage: Partitions.options(latex='young_diagram', convention='french') sage: Partitions.options.latex='exp_high'; latex(mu) # indirect doctest 2,1 sage: Partitions.options.latex='exp_low'; latex(mu) # indirect doctest @@ -972,7 +972,7 @@ def ferrers_diagram(self) -> str: EXAMPLES:: sage: mu = Partition([5,5,2,1]) - sage: Partitions.options(diagram_str='*', convention="english") + sage: Partitions.options(diagram_str='*', convention='english') sage: print(mu.ferrers_diagram()) ***** ***** @@ -1463,10 +1463,10 @@ def has_rectangle(self, h, w) -> bool: INPUT: - - ``h`` -- An integer `h \geq 1`. The (*minimum*) height of the - rectangle. + - ``h`` -- integer `h \geq 1`; the (*minimum*) height of the + rectangle - - ``w`` -- An integer `w \geq 1`. The width of the rectangle. + - ``w`` -- integer `w \geq 1`; the width of the rectangle EXAMPLES:: @@ -1654,16 +1654,16 @@ def next_within_bounds(self, min=[], max=None, partition_type=None): INPUT: - - ``min`` -- (default ``[]``, the empty partition) The - 'minimum partition' that ``next_within_bounds(self)`` must contain. + - ``min`` -- (default: ``[]``, the empty partition) the + 'minimum partition' that ``next_within_bounds(self)`` must contain - - ``max`` -- (default ``None``) The 'maximum partition' that - ``next_within_bounds(self)`` must be contained in. If set to ``None``, - then there is no restriction. + - ``max`` -- (default: ``None``) the 'maximum partition' that + ``next_within_bounds(self)`` must be contained in; if set to ``None``, + then there is no restriction - - ``partition_type`` -- (default ``None``) The type of partitions - allowed. For example, 'strict' for strictly decreasing partitions, or - ``None`` to allow any valid partition. + - ``partition_type`` -- (default: ``None``) the type of partitions + allowed; for example, 'strict' for strictly decreasing partitions, or + ``None`` to allow any valid partition EXAMPLES:: @@ -1707,7 +1707,7 @@ def next_within_bounds(self, min=[], max=None, partition_type=None): # if there is no max, the next partition just tacks a '1' on to the end! if max is None: return _Partitions(p + [1]) - # extend p and min to include 0's at the end + # extend p and min to include 0s at the end p = p + [0] * (len(max) - len(p)) min = min + [0] * (len(max) - len(min)) # finally, run the algo to find next_p @@ -1850,7 +1850,7 @@ def down_list(self): return list(self.down()) @combinatorial_map(name="cell poset") - def cell_poset(self, orientation="SE"): + def cell_poset(self, orientation='SE'): """ Return the Young diagram of ``self`` as a poset. The optional keyword variable ``orientation`` determines the order relation @@ -1859,10 +1859,10 @@ def cell_poset(self, orientation="SE"): The poset always uses the set of cells of the Young diagram of ``self`` as its ground set. The order relation of the poset depends on the ``orientation`` variable (which defaults to - ``"SE"``). Concretely, ``orientation`` has to be specified to - one of the strings ``"NW"``, ``"NE"``, ``"SW"``, and ``"SE"``, + ``'SE'``). Concretely, ``orientation`` has to be specified to + one of the strings ``'NW'``, ``'NE'``, ``'SW'``, and ``'SE'``, standing for "northwest", "northeast", "southwest" and - "southeast", respectively. If ``orientation`` is ``"SE"``, then + "southeast", respectively. If ``orientation`` is ``'SE'``, then the order relation of the poset is such that a cell `u` is greater or equal to a cell `v` in the poset if and only if `u` lies weakly southeast of `v` (this means that `u` can be @@ -2062,7 +2062,6 @@ def frobenius_coordinates(self): ([2, 1, 0], [2, 1, 0]) sage: Partition([9,1,1,1,1,1,1]).frobenius_coordinates() ([8], [6]) - """ mu = self muconj = mu.conjugate() # Naive implementation @@ -2355,7 +2354,7 @@ def generalized_pochhammer_symbol(self, a, alpha): def get_part(self, i, default=Integer(0)): r""" - Return the `i^{th}` part of ``self``, or ``default`` if it does + Return the `i`-th part of ``self``, or ``default`` if it does not exist. EXAMPLES:: @@ -2599,7 +2598,7 @@ def suter_diagonal_slide(self, n, exp=1): northwestern most cell in English notation) of `\lambda` is less than `n`, including the empty partition. - The map `\sigma_n` sends a partition (with non-zero entries) + The map `\sigma_n` sends a partition (with nonzero entries) `(\lambda_1, \lambda_2, \ldots, \lambda_m) \in Y_n` to the partition `(\lambda_2 + 1, \lambda_3 + 1, \ldots, \lambda_m + 1, \underbrace{1, 1, \ldots, 1}_{n - m - \lambda_1\text{ ones}})`. @@ -2774,7 +2773,7 @@ def initial_column_tableau(self): r""" Return the initial column tableau of shape ``self``. - The initial column tableau of shape self is the standard tableau + The initial column tableau of shape ``self`` is the standard tableau that has the numbers `1` to `n`, where `n` is the :meth:`size` of ``self``, entered in order from top to bottom and then left to right down the columns of ``self``. @@ -2947,10 +2946,10 @@ def ladder_tableau(self, e, ladder_lengths=False): INPUT: - - ``e`` -- a nonnegative integer; ``0`` is considered as `\infty` + - ``e`` -- nonnegative integer; `0` is considered as `\infty` (analogous to the characteristic of a ring) - - ``ladder_sizes`` -- (default: ``False``) if ``True``, also return - the sizes of the ladders + - ``ladder_sizes`` -- boolean (default: ``False``); if ``True``, also + return the sizes of the ladders .. SEEALSO:: @@ -3009,7 +3008,7 @@ def ladders(self, e): INPUT: - - ``e`` -- a nonnegative integer; if ``0``, then we + - ``e`` -- nonnegative integer; if ``0``, then we set ``e = self.size() + 1`` EXAMPLES:: @@ -3141,9 +3140,7 @@ def degree(self, e): - ``e`` -- an integer `e > 1` - OUTPUT: - - A non-negative integer. + OUTPUT: nonnegative integer EXAMPLES:: @@ -3177,11 +3174,9 @@ def prime_degree(self, p): INPUT: - - ``p`` -- a prime integer + - ``p`` -- prime integer - OUTPUT: - - A non-negative integer + OUTPUT: nonnegative integer The degree of a partition `\lambda` is the sum of the `e`-:meth:`degree` of the standard tableaux of shape `\lambda`, for @@ -3223,9 +3218,7 @@ def arm_length(self, i, j): - ``i``, ``j`` -- two integers - OUTPUT: - - An integer or a :class:`ValueError` + OUTPUT: integer or a :exc:`ValueError` EXAMPLES:: @@ -3284,9 +3277,7 @@ def arm_cells(self, i, j): - ``i``, ``j`` -- two integers - OUTPUT: - - A list of pairs of integers + OUTPUT: list of pairs of integers EXAMPLES:: @@ -3317,9 +3308,7 @@ def leg_length(self, i, j): - ``i``, ``j`` -- two integers - OUTPUT: - - An integer or a :class:`ValueError` + OUTPUT: integer or a :exc:`ValueError` EXAMPLES:: @@ -3379,9 +3368,7 @@ def leg_cells(self, i, j): - ``i``, ``j`` -- two integers - OUTPUT: - - A list of pairs of integers + OUTPUT: list of pairs of integers EXAMPLES:: @@ -3953,7 +3940,7 @@ def block(self, e, multicharge=(0,)): - ``e`` -- the quantum characteristic - - ``multicharge`` -- the multicharge (default `(0,)`) + - ``multicharge`` -- the multicharge (default: `(0,)`) OUTPUT: @@ -4021,12 +4008,10 @@ def defect(self, e, multicharge=(0,)): - ``e`` -- the quantum characteristic - - ``multicharge`` -- the multicharge (default `(0,)`) + - ``multicharge`` -- the multicharge (default: `(0,)`) - OUTPUT: - - - a non-negative integer, which is the defect of the block - containing the partition ``self`` + OUTPUT: nonnegative integer, which is the defect of the block + containing the partition ``self`` EXAMPLES:: @@ -4118,7 +4103,7 @@ def is_regular(self, e, multicharge=(0,)) -> bool: Return ``True`` is this is an ``e``-regular partition. A partition is `e`-regular if it does not have `e` equal - non-zero parts. + nonzero parts. EXAMPLES:: @@ -4374,8 +4359,8 @@ def zero_one_sequence(self): that in English convention, a 1 corresponds to an East step, and a 0 corresponds to a North step. - Note that every full `0-1` sequence starts with infinitely many 0's and - ends with infinitely many 1's. + Note that every full `0-1` sequence starts with infinitely many 0s and + ends with infinitely many 1s. One place where these arise is in the affine symmetric group where one takes an affine permutation `w` and every `i` such that @@ -4390,7 +4375,7 @@ def zero_one_sequence(self): OUTPUT: The finite `0-1` sequence is obtained from the full `0-1` - sequence by omitting all heading 0's and trailing 1's. The + sequence by omitting all heading 0s and trailing 1s. The output sequence is finite, starts with a 1 and ends with a 0 (unless it is empty, for the empty partition). Its length is the sum of the first part of the partition with the @@ -4687,11 +4672,9 @@ def k_irreducible(self, k): INPUT: - - ``k`` -- a non-negative integer - - OUTPUT: + - ``k`` -- nonnegative integer - - a partition + OUTPUT: a partition EXAMPLES:: @@ -4768,7 +4751,7 @@ def k_skew(self, k): def to_core(self, k): r""" - Maps the `k`-bounded partition ``self`` to its corresponding `k+1`-core. + Map the `k`-bounded partition ``self`` to its corresponding `k+1`-core. See also :meth:`k_skew`. @@ -4787,7 +4770,7 @@ def to_core(self, k): def from_kbounded_to_reduced_word(self, k): r""" - Maps a `k`-bounded partition to a reduced word for an element in + Map a `k`-bounded partition to a reduced word for an element in the affine permutation group. This uses the fact that there is a bijection between `k`-bounded @@ -4823,7 +4806,7 @@ def from_kbounded_to_reduced_word(self, k): def from_kbounded_to_grassmannian(self, k): r""" - Maps a `k`-bounded partition to a Grassmannian element in + Map a `k`-bounded partition to a Grassmannian element in the affine Weyl group of type `A_k^{(1)}`. For details, see the documentation of the method @@ -5364,11 +5347,9 @@ def dimension(self, smaller=None, k=1): - ``smaller`` -- a partition (default: an empty list ``[]``) - - `k` -- a positive integer (default: 1) - - OUTPUT: + - ``k`` -- positive integer (default: 1) - The number of such paths + OUTPUT: the number of such paths EXAMPLES: @@ -5514,7 +5495,7 @@ def outline(self, variable=None): INPUT: - - variable -- a variable (default: ``'x'`` in the symbolic ring) + - ``variable`` -- a variable (default: ``'x'`` in the symbolic ring) EXAMPLES:: @@ -5575,11 +5556,10 @@ def dual_equivalence_graph(self, directed=False, coloring=None): INPUT: - - ``directed`` -- (default: ``False``) whether to have the dual - equivalence graph be directed (where we have a directed edge - `S \to T` if `i` appears to the left of `i+1` in the - reading word of `T`; otherwise we have the directed edge - `T \to S`) + - ``directed`` -- boolean (default: ``False``); whether to have the + dual equivalence graph be directed (where we have a directed edge + `S \to T` if `i` appears to the left of `i+1` in the reading word of + `T`; otherwise we have the directed edge `T \to S`) - ``coloring`` -- (optional) a function which sends each integer `i > 1` to a color (as a string, e.g., ``'red'`` or @@ -5658,7 +5638,7 @@ def coloring(i): elif isinstance(coloring, dict): d = coloring coloring = lambda x: d[x] - G.set_latex_options(format="dot2tex", + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label=coloring) return G @@ -5691,11 +5671,11 @@ def coloring(i): if directed: from sage.graphs.digraph import DiGraph - self._DDEG = DiGraph([T, edges], format="vertices_and_edges", + self._DDEG = DiGraph([T, edges], format='vertices_and_edges', immutable=True, multiedges=True) else: from sage.graphs.graph import Graph - self._DEG = Graph([T, edges], format="vertices_and_edges", + self._DEG = Graph([T, edges], format='vertices_and_edges', immutable=True, multiedges=True) return self.dual_equivalence_graph(directed, coloring) @@ -6196,7 +6176,7 @@ def __classcall_private__(cls, n=None, **kwargs): kwargs['max_slope'] = min(0, kwargs.get('max_slope', 0)) if kwargs.get('min_slope', -float('inf')) > 0: - raise ValueError("the minimum slope must be non-negative") + raise ValueError("the minimum slope must be nonnegative") if 'outer' in kwargs: kwargs['max_length'] = min(len(kwargs['outer']), @@ -6241,8 +6221,8 @@ def __init__(self, is_infinite=False): INPUT: - - ``is_infinite`` -- (Default: ``False``) If ``True``, then the number - of partitions in this set is infinite. + - ``is_infinite`` -- boolean (default: ``False``); if ``True``, then + the number of partitions in this set is infinite EXAMPLES:: @@ -6261,7 +6241,7 @@ def __init__(self, is_infinite=False): # add options to class class options(GlobalOptions): r""" - Sets and displays the global options for elements of the partition, + Set and display the global options for elements of the partition, skew partition, and partition tuple classes. If no parameters are set, then the function returns a copy of the options dictionary. @@ -6290,13 +6270,13 @@ class options(GlobalOptions): <4,2,2,1> sage: Partitions.options(latex=lambda mu: '\\Diagram{%s}' % ','.join('%s'%m for m in mu._list)); latex(P) \Diagram{4,2,2,1} - sage: Partitions.options(display="diagram", diagram_str="#") + sage: Partitions.options(display='diagram', diagram_str='#') sage: P #### ## ## # - sage: Partitions.options(diagram_str="*", convention="french") + sage: Partitions.options(diagram_str='*', convention='french') sage: print(P.ferrers_diagram()) * ** @@ -6393,7 +6373,6 @@ def _element_constructor_(self, lst): Traceback (most recent call last): ... ValueError: all parts of [3/2] should be nonnegative integers - """ if isinstance(lst, PartitionTuple): if lst.level() != 1: @@ -6448,7 +6427,6 @@ def __contains__(self, x): sage: 0 in P False - """ if isinstance(x, Partition): return True @@ -6461,7 +6439,7 @@ def subset(self, *args, **kwargs): r""" Return ``self`` if no arguments are given. - Otherwise, it raises a :class:`ValueError`. + Otherwise, it raises a :exc:`ValueError`. EXAMPLES:: @@ -6612,11 +6590,11 @@ def from_beta_numbers(self, beta): Return a partition corresponding to a sequence of beta numbers. A sequence of beta numbers is a strictly increasing sequence - `0 \leq b_1 < \cdots < b_k` of non-negative integers. The + `0 \leq b_1 < \cdots < b_k` of nonnegative integers. The corresponding partition `\mu = (\mu_k, \ldots, \mu_1)` is given by `\mu_i = [1,i) \setminus \{ b_1, \ldots, b_i \}`. This gives - a bijection from the set of partitions with at most `k` non-zero parts - to the set of strictly increasing sequences of non-negative integers + a bijection from the set of partitions with at most `k` nonzero parts + to the set of strictly increasing sequences of nonnegative integers of length `k`. EXAMPLES:: @@ -6658,8 +6636,8 @@ def from_zero_one(self, seq): that in English convention, a 1 corresponds to an East step, and a 0 corresponds to a North step. - Note that every full `0-1` sequence starts with infinitely many 0's and - ends with infinitely many 1's. + Note that every full `0-1` sequence starts with infinitely many 0s and + ends with infinitely many 1s. .. SEEALSO:: @@ -6667,8 +6645,8 @@ def from_zero_one(self, seq): INPUT: - The input should be a finite sequence of 0's and 1's. The - heading 0's and trailing 1's will be discarded. + The input should be a finite sequence of 0s and 1s. The + heading 0s and trailing 1s will be discarded. EXAMPLES:: @@ -6679,7 +6657,7 @@ def from_zero_one(self, seq): sage: Partitions().from_zero_one([1, 1, 1, 1, 0, 1, 0]) [5, 4] - Heading 0's and trailing 1's are correctly handled:: + Heading 0s and trailing 1s are correctly handled:: sage: Partitions().from_zero_one([0,0,1,1,1,1,0,1,0,1,1,1]) [5, 4] @@ -6887,12 +6865,12 @@ def cardinality(self, algorithm='flint'): INPUT: - - ``algorithm`` -- (default: ``'flint'``) + - ``algorithm`` -- (default: ``'flint'``) - ``'flint'`` -- use FLINT (currently the fastest) - ``'gap'`` -- use GAP (VERY *slow*) - ``'pari'`` -- use PARI. Speed seems the same as GAP until - `n` is in the thousands, in which case PARI is faster. + `n` is in the thousands, in which case PARI is faster It is possible to associate with every partition of the integer `n` a conjugacy class of permutations in the symmetric group on `n` points @@ -7032,15 +7010,15 @@ def random_element_uniform(self): ALGORITHM: - - It is a python Implementation of RANDPAR, see [NW1978]_. The - complexity is unknown, there may be better algorithms. + - It is a python Implementation of RANDPAR, see [NW1978]_. The + complexity is unknown, there may be better algorithms. .. TODO:: Check in Knuth AOCP4. - - There is also certainly a lot of room for optimizations, see - comments in the code. + - There is also certainly a lot of room for optimizations, see + comments in the code. AUTHOR: @@ -7193,7 +7171,6 @@ def __iter__(self): sage: all(isinstance(i, Integer) for p in Partitions(4) for i in p) True - """ for p in ZS1_iterator(self.n): yield self.element_class(self, [Integer(i) for i in p]) @@ -7333,7 +7310,6 @@ def __iter__(self): sage: partitions = Partitions(9, length=3) sage: all(isinstance(i, Integer) for p in partitions for i in p) True - """ for p in ZS1_iterator_nk(self.n - self.k, self.k): v = [Integer(i + 1) for i in p] @@ -7565,7 +7541,6 @@ def _findfirst(self, n, parts): sage: p._findfirst(0, p.parts[:]) [] sage: p._findfirst(p.n, [10]) - """ if n == 0: return [] @@ -7621,7 +7596,7 @@ def _findlast(self, n, parts): - ``n`` -- nonnegative integer - - ``parts`` -- a sorted list of positive integers. + - ``parts`` -- a sorted list of positive integers OUTPUT: @@ -7675,15 +7650,15 @@ def __iter__(self): def _fast_iterator(self, n, parts): """ - A fast iterator for the partitions of ``n`` which returns lists and + A fast iterator for the partitions of `n` which returns lists and not partition types. This function is not intended to be called directly. INPUT: - - ``n`` -- nonnegative integer. + - ``n`` -- nonnegative integer - - ``parts`` -- a list of parts to use. This list will be + - ``parts`` -- list of parts to use. This list will be destroyed, so pass things here with ``foo[:]`` (or something equivalent) if you want to preserve your list. In particular, the ``__iter__`` method needs to use ``self.parts[:]``, or else we @@ -7718,20 +7693,18 @@ def _fast_iterator(self, n, parts): def _other_iterator(self, n, parts): """ - A fast iterator for the partitions of ``n`` which returns lists and + A fast iterator for the partitions of `n` which returns lists and not partition types. This function is not intended to be called directly. INPUT: - - ``n`` -- nonnegative integer. - - - ``parts`` -- a list of parts to use. + - ``n`` -- nonnegative integer - OUTPUT: + - ``parts`` -- list of parts to use - A generator object for partitions of `n` with parts in - ``parts``. + OUTPUT: a generator object for partitions of `n` with parts in + ``parts`` EXAMPLES:: @@ -7818,7 +7791,7 @@ def _repr_(self): def __contains__(self, x): """ - Checks if ``x`` is contained in ``self``. + Check if ``x`` is contained in ``self``. EXAMPLES:: @@ -7896,7 +7869,7 @@ def __classcall_private__(cls, n, ending_partition): def __init__(self, n, ending_partition): """ - Initializes ``self``. + Initialize ``self``. EXAMPLES:: @@ -7932,7 +7905,7 @@ def _repr_(self): def __contains__(self, x): """ - Checks if ``x`` is contained in ``self``. + Check if ``x`` is contained in ``self``. EXAMPLES:: @@ -8026,7 +7999,7 @@ def _repr_(self): def __contains__(self, x): """ - Checks if ``x`` is contained in ``self``. + Check if ``x`` is contained in ``self``. EXAMPLES:: @@ -8103,7 +8076,6 @@ def cardinality(self): ....: len(PartitionsInBox(a, b).list()) ....: for a in range(6) for b in range(6)) True - """ return binomial(self.h + self.w, self.w) @@ -8635,7 +8607,6 @@ def cardinality(self): sage: P = Partitions(5, regular=1) sage: P.cardinality() # needs sage.libs.flint 0 - """ if self._ell > self.n: return Partitions_n.cardinality(self) @@ -8700,7 +8671,6 @@ class OrderedPartitions(Partitions): [[9, 1], [8, 2], [7, 3], [6, 4], [5, 5], [4, 6], [3, 7], [2, 8], [1, 9]] sage: OrderedPartitions(4).list() # needs sage.libs.gap [[4], [3, 1], [2, 2], [2, 1, 1], [1, 3], [1, 2, 1], [1, 1, 2], [1, 1, 1, 1]] - """ @staticmethod @@ -8886,7 +8856,6 @@ def cardinality(self): ....: len(PartitionsGreatestLE(n, a).list()) ....: for n in range(20) for a in range(6)) True - """ return sum(number_of_partitions_length(self.n, i) for i in range(self.k+1)) @@ -8932,7 +8901,6 @@ class PartitionsGreatestEQ(UniqueRepresentation, IntegerListsLex): sage: PartitionsGreatestEQ(10, 2).first().parent() Partitions... - """ def __init__(self, n, k): @@ -8976,7 +8944,6 @@ def cardinality(self): ....: len(PartitionsGreatestEQ(n, a).list()) ....: for n in range(20) for a in range(6)) True - """ if not self.n: return 1 @@ -9276,15 +9243,15 @@ def number_of_partitions(n, algorithm='default'): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``algorithm`` -- (default: 'default') + - ``algorithm`` -- (default: ``'default'``) [Will be deprecated except in Partition().cardinality() ] - - ``'default'`` -- If ``k`` is not ``None``, then use Gap (very slow). - If ``k`` is ``None``, use FLINT. + - ``'default'`` -- if ``k`` is not ``None``, then use Gap (very slow); + if ``k`` is ``None``, use FLINT - - ``'flint'`` -- use FLINT + - ``'flint'`` -- use FLINT EXAMPLES:: @@ -9293,7 +9260,7 @@ def number_of_partitions(n, algorithm='default'): sage: len(v) 7 - The input must be a nonnegative integer or a :class:`ValueError` is raised. + The input must be a nonnegative integer or a :exc:`ValueError` is raised. :: @@ -9369,7 +9336,6 @@ def number_of_partitions(n, algorithm='default'): sage: n = 100000000 + randint(0,100000000) sage: number_of_partitions( n - (n % 385) + 369) % 385 == 0 # long time (4s on sage.math, 2011) True - """ n = ZZ(n) if n < 0: diff --git a/src/sage/combinat/partition_algebra.py b/src/sage/combinat/partition_algebra.py index cdc59830a28..f0d15115ac9 100644 --- a/src/sage/combinat/partition_algebra.py +++ b/src/sage/combinat/partition_algebra.py @@ -37,7 +37,7 @@ def _int_or_half_int(k): OUTPUT: - If ``k`` is not in `1/2 \ZZ`, then this raises a :class:`ValueError`. + If ``k`` is not in `1/2 \ZZ`, then this raises a :exc:`ValueError`. Otherwise, we return the pair: - boolean; ``True`` if ``k`` is an integer and ``False`` if a half integer @@ -851,7 +851,6 @@ def SetPartitionsPk(k): {{-1}, {-2}, {2}, {3, -3}, {1}} sage: P2p5.random_element() #random {{1, 2, 3, -3}, {-1, -2}} - """ is_int, k = _int_or_half_int(k) if not is_int: @@ -1579,7 +1578,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra A_%s(%s)" % (k, n) cclass = SetPartitionsAk(k) self._element_class = PartitionAlgebraElement_ak - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="A") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='A') class PartitionAlgebraElement_bk(PartitionAlgebraElement_generic): @@ -1600,7 +1599,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra B_%s(%s)" % (k, n) cclass = SetPartitionsBk(k) self._element_class = PartitionAlgebraElement_bk - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="B") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='B') class PartitionAlgebraElement_sk(PartitionAlgebraElement_generic): @@ -1621,7 +1620,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra S_%s(%s)" % (k, n) cclass = SetPartitionsSk(k) self._element_class = PartitionAlgebraElement_sk - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="S") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='S') class PartitionAlgebraElement_pk(PartitionAlgebraElement_generic): @@ -1642,7 +1641,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra P_%s(%s)" % (k, n) cclass = SetPartitionsPk(k) self._element_class = PartitionAlgebraElement_pk - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="P") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='P') class PartitionAlgebraElement_tk(PartitionAlgebraElement_generic): @@ -1663,7 +1662,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra T_%s(%s)" % (k, n) cclass = SetPartitionsTk(k) self._element_class = PartitionAlgebraElement_tk - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="T") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='T') class PartitionAlgebraElement_rk(PartitionAlgebraElement_generic): @@ -1684,7 +1683,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra R_%s(%s)" % (k, n) cclass = SetPartitionsRk(k) self._element_class = PartitionAlgebraElement_rk - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="R") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='R') class PartitionAlgebraElement_prk(PartitionAlgebraElement_generic): @@ -1705,7 +1704,7 @@ def __init__(self, R, k, n, name=None): name = "Partition algebra PR_%s(%s)" % (k, n) cclass = SetPartitionsPRk(k) self._element_class = PartitionAlgebraElement_prk - PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix="PR") + PartitionAlgebra_generic.__init__(self, R, cclass, n, k, name=name, prefix='PR') ########################################################## @@ -1949,8 +1948,8 @@ def to_set_partition(l, k=None): def identity(k): - """ - Return the identity set partition 1, -1, ..., k, -k + r""" + Return the identity set partition `1, -1, \ldots, k, -k`. EXAMPLES:: diff --git a/src/sage/combinat/partition_kleshchev.py b/src/sage/combinat/partition_kleshchev.py index 44204aad33b..cfa78933e37 100644 --- a/src/sage/combinat/partition_kleshchev.py +++ b/src/sage/combinat/partition_kleshchev.py @@ -131,14 +131,14 @@ def conormal_cells(self, i=None): EXAMPLES:: - sage: KP = KleshchevPartitions(3, convention="regular") + sage: KP = KleshchevPartitions(3, convention='regular') sage: KP([5,4,4,3,2]).conormal_cells() {0: [(1, 4)], 1: [(5, 0), (4, 2)]} sage: KP([5,4,4,3,2]).conormal_cells(0) [(1, 4)] sage: KP([5,4,4,3,2]).conormal_cells(1) [(5, 0), (4, 2)] - sage: KP = KleshchevPartitions(3, convention="restricted") + sage: KP = KleshchevPartitions(3, convention='restricted') sage: KP([5,4,4,3,2]).conormal_cells() {0: [(1, 4), (3, 3)], 2: [(0, 5)]} """ @@ -192,7 +192,7 @@ def cogood_cells(self, i=None): EXAMPLES:: - sage: KP = KleshchevPartitions(3, convention="regular") + sage: KP = KleshchevPartitions(3, convention='regular') sage: KP([5,4,4,3,2]).cogood_cells() {0: (1, 4), 1: (4, 2)} sage: KP([5,4,4,3,2]).cogood_cells(0) @@ -435,7 +435,7 @@ def is_regular(self): A partition tuple is `e`-regular if we can get to the empty partition tuple by successively removing a sequence of good cells in the down direction. Equivalently, all partitions are `0`-regular and if `e > 0` - then a partition is `e`-regular if no `e` non-zero parts of ``self`` + then a partition is `e`-regular if no `e` nonzero parts of ``self`` are equal. EXAMPLES:: @@ -788,7 +788,6 @@ def mullineux_conjugate(self): ([2, 2, 1, 1], [3, 2, 2, 1, 1]) sage: mc.parent() Kleshchev partitions with e=3 and multicharge=(0,2) - """ P = self.parent() if self.size() == 0: @@ -1098,7 +1097,7 @@ def f(self, i): class KleshchevPartitions(PartitionTuples): r""" - Kleshchev partitions + Kleshchev partitions. A partition (tuple) `\mu` is Kleshchev if it can be recursively obtained by adding a sequence of good nodes to the empty @@ -1279,7 +1278,6 @@ def _element_constructor_(self, mu): sage: KPls = KleshchevPartitions(2, [0,0], size=2, convention='left restricted') sage: [KPlg(mu) for mu in KPls] # indirect doc test [([1], [1]), ([2], [])] - """ if isinstance(mu, (KleshchevPartition, KleshchevPartitionTuple)): KPmu = mu.parent() @@ -1426,7 +1424,7 @@ class KleshchevPartitions_all(KleshchevPartitions): def __init__(self, e, multicharge, convention): r""" - Initializes ``self``. + Initialize ``self``. EXAMPLES:: diff --git a/src/sage/combinat/partition_shifting_algebras.py b/src/sage/combinat/partition_shifting_algebras.py index 90f1f10d59f..366200aefa3 100644 --- a/src/sage/combinat/partition_shifting_algebras.py +++ b/src/sage/combinat/partition_shifting_algebras.py @@ -92,7 +92,7 @@ def check(self, seq): r""" Verify that ``seq`` is a valid shifting sequence. - If it is not, raise a :class:`ValueError`. + If it is not, raise a :exc:`ValueError`. EXAMPLES:: @@ -164,7 +164,7 @@ class ShiftingOperatorAlgebra(CombinatorialFreeModule): - ``base_ring`` -- (default: ``QQ['t']``) the base ring - - ``prefix`` -- (default: ``"S"``) the label for the shifting operators + - ``prefix`` -- (default: ``'S'``) the label for the shifting operators EXAMPLES:: diff --git a/src/sage/combinat/partition_tuple.py b/src/sage/combinat/partition_tuple.py index bf40c650c33..0e0e8e4aae9 100644 --- a/src/sage/combinat/partition_tuple.py +++ b/src/sage/combinat/partition_tuple.py @@ -341,9 +341,9 @@ class of modules for the algebras which are generalisations of the Specht INPUT: - Anything which can reasonably be interpreted as a tuple of partitions. - That is, a list or tuple of partitions or valid input to - :class:`Partition`. + Anything which can reasonably be interpreted as a tuple of partitions. + That is, a list or tuple of partitions or valid input to + :class:`Partition`. EXAMPLES:: @@ -460,7 +460,6 @@ def __init__(self, parent, mu): Traceback (most recent call last): ... ValueError: [[], [], [2, 1, 2, 1]] is not a tuple of Partitions - """ mu = [_Partitions(nu) for nu in mu] CombinatorialElement.__init__(self, parent, mu) @@ -490,7 +489,6 @@ def __len__(self): sage: len( PartitionTuple([[2,1],[3,2],[1,1,1]]) ) 3 - """ return self.level() @@ -503,36 +501,36 @@ def _repr_(self, compact=None): sage: mu=PartitionTuple(([2,1],[3,2],[1,1,1])) # indirect doctest - sage: PartitionTuples.options(display="list"); mu + sage: PartitionTuples.options(display='list'); mu ([2, 1], [3, 2], [1, 1, 1]) - sage: PartitionTuples.options(display="diagram"); mu + sage: PartitionTuples.options(display='diagram'); mu ** *** * * ** * * - sage: PartitionTuples.options(display="compact_low"); mu + sage: PartitionTuples.options(display='compact_low'); mu 1,2|2,3|1^3 - sage: PartitionTuples.options(display="compact_high"); mu + sage: PartitionTuples.options(display='compact_high'); mu 2,1|3,2|1^3 - sage: PartitionTuples.options(display="exp_low"); mu + sage: PartitionTuples.options(display='exp_low'); mu 1, 2 | 2, 3 | 1^3 - sage: PartitionTuples.options(display="exp_high"); mu + sage: PartitionTuples.options(display='exp_high'); mu 2, 1 | 3, 2 | 1^3 sage: PartitionTuples.options._reset() - sage: Partitions.options(convention="French") - sage: PartitionTuples.options(display="diagram"); mu + sage: Partitions.options(convention='French') + sage: PartitionTuples.options(display='diagram'); mu * * ** * ** *** * - sage: PartitionTuples.options(display="list"); mu + sage: PartitionTuples.options(display='list'); mu ([2, 1], [3, 2], [1, 1, 1]) - sage: PartitionTuples.options(display="compact_low"); mu + sage: PartitionTuples.options(display='compact_low'); mu 1,2|2,3|1^3 - sage: PartitionTuples.options(display="compact_high"); mu + sage: PartitionTuples.options(display='compact_high'); mu 2,1|3,2|1^3 - sage: PartitionTuples.options(display="exp_low"); mu + sage: PartitionTuples.options(display='exp_low'); mu 1, 2 | 2, 3 | 1^3 - sage: PartitionTuples.options(display="exp_high"); mu + sage: PartitionTuples.options(display='exp_high'); mu 2, 1 | 3, 2 | 1^3 sage: PartitionTuples.options._reset() """ @@ -659,7 +657,7 @@ def _latex_(self): \end{array}$} } - sage: PartitionTuples.options(latex="young_diagram", convention="french") + sage: PartitionTuples.options(latex='young_diagram', convention='french') sage: PartitionTuples.options(latex='exp_high'); latex(mu) # indirect doctest (2,1|1^{3}) sage: PartitionTuples.options(latex='exp_low'); latex(mu) # indirect doctest @@ -785,7 +783,7 @@ def diagram(self): ** * * * * - sage: PartitionTuples.options(convention="french") + sage: PartitionTuples.options(convention='french') sage: print(PartitionTuple([[3,2],[2,1],[],[1,1,1,1]]).diagram()) * * @@ -818,7 +816,7 @@ def diagram(self): def pp(self): r""" - Pretty prints this partition tuple. See :meth:`diagram`. + Pretty print this partition tuple. See :meth:`diagram`. EXAMPLES:: @@ -899,7 +897,6 @@ def up_list(self): [([1], [3, 1], [1, 1]), ([], [4, 1], [1, 1]), ([], [3, 2], [1, 1]), ([], [3, 1, 1], [1, 1]), ([], [3, 1], [2, 1]), ([], [3, 1], [1, 1, 1])] sage: PartitionTuple([[],[],[],[]]).up_list() [([1], [], [], []), ([], [1], [], []), ([], [], [1], []), ([], [], [], [1])] - """ return list(self.up()) @@ -914,7 +911,6 @@ def down(self): [([], [2, 1], [1, 1]), ([], [3], [1, 1]), ([], [3, 1], [1])] sage: [mu for mu in PartitionTuple([[],[],[]]).down()] [] - """ for c in range(len(self)): for nu in self[c].down(): @@ -978,7 +974,6 @@ def content(self, k,r,c, multicharge): sage: multicharge = [IntegerModRing(3)(c) for c in [0,0,0]] sage: PartitionTuple([[2,1],[2],[1,1,1]]).content(0,1,0, multicharge) 2 - """ return multicharge[k]-r+c @@ -1279,13 +1274,11 @@ def arm_length(self, k,r,c): INPUT: - - ``k`` -- The component - - ``r`` -- The row - - ``c`` -- The cell + - ``k`` -- the component + - ``r`` -- the row + - ``c`` -- the cell - OUTPUT: - - - The arm length as an integer + OUTPUT: the arm length as an integer The arm of cell ``(k, r, c)`` is the number of cells in the ``k``-th component which are to the right of the cell in row ``r`` and column @@ -1311,13 +1304,11 @@ def leg_length(self, k,r,c): INPUT: - - ``k`` -- The component - - ``r`` -- The row - - ``c`` -- The cell - - OUTPUT: + - ``k`` -- the component + - ``r`` -- the row + - ``c`` -- the cell - - The leg length as an integer + OUTPUT: the leg length as an integer The leg of cell ``(k, r, c)`` is the number of cells in the ``k``-th component which are below the node in row ``r`` and column ``c``. @@ -1384,7 +1375,6 @@ def to_exp(self, k=0): ([2], [0, 1], [1, 1]) sage: PartitionTuple([[1,1],[2,2,2,2],[2,1]]).to_exp() ([2], [0, 4], [1, 1]) - """ return tuple(self[c].to_exp(k) for c in range(len(self))) @@ -1401,7 +1391,6 @@ def removable_cells(self): [(0, 1, 0), (1, 0, 1), (2, 0, 1), (2, 1, 0)] sage: PartitionTuple([[1,1],[4,3],[2,1,1]]).removable_cells() [(0, 1, 0), (1, 0, 3), (1, 1, 2), (2, 0, 1), (2, 2, 0)] - """ return [(k,r,c) for k in range(len(self)) for (r,c) in self[k].removable_cells()] @@ -1420,7 +1409,6 @@ def addable_cells(self): [(0, 0, 1), (0, 2, 0), (1, 0, 2), (1, 1, 0), (2, 0, 2), (2, 1, 1), (2, 2, 0)] sage: PartitionTuple([[1,1],[4,3],[2,1,1]]).addable_cells() [(0, 0, 1), (0, 2, 0), (1, 0, 4), (1, 1, 3), (1, 2, 0), (2, 0, 2), (2, 1, 1), (2, 3, 0)] - """ return [(k,r,c) for k in range(len(self)) for (r,c) in self[k].addable_cells()] @@ -1571,11 +1559,9 @@ def degree(self, e): INPUT: - - ``e`` -- an integer `e > 1` - - OUTPUT: + - ``e`` -- integer `e > 1` - A non-negative integer. + OUTPUT: nonnegative integer EXAMPLES:: @@ -1630,9 +1616,7 @@ def prime_degree(self, p): - ``multicharge`` -- an `l`-tuple of integers, where `l` is the :meth:`level` of ``self`` - OUTPUT: - - A non-negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -1666,7 +1650,7 @@ def block(self, e, multicharge): - ``e`` -- the quantum characteristic - - ``multicharge`` -- the multicharge (default `(0,)`) + - ``multicharge`` -- the multicharge (default: `(0,)`) OUTPUT: @@ -1738,12 +1722,10 @@ def defect(self, e, multicharge): - ``e`` -- the quantum characteristic - - ``multicharge`` -- the multicharge (default `(0,)`) + - ``multicharge`` -- the multicharge (default: `(0,)`) - OUTPUT: - - - a non-negative integer, which is the defect of the block - containing the partition tuple ``self`` + OUTPUT: a nonnegative integer, which is the defect of the block + containing the partition tuple ``self`` EXAMPLES:: @@ -1788,9 +1770,9 @@ class PartitionTuples(UniqueRepresentation, Parent): - ``level`` -- the length of the tuple - - ``size`` -- the total number of cells + - ``size`` -- the total number of cells - - ``regular`` -- a positive integer or a tuple of non-negative + - ``regular`` -- positive integer or a tuple of nonnegative integers; if an integer, the highest multiplicity an entry may have in a component plus `1` @@ -1845,7 +1827,7 @@ def __classcall_private__(klass, level=None, size=None, regular=None): raise ValueError('the level must be a positive integer') if size is not None and (not isinstance(size, (int, Integer)) or size < 0): - raise ValueError('the size must be a non-negative integer') + raise ValueError('the size must be a nonnegative integer') if isinstance(regular, (list, tuple)): if level is None: @@ -1856,7 +1838,7 @@ def __classcall_private__(klass, level=None, size=None, regular=None): level, regular)) if regular == 0: raise ValueError("regular must be a positive integer or a tuple " - "of non-negative integers") + "of nonnegative integers") if level is None: if size is None: if regular is None: @@ -1902,15 +1884,13 @@ def __classcall_private__(klass, level=None, size=None, regular=None): def _element_constructor_(self, mu): r""" - Constructs an element of :class:`PartitionTuple`. + Construct an element of :class:`PartitionTuple`. INPUT: - - ``mu`` -- a tuple of partitions - - OUTPUT: + - ``mu`` -- tuple of partitions - - The corresponding :class:`PartitionTuple` object + OUTPUT: the corresponding :class:`PartitionTuple` object TESTS:: @@ -2074,7 +2054,7 @@ class PartitionTuples_all(PartitionTuples): def __init__(self): r""" - Initializes the class. + Initialize the class. EXAMPLES:: @@ -2147,7 +2127,7 @@ class PartitionTuples_level(PartitionTuples): def __init__(self, level, category=None): r""" - Initializes this class. + Initialize this class. EXAMPLES:: @@ -2158,7 +2138,7 @@ def __init__(self, level, category=None): sage: TestSuite( PartitionTuples(level=4) ).run() # needs sage.libs.flint """ if level not in NN: - raise ValueError('level must be a non-negative integer') + raise ValueError('level must be a nonnegative integer') if category is None: category = InfiniteEnumeratedSets() super().__init__(category=category) @@ -2264,7 +2244,7 @@ def __init__(self, size): sage: TestSuite( PartitionTuples(size=6) ).run() # needs sage.libs.flint """ if size not in NN: - raise ValueError('size must be a non-negative integer') + raise ValueError('size must be a nonnegative integer') super().__init__(category=InfiniteEnumeratedSets()) self._size = size @@ -2309,7 +2289,7 @@ def __contains__(self, mu): def __iter__(self): r""" - Iterates through the infinite class of partition tuples of a fixed size. + Iterate through the infinite class of partition tuples of a fixed size. EXAMPLES:: @@ -2358,7 +2338,7 @@ class PartitionTuples_level_size(PartitionTuples): def __init__(self, level, size): r""" - Initializes this class. + Initialize this class. EXAMPLES:: @@ -2366,7 +2346,7 @@ def __init__(self, level, size): sage: TestSuite( PartitionTuples(level=4, size=5) ).run() # needs sage.libs.flint sage.libs.pari """ if not (level in NN and size in NN): - raise ValueError('n and level must be non-negative integers') + raise ValueError('n and level must be nonnegative integers') super().__init__(category=FiniteEnumeratedSets()) self._level = level self._size = size @@ -2414,7 +2394,7 @@ def __contains__(self, mu): def __iter__(self): r""" - Iterates through the finite class of partition tuples of a fixed level + Iterate through the finite class of partition tuples of a fixed level and a fixed size. EXAMPLES:: @@ -2660,8 +2640,8 @@ class RegularPartitionTuples_level(PartitionTuples_level): INPUT: - - ``level`` -- a non-negative Integer; the level - - ``regular`` -- a positive integer or a tuple of non-negative + - ``level`` -- nonnegative integer; the level + - ``regular`` -- positive integer or a tuple of nonnegative integers; if an integer, the highest multiplicity an entry may have in a component plus `1` with `0` representing `\infty`-regular (equivalently, partitions without restrictions) @@ -2720,7 +2700,7 @@ def __init__(self, level, regular): sage: TestSuite(RPT).run() # needs sage.libs.flint """ if level not in NN: - raise ValueError('level must be a non-negative integer') + raise ValueError('level must be a nonnegative integer') if not isinstance(regular, tuple): # This should not happen if called from RegularPartitionTuples regular = (regular,) * level @@ -2729,7 +2709,7 @@ def __init__(self, level, regular): else: category = FiniteEnumeratedSets() if any(r not in NN for r in regular): - raise ValueError('regular must be a tuple of non-negative integers') + raise ValueError('regular must be a tuple of nonnegative integers') if len(regular) != level: raise ValueError("regular must be a tuple with length {}".format(level)) PartitionTuples_level.__init__(self, level, category=category) @@ -2887,7 +2867,7 @@ def __init__(self, size, regular): sage: TestSuite(RPT).run() # needs sage.libs.flint """ if size not in NN: - raise ValueError('size must be a non-negative integer') + raise ValueError('size must be a nonnegative integer') RegularPartitionTuples.__init__(self, regular, category=InfiniteEnumeratedSets()) self._size = size @@ -2966,9 +2946,9 @@ class RegularPartitionTuples_level_size(PartitionTuples_level_size): INPUT: - - ``level`` -- a non-negative Integer; the level - - ``size`` -- a non-negative Integer; the size - - ``regular`` -- a positive integer or a tuple of non-negative + - ``level`` -- nonnegative integer; the level + - ``size`` -- nonnegative integer; the size + - ``regular`` -- positive integer or a tuple of nonnegative integers; if an integer, the highest multiplicity an entry may have in a component plus `1` with `0` representing `\infty`-regular (equivalently, partitions without restrictions) @@ -3017,7 +2997,7 @@ def __init__(self, level, size, regular): sage: TestSuite(RPT).run() # needs sage.libs.flint sage.libs.pari """ if size not in NN: - raise ValueError('size must be a non-negative integer') + raise ValueError('size must be a nonnegative integer') if not (level in ZZ and level > 0): raise ValueError('level must be a positive integer') if not isinstance(regular, tuple): @@ -3026,7 +3006,7 @@ def __init__(self, level, size, regular): if len(regular) != level: raise ValueError(f'regular must be a list with length {level}') if any(i not in NN for i in regular): - raise ValueError('regular must be a list of non-negative integers') + raise ValueError('regular must be a list of nonnegative integers') PartitionTuples_level_size.__init__(self, level, size) self._ell = regular diff --git a/src/sage/combinat/partitions.pyx b/src/sage/combinat/partitions.pyx index e193c7e5723..f453694a90c 100644 --- a/src/sage/combinat/partitions.pyx +++ b/src/sage/combinat/partitions.pyx @@ -100,7 +100,7 @@ cdef inline ZS1_step(list P, int n, int *m, int *h): INPUT: - - ``P`` -- a list of size `n` storing a partition of `n` + - ``P`` -- list of size `n` storing a partition of `n` - ``n`` -- integer; the sum of the elements of the partition stored in ``P`` @@ -207,7 +207,7 @@ def ZS1_next(list P): INPUT: - - ``P`` -- a list encoding a partition of an integer `n` in descending order + - ``P`` -- list encoding a partition of an integer `n` in descending order (i.e., `P_i \geq P_{i+1}`) EXAMPLES:: @@ -245,7 +245,7 @@ def ZS1_next(list P): def ZS1_iterator_nk(int n, int k): r""" - An iterator for the partitions of ``n`` of length at most ``k`` (in the + An iterator for the partitions of `n` of length at most `k` (in the decreasing lexicographic order) which returns lists and not objects of type :class:`~sage.combinat.partition.Partition`. @@ -345,7 +345,7 @@ cdef inline ZS2_step(list P, int n, int *m, int *h): INPUT: - - ``P`` -- a list of size `n` storing a partition of `n` + - ``P`` -- list of size `n` storing a partition of `n` - ``n`` -- integer; the sum of the elements of the partition stored in ``P`` @@ -447,7 +447,7 @@ def ZS2_next(list P): INPUT: - - ``P`` -- a list encoding a partition of an integer `n` in descending order + - ``P`` -- list encoding a partition of an integer `n` in descending order (i.e., `P_i \geq P_{i+1}`) EXAMPLES:: @@ -488,7 +488,7 @@ cdef inline AccelDesc_step(list P, int n, int* m, int* h): INPUT: - - ``P`` -- a list of size `n` storing a partition of `n` + - ``P`` -- list of size `n` storing a partition of `n` - ``n`` -- integer; the sum of the elements of the partition stored in ``P`` @@ -602,7 +602,7 @@ def AccelDesc_next(list P): INPUT: - - ``P`` -- a list encoding a partition of an integer `n` in descending order + - ``P`` -- list encoding a partition of an integer `n` in descending order (i.e., `P_i \geq P_{i+1}`) EXAMPLES:: @@ -702,7 +702,7 @@ def AccelAsc_next(list P): INPUT: - - ``P`` -- a list encoding a partition of an integer `n` in ascending order + - ``P`` -- list encoding a partition of an integer `n` in ascending order (i.e., `P_i \leq P_{i+1}`) EXAMPLES:: diff --git a/src/sage/combinat/path_tableaux/dyck_path.py b/src/sage/combinat/path_tableaux/dyck_path.py index c3c24929e99..232b87673d7 100644 --- a/src/sage/combinat/path_tableaux/dyck_path.py +++ b/src/sage/combinat/path_tableaux/dyck_path.py @@ -45,10 +45,10 @@ class DyckPath(PathTableau): INPUT: - * a sequence of nonnegative integers - * a two row standard skew tableau - * a Dyck word - * a noncrossing perfect matching + - a sequence of nonnegative integers + - a two row standard skew tableau + - a Dyck word + - a noncrossing perfect matching EXAMPLES:: @@ -272,7 +272,7 @@ def is_skew(self): @combinatorial_map(name='to Dyck word') def to_DyckWord(self): r""" - Converts ``self`` to a Dyck word. + Convert ``self`` to a Dyck word. EXAMPLES:: diff --git a/src/sage/combinat/path_tableaux/path_tableau.py b/src/sage/combinat/path_tableaux/path_tableau.py index 9809019208e..9d9177ee355 100644 --- a/src/sage/combinat/path_tableaux/path_tableau.py +++ b/src/sage/combinat/path_tableaux/path_tableau.py @@ -223,8 +223,8 @@ def cactus(self,i,j): INPUT: - - ``i`` -- a positive integer - - ``j`` -- a positive integer weakly greater than ``i`` + - ``i`` -- positive integer + - ``j`` -- positive integer weakly greater than `i` EXAMPLES:: @@ -508,7 +508,7 @@ def __init__(self, T): def _repr_(self): r""" - Return a string representation of ``self`` + Return a string representation of ``self``. TESTS:: @@ -576,7 +576,7 @@ def __ne__(self, other): def _latex_(self): r""" - Return a `\LaTeX` representation of ``self`` + Return a `\LaTeX` representation of ``self``. EXAMPLES:: @@ -603,7 +603,6 @@ def _latex_(self): & & & & & 0 & 1 & \frac{2}{3} & 1 & 1 & 1 & 0\\ & & & & & & 0 & 1 & 3 & 4 & 5 & 1 & 0 \end{array} - """ D = self.diagram m = len(D[-1]) @@ -626,7 +625,7 @@ def __len__(self): def _ascii_art_(self): r""" - Return an ascii art representation of ``self`` + Return an ascii art representation of ``self``. TESTS:: @@ -661,7 +660,7 @@ def _ascii_art_(self): def _unicode_art_(self): r""" - Return a unicode art representation of ``self`` + Return a unicode art representation of ``self``. TESTS:: diff --git a/src/sage/combinat/path_tableaux/semistandard.py b/src/sage/combinat/path_tableaux/semistandard.py index 040710d48f0..368caf54145 100644 --- a/src/sage/combinat/path_tableaux/semistandard.py +++ b/src/sage/combinat/path_tableaux/semistandard.py @@ -97,7 +97,7 @@ class SemistandardPathTableau(PathTableau): r""" - An instance is a sequence of lists. Usually the entries will be non-negative integers + An instance is a sequence of lists. Usually the entries will be nonnegative integers in which case this is the chain of partitions of a (skew) semistandard tableau. In general the entries are elements of an ordered abelian group; each list is weakly decreasing and successive lists are interleaved. @@ -255,7 +255,7 @@ def is_skew(self): def is_integral(self) -> bool: """ - Return ``True`` if all entries are non-negative integers. + Return ``True`` if all entries are nonnegative integers. EXAMPLES:: diff --git a/src/sage/combinat/perfect_matching.py b/src/sage/combinat/perfect_matching.py index aa11a40b7af..6f6fa67787e 100644 --- a/src/sage/combinat/perfect_matching.py +++ b/src/sage/combinat/perfect_matching.py @@ -132,7 +132,7 @@ def __classcall_private__(cls, parts): The function checks that the given list or permutation is a valid perfect matching (i.e. a list of pairs with pairwise disjoint elements or a fix point free involution) and raises - a :class:`ValueError` otherwise:: + a :exc:`ValueError` otherwise:: sage: PerfectMatching([(1, 2, 3), (4, 5)]) Traceback (most recent call last): @@ -265,7 +265,6 @@ def standardization(self): sage: n = PerfectMatching([('c','b'),('d','f'),('e','a')]) sage: n.standardization() [(1, 5), (2, 3), (4, 6)] - """ P = PerfectMatchings(2 * len(self)) return P(SetPartition.standardization(self)) @@ -297,7 +296,7 @@ def loops_iterator(self, other=None): INPUT: - - ``other`` -- a perfect matching of the same set of ``self``. + - ``other`` -- a perfect matching of the same set of ``self`` (if the second argument is empty, the method :meth:`an_element` is called on the parent of the first) @@ -346,7 +345,7 @@ def loops(self, other=None): INPUT: - - ``other`` -- a perfect matching of the same set of ``self``. + - ``other`` -- a perfect matching of the same set of ``self`` (if the second argument is empty, the method :meth:`an_element` is called on the parent of the first) @@ -395,7 +394,7 @@ def loop_type(self, other=None): INPUT: - - ``other`` -- a perfect matching of the same set of ``self``. + - ``other`` -- a perfect matching of the same set of ``self`` (if the second argument is empty, the method :meth:`an_element` is called on the parent of the first) @@ -428,7 +427,7 @@ def number_of_loops(self, other=None): INPUT: - - ``other`` -- a perfect matching of the same set of ``self``. + - ``other`` -- a perfect matching of the same set of ``self`` (if the second argument is empty, the method :meth:`an_element` is called on the parent of the first) @@ -473,9 +472,7 @@ def to_graph(self): r""" Return the graph corresponding to the perfect matching. - OUTPUT: - - The realization of ``self`` as a graph. + OUTPUT: the realization of ``self`` as a graph EXAMPLES:: @@ -497,9 +494,7 @@ def to_noncrossing_set_partition(self): corresponding to the perfect matching if the perfect matching is noncrossing, and otherwise gives an error. - OUTPUT: - - The realization of ``self`` as a noncrossing set partition. + OUTPUT: the realization of ``self`` as a noncrossing set partition EXAMPLES:: diff --git a/src/sage/combinat/permutation.py b/src/sage/combinat/permutation.py index 1ca90eff943..7cf80d0fe92 100644 --- a/src/sage/combinat/permutation.py +++ b/src/sage/combinat/permutation.py @@ -32,110 +32,110 @@ :widths: 30, 70 :delim: | - :meth:`~sage.combinat.permutation.Permutation.left_action_product` | Returns the product of ``self`` with another permutation, in which the other permutation is applied first. - :meth:`~sage.combinat.permutation.Permutation.right_action_product` | Returns the product of ``self`` with another permutation, in which ``self`` is applied first. - :meth:`~sage.combinat.permutation.Permutation.size` | Returns the size of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.cycle_string` | Returns the disjoint-cycles representation of ``self`` as string. - :meth:`~sage.combinat.permutation.Permutation.next` | Returns the permutation that follows ``self`` in lexicographic order (in the same symmetric group as ``self``). - :meth:`~sage.combinat.permutation.Permutation.prev` | Returns the permutation that comes directly before ``self`` in lexicographic order (in the same symmetric group as ``self``). - :meth:`~sage.combinat.permutation.Permutation.to_tableau_by_shape` | Returns a tableau of shape ``shape`` with the entries in ``self``. - :meth:`~sage.combinat.permutation.Permutation.to_cycles` | Returns the permutation ``self`` as a list of disjoint cycles. + :meth:`~sage.combinat.permutation.Permutation.left_action_product` | Return the product of ``self`` with another permutation, in which the other permutation is applied first. + :meth:`~sage.combinat.permutation.Permutation.right_action_product` | Return the product of ``self`` with another permutation, in which ``self`` is applied first. + :meth:`~sage.combinat.permutation.Permutation.size` | Return the size of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.cycle_string` | Return the disjoint-cycles representation of ``self`` as string. + :meth:`~sage.combinat.permutation.Permutation.next` | Return the permutation that follows ``self`` in lexicographic order (in the same symmetric group as ``self``). + :meth:`~sage.combinat.permutation.Permutation.prev` | Return the permutation that comes directly before ``self`` in lexicographic order (in the same symmetric group as ``self``). + :meth:`~sage.combinat.permutation.Permutation.to_tableau_by_shape` | Return a tableau of shape ``shape`` with the entries in ``self``. + :meth:`~sage.combinat.permutation.Permutation.to_cycles` | Return the permutation ``self`` as a list of disjoint cycles. :meth:`~sage.combinat.permutation.Permutation.forget_cycles` | Return ``self`` under the forget cycle map. - :meth:`~sage.combinat.permutation.Permutation.to_permutation_group_element` | Returns a ``PermutationGroupElement`` equal to ``self``. - :meth:`~sage.combinat.permutation.Permutation.signature` | Returns the signature of the permutation ``sef``. - :meth:`~sage.combinat.permutation.Permutation.is_even` | Returns ``True`` if the permutation ``self`` is even, and ``False`` otherwise. - :meth:`~sage.combinat.permutation.Permutation.to_matrix` | Returns a matrix representing the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.rank` | Returns the rank of ``self`` in lexicographic ordering (on the symmetric group containing ``self``). - :meth:`~sage.combinat.permutation.Permutation.to_inversion_vector` | Returns the inversion vector of a permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.inversions` | Returns a list of the inversions of permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.stack_sort` | Returns the permutation obtained by sorting ``self`` through one stack. + :meth:`~sage.combinat.permutation.Permutation.to_permutation_group_element` | Return a ``PermutationGroupElement`` equal to ``self``. + :meth:`~sage.combinat.permutation.Permutation.signature` | Return the signature of the permutation ``sef``. + :meth:`~sage.combinat.permutation.Permutation.is_even` | Return ``True`` if the permutation ``self`` is even, and ``False`` otherwise. + :meth:`~sage.combinat.permutation.Permutation.to_matrix` | Return a matrix representing the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.rank` | Return the rank of ``self`` in lexicographic ordering (on the symmetric group containing ``self``). + :meth:`~sage.combinat.permutation.Permutation.to_inversion_vector` | Return the inversion vector of a permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.inversions` | Return a list of the inversions of permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.stack_sort` | Return the permutation obtained by sorting ``self`` through one stack. :meth:`~sage.combinat.permutation.Permutation.to_digraph` | Return a digraph representation of ``self``. - :meth:`~sage.combinat.permutation.Permutation.show` | Displays the permutation as a drawing. - :meth:`~sage.combinat.permutation.Permutation.number_of_inversions` | Returns the number of inversions in the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.noninversions` | Returns the ``k``-noninversions in the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.number_of_noninversions` | Returns the number of ``k``-noninversions in the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.length` | Returns the Coxeter length of a permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.inverse` | Returns the inverse of a permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.ishift` | Returns the ``i``-shift of ``self``. - :meth:`~sage.combinat.permutation.Permutation.iswitch` | Returns the ``i``-switch of ``self``. - :meth:`~sage.combinat.permutation.Permutation.runs` | Returns a list of the runs in the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.longest_increasing_subsequence_length` | Returns the length of the longest increasing subsequences of ``self``. - :meth:`~sage.combinat.permutation.Permutation.longest_increasing_subsequences` | Returns the list of the longest increasing subsequences of ``self``. - :meth:`~sage.combinat.permutation.Permutation.longest_increasing_subsequences_number` | Returns the number of longest increasing subsequences - :meth:`~sage.combinat.permutation.Permutation.cycle_type` | Returns the cycle type of ``self`` as a partition of ``len(self)``. - :meth:`~sage.combinat.permutation.Permutation.foata_bijection` | Returns the image of the permutation ``self`` under the Foata bijection `\phi`. - :meth:`~sage.combinat.permutation.Permutation.foata_bijection_inverse` | Returns the image of the permutation ``self`` under the inverse of the Foata bijection `\phi`. - :meth:`~sage.combinat.permutation.Permutation.fundamental_transformation` | Returns the image of the permutation ``self`` under the Renyi-Foata-Schuetzenberger fundamental transformation. - :meth:`~sage.combinat.permutation.Permutation.fundamental_transformation_inverse` | Returns the image of the permutation ``self`` under the inverse of the Renyi-Foata-Schuetzenberger fundamental transformation. + :meth:`~sage.combinat.permutation.Permutation.show` | Display the permutation as a drawing. + :meth:`~sage.combinat.permutation.Permutation.number_of_inversions` | Return the number of inversions in the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.noninversions` | Return the ``k``-noninversions in the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.number_of_noninversions` | Return the number of ``k``-noninversions in the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.length` | Return the Coxeter length of a permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.inverse` | Return the inverse of a permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.ishift` | Return the ``i``-shift of ``self``. + :meth:`~sage.combinat.permutation.Permutation.iswitch` | Return the ``i``-switch of ``self``. + :meth:`~sage.combinat.permutation.Permutation.runs` | Return a list of the runs in the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.longest_increasing_subsequence_length` | Return the length of the longest increasing subsequences of ``self``. + :meth:`~sage.combinat.permutation.Permutation.longest_increasing_subsequences` | Return the list of the longest increasing subsequences of ``self``. + :meth:`~sage.combinat.permutation.Permutation.longest_increasing_subsequences_number` | Return the number of longest increasing subsequences + :meth:`~sage.combinat.permutation.Permutation.cycle_type` | Return the cycle type of ``self`` as a partition of ``len(self)``. + :meth:`~sage.combinat.permutation.Permutation.foata_bijection` | Return the image of the permutation ``self`` under the Foata bijection `\phi`. + :meth:`~sage.combinat.permutation.Permutation.foata_bijection_inverse` | Return the image of the permutation ``self`` under the inverse of the Foata bijection `\phi`. + :meth:`~sage.combinat.permutation.Permutation.fundamental_transformation` | Return the image of the permutation ``self`` under the Renyi-Foata-Schuetzenberger fundamental transformation. + :meth:`~sage.combinat.permutation.Permutation.fundamental_transformation_inverse` | Return the image of the permutation ``self`` under the inverse of the Renyi-Foata-Schuetzenberger fundamental transformation. :meth:`~sage.combinat.permutation.Permutation.destandardize` | Return destandardization of ``self`` with respect to ``weight`` and ``ordered_alphabet``. - :meth:`~sage.combinat.permutation.Permutation.to_lehmer_code` | Returns the Lehmer code of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.to_lehmer_cocode` | Returns the Lehmer cocode of ``self``. - :meth:`~sage.combinat.permutation.Permutation.reduced_word` | Returns the reduced word of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.reduced_words` | Returns a list of the reduced words of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.to_lehmer_code` | Return the Lehmer code of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.to_lehmer_cocode` | Return the Lehmer cocode of ``self``. + :meth:`~sage.combinat.permutation.Permutation.reduced_word` | Return the reduced word of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.reduced_words` | Return a list of the reduced words of the permutation ``self``. :meth:`~sage.combinat.permutation.Permutation.reduced_words_iterator` | An iterator for the reduced words of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.reduced_word_lexmin` | Returns a lexicographically minimal reduced word of a permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.fixed_points` | Returns a list of the fixed points of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.is_derangement` | Returns ``True`` if the permutation ``self`` is a derangement, and ``False`` otherwise. - :meth:`~sage.combinat.permutation.Permutation.is_simple` | Returns ``True`` if the permutation ``self`` is simple, and ``False`` otherwise. - :meth:`~sage.combinat.permutation.Permutation.number_of_fixed_points` | Returns the number of fixed points of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.recoils` | Returns the list of the positions of the recoils of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.number_of_recoils` | Returns the number of recoils of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.recoils_composition` | Returns the composition corresponding to the recoils of ``self``. - :meth:`~sage.combinat.permutation.Permutation.descents` | Returns the list of the descents of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.idescents` | Returns a list of the idescents of ``self``. - :meth:`~sage.combinat.permutation.Permutation.idescents_signature` | Returns the list obtained by mapping each position in ``self`` to `-1` if it is an idescent and `1` if it is not an idescent. - :meth:`~sage.combinat.permutation.Permutation.number_of_descents` | Returns the number of descents of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.number_of_idescents` | Returns the number of idescents of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.descents_composition` | Returns the composition corresponding to the descents of ``self``. - :meth:`~sage.combinat.permutation.Permutation.descent_polynomial` | Returns the descent polynomial of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.major_index` | Returns the major index of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.imajor_index` | Returns the inverse major index of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.to_major_code` | Returns the major code of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.peaks` | Returns a list of the peaks of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.number_of_peaks` | Returns the number of peaks of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.saliances` | Returns a list of the saliances of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.number_of_saliances` | Returns the number of saliances of the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.bruhat_lequal` | Returns ``True`` if self is less or equal to ``p2`` in the Bruhat order. - :meth:`~sage.combinat.permutation.Permutation.weak_excedences` | Returns all the numbers ``self[i]`` such that ``self[i] >= i+1``. - :meth:`~sage.combinat.permutation.Permutation.bruhat_inversions` | Returns the list of inversions of ``self`` such that the application of this inversion to ``self`` decrements its number of inversions. - :meth:`~sage.combinat.permutation.Permutation.bruhat_inversions_iterator` | Returns an iterator over Bruhat inversions of ``self``. - :meth:`~sage.combinat.permutation.Permutation.bruhat_succ` | Returns a list of the permutations covering ``self`` in the Bruhat order. + :meth:`~sage.combinat.permutation.Permutation.reduced_word_lexmin` | Return a lexicographically minimal reduced word of a permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.fixed_points` | Return a list of the fixed points of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.is_derangement` | Return ``True`` if the permutation ``self`` is a derangement, and ``False`` otherwise. + :meth:`~sage.combinat.permutation.Permutation.is_simple` | Return ``True`` if the permutation ``self`` is simple, and ``False`` otherwise. + :meth:`~sage.combinat.permutation.Permutation.number_of_fixed_points` | Return the number of fixed points of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.recoils` | Return the list of the positions of the recoils of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.number_of_recoils` | Return the number of recoils of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.recoils_composition` | Return the composition corresponding to the recoils of ``self``. + :meth:`~sage.combinat.permutation.Permutation.descents` | Return the list of the descents of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.idescents` | Return a list of the idescents of ``self``. + :meth:`~sage.combinat.permutation.Permutation.idescents_signature` | Return the list obtained by mapping each position in ``self`` to `-1` if it is an idescent and `1` if it is not an idescent. + :meth:`~sage.combinat.permutation.Permutation.number_of_descents` | Return the number of descents of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.number_of_idescents` | Return the number of idescents of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.descents_composition` | Return the composition corresponding to the descents of ``self``. + :meth:`~sage.combinat.permutation.Permutation.descent_polynomial` | Return the descent polynomial of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.major_index` | Return the major index of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.imajor_index` | Return the inverse major index of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.to_major_code` | Return the major code of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.peaks` | Return a list of the peaks of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.number_of_peaks` | Return the number of peaks of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.saliances` | Return a list of the saliances of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.number_of_saliances` | Return the number of saliances of the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.bruhat_lequal` | Return ``True`` if ``self`` is less or equal to ``p2`` in the Bruhat order. + :meth:`~sage.combinat.permutation.Permutation.weak_excedences` | Return all the numbers ``self[i]`` such that ``self[i] >= i+1``. + :meth:`~sage.combinat.permutation.Permutation.bruhat_inversions` | Return the list of inversions of ``self`` such that the application of this inversion to ``self`` decrements its number of inversions. + :meth:`~sage.combinat.permutation.Permutation.bruhat_inversions_iterator` | Return an iterator over Bruhat inversions of ``self``. + :meth:`~sage.combinat.permutation.Permutation.bruhat_succ` | Return a list of the permutations covering ``self`` in the Bruhat order. :meth:`~sage.combinat.permutation.Permutation.bruhat_succ_iterator` | An iterator for the permutations covering ``self`` in the Bruhat order. - :meth:`~sage.combinat.permutation.Permutation.bruhat_pred` | Returns a list of the permutations covered by ``self`` in the Bruhat order. + :meth:`~sage.combinat.permutation.Permutation.bruhat_pred` | Return a list of the permutations covered by ``self`` in the Bruhat order. :meth:`~sage.combinat.permutation.Permutation.bruhat_pred_iterator` | An iterator for the permutations covered by ``self`` in the Bruhat order. - :meth:`~sage.combinat.permutation.Permutation.bruhat_smaller` | Returns the combinatorial class of permutations smaller than or equal to ``self`` in the Bruhat order. - :meth:`~sage.combinat.permutation.Permutation.bruhat_greater` | Returns the combinatorial class of permutations greater than or equal to ``self`` in the Bruhat order. - :meth:`~sage.combinat.permutation.Permutation.permutohedron_lequal` | Returns ``True`` if ``self`` is less or equal to ``p2`` in the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.permutohedron_succ` | Returns a list of the permutations covering ``self`` in the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.permutohedron_pred` | Returns a list of the permutations covered by ``self`` in the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.permutohedron_smaller` | Returns a list of permutations smaller than or equal to ``self`` in the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.permutohedron_greater` | Returns a list of permutations greater than or equal to ``self`` in the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.right_permutohedron_interval_iterator` | Returns an iterator over permutations in an interval of the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.right_permutohedron_interval` | Returns a list of permutations in an interval of the permutohedron order. - :meth:`~sage.combinat.permutation.Permutation.has_pattern` | Tests whether the permutation ``self`` matches the pattern. - :meth:`~sage.combinat.permutation.Permutation.avoids` | Tests whether the permutation ``self`` avoids the pattern. - :meth:`~sage.combinat.permutation.Permutation.pattern_positions` | Returns the list of positions where the pattern ``patt`` appears in ``self``. - :meth:`~sage.combinat.permutation.Permutation.reverse` | Returns the permutation obtained by reversing the 1-line notation of ``self``. - :meth:`~sage.combinat.permutation.Permutation.complement` | Returns the complement of the permutation which is obtained by replacing each value `x` in the 1-line notation of ``self`` with `n - x + 1`. - :meth:`~sage.combinat.permutation.Permutation.permutation_poset` | Returns the permutation poset of ``self``. - :meth:`~sage.combinat.permutation.Permutation.dict` | Returns a dictionary corresponding to the permutation ``self``. - :meth:`~sage.combinat.permutation.Permutation.action` | Returns the action of the permutation ``self`` on a list. - :meth:`~sage.combinat.permutation.Permutation.robinson_schensted` | Returns the pair of standard tableaux obtained by running the Robinson-Schensted Algorithm on ``self``. - :meth:`~sage.combinat.permutation.Permutation.left_tableau` | Returns the left standard tableau after performing the RSK algorithm. - :meth:`~sage.combinat.permutation.Permutation.right_tableau` | Returns the right standard tableau after performing the RSK algorithm. - :meth:`~sage.combinat.permutation.Permutation.increasing_tree` | Returns the increasing tree of ``self``. - :meth:`~sage.combinat.permutation.Permutation.increasing_tree_shape` | Returns the shape of the increasing tree of ``self``. - :meth:`~sage.combinat.permutation.Permutation.binary_search_tree` | Returns the binary search tree of ``self``. - :meth:`~sage.combinat.permutation.Permutation.sylvester_class` | Iterates over the equivalence class of ``self`` under sylvester congruence - :meth:`~sage.combinat.permutation.Permutation.RS_partition` | Returns the shape of the tableaux obtained by the RSK algorithm. - :meth:`~sage.combinat.permutation.Permutation.remove_extra_fixed_points` | Returns the permutation obtained by removing any fixed points at the end of ``self``. - :meth:`~sage.combinat.permutation.Permutation.retract_plain` | Returns the plain retract of ``self`` to a smaller symmetric group `S_m`. - :meth:`~sage.combinat.permutation.Permutation.retract_direct_product` | Returns the direct-product retract of ``self`` to a smaller symmetric group `S_m`. - :meth:`~sage.combinat.permutation.Permutation.retract_okounkov_vershik` | Returns the Okounkov-Vershik retract of ``self`` to a smaller symmetric group `S_m`. - :meth:`~sage.combinat.permutation.Permutation.hyperoctahedral_double_coset_type` | Returns the coset-type of ``self`` as a partition. - :meth:`~sage.combinat.permutation.Permutation.binary_search_tree_shape` | Returns the shape of the binary search tree of ``self`` (a non labelled binary tree). - :meth:`~sage.combinat.permutation.Permutation.shifted_concatenation` | Returns the right (or left) shifted concatenation of ``self`` with a permutation ``other``. - :meth:`~sage.combinat.permutation.Permutation.shifted_shuffle` | Returns the shifted shuffle of ``self`` with a permutation ``other``. + :meth:`~sage.combinat.permutation.Permutation.bruhat_smaller` | Return the combinatorial class of permutations smaller than or equal to ``self`` in the Bruhat order. + :meth:`~sage.combinat.permutation.Permutation.bruhat_greater` | Return the combinatorial class of permutations greater than or equal to ``self`` in the Bruhat order. + :meth:`~sage.combinat.permutation.Permutation.permutohedron_lequal` | Return ``True`` if ``self`` is less or equal to ``p2`` in the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.permutohedron_succ` | Return a list of the permutations covering ``self`` in the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.permutohedron_pred` | Return a list of the permutations covered by ``self`` in the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.permutohedron_smaller` | Return a list of permutations smaller than or equal to ``self`` in the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.permutohedron_greater` | Return a list of permutations greater than or equal to ``self`` in the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.right_permutohedron_interval_iterator` | Return an iterator over permutations in an interval of the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.right_permutohedron_interval` | Return a list of permutations in an interval of the permutohedron order. + :meth:`~sage.combinat.permutation.Permutation.has_pattern` | Test whether the permutation ``self`` matches the pattern. + :meth:`~sage.combinat.permutation.Permutation.avoids` | Test whether the permutation ``self`` avoids the pattern. + :meth:`~sage.combinat.permutation.Permutation.pattern_positions` | Return the list of positions where the pattern ``patt`` appears in ``self``. + :meth:`~sage.combinat.permutation.Permutation.reverse` | Return the permutation obtained by reversing the 1-line notation of ``self``. + :meth:`~sage.combinat.permutation.Permutation.complement` | Return the complement of the permutation which is obtained by replacing each value `x` in the 1-line notation of ``self`` with `n - x + 1`. + :meth:`~sage.combinat.permutation.Permutation.permutation_poset` | Return the permutation poset of ``self``. + :meth:`~sage.combinat.permutation.Permutation.dict` | Return a dictionary corresponding to the permutation ``self``. + :meth:`~sage.combinat.permutation.Permutation.action` | Return the action of the permutation ``self`` on a list. + :meth:`~sage.combinat.permutation.Permutation.robinson_schensted` | Return the pair of standard tableaux obtained by running the Robinson-Schensted Algorithm on ``self``. + :meth:`~sage.combinat.permutation.Permutation.left_tableau` | Return the left standard tableau after performing the RSK algorithm. + :meth:`~sage.combinat.permutation.Permutation.right_tableau` | Return the right standard tableau after performing the RSK algorithm. + :meth:`~sage.combinat.permutation.Permutation.increasing_tree` | Return the increasing tree of ``self``. + :meth:`~sage.combinat.permutation.Permutation.increasing_tree_shape` | Return the shape of the increasing tree of ``self``. + :meth:`~sage.combinat.permutation.Permutation.binary_search_tree` | Return the binary search tree of ``self``. + :meth:`~sage.combinat.permutation.Permutation.sylvester_class` | Iterate over the equivalence class of ``self`` under sylvester congruence + :meth:`~sage.combinat.permutation.Permutation.RS_partition` | Return the shape of the tableaux obtained by the RSK algorithm. + :meth:`~sage.combinat.permutation.Permutation.remove_extra_fixed_points` | Return the permutation obtained by removing any fixed points at the end of ``self``. + :meth:`~sage.combinat.permutation.Permutation.retract_plain` | Return the plain retract of ``self`` to a smaller symmetric group `S_m`. + :meth:`~sage.combinat.permutation.Permutation.retract_direct_product` | Return the direct-product retract of ``self`` to a smaller symmetric group `S_m`. + :meth:`~sage.combinat.permutation.Permutation.retract_okounkov_vershik` | Return the Okounkov-Vershik retract of ``self`` to a smaller symmetric group `S_m`. + :meth:`~sage.combinat.permutation.Permutation.hyperoctahedral_double_coset_type` | Return the coset-type of ``self`` as a partition. + :meth:`~sage.combinat.permutation.Permutation.binary_search_tree_shape` | Return the shape of the binary search tree of ``self`` (a non labelled binary tree). + :meth:`~sage.combinat.permutation.Permutation.shifted_concatenation` | Return the right (or left) shifted concatenation of ``self`` with a permutation ``other``. + :meth:`~sage.combinat.permutation.Permutation.shifted_shuffle` | Return the shifted shuffle of ``self`` with a permutation ``other``. **Other classes defined in this file** @@ -182,21 +182,21 @@ :widths: 30, 70 :delim: | - :meth:`from_major_code` | Returns the permutation corresponding to major code ``mc``. - :meth:`from_permutation_group_element` | Returns a Permutation give a ``PermutationGroupElement`` ``pge``. - :meth:`from_rank` | Returns the permutation with the specified lexicographic rank. - :meth:`from_inversion_vector` | Returns the permutation corresponding to inversion vector ``iv``. - :meth:`from_cycles` | Returns the permutation with given disjoint-cycle representation ``cycles``. - :meth:`from_lehmer_code` | Returns the permutation with Lehmer code ``lehmer``. - :meth:`from_reduced_word` | Returns the permutation corresponding to the reduced word ``rw``. - :meth:`bistochastic_as_sum_of_permutations` | Returns a given bistochastic matrix as a nonnegative linear combination of permutations. - :meth:`bounded_affine_permutation` | Returns a partial permutation representing the bounded affine permutation of a matrix. - :meth:`descents_composition_list` | Returns a list of all the permutations in a given descent class (i. e., having a given descents composition). - :meth:`descents_composition_first` | Returns the smallest element of a descent class. - :meth:`descents_composition_last` | Returns the largest element of a descent class. - :meth:`bruhat_lequal` | Returns ``True`` if ``p1`` is less or equal to ``p2`` in the Bruhat order. - :meth:`permutohedron_lequal` | Returns ``True`` if ``p1`` is less or equal to ``p2`` in the permutohedron order. - :meth:`to_standard` | Returns a standard permutation corresponding to the permutation ``self``. + :meth:`from_major_code` | Return the permutation corresponding to major code ``mc``. + :meth:`from_permutation_group_element` | Return a Permutation give a ``PermutationGroupElement`` ``pge``. + :meth:`from_rank` | Return the permutation with the specified lexicographic rank. + :meth:`from_inversion_vector` | Return the permutation corresponding to inversion vector ``iv``. + :meth:`from_cycles` | Return the permutation with given disjoint-cycle representation ``cycles``. + :meth:`from_lehmer_code` | Return the permutation with Lehmer code ``lehmer``. + :meth:`from_reduced_word` | Return the permutation corresponding to the reduced word ``rw``. + :meth:`bistochastic_as_sum_of_permutations` | Return a given bistochastic matrix as a nonnegative linear combination of permutations. + :meth:`bounded_affine_permutation` | Return a partial permutation representing the bounded affine permutation of a matrix. + :meth:`descents_composition_list` | Return a list of all the permutations in a given descent class (i. e., having a given descents composition). + :meth:`descents_composition_first` | Return the smallest element of a descent class. + :meth:`descents_composition_last` | Return the largest element of a descent class. + :meth:`bruhat_lequal` | Return ``True`` if ``p1`` is less or equal to ``p2`` in the Bruhat order. + :meth:`permutohedron_lequal` | Return ``True`` if ``p1`` is less or equal to ``p2`` in the permutohedron order. + :meth:`to_standard` | Return a standard permutation corresponding to the permutation ``self``. AUTHORS: @@ -290,7 +290,7 @@ class Permutation(CombinatorialElement): INPUT: - - ``l`` -- Can be any one of the following: + - ``l`` -- can be any one of the following: - an instance of :class:`Permutation`, @@ -310,15 +310,14 @@ class Permutation(CombinatorialElement): Robinson-Schensted algorithm. - ``check`` -- boolean (default: ``True``); whether to check that input is - correct. Slows the function down, but ensures that nothing bad happens. - This is set to ``True`` by default. + correct; slows the function down, but ensures that nothing bad happens - - ``algorithm`` -- string (default: ``lex``); the algorithm used to generate - the permutations. Supported algorithms are: + - ``algorithm`` -- string (default: ``'lex'``); the algorithm used to + generate the permutations. Supported algorithms are: - - ``lex``: lexicographic order generation, this is the default algorithm. + - ``'lex'``: lexicographic order generation, this is the default algorithm - - ``sjt``: Steinhaus-Johnson-Trotter algorithm to generate permutations + - ``'sjt'``: Steinhaus-Johnson-Trotter algorithm to generate permutations using only transposition of two elements in the list. It is highly recommended to set ``check=True`` (default value). @@ -538,19 +537,19 @@ def __init__(self, parent, l, algorithm='lex', sjt=None, check=True): INPUT: - - ``l`` -- a list of ``int`` variables + - ``l`` -- list of ``int`` variables - ``check`` -- boolean (default: ``True``); whether to check that input is correct. Slows the function down, but ensures that nothing bad happens. - - ``algorithm`` -- string (default: ``lex``); the algorithm used to + - ``algorithm`` -- string (default: ``'lex'``); the algorithm used to generate the permutations. Supported algorithms are: - - ``lex``: lexicographic order generation, this is the default - algorithm. + - ``'lex'``: lexicographic order generation, this is the default + algorithm - - ``sjt``: Steinhaus-Johnson-Trotter algorithm to generate + - ``'sjt'``: Steinhaus-Johnson-Trotter algorithm to generate permutations using only transposition of two elements in the list. It is highly recommended to set ``check=True`` (default value). @@ -1840,7 +1839,7 @@ def to_digraph(self) -> DiGraph: return DiGraph([self, enumerate(self, start=1)], format='vertices_and_edges', loops=True) - def show(self, representation="cycles", orientation="landscape", **args): + def show(self, representation='cycles', orientation='landscape', **args): r""" Display the permutation as a drawing. @@ -1848,33 +1847,33 @@ def show(self, representation="cycles", orientation="landscape", **args): - ``representation`` -- different kinds of drawings are available - - ``"cycles"`` (default) -- the permutation is displayed as a + - ``'cycles'`` -- default; the permutation is displayed as a collection of directed cycles - - ``"braid"`` -- the permutation is displayed as segments linking - each element `1, ..., n` to its image on a parallel line. + - ``'braid'`` -- the permutation is displayed as segments linking + each element `1, ..., n` to its image on a parallel line When using this drawing, it is also possible to display the permutation horizontally (``orientation = "landscape"``, default option) or vertically (``orientation = "portrait"``). - - ``"chord-diagram"`` -- the permutation is displayed as a directed - graph, all of its vertices being located on a circle. + - ``'chord-diagram'`` -- the permutation is displayed as a directed + graph, all of its vertices being located on a circle All additional arguments are forwarded to the ``show`` subcalls. EXAMPLES:: sage: P20 = Permutations(20) - sage: P20.random_element().show(representation="cycles") # needs sage.graphs sage.plot - sage: P20.random_element().show(representation="chord-diagram") # needs sage.graphs sage.plot - sage: P20.random_element().show(representation="braid") # needs sage.plot - sage: P20.random_element().show(representation="braid", # needs sage.plot + sage: P20.random_element().show(representation='cycles') # needs sage.graphs sage.plot + sage: P20.random_element().show(representation='chord-diagram') # needs sage.graphs sage.plot + sage: P20.random_element().show(representation='braid') # needs sage.plot + sage: P20.random_element().show(representation='braid', # needs sage.plot ....: orientation='portrait') TESTS:: - sage: P20.random_element().show(representation="modern_art") + sage: P20.random_element().show(representation='modern_art') Traceback (most recent call last): ... ValueError: The value of 'representation' must be equal to 'cycles', 'chord-diagram' or 'braid' @@ -1885,7 +1884,7 @@ def show(self, representation="cycles", orientation="landscape", **args): if representation == "cycles": d.show(**args) else: - d.show(layout="circular", **args) + d.show(layout='circular', **args) elif representation == "braid": from sage.plot.line import line @@ -2269,12 +2268,10 @@ def runs(self, as_tuple=False): INPUT: - - ``as_tuple`` -- boolean (default: ``False``) choice of + - ``as_tuple`` -- boolean (default: ``False``); choice of output format - OUTPUT: - - a list of lists or a tuple of tuples + OUTPUT: list of lists or a tuple of tuples REFERENCES: @@ -2330,12 +2327,10 @@ def decreasing_runs(self, as_tuple=False): INPUT: - - ``as_tuple`` -- boolean (default: ``False``) choice of output + - ``as_tuple`` -- boolean (default: ``False``); choice of output format - OUTPUT: - - a list of lists or a tuple of tuples + OUTPUT: list of lists or a tuple of tuples .. SEEALSO:: @@ -2877,15 +2872,16 @@ def fundamental_transformation_inverse(self): def destandardize(self, weight, ordered_alphabet=None): r""" - Return destandardization of ``self`` with respect to ``weight`` and ``ordered_alphabet``. + Return destandardization of ``self`` with respect to ``weight`` and + ``ordered_alphabet``. INPUT: - - ``weight`` -- list or tuple of nonnegative integers that sum to `n` if ``self`` - is a permutation in `S_n`. + - ``weight`` -- list or tuple of nonnegative integers that sum to `n` + if ``self`` is a permutation in `S_n` - - ``ordered_alphabet`` -- (default: ``None``) a list or tuple specifying the ordered alphabet the - destandardized word is over + - ``ordered_alphabet`` -- (default: ``None``) a list or tuple + specifying the ordered alphabet the destandardized word is over OUTPUT: word over the ``ordered_alphabet`` which standardizes to ``self`` @@ -2970,7 +2966,6 @@ def to_lehmer_code(self) -> list: sage: all(from_lehmer_code(p.to_lehmer_code()) == p ....: for p in sample) True - """ l = len(self._list) # choose the best implementations @@ -3066,7 +3061,6 @@ def reduced_words_iterator(self): sage: next(Permutation([5,2,3,4,1]).reduced_words_iterator()) [1, 2, 3, 4, 3, 2, 1] - """ def aux(p): is_identity = True @@ -3384,17 +3378,17 @@ def descents(self, final_descent=False, side='right', positive=False, INPUT: - - ``final_descent`` -- boolean (default ``False``); + - ``final_descent`` -- boolean (default: ``False``); if ``True``, the last position of a non-empty permutation is also considered as a descent - ``side`` -- ``'right'`` (default) or ``'left'``; if ``'left'``, return the descents of the inverse permutation - - ``positive`` -- boolean (default ``False``); + - ``positive`` -- boolean (default: ``False``); if ``True``, return the positions that are not descents - - ``from_zero`` -- boolean (default ``False``); + - ``from_zero`` -- boolean (default: ``False``); if ``True``, return the positions starting from `0` - ``index_set`` -- list (default: ``[1, ..., n-1]`` where ``self`` @@ -3460,12 +3454,12 @@ def idescents(self, final_descent=False, from_zero=False): INPUT: - - ``final_descent`` -- boolean (default ``False``); - if ``True``, the last position of a non-empty - permutation is also considered as a descent + - ``final_descent`` -- boolean (default: ``False``); if ``True``, the + last position of a non-empty permutation is also considered as a + descent - - ``from_zero`` -- optional boolean (default ``False``); - if ``False``, return the positions starting from `1` + - ``from_zero`` -- boolean (default: ``False``); if ``False``, return + the positions starting from `1` EXAMPLES:: @@ -4106,7 +4100,7 @@ def bruhat_greater(self): # Permutohedron Order # ######################## - def permutohedron_lequal(self, p2, side="right") -> bool: + def permutohedron_lequal(self, p2, side='right') -> bool: r""" Return ``True`` if ``self`` is less or equal to ``p2`` in the permutohedron order. @@ -4184,7 +4178,7 @@ def permutohedron_lequal(self, p2, side="right") -> bool: sage: sorted( [len([b for b in Permutations(3) if a.permutohedron_lequal(b)]) ....: for a in Permutations(3)] ) [1, 2, 2, 3, 3, 6] - sage: sorted( [len([b for b in Permutations(3) if a.permutohedron_lequal(b, side="left")]) + sage: sorted( [len([b for b in Permutations(3) if a.permutohedron_lequal(b, side='left')]) ....: for a in Permutations(3)] ) [1, 2, 2, 3, 3, 6] @@ -4205,7 +4199,7 @@ def permutohedron_lequal(self, p2, side="right") -> bool: return prod.number_of_inversions() == l2 - l1 - def permutohedron_succ(self, side="right"): + def permutohedron_succ(self, side='right'): r""" Return a list of the permutations strictly greater than ``self`` in the permutohedron order such that there is no permutation @@ -4246,7 +4240,7 @@ def permutohedron_succ(self, side="right"): succ.append(P(pp)) return succ - def permutohedron_pred(self, side="right") -> list: + def permutohedron_pred(self, side='right') -> list: r""" Return a list of the permutations strictly smaller than ``self`` in the permutohedron order such that there is no permutation @@ -4286,7 +4280,7 @@ def permutohedron_pred(self, side="right") -> list: pred.append(P(pp)) return pred - def permutohedron_smaller(self, side="right") -> list: + def permutohedron_smaller(self, side='right') -> list: r""" Return a list of permutations smaller than or equal to ``self`` in the permutohedron order. @@ -4324,7 +4318,7 @@ def permutohedron_smaller(self, side="right") -> list: """ return transitive_ideal(lambda x: x.permutohedron_pred(side), self) - def permutohedron_greater(self, side="right") -> list: + def permutohedron_greater(self, side='right') -> list: r""" Return a list of permutations greater than or equal to ``self`` in the permutohedron order. @@ -4413,7 +4407,7 @@ def right_permutohedron_interval(self, other): P = Permutations() return [P(p) for p in self.right_permutohedron_interval_iterator(other)] - def permutohedron_join(self, other, side="right") -> Permutation: + def permutohedron_join(self, other, side='right') -> Permutation: r""" Return the join of the permutations ``self`` and ``other`` in the right permutohedron order (or, if ``side`` is set to @@ -4509,10 +4503,10 @@ def permutohedron_join(self, other, side="right") -> Permutation: sage: p = Permutation([3,1,2]) sage: q = Permutation([1,3,2]) - sage: p.permutohedron_join(q, side="left") + sage: p.permutohedron_join(q, side='left') [3, 2, 1] sage: r = Permutation([2,1,3]) - sage: r.permutohedron_join(p, side="left") + sage: r.permutohedron_join(p, side='left') [3, 1, 2] """ if side == "left": @@ -4533,7 +4527,7 @@ def permutohedron_join(self, other, side="right") -> Permutation: xs.append(i) return Permutations(n)(xs) - def permutohedron_meet(self, other, side="right") -> Permutation: + def permutohedron_meet(self, other, side='right') -> Permutation: r""" Return the meet of the permutations ``self`` and ``other`` in the right permutohedron order (or, if ``side`` is set to @@ -4625,10 +4619,10 @@ def permutohedron_meet(self, other, side="right") -> Permutation: sage: p = Permutation([3,1,2]) sage: q = Permutation([1,3,2]) - sage: p.permutohedron_meet(q, side="left") + sage: p.permutohedron_meet(q, side='left') [1, 2, 3] sage: r = Permutation([2,1,3]) - sage: r.permutohedron_meet(p, side="left") + sage: r.permutohedron_meet(p, side='left') [2, 1, 3] """ return self.reverse().permutohedron_join(other.reverse(), side=side).reverse() @@ -4691,14 +4685,15 @@ def pattern_positions(self, patt) -> list: @combinatorial_map(name='Simion-Schmidt map') def simion_schmidt(self, avoid=[1,2,3]): r""" - Implements the Simion-Schmidt map which sends an arbitrary permutation + Implement the Simion-Schmidt map which sends an arbitrary permutation to a pattern avoiding permutation, where the permutation pattern is one of four length-three patterns. This method also implements the bijection between (for example) ``[1,2,3]``- and ``[1,3,2]``-avoiding permutations. INPUT: - - ``avoid`` -- one of the patterns ``[1,2,3]``, ``[1,3,2]``, ``[3,1,2]``, ``[3,2,1]``. + - ``avoid`` -- one of the patterns ``[1,2,3]``, ``[1,3,2]``, + ``[3,1,2]``, ``[3,2,1]`` EXAMPLES:: @@ -5412,7 +5407,7 @@ def hyperoctahedral_double_coset_type(self): # Binary operations # ##################### - def shifted_concatenation(self, other, side="right"): + def shifted_concatenation(self, other, side='right'): r""" Return the right (or left) shifted concatenation of ``self`` with a permutation ``other``. These operations are also known @@ -5421,18 +5416,18 @@ def shifted_concatenation(self, other, side="right"): INPUT: - ``other`` -- a permutation, a list, a tuple, or any iterable - representing a permutation. + representing a permutation - - ``side`` -- (default: ``"right"``) the string "left" or "right". + - ``side`` -- string (default: ``'right'``); ``'left'`` or ``'right'`` OUTPUT: - If ``side`` is ``"right"``, the method returns the permutation + If ``side`` is ``'right'``, the method returns the permutation obtained by concatenating ``self`` with the letters of ``other`` incremented by the size of ``self``. This is what is called ``side / other`` in [LR0102066]_, and denoted as the "over" operation. - Otherwise, i. e., when ``side`` is ``"left"``, the method + Otherwise, i. e., when ``side`` is ``'left'``, the method returns the permutation obtained by concatenating the letters of ``other`` incremented by the size of ``self`` with ``self``. This is what is called ``side \ other`` in [LR0102066]_ @@ -5464,7 +5459,7 @@ def shifted_shuffle(self, other): INPUT: - ``other`` -- a permutation, a list, a tuple, or any iterable - representing a permutation. + representing a permutation OUTPUT: @@ -5536,8 +5531,8 @@ def nth_roots(self, n): sage: list(sigma.nth_roots(2)) [] - For n >= 6, this algorithm begins to be more efficient than naive search - (look at all permutations and test their n-th power). + For `n \geq 6`, this algorithm begins to be more efficient than naive search + (look at all permutations and test their `n`-th power). .. SEEALSO:: @@ -5570,7 +5565,7 @@ def nth_roots(self, n): def merging_cycles(list_of_cycles): """ - Generate all l-cycles such that its n-th power is the product + Generate all l-cycles such that its `n`-th power is the product of cycles in 'cycles' (which contains gcd(l, n) cycles of length l/gcd(l, n)) """ lC = len(list_of_cycles) @@ -6518,7 +6513,7 @@ def unrank(self, r): INPUT: - - ``r`` -- an integer between ``0`` and ``self.cardinality()-1`` + - ``r`` -- integer between ``0`` and ``self.cardinality()-1`` inclusive ALGORITHM: @@ -8230,9 +8225,9 @@ def bistochastic_as_sum_of_permutations(M, check=True): INPUT: - - ``M`` -- A bistochastic matrix + - ``M`` -- a bistochastic matrix - - ``check`` (boolean) -- set to ``True`` (default) to check + - ``check`` -- boolean; set to ``True`` (default) to check that the matrix is indeed bistochastic OUTPUT: @@ -8472,7 +8467,6 @@ def cardinality(self): sage: D = [6, 8, 10, 11, 12, 13, 14, 15, 17, 19] sage: P(D, n).cardinality() 125291047596 - """ def m(l): s = 0 @@ -9073,7 +9067,7 @@ def bruhat_lequal(p1, p2): # Permutohedron # ################# -def permutohedron_lequal(p1, p2, side="right"): +def permutohedron_lequal(p1, p2, side='right'): r""" Return ``True`` if ``p1`` is less than or equal to ``p2`` in the permutohedron order. @@ -9184,7 +9178,7 @@ class CyclicPermutations(Permutations_mset): INPUT: - - ``mset`` -- A multiset + - ``mset`` -- a multiset EXAMPLES:: diff --git a/src/sage/combinat/permutation_cython.pyx b/src/sage/combinat/permutation_cython.pyx index d9d095cfc61..978510c4ae9 100644 --- a/src/sage/combinat/permutation_cython.pyx +++ b/src/sage/combinat/permutation_cython.pyx @@ -80,7 +80,6 @@ cdef int next_swap(int n, int *c, int *o) noexcept: Returns the index i such that the next permutation can be obtained by swapping P[i] <-> P[i+1] - """ cdef int j,s,q,offset @@ -116,7 +115,7 @@ cdef int next_swap(int n, int *c, int *o) noexcept: def permutation_iterator_transposition_list(int n): """ - Returns a list of transposition indices to enumerate the + Return a list of transposition indices to enumerate the permutations on `n` letters by adjacent transpositions. Assumes zero-based lists. We artificially limit the argument to `n < 12` to avoid overflowing 32-bit pointers. @@ -188,9 +187,7 @@ cpdef bint next_perm(array l) noexcept: This method mutates the array ``l``. - OUTPUT: - - boolean; whether another permutation was obtained + OUTPUT: boolean; whether another permutation was obtained EXAMPLES:: @@ -267,11 +264,9 @@ cpdef map_to_list(array l, tuple values, int n): - ``l`` -- array of unsigned int (i.e., type ``'I'``) - ``values`` -- tuple; the values of the permutation - - ``n`` -- int; the length of the array ``l`` - - OUTPUT: + - ``n`` -- integer; the length of the array ``l`` - A list representing the permutation. + OUTPUT: list representing the permutation EXAMPLES:: diff --git a/src/sage/combinat/plane_partition.py b/src/sage/combinat/plane_partition.py index f8ad4a6757b..c238ce77248 100644 --- a/src/sage/combinat/plane_partition.py +++ b/src/sage/combinat/plane_partition.py @@ -56,15 +56,13 @@ class PlanePartition(ClonableArray, INPUT: - - ``PP`` -- a list of lists which represents a tableau + - ``PP`` -- list of lists which represents a tableau - ``box_size`` -- (optional) a list ``[A, B, C]`` of 3 positive integers, where ``A``, ``B``, ``C`` are the lengths of the box in the `x`-axis, `y`-axis, `z`-axis, respectively; if this is not given, it is determined by the smallest box bounding ``PP`` - OUTPUT: - - The plane partition whose tableau representation is ``PP``. + OUTPUT: the plane partition whose tableau representation is ``PP`` EXAMPLES:: @@ -162,9 +160,7 @@ def __richcmp__(self, other, op): - ``other`` -- the element that ``self`` is compared to - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -214,7 +210,6 @@ def check(self): Traceback (most recent call last): ... ValueError: entries not all integers - """ if not all(a in ZZ for b in self for a in b): raise ValueError("entries not all integers") @@ -355,9 +350,7 @@ def _repr_diagram(self, show_box=False, use_unicode=False) -> str: also shows the visible tiles on the `xy`-, `yz`-, `zx`-planes - ``use_unicode`` -- boolean (default: ``False``); use unicode - OUTPUT: - - A string of the 3D diagram of the plane partition. + OUTPUT: string of the 3D diagram of the plane partition EXAMPLES:: @@ -508,9 +501,7 @@ def pp(self, show_box=False): - ``show_box`` -- boolean (default: ``False``); if ``True``, also shows the visible tiles on the `xy`-, `yz`-, `zx`-planes - OUTPUT: - - A pretty print of the plane partition. + OUTPUT: a pretty print of the plane partition EXAMPLES:: @@ -616,9 +607,7 @@ def _latex_(self, show_box=False, - ``colors`` -- (default: ``["white", "lightgray", "darkgray"]``) list ``[A, B, C]`` of 3 strings representing colors - OUTPUT: - - Latex code for drawing the plane partition. + OUTPUT: latex code for drawing the plane partition EXAMPLES:: @@ -696,15 +685,15 @@ def move(side, i, j, k): for P in side] def add_topside(i, j, k): - return polygon(move(Uside, i, j, k), edgecolor="black", + return polygon(move(Uside, i, j, k), edgecolor='black', color=colors[0]) def add_leftside(i, j, k): - return polygon(move(Lside, i, j, k), edgecolor="black", + return polygon(move(Lside, i, j, k), edgecolor='black', color=colors[1]) def add_rightside(i, j, k): - return polygon(move(Rside, i, j, k), edgecolor="black", + return polygon(move(Rside, i, j, k), edgecolor='black', color=colors[2]) TP = plot([]) for r in range(len(self.z_tableau())): @@ -1485,7 +1474,7 @@ class PlanePartitions_all(PlanePartitions, DisjointUnionEnumeratedSets): """ def __init__(self): r""" - Initializes the class of all plane partitions. + Initialize the class of all plane partitions. .. WARNING:: @@ -1544,7 +1533,7 @@ class PlanePartitions_box(PlanePartitions): """ def __init__(self, box_size): r""" - Initializes the class of plane partitions that fit in a box of a + Initialize the class of plane partitions that fit in a box of a specified size. EXAMPLES:: @@ -1740,7 +1729,7 @@ class PlanePartitions_n(PlanePartitions): """ def __init__(self, n): r""" - Initializes the class of plane partitions with ``n`` boxes. + Initialize the class of plane partitions with ``n`` boxes. .. WARNING:: @@ -1851,7 +1840,6 @@ def cardinality(self) -> Integer: sage: P = PlanePartitions(17) sage: P.cardinality() 18334 - """ PPn = [1] for i in range(1, 1+self._n): diff --git a/src/sage/combinat/posets/cartesian_product.py b/src/sage/combinat/posets/cartesian_product.py index 8f581b5cda2..29206b236c5 100644 --- a/src/sage/combinat/posets/cartesian_product.py +++ b/src/sage/combinat/posets/cartesian_product.py @@ -25,25 +25,24 @@ class CartesianProductPoset(CartesianProduct): INPUT: - - ``sets`` -- a tuple of parents. + - ``sets`` -- tuple of parents - - ``category`` -- a subcategory of - ``Sets().CartesianProducts() & Posets()``. + - ``category`` -- a subcategory of ``Sets().CartesianProducts() & Posets()`` - - ``order`` -- a string or function specifying an order less or equal. - It can be one of the following: + - ``order`` -- string or function specifying an order less or equal; + it can be one of the following: - ``'native'`` -- elements are ordered by their native ordering, - i.e., the order the wrapped elements (tuples) provide. + i.e., the order the wrapped elements (tuples) provide - - ``'lex'`` -- elements are ordered lexicographically. + - ``'lex'`` -- elements are ordered lexicographically - ``'product'`` -- an element is less or equal to another element, if less or equal is true for all its components - (Cartesian projections). + (Cartesian projections) - - A function which performs the comparison `\leq`. It takes two - input arguments and outputs a boolean. + - a function which performs the comparison `\leq`; it takes two + input arguments and outputs a boolean Other keyword arguments (``kwargs``) are passed to the constructor of :class:`CartesianProduct`. @@ -118,13 +117,11 @@ def le(self, left, right): INPUT: - - ``left`` -- an element. + - ``left`` -- an element - - ``right`` -- an element. + - ``right`` -- an element - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -156,13 +153,11 @@ def le_lex(self, left, right): INPUT: - - ``left`` -- an element. - - - ``right`` -- an element. + - ``left`` -- an element - OUTPUT: + - ``right`` -- an element - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -220,13 +215,11 @@ def le_product(self, left, right): INPUT: - - ``left`` -- an element. - - - ``right`` -- an element. + - ``left`` -- an element - OUTPUT: + - ``right`` -- an element - A boolean. + OUTPUT: boolean The comparison is ``True`` if the result of the comparison in each component is ``True``. @@ -269,13 +262,11 @@ def le_native(self, left, right): INPUT: - - ``left`` -- an element. + - ``left`` -- an element - - ``right`` -- an element. + - ``right`` -- an element - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -313,11 +304,9 @@ def _le_(self, other): INPUT: - - ``other`` -- an element. - - OUTPUT: + - ``other`` -- an element - A boolean. + OUTPUT: boolean .. NOTE:: @@ -348,11 +337,9 @@ def __le__(self, other): INPUT: - - ``other`` -- an element. + - ``other`` -- an element - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -411,11 +398,9 @@ def __ge__(self, other): INPUT: - - ``other`` -- an element. - - OUTPUT: + - ``other`` -- an element - A boolean. + OUTPUT: boolean .. NOTE:: @@ -446,11 +431,9 @@ def __lt__(self, other): INPUT: - - ``other`` -- an element. + - ``other`` -- an element - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -481,11 +464,9 @@ def __gt__(self, other): INPUT: - - ``other`` -- an element. - - OUTPUT: + - ``other`` -- an element - A boolean. + OUTPUT: boolean .. NOTE:: diff --git a/src/sage/combinat/posets/elements.py b/src/sage/combinat/posets/elements.py index 5d033c5c26a..7a94d76e213 100644 --- a/src/sage/combinat/posets/elements.py +++ b/src/sage/combinat/posets/elements.py @@ -162,15 +162,12 @@ def _cmp(self, other): sage: P(0)._cmp(P(0)) 0 sage: P(1)._cmp(P(2)) - """ return self.parent().compare_elements(self, other) def __lt__(self, other): """ - TESTS - - :: + TESTS:: sage: dag = DiGraph({0:[2,3], 1:[3,4], 2:[5], 3:[5], 4:[5]}) sage: P = Poset(dag, facade = False) @@ -185,9 +182,7 @@ def __lt__(self, other): def __le__(self, other): """ - TESTS - - :: + TESTS:: sage: dag = DiGraph({0:[2,3], 1:[3,4], 2:[5], 3:[5], 4:[5]}) sage: P = Poset(dag, facade = False) @@ -204,9 +199,7 @@ def __le__(self, other): def __gt__(self, other): """ - TESTS - - :: + TESTS:: sage: dag = DiGraph({0:[2,3], 1:[3,4], 2:[5], 3:[5], 4:[5]}) sage: P = Poset(dag) @@ -221,9 +214,7 @@ def __gt__(self, other): def __ge__(self, other): """ - TESTS - - :: + TESTS:: sage: dag = DiGraph({0:[2,3], 1:[3,4], 2:[5], 3:[5], 4:[5]}) sage: P = Poset(dag) diff --git a/src/sage/combinat/posets/hasse_cython.pyx b/src/sage/combinat/posets/hasse_cython.pyx index 2048febd192..fee64e5d5c4 100644 --- a/src/sage/combinat/posets/hasse_cython.pyx +++ b/src/sage/combinat/posets/hasse_cython.pyx @@ -27,15 +27,15 @@ class IncreasingChains(RecursivelyEnumeratedSet_forest): INPUT: - - ``positions`` -- a list of sets of integers describing the poset, - as given by the lazy attribute ``_leq_storage`` of Hasse diagrams. + - ``positions`` -- list of sets of integers describing the poset, + as given by the lazy attribute ``_leq_storage`` of Hasse diagrams - ``element_constructor`` -- used to determine the type of chains, for example :class:`list` or :class:`tuple` - ``exclude`` -- list of integers that should not belong to the chains - - ``conversion`` -- optional list of elements of the poset + - ``conversion`` -- (optional) list of elements of the poset If ``conversion`` is provided, it is used to convert chain elements to elements of this list. diff --git a/src/sage/combinat/posets/hasse_cython_flint.pyx b/src/sage/combinat/posets/hasse_cython_flint.pyx index 5d2c5b967ae..e2b4589b238 100644 --- a/src/sage/combinat/posets/hasse_cython_flint.pyx +++ b/src/sage/combinat/posets/hasse_cython_flint.pyx @@ -28,12 +28,10 @@ cpdef Matrix_integer_dense moebius_matrix_fast(list positions): INPUT: - a list of sets of integers describing the poset, as given by the - lazy attribute ``_leq_storage`` of Hasse diagrams. + - ``positions`` -- a list of sets of integers describing the poset, as + given by the lazy attribute ``_leq_storage`` of Hasse diagrams - OUTPUT: - - a dense matrix + OUTPUT: a dense matrix EXAMPLES:: @@ -87,12 +85,10 @@ cpdef Matrix_integer_dense coxeter_matrix_fast(list positions): INPUT: - a list of sets of integers describing the poset, as given by the - lazy attribute ``_leq_storage`` of Hasse diagrams. - - OUTPUT: + - ``positions`` -- a list of sets of integers describing the poset, as + given by the lazy attribute ``_leq_storage`` of Hasse diagrams - a dense matrix + OUTPUT: a dense matrix EXAMPLES:: diff --git a/src/sage/combinat/posets/hasse_diagram.py b/src/sage/combinat/posets/hasse_diagram.py index 59c3f435976..0056ad37eed 100644 --- a/src/sage/combinat/posets/hasse_diagram.py +++ b/src/sage/combinat/posets/hasse_diagram.py @@ -74,7 +74,7 @@ class HasseDiagram(DiGraph): The Hasse diagram of a poset. This is just a transitively-reduced, directed, acyclic graph without loops or multiple edges. - .. note:: + .. NOTE:: We assume that ``range(n)`` is a linear extension of the poset. That is, ``range(n)`` is the vertex set and a topological sort of @@ -103,7 +103,7 @@ def _repr_(self): def linear_extension(self): r""" - Return a linear extension + Return a linear extension. EXAMPLES:: @@ -293,7 +293,7 @@ def is_lequal(self, i, j) -> bool: Return ``True`` if i is less than or equal to j in the poset, and ``False`` otherwise. - .. note:: + .. NOTE:: If the :meth:`lequal_matrix` has been computed, then this method is redefined to use the cached data (see :meth:`_alternate_is_lequal`). @@ -611,9 +611,9 @@ def interval(self, x, y): INPUT: - - ``x`` -- any element of the poset + - ``x`` -- any element of the poset - - ``y`` -- any element of the poset + - ``y`` -- any element of the poset .. NOTE:: @@ -645,9 +645,9 @@ def interval_iterator(self, x, y): INPUT: - - ``x`` -- any element of the poset + - ``x`` -- any element of the poset - - ``y`` -- any element of the poset + - ``y`` -- any element of the poset .. SEEALSO:: :meth:`interval` @@ -1035,15 +1035,13 @@ def moebius_function_matrix(self, algorithm='cython'): INPUT: - - ``algorithm`` -- optional, ``'recursive'``, ``'matrix'`` - or ``'cython'`` (default) + - ``algorithm`` -- ``'recursive'``, ``'matrix'`` or ``'cython'`` + (default) This uses either the recursive formula, a generic matrix inversion or a specific matrix inversion coded in Cython. - OUTPUT: - - a dense matrix for the algorithm ``cython``, a sparse matrix otherwise + OUTPUT: a dense matrix for the algorithm ``cython``, a sparse matrix otherwise .. NOTE:: @@ -1150,7 +1148,7 @@ def coxeter_transformation(self, algorithm='cython'): INPUT: - - ``algorithm`` -- optional, ``'cython'`` (default) or ``'matrix'`` + - ``algorithm`` -- ``'cython'`` (default) or ``'matrix'`` This uses either a specific matrix code in Cython, or generic matrices. @@ -1167,7 +1165,7 @@ def coxeter_transformation(self, algorithm='cython'): [-1 1 1 0 -1] [-1 1 0 1 -1] sage: P.__dict__['coxeter_transformation'].clear_cache() - sage: P.coxeter_transformation(algorithm="matrix") == M + sage: P.coxeter_transformation(algorithm='matrix') == M True TESTS:: @@ -1178,7 +1176,7 @@ def coxeter_transformation(self, algorithm='cython'): sage: M**8 == 1 True sage: P.__dict__['coxeter_transformation'].clear_cache() - sage: P.coxeter_transformation(algorithm="banana") + sage: P.coxeter_transformation(algorithm='banana') Traceback (most recent call last): ... ValueError: unknown algorithm @@ -1368,7 +1366,7 @@ def lequal_matrix(self, boolean=False): INPUT: - - ``boolean`` -- optional flag (default ``False``) telling whether to + - ``boolean`` -- flag (default: ``False``); whether to return a matrix with coefficients in `\GF(2)` or in `\ZZ` .. SEEALSO:: @@ -1664,7 +1662,7 @@ def is_meet_semilattice(self) -> bool: @lazy_attribute def _join(self): r""" - Computes a matrix whose ``(x,y)``-entry is the join of ``x`` + Compute a matrix whose ``(x,y)``-entry is the join of ``x`` and ``y`` in ``self`` if the join exists; and `-1` otherwise. EXAMPLES:: @@ -1873,11 +1871,11 @@ def vertical_decomposition(self, return_list=False): INPUT: - - ``return_list``, a boolean. If ``False`` (the default), return - an element that is not the top neither the bottom element of the - lattice, but is comparable to all elements of the lattice, if - the lattice is vertically decomposable and ``None`` otherwise. - If ``True``, return list of decomposition elements. + - ``return_list`` -- boolean (default: ``False``); if ``False`` (the + default), return an element that is not the top neither the bottom + element of the lattice, but is comparable to all elements of the + lattice, if the lattice is vertically decomposable and ``None`` + otherwise. If ``True``, return list of decomposition elements. EXAMPLES:: @@ -1956,7 +1954,7 @@ def pseudocomplement(self, element): INPUT: - - ``element`` -- an element of the lattice. + - ``element`` -- an element of the lattice OUTPUT: @@ -1989,9 +1987,7 @@ def orthocomplementations_iterator(self): r""" Return an iterator over orthocomplementations of the lattice. - OUTPUT: - - An iterator that gives plain list of integers. + OUTPUT: an iterator that gives plain list of integers EXAMPLES:: @@ -2164,8 +2160,8 @@ def find_nonsemimodular_pair(self, upper): INPUT: - - ``upper``, a Boolean -- if ``True``, test whether the lattice is - upper semimodular; otherwise test whether the lattice is + - ``upper`` -- boolean; if ``True``, test whether the lattice is + upper semimodular. Otherwise test whether the lattice is lower semimodular. OUTPUT: @@ -2209,7 +2205,7 @@ def antichains_iterator(self): r""" Return an iterator over the antichains of the poset. - .. note:: + .. NOTE:: The algorithm is based on Freese-Jezek-Nation p. 226. It does a depth first search through the set of all @@ -2264,7 +2260,7 @@ def antichains_iterator(self): def are_incomparable(self, i, j): """ - Return whether ``i`` and ``j`` are incomparable in the poset + Return whether ``i`` and ``j`` are incomparable in the poset. INPUT: @@ -2290,11 +2286,11 @@ def are_incomparable(self, i, j): def are_comparable(self, i, j): """ - Return whether ``i`` and ``j`` are comparable in the poset + Return whether ``i`` and ``j`` are comparable in the poset. INPUT: - - ``i``, ``j`` -- vertices of this Hasse diagram + - ``i``, ``j`` -- vertices of this Hasse diagram EXAMPLES:: @@ -2318,11 +2314,11 @@ def are_comparable(self, i, j): def antichains(self, element_class=list): """ - Return all antichains of ``self``, organized as a prefix tree + Return all antichains of ``self``, organized as a prefix tree. INPUT: - - ``element_class`` -- (default:list) an iterable type + - ``element_class`` -- (default: ``list``) an iterable type EXAMPLES:: @@ -2365,7 +2361,7 @@ def chains(self, element_class=list, exclude=None, conversion=None): (default: ``None``) - ``conversion`` -- (default: ``None``) used to pass - the list of elements of the poset in their fixed order + the list of elements of the poset in their fixed order OUTPUT: @@ -2490,9 +2486,7 @@ def diamonds(self) -> tuple: Thus each edge represents a cover relation in the Hasse diagram. We represent his as the tuple `(w, x, y, z)`. - OUTPUT: - - A tuple with + OUTPUT: a tuple with - a list of all diamonds in the Hasse Diagram, - a boolean checking that every `w,x,y` that form a ``V``, there is a @@ -2622,9 +2616,7 @@ def sublattices_iterator(self, elms, min_e): - ``elms`` -- elements already in sublattice; use set() at start - ``min_e`` -- smallest new element to add for new sublattices - OUTPUT: - - List of sublattices as sets of integers. + OUTPUT: list of sublattices as sets of integers EXAMPLES:: @@ -3146,9 +3138,9 @@ def congruence(self, parts, start=None, stop_pairs=None): INPUT: - - ``parts`` -- a list of lists; congruences to add + - ``parts`` -- list of lists; congruences to add - ``start`` -- a disjoint set; already computed congruence (or ``None``) - - ``stop_pairs`` -- a list of pairs; list of pairs for stopping computation + - ``stop_pairs`` -- list of pairs; list of pairs for stopping computation OUTPUT: diff --git a/src/sage/combinat/posets/lattices.py b/src/sage/combinat/posets/lattices.py index 9c5689bcb81..149915f8fb5 100644 --- a/src/sage/combinat/posets/lattices.py +++ b/src/sage/combinat/posets/lattices.py @@ -214,7 +214,7 @@ def MeetSemilattice(data=None, *args, **options): class FiniteMeetSemilattice(FinitePoset): """ - .. note:: + .. NOTE:: We assume that the argument passed to MeetSemilattice is the poset of a meet-semilattice (i.e. a poset with greatest lower bound for each pair of elements). @@ -266,8 +266,8 @@ def meet(self, x, y=None): INPUT: - - ``x, y`` -- two elements of the (semi)lattice OR - - ``x`` -- a list or tuple of elements + - ``x``, ``y`` -- two elements of the (semi)lattice OR + - ``x`` -- list or tuple of elements EXAMPLES:: @@ -342,7 +342,7 @@ def submeetsemilattice(self, elms): INPUT: - - ``elms`` -- a list of elements of the lattice. + - ``elms`` -- list of elements of the lattice EXAMPLES:: @@ -384,7 +384,7 @@ def subjoinsemilattice(self, elms): INPUT: - - ``elms`` -- a list of elements of the lattice. + - ``elms`` -- list of elements of the lattice EXAMPLES:: @@ -435,7 +435,7 @@ def pseudocomplement(self, element): INPUT: - - ``element`` -- an element of the lattice. + - ``element`` -- an element of the lattice OUTPUT: @@ -554,7 +554,6 @@ class FiniteJoinSemilattice(FinitePoset): sage: P = Poset([[1,2],[3],[3]]) sage: J = JoinSemilattice(P) sage: TestSuite(J).run() - """ Element = JoinSemilatticeElement _desc = 'Finite join-semilattice' @@ -592,8 +591,8 @@ def join(self, x, y=None): INPUT: - - ``x, y`` -- two elements of the (semi)lattice OR - - ``x`` -- a list or tuple of elements + - ``x``, ``y`` -- two elements of the (semi)lattice OR + - ``x`` -- list or tuple of elements EXAMPLES:: @@ -675,9 +674,7 @@ def LatticePoset(data=None, *args, **options): be passed down to :func:`Poset` to construct a poset that is also a lattice. - OUTPUT: - - An instance of :class:`FiniteLatticePoset`. + OUTPUT: an instance of :class:`FiniteLatticePoset` .. SEEALSO:: @@ -756,7 +753,6 @@ class FiniteLatticePoset(FiniteMeetSemilattice, FiniteJoinSemilattice): sage: P = Poset([[1,2],[3],[3]]) sage: L = LatticePoset(P) sage: TestSuite(L).run() - """ Element = LatticePosetElement @@ -935,7 +931,7 @@ def is_join_distributive(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1023,7 +1019,7 @@ def is_meet_distributive(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1116,7 +1112,7 @@ def is_stone(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1204,7 +1200,7 @@ def is_distributive(self, certificate=False): in lattices it follows that then also join distributes over meet. - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1326,7 +1322,7 @@ def is_meet_semidistributive(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1418,7 +1414,7 @@ def is_join_semidistributive(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1539,7 +1535,7 @@ def is_trim(self, certificate=False): INPUT: - - certificate -- boolean (default ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return instead a maximum chain of left modular elements EXAMPLES:: @@ -1588,7 +1584,7 @@ def is_complemented(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -1640,8 +1636,8 @@ def is_cosectionally_complemented(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) Whether to return - a certificate if the lattice is not cosectionally complemented. + - ``certificate`` -- boolean (default: ``False``); whether to return + a certificate if the lattice is not cosectionally complemented OUTPUT: @@ -1715,8 +1711,8 @@ def is_relatively_complemented(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) Whether to return - a certificate if the lattice is not relatively complemented. + - ``certificate`` -- boolean (default: ``False``); whether to return + a certificate if the lattice is not relatively complemented OUTPUT: @@ -1829,8 +1825,8 @@ def is_sectionally_complemented(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) Whether to return - a certificate if the lattice is not sectionally complemented. + - ``certificate`` -- boolean (default: ``False``); whether to return + a certificate if the lattice is not sectionally complemented OUTPUT: @@ -1909,7 +1905,7 @@ def breadth(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2102,7 +2098,7 @@ def is_pseudocomplemented(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2167,7 +2163,7 @@ def is_join_pseudocomplemented(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2281,7 +2277,7 @@ def is_orthocomplemented(self, unique=False): INPUT: - - ``unique``, a Boolean -- If ``True``, return ``True`` only + - ``unique`` -- boolean; if ``True``, return ``True`` only if the lattice has exactly one orthocomplementation. If ``False`` (the default), return ``True`` when the lattice has at least one orthocomplementation. @@ -2334,7 +2330,7 @@ def is_atomic(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2393,7 +2389,7 @@ def is_coatomic(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2574,7 +2570,7 @@ def is_modular(self, L=None, certificate=False): - ``L`` -- (default: ``None``) a list of elements to check being modular, if ``L`` is ``None``, then this checks the entire lattice - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2732,8 +2728,8 @@ def is_upper_semimodular(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) Whether to return - a certificate if the lattice is not upper semimodular. + - ``certificate`` -- boolean (default: ``False``); whether to return + a certificate if the lattice is not upper semimodular OUTPUT: @@ -2792,8 +2788,8 @@ def is_lower_semimodular(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) Whether to return - a certificate if the lattice is not lower semimodular. + - ``certificate`` -- boolean (default: ``False``); whether to return + a certificate if the lattice is not lower semimodular OUTPUT: @@ -2849,7 +2845,7 @@ def is_supersolvable(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -2955,7 +2951,7 @@ def vertical_composition(self, other, labels='pairs'): - ``other`` -- a lattice - - ``labels`` -- a string (default ``'pairs'``); can be one of + - ``labels`` -- string (default: ``'pairs'``); can be one of the following: * ``'pairs'`` -- each element ``v`` in this poset will be @@ -3109,7 +3105,7 @@ def is_vertically_decomposable(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -3158,7 +3154,7 @@ def sublattice(self, elms): INPUT: - - ``elms`` -- a list of elements of the lattice. + - ``elms`` -- list of elements of the lattice EXAMPLES:: @@ -3355,7 +3351,7 @@ def isomorphic_sublattices_iterator(self, other): INPUT: - - other -- a finite lattice + - ``other`` -- a finite lattice EXAMPLES: @@ -3467,9 +3463,7 @@ def moebius_algebra(self, R): """ Return the Möbius algebra of ``self`` over ``R``. - OUTPUT: - - An instance of :class:`sage.combinat.posets.moebius_algebra.MoebiusAlgebra`. + OUTPUT: an instance of :class:`sage.combinat.posets.moebius_algebra.MoebiusAlgebra` EXAMPLES:: @@ -3488,9 +3482,7 @@ def quantum_moebius_algebra(self, q=None): - ``q`` -- (optional) the deformation parameter `q` - OUTPUT: - - An instance of :class:`sage.combinat.posets.moebius_algebra.QuantumMoebiusAlgebra`. + OUTPUT: an instance of :class:`sage.combinat.posets.moebius_algebra.QuantumMoebiusAlgebra` EXAMPLES:: @@ -3704,7 +3696,7 @@ def is_dismantlable(self, certificate=False): INPUT: - - ``certificate`` (boolean) -- Whether to return a certificate. + - ``certificate`` -- boolean; whether to return a certificate * If ``certificate = False`` (default), returns ``True`` or ``False`` accordingly. @@ -3821,7 +3813,7 @@ def is_interval_dismantlable(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -4002,7 +3994,7 @@ def is_subdirectly_reducible(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -4092,9 +4084,7 @@ def canonical_meetands(self, e): - ``e`` -- an element of the lattice - OUTPUT: - - - canonical meetands as a list, if it exists; if not, ``None`` + OUTPUT: canonical meetands as a list, if it exists; if not, ``None`` EXAMPLES:: @@ -4158,9 +4148,7 @@ def canonical_joinands(self, e): - ``e`` -- an element of the lattice - OUTPUT: - - - canonical joinands as a list, if it exists; if not, ``None`` + OUTPUT: canonical joinands as a list, if it exists; if not, ``None`` EXAMPLES:: @@ -4222,7 +4210,7 @@ def is_constructible_by_doublings(self, type) -> bool: INPUT: - - ``type`` -- a string; can be one of the following: + - ``type`` -- string; can be one of the following: * ``'interval'`` -- allow only doublings of an interval * ``'lower'`` -- allow doublings of lower pseudo-interval; that is, a @@ -4365,7 +4353,7 @@ def is_isoform(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate if the lattice is not isoform OUTPUT: @@ -4440,7 +4428,7 @@ def is_uniform(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate if the lattice is not uniform OUTPUT: @@ -4520,7 +4508,7 @@ def is_regular(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate if the lattice is not regular OUTPUT: @@ -4589,7 +4577,7 @@ def is_simple(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate if the lattice is not simple OUTPUT: @@ -4733,7 +4721,7 @@ def congruence(self, S): INPUT: - - ``S`` -- a list of lists; list of element blocks that the congruence + - ``S`` -- list of lists; list of element blocks that the congruence will contain OUTPUT: @@ -4890,11 +4878,9 @@ def congruences_lattice(self, labels='congruence'): INPUT: - - ``labels`` -- a string; the type of elements in the resulting lattice - - OUTPUT: + - ``labels`` -- string; the type of elements in the resulting lattice - A distributive lattice. + OUTPUT: a distributive lattice - If ``labels='congruence'``, then elements of the result will be congruences given as @@ -4992,7 +4978,7 @@ def feichtner_yuzvinsky_ring(self, G, use_defining=False, base_ring=None): INPUT: - ``G`` -- a subset of elements of ``self`` - - ``use_defining`` -- (default: ``False``) whether or not to use + - ``use_defining`` -- boolean (default: ``False``); whether or not to use the defining presentation in `x_g` - ``base_ring`` -- (default: `\QQ`) the base ring diff --git a/src/sage/combinat/posets/linear_extension_iterator.pyx b/src/sage/combinat/posets/linear_extension_iterator.pyx index 59506021e07..906957fdbde 100644 --- a/src/sage/combinat/posets/linear_extension_iterator.pyx +++ b/src/sage/combinat/posets/linear_extension_iterator.pyx @@ -14,7 +14,7 @@ def _linear_extension_prepare(D): INPUT: - - ``D``, the Hasse diagram of a poset + - ``D`` -- the Hasse diagram of a poset OUTPUT: @@ -68,7 +68,6 @@ cdef void _linear_extension_switch(list _le, list _a, list _b, list _is_plus, Py If ``i == -1``, then the sign is changed. Otherwise, then ``_a[i]`` and ``_b[i]`` are transposed. - """ cdef Py_ssize_t a_index, b_index if i == -1: @@ -102,7 +101,6 @@ cdef bint _linear_extension_right_a(_D, list _le, list _a, list _b, Py_ssize_t i False sage: _linear_extension_right_a(D, [0, 1, 2, 4, 3], [1, 4], [2, 3], 1) # not tested False - """ cdef Py_ssize_t yindex x = _a[i] @@ -117,7 +115,7 @@ cdef bint _linear_extension_right_a(_D, list _le, list _a, list _b, Py_ssize_t i @cython.boundscheck(False) cdef bint _linear_extension_right_b(_D, list _le, list _a, list _b, Py_ssize_t i) noexcept: """ - Return True if and only if ``_b[i]`` is incomparable with the + Return ``True`` if and only if ``_b[i]`` is incomparable with the elements to its right in ``_le``. This is the ``Right`` function described on page 8 of @@ -130,7 +128,6 @@ cdef bint _linear_extension_right_b(_D, list _le, list _a, list _b, Py_ssize_t i False sage: _linear_extension_right_b(D, [0, 1, 2, 4, 3], [1, 4], [2, 3], 1) # not tested False - """ cdef Py_ssize_t yindex x = _b[i] @@ -155,7 +152,6 @@ def _linear_extension_gen(_D, list _le, list _a, list _b, list _is_plus, Py_ssiz sage: le, a, b = _linear_extension_prepare(D) sage: [e for e in _linear_extension_gen(D, le, a, b, [True], len(a)-1)] # needs sage.modules [[0, 2, 1, 3, 4]] - """ cdef int mra, mrb, mla cdef Py_ssize_t index, index1 @@ -253,7 +249,7 @@ def linear_extension_iterator(D): INPUT: - - ``D``, the Hasse diagram of a poset. + - ``D`` -- the Hasse diagram of a poset .. WARNING:: diff --git a/src/sage/combinat/posets/linear_extensions.py b/src/sage/combinat/posets/linear_extensions.py index 2289d7c2341..cf62e234321 100644 --- a/src/sage/combinat/posets/linear_extensions.py +++ b/src/sage/combinat/posets/linear_extensions.py @@ -52,7 +52,7 @@ class LinearExtensionOfPoset(ClonableArray, INPUT: - - ``linear_extension`` -- a list of the elements of `P` + - ``linear_extension`` -- list of the elements of `P` - ``poset`` -- the underlying poset `P` .. SEEALSO:: :class:`~sage.combinat.posets.posets.Poset`, :class:`LinearExtensionsOfPoset` @@ -93,11 +93,12 @@ class LinearExtensionOfPoset(ClonableArray, @staticmethod def __classcall_private__(cls, linear_extension, poset): r""" - Implements the shortcut ``LinearExtensionOfPoset(linear_extension, poset)`` to ``LinearExtensionsOfPoset(poset)(linear_extension)`` + Implement the shortcut ``LinearExtensionOfPoset(linear_extension, poset)`` + to ``LinearExtensionsOfPoset(poset)(linear_extension)``. INPUT: - - ``linear_extension`` -- a list of elements of ``poset`` + - ``linear_extension`` -- list of elements of ``poset`` - ``poset`` -- a finite poset .. TODO:: check whether this method is still useful @@ -131,7 +132,7 @@ def __classcall_private__(cls, linear_extension, poset): def check(self): r""" - Checks whether ``self`` is indeed a linear extension of the underlying poset. + Check whether ``self`` is indeed a linear extension of the underlying poset. TESTS:: @@ -320,7 +321,8 @@ def tau(self, i): INPUT: - - `i` -- an integer between `1` and `n-1`, where `n` is the cardinality of the poset. + - ``i`` -- integer between `1` and `n-1`, where `n` is the + cardinality of the poset The operator `\tau_i` on a linear extension `\pi` of a poset `P` interchanges positions `i` and `i+1` if the result is @@ -472,12 +474,12 @@ def jump_count(self): class LinearExtensionsOfPoset(UniqueRepresentation, Parent): """ - The set of all linear extensions of a finite poset + The set of all linear extensions of a finite poset. INPUT: - ``poset`` -- a poset `P` of size `n` - - ``facade`` -- a boolean (default: ``False``) + - ``facade`` -- boolean (default: ``False``) .. SEEALSO:: @@ -540,7 +542,7 @@ def __init__(self, poset, facade) -> None: sage: TestSuite(L).run() # needs sage.modules sage: L = P.linear_extensions(facade=True) - sage: TestSuite(L).run(skip="_test_an_element") # needs sage.modules + sage: TestSuite(L).run(skip='_test_an_element') # needs sage.modules """ self._poset = poset self._is_facade = facade @@ -660,7 +662,7 @@ def cardinality(self): def __iter__(self): r""" - Iterates through the linear extensions of the underlying poset. + Iterate through the linear extensions of the underlying poset. EXAMPLES:: @@ -701,7 +703,6 @@ def __contains__(self, obj) -> bool: sage: [p for p in Permutations(list(P)) if list(p) in L] [[1, 2, 3, 4, 6, 12], [1, 2, 3, 6, 4, 12], [1, 2, 4, 3, 6, 12], [1, 3, 2, 4, 6, 12], [1, 3, 2, 6, 4, 12]] - """ if not self._is_facade: return super().__contains__(obj) @@ -710,12 +711,12 @@ def __contains__(self, obj) -> bool: def markov_chain_digraph(self, action='promotion', labeling='identity'): r""" - Return the digraph of the action of generalized promotion or tau on ``self`` + Return the digraph of the action of generalized promotion or tau on ``self``. INPUT: - - ``action`` -- 'promotion' or 'tau' (default: 'promotion') - - ``labeling`` -- 'identity' or 'source' (default: 'identity') + - ``action`` -- 'promotion' or 'tau' (default: ``'promotion'``) + - ``labeling`` -- 'identity' or 'source' (default: ``'identity'``) .. TODO:: @@ -801,26 +802,29 @@ def markov_chain_digraph(self, action='promotion', labeling='identity'): for i in R: child = getattr(x, action)(i + 1) d[x][child] += [i + 1] - G = DiGraph(d, format="dict_of_dicts") + G = DiGraph(d, format='dict_of_dicts') if have_dot2tex(): - G.set_latex_options(format="dot2tex", edge_labels=True, + G.set_latex_options(format='dot2tex', edge_labels=True, color_by_label={1: "blue", 2: "red", 3: "green", 4: "yellow"}) return G def markov_chain_transition_matrix(self, action='promotion', labeling='identity'): r""" - Return the transition matrix of the Markov chain for the action of generalized promotion or tau on ``self`` + Return the transition matrix of the Markov chain for the action of + generalized promotion or tau on ``self``. INPUT: - ``action`` -- ``'promotion'`` or ``'tau'`` (default: ``'promotion'``) - ``labeling`` -- ``'identity'`` or ``'source'`` (default: ``'identity'``) - This method yields the transition matrix of the Markov chain defined by the action of the generalized - promotion operator `\partial_i` (resp. `\tau_i`) on the set of linear extensions of a finite poset. - Here the transition from the linear extension `\pi` to `\pi'`, where `\pi' = \pi \partial_i` - (resp. `\pi'= \pi \tau_i`) is counted with weight `x_i` (resp. `x_{\pi_i}` if ``labeling`` is set to ``source``). + This method yields the transition matrix of the Markov chain defined by + the action of the generalized promotion operator `\partial_i` (resp. + `\tau_i`) on the set of linear extensions of a finite poset. Here the + transition from the linear extension `\pi` to `\pi'`, where + `\pi' = \pi \partial_i` (resp. `\pi'= \pi \tau_i`) is counted with + weight `x_i` (resp. `x_{\pi_i}` if ``labeling`` is set to ``source``). EXAMPLES:: @@ -855,7 +859,6 @@ def markov_chain_transition_matrix(self, action='promotion', labeling='identity' [ 0 x0 0 x2 -x1 - x3] .. SEEALSO:: :meth:`markov_chain_digraph`, :meth:`promotion`, :meth:`tau` - """ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.matrix.constructor import matrix diff --git a/src/sage/combinat/posets/mobile.py b/src/sage/combinat/posets/mobile.py index 79d22aa1749..f529f6b664c 100644 --- a/src/sage/combinat/posets/mobile.py +++ b/src/sage/combinat/posets/mobile.py @@ -91,7 +91,7 @@ def _is_valid_ribbon(self, ribbon): INPUT: - - ``ribbon`` -- a list of elements that form a ribbon in your poset + - ``ribbon`` -- list of elements that form a ribbon in your poset TESTS:: diff --git a/src/sage/combinat/posets/poset_examples.py b/src/sage/combinat/posets/poset_examples.py index e2de5f4a751..468ad8d9a01 100644 --- a/src/sage/combinat/posets/poset_examples.py +++ b/src/sage/combinat/posets/poset_examples.py @@ -133,7 +133,7 @@ def check_int(n, minimum=0): sage: check_int(-1) Traceback (most recent call last): ... - ValueError: number of elements must be a non-negative integer, not -1 + ValueError: number of elements must be a nonnegative integer, not -1 sage: check_int(1, 3) Traceback (most recent call last): @@ -143,10 +143,10 @@ def check_int(n, minimum=0): sage: check_int('junk') Traceback (most recent call last): ... - ValueError: number of elements must be a non-negative integer, not junk + ValueError: number of elements must be a nonnegative integer, not junk """ if minimum == 0: - msg = "a non-negative integer" + msg = "a nonnegative integer" else: msg = f"an integer at least {minimum}" if n not in NonNegativeIntegers() or n < minimum: @@ -282,11 +282,11 @@ def BooleanLattice(n, facade=None, use_subsets=False): @staticmethod def ChainPoset(n, facade=None): - """ - Return a chain (a totally ordered poset) containing ``n`` elements. + r""" + Return a chain (a totally ordered poset) containing `n` elements. - - ``n`` (an integer) -- number of elements. - - ``facade`` (boolean) -- whether to make the returned poset a + - ``n`` -- integer; number of elements + - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor @@ -333,8 +333,8 @@ def AntichainPoset(n, facade=None): INPUT: - - ``n`` (an integer) -- number of elements - - ``facade`` (boolean) -- whether to make the returned poset a + - ``n`` -- integer; number of elements + - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor @@ -376,7 +376,7 @@ def PentagonPoset(facade=None): INPUT: - - ``facade`` (boolean) -- whether to make the returned poset a + - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor @@ -414,7 +414,7 @@ def DiamondPoset(n, facade=None): - ``n`` -- number of elements, an integer at least 3 - - ``facade`` (boolean) -- whether to make the returned poset a + - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor @@ -446,7 +446,7 @@ def Crown(n, facade=None): - ``n`` -- number of elements, an integer at least 2 - - ``facade`` (boolean) -- whether to make the returned poset a + - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor @@ -472,8 +472,8 @@ def DivisorLattice(n, facade=None): INPUT: - - ``n`` -- an integer - - ``facade`` (boolean) -- whether to make the returned poset a + - ``n`` -- integer + - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor @@ -578,7 +578,6 @@ def RestrictedIntegerPartitions(n): Finite poset containing 15 elements sage: len(P.cover_relations()) 17 - """ def lower_covers(partition): r""" @@ -614,7 +613,7 @@ def IntegerPartitionsDominanceOrder(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -688,8 +687,8 @@ def ProductOfChains(chain_lengths, facade=None): """ Return a product of chains. - - ``chain_lengths`` -- A list of nonnegative integers; number of - elements in each chain. + - ``chain_lengths`` -- list of nonnegative integers; number of + elements in each chain - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the @@ -741,7 +740,7 @@ def RandomPoset(n, p): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer - ``p`` -- a probability, a real number between 0 and 1 (inclusive) @@ -801,11 +800,11 @@ def RandomLattice(n, p, properties=None): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer - ``p`` -- a probability, a positive real number less than one - - ``properties`` -- a list of properties for the lattice. Currently + - ``properties`` -- list of properties for the lattice. Currently implemented: * ``None``, no restrictions for lattices to create @@ -938,7 +937,7 @@ def SetPartitions(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -1019,16 +1018,14 @@ def StandardExample(n, facade=None): INPUT: - - ``n`` -- an integer `\ge 2`, dimension of the constructed poset + - ``n`` -- integer `\ge 2`; dimension of the constructed poset - ``facade`` -- boolean; whether to make the returned poset a facade poset (see :mod:`sage.categories.facade_sets`); the default behaviour is the same as the default behaviour of the :func:`~sage.combinat.posets.posets.Poset` constructor - OUTPUT: - - The standard example of a poset of dimension `n`. + OUTPUT: the standard example of a poset of dimension `n` EXAMPLES:: @@ -1085,7 +1082,7 @@ def SymmetricGroupBruhatIntervalPoset(start, end): - ``end`` -- list permutation (same n, of course) - .. note:: + .. NOTE:: Must have ``start`` <= ``end``. @@ -1120,15 +1117,15 @@ def SymmetricGroupBruhatIntervalPoset(start, end): return Poset(nodes) @staticmethod - def SymmetricGroupWeakOrderPoset(n, labels="permutations", side="right"): + def SymmetricGroupWeakOrderPoset(n, labels='permutations', side='right'): r""" The poset of permutations of `\{ 1, 2, \ldots, n \}` with respect to the weak order (also known as the permutohedron order, cf. :meth:`~sage.combinat.permutation.Permutation.permutohedron_lequal`). - The optional variable ``labels`` (default: ``"permutations"``) + The optional variable ``labels`` (default: ``'permutations'``) determines the labelling of the elements if `n < 10`. The optional - variable ``side`` (default: ``"right"``) determines whether the + variable ``side`` (default: ``'right'``) determines whether the right or the left permutohedron order is to be used. EXAMPLES:: @@ -1183,13 +1180,13 @@ def TetrahedralPoset(n, *colors, **labels): INPUT: - - ``n`` -- Defines the number (n-1) of layers in the poset. + - ``n`` -- defines the number (n-1) of layers in the poset - - ``colors`` -- The colors that define the covering relations of the - poset. Colors used are 'green', 'red', 'yellow', 'orange', 'silver', - and 'blue'. + - ``colors`` -- the colors that define the covering relations of the + poset; colors used are 'green', 'red', 'yellow', 'orange', 'silver', + and 'blue' - - ``labels`` -- Keyword variable used to determine whether the poset + - ``labels`` -- keyword variable used to determine whether the poset is labeled with integers or tuples. To label with integers, the method should be called with ``labels='integers'``. Otherwise, the labeling will default to tuples. @@ -1312,13 +1309,13 @@ def NoncrossingPartitions(W): return W.noncrossing_partition_lattice() @staticmethod - def SymmetricGroupAbsoluteOrderPoset(n, labels="permutations"): + def SymmetricGroupAbsoluteOrderPoset(n, labels='permutations'): r""" Return the poset of permutations with respect to absolute order. INPUT: - - ``n`` -- a positive integer + - ``n`` -- a positive integer - ``label`` -- (default: ``'permutations'``) a label for the elements of the poset returned by the function; the options are @@ -1334,9 +1331,9 @@ def SymmetricGroupAbsoluteOrderPoset(n, labels="permutations"): sage: posets.SymmetricGroupAbsoluteOrderPoset(4) # needs sage.groups Finite poset containing 24 elements - sage: posets.SymmetricGroupAbsoluteOrderPoset(3, labels="cycles") # needs sage.groups + sage: posets.SymmetricGroupAbsoluteOrderPoset(3, labels='cycles') # needs sage.groups Finite poset containing 6 elements - sage: posets.SymmetricGroupAbsoluteOrderPoset(3, labels="reduced_words") # needs sage.groups + sage: posets.SymmetricGroupAbsoluteOrderPoset(3, labels='reduced_words') # needs sage.groups Finite poset containing 6 elements """ from sage.groups.perm_gps.permgroup_named import SymmetricGroup @@ -1362,8 +1359,8 @@ def UpDownPoset(n, m=1): INPUT: - - ``n`` -- nonnegative integer, number of elements in the poset - - ``m`` -- nonnegative integer (default 1), how frequently down + - ``n`` -- nonnegative integer; number of elements in the poset + - ``m`` -- nonnegative integer (default: 1); how frequently down steps occur OUTPUT: @@ -1409,9 +1406,9 @@ def YoungDiagramPoset(lam, dual=False): INPUT: - ``lam`` -- a partition - - ``dual`` -- (default: ``False``) determines the orientation - of the poset; if ``True``, then it is a join semilattice, - otherwise it is a meet semilattice + - ``dual`` -- boolean (default: ``False``); determines the orientation + of the poset. If ``True``, then it is a join semilattice, + otherwise it is a meet semilattice. EXAMPLES:: @@ -1429,9 +1426,8 @@ def YoungDiagramPoset(lam, dual=False): if dual: def cell_geq(a, b): """ - Nested function that returns `True` if the cell `a` is - to the right or below - the cell `b` in the (English) Young diagram. + Nested function that returns ``True`` if the cell `a` is to the + right or below the cell `b` in the (English) Young diagram. """ return ((a[0] == b[0] + 1 and a[1] == b[1]) or (a[1] == b[1] + 1 and a[0] == b[0])) @@ -1439,7 +1435,7 @@ def cell_geq(a, b): else: def cell_leq(a, b): """ - Nested function that returns `True` if the cell `a` is + Nested function that returns ``True`` if the cell `a` is to the left or above the cell `b` in the (English) Young diagram. """ @@ -1457,7 +1453,7 @@ def YoungsLattice(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -1581,7 +1577,7 @@ def DoubleTailedDiamond(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -1606,7 +1602,7 @@ def PermutationPattern(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer A permutation `u = u_1 \cdots u_n` contains the pattern `v = v_1 \cdots v_m` if there is a (not necessarily consecutive) @@ -1721,7 +1717,7 @@ def PermutationPatternOccurrenceInterval(bottom, top, pos): - ``bottom``, ``top`` -- permutations where ``top`` contains ``bottom`` as a pattern - - ``pos`` -- a list of indices indicating a distinguished copy of + - ``pos`` -- list of indices indicating a distinguished copy of ``bottom`` inside ``top`` (indexed starting at 0) For further information (and picture illustrating included example), @@ -1804,7 +1800,7 @@ def MobilePoset(ribbon, hangers, anchor=None): INPUT: - ``ribbon`` -- a finite poset that is a ribbon - - ``hangers`` -- a dictionary mapping an element on the ribbon + - ``hangers`` -- dictionary mapping an element on the ribbon to a list of d-complete posets that it covers - ``anchor`` -- (optional) a ``tuple`` (``ribbon_elmt``, ``anchor_elmt``, ``anchor_poset``), where ``anchor_elmt`` covers @@ -1863,7 +1859,7 @@ def _random_lattice(n, p): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer - ``p`` -- a number at least zero and less than one; higher number means more covering relations @@ -1935,7 +1931,7 @@ def _random_dismantlable_lattice(n): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer OUTPUT: @@ -1978,7 +1974,7 @@ def _random_planar_lattice(n): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer OUTPUT: @@ -2029,7 +2025,7 @@ def _random_distributive_lattice(n): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer OUTPUT: @@ -2086,7 +2082,7 @@ def _random_stone_lattice(n): INPUT: - - ``n`` -- number of elements, a non-negative integer + - ``n`` -- number of elements, a nonnegative integer OUTPUT: diff --git a/src/sage/combinat/posets/posets.py b/src/sage/combinat/posets/posets.py index f462becaa17..a111609b4b0 100644 --- a/src/sage/combinat/posets/posets.py +++ b/src/sage/combinat/posets/posets.py @@ -84,7 +84,7 @@ :meth:`~FinitePoset.is_incomparable_chain_free` | Return ``True`` if the poset is (m+n)-free. :meth:`~FinitePoset.is_slender` | Return ``True`` if the poset is slender. :meth:`~FinitePoset.is_sperner` | Return ``True`` if the poset is Sperner. - :meth:`~FinitePoset.is_join_semilattice` | Return ``True`` is the poset has a join operation. + :meth:`~FinitePoset.is_join_semilattice` | Return ``True`` if the poset has a join operation. :meth:`~FinitePoset.is_meet_semilattice` | Return ``True`` if the poset has a meet operation. **Minimal and maximal elements** @@ -236,7 +236,7 @@ :widths: 30, 70 :delim: | - :meth:`~FinitePoset.lequal_matrix` | Computes the matrix whose ``(i,j)`` entry is 1 if ``self.linear_extension()[i] < self.linear_extension()[j]`` and 0 otherwise. + :meth:`~FinitePoset.lequal_matrix` | Compute the matrix whose ``(i,j)`` entry is 1 if ``self.linear_extension()[i] < self.linear_extension()[j]`` and 0 otherwise. :meth:`~FinitePoset.moebius_function` | Return the value of Möbius function of given elements in the poset. :meth:`~FinitePoset.moebius_function_matrix` | Return a matrix whose ``(i,j)`` entry is the value of the Möbius function evaluated at ``self.linear_extension()[i]`` and ``self.linear_extension()[j]``. :meth:`~FinitePoset.coxeter_transformation` | Return the matrix of the Auslander-Reiten translation acting on the Grothendieck group of the derived category of modules. @@ -256,7 +256,7 @@ :meth:`~FinitePoset.list` | List the elements of the poset. :meth:`~FinitePoset.cuts` | Return the cuts of the given poset. :meth:`~FinitePoset.dilworth_decomposition` | Return a partition of the points into the minimal number of chains. - :meth:`~FinitePoset.greene_shape` | Computes the Greene-Kleitman partition aka Greene shape of the poset ``self``. + :meth:`~FinitePoset.greene_shape` | Compute the Greene-Kleitman partition aka Greene shape of the poset ``self``. :meth:`~FinitePoset.incidence_algebra` | Return the incidence algebra of ``self``. :meth:`~FinitePoset.is_EL_labelling` | Return whether ``f`` is an EL labelling of the poset. :meth:`~FinitePoset.isomorphic_subposets_iterator` | Return an iterator over the subposets isomorphic to another poset. @@ -266,7 +266,7 @@ :meth:`~FinitePoset.random_order_ideal` | Return a random order ideal of ``self`` with uniform probability. :meth:`~FinitePoset.rank` | Return the rank of an element, or the rank of the poset. :meth:`~FinitePoset.rank_function` | Return a rank function of the poset, if it exists. - :meth:`~FinitePoset.unwrap` | Unwraps an element of this poset. + :meth:`~FinitePoset.unwrap` | Unwrap an element of this poset. :meth:`~FinitePoset.atkinson` | Return the `a`-spectrum of a poset whose undirected Hasse diagram is a forest. :meth:`~FinitePoset.spectrum` | Return the `a`-spectrum of this poset. @@ -363,21 +363,21 @@ def Poset(data=None, element_labels=None, cover_relations=False, linear_extensio 6. A previously constructed poset (the poset itself is returned). - - ``element_labels`` -- (default: ``None``); an optional list or - dictionary of objects that label the poset elements. + - ``element_labels`` -- (default: ``None``) an optional list or + dictionary of objects that label the poset elements - - ``cover_relations`` -- a boolean (default: ``False``); whether the + - ``cover_relations`` -- boolean (default: ``False``); whether the data can be assumed to describe a directed acyclic graph whose - arrows are cover relations; otherwise, the cover relations are + arrows are cover relations. Otherwise, the cover relations are first computed. - - ``linear_extension`` -- a boolean (default: ``False``); whether to + - ``linear_extension`` -- boolean (default: ``False``); whether to use the provided list of elements as default linear extension - for the poset; otherwise a linear extension is computed. If the data + for the poset. Otherwise a linear extension is computed. If the data is given as the pair ``(E, f)``, then ``E`` is taken to be the linear extension. - - ``facade`` -- a boolean or ``None`` (default); whether the + - ``facade`` -- boolean or ``None`` (default); whether the :meth:`Poset`'s elements should be wrapped to make them aware of the Poset they belong to. @@ -713,7 +713,7 @@ def Poset(data=None, element_labels=None, cover_relations=False, linear_extensio elif isinstance(data, DiGraph): # type 4 D = data.copy(immutable=True) elif isinstance(data, dict): # type 3: dictionary of upper covers - D = DiGraph(data, format="dict_of_lists") + D = DiGraph(data, format='dict_of_lists') elif isinstance(data, (list, tuple)): # types 1, 2, 3 (list/tuple) if len(data) == 2: # types 1 or 2 if callable(data[1]): # type 2 @@ -736,7 +736,7 @@ def Poset(data=None, element_labels=None, cover_relations=False, linear_extensio vertices = range(len(data)) D = DiGraph({v: [u for u in cov if u != v] for v, cov in zip(vertices, data)}, - format="dict_of_lists") + format='dict_of_lists') else: raise ValueError("not valid poset data") @@ -796,9 +796,9 @@ class FinitePoset(UniqueRepresentation, Parent): then ``elements`` is considered as a specified linear extension of the poset and the `linear_extension` attribute is set. - - ``category`` -- :class:`FinitePosets`, or a subcategory thereof. + - ``category`` -- :class:`FinitePosets`, or a subcategory thereof - - ``facade`` -- a boolean or ``None`` (default); whether the + - ``facade`` -- boolean or ``None`` (default); whether the :class:`~sage.combinat.posets.posets.FinitePoset`'s elements should be wrapped to make them aware of the Poset they belong to. @@ -817,7 +817,7 @@ class FinitePoset(UniqueRepresentation, Parent): :class:`~sage.combinat.posets.posets.FinitePoset`, itself built with ``facade = False``) - - ``key`` -- any hashable value (default: ``None``). + - ``key`` -- any hashable value (default: ``None``) EXAMPLES:: @@ -956,7 +956,7 @@ class contains. For example, for this class, ``FinitePoset``, @staticmethod def __classcall__(cls, hasse_diagram, elements=None, category=None, facade=None, key=None): """ - Normalizes the arguments passed to the constructor. + Normalize the arguments passed to the constructor. INPUT: @@ -998,7 +998,7 @@ def __classcall__(cls, hasse_diagram, elements=None, category=None, facade=None, hasse_diagram = poset._hasse_diagram.relabel(relabel, inplace=False) hasse_diagram = hasse_diagram.copy(immutable=True) else: - hasse_diagram = HasseDiagram(hasse_diagram, data_structure="static_sparse") + hasse_diagram = HasseDiagram(hasse_diagram, data_structure='static_sparse') if facade is None: facade = True if elements is not None: @@ -1081,7 +1081,7 @@ def __init__(self, hasse_diagram, elements, category, facade, key) -> None: # So range(len(D)) becomes a linear extension of the poset. rdict = {element: i for i, element in enumerate(self._elements)} self._hasse_diagram = HasseDiagram(hasse_diagram.relabel(rdict, inplace=False), - data_structure="static_sparse") + data_structure='static_sparse') self._element_to_vertex_dict = rdict self._is_facade = facade @@ -1279,7 +1279,7 @@ def __contains__(self, x) -> bool: def _element_constructor_(self, element): """ - Constructs an element of ``self`` + Construct an element of ``self``. EXAMPLES:: @@ -1316,7 +1316,7 @@ def _element_constructor_(self, element): def __call__(self, element): """ - Creates elements of this poset + Create elements of this poset. This overrides the generic call method for all parents :meth:`Parent.__call__`, as a work around to allow for facade @@ -1370,7 +1370,7 @@ def hasse_diagram(self): [1, 3, 5, 15] sage: H.edges(sort=True) [(1, 3, None), (1, 5, None), (3, 15, None), (5, 15, None)] - sage: H.set_latex_options(format="dot2tex") # needs sage.plot + sage: H.set_latex_options(format='dot2tex') # needs sage.plot sage: view(H) # optional - dot2tex, not tested (opens external window) """ G = DiGraph(self._hasse_diagram).relabel(self._list, inplace=False) @@ -1427,7 +1427,7 @@ def _repr_(self): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -1472,7 +1472,7 @@ def _rich_repr_(self, display_manager, **kwds): def __iter__(self): """ - Iterates through the elements of a linear extension of the poset. + Iterate through the elements of a linear extension of the poset. EXAMPLES:: @@ -1488,12 +1488,12 @@ def sorted(self, l, allow_incomparable=True, remove_duplicates=False): INPUT: - - ``l`` -- a list of elements of the poset - - ``allow_incomparable`` -- a Boolean. If ``True`` (the default), - return incomparable elements in some order; if ``False``, raise + - ``l`` -- list of elements of the poset + - ``allow_incomparable`` -- boolean (default: ``True``); if ``True``, + return incomparable elements in some order. If ``False``, raise an error if ``l`` is not a chain of the poset. - - ``remove_duplicates`` -- a Boolean. If ``True``, remove duplicates - from the output list. + - ``remove_duplicates`` -- boolean (default: ``False``); if ``True``, + remove duplicates from the output list EXAMPLES:: @@ -1553,9 +1553,8 @@ def linear_extension(self, linear_extension=None, check=True): - ``linear_extension`` -- (default: ``None``) a list of the elements of ``self`` - - ``check`` -- a boolean (default: ``True``); - whether to check that ``linear_extension`` is indeed a - linear extension of ``self``. + - ``check`` -- boolean (default: ``True``); whether to check that + ``linear_extension`` is indeed a linear extension of ``self`` EXAMPLES:: @@ -1610,10 +1609,10 @@ def linear_extensions(self, facade=False): INPUT: - - ``facade`` -- a boolean (default: ``False``); - whether to return the linear extensions as plain lists + - ``facade`` -- boolean (default: ``False``); whether to return the + linear extensions as plain lists - .. warning:: + .. WARNING:: The ``facade`` option is not yet fully functional:: @@ -1740,7 +1739,7 @@ def atkinson(self, a): Given an element `a` in a poset `P`, the `a`-spectrum is the list of integers whose `i`-th term contains the number of linear extensions of - `P` with element `a` located in the i-th position. + `P` with element `a` located in the `i`-th position. INPUT: @@ -1748,9 +1747,7 @@ def atkinson(self, a): - ``a`` -- an element of the poset - OUTPUT: - - The `a`-spectrum of this poset, returned as a list. + OUTPUT: the `a`-spectrum of this poset, returned as a list EXAMPLES:: @@ -1830,7 +1827,7 @@ def is_linear_extension(self, l) -> bool: INPUT: - - ``l`` -- a list (or iterable) containing all of the elements of ``self`` exactly once + - ``l`` -- list (or iterable) containing all of the elements of ``self`` exactly once EXAMPLES:: @@ -1908,27 +1905,27 @@ def plot(self, label_elements=True, element_labels=None, - Options to change element look: - * ``element_colors`` -- a dictionary where keys are colors and values + * ``element_colors`` -- dictionary where keys are colors and values are lists of elements * ``element_color`` -- a color for elements not set in ``element_colors`` * ``element_shape`` -- the shape of elements, like ``'s'`` for square; see https://matplotlib.org/api/markers_api.html for the list - * ``element_size`` (default: 200) - the size of elements - * ``label_elements`` (default: ``True``) - whether to display + * ``element_size`` -- (default: 200) the size of elements + * ``label_elements`` -- boolean (default: ``True``); whether to display element labels - * ``element_labels`` (default: ``None``) - a dictionary where keys + * ``element_labels`` (default: ``None``); a dictionary where keys are elements and values are labels to show - Options to change cover relation look: - * ``cover_colors`` -- a dictionary where keys are colors and values + * ``cover_colors`` -- dictionary where keys are colors and values are lists of cover relations given as pairs of elements * ``cover_color`` -- a color for elements not set in ``cover_colors`` * ``cover_style`` -- style for cover relations: ``'solid'``, ``'dashed'``, ``'dotted'`` or ``'dashdot'`` - * ``cover_labels`` -- a dictionary, list or function representing + * ``cover_labels`` -- dictionary, list or function representing labels of the covers of the poset. When set to ``None`` (default) no label is displayed on the edges of the Hasse Diagram. * ``cover_labels_background`` -- a background color for cover @@ -1937,11 +1934,11 @@ def plot(self, label_elements=True, element_labels=None, - Options to change overall look: - * ``figsize`` (default: 8) - size of the whole plot + * ``figsize`` -- (default: 8) size of the whole plot * ``title`` -- a title for the plot * ``fontsize`` -- fontsize for the title - * ``border`` (default: ``False``) - whether to draw a border over the - plot + * ``border`` -- (default: ``False``) whether to draw a border over + the plot .. NOTE:: @@ -2111,15 +2108,14 @@ def show(self, label_elements=True, element_labels=None, INPUT: - - ``label_elements`` (default: ``True``) -- whether to display + - ``label_elements`` -- boolean (default: ``True``); whether to display element labels - - ``element_labels`` (default: ``None``) -- a dictionary of - element labels + - ``element_labels`` -- dictionary (default: ``None``) of element labels - - ``cover_labels`` -- a dictionary, list or function representing labels - of the covers of ``self``. When set to ``None`` (default) no label is - displayed on the edges of the Hasse Diagram. + - ``cover_labels`` -- dictionary, list or function representing labels + of the covers of ``self``; when set to ``None`` (default) no label is + displayed on the edges of the Hasse Diagram .. NOTE:: @@ -2202,7 +2198,7 @@ def cover_relations(self): """ return list(self.cover_relations_iterator()) - @combinatorial_map(name="cover_relations_graph") + @combinatorial_map(name='cover_relations_graph') def cover_relations_graph(self): """ Return the (undirected) graph of cover relations. @@ -2305,9 +2301,7 @@ def diamonds(self): Thus each edge represents a cover relation in the Hasse diagram. We represent this as the tuple `(w, x, y, z)`. - OUTPUT: - - A tuple with + OUTPUT: a tuple with - a list of all diamonds in the Hasse Diagram, - a boolean checking that every `w,x,y` that form a ``V``, there is a @@ -2545,9 +2539,7 @@ def intervals_poset(self): r""" Return the natural partial order on the set of intervals of the poset. - OUTPUT: - - a finite poset + OUTPUT: a finite poset The poset of intervals of a poset `P` has the set of intervals `[x,y]` in `P` as elements, endowed with the order relation defined by @@ -2599,7 +2591,7 @@ def intervals_poset(self): covers.extend([[(a, b), (aa, b)] for aa in self.upper_covers(a) if self.le(aa, b)]) - dg = DiGraph([ints, covers], format="vertices_and_edges") + dg = DiGraph([ints, covers], format='vertices_and_edges') return constructor(dg, cover_relations=True) def relations_iterator(self, strict=False): @@ -2611,9 +2603,8 @@ def relations_iterator(self, strict=False): INPUT: - - ``strict`` -- a boolean (default ``False``) if ``True``, returns - an iterator over relations `x < y`, excluding all - relations `x \leq x`. + - ``strict`` -- boolean (default: ``False``); if ``True``, return + an iterator over relations `x < y`, excluding all relations `x \leq x` OUTPUT: @@ -3153,7 +3144,7 @@ def height(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -3296,14 +3287,13 @@ def is_chain_of_poset(self, elms, ordered=False) -> bool: INPUT: - - ``elms`` -- a list or other iterable containing some elements + - ``elms`` -- list or other iterable containing some elements of the poset - - ``ordered`` -- a Boolean. If ``True``, then return ``True`` - only if elements in ``elms`` are strictly increasing in the - poset; this makes no sense if ``elms`` is a set. If ``False`` - (the default), then elements can be repeated and be in any - order. + - ``ordered`` -- boolean; if ``True``, then return ``True`` only if + elements in ``elms`` are strictly increasing in the poset. This makes + no sense if ``elms`` is a set. If ``False`` (the default), then + elements can be repeated and be in any order. EXAMPLES:: @@ -3531,11 +3521,11 @@ def dimension(self, certificate=False, *, solver=None, integrality_tolerance=1e- INPUT: - - ``certificate`` (boolean; default:``False``) -- whether to return an + - ``certificate`` -- boolean (default: ``False``); whether to return an integer (the dimension) or a certificate, i.e. a smallest set of - linear extensions. + linear extensions - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -3544,7 +3534,7 @@ def dimension(self, certificate=False, *, solver=None, integrality_tolerance=1e- :class:`MixedIntegerLinearProgram `. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` .. NOTE:: @@ -3653,7 +3643,7 @@ def dimension(self, certificate=False, *, solver=None, integrality_tolerance=1e- def init_LP(k, cycles, inc_P): r""" - Initialize a LP object with k colors and the constraints from 'cycles' + Initialize a LP object with k colors and the constraints from 'cycles'. sage: init_LP(1,2,3) # not tested """ @@ -3775,7 +3765,7 @@ def jump_number(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) Whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -3873,7 +3863,7 @@ def is_jump_critical(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -4313,9 +4303,7 @@ def coxeter_transformation(self): r""" Return the Coxeter transformation of the poset. - OUTPUT: - - a square matrix with integer coefficients + OUTPUT: a square matrix with integer coefficients The output is the matrix of the Auslander-Reiten translation acting on the Grothendieck group of the derived category of @@ -4348,9 +4336,7 @@ def coxeter_polynomial(self): """ Return the Coxeter polynomial of the poset. - OUTPUT: - - a polynomial in one variable + OUTPUT: a polynomial in one variable The output is the characteristic polynomial of the Coxeter transformation. This polynomial only depends on the derived @@ -4379,7 +4365,7 @@ def coxeter_smith_form(self, algorithm='singular'): INPUT: - - ``algorithm`` -- optional (default ``'singular'``), possible + - ``algorithm`` -- (default: ``'singular'``) possible values are ``'singular'``, ``'sage'``, ``'gap'``, ``'pari'``, ``'maple'``, ``'magma'``, ``'fricas'`` @@ -4387,9 +4373,7 @@ def coxeter_smith_form(self, algorithm='singular'): algorithm. Sage is rather slow, Singular is faster and Pari is fast at least for small sizes. - OUTPUT: - - - list of polynomials in one variable, each one dividing the next one + OUTPUT: list of polynomials in one variable, each one dividing the next one The output list is a refinement of the characteristic polynomial of the Coxeter transformation, which is its product. This list @@ -4482,7 +4466,7 @@ def is_meet_semilattice(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -4555,7 +4539,7 @@ def is_join_semilattice(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -4730,8 +4714,8 @@ def antichains(self, element_constructor=None): INPUT: - - ``element_constructor`` -- a function taking an iterable as - argument (default: ``list``) + - ``element_constructor`` -- a function taking an iterable as + argument (default: ``list``) OUTPUT: @@ -4821,7 +4805,7 @@ def width(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -5258,9 +5242,7 @@ def factor(self): Cartesian products) is unique up to reordering and isomorphism. - OUTPUT: - - a list of posets + OUTPUT: list of posets EXAMPLES:: @@ -5380,7 +5362,7 @@ def disjoint_union(self, other, labels='pairs'): INPUT: - - ``other``, a poset. + - ``other`` -- poset - ``labels`` -- (defaults to 'pairs') If set to 'pairs', each element ``v`` in this poset will be named ``(0,v)`` and each @@ -5544,7 +5526,7 @@ def ordinal_sum(self, other, labels='pairs'): INPUT: - - ``other``, a poset. + - ``other`` -- poset - ``labels`` -- (defaults to 'pairs') If set to 'pairs', each element ``v`` in this poset will be named ``(0,v)`` and each @@ -5646,9 +5628,9 @@ def star_product(self, other, labels='pairs'): INPUT: - - ``other`` -- a poset. + - ``other`` -- a poset - - ``labels`` -- (defaults to 'pairs') If set to 'pairs', each + - ``labels`` -- string (default: ``'pairs'``); if set to 'pairs', each element ``v`` in this poset will be named ``(0, v)`` and each element ``u`` in ``other`` will be named ``(1, u)`` in the result. If set to 'integers', the elements of the result @@ -5877,7 +5859,7 @@ def with_bounds(self, labels=('bottom', 'top')): INPUT: - - ``labels`` -- A pair of elements to use as a bottom and top + - ``labels`` -- a pair of elements to use as a bottom and top element of the poset. Default is strings ``'bottom'`` and ``'top'``. Either of them can be ``None``, and then a new bottom or top element will not be added. @@ -6021,7 +6003,7 @@ def without_bounds(self): This is useful as an input for the method :meth:`order_complex`. If there is either no top or no bottom element, this - raises a :class:`TypeError`. + raises a :exc:`TypeError`. EXAMPLES:: @@ -6340,7 +6322,7 @@ def with_linear_extension(self, linear_extension): category=self.category(), facade=self._is_facade) - def graphviz_string(self, graph_string="graph", edge_string="--"): + def graphviz_string(self, graph_string='graph', edge_string='--'): r""" Return a representation in the DOT language, ready to render in graphviz. @@ -7105,11 +7087,9 @@ def order_complex(self, on_ints=False): INPUT: - - ``on_ints`` -- a boolean (default: ``False``) + - ``on_ints`` -- boolean (default: ``False``) - OUTPUT: - - an order complex of type :class:`SimplicialComplex` + OUTPUT: an order complex of type :class:`SimplicialComplex` EXAMPLES:: @@ -7306,9 +7286,7 @@ def M_triangle(self): The poset is expected to be graded. - OUTPUT: - - an :class:`~sage.combinat.triangles_FHM.M_triangle` + OUTPUT: an :class:`~sage.combinat.triangles_FHM.M_triangle` The M-triangle is the generating polynomial of the Möbius numbers @@ -7353,7 +7331,7 @@ def f_polynomial(self): The coefficient of `q^i` is the number of chains of `i+1` elements containing both bounds of the poset. - .. note:: + .. NOTE:: This is slightly different from the ``fPolynomial`` method in Macaulay2. @@ -7668,7 +7646,7 @@ def chain_polynomial(self): elements in the poset. List of coefficients of this polynomial is also called a *f-vector* of the poset. - .. note:: + .. NOTE:: This is not what has been called the chain polynomial in [St1986]_. The latter is identical with the order @@ -7785,11 +7763,9 @@ def promotion(self, i=1): INPUT: - - ``i`` -- an integer between `1` and `n` (default: `1`) + - ``i`` -- integer between `1` and `n` (default: `1`) - OUTPUT: - - - an isomorphic poset, with the same default linear extension + OUTPUT: an isomorphic poset, with the same default linear extension The extended promotion is defined on a poset ``self`` of size `n` by applying the promotion operator `\tau_i \tau_{i+1} @@ -7871,9 +7847,7 @@ def evacuation(self): Compute evacuation on the linear extension associated to the poset ``self``. - OUTPUT: - - - an isomorphic poset, with the same default linear extension + OUTPUT: an isomorphic poset, with the same default linear extension Evacuation is defined on a poset ``self`` of size `n` by applying the evacuation operator @@ -7988,7 +7962,7 @@ def is_slender(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -8103,9 +8077,9 @@ def is_eulerian(self, k=None, certificate=False): INPUT: - - ``k``, an integer -- only check if the poset is `k`-eulerian. + - ``k`` -- integer; only check if the poset is `k`-eulerian. If ``None`` (the default), check if the poset is Eulerian. - - ``certificate``, a Boolean -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -8215,7 +8189,7 @@ def is_greedy(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) whether to return + - ``certificate`` -- boolean (default: ``False``); whether to return a certificate OUTPUT: @@ -8393,7 +8367,7 @@ def frank_network(self): for i in self: pdict[(0, i)] = [(1, j) for j in self if self.ge(i, j)] pdict[(1, i)] = [(2, 0)] - G = DiGraph(pdict, format="dict_of_lists") + G = DiGraph(pdict, format='dict_of_lists') a = {e: 0 for e in G.edge_iterator(labels=False)} for i in self: a[((0, i), (1, i))] = 1 @@ -8607,7 +8581,7 @@ def cuts(self): from sage.graphs.graph import Graph from sage.graphs.independent_sets import IndependentSets auxg = Graph({(u, 0): [(v, 1) for v in self if not self.ge(u, v)] - for u in self}, format="dict_of_lists") + for u in self}, format='dict_of_lists') auxg.add_vertices([(v, 1) for v in self]) return [frozenset([xa for xa, xb in c if xb == 0]) for c in IndependentSets(auxg, maximal=True)] @@ -8621,9 +8595,7 @@ def completion_by_cuts(self): See the :wikipedia:`Dedekind-MacNeille completion`. - OUTPUT: - - - a finite lattice + OUTPUT: a finite lattice EXAMPLES:: @@ -8660,9 +8632,7 @@ def incidence_algebra(self, R, prefix='I'): r""" Return the incidence algebra of ``self`` over ``R``. - OUTPUT: - - An instance of :class:`sage.combinat.posets.incidence_algebras.IncidenceAlgebra`. + OUTPUT: an instance of :class:`sage.combinat.posets.incidence_algebras.IncidenceAlgebra` EXAMPLES:: @@ -8815,7 +8785,7 @@ def is_induced_subposet(self, other): INPUT: - - ``other``, a poset. + - ``other`` -- poset .. NOTE:: @@ -8997,7 +8967,7 @@ def cardinality(self, from_iterator=False): r""" Return the cardinality of this object. - .. note:: + .. NOTE:: By default, this returns pre-computed values obtained from the On-Line Encyclopedia of Integer Sequences (:oeis:`A000112`). diff --git a/src/sage/combinat/q_analogues.py b/src/sage/combinat/q_analogues.py index a5e8bb2e1ce..8bde8028ae2 100644 --- a/src/sage/combinat/q_analogues.py +++ b/src/sage/combinat/q_analogues.py @@ -105,7 +105,7 @@ def q_factorial(n, q=None): sage: q_factorial(3, p) p^3 + 2*p^2 + 2*p + 1 - The `q`-analogue of `n!` is only defined for `n` a non-negative + The `q`-analogue of `n!` is only defined for `n` a nonnegative integer (:issue:`11411`):: sage: q_factorial(-2) @@ -289,9 +289,9 @@ def q_binomial(n, k, q=None, algorithm='auto'): Check that arbitrary polynomials work:: sage: R. = ZZ[] - sage: q_binomial(2, 1, x^2 - 1, algorithm="naive") + sage: q_binomial(2, 1, x^2 - 1, algorithm='naive') x^2 - sage: q_binomial(2, 1, x^2 - 1, algorithm="cyclotomic") + sage: q_binomial(2, 1, x^2 - 1, algorithm='cyclotomic') x^2 Check that the parent is always the parent of ``q``:: @@ -305,7 +305,7 @@ def q_binomial(n, k, q=None, algorithm='auto'): :: - sage: q_binomial(2, 1, x^2 - 1, algorithm="quantum") + sage: q_binomial(2, 1, x^2 - 1, algorithm='quantum') Traceback (most recent call last): ... ValueError: unknown algorithm 'quantum' @@ -470,9 +470,9 @@ def q_catalan_number(n, q=None, m=1): INPUT: - - ``q`` -- optional variable + - ``q`` -- (optional) variable - - ``m`` -- (optional integer) to get instead the ``m``-Fuss-Catalan numbers + - ``m`` -- (optional) integer; to get instead the ``m``-Fuss-Catalan numbers If `q` is unspecified, then it defaults to using the generator `q` for a univariate polynomial ring over the integers. @@ -646,8 +646,7 @@ def q_jordan(t, q=None): INPUT: - - ``t`` -- an integer partition, or an argument accepted by - :class:`Partition` + - ``t`` -- integer partition, or an argument accepted by :class:`Partition` - ``q`` -- (default: ``None``) the variable `q`; if ``None``, then use a default variable in `\ZZ[q]` @@ -871,9 +870,9 @@ def q_stirling_number1(n, k, q=None): INPUT: - - ``n``, ``k`` -- integers with ``1 <= k <= n`` + - ``n``, ``k`` -- integers with `1 \leq k \leq n` - - ``q`` -- optional variable (default `q`) + - ``q`` -- variable (default: `q`) OUTPUT: a polynomial in the variable `q` @@ -937,9 +936,9 @@ def q_stirling_number2(n, k, q=None): INPUT: - - ``n``, ``k`` -- integers with ``1 <= k <= n`` + - ``n``, ``k`` -- integers with `1 \leq k \leq n` - - ``q`` -- optional variable (default `q`) + - ``q`` -- variable (default: `q`) OUTPUT: a polynomial in the variable `q` @@ -1002,7 +1001,7 @@ def number_of_irreducible_polynomials(n, q=None, m=1): - ``n`` -- positive integer - ``q`` -- ``None`` (default) or a prime power - - ``m`` -- positive integer (default `1`) + - ``m`` -- positive integer (default: `1`) OUTPUT: integer or integer-valued polynomial over `\QQ` diff --git a/src/sage/combinat/q_bernoulli.pyx b/src/sage/combinat/q_bernoulli.pyx index 854a80190f3..aa1d1ef42a1 100644 --- a/src/sage/combinat/q_bernoulli.pyx +++ b/src/sage/combinat/q_bernoulli.pyx @@ -17,9 +17,9 @@ def q_bernoulli(m, p=None): INPUT: - - `m` -- a nonnegative integer + - ``m`` -- nonnegative integer - - `p` (default: ``None``) -- an optional value for `q` + - ``p`` -- (default: ``None``) an optional value for `q` OUTPUT: @@ -87,11 +87,9 @@ def q_bernoulli_polynomial(m): INPUT: - - `m` -- a nonnegative integer + - ``m`` -- nonnegative integer - OUTPUT: - - A polynomial in one variable `x`. + OUTPUT: a polynomial in one variable `x` EXAMPLES:: diff --git a/src/sage/combinat/ranker.py b/src/sage/combinat/ranker.py index be78d89de53..873424268d3 100644 --- a/src/sage/combinat/ranker.py +++ b/src/sage/combinat/ranker.py @@ -22,15 +22,13 @@ def from_list(l): """ - Returns a ranker from the list l. + Return a ranker from the list l. INPUT: - - ``l`` -- a list + - ``l`` -- list - OUTPUT: - - - ``[rank, unrank]`` -- functions + OUTPUT: ``[rank, unrank]`` -- functions EXAMPLES:: @@ -71,7 +69,7 @@ def rank_from_list(l): sage: r('c') 2 - For non elements a :class:`ValueError` is raised, as with the usual + For non elements a :exc:`ValueError` is raised, as with the usual ``index`` method of lists:: sage: r('blah') @@ -109,7 +107,7 @@ def rank_from_list(l): def unrank_from_list(l): """ - Returns an unrank function from a list. + Return an unrank function from a list. EXAMPLES:: @@ -127,7 +125,7 @@ def unrank_from_list(l): def on_fly(): """ - Returns a pair of enumeration functions rank / unrank. + Return a pair of enumeration functions rank / unrank. rank assigns on the fly an integer, starting from 0, to any object passed as argument. The object should be hashable. unrank is the @@ -182,8 +180,8 @@ def unrank(L, i): INPUT: - - ``L`` -- a list, tuple, finite enumerated set, ... - - ``i`` -- an int or :class:`Integer` + - ``L`` -- list, tuple, finite enumerated set, etc. + - ``i`` -- integer The purpose of this utility is to give a uniform idiom to recover the `i`-th element of an object ``L``, whether ``L`` is a list, diff --git a/src/sage/combinat/recognizable_series.py b/src/sage/combinat/recognizable_series.py index 8194e695d13..d9e799607c9 100644 --- a/src/sage/combinat/recognizable_series.py +++ b/src/sage/combinat/recognizable_series.py @@ -100,7 +100,7 @@ def __init__(self, words): @classmethod def create_by_alphabet(cls, alphabet): r""" - A prefix-closed set + A prefix-closed set. This is a convenience method for the creation of prefix-closed sets by specifying an alphabet. @@ -121,11 +121,9 @@ def create_by_alphabet(cls, alphabet): def __repr__(self): r""" - A representation string of this prefix-closed set - - OUTPUT: + A representation string of this prefix-closed set. - A string + OUTPUT: string EXAMPLES:: @@ -144,9 +142,9 @@ def add(self, w, check=True): - ``w`` -- a word - - ``check`` -- boolean (default: ``True``). If set, then it is verified + - ``check`` -- boolean (default: ``True``); if set, then it is verified whether all proper prefixes of ``w`` are already in this - prefix-closed set. + prefix-closed set OUTPUT: @@ -179,9 +177,7 @@ def iterate_possible_additions(self): r""" Return an iterator over all elements including possible new elements. - OUTPUT: - - An iterator + OUTPUT: an iterator EXAMPLES:: @@ -261,9 +257,7 @@ def prefix_set(self): See also Proposition 2.3.1 of [BR2010a]_. - OUTPUT: - - A list + OUTPUT: list EXAMPLES:: @@ -294,9 +288,7 @@ def minimize_result(operation): - ``operation`` -- a method - OUTPUT: - - A method with the following additional argument: + OUTPUT: a method with the following additional argument: - ``minimize`` -- (default: ``None``) a boolean or ``None``. If ``True``, then :meth:`minimized` is called after the operation, @@ -566,12 +558,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. - - OUTPUT: + - ``latex`` -- boolean (default: ``False``); if set, then LaTeX-output + is returned - A string + OUTPUT: string EXAMPLES:: @@ -638,9 +628,7 @@ def _latex_(self): r""" A LaTeX-representation string for this recognizable series. - OUTPUT: - - A string + OUTPUT: string TESTS:: @@ -663,11 +651,11 @@ def coefficient_of_word(self, w, multiply_left=True, multiply_right=True): - ``w`` -- a word over the parent's :meth:`~RecognizableSeriesSpace.alphabet` - - ``multiply_left`` -- (default: ``True``) a boolean. If ``False``, - then multiplication by :meth:`left ` is skipped. + - ``multiply_left`` -- boolean (default: ``True``); if ``False``, + then multiplication by :meth:`left ` is skipped - - ``multiply_right`` -- (default: ``True``) a boolean. If ``False``, - then multiplication by :meth:`right ` is skipped. + - ``multiply_right`` -- boolean (default: ``True``); if ``False``, + then multiplication by :meth:`right ` is skipped OUTPUT: @@ -710,9 +698,7 @@ def _mu_of_empty_word_(self): r""" Return :meth:`mu ` applied on the empty word. - OUTPUT: - - A matrix + OUTPUT: a matrix TESTS:: @@ -748,9 +734,7 @@ def _mu_of_word_(self, w): - ``w`` -- a word over the parent's :meth:`~RecognizableSeriesSpace.alphabet` - OUTPUT: - - A matrix + OUTPUT: a matrix TESTS:: @@ -941,9 +925,7 @@ def __eq__(self, other): - ``other`` -- an object - OUTPUT: - - A boolean + OUTPUT: boolean .. NOTE:: @@ -995,9 +977,7 @@ def __ne__(self, other): - ``other`` -- an object - OUTPUT: - - A boolean + OUTPUT: boolean .. NOTE:: @@ -1022,9 +1002,7 @@ def transposed(self): r""" Return the transposed series. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` Each of the matrices in :meth:`mu ` is transposed. Additionally the vectors :meth:`left ` and :meth:`right ` are switched. @@ -1077,9 +1055,7 @@ def minimized(self): If this is not the case, then the coefficients are automatically coerced to their fraction field. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` ALGORITHM: @@ -1139,9 +1115,7 @@ def _minimized_right_(self): Return a recognizable series equivalent to this series, but with a right minimized linear representation. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` See :meth:`minimized` for details. @@ -1161,9 +1135,7 @@ def _minimized_left_(self): Return a recognizable series equivalent to this series, but with a left minimized linear representation. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` See :meth:`minimized` for details. @@ -1276,9 +1248,7 @@ def _add_(self, other): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RecognizableSeries`. + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: @@ -1315,9 +1285,7 @@ def _neg_(self): r""" Return the additive inverse of this recognizable series. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: @@ -1342,9 +1310,7 @@ def _rmul_(self, other): - ``other`` -- an element of the coefficient (semi-)ring - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: @@ -1406,9 +1372,7 @@ def _lmul_(self, other): - ``other`` -- an element of the coefficient (semi-)ring - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: @@ -1476,9 +1440,7 @@ def hadamard_product(self, other): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: @@ -1593,7 +1555,7 @@ class RecognizableSeriesSpace(UniqueRepresentation, Parent): - ``coefficient_ring`` -- a (semi-)ring - - ``alphabet`` -- a tuple, list or + - ``alphabet`` -- tuple, list or :class:`~sage.sets.totally_ordered_finite_set.TotallyOrderedFiniteSet`. If specified, then the ``indices`` are the finite words over this ``alphabet``. @@ -1670,7 +1632,7 @@ def __normalize__(cls, category=None, minimize_results=True): r""" - Normalizes the input in order to ensure a unique + Normalize the input in order to ensure a unique representation. For more information see :class:`RecognizableSeriesSpace`. @@ -1739,7 +1701,7 @@ def __init__(self, coefficient_ring, indices, category, minimize_results): - ``category`` -- (default: ``None``) the category of this space - - ``minimize_results`` -- (default: ``True``) a boolean. If set, then + - ``minimize_results`` -- boolean (default: ``True``); if set, then :meth:`RecognizableSeries.minimized` is automatically called after performing operations. @@ -1802,9 +1764,7 @@ def alphabet(self): r""" Return the alphabet of this recognizable series space. - OUTPUT: - - A totally ordered set + OUTPUT: a totally ordered set EXAMPLES:: @@ -1822,9 +1782,7 @@ def indices(self): r""" Return the indices of the recognizable series. - OUTPUT: - - The set of finite words over the alphabet + OUTPUT: the set of finite words over the alphabet EXAMPLES:: @@ -1871,9 +1829,7 @@ def _repr_(self): Return a representation string of this recognizable sequence space. - OUTPUT: - - A string + OUTPUT: string TESTS:: @@ -1888,9 +1844,7 @@ def _an_element_(self): r""" Return an element of this recognizable series space. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: @@ -1917,9 +1871,7 @@ def some_elements(self, **kwds): - ``kwds`` are passed on to the element constructor - OUTPUT: - - An iterator + OUTPUT: an iterator EXAMPLES:: @@ -2015,9 +1967,7 @@ def one_hadamard(self): :meth:`~RecognizableSeries.hadamard_product`, i.e. the coefficient-wise multiplication. - OUTPUT: - - A :class:`RecognizableSeries` + OUTPUT: a :class:`RecognizableSeries` EXAMPLES:: diff --git a/src/sage/combinat/regular_sequence.py b/src/sage/combinat/regular_sequence.py index 6822fc7dd3d..b57e5ccbf5b 100644 --- a/src/sage/combinat/regular_sequence.py +++ b/src/sage/combinat/regular_sequence.py @@ -98,15 +98,13 @@ def pad_right(T, length, zero=0): INPUT: - - ``T`` -- A tuple, list or other iterable + - ``T`` -- tuple, list or other iterable - - ``length`` -- a nonnegative integer + - ``length`` -- nonnegative integer - ``zero`` -- (default: ``0``) the elements to pad with - OUTPUT: - - An object of the same type as ``T`` + OUTPUT: an object of the same type as ``T`` EXAMPLES:: @@ -136,7 +134,7 @@ def value(D, k): INPUT: - - ``D`` -- a tuple or other iterable + - ``D`` -- tuple or other iterable - ``k`` -- the base @@ -201,11 +199,11 @@ def __init__(self, parent, mu, left=None, right=None): When created via the parent :class:`RegularSequenceRing`, then the following option is available. - - ``allow_degenerated_sequence`` -- (default: ``False``) a boolean. If set, then - there will be no check if the input is a degenerated sequence - (see :meth:`is_degenerated`). - Otherwise the input is checked and a :class:`DegeneratedSequenceError` - is raised if such a sequence is detected. + - ``allow_degenerated_sequence`` -- boolean (default: ``False``); if + set, then there will be no check if the input is a degenerated + sequence (see :meth:`is_degenerated`). Otherwise the input is checked + and a :exc:`DegeneratedSequenceError` is raised if such a sequence + is detected. EXAMPLES:: @@ -243,7 +241,7 @@ def _repr_(self): r""" Return a representation string of this `k`-regular sequence. - OUTPUT: a string + OUTPUT: string TESTS:: @@ -267,7 +265,7 @@ def coefficient_of_n(self, n, **kwds): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: an element of the universe of the sequence @@ -408,9 +406,7 @@ def regenerated(self): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` ALGORITHM: @@ -494,15 +490,13 @@ def transposed(self, allow_degenerated_sequence=False): INPUT: - - ``allow_degenerated_sequence`` -- (default: ``False``) a boolean. If set, then - there will be no check if the transposed sequence is a degenerated sequence - (see :meth:`is_degenerated`). - Otherwise the transposed sequence is checked and a :class:`DegeneratedSequenceError` + - ``allow_degenerated_sequence`` -- boolean (default: ``False``); if + set, then there will be no check if the transposed sequence is a + degenerated sequence (see :meth:`is_degenerated`). Otherwise the + transposed sequence is checked and a :exc:`DegeneratedSequenceError` is raised if such a sequence is detected. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` Each of the matrices in :meth:`mu ` is transposed. Additionally the vectors :meth:`left ` and :meth:`right ` are switched. @@ -551,9 +545,7 @@ def _minimized_right_(self): Return a regular sequence equivalent to this series, but with a right minimized linear representation. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` .. SEEALSO:: @@ -576,9 +568,9 @@ def subsequence(self, a, b): INPUT: - - ``a`` -- a nonnegative integer + - ``a`` -- nonnegative integer - - ``b`` -- an integer + - ``b`` -- integer Alternatively, this is allowed to be a dictionary `b_j \mapsto c_j`. If so and applied on `f(n)`, @@ -589,9 +581,7 @@ def subsequence(self, a, b): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` .. NOTE:: @@ -863,16 +853,14 @@ def shift_left(self, b=1, **kwds): INPUT: - - ``b`` -- an integer + - ``b`` -- integer - ``minimize`` -- (default: ``None``) a boolean or ``None``. If ``True``, then :meth:`~RecognizableSeries.minimized` is called after the operation, if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` .. NOTE:: @@ -909,16 +897,14 @@ def shift_right(self, b=1, **kwds): INPUT: - - ``b`` -- an integer + - ``b`` -- integer - ``minimize`` -- (default: ``None``) a boolean or ``None``. If ``True``, then :meth:`~RecognizableSeries.minimized` is called after the operation, if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` .. NOTE:: @@ -964,9 +950,7 @@ def backward_differences(self, **kwds): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` .. NOTE:: @@ -1005,9 +989,7 @@ def forward_differences(self, **kwds): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` EXAMPLES:: @@ -1047,9 +1029,7 @@ def _mul_(self, other): if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` ALGORITHM: @@ -1148,18 +1128,16 @@ def partial_sums(self, include_n=False): INPUT: - - ``include_n`` -- (default: ``False``) a boolean. If set, then + - ``include_n`` -- boolean (default: ``False``); if set, then the `n`-th entry of the result is the sum of the entries up - to index `n` (included). + to index `n` (included) - ``minimize`` -- (default: ``None``) a boolean or ``None``. If ``True``, then :meth:`~RecognizableSeries.minimized` is called after the operation, if ``False``, then not. If this argument is ``None``, then the default specified by the parent's ``minimize_results`` is used. - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` EXAMPLES:: @@ -1323,7 +1301,7 @@ class RegularSequenceRing(RecognizableSeriesSpace): INPUT: - - ``k`` -- an integer at least `2` specifying the base + - ``k`` -- integer at least `2` specifying the base - ``coefficient_ring`` -- a (semi-)ring @@ -1350,7 +1328,7 @@ def __normalize__(cls, k, category=None, **kwds): r""" - Normalizes the input in order to ensure a unique + Normalize the input in order to ensure a unique representation. For more information see :class:`RegularSequenceRing`. @@ -1378,7 +1356,7 @@ def __init__(self, k, *args, **kwds): INPUT: - - ``k`` -- an integer at least `2` specifying the base + - ``k`` -- integer at least `2` specifying the base Other input arguments are passed on to :meth:`~sage.combinat.recognizable_series.RecognizableSeriesSpace.__init__`. @@ -1422,7 +1400,7 @@ def _repr_(self): r""" Return a representation string of this `k`-regular sequence space. - OUTPUT: a string + OUTPUT: string TESTS:: @@ -1438,7 +1416,7 @@ def _n_to_index_(self, n): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: a word @@ -1499,9 +1477,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - OUTPUT: - - An iterator + OUTPUT: an iterator EXAMPLES:: @@ -1572,9 +1548,7 @@ def guess(self, f, n_verify=100, max_exponent=10, sequence=None): for bootstrapping the guessing by adding information of the linear representation of ``sequence`` to the guessed representation - OUTPUT: - - A :class:`RegularSequence` + OUTPUT: a :class:`RegularSequence` ALGORITHM: @@ -1592,7 +1566,7 @@ def guess(self, f, n_verify=100, max_exponent=10, sequence=None): Implicitly, the algorithm also maintains a `d \times n_\mathrm{verify}` matrix ``A`` (where ``d`` is the dimension of the right vector valued sequence) whose columns are the current right vector valued sequence evaluated at - the non-negative integers less than `n_\mathrm{verify}` and ensures that this + the nonnegative integers less than `n_\mathrm{verify}` and ensures that this matrix has full row rank. EXAMPLES: @@ -1901,7 +1875,7 @@ def some_inverse_U_matrix(lines): # see :issue:`35748` for details. for m_indices in cantor_product(xsrange(n_verify), repeat=d, min_slope=1): # Iterate over all increasing lists of length d consisting - # of non-negative integers less than `n_verify`. + # of nonnegative integers less than `n_verify`. U = Matrix(domain, d, d, [values(m, lines) for m in m_indices]).transpose() try: @@ -2031,7 +2005,7 @@ def from_recurrence(self, *args, **kwds): If the recurrence relations are represented by symbolic equations, then the following arguments are required: - - ``equations`` -- A list of equations where the elements have + - ``equations`` -- list of equations where the elements have either the form - `f(k^M n + r) = c_{r,l} f(k^m n + l) + c_{r,l + 1} f(k^m n @@ -2070,18 +2044,18 @@ def from_recurrence(self, *args, **kwds): see [HKL2022]_, Definition 3.1, as well as in the description of ``equations`` above - - ``coeffs`` -- a dictionary where ``coeffs[(r, j)]`` is the + - ``coeffs`` -- dictionary where ``coeffs[(r, j)]`` is the coefficient `c_{r,j}` as given in the description of ``equations`` above. If ``coeffs[(r, j)]`` is not given for some ``r`` and ``j``, then it is assumed to be zero. - - ``initial_values`` -- a dictionary mapping integers ``n`` to the + - ``initial_values`` -- dictionary mapping integers ``n`` to the ``n``-th value of the sequence Optional keyword-only argument: - - ``offset`` -- (default: ``0``) an integer. See explanation of - ``equations`` above. + - ``offset`` -- integer (default: `0`); see explanation of + ``equations`` above - ``inhomogeneities`` -- (default: ``{}``) a dictionary mapping integers ``r`` to the inhomogeneity `g_r` as given @@ -2261,7 +2235,7 @@ def from_recurrence(self, *args, **kwds): sage: (S - T).is_trivial_zero() # long time True - Zero-sequence with non-zero initial values:: + Zero-sequence with nonzero initial values:: sage: Seq2.from_recurrence([ ....: f(2*n) == 0, f(2*n + 1) == 0, @@ -2299,7 +2273,7 @@ def from_recurrence(self, *args, **kwds): True Connection between the Stern--Brocot sequence and the number - of non-zero elements in the generalized Pascal's triangle (see + of nonzero elements in the generalized Pascal's triangle (see [LRS2017]_):: sage: U = Seq2.from_recurrence(M=1, m=0, @@ -2361,9 +2335,9 @@ def __init__(self, k, coefficient_ring): INPUT: - - ``k`` -- an integer at least `2` specifying the base + - ``k`` -- integer at least `2` specifying the base - - ``coefficient_ring`` -- a ring. + - ``coefficient_ring`` -- a ring These are the same parameters used when creating a :class:`RegularSequenceRing`. @@ -3023,14 +2997,14 @@ def parse_direct_arguments(self, M, m, coeffs, initial_values): sage: RP.parse_direct_arguments(1, 1/2, {}, {}) Traceback (most recent call last): ... - ValueError: 1/2 is not a non-negative integer. + ValueError: 1/2 is not a nonnegative integer. :: sage: RP.parse_direct_arguments(1, -1, {}, {}) Traceback (most recent call last): ... - ValueError: -1 is not a non-negative integer. + ValueError: -1 is not a nonnegative integer. :: @@ -3093,7 +3067,7 @@ def parse_direct_arguments(self, M, m, coeffs, initial_values): raise ValueError("%s is not a positive integer." % (M,)) from None if m not in ZZ or m < 0: - raise ValueError("%s is not a non-negative integer." + raise ValueError("%s is not a nonnegative integer." % (m,)) from None if M <= m: raise ValueError("%s is not larger than %s." @@ -3158,16 +3132,16 @@ def parameters(self, M, m, coeffs, initial_values, offset=0, inhomogeneities={}) - ``ll``, ``uu``, ``n1``, ``dim`` -- parameters and dimension of the resulting linear representation, see [HKL2022]_, Theorem A - - ``coeffs`` -- a dictionary mapping ``(r, j)`` to the coefficients + - ``coeffs`` -- dictionary mapping ``(r, j)`` to the coefficients `c_{r, j}` as given in [HKL2022]_, Equation (3.1). If ``coeffs[(r, j)]`` is not given for some ``r`` and ``j``, then it is assumed to be zero. - - ``initial_values`` -- a dictionary mapping integers ``n`` to the + - ``initial_values`` -- dictionary mapping integers ``n`` to the ``n``-th value of the sequence - - ``inhomogeneities`` -- a dictionary mapping integers ``r`` - to the inhomogeneity `g_r` as given in [HKL2022]_, Corollary D. + - ``inhomogeneities`` -- dictionary mapping integers ``r`` + to the inhomogeneity `g_r` as given in [HKL2022]_, Corollary D EXAMPLES:: @@ -3350,19 +3324,19 @@ def values(self, *, M, m, l, u, ll, coeffs, - ``ll`` -- parameter of the resulting linear representation, see [HKL2022]_, Theorem A - - ``coeffs`` -- a dictionary where ``coeffs[(r, j)]`` is the + - ``coeffs`` -- dictionary where ``coeffs[(r, j)]`` is the coefficient `c_{r,j}` as given in :meth:`RegularSequenceRing.from_recurrence`. If ``coeffs[(r, j)]`` is not given for some ``r`` and ``j``, then it is assumed to be zero. - - ``initial_values`` -- a dictionary mapping integers ``n`` to the + - ``initial_values`` -- dictionary mapping integers ``n`` to the ``n``-th value of the sequence - ``last_value_needed`` -- last initial value which is needed to determine the linear representation - - ``inhomogeneities`` -- a dictionary mapping integers ``r`` - to the inhomogeneity `g_r` as given in [HKL2022]_, Corollary D. + - ``inhomogeneities`` -- dictionary mapping integers ``r`` + to the inhomogeneity `g_r` as given in [HKL2022]_, Corollary D OUTPUT: @@ -3552,10 +3526,10 @@ def ind(self, M, m, ll, uu): vice versa, i.e., - ``ind[i]`` -- a pair ``(j, d)`` representing the sequence `x(k^j n + d)` - in the `i`-th component (0-based) of the resulting linear representation, + in the `i`-th component (0-based) of the resulting linear representation - ``ind[(j, d)]`` -- the (0-based) row number of the sequence - `x(k^j n + d)` in the linear representation. + `x(k^j n + d)` in the linear representation EXAMPLES:: @@ -3718,7 +3692,7 @@ def v_eval_n(self, recurrence_rules, n): - ``recurrence_rules`` -- a namedtuple generated by :meth:`parameters` - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: a vector @@ -3776,9 +3750,9 @@ def matrix(self, recurrence_rules, rem, correct_offset=True): - ``recurrence_rules`` -- a namedtuple generated by :meth:`parameters` - - ``rem`` -- an integer between ``0`` and ``k - 1`` + - ``rem`` -- integer between `0` and `k - 1` - - ``correct_offset`` -- (default: ``True``) a boolean. If + - ``correct_offset`` -- boolean (default: ``True``); if ``True``, then the resulting linear representation has no offset. See [HKL2022]_ for more information. diff --git a/src/sage/combinat/ribbon_shaped_tableau.py b/src/sage/combinat/ribbon_shaped_tableau.py index aa896679492..d33cc115396 100644 --- a/src/sage/combinat/ribbon_shaped_tableau.py +++ b/src/sage/combinat/ribbon_shaped_tableau.py @@ -459,7 +459,6 @@ def __iter__(self): [[None, 2, 3], [1, 4]], [[None, 2, 4], [1, 3]], [[None, 1, 4], [2, 3]]] - """ for p in descents_composition_list(self.shape): yield self.from_permutation(p) diff --git a/src/sage/combinat/ribbon_tableau.py b/src/sage/combinat/ribbon_tableau.py index db82cbfd660..6a1643a46c7 100644 --- a/src/sage/combinat/ribbon_tableau.py +++ b/src/sage/combinat/ribbon_tableau.py @@ -58,7 +58,7 @@ class RibbonTableau(SkewTableau): 1 0 1 In the previous example, each ribbon is uniquely determined by a - non-zero entry. The 0 entries are used to fill in the rest of the + nonzero entry. The 0 entries are used to fill in the rest of the skew shape. .. NOTE:: @@ -164,14 +164,14 @@ class RibbonTableaux(UniqueRepresentation, Parent): INPUT(Optional): - - ``shape`` -- skew shape as a list of lists or an object of type + - ``shape`` -- skew shape as a list of lists or an object of type SkewPartition - - ``length`` -- integer, ``shape`` is partitioned into ribbons of + - ``length`` -- integer; ``shape`` is partitioned into ribbons of length ``length`` - - ``weight`` -- list of integers, computed from the values of - non-zero entries labeling the ribbons + - ``weight`` -- list of integers; computed from the values of + nonzero entries labeling the ribbons EXAMPLES:: @@ -413,13 +413,13 @@ def insertion_tableau(skp, perm, evaluation, tableau, length): """ INPUT: - - ``skp`` -- skew partitions + - ``skp`` -- skew partitions - - ``perm, evaluation`` -- non-negative integers + - ``perm, evaluation`` -- nonnegative integers - - ``tableau`` -- skew tableau + - ``tableau`` -- skew tableau - - ``length`` -- integer + - ``length`` -- integer TESTS:: @@ -480,11 +480,11 @@ def count_rec(nexts, current, part, weight, length): """ INPUT: - - ``nexts, current, part`` -- skew partitions + - ``nexts, current, part`` -- skew partitions - - ``weight`` -- non-negative integer list + - ``weight`` -- nonnegative integer list - - ``length`` -- integer + - ``length`` -- integer TESTS:: @@ -516,11 +516,11 @@ def list_rec(nexts, current, part, weight, length): """ INPUT: - - ``nexts, current, part`` -- skew partitions + - ``nexts, current, part`` -- skew partitions - - ``weight`` -- non-negative integer list + - ``weight`` -- nonnegative integer list - - ``length`` -- integer + - ``length`` -- integer TESTS:: @@ -575,11 +575,11 @@ def spin_rec(t, nexts, current, part, weight, length): INPUT: - - ``weight`` -- list of non-negative integers + - ``weight`` -- list of nonnegative integers - - ``length`` -- the length of the ribbons we're tiling with + - ``length`` -- the length of the ribbons we're tiling with - - ``t`` -- the variable + - ``t`` -- the variable EXAMPLES:: @@ -620,7 +620,7 @@ def spin_rec(t, nexts, current, part, weight, length): def spin_polynomial_square(part, weight, length): r""" - Returns the spin polynomial associated with ``part``, ``weight``, and + Return the spin polynomial associated with ``part``, ``weight``, and ``length``, with the substitution `t \to t^2` made. EXAMPLES:: @@ -658,7 +658,7 @@ def spin_polynomial_square(part, weight, length): def spin_polynomial(part, weight, length): """ - Returns the spin polynomial associated to ``part``, ``weight``, and + Return the spin polynomial associated to ``part``, ``weight``, and ``length``. EXAMPLES:: diff --git a/src/sage/combinat/rigged_configurations/bij_abstract_class.py b/src/sage/combinat/rigged_configurations/bij_abstract_class.py index 520ce241d57..e22c657d672 100644 --- a/src/sage/combinat/rigged_configurations/bij_abstract_class.py +++ b/src/sage/combinat/rigged_configurations/bij_abstract_class.py @@ -52,7 +52,7 @@ def __init__(self, tp_krt): INPUT: - - ``parent`` -- The parent of tensor product of KR tableaux + - ``parent`` -- the parent of tensor product of KR tableaux EXAMPLES:: @@ -99,9 +99,9 @@ def run(self, verbose=False): INPUT: - - ``tp_krt`` -- A tensor product of KR tableaux + - ``tp_krt`` -- a tensor product of KR tableaux - - ``verbose`` -- (Default: ``False``) Display each step in the + - ``verbose`` -- (default: ``False``) display each step in the bijection EXAMPLES:: @@ -177,7 +177,7 @@ def next_state(self, val): INPUT: - - ``val`` -- The value we are adding + - ``val`` -- the value we are adding TESTS:: @@ -210,7 +210,7 @@ def _update_vacancy_nums(self, a): INPUT: - - ``a`` -- The index of the partition to update + - ``a`` -- the index of the partition to update TESTS:: @@ -250,7 +250,7 @@ def _update_partition_values(self, a): INPUT: - - ``a`` -- The index of the partition to update + - ``a`` -- the index of the partition to update TESTS:: @@ -308,7 +308,7 @@ def __init__(self, RC_element): INPUT: - - ``RC_element`` -- The rigged configuration + - ``RC_element`` -- the rigged configuration EXAMPLES:: @@ -361,9 +361,9 @@ def run(self, verbose=False, build_graph=False): INPUT: - - ``verbose`` -- (default: ``False``) display each step in the + - ``verbose`` -- boolean (default: ``False``); display each step in the bijection - - ``build_graph`` -- (default: ``False``) build the graph of each + - ``build_graph`` -- boolean (default: ``False``); build the graph of each step of the bijection EXAMPLES:: @@ -440,9 +440,9 @@ def run(self, verbose=False, build_graph=False): self._graph.pop(0) # Remove the dummy at the start from sage.graphs.digraph import DiGraph from sage.graphs.dot2tex_utils import have_dot2tex - self._graph = DiGraph(self._graph, format="list_of_edges") + self._graph = DiGraph(self._graph, format='list_of_edges') if have_dot2tex(): - self._graph.set_latex_options(format="dot2tex", edge_labels=True) + self._graph.set_latex_options(format='dot2tex', edge_labels=True) return self.KRT(pathlist=ret_crystal_path) @abstract_method @@ -471,7 +471,7 @@ def _update_vacancy_numbers(self, a): INPUT: - - ``a`` -- The index of the partition to update + - ``a`` -- the index of the partition to update TESTS:: @@ -513,9 +513,9 @@ def _find_singular_string(self, partition, last_size): INPUT: - - ``partition`` -- The partition to look in + - ``partition`` -- the partition to look in - - ``last_size`` -- The last size found + - ``last_size`` -- the last size found TESTS:: diff --git a/src/sage/combinat/rigged_configurations/bij_type_B.py b/src/sage/combinat/rigged_configurations/bij_type_B.py index 51fd8f198bc..d511ae76a2e 100644 --- a/src/sage/combinat/rigged_configurations/bij_type_B.py +++ b/src/sage/combinat/rigged_configurations/bij_type_B.py @@ -54,9 +54,9 @@ def run(self, verbose=False): INPUT: - - ``tp_krt`` -- A tensor product of KR tableaux + - ``tp_krt`` -- a tensor product of KR tableaux - - ``verbose`` -- (Default: ``False``) Display each step in the + - ``verbose`` -- (default: ``False``) display each step in the bijection EXAMPLES:: @@ -553,9 +553,9 @@ def run(self, verbose=False, build_graph=False): INPUT: - - ``verbose`` -- (default: ``False``) display each step in the + - ``verbose`` -- boolean (default: ``False``); display each step in the bijection - - ``build_graph`` -- (default: ``False``) build the graph of each + - ``build_graph`` -- boolean (default: ``False``); build the graph of each step of the bijection EXAMPLES:: @@ -739,7 +739,7 @@ def run(self, verbose=False, build_graph=False): from sage.graphs.dot2tex_utils import have_dot2tex self._graph = DiGraph(self._graph) if have_dot2tex(): - self._graph.set_latex_options(format="dot2tex", edge_labels=True) + self._graph.set_latex_options(format='dot2tex', edge_labels=True) return self.KRT(pathlist=ret_crystal_path) diff --git a/src/sage/combinat/rigged_configurations/bij_type_D.py b/src/sage/combinat/rigged_configurations/bij_type_D.py index ab9b41b89bd..e1d84d29e4b 100644 --- a/src/sage/combinat/rigged_configurations/bij_type_D.py +++ b/src/sage/combinat/rigged_configurations/bij_type_D.py @@ -56,9 +56,9 @@ def run(self, verbose=False): INPUT: - - ``tp_krt`` -- A tensor product of KR tableaux + - ``tp_krt`` -- a tensor product of KR tableaux - - ``verbose`` -- (Default: ``False``) Display each step in the + - ``verbose`` -- (default: ``False``) display each step in the bijection EXAMPLES:: @@ -425,9 +425,9 @@ def run(self, verbose=False, build_graph=False): INPUT: - - ``verbose`` -- (default: ``False``) display each step in the + - ``verbose`` -- boolean (default: ``False``); display each step in the bijection - - ``build_graph`` -- (default: ``False``) build the graph of each + - ``build_graph`` -- boolean (default: ``False``); build the graph of each step of the bijection EXAMPLES:: @@ -546,9 +546,9 @@ def run(self, verbose=False, build_graph=False): self._graph.pop(0) # Remove the dummy at the start from sage.graphs.digraph import DiGraph from sage.graphs.dot2tex_utils import have_dot2tex - self._graph = DiGraph(self._graph, format="list_of_edges") + self._graph = DiGraph(self._graph, format='list_of_edges') if have_dot2tex(): - self._graph.set_latex_options(format="dot2tex", edge_labels=True) + self._graph.set_latex_options(format='dot2tex', edge_labels=True) return self.KRT(pathlist=ret_crystal_path) diff --git a/src/sage/combinat/rigged_configurations/bij_type_D_twisted.py b/src/sage/combinat/rigged_configurations/bij_type_D_twisted.py index ce177ffb468..7d1edfb278a 100644 --- a/src/sage/combinat/rigged_configurations/bij_type_D_twisted.py +++ b/src/sage/combinat/rigged_configurations/bij_type_D_twisted.py @@ -59,9 +59,9 @@ def run(self, verbose=False): INPUT: - - ``tp_krt`` -- A tensor product of KR tableaux + - ``tp_krt`` -- a tensor product of KR tableaux - - ``verbose`` -- (Default: ``False``) Display each step in the + - ``verbose`` -- (default: ``False``) display each step in the bijection EXAMPLES:: @@ -322,9 +322,9 @@ def run(self, verbose=False, build_graph=False): INPUT: - - ``verbose`` -- (default: ``False``) display each step in the + - ``verbose`` -- boolean (default: ``False``); display each step in the bijection - - ``build_graph`` -- (default: ``False``) build the graph of each + - ``build_graph`` -- boolean (default: ``False``); build the graph of each step of the bijection EXAMPLES:: @@ -424,7 +424,7 @@ def run(self, verbose=False, build_graph=False): from sage.graphs.dot2tex_utils import have_dot2tex self._graph = DiGraph(self._graph) if have_dot2tex(): - self._graph.set_latex_options(format="dot2tex", edge_labels=True) + self._graph.set_latex_options(format='dot2tex', edge_labels=True) return self.KRT(pathlist=ret_crystal_path) diff --git a/src/sage/combinat/rigged_configurations/kleber_tree.py b/src/sage/combinat/rigged_configurations/kleber_tree.py index c3a2bbeaf0a..e82b6c28035 100644 --- a/src/sage/combinat/rigged_configurations/kleber_tree.py +++ b/src/sage/combinat/rigged_configurations/kleber_tree.py @@ -4,7 +4,7 @@ A Kleber tree is a tree of weights generated by Kleber's algorithm [Kleber1]_. The nodes correspond to the weights in the positive Weyl chamber -obtained by subtracting a (non-zero) positive root. The edges are labeled by +obtained by subtracting a (nonzero) positive root. The edges are labeled by the coefficients of the roots of the difference. AUTHORS: @@ -216,10 +216,10 @@ class KleberTreeNode(Element): INPUT: - - ``parent_obj`` -- The parent object of this element - - ``node_weight`` -- The weight of this node - - ``dominant_root`` -- The dominating root - - ``parent_node`` -- (default:None) The parent node of this node + - ``parent_obj`` -- the parent object of this element + - ``node_weight`` -- the weight of this node + - ``dominant_root`` -- the dominating root + - ``parent_node`` -- (default: ``None``) the parent node of this node """ def __init__(self, parent_obj, node_weight, dominant_root, parent_node=None): @@ -515,7 +515,7 @@ class KleberTree(UniqueRepresentation, Parent): :class:`VirtualKleberTree`. The nodes correspond to the weights in the positive Weyl chamber obtained - by subtracting a (non-zero) positive root. The edges are labeled by the + by subtracting a (nonzero) positive root. The edges are labeled by the coefficients of the roots, and `X` is a child of `Y` if `Y` is the root else if the edge label of `Y` to its parent `Z` is greater (in every component) than the label from `X` to `Y`. @@ -529,7 +529,7 @@ class KleberTree(UniqueRepresentation, Parent): - ``cartan_type`` -- an affine simply-laced Cartan type - - ``B`` -- a list of dimensions of rectangles by `[r, c]` + - ``B`` -- list of dimensions of rectangles by `[r, c]` where `r` is the number of rows and `c` is the number of columns REFERENCES: @@ -623,7 +623,7 @@ def __init__(self, cartan_type, B, classical_ct): sage: from sage.combinat.rigged_configurations.kleber_tree import KleberTree sage: KT = KleberTree(['D', 3, 1], [[1,1], [1,1]]); KT Kleber tree of Cartan type ['D', 3, 1] and B = ((1, 1), (1, 1)) - sage: TestSuite(KT).run(skip="_test_elements") + sage: TestSuite(KT).run(skip='_test_elements') """ Parent.__init__(self, category=FiniteEnumeratedSets()) @@ -650,8 +650,8 @@ def latex_options(self, **options): - ``vspace`` -- (default: ``x``) the vertical spacing of the tree nodes, here ``x`` is the minimum of `-2.5` or `-.75n` where `n` is the rank of the classical type - - ``edge_labels`` -- (default: ``True``) display edge labels - - ``use_vector_notation`` -- (default: ``False``) display edge labels + - ``edge_labels`` -- boolean (default: ``True``); display edge labels + - ``use_vector_notation`` -- boolean (default: ``False``); display edge labels using vector notation instead of a linear combination EXAMPLES:: @@ -1033,12 +1033,12 @@ def digraph(self): G = DiGraph(d) if have_dot2tex(): - G.set_latex_options(format="dot2tex", edge_labels=True) + G.set_latex_options(format='dot2tex', edge_labels=True) return G def plot(self, **options): """ - Return the plot of self as a directed graph. + Return the plot of ``self`` as a directed graph. EXAMPLES:: @@ -1115,7 +1115,7 @@ class VirtualKleberTree(KleberTree): - ``cartan_type`` -- an affine non-simply-laced Cartan type - - ``B`` -- a list of dimensions of rectangles by `[r, c]` + - ``B`` -- list of dimensions of rectangles by `[r, c]` where `r` is the number of rows and `c` is the number of columns EXAMPLES:: @@ -1168,7 +1168,7 @@ def __init__(self, cartan_type, B): sage: from sage.combinat.rigged_configurations.kleber_tree import VirtualKleberTree sage: KT = VirtualKleberTree(['C',4,1], [[2,2]]) - sage: TestSuite(KT).run(skip="_test_elements") + sage: TestSuite(KT).run(skip='_test_elements') """ self._folded_ct = cartan_type.as_folding() virtual_dims = [] @@ -1240,7 +1240,7 @@ def breadth_first_iter(self, all_nodes=False): INPUT: - - ``all_nodes`` -- (default: ``False``) if ``True``, output all + - ``all_nodes`` -- boolean (default: ``False``); if ``True``, output all nodes in the tree EXAMPLES:: @@ -1276,7 +1276,7 @@ def depth_first_iter(self, all_nodes=False): INPUT: - - ``all_nodes`` -- (default: ``False``) if ``True``, output all + - ``all_nodes`` -- boolean (default: ``False``); if ``True``, output all nodes in the tree EXAMPLES:: @@ -1363,7 +1363,7 @@ def __init__(self, cartan_type, B): sage: from sage.combinat.rigged_configurations.kleber_tree import VirtualKleberTree sage: KT = VirtualKleberTree(['A',6,2], [[2,2]]); KT Virtual Kleber tree of Cartan type ['BC', 3, 2] and B = ((2, 2),) - sage: TestSuite(KT).run(skip="_test_elements") + sage: TestSuite(KT).run(skip='_test_elements') """ self._folded_ct = cartan_type.as_folding() virtual_dims = [] @@ -1432,7 +1432,7 @@ def breadth_first_iter(self, all_nodes=False): INPUT: - - ``all_nodes`` -- (default: ``False``) if ``True``, output all + - ``all_nodes`` -- boolean (default: ``False``); if ``True``, output all nodes in the tree EXAMPLES:: @@ -1457,7 +1457,7 @@ def depth_first_iter(self, all_nodes=False): INPUT: - - ``all_nodes`` -- (default: ``False``) if ``True``, output all + - ``all_nodes`` -- boolean (default: ``False``); if ``True``, output all nodes in the tree EXAMPLES:: diff --git a/src/sage/combinat/rigged_configurations/kr_tableaux.py b/src/sage/combinat/rigged_configurations/kr_tableaux.py index 8bdc1d275b9..fb6f223e62c 100644 --- a/src/sage/combinat/rigged_configurations/kr_tableaux.py +++ b/src/sage/combinat/rigged_configurations/kr_tableaux.py @@ -653,12 +653,10 @@ def _fill(self, weight): INPUT: - - ``weight`` -- The weight of the highest weight KR tableau (the + - ``weight`` -- the weight of the highest weight KR tableau (the conjugate of the shape of the KR crystal's tableau) - OUTPUT: - - - A `r \times s` tableau + OUTPUT: a `r \times s` tableau EXAMPLES:: @@ -781,11 +779,9 @@ def _fill(self, shape): INPUT: - - ``shape`` -- The shape of the KR crystal's tableau - - OUTPUT: + - ``shape`` -- the shape of the KR crystal's tableau - - A `r \times s` tableau + OUTPUT: a `r \times s` tableau EXAMPLES:: @@ -879,12 +875,10 @@ def _fill(self, weight): INPUT: - - ``weight`` -- The weight of the highest weight KR tableau (the + - ``weight`` -- the weight of the highest weight KR tableau (the conjugate of the shape of the KR crystal's tableau) - OUTPUT: - - - A `r \times s` tableau + OUTPUT: a `r \times s` tableau EXAMPLES:: @@ -1219,8 +1213,8 @@ def to_array(self, rows=True): INPUT: - - ``rows`` -- (Default: ``True``) Set to ``True`` if the resulting - array is by row, otherwise it is by column. + - ``rows`` -- boolean (default: ``True``); set to ``True`` if the + resulting array is by row, otherwise it is by column EXAMPLES:: @@ -1287,9 +1281,9 @@ def to_classical_highest_weight(self, index_set=None): INPUT: - - ``index_set`` -- (Default: ``None``) Return the highest weight - with respect to the index set. If ``None`` is passed in, then this - uses the classical index set. + - ``index_set`` -- (default: ``None``) return the highest weight + with respect to the index set; if ``None`` is passed in, then this + uses the classical index set OUTPUT: @@ -1589,8 +1583,8 @@ def to_array(self, rows=True): INPUT: - - ``rows`` -- (Default: ``True``) Set to ``True`` if the resulting - array is by row, otherwise it is by column. + - ``rows`` -- boolean (default: ``True``); set to ``True`` if the + resulting array is by row, otherwise it is by column EXAMPLES:: diff --git a/src/sage/combinat/rigged_configurations/rigged_configuration_element.py b/src/sage/combinat/rigged_configurations/rigged_configuration_element.py index 8e1e76ed41d..4fe967a5c6c 100644 --- a/src/sage/combinat/rigged_configurations/rigged_configuration_element.py +++ b/src/sage/combinat/rigged_configurations/rigged_configuration_element.py @@ -55,7 +55,7 @@ class RiggedConfigurationElement(ClonableArray): - ``parent`` -- the parent of this element - - ``rigged_partitions`` -- a list of rigged partitions + - ``rigged_partitions`` -- list of rigged partitions There are two optional arguments to explicitly construct a rigged configuration. The first is ``partition_list`` which gives a list of @@ -462,9 +462,7 @@ def nu(self): Return the list `\nu` of rigged partitions of this rigged configuration element. - OUTPUT: - - The `\nu` array as a list. + OUTPUT: the `\nu` array as a list EXAMPLES:: @@ -503,9 +501,7 @@ def e(self, a): - ``a`` -- the index of the partition to remove a box - OUTPUT: - - The resulting rigged configuration element. + OUTPUT: the resulting rigged configuration element EXAMPLES:: @@ -625,9 +621,7 @@ def _generate_partition_e(self, a, b, k): - ``k`` -- the length of the string with the smallest negative rigging of smallest length - OUTPUT: - - The constructed rigged partition. + OUTPUT: the constructed rigged partition TESTS:: @@ -677,9 +671,7 @@ def f(self, a): - ``a`` -- the index of the partition to add a box - OUTPUT: - - The resulting rigged configuration element. + OUTPUT: the resulting rigged configuration element EXAMPLES:: @@ -784,9 +776,7 @@ def _generate_partition_f(self, a, b, k): - ``k`` -- the length of the string with smallest nonpositive rigging of largest length - OUTPUT: - - The constructed rigged partition. + OUTPUT: the constructed rigged partition TESTS:: @@ -1097,9 +1087,7 @@ def f(self, a): - ``a`` -- the index of the partition to add a box - OUTPUT: - - The resulting rigged configuration element. + OUTPUT: the resulting rigged configuration element EXAMPLES:: @@ -1354,9 +1342,7 @@ def e(self, a): - ``a`` -- the index of the partition to remove a box - OUTPUT: - - The resulting rigged configuration element. + OUTPUT: the resulting rigged configuration element EXAMPLES:: @@ -1408,9 +1394,7 @@ def f(self, a): - ``a`` -- the index of the partition to add a box - OUTPUT: - - The resulting rigged configuration element. + OUTPUT: the resulting rigged configuration element EXAMPLES:: @@ -1573,10 +1557,10 @@ def to_tensor_product_of_kirillov_reshetikhin_tableaux(self, display_steps=False INPUT: - - ``display_steps`` -- (default: ``False``) boolean which indicates - if we want to print each step in the algorithm - - ``build_graph`` -- (default: ``False``) boolean which indicates - if we want to construct and return a graph of the bijection whose + - ``display_steps`` -- boolean (default: ``False``); indicates whether + to print each step in the algorithm + - ``build_graph`` -- boolean (default: ``False``); indicates whether + to construct and return a graph of the bijection whose vertices are rigged configurations obtained at each step and edges are labeled by either the return value of `\delta` or the doubling/halving map @@ -1659,10 +1643,10 @@ def to_tensor_product_of_kirillov_reshetikhin_crystals(self, display_steps=False INPUT: - - ``display_steps`` -- (default: ``False``) boolean which indicates - if we want to print each step in the algorithm - - ``build_graph`` -- (default: ``False``) boolean which indicates - if we want to construct and return a graph of the bijection whose + - ``display_steps`` -- boolean (default: ``False``); indicates whether + to print each step in the algorithm + - ``build_graph`` -- boolean (default: ``False``); indicates whether + to construct and return a graph of the bijection whose vertices are rigged configurations obtained at each step and edges are labeled by either the return value of `\delta` or the doubling/halving map @@ -1802,7 +1786,7 @@ def left_box(self, return_b=False): INPUT: - - ``return_b`` -- (default: ``False``) whether to return the + - ``return_b`` -- boolean (default: ``False``); whether to return the resulting letter from `\delta` OUTPUT: @@ -1990,7 +1974,7 @@ def complement_rigging(self, reverse_factors=False): INPUT: - - ``reverse_factors`` -- (default: ``False``) if ``True``, then this + - ``reverse_factors`` -- boolean (default: ``False``); if ``True``, then this returns an element in `RC(B')` where `B'` is the tensor factors of ``self`` in reverse order diff --git a/src/sage/combinat/rigged_configurations/rigged_configurations.py b/src/sage/combinat/rigged_configurations/rigged_configurations.py index 535787875b5..0d3d9954cc1 100644 --- a/src/sage/combinat/rigged_configurations/rigged_configurations.py +++ b/src/sage/combinat/rigged_configurations/rigged_configurations.py @@ -123,7 +123,7 @@ class RiggedConfigurations(UniqueRepresentation, Parent): :class:`~sage.combinat.rigged_configurations.tensor_product_kr_tableaux.TensorProductOfKirillovReshetikhinTableaux` of non-exceptional affine types where the list `B` corresponds to the tensor factors `B^{r,s}`. The bijection has been proven in types `A_n^{(1)}` - and `D_n^{(1)}` and when the only non-zero entries of `L_i^{(a)}` are either + and `D_n^{(1)}` and when the only nonzero entries of `L_i^{(a)}` are either only `L_1^{(a)}` or only `L_i^{(1)}` (corresponding to single columns or rows respectively) [RigConBijection]_, [BijectionLRT]_, [BijectionDn]_. @@ -146,7 +146,7 @@ class RiggedConfigurations(UniqueRepresentation, Parent): - ``cartan_type`` -- a Cartan type - - ``B`` -- a list of positive integer tuples `(r,s)` corresponding to the + - ``B`` -- list of positive integer tuples `(r,s)` corresponding to the tensor factors in the bijection with tensor product of Kirillov-Reshetikhin tableaux or equivalently the sequence of width `s` and height `r` rectangles @@ -391,7 +391,7 @@ def __init__(self, cartan_type, B): # add options to class class options(GlobalOptions): r""" - Sets and displays the options for rigged configurations. + Set and display the options for rigged configurations. If no parameters are set, then the function returns a copy of the options dictionary. @@ -414,7 +414,7 @@ class options(GlobalOptions): -1[ ]-1 - sage: RiggedConfigurations.options(display="horizontal", convention="french") + sage: RiggedConfigurations.options(display='horizontal', convention='french') sage: elt -1[ ]-1 1[ ][ ][ ]1 -1[ ]-1 -3[ ][ ][ ]-3 @@ -437,7 +437,7 @@ class options(GlobalOptions): """ NAME = 'RiggedConfigurations' module = 'sage.combinat.rigged_configurations.rigged_configurations' - display = dict(default="vertical", + display = dict(default='vertical', description='Specifies how rigged configurations should be printed', values=dict(vertical='displayed vertically', horizontal='displayed horizontally'), @@ -612,7 +612,7 @@ def _block_iterator(self, container): INPUT: - - ``container`` -- a list of widths of the rows of the container + - ``container`` -- list of widths of the rows of the container TESTS:: @@ -1806,7 +1806,7 @@ def _block_iterator_n_odd(self, container): INPUT: - - ``container`` -- a list the widths of the rows of the container + - ``container`` -- list the widths of the rows of the container TESTS:: diff --git a/src/sage/combinat/rigged_configurations/rigged_partition.pyx b/src/sage/combinat/rigged_configurations/rigged_partition.pyx index 97ff48d7918..84d98c90f3e 100644 --- a/src/sage/combinat/rigged_configurations/rigged_partition.pyx +++ b/src/sage/combinat/rigged_configurations/rigged_partition.pyx @@ -360,13 +360,11 @@ cdef class RiggedPartition(SageObject): INPUT: - - ``end_column`` -- The index of the column to end at + - ``end_column`` -- the index of the column to end at - - ``t`` -- The scaling factor + - ``t`` -- the scaling factor - OUTPUT: - - - The number of cells + OUTPUT: the number of cells EXAMPLES:: @@ -405,12 +403,10 @@ cdef class RiggedPartition(SageObject): INPUT: - - ``max_width`` -- The maximum width (i.e. row length) that we can + - ``max_width`` -- the maximum width (i.e. row length) that we can insert the cell at - OUTPUT: - - - The width of the row we inserted at. + OUTPUT: the width of the row we inserted at EXAMPLES:: @@ -562,7 +558,7 @@ cdef class RiggedPartitionTypeB(RiggedPartition): INPUT: - - ``half_width_boxes`` -- (Default: ``True``) Display the partition + - ``half_width_boxes`` -- (default: ``True``) display the partition using half width boxes EXAMPLES:: @@ -611,7 +607,7 @@ cdef class RiggedPartitionTypeB(RiggedPartition): INPUT: - - ``half_width_boxes`` -- (default: ``True``) display the partition + - ``half_width_boxes`` -- boolean (default: ``True``); display the partition using half width boxes EXAMPLES:: diff --git a/src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element.py b/src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element.py index 8db94443af2..436bbe79b61 100644 --- a/src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element.py +++ b/src/sage/combinat/rigged_configurations/tensor_product_kr_tableaux_element.py @@ -118,9 +118,9 @@ def __init__(self, parent, list=[[]], **options): INPUT: - - ``parent`` -- Parent for this element + - ``parent`` -- parent for this element - - ``list`` -- The list of KR tableaux elements + - ``list`` -- the list of KR tableaux elements EXAMPLES:: @@ -324,12 +324,10 @@ def to_rigged_configuration(self, display_steps=False): INPUT: - - ``display_steps`` -- (default: ``False``) Boolean which indicates - if we want to output each step in the algorithm. + - ``display_steps`` -- boolean (default: ``False``); whether to output + each step in the algorithm - OUTPUT: - - The rigged configuration corresponding to ``self``. + OUTPUT: the rigged configuration corresponding to ``self`` EXAMPLES: diff --git a/src/sage/combinat/root_system/ambient_space.py b/src/sage/combinat/root_system/ambient_space.py index e52a8504edd..5fe5e161575 100644 --- a/src/sage/combinat/root_system/ambient_space.py +++ b/src/sage/combinat/root_system/ambient_space.py @@ -18,7 +18,7 @@ class AmbientSpace(CombinatorialFreeModule): r""" - Abstract class for ambient spaces + Abstract class for ambient spaces. All subclasses should implement a class method ``smallest_base_ring`` taking a Cartan type as input, and a method @@ -140,7 +140,6 @@ def dimension(self): Traceback (most recent call last): ... NotImplementedError - """ raise NotImplementedError @@ -169,7 +168,6 @@ def _repr_(self): Ambient lattice of the Root system of type ['A', 4] sage: RootSystem(['B',4]).ambient_space() Ambient space of the Root system of type ['B', 4] - """ return self._name_string() @@ -179,7 +177,6 @@ def _name_string(self, capitalize=True, base_ring=False, type=True): sage: RootSystem(['A',4]).ambient_lattice()._name_string() "Ambient lattice of the Root system of type ['A', 4]" - """ return self._name_string_helper("ambient", capitalize=capitalize, base_ring=base_ring, type=type) @@ -230,7 +227,7 @@ def coroot_lattice(self): def simple_coroot(self, i): r""" - Returns the i-th simple coroot, as an element of this space + Return the `i`-th simple coroot, as an element of this space. EXAMPLES:: @@ -257,7 +254,6 @@ def reflection(self, root, coroot=None): sage: s_a = e.reflection(a) sage: s_a(b) (0, -1, 0, 0) - """ # TODO: get rid of this as one can use the generic implementation # (i.e. scalar and associated coroot are implemented) @@ -266,7 +262,7 @@ def reflection(self, root, coroot=None): @cached_method def fundamental_weight(self, i): r""" - Returns the fundamental weight `\Lambda_i` in ``self`` + Return the fundamental weight `\Lambda_i` in ``self``. In several of the ambient spaces, it is more convenient to construct all fundamental weights at once. To support this, we @@ -291,13 +287,13 @@ def fundamental_weight(self, i): """ return self.fundamental_weights()[i] - def from_vector_notation(self, weight, style="lattice"): + def from_vector_notation(self, weight, style='lattice'): """ INPUT: - ``weight`` -- a vector or tuple representing a weight - Returns an element of self. If the weight lattice is not + Returns an element of ``self``. If the weight lattice is not of full rank, it coerces it into the weight lattice, or its ambient space by orthogonal projection. This arises in two cases: for SL(r+1), the weight lattice is @@ -307,7 +303,7 @@ def from_vector_notation(self, weight, style="lattice"): If style="coroots" and the data is a tuple of integers, it is assumed that the data represent a linear combination of - fundamental weights. If style="coroots", and the root lattice + fundamental weights. If style='coroots', and the root lattice is not of full rank in the ambient space, it is projected into the subspace corresponding to the semisimple derived group. This arises with Cartan type A, E6 and E7. @@ -318,7 +314,7 @@ def from_vector_notation(self, weight, style="lattice"): (1, 0, 0) sage: RootSystem("A2").ambient_space().from_vector_notation([1,0,0]) (1, 0, 0) - sage: RootSystem("A2").ambient_space().from_vector_notation((1,0),style="coroots") + sage: RootSystem("A2").ambient_space().from_vector_notation((1,0),style='coroots') (2/3, -1/3, -1/3) """ if style == "coroots" and isinstance(weight, tuple) and all(xv in ZZ for xv in weight): @@ -406,7 +402,6 @@ def associated_coroot(self): (1/2, -1/2, -1/2, -1/2) sage: a.associated_coroot() (1, -1, -1, -1) - """ # FIXME: make it work over ZZ! return self * self.base_ring()(2/self.inner_product(self)) @@ -508,7 +503,6 @@ def to_ambient(self): (2, 2, 3) sage: v.to_ambient() (2, 2, 3) - """ return self diff --git a/src/sage/combinat/root_system/associahedron.py b/src/sage/combinat/root_system/associahedron.py index 448b1009036..7b2752daa6d 100644 --- a/src/sage/combinat/root_system/associahedron.py +++ b/src/sage/combinat/root_system/associahedron.py @@ -337,7 +337,7 @@ class Associahedra_base: Importantly, the parent knows the dimension of the ambient space. If you try to construct an associahedron of a different - dimension, a :class:`ValueError` is raised:: + dimension, a :exc:`ValueError` is raised:: sage: parent(['A',3]) Traceback (most recent call last): @@ -387,15 +387,13 @@ def _element_constructor_(self, cartan_type, **kwds): def _coerce_map_from_(self, X): r""" - Return whether there is a coercion from ``X`` + Return whether there is a coercion from ``X``. INPUT: - - ``X`` -- anything. + - ``X`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/combinat/root_system/braid_move_calculator.py b/src/sage/combinat/root_system/braid_move_calculator.py index 38931a00229..8fcdc26f24b 100644 --- a/src/sage/combinat/root_system/braid_move_calculator.py +++ b/src/sage/combinat/root_system/braid_move_calculator.py @@ -33,7 +33,7 @@ def __init__(self, coxeter_group): sage: from sage.combinat.root_system.braid_move_calculator import BraidMoveCalculator sage: W = CoxeterGroup(['C',3]) sage: B = BraidMoveCalculator(W) - sage: TestSuite(B).run(skip="_test_pickling") + sage: TestSuite(B).run(skip='_test_pickling') """ self.coxeter_matrix = coxeter_group.coxeter_matrix() diff --git a/src/sage/combinat/root_system/branching_rules.py b/src/sage/combinat/root_system/branching_rules.py index 4877b972438..91876ee8dd3 100644 --- a/src/sage/combinat/root_system/branching_rules.py +++ b/src/sage/combinat/root_system/branching_rules.py @@ -20,7 +20,7 @@ from sage.misc.functional import is_even, is_odd -def branch_weyl_character(chi, R, S, rule="default"): +def branch_weyl_character(chi, R, S, rule='default'): r""" A branching rule describes the restriction of representations from a Lie group or algebra `G` to a subgroup `H`. See for example, R. C. @@ -46,14 +46,14 @@ def branch_weyl_character(chi, R, S, rule="default"): - ``rule`` -- an element of the ``BranchingRule`` class or one (most usually) a keyword such as: - * ``"levi"`` - * ``"automorphic"`` - * ``"symmetric"`` - * ``"extended"`` - * ``"orthogonal_sum"`` - * ``"tensor"`` - * ``"triality"`` - * ``"miscellaneous"`` + * ``'levi'`` + * ``'automorphic'`` + * ``'symmetric'`` + * ``'extended'`` + * ``'orthogonal_sum'`` + * ``'tensor'`` + * ``'triality'`` + * ``'miscellaneous'`` The :class:`BranchingRule` class is a wrapper for functions from the weight lattice of `G` to the weight lattice of `H`. @@ -79,9 +79,9 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A3=WeylCharacterRing("A3",style="coroots") - sage: A2=WeylCharacterRing("A2",style="coroots") - sage: [A3(fw).branch(A2,rule="levi") for fw in A3.fundamental_weights()] + sage: A3=WeylCharacterRing("A3",style='coroots') + sage: A2=WeylCharacterRing("A2",style='coroots') + sage: [A3(fw).branch(A2,rule='levi') for fw in A3.fundamental_weights()] [A2(0,0) + A2(1,0), A2(0,1) + A2(1,0), A2(0,0) + A2(0,1)] In this case the Levi branching rule is the default branching rule @@ -94,8 +94,8 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A4=WeylCharacterRing("A4",style="coroots") - sage: A2=WeylCharacterRing("A2",style="coroots") + sage: A4=WeylCharacterRing("A4",style='coroots') + sage: A2=WeylCharacterRing("A2",style='coroots') sage: br=branching_rule("A4","A3")*branching_rule("A3","A2") sage: A4(1,0,0,0).branch(A2,rule=br) 2*A2(0,0) + A2(1,0) @@ -129,13 +129,13 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A1 = WeylCharacterRing("A1", style="coroots") - sage: A2 = WeylCharacterRing("A2", style="coroots") - sage: D4 = WeylCharacterRing("D4", style="coroots") - sage: B3 = WeylCharacterRing("B3", style="coroots") - sage: B4 = WeylCharacterRing("B4", style="coroots") - sage: A6 = WeylCharacterRing("A6", style="coroots") - sage: A7 = WeylCharacterRing("A7", style="coroots") + sage: A1 = WeylCharacterRing("A1", style='coroots') + sage: A2 = WeylCharacterRing("A2", style='coroots') + sage: D4 = WeylCharacterRing("D4", style='coroots') + sage: B3 = WeylCharacterRing("B3", style='coroots') + sage: B4 = WeylCharacterRing("B4", style='coroots') + sage: A6 = WeylCharacterRing("A6", style='coroots') + sage: A7 = WeylCharacterRing("A7", style='coroots') sage: def try_default_rule(R,S): return [R(f).branch(S) for f in R.fundamental_weights()] sage: try_default_rule(A2,A1) [A1(0) + A1(1), A1(0) + A1(1)] @@ -214,12 +214,12 @@ def branch_weyl_character(chi, R, S, rule="default"): sage: D3 = WeylCharacterRing("D3") sage: D4 = WeylCharacterRing("D4") sage: G2 = WeylCharacterRing("G2") - sage: F4 = WeylCharacterRing("F4",style="coroots") - sage: E6=WeylCharacterRing("E6",style="coroots") - sage: E7=WeylCharacterRing("E7",style="coroots") - sage: D5=WeylCharacterRing("D5",style="coroots") - sage: D6=WeylCharacterRing("D6",style="coroots") - sage: [B3(w).branch(A2,rule="levi") for w in B3.fundamental_weights()] + sage: F4 = WeylCharacterRing("F4",style='coroots') + sage: E6=WeylCharacterRing("E6",style='coroots') + sage: E7=WeylCharacterRing("E7",style='coroots') + sage: D5=WeylCharacterRing("D5",style='coroots') + sage: D6=WeylCharacterRing("D6",style='coroots') + sage: [B3(w).branch(A2,rule='levi') for w in B3.fundamental_weights()] [A2(0,0,0) + A2(1,0,0) + A2(0,0,-1), A2(0,0,0) + A2(1,0,0) + A2(1,1,0) + A2(1,0,-1) + A2(0,-1,-1) + A2(0,0,-1), A2(-1/2,-1/2,-1/2) + A2(1/2,-1/2,-1/2) + A2(1/2,1/2,-1/2) + A2(1/2,1/2,1/2)] @@ -235,73 +235,73 @@ def branch_weyl_character(chi, R, S, rule="default"): :: - sage: [C3(w).branch(A2,rule="levi") for w in C3.fundamental_weights()] + sage: [C3(w).branch(A2,rule='levi') for w in C3.fundamental_weights()] [A2(1,0,0) + A2(0,0,-1), A2(1,1,0) + A2(1,0,-1) + A2(0,-1,-1), A2(-1,-1,-1) + A2(1,-1,-1) + A2(1,1,-1) + A2(1,1,1)] - sage: [D4(w).branch(A3,rule="levi") for w in D4.fundamental_weights()] + sage: [D4(w).branch(A3,rule='levi') for w in D4.fundamental_weights()] [A3(1,0,0,0) + A3(0,0,0,-1), A3(0,0,0,0) + A3(1,1,0,0) + A3(1,0,0,-1) + A3(0,0,-1,-1), A3(1/2,-1/2,-1/2,-1/2) + A3(1/2,1/2,1/2,-1/2), A3(-1/2,-1/2,-1/2,-1/2) + A3(1/2,1/2,-1/2,-1/2) + A3(1/2,1/2,1/2,1/2)] - sage: [B3(w).branch(B2,rule="levi") for w in B3.fundamental_weights()] + sage: [B3(w).branch(B2,rule='levi') for w in B3.fundamental_weights()] [2*B2(0,0) + B2(1,0), B2(0,0) + 2*B2(1,0) + B2(1,1), 2*B2(1/2,1/2)] sage: C3 = WeylCharacterRing(['C',3]) - sage: [C3(w).branch(C2,rule="levi") for w in C3.fundamental_weights()] + sage: [C3(w).branch(C2,rule='levi') for w in C3.fundamental_weights()] [2*C2(0,0) + C2(1,0), C2(0,0) + 2*C2(1,0) + C2(1,1), C2(1,0) + 2*C2(1,1)] - sage: [D5(w).branch(D4,rule="levi") for w in D5.fundamental_weights()] + sage: [D5(w).branch(D4,rule='levi') for w in D5.fundamental_weights()] [2*D4(0,0,0,0) + D4(1,0,0,0), D4(0,0,0,0) + 2*D4(1,0,0,0) + D4(1,1,0,0), D4(1,0,0,0) + 2*D4(1,1,0,0) + D4(1,1,1,0), D4(1/2,1/2,1/2,-1/2) + D4(1/2,1/2,1/2,1/2), D4(1/2,1/2,1/2,-1/2) + D4(1/2,1/2,1/2,1/2)] - sage: G2(1,0,-1).branch(A1,rule="levi") + sage: G2(1,0,-1).branch(A1,rule='levi') A1(1,0) + A1(1,-1) + A1(0,-1) - sage: E6=WeylCharacterRing("E6",style="coroots") - sage: D5=WeylCharacterRing("D5",style="coroots") + sage: E6=WeylCharacterRing("E6",style='coroots') + sage: D5=WeylCharacterRing("D5",style='coroots') sage: fw = E6.fundamental_weights() - sage: [E6(fw[i]).branch(D5,rule="levi") for i in [1,2,6]] + sage: [E6(fw[i]).branch(D5,rule='levi') for i in [1,2,6]] [D5(0,0,0,0,0) + D5(0,0,0,0,1) + D5(1,0,0,0,0), D5(0,0,0,0,0) + D5(0,0,0,1,0) + D5(0,0,0,0,1) + D5(0,1,0,0,0), D5(0,0,0,0,0) + D5(0,0,0,1,0) + D5(1,0,0,0,0)] - sage: E7=WeylCharacterRing("E7",style="coroots") - sage: A3xA3xA1=WeylCharacterRing("A3xA3xA1",style="coroots") - sage: E7(1,0,0,0,0,0,0).branch(A3xA3xA1,rule="extended") # long time (0.7s) + sage: E7=WeylCharacterRing("E7",style='coroots') + sage: A3xA3xA1=WeylCharacterRing("A3xA3xA1",style='coroots') + sage: E7(1,0,0,0,0,0,0).branch(A3xA3xA1,rule='extended') # long time (0.7s) A3xA3xA1(0,0,1,0,0,1,1) + A3xA3xA1(0,1,0,0,1,0,0) + A3xA3xA1(1,0,0,1,0,0,1) + A3xA3xA1(1,0,1,0,0,0,0) + A3xA3xA1(0,0,0,1,0,1,0) + A3xA3xA1(0,0,0,0,0,0,2) sage: fw = E7.fundamental_weights() - sage: [E7(fw[i]).branch(D6,rule="levi") for i in [1,2,7]] # long time (0.3s) + sage: [E7(fw[i]).branch(D6,rule='levi') for i in [1,2,7]] # long time (0.3s) [3*D6(0,0,0,0,0,0) + 2*D6(0,0,0,0,1,0) + D6(0,1,0,0,0,0), 3*D6(0,0,0,0,0,1) + 2*D6(1,0,0,0,0,0) + 2*D6(0,0,1,0,0,0) + D6(1,0,0,0,1,0), D6(0,0,0,0,0,1) + 2*D6(1,0,0,0,0,0)] - sage: D7=WeylCharacterRing("D7",style="coroots") - sage: E8=WeylCharacterRing("E8",style="coroots") - sage: D7=WeylCharacterRing("D7",style="coroots") - sage: E8(1,0,0,0,0,0,0,0).branch(D7,rule="levi") # long time (7s) + sage: D7=WeylCharacterRing("D7",style='coroots') + sage: E8=WeylCharacterRing("E8",style='coroots') + sage: D7=WeylCharacterRing("D7",style='coroots') + sage: E8(1,0,0,0,0,0,0,0).branch(D7,rule='levi') # long time (7s) 3*D7(0,0,0,0,0,0,0) + 2*D7(0,0,0,0,0,1,0) + 2*D7(0,0,0,0,0,0,1) + 2*D7(1,0,0,0,0,0,0) + D7(0,1,0,0,0,0,0) + 2*D7(0,0,1,0,0,0,0) + D7(0,0,0,1,0,0,0) + D7(1,0,0,0,0,1,0) + D7(1,0,0,0,0,0,1) + D7(2,0,0,0,0,0,0) - sage: E8(0,0,0,0,0,0,0,1).branch(D7,rule="levi") # long time (0.6s) + sage: E8(0,0,0,0,0,0,0,1).branch(D7,rule='levi') # long time (0.6s) D7(0,0,0,0,0,0,0) + D7(0,0,0,0,0,1,0) + D7(0,0,0,0,0,0,1) + 2*D7(1,0,0,0,0,0,0) + D7(0,1,0,0,0,0,0) - sage: [F4(fw).branch(B3,rule="levi") for fw in F4.fundamental_weights()] # long time (1s) + sage: [F4(fw).branch(B3,rule='levi') for fw in F4.fundamental_weights()] # long time (1s) [B3(0,0,0) + 2*B3(1/2,1/2,1/2) + 2*B3(1,0,0) + B3(1,1,0), B3(0,0,0) + 6*B3(1/2,1/2,1/2) + 5*B3(1,0,0) + 7*B3(1,1,0) + 3*B3(1,1,1) + 6*B3(3/2,1/2,1/2) + 2*B3(3/2,3/2,1/2) + B3(2,0,0) + 2*B3(2,1,0) + B3(2,1,1), 3*B3(0,0,0) + 6*B3(1/2,1/2,1/2) + 4*B3(1,0,0) + 3*B3(1,1,0) + B3(1,1,1) + 2*B3(3/2,1/2,1/2), 3*B3(0,0,0) + 2*B3(1/2,1/2,1/2) + B3(1,0,0)] - sage: [F4(fw).branch(C3,rule="levi") for fw in F4.fundamental_weights()] # long time (1s) + sage: [F4(fw).branch(C3,rule='levi') for fw in F4.fundamental_weights()] # long time (1s) [3*C3(0,0,0) + 2*C3(1,1,1) + C3(2,0,0), 3*C3(0,0,0) + 6*C3(1,1,1) + 4*C3(2,0,0) + 2*C3(2,1,0) + 3*C3(2,2,0) + C3(2,2,2) + C3(3,1,0) + 2*C3(3,1,1), 2*C3(1,0,0) + 3*C3(1,1,0) + C3(2,0,0) + 2*C3(2,1,0) + C3(2,1,1), 2*C3(1,0,0) + C3(1,1,0)] sage: A1xA1 = WeylCharacterRing("A1xA1") - sage: [A3(hwv).branch(A1xA1,rule="levi") for hwv in A3.fundamental_weights()] + sage: [A3(hwv).branch(A1xA1,rule='levi') for hwv in A3.fundamental_weights()] [A1xA1(1,0,0,0) + A1xA1(0,0,1,0), A1xA1(1,1,0,0) + A1xA1(1,0,1,0) + A1xA1(0,0,1,1), A1xA1(1,1,1,0) + A1xA1(1,0,1,1)] - sage: A1xB1=WeylCharacterRing("A1xB1",style="coroots") - sage: [B3(x).branch(A1xB1,rule="levi") for x in B3.fundamental_weights()] + sage: A1xB1=WeylCharacterRing("A1xB1",style='coroots') + sage: [B3(x).branch(A1xB1,rule='levi') for x in B3.fundamental_weights()] [2*A1xB1(1,0) + A1xB1(0,2), 3*A1xB1(0,0) + 2*A1xB1(1,2) + A1xB1(2,0) + A1xB1(0,2), A1xB1(1,1) + 2*A1xB1(0,1)] @@ -323,14 +323,14 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: [A3(chi).branch(A3,rule="automorphic") for chi in A3.fundamental_weights()] + sage: [A3(chi).branch(A3,rule='automorphic') for chi in A3.fundamental_weights()] [A3(0,0,0,-1), A3(0,0,-1,-1), A3(0,-1,-1,-1)] - sage: [D4(chi).branch(D4,rule="automorphic") for chi in D4.fundamental_weights()] + sage: [D4(chi).branch(D4,rule='automorphic') for chi in D4.fundamental_weights()] [D4(1,0,0,0), D4(1,1,0,0), D4(1/2,1/2,1/2,1/2), D4(1/2,1/2,1/2,-1/2)] Here is an example with `D_4` triality:: - sage: [D4(chi).branch(D4,rule="triality") for chi in D4.fundamental_weights()] + sage: [D4(chi).branch(D4,rule='triality') for chi in D4.fundamental_weights()] [D4(1/2,1/2,1/2,-1/2), D4(1,1,0,0), D4(1/2,1/2,1/2,1/2), D4(1,0,0,0)] .. RUBRIC:: Symmetric Type @@ -371,28 +371,28 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: [w.branch(B2,rule="symmetric") for w in [A4(1,0,0,0,0),A4(1,1,0,0,0),A4(1,1,1,0,0),A4(2,0,0,0,0)]] + sage: [w.branch(B2,rule='symmetric') for w in [A4(1,0,0,0,0),A4(1,1,0,0,0),A4(1,1,1,0,0),A4(2,0,0,0,0)]] [B2(1,0), B2(1,1), B2(1,1), B2(0,0) + B2(2,0)] - sage: [A5(w).branch(C3,rule="symmetric") for w in A5.fundamental_weights()] + sage: [A5(w).branch(C3,rule='symmetric') for w in A5.fundamental_weights()] [C3(1,0,0), C3(0,0,0) + C3(1,1,0), C3(1,0,0) + C3(1,1,1), C3(0,0,0) + C3(1,1,0), C3(1,0,0)] - sage: [A5(w).branch(D3,rule="symmetric") for w in A5.fundamental_weights()] + sage: [A5(w).branch(D3,rule='symmetric') for w in A5.fundamental_weights()] [D3(1,0,0), D3(1,1,0), D3(1,1,-1) + D3(1,1,1), D3(1,1,0), D3(1,0,0)] - sage: [D4(x).branch(B3,rule="symmetric") for x in D4.fundamental_weights()] + sage: [D4(x).branch(B3,rule='symmetric') for x in D4.fundamental_weights()] [B3(0,0,0) + B3(1,0,0), B3(1,0,0) + B3(1,1,0), B3(1/2,1/2,1/2), B3(1/2,1/2,1/2)] - sage: [D4(x).branch(G2,rule="symmetric") for x in D4.fundamental_weights()] + sage: [D4(x).branch(G2,rule='symmetric') for x in D4.fundamental_weights()] [G2(0,0,0) + G2(1,0,-1), 2*G2(1,0,-1) + G2(2,-1,-1), G2(0,0,0) + G2(1,0,-1), G2(0,0,0) + G2(1,0,-1)] - sage: [E6(fw).branch(F4,rule="symmetric") for fw in E6.fundamental_weights()] # long time (4s) + sage: [E6(fw).branch(F4,rule='symmetric') for fw in E6.fundamental_weights()] # long time (4s) [F4(0,0,0,0) + F4(0,0,0,1), F4(0,0,0,1) + F4(1,0,0,0), F4(0,0,0,1) + F4(1,0,0,0) + F4(0,0,1,0), F4(1,0,0,0) + 2*F4(0,0,1,0) + F4(1,0,0,1) + F4(0,1,0,0), F4(0,0,0,1) + F4(1,0,0,0) + F4(0,0,1,0), F4(0,0,0,0) + F4(0,0,0,1)] - sage: E6=WeylCharacterRing("E6",style="coroots") - sage: C4=WeylCharacterRing("C4",style="coroots") + sage: E6=WeylCharacterRing("E6",style='coroots') + sage: C4=WeylCharacterRing("C4",style='coroots') sage: chi = E6(1,0,0,0,0,0); chi.degree() 27 - sage: chi.branch(C4,rule="symmetric") + sage: chi.branch(C4,rule='symmetric') C4(0,1,0,0) .. RUBRIC:: Extended Type @@ -437,60 +437,60 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: [B3(x).branch(D3,rule="extended") for x in B3.fundamental_weights()] + sage: [B3(x).branch(D3,rule='extended') for x in B3.fundamental_weights()] [D3(0,0,0) + D3(1,0,0), D3(1,0,0) + D3(1,1,0), D3(1/2,1/2,-1/2) + D3(1/2,1/2,1/2)] - sage: [G2(w).branch(A2, rule="extended") for w in G2.fundamental_weights()] + sage: [G2(w).branch(A2, rule='extended') for w in G2.fundamental_weights()] [A2(0,0,0) + A2(1/3,1/3,-2/3) + A2(2/3,-1/3,-1/3), A2(1/3,1/3,-2/3) + A2(2/3,-1/3,-1/3) + A2(1,0,-1)] - sage: [F4(fw).branch(B4,rule="extended") for fw in F4.fundamental_weights()] # long time (2s) + sage: [F4(fw).branch(B4,rule='extended') for fw in F4.fundamental_weights()] # long time (2s) [B4(1/2,1/2,1/2,1/2) + B4(1,1,0,0), B4(1,1,0,0) + B4(1,1,1,0) + B4(3/2,1/2,1/2,1/2) + B4(3/2,3/2,1/2,1/2) + B4(2,1,1,0), B4(1/2,1/2,1/2,1/2) + B4(1,0,0,0) + B4(1,1,0,0) + B4(1,1,1,0) + B4(3/2,1/2,1/2,1/2), B4(0,0,0,0) + B4(1/2,1/2,1/2,1/2) + B4(1,0,0,0)] - sage: E6 = WeylCharacterRing("E6", style="coroots") - sage: A2xA2xA2 = WeylCharacterRing("A2xA2xA2",style="coroots") - sage: A5xA1 = WeylCharacterRing("A5xA1",style="coroots") - sage: G2 = WeylCharacterRing("G2", style="coroots") - sage: A1xA1 = WeylCharacterRing("A1xA1", style="coroots") - sage: F4 = WeylCharacterRing("F4",style="coroots") - sage: A3xA1 = WeylCharacterRing("A3xA1", style="coroots") - sage: A2xA2 = WeylCharacterRing("A2xA2", style="coroots") - sage: A1xC3 = WeylCharacterRing("A1xC3",style="coroots") - sage: E6(1,0,0,0,0,0).branch(A5xA1,rule="extended") # (0.7s) + sage: E6 = WeylCharacterRing("E6", style='coroots') + sage: A2xA2xA2 = WeylCharacterRing("A2xA2xA2",style='coroots') + sage: A5xA1 = WeylCharacterRing("A5xA1",style='coroots') + sage: G2 = WeylCharacterRing("G2", style='coroots') + sage: A1xA1 = WeylCharacterRing("A1xA1", style='coroots') + sage: F4 = WeylCharacterRing("F4",style='coroots') + sage: A3xA1 = WeylCharacterRing("A3xA1", style='coroots') + sage: A2xA2 = WeylCharacterRing("A2xA2", style='coroots') + sage: A1xC3 = WeylCharacterRing("A1xC3",style='coroots') + sage: E6(1,0,0,0,0,0).branch(A5xA1,rule='extended') # (0.7s) A5xA1(0,0,0,1,0,0) + A5xA1(1,0,0,0,0,1) - sage: E6(1,0,0,0,0,0).branch(A2xA2xA2, rule="extended") # (0.7s) + sage: E6(1,0,0,0,0,0).branch(A2xA2xA2, rule='extended') # (0.7s) A2xA2xA2(0,1,1,0,0,0) + A2xA2xA2(1,0,0,0,0,1) + A2xA2xA2(0,0,0,1,1,0) - sage: E7 = WeylCharacterRing("E7",style="coroots") - sage: A7 = WeylCharacterRing("A7",style="coroots") - sage: E7(1,0,0,0,0,0,0).branch(A7,rule="extended") + sage: E7 = WeylCharacterRing("E7",style='coroots') + sage: A7 = WeylCharacterRing("A7",style='coroots') + sage: E7(1,0,0,0,0,0,0).branch(A7,rule='extended') A7(0,0,0,1,0,0,0) + A7(1,0,0,0,0,0,1) - sage: D6xA1 = WeylCharacterRing("D6xA1",style="coroots") - sage: E7(1,0,0,0,0,0,0).branch(D6xA1,rule="extended") + sage: D6xA1 = WeylCharacterRing("D6xA1",style='coroots') + sage: E7(1,0,0,0,0,0,0).branch(D6xA1,rule='extended') D6xA1(0,0,0,0,1,0,1) + D6xA1(0,1,0,0,0,0,0) + D6xA1(0,0,0,0,0,0,2) - sage: A5xA2 = WeylCharacterRing("A5xA2",style="coroots") - sage: E7(1,0,0,0,0,0,0).branch(A5xA2,rule="extended") + sage: A5xA2 = WeylCharacterRing("A5xA2",style='coroots') + sage: E7(1,0,0,0,0,0,0).branch(A5xA2,rule='extended') A5xA2(0,0,0,1,0,1,0) + A5xA2(0,1,0,0,0,0,1) + A5xA2(1,0,0,0,1,0,0) + A5xA2(0,0,0,0,0,1,1) - sage: E8 = WeylCharacterRing("E8",style="coroots") - sage: D8 = WeylCharacterRing("D8",style="coroots") - sage: A8 = WeylCharacterRing("A8",style="coroots") - sage: E8(0,0,0,0,0,0,0,1).branch(D8,rule="extended") # long time (0.56s) + sage: E8 = WeylCharacterRing("E8",style='coroots') + sage: D8 = WeylCharacterRing("D8",style='coroots') + sage: A8 = WeylCharacterRing("A8",style='coroots') + sage: E8(0,0,0,0,0,0,0,1).branch(D8,rule='extended') # long time (0.56s) D8(0,0,0,0,0,0,1,0) + D8(0,1,0,0,0,0,0,0) - sage: E8(0,0,0,0,0,0,0,1).branch(A8,rule="extended") # long time (0.73s) + sage: E8(0,0,0,0,0,0,0,1).branch(A8,rule='extended') # long time (0.73s) A8(0,0,0,0,0,1,0,0) + A8(0,0,1,0,0,0,0,0) + A8(1,0,0,0,0,0,0,1) - sage: F4(1,0,0,0).branch(A1xC3,rule="extended") # (0.05s) + sage: F4(1,0,0,0).branch(A1xC3,rule='extended') # (0.05s) A1xC3(1,0,0,1) + A1xC3(2,0,0,0) + A1xC3(0,2,0,0) - sage: G2(0,1).branch(A1xA1, rule="extended") + sage: G2(0,1).branch(A1xA1, rule='extended') A1xA1(2,0) + A1xA1(3,1) + A1xA1(0,2) - sage: F4(0,0,0,1).branch(A2xA2, rule="extended") # (0.4s) + sage: F4(0,0,0,1).branch(A2xA2, rule='extended') # (0.4s) A2xA2(0,1,0,1) + A2xA2(1,0,1,0) + A2xA2(0,0,1,1) - sage: F4(0,0,0,1).branch(A3xA1,rule="extended") # (0.34s) + sage: F4(0,0,0,1).branch(A3xA1,rule='extended') # (0.34s) A3xA1(0,0,0,0) + A3xA1(0,0,1,1) + A3xA1(0,1,0,0) + A3xA1(1,0,0,1) + A3xA1(0,0,0,2) - sage: D4=WeylCharacterRing("D4",style="coroots") - sage: D2xD2=WeylCharacterRing("D2xD2",style="coroots") # We get D4 => A1xA1xA1xA1 by remembering that A1xA1 = D2. - sage: [D4(fw).branch(D2xD2, rule="extended") for fw in D4.fundamental_weights()] + sage: D4=WeylCharacterRing("D4",style='coroots') + sage: D2xD2=WeylCharacterRing("D2xD2",style='coroots') # We get D4 => A1xA1xA1xA1 by remembering that A1xA1 = D2. + sage: [D4(fw).branch(D2xD2, rule='extended') for fw in D4.fundamental_weights()] [D2xD2(1,1,0,0) + D2xD2(0,0,1,1), D2xD2(2,0,0,0) + D2xD2(0,2,0,0) + D2xD2(1,1,1,1) + D2xD2(0,0,2,0) + D2xD2(0,0,0,2), D2xD2(1,0,0,1) + D2xD2(0,1,1,0), @@ -543,31 +543,31 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A5=WeylCharacterRing("A5", style="coroots") - sage: A2xA1=WeylCharacterRing("A2xA1", style="coroots") - sage: [A5(hwv).branch(A2xA1, rule="tensor") for hwv in A5.fundamental_weights()] + sage: A5=WeylCharacterRing("A5", style='coroots') + sage: A2xA1=WeylCharacterRing("A2xA1", style='coroots') + sage: [A5(hwv).branch(A2xA1, rule='tensor') for hwv in A5.fundamental_weights()] [A2xA1(1,0,1), A2xA1(0,1,2) + A2xA1(2,0,0), A2xA1(1,1,1) + A2xA1(0,0,3), A2xA1(1,0,2) + A2xA1(0,2,0), A2xA1(0,1,1)] - sage: B4=WeylCharacterRing("B4",style="coroots") - sage: B1xB1=WeylCharacterRing("B1xB1",style="coroots") - sage: [B4(f).branch(B1xB1,rule="tensor") for f in B4.fundamental_weights()] + sage: B4=WeylCharacterRing("B4",style='coroots') + sage: B1xB1=WeylCharacterRing("B1xB1",style='coroots') + sage: [B4(f).branch(B1xB1,rule='tensor') for f in B4.fundamental_weights()] [B1xB1(2,2), B1xB1(2,0) + B1xB1(2,4) + B1xB1(4,2) + B1xB1(0,2), B1xB1(2,0) + B1xB1(2,2) + B1xB1(2,4) + B1xB1(4,2) + B1xB1(4,4) + B1xB1(6,0) + B1xB1(0,2) + B1xB1(0,6), B1xB1(1,3) + B1xB1(3,1)] - sage: D4=WeylCharacterRing("D4",style="coroots") - sage: C2xC1=WeylCharacterRing("C2xC1",style="coroots") - sage: [D4(f).branch(C2xC1,rule="tensor") for f in D4.fundamental_weights()] + sage: D4=WeylCharacterRing("D4",style='coroots') + sage: C2xC1=WeylCharacterRing("C2xC1",style='coroots') + sage: [D4(f).branch(C2xC1,rule='tensor') for f in D4.fundamental_weights()] [C2xC1(1,0,1), C2xC1(0,1,2) + C2xC1(2,0,0) + C2xC1(0,0,2), C2xC1(1,0,1), C2xC1(0,1,0) + C2xC1(0,0,2)] - sage: C3=WeylCharacterRing("C3",style="coroots") - sage: B1xC1=WeylCharacterRing("B1xC1",style="coroots") - sage: [C3(f).branch(B1xC1,rule="tensor") for f in C3.fundamental_weights()] + sage: C3=WeylCharacterRing("C3",style='coroots') + sage: B1xC1=WeylCharacterRing("B1xC1",style='coroots') + sage: [C3(f).branch(B1xC1,rule='tensor') for f in C3.fundamental_weights()] [B1xC1(2,1), B1xC1(2,2) + B1xC1(4,0), B1xC1(4,1) + B1xC1(0,3)] .. RUBRIC:: Symmetric Power @@ -595,12 +595,12 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A1=WeylCharacterRing("A1",style="coroots") - sage: B3=WeylCharacterRing("B3",style="coroots") - sage: C3=WeylCharacterRing("C3",style="coroots") - sage: [B3(fw).branch(A1,rule="symmetric_power") for fw in B3.fundamental_weights()] + sage: A1=WeylCharacterRing("A1",style='coroots') + sage: B3=WeylCharacterRing("B3",style='coroots') + sage: C3=WeylCharacterRing("C3",style='coroots') + sage: [B3(fw).branch(A1,rule='symmetric_power') for fw in B3.fundamental_weights()] [A1(6), A1(2) + A1(6) + A1(10), A1(0) + A1(6)] - sage: [C3(fw).branch(A1,rule="symmetric_power") for fw in C3.fundamental_weights()] + sage: [C3(fw).branch(A1,rule='symmetric_power') for fw in C3.fundamental_weights()] [A1(5), A1(4) + A1(8), A1(3) + A1(9)] .. RUBRIC:: Miscellaneous @@ -646,58 +646,57 @@ def branch_weyl_character(chi, R, S, rule="default"): https://doc.sagemath.org/html/en/thematic_tutorials/lie.html - EXAMPLES:: sage: G2 = WeylCharacterRing("G2") sage: [fw1, fw2, fw3] = B3.fundamental_weights() - sage: B3(fw1+fw3).branch(G2, rule="miscellaneous") + sage: B3(fw1+fw3).branch(G2, rule='miscellaneous') G2(1,0,-1) + G2(2,-1,-1) + G2(2,0,-2) - sage: E6 = WeylCharacterRing("E6",style="coroots") - sage: G2 = WeylCharacterRing("G2",style="coroots") + sage: E6 = WeylCharacterRing("E6",style='coroots') + sage: G2 = WeylCharacterRing("G2",style='coroots') sage: E6(1,0,0,0,0,0).branch(G2,"miscellaneous") G2(2,0) - sage: A2=WeylCharacterRing("A2",style="coroots") - sage: E6(1,0,0,0,0,0).branch(A2,rule="miscellaneous") + sage: A2=WeylCharacterRing("A2",style='coroots') + sage: E6(1,0,0,0,0,0).branch(A2,rule='miscellaneous') A2(2,2) - sage: E6(0,1,0,0,0,0).branch(A2,rule="miscellaneous") + sage: E6(0,1,0,0,0,0).branch(A2,rule='miscellaneous') A2(1,1) + A2(1,4) + A2(4,1) sage: E6(0,0,0,0,0,2).branch(G2,"miscellaneous") # long time (0.59s) G2(0,0) + G2(2,0) + G2(1,1) + G2(0,2) + G2(4,0) - sage: F4=WeylCharacterRing("F4",style="coroots") - sage: G2xA1=WeylCharacterRing("G2xA1",style="coroots") - sage: F4(0,0,1,0).branch(G2xA1,rule="miscellaneous") + sage: F4=WeylCharacterRing("F4",style='coroots') + sage: G2xA1=WeylCharacterRing("G2xA1",style='coroots') + sage: F4(0,0,1,0).branch(G2xA1,rule='miscellaneous') G2xA1(1,0,0) + G2xA1(1,0,2) + G2xA1(1,0,4) + G2xA1(1,0,6) + G2xA1(0,1,4) + G2xA1(2,0,2) + G2xA1(0,0,2) + G2xA1(0,0,6) - sage: E6 = WeylCharacterRing("E6",style="coroots") - sage: A2xG2 = WeylCharacterRing("A2xG2",style="coroots") - sage: E6(1,0,0,0,0,0).branch(A2xG2,rule="miscellaneous") + sage: E6 = WeylCharacterRing("E6",style='coroots') + sage: A2xG2 = WeylCharacterRing("A2xG2",style='coroots') + sage: E6(1,0,0,0,0,0).branch(A2xG2,rule='miscellaneous') A2xG2(0,1,1,0) + A2xG2(2,0,0,0) - sage: E7=WeylCharacterRing("E7",style="coroots") - sage: G2xC3=WeylCharacterRing("G2xC3",style="coroots") - sage: E7(0,1,0,0,0,0,0).branch(G2xC3,rule="miscellaneous") # long time (1.84s) + sage: E7=WeylCharacterRing("E7",style='coroots') + sage: G2xC3=WeylCharacterRing("G2xC3",style='coroots') + sage: E7(0,1,0,0,0,0,0).branch(G2xC3,rule='miscellaneous') # long time (1.84s) G2xC3(1,0,1,0,0) + G2xC3(1,0,1,1,0) + G2xC3(0,1,0,0,1) + G2xC3(2,0,1,0,0) + G2xC3(0,0,1,1,0) - sage: F4xA1=WeylCharacterRing("F4xA1",style="coroots") + sage: F4xA1=WeylCharacterRing("F4xA1",style='coroots') sage: E7(0,0,0,0,0,0,1).branch(F4xA1,"miscellaneous") F4xA1(0,0,0,1,1) + F4xA1(0,0,0,0,3) - sage: A1xA1=WeylCharacterRing("A1xA1",style="coroots") - sage: E7(0,0,0,0,0,0,1).branch(A1xA1,rule="miscellaneous") + sage: A1xA1=WeylCharacterRing("A1xA1",style='coroots') + sage: E7(0,0,0,0,0,0,1).branch(A1xA1,rule='miscellaneous') A1xA1(2,5) + A1xA1(4,1) + A1xA1(6,3) - sage: A2=WeylCharacterRing("A2",style="coroots") - sage: E7(0,0,0,0,0,0,1).branch(A2,rule="miscellaneous") + sage: A2=WeylCharacterRing("A2",style='coroots') + sage: E7(0,0,0,0,0,0,1).branch(A2,rule='miscellaneous') A2(0,6) + A2(6,0) - sage: G2xA1=WeylCharacterRing("G2xA1",style="coroots") - sage: E7(1,0,0,0,0,0,0).branch(G2xA1,rule="miscellaneous") + sage: G2xA1=WeylCharacterRing("G2xA1",style='coroots') + sage: E7(1,0,0,0,0,0,0).branch(G2xA1,rule='miscellaneous') G2xA1(1,0,4) + G2xA1(0,1,0) + G2xA1(2,0,2) + G2xA1(0,0,2) - sage: E8 = WeylCharacterRing("E8",style="coroots") - sage: G2xF4 = WeylCharacterRing("G2xF4",style="coroots") - sage: E8(0,0,0,0,0,0,0,1).branch(G2xF4,rule="miscellaneous") # long time (0.76s) + sage: E8 = WeylCharacterRing("E8",style='coroots') + sage: G2xF4 = WeylCharacterRing("G2xF4",style='coroots') + sage: E8(0,0,0,0,0,0,0,1).branch(G2xF4,rule='miscellaneous') # long time (0.76s) G2xF4(1,0,0,0,0,1) + G2xF4(0,1,0,0,0,0) + G2xF4(0,0,1,0,0,0) - sage: E8=WeylCharacterRing("E8",style="coroots") - sage: A1xA2=WeylCharacterRing("A1xA2",style="coroots") - sage: E8(0,0,0,0,0,0,0,1).branch(A1xA2,rule="miscellaneous") # long time (0.76s) + sage: E8=WeylCharacterRing("E8",style='coroots') + sage: A1xA2=WeylCharacterRing("A1xA2",style='coroots') + sage: E8(0,0,0,0,0,0,0,1).branch(A1xA2,rule='miscellaneous') # long time (0.76s) A1xA2(2,0,0) + A1xA2(2,2,2) + A1xA2(4,0,3) + A1xA2(4,3,0) + A1xA2(6,1,1) + A1xA2(0,1,1) - sage: B2=WeylCharacterRing("B2",style="coroots") - sage: E8(0,0,0,0,0,0,0,1).branch(B2,rule="miscellaneous") # long time (0.53s) + sage: B2=WeylCharacterRing("B2",style='coroots') + sage: E8(0,0,0,0,0,0,0,1).branch(B2,rule='miscellaneous') # long time (0.53s) B2(0,2) + B2(0,6) + B2(3,2) .. RUBRIC:: A1 maximal subgroups of exceptional groups @@ -713,24 +712,24 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A1=WeylCharacterRing("A1",style="coroots") - sage: G2=WeylCharacterRing("G2",style="coroots") - sage: F4=WeylCharacterRing("F4",style="coroots") - sage: E7=WeylCharacterRing("E7",style="coroots") - sage: E8=WeylCharacterRing("E8",style="coroots") - sage: [G2(f).branch(A1,rule="i") for f in G2.fundamental_weights()] + sage: A1=WeylCharacterRing("A1",style='coroots') + sage: G2=WeylCharacterRing("G2",style='coroots') + sage: F4=WeylCharacterRing("F4",style='coroots') + sage: E7=WeylCharacterRing("E7",style='coroots') + sage: E8=WeylCharacterRing("E8",style='coroots') + sage: [G2(f).branch(A1,rule='i') for f in G2.fundamental_weights()] [A1(6), A1(2) + A1(10)] - sage: F4(1,0,0,0).branch(A1,rule="ii") + sage: F4(1,0,0,0).branch(A1,rule='ii') A1(2) + A1(10) + A1(14) + A1(22) - sage: E7(0,0,0,0,0,0,1).branch(A1,rule="iii") + sage: E7(0,0,0,0,0,0,1).branch(A1,rule='iii') A1(9) + A1(17) + A1(27) - sage: E7(0,0,0,0,0,0,1).branch(A1,rule="iv") + sage: E7(0,0,0,0,0,0,1).branch(A1,rule='iv') A1(5) + A1(11) + A1(15) + A1(21) - sage: E8(0,0,0,0,0,0,0,1).branch(A1,rule="v") # long time (0.6s) + sage: E8(0,0,0,0,0,0,0,1).branch(A1,rule='v') # long time (0.6s) A1(2) + A1(14) + A1(22) + A1(26) + A1(34) + A1(38) + A1(46) + A1(58) - sage: E8(0,0,0,0,0,0,0,1).branch(A1,rule="vi") # long time (0.6s) + sage: E8(0,0,0,0,0,0,0,1).branch(A1,rule='vi') # long time (0.6s) A1(2) + A1(10) + A1(14) + A1(18) + A1(22) + A1(26) + A1(28) + A1(34) + A1(38) + A1(46) - sage: E8(0,0,0,0,0,0,0,1).branch(A1,rule="vii") # long time (0.6s) + sage: E8(0,0,0,0,0,0,0,1).branch(A1,rule='vii') # long time (0.6s) A1(2) + A1(6) + A1(10) + A1(14) + A1(16) + A1(18) + 2*A1(22) + A1(26) + A1(28) + A1(34) + A1(38) .. RUBRIC:: Branching Rules From Plethysms @@ -760,7 +759,7 @@ def branch_weyl_character(chi, R, S, rule="default"): :: - sage: A1=WeylCharacterRing("A1",style="coroots") + sage: A1=WeylCharacterRing("A1",style='coroots') sage: chi=A1([5]) sage: chi.degree() 6 @@ -774,7 +773,7 @@ def branch_weyl_character(chi, R, S, rule="default"): :: - sage: C3 = WeylCharacterRing("C3",style="coroots") + sage: C3 = WeylCharacterRing("C3",style='coroots') sage: sym5rule = branching_rule_from_plethysm(chi,"C3") sage: [C3(hwv).branch(A1,rule=sym5rule) for hwv in C3.fundamental_weights()] [A1(5), A1(4) + A1(8), A1(3) + A1(9)] @@ -785,8 +784,8 @@ def branch_weyl_character(chi, R, S, rule="default"): :: - sage: G2 = WeylCharacterRing("G2",style="coroots") - sage: D7 = WeylCharacterRing("D7",style="coroots") + sage: G2 = WeylCharacterRing("G2",style='coroots') + sage: D7 = WeylCharacterRing("D7",style='coroots') sage: ad=G2(0,1); ad.degree(); ad.frobenius_schur_indicator() 14 1 @@ -829,15 +828,15 @@ def branch_weyl_character(chi, R, S, rule="default"): sage: B2 = WeylCharacterRing("B2") sage: C2 = WeylCharacterRing("C2") - sage: [B2(x).branch(C2, rule="isomorphic") for x in B2.fundamental_weights()] + sage: [B2(x).branch(C2, rule='isomorphic') for x in B2.fundamental_weights()] [C2(1,1), C2(1,0)] - sage: [C2(x).branch(B2, rule="isomorphic") for x in C2.fundamental_weights()] + sage: [C2(x).branch(B2, rule='isomorphic') for x in C2.fundamental_weights()] [B2(1/2,1/2), B2(1,0)] sage: D3 = WeylCharacterRing("D3") sage: A3 = WeylCharacterRing("A3") - sage: [A3(x).branch(D3,rule="isomorphic") for x in A3.fundamental_weights()] + sage: [A3(x).branch(D3,rule='isomorphic') for x in A3.fundamental_weights()] [D3(1/2,1/2,1/2), D3(1,0,0), D3(1/2,1/2,-1/2)] - sage: [D3(x).branch(A3,rule="isomorphic") for x in D3.fundamental_weights()] + sage: [D3(x).branch(A3,rule='isomorphic') for x in D3.fundamental_weights()] [A3(1/2,1/2,-1/2,-1/2), A3(1/4,1/4,1/4,-3/4), A3(3/4,-1/4,-1/4,-1/4)] Here `A_3(x,y,z,w)` can be understood as a representation of `SL(4)`. @@ -853,36 +852,36 @@ def branch_weyl_character(chi, R, S, rule="default"): In cases like this you might prefer ``style="coroots"``:: - sage: A3 = WeylCharacterRing("A3",style="coroots") - sage: D3 = WeylCharacterRing("D3",style="coroots") + sage: A3 = WeylCharacterRing("A3",style='coroots') + sage: D3 = WeylCharacterRing("D3",style='coroots') sage: [D3(fw) for fw in D3.fundamental_weights()] [D3(1,0,0), D3(0,1,0), D3(0,0,1)] - sage: [D3(fw).branch(A3,rule="isomorphic") for fw in D3.fundamental_weights()] + sage: [D3(fw).branch(A3,rule='isomorphic') for fw in D3.fundamental_weights()] [A3(0,1,0), A3(0,0,1), A3(1,0,0)] - sage: D2 = WeylCharacterRing("D2", style="coroots") - sage: A1xA1 = WeylCharacterRing("A1xA1", style="coroots") - sage: [D2(fw).branch(A1xA1,rule="isomorphic") for fw in D2.fundamental_weights()] + sage: D2 = WeylCharacterRing("D2", style='coroots') + sage: A1xA1 = WeylCharacterRing("A1xA1", style='coroots') + sage: [D2(fw).branch(A1xA1,rule='isomorphic') for fw in D2.fundamental_weights()] [A1xA1(1,0), A1xA1(0,1)] .. RUBRIC:: Branching From a Reducible WeylCharacterRing If the Cartan Type of R is reducible, we may project a character onto any of the components, or any combination of components. The rule to - project on the first component is specified by the string ``"proj1"``, + project on the first component is specified by the string ``'proj1'``, the rule to project on the second component is ``"proj2". To - project on the first and third components, use ``"proj13"`` and so on. + project on the first and third components, use ``'proj13'`` and so on. EXAMPLES:: - sage: A2xG2=WeylCharacterRing("A2xG2",style="coroots") - sage: A2=WeylCharacterRing("A2",style="coroots") - sage: G2=WeylCharacterRing("G2",style="coroots") - sage: A2xG2(1,0,1,0).branch(A2,rule="proj1") + sage: A2xG2=WeylCharacterRing("A2xG2",style='coroots') + sage: A2=WeylCharacterRing("A2",style='coroots') + sage: G2=WeylCharacterRing("G2",style='coroots') + sage: A2xG2(1,0,1,0).branch(A2,rule='proj1') 7*A2(1,0) - sage: A2xG2(1,0,1,0).branch(G2,rule="proj2") + sage: A2xG2(1,0,1,0).branch(G2,rule='proj2') 3*G2(1,0) - sage: A2xA2xG2=WeylCharacterRing("A2xA2xG2",style="coroots") - sage: A2xA2xG2(0,1,1,1,0,1).branch(A2xG2,rule="proj13") + sage: A2xA2xG2=WeylCharacterRing("A2xA2xG2",style='coroots') + sage: A2xA2xG2(0,1,1,1,0,1).branch(A2xG2,rule='proj13') 8*A2xG2(0,1,0,1) A more general way of specifying a branching rule from a reducible type is @@ -895,8 +894,8 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: D4 = WeylCharacterRing("D4",style="coroots") - sage: A1xA1xA1xA1 = WeylCharacterRing("A1xA1xA1xA1",style="coroots") + sage: D4 = WeylCharacterRing("D4",style='coroots') + sage: A1xA1xA1xA1 = WeylCharacterRing("A1xA1xA1xA1",style='coroots') sage: b = branching_rule("D2","A1xA1","isomorphic") sage: br = branching_rule("D4","D2xD2","extended")*branching_rule("D2xD2","A1xA1xA1xA1",[b,b]) sage: [D4(fw).branch(A1xA1xA1xA1,rule=br) for fw in D4.fundamental_weights()] @@ -917,12 +916,12 @@ def branch_weyl_character(chi, R, S, rule="default"): EXAMPLES:: - sage: A3xA2=WeylCharacterRing("A3xA2",style="coroots") - sage: A3=WeylCharacterRing("A3",style="coroots") + sage: A3xA2=WeylCharacterRing("A3xA2",style='coroots') + sage: A3=WeylCharacterRing("A3",style='coroots') sage: chi = A3xA2(0,1,0,1,0) sage: chi.branch(A3,rule=["identity","omit"]) 3*A3(0,1,0) - sage: A2=WeylCharacterRing("A2",style="coroots") + sage: A2=WeylCharacterRing("A2",style='coroots') sage: chi.branch(A2,rule=["omit","identity"]) 6*A2(1,0) @@ -931,12 +930,12 @@ def branch_weyl_character(chi, R, S, rule="default"): branching rule is equivalent to the tensor product, as the example shows:: - sage: G2=WeylCharacterRing("G2",style="coroots") - sage: G2xG2=WeylCharacterRing("G2xG2",style="coroots") - sage: G2=WeylCharacterRing("G2",style="coroots") - sage: G2xG2(1,0,0,1).branch(G2,rule="diagonal") + sage: G2=WeylCharacterRing("G2",style='coroots') + sage: G2xG2=WeylCharacterRing("G2xG2",style='coroots') + sage: G2=WeylCharacterRing("G2",style='coroots') + sage: G2xG2(1,0,0,1).branch(G2,rule='diagonal') G2(1,0) + G2(2,0) + G2(1,1) - sage: G2xG2(1,0,0,1).branch(G2,rule="diagonal") == G2(1,0)*G2(0,1) + sage: G2xG2(1,0,0,1).branch(G2,rule='diagonal') == G2(1,0)*G2(0,1) True .. RUBRIC:: Writing Your Own (Branching) Rules @@ -976,7 +975,7 @@ def rule(x): sage: br = BranchingRule("A3", "C2", lambda x: [x[0]-x[3],x[1]-x[2]], "homemade"); br homemade branching rule A3 => C2 - sage: [A3,C2]=[WeylCharacterRing(x,style="coroots") for x in ["A3","C2"]] + sage: [A3,C2]=[WeylCharacterRing(x,style='coroots') for x in ["A3","C2"]] sage: A3(0,1,0).branch(C2,rule=br) C2(0,0) + C2(0,1) """ @@ -1011,13 +1010,13 @@ class BranchingRule(SageObject): A class for branching rules. """ - def __init__(self, R, S, f, name="default", intermediate_types=[], + def __init__(self, R, S, f, name='default', intermediate_types=[], intermediate_names=[]): """ INPUT: - ``R``, ``S`` -- CartanTypes - - ``f`` -- a function from the weight lattice of R to the weight lattice of S + - ``f`` -- a function from the weight lattice of R to the weight lattice of S """ self._R = CartanType(R) self._S = CartanType(S) @@ -1035,7 +1034,7 @@ def _repr_(self): sage: branching_rule("E6","F4","symmetric") symmetric branching rule E6 => F4 - sage: b=branching_rule("F4","B3",rule="levi")*branching_rule("B3","G2",rule="miscellaneous"); b + sage: b=branching_rule("F4","B3",rule='levi')*branching_rule("B3","G2",rule='miscellaneous'); b composite branching rule F4 => (levi) B3 => (miscellaneous) G2 """ R_repr = self._R._repr_(compact=True) @@ -1091,7 +1090,7 @@ def __eq__(self, other): sage: b2 = BranchingRule("A2","A2",lambda x: x, "identity map") sage: b1 == b2 False - sage: A2 = WeylCharacterRing("A2",style="coroots") + sage: A2 = WeylCharacterRing("A2",style='coroots') sage: [A2(f).branch(A2,rule=b1) == A2(f).branch(A2,rule=b2) for f in A2.fundamental_weights()] [True, True] """ @@ -1116,7 +1115,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Test inequality + Test inequality. EXAMPLES:: @@ -1131,9 +1130,9 @@ def __mul__(self, other): """ EXAMPLES:: - sage: E6 = WeylCharacterRing("E6",style="coroots") - sage: A5 = WeylCharacterRing("A5",style="coroots") - sage: br = branching_rule("E6","A5xA1",rule="extended")*branching_rule("A5xA1","A5",rule="proj1"); br + sage: E6 = WeylCharacterRing("E6",style='coroots') + sage: A5 = WeylCharacterRing("A5",style='coroots') + sage: br = branching_rule("E6","A5xA1",rule='extended')*branching_rule("A5xA1","A5",rule='proj1'); br composite branching rule E6 => (extended) A5xA1 => (proj1) A5 sage: E6(1,0,0,0,0,0).branch(A5,rule=br) A5(0,0,0,1,0) + 2*A5(1,0,0,0,0) @@ -1175,8 +1174,8 @@ def Stype(self): return self._S def describe(self, verbose=False, debug=False, no_r=False): - """ - Describes how extended roots restrict under self. + r""" + Describe how extended roots restrict under ``self``. EXAMPLES:: @@ -1199,9 +1198,9 @@ def describe(self, verbose=False, debug=False, no_r=False): For more detailed information use verbose=True In this example, `0` is the affine root, that is, the negative - of the highest root, for `"G2"`. If `i => j` is printed, this - means that the i-th simple (or affine) root of the ambient - group restricts to the j-th simple root of the subgroup. + of the highest root, for `"G2"`. If `i \geq j` is printed, this + means that the `i`-th simple (or affine) root of the ambient + group restricts to the `j`-th simple root of the subgroup. For reference the Dynkin diagrams are also printed. The extended Dynkin diagram of the ambient group is printed if the affine root restricts to a simple root. More information @@ -1269,24 +1268,23 @@ def branch(self, chi, style=None): """ INPUT: - - ``chi`` -- A character of the WeylCharacterRing with Cartan type self.Rtype(). + - ``chi`` -- a character of the WeylCharacterRing with Cartan type self.Rtype() Returns the branched character. EXAMPLES:: - sage: G2=WeylCharacterRing("G2",style="coroots") + sage: G2=WeylCharacterRing("G2",style='coroots') sage: chi=G2(1,1); chi.degree() 64 sage: b=G2.maximal_subgroup("A2"); b extended branching rule G2 => A2 sage: b.branch(chi) A2(0,1) + A2(1,0) + A2(0,2) + 2*A2(1,1) + A2(2,0) + A2(1,2) + A2(2,1) - sage: A2=WeylCharacterRing("A2",style="coroots"); A2 + sage: A2=WeylCharacterRing("A2",style='coroots'); A2 The Weyl Character Ring of Type A2 with Integer Ring coefficients sage: chi.branch(A2,rule=b) A2(0,1) + A2(1,0) + A2(0,2) + 2*A2(1,1) + A2(2,0) + A2(1,2) + A2(2,1) - """ from sage.combinat.root_system.weyl_characters import WeylCharacterRing if style is None: @@ -1295,9 +1293,9 @@ def branch(self, chi, style=None): return chi.branch(S, rule=self) -def branching_rule(Rtype, Stype, rule="default"): +def branching_rule(Rtype, Stype, rule='default'): """ - Creates a branching rule. + Create a branching rule. INPUT: @@ -1305,8 +1303,8 @@ def branching_rule(Rtype, Stype, rule="default"): - ``S`` -- the Weyl Character Ring of `H` - - ``rule`` -- a string describing the branching rule as a map from - the weight space of `S` to the weight space of `R`. + - ``rule`` -- string describing the branching rule as a map from + the weight space of `S` to the weight space of `R` If the rule parameter is omitted, in some cases, a default rule is supplied. See :func:`~sage.combinat.root_system.branching_rules.branch_weyl_character`. @@ -1319,10 +1317,10 @@ def branching_rule(Rtype, Stype, rule="default"): """ if rule == "plethysm": try: - S = sage.combinat.root_system.weyl_characters.WeylCharacterRing(Stype.split("(")[0], style="coroots") + S = sage.combinat.root_system.weyl_characters.WeylCharacterRing(Stype.split("(")[0], style='coroots') chi = S(eval("("+Stype.split("(")[1])) except Exception: - S = sage.combinat.root_system.weyl_characters.WeylCharacterRing(Stype.split(".")[0], style="coroots") + S = sage.combinat.root_system.weyl_characters.WeylCharacterRing(Stype.split(".")[0], style='coroots') chi = eval("S." + Stype.split(".")[1]) return branching_rule_from_plethysm(chi, Rtype) Rtype = CartanType(Rtype) @@ -1385,24 +1383,24 @@ def br(x): if not Rtype.is_compound(): if Stype.is_compound() and s == r-1: try: - return branching_rule(Rtype, Stype, rule="levi") + return branching_rule(Rtype, Stype, rule='levi') except Exception: pass if Rtype[0] == "A": if Stype[0] == "B" and r == 2*s: - return branching_rule(Rtype, Stype, rule="symmetric") + return branching_rule(Rtype, Stype, rule='symmetric') elif Stype[0] == "C" and r == 2*s-1: - return branching_rule(Rtype, Stype, rule="symmetric") + return branching_rule(Rtype, Stype, rule='symmetric') elif Stype[0] == "D" and r == 2*s-1: - return branching_rule(Rtype, Stype, rule="symmetric") + return branching_rule(Rtype, Stype, rule='symmetric') elif Rtype[0] == "B" and Stype[0] == "D" and r == s: - return branching_rule(Rtype, Stype, rule="extended") + return branching_rule(Rtype, Stype, rule='extended') elif Rtype[0] == "D" and Stype[0] == "B" and r == s+1: - return branching_rule(Rtype, Stype, rule="symmetric") + return branching_rule(Rtype, Stype, rule='symmetric') if s == r-1: try: - return branching_rule(Rtype, Stype, rule="levi") + return branching_rule(Rtype, Stype, rule='levi') except Exception: pass raise ValueError("No default rule found (you must specify the rule)") @@ -1964,7 +1962,7 @@ def branching_rule_from_plethysm(chi, cartan_type, return_matrix=False): - ``chi`` -- the character of an irreducible representation `\pi` of a group `G` - - ``cartan_type`` -- a classical Cartan type (`A`,`B`,`C` or `D`). + - ``cartan_type`` -- a classical Cartan type (`A`,`B`,`C` or `D`) It is assumed that the image of the irreducible representation pi naturally has its image in the group `G`. @@ -1980,7 +1978,7 @@ def branching_rule_from_plethysm(chi, cartan_type, return_matrix=False): of `SL(3)`:: sage: A2 = WeylCharacterRing("A2") - sage: A2 = WeylCharacterRing("A2", style="coroots") + sage: A2 = WeylCharacterRing("A2", style='coroots') sage: ad = A2.adjoint_representation(); ad A2(1,1) sage: ad.degree() @@ -2043,7 +2041,7 @@ def branching_rule_from_plethysm(chi, cartan_type, return_matrix=False): return BranchingRule(ct, chi.parent().cartan_type(), lambda x: tuple(M*vector(x)), "plethysm (along %s)" % chi) -def maximal_subgroups(ct, mode="print_rules"): +def maximal_subgroups(ct, mode='print_rules'): """ Given a classical Cartan type (of rank less than or equal to 8) this prints the Cartan types of maximal subgroups, with a method @@ -2066,7 +2064,6 @@ def maximal_subgroups(ct, mode="print_rules"): A1xA1xA1xA1:branching_rule("D4","D2xD2","orthogonal_sum")*branching_rule("D2xD2","A1xA1xA1xA1",[branching_rule("D2","A1xA1","isomorphic"),branching_rule("D2","A1xA1","isomorphic")]) .. SEEALSO:: :meth:`~sage.combinat.root_system.weyl_characters.WeylCharacterRing.ParentMethods.maximal_subgroups` - """ if CartanType(ct) == CartanType("A2"): diff --git a/src/sage/combinat/root_system/cartan_matrix.py b/src/sage/combinat/root_system/cartan_matrix.py index 25728c98345..c3151013ed7 100644 --- a/src/sage/combinat/root_system/cartan_matrix.py +++ b/src/sage/combinat/root_system/cartan_matrix.py @@ -353,7 +353,7 @@ def matrix_space(self, nrows=None, ncols=None, sparse=None): - ``ncols`` -- number of columns - - ``sparse`` -- (boolean) sparseness + - ``sparse`` -- boolean EXAMPLES:: @@ -455,7 +455,7 @@ def root_space(self): """ return self.root_system().root_space() - def reflection_group(self, type="matrix"): + def reflection_group(self, type='matrix'): """ Return the reflection group corresponding to ``self``. @@ -717,7 +717,7 @@ def dual(self): def is_simply_laced(self): """ - Implements :meth:`CartanType_abstract.is_simply_laced()`. + Implement :meth:`CartanType_abstract.is_simply_laced()`. A Cartan matrix is simply-laced if all non diagonal entries are `0` or `-1`. @@ -737,7 +737,7 @@ def is_simply_laced(self): def is_crystallographic(self): """ - Implements :meth:`CartanType_abstract.is_crystallographic`. + Implement :meth:`CartanType_abstract.is_crystallographic`. A Cartan matrix is crystallographic if it is symmetrizable. @@ -750,7 +750,7 @@ def is_crystallographic(self): def column_with_indices(self, j): """ - Return the `j^{th}` column `(a_{i,j})_i` of ``self`` as a container + Return the `j`-th column `(a_{i,j})_i` of ``self`` as a container (or iterator) of tuples `(i, a_{i,j})` EXAMPLES:: @@ -763,7 +763,7 @@ def column_with_indices(self, j): def row_with_indices(self, i): """ - Return the `i^{th}` row `(a_{i,j})_j` of ``self`` as a container + Return the `i`-th row `(a_{i,j})_j` of ``self`` as a container (or iterator) of tuples `(j, a_{i,j})` EXAMPLES:: @@ -1017,7 +1017,6 @@ def principal_submatrices(self, proper=False): ] sage: M.principal_submatrices(proper=True) # needs sage.graphs [[], [2], [2]] - """ iset = list(range(self.ncols())) ret = [] diff --git a/src/sage/combinat/root_system/cartan_type.py b/src/sage/combinat/root_system/cartan_type.py index e4526d5f079..69e9acdb135 100644 --- a/src/sage/combinat/root_system/cartan_type.py +++ b/src/sage/combinat/root_system/cartan_type.py @@ -503,7 +503,7 @@ class CartanTypeFactory(SageObject): def __call__(self, *args): """ - Constructs a Cartan type object. + Construct a Cartan type object. INPUT: @@ -511,9 +511,9 @@ def __call__(self, *args): and rank is an integer or a pair of integers - ``[letter, rank, twist]`` -- letter is one of 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'BC' - and rank and twist are integers + and rank and twist are integers - - ``str`` -- a string + - ``str`` -- string - ``object`` -- a Cartan type, or an object with a Cartan type method @@ -750,11 +750,11 @@ def samples(self, finite=None, affine=None, crystallographic=None): INPUT: - - ``finite`` -- a boolean or ``None`` (default: ``None``) + - ``finite`` -- boolean or ``None`` (default: ``None``) - - ``affine`` -- a boolean or ``None`` (default: ``None``) + - ``affine`` -- boolean or ``None`` (default: ``None``) - - ``crystallographic`` -- a boolean or ``None`` (default: ``None``) + - ``crystallographic`` -- boolean or ``None`` (default: ``None``) The sample contains all the exceptional finite and affine Cartan types, as well as typical representatives of the @@ -854,7 +854,7 @@ def _samples(self): @classmethod def color(cls, i): """ - Default color scheme for the vertices of a Dynkin diagram (and associated objects) + Default color scheme for the vertices of a Dynkin diagram (and associated objects). EXAMPLES:: @@ -884,7 +884,7 @@ def color(cls, i): # add options to class class options(GlobalOptions): r""" - Sets and displays the options for Cartan types. If no parameters + Set and display the options for Cartan types. If no parameters are set, then the function returns a copy of the options dictionary. The ``options`` to partitions can be accessed as the method @@ -938,27 +938,27 @@ class options(GlobalOptions): NAME = 'CartanType' module = 'sage.combinat.root_system.cartan_type' option_class = 'CartanTypeFactory' - notation = dict(default="Stembridge", + notation = dict(default='Stembridge', description='Specifies which notation Cartan types should use when printed', values=dict(Stembridge="use Stembridge's notation", Kac="use Kac's notation"), case_sensitive=False, - alias=dict(BC="Stembridge", tilde="Stembridge", twisted="Kac")) - dual_str = dict(default="*", + alias=dict(BC='Stembridge', tilde='Stembridge', twisted='Kac')) + dual_str = dict(default='*', description='The string used for dual Cartan types when printing', checker=lambda char: isinstance(char, str)) - dual_latex = dict(default="\\vee", + dual_latex = dict(default='\\vee', description='The latex used for dual CartanTypes when latexing', checker=lambda char: isinstance(char, str)) - mark_special_node = dict(default="none", + mark_special_node = dict(default='none', description="Make the special nodes", values=dict(none="no markup", latex="only in latex", printing="only in printing", both="both in latex and printing"), case_sensitive=False) - special_node_str = dict(default="@", + special_node_str = dict(default='@', description="The string used to indicate which node is special when printing", checker=lambda char: isinstance(char, str)) - marked_node_str = dict(default="X", + marked_node_str = dict(default='X', description="The string used to indicate a marked node when printing", checker=lambda char: isinstance(char, str)) latex_relabel = dict(default=True, @@ -1048,7 +1048,7 @@ def _ascii_art_node(self, label): """ return "O" - def _latex_draw_node(self, x, y, label, position="below=4pt", fill='white'): + def _latex_draw_node(self, x, y, label, position='below=4pt', fill='white'): r""" Draw (possibly marked [crossed out]) circular node ``i`` at the position ``(x,y)`` with node label ``label`` . @@ -1066,7 +1066,7 @@ def _latex_draw_node(self, x, y, label, position="below=4pt", fill='white'): def _latex_draw_arrow_tip(self, x, y, rot=0): r""" - Draw an arrow tip at the point ``(x, y)`` rotated by ``rot`` + Draw an arrow tip at the point ``(x, y)`` rotated by ``rot``. INPUT: @@ -1261,7 +1261,7 @@ def marked_nodes(self, marked_nodes): INPUT: - - ``marked_nodes`` -- a list of nodes to mark + - ``marked_nodes`` -- list of nodes to mark EXAMPLES:: @@ -1663,7 +1663,7 @@ def coxeter_diagram(self): def is_crystallographic(self): """ - Implements :meth:`CartanType_abstract.is_crystallographic` + Implement :meth:`CartanType_abstract.is_crystallographic` by returning ``True``. EXAMPLES:: @@ -1889,7 +1889,7 @@ def _ascii_art_node(self, label): return self.options('special_node_str') return super()._ascii_art_node(label) - def _latex_draw_node(self, x, y, label, position="below=4pt"): + def _latex_draw_node(self, x, y, label, position='below=4pt'): r""" Draw (possibly marked [crossed out]) circular node ``i`` at the position ``(x,y)`` with node label ``label`` . @@ -1930,7 +1930,7 @@ def is_affine(self): def is_untwisted_affine(self): """ - Return whether ``self`` is untwisted affine + Return whether ``self`` is untwisted affine. A Cartan type is untwisted affine if it is the canonical affine extension of some finite type. Every affine type is @@ -2046,7 +2046,6 @@ def classical(self): ....: g2.delete_vertex(ct.special_node()) ....: assert g1.vertices(sort=True) == g2.vertices(sort=True) ....: assert g1.edges(sort=True) == g2.edges(sort=True) - """ @abstract_method @@ -2092,7 +2091,7 @@ def row_annihilator(self, m=None): combination of `\alpha_0, \alpha_1, \ldots, \alpha_n` with nonnegative coefficients (or alternatively, the unique minimal non trivial annihilating linear combination of the rows of the - Cartan matrix with non-negative coefficients). + Cartan matrix with nonnegative coefficients). Throw an error if the existence of uniqueness does not hold @@ -2140,7 +2139,7 @@ def col_annihilator(self): combination of `\alpha^\vee_0, \alpha^\vee, \ldots, \alpha^\vee` with nonnegative coefficients (or alternatively, the unique minimal non trivial annihilating linear combination of the columns of the - Cartan matrix with non-negative coefficients). + Cartan matrix with nonnegative coefficients). Throw an error if the existence or uniqueness does not hold @@ -2171,7 +2170,7 @@ def col_annihilator(self): def c(self): r""" - Returns the family (c_i)_i of integer coefficients defined by + Return the family (c_i)_i of integer coefficients defined by `c_i=max(1, a_i/a^vee_i)` (see e.g. [FSS07]_ p. 3) FIXME: the current implementation assumes that the Cartan @@ -2389,7 +2388,7 @@ def translation_factors(self): def _test_dual_classical(self, **options): r""" - Tests whether the special node of the dual is still the same and whether + Test whether the special node of the dual is still the same and whether the methods dual and classical commute. TESTS:: @@ -2535,7 +2534,6 @@ def __reduce__(self): (CartanType, ('D', 4)) sage: T == loads(dumps(T)) True - """ return (CartanType, (self.letter, self.n)) @@ -2553,7 +2551,7 @@ def __hash__(self): def index_set(self): r""" - Implements :meth:`CartanType_abstract.index_set`. + Implement :meth:`CartanType_abstract.index_set`. The index set for all standard finite Cartan types is of the form `\{1, \ldots, n\}`. (See :mod:`~sage.combinat.root_system.type_I` @@ -2648,7 +2646,7 @@ def type(self): @cached_method def opposition_automorphism(self): r""" - Return the opposition automorphism + Return the opposition automorphism. The *opposition automorphism* is the automorphism `i \mapsto i^*` of the vertices Dynkin diagram such that, @@ -2708,7 +2706,6 @@ def __init__(self, letter, n, affine=1): False sage: ct1 == ct3 False - """ assert (letter in ['A', 'B', 'C', 'BC', 'D', 'E', 'F', 'G']) self.letter = letter @@ -2748,7 +2745,6 @@ def __reduce__(self): (CartanType, ('D', 4, 1)) sage: T == loads(dumps(T)) True - """ return (CartanType, (self.letter, self.n, self.affine)) @@ -2816,7 +2812,7 @@ def rank(self): def index_set(self): r""" - Implements :meth:`CartanType_abstract.index_set`. + Implement :meth:`CartanType_abstract.index_set`. The index set for all standard affine Cartan types is of the form `\{0, \ldots, n\}`. @@ -2917,7 +2913,6 @@ def is_untwisted_affine(self): sage: CartanType(['B', 3, 1]).is_untwisted_affine() True - """ return True @@ -3069,39 +3064,3 @@ def __getitem__(self, i): raise IndexError("index out of range") options = CartanType.options - -############################################################################## -# For backward compatibility - - -class CartanType_simple_finite: - def __setstate__(self, dict): - """ - Implements the unpickling of Cartan types pickled by Sage <= 4.0. - - EXAMPLES: - - This is the pickle for CartanType(["A", 4]):: - - sage: pg_CartanType_simple_finite = unpickle_global('sage.combinat.root_system.cartan_type', 'CartanType_simple_finite') - sage: si1 = unpickle_newobj(pg_CartanType_simple_finite, ()) - sage: from sage.misc.fpickle import unpickleModule - sage: pg_make_integer = unpickle_global('sage.rings.integer', 'make_integer') - sage: si2 = pg_make_integer('4') - sage: unpickle_build(si1, {'tools':unpickleModule('sage.combinat.root_system.type_A'), 't':['A', si2], 'letter':'A', 'n':si2}) - - sage: si1 - ['A', 4] - sage: si1.dynkin_diagram() # needs sage.graphs - O---O---O---O - 1 2 3 4 - A4 - - This is quite hacky; in particular unique representation is not preserved:: - - sage: si1 == CartanType(["A", 4]) # todo: not implemented - True - """ - T = CartanType([dict['letter'], dict['n']]) - self.__class__ = T.__class__ - self.__dict__ = T.__dict__ diff --git a/src/sage/combinat/root_system/coxeter_group.py b/src/sage/combinat/root_system/coxeter_group.py index 854e1625b64..0f8fd84fdea 100644 --- a/src/sage/combinat/root_system/coxeter_group.py +++ b/src/sage/combinat/root_system/coxeter_group.py @@ -16,7 +16,7 @@ lazy_import('sage.combinat.root_system.weyl_group', 'WeylGroup') -def CoxeterGroup(data, implementation="reflection", base_ring=None, index_set=None): +def CoxeterGroup(data, implementation='reflection', base_ring=None, index_set=None): """ Return an implementation of the Coxeter group given by ``data``. @@ -69,46 +69,46 @@ def CoxeterGroup(data, implementation="reflection", base_ring=None, index_set=No We now use the ``implementation`` option:: - sage: W = CoxeterGroup(["A",2], implementation="permutation"); W # optional - gap3 + sage: W = CoxeterGroup(["A",2], implementation='permutation'); W # optional - gap3 Permutation Group with generators [(1,4)(2,3)(5,6), (1,3)(2,5)(4,6)] sage: W.category() # optional - gap3 Join of Category of finite enumerated permutation groups and Category of finite Weyl groups and Category of well generated finite irreducible complex reflection groups - sage: W = CoxeterGroup(["A",2], implementation="matrix"); W # needs sage.libs.gap + sage: W = CoxeterGroup(["A",2], implementation='matrix'); W # needs sage.libs.gap Weyl Group of type ['A', 2] (as a matrix group acting on the ambient space) - sage: W = CoxeterGroup(["H",3], implementation="matrix"); W # needs sage.libs.gap sage.rings.number_field + sage: W = CoxeterGroup(["H",3], implementation='matrix'); W # needs sage.libs.gap sage.rings.number_field Finite Coxeter group over Number Field in a with defining polynomial x^2 - 5 with a = 2.236067977499790? with Coxeter matrix: [1 3 2] [3 1 5] [2 5 1] - sage: W = CoxeterGroup(["H",3], implementation="reflection"); W # needs sage.libs.gap sage.rings.number_field + sage: W = CoxeterGroup(["H",3], implementation='reflection'); W # needs sage.libs.gap sage.rings.number_field Finite Coxeter group over Number Field in a with defining polynomial x^2 - 5 with a = 2.236067977499790? with Coxeter matrix: [1 3 2] [3 1 5] [2 5 1] - sage: W = CoxeterGroup(["A",4,1], implementation="permutation") # needs sage.libs.gap + sage: W = CoxeterGroup(["A",4,1], implementation='permutation') # needs sage.libs.gap Traceback (most recent call last): ... ValueError: the type must be finite - sage: W = CoxeterGroup(["A",4], implementation="chevie"); W # optional - gap3 + sage: W = CoxeterGroup(["A",4], implementation='chevie'); W # optional - gap3 Irreducible real reflection group of rank 4 and type A4 We use the different options for the "reflection" implementation:: - sage: W = CoxeterGroup(["H",3], implementation="reflection", base_ring=RR); W # needs sage.libs.gap + sage: W = CoxeterGroup(["H",3], implementation='reflection', base_ring=RR); W # needs sage.libs.gap Finite Coxeter group over Real Field with 53 bits of precision with Coxeter matrix: [1 3 2] [3 1 5] [2 5 1] - sage: W = CoxeterGroup([[1,10],[10,1]], implementation="reflection", # needs sage.symbolics + sage: W = CoxeterGroup([[1,10],[10,1]], implementation='reflection', # needs sage.symbolics ....: index_set=['a','b'], base_ring=SR); W Finite Coxeter group over Symbolic Ring with Coxeter matrix: [ 1 10] @@ -144,7 +144,7 @@ def CoxeterGroup(data, implementation="reflection", base_ring=None, index_set=No if not cartan_type.is_finite(): raise ValueError("the type must be finite") if cartan_type.is_crystallographic(): - return WeylGroup(cartan_type, implementation="permutation") + return WeylGroup(cartan_type, implementation='permutation') return ReflectionGroup(cartan_type, index_set=index_set) elif implementation == "matrix": if cartan_type.is_crystallographic(): diff --git a/src/sage/combinat/root_system/coxeter_type.py b/src/sage/combinat/root_system/coxeter_type.py index 88a53e4bd98..10312d7e59d 100644 --- a/src/sage/combinat/root_system/coxeter_type.py +++ b/src/sage/combinat/root_system/coxeter_type.py @@ -69,11 +69,11 @@ def samples(self, finite=None, affine=None, crystallographic=None): INPUT: - - ``finite`` -- a boolean or ``None`` (default: ``None``) + - ``finite`` -- boolean or ``None`` (default: ``None``) - - ``affine`` -- a boolean or ``None`` (default: ``None``) + - ``affine`` -- boolean or ``None`` (default: ``None``) - - ``crystallographic`` -- a boolean or ``None`` (default: ``None``) + - ``crystallographic`` -- boolean or ``None`` (default: ``None``) The sample contains all the exceptional finite and affine Coxeter types, as well as typical representatives of the diff --git a/src/sage/combinat/root_system/dynkin_diagram.py b/src/sage/combinat/root_system/dynkin_diagram.py index 0b815043999..76411c66158 100644 --- a/src/sage/combinat/root_system/dynkin_diagram.py +++ b/src/sage/combinat/root_system/dynkin_diagram.py @@ -160,7 +160,7 @@ def DynkinDiagram(*args, **kwds): TESTS: - Check that :issue:`15277` is fixed by not having edges from 0's:: + Check that :issue:`15277` is fixed by not having edges from 0s:: sage: CM = CartanMatrix([[2,-1,0,0],[-3,2,-2,-2],[0,-1,2,-1],[0,-1,-1,2]]) sage: CM @@ -299,7 +299,7 @@ def _repr_(self, compact=False): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. Override rich output because :meth:`_repr_` outputs ascii art. The proper fix will be in :issue:`18328`. @@ -323,7 +323,7 @@ def _rich_repr_(self, display_manager, **kwds): def _latex_(self, scale=0.5): r""" - Return a latex representation of this Dynkin diagram + Return a latex representation of this Dynkin diagram. EXAMPLES:: @@ -403,7 +403,7 @@ def __hash__(self): @staticmethod def an_instance(): """ - Returns an example of Dynkin diagram + Return an example of Dynkin diagram. EXAMPLES:: @@ -415,7 +415,6 @@ def an_instance(): [ 2 -1 -1] [-2 2 -1] [-1 -1 2] - """ # hyperbolic Dynkin diagram of Exercise 4.9 p. 57 of Kac Infinite Dimensional Lie Algebras. g = DynkinDiagram() @@ -451,7 +450,7 @@ def cartan_type(self): def rank(self): r""" - Returns the index set for this Dynkin diagram + Return the index set for this Dynkin diagram. EXAMPLES:: @@ -476,7 +475,7 @@ def dynkin_diagram(self): @cached_method def cartan_matrix(self): r""" - Returns the Cartan matrix for this Dynkin diagram + Return the Cartan matrix for this Dynkin diagram. EXAMPLES:: @@ -489,7 +488,7 @@ def cartan_matrix(self): def dual(self): r""" - Returns the dual Dynkin diagram, obtained by reversing all edges. + Return the dual Dynkin diagram, obtained by reversing all edges. EXAMPLES:: @@ -686,7 +685,7 @@ def is_irreducible(self): def is_crystallographic(self): """ - Implements :meth:`CartanType_abstract.is_crystallographic` + Implement :meth:`CartanType_abstract.is_crystallographic`. A Dynkin diagram always corresponds to a crystallographic root system. @@ -784,9 +783,9 @@ def __getitem__(self, i): def column(self, j): """ - Returns the `j^{th}` column `(a_{i,j})_i` of the + Return the `j`-th column `(a_{i,j})_i` of the Cartan matrix corresponding to this Dynkin diagram, as a container - (or iterator) of tuples `(i, a_{i,j})` + (or iterator) of tuples `(i, a_{i,j})`. EXAMPLES:: @@ -799,9 +798,9 @@ def column(self, j): def row(self, i): """ - Returns the `i^{th}` row `(a_{i,j})_j` of the + Return the `i`-th row `(a_{i,j})_j` of the Cartan matrix corresponding to this Dynkin diagram, as a container - (or iterator) of tuples `(j, a_{i,j})` + (or iterator) of tuples `(j, a_{i,j})`. EXAMPLES:: diff --git a/src/sage/combinat/root_system/extended_affine_weyl_group.py b/src/sage/combinat/root_system/extended_affine_weyl_group.py index 64a08c28808..b1d35c86f7a 100644 --- a/src/sage/combinat/root_system/extended_affine_weyl_group.py +++ b/src/sage/combinat/root_system/extended_affine_weyl_group.py @@ -54,11 +54,11 @@ def ExtendedAffineWeylGroup(cartan_type, general_linear=None, **print_options): INPUT: - - ``cartan_type`` -- An affine or finite Cartan type (a finite Cartan type is an + - ``cartan_type`` -- an affine or finite Cartan type (a finite Cartan type is an abbreviation for its untwisted affinization) - - ``general_linear`` -- (default: ``None``) If ``True`` and ``cartan_type`` indicates + - ``general_linear`` -- (default: ``None``) if ``True`` and ``cartan_type`` indicates untwisted type A, returns the universal central extension - - ``print_options`` -- Special instructions for printing elements (see below) + - ``print_options`` -- special instructions for printing elements (see below) .. RUBRIC:: Mnemonics @@ -76,12 +76,12 @@ def ExtendedAffineWeylGroup(cartan_type, general_linear=None, **print_options): Recognized arguments for ``print_options`` are: - - ``print_tuple`` -- ``True`` or ``False`` (default: ``False``) - If ``True``, elements are printed `(a,b)`, otherwise as `a * b` - - ``affine`` -- Prefix for simple reflections in the affine Weyl group - - ``classical`` -- Prefix for simple reflections in the classical Weyl group - - ``translation`` -- Prefix for the translation elements - - ``fundamental`` -- Prefix for the elements of the fundamental group + - ``print_tuple`` -- boolean (default: ``False``); if ``True``, elements + are printed `(a,b)`, otherwise as `a * b` + - ``affine`` -- prefix for simple reflections in the affine Weyl group + - ``classical`` -- prefix for simple reflections in the classical Weyl group + - ``translation`` -- prefix for the translation elements + - ``fundamental`` -- prefix for the elements of the fundamental group These options are not mutable. @@ -101,20 +101,20 @@ def ExtendedAffineWeylGroup(cartan_type, general_linear=None, **print_options): .. RUBRIC:: Notation - - `R` -- An irreducible affine root system - - `I` -- Set of nodes of the Dynkin diagram of `R` - - `R_0` -- The classical subsystem of `R` - - `I_0` -- Set of nodes of the Dynkin diagram of `R_0` - - `E` -- Extended affine Weyl group of type `R` - - `W` -- Affine Weyl group of type `R` + - `R` -- an irreducible affine root system + - `I` -- set of nodes of the Dynkin diagram of `R` + - `R_0` -- the classical subsystem of `R` + - `I_0` -- set of nodes of the Dynkin diagram of `R_0` + - `E` -- extended affine Weyl group of type `R` + - `W` -- affine Weyl group of type `R` - `W_0` -- finite (classical) Weyl group (of type `R_0`) - `M` -- translation lattice for `W` - `L` -- translation lattice for `E` - - `F` -- Fundamental subgroup of `E` (the length zero elements) - - `P` -- Finite weight lattice - - `Q` -- Finite root lattice - - `P^\vee` -- Finite coweight lattice - - `Q^\vee` -- Finite coroot lattice + - `F` -- fundamental subgroup of `E` (the length zero elements) + - `P` -- finite weight lattice + - `Q` -- finite root lattice + - `P^\vee` -- finite coweight lattice + - `Q^\vee` -- finite coroot lattice .. RUBRIC:: Translation lattices @@ -345,8 +345,8 @@ def ExtendedAffineWeylGroup(cartan_type, general_linear=None, **print_options): Here is a demonstration of the printing options:: - sage: E = ExtendedAffineWeylGroup(["A",2,1], affine="sx", classical="Sx", - ....: translation="x", fundamental="pix") + sage: E = ExtendedAffineWeylGroup(["A",2,1], affine='sx', classical='Sx', + ....: translation='x', fundamental='pix') sage: PW0 = E.PW0() sage: y = PW0(E.lattice_basis()[1]); y x[Lambdacheck[1]] @@ -991,7 +991,7 @@ def group_generators(self): @cached_method def PW0_to_WF_func(self, x): r""" - Implements coercion from style "PW0" to "WF". + Implement coercion from style "PW0" to "WF". EXAMPLES:: @@ -1187,7 +1187,7 @@ def simple_reflections(self): Finite family {0: (pi[0], S0), 1: (pi[0], S1), 2: (pi[0], S2), 3: (pi[0], S3)} sage: ExtendedAffineWeylGroup(['A',3,1], - ....: fundamental="f", + ....: fundamental='f', ....: print_tuple=True).FW().simple_reflections() Finite family {0: (f[0], S0), 1: (f[0], S1), 2: (f[0], S2), 3: (f[0], S3)} @@ -1203,7 +1203,7 @@ def simple_reflection(self, i): INPUT: - ``self`` -- a realization of the extended affine Weyl group - - ``i`` -- An affine Dynkin node + - ``i`` -- an affine Dynkin node EXAMPLES:: @@ -1308,7 +1308,7 @@ def from_affine_weyl(self, w): def from_reduced_word(self, word): r""" - Converts an affine or finite reduced word into a group element. + Convert an affine or finite reduced word into a group element. EXAMPLES:: @@ -1333,7 +1333,7 @@ def has_descent(self, i, side='right', positive=False): OPTIONAL: - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) If ``side='left'``, then the reflection acts on the left. If ``positive=True``, then the inequality is reversed. @@ -1365,7 +1365,7 @@ def first_descent(self, side='right', positive=False, index_set=None): INPUT: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) - ``index_set`` -- an optional subset of Dynkin nodes If ``index_set`` is not ``None``, then the descent must be in the ``index_set``. @@ -1417,12 +1417,12 @@ def apply_simple_projection(self, i, side='right', length_increasing=True): INPUT: - ``self`` -- an element of the extended affine Weyl group - - `i` -- a Dynkin node (index of a simple reflection `s_i`) + - ``i`` -- a Dynkin node (index of a simple reflection `s_i`) - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``) according to which side of ``self`` the reflection `s_i` should be multiplied - - ``length_increasing`` -- ``True`` or ``False`` (default ``True``). - If ``False``, do the above with the word "greater" replaced by "less". + - ``length_increasing`` -- boolean (default: ``True``); + if ``False``, do the above with the word "greater" replaced by "less" EXAMPLES:: @@ -1695,7 +1695,7 @@ def bruhat_le(self, x): INPUT: - ``self`` -- an element of the extended affine Weyl group - - `x` -- another element with the same parent as ``self`` + - ``x`` -- another element with the same parent as ``self`` EXAMPLES:: @@ -1756,14 +1756,14 @@ def action(self, la): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], affine="s") + sage: E = ExtendedAffineWeylGroup(['A',2,1], affine='s') sage: x = E.FW().an_element(); x pi[2] * s0*s1*s2 sage: la = E.lattice().an_element(); la 2*Lambdacheck[1] + 2*Lambdacheck[2] sage: x.action(la) 5*Lambdacheck[1] - 3*Lambdacheck[2] - sage: E = ExtendedAffineWeylGroup(['C',2,1], affine="s") + sage: E = ExtendedAffineWeylGroup(['C',2,1], affine='s') sage: x = E.PW0().from_translation(E.lattice_basis()[1]) sage: x.action(E.lattice_basis()[2]) Lambdacheck[1] + Lambdacheck[2] @@ -1788,14 +1788,14 @@ def dual_action(self, la): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], affine="s") + sage: E = ExtendedAffineWeylGroup(['A',2,1], affine='s') sage: x = E.FW().an_element(); x pi[2] * s0*s1*s2 sage: la = E.dual_lattice().an_element(); la 2*Lambda[1] + 2*Lambda[2] sage: x.dual_action(la) 5*Lambda[1] - 3*Lambda[2] - sage: E = ExtendedAffineWeylGroup(['C',2,1], affine="s") + sage: E = ExtendedAffineWeylGroup(['C',2,1], affine='s') sage: x = E.PvW0().from_dual_translation(E.dual_lattice_basis()[1]) sage: x.dual_action(E.dual_lattice_basis()[2]) Lambda[1] + Lambda[2] @@ -1835,7 +1835,7 @@ def face_data(self, i): INPUT: - - ``self`` -- An element of the extended affine Weyl group + - ``self`` -- an element of the extended affine Weyl group - ``i`` -- an affine Dynkin node OUTPUT: @@ -1929,7 +1929,7 @@ def has_descent(self, i, side='right', positive=False): OPTIONAL: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -2013,7 +2013,7 @@ class ExtendedAffineWeylGroupPW0(GroupSemidirectProduct, BindableClass): INPUT: - - ``E`` -- A parent with realization in :class:`ExtendedAffineWeylGroup_Class` + - ``E`` -- a parent with realization in :class:`ExtendedAffineWeylGroup_Class` EXAMPLES:: @@ -2058,7 +2058,7 @@ def from_translation(self, la): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], translation="tau", + sage: E = ExtendedAffineWeylGroup(['A',2,1], translation='tau', ....: print_tuple=True) sage: la = E.lattice().an_element(); la 2*Lambdacheck[1] + 2*Lambdacheck[2] @@ -2134,12 +2134,12 @@ def has_descent(self, i, side='right', positive=False): INPUT: - - ``i`` -- an index. + - ``i`` -- an index OPTIONAL: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -2203,7 +2203,7 @@ class ExtendedAffineWeylGroupW0P(GroupSemidirectProduct, BindableClass): INPUT: - - ``E`` -- A parent with realization in :class:`ExtendedAffineWeylGroup_Class` + - ``E`` -- a parent with realization in :class:`ExtendedAffineWeylGroup_Class` EXAMPLES:: @@ -2318,7 +2318,7 @@ def has_descent(self, i, side='right', positive=False): OPTIONAL: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -2368,7 +2368,7 @@ def bruhat_le(self, x): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], affine="s", + sage: E = ExtendedAffineWeylGroup(['A',2,1], affine='s', ....: print_tuple=True); WF = E.WF() sage: r = E.affine_weyl().from_reduced_word sage: v = r([1,0]) @@ -2401,7 +2401,7 @@ class ExtendedAffineWeylGroupWF(GroupSemidirectProduct, BindableClass): INPUT: - - ``E`` -- A parent with realization in :class:`ExtendedAffineWeylGroup_Class` + - ``E`` -- a parent with realization in :class:`ExtendedAffineWeylGroup_Class` EXAMPLES:: @@ -2454,7 +2454,7 @@ def simple_reflections(self): EXAMPLES:: - sage: ExtendedAffineWeylGroup(["A",3,1], affine="r").WF().simple_reflections() + sage: ExtendedAffineWeylGroup(["A",3,1], affine='r').WF().simple_reflections() Finite family {0: r0, 1: r1, 2: r2, 3: r3} """ E = self.realization_of() @@ -2487,12 +2487,12 @@ def has_descent(self, i, side='right', positive=False): INPUT: - - `i` -- an affine Dynkin index. + - ``i`` -- an affine Dynkin index OPTIONAL: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -2542,7 +2542,7 @@ def action_on_affine_roots(self, beta): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], affine="s") + sage: E = ExtendedAffineWeylGroup(['A',2,1], affine='s') sage: x = E.FW().an_element(); x pi[2] * s0*s1*s2 sage: v = RootSystem(['A',2,1]).root_lattice().an_element(); v @@ -2561,7 +2561,7 @@ class ExtendedAffineWeylGroupFW(GroupSemidirectProduct, BindableClass): INPUT: - - ``E`` -- A parent with realization in :class:`ExtendedAffineWeylGroup_Class` + - ``E`` -- a parent with realization in :class:`ExtendedAffineWeylGroup_Class` EXAMPLES:: @@ -2652,7 +2652,7 @@ def has_descent(self, i, side='right', positive=False): OPTIONAL: - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) - - ``positive`` -- ``True`` or ``False`` (default: ``False``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -2733,7 +2733,7 @@ class ExtendedAffineWeylGroupPvW0(GroupSemidirectProduct, BindableClass): INPUT: - - ``E`` -- A parent with realization in :class:`ExtendedAffineWeylGroup_Class` + - ``E`` -- a parent with realization in :class:`ExtendedAffineWeylGroup_Class` EXAMPLES:: @@ -2776,7 +2776,7 @@ def from_dual_translation(self, la): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], translation="tau", + sage: E = ExtendedAffineWeylGroup(['A',2,1], translation='tau', ....: print_tuple=True) sage: la = E.dual_lattice().an_element(); la 2*Lambda[1] + 2*Lambda[2] @@ -2842,12 +2842,12 @@ def has_descent(self, i, side='right', positive=False): INPUT: - - `i` -- an affine Dynkin index + - ``i`` -- an affine Dynkin index OPTIONAL: - - ``side`` -- 'left' or 'right' (default: 'right') - - ``positive`` -- True or False (default: ``False``) + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -2905,7 +2905,7 @@ class ExtendedAffineWeylGroupW0Pv(GroupSemidirectProduct, BindableClass): INPUT: - - `E` -- A parent with realization in :class:`ExtendedAffineWeylGroup_Class` + - ``E`` -- a parent with realization in :class:`ExtendedAffineWeylGroup_Class` EXAMPLES:: @@ -2947,7 +2947,7 @@ def from_dual_translation(self, la): EXAMPLES:: - sage: E = ExtendedAffineWeylGroup(['A',2,1], translation="tau", + sage: E = ExtendedAffineWeylGroup(['A',2,1], translation='tau', ....: print_tuple=True) sage: la = E.dual_lattice().an_element(); la 2*Lambda[1] + 2*Lambda[2] diff --git a/src/sage/combinat/root_system/fundamental_group.py b/src/sage/combinat/root_system/fundamental_group.py index 6dc13e302ec..d59f6af5415 100644 --- a/src/sage/combinat/root_system/fundamental_group.py +++ b/src/sage/combinat/root_system/fundamental_group.py @@ -39,9 +39,9 @@ def FundamentalGroupOfExtendedAffineWeylGroup(cartan_type, prefix='pi', - ``cartan_type`` -- a Cartan type that is either affine or finite, with the latter being a shorthand for the untwisted affinization - - ``prefix`` (default: 'pi') -- string that labels the elements of the group - - ``general_linear`` -- (default: None, meaning False) In untwisted type A, if True, use the - universal central extension + - ``prefix`` -- (default: ``'pi'``) string that labels the elements of the group + - ``general_linear`` -- (default: ``None``, meaning ``False``) In untwisted + type `A`, if ``True``, use the universal central extension .. RUBRIC:: Fundamental group @@ -185,7 +185,7 @@ def FundamentalGroupOfExtendedAffineWeylGroup(cartan_type, prefix='pi', (2, 2, 3) sage: x.act_on_classical_ambient(wt) (2, 3, 2) - sage: w = WeylGroup(F.cartan_type(),prefix="s").an_element(); w + sage: w = WeylGroup(F.cartan_type(),prefix='s').an_element(); w s0*s1*s2 sage: x.act_on_affine_weyl(w) s2*s0*s1 @@ -207,12 +207,12 @@ def FundamentalGroupOfExtendedAffineWeylGroup(cartan_type, prefix='pi', class FundamentalGroupElement(MultiplicativeGroupElement): def __init__(self, parent, x): r""" - This should not be called directly + This should not be called directly. EXAMPLES:: sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup - sage: x = FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1], prefix="f").an_element() + sage: x = FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1], prefix='f').an_element() sage: TestSuite(x).run() """ if x not in parent.special_nodes(): @@ -227,7 +227,7 @@ def value(self): EXAMPLES:: sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup - sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1], prefix="f") + sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1], prefix='f') sage: F.special_nodes() (0, 1, 2, 3, 4) sage: x = F(4); x @@ -244,7 +244,7 @@ def _repr_(self): EXAMPLES:: sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup - sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1], prefix="f") + sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1], prefix='f') sage: F(2)^3 # indirect doctest f[1] """ @@ -260,7 +260,7 @@ def __invert__(self): sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',3,1]) sage: F(1).inverse() # indirect doctest pi[3] - sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1], prefix="f") + sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1], prefix='f') sage: F(1).inverse() f[6] """ @@ -295,7 +295,7 @@ def act_on_affine_weyl(self, w): sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',3,1]) - sage: W = WeylGroup(F.cartan_type(),prefix="s") + sage: W = WeylGroup(F.cartan_type(),prefix='s') sage: w = W.from_reduced_word([2,3,0]) sage: F(1).act_on_affine_weyl(w).reduced_word() [3, 0, 1] @@ -397,7 +397,7 @@ def leading_support(beta): Q = RootSystem(cartan_type_classical).root_lattice() alpha = Q.simple_roots() omega = RootSystem(cartan_type_classical).weight_lattice().fundamental_weights() - W = Q.weyl_group(prefix="s") + W = Q.weyl_group(prefix='s') for i in self._special_nodes: if i == special_node: continue @@ -498,7 +498,6 @@ def special_nodes(self): (0, 3) sage: FundamentalGroupOfExtendedAffineWeylGroup(['A',2,1], general_linear=True).special_nodes() Integer Ring - """ return self._special_nodes @@ -514,7 +513,7 @@ def group_generators(self): EXAMPLES:: sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup - sage: FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1],prefix="f").group_generators() + sage: FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1],prefix='f').group_generators() Finite family {0: f[0], 1: f[1], 6: f[6]} """ return Family(self.special_nodes(), self) @@ -526,7 +525,7 @@ def __iter__(self): EXAMPLES:: sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup - sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1],prefix="f") + sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1],prefix='f') sage: [x for x in F] # indirect doctest [f[0], f[1], f[6]] """ @@ -540,7 +539,7 @@ def an_element(self): EXAMPLES:: sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup - sage: FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1],prefix="f").an_element() + sage: FundamentalGroupOfExtendedAffineWeylGroup(['A',4,1],prefix='f').an_element() f[4] """ return self.last() @@ -555,7 +554,6 @@ def index_set(self): sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup sage: FundamentalGroupOfExtendedAffineWeylGroup(['A',2,1]).index_set() (0, 1, 2) - """ return self.cartan_type().index_set() diff --git a/src/sage/combinat/root_system/hecke_algebra_representation.py b/src/sage/combinat/root_system/hecke_algebra_representation.py index e9136f2f790..fd40907d33e 100644 --- a/src/sage/combinat/root_system/hecke_algebra_representation.py +++ b/src/sage/combinat/root_system/hecke_algebra_representation.py @@ -23,7 +23,7 @@ class HeckeAlgebraRepresentation(WithEqualityById, SageObject): r""" - A representation of an (affine) Hecke algebra given by the action of the `T` generators + A representation of an (affine) Hecke algebra given by the action of the `T` generators. Let `F_i` be a family of operators implementing an action of the operators `(T_i)_{i\in I}` of the Hecke algebra on some vector @@ -42,9 +42,9 @@ class HeckeAlgebraRepresentation(WithEqualityById, SageObject): - ``domain`` -- a vector space - ``f`` -- a function ``f(l,i)`` taking a basis element `l` of ``domain`` and an index `i`, and returning `F_i` - - ``cartan_type`` -- The Cartan type of the Hecke algebra - - ``q1``, ``q2`` -- The eigenvalues of the generators `T` of the Hecke algebra - - ``side`` -- "left" or "right" (default: "right") + - ``cartan_type`` -- the Cartan type of the Hecke algebra + - ``q1``, ``q2`` -- the eigenvalues of the generators `T` of the Hecke algebra + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) whether this is a left or right representation EXAMPLES:: @@ -75,7 +75,7 @@ class HeckeAlgebraRepresentation(WithEqualityById, SageObject): sage: from sage.combinat.root_system.hecke_algebra_representation import HeckeAlgebraRepresentation sage: W = SymmetricGroup(3) sage: domain = W.algebra(QQ) - sage: action = lambda x,i: domain.monomial(x.apply_simple_reflection(i, side="right")) + sage: action = lambda x,i: domain.monomial(x.apply_simple_reflection(i, side='right')) sage: r = HeckeAlgebraRepresentation(domain, action, CartanType(["A",2]), 1, -1) sage: hash(r) # random 3 @@ -85,14 +85,14 @@ class HeckeAlgebraRepresentation(WithEqualityById, SageObject): - [HST2008]_ """ - def __init__(self, domain, on_basis, cartan_type, q1, q2, q=ZZ.one(), side="right"): + def __init__(self, domain, on_basis, cartan_type, q1, q2, q=ZZ.one(), side='right'): r""" TESTS:: sage: from sage.combinat.root_system.hecke_algebra_representation import HeckeAlgebraRepresentation sage: W = SymmetricGroup(3) sage: domain = W.algebra(QQ) - sage: action = lambda x,i: domain.monomial(x.apply_simple_reflection(i, side="right")) + sage: action = lambda x,i: domain.monomial(x.apply_simple_reflection(i, side='right')) sage: HeckeAlgebraRepresentation(domain, action, CartanType(["A",2]), 1, -1) A representation of the (1, -1)-Hecke algebra of type ['A', 2] on Symmetric group algebra of order 3 over Rational Field """ @@ -149,7 +149,7 @@ def cartan_type(self): sage: from sage.combinat.root_system.hecke_algebra_representation import HeckeAlgebraRepresentation sage: KW = SymmetricGroup(3).algebra(QQ) - sage: action = lambda x,i: KW.monomial(x.apply_simple_reflection(i, side="right")) + sage: action = lambda x,i: KW.monomial(x.apply_simple_reflection(i, side='right')) sage: H = HeckeAlgebraRepresentation(KW, action, CartanType(["A",2]), 1, -1) sage: H.cartan_type() ['A', 2] @@ -198,7 +198,7 @@ def Ti_on_basis(self, x, i): def Ti_inverse_on_basis(self, x, i): r""" - The `T_i^{-1}` operators, on basis elements + The `T_i^{-1}` operators, on basis elements. INPUT: @@ -224,22 +224,23 @@ def Ti_inverse_on_basis(self, x, i): @cached_method def on_basis(self, x, word, signs=None, scalar=None): r""" - Action of product of `T_i` and `T_i^{-1}` on ``x``. + Action of product of `T_i` and `T_i^{-1}` on `x`. INPUT: - ``x`` -- the index of a basis element - ``word`` -- word of indices of generators - - ``signs`` -- (default: None) sequence of signs of same length as ``word``; determines - which operators are supposed to be taken as inverses. - - ``scalar`` -- (default: None) scalar to multiply the answer by + - ``signs`` -- (default: ``None``) sequence of signs of same length as + ``word``; determines which operators are supposed to be taken as + inverses. + - ``scalar`` -- (default: ``None``) scalar to multiply the answer by EXAMPLES:: sage: from sage.combinat.root_system.hecke_algebra_representation import HeckeAlgebraRepresentation sage: W = SymmetricGroup(3) sage: domain = W.algebra(QQ) - sage: action = lambda x,i: domain.monomial(x.apply_simple_reflection(i, side="right")) + sage: action = lambda x,i: domain.monomial(x.apply_simple_reflection(i, side='right')) sage: rho = HeckeAlgebraRepresentation(domain, action, CartanType(["A",2]), 1, -1) sage: rho.on_basis(W.one(), (1,2,1)) @@ -322,19 +323,17 @@ def Tw(self, word, signs=None, scalar=None): INPUT: - - ``word`` -- a word `i_1,\dots,i_k` for some element `w` of the Weyl group. - See :meth:`straighten_word` for how this word can be specified. + - ``word`` -- a word `i_1,\dots,i_k` for some element `w` of the Weyl group + See :meth:`straighten_word` for how this word can be specified - - ``signs`` -- a list `\epsilon_1,\dots,\epsilon_k` of the + - ``signs`` -- list `\epsilon_1,\dots,\epsilon_k` of the same length as ``word`` with `\epsilon_i =\pm 1` or ``None`` for `1,\dots,1` (default: ``None``) - ``scalar`` -- an element `c` of the base ring or ``None`` for `1` (default: ``None``) - OUTPUT: - - a module morphism implementing + OUTPUT: a module morphism implementing .. MATH:: @@ -443,7 +442,7 @@ def Tw_inverse(self, word): def _test_relations(self, **options): r""" - Test that this family of operators satisfies the Iwahori Hecke relations + Test that this family of operators satisfies the Iwahori Hecke relations. EXAMPLES:: @@ -682,7 +681,7 @@ def Y(self, base_ring=ZZ): def _test_Y(self, **options): r""" - Test the `T_w^{-1}` operators + Test the `T_w^{-1}` operators. EXAMPLES:: @@ -822,13 +821,13 @@ def __init__(self, T, T_Y=None, normalized=True): INPUT: - ``T`` -- a family `(T_i)_{i\in I}` implementing the action of - the generators of an affine Hecke algebra on ``self``. + the generators of an affine Hecke algebra on ``self`` - ``T_Y`` -- a family `(T^Y_i)_{i\in I}` implementing the action of the generators of an affine Hecke algebra on ``self``. By default, this is ``T``. - - ``normalized`` -- boolean (default: ``True``) whether the + - ``normalized`` -- boolean (default: ``True``); whether the eigenvector `E_\mu` is normalized so that `\mu` has coefficient `1`. diff --git a/src/sage/combinat/root_system/integrable_representations.py b/src/sage/combinat/root_system/integrable_representations.py index a1cb764e19a..b7d4b163242 100644 --- a/src/sage/combinat/root_system/integrable_representations.py +++ b/src/sage/combinat/root_system/integrable_representations.py @@ -228,7 +228,7 @@ def __init__(self, Lam): def highest_weight(self): """ - Returns the highest weight of ``self``. + Return the highest weight of ``self``. EXAMPLES:: @@ -466,7 +466,7 @@ def to_weight(self, n): INPUT: - - ``n`` -- a tuple representing a weight + - ``n`` -- tuple representing a weight EXAMPLES:: @@ -821,7 +821,7 @@ def m(self, n): INPUT: - - ``n`` -- a tuple representing a weight `\mu`. + - ``n`` -- tuple representing a weight `\mu` EXAMPLES:: @@ -864,7 +864,7 @@ def mult(self, mu): sage: L = RootSystem("B3~").weight_lattice(extended=True) sage: Lambda = L.fundamental_weights() sage: delta = L.null_root() - sage: W = L.weyl_group(prefix="s") + sage: W = L.weyl_group(prefix='s') sage: [s0,s1,s2,s3] = W.simple_reflections() sage: V = IntegrableRepresentation(Lambda[0]) sage: V.mult(Lambda[2] - 2*delta) @@ -1031,8 +1031,8 @@ def modular_characteristic(self, mu=None): OPTIONAL: - - ``mu`` -- a weight; or alternatively: - - ``n`` -- a tuple representing a weight `\mu`. + - ``mu`` -- a weight, or alternatively, + - ``n`` -- tuple representing a weight `\mu` If no optional parameter is specified, this returns `m_\Lambda`. If ``mu`` is specified, it returns `m_{\Lambda,\mu}`. You may @@ -1082,7 +1082,7 @@ def branch(self, i=None, weyl_character_ring=None, sequence=None, depth=5): - ``i`` -- (default: 0) an element of the index set - ``weyl_character_ring`` -- a WeylCharacterRing - - ``sequence`` -- a dictionary + - ``sequence`` -- dictionary - ``depth`` -- (default: 5) an upper bound for `k` determining how many terms to give @@ -1126,7 +1126,7 @@ def branch(self, i=None, weyl_character_ring=None, sequence=None, depth=5): Thus we have a branching to `\mathfrak{sl}(2) \times \mathfrak{sl}(2) \times \mathfrak{sl}(2)`:: - sage: A1xA1xA1 = WeylCharacterRing("A1xA1xA1",style="coroots") # needs sage.libs.gap + sage: A1xA1xA1 = WeylCharacterRing("A1xA1xA1",style='coroots') # needs sage.libs.gap sage: V.branch(i=2,weyl_character_ring=A1xA1xA1) # needs sage.libs.gap [A1xA1xA1(1,0,0), A1xA1xA1(0,1,2), @@ -1147,7 +1147,7 @@ def branch(self, i=None, weyl_character_ring=None, sequence=None, depth=5): O---O---O=>=O---O 0 1 2 3 4 F4~ - sage: A1xC3=WeylCharacterRing("A1xC3",style="coroots") + sage: A1xC3=WeylCharacterRing("A1xC3",style='coroots') sage: A1xC3.dynkin_diagram() O 1 @@ -1176,13 +1176,12 @@ def branch(self, i=None, weyl_character_ring=None, sequence=None, depth=5): [1, 3, 4, 7, 13, 19, 29, 43, 62, 90, 126, 174, 239, 325, 435, 580] sage: oeis(r) # optional -- internet 0: A029552: Expansion of phi(x) / f(-x) in powers of x where phi(), f() are Ramanujan theta functions. - """ if i is None: i = self._cartan_type.special_node() if i == self._cartan_type.special_node() or self._cartan_type.type() == 'A': if weyl_character_ring is None: - weyl_character_ring = WeylCharacterRing(self._cartan_type.classical(), style="coroots") + weyl_character_ring = WeylCharacterRing(self._cartan_type.classical(), style='coroots') if weyl_character_ring.cartan_type() != self._cartan_type.classical(): raise ValueError("Cartan type of WeylCharacterRing must be %s" % self.cartan_type().classical()) elif weyl_character_ring is None: diff --git a/src/sage/combinat/root_system/non_symmetric_macdonald_polynomials.py b/src/sage/combinat/root_system/non_symmetric_macdonald_polynomials.py index 69ed9c8f8af..90482002c92 100644 --- a/src/sage/combinat/root_system/non_symmetric_macdonald_polynomials.py +++ b/src/sage/combinat/root_system/non_symmetric_macdonald_polynomials.py @@ -32,15 +32,16 @@ class NonSymmetricMacdonaldPolynomials(CherednikOperatorsEigenvectors): r""" - Nonsymmetric Macdonald polynomials + Nonsymmetric Macdonald polynomials. INPUT: - ``KL`` -- an affine Cartan type or the group algebra of a realization of the affine weight lattice - - ``q``, ``q1``, ``q2`` -- parameters in the base ring of the group algebra (default: ``q``, ``q1``, ``q2``) - - ``normalized`` -- a boolean (default: ``True``) - whether to normalize the result to have leading coefficient 1 + - ``q``, ``q1``, ``q2`` -- parameters in the base ring of the group algebra + (default: ``q``, ``q1``, ``q2``) + - ``normalized`` -- boolean (default: ``True``); whether to normalize the + result to have leading coefficient 1 This implementation covers all reduced affine root systems. The polynomials are constructed recursively by the application @@ -943,7 +944,7 @@ class NonSymmetricMacdonaldPolynomials(CherednikOperatorsEigenvectors): Checking T0check:: - sage: T0check_on_basis = KL.T0_check_on_basis(q1,q2, convention="dominant") + sage: T0check_on_basis = KL.T0_check_on_basis(q1,q2, convention='dominant') sage: T0check_on_basis.phi # note: this is in fact a0 phi (2, 0) sage: T0check_on_basis.v # what to match it with? @@ -1284,7 +1285,6 @@ class NonSymmetricMacdonaldPolynomials(CherednikOperatorsEigenvectors): sage: for x in [0*epsilon[0], -epsilon[0], -epsilon[1], epsilon[0], epsilon[1]]: ....: x = KL.monomial(x) ....: assert q^2 * Y0(Y1(Y1(Y2(Y2(start))))) == start - """ @staticmethod @@ -1314,14 +1314,14 @@ def __classcall__(cls, KL, q='q', q1='q1', q2='q2', normalized=True): def __init__(self, KL, q, q1, q2, normalized): r""" - Initializes the nonsymmetric Macdonald polynomial class. + Initialize the nonsymmetric Macdonald polynomial class. INPUT: - ``KL`` -- algebra over weight space - ``q``, ``q1``, ``q2`` -- parameters - - ``normalized`` -- a boolean (default: ``True``) - whether to normalize the result to have leading coefficient 1 + - ``normalized`` -- boolean (default: ``True``); whether to normalize + the result to have leading coefficient 1 EXAMPLES:: @@ -1349,8 +1349,8 @@ def __init__(self, KL, q, q1, q2, normalized): self._q1 = q1 self._q2 = q2 assert self.L_prime().classical() is self.L().classical() - T = KL.twisted_demazure_lusztig_operators(q1, q2, convention="dominant") - T_Y = KL.demazure_lusztig_operators_on_classical(q, q1, q2, convention="dominant") + T = KL.twisted_demazure_lusztig_operators(q1, q2, convention='dominant') + T_Y = KL.demazure_lusztig_operators_on_classical(q, q1, q2, convention='dominant') CherednikOperatorsEigenvectors.__init__(self, T, T_Y, normalized=normalized) def _repr_(self): @@ -1499,7 +1499,6 @@ def KL0(self): sage: NonSymmetricMacdonaldPolynomials("B2~*").KL0() Algebra of the Ambient space of the Root system of type ['C', 2] over Fraction Field of Multivariate Polynomial Ring in q, q1, q2 over Rational Field - """ return self._KL.classical() @@ -1526,7 +1525,6 @@ def Q_to_Qcheck(self): alphacheck[1] + 2*alphacheck[2] sage: _.parent() Coroot lattice of the Root system of type ['C', 2, 1] - """ #assert self.cartan_type().is_untwisted_affine() Qcheck = self._T_Y.Y().keys() @@ -1726,7 +1724,7 @@ def eigenvalue_experimental(self, mu, l): INPUT: - ``mu`` -- the index `\mu` of an eigenvector - - `l` -- an index `\lambda^\vee` of some `Y` + - ``l`` -- an index `\lambda^\vee` of some `Y` .. NOTE:: @@ -1918,7 +1916,6 @@ def symmetric_macdonald_polynomial(self, mu): sage: om = E.L0().fundamental_weights() sage: E.symmetric_macdonald_polynomial(2*om[1]) ((3*q^6*v^22+3*q^5*v^22-3*q^6*v^20+q^4*v^22-4*q^5*v^20+q^4*v^18-q^5*v^16+q^3*v^18-2*q^4*v^16+q^5*v^14-q^3*v^16+q^4*v^14-4*q^4*v^12+q^2*v^14+q^5*v^10-8*q^3*v^12+4*q^4*v^10-4*q^2*v^12+8*q^3*v^10-q*v^12-q^4*v^8+4*q^2*v^10-q^2*v^8+q^3*v^6-q*v^8+2*q^2*v^6-q^3*v^4+q*v^6-q^2*v^4+4*q*v^2-q^2+3*v^2-3*q-3)/(q^6*v^22-q^5*v^20-q^4*v^12-q^3*v^12+q^3*v^10+q^2*v^10+q*v^2-1))*B[(0, 0, 0)] + ((q*v^2+v^2-q-1)/(q*v^2-1))*B[(-2, 1, 1)] + B[(-2, 2, 0)] + B[(-2, 0, 2)] + ((-q*v^2-v^2+q+1)/(-q*v^2+1))*B[(-1, -1, 2)] + ((2*q^4*v^12+2*q^3*v^12-2*q^4*v^10-2*q^3*v^10+q^2*v^8-q^3*v^6+q*v^8-2*q^2*v^6+q^3*v^4-q*v^6+q^2*v^4-2*q*v^2-2*v^2+2*q+2)/(q^4*v^12-q^3*v^10-q*v^2+1))*B[(-1, 1, 0)] + ((-q*v^2-v^2+q+1)/(-q*v^2+1))*B[(-1, 2, -1)] + ((2*q^4*v^12+2*q^3*v^12-2*q^4*v^10-2*q^3*v^10+q^2*v^8-q^3*v^6+q*v^8-2*q^2*v^6+q^3*v^4-q*v^6+q^2*v^4-2*q*v^2-2*v^2+2*q+2)/(q^4*v^12-q^3*v^10-q*v^2+1))*B[(-1, 0, 1)] + ((-q*v^2-v^2+q+1)/(-q*v^2+1))*B[(1, -2, 1)] + ((-2*q^4*v^12-2*q^3*v^12+2*q^4*v^10+2*q^3*v^10-q^2*v^8+q^3*v^6-q*v^8+2*q^2*v^6-q^3*v^4+q*v^6-q^2*v^4+2*q*v^2+2*v^2-2*q-2)/(-q^4*v^12+q^3*v^10+q*v^2-1))*B[(1, -1, 0)] + ((-q*v^2-v^2+q+1)/(-q*v^2+1))*B[(1, 1, -2)] + ((-2*q^4*v^12-2*q^3*v^12+2*q^4*v^10+2*q^3*v^10-q^2*v^8+q^3*v^6-q*v^8+2*q^2*v^6-q^3*v^4+q*v^6-q^2*v^4+2*q*v^2+2*v^2-2*q-2)/(-q^4*v^12+q^3*v^10+q*v^2-1))*B[(1, 0, -1)] + B[(2, -2, 0)] + ((q*v^2+v^2-q-1)/(q*v^2-1))*B[(2, -1, -1)] + B[(2, 0, -2)] + B[(0, -2, 2)] + ((-2*q^4*v^12-2*q^3*v^12+2*q^4*v^10+2*q^3*v^10-q^2*v^8+q^3*v^6-q*v^8+2*q^2*v^6-q^3*v^4+q*v^6-q^2*v^4+2*q*v^2+2*v^2-2*q-2)/(-q^4*v^12+q^3*v^10+q*v^2-1))*B[(0, -1, 1)] + ((2*q^4*v^12+2*q^3*v^12-2*q^4*v^10-2*q^3*v^10+q^2*v^8-q^3*v^6+q*v^8-2*q^2*v^6+q^3*v^4-q*v^6+q^2*v^4-2*q*v^2-2*v^2+2*q+2)/(q^4*v^12-q^3*v^10-q*v^2+1))*B[(0, 1, -1)] + B[(0, 2, -2)] - """ if self.cartan_type().classical() != mu.parent().cartan_type() or not mu.is_dominant(): raise ValueError("%s must be a dominant weight for the classical subrootsystem of %s" % (mu, self.cartan_type())) diff --git a/src/sage/combinat/root_system/pieri_factors.py b/src/sage/combinat/root_system/pieri_factors.py index 28b26d8bf6f..36dc4a332f2 100644 --- a/src/sage/combinat/root_system/pieri_factors.py +++ b/src/sage/combinat/root_system/pieri_factors.py @@ -551,9 +551,9 @@ def __init__(self, W, min_length, max_length, min_support, max_support): r""" INPUT: - - ``W`` -- a Weyl group of affine type `A` - - ``min_length``, ``max_length`` -- non negative integers - - ``min_support``, ``max_support`` -- subsets of the index set of `W` + - ``W`` -- a Weyl group of affine type `A` + - ``min_length``, ``max_length`` -- nonnegative integers + - ``min_support``, ``max_support`` -- subsets of the index set of `W` EXAMPLES:: @@ -604,7 +604,7 @@ def subset(self, length): INPUT: - - ``length`` -- a non-negative integer + - ``length`` -- nonnegative integer EXAMPLES:: @@ -652,7 +652,6 @@ def _test_maximal_elements(self, **options): sage: W.pieri_factors()._test_maximal_elements(verbose = True) sage: W.pieri_factors(min_length = 1)._test_maximal_elements(verbose = True) Strict subset of the Pieri factors; skipping test - """ tester = self._tester(**options) index_set = self.W.index_set() @@ -731,7 +730,6 @@ def __getitem__(self, support): [1, 0, 5, 4, 3] sage: W.pieri_factors()[[0,1,2,3,4]].reduced_word() [4, 3, 2, 1, 0] - """ index_set = sorted(self.W.index_set()) support = sorted(support) @@ -892,7 +890,7 @@ def stanley_symm_poly_weight(self, w): # The algorithm="delete" is a workaround when the set of # vertices is empty, in which case subgraph tries another # method which turns out to currently fail with Dynkin diagrams - return DiGraph(DynkinDiagram(w.parent().cartan_type())).subgraph(set(w.reduced_word()), algorithm="delete").connected_components_number() + return DiGraph(DynkinDiagram(w.parent().cartan_type())).subgraph(set(w.reduced_word()), algorithm='delete').connected_components_number() class PieriFactors_type_B_affine(PieriFactors_affine_type): @@ -1001,7 +999,7 @@ def stanley_symm_poly_weight(self, w): support_complement = set(ct.index_set()).difference(support).difference(set([0, 1])) else: support_complement = set(ct.index_set()).difference(support).difference(set([0])) - return DiGraph(DynkinDiagram(ct)).subgraph(support_complement, algorithm="delete").connected_components_number() - 1 + return DiGraph(DynkinDiagram(ct)).subgraph(support_complement, algorithm='delete').connected_components_number() - 1 class PieriFactors_type_D_affine(PieriFactors_affine_type): diff --git a/src/sage/combinat/root_system/plot.py b/src/sage/combinat/root_system/plot.py index 483c510eb61..1ffa81daf78 100644 --- a/src/sage/combinat/root_system/plot.py +++ b/src/sage/combinat/root_system/plot.py @@ -73,14 +73,14 @@ `G_2`:: sage: L = RootSystem(["G",2]).ambient_space() - sage: L.plot(reflection_hyperplanes="all") + sage: L.plot(reflection_hyperplanes='all') Graphics object consisting of 21 graphics primitives .. PLOT:: :width: 300 px L = RootSystem(["G",2]).ambient_space() - sphinx_plot(L.plot(reflection_hyperplanes="all")) + sphinx_plot(L.plot(reflection_hyperplanes='all')) The group is now the dihedral group of order 12, generated by the two reflections `s_1` and `s_2`. The picture displays the hyperplanes for @@ -108,7 +108,7 @@ its corresponding reflection hyperplane:: sage: L = RootSystem(["A",2]).weight_space() - sage: L.plot(roots="all", reflection_hyperplanes="all").show(figsize=15) + sage: L.plot(roots='all', reflection_hyperplanes='all').show(figsize=15) .. NOTE:: @@ -120,7 +120,7 @@ :width: 300 px L = RootSystem(["A",2]).weight_space() - sphinx_plot(L.plot(roots="all", reflection_hyperplanes="all")) + sphinx_plot(L.plot(roots='all', reflection_hyperplanes='all')) One can further customize which roots to display, as in the following example showing the positive roots in the @@ -150,7 +150,7 @@ sage: L = RootSystem(["E",8]).ambient_space() sage: L.dimension() 8 - sage: L.plot(roots="all", reflection_hyperplanes=False, # long time + sage: L.plot(roots='all', reflection_hyperplanes=False, # long time ....: projection=lambda v: M*vector(v), labels=False) Graphics3d Object @@ -161,7 +161,7 @@ [0.180913155536, 0., 0.160212955043, 0.160212955043, 0., 0.0990170516545, 0.766360424875, 0.0990170516545], [0.338261212718, 0, 0, -0.338261212718, 0.672816364803, 0.171502564281, 0, -0.171502564281]]) L = RootSystem(["E",8]).ambient_space() - sphinx_plot(L.plot(roots="all", reflection_hyperplanes=False, projection=lambda v: M*vector(v), labels=False)) + sphinx_plot(L.plot(roots='all', reflection_hyperplanes=False, projection=lambda v: M*vector(v), labels=False)) The projection function should be linear or affine, and return a vector with rational coordinates. The rationale for the later @@ -292,14 +292,14 @@ `u = vs_i`; the color of that wall is given by `i`:: sage: L = RootSystem(["C",2,1]).ambient_space() - sage: L.plot(coroots="simple", alcove_labels=True) # long time + sage: L.plot(coroots='simple', alcove_labels=True) # long time Graphics object consisting of 216 graphics primitives .. PLOT:: :width: 300 px L = RootSystem(["C",2,1]).ambient_space() - sphinx_plot(L.plot(coroots="simple", alcove_labels=True)) + sphinx_plot(L.plot(coroots='simple', alcove_labels=True)) Even 2D pictures of the rank `1 + 1` cases can give some food for thought. Here, we draw the root lattice, with the positive roots of @@ -507,9 +507,9 @@ sage: plot_options = L.plot_parse_options(bounding_box=[[-2,5],[-2,6]]) sage: w2 = [2,1,2,0,2,0,2,1,2,0,1,2,1,2,1,0,1,2,0,2,0,1,2,0,2] sage: p = L.plot_alcoves(plot_options=plot_options) - sage: p += L.plot_alcove_walk(w1, color="green", + sage: p += L.plot_alcove_walk(w1, color='green', ....: plot_options=plot_options) - sage: p += L.plot_alcove_walk(w2, color="orange", + sage: p += L.plot_alcove_walk(w2, color='orange', ....: plot_options=plot_options) sage: p Graphics object consisting of ... graphics primitives @@ -522,15 +522,15 @@ plot_options = L.plot_parse_options(bounding_box=[[-2,5],[-2,6]]) w2 = [2,1,2,0,2,0,2,1,2,0,1,2,1,2,1,0,1,2,0,2,0,1,2,0,2] sphinx_plot(L.plot_alcoves(plot_options=plot_options) - + L.plot_alcove_walk(w1, color="green", plot_options=plot_options) - + L.plot_alcove_walk(w2, color="orange", plot_options=plot_options)) + + L.plot_alcove_walk(w1, color='green', plot_options=plot_options) + + L.plot_alcove_walk(w2, color='orange', plot_options=plot_options)) And another with some foldings:: sage: p += L.plot_alcove_walk([0,1,2,0,2,0,1,2,0,1], ....: foldings=[False, False, True, False, False, ....: False, True, False, True, False], - ....: color="purple") + ....: color='purple') sage: p.axes(False) sage: p.show(figsize=20) @@ -542,11 +542,11 @@ plot_options = L.plot_parse_options(bounding_box=[[-2,5],[-2,6]]) w2 = [2,1,2,0,2,0,2,1,2,0,1,2,1,2,1,0,1,2,0,2,0,1,2,0,2] p = L.plot_alcoves(plot_options=plot_options) - p += L.plot_alcove_walk(w1, color="green", plot_options=plot_options) - p += L.plot_alcove_walk(w2, color="orange", plot_options=plot_options) + p += L.plot_alcove_walk(w1, color='green', plot_options=plot_options) + p += L.plot_alcove_walk(w2, color='orange', plot_options=plot_options) p += L.plot_alcove_walk([0,1,2,0,2,0,1,2,0,1], foldings=[False, False, True, False, False, False, True, False, True, False], - color="purple") + color='purple') p.axes(False) sphinx_plot(p) @@ -561,7 +561,7 @@ sage: walk = L.reduced_word_of_translation(L(t)) sage: plot_options = L.plot_parse_options(bounding_box=[[-2,5],[-2,5]]) sage: p = L.plot(plot_options=plot_options) - sage: p += L.plot_alcove_walk(walk, color="green", + sage: p += L.plot_alcove_walk(walk, color='green', ....: plot_options=plot_options) sage: p += plot_options.family_of_vectors({t: L(t)}) sage: plot_options.finalize(p) @@ -579,7 +579,7 @@ walk = L.reduced_word_of_translation(L(t)) plot_options = L.plot_parse_options(bounding_box=[[-2,5],[-2,5]]) p = L.plot(plot_options=plot_options) # long time - p += L.plot_alcove_walk(walk, color="green", plot_options=plot_options) + p += L.plot_alcove_walk(walk, color='green', plot_options=plot_options) p += plot_options.family_of_vectors({t: L(t)}) plot_options.finalize(p) sphinx_plot(p) @@ -649,7 +649,7 @@ sage: L = RootSystem(["C",2,1]).ambient_space() sage: p = L.plot(bounding_box=[[-8,9],[-5,7]], # long time (10 s) - ....: coroots="simple") + ....: coroots='simple') sage: p # long time Graphics object consisting of ... graphics primitives @@ -657,7 +657,7 @@ :width: 300 px L = RootSystem(["C",2,1]).ambient_space() - sphinx_plot(L.plot(bounding_box=[[-8,9],[-5,7]], coroots="simple")) + sphinx_plot(L.plot(bounding_box=[[-8,9],[-5,7]], coroots='simple')) By default Sage's plot are bitmap pictures which would come out ugly if printed on paper. Instead, we recommend saving the picture in @@ -688,7 +688,7 @@ sage: rho = L.rho() sage: plot_options = L.plot_parse_options() sage: W = L.weyl_group() - sage: g = W.cayley_graph(side="right") + sage: g = W.cayley_graph(side='right') sage: positions = {w: plot_options.projection(w.action(rho)) for w in W} sage: p = L.plot_alcoves() sage: p += g.plot(pos=positions, vertex_size=0, @@ -704,7 +704,7 @@ rho = L.rho() plot_options = L.plot_parse_options() W = L.weyl_group() - g = W.cayley_graph(side="right") + g = W.cayley_graph(side='right') positions = {w: plot_options.projection(w.action(rho)) for w in W} p = L.plot_alcoves() p += g.plot(pos = positions, vertex_size=0, color_by_label=plot_options.color) @@ -719,7 +719,7 @@ sage: rho = L.rho() sage: plot_options = L.plot_parse_options() sage: W = L.weyl_group() - sage: g = W.cayley_graph(side="right") + sage: g = W.cayley_graph(side='right') sage: positions = {w: plot_options.projection(w.action(rho)) for w in W} sage: p = L.plot_roots() sage: p += g.plot3d(pos3d=positions, color_by_label=plot_options.color) @@ -733,7 +733,7 @@ rho = L.rho() plot_options = L.plot_parse_options() W = L.weyl_group() - g = W.cayley_graph(side="right") + g = W.cayley_graph(side='right') positions = {w: plot_options.projection(w.action(rho)) for w in W} sphinx_plot(L.plot_roots() + g.plot3d(pos3d=positions, color_by_label=plot_options.color)) @@ -973,12 +973,11 @@ def in_bounding_box(self, x): def text(self, label, position, rgbcolor=(0,0,0)): r""" - Return text widget with label ``label`` at position ``position`` + Return text widget with label ``label`` at position ``position``. INPUT: - - ``label`` -- a string, or a Sage object upon which latex will - be called + - ``label`` -- string or Sage object upon which latex will be called - ``position`` -- a position @@ -1124,9 +1123,7 @@ def projection(self, v): - ``x`` -- an element of the root lattice realization - OUTPUT: - - An immutable vector with integer or rational coefficients. + OUTPUT: an immutable vector with integer or rational coefficients EXAMPLES:: @@ -1170,7 +1167,6 @@ def intersection_at_level_1(self, x): sage: options = L.plot_parse_options(affine=False) sage: options.intersection_at_level_1(L.rho()) Lambda[0] + Lambda[1] + Lambda[2] - """ if self.level is not None: return x * self.level / x.level() @@ -1334,7 +1330,7 @@ def family_of_vectors(self, vectors): G += self.text(i, 1.05*head) return self.finalize(G) - def cone(self, rays=[], lines=[], color="black", thickness=1, alpha=1, wireframe=False, + def cone(self, rays=[], lines=[], color='black', thickness=1, alpha=1, wireframe=False, label=None, draw_degenerate=True, as_polyhedron=False): r""" Return the cone generated by the given rays and lines. @@ -1344,28 +1340,26 @@ def cone(self, rays=[], lines=[], color="black", thickness=1, alpha=1, wireframe - ``rays``, ``lines`` -- lists of elements of the root lattice realization (default: ``[]``) - - ``color`` -- a color (default: ``"black"``) + - ``color`` -- a color (default: ``'black'``) - ``alpha`` -- a number in the interval `[0, 1]` (default: `1`) the desired transparency - - ``label`` -- an object to be used as the label for this cone. + - ``label`` -- an object to be used as the label for this cone The label itself will be constructed by calling :func:`~sage.misc.latex.latex` or :func:`repr` on the object depending on the graphics backend. - - ``draw_degenerate`` -- a boolean (default: ``True``) + - ``draw_degenerate`` -- boolean (default: ``True``) whether to draw cones with a degenerate intersection with the bounding box - - ``as_polyhedron`` -- a boolean (default: ``False``) + - ``as_polyhedron`` -- boolean (default: ``False``) whether to return the result as a polyhedron, without clipping it to the bounding box, and without making a plot out of it (for testing purposes) - OUTPUT: - - A graphic object, a polyhedron, or ``0``. + OUTPUT: a graphic object, a polyhedron, or ``0`` EXAMPLES:: @@ -1598,7 +1592,6 @@ def barycentric_projection_matrix(n, angle=0): ....: m = barycentric_projection_matrix(n) ....: assert sum(m.columns()).is_zero() ....: assert matrix(QQ, n+1,n+1, lambda i,j: 1 if i==j else -1/n) == m.transpose()*m - """ from sage.matrix.constructor import matrix from sage.misc.functional import sqrt diff --git a/src/sage/combinat/root_system/reflection_group_c.pyx b/src/sage/combinat/root_system/reflection_group_c.pyx index dbfc76282f8..2f2c1b43aaf 100644 --- a/src/sage/combinat/root_system/reflection_group_c.pyx +++ b/src/sage/combinat/root_system/reflection_group_c.pyx @@ -43,7 +43,7 @@ cdef class Iterator(): sage: from sage.combinat.root_system.reflection_group_c import Iterator sage: W = ReflectionGroup(["B", 4]) # optional - gap3 sage: I = Iterator(W, W.number_of_reflections()) # optional - gap3 - sage: TestSuite(I).run(skip="_test_pickling") # optional - gap3 + sage: TestSuite(I).run(skip='_test_pickling') # optional - gap3 """ cdef tuple S = self.S cdef int n = len(S) @@ -62,7 +62,7 @@ cdef class Iterator(): noncom.append(list(range(n))) return noncom - def __init__(self, W, int N, str algorithm="depth", bint tracking_words=True, + def __init__(self, W, int N, str algorithm='depth', bint tracking_words=True, order=None): """ Initialize ``self``. @@ -72,7 +72,7 @@ cdef class Iterator(): sage: from sage.combinat.root_system.reflection_group_c import Iterator sage: W = ReflectionGroup(["B", 4]) # optional - gap3 sage: I = Iterator(W, W.number_of_reflections()) # optional - gap3 - sage: TestSuite(I).run(skip="_test_pickling") # optional - gap3 + sage: TestSuite(I).run(skip='_test_pickling') # optional - gap3 """ self.S = tuple(W.simple_reflections()) self.n = len(W._index_set) @@ -189,7 +189,7 @@ cdef class Iterator(): EXAMPLES:: sage: from sage.combinat.root_system.reflection_group_c import Iterator - sage: W = CoxeterGroup(['B',2], implementation="permutation") + sage: W = CoxeterGroup(['B',2], implementation='permutation') sage: I = Iterator(W, W.number_of_reflections()) sage: list(I.iter_depth()) [(), @@ -225,7 +225,7 @@ cdef class Iterator(): EXAMPLES:: sage: from sage.combinat.root_system.reflection_group_c import Iterator - sage: W = CoxeterGroup(['B',2], implementation="permutation") + sage: W = CoxeterGroup(['B',2], implementation='permutation') sage: I = Iterator(W, W.number_of_reflections()) sage: for w in I.iter_words_depth(): w._reduced_word [] @@ -265,7 +265,7 @@ cdef class Iterator(): EXAMPLES:: sage: from sage.combinat.root_system.reflection_group_c import Iterator - sage: W = CoxeterGroup(['B',2], implementation="permutation") + sage: W = CoxeterGroup(['B',2], implementation='permutation') sage: I = Iterator(W, W.number_of_reflections()) sage: list(I.iter_breadth()) [(), @@ -301,7 +301,7 @@ cdef class Iterator(): EXAMPLES:: sage: from sage.combinat.root_system.reflection_group_c import Iterator - sage: W = CoxeterGroup(['B',2], implementation="permutation") + sage: W = CoxeterGroup(['B',2], implementation='permutation') sage: I = Iterator(W, W.number_of_reflections()) sage: for w in I.iter_words_breadth(): w._reduced_word [] @@ -344,7 +344,7 @@ cdef class Iterator(): EXAMPLES:: sage: from sage.combinat.root_system.reflection_group_c import Iterator - sage: W = CoxeterGroup(['B',2], implementation="permutation") + sage: W = CoxeterGroup(['B',2], implementation='permutation') sage: I = Iterator(W, W.number_of_reflections()) sage: sorted(I.iter_parabolic()) [(), @@ -468,7 +468,7 @@ cpdef PermutationGroupElement reduce_in_coset(PermutationGroupElement w, tuple S EXAMPLES:: sage: from sage.combinat.root_system.reflection_group_c import reduce_in_coset - sage: W = CoxeterGroup(['B',3], implementation="permutation") + sage: W = CoxeterGroup(['B',3], implementation='permutation') sage: N = W.number_of_reflections() sage: s = W.simple_reflections() sage: w = s[2] * s[1] * s[3] @@ -545,7 +545,7 @@ def parabolic_iteration_application(W, f): EXAMPLES:: - sage: W = CoxeterGroup(['E',6], implementation="permutation") + sage: W = CoxeterGroup(['E',6], implementation='permutation') sage: from sage.combinat.root_system.reflection_group_c import parabolic_iteration_application sage: lst = [] sage: def f(x): @@ -564,7 +564,7 @@ def parabolic_iteration_application(W, f): cpdef list reduced_word_c(W, PermutationGroupElement w): r""" - Computes a reduced word for the element ``w`` in the + Compute a reduced word for the element ``w`` in the reflection group ``W`` in the positions ``range(n)``. EXAMPLES:: diff --git a/src/sage/combinat/root_system/reflection_group_complex.py b/src/sage/combinat/root_system/reflection_group_complex.py index d4c6c5b677b..e89a01bff40 100644 --- a/src/sage/combinat/root_system/reflection_group_complex.py +++ b/src/sage/combinat/root_system/reflection_group_complex.py @@ -553,7 +553,7 @@ def reflection_hyperplanes(self, as_linear_functionals=False, with_order=False): INPUT: - - ``as_linear_functionals`` -- (default:``False``) flag whether + - ``as_linear_functionals`` -- boolean (default: ``False``); whether to return the hyperplane or its linear functional in the basis dual to the given root basis @@ -626,7 +626,7 @@ def reflection_hyperplane(self, i, as_linear_functional=False, with_order=False) INPUT: - ``i`` -- an index in the index set - - ``as_linear_functionals`` -- (default:``False``) flag whether + - ``as_linear_functionals`` -- boolean (default: ``False``); whether to return the hyperplane or its linear functional in the basis dual to the given root basis @@ -855,7 +855,7 @@ def discriminant_in_invariant_ring(self, invariants=None): @cached_method def is_crystallographic(self): r""" - Return ``True`` if self is crystallographic. + Return ``True`` if ``self`` is crystallographic. This is, if the field of definition is the rational field. @@ -1122,9 +1122,7 @@ def reflection_eigenvalues_family(self): Return the reflection eigenvalues of ``self`` as a finite family indexed by the class representatives of ``self``. - OUTPUT: - - - list with entries `k/n` representing the eigenvalue `\zeta_n^k`. + OUTPUT: list with entries `k/n` representing the eigenvalue `\zeta_n^k` EXAMPLES:: @@ -1173,8 +1171,8 @@ def reflection_eigenvalues(self, w, is_class_representative=False): INPUT: - - ``is_class_representative`` -- boolean (default ``True``) whether to - compute instead on the conjugacy class representative. + - ``is_class_representative`` -- boolean (default: ``True``) whether to + compute instead on the conjugacy class representative .. SEEALSO:: :meth:`reflection_eigenvalues_family` @@ -1493,7 +1491,7 @@ def primitive_vector_field(self, invs=None): def apply_vector_field(self, f, vf=None): r""" - Returns a rational function obtained by applying the vector + Return a rational function obtained by applying the vector field ``vf`` to the rational function ``f``. If ``vf`` is not given, the primitive vector field is used. @@ -1790,7 +1788,7 @@ def set_reflection_representation(self,refl_repr=None): INPUT: - - ``refl_repr`` -- a dictionary representing the matrices of the + - ``refl_repr`` -- dictionary representing the matrices of the generators of ``self`` with keys given by the index set, or ``None`` to reset to the default reflection representation @@ -2002,7 +2000,7 @@ def reflection_length(self, in_unitary_group=False): INPUT: - - ``in_unitary_group`` -- (default: ``False``) if ``True``, + - ``in_unitary_group`` -- boolean (default: ``False``); if ``True``, the reflection length is computed in the unitary group which is the dimension of the move space of ``self`` @@ -2070,11 +2068,11 @@ def is_coxeter_element(self, which_primitive=1, is_class_representative=False): INPUT: - - ``which_primitive`` -- (default:``1``) for which power of + - ``which_primitive`` -- (default: ``1``) for which power of the first primitive ``h``-th root of unity to look as a reflection eigenvalue for a regular element - - ``is_class_representative`` -- boolean (default ``True``) whether + - ``is_class_representative`` -- boolean (default: ``True``); whether to compute instead on the conjugacy class representative .. SEEALSO:: @@ -2140,7 +2138,7 @@ def is_regular(self, h, is_class_representative=False): INPUT: - ``h`` -- the order of the eigenvalue - - ``is_class_representative`` -- boolean (default ``True``) whether + - ``is_class_representative`` -- boolean (default: ``True``); whether to compute instead on the conjugacy class representative EXAMPLES:: diff --git a/src/sage/combinat/root_system/reflection_group_element.pyx b/src/sage/combinat/root_system/reflection_group_element.pyx index 3d81a84ff4b..ca72f87d740 100644 --- a/src/sage/combinat/root_system/reflection_group_element.pyx +++ b/src/sage/combinat/root_system/reflection_group_element.pyx @@ -102,7 +102,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): @lazy_attribute def _reduced_word(self): r""" - Computes a reduced word and stores it into ``self._reduced_word``. + Compute a reduced word and stores it into ``self._reduced_word``. TESTS:: @@ -181,12 +181,12 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): return ZZ(len(self.reduced_word())) # @cached_in_parent_method - def to_matrix(self, on_space="primal"): + def to_matrix(self, on_space='primal'): r""" Return ``self`` as a matrix acting on the underlying vector space. - - ``on_space`` -- optional (default: ``"primal"``) whether + - ``on_space`` -- (default: ``'primal'``) whether to act as the reflection representation on the given basis, or to act on the dual reflection representation on the dual basis @@ -194,10 +194,10 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): EXAMPLES:: sage: W = ReflectionGroup((3,1,2)) # optional - gap3 - sage: data = {w: [w.to_matrix(), w.to_matrix(on_space="dual")] for w in W} # optional - gap3 + sage: data = {w: [w.to_matrix(), w.to_matrix(on_space='dual')] for w in W} # optional - gap3 sage: for w in W.iteration_tracking_words(): # optional - gap3 ....: w.reduced_word() - ....: mats = [w.to_matrix(), w.to_matrix(on_space="dual")] + ....: mats = [w.to_matrix(), w.to_matrix(on_space='dual')] ....: mats ....: assert data[w] == mats [] @@ -318,7 +318,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): EXAMPLES:: sage: # needs sage.graphs - sage: W = WeylGroup(['A',2], prefix='s', implementation="permutation") + sage: W = WeylGroup(['A',2], prefix='s', implementation='permutation') sage: for w in W: ....: w.reduced_word() ....: w.canonical_matrix() @@ -348,7 +348,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): mat.set_immutable() return mat - cpdef action(self, vec, on_space="primal"): + cpdef action(self, vec, on_space='primal'): r""" Return the image of ``vec`` under the action of ``self``. @@ -356,7 +356,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): - ``vec`` -- vector in the basis given by the simple root - - ``on_space`` -- optional (default: ``"primal"``) whether + - ``on_space`` -- (default: ``'primal'``) whether to act as the reflection representation on the given basis, or to act on the dual reflection representation on the dual basis @@ -375,7 +375,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): cpdef _act_on_(self, vec, bint self_on_left): r""" - Defines the action of ``self`` as a linear transformation + Define the action of ``self`` as a linear transformation on the vector space, in the basis given by the simple roots. @@ -444,7 +444,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): sage: W = ReflectionGroup(['A',2]) # optional - gap3 sage: for w in W: # optional - gap3 ....: print("%s %s"%(w.reduced_word(), - ....: [w.action_on_root(beta,side="left") for beta in W.positive_roots()])) + ....: [w.action_on_root(beta,side='left') for beta in W.positive_roots()])) [] [(1, 0), (0, 1), (1, 1)] [2] [(1, 1), (0, -1), (1, 0)] [1] [(-1, 0), (1, 1), (0, 1)] @@ -539,7 +539,7 @@ cdef class ComplexReflectionGroupElement(PermutationGroupElement): INPUT: - - ``is_class_representative`` -- (default: ``False``) whether + - ``is_class_representative`` -- boolean (default: ``False``); whether to first replace ``self`` by the representative of its conjugacy class @@ -696,7 +696,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): @lazy_attribute def _reduced_word(self): r""" - Computes a reduced word and stores it into ``self._reduced_word``. + Compute a reduced word and stores it into ``self._reduced_word``. The words are in ``range(n)`` and not in the index set. TESTS:: @@ -785,18 +785,18 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): # we also check == because 0-based indexing return self.perm[W._index_set_inverse[i]] >= W.number_of_reflections() - cpdef bint has_descent(self, i, side="left", positive=False) noexcept: + cpdef bint has_descent(self, i, side='left', positive=False) noexcept: r""" - Return whether ``i`` is a descent (or ascent) of ``self``. + Return whether `i` is a descent (or ascent) of ``self``. - This is done by testing whether ``i`` is mapped by ``self`` + This is done by testing whether `i` is mapped by ``self`` to a negative root. INPUT: - ``i`` -- an index of a simple reflection - - ``side`` (default: ``'right'``) -- ``'left'`` or ``'right'`` - - ``positive`` (default: ``False``) -- a boolean + - ``side`` -- (default: ``'right'``) ``'left'`` or ``'right'`` + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -823,7 +823,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): else: raise ValueError('side must be "left" or "right"') - def coset_representative(self, index_set, side="right"): + def coset_representative(self, index_set, side='right'): """ Return the unique shortest element of the Coxeter group `W` which is in the same left (resp. right) coset as @@ -837,7 +837,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): EXAMPLES:: sage: # needs sage.graphs - sage: W = CoxeterGroup(['A',4], implementation="permutation") + sage: W = CoxeterGroup(['A',4], implementation='permutation') sage: s = W.simple_reflections() sage: w = s[2] * s[1] * s[3] sage: w.coset_representative([]).reduced_word() @@ -868,17 +868,17 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): S = tuple(self._parent.simple_reflections()) N = self._parent.number_of_reflections() I = self._parent._index_set_inverse - return reduce_in_coset(self, S, [I[i] for i in index_set], N, side=="left") + return reduce_in_coset(self, S, [I[i] for i in index_set], N, side=='left') - def to_matrix(self, side="right", on_space="primal"): + def to_matrix(self, side='right', on_space='primal'): r""" Return ``self`` as a matrix acting on the underlying vector space. - - ``side`` -- optional (default: ``"right"``) whether the - action of ``self`` is on the ``"left"`` or on the ``"right"`` + - ``side`` -- (default: ``'right'``) whether the + action of ``self`` is on the ``'left'`` or on the ``'right'`` - - ``on_space`` -- optional (default: ``"primal"``) whether + - ``on_space`` -- (default: ``'primal'``) whether to act as the reflection representation on the given basis, or to act on the dual reflection representation on the dual basis @@ -888,7 +888,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): sage: W = ReflectionGroup(['A',2]) # optional - gap3 sage: for w in W: # optional - gap3 ....: w.reduced_word() - ....: [w.to_matrix(), w.to_matrix(on_space="dual")] + ....: [w.to_matrix(), w.to_matrix(on_space='dual')] [] [ [1 0] [1 0] @@ -923,9 +923,9 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): TESTS:: sage: W = ReflectionGroup(['F',4]) # optional - gap3 - sage: all(w.to_matrix(side="left") == W.from_reduced_word(reversed(w.reduced_word())).to_matrix(side="right").transpose() for w in W) # optional - gap3 + sage: all(w.to_matrix(side='left') == W.from_reduced_word(reversed(w.reduced_word())).to_matrix(side='right').transpose() for w in W) # optional - gap3 True - sage: all(w.to_matrix(side="right") == W.from_reduced_word(reversed(w.reduced_word())).to_matrix(side="left").transpose() for w in W) # optional - gap3 + sage: all(w.to_matrix(side='right') == W.from_reduced_word(reversed(w.reduced_word())).to_matrix(side='left').transpose() for w in W) # optional - gap3 True """ W = self._parent @@ -959,7 +959,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): matrix = to_matrix - cpdef action(self, vec, side="right", on_space="primal"): + cpdef action(self, vec, side='right', on_space='primal'): r""" Return the image of ``vec`` under the action of ``self``. @@ -967,10 +967,10 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): - ``vec`` -- vector in the basis given by the simple root - - ``side`` -- optional (default: ``"right"``) whether the - action of ``self`` is on the ``"left"`` or on the ``"right"`` + - ``side`` -- (default: ``'right'``) whether the + action of ``self`` is on the ``'left'`` or on the ``'right'`` - - ``on_space`` -- optional (default: ``"primal"``) whether + - ``on_space`` -- (default: ``'primal'``) whether to act as the reflection representation on the given basis, or to act on the dual reflection representation on the dual basis @@ -980,7 +980,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): sage: W = ReflectionGroup(['A',2]) # optional - gap3 sage: for w in W: # optional - gap3 ....: print("%s %s"%(w.reduced_word(), - ....: [w.action(weight,side="left") for weight in W.fundamental_weights()])) + ....: [w.action(weight,side='left') for weight in W.fundamental_weights()])) [] [(2/3, 1/3), (1/3, 2/3)] [2] [(2/3, 1/3), (1/3, -1/3)] [1] [(-1/3, 1/3), (1/3, 2/3)] @@ -991,10 +991,10 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): TESTS:: sage: W = ReflectionGroup(['B',3]) # optional - gap3 - sage: all(w.action(alpha,side="right") == w.action_on_root(alpha,side="right") # optional - gap3 + sage: all(w.action(alpha,side='right') == w.action_on_root(alpha,side='right') # optional - gap3 ....: for w in W for alpha in W.simple_roots()) True - sage: all(w.action(alpha,side="left") == w.action_on_root(alpha,side="left") #optional - gap3 + sage: all(w.action(alpha,side='left') == w.action_on_root(alpha,side='left') #optional - gap3 ....: for w in W for alpha in W.simple_roots()) True """ @@ -1051,10 +1051,10 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): (1, 1) -> (0, -1) """ if self_on_left: - return self.action(vec, side="left") - return self.action(vec, side="right") + return self.action(vec, side='left') + return self.action(vec, side='right') - cpdef action_on_root_indices(self, i, side="right"): + cpdef action_on_root_indices(self, i, side='right'): """ Return the action on the set of roots. @@ -1062,7 +1062,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): - ``i`` -- index of the root to act on - - ``side`` -- optional (default: ``"right"``) whether the + - ``side`` -- (default: ``'right'``) whether the action is on the left or on the right EXAMPLES:: @@ -1071,14 +1071,14 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): sage: W = ReflectionGroup(['A',3]) sage: w = W.w0 sage: N = len(W.roots()) - sage: [w.action_on_root_indices(i,side="left") for i in range(N)] + sage: [w.action_on_root_indices(i,side='left') for i in range(N)] [8, 7, 6, 10, 9, 11, 2, 1, 0, 4, 3, 5] sage: # optional - gap3 sage: W = ReflectionGroup(['A',2], reflection_index_set=['A','B','C']) sage: w = W.w0 sage: N = len(W.roots()) - sage: [w.action_on_root_indices(i,side="left") for i in range(N)] + sage: [w.action_on_root_indices(i,side='left') for i in range(N)] [4, 3, 5, 1, 0, 2] """ cdef RealReflectionGroupElement w @@ -1090,7 +1090,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): raise ValueError('side must be "left" or "right"') return w.perm[i] - def action_on_root(self, root, side="right"): + def action_on_root(self, root, side='right'): r""" Return the root obtained by applying ``self`` to ``root``. @@ -1098,7 +1098,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): - ``root`` -- the root to act on - - ``side`` -- optional (default: ``"right"``) whether the + - ``side`` -- (default: ``'right'``) whether the action is on the left or on the right EXAMPLES:: @@ -1106,7 +1106,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): sage: W = ReflectionGroup(['A',2]) # optional - gap3 sage: for w in W: # optional - gap3 ....: print("%s %s"%(w.reduced_word(), - ....: [w.action_on_root(beta,side="left") for beta in W.positive_roots()])) + ....: [w.action_on_root(beta,side='left') for beta in W.positive_roots()])) [] [(1, 0), (0, 1), (1, 1)] [2] [(1, 1), (0, -1), (1, 0)] [1] [(-1, 0), (1, 1), (0, 1)] @@ -1117,7 +1117,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): sage: W = ReflectionGroup(['A',2]) # optional - gap3 sage: for w in W: # optional - gap3 ....: print("%s %s"%(w.reduced_word(), - ....: [w.action_on_root(beta,side="right") for beta in W.positive_roots()])) + ....: [w.action_on_root(beta,side='right') for beta in W.positive_roots()])) [] [(1, 0), (0, 1), (1, 1)] [2] [(1, 1), (0, -1), (1, 0)] [1] [(-1, 0), (1, 1), (0, 1)] @@ -1128,7 +1128,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): Phi = self._parent.roots() return Phi[self.action_on_root_indices(Phi.index(root), side=side)] - def inversion_set(self, side="right"): + def inversion_set(self, side='right'): r""" Return the inversion set of ``self``. @@ -1147,7 +1147,7 @@ cdef class RealReflectionGroupElement(ComplexReflectionGroupElement): [2, 1] [(0, 1), (1, 1)] [1, 2, 1] [(1, 0), (0, 1), (1, 1)] - sage: W.from_reduced_word([1,2]).inversion_set(side="left") # optional - gap3 + sage: W.from_reduced_word([1,2]).inversion_set(side='left') # optional - gap3 [(0, 1), (1, 1)] """ N = self._parent.number_of_reflections() diff --git a/src/sage/combinat/root_system/reflection_group_real.py b/src/sage/combinat/root_system/reflection_group_real.py index c49c3e8bc6e..9ad56e53423 100644 --- a/src/sage/combinat/root_system/reflection_group_real.py +++ b/src/sage/combinat/root_system/reflection_group_real.py @@ -53,7 +53,7 @@ from sage.combinat.root_system.reflection_group_element import RealReflectionGroupElement -def ReflectionGroup(*args,**kwds): +def ReflectionGroup(*args, **kwds): r""" Construct a finite (complex or real) reflection group as a Sage permutation group by fetching the permutation representation of the @@ -61,7 +61,7 @@ def ReflectionGroup(*args,**kwds): INPUT: - can be one or multiple of the following: + Can be one or multiple of the following: - a triple `(r, p, n)` with `p` divides `r`, which denotes the group `G(r, p, n)` @@ -295,13 +295,13 @@ def _repr_(self): type_str = type_str[:-3] return 'Reducible real reflection group of rank %s and type %s' % (self._rank, type_str) - def iteration(self, algorithm="breadth", tracking_words=True): + def iteration(self, algorithm='breadth', tracking_words=True): r""" Return an iterator going through all elements in ``self``. INPUT: - - ``algorithm`` (default: ``'breadth'``) -- must be one of + - ``algorithm`` -- (default: ``'breadth'``) must be one of the following: * ``'breadth'`` -- iterate over in a linear extension of the @@ -309,8 +309,8 @@ def iteration(self, algorithm="breadth", tracking_words=True): * ``'depth'`` -- iterate by a depth-first-search * ``'parabolic'`` -- iterate by using parabolic subgroups - - ``tracking_words`` (default: ``True``) -- whether or not to keep - track of the reduced words and store them in ``_reduced_word`` + - ``tracking_words`` -- boolean (default: ``True``); whether or not to + keep track of the reduced words and store them in ``_reduced_word`` .. NOTE:: @@ -373,7 +373,7 @@ def __iter__(self): (1,7)(3,5)(4,8) [0, 1, 0] (1,5)(2,6)(3,7)(4,8) [0, 1, 0, 1] """ - return self.iteration(algorithm="breadth", tracking_words=True) + return self.iteration(algorithm='breadth', tracking_words=True) @cached_method def bipartite_index_set(self): @@ -727,7 +727,7 @@ def bruhat_cone(self, x, y, side='upper', backend='cdd'): - ``x`` -- an element in the group `W` - ``y`` -- an element in the group `W` - - ``side`` (default: ``'upper'``) -- must be one of the following: + - ``side`` -- (default: ``'upper'``) must be one of the following: * ``'upper'`` -- return the upper Bruhat cone of the interval [``x``, ``y``] * ``'lower'`` -- return the lower Bruhat cone of the interval [``x``, ``y``] diff --git a/src/sage/combinat/root_system/root_lattice_realization_algebras.py b/src/sage/combinat/root_system/root_lattice_realization_algebras.py index db3811b820d..030b108c774 100644 --- a/src/sage/combinat/root_system/root_lattice_realization_algebras.py +++ b/src/sage/combinat/root_system/root_lattice_realization_algebras.py @@ -295,7 +295,7 @@ def demazure_operators(self): ... ValueError: the weight does not have an integral scalar product with the coroot """ - return HeckeAlgebraRepresentation(self, self.isobaric_divided_difference_on_basis, self.cartan_type(), 0, 1, side="left") + return HeckeAlgebraRepresentation(self, self.isobaric_divided_difference_on_basis, self.cartan_type(), 0, 1, side='left') def _test_demazure_operators(self, **options): """ @@ -325,7 +325,7 @@ def _test_demazure_operators(self, **options): except ImportError: pass - def demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention="antidominant"): + def demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention='antidominant'): r""" Return the result of applying the `i`-th Demazure-Lusztig operator on ``weight``. @@ -334,7 +334,7 @@ def demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention="anti - ``weight`` -- an element `\lambda` of the weight lattice - ``i`` -- an element of the index set - ``q1``, ``q2`` -- two elements of the ground ring - - ``convention`` -- ``"antidominant"``, ``"bar"``, or ``"dominant"`` (default: ``"antidominant"``) + - ``convention`` -- ``'antidominant'``, ``'bar'``, or ``'dominant'`` (default: ``'antidominant'``) See :meth:`demazure_lusztig_operators` for the details. @@ -362,11 +362,11 @@ def demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention="anti Or `1-\pi_i` for ``bar=True``:: - sage: KL.demazure_lusztig_operator_on_basis(L((2,2)), 1, 1, 0, convention="bar") + sage: KL.demazure_lusztig_operator_on_basis(L((2,2)), 1, 1, 0, convention='bar') 0 - sage: KL.demazure_lusztig_operator_on_basis(L((3,0)), 1, 1, 0, convention="bar") + sage: KL.demazure_lusztig_operator_on_basis(L((3,0)), 1, 1, 0, convention='bar') -B[(1, 2)] - B[(2, 1)] - B[(0, 3)] - sage: KL.demazure_lusztig_operator_on_basis(L((0,3)), 1, 1, 0, convention="bar") + sage: KL.demazure_lusztig_operator_on_basis(L((0,3)), 1, 1, 0, convention='bar') B[(1, 2)] + B[(2, 1)] + B[(0, 3)] At `q_1=1` and `q_2=-1` we recover the action of the simple reflection `s_i`:: @@ -389,14 +389,14 @@ def demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention="anti else: return result - def demazure_lusztig_operators(self, q1, q2, convention="antidominant"): + def demazure_lusztig_operators(self, q1, q2, convention='antidominant'): r""" Return the Demazure-Lusztig operators acting on ``self``. INPUT: - ``q1``, ``q2`` -- two elements of the ground ring - - ``convention`` -- "antidominant", "bar", or "dominant" (default: "antidominant") + - ``convention`` -- "antidominant", "bar", or "dominant" (default: ``'antidominant'``) If `R` is the parent weight ring, the Demazure-Lusztig operator `T_i` is the linear map `R\rightarrow R` obtained @@ -448,9 +448,9 @@ def demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: q1, q2 = K.gens() sage: KL = L.algebra(K) sage: T = KL.demazure_lusztig_operators(q1, q2) - sage: Tbar = KL.demazure_lusztig_operators(q1, q2, convention="bar") + sage: Tbar = KL.demazure_lusztig_operators(q1, q2, convention='bar') sage: Tdominant = KL.demazure_lusztig_operators(q1, q2, - ....: convention="dominant") + ....: convention='dominant') sage: x = KL.monomial(L((3,0))) sage: T[1](x) (q1+q2)*B[(1, 2)] + (q1+q2)*B[(2, 1)] + (q1+q2)*B[(3, 0)] + q1*B[(0, 3)] @@ -471,9 +471,9 @@ def demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: q1, q2 = K.gens() sage: KL = L.algebra(K) sage: T = KL.demazure_lusztig_operators(q1, q2) - sage: Tbar = KL.demazure_lusztig_operators(q1, q2, convention="bar") + sage: Tbar = KL.demazure_lusztig_operators(q1, q2, convention='bar') sage: Tdominant = KL.demazure_lusztig_operators(q1, q2, - ....: convention="dominant") + ....: convention='dominant') sage: e = L.basis() sage: x = KL.monomial(3*e[0]) sage: T[1](x) @@ -515,7 +515,7 @@ def demazure_lusztig_operators(self, q1, q2, convention="antidominant"): And the `\bar{T}` are basically the inverses of the `T` s:: sage: Tinv = KL.demazure_lusztig_operators(2/q1 + 1/q2, -1/q1, - ....: convention="bar") + ....: convention='bar') sage: [Tinv[1](T[1](x)) - x for x in KL.some_elements()] # needs sage.graphs [0, 0, 0, 0, 0, 0, 0] @@ -529,7 +529,7 @@ def demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: Lambda = L.fundamental_weights() # needs sage.graphs sage: alphacheck = L0.simple_coroots() sage: KL = L.algebra(K) - sage: T = KL.demazure_lusztig_operators(q1, q2, convention="dominant") + sage: T = KL.demazure_lusztig_operators(q1, q2, convention='dominant') sage: Y = T.Y() sage: alphacheck = Y.keys().alpha() # alpha of coroot lattice is alphacheck sage: alphacheck @@ -594,9 +594,9 @@ def demazure_lusztig_operators(self, q1, q2, convention="antidominant"): """ T_on_basis = functools.partial(self.demazure_lusztig_operator_on_basis, q1=q1, q2=q2, convention=convention) - return HeckeAlgebraRepresentation(self, T_on_basis, self.cartan_type(), q1, q2, side="left") + return HeckeAlgebraRepresentation(self, T_on_basis, self.cartan_type(), q1, q2, side='left') - def demazure_lusztig_operator_on_classical_on_basis(self, weight, i, q, q1, q2, convention="antidominant"): + def demazure_lusztig_operator_on_classical_on_basis(self, weight, i, q, q1, q2, convention='antidominant'): r""" Return the result of applying the `i`-th Demazure-Lusztig operator on the classical weight ``weight`` embedded at level 0. @@ -605,7 +605,7 @@ def demazure_lusztig_operator_on_classical_on_basis(self, weight, i, q, q1, q2, - ``weight`` -- a classical weight `\lambda` - ``i`` -- an element of the index set - ``q1``, ``q2`` -- two elements of the ground ring - - ``convention`` -- ``"antidominant"``, ``"bar"``, or ``"dominant"`` (default: ``"antidominant"``) + - ``convention`` -- ``'antidominant'``, ``'bar'``, or ``'dominant'`` (default: ``'antidominant'``) See :meth:`demazure_lusztig_operators` for the details. @@ -652,14 +652,14 @@ def demazure_lusztig_operator_on_classical_on_basis(self, weight, i, q, q1, q2, weight = L.embed_at_level(weight, 0) return self.q_project(self.demazure_lusztig_operator_on_basis(weight, i, q1, q2, convention=convention), q) - def demazure_lusztig_operators_on_classical(self, q, q1, q2, convention="antidominant"): + def demazure_lusztig_operators_on_classical(self, q, q1, q2, convention='antidominant'): r""" Return the Demazure-Lusztig operators acting at level 1 on ``self.classical()``. INPUT: - ``q``, ``q1``, ``q2`` -- three elements of the ground ring - - ``convention`` -- ``"antidominant"``, ``"bar"``, or ``"dominant"`` (default: ``"antidominant"``) + - ``convention`` -- ``'antidominant'``, ``'bar'``, or ``'dominant'`` (default: ``'antidominant'``) Let `KL` be the group algebra of an affine weight lattice realization `L`. The Demazure-Lusztig operators for `KL` @@ -722,7 +722,7 @@ def demazure_lusztig_operators_on_classical(self, q, q1, q2, convention="antidom sage: # needs sage.graphs sage: T = KL.demazure_lusztig_operators_on_classical(q, u, -1/u, - ....: convention="dominant") + ....: convention='dominant') sage: Y = T.Y() sage: alphacheck = Y.keys().simple_roots() sage: Ydelta = Y[Y.keys().null_root()] @@ -747,7 +747,6 @@ def demazure_lusztig_operators_on_classical(self, q, q1, q2, convention="antidom 1/(q*u)*B[Lambda[1]] sage: T0(KL0.monomial(-2*omega[1])) ((-u^2+1)/(q*u))*B[0] + 1/(q^2*u)*B[2*Lambda[1]] - """ # In type BC dual we used q^2 and q elsewhere # Not sure this is the right thing to do or just a workaround ... @@ -760,10 +759,10 @@ def demazure_lusztig_operators_on_classical(self, q, q1, q2, convention="antidom a0check = ct.acheck()[ct.special_node()] T_on_basis = functools.partial(self.demazure_lusztig_operator_on_classical_on_basis, q1=q1, q2=q2, q=q**a0check, convention=convention) - return HeckeAlgebraRepresentation(self.classical(), T_on_basis, self.cartan_type(), q1=q1, q2=q2, q=q, side="left") + return HeckeAlgebraRepresentation(self.classical(), T_on_basis, self.cartan_type(), q1=q1, q2=q2, q=q, side='left') @cached_method - def T0_check_on_basis(self, q1, q2, convention="antidominant"): + def T0_check_on_basis(self, q1, q2, convention='antidominant'): r""" Return the `T_0^\vee` operator acting on the basis. @@ -787,7 +786,7 @@ def T0_check_on_basis(self, q1, q2, convention="antidominant"): sage: L0 = L.classical() sage: KL = L.algebra(K) sage: some_weights = L.fundamental_weights() # needs sage.graphs - sage: f = KL.T0_check_on_basis(q1,q2, convention="dominant") # needs sage.graphs + sage: f = KL.T0_check_on_basis(q1,q2, convention='dominant') # needs sage.graphs sage: f(L0.zero()) # needs sage.graphs (q1+q2)*B[(0, 0)] + q1*B[(1, -1)] @@ -795,7 +794,7 @@ def T0_check_on_basis(self, q1, q2, convention="antidominant"): sage: L0 = L.classical() sage: KL = L.algebra(K) sage: some_weights = L0.fundamental_weights() - sage: f = KL.T0_check_on_basis(q1,q2, convention="dominant") # needs sage.graphs + sage: f = KL.T0_check_on_basis(q1,q2, convention='dominant') # needs sage.graphs sage: f(L0.zero()) # not checked # needs sage.graphs (q1+q2)*B[(0, 0, 0, 0)] + q1^3/q2^2*B[(1, 0, 0, -1)] @@ -818,14 +817,14 @@ def T0_check_on_basis(self, q1, q2, convention="antidominant"): sage: q2 = -1/u sage: KL = L.algebra(K) sage: KL0 = KL.classical() - sage: f = KL.T0_check_on_basis(q1,q2, convention="dominant") # needs sage.graphs - sage: T = KL.twisted_demazure_lusztig_operators(q1,q2, convention="dominant") + sage: f = KL.T0_check_on_basis(q1,q2, convention='dominant') # needs sage.graphs + sage: T = KL.twisted_demazure_lusztig_operators(q1,q2, convention='dominant') Direct calculation:: sage: T.Tw(0)(KL0.monomial(L0([0,0]))) # needs sage.graphs ((u^2-1)/u)*B[(0, 0)] + u^3*B[(1, 1)] - sage: KL.T0_check_on_basis(q1,q2, convention="dominant")(L0([0,0])) # needs sage.graphs + sage: KL.T0_check_on_basis(q1,q2, convention='dominant')(L0([0,0])) # needs sage.graphs ((u^2-1)/u)*B[(0, 0)] + u^3*B[(1, 1)] Step by step calculation, comparing by hand with Mark Shimozono:: @@ -970,7 +969,7 @@ def q_project(self, x, q): L0 = self.classical() return L0.linear_combination( (self.q_project_on_basis(l, q), c) for l,c in x ) - def twisted_demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention="antidominant"): + def twisted_demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, convention='antidominant'): r""" Return the twisted Demazure-Lusztig operator acting on the basis. @@ -979,7 +978,7 @@ def twisted_demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, conventi - ``weight`` -- an element `\lambda` of the weight lattice - ``i`` -- an element of the index set - ``q1``, ``q2`` -- two elements of the ground ring - - ``convention`` -- ``"antidominant"``, ``"bar"``, or ``"dominant"`` (default: ``"antidominant"``) + - ``convention`` -- ``'antidominant'``, ``'bar'``, or ``'dominant'`` (default: ``'antidominant'``) .. SEEALSO:: :meth:`twisted_demazure_lusztig_operators` @@ -992,16 +991,16 @@ def twisted_demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, conventi sage: KL = L.algebra(K) sage: Lambda = L.classical().fundamental_weights() sage: KL.twisted_demazure_lusztig_operator_on_basis( - ....: Lambda[1] + 2*Lambda[2], 1, q1, q2, convention="dominant") + ....: Lambda[1] + 2*Lambda[2], 1, q1, q2, convention='dominant') (-q2)*B[(2, 3, 0, 0)] sage: KL.twisted_demazure_lusztig_operator_on_basis( - ....: Lambda[1] + 2*Lambda[2], 2, q1, q2, convention="dominant") + ....: Lambda[1] + 2*Lambda[2], 2, q1, q2, convention='dominant') (-q1-q2)*B[(3, 1, 1, 0)] + (-q2)*B[(3, 0, 2, 0)] sage: KL.twisted_demazure_lusztig_operator_on_basis( - ....: Lambda[1] + 2*Lambda[2], 3, q1, q2, convention="dominant") + ....: Lambda[1] + 2*Lambda[2], 3, q1, q2, convention='dominant') q1*B[(3, 2, 0, 0)] sage: KL.twisted_demazure_lusztig_operator_on_basis( # needs sage.graphs - ....: Lambda[1]+2*Lambda[2], 0, q1, q2, convention="dominant") + ....: Lambda[1]+2*Lambda[2], 0, q1, q2, convention='dominant') ((q1*q2+q2^2)/q1)*B[(1, 2, 1, 1)] + ((q1*q2+q2^2)/q1)*B[(1, 2, 2, 0)] + q2^2/q1*B[(1, 2, 0, 2)] + ((q1^2+2*q1*q2+q2^2)/q1)*B[(2, 1, 1, 1)] + ((q1^2+2*q1*q2+q2^2)/q1)*B[(2, 1, 2, 0)] @@ -1017,19 +1016,19 @@ def twisted_demazure_lusztig_operator_on_basis(self, weight, i, q1, q2, conventi L = self.classical() return L.demazure_lusztig_operators(q1, q2, convention=convention)[i](L.monomial(weight)) - def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): + def twisted_demazure_lusztig_operators(self, q1, q2, convention='antidominant'): r""" Return the twisted Demazure-Lusztig operators acting on ``self``. INPUT: - ``q1``, ``q2`` -- two elements of the ground ring - - ``convention`` -- ``"antidominant"``, ``"bar"``, or ``"dominant"`` (default: ``"antidominant"``) + - ``convention`` -- ``'antidominant'``, ``'bar'``, or ``'dominant'`` (default: ``'antidominant'``) .. WARNING:: - the code is currently only tested for `q_1q_2=-1` - - only the ``"dominant"`` convention is functional for `i=0` + - only the ``'dominant'`` convention is functional for `i=0` For `T_1,\ldots,T_n`, these operators are the usual Demazure-Lusztig operators. On the other hand, the @@ -1040,7 +1039,7 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: K = QQ['q1,q2'].fraction_field() sage: q1, q2 = K.gens() sage: KL = L.algebra(K) - sage: T = KL.twisted_demazure_lusztig_operators(q1, q2, convention="dominant") + sage: T = KL.twisted_demazure_lusztig_operators(q1, q2, convention='dominant') sage: T._test_relations() TESTS: @@ -1052,7 +1051,7 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: K = QQ['q1,q2'].fraction_field() sage: q1,q2 = K.gens() sage: KL = L.algebra(K) - sage: T = KL.twisted_demazure_lusztig_operators(q1, q2, convention="dominant") + sage: T = KL.twisted_demazure_lusztig_operators(q1, q2, convention='dominant') sage: T._test_relations() sage: L0 = L.classical() sage: alpha = L0.simple_roots() @@ -1074,7 +1073,7 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: K = QQ['u'].fraction_field() sage: u = K.gen() sage: KL = L.algebra(K) - sage: T = KL.twisted_demazure_lusztig_operators(u, -~u, convention="dominant") + sage: T = KL.twisted_demazure_lusztig_operators(u, -~u, convention='dominant') sage: T._test_relations() sage: L0 = L.classical() sage: KL0 = L0.algebra(K) @@ -1107,7 +1106,7 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): ....: if cartan_type.rank() > 4: continue ....: if cartan_type.type() == 'BC': continue ....: KL = RootSystem(cartan_type).weight_lattice().algebra(K) - ....: T = KL.twisted_demazure_lusztig_operators(q1, q2, convention="dominant") + ....: T = KL.twisted_demazure_lusztig_operators(q1, q2, convention='dominant') ....: T._test_relations() .. TODO:: @@ -1119,7 +1118,7 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: cartan_type = CartanType(["BC",1,2]) sage: KL = RootSystem(cartan_type).weight_lattice().algebra(K) - sage: T = KL.twisted_demazure_lusztig_operators(q1,q2, convention="dominant") + sage: T = KL.twisted_demazure_lusztig_operators(q1,q2, convention='dominant') sage: T._test_relations() # needs sage.graphs Traceback (most recent call last): ... tester.assertTrue(Ti(Ti(x,i,-q2),i,-q1).is_zero()) ... @@ -1135,10 +1134,10 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): sage: q2 = -1 sage: KL = L.algebra(K) sage: L0 = L.classical() - sage: T = KL.demazure_lusztig_operators(q1,q2, convention="dominant") + sage: T = KL.demazure_lusztig_operators(q1,q2, convention='dominant') sage: def T0(*l0): return KL.q_project(T[0].on_basis()(L.embed_at_level(L0(l0), 1)), q) sage: T0_check_on_basis = KL.T0_check_on_basis(q1, q2, # needs sage.graphs - ....: convention="dominant") + ....: convention='dominant') sage: def T0c(*l0): return T0_check_on_basis(L0(l0)) sage: T0(0,0,1) # not double checked # needs sage.graphs @@ -1152,13 +1151,13 @@ def twisted_demazure_lusztig_operators(self, q1, q2, convention="antidominant"): T_on_basis, self.cartan_type().classical().dual().affine().dual(), q1, q2, - side="left") + side='left') class ElementMethods: def acted_upon(self, w): """ - Implements the action of ``w`` on ``self``. + Implement the action of ``w`` on ``self``. INPUT: diff --git a/src/sage/combinat/root_system/root_lattice_realizations.py b/src/sage/combinat/root_system/root_lattice_realizations.py index 435c2fcfc65..2eddb3bbb38 100644 --- a/src/sage/combinat/root_system/root_lattice_realizations.py +++ b/src/sage/combinat/root_system/root_lattice_realizations.py @@ -33,7 +33,7 @@ class RootLatticeRealizations(Category_over_base_ring): r""" - The category of root lattice realizations over a given base ring + The category of root lattice realizations over a given base ring. A *root lattice realization* `L` over a base ring `R` is a free module (or vector space if `R` is a field) endowed with an embedding @@ -309,7 +309,7 @@ def some_elements(self): def _test_root_lattice_realization(self, **options): """ - Run sanity checks on this root lattice realization + Run sanity checks on this root lattice realization. - embedding of the root lattice - embedding of the root space over the same base ring @@ -394,7 +394,6 @@ def highest_root(self): sage: RootSystem(['E',6]).weight_space().highest_root() # needs sage.graphs Lambda[2] - """ if not self.root_system.is_finite(): raise ValueError("The root system of %s is not of finite Cartan type" % self) @@ -477,7 +476,7 @@ def simple_roots(self): if not hasattr(self,"_simple_roots"): self._simple_roots = Family(self.index_set(), self.simple_root) # Should we use rename to set a nice name for this family? - # self._simple_roots.rename("alpha") + # self._simple_roots.rename('alpha') # This break some doctests return self._simple_roots @@ -740,7 +739,6 @@ def nonparabolic_positive_roots(self, index_set=None): sage: sorted(L.nonparabolic_positive_roots(())) # needs sage.graphs [alpha[1], alpha[1] + alpha[2], alpha[1] + alpha[2] + alpha[3], alpha[2], alpha[2] + alpha[3], alpha[3]] - """ if not self.cartan_type().is_finite(): raise NotImplementedError("Only implemented for " @@ -766,7 +764,6 @@ def nonparabolic_positive_root_sum(self, index_set=None): 0 sage: Q.nonparabolic_positive_root_sum(()) # needs sage.graphs 3*alpha[1] + 4*alpha[2] + 3*alpha[3] - """ return self.sum(self.nonparabolic_positive_roots(index_set)) @@ -920,7 +917,6 @@ def positive_roots_by_height(self, increasing=True): Traceback (most recent call last): ... NotImplementedError: Only implemented for finite Cartan type - """ if not self.cartan_type().is_finite(): @@ -999,7 +995,6 @@ def positive_roots_nonparabolic(self, index_set=None): .. WARNING:: This returns an error if the Cartan type is not finite. - """ if not self.cartan_type().is_finite(): raise NotImplementedError("Only implemented for finite Cartan type") @@ -1036,7 +1031,6 @@ def positive_roots_nonparabolic_sum(self, index_set=None): .. WARNING:: This returns an error if the Cartan type is not finite. - """ if not self.cartan_type().is_finite(): @@ -1049,13 +1043,16 @@ def root_poset(self, restricted=False, facade=False): r""" Return the (restricted) root poset associated to ``self``. - The elements are given by the positive roots (resp. non-simple, positive roots), and - `\alpha \leq \beta` iff `\beta - \alpha` is a non-negative linear combination of simple roots. + The elements are given by the positive roots (resp. non-simple, + positive roots), and `\alpha \leq \beta` iff `\beta - \alpha` is a + nonnegative linear combination of simple roots. INPUT: - - ``restricted`` -- (default: ``False``) if ``True``, only non-simple roots are considered. - - ``facade`` -- (default: ``False``) passes facade option to the poset generator. + - ``restricted`` -- boolean (default: ``False``); if ``True``, only + non-simple roots are considered. + - ``facade`` -- boolean (default: ``False``); passes facade option + to the poset generator EXAMPLES:: @@ -1146,7 +1143,7 @@ def generalized_nonnesting_partition_lattice(self, m, facade=False): INPUT: - - `m` -- integer + - ``m`` -- integer .. SEEALSO:: @@ -1227,7 +1224,6 @@ def negative_roots(self): [-2*Lambda[1] + Lambda[2], -Lambda[1] - Lambda[2], Lambda[1] - 2*Lambda[2]] Algorithm: negate the positive roots - """ if not self.cartan_type().is_finite(): raise ValueError("%s is not a finite Cartan type" % self.cartan_type()) @@ -1245,7 +1241,6 @@ def coroot_lattice(self): sage: RootSystem(['A',2]).root_lattice().coroot_lattice() Coroot lattice of the Root system of type ['A', 2] - """ return self.root_system.coroot_lattice() @@ -1265,13 +1260,12 @@ def coroot_space(self, base_ring=QQ): sage: RootSystem(['A',2]).root_lattice().coroot_space(QQ['q']) Coroot space over the Univariate Polynomial Ring in q over Rational Field of the Root system of type ['A', 2] - """ return self.root_system.coroot_space(base_ring=base_ring) def simple_coroot(self, i): """ - Returns the `i^{th}` simple coroot. + Return the `i`-th simple coroot. EXAMPLES:: @@ -1283,19 +1277,18 @@ def simple_coroot(self, i): @cached_method def simple_coroots(self): r""" - Returns the family `( \alpha^\vee_i)_{i\in I}` of the simple coroots. + Return the family `(\alpha^\vee_i)_{i\in I}` of the simple coroots. EXAMPLES:: sage: alphacheck = RootSystem(['A',3]).root_lattice().simple_coroots() sage: [alphacheck[i] for i in [1, 2, 3]] [alphacheck[1], alphacheck[2], alphacheck[3]] - """ if not hasattr(self,"cache_simple_coroots"): self.cache_simple_coroots = Family(self.index_set(), self.simple_coroot) # Should we use rename to set a nice name for this family? - # self.cache_simple_coroots.rename("alphacheck") + # self.cache_simple_coroots.rename('alphacheck') # break some doctests return self.cache_simple_coroots @@ -1327,7 +1320,6 @@ def alphacheck(self): sage: RootSystem(["A",3]).ambient_space().alphacheck() Finite family {1: (1, -1, 0, 0), 2: (0, 1, -1, 0), 3: (0, 0, 1, -1)} - """ if self.root_system.is_finite() and self.root_system.is_irreducible(): return Family(self.index_set(), self.simple_coroot, @@ -1340,7 +1332,7 @@ def cohighest_root(self): """ Return the associated coroot of the highest root. - .. note:: this is usually not the highest coroot. + .. NOTE:: this is usually not the highest coroot. EXAMPLES:: @@ -1556,7 +1548,7 @@ def simple_reflections(self): """ res = self.alpha().zip(self.reflection, self.alphacheck()) # Should we use rename to set a nice name for this family? - res.rename("simple reflections") + res.rename('simple reflections') return res s = simple_reflections @@ -1651,7 +1643,7 @@ def simple_projections(self, to_negative=True): raise NotImplementedError("only implemented when 'to_negative' is True") res = self.alpha().zip(self.projection, self.alphacheck()) # Should this use rename to set a nice name for this family? - res.rename("pi") + res.rename('pi') return res ########################################################################## @@ -1668,7 +1660,6 @@ def weyl_group(self, prefix=None): Weyl Group of type ['F', 4] (as a matrix group acting on the ambient space) sage: RootSystem(['F',4]).root_space().weyl_group() # needs sage.libs.gap Weyl Group of type ['F', 4] (as a matrix group acting on the root space) - """ from sage.combinat.root_system.weyl_group import WeylGroup return WeylGroup(self, prefix=prefix) @@ -1963,9 +1954,9 @@ def _classical_alpha_0(self): # Root system plots def plot(self, - roots="simple", + roots='simple', coroots=False, - reflection_hyperplanes="simple", + reflection_hyperplanes='simple', fundamental_weights=None, fundamental_chamber=None, alcoves=None, @@ -1977,25 +1968,25 @@ def plot(self, INPUT: - - ``roots`` -- which roots to display, if any. + - ``roots`` -- which roots to display, if any Can be one of the following: - * ``"simple"`` -- The simple roots (the default) - * ``"classical"`` -- Not yet implemented - * ``"all"`` -- Only works in the finite case + * ``'simple'`` -- the simple roots (the default) + * ``'classical'`` -- not yet implemented + * ``'all'`` -- only works in the finite case * A list or tuple of roots * ``False`` - - ``coroots`` -- which coroots to display, if any. + - ``coroots`` -- which coroots to display, if any Can be one of the following: - * ``"simple"`` -- The simple coroots (the default) - * ``"classical"`` -- Not yet implemented - * ``"all"`` -- Only works in the finite case + * ``'simple'`` -- the simple coroots (the default) + * ``'classical'`` -- not yet implemented + * ``'all'`` -- only works in the finite case * A list or tuple of coroots * ``False`` - - ``fundamental_weights`` -- a boolean or ``None`` (default: ``None``) + - ``fundamental_weights`` -- boolean or ``None`` (default: ``None``) whether to display the fundamental weights. If ``None``, the fundamental weights are drawn if available. @@ -2003,9 +1994,9 @@ def plot(self, hyperplanes to display, if any. Can be one of the following: - * ``"simple"`` -- The simple roots - * ``"classical"`` -- Not yet implemented - * ``"all"`` -- Only works in the finite case + * ``'simple'`` -- the simple roots + * ``'classical'`` -- not yet implemented + * ``'all'`` -- only works in the finite case * A list or tuple of roots * ``False`` (the default) @@ -2014,7 +2005,7 @@ def plot(self, * A boolean -- Set to ``True`` to draw the fundamental chamber - * ``"classical"`` -- Draw the classical fundamental chamber + * ``'classical'`` -- draw the classical fundamental chamber * ``None`` -- (the default) The fundamental chamber is drawn except in the root lattice where this is not yet implemented. For affine types the classical @@ -2022,7 +2013,7 @@ def plot(self, - ``alcoves`` -- one of the following (default: ``True``): - * A boolean -- Whether to display the alcoves + * A boolean -- whether to display the alcoves * A list of alcoves -- The alcoves to be drawn. Each alcove is specified by the coordinates of its center in the root lattice (affine type only). Otherwise the alcoves that intersect the @@ -2030,10 +2021,10 @@ def plot(self, - ``alcove_labels`` -- one of the following (default: ``False``): - * A boolean -- Whether to display the elements of the Weyl group + * A boolean -- whether to display the elements of the Weyl group indexing the alcoves. This currently requires to also set the ``alcoves`` option. - * A number `l` -- The label is drawn at level `l` (affine type + * A number `l` -- the label is drawn at level `l` (affine type only), which only makes sense if ``affine`` is ``False``. - ``bounding_box`` -- a rational number or a list of pairs @@ -2056,10 +2047,10 @@ def plot(self, - ``projection`` -- one of the following (default: ``True``): - * ``True`` -- The default projection for the root + * ``True`` -- the default projection for the root lattice realization is used. - * ``False`` -- No projection is used. - * ``barycentric`` -- A barycentric projection is used. + * ``False`` -- no projection is used. + * ``barycentric`` -- a barycentric projection is used. * A function -- If a function is specified, it should implement a linear (or affine) map taking as input an element of this root lattice realization and returning its @@ -2067,15 +2058,15 @@ def plot(self, rational coordinates. - ``color`` -- a function mapping vertices of the Dynkin - diagram to colors (default: ``"black"`` for 0, - ``"blue"`` for 1, ``"red"`` for 2, ``"green"`` for 3) + diagram to colors (default: ``'black'`` for 0, + ``'blue'`` for 1, ``'red'`` for 2, ``'green'`` for 3) This is used to set the color for the simple roots, fundamental weights, reflection hyperplanes, alcove facets, etc. If the color is ``None``, the object is not drawn. - - ``labels`` -- a boolean (default: ``True``) + - ``labels`` -- boolean (default: ``True``) whether to display labels on the simple roots, fundamental weights, etc. @@ -2194,9 +2185,7 @@ def _plot_projection_barycentric_matrix(self): A rational approximation of the matrix for the barycentric projection. - OUTPUT: - - a matrix with rational coefficients whose column sum is zero + OUTPUT: a matrix with rational coefficients whose column sum is zero .. SEEALSO:: @@ -2223,7 +2212,6 @@ def _plot_projection_barycentric_matrix(self): [ 1/3 1/3 1/3 -1] sage: sum(m.columns()) (0, 0, 0) - """ from sage.symbolic.constants import pi m = matrix(QQ, barycentric_projection_matrix(self.dimension()-1, angle=2*pi/3).n(20)) @@ -2264,7 +2252,7 @@ def _plot_projection_barycentric(self, x): """ return self._plot_projection_barycentric_matrix()*vector(x) - def plot_roots(self, collection="simple", **options): + def plot_roots(self, collection='simple', **options): r""" Plot the (simple/classical) roots of this root lattice. @@ -2273,11 +2261,11 @@ def plot_roots(self, collection="simple", **options): - ``collection`` -- which roots to display can be one of the following: - * ``"simple"`` (the default) - * ``"classical"`` - * ``"all"`` + * ``'simple'`` (the default) + * ``'classical'`` + * ``'all'`` - - ``**options`` -- Plotting options + - ``**options`` -- plotting options .. SEEALSO:: @@ -2349,20 +2337,20 @@ def plot_roots(self, collection="simple", **options): roots = Family(roots, self) return plot_options.family_of_vectors(roots) - def plot_coroots(self, collection="simple", **options): + def plot_coroots(self, collection='simple', **options): r""" Plot the (simple/classical) coroots of this root lattice. INPUT: - - ``collection`` -- which coroots to display. + - ``collection`` -- which coroots to display Can be one of the following: - * ``"simple"`` (the default) - * ``"classical"`` - * ``"all"`` + * ``'simple'`` (the default) + * ``'classical'`` + * ``'all'`` - - ``**options`` -- Plotting options + - ``**options`` -- plotting options .. SEEALSO:: @@ -2412,7 +2400,7 @@ def plot_fundamental_weights(self, **options): INPUT: - - ``**options`` -- Plotting options + - ``**options`` -- plotting options .. SEEALSO:: @@ -2452,20 +2440,20 @@ def plot_fundamental_weights(self, **options): self.fundamental_weights()))) return plot_options.family_of_vectors(fundamental_weights) - def plot_reflection_hyperplanes(self, collection="simple", **options): + def plot_reflection_hyperplanes(self, collection='simple', **options): r""" Plot the simple reflection hyperplanes. INPUT: - - ``collection`` -- which reflection hyperplanes to display. + - ``collection`` -- which reflection hyperplanes to display Can be one of the following: - * ``"simple"`` (the default) - * ``"classical"`` - * ``"all"`` + * ``'simple'`` (the default) + * ``'classical'`` + * ``'all'`` - - ``**options`` -- Plotting options + - ``**options`` -- plotting options .. SEEALSO:: @@ -2601,15 +2589,15 @@ def plot_hedron(self, **options): for vertex in self.rho().orbit()] return Polyhedron(vertices=vertices).plot() - def plot_fundamental_chamber(self, style="normal", **options): + def plot_fundamental_chamber(self, style='normal', **options): r""" Plot the (classical) fundamental chamber. INPUT: - - ``style`` -- ``"normal"`` or ``"classical"`` (default: ``"normal"``) + - ``style`` -- ``'normal'`` or ``'classical'`` (default: ``'normal'``) - - ``**options`` -- Plotting options + - ``**options`` -- plotting options .. SEEALSO:: @@ -2648,7 +2636,7 @@ def plot_fundamental_chamber(self, style="normal", **options): sage: print(L.plot_fundamental_chamber().description()) # needs sage.plot Polygon defined by 3 points: [(0.5, 0.5), (1.0, 0.0), (0.0, 0.0)] - sage: print(L.plot_fundamental_chamber(style="classical").description()) # needs sage.plot + sage: print(L.plot_fundamental_chamber(style='classical').description()) # needs sage.plot Polygon defined by 3 points: [(0.0, 0.0), (3.0, 3.0), (3.0, 0.0)] """ plot_options = self.plot_parse_options(**options) @@ -2666,7 +2654,7 @@ def plot_fundamental_chamber(self, style="normal", **options): lines = [] return plot_options.cone(rays=[Lambda[i] for i in I], lines=lines, - color="lightgrey", + color='lightgrey', alpha=.3) def plot_alcoves(self, alcoves=True, alcove_labels=False, wireframe=False, **options): @@ -2675,12 +2663,12 @@ def plot_alcoves(self, alcoves=True, alcove_labels=False, wireframe=False, **opt INPUT: - - ``alcoves`` -- a list of alcoves or ``True`` (default: ``True``) + - ``alcoves`` -- list of alcoves or ``True`` (default: ``True``) - - ``alcove_labels`` -- a boolean or a number specifying at + - ``alcove_labels`` -- boolean or a number specifying at which level to put the label (default: ``False``) - - ``**options`` -- Plotting options + - ``**options`` -- plotting options .. SEEALSO:: @@ -2778,13 +2766,13 @@ def alcove_label(w): alcoves = list(alcoves) if alcoves is True or (alcoves and W.is_parent_of(alcoves[0])): if alcoves is True: - alcoves = W.weak_order_ideal(alcove_in_bounding_box, side="right") + alcoves = W.weak_order_ideal(alcove_in_bounding_box, side='right') # We assume that the fundamental alcove lies within # the bounding box, and explore the alcoves # intersecting the bounding box by going up right # order (i.e. going away from the fundamental alcove) for w in alcoves: - for i in w.descents(side="right", positive=True): + for i in w.descents(side='right', positive=True): G += alcove_facet(w, i) if alcove_labels is not False: G += alcove_label(w) @@ -2803,7 +2791,7 @@ def alcove_label(w): shift = sum(x*v for x,v in zip(alcove, translation_vectors)) shift = W.from_morphism(shift.translation) for w in W0: - for i in w.descents(side="right", positive=True): + for i in w.descents(side='right', positive=True): G += alcove_facet(shift * w, i) if alcove_labels: G += alcove_label(w) @@ -2874,7 +2862,7 @@ def plot_bounding_box(self, **options): INPUT: - - ``**options`` -- Plotting options + - ``**options`` -- plotting options This is mostly for testing purposes. @@ -2896,16 +2884,16 @@ def plot_bounding_box(self, **options): [Polygon defined by 4 points] """ plot_options = self.plot_parse_options(**options) - return plot_options.bounding_box.plot(color="gray", alpha=0.5, wireframe=False) + return plot_options.bounding_box.plot(color='gray', alpha=0.5, wireframe=False) - def plot_alcove_walk(self, word, start=None, foldings=None, color="orange", **options): + def plot_alcove_walk(self, word, start=None, foldings=None, color='orange', **options): r""" Plot an alcove walk. INPUT: - - ``word`` -- a list of elements of the index set - - ``foldings`` -- a list of booleans or ``None`` (default: ``None``) + - ``word`` -- list of elements of the index set + - ``foldings`` -- list of booleans or ``None`` (default: ``None``) - ``start`` -- an element of this space (default: ``None`` for `\rho`) - ``**options`` -- plotting options @@ -2929,7 +2917,7 @@ def plot_alcove_walk(self, word, start=None, foldings=None, color="orange", **op The same plot with another alcove walk:: sage: w2 = [2,1,2,0,2,0,2,1,2,0,1,2,1,2,1,0,1,2,0,2,0,1,2,0,2] - sage: p += L.plot_alcove_walk(w2, color="orange") # long time, needs sage.plot sage.symbolic + sage: p += L.plot_alcove_walk(w2, color='orange') # long time, needs sage.plot sage.symbolic And another with some foldings:: @@ -2937,7 +2925,7 @@ def plot_alcove_walk(self, word, start=None, foldings=None, color="orange", **op sage: pic += L.plot_alcove_walk([0,1,2,0,2,0,1,2,0,1], # long time (3s), needs sage.plot sage.symbolic ....: foldings=[False, False, True, False, False, ....: False, True, False, True, False], - ....: color="green"); pic + ....: color='green'); pic Graphics object consisting of 155 graphics primitives TESTS:: @@ -2946,7 +2934,7 @@ def plot_alcove_walk(self, word, start=None, foldings=None, color="orange", **op sage: p = L.plot_alcove_walk([0,1,2,0,2,0,1,2,0,1], # needs sage.plot sage.symbolic ....: foldings=[False, False, True, False, False, ....: False, True, False, True, False], - ....: color="green", + ....: color='green', ....: start=L.rho()) sage: print(p.description()) # needs sage.plot sage.symbolic Line defined by 2 points: [(-1.0, 8.0), (-1.5, 9.0)] @@ -3024,7 +3012,7 @@ def plot_ls_paths(self, paths, plot_labels=None, colored_labels=True, **options) - ``plot_labels`` -- (default: ``None``) the distance to plot the LS labels from the endpoint of the path; set to ``None`` to not display the labels - - ``colored_labels`` -- (default: ``True``) if ``True``, then + - ``colored_labels`` -- boolean (default: ``True``); if ``True``, then color the labels the same color as the LS path - ``**options`` -- plotting options @@ -3084,7 +3072,7 @@ def plot_mv_polytope(self, mv_polytope, mark_endpoints=True, INPUT: - ``mv_polytope`` -- an MV polytope - - ``mark_endpoints`` -- (default: ``True``) mark the endpoints + - ``mark_endpoints`` -- boolean (default: ``True``); mark the endpoints of the MV polytope - ``circle_size`` -- (default: 0.06) the size of the circles - ``circle_thickness`` -- (default: 1.6) the thinkness of the @@ -3157,7 +3145,7 @@ def plot_crystal(self, crystal, INPUT: - ``crystal`` -- the finite crystal to plot - - ``plot_labels`` -- (default: ``True``) can be one of the + - ``plot_labels`` -- boolean (default: ``True``); can be one of the following: * ``True`` -- use the latex labels @@ -3167,7 +3155,7 @@ def plot_crystal(self, crystal, - ``label_color`` -- (default: ``'black'``) the color of the labels - - ``edge_labels`` -- (default: ``False``) if ``True``, then draw + - ``edge_labels`` -- boolean (default: ``False``); if ``True``, then draw in the edge label - ``circle_size`` -- (default: 0.06) the size of the circles - ``circle_thickness`` -- (default: 1.6) the thinkness of the @@ -3292,7 +3280,6 @@ def dual_type_cospace(self): sage: CartanType(['F',4]).root_system().coweight_lattice().dual_type_cospace() Weight lattice of the Root system of type ['F', 4] relabelled by {1: 4, 2: 3, 3: 2, 4: 1} - """ from .root_space import RootSpace from .weight_space import WeightSpace @@ -3329,7 +3316,6 @@ def to_ambient_space_morphism(self): Generic morphism: From: Weight lattice of the Root system of type ['B', 2] To: Ambient space of the Root system of type ['B', 2] - """ ########################################################################## @@ -3478,7 +3464,7 @@ def simple_reflection(self, i): def simple_reflections(self): """ - The images of ``self`` by all the simple reflections + The images of ``self`` by all the simple reflections. EXAMPLES:: @@ -3693,7 +3679,7 @@ def has_descent(self, i, positive=False): def first_descent(self, index_set=None, positive=False): """ - Return the first descent of pt + Return the first descent of pt. One can use the ``index_set`` option to restrict to the parabolic subgroup indexed by ``index_set``. @@ -3719,7 +3705,7 @@ def first_descent(self, index_set=None, positive=False): def descents(self, index_set=None, positive=False): """ - Return the descents of pt + Return the descents of pt. EXAMPLES:: @@ -3845,7 +3831,6 @@ def reduced_word(self, index_set=None, positive=True): [2, 3, 4, 5] sage: alpha[1].reduced_word([1,2]) # needs sage.graphs [2] - """ return self.to_dominant_chamber(index_set=index_set,positive=positive,reduced_word=True)[1] @@ -4139,7 +4124,7 @@ def to_simple_root(self, reduced_word=False): INPUT: - ``self`` -- a positive root - - ``reduced_word`` -- a boolean (default: ``False``) + - ``reduced_word`` -- boolean (default: ``False``) OUTPUT: @@ -4230,7 +4215,6 @@ def associated_reflection(self): (1, 2, 3, 2, 1) sage: C3_rl.simple_root(2).associated_reflection() # needs sage.graphs (2,) - """ i, reduced_word = self.to_simple_root(reduced_word=True) return reduced_word + (i,) + tuple(reversed(reduced_word)) @@ -4241,8 +4225,8 @@ def translation(self, x): INPUT: - - ``self`` -- an element `t` at level `0` - - ``x`` -- an element of the same space + - ``self`` -- an element `t` at level `0` + - ``x`` -- an element of the same space EXAMPLES:: @@ -4290,7 +4274,7 @@ def weyl_action(self, element, inverse=False): of the same Cartan type, or a tuple or a list (such as a reduced word) of elements from the index set - - ``inverse`` -- a boolean (default: ``False``); whether to + - ``inverse`` -- boolean (default: ``False``); whether to act by the inverse element EXAMPLES:: @@ -4322,7 +4306,7 @@ def weyl_action(self, element, inverse=False): action of a corresponding reduced word):: sage: # needs sage.libs.gap - sage: W = WeylGroup(['A',3], prefix="s") + sage: W = WeylGroup(['A',3], prefix='s') sage: w = W.from_reduced_word([1, 2]) sage: wl.weyl_group() == W False @@ -4376,7 +4360,6 @@ def weyl_stabilizer(self, index_set=None): [3, 4] sage: mu.weyl_stabilizer(index_set = [1,2,3]) [3] - """ if index_set is None: index_set = self.parent().cartan_type().index_set() @@ -4402,7 +4385,7 @@ def dot_action(self, w, inverse=False): the same Cartan type, or a tuple or a list (such as a reduced word) of elements from the index set - - ``inverse`` -- a boolean (default: ``False``); whether + - ``inverse`` -- boolean (default: ``False``); whether to act by the inverse element EXAMPLES:: @@ -4438,7 +4421,7 @@ def is_parabolic_root(self, index_set): INPUT: - - ``index_set`` -- the Dynkin node set of the parabolic subsystem. + - ``index_set`` -- the Dynkin node set of the parabolic subsystem .. TODO:: This implementation is only valid in the root or weight lattice @@ -4451,7 +4434,6 @@ def is_parabolic_root(self, index_set): True sage: alpha.is_parabolic_root([2]) False - """ for i in self.support(): if i not in index_set: @@ -4532,7 +4514,6 @@ def to_dual_type_cospace(self): 2*Lambdacheck[1] + 2*Lambdacheck[2] + 3*Lambdacheck[3] sage: w.parent() Coweight lattice of the Root system of type ['B', 3] - """ return self.parent().dual_type_cospace().from_vector(self.to_vector()) @@ -4555,7 +4536,6 @@ def to_classical(self): 2*e[0] + 2*e[1] + 3*e[2] sage: v.to_classical() # needs sage.graphs (2, 2, 3, 0) - """ return self.parent().classical()(self) @@ -4583,7 +4563,6 @@ def to_ambient(self): 2*alphacheck[1] + 2*alphacheck[2] + 3*alphacheck[3] sage: alphavee.to_ambient() (2, 0, 1, -3) - """ def is_long_root(self): diff --git a/src/sage/combinat/root_system/root_space.py b/src/sage/combinat/root_system/root_space.py index f8783a78d43..96a68eacc0f 100644 --- a/src/sage/combinat/root_system/root_space.py +++ b/src/sage/combinat/root_system/root_space.py @@ -16,12 +16,12 @@ class RootSpace(CombinatorialFreeModule): r""" - The root space of a root system over a given base ring + The root space of a root system over a given base ring. INPUT: - ``root_system`` -- a root system - - ``base_ring``: a ring `R` + - ``base_ring`` -- a ring `R` The *root space* (or lattice if ``base_ring`` is `\ZZ`) of a root system is the formal free module `\bigoplus_i R \alpha_i` @@ -47,7 +47,6 @@ class RootSpace(CombinatorialFreeModule): alpha[1] sage: latex(r.simple_root(1)) \alpha_{1} - """ def __init__(self, root_system, base_ring): @@ -56,7 +55,6 @@ def __init__(self, root_system, base_ring): sage: P = RootSystem(['A',4]).root_space() sage: s = P.simple_reflections() - """ from sage.categories.morphism import SetMorphism from sage.categories.homset import Hom @@ -87,7 +85,6 @@ def _repr_(self): Coroot lattice of the Root system of type ['A', 4] sage: RootSystem(['B',4]).coroot_space() Coroot space over the Rational Field of the Root system of type ['B', 4] - """ return self._name_string() @@ -105,7 +102,8 @@ def _name_string(self, capitalize=True, base_ring=True, type=True): @cached_method def to_coroot_space_morphism(self): """ - Returns the ``nu`` map to the coroot space over the same base ring, using the symmetrizer of the Cartan matrix + Return the ``nu`` map to the coroot space over the same base ring, + using the symmetrizer of the Cartan matrix. It does not map the root lattice to the coroot lattice, but has the property that any root is mapped to some scalar @@ -168,7 +166,7 @@ def _to_root_lattice(self, x): ... ValueError: alpha[1] + alpha[2] + 3/2*alpha[3] does not have integral coefficients - .. note:: + .. NOTE:: For internal use only; instead use a conversion:: @@ -217,7 +215,6 @@ def to_ambient_space_morphism(self): Generic morphism: From: Root lattice of the Root system of type ['A', 2] To: Ambient space of the Root system of type ['A', 2] - """ if self.root_system.dual_side: L = self.cartan_type().dual().root_system().ambient_space() @@ -273,7 +270,7 @@ def scalar(self, lambdacheck): def is_positive_root(self): """ - Checks whether an element in the root space lies in the + Check whether an element in the root space lies in the nonnegative cone spanned by the simple roots. EXAMPLES:: @@ -292,7 +289,7 @@ def is_positive_root(self): @cached_in_parent_method def associated_coroot(self): r""" - Returns the coroot associated to this root + Return the coroot associated to this root. OUTPUT: @@ -331,7 +328,7 @@ def quantum_root(self): INPUT: - - ``self`` -- an element of the nonnegative integer span of simple roots. + - ``self`` -- an element of the nonnegative integer span of simple roots A root `\alpha` is a quantum root if `\ell(s_\alpha) = \langle 2 \rho, \alpha^\vee \rangle - 1` where `\ell` is the length function, `s_\alpha` is the reflection across the hyperplane @@ -362,7 +359,7 @@ def max_coroot_le(self): INPUT: - - ``self`` -- an element of the nonnegative integer span of simple roots. + - ``self`` -- an element of the nonnegative integer span of simple roots Returns None for the zero element. @@ -419,7 +416,7 @@ def max_quantum_element(self): INPUT: - - ``self`` -- an element of the nonnegative integer span of simple roots. + - ``self`` -- an element of the nonnegative integer span of simple roots Really ``self`` is an element of a coroot lattice. @@ -437,7 +434,6 @@ def max_quantum_element(self): [1, 2, 1] sage: Qvee.from_vector(vector([0,2])).max_quantum_element() [2] - """ Qvee = self.parent() word = [] @@ -462,7 +458,6 @@ def to_ambient(self): 2*alphacheck[1] + 2*alphacheck[2] sage: alphavee.to_ambient() (2, 2) - """ return self.parent().to_ambient_space_morphism()(self) diff --git a/src/sage/combinat/root_system/root_system.py b/src/sage/combinat/root_system/root_system.py index d75aeba1505..ac70314eae1 100644 --- a/src/sage/combinat/root_system/root_system.py +++ b/src/sage/combinat/root_system/root_system.py @@ -301,7 +301,7 @@ class RootSystem(UniqueRepresentation, SageObject): @staticmethod def __classcall__(cls, cartan_type, as_dual_of=None): """ - Straighten arguments to enable unique representation + Straighten arguments to enable unique representation. .. SEEALSO:: :class:`UniqueRepresentation` @@ -341,7 +341,7 @@ def __init__(self, cartan_type, as_dual_of=None): def _test_root_lattice_realizations(self, **options): """ - Runs tests on all the root lattice realizations of this root + Run tests on all the root lattice realizations of this root system. EXAMPLES:: @@ -483,12 +483,14 @@ def root_poset(self, restricted=False, facade=False): Return the (restricted) root poset associated to ``self``. The elements are given by the positive roots (resp. non-simple, positive roots), and - `\alpha \leq \beta` iff `\beta - \alpha` is a non-negative linear combination of simple roots. + `\alpha \leq \beta` iff `\beta - \alpha` is a nonnegative linear combination of simple roots. INPUT: - - ``restricted`` -- (default: ``False``) if True, only non-simple roots are considered. - - ``facade`` -- (default: ``False``) passes facade option to the poset generator. + - ``restricted`` -- boolean (default: ``False``); if ``True``, only + non-simple roots are considered + - ``facade`` -- boolean (default: ``False``); passes facade option to + the poset generator EXAMPLES:: @@ -558,7 +560,7 @@ def weight_lattice(self, extended=False): @cached_method def weight_space(self, base_ring=QQ, extended=False): """ - Returns the weight space associated to ``self``. + Return the weight space associated to ``self``. .. SEEALSO:: @@ -792,11 +794,9 @@ def WeylDim(ct, coeffs): INPUT: + - ``ct`` -- a Cartan type - - ``ct`` -- a Cartan type - - - ``coeffs`` -- a list of nonnegative integers - + - ``coeffs`` -- list of nonnegative integers The length of the list must equal the rank type[1]. A dominant weight hwv is constructed by summing the fundamental weights with diff --git a/src/sage/combinat/root_system/type_A.py b/src/sage/combinat/root_system/type_A.py index 48d1474c1f4..26c6154a5bd 100644 --- a/src/sage/combinat/root_system/type_A.py +++ b/src/sage/combinat/root_system/type_A.py @@ -48,7 +48,7 @@ class AmbientSpace(ambient_space.AmbientSpace): @classmethod def smallest_base_ring(cls, cartan_type=None): """ - Returns the smallest base ring the ambient space can be defined upon + Return the smallest base ring the ambient space can be defined upon. .. SEEALSO:: :meth:`~sage.combinat.root_system.ambient_space.AmbientSpace.smallest_base_ring` @@ -123,7 +123,6 @@ def positive_roots(self): (1, 0, 0, -1), (0, 1, 0, -1), (0, 0, 1, -1)] - """ res = [] for j in range(self.n): @@ -148,16 +147,15 @@ def fundamental_weight(self, i): sage: e = RootSystem(['A',3]).ambient_lattice() sage: e.fundamental_weights() Finite family {1: (1, 0, 0, 0), 2: (1, 1, 0, 0), 3: (1, 1, 1, 0)} - """ return self.sum(self.monomial(j) for j in range(i)) def det(self, k=1): """ - returns the vector (1, ... ,1) which in the ['A',r] + Return the vector (1, ... ,1) which in the ['A',r] weight lattice, interpreted as a weight of GL(r+1,CC) is the determinant. If the optional parameter k is - given, returns (k, ... ,k), the k-th power of the + given, returns (k, ... ,k), the `k`-th power of the determinant. EXAMPLES:: @@ -176,7 +174,7 @@ def det(self, k=1): class CartanType(CartanType_standard_finite, CartanType_simply_laced, CartanType_simple): """ - Cartan Type `A_n` + Cartan Type `A_n`. .. SEEALSO:: :func:`~sage.combinat.root_systems.cartan_type.CartanType` """ @@ -250,7 +248,7 @@ def dual_coxeter_number(self): def dynkin_diagram(self): """ - Returns the Dynkin diagram of type A. + Return the Dynkin diagram of type A. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_A_affine.py b/src/sage/combinat/root_system/type_A_affine.py index 57ed18afd01..cf642231967 100644 --- a/src/sage/combinat/root_system/type_A_affine.py +++ b/src/sage/combinat/root_system/type_A_affine.py @@ -68,7 +68,7 @@ def _latex_(self): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for affine type A. + Return the extended Dynkin diagram for affine type A. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_A_infinity.py b/src/sage/combinat/root_system/type_A_infinity.py index 9e0f4711ccd..5c42db7e176 100644 --- a/src/sage/combinat/root_system/type_A_infinity.py +++ b/src/sage/combinat/root_system/type_A_infinity.py @@ -98,7 +98,6 @@ def ascii_art(self, label=None, node=None): sage: print(CartanType(['A', NN]).ascii_art()) O---O---O---O---O---O---O---.. 0 1 2 3 4 5 6 - """ if label is None: label = lambda i: i diff --git a/src/sage/combinat/root_system/type_B.py b/src/sage/combinat/root_system/type_B.py index 8e9cb6e75a5..9794d00794c 100644 --- a/src/sage/combinat/root_system/type_B.py +++ b/src/sage/combinat/root_system/type_B.py @@ -32,7 +32,6 @@ def root(self, i, j): sage: e = RootSystem(['B',3]).ambient_space() sage: e.root(0,1) (1, -1, 0) - """ return self.monomial(i) - self.monomial(j) @@ -98,7 +97,6 @@ def positive_roots(self): (1, 0, 0), (0, 1, 0), (0, 0, 1)] - """ res = [] for i in range(self.n-1): @@ -218,7 +216,7 @@ def dual(self): def dynkin_diagram(self): """ - Returns a Dynkin diagram for type B. + Return a Dynkin diagram for type B. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_BC_affine.py b/src/sage/combinat/root_system/type_BC_affine.py index 740dfa2e5f3..6bf8cc43697 100644 --- a/src/sage/combinat/root_system/type_BC_affine.py +++ b/src/sage/combinat/root_system/type_BC_affine.py @@ -70,7 +70,7 @@ def __init__(self, n): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for affine type BC. + Return the extended Dynkin diagram for affine type BC. EXAMPLES:: @@ -103,7 +103,6 @@ def dynkin_diagram(self): BC1~ sage: c.edges(sort=True) # needs sage.graphs [(0, 1, 1), (1, 0, 4)] - """ from .dynkin_diagram import DynkinDiagram_class n = self.n @@ -243,7 +242,7 @@ def ascii_art(self, label=None, node=None): def classical(self): """ - Returns the classical Cartan type associated with self + Return the classical Cartan type associated with ``self``. sage: CartanType(["BC", 3, 2]).classical() ['C', 3] diff --git a/src/sage/combinat/root_system/type_B_affine.py b/src/sage/combinat/root_system/type_B_affine.py index 047144f02d6..fd074cd2e8c 100644 --- a/src/sage/combinat/root_system/type_B_affine.py +++ b/src/sage/combinat/root_system/type_B_affine.py @@ -76,7 +76,6 @@ def dynkin_diagram(self): B1~ sage: b.edges(sort=True) [(0, 1, 2), (1, 0, 2)] - """ from . import cartan_type n = self.n diff --git a/src/sage/combinat/root_system/type_C.py b/src/sage/combinat/root_system/type_C.py index 8c7ebce3359..ff0288d5780 100644 --- a/src/sage/combinat/root_system/type_C.py +++ b/src/sage/combinat/root_system/type_C.py @@ -212,7 +212,7 @@ def dual(self): def dynkin_diagram(self): """ - Returns a Dynkin diagram for type C. + Return a Dynkin diagram for type C. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_C_affine.py b/src/sage/combinat/root_system/type_C_affine.py index adaf5c77562..c26e03f1b10 100644 --- a/src/sage/combinat/root_system/type_C_affine.py +++ b/src/sage/combinat/root_system/type_C_affine.py @@ -50,7 +50,7 @@ def __init__(self, n): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for affine type C. + Return the extended Dynkin diagram for affine type C. EXAMPLES:: @@ -60,7 +60,6 @@ def dynkin_diagram(self): C3~ sage: c.edges(sort=True) # needs sage.graphs [(0, 1, 2), (1, 0, 1), (1, 2, 1), (2, 1, 1), (2, 3, 1), (3, 2, 2)] - """ n = self.n if n == 1: diff --git a/src/sage/combinat/root_system/type_D.py b/src/sage/combinat/root_system/type_D.py index 5f1469e48a8..7d7988c8891 100644 --- a/src/sage/combinat/root_system/type_D.py +++ b/src/sage/combinat/root_system/type_D.py @@ -182,7 +182,7 @@ def _latex_(self): def is_atomic(self): """ - Implements :meth:`CartanType_abstract.is_atomic` + Implement :meth:`CartanType_abstract.is_atomic`. `D_2` is atomic, like all `D_n`, despite being non irreducible. @@ -220,7 +220,7 @@ def dual_coxeter_number(self): @cached_method def dynkin_diagram(self): """ - Returns a Dynkin diagram for type D. + Return a Dynkin diagram for type D. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_D_affine.py b/src/sage/combinat/root_system/type_D_affine.py index f77204e4a01..59748fb2ff6 100644 --- a/src/sage/combinat/root_system/type_D_affine.py +++ b/src/sage/combinat/root_system/type_D_affine.py @@ -50,7 +50,7 @@ def __init__(self, n): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for affine type D. + Return the extended Dynkin diagram for affine type D. EXAMPLES:: @@ -95,7 +95,6 @@ def dynkin_diagram(self): sage: d.edges(sort=True) # needs sage.graphs [(0, 2, 1), (0, 3, 1), (1, 2, 1), (1, 3, 1), (2, 0, 1), (2, 1, 1), (3, 0, 1), (3, 1, 1)] - """ from .dynkin_diagram import DynkinDiagram_class n = self.n diff --git a/src/sage/combinat/root_system/type_E.py b/src/sage/combinat/root_system/type_E.py index 22e81d52b34..5ac0041d5ca 100644 --- a/src/sage/combinat/root_system/type_E.py +++ b/src/sage/combinat/root_system/type_E.py @@ -374,7 +374,6 @@ def positive_roots(self): (1/2, 1/2, 1/2, 1/2, 1/2, 1/2, -1/2, -1/2)] sage: e.rho() (0, 1, 2, 3, 4, 5, 6, 23) - """ v = ZZ(1)/ZZ(2) # Note that @@ -525,7 +524,7 @@ def dual_coxeter_number(self): def dynkin_diagram(self): """ - Returns a Dynkin diagram for type E. + Return a Dynkin diagram for type E. EXAMPLES:: @@ -562,7 +561,6 @@ def dynkin_diagram(self): [(1, 3, 1), (2, 4, 1), (3, 1, 1), (3, 4, 1), (4, 2, 1), (4, 3, 1), (4, 5, 1), (5, 4, 1), (5, 6, 1), (6, 5, 1), (6, 7, 1), (7, 6, 1), (7, 8, 1), (8, 7, 1)] - """ from .dynkin_diagram import DynkinDiagram_class g = DynkinDiagram_class(self) diff --git a/src/sage/combinat/root_system/type_E_affine.py b/src/sage/combinat/root_system/type_E_affine.py index 3268d0603e5..a4800974566 100644 --- a/src/sage/combinat/root_system/type_E_affine.py +++ b/src/sage/combinat/root_system/type_E_affine.py @@ -62,7 +62,7 @@ def _latex_(self): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for affine type E. + Return the extended Dynkin diagram for affine type E. EXAMPLES:: @@ -113,7 +113,6 @@ def dynkin_diagram(self): [(0, 8, 1), (1, 3, 1), (2, 4, 1), (3, 1, 1), (3, 4, 1), (4, 2, 1), (4, 3, 1), (4, 5, 1), (5, 4, 1), (5, 6, 1), (6, 5, 1), (6, 7, 1), (7, 6, 1), (7, 8, 1), (8, 0, 1), (8, 7, 1)] - """ from .dynkin_diagram import DynkinDiagram_class n = self.n diff --git a/src/sage/combinat/root_system/type_F.py b/src/sage/combinat/root_system/type_F.py index 5d699d31c5a..744de2679a4 100644 --- a/src/sage/combinat/root_system/type_F.py +++ b/src/sage/combinat/root_system/type_F.py @@ -270,7 +270,7 @@ def dual_coxeter_number(self): def dynkin_diagram(self): """ - Returns a Dynkin diagram for type F. + Return a Dynkin diagram for type F. EXAMPLES:: @@ -280,7 +280,6 @@ def dynkin_diagram(self): F4 sage: f.edges(sort=True) # needs sage.graphs [(1, 2, 1), (2, 1, 1), (2, 3, 2), (3, 2, 1), (3, 4, 1), (4, 3, 1)] - """ from .dynkin_diagram import DynkinDiagram_class g = DynkinDiagram_class(self) diff --git a/src/sage/combinat/root_system/type_F_affine.py b/src/sage/combinat/root_system/type_F_affine.py index 3d2dc8350ee..66bbeb574a0 100644 --- a/src/sage/combinat/root_system/type_F_affine.py +++ b/src/sage/combinat/root_system/type_F_affine.py @@ -51,7 +51,7 @@ def __init__(self): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for affine type F. + Return the extended Dynkin diagram for affine type F. EXAMPLES:: @@ -62,7 +62,6 @@ def dynkin_diagram(self): sage: f.edges(sort=True) # needs sage.graphs [(0, 1, 1), (1, 0, 1), (1, 2, 1), (2, 1, 1), (2, 3, 2), (3, 2, 1), (3, 4, 1), (4, 3, 1)] - """ from .dynkin_diagram import DynkinDiagram_class g = DynkinDiagram_class(self) @@ -107,7 +106,7 @@ def _latex_dynkin_diagram(self, label=None, node=None, node_dist=2, dual=False): def ascii_art(self, label=None, node=None): """ - Returns a ascii art representation of the extended Dynkin diagram + Return a ascii art representation of the extended Dynkin diagram. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_G.py b/src/sage/combinat/root_system/type_G.py index a2a1612f8df..1ae705e5bec 100644 --- a/src/sage/combinat/root_system/type_G.py +++ b/src/sage/combinat/root_system/type_G.py @@ -182,7 +182,7 @@ def dual_coxeter_number(self): def dynkin_diagram(self): """ - Returns a Dynkin diagram for type G. + Return a Dynkin diagram for type G. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_G_affine.py b/src/sage/combinat/root_system/type_G_affine.py index 582f7d9ed03..0cc4f0dc4d7 100644 --- a/src/sage/combinat/root_system/type_G_affine.py +++ b/src/sage/combinat/root_system/type_G_affine.py @@ -51,7 +51,7 @@ def __init__(self): def dynkin_diagram(self): """ - Returns the extended Dynkin diagram for type G. + Return the extended Dynkin diagram for type G. EXAMPLES:: @@ -102,7 +102,7 @@ def _latex_dynkin_diagram(self, label=None, node=None, node_dist=2, dual=False): def ascii_art(self, label=None, node=None): """ - Returns an ascii art representation of the Dynkin diagram + Return an ascii art representation of the Dynkin diagram. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_H.py b/src/sage/combinat/root_system/type_H.py index 44f4b15db55..5a7c12c1b69 100644 --- a/src/sage/combinat/root_system/type_H.py +++ b/src/sage/combinat/root_system/type_H.py @@ -55,7 +55,7 @@ def _latex_(self): def coxeter_diagram(self): """ - Returns a Coxeter diagram for type H. + Return a Coxeter diagram for type H. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_I.py b/src/sage/combinat/root_system/type_I.py index 76a24817bf9..8f67bd07ee5 100644 --- a/src/sage/combinat/root_system/type_I.py +++ b/src/sage/combinat/root_system/type_I.py @@ -79,7 +79,7 @@ def index_set(self): def coxeter_diagram(self): """ - Returns the Coxeter matrix for this type. + Return the Coxeter matrix for this type. EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_Q.py b/src/sage/combinat/root_system/type_Q.py index b2aa3748e71..3e0e33b1399 100644 --- a/src/sage/combinat/root_system/type_Q.py +++ b/src/sage/combinat/root_system/type_Q.py @@ -16,7 +16,7 @@ class CartanType(CartanType_standard_finite): """ - Cartan Type `Q_n` + Cartan Type `Q_n`. .. SEEALSO:: :func:`~sage.combinat.root_systems.cartan_type.CartanType` """ diff --git a/src/sage/combinat/root_system/type_affine.py b/src/sage/combinat/root_system/type_affine.py index f903f40bf92..4acc93d29b3 100644 --- a/src/sage/combinat/root_system/type_affine.py +++ b/src/sage/combinat/root_system/type_affine.py @@ -158,8 +158,8 @@ def sortkey(x): return (1 if isinstance(x, str) else 0, x) CombinatorialFreeModule.__init__(self, base_ring, basis_keys, - prefix="e", - latex_prefix="e", + prefix='e', + latex_prefix='e', sorting_key=sortkey, category=WeightLatticeRealizations(base_ring)) self._weight_space = self.root_system.weight_space(base_ring=base_ring,extended=True) @@ -170,7 +170,7 @@ def sortkey(x): def _name_string(self, capitalize=True, base_ring=False, type=True): r""" - Utility to implement _repr_ + Utility to implement _repr_. EXAMPLES:: @@ -402,7 +402,7 @@ def coroot_lattice(self): def _plot_projection(self, x): r""" - Implements the default projection to be used for plots + Implement the default projection to be used for plots. For affine ambient spaces, the default implementation is to project onto the classical coordinates according to the diff --git a/src/sage/combinat/root_system/type_dual.py b/src/sage/combinat/root_system/type_dual.py index d7ec7e262a3..6f4710ae787 100644 --- a/src/sage/combinat/root_system/type_dual.py +++ b/src/sage/combinat/root_system/type_dual.py @@ -237,7 +237,7 @@ def _latex_dynkin_diagram(self, label=None, node=None, node_dist=2): def ascii_art(self, label=None, node=None): """ - Return an ascii art representation of this Cartan type + Return an ascii art representation of this Cartan type. (by hacking the ascii art representation of the dual Cartan type) @@ -528,7 +528,7 @@ class CartanType_finite(CartanType, cartan_type.CartanType_finite): class CartanType_affine(CartanType, cartan_type.CartanType_affine): def classical(self): """ - Return the classical Cartan type associated with self (which should + Return the classical Cartan type associated with ``self`` (which should be affine). EXAMPLES:: @@ -576,7 +576,7 @@ def basic_untwisted(self): def special_node(self): """ - Implement :meth:`CartanType_affine.special_node` + Implement :meth:`CartanType_affine.special_node`. The special node of the dual of an affine type `T` is the special node of `T`. diff --git a/src/sage/combinat/root_system/type_marked.py b/src/sage/combinat/root_system/type_marked.py index a9ca7d15a35..83d39c1a29f 100644 --- a/src/sage/combinat/root_system/type_marked.py +++ b/src/sage/combinat/root_system/type_marked.py @@ -23,7 +23,7 @@ class CartanType(cartan_type.CartanType_decorator): - ``ct`` -- a Cartan type - - ``marked_nodes`` -- a list of marked nodes + - ``marked_nodes`` -- list of marked nodes EXAMPLES: @@ -233,7 +233,7 @@ def _ascii_art_node(self, label): return self.options('marked_node_str') return 'O' - def _latex_draw_node(self, x, y, label, position="below=4pt", fill='white'): + def _latex_draw_node(self, x, y, label, position='below=4pt', fill='white'): r""" Draw (possibly marked [crossed out]) circular node ``i`` at the position ``(x,y)`` with node label ``label`` . @@ -357,7 +357,7 @@ def dynkin_diagram(self): def dual(self): """ - Implements + Implement :meth:`sage.combinat.root_system.cartan_type.CartanType_abstract.dual`, using that taking the dual and marking nodes are commuting operations. @@ -614,7 +614,7 @@ class CartanType_affine(CartanType, cartan_type.CartanType_affine): sage: TestSuite(L).run() """ - def _latex_draw_node(self, x, y, label, position="below=4pt"): + def _latex_draw_node(self, x, y, label, position='below=4pt'): r""" Draw the possibly marked (crossed out) circular node ``i`` at the position ``(x,y)`` with node label ``label`` . diff --git a/src/sage/combinat/root_system/type_reducible.py b/src/sage/combinat/root_system/type_reducible.py index a728535447e..da337ebaa96 100644 --- a/src/sage/combinat/root_system/type_reducible.py +++ b/src/sage/combinat/root_system/type_reducible.py @@ -33,7 +33,7 @@ class CartanType(SageObject, CartanType_abstract): INPUT: - - ``types`` -- a list of simple Cartan types + - ``types`` -- list of simple Cartan types EXAMPLES:: @@ -212,7 +212,7 @@ def component_types(self): def type(self): """ - Returns "reducible" since the type is reducible. + Return ``"reducible"`` since the type is reducible. EXAMPLES:: @@ -223,7 +223,7 @@ def type(self): def rank(self): """ - Returns the rank of self. + Return the rank of ``self``. EXAMPLES:: @@ -235,7 +235,7 @@ def rank(self): @cached_method def index_set(self): r""" - Implements :meth:`CartanType_abstract.index_set`. + Implement :meth:`CartanType_abstract.index_set`. For the moment, the index set is always of the form `\{1, \ldots, n\}`. @@ -276,7 +276,7 @@ def cartan_matrix(self, subdivide=True): def dynkin_diagram(self): """ - Returns a Dynkin diagram for type reducible. + Return a Dynkin diagram for type reducible. EXAMPLES:: @@ -298,7 +298,6 @@ def dynkin_diagram(self): O---O 5 6 F4xA2 - """ from .dynkin_diagram import DynkinDiagram_class relabelling = self._index_relabelling @@ -420,7 +419,7 @@ def dual(self): def is_affine(self): """ - Report that this reducible Cartan type is not affine + Report that this reducible Cartan type is not affine. EXAMPLES:: @@ -465,7 +464,6 @@ class AmbientSpace(ambient_space.AmbientSpace): sage: RootSystem("A2xB2").ambient_space() Ambient space of the Root system of type A2xB2 - """ def cartan_type(self): @@ -497,7 +495,7 @@ def dimension(self): def ambient_spaces(self): """ - Returns a list of the irreducible Cartan types of which the + Return a list of the irreducible Cartan types of which the given reducible Cartan type is a product. EXAMPLES:: @@ -509,14 +507,14 @@ def ambient_spaces(self): return [t.root_system().ambient_space() for t in self.component_types()] def inject_weights(self, i, v): - """ + r""" Produces the corresponding element of the lattice. INPUT: - - ``i`` -- an integer in range(self.components) + - ``i`` -- integer in ``range(self.components)`` - - ``v`` -- a vector in the i-th component weight lattice + - ``v`` -- a vector in the `i`-th component weight lattice EXAMPLES:: diff --git a/src/sage/combinat/root_system/type_relabel.py b/src/sage/combinat/root_system/type_relabel.py index d90e97cd375..27597563ae9 100644 --- a/src/sage/combinat/root_system/type_relabel.py +++ b/src/sage/combinat/root_system/type_relabel.py @@ -317,7 +317,7 @@ def ascii_art(self, label=None, node=None): def dynkin_diagram(self): """ - Returns the Dynkin diagram for this Cartan type. + Return the Dynkin diagram for this Cartan type. EXAMPLES:: @@ -358,7 +358,7 @@ def index_set(self): def dual(self): """ - Implements :meth:`sage.combinat.root_system.cartan_type.CartanType_abstract.dual`, + Implement :meth:`sage.combinat.root_system.cartan_type.CartanType_abstract.dual`, using that taking the dual and relabelling are commuting operations. EXAMPLES:: @@ -677,7 +677,6 @@ def classical(self): O---O---O---O 2 3 4 0 A4 relabelled by {1: 2, 2: 3, 3: 4, 4: 0} - """ return self._type.classical().relabel(self._relabelling) @@ -700,7 +699,7 @@ def basic_untwisted(self): def special_node(self): r""" - Returns a special node of the Dynkin diagram + Return a special node of the Dynkin diagram. .. SEEALSO:: :meth:`~sage.combinat.root_system.CartanType_affine.special_node` @@ -718,7 +717,7 @@ def special_node(self): def is_untwisted_affine(self): """ - Implement :meth:`CartanType_affine.is_untwisted_affine` + Implement :meth:`CartanType_affine.is_untwisted_affine`. A relabelled Cartan type is untwisted affine if the original is. @@ -726,6 +725,5 @@ def is_untwisted_affine(self): sage: CartanType(['B', 3, 1]).relabel({1:2, 2:3, 3:0, 0:1}).is_untwisted_affine() True - """ return self._type.is_untwisted_affine() diff --git a/src/sage/combinat/root_system/type_super_A.py b/src/sage/combinat/root_system/type_super_A.py index c2717a572ff..5ccb17e6a4e 100644 --- a/src/sage/combinat/root_system/type_super_A.py +++ b/src/sage/combinat/root_system/type_super_A.py @@ -43,7 +43,7 @@ def __init__(self, root_system, base_ring, index_set=None): sage: R = RootSystem(['A', [4,2]]) sage: AL = R.ambient_space(); AL Ambient space of the Root system of type ['A', [4, 2]] - sage: TestSuite(AL).run(skip="_test_norm_of_simple_roots") + sage: TestSuite(AL).run(skip='_test_norm_of_simple_roots') """ ct = root_system.cartan_type() if index_set is None: @@ -378,7 +378,7 @@ def associated_coroot(self): def has_descent(self, i, positive=False): """ Test if ``self`` has a descent at position `i`, that is - if ``self`` is on the strict negative side of the `i^{th}` + if ``self`` is on the strict negative side of the `i`-th simple reflection hyperplane. If ``positive`` is ``True``, tests if it is on the strict @@ -710,7 +710,7 @@ def relabel(self, relabelling): from . import type_relabel return type_relabel.CartanType(self, relabelling) - def _latex_draw_node(self, x, y, label, position="below=4pt"): + def _latex_draw_node(self, x, y, label, position='below=4pt'): r""" Draw (possibly marked [crossed out]) circular node ``i`` at the position ``(x,y)`` with node label ``label`` . diff --git a/src/sage/combinat/root_system/weight_lattice_realizations.py b/src/sage/combinat/root_system/weight_lattice_realizations.py index 801b4da79b7..17faf8bb914 100644 --- a/src/sage/combinat/root_system/weight_lattice_realizations.py +++ b/src/sage/combinat/root_system/weight_lattice_realizations.py @@ -30,7 +30,7 @@ class WeightLatticeRealizations(Category_over_base_ring): r""" - The category of weight lattice realizations over a given base ring + The category of weight lattice realizations over a given base ring. A *weight lattice realization* `L` over a base ring `R` is a free module (or vector space if `R` is a field) endowed with an embedding @@ -133,14 +133,14 @@ class ParentMethods: @abstract_method def fundamental_weight(self, i): r""" - Returns the `i^{th}` fundamental weight + Return the `i`-th fundamental weight. INPUT: - ``i`` -- an element of the index set By a slight notational abuse, for an affine type this method - should also accept ``"delta"`` as input, and return the image + should also accept ``'delta'`` as input, and return the image of `\delta` of the extended weight lattice in this realization. @@ -169,7 +169,7 @@ def fundamental_weight(self, i): def is_extended(self): """ - Return whether this is a realization of the extended weight lattice + Return whether this is a realization of the extended weight lattice. .. SEEALSO:: :class:`sage.combinat.root_system.weight_space.WeightSpace` @@ -191,7 +191,7 @@ def is_extended(self): def __init_extra__(self): r""" - Registers the embedding of the weight lattice into ``self`` + Registers the embedding of the weight lattice into ``self``. Also registers the embedding of the weight space over the same base field `K` into ``self`` if `K` is not `\ZZ`. @@ -211,7 +211,7 @@ def __init_extra__(self): sage: L(Lambda[2]) (0, 1, -1, 0) - .. note:: + .. NOTE:: More examples are given in :class:`WeightLatticeRealizations`; The embeddings are systematically tested in @@ -236,7 +236,7 @@ def __init_extra__(self): def _test_weight_lattice_realization(self, **options): """ - Runs sanity checks on this weight lattice realization + Run sanity checks on this weight lattice realization. - scalar products between the fundamental weights and simple coroots - embeddings from the weight lattice and weight space @@ -307,7 +307,7 @@ def _test_weight_lattice_realization(self, **options): @cached_method def fundamental_weights(self): r""" - Returns the family `(\Lambda_i)_{i\in I}` of the fundamental weights. + Return the family `(\Lambda_i)_{i\in I}` of the fundamental weights. EXAMPLES:: @@ -323,7 +323,7 @@ def fundamental_weights(self): @cached_method def simple_root(self, i): r""" - Returns the `i`-th simple root + Return the `i`-th simple root. This default implementation takes the `i`-th simple root in the weight lattice and embeds it in ``self``. @@ -532,7 +532,7 @@ def reduced_word_of_alcove_morphism(self, f): def dynkin_diagram_automorphism_of_alcove_morphism(self, f): r""" - Return the Dynkin diagram automorphism induced by an alcove morphism + Return the Dynkin diagram automorphism induced by an alcove morphism. INPUT: @@ -663,11 +663,11 @@ def reduced_word_of_translation(self, t): def _test_reduced_word_of_translation(self, elements=None, **options): r""" - Tests the method :meth:`reduced_word_of_translation`. + Test the method :meth:`reduced_word_of_translation`. INPUT: - - ``options`` -- any keyword arguments accepted by :meth:`_tester`. + - ``options`` -- any keyword arguments accepted by :meth:`_tester` EXAMPLES:: @@ -770,7 +770,7 @@ def signs_of_alcovewalk(self, walk): simple coroot associated to `\alpha_{i_k}`. This function returns a list of the form `[+1,+1,-1,...]`, - where the `k^{th}` entry denotes whether the `k^{th}` step was + where the `k`-th entry denotes whether the `k`-th step was positive or negative. See equation 3.4, of Ram: Alcove walks ..., :arxiv:`math/0601343v1` @@ -847,7 +847,7 @@ def rho_classical(self): def embed_at_level(self, x, level=1): r""" - Embed the classical weight `x` in the level ``level`` hyperplane + Embed the classical weight `x` in the level ``level`` hyperplane. This is achieved by translating the straightforward embedding of `x` by `c\Lambda_0` for `c` some appropriate @@ -856,7 +856,7 @@ def embed_at_level(self, x, level=1): INPUT: - ``x`` -- an element of the corresponding classical weight/ambient lattice - - ``level`` -- an integer or element of the base ring (default: 1) + - ``level`` -- integer or element of the base ring (default: 1) EXAMPLES:: @@ -973,7 +973,6 @@ def _symmetric_form_matrix(self): [ 0 2 2 1] [ 0 2 4 1] [1/2 1 1 0] - """ from sage.matrix.constructor import matrix ct = self.cartan_type() @@ -1100,7 +1099,6 @@ def symmetric_form(self, la): sage: all(s1(ct) == s2(ct) # needs sage.graphs ....: for ct in CartanType.samples(finite=True, crystallographic=True)) True - """ P = self.parent() ct = P.cartan_type() diff --git a/src/sage/combinat/root_system/weight_space.py b/src/sage/combinat/root_system/weight_space.py index fce5f57f94d..3dbaa0740e8 100644 --- a/src/sage/combinat/root_system/weight_space.py +++ b/src/sage/combinat/root_system/weight_space.py @@ -21,7 +21,7 @@ class WeightSpace(CombinatorialFreeModule): - ``root_system`` -- a root system - ``base_ring`` -- a ring `R` - - ``extended`` -- a boolean (default: ``False``) + - ``extended`` -- boolean (default: ``False``) The weight space (or lattice if ``base_ring`` is `\ZZ`) of a root system is the formal free module `\bigoplus_i R \Lambda_i` @@ -145,7 +145,7 @@ class WeightSpace(CombinatorialFreeModule): @staticmethod def __classcall_private__(cls, root_system, base_ring, extended=False): """ - Guarantees Unique representation + Guarantee Unique representation. .. SEEALSO:: :class:`UniqueRepresentation` @@ -230,7 +230,6 @@ def _repr_(self): Coweight lattice of the Root system of type ['A', 4] sage: RootSystem(['B',4]).coweight_space() Coweight space over the Rational Field of the Root system of type ['B', 4] - """ return self._name_string() @@ -248,14 +247,14 @@ def _name_string(self, capitalize=True, base_ring=True, type=True): @cached_method def fundamental_weight(self, i): r""" - Returns the `i`-th fundamental weight + Return the `i`-th fundamental weight. INPUT: - - ``i`` -- an element of the index set or ``"delta"`` + - ``i`` -- an element of the index set or ``'delta'`` By a slight notational abuse, for an affine type this method - also accepts ``"delta"`` as input, and returns the image of + also accepts ``'delta'`` as input, and returns the image of `\delta` of the extended weight lattice in this realization. .. SEEALSO:: :meth:`~sage.combinat.root_system.weight_lattice_realization.ParentMethods.fundamental_weight` @@ -287,7 +286,7 @@ def fundamental_weight(self, i): @cached_method def basis_extension(self): r""" - Return the basis elements used to extend the fundamental weights + Return the basis elements used to extend the fundamental weights. EXAMPLES:: @@ -313,7 +312,7 @@ def basis_extension(self): @cached_method def simple_root(self, j): r""" - Returns the `j^{th}` simple root + Return the `j`-th simple root. EXAMPLES:: @@ -371,7 +370,7 @@ def simple_root(self, j): def _repr_term(self, m): r""" - Customized monomial printing for extended weight lattices + Customized monomial printing for extended weight lattices. EXAMPLES:: @@ -389,7 +388,7 @@ def _repr_term(self, m): def _latex_term(self, m): r""" - Customized monomial typesetting for extended weight lattices + Customized monomial typesetting for extended weight lattices. EXAMPLES:: @@ -516,7 +515,7 @@ def scalar(self, lambdacheck): def is_dominant(self): r""" - Checks whether an element in the weight space lies in the positive + Check whether an element in the weight space lies in the positive cone spanned by the basis elements (fundamental weights). EXAMPLES:: @@ -546,7 +545,7 @@ def is_dominant(self): def is_dominant_weight(self): r""" - Checks whether an element in the weight space lies in the positive + Check whether an element in the weight space lies in the positive `\ZZ`-lattice cone spanned by the basis elements (fundamental weights). EXAMPLES:: @@ -580,7 +579,7 @@ def is_dominant_weight(self): def to_ambient(self): r""" - Maps ``self`` to the ambient space. + Map ``self`` to the ambient space. EXAMPLES:: @@ -594,7 +593,6 @@ def to_ambient(self): Only implemented in finite Cartan type. Does not work for coweight lattices because there is no implemented map from the coweight lattice to the ambient space. - """ return self.parent().to_ambient_space_morphism()(self) diff --git a/src/sage/combinat/root_system/weyl_characters.py b/src/sage/combinat/root_system/weyl_characters.py index a42929606b1..d7f87d6f494 100644 --- a/src/sage/combinat/root_system/weyl_characters.py +++ b/src/sage/combinat/root_system/weyl_characters.py @@ -67,7 +67,7 @@ class WeylCharacterRing(CombinatorialFreeModule): sage: L = RootSystem("A2").ambient_space() sage: [fw1,fw2] = L.fundamental_weights() - sage: R = WeylCharacterRing(['A',2], prefix="R") + sage: R = WeylCharacterRing(['A',2], prefix='R') sage: [R(1),R(fw1),R(fw2)] [R(0,0,0), R(1,0,0), R(1,1,0)] @@ -93,11 +93,11 @@ class WeylCharacterRing(CombinatorialFreeModule): https://doc.sagemath.org/html/en/thematic_tutorials/lie.html """ @staticmethod - def __classcall__(cls, ct, base_ring=ZZ, prefix=None, style="lattice", k=None, conjugate=False, cyclotomic_order=None, fusion_labels=None, inject_variables=False): + def __classcall__(cls, ct, base_ring=ZZ, prefix=None, style='lattice', k=None, conjugate=False, cyclotomic_order=None, fusion_labels=None, inject_variables=False): """ TESTS:: - sage: R = WeylCharacterRing("G2", style="coroots") + sage: R = WeylCharacterRing("G2", style='coroots') sage: R.cartan_type() is CartanType("G2") True sage: R.base_ring() is ZZ @@ -111,7 +111,7 @@ def __classcall__(cls, ct, base_ring=ZZ, prefix=None, style="lattice", k=None, c prefix = repr(ct) return super().__classcall__(cls, ct, base_ring=base_ring, prefix=prefix, style=style, k=k, conjugate=conjugate, cyclotomic_order=cyclotomic_order, fusion_labels=fusion_labels, inject_variables=inject_variables) - def __init__(self, ct, base_ring=ZZ, prefix=None, style="lattice", k=None, conjugate=False, cyclotomic_order=None, fusion_labels=None, inject_variables=False): + def __init__(self, ct, base_ring=ZZ, prefix=None, style='lattice', k=None, conjugate=False, cyclotomic_order=None, fusion_labels=None, inject_variables=False): """ EXAMPLES:: @@ -152,7 +152,7 @@ def __init__(self, ct, base_ring=ZZ, prefix=None, style="lattice", k=None, conju def next_level(wt): return [wt + la for la in fw if self.level(wt + la) <= k] B = list(RecursivelyEnumeratedSet([self._space.zero()], next_level)) - B = [self._space.from_vector_notation(wt, style="coroots") for wt in B] + B = [self._space.from_vector_notation(wt, style='coroots') for wt in B] else: B = self._space @@ -274,7 +274,7 @@ def demazure_character(self, hwv, word, debug=False): EXAMPLES:: - sage: A2 = WeylCharacterRing("A2",style="coroots") + sage: A2 = WeylCharacterRing("A2",style='coroots') sage: h = sum(A2.fundamental_weights()); h (2, 1, 0) sage: A2.demazure_character(h,word=[1,2]) @@ -284,7 +284,7 @@ def demazure_character(self, hwv, word, debug=False): """ if self._style != "coroots": raise ValueError('demazure method unavailable: use style="coroots"') - hwv = self._space.from_vector_notation(hwv, style="coroots") + hwv = self._space.from_vector_notation(hwv, style='coroots') return self.ambient()._from_dict(self._demazure_weights(hwv, word=word, debug=debug)) @lazy_attribute @@ -323,7 +323,7 @@ def lift(self): def _retract(self, chi): """ - Construct a Weyl character from an invariant element of the weight ring + Construct a Weyl character from an invariant element of the weight ring. INPUT: @@ -446,12 +446,11 @@ def __call__(self, *args): [-2*A2(0,0,0), -A2(0,0,0), 0, A2(0,0,0), 2*A2(0,0,0), -2*q*A2(0,0,0), -q*A2(0,0,0), q*A2(0,0,0), 2*q*A2(0,0,0), (-q+1)*A2(0,0,0)] sage: R. = ZZ[] - sage: A2 = WeylCharacterRing(['A',2], base_ring = R, style="coroots") + sage: A2 = WeylCharacterRing(['A',2], base_ring = R, style='coroots') sage: q*A2(1) q*A2(0,0) sage: [A2(x) for x in [-2,-1,0,1,2,-2*q,-q,q,2*q,(1-q)]] [-2*A2(0,0), -A2(0,0), 0, A2(0,0), 2*A2(0,0), -2*q*A2(0,0), -q*A2(0,0), q*A2(0,0), 2*q*A2(0,0), (-q+1)*A2(0,0)] - """ # The purpose of this __call__ method is only to handle the # syntactical shorthand; otherwise it just delegates the work @@ -520,7 +519,7 @@ def _product_helper(self, d1, b): INPUT: - - ``d1`` -- a dictionary of weight multiplicities + - ``d1`` -- dictionary of weight multiplicities - ``b`` -- a dominant weight If ``d1`` is the dictionary of weight multiplicities of a character, @@ -665,9 +664,9 @@ def _irr_weights(self, hwv): else: return irreducible_character_freudenthal(hwv) - def _demazure_weights(self, hwv, word="long", debug=False): + def _demazure_weights(self, hwv, word='long', debug=False): """ - Computes the weights of a Demazure character. + Compute the weights of a Demazure character. This method duplicates the functionality of :meth:`_irr_weights`, under the assumption that ``style = "coroots"``, but allows an optional @@ -683,7 +682,7 @@ def _demazure_weights(self, hwv, word="long", debug=False): EXAMPLES:: - sage: B2 = WeylCharacterRing("B2", style="coroots") + sage: B2 = WeylCharacterRing("B2", style='coroots') sage: [B2._demazure_weights(v, word=[1,2]) for v in B2.fundamental_weights()] [{(1, 0): 1, (0, 1): 1}, {(-1/2, 1/2): 1, (1/2, -1/2): 1, (1/2, 1/2): 1}] """ @@ -694,7 +693,7 @@ def _demazure_weights(self, hwv, word="long", debug=False): dd[h] = 1 return self._demazure_helper(dd, word=word, debug=debug) - def _demazure_helper(self, dd, word="long", debug=False): + def _demazure_helper(self, dd, word='long', debug=False): r""" Assumes ``style = "coroots"``. If the optional parameter ``word`` is specified, produces a Demazure character (defaults to the long Weyl @@ -702,13 +701,13 @@ def _demazure_helper(self, dd, word="long", debug=False): INPUT: - - ``dd`` -- a dictionary of weights + - ``dd`` -- dictionary of weights - ``word`` -- (optional) a Weyl group reduced word EXAMPLES:: - sage: A2 = WeylCharacterRing("A2",style="coroots") + sage: A2 = WeylCharacterRing("A2",style='coroots') sage: dd = {}; dd[(1,1)]=int(1) sage: A2._demazure_helper(dd,word=[1,2]) {(0, 0, 0): 1, (-1, 1, 0): 1, (1, -1, 0): 1, (1, 0, -1): 1, (0, 1, -1): 1} @@ -768,7 +767,7 @@ def _demazure_helper(self, dd, word="long", debug=False): ret = {} for v in accum: if accum[v]: - ret[self._space.from_vector_notation(v, style="coroots")] = accum[v] + ret[self._space.from_vector_notation(v, style='coroots')] = accum[v] return ret @cached_method @@ -779,7 +778,7 @@ def _weight_multiplicities(self, x): EXAMPLES:: - sage: B2 = WeylCharacterRing("B2",style="coroots") + sage: B2 = WeylCharacterRing("B2",style='coroots') sage: chi = 2*B2(1,0) sage: B2._weight_multiplicities(chi) {(0, 0): 2, (-1, 0): 2, (1, 0): 2, (0, -1): 2, (0, 1): 2} @@ -822,7 +821,7 @@ def irr_repr(self, hwv): sage: B3 = WeylCharacterRing("B3") sage: [B3.irr_repr(v) for v in B3.fundamental_weights()] ['B3(1,0,0)', 'B3(1,1,0)', 'B3(1/2,1/2,1/2)'] - sage: B3 = WeylCharacterRing("B3", style="coroots") + sage: B3 = WeylCharacterRing("B3", style='coroots') sage: [B3.irr_repr(v) for v in B3.fundamental_weights()] ['B3(1,0,0)', 'B3(0,1,0)', 'B3(0,0,1)'] """ @@ -876,7 +875,7 @@ def _wt_repr(self, wt): ((1, 0, -1), (2, -1, -1)) sage: [WeylCharacterRing("G2")._wt_repr(v) for v in [fw1,fw2]] ['(1,0,-1)', '(2,-1,-1)'] - sage: [WeylCharacterRing("G2",style="coroots")._wt_repr(v) for v in [fw1,fw2]] + sage: [WeylCharacterRing("G2",style='coroots')._wt_repr(v) for v in [fw1,fw2]] ['(1,0)', '(0,1)'] """ if self._style == "lattice": @@ -1034,7 +1033,7 @@ def char_from_weights(self, mdict): INPUT: - - ``mdict`` -- a dictionary mapping weights to coefficients, + - ``mdict`` -- dictionary mapping weights to coefficients, and representing a linear combination of weights which shall be invariant under the action of the Weyl group @@ -1063,7 +1062,7 @@ def _char_from_weights(self, mdict): INPUT: - - ``mdict`` -- a dictionary of weight multiplicities + - ``mdict`` -- dictionary of weight multiplicities The output of this method is a dictionary whose keys are dominant weights that is the same as the :meth:`monomial_coefficients` method @@ -1105,7 +1104,7 @@ def adjoint_representation(self): EXAMPLES:: - sage: G2 = WeylCharacterRing("G2",style="coroots") + sage: G2 = WeylCharacterRing("G2",style='coroots') sage: G2.adjoint_representation() G2(0,1) """ @@ -1159,7 +1158,7 @@ def maximal_subgroups(self): another different one may be obtained by composing it with the triality automorphism of `D_4`:: - sage: [D4,A1xC2]=[WeylCharacterRing(x,style="coroots") for x in ["D4","A1xC2"]] + sage: [D4,A1xC2]=[WeylCharacterRing(x,style='coroots') for x in ["D4","A1xC2"]] sage: fw = D4.fundamental_weights() sage: b = D4.maximal_subgroup("A1xC2") sage: [D4(fw).branch(A1xC2,rule=b) for fw in D4.fundamental_weights()] @@ -1182,7 +1181,7 @@ def maximal_subgroup(self, ct): INPUT: - - ``ct`` -- the Cartan type of a maximal subgroup of ``self``. + - ``ct`` -- the Cartan type of a maximal subgroup of ``self`` In rare cases where there is more than one maximal subgroup (up to outer automorphisms) @@ -1198,7 +1197,7 @@ def maximal_subgroup(self, ct): For more information, see the related method :meth:`maximal_subgroups`. """ - return sage.combinat.root_system.branching_rules.maximal_subgroups(self.cartan_type(), mode="get_rule")[ct] + return sage.combinat.root_system.branching_rules.maximal_subgroups(self.cartan_type(), mode='get_rule')[ct] class Element(CombinatorialFreeModule.Element): """ @@ -1232,7 +1231,7 @@ def degree(self): L = self.parent()._space return sum(L.weyl_dimension(k) * c for k, c in self) - def branch(self, S, rule="default"): + def branch(self, S, rule='default'): """ Return the restriction of the character to the subalgebra. @@ -1242,7 +1241,7 @@ def branch(self, S, rule="default"): - ``S`` -- a Weyl character ring for a Lie subgroup or subalgebra - - ``rule`` -- a branching rule + - ``rule`` -- a branching rule See :func:`~sage.combinat.root_system.branching_rules.branch_weyl_character` for more information about branching rules. @@ -1251,7 +1250,7 @@ def branch(self, S, rule="default"): sage: B3 = WeylCharacterRing(['B',3]) sage: A2 = WeylCharacterRing(['A',2]) - sage: [B3(w).branch(A2,rule="levi") for w in B3.fundamental_weights()] + sage: [B3(w).branch(A2,rule='levi') for w in B3.fundamental_weights()] [A2(0,0,0) + A2(1,0,0) + A2(0,0,-1), A2(0,0,0) + A2(1,0,0) + A2(1,1,0) + A2(1,0,-1) + A2(0,-1,-1) + A2(0,0,-1), A2(-1/2,-1/2,-1/2) + A2(1/2,-1/2,-1/2) + A2(1/2,1/2,-1/2) + A2(1/2,1/2,1/2)] @@ -1266,7 +1265,7 @@ def dual(self): EXAMPLES:: - sage: A3 = WeylCharacterRing("A3", style="coroots") + sage: A3 = WeylCharacterRing("A3", style='coroots') sage: A3(1,0,0)^2 A3(0,1,0) + A3(2,0,0) sage: (A3(1,0,0)^2).dual() @@ -1288,7 +1287,7 @@ def highest_weight(self): EXAMPLES:: - sage: G2 = WeylCharacterRing("G2", style="coroots") + sage: G2 = WeylCharacterRing("G2", style='coroots') sage: [x.highest_weight() for x in [G2(1,0),G2(0,1)]] [(1, 0, -1), (2, -1, -1)] """ @@ -1298,7 +1297,7 @@ def highest_weight(self): def __pow__(self, n): """ - Return the n-th power of ``self``. + Return the `n`-th power of ``self``. We override the method in :mod:`sage.monoids.monoids` since using the Brauer-Klimyk algorithm, it is more efficient to @@ -1306,7 +1305,7 @@ def __pow__(self, n): EXAMPLES:: - sage: B4 = WeylCharacterRing("B4",style="coroots") + sage: B4 = WeylCharacterRing("B4",style='coroots') sage: spin = B4(0,0,0,1) sage: [spin^k for k in [0,1,3]] [B4(0,0,0,0), B4(0,0,0,1), 5*B4(0,0,0,1) + 4*B4(1,0,0,1) + 3*B4(0,1,0,1) + 2*B4(0,0,1,1) + B4(0,0,0,3)] @@ -1352,7 +1351,7 @@ def symmetric_power(self, k): INPUT: - - `k` -- a nonnegative integer + - ``k`` -- nonnegative integer The algorithm is based on the identity `k h_k = \sum_{r=1}^k p_k h_{k-r}` relating the power-sum @@ -1364,7 +1363,7 @@ def symmetric_power(self, k): EXAMPLES:: - sage: B3 = WeylCharacterRing("B3",style="coroots") + sage: B3 = WeylCharacterRing("B3",style='coroots') sage: spin = B3(0,0,1) sage: spin.symmetric_power(6) B3(0,0,0) + B3(0,0,2) + B3(0,0,4) + B3(0,0,6) @@ -1390,7 +1389,7 @@ def exterior_power(self, k): INPUT: - - ``k`` -- a nonnegative integer + - ``k`` -- nonnegative integer The algorithm is based on the identity `k e_k = \sum_{r=1}^k (-1)^{k-1} p_k e_{k-r}` relating the @@ -1402,7 +1401,7 @@ def exterior_power(self, k): EXAMPLES:: - sage: B3 = WeylCharacterRing("B3",style="coroots") + sage: B3 = WeylCharacterRing("B3",style='coroots') sage: spin = B3(0,0,1) sage: spin.exterior_power(6) B3(1,0,0) + B3(0,1,0) @@ -1431,7 +1430,7 @@ def adams_operator(self, r): INPUT: - - ``r`` -- a positive integer + - ``r`` -- positive integer This is a virtual character, whose weights are the weights of ``self``, each multiplied by `r`. @@ -1452,7 +1451,7 @@ def _adams_operator_helper(self, r): INPUT: - - ``r`` -- a positive integer + - ``r`` -- positive integer Return the dictionary of weight multiplicities for the Adams operation, needed for internal use by symmetric and exterior powers. @@ -1472,7 +1471,7 @@ def symmetric_square(self): EXAMPLES:: - sage: A2 = WeylCharacterRing("A2",style="coroots") + sage: A2 = WeylCharacterRing("A2",style='coroots') sage: A2(1,0).symmetric_square() A2(2,0) """ @@ -1509,7 +1508,7 @@ def exterior_square(self): EXAMPLES:: - sage: A2 = WeylCharacterRing("A2",style="coroots") + sage: A2 = WeylCharacterRing("A2",style='coroots') sage: A2(1,0).exterior_square() A2(0,1) """ @@ -1559,7 +1558,7 @@ def frobenius_schur_indicator(self): EXAMPLES:: - sage: B2 = WeylCharacterRing("B2",style="coroots") + sage: B2 = WeylCharacterRing("B2",style='coroots') sage: B2(1,0).frobenius_schur_indicator() 1 sage: B2(0,1).frobenius_schur_indicator() @@ -1583,7 +1582,7 @@ def weight_multiplicities(self): EXAMPLES:: - sage: B2 = WeylCharacterRing("B2",style="coroots") + sage: B2 = WeylCharacterRing("B2",style='coroots') sage: B2(0,1).weight_multiplicities() {(-1/2, -1/2): 1, (-1/2, 1/2): 1, (1/2, -1/2): 1, (1/2, 1/2): 1} """ @@ -1624,7 +1623,7 @@ def invariant_degree(self): EXAMPLES:: - sage: A2 = WeylCharacterRing("A2",style="coroots") + sage: A2 = WeylCharacterRing("A2",style='coroots') sage: rep = A2(1,0)^2*A2(0,1)^2; rep 2*A2(0,0) + A2(0,3) + 4*A2(1,1) + A2(3,0) + A2(2,2) sage: rep.invariant_degree() @@ -1642,7 +1641,7 @@ def multiplicity(self, other): EXAMPLES:: - sage: B2 = WeylCharacterRing("B2",style="coroots") + sage: B2 = WeylCharacterRing("B2",style='coroots') sage: rep = B2(1,1)^2; rep B2(0,0) + B2(1,0) + 2*B2(0,2) + B2(2,0) + 2*B2(1,2) + B2(0,4) + B2(3,0) + B2(2,2) sage: rep.multiplicity(B2(0,2)) @@ -1669,7 +1668,7 @@ def irreducible_character_freudenthal(hwv, debug=False): INPUT: - - ``hwv`` -- a dominant weight in a weight lattice. + - ``hwv`` -- a dominant weight in a weight lattice - ``L`` -- the ambient space @@ -1755,7 +1754,7 @@ def __classcall__(cls, parent, prefix=None): """ TESTS:: - sage: A3 = WeylCharacterRing("A3", style="coroots") + sage: A3 = WeylCharacterRing("A3", style='coroots') sage: a3 = WeightRing(A3) sage: a3.cartan_type(), a3.base_ring(), a3.parent() (['A', 3], Integer Ring, The Weyl Character Ring of Type A3 with Integer Ring coefficients) @@ -1824,7 +1823,7 @@ def __call__(self, *args): you may give a tuple of integers. Normally these are the components of the vector in the standard realization of the weight lattice as a vector space. Alternatively, if - the ring is constructed with style="coroots", you may + the ring is constructed with style='coroots', you may specify the weight by giving a set of integers, one for each fundamental weight; the weight is then the linear combination of the fundamental weights with these coefficients. @@ -1853,7 +1852,7 @@ def _element_constructor_(self, weight): INPUT: - - ``weight`` -- an element of the weight space, or a tuple + - ``weight`` -- an element of the weight space, or a tuple This method is responsible for constructing an appropriate weight from the data in ``weight``, and then return the @@ -2010,7 +2009,7 @@ def wt_repr(self, wt): sage: G2 = WeylCharacterRing("G2") sage: [G2.ambient().wt_repr(x) for x in G2.fundamental_weights()] ['g2(1,0,-1)', 'g2(2,-1,-1)'] - sage: G2 = WeylCharacterRing("G2",style="coroots") + sage: G2 = WeylCharacterRing("G2",style='coroots') sage: [G2.ambient().wt_repr(x) for x in G2.fundamental_weights()] ['g2(1,0)', 'g2(0,1)'] """ @@ -2089,11 +2088,11 @@ def scale(self, k): INPUT: - - ``k`` -- a nonzero integer + - ``k`` -- nonzero integer EXAMPLES:: - sage: g2 = WeylCharacterRing("G2",style="coroots").ambient() + sage: g2 = WeylCharacterRing("G2",style='coroots').ambient() sage: g2(2,3).scale(2) g2(4,6) """ @@ -2115,7 +2114,7 @@ def shift(self, mu): EXAMPLES:: - sage: g2 = WeylCharacterRing("G2",style="coroots").ambient() + sage: g2 = WeylCharacterRing("G2",style='coroots').ambient() sage: [g2(1,2).shift(fw) for fw in g2.fundamental_weights()] [g2(2,2), g2(1,3)] """ @@ -2145,7 +2144,7 @@ def demazure(self, w, debug=False): EXAMPLES:: - sage: B2 = WeylCharacterRing("B2",style="coroots") + sage: B2 = WeylCharacterRing("B2",style='coroots') sage: b2 = WeightRing(B2) sage: b2(1,0).demazure([1]) b2(1,0) + b2(-1,2) @@ -2205,7 +2204,7 @@ def demazure_lusztig(self, i, v): EXAMPLES:: sage: P. = PolynomialRing(QQ) - sage: B2 = WeylCharacterRing("B2",style="coroots",base_ring=P); b2 = B2.ambient() + sage: B2 = WeylCharacterRing("B2",style='coroots',base_ring=P); b2 = B2.ambient() sage: def T1(f): return f.demazure_lusztig(1,v) sage: def T2(f): return f.demazure_lusztig(2,v) sage: T1(T2(T1(T2(b2(1,-1))))) @@ -2220,13 +2219,13 @@ def demazure_lusztig(self, i, v): sage: b2(1,0).demazure_lusztig([2,1],v)==T2(T1(b2(1,0))) True - sage: W = B2.space().weyl_group(prefix="s") + sage: W = B2.space().weyl_group(prefix='s') sage: [s1,s2]=W.simple_reflections() sage: b2(1,0).demazure_lusztig(s2*s1,v)==T2(T1(b2(1,0))) True """ if i in self.parent().space().index_set(): - rho = self.parent().space().from_vector_notation(self.parent().space().rho(), style="coroots") + rho = self.parent().space().from_vector_notation(self.parent().space().rho(), style='coroots') inv = self.scale(-1) return (-inv.shift(-rho).demazure([i]).shift(rho) + v * inv.demazure([i])).scale(-1) elif isinstance(i, list): diff --git a/src/sage/combinat/root_system/weyl_group.py b/src/sage/combinat/root_system/weyl_group.py index ab57e910d55..92ecf0ee33b 100644 --- a/src/sage/combinat/root_system/weyl_group.py +++ b/src/sage/combinat/root_system/weyl_group.py @@ -79,7 +79,7 @@ def WeylGroup(x, prefix=None, implementation='matrix'): - ``implementation`` -- one of the following: * ``'matrix'`` -- as matrices acting on a root system - * ``"permutation"`` -- as a permutation group acting on the roots + * ``'permutation'`` -- as a permutation group acting on the roots EXAMPLES: @@ -122,7 +122,7 @@ def WeylGroup(x, prefix=None, implementation='matrix'): :: - sage: W=WeylGroup("C3",prefix="s") + sage: W=WeylGroup("C3",prefix='s') sage: [s1,s2,s3]=W.simple_reflections() # lets Sage parse its own output sage: s2*s1*s2*s3 s1*s2*s3*s1 @@ -346,7 +346,6 @@ def simple_reflections(self): True sage: type(w) == W.element_class True - """ return self.domain().simple_reflections().map(self.from_morphism) @@ -368,13 +367,13 @@ def reflections(self): EXAMPLES:: - sage: W = WeylGroup("B2", prefix="s") + sage: W = WeylGroup("B2", prefix='s') sage: refdict = W.reflections(); refdict Finite family {(1, -1): s1, (0, 1): s2, (1, 1): s2*s1*s2, (1, 0): s1*s2*s1} sage: [r+refdict[r].action(r) for r in refdict.keys()] [(0, 0), (0, 0), (0, 0), (0, 0)] - sage: W = WeylGroup(['A',2,1], prefix="s") + sage: W = WeylGroup(['A',2,1], prefix='s') sage: W.reflections() Lazy family (real root to reflection(i))_{i in Positive real roots of type ['A', 2, 1]} @@ -476,7 +475,7 @@ def domain(self): def simple_reflection(self, i): """ - Return the `i^{th}` simple reflection. + Return the `i`-th simple reflection. EXAMPLES:: @@ -575,7 +574,7 @@ def classical(self): class ClassicalWeylSubgroup(WeylGroup_gens): """ - A class for Classical Weyl Subgroup of an affine Weyl Group + A class for Classical Weyl Subgroup of an affine Weyl Group. EXAMPLES:: @@ -656,7 +655,7 @@ def __repr__(self): type=False) return "Parabolic Subgroup of the Weyl Group of type %s (as a matrix group acting on the %s)" % (self.domain().cartan_type(), domain) - def weyl_group(self, prefix="hereditary"): + def weyl_group(self, prefix='hereditary'): """ Return the Weyl group associated to the parabolic subgroup. @@ -675,7 +674,7 @@ def weyl_group(self, prefix="hereditary"): def _test_is_finite(self, **options): """ - Tests some internal invariants + Test some internal invariants. EXAMPLES:: @@ -736,7 +735,7 @@ def _repr_(self): """ EXAMPLES:: - sage: W = WeylGroup(['A',2,1], prefix="s") + sage: W = WeylGroup(['A',2,1], prefix='s') sage: [s0,s1,s2] = W.simple_reflections() sage: s0*s1 s0*s1 @@ -764,7 +763,7 @@ def _latex_(self): EXAMPLES:: - sage: W = WeylGroup(['A',2,1], prefix="s") + sage: W = WeylGroup(['A',2,1], prefix='s') sage: [s0,s1,s2] = W.simple_reflections() sage: latex(s0*s1) # indirect doctest s_{0}s_{1} @@ -824,7 +823,7 @@ def _richcmp_(self, other, op): def action(self, v): """ - Return the action of self on the vector v. + Return the action of ``self`` on the vector `v`. EXAMPLES:: @@ -856,12 +855,12 @@ def action(self, v): # Descents # ####################################################################### - def has_descent(self, i, positive=False, side="right") -> bool: + def has_descent(self, i, positive=False, side='right') -> bool: """ Test if ``self`` has a descent at position ``i``. An element `w` has a descent in position `i` if `w` is - on the strict negative side of the `i^{th}` simple reflection + on the strict negative side of the `i`-th simple reflection hyperplane. If ``positive`` is ``True``, tests if it is on the strict @@ -946,7 +945,7 @@ def has_left_descent(self, i): sage: [(s[3]*s[2]).has_left_descent(i) for i in W.domain().index_set()] [False, False, True] """ - return self.has_descent(i, side="left") + return self.has_descent(i, side='left') def has_right_descent(self, i): """ @@ -967,9 +966,9 @@ def has_right_descent(self, i): sage: [(s[3]*s[2]).has_right_descent(i) for i in W.domain().index_set()] [False, True, False] """ - return self.has_descent(i, side="right") + return self.has_descent(i, side='right') - def apply_simple_reflection(self, i, side="right"): + def apply_simple_reflection(self, i, side='right'): s = self.parent().simple_reflections() if side == "right": return self * s[i] @@ -1015,8 +1014,8 @@ def __classcall__(cls, cartan_type, prefix=None): EXAMPLES:: - sage: W1 = WeylGroup(['B',2], implementation="permutation") - sage: W2 = WeylGroup(CartanType(['B',2]), implementation="permutation") + sage: W1 = WeylGroup(['B',2], implementation='permutation') + sage: W2 = WeylGroup(CartanType(['B',2]), implementation='permutation') sage: W1 is W2 True """ @@ -1028,7 +1027,7 @@ def __init__(self, cartan_type, prefix): EXAMPLES:: - sage: W = WeylGroup(['F',4], implementation="permutation") + sage: W = WeylGroup(['F',4], implementation='permutation') sage: TestSuite(W).run() """ self._cartan_type = cartan_type @@ -1046,20 +1045,20 @@ def __init__(self, cartan_type, prefix): cat = (cat, PermutationGroups().Finite()) PermutationGroup_generic.__init__(self, gens=p, canonicalize=False, category=cat) - def iteration(self, algorithm="breadth", tracking_words=True): + def iteration(self, algorithm='breadth', tracking_words=True): r""" Return an iterator going through all elements in ``self``. INPUT: - - ``algorithm`` (default: ``'breadth'``) -- must be one of + - ``algorithm`` -- (default: ``'breadth'``) must be one of the following: * ``'breadth'`` -- iterate over in a linear extension of the weak order * ``'depth'`` -- iterate by a depth-first-search - - ``tracking_words`` (default: ``True``) -- whether or not to keep + - ``tracking_words`` -- boolean (default: ``True``); whether or not to keep track of the reduced words and store them in ``_reduced_word`` .. NOTE:: @@ -1069,7 +1068,7 @@ def iteration(self, algorithm="breadth", tracking_words=True): EXAMPLES:: - sage: W = WeylGroup(["B",2], implementation="permutation") + sage: W = WeylGroup(["B",2], implementation='permutation') sage: for w in W.iteration("breadth",True): ....: print("%s %s"%(w, w._reduced_word)) @@ -1104,7 +1103,7 @@ def __iter__(self): EXAMPLES:: - sage: W = WeylGroup(["B",2], implementation="permutation") + sage: W = WeylGroup(["B",2], implementation='permutation') sage: for w in W: print("%s %s"%(w, w._reduced_word)) () [] (1,3)(2,6)(5,7) [1] @@ -1115,7 +1114,7 @@ def __iter__(self): (1,7)(3,5)(4,8) [0, 1, 0] (1,5)(2,6)(3,7)(4,8) [0, 1, 0, 1] """ - return self.iteration(algorithm="breadth", tracking_words=True) + return self.iteration(algorithm='breadth', tracking_words=True) def _coerce_map_from_(self, P): """ @@ -1124,7 +1123,7 @@ def _coerce_map_from_(self, P): EXAMPLES:: - sage: W = WeylGroup(["B",4], implementation="permutation") + sage: W = WeylGroup(["B",4], implementation='permutation') sage: W2 = WeylGroup(["B",4]) sage: W._coerce_map_from_(W2) True @@ -1134,7 +1133,7 @@ def _coerce_map_from_(self, P): sage: W4 = CoxeterGroup(["B",4]) sage: W.has_coerce_map_from(W4) False - sage: W5 = WeylGroup(["C",4], implementation="permutation") + sage: W5 = WeylGroup(["C",4], implementation='permutation') sage: W.has_coerce_map_from(W5) False """ @@ -1147,7 +1146,7 @@ def rank(self): EXAMPLES:: - sage: W = WeylGroup(['A',4], implementation="permutation") + sage: W = WeylGroup(['A',4], implementation='permutation') sage: W.rank() 4 """ @@ -1159,7 +1158,7 @@ def simple_reflection(self, i): EXAMPLES:: - sage: W = WeylGroup(['A',4], implementation="permutation") + sage: W = WeylGroup(['A',4], implementation='permutation') sage: W.simple_reflection(1) (1,11)(2,5)(6,8)(9,10)(12,15)(16,18)(19,20) sage: W.simple_reflections() @@ -1177,7 +1176,7 @@ def simple_roots(self): EXAMPLES:: - sage: W = WeylGroup(['A',4], implementation="permutation") + sage: W = WeylGroup(['A',4], implementation='permutation') sage: W.simple_roots() Finite family {1: (1, 0, 0, 0), 2: (0, 1, 0, 0), 3: (0, 0, 1, 0), 4: (0, 0, 0, 1)} @@ -1197,7 +1196,7 @@ def index_set(self): EXAMPLES:: - sage: W = WeylGroup(['A',4], implementation="permutation") + sage: W = WeylGroup(['A',4], implementation='permutation') sage: W.index_set() (1, 2, 3, 4) """ @@ -1210,7 +1209,7 @@ def reflection_index_set(self): EXAMPLES:: - sage: W = WeylGroup(['A',3], implementation="permutation") + sage: W = WeylGroup(['A',3], implementation='permutation') sage: W.reflection_index_set() (1, 2, 3, 4, 5, 6) """ @@ -1222,7 +1221,7 @@ def cartan_type(self): EXAMPLES:: - sage: W = WeylGroup(['A',4], implementation="permutation") + sage: W = WeylGroup(['A',4], implementation='permutation') sage: W.cartan_type() ['A', 4] """ @@ -1235,7 +1234,7 @@ def roots(self): EXAMPLES:: - sage: W = WeylGroup(['G',2], implementation="permutation") + sage: W = WeylGroup(['G',2], implementation='permutation') sage: W.roots() ((1, 0), (0, 1), @@ -1263,7 +1262,7 @@ def positive_roots(self): EXAMPLES:: - sage: W = WeylGroup(['C',3], implementation="permutation") + sage: W = WeylGroup(['C',3], implementation='permutation') sage: W.positive_roots() ((1, 0, 0), (0, 1, 0), @@ -1284,7 +1283,7 @@ def number_of_reflections(self): EXAMPLES:: - sage: W = WeylGroup(['D',4], implementation="permutation") + sage: W = WeylGroup(['D',4], implementation='permutation') sage: W.number_of_reflections() 12 """ @@ -1297,7 +1296,7 @@ def distinguished_reflections(self): EXAMPLES:: - sage: W = WeylGroup(['B',2], implementation="permutation") + sage: W = WeylGroup(['B',2], implementation='permutation') sage: W.distinguished_reflections() Finite family {1: (1,5)(2,4)(6,8), 2: (1,3)(2,6)(5,7), 3: (2,8)(3,7)(4,6), 4: (1,7)(3,5)(4,8)} @@ -1322,7 +1321,7 @@ def simple_root_index(self, i): EXAMPLES:: - sage: W = WeylGroup(['A',3], implementation="permutation") + sage: W = WeylGroup(['A',3], implementation='permutation') sage: [W.simple_root_index(i) for i in W.index_set()] [0, 1, 2] """ @@ -1333,11 +1332,11 @@ def _repr_(self): """ EXAMPLES:: - sage: W = WeylGroup(['A',3], prefix="s", implementation="permutation") + sage: W = WeylGroup(['A',3], prefix='s', implementation='permutation') sage: [s1,s2,s3] = W.simple_reflections() sage: s1*s2 s1*s2 - sage: W = WeylGroup(['A',3], implementation="permutation") + sage: W = WeylGroup(['A',3], implementation='permutation') sage: [s1,s2,s3] = W.simple_reflections() sage: s1*s2 (1,10,2)(3,5,6)(4,8,7)(9,11,12) @@ -1354,11 +1353,11 @@ def _latex_(self): """ EXAMPLES:: - sage: W = WeylGroup(['A',3], prefix="s", implementation="permutation") + sage: W = WeylGroup(['A',3], prefix='s', implementation='permutation') sage: [s1,s2,s3] = W.simple_reflections() sage: s1*s2 s1*s2 - sage: W = WeylGroup(['A',3], implementation="permutation") + sage: W = WeylGroup(['A',3], implementation='permutation') sage: [s1,s2,s3] = W.simple_reflections() sage: s1*s2 (1,10,2)(3,5,6)(4,8,7)(9,11,12) diff --git a/src/sage/combinat/rooted_tree.py b/src/sage/combinat/rooted_tree.py index 74aeeff0bba..0ced874b74d 100644 --- a/src/sage/combinat/rooted_tree.py +++ b/src/sage/combinat/rooted_tree.py @@ -425,11 +425,11 @@ def single_graft(self, x, grafting_function, path_prefix=()): INPUT: - - `x` -- a rooted tree + - ``x`` -- a rooted tree - - ``grafting_function`` -- a list of paths in ``self`` + - ``grafting_function`` -- list of paths in ``self`` - - ``path_prefix`` -- optional tuple (default ``()``) + - ``path_prefix`` -- tuple (default: ``()``) The ``path_prefix`` argument is only used for internal recursion. @@ -467,7 +467,7 @@ class RootedTrees(UniqueRepresentation, Parent): INPUT: - - ``size`` -- (optional) an integer + - ``size`` -- integer (optional) OUTPUT: @@ -808,10 +808,10 @@ class LabelledRootedTree(AbstractLabelledClonableTree, RootedTree): INPUT: - - ``children`` -- a list or tuple or more generally any iterable + - ``children`` -- list or tuple or more generally any iterable of trees or objects convertible to trees - - ``label`` -- any hashable Sage object (default is ``None``) + - ``label`` -- any hashable Sage object (default: ``None``) .. NOTE:: @@ -1042,7 +1042,7 @@ def _an_element_(self): t = LT([], label=3) t1 = LT([t, t], label=42) t2 = LT([[]], label=5) - return LT([t, t1, t2], label="alpha") + return LT([t, t1, t2], label='alpha') def unlabelled_trees(self): """ diff --git a/src/sage/combinat/rsk.py b/src/sage/combinat/rsk.py index de28f0e6db8..5e276d5ebcf 100644 --- a/src/sage/combinat/rsk.py +++ b/src/sage/combinat/rsk.py @@ -222,11 +222,10 @@ def to_pairs(self, obj1=None, obj2=None, check=True): - ``obj1``, ``obj2`` -- anything representing a biword (see the doc of :meth:`forward_rule` for the - encodings accepted). + encodings accepted) - - ``check`` -- (default: ``True``) whether to check - that ``obj1`` and ``obj2`` actually define a valid - biword. + - ``check`` -- boolean (default: ``True``); whether to check that + ``obj1`` and ``obj2`` actually define a valid biword EXAMPLES:: @@ -304,11 +303,11 @@ def forward_rule(self, obj1, obj2, check_standard=False, check=True): entries and bottom entries in the biword (in this case, ``obj2`` is ``None``) - - ``check_standard`` -- (default: ``False``) check if either of the - resulting tableaux is a standard tableau, and if so, typecast it - as such + - ``check_standard`` -- boolean (default: ``False``); check if either + of the resulting tableaux is a standard tableau, and if so, typecast + it as such - - ``check`` -- (default: ``True``) whether to check + - ``check`` -- boolean (default: ``True``); whether to check that ``obj1`` and ``obj2`` actually define a valid biword @@ -348,7 +347,7 @@ def backward_rule(self, p, q, output): INPUT: - - ``p``, ``q`` -- two tableaux of the same shape. + - ``p``, ``q`` -- two tableaux of the same shape - ``output`` -- (default: ``'array'``) if ``q`` is semi-standard: @@ -893,9 +892,9 @@ def forward_rule(self, obj1, obj2, check_standard=False): case, ``obj2`` is ``None``; the top row of the biword is understood to be `(1, 2, \ldots, n)` by default) - - ``check_standard`` -- (default: ``False``) check if either of the - resulting tableaux is a standard tableau, and if so, typecast it - as such + - ``check_standard`` -- boolean (default: ``False``); check if either + of the resulting tableaux is a standard tableau, and if so, typecast + it as such EXAMPLES:: @@ -954,7 +953,7 @@ def backward_rule(self, p, q, output): - ``p``, ``q`` -- two tableaux of the same shape - - ``output`` -- (default: ``'array'``) if ``q`` is semi-standard: + - ``output`` -- (default: ``'array'``) if ``q`` is semi-standard: - ``'array'`` -- as a two-line array (i.e. generalized permutation or biword) @@ -1330,7 +1329,7 @@ def to_pairs(self, obj1=None, obj2=None, check=True): (see the doc of :meth:`forward_rule` for the encodings accepted) - - ``check`` -- (default: ``True``) whether to check + - ``check`` -- boolean (default: ``True``); whether to check that ``obj1`` and ``obj2`` actually define a valid strict biword @@ -1713,7 +1712,7 @@ def to_pairs(self, obj1=None, obj2=None, check=True): cobiword (see the doc of :meth:`forward_rule` for the encodings accepted) - - ``check`` -- (default: ``True``) whether to check + - ``check`` -- boolean (default: ``True``); whether to check that ``obj1`` and ``obj2`` actually define a valid strict cobiword @@ -2033,7 +2032,7 @@ def to_pairs(self, obj1=None, obj2=None, check=True): (see the doc of :meth:`forward_rule` for the encodings accepted) - - ``check`` -- (default: ``True``) whether to check + - ``check`` -- boolean (default: ``True``); whether to check that ``obj1`` and ``obj2`` actually define a valid restricted super biword @@ -2178,11 +2177,11 @@ def forward_rule(self, obj1, obj2, check_standard=False, check=True): entries and bottom entries in the biword (in this case, ``obj2`` is ``None``) - - ``check_standard`` -- (default: ``False``) check if either of - the resulting tableaux is a standard super tableau, and if so, + - ``check_standard`` -- boolean (default: ``False``); check if either + of the resulting tableaux is a standard super tableau, and if so, typecast it as such - - ``check`` -- (default: ``True``) whether to check + - ``check`` -- boolean (default: ``True``); whether to check that ``obj1`` and ``obj2`` actually define a valid restricted super biword @@ -2679,10 +2678,10 @@ def forward_rule(self, obj1, obj2=None, check_braid=True): understood to be the indices of the factors for each letter in this biword. - - ``check_braid`` -- (default: ``True``) indicator to validate that - input is associated to a fully commutative word in the 0-Hecke monoid, - validation is performed if set to ``True``; otherwise, this validation - is ignored. + - ``check_braid`` -- boolean (default: ``True``); indicator to validate + that input is associated to a fully commutative word in the 0-Hecke + monoid, validation is performed if set to ``True``. Οtherwise, this + validation is ignored. EXAMPLES:: @@ -3071,7 +3070,7 @@ def RSK(obj1=None, obj2=None, insertion=InsertionRules.RSK, check_standard=False - ``RSK.rules.EG`` (or ``'EG'``) -- Edelman-Greene insertion (only for reduced words of permutations/elements of a type `A` Coxeter group) (:class:`~sage.combinat.rsk.RuleEG`) - - ``RSK.rules.Hecke`` (or ``'hecke'``) -- Hecke insertion (only + - ``RSK.rules.Hecke`` -- (or ``'hecke'``) Hecke insertion (only guaranteed for generalized permutations whose top row is strictly increasing) (:class:`~sage.combinat.rsk.RuleHecke`) - ``RSK.rules.dualRSK`` (or ``'dualRSK'``) -- Dual RSK insertion @@ -3084,8 +3083,8 @@ def RSK(obj1=None, obj2=None, insertion=InsertionRules.RSK, check_standard=False fully commutative words in the 0-Hecke monoid) (:class:`~sage.combinat.rsk.RuleStar`) - - ``check_standard`` -- (default: ``False``) check if either of the - resulting tableaux is a standard tableau, and if so, typecast it + - ``check_standard`` -- boolean (default: ``False``); check if either of + the resulting tableaux is a standard tableau, and if so, typecast it as such For precise information about constraints on the input and output, @@ -3153,7 +3152,6 @@ def RSK(obj1=None, obj2=None, insertion=InsertionRules.RSK, check_standard=False [[], []] sage: RSK(Word([]), insertion=RSK.rules.Hecke) [[], []] - """ if isinstance(insertion, str): if insertion == 'RSK': diff --git a/src/sage/combinat/schubert_polynomial.py b/src/sage/combinat/schubert_polynomial.py index 63fd2a9065e..efd11f1e0f3 100644 --- a/src/sage/combinat/schubert_polynomial.py +++ b/src/sage/combinat/schubert_polynomial.py @@ -158,7 +158,7 @@ def expand(self): p = R(p) return p - def divided_difference(self, i, algorithm="sage"): + def divided_difference(self, i, algorithm='sage'): r""" Return the ``i``-th divided difference operator, applied to ``self``. diff --git a/src/sage/combinat/set_partition.py b/src/sage/combinat/set_partition.py index 5bf9e93d1ed..092e2f9dbb7 100644 --- a/src/sage/combinat/set_partition.py +++ b/src/sage/combinat/set_partition.py @@ -487,11 +487,9 @@ def conjugate(self): INPUT: - - ``self`` -- a set partition of an ordered set + - ``self`` -- set partition of an ordered set - OUTPUT: - - a set partition + OUTPUT: a set partition EXAMPLES:: @@ -652,7 +650,7 @@ def check(self): def set_latex_options(self, **kwargs): r""" - Set the latex options for use in the ``_latex_`` function + Set the latex options for use in the ``_latex_`` function. - ``tikz_scale`` -- (default: 1) scale for use with tikz package @@ -662,14 +660,14 @@ def set_latex_options(self, **kwargs): - ``color`` -- (default: ``'black'``) the arc colors - - ``fill`` -- (default: ``False``) if ``True`` then fills ``color``, - else you can pass in a color to alter the fill color - + - ``fill`` -- boolean (default: ``False``); if ``True`` then fills + ``color``, else you can pass in a color to alter the fill color - *only works with cyclic plot* - - ``show_labels`` -- (default: ``True``) if ``True`` shows labels - - *only works with plots* + - ``show_labels`` -- boolean (default: ``True``); if ``True`` shows + labels (*only works with plots*) - - ``radius`` -- (default: ``"1cm"``) radius of circle for cyclic + - ``radius`` -- (default: ``'1cm'``) radius of circle for cyclic plot - *only works with cyclic plot* - ``angle`` -- (default: 0) angle for linear plot @@ -945,15 +943,15 @@ def to_permutation(self): """ return Permutation(tuple(map(tuple, self.standard_form()))) - def to_restricted_growth_word(self, bijection="blocks"): + def to_restricted_growth_word(self, bijection='blocks'): r""" Convert a set partition of `\{1,...,n\}` to a word of length `n` - with letters in the non-negative integers such that each + with letters in the nonnegative integers such that each letter is at most 1 larger than all the letters before. INPUT: - - ``bijection`` (default: ``blocks``) -- defines the map from + - ``bijection`` -- (default: ``blocks``) defines the map from set partitions to restricted growth functions. These are currently: @@ -961,9 +959,7 @@ def to_restricted_growth_word(self, bijection="blocks"): - ``intertwining``: :meth:`to_restricted_growth_word_intertwining`. - OUTPUT: - - A restricted growth word. + OUTPUT: a restricted growth word .. SEEALSO:: @@ -1009,16 +1005,14 @@ def to_restricted_growth_word(self, bijection="blocks"): def to_restricted_growth_word_blocks(self): r""" Convert a set partition of `\{1,...,n\}` to a word of length `n` - with letters in the non-negative integers such that each + with letters in the nonnegative integers such that each letter is at most 1 larger than all the letters before. The word is obtained by sorting the blocks by their minimal element and setting the letters at the positions of the elements in the `i`-th block to `i`. - OUTPUT: - - a restricted growth word. + OUTPUT: a restricted growth word .. SEEALSO:: @@ -1041,7 +1035,7 @@ def to_restricted_growth_word_blocks(self): def to_restricted_growth_word_intertwining(self): r""" Convert a set partition of `\{1,...,n\}` to a word of length `n` - with letters in the non-negative integers such that each + with letters in the nonnegative integers such that each letter is at most 1 larger than all the letters before. The `i`-th letter of the word is the numbers of crossings of @@ -1049,9 +1043,7 @@ def to_restricted_growth_word_intertwining(self): `i`, with arcs (or half-arcs) beginning at a smaller element and ending at a larger element. - OUTPUT: - - a restricted growth word. + OUTPUT: a restricted growth word .. SEEALSO:: @@ -1098,7 +1090,7 @@ def closers(self): """ return sorted([max(B) for B in self]) - def to_rook_placement(self, bijection="arcs"): + def to_rook_placement(self, bijection='arcs'): r""" Return a set of pairs defining a placement of non-attacking rooks on a triangular board. @@ -1108,7 +1100,7 @@ def to_rook_placement(self, bijection="arcs"): INPUT: - - ``bijection`` (default: ``arcs``) -- defines the bijection + - ``bijection`` -- (default: ``arcs``) defines the bijection from set partitions to rook placements. These are currently: @@ -1160,9 +1152,7 @@ def to_rook_placement_gamma(self): rook, which are not yet attacked by another rook, equals the index of the block to which `n+1-i` belongs. - OUTPUT: - - A list of coordinates. + OUTPUT: list of coordinates .. SEEALSO:: @@ -1236,9 +1226,7 @@ def to_rook_placement_rho(self): One can show that the precisely those rows which correspond to openers of the set partition remain empty. - OUTPUT: - - A list of coordinates. + OUTPUT: list of coordinates .. SEEALSO:: @@ -1297,9 +1285,7 @@ def to_rook_placement_psi(self): Return the rook diagram obtained by placing rooks according to Yip's bijection psi. - OUTPUT: - - A list of coordinates. + OUTPUT: list of coordinates .. SEEALSO:: @@ -2117,7 +2103,7 @@ def _element_constructor_(self, s, check=True): INPUT: - - ``s`` -- a set of sets + - ``s`` -- set of sets EXAMPLES:: @@ -2139,17 +2125,17 @@ def _element_constructor_(self, s, check=True): Element = SetPartition - def from_restricted_growth_word(self, w, bijection="blocks"): + def from_restricted_growth_word(self, w, bijection='blocks'): r""" - Convert a word of length `n` with letters in the non-negative + Convert a word of length `n` with letters in the nonnegative integers such that each letter is at most 1 larger than all the letters before to a set partition of `\{1,...,n\}`. INPUT: - - ``w`` -- a restricted growth word. + - ``w`` -- a restricted growth word - - ``bijection`` (default: ``blocks``) -- defines the map from + - ``bijection`` -- (default: ``blocks``) defines the map from restricted growth functions to set partitions. These are currently: @@ -2157,9 +2143,7 @@ def from_restricted_growth_word(self, w, bijection="blocks"): - ``intertwining``: :meth:`from_restricted_growth_word_intertwining`. - OUTPUT: - - A set partition. + OUTPUT: a set partition .. SEEALSO:: @@ -2184,7 +2168,7 @@ def from_restricted_growth_word(self, w, bijection="blocks"): def from_restricted_growth_word_blocks(self, w): r""" - Convert a word of length `n` with letters in the non-negative + Convert a word of length `n` with letters in the nonnegative integers such that each letter is at most 1 larger than all the letters before to a set partition of `\{1,...,n\}`. @@ -2193,11 +2177,9 @@ def from_restricted_growth_word_blocks(self, w): INPUT: - - ``w`` -- a restricted growth word. + - ``w`` -- a restricted growth word - OUTPUT: - - A set partition. + OUTPUT: a set partition .. SEEALSO:: @@ -2219,7 +2201,7 @@ def from_restricted_growth_word_blocks(self, w): def from_restricted_growth_word_intertwining(self, w): r""" - Convert a word of length `n` with letters in the non-negative + Convert a word of length `n` with letters in the nonnegative integers such that each letter is at most 1 larger than all the letters before to a set partition of `\{1,...,n\}`. @@ -2230,11 +2212,9 @@ def from_restricted_growth_word_intertwining(self, w): INPUT: - - ``w`` -- a restricted growth word. - - OUTPUT: + - ``w`` -- a restricted growth word - A set partition. + OUTPUT: a set partition .. SEEALSO:: @@ -2264,7 +2244,7 @@ def from_restricted_growth_word_intertwining(self, w): C = [i + 1] + C return self.element_class(self, R) - def from_rook_placement(self, rooks, bijection="arcs", n=None): + def from_rook_placement(self, rooks, bijection='arcs', n=None): r""" Convert a rook placement of the triangular grid to a set partition of `\{1,...,n\}`. @@ -2275,10 +2255,10 @@ def from_rook_placement(self, rooks, bijection="arcs", n=None): INPUT: - - ``rooks`` -- a list of pairs `(i,j)` satisfying - `0 < i < j < n+1`. + - ``rooks`` -- list of pairs `(i,j)` satisfying + `0 < i < j < n+1` - - ``bijection`` (default: ``arcs``) -- defines the map from + - ``bijection`` -- (default: ``arcs``) defines the map from rook placements to set partitions. These are currently: - ``arcs``: :meth:`from_arcs`. @@ -2286,7 +2266,7 @@ def from_rook_placement(self, rooks, bijection="arcs", n=None): - ``rho``: :meth:`from_rook_placement_rho`. - ``psi``: :meth:`from_rook_placement_psi`. - - ``n`` -- (optional) the size of the ground set. + - ``n`` -- (optional) the size of the ground set .. SEEALSO:: @@ -2342,11 +2322,11 @@ def from_arcs(self, arcs, n): INPUT: - - ``n`` -- an integer specifying the size of the set - partition to be produced. + - ``n`` -- integer specifying the size of the set + partition to be produced - - ``arcs`` -- a list of pairs specifying which elements are - in the same block. + - ``arcs`` -- list of pairs specifying which elements are + in the same block .. SEEALSO:: @@ -2377,14 +2357,12 @@ def from_rook_placement_gamma(self, rooks, n): INPUT: - - ``n`` -- an integer specifying the size of the set - partition to be produced. + - ``n`` -- integer specifying the size of the set + partition to be produced - - ``rooks`` -- a list of pairs `(i,j)` such that `0 < i < j < n+1`. + - ``rooks`` -- list of pairs `(i,j)` such that `0 < i < j < n+1` - OUTPUT: - - A set partition. + OUTPUT: a set partition .. SEEALSO:: @@ -2433,14 +2411,12 @@ def from_rook_placement_rho(self, rooks, n): INPUT: - - ``n`` -- an integer specifying the size of the set - partition to be produced. - - - ``rooks`` -- a list of pairs `(i,j)` such that `0 < i < j < n+1`. + - ``n`` -- integer specifying the size of the set + partition to be produced - OUTPUT: + - ``rooks`` -- list of pairs `(i,j)` such that `0 < i < j < n+1` - A set partition. + OUTPUT: a set partition .. SEEALSO:: @@ -2499,15 +2475,12 @@ def from_rook_placement_psi(self, rooks, n): INPUT: - - ``n`` -- an integer specifying the size of the set - partition to be produced. - - - ``rooks`` -- a list of pairs `(i,j)` such that `0 < i < j < - n+1`. + - ``n`` -- integer specifying the size of the set + partition to be produced - OUTPUT: + - ``rooks`` -- list of pairs `(i,j)` such that `0 < i < j < n+1` - A set partition. + OUTPUT: a set partition .. SEEALSO:: @@ -3297,7 +3270,7 @@ def cyclic_permutations_of_set_partition(set_part): def cyclic_permutations_of_set_partition_iterator(set_part): """ - Iterates over all combinations of cyclic permutations of each cell + Iterate over all combinations of cyclic permutations of each cell of the set partition. AUTHORS: diff --git a/src/sage/combinat/set_partition_ordered.py b/src/sage/combinat/set_partition_ordered.py index 782b13df638..37faaec29be 100644 --- a/src/sage/combinat/set_partition_ordered.py +++ b/src/sage/combinat/set_partition_ordered.py @@ -330,7 +330,7 @@ def sum(osps): INPUT: - - ``osps`` -- a list (or iterable) of ordered set partitions + - ``osps`` -- list (or iterable) of ordered set partitions EXAMPLES:: @@ -938,7 +938,7 @@ def __classcall_private__(cls, s=None, c=None): return OrderedSetPartitions_all() if isinstance(s, (int, Integer)): if s < 0: - raise ValueError("s must be non-negative") + raise ValueError("s must be nonnegative") s = frozenset(range(1, s + 1)) else: s = frozenset(s) diff --git a/src/sage/combinat/sf/character.py b/src/sage/combinat/sf/character.py index 6fd2490ff11..36755b58f05 100644 --- a/src/sage/combinat/sf/character.py +++ b/src/sage/combinat/sf/character.py @@ -56,9 +56,7 @@ def _my_key(self, la): - ``la`` -- a partition - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -128,11 +126,9 @@ def _b_power_k(self, k): INPUT: - - ``k`` -- a positive integer - - OUTPUT: + - ``k`` -- positive integer - - an expression in the powersum basis of the symmetric functions + OUTPUT: an expression in the powersum basis of the symmetric functions EXAMPLES:: @@ -143,7 +139,6 @@ def _b_power_k(self, k): -1/2*p[1] + 1/2*p[2] sage: st._b_power_k(6) 1/6*p[1] - 1/6*p[2] - 1/6*p[3] + 1/6*p[6] - """ if k == 1: return self._p([1]) @@ -224,7 +219,7 @@ def __init__(self, Sym): """ SFA_generic.__init__(self, Sym, basis_name="induced trivial symmetric group character", - prefix="ht", graded=False) + prefix='ht', graded=False) self._other = Sym.complete() self._p = Sym.powersum() @@ -248,9 +243,7 @@ def _b_bar_power_k_r(self, k, r): - ``k``, ``r`` -- positive integers - OUTPUT: - - - an expression in the powersum basis of the symmetric functions + OUTPUT: an expression in the powersum basis of the symmetric functions EXAMPLES:: @@ -261,7 +254,6 @@ def _b_bar_power_k_r(self, k, r): 2*p[1] + p[1, 1] - 2*p[2] - 2*p[2, 1] + p[2, 2] sage: ht._b_bar_power_k_r(3,2) 3*p[1] + p[1, 1] - 3*p[3] - 2*p[3, 1] + p[3, 3] - """ p = self._p return k**r * p.prod( self._b_power_k(k)-j for j in range(r) ) @@ -288,9 +280,7 @@ def _b_bar_power_gamma(self, gamma): - ``gamma`` -- a partition - OUTPUT: - - - an expression in the powersum basis of the symmetric functions + OUTPUT: an expression in the powersum basis of the symmetric functions EXAMPLES:: @@ -301,7 +291,6 @@ def _b_bar_power_gamma(self, gamma): 2*p[1] - 3*p[1, 1] + p[1, 1, 1] sage: ht._b_bar_power_gamma(Partition([3,3,1])) 3*p[1, 1] + p[1, 1, 1] - 3*p[3, 1] - 2*p[3, 1, 1] + p[3, 3, 1] - """ return self._p.prod(self._b_bar_power_k_r(Integer(k), Integer(r)) for k, r in gamma.to_exp_dict().items()) @@ -326,9 +315,7 @@ def _self_to_power_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - an expression in the power sum basis + OUTPUT: an expression in the power sum basis EXAMPLES:: @@ -337,7 +324,6 @@ def _self_to_power_on_basis(self, lam): p[1] - 2*p[1, 1] + 1/2*p[1, 1, 1] + 1/2*p[2, 1] sage: ht._self_to_power_on_basis([1,1,1]) 2*p[1] - 3*p[1, 1] + p[1, 1, 1] - """ return self._p.sum( c*self._b_bar_power_gamma(ga) for (ga, c) in self._p(self._other(lam)) ) @@ -451,7 +437,7 @@ def __init__(self, Sym): """ SFA_generic.__init__(self, Sym, basis_name="irreducible symmetric group character", - prefix="st", graded=False) + prefix='st', graded=False) self._other = Sym.Schur() self._p = Sym.powersum() @@ -475,9 +461,7 @@ def _b_power_k_r(self, k, r): - ``k``, ``r`` -- positive integers - OUTPUT: - - - an expression in the powersum basis of the symmetric functions + OUTPUT: an expression in the powersum basis of the symmetric functions EXAMPLES:: @@ -488,7 +472,6 @@ def _b_power_k_r(self, k, r): p[] + 4*p[1] + p[1, 1] - 4*p[2] - 2*p[2, 1] + p[2, 2] sage: st._b_power_k_r(3,2) p[] + 5*p[1] + p[1, 1] - 5*p[3] - 2*p[3, 1] + p[3, 3] - """ p = self._p return p.sum( (-1)**(r-j) * k**j * binomial(r,j) @@ -517,9 +500,7 @@ def _b_power_gamma(self, gamma): - ``gamma`` -- a partition - OUTPUT: - - - an expression in the powersum basis of the symmetric functions + OUTPUT: an expression in the powersum basis of the symmetric functions EXAMPLES:: @@ -530,7 +511,6 @@ def _b_power_gamma(self, gamma): -p[] + 8*p[1] - 6*p[1, 1] + p[1, 1, 1] sage: st._b_power_gamma(Partition([3,1])) p[] - p[1, 1] - p[3] + p[3, 1] - """ return self._p.prod(self._b_power_k_r(Integer(k), Integer(r)) for k, r in gamma.to_exp_dict().items()) @@ -557,9 +537,7 @@ def _self_to_power_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - an expression in the power sum basis + OUTPUT: an expression in the power sum basis EXAMPLES:: @@ -568,7 +546,6 @@ def _self_to_power_on_basis(self, lam): 3*p[1] - 2*p[1, 1] + 1/3*p[1, 1, 1] - 1/3*p[3] sage: st._self_to_power_on_basis([1,1]) p[] - p[1] + 1/2*p[1, 1] - 1/2*p[2] - """ return self._p.sum( c*self._b_power_gamma(ga) for (ga, c) in self._p(self._other(lam)) ) @@ -585,9 +562,7 @@ def _self_to_other_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - an expression in the Schur basis + OUTPUT: an expression in the Schur basis EXAMPLES:: diff --git a/src/sage/combinat/sf/dual.py b/src/sage/combinat/sf/dual.py index 207e411a2c6..ce0f9f6bd1c 100644 --- a/src/sage/combinat/sf/dual.py +++ b/src/sage/combinat/sf/dual.py @@ -27,7 +27,7 @@ class SymmetricFunctionAlgebra_dual(classical.SymmetricFunctionAlgebra_classical): @staticmethod - def __classcall__(cls, dual_basis, scalar, scalar_name="", basis_name=None, prefix=None): + def __classcall__(cls, dual_basis, scalar, scalar_name='', basis_name=None, prefix=None): """ Normalize the arguments. @@ -35,7 +35,7 @@ def __classcall__(cls, dual_basis, scalar, scalar_name="", basis_name=None, pref sage: w = SymmetricFunctions(QQ).w() sage: B1 = w.dual_basis() - sage: B2 = w.dual_basis(prefix="d_w") + sage: B2 = w.dual_basis(prefix='d_w') sage: B1 is B2 True """ @@ -51,7 +51,7 @@ def __init__(self, dual_basis, scalar, scalar_name, basis_name, prefix): - ``dual_basis`` -- a basis of the ring of symmetric functions - - ``scalar`` -- A function `z` on partitions which determines the + - ``scalar`` -- a function `z` on partitions which determines the scalar product on the power sum basis by `\langle p_{\mu}, p_{\mu} \rangle = z(\mu)`. (Independently on the function chosen, the power sum basis will always be orthogonal; the @@ -89,7 +89,7 @@ def __init__(self, dual_basis, scalar, scalar_name, basis_name, prefix): EXAMPLES:: sage: e = SymmetricFunctions(QQ).e() - sage: f = e.dual_basis(prefix="m", basis_name="Forgotten symmetric functions"); f + sage: f = e.dual_basis(prefix='m', basis_name="Forgotten symmetric functions"); f Symmetric Functions over Rational Field in the Forgotten symmetric functions basis sage: TestSuite(f).run(elements=[f[1,1]+2*f[2], f[1]+3*f[1,1]]) sage: TestSuite(f).run() # long time (11s on sage.math, 2011) @@ -135,7 +135,6 @@ def __init__(self, dual_basis, scalar, scalar_name, basis_name, prefix): sage: y = e[1, 1, 1, 1] - 2*e[2, 1, 1] + e[2, 2] sage: sorted(f.element_class(f, dual = y)) [([1, 1, 1, 1], 6), ([2, 1, 1], 2), ([2, 2], 1)] - """ self._dual_basis = dual_basis self._scalar = scalar @@ -193,9 +192,7 @@ def _dual_to_self(self, x): - ``x`` -- an element in the dual basis of ``self`` - OUTPUT: - - - returns ``x`` expressed in the basis ``self`` + OUTPUT: ``x`` expressed in the basis ``self`` EXAMPLES:: @@ -231,9 +228,7 @@ def _self_to_dual(self, x): - ``x`` -- an element of ``self`` - OUTPUT: - - - returns ``x`` expressed in the dual basis + OUTPUT: ``x`` expressed in the dual basis EXAMPLES:: @@ -257,7 +252,7 @@ def _self_to_dual(self, x): def _dual_basis_default(self): """ - Returns the default value for ``self.dual_basis()`` + Return the default value for ``self.dual_basis()``. This returns the basis ``self`` has been built from by duality. @@ -309,9 +304,7 @@ def _repr_(self): """ Representation of ``self``. - OUTPUT: - - - a string description of ``self`` + OUTPUT: string description of ``self`` EXAMPLES:: @@ -487,7 +480,7 @@ def _precompute(self, n): def transition_matrix(self, basis, n): r""" - Returns the transition matrix between the `n^{th}` homogeneous components + Return the transition matrix between the `n`-th homogeneous components of ``self`` and ``basis``. INPUT: @@ -547,9 +540,7 @@ def product(self, left, right): - ``left``, ``right`` -- elements of ``self`` - OUTPUT: - - - the product of ``left`` and ``right`` in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` in the basis ``self`` EXAMPLES:: @@ -580,7 +571,7 @@ class Element(classical.SymmetricFunctionAlgebra_classical.Element): - ``dictionary`` -- an internal dictionary for the monomials and coefficients of ``self`` - - ``dual`` -- self as an element of the dual basis. + - ``dual`` -- self as an element of the dual basis """ def __init__(self, A, dictionary=None, dual=None): @@ -714,9 +705,7 @@ def omega(self): :meth:`omega_involution` is a synonym for the :meth:`omega` method. - OUTPUT: - - - the result of applying omega to ``self`` + OUTPUT: the result of applying omega to ``self`` EXAMPLES:: @@ -742,9 +731,7 @@ def scalar(self, x): - ``x`` -- element of the symmetric functions - OUTPUT: - - - the scalar product between ``x`` and ``self`` + OUTPUT: the scalar product between ``x`` and ``self`` EXAMPLES:: @@ -765,9 +752,7 @@ def scalar_hl(self, x): - ``x`` -- element of the same dual basis as ``self`` - OUTPUT: - - - the Hall-Littlewood scalar product between ``x`` and ``self`` + OUTPUT: the Hall-Littlewood scalar product between ``x`` and ``self`` EXAMPLES:: @@ -788,9 +773,7 @@ def _add_(self, y): - ``y`` -- element of the same dual basis as ``self`` - OUTPUT: - - - the sum of ``self`` and ``y`` + OUTPUT: the sum of ``self`` and ``y`` EXAMPLES:: @@ -830,9 +813,7 @@ def _sub_(self, y): - ``y`` -- element of the same dual basis as ``self`` - OUTPUT: - - - the difference of ``self`` and ``y`` + OUTPUT: the difference of ``self`` and ``y`` EXAMPLES:: @@ -855,9 +836,7 @@ def _div_(self, y): - ``y`` -- element of base field - OUTPUT: - - - the element ``self`` divided by ``y`` + OUTPUT: the element ``self`` divided by ``y`` EXAMPLES:: @@ -875,9 +854,7 @@ def __invert__(self): Invert ``self`` (only possible if ``self`` is a scalar multiple of `1` and we are working over a field). - OUTPUT: - - - multiplicative inverse of ``self`` if possible + OUTPUT: multiplicative inverse of ``self`` if possible EXAMPLES:: @@ -904,7 +881,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion diff --git a/src/sage/combinat/sf/elementary.py b/src/sage/combinat/sf/elementary.py index f0942314323..f2905d818bd 100644 --- a/src/sage/combinat/sf/elementary.py +++ b/src/sage/combinat/sf/elementary.py @@ -54,7 +54,7 @@ def __init__(self, Sym): def _dual_basis_default(self): """ - Returns the default value for ``self.dual_basis()`` + Return the default value for ``self.dual_basis()``. This method returns the dual basis to the elementary basis with respect to the standard scalar product, that is the @@ -71,20 +71,18 @@ def _dual_basis_default(self): sage: e._dual_basis_default() is e.dual_basis() True """ - return self.dual_basis(scalar=None, prefix="f", basis_name="forgotten") + return self.dual_basis(scalar=None, prefix='f', basis_name='forgotten') def coproduct_on_generators(self, i): r""" - Returns the coproduct on ``self[i]``. + Return the coproduct on ``self[i]``. INPUT: - ``self`` -- an elementary basis of the symmetric functions - - ``i`` -- a nonnegative integer + - ``i`` -- nonnegative integer - OUTPUT: - - - returns the coproduct on the elementary generator `e(i)` + OUTPUT: the coproduct on the elementary generator `e(i)` EXAMPLES:: @@ -222,7 +220,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -277,7 +275,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -337,12 +335,12 @@ def principal_specialization(self, n=infinity, q=None): INPUT: - - ``n`` (default: ``infinity``) -- a nonnegative integer or + - ``n`` -- (default: ``infinity``) a nonnegative integer or ``infinity``, specifying whether to compute the principal specialization of order ``n`` or the stable principal specialization. - - ``q`` (default: ``None``) -- the value to use for `q`; the + - ``q`` -- (default: ``None``) the value to use for `q`; the default is to create a ring of polynomials in ``q`` (or a field of rational functions in ``q``) over the given coefficient ring. @@ -378,7 +376,6 @@ def principal_specialization(self, n=infinity, q=None): sage: e.zero().principal_specialization(3) 0 - """ from sage.combinat.q_analogues import q_binomial @@ -455,10 +452,10 @@ def exponential_specialization(self, t=None, q=1): INPUT: - - ``t`` (default: ``None``) -- the value to use for `t`; - the default is to create a ring of polynomials in ``t``. + - ``t`` -- (default: ``None``) the value to use for `t`. + The default is to create a ring of polynomials in `t`. - - ``q`` (default: `1`) -- the value to use for `q`. If + - ``q`` -- (default: `1`) the value to use for `q`. If ``q`` is ``None``, then a ring (or fraction field) of polynomials in ``q`` is created. @@ -476,7 +473,6 @@ def exponential_specialization(self, t=None, q=1): sage: e.zero().exponential_specialization() 0 - """ from sage.combinat.q_analogues import q_factorial diff --git a/src/sage/combinat/sf/hall_littlewood.py b/src/sage/combinat/sf/hall_littlewood.py index 8d656533166..c725d478749 100644 --- a/src/sage/combinat/sf/hall_littlewood.py +++ b/src/sage/combinat/sf/hall_littlewood.py @@ -64,11 +64,9 @@ class HallLittlewood(UniqueRepresentation): def __repr__(self): r""" - A string representing the family of Hall-Littlewood symmetric function bases + A string representing the family of Hall-Littlewood symmetric function bases. - OUTPUT: - - - a string representing the class + OUTPUT: string representing the class EXAMPLES:: @@ -113,17 +111,13 @@ def __init__(self, Sym, t): def symmetric_function_ring( self ): r""" - The ring of symmetric functions associated to the class of Hall-Littlewood - symmetric functions + Return the ring of symmetric functions associated to the class of + Hall-Littlewood symmetric functions. INPUT: - ``self`` -- a class of Hall-Littlewood symmetric function bases - OUTPUT: - - - returns the ring of symmetric functions - EXAMPLES:: sage: HL = SymmetricFunctions(FractionField(QQ['t'])).hall_littlewood() @@ -134,17 +128,13 @@ def symmetric_function_ring( self ): def base_ring( self ): r""" - Returns the base ring of the symmetric functions where the - Hall-Littlewood symmetric functions live + Return the base ring of the symmetric functions where the + Hall-Littlewood symmetric functions live. INPUT: - ``self`` -- a class of Hall-Littlewood symmetric function bases - OUTPUT: - - The base ring of the symmetric functions. - EXAMPLES:: sage: HL = SymmetricFunctions(QQ['t'].fraction_field()).hall_littlewood(t=1) @@ -163,9 +153,7 @@ def P(self): - ``self`` -- a class of Hall-Littlewood symmetric function bases - OUTPUT: - - The class of the Hall-Littlewood `P` basis. + OUTPUT: the class of the Hall-Littlewood `P` basis EXAMPLES:: @@ -316,7 +304,7 @@ def P(self): def Q(self): r""" - Returns the algebra of symmetric functions in Hall-Littlewood `Q` + Return the algebra of symmetric functions in Hall-Littlewood `Q` basis. This is the same as the `Q` basis in John Stembridge's SF examples file. @@ -327,9 +315,7 @@ def Q(self): - ``self`` -- a class of Hall-Littlewood symmetric function bases - OUTPUT: - - - returns the class of the Hall-Littlewood `Q` basis + OUTPUT: the class of the Hall-Littlewood `Q` basis EXAMPLES:: @@ -343,7 +329,7 @@ def Q(self): def Qp(self): r""" - Returns the algebra of symmetric functions in Hall-Littlewood `Q^\prime` (Qp) + Return the algebra of symmetric functions in Hall-Littlewood `Q^\prime` (Qp) basis. This is dual to the Hall-Littlewood `P` basis with respect to the standard scalar product. @@ -354,9 +340,7 @@ def Qp(self): - ``self`` -- a class of Hall-Littlewood symmetric function bases - OUTPUT: - - - returns the class of the Hall-Littlewood `Qp`-basis + OUTPUT: the class of the Hall-Littlewood `Qp`-basis EXAMPLES:: @@ -426,16 +410,14 @@ def construction(self): def _s_to_self(self, x): r""" - Isomorphism from the Schur basis into ``self`` + Isomorphism from the Schur basis into ``self``. INPUT: - ``self`` -- a Hall-Littlewood symmetric function basis - ``x`` -- an element of the Schur basis - OUTPUT: - - - an element of ``self`` equivalent to ``x`` + OUTPUT: an element of ``self`` equivalent to ``x`` EXAMPLES:: @@ -454,16 +436,14 @@ def _s_to_self(self, x): def _self_to_s(self, x): r""" - Isomorphism from ``self`` to the Schur basis + Isomorphism from ``self`` to the Schur basis. INPUT: - ``self`` -- a Hall-Littlewood symmetric function basis - ``x`` -- an element of the basis ``self`` - OUTPUT: - - - an element of the Schur basis equivalent to ``x`` + OUTPUT: an element of the Schur basis equivalent to ``x`` EXAMPLES:: @@ -483,14 +463,14 @@ def _self_to_s(self, x): def transition_matrix(self, basis, n): r""" - Returns the transitions matrix between ``self`` and ``basis`` for the + Return the transitions matrix between ``self`` and ``basis`` for the homogeneous component of degree ``n``. INPUT: - ``self`` -- a Hall-Littlewood symmetric function basis - ``basis`` -- another symmetric function basis - - ``n`` -- a non-negative integer representing the degree + - ``n`` -- nonnegative integer representing the degree OUTPUT: @@ -543,9 +523,7 @@ def product(self, left, right): - ``left`` -- an element of the basis ``self`` - ``right`` -- another symmetric function - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -566,15 +544,13 @@ def product(self, left, right): def hall_littlewood_family(self): r""" - The family of Hall-Littlewood bases associated to ``self`` + The family of Hall-Littlewood bases associated to ``self``. INPUT: - ``self`` -- a Hall-Littlewood symmetric function basis - OUTPUT: - - - returns the class of Hall-Littlewood bases + OUTPUT: the class of Hall-Littlewood bases EXAMPLES:: @@ -591,17 +567,15 @@ class Element(sfa.SymmetricFunctionAlgebra_generic.Element): def expand(self, n, alphabet='x'): r""" - Expands the symmetric function as a symmetric polynomial in ``n`` variables. + Expand the symmetric function as a symmetric polynomial in ``n`` variables. INPUT: - ``self`` -- an element of a Hall-Littlewood basis - - ``n`` -- a positive integer - - ``alphabet`` -- a string representing a variable name (default: 'x') - - OUTPUT: + - ``n`` -- positive integer + - ``alphabet`` -- string representing a variable name (default: ``'x'``) - - returns a symmetric polynomial of ``self`` in ``n`` variables + OUTPUT: a symmetric polynomial of ``self`` in ``n`` variables EXAMPLES:: @@ -625,7 +599,7 @@ def expand(self, n, alphabet='x'): def scalar(self, x, zee=None): r""" - Returns standard scalar product between ``self`` and ``x``. + Return standard scalar product between ``self`` and ``x``. This is the default implementation that converts both ``self`` and ``x`` into Schur functions and performs the scalar product that basis. @@ -638,9 +612,7 @@ def scalar(self, x, zee=None): - ``self`` -- an element of a Hall-Littlewood basis - ``x`` -- another symmetric element of the symmetric functions - OUTPUT: - - - returns the scalar product between ``self`` and ``x`` + OUTPUT: the scalar product between ``self`` and ``x`` EXAMPLES:: @@ -664,7 +636,7 @@ def scalar(self, x, zee=None): def scalar_hl(self, x, t=None): r""" - Returns the Hall-Littlewood (with parameter ``t``) scalar product + Return the Hall-Littlewood (with parameter ``t``) scalar product of ``self`` and ``x``. The Hall-Littlewood scalar product is defined in Macdonald's @@ -681,9 +653,7 @@ def scalar_hl(self, x, t=None): - ``t`` -- an optional parameter, if this parameter is not specified then the value of the ``t`` from the basis is used in the calculation - OUTPUT: - - - returns the Hall-Littlewood scalar product between ``self`` and ``x`` + OUTPUT: the Hall-Littlewood scalar product between ``self`` and ``x`` EXAMPLES:: @@ -724,7 +694,7 @@ class Element(HallLittlewood_generic.Element): def __init__(self, hall_littlewood): r""" - A class with methods for working with the Hall-Littlewood `P` basis + A class with methods for working with the Hall-Littlewood `P` basis. The `P` basis is calculated from the Schur basis using the functions in :meth:`sage.combinat.sf.kfpoly`. These functions calculate Kostka-Foulkes polynomials @@ -781,7 +751,7 @@ def _q_to_p_normalization(self, m): def _s_to_self_base(self, part): r""" - Returns a function which gives the coefficient of a partition + Return a function which gives the coefficient of a partition in the expansion of the Schur functions ``s(part)`` in the Hall-Littlewood `P` basis. @@ -813,7 +783,7 @@ def _s_to_self_base(self, part): def _s_cache(self, n): r""" - Computes the change of basis between the `P` polynomials and the + Compute the change of basis between the `P` polynomials and the Schur functions for partitions of size ``n``. Uses the fact that the transformation matrix is upper-triangular in @@ -895,7 +865,7 @@ def __init__(self, hall_littlewood): def _p_to_q_normalization(self, m): r""" - Returns the scalar coefficient on self(m) when converting from the + Return the scalar coefficient on self(m) when converting from the `Q` basis to the `P` basis. Note that this assumes that ``m`` is a Partition object. @@ -984,7 +954,7 @@ def __init__(self, hall_littlewood): def _to_s(self, part): r""" - Returns a function which gives the coefficient of a partition + Return a function which gives the coefficient of a partition in the Schur expansion of ``self(part)``. INPUT: @@ -1018,7 +988,7 @@ def _to_s(self, part): def _s_cache(self, n): r""" - Computes the change of basis between the `Q^\prime` polynomials and the + Compute the change of basis between the `Q^\prime` polynomials and the Schur functions for partitions of size ``n``. Uses the fact that the transformation matrix is lower-triangular in @@ -1027,7 +997,7 @@ def _s_cache(self, n): INPUT: - ``self`` -- an instance of the Hall-Littlewood `P` basis - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: diff --git a/src/sage/combinat/sf/hecke.py b/src/sage/combinat/sf/hecke.py index e0b7f965ba7..aec6860cdc5 100644 --- a/src/sage/combinat/sf/hecke.py +++ b/src/sage/combinat/sf/hecke.py @@ -176,7 +176,7 @@ def __init__(self, sym, q): self.q = q SymmetricFunctionAlgebra_multiplicative.__init__(self, sym, basis_name="Hecke character with q={}".format(self.q), - prefix="qbar") + prefix='qbar') self._p = sym.power() # temporary until Hom(GradedHopfAlgebrasWithBasis work better) @@ -206,11 +206,11 @@ def construction(self): def _p_to_qbar_on_generator(self, n): r""" - Convert `p_n` to ``self`` + Convert `p_n` to ``self``. INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -238,7 +238,7 @@ def _p_to_qbar_on_basis(self, mu): INPUT: - - ``mu`` -- a partition or a list of non-negative integers + - ``mu`` -- a partition or a list of nonnegative integers EXAMPLES:: @@ -260,7 +260,7 @@ def _qbar_to_p_on_generator(self, n): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -290,7 +290,7 @@ def _qbar_to_p_on_basis(self, mu): INPUT: - - ``mu`` -- a partition or a list of non-negative integers + - ``mu`` -- a partition or a list of nonnegative integers EXAMPLES:: diff --git a/src/sage/combinat/sf/homogeneous.py b/src/sage/combinat/sf/homogeneous.py index 29cf294ea80..fffc4a1873c 100644 --- a/src/sage/combinat/sf/homogeneous.py +++ b/src/sage/combinat/sf/homogeneous.py @@ -61,15 +61,15 @@ def _dual_basis_default(self): INPUT: - ``self`` -- a homogeneous basis of symmetric functions - - ``scalar`` -- optional input which specifies a function ``zee`` + - ``scalar`` -- (optional) input which specifies a function ``zee`` on partitions. The function ``zee`` determines the scalar product on the power sum basis with normalization `\langle p_\mu, p_\mu \rangle = \mathrm{zee}(mu)`. (default: uses standard ``zee`` function) - ``scalar_name`` -- specifies the name of the scalar function (optional) - - ``prefix`` -- optional input, specifies the prefix to be - used to display the basis. + - ``prefix`` -- (optional) input which specifies the prefix to be + used to display the basis OUTPUT: @@ -107,11 +107,9 @@ def coproduct_on_generators(self, i): INPUT: - ``self`` -- a homogeneous basis of symmetric functions - - ``i`` -- a nonnegative integer + - ``i`` -- nonnegative integer - OUTPUT: - - - the sum `\sum_{r=0}^i h_r \otimes h_{i-r}` + OUTPUT: the sum `\sum_{r=0}^i h_r \otimes h_{i-r}` EXAMPLES:: @@ -164,9 +162,7 @@ def omega(self): :meth:`omega_involution()` is a synonym for the :meth:`omega()` method. - OUTPUT: - - - the image of ``self`` under the omega automorphism + OUTPUT: the image of ``self`` under the omega automorphism EXAMPLES:: @@ -191,7 +187,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -253,12 +249,12 @@ def principal_specialization(self, n=infinity, q=None): INPUT: - - ``n`` (default: ``infinity``) -- a nonnegative integer or + - ``n`` -- (default: ``infinity``) a nonnegative integer or ``infinity``, specifying whether to compute the principal specialization of order ``n`` or the stable principal specialization. - - ``q`` (default: ``None``) -- the value to use for `q`; the + - ``q`` -- (default: ``None``) the value to use for `q`; the default is to create a ring of polynomials in ``q`` (or a field of rational functions in ``q``) over the given coefficient ring. @@ -289,7 +285,6 @@ def principal_specialization(self, n=infinity, q=None): sage: x = h.zero() sage: s = x.principal_specialization(3); s 0 - """ from sage.combinat.q_analogues import q_binomial @@ -363,12 +358,12 @@ def exponential_specialization(self, t=None, q=1): INPUT: - - ``t`` (default: ``None``) -- the value to use for `t`; - the default is to create a ring of polynomials in ``t``. + - ``t`` -- (default: ``None``) the value to use for `t`; + the default is to create a ring of polynomials in ``t`` - - ``q`` (default: `1`) -- the value to use for `q`. If + - ``q`` -- (default: `1`) the value to use for `q`; if ``q`` is ``None``, then a ring (or fraction field) of - polynomials in ``q`` is created. + polynomials in ``q`` is created EXAMPLES:: @@ -393,7 +388,6 @@ def exponential_specialization(self, t=None, q=1): sage: x = h.zero() sage: s = x.exponential_specialization(); s 0 - """ from sage.combinat.q_analogues import q_factorial diff --git a/src/sage/combinat/sf/jack.py b/src/sage/combinat/sf/jack.py index e70959f8dfc..f104af0d9d5 100644 --- a/src/sage/combinat/sf/jack.py +++ b/src/sage/combinat/sf/jack.py @@ -77,7 +77,7 @@ def __init__(self, Sym, t): - ``self`` -- the family of Jack symmetric function bases - ``Sym`` -- a ring of symmetric functions - - ``t`` -- an optional parameter (default : 't') + - ``t`` -- an optional parameter (default: ``'t'``) EXAMPLES:: @@ -95,15 +95,13 @@ def __init__(self, Sym, t): def __repr__(self): r""" - The string representation for the family of Jack symmetric function bases + The string representation for the family of Jack symmetric function bases. INPUT: - ``self`` -- the family of Jack symmetric function bases - OUTPUT: - - - returns the name of the family of bases + OUTPUT: the name of the family of bases EXAMPLES:: @@ -114,16 +112,14 @@ def __repr__(self): def base_ring( self ): r""" - Returns the base ring of the symmetric functions in which the - Jack symmetric functions live + Return the base ring of the symmetric functions in which the + Jack symmetric functions live. INPUT: - ``self`` -- the family of Jack symmetric function bases - OUTPUT: - - - the base ring of the symmetric functions ring of ``self`` + OUTPUT: the base ring of the symmetric functions ring of ``self`` EXAMPLES:: @@ -135,16 +131,14 @@ def base_ring( self ): def symmetric_function_ring( self ): r""" - Returns the base ring of the symmetric functions of the Jack symmetric + Return the base ring of the symmetric functions of the Jack symmetric function bases INPUT: - ``self`` -- the family of Jack symmetric function bases - OUTPUT: - - - the symmetric functions ring of ``self`` + OUTPUT: the symmetric functions ring of ``self`` EXAMPLES:: @@ -156,15 +150,13 @@ def symmetric_function_ring( self ): def P(self): r""" - Returns the algebra of Jack polynomials in the `P` basis. + Return the algebra of Jack polynomials in the `P` basis. INPUT: - ``self`` -- the family of Jack symmetric function bases - OUTPUT: - - - the `P` basis of the Jack symmetric functions + OUTPUT: the `P` basis of the Jack symmetric functions EXAMPLES:: @@ -261,15 +253,13 @@ def P(self): def Q(self): r""" - Returns the algebra of Jack polynomials in the `Q` basis. + Return the algebra of Jack polynomials in the `Q` basis. INPUT: - ``self`` -- the family of Jack symmetric function bases - OUTPUT: - - - the `Q` basis of the Jack symmetric functions + OUTPUT: the `Q` basis of the Jack symmetric functions EXAMPLES:: @@ -302,7 +292,7 @@ def Q(self): def J(self): r""" - Returns the algebra of Jack polynomials in the `J` basis. + Return the algebra of Jack polynomials in the `J` basis. INPUT: @@ -365,16 +355,14 @@ def J(self): def Qp(self): r""" - Returns the algebra of Jack polynomials in the `Qp`, which is dual to + Return the algebra of Jack polynomials in the `Qp`, which is dual to the `P` basis with respect to the standard scalar product. INPUT: - ``self`` -- the family of Jack symmetric function bases - OUTPUT: - - - the `Q'` basis of the Jack symmetric functions + OUTPUT: the `Q'` basis of the Jack symmetric functions EXAMPLES:: @@ -399,7 +387,7 @@ def Qp(self): def c1(part, t): r""" - Returns the `t`-Jack scalar product between ``J(part)`` and ``P(part)``. + Return the `t`-Jack scalar product between ``J(part)`` and ``P(part)``. INPUT: @@ -425,7 +413,7 @@ def c1(part, t): def c2(part, t): r""" - Returns the t-Jack scalar product between ``J(part)`` and ``Q(part)``. + Return the t-Jack scalar product between ``J(part)`` and ``Q(part)``. INPUT: @@ -462,9 +450,7 @@ def normalize_coefficients(self, c): - ``self`` -- a Jack basis of the symmetric functions - ``c`` -- a coefficient in the base ring of ``self`` - OUTPUT: - - - divide numerator and denominator by the greatest common divisor + OUTPUT: divide numerator and denominator by the greatest common divisor EXAMPLES:: @@ -510,7 +496,7 @@ def normalize_coefficients(self, c): class JackPolynomials_generic(sfa.SymmetricFunctionAlgebra_generic): def __init__(self, jack): r""" - A class of methods which are common to all Jack bases of the symmetric functions + A class of methods which are common to all Jack bases of the symmetric functions. INPUT: @@ -571,16 +557,14 @@ def construction(self): def _m_to_self(self, x): r""" - Isomorphism from the monomial basis into ``self`` + Isomorphism from the monomial basis into ``self``. INPUT: - ``self`` -- a Jack basis of the symmetric functions - ``x`` -- element of the monomial basis - OUTPUT: - - - an element of ``self`` equivalent to ``x`` + OUTPUT: an element of ``self`` equivalent to ``x`` EXAMPLES:: @@ -600,16 +584,14 @@ def _m_to_self(self, x): def _self_to_m(self, x): r""" - Isomorphism from self to the monomial basis + Isomorphism from ``self`` to the monomial basis. INPUT: - ``self`` -- a Jack basis of the symmetric functions - ``x`` -- an element of ``self`` - OUTPUT: - - - an element of the monomial basis equivalent to ``x`` + OUTPUT: an element of the monomial basis equivalent to ``x`` EXAMPLES:: @@ -629,7 +611,7 @@ def _self_to_m(self, x): def c1(self, part): r""" - Returns the `t`-Jack scalar product between ``J(part)`` and ``P(part)``. + Return the `t`-Jack scalar product between ``J(part)`` and ``P(part)``. INPUT: @@ -653,7 +635,7 @@ def c1(self, part): def c2(self, part): r""" - Returns the `t`-Jack scalar product between ``J(part)`` and ``Q(part)``. + Return the `t`-Jack scalar product between ``J(part)`` and ``Q(part)``. INPUT: @@ -679,16 +661,14 @@ def c2(self, part): def _normalize(self, x): r""" - Normalize the coefficients of ``x`` + Normalize the coefficients of ``x``. INPUT: - ``self`` -- a Jack basis of the symmetric functions - ``x`` -- an element of ``self`` - OUTPUT: - - - returns ``x`` with _normalize_coefficient applied to each of the coefficients + OUTPUT: ``x`` with _normalize_coefficient applied to each of the coefficients EXAMPLES:: @@ -706,17 +686,13 @@ def _normalize(self, x): def _normalize_morphism(self, category): r""" - Returns the normalize morphism + Return the normalize morphism. INPUT: - ``self`` -- a Jack basis of the symmetric functions - ``category`` -- a category - OUTPUT: - - - the normalized morphism - EXAMPLES:: sage: JP = SymmetricFunctions(FractionField(QQ['t'])).jack().P() @@ -751,9 +727,7 @@ def product(self, left, right): - ``self`` -- a Jack basis of the symmetric functions - ``left``, ``right`` -- symmetric function elements - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -772,16 +746,12 @@ def product(self, left, right): def jack_family(self): r""" - Returns the family of Jack bases associated to the basis ``self`` + Return the family of Jack bases associated to the basis ``self``. INPUT: - ``self`` -- a Jack basis of the symmetric functions - OUTPUT: - - - the family of Jack symmetric functions associated to ``self`` - EXAMPLES:: sage: JackP = SymmetricFunctions(QQ).jack(t=2).P() @@ -792,7 +762,7 @@ def jack_family(self): def coproduct_by_coercion(self, elt): r""" - Returns the coproduct of the element ``elt`` by coercion to the Schur basis. + Return the coproduct of the element ``elt`` by coercion to the Schur basis. INPUT: @@ -828,12 +798,10 @@ def scalar_jack(self, x, t=None): - ``self`` -- an element of a Jack basis of the symmetric functions - ``x`` -- an element of the symmetric functions - - ``t`` -- an optional parameter (default : None uses the parameter from - the basis) - - OUTPUT: + - ``t`` -- an optional parameter (default: ``None``; uses the + parameter from the basis) - - returns the Jack scalar product between ``x`` and ``self`` + OUTPUT: the Jack scalar product between ``x`` and ``self`` EXAMPLES:: @@ -855,7 +823,7 @@ def scalar_jack(self, x, t=None): def part_scalar_jack(part1, part2, t): r""" - Returns the Jack scalar product between ``p(part1)`` and ``p(part2)`` where + Return the Jack scalar product between ``p(part1)`` and ``p(part2)`` where `p` is the power-sum basis. INPUT: @@ -863,9 +831,7 @@ def part_scalar_jack(part1, part2, t): - ``part1``, ``part2`` -- two partitions - ``t`` -- a parameter - OUTPUT: - - - returns the scalar product between the power sum indexed by ``part1`` and ``part2`` + OUTPUT: the scalar product between the power sum indexed by ``part1`` and ``part2`` EXAMPLES:: @@ -913,14 +879,14 @@ def __init__(self, jack): def _m_cache(self, n): r""" - Computes the change of basis between the Jack polynomials in the `P` + Compute the change of basis between the Jack polynomials in the `P` basis and the monomial symmetric functions. This uses Gram-Schmidt to go to the monomials, and then that matrix is simply inverted. INPUT: - ``self`` -- an instance of the Jack `P` basis of the symmetric functions - - ``n`` -- a positive integer indicating the degree + - ``n`` -- positive integer indicating the degree EXAMPLES:: @@ -997,9 +963,7 @@ def product(self, left, right): - ``self`` -- a Jack basis of the symmetric functions - ``left``, ``right`` -- symmetric function elements - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -1019,7 +983,7 @@ def product(self, left, right): def scalar_jack_basis(self, part1, part2=None): r""" - Returns the scalar product of `P(part1)` and `P(part2)`. + Return the scalar product of `P(part1)` and `P(part2)`. This is equation (10.16) of [Mc1995]_ on page 380. @@ -1027,7 +991,7 @@ def scalar_jack_basis(self, part1, part2=None): - ``self`` -- an instance of the Jack `P` basis of the symmetric functions - ``part1`` -- a partition - - ``part2`` -- an optional partition (default : None) + - ``part2`` -- an optional partition (default: ``None``) OUTPUT: @@ -1096,7 +1060,7 @@ class JackPolynomials_j(JackPolynomials_generic): def __init__(self, jack): r""" - The `J` basis is a defined as a normalized form of the `P` basis + The `J` basis is a defined as a normalized form of the `P` basis. INPUT: @@ -1132,7 +1096,7 @@ class JackPolynomials_q(JackPolynomials_generic): def __init__(self, jack): r""" - The `Q` basis is defined as a normalized form of the `P` basis + The `Q` basis is defined as a normalized form of the `P` basis. INPUT: @@ -1201,9 +1165,7 @@ def product(self, left, right): - ``self`` -- an instance of the Jack `Qp` basis of the symmetric functions - ``left``, ``right`` -- symmetric function elements - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -1224,14 +1186,14 @@ def product(self, left, right): def _h_cache(self, n): r""" - Computes the change of basis between the Jack polynomials in the `Qp` + Compute the change of basis between the Jack polynomials in the `Qp` basis and the homogeneous symmetric functions. This uses the coefficients in the change of basis between the Jack `P` basis and the monomial basis. INPUT: - ``self`` -- an instance of the Jack `Qp` basis of the symmetric functions - - ``n`` -- a positive integer indicating the degree + - ``n`` -- positive integer indicating the degree EXAMPLES:: @@ -1273,16 +1235,14 @@ def _h_cache(self, n): def _self_to_h( self, x ): r""" - Isomorphism from self to the homogeneous basis + Isomorphism from ``self`` to the homogeneous basis. INPUT: - ``self`` -- a Jack `Qp` basis of the symmetric functions - ``x`` -- an element of the Jack `Qp` basis - OUTPUT: - - - an element of the homogeneous basis equivalent to ``x`` + OUTPUT: an element of the homogeneous basis equivalent to ``x`` EXAMPLES:: @@ -1302,16 +1262,14 @@ def _self_to_h( self, x ): def _h_to_self(self, x): r""" - Isomorphism from the homogeneous basis into ``self`` + Isomorphism from the homogeneous basis into ``self``. INPUT: - ``self`` -- a Jack `Qp` basis of the symmetric functions - ``x`` -- element of the homogeneous basis - OUTPUT: - - - an element of the Jack `Qp` basis equivalent to ``x`` + OUTPUT: an element of the Jack `Qp` basis equivalent to ``x`` EXAMPLES:: @@ -1331,7 +1289,7 @@ def _h_to_self(self, x): def coproduct_by_coercion(self, elt): r""" - Returns the coproduct of the element ``elt`` by coercion to the Schur basis. + Return the coproduct of the element ``elt`` by coercion to the Schur basis. INPUT: @@ -1367,7 +1325,7 @@ class Element(JackPolynomials_generic.Element): class SymmetricFunctionAlgebra_zonal(sfa.SymmetricFunctionAlgebra_generic): def __init__(self, Sym): r""" - Returns the algebra of zonal polynomials. + Return the algebra of zonal polynomials. INPUT: @@ -1389,7 +1347,7 @@ def __init__(self, Sym): #self._m_to_self_cache = {} Now that we compute Jacks once, there is a global cache #self._self_to_m_cache = {} and we don't need to compute it separately for zonals sfa.SymmetricFunctionAlgebra_generic.__init__(self, self._sym, - prefix="Z", basis_name="zonal") + prefix='Z', basis_name='zonal') category = sage.categories.all.ModulesWithBasis(self._sym.base_ring()) self .register_coercion(SetMorphism(Hom(self._P, self, category), self.sum_of_terms)) self._P.register_coercion(SetMorphism(Hom(self, self._P, category), self._P.sum_of_terms)) @@ -1405,9 +1363,7 @@ def product(self, left, right): - ``self`` -- a zonal basis of the symmetric functions - ``left``, ``right`` -- symmetric function elements - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -1436,9 +1392,7 @@ def scalar_zonal(self, x): - ``self`` -- an element of the zonal basis - ``x`` -- an element of the symmetric function - OUTPUT: - - - the scalar product between ``self`` and ``x`` + OUTPUT: the scalar product between ``self`` and ``x`` EXAMPLES:: diff --git a/src/sage/combinat/sf/k_dual.py b/src/sage/combinat/sf/k_dual.py index 62b3a2f8e72..ad7471ec001 100644 --- a/src/sage/combinat/sf/k_dual.py +++ b/src/sage/combinat/sf/k_dual.py @@ -56,7 +56,7 @@ def __init__(self, Sym, k, t='t'): - ``Sym`` -- an element of class :class:`sage.combinat.sf.sf.SymmetricFunctions` - - ``k`` -- a positive integer + - ``k`` -- positive integer - ``R`` -- a ring @@ -121,7 +121,6 @@ def __init__(self, Sym, k, t='t'): TESTS:: sage: TestSuite(Q).run() - """ R = Sym.base_ring() self.k = k @@ -147,13 +146,12 @@ def ambient(self): sage: Q = Sym.kBoundedQuotient(3,t=1) sage: Q.ambient() Symmetric Functions over Rational Field - """ return self._sym def a_realization(self): r""" - Returns a particular realization of ``self`` (the basis of `k`-bounded monomials + Return a particular realization of ``self`` (the basis of `k`-bounded monomials if `t=1` and the basis of `k`-bounded Hall-Littlewood functions otherwise). EXAMPLES:: @@ -251,19 +249,18 @@ def affineSchur(self): @cached_method def _G_to_km_on_basis_single_level(self, w, m): r""" - Returns the `m^{th}` level of the affine Grothendieck polynomial indexed by the - affine Permutation ``w``. This code could be significantly sped up if it didn't - depend on the Iwahori Hecke algebra code. + Return the `m`-th level of the affine Grothendieck + polynomial indexed by the affine Permutation ``w``. This code could be + significantly sped up if it didn't depend on the Iwahori Hecke algebra + code. INPUT: - - ``w`` -- An affine permutation (an element of the affine type `A` Weyl group). + - ``w`` -- an affine permutation (an element of the affine type `A` Weyl group) - - ``m`` -- An integer. + - ``m`` -- integer - OUTPUT: - - - An element of the `k`-bounded quotient. + OUTPUT: an element of the `k`-bounded quotient EXAMPLES:: @@ -275,7 +272,6 @@ def _G_to_km_on_basis_single_level(self, w, m): m3[1, 1, 1, 1] sage: Q._G_to_km_on_basis_single_level(W.an_element(), 5) -4*m3[1, 1, 1, 1, 1] - """ kB = self._sym.kBoundedSubspace(self.k,t=1) g = kB.K_kschur() @@ -289,20 +285,18 @@ def _G_to_km_on_basis_single_level(self, w, m): def _AffineGrothendieck(self, w, m): r""" - Returns the affine Grothendieck polynomial indexed by the affine permutation + Return the affine Grothendieck polynomial indexed by the affine permutation ``w``. Because this belongs to the completion of the algebra, and hence is an infinite sum, it computes only up to those symmetric functions of degree at most ``m``. INPUT: - - ``w`` -- An affine permutation (an element of the affine type `A` Weyl group). + - ``w`` -- an affine permutation (an element of the affine type `A` Weyl group) - - ``m`` -- An integer. + - ``m`` -- integer - OUTPUT: - - - An element of the `k`-bounded quotient. + OUTPUT: an element of the `k`-bounded quotient EXAMPLES:: @@ -316,16 +310,16 @@ def _AffineGrothendieck(self, w, m): @cached_method def _AffineGrothendieckPolynomial(self, la, m): r""" - Returns the affine Grothendieck polynomial indexed by the partition ``la``. + Return the affine Grothendieck polynomial indexed by the partition ``la``. Because this belongs to the completion of the algebra, and hence is an infinite sum, it computes only up to those symmetric functions of degree at most ``m``. This method is here to cache the polynomials. INPUT: - - ``la`` -- A `k`-bounded partition + - ``la`` -- a `k`-bounded partition - - ``m`` -- An integer + - ``m`` -- integer EXAMPLES:: @@ -337,16 +331,16 @@ def _AffineGrothendieckPolynomial(self, la, m): def AffineGrothendieckPolynomial(self, la, m): r""" - Returns the affine Grothendieck polynomial indexed by the partition ``la``. + Return the affine Grothendieck polynomial indexed by the partition ``la``. Because this belongs to the completion of the algebra, and hence is an infinite sum, it computes only up to those symmetric functions of degree at most ``m``. See :meth:`_AffineGrothendieckPolynomial` for the code. INPUT: - - ``la`` -- A `k`-bounded partition + - ``la`` -- a `k`-bounded partition - - ``m`` -- An integer + - ``m`` -- integer EXAMPLES:: @@ -360,7 +354,7 @@ def AffineGrothendieckPolynomial(self, la, m): def an_element(self): r""" - Returns an element of the quotient ring of `k`-bounded symmetric functions. This + Return an element of the quotient ring of `k`-bounded symmetric functions. This method is here to make the TestSuite run properly. EXAMPLES:: @@ -373,7 +367,7 @@ def an_element(self): def one(self): r""" - Returns the unit of the quotient ring of `k`-bounded symmetric functions. This + Return the unit of the quotient ring of `k`-bounded symmetric functions. This method is here to make the TestSuite run properly. EXAMPLES:: @@ -386,17 +380,15 @@ def one(self): def retract(self,la): r""" - Gives the retract map from the symmetric functions to the quotient ring of + Give the retract map from the symmetric functions to the quotient ring of `k`-bounded symmetric functions. This method is here to make the TestSuite run properly. INPUT: - - ``la`` -- A partition - - OUTPUT: + - ``la`` -- a partition - - The monomial element of the `k`-bounded quotient indexed by ``la``. + OUTPUT: the monomial element of the `k`-bounded quotient indexed by ``la`` EXAMPLES:: @@ -409,12 +401,12 @@ def retract(self,la): def lift(self, la): r""" - Gives the lift map from the quotient ring of `k`-bounded symmetric functions to + Give the lift map from the quotient ring of `k`-bounded symmetric functions to the symmetric functions. This method is here to make the TestSuite run properly. INPUT: - - ``la`` -- A `k`-bounded partition + - ``la`` -- a `k`-bounded partition OUTPUT: @@ -502,17 +494,15 @@ class ParentMethods: def retract(self,la): r""" - Gives the retract map from the symmetric functions to the quotient ring of + Give the retract map from the symmetric functions to the quotient ring of `k`-bounded symmetric functions. This method is here to make the TestSuite run properly. INPUT: - - ``la`` -- A partition + - ``la`` -- a partition - OUTPUT: - - - The monomial element of the `k`-bounded quotient indexed by ``la``. + OUTPUT: the monomial element of the `k`-bounded quotient indexed by ``la`` EXAMPLES:: @@ -533,9 +523,7 @@ def _element_constructor_(self, x): - ``x`` -- a `k`-bounded partition - OUTPUT: - - - an element of the `k`-bounded basis + OUTPUT: an element of the `k`-bounded basis EXAMPLES:: @@ -565,7 +553,7 @@ def _element_constructor_(self, x): def ambient(self): r""" - Returns the symmetric functions. + Return the symmetric functions. EXAMPLES:: @@ -577,7 +565,7 @@ def ambient(self): def __getitem__(self, c): r""" - Implements shorthand for accessing basis elements. + Implement shorthand for accessing basis elements. For a basis `X` indexed by partitions, this method allows for `X[[3,2]]` and `X[3,2]` to be equivalent to `X[Partition([3,2])]`. @@ -648,7 +636,7 @@ def degree_on_basis(self, b): def indices(self): r""" - The set of `k`-bounded partitions of all non-negative integers. + The set of `k`-bounded partitions of all nonnegative integers. EXAMPLES:: @@ -660,16 +648,14 @@ def indices(self): def lift(self, la): r""" - Implements the lift map from the basis ``self`` to the monomial basis of + Implement the lift map from the basis ``self`` to the monomial basis of symmetric functions. INPUT: - - ``la`` -- A `k`-bounded partition. - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - A symmetric function in the monomial basis. + OUTPUT: a symmetric function in the monomial basis EXAMPLES:: @@ -689,15 +675,13 @@ def lift(self, la): def product(self, x, y): r""" - Returns the product of two elements ``x`` and ``y``. + Return the product of two elements ``x`` and ``y``. INPUT: - - ``x``, ``y`` -- Elements of the `k`-bounded quotient of symmetric functions. + - ``x``, ``y`` -- elements of the `k`-bounded quotient of symmetric functions - OUTPUT: - - - A `k`-bounded symmetric function in the dual `k`-Schur function basis + OUTPUT: a `k`-bounded symmetric function in the dual `k`-Schur function basis EXAMPLES:: @@ -888,12 +872,12 @@ class KBoundedQuotientBasis(CombinatorialFreeModule): def __init__(self, kBoundedRing, prefix): r""" - Initializes ``self``. + Initialize ``self``. INPUT: - ``kBoundedRing`` -- an element which is of class :class:`KBoundedQuotient` - - ``prefix`` -- a string used to distinguish this basis, and used in printing. + - ``prefix`` -- string used to distinguish this basis, and used in printing EXAMPLES:: @@ -903,7 +887,6 @@ def __init__(self, kBoundedRing, prefix): 'm4' sage: isinstance(km, sage.combinat.sf.k_dual.KBoundedQuotientBasis) True - """ CombinatorialFreeModule.__init__(self, kBoundedRing.base_ring(), kBoundedRing.indices(), @@ -931,7 +914,7 @@ class kMonomial(KBoundedQuotientBasis): def __init__(self, kBoundedRing): r""" - Initializes the ring which is the `k`-Bounded monomial quotient basis. + Initialize the ring which is the `k`-Bounded monomial quotient basis. INPUT: @@ -962,18 +945,16 @@ def _repr_(self): def retract(self, la): r""" - Implements the retract function on the monomial basis. Given a partition ``la``, + Implement the retract function on the monomial basis. Given a partition ``la``, the retract will return the corresponding `k`-bounded monomial basis element if ``la`` is `k`-bounded; zero otherwise. INPUT: - - ``la`` -- A partition - - OUTPUT: + - ``la`` -- a partition - - A `k`-bounded monomial symmetric function in the `k`-quotient of symmetric - functions. + OUTPUT: a `k`-bounded monomial symmetric function in the `k`-quotient of symmetric + functions EXAMPLES:: @@ -1015,16 +996,14 @@ def retract(self, la): def lift(self, la): r""" - Implements the lift function on the monomial basis. Given a `k`-bounded partition + Implement the lift function on the monomial basis. Given a `k`-bounded partition ``la``, the lift will return the corresponding monomial basis element. INPUT: - - ``la`` -- A `k`-bounded partition - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - A monomial symmetric function. + OUTPUT: a monomial symmetric function EXAMPLES:: @@ -1050,7 +1029,7 @@ class kbounded_HallLittlewoodP(KBoundedQuotientBasis): def __init__(self, kBoundedRing): r""" - Initializes the ring which is the `k`-Bounded Hall-Littlewood P quotient basis. + Initialize the ring which is the `k`-Bounded Hall-Littlewood P quotient basis. INPUT: @@ -1085,7 +1064,7 @@ def _repr_(self): def _m_to_kHLP_on_basis(self, la): r""" - Converts from the monomial basis to the `k`-bounded Hall-Littlewood + Convert from the monomial basis to the `k`-bounded Hall-Littlewood P basis. If ``la`` is not `k`-bounded then it returns the projection of the monomial by the ideal generated by the Hall-Littlewood P basis indexed by partitions whose first part is greater than `k`. @@ -1094,9 +1073,7 @@ def _m_to_kHLP_on_basis(self, la): - ``la`` -- a partition - OUTPUT: - - - an element of the `k`-bounded Hall-Littlewood P basis. + OUTPUT: an element of the `k`-bounded Hall-Littlewood P basis EXAMPLES:: @@ -1136,16 +1113,14 @@ def _m_to_kHLP_on_basis(self, la): def _HLP_to_mk_on_basis(self, la): r""" - Converts from the Hall-Littlewood P basis to the `k`-bounded monomial basis and + Convert from the Hall-Littlewood P basis to the `k`-bounded monomial basis and projects into the `k`-bounded quotient if ``la`` is not a bounded partition. INPUT: - ``la`` -- a partition - OUTPUT: - - - an element of the `k`-bounded monomial basis + OUTPUT: an element of the `k`-bounded monomial basis EXAMPLES:: @@ -1176,18 +1151,16 @@ def _HLP_to_mk_on_basis(self, la): def retract(self, la): r""" - Implements the retract function on the Hall-Littlewood P basis. Given a partition + Implement the retract function on the Hall-Littlewood P basis. Given a partition ``la``, the retract will return the corresponding `k`-bounded Hall-Littlewood P basis element if ``la`` is `k`-bounded; zero otherwise. INPUT: - - ``la`` -- A partition + - ``la`` -- a partition - OUTPUT: - - - A `k`-bounded Hall-Littlewood P symmetric function in the `k`-quotient of - symmetric functions. + OUTPUT: a `k`-bounded Hall-Littlewood P symmetric function in the `k`-quotient of + symmetric functions EXAMPLES:: @@ -1212,17 +1185,15 @@ def retract(self, la): def lift(self, la): r""" - Implements the lift function on the Hall-Littlewood P basis. Given a `k`-bounded + Implement the lift function on the Hall-Littlewood P basis. Given a `k`-bounded partition ``la``, the lift will return the corresponding Hall-Littlewood P basis element. INPUT: - - ``la`` -- A `k`-bounded partition + - ``la`` -- a `k`-bounded partition - OUTPUT: - - - A Hall-Littlewood symmetric function. + OUTPUT: a Hall-Littlewood symmetric function EXAMPLES:: @@ -1254,7 +1225,7 @@ class DualkSchurFunctions(KBoundedQuotientBasis): def __init__(self, kBoundedRing): r""" - Initializes the ring which is the dual `k`-Schur function basis. + Initialize the ring which is the dual `k`-Schur function basis. INPUT: @@ -1290,16 +1261,14 @@ def _repr_(self): def _dks_to_khlp_on_basis(self, la): r""" - Gives the expansion of the dual `k`-Schur basis element indexed by ``la`` into + Give the expansion of the dual `k`-Schur basis element indexed by ``la`` into the Hall-Littlewood P basis. INPUT: - - ``la`` -- A `k`-bounded partition. - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - A symmetric function in the Hall-Littlewood P basis + OUTPUT: a symmetric function in the Hall-Littlewood P basis EXAMPLES:: @@ -1322,16 +1291,14 @@ def _dks_to_khlp_on_basis(self, la): def _khlp_to_dks_on_basis(self, la): r""" - Gives the expansion of the `k`-bounded Hall-Littlewood P basis element indexed by + Give the expansion of the `k`-bounded Hall-Littlewood P basis element indexed by ``la`` into the dual `k`-Schur basis. INPUT: - - ``la`` -- A `k`-bounded partition. - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - A `k`-bounded quotient symmetric function in the dual `k`-Schur basis + OUTPUT: a `k`-bounded quotient symmetric function in the dual `k`-Schur basis EXAMPLES:: @@ -1377,7 +1344,7 @@ class AffineSchurFunctions(KBoundedQuotientBasis): def __init__(self, kBoundedRing): r""" - Initializes the ring which is the `k`-Bounded affine Schur quotient basis. + Initialize the ring which is the `k`-Bounded affine Schur quotient basis. INPUT: @@ -1413,16 +1380,14 @@ def _repr_(self): def _F_to_m_on_basis(self, la): r""" - Gives the expansion of the affine Schur basis element indexed by ``la`` into + Give the expansion of the affine Schur basis element indexed by ``la`` into the monomial basis. INPUT: - - ``la`` -- A `k`-bounded partition. + - ``la`` -- a `k`-bounded partition - OUTPUT: - - - A symmetric function in the monomial basis + OUTPUT: a symmetric function in the monomial basis EXAMPLES:: @@ -1443,16 +1408,14 @@ def _F_to_m_on_basis(self, la): def _m_to_F_on_basis(self, la): r""" - Gives the expansion of the `k`-monomial basis element indexed by ``la`` into + Give the expansion of the `k`-monomial basis element indexed by ``la`` into the affine Schur basis. INPUT: - - ``la`` -- A `k`-bounded partition. - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - A `k`-bounded quotient symmetric function in the affine Schur basis + OUTPUT: a `k`-bounded quotient symmetric function in the affine Schur basis EXAMPLES:: diff --git a/src/sage/combinat/sf/kfpoly.py b/src/sage/combinat/sf/kfpoly.py index 09283745aa5..d58fb746780 100644 --- a/src/sage/combinat/sf/kfpoly.py +++ b/src/sage/combinat/sf/kfpoly.py @@ -30,7 +30,7 @@ def KostkaFoulkesPolynomial(mu, nu, t=None): r""" - Returns the Kostka-Foulkes polynomial `K_{\mu, \nu}(t)`. + Return the Kostka-Foulkes polynomial `K_{\mu, \nu}(t)`. INPUT: @@ -211,9 +211,7 @@ def riggings(part): - ``part`` -- a partition - OUTPUT: - - - a list of riggings associated to the partition ``part`` + OUTPUT: list of riggings associated to the partition ``part`` EXAMPLES:: @@ -252,12 +250,10 @@ def compat(n, mu, nu): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``mu``, ``nu`` -- partitions - OUTPUT: - - - a list of partitions + OUTPUT: list of partitions EXAMPLES:: @@ -304,9 +300,7 @@ def dom(mup, snu): - ``mup`` -- a partition conjugate to ``mu`` - ``snu`` -- a sequence of positive integers - OUTPUT: - - - a boolean value + OUTPUT: boolean EXAMPLES:: @@ -356,9 +350,7 @@ def weight(rg, t=None): - ``rg`` -- a rigging, a list of partitions - ``t`` -- an optional parameter, (default: the generator from `\ZZ['t']`) - OUTPUT: - - - a polynomial in the parameter ``t`` + OUTPUT: a polynomial in the parameter `t` EXAMPLES:: diff --git a/src/sage/combinat/sf/llt.py b/src/sage/combinat/sf/llt.py index a6234fe961a..c301e295721 100644 --- a/src/sage/combinat/sf/llt.py +++ b/src/sage/combinat/sf/llt.py @@ -111,12 +111,12 @@ def __classcall__(cls, Sym, k, t='t'): def __init__(self, Sym, k, t): r""" - Class of LLT symmetric function bases + Class of LLT symmetric function bases. INPUT: - ``self`` -- a family of LLT symmetric function bases - - ``k`` -- a positive integer (the level) + - ``k`` -- positive integer (the level) - ``t`` -- a parameter (default: `t`) EXAMPLES:: @@ -155,15 +155,13 @@ def __init__(self, Sym, k, t): def __repr__(self): r""" - Representation of the LLT symmetric functions + Representation of the LLT symmetric functions. INPUT: - ``self`` -- a family of LLT symmetric function bases - OUTPUT: - - - returns a string representing the LLT symmetric functions + OUTPUT: a string representing the LLT symmetric functions EXAMPLES:: @@ -183,9 +181,7 @@ def symmetric_function_ring( self ): - ``self`` -- a family of LLT symmetric functions bases - OUTPUT: - - - returns the symmetric function ring associated to ``self``. + OUTPUT: the symmetric function ring associated to ``self`` EXAMPLES:: @@ -197,15 +193,13 @@ def symmetric_function_ring( self ): def base_ring(self): r""" - Returns the base ring of ``self``. + Return the base ring of ``self``. INPUT: - ``self`` -- a family of LLT symmetric functions bases - OUTPUT: - - - returns the base ring of the symmetric function ring associated to ``self`` + OUTPUT: the base ring of the symmetric function ring associated to ``self`` EXAMPLES:: @@ -216,15 +210,13 @@ def base_ring(self): def level(self): r""" - Returns the level of ``self``. + Return the level of ``self``. INPUT: - ``self`` -- a family of LLT symmetric functions bases - OUTPUT: - - - the level is the parameter of `k` in the basis + OUTPUT: the level is the parameter of `k` in the basis EXAMPLES:: @@ -235,9 +227,9 @@ def level(self): def _llt_generic(self, skp, stat): r""" - Takes in partition, list of partitions, or a list of skew + Take in partition, list of partitions, or a list of skew partitions as well as a function which takes in two partitions and - a level and returns a coefficient. + a level and return a coefficient. INPUT: @@ -364,16 +356,14 @@ def cospin(self, skp): def hcospin(self): r""" - Returns the HCospin basis. + Return the HCospin basis. This basis is defined [LLT1997]_ equation (27). INPUT: - ``self`` -- a family of LLT symmetric functions bases - OUTPUT: - - - returns the h-cospin basis of the LLT symmetric functions + OUTPUT: the h-cospin basis of the LLT symmetric functions EXAMPLES:: @@ -395,16 +385,15 @@ def hcospin(self): def hspin(self): r""" - Returns the HSpin basis. + Return the HSpin basis. + This basis is defined [LLT1997]_ equation (28). INPUT: - ``self`` -- a family of LLT symmetric functions bases - OUTPUT: - - - returns the h-spin basis of the LLT symmetric functions + OUTPUT: the h-spin basis of the LLT symmetric functions EXAMPLES:: @@ -488,16 +477,14 @@ def construction(self): def _m_to_self(self, x): r""" - Isomorphism from the monomial basis into ``self`` + Isomorphism from the monomial basis into ``self``. INPUT: - ``self`` -- an instance of the LLT hspin or hcospin basis - ``x`` -- an element of the monomial basis - OUTPUT: - - - returns ``x`` expanded in the basis ``self`` + OUTPUT: ``x`` expanded in the basis ``self`` EXAMPLES:: @@ -517,16 +504,14 @@ def _m_to_self(self, x): def _self_to_m(self, x): r""" - Isomorphism from self to the monomial basis + Isomorphism from ``self`` to the monomial basis. INPUT: - ``self`` -- an instance of the LLT hspin or hcospin basis - ``x`` -- an element of ``self`` - OUTPUT: - - - returns ``x`` expanded in the monomial basis. + OUTPUT: ``x`` expanded in the monomial basis EXAMPLES:: @@ -546,15 +531,13 @@ def _self_to_m(self, x): def level(self): r""" - Returns the level of ``self``. + Return the level of ``self``. INPUT: - ``self`` -- an instance of the LLT hspin or hcospin basis - OUTPUT: - - - returns the level associated to the basis ``self``. + OUTPUT: the level associated to the basis ``self`` EXAMPLES:: @@ -572,9 +555,7 @@ def llt_family( self ): - ``self`` -- an instance of the LLT hspin or hcospin basis - OUTPUT: - - - returns an instance of the family of LLT bases associated to ``self``. + OUTPUT: an instance of the family of LLT bases associated to ``self`` EXAMPLES:: @@ -594,9 +575,7 @@ def product(self, left, right): - ``self`` -- an instance of the LLT hspin or hcospin basis - ``left``, ``right`` -- elements of the symmetric functions - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -617,7 +596,7 @@ def _m_cache(self, n): INPUT: - ``self`` -- an instance of the LLT hspin or hcospin basis - - ``n`` -- a positive integer representing the degree + - ``n`` -- positive integer representing the degree EXAMPLES:: @@ -685,7 +664,7 @@ def __init__(self, llt): def _to_m(self, part): r""" - Returns a function which gives the coefficient of a partition + Return a function which gives the coefficient of a partition in the monomial expansion of self(part). INPUT: @@ -753,7 +732,7 @@ def __init__(self, llt): def _to_m(self, part): r""" - Returns a function which gives the coefficient of part2 in the + Return a function which gives the coefficient of part2 in the monomial expansion of self(part). INPUT: diff --git a/src/sage/combinat/sf/macdonald.py b/src/sage/combinat/sf/macdonald.py index 85c03daa032..423329b76c6 100644 --- a/src/sage/combinat/sf/macdonald.py +++ b/src/sage/combinat/sf/macdonald.py @@ -80,15 +80,13 @@ class Macdonald(UniqueRepresentation): def __repr__(self): r""" - The family of Macdonald symmetric function bases + The family of Macdonald symmetric function bases. INPUT: - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - a string representing the Macdonald symmetric function family + OUTPUT: string representing the Macdonald symmetric function family EXAMPLES:: @@ -152,16 +150,14 @@ def __init__(self, Sym, q, t): def base_ring( self ): r""" - Returns the base ring of the symmetric functions where the - Macdonald symmetric functions live + Return the base ring of the symmetric functions where the + Macdonald symmetric functions live. INPUT: - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - the base ring associated to the corresponding symmetric function ring + OUTPUT: the base ring associated to the corresponding symmetric function ring EXAMPLES:: @@ -174,16 +170,14 @@ def base_ring( self ): def symmetric_function_ring( self ): r""" - Returns the base ring of the symmetric functions where the - Macdonald symmetric functions live + Return the base ring of the symmetric functions where the + Macdonald symmetric functions live. INPUT: - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - the symmetric function ring associated to the Macdonald bases + OUTPUT: the symmetric function ring associated to the Macdonald bases EXAMPLES:: @@ -195,16 +189,14 @@ def symmetric_function_ring( self ): def P(self): r""" - Returns Macdonald polynomials in `P` basis. + Return Macdonald polynomials in `P` basis. The `P` basis is defined here as a normalized form of the `J` basis. INPUT: - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - returns the `P` Macdonald basis of symmetric functions + OUTPUT: the `P` Macdonald basis of symmetric functions EXAMPLES:: @@ -300,7 +292,7 @@ def P(self): def Q(self): r""" - Returns the Macdonald polynomials on the `Q` basis. These are dual to + Return the Macdonald polynomials on the `Q` basis. These are dual to the Macdonald polynomials on the P basis with respect to the `qt`-Hall scalar product. The `Q` basis is defined to be a normalized form of the `J` basis. @@ -309,9 +301,7 @@ def Q(self): - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - returns the `Q` Macdonald basis of symmetric functions + OUTPUT: the `Q` Macdonald basis of symmetric functions EXAMPLES:: @@ -363,7 +353,7 @@ def Q(self): def J(self): r""" - Returns the Macdonald polynomials on the `J` basis also known as the + Return the Macdonald polynomials on the `J` basis also known as the integral form of the Macdonald polynomials. These are scalar multiples of both the `P` and `Q` bases. When expressed in the `P` or `Q` basis, the scaling coefficients are polynomials in `q` and `t` rather @@ -376,9 +366,7 @@ def J(self): - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - returns the `J` Macdonald basis of symmetric functions + OUTPUT: the `J` Macdonald basis of symmetric functions EXAMPLES:: @@ -425,7 +413,7 @@ def J(self): def H(self): r""" - Returns the Macdonald polynomials on the H basis. When the `H` basis + Return the Macdonald polynomials on the H basis. When the `H` basis is expanded on the Schur basis, the coefficients are the `qt`-Kostka numbers. @@ -433,9 +421,7 @@ def H(self): - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - returns the `H` Macdonald basis of symmetric functions + OUTPUT: the `H` Macdonald basis of symmetric functions EXAMPLES:: @@ -459,7 +445,7 @@ def H(self): def Ht(self): r""" - Returns the Macdonald polynomials on the `Ht` basis. The elements of + Return the Macdonald polynomials on the `Ht` basis. The elements of the `Ht` basis are eigenvectors of the `nabla` operator. When expanded on the Schur basis, the coefficients are the modified `qt`-Kostka numbers. @@ -468,9 +454,7 @@ def Ht(self): - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - returns the `Ht` Macdonald basis of symmetric functions + OUTPUT: the `Ht` Macdonald basis of symmetric functions EXAMPLES:: @@ -507,7 +491,7 @@ def Ht(self): def S(self): r""" - Returns the modified Schur functions defined by the plethystic + Return the modified Schur functions defined by the plethystic substitution `S_{\mu} = s_{\mu}[X(1-t)/(1-q)]`. When the Macdonald polynomials in the J basis are expressed in terms of the modified Schur functions at `q=0`, the coefficients are `qt`-Kostka numbers. @@ -516,9 +500,7 @@ def S(self): - ``self`` -- a family of Macdonald symmetric function bases - OUTPUT: - - - returns the `S` Macdonald basis of symmetric functions + OUTPUT: the `S` Macdonald basis of symmetric functions EXAMPLES:: @@ -577,9 +559,7 @@ def c1(part, q, t): - ``part`` -- a partition - ``q``, ``t`` -- parameters - OUTPUT: - - - returns a polynomial of the scalar product between the `J` and `P` bases + OUTPUT: a polynomial of the scalar product between the `J` and `P` bases EXAMPLES:: @@ -609,9 +589,7 @@ def c2(part, q, t): - ``part`` -- a partition - ``q``, ``t`` -- parameters - OUTPUT: - - - returns a polynomial of the scalar product between the `J` and `P` bases + OUTPUT: a polynomial of the scalar product between the `J` and `P` bases EXAMPLES:: @@ -637,9 +615,7 @@ def cmunu1(mu, nu): - ``mu``, ``nu`` -- partitions with ``nu`` precedes ``mu`` - OUTPUT: - - - an element of the fraction field of polynomials in `q` and `t` + OUTPUT: an element of the fraction field of polynomials in `q` and `t` EXAMPLES:: @@ -694,9 +670,7 @@ def cmunu(mu, nu): - ``mu``, ``nu`` -- partitions with ``nu`` contained in ``mu`` - OUTPUT: - - - an element of the fraction field of polynomials in `q` and `t` + OUTPUT: an element of the fraction field of polynomials in `q` and `t` EXAMPLES:: @@ -743,7 +717,7 @@ class MacdonaldPolynomials_generic(sfa.SymmetricFunctionAlgebra_generic): def __init__(self, macdonald): r""" - A class for methods for one of the Macdonald bases of the symmetric functions + A class for methods for one of the Macdonald bases of the symmetric functions. INPUT: @@ -752,7 +726,7 @@ def __init__(self, macdonald): EXAMPLES:: - sage: Sym = SymmetricFunctions(FractionField(QQ['q,t'])); Sym.rename("Sym"); Sym + sage: Sym = SymmetricFunctions(FractionField(QQ['q,t'])); Sym.rename('Sym'); Sym Sym sage: Sym.macdonald().P() Sym in the Macdonald P basis @@ -806,16 +780,14 @@ def construction(self): def _s_to_self(self, x): r""" - Isomorphism from the Schur basis into self + Isomorphism from the Schur basis into ``self``. INPUT: - ``self`` -- a Macdonald basis - ``x`` -- an element of the Schur basis - OUTPUT: - - - returns the basis element ``x`` in the basis ``self`` + OUTPUT: the basis element ``x`` in the basis ``self`` EXAMPLES:: @@ -835,16 +807,14 @@ def _s_to_self(self, x): def _self_to_s(self, x): r""" - Isomorphism from self to the Schur basis + Isomorphism from ``self`` to the Schur basis. INPUT: - ``self`` -- a Macdonald basis - ``x`` -- an element of a Macdonald basis - OUTPUT: - - - returns the basis element ``x`` in the Schur functions + OUTPUT: the basis element ``x`` in the Schur functions EXAMPLES:: @@ -864,7 +834,7 @@ def _self_to_s(self, x): def c1(self, part): r""" - Returns the qt-Hall scalar product between ``J(part)`` and ``P(part)``. + Return the `qt`-Hall scalar product between ``J(part)`` and ``P(part)``. INPUT: @@ -886,7 +856,7 @@ def c1(self, part): def c2(self, part): r""" - Returns the `qt`-Hall scalar product between ``J(part)`` and ``Q(part)``. + Return the `qt`-Hall scalar product between ``J(part)`` and ``Q(part)``. INPUT: @@ -920,9 +890,7 @@ def product(self, left, right): - ``left`` -- an element of the basis ``self`` - ``right`` -- another symmetric function - OUTPUT: - - the product of ``left`` and ``right`` expanded in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expanded in the basis ``self`` EXAMPLES:: @@ -949,15 +917,13 @@ def product(self, left, right): def macdonald_family(self): r""" - Returns the family of Macdonald bases associated to the basis ``self`` + Return the family of Macdonald bases associated to the basis ``self``. INPUT: - ``self`` -- a Macdonald basis - OUTPUT: - - - the family of Macdonald symmetric functions associated to ``self`` + OUTPUT: the family of Macdonald symmetric functions associated to ``self`` EXAMPLES:: @@ -989,12 +955,10 @@ def nabla(self, q=None, t=None, power=1): INPUT: - ``self`` -- an element of a Macdonald basis - - ``q``, ``t`` -- optional parameters to specialize - - ``power`` -- an integer (default: 1) - - OUTPUT: + - ``q``, ``t`` -- (optional) parameters to specialize + - ``power`` -- integer (default: 1) - - returns the symmetric function of `\nabla` acting on ``self`` + OUTPUT: the symmetric function of `\nabla` acting on ``self`` EXAMPLES:: @@ -1060,7 +1024,7 @@ def __init__(self, macdonald): def scalar_qt_basis(self, part1, part2=None): r""" - Returns the scalar product of `P(part1)` and `P(part2)` + Return the scalar product of `P(part1)` and `P(part2)` This scalar product formula is given in equation (4.11) p.323 and (6.19) p.339 of Macdonald's book [Mac1995]_. @@ -1089,7 +1053,6 @@ def scalar_qt_basis(self, part1, part2=None): sage: P.scalar_qt_basis(Partition([2,1]), Partition([2,1])) (-q^4*t + 2*q^3*t - q^2*t + q^2 - 2*q + 1)/(-q*t^4 + 2*q*t^3 - q*t^2 + t^2 - 2*t + 1) - """ if part2 is not None and part1 != part2: return self.base_ring().zero() @@ -1166,7 +1129,7 @@ def _s_cache(self, n): INPUT: - ``self`` -- a Macdonald `J` basis - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -1190,7 +1153,7 @@ def _s_cache(self, n): def _to_s(self, part): r""" - Returns a function which gives the coefficient of a partition in + Return a function which gives the coefficient of a partition in the Schur expansion of self(part). These computations are completed with coefficients in fraction @@ -1252,7 +1215,6 @@ def __init__(self, macdonald): sage: H = Sym.macdonald().H() sage: TestSuite(H).run(skip=["_test_associativity","_test_distributivity","_test_prod"]) sage: TestSuite(H).run(elements = [H.t*H[1,1]+H.q*H[2], H[1]+(H.q+H.t)*H[1,1]]) # long time (26s on sage.math, 2012) - """ MacdonaldPolynomials_generic.__init__(self, macdonald) self._m = self._sym.m() @@ -1278,9 +1240,7 @@ def _self_to_s(self, x): - ``x`` -- an element of ``H`` basis - OUTPUT: - - - an element of the Schur basis + OUTPUT: an element of the Schur basis EXAMPLES:: @@ -1318,9 +1278,7 @@ def _s_to_self(self, x): - ``x`` -- an element of the Schur basis - OUTPUT: - - - an element of the ``H`` basis + OUTPUT: an element of the ``H`` basis EXAMPLES:: @@ -1356,9 +1314,7 @@ def _self_to_m(self, x): - ``x`` -- an element of ``H`` basis - OUTPUT: - - - an element of the monomial basis + OUTPUT: an element of the monomial basis EXAMPLES:: @@ -1410,9 +1366,7 @@ def _m_to_self( self, f ): - ``f`` -- an element of the monomial basis - OUTPUT: - - - an element of the ``H`` basis + OUTPUT: an element of the ``H`` basis EXAMPLES:: @@ -1474,7 +1428,6 @@ def __init__(self, macdonald): sage: Ht = Sym.macdonald().Ht() sage: TestSuite(Ht).run(skip=["_test_associativity","_test_distributivity","_test_prod"]) # long time (26s on sage.math, 2012) sage: TestSuite(Ht).run(elements = [Ht.t*Ht[1,1]+Ht.q*Ht[2], Ht[1]+(Ht.q+Ht.t)*Ht[1,1]]) # long time (depends on previous) - """ MacdonaldPolynomials_generic.__init__(self, macdonald) self._self_to_m_cache = _ht_to_m_cache @@ -1487,7 +1440,7 @@ def __init__(self, macdonald): def _self_to_s(self, x): r""" - Convert an element of the ``Ht`` basis to the Schur basis + Convert an element of the ``Ht`` basis to the Schur basis. This function is here to force the coercion path to the Schur basis because these bases are computed using their monomial expansion. @@ -1496,9 +1449,7 @@ def _self_to_s(self, x): - ``x`` -- an element of ``self`` - OUTPUT: - - - an element of the Schur basis + OUTPUT: an element of the Schur basis EXAMPLES:: @@ -1511,7 +1462,7 @@ def _self_to_s(self, x): def _s_to_self( self, x ): r""" - Convert an element of either the Schur basis to the ``Ht`` basis + Convert an element of either the Schur basis to the ``Ht`` basis. This function is here to force the coercion path from the Schur basis because these bases are computed using the monomial expansion. @@ -1520,9 +1471,7 @@ def _s_to_self( self, x ): - ``x`` -- an element of ``s`` basis - OUTPUT: - - - an element of the basis ``self`` + OUTPUT: an element of the basis ``self`` EXAMPLES:: @@ -1556,9 +1505,7 @@ def _Lmunu(self, nu, mu): - ``nu``, ``mu`` -- partitions of the same size - OUTPUT: - - - a polynomial in `q` and `t` + OUTPUT: a polynomial in `q` and `t` EXAMPLES:: @@ -1571,7 +1518,6 @@ def _Lmunu(self, nu, mu): t^2 + q + t + 1 sage: Lmunu(Partition([2,2]),Partition([2,1,1])) q*t + 2*t^2 + q + t + 1 - """ if not mu: if not nu: @@ -1593,16 +1539,14 @@ def _Lmunu(self, nu, mu): def _self_to_m(self, x): r""" - Takes an element of the ``Ht`` basis and returns the expansion in the + Take an element of the ``Ht`` basis and return the expansion in the monomial basis. INPUT: - ``x`` -- an element of ``Ht`` basis - OUTPUT: - - - an element of the monomial basis + OUTPUT: an element of the monomial basis EXAMPLES:: @@ -1618,7 +1562,6 @@ def _self_to_m(self, x): sage: m = Sym.m() sage: m(Ht[2,1]) ((2*x^2+2*x+2)/x)*m[1, 1, 1] + ((x^2+x+1)/x)*m[2, 1] + m[3] - """ part_coeff = lambda x, d: sorted((mu,c) for mu,c in x if sum(mu) == d) return self._m._from_dict({ part2: @@ -1645,9 +1588,7 @@ def _m_to_self( self, f ): - ``f`` -- an element of the monomial basis - OUTPUT: - - - an element of the ``Ht`` basis + OUTPUT: an element of the ``Ht`` basis EXAMPLES:: @@ -1666,7 +1607,6 @@ def _m_to_self( self, f ): sage: m = Sym.m() sage: Ht((3*x+3)*m[1, 1, 1] + (x+2)*m[2, 1] + m[3]) McdHt[2, 1] - """ if self.t == 1: subsval = self.q @@ -1686,7 +1626,7 @@ def _m_to_self( self, f ): class Element(MacdonaldPolynomials_generic.Element): def nabla(self, q=None, t=None, power=1): r""" - Returns the value of the nabla operator applied to ``self``. The + Return the value of the nabla operator applied to ``self``. The eigenvectors of the `nabla` operator are the Macdonald polynomials in the `Ht` basis. For more information see: [BGHT1999]_. @@ -1700,12 +1640,10 @@ def nabla(self, q=None, t=None, power=1): INPUT: - ``self`` -- an element of the Macdonald `Ht` basis - - ``q``, ``t`` -- optional parameters to specialize - - ``power`` -- an integer (default: 1) - - OUTPUT: + - ``q``, ``t`` -- (optional) parameters to specialize + - ``power`` -- integer (default: 1) - - returns the symmetric function of `\nabla` acting on ``self`` + OUTPUT: the symmetric function of `\nabla` acting on ``self`` EXAMPLES:: @@ -1732,7 +1670,6 @@ def nabla(self, q=None, t=None, power=1): sage: a = sum(Ht(p) for p in Partitions(3)) sage: s(a.nabla()) (t^6+9*t^2+729)*s[1, 1, 1] + (t^5+t^4+3*t^2+9*t+324)*s[2, 1] + (t^3+3*t+27)*s[3] - """ P = self.parent() Ht = P._macdonald.Ht() @@ -1750,7 +1687,7 @@ def nabla(self, q=None, t=None, power=1): class MacdonaldPolynomials_s(MacdonaldPolynomials_generic): def __init__(self, macdonald): r""" - An implementation of the basis `s_\lambda[(1-t)X/(1-q)]` + An implementation of the basis `s_\lambda[(1-t)X/(1-q)]`. This is perhaps misnamed as a 'Macdonald' basis for the symmetric functions but is used in the calculation @@ -1769,7 +1706,6 @@ def __init__(self, macdonald): sage: S = Sym.macdonald().S() sage: TestSuite(S).run(skip=["_test_associativity","_test_distributivity","_test_prod"]) sage: TestSuite(S).run(elements = [S.t*S[1,1]+S.q*S[2], S[1]+(S.q+S.t)*S[1,1]]) - """ MacdonaldPolynomials_generic.__init__(self, macdonald) self._s = macdonald._s @@ -1786,9 +1722,7 @@ def product(self, left, right): - ``self`` -- a Macdonald `S` basis - ``left``, ``right`` -- a symmetric functions - OUTPUT: - - the product of ``left`` and ``right`` + OUTPUT: the product of ``left`` and ``right`` EXAMPLES:: @@ -1804,7 +1738,7 @@ def product(self, left, right): def _to_s(self, part): r""" - Returns a function which gives the coefficient of a partition in + Return a function which gives the coefficient of a partition in the Schur expansion of ``self(part)``. these computations are completed with coefficients in fraction field of polynomials in `q` and `t` @@ -1851,7 +1785,7 @@ def _s_cache(self, n): INPUT: - ``self`` -- a Macdonald `S` basis - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -1872,7 +1806,7 @@ class Element(MacdonaldPolynomials_generic.Element): def _creation_by_determinant_helper(self, k, part): r""" - Formula from [LLM1998]_ Corollary 4.3 p. 970 + Formula from [LLM1998]_ Corollary 4.3 p. 970. This is part of a formula for a column adding creation operator for the `J` basis and its action on the `S` basis. @@ -1880,8 +1814,7 @@ def _creation_by_determinant_helper(self, k, part): INPUT: - ``self`` -- an element of the Macdonald `S` basis - - ``k`` -- a positive integer at least as big as the - length of ``part`` + - ``k`` -- positive integer at least as big as the length of ``part`` - ``part`` -- a partition OUTPUT: @@ -1934,11 +1867,9 @@ def _creation_by_determinant(self, k): INPUT: - ``self`` -- an element of the Macdonald `S` basis - - ``k`` -- a positive integer + - ``k`` -- positive integer - OUTPUT: - - - returns the column adding operator on the `J` basis on ``self`` + OUTPUT: the column adding operator on the `J` basis on ``self`` EXAMPLES:: @@ -1964,11 +1895,9 @@ def creation(self, k): INPUT: - ``self`` -- an element of the Macdonald `S` basis - - ``k`` -- a positive integer - - OUTPUT: + - ``k`` -- positive integer - - returns the column adding operator on the `J` basis on ``self`` + OUTPUT: the column adding operator on the `J` basis on ``self`` EXAMPLES:: @@ -1984,7 +1913,7 @@ def creation(self, k): def _omega_qt_in_schurs(self): r""" - Returns the image of self under the omega_qt automorphism in the + Return the image of ``self`` under the omega_qt automorphism in the Schur basis. INPUT: @@ -2012,7 +1941,7 @@ def _omega_qt_in_schurs(self): def qt_kostka(lam, mu): r""" - Returns the `K_{\lambda\mu}(q,t)` by computing the change + Return the `K_{\lambda\mu}(q,t)` by computing the change of basis from the Macdonald H basis to the Schurs. INPUT: diff --git a/src/sage/combinat/sf/monomial.py b/src/sage/combinat/sf/monomial.py index 583008830af..0afecfa4b89 100644 --- a/src/sage/combinat/sf/monomial.py +++ b/src/sage/combinat/sf/monomial.py @@ -30,7 +30,7 @@ class SymmetricFunctionAlgebra_monomial(classical.SymmetricFunctionAlgebra_classical): def __init__(self, Sym): """ - A class for methods related to monomial symmetric functions + A class for methods related to monomial symmetric functions. INPUT: @@ -49,7 +49,7 @@ def __init__(self, Sym): def _dual_basis_default(self): """ - Return the default dual basis to ``self`` when no scalar product is specified + Return the default dual basis to ``self`` when no scalar product is specified. This method returns the dual basis of the monomial basis with respect to the standard scalar product, which is the @@ -80,7 +80,7 @@ def product(self, left, right): Return the product of ``left`` and ``right``. - ``left``, ``right`` -- symmetric functions written in the - monomial basis ``self``. + monomial basis ``self`` OUTPUT: @@ -141,9 +141,9 @@ def from_polynomial(self, f, check=True): INPUT: - ``self`` -- a monomial symmetric function basis - - ``f`` -- a polynomial in finitely many variables over the same base ring as ``self``. - It is assumed that this polynomial is symmetric. - - ``check`` -- boolean (default: ``True``), checks whether the polynomial is indeed symmetric + - ``f`` -- a polynomial in finitely many variables over the same base ring as ``self``; + it is assumed that this polynomial is symmetric + - ``check`` -- boolean (default: ``True``); checks whether the polynomial is indeed symmetric OUTPUT: @@ -185,7 +185,7 @@ def from_polynomial(self, f, check=True): def from_polynomial_exp(self, p): r""" - Conversion from polynomial in exponential notation + Conversion from polynomial in exponential notation. INPUT: @@ -279,7 +279,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -335,12 +335,12 @@ def principal_specialization(self, n=infinity, q=None): INPUT: - - ``n`` (default: ``infinity``) -- a nonnegative integer or + - ``n`` -- (default: ``infinity``) a nonnegative integer or ``infinity``, specifying whether to compute the principal specialization of order ``n`` or the stable principal specialization. - - ``q`` (default: ``None``) -- the value to use for `q`; the + - ``q`` -- (default: ``None``) the value to use for `q`; the default is to create a ring of polynomials in ``q`` (or a field of rational functions in ``q``) over the given coefficient ring. @@ -373,7 +373,6 @@ def principal_specialization(self, n=infinity, q=None): sage: m.zero().principal_specialization(3) 0 - """ if q == 1: if n == infinity: @@ -433,12 +432,12 @@ def exponential_specialization(self, t=None, q=1): INPUT: - - ``t`` (default: ``None``) -- the value to use for `t`; - the default is to create a ring of polynomials in ``t``. + - ``t`` -- (default: ``None``) the value to use for `t`; + the default is to create a ring of polynomials in ``t`` - - ``q`` (default: `1`) -- the value to use for `q`. If + - ``q`` -- (default: `1`) the value to use for `q`; if ``q`` is ``None``, then a ring (or fraction field) of - polynomials in ``q`` is created. + polynomials in ``q`` is created EXAMPLES:: @@ -459,7 +458,6 @@ def exponential_specialization(self, t=None, q=1): sage: m.zero().exponential_specialization() 0 - """ def get_variable(ring, name): try: diff --git a/src/sage/combinat/sf/multiplicative.py b/src/sage/combinat/sf/multiplicative.py index 7ff9797f81a..5fd06b8e373 100644 --- a/src/sage/combinat/sf/multiplicative.py +++ b/src/sage/combinat/sf/multiplicative.py @@ -46,9 +46,7 @@ def product_on_basis(self, left, right): - ``left``, ``right`` -- partitions - OUTPUT: - - - an element of ``self`` + OUTPUT: an element of ``self`` EXAMPLES:: diff --git a/src/sage/combinat/sf/new_kschur.py b/src/sage/combinat/sf/new_kschur.py index 59ce50c74e2..740489adabf 100644 --- a/src/sage/combinat/sf/new_kschur.py +++ b/src/sage/combinat/sf/new_kschur.py @@ -235,7 +235,6 @@ def K_kschur(self): .. [LamSchillingShimozono10] \T. Lam, A. Schilling, M.Shimozono, K-theory Schubert calculus of the affine Grassmannian, Compositio Math. 146 (2010), 811-852. - EXAMPLES:: sage: kB = SymmetricFunctions(QQ).kBoundedSubspace(3,1) @@ -277,12 +276,12 @@ class KBoundedSubspaceBases(Category_realization_of_parent): def __init__(self, base, t='t'): """ - Initialization of the bases of the `k`-bounded subspace + Initialization of the bases of the `k`-bounded subspace. INPUT: - ``base`` -- a basis in the `k`-bounded subspace - - ``t`` -- a parameter (default: 't') + - ``t`` -- a parameter (default: ``'t'``) TESTS:: @@ -447,12 +446,12 @@ def transition_matrix(self, other, n): INPUT: - ``other`` -- a basis in the ring of symmetric functions - - ``n`` -- a positive integer + - ``n`` -- positive integer - The entry in the `i^{th}` row and `j^{th}` column is the - coefficient obtained by writing the `i^{th}` element of the + The entry in the `i`-th row and `j`-th column is the + coefficient obtained by writing the `i`-th element of the basis of ``self`` in terms of the basis ``other``, and extracting the - `j^{th}` coefficient. + `j`-th coefficient. EXAMPLES:: @@ -672,7 +671,7 @@ def hl_creation_operator(self, nu, t=None): INPUT: - - ``nu`` -- a partition or a list of integers + - ``nu`` -- a partition or a list of integers - ``t`` -- (default: ``None``, in which case ``t`` is used) an element of the base ring @@ -820,7 +819,7 @@ def scalar(self, x, zee=None): - ``zee`` -- an optional function on partitions giving the value for the scalar product between `p_{\mu}` and `p_{\mu}` - (default is to use the standard :meth:`~sage.combinat.sf.sfa.zee` function) + (default: use the standard :meth:`~sage.combinat.sf.sfa.zee` function) .. SEEALSO:: :meth:`~sage.combinat.sf.sfa.SymmetricFunctionAlgebra_generic_Element.scalar` @@ -1077,7 +1076,7 @@ def _to_schur_on_basis(self, p): def _product_on_basis_via_rectangles(self, left, right): r""" - Multiply two `k`-Schur functions at `t=1` indexed by ``left`` and ``right`` + Multiply two `k`-Schur functions at `t=1` indexed by ``left`` and ``right``. This algorithm uses the property that if `R` is an `r \times (k+1-r)` rectangle, then @@ -1094,9 +1093,7 @@ def _product_on_basis_via_rectangles(self, left, right): - ``left``, ``right`` -- partitions - OUTPUT: - - - the product of the `k`-Schur functions indexed by ``left`` and ``right`` + OUTPUT: the product of the `k`-Schur functions indexed by ``left`` and ``right`` EXAMPLES:: @@ -1136,9 +1133,7 @@ def product_on_basis(self, left, right): - ``left``, ``right`` -- partitions - OUTPUT: - - - an element of the `k`-Schur functions + OUTPUT: an element of the `k`-Schur functions EXAMPLES:: @@ -1184,7 +1179,7 @@ def product_on_basis(self, left, right): class kSplit(CombinatorialFreeModule): def __init__(self, kBoundedRing): r""" - The `k`-split basis of the space of `k`-bounded-symmetric functions + The `k`-split basis of the space of `k`-bounded-symmetric functions. Fix ``k`` a positive integer and ``t`` an element of the base ring. @@ -1296,7 +1291,7 @@ def _repr_(self): @cached_method def _to_schur_on_basis(self, p): r""" - Computes the change of basis of `k`-split functions to Schur functions. + Compute the change of basis of `k`-split functions to Schur functions. When `t=1` the `k`-split basis is the product of the Schur functions indexed by the partitions in the `k`-split of the partition. @@ -1483,18 +1478,16 @@ def _repr_(self): def _homogeneous_generators_noncommutative_variables_zero_Hecke(self, r): r""" - Return the ``r^{th}`` homogeneous generator, viewed as an element inside the + Return the `r`-th homogeneous generator, viewed as an element inside the affine zero Hecke algebra. - This is the sum of all cyclically decreasing elements of order ``r``. + This is the sum of all cyclically decreasing elements of order `r`. INPUT: - - ``r`` -- A positive integer - - OUTPUT: + - ``r`` -- positive integer - - An element of the affine zero Hecke algebra. + OUTPUT: an element of the affine zero Hecke algebra EXAMPLES:: @@ -1520,11 +1513,9 @@ def _homogeneous_basis(self, la): INPUT: - - ``la`` -- A `k`-bounded partition - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - An element of the affine zero Hecke algebra. + OUTPUT: an element of the affine zero Hecke algebra EXAMPLES:: @@ -1543,11 +1534,9 @@ def homogeneous_basis_noncommutative_variables_zero_Hecke(self, la): INPUT: - - ``la`` -- A `k`-bounded partition + - ``la`` -- a `k`-bounded partition - OUTPUT: - - - An element of the affine zero Hecke algebra. + OUTPUT: an element of the affine zero Hecke algebra EXAMPLES:: @@ -1567,11 +1556,9 @@ def _DualGrothMatrix(self, m): INPUT: - - ``m`` -- An integer - - OUTPUT: + - ``m`` -- integer - - A matrix. + OUTPUT: a matrix EXAMPLES:: @@ -1609,11 +1596,9 @@ def _DualGrothendieck(self, la): INPUT: - - ``la`` -- A `k`-bounded partition. + - ``la`` -- a `k`-bounded partition - OUTPUT: - - - A symmetric function in the homogeneous basis. + OUTPUT: a symmetric function in the homogeneous basis EXAMPLES:: @@ -1654,11 +1639,9 @@ def _g_to_kh_on_basis(self, la): INPUT: - - ``la`` -- A `k`-bounded partition. - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - A symmetric function in the homogeneous basis. + OUTPUT: a symmetric function in the homogeneous basis EXAMPLES:: @@ -1682,11 +1665,9 @@ def K_k_Schur_non_commutative_variables(self, la): INPUT: - - ``la`` -- A `k`-bounded Partition + - ``la`` -- a `k`-bounded Partition - OUTPUT: - - - An element of the affine zero Hecke algebra. + OUTPUT: an element of the affine zero Hecke algebra EXAMPLES:: @@ -1712,11 +1693,9 @@ def _kh_to_g_on_basis(self, la): INPUT: - - ``la`` -- A `k`-bounded partition - - OUTPUT: + - ``la`` -- a `k`-bounded partition - - An element of the `k`-bounded subspace, written in the K-`k`-Schur basis. + OUTPUT: an element of the `k`-bounded subspace, written in the K-`k`-Schur basis EXAMPLES:: @@ -1743,11 +1722,9 @@ def product(self, x, y): INPUT: - - ``x``, ``y`` -- elements of the `k`-bounded subspace, in the K-`k`-Schur basis. - - OUTPUT: + - ``x``, ``y`` -- elements of the `k`-bounded subspace, in the K-`k`-Schur basis - - An element of the `k`-bounded subspace, in the K-`k`-Schur basis + OUTPUT: an element of the `k`-bounded subspace, in the K-`k`-Schur basis EXAMPLES:: @@ -1766,12 +1743,10 @@ def lift(self, x): INPUT: - - ``x`` -- An expression in the K-`k`-Schur basis. Equivalently, ``x`` can be a + - ``x`` -- an expression in the K-`k`-Schur basis. Equivalently, ``x`` can be a `k`-bounded partition (then ``x`` corresponds to the basis element indexed by ``x``) - OUTPUT: - - - A symmetric function. + OUTPUT: a symmetric function EXAMPLES:: @@ -1794,11 +1769,9 @@ def retract(self, x): INPUT: - - ``x`` -- A symmetric function. - - OUTPUT: + - ``x`` -- a symmetric function - - A `k`-bounded symmetric function in the K-`k`-Schur basis. + OUTPUT: a `k`-bounded symmetric function in the K-`k`-Schur basis EXAMPLES:: diff --git a/src/sage/combinat/sf/ns_macdonald.py b/src/sage/combinat/sf/ns_macdonald.py index 582e2f99568..9011cc86b62 100644 --- a/src/sage/combinat/sf/ns_macdonald.py +++ b/src/sage/combinat/sf/ns_macdonald.py @@ -36,7 +36,7 @@ def boxes(self): def __getitem__(self, i): """ - Return the `i^{th}` entry of ``self``. + Return the `i`-th entry of ``self``. Note that the indexing for lattice diagrams starts at `1`. @@ -440,7 +440,7 @@ def fn(ij): def reading_word(self): """ Return the reading word of ``self``, obtained by reading the boxes - entries of self from right to left, starting in the upper right. + entries of ``self`` from right to left, starting in the upper right. EXAMPLES:: diff --git a/src/sage/combinat/sf/orthogonal.py b/src/sage/combinat/sf/orthogonal.py index 3ab5f56debc..b55b3b54a3d 100644 --- a/src/sage/combinat/sf/orthogonal.py +++ b/src/sage/combinat/sf/orthogonal.py @@ -221,9 +221,7 @@ def _s_to_o_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - the expansion of ``s[lam]`` in the orthogonal basis ``self`` + OUTPUT: the expansion of ``s[lam]`` in the orthogonal basis ``self`` EXAMPLES:: diff --git a/src/sage/combinat/sf/orthotriang.py b/src/sage/combinat/sf/orthotriang.py index 17c636ce5ea..685674f0a3a 100644 --- a/src/sage/combinat/sf/orthotriang.py +++ b/src/sage/combinat/sf/orthotriang.py @@ -146,9 +146,7 @@ def _base_to_self(self, x): - ``self`` -- a basis determined by an orthotriangular definition - ``x`` -- an element of the basis `base` to which ``self`` is triangularly related - OUTPUT: - - - an element of ``self`` equivalent to ``x`` + OUTPUT: an element of ``self`` equivalent to ``x`` EXAMPLES:: @@ -169,11 +167,9 @@ def _self_to_base(self, x): INPUT: - ``self`` -- a basis determined by an orthotriangular definition - - ``x`` -- an element of ``self`` as a basis of the ring of symmetric functions. - - OUTPUT: + - ``x`` -- an element of ``self`` as a basis of the ring of symmetric functions - - the element ``x`` expressed in the basis to which ``self`` is triangularly related + OUTPUT: the element ``x`` expressed in the basis to which ``self`` is triangularly related EXAMPLES:: @@ -189,13 +185,13 @@ def _self_to_base(self, x): def _base_cache(self, n): """ - Computes the change of basis between ``self`` and base for the + Compute the change of basis between ``self`` and base for the homogeneous component of size ``n`` INPUT: - ``self`` -- a basis determined by an orthotriangular definition - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -234,7 +230,7 @@ def _to_base(self, part): - ``self`` -- a basis determined by an orthotriangular definition - ``part`` -- a partition - .. note:: + .. NOTE:: We assume that self._gram_schmidt has been called before self._to_base is called. @@ -270,9 +266,7 @@ def product(self, left, right): - ``self`` -- a basis determined by an orthotriangular definition - ``left``, ``right`` -- elements in ``self`` - OUTPUT: - - - the expansion of the product of ``left`` and ``right`` in the basis ``self``. + OUTPUT: the expansion of the product of ``left`` and ``right`` in the basis ``self`` EXAMPLES:: diff --git a/src/sage/combinat/sf/powersum.py b/src/sage/combinat/sf/powersum.py index 9521eaccd32..961e7553450 100644 --- a/src/sage/combinat/sf/powersum.py +++ b/src/sage/combinat/sf/powersum.py @@ -30,7 +30,7 @@ class SymmetricFunctionAlgebra_power(multiplicative.SymmetricFunctionAlgebra_multiplicative): def __init__(self, Sym): """ - A class for methods associated to the power sum basis of the symmetric functions + A class for methods associated to the power sum basis of the symmetric functions. INPUT: @@ -57,11 +57,9 @@ def coproduct_on_generators(self, i): INPUT: - ``self`` -- the power sum basis of the symmetric functions - - ``i`` -- a positive integer + - ``i`` -- positive integer - OUTPUT: - - - the result of the coproduct on the generator `p(i)` + OUTPUT: the result of the coproduct on the generator `p(i)` EXAMPLES:: @@ -197,12 +195,10 @@ def eval_at_permutation_roots_on_generators(self, k, rho): INPUT: - - ``k`` -- a non-negative integer - - ``rho`` -- a partition or a list of non-negative integers + - ``k`` -- nonnegative integer + - ``rho`` -- a partition or a list of nonnegative integers - OUTPUT: - - - an element of the base ring + OUTPUT: an element of the base ring EXAMPLES:: @@ -257,9 +253,7 @@ def omega(self): :meth:`omega_involution()` is a synonym for the :meth:`omega()` method. - OUTPUT: - - - the image of ``self`` under the omega automorphism + OUTPUT: the image of ``self`` under the omega automorphism EXAMPLES:: @@ -438,7 +432,7 @@ def adams_operator(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -551,7 +545,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -617,7 +611,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -683,11 +677,9 @@ def eval_at_permutation_roots(self, rho): INPUT: - - ``rho`` -- a partition or a list of non-negative integers - - OUTPUT: + - ``rho`` -- a partition or a list of nonnegative integers - - an element of the base ring + OUTPUT: an element of the base ring EXAMPLES:: @@ -737,12 +729,12 @@ def principal_specialization(self, n=infinity, q=None): INPUT: - - ``n`` (default: ``infinity``) -- a nonnegative integer or + - ``n`` -- (default: ``infinity``) a nonnegative integer or ``infinity``, specifying whether to compute the principal specialization of order ``n`` or the stable principal specialization. - - ``q`` (default: ``None``) -- the value to use for `q`; the + - ``q`` -- (default: ``None``) the value to use for `q`; the default is to create a ring of polynomials in ``q`` (or a field of rational functions in ``q``) over the given coefficient ring. @@ -785,7 +777,6 @@ def principal_specialization(self, n=infinity, q=None): sage: p.zero().principal_specialization(3) 0 - """ def get_variable(ring, name): try: @@ -871,10 +862,10 @@ def exponential_specialization(self, t=None, q=1): INPUT: - - ``t`` (default: ``None``) -- the value to use for `t`; - the default is to create a ring of polynomials in ``t``. + - ``t`` -- (default: ``None``) the value to use for `t`; + the default is to create a ring of polynomials in ``t`` - - ``q`` (default: `1`) -- the value to use for `q`. If + - ``q`` -- (default: `1`) the value to use for `q`. If ``q`` is ``None``, then a ring (or fraction field) of polynomials in ``q`` is created. @@ -897,7 +888,6 @@ def exponential_specialization(self, t=None, q=1): sage: p.zero().exponential_specialization() 0 - """ def get_variable(ring, name): try: diff --git a/src/sage/combinat/sf/schur.py b/src/sage/combinat/sf/schur.py index 40e1de75812..fb170a25370 100644 --- a/src/sage/combinat/sf/schur.py +++ b/src/sage/combinat/sf/schur.py @@ -33,7 +33,7 @@ class SymmetricFunctionAlgebra_schur(classical.SymmetricFunctionAlgebra_classical): def __init__(self, Sym): """ - A class for methods related to the Schur symmetric function basis + A class for methods related to the Schur symmetric function basis. INPUT: @@ -52,7 +52,7 @@ def __init__(self, Sym): def _dual_basis_default(self): """ - Returns the default value for ``self.dual_basis()`` + Return the default value for ``self.dual_basis()``. This method returns the dual basis to the Schur basis with respect to the standard scalar product. Since the Schur basis is self-dual, it returns itself. @@ -86,9 +86,7 @@ def product_on_basis(self, left, right): - ``self`` -- a Schur symmetric function basis - ``left``, ``right`` -- partitions - OUTPUT: - - - an element of the Schur basis, the product of ``left`` and ``right`` + OUTPUT: an element of the Schur basis, the product of ``left`` and ``right`` TESTS:: @@ -138,7 +136,7 @@ def product_on_basis(self, left, right): def coproduct_on_basis(self, mu): r""" - Returns the coproduct of ``self(mu)``. + Return the coproduct of ``self(mu)``. Here ``self`` is the basis of Schur functions in the ring of symmetric functions. @@ -229,16 +227,14 @@ def _repeated_bernstein_creation_operator_on_basis(self, la, nu): class Element(classical.SymmetricFunctionAlgebra_classical.Element): def __pow__(self, n): """ - Returns the naive powering of an instance of ``self``. + Return the naive powering of an instance of ``self``. INPUT: - ``self`` -- an element of the Schur symmetric function basis - - ``n`` -- a nonnegative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - the ``n`-th power of an instance of ``self`` in the Schur basis + OUTPUT: the `n`-th power of an instance of ``self`` in the Schur basis See ``Monoids.Element.__pow__`` and ``Monoids.Element._pow_naive``. @@ -275,7 +271,6 @@ def __pow__(self, n): # 10 loops, best of 3: 1.73 s per loop Todo: do the same for the other non multiplicative bases? - """ return self._pow_naive(n) @@ -315,9 +310,7 @@ def omega(self): :meth:`omega_involution()` is a synonym for the :meth:`omega()` method. - OUTPUT: - - - the image of ``self`` under the omega automorphism + OUTPUT: the image of ``self`` under the omega automorphism EXAMPLES:: @@ -351,9 +344,7 @@ def scalar(self, x, zee=None): (the default value is the standard :meth:`~sage.combinat.sf.sfa.zee` function) - OUTPUT: - - - the scalar product between ``self`` and ``x`` + OUTPUT: the scalar product between ``self`` and ``x`` EXAMPLES:: @@ -466,7 +457,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -563,7 +554,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -624,12 +615,12 @@ def principal_specialization(self, n=infinity, q=None): INPUT: - - ``n`` (default: ``infinity``) -- a nonnegative integer or + - ``n`` -- (default: ``infinity``) a nonnegative integer or ``infinity``, specifying whether to compute the principal specialization of order ``n`` or the stable principal specialization. - - ``q`` (default: ``None``) -- the value to use for `q`; the + - ``q`` -- (default: ``None``) the value to use for `q`; the default is to create a ring of polynomials in ``q`` (or a field of rational functions in ``q``) over the given coefficient ring. @@ -674,7 +665,6 @@ def principal_specialization(self, n=infinity, q=None): sage: s.zero().principal_specialization(3) 0 - """ def get_variable(ring, name): try: @@ -769,10 +759,10 @@ def exponential_specialization(self, t=None, q=1): INPUT: - - ``t`` (default: ``None``) -- the value to use for `t`; - the default is to create a ring of polynomials in ``t``. + - ``t`` -- (default: ``None``) the value to use for `t`; + the default is to create a ring of polynomials in ``t`` - - ``q`` (default: `1`) -- the value to use for `q`. If + - ``q`` -- (default: `1`) the value to use for `q`. If ``q`` is ``None``, then a ring (or fraction field) of polynomials in ``q`` is created. @@ -815,7 +805,6 @@ def exponential_specialization(self, t=None, q=1): sage: s.zero().exponential_specialization() 0 - """ def get_variable(ring, name): try: diff --git a/src/sage/combinat/sf/sf.py b/src/sage/combinat/sf/sf.py index fbf1ee165f7..9f15dd18fea 100644 --- a/src/sage/combinat/sf/sf.py +++ b/src/sage/combinat/sf/sf.py @@ -44,7 +44,7 @@ class SymmetricFunctions(UniqueRepresentation, Parent): r""" - The abstract algebra of commutative symmetric functions + The abstract algebra of commutative symmetric functions. .. rubric:: Symmetric Functions in Sage @@ -135,7 +135,7 @@ class SymmetricFunctions(UniqueRepresentation, Parent): sage: p[[]] p[] - .. note:: When elements are constructed using the ``p[something ]`` syntax , + .. NOTE:: When elements are constructed using the ``p[something ]`` syntax , an error will be raised if the input cannot be interpreted as a partition. This is *not* the case when ``p.basis()`` is used:: @@ -522,14 +522,14 @@ class function on the symmetric group where the elements One can also use the Sage standard renaming idiom to get shorter outputs:: sage: Sym = SymmetricFunctions(QQ) - sage: Sym.rename("Sym") + sage: Sym.rename('Sym') sage: Sym Sym sage: Sym.rename() And we name it back:: - sage: Sym.rename("Symmetric Functions over Rational Field"); Sym + sage: Sym.rename('Symmetric Functions over Rational Field'); Sym Symmetric Functions over Rational Field .. rubric:: Other bases @@ -863,7 +863,6 @@ def __init__(self, R): sage: Sym1 = SymmetricFunctions(FiniteField(23)) sage: Sym2 = SymmetricFunctions(Integers(23)) sage: TestSuite(Sym).run() - """ # change the line below to assert(R in Rings()) once MRO issues from #15536, #15475 are resolved assert R in Fields() or R in Rings() # side effect of this statement assures MRO exists for R @@ -898,7 +897,7 @@ def _repr_(self): # could be taken care of by the category def schur(self): r""" - The Schur basis of the Symmetric Functions + The Schur basis of the Symmetric Functions. EXAMPLES:: @@ -911,7 +910,7 @@ def schur(self): def powersum(self): r""" - The power sum basis of the Symmetric Functions + The power sum basis of the Symmetric Functions. EXAMPLES:: @@ -924,7 +923,7 @@ def powersum(self): def complete(self): r""" - The complete basis of the Symmetric Functions + The complete basis of the Symmetric Functions. EXAMPLES:: @@ -937,7 +936,7 @@ def complete(self): def elementary(self): r""" - The elementary basis of the Symmetric Functions + The elementary basis of the Symmetric Functions. EXAMPLES:: @@ -949,7 +948,7 @@ def elementary(self): def monomial(self): r""" - The monomial basis of the Symmetric Functions + The monomial basis of the Symmetric Functions. EXAMPLES:: @@ -1220,7 +1219,7 @@ def hecke_character(self, q='q'): def macdonald(self, q='q', t='t'): r""" - Returns the entry point for the various Macdonald bases. + Return the entry point for the various Macdonald bases. INPUT: @@ -1267,7 +1266,7 @@ def macdonald(self, q='q', t='t'): def hall_littlewood(self, t='t'): """ - Returns the entry point for the various Hall-Littlewood bases. + Return the entry point for the various Hall-Littlewood bases. INPUT: @@ -1299,7 +1298,7 @@ def hall_littlewood(self, t='t'): def jack(self, t='t'): """ - Returns the entry point for the various Jack bases. + Return the entry point for the various Jack bases. INPUT: @@ -1325,7 +1324,7 @@ def jack(self, t='t'): def zonal(self): """ - The zonal basis of the Symmetric Functions + The zonal basis of the Symmetric Functions. EXAMPLES:: @@ -1340,7 +1339,7 @@ def llt(self, k, t='t'): INPUT: - - ``k`` -- a positive integer indicating the level + - ``k`` -- positive integer indicating the level - ``t`` -- a parameter (default: `t`) LLT polynomials in `hspin` and `hcospin` bases. @@ -1360,7 +1359,7 @@ def llt(self, k, t='t'): def from_polynomial(self, f): """ - Converts a symmetric polynomial ``f`` to a symmetric function. + Convert a symmetric polynomial ``f`` to a symmetric function. INPUT: @@ -1422,7 +1421,7 @@ def register_isomorphism(self, morphism, only_conversion=False): def __init_extra__(self): """ - Sets up the coercions between the different bases + Set up the coercions between the different bases. EXAMPLES:: @@ -1438,7 +1437,6 @@ def __init_extra__(self): 2*s[] + 2*s[1] - 3*s[1, 1] + 3*s[2] sage: f(p.an_element()) == p.an_element() True - """ #powersum = self.powersum () #complete = self.complete () @@ -1472,8 +1470,8 @@ def kBoundedSubspace(self, k, t='t'): INPUT: - - ``k`` -- a positive integer - - ``t`` a formal parameter; `t=1` yields a subring + - ``k`` -- positive integer + - ``t`` -- a formal parameter; `t=1` yields a subring The subspace of the ring of symmetric functions spanned by `\{ s_{\lambda}[X/(1-t)] \}_{\lambda_1\le k} = \{ s_{\lambda}^{(k)}[X,t]\}_{\lambda_1 \le k}` @@ -1503,7 +1501,7 @@ def kBoundedSubspace(self, k, t='t'): def kschur(self, k, t='t'): r""" - Returns the `k`-Schur functions. + Return the `k`-Schur functions. EXAMPLES:: @@ -1543,7 +1541,7 @@ def ksplit(self, k, t='t'): def khomogeneous(self, k): r""" - Returns the homogeneous symmetric functions in the `k`-bounded subspace. + Return the homogeneous symmetric functions in the `k`-bounded subspace. EXAMPLES:: @@ -1558,11 +1556,11 @@ def khomogeneous(self, k): def kBoundedQuotient(self, k, t='t'): r""" - Returns the `k`-bounded quotient space of the ring of symmetric functions. + Return the `k`-bounded quotient space of the ring of symmetric functions. INPUT: - - ``k`` -- a positive integer + - ``k`` -- positive integer The quotient of the ring of symmetric functions ... @@ -1593,7 +1591,7 @@ def __init__(self, t, domain, codomain): INPUT: - ``t`` -- a function taking a monomial in CombinatorialFreeModule(QQ, Partitions()), - and returning a (partition, coefficient) list. + and returning a (partition, coefficient) list - ``domain``, ``codomain`` -- parents diff --git a/src/sage/combinat/sf/sfa.py b/src/sage/combinat/sf/sfa.py index 36168bd7e1e..3f24d0c8ea7 100644 --- a/src/sage/combinat/sf/sfa.py +++ b/src/sage/combinat/sf/sfa.py @@ -239,7 +239,7 @@ def is_SymmetricFunctionAlgebra(x): """ - Checks whether ``x`` is a symmetric function algebra. + Check whether ``x`` is a symmetric function algebra. EXAMPLES:: @@ -277,7 +277,7 @@ def zee(part): INPUT: - - ``part`` -- an integer partition (for example, ``[2,1,1]``) + - ``part`` -- integer partition (for example, ``[2,1,1]``) OUTPUT: @@ -297,7 +297,7 @@ def zee(part): def is_SymmetricFunction(x): r""" - Checks whether ``x`` is a symmetric function. + Check whether ``x`` is a symmetric function. EXAMPLES:: @@ -411,7 +411,7 @@ def is_integral_domain(self, proof=True): INPUT: - ``self`` -- a basis of the symmetric functions - - ``proof`` -- an optional argument (default value: ``True``) + - ``proof`` -- an optional argument (default: value: ``True``) EXAMPLES:: @@ -432,7 +432,7 @@ def is_field(self, proof=True): INPUT: - ``self`` -- a basis of the symmetric functions - - ``proof`` -- an optional argument (default value: ``True``) + - ``proof`` -- an optional argument (default: value: ``True``) EXAMPLES:: @@ -460,7 +460,7 @@ def is_commutative(self) -> bool: def _repr_(self): """ - Text representation of this basis of symmetric functions + Text representation of this basis of symmetric functions. INPUT: @@ -475,7 +475,7 @@ def _repr_(self): In the following examples, we rename {{{Sym}}} for brevity:: - sage: Sym.rename("Sym"); Sym + sage: Sym.rename('Sym'); Sym Sym Classical bases:: @@ -581,7 +581,7 @@ def _repr_(self): @cached_method def one_basis(self): r""" - Return the empty partition, as per ``AlgebrasWithBasis.ParentMethods.one_basis`` + Return the empty partition, as per ``AlgebrasWithBasis.ParentMethods.one_basis``. INPUT: @@ -1321,13 +1321,13 @@ def carlitz_shareshian_wachs(self, n, d, s, comparison=None): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - - ``d`` -- a nonnegative integer + - ``d`` -- nonnegative integer - - ``s`` -- a nonnegative integer + - ``s`` -- nonnegative integer - - ``comparison`` (default: ``None``) -- a variable + - ``comparison`` -- (default: ``None``) a variable which can take the forms ``None``, ``-1``, ``0`` and ``1`` @@ -1820,14 +1820,14 @@ class SymmetricFunctionAlgebra_generic(CombinatorialFreeModule): """ def __init__(self, Sym, basis_name=None, prefix=None, graded=True): r""" - Initializes the symmetric function algebra. + Initialize the symmetric function algebra. INPUT: - ``Sym`` -- the ring of symmetric functions - ``basis_name`` -- name of basis (default: ``None``) - ``prefix`` -- prefix used to display basis - - ``graded`` -- (default: ``True``) if ``True``, then the basis is + - ``graded`` -- boolean (default: ``True``); if ``True``, then the basis is considered to be graded, otherwise the basis is filtered TESTS:: @@ -1857,7 +1857,7 @@ def __init__(self, Sym, basis_name=None, prefix=None, graded=True): cat = FilteredSymmetricFunctionsBases(Sym) CombinatorialFreeModule.__init__(self, Sym.base_ring(), _Partitions, category=cat, - bracket="", prefix=prefix) + bracket='', prefix=prefix) _print_style = 'lex' @@ -1869,7 +1869,7 @@ def __getitem__(self, c): INPUT: - - ``c`` -- a list, list of lists, or partition + - ``c`` -- list, list of lists, or partition .. TODO:: @@ -1914,9 +1914,7 @@ def _change_by_proportionality(self, x, function): - ``function`` -- a function which takes in a partition and returns a scalar - OUTPUT: - - A symmetric function in ``self`` which is a scaled version of ``x``. + OUTPUT: a symmetric function in ``self`` which is a scaled version of ``x`` EXAMPLES:: @@ -1942,14 +1940,12 @@ def _change_by_plethysm(self, x, expr, deg_one): - ``x`` -- a symmetric function - ``expr`` -- an expression used in the plethysm - - ``deg_one`` -- a list (or iterable) specifying the degree one + - ``deg_one`` -- list (or iterable) specifying the degree one variables (that is, the terms to be treated as degree-one elements when encountered in ``x``; they will be taken to the appropriate powers when computing the plethysm) - OUTPUT: - - The plethysm of ``x`` by ``expr``. + OUTPUT: the plethysm of ``x`` by ``expr`` EXAMPLES:: @@ -1991,7 +1987,7 @@ def _apply_multi_module_morphism(self, x, y, f, orthogonal=False): - ``f`` -- a function that takes in two partitions (basis elements) and returns an element of the target domain - ``orthogonal`` -- if orthogonal is set to ``True``, then - ``f(part1, part2)`` is assumed to be 0 if ``part1 != part2``. + ``f(part1, part2)`` is assumed to be 0 if ``part1 != part2`` EXAMPLES:: @@ -2063,31 +2059,31 @@ def _from_cache(self, element, cache_function, cache_dict, **subs_dict): INPUT: - - ``element`` -- an element of a realization `M` of the ring of - symmetric functions. Note that `M` can be a different realization - than the one in which ``self`` is written, and does not have to - be specified. It is assumed that the basis of ``self`` is indexed - by partitions, and the degree of a basis element is the size of - the partition indexing it. - - - ``cache_function`` -- a function which accepts an - integer `n` as its input and creates the cache for that homogeneous - component (saving it in ``cache_dict``). - - - ``cache_dict`` -- a dictionary storing a cache. - It should be indexed by the positive integers `n`. Its values - are dictionaries indexed by the partitions of size `n`. The values - of those latter dictionaries are, again, dictionaries indexed by - partitions of size `n`. Altogether, ``cache_dict`` should be - understood to encode a graded linear map from `M` to the - realization ``self`` of the ring of symmetric functions; the - encoding is done in such a way that, for any `n` and any partitions - ``lam`` and ``mu`` of `n`, the ``self[mu]``-coordinate of the image - of ``M[lam]`` under this linear map (in the basis ``self``) is - ``cache_dict[lam][mu]``. - - - ``subs_dict`` -- (optional) a dictionary for any substitutions - to make after the value is extracted from ``cache_dict``. + - ``element`` -- an element of a realization `M` of the ring of + symmetric functions. Note that `M` can be a different realization + than the one in which ``self`` is written, and does not have to + be specified. It is assumed that the basis of ``self`` is indexed + by partitions, and the degree of a basis element is the size of + the partition indexing it. + + - ``cache_function`` -- a function which accepts an + integer `n` as its input and creates the cache for that homogeneous + component (saving it in ``cache_dict``). + + - ``cache_dict`` -- dictionary storing a cache. + It should be indexed by the positive integers `n`. Its values + are dictionaries indexed by the partitions of size `n`. The values + of those latter dictionaries are, again, dictionaries indexed by + partitions of size `n`. Altogether, ``cache_dict`` should be + understood to encode a graded linear map from `M` to the + realization ``self`` of the ring of symmetric functions; the + encoding is done in such a way that, for any `n` and any partitions + ``lam`` and ``mu`` of `n`, the ``self[mu]``-coordinate of the image + of ``M[lam]`` under this linear map (in the basis ``self``) is + ``cache_dict[lam][mu]``. + + - ``subs_dict`` -- (optional) a dictionary for any substitutions + to make after the value is extracted from ``cache_dict`` EXAMPLES:: @@ -2144,35 +2140,35 @@ def _invert_morphism(self, n, base_ring, INPUT: - - ``n`` -- an integer, the homogeneous component of - symmetric functions for which we want to a morphism's inverse + - ``n`` -- integer, the homogeneous component of + symmetric functions for which we want to a morphism's inverse - - ``base_ring`` -- the base ring being worked over + - ``base_ring`` -- the base ring being worked over - - ``self_to_other_cache`` -- a dictionary which - stores the transition from ``self`` to ``other`` + - ``self_to_other_cache`` -- dictionary which + stores the transition from ``self`` to ``other`` - - ``other_to_self_cache`` -- a dictionary which - stores the transition from ``other`` to ``self`` + - ``other_to_self_cache`` -- dictionary which + stores the transition from ``other`` to ``self`` - - ``to_other_function`` -- a function which takes in - a partition and returns a function which gives the coefficients of - ``self(part)`` in the ``other`` basis + - ``to_other_function`` -- a function which takes in + a partition and returns a function which gives the coefficients of + ``self(part)`` in the ``other`` basis - - ``to_self_function`` -- a function which takes in a - partition and returns a function which gives the coefficients of - ``other(part)`` in ``self`` + - ``to_self_function`` -- a function which takes in a + partition and returns a function which gives the coefficients of + ``other(part)`` in ``self`` - - ``upper_triangular`` -- a boolean, if ``True``, the - inverse will be computed by back substitution + - ``upper_triangular`` -- boolean; if ``True``, the + inverse will be computed by back substitution - - ``lower_triangular`` -- a boolean, if ``True``, the - inverse will be computed by forward substitution + - ``lower_triangular`` -- boolean; if ``True``, the + inverse will be computed by forward substitution - - ``ones_on_diagonal`` -- a boolean, if ``True``, the - entries on the diagonal of the morphism (and inverse) matrix are - assumed to be ones. This is used to remove divisions from the - forward and back substitute algorithms. + - ``ones_on_diagonal`` -- boolean; if ``True``, the + entries on the diagonal of the morphism (and inverse) matrix are + assumed to be ones. This is used to remove divisions from the + forward and back substitute algorithms. OUTPUT: @@ -2395,9 +2391,7 @@ def symmetric_function_ring(self): Return the family of symmetric functions associated to the basis ``self``. - OUTPUT: - - - returns an instance of the ring of symmetric functions + OUTPUT: an instance of the ring of symmetric functions EXAMPLES:: @@ -2432,13 +2426,12 @@ def transition_matrix(self, basis, n): INPUT: - ``basis`` -- a basis of the ring of symmetric functions - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: - - a matrix of coefficients giving the expansion of the - homogeneous degree-`n` elements of ``self`` in the - degree-`n` elements of ``basis`` + A matrix of coefficients giving the expansion of the homogeneous + degree-`n` elements of ``self`` in the degree-`n` elements of ``basis``. EXAMPLES:: @@ -2647,12 +2640,12 @@ def _inner_plethysm_pk_g(self, k, g, cache): INPUT: - - ``k`` -- a positive integer + - ``k`` -- positive integer - - ``g`` -- a symmetric function in the power sum basis + - ``g`` -- a symmetric function in the power sum basis - - ``cache`` -- a dictionary whose keys are (k, g) pairs - and values are the cached output of this function + - ``cache`` -- dictionary whose keys are (k, g) pairs + and values are the cached output of this function EXAMPLES:: @@ -2715,9 +2708,7 @@ def _inner_plethysm_pnu_g(self, p_x, cache, nu): Note that the order of the arguments is somewhat strange in order to facilitate partial function application. - OUTPUT: - - - an element of the basis ``self`` + OUTPUT: an element of the basis ``self`` EXAMPLES:: @@ -2753,7 +2744,7 @@ def _inner_plethysm_pnu_g(self, p_x, cache, nu): def _dual_basis_default(self): """ - Return the default value for ``self.dual_basis()`` + Return the default value for ``self.dual_basis()``. .. SEEALSO:: :meth:`dual_basis` @@ -2784,14 +2775,14 @@ def _dual_basis_default(self): """ return self.dual_basis(scalar=zee, scalar_name="Hall scalar product") - def dual_basis(self, scalar=None, scalar_name="", basis_name=None, prefix=None): + def dual_basis(self, scalar=None, scalar_name='', basis_name=None, prefix=None): r""" Return the dual basis of ``self`` with respect to the scalar product ``scalar``. INPUT: - - ``scalar`` -- A function ``zee`` from partitions to the base ring + - ``scalar`` -- a function ``zee`` from partitions to the base ring which specifies the scalar product by `\langle p_{\lambda}, p_{\lambda} \rangle = \mathrm{zee}(\lambda)`. (Independently on the function chosen, the power sum basis will always be orthogonal; @@ -2897,7 +2888,7 @@ def set_print_style(self, ps): INPUT: - - ``ps`` -- a string specifying the printing style + - ``ps`` -- string specifying the printing style EXAMPLES:: @@ -2954,7 +2945,7 @@ def from_polynomial(self, poly, check=True): INPUT: - ``poly`` -- a symmetric polynomial - - ``check`` -- (default: ``True``) boolean, specifies whether + - ``check`` -- boolean (default: ``True``); specifies whether the computation checks that the polynomial is indeed symmetric EXAMPLES:: @@ -2982,9 +2973,7 @@ def product_by_coercion(self, left, right): - ``left``, ``right`` -- instances of this basis - OUTPUT: - - - the product of ``left`` and ``right`` expressed in the basis ``self`` + OUTPUT: the product of ``left`` and ``right`` expressed in the basis ``self`` EXAMPLES:: @@ -3136,7 +3125,6 @@ def factor(self): sage: factor(6*s[1]) 2*s[] * 3*s[] * s[1] - """ from sage.combinat.sf.multiplicative import SymmetricFunctionAlgebra_multiplicative L = self.parent() @@ -3182,7 +3170,6 @@ def _floordiv_(self, other): sage: s(6) // s(2) 3*s[] - """ from sage.combinat.sf.multiplicative import SymmetricFunctionAlgebra_multiplicative # we can assume that the parents of self and other are the same @@ -3233,7 +3220,6 @@ def gcd(self, other): sage: gcd(s(9), s(6)) 3*s[] - """ from sage.combinat.sf.multiplicative import SymmetricFunctionAlgebra_multiplicative L = self.parent() @@ -3266,12 +3252,12 @@ def plethysm(self, x, include=None, exclude=None): INPUT: - - ``x`` -- a symmetric function over the same base ring as - ``self`` - - ``include`` -- a list of variables to be treated as - degree one elements instead of the default degree one elements - - ``exclude`` -- a list of variables to be excluded - from the default degree one elements + - ``x`` -- a symmetric function over the same base ring as + ``self`` + - ``include`` -- list of variables to be treated as + degree one elements instead of the default degree one elements + - ``exclude`` -- list of variables to be excluded + from the default degree one elements OUTPUT: @@ -3606,9 +3592,7 @@ def inner_plethysm(self, x): - ``x`` -- element of the ring of symmetric functions over the same base ring as ``self`` - OUTPUT: - - - an element of symmetric functions in the parent of ``self`` + OUTPUT: an element of symmetric functions in the parent of ``self`` EXAMPLES:: @@ -4814,8 +4798,8 @@ def nabla(self, q=None, t=None, power=1): INPUT: - - ``q``, ``t`` -- optional parameters (default: ``None``, in which - case ``q`` and ``t`` are used) + - ``q``, ``t`` -- parameters (default: ``None``, in which case ``q`` + and ``t`` are used) - ``power`` -- (default: ``1``) an integer indicating how many times to apply the operator `\nabla`. Negative values of ``power`` indicate powers of `\nabla^{-1}`. @@ -4875,7 +4859,7 @@ def scalar(self, x, zee=None): - ``zee`` -- an optional function on partitions giving the value for the scalar product between `p_{\mu}` and `p_{\mu}` - (default is to use the standard :meth:`~sage.combinat.sf.sfa.zee` function) + (default: the standard :meth:`~sage.combinat.sf.sfa.zee` function) This is the default implementation that converts both ``self`` and ``x`` into either Schur functions (if ``zee`` is not specified) or @@ -5173,7 +5157,7 @@ def adams_operator(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -5338,7 +5322,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -5537,7 +5521,7 @@ def _expand(self, condition, n, alphabet='x'): selecting only certain terms (namely, only the items failing the condition are being expanded) - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -5684,9 +5668,7 @@ def restrict_degree(self, d, exact=True): exactly ``d``, otherwise returns all terms of degree less than or equal to ``d`` - OUTPUT: - - - the homogeneous component of ``self`` of degree ``d`` + OUTPUT: the homogeneous component of ``self`` of degree ``d`` EXAMPLES:: @@ -5772,7 +5754,7 @@ def expand(self, n, alphabet='x'): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer - ``alphabet`` -- (default: ``'x'``) a variable for the expansion @@ -5977,11 +5959,9 @@ def eval_at_permutation_roots(self, rho): INPUT: - - ``rho`` -- a partition or a list of non-negative integers + - ``rho`` -- a partition or a list of nonnegative integers - OUTPUT: - - - an element of the base ring + OUTPUT: an element of the base ring EXAMPLES:: @@ -6020,12 +6000,10 @@ def character_to_frobenius_image(self, n): INPUT: - - ``n`` -- a non-negative integer to interpret ``self`` as + - ``n`` -- nonnegative integer to interpret ``self`` as a character of `GL_n` - OUTPUT: - - - a symmetric function of degree ``n`` + OUTPUT: a symmetric function of degree ``n`` EXAMPLES:: @@ -6072,12 +6050,12 @@ def principal_specialization(self, n=infinity, q=None): INPUT: - - ``n`` (default: ``infinity``) -- a nonnegative integer or + - ``n`` -- (default: ``infinity``) a nonnegative integer or ``infinity``, specifying whether to compute the principal specialization of order ``n`` or the stable principal specialization. - - ``q`` (default: ``None``) -- the value to use for `q`; the + - ``q`` -- (default: ``None``) the value to use for `q`; the default is to create a ring of polynomials in ``q`` (or a field of rational functions in ``q``) over the given coefficient ring. @@ -6147,7 +6125,7 @@ def principal_specialization(self, n=infinity, q=None): 1 Check that the stable principal specialization at `q = 1` - raises a :class:`ValueError`: + raises a :exc:`ValueError`: sage: def test_error(x): ....: message = "the stable principal specialization of %s at q=1 should raise a ValueError" @@ -6271,7 +6249,6 @@ def principal_specialization(self, n=infinity, q=None): {1} sage: set(b.one().principal_specialization(q=q) for b in B) {1} - """ # heuristically, it seems fastest to fall back to the # elementary basis - using the powersum basis would @@ -6326,10 +6303,10 @@ def exponential_specialization(self, t=None, q=1): INPUT: - - ``t`` (default: ``None``) -- the value to use for `t`; - the default is to create a ring of polynomials in ``t``. + - ``t`` -- (default: ``None``) the value to use for `t`; + the default is to create a ring of polynomials in ``t`` - - ``q`` (default: `1`) -- the value to use for `q`. If + - ``q`` -- (default: `1`) the value to use for `q`. If ``q`` is ``None``, then a ring (or fraction field) of polynomials in ``q`` is created. @@ -6482,7 +6459,6 @@ def __init__(self, basis, name, *args): sage: qbar = SymmetricFunctions(R).hecke_character() sage: SymmetricFunctionsFunctor(qbar, qbar.basis_name(), q) SymmetricFunctionsFunctor[Hecke character with q=q] - """ self._basis = basis.__class__.__base__ self._name = name @@ -6508,7 +6484,6 @@ def _apply_functor(self, R): Traceback (most recent call last): ... TypeError: no conversion of this rational to integer - """ from sage.combinat.sf.sf import SymmetricFunctions return self._basis(SymmetricFunctions(R), *self._args) @@ -6820,7 +6795,7 @@ def _to_polynomials(lf, R): INPUT: - - ``lf`` -- a list of symmetric functions + - ``lf`` -- list of symmetric functions - ``R`` -- the base ring .. SEEALSO:: @@ -6850,7 +6825,7 @@ def _to_polynomials(lf, R): def _from_polynomial(p, f): """ Return the polynomial as a symmetric function in the given - basis , where the `n`th variable corresponds to the symmetric + basis , where the `n`-th variable corresponds to the symmetric function`f[n]`. INPUT: diff --git a/src/sage/combinat/sf/symplectic.py b/src/sage/combinat/sf/symplectic.py index f6db1782489..8102121389e 100644 --- a/src/sage/combinat/sf/symplectic.py +++ b/src/sage/combinat/sf/symplectic.py @@ -229,9 +229,7 @@ def _s_to_sp_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - the expansion of ``s[lam]`` in the symplectic basis ``self`` + OUTPUT: the expansion of ``s[lam]`` in the symplectic basis ``self`` EXAMPLES:: diff --git a/src/sage/combinat/sf/witt.py b/src/sage/combinat/sf/witt.py index cf14fa826c6..5e8b115c95c 100644 --- a/src/sage/combinat/sf/witt.py +++ b/src/sage/combinat/sf/witt.py @@ -239,9 +239,7 @@ def _h_to_w_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - the expansion of ``h[lam]`` in the Witt basis ``self`` + OUTPUT: the expansion of ``h[lam]`` in the Witt basis ``self`` EXAMPLES:: @@ -318,9 +316,7 @@ def _e_to_w_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - the expansion of ``e[lam]`` in the Witt basis ``self`` + OUTPUT: the expansion of ``e[lam]`` in the Witt basis ``self`` EXAMPLES:: @@ -395,9 +391,7 @@ def _p_to_w_on_basis(self, lam): - ``lam`` -- a partition - OUTPUT: - - - the expansion of ``p[lam]`` in the Witt basis ``self`` + OUTPUT: the expansion of ``p[lam]`` in the Witt basis ``self`` EXAMPLES:: @@ -561,7 +555,7 @@ def verschiebung(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: diff --git a/src/sage/combinat/shard_order.py b/src/sage/combinat/shard_order.py index b61eb61fa48..4bcc75d0871 100644 --- a/src/sage/combinat/shard_order.py +++ b/src/sage/combinat/shard_order.py @@ -45,7 +45,7 @@ class ShardPosetElement(tuple): - ``p`` -- the permutation itself as a tuple - ``runs`` -- the decreasing runs as a tuple of tuples - - ``run_indices`` -- a list ``integer -> index of the run`` + - ``run_indices`` -- list; ``integer -> index of the run`` - ``dpg`` -- the transitive closure of the shard preorder graph - ``spg`` -- the transitive reduction of the shard preorder graph @@ -60,7 +60,7 @@ class ShardPosetElement(tuple): """ def __new__(cls, p): r""" - Initialization of the underlying tuple + Initialization of the underlying tuple. TESTS:: @@ -172,13 +172,13 @@ def shard_preorder_graph(runs): INPUT: - - a tuple of tuples, the runs of a permutation, or + - ``runs`` -- either - - a tuple of pairs `(i,j)`, each one standing for a run from `i` to `j`. + - a tuple of tuples, the runs of a permutation, or - OUTPUT: + - a tuple of pairs `(i,j)`, each one standing for a run from `i` to `j` - a directed graph, with vertices labelled by integers + OUTPUT: a directed graph, with vertices labelled by integers EXAMPLES:: diff --git a/src/sage/combinat/shifted_primed_tableau.py b/src/sage/combinat/shifted_primed_tableau.py index 68612443e82..37bbd402c14 100644 --- a/src/sage/combinat/shifted_primed_tableau.py +++ b/src/sage/combinat/shifted_primed_tableau.py @@ -284,7 +284,7 @@ def __eq__(self, other): - ``other`` -- the element that ``self`` is compared to - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -311,7 +311,7 @@ def __ne__(self, other): - ``other`` -- the element that ``self`` is compared to - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -938,9 +938,7 @@ def f(self, ind): - ``ind`` -- element in the index set of the crystal - OUTPUT: - - Primed tableau or ``None``. + OUTPUT: primed tableau or ``None`` EXAMPLES:: @@ -1133,9 +1131,7 @@ def e(self, ind): - ``ind`` -- an element in the index set of the crystal - OUTPUT: - - Primed tableau or ``None``. + OUTPUT: primed tableau or ``None`` EXAMPLES:: @@ -1363,7 +1359,7 @@ class PrimedEntry(SageObject): INPUT: - - ``entry`` -- a half integer or a string of an integer + - ``entry`` -- half integer or string of an integer possibly ending in ``p`` or ``'`` - ``double`` -- the doubled value """ @@ -1537,7 +1533,7 @@ def __ge__(self, other): def is_unprimed(self): """ - Checks if ``self`` is an unprimed element. + Check if ``self`` is an unprimed element. TESTS:: @@ -1550,7 +1546,7 @@ def is_unprimed(self): def is_primed(self): """ - Checks if ``self`` is a primed element. + Check if ``self`` is a primed element. TESTS:: @@ -1648,7 +1644,7 @@ def decrease_one(self): class ShiftedPrimedTableaux(UniqueRepresentation, Parent): r""" - Returns the combinatorial class of shifted primed tableaux subject + Return the combinatorial class of shifted primed tableaux subject to the constraints given by the arguments. A primed tableau is a tableau of shifted shape on the alphabet @@ -1873,9 +1869,7 @@ def _element_constructor_(self, T): - ``T`` -- data which can be interpreted as a primed tableau - OUTPUT: - - - the corresponding primed tableau object + OUTPUT: the corresponding primed tableau object EXAMPLES:: diff --git a/src/sage/combinat/shuffle.py b/src/sage/combinat/shuffle.py index 846a214e30d..f1797f7acab 100644 --- a/src/sage/combinat/shuffle.py +++ b/src/sage/combinat/shuffle.py @@ -81,7 +81,7 @@ def __init__(self, l1, l2, element_constructor=None): sage: from sage.combinat.shuffle import ShuffleProduct sage: SP = ShuffleProduct([1,2],[4,5,7,8,9]) - sage: TestSuite(SP).run(skip="_test_an_element") + sage: TestSuite(SP).run(skip='_test_an_element') """ self._l1 = l1 self._l2 = l2 @@ -140,7 +140,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Test for unequality + Test for unequality. EXAMPLES:: @@ -205,7 +205,7 @@ def __init__(self, l1, l2, element_constructor=None): - ``l1``, ``l2`` -- iterable: the sets to shuffle - - ``element_constructor`` -- constructor for the returned elements + - ``element_constructor`` -- constructor for the returned elements TESTS:: @@ -213,7 +213,7 @@ def __init__(self, l1, l2, element_constructor=None): sage: X = SetShuffleProduct({(1,2,3), (2,3,4)}, {(5,)}) sage: X # random Shuffle set product of: [(2, 3, 4), (1, 2, 3)] and [(5,)] - sage: TestSuite(X).run(skip="_test_an_element") + sage: TestSuite(X).run(skip='_test_an_element') sage: list(SetShuffleProduct({(1,2,3), (2,3,4)}, {(5,)})) # random [[2, 3, 4, 5], [2, 5, 3, 4], [5, 2, 3, 4], [2, 3, 5, 4], @@ -243,7 +243,6 @@ def _repr_(self): Shuffle set product of: [[1, 2], [3, 4]] and [[1, 4]] sage: SetShuffleProduct([()], [[1,4]]) Shuffle set product of: [()] and [[1, 4]] - """ return "Shuffle set product of: %s and %s" % (self._element_constructor_(self._l1), self._element_constructor_(self._l2)) @@ -259,7 +258,6 @@ def _ascii_art_(self): [ [ o, o ] ] [ [ / \ ] ] [ [ ], [ o o ] ] and [ [ 1, 4 ] ] - """ from sage.typeset.ascii_art import ascii_art return (ascii_art("Set shuffle product of:") * @@ -334,7 +332,6 @@ class ShuffleProduct(ShuffleProduct_abstract): 'abdec'] sage: list(ShuffleProduct("", "de", element_constructor="".join)) ['de'] - """ def __init__(self, l1, l2, element_constructor=None): @@ -345,7 +342,7 @@ def __init__(self, l1, l2, element_constructor=None): - ``l1``, ``l2`` -- iterable: iterables to shuffle - - ``element_constructor``: constructor for the returned elements + - ``element_constructor`` -- constructor for the returned elements TESTS:: @@ -353,7 +350,7 @@ def __init__(self, l1, l2, element_constructor=None): sage: SP = ShuffleProduct([1,2,3],[4,5]) sage: SP Shuffle product of: [1, 2, 3] and [4, 5] - sage: TestSuite(SP).run(skip="_test_an_element") + sage: TestSuite(SP).run(skip='_test_an_element') sage: list(ShuffleProduct(Word("aa"), Word("bbb"), Word)) [word: aabbb, word: baabb, word: ababb, word: bbaab, word: babab, word: abbab, @@ -567,7 +564,7 @@ def __init__(self, w1, w2, r, element_constructor=None, add=operator.add): sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]]) sage: S = ShuffleProduct_overlapping_r(w,u,1) - sage: TestSuite(S).run(skip="_test_an_element") + sage: TestSuite(S).run(skip='_test_an_element') """ self.r = r self.add = add @@ -777,7 +774,7 @@ def __init__(self, w1, w2, element_constructor=None, add=operator.add): sage: from sage.combinat.shuffle import ShuffleProduct_overlapping sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]]) sage: S = ShuffleProduct_overlapping(w,u) - sage: TestSuite(S).run(skip="_test_an_element") + sage: TestSuite(S).run(skip='_test_an_element') """ self._add = add diff --git a/src/sage/combinat/sidon_sets.py b/src/sage/combinat/sidon_sets.py index 9ba6bdb5c71..e2c85f74633 100644 --- a/src/sage/combinat/sidon_sets.py +++ b/src/sage/combinat/sidon_sets.py @@ -31,12 +31,10 @@ def sidon_sets(N, g=1): INPUT: - - `N` -- A positive integer. - - `g` -- A positive integer (default: `1`). + - ``N`` -- positive integer + - ``g`` -- positive integer (default: `1`) - OUTPUT: - - - A Sage set with categories whose element are also set of integers. + OUTPUT: a Sage set with categories whose element are also set of integers EXAMPLES:: diff --git a/src/sage/combinat/similarity_class_type.py b/src/sage/combinat/similarity_class_type.py index f6a67af12c0..caa691ac559 100644 --- a/src/sage/combinat/similarity_class_type.py +++ b/src/sage/combinat/similarity_class_type.py @@ -215,13 +215,11 @@ def fq(n, q=None): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - - ``q`` -- an integer or an indeterminate - - OUTPUT: + - ``q`` -- integer or an indeterminate - A rational function in ``q``. + OUTPUT: a rational function in ``q`` EXAMPLES:: @@ -253,15 +251,13 @@ def primitives(n, invertible=False, q=None): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``invertible`` -- boolean; if set, only number of non-zero classes is returned + - ``invertible`` -- boolean; if set, only number of nonzero classes is returned - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate - OUTPUT: - - - a rational function of the variable ``q`` + OUTPUT: a rational function of the variable ``q`` EXAMPLES:: @@ -292,9 +288,9 @@ def order_of_general_linear_group(n, q=None): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate EXAMPLES:: @@ -340,9 +336,7 @@ def centralizer_group_cardinality(la, q=None): - ``q`` -- an integer or an indeterminate - OUTPUT: - - A polynomial function of ``q``. + OUTPUT: a polynomial function of ``q`` EXAMPLES:: @@ -367,9 +361,7 @@ def invariant_subspace_generating_function(la, q=None, t=None): - ``q`` -- (optional) an integer or an inderminate - ``t`` -- (optional) an indeterminate - OUTPUT: - - A polynomial in ``t`` whose coefficients are polynomials in ``q``. + OUTPUT: a polynomial in ``t`` whose coefficients are polynomials in ``q`` EXAMPLES:: @@ -588,7 +580,7 @@ def centralizer_group_card(self, q=None): INPUT: - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate EXAMPLES:: @@ -637,7 +629,7 @@ class PrimarySimilarityClassTypes(UniqueRepresentation, Parent): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``min`` -- a primary matrix type of size ``n`` EXAMPLES: @@ -767,7 +759,7 @@ class SimilarityClassType(CombinatorialElement): INPUT: - - ``tau`` -- a list of primary similarity class types or a square matrix + - ``tau`` -- list of primary similarity class types or a square matrix over a finite field EXAMPLES:: @@ -872,7 +864,7 @@ def centralizer_group_card(self, q=None): INPUT: - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate EXAMPLES:: @@ -908,10 +900,10 @@ def number_of_classes(self, invertible=False, q=None): INPUT: - - ``invertible`` -- Boolean; return number of invertible classes if set + - ``invertible`` -- boolean; return number of invertible classes if set to ``True`` - - ``q`` -- An integer or an indeterminate + - ``q`` -- integer or an indeterminate EXAMPLES:: @@ -990,7 +982,7 @@ def class_card(self, q=None): INPUT: - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate EXAMPLES:: @@ -1011,7 +1003,7 @@ def number_of_matrices(self, invertible=False, q=None): INPUT: - - ``invertible`` -- A boolean; return the number of invertible + - ``invertible`` -- a boolean; return the number of invertible matrices if set EXAMPLES:: @@ -1031,7 +1023,7 @@ def number_of_matrices(self, invertible=False, q=None): def statistic(self, func, q=None): r""" - Return + Return. .. MATH:: @@ -1044,7 +1036,7 @@ def statistic(self, func, q=None): - ``func`` -- a function that takes a partition to a polynomial in ``q`` - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate EXAMPLES:: @@ -1100,7 +1092,7 @@ class SimilarityClassTypes(UniqueRepresentation, Parent): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - ``min`` -- a primary similarity class type EXAMPLES: @@ -1168,7 +1160,7 @@ def _element_constructor_(self, tau): INPUT: - - ``tau`` -- a list of primary similarity class types + - ``tau`` -- list of primary similarity class types EXAMPLES:: @@ -1238,7 +1230,7 @@ def size(self): """ return self._n - def sum(self, stat, sumover="matrices", invertible=False, q=None): + def sum(self, stat, sumover='matrices', invertible=False, q=None): r""" Return the sum of a local statistic over all types. @@ -1256,10 +1248,10 @@ def sum(self, stat, sumover="matrices", invertible=False, q=None): \sum n_{\tau(g)}(q) where `\tau(g)` denotes the type of a matrix `g`, and the sum is over - all `n \times n` matrices if ``sumover`` is set to ``"matrices"``, is + all `n \times n` matrices if ``sumover`` is set to ``'matrices'``, is over all `n \times n` similarity classes if ``sumover`` is set to - ``"classes"``, and over all `n \times n` types if ``sumover`` is set - to ``"types"``. If ``invertible`` is set to ``True``, then the sum is + ``'classes'``, and over all `n \times n` types if ``sumover`` is set + to ``'types'``. If ``invertible`` is set to ``True``, then the sum is only over invertible matrices or classes. INPUT: @@ -1268,15 +1260,13 @@ def sum(self, stat, sumover="matrices", invertible=False, q=None): of ``q`` - ``sumover`` -- can be one of the following: - * ``"matrices"`` - * ``"classes"`` - * ``"types"`` + * ``'matrices'`` + * ``'classes'`` + * ``'types'`` - - ``q`` -- an integer or an indeterminate + - ``q`` -- integer or an indeterminate - OUTPUT: - - A function of ``q``. + OUTPUT: a function of ``q`` EXAMPLES:: @@ -1445,8 +1435,8 @@ def ext_orbits(input_data, q=None, selftranspose=False): - ``input_data`` -- input for :func:`input_parsing()` - ``q`` -- (default: `q`) an integer or an indeterminate - - ``selftranspose`` -- (default: ``False``) boolean stating if we only want - selftranspose type + - ``selftranspose`` -- boolean (default: ``False``); stating if we only + want selftranspose type TESTS:: @@ -1522,9 +1512,9 @@ def matrix_similarity_classes_length_two(n, q=None, selftranspose=False, inverti - ``n`` -- the order - ``q`` -- (default: `q`) an integer or an indeterminate - - ``selftranspose`` -- (default: ``False``) boolean stating if we only want + - ``selftranspose`` -- boolean (default: ``False``); stating if we only want selftranspose type - - ``invertible`` -- (default: ``False``) boolean stating if we only want + - ``invertible`` -- boolean (default: ``False``); stating if we only want invertible type EXAMPLES: @@ -1575,7 +1565,7 @@ def ext_orbit_centralizers(input_data, q=None, selftranspose=False): - ``input_data`` -- input for :func:`input_parsing()` - ``q`` -- (default: `q`) an integer or an indeterminate - - ``selftranspose`` -- (default: ``False``) boolean stating if we only want + - ``selftranspose`` -- boolean (default: ``False``); stating if we only want selftranspose type TESTS:: @@ -1700,9 +1690,9 @@ def matrix_centralizer_cardinalities_length_two(n, q=None, selftranspose=False, - ``n`` -- the order - ``q`` -- (default: `q`) an integer or an indeterminate - - ``selftranspose`` -- (default: ``False``) boolean stating if we only want + - ``selftranspose`` -- boolean (default: ``False``); stating if we only want selftranspose type - - ``invertible`` -- (default: ``False``) boolean stating if we only want + - ``invertible`` -- boolean (default: ``False``); stating if we only want invertible type TESTS:: diff --git a/src/sage/combinat/sine_gordon.py b/src/sage/combinat/sine_gordon.py index 0e71beca5ef..1891f172d38 100644 --- a/src/sage/combinat/sine_gordon.py +++ b/src/sage/combinat/sine_gordon.py @@ -66,7 +66,7 @@ class SineGordonYsystem(SageObject): r""" - A class to model a (reduced) sine-Gordon Y-system + A class to model a (reduced) sine-Gordon Y-system. Note that the generations, together with all integer tuples, in this implementation are numbered from 0 while in [NS]_ they are numbered from 1 diff --git a/src/sage/combinat/six_vertex_model.py b/src/sage/combinat/six_vertex_model.py index 365cc0dd360..879418f18d9 100644 --- a/src/sage/combinat/six_vertex_model.py +++ b/src/sage/combinat/six_vertex_model.py @@ -361,13 +361,13 @@ class SixVertexModel(UniqueRepresentation, Parent): There are also the following predefined boundary conditions: - * ``'ice'`` -- The top and bottom boundary conditions are outward and the + * ``'ice'`` -- the top and bottom boundary conditions are outward and the left and right boundary conditions are inward; this gives the square ice model. Also called domain wall boundary conditions. - * ``'domain wall'`` -- Same as ``'ice'``. - * ``'alternating'`` -- The boundary conditions alternate between inward + * ``'domain wall'`` -- same as ``'ice'``. + * ``'alternating'`` -- the boundary conditions alternate between inward and outward. - * ``'free'`` -- There are no boundary conditions. + * ``'free'`` -- there are no boundary conditions. EXAMPLES: diff --git a/src/sage/combinat/skew_partition.py b/src/sage/combinat/skew_partition.py index b78e6b84d1f..bee333dc9a5 100644 --- a/src/sage/combinat/skew_partition.py +++ b/src/sage/combinat/skew_partition.py @@ -277,7 +277,6 @@ def _latex_diagram(self): sage: print(SkewPartition([[],[]])._latex_diagram()) {\emptyset} - """ if not any(self._list): return "{\\emptyset}" @@ -392,7 +391,7 @@ def ferrers_diagram(self): *** *** * - sage: SkewPartitions.options(diagram_str='#', convention="French") + sage: SkewPartitions.options(diagram_str='#', convention='French') sage: print(SkewPartition([[5,4,3,1],[3,1]]).diagram()) # ### @@ -441,7 +440,7 @@ def _ascii_art_(self): [ * * * * ] [ ** ** * * * * * * ] [ ***, * , * , **, ** , *, * , * , * ] - sage: SkewPartitions.options(diagram_str='#', convention="French") + sage: SkewPartitions.options(diagram_str='#', convention='French') sage: ascii_art(SkewPartitions(3).list()) [ # # # # ] [ # # ## ## # # # # ] @@ -816,7 +815,7 @@ def inner_corners(self): icorners += [(nn, 0)] return icorners - def cell_poset(self, orientation="SE"): + def cell_poset(self, orientation='SE'): """ Return the Young diagram of ``self`` as a poset. The optional keyword variable ``orientation`` determines the order relation @@ -825,10 +824,10 @@ def cell_poset(self, orientation="SE"): The poset always uses the set of cells of the Young diagram of ``self`` as its ground set. The order relation of the poset depends on the ``orientation`` variable (which defaults to - ``"SE"``). Concretely, ``orientation`` has to be specified to - one of the strings ``"NW"``, ``"NE"``, ``"SW"``, and ``"SE"``, + ``'SE'``). Concretely, ``orientation`` has to be specified to + one of the strings ``'NW'``, ``'NE'``, ``'SW'``, and ``'SE'``, standing for "northwest", "northeast", "southwest" and - "southeast", respectively. If ``orientation`` is ``"SE"``, then + "southeast", respectively. If ``orientation`` is ``'SE'``, then the order relation of the poset is such that a cell `u` is greater or equal to a cell `v` in the poset if and only if `u` lies weakly southeast of `v` (this means that `u` can be @@ -1054,7 +1053,7 @@ def to_list(self): """ return [list(r) for r in list(self)] - def to_dag(self, format="string"): + def to_dag(self, format='string'): """ Return a directed acyclic graph corresponding to the skew partition ``self``. @@ -1081,7 +1080,7 @@ def to_dag(self, format="string"): ('1,1', '1,2', None)] sage: dag.vertices(sort=True) ['0,1', '0,2', '1,1', '1,2', '2,0'] - sage: dag = SkewPartition([[3, 2, 1], [1, 1]]).to_dag(format="tuple") + sage: dag = SkewPartition([[3, 2, 1], [1, 1]]).to_dag(format='tuple') sage: dag.edges(sort=True) [((0, 1), (0, 2), None), ((0, 1), (1, 1), None)] sage: dag.vertices(sort=True) @@ -1414,7 +1413,7 @@ def __init__(self, is_infinite=False): # add options to class class options(GlobalOptions): """ - Sets and displays the options for elements of the skew partition + Set and display the options for elements of the skew partition classes. If no parameters are set, then the function returns a copy of the options dictionary. @@ -1436,7 +1435,7 @@ class options(GlobalOptions): Changing the ``convention`` for skew partitions also changes the ``convention`` option for partitions and tableaux and vice versa:: - sage: SkewPartitions.options(display="diagram", convention='French') + sage: SkewPartitions.options(display='diagram', convention='French') sage: SP * * @@ -1465,24 +1464,24 @@ class options(GlobalOptions): """ NAME = 'SkewPartitions' module = 'sage.combinat.skew_partition' - display = dict(default="quotient", + display = dict(default='quotient', description='Specifies how skew partitions should be printed', values=dict(lists='displayed as a pair of lists', quotient='displayed as a quotient of partitions', diagram='as a skew Ferrers diagram'), - alias=dict(array="diagram", ferrers_diagram="diagram", - young_diagram="diagram", pair="lists"), + alias=dict(array='diagram', ferrers_diagram='diagram', + young_diagram='diagram', pair='lists'), case_sensitive=False) - latex = dict(default="young_diagram", + latex = dict(default='young_diagram', description='Specifies how skew partitions should be latexed', values=dict(diagram='latex as a skew Ferrers diagram', young_diagram='latex as a skew Young diagram', marked='latex as a partition where the skew shape is marked'), - alias=dict(array="diagram", ferrers_diagram="diagram"), + alias=dict(array='diagram', ferrers_diagram='diagram'), case_sensitive=False) diagram_str = dict(link_to=(Partitions.options,'diagram_str')) latex_diagram_str = dict(link_to=(Partitions.options,'latex_diagram_str')) - latex_marking_str = dict(default="X", + latex_marking_str = dict(default='X', description='The character used to marked the deleted cells when latexing marked partitions', checker=lambda char: isinstance(char, str)) convention = dict(link_to=(Tableaux.options,'convention')) @@ -1571,15 +1570,15 @@ def from_row_and_column_length(self, rowL, colL): INPUT: - - ``rowL`` -- A composition or a list of positive integers + - ``rowL`` -- a composition or a list of positive integers - - ``colL`` -- A composition or a list of positive integers + - ``colL`` -- a composition or a list of positive integers OUTPUT: - If it exists the unique skew-partitions with row lengths ``rowL`` and column lengths ``colL``. - - Raise a :class:`ValueError` if ``rowL`` and ``colL`` are not compatible. + - Raise a :exc:`ValueError` if ``rowL`` and ``colL`` are not compatible. EXAMPLES:: @@ -1610,7 +1609,7 @@ def from_row_and_column_length(self, rowL, colL): If some rows and columns have length zero, there is no way to retrieve unambiguously the skew partition. We therefore raise - a :class:`ValueError`. + a :exc:`ValueError`. For examples here are two skew partitions with the same row and column lengths:: @@ -1716,9 +1715,9 @@ class SkewPartitions_n(SkewPartitions): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - - ``overlap`` -- an integer (default: `0`) + - ``overlap`` -- integer (default: `0`) Caveat: this set is stable under conjugation only for ``overlap`` equal to 0 or 1. What exactly happens for negative overlaps is not yet @@ -1768,8 +1767,8 @@ def __init__(self, n, overlap): INPUT: - - ``n`` -- a non-negative integer - - ``overlap`` -- an integer + - ``n`` -- nonnegative integer + - ``overlap`` -- integer TESTS:: diff --git a/src/sage/combinat/skew_tableau.py b/src/sage/combinat/skew_tableau.py index 99ef16b740d..ca57594ed71 100644 --- a/src/sage/combinat/skew_tableau.py +++ b/src/sage/combinat/skew_tableau.py @@ -152,9 +152,7 @@ def __eq__(self, other): - ``other`` -- the element that ``self`` is compared to - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -189,9 +187,7 @@ def __ne__(self, other): - ``other`` -- the element that ``self`` is compared to - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -688,7 +684,7 @@ def is_semistandard(self): def to_tableau(self): """ - Returns a tableau with the same filling. This only works if the + Return a tableau with the same filling. This only works if the inner shape of the skew tableau has size zero. EXAMPLES:: @@ -1069,9 +1065,9 @@ def rectify(self, algorithm=None): INPUT: - - ``algorithm`` -- optional: if set to ``'jdt'``, rectifies by jeu de + - ``algorithm`` -- (optional) if set to ``'jdt'``, rectifies by jeu de taquin; if set to ``'schensted'``, rectifies by Schensted insertion - of the reading word; otherwise, guesses which will be faster. + of the reading word. Otherwise, guesses which will be faster. EXAMPLES:: @@ -1136,7 +1132,6 @@ def to_list(self): [[None, None, 3], [None, 1, 3], [2, 2]] sage: st.to_list() == stlist True - """ return [list(row) for row in self] @@ -1353,8 +1348,8 @@ def standardization(self, check=True): INPUT: - - ``check`` -- (Default: ``True``) Check to make sure ``self`` is - semistandard. Set to ``False`` to avoid this check. + - ``check`` -- (default: ``True``) check to make sure ``self`` is + semistandard; set to ``False`` to avoid this check EXAMPLES:: @@ -1420,17 +1415,17 @@ def bender_knuth_involution(self, k, rows=None, check=True): INPUT: - - ``k`` -- an integer + - ``k`` -- integer - - ``rows`` -- (Default ``None``) When set to ``None``, the method + - ``rows`` -- (default: ``None``) when set to ``None``, the method computes the `k`-th Bender--Knuth involution as defined above. When an iterable, this computes the composition of the `k`-th Bender--Knuth switches at row `i` over all `i` in ``rows``. When set to an integer `i`, the method computes the `k`-th Bender--Knuth switch at row `i`. Note the indexing of the rows starts with `1`. - - ``check`` -- (Default: ``True``) Check to make sure ``self`` is - semistandard. Set to ``False`` to avoid this check. + - ``check`` -- (default: ``True``) check to make sure ``self`` is + semistandard; set to ``False`` to avoid this check OUTPUT: @@ -1686,8 +1681,8 @@ def to_ribbon(self, check_input=True): INPUT: - - ``check_input`` -- (default: ``True``) whether or not to check - that ``self`` indeed has ribbon shape + - ``check_input`` -- boolean (default: ``True``); whether or not to + check that ``self`` indeed has ribbon shape EXAMPLES:: @@ -1833,7 +1828,7 @@ def cells_containing(self, i): def is_k_tableau(self, k): r""" - Checks whether ``self`` is a valid skew weak `k`-tableau. + Check whether ``self`` is a valid skew weak `k`-tableau. EXAMPLES:: @@ -1921,7 +1916,7 @@ def _element_constructor_(self, st): def __contains__(self, x): """ - Checks if ``x`` is a skew tableau. + Check if ``x`` is a skew tableau. EXAMPLES:: @@ -2295,7 +2290,7 @@ def __iter__(self): [[None, 1, 3], [None, 2], [4]], [[None, 2, 4], [None, 3], [1]]] """ - dag = self.skp.to_dag(format="tuple") + dag = self.skp.to_dag(format='tuple') le_list = list(dag.topological_sort_generator()) empty = [[None] * row_length for row_length in self.skp.outer()] @@ -2681,9 +2676,9 @@ class SemistandardSkewTableaux_shape(SemistandardSkewTableaux): INPUT: - - ``p`` -- A skew partition + - ``p`` -- a skew partition - - ``max_entry`` -- The max entry; defaults to the size of ``p``. + - ``max_entry`` -- the max entry; defaults to the size of ``p`` .. WARNING:: diff --git a/src/sage/combinat/sloane_functions.py b/src/sage/combinat/sloane_functions.py index c1aa82e4308..7e35baa2976 100644 --- a/src/sage/combinat/sloane_functions.py +++ b/src/sage/combinat/sloane_functions.py @@ -456,7 +456,7 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -561,11 +561,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -613,11 +611,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -713,9 +709,7 @@ def __init__(self): - ``n`` -- positive integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -816,11 +810,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -873,11 +865,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -938,11 +928,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1015,11 +1003,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1061,7 +1047,7 @@ def _repr_(self): def s2(self, n, k): """ - Returns the Stirling number S2(n,k) of the 2nd kind. + Return the Stirling number S2(n,k) of the 2nd kind. EXAMPLES:: @@ -1093,11 +1079,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1160,16 +1144,14 @@ def __init__(self): to `n`. Number of totatives of `n`. Euler totient function `\phi(n)`: count numbers `n` - and prime to `n`. euler_phi is a standard Sage function - implemented in PARI + and prime to `n`. ``euler_phi`` is a standard Sage function + implemented in PARI. INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1224,11 +1206,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1275,11 +1255,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1330,11 +1308,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1386,11 +1362,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1443,9 +1417,7 @@ def __init__(self): - ``n`` -- integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1497,11 +1469,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1555,11 +1525,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1610,11 +1578,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1663,11 +1629,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1720,11 +1684,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1776,11 +1738,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1829,11 +1789,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -1880,20 +1838,18 @@ def _eval(self, n): class A000012(SloaneSequence): def __init__(self): r""" - The all 1's sequence. + The all 1s sequence. INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: sage: a = sloane.A000012; a - The all 1's sequence. + The all 1s sequence. sage: a(1) 1 sage: a(2007) @@ -1912,9 +1868,9 @@ def _repr_(self): EXAMPLES:: sage: sloane.A000012._repr_() - "The all 1's sequence." + 'The all 1s sequence.' """ - return "The all 1's sequence." + return 'The all 1s sequence.' def _eval(self, n): """ @@ -1929,20 +1885,18 @@ def _eval(self, n): class A000120(SloaneSequence): def __init__(self): r""" - 1's-counting sequence: number of 1's in binary expansion of `n`. + 1s-counting sequence: number of 1s in binary expansion of `n`. INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: sage: a = sloane.A000120;a - 1's-counting sequence: number of 1's in binary expansion of n. + 1s-counting sequence: number of 1s in binary expansion of n. sage: a(0) 0 sage: a(2) @@ -1963,9 +1917,9 @@ def _repr_(self): EXAMPLES:: sage: sloane.A000120._repr_() - "1's-counting sequence: number of 1's in binary expansion of n." + '1s-counting sequence: number of 1s in binary expansion of n.' """ - return "1's-counting sequence: number of 1's in binary expansion of n." + return '1s-counting sequence: number of 1s in binary expansion of n.' def f(self, n): """ @@ -1996,15 +1950,13 @@ def __init__(self): Let `A_k` denote the first `2^k` terms; then `A_0 = 0`, and for `k \ge 0`, `A_{k+1} = A_k B_k`, where `B_k` is obtained - from `A_k` by interchanging 0's and 1's. + from `A_k` by interchanging 0s and 1s. INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2049,20 +2001,18 @@ def _eval(self, n): class A000069(SloaneSequence): def __init__(self): r""" - Odious numbers: odd number of 1's in binary expansion. + Odious numbers: odd number of 1s in binary expansion. INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: sage: a = sloane.A000069; a - Odious numbers: odd number of 1's in binary expansion. + Odious numbers: odd number of 1s in binary expansion. sage: a(0) 1 sage: a(2) @@ -2081,9 +2031,9 @@ def _repr_(self): EXAMPLES:: sage: sloane.A000069._repr_() - "Odious numbers: odd number of 1's in binary expansion." + 'Odious numbers: odd number of 1s in binary expansion.' """ - return "Odious numbers: odd number of 1's in binary expansion." + return 'Odious numbers: odd number of 1s in binary expansion.' def _eval(self, n): """ @@ -2098,20 +2048,18 @@ def _eval(self, n): class A001969(SloaneSequence): def __init__(self): r""" - Evil numbers: even number of 1's in binary expansion. + Evil numbers: even number of 1s in binary expansion. INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: sage: a = sloane.A001969;a - Evil numbers: even number of 1's in binary expansion. + Evil numbers: even number of 1s in binary expansion. sage: a(0) 0 sage: a(1) @@ -2134,9 +2082,9 @@ def _repr_(self): EXAMPLES:: sage: sloane.A001969._repr_() - "Evil numbers: even number of 1's in binary expansion." + 'Evil numbers: even number of 1s in binary expansion.' """ - return "Evil numbers: even number of 1's in binary expansion." + return 'Evil numbers: even number of 1s in binary expansion.' def _eval(self, n): """ @@ -2155,11 +2103,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2208,11 +2154,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2262,11 +2206,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2320,15 +2262,13 @@ def _eval(self, n): class A000016(SloaneSequence): def __init__(self): r""" - Sloane's A000016 + Sloane's A000016. INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2384,11 +2324,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2450,11 +2388,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2506,11 +2442,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2600,11 +2534,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2661,11 +2593,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2717,11 +2647,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2806,11 +2734,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2864,11 +2790,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2930,11 +2854,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -2999,11 +2921,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3055,11 +2975,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3147,11 +3065,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3239,11 +3155,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3293,11 +3207,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3350,11 +3262,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3405,11 +3315,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3488,11 +3396,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3543,15 +3449,13 @@ def _eval(self, n): class A000961(SloaneSequence): def __init__(self): r""" - Prime powers + Prime powers. INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3632,15 +3536,13 @@ def list(self, n): class A005117(SloaneSequence): def __init__(self): r""" - Square-free numbers + Square-free numbers. INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3726,11 +3628,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3816,11 +3716,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3878,11 +3776,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -3934,7 +3830,7 @@ def _precompute(self, how_many=500): def fib(self): """ - Returns a generator over all Fibonacci numbers, starting with 0. + Return a generator over all Fibonacci numbers, starting with 0. EXAMPLES:: @@ -3980,11 +3876,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4034,11 +3928,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4087,11 +3979,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4140,11 +4030,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4195,11 +4083,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4250,11 +4136,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4303,11 +4187,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4354,18 +4236,16 @@ def _eval(self, n): class A000142(SloaneSequence): def __init__(self): r""" - Factorial numbers: `n! = 1 \cdot 2 \cdot 3 \cdots n` + Factorial numbers: `n! = 1 \cdot 2 \cdot 3 \cdots n`. Order of symmetric group `S_n`, number of permutations of `n` letters. INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4414,11 +4294,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4468,11 +4346,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4525,11 +4401,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4582,11 +4456,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4638,11 +4510,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4692,11 +4562,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4745,11 +4613,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4848,11 +4714,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4900,11 +4764,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -4952,11 +4814,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5004,11 +4864,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5125,11 +4983,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5178,11 +5034,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5236,11 +5090,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5298,9 +5150,7 @@ def __init__(self): - ``n`` -- positive integer >= 2 - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5356,11 +5206,9 @@ def __init__(self): INPUT: - - ``n`` -- positive integer >= 3 + - ``n`` -- positive integer `\geq 3` - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5441,11 +5289,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5505,11 +5351,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5570,11 +5414,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5643,11 +5485,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5716,11 +5556,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5789,11 +5627,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5864,11 +5700,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5925,15 +5759,13 @@ def __init__(self): permutations of `n` elements with no fixed points. With offset 1 also the permanent of a (0,1)-matrix of order - `n` with `n` 0's not on a line. + `n` with `n` 0s not on a line. INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -5991,11 +5823,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6051,11 +5881,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6104,11 +5932,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6158,11 +5984,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6221,11 +6045,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6278,11 +6100,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6332,11 +6152,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6450,11 +6268,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6513,11 +6329,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6570,7 +6384,7 @@ def g(self,k): class A001221(SloaneSequence): def __init__(self): r""" - Number of different prime divisors of `n` + Number of different prime divisors of `n`. Also called omega(n) or `\omega(n)`. Maximal number of terms in any factorization of `n`. Number of prime powers @@ -6578,11 +6392,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6640,11 +6452,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6702,9 +6512,7 @@ class A046660(SloaneSequence): - ``n`` -- positive integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6756,11 +6564,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6822,11 +6628,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -6922,11 +6726,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7048,11 +6850,9 @@ def is_powerful(self, n) -> bool: INPUT: - - `n` -- integer - - OUTPUT: + - ``n`` -- integer - ``True`` if `n` is a powerful number, else ``False`` + OUTPUT: ``True`` if `n` is a powerful number, else ``False`` EXAMPLES:: @@ -7077,16 +6877,14 @@ def __init__(self): Numbers `n` such that `\phi(2n-1) < \phi(2n)`, where `\phi` is Euler's totient function. - Euler's totient function is also known as euler_phi, euler_phi is - a standard Sage function. + Euler's totient function is also known as ``euler_phi``; ``euler_phi`` + is a standard Sage function. INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7180,8 +6978,8 @@ def list(self, n): # a group of sequences uses this function: def recur_gen2(a0, a1, a2, a3): r""" - homogeneous general second-order linear recurrence generator with - fixed coefficients + Homogeneous general second-order linear recurrence generator with + fixed coefficients. a(0) = a0, a(1) = a1, a(n) = a2\*a(n-1) + a3\*a(n-2) @@ -7251,11 +7049,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7300,11 +7096,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7350,11 +7144,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7403,11 +7195,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7450,11 +7240,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7502,11 +7290,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7550,11 +7336,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7598,11 +7382,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7648,11 +7430,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7700,11 +7480,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7782,11 +7560,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7837,11 +7613,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7894,11 +7668,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -7945,11 +7717,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8003,11 +7773,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8051,11 +7819,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8109,7 +7875,7 @@ def _eval(self, n): # a group of sequences uses this function: def recur_gen3(a0, a1, a2, a3, a4, a5): r""" - homogeneous general third-order linear recurrence generator with + Homogeneous general third-order linear recurrence generator with fixed coefficients a(0) = a0, a(1) = a1, a(2) = a2, a(n) = a3\*a(n-1) + a4\*a(n-2) + @@ -8137,11 +7903,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8221,11 +7985,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8305,7 +8067,7 @@ def perm_mh(m, h): INPUT: - ``m`` -- positive integer - - ``h`` -- non negative integer + - ``h`` -- nonnegative integer OUTPUT: permanent of the `m \times (m+h)` matrix, etc. @@ -8333,7 +8095,7 @@ def perm_mh(m, h): class A079922(SloaneSequence): r""" - function returns solutions to the Dancing School problem with + Function returns solutions to the Dancing School problem with `n` girls and `n+3` boys. The value is `per(B)`, the permanent of the (0,1)-matrix @@ -8348,9 +8110,7 @@ class A079922(SloaneSequence): - ``n`` -- positive integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8402,7 +8162,7 @@ def _eval(self, n): class A079923(SloaneSequence): r""" - function returns solutions to the Dancing School problem with + Function returns solutions to the Dancing School problem with `n` girls and `n+4` boys. The value is `per(B)`, the permanent of the (0,1)-matrix @@ -8418,9 +8178,7 @@ class A079923(SloaneSequence): - ``n`` -- positive integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8494,11 +8252,9 @@ class A109814(SloaneSequence): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8579,11 +8335,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8687,11 +8441,9 @@ def is_number_of_the_third_kind(self, n) -> bool: INPUT: - - `n` -- positive integer - - OUTPUT: + - ``n`` -- positive integer - ``True`` if `n` is not prime and not a power of 2 + OUTPUT: ``True`` if `n` is not prime and not a power of 2 EXAMPLES:: @@ -8731,11 +8483,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8820,11 +8570,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: @@ -8939,11 +8687,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- `B_n` + OUTPUT: integer; `B_n` EXAMPLES:: @@ -8993,11 +8739,9 @@ def __init__(self): INPUT: - - ``n`` -- non negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - ``integer`` -- `C_n` + OUTPUT: integer; `C_n` EXAMPLES:: @@ -9038,11 +8782,9 @@ def __init__(self): r""" INPUT: - - ``n`` -- non negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``integer`` -- function value + OUTPUT: integer; function value EXAMPLES:: diff --git a/src/sage/combinat/specht_module.py b/src/sage/combinat/specht_module.py index 5b8462754ef..91f0dd93af2 100644 --- a/src/sage/combinat/specht_module.py +++ b/src/sage/combinat/specht_module.py @@ -1165,8 +1165,8 @@ def specht_module_spanning_set(D, SGA=None): INPUT: - - ``D`` -- a list of cells ``(r,c)`` for row ``r`` and column ``c`` - - ``SGA`` -- optional; a symmetric group algebra + - ``D`` -- list of cells ``(r,c)`` for row ``r`` and column ``c`` + - ``SGA`` -- (optional) a symmetric group algebra EXAMPLES:: diff --git a/src/sage/combinat/species/all.py b/src/sage/combinat/species/all.py index 58bfc1a756f..1c3a550d342 100644 --- a/src/sage/combinat/species/all.py +++ b/src/sage/combinat/species/all.py @@ -46,6 +46,6 @@ from sage.misc.lazy_import import lazy_import lazy_import("sage.combinat.species.recursive_species", "CombinatorialSpecies") -lazy_import("sage.combinat.species", "library", as_="species") +lazy_import("sage.combinat.species", "library", as_='species') del lazy_import del install_doc diff --git a/src/sage/combinat/species/characteristic_species.py b/src/sage/combinat/species/characteristic_species.py index 37ce75abe28..a8078bc7313 100644 --- a/src/sage/combinat/species/characteristic_species.py +++ b/src/sage/combinat/species/characteristic_species.py @@ -75,7 +75,7 @@ def transport(self, perm): def automorphism_group(self): """ - Returns the group of permutations whose action on this structure + Return the group of permutations whose action on this structure leave it fixed. For the characteristic species, there is only one structure, so every permutation is in its automorphism group. @@ -169,7 +169,7 @@ def _gs_term(self, base_ring): def _order(self): """ - Returns the order of the generating series. + Return the order of the generating series. EXAMPLES:: @@ -212,7 +212,7 @@ def _cis_term(self, base_ring): def _equation(self, var_mapping): """ - Returns the right hand side of an algebraic equation satisfied by + Return the right hand side of an algebraic equation satisfied by this species. This is a utility function called by the algebraic_equation_system method. @@ -235,7 +235,7 @@ def _equation(self, var_mapping): class EmptySetSpecies(CharacteristicSpecies): def __init__(self, min=None, max=None, weight=None): """ - Returns the empty set species. + Return the empty set species. This species has exactly one structure on the empty set. It is the same (and is implemented) as ``CharacteristicSpecies(0)``. @@ -279,7 +279,7 @@ def __init__(self, min=None, max=None, weight=None): class SingletonSpecies(CharacteristicSpecies): def __init__(self, min=None, max=None, weight=None): """ - Returns the species of singletons. + Return the species of singletons. This species has exactly one structure on a set of size `1`. It is the same (and is implemented) as ``CharacteristicSpecies(1)``. diff --git a/src/sage/combinat/species/composition_species.py b/src/sage/combinat/species/composition_species.py index ccfe0141803..17a240b72dc 100644 --- a/src/sage/combinat/species/composition_species.py +++ b/src/sage/combinat/species/composition_species.py @@ -72,11 +72,11 @@ def change_labels(self, labels): INPUT: - - ``labels``, a list of labels. + - ``labels`` -- list of labels OUTPUT: - A structure with the i-th label of self replaced with the i-th + A structure with the `i`-th label of ``self`` replaced with the `i`-th label of the list. EXAMPLES:: @@ -99,7 +99,7 @@ def change_labels(self, labels): class CompositionSpecies(GenericCombinatorialSpecies, UniqueRepresentation): def __init__(self, F, G, min=None, max=None, weight=None): """ - Returns the composition of two species. + Return the composition of two species. EXAMPLES:: @@ -255,7 +255,7 @@ def _cis(self, series_ring, base_ring): def weight_ring(self): """ - Returns the weight ring for this species. This is determined by + Return the weight ring for this species. This is determined by asking Sage's coercion model what the result is when you multiply (and add) elements of the weight rings for each of the operands. diff --git a/src/sage/combinat/species/cycle_species.py b/src/sage/combinat/species/cycle_species.py index c808f6a0db1..bc27b988d3c 100644 --- a/src/sage/combinat/species/cycle_species.py +++ b/src/sage/combinat/species/cycle_species.py @@ -44,7 +44,7 @@ def canonical_label(self): def permutation_group_element(self): """ - Returns this cycle as a permutation group element. + Return this cycle as a permutation group element. EXAMPLES:: @@ -59,7 +59,7 @@ def permutation_group_element(self): def transport(self, perm): """ - Returns the transport of this structure along the permutation + Return the transport of this structure along the permutation perm. EXAMPLES:: @@ -80,7 +80,7 @@ def transport(self, perm): def automorphism_group(self): """ - Returns the group of permutations whose action on this structure + Return the group of permutations whose action on this structure leave it fixed. EXAMPLES:: @@ -117,7 +117,7 @@ def __classcall__(cls, *args, **kwds): def __init__(self, min=None, max=None, weight=None): """ - Returns the species of cycles. + Return the species of cycles. EXAMPLES:: @@ -201,7 +201,7 @@ def _gs_callable(self, base_ring, n): def _order(self): """ - Returns the order of the generating series. + Return the order of the generating series. EXAMPLES:: diff --git a/src/sage/combinat/species/empty_species.py b/src/sage/combinat/species/empty_species.py index 5c4762cb34d..8ebad9b871d 100644 --- a/src/sage/combinat/species/empty_species.py +++ b/src/sage/combinat/species/empty_species.py @@ -21,7 +21,7 @@ class EmptySpecies(GenericCombinatorialSpecies, UniqueRepresentation): """ - Returns the empty species. This species has no structure at all. + Return the empty species. This species has no structure at all. It is the zero of the semi-ring of species. EXAMPLES:: @@ -98,7 +98,7 @@ def __init__(self, min=None, max=None, weight=None): def _gs(self, series_ring, base_ring): """ - Return the generating series for self. + Return the generating series for ``self``. EXAMPLES:: @@ -135,7 +135,7 @@ def _structures(self, structure_class, labels): def _equation(self, var_mapping): """ - Returns the right hand side of an algebraic equation satisfied by + Return the right hand side of an algebraic equation satisfied by this species. This is a utility function called by the algebraic_equation_system method. diff --git a/src/sage/combinat/species/functorial_composition_species.py b/src/sage/combinat/species/functorial_composition_species.py index b327492a54a..2fc5ede99db 100644 --- a/src/sage/combinat/species/functorial_composition_species.py +++ b/src/sage/combinat/species/functorial_composition_species.py @@ -26,7 +26,7 @@ class FunctorialCompositionStructure(GenericSpeciesStructure): class FunctorialCompositionSpecies(GenericCombinatorialSpecies): def __init__(self, F, G, min=None, max=None, weight=None): """ - Returns the functorial composition of two species. + Return the functorial composition of two species. EXAMPLES:: @@ -124,7 +124,7 @@ def _cis(self, series_ring, base_ring): def weight_ring(self): """ - Returns the weight ring for this species. This is determined by + Return the weight ring for this species. This is determined by asking Sage's coercion model what the result is when you multiply (and add) elements of the weight rings for each of the operands. diff --git a/src/sage/combinat/species/generating_series.py b/src/sage/combinat/species/generating_series.py index 7622efd279b..b970bb36dbf 100644 --- a/src/sage/combinat/species/generating_series.py +++ b/src/sage/combinat/species/generating_series.py @@ -145,7 +145,7 @@ def __init__(self, base_ring): sage: OrdinaryGeneratingSeriesRing.options._reset() # reset options """ - super().__init__(base_ring, names="z") + super().__init__(base_ring, names='z') Element = OrdinaryGeneratingSeries @@ -272,7 +272,7 @@ def __init__(self, base_ring): sage: ExponentialGeneratingSeriesRing.options._reset() # reset options """ - super().__init__(base_ring, names="z") + super().__init__(base_ring, names='z') Element = ExponentialGeneratingSeries diff --git a/src/sage/combinat/species/linear_order_species.py b/src/sage/combinat/species/linear_order_species.py index 0761dea576d..41a0ac49ae4 100644 --- a/src/sage/combinat/species/linear_order_species.py +++ b/src/sage/combinat/species/linear_order_species.py @@ -35,7 +35,7 @@ def canonical_label(self): def transport(self, perm): """ - Returns the transport of this structure along the permutation + Return the transport of this structure along the permutation perm. EXAMPLES:: @@ -51,7 +51,7 @@ def transport(self, perm): def automorphism_group(self): """ - Returns the group of permutations whose action on this structure + Return the group of permutations whose action on this structure leave it fixed. For the species of linear orders, there is no non-trivial automorphism. @@ -81,7 +81,7 @@ def __classcall__(cls, *args, **kwds): def __init__(self, min=None, max=None, weight=None): """ - Returns the species of linear orders. + Return the species of linear orders. EXAMPLES:: diff --git a/src/sage/combinat/species/partition_species.py b/src/sage/combinat/species/partition_species.py index ef9adf66974..d166a99109a 100644 --- a/src/sage/combinat/species/partition_species.py +++ b/src/sage/combinat/species/partition_species.py @@ -72,7 +72,7 @@ def canonical_label(self): def transport(self, perm): """ - Returns the transport of this set partition along the permutation + Return the transport of this set partition along the permutation perm. For set partitions, this is the direct product of the automorphism groups for each of the blocks. @@ -91,7 +91,7 @@ def transport(self, perm): def automorphism_group(self): """ - Returns the group of permutations whose action on this set + Return the group of permutations whose action on this set partition leave it fixed. EXAMPLES:: @@ -113,11 +113,11 @@ def change_labels(self, labels): INPUT: - - ``labels``, a list of labels. + - ``labels`` -- list of labels OUTPUT: - A structure with the i-th label of self replaced with the i-th + A structure with the `i`-th label of ``self`` replaced with the `i`-th label of the list. EXAMPLES:: @@ -146,7 +146,7 @@ def __classcall__(cls, *args, **kwds): def __init__(self, min=None, max=None, weight=None): """ - Returns the species of partitions. + Return the species of partitions. EXAMPLES:: @@ -220,7 +220,7 @@ def _isotypes(self, structure_class, labels): def _canonical_rep_from_partition(self, structure_class, labels, p): """ - Returns the canonical representative corresponding to the partition + Return the canonical representative corresponding to the partition p. EXAMPLES:: @@ -261,7 +261,7 @@ def _itgs_callable(self, base_ring, n): def _cis(self, series_ring, base_ring): r""" - The cycle index series for the species of partitions is given by + The cycle index series for the species of partitions is given by. .. MATH:: diff --git a/src/sage/combinat/species/permutation_species.py b/src/sage/combinat/species/permutation_species.py index eebcc2cddce..7494ee33c08 100644 --- a/src/sage/combinat/species/permutation_species.py +++ b/src/sage/combinat/species/permutation_species.py @@ -44,7 +44,7 @@ def canonical_label(self): def permutation_group_element(self): """ - Returns self as a permutation group element. + Return ``self`` as a permutation group element. EXAMPLES:: @@ -59,7 +59,7 @@ def permutation_group_element(self): def transport(self, perm): """ - Returns the transport of this structure along the permutation + Return the transport of this structure along the permutation perm. EXAMPLES:: @@ -77,7 +77,7 @@ def transport(self, perm): def automorphism_group(self): """ - Returns the group of permutations whose action on this structure + Return the group of permutations whose action on this structure leave it fixed. EXAMPLES:: @@ -119,7 +119,7 @@ def __classcall__(cls, *args, **kwds): def __init__(self, min=None, max=None, weight=None): """ - Returns the species of permutations. + Return the species of permutations. EXAMPLES:: @@ -216,7 +216,7 @@ def _itgs_callable(self, base_ring, n): def _cis(self, series_ring, base_ring): r""" - The cycle index series for the species of permutations is given by + The cycle index series for the species of permutations is given by. .. MATH:: diff --git a/src/sage/combinat/species/product_species.py b/src/sage/combinat/species/product_species.py index 90209e64776..4a17d3c8ed2 100644 --- a/src/sage/combinat/species/product_species.py +++ b/src/sage/combinat/species/product_species.py @@ -123,11 +123,11 @@ def change_labels(self, labels): INPUT: - - ``labels``, a list of labels. + - ``labels`` -- list of labels OUTPUT: - A structure with the i-th label of self replaced with the i-th + A structure with the `i`-th label of ``self`` replaced with the `i`-th label of the list. EXAMPLES:: @@ -235,7 +235,7 @@ def __init__(self, F, G, min=None, max=None, weight=None): def left_factor(self): """ - Returns the left factor of this product. + Return the left factor of this product. EXAMPLES:: @@ -249,7 +249,7 @@ def left_factor(self): def right_factor(self): """ - Returns the right factor of this product. + Return the right factor of this product. EXAMPLES:: @@ -372,7 +372,7 @@ def _cis(self, series_ring, base_ring): def weight_ring(self): """ - Returns the weight ring for this species. This is determined by + Return the weight ring for this species. This is determined by asking Sage's coercion model what the result is when you multiply (and add) elements of the weight rings for each of the operands. @@ -403,7 +403,7 @@ def weight_ring(self): def _equation(self, var_mapping): """ - Returns the right hand side of an algebraic equation satisfied by + Return the right hand side of an algebraic equation satisfied by this species. This is a utility function called by the algebraic_equation_system method. diff --git a/src/sage/combinat/species/recursive_species.py b/src/sage/combinat/species/recursive_species.py index 8eaabf0d2a8..c9bc12a9a4f 100644 --- a/src/sage/combinat/species/recursive_species.py +++ b/src/sage/combinat/species/recursive_species.py @@ -307,16 +307,13 @@ def define(self, x): """ Define ``self`` to be equal to the combinatorial species ``x``. - This is - used to define combinatorial species recursively. All of the real - work is done by calling the .set() method for each of the series - associated to self. + This is used to define combinatorial species recursively. All of the + real work is done by calling the ``.set()`` method for each of the + series associated to ``self``. - EXAMPLES: The species of linear orders L can be recursively defined + EXAMPLES: The species of linear orders `L` can be recursively defined by `L = 1 + X*L` where 1 represents the empty set species - and X represents the singleton species. - - :: + and `X` represents the singleton species:: sage: X = species.SingletonSpecies() sage: E = species.EmptySetSpecies() @@ -421,7 +418,7 @@ def define(self, x): def _add_to_digraph(self, d): """ - Adds this species as a vertex to the digraph d along with any + Add this species as a vertex to the digraph d along with any 'children' of this species. Note that to avoid infinite recursion, we just return if this @@ -454,7 +451,7 @@ def _add_to_digraph(self, d): def _equation(self, var_mapping): """ - Returns the right hand side of an algebraic equation satisfied by + Return the right hand side of an algebraic equation satisfied by this species. This is a utility function called by the algebraic_equation_system method. diff --git a/src/sage/combinat/species/set_species.py b/src/sage/combinat/species/set_species.py index 94aa893cf46..3d45fe6b81a 100644 --- a/src/sage/combinat/species/set_species.py +++ b/src/sage/combinat/species/set_species.py @@ -50,7 +50,7 @@ def canonical_label(self): def transport(self, perm): """ - Returns the transport of this set along the permutation perm. + Return the transport of this set along the permutation perm. EXAMPLES:: @@ -65,7 +65,7 @@ def transport(self, perm): def automorphism_group(self): """ - Returns the group of permutations whose action on this set leave it + Return the group of permutations whose action on this set leave it fixed. For the species of sets, there is only one isomorphism class, so every permutation is in its automorphism group. @@ -95,7 +95,7 @@ def __classcall__(cls, *args, **kwds): def __init__(self, min=None, max=None, weight=None): """ - Returns the species of sets. + Return the species of sets. EXAMPLES:: diff --git a/src/sage/combinat/species/species.py b/src/sage/combinat/species/species.py index 61d70666665..a1760df462f 100644 --- a/src/sage/combinat/species/species.py +++ b/src/sage/combinat/species/species.py @@ -350,9 +350,9 @@ def restricted(self, min=None, max=None): INPUT: - - ``min`` -- optional integer + - ``min`` -- (optional) integer - - ``max`` -- optional integer + - ``max`` -- (optional) integer EXAMPLES:: @@ -501,17 +501,16 @@ def _series_helper(self, series_ring_class, prefix, base_ring=None): INPUT: - - ``series_ring_class`` -- A class for the series - ring such as ExponentialGeneratingSeriesRing, etc. + - ``series_ring_class`` -- a class for the series ring such as + ``ExponentialGeneratingSeriesRing``, etc. - - ``prefix`` -- The string prefix associated with the - generating series such as "cis" for the cycle index series. This - prefix appears in the methods that are implemented in the - subclass. + - ``prefix`` -- the string prefix associated with the generating series + such as "cis" for the cycle index series. This prefix appears in the + methods that are implemented in the subclass. - - ``base_ring`` -- The ring in which the coefficients - of the generating series live. If it is not specified, then it is - determined by the weight of the species. + - ``base_ring`` -- the ring in which the coefficients of the generating + series live. If it is not specified, then it is determined by the + weight of the species. EXAMPLES:: diff --git a/src/sage/combinat/species/structure.py b/src/sage/combinat/species/structure.py index c5629212f5d..d34005ca138 100644 --- a/src/sage/combinat/species/structure.py +++ b/src/sage/combinat/species/structure.py @@ -66,7 +66,7 @@ def __init__(self, parent, labels, list): def parent(self): """ - Returns the species that this structure is associated with. + Return the species that this structure is associated with. EXAMPLES:: @@ -127,9 +127,9 @@ def __ne__(self, other): def labels(self): """ - Returns the labels used for this structure. + Return the labels used for this structure. - .. note:: + .. NOTE:: This includes labels which may not "appear" in this particular structure. @@ -149,11 +149,11 @@ def change_labels(self, labels): INPUT: - - ``labels``, a list of labels. + - ``labels`` -- list of labels OUTPUT: - A structure with the i-th label of self replaced with the i-th + A structure with the `i`-th label of ``self`` replaced with the `i`-th label of the list. EXAMPLES:: @@ -264,7 +264,7 @@ def __getattr__(self, attr): def __repr__(self): """ - Returns the repr of the object which this one wraps. + Return the repr of the object which this one wraps. EXAMPLES:: @@ -304,11 +304,11 @@ def change_labels(self, labels): INPUT: - - ``labels``, a list of labels. + - ``labels`` -- list of labels OUTPUT: - A structure with the i-th label of self replaced with the i-th + A structure with the `i`-th label of ``self`` replaced with the `i`-th label of the list. EXAMPLES:: @@ -334,7 +334,7 @@ def __init__(self, species, labels, iterator, generating_series, name, structure This is a abstract base class for the set of structures of a species as well as the set of isotypes of the species. - .. note:: + .. NOTE:: One typically does not use :class:`SpeciesWrapper` directly, but instead instantiates one of its subclasses: @@ -402,7 +402,7 @@ def _repr_(self) -> str: def labels(self): """ - Returns the labels used on these structures. If `X` is the + Return the labels used on these structures. If `X` is the species, then :meth:`labels` returns the preimage of these structures under the functor `X`. @@ -443,7 +443,7 @@ def __iter__(self): def cardinality(self): """ - Returns the number of structures in this set. + Return the number of structures in this set. EXAMPLES:: diff --git a/src/sage/combinat/species/subset_species.py b/src/sage/combinat/species/subset_species.py index 2e7a6697e29..5515f1c9d96 100644 --- a/src/sage/combinat/species/subset_species.py +++ b/src/sage/combinat/species/subset_species.py @@ -215,7 +215,7 @@ def _itgs_callable(self, base_ring, n): def _cis(self, series_ring, base_ring): r""" - The cycle index series for the species of subsets satisfies + The cycle index series for the species of subsets satisfies. .. MATH:: diff --git a/src/sage/combinat/species/sum_species.py b/src/sage/combinat/species/sum_species.py index b3ff129dc55..c54e7245a55 100644 --- a/src/sage/combinat/species/sum_species.py +++ b/src/sage/combinat/species/sum_species.py @@ -27,7 +27,7 @@ class SumSpeciesStructure(SpeciesStructureWrapper): class SumSpecies(GenericCombinatorialSpecies, UniqueRepresentation): def __init__(self, F, G, min=None, max=None, weight=None): """ - Returns the sum of two species. + Return the sum of two species. EXAMPLES:: @@ -64,7 +64,7 @@ def __init__(self, F, G, min=None, max=None, weight=None): def left_summand(self): """ - Returns the left summand of this species. + Return the left summand of this species. EXAMPLES:: @@ -77,7 +77,7 @@ def left_summand(self): def right_summand(self): """ - Returns the right summand of this species. + Return the right summand of this species. EXAMPLES:: @@ -115,10 +115,10 @@ def _structures(self, structure_class, labels): [[1, 2], [2, 1], [1, 2], [2, 1]] """ for res in self.left_summand().structures(labels): - yield structure_class(self, res, tag="left") + yield structure_class(self, res, tag='left') for res in self.right_summand().structures(labels): - yield structure_class(self, res, tag="right") + yield structure_class(self, res, tag='right') def _isotypes(self, structure_class, labels): """ @@ -130,14 +130,14 @@ def _isotypes(self, structure_class, labels): [[2, 1], [1, 2], [2, 1], [1, 2]] """ for res in self._F.isotypes(labels): - yield structure_class(self, res, tag="left") + yield structure_class(self, res, tag='left') for res in self._G.isotypes(labels): - yield structure_class(self, res, tag="right") + yield structure_class(self, res, tag='right') def _gs(self, series_ring, base_ring): """ - Returns the cycle index series of this species. + Return the cycle index series of this species. EXAMPLES:: @@ -151,7 +151,7 @@ def _gs(self, series_ring, base_ring): def _itgs(self, series_ring, base_ring): """ - Returns the isomorphism type generating series of this species. + Return the isomorphism type generating series of this species. EXAMPLES:: @@ -165,7 +165,7 @@ def _itgs(self, series_ring, base_ring): def _cis(self, series_ring, base_ring): """ - Returns the generating series of this species. + Return the generating series of this species. EXAMPLES:: @@ -183,7 +183,7 @@ def _cis(self, series_ring, base_ring): def weight_ring(self): """ - Returns the weight ring for this species. This is determined by + Return the weight ring for this species. This is determined by asking Sage's coercion model what the result is when you add elements of the weight rings for each of the operands. @@ -206,7 +206,7 @@ def weight_ring(self): def _equation(self, var_mapping): """ - Returns the right hand side of an algebraic equation satisfied by + Return the right hand side of an algebraic equation satisfied by this species. This is a utility function called by the algebraic_equation_system method. diff --git a/src/sage/combinat/subset.py b/src/sage/combinat/subset.py index 57ea1f5393d..5fea2f5f97b 100644 --- a/src/sage/combinat/subset.py +++ b/src/sage/combinat/subset.py @@ -50,7 +50,7 @@ def Subsets(s, k=None, submultiset=False): r""" Return the combinatorial class of the subsets of the finite set ``s``. The set can be given as a list, Set or any iterable - convertible to a set. Alternatively, a non-negative integer `n` + convertible to a set. Alternatively, a nonnegative integer `n` can be provided in place of ``s``; in this case, the result is the combinatorial class of the subsets of the set `\{1,2,\dots,n\}` (i.e. of the Sage ``range(1,n+1)``). @@ -153,7 +153,7 @@ def Subsets(s, k=None, submultiset=False): if isinstance(s, (int, Integer)): if s < 0: - raise ValueError("s must be non-negative") + raise ValueError("s must be nonnegative") from sage.sets.integer_range import IntegerRange s = IntegerRange(1,s+1) @@ -254,7 +254,7 @@ def underlying_set(self): def __eq__(self, other): r""" - Equality test + Equality test. TESTS:: @@ -271,7 +271,7 @@ def __eq__(self, other): def __ne__(self, other): r""" - Difference test + Difference test. TESTS:: @@ -357,7 +357,7 @@ def cardinality(self): def first(self): """ - Returns the first subset of ``s``. Since we aren't restricted to + Return the first subset of ``s``. Since we aren't restricted to subsets of a certain size, this is always the empty set. EXAMPLES:: @@ -395,7 +395,6 @@ def __iter__(self): [{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}] sage: [sub for sub in Subsets([1,2,3,3])] [{}, {1}, {2}, {3}, {1, 2}, {1, 3}, {2, 3}, {1, 2, 3}] - """ k = ZZ_0 while k <= self._s.cardinality(): @@ -474,7 +473,6 @@ def unrank(self, r): Traceback (most recent call last): ... IndexError: index out of range - """ r = Integer(r) if r >= self.cardinality() or r < 0: @@ -524,7 +522,7 @@ def _element_constructor_(self,X): def _an_element_(self): """ - Returns an example of subset. + Return an example of subset. EXAMPLES:: @@ -554,7 +552,6 @@ def lattice(self): sage: Y = Subsets(0) sage: Y.lattice() # needs sage.combinat sage.graphs Finite lattice containing 1 elements - """ S = self.underlying_set() return S.subsets_lattice() @@ -605,7 +602,7 @@ def __init__(self, s, k): Subsets_s.__init__(self, s) self._k = Integer(k) if self._k < 0: - raise ValueError("the integer k (={}) should be non-negative".format(k)) + raise ValueError("the integer k (={}) should be nonnegative".format(k)) def _repr_(self): """ @@ -632,7 +629,7 @@ def __contains__(self, value): def __eq__(self, other): r""" - Equality test + Equality test. TESTS:: @@ -647,7 +644,7 @@ def __eq__(self, other): def __ne__(self, other): r""" - Difference test + Difference test. TESTS:: @@ -760,7 +757,7 @@ def _fast_iterator(self): def __iter__(self): """ - Iterates through the subsets of s of size k. + Iterate through the subsets of s of size k. EXAMPLES:: @@ -858,7 +855,7 @@ def unrank(self, r): def an_element(self): """ - Returns an example of subset. + Return an example of subset. EXAMPLES:: @@ -895,7 +892,7 @@ def list_to_dict(l): INPUT: - a list ``l`` with possibly repeated elements + - ``l`` -- list with possibly repeated elements The keys are the elements of ``l`` (in the same order in which they appear) and values are the multiplicities of each element in ``l``. @@ -1323,7 +1320,6 @@ def __iter__(self): sage: Subsets([3,2,2], submultiset=True).list() [[], [3], [2], [3, 2], [2, 2], [3, 2, 2]] - """ from sage.combinat.integer_vector import IntegerVectors elts = self._keys @@ -1479,7 +1475,7 @@ def powerset(X): INPUT: - - ``X`` -- an iterable + - ``X`` -- an iterable OUTPUT: iterator of lists diff --git a/src/sage/combinat/subsets_hereditary.py b/src/sage/combinat/subsets_hereditary.py index 33b576e3cf1..b02cf538f42 100644 --- a/src/sage/combinat/subsets_hereditary.py +++ b/src/sage/combinat/subsets_hereditary.py @@ -26,12 +26,12 @@ def subsets_with_hereditary_property(f, X, max_obstruction_size=None, ncpus=1): INPUT: - - ``f`` -- a boolean function which takes as input a list of elements from - ``X``. + - ``f`` -- boolean function which takes as input a list of elements from + ``X`` - - ``X`` -- a list/iterable. + - ``X`` -- list/iterable - - ``max_obstruction_size`` (integer) -- if you know that there is + - ``max_obstruction_size`` -- integer; if you know that there is a `k` such that `f(S)` is true if and only if `f(S')` is true for all `S'\subseteq S` with `S'\leq k`, set ``max_obstruction_size=k``. It may dramatically decrease the diff --git a/src/sage/combinat/subsets_pairwise.py b/src/sage/combinat/subsets_pairwise.py index ed5613157f2..d8fec5c1a0c 100644 --- a/src/sage/combinat/subsets_pairwise.py +++ b/src/sage/combinat/subsets_pairwise.py @@ -21,13 +21,13 @@ class PairwiseCompatibleSubsets(RecursivelyEnumeratedSet_forest): INPUT: - - ``ambient`` -- a set (or iterable) + - ``ambient`` -- set (or iterable) - ``predicate`` -- a binary predicate Assumptions: ``predicate`` is symmetric (``predicate(x,y) == predicate(y,x)``) and reflexive (``predicate(x,x) == True``). - .. note:: in fact, ``predicate(x,x)`` is never called. + .. NOTE:: in fact, ``predicate(x,x)`` is never called. .. warning:: The current name is suboptimal and is subject to change. Suggestions for a good name, and a good user entry @@ -68,11 +68,11 @@ class PairwiseCompatibleSubsets(RecursivelyEnumeratedSet_forest): organizing them in a search tree. Each node of this tree is of the form ``(subset, rest)``, where: - - ``subset`` represents an element of ``self``, represented - by an increasing tuple - - ``rest`` is the set of all `y`'s such that `y` appears - after `x` in the ambient set and ``predicate(x,y)`` - holds, represented by a decreasing tuple + - ``subset`` represents an element of ``self``, represented + by an increasing tuple + - ``rest`` is the set of all `y`'s such that `y` appears + after `x` in the ambient set and ``predicate(x,y)`` + holds, represented by a decreasing tuple The root of this tree is ``( (), ambient )``. All the other elements are generated by recursive depth first search, which gives @@ -96,7 +96,6 @@ def __init__(self, ambient, predicate, maximal=False, element_class=Set_object_e An enumerated set with a forest structure sage: import __main__; __main__.predicate = predicate sage: TestSuite(P).run() - """ self._ambient = set(ambient) self._roots = ( ((), tuple(reversed(ambient))), ) @@ -124,7 +123,7 @@ def __eq__(self, other): def __contains__(self, subset): """ - Membership testing + Membership testing. Returns whether subset is a subset of ``self._ambient``, and ``predicate(x,y)`` holds for every ``x,y`` in ``self``. @@ -163,7 +162,7 @@ def post_process(self, subset_rest): def children(self, subset_rest): """ - Returns the children of a node in the tree. + Return the children of a node in the tree. TESTS:: @@ -173,7 +172,6 @@ def children(self, subset_rest): An enumerated set with a forest structure sage: list(P.children( ((3,5), [14,11,7]) )) [((3, 5, 7), (11,)), ((3, 5, 11), (14,)), ((3, 5, 14), ())] - """ (subset, rest) = subset_rest predicate = self._predicate diff --git a/src/sage/combinat/subword_complex.py b/src/sage/combinat/subword_complex.py index ff77970776e..8dcbd2d64cd 100644 --- a/src/sage/combinat/subword_complex.py +++ b/src/sage/combinat/subword_complex.py @@ -158,7 +158,7 @@ class SubwordComplexFacet(Simplex, Element): def __init__(self, parent, positions, facet_test=True): r""" - Initializes a facet of the subword complex ``parent``. + Initialize a facet of the subword complex ``parent``. EXAMPLES:: @@ -400,7 +400,7 @@ def kappa_preimage(self): N = len(W.long_element(as_word=True)) root_conf = self._root_configuration_indices() return [~w for w in W - if all(w.action_on_root_indices(i, side="left") < N + if all(w.action_on_root_indices(i, side='left') < N for i in root_conf)] def is_vertex(self): @@ -525,7 +525,7 @@ def extended_weight_configuration(self, coefficients=None): INPUT: - - coefficients -- (optional) a list of coefficients used to + - ``coefficients`` -- (optional) a list of coefficients used to scale the fundamental weights .. SEEALSO:: @@ -654,7 +654,7 @@ def brick_vector(self, coefficients=None): INPUT: - - coefficients -- (optional) a list of coefficients used to + - ``coefficients`` -- (optional) a list of coefficients used to scale the fundamental weights .. SEEALSO:: @@ -695,9 +695,9 @@ def flip(self, i, return_position=False): INPUT: - - ``i`` -- position in the word `Q` (integer). - - ``return_position`` -- boolean (default: ``False``) tells - whether the new position should be returned as well. + - ``i`` -- integer; position in the word `Q` + - ``return_position`` -- boolean (default: ``False``); tells + whether the new position should be returned as well OUTPUT: @@ -751,20 +751,20 @@ def plot(self, list_colors=None, labels=[], thickness=3, fontsize=14, INPUT: - - ``list_colors`` -- list (default: ``[]``) to change the colors - of the pseudolines. - - ``labels`` -- list (default: ``[]``) to change the labels - of the pseudolines. - - ``thickness`` -- integer (default: ``3``) for the thickness - of the pseudolines. - - ``fontsize`` -- integer (default: ``14``) for the size - of the font used for labels. + - ``list_colors`` -- list (default: ``[]``); to change the colors + of the pseudolines + - ``labels`` -- list (default: ``[]``); to change the labels + of the pseudolines + - ``thickness`` -- integer (default: 3); for the thickness + of the pseudolines + - ``fontsize`` -- integer (default: 14); for the size + of the font used for labels - ``shift`` -- couple of coordinates (default: ``(0,0)``) - to change the origin. - - ``compact`` -- boolean (default: ``False``) to require - a more compact representation. - - ``roots`` -- boolean (default: ``True``) to print - the extended root configuration. + to change the origin + - ``compact`` -- boolean (default: ``False``); to require + a more compact representation + - ``roots`` -- boolean (default: ``True``); whether to print + the extended root configuration EXAMPLES:: @@ -956,11 +956,11 @@ def plot(self, list_colors=None, labels=[], thickness=3, fontsize=14, if type in ['B', 'C']: L += line(pseudolines_type_B[pseudoline], color=list_colors[pseudoline], - thickness=thickness, linestyle="--") + thickness=thickness, linestyle='--') for root_label in root_labels: L += text(root_label[0], root_label[1], rgbcolor=[0, 0, 0], - fontsize=fontsize, vertical_alignment="center", - horizontal_alignment="right") + fontsize=fontsize, vertical_alignment='center', + horizontal_alignment='right') if len(labels) < last + 1: labels = list(range(1, last + 2)) for pseudoline_label in pseudoline_labels: @@ -968,15 +968,15 @@ def plot(self, list_colors=None, labels=[], thickness=3, fontsize=14, color=list_colors[pseudoline_label[0]], fontsize=fontsize, vertical_alignment=pseudoline_label[2], - horizontal_alignment="right") + horizontal_alignment='right') if labels is not False: for pseudoline in range(last): L += text(labels[pseudoline], (shift[0] + x_max + .1, shift[1] + permutation.inverse()(pseudoline + 1) - 1), color=list_colors[pseudoline], fontsize=fontsize, - vertical_alignment="center", - horizontal_alignment="left") + vertical_alignment='center', + horizontal_alignment='left') L.axes(False) return L @@ -1063,7 +1063,7 @@ class SubwordComplex(UniqueRepresentation, SimplicialComplex): # standard functions @staticmethod - def __classcall__(cls, Q, w, algorithm="inductive"): + def __classcall__(cls, Q, w, algorithm='inductive'): r""" Making the input hashable. @@ -1085,17 +1085,17 @@ def __classcall__(cls, Q, w, algorithm="inductive"): Q = tuple(Q) return super().__classcall__(cls, Q, w, algorithm=algorithm) - def __init__(self, Q, w, algorithm="inductive"): + def __init__(self, Q, w, algorithm='inductive'): r""" Initialize the subword complex `\mathcal{SC}(Q,w)`. INPUT: - - ``Q`` -- word on the simple generators of the Coxeter group. - - ``w`` -- element of the Coxeter group. - - ``algorithm`` -- (default: ``"inductive"``) choice of the + - ``Q`` -- word on the simple generators of the Coxeter group + - ``w`` -- element of the Coxeter group + - ``algorithm`` -- (default: ``'inductive'``) choice of the algorithm to generate the subword complex. Options are - ``"inductive"`` or ``"greedy"``. The second option is + ``'inductive'`` or ``'greedy'``. The second option is recommended when `|Q|` is closed to `\ell(w) + \mathrm{rank}(W)`. EXAMPLES:: @@ -1201,13 +1201,11 @@ def __call__(self, F, facet_test=True): INPUT: - - ``F`` -- an iterable of positions. - - ``facet_test`` -- boolean (default: ``True``) tells whether or - not the facet ``F`` should be tested before creation. + - ``F`` -- an iterable of positions + - ``facet_test`` -- boolean (default: ``True``); whether or + not the facet ``F`` should be tested before creation - OUTPUT: - - the facet of ``self`` at positions given by ``F``. + OUTPUT: the facet of ``self`` at positions given by ``F`` EXAMPLES:: @@ -1229,7 +1227,7 @@ def __call__(self, F, facet_test=True): def __contains__(self, F): r""" - Tests if ``self`` contains a given iterable ``F``. + Test if ``self`` contains a given iterable ``F``. EXAMPLES:: @@ -1417,7 +1415,7 @@ def __iter__(self): """ return iter(self.facets()) - def greedy_facet(self, side="positive"): + def greedy_facet(self, side='positive'): r""" Return the negative (or positive) greedy facet of ``self``. @@ -1429,17 +1427,17 @@ def greedy_facet(self, side="positive"): sage: W = ReflectionGroup(['A',2]) sage: w = W.from_reduced_word([1,2,1]) sage: SC = SubwordComplex([1,2,1,2,1], w) - sage: SC.greedy_facet(side="positive") + sage: SC.greedy_facet(side='positive') (0, 1) - sage: SC.greedy_facet(side="negative") + sage: SC.greedy_facet(side='negative') (3, 4) sage: W = CoxeterGroup(['A',2]) sage: w = W.from_reduced_word([1,2,1]) sage: SC = SubwordComplex([1,2,1,2,1], w) - sage: SC.greedy_facet(side="positive") + sage: SC.greedy_facet(side='positive') (0, 1) - sage: SC.greedy_facet(side="negative") + sage: SC.greedy_facet(side='negative') (3, 4) """ return self.element_class(self, _greedy_facet(self.word(), @@ -1567,7 +1565,7 @@ def is_root_independent(self): True """ from sage.matrix.constructor import matrix - M = matrix(self.greedy_facet(side="negative").root_configuration()) + M = matrix(self.greedy_facet(side='negative').root_configuration()) return M.rank() == max(M.ncols(), M.nrows()) @cached_method @@ -1683,7 +1681,7 @@ def brick_vectors(self, coefficients=None): INPUT: - - coefficients -- (optional) a list of coefficients used to + - ``coefficients`` -- (optional) a list of coefficients used to scale the fundamental weights .. SEEALSO:: @@ -1715,7 +1713,7 @@ def minkowski_summand(self, i): INPUT: - `i` -- an integer defining a position in the word `Q` + - ``i`` -- an integer defining a position in the word `Q` EXAMPLES:: @@ -1748,7 +1746,7 @@ def brick_polytope(self, coefficients=None): INPUT: - - coefficients -- (optional) a list of coefficients used to + - ``coefficients`` -- (optional) a list of coefficients used to scale the fundamental weights .. SEEALSO:: @@ -1827,12 +1825,10 @@ def cover_relations(self, label=False): INPUT: - - label -- boolean (default ``False``) whether or not to label + - ``label`` -- boolean (default: ``False``); whether or not to label the cover relations by the position of flip - OUTPUT: - - a list of pairs of facets + OUTPUT: list of pairs of facets EXAMPLES:: @@ -1855,7 +1851,7 @@ def cover_relations(self, label=False): ((2, 3), (3, 4))] """ N = len(self.group().long_element(as_word=True)) - F = self.greedy_facet(side="positive") + F = self.greedy_facet(side='positive') Fs = {F} seen = {F} covers = [] @@ -1878,9 +1874,7 @@ def increasing_flip_graph(self, label=True): """ Return the increasing flip graph of the subword complex. - OUTPUT: - - a directed graph + OUTPUT: a directed graph EXAMPLES:: @@ -1905,9 +1899,7 @@ def interval(self, I, J) -> set: - I, J -- two facets - OUTPUT: - - a set of facets + OUTPUT: a set of facets EXAMPLES:: @@ -1932,9 +1924,7 @@ def increasing_flip_poset(self): """ Return the increasing flip poset of the subword complex. - OUTPUT: - - a poset + OUTPUT: a poset EXAMPLES:: @@ -1956,7 +1946,7 @@ def increasing_flip_poset(self): return Poset(((), cov), facade=True) -def _greedy_facet(Q, w, side="negative", n=None, pos=0, l=None, elems=[]): +def _greedy_facet(Q, w, side='negative', n=None, pos=0, l=None, elems=[]): r""" Return the (positive or negative) *greedy facet* of the subword complex `SC(Q, w)`. @@ -1965,15 +1955,13 @@ def _greedy_facet(Q, w, side="negative", n=None, pos=0, l=None, elems=[]): - ``Q`` -- a word - ``w`` -- an element in the Coxeter group - - ``side`` -- optional, either ``'negative'`` (default) or ``'positive'`` - - ``n`` -- an integer (default: the length of `Q`) - - ``pos`` -- an integer (default: 0) - - ``l`` -- an integer (default: the length of `w`) - - ``elems`` -- a list (optional) + - ``side`` -- string; either ``'negative'`` (default) or ``'positive'`` + - ``n`` -- integer (default: the length of `Q`) + - ``pos`` -- integer (default: 0) + - ``l`` -- integer (default: the length of `w`) + - ``elems`` -- list (optional) - OUTPUT: - - - a set + OUTPUT: a set EXAMPLES:: @@ -2038,9 +2026,7 @@ def _extended_root_configuration_indices(W, Q, F): - ``Q`` -- a word representing an element of `W` - ``F`` -- a facet of the subword complex - OUTPUT: - - a list of root indices + OUTPUT: list of root indices EXAMPLES:: @@ -2067,7 +2053,7 @@ def _extended_root_configuration_indices(W, Q, F): pi = W.one() for i, wi in enumerate(Q): V_roots.append(pi.action_on_root_indices(W.simple_root_index(wi), - side="left")) + side='left')) if i not in F: pi = pi.apply_simple_reflection_right(wi) return V_roots @@ -2080,9 +2066,7 @@ def _greedy_flip_algorithm(Q, w): - ``Q`` -- a word in a Coxeter group `W` - ``w`` -- an element of `W` - OUTPUT: - - a pair: the list of facets and the list of extended root conf. indices + OUTPUT: a pair: the list of facets and the list of extended root conf. indices EXAMPLES:: @@ -2112,7 +2096,7 @@ def _greedy_flip_algorithm(Q, w): [0, 2, 1, 0, 5]]) """ W = w.parent() - F = _greedy_facet(Q, w, side="positive") + F = _greedy_facet(Q, w, side='positive') R = _extended_root_configuration_indices(W, Q, F) facet_list = [F] extended_root_conf_indices_list = [R] @@ -2122,7 +2106,7 @@ def _greedy_flip_algorithm(Q, w): has_new_child = False for i in sorted(F): if (not has_new_child) and (i >= next_index): - j = _flip_c(W, F, R, i, side="positive") + j = _flip_c(W, F, R, i, side='positive') if j != i: flip_to_ancestors.append(j) next_index = i + 1 @@ -2132,6 +2116,6 @@ def _greedy_flip_algorithm(Q, w): if not has_new_child: i = flip_to_ancestors.pop() if i != -1: - j = _flip_c(W, F, R, i, side="negative") + j = _flip_c(W, F, R, i, side='negative') next_index = j + 1 return facet_list, extended_root_conf_indices_list diff --git a/src/sage/combinat/subword_complex_c.pyx b/src/sage/combinat/subword_complex_c.pyx index 5b155efda75..17d18c50c77 100644 --- a/src/sage/combinat/subword_complex_c.pyx +++ b/src/sage/combinat/subword_complex_c.pyx @@ -1,7 +1,7 @@ # sage.doctest: needs sage.modules cpdef int _flip_c(W, set positions, list extended_root_conf_indices, - int i, side="both") noexcept: + int i, side='both') noexcept: r""" Flip a facet. @@ -11,11 +11,9 @@ cpdef int _flip_c(W, set positions, list extended_root_conf_indices, - ``positions`` -- the positions of the elements of the facet - ``extended_root_conf_indices`` -- also attached to the facet ? - ``i`` -- the position where to flip - - ``side`` -- optional, can be ``'positive'``, ``'negative'`` or ``'both'`` (default) + - ``side`` -- string; ``'positive'``, ``'negative'``, or ``'both'`` (default) - OUTPUT: - - the new position `j` that has replaced `i` + OUTPUT: the new position `j` that has replaced `i` EXAMPLES:: @@ -59,7 +57,7 @@ cpdef int _flip_c(W, set positions, list extended_root_conf_indices, if j != i: t = R[min(r, r_minus)] for k in range(min(i, j) + 1, max(i, j) + 1): - extended_root_conf_indices[k] = t.action_on_root_indices(extended_root_conf_indices[k], side="left") + extended_root_conf_indices[k] = t.action_on_root_indices(extended_root_conf_indices[k], side='left') return j diff --git a/src/sage/combinat/super_tableau.py b/src/sage/combinat/super_tableau.py index ffcdb0fc374..280654fcc5e 100644 --- a/src/sage/combinat/super_tableau.py +++ b/src/sage/combinat/super_tableau.py @@ -184,13 +184,13 @@ def check(self): Traceback (most recent call last): ... ValueError: the entries of a semistandard super tableau must be - non-negative primed integers + nonnegative primed integers """ super().check() for row in self: if not all(isinstance(c, PrimedEntry) and c > 0 for c in row): raise ValueError("the entries of a semistandard super tableau" - " must be non-negative primed integers") + " must be nonnegative primed integers") if any(row[c] > row[c + 1] for c in range(len(row) - 1)): raise ValueError("the entries in each row of a semistandard" " super tableau must be weakly increasing") @@ -419,7 +419,7 @@ class SemistandardSuperTableaux_all(SemistandardSuperTableaux): def __init__(self): r""" - Initializes the class of all semistandard super tableaux. + Initialize the class of all semistandard super tableaux. TESTS:: @@ -455,7 +455,7 @@ class StandardSuperTableaux(SemistandardSuperTableaux, Parent): INPUT: - - ``n`` -- a non-negative integer or a partition. + - ``n`` -- a nonnegative integer or a partition EXAMPLES:: @@ -519,12 +519,12 @@ def __classcall_private__(cls, n=None): sage: StandardSuperTableaux(-1) Traceback (most recent call last): ... - ValueError: the argument must be a non-negative integer or a + ValueError: the argument must be a nonnegative integer or a partition sage: StandardSuperTableaux([[1]]) Traceback (most recent call last): ... - ValueError: the argument must be a non-negative integer or a + ValueError: the argument must be a nonnegative integer or a partition """ from sage.combinat.partition import _Partitions @@ -541,7 +541,7 @@ def __classcall_private__(cls, n=None): "partitions is not implemented yet") if not isinstance(n, (int, Integer)) or n < 0: - raise ValueError("the argument must be a non-negative integer" + raise ValueError("the argument must be a nonnegative integer" " or a partition") return StandardSuperTableaux_size(n) @@ -601,7 +601,7 @@ class StandardSuperTableaux_all(StandardSuperTableaux, def __init__(self): r""" - Initializes the class of all standard super tableaux. + Initialize the class of all standard super tableaux. TESTS:: @@ -654,7 +654,7 @@ class StandardSuperTableaux_size(StandardSuperTableaux, def __init__(self, n): r""" - Initializes the class of all standard super tableaux of size ``n``. + Initialize the class of all standard super tableaux of size ``n``. TESTS:: @@ -735,7 +735,7 @@ class StandardSuperTableaux_shape(StandardSuperTableaux): def __init__(self, p): r""" - Initializes the class of all standard super tableaux of a given shape. + Initialize the class of all standard super tableaux of a given shape. TESTS:: diff --git a/src/sage/combinat/superpartition.py b/src/sage/combinat/superpartition.py index e16e87fa9f0..b270c17d68b 100644 --- a/src/sage/combinat/superpartition.py +++ b/src/sage/combinat/superpartition.py @@ -121,7 +121,7 @@ class SuperPartition(ClonableArray, @staticmethod def __classcall_private__(cls, lst): r""" - Construct a superpartition in the correct parent + Construct a superpartition in the correct parent. EXAMPLES:: @@ -323,7 +323,7 @@ def to_composition(self) -> Composition: sage: SuperPartition([[2,1,0],[3,3]]).to_composition() [2, 1, 0, 3, 3] sage: SuperPartition([[2,1,0],[3,3]]).to_composition().parent() - Compositions of non-negative integers + Compositions of nonnegative integers """ return Composition(self[0] + self[1]) @@ -332,9 +332,7 @@ def to_partition(self) -> Partition: Concatenate and sort the antisymmetric and symmetric parts to a partition. - OUTPUT: - - - a partition + OUTPUT: a partition EXAMPLES:: @@ -351,9 +349,7 @@ def antisymmetric_part(self) -> list: r""" The antisymmetric part as a list of strictly decreasing integers. - OUTPUT: - - - a list + OUTPUT: list EXAMPLES:: @@ -370,9 +366,7 @@ def symmetric_part(self) -> list: r""" The symmetric part as a list of weakly decreasing integers. - OUTPUT: - - - a list + OUTPUT: list EXAMPLES:: @@ -392,9 +386,7 @@ def bosonic_degree(self) -> int: The *bosonic degree* is the sum of the sizes of the antisymmetric and symmetric parts. - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -413,9 +405,7 @@ def fermionic_degree(self) -> int: The *fermionic degree* is the length of the antisymmetric part. - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -433,9 +423,7 @@ def bi_degree(self) -> tuple: Return the bidegree of ``self``, which is a pair consisting of the bosonic and fermionic degree. - OUTPUT: - - - a tuple of two integers + OUTPUT: a tuple of two integers EXAMPLES:: @@ -451,9 +439,7 @@ def length(self) -> int: Return the length of ``self``, which is the sum of the lengths of the antisymmetric and symmetric part. - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -468,9 +454,7 @@ def bosonic_length(self) -> int: r""" Return the length of the partition of the symmetric part. - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -485,9 +469,7 @@ def shape_circled_diagram(self) -> Partition: r""" A concatenated partition with an extra cell for each antisymmetric part - OUTPUT: - - - a partition + OUTPUT: a partition EXAMPLES:: @@ -512,11 +494,9 @@ def from_circled_diagram(shape, corners) -> SuperPartition: INPUT: - ``shape`` -- a partition or list of integers - - ``corners`` -- a list of removable cells of ``shape`` - - OUTPUT: + - ``corners`` -- list of removable cells of ``shape`` - - a :class:`SuperPartition` + OUTPUT: a :class:`SuperPartition` EXAMPLES:: @@ -541,9 +521,7 @@ def to_circled_diagram(self) -> list: and a list of removable cells of the partition indicating the location of the circled cells - OUTPUT: - - - a list consisting of a partition and a list of pairs of integers + OUTPUT: list consisting of a partition and a list of pairs of integers EXAMPLES:: @@ -566,9 +544,7 @@ def conjugate(self) -> SuperPartition: The *conjugate* of a super partition is defined by conjugating the circled diagram. - OUTPUT: - - - a :class:`SuperPartition` + OUTPUT: a :class:`SuperPartition` EXAMPLES:: @@ -588,9 +564,7 @@ def zee(self) -> Integer: Return the centralizer size of a permutation of cycle type symmetric part of ``self``. - OUTPUT: - - - a positive integer + OUTPUT: a positive integer EXAMPLES:: @@ -608,9 +582,7 @@ def sign(self) -> int: Return the sign of a permutation of cycle type the symmetric part of ``self``. - OUTPUT: - - - either `1` or `-1` + OUTPUT: either `1` or `-1` EXAMPLES:: @@ -659,9 +631,7 @@ def add_horizontal_border_strip_star(self, h) -> list: - ``h`` -- number of cells in the horizontal strip - OUTPUT: - - - a list of super partitions + OUTPUT: list of super partitions EXAMPLES:: @@ -707,9 +677,7 @@ def add_horizontal_border_strip_star_bar(self, h) -> list: - ``h`` -- number of cells in the horizontal strip - OUTPUT: - - - a list of super partitions + OUTPUT: list of super partitions EXAMPLES:: @@ -783,7 +751,7 @@ class SuperPartitions(UniqueRepresentation, Parent): INPUT: - - ``n`` -- an integer (optional: default ``None``) + - ``n`` -- integer (default: ``None``) - ``m`` -- if ``n`` is specified, an integer (optional: default ``None``) Super partitions are the indexing set for symmetric functions @@ -901,7 +869,7 @@ class options(GlobalOptions): """, NAME = 'SuperPartition' module = 'sage.combinat.superpartition' - display = dict(default="default", + display = dict(default='default', description="Specifies how the super partitions should " "be printed", values=dict(list="the super partitions are displayed in " diff --git a/src/sage/combinat/symmetric_group_algebra.py b/src/sage/combinat/symmetric_group_algebra.py index 1706f848f10..b9ea545cd60 100644 --- a/src/sage/combinat/symmetric_group_algebra.py +++ b/src/sage/combinat/symmetric_group_algebra.py @@ -247,7 +247,7 @@ def __init__(self, R, W, category): sage: S = SymmetricGroup(4) sage: SGA = S.algebra(QQ) - sage: TestSuite(SGA).run(skip="_test_cellular") + sage: TestSuite(SGA).run(skip='_test_cellular') sage: SGA._test_cellular() # long time Checking that coercion works between equivalent indexing sets:: @@ -1986,7 +1986,7 @@ def seminormal_basis(self, mult='l2r'): INPUT: - - ``mult`` -- string (default: ``'l2r'``). If set to ``'r2l'``, + - ``mult`` -- string (default: ``'l2r'``); if set to ``'r2l'``, this causes the method to return the list of the antipodes (:meth:`antipode`) of all `\epsilon(T, S)` instead of the `\epsilon(T, S)` themselves. @@ -2032,7 +2032,7 @@ def dft(self, form=None, mult='l2r'): INPUT: - - ``mult`` -- string (default: `l2r`). If set to `r2l`, + - ``mult`` -- string (default: `l2r`); if set to `r2l`, this causes the method to use the antipodes (:meth:`antipode`) of the seminormal basis instead of the seminormal basis. @@ -2076,7 +2076,7 @@ def _dft_seminormal(self, mult='l2r'): INPUT: - - ``mult`` -- string (default: `l2r`). If set to `r2l`, + - ``mult`` -- string (default: `l2r`); if set to `r2l`, this causes the method to use the antipodes (:meth:`antipode`) of the seminormal basis instead of the seminormal basis. @@ -2133,11 +2133,11 @@ def epsilon_ik(self, itab, ktab, star=0, mult='l2r'): INPUT: - - ``itab``, ``ktab`` -- two standard tableaux of size `n`. + - ``itab``, ``ktab`` -- two standard tableaux of size `n` - - ``star`` -- integer (default: `0`). + - ``star`` -- integer (default: `0`) - - ``mult`` -- string (default: `l2r`). If set to `r2l`, + - ``mult`` -- string (default: `l2r`); if set to `r2l`, this causes the method to return the antipode (:meth:`antipode`) of `\epsilon(I, K)` instead of `\epsilon(I, K)` itself. @@ -2507,9 +2507,9 @@ def epsilon_ik(itab, ktab, star=0): INPUT: - - ``itab``, ``ktab`` -- two standard tableaux of same size. + - ``itab``, ``ktab`` -- two standard tableaux of same size - - ``star`` -- integer (default: `0`). + - ``star`` -- integer (default: `0`) OUTPUT: @@ -2647,7 +2647,7 @@ def kappa(alpha): INPUT: - - ``alpha`` -- integer partition (can be encoded as a list). + - ``alpha`` -- integer partition (can be encoded as a list) OUTPUT: @@ -2684,15 +2684,15 @@ def a(tableau, star=0, base_ring=QQ): INPUT: - ``tableau`` -- Young tableau which contains every integer - from `1` to its size precisely once. + from `1` to its size precisely once - - ``star`` -- nonnegative integer (default: `0`). When this + - ``star`` -- nonnegative integer (default: `0`); when this optional variable is set, the method computes not the row projection operator of ``tableau``, but the row projection operator of the restriction of ``tableau`` to the entries ``1, 2, ..., tableau.size() - star`` instead. - - ``base_ring`` -- commutative ring (default: ``QQ``). When this + - ``base_ring`` -- commutative ring (default: ``QQ``); when this optional variable is set, the row projection operator is computed over a user-determined base ring instead of `\QQ`. (Note that symmetric group algebras currently don't preserve @@ -2757,7 +2757,7 @@ def b(tableau, star=0, base_ring=QQ): INPUT: - ``tableau`` -- Young tableau which contains every integer - from `1` to its size precisely once. + from `1` to its size precisely once - ``star`` -- nonnegative integer (default: `0`). When this optional variable is set, the method computes not the column @@ -3242,7 +3242,7 @@ def _to_sga(self, ind): from sage.combinat.rsk import RSK_inverse S = ind[1] T = ind[2] - w = RSK_inverse(T, S, output="permutation") + w = RSK_inverse(T, S, output='permutation') return self._algebra.kazhdan_lusztig_basis_element(w) @@ -3435,7 +3435,7 @@ def __init__(self, R, n, q=None): """ HeckeAlgebraSymmetricGroup_generic.__init__(self, R, n, q) self._name += " on the T basis" - self.print_options(prefix="T") + self.print_options(prefix='T') def t_action_on_basis(self, perm, i): r""" diff --git a/src/sage/combinat/symmetric_group_representations.py b/src/sage/combinat/symmetric_group_representations.py index ae74e707645..dbaebfe3f01 100644 --- a/src/sage/combinat/symmetric_group_representations.py +++ b/src/sage/combinat/symmetric_group_representations.py @@ -45,14 +45,14 @@ from sage.sets.finite_enumerated_set import FiniteEnumeratedSets lazy_import("sage.combinat.yang_baxter_graph", "YangBaxterGraph_partition") -lazy_import("sage.groups.perm_gps.constructor", "PermutationGroupElement", as_="PermutationConstructor") +lazy_import("sage.groups.perm_gps.constructor", "PermutationGroupElement", as_='PermutationConstructor') lazy_import("sage.symbolic.ring", "SR") # #### Constructor function ################################################ -def SymmetricGroupRepresentation(partition, implementation="specht", +def SymmetricGroupRepresentation(partition, implementation='specht', ring=None, cache_matrices=True): r""" The irreducible representation of the symmetric group corresponding to @@ -62,15 +62,15 @@ def SymmetricGroupRepresentation(partition, implementation="specht", - ``partition`` -- a partition of a positive integer - - ``implementation`` -- string (default: ``"specht"``), one of: + - ``implementation`` -- string (default: ``'specht'``); one of: - * ``"seminormal"`` -- for Young's seminormal representation - * ``"orthogonal"`` -- for Young's orthogonal representation - * ``"specht"`` -- for Specht's representation + * ``'seminormal'`` -- for Young's seminormal representation + * ``'orthogonal'`` -- for Young's orthogonal representation + * ``'specht'`` -- for Specht's representation - ``ring`` -- the ring over which the representation is defined - - ``cache_matrices`` -- boolean (default: ``True``) if ``True``, then any + - ``cache_matrices`` -- boolean (default: ``True``); if ``True``, then any representation matrices that are computed are cached EXAMPLES: @@ -179,7 +179,7 @@ def SymmetricGroupRepresentation(partition, implementation="specht", return Rep(partition) -def SymmetricGroupRepresentations(n, implementation="specht", ring=None, +def SymmetricGroupRepresentations(n, implementation='specht', ring=None, cache_matrices=True): r""" Irreducible representations of the symmetric group. @@ -188,15 +188,15 @@ def SymmetricGroupRepresentations(n, implementation="specht", ring=None, - ``n`` -- positive integer - - ``implementation`` -- string (default: ``"specht"``), one of: + - ``implementation`` -- string (default: ``'specht'``); one of: - * ``"seminormal"`` -- for Young's seminormal representation - * ``"orthogonal"`` -- for Young's orthogonal representation - * ``"specht"`` -- for Specht's representation + * ``'seminormal'`` -- for Young's seminormal representation + * ``'orthogonal'`` -- for Young's orthogonal representation + * ``'specht'`` -- for Specht's representation - ``ring`` -- the ring over which the representation is defined - - ``cache_matrices`` -- boolean (default: ``True``) if ``True``, then any + - ``cache_matrices`` -- boolean (default: ``True``); if ``True``, then any representation matrices that are computed are cached EXAMPLES: diff --git a/src/sage/combinat/t_sequences.py b/src/sage/combinat/t_sequences.py index 0376ac8f262..c78a451f67c 100644 --- a/src/sage/combinat/t_sequences.py +++ b/src/sage/combinat/t_sequences.py @@ -18,8 +18,8 @@ * the last element of `X` is -1 * the last element of `U` is 1 -The nonperiodic autocorrelation of a familiy of sequences `X=\{A_1, A_2, ..., A_n\}` is defined as -(see Definition 7.2 of [Seb2017]_): +The nonperiodic autocorrelation of a familiy of sequences +`X=\{A_1, A_2, ..., A_n\}` is defined as (see Definition 7.2 of [Seb2017]_): .. MATH:: @@ -55,10 +55,11 @@ def _nonperiodic_autocorrelation(sequences, j): INPUT: - - ``sequences`` -- either a single sequence or a list of sequences for which we want - to compute the nonperiodic autocorrelation. + - ``sequences`` -- either a single sequence or a list of sequences for + which we want to compute the nonperiodic autocorrelation - - ``j`` -- integer, the parameter `j` used when calculating the nonperiodic autocorrelation. + - ``j`` -- integer; the parameter `j` used when calculating the nonperiodic + autocorrelation """ if not isinstance(sequences[0], list): sequences = [sequences] @@ -80,10 +81,10 @@ def is_skew(seq, verbose=False): INPUT: - - ``seq`` -- the sequence that should be checked. + - ``seq`` -- the sequence that should be checked - - ``verbose`` -- a boolean (default false). If true the function will be verbose - when the sequences do not satisfy the contraints. + - ``verbose`` -- boolean (default: ``False``); if ``True`` the function + will be verbose when the sequences do not satisfy the contraints EXAMPLES:: @@ -126,10 +127,10 @@ def is_symmetric(seq, verbose=False) -> bool: INPUT: - - ``seq`` -- the sequence that should be checked. + - ``seq`` -- the sequence that should be checked - - ``verbose`` -- a boolean (default false). If true the function will be verbose - when the sequences do not satisfy the contraints. + - ``verbose`` -- boolean (default: ``False``); if ``True`` the function will be + verbose when the sequences do not satisfy the contraints EXAMPLES:: @@ -176,10 +177,10 @@ def is_T_sequences_set(sequences, verbose=False): INPUT: - - ``sequences`` -- a list of four sequences. + - ``sequences`` -- list of four sequences - - ``verbose`` -- a boolean (default false). If true the function will be verbose - when the sequences do not satisfy the contraints. + - ``verbose`` -- boolean (default: ``False``); if ``True`` the function will be + verbose when the sequences do not satisfy the contraints EXAMPLES:: @@ -189,7 +190,8 @@ def is_T_sequences_set(sequences, verbose=False): True sage: seqs = [[1, 1, 0, 1, 0], [0, 0, 1, 0, 0], [0, 0, 0, 1, -1], [0, 0, 0, 0, 0]] sage: is_T_sequences_set(seqs, verbose=True) - There should be exactly a nonzero element at every index, found 2 such elemnents at index 3 + There should be exactly a nonzero element at every index, found 2 such + elements at index 3 False @@ -226,7 +228,7 @@ def is_T_sequences_set(sequences, verbose=False): tot += abs(seq[i]) if tot != 1: if verbose: - print(f"There should be exactly a nonzero element at every index, found {tot} such elemnents at index {i}") + print(f"There should be exactly a nonzero element at every index, found {tot} such elements at index {i}") return False for j in range(1, t): @@ -247,10 +249,10 @@ def turyn_sequences_smallcases(l, existence=False): INPUT: - - ``l`` -- integer, the length of the Turyn sequences. + - ``l`` -- integer; the length of the Turyn sequences - - ``existence`` -- boolean (default: ``False``). If true, only return whether the - Turyn sequences are available for the given length. + - ``existence`` -- boolean (default: ``False``); if ``True``, only return + whether the Turyn sequences are available for the given length EXAMPLES: @@ -315,9 +317,11 @@ def T_sequences_construction_from_base_sequences(base_sequences, check=True): INPUT: - - ``base_sequences`` -- the base sequences that should be used to construct the T-sequences. + - ``base_sequences`` -- the base sequences that should be used to construct + the T-sequences - - ``check`` -- boolean, if true (default) checks that the sequences created are T-sequences before returning them. + - ``check`` -- boolean (default: ``True``); check that the sequences + created are T-sequences before returning them EXAMPLES:: @@ -394,9 +398,11 @@ def T_sequences_construction_from_turyn_sequences(turyn_sequences, check=True): INPUT: - - ``turyn_sequences`` -- the Turyn sequences that should be used to construct the T-sequences . + - ``turyn_sequences`` -- the Turyn sequences that should be used to + construct the T-sequences - - ``check`` -- boolean, if true (default) checks that the sequences created are T-sequences before returning them. + - ``check`` -- boolean (default: ``True``); check that the sequences + created are T-sequences before returning them EXAMPLES:: @@ -463,12 +469,13 @@ def T_sequences_smallcases(t, existence=False, check=True): INPUT: - - ``t`` -- integer, the length of the T-sequences to construct. + - ``t`` -- integer; the length of the T-sequences to construct - - ``existence`` -- boolean (default false). If true, this method only returns whether a T-sequences of - the given size can be constructed. + - ``existence`` -- boolean (default: ``False``); if ``True``, this method + only returns whether a T-sequences of the given size can be constructed - - ``check`` -- boolean, if true (default) check that the sequences are T-sequences before returning them. + - ``check`` -- boolean (default: ``True``); check that the sequences are + T-sequences before returning them EXAMPLES: @@ -553,10 +560,13 @@ def T_sequences_smallcases(t, existence=False, check=True): def base_sequences_construction(turyn_type_seqs, check=True): - r"""Construct base sequences of length `2n-1, 2n-1, n, n` from Turyn type sequences of length `n,n,n,n-1`. + r""" + Construct base sequences of length `2n-1, 2n-1, n, n` from Turyn type + sequences of length `n,n,n,n-1`. - Given Turyn type sequences `X, Y, Z, W` of length `n,n,n,n-1`, Theorem 1 of [KTR2005]_ shows that the - following are base sequences of length `2n-1, 2n-1, n, n`: + Given Turyn type sequences `X, Y, Z, W` of length `n,n,n,n-1`, Theorem 1 of + [KTR2005]_ shows that the following are base sequences of length + `2n-1, 2n-1, n, n`: .. MATH:: @@ -569,12 +579,13 @@ def base_sequences_construction(turyn_type_seqs, check=True): INPUT: - - ``turyn_type_seqs`` -- The list of 4 Turyn type sequences that should be used to construct the base sequences. + - ``turyn_type_seqs`` -- the list of 4 Turyn type sequences that should be + used to construct the base sequences - - ``check`` -- boolean, if True (default) check that the resulting sequences are base sequences - before returning them. + - ``check`` -- boolean (default: ``True``); check that the resulting + sequences are base sequences before returning them - OUTPUT: A list containing the four base sequences. + OUTPUT: list containing the four base sequences EXAMPLES:: @@ -618,8 +629,8 @@ def base_sequences_construction(turyn_type_seqs, check=True): def is_base_sequences_tuple(base_sequences, verbose=False): r"""Check if the given sequences are base sequences. - Four (-1, +1) sequences `A, B, C, D` of length `n+p, n+p, n, n` are called base sequences if - for all `j \ge 1`: + Four (-1, +1) sequences `A, B, C, D` of length `n+p, n+p, n, n` are called + base sequences if for all `j \ge 1`: .. MATH:: @@ -629,10 +640,10 @@ def is_base_sequences_tuple(base_sequences, verbose=False): INPUT: - - ``base_sequences`` -- The list of 4 sequences that should be checked. + - ``base_sequences`` -- the list of 4 sequences that should be checked - - ``verbose`` -- a boolean (default false). If true the function will be verbose - when the sequences do not satisfy the contraints. + - ``verbose`` -- boolean (default: ``False``); if ``True`` the function + will be verbose when the sequences do not satisfy the contraints EXAMPLES:: @@ -704,10 +715,10 @@ def turyn_type_sequences_smallcases(n, existence=False): INPUT: - - ``n`` -- integer, the length of the Turyn type sequences. + - ``n`` -- integer; the length of the Turyn type sequences - - ``existence`` -- boolean (default: ``False``). If true, only return whether the - Turyn type sequences are available for the given length. + - ``existence`` -- boolean (default: ``False``); if ``True``, only return + whether the Turyn type sequences are available for the given length EXAMPLES: @@ -734,12 +745,14 @@ def turyn_type_sequences_smallcases(n, existence=False): ALGORITHM: The Turyn type sequences are stored in hexadecimal format. - Given `n` hexadecimal digits `h_1, h_2,...,h_n`, it is possible to get the Turyn type sequences - by converting each `h_i` (`1 \le i \le n-1`) into a four digits binary number. Then, the j-th binary digit is - `0` if the i-th number in the j-th sequence is `1`, and it is `1` if the number in the sequence is -1. - - For the n-th digit, it should be converted to a 3 digits binary number, and then the same mapping - as before can be used (see also [BDKR2013]_). + Given `n` hexadecimal digits `h_1, h_2,...,h_n`, it is possible to get the + Turyn type sequences by converting each `h_i` (`1 \le i \le n-1`) into a + four digits binary number. Then, the `j`-th binary digit is `0` if the `i`-th + number in the `j`-th sequence is `1`, and it is `1` if the number in the + sequence is -1. + + For the `n`-th digit, it should be converted to a 3 digits binary number, and + then the same mapping as before can be used (see also [BDKR2013]_). """ def convertLists(hexstring): seqs = [Sequence([]), Sequence([]), Sequence([]), Sequence([])] @@ -790,30 +803,33 @@ def convertLists(hexstring): def base_sequences_smallcases(n, p, existence=False, check=True): r"""Construct base sequences of length `n+p, n+p, n, n` from available data. - The function uses the construction :func:`base_sequences_construction`, together with - Turyn type sequences from :func:`turyn_type_sequences_smallcases` to construct base sequences - with `p = n-1`. + The function uses the construction :func:`base_sequences_construction`, + together with Turyn type sequences from :func:`turyn_type_sequences_smallcases` + to construct base sequences with `p = n-1`. - Furthermore, this function uses also Turyn sequences (i.e. base sequences with `p=1`) from - :func:`turyn_sequences_smallcases`. + Furthermore, this function uses also Turyn sequences (i.e. base sequences + with `p=1`) from :func:`turyn_sequences_smallcases`. INPUT: - - ``n`` -- integer, the length of the last two base sequences. + - ``n`` -- integer; the length of the last two base sequences - - ``p`` -- integer, `n+p` will be the length of the first two base sequences. + - ``p`` -- integer; `n+p` will be the length of the first two base + sequences - - ``existence`` -- boolean (default: ``False``). If True, the function will only check whether the base - sequences can be constructed. + - ``existence`` -- boolean (default: ``False``); if ``True``, the function + will only check whether the base sequences can be constructed - - ``check`` -- boolean, if True (default) check that the resulting sequences are base sequences - before returning them. + - ``check`` -- boolean (default: ``True``); check that the resulting + sequences are base sequences before returning them OUTPUT: - If ``existence`` is ``False``, the function returns a list containing the four base sequences, or raises - an error if the base sequences cannot be constructed. If ``existence`` is ``True``, the function returns a - boolean, which is ``True`` if the base sequences can be constructed and ``False`` otherwise. + If ``existence`` is ``False``, the function returns a list containing the + four base sequences, or raises an error if the base sequences cannot be + constructed. If ``existence`` is ``True``, the function returns a boolean, + which is ``True`` if the base sequences can be constructed and ``False`` + otherwise. EXAMPLES:: diff --git a/src/sage/combinat/tableau.py b/src/sage/combinat/tableau.py index 5540faeeb1d..19f9033fcea 100644 --- a/src/sage/combinat/tableau.py +++ b/src/sage/combinat/tableau.py @@ -126,9 +126,7 @@ class Tableau(ClonableList, metaclass=InheritComparisonClasscallMetaclass): - ``t`` -- a Tableau, a list of iterables, or an empty list - OUTPUT: - - - A Tableau object constructed from ``t``. + OUTPUT: a Tableau object constructed from ``t`` A tableau is abstractly a mapping from the cells in a partition to arbitrary objects (called entries). It is often represented as a @@ -181,7 +179,6 @@ class Tableau(ClonableList, metaclass=InheritComparisonClasscallMetaclass): Traceback (most recent call last): ... ValueError: a tableau must be a list of iterables - """ @staticmethod def __classcall_private__(cls, t): @@ -279,9 +276,7 @@ def __richcmp__(self, other, op): - ``other`` -- the element that ``self`` is compared to - OUTPUT: - - A Boolean. + OUTPUT: boolean TESTS:: @@ -469,12 +464,12 @@ def _ascii_art_(self): [ 1 ] [ 1 3 1 2 2 ] [ 1 2 3, 2 , 3 , 3 ] - sage: Tableaux.options(ascii_art="compact") + sage: Tableaux.options(ascii_art='compact') sage: ascii_art(list(StandardTableaux(3))) [ |1| ] [ |1|3| |1|2| |2| ] [ |1|2|3|, |2| , |3| , |3| ] - sage: Tableaux.options(convention="french", ascii_art="table") + sage: Tableaux.options(convention='french', ascii_art='table') sage: ascii_art(list(StandardTableaux(3))) [ +---+ ] [ | 3 | ] @@ -483,12 +478,12 @@ def _ascii_art_(self): [ +---+---+---+ +---+---+ +---+---+ +---+ ] [ | 1 | 2 | 3 | | 1 | 3 | | 1 | 2 | | 1 | ] [ +---+---+---+, +---+---+, +---+---+, +---+ ] - sage: Tableaux.options(ascii_art="repr") + sage: Tableaux.options(ascii_art='repr') sage: ascii_art(list(StandardTableaux(3))) [ 3 ] [ 2 3 2 ] [ 1 2 3, 1 3, 1 2, 1 ] - sage: Tableaux.options(convention="russian", ascii_art="table") + sage: Tableaux.options(convention='russian', ascii_art='table') sage: ascii_art(list(StandardTableaux(3))) [ / \ / \ ] [ / 3 / \ 3 \ ] @@ -497,7 +492,7 @@ def _ascii_art_(self): [ / \ / \ / \ / \ / \ / \ / \ ] [ \ 1 / \ 1 / \ 1 / \ 1 / ] [ \ / , \ / , \ / , \ / ] - sage: Tableaux.options(ascii_art="repr") + sage: Tableaux.options(ascii_art='repr') sage: ascii_art(list(StandardTableaux(3))) [ 3 3 ] [ 2 2 3 3 2 2 ] @@ -820,9 +815,7 @@ def __call__(self, *cell): - ``cell`` -- a pair of integers, tuple, or list specifying a cell in the tableau - OUTPUT: - - - The value in the corresponding cell. + OUTPUT: the value in the corresponding cell EXAMPLES:: @@ -1264,15 +1257,14 @@ def to_sign_matrix(self, max_entry=None): r""" Return the sign matrix of ``self``. - A sign matrix is an `m \times n` matrix of 0's, 1's and -1's such that the + A sign matrix is an `m \times n` matrix of 0s, 1s, and -1s such that the partial sums of each column is either 0 or 1 and the partial sums of - each row is non-negative. [Ava2007]_ + each row is nonnegative. [Ava2007]_ INPUT: - - ``max_entry`` -- A non-negative integer, the maximum allowable number in - the tableau. Defaults to the largest entry in the tableau if not specified. - + - ``max_entry`` -- nonnegative integer; the maximum allowable number in + the tableau (defaults to the largest entry in the tableau if not specified) EXAMPLES:: @@ -1298,14 +1290,14 @@ def to_sign_matrix(self, max_entry=None): sage: s.to_sign_matrix(6) Traceback (most recent call last): ... - ValueError: the entries must be non-negative integers + ValueError: the entries must be nonnegative integers """ from sage.rings.integer_ring import ZZ from sage.sets.positive_integers import PositiveIntegers PI = PositiveIntegers() for row in self: if any(c not in PI for c in row): - raise ValueError("the entries must be non-negative integers") + raise ValueError("the entries must be nonnegative integers") from sage.matrix.matrix_space import MatrixSpace if max_entry is None: max_entry = max([max(c) for c in self]) @@ -1335,14 +1327,12 @@ def schuetzenberger_involution(self, n=None, check=True): INPUT: - - ``n`` -- an integer specifying the maximal letter in the + - ``n`` -- integer specifying the maximal letter in the alphabet (optional) - - ``check`` -- (Default: ``True``) Check to make sure ``self`` is - semistandard. Set to ``False`` to avoid this check. (optional) - - OUTPUT: + - ``check`` -- boolean (default: ``True``); check to make sure ``self`` + is semistandard - - a tableau, the Schuetzenberger involution of ``self`` + OUTPUT: a tableau, the Schuetzenberger involution of ``self`` EXAMPLES:: @@ -1402,14 +1392,12 @@ def evacuation(self, n=None, check=True): INPUT: - - ``n`` -- an integer specifying the maximal letter in the + - ``n`` -- integer specifying the maximal letter in the alphabet (optional) - - ``check`` -- (Default: ``True``) Check to make sure ``self`` is - semistandard. Set to ``False`` to avoid this check. (optional) + - ``check`` -- boolean (default: ``True``); check to make sure ``self`` + is semistandard - OUTPUT: - - - a tableau, the evacuation of ``self`` + OUTPUT: a tableau, the evacuation of ``self`` EXAMPLES:: @@ -1436,7 +1424,7 @@ def evacuation(self, n=None, check=True): """ return self.schuetzenberger_involution(n, check) - @combinatorial_map(name="standardization") + @combinatorial_map(name='standardization') def standardization(self, check=True): r""" Return the standardization of ``self``, assuming ``self`` is a @@ -1455,8 +1443,8 @@ def standardization(self, check=True): INPUT: - - ``check`` -- (Default: ``True``) Check to make sure ``self`` is - semistandard. Set to ``False`` to avoid this check. + - ``check`` -- (default: ``True``) check to make sure ``self`` is + semistandard; set to ``False`` to avoid this check EXAMPLES:: @@ -1511,17 +1499,17 @@ def bender_knuth_involution(self, k, rows=None, check=True): INPUT: - - ``k`` -- an integer + - ``k`` -- integer - - ``rows`` -- (Default ``None``) When set to ``None``, the method + - ``rows`` -- (default: ``None``) when set to ``None``, the method computes the `k`-th Bender--Knuth involution as defined above. When an iterable, this computes the composition of the `k`-th Bender--Knuth switches at row `i` over all `i` in ``rows``. When set to an integer `i`, the method computes the `k`-th Bender--Knuth switch at row `i`. Note the indexing of the rows starts with `1`. - - ``check`` -- (Default: ``True``) Check to make sure ``self`` is - semistandard. Set to ``False`` to avoid this check. + - ``check`` -- (default: ``True``) check to make sure ``self`` is + semistandard; Set to ``False`` to avoid this check OUTPUT: @@ -2083,7 +2071,7 @@ def k_weight(self, k): def is_k_tableau(self, k): r""" - Checks whether ``self`` is a valid weak `k`-tableau. + Check whether ``self`` is a valid weak `k`-tableau. EXAMPLES:: @@ -2353,7 +2341,7 @@ def schensted_insert(self, i, left=False): INPUT: - ``i`` -- a number to insert - - ``left`` -- (default: ``False``) boolean; if set to + - ``left`` -- boolean (default: ``False``); if set to ``True``, the insertion will be done from the left. That is, if one thinks of the algorithm as appending a letter to the reading word of ``self``, we append the letter to @@ -2466,7 +2454,7 @@ def reverse_bump(self, loc): INPUT: - - ``loc`` -- Can be either of the following: + - ``loc`` -- can be either of the following: - The coordinates ``(r, c)`` of the square to reverse-bump (which must be a corner of the tableau); @@ -2476,9 +2464,7 @@ def reverse_bump(self, loc): topmost row and the leftmost column are the `0`-th row and the `0`-th column. - OUTPUT: - - An ordered pair consisting of: + OUTPUT: an ordered pair consisting of: 1. The resulting (smaller) tableau; 2. The entry bumped out at the end of the process. @@ -2530,7 +2516,6 @@ def reverse_bump(self, loc): Reverse row bumping is only implemented for tableaux with weakly increasing and strictly increasing columns (though the tableau does not need to be an instance of class :class:`SemistandardTableau`). - """ if not (self.is_semistandard()): raise ValueError("reverse bumping is only defined for semistandard tableaux") @@ -3193,7 +3178,6 @@ def add_entry(self, cell, m): Traceback (most recent call last): ... IndexError: (2, 2) is not an addable cell of the tableau - """ tab = self.to_list() (r, c) = cell @@ -3709,7 +3693,6 @@ def right_key_tableau(self): sage: Tableau([]).right_key_tableau() [] - """ if not self: return self @@ -3736,7 +3719,7 @@ def left_key_tableau(self): Return the left key tableau of ``self``. The left key tableau of a tableau `T` is the key tableau whose entries - are weakly lesser than the corresponding entries in `T`, and whose column + are weakly less than the corresponding entries in `T`, and whose column reading word is subject to certain conditions. See [LS1990]_ for the full definition. ALGORITHM: @@ -3778,7 +3761,6 @@ def left_key_tableau(self): sage: Tableau([]).left_key_tableau() [] - """ if not self: return self @@ -3945,8 +3927,8 @@ def residue(self, k, e, multicharge=(0,)): INPUT: - - ``k`` -- an integer in `\{1, 2, \ldots, n\}` - - ``e`` -- an integer in `\{0, 2, 3, 4, 5, \ldots\}` + - ``k`` -- integer in `\{1, 2, \ldots, n\}` + - ``e`` -- integer in `\{0, 2, 3, 4, 5, \ldots\}` - ``multicharge`` -- (default: ``[0]``) a list of length 1 Here `n` is its size of ``self``. @@ -3955,9 +3937,7 @@ def residue(self, k, e, multicharge=(0,)): all of the contents. It is included mainly for compatibility with :meth:`~sage.combinat.tableau_tuples.TableauTuple.residue`. - OUTPUT: - - The residue in `\ZZ / e\ZZ`. + OUTPUT: the residue in `\ZZ / e\ZZ` EXAMPLES:: @@ -3990,7 +3970,7 @@ def residue_sequence(self, e, multicharge=(0,)): INPUT: - - ``e`` -- an integer in `\{0, 2, 3, 4, 5, \ldots\}` + - ``e`` -- integer in `\{0, 2, 3, 4, 5, \ldots\}` - ``multicharge`` -- (default: ``[0]``) a sequence of integers of length 1 @@ -4037,9 +4017,7 @@ def degree(self, e, multicharge=(0,)): - ``e`` -- the *quantum characteristic* - ``multicharge`` -- (default: ``[0]``) the multicharge - OUTPUT: - - The degree of the tableau ``self``, which is an integer. + OUTPUT: the degree of the tableau ``self``, which is an integer EXAMPLES:: @@ -4082,9 +4060,7 @@ def codegree(self, e, multicharge=(0,)): - ``e`` -- the *quantum characteristic* - ``multicharge`` -- (default: ``[0]``) the multicharge - OUTPUT: - - The codegree of the tableau ``self``, which is an integer. + OUTPUT: the codegree of the tableau ``self``, which is an integer EXAMPLES:: @@ -4417,9 +4393,7 @@ class SemistandardTableau(Tableau): - ``t`` -- a tableau, a list of iterables, or an empty list - OUTPUT: - - - A SemistandardTableau object constructed from ``t``. + OUTPUT: a SemistandardTableau object constructed from ``t`` A semistandard tableau is a tableau whose entries are positive integers, which are weakly increasing in rows and strictly increasing down columns. @@ -4560,7 +4534,7 @@ def check(self): for row in self: if any(c not in PI for c in row): - raise ValueError("the entries of a semistandard tableau must be non-negative integers") + raise ValueError("the entries of a semistandard tableau must be nonnegative integers") if any(row[c] > row[c+1] for c in range(len(row)-1)): raise ValueError("the entries in each row of a semistandard tableau must be weakly increasing") @@ -4812,7 +4786,6 @@ def dominates(self, t): True sage: s.dominates([[1,2,3,4,5]]) False - """ t = StandardTableau(t) return all(self.restrict(m).shape().dominates(t.restrict(m).shape()) @@ -5076,7 +5049,7 @@ def from_chain(chain): return T.element_class(T, res) -def from_shape_and_word(shape, w, convention="French"): +def from_shape_and_word(shape, w, convention='French'): r""" Return a tableau from a shape and word. @@ -5086,15 +5059,15 @@ def from_shape_and_word(shape, w, convention="French"): - ``w`` -- a word whose length equals that of the partition - - ``convention`` -- a string which can take values ``"French"`` or - ``"English"``; the default is ``"French"`` + - ``convention`` -- string (default: ``'French'``); can take values + ``'French'`` or ``'English'`` OUTPUT: A tableau, whose shape is ``shape`` and whose reading word is ``w``. - If the ``convention`` is specified as ``"French"``, the reading word is to be read + If the ``convention`` is specified as ``'French'``, the reading word is to be read starting from the top row in French convention (= the bottom row in English - convention). If the ``convention`` is specified as ``"English"``, the reading word + convention). If the ``convention`` is specified as ``'English'``, the reading word is to be read starting with the top row in English convention. EXAMPLES:: @@ -5108,7 +5081,7 @@ def from_shape_and_word(shape, w, convention="French"): sage: from_shape_and_word(shape, word) [[1, 3], [2], [4]] sage: word = Word(flatten(t)) - sage: from_shape_and_word(shape, word, convention="English") + sage: from_shape_and_word(shape, word, convention='English') [[1, 3], [2], [4]] """ res = [] @@ -5227,7 +5200,7 @@ def check(self): sage: IncreasingTableau([[0,1]]) # indirect doctest Traceback (most recent call last): ... - ValueError: the entries of an increasing tableau must be non-negative integers + ValueError: the entries of an increasing tableau must be nonnegative integers """ if not self: # Empty tableau, so trivially an increasing tableau @@ -5244,7 +5217,7 @@ def check(self): for row in self: if any(c not in PI for c in row): raise ValueError("the entries of an increasing tableau" - " must be non-negative integers") + " must be nonnegative integers") if any(row[c] >= row[c+1] for c in range(len(row)-1)): raise ValueError("the entries in each row of an increasing" " tableau must be strictly increasing") @@ -5459,7 +5432,7 @@ class Tableaux(UniqueRepresentation, Parent): INPUT: - - ``n`` (optional) -- a non-negative integer + - ``n`` -- (optional) nonnegative integer OUTPUT: @@ -5510,7 +5483,7 @@ class Tableaux(UniqueRepresentation, Parent): sage: Tableaux(t) Traceback (most recent call last): ... - ValueError: the argument to Tableaux() must be a non-negative integer + ValueError: the argument to Tableaux() must be a nonnegative integer sage: Tableaux(3)([[1, 1]]) Traceback (most recent call last): ... @@ -5565,7 +5538,7 @@ def __classcall_private__(cls, *args, **kwargs): return Tableaux_all() else: if not isinstance(n, (int, Integer)) or n < 0: - raise ValueError("the argument to Tableaux() must be a non-negative integer") + raise ValueError("the argument to Tableaux() must be a nonnegative integer") return Tableaux_size(n) Element = Tableau @@ -5573,7 +5546,7 @@ def __classcall_private__(cls, *args, **kwargs): # add options to class class options(GlobalOptions): r""" - Sets the global options for elements of the tableau, skew_tableau, + Set the global options for elements of the tableau, skew_tableau, and tableau tuple classes. The defaults are for tableau to be displayed as a list, latexed as a Young diagram using the English convention. @@ -5640,25 +5613,25 @@ class options(GlobalOptions): """ NAME = 'Tableaux' module = 'sage.combinat.tableau' - display = dict(default="list", + display = dict(default='list', description='Controls the way in which tableaux are printed', values=dict(list='print tableaux as lists', diagram='display as Young diagram (similar to :meth:`~sage.combinat.tableau.Tableau.pp()`', compact='minimal length string representation'), - alias=dict(array="diagram", ferrers_diagram="diagram", young_diagram="diagram"), + alias=dict(array='diagram', ferrers_diagram='diagram', young_diagram='diagram'), case_sensitive=False) - ascii_art = dict(default="repr", + ascii_art = dict(default='repr', description='Controls the ascii art output for tableaux', values=dict(repr='display using the diagram string representation', table='display as a table', compact='minimal length ascii art'), case_sensitive=False) - latex = dict(default="diagram", + latex = dict(default='diagram', description='Controls the way in which tableaux are latexed', values=dict(list='as a list', diagram='as a Young diagram'), - alias=dict(array="diagram", ferrers_diagram="diagram", young_diagram="diagram"), + alias=dict(array='diagram', ferrers_diagram='diagram', young_diagram='diagram'), case_sensitive=False) - convention = dict(default="English", + convention = dict(default='English', description='Sets the convention used for displaying tableaux and partitions', values=dict( English='use the English convention', @@ -5666,21 +5639,19 @@ class options(GlobalOptions): Russian='use the Russian convention', ), case_sensitive=False) - notation = dict(alt_name="convention") + notation = dict(alt_name='convention') def _element_constructor_(self, t): r""" - Constructs an object from ``t`` as an element of ``self``, if + Construct an object from ``t`` as an element of ``self``, if possible. This is inherited by all Tableaux, SemistandardTableaux, and StandardTableaux classes. INPUT: - - ``t`` -- Data which can be interpreted as a tableau - - OUTPUT: + - ``t`` -- data which can be interpreted as a tableau - - The corresponding tableau object + OUTPUT: the corresponding tableau object TESTS:: @@ -5744,7 +5715,7 @@ class Tableaux_all(Tableaux): def __init__(self): r""" - Initializes the class of all tableaux + Initialize the class of all tableaux. TESTS:: @@ -5782,7 +5753,7 @@ class Tableaux_size(Tableaux): def __init__(self, n): r""" - Initializes the class of tableaux of size ``n``. + Initialize the class of tableaux of size `n`. TESTS:: @@ -5855,11 +5826,11 @@ class SemistandardTableaux(Tableaux): Keyword arguments: - - ``size`` -- The size of the tableaux - - ``shape`` -- The shape of the tableaux - - ``eval`` -- The weight (also called content or evaluation) of + - ``size`` -- the size of the tableaux + - ``shape`` -- the shape of the tableaux + - ``eval`` -- the weight (also called content or evaluation) of the tableaux - - ``max_entry`` -- A maximum entry for the tableaux. This can be a + - ``max_entry`` -- a maximum entry for the tableaux. This can be a positive integer or infinity (``oo``). If ``size`` or ``shape`` are specified, ``max_entry`` defaults to be ``size`` or the size of ``shape``. @@ -6065,7 +6036,7 @@ def __classcall_private__(cls, *args, **kwargs): if not isinstance(size, (int, Integer)): raise ValueError("size must be an integer") if size < 0: - raise ValueError("size must be non-negative") + raise ValueError("size must be nonnegative") if shape is not None: from sage.combinat.skew_partition import SkewPartitions @@ -6294,7 +6265,7 @@ class SemistandardTableaux_all(SemistandardTableaux, DisjointUnionEnumeratedSets def __init__(self, max_entry=None): r""" - Initializes the class of all semistandard tableaux. + Initialize the class of all semistandard tableaux. .. WARNING:: @@ -6454,7 +6425,7 @@ class SemistandardTableaux_shape_inf(SemistandardTableaux): def __init__(self, p): r""" - Initializes the class of semistandard tableaux of shape ``p`` and no + Initialize the class of semistandard tableaux of shape ``p`` and no maximum entry. .. WARNING:: @@ -6542,7 +6513,7 @@ class SemistandardTableaux_size(SemistandardTableaux): def __init__(self, n, max_entry=None): r""" - Initializes the class of semistandard tableaux of size ``n``. + Initialize the class of semistandard tableaux of size `n`. .. WARNING:: @@ -6741,12 +6712,12 @@ class SemistandardTableaux_shape(SemistandardTableaux): INPUT: - ``p`` -- a partition - - ``max_entry`` -- the max entry; defaults to the size of ``p`` + - ``max_entry`` -- the max entry; defaults to the size of `p` """ def __init__(self, p, max_entry=None): r""" - Initializes the class of semistandard tableaux of shape ``p``, with a + Initialize the class of semistandard tableaux of shape `p`, with a given ``max_entry``. .. WARNING:: @@ -6859,7 +6830,6 @@ def random_element(self): sage: S = SemistandardTableaux([2, 2, 1, 1], max_entry=7) sage: S.random_element() in S True - """ from sage.misc.prandom import randint with_sentinels = [max(i, j) for i, j in zip([0]+list(self.shape), [k+1 for k in self.shape]+[0])] @@ -6958,7 +6928,7 @@ class SemistandardTableaux_shape_weight(SemistandardTableaux_shape): def __init__(self, p, mu): r""" - Initializes the class of all semistandard tableaux of shape ``p`` and + Initialize the class of all semistandard tableaux of shape ``p`` and weight ``mu``. .. WARNING:: @@ -7075,7 +7045,7 @@ class SemistandardTableaux_size_weight(SemistandardTableaux): def __init__(self, n, mu): r""" - Initializes the class of semistandard tableaux of size ``n`` and + Initialize the class of semistandard tableaux of size ``n`` and weight ``mu``. .. WARNING:: @@ -7162,14 +7132,12 @@ class RowStandardTableaux(Tableaux): INPUT: - - either a non-negative integer (possibly specified with the keyword + - either a nonnegative integer (possibly specified with the keyword ``n``) or a partition - OUTPUT: - - - with no argument, the class of all standard tableaux + OUTPUT: with no argument, the class of all standard tableaux - - with a non-negative integer argument, ``n``, the class of all standard + - with a nonnegative integer argument, ``n``, the class of all standard tableaux of size ``n`` - with a partition argument, the class of all standard tableaux of that @@ -7254,11 +7222,11 @@ def __classcall_private__(cls, *args, **kwargs): sage: RowStandardTableaux(-1) Traceback (most recent call last): ... - ValueError: the argument must be a non-negative integer or a partition + ValueError: the argument must be a nonnegative integer or a partition sage: RowStandardTableaux([[1]]) Traceback (most recent call last): ... - ValueError: the argument must be a non-negative integer or a partition + ValueError: the argument must be a nonnegative integer or a partition """ from sage.combinat.partition import _Partitions from sage.combinat.skew_partition import SkewPartitions @@ -7282,7 +7250,7 @@ def __classcall_private__(cls, *args, **kwargs): raise NotImplementedError("row standard skew tableaux not yet implemented") if not isinstance(n, (int, Integer)) or n < 0: - raise ValueError("the argument must be a non-negative integer or a partition") + raise ValueError("the argument must be a nonnegative integer or a partition") return RowStandardTableaux_size(n) @@ -7325,7 +7293,7 @@ class RowStandardTableaux_all(RowStandardTableaux, DisjointUnionEnumeratedSets): def __init__(self): r""" - Initializes the class of all standard tableaux. + Initialize the class of all standard tableaux. .. WARNING:: @@ -7390,7 +7358,7 @@ class RowStandardTableaux_size(RowStandardTableaux, DisjointUnionEnumeratedSets) def __init__(self, n): r""" - Initializes the class of all row standard tableaux of size ``n``. + Initialize the class of all row standard tableaux of size ``n``. .. WARNING:: @@ -7460,7 +7428,7 @@ class RowStandardTableaux_shape(RowStandardTableaux): def __init__(self, p): r""" - Initializes the class of all row standard tableaux of a given shape. + Initialize the class of all row standard tableaux of a given shape. .. WARNING:: @@ -7576,14 +7544,12 @@ class StandardTableaux(SemistandardTableaux): INPUT: - - Either a non-negative integer (possibly specified with the keyword ``n``) + - Either a nonnegative integer (possibly specified with the keyword ``n``) or a partition. - OUTPUT: - - - With no argument, the class of all standard tableaux + OUTPUT: with no argument, the class of all standard tableaux - - With a non-negative integer argument, ``n``, the class of all standard + - With a nonnegative integer argument, ``n``, the class of all standard tableaux of size ``n`` - With a partition argument, the class of all standard tableaux of that @@ -7656,11 +7622,11 @@ def __classcall_private__(cls, *args, **kwargs): sage: StandardTableaux(-1) Traceback (most recent call last): ... - ValueError: the argument must be a non-negative integer or a partition + ValueError: the argument must be a nonnegative integer or a partition sage: StandardTableaux([[1]]) Traceback (most recent call last): ... - ValueError: the argument must be a non-negative integer or a partition + ValueError: the argument must be a nonnegative integer or a partition """ from sage.combinat.partition import _Partitions from sage.combinat.skew_partition import SkewPartitions @@ -7683,7 +7649,7 @@ def __classcall_private__(cls, *args, **kwargs): return StandardSkewTableaux(n) if not isinstance(n, (int, Integer)) or n < 0: - raise ValueError("the argument must be a non-negative integer or a partition") + raise ValueError("the argument must be a nonnegative integer or a partition") return StandardTableaux_size(n) @@ -7728,7 +7694,7 @@ class StandardTableaux_all(StandardTableaux, DisjointUnionEnumeratedSets): def __init__(self): r""" - Initializes the class of all standard tableaux. + Initialize the class of all standard tableaux. TESTS:: @@ -7780,7 +7746,7 @@ class StandardTableaux_size(StandardTableaux, DisjointUnionEnumeratedSets): def __init__(self, n): r""" - Initializes the class of all standard tableaux of size ``n``. + Initialize the class of all standard tableaux of size `n`. .. WARNING:: @@ -7967,7 +7933,7 @@ class StandardTableaux_shape(StandardTableaux): def __init__(self, p): r""" - Initializes the class of all semistandard tableaux of a given shape. + Initialize the class of all semistandard tableaux of a given shape. .. WARNING:: @@ -8597,7 +8563,7 @@ def __classcall_private__(cls, *args, **kwargs): # Consistency checks if size is not None: if size not in NonNegativeIntegers(): - raise ValueError("size must be a non-negative integer") + raise ValueError("size must be a nonnegative integer") size = Integer(size) if shape is not None: @@ -8631,7 +8597,7 @@ def __classcall_private__(cls, *args, **kwargs): if not is_inf and not isinstance(max_entry, (int, Integer)): raise ValueError("max_entry must be an integer or PlusInfinity") elif max_entry < 0: - raise ValueError("max_entry must be non-negative") + raise ValueError("max_entry must be nonnegative") if size is not None and shape is not None: if sum(shape) != size: @@ -8866,7 +8832,7 @@ class IncreasingTableaux_all(IncreasingTableaux, DisjointUnionEnumeratedSets): def __init__(self, max_entry=None): r""" - Initializes the class of all increasing tableaux. + Initialize the class of all increasing tableaux. .. WARNING:: @@ -8921,7 +8887,7 @@ class IncreasingTableaux_size_inf(IncreasingTableaux): def __init__(self, n): r""" - Initializes the class of increasing tableaux of size ``n`` with no + Initialize the class of increasing tableaux of size `n` with no maximum entry. .. WARNING:: @@ -9002,7 +8968,7 @@ class IncreasingTableaux_shape_inf(IncreasingTableaux): def __init__(self, p): r""" - Initializes the class of increasing tableaux of shape ``p`` and no + Initialize the class of increasing tableaux of shape `p` and no maximum entry. .. WARNING:: @@ -9084,7 +9050,7 @@ class IncreasingTableaux_size(IncreasingTableaux): def __init__(self, n, max_entry=None): r""" - Initializes the class of increasing tableaux of size ``n``. + Initialize the class of increasing tableaux of size `n`. .. WARNING:: @@ -9204,7 +9170,7 @@ class IncreasingTableaux_shape(IncreasingTableaux): def __init__(self, p, max_entry=None): r""" - Initializes the class of increasing tableaux of shape ``p``, with a + Initialize the class of increasing tableaux of shape `p`, with a given ``max_entry``. .. WARNING:: @@ -9323,7 +9289,7 @@ class IncreasingTableaux_shape_weight(IncreasingTableaux_shape): def __init__(self, p, wt): r""" - Initializes the class of all increasing tableaux of shape ``p`` and + Initialize the class of all increasing tableaux of shape ``p`` and weight ``mu``. .. WARNING:: @@ -9467,7 +9433,7 @@ class IncreasingTableaux_size_weight(IncreasingTableaux): def __init__(self, n, wt): r""" - Initializes the class of increasing tableaux of size ``n`` and + Initialize the class of increasing tableaux of size `n` and weight ``wt``. .. WARNING:: diff --git a/src/sage/combinat/tableau_residues.py b/src/sage/combinat/tableau_residues.py index db94461f6ef..ccd39961fa9 100644 --- a/src/sage/combinat/tableau_residues.py +++ b/src/sage/combinat/tableau_residues.py @@ -244,7 +244,7 @@ def __init__(self, parent, residues, check): The ``multicharge`` is the optional argument which, if omitted, defaults to ``(0,)``. On the other hand, the ``residue`` must always be specified so, below, we check to see whether or note - ``residues`` is `None` and adjust accordingly in this case. + ``residues`` is ``None`` and adjust accordingly in this case. EXAMPLES:: @@ -269,7 +269,7 @@ def __init__(self, parent, residues, check): def check(self): r""" - Raise a :class:`ValueError` if ``self`` is not a residue sequence. + Raise a :exc:`ValueError` if ``self`` is not a residue sequence. EXAMPLES:: @@ -433,11 +433,11 @@ def restrict_row(self, cell, row): def swap_residues(self, i, j): r""" Return the *new* residue sequence obtained by swapping the residues - for ``i`` and `j``. + for ``i`` and ``j``. INPUT: - - ``i`` and ``j`` -- two integers between `1` and the length of + - ``i``, ``j`` -- two integers between `1` and the length of the residue sequence If residue sequence ``self`` is of the form `(r_1, \ldots, r_n)`, and @@ -718,7 +718,7 @@ def __init__(self, e, multicharge=(0,)): sage: ResidueSequences(e=0, multicharge=(0,1,2)) == ResidueSequences(e=3, multicharge=(0,1,2)) False - The TestSuite fails ``_test_pickling` because ``__getitem__`` does + The TestSuite fails ``_test_pickling`` because ``__getitem__`` does not support slices, so we skip this:: sage: R = ResidueSequences(e=0, multicharge=(0,1,2)) @@ -792,8 +792,8 @@ def cell_residue(self, *args): INPUT: - - ``r`` and ``c`` -- the row and column indices in level one - - ``k``, ``r`` and ``c`` -- the component, row and column indices + - ``r``, ``c`` -- the row and column indices in level one + - ``k``, ``r``, ``c`` -- the component, row and column indices in higher levels EXAMPLES:: diff --git a/src/sage/combinat/tableau_tuple.py b/src/sage/combinat/tableau_tuple.py index 3bc6b03d5dd..a24ac5ca809 100644 --- a/src/sage/combinat/tableau_tuple.py +++ b/src/sage/combinat/tableau_tuple.py @@ -251,12 +251,10 @@ class TableauTuple(CombinatorialElement): INPUT: - - ``t`` -- a list or tuple of :class:`Tableau`, a list or tuple of lists + - ``t`` -- list or tuple of :class:`Tableau`, a list or tuple of lists of lists - OUTPUT: - - - The Tableau tuple object constructed from ``t``. + OUTPUT: the Tableau tuple object constructed from ``t`` A :class:`TableauTuple` is a tuple of tableau of shape a :class:`PartitionTuple`. These combinatorial objects are useful is @@ -538,7 +536,7 @@ def _latex_(self): \lr{6}&\lr{7}\\\cline{1-2} \end{array}$} } \Bigg) - sage: TableauTuples.options(convention="french") + sage: TableauTuples.options(convention='french') sage: latex(t) # indirect doctest \Bigg( {\def\lr#1{\multicolumn{1}{|@{\hspace{.6ex}}c@{\hspace{.6ex}}|}{\raisebox{-.3ex}{$#1$}}} \raisebox{-.6ex}{$\begin{array}[t]{*{2}c}\cline{1-1} @@ -622,9 +620,7 @@ def __call__(self, *cell): - ``cell`` -- a triple of integers, tuple, or list specifying a cell in ``self`` - OUTPUT: - - - The value in the corresponding cell. + OUTPUT: the value in the corresponding cell EXAMPLES:: @@ -733,7 +729,7 @@ def pp(self): 4 5 4 5 8 14 6 9 - sage: TableauTuples.options(convention="french") + sage: TableauTuples.options(convention='french') sage: t.pp() 9 6 @@ -1047,7 +1043,6 @@ def up(self, n=None): ([[1, 2], [4]], [[3]]), ([[1, 2]], [[3, 4]]), ([[1, 2]], [[3], [4]])] - """ if n is None: n = self.size() @@ -1307,7 +1302,7 @@ def content(self, k, multicharge): INPUT: - - ``k`` -- an integer in `\{1, 2, \ldots, n\}` + - ``k`` -- integer in `\{1, 2, \ldots, n\}` - ``multicharge`` -- a sequence of integers of length `l` Here `l` is the :meth:`~TableauTuple.level` and `n` is the @@ -1354,16 +1349,14 @@ def residue(self, k, e, multicharge): INPUT: - - ``k`` -- an integer in `\{1, 2, \ldots, n\}` - - ``e`` -- an integer in `\{0, 2, 3, 4, 5, \ldots\}` - - ``multicharge`` -- a list of integers of length `l` + - ``k`` -- integer in `\{1, 2, \ldots, n\}` + - ``e`` -- integer in `\{0, 2, 3, 4, 5, \ldots\}` + - ``multicharge`` -- list of integers of length `l` Here `l` is the :meth:`~TableauTuple.level` and `n` is the :meth:`~TableauTuple.size` of ``self``. - OUTPUT: - - The residue of ``k`` in a standard tableau. That is, + OUTPUT: the residue of ``k`` in a standard tableau. That is, EXAMPLES:: @@ -1412,9 +1405,7 @@ class RowStandardTableauTuple(TableauTuple, metaclass=ClasscallMetaclass): - ``t`` -- a tableau, a list of (standard) tableau or an equivalent list - OUTPUT: - - - A :class:`RowStandardTableauTuple` object constructed from ``t``. + OUTPUT: a :class:`RowStandardTableauTuple` object constructed from ``t`` .. NOTE:: @@ -1538,7 +1529,7 @@ def __classcall_private__(self, t): def __init__(self, parent, t, check=True): r""" - Initializes a row standard tableau tuple. + Initialize a row standard tableau tuple. EXAMPLES:: @@ -1668,9 +1659,7 @@ def degree(self, e, multicharge): - ``e`` -- the *quantum characteristic* ``e`` - ``multicharge`` -- (default: ``[0]``) the multicharge - OUTPUT: - - The degree of the tableau ``self``, which is an integer. + OUTPUT: the degree of the tableau ``self``, which is an integer EXAMPLES:: @@ -1723,9 +1712,7 @@ def codegree(self, e, multicharge): - ``e`` -- the *quantum characteristic* - ``multicharge`` -- the multicharge - OUTPUT: - - The codegree of the tableau ``self``, which is an integer. + OUTPUT: the codegree of the tableau ``self``, which is an integer EXAMPLES:: @@ -1747,7 +1734,6 @@ def codegree(self, e, multicharge): 2 sage: StandardTableauTuple([[],[[2]], [[1]]]).codegree(0,(0,0,0)) 3 - """ if not self: # the trivial case return 0 @@ -1793,9 +1779,7 @@ class StandardTableauTuple(RowStandardTableauTuple): - ``t`` -- a tableau, a list of (standard) tableau or an equivalent list - OUTPUT: - - - A :class:`StandardTableauTuple` object constructed from ``t``. + OUTPUT: a :class:`StandardTableauTuple` object constructed from ``t`` .. NOTE:: @@ -1924,7 +1908,7 @@ def __classcall_private__(self, t): def __init__(self, parent, t, check=True): r""" - Initializes a standard tableau tuple. + Initialize a standard tableau tuple. EXAMPLES:: @@ -2056,15 +2040,13 @@ class TableauTuples(UniqueRepresentation, Parent): - ``level`` -- the level of the tableau tuples (positive integer) - - ``size`` -- the size of the tableau tuples (non-negative integer) + - ``size`` -- the size of the tableau tuples (nonnegative integer) It is not necessary to use the keywords. If they are not specified then the first integer argument specifies the ``level`` and the second the ``size`` of the tableaux. - OUTPUT: - - - The corresponding class of tableau tuples. + OUTPUT: the corresponding class of tableau tuples The entries of a tableau can be any sage object. Because of this, no enumeration of the set of :class:`TableauTuples` is possible. @@ -2197,7 +2179,7 @@ def __classcall_private__(cls, level=None, size=None): raise ValueError('the level must be a positive integer') if not (size is None or size in NN): - raise ValueError('the size must be a non-negative integer') + raise ValueError('the size must be a nonnegative integer') # now that the inputs appear to make sense, return the appropriate class @@ -2217,18 +2199,16 @@ def __classcall_private__(cls, level=None, size=None): def _element_constructor_(self, t): r""" - Constructs an object from t as an element of ``self``, if possible. + Construct an object from t as an element of ``self``, if possible. This is inherited by all :class:`TableauTuples`, :class:`StandardTableauTuples`, and :class:`StandardTableauTuples` classes. INPUT: - - ``t`` -- Data which can be interpreted as a tableau - - OUTPUT: + - ``t`` -- data which can be interpreted as a tableau - - The corresponding tableau object + OUTPUT: the corresponding tableau object EXAMPLES:: @@ -2384,7 +2364,7 @@ class TableauTuples_all(TableauTuples): def __init__(self): r""" - Initializes the class of all tableaux. + Initialize the class of all tableaux. EXAMPLES:: @@ -2427,7 +2407,7 @@ class TableauTuples_level(TableauTuples): def __init__(self, level): r""" - Initializes the class of tableaux of level ``level``. + Initialize the class of tableaux of level ``level``. EXAMPLES:: @@ -2508,7 +2488,7 @@ class TableauTuples_size(TableauTuples): def __init__(self, size): """ - Initializes the class of tableaux of size ``size``. + Initialize the class of tableaux of size ``size``. EXAMPLES:: @@ -2589,7 +2569,7 @@ class TableauTuples_level_size(TableauTuples): def __init__(self, level, size): r""" - Initializes the class of tableaux of size ``size``. + Initialize the class of tableaux of size ``size``. EXAMPLES:: @@ -2685,18 +2665,16 @@ class RowStandardTableauTuples(TableauTuples): - ``level`` -- the :meth:`~TableauTuples.level` of the tuples of tableaux - - ``size`` -- the :meth:`~TableauTuples.size` of the tuples of tableaux + - ``size`` -- the :meth:`~TableauTuples.size` of the tuples of tableaux - - ``shape`` -- a list or a partition tuple specifying the :meth:`shape` of + - ``shape`` -- list or a partition tuple specifying the :meth:`shape` of the row standard tableau tuples It is not necessary to use the keywords. If they are not used then the first integer argument specifies the :meth:`~TableauTuples.level` and the second the :meth:`~TableauTuples.size` of the tableau tuples. - OUTPUT: - - The appropriate subclass of :class:`RowStandardTableauTuples`. + OUTPUT: the appropriate subclass of :class:`RowStandardTableauTuples` A tuple of row standard tableau is a tableau whose entries are positive integers which increase from left to right along the rows in each component. @@ -2833,7 +2811,7 @@ def __classcall_private__(cls, *args, **kwargs): raise ValueError('the level must be a positive integer') if size is not None and (not isinstance(size, (int, Integer)) or size < 0): - raise ValueError('the size must be a non-negative integer') + raise ValueError('the size must be a nonnegative integer') if shape is not None: try: @@ -2988,7 +2966,7 @@ class RowStandardTableauTuples_all(RowStandardTableauTuples, DisjointUnionEnumer def __init__(self): r""" - Initializes the class of all row standard tableaux. + Initialize the class of all row standard tableaux. .. WARNING:: @@ -3039,7 +3017,7 @@ class RowStandardTableauTuples_level(RowStandardTableauTuples, DisjointUnionEnum def __init__(self, level): r""" - Initializes the class of row standard tableaux of level + Initialize the class of row standard tableaux of level ``level`` of arbitrary ``size``. .. WARNING:: @@ -3137,7 +3115,7 @@ class RowStandardTableauTuples_size(RowStandardTableauTuples, DisjointUnionEnume def __init__(self, size): r""" - Initializes the class of row standard tableaux of size ``size`` of + Initialize the class of row standard tableaux of size ``size`` of arbitrary level. .. WARNING:: @@ -3237,7 +3215,7 @@ class RowStandardTableauTuples_level_size(RowStandardTableauTuples, DisjointUnio def __init__(self, level, size): r""" - Initializes the class of row standard tableaux of level ``level`` + Initialize the class of row standard tableaux of level ``level`` and size ``size``. .. WARNING:: @@ -3353,7 +3331,7 @@ class RowStandardTableauTuples_shape(RowStandardTableauTuples): def __init__(self, shape): r""" - Initializes the class of row standard tableaux of shape ``p`` + Initialize the class of row standard tableaux of shape ``p`` and no maximum entry. .. WARNING:: @@ -3502,7 +3480,7 @@ def __iter__(self): # line lists back into tableaux. This is done y the following functions. def tableau_from_list(tab): """ - Converts a list tab=[t_1,...,t_n] into the mu-tableau obtained by + Convert a list tab=[t_1,...,t_n] into the mu-tableau obtained by inserting t_1,..,t_n in order into the rows of mu, from left to right in each component and then left to right along the components. """ @@ -3981,18 +3959,16 @@ class StandardTableauTuples(RowStandardTableauTuples): - ``level`` -- the :meth:`~TableauTuples.level` of the tuples of tableaux - - ``size`` -- the :meth:`~TableauTuples.size` of the tuples of tableaux + - ``size`` -- the :meth:`~TableauTuples.size` of the tuples of tableaux - - ``shape`` -- a list or a partition tuple specifying the :meth:`shape` of + - ``shape`` -- list or a partition tuple specifying the :meth:`shape` of the standard tableau tuples It is not necessary to use the keywords. If they are not used then the first integer argument specifies the :meth:`~TableauTuples.level` and the second the :meth:`~TableauTuples.size` of the tableau tuples. - OUTPUT: - - The appropriate subclass of :class:`StandardTableauTuples`. + OUTPUT: the appropriate subclass of :class:`StandardTableauTuples` A tuple of standard tableau is a tableau whose entries are positive integers which increase from left to right along the rows, and from top to @@ -4125,7 +4101,7 @@ def __classcall_private__(cls, *args, **kwargs): raise ValueError('the level must be a positive integer') if size is not None and (not isinstance(size, (int, Integer)) or size < 0): - raise ValueError('the size must be a non-negative integer') + raise ValueError('the size must be a nonnegative integer') if shape is not None: try: @@ -4279,7 +4255,7 @@ class StandardTableauTuples_all(StandardTableauTuples, DisjointUnionEnumeratedSe def __init__(self): r""" - Initializes the class of all standard tableaux. Input is not + Initialize the class of all standard tableaux. Input is not checked; please use :class:`StandardTableauTuples` to ensure the options are properly parsed. @@ -4303,7 +4279,6 @@ def _repr_(self): sage: STT = StandardTableauTuples(); STT # indirect doctest Standard tableau tuples - """ return "Standard tableau tuples" @@ -4472,7 +4447,7 @@ class StandardTableauTuples_size(StandardTableauTuples, DisjointUnionEnumeratedS def __init__(self, size): r""" - Initializes the class of semistandard tableaux of size ``size`` of + Initialize the class of semistandard tableaux of size ``size`` of arbitrary level. Input is not checked; please use :class:`StandardTableauTuples` to ensure the options are properly parsed. @@ -4599,7 +4574,7 @@ class StandardTableauTuples_level_size(StandardTableauTuples, DisjointUnionEnume def __init__(self, level, size): r""" - Initializes the class of semistandard tableaux of level ``level`` and + Initialize the class of semistandard tableaux of level ``level`` and size ``size``. Input is not checked; please use :class:`StandardTableauTuples` to ensure the options are properly parsed. @@ -4742,7 +4717,7 @@ class StandardTableauTuples_shape(StandardTableauTuples): def __init__(self, shape): r""" - Initializes the class of semistandard tableaux of shape ``p`` and no + Initialize the class of semistandard tableaux of shape ``p`` and no maximum entry. Input is not checked; please use :class:`StandardTableauTuples` to ensure the options are properly parsed. @@ -4867,7 +4842,7 @@ def __iter__(self): # now use clen and cclen to "inflate" tab into a tableau def tableau_from_list(tab): """ - Converts a list tab=[t_1,...,t_n] into the mu-tableau obtained by + Convert a list tab=[t_1,...,t_n] into the mu-tableau obtained by inserting t_1,..,t_n in order into the rows of mu, from left to right in each component and then left to right along the components. """ @@ -5340,9 +5315,7 @@ def _add_entry_fast(T, cell, m): - ``cell`` -- the cell - ``m`` -- the entry to add - OUTPUT: - - - a list of lists of lists representing the tableau tuple + OUTPUT: list of lists of lists representing the tableau tuple .. WARNING:: diff --git a/src/sage/combinat/tamari_lattices.py b/src/sage/combinat/tamari_lattices.py index f3e4de13a28..e38fcfbc7ed 100644 --- a/src/sage/combinat/tamari_lattices.py +++ b/src/sage/combinat/tamari_lattices.py @@ -61,14 +61,12 @@ def paths_in_triangle(i, j, a, b) -> list[tuple[int, ...]]: INPUT: - - `a` and `b` -- integers with `a \geq b` + - ``a``, ``b`` -- integers with `a \geq b` - - `i` and `j` -- nonnegative integers with `1 \geq \frac{j}{b} \geq + - ``i``, ``j`` -- nonnegative integers with `1 \geq \frac{j}{b} \geq \frac{i}{a} \geq 0` - OUTPUT: - - - a list of paths + OUTPUT: list of paths EXAMPLES:: @@ -110,11 +108,9 @@ def swap(p, i, m=1) -> tuple[int, ...]: - ``p`` -- a Dyck path in the `(a \times b)`-rectangle - - ``i`` -- an integer between `0` and `a+b-1` - - OUTPUT: + - ``i`` -- integer between `0` and `a+b-1` - - a Dyck path in the `(a \times b)`-rectangle + OUTPUT: a Dyck path in the `(a \times b)`-rectangle EXAMPLES:: @@ -169,9 +165,9 @@ def GeneralizedTamariLattice(a, b, m=1): INPUT: - - `a` and `b` -- integers with `a \geq b` + - ``a``, ``b`` -- integers with `a \geq b` - - `m` -- a nonnegative rational number such that `a \geq b m` + - ``m`` -- a nonnegative rational number such that `a \geq b m` OUTPUT: @@ -239,13 +235,11 @@ def TamariLattice(n, m=1): INPUT: - - `n` -- a nonnegative integer (the index) + - ``n`` -- nonnegative integer (the index) - - `m` -- an optional nonnegative integer (the slope, default to 1) + - ``m`` -- nonnegative integer (the slope, default: 1) - OUTPUT: - - a finite lattice + OUTPUT: a finite lattice In the usual case, the elements of the lattice are :func:`Dyck paths` in the `(n+1 \times @@ -284,7 +278,7 @@ def swap_dexter(p, i) -> list[tuple[int, ...]]: - ``p`` -- a Dyck path in the `(a \times b)`-rectangle - - ``i`` -- an integer between `0` and `a+b-1` + - ``i`` -- integer between `0` and `a+b-1` OUTPUT: @@ -350,11 +344,9 @@ def DexterSemilattice(n): INPUT: - - ``n`` -- a nonnegative integer (the index) - - OUTPUT: + - ``n`` -- nonnegative integer (the index) - a finite meet-semilattice + OUTPUT: a finite meet-semilattice The elements of the semilattice are :func:`Dyck paths` in the `(n+1 \times diff --git a/src/sage/combinat/tiling.py b/src/sage/combinat/tiling.py index 797852a2851..9aed8fd0652 100644 --- a/src/sage/combinat/tiling.py +++ b/src/sage/combinat/tiling.py @@ -157,7 +157,7 @@ sage: L.append(Polyomino([(0,0),(0,1),(0,2),(1,0),(1,1),(1,2)],"pink")) By default, rotations are allowed and reflections are not. In this case, -there are no solution for tiling a `8 \times 8` rectangular box:: +there are no solutions for tiling a `8 \times 8` rectangular box:: sage: T = TilingSolver(L, box=(8,8)) sage: T.number_of_solutions() # long time (2.5s) @@ -304,12 +304,10 @@ def ncube_isometry_group(n, orientation_preserving=True): INPUT: - ``n`` -- positive integer, dimension of the space - - ``orientation_preserving`` -- bool (default: ``True``), + - ``orientation_preserving`` -- boolean (default: ``True``); whether the orientation is preserved - OUTPUT: - - list of matrices + OUTPUT: list of matrices EXAMPLES:: @@ -372,12 +370,10 @@ def ncube_isometry_group_cosets(n, orientation_preserving=True): INPUT: - ``n`` -- positive integer, dimension of the space - - ``orientation_preserving`` -- bool (default: ``True``), + - ``orientation_preserving`` -- boolean (default: ``True``); whether the orientation is preserved - OUTPUT: - - list of cosets, each coset being a sorted list of matrices + OUTPUT: list of cosets, each coset being a sorted list of matrices EXAMPLES:: @@ -485,8 +481,8 @@ class Polyomino(SageObject): INPUT: - ``coords`` -- iterable of integer coordinates in `\ZZ^d` - - ``color`` -- string (default: ``'gray'``), color for display - - ``dimension`` -- integer (default: ``None``), dimension of the space, + - ``color`` -- string (default: ``'gray'``); color for display + - ``dimension`` -- integer (default: ``None``); dimension of the space, if ``None``, it is guessed from the ``coords`` if ``coords`` is non empty @@ -518,7 +514,6 @@ def __init__(self, coords, color='gray', dimension=None): sage: Polyomino([], dimension=2) Polyomino: [], Color: gray - """ from sage.modules.free_module import FreeModule from sage.rings.integer_ring import ZZ @@ -666,9 +661,7 @@ def __eq__(self, other): - ``other`` -- a polyomino - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -691,9 +684,7 @@ def __ne__(self, other): - ``other`` -- a polyomino - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -716,9 +707,7 @@ def __le__(self, other): - ``other`` -- a polyomino - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -740,9 +729,7 @@ def __ge__(self, other): - ``other`` -- a polyomino - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -764,9 +751,7 @@ def __lt__(self, other): - ``other`` -- a polyomino - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -788,9 +773,7 @@ def __gt__(self, other): - ``other`` -- a polyomino - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -812,9 +795,7 @@ def intersection(self, other): - ``other`` -- a polyomino - OUTPUT: - - polyomino + OUTPUT: polyomino EXAMPLES:: @@ -840,9 +821,7 @@ def __sub__(self, v): - ``v`` -- tuple - OUTPUT: - - polyomino + OUTPUT: polyomino EXAMPLES:: @@ -862,9 +841,7 @@ def __add__(self, v): - ``v`` -- tuple - OUTPUT: - - polyomino + OUTPUT: polyomino EXAMPLES:: @@ -883,11 +860,9 @@ def __rmul__(self, m): INPUT: - - ``m`` -- square matrix, matching the dimension of ``self``. - - OUTPUT: + - ``m`` -- square matrix, matching the dimension of ``self`` - Polyomino + OUTPUT: polyomino EXAMPLES:: @@ -947,18 +922,16 @@ def canonical_isometric_copies(self, orientation_preserving=True, INPUT: - - ``orientation_preserving`` -- bool (default: ``True``); + - ``orientation_preserving`` -- boolean (default: ``True``); if ``True``, the group of isometries of the `n`-cube is restricted to those that preserve the orientation, i.e. of determinant 1. - - ``mod_box_isometries`` -- bool (default: ``False``), whether to + - ``mod_box_isometries`` -- boolean (default: ``False``); whether to quotient the group of isometries of the `n`-cube by the subgroup of isometries of the `a_1\times a_2\cdots \times a_n` rectangular box where are the `a_i` are assumed to be distinct. - OUTPUT: - - set of Polyomino + OUTPUT: set of Polyomino EXAMPLES:: @@ -1006,11 +979,9 @@ def translated_copies(self, box): INPUT: - - ``box`` -- Polyomino or tuple of integers (size of a box) - - OUTPUT: + - ``box`` -- polyomino or tuple of integers (size of a box) - iterator of 3d polyominoes + OUTPUT: iterator of 3d polyominoes EXAMPLES:: @@ -1111,11 +1082,9 @@ def translated_copies_intersection(self, box): INPUT: - - ``box`` -- Polyomino or tuple of integers (size of a box) + - ``box`` -- polyomino or tuple of integers (size of a box) - OUTPUT: - - set of 3d polyominoes + OUTPUT: set of 3d polyominoes EXAMPLES:: @@ -1140,7 +1109,6 @@ def translated_copies_intersection(self, box): sage: sorted(sorted(a.frozenset()) ....: for a in p.translated_copies_intersection(b)) [[(0, 0)], [(0, 0), (1, 0)], [(0, 1)], [(0, 2)], [(1, 0), (2, 0)], [(2, 0)]] - """ if not isinstance(box, Polyomino): ranges = [range(a) for a in box] @@ -1171,13 +1139,13 @@ def isometric_copies(self, box, orientation_preserving=True, INPUT: - - ``box`` -- Polyomino or tuple of integers (size of a box) + - ``box`` -- polyomino or tuple of integers (size of a box) - - ``orientation_preserving`` -- bool (default: ``True``); - If ``True``, the group of isometries of the `n`-cube is restricted + - ``orientation_preserving`` -- boolean (default: ``True``); + if ``True``, the group of isometries of the `n`-cube is restricted to those that preserve the orientation, i.e. of determinant 1. - - ``mod_box_isometries`` -- bool (default: ``False``), whether to + - ``mod_box_isometries`` -- boolean (default: ``False``); whether to quotient the group of isometries of the `n`-cube by the subgroup of isometries of the `a_1\times a_2\cdots \times a_n` rectangular box where are the `a_i` are assumed to be distinct. @@ -1239,9 +1207,9 @@ def isometric_copies_intersection(self, box, orientation_preserving=True): INPUT: - - ``box`` -- Polyomino or tuple of integers (size of a box) + - ``box`` -- polyomino or tuple of integers (size of a box) - - ``orientation_preserving`` -- bool (default: ``True``); + - ``orientation_preserving`` -- boolean (default: ``True``); if ``True``, the group of isometries of the `n`-cube is restricted to those that preserve the orientation, i.e. of determinant 1. @@ -1263,7 +1231,6 @@ def isometric_copies_intersection(self, box, orientation_preserving=True): [(1, 1)], [(1, 1), (1, 2)], [(1, 2)]] - """ all_distinct_cano = self.canonical_isometric_copies(orientation_preserving, mod_box_isometries=False) @@ -1394,7 +1361,7 @@ def show3d(self, size=1): INPUT: - ``self`` -- a polyomino of dimension 3 - - ``size`` -- number (default: ``1``), the size of each + - ``size`` -- number (default: ``1``); the size of each ``1 \times 1 \times 1`` cube. This does a homothety with respect to the center of the polyomino. @@ -1424,12 +1391,9 @@ def show2d(self, size=0.7, color='black', thickness=1): INPUT: - ``self`` -- a polyomino of dimension 2 - - ``size`` -- number (default: ``0.7``), the size of each - square. - - ``color`` -- color (default: ``'black'``), color of - the boundary line. - - ``thickness`` -- number (default: ``1``), how thick the - boundary line is. + - ``size`` -- number (default: ``0.7``); the size of each square + - ``color`` -- color (default: ``'black'``); color of the boundary line + - ``thickness`` -- number (default: ``1``); how thick the boundary line is EXAMPLES:: @@ -1466,17 +1430,15 @@ def self_surrounding(self, radius, remove_incomplete_copies=True, - ``self`` -- a polyomino of dimension 2 - ``radius`` -- integer - - ``remove_incomplete_copies`` -- bool (default: ``True``), whether + - ``remove_incomplete_copies`` -- boolean (default: ``True``); whether to keep only complete copies of ``self`` in the output - - ``ncpus`` -- integer (default: ``None``), maximal number of + - ``ncpus`` -- integer (default: ``None``); maximal number of subprocesses to use at the same time. If ``None``, it detects the number of effective CPUs in the system using :func:`sage.parallel.ncpus.ncpus()`. If ``ncpus=1``, the first solution is searched serially. - OUTPUT: - - list of polyominoes + OUTPUT: list of polyominoes EXAMPLES:: @@ -1492,7 +1454,6 @@ def self_surrounding(self, radius, remove_incomplete_copies=True, sage: solution = H.self_surrounding(8, remove_incomplete_copies=False) sage: G = sum([p.show2d() for p in solution], Graphics()) # needs sage.plot - """ # Define the box to tile minxyz, maxxyz = self.bounding_box() @@ -1545,7 +1506,7 @@ def self_surrounding(self, radius, remove_incomplete_copies=True, ####################### class TilingSolver(SageObject): r""" - Tiling solver + Tiling solver. Solve the problem of tiling a polyomino with a certain number of polyominoes. @@ -1553,14 +1514,14 @@ class TilingSolver(SageObject): INPUT: - ``pieces`` -- iterable of Polyominoes - - ``box`` -- Polyomino or tuple of integers (size of a box) - - ``rotation`` -- bool (default: ``True``), whether to allow + - ``box`` -- polyomino or tuple of integers (size of a box) + - ``rotation`` -- boolean (default: ``True``); whether to allow rotations - - ``reflection`` -- bool (default: ``False``), whether to allow + - ``reflection`` -- boolean (default: ``False``); whether to allow reflections - - ``reusable`` -- bool (default: ``False``), whether to allow + - ``reusable`` -- boolean (default: ``False``); whether to allow the pieces to be reused - - ``outside`` -- bool (default: ``False``), whether to allow + - ``outside`` -- boolean (default: ``False``); whether to allow pieces to partially go outside of the box (all non-empty intersection of the pieces with the box are considered) @@ -1645,7 +1606,7 @@ def __init__(self, pieces, box, rotation=True, def _repr_(self): r""" - String representation + String representation. EXAMPLES:: @@ -1658,7 +1619,6 @@ def _repr_(self): Rotation allowed: True Reflection allowed: False Reusing pieces allowed: False - """ s = "Tiling solver of %s pieces " % len(self._pieces) s += "into a box of size %s\n" % len(self._box) @@ -1699,9 +1659,7 @@ def pieces(self): r""" Return the list of pieces. - OUTPUT: - - list of 3d polyominoes + OUTPUT: list of 3d polyominoes EXAMPLES:: @@ -1719,7 +1677,7 @@ def pieces(self): def space(self): r""" - Return an iterator over all the non negative integer coordinates + Return an iterator over all the nonnegative integer coordinates contained in the space to tile. EXAMPLES:: @@ -1739,9 +1697,7 @@ def coord_to_int_dict(self): r""" Return a dictionary mapping coordinates to integers. - OUTPUT: - - dict + OUTPUT: dictionary EXAMPLES:: @@ -1822,9 +1778,9 @@ def rows_for_piece(self, i, mod_box_isometries=False): INPUT: - - ``i`` -- integer, the `i`-th piece + - ``i`` -- integer; the `i`-th piece - - ``mod_box_isometries`` -- bool (default: ``False``), whether to + - ``mod_box_isometries`` -- boolean (default: ``False``); whether to consider only rows for positions up to the action of the quotient the group of isometries of the `n`-cube by the subgroup of isometries of the `a_1\times a_2\cdots \times a_n` @@ -1896,7 +1852,7 @@ def rows_for_piece(self, i, mod_box_isometries=False): @cached_method def rows(self): r""" - Creation of the rows + Creation of the rows. EXAMPLES:: @@ -1941,8 +1897,8 @@ def _rows_mod_box_isometries(self, i): INPUT: - - ``i`` -- integer, the `i`-th piece to consider, that piece must not - be isometric to itself by a isometry that preserve the box. + - ``i`` -- integer; the `i`-th piece to consider, that piece must not + be isometric to itself by a isometry that preserve the box EXAMPLES:: @@ -1984,7 +1940,7 @@ def _rows_mod_box_isometries(self, i): Dancing links solver for 96 columns and 5484 rows It is possible to avoid to compute 4 times each solution up to - rotations. This is done by choosing a piece (here the 0-th) and + rotations. This is done by choosing a piece (here the 0th) and considering 4 times less positions for that piece. To be precise, 90 positions instead of 360, therefore the dancing links solver below has 270 less rows:: @@ -2008,9 +1964,7 @@ def nrows_per_piece(self): r""" Return the number of rows necessary by each piece. - OUTPUT: - - list + OUTPUT: list EXAMPLES:: @@ -2049,11 +2003,9 @@ def row_to_polyomino(self, row_number): INPUT: - - ``row_number`` -- integer, the `i`-th row - - OUTPUT: + - ``row_number`` -- integer; the `i`-th row - polyomino + OUTPUT: polyomino EXAMPLES:: @@ -2079,8 +2031,8 @@ def row_to_polyomino(self, row_number): We check that issue :issue:`32252` is fixed and that colors of polyominoes are properly recovered:: - sage: v = Polyomino([(0, 0), (0, 1)], color="blue") - sage: h = Polyomino([(0, 0), (1, 0)], color="red") + sage: v = Polyomino([(0, 0), (0, 1)], color='blue') + sage: h = Polyomino([(0, 0), (1, 0)], color='red') sage: T = TilingSolver(pieces=[v, h], box=(2, 2), ....: rotation=False, reflection=False, reusable=True) sage: for i in range(4): print(i,T.row_to_polyomino(i)) @@ -2088,7 +2040,6 @@ def row_to_polyomino(self, row_number): 1 Polyomino: [(1, 0), (1, 1)], Color: blue 2 Polyomino: [(0, 0), (1, 0)], Color: red 3 Polyomino: [(0, 1), (1, 1)], Color: red - """ rows = self.rows() row = rows[row_number] @@ -2110,9 +2061,7 @@ def dlx_solver(self): r""" Return the sage DLX solver of that tiling problem. - OUTPUT: - - DLX Solver + OUTPUT: dLX Solver EXAMPLES:: @@ -2131,9 +2080,7 @@ def _dlx_solutions_iterator(self): r""" Return an iterator over the row indices of the solutions. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -2160,9 +2107,7 @@ def _dlx_common_prefix_solutions_iterator(self): The purpose is to illustrate the backtracking and construct an animation of the evolution of solutions. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -2229,9 +2174,7 @@ def _dlx_incremental_solutions_iterator(self): The purpose is to illustrate the backtracking and construct an animation of the evolution of solutions. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -2289,7 +2232,7 @@ def solve(self, partial=None): INPUT: - - ``partial`` -- string (default: ``None``), whether to + - ``partial`` -- string (default: ``None``); whether to include partial (incomplete) solutions. It can be one of the following: @@ -2297,9 +2240,7 @@ def solve(self, partial=None): - ``'common_prefix'`` -- common prefix between two consecutive solutions - ``'incremental'`` -- one piece change at a time - OUTPUT: - - iterator of list of polyominoes + OUTPUT: iterator of list of polyominoes EXAMPLES:: @@ -2363,7 +2304,6 @@ def solve(self, partial=None): Traceback (most recent call last): ... StopIteration - """ if not self.is_suitable(): return @@ -2382,9 +2322,7 @@ def number_of_solutions(self): r""" Return the number of distinct solutions. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -2416,7 +2354,7 @@ def animate(self, partial=None, stop=None, size=0.75, axes=False): INPUT: - - ``partial`` -- string (default: ``None``), whether to + - ``partial`` -- string (default: ``None``); whether to include partial (incomplete) solutions. It can be one of the following: @@ -2424,14 +2362,14 @@ def animate(self, partial=None, stop=None, size=0.75, axes=False): - ``'common_prefix'`` -- common prefix between two consecutive solutions - ``'incremental'`` -- one piece change at a time - - ``stop`` -- integer (default:``None``), number of frames + - ``stop`` -- integer (default: ``None``); number of frames - - ``size`` -- number (default: ``0.75``), the size of each + - ``size`` -- number (default: ``0.75``); the size of each ``1 \times 1`` square. This does a homothety with respect to the center of each polyomino. - - ``axes`` -- bool (default:``False``), whether the x and - y axes are shown. + - ``axes`` -- boolean (default: ``False``); whether the x and + y axes are shown EXAMPLES:: @@ -2461,7 +2399,7 @@ def animate(self, partial=None, stop=None, size=0.75, axes=False): The ``show`` function takes arguments to specify the delay between frames (measured in hundredths of a second, default value 20) and - the number of iterations (default value 0, which means to iterate + the number of iterations (default: 0, which means to iterate forever). To iterate 4 times with half a second between each frame:: sage: a.show(delay=50, iterations=4) # long time, optional - imagemagick, needs sage.plot diff --git a/src/sage/combinat/triangles_FHM.py b/src/sage/combinat/triangles_FHM.py index 6822f342658..ebd457d7487 100644 --- a/src/sage/combinat/triangles_FHM.py +++ b/src/sage/combinat/triangles_FHM.py @@ -7,7 +7,7 @@ invertible rational change-of-variables involving `x` and `y`. These polynomial are called triangles because their supports, the sets -of exponents where their coefficients can be non-zero, have a triangular shape. +of exponents where their coefficients can be nonzero, have a triangular shape. The M-triangle class is motivated by the generating series of Möbius numbers for graded posets. A typical example is:: @@ -60,7 +60,7 @@ def _matrix_display(self, variables=None): INPUT: - - ``variables`` -- optional choice of 2 variables + - ``variables`` -- (optional) choice of 2 variables OUPUT: @@ -388,9 +388,7 @@ def transmute(self): """ Return the image of ``self`` by an involution. - OUTPUT: - - another M-triangle + OUTPUT: another M-triangle The involution is defined by converting to an H-triangle, transposing the matrix, and then converting back to an M-triangle. @@ -466,9 +464,7 @@ def transpose(self): """ Return the transposed H-triangle. - OUTPUT: - - another H-triangle + OUTPUT: another H-triangle This operation is an involution. When seen as a matrix, it performs a symmetry with respect to the northwest-southeast diff --git a/src/sage/combinat/tutorial.py b/src/sage/combinat/tutorial.py index 0da72d30dbf..1b8555f4565 100644 --- a/src/sage/combinat/tutorial.py +++ b/src/sage/combinat/tutorial.py @@ -461,7 +461,7 @@ sage: fraction = - R(Px) / R(Py); fraction # needs sage.symbolic (1/2/(x - 1/4))*ybar - 1/4/(x - 1/4) -.. note:: +.. NOTE:: The following variant does not work yet:: @@ -1540,7 +1540,7 @@ These sets share the same underlying algorithmic structure, implemented in the more general (and slightly more cumbersome) class ``IntegerListsLex``. This class models sets of vectors -`(\ell_0,\dots,\ell_k)` of non-negative integers, with +`(\ell_0,\dots,\ell_k)` of nonnegative integers, with constraints on the sum and the length, and bounds on the parts and on the consecutive differences between the parts. Here are some more examples:: diff --git a/src/sage/combinat/vector_partition.py b/src/sage/combinat/vector_partition.py index 9e5f5ac9025..1f41c08d7af 100644 --- a/src/sage/combinat/vector_partition.py +++ b/src/sage/combinat/vector_partition.py @@ -36,7 +36,7 @@ def find_min(vect): INPUT: - - ``vec`` -- A list of integers + - ``vec`` -- list of integers OUTPUT: @@ -68,8 +68,8 @@ def IntegerVectorsIterator(vect, min=None): INPUT: - - ``vect`` -- A list of non-negative integers - - ``min`` -- A list of non-negative integers dominated elementwise by ``vect`` + - ``vect`` -- list of nonnegative integers + - ``min`` -- list of nonnegative integers dominated elementwise by ``vect`` OUTPUT: @@ -169,16 +169,18 @@ class VectorPartitions(UniqueRepresentation, Parent): Class of all vector partitions of ``vec`` with all parts greater than or equal to ``min`` in lexicographic order, with parts from ``parts``. - A vector partition of ``vec`` is a list of vectors with non-negative + A vector partition of ``vec`` is a list of vectors with nonnegative integer entries whose sum is ``vec``. INPUT: - - ``vec`` -- Integer vector - - ``min`` -- Integer vector dominated elementwise by ``vec`` - - ``parts`` -- Finite list of possible parts - - ``distinct`` -- Boolean, set to ``True`` if only vector partitions with distinct parts are enumerated - - ``is_repeatable`` -- Boolean function on ``parts`` which gives ``True`` in parts that can be repeated + - ``vec`` -- integer vector + - ``min`` -- integer vector dominated elementwise by ``vec`` + - ``parts`` -- finite list of possible parts + - ``distinct`` -- boolean, set to ``True`` if only vector partitions with + distinct parts are enumerated + - ``is_repeatable`` -- boolean function on ``parts`` which gives ``True`` + in parts that can be repeated EXAMPLES: @@ -238,7 +240,6 @@ class VectorPartitions(UniqueRepresentation, Parent): sage: Vector_Partitions = VectorPartitions([2,2], parts=[[0,1],[1,0],[1,1]], is_repeatable=lambda vec: sum(vec)%2!=0) sage: list(Vector_Partitions) [[[0, 1], [0, 1], [1, 0], [1, 0]], [[0, 1], [1, 0], [1, 1]]] - """ @staticmethod def __classcall_private__(cls, vec, min=None, parts=None, distinct=False, is_repeatable=None): diff --git a/src/sage/combinat/words/abstract_word.py b/src/sage/combinat/words/abstract_word.py index 3c76c4d6de3..21d17ab759f 100644 --- a/src/sage/combinat/words/abstract_word.py +++ b/src/sage/combinat/words/abstract_word.py @@ -44,11 +44,11 @@ class Word_class(SageObject): def parent(self): r""" - Returns the parent of self. + Return the parent of ``self``. TESTS:: - sage: Word(iter([1,2,3]), length="unknown").parent() + sage: Word(iter([1,2,3]), length='unknown').parent() Finite words over Set of Python objects of class 'object' sage: Word(range(12)).parent() Finite words over Set of Python objects of class 'object' @@ -61,13 +61,13 @@ def parent(self): def _repr_(self): r""" - Returns a string representation of self. + Return a string representation of ``self``. TESTS:: - sage: Word(iter([1,2,3]), length="unknown")._repr_() + sage: Word(iter([1,2,3]), length='unknown')._repr_() 'word: 123' - sage: Word(range(100), length="unknown")._repr_() + sage: Word(range(100), length='unknown')._repr_() 'word: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,...' sage: Word(lambda x:x%3)._repr_() 'word: 0120120120120120120120120120120120120120...' @@ -78,7 +78,7 @@ def _repr_(self): def string_rep(self): r""" - Returns the (truncated) raw sequence of letters as a string. + Return the (truncated) raw sequence of letters as a string. EXAMPLES:: @@ -157,21 +157,21 @@ def __iter__(self): def length(self): r""" - Returns the length of self. + Return the length of ``self``. TESTS:: sage: from sage.combinat.words.word import Word_class - sage: w = Word(iter('abba'*100), length="unknown") + sage: w = Word(iter('abba'*100), length='unknown') sage: w.length() is None True - sage: w = Word(iter('abba'), length="finite") + sage: w = Word(iter('abba'), length='finite') sage: w.length() 4 - sage: w = Word(iter([0,1,1,0,1,0,0,1]*100), length="unknown") + sage: w = Word(iter([0,1,1,0,1,0,0,1]*100), length='unknown') sage: w.length() is None True - sage: w = Word(iter([0,1,1,0,1,0,0,1]), length="finite") + sage: w = Word(iter([0,1,1,0,1,0,0,1]), length='finite') sage: w.length() 8 """ @@ -179,7 +179,7 @@ def length(self): def is_finite(self): r""" - Returns whether this word is known to be finite. + Return whether this word is known to be finite. .. WARNING:: @@ -201,22 +201,19 @@ def is_finite(self): sage: w = Word(iter('a'*100)) sage: w.is_finite() False - """ return False def __len__(self): r""" - Return the length of self (as a python integer). + Return the length of ``self`` (as a Python integer). .. NOTE:: For infinite words or words of unknown length, use `length()` method instead. - OUTPUT: - - positive integer + OUTPUT: positive integer EXAMPLES:: @@ -375,26 +372,24 @@ def __richcmp__(self, other, op): def _longest_common_prefix_iterator(self, other): r""" - Return an iterator of the longest common prefix of self and other. + Return an iterator of the longest common prefix of ``self`` and ``other``. INPUT: - - ``other`` -- word - - OUTPUT: + - ``other`` -- word - iterator + OUTPUT: iterator EXAMPLES:: sage: f = words.FibonacciWord() sage: it = f._longest_common_prefix_iterator(f) - sage: w = Word(it, length="unknown"); w + sage: w = Word(it, length='unknown'); w word: 0100101001001010010100100101001001010010... sage: w[:6] word: 010010 sage: it = w._longest_common_prefix_iterator(w[:10]) - sage: w = Word(it, length="finite"); w + sage: w = Word(it, length='finite'); w word: 0100101001 """ for (b, c) in zip(self, other): @@ -405,19 +400,19 @@ def _longest_common_prefix_iterator(self, other): def longest_common_prefix(self, other, length='unknown'): r""" - Returns the longest common prefix of self and other. + Return the longest common prefix of ``self`` and ``other``. INPUT: - - ``other`` -- word + - ``other`` -- word - - ``length`` -- string (default: ``'unknown'``) - the length type of the resulting word if known. It may be one of - the following: + - ``length`` -- string (default: ``'unknown'``) + the length type of the resulting word if known. It may be one of + the following: - - ``'unknown'`` - - ``'finite'`` - - ``'infinite'`` + - ``'unknown'`` + - ``'finite'`` + - ``'infinite'`` EXAMPLES:: @@ -501,16 +496,14 @@ def longest_common_prefix(self, other, length='unknown'): def _longest_periodic_prefix_iterator(self, period=1): r""" - Returns an iterator of the longest prefix of self having the given + Return an iterator of the longest prefix of ``self`` having the given period. INPUT: - ``period`` -- positive integer (default: 1) - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -537,15 +530,13 @@ def _longest_periodic_prefix_iterator(self, period=1): def longest_periodic_prefix(self, period=1): r""" - Returns the longest prefix of self having the given period. + Return the longest prefix of ``self`` having the given period. INPUT: - ``period`` -- positive integer (default: 1) - OUTPUT: - - word + OUTPUT: word EXAMPLES:: @@ -573,7 +564,7 @@ def longest_periodic_prefix(self, period=1): def is_empty(self): r""" - Returns True if the length of self is zero, and False otherwise. + Return ``True`` if the length of ``self`` is zero, and ``False`` otherwise. EXAMPLES:: @@ -595,15 +586,15 @@ def is_empty(self): def _to_integer_iterator(self, use_parent_alphabet=False): r""" - Returns an iterator over the letters of an integer representation of - self. + Return an iterator over the letters of an integer representation of + ``self``. INPUT: - - ``use_parent_alphabet`` -- Bool (default: ``False``). When True and if - the self parent's alphabet is finite, it uses the index of + - ``use_parent_alphabet`` -- boolean (default: ``False``); when ``True`` + and if the ``self`` parent's alphabet is finite, it uses the index of the letters in the alphabet. Otherwise, the first letter occurring in - self is mapped to zero, and every letter that hasn't yet occurred in + ``self`` is mapped to zero, and every letter that hasn't yet occurred in the word is mapped to the next available integer. EXAMPLES:: @@ -648,7 +639,7 @@ def _to_integer_iterator(self, use_parent_alphabet=False): def to_integer_word(self): r""" - Returns a word over the integers whose letters are those output by + Return a word over the integers whose letters are those output by self._to_integer_iterator() EXAMPLES:: @@ -658,11 +649,11 @@ def to_integer_word(self): word: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,... sage: w.to_integer_word() word: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,... - sage: w = Word(iter("abbacabba"), length="finite"); w + sage: w = Word(iter("abbacabba"), length='finite'); w word: abbacabba sage: w.to_integer_word() word: 011020110 - sage: w = Word(iter("abbacabba"), length="unknown"); w + sage: w = Word(iter("abbacabba"), length='unknown'); w word: abbacabba sage: w.to_integer_word() word: 011020110 @@ -673,7 +664,7 @@ def to_integer_word(self): def lex_less(self, other): r""" - Returns True if self is lexicographically less than other. + Return ``True`` if ``self`` is lexicographically less than ``other``. EXAMPLES:: @@ -703,7 +694,7 @@ def lex_less(self, other): def lex_greater(self, other): r""" - Returns True if self is lexicographically greater than other. + Return ``True`` if ``self`` is lexicographically greater than ``other``. EXAMPLES:: @@ -733,12 +724,12 @@ def lex_greater(self, other): def apply_morphism(self, morphism): r""" - Returns the word obtained by applying the morphism to self. + Return the word obtained by applying the morphism to ``self``. INPUT: - - ``morphism`` -- Can be an instance of WordMorphism, or - anything that can be used to construct one. + - ``morphism`` -- can be an instance of WordMorphism, or + anything that can be used to construct one EXAMPLES:: @@ -772,13 +763,11 @@ def apply_morphism(self, morphism): def _delta_iterator(self): r""" - Returns an iterator of the image of self under the delta morphism. + Return an iterator of the image of ``self`` under the delta morphism. This is the word composed of the length of consecutive runs of the same letter in a given word. - OUTPUT: - - generator object + OUTPUT: generator object EXAMPLES:: @@ -803,14 +792,12 @@ def _delta_iterator(self): def delta(self): r""" - Returns the image of self under the delta morphism. + Return the image of ``self`` under the delta morphism. This is the word composed of the length of consecutive runs of the same letter in a given word. - OUTPUT: - - Word over integers + OUTPUT: word over integers EXAMPLES: @@ -838,16 +825,14 @@ def delta(self): def _iterated_right_palindromic_closure_iterator(self, f=None): r""" - Returns an iterator over the iterated (`f`-)palindromic closure of self. + Return an iterator over the iterated (`f`-)palindromic closure of ``self``. INPUT: - - ``f`` -- involution (default: None) on the alphabet of self. It must - be callable on letters as well as words (e.g. WordMorphism). - - OUTPUT: + - ``f`` -- involution on the alphabet of ``self`` (default: ``None``); + it must be callable on letters as well as words (e.g. WordMorphism) - iterator -- the iterated (`f`-)palindromic closure of self + OUTPUT: iterator; the iterated (`f`-)palindromic closure of ``self`` EXAMPLES:: @@ -904,16 +889,14 @@ def _iterated_right_palindromic_closure_iterator(self, f=None): def _iterated_right_palindromic_closure_recursive_iterator(self, f=None): r""" - Returns an iterator over the iterated (`f`-)palindromic closure of self. + Return an iterator over the iterated (`f`-)palindromic closure of ``self``. INPUT: - - ``f`` -- involution (default: None) on the alphabet of self. It must - be callable on letters as well as words (e.g. WordMorphism). + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. WordMorphism) - OUTPUT: - - iterator -- the iterated (`f`-)palindromic closure of self + OUTPUT: iterator; the iterated (`f`-)palindromic closure of ``self`` ALGORITHM: @@ -994,26 +977,24 @@ def _iterated_right_palindromic_closure_recursive_iterator(self, f=None): def iterated_right_palindromic_closure(self, f=None, algorithm='recursive'): r""" - Returns the iterated (`f`-)palindromic closure of self. + Return the iterated (`f`-)palindromic closure of ``self``. INPUT: - - ``f`` -- involution (default: None) on the alphabet of self. It must - be callable on letters as well as words (e.g. WordMorphism). - - - ``algorithm`` -- string (default: ``'recursive'``) specifying which - algorithm to be used when computing the iterated palindromic closure. - It must be one of the two following values: + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. WordMorphism) - - ``'definition'`` -- computed using the definition - - ``'recursive'`` -- computation based on an efficient formula - that recursively computes the iterated right palindromic closure - without having to recompute the longest `f`-palindromic suffix - at each iteration [2]. + - ``algorithm`` -- string (default: ``'recursive'``); specifying which + algorithm to be used when computing the iterated palindromic closure. + It must be one of the two following values: - OUTPUT: + - ``'definition'`` -- computed using the definition + - ``'recursive'`` -- computation based on an efficient formula + that recursively computes the iterated right palindromic closure + without having to recompute the longest `f`-palindromic suffix + at each iteration [2]. - word -- the iterated (`f`-)palindromic closure of self + OUTPUT: word; the iterated (`f`-)palindromic closure of ``self`` EXAMPLES:: @@ -1111,16 +1092,14 @@ def iterated_right_palindromic_closure(self, f=None, algorithm='recursive'): def prefixes_iterator(self, max_length=None): r""" - Returns an iterator over the prefixes of self. + Return an iterator over the prefixes of ``self``. INPUT: - - ``max_length`` -- non negative integer or None (optional, - default: None) the maximum length of the prefixes + - ``max_length`` -- nonnegative integer or ``None`` (default); the + maximum length of the prefixes - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -1165,16 +1144,14 @@ def prefixes_iterator(self, max_length=None): def palindrome_prefixes_iterator(self, max_length=None): r""" - Returns an iterator over the palindrome prefixes of self. + Return an iterator over the palindrome prefixes of ``self``. INPUT: - - ``max_length`` -- non negative integer or None (optional, - default: None) the maximum length of the prefixes - - OUTPUT: + - ``max_length`` -- nonnegative integer or ``None`` (default); the + maximum length of the prefixes - iterator + OUTPUT: iterator EXAMPLES:: @@ -1206,13 +1183,13 @@ def palindrome_prefixes_iterator(self, max_length=None): def _partial_sums_iterator(self, start, mod=None): r""" - Iterator over the partial sums of the prefixes of self. + Iterator over the partial sums of the prefixes of ``self``. INPUT: - - ``self`` -- A word over the integers. - - ``start`` -- integer, the first letter of the resulting word. - - ``mod`` -- (default: None) It can be one of the following: + - ``self`` -- a word over the integers + - ``start`` -- integer; the first letter of the resulting word + - ``mod`` -- (default: ``None``) it can be one of the following: - None or 0 : result is over the integers - integer : result is over the integers modulo ``mod``. @@ -1233,7 +1210,6 @@ def _partial_sums_iterator(self, start, mod=None): sage: w = Word([1,1,1,1,1,1,1,1,1,1,1,1]) sage: list(w._partial_sums_iterator(0)) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] - """ if mod in (None, 0): sum = start @@ -1252,13 +1228,13 @@ def _partial_sums_iterator(self, start, mod=None): def partial_sums(self, start, mod=None): r""" - Returns the word defined by the partial sums of its prefixes. + Return the word defined by the partial sums of its prefixes. INPUT: - - ``self`` -- A word over the integers. - - ``start`` -- integer, the first letter of the resulting word. - - ``mod`` -- (default: None) It can be one of the following: + - ``self`` -- a word over the integers + - ``start`` -- integer; the first letter of the resulting word + - ``mod`` -- (default: ``None``) it can be one of the following: - None or 0 : result is over the integers - integer : result is over the integers modulo ``mod``. @@ -1317,8 +1293,8 @@ def _finite_differences_iterator(self, mod=None): INPUT: - - ``self`` -- A word over the integers. - - ``mod`` -- (default: None) It can be one of the following: + - ``self`` -- a word over the integers + - ``mod`` -- (default: ``None``) it can be one of the following: - None or 0 : result is over the integers - integer : result is over the integers modulo ``mod``. @@ -1393,8 +1369,8 @@ def finite_differences(self, mod=None): INPUT: - - ``self`` -- A word over the integers. - - ``mod`` -- (default: None) It can be one of the following: + - ``self`` -- a word over the integers + - ``mod`` -- (default: ``None``) it can be one of the following: - None or 0 : result is over the integers - integer : result is over the integers modulo ``mod``. @@ -1455,16 +1431,14 @@ def sum_digits(self, base=2, mod=None): INPUT: - - ``self`` -- word over natural numbers - - - ``base`` -- integer (default : 2), greater or equal to 2 - - - ``mod`` -- modulo (default: ``None``), can take the following - values: + - ``self`` -- word over natural numbers - - integer -- the modulo + - ``base`` -- integer (default: 2) greater or equal to 2 - - ``None`` -- the value ``base`` is considered for the modulo. + - ``mod`` -- modulo (default: ``None``); can take the following + values: + - ``integer`` -- the modulo + - ``None`` -- the value ``base`` is considered for the modulo EXAMPLES: @@ -1555,11 +1529,9 @@ def first_occurrence(self, other, start=0): INPUT: - ``other`` -- a finite word - - ``start`` -- integer (default:``0``), where the search starts + - ``start`` -- integer (default: `0`) where the search starts - OUTPUT: - - integer or ``None`` + OUTPUT: integer or ``None`` EXAMPLES:: @@ -1616,16 +1588,14 @@ def first_occurrence(self, other, start=0): def factor_occurrences_iterator(self, fact): r""" - Returns an iterator over all occurrences (including overlapping ones) - of fact in self in their order of appearance. + Return an iterator over all occurrences (including overlapping ones) + of fact in ``self`` in their order of appearance. INPUT: - ``fact`` -- a non empty finite word - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -1657,16 +1627,14 @@ def factor_occurrences_iterator(self, fact): def return_words_iterator(self, fact): r""" - Returns an iterator over all the return words of fact in self + Return an iterator over all the return words of fact in self (without unicity). INPUT: - ``fact`` -- a non empty finite word - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -1705,8 +1673,8 @@ def return_words_iterator(self, fact): def complete_return_words_iterator(self, fact): r""" - Returns an iterator over all the complete return words of fact in - self (without unicity). + Return an iterator over all the complete return words of fact in + ``self`` (without unicity). A complete return words `u` of a factor `v` is a factor starting by the given factor `v` and ending just after the next occurrence @@ -1716,9 +1684,7 @@ def complete_return_words_iterator(self, fact): - ``fact`` -- a non empty finite word - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: diff --git a/src/sage/combinat/words/alphabet.py b/src/sage/combinat/words/alphabet.py index 19ac17054b8..4c899084eff 100644 --- a/src/sage/combinat/words/alphabet.py +++ b/src/sage/combinat/words/alphabet.py @@ -14,11 +14,11 @@ {'a', 'b'} sage: build_alphabet([0,1,2]) {0, 1, 2} - sage: build_alphabet(name="PP") + sage: build_alphabet(name='PP') Positive integers - sage: build_alphabet(name="NN") + sage: build_alphabet(name='NN') Non negative integers - sage: build_alphabet(name="lower") + sage: build_alphabet(name='lower') {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'} """ # **************************************************************************** @@ -80,8 +80,8 @@ def build_alphabet(data=None, names=None, name=None): punctuation'`` represents the union of the two alphabets ``'lower'`` and ``'punctuation'``. - Alternatively, ``name`` can be set to ``"positive integers"`` (or - ``"PP"``) or ``"natural numbers"`` (or ``"NN"``). + Alternatively, ``name`` can be set to ``'positive integers'`` (or + ``'PP'``) or ``'natural numbers'`` (or ``'NN'``). ``name`` cannot be combined with ``data``. @@ -124,7 +124,7 @@ def build_alphabet(data=None, names=None, name=None): sage: build_alphabet(name="positive integers") Positive integers - sage: build_alphabet(name="PP") + sage: build_alphabet(name='PP') Positive integers sage: build_alphabet(name="natural numbers") Non negative integers @@ -136,9 +136,9 @@ def build_alphabet(data=None, names=None, name=None): 'decimal', 'hexadecimal', 'radix64' which refer to standard set of characters. Theses names may be combined by separating them by a space:: - sage: build_alphabet(name="lower") + sage: build_alphabet(name='lower') {'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'} - sage: build_alphabet(name="hexadecimal") + sage: build_alphabet(name='hexadecimal') {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'} sage: build_alphabet(name="decimal punctuation") {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', ' ', ',', '.', ';', ':', '!', '?'} @@ -183,7 +183,7 @@ def build_alphabet(data=None, names=None, name=None): TESTS:: - sage: Alphabet(3, name="punctuation") + sage: Alphabet(3, name='punctuation') Traceback (most recent call last): ... ValueError: name cannot be specified with any other argument @@ -195,7 +195,7 @@ def build_alphabet(data=None, names=None, name=None): Traceback (most recent call last): ... ValueError: invalid value for names - sage: Alphabet(name=x, names="punctuation") # needs sage.symbolic + sage: Alphabet(name=x, names='punctuation') # needs sage.symbolic Traceback (most recent call last): ... ValueError: name cannot be specified with any other argument diff --git a/src/sage/combinat/words/finite_word.py b/src/sage/combinat/words/finite_word.py index 8cc01a3c085..c754b029692 100644 --- a/src/sage/combinat/words/finite_word.py +++ b/src/sage/combinat/words/finite_word.py @@ -307,7 +307,7 @@ def coerce(self, other): Otherwise it will attempt to convert ``other`` to the domain of ``self``. If that fails, it will attempt to convert ``self`` to the domain of - ``other``. If both attempts fail, it raises a :class:`TypeError` + ``other``. If both attempts fail, it raises a :exc:`TypeError` to signal failure. EXAMPLES:: @@ -436,19 +436,17 @@ def __pow__(self, exp): Return the ``exp``-th power of ``self``. If ``exp`` is `\infty`, returns the infinite periodic word of base ``self``. - Otherwise, `|w|\cdot exp` must be a non-negative integer. + Otherwise, `|w|\cdot exp` must be a nonnegative integer. INPUT: - - ``exp`` -- an integer, a rational, a float number or plus infinity + - ``exp`` -- integer; a rational, a float number or plus infinity - OUTPUT: - - word -- the ``exp``-th power of ``self`` + OUTPUT: word; the ``exp``-th power of ``self`` EXAMPLES: - You can take non-negative integer powers:: + You can take nonnegative integer powers:: sage: w = Word(range(6)); w word: 012345 @@ -464,7 +462,7 @@ def __pow__(self, exp): ValueError: Power of the word is not defined on the exponent -1: the length of the word (6) times the exponent (-1) must be a positive integer - You can take non-negative rational powers:: + You can take nonnegative rational powers:: sage: w = Word(range(6)); w word: 012345 @@ -525,7 +523,7 @@ def length(self): TESTS:: sage: from sage.combinat.words.word import Word_class - sage: w = Word(iter('abba'*40), length="finite") + sage: w = Word(iter('abba'*40), length='finite') sage: w._len is None True sage: w.length() @@ -554,10 +552,8 @@ def content(self, n=None): - ``n`` -- (optional) an integer specifying the maximal letter in the alphabet - OUTPUT: - - - a list where the `i`-th entry indicates the multiplicity - of the `i`-th letter in the alphabet in ``self`` + OUTPUT: list where the `i`-th entry indicates the multiplicity + of the `i`-th letter in the alphabet in ``self`` EXAMPLES:: @@ -643,11 +639,9 @@ def schuetzenberger_involution(self, n=None): INPUT: - ``self`` -- a word - - ``n`` -- an integer specifying the maximal letter in the alphabet (optional) + - ``n`` -- integer specifying the maximal letter in the alphabet (optional) - OUTPUT: - - a word, the Schützenberger involution of ``self`` + OUTPUT: a word, the Schützenberger involution of ``self`` EXAMPLES:: @@ -842,7 +836,7 @@ def to_integer_word(self): sage: w = Word('abbabaab') sage: w.to_integer_word() word: 01101001 - sage: w = Word(iter("cacao"), length="finite") + sage: w = Word(iter("cacao"), length='finite') sage: w.to_integer_word() word: 10102 @@ -864,7 +858,7 @@ def to_integer_list(self): sage: w = Word('abbabaab') sage: w.to_integer_list() [0, 1, 1, 0, 1, 0, 0, 1] - sage: w = Word(iter("cacao"), length="finite") + sage: w = Word(iter("cacao"), length='finite') sage: w.to_integer_list() [1, 0, 1, 0, 2] sage: w = Words([3,2,1])([2,3,3,1]) @@ -946,7 +940,7 @@ def has_suffix(self, other): """ Test whether ``self`` has ``other`` as a suffix. - .. note:: + .. NOTE:: Some word datatype classes, like :class:`WordDatatype_str`, override this method. @@ -955,9 +949,7 @@ def has_suffix(self, other): - ``other`` -- a word, or data describing a word - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -980,7 +972,6 @@ def has_suffix(self, other): False sage: u.has_suffix([0,1,0,1,0]) True - """ from sage.combinat.words.word import Word w = Word(other) @@ -1034,9 +1025,7 @@ def has_prefix(self, other): - ``other`` -- a word, or data describing a word - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -1059,8 +1048,6 @@ def has_prefix(self, other): False sage: u.has_prefix([0,1,1,0,1]) True - - """ from sage.combinat.words.word import Word w = Word(other) @@ -1200,8 +1187,8 @@ def number_of_factors(self, n=None, algorithm='suffix tree'): INPUT: - - ``n`` -- an integer, or ``None``. - - ``algorithm`` -- string (default: ``'suffix tree'``), takes the + - ``n`` -- integer or ``None`` + - ``algorithm`` -- string (default: ``'suffix tree'``); takes the following values: - ``'suffix tree'`` -- construct and use the suffix tree of the word @@ -1269,7 +1256,7 @@ def factor_iterator(self, n=None): INPUT: - - ``n`` -- an integer, or ``None``. + - ``n`` -- integer or ``None`` OUTPUT: @@ -1340,7 +1327,7 @@ def factor_complexity(self, n): INPUT: - - ``n`` -- the length of the factors. + - ``n`` -- the length of the factors EXAMPLES:: @@ -1362,7 +1349,7 @@ def factor_set(self, n=None, algorithm='suffix tree'): INPUT: - - ``n`` -- an integer or ``None`` (default: ``None``). + - ``n`` -- integer or ``None`` (default: ``None``) - ``algorithm`` -- string (default: ``'suffix tree'``), takes the following values: @@ -1453,11 +1440,9 @@ def topological_entropy(self, n): INPUT: - ``self`` -- a word defined over a finite alphabet - - ``n`` -- positive integer - - OUTPUT: + - ``n`` -- positive integer - real number (a symbolic expression) + OUTPUT: real number (a symbolic expression) EXAMPLES:: @@ -1592,12 +1577,10 @@ def reduced_rauzy_graph(self, n): INPUT: - - ``n`` -- a non-negative integer. Every vertex of a reduced - Rauzy graph of order ``n`` is a factor of length ``n`` of ``self``. - - OUTPUT: + - ``n`` -- nonnegative integer; every vertex of a reduced + Rauzy graph of order ``n`` is a factor of length ``n`` of ``self`` - a looped multi-digraph + OUTPUT: a looped multi-digraph DEFINITION: @@ -1609,7 +1592,7 @@ def reduced_rauzy_graph(self, n): where `w` is the unique return word to `p`. In other cases, it is the directed graph defined as followed. Let - `G_n` be the Rauzy graph of order `n` of self. The vertices are the + `G_n` be the Rauzy graph of order `n` of ``self``. The vertices are the vertices of `G_n` that are either special or not prolongable to the right or to the left. For each couple (`u`, `v`) of such vertices and each directed path in `G_n` from `u` to `v` that contains no @@ -1686,7 +1669,6 @@ def reduced_rauzy_graph(self, n): AUTHOR: Julien Leroy (March 2010): initial version - """ from sage.graphs.digraph import DiGraph from copy import copy @@ -1719,8 +1701,8 @@ def left_special_factors_iterator(self, n=None): INPUT: - - ``n`` -- integer (default: ``None``). If ``None``, it returns - an iterator over all left special factors. + - ``n`` -- integer (default: ``None``); if ``None``, it returns + an iterator over all left special factors EXAMPLES:: @@ -1755,12 +1737,10 @@ def left_special_factors(self, n=None): INPUT: - - ``n`` -- integer (default: ``None``). If ``None``, it - returns all left special factors. + - ``n`` -- integer (default: ``None``); if ``None``, it + returns all left special factors - OUTPUT: - - a list of words + OUTPUT: list of words EXAMPLES:: @@ -1786,8 +1766,8 @@ def right_special_factors_iterator(self, n=None): INPUT: - - ``n`` -- integer (default: ``None``). If ``None``, it returns - an iterator over all right special factors. + - ``n`` -- integer (default: ``None``); if ``None``, it returns + an iterator over all right special factors EXAMPLES:: @@ -1822,12 +1802,10 @@ def right_special_factors(self, n=None): INPUT: - - ``n`` -- integer (default: ``None``). If ``None``, it returns - all right special factors. - - OUTPUT: + - ``n`` -- integer (default: ``None``); if ``None``, it returns + all right special factors - a list of words + OUTPUT: list of words EXAMPLES:: @@ -1851,8 +1829,8 @@ def bispecial_factors_iterator(self, n=None): INPUT: - - ``n`` -- integer (default: ``None``). If ``None``, it returns - an iterator over all bispecial factors. + - ``n`` -- integer (default: ``None``); if ``None``, it returns + an iterator over all bispecial factors EXAMPLES:: @@ -1914,12 +1892,10 @@ def bispecial_factors(self, n=None): INPUT: - - ``n`` -- integer (default: ``None``). If ``None``, it returns - all bispecial factors. + - ``n`` -- integer (default: ``None``); if ``None``, it returns + all bispecial factors - OUTPUT: - - a list of words + OUTPUT: list of words EXAMPLES:: @@ -1947,7 +1923,7 @@ def bispecial_factors(self, n=None): def number_of_left_special_factors(self, n): r""" - Return the number of left special factors of length ``n``. + Return the number of left special factors of length `n`. A factor `u` of a word `w` is *left special* if there are two distinct letters `a` and `b` such that `au` and `bu` @@ -1957,9 +1933,7 @@ def number_of_left_special_factors(self, n): - ``n`` -- integer - OUTPUT: - - a non-negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -1988,9 +1962,7 @@ def number_of_right_special_factors(self, n): - ``n`` -- integer - OUTPUT: - - a non-negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -2153,9 +2125,7 @@ def is_conjugate_with(self, other): - ``other`` -- a finite word - OUTPUT: - - bool + OUTPUT: boolean EXAMPLES:: @@ -2272,7 +2242,6 @@ def longest_forward_extension(self, x, y): Traceback (most recent call last): ... ValueError: x and y must be valid positions in self - """ length = self.length() if not (-length <= x < length and -length <= y < length): @@ -2522,14 +2491,12 @@ def lps(self, f=None, l=None): INPUT: - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. - It must be callable on letters as well as words (e.g. ``WordMorphism``). - - ``l`` -- integer (default: ``None``) the length of the longest - palindrome suffix of ````self[:-1]````, if known. - - OUTPUT: + It must be callable on letters as well as words (e.g. ``WordMorphism``) + - ``l`` -- integer (default: ``None``); the length of the longest + palindrome suffix of ``self[:-1]``, if known - word -- If ``f`` is ``None``, the longest palindromic suffix of ``self``; - otherwise, the longest ``f``-palindromic suffix of ``self``. + OUTPUT: word; if ``f`` is ``None``, the longest palindromic suffix of + ``self``. Otherwise, the longest ``f``-palindromic suffix of ``self``. EXAMPLES:: @@ -2706,9 +2673,7 @@ def lacunas(self, f=None): default value corresponds to usual palindromes, i.e., ``f`` equal to the identity. - OUTPUT: - - a list -- list of all the lacunas of self + OUTPUT: list of all the lacunas of self EXAMPLES:: @@ -2770,19 +2735,17 @@ def length_maximal_palindrome(self, j, m=None, f=None): INPUT: - - ``j`` -- rational, position of the symmetry axis of the palindrome. + - ``j`` -- rational; position of the symmetry axis of the palindrome. Must return an integer when doubled. It is an integer when the center of the palindrome is a letter. - - ``m`` -- integer (default: ``None``), minimal length of palindrome, if known. + - ``m`` -- integer (default: ``None``); minimal length of palindrome, if known. The parity of ``m`` can't be the same as the parity of ``2j``. - - ``f`` -- involution (default: ``None``), on the alphabet. It must be - callable on letters as well as words (e.g. ``WordMorphism``). - - OUTPUT: + - ``f`` -- involution (default: ``None``) on the alphabet; it must be + callable on letters as well as words (e.g. ``WordMorphism``) - length of the longest ``f``-palindrome centered at position ``j`` + OUTPUT: length of the longest ``f``-palindrome centered at position ``j`` EXAMPLES:: @@ -2829,7 +2792,6 @@ def length_maximal_palindrome(self, j, m=None, f=None): ... ValueError: (2*j-m-1)/2(=15/2) must be an integer, i.e., 2*j(=19) and m(=3) can't have the same parity - """ # Ensure `f` is an involutory word morphism if f is not None: @@ -2874,13 +2836,12 @@ def lengths_maximal_palindromes(self, f=None): INPUT: - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. It must - be callable on letters as well as words (e.g. ``WordMorphism``). - - OUTPUT: + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. + ``WordMorphism``) - a list -- The length of the maximal palindrome (or ``f``-palindrome) - with a given symmetry axis (letter or space between two letters). + OUTPUT: list; the length of the maximal palindrome (or ``f``-palindrome) + with a given symmetry axis (letter or space between two letters) EXAMPLES:: @@ -2938,13 +2899,12 @@ def lps_lengths(self, f=None): INPUT: - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. It must - be callable on letters as well as words (e.g. ``WordMorphism``). - - OUTPUT: + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. + It must be callable on letters as well as words (e.g. + ``WordMorphism``). - a list -- The length of the longest palindromic (or ``f``-palindromic) - suffix of each prefix of ``self``. + OUTPUT: list; the length of the longest palindromic (or + ``f``-palindromic) suffix of each prefix of ``self`` EXAMPLES:: @@ -2979,13 +2939,12 @@ def palindromes(self, f=None): INPUT: - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. It must - be callable on letters as well as words (e.g. ``WordMorphism``). - - OUTPUT: + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. ``WordMorphism``). - a set -- If ``f`` is ``None``, the set of all palindromic factors of ``self``; - otherwise, the set of all ``f``-palindromic factors of ``self``. + OUTPUT: a set -- If ``f`` is ``None``, the set of all palindromic + factors of ``self``; otherwise, the set of all ``f``-palindromic + factors of ``self`` EXAMPLES:: @@ -3012,7 +2971,7 @@ def palindromic_complexity(self, n): INPUT: - - ``n`` -- the length of the factors. + - ``n`` -- the length of the factors EXAMPLES:: @@ -3032,10 +2991,6 @@ def palindrome_prefixes(self): r""" Return a list of all palindrome prefixes of ``self``. - OUTPUT: - - a list -- A list of all palindrome prefixes of ``self``. - EXAMPLES:: sage: w = Word('abaaba') @@ -3176,8 +3131,8 @@ def is_full(self, f=None): INPUT: - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. It must - be callable on letters as well as words (e.g. ``WordMorphism``). + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. ``WordMorphism``) OUTPUT: @@ -3243,8 +3198,8 @@ def palindromic_closure(self, side='right', f=None): - ``side`` -- ``'right'`` or ``'left'`` (default: ``'right'``) the direction of the closure - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. - It must be callable on letters as well as words (e.g. ``WordMorphism``). + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. ``WordMorphism``) OUTPUT: @@ -3319,8 +3274,8 @@ def is_symmetric(self, f=None): INPUT: - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. It must - be callable on letters as well as words (e.g. ``WordMorphism``). + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. ``WordMorphism``) EXAMPLES:: @@ -3420,9 +3375,7 @@ def order(self): Let `p(w)` be the period of a word `w`. The positive rational number `|w|/p(w)` is the *order* of `w`. See Chapter 8 of [Lot2002]_. - OUTPUT: - - rational -- the order + OUTPUT: rational; the order EXAMPLES:: @@ -3583,9 +3536,7 @@ def exponent(self): r""" Return the exponent of ``self``. - OUTPUT: - - integer -- the exponent + OUTPUT: integer; the exponent EXAMPLES:: @@ -3602,7 +3553,7 @@ def exponent(self): def has_period(self, p): r""" - Return ``True`` if ``self`` has the period ``p``, + Return ``True`` if ``self`` has the period `p`, ``False`` otherwise. .. NOTE:: @@ -3612,8 +3563,8 @@ def has_period(self, p): INPUT: - - ``p`` -- an integer to check if it is a period - of ``self``. + - ``p`` -- integer to check if it is a period + of ``self`` EXAMPLES:: @@ -3649,13 +3600,11 @@ def periods(self, divide_length=False): INPUT: - - ``divide_length`` -- boolean (default: ``False``). - When set to ``True``, then only periods that divide - the length of ``self`` are considered. - - OUTPUT: + - ``divide_length`` -- boolean (default: ``False``); + when set to ``True``, then only periods that divide + the length of ``self`` are considered - a list of positive integers + OUTPUT: list of positive integers EXAMPLES:: @@ -3814,9 +3763,7 @@ def subword_complementaries(self, other): - ``other`` -- finite word - OUTPUT: - - - list of all the complementary subwords of ``self`` in ``other``. + OUTPUT: list of all the complementary subwords of ``self`` in ``other`` EXAMPLES:: @@ -3831,7 +3778,6 @@ def subword_complementaries(self, other): sage: Word('a').subword_complementaries(Word('a')) [word: ] - """ ls = self.length() @@ -3949,9 +3895,7 @@ def lyndon_factorization(self): i.e., `w = l_1\cdots l_n` where each `l_i` is a Lyndon word and `l_1\geq \cdots \geq l_n`. See for instance [Duv1983]_. - OUTPUT: - - the list `[l_1, \ldots, l_n]` of factors obtained + OUTPUT: the list `[l_1, \ldots, l_n]` of factors obtained EXAMPLES:: @@ -4013,7 +3957,7 @@ def lyndon_factorization(self): def inversions(self): r""" Return a list of the inversions of ``self``. An inversion is a pair - `(i,j)` of non-negative integers `i < j` such that ``self[i] > self[j]``. + `(i,j)` of nonnegative integers `i < j` such that ``self[i] > self[j]``. EXAMPLES:: @@ -4046,8 +3990,8 @@ def degree(self, weights=None): INPUT: - - ``weights`` -- a list or a tuple, or a dictionary keyed by the - letters occurring in ``self``. + - ``weights`` -- list or tuple, or dictionary keyed by the + letters occurring in ``self`` EXAMPLES:: @@ -4284,22 +4228,20 @@ def find(self, sub, start=0, end=None): r""" Return the index of the first occurrence of ``sub`` in ``self``, such that ``sub`` is contained within ``self[start:end]``. - Return ``-1`` on failure. + Return `-1` on failure. INPUT: - - ``sub`` -- string, list, tuple or word to search for. + - ``sub`` -- string, list, tuple or word to search for - - ``start`` -- non-negative integer (default: ``0``) specifying - the position from which to start the search. + - ``start`` -- nonnegative integer (default: `0`) specifying + the position from which to start the search - - ``end`` -- non-negative integer (default: ``None``) specifying + - ``end`` -- nonnegative integer (default: ``None``); specifying the position at which the search must stop. If ``None``, then the search is performed up to the end of the string. - OUTPUT: - - a non-negative integer or ``-1`` + OUTPUT: nonnegative integer or `-1` EXAMPLES:: @@ -4339,7 +4281,7 @@ def find(self, sub, start=0, end=None): Check that :issue:`12804` is fixed:: - sage: w = Word(iter("ababab"), length="finite") + sage: w = Word(iter("ababab"), length='finite') sage: w.find("ab") 0 sage: w.find("ab", start=1) @@ -4351,7 +4293,6 @@ def find(self, sub, start=0, end=None): sage: w = Words('ab')(tuple('babaabaaab')) sage: w.find('abc') -1 - """ if not isinstance(sub, FiniteWord_class): try: @@ -4369,18 +4310,16 @@ def rfind(self, sub, start=0, end=None): INPUT: - - ``sub`` -- string, list, tuple or word to search for. + - ``sub`` -- string, list, tuple or word to search for - - ``start`` -- non-negative integer (default: ``0``) specifying - the position at which the search must stop. + - ``start`` -- nonnegative integer (default: `0`); specifying + the position at which the search must stop - - ``end`` -- non-negative integer (default: ``None``) specifying + - ``end`` -- nonnegative integer (default: ``None``); specifying the position from which to start the search. If ``None``, then the search is performed up to the end of the string. - OUTPUT: - - a non-negative integer or ``-1`` + OUTPUT: nonnegative integer or `-1` EXAMPLES:: @@ -4420,7 +4359,7 @@ def rfind(self, sub, start=0, end=None): Check that :issue:`12804` is fixed:: - sage: w = Word(iter("abab"), length="finite") + sage: w = Word(iter("abab"), length='finite') sage: w.rfind("ab") 2 sage: w.rfind("ab", end=3) @@ -4719,9 +4658,7 @@ def number_of_letter_occurrences(self, letter): - ``letter`` -- a letter - OUTPUT: - - - integer + OUTPUT: integer EXAMPLES:: @@ -4754,7 +4691,6 @@ def number_of_letter_occurrences(self, letter): .. SEEALSO:: :meth:`sage.combinat.words.finite_word.FiniteWord_class.number_of_factor_occurrences` - """ return Integer(sum(1 for a in self if a == letter)) count = number_of_letter_occurrences @@ -4767,9 +4703,7 @@ def _return_words_list(self, fact): - ``fact`` -- a non-empty finite word - OUTPUT: - - a Python list of finite words + OUTPUT: a Python list of finite words TESTS:: @@ -4790,9 +4724,7 @@ def return_words(self, fact): - ``fact`` -- a non-empty finite word - OUTPUT: - - a Python set of finite words + OUTPUT: a Python set of finite words EXAMPLES:: @@ -4823,9 +4755,7 @@ def complete_return_words(self, fact): - ``fact`` -- a non-empty finite word - OUTPUT: - - a Python set of finite words + OUTPUT: a Python set of finite words EXAMPLES:: @@ -5035,19 +4965,16 @@ def overlap_partition(self, other, delay=0, p=None, involution=None): INPUT: - - ``other`` -- word on the same alphabet as ``self`` - - ``delay`` -- integer (default: ``0``) - - ``p`` -- disjoint sets data structure (default: ``None``), - a partition of the alphabet into disjoint sets to start with. - If ``None``, each letter start in distinct equivalence classes. - - ``involution`` -- callable (default: ``None``), an - involution on the alphabet. If ``involution`` is not ``None``, the relation - `R_{u,v,d} \cup R_{involution(u),involution(v),d}` is considered. - - OUTPUT: - - a disjoint set data structure + - ``other`` -- word on the same alphabet as ``self`` + - ``delay`` -- integer (default: `0`) + - ``p`` -- disjoint sets data structure (default: ``None``), + a partition of the alphabet into disjoint sets to start with. + If ``None``, each letter start in distinct equivalence classes. + - ``involution`` -- callable (default: ``None``); an + involution on the alphabet. If ``involution`` is not ``None``, the relation + `R_{u,v,d} \cup R_{involution(u),involution(v),d}` is considered. + OUTPUT: a disjoint set data structure EXAMPLES:: @@ -5515,12 +5442,10 @@ def iterated_left_palindromic_closure(self, f=None): INPUT: - - ``f`` -- involution (default: ``None``) on the alphabet of ``self``. - It must be callable on letters as well as words (e.g. ``WordMorphism``). - - OUTPUT: + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. ``WordMorphism``) - word -- the left iterated ``f``-palindromic closure of ``self``. + OUTPUT: word; the left iterated ``f``-palindromic closure of ``self`` EXAMPLES:: @@ -5564,9 +5489,7 @@ def balance(self): for all letters `x` in the alphabet of `w`. A `1`-balanced word is simply said to be balanced. See Chapter 2 of [Lot2002]_. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -5637,11 +5560,7 @@ def is_balanced(self, q=1): INPUT: - - ``q`` -- integer (default: ``1``), the balance level - - OUTPUT: - - boolean -- the result + - ``q`` -- integer (default: `1`); the balance level EXAMPLES:: @@ -5697,9 +5616,7 @@ def abelian_vectors(self, n): The vectors are defined w.r.t. the order of the alphabet of the parent. - OUTPUT: - - a set of tuples + OUTPUT: a set of tuples EXAMPLES:: @@ -5755,7 +5672,6 @@ def abelian_vectors(self, n): 1 sage: w.abelian_complexity(4) 0 - """ alphabet = self.parent().alphabet() size = alphabet.cardinality() @@ -5793,7 +5709,6 @@ def abelian_complexity(self, n): sage: w = words.ThueMorseWord()[:100] sage: [w.abelian_complexity(i) for i in range(20)] [1, 2, 3, 2, 3, 2, 3, 2, 3, 2, 3, 2, 3, 2, 3, 2, 3, 2, 3, 2] - """ return len(self.abelian_vectors(n)) @@ -5815,9 +5730,7 @@ def sturmian_desubstitute_as_possible(self): a factor of a Sturmian word if, and only if, the result is the empty word. - OUTPUT: - - a finite word defined on a two-letter alphabet + OUTPUT: a finite word defined on a two-letter alphabet EXAMPLES:: @@ -5892,7 +5805,7 @@ def sturmian_desubstitute_as_possible(self): raise TypeError('your word must be defined on a binary alphabet or use at most two different letters') elif len(alphabet) < 2: return W() - word_from_letter = {l: W([l], datatype="list", check=False) for l in alphabet} + word_from_letter = {l: W([l], datatype='list', check=False) for l in alphabet} is_prefix = True current_run_length = 0 prefix_length = 0 @@ -5959,9 +5872,7 @@ def is_sturmian_factor(self): advantage over the ``is_balanced`` method is that this one runs in linear time whereas ``is_balanced`` runs in quadratic time. - OUTPUT: - - boolean -- the result + OUTPUT: boolean EXAMPLES:: @@ -6024,9 +5935,7 @@ def is_tangent(self): This method runs in linear time. - OUTPUT: - - boolean -- the result + OUTPUT: boolean EXAMPLES:: @@ -6167,9 +6076,7 @@ def abelian_vector(self): - ``self`` -- word having a parent on a finite alphabet - OUTPUT: - - a list + OUTPUT: list EXAMPLES:: @@ -6249,7 +6156,7 @@ def shuffle(self, other, overlap=0): ``self.length()+other.length()`` that have both ``self`` and ``other`` as subwords. - If ``overlap`` is non-zero, then the combinatorial class representing + If ``overlap`` is nonzero, then the combinatorial class representing the shuffle product with overlaps is returned. The calculation of the shift in each overlap is done relative to the order of the alphabet. For example, `a` shifted by `a` is `b` in the alphabet @@ -6257,12 +6164,10 @@ def shuffle(self, other, overlap=0): INPUT: - - ``other`` -- finite word - - ``overlap`` -- (default: ``0``) integer or ``True`` - - OUTPUT: + - ``other`` -- finite word + - ``overlap`` -- (default: ``0``) integer or ``True`` - combinatorial class of shuffle product of ``self`` and ``other`` + OUTPUT: combinatorial class of shuffle product of ``self`` and ``other`` EXAMPLES:: @@ -6310,12 +6215,10 @@ def shifted_shuffle(self, other, shift=None): INPUT: - ``other`` -- finite word over the integers - - ``shift`` -- integer or ``None`` (default: ``None``) added to each letter of + - ``shift`` -- integer or ``None`` (default: ``None``); added to each letter of ``other``. When ``shift`` is ``None``, it is replaced by ``self.length()`` - OUTPUT: - - combinatorial class of shifted shuffle products of ``self`` and ``other`` + OUTPUT: combinatorial class of shifted shuffle products of ``self`` and ``other`` EXAMPLES:: @@ -6350,8 +6253,8 @@ def shifted_shuffle(self, other, shift=None): def delta_inv(self, W=None, s=None): r""" Lift ``self`` via the delta operator to obtain a word containing the - letters in alphabet (default is ``[0, 1]``). The letters used in the - construction start with ``s`` (default is ``alphabet[0]``) and cycle + letters in alphabet (default: ``[0, 1]``). The letters used in the + construction start with ``s`` (default: ``alphabet[0]``) and cycle through alphabet. INPUT: @@ -6406,7 +6309,6 @@ def delta(self): word: sage: Word('aabbabaa').delta() word: 22112 - """ if self.is_empty(): return Words()([]) @@ -6524,9 +6426,7 @@ def phi(self): the word obtained by taking the first letter of the words obtained by iterating delta on ``self``. - OUTPUT: - - a word -- the result of the phi function + OUTPUT: a word -- the result of the phi function EXAMPLES:: @@ -6566,9 +6466,7 @@ def phi_inv(self, W=None): - ``self`` -- a word over the integers - ``W`` -- a parent object of words defined over integers - OUTPUT: - - a word -- the inverse of the phi function + OUTPUT: a word -- the inverse of the phi function EXAMPLES:: @@ -6618,9 +6516,7 @@ def is_smooth_prefix(self): - ``self`` -- must be a word over the integers to get something other than ``False`` - OUTPUT: - - boolean -- whether ``self`` is a smooth prefix or not + OUTPUT: boolean; whether ``self`` is a smooth prefix or not EXAMPLES:: @@ -6681,9 +6577,7 @@ def standard_factorization(self): - ``self`` -- finite word of length greater than `1` - OUTPUT: - - `2`-tuple `(u, v)` + OUTPUT: `2`-tuple `(u, v)` EXAMPLES:: @@ -6812,11 +6706,9 @@ def colored_vector(self, x=0, y=0, width='default', height=1, cmap='hsv', thickn - ``thickness`` -- (default: ``1``) thickness of the contour - ``cmap`` -- (default: ``'hsv'``) color map; for available color map names type: ``import matplotlib.cm; list(matplotlib.cm.datad)`` - - ``label`` -- string (default: ``None``) a label to add on the colored vector - - OUTPUT: + - ``label`` -- string (default: ``None``); a label to add on the colored vector - Graphics + OUTPUT: Graphics EXAMPLES:: @@ -6981,7 +6873,7 @@ def is_square_free(self): def squares(self): r""" - Returns a set of all distinct squares of ``self``. + Return a set of all distinct squares of ``self``. EXAMPLES:: @@ -7101,10 +6993,8 @@ def is_christoffel(self): - ``self`` -- word - OUTPUT: - - boolean -- ``True`` if ``self`` is a Christoffel word, - ``False`` otherwise. + OUTPUT: boolean; ``True`` if ``self`` is a Christoffel word, + ``False`` otherwise EXAMPLES:: diff --git a/src/sage/combinat/words/infinite_word.py b/src/sage/combinat/words/infinite_word.py index 8baae7c1c3c..0fab1f18891 100644 --- a/src/sage/combinat/words/infinite_word.py +++ b/src/sage/combinat/words/infinite_word.py @@ -81,13 +81,13 @@ class InfiniteWord_class(Word_class): def _repr_(self): r""" - Returns a string representation of self. + Return a string representation of ``self``. TESTS:: - sage: Word(iter([1,2,3]), length="unknown")._repr_() + sage: Word(iter([1,2,3]), length='unknown')._repr_() 'word: 123' - sage: Word(range(100), length="unknown")._repr_() + sage: Word(range(100), length='unknown')._repr_() 'word: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,...' sage: Word(lambda x:x%3)._repr_() 'word: 0120120120120120120120120120120120120120...' @@ -99,7 +99,7 @@ def _repr_(self): def length(self): r""" - Returns the length of self. + Return the length of ``self``. EXAMPLES:: diff --git a/src/sage/combinat/words/lyndon_word.py b/src/sage/combinat/words/lyndon_word.py index fa58a3ffa03..0f4e4111f37 100644 --- a/src/sage/combinat/words/lyndon_word.py +++ b/src/sage/combinat/words/lyndon_word.py @@ -38,16 +38,14 @@ def LyndonWords(e=None, k=None): or - - ``e`` -- integer, size of alphabet - - ``k`` -- integer, length of the words + - ``e`` -- integer; size of alphabet + - ``k`` -- integer; length of the words or - ``e`` -- a composition - OUTPUT: - - A combinatorial class of Lyndon words. + OUTPUT: a combinatorial class of Lyndon words EXAMPLES:: @@ -83,9 +81,9 @@ def LyndonWords(e=None, k=None): elif isinstance(e, (int, Integer)): if e > 0: if not isinstance(k, (int, Integer)): - raise TypeError("k must be a non-negative integer") + raise TypeError("k must be a nonnegative integer") if k < 0: - raise TypeError("k must be a non-negative integer") + raise TypeError("k must be a nonnegative integer") return LyndonWords_nk(Integer(e), Integer(k)) elif e in Compositions(): return LyndonWords_evaluation(Composition(e)) @@ -100,12 +98,10 @@ def LyndonWord(data, check=True): INPUT: - ``data`` -- list - - ``check`` -- bool (default: ``True``) if ``True``, - check that the input data represents a Lyndon word. - - OUTPUT: + - ``check`` -- boolean (default: ``True``); if ``True``, + check that the input data represents a Lyndon word - A Lyndon word. + OUTPUT: a Lyndon word EXAMPLES:: diff --git a/src/sage/combinat/words/morphic.py b/src/sage/combinat/words/morphic.py index 3699f08c524..160f4e2243a 100644 --- a/src/sage/combinat/words/morphic.py +++ b/src/sage/combinat/words/morphic.py @@ -18,7 +18,7 @@ sage: w.length() +Infinity -Computing the n-th letter of a fixed point is fast as it is using the +Computing the `n`-th letter of a fixed point is fast as it is using the abstract numeration system associated to the morphism and the starting letter, see chapter 3 of the book [BR2010b]_:: @@ -45,7 +45,7 @@ def __init__(self, parent, morphism, letter, coding=None, length=Infinity): - ``parent`` -- a parent - ``morphism`` -- a word morphism - ``letter`` -- a starting letter - - ``coding`` -- dict (default: ``None``), if ``None`` + - ``coding`` -- dictionary (default: ``None``); if ``None`` the identity map is used for the coding - ``length`` -- integer or ``'finite'`` or ``Infinity`` or ``'unknown'`` (default: ``Infinity``) the length of the word @@ -106,7 +106,6 @@ def __init__(self, parent, morphism, letter, coding=None, length=Infinity): word: dddcdddcba sage: list(w[10000:10010]) == L # needs sage.modules True - """ self._parent = parent # self._func = callable @@ -153,7 +152,6 @@ def __reduce__(self): 'a', {'a': 'a', 'b': 'b'}, 2)) - """ return self.__class__, (self._parent, self._morphism, self._letter, self._coding, self._len) @@ -167,9 +165,7 @@ def representation(self, n): - ``n`` -- nonnegative integer - OUTPUT: - - list + OUTPUT: list EXAMPLES:: @@ -243,11 +239,9 @@ def _func(self, key): INPUT: - ``self`` -- a fixed point of a morphism - - ``key`` -- an integer, the position + - ``key`` -- integer; the position - OUTPUT: - - - a letter + OUTPUT: a letter EXAMPLES:: @@ -271,7 +265,6 @@ def _func(self, key): sage: w = WordDatatype_morphic(W, m, 'a') sage: w._func(5) # needs sage.modules 'a' - """ letter = self._letter for a in self.representation(key): @@ -291,13 +284,11 @@ def __iter__(self): INPUT: - ``self`` -- an endomorphism, must be prolongable on - letter + letter - ``letter`` -- a letter in the domain of ``self`` - OUTPUT: - - - iterator of the fixed point + OUTPUT: iterator of the fixed point EXAMPLES:: diff --git a/src/sage/combinat/words/morphism.py b/src/sage/combinat/words/morphism.py index 871fa118c42..7ff3b53451c 100644 --- a/src/sage/combinat/words/morphism.py +++ b/src/sage/combinat/words/morphism.py @@ -112,9 +112,9 @@ def get_cycles(f, domain): INPUT: - - ``f`` -- function. + - ``f`` -- function - - ``domain`` -- iterable, a subdomain of the domain of definition of ``f``. + - ``domain`` -- iterable, a subdomain of the domain of definition of ``f`` EXAMPLES:: @@ -228,11 +228,11 @@ def get_iterator(self, i): class WordMorphism(SageObject): r""" - WordMorphism class + WordMorphism class. INPUT: - - ``data`` -- dict or str or an instance of WordMorphism, the map + - ``data`` -- dictionary or string or an instance of WordMorphism, the map giving the image of letters - ``domain`` -- (optional:``None``) set of words over a given alphabet. If ``None``, the domain alphabet is computed from ``data`` @@ -565,7 +565,6 @@ def __ne__(self, other): True sage: s != s.reversal() False - """ return not self == other @@ -628,17 +627,15 @@ def __str__(self) -> str: def __call__(self, w, order=1): r""" - Return the image of ``w`` under self to the given order. + Return the image of ``w`` under ``self`` to the given order. INPUT: - - ``w`` -- word or sequence in the domain of self - - - ``order`` -- integer or plus ``Infinity`` (default: 1) + - ``w`` -- word or sequence in the domain of self - OUTPUT: + - ``order`` -- integer or plus ``Infinity`` (default: 1) - - ``word`` -- order-th iterated image under self of ``w`` + OUTPUT: ``word`` -- ``order``-th iterated image under ``self`` of ``w`` EXAMPLES: @@ -699,16 +696,16 @@ def __call__(self, w, order=1): ... ValueError: 0 not in alphabet - The order must be a non-negative integer or plus Infinity:: + The order must be a nonnegative integer or plus Infinity:: sage: tm('a', -1) Traceback (most recent call last): ... - TypeError: order (-1) must be a non-negative integer or plus Infinity + TypeError: order (-1) must be a nonnegative integer or plus Infinity sage: tm('a', 6.7) Traceback (most recent call last): ... - TypeError: order (6.7...) must be a non-negative integer or plus Infinity + TypeError: order (6.7...) must be a nonnegative integer or plus Infinity Only the first letter is considered for infinitely iterated image of a word under a morphism:: @@ -716,7 +713,7 @@ def __call__(self, w, order=1): sage: tm('aba',oo) word: abbabaabbaababbabaababbaabbabaabbaababba... - The morphism self must be prolongable on the given letter for infinitely + The morphism ``self`` must be prolongable on the given letter for infinitely iterated image:: sage: m = WordMorphism('a->ba,b->ab') @@ -761,7 +758,7 @@ def __call__(self, w, order=1): sage: w == loads(dumps(w)) True sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".sobj") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.sobj') as f: ....: save(w, filename=f.name) """ if order == 1: @@ -813,7 +810,7 @@ def __call__(self, w, order=1): return self._domain(w) else: - raise TypeError("order (%s) must be a non-negative integer or plus Infinity" % order) + raise TypeError("order (%s) must be a nonnegative integer or plus Infinity" % order) def latex_layout(self, layout=None): r""" @@ -821,13 +818,13 @@ def latex_layout(self, layout=None): INPUT: - - ``layout`` -- string (default: ``None``), can take one of the + - ``layout`` -- string (default: ``None``); can take one of the following values: - - ``None`` -- Returns the actual latex layout. By default, the + - ``None`` -- returns the actual latex layout; by default, the layout is ``'array'`` - - ``'oneliner'`` -- Set the layout to ``'oneliner'`` - - ``'array'`` -- Set the layout to ``'array'`` + - ``'oneliner'`` -- set the layout to ``'oneliner'`` + - ``'array'`` -- set the layout to ``'array'`` EXAMPLES:: @@ -956,7 +953,7 @@ def __pow__(self, exp): INPUT: - - ``exp`` -- a positive integer + - ``exp`` -- positive integer EXAMPLES:: @@ -1018,11 +1015,9 @@ def extend_by(self, other): INPUT: - - ``other`` -- a WordMorphism. + - ``other`` -- a WordMorphism - OUTPUT: - - WordMorphism + OUTPUT: WordMorphism EXAMPLES:: @@ -1065,9 +1060,7 @@ def restrict_domain(self, alphabet): - ``alphabet`` -- an iterable - OUTPUT: - - WordMorphism + OUTPUT: WordMorphism EXAMPLES:: @@ -1241,9 +1234,7 @@ def image(self, letter): - ``letter`` -- a letter in the domain alphabet - OUTPUT: - - word + OUTPUT: word .. NOTE:: @@ -1396,11 +1387,9 @@ def partition_of_domain_alphabet(self): INPUT: - - ``self`` -- An involution. + - ``self`` -- an involution - OUTPUT: - - A tuple of three sets + OUTPUT: a tuple of three sets EXAMPLES:: @@ -1481,7 +1470,7 @@ def pisot_eigenvector_right(self): to the largest eigenvalue (in absolute value). Unicity of the result is guaranteed when the multiplicity of the - largest eigenvalue is one, for example when self is a Pisot + largest eigenvalue is one, for example when ``self`` is a Pisot irreductible substitution. A substitution is Pisot irreducible if the characteristic @@ -1490,7 +1479,7 @@ def pisot_eigenvector_right(self): INPUT: - - ``self`` -- a Pisot irreducible substitution. + - ``self`` -- a Pisot irreducible substitution EXAMPLES:: @@ -1511,7 +1500,7 @@ def pisot_eigenvector_left(self): to the largest eigenvalue (in absolute value). Unicity of the result is guaranteed when the multiplicity of the - largest eigenvalue is one, for example when self is a Pisot + largest eigenvalue is one, for example when ``self`` is a Pisot irreductible substitution. A substitution is Pisot irreducible if the characteristic @@ -1520,7 +1509,7 @@ def pisot_eigenvector_left(self): INPUT: - - ``self`` -- a Pisot irreducible substitution. + - ``self`` -- a Pisot irreducible substitution EXAMPLES:: @@ -1556,7 +1545,6 @@ def _check_primitive(self): WordMorphism: 2->456, 3->418 sage: WordMorphism({2:[4,5,6],3:[4,1,8]})._check_primitive() False - """ dom_alphabet = set(self.domain().alphabet()) @@ -1648,9 +1636,7 @@ def is_prolongable(self, letter): - ``self`` -- its codomain must be an instance of Words - ``letter`` -- a letter in the domain alphabet - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -1705,7 +1691,7 @@ def is_uniform(self, k=None): INPUT: - - ``k`` -- a positive integer or ``None``. If set to a positive integer, + - ``k`` -- positive integer or ``None``. If set to a positive integer, then the function return ``True`` if ``self`` is `k`-uniform. If set to ``None``, then the function return ``True`` if ``self`` is uniform. @@ -1747,15 +1733,13 @@ def fixed_point(self, letter): INPUT: - - ``self`` -- an endomorphism (or more generally a self-composable - morphism), must be prolongable on ``letter`` - - - ``letter`` -- in the domain of ``self``, the first letter - of the fixed point. + - ``self`` -- an endomorphism (or more generally a self-composable + morphism), must be prolongable on ``letter`` - OUTPUT: + - ``letter`` -- in the domain of ``self``, the first letter + of the fixed point - - ``word`` -- the fixed point of ``self`` beginning with ``letter``. + OUTPUT: ``word`` -- the fixed point of ``self`` beginning with ``letter`` EXAMPLES:: @@ -1887,7 +1871,6 @@ def fixed_points(self): sage: s = WordMorphism(s) sage: (s^2).fixed_points() [] - """ return [self.fixed_point(letter=letter) for letter in self.domain().alphabet() @@ -1895,7 +1878,7 @@ def fixed_points(self): def periodic_point(self, letter): r""" - Return the periodic point of self that starts with ``letter``. + Return the periodic point of ``self`` that starts with ``letter``. EXAMPLES:: @@ -2008,7 +1991,7 @@ def _language_naive(self, n, u): INPUT: - - ``n`` -- non-negative integer; length of the words in the language + - ``n`` -- nonnegative integer; length of the words in the language - ``u`` -- a word used as a seed @@ -2065,11 +2048,11 @@ def language(self, n, u=None): Given a non-erasing substitution `s` and a word `u` the DOL-language generated by `s` and `u` is the union of the factors of `s^n(u)` where - `n` is a non-negative integer. + `n` is a nonnegative integer. INPUT: - - ``n`` -- non-negative integer; length of the words in the language + - ``n`` -- nonnegative integer; length of the words in the language - ``u`` -- a word or ``None`` (default: ``None``); if set to ``None`` some letter of the alphabet is used @@ -2340,8 +2323,8 @@ def is_in_classP(self, f=None): INPUT: - - ``f`` -- involution (default: None) on the alphabet of ``self``. - It must be callable on letters as well as words (e.g. WordMorphism). + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. WordMorphism) REFERENCES: @@ -2418,8 +2401,8 @@ def has_conjugate_in_classP(self, f=None): INPUT: - - ``f`` -- involution (default: None) on the alphabet of ``self``. - It must be callable on letters as well as words (e.g. WordMorphism). + - ``f`` -- involution (default: ``None``) on the alphabet of ``self``; + it must be callable on letters as well as words (e.g. WordMorphism) REFERENCES: @@ -2448,7 +2431,7 @@ def has_conjugate_in_classP(self, f=None): def dual_map(self, k=1): r""" - Return the dual map `E_k^*` of self (see [1]). + Return the dual map `E_k^*` of ``self`` (see [1]). .. NOTE:: @@ -2460,9 +2443,7 @@ def dual_map(self, k=1): ``1, 2, \ldots, d`` - ``k`` -- integer (default: 1) - OUTPUT: - - an instance of E1Star - the dual map + OUTPUT: an instance of E1Star - the dual map EXAMPLES:: @@ -2507,9 +2488,9 @@ def rauzy_fractal_projection(self, eig=None, prec=53): but for substitutions with more than 3 letters other interesting choices are sometimes possible. - - ``prec`` -- integer (default: ``53``). - The number of bits used in the floating point representations - of the coordinates. + - ``prec`` -- integer (default: 53); + the number of bits used in the floating point representations + of the coordinates OUTPUT: @@ -2611,12 +2592,10 @@ def rauzy_fractal_points(self, n=None, exchange=False, eig=None, translate=None, INPUT: - See the method :meth:`rauzy_fractal_plot` for a description - of the options and more examples. - - OUTPUT: + See the method :meth:`rauzy_fractal_plot` for a description + of the options and more examples. - dictionary of list of points + OUTPUT: dictionary of list of points EXAMPLES: @@ -2736,9 +2715,7 @@ def rauzy_fractal_plot(self, n=None, exchange=False, eig=None, can be found in :meth:`sage.combinat.words.paths.FiniteWordPath_all.plot_projection` or in :meth:`sage.combinat.e_one_star`. - OUTPUT: - - A Graphics object. + OUTPUT: a Graphics object INPUT: @@ -2747,18 +2724,18 @@ def rauzy_fractal_plot(self, n=None, exchange=False, eig=None, Default values: ``1000`` for a 1D fractal, ``50000`` for a 2D fractal, ``10000`` for a 3D fractal. - - ``exchange`` -- boolean (default: ``False``). - Plot the Rauzy fractal with domain exchange. + - ``exchange`` -- boolean (default: ``False``); plot the Rauzy fractal + with domain exchange - - ``eig`` -- a real element of ``QQbar`` of degree >= 2 (default: ``None``). - The eigenvalue used to plot the fractal. + - ``eig`` -- a real element of ``QQbar`` of degree >= 2 (default: ``None``); + the eigenvalue used to plot the fractal. It must be an eigenvalue of ``self.incidence_matrix()``. The one used by default the maximal eigenvalue of ``self.incidence_matrix()`` (usually a Pisot number), but for substitutions with more than 3 letters other interesting choices are sometimes possible. - - ``translate`` -- a list of vectors of ``RR^size_alphabet``, + - ``translate`` -- list of vectors of ``RR^size_alphabet``, or a dictionary from the alphabet to lists of vectors (default: ``None``). Plot translated copies of the fractal. This option allows to plot tilings easily. @@ -2771,9 +2748,9 @@ def rauzy_fractal_plot(self, n=None, exchange=False, eig=None, is not plotted with the ``translate`` option; the vector ``(0,0,...,0)`` has to be added manually. - - ``prec`` -- integer (default: ``53``). - The number of bits used in the floating point representations - of the points of the fractal. + - ``prec`` -- integer (default: 53); + the number of bits used in the floating point representations + of the points of the fractal - ``colormap`` -- color map or dictionary (default: ``'hsv'``). It can be one of the following: @@ -2781,19 +2758,20 @@ def rauzy_fractal_plot(self, n=None, exchange=False, eig=None, - ``string`` -- a coloring map. For available coloring map names type: ``sorted(colormaps)`` - - ``dict`` -- a dictionary of the alphabet mapped to colors. + - ``dict`` -- dictionary of the alphabet mapped to colors - - ``opacity`` -- a dictionary from the alphabet to the real interval [0,1] (default: ``None``). - If none is specified, all letters are plotted with opacity ``1``. + - ``opacity`` -- dictionary from the alphabet to the real interval + [0,1] (default: ``None``); if none is specified, all letters are + plotted with opacity ``1`` - - ``plot_origin`` -- a couple ``(k,c)`` (default: ``None``). - If specified, mark the origin by a point of size ``k`` and color ``c``. + - ``plot_origin`` -- a couple ``(k,c)`` (default: ``None``); + if specified, mark the origin by a point of size ``k`` and color ``c`` - - ``plot_basis`` -- boolean (default: ``False``). - Plot the projection of the canonical basis with the fractal. + - ``plot_basis`` -- boolean (default: ``False``); plot the projection + of the canonical basis with the fractal - - ``point_size`` -- float (default: ``None``). - The size of the points used to plot the fractal. + - ``point_size`` -- float (default: ``None``); the size of the points + used to plot the fractal EXAMPLES: @@ -3208,10 +3186,10 @@ def letter_growth_types(self): The output is a 3-tuple of lists (mortal, polynomial, exponential) where: - - ``mortal``: list of mortal letters - - ``polynomial``: a list of lists where ``polynomial[i]`` is the - list of letters with growth `n^i`. - - ``exponential``: list of at least exponentionally growing letters + - ``mortal`` -- list of mortal letters + - ``polynomial`` -- list of lists where ``polynomial[i]`` is the + list of letters with growth `n^i` + - ``exponential`` -- list of at least exponentionally growing letters EXAMPLES:: @@ -3446,8 +3424,8 @@ def is_pushy(self, w=None): INPUT: - - ``w`` -- finite iterable (default: ``self.domain().alphabet()``). - Represents a word used to start the language. + - ``w`` -- finite iterable (default: ``self.domain().alphabet()``); + represents a word used to start the language EXAMPLES:: @@ -3473,8 +3451,8 @@ def is_unboundedly_repetitive(self, w=None): INPUT: - - ``w`` -- finite iterable (default: ``self.domain().alphabet()``). - Represents a word used to start the language. + - ``w`` -- finite iterable (default: ``self.domain().alphabet()``); + represents a word used to start the language EXAMPLES:: @@ -3503,8 +3481,8 @@ def is_repetitive(self, w=None): INPUT: - - ``w`` -- finite iterable (default: ``self.domain().alphabet()``). - Represents a word used to start the language. + - ``w`` -- finite iterable (default: ``self.domain().alphabet()``); + represents a word used to start the language EXAMPLES: @@ -3550,10 +3528,10 @@ def infinite_repetitions_primitive_roots(self, w=None, allow_growing=None): INPUT: - - ``w`` -- finite iterable (default: ``self.domain().alphabet()``). - Represents a word used to start the language. + - ``w`` -- finite iterable (default: ``self.domain().alphabet()``); + represents a word used to start the language - - ``allow_growing`` -- boolean or ``None`` (default: ``None``). If + - ``allow_growing`` -- boolean or ``None`` (default: ``None``); if ``False``, return only the primitive roots that contain no growing letters. If ``True``, return only the primitive roots that contain at least one growing letter. If ``None``, return both. @@ -3696,7 +3674,7 @@ def simplify_alphabet_size(self, Z=None): r""" If this morphism is simplifiable, return morphisms `h` and `k` such that this morphism is simplifiable with respect to `h` and `k`, otherwise - raise :class:`ValueError`. + raise :exc:`ValueError`. This method is quite fast if this morphism is non-injective, but very slow if it is injective. @@ -3715,8 +3693,8 @@ def simplify_alphabet_size(self, Z=None): INPUT: - - ``Z`` -- iterable (default: ``self.domain().alphabet()``), whose - elements are used as an alphabet for the simplification. + - ``Z`` -- iterable (default: ``self.domain().alphabet()``) whose + elements are used as an alphabet for the simplification EXAMPLES: diff --git a/src/sage/combinat/words/paths.py b/src/sage/combinat/words/paths.py index ac89659fe91..79c00b5c20e 100644 --- a/src/sage/combinat/words/paths.py +++ b/src/sage/combinat/words/paths.py @@ -217,7 +217,7 @@ def WordPaths(alphabet, steps=None): - ``alphabet`` -- ordered alphabet - - ``steps`` -- (default is ``None``). It can be one of the following: + - ``steps`` -- (default: ``None``) it can be one of the following: - an iterable ordered container of as many vectors as there are letters in the alphabet. The vectors are associated to the letters @@ -229,25 +229,23 @@ def WordPaths(alphabet, steps=None): to the letters according to their order in steps (given vectors first, opposite vectors after). - - ``None``: In this case, the type of steps are guessed from the - length of alphabet. + - ``None`` -- in this case, the type of steps are guessed from the + length of alphabet - - 'square_grid' or 'square': (default when size of alphabet is 4) + - ``'square_grid'`` or ``'square'`` -- (default when size of alphabet is 4) The order is : East, North, West, South. - - 'triangle_grid' or 'triangle': + - ``'triangle_grid'`` or ``'triangle'`` - - 'hexagonal_grid' or 'hexagon': (default when size of alphabet is 6) + - ``'hexagonal_grid'`` or ``'hexagon'`` -- (default when size of alphabet is 6) - - 'cube_grid' or 'cube': + - ``'cube_grid'`` or ``'cube'`` - - 'north_east', 'ne' or 'NE': (the default when size of alphabet is 2) + - ``'north_east'``, ``'ne'`` or ``'NE'`` -- (the default when size of alphabet is 2) - - 'dyck': + - ``'dyck'`` - OUTPUT: - - The combinatorial class of all paths of the given type. + OUTPUT: the combinatorial class of all paths of the given type EXAMPLES: @@ -606,7 +604,6 @@ def vector_space(self): Ambient free module of rank 3 over the principal ideal domain Integer Ring sage: WordPaths('abcdef',steps='triangle_grid').vector_space() Vector space of dimension 2 over Number Field in sqrt3 with defining polynomial x^2 - 3 with sqrt3 = 1.732050807568878? - """ return self._vector_space @@ -621,8 +618,8 @@ def __init__(self, alphabet): INPUT: - - ``alphabet`` -- ordered alphabet of length 4. The order for the steps - is : East, North, West, South. + - ``alphabet`` -- ordered alphabet of length 4; the order for the steps + is : East, North, West, South EXAMPLES:: @@ -1060,7 +1057,7 @@ def points(self, include_last=True): INPUT: - - ``include_last`` -- bool (default: ``True``) whether to include the + - ``include_last`` -- boolean (default: ``True``); whether to include the last point EXAMPLES: @@ -1092,9 +1089,7 @@ def start_point(self): r""" Return the starting point of ``self``. - OUTPUT: - - vector + OUTPUT: vector EXAMPLES:: @@ -1226,7 +1221,6 @@ def tikz_trajectory(self) -> str: sage: p = P('abcde') sage: p.tikz_trajectory() '(0.000, 0.000) -- (1.00, 0.000) -- (1.50, 0.866) -- (1.00, 1.73) -- (0.000, 1.73) -- (-0.500, 0.866)' - """ from sage.misc.functional import N as n l = (str(tuple(n(x, digits=3) for x in pt)) for pt in self.points()) @@ -1239,16 +1233,14 @@ def projected_point_iterator(self, v=None, ring=None): INPUT: - - ``v`` -- vector (default: None) If None, the directive + - ``v`` -- vector (default: ``None``); if ``None``, the directive vector (i.e. the end point minus starting point) of the path is - considered. - - - ``ring`` -- ring (default: None) where to do the - computations. If None, RealField(53) is used. + considered - OUTPUT: + - ``ring`` -- ring (default: ``None``); where to do the + computations. If ``None``, RealField(53) is used. - iterator of points + OUTPUT: iterator of points EXAMPLES: @@ -1301,28 +1293,26 @@ def plot_projection(self, v=None, letters=None, color=None, ring=None, - ``self`` -- a word path in a 3 or 4 dimension vector space - - ``v`` -- vector (default: None) If None, the directive + - ``v`` -- vector (default: ``None``); if ``None``, the directive vector (i.e. the end point minus starting point) of the path is considered. - - ``letters`` -- iterable (default: None) of the letters - to be projected. If None, then all the letters are considered. + - ``letters`` -- iterable (default: ``None``); of the letters + to be projected. If ``None``, then all the letters are considered. - - ``color`` -- dictionary (default: None) of the letters - mapped to colors. If None, automatic colors are chosen. + - ``color`` -- dictionary (default: ``None``); of the letters + mapped to colors. If ``None``, automatic colors are chosen. - - ``ring`` -- ring (default: None) where to do the - computations. If None, RealField(53) is used. + - ``ring`` -- ring (default: ``None``); where to do the + computations. If ``None``, RealField(53) is used. - - ``size`` -- number (default: ``12``) size of the points. + - ``size`` -- number (default: ``12``); size of the points - - ``kind`` -- string (default: ``'right'``) either + - ``kind`` -- string (default: ``'right'``); either ``'right'`` or ``'left'``. The color of a letter is given to the projected prefix to the right or the left of the letter. - OUTPUT: - - 2d or 3d Graphic object. + OUTPUT: 2d or 3d Graphic object EXAMPLES: @@ -1422,16 +1412,14 @@ def projected_path(self, v=None, ring=None): INPUT: - - ``v`` -- vector (default: None) If None, the directive + - ``v`` -- vector (default: ``None``); if ``None``, the directive vector (i.e. the end point minus starting point) of the path is considered. - - ``ring`` -- ring (default: None) where to do the - computations. If None, RealField(53) is used. - - OUTPUT: + - ``ring`` -- ring (default: ``None``); where to do the + computations. If ``None``, RealField(53) is used. - word path + OUTPUT: word path EXAMPLES: @@ -1502,30 +1490,29 @@ def plot(self, pathoptions={"rgbcolor": 'red', "thickness": 3}, default:dict(rgbcolor='red',thickness=3)), options for the path drawing - - ``fill`` -- (boolean, default: ``True``), if fill is True and if + - ``fill`` -- boolean (default: ``True``); if fill is ``True`` and if the path is closed, the inside is colored - ``filloptions`` -- (dict, default:dict(rgbcolor='red',alpha=0.2)), options for the inside filling - - ``startpoint`` -- (boolean, default: ``True``), draw the start point? + - ``startpoint`` -- boolean (default: ``True``); draw the start point? - ``startoptions`` -- (dict, default:dict(rgbcolor='red',pointsize=100)) options for the start point drawing - - ``endarrow`` -- (boolean, default: ``True``), draw an arrow end at the end? + - ``endarrow`` -- boolean (default: ``True``); draw an arrow end at the end? - ``arrowoptions`` -- (dict, default:dict(rgbcolor='red',arrowsize=20, width=3)) options for the end point arrow - - ``gridlines`` -- (boolean, default: ``False``), show gridlines? + - ``gridlines`` -- boolean (default: ``False``); show gridlines? - ``gridoptions`` -- (dict, default: {}), options for the gridlines - EXAMPLES: A non closed path on the square grid:: @@ -1655,7 +1642,7 @@ def animate(self): Animation with 296 frames sage: show(a*b*c*d) # long time, optional - imagemagick - .. note:: + .. NOTE:: If ImageMagick is not installed, you will get an error message like this:: @@ -1667,7 +1654,6 @@ def animate(self): ImageMagick, so please install it and try again. See www.imagemagick.org, for example. - """ from sage.plot.all import line, polygon, animate @@ -1752,7 +1738,6 @@ def area(self): sage: p = P('abcd') sage: p.area() #todo: not implemented 2 - """ if not self.is_closed(): raise TypeError("the path must be closed to compute its area") @@ -1766,9 +1751,7 @@ def height(self): between the highest and the lowest `y`-coordinate of each points traced by it. - OUTPUT: - - non negative real number + OUTPUT: nonnegative real number EXAMPLES:: @@ -1776,7 +1759,7 @@ def height(self): sage: Freeman('aababaabbbAA').height() 5 - The function is well-defined if self is not simple or close:: + The function is well-defined if ``self`` is not simple or close:: sage: Freeman('aabAAB').height() 1 @@ -1833,9 +1816,7 @@ def width(self): between the rightmost and the leftmost `x`-coordinate of each points traced by it. - OUTPUT: - - non negative real number + OUTPUT: nonnegative real number EXAMPLES:: @@ -1843,7 +1824,7 @@ def width(self): sage: Freeman('aababaabbbAA').width() 5 - The function is well-defined if self is not simple or close:: + The function is well-defined if ``self`` is not simple or close:: sage: Freeman('aabAAB').width() 2 @@ -2010,10 +1991,10 @@ def plot(self, pathoptions={"rgbcolor": 'red', "arrow_head": True, "thickness": - ``pathoptions`` -- (dict, default:dict(rgbcolor='red',arrow_head=True, thickness=3)), options for the path drawing - - ``startpoint`` -- (boolean, default: ``True``), draw the start point? + - ``startpoint`` -- boolean (default: ``True``); draw the start point? - ``startoptions`` -- (dict, default:dict(rgbcolor='red',size=10)) - options for the start point drawing + options for the start point drawing EXAMPLES:: @@ -2029,7 +2010,6 @@ def plot(self, pathoptions={"rgbcolor": 'red', "arrow_head": True, "thickness": sage: p = P('abcabcAABBC') sage: p.plot() # needs sage.plot Graphics3d Object - """ # The following line seems not to work for 3d # G = Graphics() @@ -2129,7 +2109,6 @@ def area(self): Traceback (most recent call last): ... TypeError: the path must be closed to compute its area - """ if not self.is_closed(): raise TypeError("the path must be closed to compute its area") @@ -2186,7 +2165,7 @@ def is_simple(self) -> bool: If the path is closed, the last point is not considered. - .. note:: + .. NOTE:: The linear algorithm described in the thesis of Xavier Provençal should be implemented here. diff --git a/src/sage/combinat/words/shuffle_product.py b/src/sage/combinat/words/shuffle_product.py index 719e0122e5c..5aea554b6b6 100644 --- a/src/sage/combinat/words/shuffle_product.py +++ b/src/sage/combinat/words/shuffle_product.py @@ -56,7 +56,7 @@ def __init__(self, w1, w2, check=True): INPUT: - - ``check`` -- boolean (default ``True``) whether to check that + - ``check`` -- boolean (default: ``True``); whether to check that all words in the shuffle product belong to the correct parent EXAMPLES:: @@ -243,7 +243,7 @@ def __init__(self, w1, w2, check=True): INPUT: - - ``check`` -- boolean (default ``True``) whether to check that + - ``check`` -- boolean (default: ``True``); whether to check that all words in the shuffle product belong to the correct parent EXAMPLES:: diff --git a/src/sage/combinat/words/suffix_trees.py b/src/sage/combinat/words/suffix_trees.py index e64f2fb8db6..3249ce23235 100644 --- a/src/sage/combinat/words/suffix_trees.py +++ b/src/sage/combinat/words/suffix_trees.py @@ -103,7 +103,7 @@ def _process_letter(self, letter): Process a letter. That is, modify the current suffix trie producing the suffix trie for ``self.word() + letter``. - .. note:: + .. NOTE:: ``letter`` must occur within the alphabet of the word. @@ -143,7 +143,7 @@ def process_letter(self, letter): Modify ``self`` to produce the suffix trie for ``self.word() + letter``. - .. note:: + .. NOTE:: ``letter`` must occur within the alphabet of the word. @@ -602,7 +602,7 @@ def _process_letter(self, letter): This corresponds to the algorithm "update" in [Ukko1995]_. - .. note:: + .. NOTE:: This function is a helper and does not update ``self._data`` and ``self._word``. @@ -833,9 +833,8 @@ def to_digraph(self, word_labels=False): INPUT: - - ``word_labels`` -- boolean (default: ``False``) if ``False``, labels - the edges by pairs `(i, j)`; if ``True``, labels the edges by - ``word[i:j]``. + - ``word_labels`` -- boolean (default: ``False``); if ``False``, labels + the edges by pairs `(i, j)`. If ``True``, labels the edges by ``word[i:j]`` EXAMPLES:: @@ -866,14 +865,13 @@ def plot(self, word_labels=False, layout='tree', tree_root=0, INPUT: - - ``word_labels`` -- boolean (default: ``False``) if ``False``, labels - the edges by pairs `(i, j)`; if ``True``, labels the edges by - ``word[i:j]``. - - ``layout`` -- (default: ``'tree'``) - - ``tree_root`` -- (default: 0) - - ``tree_orientation`` -- (default: ``'up'``) - - ``vertex_colors`` -- (default: ``None``) - - ``edge_labels`` -- (default: ``True``) + - ``word_labels`` -- boolean (default: ``False``); if ``False``, labels + the edges by pairs `(i, j)`; if ``True``, labels the edges by ``word[i:j]`` + - ``layout`` -- (default: ``'tree'``) + - ``tree_root`` -- (default: 0) + - ``tree_orientation`` -- (default: ``'up'``) + - ``vertex_colors`` -- (default: ``None``) + - ``edge_labels`` -- (default: ``True``) EXAMPLES:: @@ -908,9 +906,8 @@ def show(self, word_labels=None, *args, **kwds): INPUT: - - ``word_labels`` -- (default: ``None``) if ``False``, labels the - edges by pairs `(i, j)`; if ``True``, labels the edges by - ``word[i:j]``. + - ``word_labels`` -- (default: ``None``) if ``False``, labels the edges + by pairs `(i, j)`; if ``True``, labels the edges by ``word[i:j]`` EXAMPLES:: @@ -1150,13 +1147,13 @@ def number_of_factors(self, n=None): INPUT: - - ``n`` -- an integer, or ``None``. + - ``n`` -- integer or ``None`` OUTPUT: - - If ``n`` is an integer, returns the number of distinct factors - of length ``n``. If ``n`` is ``None``, returns the total number of - distinct factors. + If ``n`` is an integer, returns the number of distinct factors + of length ``n``. If ``n`` is ``None``, returns the total number of + distinct factors. EXAMPLES:: @@ -1236,13 +1233,13 @@ def factor_iterator(self, n=None): INPUT: - - ``n`` -- an integer, or ``None``. + - ``n`` -- integer or ``None`` OUTPUT: - - If ``n`` is an integer, returns an iterator over all distinct - factors of length ``n``. If ``n`` is ``None``, returns an iterator - generating all distinct factors. + If ``n`` is an integer, returns an iterator over all distinct + factors of length ``n``. If ``n`` is ``None``, returns an iterator + generating all distinct factors. EXAMPLES:: @@ -1468,7 +1465,7 @@ def leftmost_covering_set(self): def condition1_square_pairs(i): r""" - Computes the squares that have their center (the last letter of the + Compute the squares that have their center (the last letter of the first occurrence of ``w`` in ``ww``) in the `i`-th block of the LZ-decomposition and that start in the `i`-th block and end in the `(i+1)`-th. @@ -1626,7 +1623,7 @@ def __init__(self, w): We skip the ``_test_and_split`` test because it is not a test meant for the ``TestSuite``:: - sage: TestSuite(DST).run(skip="_test_and_split") + sage: TestSuite(DST).run(skip='_test_and_split') Test that we do not allow ``'$'`` to appear in the word:: @@ -1686,7 +1683,7 @@ def node_processing(node, parent, head): - ``node`` -- a node of ``self`` - ``parent`` -- the parent of a node in ``self`` - - ``head`` -- a tuple indicating the head of the list ``P(node)`` + - ``head`` -- tuple indicating the head of the list ``P(node)`` OUTPUT: ``(i, pos)``, the new head of ``P(node)`` """ @@ -1811,8 +1808,8 @@ def treat_node(current_node, i, j): INPUT: - - ``current_node`` -- The node to treat - - ``(i, j)`` -- Pair of index such that the path from 0 to + - ``current_node`` -- the node to treat + - ``(i, j)`` -- pair of index such that the path from 0 to ``current_node`` reads ``self.word()[i:j]`` """ @@ -1832,7 +1829,7 @@ def treat_node(current_node, i, j): treat_node(0, 0, 0) return labeling - def square_vocabulary(self, output="pair"): + def square_vocabulary(self, output='pair'): r""" Return the list of distinct squares of ``self.word``. @@ -1843,7 +1840,7 @@ def square_vocabulary(self, output="pair"): INPUT: - - ``output`` -- (default: ``"pair"``) either ``"pair"`` or ``"word"`` + - ``output`` -- (default: ``'pair'``) either ``'pair'`` or ``'word'`` EXAMPLES:: @@ -1852,7 +1849,7 @@ def square_vocabulary(self, output="pair"): sage: sorted(DecoratedSuffixTree(w).square_vocabulary()) [(0, 0), (0, 2), (2, 2)] sage: w = Word('00110011010') - sage: sorted(DecoratedSuffixTree(w).square_vocabulary(output="word")) + sage: sorted(DecoratedSuffixTree(w).square_vocabulary(output='word')) [word: , word: 00, word: 00110011, word: 01100110, word: 1010, word: 11] """ def treat_node(current_node, i, j): diff --git a/src/sage/combinat/words/word.py b/src/sage/combinat/words/word.py index 1802ab23750..2470ee0c00f 100644 --- a/src/sage/combinat/words/word.py +++ b/src/sage/combinat/words/word.py @@ -47,31 +47,31 @@ def Word(data=None, alphabet=None, length=None, datatype=None, caching=True, RSK INPUT: - - ``data`` -- (default: ``None``) list, string, tuple, iterator, free - monoid element, ``None`` (shorthand for ``[]``), or a callable defined - on ``[0,1,...,length]``. + - ``data`` -- (default: ``None``) list, string, tuple, iterator, free + monoid element, ``None`` (shorthand for ``[]``), or a callable defined + on ``[0,1,...,length]`` - - ``alphabet`` -- any argument accepted by Words + - ``alphabet`` -- any argument accepted by Words - - ``length`` -- (default: ``None``) This is dependent on the type of data. - It is ignored for words defined by lists, strings, tuples, - etc., because they have a naturally defined length. - For callables, this defines the domain of definition, - which is assumed to be ``[0, 1, 2, ..., length-1]``. - For iterators: Infinity if you know the iterator will not - terminate (default); ``"unknown"`` if you do not know whether the - iterator terminates; ``"finite"`` if you know that the iterator - terminates, but do not know the length. + - ``length`` -- (default: ``None``) this is dependent on the type of data. + It is ignored for words defined by lists, strings, tuples, + etc., because they have a naturally defined length. + For callables, this defines the domain of definition, + which is assumed to be ``[0, 1, 2, ..., length-1]``. + For iterators: Infinity if you know the iterator will not + terminate (default); ``'unknown'`` if you do not know whether the + iterator terminates; ``'finite'`` if you know that the iterator + terminates, but do not know the length. - - ``datatype`` -- (default: ``None``) ``None``, ``"list"``, ``"str"``, - ``"tuple"``, ``"iter"``, ``"callable"``. If ``None``, then the function - tries to guess this from the data. + - ``datatype`` -- (default: ``None``) ``None``, ``'list'``, ``'str'``, + ``'tuple'``, ``'iter'``, ``'callable'``; if ``None``, then the function + tries to guess this from the data - - ``caching`` -- (default: ``True``) ``True`` or ``False``. Whether to - keep a cache of the letters computed by an iterator or callable. + - ``caching`` -- boolean (default: ``True``); whether to + keep a cache of the letters computed by an iterator or callable - - ``RSK_data`` -- (Optional. Default: ``None``) A semistandard and a - standard Young tableau to run the inverse RSK bijection on. + - ``RSK_data`` -- (default: ``None``) semistandard and a + standard Young tableau to run the inverse RSK bijection on .. NOTE:: @@ -94,9 +94,9 @@ def Word(data=None, alphabet=None, length=None, datatype=None, caching=True, RSK Word with string constructed from other types:: - sage: Word([0,1,1,0,1,0,0,1], datatype="str") + sage: Word([0,1,1,0,1,0,0,1], datatype='str') word: 01101001 - sage: Word((0,1,1,0,1,0,0,1), datatype="str") + sage: Word((0,1,1,0,1,0,0,1), datatype='str') word: 01101001 Word with list:: @@ -106,9 +106,9 @@ def Word(data=None, alphabet=None, length=None, datatype=None, caching=True, RSK Word with list constructed from other types:: - sage: Word("01101001", datatype="list") + sage: Word("01101001", datatype='list') word: 01101001 - sage: Word((0,1,1,0,1,0,0,1), datatype="list") + sage: Word((0,1,1,0,1,0,0,1), datatype='list') word: 01101001 Word with tuple:: @@ -118,9 +118,9 @@ def Word(data=None, alphabet=None, length=None, datatype=None, caching=True, RSK Word with tuple constructed from other types:: - sage: Word([0,1,1,0,1,0,0,1], datatype="tuple") + sage: Word([0,1,1,0,1,0,0,1], datatype='tuple') word: 01101001 - sage: Word("01101001", datatype="str") + sage: Word("01101001", datatype='str') word: 01101001 Word with iterator:: @@ -130,9 +130,9 @@ def Word(data=None, alphabet=None, length=None, datatype=None, caching=True, RSK word: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,... sage: Word(iter("abbabaab")) # iterators default to infinite words word: abbabaab - sage: Word(iter("abbabaab"), length="unknown") + sage: Word(iter("abbabaab"), length='unknown') word: abbabaab - sage: Word(iter("abbabaab"), length="finite") + sage: Word(iter("abbabaab"), length='finite') word: abbabaab Word with function (a 'callable'):: @@ -145,7 +145,7 @@ def Word(data=None, alphabet=None, length=None, datatype=None, caching=True, RSK Word over a string with a parent:: - sage: w = Word("abbabaab", alphabet="abc"); w + sage: w = Word("abbabaab", alphabet='abc'); w word: abbabaab sage: w.parent() Finite words over {'a', 'b', 'c'} diff --git a/src/sage/combinat/words/word_char.pyx b/src/sage/combinat/words/word_char.pyx index da5d9bb2194..18be2efde90 100644 --- a/src/sage/combinat/words/word_char.pyx +++ b/src/sage/combinat/words/word_char.pyx @@ -68,7 +68,7 @@ cdef class WordDatatype_char(WordDatatype): def __cinit__(self): r""" - Initialization of C attributes + Initialization of C attributes. TESTS:: @@ -81,7 +81,7 @@ cdef class WordDatatype_char(WordDatatype): def __init__(self, parent, data): r""" - Constructor + Constructor. TESTS:: @@ -102,7 +102,7 @@ cdef class WordDatatype_char(WordDatatype): @cython.wraparound(False) # not check not correctly handle negative indices cdef _set_data(self, data): r""" - set the attribute ._data and ._length from the sequence data + Set the attribute ._data and ._length from the sequence data (usually data is a word, a tuple or a list) """ cdef size_t i @@ -114,9 +114,9 @@ cdef class WordDatatype_char(WordDatatype): def __dealloc__(self): r""" - Deallocate memory only if self uses it own memory. + Deallocate memory only if ``self`` uses it own memory. - Note that ``sig_free`` will not deallocate memory if self is the + Note that ``sig_free`` will not deallocate memory if ``self`` is the master of another word. """ # it is strictly forbidden here to access _master here! (it will be set @@ -250,7 +250,7 @@ cdef class WordDatatype_char(WordDatatype): - ``other`` -- a word (WordDatatype_char) - - ``op`` -- int, from 0 to 5 + - ``op`` -- integer from 0 to 5 TESTS:: @@ -501,11 +501,11 @@ cdef class WordDatatype_char(WordDatatype): def __pow__(self, exp, mod): r""" - Power + Power. INPUT: - - ``exp`` -- an integer, a rational, a float number or plus infinity. + - ``exp`` -- integer, rational, float, or plus infinity TESTS:: @@ -646,7 +646,7 @@ cdef class WordDatatype_char(WordDatatype): def is_square(self): r""" - Return True if self is a square, and False otherwise. + Return ``True`` if ``self`` is a square, and ``False`` otherwise. EXAMPLES:: diff --git a/src/sage/combinat/words/word_datatypes.pyx b/src/sage/combinat/words/word_datatypes.pyx index 4e30fd81ba4..ddda24ab436 100644 --- a/src/sage/combinat/words/word_datatypes.pyx +++ b/src/sage/combinat/words/word_datatypes.pyx @@ -33,11 +33,10 @@ cdef class WordDatatype(): sage: w = Word([0,1,1,0,0,1]) sage: isinstance(w, sage.combinat.words.word_datatypes.WordDatatype) True - """ def __reduce__(self): r""" - Default pickle support + Default pickle support. TESTS:: @@ -49,7 +48,7 @@ cdef class WordDatatype(): def __hash__(self): r""" - Returns the hash for this word. + Return the hash for this word. TESTS:: @@ -112,9 +111,7 @@ cdef class WordDatatype_list(WordDatatype): - ``a`` -- anything - OUTPUT: - - - boolean + OUTPUT: boolean EXAMPLES:: @@ -123,36 +120,32 @@ cdef class WordDatatype_list(WordDatatype): True sage: 3 in w False - """ return a in self._data def __iter__(self): r""" - Return an iterator that iterates through the letters of self. + Return an iterator that iterates through the letters of ``self``. EXAMPLES:: sage: w = Word([0,1,1,0]) sage: list(iter(w)) [0, 1, 1, 0] - """ return iter(self._data) def __richcmp__(self, other, int op): r""" - Equality test for self and other if other is an instance of - WordDatype_list. + Equality test for ``self`` and ``other`` if other is an instance of + ``WordDatype_list``. INPUT: - ``other`` -- a word - - ``op`` -- integer: 0, 1, 2, 3, 4 or 5 - - OUTPUT: + - ``op`` -- integer; 0, 1, 2, 3, 4 or 5 - boolean or NotImplemented + OUTPUT: boolean or NotImplemented EXAMPLES:: @@ -198,7 +191,6 @@ cdef class WordDatatype_list(WordDatatype): sage: w = Word([0,1,1,0]) sage: len(w) 4 - """ return len(self._data) @@ -211,13 +203,12 @@ cdef class WordDatatype_list(WordDatatype): sage: w = Word([0,1,1,0]) sage: w.length() 4 - """ return len(self._data) def __getitem__(self, key): r""" - Implements :meth:`__getitem__` for words stored as lists. + Implement :meth:`__getitem__` for words stored as lists. INPUT: @@ -233,7 +224,6 @@ cdef class WordDatatype_list(WordDatatype): 99 sage: w[3:10:2] word: 3579 - """ if isinstance(key, slice): return self._parent(self._data[key]) @@ -242,15 +232,13 @@ cdef class WordDatatype_list(WordDatatype): def __mul__(self, other): r""" - Return the concatenation of self and other. + Return the concatenation of ``self`` and ``other``. INPUT: - ``other`` -- word represented by a list - OUTPUT: - - word + OUTPUT: word EXAMPLES:: @@ -274,16 +262,14 @@ cdef class WordDatatype_list(WordDatatype): def number_of_letter_occurrences(self, a): r""" - Returns the number of occurrences of the letter ``a`` in the word + Return the number of occurrences of the letter ``a`` in the word ``self``. INPUT: - - ``a`` -- a letter - - OUTPUT: + - ``a`` -- a letter - - integer + OUTPUT: integer EXAMPLES:: @@ -298,7 +284,6 @@ cdef class WordDatatype_list(WordDatatype): .. SEEALSO:: :meth:`sage.combinat.words.finite_word.FiniteWord_class.number_of_factor_occurrences` - """ return self._data.count(a) @@ -323,7 +308,6 @@ cdef class WordDatatype_str(WordDatatype): sage: w = Word("abba") sage: isinstance(w, sage.combinat.words.word_datatypes.WordDatatype_str) True - """ self._parent = parent if isinstance(data, str): @@ -343,23 +327,20 @@ cdef class WordDatatype_str(WordDatatype): sage: w = Word('abba') sage: list(iter(w)) ['a', 'b', 'b', 'a'] - """ return iter(self._data) def __richcmp__(self, other, int op): r""" - Equality test for self and other if other is an instance of - WordDatype_str. + Equality test for ``self`` and ``other`` if other is an instance of + ``WordDatype_str``. INPUT: - ``other`` -- a word - - ``op`` -- integer: 0, 1, 2, 3, 4 or 5 + - ``op`` -- integer; 0, 1, 2, 3, 4 or 5 - OUTPUT: - - boolean or NotImplemented + OUTPUT: boolean or NotImplemented EXAMPLES:: @@ -408,7 +389,6 @@ cdef class WordDatatype_str(WordDatatype): True sage: 'c' in w False - """ # we need to override the non standard behaviour of # the __contains__ of python str @@ -429,11 +409,10 @@ cdef class WordDatatype_str(WordDatatype): INPUT: - - ``w`` -- a word, or something that behaves like one (list, tuple, str, ...) - - OUTPUT: + - ``w`` -- a word, or something that behaves like one (``list``, + ``tuple``, ``str``, ...) - - boolean + OUTPUT: boolean EXAMPLES:: @@ -451,22 +430,20 @@ cdef class WordDatatype_str(WordDatatype): cpdef find(self, sub, start=0, end=None): r""" - Returns the index of the first occurrence of sub in self, + Return the index of the first occurrence of sub in self, such that sub is contained within self[start:end]. Returns -1 on failure. INPUT: - - ``sub`` -- string or word to search for. - - ``start`` -- non negative integer (default: 0) specifying - the position from which to start the search. - - ``end`` -- non negative integer (default: None) specifying - the position at which the search must stop. If None, then - the search is performed up to the end of the string. - - OUTPUT: + - ``sub`` -- string or word to search for + - ``start`` -- nonnegative integer (default: 0) specifying + the position from which to start the search. + - ``end`` -- nonnegative integer (default: ``None``); specifying + the position at which the search must stop. If ``None``, then + the search is performed up to the end of the string. - non negative integer or -1 + OUTPUT: nonnegative integer or `-1` EXAMPLES:: @@ -489,22 +466,20 @@ cdef class WordDatatype_str(WordDatatype): def rfind(self, sub, start=0, end=None): r""" - Returns the index of the last occurrence of sub in self, + Return the index of the last occurrence of sub in self, such that sub is contained within self[start:end]. Returns -1 on failure. INPUT: - - ``sub`` -- string or word to search for. - - ``start`` -- non negative integer (default: 0) specifying - the position at which the search must stop. - - ``end`` -- non negative integer (default: None) specifying - the position from which to start the search. If None, then - the search is performed up to the end of the string. + - ``sub`` -- string or word to search for + - ``start`` -- nonnegative integer (default: 0) specifying + the position at which the search must stop. + - ``end`` -- nonnegative integer (default: ``None``); specifying + the position from which to start the search. If ``None``, then + the search is performed up to the end of the string. - OUTPUT: - - non negative integer or -1 + OUTPUT: nonnegative integer or `-1` EXAMPLES:: @@ -539,7 +514,6 @@ cdef class WordDatatype_str(WordDatatype): sage: w = Word("abbabaabababa") sage: len(w) 13 - """ return len(self._data) @@ -552,13 +526,12 @@ cdef class WordDatatype_str(WordDatatype): sage: w = Word("abbabaabababa") sage: w.length() 13 - """ return len(self._data) def __getitem__(self, key): r""" - Implements the :meth:`__getitem__`. + Implement the :meth:`__getitem__`. TESTS:: @@ -579,15 +552,13 @@ cdef class WordDatatype_str(WordDatatype): def __mul__(self, other): r""" - Return the concatenation of self and other. + Return the concatenation of ``self`` and ``other``. INPUT: - - ``other`` -- word represented by a str + - ``other`` -- word represented by a string - OUTPUT: - - word + OUTPUT: word EXAMPLES:: @@ -617,9 +588,7 @@ cdef class WordDatatype_str(WordDatatype): - ``letter`` -- a letter - OUTPUT: - - - integer + OUTPUT: integer EXAMPLES:: @@ -639,7 +608,6 @@ cdef class WordDatatype_str(WordDatatype): .. SEEALSO:: :meth:`sage.combinat.words.finite_word.FiniteWord_class.number_of_factor_occurrences` - """ if len(letter) == 1: return self._data.count(letter) @@ -648,7 +616,7 @@ cdef class WordDatatype_str(WordDatatype): def split(self, sep=None, maxsplit=None): r""" - Returns a list of words, using sep as a delimiter string. + Return a list of words, using sep as a delimiter string. If maxsplit is given, at most maxsplit splits are done. See also the partition method. @@ -660,13 +628,11 @@ cdef class WordDatatype_str(WordDatatype): INPUT: - - ``sep`` -- string or word (default: None) - - - ``maxsplit`` -- positive integer (default: None) + - ``sep`` -- string or word (default: ``None``) - OUTPUT: + - ``maxsplit`` -- positive integer (default: ``None``) - - a list of words + OUTPUT: list of words EXAMPLES: @@ -696,7 +662,7 @@ cdef class WordDatatype_str(WordDatatype): sage: w.split("32") [word: , word: 30301030, word: , word: 12, word: 30, word: , word: 1] - If the separator is not a string a :class:`ValueError` is raised:: + If the separator is not a string a :exc:`ValueError` is raised:: sage: w = Word("le papa du papa du papa etait un petit pioupiou") sage: w.split(Word(['p','a','p','a'])) @@ -768,11 +734,9 @@ cdef class WordDatatype_str(WordDatatype): INPUT: - ``other`` -- a word (an instance of :class:`Word_class`) or a - :class:`str`. + :class:`str` - OUTPUT: - - - boolean + OUTPUT: boolean EXAMPLES:: @@ -793,7 +757,6 @@ cdef class WordDatatype_str(WordDatatype): False sage: u.is_suffix(w) True - """ if isinstance(other, WordDatatype_str): return other._data.endswith(self._data) @@ -809,11 +772,9 @@ cdef class WordDatatype_str(WordDatatype): INPUT: - ``other`` -- a word (an instance of :class:`Word_class`) or a - :class:`str`. - - OUTPUT: + :class:`str` - - boolean + OUTPUT: boolean EXAMPLES:: @@ -825,7 +786,6 @@ cdef class WordDatatype_str(WordDatatype): False sage: u.has_suffix("ababa") True - """ if isinstance(other, WordDatatype_str): return self._data.endswith(other._data) @@ -841,11 +801,9 @@ cdef class WordDatatype_str(WordDatatype): INPUT: - ``other`` -- a word (an instance of :class:`Word_class`) or a - :class:`str`. - - OUTPUT: + :class:`str` - - boolean + OUTPUT: boolean EXAMPLES:: @@ -880,11 +838,9 @@ cdef class WordDatatype_str(WordDatatype): INPUT: - ``other`` -- a word (an instance of :class:`Word_class`) or a - :class:`str`. + :class:`str` - OUTPUT: - - - boolean + OUTPUT: boolean EXAMPLES:: @@ -905,7 +861,6 @@ cdef class WordDatatype_str(WordDatatype): False sage: abba.has_prefix(ab) True - """ if isinstance(other, WordDatatype_str): return self._data.startswith(other._data) @@ -949,30 +904,27 @@ cdef class WordDatatype_tuple(WordDatatype): def __iter__(self): r""" - Return an iterator that iterates through the letters of self. + Return an iterator that iterates through the letters of ``self``. EXAMPLES:: sage: w = Word((0,1,1,0)) sage: list(iter(w)) [0, 1, 1, 0] - """ return iter(self._data) def __richcmp__(self, other, int op): r""" - Equality test for self and other if other is an instance of - WordDatype_tuple. + Equality test for ``self`` and ``other`` if other is an instance of + ``WordDatype_tuple``. INPUT: - ``other`` -- a word - - ``op`` -- integer: 0, 1, 2, 3, 4 or 5 - - OUTPUT: + - ``op`` -- integer; 0, 1, 2, 3, 4 or 5 - boolean or NotImplemented + OUTPUT: boolean or NotImplemented EXAMPLES:: @@ -1020,7 +972,6 @@ cdef class WordDatatype_tuple(WordDatatype): sage: w = Word((0,1,1,0)) sage: len(w) 4 - """ return len(self._data) @@ -1033,7 +984,6 @@ cdef class WordDatatype_tuple(WordDatatype): sage: w = Word((0,1,1,0)) sage: w.length() 4 - """ return len(self._data) @@ -1052,17 +1002,16 @@ cdef class WordDatatype_tuple(WordDatatype): True sage: 3 in w False - """ return a in self._data def __getitem__(self, key): r""" - Implements ``__getitem__`` for words stored as tuples. + Implement ``__getitem__`` for words stored as tuples. INPUT: - - ``key`` -- an integer + - ``key`` -- integer OUTPUT: @@ -1079,7 +1028,6 @@ cdef class WordDatatype_tuple(WordDatatype): word: 3579 sage: all(w[i] == i for i in range(100)) True - """ if isinstance(key, slice): return self._parent(self._data[key]) @@ -1087,15 +1035,13 @@ cdef class WordDatatype_tuple(WordDatatype): def __mul__(self, other): r""" - Return the concatenation of self and other. + Return the concatenation of ``self`` and ``other``. INPUT: - ``other`` -- word represented by a tuple - OUTPUT: - - word + OUTPUT: word EXAMPLES:: diff --git a/src/sage/combinat/words/word_generators.py b/src/sage/combinat/words/word_generators.py index 6665658a71e..5803709ba5b 100644 --- a/src/sage/combinat/words/word_generators.py +++ b/src/sage/combinat/words/word_generators.py @@ -108,8 +108,8 @@ def _build_tab(sym, tab, W): class LowerChristoffelWord(FiniteWord_list): r""" - Returns the lower Christoffel word of slope `p/q`, where `p` and - `q` are relatively prime non-negative integers, over the given + Return the lower Christoffel word of slope `p/q`, where `p` and + `q` are relatively prime nonnegative integers, over the given two-letter alphabet. The *Christoffel word of slope `p/q`* is obtained from the @@ -144,14 +144,14 @@ def __init__(self, p, q, alphabet=(0, 1), algorithm='cf'): r""" INPUT: - - ``p`` -- integer coprime with ``q``. - - ``q`` -- integer coprime with ``p``. - - ``alphabet`` -- sequence of two elements (default: (0, 1)). - - ``algorithm`` -- construction method (default: 'cf'). + - ``p`` -- integer coprime with `q` + - ``q`` -- integer coprime with `p` + - ``alphabet`` -- sequence of two elements (default: (0, 1)) + - ``algorithm`` -- construction method (default: ``'cf'``). It can be one of the following: - - ``'linear'`` -- linear algorithm in the length of the word. - - ``'cf'`` -- fast method using continued fraction. + - ``'linear'`` -- linear algorithm in the length of the word + - ``'cf'`` -- fast method using continued fraction TESTS:: @@ -257,7 +257,7 @@ def markoff_number(self): def standard_factorization(self): r""" - Returns the standard factorization of the Christoffel word ``self``. + Return the standard factorization of the Christoffel word ``self``. The *standard factorization* of a Christoffel word `w` is the unique factorization of `w` into two Christoffel words. @@ -367,7 +367,7 @@ class WordGenerator: """ def ThueMorseWord(self, alphabet=(0, 1), base=2): r""" - Returns the (Generalized) Thue-Morse word over the given alphabet. + Return the (Generalized) Thue-Morse word over the given alphabet. There are several ways to define the Thue-Morse word `t`. We use the following definition: `t[n]` is the sum modulo `m` of @@ -377,10 +377,10 @@ def ThueMorseWord(self, alphabet=(0, 1), base=2): INPUT: - - ``alphabet`` -- (default: (0, 1) ) any container that is suitable to - build an instance of OrderedAlphabet (list, tuple, str, ...) + - ``alphabet`` -- (default: ``(0, 1)``) any container that is suitable + to build an instance of OrderedAlphabet (``list``, ``tuple``, ``str``, ...) - - ``base`` -- an integer (default : 2) greater or equal to 2 + - ``base`` -- integer (default: 2); greater than or equal to 2 EXAMPLES: @@ -435,7 +435,7 @@ def ThueMorseWord(self, alphabet=(0, 1), base=2): def _ThueMorseWord_nth_digit(self, n, alphabet=(0, 1), base=2): r""" - Returns the `n`-th letter of the (Generalized) Thue-Morse word. + Return the `n`-th letter of the (Generalized) Thue-Morse word. The `n`-th digit of the Thue-Morse word can be defined as the number of bits in the 2-complement representation of the position @@ -448,9 +448,9 @@ def _ThueMorseWord_nth_digit(self, n, alphabet=(0, 1), base=2): INPUT: - - ``n`` -- integer, the position - - ``alphabet`` -- an alphabet (default : (0, 1) ) of size at least 2 - - ``base`` -- an integer (default : 2) greater or equal to 2 + - ``n`` -- integer; the position + - ``alphabet`` -- an alphabet (default: (0, 1)) of size at least 2 + - ``base`` -- integer (default: 2) greater than or equal to 2 OUTPUT: @@ -489,17 +489,17 @@ def _ThueMorseWord_nth_digit(self, n, alphabet=(0, 1), base=2): else: return alphabet[ZZ(sum(ZZ(n).digits(base=base))).mod(m)] - def FibonacciWord(self, alphabet=(0, 1), construction_method="recursive"): + def FibonacciWord(self, alphabet=(0, 1), construction_method='recursive'): r""" - Returns the Fibonacci word on the given two-letter alphabet. + Return the Fibonacci word on the given two-letter alphabet. INPUT: - - ``alphabet`` -- any container of length two that is suitable to - build an instance of OrderedAlphabet (list, tuple, str, ...) + - ``alphabet`` -- any container of length two that is suitable to + build an instance of OrderedAlphabet (``list``, ``tuple``, ``str``, ...) - - ``construction_method`` -- can be any of the following: - "recursive", "fixed point", "function" (see below for definitions). + - ``construction_method`` -- can be any of the following: + "recursive", "fixed point", "function" (see below for definitions) Recursive construction: the Fibonacci word is the limit of the following sequence of words: `S_0 = 0`, `S_1 = 01`, @@ -514,19 +514,19 @@ def FibonacciWord(self, alphabet=(0, 1), construction_method="recursive"): #. if the next letter is `1`, append `1` to the word; #. move to the next letter of the word. - Function: Over the alphabet `\{1, 2\}`, the n-th letter of the + Function: Over the alphabet `\{1, 2\}`, the `n`-th letter of the Fibonacci word is `\lfloor (n+2) \varphi \rfloor - \lfloor (n+1) \varphi \rfloor` where `\varphi=(1+\sqrt{5})/2` is the golden ratio. EXAMPLES:: - sage: w = words.FibonacciWord(construction_method="recursive"); w + sage: w = words.FibonacciWord(construction_method='recursive'); w word: 0100101001001010010100100101001001010010... :: - sage: v = words.FibonacciWord(construction_method="recursive", alphabet='ab'); v + sage: v = words.FibonacciWord(construction_method='recursive', alphabet='ab'); v word: abaababaabaababaababaabaababaabaababaaba... :: @@ -591,7 +591,7 @@ def FibonacciWord(self, alphabet=(0, 1), construction_method="recursive"): def _FibonacciWord_RecursiveConstructionIterator(self,alphabet=(0,1)): r""" - Iterates over the symbols of the Fibonacci word, as defined by + Iterate over the symbols of the Fibonacci word, as defined by the following recursive construction: the Fibonacci word is the limit of the sequence `S_0 = 0`, `S_1 = 01`, `S_n = S_{n-1} S_{n-2}` for `n \geq 2`. @@ -617,7 +617,7 @@ def _FibonacciWord_RecursiveConstructionIterator(self,alphabet=(0,1)): def FixedPointOfMorphism(self, morphism, first_letter): r""" - Returns the fixed point of the morphism beginning with + Return the fixed point of the morphism beginning with ``first_letter``. A *fixed point* of a morphism `\varphi` is a word `w` such that @@ -625,15 +625,13 @@ def FixedPointOfMorphism(self, morphism, first_letter): INPUT: - - ``morphism`` -- endomorphism prolongable on ``first_letter``. It - must be something that WordMorphism's constructor understands - (dict, str, ...). + - ``morphism`` -- endomorphism prolongable on ``first_letter``. It + must be something that WordMorphism's constructor understands + (dict, str, ...). - - ``first_letter`` -- the first letter of the fixed point + - ``first_letter`` -- the first letter of the fixed point - OUTPUT: - - The fixed point of the morphism beginning with ``first_letter`` + OUTPUT: the fixed point of the morphism beginning with ``first_letter`` EXAMPLES:: @@ -663,7 +661,7 @@ def FixedPointOfMorphism(self, morphism, first_letter): def CodingOfRotationWord(self, alpha, beta, x=0, alphabet=(0,1)): r""" - Returns the infinite word obtained from the coding of rotation of + Return the infinite word obtained from the coding of rotation of parameters `(\alpha,\beta, x)` over the given two-letter alphabet. The *coding of rotation* corresponding to the parameters @@ -725,7 +723,7 @@ def _CodingOfRotationWord_function(self, n, alpha, beta, x=0, alphabet=(0,1)): @rename_keyword(cf='slope') def CharacteristicSturmianWord(self, slope, alphabet=(0, 1), bits=None): r""" - Returns the characteristic Sturmian word (also called standard + Return the characteristic Sturmian word (also called standard Sturmian word) of given slope. Over a binary alphabet `\{a,b\}`, the characteristic Sturmian @@ -746,23 +744,22 @@ def CharacteristicSturmianWord(self, slope, alphabet=(0, 1), bits=None): INPUT: - - ``slope`` -- the slope of the word. It can be one of the following: - - - real number in `]0, 1[` + - ``slope`` -- the slope of the word. It can be one of the following: - - iterable over the continued fraction expansion of a real - number in `]0, 1[` + - real number in `]0, 1[` - - ``alphabet`` -- any container of length two that is suitable to - build an instance of OrderedAlphabet (list, tuple, str, ...) + - iterable over the continued fraction expansion of a real + number in `]0, 1[` - - ``bits`` -- integer (optional and considered only if ``slope`` is - a real number) the number of bits to consider when computing the - continued fraction. + - ``alphabet`` -- any container of length two that is suitable to + build an instance of OrderedAlphabet (``list``, ``tuple``, ``str``, + ...) - OUTPUT: + - ``bits`` -- integer (optional and considered only if ``slope`` is + a real number); the number of bits to consider when computing the + continued fraction - word + OUTPUT: word ALGORITHM: @@ -906,19 +903,17 @@ def CharacteristicSturmianWord(self, slope, alphabet=(0, 1), bits=None): def _CharacteristicSturmianWord_LetterIterator(self, cf, alphabet=(0,1)): r""" - Returns an iterator over the symbols of the characteristic + Return an iterator over the symbols of the characteristic Sturmian word of slope ``cf``. INPUT: - ``cf`` -- iterator, the continued fraction expansion of a real - number in `]0, 1[`. + number in `]0, 1[` - ``alphabet`` -- the alphabet (default: ``(0,1)``) of the output - OUTPUT: - - iterator of letters + OUTPUT: iterator of letters ALGORITHM: @@ -974,7 +969,7 @@ def _CharacteristicSturmianWord_LetterIterator(self, cf, alphabet=(0,1)): def KolakoskiWord(self, alphabet=(1,2)): r""" - Returns the Kolakoski word over the given alphabet and + Return the Kolakoski word over the given alphabet and starting with the first letter of the alphabet. Let `A = \{a,b\}` be an alphabet, where `a` and `b` are two @@ -993,12 +988,10 @@ def KolakoskiWord(self, alphabet=(1,2)): INPUT: - - ``alphabet`` -- (default: (1,2)) an iterable of two positive - integers + - ``alphabet`` -- (default: (1,2)) an iterable of two positive + integers - OUTPUT: - - infinite word + OUTPUT: infinite word EXAMPLES: @@ -1055,7 +1048,7 @@ def KolakoskiWord(self, alphabet=(1,2)): def _KolakoskiWord_iterator(self, a=1, b=2): r""" - Returns an iterator over the Kolakoski word over ``{a,b}`` + Return an iterator over the Kolakoski word over ``{a,b}`` and starting with ``a``. Let `A = \{a,b\}` be an alphabet, where `a` and `b` are two @@ -1071,14 +1064,12 @@ def _KolakoskiWord_iterator(self, a=1, b=2): INPUT: - - ``a`` -- positive integer (default: 1), the first letter occurring - in the returned Kolakoski word. - - ``b`` -- positive integer (default: 2), the second and last letter - occurring in the returned Kolakoski word. + - ``a`` -- positive integer (default: 1); the first letter occurring + in the returned Kolakoski word + - ``b`` -- positive integer (default: 2); the second and last letter + occurring in the returned Kolakoski word - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES: @@ -1113,7 +1104,7 @@ def _KolakoskiWord_iterator(self, a=1, b=2): def LowerMechanicalWord(self, alpha, rho=0, alphabet=None): r""" - Returns the lower mechanical word with slope `\alpha` and + Return the lower mechanical word with slope `\alpha` and intercept `\rho` The lower mechanical word `s_{\alpha,\rho}` with @@ -1130,9 +1121,7 @@ def LowerMechanicalWord(self, alpha, rho=0, alphabet=None): - ``alphabet`` -- iterable of two elements or ``None`` (default: ``None``) - OUTPUT: - - infinite word + OUTPUT: infinite word EXAMPLES:: @@ -1173,7 +1162,7 @@ def LowerMechanicalWord(self, alpha, rho=0, alphabet=None): def UpperMechanicalWord(self, alpha, rho=0, alphabet=None): r""" - Returns the upper mechanical word with slope `\alpha` and + Return the upper mechanical word with slope `\alpha` and intercept `\rho` The upper mechanical word `s'_{\alpha,\rho}` with @@ -1190,9 +1179,7 @@ def UpperMechanicalWord(self, alpha, rho=0, alphabet=None): - ``alphabet`` -- iterable of two elements or ``None`` (default: ``None``) - OUTPUT: - - infinite word + OUTPUT: infinite word EXAMPLES:: @@ -1233,7 +1220,7 @@ def UpperMechanicalWord(self, alpha, rho=0, alphabet=None): def StandardEpisturmianWord(self, directive_word): r""" - Returns the standard episturmian word (or epistandard word) directed by + Return the standard episturmian word (or epistandard word) directed by directive_word. Over a 2-letter alphabet, this function gives characteristic Sturmian words. @@ -1251,8 +1238,8 @@ def StandardEpisturmianWord(self, directive_word): INPUT: - - ``directive_word`` -- an infinite word or a period of a periodic - infinite word + - ``directive_word`` -- an infinite word or a period of a periodic + infinite word EXAMPLES:: @@ -1297,9 +1284,9 @@ def _StandardEpisturmianWord_LetterIterator(self, directive_word): INPUT: - - ``directive_word`` -- an infinite word or a finite word. If - directive_word is finite, then it is repeated to give - an infinite word. + - ``directive_word`` -- an infinite word or a finite word; if + directive_word is finite, then it is repeated to give + an infinite word TESTS:: @@ -1333,9 +1320,7 @@ def MinimalSmoothPrefix(self, n): - ``n`` -- the desired length of the prefix - OUTPUT: - - word -- the prefix + OUTPUT: word; the prefix .. NOTE:: @@ -1369,11 +1354,11 @@ def RandomWord(self, n, m=2, alphabet=None): INPUT: - - ``n`` -- integer, the length of the word - - ``m`` -- integer (default 2), the size of the output alphabet - - ``alphabet`` -- (default is `\{0,1,...,m-1\}`) any container of - length m that is suitable to build an instance of - OrderedAlphabet (list, tuple, str, ...) + - ``n`` -- integer; the length of the word + - ``m`` -- integer (default: 2); the size of the output alphabet + - ``alphabet`` -- (default: `\{0,1,...,m-1\}`) any container of + length m that is suitable to build an instance of + OrderedAlphabet (``list``, ``tuple``, ``str``, ...) EXAMPLES:: @@ -1409,8 +1394,8 @@ def RandomWord(self, n, m=2, alphabet=None): def UpperChristoffelWord(self, p, q, alphabet=(0,1)): r""" - Returns the upper Christoffel word of slope `p/q`, where - `p` and `q` are relatively prime non-negative + Return the upper Christoffel word of slope `p/q`, where + `p` and `q` are relatively prime nonnegative integers, over the given alphabet. The *upper Christoffel word of slope `p/q`* is equal to the @@ -1422,9 +1407,8 @@ def UpperChristoffelWord(self, p, q, alphabet=(0,1)): INPUT: - - ``alphabet`` -- any container of length two that is - suitable to build an instance of OrderedAlphabet (list, tuple, str, - ...) + - ``alphabet`` -- any container of length two that is suitable to build + an instance of OrderedAlphabet (``list``, ``tuple``, ``str``, ...) EXAMPLES:: @@ -1459,7 +1443,7 @@ def UpperChristoffelWord(self, p, q, alphabet=(0,1)): @cached_method def _fibonacci_tile(self, n, q_0=None, q_1=3): r""" - Returns the word `q_n` defined by the recurrence below. + Return the word `q_n` defined by the recurrence below. The sequence `(q_n)_{n\in\NN}` is defined by `q_0=\varepsilon`, `q_1=3` and @@ -1475,11 +1459,11 @@ def _fibonacci_tile(self, n, q_0=None, q_1=3): INPUT: - - ``n`` -- non negative integer - - ``q_0`` -- first initial value (default: None) It can be None, 0, 1, - 2 or 3. - - ``q_1`` -- second initial value (default: 3) It can be None, 0, 1, 2 - or 3. + - ``n`` -- nonnegative integer + - ``q_0`` -- first initial value (default: ``None``); it can be + ``None``, 0, 1, 2 or 3 + - ``q_1`` -- second initial value (default: 3); it can be ``None``, 0, + 1, 2 or 3 EXAMPLES:: @@ -1519,7 +1503,7 @@ def _fibonacci_tile(self, n, q_0=None, q_1=3): def fibonacci_tile(self, n): r""" - Returns the `n`-th Fibonacci Tile [BmBGL09]_. + Return the `n`-th Fibonacci Tile [BmBGL09]_. EXAMPLES:: @@ -1537,7 +1521,7 @@ def fibonacci_tile(self, n): def dual_fibonacci_tile(self, n): r""" - Returns the `n`-th dual Fibonacci Tile [BmBGL09]_. + Return the `n`-th dual Fibonacci Tile [BmBGL09]_. EXAMPLES:: @@ -1556,7 +1540,7 @@ def dual_fibonacci_tile(self, n): def _s_adic_iterator(self, sequence, letters): r""" - Returns the iterator over the `s`-adic infinite word obtained from a + Return the iterator over the `s`-adic infinite word obtained from a sequence of morphisms applied on letters where the hypothesis of nested prefixes is used. @@ -1577,15 +1561,13 @@ def _s_adic_iterator(self, sequence, letters): INPUT: - - ``sequence`` -- An iterable sequence of morphisms. It may be finite - or infinite. - - ``letters`` -- An iterable sequence of letters. The image of the + - ``sequence`` -- an iterable sequence of morphisms. It may be finite + or infinite + - ``letters`` -- an iterable sequence of letters. The image of the (i+1)-th letter under the (i+1)-th morphism must start with the i-th - letter. + letter - OUTPUT: - - iterator of letters + OUTPUT: iterator of letters EXAMPLES: @@ -1660,7 +1642,7 @@ def _s_adic_iterator(self, sequence, letters): def s_adic(self, sequence, letters, morphisms=None): r""" - Returns the `s`-adic infinite word obtained from a sequence of + Return the `s`-adic infinite word obtained from a sequence of morphisms applied on a letter. DEFINITION (from [Fogg]_): @@ -1680,20 +1662,18 @@ def s_adic(self, sequence, letters, morphisms=None): INPUT: - - ``sequence`` -- An iterable sequence of indices or of morphisms. It + - ``sequence`` -- an iterable sequence of indices or of morphisms. It may be finite or infinite. If ``sequence`` is infinite, the image of the `(i+1)`-th letter under the `(i+1)`-th morphism must start with the `i`-th letter. - - ``letters`` -- A letter or a sequence of letters. + - ``letters`` -- a letter or a sequence of letters - ``morphisms`` -- dict, list, callable or ``None`` (default: ``None``) an object that maps indices to morphisms. If ``None``, then ``sequence`` must consist of morphisms. - OUTPUT: - - A word. + OUTPUT: a word EXAMPLES: @@ -1932,11 +1912,9 @@ def PalindromicDefectWord(self, k=1, alphabet='ab'): - ``k`` -- positive integer (default: 1) - - ``alphabet`` -- iterable (default: ``'ab'``) of size two - - OUTPUT: + - ``alphabet`` -- iterable of size two (default: ``'ab'``) - finite word + OUTPUT: finite word EXAMPLES:: @@ -1984,7 +1962,7 @@ def PalindromicDefectWord(self, k=1, alphabet='ab'): def BaumSweetWord(self): r""" - Returns the Baum-Sweet Word. + Return the Baum-Sweet Word. The Baum-Sweet Sequence is an infinite word over the alphabet `\{0,1\}` defined by the following string substitution rules: @@ -2019,7 +1997,7 @@ def BaumSweetWord(self): .. MATH:: b_n = \begin{cases} - 1, & \text{if the binary representation of} n \text{ contains no block of consecutive 0's of odd length}\\ + 1, & \text{if the binary representation of} n \text{ contains no block of consecutive 0s of odd length}\\ 0, & \text{otherwise}\\ \end{cases}\\ diff --git a/src/sage/combinat/words/word_infinite_datatypes.py b/src/sage/combinat/words/word_infinite_datatypes.py index a78d461d078..d36b3f80976 100644 --- a/src/sage/combinat/words/word_infinite_datatypes.py +++ b/src/sage/combinat/words/word_infinite_datatypes.py @@ -27,8 +27,8 @@ def __init__(self, parent, callable, length=None): INPUT: - ``parent`` -- a parent - - ``callable`` -- a callable defined on ``range(stop=length)`` - - ``length`` -- (default: ``None``) nonnegative integer or ``None`` + - ``callable`` -- a callable defined on ``range(stop=length)`` + - ``length`` -- (default: ``None``) nonnegative integer or ``None`` EXAMPLES:: @@ -323,8 +323,8 @@ def __init__(self, parent, callable, length=None): INPUT: - ``parent`` -- a parent - - ``callable`` -- a callable defined on ``range(stop=length)`` - - ``length`` -- (default: ``None``) nonnegative integer or ``None`` + - ``callable`` -- a callable defined on ``range(stop=length)`` + - ``length`` -- (default: ``None``) nonnegative integer or ``None`` EXAMPLES:: @@ -545,7 +545,6 @@ def __reduce__(self): sage: w = Word(range(5)) + Word('abcde') sage: w.__reduce__() (Finite words over Set of Python objects of class 'object', ([0, 1, 2, 3, 4, 'a', 'b', 'c', 'd', 'e'],)) - """ from sage.misc.fpickle import pickle_function try: @@ -590,12 +589,12 @@ def __init__(self, parent, iter, length=None): INPUT: - ``parent`` -- a parent - - ``iter`` -- an iterator - - ``length`` -- (default: ``None``) the length of the word + - ``iter`` -- an iterator + - ``length`` -- (default: ``None``) the length of the word EXAMPLES:: - sage: w = Word(iter("abbabaab"), length="unknown", caching=False); w + sage: w = Word(iter("abbabaab"), length='unknown', caching=False); w word: abbabaab sage: isinstance(w, sage.combinat.words.word_infinite_datatypes.WordDatatype_iter) True @@ -604,14 +603,14 @@ def __init__(self, parent, iter, length=None): sage: w.length() 8 sage: s = "abbabaabbaababbabaababbaabbabaabbaababbaabbabaabab" - sage: w = Word(iter(s), length="unknown", caching=False); w + sage: w = Word(iter(s), length='unknown', caching=False); w word: abbabaabbaababbabaababbaabbabaabbaababba... sage: w.length() is None True :: - sage: w = Word(iter("abbabaab"), length="finite", caching=False); w + sage: w = Word(iter("abbabaab"), length='finite', caching=False); w word: abbabaab sage: isinstance(w, sage.combinat.words.word_infinite_datatypes.WordDatatype_iter) True @@ -668,7 +667,7 @@ def __getitem__(self, key): A word from an iterator without a length specified:: - sage: w = Word(iter("abbabaabbaab"), length="finite", caching=False); w + sage: w = Word(iter("abbabaabbaab"), length='finite', caching=False); w word: abbabaabbaab Test getitems with indexes:: @@ -923,19 +922,19 @@ def __init__(self, parent, iter, length=None): INPUT: - ``parent`` -- a parent - - ``iter`` -- an iterator - - ``length`` -- (default: ``None``) the length of the word + - ``iter`` -- an iterator + - ``length`` -- (default: ``None``) the length of the word EXAMPLES:: sage: import itertools sage: Word(itertools.cycle("abbabaab")) word: abbabaababbabaababbabaababbabaababbabaab... - sage: w = Word(iter("abbabaab"), length="finite"); w + sage: w = Word(iter("abbabaab"), length='finite'); w word: abbabaab sage: w.length() 8 - sage: w = Word(iter("abbabaab"), length="unknown"); w + sage: w = Word(iter("abbabaab"), length='unknown'); w word: abbabaab sage: w.length() 8 @@ -990,7 +989,7 @@ def __getitem__(self, key): A word from an iterator without a length specified:: - sage: w = Word(iter("abbabaabbaab"), length="unknown"); w + sage: w = Word(iter("abbabaabbaab"), length='unknown'); w word: abbabaabbaab Test getitems with indexes:: @@ -1015,50 +1014,50 @@ def __getitem__(self, key): Suffixes:: - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[0:] word: abbabaabbaab - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[1:] word: bbabaabbaab Prefixes:: - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[:0] word: - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[:5] word: abbab With positive steps:: - sage: w = Word(iter("abbabaabbaab"), length="unknown") + sage: w = Word(iter("abbabaabbaab"), length='unknown') sage: w[::2] word: abbaba With a negative start position, the word must be expanded! :: - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[-2:] word: ab - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[-20:] word: abbabaabbaab With a negative stop position, the word must be expanded! :: - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[:-1] word: abbabaabbaa - sage: w = Word(iter("abbabaabbaab"), length="unknown") + sage: w = Word(iter("abbabaabbaab"), length='unknown') sage: w[:-10] word: ab With a negative step, the word may or may not be expanded; it depends on the slice:: - sage: w = Word(iter("abbabaabbaab"), length="finite") + sage: w = Word(iter("abbabaabbaab"), length='finite') sage: w[::-2] word: babaab sage: w = Word(iter("abbabaabbaab")) diff --git a/src/sage/combinat/words/word_options.py b/src/sage/combinat/words/word_options.py index 28ab578b791..44bc5ea071e 100644 --- a/src/sage/combinat/words/word_options.py +++ b/src/sage/combinat/words/word_options.py @@ -24,21 +24,21 @@ def WordOptions(**kwargs): """ - Sets the global options for elements of the word class. + Set the global options for elements of the word class. The defaults are for words to be displayed in list notation. INPUT: - - ``display`` -- 'string' (default), or 'list', words are displayed in - string or list notation. - - ``truncate`` -- boolean (default: ``True``), whether to truncate the string - output of long words (see truncate_length below). - - ``truncate_length`` -- integer (default: 40), if the length of the word - is greater than this integer, then the word is truncated. - - ``letter_separator`` -- (string, default: ",") if the string - representation of letters have length greater than 1, then - the letters are separated by this string in the string - representation of the word. + - ``display`` -- 'string' (default), or 'list', words are displayed in + string or list notation + - ``truncate`` -- boolean (default: ``True``); whether to truncate the string + output of long words (see truncate_length below) + - ``truncate_length`` -- integer (default: 40); if the length of the word + is greater than this integer, then the word is truncated + - ``letter_separator`` -- string (default: ``','``); if the string + representation of letters have length greater than 1, then + the letters are separated by this string in the string + representation of the word If no parameters are set, then the function returns a copy of the options dictionary. @@ -68,7 +68,7 @@ def WordOptions(**kwargs): word_options['display'] = kwargs['display'] elif 'truncate' in kwargs: if not isinstance(kwargs['truncate'], bool): - raise ValueError("truncate must be True or False") + raise ValueError("truncate must be ``True`` or False") else: word_options['truncate'] = kwargs['truncate'] elif 'truncate_length' in kwargs: @@ -88,11 +88,11 @@ def WordOptions(**kwargs): word_options['identifier'] = kwargs['identifier'] elif 'cache' in kwargs: if not isinstance(kwargs['cache'], bool): - raise ValueError("cache must be True or False") + raise ValueError("cache must be ``True`` or False") else: word_options['cache'] = kwargs['cache'] elif 'old_repr' in kwargs: if not isinstance(kwargs['old_repr'], bool): - raise ValueError("old_repr must be True or False") + raise ValueError("old_repr must be ``True`` or False") else: word_options['old_repr'] = kwargs['old_repr'] diff --git a/src/sage/combinat/words/words.py b/src/sage/combinat/words/words.py index 426fcc73b56..c230c90057d 100644 --- a/src/sage/combinat/words/words.py +++ b/src/sage/combinat/words/words.py @@ -61,7 +61,7 @@ def Words(alphabet=None, length=None, finite=True, infinite=True): """ - Returns the combinatorial class of words of length k over an alphabet. + Return the combinatorial class of words of length k over an alphabet. EXAMPLES:: @@ -114,7 +114,7 @@ def Words(alphabet=None, length=None, finite=True, infinite=True): class AbstractLanguage(Parent): r""" - Abstract base class + Abstract base class. This is *not* to be used by any means. This class gather previous features of set of words (prior to :issue:`19619`). In the future that class might @@ -192,7 +192,7 @@ def alphabet(self): def identity_morphism(self): r""" - Returns the identity morphism from self to itself. + Return the identity morphism from ``self`` to itself. EXAMPLES:: @@ -229,7 +229,7 @@ def _check(self, w, length=40): - ``w`` -- word - - ``length`` -- integer (default: ``40``) + - ``length`` -- integer (default: `40`) EXAMPLES:: @@ -383,10 +383,10 @@ def factors(self): @lazy_attribute def _element_classes(self): r""" - Returns a dictionary that gives the class of the element of self. + Return a dictionary that gives the class of the element of ``self``. The word may be finite, infinite or of unknown length. - Its data may be str, list, tuple, a callable or an iterable. + Its data may be string, list, tuple, a callable or an iterable. For callable and iterable, the data may be cached. EXAMPLES: @@ -445,7 +445,7 @@ def _word_from_word(self, data): INPUT: - - ``data`` -- word + - ``data`` -- word EXAMPLES:: @@ -508,10 +508,10 @@ def _word_from_callable(self, data, length, caching=True): INPUT: - - ``data`` -- callable - - ``length`` -- integer or ``None`` or "infinite" or ``Infinity`` - - ``caching`` -- (default: ``True``) True or False. Whether to keep a cache - of the letters computed by the callable. + - ``data`` -- callable + - ``length`` -- integer or ``None`` or ``'infinite'`` or ``Infinity`` + - ``caching`` -- boolean (default: ``True``); whether to keep a cache + of the letters computed by the callable EXAMPLES:: @@ -533,12 +533,12 @@ def _word_from_iter(self, data, length=None, caching=True): INPUT: - - ``data`` -- iterable + - ``data`` -- iterable - - ``length`` -- (optional) integer + - ``length`` -- (optional) integer - - ``caching`` -- (default: ``True``) True or False. Whether to keep a cache - of the letters computed by the iterator. + - ``caching`` -- boolean (default: ``True``); whether to keep a cache + of the letters computed by the iterator EXAMPLES:: @@ -557,28 +557,28 @@ def _word_from_iter(self, data, length=None, caching=True): def __call__(self, data=None, length=None, datatype=None, caching=True, check=True): r""" - Construct a new word object with parent self. + Construct a new word object with parent ``self``. INPUT: - - ``data`` -- (default: None) list, string, tuple, iterator, None - (shorthand for []), or a callable defined on [0,1,...,length]. + - ``data`` -- (default: ``None``) list, string, tuple, iterator, ``None`` + (shorthand for []), or a callable defined on [0,1,...,length] - - ``length`` -- integer (default: None). Only used if the data is an iterator or - a callable. It determines the length of the word. + - ``length`` -- integer (default: ``None``); only used if the data is + an iterator or a callable. It determines the length of the word - - ``datatype`` -- (default: None) None, "char", "list", "str", - "tuple", "iter", "callable" or "pickled_function". If None, then - the function tries to guess this from the data. + - ``datatype`` -- (default: ``None``) ``None``, "char", "list", "str", + "tuple", "iter", "callable" or "pickled_function"; if ``None``, then + the function tries to guess this from the data - - ``caching`` -- (default: ``True``) True or False. Whether to keep a cache - of the letters computed by an iterator or callable. + - ``caching`` -- boolean (default: ``True``); whether to keep a cache + of the letters computed by an iterator or callable - - ``check`` -- (default: ``True``) True or False. Whether to check if - the 40 first letters are in the parent alphabet. This is a - check done to test for small programming errors. Since we also - support infinite words, we cannot really implement a more - accurate check. + - ``check`` -- boolean (default: ``True``); whether to check if + the 40 first letters are in the parent alphabet. This is a + check done to test for small programming errors. Since we also + support infinite words, we cannot really implement a more + accurate check. .. NOTE:: @@ -610,9 +610,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr Word with string constructed from other types:: - sage: W([0,1,1,0,1,0,0,1], datatype="str") + sage: W([0,1,1,0,1,0,0,1], datatype='str') word: 01101001 - sage: W((0,1,1,0,1,0,0,1), datatype="str") + sage: W((0,1,1,0,1,0,0,1), datatype='str') word: 01101001 Word with list:: @@ -622,9 +622,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr Word with list constructed from other types:: - sage: W("01101001", datatype="list") + sage: W("01101001", datatype='list') word: 01101001 - sage: W((0,1,1,0,1,0,0,1), datatype="list") + sage: W((0,1,1,0,1,0,0,1), datatype='list') word: 01101001 Word with tuple:: @@ -634,9 +634,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr Word with tuple constructed from other types:: - sage: W([0,1,1,0,1,0,0,1], datatype="tuple") + sage: W([0,1,1,0,1,0,0,1], datatype='tuple') word: 01101001 - sage: W("01101001", datatype="str") + sage: W("01101001", datatype='str') word: 01101001 Word with iterator:: @@ -860,7 +860,7 @@ def _repr_(self): def _an_element_(self): r""" - Return an element of self. + Return an element of ``self``. EXAMPLES:: @@ -886,11 +886,11 @@ def _an_element_(self): def iterate_by_length(self, l=1): r""" - Returns an iterator over all the words of self of length l. + Return an iterator over all the words of ``self`` of length `l`. INPUT: - - ``l`` -- integer (default: 1), the length of the desired words + - ``l`` -- integer (default: 1); the length of the desired words EXAMPLES:: @@ -921,7 +921,7 @@ def iterate_by_length(self, l=1): def __iter__(self): r""" - Returns an iterator over all the words of self. + Return an iterator over all the words of ``self``. The iterator outputs the words in shortlex order (see :wikipedia:`Shortlex_order`), i.e. first by increasing length and then @@ -963,7 +963,7 @@ def __iter__(self): def __contains__(self, x): """ - Tests whether ``self`` contains ``x``. + Test whether ``self`` contains ``x``. OUTPUT: @@ -992,12 +992,12 @@ def __contains__(self, x): def random_element(self, length=None, *args, **kwds): r""" - Returns a random finite word on the given alphabet. + Return a random finite word on the given alphabet. INPUT: - - ``length`` -- (optional) the length of the word. If not set, will use - a uniformly random number between 0 and 10. + - ``length`` -- (optional) the length of the word; if not set, will use + a uniformly random number between 0 and 10 - all other argument are transmitted to the random generator of the alphabet @@ -1030,30 +1030,28 @@ def iter_morphisms(self, arg=None, codomain=None, min_length=1): INPUT: - - ``arg`` -- (default: ``None``) It can be one of the following: + - ``arg`` -- (default: ``None``) it can be one of the following: - - ``None`` -- then the method iterates through all morphisms. + - ``None`` -- then the method iterates through all morphisms - - tuple `(a, b)` of two integers -- It specifies the range + - tuple `(a, b)` of two integers -- it specifies the range ``range(a, b)`` of values to consider for the sum of the length - of the image of each letter in the alphabet. + of the image of each letter in the alphabet - - list of nonnegative integers -- The length of the list must be - equal to the size of the alphabet, and the i-th integer of - ``arg`` determines the length of the word mapped to by the i-th - letter of the (ordered) alphabet. + - list of nonnegative integers -- the length of the list must be + equal to the size of the alphabet, and the `i`-th integer of + ``arg`` determines the length of the word mapped to by the `i`-th + letter of the (ordered) alphabet - - ``codomain`` -- (default: ``None``) a combinatorial class of words. - By default, ``codomain`` is ``self``. + - ``codomain`` -- (default: ``None``) a combinatorial class of words; + by default, ``codomain`` is ``self`` - - ``min_length`` -- (default: 1) nonnegative integer. If ``arg`` is + - ``min_length`` -- nonnegative integer (default: 1); if ``arg`` is not specified, then iterate through all the morphisms where the length of the images of each letter in the alphabet is at least ``min_length``. This is ignored if ``arg`` is a list. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES: @@ -1216,7 +1214,6 @@ def iter_morphisms(self, arg=None, codomain=None, min_length=1): Traceback (most recent call last): ... TypeError: codomain (=a) must be an instance of FiniteWords - """ n = self.alphabet().cardinality() if min_length < 0: @@ -1266,7 +1263,7 @@ def iter_morphisms(self, arg=None, codomain=None, min_length=1): class InfiniteWords(AbstractLanguage): def cardinality(self): r""" - Return the cardinality of this set + Return the cardinality of this set. EXAMPLES:: @@ -1319,10 +1316,10 @@ def shift(self): @lazy_attribute def _element_classes(self): r""" - Returns a dictionary that gives the class of the element of self. + Return a dictionary that gives the class of the element of ``self``. The word may be finite, infinite or of unknown length. - Its data may be str, list, tuple, a callable or an iterable. + Its data may be string, list, tuple, a callable or an iterable. For callable and iterable, the data may be cached. EXAMPLES: @@ -1384,7 +1381,7 @@ def _word_from_word(self, data): INPUT: - - ``data`` -- word + - ``data`` -- word EXAMPLES:: @@ -1430,10 +1427,10 @@ def _word_from_callable(self, data, caching=True): INPUT: - - ``data`` -- callable + - ``data`` -- callable - - ``caching`` -- (default: ``True``) True or False. Whether to keep a cache - of the letters computed by the callable. + - ``caching`` -- boolean (default: ``True``); whether to keep a cache + of the letters computed by the callable EXAMPLES:: @@ -1453,10 +1450,10 @@ def _word_from_iter(self, data, caching=True): INPUT: - - ``data`` -- iterable + - ``data`` -- iterable - - ``caching`` -- (default: ``True``) True or False. Whether to keep a cache - of the letters computed by the iterator. + - ``caching`` -- boolean (default: ``True``); whether to keep a cache + of the letters computed by the iterator EXAMPLES:: @@ -1470,24 +1467,24 @@ def _word_from_iter(self, data, caching=True): def __call__(self, data=None, datatype=None, caching=True, check=True): r""" - Construct a new word object with parent self. + Construct a new word object with parent ``self``. INPUT: - - ``data`` -- iterator or a callable + - ``data`` -- iterator or a callable - - ``datatype`` -- (default: None) None, "iter", "callable" or - "pickled_function". If None, then the function tries to guess - this from the data. + - ``datatype`` -- (default: ``None``) ``None``, "iter", "callable" or + "pickled_function"; if ``None``, then the function tries to guess + this from the data - - ``caching`` -- (default: ``True``) True or False. Whether to keep a - cache of the letters computed by an iterator or callable. + - ``caching`` -- boolean (default: ``True``); whether to keep a + cache of the letters computed by an iterator or callable - - ``check`` -- (default: ``True``) True or False. Whether to check if - the 40 first letters are in the parent alphabet. This is a - check done to test for small programming errors. Since we also - support infinite words, we cannot really implement a more - accurate check. + - ``check`` -- boolean (default: ``True``); whether to check if + the 40 first letters are in the parent alphabet. This is a + check done to test for small programming errors. Since we also + support infinite words, we cannot really implement a more + accurate check. .. NOTE:: @@ -1575,7 +1572,7 @@ def __call__(self, data=None, datatype=None, caching=True, check=True): def _repr_(self): r""" - Returns a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -1586,7 +1583,7 @@ def _repr_(self): def _an_element_(self): r""" - Return an element of self. + Return an element of ``self``. EXAMPLES:: @@ -1771,35 +1768,35 @@ def _word_from_iter(self, data, caching=True): def __call__(self, data=None, length=None, datatype=None, caching=True, check=True): r""" - Construct a new word object with parent self. + Construct a new word object with parent ``self``. INPUT: - - ``data`` -- (default: None) list, string, tuple, iterator, None - (shorthand for []), or a callable defined on [0,1,...,length]. + - ``data`` -- (default: ``None``) list, string, tuple, iterator, ``None`` + (shorthand for []), or a callable defined on [0,1,...,length] - - ``length`` -- (default: None) This is dependent on the type of data. - It is ignored for words defined by lists, strings, tuples, - etc., because they have a naturally defined length. - For callables, this defines the domain of definition, - which is assumed to be [0, 1, 2, ..., length-1]. - For iterators: Infinity if you know the iterator will not - terminate (default); "unknown" if you do not know whether the - iterator terminates; "finite" if you know that the iterator - terminates, but do not know the length. + - ``length`` -- (default: ``None``) this is dependent on the type of data. + It is ignored for words defined by lists, strings, tuples, + etc., because they have a naturally defined length. + For callables, this defines the domain of definition, + which is assumed to be [0, 1, 2, ..., length-1]. + For iterators: Infinity if you know the iterator will not + terminate (default); ``'unknown'`` if you do not know whether the + iterator terminates; ``'finite'`` if you know that the iterator + terminates, but do not know the length. - - ``datatype`` -- (default: None) None, "char", "list", "str", - "tuple", "iter", "callable" or "pickled_function". If None, then - the function tries to guess this from the data. + - ``datatype`` -- (default: ``None``) ``None``, "char", "list", "str", + "tuple", "iter", "callable" or "pickled_function"; if ``None``, then + the function tries to guess this from the data. - - ``caching`` -- (default: ``True``) True or False. Whether to keep a cache - of the letters computed by an iterator or callable. + - ``caching`` -- boolean (default: ``True``); whether to keep a cache + of the letters computed by an iterator or callable - - ``check`` -- (default: ``True``) True or False. Whether to check if - the 40 first letters are in the parent alphabet. This is a - check done to test for small programming errors. Since we also - support infinite words, we cannot really implement a more - accurate check. + - ``check`` -- boolean (default: ``True``); whether to check if + the 40 first letters are in the parent alphabet. This is a + check done to test for small programming errors. Since we also + support infinite words, we cannot really implement a more + accurate check. .. NOTE:: @@ -1829,9 +1826,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr Word with string constructed from other types:: - sage: Words()([0,1,1,0,1,0,0,1], datatype="str") + sage: Words()([0,1,1,0,1,0,0,1], datatype='str') word: 01101001 - sage: Words()((0,1,1,0,1,0,0,1), datatype="str") + sage: Words()((0,1,1,0,1,0,0,1), datatype='str') word: 01101001 Word with list:: @@ -1841,9 +1838,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr Word with list constructed from other types:: - sage: Words()("01101001", datatype="list") + sage: Words()("01101001", datatype='list') word: 01101001 - sage: Words()((0,1,1,0,1,0,0,1), datatype="list") + sage: Words()((0,1,1,0,1,0,0,1), datatype='list') word: 01101001 Word with tuple:: @@ -1853,9 +1850,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr Word with tuple constructed from other types:: - sage: Words()([0,1,1,0,1,0,0,1], datatype="tuple") + sage: Words()([0,1,1,0,1,0,0,1], datatype='tuple') word: 01101001 - sage: Words()("01101001", datatype="str") + sage: Words()("01101001", datatype='str') word: 01101001 Word with iterator:: @@ -1865,9 +1862,9 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr word: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,... sage: Words()(iter("abbabaab")) # iterators default to infinite words word: abbabaab - sage: Words()(iter("abbabaab"), length="unknown") + sage: Words()(iter("abbabaab"), length='unknown') word: abbabaab - sage: Words()(iter("abbabaab"), length="finite") + sage: Words()(iter("abbabaab"), length='finite') word: abbabaab Word with function (a 'callable'):: @@ -2058,7 +2055,7 @@ def __call__(self, data=None, length=None, datatype=None, caching=True, check=Tr def _repr_(self): r""" - Returns a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -2076,20 +2073,20 @@ def __init__(self, words, n): r""" INPUT: - - ``words`` -- a set of finite words + - ``words`` -- set of finite words - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer TESTS:: sage: Words([0,1], length=-42) Traceback (most recent call last): ... - ValueError: n = -42 must be non-negative + ValueError: n = -42 must be nonnegative """ n = ZZ(n) if n < 0: - raise ValueError("n = {} must be non-negative".format(n)) + raise ValueError("n = {} must be nonnegative".format(n)) self._words = words self._n = n @@ -2152,7 +2149,7 @@ def __call__(self, data, *args, **kwds): def list(self): r""" - Returns a list of all the words contained in self. + Return a list of all the words contained in ``self``. EXAMPLES:: @@ -2171,7 +2168,7 @@ def list(self): def _an_element_(self): r""" - Return an element of self. + Return an element of ``self``. EXAMPLES:: @@ -2262,7 +2259,7 @@ def __contains__(self, x): def cardinality(self): r""" - Returns the number of words of length `n` from alphabet. + Return the number of words of length `n` from alphabet. EXAMPLES:: diff --git a/src/sage/combinat/yang_baxter_graph.py b/src/sage/combinat/yang_baxter_graph.py index 7a79e69c3be..33552e4cc46 100644 --- a/src/sage/combinat/yang_baxter_graph.py +++ b/src/sage/combinat/yang_baxter_graph.py @@ -43,9 +43,7 @@ def YangBaxterGraph(partition=None, root=None, operators=None): tuples of the form `(v, l)` where `v` is a successor of `u` and `l` is the label of the edge from `u` to `v`. - OUTPUT: - - - Either: + OUTPUT: either: - :class:`YangBaxterGraph_partition` -- if partition is defined - :class:`YangBaxterGraph_generic` -- if partition is ``None`` @@ -126,8 +124,8 @@ def __init__(self, root, operators): - ``root`` -- the root vertex of the graph - - ``operators`` -- a list of callables that map vertices to (new) - vertices. + - ``operators`` -- list of callables that map vertices to (new) + vertices .. NOTE:: @@ -413,7 +411,7 @@ def vertices(self, sort=False) -> list: INPUT: - - ``sort`` -- boolean (default ``False``) whether to sort the vertices + - ``sort`` -- boolean (default: ``False``); whether to sort the vertices EXAMPLES:: @@ -456,9 +454,7 @@ def vertex_relabelling_dict(self, v, relabel_operator) -> dict: - ``relabel_operator`` -- function mapping a vertex and a label to the image of the vertex - OUTPUT: - - - dictionary pairing vertices with the corresponding image of ``v`` + OUTPUT: dictionary pairing vertices with the corresponding image of ``v`` EXAMPLES:: @@ -488,10 +484,10 @@ def relabel_vertices(self, v, relabel_operator, inplace=True): INPUT: - - ``v`` -- tuple, Permutation, ... + - ``v`` -- tuple, Permutation, etc. - ``inplace`` -- if ``True``, modifies ``self``; otherwise returns a - modified copy of ``self``. + modified copy of ``self`` EXAMPLES:: @@ -523,7 +519,7 @@ def relabel_edges(self, edge_dict, inplace=True): INPUT: - - ``edge_dict`` -- a dictionary keyed by the (unlabelled) edges. + - ``edge_dict`` -- dictionary keyed by the (unlabelled) edges EXAMPLES:: @@ -678,9 +674,9 @@ def _swap_operator(self, operator, u): INPUT: - - ``i`` -- positive integer between 1 and len(u)-1, inclusive + - ``i`` -- positive integer between ``1`` and ``len(u)-1``, inclusive - - ``u`` -- tuple, list, permutation, .... + - ``u`` -- tuple, list, permutation, etc. EXAMPLES:: @@ -709,9 +705,7 @@ def vertex_relabelling_dict(self, v) -> dict: - ``v`` -- an object - OUTPUT: - - - dictionary pairing vertices with the corresponding image of ``v`` + OUTPUT: dictionary pairing vertices with the corresponding image of ``v`` EXAMPLES:: @@ -735,10 +729,10 @@ def relabel_vertices(self, v, inplace=True): INPUT: - - ``v`` -- tuple, Permutation, ... + - ``v`` -- tuple, Permutation, etc. - ``inplace`` -- if ``True``, modifies ``self``; otherwise - returns a modified copy of ``self``. + returns a modified copy of ``self`` EXAMPLES:: @@ -877,8 +871,8 @@ def __call__(self, u): def position(self): r""" - ``self`` is the operator that swaps positions ``i`` and ``i+1``. This - method returns ``i``. + Return ``i`` where ``self`` is the operator that swaps positions ``i`` + and ``i+1``. EXAMPLES:: @@ -913,7 +907,7 @@ def __call__(self, u): - ``i`` -- positive integer between ``1`` and ``len(u)-1``, inclusive - - ``u`` -- tuple, list, permutation, .... + - ``u`` -- tuple, list, permutation, etc. EXAMPLES:: diff --git a/src/sage/cpython/_py2_random.py b/src/sage/cpython/_py2_random.py index 0da28217eec..a86f66c5ba0 100644 --- a/src/sage/cpython/_py2_random.py +++ b/src/sage/cpython/_py2_random.py @@ -59,7 +59,6 @@ class Random(_random.Random): methods: random(), seed(), getstate(), setstate() and jumpahead(). Optionally, implement a getrandbits() method so that randrange() can cover arbitrarily large ranges. - """ VERSION = 3 # used by getstate/setstate @@ -155,7 +154,6 @@ def randrange(self, start, stop=None, step=1, _int=int, _maxwidth=1 << BPF): This fixes the problem with randint() which includes the endpoint; in Python this is usually not what you want. - """ # This code is a bit messy to make it fast for the @@ -257,7 +255,6 @@ def shuffle(self, x, random=None): Optional arg random is a 0-argument function returning a random float in [0.0, 1.0); by default, the standard random.random. - """ if random is None: @@ -347,7 +344,6 @@ def triangular(self, low=0.0, high=1.0, mode=None): and having a given mode value in-between. http://en.wikipedia.org/wiki/Triangular_distribution - """ u = self.random() try: @@ -366,7 +362,6 @@ def normalvariate(self, mu, sigma): """Normal distribution. mu is the mean, and sigma is the standard deviation. - """ # mu = mean, sigma = standard deviation @@ -393,7 +388,6 @@ def lognormvariate(self, mu, sigma): If you take the natural logarithm of this distribution, you'll get a normal distribution with mean mu and standard deviation sigma. mu can have any value, and sigma must be greater than zero. - """ return _exp(self.normalvariate(mu, sigma)) @@ -407,7 +401,6 @@ def expovariate(self, lambd): a reserved word in Python.) Returned values range from 0 to positive infinity if lambd is positive, and from negative infinity to 0 if lambd is negative. - """ # lambd: rate lambd = 1/mean # ('lambda' is a Python reserved word) @@ -425,7 +418,6 @@ def vonmisesvariate(self, mu, kappa): kappa is the concentration parameter, which must be greater than or equal to zero. If kappa is equal to zero, this distribution reduces to a uniform random angle over the range 0 to 2*pi. - """ # mu: mean angle (in radians between 0 and 2*pi) # kappa: concentration parameter kappa (>= 0) @@ -476,7 +468,6 @@ def gammavariate(self, alpha, beta): x ** (alpha - 1) * math.exp(-x / beta) pdf(x) = -------------------------------------- math.gamma(alpha) * beta ** alpha - """ # alpha > 0, beta > 0, mean is alpha*beta, variance is alpha*beta**2 @@ -545,7 +536,6 @@ def gauss(self, mu, sigma): slightly faster than the normalvariate() function. Not thread-safe without a lock around calls. - """ # When x and y are two variables from [0, 1), uniformly @@ -596,7 +586,6 @@ def betavariate(self, alpha, beta): Conditions on the parameters are alpha > 0 and beta > 0. Returned values range between 0 and 1. - """ # This version due to Janne Sinkkonen, and matches all the std @@ -622,7 +611,6 @@ def weibullvariate(self, alpha, beta): """Weibull distribution. alpha is the scale parameter and beta is the shape parameter. - """ # Jain, pg. 499; bug fix courtesy Bill Arms diff --git a/src/sage/cpython/atexit.pyx b/src/sage/cpython/atexit.pyx index 8bc12e2d2d9..8f833ab1437 100644 --- a/src/sage/cpython/atexit.pyx +++ b/src/sage/cpython/atexit.pyx @@ -25,12 +25,12 @@ cdef class restore_atexit: INPUT: - - ``run`` (bool, default: ``False``) -- if True, when exiting the + - ``run`` -- boolean (default: ``False``); if ``True``, when exiting the context (but before restoring the old exit functions), run all - atexit functions which were added inside the context. + atexit functions which were added inside the context - - ``clear`` (bool, default: equal to ``run``) -- if True, clear - already registered atexit handlers upon entering the context. + - ``clear`` -- boolean (default: equal to ``run``); if ``True``, clear + already registered atexit handlers upon entering the context .. WARNING:: diff --git a/src/sage/cpython/debug.pyx b/src/sage/cpython/debug.pyx index 79aba1a7fbe..f4e0a44046f 100644 --- a/src/sage/cpython/debug.pyx +++ b/src/sage/cpython/debug.pyx @@ -73,7 +73,7 @@ def getattr_debug(obj, name, default=_no_default): - ``obj`` -- the object whose attribute is requested - - ``name`` -- (string) the name of the attribute + - ``name`` -- string; the name of the attribute - ``default`` -- default value to return if attribute was not found @@ -220,7 +220,7 @@ def getattr_debug(obj, name, default=_no_default): def type_debug(cls): """ - Print all internals of the type ``cls`` + Print all internals of the type ``cls``. EXAMPLES:: diff --git a/src/sage/cpython/dict_del_by_value.pyx b/src/sage/cpython/dict_del_by_value.pyx index 44f0700206e..eff4e944ef6 100644 --- a/src/sage/cpython/dict_del_by_value.pyx +++ b/src/sage/cpython/dict_del_by_value.pyx @@ -54,8 +54,8 @@ cdef int del_dictitem_by_exact_value(PyDictObject *mp, PyObject *value, Py_hash_ INPUT: - ``PyDictObject *mp`` -- pointer to a dict - - ``PyObject *value`` -- pointer to a value of the dictionary - - ``Py_hash_t hash`` -- hash of the key by which the value is stored in the dict + - ``PyObject *value`` -- pointer to a value of the dictionary + - ``Py_hash_t hash`` -- hash of the key by which the value is stored in the dict The hash bucket determined by the given hash is searched for the item containing the given value. If this item cannot be found, the function is @@ -143,9 +143,9 @@ def test_del_dictitem_by_exact_value(D, value, h): INPUT: - - ``D`` -- a Python ````. - - ``value`` -- an object that is value ``D``. - - ``h`` -- the hash of the key under which to find ``value`` in ``D``. + - ``D`` -- a Python ```` + - ``value`` -- an object that is value ``D`` + - ``h`` -- the hash of the key under which to find ``value`` in ``D`` The underlying cdef function deletes an item from ``D`` that is in the hash bucket determined by ``h`` and whose value is identic with diff --git a/src/sage/cpython/getattr.pyx b/src/sage/cpython/getattr.pyx index 899fbe62ecc..bebe646037f 100644 --- a/src/sage/cpython/getattr.pyx +++ b/src/sage/cpython/getattr.pyx @@ -38,7 +38,7 @@ cdef extern from "Python.h": cdef class AttributeErrorMessage: """ - Tries to emulate the standard Python :class:`AttributeError` message. + Try to emulate the standard Python :exc:`AttributeError` message. .. NOTE:: @@ -69,7 +69,7 @@ cdef class AttributeErrorMessage: TESTS: - The error message used for the :class:`AttributeError` is a unique object + The error message used for the :exc:`AttributeError` is a unique object and is changed inplace. This is for reasons of efficiency. Hence, if one really needs the error message as a string, then one should make a copy of its string representation before it changes. :: @@ -239,12 +239,12 @@ cpdef getattr_from_other_class(self, cls, name): - ``cls`` -- a new-style class - - ``name`` -- a string + - ``name`` -- string - If self is an instance of cls, raises an :class:`AttributeError`, to + If ``self`` is an instance of cls, raises an :exc:`AttributeError`, to avoid a double lookup. This function is intended to be called from __getattr__, and so should not be called if name is an attribute - of self. + of ``self``. EXAMPLES:: @@ -301,7 +301,7 @@ cpdef getattr_from_other_class(self, cls, name): TypeError: descriptor '__weakref__' for 'A' objects doesn't apply to ...'sage.rings.integer.Integer' object - When this occurs, an :class:`AttributeError` is raised:: + When this occurs, an :exc:`AttributeError` is raised:: sage: getattr_from_other_class(1, A, "__weakref__") Traceback (most recent call last): @@ -368,7 +368,7 @@ cpdef getattr_from_other_class(self, cls, name): # Not a descriptor return attribute # Conditionally defined lazy_attributes don't work well with fake subclasses - # (a :class:`TypeError` is raised if the lazy attribute is not defined). + # (a :exc:`TypeError` is raised if the lazy attribute is not defined). # For the moment, we ignore that when this occurs. # Other descriptors (including __weakref__) also break. try: @@ -382,7 +382,7 @@ cpdef getattr_from_other_class(self, cls, name): def dir_with_other_class(self, *cls): r""" - Emulates ``dir(self)``, as if self was also an instance ``cls``, + Emulates ``dir(self)``, as if ``self`` was also an instance ``cls``, right after ``caller_class`` in the method resolution order (``self.__class__.mro()``) diff --git a/src/sage/cpython/wrapperdescr.pyx b/src/sage/cpython/wrapperdescr.pyx index 1e74353e798..b1b1e67cc79 100644 --- a/src/sage/cpython/wrapperdescr.pyx +++ b/src/sage/cpython/wrapperdescr.pyx @@ -44,13 +44,13 @@ def wrapperdescr_call(slotwrapper, self, *args, **kwds): INPUT: - - ``slotwrapper`` -- a slot wrapper (for example ``int.__add__``). + - ``slotwrapper`` -- a slot wrapper (for example ``int.__add__``) - ``self`` -- the first positional argument. Normally, this should be of the correct type (an ``int`` when calling ``int.__add__``). However, this check is skipped: you can pass an arbitrary object. - - ``*args``, ``**kwds`` -- further arguments. + - ``*args``, ``**kwds`` -- further arguments .. WARNING:: diff --git a/src/sage/crypto/block_cipher/des.py b/src/sage/crypto/block_cipher/des.py index 6799dd8e4c1..182de4a14b3 100644 --- a/src/sage/crypto/block_cipher/des.py +++ b/src/sage/crypto/block_cipher/des.py @@ -346,14 +346,14 @@ def __init__(self, rounds=None, keySchedule='DES_KS', keySize=64, doFinalRound=T INPUT: - - ``rounds`` -- integer (default: ``None``); the number of rounds. If + - ``rounds`` -- integer (default: ``None``); the number of rounds. If ``None`` the number of rounds of the key schedule is used. - - ``keySchedule`` -- (default: ``'DES_KS'``); the key schedule that + - ``keySchedule`` -- (default: ``'DES_KS'``) the key schedule that will be used for encryption and decryption. If ``'DES_KS'`` the default DES key schedule is used. - - ``keySize`` -- (default: ``64``); the key length in bits. Must be + - ``keySize`` -- (default: ``64``) the key length in bits. Must be ``56`` of ``64``. In the latter case the key contains 8 parity bits. - ``doFinalRound`` -- boolean (default: ``True``); if ``False`` a swap @@ -484,7 +484,7 @@ def encrypt(self, plaintext, key): INPUT: - ``plaintext`` -- integer or bit list-like; the plaintext that will be - encrypted. + encrypted - ``key`` -- integer or bit list-like; the key @@ -794,7 +794,7 @@ def __init__(self, rounds=16, masterKey=None): INPUT: - - ``rounds`` -- integer (default: ``16``); the number of rounds + - ``rounds`` -- integer (default: `16`); the number of rounds ``self`` can create keys for - ``masterKey`` -- integer or bit list-like (default: ``None``); the @@ -915,14 +915,14 @@ def __repr__(self): def __getitem__(self, r): r""" - Computes the sub key for round ``r`` derived from initial master key. + Compute the sub key for round ``r`` derived from initial master key. The key schedule object has to have been initialised with the `masterKey` argument. INPUT: - - ``r`` integer; the round for which the sub key is computed + - ``r`` -- integer; the round for which the sub key is computed EXAMPLES:: @@ -1043,9 +1043,7 @@ def convert_to_vector(I, L): - ``L`` -- integer; the desired bit length of the ouput - OUTPUT: - - - the ``L``-bit vector representation of ``I`` + OUTPUT: the ``L``-bit vector representation of ``I`` EXAMPLES:: diff --git a/src/sage/crypto/block_cipher/miniaes.py b/src/sage/crypto/block_cipher/miniaes.py index 6eb9568b9fc..babb4fec8b0 100644 --- a/src/sage/crypto/block_cipher/miniaes.py +++ b/src/sage/crypto/block_cipher/miniaes.py @@ -91,9 +91,9 @@ class MiniAES(SageObject): 0100101101000101 sage: P = bin.encoding("Encrypt this secret message!"); P 01000101011011100110001101110010011110010111000001110100001000000111010001101000011010010111001100100000011100110110010101100011011100100110010101110100001000000110110101100101011100110111001101100001011001110110010100100001 - sage: C = maes(P, key, algorithm="encrypt"); C + sage: C = maes(P, key, algorithm='encrypt'); C 11100000101000010110001101101001110110010010111011010001100111100000101000101111100110010010100001110101011100111001000010101000001111000101010011010001100111100111001100000001101100110110101001001000011100000101010110110101 - sage: plaintxt = maes(C, key, algorithm="decrypt") + sage: plaintxt = maes(C, key, algorithm='decrypt') sage: plaintxt == P True @@ -109,9 +109,9 @@ class MiniAES(SageObject): 0000000100100011010001010110011110001001101010111100110111101111 sage: key = maes.integer_to_binary(key); key 0010001110110000 - sage: C = maes(P, key, algorithm="encrypt"); C + sage: C = maes(P, key, algorithm='encrypt'); C 0011101000101110010011000101010100011101010000111000100100011010 - sage: plaintxt = maes(C, key, algorithm="decrypt") + sage: plaintxt = maes(C, key, algorithm='decrypt') sage: plaintxt == P True @@ -258,7 +258,7 @@ def __init__(self): Integer(14): K("x^3 + x^2 + x"), Integer(15): K("x^3 + x^2 + x+ 1") } - def __call__(self, B, key, algorithm="encrypt"): + def __call__(self, B, key, algorithm='encrypt'): r""" Apply Mini-AES encryption or decryption on the binary string ``B`` using the key ``key``. The flag ``algorithm`` controls what action is @@ -273,10 +273,10 @@ def __call__(self, B, key, algorithm="encrypt"): - ``key`` -- a secret key; this must be a 16-bit binary string - - ``algorithm`` -- (default: ``"encrypt"``) a string; a flag to signify + - ``algorithm`` -- (default: ``'encrypt'``) a string; a flag to signify whether encryption or decryption is to be applied to the binary - string ``B``. The encryption flag is ``"encrypt"`` and the decryption - flag is ``"decrypt"``. + string ``B``. The encryption flag is ``'encrypt'`` and the decryption + flag is ``'decrypt'``. OUTPUT: @@ -292,9 +292,9 @@ def __call__(self, B, key, algorithm="encrypt"): 0100101101000101 sage: P = bin.encoding("Encrypt this secret message!"); P 01000101011011100110001101110010011110010111000001110100001000000111010001101000011010010111001100100000011100110110010101100011011100100110010101110100001000000110110101100101011100110111001101100001011001110110010100100001 - sage: C = maes(P, key, algorithm="encrypt"); C + sage: C = maes(P, key, algorithm='encrypt'); C 11100000101000010110001101101001110110010010111011010001100111100000101000101111100110010010100001110101011100111001000010101000001111000101010011010001100111100111001100000001101100110110101001001000011100000101010110110101 - sage: plaintxt = maes(C, key, algorithm="decrypt") + sage: plaintxt = maes(C, key, algorithm='decrypt') sage: plaintxt == P True @@ -329,20 +329,20 @@ def __call__(self, B, key, algorithm="encrypt"): ... ValueError: secret key must be a 16-bit binary string - The value for ``algorithm`` must be either ``"encrypt"`` or - ``"decrypt"``:: + The value for ``algorithm`` must be either ``'encrypt'`` or + ``'decrypt'``:: sage: B = bin.encoding("ABCD") sage: key = bin.encoding("KE") - sage: maes(B, key, algorithm="ABC") + sage: maes(B, key, algorithm='ABC') Traceback (most recent call last): ... ValueError: algorithm must be either 'encrypt' or 'decrypt' - sage: maes(B, key, algorithm="e") + sage: maes(B, key, algorithm='e') Traceback (most recent call last): ... ValueError: algorithm must be either 'encrypt' or 'decrypt' - sage: maes(B, key, algorithm="d") + sage: maes(B, key, algorithm='d') Traceback (most recent call last): ... ValueError: algorithm must be either 'encrypt' or 'decrypt' @@ -406,7 +406,7 @@ def __eq__(self, other): def __repr__(self): r""" - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -431,9 +431,7 @@ def add_key(self, block, rkey): - ``rkey`` -- a round key; a `2 \times 2` matrix with entries over `\GF{2^4}` - OUTPUT: - - - The matrix addition of ``block`` and ``rkey``. + OUTPUT: the matrix addition of ``block`` and ``rkey`` EXAMPLES: @@ -590,9 +588,7 @@ def decrypt(self, C, key): - ``key`` -- a secret key for this Mini-AES block cipher; must be a `2 \times 2` matrix over the finite field `\GF{2^4}` - OUTPUT: - - - The plaintext corresponding to ``C``. + OUTPUT: the plaintext corresponding to ``C`` EXAMPLES: @@ -723,13 +719,13 @@ def decrypt(self, C, key): # undo the result of round 2 plaintext = self.add_key(C, rkey2) plaintext = self.shift_row(plaintext) - plaintext = self.nibble_sub(plaintext, algorithm="decrypt") + plaintext = self.nibble_sub(plaintext, algorithm='decrypt') # undo the result of round 1 plaintext = self.add_key(plaintext, rkey1) plaintext = self.mix_column(plaintext) plaintext = self.shift_row(plaintext) - plaintext = self.nibble_sub(plaintext, algorithm="decrypt") + plaintext = self.nibble_sub(plaintext, algorithm='decrypt') # undo the result of round 0 plaintext = self.add_key(plaintext, rkey0) @@ -762,9 +758,7 @@ def encrypt(self, P, key): - ``key`` -- a secret key for this Mini-AES block cipher; must be a `2 \times 2` matrix over the finite field `\GF{2^4}` - OUTPUT: - - - The ciphertext corresponding to ``P``. + OUTPUT: the ciphertext corresponding to ``P`` EXAMPLES: @@ -884,13 +878,13 @@ def encrypt(self, P, key): ciphertext = self.add_key(P, rkey0) # round 1 - ciphertext = self.nibble_sub(ciphertext, algorithm="encrypt") + ciphertext = self.nibble_sub(ciphertext, algorithm='encrypt') ciphertext = self.shift_row(ciphertext) ciphertext = self.mix_column(ciphertext) ciphertext = self.add_key(ciphertext, rkey1) # round 2 - ciphertext = self.nibble_sub(ciphertext, algorithm="encrypt") + ciphertext = self.nibble_sub(ciphertext, algorithm='encrypt') ciphertext = self.shift_row(ciphertext) ciphertext = self.add_key(ciphertext, rkey2) @@ -1028,7 +1022,7 @@ def mix_column(self, block): [K("x"), K("x + 1")] ] ) return M * block - def nibble_sub(self, block, algorithm="encrypt"): + def nibble_sub(self, block, algorithm='encrypt'): r""" Substitute a nibble (or a block of 4 bits) using the following S-box: @@ -1108,15 +1102,13 @@ def nibble_sub(self, block, algorithm="encrypt"): - ``block`` -- a `2 \times 2` matrix with entries over `\GF{2^4}` - - ``algorithm`` -- (default: ``"encrypt"``) a string; a flag to signify + - ``algorithm`` -- (default: ``'encrypt'``) a string; a flag to signify whether this nibble-sub operation is used for encryption or - decryption. The encryption flag is ``"encrypt"`` and the decryption - flag is ``"decrypt"``. + decryption. The encryption flag is ``'encrypt'`` and the decryption + flag is ``'decrypt'``. - OUTPUT: - - - A `2 \times 2` matrix resulting from applying an S-box on - entries of the `2 \times 2` matrix ``block``. + OUTPUT: a `2 \times 2` matrix resulting from applying an S-box on + entries of the `2 \times 2` matrix ``block``. EXAMPLES: @@ -1127,7 +1119,7 @@ def nibble_sub(self, block, algorithm="encrypt"): sage: K = FiniteField(16, "x") sage: MS = MatrixSpace(K, 2, 2) sage: mat = MS([[K("x^3 + x^2 + x + 1"), K("0")], [K("x^2 + x + 1"), K("x^3 + x")]]) - sage: maes.nibble_sub(mat, algorithm="encrypt") + sage: maes.nibble_sub(mat, algorithm='encrypt') [ x^2 + x + 1 x^3 + x^2 + x] [ x^3 x^2 + x] @@ -1141,11 +1133,11 @@ def nibble_sub(self, block, algorithm="encrypt"): [x^2 + x x] [x^2 + x x^3 + 1] - sage: maes.nibble_sub(B, algorithm="encrypt") + sage: maes.nibble_sub(B, algorithm='encrypt') [ x^3 + x + 1 x^3 + x^2 + 1] [ x^3 + x + 1 x^3 + x] - sage: maes.nibble_sub(B, algorithm="decrypt") + sage: maes.nibble_sub(B, algorithm='decrypt') [ x^3 + x x^2] [ x^3 + x x^3 + x^2 + 1] @@ -1158,11 +1150,11 @@ def nibble_sub(self, block, algorithm="encrypt"): [ x x^2 + x] [ x^3 x^3 + x^2 + x] - sage: maes.nibble_sub(P, algorithm="encrypt") + sage: maes.nibble_sub(P, algorithm='encrypt') [x^3 + x^2 + 1 x^3 + x + 1] [ x + 1 0] - sage: maes.nibble_sub(P, algorithm="decrypt") + sage: maes.nibble_sub(P, algorithm='decrypt') [ x^2 x^3 + x] [x^2 + x + 1 0] @@ -1189,20 +1181,20 @@ def nibble_sub(self, block, algorithm="encrypt"): TypeError: input block must be a 2 x 2 matrix over GF(16) The value for the option ``algorithm`` must be either the string - ``"encrypt"`` or ``"decrypt"``:: + ``'encrypt'`` or ``'decrypt'``:: sage: K = FiniteField(16, "x") sage: MS = MatrixSpace(K, 2, 2) sage: mat = MS([[K("x^3 + x^2 + x + 1"), K("0")], [K("x^2 + x + 1"), K("x^3 + x")]]) - sage: maes.nibble_sub(mat, algorithm="abc") + sage: maes.nibble_sub(mat, algorithm='abc') Traceback (most recent call last): ... ValueError: the algorithm for nibble-sub must be either 'encrypt' or 'decrypt' - sage: maes.nibble_sub(mat, algorithm="e") + sage: maes.nibble_sub(mat, algorithm='e') Traceback (most recent call last): ... ValueError: the algorithm for nibble-sub must be either 'encrypt' or 'decrypt' - sage: maes.nibble_sub(mat, algorithm="d") + sage: maes.nibble_sub(mat, algorithm='d') Traceback (most recent call last): ... ValueError: the algorithm for nibble-sub must be either 'encrypt' or 'decrypt' @@ -1284,11 +1276,9 @@ def round_key(self, key, n): - ``key`` -- the secret key - - ``n`` -- non-negative integer; the round number + - ``n`` -- nonnegative integer; the round number - OUTPUT: - - - The `n`-th round key. + OUTPUT: the `n`-th round key EXAMPLES: @@ -1430,9 +1420,7 @@ def shift_row(self, block): - ``block`` -- a `2 \times 2` matrix with entries over `\GF{2^4}` - OUTPUT: - - - A `2 \times 2` matrix resulting from applying shift-row on ``block``. + OUTPUT: a `2 \times 2` matrix resulting from applying shift-row on ``block`` EXAMPLES: @@ -1547,9 +1535,7 @@ def GF_to_binary(self, G): - ``G`` -- an element of `\GF{2^4}`, a list of elements of `\GF{2^4}`, or a matrix over `\GF{2^4}` - OUTPUT: - - - A binary string representation of ``G``. + OUTPUT: a binary string representation of ``G`` EXAMPLES: @@ -1697,9 +1683,7 @@ def GF_to_integer(self, G): - ``G`` -- an element of `\GF{2^4}`, a list of elements belonging to `\GF{2^4}`, or a matrix over `\GF{2^4}` - OUTPUT: - - - The integer representation of ``G``. + OUTPUT: the integer representation of ``G`` EXAMPLES: @@ -1908,9 +1892,7 @@ def binary_to_integer(self, B): - ``B`` -- a binary string, where the number of bits is positive and a multiple of 4 - OUTPUT: - - - A list of integers that represent the binary string ``B``. + OUTPUT: list of integers that represent the binary string ``B`` EXAMPLES: @@ -1979,12 +1961,10 @@ def integer_to_binary(self, N): INPUT: - - ``N`` -- a non-negative integer less than or equal to 15, or a list + - ``N`` -- nonnegative integer less than or equal to 15, or a list of such integers - OUTPUT: - - - A binary string representing ``N``. + OUTPUT: a binary string representing ``N`` EXAMPLES: @@ -2090,12 +2070,10 @@ def integer_to_GF(self, N): INPUT: - - ``N`` -- a non-negative integer less than or equal to 15, or a list + - ``N`` -- nonnegative integer less than or equal to 15, or a list of such integers - OUTPUT: - - - Elements of the finite field `\GF{2^4}`. + OUTPUT: elements of the finite field `\GF{2^4}` EXAMPLES: @@ -2111,7 +2089,7 @@ def integer_to_GF(self, N): sage: maes.integer_to_GF(7) x^2 + x + 1 - Obtain the finite field elements corresponding to all non-negative + Obtain the finite field elements corresponding to all nonnegative integers less than or equal to 15:: sage: from sage.crypto.block_cipher.miniaes import MiniAES diff --git a/src/sage/crypto/block_cipher/present.py b/src/sage/crypto/block_cipher/present.py index d6f6146af3a..7b1a4a8a3d5 100644 --- a/src/sage/crypto/block_cipher/present.py +++ b/src/sage/crypto/block_cipher/present.py @@ -179,11 +179,11 @@ def __init__(self, keySchedule=80, rounds=None, doFinalRound=False): INPUT: - - ``keySchedule`` -- (default: ``80``); the key schedule that will be + - ``keySchedule`` -- (default: ``80``) the key schedule that will be used for encryption and decryption. Use ``80`` or ``128`` as a shortcut for the original key schedules from [BKLPPRSV2007]_. - - ``rounds`` -- integer (default: ``None``); the number of rounds. If + - ``rounds`` -- integer (default: ``None``); the number of rounds. If ``None`` the number of rounds of the key schedule is used. - ``doFinalRound`` -- boolean (default: ``False``); flag to @@ -355,7 +355,7 @@ def encrypt(self, plaintext, key): INPUT: - ``plaintext`` -- integer or bit list-like; the plaintext that will be - encrypted. + encrypted - ``key`` -- integer or bit list-like; the key @@ -716,10 +716,10 @@ def __init__(self, keysize=80, rounds=31, master_key=None): INPUT: - - ``keysize`` -- integer (default: ``80``); the size of the keys that + - ``keysize`` -- integer (default: 80); the size of the keys that will be used in bits. It must be either 80 or 128. - - ``rounds`` -- integer (default: ``31``); the number of rounds + - ``rounds`` -- integer (default: 31); the number of rounds ``self`` can create keys for - ``master_key`` -- integer or bit list-like (default: ``None``); the @@ -836,14 +836,14 @@ def __repr__(self): def __getitem__(self, r): r""" - Computes the sub key for round ``r`` derived from initial master key. + Compute the sub key for round ``r`` derived from initial master key. The key schedule object has to have been initialised with the ``master_key`` argument. INPUT: - - ``r`` integer; the round for which the sub key is computed + - ``r`` -- integer; the round for which the sub key is computed EXAMPLES:: @@ -887,9 +887,7 @@ def convert_to_vector(I, L): - ``L`` -- integer; the desired bit length of the ouput - OUTPUT: - - - the ``L``-bit vector representation of ``I`` + OUTPUT: the ``L``-bit vector representation of ``I`` EXAMPLES:: diff --git a/src/sage/crypto/block_cipher/sdes.py b/src/sage/crypto/block_cipher/sdes.py index 30b8cf2516c..a474530199b 100644 --- a/src/sage/crypto/block_cipher/sdes.py +++ b/src/sage/crypto/block_cipher/sdes.py @@ -70,8 +70,8 @@ class SimplifiedDES(SageObject): sage: Mod(len(P), 8) == 0 True sage: K = sdes.list_to_string(sdes.random_key()) - sage: C = sdes(P, K, algorithm="encrypt") - sage: plaintxt = sdes(C, K, algorithm="decrypt") + sage: C = sdes(P, K, algorithm='encrypt') + sage: plaintxt = sdes(C, K, algorithm='decrypt') sage: plaintxt == P True """ @@ -101,7 +101,7 @@ def __init__(self): # the S-box S_1 self._sbox1 = SBox(0, 1, 2, 3, 2, 0, 1, 3, 3, 0, 1, 0, 2, 1, 0, 3) - def __call__(self, B, K, algorithm="encrypt"): + def __call__(self, B, K, algorithm='encrypt'): r""" Apply S-DES encryption or decryption on the binary string ``B`` using the key ``K``. The flag ``algorithm`` controls what action is @@ -110,14 +110,14 @@ def __call__(self, B, K, algorithm="encrypt"): INPUT: - ``B`` -- a binary string, where the number of bits is positive and - a multiple of 8. + a multiple of 8 - ``K`` -- a secret key; this must be a 10-bit binary string - - ``algorithm`` -- (default: ``"encrypt"``) a string; a flag to signify + - ``algorithm`` -- (default: ``'encrypt'``) a string; a flag to signify whether encryption or decryption is to be applied to the binary - string ``B``. The encryption flag is ``"encrypt"`` and the decryption - flag is ``"decrypt"``. + string ``B``. The encryption flag is ``'encrypt'`` and the decryption + flag is ``'decrypt'``. OUTPUT: @@ -135,8 +135,8 @@ def __call__(self, B, K, algorithm="encrypt"): sage: P = bin.encoding("Encrypt this using DES!") sage: K = sdes.random_key() sage: K = sdes.list_to_string(K) - sage: C = sdes(P, K, algorithm="encrypt") - sage: plaintxt = sdes(C, K, algorithm="decrypt") + sage: C = sdes(P, K, algorithm='encrypt') + sage: plaintxt = sdes(C, K, algorithm='decrypt') sage: plaintxt == P True @@ -171,20 +171,20 @@ def __call__(self, B, K, algorithm="encrypt"): ... ValueError: secret key must be a 10-bit binary string - The value for ``algorithm`` must be either ``"encrypt"`` or - ``"decrypt"``:: + The value for ``algorithm`` must be either ``'encrypt'`` or + ``'decrypt'``:: sage: B = bin.encoding("abc") sage: K = sdes.list_to_string(sdes.random_key()) - sage: sdes(B, K, algorithm="e") + sage: sdes(B, K, algorithm='e') Traceback (most recent call last): ... ValueError: algorithm must be either 'encrypt' or 'decrypt' - sage: sdes(B, K, algorithm="d") + sage: sdes(B, K, algorithm='d') Traceback (most recent call last): ... ValueError: algorithm must be either 'encrypt' or 'decrypt' - sage: sdes(B, K, algorithm="abc") + sage: sdes(B, K, algorithm='abc') Traceback (most recent call last): ... ValueError: algorithm must be either 'encrypt' or 'decrypt' @@ -535,9 +535,9 @@ def initial_permutation(self, B, inverse=False): - ``B`` -- list; a block of 8 bits - - ``inverse`` -- (default: ``False``) if ``True`` then use the - inverse permutation `P^{-1}`; if ``False`` then use the initial - permutation `P` + - ``inverse`` -- boolean (default: ``False``); if ``True`` then use the + inverse permutation `P^{-1}`. If ``False`` then use the initial + permutation `P`. OUTPUT: @@ -647,16 +647,14 @@ def left_shift(self, B, n=1): INPUT: - - ``B`` -- a list of 10 bits + - ``B`` -- list of 10 bits - ``n`` -- (default: 1) if ``n=1`` then perform left shift by 1 position; if ``n=2`` then perform left shift by 2 positions. The valid values for ``n`` are 1 and 2, since only up to 2 positions are defined for this circular left shift operation. - OUTPUT: - - The circular left shift of each half of ``B``. + OUTPUT: the circular left shift of each half of ``B`` EXAMPLES: @@ -763,9 +761,7 @@ def list_to_string(self, B): - ``B`` -- a non-empty list of bits - OUTPUT: - - The binary string representation of ``B``. + OUTPUT: the binary string representation of ``B`` EXAMPLES: @@ -823,9 +819,7 @@ def permutation4(self, B): - ``B`` -- a block of 4-bit string - OUTPUT: - - A permutation of ``B``. + OUTPUT: a permutation of ``B`` EXAMPLES: @@ -910,9 +904,7 @@ def permutation8(self, B): - ``B`` -- a block of 10-bit string - OUTPUT: - - Pick out 8 of the 10 bits of ``B`` and permute those 8 bits. + OUTPUT: pick out 8 of the 10 bits of ``B`` and permute those 8 bits EXAMPLES: @@ -1000,9 +992,7 @@ def permutation10(self, B): - ``B`` -- a block of 10-bit string - OUTPUT: - - A permutation of ``B``. + OUTPUT: a permutation of ``B`` EXAMPLES: @@ -1170,13 +1160,11 @@ def permute_substitute(self, B, key): INPUT: - - ``B`` -- a list of 8 bits + - ``B`` -- list of 8 bits - ``key`` -- an 8-bit subkey - OUTPUT: - - The result of applying the function `\Pi_F` to ``B``. + OUTPUT: the result of applying the function `\Pi_F` to ``B`` EXAMPLES: @@ -1314,11 +1302,9 @@ def string_to_list(self, S): INPUT: - - ``S`` -- a string of bits + - ``S`` -- string of bits - OUTPUT: - - A list representation of the string ``S``. + OUTPUT: list representation of the string ``S`` EXAMPLES: @@ -1364,7 +1350,7 @@ def string_to_list(self, S): def subkey(self, K, n=1): r""" - Return the ``n``-th subkey based on the key ``K``. + Return the `n`-th subkey based on the key ``K``. INPUT: @@ -1375,9 +1361,7 @@ def subkey(self, K, n=1): values for ``n`` are 1 and 2, since only two subkeys are defined for each secret key in Schaefer's S-DES. - OUTPUT: - - The ``n``-th subkey based on the secret key ``K``. + OUTPUT: the `n`-th subkey based on the secret key ``K`` EXAMPLES: diff --git a/src/sage/crypto/boolean_function.pyx b/src/sage/crypto/boolean_function.pyx index 8cfd08bfd58..7f8f4b4fba0 100644 --- a/src/sage/crypto/boolean_function.pyx +++ b/src/sage/crypto/boolean_function.pyx @@ -120,7 +120,6 @@ cdef reed_muller(mp_limb_t* f, int ldn): .. MATH:: f(x) = \bigoplus_{support(x)\subset I} a_I .. MATH:: a_i = \bigoplus_{I\subset support(x)} f(x) - EXAMPLES:: sage: # needs sage.rings.polynomial.pbori @@ -366,7 +365,7 @@ cdef class BooleanFunction(SageObject): def __invert__(self): """ - Return the complement Boolean function of `self`. + Return the complement Boolean function of ``self``. EXAMPLES:: @@ -543,11 +542,14 @@ cdef class BooleanFunction(SageObject): """ The truth table of the Boolean function. - INPUT: a string representing the desired format, can be either + INPUT: + + - ``format`` -- string representing the desired format; can be either - - ``'bin'`` (default): we return a tuple of Boolean values - - ``'int'``: we return a tuple of 0 or 1 values - - ``'hex'``: we return a string representing the truth table in hexadecimal + - ``'bin'`` -- (default) we return a tuple of Boolean values + - ``'int'`` -- we return a tuple of 0 or 1 values + - ``'hex'`` -- we return a string representing the truth table in + hexadecimal EXAMPLES:: @@ -637,10 +639,13 @@ cdef class BooleanFunction(SageObject): """ Return the value of the function for the given input. - INPUT: either + INPUT: + + - ``x`` -- either: + + - a list: then all elements are evaluated as booleans - - a list -- then all elements are evaluated as Booleans - - an integer -- then we consider its binary representation + - an integer: then we consider its binary representation EXAMPLES:: @@ -989,9 +994,9 @@ cdef class BooleanFunction(SageObject): INPUT: - - ``d`` -- an integer; - - ``dim`` -- a Boolean (default: ``False``), if ``True``, return also - the dimension of the annihilator vector space. + - ``d`` -- integer + - ``dim`` -- boolean (default: ``False``); if ``True``, return also + the dimension of the annihilator vector space EXAMPLES:: @@ -1272,7 +1277,7 @@ cdef class BooleanFunction(SageObject): def derivative(self, u): r""" - Return the derivative in direction of ``u`` + Return the derivative in direction of ``u``. INPUT: diff --git a/src/sage/crypto/cipher.py b/src/sage/crypto/cipher.py index 14e9df6a504..09f9fe902cb 100644 --- a/src/sage/crypto/cipher.py +++ b/src/sage/crypto/cipher.py @@ -23,10 +23,6 @@ class Cipher(Element): def __init__(self, parent, key): """ Create a cipher. - - INPUT: Parent and key - - EXAMPLES: None yet """ Element.__init__(self, parent) self._key = key @@ -62,11 +58,7 @@ class SymmetricKeyCipher(Cipher): """ def __init__(self, parent, key): """ - Create a symmetric cipher - - INPUT: Parent and key - - EXAMPLES: None yet + Create a symmetric cipher. """ Cipher.__init__(self, parent, key) @@ -76,11 +68,7 @@ class PublicKeyCipher(Cipher): """ def __init__(self, parent, key, public=True): """ - Create a public key cipher - - INPUT: Parent and key - - EXAMPLES: None yet + Create a public key cipher. """ Cipher.__init__(self, parent, key) self._public = public diff --git a/src/sage/crypto/classical.py b/src/sage/crypto/classical.py index d6740bf396a..3e2e618ea29 100644 --- a/src/sage/crypto/classical.py +++ b/src/sage/crypto/classical.py @@ -258,13 +258,11 @@ def __init__(self, A): INPUT: - - ``A`` -- a string monoid over some alphabet; this is the non-empty + - ``A`` -- string monoid over some alphabet; this is the non-empty alphabet over which the plaintext and ciphertext spaces - are defined. + are defined - OUTPUT: - - - An affine cryptosystem over the alphabet ``A``. + OUTPUT: an affine cryptosystem over the alphabet ``A`` EXAMPLES: @@ -428,11 +426,11 @@ def rank_by_chi_square(self, C, pdict): INPUT: - - ``C`` -- The ciphertext, a non-empty string. The ciphertext + - ``C`` -- the ciphertext, a non-empty string. The ciphertext must be encoded using the upper-case letters of the English alphabet. - - ``pdict`` -- A dictionary of key, possible plaintext + - ``pdict`` -- dictionary of key, possible plaintext pairs. This should be the output of :func:`brute_force` with ``ranking="none"``. @@ -637,11 +635,11 @@ def rank_by_squared_differences(self, C, pdict): INPUT: - - ``C`` -- The ciphertext, a non-empty string. The ciphertext + - ``C`` -- the ciphertext, a non-empty string. The ciphertext must be encoded using the upper-case letters of the English alphabet. - - ``pdict`` -- A dictionary of key, possible plaintext + - ``pdict`` -- dictionary of key, possible plaintext pairs. This should be the output of :func:`brute_force` with ``ranking="none"``. @@ -786,25 +784,25 @@ def rank_by_squared_differences(self, C, pdict): for val, key in Rank] return RankedList - def brute_force(self, C, ranking="none"): + def brute_force(self, C, ranking='none'): r""" Attempt a brute force cryptanalysis of the ciphertext ``C``. INPUT: - - ``C`` -- A ciphertext over one of the supported alphabets of this + - ``C`` -- a ciphertext over one of the supported alphabets of this affine cryptosystem. See the class :class:`AffineCryptosystem` for documentation on the supported alphabets. - - ``ranking`` -- (default ``"none"``) the method to use for + - ``ranking`` -- (default: ``'none'``) the method to use for ranking all possible keys. If ``ranking="none"``, then do not use any ranking function. The following ranking functions are supported: - - ``"chi_square"`` -- the chi-square ranking function - as implemented in the method :func:`rank_by_chi_square`. + - ``'chi_square'`` -- the chi-square ranking function + as implemented in the method :func:`rank_by_chi_square` - - ``"squared_differences"`` -- the squared differences ranking + - ``'squared_differences'`` -- the squared differences ranking function as implemented in the method :func:`rank_by_squared_differences`. @@ -863,7 +861,7 @@ def brute_force(self, C, ranking="none"): sage: P = A.encoding("Linear functions for encrypting and decrypting."); P LINEARFUNCTIONSFORENCRYPTINGANDDECRYPTING sage: C = A.enciphering(a, b, P) - sage: Rank = A.brute_force(C, ranking="chisquare") + sage: Rank = A.brute_force(C, ranking='chisquare') sage: Rank[:10] # display only the top 10 candidate keys [((3, 7), LINEARFUNCTIONSFORENCRYPTINGANDDECRYPTING), @@ -880,7 +878,7 @@ def brute_force(self, C, ranking="none"): Use the squared differences ranking function, i.e. ``ranking="squared_differences"``:: - sage: Rank = A.brute_force(C, ranking="squared_differences") + sage: Rank = A.brute_force(C, ranking='squared_differences') sage: Rank[:10] # display only the top 10 candidate keys [((3, 7), LINEARFUNCTIONSFORENCRYPTINGANDDECRYPTING), @@ -931,14 +929,14 @@ def brute_force(self, C, ranking="none"): Only the chi-square and squared-differences ranking functions are currently supported. The keyword ``ranking`` must take on either - of the values ``"none"``, ``"chisquare"`` or - ``"squared_differences"``:: + of the values ``'none'``, ``'chisquare'`` or + ``'squared_differences'``:: sage: A = AffineCryptosystem(AlphabeticStrings()) sage: a, b = (3, 7) sage: P = A.encoding("Linear") sage: C = A.enciphering(a, b, P) - sage: A.brute_force(C, ranking="chi") + sage: A.brute_force(C, ranking='chi') Traceback (most recent call last): ... ValueError: Keyword 'ranking' must be either 'none', 'chisquare', or 'squared_differences'. @@ -987,14 +985,12 @@ def deciphering(self, a, b, C): `\ZZ/n\ZZ \times \ZZ/n\ZZ` such that `\gcd(a,n) = 1` with `n` being the size of the ciphertext and plaintext spaces. - - ``C`` -- a string of ciphertext; possibly an empty string. + - ``C`` -- string of ciphertext; possibly an empty string. Characters in this string must be encoded using one of the supported alphabets. See the method :func:`encoding()` for more information. - OUTPUT: - - - The plaintext corresponding to the ciphertext ``C``. + OUTPUT: the plaintext corresponding to the ciphertext ``C`` EXAMPLES: @@ -1061,14 +1057,12 @@ def enciphering(self, a, b, P): `\ZZ/n\ZZ \times \ZZ/n\ZZ` such that `\gcd(a,n) = 1` with `n` being the size of the ciphertext and plaintext spaces. - - ``P`` -- a string of plaintext; possibly an empty string. + - ``P`` -- string of plaintext; possibly an empty string. Characters in this string must be encoded using one of the supported alphabets. See the method :func:`encoding()` for more information. - OUTPUT: - - - The ciphertext corresponding to the plaintext ``P``. + OUTPUT: the ciphertext corresponding to the plaintext ``P`` EXAMPLES: @@ -1129,12 +1123,10 @@ def encoding(self, S): INPUT: - - ``S`` -- a string, possibly empty. + - ``S`` -- string, possibly empty - OUTPUT: - - - The encoding of ``S`` over the string monoid of this cryptosystem. - If ``S`` is an empty string, return an empty string. + OUTPUT: the encoding of ``S`` over the string monoid of this + cryptosystem; if ``S`` is an empty string, return an empty string EXAMPLES: @@ -1295,14 +1287,12 @@ class HillCryptosystem(SymmetricKeyCryptosystem): INPUT: - - ``S`` -- a string monoid over some alphabet + - ``S`` -- string monoid over some alphabet - ``m`` -- integer `> 0`; the block length of matrices that specify block permutations - OUTPUT: - - - A Hill cryptosystem of block length ``m`` over the alphabet ``S``. + OUTPUT: a Hill cryptosystem of block length ``m`` over the alphabet ``S`` EXAMPLES:: @@ -1339,14 +1329,12 @@ def __init__(self, S, m): INPUT: - - ``S`` -- a string monoid over some alphabet + - ``S`` -- string monoid over some alphabet - ``m`` -- integer `> 0`; the block length of matrices that specify block permutations - OUTPUT: - - - A Hill cryptosystem of block length ``m`` over the alphabet ``S``. + OUTPUT: a Hill cryptosystem of block length ``m`` over the alphabet ``S`` EXAMPLES:: @@ -1399,7 +1387,7 @@ def __call__(self, A): def _repr_(self): """ - Return a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -1420,9 +1408,7 @@ def block_length(self): or decryption key are the same. This row/column dimension is referred to as the *block length*. - OUTPUT: - - - The block length of an encryption/decryption key. + OUTPUT: the block length of an encryption/decryption key EXAMPLES:: @@ -1444,9 +1430,7 @@ def random_key(self): i.e. invertible `m \times m` square matrices, is smaller than `n^{m^2}`. - OUTPUT: - - - A random key within the key space of this Hill cipher. + OUTPUT: a random key within the key space of this Hill cipher EXAMPLES:: @@ -1479,9 +1463,7 @@ def inverse_key(self, A): - ``A`` -- an invertible matrix of the key space of this Hill cipher - OUTPUT: - - - The inverse matrix of ``A``. + OUTPUT: the inverse matrix of ``A`` EXAMPLES:: @@ -1519,11 +1501,10 @@ def encoding(self, M): INPUT: - - ``M`` -- a string, possibly empty + - ``M`` -- string, possibly empty - OUTPUT: - - - The encoding of ``M`` over the string monoid of this Hill cipher. + OUTPUT: the encoding of ``M`` over the string monoid of this Hill + cipher EXAMPLES:: @@ -1549,12 +1530,10 @@ def deciphering(self, A, C): - ``A`` -- a key within the key space of this Hill cipher - - ``C`` -- a string (possibly empty) over the string monoid of this + - ``C`` -- string (possibly empty) over the string monoid of this Hill cipher - OUTPUT: - - - The plaintext corresponding to the ciphertext ``C``. + OUTPUT: the plaintext corresponding to the ciphertext ``C`` EXAMPLES:: @@ -1577,12 +1556,10 @@ def enciphering(self, A, M): - ``A`` -- a key within the key space of this Hill cipher - - ``M`` -- a string (possibly empty) over the string monoid of this - Hill cipher. - - OUTPUT: + - ``M`` -- string (possibly empty) over the string monoid of this + Hill cipher - - The ciphertext corresponding to the plaintext ``M``. + OUTPUT: the ciphertext corresponding to the plaintext ``M`` EXAMPLES:: @@ -1814,13 +1791,11 @@ def __init__(self, A): INPUT: - - ``A`` -- a string monoid over some alphabet; this is the non-empty + - ``A`` -- string monoid over some alphabet; this is the non-empty alphabet over which the plaintext and ciphertext spaces - are defined. - - OUTPUT: + are defined - - A shift cryptosystem over the alphabet ``A``. + OUTPUT: a shift cryptosystem over the alphabet ``A`` EXAMPLES:: @@ -1867,9 +1842,7 @@ def __call__(self, K): `0 \leq k < n` where `n` is the size or cardinality of the set `A`. - OUTPUT: - - - A shift cipher with secret key ``K``. + OUTPUT: a shift cipher with secret key ``K`` EXAMPLES:: @@ -2018,11 +1991,11 @@ def rank_by_chi_square(self, C, pdict): INPUT: - - ``C`` -- The ciphertext, a non-empty string. The ciphertext + - ``C`` -- the ciphertext, a non-empty string. The ciphertext must be encoded using the upper-case letters of the English alphabet. - - ``pdict`` -- A dictionary of key, possible plaintext pairs. + - ``pdict`` -- dictionary of key, possible plaintext pairs. This should be the output of :func:`brute_force` with ``ranking="none"``. @@ -2255,18 +2228,16 @@ def rank_by_squared_differences(self, C, pdict): INPUT: - - ``C`` -- The ciphertext, a non-empty string. The ciphertext + - ``C`` -- the ciphertext, a non-empty string. The ciphertext must be encoded using the upper-case letters of the English alphabet. - - ``pdict`` -- A dictionary of key, possible plaintext pairs. + - ``pdict`` -- dictionary of key, possible plaintext pairs. This should be the output of :func:`brute_force` with ``ranking="none"``. - OUTPUT: - - - A list ranking the most likely keys first. Each element of the - list is a tuple of key, possible plaintext pairs. + OUTPUT: a list ranking the most likely keys first; each element of the + list is a tuple of key, possible plaintext pairs EXAMPLES: @@ -2432,25 +2403,25 @@ def rank_by_squared_differences(self, C, pdict): [RankedList.append((key, pdict[key])) for val, key in Rank] return RankedList - def brute_force(self, C, ranking="none"): + def brute_force(self, C, ranking='none'): r""" Attempt a brute force cryptanalysis of the ciphertext ``C``. INPUT: - - ``C`` -- A ciphertext over one of the supported alphabets of this + - ``C`` -- a ciphertext over one of the supported alphabets of this shift cryptosystem. See the class :class:`ShiftCryptosystem` for documentation on the supported alphabets. - - ``ranking`` -- (default ``"none"``) the method to use for + - ``ranking`` -- (default: ``'none'``) the method to use for ranking all possible keys. If ``ranking="none"``, then do not use any ranking function. The following ranking functions are supported: - - ``"chisquare"`` -- the chi-square ranking function as - implemented in the method :func:`rank_by_chi_square`. + - ``'chisquare'`` -- the chi-square ranking function as + implemented in the method :func:`rank_by_chi_square` - - ``"squared_differences"`` -- the squared differences ranking + - ``'squared_differences'`` -- the squared differences ranking function as implemented in the method :func:`rank_by_squared_differences`. @@ -2539,7 +2510,7 @@ def brute_force(self, C, ranking="none"): Use the chi-square ranking function, i.e. ``ranking="chisquare"``:: - sage: S.brute_force(C, ranking="chisquare") + sage: S.brute_force(C, ranking='chisquare') [(8, SHIFTINGUSINGMODULARARITHMETIC), (14, MBCZNCHAOMCHAGIXOFULULCNBGYNCW), @@ -2571,7 +2542,7 @@ def brute_force(self, C, ranking="none"): Use the squared differences ranking function, i.e. ``ranking="squared_differences"``:: - sage: S.brute_force(C, ranking="squared_differences") + sage: S.brute_force(C, ranking='squared_differences') [(8, SHIFTINGUSINGMODULARARITHMETIC), (23, DSTQETYRFDTYRXZOFWLCLCTESXPETN), @@ -2669,14 +2640,12 @@ def deciphering(self, K, C): shift cipher. This key is an integer `k` satisfying the inequality `0 \leq k < n`, where `n` is the size of the cipher domain. - - ``C`` -- a string of ciphertext; possibly an empty string. + - ``C`` -- string of ciphertext; possibly an empty string Characters in this string must be encoded using one of the supported alphabets. See the method :func:`encoding()` for more information. - OUTPUT: - - - The plaintext corresponding to the ciphertext ``C``. + OUTPUT: the plaintext corresponding to the ciphertext ``C`` EXAMPLES: @@ -2728,14 +2697,12 @@ def enciphering(self, K, P): This key is an integer `k` satisfying the inequality `0 \leq k < n`, where `n` is the size of the cipher domain. - - ``P`` -- a string of plaintext; possibly an empty string. + - ``P`` -- string of plaintext; possibly an empty string. Characters in this string must be encoded using one of the supported alphabets. See the method :func:`encoding()` for more information. - OUTPUT: - - - The ciphertext corresponding to the plaintext ``P``. + OUTPUT: the ciphertext corresponding to the plaintext ``P`` EXAMPLES: @@ -2792,12 +2759,10 @@ def encoding(self, S): INPUT: - - ``S`` -- a string, possibly empty. - - OUTPUT: + - ``S`` -- string, possibly empty - - The encoding of ``S`` over the string monoid of this cryptosystem. - If ``S`` is an empty string, return an empty string. + OUTPUT: the encoding of ``S`` over the string monoid of this + cryptosystem; if ``S`` is an empty string, return an empty string EXAMPLES: @@ -2849,11 +2814,9 @@ def inverse_key(self, K): INPUT: - ``K`` -- a key for this shift cipher. This must be an integer `k` - such that `0 \leq k < n`, where `n` is the size of the cipher domain. - - OUTPUT: + such that `0 \leq k < n`, where `n` is the size of the cipher domain - - The inverse key corresponding to ``K``. + OUTPUT: the inverse key corresponding to ``K`` EXAMPLES: @@ -2881,7 +2844,7 @@ def inverse_key(self, K): Regardless of the value of a key, the addition of the key and its inverse must be equal to the alphabet size. This relationship holds - exactly when the value of the key is non-zero:: + exactly when the value of the key is nonzero:: sage: S = ShiftCryptosystem(AlphabeticStrings()) sage: K = S.random_key() @@ -2964,9 +2927,7 @@ def random_key(self): key space, which is the set `\ZZ / n\ZZ`. The key `k = 0` has no effect on either the plaintext or the ciphertext. - OUTPUT: - - - A random key within the key space of this shift cryptosystem. + OUTPUT: a random key within the key space of this shift cryptosystem EXAMPLES:: @@ -2982,7 +2943,7 @@ def random_key(self): Regardless of the value of a key, the addition of the key and its inverse must be equal to the alphabet size. This relationship holds - exactly when the value of the key is non-zero:: + exactly when the value of the key is nonzero:: sage: S = ShiftCryptosystem(AlphabeticStrings()) sage: K = S.random_key() @@ -3014,11 +2975,9 @@ class SubstitutionCryptosystem(SymmetricKeyCryptosystem): INPUT: - - ``S`` -- a string monoid over some alphabet + - ``S`` -- string monoid over some alphabet - OUTPUT: - - - A substitution cryptosystem over the alphabet ``S``. + OUTPUT: a substitution cryptosystem over the alphabet ``S`` EXAMPLES:: @@ -3087,7 +3046,7 @@ def __call__(self, K): def _repr_(self): """ - Return a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -3107,9 +3066,7 @@ def random_key(self): alphabet. Let `n` be the length of the alphabet. Then there are `n!` possible keys in the key space. - OUTPUT: - - - A random key within the key space of this cryptosystem. + OUTPUT: a random key within the key space of this cryptosystem EXAMPLES:: @@ -3138,9 +3095,7 @@ def inverse_key(self, K): - ``K`` -- a key belonging to the key space of this cryptosystem - OUTPUT: - - - The inverse key of ``K``. + OUTPUT: the inverse key of ``K`` EXAMPLES:: @@ -3169,11 +3124,10 @@ def encoding(self, M): INPUT: - - ``M`` -- a string, possibly empty - - OUTPUT: + - ``M`` -- string, possibly empty - - The encoding of ``M`` over the string monoid of this cryptosystem. + OUTPUT: the encoding of ``M`` over the string monoid of this + cryptosystem EXAMPLES:: @@ -3199,12 +3153,10 @@ def deciphering(self, K, C): - ``K`` -- a key belonging to the key space of this substitution cipher - - ``C`` -- a string (possibly empty) over the string monoid of this - cryptosystem. - - OUTPUT: + - ``C`` -- string (possibly empty) over the string monoid of this + cryptosystem - - The plaintext corresponding to the ciphertext ``C``. + OUTPUT: the plaintext corresponding to the ciphertext ``C`` EXAMPLES:: @@ -3225,12 +3177,10 @@ def enciphering(self, K, M): - ``K`` -- a key belonging to the key space of this substitution cipher - - ``M`` -- a string (possibly empty) over the string monoid of this - cryptosystem. - - OUTPUT: + - ``M`` -- string (possibly empty) over the string monoid of this + cryptosystem - - The ciphertext corresponding to the plaintext ``M``. + OUTPUT: the ciphertext corresponding to the plaintext ``M`` EXAMPLES:: @@ -3249,7 +3199,7 @@ class TranspositionCryptosystem(SymmetricKeyCryptosystem): INPUT: - - ``S`` -- a string monoid over some alphabet + - ``S`` -- string monoid over some alphabet - ``n`` -- integer `> 0`; a block length of a block permutation @@ -3325,7 +3275,7 @@ def __call__(self, K): def _repr_(self): """ - Return a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -3344,9 +3294,7 @@ def random_key(self): cryptosystem. Let `n > 0` be the block length of this cryptosystem. Then there are `n!` possible keys. - OUTPUT: - - - A random key within the key space of this cryptosystem. + OUTPUT: a random key within the key space of this cryptosystem EXAMPLES:: @@ -3374,12 +3322,10 @@ def inverse_key(self, K, check=True): - ``K`` -- a key belonging to the key space of this transposition cipher - - ``check`` -- bool (default: ``True``); check that ``K`` belongs to - the key space of this cryptosystem. - - OUTPUT: + - ``check`` -- boolean (default: ``True``); check that ``K`` belongs to + the key space of this cryptosystem - - The inverse key corresponding to ``K``. + OUTPUT: the inverse key corresponding to ``K`` EXAMPLES:: @@ -3410,11 +3356,10 @@ def encoding(self, M): INPUT: - - ``M`` -- a string, possibly empty + - ``M`` -- string, possibly empty - OUTPUT: - - - The encoding of ``M`` over the string monoid of this cryptosystem. + OUTPUT: the encoding of ``M`` over the string monoid of this + cryptosystem EXAMPLES:: @@ -3441,12 +3386,10 @@ def deciphering(self, K, C): - ``K`` -- a key belonging to the key space of this transposition cipher - - ``C`` -- a string (possibly empty) over the string monoid of this - cryptosystem. - - OUTPUT: + - ``C`` -- string (possibly empty) over the string monoid of this + cryptosystem - - The plaintext corresponding to the ciphertext ``C``. + OUTPUT: the plaintext corresponding to the ciphertext ``C`` EXAMPLES:: @@ -3469,12 +3412,10 @@ def enciphering(self, K, M): - ``K`` -- a key belonging to the key space of this transposition cipher - - ``M`` -- a string (possibly empty) over the string monoid of this + - ``M`` -- string (possibly empty) over the string monoid of this cryptosystem - OUTPUT: - - - The ciphertext corresponding to the plaintext ``M``. + OUTPUT: the ciphertext corresponding to the plaintext ``M`` EXAMPLES:: @@ -3495,7 +3436,7 @@ class VigenereCryptosystem(SymmetricKeyCryptosystem): INPUT: - - ``S`` -- a string monoid over some alphabet + - ``S`` -- string monoid over some alphabet - ``n`` -- integer `> 0`; block length of an encryption/decryption key @@ -3546,7 +3487,9 @@ def __call__(self, K): """ Create a Vigenere cipher. - INPUT: A key which specifies a block permutation. + INPUT: + + - ``K`` -- a key which specifies a block permutation EXAMPLES:: @@ -3576,7 +3519,7 @@ def __call__(self, K): def _repr_(self): """ - Return a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -3597,9 +3540,7 @@ def random_key(self): and let `m > 0` be the block length of this cryptosystem. Then there are `n^m` possible keys. - OUTPUT: - - - A random key within the key space of this cryptosystem. + OUTPUT: a random key within the key space of this cryptosystem EXAMPLES:: @@ -3626,9 +3567,7 @@ def inverse_key(self, K): - ``K`` -- a key within the key space of this Vigenere cryptosystem - OUTPUT: - - - The inverse key corresponding to ``K``. + OUTPUT: the inverse key corresponding to ``K`` EXAMPLES:: @@ -3656,11 +3595,10 @@ def encoding(self, M): INPUT: - - ``M`` -- a string, possibly empty - - OUTPUT: + - ``M`` -- string, possibly empty - - The encoding of ``M`` over the string monoid of this cryptosystem. + OUTPUT: the encoding of ``M`` over the string monoid of this + cryptosystem EXAMPLES:: @@ -3686,12 +3624,10 @@ def deciphering(self, K, C): - ``K`` -- a key belonging to the key space of this Vigenere cipher - - ``C`` -- a string (possibly empty) over the string monoid of this + - ``C`` -- string (possibly empty) over the string monoid of this cryptosystem - OUTPUT: - - - The plaintext corresponding to the ciphertext ``C``. + OUTPUT: the plaintext corresponding to the ciphertext ``C`` EXAMPLES:: @@ -3712,12 +3648,10 @@ def enciphering(self, K, M): - ``K`` -- a key belonging to the key space of this Vigenere cipher - - ``M`` -- a string (possibly empty) over the string monoid of this + - ``M`` -- string (possibly empty) over the string monoid of this cryptosystem - OUTPUT: - - - The ciphertext corresponding to the plaintext ``M``. + OUTPUT: the ciphertext corresponding to the plaintext ``M`` EXAMPLES:: diff --git a/src/sage/crypto/classical_cipher.py b/src/sage/crypto/classical_cipher.py index b775c426058..b03aedff480 100644 --- a/src/sage/crypto/classical_cipher.py +++ b/src/sage/crypto/classical_cipher.py @@ -33,9 +33,9 @@ def __init__(self, parent, key): INPUT: - - ``parent`` -- an ``AffineCryptosystem`` object. + - ``parent`` -- an ``AffineCryptosystem`` object - - ``key`` -- a secret key. Let `N` be the size of the cipher domain. + - ``key`` -- a secret key; let `N` be the size of the cipher domain. A key of this affine cipher is an ordered pair `(a, b) \in \ZZ_N \times \ZZ_N` such that `\gcd(a, N) = 1`. @@ -58,12 +58,10 @@ def __eq__(self, other): INPUT: - - ``other`` -- another object to compare with. + - ``other`` -- another object to compare with - OUTPUT: - - - ``True`` if ``self`` and ``other`` are the same ``AffineCipher`` - object; ``False`` otherwise. + OUTPUT: ``True`` if ``self`` and ``other`` are the same + ``AffineCipher`` object; ``False`` otherwise EXAMPLES:: @@ -89,15 +87,13 @@ def __call__(self, M): behaviour is that the plaintext and ciphertext alphabets are the same alphabet. - - ``algorithm`` -- (default ``"encrypt"``) whether to use the - encryption or decryption algorithm on ``M``. The flag ``"encrypt"`` - signifies using the encryption algorithm, while ``"decrypt"`` + - ``algorithm`` -- (default: ``'encrypt'``) whether to use the + encryption or decryption algorithm on ``M``. The flag ``'encrypt'`` + signifies using the encryption algorithm, while ``'decrypt'`` signifies using the decryption algorithm. The only acceptable - values for ``algorithm`` are: ``"encrypt"`` and ``"decrypt"``. - - OUTPUT: + values for ``algorithm`` are: ``'encrypt'`` and ``'decrypt'``. - - The ciphertext or plaintext corresponding to ``M``. + OUTPUT: the ciphertext or plaintext corresponding to ``M`` EXAMPLES:: @@ -165,8 +161,6 @@ def __init__(self, parent, key): """ Create a Hill cipher. - INPUT: Parent and key - EXAMPLES:: sage: # needs sage.modules @@ -254,9 +248,9 @@ def __init__(self, parent, key): INPUT: - - ``parent`` -- a ``ShiftCryptosystem`` object. + - ``parent`` -- a ``ShiftCryptosystem`` object - - ``key`` -- a secret key. + - ``key`` -- a secret key EXAMPLES:: @@ -283,12 +277,10 @@ def __eq__(self, other): INPUT: - - ``other`` -- another object to compare with. - - OUTPUT: + - ``other`` -- another object to compare with - - ``True`` if ``self`` and ``other`` are the same ``ShiftCipher`` - object; ``False`` otherwise. + OUTPUT: ``True`` if ``self`` and ``other`` are the same ``ShiftCipher`` + object; ``False`` otherwise. EXAMPLES:: @@ -316,9 +308,7 @@ def __call__(self, M): behaviour is that the plaintext and ciphertext alphabets are the same alphabet. - OUTPUT: - - - The ciphertext or plaintext corresponding to ``M``. + OUTPUT: the ciphertext or plaintext corresponding to ``M`` EXAMPLES: @@ -392,8 +382,6 @@ def __init__(self, parent, key): """ Create a substitution cipher. - INPUT: Parent and key - EXAMPLES:: sage: S = AlphabeticStrings() @@ -467,8 +455,6 @@ def __init__(self, parent, key): """ Create a transposition cipher. - INPUT: Parent and key - EXAMPLES:: sage: # needs sage.groups @@ -508,7 +494,7 @@ def __init__(self, parent, key): raise ValueError("key (= %s) must have block length %s" % (key, n)) SymmetricKeyCipher.__init__(self, parent, key) - def __call__(self, M, mode="ECB"): + def __call__(self, M, mode='ECB'): S = self.domain() # = plaintext_space = ciphertext_space if not isinstance(M, StringMonoidElement) and M.parent() == S: raise TypeError("Argument M (= %s) must be a string in the plaintext space." % M) @@ -539,8 +525,6 @@ def __init__(self, parent, key): """ Create a Vigenere cipher. - INPUT: Parent and key - EXAMPLES:: sage: S = AlphabeticStrings() @@ -560,7 +544,7 @@ def __init__(self, parent, key): """ SymmetricKeyCipher.__init__(self, parent, key) - def __call__(self, M, mode="ECB"): + def __call__(self, M, mode='ECB'): S = self.domain() # = plaintext_space = ciphertext_space if not isinstance(M, StringMonoidElement) and M.parent() == S: raise TypeError("Argument M (= %s) must be a string in the plaintext space." % M) diff --git a/src/sage/crypto/cryptosystem.py b/src/sage/crypto/cryptosystem.py index 488b9a014b5..82fb0e553ad 100644 --- a/src/sage/crypto/cryptosystem.py +++ b/src/sage/crypto/cryptosystem.py @@ -78,15 +78,15 @@ class Cryptosystem(Set_generic): INPUT: - - ``plaintext_space`` -- the plaintext alphabet. + - ``plaintext_space`` -- the plaintext alphabet - - ``ciphertext_space`` -- the ciphertext alphabet. + - ``ciphertext_space`` -- the ciphertext alphabet - - ``key_space`` -- the key alphabet. + - ``key_space`` -- the key alphabet - - ``block_length`` -- (default: 1) the block length. + - ``block_length`` -- (default: 1) the block length - - ``period`` -- (default: ``None``) the period. + - ``period`` -- (default: ``None``) the period EXAMPLES: @@ -111,15 +111,15 @@ def __init__(self, plaintext_space, ciphertext_space, key_space, INPUT: - - ``plaintext_space`` -- the plaintext alphabet. + - ``plaintext_space`` -- the plaintext alphabet - - ``ciphertext_space`` -- the ciphertext alphabet. + - ``ciphertext_space`` -- the ciphertext alphabet - - ``key_space`` -- the key alphabet. + - ``key_space`` -- the key alphabet - - ``block_length`` -- (default: 1) the block length. + - ``block_length`` -- (default: 1) the block length - - ``period`` -- (default: ``None``) the period. + - ``period`` -- (default: ``None``) the period EXAMPLES: @@ -158,7 +158,7 @@ def __eq__(self, right): INPUT: - - ``right`` -- a ``Cryptosystem`` object. + - ``right`` -- a ``Cryptosystem`` object EXAMPLES: diff --git a/src/sage/crypto/lattice.py b/src/sage/crypto/lattice.py index 513730ff89f..355bfd1c3ba 100644 --- a/src/sage/crypto/lattice.py +++ b/src/sage/crypto/lattice.py @@ -22,7 +22,7 @@ # http://www.gnu.org/licenses/ #***************************************************************************** -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general def gen_lattice(type='modular', n=4, m=8, q=11, seed=None, quotient=None, dual=False, ntl=False, lattice=False): @@ -37,43 +37,41 @@ def gen_lattice(type='modular', n=4, m=8, q=11, seed=None, - ``type`` -- one of the following strings - - ``'modular'`` (default) -- A class of lattices for which + - ``'modular'`` -- default; a class of lattices for which asymptotic worst-case to average-case connections hold. For - more refer to [Aj1996]_. - - ``'random'`` -- Special case of modular (n=1). A dense class + more refer to [Aj1996]_ + - ``'random'`` -- special case of modular (n=1); a dense class of lattice used for testing basis reduction algorithms - proposed by Goldstein and Mayer [GM2002]_. - - ``'ideal'`` -- Special case of modular. Allows for a more - compact representation proposed by [LM2006]_. - - ``'cyclotomic'`` -- Special case of ideal. Allows for - efficient processing proposed by [LM2006]_. + proposed by Goldstein and Mayer [GM2002]_ + - ``'ideal'`` -- special case of modular; allows for a more + compact representation proposed by [LM2006]_ + - ``'cyclotomic'`` -- special case of ideal; allows for + efficient processing proposed by [LM2006]_ - - ``n`` -- Determinant size, primal: `det(L) = q^n`, dual: `det(L) = q^{m-n}`. + - ``n`` -- determinant size, primal: `det(L) = q^n`, dual: `det(L) = q^{m-n}`. For ideal lattices this is also the degree of the quotient polynomial. - - ``m`` -- Lattice dimension, `L \subseteq Z^m`. + - ``m`` -- lattice dimension, `L \subseteq Z^m` - - ``q`` -- Coefficient size, `q-Z^m \subseteq L`. + - ``q`` -- coefficient size, `q-Z^m \subseteq L` - - ``seed`` -- Randomness seed. + - ``seed`` -- randomness seed - - ``quotient`` -- For the type ``'ideal'``, this determines the quotient - polynomial. Ignored for all other types. + - ``quotient`` -- for the type ``'ideal'``, this determines the quotient + polynomial. Ignored for all other types - - ``dual`` -- Set this flag if you want a basis for `q-dual(L)`, for example - for Regev's LWE bases [Reg2005]_. + - ``dual`` -- set this flag if you want a basis for `q-dual(L)`, for example + for Regev's LWE bases [Reg2005]_ - - ``ntl`` -- Set this flag if you want the lattice basis in NTL readable - format. + - ``ntl`` -- set this flag if you want the lattice basis in NTL readable + format - - ``lattice`` -- Set this flag if you want a + - ``lattice`` -- set this flag if you want a :class:`FreeModule_submodule_with_basis_integer` object instead - of an integer matrix representing the basis. + of an integer matrix representing the basis - OUTPUT: - - ``B`` a unique size-reduced triangular (primal: lower_left, - dual: lower_right) basis of row vectors for the lattice in question. + OUTPUT: ``B`` a unique size-reduced triangular (primal: lower_left, + dual: lower_right) basis of row vectors for the lattice in question EXAMPLES: @@ -254,7 +252,7 @@ def gen_lattice(type='modular', n=4, m=8, q=11, seed=None, P = quotient.parent() # P should be a univariate polynomial ring over ZZ_q - if not is_PolynomialRing(P): + if not isinstance(P, PolynomialRing_general): raise TypeError("quotient should be a univariate polynomial") assert P.base_ring() is ZZ_q diff --git a/src/sage/crypto/lfsr.py b/src/sage/crypto/lfsr.py index 87d64756b3a..7a640e91533 100644 --- a/src/sage/crypto/lfsr.py +++ b/src/sage/crypto/lfsr.py @@ -139,7 +139,7 @@ def lfsr_sequence(key, fill, n): INPUT: - - ``key`` -- a list of finite field elements, `[c_0, c_1,\dots, c_k]` + - ``key`` -- list of finite field elements, `[c_0, c_1,\dots, c_k]` - ``fill`` -- the list of the initial terms of the LFSR sequence, `[x_0,x_1,\dots,x_k]` @@ -174,7 +174,6 @@ def lfsr_sequence(key, fill, n): 1 + x + x^4 + x^5 + x^8 + x^9 + x^12 + x^13 + x^16 + x^17 + O(x^20) sage: (1+x+x^3)/(g.reverse()+O(x^20)) 1 + x + x^3 + x^4 + x^5 + x^7 + x^8 + x^9 + x^11 + x^12 + x^13 + x^15 + x^16 + x^17 + x^19 + O(x^20) - """ if not isinstance(key, list): raise TypeError("key must be a list") @@ -202,7 +201,7 @@ def lfsr_autocorrelation(L, p, k): - ``p`` -- the period of `L` - - ``k`` -- an integer between `0` and `p` + - ``k`` -- integer between `0` and `p` OUTPUT: autocorrelation sequence of `L` @@ -236,7 +235,7 @@ def lfsr_connection_polynomial(s): OUTPUT: - - ``C(x)`` -- the connection polynomial of the minimal LFSR. + - ``C(x)`` -- the connection polynomial of the minimal LFSR This implements the algorithm in section 3 of J. L. Massey's article [Mas1969]_. diff --git a/src/sage/crypto/lwe.py b/src/sage/crypto/lwe.py index 035b05b48a2..4eee100c205 100644 --- a/src/sage/crypto/lwe.py +++ b/src/sage/crypto/lwe.py @@ -257,10 +257,10 @@ def __init__(self, n, q, D, secret_dist='uniform', m=None): - ``q`` -- modulus typically > n (integer > 0) - ``D`` -- an error distribution such as an instance of :class:`DiscreteGaussianDistributionIntegerSampler` or :class:`UniformSampler` - - ``secret_dist`` -- distribution of the secret (default: 'uniform'); one of + - ``secret_dist`` -- distribution of the secret (default: ``'uniform'``); one of - - "uniform" -- secret follows the uniform distribution in `\Zmod{q}` - - "noise" -- secret follows the noise distribution + - ``'uniform'`` -- secret follows the uniform distribution in `\Zmod{q}` + - ``'noise'`` -- secret follows the noise distribution - ``(lb, ub)`` -- the secret is chosen uniformly from ``[lb,...,ub]`` including both endpoints @@ -464,9 +464,9 @@ def __init__(self, n, instance='key', m=None): - ``n`` -- security parameter (integer >= 89) - ``instance`` -- one of - - "key" -- the LWE-instance that hides the secret key is generated - - "encrypt" -- the LWE-instance that hides the message is generated - (default: ``key``) + - ``'key'`` -- the LWE-instance that hides the secret key is generated + - ``'encrypt'`` -- the LWE-instance that hides the message is generated + (default: ``'key'``) - ``m`` -- number of allowed samples or ``None`` in which case ``m`` is chosen as in [CGW2013]_. (default: ``None``) @@ -709,7 +709,6 @@ def _repr_(self): sage: lwe = RingLWEConverter(rlwe) sage: lwe RingLWEConverter(RingLWE(20, 257, Discrete Gaussian sampler for polynomials of degree < 8 with σ=5.000000 in each component, x^8 - x^6 + x^4 - x^2 + 1, 'uniform', None)) - """ return "RingLWEConverter(%s)" % str(self.ringlwe) @@ -749,7 +748,6 @@ def samples(m, n, lwe, seed=None, balanced=False, **kwds): sage: samples(2, 20, 'LindnerPeikert') [((506, 1205, 398, 0, 337, 106, 836, 75, 1242, 642, 840, 262, 1823, 1798, 1831, 1658, 1084, 915, 1994, 163), 1447), ((463, 250, 1226, 1906, 330, 933, 1014, 1061, 1322, 2035, 1849, 285, 1993, 1975, 864, 1341, 41, 1955, 1818, 1357), 312)] - """ if seed is not None: set_random_seed(seed) @@ -803,7 +801,7 @@ def balance_sample(s, q=None): ....: assert all(-257//2 <= c <= 257//2 for bi in b for c in bi) ....: assert all(s[i][j] == b[i][j] % 257 for i in range(2) for j in range(8)) - .. note:: + .. NOTE:: This function is useful to convert between Sage's standard representation of elements in `\Zmod{q}` as integers between 0 and q-1 diff --git a/src/sage/crypto/mq/mpolynomialsystemgenerator.py b/src/sage/crypto/mq/mpolynomialsystemgenerator.py index 4416d9ef7f6..864e9ab1ea1 100644 --- a/src/sage/crypto/mq/mpolynomialsystemgenerator.py +++ b/src/sage/crypto/mq/mpolynomialsystemgenerator.py @@ -40,7 +40,8 @@ def varformatstr(self, name): encoded. INPUT: - name -- string + + - ``name`` -- string EXAMPLES:: @@ -61,8 +62,9 @@ def varstrs(self, name, round): This function is typically used by self._vars. INPUT: - name -- string - round -- integer index + + - ``name`` -- string + - ``round`` -- integer index EXAMPLES:: @@ -81,8 +83,9 @@ def vars(self, name, round): index 'round'. INPUT: - name -- string - round -- integer index + + - ``name`` -- string + - ``round`` -- integer index EXAMPLES:: @@ -113,7 +116,7 @@ def ring(self): def block_order(self): """ Return a block term ordering for the equation systems - generated by self. + generated by ``self``. EXAMPLES:: @@ -131,8 +134,9 @@ def __call__(self, P, K): Encrypt plaintext P using the key K. INPUT: - P -- plaintext (vector, list) - K -- key (vector, list) + + - ``P`` -- plaintext (vector, list) + - ``K`` -- key (vector, list) EXAMPLES:: @@ -147,7 +151,7 @@ def __call__(self, P, K): def sbox(self): """ - Return SBox object for self. + Return SBox object for ``self``. EXAMPLES:: @@ -167,8 +171,9 @@ def polynomial_system(self, P=None, K=None): to their solutions. INPUT: - P -- plaintext (vector, list) - K -- key (vector, list) + + - ``P`` -- plaintext (vector, list) + - ``K`` -- key (vector, list) EXAMPLES:: diff --git a/src/sage/crypto/mq/rijndael_gf.py b/src/sage/crypto/mq/rijndael_gf.py index 55ae295f2cd..dc75f5d165b 100644 --- a/src/sage/crypto/mq/rijndael_gf.py +++ b/src/sage/crypto/mq/rijndael_gf.py @@ -442,16 +442,16 @@ def __init__(self, Nb, Nk, state_chr='a', key_chr='k'): INPUT: - - ``Nb`` -- The block length of this instantiation. Must be between 4 - and 8. + - ``Nb`` -- the block length of this instantiation. Must be between 4 + and 8 - - ``Nk`` -- The key length of this instantiation. Must be between 4 and 8. + - ``Nk`` -- the key length of this instantiation. Must be between 4 and 8 - - ``state_chr`` -- The variable name for polynomials representing - elements from state matrices. + - ``state_chr`` -- the variable name for polynomials representing + elements from state matrices - - ``key_chr`` -- The variable name for polynomials representing - elements of the key schedule. + - ``key_chr`` -- the variable name for polynomials representing + elements of the key schedule EXAMPLES:: @@ -575,19 +575,17 @@ def __call__(self, text, key, algorithm='encrypt', format='hex'): INPUT: - - ``text`` -- A plaintext to encrypt or a ciphertext to decrypt. + - ``text`` -- a plaintext to encrypt or a ciphertext to decrypt - - ``key`` -- The key to encrypt/decrypt ``text`` with. + - ``key`` -- the key to encrypt/decrypt ``text`` with - - ``algorithm`` -- Whether to encrypt or decrypt ``text``. Flag for - encryption is "encrypt", flag for decryption is "decrypt". + - ``algorithm`` -- whether to encrypt or decrypt ``text``. Flag for + encryption is "encrypt", flag for decryption is "decrypt" - - ``format`` -- The format of ``text`` and ``key``, either "hex" or + - ``format`` -- the format of ``text`` and ``key``, either "hex" or "binary" - OUTPUT: - - - The encrypted or decrypted message ``text`` with key ``key``. + OUTPUT: the encrypted or decrypted message ``text`` with key ``key`` EXAMPLES:: @@ -679,11 +677,11 @@ def _hex_to_GF(self, H, matrix=True): INPUT: - - ``H`` -- A hex string where every two hex characters correspond to a + - ``H`` -- a hex string where every two hex characters correspond to a single element in `\GF{2^8}` - - ``matrix`` -- (default: ``True``) Return a list if ``False``; - return a state matrix if ``True``. + - ``matrix`` -- boolean (default: ``True``); return a list if ``False``. + Return a state matrix if ``True`` OUTPUT: @@ -728,7 +726,7 @@ def _GF_to_hex(self, GF): INPUT: - - ``GF`` -- Either a state matrix over `\GF{2^8}`, a list of elements + - ``GF`` -- either a state matrix over `\GF{2^8}`, a list of elements from `\GF{2^8}`, or a single element from `\GF{2^8}` OUTPUT: @@ -795,11 +793,11 @@ def _bin_to_GF(self, B, matrix=True): INPUT: - - ``B`` -- A binary string where every eight bits correspond to a + - ``B`` -- a binary string where every eight bits correspond to a single element in `\GF{2^8}` - - ``matrix`` -- (default: ``True``) Return a list if ``False``. - Return a state matrix over `\GF{2^8}` if ``True``. + - ``matrix`` -- boolean (default: ``True``); return a list if ``False``. + Return a state matrix over `\GF{2^8}` if ``True`` OUTPUT: @@ -855,7 +853,7 @@ def _GF_to_bin(self, GF): INPUT: - - ``GF`` -- Either a state matrix over `\GF{2^8}`, a list of elements + - ``GF`` -- either a state matrix over `\GF{2^8}`, a list of elements from `\GF{2^8}`, or a single element from `\GF{2^8}` OUTPUT: @@ -920,16 +918,14 @@ def encrypt(self, plain, key, format='hex'): INPUT: - - ``plain`` -- The plaintext to be encrypted. + - ``plain`` -- the plaintext to be encrypted - - ``key`` -- The key to encrypt ``plain`` with. + - ``key`` -- the key to encrypt ``plain`` with - - ``format`` -- (default: ``hex``) The string format of ``key`` and - ``plain``, either "hex" or "binary". + - ``format`` -- (default: ``hex``) the string format of ``key`` and + ``plain``, either "hex" or "binary" - OUTPUT: - - - A string of the plaintext ``plain`` encrypted with the key ``key``. + OUTPUT: string of the plaintext ``plain`` encrypted with the key ``key`` EXAMPLES:: @@ -1009,12 +1005,12 @@ def decrypt(self, ciphertext, key, format='hex'): INPUT: - - ``ciphertext`` -- The ciphertext to be decrypted. + - ``ciphertext`` -- the ciphertext to be decrypted - - ``key`` -- The key to decrypt ``ciphertext`` with. + - ``key`` -- the key to decrypt ``ciphertext`` with - - ``format`` -- (default: ``hex``) The string format that both - ``ciphertext`` and ``key`` must be in, either "hex" or "binary". + - ``format`` -- (default: ``hex``) the string format that both + ``ciphertext`` and ``key`` must be in, either "hex" or "binary" OUTPUT: @@ -1100,13 +1096,13 @@ def _check_valid_PRmatrix(self, PRm, keyword): INPUT: - - ``PRm`` -- If ``PRm`` is a `4 \times Nb` matrix with entries from + - ``PRm`` -- if ``PRm`` is a `4 \times Nb` matrix with entries from the multivariate PolynomialRing ``_all_PR``, this method does nothing `\GF{2^8}`, this method does nothing. Otherwise, this method raises an error. Note that a matrix of elements from `\GF{2^8}` is regarded as a matrix with entries from ``_all_PR`` and will pass this test. - - ``keyword`` -- The name of the keyword ``PRm`` from where this + - ``keyword`` -- the name of the keyword ``PRm`` from where this method was called, for the potential error message. For example, if called from ``sub_bytes``, ``keyword`` would be "state". @@ -1164,8 +1160,8 @@ def expand_key(self, key): INPUT: - - ``key`` -- The key to build a key schedule from. Must be a matrix - over `\GF{2^8}` of dimensions `4 \times N_k`. + - ``key`` -- the key to build a key schedule from. Must be a matrix + over `\GF{2^8}` of dimensions `4 \times N_k` OUTPUT: @@ -1232,11 +1228,11 @@ def expand_key_poly(self, row, col, round): INPUT: - - ``row`` -- The row position of the element represented by this - polynomial. + - ``row`` -- the row position of the element represented by this + polynomial - - ``col`` -- The column position of the element represented by this - polynomial. + - ``col`` -- the column position of the element represented by this + polynomial OUTPUT: @@ -1323,24 +1319,24 @@ def apply_poly(self, state, poly_constr, algorithm='encrypt', keys=None, INPUT: - - ``state`` -- The state matrix over `\GF{2^8}` to which - ``poly_method`` is applied to. + - ``state`` -- the state matrix over `\GF{2^8}` to which + ``poly_method`` is applied to - - ``poly_constr`` -- The ``Round_Component_Poly_Constr`` object to - build polynomials during evaluation. + - ``poly_constr`` -- the ``Round_Component_Poly_Constr`` object to + build polynomials during evaluation - - ``algorithm`` -- (default: "encrypt") Passed directly to - ``rcpc`` to select encryption or decryption. The - encryption flag is "encrypt" and the decrypt flag is "decrypt". + - ``algorithm`` -- (default: ``'encrypt'``) passed directly to + ``rcpc`` to select encryption or decryption; the + encryption flag is "encrypt" and the decrypt flag is "decrypt" - - ``keys`` -- (default: None) An array of `N_r` subkey matrices to + - ``keys`` -- (default: ``None``) an array of `N_r` subkey matrices to replace any key variables in any polynomials returned by ``poly_method``. Must be identical to the format returned by ``expand_key``. If any polynomials have key variables and ``keys`` is not supplied, the key variables will remain as-is. - - ``poly_constr_attr`` -- (default:None) A dictionary of keyword - attributes to pass to ``rcpc`` when it is called. + - ``poly_constr_attr`` -- (default: ``None``) a dictionary of keyword + attributes to pass to ``rcpc`` when it is called OUTPUT: @@ -1448,25 +1444,25 @@ def compose(self, f, g, algorithm='encrypt', f_attr=None, g_attr=None): INPUT: - - ``f`` -- A ``Round_Component_Poly_Constr`` object corresponding to - a round component function `f`. + - ``f`` -- a ``Round_Component_Poly_Constr`` object corresponding to + a round component function `f` - - ``g`` -- A ``Round_Component_Poly_Constr`` object corresponding to + - ``g`` -- a ``Round_Component_Poly_Constr`` object corresponding to a round component function `g` or a polynomial output of this object's ``__call__`` method. - - ``algorithm`` -- (default: "encrypt") Whether ``f`` and ``g`` + - ``algorithm`` -- (default: ``'encrypt'``) whether ``f`` and ``g`` should use their encryption transformations or their decryption transformations. Does nothing if ``g`` is a ``Round_Component_Poly_Constr`` object. The encryption flag is "encrypt" and the decryption flag is "decrypt". - - ``f_attr`` -- (default: None) A dictionary of keyword attributes to - pass to ``f`` when it is called. + - ``f_attr`` -- (default: ``None``) a dictionary of keyword attributes to + pass to ``f`` when it is called - - ``g_attr`` -- (default: None) A dictionary of keyword attributes to - pass to ``g`` when it is called. Does nothing if ``g`` is a - polynomial. + - ``g_attr`` -- (default: ``None``) a dictionary of keyword attributes to + pass to ``g`` when it is called; does nothing if ``g`` is a + polynomial OUTPUT: @@ -1646,18 +1642,18 @@ def _add_round_key_pc(self, row, col, algorithm='encrypt', round=0): INPUT: - - ``row`` -- The row number of the entry represented by this method's - output. + - ``row`` -- the row number of the entry represented by this method's + output - - ``col`` -- The column number of the entry represented by this - method's output. + - ``col`` -- the column number of the entry represented by this + method's output - - ``algorithm`` -- (default: "encrypt") Whether to return the - polynomial as an encryption or as a decryption. The encryption flag - is "encrypt" and the decryption flag is "decrypt". + - ``algorithm`` -- (default: ``'encrypt'``) whether to return the + polynomial as an encryption or as a decryption; the encryption flag + is "encrypt" and the decryption flag is "decrypt" - - ``round`` -- (default: 0) The round number of the entry represented - by this method's output. + - ``round`` -- (default: 0) the round number of the entry represented + by this method's output OUTPUT: @@ -1693,9 +1689,9 @@ def add_round_key(self, state, round_key): INPUT: - - ``state`` -- The state matrix to have ``round_key`` added to. + - ``state`` -- the state matrix to have ``round_key`` added to - - ``round_key`` -- The round key to add to ``state``. + - ``round_key`` -- the round key to add to ``state`` OUTPUT: @@ -1804,20 +1800,20 @@ def _sub_bytes_pc(self, row, col, algorithm='encrypt', no_inversion=False): INPUT: - - ``row`` -- The row number of the entry represented by this method's - output. + - ``row`` -- the row number of the entry represented by this method's + output - - ``col`` -- The column number of the entry represented by this - method's output. + - ``col`` -- the column number of the entry represented by this + method's output - - ``algorithm`` -- (default: "encrypt") Whether to return the + - ``algorithm`` -- (default: ``'encrypt'``) whether to return the polynomial as an encryption or as a decryption. The encryption flag is "encrypt" and the decryption flag is "decrypt". - - ``no_inversion`` -- (default: ``False``) Don't perform the inversion - step, only perform the affine transformation. Primarily intended - to increase performance during decryption, as is shown in the - below example. + - ``no_inversion`` -- boolean (default: ``False``); don't perform the + inversion step, only perform the affine transformation. Primarily + intended to increase performance during decryption, as is shown in + the below example. OUTPUT: @@ -1887,17 +1883,15 @@ def _srd(self, el, algorithm='encrypt'): INPUT: - - ``el`` -- An element of `\GF{2^8}`. + - ``el`` -- an element of `\GF{2^8}` - - ``algorithm`` -- (default: "encrypt") Whether to perform the + - ``algorithm`` -- (default: ``'encrypt'``) whether to perform the encryption transformation or the decryption transformation. The encryption flag is "encrypt" and the decryption flag is "decrypt". - OUTPUT: - - - The result of the application of the non-linear transformation - SubBytes to ``el``. + OUTPUT: the result of the application of the non-linear transformation + SubBytes to ``el``. EXAMPLES:: @@ -1925,16 +1919,14 @@ def sub_bytes(self, state, algorithm='encrypt'): INPUT: - - ``state`` -- The state matrix to apply SubBytes to. + - ``state`` -- the state matrix to apply SubBytes to - - ``algorithm`` -- (default: "encrypt") Whether to apply the + - ``algorithm`` -- (default: ``'encrypt'``) whether to apply the encryption step of SubBytes or its decryption inverse. The encryption flag is "encrypt" and the decryption flag is "decrypt". - OUTPUT: - - - The state matrix over `\GF{2^8}` where SubBytes has been applied - to every entry of ``state``. + OUTPUT: the state matrix over `\GF{2^8}` where SubBytes has been + applied to every entry of ``state`` EXAMPLES:: @@ -1980,21 +1972,19 @@ def _mix_columns_pc(self, row, col, algorithm='encrypt'): INPUT: - - ``row`` -- The row number of the entry represented by this method's - output. - - - ``col`` -- The column number of the entry represented by this - method's output. + - ``row`` -- the row number of the entry represented by this method's + output - - ``algorithm`` -- (default: "encrypt") Whether to perform the - encryption transformation or the decryption transformation. The - encryption flag is "encrypt" and the decryption flag is "decrypt". + - ``col`` -- the column number of the entry represented by this + method's output - OUTPUT: + - ``algorithm`` -- (default: ``'encrypt'``) whether to perform the + encryption transformation or the decryption transformation; the + encryption flag is "encrypt" and the decryption flag is "decrypt" - - A polynomial in terms of entries of the input state matrix which - represents the ``row,col`` th entry of the output matrix after - MixColumns has been applied to it. + OUTPUT: a polynomial in terms of entries of the input state matrix + which represents the ``row,col`` th entry of the output matrix after + MixColumns has been applied to it EXAMPLES:: @@ -2030,16 +2020,14 @@ def mix_columns(self, state, algorithm='encrypt'): INPUT: - - ``state`` -- The state matrix to apply MixColumns to. + - ``state`` -- the state matrix to apply MixColumns to - - ``algorithm`` -- (default: "encrypt") Whether to perform the - encryption version of MixColumns, or its decryption inverse. The - encryption flag is "encrypt" and the decryption flag is "decrypt". - - OUTPUT: + - ``algorithm`` -- (default: ``'encrypt'``) whether to perform the + encryption version of MixColumns, or its decryption inverse; the + encryption flag is "encrypt" and the decryption flag is "decrypt" - - The state matrix over `\GF{2^8}` which is the result of applying - MixColumns to ``state``. + OUTPUT: the state matrix over `\GF{2^8}` which is the result of + applying MixColumns to ``state`` EXAMPLES:: @@ -2082,21 +2070,19 @@ def _shift_rows_pc(self, row, col, algorithm='encrypt'): INPUT: - - ``row`` -- The row number of the entry represented by this method's - output. + - ``row`` -- the row number of the entry represented by this method's + output - - ``col`` -- The column number of the entry represented by this - method's output. + - ``col`` -- the column number of the entry represented by this + method's output - - ``algorithm`` -- (default: "encrypt") Whether to perform ShiftRows' + - ``algorithm`` -- (default: ``'encrypt'``) whether to perform ShiftRows' encryption step or its decryption inverse. The encryption flag is "encrypt" and the decryption flag is "decrypt". - OUTPUT: - - - A polynomial in terms of entries of the input state matrix which - represents the ``row,col`` th entry of the output matrix after - ShiftRows has been applied to it. + OUTPUT: a polynomial in terms of entries of the input state matrix + which represents the ``row,col`` th entry of the output matrix after + ShiftRows has been applied to it EXAMPLES:: @@ -2133,17 +2119,15 @@ def shift_rows(self, state, algorithm='encrypt'): INPUT: - - ``state`` -- A state matrix over `\GF{2^8}` to which ShiftRows is - applied to. + - ``state`` -- a state matrix over `\GF{2^8}` to which ShiftRows is + applied to - - ``algorithm`` -- (default: "encrypt") Whether to perform the - encryption version of ShiftRows or its decryption inverse. The - encryption flag is "encrypt" and the decryption flag is "decrypt". - - OUTPUT: + - ``algorithm`` -- (default: ``'encrypt'``) whether to perform the + encryption version of ShiftRows or its decryption inverse; the + encryption flag is "encrypt" and the decryption flag is "decrypt" - - A state matrix over `\GF{2^8}` which is the application of ShiftRows - to ``state``. + OUTPUT: a state matrix over `\GF{2^8}` which is the application of + ShiftRows to ``state`` EXAMPLES:: @@ -2169,7 +2153,7 @@ def __init__(self, polynomial_constr, rgf, round_component_name=None): INPUT: - - ``polynomial_constr`` -- A function which takes an index + - ``polynomial_constr`` -- a function which takes an index ``row,col`` and returns a polynomial representing the ``row,col`` th entry of a matrix after a specific round component function has been applied to it. This polynomial must be in terms of @@ -2179,12 +2163,12 @@ def __init__(self, polynomial_constr, rgf, round_component_name=None): algorithm='encrypt', **kwargs)`` and must be able to be called as ``polynomial_constr(row, col)``. - - ``rgf`` -- The RijndaelGF object whose state entries are - represented by polynomials returned from ``polynomial_constr``. + - ``rgf`` -- the RijndaelGF object whose state entries are + represented by polynomials returned from ``polynomial_constr`` - - ``round_component_name`` -- The name of the round component - function this object corresponds to as a string. Used solely - for display purposes. + - ``round_component_name`` -- the name of the round component + function this object corresponds to as a string; used solely + for display purposes EXAMPLES:: @@ -2293,16 +2277,16 @@ def __call__(self, row, col, algorithm='encrypt', **kwargs): INPUT: - - ``row`` -- The row number to pass to ``polynomial_constr``. + - ``row`` -- the row number to pass to ``polynomial_constr`` - - ``col`` -- The column number to pass to ``polynomial_constr``. + - ``col`` -- the column number to pass to ``polynomial_constr`` - - ``algorithm`` -- (default: 'encrypt') The algorithm keyword - to pass to ``polynomial_constr``. + - ``algorithm`` -- (default: ``'encrypt'``) the algorithm keyword + to pass to ``polynomial_constr`` - - ``**kwargs`` -- Keyword arguments to pass to + - ``**kwargs`` -- keyword arguments to pass to ``polynomial_constr``. Keyword arguments will vary depending - on ``polynomial_constr``. + on ``polynomial_constr`` OUTPUT: diff --git a/src/sage/crypto/mq/sr.py b/src/sage/crypto/mq/sr.py index 01753004526..8c372a22e92 100644 --- a/src/sage/crypto/mq/sr.py +++ b/src/sage/crypto/mq/sr.py @@ -332,11 +332,11 @@ def SR(n=1, r=1, c=1, e=4, star=False, **kwargs): INPUT: - - ``n`` -- the number of rounds (default: 1) - - ``r`` -- the number of rows in the state array (default: 1) - - ``c`` -- the number of columns in the state array (default: 1) - - ``e`` -- the exponent of the finite extension field (default: 4) - - ``star`` -- determines if SR\* or SR should be constructed (default: ``False``) + - ``n`` -- the number of rounds (default: 1) + - ``r`` -- the number of rows in the state array (default: 1) + - ``c`` -- the number of columns in the state array (default: 1) + - ``e`` -- the exponent of the finite extension field (default: 4) + - ``star`` -- determines if SR\* or SR should be constructed (default: ``False``) - ``aes_mode`` -- as the SR key schedule specification differs slightly from the AES key schedule, this parameter controls which schedule to use (default: ``True``) @@ -344,18 +344,17 @@ def SR(n=1, r=1, c=1, e=4, star=False, **kwargs): over `\GF{2^e}` (default: ``False``) - ``polybori`` -- use the ``BooleanPolynomialRing`` as polynomial representation (default: ``True``, `\GF{2}` only) - - ``order`` -- a string to specify the term ordering of the + - ``order`` -- string to specify the term ordering of the variables (default: ``deglex``) - - ``postfix`` -- a string which is appended after the variable name - (default: '') - - ``allow_zero_inversions`` -- a boolean to control whether zero + - ``postfix`` -- string which is appended after the variable name + (default: ``''``) + - ``allow_zero_inversions`` -- boolean to control whether zero inversions raise an exception (default: ``False``) - ``correct_only`` -- only include correct inversion polynomials (default: ``False``, `\GF{2}` only) - ``biaffine_only`` -- only include bilinear and biaffine inversion polynomials (default: ``True``, `\GF{2}` only) - EXAMPLES:: sage: sr = mq.SR(1, 1, 1, 4) @@ -602,7 +601,7 @@ def _repr_(self): def base_ring(self): r""" - Return the base field of self as determined by + Return the base field of ``self`` as determined by ``self.e``. EXAMPLES:: @@ -672,7 +671,7 @@ def sub_bytes(self, d): INPUT: - - ``d`` -- state array or something coercible to a state array + - ``d`` -- state array or something coercible to a state array EXAMPLES:: @@ -697,8 +696,7 @@ def sub_byte(self, b): INPUT: - - ``b`` -- an element in ``self.base_ring()`` - + - ``b`` -- an element in ``self.base_ring()`` EXAMPLES: @@ -919,10 +917,7 @@ def mix_columns(self, d): INPUT: - - - ``d`` -- state array or something coercible to a - state array - + - ``d`` -- state array or something coercible to a state array EXAMPLES:: @@ -969,13 +964,9 @@ def add_round_key(self, d, key): INPUT: + - ``d`` -- state array or something coercible to a state array - - ``d`` -- state array or something coercible to a - state array - - - ``key`` -- state array or something coercible to a - state array - + - ``key`` -- state array or something coercible to a state array EXAMPLES:: @@ -996,9 +987,7 @@ def state_array(self, d=None): INPUT: - - - ``d`` -- a matrix, a list, or a tuple (default: ``None``) - + - ``d`` -- a matrix, a list, or a tuple (default: ``None``) EXAMPLES:: @@ -1077,30 +1066,27 @@ def random_state_array(self, *args, **kwds): def random_vector(self, *args, **kwds): r""" Return a random vector as it might appear in the algebraic - expression of self. + expression of ``self``. EXAMPLES:: sage: mq.SR(2, 2, 2, 4).random_vector().parent() Full MatrixSpace of 16 by 1 dense matrices over Finite Field in a of size 2^4 - .. note:: + .. NOTE:: `\phi` was already applied to the result. """ return self.vector(self.random_state_array(*args, **kwds)) - def random_element(self, elem_type="vector", *args, **kwds): + def random_element(self, elem_type='vector', *args, **kwds): """ - Return a random element for self. Other arguments and keywords are + Return a random element for ``self``. Other arguments and keywords are passed to random_* methods. INPUT: - - - ``elem_type`` -- either 'vector' or 'state array' - (default: ``'vector'``) - + - ``elem_type`` -- either 'vector' or 'state array' (default: ``'vector'``) EXAMPLES:: @@ -1373,18 +1359,16 @@ def __call__(self, P, K): return _type(P) - def hex_str(self, M, typ="matrix"): + def hex_str(self, M, typ='matrix'): r""" Return a hex string for the provided AES state array/matrix. INPUT: + - ``M`` -- state array - - ``M`` -- state array - - - ``typ`` -- controls what to return, either 'matrix' - or 'vector' (default: ``'matrix'``) - + - ``typ`` -- controls what to return, either 'matrix' + or 'vector' (default: ``'matrix'``) EXAMPLES:: @@ -1414,9 +1398,7 @@ def hex_str_matrix(self, M): INPUT: - - - ``M`` -- an AES state array - + - ``M`` -- an AES state array EXAMPLES:: @@ -1445,9 +1427,7 @@ def hex_str_vector(self, M): INPUT: - - - ``M`` -- an AES state array - + - ``M`` -- an AES state array EXAMPLES:: @@ -1474,15 +1454,13 @@ def _insert_matrix_into_matrix(self, dst, src, row, col): INPUT: + - ``dst`` -- a matrix - - ``dst`` -- a matrix - - - ``src`` -- a matrix - - - ``row`` -- offset row + - ``src`` -- a matrix - - ``col`` -- offset columns + - ``row`` -- offset row + - ``col`` -- offset columns EXAMPLES:: @@ -1518,11 +1496,10 @@ def varformatstr(self, name, n=None, rc=None, e=None): INPUT: - - ``name`` -- name of the variable - - ``n`` -- number of rounds (default: ``None``) - - ``rc`` -- number of rows \* number of cols (default: ``None``) - - ``e`` -- exponent of base field (default: ``None``) - + - ``name`` -- name of the variable + - ``n`` -- number of rounds (default: ``None``) + - ``rc`` -- number of rows \* number of cols (default: ``None``) + - ``e`` -- exponent of base field (default: ``None``) EXAMPLES:: @@ -1584,7 +1561,6 @@ def varstrs(self, name, nr, rc=None, e=None): sage: sr = mq.SR(10, 1, 2, 4) sage: sr.varstrs('x', 2) ('x200', 'x201', 'x202', 'x203', 'x210', 'x211', 'x212', 'x213') - """ if rc is None: rc = self.r * self.c @@ -1614,7 +1590,6 @@ def vars(self, name, nr, rc=None, e=None): sage: sr = mq.SR(10, 1, 2, 4) sage: sr.vars('x', 2) (x200, x201, x202, x203, x210, x211, x212, x213) - """ gd = self.variable_dict() return tuple([gd[s] for s in self.varstrs(name, nr, rc, e)]) @@ -1671,7 +1646,6 @@ def variable_dict(self): 'x101': x101, 'x102': x102, 'x103': x103} - """ try: R,gd = self._variable_dict @@ -1688,7 +1662,7 @@ def variable_dict(self): def block_order(self): """ - Return a block order for self where each round is a block. + Return a block order for ``self`` where each round is a block. EXAMPLES:: @@ -1821,15 +1795,11 @@ def round_polynomials(self, i, plaintext=None, ciphertext=None): INPUT: + - ``i`` -- round number - - ``i`` -- round number - - - ``plaintext`` -- optional plaintext (mandatory in - first round) - - - ``ciphertext`` -- optional ciphertext (mandatory in - last round) + - ``plaintext`` -- plaintext (optional, mandatory in first round) + - ``ciphertext`` -- ciphertext (optional, mandatory in last round) OUTPUT: tuple @@ -1891,19 +1861,19 @@ def key_schedule_polynomials(self, i): INPUT: - - ``i`` -- round (`0 \leq i \leq n`) + - ``i`` -- round (`0 \leq i \leq n`) EXAMPLES:: sage: sr = mq.SR(1, 1, 1, 4, gf2=True, polybori=False) - The 0-th subkey is the user provided key, so only conjugacy + The `0`-th subkey is the user provided key, so only conjugacy relations or field polynomials are added.:: sage: sr.key_schedule_polynomials(0) (k000^2 + k000, k001^2 + k001, k002^2 + k002, k003^2 + k003) - The 1-th subkey is derived from the user provided key according to + The 1st subkey is derived from the user provided key according to the key schedule which is non-linear.:: sage: sr.key_schedule_polynomials(1) @@ -2138,12 +2108,13 @@ class SR_gf2n(SR_generic): """ def vector(self, d=None): """ - Constructs a vector suitable for the algebraic representation of + Construct a vector suitable for the algebraic representation of SR, i.e. BES. INPUT: - - ``d`` -- values for vector, must be understood by ``self.phi`` (default:``None``) + - ``d`` -- values for vector, must be understood by ``self.phi`` + (default: ``None``) EXAMPLES:: @@ -2192,13 +2163,13 @@ def is_vector(self, d): def phi(self, l): r""" - The operation `\phi` from [MR2002]_ + The operation `\phi` from [MR2002]_. Projects state arrays to their algebraic representation. INPUT: - - ``l`` -- element to perform `\phi` on. + - ``l`` -- element to perform `\phi` on EXAMPLES:: @@ -2296,8 +2267,7 @@ def lin_matrix(self, length=None): INPUT: - - ``length`` -- length of state space (default: ``None``) - + - ``length`` -- length of state space (default: ``None``) EXAMPLES:: @@ -2420,13 +2390,11 @@ def inversion_polynomials(self, xi, wi, length): INPUT: + - ``xi`` -- output variables - - ``xi`` -- output variables - - - ``wi`` -- input variables - - - ``length`` -- length of both lists + - ``wi`` -- input variables + - ``length`` -- length of both lists EXAMPLES:: @@ -2453,9 +2421,9 @@ def field_polynomials(self, name, i, l=None): INPUT: - - ``name`` -- variable name - - ``i`` -- round number - - ``l`` -- r\*c (default: ``None``) + - ``name`` -- variable name + - ``i`` -- round number + - ``l`` -- r\*c (default: ``None``) EXAMPLES:: @@ -2498,13 +2466,12 @@ def __init__(self, n=1, r=1, c=1, e=4, star=False, **kwargs): def vector(self, d=None): """ - Constructs a vector suitable for the algebraic representation of + Construct a vector suitable for the algebraic representation of SR. INPUT: - - ``d`` -- values for vector (default: ``None``) - + - ``d`` -- values for vector (default: ``None``) EXAMPLES:: @@ -2548,9 +2515,7 @@ def is_vector(self, d): INPUT: - - - ``d`` -- matrix - + - ``d`` -- matrix EXAMPLES:: @@ -2572,14 +2537,14 @@ def is_vector(self, d): def phi(self, l, diffusion_matrix=False): r""" - The operation `\phi` from [MR2002]_ + The operation `\phi` from [MR2002]_. Given a list/matrix of elements in `\GF{2^e}`, return a matching list/matrix of elements in `\GF{2}`. INPUT: - - ``l`` -- element to perform `\phi` on. + - ``l`` -- element to perform `\phi` on - ``diffusion_matrix`` -- if ``True``, the given matrix ``l`` is transformed to a matrix which performs the same operation over `\GF{2}` as ``l`` over `\GF{2^n}` (default: ``False``). @@ -2740,8 +2705,7 @@ def lin_matrix(self, length=None): INPUT: - - ``length`` -- length of state space (default: ``None``) - + - ``length`` -- length of state space (default: ``None``) EXAMPLES:: @@ -2788,9 +2752,7 @@ def _mul_matrix(self, x): INPUT: - - - ``x`` -- an element in self.base_ring() - + - ``x`` -- an element in self.base_ring() EXAMPLES:: @@ -3135,13 +3097,11 @@ def inversion_polynomials(self, xi, wi, length): INPUT: + - ``xi`` -- output variables - - ``xi`` -- output variables - - - ``wi`` -- input variables - - - ``length`` -- length of both lists + - ``wi`` -- input variables + - ``length`` -- length of both lists EXAMPLES:: @@ -3171,9 +3131,9 @@ def field_polynomials(self, name, i, l=None): INPUT: - - ``name`` -- variable name - - ``i`` -- round number - - ``l`` -- length of variable list (default: ``None`` = r\*c) + - ``name`` -- variable name + - ``i`` -- round number + - ``l`` -- length of variable list (default: ``None`` = r\*c) EXAMPLES:: @@ -3219,7 +3179,7 @@ def inversion_polynomials_single_sbox(self, x=None, w=None, biaffine_only=None, - ``w`` -- input variables (default: ``None``) - ``biaffine_only`` -- ignored (always ``False``) - ``correct_only`` -- ignored (always ``True``) - - ``groebner`` -- precompute the Groebner basis for this S-Box (default: ``False``). + - ``groebner`` -- precompute the Groebner basis for this S-Box (default: ``False``) EXAMPLES:: @@ -3273,7 +3233,6 @@ def inversion_polynomials_single_sbox(self, x=None, w=None, biaffine_only=None, sage: l = sr.inversion_polynomials_single_sbox() # needs sage.libs.singular sage: l == sr.inversion_polynomials_single_sbox(biaffine_only=True, correct_only=False) # needs sage.libs.singular True - """ e = self.e if x is None and w is None: diff --git a/src/sage/crypto/public_key/blum_goldwasser.py b/src/sage/crypto/public_key/blum_goldwasser.py index 1d090673400..c4338ae46af 100644 --- a/src/sage/crypto/public_key/blum_goldwasser.py +++ b/src/sage/crypto/public_key/blum_goldwasser.py @@ -162,12 +162,10 @@ def __eq__(self, other): INPUT: - - ``other`` -- a ``BlumGoldwasser`` object. + - ``other`` -- a ``BlumGoldwasser`` object - OUTPUT: - - - ``True`` if both ``self`` and ``other`` are ``BlumGoldwasser`` - objects. ``False`` otherwise. + OUTPUT: ``True`` if both ``self`` and ``other`` are ``BlumGoldwasser`` + objects; ``False`` otherwise Two objects are ``BlumGoldwasser`` objects if their string representations are the same. @@ -214,7 +212,7 @@ def decrypt(self, C, K): `t+1`-th iteration of the Blum-Blum-Shub algorithm. - ``K`` -- a private key `(p, q, a, b)` where `p` and `q` are - distinct Blum primes and `\gcd(p, q) = ap + bq = 1`. + distinct Blum primes and `\gcd(p, q) = ap + bq = 1` OUTPUT: @@ -361,7 +359,7 @@ def encrypt(self, P, K, seed=None): a string of ASCII characters. Where ``P`` is an ASCII string, then ``P`` is first encoded as a binary string prior to encryption. - - ``K`` -- a public key, which is the product of two Blum primes. + - ``K`` -- a public key, which is the product of two Blum primes - ``seed`` -- (default: ``None``) if `p` and `q` are Blum primes and `n = pq` is a public key, then ``seed`` is a quadratic residue in @@ -537,14 +535,12 @@ def private_key(self, p, q): INPUT: - - ``p`` -- a Blum prime. + - ``p`` -- a Blum prime - - ``q`` -- a Blum prime. + - ``q`` -- a Blum prime - OUTPUT: - - - The Blum-Goldwasser private key `(p, q, a, b)` where - `\gcd(p, q) = ap + bq = 1`. + OUTPUT: the Blum-Goldwasser private key `(p, q, a, b)` where + `\gcd(p, q) = ap + bq = 1` Both ``p`` and ``q`` must be distinct Blum primes. Let `p` be a positive prime. Then `p` is a Blum prime if `p` is congruent to 3 @@ -613,13 +609,11 @@ def public_key(self, p, q): INPUT: - - ``p`` -- a Blum prime. - - - ``q`` -- a Blum prime. + - ``p`` -- a Blum prime - OUTPUT: + - ``q`` -- a Blum prime - - The Blum-Goldwasser public key `n = pq`. + OUTPUT: the Blum-Goldwasser public key `n = pq` Both ``p`` and ``q`` must be distinct Blum primes. Let `p` be a positive prime. Then `p` is a Blum prime if `p` is congruent to 3 diff --git a/src/sage/crypto/sbox.pyx b/src/sage/crypto/sbox.pyx index b786af7b0f3..85c8a562ddd 100644 --- a/src/sage/crypto/sbox.pyx +++ b/src/sage/crypto/sbox.pyx @@ -129,7 +129,7 @@ cdef class SBox(SageObject): - ``S`` -- a finite iterable defining the S-box with integer or finite field elements - - ``big_endian`` -- (default: ``True``) controls whether bits + - ``big_endian`` -- boolean (default: ``True``); controls whether bits shall be ordered in big endian order EXAMPLES: @@ -275,7 +275,7 @@ cdef class SBox(SageObject): INPUT: - - ``x`` -- an integer + - ``x`` -- integer - ``n`` -- bit length (optional) @@ -417,7 +417,7 @@ cdef class SBox(SageObject): sage: all([x == id(x) for x in k]) True - Some examples for inputs that throw an :class:`TypeError`:: + Some examples for inputs that throw an :exc:`TypeError`:: sage: S([1]*10^6) Traceback (most recent call last): @@ -563,7 +563,7 @@ cdef class SBox(SageObject): def derivative(self, u): r""" - Return the derivative in direction of ``u`` + Return the derivative in direction of ``u``. INPUT: @@ -746,7 +746,7 @@ cdef class SBox(SageObject): return self.maximal_difference_probability_absolute() / (2.0**self.output_size()) @cached_method - def linear_approximation_table(self, scale="absolute_bias"): + def linear_approximation_table(self, scale='absolute_bias'): r""" Return linear approximation table (LAT) `A` for this S-box. @@ -791,13 +791,13 @@ cdef class SBox(SageObject): [ 0 -2 -2 0 0 -2 2 0] [ 0 -2 2 0 -2 0 0 -2] - sage: lat_abs_bias/(1 << S.input_size()) == S.linear_approximation_table(scale="bias") + sage: lat_abs_bias/(1 << S.input_size()) == S.linear_approximation_table(scale='bias') True - sage: lat_abs_bias/(1 << (S.input_size()-1)) == S.linear_approximation_table(scale="correlation") + sage: lat_abs_bias/(1 << (S.input_size()-1)) == S.linear_approximation_table(scale='correlation') True - sage: lat_abs_bias*2 == S.linear_approximation_table(scale="fourier_coefficient") + sage: lat_abs_bias*2 == S.linear_approximation_table(scale='fourier_coefficient') True According to this table the first bit of the input is equal @@ -946,8 +946,8 @@ cdef class SBox(SageObject): - ``degree`` -- (default: ``2``) integer > 0 - - ``groebner`` -- (default: ``False``) calculate a reduced Groebner - basis of the spanning polynomials to obtain more polynomials + - ``groebner`` -- boolean (default: ``False``); calculate a reduced + Groebner basis of the spanning polynomials to obtain more polynomials EXAMPLES:: @@ -1063,7 +1063,7 @@ cdef class SBox(SageObject): field is of degree ``m``. If the output length does not match the input length then a - :class:`TypeError` is raised. + :exc:`TypeError` is raised. INPUT: @@ -1133,13 +1133,13 @@ cdef class SBox(SageObject): represents a variable and the sign of an integer indicates inversion - - ``symbolic`` -- a string that can be parsed by the + - ``symbolic`` -- string that can be parsed by the ``SymbolicLogic`` package - - ``dimacs`` -- a string in DIMACS format which is the gold + - ``dimacs`` -- string in DIMACS format which is the gold standard for SAT-solver input (cf. http://www.satlib.org/) - - ``dimacs_headless`` -- a string in DIMACS format, but without + - ``dimacs_headless`` -- string in DIMACS format, but without the header; this is useful for concatenation of outputs EXAMPLES: @@ -1590,7 +1590,7 @@ cdef class SBox(SageObject): def boomerang_uniformity(self): """ - Return the boomerang uniformity + Return the boomerang uniformity. The boomerang uniformity is defined as the highest entry in the boomerang connectivity table, ignoring the first row and column. @@ -1804,7 +1804,7 @@ cdef class SBox(SageObject): Return the inverse of this S-Box. Note that the S-Box must be invertible, otherwise it will raise - a :class:`TypeError`. + a :exc:`TypeError`. EXAMPLES:: diff --git a/src/sage/crypto/sboxes.py b/src/sage/crypto/sboxes.py index 55590d1a4fe..ab0f2759573 100644 --- a/src/sage/crypto/sboxes.py +++ b/src/sage/crypto/sboxes.py @@ -203,11 +203,12 @@ def carlet_tang_tang_liao(n, c=None, bf=None): INPUT: - - ``n`` -- integer, the bit length of inputs and outputs, has to be even and >= 6 + - ``n`` -- integer; the bit length of inputs and outputs, has to be even + and `\geq 6` - ``c`` -- element of `\GF{2^{n-1}}` used in the construction - (default: random element) - - ``f`` -- Function from `\GF{2^n} \to \GF{2}` or BooleanFunction on `n-1` bits - (default: ``x -> (1/(x+1)).trace())`` + (default: random element) + - ``f`` -- function from `\GF{2^n} \to \GF{2}` or BooleanFunction on `n-1` + bits (default: ``x -> (1/(x+1)).trace())``) EXAMPLES:: @@ -270,7 +271,7 @@ def gold(n, i): INPUT: - ``n`` -- size of the S-Box - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: @@ -293,7 +294,7 @@ def kasami(n, i): INPUT: - ``n`` -- size of the S-Box - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: diff --git a/src/sage/crypto/stream.py b/src/sage/crypto/stream.py index 636f588ad97..4a9ef986b6e 100644 --- a/src/sage/crypto/stream.py +++ b/src/sage/crypto/stream.py @@ -33,9 +33,9 @@ def __init__(self, field=None): """ Create a linear feedback shift cryptosystem. - INPUT: A string monoid over a binary alphabet. + INPUT: - OUTPUT: + - ``field`` -- (default: ``None``) string monoid over a binary alphabet EXAMPLES:: @@ -68,7 +68,9 @@ def __call__(self, key): """ Create a LFSR cipher. - INPUT: A polynomial and initial state of the LFSR. + INPUT: + + - ``key`` -- a polynomial and initial state of the LFSR """ if not isinstance(key, (list, tuple)) and len(key) == 2: raise TypeError("Argument key (= %s) must be a list of tuple of length 2" % key) @@ -107,9 +109,9 @@ def __init__(self, field=None): """ Create a shrinking generator cryptosystem. - INPUT: A string monoid over a binary alphabet. + INPUT: - OUTPUT: + - ``field`` -- (default: ``None``) string monoid over a binary alphabet EXAMPLES:: @@ -129,10 +131,12 @@ def __call__(self, key): """ Create a Shrinking generator cipher. - INPUT: A list or tuple consisting of two LFSR ciphers (e1,e2). + INPUT: + + - ``key`` -- list or tuple consisting of two LFSR ciphers (e1,e2) - OUTPUT: The shrinking generator cipher with key stream generator e1 - and decimating cipher e2. + OUTPUT: the shrinking generator cipher with key stream generator e1 + and decimating cipher e2 """ if not isinstance(key, (list, tuple)) and len(key) == 2: raise TypeError("Argument key (= %s) must be a list of tuple of length 2" % key) @@ -172,7 +176,7 @@ def blum_blum_shub(length, seed=None, p=None, q=None, INPUT: - ``length`` -- positive integer; the number of bits in the output - pseudorandom bit sequence. + pseudorandom bit sequence - ``seed`` -- (default: ``None``) if `p` and `q` are Blum primes, then ``seed`` is a quadratic residue in the multiplicative group @@ -207,9 +211,7 @@ def blum_blum_shub(length, seed=None, p=None, q=None, perform that many attempts at generating a random Blum prime. This might or might not result in a Blum prime. - OUTPUT: - - - A pseudorandom bit sequence whose length is specified by ``length``. + OUTPUT: a pseudorandom bit sequence whose length is specified by ``length`` Here is a common use case for this function. If you want this function to use pre-computed values for `p` and `q`, you should pass diff --git a/src/sage/crypto/stream_cipher.py b/src/sage/crypto/stream_cipher.py index ab9d2dfc815..ef1b44e6f2b 100644 --- a/src/sage/crypto/stream_cipher.py +++ b/src/sage/crypto/stream_cipher.py @@ -21,13 +21,11 @@ def __init__(self, parent, poly, IS): INPUT: + - ``parent`` -- parent - - ``parent`` -- parent - - - ``poly`` -- connection polynomial - - - ``IS`` -- initial state + - ``poly`` -- connection polynomial + - ``IS`` -- initial state EXAMPLES:: @@ -64,17 +62,15 @@ def __init__(self, parent, poly, IS): """ SymmetricKeyCipher.__init__(self, parent, key=(poly, IS)) - def __call__(self, M, mode="ECB"): + def __call__(self, M, mode='ECB'): r""" Generate key stream from the binary string ``M``. INPUT: + - ``M`` -- a StringMonoidElement - - ``M`` -- a StringMonoidElement - - - ``mode`` -- ignored (default: 'ECB') - + - ``mode`` -- ignored (default: ``'ECB'``) EXAMPLES:: @@ -154,13 +150,11 @@ def __init__(self, parent, e1, e2): INPUT: + - ``parent`` -- parent - - ``parent`` -- parent - - - ``poly`` -- connection polynomial - - - ``IS`` -- initial state + - ``poly`` -- connection polynomial + - ``IS`` -- initial state EXAMPLES:: @@ -222,15 +216,13 @@ def decimating_cipher(self): """ return self.key()[1] - def __call__(self, M, mode="ECB"): + def __call__(self, M, mode='ECB'): r""" INPUT: + - ``M`` -- a StringMonoidElement - - ``M`` -- a StringMonoidElement - - - ``mode`` -- ignored (default: 'ECB') - + - ``mode`` -- ignored (default: ``'ECB'``) EXAMPLES:: diff --git a/src/sage/crypto/util.py b/src/sage/crypto/util.py index 8590c83db5c..199d09c2758 100644 --- a/src/sage/crypto/util.py +++ b/src/sage/crypto/util.py @@ -38,11 +38,9 @@ def ascii_integer(B): INPUT: - ``B`` -- a non-empty binary string or a non-empty list of bits. The - number of bits in ``B`` must be 8. + number of bits in ``B`` must be 8 - OUTPUT: - - - The ASCII integer corresponding to the 8-bit block ``B``. + OUTPUT: the ASCII integer corresponding to the 8-bit block ``B`` EXAMPLES: @@ -101,11 +99,9 @@ def ascii_to_bin(A): INPUT: - - ``A`` -- a string or list of ASCII characters. + - ``A`` -- string or list of ASCII characters - OUTPUT: - - - The binary representation of ``A``. + OUTPUT: the binary representation of ``A`` ALGORITHM: @@ -170,11 +166,9 @@ def bin_to_ascii(B): INPUT: - ``B`` -- a non-empty binary string or a non-empty list of bits. The - number of bits in ``B`` must be a multiple of 8. - - OUTPUT: + number of bits in ``B`` must be a multiple of 8 - - The ASCII string corresponding to ``B``. + OUTPUT: the ASCII string corresponding to ``B`` ALGORITHM: @@ -359,11 +353,9 @@ def is_blum_prime(n): INPUT: - - ``n`` a positive prime. - - OUTPUT: + - ``n`` -- a positive prime - - ``True`` if ``n`` is a Blum prime; ``False`` otherwise. + OUTPUT: ``True`` if ``n`` is a Blum prime; ``False`` otherwise Let `n` be a positive prime. Then `n` is a Blum prime if `n` is congruent to 3 modulo 4, i.e. `n \equiv 3 \pmod{4}`. @@ -398,9 +390,9 @@ def least_significant_bits(n, k): INPUT: - - ``n`` -- an integer. + - ``n`` -- integer - - ``k`` -- a positive integer. + - ``k`` -- positive integer OUTPUT: @@ -470,9 +462,7 @@ def random_blum_prime(lbound, ubound, ntries=100): perform that many attempts at generating a random Blum prime. This might or might not result in a Blum prime. - OUTPUT: - - - A random Blum prime within the specified lower and upper bounds. + OUTPUT: a random Blum prime within the specified lower and upper bounds .. NOTE:: diff --git a/src/sage/data_structures/binary_matrix.pxd b/src/sage/data_structures/binary_matrix.pxd index 8827a6a3f66..ce69e036ad2 100644 --- a/src/sage/data_structures/binary_matrix.pxd +++ b/src/sage/data_structures/binary_matrix.pxd @@ -12,7 +12,7 @@ A ``binary_matrix_t`` structure contains: - ``mp_bitcnt_t n_rows`` -- number of rows - ``bitset_t * rows`` -- ``rows[i]`` points toward a block of type ``bitset_t`` - containing the bits of row `i`. + containing the bits of row `i` """ from sage.data_structures.bitset_base cimport * diff --git a/src/sage/data_structures/bitset.pyx b/src/sage/data_structures/bitset.pyx index 9d5e2029407..973102fc2a6 100644 --- a/src/sage/data_structures/bitset.pyx +++ b/src/sage/data_structures/bitset.pyx @@ -62,28 +62,26 @@ cdef class FrozenBitset: INPUT: - - ``iter`` -- initialization parameter (default: ``None``). Valid input + - ``iter`` -- initialization parameter (default: ``None``); valid inputs are: - :class:`Bitset` and :class:`FrozenBitset` -- If this is a - :class:`Bitset` or :class:`FrozenBitset`, then it is copied. + :class:`Bitset` or :class:`FrozenBitset`, then it is copied - - ``None`` -- If ``None``, then the bitset is set to the empty set. + - ``None`` -- if ``None``, then the bitset is set to the empty set - - string -- If a nonempty string, then the bitset is initialized by + - ``string`` -- if a nonempty string, then the bitset is initialized by including an element if the index of the string is ``1``. If the - string is empty, then raise a :class:`ValueError`. + string is empty, then raise a :exc:`ValueError`. - - iterable -- If an iterable, then it is assumed to contain a list of - nonnegative integers and those integers are placed in the set. + - ``iterable`` -- if an iterable, then it is assumed to contain a list of + nonnegative integers and those integers are placed in the set - - ``capacity`` -- (default: ``None``) The maximum capacity of the bitset. + - ``capacity`` -- (default: ``None``) the maximum capacity of the bitset. If this is not specified, then it is automatically calculated from the passed iterable. It must be at least one. - OUTPUT: - - - None. + OUTPUT: none The string representation of a :class:`FrozenBitset` ``FB`` can be understood as follows. Let `B = b_0 b_1 b_2 \cdots b_k` be the string @@ -560,13 +558,7 @@ cdef class FrozenBitset: """ Test if the bitset is empty. - INPUT: - - - None. - - OUTPUT: - - - ``True`` if the bitset is empty; ``False`` otherwise. + OUTPUT: boolean EXAMPLES:: @@ -1184,7 +1176,7 @@ cdef class FrozenBitset: cpdef complement(self): """ - Return the complement of self. + Return the complement of ``self``. EXAMPLES:: @@ -1208,7 +1200,7 @@ cdef class FrozenBitset: def __invert__(self): """ - Return the complement of self. + Return the complement of ``self``. EXAMPLES:: @@ -1799,7 +1791,7 @@ cdef class Bitset(FrozenBitset): """ Update the bitset by removing ``n``. - This raises a :class:`KeyError` if ``n`` is not contained + This raises a :exc:`KeyError` if ``n`` is not contained in the bitset. EXAMPLES:: @@ -1874,7 +1866,7 @@ cdef class Bitset(FrozenBitset): """ Remove and return an arbitrary element from the set. - This raises a :class:`KeyError` if the set is empty. + This raises a :exc:`KeyError` if the set is empty. EXAMPLES:: @@ -2121,7 +2113,6 @@ def test_bitset(py_a, py_b, long n): to size 69 111001111001111001111001111001111001111001111001111001111001111001111 to size 138 111001111001111001111001111001111001111001111001111001111001111001111000000000000000000000000000000000000000000000000000000000000000000000 to original size 111001111001111001111001111001111001111001111001111001111001111001111000000000000000000000000000000000000000000000000000000000000000000000000000000000 - """ cdef bint bit = True cdef bitset_t a, b, r @@ -2279,7 +2270,6 @@ def test_bitset_set_first_n(py_a, long n): sage: from sage.data_structures.bitset import test_bitset_set_first_n sage: test_bitset_set_first_n('00'*64, 128) a.set_first_n(n) 11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111 - """ cdef bint bit = True cdef bitset_t a @@ -2324,7 +2314,7 @@ def test_bitset_remove(py_a, long n): def test_bitset_pop(py_a): """ - Tests for the bitset_pop function. + Test for the bitset_pop function. TESTS:: @@ -2351,11 +2341,10 @@ def test_bitset_unpickle(data): INPUT: - - ``data`` -- A tuple of data as would be produced by the internal, Cython-only, method ``bitset_pickle``. - - OUTPUT: + - ``data`` -- tuple of data as would be produced by the internal, + Cython-only, method ``bitset_pickle`` - A list form of the bitset corresponding to the pickled data. + OUTPUT: list form of the bitset corresponding to the pickled data EXAMPLES: diff --git a/src/sage/data_structures/bitset_base.pxd b/src/sage/data_structures/bitset_base.pxd index f8949d05e78..b2fb299dd9c 100644 --- a/src/sage/data_structures/bitset_base.pxd +++ b/src/sage/data_structures/bitset_base.pxd @@ -274,7 +274,7 @@ cdef inline void bitset_fix(fused_bitset_t bits) noexcept: cdef inline void sparse_bitset_set_non_zero(sparse_bitset_t bits) noexcept nogil: """ - Set the non zero chunks of ``bits``. + Set the nonzero chunks of ``bits``. """ bits.n_non_zero_chunks = _set_non_zero(bits.bits, bits.non_zero_chunks, bits.limbs) bits.non_zero_chunks_are_initialized = True @@ -331,15 +331,15 @@ cdef inline bint mpn_equal_bits_shifted(mp_srcptr b1, mp_srcptr b2, mp_bitcnt_t cdef inline bint bitset_isempty(fused_bitset_t bits) noexcept nogil: """ - Test whether bits is empty. Return True (i.e., 1) if the set is - empty, False (i.e., 0) otherwise. + Test whether bits is empty. Return ``True`` (i.e., 1) if the set is + empty, ``False`` (i.e., 0) otherwise. """ return _bitset_isempty(bits.bits, bits.limbs) cdef inline bint bitset_is_zero(fused_bitset_t bits) noexcept: """ - Test whether bits is empty (i.e., zero). Return True (1) if - the set is empty, False (0) otherwise. + Test whether bits is empty (i.e., zero). Return ``True`` (1) if + the set is empty, ``False`` (0) otherwise. This function is the same as bitset_is_empty(bits). """ @@ -347,8 +347,8 @@ cdef inline bint bitset_is_zero(fused_bitset_t bits) noexcept: cdef inline bint bitset_eq(fused_bitset_t a, fused_bitset_t b) noexcept: """ - Compare bitset a and b. Return True (i.e., 1) if the sets are - equal, and False (i.e., 0) otherwise. + Compare bitset a and b. Return ``True`` (i.e., 1) if the sets are + equal, and ``False`` (i.e., 0) otherwise. We assume ``a.limbs >= b.limbs``. """ @@ -378,7 +378,7 @@ cdef inline int bitset_lex_cmp(fused_bitset_t a, fused_bitset_t b) noexcept: INPUT: - ``a`` -- a bitset - - ``b`` -- a bitset, assumed to have the same size as ``a``. + - ``b`` -- a bitset, assumed to have the same size as ``a`` OUTPUT: @@ -416,7 +416,7 @@ cdef inline bint bitset_issuperset(fused_bitset_t a, fused_bitset_t b) noexcept cdef inline bint bitset_are_disjoint(fused_bitset_t a, fused_bitset_t b) noexcept: """ - Tests whether ``a`` and ``b`` have an empty intersection. + Test whether ``a`` and ``b`` have an empty intersection. We assume ``a.limbs <= b.limbs``. """ @@ -432,15 +432,15 @@ cdef inline bint bitset_are_disjoint(fused_bitset_t a, fused_bitset_t b) noexcep cdef inline bint bitset_in(fused_bitset_t bits, mp_bitcnt_t n) noexcept: """ - Check if n is in bits. Return True (i.e., 1) if n is in the - set, False (i.e., 0) otherwise. + Check if n is in bits. Return ``True`` (i.e., 1) if n is in the + set, ``False`` (i.e., 0) otherwise. """ return (bits.bits[n >> index_shift] >> (n % GMP_LIMB_BITS)) & 1 cdef inline bint bitset_check(fused_bitset_t bits, mp_bitcnt_t n) noexcept: """ - Check if n is in bits. Return True (i.e., 1) if n is in the - set, False (i.e., 0) otherwise. + Check if n is in bits. Return ``True`` (i.e., 1) if n is in the + set, ``False`` (i.e., 0) otherwise. This function is the same as bitset_in(bits, n). """ @@ -448,8 +448,8 @@ cdef inline bint bitset_check(fused_bitset_t bits, mp_bitcnt_t n) noexcept: cdef inline bint bitset_not_in(fused_bitset_t bits, mp_bitcnt_t n) noexcept: """ - Check if n is not in bits. Return True (i.e., 1) if n is not in the - set, False (i.e., 0) otherwise. + Check if n is not in bits. Return ``True`` (i.e., 1) if n is not in the + set, ``False`` (i.e., 0) otherwise. """ return not bitset_in(bits, n) @@ -457,7 +457,7 @@ cdef inline bint bitset_remove(fused_bitset_t bits, mp_bitcnt_t n) except -1: """ Remove ``n`` from ``bits``. - This raises a :class:`KeyError` if ``n`` is not contained in ``bits``. + This raises a :exc:`KeyError` if ``n`` is not contained in ``bits``. """ if not bitset_in(bits, n): raise KeyError(n) @@ -562,7 +562,7 @@ cdef inline long bitset_pop(fused_bitset_t a) except -1: """ Remove and return an arbitrary element from the set. - This raises a :class:`KeyError` if the set is empty. + This raises a :exc:`KeyError` if the set is empty. """ cdef long i = bitset_first(a) if i == -1: @@ -681,7 +681,7 @@ cdef inline void sparse_bitset_intersection(sparse_bitset_t r, fused_bitset_t a, """ Set r to the intersection of a and b, overwriting r. - Also set the non zero positions of ``r``. + Also set the nonzero positions of ``r``. We assume ``a.limbs >= r.limbs == b.limbs``. """ @@ -713,7 +713,7 @@ cdef inline void sparse_bitset_union(sparse_bitset_t r, fused_bitset_t a, fused_ """ Set r to the union of a and b, overwriting r. - Also set the non zero positions of ``r``. + Also set the nonzero positions of ``r``. We assume ``r.limbs >= a.limbs >= b.limbs`` and either ``r is a`` or ``r.limbs == b.limbs``. @@ -749,7 +749,7 @@ cdef inline void sparse_bitset_difference(sparse_bitset_t r, fused_bitset_t a, f Set r to the difference of a and b (i.e., things in a that are not in b), overwriting r. - Also set the non zero positions of ``r``. + Also set the nonzero positions of ``r``. We assume ``r.limbs >= a.limbs >= b.limbs`` and either ``r is a`` or ``r.limbs == b.limbs``. @@ -772,7 +772,7 @@ cdef inline void sparse_bitset_symmetric_difference(sparse_bitset_t r, fused_bit """ Set r to the symmetric difference of a and b, overwriting r. - Also set the non zero positions of ``r``. + Also set the nonzero positions of ``r``. We assume ``r.limbs >= a.limbs >= b.limbs`` and either ``r is a`` or ``r.limbs == b.limbs``. diff --git a/src/sage/data_structures/bitset_intrinsics.h b/src/sage/data_structures/bitset_intrinsics.h index 2e4dd228952..ce9c0f9889d 100644 --- a/src/sage/data_structures/bitset_intrinsics.h +++ b/src/sage/data_structures/bitset_intrinsics.h @@ -246,7 +246,7 @@ static inline int _sparse_bitset_cmp(mp_limb_t* a, mp_bitcnt_t* a_non_zero_chunk static inline long _bitset_first_in_limb_nonzero(mp_limb_t limb){ /* - Given a non-zero limb of a bitset, return the index of the first + Given a nonzero limb of a bitset, return the index of the first nonzero bit. */ #if (__BMI__) && (GMP_LIMB_BITS == 64) && (INTPTR_MAX == INT64_MAX) diff --git a/src/sage/data_structures/blas_dict.pyx b/src/sage/data_structures/blas_dict.pyx index 359ece0690d..baa27e54c22 100644 --- a/src/sage/data_structures/blas_dict.pyx +++ b/src/sage/data_structures/blas_dict.pyx @@ -19,7 +19,7 @@ meaningful in those cases. We are also assuming that ``-1 * x = -x`` and ``bool(x) == bool(-x)`` for all ``x`` in `K`. Unless stated overwise, all values `v` in the dictionaries should be -non zero (as tested with `bool(v)`). +nonzero (as tested with `bool(v)`). This is mostly used by :class:`CombinatorialFreeModule`. """ @@ -208,7 +208,7 @@ cpdef dict negate(dict D): INPUT: - - ``X`` -- a dictionary representing a vector `X` + - ``X`` -- dictionary representing a vector `X` EXAMPLES:: @@ -226,7 +226,7 @@ cpdef dict scal(a, dict D, bint factor_on_left=True): INPUT: - ``a`` -- an element of the base ring `K` - - ``X`` -- a dictionary representing a vector `X` + - ``X`` -- dictionary representing a vector `X` EXAMPLES:: @@ -248,7 +248,7 @@ cpdef dict add(dict D, dict D2): INPUT: - ``D``, ``D2`` -- dictionaries whose values are in a common ring - and all values are non-zero + and all values are nonzero EXAMPLES:: @@ -275,7 +275,7 @@ cpdef dict sum(dict_iter): INPUT: - ``dict_iter`` -- iterator of dictionaries whose values are in - a common ring and all values are non-zero + a common ring and all values are nonzero OUTPUT: @@ -360,7 +360,7 @@ cpdef dict sum_of_monomials(monomials, scalar): INPUT: - - ``monomials`` -- a list (or iterable) of indices representing the monomials + - ``monomials`` -- list (or iterable) of indices representing the monomials - ``scalar`` -- the scalar for each monomial EXAMPLES:: @@ -388,7 +388,7 @@ cpdef dict sum_of_terms(index_coeff_pairs): INPUT: - - ``index_coeff_pairs`` -- a list (or iterable) of pairs ``(index, coeff)`` + - ``index_coeff_pairs`` -- list (or iterable) of pairs ``(index, coeff)`` EXAMPLES:: diff --git a/src/sage/data_structures/bounded_integer_sequences.pxd b/src/sage/data_structures/bounded_integer_sequences.pxd index c87fc914921..ed30b915d14 100644 --- a/src/sage/data_structures/bounded_integer_sequences.pxd +++ b/src/sage/data_structures/bounded_integer_sequences.pxd @@ -1,7 +1,7 @@ from sage.libs.gmp.types cimport * from sage.data_structures.bitset cimport * -# A biseq (bounded integer sequence) is a sequence of non-negative +# A biseq (bounded integer sequence) is a sequence of nonnegative # integers, each fitting in "itembitsize" bits. We store the sequence # in a bitset of length at least length*itembitsize. ctypedef struct biseq_s: @@ -21,7 +21,7 @@ ctypedef struct biseq_s: mp_size_t length # Bitsize (ranging from 1 to GMP_LIMB_BITS) of one item of this - # sequence. Note: Each item is a non-negative integer, and all + # sequence. Note: Each item is a nonnegative integer, and all # items of this sequence satisfy an upper bound. We do not store # the exact bound for the items of this sequence, but store the # bitsize that is sufficient to store one item. diff --git a/src/sage/data_structures/bounded_integer_sequences.pyx b/src/sage/data_structures/bounded_integer_sequences.pyx index 283cde6b1d9..1b23b5ed8a7 100644 --- a/src/sage/data_structures/bounded_integer_sequences.pyx +++ b/src/sage/data_structures/bounded_integer_sequences.pyx @@ -182,7 +182,7 @@ cdef bint biseq_init_list(biseq_t R, list data, size_t bound) except -1: INPUT: - - ``data`` -- a list of integers + - ``data`` -- list of integers - ``bound`` -- a number which is the maximal value of an item """ @@ -235,7 +235,7 @@ cdef bint biseq_init_concat(biseq_t R, biseq_t S1, biseq_t S2) except -1: cdef inline bint biseq_startswith(biseq_t S1, biseq_t S2) except -1: """ - Tests if bounded integer sequence ``S1`` starts with bounded integer + Test if bounded integer sequence ``S1`` starts with bounded integer sequence ``S2``. ASSUMPTION: @@ -243,7 +243,6 @@ cdef inline bint biseq_startswith(biseq_t S1, biseq_t S2) except -1: - The two sequences must have equivalent bounds, i.e., the items on the sequences must fit into the same number of bits. This condition is not tested. - """ if S2.length > S1.length: return False @@ -259,7 +258,6 @@ cdef mp_size_t biseq_index(biseq_t S, size_t item, mp_size_t start) except -2: """ Return the position in ``S`` of an item in ``S[start:]``, or -1 if ``S[start:]`` does not contain the item. - """ cdef mp_size_t index sig_on() @@ -274,7 +272,6 @@ cdef mp_size_t biseq_index(biseq_t S, size_t item, mp_size_t start) except -2: cdef inline size_t biseq_getitem(biseq_t S, mp_size_t index) noexcept: """ Get item ``S[index]``, without checking margins. - """ cdef mp_bitcnt_t limb_index, bit_index bit_index = (index) * S.itembitsize @@ -292,7 +289,6 @@ cdef biseq_getitem_py(biseq_t S, mp_size_t index): """ Get item ``S[index]`` as a Python ``int``, without checking margins. - """ cdef size_t out = biseq_getitem(S, index) return PyLong_FromSize_t(out) @@ -336,7 +332,6 @@ cdef bint biseq_init_slice(biseq_t R, biseq_t S, mp_size_t start, mp_size_t stop """ Create the slice ``S[start:stop:step]`` as bounded integer sequence and write the result to ``R``, which must not be initialised. - """ cdef mp_size_t length = 0 if step > 0: @@ -369,13 +364,13 @@ cdef bint biseq_init_slice(biseq_t R, biseq_t S, mp_size_t start, mp_size_t stop cdef mp_size_t biseq_contains(biseq_t S1, biseq_t S2, mp_size_t start) except -2: """ - Tests if the bounded integer sequence ``S1[start:]`` contains a + Test if the bounded integer sequence ``S1[start:]`` contains a sub-sequence ``S2``. INPUT: - ``S1``, ``S2`` -- two bounded integer sequences - - ``start`` -- integer, start index + - ``start`` -- integer; start index OUTPUT: @@ -387,7 +382,6 @@ cdef mp_size_t biseq_contains(biseq_t S1, biseq_t S2, mp_size_t start) except -2 - The two sequences must have equivalent bounds, i.e., the items on the sequences must fit into the same number of bits. This condition is not tested. - """ if S2.length == 0: return start @@ -410,7 +404,7 @@ cdef mp_size_t biseq_startswith_tail(biseq_t S1, biseq_t S2, mp_size_t start) ex INPUT: - ``S1``, ``S2`` -- two bounded integer sequences - - ``start`` -- integer, start index + - ``start`` -- integer; start index OUTPUT: @@ -422,7 +416,6 @@ cdef mp_size_t biseq_startswith_tail(biseq_t S1, biseq_t S2, mp_size_t start) ex - The two sequences must have equivalent bounds, i.e., the items on the sequences must fit into the same number of bits. This condition is not tested. - """ # Increase start if S1 is too short to contain S2[start:] if S1.length < S2.length - start: @@ -447,14 +440,14 @@ from sage.rings.integer cimport smallInteger cdef class BoundedIntegerSequence: """ - A sequence of non-negative uniformly bounded integers. + A sequence of nonnegative uniformly bounded integers. INPUT: - - ``bound`` -- non-negative integer. When zero, a :class:`ValueError` + - ``bound`` -- nonnegative integer. When zero, a :exc:`ValueError` will be raised. Otherwise, the given bound is replaced by the power of two that is at least the given bound. - - ``data`` -- a list of integers. + - ``data`` -- list of integers EXAMPLES: @@ -603,16 +596,15 @@ cdef class BoundedIntegerSequence: False sage: BoundedIntegerSequence(16, [2, 7, 4])[1:1] <> - """ def __cinit__(self, *args, **kwds): """ - Allocate memory for underlying data + Allocate memory for underlying data. INPUT: - - ``bound``, non-negative integer - - ``data``, ignored + - ``bound`` -- nonnegative integer + - ``data`` -- ignored .. WARNING:: @@ -624,21 +616,19 @@ cdef class BoundedIntegerSequence: sage: from sage.data_structures.bounded_integer_sequences import BoundedIntegerSequence sage: BoundedIntegerSequence(21, [4,1,6,2,7,20,9]) # indirect doctest <4, 1, 6, 2, 7, 20, 9> - """ # In __init__, we'll raise an error if the bound is 0. self.data.data.bits = NULL def __dealloc__(self): """ - Free the memory from underlying data + Free the memory from underlying data. EXAMPLES:: sage: from sage.data_structures.bounded_integer_sequences import BoundedIntegerSequence sage: S = BoundedIntegerSequence(21, [4,1,6,2,7,20,9]) sage: del S # indirect doctest - """ biseq_dealloc(self.data) @@ -646,11 +636,11 @@ cdef class BoundedIntegerSequence: """ INPUT: - - ``bound`` -- positive integer. The given bound is replaced by - the next power of two that is greater than the given bound. + - ``bound`` -- positive integer; the given bound is replaced by + the next power of two that is greater than the given bound - - ``data`` -- a list of non-negative integers, all less than - ``bound``. + - ``data`` -- list of nonnegative integers; all less than + ``bound`` EXAMPLES:: @@ -702,7 +692,6 @@ cdef class BoundedIntegerSequence: Traceback (most recent call last): ... OverflowError: ... int too large to convert... - """ if bound <= 0: raise ValueError("positive bound expected") @@ -718,13 +707,12 @@ cdef class BoundedIntegerSequence: sage: S = BoundedIntegerSequence(21, [4,1,6,2,7,20,9]) sage: copy(S) is S True - """ return self def __reduce__(self): """ - Pickling of :class:`BoundedIntegerSequence` + Pickling of :class:`BoundedIntegerSequence`. EXAMPLES:: @@ -751,7 +739,6 @@ cdef class BoundedIntegerSequence: True sage: loads(dumps(X[1::2])) == X[1::2] True - """ return NewBISEQ, biseq_pickle(self.data) @@ -764,7 +751,6 @@ cdef class BoundedIntegerSequence: sage: S = BoundedIntegerSequence(57, L) # indirect doctest sage: len(S) == len(L) True - """ return self.data.length @@ -780,7 +766,6 @@ cdef class BoundedIntegerSequence: True sage: bool(S[1:1]) False - """ return self.data.length!=0 @@ -798,7 +783,6 @@ cdef class BoundedIntegerSequence: <4, 1, 6, 2, 7, 20, 9> sage: BoundedIntegerSequence(21, [0,0]) + BoundedIntegerSequence(21, [0,0]) <0, 0, 0, 0> - """ return "<" + ", ".join(str(x) for x in self) + ">" @@ -806,7 +790,7 @@ cdef class BoundedIntegerSequence: """ Return the bound of this bounded integer sequence. - All items of this sequence are non-negative integers less than the + All items of this sequence are nonnegative integers less than the returned bound. The bound is a power of two. EXAMPLES:: @@ -818,7 +802,6 @@ cdef class BoundedIntegerSequence: 32 sage: T.bound() 64 - """ return smallInteger(1) << self.data.itembitsize @@ -847,7 +830,6 @@ cdef class BoundedIntegerSequence: [4, 1, 6, 2, 7, 2, 3, 0, 0, 0, 0, 0, 0, 0] sage: list(BoundedIntegerSequence(21, [0,0]) + BoundedIntegerSequence(21, [0,0])) [0, 0, 0, 0] - """ cdef mp_size_t index for index in range(self.data.length): @@ -944,7 +926,6 @@ cdef class BoundedIntegerSequence: sage: B2 = BoundedIntegerSequence(8, [2,1,4]) sage: B1[0:1]+B2 <0, 2, 1, 4> - """ cdef BoundedIntegerSequence out cdef Py_ssize_t start, stop, step, slicelength @@ -968,7 +949,7 @@ cdef class BoundedIntegerSequence: def __contains__(self, other): """ - Tells whether this bounded integer sequence contains an item or a sub-sequence + Tells whether this bounded integer sequence contains an item or a sub-sequence. EXAMPLES:: @@ -1029,7 +1010,6 @@ cdef class BoundedIntegerSequence: sage: -1 in B False - """ if not isinstance(other, BoundedIntegerSequence): try: @@ -1043,7 +1023,7 @@ cdef class BoundedIntegerSequence: cpdef list list(self): """ - Converts this bounded integer sequence to a list + Convert this bounded integer sequence to a list. NOTE: @@ -1062,7 +1042,6 @@ cdef class BoundedIntegerSequence: sage: (BoundedIntegerSequence(21, [0,0]) + BoundedIntegerSequence(21, [0,0])).list() [0, 0, 0, 0] - """ cdef mp_size_t i return [biseq_getitem_py(self.data, i) for i in range(self.data.length)] @@ -1097,7 +1076,6 @@ cdef class BoundedIntegerSequence: sage: T = BoundedIntegerSequence(51, L0) sage: S.startswith(T) False - """ if self.data.itembitsize != other.data.itembitsize: return False @@ -1105,7 +1083,7 @@ cdef class BoundedIntegerSequence: def index(self, other): """ - The index of a given item or sub-sequence of ``self`` + The index of a given item or sub-sequence of ``self``. EXAMPLES:: @@ -1159,7 +1137,6 @@ cdef class BoundedIntegerSequence: Traceback (most recent call last): ... TypeError: an integer is required - """ cdef mp_size_t out if not isinstance(other, BoundedIntegerSequence): @@ -1223,7 +1200,6 @@ cdef class BoundedIntegerSequence: sage: B2 = BoundedIntegerSequence(2^30, [10^9+3, 10^9+4]) sage: B1 + B2 <1000000001, 1000000002, 1000000003, 1000000004> - """ cdef BoundedIntegerSequence myself, right, out if other is None or self is None: @@ -1258,7 +1234,6 @@ cdef class BoundedIntegerSequence: sage: B2 = BoundedIntegerSequence(4,[2,3,2,3,2,3,1]) sage: B1.maximal_overlap(B2) <2, 3, 2, 3, 2, 3> - """ cdef mp_size_t i = biseq_startswith_tail(other.data, self.data, 0) if i==-1: @@ -1267,7 +1242,7 @@ cdef class BoundedIntegerSequence: def __richcmp__(self, other, op): """ - Comparison of bounded integer sequences + Comparison of bounded integer sequences. We compare, in this order: @@ -1313,7 +1288,6 @@ cdef class BoundedIntegerSequence: False sage: list(S)> list(T) True - """ cdef BoundedIntegerSequence right cdef BoundedIntegerSequence left @@ -1348,7 +1322,6 @@ cdef class BoundedIntegerSequence: True sage: hash(S) == hash(T) True - """ cdef Py_hash_t h = biseq_hash(self.data) if h == -1: @@ -1382,7 +1355,6 @@ cpdef BoundedIntegerSequence NewBISEQ(tuple bitset_data, mp_bitcnt_t itembitsize sage: S = BoundedIntegerSequence(2*sys.maxsize, [8, 8, 26, 18, 18, 8, 22, 4, 17, 22, 22, 7, 12, 4, 1, 7, 21, 7, 10, 10]) sage: loads(dumps(S)) <8, 8, 26, 18, 18, 8, 22, 4, 17, 22, 22, 7, 12, 4, 1, 7, 21, 7, 10, 10> - """ cdef BoundedIntegerSequence out = BoundedIntegerSequence.__new__(BoundedIntegerSequence) biseq_unpickle(out.data, bitset_data, itembitsize, length) diff --git a/src/sage/data_structures/mutable_poset.py b/src/sage/data_structures/mutable_poset.py index 8595bdcba75..0acef5aca6e 100644 --- a/src/sage/data_structures/mutable_poset.py +++ b/src/sage/data_structures/mutable_poset.py @@ -158,14 +158,12 @@ class MutablePosetShell(SageObject): INPUT: - - ``poset`` -- the poset to which this shell belongs. + - ``poset`` -- the poset to which this shell belongs - ``element`` -- the element which should be - contained/encapsulated in this shell. + contained/encapsulated in this shell - OUTPUT: - - A shell for the given element. + OUTPUT: a shell for the given element .. NOTE:: @@ -300,12 +298,10 @@ def predecessors(self, reverse=False): INPUT: - - ``reverse`` -- (default: ``False``) if set, then return - successors instead. - - OUTPUT: + - ``reverse`` -- boolean (default: ``False``); if set, then return + successors instead - A set. + OUTPUT: set .. SEEALSO:: @@ -331,12 +327,10 @@ def successors(self, reverse=False): INPUT: - - ``reverse`` -- (default: ``False``) if set, then return - predecessors instead. + - ``reverse`` -- boolean (default: ``False``); if set, then return + predecessors instead - OUTPUT: - - A set. + OUTPUT: set .. SEEALSO:: @@ -363,13 +357,7 @@ def is_special(self): infinity-element, i.e., the element larger than any possible other element. - INPUT: - - Nothing. - - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean .. SEEALSO:: @@ -393,9 +381,7 @@ def is_null(self): Return whether this shell contains the null-element, i.e., the element smaller than any possible other element. - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean .. SEEALSO:: @@ -420,9 +406,7 @@ def is_oo(self): Return whether this shell contains the infinity-element, i.e., the element larger than any possible other element. - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean .. SEEALSO:: @@ -446,13 +430,7 @@ def _repr_(self): r""" Return the representation of this shell. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string .. NOTE:: @@ -485,13 +463,7 @@ def __hash__(self): r""" Return the hash of this shell. - INPUT: - - Nothing. - - OUTPUT: - - A hash value. + OUTPUT: a hash value This returns the hash value of the key of the element contained in this shell. @@ -512,14 +484,12 @@ def le(self, other, reverse=False): INPUT: - - ``other`` -- a shell. - - - ``reverse`` -- (default: ``False``) if set, then return - whether this shell is greater than or equal to ``other``. + - ``other`` -- a shell - OUTPUT: + - ``reverse`` -- boolean (default: ``False``); if set, then return + whether this shell is greater than or equal to ``other`` - ``True`` or ``False``. + OUTPUT: boolean .. NOTE:: @@ -609,11 +579,9 @@ def eq(self, other): INPUT: - - ``other`` -- a shell. - - OUTPUT: + - ``other`` -- a shell - ``True`` or ``False``. + OUTPUT: boolean .. NOTE:: @@ -675,19 +643,17 @@ def _copy_all_linked_(self, memo, poset, mapping): INPUT: - - ``memo`` -- a dictionary which assigns to the id of the - calling shell to a copy of it. + - ``memo`` -- dictionary which assigns to the id of the + calling shell to a copy of it - ``poset`` -- the poset to which the newly created shells belongs. Note that the elements are not inserted into ``poset``; this is done in the calling method :meth:`MutablePoset._copy_shells_`. - - ``mapping`` -- a function which is applied on each of the elements. + - ``mapping`` -- a function which is applied on each of the elements - OUTPUT: - - A new shell. + OUTPUT: a new shell .. SEEALSO:: @@ -741,18 +707,16 @@ def lower_covers(self, shell, reverse=False): INPUT: - - ``shell`` -- the shell for which to find the covering shells. - There is no restriction of ``shell`` being contained in the poset. + - ``shell`` -- the shell for which to find the covering shells + There is no restriction of ``shell`` being contained in the poset If ``shell`` is contained in the poset, then use the more efficient methods :meth:`predecessors` and :meth:`successors`. - - ``reverse`` -- (default: ``False``) if set, then find + - ``reverse`` -- boolean (default: ``False``); if set, then find the upper covers (see also :meth:`upper_covers`) - instead of the lower covers. - - OUTPUT: + instead of the lower covers - A set of :class:`shells `. + OUTPUT: a set of :class:`shells ` .. NOTE:: @@ -821,18 +785,16 @@ def upper_covers(self, shell, reverse=False): INPUT: - - ``shell`` -- the shell for which to find the covering shells. - There is no restriction of ``shell`` being contained in the poset. + - ``shell`` -- the shell for which to find the covering shells + There is no restriction of ``shell`` being contained in the poset If ``shell`` is contained in the poset, then use the more efficient methods :meth:`predecessors` and :meth:`successors`. - - ``reverse`` -- (default: ``False``) if set, then find + - ``reverse`` -- boolean (default: ``False``); if set, then find the lower covers (see also :meth:`lower_covers`) instead of the upper covers. - OUTPUT: - - A set of :class:`shells `. + OUTPUT: a set of :class:`shells ` .. NOTE:: @@ -894,11 +856,11 @@ def _iter_depth_first_visit_(self, marked, INPUT: - - ``marked`` -- a set in which marked shells are stored. + - ``marked`` -- set in which marked shells are stored - - ``reverse`` -- (default: ``False``) if set, reverses the + - ``reverse`` -- boolean (default: ``False``); if set, reverses the order, i.e., ``False`` searches towards ``'oo'`` and - ``True`` searches towards ``'null'``. + ``True`` searches towards ``'null'`` - ``key`` -- (default: ``None``) a function used for sorting the direct successors of a shell (used in case of a @@ -910,10 +872,6 @@ def _iter_depth_first_visit_(self, marked, always ``True``. Note that the iteration does not go beyond a not included shell. - OUTPUT: - - An iterator. - .. NOTE:: The depth first search starts at this (``self``) shell. Thus @@ -956,9 +914,9 @@ def iter_depth_first(self, reverse=False, key=None, condition=None): INPUT: - - ``reverse`` -- (default: ``False``) if set, reverses the + - ``reverse`` -- boolean (default: ``False``); if set, reverses the order, i.e., ``False`` searches towards ``'oo'`` and - ``True`` searches towards ``'null'``. + ``True`` searches towards ``'null'`` - ``key`` -- (default: ``None``) a function used for sorting the direct successors of a shell (used in case of a @@ -970,10 +928,6 @@ def iter_depth_first(self, reverse=False, key=None, condition=None): always ``True``. Note that the iteration does not go beyond a not included shell. - OUTPUT: - - An iterator. - .. NOTE:: The depth first search starts at this (``self``) shell. Thus @@ -1018,11 +972,11 @@ def _iter_topological_visit_(self, marked, INPUT: - - ``marked`` -- a set in which marked shells are stored. + - ``marked`` -- set in which marked shells are stored - - ``reverse`` -- (default: ``False``) if set, reverses the + - ``reverse`` -- boolean (default: ``False``); if set, reverses the order, i.e., ``False`` searches towards ``'oo'`` and - ``True`` searches towards ``'null'``. + ``True`` searches towards ``'null'`` - ``key`` -- (default: ``None``) a function used for sorting the direct predecessors of a shell (used in case of a @@ -1034,9 +988,7 @@ def _iter_topological_visit_(self, marked, always ``True``. Note that the iteration does not go beyond a not included shell. - OUTPUT: - - An iterator. + OUTPUT: an iterator .. NOTE:: @@ -1081,9 +1033,9 @@ def iter_topological(self, reverse=False, key=None, condition=None): INPUT: - - ``reverse`` -- (default: ``False``) if set, reverses the + - ``reverse`` -- boolean (default: ``False``); if set, reverses the order, i.e., ``False`` searches towards ``'oo'`` and - ``True`` searches towards ``'null'``. + ``True`` searches towards ``'null'`` - ``key`` -- (default: ``None``) a function used for sorting the direct predecessors of a shell (used in case of a @@ -1095,9 +1047,7 @@ def iter_topological(self, reverse=False, key=None, condition=None): always ``True``. Note that the iteration does not go beyond a not included shell. - OUTPUT: - - An iterator. + OUTPUT: an iterator .. NOTE:: @@ -1192,19 +1142,17 @@ def merge(self, element, check=True, delete=True): INPUT: - - ``element`` -- an element (of the poset). + - ``element`` -- an element (of the poset) - - ``check`` -- (default: ``True``) if set, then the + - ``check`` -- boolean (default: ``True``); if set, then the ``can_merge``-function of :class:`MutablePoset` determines whether the merge is possible. ``can_merge`` is ``None`` means that this check is always passed. - - ``delete`` -- (default: ``True``) if set, then ``element`` - is removed from the poset after the merge. - - OUTPUT: + - ``delete`` -- boolean (default: ``True``); if set, then ``element`` + is removed from the poset after the merge - Nothing. + OUTPUT: nothing .. NOTE:: @@ -1336,7 +1284,7 @@ class MutablePoset(SageObject): position of the element in the poset. - ``can_merge`` -- a function which checks whether its second argument - can be merged to its first. + can be merged to its first This hook is called by :meth:`merge`. Moreover it is used during :meth:`add` when an element (more precisely its key) is already @@ -1345,9 +1293,7 @@ class MutablePoset(SageObject): ``can_merge`` is ``None`` (default) is equivalent to ``can_merge`` returning ``True`` in all cases. - OUTPUT: - - A mutable poset. + OUTPUT: a mutable poset You can find a short introduction and examples :mod:`here `. @@ -1441,13 +1387,7 @@ def clear(self): r""" Remove all elements from this poset. - INPUT: - - Nothing. - - OUTPUT: - - Nothing. + OUTPUT: nothing .. SEEALSO:: @@ -1481,13 +1421,7 @@ def __len__(self): r""" Return the number of elements contained in this poset. - INPUT: - - Nothing. - - OUTPUT: - - An integer. + OUTPUT: integer .. NOTE:: @@ -1561,11 +1495,9 @@ def shell(self, key): INPUT: - - ``key`` -- the key of an object. - - OUTPUT: + - ``key`` -- the key of an object - An instance of :class:`MutablePosetShell`. + OUTPUT: an instance of :class:`MutablePosetShell` .. NOTE:: @@ -1595,11 +1527,9 @@ def element(self, key): INPUT: - - ``key`` -- the key of an object. + - ``key`` -- the key of an object - OUTPUT: - - An object. + OUTPUT: an object EXAMPLES:: @@ -1624,11 +1554,9 @@ def get_key(self, element): INPUT: - - ``element`` -- an object. - - OUTPUT: + - ``element`` -- an object - An object (the key of ``element``). + OUTPUT: an object (the key of ``element``) .. SEEALSO:: @@ -1658,13 +1586,11 @@ def _copy_shells_(self, other, mapping): INPUT: - ``other`` -- the mutable poset from which the shells - should be copied to this poset. - - - ``mapping`` -- a function that is applied to each element. + should be copied to this poset - OUTPUT: + - ``mapping`` -- a function that is applied to each element - Nothing. + OUTPUT: nothing .. SEEALSO:: @@ -1700,11 +1626,9 @@ def copy(self, mapping=None): INPUT: - - ``mapping`` -- a function which is applied on each of the elements. + - ``mapping`` -- a function which is applied on each of the elements - OUTPUT: - - A poset with the same content as ``self``. + OUTPUT: a poset with the same content as ``self`` .. SEEALSO:: @@ -1739,13 +1663,11 @@ def shells(self, include_special=False): INPUT: - - ``include_special`` -- (default: ``False``) if set, then + - ``include_special`` -- boolean (default: ``False``); if set, then including shells containing a smallest element (`\emptyset`) - and a largest element (`\infty`). - - OUTPUT: + and a largest element (`\infty`) - An iterator. + OUTPUT: an iterator .. NOTE:: @@ -1784,11 +1706,11 @@ def shells_topological(self, include_special=False, INPUT: - - ``include_special`` -- (default: ``False``) if set, then + - ``include_special`` -- boolean (default: ``False``); if set, then including shells containing a smallest element (`\emptyset`) and a largest element (`\infty`). - - ``reverse`` -- (default: ``False``) -- if set, reverses the + - ``reverse`` -- boolean (default: ``False``); if set, reverses the order, i.e., ``False`` gives smallest elements first, ``True`` gives largest first. @@ -1796,9 +1718,7 @@ def shells_topological(self, include_special=False, the direct successors of a shell (used in case of a tie). If this is ``None``, no sorting occurs. - OUTPUT: - - An iterator. + OUTPUT: an iterator .. NOTE:: @@ -1843,11 +1763,7 @@ def elements(self, **kwargs): INPUT: - - ``kwargs`` -- arguments are passed to :meth:`shells`. - - OUTPUT: - - An iterator. + - ``kwargs`` -- arguments are passed to :meth:`shells` EXAMPLES:: @@ -1889,11 +1805,7 @@ def elements_topological(self, **kwargs): INPUT: - - ``kwargs`` -- arguments are passed to :meth:`shells_topological`. - - OUTPUT: - - An iterator. + - ``kwargs`` -- arguments are passed to :meth:`shells_topological` EXAMPLES:: @@ -1930,11 +1842,7 @@ def keys(self, **kwargs): INPUT: - - ``kwargs`` -- arguments are passed to :meth:`shells`. - - OUTPUT: - - An iterator. + - ``kwargs`` -- arguments are passed to :meth:`shells` EXAMPLES:: @@ -1976,11 +1884,7 @@ def keys_topological(self, **kwargs): INPUT: - - ``kwargs`` -- arguments are passed to :meth:`shells_topological`. - - OUTPUT: - - An iterator. + - ``kwargs`` -- arguments are passed to :meth:`shells_topological` EXAMPLES:: @@ -2019,16 +1923,13 @@ def repr(self, include_special=False, reverse=False): INPUT: - - ``include_special`` -- (default: ``False``) a boolean - indicating whether to include the special elements - ``'null'`` and ``'oo'`` or not. + - ``include_special`` -- boolean (default: ``False``); whether to + include the special elements ``'null'`` and ``'oo'`` or not - - ``reverse`` -- (default: ``False``) a boolean. If set, then - largest elements are displayed first. + - ``reverse`` -- boolean (default: ``False``); if set, then + largest elements are displayed first - OUTPUT: - - A string. + OUTPUT: string .. SEEALSO:: @@ -2053,12 +1954,10 @@ def repr_full(self, reverse=False): INPUT: - - ``reverse`` -- (default: ``False``) a boolean. If set, then - largest elements are displayed first. - - OUTPUT: + - ``reverse`` -- boolean (default: ``False``); if set, then + largest elements are displayed first - A string. + OUTPUT: string .. SEEALSO:: @@ -2102,11 +2001,9 @@ def contains(self, key): INPUT: - - ``key`` -- an object. - - OUTPUT: + - ``key`` -- an object - ``True`` or ``False``. + OUTPUT: boolean .. SEEALSO:: @@ -2138,11 +2035,9 @@ def add(self, element): INPUT: - ``element`` -- an object (hashable and supporting comparison - with the operator ``<=``). + with the operator ``<=``) - OUTPUT: - - Nothing. + OUTPUT: nothing EXAMPLES:: @@ -2303,24 +2198,22 @@ def remove(self, key, raise_key_error=True): INPUT: - - ``key`` -- the key of an object. - - - ``raise_key_error`` -- (default: ``True``) switch raising - :class:`KeyError` on and off. + - ``key`` -- the key of an object - OUTPUT: + - ``raise_key_error`` -- boolean (default: ``True``); switch raising + :exc:`KeyError` on and off - Nothing. + OUTPUT: nothing If the element is not a member and ``raise_key_error`` is set - (default), raise a :class:`KeyError`. + (default), raise a :exc:`KeyError`. .. NOTE:: As with Python's ``set``, the methods :meth:`remove` and :meth:`discard` only differ in their behavior when an element is not contained in the poset: :meth:`remove` - raises a :class:`KeyError` whereas :meth:`discard` does not + raises a :exc:`KeyError` whereas :meth:`discard` does not raise any exception. This default behavior can be overridden with the @@ -2483,24 +2376,22 @@ def discard(self, key, raise_key_error=False): INPUT: - - ``key`` -- the key of an object. - - - ``raise_key_error`` -- (default: ``False``) switch raising - :class:`KeyError` on and off. + - ``key`` -- the key of an object - OUTPUT: + - ``raise_key_error`` -- boolean (default: ``False``); switch raising + :exc:`KeyError` on and off - Nothing. + OUTPUT: nothing If the element is not a member and ``raise_key_error`` is set - (not default), raise a :class:`KeyError`. + (not default), raise a :exc:`KeyError`. .. NOTE:: As with Python's ``set``, the methods :meth:`remove` and :meth:`discard` only differ in their behavior when an element is not contained in the poset: :meth:`remove` - raises a :class:`KeyError` whereas :meth:`discard` does not + raises a :exc:`KeyError` whereas :meth:`discard` does not raise any exception. This default behavior can be overridden with the @@ -2536,11 +2427,9 @@ def pop(self, **kwargs): INPUT: - - ``kwargs`` -- arguments are passed to :meth:`shells_topological`. + - ``kwargs`` -- arguments are passed to :meth:`shells_topological` - OUTPUT: - - An object. + OUTPUT: an object .. NOTE:: @@ -2580,7 +2469,7 @@ def pop(self, **kwargs): def union(self, *other): r""" - Return the union of the given posets as a new poset + Return the union of the given posets as a new poset. INPUT: @@ -2589,10 +2478,6 @@ def union(self, *other): It is possible to specify more than one ``other`` as variadic arguments (arbitrary argument lists). - OUTPUT: - - A poset. - .. NOTE:: The key of an element is used for comparison. Thus elements with @@ -2647,9 +2532,7 @@ def union_update(self, *other): It is possible to specify more than one ``other`` as variadic arguments (arbitrary argument lists). - OUTPUT: - - Nothing. + OUTPUT: nothing .. NOTE:: @@ -2716,10 +2599,6 @@ def difference(self, *other): It is possible to specify more than one ``other`` as variadic arguments (arbitrary argument lists). - OUTPUT: - - A poset. - .. NOTE:: The key of an element is used for comparison. Thus elements with @@ -2769,9 +2648,7 @@ def difference_update(self, *other): It is possible to specify more than one ``other`` as variadic arguments (arbitrary argument lists). - OUTPUT: - - Nothing. + OUTPUT: nothing .. NOTE:: @@ -2809,7 +2686,7 @@ def difference_update(self, *other): def intersection(self, *other): r""" - Return the intersection of the given posets as a new poset + Return the intersection of the given posets as a new poset. INPUT: @@ -2818,10 +2695,6 @@ def intersection(self, *other): It is possible to specify more than one ``other`` as variadic arguments (arbitrary argument lists). - OUTPUT: - - A poset. - .. NOTE:: The key of an element is used for comparison. Thus elements with @@ -2867,9 +2740,7 @@ def intersection_update(self, *other): It is possible to specify more than one ``other`` as variadic arguments (arbitrary argument lists). - OUTPUT: - - Nothing. + OUTPUT: nothing .. NOTE:: @@ -2910,11 +2781,7 @@ def symmetric_difference(self, other): INPUT: - - ``other`` -- a poset. - - OUTPUT: - - A poset. + - ``other`` -- a poset .. NOTE:: @@ -2952,11 +2819,9 @@ def symmetric_difference_update(self, other): INPUT: - - ``other`` -- a poset. + - ``other`` -- a poset - OUTPUT: - - Nothing. + OUTPUT: nothing .. NOTE:: @@ -2997,12 +2862,10 @@ def is_disjoint(self, other): INPUT: - - ``other`` -- a poset or an iterable. In the latter case the - iterated objects are seen as elements of a poset. - - OUTPUT: + - ``other`` -- a poset or an iterable; in the latter case the + iterated objects are seen as elements of a poset - Nothing. + OUTPUT: nothing .. NOTE:: @@ -3045,12 +2908,10 @@ def is_subset(self, other): INPUT: - - ``other`` -- a poset or an iterable. In the latter case the - iterated objects are seen as elements of a poset. - - OUTPUT: + - ``other`` -- a poset or an iterable; in the latter case the + iterated objects are seen as elements of a poset - Nothing. + OUTPUT: nothing .. NOTE:: @@ -3097,12 +2958,10 @@ def is_superset(self, other): INPUT: - - ``other`` -- a poset or an iterable. In the latter case the - iterated objects are seen as elements of a poset. - - OUTPUT: + - ``other`` -- a poset or an iterable; in the latter case the + iterated objects are seen as elements of a poset - Nothing. + OUTPUT: nothing .. NOTE:: @@ -3154,18 +3013,16 @@ def merge(self, key=None, reverse=False): - ``key`` -- the key specifying an element or ``None`` (default), in which case this method is called on each - element in this poset. + element in this poset - - ``reverse`` -- (default: ``False``) specifies which + - ``reverse`` -- boolean (default: ``False``); specifies which direction to go first: ``False`` searches towards ``'oo'`` and ``True`` searches towards ``'null'``. When ``key=None``, then this also specifies which elements are merged first. - OUTPUT: - - Nothing. + OUTPUT: nothing This method tests all (not necessarily direct) successors and predecessors of the given element whether they can be merged with @@ -3302,13 +3159,7 @@ def maximal_elements(self): r""" Return an iterator over the maximal elements of this poset. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -3333,13 +3184,7 @@ def minimal_elements(self): r""" Return an iterator over the minimal elements of this poset. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -3367,16 +3212,14 @@ def map(self, function, topological=False, reverse=False): INPUT: - ``function`` -- a function mapping an existing element to - a new element. - - - ``topological`` -- (default: ``False``) if set, then the - mapping is done in topological order, otherwise unordered. + a new element - - ``reverse`` -- is passed on to topological ordering. + - ``topological`` -- boolean (default: ``False``); if set, then the + mapping is done in topological order, otherwise unordered - OUTPUT: + - ``reverse`` -- is passed on to topological ordering - Nothing. + OUTPUT: nothing .. NOTE:: @@ -3431,16 +3274,14 @@ def mapped(self, function): INPUT: - ``function`` -- a function mapping an existing element to - a new element. - - - ``topological`` -- (default: ``False``) if set, then the - mapping is done in topological order, otherwise unordered. + a new element - - ``reverse`` -- is passed on to topological ordering. + - ``topological`` -- boolean (default: ``False``); if set, then the + mapping is done in topological order, otherwise unordered - OUTPUT: + - ``reverse`` -- is passed on to topological ordering - A :class:`MutablePoset`. + OUTPUT: a :class:`MutablePoset` .. NOTE:: diff --git a/src/sage/data_structures/sparse_bitset.pxd b/src/sage/data_structures/sparse_bitset.pxd index 9b95c55675b..e30de80073f 100644 --- a/src/sage/data_structures/sparse_bitset.pxd +++ b/src/sage/data_structures/sparse_bitset.pxd @@ -46,13 +46,13 @@ cdef struct sparse_bitset_s: # Pointer to the memory of ``bits``. void* mem - # Storing the non zero positions can safe time, when performing + # Storing the nonzero positions can safe time, when performing # multiple comparisons. # E.g. one can set them while computing the intersection # and then use those to ``bitset_issubset`` many times in a row. # Any modification, will invalidate the already computed positions. - # It is stored, whether the non zero chunks are correctly initialized + # It is stored, whether the nonzero chunks are correctly initialized # or not. Computations will work correctly either way. bint non_zero_chunks_are_initialized mp_bitcnt_t* non_zero_chunks diff --git a/src/sage/data_structures/stream.py b/src/sage/data_structures/stream.py index 251deff8b96..ae3cbb71ecd 100644 --- a/src/sage/data_structures/stream.py +++ b/src/sage/data_structures/stream.py @@ -133,7 +133,6 @@ class Stream(): However, keep in mind that (trivially) this initialization code is not executed if ``_approximate_order`` is set to a value before it is accessed. - """ def __init__(self, true_order): """ @@ -185,7 +184,7 @@ def __ne__(self, other): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. The default implementation is ``False``. @@ -226,7 +225,7 @@ class Stream_inexact(Stream): - ``is_sparse`` -- boolean; whether the implementation of the stream is sparse - ``true_order`` -- boolean; if the approximate order is the actual order - If the cache is dense, it begins with the first non-zero term. + If the cache is dense, it begins with the first nonzero term. """ def __init__(self, is_sparse, true_order): """ @@ -251,7 +250,7 @@ def __init__(self, is_sparse, true_order): def is_nonzero(self): r""" - Return ``True`` if and only if the cache contains a non-zero element. + Return ``True`` if and only if the cache contains a nonzero element. EXAMPLES:: @@ -319,7 +318,7 @@ def __setstate__(self, d): INPUT: - - ``d`` -- a dictionary that needs to be unpickled + - ``d`` -- dictionary that needs to be unpickled EXAMPLES:: @@ -441,7 +440,7 @@ def iterate_coefficients(self): def order(self): r""" Return the order of ``self``, which is the minimum index ``n`` such - that ``self[n]`` is non-zero. + that ``self[n]`` is nonzero. EXAMPLES:: @@ -545,7 +544,6 @@ def __ne__(self, other): True sage: g != f True - """ # TODO: more cases, in particular mixed implementations, # could be detected @@ -582,7 +580,7 @@ class Stream_exact(Stream): INPUT: - - ``initial_values`` -- a list of initial values + - ``initial_values`` -- list of initial values - ``is_sparse`` -- boolean; specifies whether the stream is sparse - ``order`` -- integer (default: 0); determining the degree of the first element of ``initial_values`` @@ -607,7 +605,7 @@ def __init__(self, initial_coefficients, constant=None, degree=None, order=None) sage: Stream_exact([]) Traceback (most recent call last): ... - AssertionError: Stream_exact should only be used for non-zero streams + AssertionError: Stream_exact should only be used for nonzero streams sage: s = Stream_exact([0, 0, 1, 0, 0]) sage: s._initial_coefficients, s._approximate_order, s._degree, s._true_order @@ -669,7 +667,7 @@ def __init__(self, initial_coefficients, constant=None, degree=None, order=None) # complicated otherwise for i, v in enumerate(initial_coefficients): if v: - # We have found the first non-zero coefficient + # We have found the first nonzero coefficient order += i initial_coefficients = initial_coefficients[i:] if order + len(initial_coefficients) == self._degree: @@ -690,7 +688,7 @@ def __init__(self, initial_coefficients, constant=None, degree=None, order=None) order = self._degree self._initial_coefficients = tuple() - assert self._initial_coefficients or self._constant, "Stream_exact should only be used for non-zero streams" + assert self._initial_coefficients or self._constant, "Stream_exact should only be used for nonzero streams" super().__init__(True) self._approximate_order = order @@ -748,7 +746,7 @@ def __getitem__(self, n): def order(self): r""" Return the order of ``self``, which is the minimum index - ``n`` such that ``self[n]`` is non-zero. + ``n`` such that ``self[n]`` is nonzero. EXAMPLES:: @@ -808,7 +806,6 @@ def __eq__(self, other): sage: t = Stream_exact([2], order=-1, degree=5, constant=1) sage: s == t False - """ return (isinstance(other, type(self)) and self._degree == other._degree @@ -821,7 +818,7 @@ def __ne__(self, other): Return whether ``self`` and ``other`` are known to be different. The argument ``other`` may be exact or inexact, but is - assumed to be non-zero. + assumed to be nonzero. INPUT: @@ -882,9 +879,9 @@ def __ne__(self, other): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. - An assumption of this class is that it is non-zero. + An assumption of this class is that it is nonzero. EXAMPLES:: @@ -943,7 +940,7 @@ def __init__(self, iter, approximate_order, true_order=False): sage: from sage.data_structures.stream import Stream_iterator sage: f = Stream_iterator(iter(NonNegativeIntegers()), 0) - sage: TestSuite(f).run(skip="_test_pickling") + sage: TestSuite(f).run(skip='_test_pickling') """ self.iterate_coefficients = lambda: iter super().__init__(False, true_order) @@ -993,7 +990,7 @@ def __init__(self, function, is_sparse, approximate_order, true_order=False): sage: from sage.data_structures.stream import Stream_function sage: f = Stream_function(lambda n: 1, False, 1) - sage: TestSuite(f).run(skip="_test_pickling") + sage: TestSuite(f).run(skip='_test_pickling') """ self.get_coefficient = function super().__init__(is_sparse, true_order) @@ -1076,7 +1073,7 @@ def __init__(self, function, is_sparse): sage: from sage.data_structures.stream import Stream_taylor sage: f = Stream_taylor(polygen(QQ, 'x')^3, False) - sage: TestSuite(f).run(skip="_test_pickling") + sage: TestSuite(f).run(skip='_test_pickling') """ from sage.symbolic.ring import SR from sage.structure.element import parent @@ -1241,7 +1238,7 @@ def __init__(self, approximate_order, true_order=False): sage: from sage.data_structures.stream import Stream_uninitialized sage: C = Stream_uninitialized(0) - sage: TestSuite(C).run(skip="_test_pickling") + sage: TestSuite(C).run(skip='_test_pickling') """ self._target = None if approximate_order is None: @@ -1310,7 +1307,7 @@ class Stream_unary(Stream_inexact): - ``series`` -- :class:`Stream` the operator acts on - ``is_sparse`` -- boolean - - ``true_order`` -- boolean (default: ``False``) if the approximate order + - ``true_order`` -- boolean (default: ``False``); if the approximate order is the actual order EXAMPLES:: @@ -1871,7 +1868,7 @@ def get_coefficient(self, n): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. EXAMPLES:: @@ -1945,7 +1942,7 @@ def _approximate_order(self): or self._right._approximate_order <= 0): raise ValueError("Dirichlet convolution is only defined for " "coefficient streams with minimal index of " - "non-zero coefficient at least 1") + "nonzero coefficient at least 1") return self._left._approximate_order * self._right._approximate_order def get_coefficient(self, n): @@ -2100,13 +2097,13 @@ class Stream_plethysm(Stream_binary): - ``f`` -- a :class:`Stream` - ``g`` -- a :class:`Stream` with positive order, unless ``f`` is - of :class:`Stream_exact`. + of :class:`Stream_exact` - ``p`` -- the ring of powersum symmetric functions containing ``g`` - - ``ring`` (default: ``None``) -- the ring the result + - ``ring`` -- (default: ``None``) the ring the result should be in, by default ``p`` - - ``include`` -- a list of variables to be treated as degree one + - ``include`` -- list of variables to be treated as degree one elements instead of the default degree one elements - - ``exclude`` -- a list of variables to be excluded from the + - ``exclude`` -- list of variables to be excluded from the default degree one elements EXAMPLES:: @@ -2180,7 +2177,6 @@ class Stream_plethysm(Stream_binary): sage: r2 = Stream_plethysm(f, g, True, p, include=[]) # needs sage.modules sage: r_s - sum(r2[n] for n in range(2*(r_s.degree()+1))) # needs sage.modules (a2*b1^2-a2*b1)*p[2] + (a2*b111^2-a2*b111)*p[2, 2, 2] + (a2*b21^2-a2*b21)*p[4, 2] - """ def __init__(self, f, g, is_sparse, p, ring=None, include=None, exclude=None): r""" @@ -2396,7 +2392,6 @@ def stretched_power_restrict_degree(self, i, m, d): ....: if sum(mu.size() for mu in m) == 12}) sage: A == B # long time True - """ # TODO: we should do lazy binary powering here while len(self._powers) < m: @@ -2409,7 +2404,7 @@ def stretched_power_restrict_degree(self, i, m, d): # integer and not a symmetric function if power_d: # _raise_variables(c, i, self._degree_one) cannot vanish - # because i is positive and c is non-zero + # because i is positive and c is nonzero if self._tensor_power is None: terms = {mon.stretch(i): _raise_variables(c, i, self._degree_one) @@ -2434,7 +2429,7 @@ class Stream_scalar(Stream_unary): INPUT: - ``series`` -- a :class:`Stream` - - ``scalar`` -- a non-zero, non-one scalar + - ``scalar`` -- a nonzero, non-one scalar - ``is_sparse`` -- boolean """ def __init__(self, series, scalar, is_sparse): @@ -2515,7 +2510,7 @@ def __eq__(self, other): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. EXAMPLES:: @@ -2542,7 +2537,7 @@ class Stream_rmul(Stream_scalar): INPUT: - ``series`` -- a :class:`Stream` - - ``scalar`` -- a non-zero, non-one scalar + - ``scalar`` -- a nonzero, non-one scalar EXAMPLES:: @@ -2584,7 +2579,7 @@ class Stream_lmul(Stream_scalar): INPUT: - ``series`` -- a :class:`Stream` - - ``scalar`` -- a non-zero, non-one scalar + - ``scalar`` -- a nonzero, non-one scalar EXAMPLES:: @@ -2691,7 +2686,7 @@ def get_coefficient(self, n): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. EXAMPLES:: @@ -2730,7 +2725,6 @@ class Stream_cauchy_invert(Stream_unary): sage: g = Stream_cauchy_invert(f) sage: [g[i] for i in range(10)] [-1, 0, 0, 0, 0, 0, 0, 0, 0, 0] - """ def __init__(self, series, approximate_order=None): """ @@ -2830,9 +2824,9 @@ def iterate_coefficients(self): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. - An assumption of this class is that it is non-zero. + An assumption of this class is that it is nonzero. EXAMPLES:: @@ -2875,7 +2869,7 @@ def __init__(self, series, is_sparse): sage: g[1] Traceback (most recent call last): ... - ZeroDivisionError: the Dirichlet inverse only exists if the coefficient with index 1 is non-zero + ZeroDivisionError: the Dirichlet inverse only exists if the coefficient with index 1 is nonzero """ super().__init__(series, is_sparse) self._zero = ZZ.zero() @@ -2898,7 +2892,7 @@ def _approximate_order(self): # this is the true order, but we want to check first if self._series._approximate_order > 1: raise ZeroDivisionError("the Dirichlet inverse only exists if the " - "coefficient with index 1 is non-zero") + "coefficient with index 1 is nonzero") self._true_order = True return 1 @@ -2954,7 +2948,7 @@ def get_coefficient(self, n): class Stream_map_coefficients(Stream_unary): r""" - The stream with ``function`` applied to each non-zero coefficient + The stream with ``function`` applied to each nonzero coefficient of ``series``. INPUT: @@ -2974,7 +2968,6 @@ class Stream_map_coefficients(Stream_unary): sage: g = Stream_map_coefficients(f, lambda n: -n, True) sage: [g[i] for i in range(10)] [0, -1, -1, -1, -1, -1, -1, -1, -1, -1] - """ def __init__(self, series, function, is_sparse, approximate_order=None, true_order=False): """ @@ -2985,7 +2978,7 @@ def __init__(self, series, function, is_sparse, approximate_order=None, true_ord sage: from sage.data_structures.stream import (Stream_map_coefficients, Stream_function) sage: f = Stream_function(lambda n: -1, True, 0) sage: g = Stream_map_coefficients(f, lambda n: n + 1, True) - sage: TestSuite(g).run(skip="_test_pickling") + sage: TestSuite(g).run(skip='_test_pickling') """ self._function = function super().__init__(series, is_sparse, true_order) @@ -3079,14 +3072,14 @@ def __eq__(self, other): class Stream_shift(Stream): """ - Operator for shifting a non-zero, non-exact stream. + Operator for shifting a nonzero, non-exact stream. Instances of this class share the cache with its input stream. INPUT: - ``series`` -- a :class:`Stream` - - ``shift`` -- an integer + - ``shift`` -- integer """ def __init__(self, series, shift): """ @@ -3098,7 +3091,7 @@ def __init__(self, series, shift): sage: from sage.data_structures.stream import Stream_function sage: h = Stream_function(lambda n: n, True, -5) sage: M = Stream_shift(h, 2) - sage: TestSuite(M).run(skip="_test_pickling") + sage: TestSuite(M).run(skip='_test_pickling') """ self._series = series self._shift = shift @@ -3125,7 +3118,7 @@ def _approximate_order(self): def order(self): r""" Return the order of ``self``, which is the minimum index - ``n`` such that ``self[n]`` is non-zero. + ``n`` such that ``self[n]`` is nonzero. EXAMPLES:: @@ -3195,9 +3188,9 @@ def __eq__(self, other): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. - An assumption of this class is that it is non-zero. + An assumption of this class is that it is nonzero. EXAMPLES:: @@ -3226,7 +3219,7 @@ def is_uninitialized(self): class Stream_truncated(Stream_unary): """ - Operator for shifting a non-zero, non-exact stream that has + Operator for shifting a nonzero, non-exact stream that has been shifted below its minimal valuation. Instances of this class share the cache with its input stream. @@ -3234,8 +3227,8 @@ class Stream_truncated(Stream_unary): INPUT: - ``series`` -- a :class:`Stream_inexact` - - ``shift`` -- an integer - - ``minimal_valuation`` -- an integer; this is also the approximate order + - ``shift`` -- integer + - ``minimal_valuation`` -- integer; this is also the approximate order """ def __init__(self, series, shift, minimal_valuation): """ @@ -3246,9 +3239,9 @@ def __init__(self, series, shift, minimal_valuation): sage: from sage.data_structures.stream import Stream_function, Stream_truncated sage: def fun(n): return 1 if ZZ(n).is_power_of(2) else 0 sage: s = Stream_truncated(Stream_function(fun, True, 0), -5, 0) - sage: TestSuite(s).run(skip="_test_pickling") + sage: TestSuite(s).run(skip='_test_pickling') sage: s = Stream_truncated(Stream_function(fun, False, 0), -5, 0) - sage: TestSuite(s).run(skip="_test_pickling") + sage: TestSuite(s).run(skip='_test_pickling') Verify that we have used the cache to see if we can get the true order at initialization:: @@ -3386,7 +3379,7 @@ def __eq__(self, other): def order(self): """ Return the order of ``self``, which is the minimum index ``n`` such - that ``self[n]`` is non-zero. + that ``self[n]`` is nonzero. EXAMPLES:: @@ -3432,7 +3425,7 @@ def order(self): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. EXAMPLES:: @@ -3479,7 +3472,7 @@ class Stream_derivative(Stream_unary): INPUT: - ``series`` -- a :class:`Stream` - - ``shift`` -- a positive integer + - ``shift`` -- positive integer - ``is_sparse`` -- boolean """ def __init__(self, series, shift, is_sparse): @@ -3586,7 +3579,7 @@ def __eq__(self, other): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. EXAMPLES:: @@ -3607,7 +3600,7 @@ class Stream_integral(Stream_unary): INPUT: - ``series`` -- a :class:`Stream` - - ``integration_constants`` -- a list of integration constants + - ``integration_constants`` -- list of integration constants - ``is_sparse`` -- boolean """ def __init__(self, series, integration_constants, is_sparse): @@ -3714,7 +3707,7 @@ def __eq__(self, other): def is_nonzero(self): r""" Return ``True`` if and only if this stream is known - to be non-zero. + to be nonzero. EXAMPLES:: diff --git a/src/sage/databases/conway.py b/src/sage/databases/conway.py index 7c7c3af42ac..38458806b76 100644 --- a/src/sage/databases/conway.py +++ b/src/sage/databases/conway.py @@ -173,7 +173,7 @@ def __iter__(self): def polynomial(self, p, n): """ Return the Conway polynomial of degree ``n`` over ``GF(p)``, - or raise a :class:`RuntimeError` if this polynomial is not in the + or raise a :exc:`RuntimeError` if this polynomial is not in the database. .. NOTE:: @@ -209,7 +209,7 @@ def polynomial(self, p, n): def has_polynomial(self, p, n): """ - Return True if the database of Conway polynomials contains the + Return ``True`` if the database of Conway polynomials contains the polynomial of degree ``n`` over ``GF(p)``. INPUT: diff --git a/src/sage/databases/cremona.py b/src/sage/databases/cremona.py index c556a64bdff..0349afb2518 100644 --- a/src/sage/databases/cremona.py +++ b/src/sage/databases/cremona.py @@ -103,7 +103,7 @@ def build(name, data_tgz, largest_conductor=0, mini=False, decompress=True): Build the CremonaDatabase with given name from scratch using the data_tgz tarball. - .. note:: + .. NOTE:: For data up to level 350000, this function takes about 3m40s. The resulting database occupies 426MB disk space. @@ -144,23 +144,23 @@ def build(name, data_tgz, largest_conductor=0, mini=False, decompress=True): def is_optimal_id(id): """ - Return True if the Cremona id refers to an optimal curve, and - false otherwise. + Return ``True`` if the Cremona id refers to an optimal curve, and + ``False`` otherwise. The curve is optimal if the id, which is of the form [letter code][number] has number 1. - .. note:: + .. NOTE:: 990h3 is the optimal curve in that class, so doesn't obey this rule. INPUT: - - ``id`` -- str of form letter code followed by an - integer, e.g., a3, bb5, etc. + - ``id`` -- string of form letter code followed by an + integer, e.g., a3, bb5, etc. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -183,7 +183,7 @@ def cremona_letter_code(n): For example, 0 - a 25 - z 26 - ba 51 - bz 52 - ca 53 - cb etc. - .. note:: + .. NOTE:: This is just the base 26 representation of n, where a=0, b=1, ..., z=25. This extends the old Cremona notation (counting from @@ -192,9 +192,9 @@ def cremona_letter_code(n): INPUT: - - ``n`` (int) -- a non-negative integer + - ``n`` -- nonnegative integer - OUTPUT: str + OUTPUT: string EXAMPLES:: @@ -217,19 +217,19 @@ def cremona_letter_code(n): sage: cremona_letter_code(QQ) Traceback (most recent call last): ... - ValueError: Cremona letter codes are only defined for non-negative integers + ValueError: Cremona letter codes are only defined for nonnegative integers sage: cremona_letter_code(x) # needs sage.symbolic Traceback (most recent call last): ... - ValueError: Cremona letter codes are only defined for non-negative integers + ValueError: Cremona letter codes are only defined for nonnegative integers sage: cremona_letter_code(-1) Traceback (most recent call last): ... - ValueError: Cremona letter codes are only defined for non-negative integers + ValueError: Cremona letter codes are only defined for nonnegative integers sage: cremona_letter_code(3.14159) Traceback (most recent call last): ... - ValueError: Cremona letter codes are only defined for non-negative integers + ValueError: Cremona letter codes are only defined for nonnegative integers """ try: m = int(n) @@ -241,7 +241,7 @@ def cremona_letter_code(n): n = -1 if n < 0: - raise ValueError("Cremona letter codes are only defined for non-negative integers") + raise ValueError("Cremona letter codes are only defined for nonnegative integers") if n == 0: return "a" @@ -267,9 +267,9 @@ def old_cremona_letter_code(n): INPUT: - - ``n`` -- int + - ``n`` -- integer - OUTPUT: str + OUTPUT: string EXAMPLES:: @@ -314,17 +314,17 @@ def parse_cremona_label(label, numerical_class_code=False): INPUT: - - ``label`` (string) -- a valid Cremona elliptic curve label + - ``label`` -- string; a valid Cremona elliptic curve label - - ``numerical_class_code`` (boolean, default: ``False``) -- if ``True``, - convert the isogeny class label from a letter code in base 26 - to an integer; this is useful for sorting + - ``numerical_class_code`` -- boolean (default: ``False``); if ``True``, + convert the isogeny class label from a letter code in base 26 + to an integer. This is useful for sorting. OUTPUT: - - ``int`` -- the conductor - - ``str`` or ``int`` -- the isogeny class label - - ``int`` -- the number + - integer; the conductor + - string or integer; the isogeny class label + - integer; the number EXAMPLES:: @@ -364,7 +364,6 @@ def parse_cremona_label(label, numerical_class_code=False): Traceback (most recent call last): ... ValueError: x11 is not a valid Cremona label - """ m = cremona_label_regex.match(str(label)) if m is None: @@ -399,11 +398,11 @@ def parse_lmfdb_label(label, numerical_class_code=False): or 37.b3, parse the label and return the conductor, isogeny class label, and number. - The LMFDB label (named after the L-functions and modular forms + The LMFDB label (named after the `L`-functions and modular forms database), is determined by the following two orders: - Isogeny classes with the same conductor are ordered - lexicographically by the coefficients in the q-expansion of the + lexicographically by the coefficients in the `q`-expansion of the associated modular form. - Curves within the same isogeny class are ordered @@ -420,17 +419,17 @@ def parse_lmfdb_label(label, numerical_class_code=False): INPUT: - - ``label`` -- str + - ``label`` -- str - - ``numerical_class_code`` (boolean, default: ``False``) -- if ``True``, - convert the isogeny class label from a letter code in base 26 - to an integer; this is useful for sorting + - ``numerical_class_code`` -- boolean (default: ``False``); if ``True``, + convert the isogeny class label from a letter code in base 26 + to an integer. This is useful for sorting. OUTPUT: - - ``int`` -- the conductor - - ``str`` or ``int`` -- the isogeny class label - - ``int`` -- the number + - ``int`` -- the conductor + - ``str`` or ``int`` -- the isogeny class label + - ``int`` -- the number EXAMPLES:: @@ -515,7 +514,7 @@ def sort_key(key1): """ Comparison key for curve id strings. - .. note:: + .. NOTE:: Not the same as standard lexicographic order! @@ -538,15 +537,12 @@ def cremona_to_lmfdb(cremona_label, CDB=None): INPUT: - - ``cremona_label`` -- a string, the Cremona label of a curve. - This can be the label of a curve (e.g. '990j1') or of an isogeny - class (e.g. '990j') + - ``cremona_label`` -- string, the Cremona label of a curve; this can be + the label of a curve (e.g. '990j1') or of an isogeny class (e.g. '990j') - ``CDB`` -- the Cremona database in which to look up the isogeny - classes of the same conductor. - - OUTPUT: + classes of the same conductor - - ``lmfdb_label`` -- a string, the corresponding LMFDB label. + OUTPUT: ``lmfdb_label``; string, the corresponding LMFDB label EXAMPLES:: @@ -598,15 +594,12 @@ def lmfdb_to_cremona(lmfdb_label, CDB=None): INPUT: - - ``lmfdb_label`` -- a string, the LMFDB label of a curve. - This can be the label of a curve (e.g. '990.j1') or of an isogeny - class (e.g. '990.j') + - ``lmfdb_label`` -- string, the LMFDB label of a curve; this can be the + label of a curve (e.g. '990.j1') or of an isogeny class (e.g. '990.j') - ``CDB`` -- the Cremona database in which to look up the isogeny - classes of the same conductor. - - OUTPUT: + classes of the same conductor - - ``cremona_label`` -- a string, the corresponding Cremona label. + OUTPUT: ``cremona_label``; a string, the corresponding Cremona label EXAMPLES:: @@ -708,15 +701,16 @@ def __iter__(self): def __getitem__(self, N): """ - If N is an integer, return all data about level N in the database. - If N is a string it must be a Cremona label, in which case return + If `N` is an integer, return all data about level `N` in the database. + If `N` is a string it must be a Cremona label, in which case return the corresponding elliptic curve, if it is in the database. INPUT: - - ``N`` -- int or str + - ``N`` -- integer or string - OUTPUT: dict (if N is an int) or EllipticCurve (if N is a str) + OUTPUT: dictionary (if `N` is an integer) or EllipticCurve (if `N` is + a string) TESTS:: @@ -765,11 +759,9 @@ def allcurves(self, N): INPUT: - - ``N`` -- int, the conductor - - OUTPUT: + - ``N`` -- integer; the conductor - - ``dict`` -- id:[ainvs, rank, tor], ... + OUTPUT: dictionary; id:[ainvs, rank, tor], ... EXAMPLES:: @@ -795,11 +787,9 @@ def curves(self, N): INPUT: - - ``N`` -- int, the conductor + - ``N`` -- integer; the conductor - OUTPUT: - - - ``dict`` -- id:[ainvs, rank, tor], ... + OUTPUT: dictionary; id:[ainvs, rank, tor], ... EXAMPLES: @@ -956,12 +946,12 @@ def elliptic_curve_from_ainvs(self, ainvs): Return the elliptic curve in the database of with minimal ``ainvs`` if it exists. - This raises a :class:`RuntimeError` exception otherwise. + This raises a :exc:`RuntimeError` exception otherwise. INPUT: - - ``ainvs`` -- list (5-tuple of int's); the minimal - Weierstrass model for an elliptic curve + - ``ainvs`` -- list (5-tuple of int's); the minimal + Weierstrass model for an elliptic curve OUTPUT: EllipticCurve @@ -995,13 +985,11 @@ def elliptic_curve(self, label): INPUT: - - ``label`` -- str (Cremona or LMFDB label) - - OUTPUT: + - ``label`` -- string (Cremona or LMFDB label) - - an :class:`sage.schemes.elliptic_curves.ell_rational_field.EllipticCurve_rational_field` + OUTPUT: an :class:`sage.schemes.elliptic_curves.ell_rational_field.EllipticCurve_rational_field` - .. note:: + .. NOTE:: For more details on LMFDB labels see :func:`parse_lmfdb_label`. @@ -1032,9 +1020,9 @@ def iter(self, conductors): INPUT: - - ``conductors`` -- list or generator of ints + - ``conductors`` -- list or generator of ints - OUTPUT: generator that iterates over EllipticCurve objects. + OUTPUT: generator that iterates over EllipticCurve objects EXAMPLES:: @@ -1088,11 +1076,9 @@ def isogeny_class(self, label): INPUT: - - ``label`` -- string + - ``label`` -- string - OUTPUT: - - - ``list`` -- list of EllipticCurve objects. + OUTPUT: list of EllipticCurve objects EXAMPLES:: @@ -1118,9 +1104,7 @@ def iter_optimal(self, conductors): - ``conductors`` -- list or generator of ints - OUTPUT: - - generator that iterates over EllipticCurve objects. + OUTPUT: generator that iterates over EllipticCurve objects EXAMPLES: @@ -1156,9 +1140,7 @@ def list(self, conductors): - ``conductors`` -- list or generator of ints - OUTPUT: - - - list of EllipticCurve objects. + OUTPUT: list of EllipticCurve objects EXAMPLES:: @@ -1176,12 +1158,10 @@ def list_optimal(self, conductors): INPUT: - - ``conductors`` -- list or generator of ints - list of EllipticCurve objects. + - ``conductors`` -- list or generator of ints list of EllipticCurve + objects - OUTPUT: - - list of EllipticCurve objects. + OUTPUT: list of EllipticCurve objects EXAMPLES:: @@ -1195,9 +1175,7 @@ def largest_conductor(self): """ The largest conductor for which the database is complete. - OUTPUT: - - - ``int`` -- largest conductor + OUTPUT: integer; largest conductor EXAMPLES:: @@ -1216,11 +1194,9 @@ def smallest_conductor(self): """ The smallest conductor for which the database is complete: always 1. - OUTPUT: - - - ``int`` -- smallest conductor + OUTPUT: integer; smallest conductor - .. note:: + .. NOTE:: This always returns the integer 1, since that is the smallest conductor for which the database is complete, @@ -1252,18 +1228,18 @@ def conductor_range(self): def number_of_curves(self, N=0, i=0): """ Return the number of curves stored in the database with conductor - N. If N = 0, returns the total number of curves in the database. + `N`. If `N = 0`, returns the total number of curves in the database. - If i is nonzero, returns the number of curves in the i-th isogeny - class. If i is a Cremona letter code, e.g., 'a' or 'bc', it is + If `i` is nonzero, returns the number of curves in the `i`-th isogeny + class. If `i` is a Cremona letter code, e.g., 'a' or 'bc', it is converted to the corresponding number. INPUT: - - ``N`` -- int - - ``i`` -- int or str + - ``N`` -- integer + - ``i`` -- integer or string - OUTPUT: int + OUTPUT: integer EXAMPLES:: @@ -1302,9 +1278,9 @@ def number_of_isogeny_classes(self, N=0): INPUT: - - ``N`` -- int + - ``N`` -- integer - OUTPUT: int + OUTPUT: integer EXAMPLES:: @@ -1368,7 +1344,6 @@ def _init_from_ftpdata(self, ftpdata, largest_conductor=0): sage: d = sage.databases.cremona.MiniCremonaDatabase(name='cremona', read_only=False, rebuild=True) # not tested sage: d._init_from_ftpdata('/home/jec/ecdata') # not tested - """ if self.__read_only__: raise RuntimeError("The database must not be read_only.") @@ -1408,15 +1383,15 @@ def _init_allcurves(self, ftpdata, largest_conductor=0): INPUT: - - `ftpdata` (string) -- the name of the directory in which the data is + - ``ftpdata`` -- string; the name of the directory in which the data is - - ``largest_conductor`` -- int (default: 0), if 0, - then only include data up to that conductor. + - ``largest_conductor`` -- integer (default: 0); if 0, + then only include data up to that conductor OUTPUT: - - ``int`` -- number_of_curves - - ``int`` -- number_of_isogeny_classes + - integer; number_of_curves + - integer; number_of_isogeny_classes EXAMPLES:: @@ -1485,9 +1460,9 @@ def allbsd(self, N): INPUT: - - ``N`` -- int, the conductor + - ``N`` -- integer; the conductor - OUTPUT: dict containing the allbsd table for each isogeny class + OUTPUT: dictionary containing the allbsd table for each isogeny class in conductor N EXAMPLES:: @@ -1514,11 +1489,9 @@ def allgens(self, N): INPUT: - - ``N`` -- int, the conductor + - ``N`` -- integer; the conductor - OUTPUT: - - - ``dict`` -- id:[points, ...], ... + OUTPUT: dictionary; id:[points, ...], ... EXAMPLES:: @@ -1543,11 +1516,9 @@ def degphi(self, N): INPUT: - - ``N`` -- int, the conductor - - OUTPUT: + - ``N`` -- integer; the conductor - - ``dict`` -- id:degphi, ... + OUTPUT: dictionary; id:degphi, ... EXAMPLES:: @@ -1681,7 +1652,7 @@ def _init_allgens(self, ftpdata, largest_conductor=0): def CremonaDatabase(name=None,mini=None,set_global=None): """ - Initializes the Cremona database with name ``name``. If ``name`` is + Initialize the Cremona database with name ``name``. If ``name`` is ``None`` it instead initializes large Cremona database (named 'cremona'), if available or default mini Cremona database (named 'cremona mini'). diff --git a/src/sage/databases/cubic_hecke_db.py b/src/sage/databases/cubic_hecke_db.py index 782d3c2f771..2f94439e6f0 100644 --- a/src/sage/databases/cubic_hecke_db.py +++ b/src/sage/databases/cubic_hecke_db.py @@ -129,9 +129,9 @@ class CubicHeckeDataSection(Enum): The following choices are possible: - - ``basis`` -- list of basis elements - - ``reg_left_reprs`` -- data for the left regular representation - - ``reg_right_reprs`` -- data for the right regular representation + - ``basis`` -- list of basis elements + - ``reg_left_reprs`` -- data for the left regular representation + - ``reg_right_reprs`` -- data for the right regular representation - ``irr_reprs`` -- data for the split irreducible representations - ``markov_tr_cfs`` -- data for the coefficients of the formal Markov traces @@ -239,9 +239,7 @@ def read(self, section, variables=None, nstrands=4): - ``section`` -- instance of enum :class:`CubicHeckeDataSection` to select the data to be read in - OUTPUT: - - A dictionary containing the data corresponding to the section. + OUTPUT: a dictionary containing the data corresponding to the section EXAMPLES:: @@ -310,8 +308,6 @@ def read_matrix_representation(self, representation_type, gen_ind, nstrands, rin :class:`~sage.algebras.hecke_algebras.cubic_hecke_matrix_rep.RepresentationType` specifying the type of the representation - OUTPUT: - EXAMPLES:: sage: from sage.databases.cubic_hecke_db import CubicHeckeDataBase @@ -418,9 +414,7 @@ def braid_tietze(self, strands_embed=None): - ``strands_embed`` -- (optional) the number of strands of the braid if strands should be added - OUTPUT: - - A tuple representing the braid in Tietze form. + OUTPUT: a tuple representing the braid in Tietze form EXAMPLES:: @@ -660,9 +654,9 @@ class section(Enum): Enum for the different sections of file cache. The following choices are possible: - - ``matrix_representations`` -- file cache for representation matrices + - ``matrix_representations`` -- file cache for representation matrices of basis elements - - ``braid_images`` -- file cache for images of braids + - ``braid_images`` -- file cache for images of braids - ``basis_extensions`` -- file cache for a dynamical growing basis used in the case of cubic Hecke algebras on more than 4 strands - ``markov_trace`` -- file cache for intermediate results of long @@ -1497,7 +1491,6 @@ def read_markov(bas_ele, variables, num_strands=4): the coefficients - ``num_strands`` -- integer (default: 4); the number of strands - OUTPUT: A list of the coefficients. The i'th member corresponds to the i'th diff --git a/src/sage/databases/findstat.py b/src/sage/databases/findstat.py index cba955c68b3..85c06bf06cd 100644 --- a/src/sage/databases/findstat.py +++ b/src/sage/databases/findstat.py @@ -354,16 +354,16 @@ def set_user(self, name=None, email=None): INPUT: - - ``name`` -- the name of the user. + - ``name`` -- the name of the user - - ``email`` -- an email address of the user. + - ``email`` -- an email address of the user This information is used when submitting a statistic with :meth:`FindStatStatistic.submit`. EXAMPLES:: - sage: findstat().set_user(name="Anonymous", email="invalid@org") + sage: findstat().set_user(name='Anonymous', email='invalid@org') .. NOTE:: @@ -383,7 +383,7 @@ def user_name(self): EXAMPLES:: - sage: findstat().set_user(name="Anonymous", email="invalid@org") + sage: findstat().set_user(name='Anonymous', email='invalid@org') sage: findstat().user_name() 'Anonymous' """ @@ -395,7 +395,7 @@ def user_email(self): EXAMPLES:: - sage: findstat().set_user(name="Anonymous", email="invalid@org") + sage: findstat().set_user(name='Anonymous', email='invalid@org') sage: findstat().user_email() 'invalid@org' """ @@ -487,7 +487,6 @@ def _submit(args, url): ....: "CurrentAuthor": "", ....: "CurrentEmail": ""} sage: _submit(args, url) # optional -- webbrowser - """ f = tempfile.NamedTemporaryFile(mode='w', suffix='.html', delete=False) verbose("Created temporary file %s" % f.name, caller_name='FindStat') @@ -514,11 +513,11 @@ def _data_to_str(data, domain, codomain=None): INPUT: - - ``data``, a list of lists of objects + - ``data`` -- list of lists of objects - - ``domain``, a :class:`FindStatCollection` + - ``domain`` -- :class:`FindStatCollection` - - ``codomain`` -- (optional), a :class:`FindStatCollection` or ``None`` + - ``codomain`` -- (optional) :class:`FindStatCollection` or ``None`` If ``codomain`` is ``None``, the values are treated as integers. @@ -567,13 +566,13 @@ def _data_from_iterable(iterable, mapping=False, domain=None, same size, or a single element and a single value. Every object must be a :class:`SageObject`. - - mapping -- (default: ``False``), ``False``, if the codomain is - ``Integer`` and ``True`` if it is a FindStat collection + - ``mapping`` -- boolean (default: ``False``); ``False``, if the codomain + is ``Integer`` and ``True`` if it is a FindStat collection - - domain -- (optional), a :class:`FindStatCollection`, if + - ``domain`` -- (default: ``None``) a :class:`FindStatCollection`, if ``None`` it is guessed from the iterable - - codomain -- (optional), a :class:`FindStatCollection`, if + - ``codomain`` -- (default: ``None``) a :class:`FindStatCollection`, if ``None`` it is guessed from the iterable TESTS:: @@ -682,8 +681,8 @@ def _data_from_function(function, domain): INPUT: - - ``function``, a callable - - ``domain``, a :class:`FindStatCollection` + - ``function`` -- a callable + - ``domain`` -- a :class:`FindStatCollection` If ``function`` returns the value ``None``, the pair is omitted. @@ -707,9 +706,9 @@ def _data_from_data(data, max_values): INPUT: - - ``data``, an iterable over pairs of lists of the same size + - ``data`` -- an iterable over pairs of lists of the same size - - ``max_values``, the maximal number of objects (and values) to + - ``max_values`` -- the maximal number of objects (and values) to return We assume that the number of elements in each pair weakly @@ -750,11 +749,11 @@ def _distribution_from_data(data, domain, max_values, generating_functions=False INPUT: - - ``data``, an iterable over pairs of lists of the same size + - ``data`` -- an iterable over pairs of lists of the same size - - ``domain``, a :class:`FindStatCollection` + - ``domain`` -- a :class:`FindStatCollection` - - ``max_values``, the maximal number of objects (and values) to + - ``max_values`` -- the maximal number of objects (and values) to return TESTS:: @@ -807,11 +806,11 @@ def _generating_functions_from_dict(gfs, style): INPUT: - - ``gfs``, a dictionary whose keys are the levels and whose values + - ``gfs`` -- dictionary whose keys are the levels and whose values are dictionaries from values to multiplicities - - ``style``, one of ``"dictionary"``, ``"list"`` or - ``"polynomial"`` + - ``style`` -- one of ``'dictionary'``, ``'list'`` or + ``'polynomial'`` .. SEEALSO:: @@ -922,9 +921,7 @@ def findstat(query=None, values=None, distribution=None, domain=None, collection, such as ``Permutations(3)``. The keyword arguments ``depth`` and ``max_values`` are passed to the finder. - OUTPUT: - - An instance of a :class:`FindStatStatistic`, represented by + OUTPUT: an instance of a :class:`FindStatStatistic`, represented by - the FindStat identifier together with its name, or @@ -1007,20 +1004,20 @@ def findstat(query=None, values=None, distribution=None, domain=None, sage: findstat("Cc0024") # optional -- internet Set of combinatorial statistics with domain Cc0024: Binary words in FindStat - sage: findstat(domain="Cores") # optional -- internet + sage: findstat(domain='Cores') # optional -- internet Set of combinatorial statistics with domain Cc0013: Cores in FindStat TESTS:: - sage: findstat("Permutations", lambda x: 1, depth="x") # optional -- internet + sage: findstat("Permutations", lambda x: 1, depth='x') # optional -- internet Traceback (most recent call last): ... - ValueError: E021: Depth should be a non-negative integer at most 9, but is x. + ValueError: E021: Depth should be a nonnegative integer at most 9, but is x. sage: findstat("Permutations", lambda x: 1, depth=100) # optional -- internet Traceback (most recent call last): ... - ValueError: E021: Depth should be a non-negative integer at most 9, but is 100. + ValueError: E021: Depth should be a nonnegative integer at most 9, but is 100. sage: S = Permutation sage: findstat([(S([1,2]), 1), ([S([1,3,2]), S([1,2])], [2,3])]) # optional -- internet @@ -1042,7 +1039,7 @@ def findstat(query=None, values=None, distribution=None, domain=None, max_values = int(max_values) assert 0 <= max_values <= FINDSTAT_MAX_VALUES except (ValueError, AssertionError): - raise ValueError("the maximal number of values for a FindStat query must be a non-negative integer less than or equal to %i" % FINDSTAT_MAX_VALUES) + raise ValueError("the maximal number of values for a FindStat query must be a nonnegative integer less than or equal to %i" % FINDSTAT_MAX_VALUES) check_collection = True @@ -1135,18 +1132,17 @@ def findmap(*args, **kwargs): ``distribution``, ``depth`` and ``max_values``. They have the following meanings: - - ``depth`` -- (default ``FINDSTAT_DEFAULT_DEPTH``), a - non-negative integer, specifying how many maps to apply to - generate the given map. + - ``depth`` -- nonnegative integer (default: ``FINDSTAT_DEFAULT_DEPTH``); + specifying how many maps to apply to generate the given map - - ``max_values`` -- (default ``FINDSTAT_MAX_VALUES``), an integer - specifying how many values are sent to the finder. + - ``max_values`` -- integer (default: ``FINDSTAT_MAX_VALUES``); specifying + how many values are sent to the finder - - ``domain``, ``codomain``, an integer or string of the form + - ``domain``, ``codomain`` -- integer or string of the form ``Cc1234``, designates the domain and codomain of the sought - for maps. + for maps - - ``values``, ``distribution``, data specifying the values or + - ``values``, ``distribution`` -- data specifying the values or distribution of values of the sought for maps. The keyword arguments ``depth`` and ``max_values`` are passed to the finder. The data may be specified in one of the following @@ -1242,7 +1238,7 @@ def findmap(*args, **kwargs): sage: findmap("Cc0024") # optional -- internet Set of combinatorial maps with domain Cc0024: Binary words used by FindStat - sage: findmap(codomain="Cores") # optional -- internet + sage: findmap(codomain='Cores') # optional -- internet Set of combinatorial maps with codomain Cc0013: Cores used by FindStat """ if len(args) > 3: @@ -1265,7 +1261,7 @@ def findmap(*args, **kwargs): max_values = int(max_values) assert 0 <= max_values <= FINDSTAT_MAX_VALUES except (ValueError, AssertionError): - raise ValueError("the maximal number of values for a FindStat query must be a non-negative integer less than or equal to %i" % FINDSTAT_MAX_VALUES) + raise ValueError("the maximal number of values for a FindStat query must be a nonnegative integer less than or equal to %i" % FINDSTAT_MAX_VALUES) check_collection = True @@ -1399,13 +1395,13 @@ def __init__(self, id, data=None, function=None): INPUT: - - ``id``, a padded identifier, with number 0 reserved for new + - ``id`` -- a padded identifier, with number 0 reserved for new statistics or maps. - - ``data``, a dictionary with "Description", "Code", etc. + - ``data`` -- dictionary with "Description", "Code", etc. - - ``function`` -- (optional), a callable implementing the - statistic or map, or ``None``. + - ``function`` -- (optional) a callable implementing the + statistic or map, or ``None`` ``data`` should be provided if and only if ``id`` refers to a new statistic or map (with identifier 0). @@ -1569,9 +1565,7 @@ def id(self): r""" Return the FindStat identifier of the statistic or map. - OUTPUT: - - The FindStat identifier of the statistic or map, as an integer. + OUTPUT: the FindStat identifier of the statistic or map, as an integer EXAMPLES:: @@ -1584,9 +1578,7 @@ def id_str(self): r""" Return the FindStat identifier of the statistic or map. - OUTPUT: - - The FindStat identifier of the statistic or map, as a string. + OUTPUT: the FindStat identifier of the statistic or map, as a string EXAMPLES:: @@ -1618,9 +1610,7 @@ def description(self): r""" Return the description of the statistic or map. - OUTPUT: - - A string. For statistics, the first line is used as name. + OUTPUT: string; for statistics, the first line is used as name EXAMPLES:: @@ -1635,8 +1625,8 @@ def set_description(self, value): INPUT: - - a string -- for statistics, this is the name of the - statistic followed by its description on a separate line. + - ``value`` -- string; for statistics, this is the name of the + statistic followed by its description on a separate line This information is used when submitting the statistic or map with :meth:`submit`. @@ -1729,8 +1719,8 @@ def set_references_raw(self, value): INPUT: - - a string -- each reference should be on a single line, and - consist of one or more links to the same item. + - ``value`` -- string; each reference should be on a single line, and + consist of one or more links to the same item FindStat will automatically resolve the links, if possible. A complete list of supported services can be found at @@ -1755,9 +1745,7 @@ def sage_code(self): r""" Return the Sage code associated with the statistic or map. - OUTPUT: - - An empty string or a string of the form:: + OUTPUT: an empty string or a string of the form:: def statistic(x): ... @@ -1781,7 +1769,8 @@ def set_sage_code(self, value): INPUT: - - a string -- SageMath code producing the values of the statistic or map. + - ``value`` -- string; SageMath code producing the values of the + statistic or map Contributors are encouraged to submit code for statistics using :meth:`FindStatStatistic.set_code`. Modifying the @@ -1856,12 +1845,10 @@ def _first_terms_raw(self, max_values): INPUT: - - ``max_values``, an integer determining how many terms to + - ``max_values`` -- integer determining how many terms to return at most - OUTPUT: - - A list of ``(string, value)`` pairs. + OUTPUT: list of ``(string, value)`` pairs This method is overridden in :class:`FindStatStatisticQuery`. @@ -1967,7 +1954,7 @@ def _generating_functions_dict(self, del gfs[lvl] return gfs - def generating_functions(self, style="polynomial", + def generating_functions(self, style='polynomial', max_values=FINDSTAT_MAX_SUBMISSION_VALUES): r""" Return the generating functions of the statistic as a dictionary. @@ -1980,19 +1967,19 @@ def generating_functions(self, style="polynomial", INPUT: - - a string -- (default:"polynomial") can be - "polynomial", "dictionary", or "list". + - ``style`` -- string (default: ``'polynomial'``); can be + ``'polynomial'``, ``'dictionary'``, or ``'list'`` OUTPUT: - - if ``style`` is ``"polynomial"``, the generating function is - returned as a polynomial. + - if ``style`` is ``'polynomial'``, the generating function is + returned as a polynomial - - if ``style`` is ``"dictionary"``, the generating function is + - if ``style`` is ``'dictionary'``, the generating function is returned as a dictionary representing the monomials of the - generating function. + generating function - - if ``style`` is ``"list"``, the generating function is + - if ``style`` is ``'list'``, the generating function is returned as a list of coefficients of the generating function. In this case, leading and trailing zeros are omitted. @@ -2006,13 +1993,13 @@ def generating_functions(self, style="polynomial", 6: q^3 + 3*q^2 + 6*q + 5, 8: q^6 + 4*q^5 + 10*q^4 + 20*q^3 + 28*q^2 + 28*q + 14} - sage: st.generating_functions(style="dictionary") # optional -- internet + sage: st.generating_functions(style='dictionary') # optional -- internet {2: {0: 1}, 4: {0: 2, 1: 1}, 6: {0: 5, 1: 6, 2: 3, 3: 1}, 8: {0: 14, 1: 28, 2: 28, 3: 20, 4: 10, 5: 4, 6: 1}} - sage: st.generating_functions(style="list") # optional -- internet + sage: st.generating_functions(style='list') # optional -- internet {2: [1], 4: [2, 1], 6: [5, 6, 3, 1], 8: [14, 28, 28, 20, 10, 4, 1]} TESTS:: @@ -2045,18 +2032,16 @@ def oeis_search(self, search_size=32, verbose=True): INPUT: - - ``search_size`` (default:32) the number of integers in the + - ``search_size`` -- (default: 32) the number of integers in the sequence. If this is chosen too big, the OEIS result may be corrupted. - - ``verbose`` (default: ``True``) if true, some information about - the search are printed. - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``); if ``True``, some + information about the search are printed - - a tuple of OEIS sequences, see - :meth:`sage.databases.oeis.OEIS.find_by_description` for more - information. + OUTPUT: a tuple of OEIS sequences, see + :meth:`sage.databases.oeis.OEIS.find_by_description` for more + information EXAMPLES:: @@ -2067,7 +2052,7 @@ def oeis_search(self, search_size=32, verbose=True): 0: A067311: Triangle read by rows: T(n,k) gives number of ways of arranging n chords on a circle with k simple intersections ... """ from sage.databases.oeis import oeis - gen_funcs = self.generating_functions(style="list") + gen_funcs = self.generating_functions(style='list') OEIS_string = "" keys = sorted(gen_funcs.keys()) @@ -2139,7 +2124,7 @@ def __init__(self, parent, id): - ``parent`` -- :class:`FindStatStatistics` - - ``id`` -- the (padded) FindStat identifier of the statistic. + - ``id`` -- the (padded) FindStat identifier of the statistic EXAMPLES:: @@ -2250,9 +2235,9 @@ def set_first_terms(self, values): INPUT: - - a list of pairs of the form ``(object, value)`` where + - ``values`` -- list of pairs of the form ``(object, value)`` where ``object`` is a Sage object representing an element of the - appropriate collection and ``value`` is an integer. + appropriate collection and ``value`` is an integer This information is used when submitting the statistic with :meth:`submit`. @@ -2286,9 +2271,9 @@ def code(self): r""" Return the code associated with the statistic or map. - OUTPUT: + OUTPUT: string - A string. Contributors are encouraged to submit Sage code in the form:: + Contributors are encouraged to submit Sage code in the form:: def statistic(x): ... @@ -2315,7 +2300,7 @@ def set_code(self, value): INPUT: - - a string -- code producing the values of the statistic. + - ``value`` -- string; code producing the values of the statistic Contributors are encouraged to submit SageMath code in the form:: @@ -2448,7 +2433,7 @@ def _element_constructor_(self, id): INPUT: - - ``id`` -- a string containing the FindStat identifier of + - ``id`` -- string containing the FindStat identifier of the statistic, or the corresponding integer EXAMPLES:: @@ -2520,7 +2505,7 @@ def _an_element_(self): EXAMPLES:: - sage: findstat(domain="Permutations").an_element() # optional -- internet + sage: findstat(domain='Permutations').an_element() # optional -- internet St000001: The number of reduced words for a permutation. """ try: @@ -2731,7 +2716,7 @@ def __repr__(self): def __getitem__(self, i): """ - Return the t-th result in the query. + Return the `t`-th result in the query. EXAMPLES:: @@ -2933,13 +2918,13 @@ def __init__(self, matching_statistic, offset, quality, domain=None): INPUT: - - ``matching_statistic``, a compound statistic identifier + - ``matching_statistic`` -- a compound statistic identifier - - ``offset``, the offset of the values, as provided by FindStat + - ``offset`` -- the offset of the values, as provided by FindStat - - ``quality``, the quality of the match, as provided by FindStat + - ``quality`` -- the quality of the match, as provided by FindStat - - ``domain`` -- (optional), the domain of the compound statistic + - ``domain`` -- (optional) the domain of the compound statistic EXAMPLES:: @@ -2997,7 +2982,6 @@ def quality(self): sage: r = FindStatMatchingStatistic("St000042oMp00116", 1, [17, 83]) # optional -- internet sage: r.quality() # optional -- internet [17, 83] - """ return self._quality[:] @@ -3238,9 +3222,7 @@ def codomain(self): r""" Return the FindStat collection which is the codomain of the map. - OUTPUT: - - The codomain of the map as a :class:`FindStatCollection`. + OUTPUT: the codomain of the map as a :class:`FindStatCollection` EXAMPLES:: @@ -3254,9 +3236,7 @@ def properties_raw(self): r""" Return the properties of the map. - OUTPUT: - - The properties as a string. + OUTPUT: the properties as a string EXAMPLES:: @@ -3293,7 +3273,7 @@ def set_name(self, value): INPUT: - - a string -- the new name of the map. + - ``value`` -- string; the new name of the map This information is used when submitting the map with :meth:`submit`. @@ -3340,7 +3320,7 @@ class FindStatMaps(UniqueRepresentation, Parent): sage: ccs = sorted(FindStatCollections())[:3] # optional -- internet sage: for cc_dom in ccs: # optional -- internet ....: for cc_codom in ccs: - ....: print(cc_dom.name(style="plural") + " -> " + cc_codom.name(style="plural")) + ....: print(cc_dom.name(style='plural') + " -> " + cc_codom.name(style='plural')) ....: try: ....: print(" " + next(iter(FindStatMaps(cc_dom, cc_codom))).name()) ....: except StopIteration: @@ -3388,7 +3368,7 @@ def _element_constructor_(self, id): INPUT: - - ``id`` -- a string containing the FindStat identifier of + - ``id`` -- string containing the FindStat identifier of the map, or an integer giving its id EXAMPLES:: @@ -3468,7 +3448,7 @@ def _an_element_(self): EXAMPLES:: - sage: findmap(domain="Dyck paths", codomain="Posets").an_element() # optional -- internet + sage: findmap(domain="Dyck paths", codomain='Posets').an_element() # optional -- internet Mp00232: parallelogram poset """ try: @@ -3489,7 +3469,7 @@ def __init__(self, data=None, values_of=None, distribution_of=None, depth=FINDSTAT_DEFAULT_DEPTH, debug=False): """ - Initialize a query for FindStat (compound) maps + Initialize a query for FindStat (compound) maps. INPUT: @@ -3619,7 +3599,7 @@ def __repr__(self): def __getitem__(self, i): """ - Return the i-th result in the query. + Return the `i`-th result in the query. EXAMPLES:: @@ -3747,7 +3727,7 @@ def __call__(self, elt): def __getitem__(self, i): """ - Return the i-th map in the compound map. + Return the `i`-th map in the compound map. EXAMPLES:: @@ -3835,11 +3815,11 @@ def __init__(self, matching_map, quality, domain=None, codomain=None): INPUT: - - ``matching_map``, a compound map identifier + - ``matching_map`` -- a compound map identifier - - ``quality``, the quality of the match, as provided by FindStat + - ``quality`` -- the quality of the match, as provided by FindStat - - ``domain`` -- (optional), the domain of the compound map + - ``domain`` -- (optional) the domain of the compound map - ``codomain`` -- (optional), the codomain of the compound map @@ -3904,15 +3884,13 @@ def info(self): # helper for generation of CartanTypes def _finite_irreducible_cartan_types_by_rank(n): """ - Return the Cartan types of rank n. + Return the Cartan types of rank `n`. INPUT: - - n -- an integer. - - OUTPUT: + - ``n`` -- integer - The list of Cartan types of rank n. + OUTPUT: the list of Cartan types of rank `n` TESTS:: @@ -3942,18 +3920,15 @@ def _plane_partitions_by_size_aux(n, outer=None): INPUT: - - n -- an integer. + - ``n`` -- integer - OUTPUT: - - The plane partitions with `n` boxes as lists. + OUTPUT: the plane partitions with `n` boxes as lists TESTS:: sage: from sage.databases.findstat import _plane_partitions_by_size_aux sage: list(_plane_partitions_by_size_aux(3)) [[[1], [1], [1]], [[2], [1]], [[1, 1], [1]], [[3]], [[2, 1]], [[1, 1, 1]]] - """ if n == 0: yield [] @@ -3976,11 +3951,9 @@ def _plane_partitions_by_size(n): INPUT: - - n -- an integer. + - ``n`` -- integer - OUTPUT: - - The plane partitions with `n` boxes. + OUTPUT: the plane partitions with `n` boxes TESTS:: @@ -3992,7 +3965,6 @@ def _plane_partitions_by_size(n): Plane partition [[3]], Plane partition [[2, 1]], Plane partition [[1, 1, 1]]] - """ for pp in _plane_partitions_by_size_aux(n): yield PlanePartition(pp) @@ -4004,11 +3976,9 @@ def _finite_lattices(n): INPUT: - - n -- an integer. - - OUTPUT: + - ``n`` -- integer - The lattices with `n` elements. + OUTPUT: the lattices with `n` elements TESTS:: @@ -4016,7 +3986,6 @@ def _finite_lattices(n): sage: [L.cover_relations() for L in _finite_lattices(4)] [[['bottom', 0], ['bottom', 1], [0, 'top'], [1, 'top']], [['bottom', 0], [0, 1], [1, 'top']]] - """ if n <= 2: for P in Posets(n): @@ -4102,11 +4071,11 @@ def __init__(self, parent, id, data, sageconstructor_overridden): INPUT: - - ``parent`` -- :class:`FindStatCollections`. + - ``parent`` -- :class:`FindStatCollections` - - ``id`` -- the (padded) FindStat identifier of the collection. + - ``id`` -- the (padded) FindStat identifier of the collection - - ``data`` -- a dictionary containing the properties of the + - ``data`` -- dictionary containing the properties of the collection, such as its name, the corresponding class in sage, and so on. @@ -4267,12 +4236,10 @@ def in_range(self, element): INPUT: - - ``element`` -- a Sage object that belongs to the collection. - - OUTPUT: + - ``element`` -- a Sage object that belongs to the collection - ``True``, if ``element`` is used by the FindStat search - engine, and ``False`` if it is ignored. + OUTPUT: ``True``, if ``element`` is used by the FindStat search + engine, and ``False`` if it is ignored EXAMPLES:: @@ -4371,9 +4338,7 @@ def id(self): r""" Return the FindStat identifier of the collection. - OUTPUT: - - The FindStat identifier of the collection as an integer. + OUTPUT: the FindStat identifier of the collection as an integer EXAMPLES:: @@ -4388,9 +4353,7 @@ def id_str(self): r""" Return the FindStat identifier of the collection. - OUTPUT: - - The FindStat identifier of the collection as a string. + OUTPUT: the FindStat identifier of the collection as a string EXAMPLES:: @@ -4465,9 +4428,7 @@ def _repr_(self): r""" Return the representation of the FindStat collection. - OUTPUT: - - The representation, including the identifier and the name. + OUTPUT: the representation, including the identifier and the name EXAMPLES:: @@ -4479,18 +4440,16 @@ def _repr_(self): return "a subset of %s: %s" % (self.id_str(), self._data["NamePlural"]) return "%s: %s" % (self.id_str(), self._data["NamePlural"]) - def name(self, style="singular"): + def name(self, style='singular'): r""" Return the name of the FindStat collection. INPUT: - - a string -- (default:"singular") can be - "singular", or "plural". - - OUTPUT: + - ``style`` -- string (default: ``'singular'``); can be + ``'singular'``, or ``'plural'`` - The name of the FindStat collection, in singular or in plural. + OUTPUT: the name of the FindStat collection, in singular or in plural EXAMPLES:: @@ -4498,7 +4457,7 @@ def name(self, style="singular"): sage: FindStatCollection("Binary trees").name() # optional -- internet 'Binary tree' - sage: FindStatCollection("Binary trees").name(style="plural") # optional -- internet + sage: FindStatCollection("Binary trees").name(style='plural') # optional -- internet 'Binary trees' """ if style == "singular": @@ -4757,7 +4716,7 @@ def _element_constructor_(self, entry): INPUT: - see :class:`FindStatCollection`. + See :class:`FindStatCollection`. TESTS: diff --git a/src/sage/databases/jones.py b/src/sage/databases/jones.py index 23a7cbd545f..38e8ce47b54 100644 --- a/src/sage/databases/jones.py +++ b/src/sage/databases/jones.py @@ -129,12 +129,10 @@ def _init(self, path): INPUT: - - - ``path`` -- (default works on William Stein install.) - path must be the path to Jones's Number_Fields directory - http://hobbes.la.asu.edu/Number_Fields These files should have - been downloaded using wget. - + - ``path`` -- (default: works on William Stein install) + path must be the path to Jones's Number_Fields directory + (http://hobbes.la.asu.edu/Number_Fields); these files should have + been downloaded using wget EXAMPLES: This is how to create the database from scratch, assuming that the number fields are in the default directory above: From a @@ -171,12 +169,12 @@ def unramified_outside(self, S, d=None, var='a'): INPUT: - - ``S`` -- list or set of primes, or a single prime + - ``S`` -- list or set of primes, or a single prime - - ``d`` -- None (default, in which case all fields of degree <= 6 are returned) - or a positive integer giving the degree of the number fields returned. + - ``d`` -- ``None`` (default, in which case all fields of degree <= 6 are returned) + or a positive integer giving the degree of the number fields returned - - ``var`` -- the name used for the generator of the number fields (default 'a'). + - ``var`` -- the name used for the generator of the number fields (default: ``'a'``) EXAMPLES:: @@ -211,9 +209,9 @@ def get(self, S, var='a'): INPUT: - - ``S`` -- list or set of primes, or a single prime + - ``S`` -- list or set of primes, or a single prime - - ``var`` -- the name used for the generator of the number fields (default 'a'). + - ``var`` -- the name used for the generator of the number fields (default: ``'a'``) EXAMPLES:: @@ -248,12 +246,12 @@ def ramified_at(self, S, d=None, var='a'): INPUT: - - ``S`` -- list or set of primes + - ``S`` -- list or set of primes - - ``d`` -- None (default, in which case all fields of degree <= 6 are returned) - or a positive integer giving the degree of the number fields returned. + - ``d`` -- ``None`` (default, in which case all fields of degree <= 6 are returned) + or a positive integer giving the degree of the number fields returned - - ``var`` -- the name used for the generator of the number fields (default 'a'). + - ``var`` -- the name used for the generator of the number fields (default: ``'a'``) EXAMPLES:: diff --git a/src/sage/databases/knotinfo_db.py b/src/sage/databases/knotinfo_db.py index dc21575d779..779ee127467 100644 --- a/src/sage/databases/knotinfo_db.py +++ b/src/sage/databases/knotinfo_db.py @@ -334,7 +334,7 @@ def diagram_url(self, fname, single=False): #---------------------------------------------------------------------------------------------------------------------------- class KnotInfoDataBase(SageObject, UniqueRepresentation): r""" - Database interface to KnotInfo + Database interface to KnotInfo. The original data are obtained from KnotInfo web-page (URL see the example below). In order to have these data installed during the build process as @@ -385,8 +385,8 @@ def create_filecache(self, force=False): INPUT: - - ``force`` -- optional boolean. If set to ``True`` the existing - file-cache is overwritten + - ``force`` -- boolean (default: ``False``); if set to ``True`` the + existing file-cache is overwritten EXAMPLES:: @@ -658,11 +658,9 @@ def columns(self): @cached_method def read_column_dict(self): r""" - Read the dictionary for the column names from the according sobj-file + Read the dictionary for the column names from the according sobj-file. - OUTPUT: - - A python dictionary containing the column names and types + OUTPUT: a Python dictionary containing the column names and types EXAMPLES:: @@ -711,12 +709,10 @@ def read_row_dict(self): @cached_method def row_names(self): r""" - Return a dictionary to obtain the original name to a row_dict key + Return a dictionary to obtain the original name to a row_dict key. - OUTPUT: - - A python dictionary containing the names of the knots and links - together with their original names from the database, + OUTPUT: a Python dictionary containing the names of the knots and links + together with their original names from the database EXAMPLES:: @@ -737,9 +733,7 @@ def read_num_knots(self): Read the number of knots contained in the database (without proper links) from the according sobj-file. - OUTPUT: - - Integer + OUTPUT: integer EXAMPLES:: @@ -758,16 +752,14 @@ def read_num_knots(self): @cached_method def read(self, column): r""" - Access a column of KnotInfo / LinkInfo + Access a column of KnotInfo / LinkInfo. INPUT: - ``column`` -- instance of enum :class:`KnotInfoColumns` to select the data to be read in - OUTPUT: - - A python list containing the data corresponding to the column. + OUTPUT: a Python list containing the data corresponding to the column EXAMPLES:: diff --git a/src/sage/databases/oeis.py b/src/sage/databases/oeis.py index 03caa9cc36c..dec5cabd8a4 100644 --- a/src/sage/databases/oeis.py +++ b/src/sage/databases/oeis.py @@ -167,11 +167,9 @@ def _fetch(url): INPUT: - - ``url`` -- a string corresponding to the URL to be fetched. + - ``url`` -- string corresponding to the URL to be fetched - OUTPUT: - - - a string representing the fetched web page. + OUTPUT: string representing the fetched web page TESTS:: @@ -198,11 +196,9 @@ def _urls(html_string): INPUT: - - ``html_string`` -- a string representing some HTML code. - - OUTPUT: + - ``html_string`` -- string representing some HTML code - - a list of (string) URLs contained in ``html_string``. + OUTPUT: list of (string) URLs contained in ``html_string`` EXAMPLES:: @@ -398,18 +394,15 @@ def __repr__(self) -> str: def find_by_id(self, ident, fetch=False): r""" - INPUT: - - ``ident`` -- a string representing the A-number of the sequence - or an integer representing its number. + - ``ident`` -- string representing the A-number of the sequence + or an integer representing its number - - ``fetch`` -- (bool, default: ``False``) whether to force fetching the - content of the sequence on the internet. + - ``fetch`` -- boolean (default: ``False``); whether to force fetching the + content of the sequence on the internet - OUTPUT: - - - The OEIS sequence whose A-number or number corresponds to ``ident``. + OUTPUT: the OEIS sequence whose A-number or number corresponds to ``ident`` EXAMPLES:: @@ -426,15 +419,12 @@ def find_by_id(self, ident, fetch=False): def find_by_entry(self, entry): r""" - INPUT: - - ``entry`` -- a string corresponding to an entry in the internal format - of the OEIS. + - ``entry`` -- string corresponding to an entry in the internal format + of the OEIS - OUTPUT: - - - The corresponding OEIS sequence. + OUTPUT: the corresponding OEIS sequence EXAMPLES:: @@ -454,7 +444,7 @@ def find_by_description(self, description, max_results=3, first_result=0): INPUT: - - ``description`` -- (string) the description the searched sequences. + - ``description`` -- string; the description the searched sequences - ``max_results`` -- (integer, default: 3) the maximum number of results we want. In any case, the on-line encyclopedia will not return more @@ -507,20 +497,20 @@ def find_by_subsequence(self, subsequence, max_results=3, first_result=0): INPUT: - - ``subsequence`` -- a list or tuple of integers. + - ``subsequence`` -- list or tuple of integers - - ``max_results`` -- (integer, default: 3), the maximum of results requested. + - ``max_results`` -- integer (default: 3); the maximum of results requested - - ``first_result`` -- (integer, default: 0) allow to skip the + - ``first_result`` -- integer (default: 0); allow to skip the ``first_result`` first results in the search, to go further. This is useful if you are looking for a sequence that may appear after the 100 first found sequences. OUTPUT: - - a tuple (with fancy formatting) of at most ``max_results`` OEIS - sequences. Those sequences can be used without the need to fetch the - database again. + A tuple (with fancy formatting) of at most ``max_results`` OEIS + sequences. Those sequences can be used without the need to fetch the + database again. EXAMPLES:: @@ -552,14 +542,12 @@ def _imaginary_entry(self, ident='A999999', keywords=''): INPUT: - - ``ident`` -- a string representing the A-number of the sequence. + - ``ident`` -- string representing the A-number of the sequence - - ``keywords`` -- a string corresponding to the keyword field of the - sequence. + - ``keywords`` -- string corresponding to the keyword field of the + sequence - OUTPUT: - - - a string representing the entry of the sequence. + OUTPUT: string representing the entry of the sequence TESTS:: @@ -570,7 +558,6 @@ def _imaginary_entry(self, ident='A999999', keywords=''): sage: s = oeis.find_by_entry(entry=oeis._imaginary_entry(ident='A999998', keywords=keywords)) sage: ','.join(s.keywords()) == keywords True - """ return ('%I ' + ident + ' M9999 N9999\n' '%S ' + ident + ' 1,1,1,1,2,1,1,1,\n' @@ -612,14 +599,12 @@ def _imaginary_sequence(self, ident='A999999', keywords='sign,easy'): INPUT: - - ``ident`` -- a string representing the A-number of the sequence. + - ``ident`` -- string representing the A-number of the sequence - - ``keywords`` -- string (default: 'sign,easy'), a list of words - separated by commas. + - ``keywords`` -- string (default: ``'sign,easy'``); a list of words + separated by commas - OUTPUT: - - - OEIS sequence. + OUTPUT: OEIS sequence TESTS:: @@ -689,8 +674,8 @@ def __init__(self, ident): INPUT: - - ``ident`` -- a string representing the A-number of the sequence or an - integer representing its number. + - ``ident`` -- string representing the A-number of the sequence or an + integer representing its number TESTS:: @@ -754,7 +739,7 @@ def id(self, format='A'): INPUT: - - ``format`` -- (string, default: 'A'). + - ``format`` -- string (default: ``'A'``) OUTPUT: @@ -791,9 +776,7 @@ def __hash__(self): This method allows unique representation of OEIS sequences. - OUTPUT: - - - Python `int`. + OUTPUT: Python integer EXAMPLES:: @@ -825,9 +808,7 @@ def raw_entry(self): The raw entry is fetched online if needed. - OUTPUT: - - - string. + OUTPUT: string EXAMPLES:: @@ -856,9 +837,7 @@ def name(self) -> str: r""" Return the name of the sequence ``self``. - OUTPUT: - - - string. + OUTPUT: string EXAMPLES:: @@ -920,9 +899,7 @@ def offsets(self): from 1) whose absolute value is greater than 1. This is set to 1 if all the terms are 0 or +-1. - OUTPUT: - - - tuple of two elements. + OUTPUT: tuple of two elements EXAMPLES:: @@ -947,9 +924,7 @@ def author(self): r""" Return the author of the sequence in the encyclopedia. - OUTPUT: - - - string. + OUTPUT: string EXAMPLES:: @@ -971,9 +946,7 @@ def keywords(self, warn=True): r""" Return the keywords associated to the sequence ``self``. - OUTPUT: - - - tuple of strings. + OUTPUT: tuple of strings EXAMPLES:: @@ -1179,7 +1152,6 @@ def is_finite(self): sage: s = oeis._imaginary_sequence(ident='A999993', keywords='nonn,finit') sage: s.is_finite() True - """ if 'finit' in self.keywords() or 'full' in self.keywords(): return True @@ -1237,13 +1209,11 @@ def first_terms(self, number=None): INPUT: - - ``number`` -- (integer or ``None``, default: ``None``) the number of + - ``number`` -- integer or ``None`` (default); the number of terms returned (if less than the number of available terms). When set - to None, returns all the known terms. - - OUTPUT: + to ``None``, returns all the known terms. - - tuple of integers. + OUTPUT: tuple of integers EXAMPLES:: @@ -1273,9 +1243,7 @@ def _repr_(self): r""" Print the sequence number and a short summary of this sequence. - OUTPUT: - - - string. + OUTPUT: string EXAMPLES:: @@ -1297,11 +1265,9 @@ def __call__(self, k): INPUT: - - ``k`` -- integer. + - ``k`` -- integer - OUTPUT: - - - integer. + OUTPUT: integer .. NOTE:: @@ -1354,18 +1320,16 @@ def __call__(self, k): def __getitem__(self, i): r""" - Return the ``i``th element of sequence ``self``, viewed as a tuple. + Return the `i`-th element of sequence ``self``, viewed as a tuple. The first element appearing in the sequence ``self``corresponds to ``self[0]``. Do not confuse with calling ``self(k)``. INPUT: - - ``i`` -- integer. + - ``i`` -- integer - OUTPUT: - - - integer. + OUTPUT: integer EXAMPLES:: @@ -1395,9 +1359,7 @@ def __iter__(self): those first terms are exhausted and the real associated sequence still have terms to produce. - OUTPUT: - - - integer. + OUTPUT: integer EXAMPLES:: @@ -1498,12 +1460,12 @@ def links(self, browse=None, format='guess'): INPUT: - - ``browse`` -- an integer, a list of integers, or the word 'all' - (default: ``None``): which links to open in a web browser. + - ``browse`` -- integer; a list of integers, or the word 'all' + (default: ``None``) which links to open in a web browser - - ``format`` -- string (default: 'guess'): how to display the links. + - ``format`` -- string (default: ``'guess'``); how to display the links - OUTPUT: Tuple of strings (with fancy formatting): + OUTPUT: tuple of strings (with fancy formatting): - if ``format`` is ``url``, returns a tuple of absolute links without description. - if ``format`` is ``html``, returns nothing but prints a tuple of clickable absolute links in their context. @@ -1534,7 +1496,7 @@ def links(self, browse=None, format='guess'): sage: s.links(format='url')[3] 'https://oeis.org/A000024' - sage: HTML = s.links(format="html"); HTML + sage: HTML = s.links(format='html'); HTML 0: Wikipedia, 42 (number) 1: See. also github issue #42 ... @@ -1597,7 +1559,7 @@ def cross_references(self, fetch=False): INPUT: - - ``fetch`` -- boolean (default: ``False``). + - ``fetch`` -- boolean (default: ``False``) OUTPUT: @@ -1725,9 +1687,7 @@ def url(self): r""" Return the URL of the page associated to the sequence ``self``. - OUTPUT: - - - string. + OUTPUT: string EXAMPLES:: @@ -1828,15 +1788,15 @@ def programs(self, language='all', preparsing=True, keep_comments=False): INPUT: - - ``language`` -- string (default: 'all'), the chosen language. + - ``language`` -- string (default: ``'all'``); the chosen language. Possible values are 'all' for the full list, or any language name, for example 'sage', 'maple', 'mathematica', etc. Some further optional input is specific to sage code treatment: - - ``preparsing`` -- boolean (default: ``True``) whether to preparse + - ``preparsing`` -- boolean (default: ``True``); whether to preparse sage code - - ``keep_comments`` -- boolean (default: ``False``) whether to keep + - ``keep_comments`` -- boolean (default: ``False``); whether to keep comments in sage code OUTPUT: @@ -2070,7 +2030,7 @@ def __getslice__(self, i, j): def __getitem__(self, x): r""" If ``x`` is a slice return the corresponding sub FancyTuple, - else return the `̀`x``-th item of ``self``. + else return the ``x``-th item of ``self``. TESTS:: diff --git a/src/sage/databases/sloane.py b/src/sage/databases/sloane.py index 048aa221e6c..78fc268b486 100644 --- a/src/sage/databases/sloane.py +++ b/src/sage/databases/sloane.py @@ -109,7 +109,9 @@ def __init__(self): def __repr__(self): """ - String representation of this database. OUTPUT: str + String representation of this database. + + OUTPUT: string """ return "Local copy of Sloane Online Encyclopedia of Integer Sequences" @@ -124,11 +126,11 @@ def __iter__(self): def __getitem__(self, N): """ Return sequence N in the encyclopedia. If sequence N does not - exist, return []. + exist, return ``[]``. INPUT: - - ``N`` -- int + - ``N`` -- integer OUTPUT: list """ @@ -155,9 +157,9 @@ def find(self, seq, maxresults=30): INPUT: - - ``seq`` -- list + - ``seq`` -- list - - ``maxresults`` -- int + - ``maxresults`` -- integer OUTPUT: list of 2-tuples (i, v), where v is a sequence with seq as a subsequence. @@ -175,24 +177,24 @@ def find(self, seq, maxresults=30): return answer - def install(self, oeis_url="https://oeis.org/stripped.gz", - names_url="https://oeis.org/names.gz", overwrite=False): + def install(self, oeis_url='https://oeis.org/stripped.gz', + names_url='https://oeis.org/names.gz', overwrite=False): """ Download and install the online encyclopedia, raising an IOError if either step fails. INPUT: - - ``oeis_url`` -- string (default: "https://oeis.org...") - The URL of the stripped.gz encyclopedia file. + - ``oeis_url`` -- string (default: ``'https://oeis.org...'``) + The URL of the stripped.gz encyclopedia file - - ``names_url`` -- string (default: "https://oeis.org...") + - ``names_url`` -- string (default: ``'https://oeis.org...'``) The URL of the names.gz encyclopedia file. If you do not want to download this file, set names_url=None. - - ``overwrite`` -- boolean (default: ``False``) If the encyclopedia is + - ``overwrite`` -- boolean (default: ``False``); if the encyclopedia is already installed and overwrite=True, download and install the latest - version over the installed one. + version over the installed one """ # See if the encyclopedia already exists if not overwrite and os.path.exists(self.__file__): @@ -226,14 +228,14 @@ def install_from_gz(self, stripped_file, names_file, overwrite=False): INPUT: - - ``stripped_file`` -- string. The name of the stripped.gz OEIS file. + - ``stripped_file`` -- string; the name of the stripped.gz OEIS file - - ``names_file`` -- string. The name of the names.gz OEIS file, or - None if the user does not want it installed. + - ``names_file`` -- string; the name of the names.gz OEIS file, or + None if the user does not want it installed - - ``overwrite`` -- boolean (default: ``False``) If the encyclopedia is - already installed and overwrite=True, install 'filename' over the - old encyclopedia. + - ``overwrite`` -- boolean (default: ``False``); if the encyclopedia is + already installed and ``overwrite=True``, install 'filename' over the + old encyclopedia """ if not overwrite and os.path.exists(self.__file__): raise OSError("Sloane encyclopedia is already installed") @@ -307,11 +309,11 @@ def sequence_name(self, N): Return the name of sequence ``N`` in the encyclopedia. If sequence ``N`` does not exist, return ``''``. If the names - database is not installed, raise an :class:`IOError`. + database is not installed, raise an :exc:`IOError`. INPUT: - - ``N`` -- int + - ``N`` -- integer OUTPUT: string @@ -352,9 +354,9 @@ def copy_gz_file(gz_source, bz_destination): INPUT: - - ``gz_source`` -- string. The name of the gzipped file. + - ``gz_source`` -- string; the name of the gzipped file - - ``bz_destination`` -- string. The name of the newly compressed file. + - ``bz_destination`` -- string; the name of the newly compressed file """ import gzip diff --git a/src/sage/databases/sql_db.py b/src/sage/databases/sql_db.py index bdb407b5361..edef584b6d4 100644 --- a/src/sage/databases/sql_db.py +++ b/src/sage/databases/sql_db.py @@ -141,7 +141,6 @@ def verify_type(type): Traceback (most recent call last): ... TypeError: float is not a legal type. - """ types = ['INTEGER','INT','BOOLEAN','REAL','TEXT','BOOL','BLOB','NOTYPE'] if type.upper() not in types: @@ -283,19 +282,19 @@ def _create_print_table(cur, col_titles, **kwds): KEYWORDS: - ``max_field_size`` -- how wide each field can be - - ``format_cols`` -- a dictionary that allows the user to specify the + - ``format_cols`` -- dictionary that allows the user to specify the format of a column's output by supplying a function. The format of the dictionary is:: {'column_name':(lambda x: format_function(x))} - - ``plot_cols`` -- a dictionary that allows the user to specify that a + - ``plot_cols`` -- dictionary that allows the user to specify that a plot should be drawn by the object generated by a data slice. Note that plot kwds are permitted. The dictionary format is:: {'column_name':((lambda x: plot_function(x)),**kwds)} - - ``relabel_cols`` -- a dictionary to specify a relabeling of column + - ``relabel_cols`` -- dictionary to specify a relabeling of column headers. The dictionary format is:: {'table_name':{'old_col_name':'new_col_name'}} @@ -303,8 +302,8 @@ def _create_print_table(cur, col_titles, **kwds): - ``id_col`` -- reference to a column that can be used as an object identifier for each row - - ``html_table`` -- boolean that if True creates an html table instead of - a print table. Always set to True in the notebook. + - ``html_table`` -- boolean that if ``True`` creates an html table instead of + a print table. Always set to ``True`` in the notebook EXAMPLES:: @@ -406,7 +405,7 @@ def __init__(self, database, *args, **kwds): INPUT: - ``database`` -- a SQLDatabase object - - ``query_dict`` -- a dictionary specifying the query itself. The + - ``query_dict`` -- dictionary specifying the query itself. The format is:: {'table_name':'tblname', 'display_cols':['col1', 'col2','col3'], 'expression': [col, operator, value]} @@ -447,7 +446,6 @@ def __init__(self, database, *args, **kwds): Traceback (most recent call last): ... ValueError: Table has no column c1 - """ if not isinstance(database, SQLDatabase): raise TypeError('%s is not a valid SQLDatabase' % database) @@ -616,19 +614,19 @@ def show(self, **kwds): KEYWORDS: - ``max_field_size`` -- how wide each field can be - - ``format_cols`` -- a dictionary that allows the user to specify the + - ``format_cols`` -- dictionary that allows the user to specify the format of a column's output by supplying a function. The format of the dictionary is:: {'column_name':(lambda x: format_function(x))} - - ``plot_cols`` -- a dictionary that allows the user to specify that a + - ``plot_cols`` -- dictionary that allows the user to specify that a plot should be drawn by the object generated by a data slice. Note that plot kwds are permitted. The dictionary format is:: {'column_name':((lambda x: plot_function(x)),**kwds)} - - ``relabel_cols`` -- a dictionary to specify a relabeling of column + - ``relabel_cols`` -- dictionary to specify a relabeling of column headers. The dictionary format is:: {'table_name':{'old_col_name':'new_col_name'}} @@ -706,14 +704,14 @@ def intersect(self, other, join_table=None, join_dict=None, Return a new ``SQLQuery`` that is the intersection of ``self`` and ``other``. ``join_table`` and ``join_dict`` can be ``None`` iff the two queries only search one table in the database. All display columns - will be concatenated in order: self display cols + other display cols. + will be concatenated in order: ``self`` display cols + other display cols. INPUT: - ``other`` -- the ``SQLQuery`` to intersect with - ``join_table`` -- base table to join on (This table should have at least one column in each table to join on). - - ``join_dict`` -- a dictionary that represents the join structure for + - ``join_dict`` -- dictionary that represents the join structure for the new query. (Must include a mapping for all tables, including those previously joined in either query). Structure is given by:: @@ -837,23 +835,23 @@ def _merge_queries(self, other, ret, join_table, join_dict, operator): def union(self, other, join_table=None, join_dict=None, in_place=False): """ - Return a new ``SQLQuery`` that is the union of self and other. + Return a new ``SQLQuery`` that is the union of ``self`` and ``other``. ``join_table`` and ``join_dict`` can be ``None`` iff the two queries only search one table in the database. All display columns will be - concatenated in order: self display cols + other display cols. + concatenated in order: ``self`` display cols + other display cols. INPUT: - ``other`` -- the ``SQLQuery`` to union with - ``join_table`` -- base table to join on (This table should have at least one column in each table to join on). - - ``join_dict`` -- a dictionary that represents the join structure for + - ``join_dict`` -- dictionary that represents the join structure for the new query. (Must include a mapping for all tables, including those previously joined in either query). Structure is given by:: {'join_table1':('corr_base_col1', 'col1'), 'join_table2':('corr_base_col2', 'col2')} - where ``join_table1` is to be joined with ``join_table`` on + where ``join_table1`` is to be joined with ``join_table`` on ``join_table.corr_base_col1=join_table1.col1`` EXAMPLES:: @@ -899,7 +897,7 @@ def __init__(self, filename=None, read_only=None, skeleton=None): INPUT: - - ``filename`` -- a string + - ``filename`` -- string - ``skeleton`` -- a triple-indexed dictionary:: | - outer key -- table name @@ -1065,7 +1063,6 @@ def __init__(self, filename=None, read_only=None, skeleton=None): Call ``cleanup()`` on the temporary directory to, well, clean it up:: sage: d.cleanup() - """ if filename is None: if read_only is None: @@ -1243,8 +1240,8 @@ def get_skeleton(self, check=False): INPUT: - - ``check`` -- if True, checks to make sure the database's actual - structure matches the skeleton on record. + - ``check`` -- if ``True``, checks to make sure the database's actual + structure matches the skeleton on record EXAMPLES:: @@ -1403,7 +1400,7 @@ def create_table(self, table_name, table_skeleton): INPUT: - - ``table_name`` -- a string + - ``table_name`` -- string - ``table_skeleton`` -- a double-indexed dictionary - outer key -- column name @@ -1486,7 +1483,7 @@ def add_column(self, table_name, col_name, col_dict, default='NULL'): INPUT: - - ``col_dict`` -- a dictionary: + - ``col_dict`` -- dictionary: - key -- column name @@ -1734,7 +1731,6 @@ def rename_table(self, table_name, new_name): sage: D.show('lucy') col1 -------------------- - """ if self.__read_only__: raise RuntimeError('Cannot rename tables in a read only database.') @@ -1756,7 +1752,7 @@ def drop_table(self, table_name): INPUT: - - ``table_name`` -- a string + - ``table_name`` -- string EXAMPLES:: @@ -1811,8 +1807,8 @@ def make_index(self, col_name, table_name, unique=False): INPUT: - - ``col_name`` -- a string - - ``table_name`` -- a string + - ``col_name`` -- string + - ``table_name`` -- string - ``unique`` -- requires that there are no multiple entries in the column, makes searching faster @@ -1912,7 +1908,6 @@ def make_unique(self, table_name, col_name): 'primary_key': False, 'sql': 'INTEGER', 'unique': True}}} - """ if self.__read_only__: raise RuntimeError('Cannot modify a read only database') @@ -2094,7 +2089,7 @@ def delete_rows(self, query): INPUT: - ``query`` -- a ``SQLQuery`` (Delete the rows returned when query is - run). + run) EXAMPLES:: @@ -2146,9 +2141,9 @@ def add_rows(self, table_name, rows, entry_order=None): """ INPUT: - - ``rows`` -- a list of tuples that represent one row of data to add + - ``rows`` -- list of tuples that represent one row of data to add (types should match col types in order) - - ``entry_order`` -- an ordered list or tuple overrides normal order + - ``entry_order`` -- an ordered list or tuple overrides normal order with user defined order EXAMPLES:: diff --git a/src/sage/databases/stein_watkins.py b/src/sage/databases/stein_watkins.py index 5c9c63a2669..c30bf4d914f 100644 --- a/src/sage/databases/stein_watkins.py +++ b/src/sage/databases/stein_watkins.py @@ -26,11 +26,10 @@ 999, inclusive. - The command ``SteinWatkinsPrimeData(n)`` returns an iterator over the curves - in the `n^{th}` Stein-Watkins prime table, which contains prime conductor + in the `n`-th Stein-Watkins prime table, which contains prime conductor elliptic curves of conductor between `n10^8` and `(n+1)10^8`. Here `n` varies between 0 and 99, inclusive. - EXAMPLES: We obtain the first table of elliptic curves. :: @@ -213,7 +212,7 @@ def __iter__(self): Stein-Watkins isogeny class of conductor 20 """ try: - file = bz2.open(self._file, 'rt', encoding="utf-8") + file = bz2.open(self._file, 'rt', encoding='utf-8') except OSError: raise OSError("The Stein-Watkins data file %s must be installed." % self._file) C = None diff --git a/src/sage/databases/symbolic_data.py b/src/sage/databases/symbolic_data.py index 0c6c4fbfc0a..f3f33192290 100644 --- a/src/sage/databases/symbolic_data.py +++ b/src/sage/databases/symbolic_data.py @@ -96,7 +96,7 @@ def __init__(self): self.__intpath = path + "/Data/XMLResources/INTPS/" self.__genpath = path + "/Data/XMLResources/GenPS/" - def get_ideal(self, name, base_ring=QQ, term_order="degrevlex"): + def get_ideal(self, name, base_ring=QQ, term_order='degrevlex'): """ Return the ideal given by 'name' over the base ring given by 'base_ring' in a polynomial ring with the term order given by @@ -130,8 +130,6 @@ def _getTextFromNode(node): return t def _dom2ideal(node): - """ - """ l = [] if str(node.nodeName) in ['vars', 'poly']: diff --git a/src/sage/doctest/control.py b/src/sage/doctest/control.py index cf9c32edd63..4908959e497 100644 --- a/src/sage/doctest/control.py +++ b/src/sage/doctest/control.py @@ -159,7 +159,7 @@ def _repr_(self): EXAMPLES:: sage: from sage.doctest.control import DocTestDefaults - sage: DocTestDefaults(timeout=100, foobar="hello") + sage: DocTestDefaults(timeout=100, foobar='hello') DocTestDefaults(foobar='hello', timeout=100) """ s = "DocTestDefaults(" @@ -203,7 +203,7 @@ def __ne__(self, other): def skipdir(dirname): """ - Return True if and only if the directory ``dirname`` should not be + Return ``True`` if and only if the directory ``dirname`` should not be doctested. EXAMPLES:: @@ -228,10 +228,10 @@ def skipfile(filename, tested_optional_tags=False, *, - ``filename`` -- name of a file - - ``tested_optional_tags`` -- a list or tuple or set of optional tags to test, + - ``tested_optional_tags`` -- list or tuple or set of optional tags to test, or ``False`` (no optional test) or ``True`` (all optional tests) - - ``if_installed`` -- (boolean, default ``False``) whether to skip Python/Cython files + - ``if_installed`` -- boolean (default: ``False``); whether to skip Python/Cython files that are not installed as modules - ``log`` -- function to call with log messages, or ``None`` @@ -246,7 +246,7 @@ def skipfile(filename, tested_optional_tags=False, *, sage: from sage.doctest.control import skipfile sage: skipfile("skipme.c") True - sage: filename = tmp_filename(ext=".pyx") + sage: filename = tmp_filename(ext='.pyx') sage: skipfile(filename) False sage: with open(filename, "w") as f: @@ -388,9 +388,9 @@ def __init__(self, options, args): INPUT: - - options -- either options generated from the command line by sage-runtests - or a DocTestDefaults object (possibly with some entries modified) - - args -- a list of filenames to doctest + - ``options`` -- either options generated from the command line by sage-runtests + or a DocTestDefaults object (possibly with some entries modified) + - ``args`` -- list of filenames to doctest EXAMPLES:: @@ -613,7 +613,7 @@ def second_on_modern_computer(self): Float. The wall time on your computer that would be equivalent to one second on a modern computer. Unless you have kick-ass hardware this should always be >= 1.0. This raises a - :class:`RuntimeError` if there are no stored timings to use as + :exc:`RuntimeError` if there are no stored timings to use as benchmark. EXAMPLES:: @@ -772,7 +772,7 @@ def save_stats(self, filename): with atomic_write(filename) as stats_file: json.dump(self.stats, stats_file, sort_keys=True, indent=4) - def log(self, s, end="\n"): + def log(self, s, end='\n'): """ Log the string ``s + end`` (where ``end`` is a newline by default) to the logfile and print it to the standard output. @@ -819,14 +819,13 @@ def log(self, s, end="\n"): sage: with open(DD.logfile) as f: ....: print(f.read()) hello world - """ self.logger.write(s + end) self.logger.flush() def create_run_id(self): """ - Creates the run id. + Create the run id. EXAMPLES:: @@ -840,7 +839,7 @@ def create_run_id(self): def add_files(self): r""" - Checks for the flags '--all' and '--new'. + Check for the flags '--all' and '--new'. For each one present, this function adds the appropriate directories and files to the todo list. @@ -956,7 +955,7 @@ def all_doc_sources(): def expand_files_into_sources(self): r""" - Expands ``self.files``, which may include directories, into a + Expand ``self.files``, which may include directories, into a list of :class:`sage.doctest.FileDocTestSource` This function also handles the optional command line option. @@ -1099,9 +1098,7 @@ def source_baseline(self, source): - ``source`` -- a :class:`DocTestSource` instance - OUTPUT: - - A dictionary. + OUTPUT: a dictionary EXAMPLES:: @@ -1120,7 +1117,7 @@ def source_baseline(self, source): def run_doctests(self): """ - Actually runs the doctests. + Actually run the doctests. This function is called by :meth:`run`. @@ -1185,7 +1182,7 @@ def run_doctests(self): def cleanup(self, final=True): """ - Runs cleanup activities after actually running doctests. + Run cleanup activities after actually running doctests. In particular, saves the stats to disk and closes the logfile. @@ -1235,7 +1232,7 @@ def _optional_tags_string(self): """ Return a string describing the optional tags used. - OUTPUT: a string with comma-separated tags (without spaces, so + OUTPUT: string with comma-separated tags (without spaces, so it can be used to build a command-line) EXAMPLES:: @@ -1244,10 +1241,10 @@ def _optional_tags_string(self): sage: DC = DocTestController(DocTestDefaults(), []) sage: DC._optional_tags_string() 'sage' - sage: DC = DocTestController(DocTestDefaults(optional="all,and,some,more"), []) + sage: DC = DocTestController(DocTestDefaults(optional='all,and,some,more'), []) sage: DC._optional_tags_string() 'all' - sage: DC = DocTestController(DocTestDefaults(optional="sage,openssl"), []) + sage: DC = DocTestController(DocTestDefaults(optional='sage,openssl'), []) sage: DC._optional_tags_string() 'openssl,sage' """ @@ -1288,8 +1285,8 @@ def run_val_gdb(self, testing=False): INPUT: - - ``testing`` -- boolean; if True then the command to be run - will be printed rather than a subprocess started. + - ``testing`` -- boolean (default: ``False``); if ``True`` then the + command to be run will be printed rather than a subprocess started EXAMPLES: @@ -1305,7 +1302,7 @@ def run_val_gdb(self, testing=False): :: - sage: DD = DocTestDefaults(valgrind=True, optional="all", timeout=172800) + sage: DD = DocTestDefaults(valgrind=True, optional='all', timeout=172800) sage: DC = DocTestController(DD, ["hello_world.py"]) sage: DC.run_val_gdb(testing=True) exec valgrind --tool=memcheck --leak-resolution=high --leak-check=full --num-callers=25 --suppressions="...valgrind/pyalloc.supp" --suppressions="...valgrind/sage.supp" --suppressions="...valgrind/sage-additional.supp" --log-file=.../valgrind/sage-memcheck.%p... sage-runtests --serial --timeout=172800 --optional=all hello_world.py @@ -1590,13 +1587,13 @@ def run(self): def run_doctests(module, options=None): """ - Runs the doctests in a given file. + Run the doctests in a given file. INPUT: - - ``module`` -- a Sage module, a string, or a list of such. + - ``module`` -- a Sage module, a string, or a list of such - - ``options`` -- a DocTestDefaults object or None. + - ``options`` -- a DocTestDefaults object or ``None`` EXAMPLES:: diff --git a/src/sage/doctest/fixtures.py b/src/sage/doctest/fixtures.py index 01f931727df..033b0671c06 100644 --- a/src/sage/doctest/fixtures.py +++ b/src/sage/doctest/fixtures.py @@ -125,13 +125,11 @@ def __init__(self, delegate, prefix=" ", reads=True): INPUT: - - ``delegate`` -- the actual object to be proxied. + - ``delegate`` -- the actual object to be proxied - - ``prefix`` -- (default: ``" "``) - string to prepend to each printed output. + - ``prefix`` -- (default: ``" "``) string to prepend to each printed output - - ``reads`` -- (default: ``True``) - whether to trace read access as well. + - ``reads`` -- (default: ``True``) whether to trace read access as well EXAMPLES:: @@ -238,13 +236,13 @@ def __init__(self, delegate, **kwds): INPUT: - - ``delegate`` -- the actual object to be proxied. + - ``delegate`` -- the actual object to be proxied - ``prefix`` -- (default: ``" "``) - string to prepend to each printed output. + string to prepend to each printed output - ``reads`` -- (default: ``True``) - whether to trace read access as well. + whether to trace read access as well EXAMPLES:: @@ -332,15 +330,15 @@ def trace_method(obj, meth, **kwds): INPUT: - - ``obj`` -- the object containing the method. + - ``obj`` -- the object containing the method - - ``meth`` -- the name of the method to be traced. + - ``meth`` -- the name of the method to be traced - ``prefix`` -- (default: ``" "``) - string to prepend to each printed output. + string to prepend to each printed output - ``reads`` -- (default: ``True``) - whether to trace read access as well. + whether to trace read access as well EXAMPLES:: diff --git a/src/sage/doctest/forker.py b/src/sage/doctest/forker.py index 7e9eab2ff2e..823a0d14a41 100644 --- a/src/sage/doctest/forker.py +++ b/src/sage/doctest/forker.py @@ -253,7 +253,7 @@ def showwarning_with_traceback(message, category, filename, lineno, file=None, l INPUT: see :func:`warnings.showwarning`. - OUTPUT: None + OUTPUT: none EXAMPLES:: @@ -307,10 +307,10 @@ class SageSpoofInOut(SageObject): INPUT: - ``outfile`` -- (default: ``tempfile.TemporaryFile()``) a seekable open file - object to which stdout and stderr should be redirected. + object to which stdout and stderr should be redirected - ``infile`` -- (default: ``open(os.devnull)``) an open file object - from which stdin should be redirected. + from which stdin should be redirected EXAMPLES:: @@ -470,7 +470,7 @@ def stop_spoofing(self): def getvalue(self): r""" - Gets the value that has been printed to ``outfile`` since the + Get the value that has been printed to ``outfile`` since the last time this function was called. EXAMPLES:: @@ -521,10 +521,10 @@ def __init__(self, *args, **kwds): :class:`doctest.OutputChecker` - ``verbose`` -- boolean, determines whether verbose printing - is enabled. + is enabled - - ``optionflags`` -- Controls the comparison with the expected - output. See :mod:`testmod` for more information. + - ``optionflags`` -- controls the comparison with the expected + output. See :mod:`testmod` for more information - ``baseline`` -- dictionary, the ``baseline_stats`` value @@ -845,7 +845,7 @@ def compiler(example): def run(self, test, compileflags=0, out=None, clear_globs=True): """ - Runs the examples in a given doctest. + Run the examples in a given doctest. This function replaces :class:`doctest.DocTestRunner.run` since it needs to handle spoofing. It also leaves the display @@ -855,14 +855,14 @@ def run(self, test, compileflags=0, out=None, clear_globs=True): - ``test`` -- an instance of :class:`doctest.DocTest` - - ``compileflags`` -- int (default: 0) the set of compiler flags used to - execute examples (passed in to the :func:`compile`). + - ``compileflags`` -- integer (default: 0) the set of compiler flags + used to execute examples (passed in to the :func:`compile`) - ``out`` -- a function for writing the output (defaults to - :func:`sys.stdout.write`). + :func:`sys.stdout.write`) - - ``clear_globs`` -- boolean (default: ``True``): whether to clear - the namespace after running this doctest. + - ``clear_globs`` -- boolean (default: ``True``); whether to clear + the namespace after running this doctest OUTPUT: @@ -1044,7 +1044,7 @@ def update_digests(self, example): def compile_and_execute(self, example, compiler, globs): """ - Runs the given example, recording dependencies. + Run the given example, recording dependencies. Rather than using a basic dictionary, Sage's doctest runner uses a :class:`sage.doctest.util.RecordingDict`, which records @@ -1063,16 +1063,14 @@ def compile_and_execute(self, example, compiler, globs): INPUT: - - ``example`` -- a :class:`doctest.Example` instance. + - ``example`` -- a :class:`doctest.Example` instance - ``compiler`` -- a callable that, applied to example, produces a code object - - ``globs`` -- a dictionary in which to execute the code. - - OUTPUT: + - ``globs`` -- dictionary in which to execute the code - - the output of the compiled code snippet. + OUTPUT: the output of the compiled code snippet EXAMPLES:: @@ -1188,11 +1186,9 @@ def _failure_header(self, test, example, message='Failed example:'): - ``test`` -- a :class:`doctest.DocTest` instance - - ``example`` -- a :class:`doctest.Example` instance in ``test``. - - OUTPUT: + - ``example`` -- a :class:`doctest.Example` instance in ``test`` - - a string used for reporting that the given example failed. + OUTPUT: string used for reporting that the given example failed EXAMPLES:: @@ -1301,9 +1297,7 @@ def report_start(self, out, test, example): - ``example`` -- a :class:`doctest.Example` instance in ``test`` - OUTPUT: - - - prints a report to ``out`` + OUTPUT: prints a report to ``out`` EXAMPLES:: @@ -1345,17 +1339,13 @@ def report_success(self, out, test, example, got, *, check_duration=0): - ``example`` -- a :class:`doctest.Example` instance in ``test`` - - ``got`` -- a string, the result of running ``example`` + - ``got`` -- string; the result of running ``example`` - - ``check_duration`` -- number (default: ``0``) time spent for checking + - ``check_duration`` -- number (default: ``0``); time spent for checking the test output - OUTPUT: - - - prints a report to ``out`` - - - if in debugging mode, starts an IPython prompt at the point - of the failure + OUTPUT: prints a report to ``out``; if in debugging mode, starts an + IPython prompt at the point of the failure EXAMPLES:: @@ -1390,13 +1380,11 @@ def report_failure(self, out, test, example, got, globs): - ``example`` -- a :class:`doctest.Example` instance in ``test`` - - ``got`` -- a string, the result of running ``example`` + - ``got`` -- string, the result of running ``example`` - - ``globs`` -- a dictionary of globals, used if in debugging mode + - ``globs`` -- dictionary of globals, used if in debugging mode - OUTPUT: - - - prints a report to ``out`` + OUTPUT: prints a report to ``out`` EXAMPLES:: @@ -1521,14 +1509,12 @@ def report_overtime(self, out, test, example, got, *, check_duration=0): - ``example`` -- a :class:`doctest.Example` instance in ``test`` - - ``got`` -- a string, the result of running ``example`` + - ``got`` -- string; the result of running ``example`` - - ``check_duration`` -- number (default: ``0``) time spent for checking + - ``check_duration`` -- number (default: ``0``); time spent for checking the test output - OUTPUT: - - - prints a report to ``out`` + OUTPUT: prints a report to ``out`` EXAMPLES:: @@ -1571,9 +1557,7 @@ def report_unexpected_exception(self, out, test, example, exc_info): - ``exc_info`` -- the result of ``sys.exc_info()`` - OUTPUT: - - - prints a report to ``out`` + OUTPUT: prints a report to ``out`` - if in debugging mode, starts PDB with the given traceback @@ -1653,11 +1637,10 @@ def update_results(self, D): INPUT: - - ``D`` -- a dictionary to update with cputime and walltime - - OUTPUT: + - ``D`` -- dictionary to update with cputime and walltime - - the number of failures (or False if there is no failure attribute) + OUTPUT: the number of failures (or ``False`` if there is no failure + attribute) EXAMPLES:: @@ -1715,7 +1698,7 @@ def dummy_handler(sig, frame): class DocTestDispatcher(SageObject): """ - Creates parallel :class:`DocTestWorker` processes and dispatches + Create parallel :class:`DocTestWorker` processes and dispatches doctesting tasks. """ def __init__(self, controller): @@ -1814,8 +1797,8 @@ def parallel_dispatch(self): canceled:: sage: from tempfile import NamedTemporaryFile as NTF - sage: with NTF(suffix=".py", mode="w+t") as f1, \ - ....: NTF(suffix=".py", mode="w+t") as f2: + sage: with NTF(suffix='.py', mode='w+t') as f1, \ + ....: NTF(suffix='.py', mode='w+t') as f2: ....: _ = f1.write("'''\nsage: import time; time.sleep(60)\n'''") ....: f1.flush() ....: _ = f2.write("'''\nsage: True\nFalse\n'''") @@ -1844,7 +1827,6 @@ def parallel_dispatch(self): 1 of 1 in ... [1 test, 1 failure, ... s] Killing test ... - """ opt = self.controller.options @@ -2168,10 +2150,10 @@ class should be accessed by the child process. - ``source`` -- a :class:`DocTestSource` instance - - ``options`` -- an object representing doctest options. + - ``options`` -- an object representing doctest options - - ``funclist`` -- a list of callables to be called at the start of - the child process. + - ``funclist`` -- list of callables to be called at the start of + the child process - ``baseline`` -- dictionary, the ``baseline_stats`` value @@ -2242,7 +2224,7 @@ def __init__(self, source, options, funclist=[], baseline=None): def run(self): """ - Runs the :class:`DocTestTask` under its own PGID. + Run the :class:`DocTestTask` under its own PGID. TESTS:: @@ -2498,9 +2480,9 @@ class DocTestTask(): INPUT: - - ``source`` -- a :class:`sage.doctest.sources.DocTestSource` instance. + - ``source`` -- a :class:`sage.doctest.sources.DocTestSource` instance - - ``verbose`` -- boolean, controls reporting of progress by :class:`doctest.DocTestRunner`. + - ``verbose`` -- boolean, controls reporting of progress by :class:`doctest.DocTestRunner` EXAMPLES:: @@ -2544,18 +2526,18 @@ def __call__(self, options, outtmpfile=None, msgfile=None, result_queue=None, *, INPUT: - - ``options`` -- an object representing doctest options. + - ``options`` -- an object representing doctest options - ``outtmpfile`` -- a seekable file that's used by the doctest - runner to redirect stdout and stderr of the doctests. + runner to redirect stdout and stderr of the doctests - ``msgfile`` -- a file or pipe to send doctest messages about - doctest failures (or all tests in verbose mode). + doctest failures (or all tests in verbose mode) - ``result_queue`` -- an instance of :class:`multiprocessing.Queue` - to store the doctest result. For testing, this can also be None. + to store the doctest result. For testing, this can also be ``None`` - - ``baseline`` -- a dictionary, the ``baseline_stats`` value. + - ``baseline`` -- dictionary, the ``baseline_stats`` value OUTPUT: diff --git a/src/sage/doctest/parsing.py b/src/sage/doctest/parsing.py index 2e4823c7370..92dd31384b3 100644 --- a/src/sage/doctest/parsing.py +++ b/src/sage/doctest/parsing.py @@ -144,9 +144,9 @@ def parse_optional_tags( INPUT: - - ``string`` -- a string + - ``string`` -- string - - ``return_string_sans_tags`` -- (boolean, default ``False``); whether to + - ``return_string_sans_tags`` -- boolean (default: ``False``); whether to additionally return ``string`` with the optional tags removed but other comments kept and a boolean ``is_persistent`` @@ -205,7 +205,6 @@ def parse_optional_tags( sage: parse_optional_tags("sage: #this is not #needs scipy\n....: import scipy", ....: return_string_sans_tags=True) ({'scipy': None}, 'sage: #this is not \n....: import scipy', False) - """ safe, literals, state = strip_string_literals(string) split = safe.split('\n', 1) @@ -277,16 +276,15 @@ def parse_file_optional_tags(lines): INPUT: - - ``lines`` -- iterable of pairs ``(lineno, line)``. - - OUTPUT: + - ``lines`` -- iterable of pairs ``(lineno, line)`` - a dictionary whose keys are strings (tags); see :func:`parse_optional_tags` + OUTPUT: dictionary whose keys are strings (tags); + see :func:`parse_optional_tags` EXAMPLES:: sage: from sage.doctest.parsing import parse_file_optional_tags - sage: filename = tmp_filename(ext=".pyx") + sage: filename = tmp_filename(ext='.pyx') sage: with open(filename, "r") as f: ....: parse_file_optional_tags(enumerate(f)) {} @@ -338,9 +336,7 @@ def _tag_group(tag): - ``tag`` -- string - OUTPUT: - - a string; one of ``'special'``, ``'optional'``, ``'standard'``, ``'sage'`` + OUTPUT: string; one of ``'special'``, ``'optional'``, ``'standard'``, ``'sage'`` EXAMPLES:: @@ -370,7 +366,8 @@ def unparse_optional_tags(tags, prefix='# '): INPUT: - - ``tags`` -- dict or iterable of tags, as output by :func:`parse_optional_tags` + - ``tags`` -- dictionary or iterable of tags, as output by + :func:`parse_optional_tags` - ``prefix`` -- to be put before a nonempty string @@ -585,13 +582,11 @@ def parse_tolerance(source, want): INPUT: - - ``source`` -- a string, the source of a doctest - - ``want`` -- a string, the desired output of the doctest - - OUTPUT: + - ``source`` -- string, the source of a doctest + - ``want`` -- string, the desired output of the doctest - ``want`` if there are no tolerance tags specified; a - :class:`MarkedOutput` version otherwise. + OUTPUT: ``want`` if there are no tolerance tags specified; a + :class:`MarkedOutput` version otherwise EXAMPLES:: @@ -873,11 +868,11 @@ def __init__(self, optional_tags=(), long=False, *, probed_tags=(), file_optiona r""" INPUT: - - ``optional_tags`` -- a list or tuple of strings. + - ``optional_tags`` -- list or tuple of strings - ``long`` -- boolean, whether to run doctests marked as taking a - long time. - - ``probed_tags`` -- a list or tuple of strings. - - ``file_optional_tags`` -- an iterable of strings. + long time + - ``probed_tags`` -- list or tuple of strings + - ``file_optional_tags`` -- an iterable of strings EXAMPLES:: @@ -948,9 +943,9 @@ def parse(self, string, *args): INPUT: - - ``string`` -- the string to parse. - - ``name`` -- optional string giving the name identifying string, - to be used in error messages. + - ``string`` -- the string to parse + - ``name`` -- (optional) string giving the name identifying string, + to be used in error messages OUTPUT: @@ -1378,9 +1373,7 @@ def add_tolerance(self, wantval, want): - ``wantval`` -- a real interval element - ``want`` -- a :class:`MarkedOutput` describing the tolerance - OUTPUT: - - - an interval element containing ``wantval`` + OUTPUT: an interval element containing ``wantval`` EXAMPLES:: @@ -1422,19 +1415,18 @@ def add_tolerance(self, wantval, want): def check_output(self, want, got, optionflags): r""" - Checks to see if the output matches the desired output. + Check to see if the output matches the desired output. If ``want`` is a :class:`MarkedOutput` instance, takes into account the desired tolerance. INPUT: - - ``want`` -- a string or :class:`MarkedOutput` - - ``got`` -- a string - - ``optionflags`` -- an integer, passed down to :class:`doctest.OutputChecker` + - ``want`` -- string or :class:`MarkedOutput` + - ``got`` -- string + - ``optionflags`` -- integer; passed down to :class:`doctest.OutputChecker` - OUTPUT: - - - boolean, whether ``got`` matches ``want`` up to the specified tolerance. + OUTPUT: boolean; whether ``got`` matches ``want`` up to the specified + tolerance EXAMPLES:: @@ -1588,20 +1580,18 @@ def check_output(self, want, got, optionflags): def do_fixup(self, want, got): r""" - Performs few changes to the strings ``want`` and ``got``. + Perform few changes to the strings ``want`` and ``got``. For example, remove warnings to be ignored. INPUT: - - ``want`` -- a string or :class:`MarkedOutput` - - ``got`` -- a string - - OUTPUT: + - ``want`` -- string or :class:`MarkedOutput` + - ``got`` -- string - A tuple: + OUTPUT: a tuple: - - bool, ``True`` when some fixup were performed and ``False`` otherwise + - boolean, ``True`` when some fixup were performed and ``False`` otherwise - string, edited wanted string - string, edited got string @@ -1641,7 +1631,6 @@ def do_fixup(self, want, got): (False, '1.3090169943749475\n', 'ANYTHING1.3090169943749475') sage: OC.do_fixup(ex.want,'Long-step dual simplex will be used\n1.3090169943749475') (True, '1.3090169943749475\n', '\n1.3090169943749475') - """ did_fixup = False @@ -1717,12 +1706,10 @@ def output_difference(self, example, got, optionflags): INPUT: - ``example`` -- a :class:`doctest.Example` instance - - ``got`` -- a string - - ``optionflags`` -- an integer, passed down to :class:`doctest.OutputChecker` - - OUTPUT: + - ``got`` -- string + - ``optionflags`` -- integer; passed down to :class:`doctest.OutputChecker` - - a string, describing how ``got`` fails to match ``example.want`` + OUTPUT: string, describing how ``got`` fails to match ``example.want`` EXAMPLES:: diff --git a/src/sage/doctest/reporting.py b/src/sage/doctest/reporting.py index e4f5c305b45..d72fd18023b 100644 --- a/src/sage/doctest/reporting.py +++ b/src/sage/doctest/reporting.py @@ -10,7 +10,7 @@ - 1: Doctest failure - 2: Bad command line syntax or invalid options - 4: Test timed out -- 8: Test exited with non-zero status +- 8: Test exited with nonzero status - 16: Test crashed with a signal (e.g. segmentation fault) - 32: TAB character found - 64: Internal error in the doctesting framework @@ -102,9 +102,9 @@ def __init__(self, controller): INPUT: - ``controller`` -- a - :class:`sage.doctest.control.DocTestController` instance. + :class:`sage.doctest.control.DocTestController` instance; Note that some methods assume that appropriate tests have - been run by the controller. + been run by the controller EXAMPLES:: @@ -152,7 +152,6 @@ def were_doctests_with_optional_tag_run(self, tag): sage: DTR = DocTestReporter(DC) sage: DTR.were_doctests_with_optional_tag_run('latex') # optional - latex True - """ if self.controller.options.optional is True or tag in self.controller.options.optional: return True @@ -227,11 +226,11 @@ def _log_failure(self, source, fail_msg, event, output=None): - ``source`` -- a source from :mod:`sage.doctest.sources` - - ``fail_msg`` -- a string + - ``fail_msg`` -- string - - ``event`` -- a string + - ``event`` -- string - - ``output`` -- optional string + - ``output`` -- (optional) string EXAMPLES:: @@ -293,25 +292,22 @@ def report(self, source, timeout, return_code, results, output, pid=None): - ``source`` -- a source from :mod:`sage.doctest.sources` - - ``timeout`` -- a boolean, whether doctests timed out + - ``timeout`` -- boolean; whether doctests timed out - - ``return_code`` -- an int, the return code of the process - running doctests on that file. + - ``return_code`` -- integer; the return code of the process + running doctests on that file - - ``results`` -- (irrelevant if ``timeout`` or - ``return_code``), a tuple + - ``results`` -- (irrelevant if ``timeout`` or ``return_code``) a tuple - ``ntests`` -- the number of doctests - ``timings`` -- a :class:`sage.doctest.sources.DictAsObject` instance - storing timing data. + storing timing data - - ``output`` -- a string, printed if there was some kind of - failure + - ``output`` -- string; printed if there was some kind of failure - - ``pid`` -- optional integer (default: ``None``). The pid of - the worker process. + - ``pid`` -- integer (default: ``None``); the pid of the worker process EXAMPLES:: diff --git a/src/sage/doctest/sources.py b/src/sage/doctest/sources.py index c1539088015..68d95d1cf26 100644 --- a/src/sage/doctest/sources.py +++ b/src/sage/doctest/sources.py @@ -78,7 +78,8 @@ def get_basename(path): """ - This function returns the basename of the given path, e.g. sage.doctest.sources or doc.ru.tutorial.tour_advanced + This function returns the basename of the given path, e.g. + ``sage.doctest.sources`` or ``doc.ru.tutorial.tour_advanced``. EXAMPLES:: @@ -130,7 +131,7 @@ class DocTestSource(): INPUT: - ``options`` -- a :class:`sage.doctest.control.DocTestDefaults` - instance or equivalent. + instance or equivalent """ def __init__(self, options): """ @@ -194,17 +195,17 @@ def _process_doc(self, doctests, doc, namespace, start): INPUT: - ``doctests`` -- a running list of doctests to which the new - test(s) will be appended. + test(s) will be appended - - ``doc`` -- a list of lines of a docstring, each including - the trailing newline. + - ``doc`` -- list of lines of a docstring, each including + the trailing newline - - ``namespace`` -- a dictionary or + - ``namespace`` -- dictionary or :class:`sage.doctest.util.RecordingDict`, used in the - creation of new :class:`doctest.DocTest` s. + creation of new :class:`doctest.DocTest` s - - ``start`` -- an integer, giving the line number of the start - of this docstring in the larger file. + - ``start`` -- integer giving the line number of the start + of this docstring in the larger file EXAMPLES:: @@ -257,7 +258,7 @@ def file_optional_tags(self): def _create_doctests(self, namespace, tab_okay=None): """ - Creates a list of doctests defined in this source. + Create a list of doctests defined in this source. This function collects functionality common to file and string sources, and is called by @@ -265,18 +266,18 @@ def _create_doctests(self, namespace, tab_okay=None): INPUT: - - ``namespace`` -- a dictionary or + - ``namespace`` -- dictionary or :class:`sage.doctest.util.RecordingDict`, used in the creation of new :class:`doctest.DocTest` s. - - ``tab_okay`` -- whether tabs are allowed in this source. + - ``tab_okay`` -- whether tabs are allowed in this source OUTPUT: - - ``doctests`` -- a list of doctests defined by this source + - ``doctests`` -- list of doctests defined by this source - - ``extras`` -- a dictionary with ``extras['tab']`` either - False or a list of linenumbers on which tabs appear. + - ``extras`` -- dictionary with ``extras['tab']`` either + ``False`` or a list of linenumbers on which tabs appear EXAMPLES:: @@ -385,19 +386,19 @@ class StringDocTestSource(DocTestSource): INPUT: - ``basename`` -- string such as 'sage.doctests.sources', going - into the names of created doctests and examples. + into the names of created doctests and examples - - ``source`` -- a string, giving the source code to be parsed for - doctests. + - ``source`` -- string, giving the source code to be parsed for + doctests - ``options`` -- a :class:`sage.doctest.control.DocTestDefaults` - or equivalent. + or equivalent - - ``printpath`` -- a string, to be used in place of a filename - when doctest failures are displayed. + - ``printpath`` -- string, to be used in place of a filename + when doctest failures are displayed - - ``lineno_shift`` -- an integer (default: 0) by which to shift - the line numbers of all doctests defined in this string. + - ``lineno_shift`` -- integer (default: 0) by which to shift + the line numbers of all doctests defined in this string EXAMPLES:: @@ -429,7 +430,7 @@ class StringDocTestSource(DocTestSource): """ def __init__(self, basename, source, options, printpath, lineno_shift=0): r""" - Initialization + Initialization. TESTS:: @@ -471,18 +472,18 @@ def __iter__(self): def create_doctests(self, namespace): r""" - Creates doctests from this string. + Create doctests from this string. INPUT: - - ``namespace`` -- a dictionary or :class:`sage.doctest.util.RecordingDict`. + - ``namespace`` -- dictionary or :class:`sage.doctest.util.RecordingDict` OUTPUT: - - ``doctests`` -- a list of doctests defined by this string + - ``doctests`` -- list of doctests defined by this string - - ``tab_locations`` -- either False or a list of linenumbers - on which tabs appear. + - ``tab_locations`` -- either ``False`` or a list of linenumbers + on which tabs appear EXAMPLES:: @@ -506,10 +507,10 @@ class FileDocTestSource(DocTestSource): INPUT: - - ``path`` -- string, the filename + - ``path`` -- string; the filename - ``options`` -- a :class:`sage.doctest.control.DocTestDefaults` - instance or equivalent. + instance or equivalent EXAMPLES:: @@ -528,13 +529,12 @@ class FileDocTestSource(DocTestSource): sage: from sage.doctest.control import DocTestDefaults sage: from sage.doctest.sources import FileDocTestSource - sage: filename = tmp_filename(ext=".txtt") + sage: filename = tmp_filename(ext='.txtt') sage: FDS = FileDocTestSource(filename, DocTestDefaults()) Traceback (most recent call last): ... ValueError: unknown extension for the file to test (=...txtt), valid extensions are: .py, .pyx, .pxd, .pxi, .sage, .spyx, .tex, .rst, .rst.txt - """ def __init__(self, path, options): """ @@ -578,7 +578,7 @@ def __iter__(self): sage: from sage.doctest.control import DocTestDefaults sage: from sage.doctest.sources import FileDocTestSource - sage: filename = tmp_filename(ext=".py") + sage: filename = tmp_filename(ext='.py') sage: s = "'''\n sage: 2 + 2\n 4\n'''" sage: with open(filename, 'w') as f: ....: _ = f.write(s) @@ -660,7 +660,7 @@ def printpath(self): @lazy_attribute def basename(self): """ - The basename of this file source, e.g. sage.doctest.sources + The basename of this file source, e.g. ``sage.doctest.sources``. EXAMPLES:: @@ -732,13 +732,13 @@ def create_doctests(self, namespace): INPUT: - - ``namespace`` -- a dictionary or :class:`sage.doctest.util.RecordingDict`. + - ``namespace`` -- dictionary or :class:`sage.doctest.util.RecordingDict` OUTPUT: - - ``doctests`` -- a list of doctests defined in this file. + - ``doctests`` -- list of doctests defined in this file - - ``extras`` -- a dictionary + - ``extras`` -- dictionary EXAMPLES:: @@ -805,11 +805,11 @@ def _test_enough_doctests(self, check_extras=True, verbose=True): INPUT: - - ``check_extras`` -- bool (default ``True``), whether to check if + - ``check_extras`` -- boolean (default: ``True``); whether to check if doctests are created that do not correspond to either a ``sage:`` or a ``>>>`` prompt - - ``verbose`` -- bool (default ``True``), whether to print + - ``verbose`` -- boolean (default: ``True``); whether to print offending line numbers when there are missing or extra tests TESTS:: @@ -911,11 +911,11 @@ def parse_docstring(self, docstring, namespace, start): INPUT: - - ``docstring`` -- a string containing documentation and tests. + - ``docstring`` -- string containing documentation and tests - - ``namespace`` -- a dictionary or :class:`sage.doctest.util.RecordingDict`. + - ``namespace`` -- dictionary or :class:`sage.doctest.util.RecordingDict` - - ``start`` -- an integer, one less than the starting line number + - ``start`` -- integer; one less than the starting line number EXAMPLES:: @@ -975,7 +975,7 @@ def _init(self): def _update_quotetype(self, line): r""" - Updates the track of what kind of quoted string we're in. + Update the track of what kind of quoted string we are in. We need to track whether we're inside a triple quoted string, since a triple quoted string that starts a line @@ -1078,11 +1078,9 @@ def starting_docstring(self, line): INPUT: - - ``line`` -- a string, one line of an input file - - OUTPUT: + - ``line`` -- string; one line of an input file - - either None or a Match object. + OUTPUT: either ``None`` or a Match object EXAMPLES:: @@ -1151,13 +1149,11 @@ def ending_docstring(self, line): INPUT: - - ``line`` -- a string, one line of an input file. - - OUTPUT: + - ``line`` -- string, one line of an input file - - an object that, when evaluated in a boolean context, gives - ``True`` or ``False`` depending on whether the input line marks the - end of a docstring. + OUTPUT: an object that, when evaluated in a boolean context, gives + ``True`` or ``False`` depending on whether the input line marks the + end of a docstring EXAMPLES:: @@ -1189,8 +1185,8 @@ def _neutralize_doctests(self, reindent): INPUT: - - ``reindent`` -- an integer, the number of spaces to indent - the result. + - ``reindent`` -- integer; the number of spaces to indent + the result EXAMPLES:: @@ -1270,12 +1266,10 @@ def starting_docstring(self, line): INPUT: - - ``line`` -- a string, one line of an input file + - ``line`` -- string, one line of an input file - OUTPUT: - - - a boolean giving whether the input line marks the - start of a docstring (verbatim block). + OUTPUT: boolean; whether the input line marks the start of a docstring + (verbatim block) EXAMPLES:: @@ -1347,14 +1341,13 @@ def ending_docstring(self, line, check_skip=True): INPUT: - - ``line`` -- a string, one line of an input file - - - ``check_skip`` -- boolean (default: ``True``), used internally in starting_docstring. + - ``line`` -- string, one line of an input file - OUTPUT: + - ``check_skip`` -- boolean (default: ``True``); used internally in + ``starting_docstring`` - - a boolean giving whether the input line marks the - end of a docstring (verbatim block). + OUTPUT: boolean; whether the input line marks the end of a docstring + (verbatim block) EXAMPLES:: @@ -1449,11 +1442,9 @@ def starting_docstring(self, line): INPUT: - - ``line`` -- a string, one line of an input file + - ``line`` -- string; one line of an input file - OUTPUT: - - - either None or a Match object. + OUTPUT: either ``None`` or a Match object EXAMPLES:: @@ -1507,11 +1498,9 @@ def ending_docstring(self, line): INPUT: - - ``line`` -- a string, one line of an input file - - OUTPUT: + - ``line`` -- string; one line of an input file - - a boolean, whether the verbatim block is ending. + OUTPUT: boolean; whether the verbatim block is ending EXAMPLES:: @@ -1618,7 +1607,7 @@ def __init__(self, attrs): INPUT: - - ``attrs`` -- a dictionary. + - ``attrs`` -- dictionary EXAMPLES:: diff --git a/src/sage/doctest/test.py b/src/sage/doctest/test.py index 4907d30d58d..2819b782a66 100644 --- a/src/sage/doctest/test.py +++ b/src/sage/doctest/test.py @@ -266,7 +266,7 @@ If the child process is dead and removed, the last output should be as above. However, the child process interrupted its parent process (see -``"interrupt_diehard.rst"``), and became an orphan process. Depending on the +``'interrupt_diehard.rst'``), and became an orphan process. Depending on the system, an orphan process may eventually become a zombie process instead of being removed, and then the last output would just be a blank. Hence the ``# random`` tag. diff --git a/src/sage/doctest/tests/fail_and_die.rst b/src/sage/doctest/tests/fail_and_die.rst index 90d7d3428e6..65e652f4f5e 100644 --- a/src/sage/doctest/tests/fail_and_die.rst +++ b/src/sage/doctest/tests/fail_and_die.rst @@ -1,4 +1,4 @@ -The ``NameError`` raised on the second line should be displayed, even +The :exc:`NameError` raised on the second line should be displayed, even if we crash immediately afterwards:: sage: import time, signal diff --git a/src/sage/doctest/tests/initial.rst b/src/sage/doctest/tests/initial.rst index 595cf2b54fa..f6eec87bec5 100644 --- a/src/sage/doctest/tests/initial.rst +++ b/src/sage/doctest/tests/initial.rst @@ -1,4 +1,4 @@ -One initial typo causes a ``NameError`` in the first test and many +One initial typo causes a :exc:`NameError` in the first test and many following failures:: sage: a = binomiak(10,5) # random to test that we still get the exception diff --git a/src/sage/doctest/util.py b/src/sage/doctest/util.py index 3fe9d3408bd..6bffb67156b 100644 --- a/src/sage/doctest/util.py +++ b/src/sage/doctest/util.py @@ -41,7 +41,7 @@ def count_noun(number, noun, plural=None, pad_number=False, pad_noun=False): '2 oranges' sage: count_noun(3, "peach", "peaches") '3 peaches' - sage: count_noun(1, "peach", plural="peaches", pad_noun=True) + sage: count_noun(1, "peach", plural='peaches', pad_noun=True) '1 peach ' """ if plural is None: @@ -78,7 +78,7 @@ def dict_difference(self, other): sage: from sage.doctest.control import DocTestDefaults sage: D1 = DocTestDefaults() - sage: D2 = DocTestDefaults(foobar="hello", timeout=100) + sage: D2 = DocTestDefaults(foobar='hello', timeout=100) sage: dict_difference(D2.__dict__, D1.__dict__) {'foobar': 'hello', 'timeout': 100} """ @@ -198,7 +198,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Test for non-equality + Test for non-equality. EXAMPLES:: @@ -423,7 +423,7 @@ def __init__(self, base): """ INPUT: - - base -- a string: the name of the module. + - ``base`` -- string; the name of the module EXAMPLES:: @@ -436,12 +436,14 @@ def __init__(self, base): def __setitem__(self, index, value): """ - Sets the value at a given indentation level. + Set the value at a given indentation level. INPUT: - - index -- a positive integer, the indentation level (often a multiple of 4, but not necessarily) - - value -- a string, the name of the class or function at that indentation level. + - ``index`` -- positive integer; the indentation level (often a + multiple of 4, but not necessarily) + - ``value`` -- string; the name of the class or function at that + indentation level EXAMPLES:: diff --git a/src/sage/dynamics/arithmetic_dynamics/affine_ds.py b/src/sage/dynamics/arithmetic_dynamics/affine_ds.py index 2b9dd28b13b..c2ad0f04cea 100644 --- a/src/sage/dynamics/arithmetic_dynamics/affine_ds.py +++ b/src/sage/dynamics/arithmetic_dynamics/affine_ds.py @@ -46,7 +46,7 @@ class initialization directly. from sage.rings.finite_rings.finite_field_base import FiniteField from sage.rings.fraction_field import FractionField from sage.rings.fraction_field import FractionField_generic -from sage.rings.quotient_ring import is_QuotientRing +from sage.rings.quotient_ring import QuotientRing_nc from sage.schemes.affine.affine_morphism import SchemeMorphism_polynomial_affine_space from sage.schemes.affine.affine_morphism import SchemeMorphism_polynomial_affine_space_field from sage.schemes.affine.affine_morphism import SchemeMorphism_polynomial_affine_space_finite_field @@ -78,7 +78,7 @@ class DynamicalSystem_affine(SchemeMorphism_polynomial_affine_space, rational function, or a list or tuple of polynomials or rational functions - - ``domain`` -- optional affine space or subscheme of such; + - ``domain`` -- (optional) affine space or subscheme of such; the following combinations of ``morphism_or_polys`` and ``domain`` are meaningful: @@ -268,7 +268,7 @@ def __classcall_private__(cls, morphism_or_polys, domain=None): PR = PR.ring().change_ring(K).fraction_field() polys = [PR(poly) for poly in polys] else: - quotient_ring = any(is_QuotientRing(poly.parent()) for poly in polys) + quotient_ring = any(isinstance(poly.parent(), QuotientRing_nc) for poly in polys) # If any of the list entries lies in a quotient ring, we try # to lift all entries to a common polynomial ring. if quotient_ring: @@ -353,7 +353,7 @@ def homogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers. If ``n`` is an integer, + - ``n`` -- tuple of nonnegative integers; if `n` is an integer, then the two values of the tuple are assumed to be the same OUTPUT: :class:`DynamicalSystem_projective` @@ -434,7 +434,7 @@ def dynatomic_polynomial(self, period): INPUT: - - ``period`` -- a positive integer or a list/tuple `[m,n]`, + - ``period`` -- positive integer or a list/tuple `[m,n]`, where `m` is the preperiod and `n` is the period OUTPUT: @@ -547,7 +547,7 @@ def dynatomic_polynomial(self, period): def nth_iterate_map(self, n): r""" - Return the ``n``-th iterate of ``self``. + Return the `n`-th iterate of ``self``. ALGORITHM: @@ -559,7 +559,7 @@ def nth_iterate_map(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: a dynamical system of affine space @@ -618,13 +618,13 @@ def nth_iterate_map(self, n): def nth_iterate(self, P, n): r""" - Return the ``n``-th iterate of the point ``P`` by this dynamical system. + Return the `n`-th iterate of the point `P` by this dynamical system. INPUT: - ``P`` -- a point in the map's domain - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: a point in the map's codomain @@ -672,7 +672,7 @@ def nth_iterate(self, P, n): def orbit(self, P, n): r""" - Return the orbit of ``P`` by the dynamical system. + Return the orbit of `P` by the dynamical system. Let `F` be this dynamical system. If `n` is an integer return `[P, F(P), \ldots, F^n(P)]`. If `n` is a list or @@ -682,10 +682,10 @@ def orbit(self, P, n): - ``P`` -- a point in the map's domain - - ``n`` -- a non-negative integer or list or tuple of - two non-negative integers + - ``n`` -- nonnegative integer or list or tuple of + two nonnegative integers - OUTPUT: a list of points in the map's codomain + OUTPUT: list of points in the map's codomain EXAMPLES:: @@ -735,22 +735,20 @@ def orbit(self, P, n): def multiplier(self, P, n, check=True): r""" - Return the multiplier of the point ``P`` of period ``n`` by this + Return the multiplier of the point `P` of period `n` by this dynamical system. INPUT: - ``P`` -- a point on domain of the map - - ``n`` -- a positive integer, the period of ``P`` + - ``n`` -- positive integer, the period of `P` - - ``check`` -- (default: ``True``) boolean, verify that ``P`` - has period ``n`` + - ``check`` -- boolean (default: ``True``); verify that `P` + has period `n` - OUTPUT: - - A square matrix of size ``self.codomain().dimension_relative()`` in - the ``base_ring`` of the map. + OUTPUT: a square matrix of size ``self.codomain().dimension_relative()`` + in the ``base_ring`` of the map EXAMPLES:: @@ -819,9 +817,7 @@ def conjugate(self, M): - ``M`` -- a square invertible matrix - OUTPUT: - - An affine dynamical system + OUTPUT: an affine dynamical system EXAMPLES:: @@ -853,7 +849,6 @@ def conjugate(self, M): Dynamical System of Affine Space of dimension 1 over Integer Ring Defn: Defined on coordinates by sending (x) to (x^3 + x^2 - x - 5) - """ d = self.codomain().ngens() f = self.homogenize(d).conjugate(M) @@ -951,7 +946,7 @@ def reduce_base_field(self): the base ring is a number field, ``QQbar``, a finite field, or algebraic closure of a finite field. - OUTPUT: A dynamical system + OUTPUT: a dynamical system EXAMPLES:: @@ -998,13 +993,13 @@ def orbit_structure(self, P): Every point is preperiodic over a finite field. This function returns the pair `[m,n]` where `m` is the - preperiod and `n` is the period of the point ``P`` by this map. + preperiod and `n` is the period of the point `P` by this map. INPUT: - ``P`` -- a point in the map's domain - OUTPUT: a list `[m, n]` of integers + OUTPUT: list `[m, n]` of integers EXAMPLES:: diff --git a/src/sage/dynamics/arithmetic_dynamics/berkovich_ds.py b/src/sage/dynamics/arithmetic_dynamics/berkovich_ds.py index be1ef46b251..6995f61f463 100644 --- a/src/sage/dynamics/arithmetic_dynamics/berkovich_ds.py +++ b/src/sage/dynamics/arithmetic_dynamics/berkovich_ds.py @@ -55,9 +55,9 @@ class DynamicalSystem_Berkovich(Element, metaclass=InheritComparisonClasscallMet INPUT: - - ``dynamical_system`` -- A :class:`DynamicalSystem` + - ``dynamical_system`` -- a :class:`DynamicalSystem` over affine or projective space. If this input is not defined - over a p-adic field, then ``domain`` MUST be specified. + over a `p`-adic field, then ``domain`` MUST be specified. - ``domain`` -- (optional) affine or projective Berkovich space over `\CC_p`. ``domain`` must be specified if ``dynamical_system`` @@ -345,7 +345,7 @@ def domain(self): """ Return the domain of this dynamical system. - OUTPUT: A Berkovich space over ``Cp``. + OUTPUT: a Berkovich space over ``Cp`` EXAMPLES:: @@ -361,7 +361,7 @@ def as_scheme_dynamical_system(self): r""" Return this dynamical system as :class:`DynamicalSystem`. - OUTPUT: An affine or projective :class:`DynamicalSystem`. + OUTPUT: an affine or projective :class:`DynamicalSystem` EXAMPLES:: @@ -376,13 +376,13 @@ def as_scheme_dynamical_system(self): def __getitem__(self, i): """ - Return the ith polynomial. + Return the `i`-th polynomial. INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - OUTPUT: An element of polynomial ring or a + OUTPUT: an element of polynomial ring or a fraction field of a polynomial ring EXAMPLES:: @@ -399,7 +399,7 @@ def defining_polynomials(self): """ Return the defining polynomials. - OUTPUT: A tuple of polynomials that defines the + OUTPUT: a tuple of polynomials that defines the dynamical system. EXAMPLES:: @@ -417,7 +417,7 @@ def base_ring(self): """ The base ring of this dynamical system, that is, the field of definition of the coefficients. - OUTPUT: A field. + OUTPUT: a field EXAMPLES:: @@ -442,7 +442,7 @@ def _repr_(self): r""" Return a string representation of this dynamical system. - OUTPUT: a string. + OUTPUT: string EXAMPLES:: @@ -471,11 +471,11 @@ class DynamicalSystem_Berkovich_projective(DynamicalSystem_Berkovich): - ``dynamical_system`` -- a :class:`DynamicalSystem_Projective` of relative dimension 1. If this input is not defined - over a p-adic field, then ``domain`` MUST be specified. + over a `p`-adic field, then ``domain`` MUST be specified. - ``domain`` -- (optional) projective Berkovich space over `\CC_p`. If the input to ``dynamical_system`` is - not defined over a p-adic field, ``domain`` + not defined over a `p`-adic field, ``domain`` must be specified. EXAMPLES: @@ -566,13 +566,13 @@ def __init__(self, dynamical_system, domain=None): def scale_by(self, t): """ - Scales each coordinate of this dynamical system by a factor of ``t``. + Scale each coordinate of this dynamical system by a factor of `t`. INPUT: - - ``t`` -- a ring element. + - ``t`` -- a ring element - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -602,9 +602,9 @@ def scale_by(self, t): def normalize_coordinates(self): r""" - Normalizes the coordinates of the inducing map. + Normalize the coordinates of the inducing map. - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -616,7 +616,7 @@ def normalize_coordinates(self): Defn: Defined on coordinates by sending (x : y) to (x^2 : y^2) - Normalize_coordinates may sometimes fail over p-adic fields:: + Normalize_coordinates may sometimes fail over `p`-adic fields:: sage: g = DynamicalSystem_Berkovich([2*x^2, x*y]) sage: g.normalize_coordinates() # not tested @@ -646,9 +646,9 @@ def conjugate(self, M, adjugate=False, new_ideal=None): INPUT: - - ``M`` -- a square invertible matrix. + - ``M`` -- a square invertible matrix - - ``adjugate`` -- (default: ``False``) boolean, also classically + - ``adjugate`` -- boolean (default: ``False``); also classically called adjoint, takes a square matrix ``M`` and finds the transpose of its cofactor matrix. Used for conjugation in place of inverse when specified ``'True'``. Functionality is the same in projective space. @@ -657,7 +657,7 @@ def conjugate(self, M, adjugate=False, new_ideal=None): Used to specify an extension in the case where ``M`` is not defined over the same number field as this dynamical system. - OUTPUT: a dynamical system. + OUTPUT: a dynamical system EXAMPLES:: @@ -711,7 +711,7 @@ def conjugate(self, M, adjugate=False, new_ideal=None): def resultant(self, normalize=False): r""" - Computes the resultant of the defining polynomials of + Compute the resultant of the defining polynomials of this dynamical system. If ``normalize`` is ``True``, then first normalize the coordinate @@ -719,9 +719,9 @@ def resultant(self, normalize=False): INPUT: - - ``normalize`` -- (default: ``False``) boolean. + - ``normalize`` -- boolean (default: ``False``) - OUTPUT: an element of the base ring of this map. + OUTPUT: an element of the base ring of this map EXAMPLES:: @@ -751,10 +751,10 @@ def dehomogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers; if ``n`` is an integer, - then the two values of the tuple are assumed to be the same. + - ``n`` -- tuple of nonnegative integers; if `n` is an integer, + then the two values of the tuple are assumed to be the same - OUTPUT: A dynamical system on affine Berkovich space. + OUTPUT: a dynamical system on affine Berkovich space EXAMPLES:: @@ -779,15 +779,15 @@ def __call__(self, x, type_3_pole_check=True): INPUT: - - ``x`` -- a point of projective Berkovich space over ``Cp``. + - ``x`` -- a point of projective Berkovich space over ``Cp`` - - ``type_3_pole_check`` -- (default ``True``) A bool. WARNING: + - ``type_3_pole_check`` -- boolean (default: ``True``); WARNING: changing the value of ``type_3_pole_check`` can lead to mathematically incorrect answers. Only set to ``False`` if there are NO poles of the dynamical system in the disk corresponding to the type III point ``x``. See Examples. - OUTPUT: A point of projective Berkovich space over ``Cp``. + OUTPUT: a point of projective Berkovich space over ``Cp`` EXAMPLES:: @@ -966,8 +966,8 @@ class DynamicalSystem_Berkovich_affine(DynamicalSystem_Berkovich): INPUT: - - ``dynamical_system`` -- A :class:`DynamicalSystem_affine` - of relative dimension 1. + - ``dynamical_system`` -- a :class:`DynamicalSystem_affine` + of relative dimension 1 - ``domain`` -- (optional) affine or projective Berkovich space over `\CC_p`. If the input to ``dynamical_system`` is @@ -1054,7 +1054,7 @@ def homogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers. If ``n`` is an integer, + - ``n`` -- tuple of nonnegative integers. If `n` is an integer, then the two values of the tuple are assumed to be the same OUTPUT: a dynamical system on projective Berkovich space diff --git a/src/sage/dynamics/arithmetic_dynamics/dynamical_semigroup.py b/src/sage/dynamics/arithmetic_dynamics/dynamical_semigroup.py index 93c402d4695..43ca8843fe8 100644 --- a/src/sage/dynamics/arithmetic_dynamics/dynamical_semigroup.py +++ b/src/sage/dynamics/arithmetic_dynamics/dynamical_semigroup.py @@ -386,9 +386,10 @@ def __call__(self, input): INPUT: - ``input`` -- one value that can be evaluated - with the generators of this dynamical semigroup. + with the generators of this dynamical semigroup - OUTPUT: A set of the resulting values after applying all of this dynamical semigroup's generators to ``input``. + OUTPUT: a set of the resulting values after applying all of this + dynamical semigroup's generators to ``input`` EXAMPLES:: @@ -423,7 +424,7 @@ def base_ring(self): The base ring of this dynamical semigroup. This is identical to the base ring of all of its defining dynamical system. - OUTPUT: A ring. + OUTPUT: a ring EXAMPLES:: @@ -441,7 +442,7 @@ def change_ring(self, new_ring): INPUT: - - ``new_ring`` -- a ring. + - ``new_ring`` -- a ring OUTPUT: @@ -471,7 +472,7 @@ def domain(self): r""" Return the domain of the generators of this dynamical semigroup. - OUTPUT: A subscheme of a projective space or affine space. + OUTPUT: a subscheme of a projective space or affine space EXAMPLES:: @@ -486,7 +487,7 @@ def codomain(self): r""" Return the codomain of the generators of this dynamical semigroup. - OUTPUT: A subscheme of a projective space or affine space. + OUTPUT: a subscheme of a projective space or affine space EXAMPLES:: @@ -501,7 +502,7 @@ def defining_polynomials(self): r""" Return the set of polynomials that define the generators of this dynamical semigroup. - OUTPUT: A set of polynomials. + OUTPUT: a set of polynomials EXAMPLES:: @@ -519,7 +520,7 @@ def defining_systems(self): r""" Return the generators of this dynamical semigroup. - OUTPUT: A tuple of dynamical systems. + OUTPUT: a tuple of dynamical systems EXAMPLES:: @@ -541,7 +542,7 @@ def nth_iterate(self, p, n): INPUT: - ``p`` -- a value on which dynamical systems can evaluate - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: a set of values @@ -619,7 +620,6 @@ def nth_iterate(self, p, n): sage: one = QQ(1) sage: f.nth_iterate(2, one) {(3 : 1), (4 : 1)} - """ n = ZZ(n) if n < 0: @@ -639,11 +639,11 @@ def orbit(self, p, n): INPUT: - - `p` -- value on which this dynamical semigroup can be evaluated - - `n` -- a nonnegative integer or a list or tuple of length 2 describing an + - ``p`` -- value on which this dynamical semigroup can be evaluated + - ``n`` -- nonnegative integer or a list or tuple of length 2 describing an interval of the number line containing entirely nonnegative integers - OUTPUT: a tuple of sets of values on the domain of this dynamical semigroup. + OUTPUT: a tuple of sets of values on the domain of this dynamical semigroup EXAMPLES:: @@ -753,13 +753,15 @@ def orbit(self, p, n): def specialization(self, assignments): r""" - Returns the specialization of the generators of this dynamical semigroup. + Return the specialization of the generators of this dynamical semigroup. INPUT: - - `assignments` -- argument for specialization of the generators of this dynamical semigroup. + - ``assignments`` -- argument for specialization of the generators of + this dynamical semigroup - OUTPUT: a dynamical semigroup with the specialization of the generators of this dynamical semigroup. + OUTPUT: a dynamical semigroup with the specialization of the generators + of this dynamical semigroup EXAMPLES:: @@ -846,7 +848,6 @@ def __mul__(self, other_dynamical_semigroup): OUTPUT: :class:`DynamicalSemigroup` - EXAMPLES:: sage: P. = ProjectiveSpace(QQ, 1) @@ -986,7 +987,7 @@ def __pow__(self, n): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: :class:`DynamicalSemigroup` @@ -1123,7 +1124,7 @@ def _repr_(self): r""" Return the :class:`String` representation of this dynamical semigroup. - OUTPUT: A :class:`String` displaying information about this dynamical semigroup. + OUTPUT: a :class:`String` displaying information about this dynamical semigroup EXAMPLES:: @@ -1154,7 +1155,7 @@ def __eq__(self, other): OUTPUT: - A boolean that is True if and only if the generators of the two + A boolean that is ``True`` if and only if the generators of the two dynamical semigroups are equal as sets and no generator is of degree 1. EXAMPLES:: @@ -1221,8 +1222,8 @@ class DynamicalSemigroup_projective(DynamicalSemigroup): INPUT: - - ``ds_data`` -- list or tuple of dynamical systems or objects that define dynamical systems - over projective space. + - ``ds_data`` -- list or tuple of dynamical systems or objects that define + dynamical systems over projective space OUTPUT: :class:`DynamicalSemigroup_projective` @@ -1277,7 +1278,7 @@ def dehomogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers. If ``n`` is an integer, + - ``n`` -- tuple of nonnegative integers; if `n` is an integer, then the two values of the tuple are assumed to be the same OUTPUT: :class:`DynamicalSemigroup_affine` @@ -1349,7 +1350,7 @@ class DynamicalSemigroup_affine(DynamicalSemigroup): INPUT: - ``ds_data`` -- list or tuple of dynamical systems or objects that define dynamical systems - over affine space. + over affine space OUTPUT: :class:`DynamicalSemigroup_affine` @@ -1403,7 +1404,7 @@ def homogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers. If ``n`` is an integer, + - ``n`` -- tuple of nonnegative integers; if `n` is an integer, then the two values of the tuple are assumed to be the same OUTPUT: :class:`DynamicalSemigroup_projective` diff --git a/src/sage/dynamics/arithmetic_dynamics/endPN_automorphism_group.py b/src/sage/dynamics/arithmetic_dynamics/endPN_automorphism_group.py index d0d662dcc57..d10207210a5 100644 --- a/src/sage/dynamics/arithmetic_dynamics/endPN_automorphism_group.py +++ b/src/sage/dynamics/arithmetic_dynamics/endPN_automorphism_group.py @@ -45,7 +45,8 @@ def automorphism_group_QQ_fixedpoints(rational_function, return_functions=False, iso_type=False): r""" - Compute the automorphism group for ``rational_function`` via the method of fixed points + Compute the automorphism group for ``rational_function`` via the method of + fixed points. ALGORITHM: @@ -55,13 +56,14 @@ def automorphism_group_QQ_fixedpoints(rational_function, return_functions=False, - ``rational_function`` -- Rational Function defined over `\ZZ` or `\QQ` - - ``return_functions`` -- Boolean value; ``True`` will return elements in the automorphism group - as linear fractional transformations. ``False`` will return elements as `PGL_2` matrices + - ``return_functions`` -- boolean value; ``True`` will return elements in + the automorphism group as linear fractional transformations. ``False`` + will return elements as `PGL_2` matrices. - - ``iso_type`` -- Boolean; ``True`` will cause the classification of the finite automorphism - group to also be returned + - ``iso_type`` -- boolean; ``True`` will cause the classification of the + finite automorphism group to also be returned - OUTPUT: a list of automorphisms that make up the automorphism group + OUTPUT: list of automorphisms that make up the automorphism group of ``rational_function`` EXAMPLES:: @@ -410,11 +412,11 @@ def CRT_helper(automorphisms, moduli): INPUT: - - ``automorphisms`` -- a list of lists of automorphisms over various `Zmod(p^k)` + - ``automorphisms`` -- list of lists of automorphisms over various `Zmod(p^k)` - ``moduli`` -- list of the various `p^k` - OUTPUT: a list of automorphisms over `Zmod(M)` + OUTPUT: list of automorphisms over `Zmod(M)` EXAMPLES:: @@ -459,15 +461,16 @@ def CRT_automorphisms(automorphisms, order_elts, degree, moduli): INPUT: - - ``automorphisms`` -- a list of lists of automorphisms over various `Zmod(p^k)` + - ``automorphisms`` -- list of lists of automorphisms over various `Zmod(p^k)` - - ``order_elts`` -- a list of lists of the orders of the elements of ``automorphisms`` + - ``order_elts`` -- list of lists of the orders of the elements of ``automorphisms`` - - ``degree`` -- a positive integer + - ``degree`` -- positive integer - ``moduli`` -- list of prime powers, i.e., `p^k` - OUTPUT: a list containing a list of automorphisms over `Zmod(M)` and the product of the moduli + OUTPUT: list containing a list of automorphisms over `Zmod(M)` and the + product of the moduli EXAMPLES:: @@ -503,17 +506,17 @@ def valid_automorphisms(automorphisms_CRT, rational_function, ht_bound, M, INPUT: - - ``automorphisms`` -- a list of lists of automorphisms over various `Zmod(p^k)` + - ``automorphisms`` -- list of lists of automorphisms over various `Zmod(p^k)` - - ``rational_function`` -- A one variable rational function + - ``rational_function`` -- a one variable rational function - - ``ht_bound`` -- a positive integer + - ``ht_bound`` -- positive integer - - ``M`` -- a positive integer, a product of prime powers + - ``M`` -- positive integer, a product of prime powers - - ``return_functions`` -- (default: ``False``) boolean + - ``return_functions`` -- boolean (default: ``False``) - OUTPUT: a list of automorphisms over `\ZZ` + OUTPUT: list of automorphisms over `\ZZ` EXAMPLES:: @@ -558,15 +561,15 @@ def remove_redundant_automorphisms(automorphisms, order_elts, moduli, integral_a INPUT: - - ``automorphisms`` -- a list of lists of automorphisms + - ``automorphisms`` -- list of lists of automorphisms - - ``order_elts`` -- a list of lists of the orders of the elements of ``automorphisms`` + - ``order_elts`` -- list of lists of the orders of the elements of ``automorphisms`` - - ``moduli`` -- a list of prime powers + - ``moduli`` -- list of prime powers - ``integral_autos`` -- list of known automorphisms - OUTPUT: a list of automorphisms + OUTPUT: list of automorphisms EXAMPLES:: @@ -631,10 +634,11 @@ def automorphism_group_QQ_CRT(rational_function, prime_lower_bound=4, return_fun - ``prime_lower_bound`` -- (default: 4) a positive integer; a lower bound for the primes to use for the Chinese Remainder Theorem step - - ``return_functions`` -- (default: ``True``) boolean; ``True`` returns linear fractional transformations - False returns elements of `PGL(2,\QQ)` + - ``return_functions`` -- boolean (default: ``True``); ``True`` returns + linear fractional transformations ``False`` returns elements of `PGL(2,\QQ)` - - ``iso_type`` -- (default: ``False``) boolean; ``True`` returns the isomorphism type of the automorphism group + - ``iso_type`` -- boolean (default: ``False``); ``True`` returns the + isomorphism type of the automorphism group OUTPUT: a complete list of automorphisms of ``rational_function`` @@ -840,14 +844,16 @@ def automorphism_group_FF(rational_function, absolute=False, iso_type=False, ret - ``rational_function`` -- a rational function defined over the fraction field of a polynomial ring in one variable with finite field coefficients - - ``absolute`` -- (default: ``False``) boolean; ``True`` returns the absolute automorphism group and a field of definition + - ``absolute`` -- boolean (default: ``False``); ``True`` returns the + absolute automorphism group and a field of definition - - ``iso_type`` -- (default: ``False``) boolean; ``True`` returns the isomorphism type of the automorphism group + - ``iso_type`` -- boolean (default: ``False``); ``True`` returns the + isomorphism type of the automorphism group - - ``return_functions`` -- (default: ``False``) boolean; ``True`` returns linear fractional transformations - False returns elements of `PGL(2)` + - ``return_functions`` -- boolean (default: ``False``); ``True`` returns + linear fractional transformations ``False`` returns elements of `PGL(2)` - OUTPUT: a list of automorphisms of ``rational_function`` + OUTPUT: list of automorphisms of ``rational_function`` EXAMPLES:: @@ -1088,7 +1094,7 @@ def three_stable_points(rational_function, invariant_list): - ``rational_function`` -- rational function `\phi` defined over finite field `E` - - ``invariant_list`` -- a list of at least `3` points of `\mathbb{P}^1(E)` that + - ``invariant_list`` -- list of at least `3` points of `\mathbb{P}^1(E)` that is stable under `Aut_{\phi}(E)` OUTPUT: list of automorphisms @@ -1460,7 +1466,7 @@ def automorphisms_fixing_pair(rational_function, pair, quad): - ``pair`` -- a pair of points of `\mathbb{P}^1(E)` - - ``quad`` -- Boolean: an indicator if this is a quadratic pair of points + - ``quad`` -- boolean; an indicator if this is a quadratic pair of points OUTPUT: set of automorphisms with order prime to characteristic defined over `E` that fix the pair, excluding the identity @@ -1704,7 +1710,7 @@ def which_group(list_of_elements): - ``list_of_elements`` -- a finite list of elements of `PGL(2,K)` that we know a priori form a group - OUTPUT: a string -- the isomorphism type of the group + OUTPUT: string; the isomorphism type of the group EXAMPLES:: @@ -1835,7 +1841,7 @@ def conjugating_set_initializer(f, g): of which no `n+1` are linearly dependent. Used to specify a possible conjugation from `f` to `g`. - - ``possible_targets`` -- a list of tuples of the form (``points``, ``repeated``). ``points`` + - ``possible_targets`` -- list of tuples of the form (``points``, ``repeated``). ``points`` is a list of ``points`` which are possible targets for point(s) in ``source``. ``repeated`` specifies how many points in ``source`` have points in ``points`` as their possible target. @@ -2060,12 +2066,12 @@ def greedy_independence_check(P, repeated_mult, point_to_mult): - ``P`` -- a projective space - - ``repeated_mult`` -- a dictionary of integers to lists of points of + - ``repeated_mult`` -- dictionary of integers to lists of points of the projective space ``P``. The list of points should be conjugation invariant. The keys are considered as weights, and this function attempts to minimize the total weight - - ``point_to_mult`` -- a dictionary of points of ``P`` to tuples of the form + - ``point_to_mult`` -- dictionary of points of ``P`` to tuples of the form (multiplier, level), where multiplier is the characteristic polynomial of the multiplier of the point, and level is the number of preimages taken to find the point @@ -2078,9 +2084,9 @@ def greedy_independence_check(P, repeated_mult, point_to_mult): Otherwise, a tuple of the form (``source``, ``corresponding``) is returned. - ``source`` -- the set `U` of the conjugation invariant pair. A set of `n+2` points - of the domain of `f`, of which no `n+1` are linearly dependent. + of the domain of `f`, of which no `n+1` are linearly dependent - - ``corresponding`` -- a list of tuples of the form ((multiplier, level), repeat) where the + - ``corresponding`` -- list of tuples of the form ((multiplier, level), repeat) where the (multiplier, level) pair is the multiplier of a point in ``source`` and repeat specifies how many points in source have that (multiplier, level) pair. This information specifies the set `V` of the invariant pair. @@ -2138,14 +2144,14 @@ def conjugating_set_helper(f, g, num_cpus, source, possible_targets): - ``num_cpus`` -- the number of threads to run in parallel - - ``source`` -- a list of `n+2` conjugation invariant points, of which - no `n+1` are linearly dependent. + - ``source`` -- list of `n+2` conjugation invariant points, of which + no `n+1` are linearly dependent - - ``possible_targets`` -- a list of tuples of the form (``points``, ``repeated``). ``points`` + - ``possible_targets`` -- list of tuples of the form (``points``, ``repeated``). ``points`` is a list of ``points`` which are possible targets for point(s) in ``source``. ``repeated`` specifies how many points in ``source`` have points in ``points`` as their possible target. - OUTPUT: a list of elements of PGL which conjugate ``f`` to ``g``. + OUTPUT: list of elements of PGL which conjugate ``f`` to ``g`` EXAMPLES:: @@ -2282,14 +2288,14 @@ def is_conjugate_helper(f, g, num_cpus, source, possible_targets): - ``num_cpus`` -- the number of threads to run in parallel - - ``source`` -- a list of `n+2` conjugation invariant points, of which - no `n+1` are linearly dependent. + - ``source`` -- list of `n+2` conjugation invariant points, of which + no `n+1` are linearly dependent - - ``possible_targets`` -- a list of tuples of the form (``points``, ``repeated``). ``points`` + - ``possible_targets`` -- list of tuples of the form (``points``, ``repeated``). ``points`` is a list of ``points`` which are possible targets for point(s) in ``source``. ``repeated`` specifies how many points in ``source`` have points in ``points`` as their possible target. - OUTPUT: ``True`` if ``f`` is conjugate to ``g``, ``False`` otherwise. + OUTPUT: ``True`` if ``f`` is conjugate to ``g``, ``False`` otherwise EXAMPLES:: diff --git a/src/sage/dynamics/arithmetic_dynamics/endPN_minimal_model.py b/src/sage/dynamics/arithmetic_dynamics/endPN_minimal_model.py index 393e568118e..c993cab86db 100644 --- a/src/sage/dynamics/arithmetic_dynamics/endPN_minimal_model.py +++ b/src/sage/dynamics/arithmetic_dynamics/endPN_minimal_model.py @@ -48,16 +48,16 @@ def bCheck(c, v, p, b): INPUT: - - ``c`` -- a list of polynomials in `b`. See v for their use + - ``c`` -- list of polynomials in `b`. See v for their use - - ``v`` -- a list of rational numbers, where we are considering the inequalities + - ``v`` -- list of rational numbers, where we are considering the inequalities `ord_p(c[i]) > v[i]` - ``p`` -- a prime - ``b`` -- local variable - OUTPUT: ``bval`` -- Integer, lower bound in Theorem 3.3.5 + OUTPUT: ``bval`` -- integer; lower bound in Theorem 3.3.5 EXAMPLES:: @@ -88,9 +88,9 @@ def scale(c, v, p): INPUT: - - ``c`` -- an integer polynomial + - ``c`` -- integer polynomial - - ``v`` -- an integer; the bound on the exponent from :func:`blift` + - ``v`` -- integer; the bound on the exponent from :func:`blift` - ``p`` -- a prime @@ -129,9 +129,9 @@ def blift(LF, Li, p, k, S=None, all_orbits=False): INPUT: - - ``LF`` -- a list of integer polynomials in one variable (the normalized coefficients) + - ``LF`` -- list of integer polynomials in one variable (the normalized coefficients) - - ``Li`` -- an integer, the bound on coefficients + - ``Li`` -- integer; the bound on coefficients - ``p`` -- a prime @@ -220,20 +220,18 @@ def affine_minimal(vp, return_transformation=False, D=None, quick=False): - ``vp`` -- dynamical system on the projective line - - ``D`` -- a list of primes, in case one only wants to check minimality + - ``D`` -- list of primes, in case one only wants to check minimality at those specific primes - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the `PGL_2` transformation to conjugate this map to the calculated models - - ``quick`` -- a boolean value. If true the algorithm terminates once + - ``quick`` -- boolean value. If true the algorithm terminates once algorithm determines F/G is not minimal, otherwise algorithm only terminates once a minimal model has been found - OUTPUT: - - - ``newvp`` -- dynamical system on the projective line + OUTPUT: ``newvp`` -- dynamical system on the projective line - ``conj`` -- linear fractional transformation which conjugates ``vp`` to ``newvp`` @@ -341,7 +339,7 @@ def Min(Fun, p, ubRes, conj, all_orbits=False): - ``p`` -- a prime - - ``ubRes`` -- integer, the upper bound needed for Th. 3.3.3 in [Molnar]_ + - ``ubRes`` -- integer; the upper bound needed for Th. 3.3.3 in [Molnar]_ - ``conj`` -- a 2x2 matrix keeping track of the conjugation @@ -491,11 +489,11 @@ def BM_all_minimal(vp, return_transformation=False, D=None): - ``vp`` -- a minimal model of a dynamical system on the projective line - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the ``PGL_2`` transformation to conjugate ``vp`` to the calculated minimal model - - ``D`` -- a list of primes, in case one only wants to check minimality + - ``D`` -- list of primes, in case one only wants to check minimality at those specific primes OUTPUT: @@ -637,11 +635,11 @@ def HS_minimal(f, return_transformation=False, D=None): - ``f`` -- dynamical system on the projective line with minimal resultant - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the `PGL_2` transformation to conjugate this map to the calculated models - - ``D`` -- a list of primes, in case one only wants to check minimality + - ``D`` -- list of primes, in case one only wants to check minimality at those specific primes OUTPUT: @@ -733,7 +731,7 @@ def HS_all_minimal_p(p, f, m=None, return_transformation=False): - ``m`` -- (optional) `2 \times 2` matrix associated with ``f`` - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the ``PGL_2`` transformation to conjugate ``vp`` to the calculated minimal model @@ -828,11 +826,11 @@ def HS_all_minimal(f, return_transformation=False, D=None): - ``f`` -- dynamical system on the projective line with minimal resultant - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the ``PGL_2`` transformation to conjugate ``vp`` to the calculated minimal model - - ``D`` -- a list of primes, in case one only wants to check minimality + - ``D`` -- list of primes, in case one only wants to check minimality at those specific primes OUTPUT: @@ -914,7 +912,7 @@ def get_bound_dynamical(F, f, m=1, dynatomic=True, prec=53, emb=None): This defines the maximum possible distance from `j` to the `z_0` covariant of the associated binary form `F` in the hyperbolic 3-space - for which the map `f`` could have smaller coefficients. + for which the map `f` could have smaller coefficients. INPUT: @@ -984,7 +982,7 @@ def coshdelta(z): def smallest_dynamical(f, dynatomic=True, start_n=1, prec=53, emb=None, algorithm='HS', check_minimal=True): r""" - Determine the poly with smallest coefficients in `SL(2,\ZZ)` orbit of ``F`` + Determine the poly with smallest coefficients in `SL(2,\ZZ)` orbit of ``F``. Smallest is in the sense of global height. The method is the algorithm in Hutz-Stoll [HS2018]_. diff --git a/src/sage/dynamics/arithmetic_dynamics/generic_ds.py b/src/sage/dynamics/arithmetic_dynamics/generic_ds.py index be678cca40a..f16d99cbb11 100644 --- a/src/sage/dynamics/arithmetic_dynamics/generic_ds.py +++ b/src/sage/dynamics/arithmetic_dynamics/generic_ds.py @@ -50,12 +50,12 @@ class DynamicalSystem(SchemeMorphism_polynomial, INPUT: - - ``polys_or_rat_fncts`` -- a list of polynomials or rational functions, + - ``polys_or_rat_fncts`` -- list of polynomials or rational functions, all of which should have the same parent - ``domain`` -- an affine or projective scheme, or product of - projective schemes, on which ``polys`` defines an endomorphism. - Subschemes are also ok + projective schemes, on which ``polys`` defines an endomorphism + (Subschemes are also ok) - ``names`` -- (default: ``('X', 'Y')``) tuple of strings to be used as coordinate names for a projective space that is constructed @@ -338,20 +338,20 @@ def specialization(self, D=None, phi=None, homset=None): def field_of_definition_critical(self, return_embedding=False, simplify_all=False, names='a'): r""" - Return smallest extension of the base field which contains the critical points + Return smallest extension of the base field which contains the critical points. Ambient space of dynamical system must be either the affine line or projective line over a number field or finite field. INPUT: - - ``return_embedding`` -- (default: ``False``) boolean; If ``True``, return an + - ``return_embedding`` -- boolean (default: ``False``); if ``True``, return an embedding of base field of dynamical system into the returned number field or finite field. Note that computing this embedding might be expensive. - - ``simplify_all`` -- (default: ``False``) boolean; If ``True``, simplify + - ``simplify_all`` -- boolean (default: ``False``); if ``True``, simplify intermediate fields and also the resulting number field. Note that this - is not implemented for finite fields and has no effect + is not implemented for finite fields and has no effect. - ``names`` -- (optional) string to be used as generator for returned number field or finite field @@ -448,21 +448,21 @@ def field_of_definition_periodic(self, n, formal=False, return_embedding=False, INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``formal`` -- (default: ``False``) boolean; ``True`` signals to return number + - ``formal`` -- boolean (default: ``False``); ``True`` signals to return number field or finite field over which the formal periodic points are defined, where a formal periodic point is a root of the ``n``-th dynatomic polynomial. ``False`` specifies to find number field or finite field over which all periodic - points of the ``n``-th iterate are defined + points of the ``n``-th iterate are defined. - - ``return_embedding`` -- (default: ``False``) boolean; If ``True``, return + - ``return_embedding`` -- boolean (default: ``False``); if ``True``, return an embedding of base field of dynamical system into the returned number field or finite field. Note that computing this embedding might be expensive. - - ``simplify_all`` -- (default: ``False``) boolean; If ``True``, simplify + - ``simplify_all`` -- boolean (default: ``False``); if ``True``, simplify intermediate fields and also the resulting number field. Note that this - is not implemented for finite fields and has no effect + is not implemented for finite fields and has no effect. - ``names`` -- (optional) string to be used as generator for returned number field or finite field @@ -574,15 +574,15 @@ def field_of_definition_preimage(self, point, n, return_embedding=False, simplif - ``point`` -- a point in this map's domain - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``return_embedding`` -- (default: ``False``) boolean; If ``True``, return + - ``return_embedding`` -- boolean (default: ``False``); if ``True``, return an embedding of base field of dynamical system into the returned number field or finite field. Note that computing this embedding might be expensive. - - ``simplify_all`` -- (default: ``False``) boolean; If ``True``, simplify + - ``simplify_all`` -- boolean (default: ``False``); if ``True``, simplify intermediate fields and also the resulting number field. Note that this - is not implemented for finite fields and has no effect + is not implemented for finite fields and has no effect. - ``names`` -- (optional) string to be used as generator for returned number field or finite field diff --git a/src/sage/dynamics/arithmetic_dynamics/product_projective_ds.py b/src/sage/dynamics/arithmetic_dynamics/product_projective_ds.py index 706bb28cbef..3cf6ae27350 100644 --- a/src/sage/dynamics/arithmetic_dynamics/product_projective_ds.py +++ b/src/sage/dynamics/arithmetic_dynamics/product_projective_ds.py @@ -47,7 +47,7 @@ class DynamicalSystem_product_projective(DynamicalSystem, INPUT: - - ``polys`` -- a list of `n_1 + \cdots + n_r` multi-homogeneous polynomials, all + - ``polys`` -- list of `n_1 + \cdots + n_r` multi-homogeneous polynomials, all of which should have the same parent - ``domain`` -- a projective scheme embedded in @@ -85,10 +85,10 @@ def _call_with_args(self, P, check=True): - ``P`` -- a point in the domain - - ``check`` -- Boolean; whether or not to perform the input checks - on the image point (Default: ``True``) + - ``check`` -- boolean (default: ``True``); whether or not to perform + the input checks on the image point - OUTPUT: The image point in the codomain + OUTPUT: the image point in the codomain EXAMPLES:: @@ -125,11 +125,11 @@ def nth_iterate(self, P, n, normalize=False): - ``P`` -- a point in ``self.domain()`` - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``normalize`` -- (default: ``False``) boolean + - ``normalize`` -- boolean (default: ``False``) - OUTPUT: A point in ``self.codomain()`` + OUTPUT: a point in ``self.codomain()`` EXAMPLES:: @@ -180,16 +180,15 @@ def orbit(self, P, N, **kwds): - ``P`` -- a point in ``self.domain()`` - - ``N`` -- a non-negative integer or list or tuple of two non-negative integers + - ``N`` -- nonnegative integer or list or tuple of two nonnegative integers kwds: - - ``check`` -- (default: ``True``) boolean + - ``check`` -- boolean (default: ``True``) - - ``normalize`` -- (default: ``False``) boolean + - ``normalize`` -- boolean (default: ``False``) - - OUTPUT: a list of points in ``self.codomain()`` + OUTPUT: list of points in ``self.codomain()`` EXAMPLES:: @@ -220,7 +219,7 @@ def orbit(self, P, N, **kwds): except TypeError: raise TypeError("orbit bounds must be integers") if N[0] < 0 or N[1] < 0: - raise TypeError("orbit bounds must be non-negative") + raise TypeError("orbit bounds must be nonnegative") if N[0] > N[1]: return [] @@ -255,9 +254,9 @@ def nth_iterate_map(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: A dynamical system of products of projective spaces + OUTPUT: a dynamical system of products of projective spaces EXAMPLES:: diff --git a/src/sage/dynamics/arithmetic_dynamics/projective_ds.py b/src/sage/dynamics/arithmetic_dynamics/projective_ds.py index 2f62d674289..192e531cd82 100644 --- a/src/sage/dynamics/arithmetic_dynamics/projective_ds.py +++ b/src/sage/dynamics/arithmetic_dynamics/projective_ds.py @@ -94,9 +94,9 @@ class initialization directly. from sage.rings.integer_ring import ZZ from sage.rings.polynomial.flatten import FlatteningMorphism, UnflatteningMorphism from sage.rings.morphism import RingHomomorphism_im_gens -from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing +from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.quotient_ring import QuotientRing_generic from sage.rings.rational_field import QQ from sage.rings.real_mpfr import RealField @@ -135,12 +135,12 @@ class DynamicalSystem_projective(SchemeMorphism_polynomial_projective_space, INPUT: - ``morphism_or_polys`` -- a SchemeMorphism, a polynomial, a - rational function, or a list or tuple of homogeneous polynomials. + rational function, or a list or tuple of homogeneous polynomials - - ``domain`` -- optional projective space or projective subscheme. + - ``domain`` -- (optional) projective space or projective subscheme - - ``names`` -- optional tuple of strings to be used as coordinate - names for a projective space that is constructed; defaults to ``'X','Y'``. + - ``names`` -- tuple of strings (default: ``'X','Y'``) to be used as coordinate + names for a projective space that is constructed The following combinations of ``morphism_or_polys`` and ``domain`` are meaningful: @@ -161,7 +161,7 @@ class DynamicalSystem_projective(SchemeMorphism_polynomial_projective_space, 1-dimensional projective space over the base ring of ``morphism_or_polys`` with coordinate names given by ``names``. - OUTPUT: :class:`DynamicalSystem_projective`. + OUTPUT: :class:`DynamicalSystem_projective` EXAMPLES:: @@ -384,7 +384,7 @@ def __classcall_private__(cls, morphism_or_polys, domain=None, names=None): polys = list(morphism_or_polys) if len(polys) == 1: raise ValueError("list/tuple must have at least 2 polynomials") - test = lambda x: is_PolynomialRing(x) or is_MPolynomialRing(x) + test = lambda x: isinstance(x, PolynomialRing_general) or isinstance(x, MPolynomialRing_base) if not all(test(poly.parent()) for poly in polys): try: polys = [poly.lift() for poly in polys] @@ -394,8 +394,8 @@ def __classcall_private__(cls, morphism_or_polys, domain=None, names=None): # homogenize! f = morphism_or_polys aff_CR = f.parent() - if (not is_PolynomialRing(aff_CR) and not isinstance(aff_CR, FractionField_generic) - and not (is_MPolynomialRing(aff_CR) and aff_CR.ngens() == 1)): + if (not isinstance(aff_CR, PolynomialRing_general) and not isinstance(aff_CR, FractionField_generic) + and not (isinstance(aff_CR, MPolynomialRing_base) and aff_CR.ngens() == 1)): msg = '{} is not a single variable polynomial or rational function' raise ValueError(msg.format(f)) if isinstance(aff_CR, FractionField_generic): @@ -498,7 +498,7 @@ def _number_field_from_algebraics(self): r""" Return a dynamical system defined over the number field of its coefficients. - OUTPUT: dynamical system. + OUTPUT: dynamical system EXAMPLES:: @@ -522,7 +522,7 @@ def dehomogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers; if ``n`` is an integer, + - ``n`` -- tuple of nonnegative integers; if ``n`` is an integer, then the two values of the tuple are assumed to be the same OUTPUT: @@ -594,7 +594,7 @@ def dynatomic_polynomial(self, period): INPUT: - - ``period`` -- a positive integer or a list/tuple `[m,n]` where + - ``period`` -- positive integer or a list/tuple `[m,n]` where `m` is the preperiod and `n` is the period OUTPUT: @@ -1005,11 +1005,11 @@ def nth_iterate(self, P, n, **kwds): - ``P`` -- a point in this map's domain - - ``n`` -- a positive integer + - ``n`` -- positive integer kwds: - - ``normalize`` -- (default: ``False``) boolean + - ``normalize`` -- boolean (default: ``False``) OUTPUT: a point in this map's codomain @@ -1138,13 +1138,13 @@ def arakelov_zhang_pairing(self, g, **kwds): INPUT: - - ``g`` -- a rational map of `\mathbb{P}^1` given as a projective morphism. - ``g`` and ``self`` should have the same field of definition. + - ``g`` -- a rational map of `\mathbb{P}^1` given as a projective morphism + ``g`` and ``self`` should have the same field of definition kwds: - - ``n`` -- (default: 5) a positive integer - Order of periodic points to use or preimages to take if starting points are specified. + - ``n`` -- positive integer (default: 5); order of periodic points to + use or preimages to take if starting points are specified - ``f_starting_point`` -- (default: ``None``) value in the base number field or None. If ``f_starting_point`` is None, we solve for points of period ``n`` for ``self``. @@ -1156,11 +1156,11 @@ def arakelov_zhang_pairing(self, g, **kwds): Otherwise, we take ``n``-th preimages of the point given by ``g_starting_point`` under ``g`` on the affine line. - - ``check_primes_of_bad_reduction`` -- (default: ``False``) boolean. - Passed to the ``primes_of_bad_reduction`` function for ``self`` and ``g``. + - ``check_primes_of_bad_reduction`` -- boolean (default: ``False``); + passed to the ``primes_of_bad_reduction`` function for ``self`` and ``g`` - - ``prec`` -- (default: ``RealField`` default) - default precision for RealField values which are returned. + - ``prec`` -- (default: ``RealField`` default); + default precision for RealField values which are returned - ``noise_multiplier`` -- (default: 2) a real number. Discriminant terms involved in the computation at the archimedean places @@ -1174,9 +1174,7 @@ def arakelov_zhang_pairing(self, g, **kwds): the accuracy of the estimate of the pairing. If desired, ``noise_multiplier`` can be set to 0, and no terms will be ignored. - OUTPUT: - - - a real number estimating the Arakelov-Zhang pairing of the two rational maps. + OUTPUT: a real number estimating the Arakelov-Zhang pairing of the two rational maps EXAMPLES:: @@ -1416,7 +1414,9 @@ def degree_sequence(self, iterates=2): Return sequence of degrees of normalized iterates starting with the degree of this dynamical system. - INPUT: ``iterates`` -- (default: 2) positive integer + INPUT: + + - ``iterates`` -- (default: 2) positive integer OUTPUT: list of integers @@ -1519,16 +1519,16 @@ def orbit(self, P, N, **kwds): - ``P`` -- a point in this dynamical system's domain - - ``n`` -- a non-negative integer or list or tuple of two - non-negative integers + - ``n`` -- nonnegative integer or list or tuple of two + nonnegative integers kwds: - - ``check`` -- (default: ``True``) boolean + - ``check`` -- boolean (default: ``True``) - - ``normalize`` -- (default: ``False``) boolean + - ``normalize`` -- boolean (default: ``False``) - OUTPUT: a list of points in this dynamical system's codomain + OUTPUT: list of points in this dynamical system's codomain EXAMPLES:: @@ -1581,7 +1581,7 @@ def orbit(self, P, N, **kwds): sage: f.orbit(P(2, 1),[-1, 4]) Traceback (most recent call last): ... - TypeError: orbit bounds must be non-negative + TypeError: orbit bounds must be nonnegative sage: f.orbit(P(2, 1), 0.1) Traceback (most recent call last): ... @@ -1633,7 +1633,7 @@ def orbit(self, P, N, **kwds): N[0] = Integer(N[0]) N[1] = Integer(N[1]) if N[0] < 0 or N[1] < 0: - raise TypeError("orbit bounds must be non-negative") + raise TypeError("orbit bounds must be nonnegative") if N[0] > N[1]: return [] @@ -1668,7 +1668,7 @@ def resultant(self, normalize=False): INPUT: - - ``normalize`` -- (default: ``False``) boolean + - ``normalize`` -- boolean (default: ``False``) OUTPUT: an element of the base ring of this map @@ -1751,20 +1751,20 @@ def primes_of_bad_reduction(self, check=True): ALGORITHM: `p` is a prime of bad reduction if and only if the defining - polynomials of self have a common zero. Or stated another way, + polynomials of ``self`` have a common zero. Or stated another way, `p` is a prime of bad reduction if and only if the radical of - the ideal defined by the defining polynomials of self is not + the ideal defined by the defining polynomials of ``self`` is not `(x_0,x_1,\ldots,x_N)`. This happens if and only if some power of each `x_i` is not in the ideal defined by the - defining polynomials of self. This last condition is what is + defining polynomials of ``self``. This last condition is what is checked. The lcm of the coefficients of the monomials `x_i` in a Groebner basis is computed. This may return extra primes. INPUT: - - ``check`` -- (default: ``True``) boolean + - ``check`` -- boolean (default: ``True``) - OUTPUT: a list of primes + OUTPUT: list of primes EXAMPLES:: @@ -1873,13 +1873,13 @@ def conjugate(self, M, adjugate=False, normalize=False): - ``M`` -- a square invertible matrix - - ``adjugate`` -- (default: ``False``) boolean, also classically called + - ``adjugate`` -- boolean (default: ``False``); also classically called adjoint, takes a square matrix ``M`` and finds the transpose of its cofactor matrix. Used for conjugation in place of inverse when specified ``True``. Functionality is the same in projective space. - - ``normalize`` -- (default: ``False``) boolean, if ``normalize`` is - ``True``, then the method ``normalize_coordinates`` is called. + - ``normalize`` -- boolean (default: ``False``); if ``normalize`` is + ``True``, then the method ``normalize_coordinates`` is called OUTPUT: a dynamical system @@ -1999,12 +1999,12 @@ def green_function(self, P, v, **kwds): - ``P`` -- a projective point - - ``v`` -- non-negative integer. a place, use ``0`` for the + - ``v`` -- nonnegative integer; a place, use ``0`` for the archimedean place kwds: - - ``N`` -- (default: 10) positive integer. number of + - ``N`` -- (default: 10) positive integer; number of terms of the series to use - ``prec`` -- (default: 100) positive integer, float point or @@ -2196,7 +2196,7 @@ def canonical_height(self, P, **kwds): - ``badprimes`` -- (optional) a list of primes of bad reduction - - ``N`` -- (default: 10) positive integer. number of + - ``N`` -- (default: 10) positive integer; number of terms of the series to use in the local green functions - ``prec`` -- (default: 100) positive integer, float point or @@ -2498,9 +2498,9 @@ def multiplier(self, P, n, check=True): - ``P`` -- a point on domain of this map - - ``n`` -- a positive integer, the period of ``P`` + - ``n`` -- positive integer, the period of ``P`` - - ``check`` -- (default: ``True``) boolean; verify that ``P`` + - ``check`` -- boolean (default: ``True``); verify that ``P`` has period ``n`` OUTPUT: @@ -2599,11 +2599,11 @@ def _multipliermod(self, P, n, p, k): - ``P`` -- a point on domain of this map - - ``n`` -- a positive integer, the period of ``P`` + - ``n`` -- positive integer, the period of ``P`` - - ``p`` -- a positive integer + - ``p`` -- positive integer - - ``k`` -- a positive integer + - ``k`` -- positive integer OUTPUT: @@ -2728,37 +2728,37 @@ def nth_preimage_tree(self, Q, n, **kwds): - ``Q`` -- a point in the domain of this map - - ``n`` -- a positive integer, the depth of the pre-image tree + - ``n`` -- positive integer, the depth of the pre-image tree kwds: - - ``return_points`` -- (default: ``False``) boolean; if ``True``, + - ``return_points`` -- boolean (default: ``False``); if ``True``, return a list of lists where the index `i` is the level of the tree and the elements of the list at that index are the `i`-th preimage points as an algebraic element of the splitting field of the - polynomial `f^n - Q = 0` + polynomial `f^n - Q = 0`. - - ``numerical`` -- (default: ``False``) boolean; calculate pre-images + - ``numerical`` -- boolean (default: ``False``); calculate pre-images numerically. Note if this is set to ``True``, preimage points are - displayed as complex numbers + displayed as complex numbers. - ``prec`` -- (default: 100) positive integer; the precision of the ``ComplexField`` if we compute the preimage points numerically - - ``display_labels`` -- (default: ``True``) boolean; whether to display + - ``display_labels`` -- boolean (default: ``True``); whether to display vertex labels. Since labels can be very cluttered, can set ``display_labels`` to ``False`` and use ``return_points`` to get a - hold of the points themselves, either as algebraic or complex numbers + hold of the points themselves, either as algebraic or complex numbers. - - ``display_complex`` -- (default: ``False``) boolean; display vertex + - ``display_complex`` -- boolean (default: ``False``); display vertex labels as complex numbers. Note if this option is chosen that we must choose an embedding from the splitting field ``field_def`` of the `n`-th-preimage equation into `\CC`. We make the choice of the first - embedding returned by ``field_def.embeddings(ComplexField())`` + embedding returned by ``field_def.embeddings(ComplexField())``. - - ``digits`` -- a positive integer, the number of decimal digits to + - ``digits`` -- positive integer; the number of decimal digits to display for complex numbers. This only applies if ``display_complex`` - is set to ``True`` + is set to ``True``. OUTPUT: @@ -2864,19 +2864,17 @@ def possible_periods(self, **kwds): Calls ``self.possible_periods()`` modulo all primes of good reduction in range ``prime_bound``. Return the intersection of those lists. - INPUT: + INPUT: keyword arguments: - kwds: - - - ``prime_bound`` -- (default: ``[1, 20]``) a list or tuple of - two positive integers or an integer for the upper bound + - ``prime_bound`` -- (default: ``[1, 20]``) a list or tuple of + two positive integers or an integer for the upper bound - ``bad_primes`` -- (optional) a list or tuple of integer primes, the primes of bad reduction - ``ncpus`` -- (default: all cpus) number of cpus to use in parallel - OUTPUT: a list of positive integers + OUTPUT: list of positive integers EXAMPLES:: @@ -2969,7 +2967,7 @@ def _preperiodic_points_to_cyclegraph(self, preper): INPUT: - - ``preper`` -- a list or tuple of projective points; the complete + - ``preper`` -- list or tuple of projective points; the complete set of rational periodic or preperiodic points OUTPUT: @@ -3075,7 +3073,7 @@ def minimal_model(self, return_transformation=False, prime_list=None, algorithm= INPUT: - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the `PGL_2` transformation to conjugate this map to the calculated minimal model @@ -3084,7 +3082,7 @@ def minimal_model(self, return_transformation=False, prime_list=None, algorithm= - ``algorithm`` -- (optional) string; can be one of the following: - - ``check_primes`` -- (optional) boolean: this signals whether to + - ``check_primes`` -- (optional) boolean; this signals whether to check whether each element in ``prime_list`` is a prime * ``'BM'`` -- the Bruin-Molnar algorithm [BM2012]_ @@ -3259,7 +3257,7 @@ def all_minimal_models(self, return_transformation=False, prime_list=None, INPUT: - - ``return_transformation`` -- (default: ``False``) boolean; this + - ``return_transformation`` -- boolean (default: ``False``); this signals a return of the `PGL_2` transformation to conjugate this map to the calculated models @@ -3383,19 +3381,19 @@ def affine_preperiodic_model(self, m, n, return_conjugation=False): If the base ring of this dynamical system is finite, there may not be a model with affine preperiodic points, in which case a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. INPUT: - - ``m`` -- the preperiod of the preperiodic points to make affine. + - ``m`` -- the preperiod of the preperiodic points to make affine - - ``n`` -- the period of the preperiodic points to make affine. + - ``n`` -- the period of the preperiodic points to make affine - - ``return_conjugation`` -- (default: ``False``) If ``True``, return a tuple - ``(g, phi)`` where ``g`` is a model with affine (n, m) preperiodic points - and ``phi`` is the matrix that moves ``f`` to ``g``. + - ``return_conjugation`` -- boolean (default: ``False``); if ``True``, return a tuple + ``(g, phi)`` where ``g`` is a model with affine (n, m) preperiodic points + and ``phi`` is the matrix that moves ``f`` to ``g``. - OUTPUT: a dynamical system conjugate to this one. + OUTPUT: a dynamical system conjugate to this one EXAMPLES:: @@ -3485,7 +3483,7 @@ def affine_preperiodic_model(self, m, n, return_conjugation=False): raise ValueError('period must be positive') m = ZZ(m) if m < 0: - raise ValueError('preperiod must be non-negative') + raise ValueError('preperiod must be nonnegative') f = self CR = f.coordinate_ring() dom = f.domain() @@ -3533,7 +3531,7 @@ def affine_preperiodic_model(self, m, n, return_conjugation=False): if hyperplane_found: break else: - if is_PolynomialRing(R) or is_MPolynomialRing(R) or isinstance(R, FractionField_generic): + if isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base) or isinstance(R, FractionField_generic): # for polynomial rings, we can get an infinite family of hyperplanes # by increasing the degree var = R.gen() @@ -3568,7 +3566,7 @@ def affine_preperiodic_model(self, m, n, return_conjugation=False): def automorphism_group(self, **kwds): r""" - Calculates the subgroup of `PGL2` that is the automorphism group + Calculate the subgroup of `PGL2` that is the automorphism group of this dynamical system. The automorphism group is the set of `PGL(2)` elements that fixes @@ -3579,7 +3577,7 @@ def automorphism_group(self, **kwds): The following keywords are used in most cases: - ``num_cpus`` -- (default: 2) the number of threads to use. Setting to a - larger number can greatly speed up this function. + larger number can greatly speed up this function The following keywords are used only when the dimension of the domain is 1 and the base ring is the rationals, but ignored in all other cases: @@ -3591,14 +3589,14 @@ def automorphism_group(self, **kwds): * ``'CRT'`` -- Chinese Remainder Theorem * ``'fixed_points'`` -- fixed points algorithm - - ``return_functions`` -- (default: ``False``) boolean; ``True`` + - ``return_functions`` -- boolean (default: ``False``); ``True`` returns elements as linear fractional transformations and ``False`` returns elements as `PGL2` matrices - - ``iso_type`` -- (default: ``False``) boolean; ``True`` returns the + - ``iso_type`` -- boolean (default: ``False``); ``True`` returns the isomorphism type of the automorphism group - OUTPUT: a list of elements in the automorphism group + OUTPUT: list of elements in the automorphism group AUTHORS: @@ -3780,7 +3778,7 @@ def critical_subscheme(self): def critical_points(self, R=None): r""" Return the critical points of this dynamical system defined over - the ring ``R`` or the base ring of this map. + the ring `R` or the base ring of this map. Must be dimension 1. @@ -3788,7 +3786,7 @@ def critical_points(self, R=None): - ``R`` -- (optional) a ring - OUTPUT: a list of projective space points defined over ``R`` + OUTPUT: list of projective space points defined over `R` EXAMPLES:: @@ -3875,7 +3873,6 @@ def ramification_type(self, R=None, stable=True): [[2], [2], [3]] sage: F.ramification_type(R=F.base_ring()) # needs sage.rings.function_field [[2], [3]] - """ # Change base ring if specified. if R is None: @@ -3914,7 +3911,7 @@ def is_postcritically_finite(self, err=0.01, use_algebraic_closure=True): - ``err`` -- (default: 0.01) positive real number - - ``use_algebraic_closure`` -- boolean (default: ``True``) -- If ``True``, uses the + - ``use_algebraic_closure`` -- boolean (default: ``True``); if ``True``, uses the algebraic closure. If ``False``, uses the smallest extension of the base field containing all the critical points. @@ -4109,7 +4106,7 @@ def critical_point_portrait(self, check=True, use_algebraic_closure=True): - ``check`` -- boolean (default: ``True``) - - ``use_algebraic_closure`` -- boolean (default: ``True``) -- If ``True``, uses the + - ``use_algebraic_closure`` -- boolean (default: ``True``); if ``True``, uses the algebraic closure. If ``False``, uses the smallest extension of the base field containing all the critical points. @@ -4175,7 +4172,6 @@ def critical_point_portrait(self, check=True, use_algebraic_closure=True): Looped digraph on 6 vertices sage: f.critical_point_portrait() #long time Looped digraph on 6 vertices - """ #input checking done in is_postcritically_finite if check: @@ -4221,9 +4217,7 @@ def critical_height(self, **kwds): base field or over the minimal extension of the base field that contains the critical points. - INPUT: - - kwds: + INPUT: keyword arguments: - ``badprimes`` -- (optional) a list of primes of bad reduction @@ -4235,9 +4229,10 @@ def critical_height(self, **kwds): - ``error_bound`` -- (optional) a positive real number - - ``use_algebraic_closure`` -- boolean (default: ``True``) -- If ``True``, uses the - algebraic closure. If ``False``, uses the smallest extension of the base field - containing all the critical points. + - ``use_algebraic_closure`` -- boolean (default: ``True``); if + ``True``, uses the algebraic closure. If ``False``, uses the + smallest extension of the base field containing all the critical + points. OUTPUT: real number @@ -4304,7 +4299,7 @@ def critical_height(self, **kwds): def preperiodic_points(self, m, n, **kwds): r""" - Computes the preperiodic points of period ``m, n`` of this dynamical system + Compute the preperiodic points of period ``m, n`` of this dynamical system defined over the ring ``R`` or the base ring of the map. This is done by finding the rational points on the variety @@ -4316,25 +4311,25 @@ def preperiodic_points(self, m, n, **kwds): INPUT: - - ``n`` -- a positive integer, the period + - ``n`` -- positive integer; the period - - ``m`` -- a non negative integer, the preperiod + - ``m`` -- nonnegative integer; the preperiod kwds: - - ``minimal`` -- (default: ``True``) boolean; ``True`` specifies to + - ``minimal`` -- boolean (default: ``True``); ``True`` specifies to find only the preperiodic points of minimal period ``m``,``n`` and ``False`` specifies to find all preperiodic points of period ``m``, ``n`` - - ``formal`` -- (default: ``False``) boolean; ``True`` specifies to + - ``formal`` -- boolean (default: ``False``); ``True`` specifies to find the formal periodic points only. The formal periodic points are the points in the support of the dynatomic cycle. - ``R`` -- (default: the base ring of the dynamical system) a commutative ring over which to find the preperiodic points - - ``return_scheme`` -- (default: ``False``) boolean; return a + - ``return_scheme`` -- boolean (default: ``False``); return a subscheme of the ambient space that defines the ``m``,``n`` th preperiodic points @@ -4531,7 +4526,7 @@ def preperiodic_points(self, m, n, **kwds): if n <= 0: raise ValueError("a positive integer period must be specified") if m < 0: - raise ValueError("a non negative preperiod must be specified") + raise ValueError("a nonnegative preperiod must be specified") R = kwds.pop('R', None) if R is None: f_sub = self @@ -4598,7 +4593,7 @@ def preperiodic_points(self, m, n, **kwds): for k in ZZ(n).divisors(): if ZZ(n/k).is_prime(): Sn.append(k) - if (is_PolynomialRing(R) or is_MPolynomialRing(R)): + if (isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base)): phi = FlatteningMorphism(CR) flatCR = phi.codomain() Ik = flatCR.ideal(1) @@ -4641,7 +4636,7 @@ def preperiodic_points(self, m, n, **kwds): def periodic_points(self, n, minimal=True, formal=False, R=None, algorithm='variety', return_scheme=False): r""" - Computes the periodic points of period ``n`` of this dynamical system + Compute the periodic points of period ``n`` of this dynamical system defined over the ring ``R`` or the base ring of the map. This can be done either by finding the rational points on the variety @@ -4659,18 +4654,18 @@ def periodic_points(self, n, minimal=True, formal=False, R=None, algorithm='vari INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``minimal`` -- (default: ``True``) boolean; ``True`` specifies to + - ``minimal`` -- boolean (default: ``True``); ``True`` specifies to find only the periodic points of minimal period ``n`` and ``False`` specifies to find all periodic points of period ``n`` - - ``formal`` -- (default: ``False``) boolean; ``True`` specifies to + - ``formal`` -- boolean (default: ``False``); ``True`` specifies to find the formal periodic points only. The formal periodic points are the points in the support of the dynatomic cycle. - ``R`` -- (optional) a commutative ring. Defaults to the base ring of - this map. + this map - ``algorithm`` -- (default: ``'variety'``) must be one of the following: @@ -4881,7 +4876,7 @@ def periodic_points(self, n, minimal=True, formal=False, R=None, algorithm='vari raise NotImplementedError('periodic points not implemented for fraction function fields; ' 'clear denominators and use the polynomial ring instead') if isinstance(R, FractionField_generic): - if is_MPolynomialRing(R.ring()): + if isinstance(R.ring(), MPolynomialRing_base): raise NotImplementedError('periodic points not implemented for fraction function fields; ' 'clear denominators and use the polynomial ring instead') CR = f_sub.coordinate_ring() @@ -4954,7 +4949,7 @@ def periodic_points(self, n, minimal=True, formal=False, R=None, algorithm='vari for k in ZZ(n).divisors(): if ZZ(n/k).is_prime(): Sn.append(k) - if (is_PolynomialRing(R) or is_MPolynomialRing(R)): + if (isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base)): phi = FlatteningMorphism(CR) flatCR = phi.codomain() Ik = flatCR.ideal(1) @@ -4994,7 +4989,7 @@ def periodic_points(self, n, minimal=True, formal=False, R=None, algorithm='vari def multiplier_spectra(self, n, formal=False, type='point', use_algebraic_closure=True, check=True): r""" - Computes the ``n`` multiplier spectra of this dynamical system. + Compute the ``n`` multiplier spectra of this dynamical system. This is the set of multipliers of all peroidic points of period ``n`` included with the appropriate multiplicity. @@ -5011,9 +5006,9 @@ def multiplier_spectra(self, n, formal=False, type='point', use_algebraic_closur INPUT: - - ``n`` -- a positive integer, the period + - ``n`` -- positive integer, the period - - ``formal`` -- (default: ``False``) boolean; ``True`` specifies + - ``formal`` -- boolean (default: ``False``); ``True`` specifies to find the formal ``n`` multiplier spectra of this map and ``False`` specifies to find the ``n`` multiplier spectra @@ -5021,7 +5016,7 @@ def multiplier_spectra(self, n, formal=False, type='point', use_algebraic_closur or ``'cycle'`` depending on whether you compute one multiplier per point or one per cycle - - ``use_algebraic_closure`` -- boolean (default: ``True``) -- If ``True`` uses the + - ``use_algebraic_closure`` -- boolean (default: ``True``); if ``True`` uses the algebraic closure. Using the algebraic closure can sometimes lead to numerical instability and extraneous errors. For most accurate results in dimension 1, set to ``False``. If ``False``, and the map is defined over projective space of @@ -5029,7 +5024,7 @@ def multiplier_spectra(self, n, formal=False, type='point', use_algebraic_closur containing all the periodic points. If the map is defined over projective space of dimension greater than 1, then the base ring of the map is used. - - ``check`` -- (defualt: ``True``) whether to check if the + - ``check`` -- boolean (default: ``True``); whether to check if the full multiplier spectra was computed. If ``False``, can lead to mathematically incorrect answers in dimension greater than 1. Ignored if ``use_algebraic_closure`` is ``True`` or if this dynamical system is defined @@ -5398,7 +5393,7 @@ def multiplier_spectra(self, n, formal=False, type='point', use_algebraic_closur def sigma_invariants(self, n, formal=False, embedding=None, type='point', return_polynomial=False, chow=False, deform=False, check=True): r""" - Computes the values of the elementary symmetric polynomials evaluated + Compute the values of the elementary symmetric polynomials evaluated on the ``n`` multiplier spectra of this dynamical system. The sigma invariants are the symmetric polynomials evaluated on the @@ -5452,30 +5447,31 @@ def sigma_invariants(self, n, formal=False, embedding=None, type='point', are 4 cases: - multipliers and ``n`` periodic points all distinct -- in this case, - we can use Proposition 4.1 of [Hutz2019]_ to compute the sigma invariants. + we can use Proposition 4.1 of [Hutz2019]_ to compute the sigma invariants - - ``n`` periodic points are all distinct, multipliers are repeated -- here we + - ``n`` -- periodic points are all distinct, multipliers are repeated; here we can use Proposition 4.2 of [Hutz2019]_ to compute the sigma invariants. This corresponds to ``chow=True``. - - ``n`` periodic points are repeated, multipliers are all distinct -- to deal + - ``n`` -- periodic points are repeated, multipliers are all distinct; to deal with this case, we deform the map by a formal parameter `k`. The deformation separates the ``n`` periodic points, making them distinct, and we can recover the ``n`` periodic points of the original map by specializing `k` to 0. This corresponds to ``deform=True``. - - ``n`` periodic points are repeated, multipliers are repeated -- here we + - ``n`` -- periodic points are repeated, multipliers are repeated; here we can use both cases 2 and 3 together. This corresponds to ``deform=True`` and ``chow=True``. As we do not want to check which case we are in beforehand, we throw a - ValueError if the computed polynomial does not have the correct degree. + :exc:`ValueError` if the computed polynomial does not have the correct + degree. INPUT: - - ``n`` -- a positive integer, the period + - ``n`` -- positive integer, the period - - ``formal`` -- (default: ``False``) boolean; ``True`` specifies + - ``formal`` -- boolean (default: ``False``); ``True`` specifies to find the values of the elementary symmetric polynomials corresponding to the formal ``n`` multiplier spectra and ``False`` specifies to instead find the values corresponding to the ``n`` @@ -5483,33 +5479,33 @@ def sigma_invariants(self, n, formal=False, embedding=None, type='point', periodic points of period ``n`` - ``embedding`` -- (default: ``None``) must be ``None``, passing an embedding - is no longer supported, see :issue: `32205`. + is no longer supported, see :issue:`32205` - ``type`` -- (default: ``'point'``) string; either ``'point'`` or ``'cycle'`` depending on whether you compute with one multiplier per point or one per cycle. Not implemented for dimension greater than 1. - - ``return polynomial`` -- (default: ``False``) boolean; + - ``return polynomial`` -- boolean (default: ``False``); ``True`` specifies returning the polynomial which generates the sigma invariants, see [Hutz2019]_ for the full definition. The polynomial is always a multivariate polynomial with variables ``w`` and ``t``. - - ``chow`` -- (default: ``False``) boolean; ``True`` specifies + - ``chow`` -- boolean (default: ``False``); ``True`` specifies using the Chow algorithm from [Hutz2019]_ to compute the sigma invariants. While slower, the Chow algorithm does not lose information about multiplicities of the multipliers. In order to accurately compute the sigma polynomial when there is a repeated multiplier, ``chow`` must be ``True``. - - ``deform`` -- (default: ``False``) boolean; ``True`` specifies + - ``deform`` -- boolean (default: ``False``); ``True`` specifies first deforming the map so that all periodic points are distinct and then calculating the sigma invariants. In order to accurately calculate the sigma polynomial when there is a periodic point with multiplicity, ``deform`` must be ``True``. - - ``check`` -- (default: ``True``) boolean; when ``True`` the degree of + - ``check`` -- boolean (default: ``True``); when ``True`` the degree of the sigma polynomial is checked against the expected degree. This is done as the sigma polynomial may drop degree if multiplicities of periodic points or multipliers are not correctly accounted for using ``chow`` or @@ -5520,13 +5516,13 @@ def sigma_invariants(self, n, formal=False, embedding=None, type='point', Setting ``check`` to ``False`` can lead to mathematically incorrect answers. - OUTPUT: a list of elements in the base ring, unless ``return_polynomial`` - is ``True``, in which case a polynomial in ``w`` and ``t`` is returned. - The variable ``t`` is the variable of the characteristic - polynomials of the multipliers. + OUTPUT: list of elements in the base ring, unless ``return_polynomial`` + is ``True``, in which case a polynomial in ``w`` and ``t`` is returned. + The variable ``t`` is the variable of the characteristic + polynomials of the multipliers. - If this map is defined over `\mathbb{P}^N`, where `N > 1`, then - the list is the coefficients of `w` and `t`, in lexographical order with `w > t`. + If this map is defined over `\mathbb{P}^N`, where `N > 1`, then + the list is the coefficients of `w` and `t`, in lexographical order with `w > t`. EXAMPLES:: @@ -5785,7 +5781,7 @@ def sigma_invariants(self, n, formal=False, embedding=None, type='point', else: F = base_ring if isinstance(base_ring, FractionField_generic): - if is_MPolynomialRing(base_ring.ring()) or is_PolynomialRing(base_ring.ring()): + if isinstance(base_ring.ring(), MPolynomialRing_base) or isinstance(base_ring.ring(), PolynomialRing_general): f.normalize_coordinates() f_ring = f.change_ring(base_ring.ring()) X = f_ring.periodic_points(n, minimal=False, formal=formal, return_scheme=True) @@ -5888,7 +5884,7 @@ def sigma_invariants(self, n, formal=False, embedding=None, type='point', base_ring = dom.base_ring() if isinstance(base_ring, FractionField_generic): base_ring = base_ring.ring() - if (is_PolynomialRing(base_ring) or is_MPolynomialRing(base_ring)): + if (isinstance(base_ring, PolynomialRing_general) or isinstance(base_ring, MPolynomialRing_base)): base_ring = base_ring.base_ring() elif base_ring in FunctionFields(): base_ring = base_ring.constant_base_field() @@ -6004,24 +6000,22 @@ def reduced_form(self, **kwds): Implemented by Rebecca Lauren Miller as part of GSOC 2016. Minimal height added by Ben Hutz July 2018. - INPUT: + INPUT: keyword arguments: - keywords: + - ``prec`` -- integer (default: 300); desired precision - - ``prec`` -- (default: 300) integer, desired precision - - - ``return_conjuagtion`` -- (default: ``True``) boolean; return + - ``return_conjuagtion`` -- boolean (default: ``True``); return an element of `SL(2, \ZZ)` - ``error_limit`` -- (default: 0.000001) a real number, sets the error tolerance - - ``smallest_coeffs`` -- (default: ``True``), boolean, whether to find the + - ``smallest_coeffs`` -- boolean (default: ``True``); whether to find the model with smallest coefficients - - ``dynatomic`` -- (default: ``True``) boolean, to use formal periodic points + - ``dynatomic`` -- boolean (default: ``True``); to use formal periodic points - - ``start_n`` -- (default: 1), positive integer, firs period to rry to find + - ``start_n`` -- positive integer (default: 1); first period to try to find appropriate binary form - ``emb`` -- (optional) embedding of based field into CC @@ -6032,10 +6026,10 @@ def reduced_form(self, **kwds): * ``'BM'`` -- Bruin-Molnar algorithm [BM2012]_ * ``'HS'`` -- Hutz-Stoll algorithm [HS2018]_ - - ``check_minimal`` -- (default: ``True``), boolean, whether to check + - ``check_minimal`` -- boolean (default: ``True``); whether to check if this map is a minimal model - - ``smallest_coeffs`` -- (default: ``True``), boolean, whether to find the + - ``smallest_coeffs`` -- boolean (default: ``True``); whether to find the model with smallest coefficients OUTPUT: @@ -6332,7 +6326,7 @@ def _is_preperiodic(self, P, err=0.1, return_period=False): sets the error_bound used in the canonical height computation and ``return_period`` a boolean which - - ``return_period`` -- (default: ``False``) boolean; controls if + - ``return_period`` -- boolean (default: ``False``); controls if the period is returned if the point is preperiodic OUTPUT: @@ -6465,10 +6459,10 @@ def postcritical_set(self, check=True): INPUT: - - ``check`` -- (default: ``True``) boolean; whether to check - if this dynamical system is postcritically finite or not. + - ``check`` -- boolean (default: ``True``); whether to check + if this dynamical system is postcritically finite or not - OUTPUT: The set of postcritical points. + OUTPUT: the set of postcritical points EXAMPLES:: @@ -6535,7 +6529,7 @@ def is_chebyshev(self): r""" Check if ``self`` is a Chebyshev polynomial. - OUTPUT: True if ``self`` is Chebyshev, False otherwise. + OUTPUT: ``True`` if ``self`` is Chebyshev, ``False`` otherwise EXAMPLES:: @@ -6682,7 +6676,7 @@ def is_chebyshev(self): def is_Lattes(self): r""" - Check if ``self`` is a Lattes map + Check if ``self`` is a Lattes map. OUTPUT: ``True`` if ``self`` is Lattes, ``False`` otherwise @@ -6860,13 +6854,13 @@ def lift_to_rational_periodic(self, points_modp, B=None): INPUT: - - ``points_modp`` -- a list or tuple of pairs containing a point + - ``points_modp`` -- list or tuple of pairs containing a point in projective space over `\GF{p}` and the possible period - ``B`` -- (optional) a positive integer; the height bound for a rational preperiodic point - OUTPUT: a list of projective points + OUTPUT: list of projective points EXAMPLES:: @@ -6927,7 +6921,7 @@ def lift_to_rational_periodic(self, points_modp, B=None): while points: q = points.pop() qindex = N - #Find the last non-zero coordinate to use for normalizations + #Find the last nonzero coordinate to use for normalizations while q[0][qindex] % p == 0: qindex -= 1 T = q[0] @@ -7076,9 +7070,7 @@ def all_periodic_points(self, **kwds): See [Hutz2015]_. - INPUT: - - kwds: + INPUT: keyword arguments: - ``R`` -- (default: domain of dynamical system) the base ring over which the periodic points of the dynamical system are found @@ -7105,7 +7097,7 @@ def all_periodic_points(self, **kwds): - ``ncpus`` -- (default: all cpus) number of cpus to use in parallel - OUTPUT: a list of rational points in projective space + OUTPUT: list of rational points in projective space EXAMPLES:: @@ -7171,7 +7163,7 @@ def all_periodic_points(self, **kwds): sage: P. = ProjectiveSpace(QQ, 3) sage: f = DynamicalSystem_projective([x^2 - (3/4)*w^2, y^2 - 3/4*w^2, ....: z^2 - 3/4*w^2, w^2]) - sage: sorted(f.all_periodic_points(algorithm="dynatomic")) # needs sage.rings.function_field + sage: sorted(f.all_periodic_points(algorithm='dynatomic')) # needs sage.rings.function_field [(-1/2 : -1/2 : -1/2 : 1), (-1/2 : -1/2 : 3/2 : 1), (-1/2 : 3/2 : -1/2 : 1), @@ -7199,7 +7191,7 @@ def all_periodic_points(self, **kwds): sage: P. = ProjectiveSpace(QQ, 1) sage: f = DynamicalSystem([x^2 + y^2, x*y]) - sage: f.all_periodic_points(algorithm="banana") + sage: f.all_periodic_points(algorithm='banana') Traceback (most recent call last): ... ValueError: algorithm must be 'dynatomic' or 'lifting' @@ -7337,9 +7329,9 @@ def all_rational_preimages(self, points): INPUT: - - ``points`` -- a list of rational points in the domain of this map + - ``points`` -- list of rational points in the domain of this map - OUTPUT: a list of rational points in the domain of this map + OUTPUT: list of rational points in the domain of this map EXAMPLES:: @@ -7437,9 +7429,7 @@ def all_preperiodic_points(self, **kwds): - Determines the rational preperiodic points from the rational periodic points by determining rational preimages. - INPUT: - - kwds: + INPUT: keyword arguments: - ``R`` -- (default: domain of dynamical system) the base ring over which the periodic points of the dynamical system are found @@ -7467,7 +7457,7 @@ def all_preperiodic_points(self, **kwds): current options are `dynatomic` and `lifting`; defaults to solving the dynatomic for low periods and degrees and lifts for everything else - OUTPUT: a list of rational points in projective space + OUTPUT: list of rational points in projective space EXAMPLES:: @@ -7607,9 +7597,7 @@ def rational_preperiodic_graph(self, **kwds): - Determines the rational preperiodic points from the rational periodic points by determining rational preimages. - INPUT: - - kwds: + INPUT: keyword arguments: - ``prime_bound`` -- (default: ``[1, 20]``) a pair (list or tuple) of positive integers that represent the limits of primes to use @@ -7670,7 +7658,7 @@ def rational_preperiodic_graph(self, **kwds): def connected_rational_component(self, P, n=0): r""" - Computes the connected component of a rational preperiodic + Compute the connected component of a rational preperiodic point ``P`` by this dynamical system. Will work for non-preperiodic points if ``n`` is positive. @@ -7683,9 +7671,7 @@ def connected_rational_component(self, P, n=0): - ``n`` -- (default: 0) integer; maximum distance from ``P`` to branch out; a value of 0 indicates no bound - OUTPUT: - - A list of points connected to ``P`` up to the specified distance. + OUTPUT: list of points connected to ``P`` up to the specified distance EXAMPLES:: @@ -7729,7 +7715,6 @@ def connected_rational_component(self, P, n=0): (-1/2 : 1/2 : 1), (1/2 : -1/2 : 1), (1/2 : 1/2 : 1)] - """ points = [[],[]] # list of points and a list of their corresponding levels points[0].append(P) @@ -7802,12 +7787,10 @@ def conjugating_set(self, other, R=None, num_cpus=2): - ``R`` -- a field or embedding - - ``num_cpus`` -- (default: 2) the number of threads to run in parallel. - Increasing ``num_cpus`` can potentially greatly speed up this function. + - ``num_cpus`` -- (default: 2) the number of threads to run in parallel; + increasing ``num_cpus`` can potentially greatly speed up this function - OUTPUT: - - Set of conjugating `n+1` by `n+1` matrices. + OUTPUT: set of conjugating `n+1` by `n+1` matrices AUTHORS: @@ -8057,8 +8040,8 @@ def is_conjugate(self, other, R=None, num_cpus=2): - ``R`` -- a field or embedding - - ``num_cpus`` -- (default: 2) the number of threads to run in parallel. - Increasing ``num_cpus`` can potentially greatly speed up this function. + - ``num_cpus`` -- (default: 2) the number of threads to run in parallel; + increasing ``num_cpus`` can potentially greatly speed up this function OUTPUT: boolean @@ -8372,7 +8355,7 @@ def normal_form(self, return_conjugation=False): INPUT: - - ``return_conjugation`` -- (default: ``False``) boolean; if ``True``, + - ``return_conjugation`` -- boolean (default: ``False``); if ``True``, then return the conjugation element of PGL along with the embedding into the new field @@ -8473,7 +8456,7 @@ def normal_form(self, return_conjugation=False): #we find one and not go all the way to the splitting field i = 0 if G.degree() != 0: - if is_MPolynomialRing(G.parent()): + if isinstance(G.parent(), MPolynomialRing_base): G = G.polynomial(G.variable(0)) else: #no other fixed points @@ -8589,12 +8572,10 @@ def potential_good_reduction(self, prime, return_conjugation=False): points of the map, or a prime number in `\QQ` if the field of definition of the fixed points is `\QQ`. - - ``return_conjugation`` -- (default: ``False``) if set to ``True``, + - ``return_conjugation`` -- boolean (default: ``False``); if set to ``True``, the `PGL_2` map used to achieve good reduction will be returned - OUTPUT: - - A tuple: + OUTPUT: a tuple: - The first element is: - ``False`` if this dynamical system does not have potential good reduction. @@ -8694,7 +8675,6 @@ def potential_good_reduction(self, prime, return_conjugation=False): sage: prime = system.field_of_definition_periodic(1).prime_above(3) # needs sage.rings.number_field sage: system.potential_good_reduction(prime) # needs sage.rings.number_field (False, None) - """ if self.domain().base_ring() not in NumberFields(): raise ValueError('dynamical system must be defined over number field') @@ -8782,7 +8762,7 @@ def reduce_base_field(self): the base ring is a number field, QQbar, a finite field, or algebraic closure of a finite field. - OUTPUT: A dynamical system + OUTPUT: a dynamical system EXAMPLES:: @@ -8844,13 +8824,13 @@ def is_newton(self, return_conjugation=False): INPUT: - - ``return_conjugation`` -- (default: ``False``) if the map is Newton + - ``return_conjugation`` -- boolean (default: ``False``); if the map is Newton and ``True``, then return the conjugation that moves this map to the above form OUTPUT: - A Boolean. If ``return_conjugation`` is ``True``, then this also + A boolean. If ``return_conjugation`` is ``True``, then this also returns the conjugation as a matrix if ``self`` is Newton or ``None`` otherwise. @@ -8979,7 +8959,7 @@ def _is_preperiodic(self, P, **kwds): keywords: - - ``return_period`` -- (default: ``False``) boolean; controls if + - ``return_period`` -- boolean (default: ``False``); controls if the period is returned OUTPUT: the boolean ``True`` or a tuple ``(m,n)`` of integers @@ -9150,7 +9130,7 @@ def possible_periods(self, return_points=False): INPUT: - - ``return_points`` -- (default: ``False``) boolean; if ``True``, + - ``return_points`` -- boolean (default: ``False``); if ``True``, then return the points as well as the possible periods OUTPUT: @@ -9205,22 +9185,22 @@ def automorphism_group(self, **kwds): The following keywords are used when the dimension of the domain is greater than 1: - - ``num_cpus`` -- (default: 2) the number of threads to use. Setting to a - larger number can greatly speed up this function. + - ``num_cpus`` -- (default: 2) the number of threads to use; setting to a + larger number can greatly speed up this function The following keywords are used when the dimension of the domain is 1: - - ``absolute`` -- (default: ``False``) boolean; if ``True``, then + - ``absolute`` -- boolean (default: ``False``); if ``True``, then return the absolute automorphism group and a field of definition - - ``iso_type`` -- (default: ``False``) boolean; if ``True``, then + - ``iso_type`` -- boolean (default: ``False``); if ``True``, then return the isomorphism type of the automorphism group - - ``return_functions`` -- (default: ``False``) boolean; ``True`` + - ``return_functions`` -- boolean (default: ``False``); ``True`` returns elements as linear fractional transformations and ``False`` returns elements as `PGL2` matrices - OUTPUT: a list of elements of the automorphism group + OUTPUT: list of elements of the automorphism group AUTHORS: @@ -9323,14 +9303,12 @@ def all_periodic_points(self, **kwds): r""" Return a list of all periodic points over a finite field. - INPUT: - - keywords: + INPUT: keyword arguments: - ``R`` -- (default: base ring of dynamical system) the base ring over which the periodic points of the dynamical system are found - OUTPUT: a list of elements which are periodic + OUTPUT: list of elements which are periodic EXAMPLES:: diff --git a/src/sage/dynamics/arithmetic_dynamics/projective_ds_helper.pyx b/src/sage/dynamics/arithmetic_dynamics/projective_ds_helper.pyx index ea48d20c9b6..fb3b268b0df 100644 --- a/src/sage/dynamics/arithmetic_dynamics/projective_ds_helper.pyx +++ b/src/sage/dynamics/arithmetic_dynamics/projective_ds_helper.pyx @@ -34,7 +34,7 @@ cpdef _fast_possible_periods(self, return_points=False): INPUT: - - ``return_points`` -- (default: ``False``) boolean; if ``True``, then + - ``return_points`` -- boolean (default: ``False``); if ``True``, then return the points as well as the possible periods OUTPUT: @@ -187,7 +187,6 @@ cpdef int _hash(list Point, int prime) noexcept: sage: from sage.dynamics.arithmetic_dynamics.projective_ds_helper import _hash sage: _hash([1, 2, 1], 3) 16 - """ cdef int hash_q cdef int coefficient diff --git a/src/sage/dynamics/arithmetic_dynamics/wehlerK3.py b/src/sage/dynamics/arithmetic_dynamics/wehlerK3.py index 21d107dee4c..3ef9877e782 100644 --- a/src/sage/dynamics/arithmetic_dynamics/wehlerK3.py +++ b/src/sage/dynamics/arithmetic_dynamics/wehlerK3.py @@ -56,10 +56,12 @@ def WehlerK3Surface(polys): r""" - Defines a K3 Surface over `\mathbb{P}^2 \times \mathbb{P}^2` defined as + Define a K3 Surface over `\mathbb{P}^2 \times \mathbb{P}^2` defined as the intersection of a bilinear and biquadratic form. [Weh1998]_ - INPUT: Bilinear and biquadratic polynomials as a tuple or list + INPUT: + + - ``polys`` -- bilinear and biquadratic polynomials as a tuple or list OUTPUT: :class:`WehlerK3Surface_ring` @@ -92,7 +94,9 @@ def random_WehlerK3Surface(PP): Produces a random K3 surface in `\mathbb{P}^2 \times \mathbb{P}^2` defined as the intersection of a bilinear and biquadratic form. [Weh1998]_ - INPUT: Projective space cartesian product + INPUT: + + - ``PP`` -- projective space cartesian product OUTPUT: :class:`WehlerK3Surface_ring` @@ -163,7 +167,9 @@ def change_ring(self, R): r""" Changes the base ring on which the Wehler K3 Surface is defined. - INPUT: ``R`` -- ring + INPUT: + + - ``R`` -- ring OUTPUT: K3 Surface defined over input ring @@ -188,9 +194,12 @@ def _check_satisfies_equations(self, P): r""" Function checks to see if point ``P`` lies on the K3 Surface. - INPUT: ``P`` -- point in `\mathbb{P}^2 \times \mathbb{P}^2` + INPUT: + + - ``P`` -- point in `\mathbb{P}^2 \times \mathbb{P}^2` - OUTPUT: AttributeError True if the point is not on the surface + OUTPUT: ``True`` if the point is not on the surface; :exc:`AttributeError` + otherwise EXAMPLES:: @@ -242,9 +251,9 @@ def _Lcoeff(self, component, i): INPUT: - - ``component`` -- Integer: 0 or 1 + - ``component`` -- integer; 0 or 1 - - ``i`` -- Integer: 0, 1 or 2 + - ``i`` -- integer; 0, 1 or 2 OUTPUT: polynomial in terms of either y (Component = 0) or x (Component = 1) @@ -290,11 +299,11 @@ def _Qcoeff(self, component, i, j): INPUT: - - ``component`` -- Integer: 0 or 1 + - ``component`` -- integer; 0 or 1 - - ``i`` -- Integer: 0, 1 or 2 + - ``i`` -- integer; 0, 1 or 2 - - ``j`` -- Integer: 0, 1 or 2 + - ``j`` -- integer; 0, 1 or 2 OUTPUT: polynomial in terms of either y (Component = 0) or x (Component = 1) @@ -340,9 +349,9 @@ def Gpoly(self, component, k): INPUT: - - ``component`` -- Integer: 0 or 1 + - ``component`` -- integer; 0 or 1 - - ``k`` -- Integer: 0, 1 or 2 + - ``k`` -- integer; 0, 1 or 2 OUTPUT: polynomial in terms of either `y` (``component=0``) or `x` (``component=1``) @@ -384,11 +393,11 @@ def Hpoly(self, component, i, j): INPUT: - - ``component`` -- Integer: 0 or 1 + - ``component`` -- integer; 0 or 1 - - ``i`` -- Integer: 0, 1 or 2 + - ``i`` -- integer; 0, 1 or 2 - - ``j`` -- Integer: 0, 1 or 2 + - ``j`` -- integer; 0, 1 or 2 OUTPUT: polynomial in terms of either y (``component=0``) or x (``component=1``) @@ -432,9 +441,9 @@ def Lxa(self, a): INPUT: - - ``a`` -- Point in `\mathbb{P}^2` + - ``a`` -- point in `\mathbb{P}^2` - OUTPUT: A polynomial representing the fiber + OUTPUT: a polynomial representing the fiber EXAMPLES:: @@ -470,9 +479,11 @@ def Qxa(self, a): Notation and definition from: [CS1996]_ - INPUT: ``a`` -- Point in `\mathbb{P}^2` + INPUT: + + - ``a`` -- point in `\mathbb{P}^2` - OUTPUT: A polynomial representing the fiber + OUTPUT: a polynomial representing the fiber EXAMPLES:: @@ -509,9 +520,9 @@ def Sxa(self, a): INPUT: - - ``a`` -- Point in `\mathbb{P}^2` + - ``a`` -- point in `\mathbb{P}^2` - OUTPUT: A subscheme representing the fiber + OUTPUT: a subscheme representing the fiber EXAMPLES:: @@ -545,9 +556,11 @@ def Lyb(self, b): Notation and definition from: [CS1996]_ - INPUT: ``b`` -- Point in projective space + INPUT: + + - ``b`` -- point in projective space - OUTPUT: A polynomial representing the fiber + OUTPUT: a polynomial representing the fiber EXAMPLES:: @@ -586,9 +599,9 @@ def Qyb(self, b): INPUT: - - ``b`` -- Point in projective space + - ``b`` -- point in projective space - OUTPUT: A polynomial representing the fiber + OUTPUT: a polynomial representing the fiber EXAMPLES:: @@ -624,9 +637,9 @@ def Syb(self, b): INPUT: - - ``b`` -- Point in `\mathbb{P}^2` + - ``b`` -- point in `\mathbb{P}^2` - OUTPUT: A subscheme representing the fiber + OUTPUT: a subscheme representing the fiber EXAMPLES:: @@ -642,7 +655,6 @@ def Syb(self, b): Closed subscheme of Projective Space of dimension 2 over Rational Field defined by: x0, x0^2 + 3*x0*x1 + x1^2 - """ if b not in self.ambient_space()[1]: raise TypeError("point must be in projective space of dimension 2") @@ -661,9 +673,11 @@ def Ramification_poly(self, i): The roots of this polynomial will either be degenerate fibers or fixed points of the involutions `\sigma_x` or `\sigma_y` for more information, see [CS1996]_. - INPUT: ``i`` -- Integer, either 0 (polynomial in y) or 1 (polynomial in x) + INPUT: + + - ``i`` -- integer; either 0 (polynomial in y) or 1 (polynomial in x) - OUTPUT: Polynomial in the coordinate ring of the ambient space + OUTPUT: polynomial in the coordinate ring of the ambient space EXAMPLES:: @@ -697,8 +711,8 @@ def Ramification_poly(self, i): @cached_method def is_degenerate(self): r""" - Function will return True if there is a fiber (over the algebraic closure of the - base ring) of dimension greater than 0 and False otherwise. + Function will return ``True`` if there is a fiber (over the algebraic closure of the + base ring) of dimension greater than 0 and ``False`` otherwise. OUTPUT: boolean @@ -776,7 +790,7 @@ def degenerate_fibers(self): This function finds the common solution through elimination via Groebner bases by using the .variety() function on the three affine charts in each component. - OUTPUT: The output is a list of lists where the elements of lists are + OUTPUT: the output is a list of lists where the elements of lists are points in the appropriate projective space. The first list is the points whose pullback by the projection to the first component (projective space) is dimension greater than 0. @@ -884,13 +898,15 @@ def degenerate_fibers(self): @cached_method def degenerate_primes(self, check=True): r""" - Determine which primes `p` self has degenerate fibers over `\GF{p}`. + Determine which primes `p` ``self`` has degenerate fibers over `\GF{p}`. If ``check`` is ``False``, then may return primes that do not have degenerate fibers. Raises an error if the surface is degenerate. Works only for ``ZZ`` or ``QQ``. - INPUT: ``check`` -- (default: ``True``) boolean, whether the primes are verified + INPUT: + + - ``check`` -- boolean (default: ``True``); whether the primes are verified ALGORITHM: @@ -905,7 +921,7 @@ def degenerate_primes(self, check=True): is what is checked. The lcm of the coefficients of the monomials `x_i` in a Groebner basis is computed. This may return extra primes. - OUTPUT: List of primes. + OUTPUT: list of primes EXAMPLES:: @@ -996,7 +1012,7 @@ def is_smooth(self): Checks to confirm that all of the 2x2 minors of the Jacobian generated from the biquadratic and bilinear forms have no common vanishing points. - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -1057,11 +1073,11 @@ def sigmaX(self, P, **kwds): kwds: - - ``check`` -- (default: ``True``) boolean checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``True``) boolean normalizes the point + - ``normalize`` -- boolean (default: ``True``); normalizes the point - OUTPUT: A point on the K3 surface + OUTPUT: a point on the K3 surface EXAMPLES:: @@ -1174,7 +1190,7 @@ def sigmaX(self, P, **kwds): -phi(self.Hpoly(1, 1, 2))] maxexp = [] - #Find highest exponent that we can divide out by to get a non zero answer + #Find highest exponent that we can divide out by to get a nonzero answer for i in range(2,len(T)): e = 0 while (T[i]/t**e).subs({w1:t1}) == 0: @@ -1304,11 +1320,11 @@ def sigmaY(self,P, **kwds): kwds: - - ``check`` -- (default: ``True``) boolean checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``True``) boolean normalizes the point + - ``normalize`` -- boolean (default: ``True``); normalizes the point - OUTPUT: A point on the K3 surface + OUTPUT: a point on the K3 surface EXAMPLES:: @@ -1419,7 +1435,7 @@ def sigmaY(self,P, **kwds): -phi(self.Hpoly(0, 1, 2))] maxexp = [] - #Find highest exponent that we can divide out by to get a non zero answer + #Find highest exponent that we can divide out by to get a nonzero answer for i in range(2, len(T)): e = 0 while (T[i]/t**e).subs({w1:t1}) == 0: @@ -1536,15 +1552,15 @@ def phi(self, a, **kwds): INPUT: - - ``a`` -- Point in `\mathbb{P}^2 \times \mathbb{P}^2` + - ``a`` -- point in `\mathbb{P}^2 \times \mathbb{P}^2` kwds: - - ``check`` -- (default: ``True``) boolean checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``True``) boolean normalizes the point + - ``normalize`` -- boolean (default: ``True``); normalizes the point - OUTPUT: A point on this surface + OUTPUT: a point on this surface EXAMPLES:: @@ -1576,15 +1592,15 @@ def psi(self,a, **kwds): INPUT: - - ``a`` -- Point in `\mathbb{P}^2 \times \mathbb{P}^2` + - ``a`` -- point in `\mathbb{P}^2 \times \mathbb{P}^2` kwds: - - ``check`` -- (default: ``True``) boolean checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``True``) boolean normalizes the point + - ``normalize`` -- boolean (default: ``True``); normalizes the point - OUTPUT: A point on this surface + OUTPUT: a point on this surface EXAMPLES:: @@ -1619,16 +1635,17 @@ def lambda_plus(self, P, v, N, m, n, prec=100): - ``P`` -- a surface point - - ``N`` -- positive integer. number of terms of the series to use + - ``N`` -- positive integer; number of terms of the series to use - - ``v`` -- non-negative integer. a place, use v = 0 for the Archimedean place + - ``v`` -- nonnegative integer; a place, use v = 0 for the Archimedean place - - ``m``, ``n`` -- positive integers; we compute the local height for the divisor `E_{mn}^{+}`. - These must be indices of non-zero coordinates of the point ``P``. + - ``m``, ``n`` -- positive integers; we compute the local height for + the divisor `E_{mn}^{+}`. These must be indices of nonzero + coordinates of the point ``P`` - - ``prec`` -- (default: 100) float point or p-adic precision + - ``prec`` -- (default: 100) float point or `p`-adic precision - OUTPUT: A real number + OUTPUT: a real number EXAMPLES:: @@ -1720,15 +1737,15 @@ def lambda_minus(self, P, v, N, m, n, prec=100): - ``N`` -- positive integer. number of terms of the series to use - - ``v`` -- non-negative integer. a place, use v = 0 for the Archimedean place + - ``v`` -- nonnegative integer. a place, use v = 0 for the Archimedean place - ``m``, ``n`` -- positive integers; we compute the local height for - the divisor `E_{mn}^{+}`. These must be indices of non-zero + the divisor `E_{mn}^{+}`. These must be indices of nonzero coordinates of the point ``P``. - - ``prec`` -- (default: 100) float point or p-adic precision + - ``prec`` -- (default: 100) float point or `p`-adic precision - OUTPUT: A real number + OUTPUT: a real number EXAMPLES:: @@ -1817,9 +1834,9 @@ def canonical_height_plus(self, P, N, badprimes=None, prec=100): - ``badprimes`` -- (optional) list of integer primes (where the surface is degenerate) - - ``prec`` -- (default: 100) float point or p-adic precision + - ``prec`` -- (default: 100) float point or `p`-adic precision - OUTPUT: A real number + OUTPUT: a real number EXAMPLES:: @@ -1881,9 +1898,9 @@ def canonical_height_minus(self, P, N, badprimes=None, prec=100): - ``badprimes`` -- (optional) list of integer primes (where the surface is degenerate) - - ``prec`` -- (default: 100) float point or p-adic precision + - ``prec`` -- (default: 100) float point or `p`-adic precision - OUTPUT: A real number + OUTPUT: a real number EXAMPLES:: @@ -1943,9 +1960,9 @@ def canonical_height(self, P, N, badprimes=None, prec=100): - ``badprimes`` -- (optional) list of integer primes (where the surface is degenerate) - - ``prec`` -- (default: 100) float point or p-adic precision + - ``prec`` -- (default: 100) float point or `p`-adic precision - OUTPUT: A real number + OUTPUT: a real number EXAMPLES:: @@ -1991,7 +2008,7 @@ def fiber(self, p, component): - ``p`` -- a point in `\mathbb{P}^2` - OUTPUT: The corresponding fiber (as a list) + OUTPUT: the corresponding fiber (as a list) EXAMPLES:: @@ -2159,22 +2176,23 @@ def fiber(self, p, component): def nth_iterate_phi(self, P, n, **kwds): r""" - Computes the ``n``-th iterate for the phi function. + Compute the `n`-th iterate for the phi function. INPUT: - ``P`` -- a point in `\mathbb{P}^2 \times \mathbb{P}^2` - - ``n`` -- an integer + - ``n`` -- integer kwds: - - ``check`` -- (default: ``True``) boolean checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is + on the surface - - ``normalize`` -- (default: ``False``) boolean normalizes the point + - ``normalize`` -- boolean (default: ``False``); normalizes the point - OUTPUT: The nth iterate of the point given the phi function (if ``n`` is positive), or the - psi function (if ``n`` is negative) + OUTPUT: the `n`-th iterate of the point given the phi function (if `n` + is positive), or the psi function (if `n` is negative) EXAMPLES:: @@ -2224,22 +2242,22 @@ def nth_iterate_phi(self, P, n, **kwds): def nth_iterate_psi(self, P, n, **kwds): r""" - Computes the ``n``-th iterate for the psi function. + Compute the `n`-th iterate for the psi function. INPUT: - ``P`` -- a point in `\mathbb{P}^2 \times \mathbb{P}^2` - - ``n`` -- an integer + - ``n`` -- integer kwds: - - ``check`` -- (default: ``True``) boolean, checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``False``) boolean, normalizes the point + - ``normalize`` -- boolean (default: ``False``); normalizes the point - OUTPUT: The nth iterate of the point given the psi function (if ``n`` is positive), - or the phi function (if ``n`` is negative) + OUTPUT: the `n`-th iterate of the point given the psi function (if `n` is positive), + or the phi function (if `n` is negative) EXAMPLES:: @@ -2285,17 +2303,17 @@ def orbit_phi(self, P, N, **kwds): INPUT: - - ``P`` -- Point on the K3 surface + - ``P`` -- point on the K3 surface - - ``N`` -- a non-negative integer or list or tuple of two non-negative integers + - ``N`` -- nonnegative integer or list or tuple of two nonnegative integers kwds: - - ``check`` -- (default: ``True``) boolean, checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``False``) boolean, normalizes the point + - ``normalize`` -- boolean (default: ``False``); normalizes the point - OUTPUT: List of points in the orbit + OUTPUT: list of points in the orbit EXAMPLES:: @@ -2323,7 +2341,7 @@ def orbit_phi(self, P, N, **kwds): except TypeError: raise TypeError("orbit bounds must be integers") if N[0] < 0 or N[1] < 0: - raise TypeError("orbit bounds must be non-negative") + raise TypeError("orbit bounds must be nonnegative") if N[0] > N[1]: return [] Q = self(copy(P)) @@ -2346,15 +2364,15 @@ def orbit_psi(self, P, N, **kwds): - ``P`` -- a point on the K3 surface - - ``N`` -- a non-negative integer or list or tuple of two non-negative integers + - ``N`` -- nonnegative integer or list or tuple of two nonnegative integers kwds: - - ``check`` -- (default: ``True``) boolean, checks to see if point is on the surface + - ``check`` -- boolean (default: ``True``); checks to see if point is on the surface - - ``normalize`` -- (default: ``False``) boolean, normalizes the point + - ``normalize`` -- boolean (default: ``False``); normalizes the point - OUTPUT: a list of points in the orbit + OUTPUT: list of points in the orbit EXAMPLES:: @@ -2380,7 +2398,7 @@ def orbit_psi(self, P, N, **kwds): except TypeError: raise TypeError("orbit bounds must be integers") if N[0] < 0 or N[1] < 0: - raise TypeError("orbit bounds must be non-negative") + raise TypeError("orbit bounds must be nonnegative") if N[0] > N[1]: return [] Q = self(copy(P)) @@ -2400,7 +2418,7 @@ def is_isomorphic(self, right): - ``right`` -- the K3 surface to compare to the original - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -2439,7 +2457,7 @@ def is_symmetric_orbit(self,orbit): - ``orbit`` -- a periodic cycle of either psi or phi - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -2493,7 +2511,7 @@ def cardinality( self): Enumerate points over `\mathbb{P}^2`, and then count the points on the fiber of each of those points. - OUTPUT: Integer -- total number of points on the surface + OUTPUT: integer; total number of points on the surface EXAMPLES:: diff --git a/src/sage/dynamics/cellular_automata/elementary.py b/src/sage/dynamics/cellular_automata/elementary.py index 77d5b705fcb..51f959ed237 100644 --- a/src/sage/dynamics/cellular_automata/elementary.py +++ b/src/sage/dynamics/cellular_automata/elementary.py @@ -51,7 +51,7 @@ class ElementaryCellularAutomata(SageObject): INPUT: - - ``rule`` -- an integer between 0 and 255 + - ``rule`` -- integer between 0 and 255 - ``width`` -- (optional) the width of the ECA - ``initial_state`` -- (optional) the initial state given as a list of ``0`` and ``1`` diff --git a/src/sage/dynamics/cellular_automata/glca.py b/src/sage/dynamics/cellular_automata/glca.py index 8c896a981e9..dbd7bdc6fc3 100644 --- a/src/sage/dynamics/cellular_automata/glca.py +++ b/src/sage/dynamics/cellular_automata/glca.py @@ -34,7 +34,7 @@ class GraftalLaceCellularAutomata(SageObject): INPUT: - - ``rule`` -- a list of length 8 with integer entries `0 \leq x < 8` + - ``rule`` -- list of length 8 with integer entries `0 \leq x < 8` EXAMPLES:: @@ -105,7 +105,6 @@ def __init__(self, rule): Traceback (most recent call last): ... ValueError: invalid rule - """ if len(rule) != 8 or any(x not in range(8) for x in rule): raise ValueError("invalid rule") diff --git a/src/sage/dynamics/cellular_automata/solitons.py b/src/sage/dynamics/cellular_automata/solitons.py index 72ec9ed0104..8f5c3110533 100644 --- a/src/sage/dynamics/cellular_automata/solitons.py +++ b/src/sage/dynamics/cellular_automata/solitons.py @@ -755,7 +755,7 @@ def print_state(self, num=None, vacuum_letter='.', remove_trailing_vacuums=False - ``num`` -- (default: the current state) the state to print - ``vacuum_letter`` -- (default: ``'.'``) the letter to print for the vacuum - - ``remove_trailing_vacuums`` -- (default: ``False``) if ``True`` + - ``remove_trailing_vacuums`` -- boolean (default: ``False``); if ``True`` then this does not print the vacuum letters at the right end of the state @@ -964,9 +964,9 @@ def latex_states(self, num=None, as_array=True, box_width='5pt'): INPUT: - ``num`` -- the number of states - - ``as_array`` (default: ``True``) if ``True``, then the states are - placed inside of an array; if ``False``, then the states are - given as a word + - ``as_array`` -- boolean (default: ``True``); if ``True``, then the + states are placed inside of an array; if ``False``, then the states + are given as a word - ``box_width`` -- (default: ``'5pt'``) the width of the ``.`` used to represent the vacuum state when ``as_array`` is ``True`` diff --git a/src/sage/dynamics/complex_dynamics/mandel_julia.py b/src/sage/dynamics/complex_dynamics/mandel_julia.py index 8ceb38d0cec..87e98ec084d 100644 --- a/src/sage/dynamics/complex_dynamics/mandel_julia.py +++ b/src/sage/dynamics/complex_dynamics/mandel_julia.py @@ -71,42 +71,40 @@ def mandelbrot_plot(f=None, **kwds): INPUT: - - ``f`` -- map (default: ``z^2 + c``), polynomial family used to - plot the Mandelbrot set. + - ``f`` -- map (default: ``z^2 + c``); polynomial family used to + plot the Mandelbrot set - - ``parameter`` -- variable (default: ``c``), parameter variable - used to plot the Mandelbrot set. + - ``parameter`` -- variable (default: ``c``); parameter variable + used to plot the Mandelbrot set - - ``x_center`` -- double (default: ``-1.0``), Real part of center - point. + - ``x_center`` -- double (default: ``-1.0``); Real part of center + point - - ``y_center`` -- double (default: ``0.0``), Imaginary part of - center point. + - ``y_center`` -- double (default: ``0.0``); Imaginary part of + center point - - ``image_width`` -- double (default: ``4.0``), width of image - in the complex plane. + - ``image_width`` -- double (default: ``4.0``); width of image + in the complex plane - - ``max_iteration`` -- long (default: ``500``), maximum number of - iterations the map ``f_c(z)``. + - ``max_iteration`` -- long (default: ``500``); maximum number of + iterations the map ``f_c(z)`` - - ``pixel_count`` -- long (default: ``500``), side length of - image in number of pixels. + - ``pixel_count`` -- long (default: ``500``); side length of + image in number of pixels - - ``base_color`` -- RGB color (default: ``[40, 40, 40]``) color - used to determine the coloring of set. + - ``base_color`` -- RGB color (default: ``[40, 40, 40]``); color + used to determine the coloring of set - - ``level_sep`` -- long (default: 1) number of iterations - between each color level. + - ``level_sep`` -- long (default: 1); number of iterations + between each color level - - ``number_of_colors`` -- long (default: 30) number of colors - used to plot image. + - ``number_of_colors`` -- long (default: 30); number of colors + used to plot image - - ``interact`` -- boolean (default: ``False``), controls whether - plot will have interactive functionality. + - ``interact`` -- boolean (default: ``False``); controls whether + plot will have interactive functionality - OUTPUT: - - 24-bit RGB image of the Mandelbrot set in the complex plane. + OUTPUT: 24-bit RGB image of the Mandelbrot set in the complex plane EXAMPLES: @@ -211,11 +209,11 @@ def mandelbrot_plot(f=None, **kwds): y_center=FloatSlider(min=-1.0, max=1.0, step=EPS, value=y_center, description="Imag center"), image_width=FloatSlider(min=EPS, max=4.0, step=EPS, - value=image_width, description="Width"), + value=image_width, description='Width'), max_iteration=IntSlider(min=0, max=1000, - value=max_iteration, description="Iterations"), + value=max_iteration, description='Iterations'), pixel_count=IntSlider(min=10, max=1000, - value=pixel_count, description="Pixels"), + value=pixel_count, description='Pixels'), level_sep=IntSlider(min=1, max=20, value=level_sep, description="Color sep"), color_num=IntSlider(min=1, max=100, @@ -301,36 +299,34 @@ def external_ray(theta, **kwds): INPUT: - - ``theta`` -- double or list of doubles, angles between 0 and 1 inclusive. + - ``theta`` -- double or list of doubles, angles between 0 and 1 inclusive kwds: - - ``image`` -- 24-bit RGB image (default: None) user specified - image of Mandelbrot set. + - ``image`` -- 24-bit RGB image (default: ``None``); user specified + image of Mandelbrot set - - ``D`` -- long (default: ``25``) depth of the approximation. + - ``D`` -- long (default: ``25``); depth of the approximation. As ``D`` increases, the external ray gets closer to the boundary of the Mandelbrot set. If the ray doesn't reach the boundary of the Mandelbrot set, increase ``D``. - - ``S`` -- long (default: ``10``) sharpness of the approximation. + - ``S`` -- long (default: ``10``); sharpness of the approximation. Adjusts the number of points used to approximate the external ray (number of points is equal to ``S*D``). If ray looks jagged, increase ``S``. - - ``R`` -- long (default: ``100``) radial parameter. If ``R`` is + - ``R`` -- long (default: ``100``); radial parameter. If ``R`` is large, the external ray reaches sufficiently close to infinity. If ``R`` is too small, Newton's method may not converge to the correct ray. - - ``prec`` -- long (default: ``300``) specifies the bits of + - ``prec`` -- long (default: ``300``); specifies the bits of precision used by the Complex Field when using Newton's method to compute - points on the external ray. + points on the external ray - ``ray_color`` -- RGB color (default: ``[255, 255, 255]``) color - of the external ray(s). - - OUTPUT: + of the external ray(s) - 24-bit RGB image of external ray(s) on the Mandelbrot set. + OUTPUT: 24-bit RGB image of external ray(s) on the Mandelbrot set EXAMPLES:: @@ -444,9 +440,7 @@ def kneading_sequence(theta): - ``theta`` -- a rational number with odd denominator - OUTPUT: - - a string representing the kneading sequence of theta in RR/ZZ + OUTPUT: string representing the kneading sequence of theta in RR/ZZ REFERENCES: @@ -529,48 +523,46 @@ def julia_plot(f=None, **kwds): INPUT: - - ``f`` -- input polynomial (default: ``z^2 - 1``). + - ``f`` -- input polynomial (default: ``z^2 - 1``) - - ``period`` -- list (default: ``None``), returns the Julia set - for a random `c` value with the given (formal) cycle structure. + - ``period`` -- list (default: ``None``); returns the Julia set + for a random `c` value with the given (formal) cycle structure - - ``mandelbrot`` -- boolean (default: ``True``), when set to + - ``mandelbrot`` -- boolean (default: ``True``); when set to ``True``, an image of the Mandelbrot set is appended to the right of the - Julia set. - - - ``point_color`` -- RGB color (default: ``'tomato'``), - color of the point `c` in the Mandelbrot set (any valid input for Color). + Julia set - - ``x_center`` -- double (default: ``-1.0``), Real part - of center point. + - ``point_color`` -- RGB color (default: ``'tomato'``); + color of the point `c` in the Mandelbrot set (any valid input for Color) - - ``y_center`` -- double (default: ``0.0``), Imaginary part - of center point. + - ``x_center`` -- double (default: ``-1.0``); real part + of center point - - ``image_width`` -- double (default: ``4.0``), width of image - in the complex plane. + - ``y_center`` -- double (default: ``0.0``); imaginary part + of center point - - ``max_iteration`` -- long (default: ``500``), maximum number - of iterations the map `f(z)`. + - ``image_width`` -- double (default: ``4.0``); width of image + in the complex plane - - ``pixel_count`` -- long (default: ``500``), side length of - image in number of pixels. + - ``max_iteration`` -- long (default: ``500``); maximum number + of iterations the map `f(z)` - - ``base_color`` -- hex color (default: ``'steelblue'``), color - used to determine the coloring of set (any valid input for Color). + - ``pixel_count`` -- long (default: ``500``); side length of + image in number of pixels - - ``level_sep`` -- long (default: 1), number of iterations - between each color level. + - ``base_color`` -- hex color (default: ``'steelblue'``); color + used to determine the coloring of set (any valid input for Color) - - ``number_of_colors`` -- long (default: 30), number of colors - used to plot image. + - ``level_sep`` -- long (default: 1); number of iterations + between each color level - - ``interact`` -- boolean (default: ``False``), controls whether - plot will have interactive functionality. + - ``number_of_colors`` -- long (default: 30); number of colors + used to plot image - OUTPUT: + - ``interact`` -- boolean (default: ``False``); controls whether + plot will have interactive functionality - 24-bit RGB image of the Julia set in the complex plane. + OUTPUT: 24-bit RGB image of the Julia set in the complex plane .. TODO:: @@ -738,11 +730,11 @@ def julia_plot(f=None, **kwds): y_center=FloatSlider(min=-1.0, max=1.0, step=EPS, value=y_center, description="Imag center"), image_width=FloatSlider(min=EPS, max=4.0, step=EPS, - value=image_width, description="Width"), + value=image_width, description='Width'), max_iteration=IntSlider(min=0, max=1000, - value=max_iteration, description="Iterations"), + value=max_iteration, description='Iterations'), pixel_count=IntSlider(min=10, max=1000, - value=pixel_count, description="Pixels"), + value=pixel_count, description='Pixels'), level_sep=IntSlider(min=1, max=20, value=level_sep, description="Color sep"), color_num=IntSlider(min=1, max=100, diff --git a/src/sage/dynamics/complex_dynamics/mandel_julia_helper.pyx b/src/sage/dynamics/complex_dynamics/mandel_julia_helper.pyx index 479589dc0e3..2fd00e9b07a 100644 --- a/src/sage/dynamics/complex_dynamics/mandel_julia_helper.pyx +++ b/src/sage/dynamics/complex_dynamics/mandel_julia_helper.pyx @@ -78,27 +78,25 @@ cpdef fast_mandelbrot_plot(double x_center, double y_center, INPUT: - - ``x_center`` -- double, real part of the center point in the complex plane. + - ``x_center`` -- double; real part of the center point in the complex plane - - ``y_center`` -- double, imaginary part of the center point in the complex - plane. - - - ``image_width`` -- double, width of the image in the complex plane. + - ``y_center`` -- double; imaginary part of the center point in the complex + plane - - ``max_iteration`` -- long, maximum number of iterations the map `Q_c(z)` - considered. + - ``image_width`` -- double; width of the image in the complex plane - - ``pixel_count`` -- long, side length of image in number of pixels. + - ``max_iteration`` -- long; maximum number of iterations the map `Q_c(z)` + considered - - ``level_sep`` -- long, number of iterations between each color level. + - ``pixel_count`` -- long; side length of image in number of pixels - - ``color_num`` -- long, number of colors used to plot image. + - ``level_sep`` -- long; number of iterations between each color level - - ``base_color`` -- list, RGB color used to determine the coloring of set. + - ``color_num`` -- long; number of colors used to plot image - OUTPUT: + - ``base_color`` -- list; RGB color used to determine the coloring of set - 24-bit RGB image of the Mandelbrot set in the complex plane. + OUTPUT: 24-bit RGB image of the Mandelbrot set in the complex plane EXAMPLES: @@ -185,32 +183,30 @@ cpdef fast_external_ray(double theta, long D=30, long S=10, long R=100, INPUT: - - ``theta`` -- double, angle between 0 and 1 inclusive. + - ``theta`` -- double; angle between 0 and 1 inclusive - - ``D`` -- long (default: ``25``) depth of the approximation. + - ``D`` -- long (default: ``25``); depth of the approximation. As ``D`` increases, the external ray gets closer to the boundary of the Mandelbrot set. - - ``S`` -- long (default: ``10``) sharpness of the approximation. + - ``S`` -- long (default: ``10``); sharpness of the approximation. Adjusts the number of points used to approximate the external ray (number of points is equal to ``S*D``). - - ``R`` -- long (default: ``100``) radial parameter. If ``R`` is + - ``R`` -- long (default: ``100``); radial parameter. If ``R`` is sufficiently large, the external ray reaches enough close to infinity. - - ``pixel_count`` -- long (default: ``500``) side length of image - in number of pixels. + - ``pixel_count`` -- long (default: ``500``); side length of image + in number of pixels - - ``image_width`` -- double (default: ``4``) width of the image - in the complex plane. + - ``image_width`` -- double (default: ``4``); width of the image + in the complex plane - - ``prec`` -- long (default: ``300``) specifies the bits of + - ``prec`` -- long (default: ``300``); specifies the bits of precision used by the Complex Field when using Newton's method to compute - points on the external ray. + points on the external ray - OUTPUT: - - List of tuples of Real Interval Field Elements. + OUTPUT: list of tuples of Real Interval Field Elements EXAMPLES:: @@ -292,23 +288,21 @@ cpdef fast_external_ray(double theta, long D=30, long S=10, long R=100, cpdef convert_to_pixels(point_list, double x_0, double y_0, double width, long number_of_pixels): r""" - Converts cartesian coordinates to pixels within a specified window. + Convert cartesian coordinates to pixels within a specified window. INPUT: - - ``point_list`` -- list of tuples, points in cartesian coordinates. - - - ``x_0`` -- double, x-coordinate of the center of the image. + - ``point_list`` -- list of tuples; points in cartesian coordinates - - ``y_0`` -- double, y-coordinate of the center of the image. + - ``x_0`` -- double; x-coordinate of the center of the image - - ``width`` -- double, width of visible window in cartesian coordinates. + - ``y_0`` -- double; y-coordinate of the center of the image - - ``number_of_pixels`` -- long, width of image in pixels. + - ``width`` -- double; width of visible window in cartesian coordinates - OUTPUT: + - ``number_of_pixels`` -- long; width of image in pixels - List of tuples of integers representing pixels. + OUTPUT: list of tuples of integers representing pixels EXAMPLES:: @@ -345,13 +339,11 @@ cpdef get_line(start, end): INPUT: - - ``start`` -- tuple, starting point of line. + - ``start`` -- tuple; starting point of line - - ``end`` -- tuple, ending point of line. + - ``end`` -- tuple; ending point of line - OUTPUT: - - List of tuples of integers approximating the line between two pixels. + OUTPUT: list of tuples of integers approximating the line between two pixels EXAMPLES:: @@ -427,38 +419,36 @@ cpdef fast_julia_plot(double c_real, double c_imag, INPUT: - - ``c_real`` -- double, Real part of `c` value that determines Julia set. - - - ``c_imag`` -- double, Imaginary part of `c` value that determines Julia - set. + - ``c_real`` -- double; Real part of `c` value that determines Julia set - - ``x_center`` -- double (default: ``0.0``), Real part of center - point. + - ``c_imag`` -- double; Imaginary part of `c` value that determines Julia + set - - ``y_center`` -- double (default: ``0.0``), Imaginary part of - center point. + - ``x_center`` -- double (default: ``0.0``); real part of center + point - - ``image_width`` -- double (default: ``4.0``), width of image - in the complex plane. + - ``y_center`` -- double (default: ``0.0``); imaginary part of + center point - - ``max_iteration`` -- long (default: ``500``), maximum number of - iterations the map ``Q_c(z)``. + - ``image_width`` -- double (default: ``4.0``); width of image + in the complex plane - - ``pixel_count`` -- long (default: ``500``), side length of - image in number of pixels. + - ``max_iteration`` -- long (default: ``500``); maximum number of + iterations the map ``Q_c(z)`` - - ``level_sep`` -- long (default: ``2``), number of iterations - between each color level. + - ``pixel_count`` -- long (default: ``500``); side length of + image in number of pixels - - ``color_num`` -- long (default: ``40``), number of colors used - to plot image. + - ``level_sep`` -- long (default: ``2``); number of iterations + between each color level - - ``base_color`` -- RGB color (default: ``[50, 50, 50]``), color - used to determine the coloring of set. + - ``color_num`` -- long (default: ``40``); number of colors used + to plot image - OUTPUT: + - ``base_color`` -- RGB color (default: ``[50, 50, 50]``); color + used to determine the coloring of set - 24-bit RGB image of the Julia set in the complex plane. + OUTPUT: 24-bit RGB image of the Julia set in the complex plane EXAMPLES: @@ -548,41 +538,39 @@ cpdef julia_helper(double c_real, double c_imag, double x_center=0, INPUT: - - ``c_real`` -- double, Real part of `c` value that determines Julia set. + - ``c_real`` -- double; Real part of `c` value that determines Julia set - - ``c_imag`` -- double, Imaginary part of `c` value that determines Julia - set. + - ``c_imag`` -- double; Imaginary part of `c` value that determines Julia + set - - ``x_center`` -- double (default: ``0.0``), Real part of center - point. + - ``x_center`` -- double (default: ``0.0``); Real part of center + point - - ``y_center`` -- double (default: ``0.0``), Imaginary part of - center point. + - ``y_center`` -- double (default: ``0.0``); Imaginary part of + center point - - ``image_width`` -- double (default: ``4.0``), width of image in - the complex plane. + - ``image_width`` -- double (default: ``4.0``); width of image in + the complex plane - - ``max_iteration`` -- long (default: ``500``), maximum number of - iterations the map ``Q_c(z)``. + - ``max_iteration`` -- long (default: ``500``); maximum number of + iterations the map ``Q_c(z)`` - - ``pixel_count`` -- long (default: ``500``), side length of - image in number of pixels. + - ``pixel_count`` -- long (default: ``500``); side length of + image in number of pixels - - ``level_sep`` -- long (default: ``2``), number of iterations - between each color level. + - ``level_sep`` -- long (default: ``2``); number of iterations + between each color level - - ``color_num`` -- long (default: ``40``), number of colors used - to plot image. + - ``color_num`` -- long (default: ``40``); number of colors used + to plot image - - ``base_color`` -- RGB color (default: ``[50, 50, 50]``), color - used to determine the coloring of set. + - ``base_color`` -- RGB color (default: ``[50, 50, 50]``); color + used to determine the coloring of set - - ``point_color`` -- RGB color (default: ``[255, 0, 0]``), color - of the point `c` in the Mandelbrot set. + - ``point_color`` -- RGB color (default: ``[255, 0, 0]``); color + of the point `c` in the Mandelbrot set - OUTPUT: - - 24-bit RGB image of the Julia and Mandelbrot sets in the complex plane. + OUTPUT: 24-bit RGB image of the Julia and Mandelbrot sets in the complex plane EXAMPLES: @@ -637,33 +625,31 @@ cpdef polynomial_mandelbrot(f, parameter=None, double x_center=0, INPUT: - - ``f`` -- a one parameter family of polynomial maps defined over the multivariate polynomial ring in - z, c over the Complex field. + - ``f`` -- a one parameter family of polynomial maps defined over the + multivariate polynomial ring in z, c over the Complex field - - ``parameter`` -- designates which variable is used as the parameter. - If no parameter is provided, ``c`` will be used as the parameter. + - ``parameter`` -- designates which variable is used as the parameter + If no parameter is provided, ``c`` will be used as the parameter - - ``x_center`` -- double, real part of the center point in the complex plane. + - ``x_center`` -- double, real part of the center point in the complex plane - ``y_center`` -- double, imaginary part of the center point in the complex - plane. + plane - - ``image_width`` -- double, width of the image in the complex plane. + - ``image_width`` -- double, width of the image in the complex plane - ``max_iteration`` -- long, maximum number of iterations the map `f(z)` - considered. - - - ``pixel_count`` -- long, side length of image in number of pixels. + considered - - ``level_sep`` -- long, number of iterations between each color level. + - ``pixel_count`` -- long, side length of image in number of pixels - - ``color_num`` -- long, number of colors used to plot image. + - ``level_sep`` -- long, number of iterations between each color level - - ``base_color`` -- list, RGB color used to determine the coloring of set. + - ``color_num`` -- long, number of colors used to plot image - OUTPUT: + - ``base_color`` -- list; RGB color used to determine the coloring of set - 24-bit RGB image of a Mandelbrot set in the complex plane. + OUTPUT: 24-bit RGB image of a Mandelbrot set in the complex plane EXAMPLES:: diff --git a/src/sage/dynamics/finite_dynamical_system.py b/src/sage/dynamics/finite_dynamical_system.py index 9cf9fc6a51e..d6cfc29feb7 100644 --- a/src/sage/dynamics/finite_dynamical_system.py +++ b/src/sage/dynamics/finite_dynamical_system.py @@ -139,7 +139,7 @@ class DiscreteDynamicalSystem(SageObject, metaclass=ClasscallMetaclass): (and thus subject to mutation or exhaustion). - ``phi`` -- function, or callable that acts like a - function; the evolution of the DDS. + function; the evolution of the DDS - ``cache_orbits`` -- boolean (default: ``False``); whether or not the orbits should be cached once they @@ -366,15 +366,15 @@ def __init__(self, X, phi, cache_orbits=False, create_tuple=False): EXAMPLES:: sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: (3 if x == 4 else 1), create_tuple=True) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: (3 if x == 4 else 1), create_tuple=True, is_finite=False) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem(NN, lambda x: (3 if x == 4 else 1)) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem(None, lambda x: (3 if x == 4 else 1)) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: x, create_tuple=True) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest """ if create_tuple: X = tuple(X) @@ -705,7 +705,7 @@ class InvertibleDiscreteDynamicalSystem(DiscreteDynamicalSystem): ``X``, as otherwise the input would be exposed. - ``phi`` -- function, or callable that acts like a - function; the evolution of the DDS. + function; the evolution of the DDS - ``inverse`` -- function, or callable that acts like a function; the inverse evolution of the DDS. (A @@ -756,13 +756,13 @@ def __init__(self, X, phi, inverse=None, cache_orbits=False, create_tuple=False) EXAMPLES:: sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: x, create_tuple=True, inverse=True) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: x, create_tuple=True, is_finite=False, inverse=True) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem(NN, lambda x: x, inverse=True) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest sage: D = DiscreteDynamicalSystem(None, lambda x: x, inverse=True) - sage: TestSuite(D).run(skip ="_test_pickling") # indirect doctest + sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest """ if create_tuple: X = tuple(X) diff --git a/src/sage/env.py b/src/sage/env.py index abb9b19f9e3..6d08056f30d 100644 --- a/src/sage/env.py +++ b/src/sage/env.py @@ -74,17 +74,15 @@ def var(key: str, *fallbacks: Optional[str], force: bool = False) -> Optional[st INPUT: - - ``key`` -- string. + - ``key`` -- string - - ``fallbacks`` -- tuple containing ``str`` or ``None`` values. + - ``fallbacks`` -- tuple containing ``str`` or ``None`` values - - ``force`` -- boolean (default: ``False``). If + - ``force`` -- boolean (default: ``False``); if ``True``, skip the environment variable and only use the - fallbacks. + fallbacks - OUTPUT: - - The value of the environment variable or its fallbacks. + OUTPUT: the value of the environment variable or its fallbacks EXAMPLES:: @@ -281,7 +279,7 @@ def sage_include_directories(use_sources=False): INPUT: - - ``use_sources`` -- (default: ``False``) a boolean + - ``use_sources`` -- boolean (default: ``False``) OUTPUT: @@ -344,8 +342,7 @@ def get_cblas_pc_module_name() -> str: default_optional_modules = ('lapack',) -def cython_aliases(required_modules=None, - optional_modules=None): +def cython_aliases(required_modules=None, optional_modules=None): """ Return the aliases for compiling Cython code. These aliases are macros which can occur in ``# distutils`` headers. @@ -353,10 +350,10 @@ def cython_aliases(required_modules=None, INPUT: - ``required_modules`` -- (default: taken from ``default_required_modules``) - iterable of ``str`` values. + iterable of string values - ``optional_modules`` -- (default: taken from ``default_optional_modules``) - iterable of ``str`` values. + iterable of string values EXAMPLES:: diff --git a/src/sage/ext/fast_callable.pyx b/src/sage/ext/fast_callable.pyx index 9d2db75be3d..c7b4664ff1a 100644 --- a/src/sage/ext/fast_callable.pyx +++ b/src/sage/ext/fast_callable.pyx @@ -475,9 +475,9 @@ def fast_callable(x, domain=None, vars=None, x = x.function(*vars) if vars is None: - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing - if is_PolynomialRing(x.parent()) or is_MPolynomialRing(x.parent()): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base + if isinstance(x.parent(), PolynomialRing_general) or isinstance(x.parent(), MPolynomialRing_base): vars = x.parent().variable_names() else: # constant @@ -506,7 +506,7 @@ def _builder_and_stream(vars, domain): - ``domain`` -- a Sage parent or Python type or ``None``; if non-``None``, all arithmetic is done in that domain - OUTPUT: A :class:`Wrapper`, an class:`InstructionStream` + OUTPUT: a :class:`Wrapper`, an class:`InstructionStream` EXAMPLES:: @@ -1607,7 +1607,6 @@ cpdef _expression_binop_helper(s, o, op): add(v_0, v_1) sage: _expression_binop_helper(y, x, operator.add) # needs sage.symbolic add(v_1, v_0) - """ # The Cython way of handling operator overloading on cdef classes # (which is inherited from Python) is quite annoying. Inside the @@ -2068,12 +2067,12 @@ cdef class InstructionStream: INPUT: - - ``metadata`` -- The ``metadata_by_opname`` from a wrapper module + - ``metadata`` -- the ``metadata_by_opname`` from a wrapper module - - ``n_args`` -- The number of arguments accessible by the generated code + - ``n_args`` -- the number of arguments accessible by the generated code (this is just passed to the wrapper class) - - ``domain`` -- The domain of interpretation (this is just passed to the + - ``domain`` -- the domain of interpretation (this is just passed to the wrapper class) EXAMPLES:: @@ -2394,14 +2393,14 @@ class CompilerInstrSpec(): The parameter list is a list of strings. Each string is one of the following: - - ``'args'`` -- The instruction argument refers to an input argument of the - wrapper class; it is just appended to the code. + - ``'args'`` -- the instruction argument refers to an input argument of the + wrapper class; it is just appended to the code - - ``'constants'``, ``'py_constants'`` -- The instruction argument is a value; the + - ``'constants'``, ``'py_constants'`` -- the instruction argument is a value; the value is added to the corresponding list (if it's not already there) and the index is appended to the code. - - ``'n_inputs'``, ``'n_outputs'`` -- The instruction actually takes a variable + - ``'n_inputs'``, ``'n_outputs'`` -- the instruction actually takes a variable number of inputs or outputs (the ``n_inputs`` and ``n_outputs`` attributes of this instruction are ignored). The instruction argument specifies the number of inputs or outputs (respectively); it is just appended to the @@ -2655,7 +2654,6 @@ class FastCallableFloatWrapper: ... ValueError: complex fast-callable function result 1.0*I for arguments (-1,) - """ def __init__(self, ff, imag_tol): r""" @@ -2668,13 +2666,13 @@ class FastCallableFloatWrapper: with :func:`fast_callable`. - ``imag_tol`` -- float; how big of an imaginary part we're willing - to ignore before raising an error. + to ignore before raising an error OUTPUT: An instance of :class:`FastCallableFloatWrapper` that can be called just like ``ff``, but that always returns a :class:`float` - if no error is raised. A :class:`ValueError` is raised if the + if no error is raised. A :exc:`ValueError` is raised if the imaginary part of the result exceeds ``imag_tol``. EXAMPLES: @@ -2695,7 +2693,6 @@ class FastCallableFloatWrapper: ... ValueError: complex fast-callable function result 1e-09*I for arguments (1.00000000000000e-9*I,) - """ self._ff = ff self._imag_tol = imag_tol @@ -2706,7 +2703,7 @@ class FastCallableFloatWrapper: TESTS: - Evaluation either returns a :class:`float`, or raises a :class:`ValueError`:: + Evaluation either returns a :class:`float`, or raises a :exc:`ValueError`:: sage: # needs sage.symbolic sage: from sage.ext.fast_callable import FastCallableFloatWrapper @@ -2719,7 +2716,6 @@ class FastCallableFloatWrapper: ....: result = float(0) sage: type(result) is float True - """ z = self._ff(*args) diff --git a/src/sage/ext/fast_eval.pyx b/src/sage/ext/fast_eval.pyx index 3db7d6fa1dc..cd14c0b0893 100644 --- a/src/sage/ext/fast_eval.pyx +++ b/src/sage/ext/fast_eval.pyx @@ -43,7 +43,7 @@ def fast_float(f, *vars, expect_one_var=False): INPUT: - - ``f`` -- an expression + - ``f`` -- an expression - ``vars`` -- the names of the arguments - ``expect_one_var`` -- don't give deprecation warning if ``vars`` is omitted, as long as expression has only one var diff --git a/src/sage/ext/memory.pyx b/src/sage/ext/memory.pyx index b5d9e422410..76f51623d96 100644 --- a/src/sage/ext/memory.pyx +++ b/src/sage/ext/memory.pyx @@ -44,7 +44,7 @@ cdef extern from "Python.h": cdef void alloc_error(size_t size) noexcept nogil: """ - Jump back to ``sig_on()``, raising a :class:`MemoryError`. + Jump back to ``sig_on()``, raising a :exc:`MemoryError`. """ with gil: PyErr_Format(MemoryError, "failed to allocate %zu bytes", size) diff --git a/src/sage/ext_data/pari/simon/ell.gp b/src/sage/ext_data/pari/simon/ell.gp index 663df10a7c3..c330ef59f55 100644 --- a/src/sage/ext_data/pari/simon/ell.gp +++ b/src/sage/ext_data/pari/simon/ell.gp @@ -878,7 +878,7 @@ if( DEBUGLEVEL_ell >= 4, print(" end of nflocallysoluble")); p4 = Delta Note that the case of 4 real roots can only occur if both s and t - are non-zero, otherwise the Sturm sequence is shorter than this one. + are nonzero, otherwise the Sturm sequence is shorter than this one. By Sturm's theorem, the number of roots equals (sign changes in [1, -4, -2*s, t, Delta]) - diff --git a/src/sage/features/__init__.py b/src/sage/features/__init__.py index df76ec9da99..81602180d80 100644 --- a/src/sage/features/__init__.py +++ b/src/sage/features/__init__.py @@ -22,26 +22,26 @@ feature:: sage: from sage.features import Executable - sage: Executable(name="sh", executable="sh").is_present() + sage: Executable(name='sh', executable='sh').is_present() FeatureTestResult('sh', True) Here we test whether the grape GAP package is available:: sage: from sage.features.gap import GapPackage - sage: GapPackage("grape", spkg="gap_packages").is_present() # optional - gap_package_grape + sage: GapPackage("grape", spkg='gap_packages').is_present() # optional - gap_package_grape FeatureTestResult('gap_package_grape', True) Note that a :class:`FeatureTestResult` acts like a bool in most contexts:: - sage: if Executable(name="sh", executable="sh").is_present(): "present." + sage: if Executable(name='sh', executable='sh').is_present(): "present." 'present.' When one wants to raise an error if the feature is not available, one can use the ``require`` method:: - sage: Executable(name="sh", executable="sh").require() + sage: Executable(name='sh', executable='sh').require() - sage: Executable(name="random", executable="randomOochoz6x", spkg="random", url="http://rand.om").require() # optional - sage_spkg + sage: Executable(name='random', executable='randomOochoz6x', spkg='random', url='http://rand.om').require() # optional - sage_spkg Traceback (most recent call last): ... FeatureNotPresentError: random is not available. @@ -110,28 +110,28 @@ def __classcall__(cls, *args, **options): class Feature(TrivialUniqueRepresentation): r""" - A feature of the runtime environment + A feature of the runtime environment. INPUT: - - ``name`` -- (string) name of the feature; this should be suitable as an optional tag + - ``name`` -- string; name of the feature. This should be suitable as an optional tag for the Sage doctester, i.e., lowercase alphanumeric with underscores (``_``) allowed; features that correspond to Python modules/packages may use periods (``.``) - - ``spkg`` -- (string) name of the SPKG providing the feature + - ``spkg`` -- string; name of the SPKG providing the feature - - ``description`` -- (string) optional; plain English description of the feature + - ``description`` -- string (optional); plain English description of the feature - ``url`` -- a URL for the upstream package providing the feature - - ``type`` -- (string) one of ``'standard'``, ``'optional'`` (default), ``'experimental'`` + - ``type`` -- string; one of ``'standard'``, ``'optional'`` (default), ``'experimental'`` Overwrite :meth:`_is_present` to add feature checks. EXAMPLES:: sage: from sage.features.gap import GapPackage - sage: GapPackage("grape", spkg="gap_packages") # indirect doctest + sage: GapPackage("grape", spkg='gap_packages') # indirect doctest Feature('gap_package_grape') For efficiency, features are unique:: @@ -145,7 +145,7 @@ def __init__(self, name, spkg=None, url=None, description=None, type='optional') sage: from sage.features import Feature sage: from sage.features.gap import GapPackage - sage: isinstance(GapPackage("grape", spkg="gap_packages"), Feature) # indirect doctest + sage: isinstance(GapPackage("grape", spkg='gap_packages'), Feature) # indirect doctest True """ self.name = name @@ -182,9 +182,9 @@ def is_present(self): EXAMPLES:: sage: from sage.features.gap import GapPackage - sage: GapPackage("grape", spkg="gap_packages").is_present() # optional - gap_package_grape + sage: GapPackage("grape", spkg='gap_packages').is_present() # optional - gap_package_grape FeatureTestResult('gap_package_grape', True) - sage: GapPackage("NOT_A_PACKAGE", spkg="gap_packages").is_present() + sage: GapPackage("NOT_A_PACKAGE", spkg='gap_packages').is_present() FeatureTestResult('gap_package_NOT_A_PACKAGE', False) The result is cached:: @@ -229,7 +229,7 @@ def _is_present(self): def require(self): r""" - Raise a :class:`FeatureNotPresentError` if the feature is not present. + Raise a :exc:`FeatureNotPresentError` if the feature is not present. EXAMPLES:: @@ -253,7 +253,6 @@ def __repr__(self): sage: from sage.features.gap import GapPackage sage: GapPackage("grape") # indirect doctest Feature('gap_package_grape') - """ description = f'{self.name!r}: {self.description}' if self.description else f'{self.name!r}' return f'Feature({description})' @@ -282,14 +281,12 @@ def resolution(self): Return a suggestion on how to make :meth:`is_present` pass if it did not pass. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: sage: from sage.features import Executable - sage: Executable(name="CSDP", spkg="csdp", executable="theta", url="https://github.com/dimpase/csdp").resolution() # optional - sage_spkg + sage: Executable(name='CSDP', spkg='csdp', executable='theta', url='https://github.com/dimpase/csdp').resolution() # optional - sage_spkg '...To install CSDP...you can try to run...sage -i csdp...Further installation instructions might be available at https://github.com/dimpase/csdp.' """ if self._hidden: @@ -432,7 +429,7 @@ class FeatureNotPresentError(RuntimeError): ....: def _is_present(self): ....: return False - sage: Missing(name="missing").require() + sage: Missing(name='missing').require() Traceback (most recent call last): ... FeatureNotPresentError: missing is not available. @@ -498,12 +495,12 @@ class FeatureTestResult(): default you need explicitly set ``resolution`` to a string:: sage: from sage.features import FeatureTestResult - sage: package = GapPackage("NOT_A_PACKAGE", spkg="no_package") + sage: package = GapPackage("NOT_A_PACKAGE", spkg='no_package') sage: str(FeatureTestResult(package, True).resolution) # optional - sage_spkg '...To install gap_package_NOT_A_PACKAGE...you can try to run...sage -i no_package...' sage: str(FeatureTestResult(package, False).resolution) # optional - sage_spkg '...To install gap_package_NOT_A_PACKAGE...you can try to run...sage -i no_package...' - sage: FeatureTestResult(package, False, resolution="rtm").resolution + sage: FeatureTestResult(package, False, resolution='rtm').resolution 'rtm' """ def __init__(self, feature, is_present, reason=None, resolution=None): @@ -511,7 +508,7 @@ def __init__(self, feature, is_present, reason=None, resolution=None): TESTS:: sage: from sage.features import Executable, FeatureTestResult - sage: isinstance(Executable(name="sh", executable="sh").is_present(), FeatureTestResult) + sage: isinstance(Executable(name='sh', executable='sh').is_present(), FeatureTestResult) True """ self.feature = feature @@ -604,9 +601,9 @@ class FileFeature(Feature): True To work with the file described by the feature, use the method :meth:`absolute_filename`. - A :class:`FeatureNotPresentError` is raised if the file cannot be found:: + A :exc:`FeatureNotPresentError` is raised if the file cannot be found:: - sage: Executable(name="does-not-exist", executable="does-not-exist-xxxxyxyyxyy").absolute_filename() + sage: Executable(name='does-not-exist', executable='does-not-exist-xxxxyxyyxyy').absolute_filename() Traceback (most recent call last): ... sage.features.FeatureNotPresentError: does-not-exist is not available. @@ -616,7 +613,7 @@ class FileFeature(Feature): the presence of the file at run time. This is inherited from the base class :class:`Feature`:: - sage: Executable(name="sh", executable="sh").is_present() + sage: Executable(name='sh', executable='sh').is_present() FeatureTestResult('sh', True) """ def _is_present(self): @@ -626,7 +623,7 @@ def _is_present(self): EXAMPLES:: sage: from sage.features import StaticFile - sage: StaticFile(name="no_such_file", filename="KaT1aihu", spkg="some_spkg", url="http://rand.om").is_present() + sage: StaticFile(name='no_such_file', filename='KaT1aihu', spkg='some_spkg', url='http://rand.om').is_present() FeatureTestResult('no_such_file', False) """ try: @@ -644,7 +641,7 @@ def absolute_filename(self) -> str: TESTS:: sage: from sage.features import FileFeature - sage: FileFeature(name="abstract_file").absolute_filename() + sage: FileFeature(name='abstract_file').absolute_filename() Traceback (most recent call last): ... NotImplementedError @@ -675,9 +672,9 @@ class Executable(FileFeature): EXAMPLES:: sage: from sage.features import Executable - sage: Executable(name="sh", executable="sh").is_present() + sage: Executable(name='sh', executable='sh').is_present() FeatureTestResult('sh', True) - sage: Executable(name="does-not-exist", executable="does-not-exist-xxxxyxyyxyy").is_present() + sage: Executable(name='does-not-exist', executable='does-not-exist-xxxxyxyyxyy').is_present() FeatureTestResult('does-not-exist', False) """ def __init__(self, name, executable, **kwds): @@ -685,7 +682,7 @@ def __init__(self, name, executable, **kwds): TESTS:: sage: from sage.features import Executable - sage: isinstance(Executable(name="sh", executable="sh"), Executable) + sage: isinstance(Executable(name='sh', executable='sh'), Executable) True """ Feature.__init__(self, name, **kwds) @@ -700,7 +697,7 @@ def _is_present(self): EXAMPLES:: sage: from sage.features import Executable - sage: Executable(name="sh", executable="sh").is_present() + sage: Executable(name='sh', executable='sh').is_present() FeatureTestResult('sh', True) """ result = FileFeature._is_present(self) @@ -721,7 +718,7 @@ def is_functional(self): The function returns ``True`` unless explicitly overwritten:: sage: from sage.features import Executable - sage: Executable(name="sh", executable="sh").is_functional() + sage: Executable(name='sh', executable='sh').is_functional() FeatureTestResult('sh', True) """ return FeatureTestResult(self, True) @@ -733,12 +730,12 @@ def absolute_filename(self) -> str: EXAMPLES:: sage: from sage.features import Executable - sage: Executable(name="sh", executable="sh").absolute_filename() + sage: Executable(name='sh', executable='sh').absolute_filename() '/...bin/sh' - A :class:`FeatureNotPresentError` is raised if the file cannot be found:: + A :exc:`FeatureNotPresentError` is raised if the file cannot be found:: - sage: Executable(name="does-not-exist", executable="does-not-exist-xxxxyxyyxyy").absolute_filename() + sage: Executable(name='does-not-exist', executable='does-not-exist-xxxxyxyyxyy').absolute_filename() Traceback (most recent call last): ... sage.features.FeatureNotPresentError: does-not-exist is not available. @@ -770,9 +767,9 @@ class StaticFile(FileFeature): EXAMPLES:: sage: from sage.features import StaticFile - sage: StaticFile(name="no_such_file", filename="KaT1aihu", # optional - sage_spkg - ....: search_path="/", spkg="some_spkg", - ....: url="http://rand.om").require() + sage: StaticFile(name='no_such_file', filename='KaT1aihu', # optional - sage_spkg + ....: search_path='/', spkg='some_spkg', + ....: url='http://rand.om').require() Traceback (most recent call last): ... FeatureNotPresentError: no_such_file is not available. @@ -785,15 +782,14 @@ def __init__(self, name, filename, *, search_path=None, type='optional', **kwds) TESTS:: sage: from sage.features import StaticFile - sage: StaticFile(name="null", filename="null", search_path="/dev") + sage: StaticFile(name='null', filename='null', search_path='/dev') Feature('null') - sage: sh = StaticFile(name="shell", filename="sh", + sage: sh = StaticFile(name='shell', filename='sh', ....: search_path=("/dev", "/bin", "/usr")) sage: sh Feature('shell') sage: sh.absolute_filename() '/bin/sh' - """ Feature.__init__(self, name, type=type, **kwds) self.filename = filename @@ -816,16 +812,16 @@ def absolute_filename(self) -> str: sage: file_path = os.path.join(dir_with_file, "file.txt") sage: open(file_path, 'a').close() # make sure the file exists sage: search_path = ( '/foo/bar', dir_with_file ) # file is somewhere in the search path - sage: feature = StaticFile(name="file", filename="file.txt", search_path=search_path) + sage: feature = StaticFile(name='file', filename='file.txt', search_path=search_path) sage: feature.absolute_filename() == file_path True - A :class:`FeatureNotPresentError` is raised if the file cannot be found:: + A :exc:`FeatureNotPresentError` is raised if the file cannot be found:: sage: from sage.features import StaticFile - sage: StaticFile(name="no_such_file", filename="KaT1aihu",\ - search_path=(), spkg="some_spkg",\ - url="http://rand.om").absolute_filename() # optional - sage_spkg + sage: StaticFile(name='no_such_file', filename='KaT1aihu',\ + search_path=(), spkg='some_spkg',\ + url='http://rand.om').absolute_filename() # optional - sage_spkg Traceback (most recent call last): ... FeatureNotPresentError: no_such_file is not available. @@ -859,8 +855,8 @@ class CythonFeature(Feature): ....: assert fabs(-1) == 1 ....: ''' sage: fabs = CythonFeature("fabs", test_code=fabs_test_code, # needs sage.misc.cython - ....: spkg="gcc", url="https://gnu.org", - ....: type="standard") + ....: spkg='gcc', url='https://gnu.org', + ....: type='standard') sage: fabs.is_present() # needs sage.misc.cython FeatureTestResult('fabs', True) @@ -924,7 +920,7 @@ def _is_present(self): from distutils.errors import CCompilerError except ImportError: CCompilerError = () - with open(tmp_filename(ext=".pyx"), 'w') as pyx: + with open(tmp_filename(ext='.pyx'), 'w') as pyx: pyx.write(self.test_code) try: from sage.misc.cython import cython_import diff --git a/src/sage/features/all.py b/src/sage/features/all.py index a53d095c596..14d2480d520 100644 --- a/src/sage/features/all.py +++ b/src/sage/features/all.py @@ -50,7 +50,7 @@ def module_feature(module_name): - ``module_name`` -- string - OUTPUT: a :class:`Feature` or ``None``. + OUTPUT: a :class:`Feature` or ``None`` EXAMPLES:: @@ -93,7 +93,7 @@ def name_feature(name, toplevel=None): - ``toplevel`` -- a module or other namespace - OUTPUT: a :class:`Feature` or ``None``. + OUTPUT: a :class:`Feature` or ``None`` EXAMPLES:: diff --git a/src/sage/features/bliss.py b/src/sage/features/bliss.py index 0bc812a76bc..d905ff13d5f 100644 --- a/src/sage/features/bliss.py +++ b/src/sage/features/bliss.py @@ -54,8 +54,8 @@ def __init__(self): Feature('libbliss') """ CythonFeature.__init__(self, "libbliss", test_code=TEST_CODE, - spkg="bliss", - url="http://www.tcs.hut.fi/Software/bliss/") + spkg='bliss', + url='http://www.tcs.hut.fi/Software/bliss/') class Bliss(JoinFeature): @@ -77,8 +77,8 @@ def __init__(self): Feature('bliss') """ JoinFeature.__init__(self, "bliss", - [PythonModule("sage.graphs.bliss", spkg="sagemath_bliss", - url="http://www.tcs.hut.fi/Software/bliss/")]) + [PythonModule("sage.graphs.bliss", spkg='sagemath_bliss', + url='http://www.tcs.hut.fi/Software/bliss/')]) def all_features(): diff --git a/src/sage/features/cddlib.py b/src/sage/features/cddlib.py index 24b67ef9f8e..8e657ca0020 100644 --- a/src/sage/features/cddlib.py +++ b/src/sage/features/cddlib.py @@ -34,5 +34,5 @@ def __init__(self, name='cddexec_gmp'): sage: isinstance(CddExecutable(), CddExecutable) True """ - Executable.__init__(self, name=name, executable=name, spkg="cddlib", - url="https://github.com/cddlib/cddlib", type="standard") + Executable.__init__(self, name=name, executable=name, spkg='cddlib', + url='https://github.com/cddlib/cddlib', type='standard') diff --git a/src/sage/features/coxeter3.py b/src/sage/features/coxeter3.py index 97e153b18a3..bf7b476d50c 100644 --- a/src/sage/features/coxeter3.py +++ b/src/sage/features/coxeter3.py @@ -38,7 +38,7 @@ def __init__(self): """ JoinFeature.__init__(self, "coxeter3", [PythonModule("sage.libs.coxeter3.coxeter", - spkg="sagemath_coxeter3")]) + spkg='sagemath_coxeter3')]) def all_features(): diff --git a/src/sage/features/csdp.py b/src/sage/features/csdp.py index 866ca1c21d1..733e8b6ffdf 100644 --- a/src/sage/features/csdp.py +++ b/src/sage/features/csdp.py @@ -41,8 +41,8 @@ def __init__(self): sage: isinstance(CSDP(), CSDP) True """ - Executable.__init__(self, name="csdp", spkg="csdp", executable="theta", - url="https://github.com/dimpase/csdp") + Executable.__init__(self, name='csdp', spkg='csdp', executable='theta', + url='https://github.com/dimpase/csdp') def is_functional(self): r""" diff --git a/src/sage/features/databases.py b/src/sage/features/databases.py index 7a05270532c..9d070d932ed 100644 --- a/src/sage/features/databases.py +++ b/src/sage/features/databases.py @@ -48,7 +48,7 @@ class DatabaseCremona(StaticFile): INPUT: - ``name`` -- either ``'cremona'`` (the default) for the full large - database or ``'cremona_mini'`` for the small database. + database or ``'cremona_mini'`` for the small database EXAMPLES:: @@ -58,7 +58,7 @@ class DatabaseCremona(StaticFile): sage: DatabaseCremona().is_present() # optional - database_cremona_ellcurve FeatureTestResult('database_cremona_ellcurve', True) """ - def __init__(self, name="cremona", spkg="database_cremona_ellcurve", type='optional'): + def __init__(self, name='cremona', spkg='database_cremona_ellcurve', type='optional'): r""" TESTS:: @@ -82,7 +82,7 @@ def __init__(self, name="cremona", spkg="database_cremona_ellcurve", type='optio search_path=search_path, spkg=spkg, type=spkg_type, - url="https://github.com/JohnCremona/ecdata", + url='https://github.com/JohnCremona/ecdata', description="Cremona's database of elliptic curves") @@ -111,8 +111,8 @@ def __init__(self): StaticFile.__init__(self, "database_ellcurves", filename='rank0', search_path=search_path, - spkg="elliptic_curves", - type="standard", + spkg='elliptic_curves', + type='standard', description="William Stein's database of interesting curve") @@ -141,8 +141,8 @@ def __init__(self): StaticFile.__init__(self, "database_graphs", filename='graphs.db', search_path=search_path, - spkg="graphs", - type="standard", + spkg='graphs', + type='standard', description="A database of graphs") @@ -168,7 +168,7 @@ def __init__(self): StaticFile.__init__(self, "database_jones_numfield", filename='jones.sobj', search_path=sage_data_path("jones"), - spkg="database_jones_numfield", + spkg='database_jones_numfield', description="John Jones's tables of number fields") @@ -221,7 +221,7 @@ def __init__(self): sage: isinstance(DatabaseMatroids(), DatabaseMatroids) True """ - PythonModule.__init__(self, "matroid_database", spkg="matroid_database") + PythonModule.__init__(self, 'matroid_database', spkg='matroid_database') class DatabaseCubicHecke(PythonModule): diff --git a/src/sage/features/dvipng.py b/src/sage/features/dvipng.py index 66fbee39561..68bcdcb5a04 100644 --- a/src/sage/features/dvipng.py +++ b/src/sage/features/dvipng.py @@ -16,7 +16,7 @@ class dvipng(Executable): r""" - A :class:`~sage.features.Feature` describing the presence of ``dvipng`` + A :class:`~sage.features.Feature` describing the presence of ``dvipng``. EXAMPLES:: @@ -32,8 +32,8 @@ def __init__(self): sage: isinstance(dvipng(), dvipng) True """ - Executable.__init__(self, "dvipng", executable="dvipng", - url="https://savannah.nongnu.org/projects/dvipng/") + Executable.__init__(self, 'dvipng', executable='dvipng', + url='https://savannah.nongnu.org/projects/dvipng/') def all_features(): diff --git a/src/sage/features/ecm.py b/src/sage/features/ecm.py index 06f4ac10dbd..3bf3e67fc14 100644 --- a/src/sage/features/ecm.py +++ b/src/sage/features/ecm.py @@ -34,8 +34,8 @@ def __init__(self): sage: isinstance(Ecm(), Ecm) True """ - Executable.__init__(self, name="ecm", executable=SAGE_ECMBIN, - spkg="ecm", type="standard") + Executable.__init__(self, name='ecm', executable=SAGE_ECMBIN, + spkg='ecm', type='standard') def all_features(): diff --git a/src/sage/features/ffmpeg.py b/src/sage/features/ffmpeg.py index 366249875d7..0d3ff8e4232 100644 --- a/src/sage/features/ffmpeg.py +++ b/src/sage/features/ffmpeg.py @@ -32,9 +32,9 @@ def __init__(self): sage: isinstance(FFmpeg(), FFmpeg) True """ - Executable.__init__(self, "ffmpeg", executable="ffmpeg", - spkg="ffmpeg", - url="https://www.ffmpeg.org/") + Executable.__init__(self, 'ffmpeg', executable='ffmpeg', + spkg='ffmpeg', + url='https://www.ffmpeg.org/') def is_functional(self): r""" @@ -45,7 +45,6 @@ def is_functional(self): sage: from sage.features.ffmpeg import FFmpeg sage: FFmpeg().is_functional() # optional - ffmpeg FeatureTestResult('ffmpeg', True) - """ # Create the content of 1-pixel png file content = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x00\x00\x00\x00:~\x9bU\x00\x00\x00\nIDATx\x9cc`\x00\x00\x00\x02\x00\x01H\xaf\xa4q\x00\x00\x00\x00IEND\xaeB`\x82' @@ -103,7 +102,7 @@ def is_functional(self): # If an error occurred, return False if result.returncode: return FeatureTestResult(self, False, reason='Running command "{}" ' - 'returned non-zero exit status "{}" with stderr ' + 'returned nonzero exit status "{}" with stderr ' '"{}" and stdout "{}".'.format(result.args, result.returncode, result.stderr.strip(), diff --git a/src/sage/features/four_ti_2.py b/src/sage/features/four_ti_2.py index 655674cbde1..8ae7822bfc3 100644 --- a/src/sage/features/four_ti_2.py +++ b/src/sage/features/four_ti_2.py @@ -23,7 +23,7 @@ def __init__(self, name): Executable.__init__(self, name="4ti2-" + name, executable=SAGE_ENV.get("FOURTITWO_" + name.upper(), None) or name, - spkg="4ti2") + spkg='4ti2') class FourTi2(JoinFeature): diff --git a/src/sage/features/fricas.py b/src/sage/features/fricas.py index d5b7d469207..539b3b027dd 100644 --- a/src/sage/features/fricas.py +++ b/src/sage/features/fricas.py @@ -34,9 +34,9 @@ def __init__(self): sage: isinstance(FriCAS(), FriCAS) True """ - Executable.__init__(self, name="fricas", spkg="fricas", - executable="fricas", - url="https://fricas.github.io") + Executable.__init__(self, name='fricas', spkg='fricas', + executable='fricas', + url='https://fricas.github.io') def is_functional(self): r""" diff --git a/src/sage/features/gap.py b/src/sage/features/gap.py index fdcbceee102..22197942b00 100644 --- a/src/sage/features/gap.py +++ b/src/sage/features/gap.py @@ -30,7 +30,7 @@ class GapPackage(Feature): EXAMPLES:: sage: from sage.features.gap import GapPackage - sage: GapPackage("grape", spkg="gap_packages") + sage: GapPackage("grape", spkg='gap_packages') Feature('gap_package_grape') """ def __init__(self, package, **kwds): @@ -38,7 +38,7 @@ def __init__(self, package, **kwds): TESTS:: sage: from sage.features.gap import GapPackage - sage: isinstance(GapPackage("grape", spkg="gap_packages"), GapPackage) + sage: isinstance(GapPackage("grape", spkg='gap_packages'), GapPackage) True """ Feature.__init__(self, f"gap_package_{package}", **kwds) @@ -54,7 +54,7 @@ def _is_present(self): EXAMPLES:: sage: from sage.features.gap import GapPackage - sage: GapPackage("grape", spkg="gap_packages")._is_present() # optional - gap_package_grape + sage: GapPackage("grape", spkg='gap_packages')._is_present() # optional - gap_package_grape FeatureTestResult('gap_package_grape', True) """ try: @@ -76,11 +76,11 @@ def _is_present(self): def all_features(): - return [GapPackage("atlasrep", spkg="gap_packages"), - GapPackage("design", spkg="gap_packages"), - GapPackage("grape", spkg="gap_packages"), - GapPackage("guava", spkg="gap_packages"), - GapPackage("hap", spkg="gap_packages"), - GapPackage("polycyclic", spkg="gap_packages"), - GapPackage("qpa", spkg="gap_packages"), - GapPackage("quagroup", spkg="gap_packages")] + return [GapPackage("atlasrep", spkg='gap_packages'), + GapPackage("design", spkg='gap_packages'), + GapPackage("grape", spkg='gap_packages'), + GapPackage("guava", spkg='gap_packages'), + GapPackage("hap", spkg='gap_packages'), + GapPackage("polycyclic", spkg='gap_packages'), + GapPackage("qpa", spkg='gap_packages'), + GapPackage("quagroup", spkg='gap_packages')] diff --git a/src/sage/features/gfan.py b/src/sage/features/gfan.py index e3545392934..dfc6875c53b 100644 --- a/src/sage/features/gfan.py +++ b/src/sage/features/gfan.py @@ -31,7 +31,7 @@ def __init__(self, cmd=None): name = "gfan" else: name = f"gfan_{cmd}" - Executable.__init__(self, name, executable=name, spkg="gfan", type='standard') + Executable.__init__(self, name, executable=name, spkg='gfan', type='standard') def all_features(): diff --git a/src/sage/features/graph_generators.py b/src/sage/features/graph_generators.py index 8f384af9ed3..603b2bab7b8 100644 --- a/src/sage/features/graph_generators.py +++ b/src/sage/features/graph_generators.py @@ -40,9 +40,9 @@ def __init__(self): sage: isinstance(Plantri(), Plantri) True """ - Executable.__init__(self, name="plantri", spkg="plantri", - executable="plantri", - url="http://users.cecs.anu.edu.au/~bdm/plantri/") + Executable.__init__(self, name='plantri', spkg='plantri', + executable='plantri', + url='http://users.cecs.anu.edu.au/~bdm/plantri/') def is_functional(self): r""" @@ -87,9 +87,9 @@ def __init__(self): sage: isinstance(Buckygen(), Buckygen) True """ - Executable.__init__(self, name="buckygen", spkg="buckygen", - executable="buckygen", - url="http://caagt.ugent.be/buckygen/") + Executable.__init__(self, name='buckygen', spkg='buckygen', + executable='buckygen', + url='http://caagt.ugent.be/buckygen/') def is_functional(self): r""" @@ -135,9 +135,9 @@ def __init__(self): sage: isinstance(Benzene(), Benzene) True """ - Executable.__init__(self, name="benzene", spkg="benzene", - executable="benzene", - url="http://www.grinvin.org/") + Executable.__init__(self, name='benzene', spkg='benzene', + executable='benzene', + url='http://www.grinvin.org/') def is_functional(self): r""" diff --git a/src/sage/features/graphviz.py b/src/sage/features/graphviz.py index 4e6ae9a6c4a..f8c633eafbf 100644 --- a/src/sage/features/graphviz.py +++ b/src/sage/features/graphviz.py @@ -36,9 +36,9 @@ def __init__(self): sage: isinstance(dot(), dot) True """ - Executable.__init__(self, "dot", executable="dot", - spkg="graphviz", - url="https://www.graphviz.org/") + Executable.__init__(self, 'dot', executable='dot', + spkg='graphviz', + url='https://www.graphviz.org/') class neato(Executable): @@ -59,9 +59,9 @@ def __init__(self): sage: isinstance(neato(), neato) True """ - Executable.__init__(self, "neato", executable="neato", - spkg="graphviz", - url="https://www.graphviz.org/") + Executable.__init__(self, 'neato', executable='neato', + spkg='graphviz', + url='https://www.graphviz.org/') class twopi(Executable): @@ -82,9 +82,9 @@ def __init__(self): sage: isinstance(twopi(), twopi) True """ - Executable.__init__(self, "twopi", executable="twopi", - spkg="graphviz", - url="https://www.graphviz.org/") + Executable.__init__(self, 'twopi', executable='twopi', + spkg='graphviz', + url='https://www.graphviz.org/') class Graphviz(JoinFeature): @@ -107,10 +107,10 @@ def __init__(self): sage: isinstance(Graphviz(), Graphviz) True """ - JoinFeature.__init__(self, "graphviz", + JoinFeature.__init__(self, 'graphviz', [dot(), neato(), twopi()], - spkg="graphviz", - url="https://www.graphviz.org/") + spkg='graphviz', + url='https://www.graphviz.org/') def all_features(): diff --git a/src/sage/features/igraph.py b/src/sage/features/igraph.py index 00d260f2ac7..9bb61c28454 100644 --- a/src/sage/features/igraph.py +++ b/src/sage/features/igraph.py @@ -37,8 +37,8 @@ def __init__(self): True """ JoinFeature.__init__(self, 'python_igraph', - [PythonModule('igraph', spkg="python_igraph", - url="http://igraph.org")]) + [PythonModule('igraph', spkg='python_igraph', + url='http://igraph.org')]) def all_features(): return [python_igraph()] diff --git a/src/sage/features/imagemagick.py b/src/sage/features/imagemagick.py index fb273371326..866d0aed95e 100644 --- a/src/sage/features/imagemagick.py +++ b/src/sage/features/imagemagick.py @@ -39,11 +39,11 @@ def __init__(self): sage: isinstance(Magick(), Magick) True """ - Executable.__init__(self, "magick", executable="magick") + Executable.__init__(self, 'magick', executable='magick') try: _ = self.absolute_filename() except RuntimeError: - Executable.__init__(self, "magick", executable="convert") + Executable.__init__(self, 'magick', executable='convert') def is_functional(self): r""" @@ -54,7 +54,6 @@ def is_functional(self): sage: from sage.features.imagemagick import Magick sage: Magick().is_functional() # optional - imagemagick FeatureTestResult('magick', True) - """ # Create the content of 1-pixel png file content = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x00\x00\x00\x00:~\x9bU\x00\x00\x00\nIDATx\x9cc`\x00\x00\x00\x02\x00\x01H\xaf\xa4q\x00\x00\x00\x00IEND\xaeB`\x82' @@ -96,7 +95,7 @@ def is_functional(self): # If an error occurred, return False if result.returncode: return FeatureTestResult(self, False, reason='Running command "{}" ' - 'returned non-zero exit status "{}" with stderr ' + 'returned nonzero exit status "{}" with stderr ' '"{}" and stdout "{}".'.format(result.args, result.returncode, result.stderr.strip(), @@ -130,10 +129,10 @@ def __init__(self): sage: isinstance(ImageMagick(), ImageMagick) True """ - JoinFeature.__init__(self, "imagemagick", + JoinFeature.__init__(self, 'imagemagick', [Magick()], - spkg="imagemagick", - url="https://www.imagemagick.org/") + spkg='imagemagick', + url='https://www.imagemagick.org/') def all_features(): return [ImageMagick()] diff --git a/src/sage/features/jmol.py b/src/sage/features/jmol.py index feb293bd8db..52104202a40 100644 --- a/src/sage/features/jmol.py +++ b/src/sage/features/jmol.py @@ -32,11 +32,11 @@ def __init__(self): ) StaticFile.__init__( - self, name="jmol", - filename="JmolData.jar", + self, name='jmol', + filename='JmolData.jar', search_path=jmol_search_path, - spkg="jmol", - type="standard", + spkg='jmol', + type='standard', description="Java viewer for chemical structures in 3D") diff --git a/src/sage/features/kenzo.py b/src/sage/features/kenzo.py index 39b8dd9a936..b5d83b06972 100644 --- a/src/sage/features/kenzo.py +++ b/src/sage/features/kenzo.py @@ -36,8 +36,8 @@ def __init__(self): sage: isinstance(Kenzo(), Kenzo) True """ - Feature.__init__(self, name="kenzo", spkg="kenzo", - url="https://github.com/miguelmarco/kenzo/") + Feature.__init__(self, name='kenzo', spkg='kenzo', + url='https://github.com/miguelmarco/kenzo/') def _is_present(self): r""" diff --git a/src/sage/features/latex.py b/src/sage/features/latex.py index 6f366ff86f6..271800beece 100644 --- a/src/sage/features/latex.py +++ b/src/sage/features/latex.py @@ -24,7 +24,7 @@ class LaTeX(Executable): r""" - A :class:`~sage.features.Feature` describing the presence of ``latex`` + A :class:`~sage.features.Feature` describing the presence of ``latex``. EXAMPLES:: @@ -59,7 +59,7 @@ def is_functional(self): sage: print(result.reason) # not tested Running latex on a sample file (with command='latex -interaction=nonstopmode tmp_wmpos8ak.tex') - returned non-zero exit status='1' with stderr='' + returned nonzero exit status='1' with stderr='' and stdout='This is pdfTeX, ... Runaway argument? @@ -95,7 +95,7 @@ def is_functional(self): return FeatureTestResult(self, True) else: return FeatureTestResult(self, False, reason="Running latex on " - "a sample file (with command='{}') returned non-zero " + "a sample file (with command='{}') returned nonzero " "exit status='{}' with stderr='{}' " "and stdout='{}'".format(result.args, result.returncode, @@ -105,7 +105,7 @@ def is_functional(self): class latex(LaTeX): r""" - A :class:`~sage.features.Feature` describing the presence of ``latex`` + A :class:`~sage.features.Feature` describing the presence of ``latex``. EXAMPLES:: @@ -126,7 +126,7 @@ def __init__(self): class pdflatex(LaTeX): r""" - A :class:`~sage.features.Feature` describing the presence of ``pdflatex`` + A :class:`~sage.features.Feature` describing the presence of ``pdflatex``. EXAMPLES:: @@ -147,7 +147,7 @@ def __init__(self): class xelatex(LaTeX): r""" - A :class:`~sage.features.Feature` describing the presence of ``xelatex`` + A :class:`~sage.features.Feature` describing the presence of ``xelatex``. EXAMPLES:: @@ -168,7 +168,7 @@ def __init__(self): class lualatex(LaTeX): r""" - A :class:`~sage.features.Feature` describing the presence of ``lualatex`` + A :class:`~sage.features.Feature` describing the presence of ``lualatex``. EXAMPLES:: @@ -189,7 +189,7 @@ def __init__(self): class dvips(Executable): r""" - A :class:`~sage.features.Feature` describing the presence of ``dvips`` + A :class:`~sage.features.Feature` describing the presence of ``dvips``. EXAMPLES:: @@ -205,12 +205,12 @@ def __init__(self): sage: isinstance(dvips(), dvips) True """ - Executable.__init__(self, "dvips", executable="dvips", - url="https://tug.org/texinfohtml/dvips.html") + Executable.__init__(self, 'dvips', executable='dvips', + url='https://tug.org/texinfohtml/dvips.html') class TeXFile(StaticFile): r""" - A :class:`sage.features.Feature` describing the presence of a TeX file + A :class:`sage.features.Feature` describing the presence of a TeX file. EXAMPLES:: diff --git a/src/sage/features/latte.py b/src/sage/features/latte.py index 7e973978c24..9370d5e1ecc 100644 --- a/src/sage/features/latte.py +++ b/src/sage/features/latte.py @@ -35,8 +35,8 @@ def __init__(self): sage: isinstance(Latte_count(), Latte_count) True """ - Executable.__init__(self, "count", executable="count", - spkg="latte_int", + Executable.__init__(self, 'count', executable='count', + spkg='latte_int', url=LATTE_URL) @@ -52,8 +52,8 @@ def __init__(self): sage: isinstance(Latte_integrate(), Latte_integrate) True """ - Executable.__init__(self, "integrate", executable="integrate", - spkg="latte_int", + Executable.__init__(self, 'integrate', executable='integrate', + spkg='latte_int', url=LATTE_URL) @@ -76,9 +76,9 @@ def __init__(self): sage: isinstance(Latte(), Latte) True """ - JoinFeature.__init__(self, "latte_int", + JoinFeature.__init__(self, 'latte_int', (Latte_count(), Latte_integrate()), - description="LattE") + description='LattE') def all_features(): diff --git a/src/sage/features/lrs.py b/src/sage/features/lrs.py index 52506e496e5..b0f61b62bc9 100644 --- a/src/sage/features/lrs.py +++ b/src/sage/features/lrs.py @@ -41,8 +41,8 @@ def __init__(self): sage: isinstance(Lrs(), Lrs) True """ - Executable.__init__(self, "lrs", executable="lrs", spkg="lrslib", - url="http://cgm.cs.mcgill.ca/~avis/C/lrs.html") + Executable.__init__(self, "lrs", executable='lrs', spkg='lrslib', + url='http://cgm.cs.mcgill.ca/~avis/C/lrs.html') def is_functional(self): r""" @@ -100,8 +100,8 @@ def __init__(self): sage: isinstance(LrsNash(), LrsNash) True """ - Executable.__init__(self, "lrsnash", executable="lrsnash", spkg="lrslib", - url="http://cgm.cs.mcgill.ca/~avis/C/lrs.html") + Executable.__init__(self, "lrsnash", executable='lrsnash', spkg='lrslib', + url='http://cgm.cs.mcgill.ca/~avis/C/lrs.html') def is_functional(self): r""" @@ -128,7 +128,7 @@ def is_functional(self): 'raised an OSError "{}" '.format(' '.join(command), e)) if result.returncode: return FeatureTestResult(self, False, reason='Running command "{}" ' - 'returned non-zero exit status "{}" with stderr ' + 'returned nonzero exit status "{}" with stderr ' '"{}" and stdout "{}".'.format(' '.join(result.args), result.returncode, result.stderr.strip(), diff --git a/src/sage/features/msolve.py b/src/sage/features/msolve.py index 4328af54876..bc66da45044 100644 --- a/src/sage/features/msolve.py +++ b/src/sage/features/msolve.py @@ -40,8 +40,8 @@ def __init__(self): sage: isinstance(msolve(), msolve) True """ - Executable.__init__(self, "msolve", executable="msolve", - url="https://msolve.lip6.fr/") + Executable.__init__(self, "msolve", executable='msolve', + url='https://msolve.lip6.fr/') def is_functional(self): r""" @@ -57,7 +57,7 @@ def is_functional(self): # if msolve_out.returncode != 0: # return FeatureTestResult(self, False, reason="msolve -h returned " -# f"non-zero exit status {msolve_out.returncode}") +# f"nonzero exit status {msolve_out.returncode}") if (msolve_out.stdout[:46] != b'\nmsolve library for polynomial system solving\n'): return FeatureTestResult(self, False, diff --git a/src/sage/features/nauty.py b/src/sage/features/nauty.py index 79542de74fc..f0f47bcda28 100644 --- a/src/sage/features/nauty.py +++ b/src/sage/features/nauty.py @@ -38,8 +38,8 @@ def __init__(self, name): """ Executable.__init__(self, name=f"nauty_{name}", executable=f"{SAGE_NAUTY_BINS_PREFIX}{name}", - spkg="nauty", - type="standard") + spkg='nauty', + type='standard') class Nauty(JoinFeature): diff --git a/src/sage/features/normaliz.py b/src/sage/features/normaliz.py index 6d1de88bf58..5b872739bc0 100644 --- a/src/sage/features/normaliz.py +++ b/src/sage/features/normaliz.py @@ -36,7 +36,7 @@ def __init__(self): True """ JoinFeature.__init__(self, 'pynormaliz', - [PythonModule('PyNormaliz', spkg="pynormaliz")]) + [PythonModule('PyNormaliz', spkg='pynormaliz')]) def all_features(): diff --git a/src/sage/features/palp.py b/src/sage/features/palp.py index b35634ac800..9e3324c495b 100644 --- a/src/sage/features/palp.py +++ b/src/sage/features/palp.py @@ -22,9 +22,9 @@ class PalpExecutable(Executable): INPUT: - - ``palpprog`` -- string, one of ``"poly"``, ``"class"``, ``"nef"``, ``"cws"``. + - ``palpprog`` -- string, one of ``'poly'``, ``'class'``, ``'nef'``, ``'cws'`` - - ``suff`` -- string or ``None``. + - ``suff`` -- string or ``None`` """ def __init__(self, palpprog, suff=None): r""" @@ -37,11 +37,11 @@ def __init__(self, palpprog, suff=None): if suff: Executable.__init__(self, f"palp_{palpprog}_{suff}d", executable=f"{palpprog}-{suff}d.x", - spkg="palp", type="standard") + spkg='palp', type='standard') else: Executable.__init__(self, f"palp_{palpprog}", executable=f"{palpprog}.x", - spkg="palp", type="standard") + spkg='palp', type='standard') class Palp(JoinFeature): r""" @@ -59,7 +59,7 @@ def __init__(self): [PalpExecutable(palpprog, suff) for palpprog in ("poly", "class", "nef", "cws") for suff in (None, 4, 5, 6, 11)], - description="PALP") + description='PALP') def all_features(): return [Palp()] diff --git a/src/sage/features/pandoc.py b/src/sage/features/pandoc.py index 1c4450b9b0c..3c43c7fcf47 100644 --- a/src/sage/features/pandoc.py +++ b/src/sage/features/pandoc.py @@ -34,8 +34,8 @@ def __init__(self): sage: isinstance(Pandoc(), Pandoc) True """ - Executable.__init__(self, "pandoc", executable="pandoc", - url="https://pandoc.org/") + Executable.__init__(self, "pandoc", executable='pandoc', + url='https://pandoc.org/') def all_features(): diff --git a/src/sage/features/pdf2svg.py b/src/sage/features/pdf2svg.py index af20d011ac3..41014eb8e5c 100644 --- a/src/sage/features/pdf2svg.py +++ b/src/sage/features/pdf2svg.py @@ -32,9 +32,9 @@ def __init__(self): sage: isinstance(pdf2svg(), pdf2svg) True """ - Executable.__init__(self, "pdf2svg", executable="pdf2svg", + Executable.__init__(self, "pdf2svg", executable='pdf2svg', spkg='pdf2svg', - url="http://www.cityinthesky.co.uk/opensource/pdf2svg/") + url='http://www.cityinthesky.co.uk/opensource/pdf2svg/') def all_features(): diff --git a/src/sage/features/polymake.py b/src/sage/features/polymake.py index 10dfab73346..6428d68a29d 100644 --- a/src/sage/features/polymake.py +++ b/src/sage/features/polymake.py @@ -36,7 +36,7 @@ def __init__(self): True """ JoinFeature.__init__(self, "jupymake", - [PythonModule("JuPyMake", spkg="jupymake")]) + [PythonModule("JuPyMake", spkg='jupymake')]) def all_features(): diff --git a/src/sage/features/poppler.py b/src/sage/features/poppler.py index d3c0ad18541..a6da8343f53 100644 --- a/src/sage/features/poppler.py +++ b/src/sage/features/poppler.py @@ -51,8 +51,8 @@ def __init__(self): sage: isinstance(pdftocairo(), pdftocairo) True """ - Executable.__init__(self, "pdftocairo", executable="pdftocairo", - url="https://poppler.freedesktop.org/") + Executable.__init__(self, "pdftocairo", executable='pdftocairo', + url='https://poppler.freedesktop.org/') def all_features(): return [pdftocairo()] diff --git a/src/sage/features/rubiks.py b/src/sage/features/rubiks.py index 2429645d2ff..cc8d5dc10ab 100644 --- a/src/sage/features/rubiks.py +++ b/src/sage/features/rubiks.py @@ -38,7 +38,7 @@ def __init__(self): True """ Executable.__init__(self, "cu2", executable=RUBIKS_BINS_PREFIX + "cu2", - spkg="rubiks") + spkg='rubiks') class size222(Executable): @@ -60,7 +60,7 @@ def __init__(self): True """ Executable.__init__(self, "size222", executable=RUBIKS_BINS_PREFIX + "size222", - spkg="rubiks") + spkg='rubiks') class optimal(Executable): @@ -82,7 +82,7 @@ def __init__(self): True """ Executable.__init__(self, "optimal", executable=RUBIKS_BINS_PREFIX + "optimal", - spkg="rubiks") + spkg='rubiks') class mcube(Executable): @@ -104,7 +104,7 @@ def __init__(self): True """ Executable.__init__(self, "mcube", executable=RUBIKS_BINS_PREFIX + "mcube", - spkg="rubiks") + spkg='rubiks') class dikcube(Executable): @@ -126,7 +126,7 @@ def __init__(self): True """ Executable.__init__(self, "dikcube", executable=RUBIKS_BINS_PREFIX + "dikcube", - spkg="rubiks") + spkg='rubiks') class cubex(Executable): @@ -148,7 +148,7 @@ def __init__(self): True """ Executable.__init__(self, "cubex", executable=RUBIKS_BINS_PREFIX + "cubex", - spkg="rubiks") + spkg='rubiks') class Rubiks(JoinFeature): @@ -173,7 +173,7 @@ def __init__(self): """ JoinFeature.__init__(self, "rubiks", [cu2(), size222(), optimal(), mcube(), dikcube(), cubex()], - spkg="rubiks") + spkg='rubiks') def all_features(): diff --git a/src/sage/features/sagemath.py b/src/sage/features/sagemath.py index 1e41ab758d9..b5e4c59b3bb 100644 --- a/src/sage/features/sagemath.py +++ b/src/sage/features/sagemath.py @@ -48,7 +48,6 @@ class SAGE_SRC(StaticFile): r""" A :class:`~sage.features.Feature` which describes the presence of the monolithic source tree of the Sage library. - """ def __init__(self): r""" @@ -175,7 +174,7 @@ def __init__(self): [PythonModule('sage.combinat'), # namespace package PythonModule('sage.combinat.tableau'), # representative ], - spkg='sagemath_combinat', type="standard") + spkg='sagemath_combinat', type='standard') class sage__geometry__polyhedron(JoinFeature): @@ -219,7 +218,7 @@ def __init__(self): PythonModule('sage.schemes.toric'), # namespace package PythonModule('sage.schemes.toric.variety'), # representative ], - spkg='sagemath_polyhedra', type="standard") + spkg='sagemath_polyhedra', type='standard') class sage__graphs(JoinFeature): @@ -301,7 +300,7 @@ def __init__(self): PythonModule('sage.topology'), # namespace package PythonModule('sage.topology.simplicial_complex'), # representative ], - spkg='sagemath_graphs', type="standard") + spkg='sagemath_graphs', type='standard') class sage__groups(JoinFeature): @@ -1063,7 +1062,7 @@ def __init__(self): """ JoinFeature.__init__(self, 'sage.schemes', [PythonModule('sage.schemes.elliptic_curves.ell_generic')], - spkg="sagemath_schemes", type='standard') + spkg='sagemath_schemes', type='standard') class sage__symbolic(JoinFeature): diff --git a/src/sage/features/sirocco.py b/src/sage/features/sirocco.py index 676f187299f..2f392855a5e 100644 --- a/src/sage/features/sirocco.py +++ b/src/sage/features/sirocco.py @@ -38,7 +38,7 @@ def __init__(self): """ JoinFeature.__init__(self, "sirocco", [PythonModule("sage.libs.sirocco", - spkg="sagemath_sirocco")]) + spkg='sagemath_sirocco')]) def all_features(): diff --git a/src/sage/features/symengine_py.py b/src/sage/features/symengine_py.py index 0e602e0b84d..96a64ca60b3 100644 --- a/src/sage/features/symengine_py.py +++ b/src/sage/features/symengine_py.py @@ -37,8 +37,8 @@ def __init__(self): True """ JoinFeature.__init__(self, 'symengine_py', - [PythonModule('symengine', spkg="symengine_py", - url="https://pypi.org/project/symengine")]) + [PythonModule('symengine', spkg='symengine_py', + url='https://pypi.org/project/symengine')]) def all_features(): return [symengine_py()] diff --git a/src/sage/features/threejs.py b/src/sage/features/threejs.py index 39136c87ecd..56ad807babf 100644 --- a/src/sage/features/threejs.py +++ b/src/sage/features/threejs.py @@ -40,10 +40,10 @@ def __init__(self): filename = 'unknown' StaticFile.__init__( - self, name="threejs", + self, name='threejs', filename=filename, - spkg="threejs", - type="standard", + spkg='threejs', + type='standard', search_path=threejs_search_path, description="JavaScript library to display 3D graphics") @@ -54,7 +54,7 @@ def required_version(self): Defining what version is required is delegated to the distribution package that provides the file ``threejs-version.txt`` in :mod:`sage.ext_data.threejs`. - If the file is not provided, :class:`FileNotFoundError` is raised. + If the file is not provided, :exc:`FileNotFoundError` is raised. EXAMPLES:: diff --git a/src/sage/functions/airy.py b/src/sage/functions/airy.py index 11f4c56be8c..d8f1a79fa8b 100644 --- a/src/sage/functions/airy.py +++ b/src/sage/functions/airy.py @@ -62,11 +62,11 @@ class FunctionAiryAiGeneral(BuiltinFunction): def __init__(self): r""" - The generalized derivative of the Airy Ai function + The generalized derivative of the Airy Ai function. INPUT: - - ``alpha`` -- Return the `\alpha`-th order fractional derivative with + - ``alpha`` -- return the `\alpha`-th order fractional derivative with respect to `z`. For `\alpha = n = 1,2,3,\ldots` this gives the derivative `\operatorname{Ai}^{(n)}(z)`, and for `\alpha = -n = -1,-2,-3,\ldots` @@ -78,7 +78,7 @@ def __init__(self): f_n(z) = \int_0^z f_{n-1}(t) dt - - ``x`` -- The argument of the function + - ``x`` -- the argument of the function EXAMPLES:: @@ -365,7 +365,7 @@ def _evalf_(self, x, **kwargs): def airy_ai(alpha, x=None, hold_derivative=True, **kwds): r""" - The Airy Ai function + The Airy Ai function. The Airy Ai function `\operatorname{Ai}(x)` is (along with `\operatorname{Bi}(x)`) one of the two linearly independent standard @@ -387,7 +387,7 @@ def airy_ai(alpha, x=None, hold_derivative=True, **kwds): INPUT: - - ``alpha`` -- Return the `\alpha`-th order fractional derivative with + - ``alpha`` -- return the `\alpha`-th order fractional derivative with respect to `z`. For `\alpha = n = 1,2,3,\ldots` this gives the derivative `\operatorname{Ai}^{(n)}(z)`, and for `\alpha = -n = -1,-2,-3,\ldots` @@ -399,9 +399,9 @@ def airy_ai(alpha, x=None, hold_derivative=True, **kwds): f_n(z) = \int_0^z f_{n-1}(t) dt - - ``x`` -- The argument of the function + - ``x`` -- the argument of the function - - ``hold_derivative`` -- Whether or not to stop from returning higher + - ``hold_derivative`` -- whether or not to stop from returning higher derivatives in terms of `\operatorname{Ai}(x)` and `\operatorname{Ai}'(x)` @@ -504,7 +504,7 @@ def __init__(self): INPUT: - - ``alpha`` -- Return the `\alpha`-th order fractional derivative with + - ``alpha`` -- return the `\alpha`-th order fractional derivative with respect to `z`. For `\alpha = n = 1,2,3,\ldots` this gives the derivative `\operatorname{Bi}^{(n)}(z)`, and for `\alpha = -n = -1,-2,-3,\ldots` @@ -516,7 +516,7 @@ def __init__(self): f_n(z) = \int_0^z f_{n-1}(t) dt - - ``x`` -- The argument of the function + - ``x`` -- the argument of the function EXAMPLES:: @@ -581,7 +581,6 @@ def _evalf_(self, alpha, x, **kwargs): sage: from sage.functions.airy import airy_bi_general sage: airy_bi_general(-2, 1.0) # needs mpmath 0.388621540699059 - """ parent = kwargs.get('parent') import mpmath @@ -807,7 +806,7 @@ def _evalf_(self, x, **kwargs): def airy_bi(alpha, x=None, hold_derivative=True, **kwds): r""" - The Airy Bi function + The Airy Bi function. The Airy Bi function `\operatorname{Bi}(x)` is (along with `\operatorname{Ai}(x)`) one of the two linearly independent standard @@ -830,7 +829,7 @@ def airy_bi(alpha, x=None, hold_derivative=True, **kwds): INPUT: - - ``alpha`` -- Return the `\alpha`-th order fractional derivative with + - ``alpha`` -- return the `\alpha`-th order fractional derivative with respect to `z`. For `\alpha = n = 1,2,3,\ldots` this gives the derivative `\operatorname{Bi}^{(n)}(z)`, and for `\alpha = -n = -1,-2,-3,\ldots` @@ -842,11 +841,11 @@ def airy_bi(alpha, x=None, hold_derivative=True, **kwds): f_n(z) = \int_0^z f_{n-1}(t) dt - - ``x`` -- The argument of the function + - ``x`` -- the argument of the function - - ``hold_derivative`` -- Whether or not to stop from returning higher - derivatives in terms of `\operatorname{Bi}(x)` and - `\operatorname{Bi}'(x)` + - ``hold_derivative`` -- boolean (default: ``True``); whether or not to + stop from returning higher derivatives in terms of `\operatorname{Bi}(x)` + and `\operatorname{Bi}'(x)` .. SEEALSO:: :func:`airy_ai` diff --git a/src/sage/functions/bessel.py b/src/sage/functions/bessel.py index cedbe56c00e..2eced09d619 100644 --- a/src/sage/functions/bessel.py +++ b/src/sage/functions/bessel.py @@ -7,20 +7,20 @@ The main objects which are exported from this module are: - * :meth:`bessel_J(n, x) ` -- The Bessel J function - * :meth:`bessel_Y(n, x) ` -- The Bessel Y function - * :meth:`bessel_I(n, x) ` -- The Bessel I function - * :meth:`bessel_K(n, x) ` -- The Bessel K function - * :meth:`Bessel(...) ` -- A factory function for producing Bessel functions of + * :meth:`bessel_J(n, x) ` -- the Bessel J function + * :meth:`bessel_Y(n, x) ` -- the Bessel Y function + * :meth:`bessel_I(n, x) ` -- the Bessel I function + * :meth:`bessel_K(n, x) ` -- the Bessel K function + * :meth:`Bessel(...) ` -- a factory function for producing Bessel functions of various kinds and orders - * :meth:`hankel1(nu, z) ` -- The Hankel function of the first kind - * :meth:`hankel2(nu, z) ` -- The Hankel function of the second kind - * :meth:`struve_H(nu, z) ` -- The Struve function - * :meth:`struve_L(nu, z) ` -- The modified Struve function - * :meth:`spherical_bessel_J(n, z) ` -- The Spherical Bessel J function - * :meth:`spherical_bessel_Y(n, z) ` -- The Spherical Bessel J function - * :meth:`spherical_hankel1(n, z) ` -- The Spherical Hankel function of the first kind - * :meth:`spherical_hankel2(n, z) ` -- The Spherical Hankel function of the second kind + * :meth:`hankel1(nu, z) ` -- the Hankel function of the first kind + * :meth:`hankel2(nu, z) ` -- the Hankel function of the second kind + * :meth:`struve_H(nu, z) ` -- the Struve function + * :meth:`struve_L(nu, z) ` -- the modified Struve function + * :meth:`spherical_bessel_J(n, z) ` -- the Spherical Bessel J function + * :meth:`spherical_bessel_Y(n, z) ` -- the Spherical Bessel J function + * :meth:`spherical_hankel1(n, z) ` -- the Spherical Hankel function of the first kind + * :meth:`spherical_hankel2(n, z) ` -- the Spherical Hankel function of the second kind - Bessel functions, first defined by the Swiss mathematician Daniel Bernoulli and named after Friedrich Bessel, are canonical @@ -435,7 +435,6 @@ def _derivative_(self, n, x, diff_param): Traceback (most recent call last): ... NotImplementedError: derivative with respect to order - """ if diff_param == 1: return (bessel_J(n - 1, x) - bessel_J(n + 1, x)) / Integer(2) @@ -1203,7 +1202,6 @@ def Bessel(*args, **kwds): sage: G += plot(Bessel(1, 'J'), 0, 15, color='black', linestyle='dotted') sage: G += plot(Bessel(1, 'Y'), 0, 15, color='black', linestyle='dotted') sage: show(G, ymin=-1, ymax=1) - """ # Determine the order and type of function from the arguments and keywords. # These are recorded in local variables: _type, _order, _system, _nargs. @@ -1476,7 +1474,7 @@ def _print_latex_(self, a, z): class Function_Hankel1(BuiltinFunction): r""" - The Hankel function of the first kind + The Hankel function of the first kind. DEFINITION: @@ -1563,7 +1561,7 @@ def _derivative_(self, nu, z, diff_param): class Function_Hankel2(BuiltinFunction): r""" - The Hankel function of the second kind + The Hankel function of the second kind. DEFINITION: @@ -1650,7 +1648,7 @@ def _derivative_(self, nu, z, diff_param): class SphericalBesselJ(BuiltinFunction): r""" - The spherical Bessel function of the first kind + The spherical Bessel function of the first kind. DEFINITION: @@ -1752,7 +1750,7 @@ def _derivative_(self, n, z, diff_param): class SphericalBesselY(BuiltinFunction): r""" - The spherical Bessel function of the second kind + The spherical Bessel function of the second kind. DEFINITION: @@ -1853,7 +1851,7 @@ def _derivative_(self, n, z, diff_param): class SphericalHankel1(BuiltinFunction): r""" - The spherical Hankel function of the first kind + The spherical Hankel function of the first kind. DEFINITION: @@ -1951,7 +1949,7 @@ def _derivative_(self, n, z, diff_param): class SphericalHankel2(BuiltinFunction): r""" - The spherical Hankel function of the second kind + The spherical Hankel function of the second kind. DEFINITION: diff --git a/src/sage/functions/error.py b/src/sage/functions/error.py index db6312af807..78eb4992aa6 100644 --- a/src/sage/functions/error.py +++ b/src/sage/functions/error.py @@ -7,12 +7,12 @@ The main objects which are exported from this module are: - * :meth:`erf ` -- The error function - * :meth:`erfc ` -- The complementary error function - * :meth:`erfi ` -- The imaginary error function - * :meth:`erfinv ` -- The inverse error function - * :meth:`fresnel_sin ` -- The Fresnel integral `S(x)` - * :meth:`fresnel_cos ` -- The Fresnel integral `C(x)` + * :meth:`erf ` -- the error function + * :meth:`erfc ` -- the complementary error function + * :meth:`erfi ` -- the imaginary error function + * :meth:`erfinv ` -- the inverse error function + * :meth:`fresnel_sin ` -- the Fresnel integral `S(x)` + * :meth:`fresnel_cos ` -- the Fresnel integral `C(x)` AUTHORS: @@ -383,7 +383,6 @@ def _derivative_(self, x, diff_param=None): sage: erfi(x).diff(x) # needs sage.symbolic 2*e^(x^2)/sqrt(pi) - """ return 2*exp(x**2)/sqrt(pi) @@ -421,7 +420,6 @@ class Function_erfc(BuiltinFunction): sage: erfc(x)._fricas_() # optional - fricas, needs sage.symbolic - erf(x) + 1 - """ def __init__(self): r""" diff --git a/src/sage/functions/exp_integral.py b/src/sage/functions/exp_integral.py index a277afd04b5..ac88a0146a1 100644 --- a/src/sage/functions/exp_integral.py +++ b/src/sage/functions/exp_integral.py @@ -148,7 +148,6 @@ class Function_exp_integral_e(BuiltinFunction): Numerical evaluation is handled using mpmath, but symbolics are handled by Sage and Maxima. - """ def __init__(self): """ @@ -160,7 +159,6 @@ def __init__(self): exp_integral_e(1, 0) sage: exp_integral_e(1, x)._sympy_() # needs sage.symbolic expint(1, x) - """ BuiltinFunction.__init__(self, "exp_integral_e", nargs=2, conversions=dict(maxima='expintegral_e', @@ -308,7 +306,6 @@ class Function_exp_integral_e1(BuiltinFunction): Numerical evaluation is handled using mpmath, but symbolics are handled by Sage and Maxima. - """ def __init__(self): """ @@ -320,7 +317,6 @@ def __init__(self): exp_integral_e1(1) sage: exp_integral_e1(x)._sympy_() # needs sympy sage.symbolic expint(1, x) - """ BuiltinFunction.__init__(self, "exp_integral_e1", nargs=1, conversions=dict(maxima='expintegral_e1', @@ -334,7 +330,6 @@ def _evalf_(self, z, parent=None, algorithm=None): 0.000281624451981418 - 0.179324535039359*I sage: exp_integral_e1(RealField(200)(0.5)) # needs sage.rings.real_mpfr 0.55977359477616081174679593931508523522684689031635351524829 - """ return _mpmath_utils_call(_mpmath_e1, z, parent=parent) @@ -365,7 +360,6 @@ def _derivative_(self, z, diff_param=None): sage: f = exp_integral_e1(x^2) sage: f.diff(x) -2*e^(-x^2)/x - """ return -exp(-z)/z @@ -424,8 +418,6 @@ class Function_log_integral(BuiltinFunction): - mpmath documentation: `logarithmic-integral`_ .. _`logarithmic-integral`: http://mpmath.org/doc/current/functions/expintegrals.html#logarithmic-integral - - """ def __init__(self): r""" @@ -464,7 +456,6 @@ def _eval_(self, z): 2.16358859466719 sage: log_integral(0) # needs mpmath 0 - """ # Special case z = 0 if isinstance(z, Expression): @@ -481,7 +472,6 @@ def _evalf_(self, z, parent=None, algorithm=None): 78627.5491594622 sage: log_integral(RealField(200)(1e6)) # needs sage.rings.real_mpfr 78627.549159462181919862910747947261161321874382421767074759 - """ return _mpmath_utils_call(_mpmath_li, z, parent=parent) @@ -499,7 +489,6 @@ def _derivative_(self, z, diff_param=None): sage: f = log_integral(x^2) sage: f.diff(x) 2*x/log(x^2) - """ return 1/log(z) @@ -642,7 +631,6 @@ def __init__(self): sage: latex(log_integral_offset) \operatorname{log\_integral\_offset} - """ BuiltinFunction.__init__(self, "log_integral_offset", nargs=1, latex_name=r'\operatorname{log\_integral\_offset}', @@ -659,7 +647,6 @@ def _eval_(self, z): 1.11842481454970 sage: log_integral_offset(2) # needs mpmath 0 - """ if z == 2: return SR(0) @@ -677,7 +664,6 @@ def _evalf_(self, z, parent=None, algorithm=None): 78626.503995682064427078066159058066548185351766843615873183 sage: li(4.5) - li(2.0) - Li(4.5) # needs mpmath 0.000000000000000 - """ return _mpmath_utils_call(_mpmath_li, z, offset=True, parent=parent) @@ -800,7 +786,6 @@ class Function_sin_integral(BuiltinFunction): - mpmath documentation: `si`_ .. _`si`: http://mpmath.org/doc/current/functions/expintegrals.html#si - """ def __init__(self): """ @@ -835,7 +820,6 @@ def _eval_(self, z): 1.84865252799947 sage: sin_integral(0) # needs mpmath 0 - """ if isinstance(z, Expression): if z.is_trivial_zero(): @@ -888,7 +872,6 @@ def _derivative_(self, z, diff_param=None): sage: f = sin_integral(x^2) sage: f.diff(x) 2*sin(x^2)/x - """ return sin(z)/z @@ -978,7 +961,6 @@ class Function_cos_integral(BuiltinFunction): - mpmath documentation: `ci`_ .. _`ci`: http://mpmath.org/doc/current/functions/expintegrals.html#ci - """ def __init__(self): """ @@ -1012,7 +994,6 @@ def _evalf_(self, z, parent=None, algorithm=None): -22.4486352650389239795759024568 sage: cos_integral(ComplexField(100)(I)) # needs sage.symbolic 0.83786694098020824089467857943 + 1.5707963267948966192313216916*I - """ return _mpmath_utils_call(_mpmath_ci, z, parent=parent) @@ -1030,7 +1011,6 @@ def _derivative_(self, z, diff_param=None): sage: f = cos_integral(x^2) sage: f.diff(x) 2*cos(x^2)/x - """ return cos(z)/z @@ -1116,7 +1096,6 @@ class Function_sinh_integral(BuiltinFunction): - mpmath documentation: `shi`_ .. _`shi`: http://mpmath.org/doc/current/functions/expintegrals.html#shi - """ def __init__(self): """ @@ -1128,7 +1107,6 @@ def __init__(self): sinh_integral(1) sage: sinh_integral(x)._sympy_() # needs sympy sage.symbolic Shi(x) - """ BuiltinFunction.__init__(self, "sinh_integral", nargs=1, latex_name=r'\operatorname{Shi}', @@ -1147,7 +1125,6 @@ def _eval_(self, z): 4.97344047585981 sage: sinh_integral(0) # needs mpmath 0 - """ # special case: z = 0 if isinstance(z, Expression): @@ -1164,7 +1141,6 @@ def _evalf_(self, z, parent=None, algorithm=None): 1.00000000000000000000055555556e-10 sage: sinh_integral(ComplexField(100)(I)) # needs sage.symbolic 0.94608307036718301494135331382*I - """ return _mpmath_utils_call(_mpmath_shi, z, parent=parent) @@ -1182,7 +1158,6 @@ def _derivative_(self, z, diff_param=None): sage: f = sinh_integral(ln(x)) sage: f.diff(x) 1/2*(x^2 - 1)/(x^2*log(x)) - """ return sinh(z)/z @@ -1264,7 +1239,6 @@ class Function_cosh_integral(BuiltinFunction): - mpmath documentation: `chi`_ .. _`chi`: http://mpmath.org/doc/current/functions/expintegrals.html#chi - """ def __init__(self): """ @@ -1276,7 +1250,6 @@ def __init__(self): cosh_integral(1) sage: cosh_integral(x)._sympy_() # needs sage.symbolic Chi(x) - """ BuiltinFunction.__init__(self, "cosh_integral", nargs=1, latex_name=r'\operatorname{Chi}', @@ -1292,7 +1265,6 @@ def _evalf_(self, z, parent=None, algorithm=None): -22.4486352650389239795709024568 sage: cosh_integral(ComplexField(100)(I)) # needs sage.symbolic 0.33740392290096813466264620389 + 1.5707963267948966192313216916*I - """ return _mpmath_utils_call(_mpmath_chi, z, parent=parent) @@ -1310,7 +1282,6 @@ def _derivative_(self, z, diff_param=None): sage: f = cosh_integral(ln(x)) sage: f.diff(x) 1/2*(x^2 + 1)/(x^2*log(x)) - """ return cosh(z)/z @@ -1440,7 +1411,7 @@ def _derivative_(self, x, diff_param=None): # moved here from sage/functions/transcendental.py def exponential_integral_1(x, n=0): r""" - Returns the exponential integral `E_1(x)`. If the optional + Return the exponential integral `E_1(x)`. If the optional argument `n` is given, computes list of the first `n` values of the exponential integral `E_1(x m)`. @@ -1458,8 +1429,7 @@ def exponential_integral_1(x, n=0): - ``n`` -- (default: 0) a nonnegative integer; if nonzero, then return a list of values ``E_1(x*m)`` for m = 1,2,3,...,n. This is useful, e.g., when computing derivatives of - L-functions. - + `L`-functions. OUTPUT: diff --git a/src/sage/functions/gamma.py b/src/sage/functions/gamma.py index be2d60d0861..c5b730eb65b 100644 --- a/src/sage/functions/gamma.py +++ b/src/sage/functions/gamma.py @@ -359,7 +359,7 @@ def __init__(self): sage: var('t') # needs sage.symbolic t - sage: integrate(-exp(-x)*x^(t-1), x, algorithm="fricas") # optional - fricas, needs sage.symbolic + sage: integrate(-exp(-x)*x^(t-1), x, algorithm='fricas') # optional - fricas, needs sage.symbolic gamma(t, x) .. SEEALSO:: @@ -816,7 +816,7 @@ def __init__(self): class Function_psi2(GinacFunction): def __init__(self): r""" - Derivatives of the digamma function `\psi(x)`. T + Derivatives of the digamma function `\psi(x)`. EXAMPLES:: @@ -979,7 +979,7 @@ def __init__(self): GiNaC is used to compute `\operatorname{B}(p,q)`. However, complex inputs are not yet handled in general. When GiNaC raises an error on - such inputs, we raise a NotImplementedError. + such inputs, we raise a :exc:`NotImplementedError`. If either input is 1, GiNaC returns the reciprocal of the other. In other cases, GiNaC uses one of the following @@ -1005,10 +1005,9 @@ def __init__(self): INPUT: - - ``p`` -- number or symbolic expression - - - ``q`` -- number or symbolic expression + - ``p`` -- number or symbolic expression + - ``q`` -- number or symbolic expression OUTPUT: number or symbolic expression (if input is symbolic) diff --git a/src/sage/functions/generalized.py b/src/sage/functions/generalized.py index 1305cd1dd25..f8f92b293a4 100644 --- a/src/sage/functions/generalized.py +++ b/src/sage/functions/generalized.py @@ -11,7 +11,6 @@ - Golam Mortuza Hossain (2009-06-26): initial version - EXAMPLES: Dirac delta function:: @@ -64,7 +63,7 @@ class FunctionDiracDelta(BuiltinFunction): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression DEFINITION: @@ -93,7 +92,6 @@ class FunctionDiracDelta(BuiltinFunction): REFERENCES: - :wikipedia:`Dirac_delta_function` - """ def __init__(self): r""" @@ -101,7 +99,7 @@ def __init__(self): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression EXAMPLES:: @@ -130,7 +128,7 @@ def _eval_(self, x): """ INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression EXAMPLES:: @@ -181,7 +179,7 @@ class FunctionHeaviside(GinacFunction): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression DEFINITION: @@ -231,7 +229,6 @@ class FunctionHeaviside(GinacFunction): REFERENCES: - :wikipedia:`Heaviside_function` - """ def __init__(self): r""" @@ -239,7 +236,7 @@ def __init__(self): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression EXAMPLES:: @@ -262,7 +259,7 @@ def __init__(self): sage: h(pi).numerical_approx() 1.00000000000000 """ - GinacFunction.__init__(self, "heaviside", latex_name="H", + GinacFunction.__init__(self, "heaviside", latex_name='H', conversions=dict(maxima='hstep', mathematica='HeavisideTheta', sympy='Heaviside', @@ -270,7 +267,7 @@ def __init__(self): def _derivative_(self, x, diff_param=None): """ - Derivative of Heaviside step function + Derivative of Heaviside step function. EXAMPLES:: @@ -289,7 +286,7 @@ class FunctionUnitStep(GinacFunction): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression DEFINITION: @@ -330,7 +327,7 @@ def __init__(self): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression EXAMPLES:: @@ -358,7 +355,7 @@ def __init__(self): def _derivative_(self, x, diff_param=None): """ - Derivative of unit step function + Derivative of unit step function. EXAMPLES:: @@ -377,7 +374,7 @@ class FunctionSignum(BuiltinFunction): INPUT: - - ``x`` -- a real number or a symbolic expression + - ``x`` -- a real number or a symbolic expression DEFINITION: @@ -427,7 +424,6 @@ class FunctionSignum(BuiltinFunction): REFERENCES: - :wikipedia:`Sign_function` - """ def __init__(self): r""" @@ -450,7 +446,7 @@ def __init__(self): conversions=dict(maxima='signum', mathematica='Sign', sympy='sign', giac='sign', fricas='(x+->abs(x)/x)'), - alt_name="sign") + alt_name='sign') def _eval_(self, x): """ @@ -517,7 +513,7 @@ def _evalf_(self, x, **kwds): if bool(approx_x.imag() == 0): # x is real if bool(approx_x.real() == 0): # x is zero return ZZ(0) - # Now we have a non-zero real + # Now we have a nonzero real if bool((approx_x**(0.5)).imag() == 0): # Check: x > 0 return ZZ(1) else: @@ -526,7 +522,7 @@ def _evalf_(self, x, **kwds): def _derivative_(self, x, diff_param=None): """ - Derivative of sgn function + Derivative of sgn function. EXAMPLES:: @@ -547,8 +543,8 @@ class FunctionKroneckerDelta(BuiltinFunction): INPUT: - - ``m`` -- a number or a symbolic expression - - ``n`` -- a number or a symbolic expression + - ``m`` -- a number or a symbolic expression + - ``n`` -- a number or a symbolic expression DEFINITION: @@ -570,7 +566,6 @@ class FunctionKroneckerDelta(BuiltinFunction): REFERENCES: - :wikipedia:`Kronecker_delta` - """ def __init__(self): r""" @@ -646,14 +641,14 @@ def _evalf_(self, m, n, **kwds): def _derivative_(self, *args, **kwds): """ - Derivative of Kronecker delta + Derivative of Kronecker delta. EXAMPLES:: sage: kronecker_delta(x, 1).diff(x) # needs sage.symbolic 0 """ - # Kronecker delta is non-zero (but finite) only in the set of + # Kronecker delta is nonzero (but finite) only in the set of # zero-measure unlike Dirac delta. Consequently, it is null # for the purpose of integration/differentiation. For *discrete sum* # Kronecker delta is however non-trivial. @@ -661,7 +656,7 @@ def _derivative_(self, *args, **kwds): def _print_latex_(self, m, n, **kwds): r""" - Return latex expression + Return latex expression. EXAMPLES:: diff --git a/src/sage/functions/hypergeometric.py b/src/sage/functions/hypergeometric.py index 010c61febe0..ade7836b310 100644 --- a/src/sage/functions/hypergeometric.py +++ b/src/sage/functions/hypergeometric.py @@ -274,9 +274,9 @@ def __call__(self, a, b, z, **kwargs): INPUT: - - ``a`` -- a list or tuple of parameters - - ``b`` -- a list or tuple of parameters - - ``z`` -- a number or symbolic expression + - ``a`` -- list or tuple of parameters + - ``b`` -- list or tuple of parameters + - ``z`` -- number or symbolic expression EXAMPLES:: @@ -307,7 +307,6 @@ def _print_latex_(self, a, b, z): sage: latex(hypergeometric([1, 1], [2], -1)) # needs sage.symbolic \,_2F_1\left(\begin{matrix} 1,1 \\ 2 \end{matrix} ; -1 \right) - """ aa = ",".join(latex(c) for c in a) bb = ",".join(latex(c) for c in b) @@ -370,7 +369,6 @@ def _evalf_(self, a, b, z, parent, algorithm=None): 0.693147180559945 sage: hypergeometric([], [], RealField(100)(1)) # needs sage.rings.real_mpfr sage.symbolic 2.7182818284590452353602874714 - """ if not isinstance(a, tuple) or not isinstance(b, tuple): raise TypeError("The first two parameters must be of type list") @@ -1038,7 +1036,6 @@ def generalized(self, a, b, z): (a, b, z) sage: hypergeometric_M(a, b, z).generalized() # needs sage.symbolic hypergeometric((a,), (b,), z) - """ return hypergeometric([a], [b], z) @@ -1150,7 +1147,6 @@ def generalized(self, a, b, z): 2*hypergeometric((1, -1), (), -2) sage: hypergeometric_U(3, I, 2).generalized() 1/8*hypergeometric((3, -I + 4), (), -1/2) - """ return z ** (-a) * hypergeometric([a, a - b + 1], [], -z ** (-1)) diff --git a/src/sage/functions/jacobi.py b/src/sage/functions/jacobi.py index 063dc8c7b78..9e5e6ae3849 100644 --- a/src/sage/functions/jacobi.py +++ b/src/sage/functions/jacobi.py @@ -935,7 +935,7 @@ def jacobi(kind, z, m, **kwargs): INPUT: - - ``kind`` -- a string of the form ``'pq'``, where ``p``, ``q`` are in + - ``kind`` -- string of the form ``'pq'``, where ``p``, ``q`` are in ``c``, ``d``, ``n``, ``s`` - ``z`` -- a complex number - ``m`` -- a complex number; note that `m = k^2`, where `k` is @@ -998,7 +998,7 @@ def inverse_jacobi(kind, x, m, **kwargs): INPUT: - - ``kind`` -- a string of the form ``'pq'``, where ``p``, ``q`` are in + - ``kind`` -- string of the form ``'pq'``, where ``p``, ``q`` are in ``c``, ``d``, ``n``, ``s`` - ``x`` -- a real number - ``m`` -- a real number; note that `m = k^2`, where `k` is the elliptic diff --git a/src/sage/functions/log.py b/src/sage/functions/log.py index 5940fe0281f..de1db4dcb92 100644 --- a/src/sage/functions/log.py +++ b/src/sage/functions/log.py @@ -573,7 +573,7 @@ class Function_lambert_w(BuiltinFunction): INPUT: - - ``n`` -- an integer. `n=0` corresponds to the principal branch. + - ``n`` -- integer; `n=0` corresponds to the principal branch - ``z`` -- a complex number @@ -920,7 +920,7 @@ def __init__(self): INPUT: - - ``z`` -- a complex number `z = a + ib`. + - ``z`` -- a complex number `z = a + ib` OUTPUT: @@ -989,7 +989,6 @@ def _evalf_(self, z, parent=None, algorithm=None): Traceback (most recent call last): ... ValueError: invalid attempt to numerically evaluate exp_polar() - """ if (not isinstance(z, Expression) and bool(-const_pi < imag(z) <= const_pi)): diff --git a/src/sage/functions/orthogonal_polys.py b/src/sage/functions/orthogonal_polys.py index 70514cc3f44..78f4c6bc712 100644 --- a/src/sage/functions/orthogonal_polys.py +++ b/src/sage/functions/orthogonal_polys.py @@ -811,7 +811,7 @@ def eval_formula(self, n, x): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``x`` -- a value to evaluate the polynomial at (this can be any ring element) @@ -852,7 +852,7 @@ def eval_algebraic(self, n, x): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``x`` -- a value to evaluate the polynomial at (this can be any ring element) @@ -1035,7 +1035,7 @@ def eval_formula(self, n, x): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``x`` -- a value to evaluate the polynomial at (this can be any ring element) @@ -1072,7 +1072,7 @@ def eval_algebraic(self, n, x): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - ``x`` -- a value to evaluate the polynomial at (this can be any ring element) @@ -1612,7 +1612,7 @@ class Func_assoc_legendre_P(BuiltinFunction): EXAMPLES: - We give the first Ferrers functions for non-negative integers + We give the first Ferrers functions for nonnegative integers `n` and `m` in the interval `-1 -1`, `|m| \leq n`, simplification is done automatically. Numeric evaluation is supported for complex `n` and `m`. @@ -236,7 +236,6 @@ class SphericalHarmonic(BuiltinFunction): REFERENCES: - :wikipedia:`Spherical_harmonics` - """ def __init__(self): r""" @@ -298,7 +297,6 @@ def _eval_(self, n, m, theta, phi, **kwargs): -1/4*sqrt(6)*sqrt(5)*cos(x)*e^(I*y)*sin(x)/sqrt(pi) sage: spherical_harmonic(5, -3, x, y) # needs sage.symbolic -1/32*(9*sqrt(385)*sin(x)^4 - 8*sqrt(385)*sin(x)^2)*e^(-3*I*y)*sin(x)/sqrt(pi) - """ if n in ZZ and m in ZZ and n > -1: if abs(m) > n: @@ -330,7 +328,6 @@ def _evalf_(self, n, m, theta, phi, parent, **kwds): sage: ab = [(0, 0), (1, -1), (1, 0), (1, 1), (3, 2), (3, 3)] sage: all(d(a, b) < 1e-14 for a, b in ab) # needs sage.symbolic True - """ return _mpmath_utils_call(_mpmath_spherharm, n, m, theta, phi, parent=parent) @@ -360,7 +357,6 @@ def _derivative_(self, n, m, theta, phi, diff_param): True sage: bool(DY_theta.subs({n: 1, m: -1}) == Ynm.subs({n: 1, m: -1}).diff(theta)) True - """ if diff_param == 2: return (m * cot(theta) * spherical_harmonic(n, m, theta, phi) + @@ -400,17 +396,15 @@ def _print_latex_(self, n, m, theta, phi): def elliptic_j(z, prec=53): r""" - Returns the elliptic modular `j`-function evaluated at `z`. + Return the elliptic modular `j`-function evaluated at `z`. INPUT: - - ``z`` (complex) -- a complex number with positive imaginary part. + - ``z`` -- complex; a complex number with positive imaginary part - - ``prec`` (default: 53) -- precision in bits for the complex field. + - ``prec`` -- (default: 53) precision in bits for the complex field - OUTPUT: - - (complex) The value of `j(z)`. + OUTPUT: (complex) the value of `j(z)` ALGORITHM: @@ -538,7 +532,6 @@ def __init__(self): 0.000000000000000, 0.000000000000000, 0.000000000000000] - """ BuiltinFunction.__init__(self, 'elliptic_e', nargs=2, # Maple conversion left out since it uses @@ -904,7 +897,6 @@ def __init__(self): 0.000000000000000, 0.000000000000000, 0.000000000000000] - """ BuiltinFunction.__init__(self, 'elliptic_f', nargs=2, conversions=dict(mathematica='EllipticF', diff --git a/src/sage/functions/spike_function.py b/src/sage/functions/spike_function.py index c2fb6113e39..d7e317ba615 100644 --- a/src/sage/functions/spike_function.py +++ b/src/sage/functions/spike_function.py @@ -32,13 +32,11 @@ class SpikeFunction: INPUT: - - ``v`` -- list of pairs (x, height) + - ``v`` -- list of pairs (x, height) - - ``eps`` -- parameter that determines approximation to a true spike + - ``eps`` -- parameter that determines approximation to a true spike - OUTPUT: - - a function with spikes at each point ``x`` in ``v`` with the given height. + OUTPUT: a function with spikes at each point ``x`` in ``v`` with the given height EXAMPLES:: diff --git a/src/sage/functions/transcendental.py b/src/sage/functions/transcendental.py index 3dcb446e706..7cfa2640473 100644 --- a/src/sage/functions/transcendental.py +++ b/src/sage/functions/transcendental.py @@ -44,7 +44,7 @@ def __init__(self): INPUT: - - ``s`` -- real or complex number + - ``s`` -- real or complex number If s is a real number, the computation is done using the MPFR library. When the input is not real, the computation is done using @@ -173,7 +173,7 @@ def __init__(self): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -305,7 +305,7 @@ def hurwitz_zeta(s, x, **kwargs): When `x = 1`, this coincides with Riemann's zeta function. - The Dirichlet L-functions may be expressed as linear combinations + The Dirichlet `L`-functions may be expressed as linear combinations of Hurwitz zeta functions. EXAMPLES: @@ -378,7 +378,7 @@ def __init__(self): zetaderiv([1.500000000 +/- 1.01e-10], 1) """ GinacFunction.__init__(self, "zetaderiv", nargs=2, - conversions=dict(maple="Zeta")) + conversions=dict(maple='Zeta')) def _evalf_(self, n, x, parent=None, algorithm=None): r""" @@ -412,9 +412,7 @@ def zeta_symmetric(s): INPUT: - - - ``s`` -- real or complex number - + - ``s`` -- real or complex number If s is a real number the computation is done using the MPFR library. When the input is not real, the computation is done using @@ -426,7 +424,6 @@ def zeta_symmetric(s): xi(s) = \gamma(s/2 + 1) * (s-1) * \pi^{-s/2} * \zeta(s). - EXAMPLES:: sage: # needs sage.rings.real_mpfr @@ -518,7 +515,7 @@ class DickmanRho(BuiltinFunction): """ def __init__(self): """ - Constructs an object to represent Dickman's rho function. + Construct an object to represent Dickman's rho function. TESTS:: @@ -574,11 +571,11 @@ def power_series(self, n, abs_prec): INPUT: - - ``n`` -- the lower endpoint of the interval for which - this power series holds + - ``n`` -- the lower endpoint of the interval for which + this power series holds - - ``abs_prec`` -- the absolute precision of the - resulting power series + - ``abs_prec`` -- the absolute precision of the + resulting power series EXAMPLES:: @@ -602,14 +599,14 @@ def _compute_power_series(self, n, abs_prec, cache_ring=None): INPUT: - - ``n`` -- the lower endpoint of the interval for which - this power series holds + - ``n`` -- the lower endpoint of the interval for which + this power series holds - - ``abs_prec`` -- the absolute precision of the - resulting power series + - ``abs_prec`` -- the absolute precision of the + resulting power series - - ``cache_ring`` -- for internal use, caches the power - series at this precision. + - ``cache_ring`` -- for internal use, caches the power + series at this precision EXAMPLES:: @@ -653,7 +650,7 @@ def _compute_power_series(self, n, abs_prec, cache_ring=None): def approximate(self, x, parent=None): r""" - Approximate using de Bruijn's formula + Approximate using de Bruijn's formula. .. MATH:: diff --git a/src/sage/functions/trig.py b/src/sage/functions/trig.py index b767fbbd5d4..f912dd79e8f 100644 --- a/src/sage/functions/trig.py +++ b/src/sage/functions/trig.py @@ -572,7 +572,7 @@ def __init__(self): GinacFunction.__init__(self, 'arcsin', latex_name=r"\arcsin", conversions=dict(maxima='asin', sympy='asin', mathematica='ArcSin', - fricas="asin", giac="asin")) + fricas='asin', giac='asin')) arcsin = asin = Function_arcsin() @@ -762,7 +762,6 @@ def __init__(self): (0.5535743588970452-0.4023594781085251j) sage: arccot(1.+I) # needs sage.symbolic 0.553574358897045 - 0.402359478108525*I - """ GinacFunction.__init__(self, 'arccot', latex_name=r"\operatorname{arccot}", conversions=dict(maxima='acot', sympy='acot', @@ -927,7 +926,6 @@ def __init__(self): Note that the `y`-coordinate is by convention the first input. - EXAMPLES: Note the difference between the two functions:: diff --git a/src/sage/functions/wigner.py b/src/sage/functions/wigner.py index 5a19010f073..e177fc1287b 100644 --- a/src/sage/functions/wigner.py +++ b/src/sage/functions/wigner.py @@ -44,11 +44,9 @@ def _calc_factlist(nn): INPUT: - - ``nn`` -- integer, highest factorial to be computed + - ``nn`` -- integer; highest factorial to be computed - OUTPUT: - - list of integers -- the list of precomputed factorials + OUTPUT: list of integers -- the list of precomputed factorials EXAMPLES: @@ -70,10 +68,10 @@ def wigner_3j(j_1, j_2, j_3, m_1, m_2, m_3, prec=None): INPUT: - - ``j_1``, ``j_2``, ``j_3``, ``m_1``, ``m_2``, ``m_3`` -- integer or half integer + - ``j_1``, ``j_2``, ``j_3``, ``m_1``, ``m_2``, ``m_3`` -- integer or half integer - - ``prec`` -- precision, default: ``None``. Providing a precision can - drastically speed up the calculation. + - ``prec`` -- precision (default: ``None``); providing a precision can + drastically speed up the calculation OUTPUT: @@ -215,10 +213,10 @@ def clebsch_gordan(j_1, j_2, j_3, m_1, m_2, m_3, prec=None): INPUT: - - ``j_1``, ``j_2``, ``j_3``, ``m_1``, ``m_2``, ``m_3`` -- integer or half integer + - ``j_1``, ``j_2``, ``j_3``, ``m_1``, ``m_2``, ``m_3`` -- integer or half integer - - ``prec`` -- precision, default: ``None``. Providing a precision can - drastically speed up the calculation. + - ``prec`` -- precision (default: ``None``); providing a precision can + drastically speed up the calculation OUTPUT: @@ -264,17 +262,15 @@ def _big_delta_coeff(aa, bb, cc, prec=None): INPUT: - - ``aa`` -- first angular momentum, integer or half integer + - ``aa`` -- first angular momentum, integer or half integer - - ``bb`` -- second angular momentum, integer or half integer + - ``bb`` -- second angular momentum, integer or half integer - - ``cc`` -- third angular momentum, integer or half integer + - ``cc`` -- third angular momentum, integer or half integer - - ``prec`` -- precision of the ``sqrt()`` calculation - - OUTPUT: + - ``prec`` -- precision of the ``sqrt()`` calculation - double - Value of the Delta coefficient + OUTPUT: double - Value of the Delta coefficient EXAMPLES:: @@ -317,10 +313,10 @@ def racah(aa, bb, cc, dd, ee, ff, prec=None): INPUT: - - ``aa``, ..., ``ff`` -- integer or half integer + - ``aa``, ..., ``ff`` -- integer or half integer - - ``prec`` -- precision, default: ``None``. Providing a precision can - drastically speed up the calculation. + - ``prec`` -- precision (default: ``None``); providing a precision can + drastically speed up the calculation OUTPUT: @@ -390,10 +386,10 @@ def wigner_6j(j_1, j_2, j_3, j_4, j_5, j_6, prec=None): INPUT: - - ``j_1``, ..., ``j_6`` -- integer or half integer + - ``j_1``, ..., ``j_6`` -- integer or half integer - - ``prec`` -- precision, default: ``None``. Providing a precision can - drastically speed up the calculation. + - ``prec`` -- precision (default: ``None``); providing a precision can + drastically speed up the calculation OUTPUT: @@ -465,7 +461,7 @@ def wigner_6j(j_1, j_2, j_3, j_4, j_5, j_6, prec=None): - additional 6 symmetries [Reg1959]_ giving rise to 144 symmetries in total - - only non-zero if any triple of `j`'s fulfill a triangle relation + - only nonzero if any triple of `j`'s fulfill a triangle relation ALGORITHM: @@ -487,10 +483,10 @@ def wigner_9j(j_1, j_2, j_3, j_4, j_5, j_6, j_7, j_8, j_9, prec=None): INPUT: - - ``j_1``, ..., ``j_9`` -- integer or half integer + - ``j_1``, ..., ``j_9`` -- integer or half integer - - ``prec`` -- precision, default: ``None``. Providing a precision can - drastically speed up the calculation. + - ``prec`` -- precision (default: ``None``); providing a precision can + drastically speed up the calculation OUTPUT: @@ -578,10 +574,10 @@ def gaunt(l_1, l_2, l_3, m_1, m_2, m_3, prec=None): INPUT: - - ``l_1``, ``l_2``, ``l_3``, ``m_1``, ``m_2``, ``m_3`` -- integer + - ``l_1``, ``l_2``, ``l_3``, ``m_1``, ``m_2``, ``m_3`` -- integer - - ``prec`` -- precision, default: ``None``. Providing a precision can - drastically speed up the calculation. + - ``prec`` -- precision (default: ``None``); providing a precision can + drastically speed up the calculation OUTPUT: @@ -660,7 +656,7 @@ def gaunt(l_1, l_2, l_3, m_1, m_2, m_3, prec=None): - zero for violating any one of the conditions: `l_1 \ge |m_1|`, `l_2 \ge |m_2|`, `l_3 \ge |m_3|` - - non-zero only for an even sum of the `l_i`, i.e. + - nonzero only for an even sum of the `l_i`, i.e. `J=l_1+l_2+l_3=2n` for `n` in `\Bold{N}` ALGORITHM: diff --git a/src/sage/game_theory/catalog_normal_form_games.py b/src/sage/game_theory/catalog_normal_form_games.py index ab7b48a4dc0..705957f079e 100644 --- a/src/sage/game_theory/catalog_normal_form_games.py +++ b/src/sage/game_theory/catalog_normal_form_games.py @@ -128,7 +128,6 @@ def PrisonersDilemma(R=-2, P=-4, S=-5, T=0): ... TypeError: the input values for a Prisoners Dilemma must be of the form T > R > P > S - """ if not (T > R > P > S): raise TypeError("the input values for a Prisoners Dilemma must be of the form T > R > P > S") @@ -319,7 +318,6 @@ def StagHunt(): True sage: g.obtain_nash() [[(0, 1), (0, 1)], [(2/3, 1/3), (2/3, 1/3)], [(1, 0), (1, 0)]] - """ g = CoordinationGame(A=5, a=5, B=4, b=0, C=0, c=4, D=2, d=2) g.rename('Stag hunt - ' + repr(g)) @@ -550,7 +548,6 @@ def Pigs(): True sage: g.obtain_nash() [[(1, 0), (0, 1)]] - """ from sage.matrix.constructor import matrix A = matrix([[3, 1], [6, 0]]) @@ -915,7 +912,6 @@ def TravellersDilemma(max_value=10): True sage: g.obtain_nash() [[(0, 0, 0, 1), (0, 0, 0, 1)]] - """ from sage.matrix.constructor import matrix from sage.functions.generalized import sign diff --git a/src/sage/game_theory/cooperative_game.py b/src/sage/game_theory/cooperative_game.py index b95ba0f655a..c9253d2bbb0 100644 --- a/src/sage/game_theory/cooperative_game.py +++ b/src/sage/game_theory/cooperative_game.py @@ -33,7 +33,7 @@ class CooperativeGame(SageObject): INPUT: - - ``characteristic_function`` -- a dictionary containing all possible + - ``characteristic_function`` -- dictionary containing all possible sets of players: * key - each set must be entered as a tuple. @@ -254,7 +254,7 @@ class CooperativeGame(SageObject): """ def __init__(self, characteristic_function): r""" - Initializes a co-operative game and checks the inputs. + Initialize a co-operative game and checks the inputs. TESTS: @@ -616,7 +616,7 @@ def is_efficient(self, payoff_vector): INPUT: - - ``payoff_vector`` -- a dictionary where the key is the player + - ``payoff_vector`` -- dictionary where the key is the player and the value is their payoff EXAMPLES: @@ -684,7 +684,7 @@ def nullplayer(self, payoff_vector): INPUT: - - ``payoff_vector`` -- a dictionary where the key is the player + - ``payoff_vector`` -- dictionary where the key is the player and the value is their payoff EXAMPLES: @@ -775,7 +775,7 @@ def is_symmetric(self, payoff_vector): INPUT: - - ``payoff_vector`` -- a dictionary where the key is the player + - ``payoff_vector`` -- dictionary where the key is the player and the value is their payoff EXAMPLES: diff --git a/src/sage/game_theory/matching_game.py b/src/sage/game_theory/matching_game.py index 8efa2c2acfa..5b3f081bf10 100644 --- a/src/sage/game_theory/matching_game.py +++ b/src/sage/game_theory/matching_game.py @@ -73,7 +73,7 @@ class MatchingGame(SageObject): Two potential inputs are accepted (see below to see the effect of each): - - ``reviewer/suitors_preferences`` -- a dictionary containing the + - ``reviewer/suitors_preferences`` -- dictionary containing the preferences of all players: * key - each reviewer/suitors @@ -81,8 +81,8 @@ class MatchingGame(SageObject): OR: - - ``integer`` -- an integer simply representing the number of reviewers - and suitors. + - ``integer`` -- integer simply representing the number of reviewers + and suitors To implement the above game in Sage:: @@ -1025,7 +1025,7 @@ def __eq__(self, other): def __lt__(self, other): """ - Tests less than inequality of two players. Allows for players to be + Test less than inequality of two players. Allows for players to be sorted on their names. TESTS:: @@ -1051,7 +1051,7 @@ def __lt__(self, other): def __gt__(self, other): """ - Tests greater than inequality of two players. Allows for players to be + Test greater than inequality of two players. Allows for players to be sorted on their names. TESTS:: @@ -1077,7 +1077,7 @@ def __gt__(self, other): def __ge__(self, other): """ - Tests greater than or equal inequality of two players. Allows for + Test greater than or equal inequality of two players. Allows for players to be sorted on their names. TESTS:: @@ -1113,7 +1113,7 @@ def __ge__(self, other): def __le__(self, other): """ - Tests less than or equal inequality of two players. Allows for + Test less than or equal inequality of two players. Allows for players to be sorted on their names. TESTS:: @@ -1149,7 +1149,7 @@ def __le__(self, other): def __ne__(self, other): """ - Tests inequality of two players. Allows for + Test inequality of two players. Allows for players to be sorted on their names. TESTS:: diff --git a/src/sage/game_theory/normal_form_game.py b/src/sage/game_theory/normal_form_game.py index 2b1e592c4e8..8f19e4842e1 100644 --- a/src/sage/game_theory/normal_form_game.py +++ b/src/sage/game_theory/normal_form_game.py @@ -665,12 +665,11 @@ class NormalFormGame(SageObject, MutableMapping): - ``generator`` -- can be a list of 2 matrices, a single matrix or left blank - """ def __init__(self, generator=None): r""" - Initializes a Normal Form game and checks the inputs. + Initialize a Normal Form game and checks the inputs. EXAMPLES: @@ -763,7 +762,6 @@ def __init__(self, generator=None): sage: game = NormalFormGame() sage: game Normal Form Game with the following utilities: {} - """ self.players = [] self.utilities = {} @@ -971,7 +969,7 @@ def _two_matrix_game(self, matrices): def _gambit_game(self, game): r""" - Creates a ``NormalFormGame`` object from a Gambit game. + Create a ``NormalFormGame`` object from a Gambit game. TESTS:: @@ -1004,7 +1002,7 @@ def _gambit_game(self, game): def _gambit_(self, as_integer=False, maximization=True): r""" - Creates a Gambit game from a ``NormalFormGame`` object + Create a Gambit game from a ``NormalFormGame`` object. INPUT: @@ -1165,7 +1163,7 @@ def _gambit_(self, as_integer=False, maximization=True): def is_constant_sum(self): r""" - Checks if the game is constant sum. + Check if the game is constant sum. EXAMPLES:: @@ -1294,7 +1292,7 @@ def _generate_utilities(self, replacement): INPUT: - - ``replacement`` -- Boolean value of whether previously created + - ``replacement`` -- boolean value of whether previously created profiles should be replaced or not TESTS:: @@ -1367,7 +1365,6 @@ def add_strategy(self, player): (1, 1): [3, 0], (2, 0): [False, False], (2, 1): [False, False]} - """ self.players[player].add_strategy() self._generate_utilities(False) @@ -1404,17 +1401,17 @@ def obtain_nash(self, algorithm=False, maximization=True, solver=None): - ``algorithm`` -- the following algorithms should be available through this function: - * ``'lrs'`` -- This algorithm is only suited for 2 player games. + * ``'lrs'`` -- this algorithm is only suited for 2 player games. See the lrs web site (http://cgm.cs.mcgill.ca/~avis/C/lrs.html). - * ``'LCP'`` -- This algorithm is only suited for 2 player games. + * ``'LCP'`` -- this algorithm is only suited for 2 player games. See the gambit web site (http://gambit.sourceforge.net/). - * ``'lp'`` -- This algorithm is only suited for 2 player + * ``'lp'`` -- this algorithm is only suited for 2 player constant sum games. Uses MILP solver determined by the ``solver`` argument. - * ``'enumeration'`` -- This is a very inefficient + * ``'enumeration'`` -- this is a very inefficient algorithm (in essence a brute force approach). 1. For each k in 1...min(size of strategy sets) @@ -1453,7 +1450,7 @@ def obtain_nash(self, algorithm=False, maximization=True, solver=None): \sum_{j\in S(\rho_1)}{\rho_2}_j = 1 - - ``maximization`` -- (default: ``True``) whether a player is + - ``maximization`` -- boolean (default: ``True``); whether a player is trying to maximize their utility or minimize it: * When set to ``True`` it is assumed that players aim to @@ -1589,7 +1586,7 @@ def obtain_nash(self, algorithm=False, maximization=True, solver=None): [[(0, 0, 1, 0), (0, 0, 1)]] Running the constant-sum solver on a game which is not a constant sum - game generates a :class:`ValueError`:: + game generates a :exc:`ValueError`:: sage: cg = NormalFormGame([A, A]) sage: cg.obtain_nash(algorithm='lp', solver='glpk') @@ -1665,11 +1662,11 @@ def obtain_nash(self, algorithm=False, maximization=True, solver=None): sage: A = matrix.identity(2) sage: g = NormalFormGame([A]) - sage: g.obtain_nash(algorithm="invalid") + sage: g.obtain_nash(algorithm='invalid') Traceback (most recent call last): ... ValueError: 'algorithm' should be set to 'enumeration', 'LCP', 'lp' or 'lrs' - sage: g.obtain_nash(algorithm="lp", solver="invalid") + sage: g.obtain_nash(algorithm='lp', solver='invalid') Traceback (most recent call last): ... ValueError: 'solver' should be set to 'GLPK', ..., None @@ -1823,7 +1820,7 @@ def _solve_gambit_LP(self, maximization=True): def _solve_LP(self, solver='glpk', maximization=True): r""" - Solves a constant sum :class:`NormalFormGame` using + Solve a constant sum :class:`NormalFormGame` using the specified LP solver. INPUT: @@ -2284,7 +2281,6 @@ def _Hrepresentation(self, m1, m2): -1 1 1 0 end - """ from sage.misc.superseded import deprecation deprecation(27745, @@ -2605,7 +2601,7 @@ def best_responses(self, strategy, player): - ``strategy`` -- a probability distribution vector - ``player`` -- the index of the opponent, ``0`` for the row player, - ``1`` for the column player. + ``1`` for the column player EXAMPLES:: @@ -2726,7 +2722,7 @@ def best_responses(self, strategy, player): def _is_degenerate_pure(self, certificate=False): """ - Checks whether a game is degenerate in pure strategies. + Check whether a game is degenerate in pure strategies. TESTS:: diff --git a/src/sage/games/hexad.py b/src/sage/games/hexad.py index ddc08530b08..5d3e2785900 100644 --- a/src/sage/games/hexad.py +++ b/src/sage/games/hexad.py @@ -87,7 +87,7 @@ def view_list(L): EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: view_list(M.line[1]) [0 0 0] @@ -114,7 +114,7 @@ def picture_set(A, L) -> set: EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: picture_set(M.picture00, M.cross[2]) {5, 7, 8, 9, 10} sage: picture_set(M.picture02, M.square[7]) @@ -131,7 +131,7 @@ class Minimog: EXAMPLES:: sage: from sage.games.hexad import * - sage: Minimog(type="shuffle") + sage: Minimog(type='shuffle') Minimog of type shuffle sage: M = Minimog(type = "modulo11") sage: M.minimog @@ -139,7 +139,7 @@ class Minimog: [ 5 9 8 10] [ 4 1 6 7] """ - def __init__(self, type="shuffle"): + def __init__(self, type='shuffle'): self.type = type MS34 = MatrixSpace(SR, 3, 4) minimog_modulo11 = MS34([[0, 3, infinity, 2], [5, 9, 8, 10], [4, 1, 6, 7]]) @@ -225,7 +225,7 @@ def __repr__(self) -> str: EXAMPLES:: - sage: M = Minimog(type="modulo11") + sage: M = Minimog(type='modulo11') sage: M Minimog of type modulo11 """ @@ -235,23 +235,22 @@ def __str__(self) -> str: """ EXAMPLES:: - sage: M = Minimog(type="modulo11") + sage: M = Minimog(type='modulo11') sage: print(M) Minimog of type modulo11 associated to [ 0 3 +Infinity 2] [ 5 9 8 10] [ 4 1 6 7] - """ return f"Minimog of type {self.type} associated to\n {self.minimog}" def _latex_(self): r""" - Prints latex code. + Print latex code. EXAMPLES:: - sage: M = Minimog(type="modulo11") + sage: M = Minimog(type='modulo11') sage: latex(M) Minimog of type modulo11 associated to $\left(\begin{array}{rrrr} @@ -293,7 +292,6 @@ def print_kitten(self): 2 10 8 2 10 0 1 - """ MINIMOG = self.minimog kitten = f' {MINIMOG[0][2]}' @@ -313,7 +311,7 @@ def find_hexad0(self, pts): INPUT: - - ``pts`` -- a set of 2 distinct elements of MINIMOG, but not + - ``pts`` -- set of 2 distinct elements of MINIMOG, but not including the "points at infinity" OUTPUT: @@ -329,10 +327,9 @@ def find_hexad0(self, pts): EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: M.find_hexad0(set([2, 4])) ([0, 1, 2, 4, 6, 8], ['line 1', 'picture 1']) - """ MINIMOG = self.minimog L = set(pts) @@ -358,7 +355,7 @@ def find_hexad1(self, pts): INPUT: - - ``pts`` -- a set of 5 distinct elements of MINIMOG + - ``pts`` -- set of 5 distinct elements of MINIMOG OUTPUT: @@ -373,7 +370,7 @@ def find_hexad1(self, pts): EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: M.find_hexad1(set([2, 3, 4, 5, 8])) ([2, 3, 4, 5, 8, 11], ['lines (1, 2)', 'picture 1']) """ @@ -404,18 +401,16 @@ def find_hexad2(self, pts, x0): INPUT: - - ``pts`` -- a list S of 4 elements of MINIMOG, not including + - ``pts`` -- list S of 4 elements of MINIMOG, not including any "points at infinity" - ``x0`` -- in ``{MINIMOG[0][2], MINIMOG[2][1], MINIMOG[0][0]}`` - OUTPUT: - - hexad containing `S \cup \{x0\}` of type 2 + OUTPUT: hexad containing `S \cup \{x0\}` of type 2 EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: M.find_hexad2([2, 3, 4, 5], 1) ([], []) @@ -450,9 +445,9 @@ def find_hexad3(self, pts, x0, x1): INPUT: - - ``pts`` -- a list of 3 elements of MINIMOG, not including any + - ``pts`` -- list of 3 elements of MINIMOG, not including any "points at infinity" - - ``x0``, ``x1`` -- in ``{MINIMOG[0][2], MINIMOG[2][1], + - ``x0``, ``x1`` -- in ``{MINIMOG[0][2], MINIMOG[2][1], MINIMOG[0][0]}`` OUTPUT: @@ -463,10 +458,9 @@ def find_hexad3(self, pts, x0, x1): EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: M.find_hexad3([2, 3, 4], 0, 1) ([0, 1, 2, 3, 4, 11], ['square 2', 'picture 6']) - """ MINIMOG = self.minimog L = set(pts) @@ -492,11 +486,9 @@ def find_hexad(self, pts): INPUT: - - ``pts`` -- a list S of 5 elements of MINIMOG - - OUTPUT: + - ``pts`` -- list S of 5 elements of MINIMOG - hexad containing `S \cup \{x0\}` of some type + OUTPUT: hexad containing `S \cup \{x0\}` of some type .. NOTE:: @@ -521,7 +513,7 @@ def find_hexad(self, pts): EXAMPLES:: sage: from sage.games.hexad import * - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: M.find_hexad([0, 1, 2, 3, 4]) ([0, 1, 2, 3, 4, 11], ['square 2', 'picture 6']) sage: M.find_hexad([1, 2, 3, 4, 5]) @@ -530,7 +522,7 @@ def find_hexad(self, pts): ([2, 3, 4, 5, 8, 11], ['lines (1, 2)', 'picture 1']) sage: M.find_hexad([0, 1, 2, 4, 6]) ([0, 1, 2, 4, 6, 8], ['line 1', 'picture 1']) - sage: M = Minimog(type="modulo11") + sage: M = Minimog(type='modulo11') sage: M.find_hexad([1, 2, 3, 4, SR(infinity)]) # random (machine dependent?) order ([+Infinity, 2, 3, 4, 1, 10], ['square 8', 'picture 0']) @@ -624,7 +616,7 @@ def blackjack_move(self, L0): INPUT: - - ``L0`` -- a list of cards of length 6, taken + - ``L0`` -- list of cards of length 6, taken from `\{0, 1, ..., 11\}` .. RUBRIC:: MATHEMATICAL BLACKJACK @@ -659,10 +651,10 @@ def blackjack_move(self, L0): EXAMPLES:: - sage: M = Minimog(type="modulo11") + sage: M = Minimog(type='modulo11') sage: M.blackjack_move([0, 2, 3, 6, 1, 10]) '6 --> 5. The total went from 22 to 21.' - sage: M = Minimog(type="shuffle") + sage: M = Minimog(type='shuffle') sage: M.blackjack_move([0, 2, 4, 6, 7, 11]) '4 --> 3. The total went from 30 to 29.' diff --git a/src/sage/games/quantumino.py b/src/sage/games/quantumino.py index fa0a013ff6a..e40dc47f407 100644 --- a/src/sage/games/quantumino.py +++ b/src/sage/games/quantumino.py @@ -215,9 +215,7 @@ def show_pentaminos(box=(5,8,2)): - ``box`` -- tuple of size three (default: ``(5,8,2)``), size of the box - OUTPUT: - - 3D Graphic object + OUTPUT: 3D Graphic object EXAMPLES:: @@ -348,9 +346,7 @@ def show3d(self, size=0.85): r""" Return the solution as a 3D Graphic object. - OUTPUT: - - 3D Graphic Object + OUTPUT: 3D Graphic Object EXAMPLES:: @@ -429,7 +425,7 @@ def __init__(self, aside, box=(5, 8, 2)): def __repr__(self): r""" - String representation + String representation. EXAMPLES:: @@ -484,9 +480,7 @@ def solve(self, partial=None): - ``'common'`` -- common part between two consecutive solutions - ``'incremental'`` -- one piece change at a time - OUTPUT: - - iterator of QuantuminoState + OUTPUT: iterator of :class:`QuantuminoState` EXAMPLES: @@ -574,9 +568,7 @@ def number_of_solutions(self): r""" Return the number of solutions. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/games/sudoku.py b/src/sage/games/sudoku.py index d8cfb504e14..c1b3fa8b62d 100644 --- a/src/sage/games/sudoku.py +++ b/src/sage/games/sudoku.py @@ -26,7 +26,7 @@ def sudoku(m): r""" - Solves Sudoku puzzles described by matrices. + Solve Sudoku puzzles described by matrices. INPUT: @@ -91,13 +91,14 @@ class Sudoku(SageObject): INPUT: - - puzzle -- the first argument can take one of three forms + - ``puzzle`` -- the first argument can take one of three forms * list - a Python list with elements of the puzzle in row-major order, where a blank entry is a zero * matrix - a square Sage matrix over `\ZZ` * string - a string where each character is an entry of the puzzle. For two-digit entries, a = 10, b = 11, etc. - - verify_input -- default = ``True``, use ``False`` if you know the input is valid + - ``verify_input`` -- boolean (default: ``True``); use ``False`` if you know + the input is valid EXAMPLES:: @@ -203,7 +204,7 @@ def __init__(self, puzzle, verify_input=True): def __eq__(self, other): r""" - Compares two Sudoku puzzles, based on the underlying + Compare two Sudoku puzzles, based on the underlying representation of the puzzles as tuples. EXAMPLES:: @@ -269,7 +270,6 @@ def _repr_(self): sage: s = Sudoku('.4..32....14..3.') sage: s._repr_() '+---+---+\n| 4| |\n|3 2| |\n+---+---+\n| |1 4|\n| |3 |\n+---+---+' - """ return self.to_ascii() @@ -480,8 +480,9 @@ def solve(self, algorithm='dlx'): INPUT: - - algorithm -- default = ``'dlx'``, specify choice of solution algorithm. The - two possible algorithms are ``'dlx'`` and ``'backtrack'``. + - ``algorithm`` -- string (default: ``'dlx'``); specify choice of + solution algorithm. The two possible algorithms are ``'dlx'`` and + ``'backtrack'`` OUTPUT: @@ -727,14 +728,12 @@ def dlx(self, count_only=False): INPUT: - - count_only -- boolean, default = False. - If set to ``True`` the generator returned as output will + - ``count_only`` -- boolean (default: ``False``); + if set to ``True`` the generator returned as output will simply generate ``None`` for each solution, so the - calling routine can count these. - - OUTPUT: + calling routine can count these - A generator that iterates over all the solutions. + OUTPUT: a generator that iterates over all the solutions This function is intended to be called from the :func:`~sage.games.sudoku.Sudoku.solve` method @@ -840,7 +839,7 @@ def dlx(self, count_only=False): def make_row(row, col, entry): r""" - Constructs a row of the `0-1` matrix describing + Construct a row of the `0-1` matrix describing the exact cover constraints for a Sudoku puzzle. If a (zero-based) ``entry`` is placed in location diff --git a/src/sage/games/sudoku_backtrack.pyx b/src/sage/games/sudoku_backtrack.pyx index ddf020d498d..b9630566cf5 100644 --- a/src/sage/games/sudoku_backtrack.pyx +++ b/src/sage/games/sudoku_backtrack.pyx @@ -13,7 +13,7 @@ def backtrack_all(n, puzzle): - ``n`` -- the size of the puzzle, where the array is an `n^2\times n^2` grid - - ``puzzle`` -- a list of the entries of the puzzle (1-based), in row-major order + - ``puzzle`` -- list of the entries of the puzzle (1-based), in row-major order OUTPUT: @@ -103,7 +103,7 @@ def backtrack_all(n, puzzle): for j in range(nsquare): available[level][j] = 0 - # For non-zero entries of input puzzle + # For nonzero entries of input puzzle # (1) Convert to zero-based indexing # (2) Make a set of size 1 available initially for level in range(nboxes): diff --git a/src/sage/geometry/cone.py b/src/sage/geometry/cone.py index 1b25726832c..17f58378373 100644 --- a/src/sage/geometry/cone.py +++ b/src/sage/geometry/cone.py @@ -236,9 +236,9 @@ from sage.features import PythonModule lazy_import('ppl', ['C_Polyhedron', 'Generator_System', 'Constraint_System', 'Linear_Expression', 'Poly_Con_Relation'], - feature=PythonModule("ppl", spkg="pplpy", type="standard")) + feature=PythonModule("ppl", spkg='pplpy', type='standard')) lazy_import('ppl', ['ray', 'point'], as_=['PPL_ray', 'PPL_point'], - feature=PythonModule("ppl", spkg="pplpy", type="standard")) + feature=PythonModule("ppl", spkg='pplpy', type='standard')) def is_Cone(x): @@ -247,11 +247,9 @@ def is_Cone(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - - ``True`` if ``x`` is a cone and ``False`` otherwise. + OUTPUT: ``True`` if ``x`` is a cone and ``False`` otherwise EXAMPLES:: @@ -278,7 +276,7 @@ def Cone(rays, lattice=None, check=True, normalize=True): INPUT: - - ``rays`` -- a list of rays. Each ray should be given as a list + - ``rays`` -- list of rays; each ray should be given as a list or a vector convertible to the rational extension of the given ``lattice``. May also be specified by a :class:`~sage.geometry.polyhedron.base.Polyhedron_base` object; @@ -301,9 +299,7 @@ def Cone(rays, lattice=None, check=True, normalize=True): this option, it is designed for code optimization and does not give as drastic improvement in speed as the previous one. - OUTPUT: - - - convex rational polyhedral cone determined by ``rays``. + OUTPUT: convex rational polyhedral cone determined by ``rays`` EXAMPLES: @@ -496,7 +492,7 @@ def _Cone_from_PPL(cone, lattice, original_rays=None): INPUT: - ``cone`` -- a :class:`~ppl.polyhedron.Polyhedron` having the - origin as its single point. + origin as its single point - ``lattice`` -- :class:`ToricLattice `, `\ZZ^n`, or any @@ -507,9 +503,7 @@ def _Cone_from_PPL(cone, lattice, original_rays=None): and ``original_rays`` were given, they will be used as internal rays of the constructed cone, in the given order. - OUTPUT: - - A :class:`ConvexRationalPolyhedralCone`. + OUTPUT: a :class:`ConvexRationalPolyhedralCone` TESTS:: @@ -556,7 +550,7 @@ def _ambient_space_point(body, data): An integral, rational, real algebraic, or numeric point of the ambient space of ``body`` is returned if ``data`` were - successfully interpreted in such a way. A :class:`TypeError` is raised + successfully interpreted in such a way. A :exc:`TypeError` is raised otherwise. TESTS:: @@ -600,7 +594,6 @@ def _ambient_space_point(body, data): (1.00000000000000, 3.14159265358979) sage: _ambient_space_point(c, vector(SR,[1, pi])) # needs sage.rings.number_field sage.symbolic (1.00000000000000, 3.14159265358979) - """ L = body.lattice() @@ -660,7 +653,7 @@ def integral_length(v): OUTPUT: - Rational number `r`` such that ``v = r * u``, where ``u`` is the + Rational number ``r`` such that ``v = r * u``, where ``u`` is the primitive integral vector in the direction of ``v``. EXAMPLES:: @@ -835,11 +828,9 @@ def __richcmp__(self, right, op): INPUT: - - ``right`` -- anything. + - ``right`` -- anything - OUTPUT: - - boolean + OUTPUT: boolean There is equality if ``right`` is of the same type as ``self``, they have the same ambient lattices, and their @@ -872,9 +863,7 @@ def __hash__(self): r""" Return the hash of ``self`` computed from rays. - OUTPUT: - - - integer. + OUTPUT: integer TESTS:: @@ -890,9 +879,7 @@ def __iter__(self): r""" Return an iterator over rays of ``self``. - OUTPUT: - - - iterator. + OUTPUT: iterator TESTS:: @@ -915,9 +902,7 @@ def cartesian_product(self, other, lattice=None): default, the direct sum of the ambient lattices of ``self`` and ``other`` is constructed. - OUTPUT: - - - an :class:`IntegralRayCollection`. + OUTPUT: an :class:`IntegralRayCollection` By the Cartesian product of ray collections `(r_0, \dots, r_{n-1})` and `(s_0, \dots, s_{m-1})` we understand the ray collection of the form @@ -970,9 +955,7 @@ def dim(self): r""" Return the dimension of the subspace spanned by rays of ``self``. - OUTPUT: - - - integer. + OUTPUT: integer EXAMPLES:: @@ -990,9 +973,7 @@ def lattice(self): r""" Return the ambient lattice of ``self``. - OUTPUT: - - - lattice. + OUTPUT: lattice EXAMPLES:: @@ -1013,7 +994,7 @@ def ambient_vector_space(self, base_field=None): INPUT: - - ``base_field`` -- (default: the rationals) a field. + - ``base_field`` -- (default: the rationals) a field EXAMPLES:: @@ -1065,9 +1046,7 @@ def lattice_dim(self): An alias is :meth:`ambient_dim`. - OUTPUT: - - - integer. + OUTPUT: integer EXAMPLES:: @@ -1085,9 +1064,7 @@ def nrays(self): r""" Return the number of rays of ``self``. - OUTPUT: - - - integer. + OUTPUT: integer EXAMPLES:: @@ -1106,9 +1083,7 @@ def plot(self, **options): - any options for toric plots (see :func:`toric_plotter.options `), none are mandatory. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -1125,12 +1100,10 @@ def ray(self, n): INPUT: - - ``n`` -- integer, an index of a ray of ``self``. Enumeration of rays - starts with zero. - - OUTPUT: + - ``n`` -- integer; an index of a ray of ``self``. Enumeration of rays + starts with zero - - ray, an element of the lattice of ``self``. + OUTPUT: ray; an element of the lattice of ``self`` EXAMPLES:: @@ -1146,13 +1119,11 @@ def rays(self, *args): INPUT: - - ``ray_list`` -- a list of integers, the indices of the requested - rays. If not specified, all rays of ``self`` will be returned. + - ``ray_list`` -- list of integers, the indices of the requested + rays. If not specified, all rays of ``self`` will be returned - OUTPUT: - - - a :class:`~sage.geometry.point_collection.PointCollection` - of primitive integral ray generators. + OUTPUT: a :class:`~sage.geometry.point_collection.PointCollection` + of primitive integral ray generators EXAMPLES:: @@ -1185,9 +1156,7 @@ def codim(self): difference between the dimension of the ambient space and the dimension of the subspace spanned by those rays (of the cone/fan). - OUTPUT: - - A nonnegative integer representing the codimension of ``self``. + OUTPUT: nonnegative integer representing the codimension of ``self`` .. SEEALSO:: @@ -1278,11 +1247,9 @@ def span(self, base_ring=None): INPUT: - ``base_ring`` -- (default: from lattice) the base ring to use - for the generated module. - - OUTPUT: + for the generated module - A module spanned by the generators of ``self``. + OUTPUT: a module spanned by the generators of ``self`` EXAMPLES: @@ -1338,11 +1305,11 @@ def classify_cone_2d(ray0, ray1, check=True): INPUT: - - ``ray0``, ``ray1`` -- two primitive integer vectors. The - generators of the two rays generating the two-dimensional cone. + - ``ray0``, ``ray1`` -- two primitive integer vectors; the + generators of the two rays generating the two-dimensional cone - - ``check`` -- boolean (default: ``True``). Whether to check the - input rays for consistency. + - ``check`` -- boolean (default: ``True``); whether to check the + input rays for consistency OUTPUT: @@ -1465,7 +1432,7 @@ class ConvexRationalPolyhedralCone(IntegralRayCollection, Container, ConvexSet_c of* ``ambient``; - ``ambient_ray_indices`` -- increasing list or tuple of integers, indices - of rays of ``ambient`` generating this cone. + of rays of ``ambient`` generating this cone In both cases, the following keyword parameter may be specified in addition: @@ -1475,9 +1442,7 @@ class ConvexRationalPolyhedralCone(IntegralRayCollection, Container, ConvexSet_c already. The constructor does not make a copy so the ``PPL`` object should not be modified afterwards. - OUTPUT: - - - convex rational polyhedral cone. + OUTPUT: convex rational polyhedral cone .. NOTE:: @@ -1550,11 +1515,9 @@ def _sage_input_(self, sib, coerced): def _PPL_cone(self): r""" - Returns the Parma Polyhedra Library (PPL) representation of the cone. - - OUTPUT: + Return the Parma Polyhedra Library (PPL) representation of the cone. - A :class:`~ppl.polyhedron.C_Polyhedron` representing the cone. + OUTPUT: a :class:`~ppl.polyhedron.C_Polyhedron` representing the cone EXAMPLES:: @@ -1609,9 +1572,7 @@ def __getstate__(self): r""" Return the dictionary that should be pickled. - OUTPUT: - - - :class:`dict`. + OUTPUT: :class:`dict` TESTS:: @@ -1665,10 +1626,10 @@ def _contains(self, point, region='whole cone'): INPUT: - ``point`` -- anything; an attempt will be made to convert it - into an element compatible with the ambient space of ``self``. + into an element compatible with the ambient space of ``self`` - - ``region`` -- a string (default: 'whole cone'); can be - either 'whole cone', 'interior', or 'relative interior'. + - ``region`` -- string (default: 'whole cone'); can be + either 'whole cone', 'interior', or 'relative interior' OUTPUT: @@ -1677,7 +1638,7 @@ def _contains(self, point, region='whole cone'): otherwise, in particular when ``point`` is incompatible with the ambient space. - A :class:`ValueError` is raised if ``region`` is not one of the + A :exc:`ValueError` is raised if ``region`` is not one of the three allowed values. TESTS:: @@ -1799,7 +1760,6 @@ def interior(self): 2-d cone in 2-d lattice N sage: K2.interior() is K2 True - """ if self.is_solid(): return self.relative_interior() @@ -1888,15 +1848,13 @@ def cartesian_product(self, other, lattice=None): INPUT: - - ``other`` -- a :class:`cone `; + - ``other`` -- a :class:`cone ` - ``lattice`` -- (optional) the ambient lattice for the - Cartesian product cone. By default, the direct sum of the - ambient lattices of ``self`` and ``other`` is constructed. + Cartesian product cone; by default, the direct sum of the + ambient lattices of ``self`` and ``other`` is constructed - OUTPUT: - - - a :class:`cone `. + OUTPUT: a :class:`cone ` EXAMPLES:: @@ -1916,9 +1874,7 @@ def __neg__(self): """ Return the cone with opposite rays. - OUTPUT: - - - a :class:`cone `. + OUTPUT: a :class:`cone ` EXAMPLES:: @@ -1942,11 +1898,9 @@ def __richcmp__(self, right, op): INPUT: - - ``right`` -- anything. + - ``right`` -- anything - OUTPUT: - - boolean + OUTPUT: boolean There is equality if ``self`` and ``right`` are cones of any kind in the same lattice with the same rays listed in the @@ -1977,9 +1931,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1999,9 +1951,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -2056,11 +2006,9 @@ def _sort_faces(self, faces): INPUT: - ``faces`` -- iterable of :class:`cones - `. + ` - OUTPUT: - - - :class:`tuple` of :class:`cones `. + OUTPUT: :class:`tuple` of :class:`cones ` TESTS:: @@ -2104,9 +2052,7 @@ def adjacent(self): * `F_1` and `F_2` are facets of some face of dimension `d+1`, unless `d` is the dimension of the ambient structure. - OUTPUT: - - - :class:`tuple` of :class:`cones `. + OUTPUT: :class:`tuple` of :class:`cones ` EXAMPLES:: @@ -2181,9 +2127,7 @@ def ambient(self): r""" Return the ambient structure of ``self``. - OUTPUT: - - - cone or fan containing ``self`` as a face. + OUTPUT: cone or fan containing ``self`` as a face EXAMPLES:: @@ -2208,9 +2152,7 @@ def ambient_ray_indices(self): r""" Return indices of rays of the ambient structure generating ``self``. - OUTPUT: - - - increasing :class:`tuple` of integers. + OUTPUT: increasing :class:`tuple` of integers EXAMPLES:: @@ -2270,9 +2212,7 @@ def dual(self): r""" Return the dual cone of ``self``. - OUTPUT: - - - :class:`cone `. + OUTPUT: :class:`cone ` EXAMPLES:: @@ -2353,7 +2293,7 @@ def embed(self, cone): or :meth:`~sage.geometry.cone.ConvexRationalPolyhedralCone.facet_of`. The cone returned by this method will have ``self`` as ambient. If ``cone`` - does not represent a valid cone of ``self``, :class:`ValueError` + does not represent a valid cone of ``self``, :exc:`ValueError` exception is raised. .. NOTE:: @@ -2366,7 +2306,7 @@ def embed(self, cone): INPUT: - ``cone`` -- a :class:`cone - `. + ` OUTPUT: @@ -2677,9 +2617,9 @@ def faces(self, dim=None, codim=None): INPUT: - - ``dim`` -- integer, dimension of the requested faces; + - ``dim`` -- integer; dimension of the requested faces - - ``codim`` -- integer, codimension of the requested faces. + - ``codim`` -- integer; codimension of the requested faces .. NOTE:: @@ -2734,7 +2674,7 @@ def faces(self, dim=None, codim=None): () In the case of non-strictly convex cones even faces of small - non-negative dimension may be missing:: + nonnegative dimension may be missing:: sage: # needs sage.graphs sage: halfplane = Cone([(1,0), (0,1), (-1,0)]) @@ -2815,9 +2755,7 @@ def facet_normals(self): #. The order of normals is random, but consistent with :meth:`facets`. - OUTPUT: - - - a :class:`~sage.geometry.point_collection.PointCollection`. + OUTPUT: a :class:`~sage.geometry.point_collection.PointCollection` If the ambient :meth:`~IntegralRayCollection.lattice` of ``self`` is a :class:`toric lattice @@ -2918,9 +2856,7 @@ def facet_of(self): r""" Return *cones* of the ambient face lattice having ``self`` as a facet. - OUTPUT: - - - :class:`tuple` of :class:`cones `. + OUTPUT: :class:`tuple` of :class:`cones ` EXAMPLES:: @@ -2956,9 +2892,7 @@ def facets(self): r""" Return facets (faces of codimension 1) of ``self``. - OUTPUT: - - - :class:`tuple` of :class:`cones `. + OUTPUT: :class:`tuple` of :class:`cones ` EXAMPLES:: @@ -3025,13 +2959,11 @@ def intersection(self, other): INPUT: - - ``other`` -- :class:`cone `. + - ``other`` -- :class:`cone ` - OUTPUT: + OUTPUT: :class:`cone ` - - :class:`cone `. - - This raises :class:`ValueError` if the ambient space dimensions + This raises :exc:`ValueError` if the ambient space dimensions are not compatible. EXAMPLES:: @@ -3110,7 +3042,7 @@ def is_equivalent(self, other): INPUT: - - ``other`` -- cone. + - ``other`` -- cone OUTPUT: @@ -3152,7 +3084,6 @@ def is_equivalent(self, other): sage: K = random_cone(max_ambient_dim=8, max_rays=10) sage: K.is_equivalent(K) True - """ if self is other: return True @@ -3169,11 +3100,9 @@ def is_face_of(self, cone): INPUT: - - ``cone`` -- cone. - - OUTPUT: + - ``cone`` -- cone - - ``True`` if ``self`` is a face of ``cone``, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is a face of ``cone``, ``False`` otherwise EXAMPLES:: @@ -3202,7 +3131,6 @@ def is_face_of(self, cone): sage: K = random_cone(max_ambient_dim=8, max_rays=10) sage: K.is_face_of(K) True - """ if self.lattice() != cone.lattice(): return False @@ -3240,12 +3168,10 @@ def is_isomorphic(self, other): INPUT: - - ``other`` -- cone. - - OUTPUT: + - ``other`` -- cone - - ``True`` if ``self`` and ``other`` are in the same - `GL(n, \ZZ)`-orbit, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` and ``other`` are in the same + `GL(n, \ZZ)`-orbit, ``False`` otherwise There are three different equivalences between cones `C_1` and `C_2` in the same lattice: @@ -3314,9 +3240,7 @@ def is_simplicial(self): generating rays form a part of a *rational* basis of the ambient space. - OUTPUT: - - - ``True`` if ``self`` is simplicial, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is simplicial, ``False`` otherwise EXAMPLES:: @@ -3339,9 +3263,7 @@ def is_smooth(self): ambient space. Equivalently, they generate the whole lattice on the linear subspace spanned by the rays. - OUTPUT: - - - ``True`` if ``self`` is smooth, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is smooth, ``False`` otherwise EXAMPLES:: @@ -3377,17 +3299,14 @@ def is_empty(self): sage: trivial_cone = cones.trivial(3) sage: trivial_cone.is_empty() False - """ return False def is_trivial(self): """ - Checks if the cone has no rays. - - OUTPUT: + Check if the cone has no rays. - - ``True`` if the cone has no rays, ``False`` otherwise. + OUTPUT: ``True`` if the cone has no rays, ``False`` otherwise EXAMPLES:: @@ -3407,9 +3326,7 @@ def is_strictly_convex(self): A cone is called **strictly convex** if it does not contain any lines. - OUTPUT: - - - ``True`` if ``self`` is strictly convex, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is strictly convex, ``False`` otherwise EXAMPLES:: @@ -3434,9 +3351,7 @@ def linear_subspace(self): r""" Return the largest linear subspace contained inside of ``self``. - OUTPUT: - - - subspace of the ambient space of ``self``. + OUTPUT: subspace of the ambient space of ``self`` EXAMPLES:: @@ -3501,11 +3416,9 @@ def plot(self, **options): INPUT: - any options for toric plots (see :func:`toric_plotter.options - `), none are mandatory. - - OUTPUT: + `), none are mandatory - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -3548,9 +3461,7 @@ def polyhedron(self, **kwds): Mathematically this polyhedron is the same as ``self``. - OUTPUT: - - - :class:`~sage.geometry.polyhedron.base.Polyhedron_base`. + OUTPUT: :class:`~sage.geometry.polyhedron.base.Polyhedron_base` EXAMPLES:: @@ -3599,9 +3510,7 @@ def strict_quotient(self): cone in the quotient of the ambient space by the linear subspace of the cone, i.e. it is the "complementary part" to the linear subspace. - OUTPUT: - - - cone. + OUTPUT: cone EXAMPLES:: @@ -3795,7 +3704,7 @@ def solid_restriction(self): L._dual_name, L._latex_name, L._latex_dual_name) # We don't need to check if these rays are zero: they will all - # have at least one non-zero coordinate; otherwise they would + # have at least one nonzero coordinate; otherwise they would # lie outside of the span of our cone. And they don't, because # they generate the cone. rays = ( S(subL.coordinates(ray)) for ray in self ) @@ -4295,7 +4204,7 @@ def semigroup_generators(self): of lattice points generating the semigroup of lattice points contained in ``self``. - .. note:: + .. NOTE:: No attempt is made to return a minimal set of generators, see :meth:`Hilbert_basis` for that. @@ -4574,7 +4483,7 @@ def Hilbert_coefficients(self, point, solver=None, verbose=0, in the cone, or something that can be converted to a point. For example, a list or tuple of integers. - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -4582,18 +4491,18 @@ def Hilbert_coefficients(self, point, solver=None, verbose=0, of the class :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``). Sets the level of verbosity + - ``verbose`` -- integer (default: 0); sets the level of verbosity of the LP solver. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` OUTPUT: A `\ZZ`-vector of length ``len(self.Hilbert_basis())`` with nonnegative components. - .. note:: + .. NOTE:: Since the Hilbert basis elements are not necessarily linearly independent, the expansion coefficients are not unique. However, @@ -4660,9 +4569,7 @@ def is_solid(self): An alias is :meth:`is_full_dimensional`. - OUTPUT: - - ``True`` if this cone is solid, and ``False`` otherwise. + OUTPUT: ``True`` if this cone is solid, and ``False`` otherwise .. SEEALSO:: @@ -4709,9 +4616,7 @@ def is_proper(self): convex; therefore it is proper if it is solid and contains no lines. - OUTPUT: - - ``True`` if this cone is proper, and ``False`` otherwise. + OUTPUT: ``True`` if this cone is proper, and ``False`` otherwise .. SEEALSO:: @@ -4742,7 +4647,6 @@ def is_proper(self): sage: halfspace = Cone([(1,0), (0,1), (-1,0)]) sage: halfspace.is_proper() False - """ return (self.is_strictly_convex() and self.is_solid()) @@ -4785,7 +4689,6 @@ def is_full_space(self): sage: K = Cone([(1,0), (-1,0), (0,1), (0,-1)]) sage: K.is_full_space() True - """ return self.linear_subspace() == self.lattice().vector_space() @@ -4865,9 +4768,7 @@ def is_relatively_open(self): r""" Return whether ``self`` is relatively open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -5131,9 +5032,7 @@ def lyapunov_rank(self): the dimension of the Lie algebra of the automorphism group of the cone. - OUTPUT: - - A nonnegative integer representing the Lyapunov rank of this cone. + OUTPUT: nonnegative integer representing the Lyapunov rank of this cone If the ambient space is trivial, then the Lyapunov rank will be zero. On the other hand, if the dimension of the ambient vector @@ -5357,14 +5256,14 @@ def random_element(self, ring=ZZ): INPUT: - ``ring`` -- (default: ``ZZ``) the ring from which the random - generator weights are chosen; either ``ZZ`` or ``QQ``. + generator weights are chosen; either ``ZZ`` or ``QQ`` OUTPUT: Either a lattice element or vector contained in both this cone and its ambient vector space. If ``ring`` is ``ZZ``, a lattice element is returned; otherwise a vector is returned. If ``ring`` - is neither ``ZZ`` nor ``QQ``, then a :class:`NotImplementedError` is + is neither ``ZZ`` nor ``QQ``, then a :exc:`NotImplementedError` is raised. EXAMPLES: @@ -5497,7 +5396,7 @@ def positive_operators_gens(self, K2=None): INPUT: - ``K2`` -- (default: ``self``) the codomain cone; the image of - this cone under the returned generators is a subset of ``K2``. + this cone under the returned generators is a subset of ``K2`` OUTPUT: @@ -6222,14 +6121,14 @@ def max_angle(self, other=None, exact=True, epsilon=0): be made using inexact arithmetic. (This sometimes avoids the problem noted in [Or2024]_). If the computation fails when the cones are not strictly convex or when ``exact`` is ``False``, - a :class:`ValueError` is raised. + a :exc:`ValueError` is raised. INPUT: - ``other`` -- (default: ``None``) a rational, polyhedral convex cone - - ``exact`` -- (default: ``True``) whether or not to use exact + - ``exact`` -- boolean (default: ``True``); whether or not to use exact rational arithmetic instead of floating point computations; beware that ``True`` is not guaranteed to avoid floating point computations if the algorithm runs into trouble in @@ -6272,7 +6171,7 @@ def max_angle(self, other=None, exact=True, epsilon=0): vectors will be over :class:`sage.rings.real_double.RDF`. - If ``exact`` is ``False`` or if either cone is not strictly - convex, then a :class:`ValueError` is raised to indicate + convex, then a :exc:`ValueError` is raised to indicate that we have failed; i.e. we cannot say with certainty what the maximal angle is. @@ -6447,37 +6346,35 @@ def random_cone(lattice=None, min_ambient_dim=0, max_ambient_dim=None, INPUT: - * ``lattice`` (default: random) -- A ``ToricLattice`` object in + - ``lattice`` -- (default: random) a ``ToricLattice`` object in which the returned cone will live. By default a new lattice will be constructed with a randomly-chosen rank (subject to ``min_ambient_dim`` and ``max_ambient_dim``). - * ``min_ambient_dim`` (default: zero) -- A nonnegative integer - representing the minimum dimension of the ambient lattice. + - ``min_ambient_dim`` -- (default: zero) a nonnegative integer + representing the minimum dimension of the ambient lattice - * ``max_ambient_dim`` (default: random) -- A nonnegative integer - representing the maximum dimension of the ambient lattice. + - ``max_ambient_dim`` -- (default: random) a nonnegative integer + representing the maximum dimension of the ambient lattice - * ``min_rays`` (default: zero) -- A nonnegative integer representing - the minimum number of generating rays of the cone. + - ``min_rays`` -- (default: zero) a nonnegative integer representing + the minimum number of generating rays of the cone - * ``max_rays`` (default: random) -- A nonnegative integer representing - the maximum number of generating rays of the cone. + - ``max_rays`` -- (default: random) a nonnegative integer representing + the maximum number of generating rays of the cone - * ``strictly_convex`` (default: random) -- Whether or not to make the + - ``strictly_convex`` -- (default: random) whether or not to make the returned cone strictly convex. Specify ``True`` for a strictly convex cone, ``False`` for a non-strictly-convex cone, or ``None`` if you don't care. - * ``solid`` (default: random) -- Whether or not to make the returned + - ``solid`` -- (default: random) whether or not to make the returned cone solid. Specify ``True`` for a solid cone, ``False`` for a non-solid cone, or ``None`` if you don't care. - OUTPUT: - - A new, randomly generated cone. + OUTPUT: a new, randomly generated cone - A :class:`ValueError` will be thrown under the following conditions: + A :exc:`ValueError` will be thrown under the following conditions: * Any of ``min_ambient_dim``, ``max_ambient_dim``, ``min_rays``, or ``max_rays`` are negative. @@ -6634,7 +6531,7 @@ def random_cone(lattice=None, min_ambient_dim=0, max_ambient_dim=None, provided. If the user requests too many rays in zero, one, or two dimensions, - a :class:`ValueError` is thrown:: + a :exc:`ValueError` is thrown:: sage: random_cone(max_ambient_dim=0, min_rays=1) Traceback (most recent call last): @@ -6722,7 +6619,7 @@ def random_cone(lattice=None, min_ambient_dim=0, max_ambient_dim=None, sage: random_cone(lattice=L, strictly_convex=True) 0-d cone in 0-d lattice L - A :class:`ValueError` is thrown if a non-solid cone is requested in a + A :exc:`ValueError` is thrown if a non-solid cone is requested in a zero-dimensional lattice:: sage: L = ToricLattice(0) @@ -6736,7 +6633,7 @@ def random_cone(lattice=None, min_ambient_dim=0, max_ambient_dim=None, ... ValueError: all cones are solid when max_ambient_dim is zero. - A :class:`ValueError` is thrown if a solid cone is requested but the + A :exc:`ValueError` is thrown if a solid cone is requested but the maximum number of rays is too few:: sage: random_cone(min_ambient_dim=4, max_rays=3, solid=True) @@ -6751,7 +6648,7 @@ def random_cone(lattice=None, min_ambient_dim=0, max_ambient_dim=None, ValueError: max_rays must be at least 5 for a solid cone in this lattice. - A :class:`ValueError` is thrown if a non-solid cone is requested but + A :exc:`ValueError` is thrown if a non-solid cone is requested but ``min_rays`` guarantees a solid cone:: sage: random_cone(max_ambient_dim=4, min_rays=10, solid=False) @@ -6765,7 +6662,6 @@ def random_cone(lattice=None, min_ambient_dim=0, max_ambient_dim=None, ... ValueError: every cone is solid when min_rays > 2*(d - 1) where d is the dimension of the given lattice. - """ # Catch obvious mistakes so that we can generate clear error diff --git a/src/sage/geometry/cone_catalog.py b/src/sage/geometry/cone_catalog.py index a56de80b412..da2ab39a0e6 100644 --- a/src/sage/geometry/cone_catalog.py +++ b/src/sage/geometry/cone_catalog.py @@ -98,7 +98,7 @@ def _preprocess_args(ambient_dim, lattice): INPUT: - - ``ambient_dim`` -- a nonnegative integer; the dimension of the + - ``ambient_dim`` -- nonnegative integer; the dimension of the ambient space in which the cone will live - ``lattice`` -- a toric lattice; the lattice in which the cone @@ -176,7 +176,7 @@ def downward_monotone(ambient_dim=None, lattice=None): INPUT: - - ``ambient_dim`` -- a nonnegative integer (default: ``None``); the + - ``ambient_dim`` -- nonnegative integer (default: ``None``); the dimension of the ambient space - ``lattice`` -- a toric lattice (default: ``None``); the lattice in @@ -186,8 +186,8 @@ def downward_monotone(ambient_dim=None, lattice=None): rank of ``lattice``. If the ``lattice`` is omitted, then the default lattice of rank ``ambient_dim`` will be used. - A :class:`ValueError` is raised if neither ``ambient_dim`` nor - ``lattice`` are specified. It is also a :class:`ValueError` to + A :exc:`ValueError` is raised if neither ``ambient_dim`` nor + ``lattice`` are specified. It is also a :exc:`ValueError` to specify both ``ambient_dim`` and ``lattice`` unless the rank of ``lattice`` is equal to ``ambient_dim``. @@ -198,7 +198,7 @@ def downward_monotone(ambient_dim=None, lattice=None): nonincreasing order. Each generating ray has the integer ring as its base ring. - A :class:`ValueError` can be raised if the inputs are incompatible + A :exc:`ValueError` can be raised if the inputs are incompatible or insufficient. See the INPUT documentation for details. .. SEEALSO:: @@ -307,7 +307,7 @@ def nonnegative_orthant(ambient_dim=None, lattice=None): INPUT: - - ``ambient_dim`` -- a nonnegative integer (default: ``None``); the + - ``ambient_dim`` -- nonnegative integer (default: ``None``); the dimension of the ambient space - ``lattice`` -- a toric lattice (default: ``None``); the lattice in @@ -317,8 +317,8 @@ def nonnegative_orthant(ambient_dim=None, lattice=None): rank of ``lattice``. If the ``lattice`` is omitted, then the default lattice of rank ``ambient_dim`` will be used. - A :class:`ValueError` is raised if neither ``ambient_dim`` nor - ``lattice`` are specified. It is also a :class:`ValueError` to + A :exc:`ValueError` is raised if neither ``ambient_dim`` nor + ``lattice`` are specified. It is also a :exc:`ValueError` to specify both ``ambient_dim`` and ``lattice`` unless the rank of ``lattice`` is equal to ``ambient_dim``. @@ -329,7 +329,7 @@ def nonnegative_orthant(ambient_dim=None, lattice=None): as its generators. Each generating ray has the integer ring as its base ring. - A :class:`ValueError` can be raised if the inputs are incompatible + A :exc:`ValueError` can be raised if the inputs are incompatible or insufficient. See the INPUT documentation for details. REFERENCES: @@ -412,10 +412,10 @@ def rearrangement(p, ambient_dim=None, lattice=None): INPUT: - - ``p`` -- a nonnegative integer; the number of components to + - ``p`` -- nonnegative integer; the number of components to "rearrange", between ``1`` and ``ambient_dim`` inclusive - - ``ambient_dim`` -- a nonnegative integer (default: ``None``); the + - ``ambient_dim`` -- nonnegative integer (default: ``None``); the dimension of the ambient space - ``lattice`` -- a toric lattice (default: ``None``); the lattice in @@ -425,12 +425,12 @@ def rearrangement(p, ambient_dim=None, lattice=None): rank of ``lattice``. If the ``lattice`` is omitted, then the default lattice of rank ``ambient_dim`` will be used. - A :class:`ValueError` is raised if neither ``ambient_dim`` nor - ``lattice`` are specified. It is also a :class:`ValueError` to + A :exc:`ValueError` is raised if neither ``ambient_dim`` nor + ``lattice`` are specified. It is also a :exc:`ValueError` to specify both ``ambient_dim`` and ``lattice`` unless the rank of ``lattice`` is equal to ``ambient_dim``. - It is also a :class:`ValueError` to specify a non-integer ``p``. + It is also a :exc:`ValueError` to specify a non-integer ``p``. OUTPUT: @@ -439,7 +439,7 @@ def rearrangement(p, ambient_dim=None, lattice=None): ``lattice``, with ambient dimension ``ambient_dim``. Each generating ray has the integer ring as its base ring. - A :class:`ValueError` can be raised if the inputs are incompatible + A :exc:`ValueError` can be raised if the inputs are incompatible or insufficient. See the INPUT documentation for details. ALGORITHM: @@ -636,7 +636,7 @@ def schur(ambient_dim=None, lattice=None): INPUT: - - ``ambient_dim`` -- a nonnegative integer (default: ``None``); the + - ``ambient_dim`` -- nonnegative integer (default: ``None``); the dimension of the ambient space - ``lattice`` -- a toric lattice (default: ``None``); the lattice in @@ -646,8 +646,8 @@ def schur(ambient_dim=None, lattice=None): rank of ``lattice``. If the ``lattice`` is omitted, then the default lattice of rank ``ambient_dim`` will be used. - A :class:`ValueError` is raised if neither ``ambient_dim`` nor - ``lattice`` are specified. It is also a :class:`ValueError` to + A :exc:`ValueError` is raised if neither ``ambient_dim`` nor + ``lattice`` are specified. It is also a :exc:`ValueError` to specify both ``ambient_dim`` and ``lattice`` unless the rank of ``lattice`` is equal to ``ambient_dim``. @@ -658,7 +658,7 @@ def schur(ambient_dim=None, lattice=None): dimension ``ambient_dim``. Each generating ray has the integer ring as its base ring. - A :class:`ValueError` can be raised if the inputs are incompatible + A :exc:`ValueError` can be raised if the inputs are incompatible or insufficient. See the INPUT documentation for details. .. SEEALSO:: @@ -775,7 +775,7 @@ def trivial(ambient_dim=None, lattice=None): INPUT: - - ``ambient_dim`` -- a nonnegative integer (default: ``None``); the + - ``ambient_dim`` -- nonnegative integer (default: ``None``); the dimension of the ambient space - ``lattice`` -- a toric lattice (default: ``None``); the lattice in @@ -785,8 +785,8 @@ def trivial(ambient_dim=None, lattice=None): rank of ``lattice``. If the ``lattice`` is omitted, then the default lattice of rank ``ambient_dim`` will be used. - A :class:`ValueError` is raised if neither ``ambient_dim`` nor - ``lattice`` are specified. It is also a :class:`ValueError` to + A :exc:`ValueError` is raised if neither ``ambient_dim`` nor + ``lattice`` are specified. It is also a :exc:`ValueError` to specify both ``ambient_dim`` and ``lattice`` unless the rank of ``lattice`` is equal to ``ambient_dim``. @@ -796,7 +796,7 @@ def trivial(ambient_dim=None, lattice=None): representing the trivial cone with no nonzero generators living in ``lattice``, with ambient dimension ``ambient_dim``. - A :class:`ValueError` can be raised if the inputs are incompatible + A :exc:`ValueError` can be raised if the inputs are incompatible or insufficient. See the INPUT documentation for details. EXAMPLES: diff --git a/src/sage/geometry/cone_critical_angles.py b/src/sage/geometry/cone_critical_angles.py index 3e39102426a..55636a15da8 100644 --- a/src/sage/geometry/cone_critical_angles.py +++ b/src/sage/geometry/cone_critical_angles.py @@ -128,7 +128,7 @@ def _random_admissible_cone(ambient_dim): INPUT: - - ``ambient_dim`` -- a positive integer representing the dimension + - ``ambient_dim`` -- positive integer representing the dimension of the ambient lattice in which the returned cone lives OUTPUT: @@ -136,7 +136,7 @@ def _random_admissible_cone(ambient_dim): A "random" nontrivial closed convex cone in a lattice of dimension ``ambient_dim``. - A :class:`ValueError` is raised if ``ambient_dim`` is not + A :exc:`ValueError` is raised if ``ambient_dim`` is not positive. EXAMPLES: @@ -458,7 +458,7 @@ def solve_gevp_nonzero(GG, HH, M, I, J): ALGORITHM: According to Proposition 5 [Or2020]_, the solutions corresponding - to non-zero eigenvalues can be found by solving a smaller + to nonzero eigenvalues can be found by solving a smaller eigenvalue problem in only the variable `\xi`. So, we do that, and then solve for `\eta` in terms of `\xi` as described in the proposition. @@ -626,9 +626,7 @@ def compute_gevp_M(gs, hs): - ``hs`` -- a linearly independent list of unit-norm generators for the cone `Q` - OUTPUT: - - A tuple containing four elements, in order: + OUTPUT: a tuple containing four elements, in order: - The matrix `M` described in Proposition 6 diff --git a/src/sage/geometry/convex_set.py b/src/sage/geometry/convex_set.py index dd7237f0e30..2117eccfcc6 100644 --- a/src/sage/geometry/convex_set.py +++ b/src/sage/geometry/convex_set.py @@ -45,9 +45,7 @@ def is_empty(self): r""" Test whether ``self`` is the empty set. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -62,9 +60,7 @@ def is_finite(self): r""" Test whether ``self`` is a finite set. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -87,9 +83,7 @@ def cardinality(self): """ Return the cardinality of this set. - OUTPUT: - - Either an integer or ``Infinity``. + OUTPUT: either an integer or ``Infinity`` EXAMPLES:: @@ -116,9 +110,7 @@ def is_universe(self): r""" Test whether ``self`` is the whole ambient space. - OUTPUT: - - Boolean. + OUTPUT: boolean TESTS:: @@ -260,7 +252,7 @@ def an_affine_basis(self): def _test_an_affine_basis(self, tester=None, **options): r""" - Run tests on the method :meth:`.an_affine_basis` + Run tests on the method :meth:`.an_affine_basis`. TESTS:: @@ -457,10 +449,8 @@ def is_full_dimensional(self): r""" Return whether ``self`` is full dimensional. - OUTPUT: - - Boolean. Whether the polyhedron is not contained in any strict - affine subspace. + OUTPUT: boolean; whether the polyhedron is not contained in any strict + affine subspace EXAMPLES:: @@ -482,9 +472,7 @@ def is_open(self): The default implementation of this method only knows that the empty set and the ambient space are open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -509,9 +497,7 @@ def is_relatively_open(self): sets are also relatively open, and in addition singletons are relatively open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -535,9 +521,7 @@ def is_closed(self): The default implementation of this method only knows that the empty set, a singleton set, and the ambient space are closed. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -560,9 +544,7 @@ def is_compact(self): non-closed set cannot be compact, and that the empty set and a singleton set are compact. - OUTPUT: - - Boolean. + OUTPUT: boolean sage: from sage.geometry.convex_set import ConvexSet_base sage: class ExampleSet(ConvexSet_base): @@ -627,9 +609,7 @@ def representative_point(self): """ Return a "generic" point of ``self``. - OUTPUT: - - A point in the relative interior of ``self`` as a coordinate vector. + OUTPUT: a point in the relative interior of ``self`` as a coordinate vector EXAMPLES:: @@ -676,7 +656,6 @@ def _test_convex_set(self, tester=None, **options): Failure in _test_convex_set: ... The following tests failed: _test_convex_set - """ if tester is None: tester = self._tester(**options) @@ -721,7 +700,7 @@ def an_element(self): r""" Return a point of ``self``. - If ``self`` is empty, an :class:`EmptySetError` will be raised. + If ``self`` is empty, an :exc:`EmptySetError` will be raised. The default implementation delegates to :meth:`_some_elements_`. @@ -790,9 +769,7 @@ def cartesian_product(self, other): - ``other`` -- another convex set - OUTPUT: - - The Cartesian product of ``self`` and ``other``. + OUTPUT: the Cartesian product of ``self`` and ``other`` TESTS:: @@ -908,9 +885,7 @@ def intersection(self, other): - ``other`` -- another convex set - OUTPUT: - - The intersection. + OUTPUT: the intersection TESTS:: @@ -928,7 +903,7 @@ def dilation(self, scalar): INPUT: - - ``scalar`` -- A scalar, not necessarily in :meth:`base_ring` + - ``scalar`` -- a scalar, not necessarily in :meth:`base_ring` EXAMPLES:: @@ -998,9 +973,7 @@ def is_closed(self): r""" Return whether ``self`` is closed. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1014,9 +987,7 @@ def is_open(self): r""" Return whether ``self`` is open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1038,11 +1009,9 @@ class ConvexSet_compact(ConvexSet_closed): def is_universe(self): r""" - Return whether ``self`` is the whole ambient space - - OUTPUT: + Return whether ``self`` is the whole ambient space. - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1060,9 +1029,7 @@ def is_compact(self): r""" Return whether ``self`` is compact. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1084,9 +1051,7 @@ def is_relatively_open(self): r""" Return whether ``self`` is relatively open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1101,9 +1066,7 @@ def is_open(self): r""" Return whether ``self`` is open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1124,9 +1087,7 @@ def is_open(self): r""" Return whether ``self`` is open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1141,9 +1102,7 @@ def is_closed(self): r""" Return whether ``self`` is closed. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/geometry/fan.py b/src/sage/geometry/fan.py index 864a9237ee7..a020df85b83 100644 --- a/src/sage/geometry/fan.py +++ b/src/sage/geometry/fan.py @@ -269,11 +269,9 @@ def is_Fan(x) -> bool: INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - ``True`` if ``x`` is a fan and ``False`` otherwise + OUTPUT: ``True`` if ``x`` is a fan and ``False`` otherwise EXAMPLES:: @@ -376,9 +374,7 @@ def Fan(cones, rays=None, lattice=None, check=True, normalize=True, union of the cones in the polyhedral fan equals to the union of the given cones, and each given cone is the union of some cones in the polyhedral fan. - OUTPUT: - - a :class:`fan ` + OUTPUT: a :class:`fan ` .. SEEALSO:: @@ -694,9 +690,7 @@ def FaceFan(polytope, lattice=None): other object that behaves like these. If not specified, an attempt will be made to determine an appropriate toric lattice automatically. - OUTPUT: - - :class:`rational polyhedral fan ` + OUTPUT: :class:`rational polyhedral fan ` See also :func:`NormalFan`. @@ -802,9 +796,7 @@ def NormalFan(polytope, lattice=None): other object that behaves like these. If not specified, an attempt will be made to determine an appropriate toric lattice automatically. - OUTPUT: - - :class:`rational polyhedral fan ` + OUTPUT: :class:`rational polyhedral fan ` See also :func:`FaceFan`. @@ -943,7 +935,7 @@ def Fan2d(rays, lattice=None): sage: Fan2d([(0,1), (1,0), (0,0)]) Traceback (most recent call last): ... - ValueError: only non-zero vectors define rays + ValueError: only nonzero vectors define rays sage: Fan2d([(0, -2), (2, -10), (1, -3), (2, -9), (2, -12), (1, 1), ....: (2, 1), (1, -5), (0, -6), (1, -7), (0, 1), (2, -4), @@ -994,7 +986,7 @@ def Fan2d(rays, lattice=None): r0 = sorted_rays[i-1][1] r1 = sorted_rays[i][1] if r1.is_zero(): - raise ValueError('only non-zero vectors define rays') + raise ValueError('only nonzero vectors define rays') assert r0 != r1 cross_prod = r0[0] * r1[1] - r0[1] * r1[0] if cross_prod < 0: @@ -1021,14 +1013,12 @@ class Cone_of_fan(ConvexRationalPolyhedralCone): INPUT: - - ``ambient`` -- fan whose cone is constructed; + - ``ambient`` -- fan whose cone is constructed - ``ambient_ray_indices`` -- increasing list or tuple of integers, indices - of rays of ``ambient`` generating this cone. - - OUTPUT: + of rays of ``ambient`` generating this cone - cone of ``ambient`` + OUTPUT: cone of ``ambient`` EXAMPLES: @@ -1067,9 +1057,7 @@ def _repr_(self) -> str: r""" Return a string representation of ``self``. - OUTPUT: - - string + OUTPUT: string TESTS:: @@ -1089,9 +1077,7 @@ def star_generator_indices(self): Return indices of generating cones of the "ambient fan" containing ``self``. - OUTPUT: - - increasing :class:`tuple` of integers + OUTPUT: increasing :class:`tuple` of integers EXAMPLES:: @@ -1141,9 +1127,7 @@ def star_generators(self): Return indices of generating cones of the "ambient fan" containing ``self``. - OUTPUT: - - increasing :class:`tuple` of integers + OUTPUT: increasing :class:`tuple` of integers EXAMPLES:: @@ -1261,9 +1245,9 @@ def __call__(self, dim=None, codim=None): INPUT: - - ``dim`` -- dimension of the requested cones; + - ``dim`` -- dimension of the requested cones - - ``codim`` -- codimension of the requested cones. + - ``codim`` -- codimension of the requested cones OUTPUT: @@ -1307,11 +1291,9 @@ def __richcmp__(self, right, op): INPUT: - - ``right`` -- anything. - - OUTPUT: + - ``right`` -- anything - boolean + OUTPUT: boolean There is equality if ``right`` is also a fan, their rays are the same and stored in the same order, and their generating @@ -1372,9 +1354,7 @@ def __iter__(self): r""" Return an iterator over generating cones of ``self``. - OUTPUT: - - iterator + OUTPUT: iterator TESTS:: @@ -1549,7 +1529,7 @@ def _contains(self, cone) -> bool: INPUT: - - ``cone`` -- anything. + - ``cone`` -- anything OUTPUT: @@ -1735,9 +1715,7 @@ def common_refinement(self, other): - ``other`` -- a :class:`fan ` in the same :meth:`lattice` and with the same support as this fan - OUTPUT: - - a :class:`fan ` + OUTPUT: a :class:`fan ` EXAMPLES: @@ -1791,9 +1769,7 @@ def _latex_(self) -> str: r""" Return a LaTeX representation of ``self``. - OUTPUT: - - string + OUTPUT: string TESTS:: @@ -1811,7 +1787,7 @@ def _ray_to_cones(self, i=None): INPUT: - - ``i`` -- integer, index of a ray of ``self``. + - ``i`` -- integer; index of a ray of ``self`` OUTPUT: @@ -1848,9 +1824,7 @@ def _repr_(self) -> str: r""" Return a string representation of ``self``. - OUTPUT: - - string + OUTPUT: string TESTS:: @@ -1880,13 +1854,11 @@ def _subdivide_stellar(self, new_rays, verbose): INPUT: - ``new_rays`` -- immutable primitive vectors in the lattice of - ``self``; - - - ``verbose`` -- if ``True``, some timing information will be printed. + ``self`` - OUTPUT: + - ``verbose`` -- if ``True``, some timing information will be printed - rational polyhedral fan + OUTPUT: rational polyhedral fan TESTS:: @@ -1963,7 +1935,7 @@ def cone_containing(self, *points): We think of the origin as of the smallest cone containing no rays at all. If there is no ray in ``self`` that contains all ``rays``, - a :class:`ValueError` exception will be raised. + a :exc:`ValueError` exception will be raised. EXAMPLES:: @@ -2180,9 +2152,7 @@ def __getstate__(self): r""" Return the dictionary that should be pickled. - OUTPUT: - - :class:`dict` + OUTPUT: :class:`dict` TESTS:: @@ -2206,9 +2176,9 @@ def cones(self, dim=None, codim=None): INPUT: - - ``dim`` -- dimension of the requested cones; + - ``dim`` -- dimension of the requested cones - - ``codim`` -- codimension of the requested cones. + - ``codim`` -- codimension of the requested cones .. NOTE:: @@ -2290,7 +2260,7 @@ def contains(self, cone) -> bool: INPUT: - - ``cone`` -- anything. + - ``cone`` -- anything OUTPUT: @@ -2359,7 +2329,7 @@ def embed(self, cone): or :meth:`~sage.geometry.cone.ConvexRationalPolyhedralCone.facet_of`. The cone returned by this method will have ``self`` as ambient. If ``cone`` - does not represent a valid cone of ``self``, :class:`ValueError` + does not represent a valid cone of ``self``, :exc:`ValueError` exception is raised. .. NOTE:: @@ -2372,7 +2342,7 @@ def embed(self, cone): INPUT: - ``cone`` -- a :class:`cone - `. + ` OUTPUT: @@ -2456,9 +2426,7 @@ def Gale_transform(self): r""" Return the Gale transform of ``self``. - OUTPUT: - - A matrix over `ZZ` + OUTPUT: a matrix over `ZZ` EXAMPLES:: @@ -2479,11 +2447,9 @@ def generating_cone(self, n): INPUT: - - ``n`` -- integer, the index of a generating cone. - - OUTPUT: + - ``n`` -- integer; the index of a generating cone - :class:`cone of fan` + OUTPUT: :class:`cone of fan` EXAMPLES:: @@ -2497,9 +2463,7 @@ def generating_cones(self): r""" Return generating cones of ``self``. - OUTPUT: - - :class:`tuple` of :class:`cones of fan` + OUTPUT: :class:`tuple` of :class:`cones of fan` EXAMPLES:: @@ -2572,9 +2536,7 @@ def is_complete(self) -> bool: A rational polyhedral fan is *complete* if its cones fill the whole space. - OUTPUT: - - ``True`` if ``self`` is complete and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is complete and ``False`` otherwise EXAMPLES:: @@ -2612,7 +2574,7 @@ def is_equivalent(self, other) -> bool: INPUT: - - ``other`` -- fan. + - ``other`` -- fan OUTPUT: @@ -2688,7 +2650,7 @@ def is_isomorphic(self, other) -> bool: INPUT: - - ``other`` -- a :class:`fan `. + - ``other`` -- a :class:`fan ` OUTPUT: @@ -2755,9 +2717,7 @@ def _2d_echelon_forms(self): """ Return all echelon forms of the cyclically ordered rays of a 2-d fan. - OUTPUT: - - A set of integer matrices + OUTPUT: a set of integer matrices EXAMPLES:: @@ -2777,9 +2737,7 @@ def _2d_echelon_form(self): """ Return the echelon form of one particular cyclic order of rays of a 2-d fan. - OUTPUT: - - An integer matrix whose columns are the rays in the echelon form + OUTPUT: integer matrix whose columns are the rays in the echelon form EXAMPLES:: @@ -2797,7 +2755,7 @@ def isomorphism(self, other): INPUT: - - ``other`` -- fan. + - ``other`` -- fan OUTPUT: @@ -2843,9 +2801,7 @@ def is_simplicial(self) -> bool: i.e. primitive vectors along generating rays of every cone form a part of a *rational* basis of the ambient space. - OUTPUT: - - ``True`` if ``self`` is simplicial and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is simplicial and ``False`` otherwise EXAMPLES:: @@ -2890,7 +2846,7 @@ def is_smooth(self, codim=None) -> bool: INPUT: - ``codim`` -- codimension in which smoothness has to be checked, by - default complete smoothness will be checked. + default complete smoothness will be checked OUTPUT: @@ -2962,9 +2918,7 @@ def ngenerating_cones(self): r""" Return the number of generating cones of ``self``. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -2988,9 +2942,7 @@ def plot(self, **options): - any options for toric plots (see :func:`toric_plotter.options `), none are mandatory. - OUTPUT: - - a plot + OUTPUT: a plot EXAMPLES:: @@ -3005,7 +2957,7 @@ def plot(self, **options): return result def subdivide(self, new_rays=None, make_simplicial=False, - algorithm="default", verbose=False): + algorithm='default', verbose=False): r""" Construct a new fan subdividing ``self``. @@ -3022,7 +2974,7 @@ def subdivide(self, new_rays=None, make_simplicial=False, "default"; - ``verbose`` -- if ``True``, some timing information may be printed - during the process of subdivision. + during the process of subdivision OUTPUT: @@ -3102,7 +3054,7 @@ def virtual_rays(self, *args): INPUT: - - ``ray_list`` -- a list of integers, the indices of the + - ``ray_list`` -- list of integers; the indices of the requested virtual rays. If not specified, all virtual rays of ``self`` will be returned. @@ -3256,9 +3208,7 @@ def Stanley_Reisner_ideal(self, ring): - A polynomial ring in ``self.nrays()`` variables. - OUTPUT: - - The Stanley-Reisner ideal in the given polynomial ring + OUTPUT: the Stanley-Reisner ideal in the given polynomial ring EXAMPLES:: @@ -3307,7 +3257,7 @@ def oriented_boundary(self, cone): INPUT: - - ``cone`` -- a cone of the fan or the whole fan. + - ``cone`` -- a cone of the fan or the whole fan OUTPUT: @@ -3433,11 +3383,9 @@ def toric_variety(self, *args, **kwds): INPUT: - same arguments as :func:`~sage.schemes.toric.variety.ToricVariety` - - OUTPUT: + Same arguments as :func:`~sage.schemes.toric.variety.ToricVariety`. - a toric variety + OUTPUT: a toric variety This is equivalent to the command ``ToricVariety(self)`` and is provided only as a convenient alternative method to go from the @@ -3467,7 +3415,7 @@ def complex(self, base_ring=ZZ, extended=False): \ZZ^{\Sigma(0)} \longrightarrow 0 - where the leftmost non-zero entry is in degree `0` and the + where the leftmost nonzero entry is in degree `0` and the rightmost entry in degree `d`. See [Kly1990]_, eq. (3.2). This complex computes the homology of `|\Sigma|\subset N_\RR` with arbitrary support, @@ -3478,7 +3426,7 @@ def complex(self, base_ring=ZZ, extended=False): For a complete fan, this is just the non-compactly supported homology of `\RR^d`. In this case, `H_0(K)=\ZZ` and `0` in all - non-zero degrees. + nonzero degrees. For a complete fan, there is an extended chain complex @@ -3501,18 +3449,18 @@ def complex(self, base_ring=ZZ, extended=False): INPUT: - - ``extended`` -- Boolean (default: ``False``). Whether to + - ``extended`` -- boolean (default: ``False``); whether to construct the extended complex, that is, including the - `\ZZ`-term at degree -1 or not. + `\ZZ`-term at degree -1 or not - - ``base_ring`` -- A ring (default: ``ZZ``). The ring to use - instead of `\ZZ`. + - ``base_ring`` -- a ring (default: ``ZZ``); the ring to use + instead of `\ZZ` OUTPUT: The complex associated to the fan as a :class:`ChainComplex `. This raises a - :class:`ValueError` if the extended complex is requested for a + :exc:`ValueError` if the extended complex is requested for a non-complete fan. EXAMPLES:: @@ -3606,8 +3554,8 @@ def discard_faces(cones): INPUT: - - ``cones`` -- a list of - :class:`cones `. + - ``cones`` -- list of + :class:`cones ` OUTPUT: @@ -3651,11 +3599,9 @@ def _refine_arrangement_to_fan(cones): INPUT: - - ``cones`` -- a list of rational cones that are possibly overlapping. - - OUTPUT: + - ``cones`` -- list of rational cones that are possibly overlapping - a list of refined cones + OUTPUT: list of refined cones EXAMPLES:: diff --git a/src/sage/geometry/fan_isomorphism.py b/src/sage/geometry/fan_isomorphism.py index d06fb1f6688..bae1501e897 100644 --- a/src/sage/geometry/fan_isomorphism.py +++ b/src/sage/geometry/fan_isomorphism.py @@ -29,11 +29,9 @@ def fan_isomorphic_necessary_conditions(fan1, fan2): INPUT: - - ``fan1``, ``fan2`` -- two fans. + - ``fan1``, ``fan2`` -- two fans - OUTPUT: - - Boolean. ``False`` if the two fans cannot be isomorphic. ``True`` + OUTPUT: boolean; ``False`` if the two fans cannot be isomorphic. ``True`` if the two fans may be isomorphic. EXAMPLES:: @@ -69,7 +67,7 @@ def fan_isomorphism_generator(fan1, fan2): INPUT: - - ``fan1``, ``fan2`` -- two fans. + - ``fan1``, ``fan2`` -- two fans OUTPUT: @@ -193,16 +191,16 @@ def find_isomorphism(fan1, fan2, check=False): INPUT: - - ``fan1``, ``fan2`` -- two fans. + - ``fan1``, ``fan2`` -- two fans - - ``check`` -- boolean (default: ``False``). Passed to the fan + - ``check`` -- boolean (default: ``False``); passed to the fan morphism constructor, see - :func:`~sage.geometry.fan_morphism.FanMorphism`. + :func:`~sage.geometry.fan_morphism.FanMorphism` OUTPUT: A fan isomorphism. If the fans are not isomorphic, a - :class:`FanNotIsomorphicError` is raised. + :exc:`FanNotIsomorphicError` is raised. EXAMPLES:: @@ -251,7 +249,7 @@ def fan_2d_cyclically_ordered_rays(fan): INPUT: - - ``fan`` -- a 2-dimensional fan. + - ``fan`` -- a 2-dimensional fan OUTPUT: @@ -302,7 +300,7 @@ def fan_2d_echelon_forms(fan): INPUT: - - ``fan`` -- a fan. + - ``fan`` -- a fan OUTPUT: @@ -373,7 +371,7 @@ def fan_2d_echelon_form(fan): INPUT: - - ``fan`` -- a fan. + - ``fan`` -- a fan OUTPUT: diff --git a/src/sage/geometry/fan_morphism.py b/src/sage/geometry/fan_morphism.py index 5a8aef777f8..ddefd299133 100644 --- a/src/sage/geometry/fan_morphism.py +++ b/src/sage/geometry/fan_morphism.py @@ -122,29 +122,27 @@ class FanMorphism(FreeModuleMorphism): integral matrix defining such a morphism; - ``domain_fan`` -- a :class:`fan - ` in the domain; + ` in the domain - ``codomain`` -- (default: ``None``) either a codomain lattice or a fan in the codomain. If the codomain fan is not given, the image fan (fan generated by images of generating cones) of ``domain_fan`` will be used, - if possible; + if possible. - - ``subdivide`` -- (default: ``False``) if ``True`` and ``domain_fan`` is + - ``subdivide`` -- boolean (default: ``False``); if ``True`` and ``domain_fan`` is not compatible with the codomain fan because it is too coarse, it will be automatically refined to become compatible (the minimal refinement is - canonical, so there are no choices involved); + canonical, so there are no choices involved) - - ``check`` -- (default: ``True``) if ``False``, given fans and morphism + - ``check`` -- boolean (default: ``True``); if ``False``, given fans and morphism will be assumed to be compatible. Be careful when using this option, since wrong assumptions can lead to wrong and hard-to-detect errors. On - the other hand, this option may save you some time; + the other hand, this option may save you some time. - - ``verbose`` -- (default: ``False``) if ``True``, some information may be - printed during construction of the fan morphism. + - ``verbose`` -- boolean (default: ``False``); if ``True``, some information may be + printed during construction of the fan morphism - OUTPUT: - - - a fan morphism. + OUTPUT: a fan morphism EXAMPLES: @@ -266,7 +264,7 @@ def __init__(self, morphism, domain_fan, [0 1] Domain fan: Rational polyhedral fan in 2-d lattice N Codomain fan: Rational polyhedral fan in 2-d lattice N - sage: TestSuite(fm).run(skip="_test_category") + sage: TestSuite(fm).run(skip='_test_category') """ assert isinstance(domain_fan, RationalPolyhedralFan) if isinstance(codomain, RationalPolyhedralFan): @@ -307,11 +305,9 @@ def __mul__(self, right): INPUT: - ``right`` -- a :class:`FanMorphism` whose :meth:`codomain_fan` can be - mapped to :meth:`domain_fan` of ``self`` via identity map of lattices. - - OUTPUT: + mapped to :meth:`domain_fan` of ``self`` via identity map of lattices - - a :class:`FanMorphism`. + OUTPUT: a :class:`FanMorphism` EXAMPLES:: @@ -392,7 +388,7 @@ def _chambers(self): - ``chambers`` is a :class:`list` of :class:`cones ` in the domain of - ``self``; + ``self`` - ``cone_to_chamber`` is a :class:`list` of integers, if its `i`-th element is `j`, then the `j`-th element of ``chambers`` is the @@ -444,11 +440,9 @@ def _construct_codomain_fan(self, check): INPUT: - - ``check`` -- passed on to the fan constructor. - - OUTPUT: + - ``check`` -- passed on to the fan constructor - - none, but the codomain fan of ``self`` is set to the constructed fan. + OUTPUT: none, but the codomain fan of ``self`` is set to the constructed fan TESTS:: @@ -481,9 +475,7 @@ def _latex_(self): r""" Return the `\LaTeX` representation of ``self``. - OUTPUT: - - - a :class:`string`. + OUTPUT: a :class:`string` EXAMPLES:: @@ -518,7 +510,7 @@ def _ray_index_map(self): domain fan is mapped to the origin. If it is `j`, then the `i`-th ray of the domain fan is mapped onto the `j`-th ray of the codomain fan. If there is a ray in the domain fan which is mapped into the relative - interior of a higher dimensional cone, a :class:`ValueError` + interior of a higher dimensional cone, a :exc:`ValueError` exception is raised. .. NOTE:: @@ -554,9 +546,7 @@ def _repr_(self): r""" Return the string representation of ``self``. - OUTPUT: - - - a :class:`string`. + OUTPUT: a :class:`string` EXAMPLES:: @@ -587,19 +577,19 @@ def _subdivide_domain_fan(self, check, verbose): INPUT: - - ``check`` -- (default: ``True``) if ``False``, some of the + - ``check`` -- boolean (default: ``True``); if ``False``, some of the consistency checks will be omitted, which saves time but can potentially lead to wrong results. Currently, with ``check=False`` option there will be no check that ``domain_fan`` - maps to ``codomain_fan``; + maps to ``codomain_fan`` - - ``verbose`` -- (default: ``False``) if ``True``, some timing - information will be printed in the process. + - ``verbose`` -- boolean (default: ``False``); if ``True``, some timing + information will be printed in the process OUTPUT: - - none, but the domain fan of self is replaced with its minimal - refinement, if possible. Otherwise a :class:`ValueError` + - none, but the domain fan of ``self`` is replaced with its minimal + refinement, if possible. Otherwise a :exc:`ValueError` exception is raised. TESTS:: @@ -761,11 +751,9 @@ def _subdivide_domain_fan(self, check, verbose): def _support_error(self): r""" - Raise a :class:`ValueError` exception due to support incompatibility. + Raise a :exc:`ValueError` exception due to support incompatibility. - OUTPUT: - - - none, a :class:`ValueError` exception is raised. + OUTPUT: none, a :exc:`ValueError` exception is raised TESTS: @@ -804,7 +792,7 @@ def _validate(self): OUTPUT: - - none, but a :class:`ValueError` exception is raised if there is + - none, but a :exc:`ValueError` exception is raised if there is a cone of the domain fan of ``self`` which is not completely contained in a single cone of the codomain fan of ``self``, or if one of these fans does not sit in the appropriate lattice. @@ -894,9 +882,9 @@ def codomain_fan(self, dim=None, codim=None): INPUT: - - ``dim`` -- dimension of the requested cones; + - ``dim`` -- dimension of the requested cones - - ``codim`` -- codimension of the requested cones. + - ``codim`` -- codimension of the requested cones OUTPUT: @@ -924,9 +912,9 @@ def domain_fan(self, dim=None, codim=None): INPUT: - - ``dim`` -- dimension of the requested cones; + - ``dim`` -- dimension of the requested cones - - ``codim`` -- codimension of the requested cones. + - ``codim`` -- codimension of the requested cones OUTPUT: @@ -1020,9 +1008,7 @@ def index(self, cone=None): ` of the :meth:`codomain_fan` of ``self``. - OUTPUT: - - - an integer, infinity, or ``None``. + OUTPUT: integer, infinity, or ``None`` If no cone was specified, this function computes the index of the image of ``self`` in the codomain. If a cone `\sigma` was given, the @@ -1122,9 +1108,7 @@ def is_birational(self): r""" Check if ``self`` is birational. - OUTPUT: - - - ``True`` if ``self`` is birational, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is birational, ``False`` otherwise For fan morphisms this check is equivalent to ``self.index() == 1`` and means that the corresponding map between toric varieties is birational. @@ -1149,9 +1133,7 @@ def is_bundle(self): r""" Check if ``self`` is a bundle. - OUTPUT: - - - ``True`` if ``self`` is a bundle, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is a bundle, ``False`` otherwise Let `\phi: \Sigma \to \Sigma'` be a fan morphism such that the underlying lattice morphism `\phi: N \to N'` is surjective. Let @@ -1246,9 +1228,7 @@ def is_fibration(self): r""" Check if ``self`` is a fibration. - OUTPUT: - - - ``True`` if ``self`` is a fibration, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is a fibration, ``False`` otherwise A fan morphism `\phi: \Sigma \to \Sigma'` is a **fibration** if for any cone `\sigma' \in \Sigma'` and any primitive @@ -1334,9 +1314,7 @@ def is_injective(self): r""" Check if ``self`` is injective. - OUTPUT: - - - ``True`` if ``self`` is injective, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is injective, ``False`` otherwise Let `\phi: \Sigma \to \Sigma'` be a fan morphism such that the underlying lattice morphism `\phi: N \to N'` bijectively maps `N` to a @@ -1407,9 +1385,7 @@ def is_surjective(self): r""" Check if ``self`` is surjective. - OUTPUT: - - - ``True`` if ``self`` is surjective, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is surjective, ``False`` otherwise A fan morphism `\phi: \Sigma \to \Sigma'` is **surjective** if the corresponding map between cones is surjective, i.e. for each cone @@ -1484,9 +1460,7 @@ def is_dominant(self): of toric varieties is dominant in the algebraic-geometric sense (that is, surjective onto a dense subset). - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1505,9 +1479,7 @@ def kernel_fan(self): r""" Return the subfan of the domain fan mapped into the origin. - OUTPUT: - - - a :class:`fan `. + OUTPUT: a :class:`fan ` .. NOTE:: @@ -1607,11 +1579,9 @@ def preimage_fan(self, cone): - ``cone`` -- a :class:`cone ` equivalent to a - cone of the :meth:`codomain_fan` of ``self``. - - OUTPUT: + cone of the :meth:`codomain_fan` of ``self`` - - a :class:`fan `. + OUTPUT: a :class:`fan ` .. NOTE:: @@ -1663,11 +1633,9 @@ def primitive_preimage_cones(self, cone): - ``cone`` -- a :class:`cone ` equivalent to a - cone of the :meth:`codomain_fan` of ``self``. - - OUTPUT: + cone of the :meth:`codomain_fan` of ``self`` - - a :class:`cone `. + OUTPUT: a :class:`cone ` Let `\phi: \Sigma \to \Sigma'` be a fan morphism, let `\sigma \in \Sigma`, and let `\sigma' = \phi(\sigma)`. Then `\sigma` is a @@ -1759,7 +1727,7 @@ def factor(self): \hookrightarrow \Sigma. - .. note:: + .. NOTE:: * `\Sigma_s` is the finest fan with the smallest support that is compatible with ``self``: any fan morphism from `\Sigma` given by @@ -1890,7 +1858,7 @@ def relative_star_generators(self, domain_cone): INPUT: - - ``domain_cone`` -- a cone of the :meth:`domain_fan` of ``self``. + - ``domain_cone`` -- a cone of the :meth:`domain_fan` of ``self`` OUTPUT: diff --git a/src/sage/geometry/hasse_diagram.py b/src/sage/geometry/hasse_diagram.py index d30f08ac8d5..99dc7dca9b8 100644 --- a/src/sage/geometry/hasse_diagram.py +++ b/src/sage/geometry/hasse_diagram.py @@ -30,11 +30,11 @@ def lattice_from_incidences(atom_to_coatoms, coatom_to_atoms, INPUT: - - ``atom_to_coatoms`` -- list, ``atom_to_coatom[i]`` should list all - coatoms over the ``i``-th atom; + - ``atom_to_coatoms`` -- list; ``atom_to_coatom[i]`` should list all + coatoms over the ``i``-th atom - - ``coatom_to_atoms`` -- list, ``coatom_to_atom[i]`` should list all - atoms under the ``i``-th coatom; + - ``coatom_to_atoms`` -- list; ``coatom_to_atom[i]`` should list all + atoms under the ``i``-th coatom - ``face_constructor`` -- function or class taking as the first two arguments sorted :class:`tuple` of integers and any keyword arguments. @@ -42,15 +42,15 @@ def lattice_from_incidences(atom_to_coatoms, coatom_to_atoms, argument and under coatoms passed as the second argument. Default implementation will just return these two tuples as a tuple; - - ``required_atoms`` -- list of atoms (default:None). Each + - ``required_atoms`` -- list of atoms (default: ``None``); each non-empty "face" requires at least one of the specified atoms present. Used to ensure that each face has a vertex. - - ``key`` -- any hashable value (default: None). It is passed down - to :class:`~sage.combinat.posets.posets.FinitePoset`. + - ``key`` -- any hashable value (default: ``None``); it is passed down + to :class:`~sage.combinat.posets.posets.FinitePoset` - all other keyword arguments will be passed to ``face_constructor`` on - each call. + each call OUTPUT: diff --git a/src/sage/geometry/hyperbolic_space/hyperbolic_geodesic.py b/src/sage/geometry/hyperbolic_space/hyperbolic_geodesic.py index cb541e295d0..b9488e77b16 100644 --- a/src/sage/geometry/hyperbolic_space/hyperbolic_geodesic.py +++ b/src/sage/geometry/hyperbolic_space/hyperbolic_geodesic.py @@ -131,7 +131,6 @@ class HyperbolicGeodesic(SageObject): Geodesic in KM from (0, 1/2) to (1/2, 0) sage: HyperbolicPlane().HM().get_geodesic((0,0,1), (0,1, sqrt(2))) Geodesic in HM from (0, 0, 1) to (0, 1, sqrt(2)) - """ ##################### @@ -162,7 +161,6 @@ def _cached_geodesic(self): sage: A = HyperbolicPlane().PD().get_geodesic(0, 1/2) sage: A._cached_geodesic Geodesic in UHP from I to 3/5*I + 4/5 - """ M = self._model.realization_of().a_realization() @@ -187,7 +185,6 @@ def _complete(self): False sage: g.complete()._complete True - """ if self._model.is_bounded(): @@ -215,7 +212,6 @@ def _repr_(self): sage: HM = HyperbolicPlane().HM() sage: HM.get_geodesic((0,0,1), (0, 1, sqrt(Integer(2)))) Geodesic in HM from (0, 0, 1) to (0, 1, sqrt(2)) - """ msg = "Geodesic in {0} from {1} to {2}" @@ -244,7 +240,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Test unequality of self and other. + Test unequality of ``self`` and ``other``. EXAMPLES:: @@ -270,7 +266,6 @@ def start(self): sage: g = HyperbolicPlane().UHP().get_geodesic(I, 3*I) sage: g.start() Point in UHP I - """ return self._start @@ -283,7 +278,6 @@ def end(self): sage: g = HyperbolicPlane().UHP().get_geodesic(I, 3*I) sage: g.end() Point in UHP 3*I - """ return self._end @@ -297,7 +291,6 @@ def endpoints(self): sage: g = HyperbolicPlane().UHP().get_geodesic(I, 3*I) sage: g.endpoints() [Point in UHP I, Point in UHP 3*I] - """ return [self._start, self._end] @@ -342,7 +335,6 @@ def to_model(self, model): Geodesic in PD from 0 to 1/3*I sage: UHP.get_geodesic(I, 2*I).to_model('PD') Geodesic in PD from 0 to 1/3*I - """ if isinstance(model, str): @@ -360,12 +352,10 @@ def graphics_options(self): EXAMPLES:: - sage: g = HyperbolicPlane().UHP().get_geodesic(I, 2*I, color="red") + sage: g = HyperbolicPlane().UHP().get_geodesic(I, 2*I, color='red') sage: g.graphics_options() {'color': 'red'} - """ - return self._graphics_options def update_graphics(self, update=False, **options): @@ -391,7 +381,6 @@ def update_graphics(self, update=False, **options): sage: g.update_graphics(True, size = 20); g.graphics_options() {'color': 'blue', 'size': 20} - """ if not update: @@ -447,7 +436,6 @@ def is_complete(self): True sage: UHP.get_geodesic(2,5).is_complete() True - """ return self._complete @@ -493,7 +481,6 @@ def is_asymptotically_parallel(self, other): sage: g = HyperbolicPlane().UHP().get_geodesic(-2,5) sage: g.is_asymptotically_parallel(g) False - """ p1, p2 = self.complete().endpoints() @@ -543,7 +530,6 @@ def is_ultra_parallel(self, other): sage: g = HyperbolicPlane().UHP().get_geodesic(-2,5) sage: g.is_ultra_parallel(g) False - """ A = self.reflection_involution() @@ -610,7 +596,6 @@ def is_parallel(self, other): sage: g = HyperbolicPlane().UHP().get_geodesic(-2,5) sage: g.is_parallel(g) False - """ A = self.reflection_involution() @@ -620,7 +605,7 @@ def is_parallel(self, other): def ideal_endpoints(self): r""" Return the ideal endpoints in bounded models. Raise a - :class:`NotImplementedError` in models that are not bounded. + :exc:`NotImplementedError` in models that are not bounded. EXAMPLES:: @@ -643,7 +628,6 @@ def ideal_endpoints(self): ... NotImplementedError: boundary points are not implemented in the HM model - """ if not self._model.is_bounded(): @@ -658,7 +642,7 @@ def ideal_endpoints(self): def complete(self): r""" Return the geodesic with ideal endpoints in bounded models. Raise a - :class:`NotImplementedError` in models that are not bounded. + :exc:`NotImplementedError` in models that are not bounded. In the following examples we represent complete geodesics by a dashed line. @@ -744,7 +728,6 @@ def complete(self): sage: gc = g.complete() sage: parent(gc.start().coordinates()) Real Field with 53 bits of precision - """ if self._model.is_bounded(): @@ -805,7 +788,6 @@ def reflection_involution(self): sage: R = H.PD().get_geodesic(-1,1).reflection_involution() sage: bool(moebius_transform(R.matrix(), 0) == 0) True - """ ri = self._cached_geodesic.reflection_involution() @@ -815,15 +797,13 @@ def common_perpendicula(self, other): r""" Return the unique hyperbolic geodesic perpendicular to two given geodesics, if such a geodesic exists. If none exists, raise a - :class:`ValueError`. + :exc:`ValueError`. INPUT: - ``other`` -- a hyperbolic geodesic in the same model as ``self`` - OUTPUT: - - - a hyperbolic geodesic + OUTPUT: a hyperbolic geodesic EXAMPLES:: @@ -851,7 +831,6 @@ def common_perpendicula(self, other): Traceback (most recent call last): ... ValueError: geodesics intersect; no common perpendicular exists - """ if not self.is_parallel(other): @@ -869,14 +848,11 @@ def intersection(self, other): - ``other`` -- a hyperbolic geodesic in the same model as ``self`` - OUTPUT: - - - a hyperbolic point or geodesic + OUTPUT: a hyperbolic point or geodesic EXAMPLES:: sage: PD = HyperbolicPlane().PD() - """ if self == other: @@ -951,7 +927,6 @@ def midpoint(self): Traceback (most recent call last): ... ValueError: the length must be finite - """ UHP = self._model.realization_of().a_realization() @@ -968,9 +943,7 @@ def dist(self, other): - ``other`` -- a hyperbolic geodesic or hyperbolic point in the same model - OUTPUT: - - - the hyperbolic distance + OUTPUT: the hyperbolic distance EXAMPLES:: @@ -1000,7 +973,6 @@ def dist(self, other): 1.45057451382258 sage: parent(_) Real Field with 53 bits of precision - """ return self._model.dist(self, other) @@ -1014,9 +986,7 @@ def angle(self, other): - ``other`` -- a hyperbolic geodesic in the same model as ``self`` - OUTPUT: - - - the angle in radians between the two given geodesics + OUTPUT: the angle in radians between the two given geodesics EXAMPLES:: @@ -1032,7 +1002,6 @@ def angle(self, other): g = PD.get_geodesic(3.0/5.0*I + 4.0/5.0, 15.0/17.0*I + 8.0/17.0) h = PD.get_geodesic(4.0/5.0*I + 3.0/5.0, I) sphinx_plot(g.plot()+h.plot(color='orange')) - """ return self._cached_geodesic.angle(other) @@ -1046,7 +1015,6 @@ def length(self): sage: g = HyperbolicPlane().UHP().get_geodesic(2 + I, 3 + I/2) sage: g.length() arccosh(9/4) - """ return self._model._dist_points(self._start.coordinates(), @@ -1086,7 +1054,6 @@ class HyperbolicGeodesicUHP(HyperbolicGeodesic): g = UHP.get_geodesic(I, 2 + I) h = UHP.get_geodesic(-1, -1+2*I) sphinx_plot(g.plot()+h.plot()) - """ def reflection_involution(self): @@ -1105,7 +1072,6 @@ def reflection_involution(self): Isometry in UHP [ 1 0] [ 0 -1] - """ x, y = (real(k.coordinates()) for k in self.ideal_endpoints()) @@ -1135,13 +1101,13 @@ def plot(self, boundary=True, **options): :: - sage: UHP.get_geodesic(I, 3+4*I).plot(linestyle="dashed", color="brown") # needs sage.plot + sage: UHP.get_geodesic(I, 3+4*I).plot(linestyle='dashed', color='brown') # needs sage.plot Graphics object consisting of 2 graphics primitives .. PLOT:: UHP = HyperbolicPlane().UHP() - g = UHP.get_geodesic(I, 3+4*I).plot(linestyle="dashed", color="brown") + g = UHP.get_geodesic(I, 3+4*I).plot(linestyle='dashed', color='brown') sphinx_plot(g) :: @@ -1180,7 +1146,6 @@ def plot(self, boundary=True, **options): sage: g = HyperbolicPlane().UHP().get_geodesic(3, 4) sage: g.plot(boundary=False) # needs sage.plot Graphics object consisting of 1 graphics primitive - """ opts = {'axes': False, 'aspect_ratio': 1} @@ -1236,9 +1201,7 @@ def ideal_endpoints(self): Determine the ideal (boundary) endpoints of the complete hyperbolic geodesic corresponding to ``self``. - OUTPUT: - - - a list of 2 boundary points + OUTPUT: list of 2 boundary points EXAMPLES:: @@ -1249,7 +1212,6 @@ def ideal_endpoints(self): sage: UHP.get_geodesic(1 + I, 2 + 4*I).ideal_endpoints() [Boundary point in UHP -sqrt(65) + 9, Boundary point in UHP sqrt(65) + 9] - """ start = self._start.coordinates() @@ -1276,15 +1238,13 @@ def common_perpendicular(self, other): r""" Return the unique hyperbolic geodesic perpendicular to ``self`` and ``other``, if such a geodesic exists; otherwise raise a - :class:`ValueError`. + :exc:`ValueError`. INPUT: - ``other`` -- a hyperbolic geodesic in current model - OUTPUT: - - - a hyperbolic geodesic + OUTPUT: a hyperbolic geodesic EXAMPLES:: @@ -1311,7 +1271,6 @@ def common_perpendicular(self, other): Traceback (most recent call last): ... ValueError: geodesics intersect; no common perpendicular exists - """ # Make sure both are in the same model @@ -1335,9 +1294,7 @@ def intersection(self, other): - ``other`` -- a hyperbolic geodesic in the current model - OUTPUT: - - - a list of hyperbolic points or a hyperbolic geodesic + OUTPUT: list of hyperbolic points or a hyperbolic geodesic EXAMPLES:: @@ -1353,7 +1310,7 @@ def intersection(self, other): g = UHP.get_geodesic(3, 5) h = UHP.get_geodesic(4, 7) P = g.intersection(h) - pict = g.plot(color="red")+h.plot(color="red") + pict = g.plot(color='red')+h.plot(color='red') sphinx_plot(pict) If the given geodesics do not intersect, the function returns an @@ -1467,7 +1424,6 @@ def intersection(self, other): sage: g2=UHP.get_geodesic(3*I,infinity) sage: g1.intersection(g2) Geodesic in UHP from 3.00000000000000*I to +infinity - """ UHP = self.model() @@ -1717,9 +1673,7 @@ def angle(self, other): # UHP - ``other`` -- a hyperbolic geodesic in the UHP model - OUTPUT: - - - the angle in radians between the two given geodesics + OUTPUT: the angle in radians between the two given geodesics EXAMPLES:: @@ -1917,7 +1871,6 @@ def angle(self, other): # UHP arccos(1/3) sage: h2.angle(g) arccos(1/3) - """ if self.is_parallel(other): @@ -1955,7 +1908,7 @@ def angle(self, other): # UHP # is ``infinity``. if infinity in [q1, q2]: p1, p2, q1, q2 = q1, q2, p1, p2 - # Then, if ``p1`` is infinity, swap ``p1` and ``p2`. This + # Then, if ``p1`` is infinity, swap ``p1`` and ``p2``. This # ensures that if any element of ``{p1, p2}`` is ``infinity``, # then that element is now ``p2``. if p1 == infinity: @@ -1994,7 +1947,7 @@ def _get_B(a): INPUT: - - ``a`` -- an element to identify the class of the resulting matrix. + - ``a`` -- an element to identify the class of the resulting matrix EXAMPLES:: @@ -2092,7 +2045,6 @@ def _to_std_geod(self, p): sage: parent(gc._to_std_geod(g.start().coordinates())) Full MatrixSpace of 2 by 2 dense matrices over Complex Field with 53 bits of precision - """ [s, e] = [k.coordinates() for k in self.complete().endpoints()] @@ -2115,13 +2067,11 @@ def _crossratio_matrix(p0, p1, p2): # UHP INPUT: - - a list of three distinct elements + - ``p0``, ``p1``, ``p2`` -- a list of three distinct elements of `\mathbb{CP}^1` in affine coordinates; that is, each element must be a complex number, `\infty`, or symbolic. - OUTPUT: - - - an element of `\GL(2,\CC)` + OUTPUT: an element of `\GL(2,\CC)` EXAMPLES:: @@ -2143,7 +2093,6 @@ def _crossratio_matrix(p0, p1, p2): # UHP sage: HyperbolicGeodesicUHP._crossratio_matrix(x,y,z) [ y - z -x*(y - z)] [ -x + y (x - y)*z] - """ if p0 == infinity: @@ -2222,10 +2171,10 @@ def plot(self, boundary=True, **options): sage: PD.get_geodesic(-0.5, 0.3+0.4*I).plot() # needs sage.plot Graphics object consisting of 2 graphics primitives sage: g = PD.get_geodesic(-1, exp(3*I*pi/7)) - sage: G = g.plot(linestyle="dashed",color="red"); G # needs sage.plot + sage: G = g.plot(linestyle='dashed',color='red'); G # needs sage.plot Graphics object consisting of 2 graphics primitives sage: h = PD.get_geodesic(exp(2*I*pi/11), exp(1*I*pi/11)) - sage: H = h.plot(thickness=6, color="orange"); H # needs sage.plot + sage: H = h.plot(thickness=6, color='orange'); H # needs sage.plot Graphics object consisting of 2 graphics primitives sage: show(G+H) # needs sage.plot @@ -2234,11 +2183,10 @@ def plot(self, boundary=True, **options): PD = HyperbolicPlane().PD() PD.get_geodesic(-0.5, 0.3+0.4*I).plot() g = PD.get_geodesic(-1, exp(3*I*pi/7)) - G = g.plot(linestyle="dashed",color="red") + G = g.plot(linestyle='dashed',color='red') h = PD.get_geodesic(exp(2*I*pi/11), exp(1*I*pi/11)) - H = h.plot(thickness=6, color="orange") + H = h.plot(thickness=6, color='orange') sphinx_plot(G+H) - """ opts = {'axes': False, 'aspect_ratio': 1} @@ -2302,7 +2250,6 @@ class HyperbolicGeodesicKM(HyperbolicGeodesic): h = KM.get_geodesic(CC(-0.707106781,-0.707106781), CC(0.707106781,-0.707106781)) sphinx_plot(g.plot(color='orange')+h.plot()) - """ def plot(self, boundary=True, **options): @@ -2318,7 +2265,6 @@ def plot(self, boundary=True, **options): KM = HyperbolicPlane().KM() sphinx_plot(KM.get_geodesic(CC(0,0), CC(1,0)).plot()) - """ opts = {'axes': False, 'aspect_ratio': 1} opts.update(self.graphics_options()) @@ -2365,7 +2311,6 @@ class HyperbolicGeodesicHM(HyperbolicGeodesic): p2 = HM.get_point((-3,-3,sqrt(19))) g = HM.get_geodesic(p1, p2) sphinx_plot(g.plot(color='blue')) - """ def _plot_vertices(self, points=75): r""" @@ -2428,7 +2373,6 @@ def plot(self, show_hyperboloid=True, **graphics_options): .. PLOT:: sphinx_plot(HyperbolicPlane().HM().random_geodesic().plot()) - """ x = SR.var('x') diff --git a/src/sage/geometry/hyperbolic_space/hyperbolic_isometry.py b/src/sage/geometry/hyperbolic_space/hyperbolic_isometry.py index 45b37b7f91d..03a646b7059 100644 --- a/src/sage/geometry/hyperbolic_space/hyperbolic_isometry.py +++ b/src/sage/geometry/hyperbolic_space/hyperbolic_isometry.py @@ -89,7 +89,7 @@ def __init__(self, model, A, check=True): EXAMPLES:: sage: A = HyperbolicPlane().UHP().get_isometry(matrix(2, [0,1,-1,0])) - sage: TestSuite(A).run(skip="_test_category") + sage: TestSuite(A).run(skip='_test_category') """ if check: model.isometry_test(A) @@ -120,9 +120,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string EXAMPLES:: @@ -489,7 +487,7 @@ def classification(self): def translation_length(self): r""" For hyperbolic elements, return the translation length; - otherwise, raise a :class:`ValueError`. + otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -512,7 +510,7 @@ def translation_length(self): def axis(self): r""" For a hyperbolic isometry, return the axis of the - transformation; otherwise raise a :class:`ValueError`. + transformation; otherwise raise a :exc:`ValueError`. EXAMPLES:: @@ -540,9 +538,7 @@ def fixed_point_set(self): Return a list containing the fixed point set of orientation-preserving isometries. - OUTPUT: - - list of hyperbolic points or a hyperbolic geodesic + OUTPUT: list of hyperbolic points or a hyperbolic geodesic EXAMPLES:: @@ -593,11 +589,9 @@ def fixed_geodesic(self): def repelling_fixed_point(self): r""" For a hyperbolic isometry, return the attracting fixed point; - otherwise raise a :class:`ValueError`. - - OUTPUT: + otherwise raise a :exc:`ValueError`. - - a hyperbolic point + OUTPUT: a hyperbolic point EXAMPLES:: @@ -612,11 +606,9 @@ def repelling_fixed_point(self): def attracting_fixed_point(self): r""" For a hyperbolic isometry, return the attracting fixed point; - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. - OUTPUT: - - - a hyperbolic point + OUTPUT: a hyperbolic point EXAMPLES:: @@ -735,7 +727,7 @@ def classification(self): #UHP def translation_length(self): #UHP r""" For hyperbolic elements, return the translation length; - otherwise, raise a :class:`ValueError`. + otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -762,9 +754,7 @@ def fixed_point_set(self): # UHP Return a list or geodesic containing the fixed point set of orientation-preserving isometries. - OUTPUT: - - list of hyperbolic points or a hyperbolic geodesic + OUTPUT: list of hyperbolic points or a hyperbolic geodesic EXAMPLES:: @@ -847,11 +837,9 @@ def repelling_fixed_point(self): # UHP r""" Return the repelling fixed point. - Otherwise, this raises a :class:`ValueError`. + Otherwise, this raises a :exc:`ValueError`. - OUTPUT: - - - a hyperbolic point + OUTPUT: a hyperbolic point EXAMPLES:: @@ -873,11 +861,9 @@ def attracting_fixed_point(self): # UHP r""" Return the attracting fixed point. - Otherwise, this raises a :class:`ValueError`. - - OUTPUT: + Otherwise, this raises a :exc:`ValueError`. - - a hyperbolic point + OUTPUT: a hyperbolic point EXAMPLES:: @@ -957,7 +943,6 @@ def __pow__(self, n): #PD Isometry in PD [ 5/8 3/8*I] [-3/8*I 5/8] - """ return (self._cached_isometry**n).to_model('PD') @@ -1044,9 +1029,7 @@ def moebius_transform(A, z): - ``A`` -- a `2 \times 2` invertible matrix over the complex numbers - ``z`` -- a complex number or infinity - OUTPUT: - - - a complex number or infinity + OUTPUT: a complex number or infinity EXAMPLES:: diff --git a/src/sage/geometry/hyperbolic_space/hyperbolic_model.py b/src/sage/geometry/hyperbolic_space/hyperbolic_model.py index 8533329d7c5..d9def677e6d 100644 --- a/src/sage/geometry/hyperbolic_space/hyperbolic_model.py +++ b/src/sage/geometry/hyperbolic_space/hyperbolic_model.py @@ -243,9 +243,7 @@ def point_in_model(self, p): - any object that can converted into a complex number - OUTPUT: - - - boolean + OUTPUT: boolean EXAMPLES:: @@ -259,7 +257,7 @@ def point_in_model(self, p): def point_test(self, p): # Abstract r""" Test whether a point is in the model. If the point is in the - model, do nothing. Otherwise, raise a :class:`ValueError`. + model, do nothing. Otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -283,9 +281,7 @@ def boundary_point_in_model(self, p): # Abstract - any object that can converted into a complex number - OUTPUT: - - - boolean + OUTPUT: boolean EXAMPLES:: @@ -297,7 +293,7 @@ def boundary_point_in_model(self, p): # Abstract def bdry_point_test(self, p): # Abstract r""" Test whether a point is in the model. If the point is in the - model, do nothing; otherwise raise a :class:`ValueError`. + model, do nothing; otherwise raise a :exc:`ValueError`. EXAMPLES:: @@ -318,11 +314,9 @@ def isometry_in_model(self, A): # Abstract INPUT: - - a matrix that represents an isometry in the appropriate model - - OUTPUT: + - ``A`` -- a matrix that represents an isometry in the appropriate model - - boolean + OUTPUT: boolean EXAMPLES:: @@ -339,7 +333,7 @@ def isometry_test(self, A): # Abstract Test whether an isometry ``A`` is in the model. If the isometry is in the model, do nothing. Otherwise, raise - a :class:`ValueError`. + a :exc:`ValueError`. EXAMPLES:: @@ -369,9 +363,7 @@ def get_point(self, coordinates, is_boundary=None, **graphics_options): - a point in hyperbolic space or on the ideal boundary - OUTPUT: - - - a :class:`~sage.geometry.hyperbolic_space.hyperbolic_point.HyperbolicPoint` + OUTPUT: a :class:`~sage.geometry.hyperbolic_space.hyperbolic_point.HyperbolicPoint` EXAMPLES: @@ -406,7 +398,7 @@ def get_point(self, coordinates, is_boundary=None, **graphics_options): sage: HyperbolicPlane().HM().get_point((0,0,1)) Point in HM (0, 0, 1) - sage: p = HyperbolicPlane().UHP().get_point(I, color="red") + sage: p = HyperbolicPlane().UHP().get_point(I, color='red') sage: p.graphics_options() {'color': 'red'} @@ -565,7 +557,6 @@ def random_geodesic(self, **kwargs): sage: h = HyperbolicPlane().PD().random_geodesic() sage: all( e.coordinates().abs() <= 1 for e in h.endpoints() ) True - """ R = self.realization_of().a_realization() g_ends = [R.random_point(**kwargs) for k in range(2)] @@ -580,9 +571,7 @@ def random_isometry(self, preserve_orientation=True, **kwargs): - ``preserve_orientation`` -- if ``True`` return an orientation-preserving isometry - OUTPUT: - - - a hyperbolic isometry + OUTPUT: a hyperbolic isometry EXAMPLES:: @@ -610,9 +599,7 @@ def dist(self, a, b): - ``a``, ``b`` -- a point or geodesic - OUTPUT: - - - the hyperbolic distance + OUTPUT: the hyperbolic distance EXAMPLES:: @@ -717,9 +704,7 @@ def _dist_geod_point(self, start, end, p): - ``end`` -- the end ideal point coordinates of the geodesic - ``p`` -- the coordinates of the point - OUTPUT: - - - the hyperbolic distance + OUTPUT: the hyperbolic distance EXAMPLES:: @@ -796,7 +781,7 @@ def __init__(self, space): sage: TestSuite(UHP).run() """ HyperbolicModel.__init__(self, space, - name="Upper Half Plane Model", short_name="UHP", + name="Upper Half Plane Model", short_name='UHP', bounded=True, conformal=True, dimension=2, isometry_group="PSL(2, \\RR)", isometry_group_is_projective=True) @@ -977,9 +962,7 @@ def _dist_geod_point(self, start, end, p): - ``end`` -- the end ideal point coordinates of the geodesic - ``p`` -- the coordinates of the point - OUTPUT: - - - the hyperbolic distance + OUTPUT: the hyperbolic distance EXAMPLES:: @@ -1099,9 +1082,7 @@ def random_isometry(self, preserve_orientation=True, **kwargs): - ``preserve_orientation`` -- if ``True`` return an orientation-preserving isometry - OUTPUT: - - - a hyperbolic isometry + OUTPUT: a hyperbolic isometry EXAMPLES:: @@ -1173,7 +1154,7 @@ def __init__(self, space): # name should really be 'Poincaré Disk Model', but utf8 is not # accepted by repr HyperbolicModel.__init__(self, space, - name='Poincare Disk Model', short_name="PD", + name='Poincare Disk Model', short_name='PD', bounded=True, conformal=True, dimension=2, isometry_group="PU(1, 1)", isometry_group_is_projective=True) @@ -1299,7 +1280,7 @@ def __init__(self, space): sage: TestSuite(KM).run() """ HyperbolicModel.__init__(self, space, - name="Klein Disk Model", short_name="KM", + name="Klein Disk Model", short_name='KM', bounded=True, conformal=False, dimension=2, isometry_group="PSO(2, 1)", isometry_group_is_projective=True) @@ -1422,7 +1403,7 @@ def __init__(self, space): sage: TestSuite(HM).run() """ HyperbolicModel.__init__(self, space, - name="Hyperboloid Model", short_name="HM", + name="Hyperboloid Model", short_name='HM', bounded=False, conformal=True, dimension=2, isometry_group="SO(2, 1)", isometry_group_is_projective=False) diff --git a/src/sage/geometry/hyperbolic_space/hyperbolic_point.py b/src/sage/geometry/hyperbolic_space/hyperbolic_point.py index 67608311693..3c408e69d95 100644 --- a/src/sage/geometry/hyperbolic_space/hyperbolic_point.py +++ b/src/sage/geometry/hyperbolic_space/hyperbolic_point.py @@ -85,7 +85,7 @@ class HyperbolicPoint(Element): - ``coordinates`` -- the coordinates of a hyperbolic point in the appropriate model - ``is_boundary`` -- whether the point is a boundary point - - ``check`` -- (default: ``True``) if ``True``, then check to make sure + - ``check`` -- boolean (default: ``True``); if ``True``, then check to make sure the coordinates give a valid point in the model EXAMPLES: @@ -270,7 +270,7 @@ def _latex_(self): def _richcmp_(self, other, op): r""" - Comparison of self and other. + Comparison of ``self`` and ``other``. EXAMPLES:: @@ -443,7 +443,7 @@ def graphics_options(self): EXAMPLES:: - sage: p = HyperbolicPlane().UHP().get_point(2 + I, color="red") + sage: p = HyperbolicPlane().UHP().get_point(2 + I, color='red') sage: p.graphics_options() {'color': 'red'} """ diff --git a/src/sage/geometry/hyperplane_arrangement/affine_subspace.py b/src/sage/geometry/hyperplane_arrangement/affine_subspace.py index 7c1065553c4..94d004f987f 100644 --- a/src/sage/geometry/hyperplane_arrangement/affine_subspace.py +++ b/src/sage/geometry/hyperplane_arrangement/affine_subspace.py @@ -82,9 +82,7 @@ class AffineSubspace(SageObject): - ``V`` -- vector subspace - OUTPUT: - - Affine subspace parallel to ``V`` and passing through ``p``. + OUTPUT: affine subspace parallel to ``V`` and passing through ``p`` EXAMPLES:: @@ -136,9 +134,7 @@ def _repr_(self): r""" String representation for an :class:`AffineSubspace`. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -159,9 +155,7 @@ def __eq__(self, other): - ``other`` -- an :class:`AffineSubspace` - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -186,9 +180,7 @@ def __ne__(self, other): - ``other`` -- an :class:`AffineSubspace` - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -212,9 +204,7 @@ def __le__(self, other): - ``other`` -- an :class:`AffineSubspace` - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -243,9 +233,7 @@ def __lt__(self, other): - ``other`` -- an :class:`AffineSubspace` - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -274,9 +262,7 @@ def __contains__(self, q): - ``q`` -- point as a list/tuple/iterable - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -294,9 +280,7 @@ def linear_part(self): r""" Return the linear part of the affine space. - OUTPUT: - - A vector subspace of the ambient space. + OUTPUT: a vector subspace of the ambient space EXAMPLES:: @@ -316,9 +300,7 @@ def point(self): r""" Return a point ``p`` in the affine space. - OUTPUT: - - A point of the affine space as a vector in the ambient space. + OUTPUT: a point of the affine space as a vector in the ambient space EXAMPLES:: @@ -333,9 +315,7 @@ def dimension(self): r""" Return the dimension of the affine space. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/geometry/hyperplane_arrangement/arrangement.py b/src/sage/geometry/hyperplane_arrangement/arrangement.py index 533f7ac1151..bec72761669 100644 --- a/src/sage/geometry/hyperplane_arrangement/arrangement.py +++ b/src/sage/geometry/hyperplane_arrangement/arrangement.py @@ -382,7 +382,7 @@ def __init__(self, parent, hyperplanes, check=True, backend=None): - ``parent`` -- the parent :class:`HyperplaneArrangements` - - ``hyperplanes`` -- a tuple of hyperplanes + - ``hyperplanes`` -- tuple of hyperplanes - ``check`` -- boolean (default: ``True``); whether to check input @@ -423,9 +423,7 @@ def _first_ngens(self, n): """ Workaround to support the construction with names. - INPUT/OUTPUT: - - See :meth:`HyperplaneArrangements._first_ngens`. + INPUT/OUTPUT: see :meth:`HyperplaneArrangements._first_ngens` EXAMPLES:: @@ -443,9 +441,7 @@ def __getitem__(self, i): - ``i`` -- integer - OUTPUT: - - The `i`-th hyperplane. + OUTPUT: the `i`-th hyperplane EXAMPLES:: @@ -474,9 +470,7 @@ def n_hyperplanes(self): r""" Return the number of hyperplanes in the arrangement. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -495,9 +489,7 @@ def hyperplanes(self): r""" Return the hyperplanes in the arrangement as a tuple. - OUTPUT: - - A tuple + OUTPUT: a tuple EXAMPLES:: @@ -517,9 +509,7 @@ def _repr_(self): r""" String representation for a hyperplane arrangement. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -543,9 +533,7 @@ def dimension(self): """ Return the ambient space dimension of the arrangement. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -597,11 +585,9 @@ def rank(self): def backend(self): """ - Return the backend used for polyhedral objects - - OUTPUT: + Return the backend used for polyhedral objects. - A string giving the backend or ``None`` if none is specified. + OUTPUT: string giving the backend or ``None`` if none is specified EXAMPLES: @@ -648,9 +634,7 @@ def union(self, other): - ``other`` -- a hyperplane arrangement or something that can be converted into a hyperplane arrangement - OUTPUT: - - A new hyperplane arrangement. + OUTPUT: a new hyperplane arrangement EXAMPLES:: @@ -689,9 +673,7 @@ def plot(self, **kwds): """ Plot the hyperplane arrangement. - OUTPUT: - - A graphics object. + OUTPUT: a graphics object EXAMPLES:: @@ -763,18 +745,18 @@ def cone(self, variable='t'): return H(*hyperplanes, backend=self._backend) @cached_method - def intersection_poset(self, element_label="int"): + def intersection_poset(self, element_label='int'): r""" Return the intersection poset of the hyperplane arrangement. INPUT: - - ``element_label`` -- (default: ``"int"``) specify how an + - ``element_label`` -- (default: ``'int'``) specify how an intersection should be represented; must be one of the following: - * ``"subspace"`` -- as a subspace - * ``"subset"`` -- as a subset of the defining hyperplanes - * ``"int"`` -- as an integer + * ``'subspace'`` -- as a subspace + * ``'subset'`` -- as a subset of the defining hyperplanes + * ``'int'`` -- as an integer OUTPUT: @@ -930,9 +912,7 @@ def characteristic_polynomial(self): r""" Return the characteristic polynomial of the hyperplane arrangement. - OUTPUT: - - The characteristic polynomial in `\QQ[x]`. + OUTPUT: the characteristic polynomial in `\QQ[x]` EXAMPLES:: @@ -978,9 +958,7 @@ def poincare_polynomial(self): r""" Return the Poincaré polynomial of the hyperplane arrangement. - OUTPUT: - - The Poincaré polynomial in `\QQ[x]`. + OUTPUT: the Poincaré polynomial in `\QQ[x]` EXAMPLES:: @@ -1010,9 +988,7 @@ def cocharacteristic_polynomial(self): element of `L` (here, the `0` dimensional subspace), and `\mu` is the Möbius function of `L`. - OUTPUT: - - The cocharacteristic polynomial in `\ZZ[z]`. + OUTPUT: the cocharacteristic polynomial in `\ZZ[z]` EXAMPLES:: @@ -1039,7 +1015,7 @@ def cocharacteristic_polynomial(self): from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing R = PolynomialRing(ZZ, 'z') z = R.gen() - L = self.intersection_poset(element_label="subspace").dual() + L = self.intersection_poset(element_label='subspace').dual() B = L.minimal_elements()[0] return R.sum(abs(L.moebius_function(B, X)) * z**X.dimension() for X in L) @@ -1060,9 +1036,7 @@ def primitive_eulerian_polynomial(self): element of `L` (here, the `0` dimensional subspace), and `\mu` is the Möbius function of `L`. - OUTPUT: - - The primitive Eulerian polynomial in `\ZZ[z]`. + OUTPUT: the primitive Eulerian polynomial in `\ZZ[z]` EXAMPLES:: @@ -1106,7 +1080,7 @@ def primitive_eulerian_polynomial(self): We compute types `H_3` and `F_4` in Table 1 of [BHS2023]_:: sage: # needs sage.libs.gap - sage: W = CoxeterGroup(['H',3], implementation="matrix") + sage: W = CoxeterGroup(['H',3], implementation='matrix') sage: A = HyperplaneArrangements(W.base_ring(), tuple(f'x{s}' for s in range(W.rank()))) sage: H = A([[0] + list(r) for r in W.positive_roots()]) sage: H.is_simplicial() # needs sage.graphs @@ -1114,7 +1088,7 @@ def primitive_eulerian_polynomial(self): sage: H.primitive_eulerian_polynomial() z^3 + 28*z^2 + 16*z - sage: W = CoxeterGroup(['F',4], implementation="permutation") + sage: W = CoxeterGroup(['F',4], implementation='permutation') sage: A = HyperplaneArrangements(QQ, tuple(f'x{s}' for s in range(W.rank()))) sage: H = A([[0] + list(r) for r in W.positive_roots()]) sage: H.primitive_eulerian_polynomial() # long time # needs sage.graphs @@ -1163,7 +1137,7 @@ def primitive_eulerian_polynomial(self): from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing R = PolynomialRing(ZZ, 'z') z = R.gen() - L = self.intersection_poset(element_label="subspace").dual() + L = self.intersection_poset(element_label='subspace').dual() B = L.minimal_elements()[0] n = self.dimension() return R.sum(abs(L.moebius_function(B, X)) * (z - 1)**(n-X.dimension()) @@ -1365,9 +1339,7 @@ def n_regions(self): r""" The number of regions of the hyperplane arrangement. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -1399,7 +1371,7 @@ def n_regions(self): ....: vector(AA, [-1/2, AA(-1/2*v2^3 + v2), 0])) sage: H = HyperplaneArrangements(AA, names='xyz') sage: x,y,z = H.gens() - sage: A = H(backend="normaliz") # optional - pynormaliz + sage: A = H(backend='normaliz') # optional - pynormaliz sage: for v in my_vectors: # optional - pynormaliz ....: a, b, c = v ....: A = A.add_hyperplane(a*x + b*y + c*z) @@ -1456,9 +1428,7 @@ def has_good_reduction(self, p): - ``p`` -- prime number - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1488,9 +1458,7 @@ def is_linear(self): r""" Test whether all hyperplanes pass through the origin. - OUTPUT: - - A boolean. Whether all the hyperplanes pass through the origin. + OUTPUT: boolean EXAMPLES:: @@ -1521,9 +1489,7 @@ def is_essential(self): :meth:`essentialization` - OUTPUT: - - A boolean indicating whether the hyperplane arrangement is essential. + OUTPUT: boolean EXAMPLES:: @@ -1549,9 +1515,7 @@ def is_central(self, certificate=False): to return the center as a polyhedron (possibly empty) as part of the output - OUTPUT: - - If ``certificate`` is ``True``, returns a tuple containing: + OUTPUT: if ``certificate`` is ``True``, returns a tuple containing: 1. A boolean 2. The polyhedron defined to be the intersection of all the hyperplanes @@ -1620,9 +1584,7 @@ def center(self): ambient space of the arrangement that lie on all of the hyperplanes. - OUTPUT: - - A polyhedron. + OUTPUT: a polyhedron EXAMPLES: @@ -1658,9 +1620,7 @@ def is_simplicial(self): are linearly independent. A hyperplane arrangement is said to be simplicial if every region is simplicial. - OUTPUT: - - A boolean whether the hyperplane arrangement is simplicial. + OUTPUT: boolean; whether the hyperplane arrangement is simplicial EXAMPLES:: @@ -1763,7 +1723,7 @@ def echelon_col_iter(row_iter): v[pivot] = 1 complement_basis.append(vector(R, v)) # reduce the hyperplane equations - echelon_pivots = [] # the column indices where N has 1's from the echelonization + echelon_pivots = [] # the column indices where N has 1s from the echelonization for pivot, row in echelon_col_iter(complement_basis): assert row[pivot] == 1 echelon_pivots.append(pivot) @@ -1828,9 +1788,7 @@ def face_vector(self): r""" Return the face vector. - OUTPUT: - - A vector of integers. + OUTPUT: a vector of integers The `d`-th entry is the number of faces of dimension `d`. A *face* is the intersection of a region with a hyperplane of @@ -1981,7 +1939,7 @@ def _make_region(self, hyperplanes): INPUT: - - ``hyperplanes`` -- a list/tuple/iterable of hyperplanes + - ``hyperplanes`` -- list/tuple/iterable of hyperplanes OUTPUT: @@ -2016,9 +1974,7 @@ def regions(self): The base field must have characteristic zero. - OUTPUT: - - A tuple containing the regions as polyhedra. + OUTPUT: a tuple containing the regions as polyhedra The regions are the connected components of the complement of the union of the hyperplanes as a subset of `\RR^n`. @@ -2191,15 +2147,13 @@ def poset_of_regions(self, B=None, numbered_labels=True): INPUT: - ``B`` -- a region (optional); if ``None``, then - an arbitrary region is chosen as the base region. + an arbitrary region is chosen as the base region - - ``numbered_labels`` -- bool (default: ``True``); if ``True``, + - ``numbered_labels`` -- boolean (default: ``True``); if ``True``, then the elements of the poset are numbered. Else they are labelled with the regions themselves. - OUTPUT: - - A Poset object containing the poset of regions. + OUTPUT: a Poset object containing the poset of regions EXAMPLES:: @@ -2552,7 +2506,7 @@ def face_product(self, F, G, normalize=True): - ``F``, ``G`` -- two faces of ``self`` (as polyhedra) - - ``normalize`` -- Boolean (default: ``True``); if ``True``, then + - ``normalize`` -- boolean (default: ``True``); if ``True``, then this method returns the precise instance of `FG` in the list returned by ``self.closed_faces()``, rather than creating a new instance @@ -2755,7 +2709,7 @@ def region_containing_point(self, p): OUTPUT: - A polyhedron. A :class:`ValueError` is raised if the point is not + A polyhedron. A :exc:`ValueError` is raised if the point is not interior to a region, that is, sits on a hyperplane. EXAMPLES:: @@ -3075,10 +3029,8 @@ def is_separating_hyperplane(self, region1, region2, hyperplane): - ``hyperplane`` -- a hyperplane - OUTPUT: - - A boolean. Whether the hyperplane ``hyperplane`` separate the given - regions. + OUTPUT: boolean; whether the hyperplane ``hyperplane`` separate the + given regions EXAMPLES:: @@ -3119,9 +3071,7 @@ def distance_between_regions(self, region1, region2): - ``region1``, ``region2`` -- regions of the arrangement or representative points of regions - OUTPUT: - - An integer. The number of hyperplanes separating the two regions. + OUTPUT: integer; the number of hyperplanes separating the two regions EXAMPLES:: @@ -3180,11 +3130,9 @@ def varchenko_matrix(self, names='h'): INPUT: - ``names`` -- string or list/tuple/iterable of strings. The - variable names for the polynomial ring `S`. - - OUTPUT: + variable names for the polynomial ring `S` - The Varchenko matrix. + OUTPUT: the Varchenko matrix EXAMPLES:: @@ -3463,7 +3411,7 @@ def derivation_module_free_chain(self): return construct_free_chain(self) @cached_method(key=lambda self, a: None) - def is_free(self, algorithm="singular"): + def is_free(self, algorithm='singular'): r""" Return if ``self`` is free. @@ -3473,11 +3421,11 @@ def is_free(self, algorithm="singular"): INPUT: - - ``algorithm`` -- (default: ``"singular"``) can be one of + - ``algorithm`` -- (default: ``'singular'``) can be one of the following: - * ``"singular"`` -- use Singular's minimal free resolution - * ``"BC"`` -- use the algorithm given by Barakat and Cuntz + * ``'singular'`` -- use Singular's minimal free resolution + * ``'BC'`` -- use the algorithm given by Barakat and Cuntz in [BC2012]_ (much slower than using Singular) ALGORITHM: @@ -3517,8 +3465,8 @@ def is_free(self, algorithm="singular"): sage: W = WeylGroup(['B', 3], prefix='s') # needs sage.combinat sage.groups sage: for x in W: # long time # needs sage.combinat sage.groups ....: A = x.inversion_arrangement() - ....: assert (A.is_free(algorithm="BC") - ....: == A.is_free(algorithm="singular")) + ....: assert (A.is_free(algorithm='BC') + ....: == A.is_free(algorithm='singular')) """ if not self.is_central(): raise NotImplementedError("only implemented for central arrangements") @@ -3531,7 +3479,7 @@ def is_free(self, algorithm="singular"): else: raise ValueError("invalid algorithm") - def derivation_module_basis(self, algorithm="singular"): + def derivation_module_basis(self, algorithm='singular'): """ Return a basis for the derivation module of ``self`` if one exists, otherwise return ``None``. @@ -3542,11 +3490,11 @@ def derivation_module_basis(self, algorithm="singular"): INPUT: - - ``algorithm`` -- (default: ``"singular"``) can be one of + - ``algorithm`` -- (default: ``'singular'``) can be one of the following: - * ``"singular"`` -- use Singular's minimal free resolution - * ``"BC"`` -- use the algorithm given by Barakat and Cuntz + * ``'singular'`` -- use Singular's minimal free resolution + * ``'BC'`` -- use the algorithm given by Barakat and Cuntz in [BC2012]_ (much slower than using Singular) OUTPUT: @@ -3589,8 +3537,8 @@ def derivation_module_basis(self, algorithm="singular"): ....: return sorted([max(x.degree() for x in b) for b in B]) sage: for x in W: # long time # needs sage.combinat sage.groups ....: A = x.inversion_arrangement() - ....: B = A.derivation_module_basis(algorithm="singular") - ....: Bp = A.derivation_module_basis(algorithm="BC") + ....: B = A.derivation_module_basis(algorithm='singular') + ....: Bp = A.derivation_module_basis(algorithm='BC') ....: if B is None: ....: assert Bp is None ....: else: @@ -3691,9 +3639,7 @@ def base_ring(self): """ Return the base ring. - OUTPUT: - - The base ring of the hyperplane arrangement. + OUTPUT: the base ring of the hyperplane arrangement EXAMPLES:: @@ -3709,7 +3655,7 @@ def change_ring(self, base_ring): INPUT: - - ``base_ring`` -- a ring; the new base ring. + - ``base_ring`` -- a ring; the new base ring OUTPUT: @@ -3754,9 +3700,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3784,7 +3728,7 @@ def _element_constructor_(self, *args, **kwds): whether or not there is a warning shown - ``check`` -- boolean (default: ``True``); whether to - perform argument checking. + perform argument checking EXAMPLES:: @@ -3872,9 +3816,7 @@ def ngens(self): """ Return the number of linear variables. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -3891,9 +3833,7 @@ def gens(self) -> tuple: """ Return the coordinate hyperplanes. - OUTPUT: - - A tuple of linear expressions, one for each linear variable. + OUTPUT: a tuple of linear expressions, one for each linear variable EXAMPLES:: @@ -3913,9 +3853,7 @@ def gen(self, i): - ``i`` -- integer - OUTPUT: - - A linear expression. + OUTPUT: a linear expression EXAMPLES:: diff --git a/src/sage/geometry/hyperplane_arrangement/hyperplane.py b/src/sage/geometry/hyperplane_arrangement/hyperplane.py index b7f493d9acb..04de307442d 100644 --- a/src/sage/geometry/hyperplane_arrangement/hyperplane.py +++ b/src/sage/geometry/hyperplane_arrangement/hyperplane.py @@ -166,9 +166,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -182,9 +180,7 @@ def _latex_(self): r""" Return a LaTeX representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -208,9 +204,7 @@ def normal(self): """ Return the normal vector. - OUTPUT: - - A vector over the base ring. + OUTPUT: a vector over the base ring EXAMPLES:: @@ -228,9 +222,7 @@ def _normal_pivot(self): """ Return the index of the largest entry of the normal vector. - OUTPUT: - - An integer. The index of the largest entry. + OUTPUT: integer; the index of the largest entry EXAMPLES:: @@ -265,9 +257,7 @@ def __contains__(self, q): - ``q`` -- point (as a vector, list, or tuple) - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -287,9 +277,7 @@ def polyhedron(self, **kwds): """ Return the hyperplane as a polyhedron. - OUTPUT: - - A :func:`~sage.geometry.polyhedron.constructor.Polyhedron` instance. + OUTPUT: a :func:`~sage.geometry.polyhedron.constructor.Polyhedron` instance EXAMPLES:: @@ -426,9 +414,7 @@ def dimension(self): r""" The dimension of the hyperplane. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -448,9 +434,7 @@ def intersection(self, other): - ``other`` -- a hyperplane, a polyhedron, or something that defines a polyhedron - OUTPUT: - - A polyhedron. + OUTPUT: a polyhedron EXAMPLES:: @@ -484,7 +468,7 @@ def orthogonal_projection(self, point): A vector in the ambient vector space that lies on the hyperplane. - In finite characteristic, a :class:`ValueError` is raised if the + In finite characteristic, a :exc:`ValueError` is raised if the the norm of the hyperplane normal is zero. EXAMPLES:: @@ -634,9 +618,7 @@ def plot(self, **kwds): """ Plot the hyperplane. - OUTPUT: - - A graphics object. + OUTPUT: a graphics object EXAMPLES:: @@ -716,9 +698,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -736,9 +716,7 @@ def dimension(self): """ Return the ambient space dimension. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -760,9 +738,7 @@ def change_ring(self, base_ring): - ``base_ring`` -- a ring; the new base ring - OUTPUT: - - A new :class:`AmbientVectorSpace`. + OUTPUT: a new :class:`AmbientVectorSpace` EXAMPLES:: diff --git a/src/sage/geometry/hyperplane_arrangement/library.py b/src/sage/geometry/hyperplane_arrangement/library.py index 085cdd32e21..9e2ca3336f6 100644 --- a/src/sage/geometry/hyperplane_arrangement/library.py +++ b/src/sage/geometry/hyperplane_arrangement/library.py @@ -241,7 +241,7 @@ def Coxeter(self, data, K=QQ, names=None): - ``data`` -- either an integer or a Cartan type (or coercible into; see "CartanType") - - ``K`` -- field (default:``QQ``) + - ``K`` -- field (default: ``QQ``) - ``names`` -- tuple of strings or ``None`` (default); the variable names for the ambient space @@ -367,9 +367,7 @@ def G_Shi(self, G, K=QQ, names=None): - ``names`` -- tuple of strings or ``None`` (default); the variable names for the ambient space - OUTPUT: - - The Shi hyperplane arrangement of the given graph ``G``. + OUTPUT: the Shi hyperplane arrangement of the given graph ``G`` EXAMPLES:: @@ -456,7 +454,7 @@ def Ish(self, n, K=QQ, names=None): - ``n`` -- integer - - ``K`` -- field (default:``QQ``) + - ``K`` -- field (default: ``QQ``) - ``names`` -- tuple of strings or ``None`` (default); the variable names for the ambient space @@ -515,13 +513,11 @@ def IshB(self, n, K=QQ, names=None): INPUT: - ``n`` -- integer - - ``K`` -- field (default:``QQ``) + - ``K`` -- field (default: ``QQ``) - ``names`` -- tuple of strings or ``None`` (default); the variable names for the ambient space - OUTPUT: - - The type `B` Ish arrangement, which is the set of `2n^2` hyperplanes + OUTPUT: the type `B` Ish arrangement, which is the set of `2n^2` hyperplanes .. MATH:: @@ -691,7 +687,7 @@ def Shi(self, data, K=QQ, names=None, m=1): - ``data`` -- either an integer or a Cartan type (or coercible into; see "CartanType") - - ``K`` -- field (default:``QQ``) + - ``K`` -- field (default: ``QQ``) - ``names`` -- tuple of strings or ``None`` (default); the variable names for the ambient space diff --git a/src/sage/geometry/hyperplane_arrangement/ordered_arrangement.py b/src/sage/geometry/hyperplane_arrangement/ordered_arrangement.py index bb16768e13b..c0024f4c982 100644 --- a/src/sage/geometry/hyperplane_arrangement/ordered_arrangement.py +++ b/src/sage/geometry/hyperplane_arrangement/ordered_arrangement.py @@ -115,9 +115,9 @@ def __init__(self, parent, hyperplanes, check=True, backend=None): - ``parent`` -- the parent :class:`OrderedHyperplaneArrangements` - - ``hyperplanes`` -- a tuple of hyperplanes + - ``hyperplanes`` -- tuple of hyperplanes - - ``check`` -- boolean (default ``True``); whether + - ``check`` -- boolean (default: ``True``); whether to check input - ``backend`` -- string (default: ``None``); the backend to @@ -142,7 +142,7 @@ def hyperplane_section(self, proj=True): INPUT: - - ``proj`` -- (default: ``True``); if the + - ``proj`` -- (default: ``True``) if the ambient space is affine or projective OUTPUT: @@ -224,7 +224,7 @@ def hyperplane_section(self, proj=True): mat_rows = mat.rows()[:-1] H1b = A1(mat_rows) return H1b - P = self.intersection_poset(element_label="subspace") + P = self.intersection_poset(element_label='subspace') center = P.maximal_elements()[0].linear_part() n1 = center.dimension() U = [] @@ -250,9 +250,7 @@ def affine_fundamental_group(self): hyperplane arrangement in `\CC^n` whose equations have coefficients in a subfield of `\QQbar`. - OUTPUT: - - A finitely presented fundamental group. + OUTPUT: a finitely presented fundamental group .. NOTE:: @@ -340,9 +338,7 @@ def affine_meridians(self): r""" Return the meridians of each hyperplane (including the one at infinity). - OUTPUT: - - A dictionary + OUTPUT: a dictionary .. NOTE:: @@ -479,9 +475,7 @@ def projective_meridians(self): r""" Return the meridian of each hyperplane. - OUTPUT: - - A dictionary + OUTPUT: a dictionary .. NOTE:: @@ -558,7 +552,7 @@ def _element_constructor_(self, *args, **kwds): preserve signs of hyperplane equations - ``check`` -- boolean (default: ``True``); whether to - perform argument checking. + perform argument checking EXAMPLES:: @@ -637,9 +631,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: diff --git a/src/sage/geometry/hyperplane_arrangement/plot.py b/src/sage/geometry/hyperplane_arrangement/plot.py index c7b413114e6..190bef9982f 100644 --- a/src/sage/geometry/hyperplane_arrangement/plot.py +++ b/src/sage/geometry/hyperplane_arrangement/plot.py @@ -6,21 +6,21 @@ Beside the usual plot options (enter ``plot?``), the plot command for hyperplane arrangements includes the following: -- ``hyperplane_colors`` -- Color or list of colors, one for each - hyperplane (default: equally spread range of hues). +- ``hyperplane_colors`` -- color or list of colors, one for each + hyperplane (default: equally spread range of hues) -- ``hyperplane_labels`` -- Boolean, ``'short'``, ``'long'`` (default: +- ``hyperplane_labels`` -- boolean, ``'short'``, ``'long'`` (default: ``False``). If ``False``, no labels are shown; if 'short' or 'long', the hyperplanes are given short or long labels, respectively. If ``True``, the hyperplanes are given long labels. -- ``label_colors`` -- Color or list of colors, one for each hyperplane - (default: black). +- ``label_colors`` -- color or list of colors, one for each hyperplane + (default: black) -- ``label_fontsize`` -- Size for hyperplane_label font (default: - ``14``). This does not work for 3d plots. +- ``label_fontsize`` -- size for hyperplane_label font (default: + ``14``); this does not work for 3d plots -- ``label_offsets`` -- Amount be which labels are offset from +- ``label_offsets`` -- amount be which labels are offset from h.point() for each hyperplane h. The format is different for each dimension: if the hyperplanes have dimension 0, the offset can be a single number or a list of numbers, one for each hyperplane; if the @@ -30,20 +30,20 @@ 3-tuples, one for each hyperplane. (Defaults: 0-dim: ``0.1``, 1-dim: ``(0,1)``, 2-dim: ``(0,0,0.2)``). -- ``hyperplane_legend`` -- Boolean, ``'short'``, ``'long'`` (default: +- ``hyperplane_legend`` -- boolean, ``'short'``, ``'long'`` (default: ``'long'``; in 3-d: ``False``). If ``False``, no legend is shown; if ``True``, ``'short'``, or ``'long'``, the legend is shown with the default, long, or short labeling, respectively. (For arrangements of lines or planes, only.) -- ``hyperplane_opacities`` -- A number or list of numbers, one for each - hyperplane, between 0 and 1. Only applies to 3d plots. +- ``hyperplane_opacities`` -- a number or list of numbers, one for each + hyperplane, between 0 and 1; only applies to 3d plots -- ``point_sizes`` -- Number or list of numbers, one for each hyperplane +- ``point_sizes`` -- number or list of numbers, one for each hyperplane giving the sizes of points in a zero-dimensional arrangement - (default: ``50``). + (default: ``50``) -- ``ranges`` -- Range for the parameters or a list of ranges of +- ``ranges`` -- range for the parameters or a list of ranges of parameters, one for each hyperplane, for the parametric plots of the hyperplanes. If a single positive number `r` is given for ``ranges``, then all parameters run from -r to r. Otherwise, for a @@ -136,11 +136,9 @@ def plot(hyperplane_arrangement, **kwds): - ``hyperplane_arrangement`` -- the hyperplane arrangement to plot - ``**kwds`` -- plot options: see - :mod:`sage.geometry.hyperplane_arrangement.plot`. + :mod:`sage.geometry.hyperplane_arrangement.plot` - OUTPUT: - - A graphics object of the plot. + OUTPUT: a graphics object of the plot EXAMPLES:: @@ -292,33 +290,31 @@ def plot_hyperplane(hyperplane, **kwds): - ``**kwds`` -- plot options: see below - OUTPUT: - - A graphics object of the plot. + OUTPUT: a graphics object of the plot .. RUBRIC:: Plot Options Beside the usual plot options (enter ``plot?``), the plot command for hyperplanes includes the following: - - ``hyperplane_label`` -- Boolean value or string (default: ``True``). - If ``True``, the hyperplane is labeled with its equation, if a + - ``hyperplane_label`` -- boolean value or string (default: ``True``); + if ``True``, the hyperplane is labeled with its equation, if a string, it is labeled by that string, otherwise it is not - labeled. + labeled - - ``label_color`` -- (Default: ``'black'``) Color for hyperplane_label. + - ``label_color`` -- (default: ``'black'``) color for hyperplane_label - - ``label_fontsize`` -- Size for ``hyperplane_label`` font (default: 14) - (does not work in 3d, yet). + - ``label_fontsize`` -- size for ``hyperplane_label`` font (default: 14) + (does not work in 3d, yet) - - ``label_offset`` -- (Default: 0-dim: 0.1, 1-dim: (0,1), - 2-dim: (0,0,0.2)) Amount by which label is offset from - ``hyperplane.point()``. + - ``label_offset`` -- (default: 0-dim: 0.1, 1-dim: (0,1), + 2-dim: (0,0,0.2)); amount by which label is offset from + ``hyperplane.point()`` - - ``point_size`` -- (Default: 50) Size of points in a zero-dimensional - arrangement or of an arrangement over a finite field. + - ``point_size`` -- (default: 50) size of points in a zero-dimensional + arrangement or of an arrangement over a finite field - - ``ranges`` -- Range for the parameters for the parametric plot of the + - ``ranges`` -- range for the parameters for the parametric plot of the hyperplane. If a single positive number ``r`` is given for the value of ``ranges``, then the ranges for all parameters are set to `[-r, r]`. Otherwise, for a line in the plane, ``ranges`` has the @@ -482,9 +478,7 @@ def legend_3d(hyperplane_arrangement, hyperplane_colors, length): - ``length`` -- either ``'short'`` or ``'long'`` - OUTPUT: - - - A graphics object. + OUTPUT: a graphics object EXAMPLES:: diff --git a/src/sage/geometry/integral_points.pxi b/src/sage/geometry/integral_points.pxi index 327855b6a57..a67535b450b 100644 --- a/src/sage/geometry/integral_points.pxi +++ b/src/sage/geometry/integral_points.pxi @@ -119,7 +119,7 @@ cpdef tuple parallelotope_points(spanning_points, lattice): sage: parallelotope_points(c.rays(), c.lattice()) (N(0, 0), N(1, 1)) - A :class:`ValueError` is raised if the ``spanning_points`` are not + A :exc:`ValueError` is raised if the ``spanning_points`` are not linearly independent:: sage: rays = list(map(ToricLattice(2), [(1,1)]*2)) @@ -151,11 +151,9 @@ cpdef tuple ray_matrix_normal_form(R): INPUT: - ``R`` -- `\ZZ`-matrix whose columns are the rays spanning the - parallelotope. + parallelotope - OUTPUT: - - A tuple containing ``e``, ``d``, and ``VDinv``. + OUTPUT: a tuple containing ``e``, ``d``, and ``VDinv`` EXAMPLES:: @@ -186,7 +184,7 @@ cpdef tuple loop_over_parallelotope_points(e, d, MatrixClass VDinv, See :meth:`parallelotope_points` for ``e``, ``d``, ``VDinv``, ``R``, ``lattice``. - - ``A``, ``b``: Either both ``None`` or a vector and number. If + - ``A``, ``b`` -- either both ``None`` or a vector and number. If present, only the parallelotope points satisfying `A x \leq b` are returned. @@ -352,23 +350,23 @@ cpdef rectangular_box_points(list box_min, list box_max, INPUT: - - ``box_min`` -- A list of integers. The minimal value for each - coordinate of the rectangular bounding box. + - ``box_min`` -- list of integers; the minimal value for each + coordinate of the rectangular bounding box - - ``box_max`` -- A list of integers. The maximal value for each - coordinate of the rectangular bounding box. + - ``box_max`` -- list of integers; the maximal value for each + coordinate of the rectangular bounding box - - ``polyhedron`` -- A + - ``polyhedron`` -- a :class:`~sage.geometry.polyhedron.base.Polyhedron_base`, a PPL - :class:`~ppl.polyhedron.C_Polyhedron`, or ``None`` (default). + :class:`~ppl.polyhedron.C_Polyhedron`, or ``None`` (default) - - ``count_only`` -- Boolean (default: ``False``). Whether to + - ``count_only`` -- boolean (default: ``False``); whether to return only the total number of vertices, and not their coordinates. Enabling this option speeds up the enumeration. Cannot be combined with the ``return_saturated`` option. - - ``return_saturated`` -- Boolean (default: ``False``. Whether to + - ``return_saturated`` -- boolean (default: ``False``); whether to also return which inequalities are saturated for each point of the polyhedron. Enabling this slows down the enumeration. Cannot be combined with the ``count_only`` option. @@ -595,20 +593,18 @@ cdef loop_over_rectangular_box_points(list box_min, list box_max, INPUT: - - ``box_min``, ``box_max`` -- the bounding box. + - ``box_min``, ``box_max`` -- the bounding box - ``inequalities`` -- a :class:`InequalityCollection` containing - the inequalities defining the polyhedron. + the inequalities defining the polyhedron - - ``d`` -- the ambient space dimension. + - ``d`` -- the ambient space dimension - ``count_only`` -- whether to only return the total number of - lattice points. + lattice points - OUTPUT: - - The integral points in the bounding box satisfying all - inequalities. + OUTPUT: the integral points in the bounding box satisfying all + inequalities """ cdef int inc cdef Integer i_min, i_max @@ -729,9 +725,7 @@ cdef class Inequality_generic: - ``b`` -- element - OUTPUT: - - Inequality `A x + b \geq 0`. + OUTPUT: inequality `A x + b \geq 0` EXAMPLES:: @@ -749,7 +743,7 @@ cdef class Inequality_generic: def __cinit__(self, list A, b, int index=-1): """ - The Cython constructor + The Cython constructor. INPUT: @@ -771,9 +765,7 @@ cdef class Inequality_generic: """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -811,9 +803,7 @@ cdef class Inequality_generic: r""" Test the inequality, using the cached value from :meth:`prepare_inner_loop` - OUTPUT: - - Boolean. Whether the inequality is not satisfied. + OUTPUT: boolean; whether the inequality is not satisfied """ return inner_loop_variable * self.coeff + self.cache < 0 @@ -823,7 +813,7 @@ cdef class Inequality_generic: OUTPUT: - Boolean. Given the inequality `Ax + b \geq 0`, this method + boolean. Given the inequality `Ax + b \geq 0`, this method returns whether the equality `Ax + b = 0` is satisfied. """ return inner_loop_variable * self.coeff + self.cache == 0 @@ -849,9 +839,9 @@ cdef class Inequality_int: OUTPUT: - Inequality `A x + b \geq 0`. A :class:`OverflowError` is raised if a + Inequality `A x + b \geq 0`. A :exc:`OverflowError` is raised if a machine integer is not long enough to hold the results. A - :class:`ValueError` is raised if some of the input is not integral. + :exc:`ValueError` is raised if some of the input is not integral. EXAMPLES:: @@ -887,7 +877,6 @@ cdef class Inequality_int: Traceback (most recent call last): ... OverflowError: ... - """ cdef int A[INEQ_INT_MAX_DIM] cdef int b @@ -908,7 +897,7 @@ cdef class Inequality_int: def __cinit__(self, list A, b, list max_abs_coordinates, int index=-1): """ - The Cython constructor + The Cython constructor. See :class:`Inequality_int` for input. @@ -937,9 +926,7 @@ cdef class Inequality_int: """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -988,13 +975,13 @@ cdef class InequalityCollection: INPUT: - - ``polyhedron`` -- a polyhedron defining the inequalities. + - ``polyhedron`` -- a polyhedron defining the inequalities - - ``permutation`` -- list; a 0-based permutation of the coordinates. - Will be used to permute the coordinates of the inequality. + - ``permutation`` -- list; a 0-based permutation of the coordinates + Will be used to permute the coordinates of the inequality - ``box_min``, ``box_max`` -- the (not permuted) minimal and maximal - coordinates of the bounding box. Used for bounds checking. + coordinates of the bounding box; used for bounds checking EXAMPLES:: @@ -1031,9 +1018,7 @@ cdef class InequalityCollection: r""" Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1087,7 +1072,7 @@ cdef class InequalityCollection: def __cinit__(self, polyhedron, list permutation, box_min, box_max): """ - The Cython constructor + The Cython constructor. See the class documentation for the description of the arguments. @@ -1121,7 +1106,7 @@ cdef class InequalityCollection: cdef _cinit_from_PPL(self, list max_abs_coordinates, list permutation, polyhedron): """ - Initialize the inequalities from a PPL C_Polyhedron + Initialize the inequalities from a PPL C_Polyhedron. See __cinit__ for a description of the arguments. @@ -1170,7 +1155,7 @@ cdef class InequalityCollection: cdef _cinit_from_Polyhedron(self, list max_abs_coordinates, list permutation, polyhedron): """ - Initialize the inequalities from a Sage Polyhedron + Initialize the inequalities from a Sage Polyhedron. See __cinit__ for a description of the arguments. @@ -1238,7 +1223,7 @@ cdef class InequalityCollection: INPUT: - ``p`` -- the point coordinates. Only ``p[2:]`` coordinates - are potentially used by this method. + are potentially used by this method EXAMPLES:: @@ -1277,7 +1262,7 @@ cdef class InequalityCollection: INPUT: - ``p`` -- the coordinates of the point to loop over. Only the - ``p[1:]`` entries are used. + ``p[1:]`` entries are used EXAMPLES:: @@ -1303,8 +1288,8 @@ cdef class InequalityCollection: INPUT: - - ``i`` -- Integer. The :class:`Inequality_int` to swap to the - beginning of the list of integral inequalities. + - ``i`` -- integer; the :class:`Inequality_int` to swap to the + beginning of the list of integral inequalities EXAMPLES:: @@ -1340,12 +1325,10 @@ cdef class InequalityCollection: INPUT: - - ``inner_loop_variable`` -- Integer. the 0-th coordinate of - the lattice point. - - OUTPUT: + - ``inner_loop_variable`` -- integer; the 0th coordinate of + the lattice point - Boolean. Whether the lattice point is in the polyhedron. + OUTPUT: boolean; whether the lattice point is in the polyhedron EXAMPLES:: @@ -1379,8 +1362,8 @@ cdef class InequalityCollection: INPUT: - - ``inner_loop_variable`` -- Integer. the 0-th coordinate of - the lattice point. + - ``inner_loop_variable`` -- integer; the 0th coordinate of + the lattice point OUTPUT: diff --git a/src/sage/geometry/lattice_polytope.py b/src/sage/geometry/lattice_polytope.py index 0f83da4c96b..67f6e74ea89 100644 --- a/src/sage/geometry/lattice_polytope.py +++ b/src/sage/geometry/lattice_polytope.py @@ -29,7 +29,7 @@ included standard with Sage. PALP is described in the paper :arxiv:`math.SC/0204356`. Its distribution -also contains the application nef.x, which was created by Erwin +also contains the application ``nef.x``, which was created by Erwin Riegler and computes nef-partitions and Hodge data for toric complete intersections. @@ -41,15 +41,15 @@ Robert Bradshaw helped Andrey Novoseltsev to realize plot3d function. -.. note:: +.. NOTE:: IMPORTANT: PALP requires some parameters to be determined during compilation time, i.e., the maximum dimension of polytopes, the maximum number of points, etc. These limitations may lead to errors during calls to different functions of these module. Currently, a - ValueError exception will be raised if the output of poly.x or - nef.x is empty or contains the exclamation mark. The error message - will contain the exact command that caused an error, the + :exc:`ValueError` exception will be raised if the output of ``poly.x`` + or ``nef.x`` is empty or contains the exclamation mark. The error + message will contain the exact command that caused an error, the description and vertices of the polytope, and the obtained output. Data obtained from PALP and some other data is cached and most @@ -135,9 +135,9 @@ from sage.features import PythonModule from sage.features.palp import PalpExecutable lazy_import('ppl', ['C_Polyhedron', 'Generator_System', 'Linear_Expression'], - feature=PythonModule("ppl", spkg="pplpy", type="standard")) + feature=PythonModule("ppl", spkg='pplpy', type='standard')) lazy_import('ppl', 'point', as_='PPL_point', - feature=PythonModule("ppl", spkg="pplpy", type="standard")) + feature=PythonModule("ppl", spkg='pplpy', type='standard')) from sage.matrix.constructor import matrix from sage.structure.element import Matrix @@ -220,23 +220,20 @@ def LatticePolytope(data, compute_vertices=True, n=0, lattice=None): :func:`~sage.geometry.point_collection.read_palp_point_collection` for the file format; - - ``compute_vertices`` -- boolean (default: ``True``). If ``True``, the - convex hull of the given points will be computed for - determining vertices. Otherwise, the given points must be - vertices; + - ``compute_vertices`` -- boolean (default: ``True``); if ``True``, the + convex hull of the given points will be computed for determining + vertices. Otherwise, the given points must be vertices. - - ``n`` -- an integer (default: 0) if ``data`` is a name of a file, - that contains data blocks for several polytopes, the ``n``-th block - will be used; + - ``n`` -- integer (default: 0); if ``data`` is a name of a file, + that contains data blocks for several polytopes, the ``n``-th block + will be used - ``lattice`` -- the ambient lattice of the polytope. If not given, a suitable lattice will be determined automatically, most likely the :class:`toric lattice ` `M` of the appropriate dimension. - OUTPUT: - - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` EXAMPLES:: @@ -428,9 +425,11 @@ def ReflexivePolytopes(dim): future use, so repetitive calls will return the same object in memory. - :param dim: dimension of required reflexive polytopes - :type dim: 2 or 3 - :rtype: list of lattice polytopes + INPUT: + + - ``dim`` -- integer (2 or 3); dimension of required reflexive polytopes + + OUTPUT: list of lattice polytopes EXAMPLES: @@ -470,7 +469,7 @@ def is_LatticePolytope(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: @@ -512,24 +511,22 @@ class LatticePolytopeClass(ConvexSet_compact, Hashable, sage.geometry.abc.Lattic The input can be either: - - ``points`` -- :class:`~sage.geometry.point_collection.PointCollection`; + - ``points`` -- :class:`~sage.geometry.point_collection.PointCollection` - - ``compute_vertices`` -- boolean. + - ``compute_vertices`` -- boolean or (these parameters must be given as keywords): - ``ambient`` -- ambient structure, this polytope *must be a face of* - ``ambient``; + ``ambient`` - ``ambient_vertex_indices`` -- increasing list or tuple of integers, - indices of vertices of ``ambient`` generating this polytope; + indices of vertices of ``ambient`` generating this polytope - ``ambient_facet_indices`` -- increasing list or tuple of integers, - indices of facets of ``ambient`` generating this polytope. + indices of facets of ``ambient`` generating this polytope - OUTPUT: - - - lattice polytope. + OUTPUT: lattice polytope .. NOTE:: @@ -550,7 +547,6 @@ def __init__(self, points=None, compute_vertices=None, sage: LatticePolytope([(1,2,3), (4,5,6)]) # indirect test 1-d lattice polytope in 3-d lattice M sage: TestSuite(_).run() - """ if ambient is None: self._ambient = self @@ -621,7 +617,7 @@ def __richcmp__(self, other, op): INPUT: - - ``other`` -- anything. + - ``other`` -- anything .. NOTE:: @@ -685,9 +681,7 @@ def __hash__(self): r""" Return the hash of ``self``. - OUTPUT: - - - an integer. + OUTPUT: integer TESTS:: @@ -722,7 +716,7 @@ def __reduce__(self): def __setstate__(self, state): r""" - Restores the state of pickled polytope. + Restore the state of pickled polytope. TESTS:: @@ -950,11 +944,9 @@ def _embed(self, data): def _latex_(self): r""" - Return the latex representation of self. - - OUTPUT: + Return the latex representation of ``self``. - - string + OUTPUT: string EXAMPLES: @@ -981,7 +973,7 @@ def _palp(self, command, reduce_dimension=False): Returns the output of ``command`` as a string. - .. note:: + .. NOTE:: PALP cannot be called for polytopes that do not span the ambient space. If you specify ``reduce_dimension=True`` argument, PALP will be @@ -1040,9 +1032,7 @@ def _PPL(self): r""" Return the Parma Polyhedra Library (PPL) representation of ``self``. - OUTPUT: - - - :class:`~ppl.polyhedron.C_Polyhedron` + OUTPUT: :class:`~ppl.polyhedron.C_Polyhedron` EXAMPLES:: @@ -1228,11 +1218,9 @@ def _read_nef_partitions(self, data): INPUT: - - ``data`` -- a string or a file. - - OUTPUT: + - ``data`` -- string or file - - none. + OUTPUT: none TESTS:: @@ -1313,9 +1301,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - a string. + OUTPUT: string TESTS:: @@ -1352,11 +1338,9 @@ def _sort_faces(self, faces): INPUT: - ``faces`` -- iterable of :class:`lattice polytopes - `. - - OUTPUT: + ` - - :class:`tuple` of :class:`lattice polytopes `. + OUTPUT: :class:`tuple` of :class:`lattice polytopes ` TESTS:: @@ -1400,9 +1384,7 @@ def adjacent(self): * `F_1` and `F_2` are facets of some face of dimension `d+1`, unless `d` is the dimension of the ambient structure. - OUTPUT: - - - :class:`tuple` of :class:`lattice polytopes `. + OUTPUT: :class:`tuple` of :class:`lattice polytopes ` EXAMPLES:: @@ -1428,7 +1410,7 @@ def affine_transform(self, a=1, b=0): r""" Return a*P+b, where P is this lattice polytope. - .. note:: + .. NOTE:: #. While ``a`` and ``b`` may be rational, the final result must be a lattice polytope, i.e. all vertices must be integral. @@ -1521,9 +1503,7 @@ def ambient(self): r""" Return the ambient structure of ``self``. - OUTPUT: - - - lattice polytope containing ``self`` as a face. + OUTPUT: lattice polytope containing ``self`` as a face EXAMPLES:: @@ -1548,9 +1528,7 @@ def ambient_facet_indices(self): r""" Return indices of facets of the ambient polytope containing ``self``. - OUTPUT: - - - increasing :class:`tuple` of integers. + OUTPUT: increasing :class:`tuple` of integers EXAMPLES: @@ -1642,9 +1620,7 @@ def ambient_vertex_indices(self): r""" Return indices of vertices of the ambient structure generating ``self``. - OUTPUT: - - - increasing :class:`tuple` of integers. + OUTPUT: increasing :class:`tuple` of integers EXAMPLES:: @@ -1662,9 +1638,7 @@ def boundary_point_indices(self): r""" Return indices of (relative) boundary lattice points of this polytope. - OUTPUT: - - - increasing :class:`tuple` of integers. + OUTPUT: increasing :class:`tuple` of integers EXAMPLES: @@ -1704,9 +1678,7 @@ def boundary_points(self): r""" Return (relative) boundary lattice points of this polytope. - OUTPUT: - - - a :class:`point collection `. + OUTPUT: a :class:`point collection ` EXAMPLES: @@ -1795,9 +1767,9 @@ def distances(self, point=None): Return the matrix of distances for this polytope or distances for the given point. - The matrix of distances m gives distances m[i,j] between the i-th - facet (which is also the i-th vertex of the polar polytope in the - reflexive case) and j-th point of this polytope. + The matrix of distances m gives distances m[i,j] between the `i`-th + facet (which is also the `i`-th vertex of the polar polytope in the + reflexive case) and `j`-th point of this polytope. If point is specified, integral distances from the point to all facets of this polytope will be computed. @@ -1865,9 +1837,7 @@ def dual(self): This duality extends the correspondence between vertices and facets. - OUTPUT: - - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` EXAMPLES:: @@ -1917,9 +1887,7 @@ def edges(self): r""" Return edges (faces of dimension 1) of ``self``. - OUTPUT: - - - :class:`tuple` of :class:`lattice polytopes `. + OUTPUT: :class:`tuple` of :class:`lattice polytopes ` EXAMPLES:: @@ -2106,9 +2074,9 @@ def faces(self, dim=None, codim=None): INPUT: - - ``dim`` -- integer, dimension of the requested faces; + - ``dim`` -- integer; dimension of the requested faces - - ``codim`` -- integer, codimension of the requested faces. + - ``codim`` -- integer; codimension of the requested faces .. NOTE:: @@ -2191,7 +2159,7 @@ def faces(self, dim=None, codim=None): def facet_constant(self, i): r""" - Return the constant in the ``i``-th facet inequality of this polytope. + Return the constant in the `i`-th facet inequality of this polytope. This is equivalent to ``facet_constants()[i]``. @@ -2199,9 +2167,7 @@ def facet_constant(self, i): - ``i`` -- integer; the index of the facet - OUTPUT: - - - integer -- the constant in the ``i``-th facet inequality. + OUTPUT: integer; the constant in the `i`-th facet inequality .. SEEALSO:: @@ -2227,9 +2193,7 @@ def facet_constants(self): Facet inequalities have form `n \cdot x + c \geq 0` where `n` is the inner normal and `c` is a constant. - OUTPUT: - - - an integer vector + OUTPUT: integer vector .. SEEALSO:: @@ -2284,9 +2248,7 @@ def facet_normal(self, i): - ``i`` -- integer; the index of the facet - OUTPUT: - - - a vector + OUTPUT: a vector .. SEEALSO:: @@ -2391,9 +2353,7 @@ def facet_of(self): r""" Return elements of the ambient face lattice having ``self`` as a facet. - OUTPUT: - - - :class:`tuple` of :class:`lattice polytopes `. + OUTPUT: :class:`tuple` of :class:`lattice polytopes ` EXAMPLES:: @@ -2415,9 +2375,7 @@ def facets(self): r""" Return facets (faces of codimension 1) of ``self``. - OUTPUT: - - - :class:`tuple` of :class:`lattice polytopes `. + OUTPUT: :class:`tuple` of :class:`lattice polytopes ` EXAMPLES:: @@ -2493,7 +2451,7 @@ def index(self): 3-dimensional reflexive polytopes. Databases are stored in the directory of the package. - .. note:: + .. NOTE:: The first call to this function for each dimension can take a few seconds while the dictionary of all polytopes is @@ -2557,9 +2515,7 @@ def interior_point_indices(self): r""" Return indices of (relative) interior lattice points of this polytope. - OUTPUT: - - - increasing :class:`tuple` of integers. + OUTPUT: increasing :class:`tuple` of integers EXAMPLES: @@ -2599,9 +2555,7 @@ def interior_points(self): r""" Return (relative) boundary lattice points of this polytope. - OUTPUT: - - - a :class:`point collection `. + OUTPUT: a :class:`point collection ` EXAMPLES: @@ -2624,7 +2578,7 @@ def interior_points(self): @cached_method def is_reflexive(self): r""" - Return True if this polytope is reflexive. + Return ``True`` if this polytope is reflexive. EXAMPLES: The 3-dimensional octahedron is reflexive (and 4319 other 3-polytopes):: @@ -2653,9 +2607,7 @@ def lattice(self): r""" Return the ambient lattice of ``self``. - OUTPUT: - - - a lattice. + OUTPUT: a lattice EXAMPLES:: @@ -2670,9 +2622,7 @@ def lattice_dim(self): An alias is :meth:`ambient_dim`. - OUTPUT: - - - integer. + OUTPUT: integer EXAMPLES:: @@ -2694,7 +2644,7 @@ def ambient_vector_space(self, base_field=None): INPUT: - - ``base_field`` -- (default: the rationals) a field. + - ``base_field`` -- (default: the rationals) a field EXAMPLES:: @@ -2710,9 +2660,7 @@ def linearly_independent_vertices(self): r""" Return a maximal set of linearly independent vertices. - OUTPUT: - - A tuple of vertex indices. + OUTPUT: a tuple of vertex indices EXAMPLES:: @@ -2735,25 +2683,23 @@ def nef_partitions(self, keep_symmetric=False, keep_products=True, INPUT: - - ``keep_symmetric`` -- (default: ``False``) if ``True``, "-s" option + - ``keep_symmetric`` -- boolean (default: ``False``); if ``True``, "-s" option will be passed to ``nef.x`` in order to keep symmetric partitions, - i.e. partitions related by lattice automorphisms preserving ``self``; + i.e. partitions related by lattice automorphisms preserving ``self`` - - ``keep_products`` -- (default: ``True``) if ``True``, "-D" option + - ``keep_products`` -- boolean (default: ``True``); if ``True``, "-D" option will be passed to ``nef.x`` in order to keep product partitions, - with corresponding complete intersections being direct products; + with corresponding complete intersections being direct products - - ``keep_projections`` -- (default: ``True``) if ``True``, "-P" option + - ``keep_projections`` -- boolean (default: ``True``); if ``True``, "-P" option will be passed to ``nef.x`` in order to keep projection partitions, - i.e. partitions with one of the parts consisting of a single vertex; + i.e. partitions with one of the parts consisting of a single vertex - - ``hodge_numbers`` -- (default: ``False``) if ``False``, "-p" option + - ``hodge_numbers`` -- boolean (default: ``False``); if ``False``, "-p" option will be passed to ``nef.x`` in order to skip Hodge numbers - computation, which takes a lot of time. - - OUTPUT: + computation, which takes a lot of time - - a sequence of :class:`nef-partitions `. + OUTPUT: a sequence of :class:`nef-partitions ` Type ``NefPartition?`` for definitions and notation. @@ -2883,17 +2829,15 @@ def nef_partitions(self, keep_symmetric=False, keep_products=True, def nef_x(self, keys): r""" - Run nef.x with given ``keys`` on vertices of this + Run ``nef.x`` with given ``keys`` on vertices of this polytope. INPUT: + - ``keys`` -- string of options passed to ``nef.x``; the + key "-f" is added automatically - - ``keys`` -- a string of options passed to nef.x. The - key "-f" is added automatically. - - - OUTPUT: the output of nef.x as a string. + OUTPUT: the output of ``nef.x`` as a string EXAMPLES: This call is used internally for computing nef-partitions:: @@ -2937,7 +2881,7 @@ def nfacets(self): return len(self.facet_normals()) if self.dim() > 0 else 0 @cached_method - def normal_form(self, algorithm="palp_native", permutation=False): + def normal_form(self, algorithm='palp_native', permutation=False): r""" Return the normal form of vertices of ``self``. @@ -2948,21 +2892,21 @@ def normal_form(self, algorithm="palp_native", permutation=False): The original algorithm was presented in [KS1998]_ and implemented in PALP. A modified version of the PALP algorithm is discussed in - [GK2013]_ and available here as ``"palp_modified"``. + [GK2013]_ and available here as ``'palp_modified'``. INPUT: - - ``algorithm`` -- (default: ``"palp_native"``) The algorithm which is used + - ``algorithm`` -- (default: ``'palp_native'``) the algorithm which is used to compute the normal form. Options are: - * ``"palp"`` -- Run external PALP code, usually the fastest option + * ``'palp'`` -- run external PALP code, usually the fastest option when it works; but reproducible crashes have been observed in dimension 5 and higher. - * ``"palp_native"`` -- The original PALP algorithm implemented + * ``'palp_native'`` -- the original PALP algorithm implemented in sage. Currently competitive with PALP in many cases. - * ``"palp_modified"`` -- A modified version of the PALP + * ``'palp_modified'`` -- a modified version of the PALP algorithm which determines the maximal vertex-facet pairing matrix first and then computes its automorphisms, while the PALP algorithm does both things @@ -3025,7 +2969,7 @@ def normal_form(self, algorithm="palp_native", permutation=False): We can perform the same examples using other algorithms:: sage: o = lattice_polytope.cross_polytope(2) - sage: o.normal_form(algorithm="palp_native") # needs sage.groups + sage: o.normal_form(algorithm='palp_native') # needs sage.groups M( 1, 0), M( 0, 1), M( 0, -1), @@ -3033,7 +2977,7 @@ def normal_form(self, algorithm="palp_native", permutation=False): in 2-d lattice M sage: o = lattice_polytope.cross_polytope(2) - sage: o.normal_form(algorithm="palp_modified") # needs sage.groups + sage: o.normal_form(algorithm='palp_modified') # needs sage.groups M( 1, 0), M( 0, 1), M( 0, -1), @@ -3041,10 +2985,10 @@ def normal_form(self, algorithm="palp_native", permutation=False): in 2-d lattice M The following examples demonstrate the speed of the available algorithms. - In low dimensions, the default algorithm, ``"palp_native"``, is the fastest. - As the dimension increases, ``"palp"`` is relatively faster than ``"palp_native"``. - ``"palp_native"`` is usually much faster than ``"palp_modified"``. - In some cases when the polytope has high symmetry, however, ``"palp_native"`` is slower:: + In low dimensions, the default algorithm, ``'palp_native'``, is the fastest. + As the dimension increases, ``'palp'`` is relatively faster than ``'palp_native'``. + ``'palp_native'`` is usually much faster than ``'palp_modified'``. + In some cases when the polytope has high symmetry, however, ``'palp_native'`` is slower:: sage: # not tested sage: o = lattice_polytope.cross_polytope(2) @@ -3076,11 +3020,11 @@ def normal_form(self, algorithm="palp_native", permutation=False): sage: %timeit o.normal_form.clear_cache(); o.normal_form("palp_modified") 10 loops, best of 3: 0.858 s per loop - Note that the algorithm ``"palp"`` may crash for higher dimensions because of + Note that the algorithm ``'palp'`` may crash for higher dimensions because of the overflow errors as mentioned in :issue:`13525#comment:9`. - Then use ``"palp_native"`` instead, which is usually faster than ``"palp_modified"``. - Below is an example where ``"palp"`` fails and - ``"palp_native"`` is much faster than ``"palp_modified"``:: + Then use ``'palp_native'`` instead, which is usually faster than ``'palp_modified'``. + Below is an example where ``'palp'`` fails and + ``'palp_native'`` is much faster than ``'palp_modified'``:: sage: P = LatticePolytope([[-3, -3, -6, -6, -1], [3, 3, 6, 6, 1], [-3, -3, -6, -6, 1], ....: [-3, -3, -3, -6, 0], [-3, -3, -3, 0, 0], [-3, -3, 0, 0, 0], @@ -3095,13 +3039,13 @@ def normal_form(self, algorithm="palp_native", permutation=False): ....: [0, 0, 3, 6, 1], [0, 0, 6, 6, 0], [0, 3, 0, 0, -1], ....: [3, 0, 3, 0, 0], [0, 3, 0, 0, 1], [0, 3, 3, 0, 0], ....: [0, 3, 3, 6, 0], [0, 3, 6, 6, 0], [3, 0,0, 0, -1], [3, 0, 0, 0, 1]]) - sage: P.normal_form(algorithm="palp") # not tested + sage: P.normal_form(algorithm='palp') # not tested Traceback (most recent call last): ... RuntimeError: Error executing ... for a polytope sequence! Output: b'*** stack smashing detected ***: terminated\nAborted\n' - sage: P.normal_form(algorithm="palp_native") # needs sage.groups + sage: P.normal_form(algorithm='palp_native') # needs sage.groups M( 6, 0, 0, 0, 0), M( -6, 0, 0, 0, 0), M( 0, 1, 0, 0, 0), @@ -3143,7 +3087,7 @@ def normal_form(self, algorithm="palp_native", permutation=False): M( 12, -1, -9, -6, 6), M( 12, -1, -6, -3, 3) in 5-d lattice M - sage: P.normal_form(algorithm="palp_modified") # not tested (22s; MemoryError on 32 bit), needs sage.groups + sage: P.normal_form(algorithm='palp_modified') # not tested (22s; MemoryError on 32 bit), needs sage.groups M( 6, 0, 0, 0, 0), M( -6, 0, 0, 0, 0), M( 0, 1, 0, 0, 0), @@ -3231,12 +3175,11 @@ def _palp_modified_normal_form(self, permutation=False): INPUT: - - ``permutation`` -- boolean (default: ``False``); whether to return the permutation of - the order of the vertices that was applied to obtain this matrix. - - OUTPUT: + - ``permutation`` -- boolean (default: ``False``); whether to return + the permutation of the order of the vertices that was applied to + obtain this matrix - A matrix or a tuple of a matrix and a permutation. + OUTPUT: a matrix or a tuple of a matrix and a permutation EXAMPLES:: @@ -3286,10 +3229,7 @@ def _palp_native_normal_form(self, permutation=False): of the order of the vertices that was applied to obtain this matrix. - OUTPUT: - - A matrix or a tuple of a matrix and a permutation. - + OUTPUT: a matrix or a tuple of a matrix and a permutation EXAMPLES:: @@ -3336,9 +3276,9 @@ def _palp_PM_max(self, check=False): INPUT: - - ``check`` -- Boolean (default: ``False``), whether to return + - ``check`` -- boolean (default: ``False``); whether to return the permutations leaving the maximal vertex-facet pairing - matrix invariant. + matrix invariant OUTPUT: @@ -3434,11 +3374,9 @@ def nvertices(self): @cached_method def origin(self): r""" - Return the index of the origin in the list of points of self. + Return the index of the origin in the list of points of ``self``. - OUTPUT: - - - integer if the origin belongs to this polytope, ``None`` otherwise. + OUTPUT: integer if the origin belongs to this polytope, ``None`` otherwise EXAMPLES:: @@ -3505,55 +3443,54 @@ def plot3d(self, Most of the parameters are self-explanatory: - - ``show_facets`` -- (default: ``True``) - - - ``facet_opacity`` -- (default:0.5) + - ``show_facets`` -- (default: ``True``) - - ``facet_color`` -- (default:(0,1,0)) + - ``facet_opacity`` -- (default:0.5) - - ``facet_colors`` -- (default:None) if specified, must be a list of - colors for each facet separately, used instead of ``facet_color`` + - ``facet_color`` -- (default:(0,1,0)) - - ``show_edges`` -- (default: ``True``) whether to draw - edges as lines + - ``facet_colors`` -- (default:None) if specified, must be a list of + colors for each facet separately, used instead of ``facet_color`` - - ``edge_thickness`` -- (default:3) + - ``show_edges`` -- boolean (default: ``True``); whether to draw + edges as lines - - ``edge_color`` -- (default:(0.5,0.5,0.5)) + - ``edge_thickness`` -- (default:3) - - ``show_vertices`` -- (default: ``True``) whether to draw - vertices as balls + - ``edge_color`` -- (default:(0.5,0.5,0.5)) - - ``vertex_size`` -- (default:10) + - ``show_vertices`` -- boolean (default: ``True``); whether to draw + vertices as balls - - ``vertex_color`` -- (default:(1,0,0)) + - ``vertex_size`` -- (default:10) - - ``show_points`` -- (default: ``True``) whether to draw - other points as balls + - ``vertex_color`` -- (default:(1,0,0)) - - ``point_size`` -- (default:10) + - ``show_points`` -- boolean (default: ``True``); whether to draw + other points as balls - - ``point_color`` -- (default:(0,0,1)) + - ``point_size`` -- (default:10) - - ``show_vindices`` -- (default: same as - ``show_vertices``) whether to show indices of vertices + - ``point_color`` -- (default:(0,0,1)) - - ``vindex_color`` -- (default:(0,0,0)) color for - vertex labels + - ``show_vindices`` -- (default: same as + ``show_vertices``) whether to show indices of vertices - - ``vlabels`` -- (default:None) if specified, must be a list of labels - for each vertex, default labels are vertex indices + - ``vindex_color`` -- (default:(0,0,0)) color for + vertex labels - - ``show_pindices`` -- (default: same as ``show_points``) - whether to show indices of other points + - ``vlabels`` -- (default:None) if specified, must be a list of labels + for each vertex, default labels are vertex indices - - ``pindex_color`` -- (default:(0,0,0)) color for - point labels + - ``show_pindices`` -- (default: same as ``show_points``) + whether to show indices of other points - - ``index_shift`` -- (default:1.1)) if 1, labels are - placed exactly at the corresponding points. Otherwise the label - position is computed as a multiple of the point position vector. + - ``pindex_color`` -- (default:(0,0,0)) color for + point labels + - ``index_shift`` -- (default:1.1)) if 1, labels are + placed exactly at the corresponding points. Otherwise the label + position is computed as a multiple of the point position vector. EXAMPLES: The default plot of a cube:: @@ -3678,8 +3615,8 @@ def show3d(self): def point(self, i): r""" - Return the i-th point of this polytope, i.e. the i-th column of the - matrix returned by points(). + Return the `i`-th point of this polytope, i.e. the `i`-th column of the + matrix returned by ``points()``. EXAMPLES: First few points are actually vertices:: @@ -3719,9 +3656,7 @@ def points(self, *args, **kwds): - any arguments given will be passed on to the returned object. - OUTPUT: - - - a :class:`point collection `. + OUTPUT: a :class:`point collection ` EXAMPLES: @@ -3894,19 +3829,19 @@ def polar(self): def poly_x(self, keys, reduce_dimension=False): r""" - Run poly.x with given ``keys`` on vertices of this + Run ``poly.x`` with given ``keys`` on vertices of this polytope. INPUT: - - ``keys`` -- a string of options passed to poly.x. The - key "f" is added automatically. + - ``keys`` -- string of options passed to ``poly.x``. The + key "f" is added automatically - - ``reduce_dimension`` -- (default: ``False``) if ``True`` and this - polytope is not full-dimensional, poly.x will be called for the - vertices of this polytope in some basis of the spanned affine space. + - ``reduce_dimension`` -- boolean (default: ``False``); if ``True`` and this + polytope is not full-dimensional, ``poly.x`` will be called for the + vertices of this polytope in some basis of the spanned affine space - OUTPUT: the output of poly.x as a string. + OUTPUT: the output of ``poly.x`` as a string EXAMPLES: This call is used for determining if a polytope is reflexive or not:: @@ -3937,7 +3872,7 @@ def poly_x(self, keys, reduce_dimension=False): Output: Please increase POLY_Dmax to at least 7 - You cannot call poly.x for polytopes that don't span the space (if you + You cannot call ``poly.x`` for polytopes that don't span the space (if you could, it would crush anyway):: sage: p = LatticePolytope([(1,0,0), (0,1,0), (-1,0,0), (0,-1,0)]) @@ -4035,12 +3970,9 @@ def skeleton_show(self, normal=None): INPUT: - - - ``normal`` -- a 3-dimensional vector (can be given as - a list), which should be perpendicular to the screen. If not given, - will be selected randomly (new each time and it may be far from - "nice"). - + - ``normal`` -- a 3-dimensional vector (can be given as a list), which + should be perpendicular to the screen. If not given, will be selected + randomly (new each time and it may be far from "nice"). EXAMPLES: Show a pretty picture of the octahedron:: @@ -4092,8 +4024,8 @@ def traverse_boundary(self): def vertex(self, i): r""" - Return the i-th vertex of this polytope, i.e. the i-th column of - the matrix returned by vertices(). + Return the `i`-th vertex of this polytope, i.e. the `i`-th column of + the matrix returned by ``vertices()``. EXAMPLES: Note that numeration starts with zero:: @@ -4148,9 +4080,7 @@ def vertices(self, *args, **kwds): - any arguments given will be passed on to the returned object. - OUTPUT: - - - a :class:`point collection `. + OUTPUT: a :class:`point collection ` EXAMPLES: @@ -4189,7 +4119,7 @@ def is_NefPartition(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: @@ -4220,7 +4150,7 @@ class NefPartition(SageObject, Hashable): INPUT: - - ``data`` -- a list of integers, the `i`-th element of this list must be + - ``data`` -- list of integers, the `i`-th element of this list must be the part of the `i`-th vertex of ``Delta_polar`` in this nef-partition; - ``Delta_polar`` -- a :class:`lattice polytope @@ -4231,9 +4161,7 @@ class NefPartition(SageObject, Hashable): input is correct, you can speed up construction via ``check=False`` option. - OUTPUT: - - - a nef-partition of ``Delta_polar``. + OUTPUT: a nef-partition of ``Delta_polar`` Let `M` and `N` be dual lattices. Let `\Delta \subset M_\RR` be a reflexive polytope with polar `\Delta^\circ \subset N_\RR`. Let `X_\Delta` be the @@ -4297,10 +4225,10 @@ class NefPartition(SageObject, Hashable): It is very easy to create a nef-partition for the octahedron, since for this polytope any decomposition of vertices is a nef-partition. We create a - 3-part nef-partition with the 0-th and 1-st vertices belonging to the 0-th - part (recall that numeration in Sage starts with 0), the 2-nd and 5-th - vertices belonging to the 1-st part, and 3-rd and 4-th vertices belonging - to the 2-nd part:: + 3-part nef-partition with the 0th and 1st vertices belonging to the 0th + part (recall that numeration in Sage starts with 0), the 2nd and 5th + vertices belonging to the 1st part, and 3rd and 4th vertices belonging + to the 2nd part:: sage: o = lattice_polytope.cross_polytope(3) sage: np = NefPartition([0,0,1,2,2,1], o) @@ -4381,7 +4309,7 @@ def __eq__(self, other): INPUT: - - ``other`` -- anything. + - ``other`` -- anything OUTPUT: @@ -4419,9 +4347,7 @@ def __hash__(self): r""" Return the hash of ``self``. - OUTPUT: - - - an integer. + OUTPUT: integer TESTS:: @@ -4442,7 +4368,7 @@ def __ne__(self, other): INPUT: - - ``other`` -- anything. + - ``other`` -- anything OUTPUT: @@ -4478,9 +4404,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - a string. + OUTPUT: string TESTS:: @@ -4508,9 +4432,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - a string. + OUTPUT: string TESTS:: @@ -4565,11 +4487,9 @@ def Delta(self, i=None): INPUT: - - ``i`` -- an integer. If not given, `\Delta` will be returned. - - OUTPUT: + - ``i`` -- integer; if not given, `\Delta` will be returned - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` See :class:`nef-partition ` class documentation for definitions and notation. @@ -4607,9 +4527,7 @@ def Delta_polar(self): r""" Return the polytope `\Delta^\circ` corresponding to ``self``. - OUTPUT: - - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` See :class:`nef-partition ` class documentation for definitions and notation. @@ -4628,9 +4546,7 @@ def Deltas(self): r""" Return the polytopes `\Delta_i` corresponding to ``self``. - OUTPUT: - - - a tuple of :class:`lattice polytopes `. + OUTPUT: a tuple of :class:`lattice polytopes ` See :class:`nef-partition ` class documentation for definitions and notation. @@ -4679,9 +4595,7 @@ def dual(self): r""" Return the dual nef-partition. - OUTPUT: - - - a :class:`nef-partition `. + OUTPUT: a :class:`nef-partition ` See the class documentation for the definition. @@ -4733,9 +4647,7 @@ def hodge_numbers(self): r""" Return Hodge numbers corresponding to ``self``. - OUTPUT: - - - a tuple of integers (produced by ``nef.x`` program from PALP). + OUTPUT: a tuple of integers (produced by ``nef.x`` program from PALP) EXAMPLES: @@ -4765,11 +4677,9 @@ def nabla(self, i=None): INPUT: - - ``i`` -- an integer. If not given, `\nabla` will be returned. + - ``i`` -- integer; if not given, `\nabla` will be returned - OUTPUT: - - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` See :class:`nef-partition ` class documentation for definitions and notation. @@ -4812,9 +4722,7 @@ def nabla_polar(self): r""" Return the polytope `\nabla^\circ` corresponding to ``self``. - OUTPUT: - - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` See :class:`nef-partition ` class documentation for definitions and notation. @@ -4843,9 +4751,7 @@ def nablas(self): r""" Return the polytopes `\nabla_i` corresponding to ``self``. - OUTPUT: - - - a tuple of :class:`lattice polytopes `. + OUTPUT: a tuple of :class:`lattice polytopes ` See :class:`nef-partition ` class documentation for definitions and notation. @@ -4888,9 +4794,7 @@ def nparts(self): r""" Return the number of parts in ``self``. - OUTPUT: - - - an integer. + OUTPUT: integer EXAMPLES:: @@ -4908,9 +4812,9 @@ def part(self, i, all_points=False): INPUT: - - ``i`` -- an integer + - ``i`` -- integer - - ``all_points`` -- (default: ``False``) whether to list all lattice points + - ``all_points`` -- boolean (default: ``False``); whether to list all lattice points or just vertices OUTPUT: @@ -4944,7 +4848,7 @@ def parts(self, all_points=False): INPUT: - - ``all_points`` -- (default: ``False``) whether to list all lattice points + - ``all_points`` -- boolean (default: ``False``); whether to list all lattice points or just vertices OUTPUT: @@ -4985,7 +4889,7 @@ def part_of(self, i): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer OUTPUT: @@ -5014,7 +4918,7 @@ def part_of_point(self, i): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer OUTPUT: @@ -5026,7 +4930,7 @@ def part_of_point(self, i): Since a nef-partition induces a partition on the set of boundary lattice points of `\Delta^\circ`, the value of `j` is well-defined for all `i` but the one that corresponds to the origin, in which - case this method will raise a :class:`ValueError` exception. + case this method will raise a :exc:`ValueError` exception. (The origin always belongs to all `\nabla_j`.) See :class:`nef-partition ` class documentation for @@ -5086,7 +4990,7 @@ def _palp(command, polytopes, reduce_dimension=False): Returns the name of the file containing the output of ``command``. You should delete it after using. - .. note:: + .. NOTE:: PALP cannot be called for polytopes that do not span the ambient space. If you specify ``reduce_dimension=True`` argument, PALP will be @@ -5173,12 +5077,12 @@ def _palp_canonical_order(V, PM_max, permutations): INPUT: - - ``V`` -- :class:`point collection `. The vertices. + - ``V`` -- :class:`point collection `. The vertices - ``PM_max`` -- the maximal vertex-facet pairing matrix - ``permutations`` -- the permutations of the vertices yielding - ``PM_max``. + ``PM_max`` OUTPUT: @@ -5219,11 +5123,9 @@ def _palp_convert_permutation(permutation): INPUT: - - ``permutation`` -- A string specifying a PALP style permutation. - - OUTPUT: + - ``permutation`` -- string specifying a PALP style permutation - A :class:`permutation group element `. + OUTPUT: a :class:`permutation group element ` EXAMPLES:: @@ -5260,13 +5162,15 @@ def _read_nef_x_partitions(data): Read all nef-partitions for one polytope from a string or an open file. - ``data`` should be an output of nef.x. + INPUT: + + - ``data`` -- should be an output of ``nef.x`` Returns the sequence of nef-partitions. Each nef-partition is given as a sequence of integers. If there are no nef-partitions, returns the empty sequence. If the - string is empty or EOF is reached, raises ValueError. + string is empty or EOF is reached, raises :exc:`ValueError`. TESTS:: @@ -5319,17 +5223,15 @@ def _read_poly_x_incidences(data, dim): INPUT: - - ``data`` -- an opened file with incidence - information. The first line will be skipped, each consecutive line - contains incidence information for all faces of one dimension, the - first word of each line is a comment and is dropped. + - ``data`` -- an opened file with incidence + information. The first line will be skipped, each consecutive line + contains incidence information for all faces of one dimension, the + first word of each line is a comment and is dropped. - - ``dim`` -- dimension of the polytope. + - ``dim`` -- dimension of the polytope - OUTPUT: - - a sequence F, such that F[d][i] is a sequence of vertices - or facets corresponding to the i-th d-dimensional face. + OUTPUT: a sequence F, such that F[d][i] is a sequence of vertices + or facets corresponding to the `i`-th d-dimensional face TESTS:: @@ -5381,7 +5283,9 @@ def all_cached_data(polytopes): polytopes in the given sequence should be constructed as the polar polytope to another one. - INPUT: a sequence of lattice polytopes. + INPUT: + + - ``polytopes`` -- a sequence of lattice polytopes EXAMPLES: This function has no output, it is just a fast way to work with long sequences of polytopes. Of course, you can use short @@ -5412,7 +5316,9 @@ def all_nef_partitions(polytopes, keep_symmetric=False): ``all_polars`` on the sequence of ``polytopes`` before using this function. - INPUT: a sequence of lattice polytopes. + INPUT: + + - ``polytopes`` -- a sequence of lattice polytopes EXAMPLES: This function has no output, it is just a fast way to work with long sequences of polytopes. Of course, you can use short @@ -5461,7 +5367,9 @@ def all_points(polytopes): ``LatticePolytope`` during the first run. So it is recommended to use this functions if you work with big sets of data. - INPUT: a sequence of lattice polytopes. + INPUT: + + - ``polytopes`` -- a sequence of lattice polytopes EXAMPLES: This function has no output, it is just a fast way to work with long sequences of polytopes. Of course, you can use short @@ -5514,7 +5422,9 @@ def all_polars(polytopes): ``LatticePolytope`` during the first run. So it is recommended to use this functions if you work with big sets of data. - INPUT: a sequence of lattice polytopes. + INPUT: + + - ``polytopes`` -- a sequence of lattice polytopes EXAMPLES: This function has no output, it is just a fast way to work with long sequences of polytopes. Of course, you can use short @@ -5541,20 +5451,17 @@ def convex_hull(points): r""" Compute the convex hull of the given points. - .. note:: + .. NOTE:: ``points`` might not span the space. Also, it fails for large numbers of vertices in dimensions 4 or greater INPUT: - - ``points`` -- a list that can be converted into - vectors of the same dimension over ZZ. - - OUTPUT: + - ``points`` -- list that can be converted into + vectors of the same dimension over `\ZZ` - list of vertices of the convex hull of the given points (as - vectors). + OUTPUT: list of vertices of the convex hull of the given points (as vectors) EXAMPLES: Let's compute the convex hull of several points on a line in the plane:: @@ -5591,11 +5498,9 @@ def cross_polytope(dim): INPUT: - - ``dim`` -- an integer. - - OUTPUT: + - ``dim`` -- integer - - a :class:`lattice polytope `. + OUTPUT: a :class:`lattice polytope ` EXAMPLES:: @@ -5621,17 +5526,17 @@ def minkowski_sum(points1, points2): r""" Compute the Minkowski sum of two convex polytopes. - .. note:: + .. NOTE:: Polytopes might not be of maximal dimension. INPUT: - - ``points1, points2`` -- lists of objects that can be - converted into vectors of the same dimension, treated as vertices - of two polytopes. + - ``points1``, ``points2`` -- lists of objects that can be + converted into vectors of the same dimension, treated as vertices + of two polytopes. - OUTPUT: list of vertices of the Minkowski sum, given as vectors. + OUTPUT: list of vertices of the Minkowski sum, given as vectors EXAMPLES: Let's compute the Minkowski sum of two line segments:: @@ -5653,12 +5558,9 @@ def positive_integer_relations(points): INPUT: - - ``points`` -- lattice points given as columns of a - matrix + - ``points`` -- lattice points given as columns of a matrix - OUTPUT: - - matrix of relations between given points with non-negative + OUTPUT: matrix of relations between given points with nonnegative integer coefficients EXAMPLES: This is a 3-dimensional reflexive polytope:: @@ -5684,7 +5586,7 @@ def positive_integer_relations(points): However, the above relations may contain negative and rational numbers. This function transforms them in such a way, that all - coefficients are non-negative integers:: + coefficients are nonnegative integers:: sage: points = p.points().column_matrix() sage: lattice_polytope.positive_integer_relations(points) # needs palp @@ -5708,8 +5610,8 @@ def positive_integer_relations(points): a = nonpivot_relations.stack(a).transpose() new_relations = [] for i in range(n_nonpivots): - # Find a non-negative linear combination of relations, - # such that all components are non-negative and the i-th one is 1 + # Find a nonnegative linear combination of relations, + # such that all components are nonnegative and the `i`-th one is 1 MIP = MixedIntegerLinearProgram(maximization=False, base_ring=QQ) w = MIP.new_variable(integer=False, nonnegative=True) b = vector([0] * i + [1] + [0] * (n_nonpivots - i - 1)) @@ -5742,16 +5644,14 @@ def read_all_polytopes(file_name): INPUT: - - ``file_name`` -- a string with the name of a file with VERTICES of - polytopes. - - OUTPUT: + - ``file_name`` -- string with the name of a file with VERTICES of + polytopes - - a sequence of polytopes. + OUTPUT: a sequence of polytopes EXAMPLES: - We use poly.x to compute two polar polytopes and read them:: + We use ``poly.x`` to compute two polar polytopes and read them:: sage: # needs palp sage: d = lattice_polytope.cross_polytope(2) @@ -5801,16 +5701,14 @@ def read_palp_matrix(data, permutation=False): INPUT: - - ``data`` -- Either a string containing the filename or the file itself - containing the output by PALP. + - ``data`` -- either a string containing the filename or the file itself + containing the output by PALP - - ``permutation`` -- (default: ``False``) If ``True``, try to retrieve + - ``permutation`` -- boolean (default: ``False``); if ``True``, try to retrieve the permutation output by PALP. This parameter makes sense only when PALP computed the normal form of a lattice polytope. - OUTPUT: - - A matrix or a tuple of a matrix and a permutation. + OUTPUT: a matrix or a tuple of a matrix and a permutation EXAMPLES:: @@ -5857,11 +5755,9 @@ def set_palp_dimension(d): INPUT: - - ``d`` -- an integer from the list [4,5,6,11] or ``None``. - - OUTPUT: + - ``d`` -- integer from the list ``[4,5,6,11]`` or ``None`` - - none. + OUTPUT: none PALP has many hard-coded limits, which must be specified before compilation, one of them is dimension. Sage includes several versions with @@ -5903,16 +5799,14 @@ def skip_palp_matrix(data, n=1): INPUT: + - ``data`` -- opened file with blocks of matrix data in + the following format: A block consisting of m+1 lines has the + number m as the first element of its first line. - - ``data`` -- opened file with blocks of matrix data in - the following format: A block consisting of m+1 lines has the - number m as the first element of its first line. - - - ``n`` -- (default: 1) integer, specifies how many - blocks should be skipped + - ``n`` -- (default: 1) integer, specifies how many + blocks should be skipped - - If EOF is reached during the process, raises ValueError exception. + If EOF is reached during the process, raises :exc:`ValueError` exception. EXAMPLES: We create a file with vertices of the square and the cube, but read only the second set:: @@ -5955,25 +5849,22 @@ def skip_palp_matrix(data, n=1): raise ValueError("There are not enough data to skip!") -def write_palp_matrix(m, ofile=None, comment="", format=None): +def write_palp_matrix(m, ofile=None, comment='', format=None): r""" Write ``m`` into ``ofile`` in PALP format. INPUT: - ``m`` -- a matrix over integers or a - :class:`point collection `. - - - ``ofile`` -- a file opened for writing (default: stdout) + :class:`point collection ` - - ``comment`` -- a string (default: empty) see output description + - ``ofile`` -- a file opened for writing (default: ``stdout``) - - ``format`` -- a format string used to print matrix entries. + - ``comment`` -- string (default: empty); see output description + - ``format`` -- a format string used to print matrix entries - OUTPUT: - - - nothing is returned, output written to ``ofile`` has the format + OUTPUT: nothing is returned, output written to ``ofile`` has the format * First line: number_of_rows number_of_columns comment * Next number_of_rows lines: rows of the matrix. @@ -5986,7 +5877,7 @@ def write_palp_matrix(m, ofile=None, comment="", format=None): 1 0 0 -1 0 0 0 1 0 0 -1 0 0 0 1 0 0 -1 - sage: lattice_polytope.write_palp_matrix(o.vertices(), format="%4d") + sage: lattice_polytope.write_palp_matrix(o.vertices(), format='%4d') 3 6 1 0 0 -1 0 0 0 1 0 0 -1 0 diff --git a/src/sage/geometry/linear_expression.py b/src/sage/geometry/linear_expression.py index 8cee8aa7c12..bef7fd7160b 100644 --- a/src/sage/geometry/linear_expression.py +++ b/src/sage/geometry/linear_expression.py @@ -103,9 +103,7 @@ def A(self): """ Return the coefficient vector. - OUTPUT: - - The coefficient vector of the linear expression. + OUTPUT: the coefficient vector of the linear expression EXAMPLES:: @@ -124,9 +122,7 @@ def b(self): """ Return the constant term. - OUTPUT: - - The constant term of the linear expression. + OUTPUT: the constant term of the linear expression EXAMPLES:: @@ -225,12 +221,10 @@ def _repr_linear(self, include_zero=True, include_constant=True, multiplication= - ``include_constant`` -- whether to include the constant term - - ``multiplication`` -- string (default: ``*``); the + - ``multiplication`` -- string (default: ``'*'``); the multiplication symbol to use - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -359,9 +353,7 @@ def change_ring(self, base_ring): - ``base_ring`` -- a ring; the new base ring - OUTPUT: - - A new linear expression over the new base ring. + OUTPUT: a new linear expression over the new base ring EXAMPLES:: @@ -427,9 +419,7 @@ def evaluate(self, point): - ``point`` -- list/tuple/iterable of coordinates; the coordinates of a point - OUTPUT: - - The linear expression `Ax + b` evaluated at the point `x`. + OUTPUT: the linear expression `Ax + b` evaluated at the point `x` EXAMPLES:: @@ -520,9 +510,7 @@ def ngens(self): """ Return the number of linear variables. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -538,9 +526,7 @@ def gens(self) -> tuple: """ Return the generators of ``self``. - OUTPUT: - - A tuple of linear expressions, one for each linear variable. + OUTPUT: a tuple of linear expressions, one for each linear variable EXAMPLES:: @@ -561,9 +547,7 @@ def gen(self, i): - ``i`` -- integer - OUTPUT: - - A linear expression. + OUTPUT: a linear expression EXAMPLES:: @@ -752,9 +736,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -773,9 +755,7 @@ def change_ring(self, base_ring): - ``base_ring`` -- a ring; the new base ring - OUTPUT: - - A new linear expression over the new base ring. + OUTPUT: a new linear expression over the new base ring EXAMPLES:: diff --git a/src/sage/geometry/newton_polygon.py b/src/sage/geometry/newton_polygon.py index c8e185d01e6..05cfbcbf621 100644 --- a/src/sage/geometry/newton_polygon.py +++ b/src/sage/geometry/newton_polygon.py @@ -36,7 +36,7 @@ def __init__(self, polyhedron, parent): INPUT: - - polyhedron -- a polyhedron defining the Newton polygon + - ``polyhedron`` -- a polyhedron defining the Newton polygon TESTS: @@ -87,15 +87,13 @@ def _repr_(self): def vertices(self, copy=True): """ - Returns the list of vertices of this Newton polygon + Return the list of vertices of this Newton polygon. INPUT: - - ``copy`` -- a boolean (default: ``True``) + - ``copy`` -- boolean (default: ``True``) - OUTPUT: - - The list of vertices of this Newton polygon (or a copy of it + OUTPUT: the list of vertices of this Newton polygon (or a copy of it if ``copy`` is set to True) EXAMPLES:: @@ -126,7 +124,7 @@ def vertices(self, copy=True): @cached_method def last_slope(self): """ - Returns the last (infinite) slope of this Newton polygon + Return the last (infinite) slope of this Newton polygon if it is infinite and ``+Infinity`` otherwise. EXAMPLES:: @@ -156,11 +154,11 @@ def last_slope(self): def slopes(self, repetition=True): """ - Returns the slopes of this Newton polygon + Return the slopes of this Newton polygon. INPUT: - - ``repetition`` -- a boolean (default: ``True``) + - ``repetition`` -- boolean (default: ``True``) OUTPUT: @@ -196,15 +194,13 @@ def slopes(self, repetition=True): def _add_(self, other): """ - Returns the convex hull of ``self`` and ``other`` + Return the convex hull of ``self`` and ``other``. INPUT: - ``other`` -- a Newton polygon - OUTPUT: - - The Newton polygon, which is the convex hull of this Newton polygon and ``other`` + OUTPUT: the Newton polygon, which is the convex hull of this Newton polygon and ``other`` EXAMPLES:: @@ -222,15 +218,13 @@ def _add_(self, other): def _mul_(self, other): """ - Returns the Minkowski sum of ``self`` and ``other`` + Return the Minkowski sum of ``self`` and ``other``. INPUT: - ``other`` -- a Newton polygon - OUTPUT: - - The Newton polygon, which is the Minkowski sum of this Newton polygon and ``other``. + OUTPUT: the Newton polygon, which is the Minkowski sum of this Newton polygon and ``other`` .. NOTE:: @@ -263,15 +257,13 @@ def _mul_(self, other): def __pow__(self, exp, ignored=None): """ - Returns ``self`` dilated by ``exp`` + Return ``self`` dilated by ``exp``. INPUT: - - ``exp`` -- a positive integer - - OUTPUT: + - ``exp`` -- positive integer - This Newton polygon scaled by a factor ``exp``. + OUTPUT: this Newton polygon scaled by a factor ``exp`` .. NOTE:: @@ -292,15 +284,13 @@ def __pow__(self, exp, ignored=None): def __lshift__(self, i): """ - Returns ``self`` shifted by `(0,i)` + Return ``self`` shifted by `(0,i)`. INPUT: - ``i`` -- a rational number - OUTPUT: - - This Newton polygon shifted by the vector `(0,i)` + OUTPUT: this Newton polygon shifted by the vector `(0,i)` EXAMPLES:: @@ -316,15 +306,13 @@ def __lshift__(self, i): def __rshift__(self, i): """ - Returns ``self`` shifted by `(0,-i)` + Return ``self`` shifted by `(0,-i)`. INPUT: - ``i`` -- a rational number - OUTPUT: - - This Newton polygon shifted by the vector `(0,-i)` + OUTPUT: this Newton polygon shifted by the vector `(0,-i)` EXAMPLES:: @@ -340,15 +328,13 @@ def __rshift__(self, i): def __call__(self, x): """ - Returns `self(x)` + Return `self(x)`. INPUT: - ``x`` -- a real number - OUTPUT: - - The value of this Newton polygon at abscissa `x` + OUTPUT: the value of this Newton polygon at abscissa `x` EXAMPLES:: @@ -476,27 +462,27 @@ def plot(self, **kwargs): (xstart,ystart) = vertices[0] (xend,yend) = vertices[-1] if self.last_slope() is Infinity: - return line([(xstart, ystart+1), (xstart,ystart+0.5)], linestyle="--", **kwargs) \ + return line([(xstart, ystart+1), (xstart,ystart+0.5)], linestyle='--', **kwargs) \ + line([(xstart, ystart+0.5)] + vertices + [(xend, yend+0.5)], **kwargs) \ - + line([(xend, yend+0.5), (xend, yend+1)], linestyle="--", **kwargs) + + line([(xend, yend+0.5), (xend, yend+1)], linestyle='--', **kwargs) else: - return line([(xstart, ystart+1), (xstart,ystart+0.5)], linestyle="--", **kwargs) \ + return line([(xstart, ystart+1), (xstart,ystart+0.5)], linestyle='--', **kwargs) \ + line([(xstart, ystart+0.5)] + vertices + [(xend+0.5, yend + 0.5*self.last_slope())], **kwargs) \ - + line([(xend+0.5, yend + 0.5*self.last_slope()), (xend+1, yend+self.last_slope())], linestyle="--", **kwargs) + + line([(xend+0.5, yend + 0.5*self.last_slope()), (xend+1, yend+self.last_slope())], linestyle='--', **kwargs) def reverse(self, degree=None): r""" - Returns the symmetric of ``self`` + Return the symmetric of ``self``. INPUT: - - ``degree`` -- an integer (default: the top right abscissa of + - ``degree`` -- integer (default: the top right abscissa of this Newton polygon) OUTPUT: The image this Newton polygon under the symmetry - '(x,y) \mapsto (degree-x, y)` + '(x,y) \mapsto (degree-x, y)`. EXAMPLES:: @@ -530,20 +516,18 @@ class ParentNewtonPolygon(Parent, UniqueRepresentation): INPUT: - - ``arg`` -- a list/tuple/iterable of vertices or of - slopes. Currently, slopes must be rational numbers. + - ``arg`` -- list/tuple/iterable of vertices or of + slopes. Currently, slopes must be rational numbers - - ``sort_slopes`` -- boolean (default: ``True``). Specifying - whether slopes must be first sorted + - ``sort_slopes`` -- boolean (default: ``True``); whether slopes must be + first sorted - ``last_slope`` -- rational or infinity (default: - ``Infinity``). The last slope of the Newton polygon - - OUTPUT: + ``Infinity``); the last slope of the Newton polygon - The corresponding Newton polygon. + OUTPUT: the corresponding Newton polygon - .. note:: + .. NOTE:: By convention, a Newton polygon always contains the point at infinity `(0, \infty)`. These polygons are attached to @@ -652,8 +636,8 @@ def __init__(self): def _repr_(self): """ - Returns the string representation of this parent, - which is ``Parent for Newton polygons`` + Return the string representation of this parent, + which is ``Parent for Newton polygons``. TESTS: @@ -668,7 +652,7 @@ def _repr_(self): def _an_element_(self): """ - Returns a Newton polygon (which is the empty one) + Return a Newton polygon (which is the empty one). TESTS: @@ -684,8 +668,8 @@ def _element_constructor_(self, arg, sort_slopes=True, last_slope=Infinity): - ``arg`` -- an argument describing the Newton polygon - - ``sort_slopes`` -- boolean (default: ``True``). Specifying - whether slopes must be first sorted + - ``sort_slopes`` -- boolean (default: ``True``); whether + slopes must be first sorted - ``last_slope`` -- rational or infinity (default: ``Infinity``). The last slope of the Newton polygon @@ -703,9 +687,7 @@ def _element_constructor_(self, arg, sort_slopes=True, last_slope=Infinity): - a list/tuple/iterable of slopes - OUTPUT: - - The corresponding Newton polygon. + OUTPUT: the corresponding Newton polygon For more informations, see :class:`ParentNewtonPolygon`. diff --git a/src/sage/geometry/palp_normal_form.pyx b/src/sage/geometry/palp_normal_form.pyx index fa756fe65b0..82e26830234 100644 --- a/src/sage/geometry/palp_normal_form.pyx +++ b/src/sage/geometry/palp_normal_form.pyx @@ -42,9 +42,9 @@ def _palp_PM_max(Matrix_integer_dense PM, check=False): INPUT: - - ``check`` -- Boolean (default: ``False``), whether to return + - ``check`` -- boolean (default: ``False``); whether to return the permutations leaving the maximal vertex-facet pairing - matrix invariant. + matrix invariant OUTPUT: @@ -350,15 +350,13 @@ def _palp_canonical_order(vertices, PM_max, permutations): INPUT: - - ``vertices`` -- iterable of iterables. The vertices. + - ``vertices`` -- iterable of iterables; the vertices - ``PM_max`` -- the maximal vertex-facet pairing matrix - - ``permutation`` -- the permutations of the vertices yielding ``PM_max``. + - ``permutation`` -- the permutations of the vertices yielding ``PM_max`` - OUTPUT: - - The PALP normal form as an iterable of integer vectors. + OUTPUT: the PALP normal form as an iterable of integer vectors TESTS:: diff --git a/src/sage/geometry/point_collection.pyx b/src/sage/geometry/point_collection.pyx index ae4c92ffd75..f310dc7cb14 100644 --- a/src/sage/geometry/point_collection.pyx +++ b/src/sage/geometry/point_collection.pyx @@ -90,11 +90,9 @@ def is_PointCollection(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - - ``True`` if ``x`` is a point collection and ``False`` otherwise. + OUTPUT: ``True`` if ``x`` is a point collection and ``False`` otherwise EXAMPLES:: @@ -205,11 +203,9 @@ cdef class PointCollection(SageObject): - ``left`` -- a :class:`PointCollection`; - - ``right`` -- a :class:`PointCollection`. - - OUTPUT: + - ``right`` -- a :class:`PointCollection` - - a :class:`PointCollection`. + OUTPUT: a :class:`PointCollection` TESTS:: @@ -243,9 +239,7 @@ cdef class PointCollection(SageObject): - a list of integers (as a single or many arguments). - OUTPUT: - - - a :class:`point collection `. + OUTPUT: a :class:`point collection ` TESTS:: @@ -279,9 +273,7 @@ cdef class PointCollection(SageObject): - ``right`` -- another PointCollection - OUTPUT: - - boolean + OUTPUT: boolean First compare according to the underlying :meth:`module` and then according to the list of points. @@ -314,11 +306,9 @@ cdef class PointCollection(SageObject): INPUT: - - ``n`` -- an integer. + - ``n`` -- integer - OUTPUT: - - - a point, an element of the ambient :meth:`module` of ``self``. + OUTPUT: a point, an element of the ambient :meth:`module` of ``self`` EXAMPLES:: @@ -332,9 +322,7 @@ cdef class PointCollection(SageObject): r""" Return the hash of ``self``. - OUTPUT: - - - an integer. + OUTPUT: integer TESTS:: @@ -348,9 +336,7 @@ cdef class PointCollection(SageObject): r""" Return an iterator over points of ``self``. - OUTPUT: - - - an iterator. + OUTPUT: an iterator TESTS:: @@ -367,9 +353,7 @@ cdef class PointCollection(SageObject): r""" Return the number of points in ``self``. - OUTPUT: - - - an integer. + OUTPUT: integer EXAMPLES:: @@ -383,9 +367,7 @@ cdef class PointCollection(SageObject): r""" Return a list of points of ``self``. - OUTPUT: - - - a list. + OUTPUT: list TESTS:: @@ -481,9 +463,7 @@ cdef class PointCollection(SageObject): r""" Return the tuple of points of ``self``. - OUTPUT: - - - a tuple. + OUTPUT: a tuple TESTS:: @@ -497,9 +477,7 @@ cdef class PointCollection(SageObject): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - a string. + OUTPUT: string TESTS:: @@ -527,11 +505,9 @@ cdef class PointCollection(SageObject): INPUT: - ``ring`` -- a base ring for the returned matrix (default: base ring of - :meth:`module` of ``self``). - - OUTPUT: + :meth:`module` of ``self``) - - a :class:`matrix `. + OUTPUT: a :class:`matrix ` EXAMPLES:: @@ -551,9 +527,7 @@ cdef class PointCollection(SageObject): r""" Return a string representation of ``self``. - OUTPUT: - - - a string. + OUTPUT: string TESTS:: @@ -631,9 +605,7 @@ cdef class PointCollection(SageObject): r""" Return the number of points in ``self``. - OUTPUT: - - - an integer. + OUTPUT: integer EXAMPLES:: @@ -655,9 +627,7 @@ cdef class PointCollection(SageObject): default, the direct sum of the ambient modules of ``self`` and ``other`` is constructed. - OUTPUT: - - - a :class:`point collection `. + OUTPUT: a :class:`point collection ` EXAMPLES:: @@ -683,9 +653,7 @@ cdef class PointCollection(SageObject): r""" Return a matrix whose columns are points of ``self``. - OUTPUT: - - - a :class:`matrix `. + OUTPUT: a :class:`matrix ` EXAMPLES:: @@ -703,9 +671,7 @@ cdef class PointCollection(SageObject): .. NOTE:: You can use either :meth:`dim` or :meth:`dimension`. - OUTPUT: - - - an integer. + OUTPUT: integer EXAMPLES:: @@ -749,18 +715,16 @@ cdef class PointCollection(SageObject): INPUT: - - ``point`` -- a point of ``self``; + - ``point`` -- a point of ``self`` - ``start`` -- (optional) an integer, if given, the search will start - at this position; + at this position - ``stop`` -- (optional) an integer, if given, the search will stop - at this position. + at this position - OUTPUT: - - - an integer if ``point`` is in ``self[start:stop]``, otherwise a - :class:`ValueError` exception is raised. + OUTPUT: an integer if ``point`` is in ``self[start:stop]``, otherwise a + :exc:`ValueError` exception is raised EXAMPLES:: @@ -786,9 +750,7 @@ cdef class PointCollection(SageObject): r""" Return a matrix whose rows are points of ``self``. - OUTPUT: - - - a :class:`matrix `. + OUTPUT: a :class:`matrix ` EXAMPLES:: @@ -810,9 +772,7 @@ cdef class PointCollection(SageObject): r""" Return the ambient module of ``self``. - OUTPUT: - - - a :class:`module `. + OUTPUT: a :class:`module ` EXAMPLES:: @@ -912,9 +872,7 @@ cdef class PointCollection(SageObject): r""" Return points of ``self`` as a :class:`frozenset`. - OUTPUT: - - - a :class:`frozenset`. + OUTPUT: a :class:`frozenset` EXAMPLES:: @@ -932,7 +890,7 @@ cdef class PointCollection(SageObject): INPUT: - - ``f`` -- a file opened for writing. + - ``f`` -- a file opened for writing EXAMPLES:: @@ -974,13 +932,13 @@ def read_palp_point_collection(f, lattice=None, permutation=False): INPUT: - - ``f`` -- an opened file with PALP output. + - ``f`` -- an opened file with PALP output - ``lattice`` -- the lattice for points. If not given, the :class:`toric lattice ` `M` of dimension `n` will be used. - - ``permutation`` -- (default: ``False``) if ``True``, try to retrieve + - ``permutation`` -- boolean (default: ``False``); if ``True``, try to retrieve the permutation. This parameter makes sense only when PALP computed the normal form of a lattice polytope. diff --git a/src/sage/geometry/polyhedral_complex.py b/src/sage/geometry/polyhedral_complex.py index 56a84be0300..5e7d99e7587 100644 --- a/src/sage/geometry/polyhedral_complex.py +++ b/src/sage/geometry/polyhedral_complex.py @@ -150,7 +150,7 @@ class PolyhedralComplex(GenericCellComplex): INPUT: - - ``maximal_cells`` -- a list, a tuple, or a dictionary (indexed by + - ``maximal_cells`` -- list, tuple, or dictionary (indexed by dimension) of cells of the Complex. Each cell is of class :class:`Polyhedron` of the same ambient dimension. To set up a :class:PolyhedralComplex, it is sufficient to provide the maximal @@ -165,7 +165,7 @@ class PolyhedralComplex(GenericCellComplex): - ``face_to_face_check`` -- boolean (default: ``False``); if ``True``, then the constructor checks whether the cells - are face-to-face, and it raises a :class:`ValueError` if they are not + are face-to-face, and it raises a :exc:`ValueError` if they are not - ``is_mutable`` and ``is_immutable`` -- boolean (default: ``True`` and ``False`` respectively); set ``is_mutable=False`` or ``is_immutable=True`` @@ -394,7 +394,7 @@ def cell_iterator(self, increasing=True): INPUT: - - ``increasing`` -- (default ``True``) if ``True``, return + - ``increasing`` -- boolean (default: ``True``); if ``True``, return cells in increasing order of dimension, thus starting with the zero-dimensional cells; otherwise it returns cells in decreasing order of dimension @@ -425,7 +425,7 @@ def _n_cells_sorted(self, n, subcomplex=None): INPUT: - - ``n`` -- non-negative integer; the dimension + - ``n`` -- nonnegative integer; the dimension - ``subcomplex`` -- (optional) if a subcomplex is given then return the cells which are **not** in this subcomplex @@ -509,7 +509,7 @@ def maximal_cell_iterator(self, increasing=False): INPUT: - - ``increasing`` -- (default: ``False``) if ``True``, return + - ``increasing`` -- boolean (default: ``False``); if ``True``, return maximal cells in increasing order of dimension. Otherwise it returns cells in decreasing order of dimension. @@ -552,7 +552,7 @@ def n_maximal_cells(self, n): INPUT: - - ``n`` -- non-negative integer; the dimension + - ``n`` -- nonnegative integer; the dimension .. NOTE:: @@ -594,7 +594,7 @@ def _n_maximal_cells_sorted(self, n): INPUT: - - ``n`` -- (non-negative integer) the dimension + - ``n`` -- nonnegative integer; the dimension .. WARNING:: @@ -730,15 +730,15 @@ def plot(self, **kwds): can be passed to :func:`exploded_plot`: - ``center`` -- (default: ``None``, denoting the origin) the center of explosion - - ``sticky_vertices`` -- (default: ``False``) boolean or dict. - Whether to draw line segments between shared vertices of the given polyhedra. + - ``sticky_vertices`` -- (default: ``False``) boolean or dict; + whether to draw line segments between shared vertices of the given polyhedra. A dict gives options for :func:`sage.plot.line`. - ``sticky_center`` -- (default: ``True``) boolean or dict. When ``center`` is a vertex of some of the polyhedra, whether to draw line segments connecting the ``center`` to the shifted copies of these vertices. A dict gives options for :func:`sage.plot.line`. - - ``color`` -- (default: ``None``) if ``"rainbow"``, assign a different color + - ``color`` -- (default: ``None``) if ``'rainbow'``, assign a different color to every maximal cell; otherwise, passed on to :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot`. @@ -775,7 +775,6 @@ def plot(self, **kwds): ....: Polyhedron(rays=[[-1,0,0], [0,1,0], [0,0,1]])]) sage: g5 = pc5.plot(explosion_factor=0.3, color='rainbow', alpha=0.8, # needs sage.plot ....: point={'size': 20}, axes=False, online=True) - """ if self.dimension() > 3: raise ValueError("cannot plot in high dimension") @@ -946,7 +945,7 @@ def _an_element_(self): def __contains__(self, x): """ - True if ``x`` is a polyhedron which is contained in this complex. + Return ``True`` if ``x`` is a polyhedron which is contained in this complex. EXAMPLES:: @@ -972,7 +971,7 @@ def __contains__(self, x): def __call__(self, x): """ If ``x`` is a polyhedron in this complex, return it. - Otherwise, raise a :class:`ValueError`. + Otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -1062,7 +1061,7 @@ def is_subcomplex(self, other): def is_compact(self): """ - Test for boundedness of the polyhedral complex + Test for boundedness of the polyhedral complex. EXAMPLES:: @@ -1080,7 +1079,7 @@ def graph(self): Return the 1-skeleton of this polyhedral complex, as a graph. The vertices of the graph are of type ``vector``. This raises - a :class:`NotImplementedError` if the polyhedral complex is unbounded. + a :exc:`NotImplementedError` if the polyhedral complex is unbounded. .. WARNING:: @@ -1319,7 +1318,7 @@ def n_skeleton(self, n): INPUT: - - ``n`` -- non-negative integer; the dimension + - ``n`` -- nonnegative integer; the dimension .. SEEALSO:: @@ -1676,9 +1675,7 @@ def product(self, right): - ``right`` -- the other polyhedral complex (the right-hand factor) - OUTPUT: - - - the product ``self x right`` + OUTPUT: the product ``self x right`` EXAMPLES:: @@ -2139,7 +2136,7 @@ def remove_cell(self, cell, check=False): TESTS: - Check that ValueError and empty complex are treated properly:: + Check that :exc:`ValueError` and empty complex are treated properly:: sage: p = Polyhedron(vertices=[[1]]) sage: pc = PolyhedralComplex([p]) @@ -2462,7 +2459,7 @@ def subdivide(self, make_simplicial=False, return PolyhedralComplex(cones, maximality_check=False, backend=self._backend) else: - # TODO: `self`` is unbounded, make it projectively simplicial. + # TODO: ``self`` is unbounded, make it projectively simplicial. # (1) homogenize self of dim d to fan in space of dim d+1; # (2) call fan.subdivide(make_simplicial=True); # (3) take section back to the space of dim d. @@ -2506,28 +2503,35 @@ def exploded_plot(polyhedra, *, center=None, explosion_factor=1, sticky_vertices=False, sticky_center=True, point=None, **kwds): r""" - Return a plot of several ``polyhedra`` in one figure with extra space between them. + Return a plot of several ``polyhedra`` in one figure with extra space + between them. INPUT: - - ``polyhedra`` -- an iterable of :class:`~sage.geometry.polyhedron.base.Polyhedron_base` objects + - ``polyhedra`` -- an iterable of + :class:`~sage.geometry.polyhedron.base.Polyhedron_base` objects - - ``center`` -- (default: ``None``, denoting the origin) the center of explosion + - ``center`` -- (default: ``None``, denoting the origin) the center of + explosion - - ``explosion_factor`` -- (default: 1) a nonnegative number; translate polyhedra by this - factor of the distance from ``center`` to their center + - ``explosion_factor`` -- (default: 1) a nonnegative number; translate + polyhedra by this factor of the distance from ``center`` to their center - - ``sticky_vertices`` -- (default: ``False``) boolean or dict. Whether to draw line segments between shared - vertices of the given polyhedra. A dict gives options for :func:`sage.plot.line`. + - ``sticky_vertices`` -- (default: ``False``) boolean or dict; whether to + draw line segments between shared vertices of the given polyhedra. A dict + gives options for :func:`sage.plot.line`. - - ``sticky_center`` -- (default: ``True``) boolean or dict. When ``center`` is a vertex of some - of the polyhedra, whether to draw line segments connecting the ``center`` to the shifted copies - of these vertices. A dict gives options for :func:`sage.plot.line`. + - ``sticky_center`` -- (default: ``True``) boolean or dict. When ``center`` + is a vertex of some of the polyhedra, whether to draw line segments + connecting the ``center`` to the shifted copies of these vertices. A dict + gives options for :func:`sage.plot.line`. - - ``color`` -- (default: ``None``) if ``"rainbow"``, assign a different color to every maximal cell and - every vertex; otherwise, passed on to :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot`. + - ``color`` -- (default: ``None``) if ``'rainbow'``, assign a different + color to every maximal cell and every vertex; otherwise, passed on to + :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot` - - other keyword arguments are passed on to :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot`. + - other keyword arguments are passed on to + :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/backend_cdd.py b/src/sage/geometry/polyhedron/backend_cdd.py index a333defe55c..07abff41d80 100644 --- a/src/sage/geometry/polyhedron/backend_cdd.py +++ b/src/sage/geometry/polyhedron/backend_cdd.py @@ -34,8 +34,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, verbose=False): INPUT: - ``vertices`` -- list of point. Each point can be specified - as any iterable container of - :meth:`~sage.geometry.polyhedron.base.base_ring` elements. + as any iterable container of + :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - ``rays`` -- list of rays. Each ray can be specified as any iterable container of @@ -45,8 +45,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, verbose=False): any iterable container of :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes EXAMPLES:: @@ -97,8 +97,8 @@ def _init_from_Hrepresentation(self, ieqs, eqns, verbose=False): as any iterable container of :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes EXAMPLES:: @@ -193,7 +193,6 @@ def _parse_block(cls, cddout, header, parser): sage: Polyhedron_cdd._parse_block(cddout, 'HEADER', parser) INTRO: [['intro', '0', '1', '2']] DATA: [['data', '0', '1', '2'], ['data', '3', '4', '5']] - """ try: block = cddout[cddout.index(header)+1:] @@ -407,16 +406,16 @@ def parse_incidence_matrix(intro, data): class Polyhedron_QQ_cdd(Polyhedron_cdd, Polyhedron_QQ): """ - Polyhedra over QQ with cdd + Polyhedra over QQ with cdd. INPUT: - ``parent`` -- the parent, an instance of - :class:`~sage.geometry.polyhedron.parent.Polyhedra`. + :class:`~sage.geometry.polyhedron.parent.Polyhedra` - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/backend_cdd_rdf.py b/src/sage/geometry/polyhedron/backend_cdd_rdf.py index 72def8849ad..985cad14419 100644 --- a/src/sage/geometry/polyhedron/backend_cdd_rdf.py +++ b/src/sage/geometry/polyhedron/backend_cdd_rdf.py @@ -22,15 +22,15 @@ class Polyhedron_RDF_cdd(Polyhedron_cdd, Polyhedron_RDF): """ - Polyhedra over RDF with cdd + Polyhedra over RDF with cdd. INPUT: - - ``ambient_dim`` -- integer. The dimension of the ambient space. + - ``ambient_dim`` -- integer; the dimension of the ambient space - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/backend_field.py b/src/sage/geometry/polyhedron/backend_field.py index 7026cca98b8..ebed490d7af 100644 --- a/src/sage/geometry/polyhedron/backend_field.py +++ b/src/sage/geometry/polyhedron/backend_field.py @@ -37,13 +37,13 @@ class Polyhedron_field(Polyhedron_base): """ - Polyhedra over all fields supported by Sage + Polyhedra over all fields supported by Sage. INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: @@ -79,11 +79,9 @@ def _is_zero(self, x): INPUT: - - ``x`` -- a number in the base ring. + - ``x`` -- a number in the base ring - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -101,11 +99,9 @@ def _is_nonneg(self, x): INPUT: - - ``x`` -- a number in the base ring. - - OUTPUT: + - ``x`` -- a number in the base ring - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -123,11 +119,9 @@ def _is_positive(self, x): INPUT: - - ``x`` -- a number in the base ring. - - OUTPUT: + - ``x`` -- a number in the base ring - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -173,21 +167,21 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, INPUT: - - ``vertices`` -- list of points. Each point can be specified - as any iterable container of ``internal_base_ring`` elements. + - ``vertices`` -- list of points; each point can be specified + as any iterable container of ``internal_base_ring`` elements - - ``rays`` -- list of rays. Each ray can be specified as any - iterable container of ``internal_base_ring`` elements. + - ``rays`` -- list of rays; each ray can be specified as any + iterable container of ``internal_base_ring`` elements - - ``lines`` -- list of lines. Each line can be specified asinternal_base_ring - any iterable container of ``internal_base_ring`` elements. + - ``lines`` -- list of lines; each line can be specified asinternal_base_ring + any iterable container of ``internal_base_ring`` elements - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes - - ``internal_base_ring`` -- the base ring of the generators' components. - Default is ``None``, in which case, it is set to - :meth:`~sage.geometry.polyhedron.base.base_ring`. + - ``internal_base_ring`` -- the base ring of the generators' components; + default is ``None``, in which case, it is set to + :meth:`~sage.geometry.polyhedron.base.base_ring` EXAMPLES:: @@ -212,18 +206,18 @@ def _init_from_Hrepresentation(self, ieqs, eqns, INPUT: - - ``ieqs`` -- list of inequalities. Each line can be specified - as any iterable container of ``internal_base_ring`` elements. + - ``ieqs`` -- list of inequalities; each line can be specified + as any iterable container of ``internal_base_ring`` elements - - ``eqns`` -- list of equalities. Each line can be specified - as any iterable container of ``internal_base_ring`` elements. + - ``eqns`` -- list of equalities; each line can be specified + as any iterable container of ``internal_base_ring`` elements - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes - - ``internal_base_ring`` -- the base ring of the generators' components. - Default is ``None``, in which case, it is set to - :meth:`~sage.geometry.polyhedron.base.base_ring`. + - ``internal_base_ring`` -- the base ring of the generators' components; + default is ``None``, in which case, it is set to + :meth:`~sage.geometry.polyhedron.base.base_ring` TESTS:: @@ -335,7 +329,7 @@ def _init_Hrepresentation_backend(self, Hrep): def _init_empty_polyhedron(self): """ - Initializes an empty polyhedron. + Initialize an empty polyhedron. TESTS:: diff --git a/src/sage/geometry/polyhedron/backend_normaliz.py b/src/sage/geometry/polyhedron/backend_normaliz.py index 29b914531c4..e52461a08b7 100644 --- a/src/sage/geometry/polyhedron/backend_normaliz.py +++ b/src/sage/geometry/polyhedron/backend_normaliz.py @@ -68,18 +68,18 @@ def _format_function_call(fn_name, *v, **k): ######################################################################### class Polyhedron_normaliz(Polyhedron_base_number_field): """ - Polyhedra with normaliz + Polyhedra with normaliz. INPUT: - ``parent`` -- :class:`~sage.geometry.polyhedron.parent.Polyhedra` the parent - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``; the + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None``; the V-representation of the polyhedron; if ``None``, the polyhedron is determined by the H-representation - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``; the + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None``; the H-representation of the polyhedron; if ``None``, the polyhedron is determined by the V-representation @@ -200,7 +200,6 @@ class Polyhedron_normaliz(Polyhedron_base_number_field): the convex hull of 2 vertices sage: P.vertices() # needs sage.rings.number_field sage.symbolic (A vertex at (2^(1/3)), A vertex at (sqrt(2))) - """ def __init__(self, parent, Vrep, Hrep, normaliz_cone=None, normaliz_data=None, internal_base_ring=None, **kwds): """ @@ -428,9 +427,7 @@ def _is_zero(self, x) -> bool: - ``x`` -- a number in the base ring - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -450,9 +447,7 @@ def _is_nonneg(self, x) -> bool: - ``x`` -- a number in the base ring - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -472,9 +467,7 @@ def _is_positive(self, x) -> bool: - ``x`` -- a number in the base ring - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -1038,9 +1031,9 @@ def _make_normaliz_cone(data, verbose=False): INPUT: - - ``data`` -- a dictionary + - ``data`` -- dictionary - - ``verbose`` -- a boolean (default: ``False``) + - ``verbose`` -- boolean (default: ``False``) TESTS:: @@ -1061,9 +1054,7 @@ def _get_nmzcone_data(self) -> dict: r""" Get the data necessary to reproduce the normaliz cone. - OUTPUT: - - - ``data`` -- a dictionary. + OUTPUT: ``data`` -- dictionary TESTS: @@ -1105,9 +1096,9 @@ def _normaliz_format(self, data, file_output=None): INPUT: - - ``data`` -- a dictionary of PyNormaliz cone input properties + - ``data`` -- dictionary of PyNormaliz cone input properties - - ``file_output`` (string; optional) -- a filename to which the + - ``file_output`` -- string (optional); a filename to which the representation should be written. If set to ``None`` (default), representation is returned as a string. @@ -1353,7 +1344,7 @@ def _h_star_vector_normaliz(self) -> list: INPUT: - - ``self`` -- A lattice polytope with backend ``'normaliz'``. + - ``self`` -- a lattice polytope with backend ``'normaliz'`` OUTPUT: @@ -1623,8 +1614,8 @@ class Polyhedron_QQ_normaliz(Polyhedron_normaliz, Polyhedron_QQ): INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None`` + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: @@ -1647,9 +1638,7 @@ def ehrhart_series(self, variable='t'): - ``variable`` -- string (default: ``'t'``) - OUTPUT: - - A rational function. + OUTPUT: a rational function EXAMPLES:: @@ -1737,9 +1726,7 @@ def _ehrhart_quasipolynomial_normaliz(self, variable='t'): - ``variable`` -- string (default: ``'t'``) - OUTPUT: - - A polynomial or tuple of polynomials. + OUTPUT: a polynomial or tuple of polynomials EXAMPLES:: @@ -1810,9 +1797,7 @@ def hilbert_series(self, grading, variable='t'): - ``variable`` -- string (default: ``'t'``) - OUTPUT: - - A rational function. + OUTPUT: a rational function EXAMPLES:: @@ -1905,7 +1890,7 @@ def integral_points(self, threshold=10000) -> tuple: OUTPUT: The list of integral points in the polyhedron. If the - polyhedron is not compact, a :class:`ValueError` is raised. + polyhedron is not compact, a :exc:`ValueError` is raised. EXAMPLES:: @@ -2121,7 +2106,7 @@ def integral_points_generators(self): Return the integral points generators of the polyhedron. Every integral point in the polyhedron can be written as a (unique) - non-negative linear combination of integral points contained in the three + nonnegative linear combination of integral points contained in the three defining parts of the polyhedron: the integral points (the compact part), the recession cone, and the lineality space. @@ -2216,7 +2201,6 @@ class functions. There are several output options to see the intermediary outputs of the function. - EXAMPLES: The `H^*`-polynomial of the standard `d-1` dimensional simplex @@ -2374,7 +2358,7 @@ def _Hstar_as_rat_fct(self, initial_Hstar): INPUT: - - ``initial_Hstar`` -- a vector of rational functions in `t`. + - ``initial_Hstar`` -- a vector of rational functions in `t` OUTPUT: @@ -2441,21 +2425,19 @@ def _is_effective_normaliz(self, Hstar, Hstar_as_lin_comb): coefficient of each `t^i` is an effective character in the ring of class functions of the acting group. A character `\rho` is effective if the coefficients of the irreducible representations in the expression - of `\rho` are non-negative integers. + of `\rho` are nonnegative integers. INPUT: - ``Hstar`` -- a rational function in `t` with coefficients in the ring - of class functions. + of class functions - ``Hstar_as_lin_comb`` -- vector. The coefficients of the irreducible representations of the acting group in the expression of ``Hstar`` as a linear combination of irreducible representations with coefficients in the field of rational functions in `t`. - OUTPUT: - - Boolean. Whether the ``Hstar`` series is effective. + OUTPUT: boolean; whether the ``Hstar`` series is effective EXAMPLES: @@ -2507,8 +2489,8 @@ class Polyhedron_ZZ_normaliz(Polyhedron_QQ_normaliz, Polyhedron_ZZ): INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None`` + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/backend_number_field.py b/src/sage/geometry/polyhedron/backend_number_field.py index e79688bea5f..5a8b8d285a0 100644 --- a/src/sage/geometry/polyhedron/backend_number_field.py +++ b/src/sage/geometry/polyhedron/backend_number_field.py @@ -26,16 +26,16 @@ class Polyhedron_number_field(Polyhedron_field, Polyhedron_base_number_field): r""" - Polyhedra whose data can be converted to number field elements + Polyhedra whose data can be converted to number field elements. All computations are done internally using a fixed real embedded number field, which is determined automatically. INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: @@ -97,8 +97,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, INPUT: - ``vertices`` -- list of points. Each point can be specified - as any iterable container of - :meth:`~sage.geometry.polyhedron.base.base_ring` elements. + as any iterable container of + :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - ``rays`` -- list of rays. Each ray can be specified as any iterable container of @@ -108,8 +108,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, any iterable container of :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes EXAMPLES:: @@ -150,8 +150,8 @@ def _init_from_Hrepresentation(self, ieqs, eqns, minimize=True, verbose=False): as any iterable container of :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes TESTS:: diff --git a/src/sage/geometry/polyhedron/backend_polymake.py b/src/sage/geometry/polyhedron/backend_polymake.py index 0c19d8b5c91..f461b041bae 100644 --- a/src/sage/geometry/polyhedron/backend_polymake.py +++ b/src/sage/geometry/polyhedron/backend_polymake.py @@ -33,20 +33,20 @@ ######################################################################### class Polyhedron_polymake(Polyhedron_base): """ - Polyhedra with polymake + Polyhedra with polymake. INPUT: - ``parent`` -- :class:`~sage.geometry.polyhedron.parent.Polyhedra` the parent - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``; the - V-representation of the polyhedron; if ``None``, the polyhedron - is determined by the H-representation + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None``; the + V-representation of the polyhedron. If ``None``, the polyhedron + is determined by the H-representation. - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``; the - H-representation of the polyhedron; if ``None``, the polyhedron - is determined by the V-representation + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None``; the + H-representation of the polyhedron. If ``None``, the polyhedron + is determined by the V-representation. - ``polymake_polytope`` -- a polymake polytope object @@ -133,7 +133,6 @@ class Polyhedron_polymake(Polyhedron_base): ....: backend='polymake') sage: p.n_lines() # optional - jupymake 1 - """ def _is_zero(self, x): @@ -142,11 +141,9 @@ def _is_zero(self, x): INPUT: - - ``x`` -- a number in the base ring. - - OUTPUT: + - ``x`` -- a number in the base ring - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -164,11 +161,9 @@ def _is_nonneg(self, x): INPUT: - - ``x`` -- a number in the base ring. - - OUTPUT: + - ``x`` -- a number in the base ring - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -186,11 +181,9 @@ def _is_positive(self, x): INPUT: - - ``x`` -- a number in the base ring. + - ``x`` -- a number in the base ring - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -204,7 +197,7 @@ def _is_positive(self, x): def __init__(self, parent, Vrep, Hrep, polymake_polytope=None, **kwds): """ - Initializes the polyhedron. + Initialize the polyhedron. See :class:`Polyhedron_polymake` for a description of the input data. @@ -266,8 +259,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, minimize=True, verbo INPUT: - ``vertices`` -- list of points; each point can be specified - as any iterable container of - :meth:`~sage.geometry.polyhedron.base.base_ring` elements + as any iterable container of + :meth:`~sage.geometry.polyhedron.base.base_ring` elements - ``rays`` -- list of rays; each ray can be specified as any iterable container of @@ -299,8 +292,8 @@ def _polymake_Vrepresentation_data(self, vertices, rays, lines, minimal=False): INPUT: - ``vertices`` -- list of points; each point can be specified - as any iterable container of - :meth:`~sage.geometry.polyhedron.base.base_ring` elements + as any iterable container of + :meth:`~sage.geometry.polyhedron.base.base_ring` elements - ``rays`` -- list of rays; each ray can be specified as any iterable container of @@ -492,7 +485,6 @@ def _init_Vrepresentation_from_polymake(self): An inequality (-5, 12) x + 10 >= 0} sage: set(p.Vrepresentation()) # optional - jupymake {A vertex at (0, 1/2), A vertex at (2, 0), A vertex at (4, 5/6)} - """ self._Vrepresentation = [] parent = self.parent() @@ -527,7 +519,6 @@ def _init_Hrepresentation_from_polymake(self): An inequality (-5, 12) x + 10 >= 0} sage: set(p.Vrepresentation()) # optional - jupymake {A vertex at (0, 1/2), A vertex at (2, 0), A vertex at (4, 5/6)} - """ p = self._polymake_polytope if not p.FEASIBLE: @@ -548,7 +539,7 @@ def _init_Hrepresentation_from_polymake(self): @classmethod def _from_polymake_polytope(cls, parent, polymake_polytope): r""" - Initializes a polyhedron from a polymake Polytope object. + Initialize a polyhedron from a polymake Polytope object. TESTS:: @@ -739,8 +730,8 @@ class Polyhedron_QQ_polymake(Polyhedron_polymake, Polyhedron_QQ): INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None`` + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: @@ -759,8 +750,8 @@ class Polyhedron_ZZ_polymake(Polyhedron_polymake, Polyhedron_ZZ): INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None`` + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/backend_ppl.py b/src/sage/geometry/polyhedron/backend_ppl.py index bb1a77e9f5d..c930039886b 100644 --- a/src/sage/geometry/polyhedron/backend_ppl.py +++ b/src/sage/geometry/polyhedron/backend_ppl.py @@ -16,19 +16,19 @@ from sage.features import PythonModule lazy_import('ppl', ['C_Polyhedron', 'Generator_System', 'Constraint_System', 'Linear_Expression', 'line', 'ray', 'point'], - feature=PythonModule("ppl", spkg="pplpy", type="standard")) + feature=PythonModule("ppl", spkg='pplpy', type='standard')) ######################################################################### class Polyhedron_ppl(Polyhedron_mutable): """ - Polyhedra with ppl + Polyhedra with ppl. INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: @@ -41,7 +41,7 @@ class Polyhedron_ppl(Polyhedron_mutable): def __init__(self, parent, Vrep, Hrep, ppl_polyhedron=None, mutable=False, **kwds): """ - Initializes the polyhedron. + Initialize the polyhedron. See :class:`Polyhedron_ppl` for a description of the input data. @@ -76,8 +76,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, minimize=True, verbo INPUT: - ``vertices`` -- list of point. Each point can be specified - as any iterable container of - :meth:`~sage.geometry.polyhedron.base.base_ring` elements. + as any iterable container of + :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - ``rays`` -- list of rays. Each ray can be specified as any iterable container of @@ -87,8 +87,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, minimize=True, verbo any iterable container of :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes EXAMPLES:: @@ -117,8 +117,8 @@ def _init_from_Hrepresentation(self, ieqs, eqns, minimize=True, verbose=False): as any iterable container of :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - - ``verbose`` -- boolean (default: ``False``). Whether to print - verbose output for debugging purposes. + - ``verbose`` -- boolean (default: ``False``); whether to print + verbose output for debugging purposes EXAMPLES:: @@ -391,7 +391,7 @@ def Hrepresentation(self, index=None): def _init_empty_polyhedron(self): """ - Initializes an empty polyhedron. + Initialize an empty polyhedron. TESTS:: @@ -415,9 +415,10 @@ def _convert_generator_to_ppl(v, typ): INPUT: - - ``v`` -- a vertex, ray, or line. + - ``v`` -- a vertex, ray, or line - - ``typ`` -- integer according to `:sage:`~sage.geometry.polyhedron.representation.LINE` etc. + - ``typ`` -- integer according to + `:sage:`~sage.geometry.polyhedron.representation.LINE` etc. EXAMPLES:: @@ -488,9 +489,10 @@ def _convert_constraint_to_ppl(c, typ): INPUT: - - ``c`` -- an inequality or equation. + - ``c`` -- an inequality or equation - - ``typ`` -- integer according to `:sage:`~sage.geometry.polyhedron.representation.INEQUALITY` etc. + - ``typ`` -- integer according to + `:sage:`~sage.geometry.polyhedron.representation.INEQUALITY` etc. EXAMPLES:: @@ -542,13 +544,13 @@ def _convert_constraints_to_ppl(ieqs, eqns): ######################################################################### class Polyhedron_QQ_ppl(Polyhedron_ppl, Polyhedron_QQ): r""" - Polyhedra over `\QQ` with ppl + Polyhedra over `\QQ` with ppl. INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: @@ -562,13 +564,13 @@ class Polyhedron_QQ_ppl(Polyhedron_ppl, Polyhedron_QQ): ######################################################################### class Polyhedron_ZZ_ppl(Polyhedron_ppl, Polyhedron_ZZ): r""" - Polyhedra over `\ZZ` with ppl + Polyhedra over `\ZZ` with ppl. INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/base.py b/src/sage/geometry/polyhedron/base.py index 67ac7d9ec9e..4261b13a292 100644 --- a/src/sage/geometry/polyhedron/base.py +++ b/src/sage/geometry/polyhedron/base.py @@ -64,11 +64,9 @@ def is_Polyhedron(X): INPUT: - - ``X`` -- anything. + - ``X`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -90,24 +88,24 @@ def is_Polyhedron(X): ######################################################################### class Polyhedron_base(Polyhedron_base7): """ - Base class for Polyhedron objects + Base class for Polyhedron objects. INPUT: - ``parent`` -- the parent, an instance of - :class:`~sage.geometry.polyhedron.parent.Polyhedra`. + :class:`~sage.geometry.polyhedron.parent.Polyhedra` - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. The - V-representation of the polyhedron. If ``None``, the polyhedron - is determined by the H-representation. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None``. The + V-representation of the polyhedron; if ``None``, the polyhedron + is determined by the H-representation - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. The - H-representation of the polyhedron. If ``None``, the polyhedron - is determined by the V-representation. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None``. The + H-representation of the polyhedron; if ``None``, the polyhedron + is determined by the V-representation - - ``Vrep_minimal`` (optional) -- see below + - ``Vrep_minimal`` -- (optional) see below - - ``Hrep_minimal`` (optional) -- see below + - ``Hrep_minimal`` -- (optional) see below - ``pref_rep`` -- string (default: ``None``); one of ``Vrep`` or ``Hrep`` to pick this in case the backend @@ -199,7 +197,7 @@ def to_linear_program(self, solver=None, return_variable=False, base_ring=None): - ``solver`` -- select a solver (MIP backend). See the documentation of for :class:`MixedIntegerLinearProgram`. Set to ``None`` by default. - - ``return_variable`` -- (default: ``False``) If ``True``, return a tuple + - ``return_variable`` -- boolean (default: ``False``); if ``True``, return a tuple ``(p, x)``, where ``p`` is the :class:`MixedIntegerLinearProgram` object and ``x`` is the vector-valued MIP variable in this problem, indexed from 0. If ``False``, only return ``p``. @@ -382,7 +380,7 @@ def center(self): OUTPUT: The center of the polyhedron. All rays and lines are - ignored. Raises a ``ZeroDivisionError`` for the empty + ignored. Raises a :exc:`ZeroDivisionError` for the empty polytope. EXAMPLES:: @@ -459,12 +457,10 @@ def is_inscribed(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) boolean; specifies whether to - return the circumcenter, if found. - - OUTPUT: + - ``certificate`` -- boolean (default: ``False``); specifies whether to + return the circumcenter, if found - If ``certificate`` is true, returns a tuple containing: + OUTPUT: if ``certificate`` is true, returns a tuple containing: 1. Boolean. 2. The circumcenter of the polytope or None. @@ -798,10 +794,8 @@ def is_minkowski_summand(self, Y): See :meth:`~sage.geometry.polyhedron.base5.Polyhedron_base5.minkowski_sum`. - OUTPUT: - - Boolean. Whether there exists another polyhedron `Z` such that - ``self`` can be written as `Y\oplus Z`. + OUTPUT: boolean; whether there exists another polyhedron `Z` such that + ``self`` can be written as `Y\oplus Z` EXAMPLES:: @@ -849,9 +843,7 @@ def barycentric_subdivision(self, subdivision_frac=None): the value should be smaller than `\frac{1}{2}`. The subdivision is computed on the polar polyhedron. - OUTPUT: - - A Polyhedron object, subdivided as described above. + OUTPUT: a Polyhedron object, subdivided as described above EXAMPLES:: @@ -958,13 +950,13 @@ def permutations_to_matrices(self, conj_class_reps, acting_group=None, additiona INPUT: - - ``conj_class_reps`` -- list. A list of representatives of the - conjugacy classes of the ``acting_group``. + - ``conj_class_reps`` -- list; a list of representatives of the + conjugacy classes of the ``acting_group`` - ``acting_group`` -- a subgroup of polytope's - :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.restricted_automorphism_group`. + :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.restricted_automorphism_group` - - ``additional_elts`` -- list (default=None). A subset of the + - ``additional_elts`` -- list (default: ``None``); a subset of the :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.restricted_automorphism_group` of the polytope expressed as permutations. @@ -1052,12 +1044,12 @@ def bounding_box(self, integral=False, integral_hull=False): INPUT: - - ``integral`` -- Boolean (default: ``False``). Whether to - only allow integral coordinates in the bounding box. + - ``integral`` -- boolean (default: ``False``); whether to + only allow integral coordinates in the bounding box - - ``integral_hull`` -- Boolean (default: ``False``). If ``True``, return a + - ``integral_hull`` -- boolean (default: ``False``); if ``True``, return a box containing the integral points of the polytope, or ``None, None`` if it - is known that the polytope has no integral points. + is known that the polytope has no integral points OUTPUT: @@ -1192,7 +1184,6 @@ def _polymake_init_(self): Polytope[...] sage: sorted(PP.VERTICES[:], key=repr)[0] 1 -0.472135955 0 -1.236067978 - """ from sage.interfaces.polymake import polymake polymake_field = polymake(self.base_ring().fraction_field()) diff --git a/src/sage/geometry/polyhedron/base0.py b/src/sage/geometry/polyhedron/base0.py index b2e2ece5467..7ba3007ea35 100644 --- a/src/sage/geometry/polyhedron/base0.py +++ b/src/sage/geometry/polyhedron/base0.py @@ -72,7 +72,7 @@ class Polyhedron_base0(Element, sage.geometry.abc.Polyhedron): """ def __init__(self, parent, Vrep, Hrep, Vrep_minimal=None, Hrep_minimal=None, pref_rep=None, mutable=False, **kwds): """ - Initializes the polyhedron. + Initialize the polyhedron. See :class:`sage.geometry.polyhedron.base.Polyhedron_base` for a description of the input data. @@ -188,8 +188,8 @@ def _init_from_Vrepresentation(self, vertices, rays, lines, **kwds): INPUT: - ``vertices`` -- list of point. Each point can be specified - as any iterable container of - :meth:`~sage.geometry.polyhedron.base.base_ring` elements. + as any iterable container of + :meth:`~sage.geometry.polyhedron.base.base_ring` elements. - ``rays`` -- list of rays. Each ray can be specified as any iterable container of @@ -236,7 +236,7 @@ def _init_from_Hrepresentation(self, ieqs, eqns, **kwds): def _init_empty_polyhedron(self): """ - Initializes an empty polyhedron. + Initialize an empty polyhedron. TESTS:: @@ -339,14 +339,12 @@ def base_extend(self, base_ring, backend=None): - ``base_ring`` -- the new base ring - ``backend`` -- the new backend, see - :func:`~sage.geometry.polyhedron.constructor.Polyhedron`. + :func:`~sage.geometry.polyhedron.constructor.Polyhedron` If ``None`` (the default), attempt to keep the same backend. Otherwise, use the same defaulting behavior as described there. - OUTPUT: - - The same polyhedron, but over a larger base ring and possibly with a changed backend. + OUTPUT: the same polyhedron, but over a larger base ring and possibly with a changed backend EXAMPLES:: @@ -364,7 +362,6 @@ def base_extend(self, base_ring, backend=None): sage: Q = P.base_extend(ZZ, backend='field') sage: Q.backend() 'field' - """ new_parent = self.parent().base_extend(base_ring, backend) return new_parent(self, copy=True) @@ -450,7 +447,7 @@ def change_ring(self, base_ring, backend=None): def is_mutable(self): r""" - Return True if the polyhedron is mutable, i.e. it can be modified in place. + Return ``True`` if the polyhedron is mutable, i.e. it can be modified in place. EXAMPLES:: @@ -462,7 +459,7 @@ def is_mutable(self): def is_immutable(self): r""" - Return True if the polyhedron is immutable, i.e. it cannot be modified in place. + Return ``True`` if the polyhedron is immutable, i.e. it cannot be modified in place. EXAMPLES:: @@ -623,14 +620,14 @@ def Hrepresentation_str(self, separator='\n', latex=False, style='>=', align=Non INPUT: - - ``separator`` -- a string. Default is ``"\n"``. + - ``separator`` -- string (default: ``'\n'``) - - ``latex`` -- a boolean. Default is ``False``. + - ``latex`` -- boolean (default: ``False``) - - ``style`` -- either ``"positive"`` (making all coefficients positive) - or ``"<="``, or ``">="``. Default is ``">="``. + - ``style`` -- either ``'positive'`` (making all coefficients positive) + or ``'<='``, or ``'>='``; default is ``'>='`` - - ``align`` -- a boolean or ``None''. Default is ``None`` in which case + - ``align`` -- boolean or ``None''; default is ``None`` in which case ``align`` is ``True`` if ``separator`` is the newline character. If set, then the lines of the output string are aligned by the comparison symbol by padding blanks. @@ -639,13 +636,11 @@ def Hrepresentation_str(self, separator='\n', latex=False, style='>=', align=Non :meth:`~sage.geometry.polyhedron.representation.Hrepresentation.repr_pretty` are passed on: - - ``prefix`` -- a string + - ``prefix`` -- string - - ``indices`` -- a tuple or other iterable + - ``indices`` -- tuple or other iterable - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -761,9 +756,7 @@ def n_Hrepresentation(self): Return the number of objects that make up the H-representation of the polyhedron. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -814,9 +807,7 @@ def n_Vrepresentation(self): Return the number of objects that make up the V-representation of the polyhedron. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -849,9 +840,7 @@ def inequality_generator(self): Return a generator for the defining inequalities of the polyhedron. - OUTPUT: - - A generator of the inequality Hrepresentation objects. + OUTPUT: a generator of the inequality Hrepresentation objects EXAMPLES:: @@ -876,9 +865,7 @@ def inequalities(self): """ Return all inequalities. - OUTPUT: - - A tuple of inequalities. + OUTPUT: a tuple of inequalities EXAMPLES:: @@ -947,9 +934,7 @@ def equations(self): """ Return all linear constraints of the polyhedron. - OUTPUT: - - A tuple of equations. + OUTPUT: a tuple of equations EXAMPLES:: @@ -1065,9 +1050,7 @@ def vertices(self): """ Return all vertices of the polyhedron. - OUTPUT: - - A tuple of vertices. + OUTPUT: a tuple of vertices .. WARNING:: @@ -1102,14 +1085,14 @@ def vertices_matrix(self, base_ring=None): INPUT: - - ``base_ring`` -- A ring or ``None`` (default). The base ring + - ``base_ring`` -- a ring or ``None`` (default); the base ring of the returned matrix. If not specified, the base ring of the polyhedron is used. OUTPUT: A matrix over ``base_ring`` whose columns are the coordinates - of the vertices. A ``TypeError`` is raised if the coordinates + of the vertices. A :exc:`TypeError` is raised if the coordinates cannot be converted to ``base_ring``. .. WARNING:: @@ -1178,9 +1161,7 @@ def rays(self): """ Return a list of rays of the polyhedron. - OUTPUT: - - A tuple of rays. + OUTPUT: a tuple of rays EXAMPLES:: @@ -1202,9 +1183,7 @@ def rays_list(self): :meth:`ray_generator` instead to iterate over the list of :class:`~sage.geometry.polyhedron.representation.Ray` objects. - OUTPUT: - - A list of rays as lists of coordinates. + OUTPUT: list of rays as lists of coordinates EXAMPLES:: @@ -1235,9 +1214,7 @@ def lines(self): """ Return all lines of the polyhedron. - OUTPUT: - - A tuple of lines. + OUTPUT: a tuple of lines EXAMPLES:: @@ -1336,7 +1313,7 @@ def cdd_Hrepresentation(self): :meth:`write_cdd_Hrepresentation` -- export the polyhedron as a H-representation to a file. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -1382,7 +1359,7 @@ def write_cdd_Hrepresentation(self, filename): INPUT: - - ``filename`` -- the output file. + - ``filename`` -- the output file .. SEEALSO:: @@ -1408,7 +1385,7 @@ def cdd_Vrepresentation(self): :meth:`write_cdd_Vrepresentation` -- export the polyhedron as a V-representation to a file. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -1446,7 +1423,7 @@ def write_cdd_Vrepresentation(self, filename): INPUT: - - ``filename`` -- the output file. + - ``filename`` -- the output file .. SEEALSO:: diff --git a/src/sage/geometry/polyhedron/base1.py b/src/sage/geometry/polyhedron/base1.py index 507316f26a3..40a94c1b2d7 100644 --- a/src/sage/geometry/polyhedron/base1.py +++ b/src/sage/geometry/polyhedron/base1.py @@ -243,9 +243,7 @@ def _is_subpolyhedron(self, other): - ``other`` -- a :class:`Polyhedron` - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -262,11 +260,9 @@ def _is_subpolyhedron(self, other): def is_empty(self): """ - Test whether the polyhedron is the empty polyhedron - - OUTPUT: + Test whether the polyhedron is the empty polyhedron. - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -289,11 +285,9 @@ def is_empty(self): def is_universe(self): """ - Test whether the polyhedron is the whole ambient space - - OUTPUT: + Test whether the polyhedron is the whole ambient space. - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -318,9 +312,7 @@ def dim(self): """ Return the dimension of the polyhedron. - OUTPUT: - - -1 if the polyhedron is empty, otherwise a non-negative integer. + OUTPUT: -1 if the polyhedron is empty, otherwise a nonnegative integer EXAMPLES:: @@ -351,9 +343,7 @@ def Vrepresentation_space(self): r""" Return the ambient free module. - OUTPUT: - - A free module over the base ring of dimension :meth:`ambient_dim`. + OUTPUT: a free module over the base ring of dimension :meth:`ambient_dim` EXAMPLES:: @@ -369,9 +359,7 @@ def Hrepresentation_space(self): r""" Return the linear space containing the H-representation vectors. - OUTPUT: - - A free module over the base ring of dimension :meth:`ambient_dim` + 1. + OUTPUT: a free module over the base ring of dimension :meth:`ambient_dim` + 1 EXAMPLES:: @@ -392,7 +380,7 @@ def ambient_vector_space(self, base_field=None): INPUT: - - ``base_field`` -- (default: the fraction field of the base ring) a field. + - ``base_field`` -- a field (default: the fraction field of the base ring) EXAMPLES:: @@ -599,9 +587,7 @@ def contains(self, point): - ``point`` -- coordinates of a point (an iterable) - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -731,9 +717,7 @@ def interior_contains(self, point): - ``point`` -- coordinates of a point - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -783,9 +767,7 @@ def is_relatively_open(self): r""" Return whether ``self`` is relatively open. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -808,7 +790,6 @@ def is_relatively_open(self): A 1-dimensional polyhedron in QQ^2 defined as the convex hull of 1 vertex and 1 line sage: Line.is_relatively_open() True - """ return not self.inequalities() @@ -857,9 +838,7 @@ def relative_interior_contains(self, point): - ``point`` -- coordinates of a point - OUTPUT: - - ``True`` or ``False`` + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/base2.py b/src/sage/geometry/polyhedron/base2.py index 3b72b5088c7..f9a48e45b1c 100644 --- a/src/sage/geometry/polyhedron/base2.py +++ b/src/sage/geometry/polyhedron/base2.py @@ -111,10 +111,10 @@ def lattice_polytope(self, envelope=False): INPUT: - - ``envelope`` -- boolean (default: ``False``). If the + - ``envelope`` -- boolean (default: ``False``); if the polyhedron has non-integral vertices, this option decides whether to return a strictly larger lattice polytope or - raise a ``ValueError``. This option has no effect if the + raise a :exc:`ValueError`. This option has no effect if the polyhedron has already integral vertices. OUTPUT: @@ -126,11 +126,11 @@ def lattice_polytope(self, envelope=False): but has at least one non-integral vertex, a strictly larger lattice polytope is returned. - If the polyhedron is not compact, a ``NotImplementedError`` is + If the polyhedron is not compact, a :exc:`NotImplementedError` is raised. If the polyhedron is not integral and ``envelope=False``, a - ``ValueError`` is raised. + :exc:`ValueError` is raised. ALGORITHM: @@ -204,7 +204,7 @@ def _integral_points_PALP(self): OUTPUT: The list of integral points in the polyhedron. If the - polyhedron is not compact, a ``ValueError`` is raised. + polyhedron is not compact, a :exc:`ValueError` is raised. EXAMPLES:: @@ -245,13 +245,13 @@ def h_star_vector(self): INPUT: - - ``self`` -- A lattice polytope. + - ``self`` -- a lattice polytope OUTPUT: A list whose entries give the `h^*`-vector. - .. NOTE: + .. NOTE:: The backend of ``self`` should be ``'normaliz'``. This function depends on Normaliz (i.e. the ``'pynormaliz'`` optional @@ -321,15 +321,15 @@ def _h_star_vector_normaliz(self): INPUT: - - ``self`` -- A lattice polytope. + - ``self`` -- a lattice polytope OUTPUT: The `h^*`-vector as a list. - .. NOTE: + .. NOTE:: - The backend of ``self`` should be ``'normaliz'``. + The backend of ``self`` should be ``'normaliz'``. TESTS:: @@ -379,7 +379,6 @@ def integral_points_count(self, **kwds): Traceback (most recent call last): ... NotImplementedError: ... - """ return len(self.integral_points()) @@ -392,13 +391,13 @@ def integral_points(self, threshold=100000): INPUT: - - ``threshold`` -- integer (default: 100000). Use the naive - algorithm as long as the bounding box is smaller than this. + - ``threshold`` -- integer (default: 100000); use the naive + algorithm as long as the bounding box is smaller than this OUTPUT: The list of integral points in the polyhedron. If the - polyhedron is not compact, a ``ValueError`` is raised. + polyhedron is not compact, a :exc:`ValueError` is raised. EXAMPLES:: @@ -532,21 +531,21 @@ def get_integral_point(self, index, **kwds): However, so long as :meth:`integral_points_count` does not need to enumerate all integral points, neither does this method. Hence it can be significantly faster. If the polyhedron is not compact, a - ``ValueError`` is raised. + :exc:`ValueError` is raised. INPUT: - - ``index`` -- integer. The index of the integral point to be found. If - this is not in [0, ``self.integral_point_count()``), an ``IndexError`` + - ``index`` -- integer; the index of the integral point to be found. If + this is not in [0, ``self.integral_point_count()``), an :exc:`IndexError` is raised. - ``**kwds`` -- optional keyword parameters that are passed to - :meth:`integral_points_count`. + :meth:`integral_points_count` ALGORITHM: The function computes each of the components of the requested point in - turn. To compute x_i, the ith component, it bisects the upper and lower + turn. To compute x_i, the `i`-th component, it bisects the upper and lower bounds on x_i given by the bounding box. At each bisection, it uses :meth:`integral_points_count` to determine on which side of the bisecting hyperplane the requested point lies. @@ -627,12 +626,12 @@ def random_integral_point(self, **kwds): INPUT: - ``**kwds`` -- optional keyword parameters that are passed to - :meth:`get_integral_point`. + :meth:`get_integral_point` OUTPUT: The integral point in the polyhedron chosen uniformly at random. If the - polyhedron is not compact, a ``ValueError`` is raised. If the + polyhedron is not compact, a :exc:`ValueError` is raised. If the polyhedron does not contain any integral points, an :class:`~sage.categories.sets_cat.EmptySetError` is raised. @@ -701,7 +700,7 @@ def generating_function_of_integral_points(self, **kwds): The following keyword arguments are passed to :func:`~sage.geometry.polyhedron.generating_function.generating_function_of_integral_points`: - - ``split`` -- (default: ``False``) a boolean or list + - ``split`` -- boolean (default: ``False``) or list - ``split=False`` computes the generating function directly, without any splitting. @@ -732,7 +731,7 @@ def generating_function_of_integral_points(self, **kwds): The variable names of the Laurent polynomial ring of the output are this string followed by an integer. - - ``names`` -- a list or tuple of names (strings), or a comma separated string + - ``names`` -- list or tuple of names (strings), or a comma separated string ``name`` is extracted from ``names``, therefore ``names`` has to contain exactly one variable name, and ``name`` and``names`` cannot be specified @@ -745,12 +744,12 @@ def generating_function_of_integral_points(self, **kwds): :class:`sage.structure.factorization.Factorization` when creating the result. - - ``sort_factors`` -- (default: ``False``) a boolean + - ``sort_factors`` -- boolean (default: ``False``) - If set, then - the factors of the output are sorted such that the numerator is - first and only then all factors of the denominator. It is ensured - that the sorting is always the same; use this for doctesting. + If set, then the factors of the output are sorted such that the + numerator is first and only then all factors of the denominator. It + is ensured that the sorting is always the same; use this for + doctesting. OUTPUT: diff --git a/src/sage/geometry/polyhedron/base3.py b/src/sage/geometry/polyhedron/base3.py index 3b57c4f2055..6347132e0fb 100644 --- a/src/sage/geometry/polyhedron/base3.py +++ b/src/sage/geometry/polyhedron/base3.py @@ -73,7 +73,7 @@ class Polyhedron_base3(Polyhedron_base2): def _init_empty_polyhedron(self): """ - Initializes an empty polyhedron. + Initialize an empty polyhedron. TESTS:: @@ -380,7 +380,7 @@ def face_generator(self, face_dimension=None, algorithm=None): INPUT: - - ``face_dimension`` -- integer (default ``None``), + - ``face_dimension`` -- integer (default: ``None``); yield only faces of this dimension if specified - ``algorithm`` -- string (optional); @@ -610,12 +610,12 @@ def face_generator(self, face_dimension=None, algorithm=None): def faces(self, face_dimension): """ - Return the faces of given dimension + Return the faces of given dimension. INPUT: - - ``face_dimension`` -- integer. The dimension of the faces - whose representation will be returned. + - ``face_dimension`` -- integer; the dimension of the faces + whose representation will be returned OUTPUT: @@ -838,9 +838,7 @@ def bounded_edges(self): """ Return the bounded edges (excluding rays and lines). - OUTPUT: - - A generator for pairs of vertices, one pair per edge. + OUTPUT: a generator for pairs of vertices, one pair per edge EXAMPLES:: @@ -1206,7 +1204,7 @@ def simpliciality(self): def is_simplicial(self): """ - Tests if the polytope is simplicial + Test if the polytope is simplicial. A polytope is simplicial if every facet is a simplex. @@ -1253,9 +1251,7 @@ def is_pyramid(self, certificate=False): to return a vertex of the polytope which is the apex of a pyramid, if found - OUTPUT: - - If ``certificate`` is ``True``, returns a tuple containing: + OUTPUT: if ``certificate`` is ``True``, returns a tuple containing: 1. Boolean. 2. The apex of the pyramid or ``None``. @@ -1303,9 +1299,7 @@ def is_bipyramid(self, certificate=False): to return two vertices of the polytope which are the apices of a bipyramid, if found - OUTPUT: - - If ``certificate`` is ``True``, returns a tuple containing: + OUTPUT: if ``certificate`` is ``True``, returns a tuple containing: 1. Boolean. 2. ``None`` or a tuple containing: @@ -1360,9 +1354,7 @@ def is_prism(self, certificate=False): to return two facets of the polytope which are the bases of a prism, if found - OUTPUT: - - If ``certificate`` is ``True``, returns a tuple containing: + OUTPUT: if ``certificate`` is ``True``, returns a tuple containing: 1. Boolean. 2. ``None`` or a tuple containing: @@ -1500,7 +1492,6 @@ def neighborliness(self): 3 sage: [polytopes.cyclic_polytope(5,n).neighborliness() for n in range(6,10)] [6, 2, 2, 2] - """ return self.combinatorial_polyhedron().neighborliness() @@ -1550,7 +1541,6 @@ def is_neighborly(self, k=None): sage: testpolys = [polytopes.cube(), polytopes.cyclic_polytope(6, 9), polytopes.simplex(6)] sage: [(P.neighborliness() >= P.dim() // 2) == P.is_neighborly() for P in testpolys] [True, True, True] - """ return self.combinatorial_polyhedron().is_neighborly() diff --git a/src/sage/geometry/polyhedron/base4.py b/src/sage/geometry/polyhedron/base4.py index 3f8fe215749..a6fd6dad1ea 100644 --- a/src/sage/geometry/polyhedron/base4.py +++ b/src/sage/geometry/polyhedron/base4.py @@ -218,8 +218,8 @@ def vertex_digraph(self, f, increasing=True): - a vector ; in this case the linear form is obtained by duality using the dot product: ``f(v) = v.dot_product(f)``. - - ``increasing`` -- boolean (default ``True``) whether to orient - edges in the increasing or decreasing direction. + - ``increasing`` -- boolean (default: ``True``); whether to orient + edges in the increasing or decreasing direction By default, an edge is oriented from `v` to `w` if `f(v) \leq f(w)`. @@ -383,7 +383,6 @@ def face_lattice(self): [[()], [(0, 1)]] sage: [[ls.ambient_V_indices() for ls in lss] for lss in Polyhedron(lines=[(1,0)], vertices=[(0,0)]).face_lattice().level_sets()] [[()], [(0, 1)]] - """ from sage.combinat.posets.lattices import FiniteLatticePoset return FiniteLatticePoset(self.hasse_diagram()) @@ -471,12 +470,10 @@ def flag_f_vector(self, *args): INPUT: - - ``args`` -- integers (optional); specify an entry of the + - ``args`` -- integer (optional); specify an entry of the flag-f-vector; must be an increasing sequence of integers - OUTPUT: - - - a dictionary, if no arguments were given + OUTPUT: a dictionary, if no arguments were given - an Integer, if arguments were given @@ -603,7 +600,7 @@ def _flag_f_vector(self): @cached_method def combinatorial_automorphism_group(self, vertex_graph_only=False): """ - Computes the combinatorial automorphism group. + Compute the combinatorial automorphism group. If ``vertex_graph_only`` is ``True``, the automorphism group of the vertex-edge graph of the polyhedron is returned. Otherwise @@ -688,7 +685,6 @@ def combinatorial_automorphism_group(self, vertex_graph_only=False): sage: QG = Q.hasse_diagram().automorphism_group() sage: Q.combinatorial_automorphism_group().is_isomorphic(QG) True - """ if vertex_graph_only: G = self.graph() @@ -697,7 +693,7 @@ def combinatorial_automorphism_group(self, vertex_graph_only=False): return G.automorphism_group(edge_labels=True) @cached_method - def restricted_automorphism_group(self, output="abstract"): + def restricted_automorphism_group(self, output='abstract'): r""" Return the restricted automorphism group. @@ -764,22 +760,22 @@ def restricted_automorphism_group(self, output="abstract"): - ``output`` -- how the group should be represented: - - ``"abstract"`` (default) -- return an abstract permutation - group without further meaning. + - ``'abstract'`` -- default; return an abstract permutation + group without further meaning - - ``"permutation"`` -- return a permutation group on the + - ``'permutation'`` -- return a permutation group on the indices of the polyhedron generators. For example, the permutation ``(0,1)`` would correspond to swapping ``self.Vrepresentation(0)`` and ``self.Vrepresentation(1)``. - - ``"matrix"`` -- return a matrix group representing affine + - ``'matrix'`` -- return a matrix group representing affine transformations. When acting on affine vectors, you should append a `1` to every vector. If the polyhedron is not full dimensional, the returned matrices act as the identity on the orthogonal complement of the affine space spanned by the polyhedron. - - ``"matrixlist"`` -- like ``matrix``, but return the list of + - ``'matrixlist'`` -- like ``matrix``, but return the list of elements of the matrix group. Useful for fields without a good implementation of matrix groups or to avoid the overhead of creating the group. @@ -805,14 +801,14 @@ def restricted_automorphism_group(self, output="abstract"): sage: P = polytopes.cross_polytope(3) sage: P.restricted_automorphism_group() == PermutationGroup([[(3,4)], [(2,3),(4,5)],[(2,5)],[(1,2),(5,6)],[(1,6)]]) True - sage: P.restricted_automorphism_group(output="permutation") == PermutationGroup([[(2,3)],[(1,2),(3,4)],[(1,4)],[(0,1),(4,5)],[(0,5)]]) + sage: P.restricted_automorphism_group(output='permutation') == PermutationGroup([[(2,3)],[(1,2),(3,4)],[(1,4)],[(0,1),(4,5)],[(0,5)]]) True sage: mgens = [[[1,0,0,0],[0,1,0,0],[0,0,-1,0],[0,0,0,1]], [[1,0,0,0],[0,0,1,0],[0,1,0,0],[0,0,0,1]], [[0,1,0,0],[1,0,0,0],[0,0,1,0],[0,0,0,1]]] We test groups for equality in a fool-proof way; they can have different generators, etc:: sage: # needs sage.groups - sage: poly_g = P.restricted_automorphism_group(output="matrix") + sage: poly_g = P.restricted_automorphism_group(output='matrix') sage: matrix_g = MatrixGroup([matrix(QQ,t) for t in mgens]) sage: all(t.matrix() in poly_g for t in matrix_g.gens()) True @@ -838,7 +834,7 @@ def restricted_automorphism_group(self, output="abstract"): sage: P = Polyhedron(rays=[(1,0),(0,1)]) sage: P.Vrepresentation() (A vertex at (0, 0), A ray in the direction (0, 1), A ray in the direction (1, 0)) - sage: P.restricted_automorphism_group(output="permutation") + sage: P.restricted_automorphism_group(output='permutation') Permutation Group with generators [(1,2)] Also, the polyhedron need not be full-dimensional:: @@ -847,7 +843,7 @@ def restricted_automorphism_group(self, output="abstract"): sage: P = Polyhedron(vertices=[(1,2,3,4,5),(7,8,9,10,11)]) sage: P.restricted_automorphism_group() Permutation Group with generators [(1,2)] - sage: G = P.restricted_automorphism_group(output="matrixlist"); G + sage: G = P.restricted_automorphism_group(output='matrixlist'); G ( [1 0 0 0 0 0] [ -87/55 -82/55 -2/5 38/55 98/55 12/11] [0 1 0 0 0 0] [-142/55 -27/55 -2/5 38/55 98/55 12/11] @@ -901,7 +897,7 @@ def restricted_automorphism_group(self, output="abstract"): A 3-dimensional polyhedron in (Number Field in sqrt5 with defining polynomial x^2 - 5 with sqrt5 = 2.236067977499790?)^3 defined as the convex hull of 20 vertices - sage: G = P.restricted_automorphism_group(output="matrixlist") + sage: G = P.restricted_automorphism_group(output='matrixlist') sage: len(G) 120 @@ -912,21 +908,21 @@ def restricted_automorphism_group(self, output="abstract"): ....: base_ring=RDF) sage: P.restricted_automorphism_group() # needs sage.groups Permutation Group with generators [(2,3), (1,2)] - sage: len(P.restricted_automorphism_group(output="matrixlist")) + sage: len(P.restricted_automorphism_group(output='matrixlist')) 6 TESTS:: sage: P = Polyhedron(vertices=[(1,0), (1,1)], rays=[(1,0)]) - sage: P.restricted_automorphism_group(output="permutation") # needs sage.groups + sage: P.restricted_automorphism_group(output='permutation') # needs sage.groups Permutation Group with generators [(1,2)] - sage: P.restricted_automorphism_group(output="matrix") + sage: P.restricted_automorphism_group(output='matrix') Matrix group over Rational Field with 1 generators ( [ 1 0 0] [ 0 -1 1] [ 0 0 1] ) - sage: P.restricted_automorphism_group(output="foobar") + sage: P.restricted_automorphism_group(output='foobar') Traceback (most recent call last): ... ValueError: unknown output 'foobar', valid values are @@ -934,7 +930,7 @@ def restricted_automorphism_group(self, output="abstract"): Check that :issue:`28828` is fixed:: - sage: P.restricted_automorphism_group(output="matrixlist")[0].is_immutable() + sage: P.restricted_automorphism_group(output='matrixlist')[0].is_immutable() True """ # The algorithm works as follows: @@ -1072,8 +1068,8 @@ def is_combinatorially_isomorphic(self, other, algorithm='bipartite_graph'): INPUT: - ``other`` -- a polyhedron object - - ``algorithm`` (default = ``'bipartite_graph'``) -- the algorithm to use. - The other possible value is ``'face_lattice'``. + - ``algorithm`` -- (default: ``'bipartite_graph'``) the algorithm to + use; the other possible value is ``'face_lattice'`` OUTPUT: @@ -1173,7 +1169,6 @@ def is_combinatorially_isomorphic(self, other, algorithm='bipartite_graph'): Traceback (most recent call last): ... AssertionError: polyhedron `other` must be bounded - """ assert isinstance(other, Polyhedron_base4), "input `other` must be a polyhedron" assert self.is_compact(), "polyhedron `self` must be bounded" @@ -1250,7 +1245,6 @@ def is_self_dual(self): Traceback (most recent call last): ... ValueError: polyhedron has to be compact - """ if not self.is_compact(): raise ValueError("polyhedron has to be compact") diff --git a/src/sage/geometry/polyhedron/base5.py b/src/sage/geometry/polyhedron/base5.py index 2ac8b75cdd8..d683955b53a 100644 --- a/src/sage/geometry/polyhedron/base5.py +++ b/src/sage/geometry/polyhedron/base5.py @@ -579,12 +579,10 @@ def truncation(self, cut_frac=None): INPUT: - - ``cut_frac`` -- integer, how deeply to cut into the edge. - Default is `\frac{1}{3}`. - - OUTPUT: + - ``cut_frac`` -- integer; how deeply to cut into the edge + Default is `\frac{1}{3}` - A Polyhedron object, truncated as described above. + OUTPUT: a Polyhedron object, truncated as described above EXAMPLES:: @@ -684,9 +682,7 @@ def minkowski_sum(self, other): - ``other`` -- a :class:`~sage.geometry.polyhedron.base.Polyhedron_base` - OUTPUT: - - The Minkowski sum of ``self`` and ``other`` + OUTPUT: the Minkowski sum of ``self`` and ``other`` EXAMPLES:: @@ -846,7 +842,7 @@ def minkowski_difference(self, other): def __sub__(self, other): r""" - Implement minus binary operation + Implement minus binary operation. Polyhedra are not a ring with respect to dilatation and Minkowski sum, for example `X\oplus(-1)*Y \not= X\ominus Y`. @@ -991,9 +987,9 @@ def _test_product(self, tester=None, **options): if self.n_vertices() + self.n_rays() < 40 and self.n_facets() < 40: # Check that the product preserves the backend, where possible. - P = polytopes.simplex(backend="cdd") + P = polytopes.simplex(backend='cdd') tester.assertEqual((self*P).backend(), self.backend()) - Q = polytopes.simplex(backend="ppl") + Q = polytopes.simplex(backend='ppl') tester.assertEqual((self*Q).backend(), self.backend()) # And that it changes the backend correctly where necessary. @@ -1292,9 +1288,7 @@ def convex_hull(self, other): - ``other`` -- a :class:`Polyhedron` - OUTPUT: - - The convex hull. + OUTPUT: the convex hull EXAMPLES:: @@ -1320,9 +1314,7 @@ def intersection(self, other): - ``other`` -- a :class:`Polyhedron` - OUTPUT: - - The intersection. + OUTPUT: the intersection Note that the intersection of two `\ZZ`-polyhedra might not be a `\ZZ`-polyhedron. In this case, a `\QQ`-polyhedron is @@ -1460,9 +1452,7 @@ def translation(self, displacement): - ``displacement`` -- a displacement vector or a list/tuple of coordinates that determines a displacement vector - OUTPUT: - - The translated polyhedron. + OUTPUT: the translated polyhedron EXAMPLES:: @@ -1503,7 +1493,7 @@ def _translation_double_description(self, displacement): - ``displacement`` -- a displacement vector or a list/tuple of coordinates that determines a displacement vector - OUTPUT: Tuple of consisting of new Vrepresentation, Hrepresentation and parent. + OUTPUT: tuple of consisting of new Vrepresentation, Hrepresentation and parent .. SEEALSO:: @@ -1542,7 +1532,7 @@ def dilation(self, scalar): INPUT: - - ``scalar`` -- A scalar, not necessarily in :meth:`base_ring` + - ``scalar`` -- a scalar, not necessarily in :meth:`base_ring` OUTPUT: @@ -1933,9 +1923,7 @@ def face_truncation(self, face, linear_coefficients=None, cut_frac=None): vertex (according to the normal vector of the cutting hyperplane). Default is `\frac{1}{3}`. - OUTPUT: - - A Polyhedron object, truncated as described above. + OUTPUT: a Polyhedron object, truncated as described above EXAMPLES:: @@ -2089,9 +2077,7 @@ def stack(self, face, position=None): new vertex close to the face and a large value further away. Default is `1`. If the given value is too large, an error is returned. - OUTPUT: - - A Polyhedron object + OUTPUT: a Polyhedron object EXAMPLES:: @@ -2421,7 +2407,8 @@ def lawrence_extension(self, v): if `v` is a vertex. INPUT: - - ``v`` -- a vertex of ``self`` or a point outside it + + - ``v`` -- a vertex of ``self`` or a point outside it EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/base6.py b/src/sage/geometry/polyhedron/base6.py index cb1577c10b1..f9bc49d7821 100644 --- a/src/sage/geometry/polyhedron/base6.py +++ b/src/sage/geometry/polyhedron/base6.py @@ -151,7 +151,7 @@ def plot(self, INPUT: - - ``point``, ``line``, ``polygon`` -- Parameters to pass to + - ``point``, ``line``, ``polygon`` -- parameters to pass to point (0d), line (1d), and polygon (2d) plot commands. Allowed values are: @@ -164,7 +164,7 @@ def plot(self, * ``False``: Switches off the drawing of the corresponding graphics object - - ``wireframe``, ``fill`` -- Similar to ``point``, ``line``, + - ``wireframe``, ``fill`` -- similar to ``point``, ``line``, and ``polygon``, but ``fill`` is used for the graphics objects in the dimension of the polytope (or of dimension 2 for higher dimensional polytopes) and ``wireframe`` is used @@ -172,13 +172,13 @@ def plot(self, (default: 'green' for ``fill`` and 'blue' for ``wireframe``) - ``position`` -- positive number; the position to take the projection - point in Schlegel diagrams. + point in Schlegel diagrams - - ``orthonormal`` -- Boolean (default: ``True``); whether to use - orthonormal projections. + - ``orthonormal`` -- boolean (default: ``True``); whether to use + orthonormal projections - ``**kwds`` -- optional keyword parameters that are passed to - all graphics objects. + all graphics objects OUTPUT: @@ -324,15 +324,15 @@ def plot(self, Draw in red without wireframe:: - sage: for p in square.plot(wireframe=False, fill="red"): # needs sage.plot + sage: for p in square.plot(wireframe=False, fill='red'): # needs sage.plot ....: print("{} {}".format(p.options()['rgbcolor'], p)) red Polygon defined by 4 points - sage: for p in line.plot(wireframe=False, fill="red"): # needs sage.plot + sage: for p in line.plot(wireframe=False, fill='red'): # needs sage.plot ....: print("{} {}".format(p.options()['rgbcolor'], p)) red Line defined by 2 points - sage: for p in point.plot(wireframe=False, fill="red"): # needs sage.plot + sage: for p in point.plot(wireframe=False, fill='red'): # needs sage.plot ....: print("{} {}".format(p.options()['rgbcolor'], p)) red Point set defined by 1 point(s) @@ -457,7 +457,7 @@ def project(polyhedron, ortho): def show(self, **kwds): r""" - Display graphics immediately + Display graphics immediately. This method attempts to display the graphics immediately, without waiting for the currently running code (if any) to @@ -467,8 +467,8 @@ def show(self, **kwds): INPUT: - - ``kwds`` -- optional keyword arguments. See :meth:`plot` for - the description of available options. + - ``kwds`` -- optional keyword arguments; see :meth:`plot` for + the description of available options OUTPUT: @@ -495,28 +495,26 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1, INPUT: - - ``view`` -- list (default: [0,0,1]) representing the rotation axis (see note below). - - ``angle`` -- integer (default: 0) angle of rotation in degree from 0 to 360 (see note - below). - - ``scale`` -- integer (default: 1) specifying the scaling of the tikz picture. - - ``edge_color`` -- string (default: 'blue!95!black') representing colors which tikz - recognize. - - ``facet_color`` -- string (default: 'blue!95!black') representing colors which tikz - recognize. - - ``vertex_color`` -- string (default: 'green') representing colors which tikz - recognize. + - ``view`` -- list (default: [0,0,1]) representing the rotation axis (see note below) + - ``angle`` -- integer (default: 0); angle of rotation in degree from 0 to 360 (see note + below) + - ``scale`` -- integer (default: 1); the scaling of the tikz picture + - ``edge_color`` -- string (default: ``'blue!95!black'``); representing colors which tikz + recognizes + - ``facet_color`` -- string (default: ``'blue!95!black'``); representing colors which tikz + recognizes + - ``vertex_color`` -- string (default: ``'green'``); representing colors which tikz + recognizes - ``opacity`` -- real number (default: 0.8) between 0 and 1 giving the opacity of - the front facets. - - ``axis`` -- Boolean (default: ``False``) draw the axes at the origin or not. - - ``output_type`` -- string (default: ``None``), valid values + the front facets + - ``axis`` -- boolean (default: ``False``); draw the axes at the origin or not + - ``output_type`` -- string (default: ``None``); valid values are ``None`` (deprecated), ``'LatexExpr'`` and ``'TikzPicture'``, whether to return a LatexExpr object (which inherits from Python str) or a ``TikzPicture`` object from module :mod:`sage.misc.latex_standalone` - OUTPUT: - - - LatexExpr object or TikzPicture object + OUTPUT: LatexExpr object or TikzPicture object .. NOTE:: @@ -550,7 +548,6 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1, Jmol performs a rotation of ``angle`` degrees along the vector [x,y,z] and show the result from the z-axis. - EXAMPLES:: sage: # needs sage.plot @@ -611,7 +608,6 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1, \end{tikzpicture} \end{document} sage: path_to_file = t.pdf() # not tested - """ return self.projection().tikz(view, angle, scale, edge_color, facet_color, @@ -620,7 +616,7 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1, def _rich_repr_(self, display_manager, **kwds): r""" - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -835,17 +831,15 @@ def schlegel_projection(self, facet=None, position=None): INPUT: - - ``facet`` -- a :class:`~sage.geometry.polyhedron.face.PolyhedronFace`. - The facet into which the Schlegel diagram is created. The default is the first facet. + - ``facet`` -- a :class:`~sage.geometry.polyhedron.face.PolyhedronFace` + The facet into which the Schlegel diagram is created. The default is the first facet - ``position`` -- a positive number. Determines a relative distance from the barycenter of ``facet``. A value close to 0 will place the projection point close to the facet and a large value further away. Default is `1`. If the given value is too large, an error is returned. - OUTPUT: - - A :class:`~sage.geometry.polyhedron.plot.Projection` object. + OUTPUT: a :class:`~sage.geometry.polyhedron.plot.Projection` object EXAMPLES:: @@ -1099,10 +1093,10 @@ def affine_hull_projection(self, INPUT: - - ``as_polyhedron`` (or ``as_convex_set``) -- (boolean or the default - ``None``) and + - ``as_polyhedron``, ``as_convex_set`` -- boolean or the default + ``None``; one of the two to be set - - ``as_affine_map`` -- (boolean, default ``False``) control the output + - ``as_affine_map`` -- boolean (default: ``False``); control the output The default ``as_polyhedron=None`` translates to ``as_polyhedron=not as_affine_map``, @@ -1120,7 +1114,7 @@ def affine_hull_projection(self, both are returned, encapsulated in an instance of :class:`~sage.geometry.convex_set.AffineHullProjectionData`. - - ``return_all_data`` -- (boolean, default ``False``) + - ``return_all_data`` -- boolean (default: ``False``) If set, then ``as_polyhedron`` and ``as_affine_map`` will set (possibly overridden) and additional (internal) data concerning @@ -1130,7 +1124,7 @@ def affine_hull_projection(self, this case. - ``orthogonal`` -- boolean (default: ``False``); if ``True``, - provide an orthogonal transformation. + provide an orthogonal transformation - ``orthonormal`` -- boolean (default: ``False``); if ``True``, provide an orthonormal transformation. If the base ring does not @@ -1603,11 +1597,11 @@ def affine_hull_manifold(self, name=None, latex_name=None, start_index=0, ambien of the ambient dimension (default: the manifold of ``ambient_chart``, if provided; otherwise, a new instance of ``EuclideanSpace``). - - ``ambient_chart`` -- a chart on ``ambient_space``. + - ``ambient_chart`` -- a chart on ``ambient_space`` - - ``names`` -- names for the coordinates on the affine hull. + - ``names`` -- names for the coordinates on the affine hull - - optional arguments accepted by :meth:`affine_hull_projection`. + - optional arguments accepted by :meth:`affine_hull_projection` The default chart is determined by the optional arguments of :meth:`affine_hull_projection`. @@ -1669,7 +1663,6 @@ def affine_hull_manifold(self, name=None, latex_name=None, start_index=0, ambien A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 8 vertices sage: cube.affine_hull_manifold() # needs sage.symbolic Euclidean space E^3 - """ if ambient_space is None: if ambient_chart is not None: @@ -1690,7 +1683,7 @@ def affine_hull_manifold(self, name=None, latex_name=None, start_index=0, ambien from sage.manifolds.manifold import Manifold if name is None: name, latex_name = self._affine_hull_name_latex_name() - H = Manifold(self.dim(), name, ambient=ambient_space, structure="Riemannian", + H = Manifold(self.dim(), name, ambient=ambient_space, structure='Riemannian', latex_name=latex_name, start_index=start_index) if names is None: names = tuple(f'x{i}' for i in range(self.dim())) diff --git a/src/sage/geometry/polyhedron/base7.py b/src/sage/geometry/polyhedron/base7.py index aca38a58404..7b86d534017 100644 --- a/src/sage/geometry/polyhedron/base7.py +++ b/src/sage/geometry/polyhedron/base7.py @@ -64,7 +64,7 @@ def centroid(self, engine='auto', **kwds): The mass is taken with respect to the induced Lebesgue measure, see :meth:`volume`. - If the polyhedron is not compact, a ``NotImplementedError`` is + If the polyhedron is not compact, a :exc:`NotImplementedError` is raised. INPUT: @@ -76,9 +76,9 @@ def centroid(self, engine='auto', **kwds): TOPCOM is used if it is available and internal routines otherwise. - ``**kwds`` -- keyword arguments that are passed to the - triangulation engine (see :meth:`triangulate`). + triangulation engine (see :meth:`triangulate`) - OUTPUT: The centroid as vector. + OUTPUT: the centroid as vector ALGORITHM: @@ -150,7 +150,7 @@ def centroid(self, engine='auto', **kwds): def _triangulate_normaliz(self): r""" - Gives a triangulation of the polyhedron using normaliz + Give a triangulation of the polyhedron using normaliz. OUTPUT: @@ -188,17 +188,17 @@ def triangulate(self, engine='auto', connected=True, fine=False, regular=None, s :class:`~sage.geometry.triangulation.point_configuration.PointConfiguration` constructor: - - ``connected`` -- boolean (default: ``True``). Whether the + - ``connected`` -- boolean (default: ``True``); whether the triangulations should be connected to the regular triangulations via bistellar flips. These are much easier to compute than all triangulations. - - ``fine`` -- boolean (default: ``False``). Whether the + - ``fine`` -- boolean (default: ``False``); whether the triangulations must be fine, that is, make use of all points - of the configuration. + of the configuration - ``regular`` -- boolean or ``None`` (default: - ``None``). Whether the triangulations must be regular. A + ``None``); whether the triangulations must be regular. A regular triangulation is one that is induced by a piecewise-linear convex support function. In other words, the shadows of the faces of a polyhedron in one higher @@ -312,11 +312,9 @@ def triangulate(self, engine='auto', connected=True, fine=False, regular=None, s def _volume_lrs(self, verbose=False): """ - Computes the volume of a polytope using lrs. + Compute the volume of a polytope using lrs. - OUTPUT: - - The exact volume as a rational number. + OUTPUT: the exact volume as a rational number EXAMPLES:: @@ -365,24 +363,25 @@ def _volume_lrs(self, verbose=False): def _volume_latte(self, verbose=False, algorithm='triangulate', **kwargs): """ - Computes the volume of a polytope using LattE integrale. + Compute the volume of a polytope using LattE integrale. INPUT: - ``arg`` -- a cdd or LattE description string - - ``algorithm`` -- (default: 'triangulate') the integration method. Use 'triangulate' for - polytope triangulation or 'cone-decompose' for tangent cone decomposition method. + - ``algorithm`` -- (default: ``'triangulate'``) the integration method; + use 'triangulate' for polytope triangulation or 'cone-decompose' for + tangent cone decomposition method - - ``raw_output`` -- if ``True`` then return directly the output string from LattE. + - ``raw_output`` -- if ``True`` then return directly the output string + from LattE - - ``verbose`` -- if ``True`` then return directly verbose output from LattE. + - ``verbose`` -- if ``True`` then return directly verbose output from + LattE - For all other options, consult the LattE manual. - OUTPUT: - - A rational value, or a string if ``raw_output`` if set to ``True``. + OUTPUT: a rational value, or a string if ``raw_output`` if set to ``True`` .. NOTE:: @@ -436,13 +435,13 @@ def _volume_latte(self, verbose=False, algorithm='triangulate', **kwargs): def _volume_normaliz(self, measure='induced'): r""" - Computes the volume of a polytope using normaliz. + Compute the volume of a polytope using normaliz. INPUT: - - ``measure`` -- (default: 'induced') the measure to take. 'induced' - correspond to ``EuclideanVolume`` in normaliz and 'induced_lattice' - correspond to ``Volume`` in normaliz + - ``measure`` -- (default: ``'induced'``) the measure to take; + 'induced' correspond to ``EuclideanVolume`` in normaliz and + 'induced_lattice' correspond to ``Volume`` in normaliz OUTPUT: @@ -492,9 +491,7 @@ def volume(self, measure='ambient', engine='auto', **kwds): - ``**kwds`` -- keyword arguments that are passed to the triangulation engine - OUTPUT: - - The volume of the polytope + OUTPUT: the volume of the polytope EXAMPLES:: @@ -788,9 +785,7 @@ def integrate(self, function, measure='ambient', **kwds): - ``**kwds`` -- additional keyword arguments that are passed to the engine - OUTPUT: - - The integral of the polynomial over the polytope + OUTPUT: the integral of the polynomial over the polytope .. NOTE:: @@ -961,9 +956,7 @@ def _integrate_latte_(self, polynomial, **kwds): - ``**kwds`` -- additional keyword arguments that are passed to the engine - OUTPUT: - - The integral of the polynomial over the polytope. + OUTPUT: the integral of the polynomial over the polytope .. NOTE:: diff --git a/src/sage/geometry/polyhedron/base_QQ.py b/src/sage/geometry/polyhedron/base_QQ.py index a6d1aa719f3..e17f043adb5 100644 --- a/src/sage/geometry/polyhedron/base_QQ.py +++ b/src/sage/geometry/polyhedron/base_QQ.py @@ -10,7 +10,7 @@ class Polyhedron_QQ(Polyhedron_base): r""" - Base class for Polyhedra over `\QQ` + Base class for Polyhedra over `\QQ`. TESTS:: @@ -24,11 +24,9 @@ def _is_zero(self, x): INPUT: - - ``x`` -- a number in the base ring. + - ``x`` -- a number in the base ring - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -46,11 +44,9 @@ def _is_nonneg(self, x): INPUT: - - ``x`` -- a number in the base ring. + - ``x`` -- a number in the base ring - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -68,11 +64,9 @@ def _is_positive(self, x): INPUT: - - ``x`` -- a number in the base ring. + - ``x`` -- a number in the base ring - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -97,13 +91,13 @@ def integral_points_count(self, verbose=False, use_Hrepresentation=False, INPUT: - - ``verbose`` -- (boolean; ``False`` by default) whether to display - verbose output. + - ``verbose`` -- boolean (default: ``False``); whether to display + verbose output - - ``use_Hrepresentation`` -- (boolean; ``False`` by default) -- whether + - ``use_Hrepresentation`` -- boolean (default: ``False``); whether to send the H or V representation to LattE - - ``preprocess`` -- (boolean; ``True`` by default) whether, if the integral hull + - ``preprocess`` -- boolean (default: ``True``); whether, if the integral hull is known to lie in a coordinate hyperplane, to tighten bounds to reduce dimension .. SEEALSO:: @@ -237,7 +231,7 @@ def ehrhart_polynomial(self, engine=None, variable='t', verbose=False, INPUT: - - ``engine`` -- string; The backend to use. Allowed values are: + - ``engine`` -- string; the backend to use. Allowed values are: * ``None`` (default); When no input is given the Ehrhart polynomial is computed using LattE Integrale (optional) @@ -245,13 +239,13 @@ def ehrhart_polynomial(self, engine=None, variable='t', verbose=False, * ``'normaliz'``; use Normaliz program (optional package pynormaliz). The backend of ``self`` must be set to ``'normaliz'``. - - ``variable`` -- string (default: ``'t'``); The variable in which the - Ehrhart polynomial should be expressed. + - ``variable`` -- string (default: ``'t'``); the variable in which the + Ehrhart polynomial should be expressed - When the ``engine`` is ``'latte'``, the additional input values are: - * ``verbose`` -- boolean (default: ``False``); If ``True``, print the - whole output of the LattE command. + * ``verbose`` -- boolean (default: ``False``); if ``True``, print the + whole output of the LattE command The following options are passed to the LattE command, for details consult `the LattE documentation @@ -274,9 +268,7 @@ def ehrhart_polynomial(self, engine=None, variable='t', verbose=False, * ``triangulation_max_height`` -- integer; use a uniform distribution of height from 1 to this number - OUTPUT: - - A univariate polynomial in ``variable`` over a rational field. + OUTPUT: a univariate polynomial in ``variable`` over a rational field .. SEEALSO:: @@ -410,10 +402,10 @@ def ehrhart_quasipolynomial(self, variable='t', engine=None, verbose=False, INPUT: - - ``variable`` -- string (default: ``'t'``); The variable in which the - Ehrhart polynomial should be expressed. + - ``variable`` -- string (default: ``'t'``); the variable in which the + Ehrhart polynomial should be expressed - - ``engine`` -- string; The backend to use. Allowed values are: + - ``engine`` -- string; the backend to use. Allowed values are: * ``None`` (default); When no input is given the Ehrhart polynomial is computed using Normaliz (optional) @@ -424,8 +416,8 @@ def ehrhart_quasipolynomial(self, variable='t', engine=None, verbose=False, - When the ``engine`` is 'latte', the additional input values are: - * ``verbose`` -- boolean (default: ``False``); If ``True``, print the - whole output of the LattE command. + * ``verbose`` -- boolean (default: ``False``); if ``True``, print the + whole output of the LattE command The following options are passed to the LattE command, for details consult `the LattE documentation @@ -593,8 +585,8 @@ def _ehrhart_quasipolynomial_normaliz(self, variable='t'): INPUT: - - ``variable`` -- string (default: ``'t'``); The variable in which the - Ehrhart polynomial is expressed. + - ``variable`` -- string (default: ``'t'``); the variable in which the + Ehrhart polynomial is expressed OUTPUT: @@ -657,7 +649,7 @@ def _ehrhart_polynomial_latte(self, verbose=False, dual=None, INPUT: - ``verbose`` -- boolean (default: ``False``); if ``True``, print the - whole output of the LattE command. + whole output of the LattE command The following options are passed to the LattE command, for details you should consult `the LattE documentation @@ -667,15 +659,15 @@ def _ehrhart_polynomial_latte(self, verbose=False, dual=None, space - ``irrational_primal`` -- boolean; triangulate in the dual space, - signed-decompose in the primal space using irrationalization. + signed-decompose in the primal space using irrationalization - ``irrational_all_primal`` -- boolean; triangulate and signed-decompose - in the primal space using irrationalization. + in the primal space using irrationalization - ``maxdet`` -- integer; decompose down to an index (determinant) of - ``maxdet`` instead of index 1 (unimodular cones). + ``maxdet`` instead of index 1 (unimodular cones) - - ``no_decomposition`` -- boolean; do not signed-decompose simplicial cones. + - ``no_decomposition`` -- boolean; do not signed-decompose simplicial cones - ``compute_vertex_cones`` -- string; either ``'cdd'`` or ``'lrs'`` or ``'4ti2'`` @@ -693,9 +685,7 @@ def _ehrhart_polynomial_latte(self, verbose=False, dual=None, Any additional argument is forwarded to LattE's executable ``count``. All occurrences of '_' will be replaced with a '-'. - OUTPUT: - - A univariate polynomial over a rational field. + OUTPUT: a univariate polynomial over a rational field ALGORITHM: @@ -814,11 +804,9 @@ def fixed_subpolytope(self, vertex_permutation): INPUT: - ``vertex_permutation`` -- permutation; a permutation of the vertices - of ``self``. - - OUTPUT: + of ``self`` - A subpolytope of ``self``. + OUTPUT: a subpolytope of ``self`` .. NOTE:: @@ -927,7 +915,7 @@ def fixed_subpolytopes(self, conj_class_reps): INPUT: - - ``conj_class_reps`` -- a list of representatives of the conjugacy + - ``conj_class_reps`` -- list of representatives of the conjugacy classes of the subgroup of the :meth:`restricted_automorphism_group` of the polytope. Each element is written as a permutation of the vertices of the polytope. @@ -1021,7 +1009,6 @@ class functions. There are several output options to see the intermediary outputs of the function. - EXAMPLES: The `H^*`-polynomial of the standard (`d-1`)-dimensional simplex @@ -1101,8 +1088,7 @@ class functions. def _Hstar_function_normaliz(self, acting_group=None, output=None): r""" Return `H^*` as a rational function in `t` with coefficients in - the ring of class functions of the ``acting_group`' - of ``self``. + the ring of class functions of the ``acting_group`` of ``self``. INPUT: @@ -1155,21 +1141,19 @@ def is_effective(self, Hstar, Hstar_as_lin_comb): coefficient of each `t^i` is an effective character in the ring of class functions of the acting group. A character `\rho` is effective if the coefficients of the irreducible representations in the expression - of `\rho` are non-negative integers. + of `\rho` are nonnegative integers. INPUT: - ``Hstar`` -- a rational function in `t` with coefficients in the ring - of class functions. + of class functions - ``Hstar_as_lin_comb`` -- vector. The coefficients of the irreducible representations of the acting group in the expression of ``Hstar`` as a linear combination of irreducible representations with coefficients in the field of rational functions in `t`. - OUTPUT: - - Boolean. Whether the ``Hstar`` series is effective. + OUTPUT: boolean; whether the ``Hstar`` series is effective .. SEEALSO:: @@ -1232,21 +1216,19 @@ def _is_effective_normaliz(self, Hstar, Hstar_as_lin_comb): coefficient of each `t^i` is an effective character in the ring of class functions of the acting group. A character `\rho` is effective if the coefficients of the irreducible representations in the expression - of `\rho` are non-negative integers. + of `\rho` are nonnegative integers. INPUT: - ``Hstar`` -- a rational function in `t` with coefficients in the ring - of class functions. + of class functions - ``Hstar_as_lin_comb`` -- vector. The coefficients of the irreducible representations of the acting group in the expression of ``Hstar`` as a linear combination of irreducible representations with coefficients in the field of rational functions in `t`. - OUTPUT: - - Boolean. Whether the ``Hstar`` series is effective. + OUTPUT: boolean; whether the ``Hstar`` series is effective TESTS:: diff --git a/src/sage/geometry/polyhedron/base_RDF.py b/src/sage/geometry/polyhedron/base_RDF.py index 93914ded471..505355ac42c 100644 --- a/src/sage/geometry/polyhedron/base_RDF.py +++ b/src/sage/geometry/polyhedron/base_RDF.py @@ -25,11 +25,9 @@ def _is_zero(self, x): INPUT: - - ``x`` -- a number in the base ring. + - ``x`` -- a number in the base ring - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -52,11 +50,9 @@ def _is_nonneg(self, x): INPUT: - - ``x`` -- a number in the base ring. - - OUTPUT: + - ``x`` -- a number in the base ring - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -79,11 +75,9 @@ def _is_positive(self, x): INPUT: - - ``x`` -- a number in the base ring. - - OUTPUT: + - ``x`` -- a number in the base ring - Boolean. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/base_ZZ.py b/src/sage/geometry/polyhedron/base_ZZ.py index dd3d32d9e51..d17b40a1b3d 100644 --- a/src/sage/geometry/polyhedron/base_ZZ.py +++ b/src/sage/geometry/polyhedron/base_ZZ.py @@ -30,7 +30,7 @@ ######################################################################### class Polyhedron_ZZ(Polyhedron_QQ): r""" - Base class for Polyhedra over `\ZZ` + Base class for Polyhedra over `\ZZ`. TESTS:: @@ -116,7 +116,7 @@ def _ehrhart_polynomial_latte(self, verbose=False, dual=None, INPUT: - ``verbose`` -- boolean (default: ``False``); if ``True``, print the - whole output of the LattE command. + whole output of the LattE command The following options are passed to the LattE command, for details you should consult `the LattE documentation @@ -126,15 +126,15 @@ def _ehrhart_polynomial_latte(self, verbose=False, dual=None, space - ``irrational_primal`` -- boolean; triangulate in the dual space, - signed-decompose in the primal space using irrationalization. + signed-decompose in the primal space using irrationalization - ``irrational_all_primal`` -- boolean; triangulate and signed-decompose - in the primal space using irrationalization. + in the primal space using irrationalization - ``maxdet`` -- integer; decompose down to an index (determinant) of - ``maxdet`` instead of index 1 (unimodular cones). + ``maxdet`` instead of index 1 (unimodular cones) - - ``no_decomposition`` -- boolean; do not signed-decompose simplicial cones. + - ``no_decomposition`` -- boolean; do not signed-decompose simplicial cones - ``compute_vertex_cones`` -- string; either 'cdd' or 'lrs' or '4ti2' @@ -266,12 +266,10 @@ def _ehrhart_polynomial_normaliz(self, variable='t'): INPUT: - - ``variable`` -- (string, default='t'); the variable in which the - Ehrhart polynomial is expressed. + - ``variable`` -- string (default: ``'t'``); the variable in which the + Ehrhart polynomial is expressed - OUTPUT: - - A univariate polynomial over a rational field. + OUTPUT: a univariate polynomial over a rational field EXAMPLES:: @@ -316,7 +314,7 @@ def ehrhart_polynomial(self, engine=None, variable='t', verbose=False, dual=None INPUT: - - ``engine`` -- string; The backend to use. Allowed values are: + - ``engine`` -- string; the backend to use. Allowed values are: * ``None`` (default); When no input is given the Ehrhart polynomial is computed using LattE Integrale (optional) @@ -324,8 +322,8 @@ def ehrhart_polynomial(self, engine=None, variable='t', verbose=False, dual=None * ``'normaliz'``; use Normaliz program (optional). The backend of ``self`` must be set to 'normaliz'. - - ``variable`` -- string (default: 't'); The variable in which the - Ehrhart polynomial should be expressed. + - ``variable`` -- string (default: ``'t'``); the variable in which the + Ehrhart polynomial should be expressed - When the ``engine`` is 'latte' or None, the additional input values are: @@ -340,7 +338,7 @@ def ehrhart_polynomial(self, engine=None, variable='t', verbose=False, dual=None space * ``irrational_primal`` -- boolean; triangulate in the dual space, signed-decompose in the primal space using irrationalization. - * ``irrational_all_primal`` -- boolean; Triangulate and signed-decompose + * ``irrational_all_primal`` -- boolean; triangulate and signed-decompose in the primal space using irrationalization. * ``maxdet`` -- integer; decompose down to an index (determinant) of ``maxdet`` instead of index 1 (unimodular cones). @@ -627,8 +625,8 @@ def fibration_generator(self, dim): INPUT: - - ``dim`` -- integer. The dimension of the lattice polytope - fiber. + - ``dim`` -- integer; the dimension of the lattice polytope + fiber OUTPUT: @@ -669,12 +667,12 @@ def find_translation(self, translated_polyhedron): INPUT: - - ``translated_polyhedron`` -- a polyhedron. + - ``translated_polyhedron`` -- a polyhedron OUTPUT: A `\ZZ`-vector that translates ``self`` to - ``translated_polyhedron``. A ``ValueError`` is raised if + ``translated_polyhedron``. A :exc:`ValueError` is raised if ``translated_polyhedron`` is not a translation of ``self``, this can be used to check that two polyhedra are not translates of each other. @@ -842,16 +840,16 @@ def is_known_summand(poly): summands += [X, Y] return tuple(decompositions) - def normal_form(self, algorithm="palp_native", permutation=False): + def normal_form(self, algorithm='palp_native', permutation=False): r""" Return the normal form of vertices of the lattice polytope ``self``. INPUT: - - ``algorithm`` -- must be ``"palp_native"``, the default. + - ``algorithm`` -- must be ``'palp_native'``, the default - ``permutation`` -- boolean (default: ``False``); if ``True``, the permutation - applied to vertices to obtain the normal form is returned as well. + applied to vertices to obtain the normal form is returned as well For more more detail, see :meth:`~sage.geometry.lattice_polytope.LatticePolytopeClass.normal_form`. @@ -903,7 +901,7 @@ def normal_form(self, algorithm="palp_native", permutation=False): TESTS:: - sage: d.normal_form(algorithm="palp_fiction") + sage: d.normal_form(algorithm='palp_fiction') Traceback (most recent call last): ... ValueError: algorithm must be 'palp_native' diff --git a/src/sage/geometry/polyhedron/base_mutable.py b/src/sage/geometry/polyhedron/base_mutable.py index 42e77a8fcf0..1a3622a9e5b 100644 --- a/src/sage/geometry/polyhedron/base_mutable.py +++ b/src/sage/geometry/polyhedron/base_mutable.py @@ -136,7 +136,7 @@ def _add_dependent_object(self, ob): def is_mutable(self): r""" - Return True if the polyhedron is mutable, i.e. it can be modified in place. + Return ``True`` if the polyhedron is mutable, i.e. it can be modified in place. EXAMPLES:: @@ -151,7 +151,7 @@ def is_mutable(self): def is_immutable(self): r""" - Return True if the polyhedron is immutable, i.e. it cannot be modified in place. + Return ``True`` if the polyhedron is immutable, i.e. it cannot be modified in place. EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/cdd_file_format.py b/src/sage/geometry/polyhedron/cdd_file_format.py index 728f20bb9b5..9dfedcad58d 100644 --- a/src/sage/geometry/polyhedron/cdd_file_format.py +++ b/src/sage/geometry/polyhedron/cdd_file_format.py @@ -20,7 +20,7 @@ def cdd_Vrepresentation(cdd_type, vertices, rays, lines, file_output=None): INPUT: - - ``file_output`` (string; optional) -- a filename to which the + - ``file_output`` -- string (optional); a filename to which the representation should be written. If set to ``None`` (default), representation is returned as a string. @@ -98,7 +98,7 @@ def cdd_Hrepresentation(cdd_type, ieqs, eqns, file_output=None): INPUT: - - ``file_output`` (string; optional) -- a filename to which the + - ``file_output`` -- string (optional); a filename to which the representation should be written. If set to ``None`` (default), representation is returned as a string. diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/base.pyx b/src/sage/geometry/polyhedron/combinatorial_polyhedron/base.pyx index d21b824da0c..73cc5be6428 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/base.pyx +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/base.pyx @@ -11,11 +11,11 @@ the ridges and the face lattice. Terminology used in this module: -- Vrep -- ``[vertices, rays, lines]`` of the polyhedron. -- Hrep -- inequalities and equations of the polyhedron. -- Facets -- facets of the polyhedron. -- Vrepresentation -- represents a face by the list of Vrep it contains. -- Hrepresentation -- represents a face by a list of Hrep it is contained in. +- Vrep -- ``[vertices, rays, lines]`` of the polyhedron +- Hrep -- inequalities and equations of the polyhedron +- Facets -- facets of the polyhedron +- Vrepresentation -- represents a face by the list of Vrep it contains +- Hrepresentation -- represents a face by a list of Hrep it is contained in - bit representation -- represents incidences as bitset, where each bit represents one incidence. There might be trailing zeros, to fit alignment requirements. In most instances, faces are represented by the bit @@ -543,7 +543,7 @@ cdef class CombinatorialPolyhedron(SageObject): cdef _init_from_ListOfFaces(self, ListOfFaces facets, ListOfFaces Vrep): """ - Initialize self from two ``ListOfFaces``. + Initialize ``self`` from two ``ListOfFaces``. """ self._bitrep_facets = facets self._bitrep_Vrep = Vrep @@ -1300,7 +1300,7 @@ cdef class CombinatorialPolyhedron(SageObject): edges = tuple(edge for edge in self.edges(names=names, algorithm=algorithm) if edge[0] in vertices and edge[1] in vertices) - return Graph([vertices, edges], format="vertices_and_edges") + return Graph([vertices, edges], format='vertices_and_edges') graph = vertex_graph @@ -1376,7 +1376,7 @@ cdef class CombinatorialPolyhedron(SageObject): - ``add_equations`` -- if ``True``, then equations of the polyhedron will be added (only applicable when ``names`` is ``True``) - - ``names`` -- boolean (default: `True`); + - ``names`` -- boolean (default: ``True``); if ``False``, then the facets are given by their indices - ``algorithm`` -- string (optional); @@ -1583,7 +1583,7 @@ cdef class CombinatorialPolyhedron(SageObject): # If names is false, the ridges are given as tuple of indices, # i.e. (1,2) instead of (('f1',), ('f2',)). V = list(v[0] for v in V) - return Graph([V, E], format="vertices_and_edges") + return Graph([V, E], format='vertices_and_edges') @cached_method def vertex_facet_graph(self, names=True): @@ -1781,14 +1781,14 @@ cdef class CombinatorialPolyhedron(SageObject): INPUT: - - ``args`` -- integers (optional); specify an entry of the - flag-f-vector; must be an increasing sequence of integers + - ``args`` -- integer (optional); specify an entry of the + flag-f-vector (must be an increasing sequence of integers) OUTPUT: - a dictionary, if no arguments were given - - an Integer, if arguments were given + - an integer, if arguments were given EXAMPLES: @@ -2674,9 +2674,7 @@ cdef class CombinatorialPolyhedron(SageObject): * ``'dual'`` -- start with the vertices * ``None`` -- choose automatically - OUTPUT: - - - :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator.FaceIterator` + OUTPUT: :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator.FaceIterator` .. NOTE:: @@ -2787,9 +2785,7 @@ cdef class CombinatorialPolyhedron(SageObject): r""" Generate the face-lattice. - OUTPUT: - - - :class:`~sage.combinat.posets.lattices.FiniteLatticePoset` + OUTPUT: :class:`~sage.combinat.posets.lattices.FiniteLatticePoset` .. NOTE:: @@ -3172,7 +3168,7 @@ cdef class CombinatorialPolyhedron(SageObject): def _test_a_maximal_chain(self, tester=None, **options): """ - Run tests on the method :meth:`.a_maximal_chain` + Run tests on the method :meth:`.a_maximal_chain`. TESTS:: @@ -3252,7 +3248,7 @@ cdef class CombinatorialPolyhedron(SageObject): def is_compact(self): r""" - Return whether the polyhedron is compact + Return whether the polyhedron is compact. EXAMPLES:: @@ -3314,7 +3310,7 @@ cdef class CombinatorialPolyhedron(SageObject): cpdef CombinatorialPolyhedron dual(self): r""" - Return the dual/polar of self. + Return the dual/polar of ``self``. Only defined for bounded polyhedra. @@ -3594,9 +3590,7 @@ cdef class CombinatorialPolyhedron(SageObject): * ``'edges'`` * ``'ridges'`` - OUTPUT: - - Either ``'primal'`` or ``'dual'``. + OUTPUT: either ``'primal'`` or ``'dual'`` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/conversions.pyx b/src/sage/geometry/polyhedron/combinatorial_polyhedron/conversions.pyx index 951dd9e5420..a1ce8b14cb1 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/conversions.pyx +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/conversions.pyx @@ -107,9 +107,7 @@ cdef int Vrep_list_to_bit_rep(tuple Vrep_list, face_t output) except -1: - ``vertex_list`` -- tuple of pairwise distinct positive integers that fit into ``output`` - ``output`` -- an already initialized face - OUTPUT: - - - ``output`` is filled + OUTPUT: ``output`` is filled EXAMPLES:: @@ -158,16 +156,14 @@ cdef int incidences_to_bit_rep(tuple incidences, face_t output) except -1: Convert a tuple of incidences into Bit-representation. Store it in ``output``. Each entry in ``incidences`` represents a bit in - ``output``. It is set to ``1``, iff the entry in ``incidences`` is non-zero. + ``output``. It is set to ``1``, iff the entry in ``incidences`` is nonzero. INPUT: - ``incidences`` -- tuple of integers representing incidences that fit into ``output`` - ``output`` -- an already initialized face - OUTPUT: - - - ``output`` is filled + OUTPUT: ``output`` is filled EXAMPLES:: @@ -200,9 +196,7 @@ def incidence_matrix_to_bit_rep_of_facets(Matrix_dense matrix): with columns corresponding to equations deleted of type :class:`sage.matrix.matrix_dense.Matrix_dense` - OUTPUT: - - - :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` + OUTPUT: :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` EXAMPLES:: @@ -268,9 +262,7 @@ def incidence_matrix_to_bit_rep_of_Vrep(Matrix_dense matrix): with columns corresponding to equations deleted of type :class:`sage.matrix.matrix_dense.Matrix_dense` - OUTPUT: - - - :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` + OUTPUT: :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` EXAMPLES:: @@ -315,7 +307,7 @@ def incidence_matrix_to_bit_rep_of_Vrep(Matrix_dense matrix): def facets_tuple_to_bit_rep_of_facets(tuple facets_input, size_t n_Vrep): r""" - Initializes facets in Bit-representation as :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces`. + Initialize facets in Bit-representation as :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces`. INPUT: @@ -323,9 +315,7 @@ def facets_tuple_to_bit_rep_of_facets(tuple facets_input, size_t n_Vrep): Vrep must be exactly ``range(n_Vrep)`` - ``n_Vrep`` - OUTPUT: - - - :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` + OUTPUT: :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` EXAMPLES:: @@ -368,10 +358,7 @@ def facets_tuple_to_bit_rep_of_Vrep(tuple facets_input, size_t n_Vrep): Vrep must be exactly ``range(n_Vrep)`` - ``n_Vrep`` - OUTPUT: - - - :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` - + OUTPUT: :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` EXAMPLES:: @@ -423,9 +410,9 @@ def _bit_rep_to_Vrep_list_wrapper(ListOfFaces faces, index=0): INPUT: - ``faces`` -- a :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.list_of_faces.ListOfFaces` - - ``index`` -- (default: ``0``); the face to obtain + - ``index`` -- (default: ``0``) the face to obtain - OUTPUT: The face as tuple of integers. + OUTPUT: the face as tuple of integers EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_data_structure.pxd b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_data_structure.pxd index 3ed71a664e1..87766041ffb 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_data_structure.pxd +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_data_structure.pxd @@ -182,7 +182,7 @@ cdef inline void face_intersection_fused(face_t dest, face_t A, face_t B, algori Set ``dest`` to the intersection of ``A`` and ``B``. """ if algorithm_variant is standard: - # Also setting the non zero positions. + # Also setting the nonzero positions. sparse_bitset_intersection(dest.atoms, A.atoms, B.atoms) else: bitset_intersection(dest.atoms, A.atoms, B.atoms) diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pxd b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pxd index 3c015973dd1..e77abc9f33a 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pxd +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pxd @@ -25,7 +25,7 @@ cdef struct iter_s: size_t _index # this counts the number of seen faces, useful for hasing the faces # ``visited_all`` points to faces, of which we have visited all faces already. - # The number of faces in ``visited_all` might depend on the current dimension: + # The number of faces in ``visited_all`` might depend on the current dimension: # Consider we visit the facets A,B of some face F. # We will first visit all faces of A and then add A to visited_all. # Then we visit all faces of B and add B to visited_all. diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx index 99cfef13db2..d1daed6ad8b 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx @@ -2140,7 +2140,7 @@ cdef inline int prepare_face_iterator_for_partial_job( The first digit determines which facet to visit. The next digit determines which facet of the facet should be visited. - OUTPUT: ``1`` if the job exists and ``0`` otherwise. + OUTPUT: ``1`` if the job exists and ``0`` otherwise In addition, the first job treating a face will "visit" this face and increase the corresponding entry of the f-vector. diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_list_data_structure.pxd b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_list_data_structure.pxd index 50bbd7c4026..ea68babbaf5 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_list_data_structure.pxd +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/face_list_data_structure.pxd @@ -36,7 +36,7 @@ ctypedef face_list_s face_list_t[1] cdef inline int face_list_init(face_list_t faces, size_t n_faces, size_t n_atoms, size_t n_coatoms) except -1: """ - Sets the initial values for a list of faces with given number of faces + Set the initial values for a list of faces with given number of faces and number of atoms. """ face_list_shallow_init(faces, n_faces, n_atoms, n_coatoms) @@ -279,9 +279,7 @@ cdef inline size_t get_next_level_fused( - ``new_faces`` -- needs to be of same size as ``faces`` - ``visited_all`` -- the faces which have been visited before - OUTPUT: - - - set ``new_faces`` to point to the new faces + OUTPUT: set ``new_faces`` to point to the new faces ALGORITHM: diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/list_of_faces.pyx b/src/sage/geometry/polyhedron/combinatorial_polyhedron/list_of_faces.pyx index 468347f5256..0e8a53e97dc 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/list_of_faces.pyx +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/list_of_faces.pyx @@ -180,7 +180,7 @@ cdef class ListOfFaces: cpdef ListOfFaces __copy__(self): r""" - Return a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -423,7 +423,7 @@ cdef class ListOfFaces: cdef void delete_faces_unsafe(self, bint *delete, face_t face) noexcept: r""" - Deletes face ``i`` if and only if ``delete[i]``. + Delete face ``i`` if and only if ``delete[i]``. Alternatively, deletes all faces such that the ``i``-th bit in ``face`` is not set. @@ -478,7 +478,7 @@ cdef class ListOfFaces: def matrix(self): r""" - Obtain the matrix of self. + Obtain the matrix of ``self``. Each row represents a face and each column an atom. @@ -529,7 +529,7 @@ cdef tuple face_as_combinatorial_polyhedron(ListOfFaces facets, ListOfFaces Vrep - ``face`` -- face in Vrepresentation or ``NULL`` - ``dual`` -- boolean - OUTPUT: A tuple of new facets and new Vrepresentation as :class:`ListOfFaces`. + OUTPUT: a tuple of new facets and new Vrepresentation as :class:`ListOfFaces`. """ cdef ListOfFaces new_facets, new_Vrep cdef bint* delete diff --git a/src/sage/geometry/polyhedron/combinatorial_polyhedron/polyhedron_face_lattice.pyx b/src/sage/geometry/polyhedron/combinatorial_polyhedron/polyhedron_face_lattice.pyx index d0064795fa5..475b3e63e6c 100644 --- a/src/sage/geometry/polyhedron/combinatorial_polyhedron/polyhedron_face_lattice.pyx +++ b/src/sage/geometry/polyhedron/combinatorial_polyhedron/polyhedron_face_lattice.pyx @@ -8,11 +8,11 @@ the face lattice of a polyhedron. Terminology in this module: -- Vrep -- ``[vertices, rays, lines]`` of the polyhedron. +- Vrep -- ``[vertices, rays, lines]`` of the polyhedron -- Hrep -- inequalities and equations of the polyhedron. +- Hrep -- inequalities and equations of the polyhedron -- Facets -- facets of the polyhedron. +- Facets -- facets of the polyhedron - Coatoms -- the faces from which all others are constructed in the face iterator. This will be facets or Vrep. In non-dual mode, faces are @@ -23,9 +23,9 @@ Terminology in this module: - Atoms -- facets or Vrep depending on application of algorithm. Atoms are repsented as incidences of coatoms they are contained in. -- Vrepresentation -- represents a face by a list of Vrep it contains. +- Vrepresentation -- represents a face by a list of Vrep it contains -- Hrepresentation -- represents a face by a list of Hrep it is contained in. +- Hrepresentation -- represents a face by a list of Hrep it is contained in - bit representation -- represents incidences as ``uint64_t``-array, where each bit represents one incidence. There might be trailing zeros, to fit alignment diff --git a/src/sage/geometry/polyhedron/constructor.py b/src/sage/geometry/polyhedron/constructor.py index 5a5db0b43ae..0d8a4bfa6e6 100644 --- a/src/sage/geometry/polyhedron/constructor.py +++ b/src/sage/geometry/polyhedron/constructor.py @@ -34,15 +34,15 @@ points are equal if and only if the vector is the same. * **rays** `r_1,\dots,r_m` are a finite number of directions - (directions of infinity). Each ray is specified by a non-zero + (directions of infinity). Each ray is specified by a nonzero vector, and two rays are equal if and only if the vectors are the same up to rescaling with a positive constant. * **lines** `\ell_1,\dots,\ell_n` are a finite number of unoriented directions. In other words, a line is equivalent to the set `\{r, -r\}` for a ray `r`. Each line is specified by a - non-zero vector, and two lines are equivalent if and only if the - vectors are the same up to rescaling with a non-zero (possibly + nonzero vector, and two lines are equivalent if and only if the + vectors are the same up to rescaling with a nonzero (possibly negative) constant. When specifying a polyhedron, you can input a non-minimal set of @@ -326,21 +326,21 @@ def Polyhedron(vertices=None, rays=None, lines=None, or :meth:`polyhedron` method. In this case, the following 5 arguments cannot be provided. - - ``rays`` -- list of rays. Each ray can be specified as any - iterable container of ``base_ring`` elements. + - ``rays`` -- list of rays; each ray can be specified as any + iterable container of ``base_ring`` elements - - ``lines`` -- list of lines. Each line can be specified as any - iterable container of ``base_ring`` elements. + - ``lines`` -- list of lines; each line can be specified as any + iterable container of ``base_ring`` elements - - ``ieqs`` -- list of inequalities. Each line can be specified as any + - ``ieqs`` -- list of inequalities; each line can be specified as any iterable container of ``base_ring`` elements. An entry equal to ``[-1,7,3,4]`` represents the inequality `7x_1+3x_2+4x_3\geq 1`. - - ``eqns`` -- list of equalities. Each line can be specified as + - ``eqns`` -- list of equalities; each line can be specified as any iterable container of ``base_ring`` elements. An entry equal to ``[-1,7,3,4]`` represents the equality `7x_1+3x_2+4x_3= 1`. - - ``ambient_dim`` -- integer. The ambient space dimension. Usually + - ``ambient_dim`` -- integer; the ambient space dimension. Usually can be figured out automatically from the H/Vrepresentation dimensions. @@ -385,9 +385,7 @@ def Polyhedron(vertices=None, rays=None, lines=None, - ``mutable`` -- boolean (default: ``False``); whether the polyhedron is mutable - OUTPUT: - - The polyhedron defined by the input data. + OUTPUT: the polyhedron defined by the input data EXAMPLES: @@ -599,11 +597,11 @@ def Polyhedron(vertices=None, rays=None, lines=None, sage: Polyhedron(ambient_dim=2, ieqs=[], eqns=[], base_ring=QQ, backend='field') A 2-dimensional polyhedron in QQ^2 defined as the convex hull of 1 vertex and 2 lines - sage: Polyhedron(ambient_dim=0, ieqs=[], eqns=[[1]], base_ring=QQ, backend="cdd") + sage: Polyhedron(ambient_dim=0, ieqs=[], eqns=[[1]], base_ring=QQ, backend='cdd') The empty polyhedron in QQ^0 - sage: Polyhedron(ambient_dim=0, ieqs=[], eqns=[[1]], base_ring=QQ, backend="ppl") + sage: Polyhedron(ambient_dim=0, ieqs=[], eqns=[[1]], base_ring=QQ, backend='ppl') The empty polyhedron in QQ^0 - sage: Polyhedron(ambient_dim=0, ieqs=[], eqns=[[1]], base_ring=QQ, backend="field") + sage: Polyhedron(ambient_dim=0, ieqs=[], eqns=[[1]], base_ring=QQ, backend='field') The empty polyhedron in QQ^0 sage: Polyhedron(ambient_dim=2, vertices=[], rays=[], lines=[], base_ring=QQ) diff --git a/src/sage/geometry/polyhedron/double_description.py b/src/sage/geometry/polyhedron/double_description.py index 089580e3146..b38e108640f 100644 --- a/src/sage/geometry/polyhedron/double_description.py +++ b/src/sage/geometry/polyhedron/double_description.py @@ -85,13 +85,11 @@ def random_inequalities(d, n): INPUT: - - ``d`` -- integer. The dimension. + - ``d`` -- integer; the dimension - - ``n`` -- integer. The number of random inequalities to generate. + - ``n`` -- integer; the number of random inequalities to generate - OUTPUT: - - A random set of inequalities as a :class:`StandardAlgorithm` instance. + OUTPUT: a random set of inequalities as a :class:`StandardAlgorithm` instance EXAMPLES:: @@ -111,7 +109,7 @@ class DoubleDescriptionPair: def __init__(self, problem, A_rows, R_cols): r""" - Base class for a double description pair `(A, R)` + Base class for a double description pair `(A, R)`. .. warning:: @@ -122,13 +120,13 @@ def __init__(self, problem, A_rows, R_cols): INPUT: - - ``problem`` -- instance of :class:`Problem`. + - ``problem`` -- instance of :class:`Problem` - - ``A_rows`` -- list of row vectors of the matrix `A`. These - encode the inequalities. + - ``A_rows`` -- list of row vectors of the matrix `A`; these + encode the inequalities - ``R_cols`` -- list of column vectors of the matrix - `R`. These encode the rays. + `R`; these encode the rays TESTS:: @@ -159,11 +157,11 @@ def _make_new(self, A_rows, R_cols): INPUT: - - ``A_rows`` -- list of row vectors of the matrix `A`. These - encode the inequalities. + - ``A_rows`` -- list of row vectors of the matrix `A`; these + encode the inequalities - ``R_cols`` -- list of column vectors of the matrix - `R`. These encode the rays. + `R`; these encode the rays OUTPUT: @@ -192,9 +190,7 @@ def __repr__(self): r""" Return string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -316,7 +312,7 @@ def R_by_sign(self, a): INPUT: - - ``a`` -- vector. Coefficient vector of a homogeneous inequality. + - ``a`` -- vector; coefficient vector of a homogeneous inequality OUTPUT: @@ -352,11 +348,9 @@ def zero_set(self, ray): INPUT: - - ``ray`` -- a ray vector. - - OUTPUT: + - ``ray`` -- a ray vector - A set containing the inequality vectors that are zero on ``ray``. + OUTPUT: a set containing the inequality vectors that are zero on ``ray`` EXAMPLES:: @@ -427,11 +421,9 @@ def are_adjacent(self, r1, r2): INPUT: - - ``r1``, ``r2`` -- two rays. + - ``r1``, ``r2`` -- two rays - OUTPUT: - - Boolean. Whether the two rays are adjacent. + OUTPUT: boolean; whether the two rays are adjacent EXAMPLES:: @@ -523,14 +515,14 @@ class Problem: def __init__(self, A): r""" - Base class for implementations of the double description algorithm + Base class for implementations of the double description algorithm. It does not make sense to instantiate the base class directly, it just provides helpers for implementations. INPUT: - - ``A`` -- a matrix. The rows of the matrix are interpreted as + - ``A`` -- a matrix; the rows of the matrix are interpreted as homogeneous inequalities `A x \geq 0`. Must have maximal rank. TESTS:: @@ -554,9 +546,7 @@ def A(self): """ Return the rows of the defining matrix `A`. - OUTPUT: - - The matrix `A` whose rows are the inequalities. + OUTPUT: the matrix `A` whose rows are the inequalities EXAMPLES:: @@ -574,9 +564,7 @@ def A_matrix(self): """ Return the defining matrix `A`. - OUTPUT: - - Matrix whose rows are the inequalities. + OUTPUT: matrix whose rows are the inequalities EXAMPLES:: @@ -592,9 +580,7 @@ def base_ring(self): """ Return the base field. - OUTPUT: - - A field. + OUTPUT: a field EXAMPLES:: @@ -610,9 +596,7 @@ def dim(self): """ Return the ambient space dimension. - OUTPUT: - - Integer. The ambient space dimension of the cone. + OUTPUT: integer; the ambient space dimension of the cone EXAMPLES:: @@ -627,9 +611,7 @@ def __repr__(self): r""" Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -650,7 +632,7 @@ def initial_pair(self): INPUT: - ``pair_class`` -- subclass of - :class:`DoubleDescriptionPair`. + :class:`DoubleDescriptionPair` OUTPUT: @@ -694,7 +676,7 @@ def add_inequality(self, a): INPUT: - - ``a`` -- vector. An inequality. + - ``a`` -- vector; an inequality EXAMPLES:: @@ -724,7 +706,7 @@ def add_inequality(self, a): class StandardAlgorithm(Problem): """ - Standard implementation of the double description algorithm + Standard implementation of the double description algorithm. See [FP1996]_ for the definition of the "Standard Algorithm". diff --git a/src/sage/geometry/polyhedron/double_description_inhomogeneous.py b/src/sage/geometry/polyhedron/double_description_inhomogeneous.py index 9b7882a5bcd..873b3b431ea 100644 --- a/src/sage/geometry/polyhedron/double_description_inhomogeneous.py +++ b/src/sage/geometry/polyhedron/double_description_inhomogeneous.py @@ -16,7 +16,7 @@ implementation is general and works with any field in Sage that allows you to define polyhedra. -.. note:: +.. NOTE:: If you just want polyhedra over arbitrary fields then you should just use the @@ -66,13 +66,13 @@ class PivotedInequalities(SageObject): def __init__(self, base_ring, dim): """ - Base class for inequalities that may contain linear subspaces + Base class for inequalities that may contain linear subspaces. INPUT: - - ``base_ring`` -- a field. + - ``base_ring`` -- a field - - ``dim`` -- integer. The ambient space dimension. + - ``dim`` -- integer; the ambient space dimension EXAMPLES:: @@ -98,11 +98,9 @@ def _pivot_inequalities(self, A): INPUT: - - ``A`` -- matrix. The inequalities. + - ``A`` -- matrix; the inequalities - OUTPUT: - - The matrix of pivot columns. + OUTPUT: the matrix of pivot columns EXAMPLES:: @@ -125,11 +123,9 @@ def _unpivot_ray(self, ray): INPUT: - - ``ray`` -- ray in the pivoted coordinates. - - OUTPUT: + - ``ray`` -- ray in the pivoted coordinates - Ray in the original coordinates. + OUTPUT: ray in the original coordinates EXAMPLES:: @@ -156,15 +152,15 @@ def __init__(self, base_ring, dim, inequalities, equations): INPUT: - - ``base_ring`` -- a field. + - ``base_ring`` -- a field - - ``dim`` -- integer. The ambient space dimension. + - ``dim`` -- integer; the ambient space dimension - - ``inequalities`` -- list of inequalities. Each inequality - is given as constant term, ``dim`` coefficients. + - ``inequalities`` -- list of inequalities; each inequality + is given as constant term, ``dim`` coefficients - - ``equations`` -- list of equations. Same notation as for - inequalities. + - ``equations`` -- list of equations; same notation as for + inequalities EXAMPLES:: @@ -213,15 +209,13 @@ def __init__(self, base_ring, dim, inequalities, equations): def _init_Vrep(self, inequalities, equations): """ - Split off the linear subspace from the inequalities and select pivots + Split off the linear subspace from the inequalities and select pivots. INPUT: - - ``inequalities``, ``equations`` -- see :class:`Vrep2Hrep`. + - ``inequalities``, ``equations`` -- see :class:`Vrep2Hrep` - OUTPUT: - - The pivoted inequalities. + OUTPUT: the pivoted inequalities TESTS:: @@ -285,7 +279,7 @@ def _extract_Vrep(self, DD): INPUT: - ``DD`` -- a - :class:`~sage.geometry.polyhedron.double_description.DoubleDescriptionPair`. + :class:`~sage.geometry.polyhedron.double_description.DoubleDescriptionPair` TESTS:: @@ -355,7 +349,7 @@ def verify(self, inequalities, equations): INPUT: - - ``inequalities``, ``equations`` -- see :class:`Hrep2Vrep`. + - ``inequalities``, ``equations`` -- see :class:`Hrep2Vrep` EXAMPLES:: @@ -388,18 +382,18 @@ def __init__(self, base_ring, dim, vertices, rays, lines): INPUT: - - ``base_ring`` -- a field. + - ``base_ring`` -- a field - - ``dim`` -- integer. The ambient space dimension. + - ``dim`` -- integer; the ambient space dimension - - ``vertices`` -- list of vertices. Each vertex is given as - list of ``dim`` coordinates. + - ``vertices`` -- list of vertices; each vertex is given as + list of ``dim`` coordinates - - ``rays`` -- list of rays. Each ray is given as - list of ``dim`` coordinates, not all zero. + - ``rays`` -- list of rays; each ray is given as + list of ``dim`` coordinates, not all zero - - ``lines`` -- list of line generators. Each line is given as - list of ``dim`` coordinates, not all zero. + - ``lines`` -- list of line generators; each line is given as + list of ``dim`` coordinates, not all zero EXAMPLES:: @@ -465,11 +459,9 @@ def _init_Vrep(self, vertices, rays, lines): INPUT: - - ``vertices``, ``rays``, ``lines`` -- see :class:`Vrep2Hrep`. - - OUTPUT: + - ``vertices``, ``rays``, ``lines`` -- see :class:`Vrep2Hrep` - Matrix of pivoted inequalities for the dual homogenized cone. + OUTPUT: matrix of pivoted inequalities for the dual homogenized cone TESTS:: @@ -497,7 +489,7 @@ def _extract_Hrep(self, DD): INPUT: - ``DD`` -- a - :class:`~sage.geometry.polyhedron.double_description.DoubleDescriptionPair`. + :class:`~sage.geometry.polyhedron.double_description.DoubleDescriptionPair` EXAMPLES:: @@ -520,9 +512,7 @@ def _repr_(self): r""" Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -548,7 +538,7 @@ def verify(self, vertices, rays, lines): INPUT: - - ``vertices``, ``rays``, ``lines`` -- see :class:`Vrep2Hrep`. + - ``vertices``, ``rays``, ``lines`` -- see :class:`Vrep2Hrep` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/face.py b/src/sage/geometry/polyhedron/face.py index 97319ed1740..9b72f1fc691 100644 --- a/src/sage/geometry/polyhedron/face.py +++ b/src/sage/geometry/polyhedron/face.py @@ -96,9 +96,7 @@ class PolyhedronFace(ConvexSet_closed): manually create :class:`PolyhedronFace` objects unless you know what you are doing. - OUTPUT: - - A :class:`PolyhedronFace`. + OUTPUT: a :class:`PolyhedronFace` EXAMPLES:: @@ -134,16 +132,16 @@ def __init__(self, polyhedron, V_indices, H_indices): INPUT: - - ``polyhedron`` -- a :class:`Polyhedron`. The ambient - polyhedron. + - ``polyhedron`` -- a :class:`Polyhedron`; the ambient + polyhedron - - ``V_indices`` -- list of sorted integers. The indices of the + - ``V_indices`` -- list of sorted integers; the indices of the face-spanning V-representation objects in the ambient - polyhedron. + polyhedron - - ``H_indices`` -- list of sorted integers. The indices of the + - ``H_indices`` -- list of sorted integers; the indices of the H-representation objects of the ambient polyhedron that are - saturated on the face. + saturated on the face TESTS:: @@ -200,9 +198,7 @@ def vertices(self): """ Return all vertices of the face. - OUTPUT: - - A tuple of vertices. + OUTPUT: a tuple of vertices EXAMPLES:: @@ -222,9 +218,7 @@ def n_vertices(self): """ Return the number of vertices of the face. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -263,9 +257,7 @@ def rays(self): """ Return the rays of the face. - OUTPUT: - - A tuple of rays. + OUTPUT: a tuple of rays EXAMPLES:: @@ -281,9 +273,7 @@ def n_rays(self): """ Return the number of rays of the face. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -318,9 +308,7 @@ def lines(self): """ Return all lines of the face. - OUTPUT: - - A tuple of lines. + OUTPUT: a tuple of lines EXAMPLES:: @@ -335,9 +323,7 @@ def n_lines(self): """ Return the number of lines of the face. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -353,7 +339,7 @@ def __richcmp__(self, other, op): INPUT: - - ``other`` -- anything. + - ``other`` -- anything OUTPUT: @@ -389,8 +375,7 @@ def ambient_Hrepresentation(self, index=None): INPUT: - - ``index`` -- optional. Either an integer or ``None`` - (default). + - ``index`` -- integer or ``None`` (default) OUTPUT: @@ -430,8 +415,7 @@ def ambient_Vrepresentation(self, index=None): INPUT: - - ``index`` -- optional. Either an integer or ``None`` - (default). + - ``index`` -- integer or ``None`` (default) OUTPUT: @@ -471,9 +455,7 @@ def n_ambient_Hrepresentation(self): See also :meth:`ambient_Hrepresentation`. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -497,9 +479,7 @@ def n_ambient_Vrepresentation(self): See also :meth:`ambient_Vrepresentation`. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -520,9 +500,7 @@ def ambient_H_indices(self): See also :meth:`ambient_Hrepresentation`. - OUTPUT: - - Tuple of indices + OUTPUT: tuple of indices EXAMPLES:: @@ -551,9 +529,7 @@ def ambient_V_indices(self): See also :meth:`ambient_Vrepresentation`. - OUTPUT: - - Tuple of indices + OUTPUT: tuple of indices EXAMPLES:: @@ -587,9 +563,7 @@ def dim(self): """ Return the dimension of the face. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -621,9 +595,7 @@ def _repr_(self): r""" Return a string representation. - OUTPUT: - - A string listing the V-representation indices of the face. + OUTPUT: a string listing the V-representation indices of the face EXAMPLES:: @@ -695,7 +667,7 @@ def ambient_vector_space(self, base_field=None): INPUT: - - ``base_field`` -- (default: the fraction field of the base ring) a field. + - ``base_field`` -- a field (default: the fraction field of the base ring) EXAMPLES:: @@ -714,7 +686,7 @@ def is_relatively_open(self): r""" Return whether ``self`` is relatively open. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -731,7 +703,7 @@ def is_compact(self): r""" Return whether ``self`` is compact. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -750,9 +722,7 @@ def as_polyhedron(self, **kwds): """ Return the face as an independent polyhedron. - OUTPUT: - - A polyhedron. + OUTPUT: a polyhedron EXAMPLES:: @@ -851,13 +821,11 @@ def normal_cone(self, direction='outer'): INPUT: - - ``direction`` -- string (default: ``'outer'``), the direction in + - ``direction`` -- string (default: ``'outer'``); the direction in which to consider the normals. The other allowed option is ``'inner'``. - OUTPUT: - - A polyhedron. + OUTPUT: a polyhedron EXAMPLES:: @@ -933,9 +901,7 @@ def affine_tangent_cone(self): It is equal to the sum of ``self`` and the cone of feasible directions at any point of the relative interior of ``self``. - OUTPUT: - - A polyhedron. + OUTPUT: a polyhedron EXAMPLES:: @@ -983,9 +949,7 @@ def stacking_locus(self): Return the polyhedron containing the points that sees every facet containing ``self``. - OUTPUT: - - A polyhedron. + OUTPUT: a polyhedron EXAMPLES:: @@ -1036,7 +1000,7 @@ def combinatorial_face_to_polyhedral_face(polyhedron, combinatorial_face): - ``polyhedron`` -- a polyhedron containing ``combinatorial_face`` - ``combinatorial_face`` -- a :class:`CombinatorialFace` - OUTPUT: a :class:`PolyhedronFace`. + OUTPUT: a :class:`PolyhedronFace` EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/generating_function.py b/src/sage/geometry/polyhedron/generating_function.py index 89d86058c2d..936c761273d 100644 --- a/src/sage/geometry/polyhedron/generating_function.py +++ b/src/sage/geometry/polyhedron/generating_function.py @@ -91,7 +91,7 @@ def generating_function_of_integral_points(polyhedron, split=False, The variable names of the Laurent polynomial ring of the output are this string followed by an integer. - - ``names`` -- a list or tuple of names (strings), or a comma separated string + - ``names`` -- list or tuple of names (strings), or a comma separated string ``name`` is extracted from ``names``, therefore ``names`` has to contain exactly one variable name, and ``name`` and``names`` cannot be specified @@ -697,19 +697,17 @@ def _generating_function_via_Omega_(inequalities, B, skip_indices=()): INPUT: - - ``inequalities`` -- a list or other iterable of tuples - of numbers. + - ``inequalities`` -- list or other iterable of tuples + of numbers - ``B`` -- a Laurent polynomial ring - - ``skip_indices`` -- a list or tuple of indices + - ``skip_indices`` -- list or tuple of indices The variables corresponding to ``skip_indices`` are not handled (e.g. because they are determined by an equation). - OUTPUT: - - A pair of + OUTPUT: a pair of - a Laurent polynomial specifying the numerator and @@ -780,9 +778,9 @@ class _TransformHrepresentation: INPUT: - - ``inequalities`` -- a list of tuples of numbers + - ``inequalities`` -- list of tuples of numbers - - ``equations`` -- a list of tuples of numbers + - ``equations`` -- list of tuples of numbers - ``B`` -- a Laurent polynomial ring @@ -798,7 +796,7 @@ class _TransformHrepresentation: The numerator of the generating function has to be multiplied with ``factor`` *after* substituting ``rules``. - - ``rules`` -- a dictionary mapping Laurent polynomial variables to + - ``rules`` -- dictionary mapping Laurent polynomial variables to Laurent polynomials Substitute ``rules`` into the generating function. @@ -854,7 +852,7 @@ def apply_rules(self, numerator, terms): - ``numerator`` -- a Laurent polynomial - - ``terms`` -- a tuple or other iterable of Laurent polynomials + - ``terms`` -- tuple or other iterable of Laurent polynomials The denominator is the product of factors `1 - t` for each `t` in ``terms``. @@ -887,9 +885,9 @@ class _SplitOffSimpleInequalities(_TransformHrepresentation): INPUT: - - ``inequalities`` -- a list of tuples of numbers + - ``inequalities`` -- list of tuples of numbers - - ``equations`` -- a list of tuples of numbers + - ``equations`` -- list of tuples of numbers - ``B`` -- a Laurent polynomial ring @@ -905,7 +903,7 @@ class _SplitOffSimpleInequalities(_TransformHrepresentation): The numerator of the generating function has to be multiplied with ``factor`` *after* substituting ``rules``. - - ``rules`` -- a dictionary mapping Laurent polynomial variables to + - ``rules`` -- dictionary mapping Laurent polynomial variables to Laurent polynomials Substitute ``rules`` into the generating function. @@ -1197,9 +1195,9 @@ class _EliminateByEquations(_TransformHrepresentation): INPUT: - - ``inequalities`` -- a list of tuples of numbers + - ``inequalities`` -- list of tuples of numbers - - ``equations`` -- a list of tuples of numbers + - ``equations`` -- list of tuples of numbers - ``B`` -- a Laurent polynomial ring @@ -1215,7 +1213,7 @@ class _EliminateByEquations(_TransformHrepresentation): The numerator of the generating function has to be multiplied with ``factor`` *after* substituting ``rules``. - - ``rules`` -- a dictionary mapping Laurent polynomial variables to + - ``rules`` -- dictionary mapping Laurent polynomial variables to Laurent polynomials Substitute ``rules`` into the generating function. @@ -1325,7 +1323,7 @@ def prepare_equations_transformation(E): - ``indicesn`` -- a sorted tuple of integers representing column indices ``indicesn`` contains ``0`` and all indices of the columns of ``E`` - which are non-zero. + which are nonzero. TESTS:: @@ -1365,13 +1363,13 @@ class _TransformMod(_TransformHrepresentation): INPUT: - - ``inequalities`` -- a list of tuples of numbers + - ``inequalities`` -- list of tuples of numbers - - ``equations`` -- a list of tuples of numbers + - ``equations`` -- list of tuples of numbers - ``B`` -- a Laurent polynomial ring - - ``mod`` -- a dictionary mapping an index ``i`` to ``(m, r)`` + - ``mod`` -- dictionary mapping an index ``i`` to ``(m, r)`` This is one entry of the output tuple of :meth:`generate_mods`. @@ -1387,7 +1385,7 @@ class _TransformMod(_TransformHrepresentation): The numerator of the generating function has to be multiplied with ``factor`` *after* substituting ``rules``. - - ``rules`` -- a dictionary mapping Laurent polynomial variables to + - ``rules`` -- dictionary mapping Laurent polynomial variables to Laurent polynomials Substitute ``rules`` into the generating function. @@ -1478,7 +1476,7 @@ def generate_mods(equations): INPUT: - - ``equations`` -- a list of tuples + - ``equations`` -- list of tuples OUTPUT: @@ -1531,7 +1529,7 @@ def _compositions_mod(u, m, r=0, multidimensional=False): - ``m`` -- the modulus as a positive integer - - ``multidimensional`` -- (default: ``False``) a boolean + - ``multidimensional`` -- boolean (default: ``False``) If ``multidimensional=False``: diff --git a/src/sage/geometry/polyhedron/lattice_euclidean_group_element.py b/src/sage/geometry/polyhedron/lattice_euclidean_group_element.py index 79331133960..6d26a0ff267 100644 --- a/src/sage/geometry/polyhedron/lattice_euclidean_group_element.py +++ b/src/sage/geometry/polyhedron/lattice_euclidean_group_element.py @@ -85,11 +85,11 @@ def __init__(self, A, b): def __call__(self, x): """ - Return the image of ``x`` + Return the image of ``x``. INPUT: - - ``x`` -- a vector or lattice polytope. + - ``x`` -- a vector or lattice polytope EXAMPLES:: @@ -115,7 +115,7 @@ def __call__(self, x): def _repr_(self): r""" - Return a string representation + Return a string representation. EXAMPLES:: @@ -130,7 +130,7 @@ def _repr_(self): def domain_dim(self): """ - Return the dimension of the domain lattice + Return the dimension of the domain lattice. EXAMPLES:: @@ -150,7 +150,7 @@ def domain_dim(self): def codomain_dim(self): """ - Return the dimension of the codomain lattice + Return the dimension of the codomain lattice. EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/library.py b/src/sage/geometry/polyhedron/library.py index 0c6a962eb55..97ca4131fe9 100644 --- a/src/sage/geometry/polyhedron/library.py +++ b/src/sage/geometry/polyhedron/library.py @@ -119,7 +119,6 @@ def zero_sum_projection(d, base_ring=None): sage: zero_sum_projection(3, base_ring=AA) # needs sage.rings.number_field [ 0.7071067811865475? -0.7071067811865475? 0] [ 0.4082482904638630? 0.4082482904638630? -0.8164965809277260?] - """ from sage.matrix.constructor import matrix from sage.modules.free_module_element import vector @@ -135,10 +134,10 @@ def project_points(*points, **kwds): INPUT: - - ``points``... -- the points to project. + - ``points``... -- the points to project - ``base_ring`` -- (defaults to ``RDF`` if keyword is ``None`` or not - provided in ``kwds``) the base ring to use. + provided in ``kwds``) the base ring to use The projection is isometric to the orthogonal projection on the hyperplane made of zero sum vector. Hence, if the set of points have all equal sums, @@ -183,7 +182,6 @@ def project_points(*points, **kwds): sage: for i in range(len(V)): # needs sage.combinat sage.rings.number_field ....: for j in range(len(V)): ....: assert (V[i]-V[j]).norm() == (P[i]-P[j]).norm() - """ if not points: return [] @@ -208,10 +206,10 @@ def gale_transform_to_polytope(vectors, base_ring=None, backend=None): - ``vectors`` -- the vectors of the Gale transform - - ``base_ring`` -- string (default: `None`); + - ``base_ring`` -- string (default: ``None``); the base ring to be used for the construction - - ``backend`` -- string (default: `None`); + - ``backend`` -- string (default: ``None``); the backend to use to create the polytope .. NOTE:: @@ -333,15 +331,15 @@ def gale_transform_to_primal(vectors, base_ring=None, backend=None): - ``vectors`` -- the ordered vectors of the Gale transform - - ``base_ring`` -- string (default: `None`); + - ``base_ring`` -- string (default: ``None``); the base ring to be used for the construction - - ``backend`` -- string (default: `None`); + - ``backend`` -- string (default: ``None``); the backend to be use to construct a polyhedral, used internally in case the center is not the origin, see :func:`~sage.geometry.polyhedron.constructor.Polyhedron` - OUTPUT: An ordered point configuration as list of vectors. + OUTPUT: an ordered point configuration as list of vectors .. NOTE:: @@ -500,17 +498,17 @@ def regular_polygon(self, n, exact=True, base_ring=None, backend=None): INPUT: - - ``n`` -- a positive integer, the number of vertices. + - ``n`` -- positive integer; the number of vertices - - ``exact`` -- (boolean, default ``True``) if ``False`` floating point - numbers are used for coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` floating point + numbers are used for coordinates - ``base_ring`` -- a ring in which the coordinates will lie. It is ``None`` by default. If it is not provided and ``exact`` is ``True`` then it will be the field of real algebraic number, if ``exact`` is ``False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -579,9 +577,9 @@ def Birkhoff_polytope(self, n, backend=None): INPUT: - - ``n`` -- a positive integer giving the size of the permutation matrices. + - ``n`` -- positive integer giving the size of the permutation matrices - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope .. SEEALSO:: @@ -632,21 +630,21 @@ def simplex(self, dim=3, project=False, base_ring=None, backend=None): INPUT: - - ``dim`` -- The dimension of the simplex, a positive - integer. + - ``dim`` -- the dimension of the simplex, a positive + integer - - ``project`` -- (boolean, default ``False``) if ``True``, the polytope + - ``project`` -- boolean (default: ``False``); if ``True``, the polytope is (isometrically) projected to a vector space of dimension ``dim-1``. This corresponds to the projection given by the matrix from :func:`zero_sum_projection`. By default, this operation turns the coordinates into floating point approximations (see ``base_ring``). - - ``base_ring`` -- the base ring to use to create the polytope. - If ``project`` is ``False``, this defaults to `\ZZ`. + - ``base_ring`` -- the base ring to use to create the polytope; + if ``project`` is ``False``, this defaults to `\ZZ`. Otherwise, it defaults to ``RDF``. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope .. SEEALSO:: @@ -705,8 +703,8 @@ def icosahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- (optional) the ring in which the coordinates will belong to. Note that this ring must contain `\sqrt(5)`. If it is not @@ -714,7 +712,7 @@ def icosahedron(self, exact=True, base_ring=None, backend=None): `\QQ[\sqrt(5)]` and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -759,8 +757,7 @@ def icosahedron(self, exact=True, base_ring=None, backend=None): sage: TestSuite(ico).run() sage: ico = polytopes.icosahedron(exact=False) # needs sage.groups - sage: TestSuite(ico).run(skip="_test_lawrence") # needs sage.groups - + sage: TestSuite(ico).run(skip='_test_lawrence') # needs sage.groups """ if base_ring is None and exact: from sage.rings.number_field.number_field import QuadraticField @@ -788,8 +785,8 @@ def dodecahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- (optional) the ring in which the coordinates will belong to. Note that this ring must contain `\sqrt(5)`. If it is not @@ -797,7 +794,7 @@ def dodecahedron(self, exact=True, base_ring=None, backend=None): `\QQ[\sqrt(5)]` and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -839,15 +836,15 @@ def small_rhombicuboctahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -911,15 +908,15 @@ def great_rhombicuboctahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -969,7 +966,7 @@ def rhombic_dodecahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope .. SEEALSO:: @@ -1017,7 +1014,7 @@ def cuboctahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope .. SEEALSO:: @@ -1065,15 +1062,15 @@ def truncated_cube(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\sqrt{2}]` and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1099,7 +1096,6 @@ def truncated_cube(self, exact=True, base_ring=None, backend=None): sage: co.f_vector() # optional - pynormaliz # needs sage.rings.number_field (1, 24, 36, 14, 1) sage: TestSuite(co).run() # optional - pynormaliz # needs sage.rings.number_field - """ if base_ring is None and exact: from sage.rings.number_field.number_field import QuadraticField @@ -1129,7 +1125,7 @@ def tetrahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope .. SEEALSO:: @@ -1173,7 +1169,7 @@ def truncated_tetrahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1219,7 +1215,7 @@ def truncated_octahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1263,7 +1259,7 @@ def octahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1306,15 +1302,15 @@ def snub_cube(self, exact=False, base_ring=None, backend=None, verbose=False): INPUT: - - ``exact`` -- (boolean, default ``False``) if ``True`` use exact + - ``exact`` -- boolean (default: ``False``); if ``True`` use exact coordinates instead of floating point approximations - - ``base_ring`` -- the field to use. If ``None`` (the default), + - ``base_ring`` -- the field to use; if ``None`` (the default), construct the exact number field needed (if ``exact`` is ``True``) or - default to ``RDF`` (if ``exact`` is ``True``). + default to ``RDF`` (if ``exact`` is ``True``) - - ``backend`` -- the backend to use to create the polytope. If - ``None`` (the default), the backend will be selected automatically. + - ``backend`` -- the backend to use to create the polytope; if + ``None`` (the default), the backend will be selected automatically EXAMPLES:: @@ -1361,7 +1357,6 @@ def snub_cube(self, exact=False, base_ring=None, backend=None, verbose=False): sage: sc = polytopes.snub_cube(exact=True, backend='normaliz') # optional - pynormaliz, needs sage.groups sage.rings.number_field sage: sc.f_vector() # optional - pynormaliz, needs sage.groups sage.rings.number_field (1, 24, 60, 38, 1) - """ def construct_z(field): # z here is the reciprocal of the tribonacci constant, that is, the @@ -1412,15 +1407,15 @@ def buckyball(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1455,7 +1450,6 @@ def buckyball(self, exact=True, base_ring=None, backend=None): sage: bb.base_ring() Number Field in sqrt5 with defining polynomial x^2 - 5 with sqrt5 = 2.236067977499790? - """ return self.icosahedron(exact=exact, base_ring=base_ring, backend=backend).truncation() @@ -1469,10 +1463,10 @@ def icosidodecahedron(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1530,15 +1524,15 @@ def icosidodecahedron_V2(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - - ``base_ring`` -- the ring in which the coordinates will belong to. + - ``base_ring`` -- the ring in which the coordinates will belong to If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1604,15 +1598,15 @@ def truncated_dodecahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1657,7 +1651,6 @@ def truncated_dodecahedron(self, exact=True, base_ring=None, backend=None): sage: td.base_ring() Number Field in sqrt5 with defining polynomial x^2 - 5 with sqrt5 = 2.236067977499790? - """ if base_ring is None and exact: from sage.rings.number_field.number_field import QuadraticField @@ -1693,15 +1686,15 @@ def pentakis_dodecahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1736,7 +1729,7 @@ def Kirkman_icosahedron(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1775,15 +1768,15 @@ def rhombicosidodecahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1820,7 +1813,6 @@ def rhombicosidodecahedron(self, exact=True, base_ring=None, backend=None): sage: rid.base_ring() Number Field in sqrt5 with defining polynomial x^2 - 5 with sqrt5 = 2.236067977499790? - """ if base_ring is None and exact: from sage.rings.number_field.number_field import QuadraticField @@ -1855,15 +1847,15 @@ def truncated_icosidodecahedron(self, exact=True, base_ring=None, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) If ``False`` use an - approximate ring for the coordinates. + - ``exact`` -- boolean (default: ``True``); if ``False`` use an + approximate ring for the coordinates - ``base_ring`` -- the ring in which the coordinates will belong to. If it is not provided and ``exact=True`` it will be a the number field `\QQ[\phi]` where `\phi` is the golden ratio and if ``exact=False`` it will be the real double field. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -1898,7 +1890,6 @@ def truncated_icosidodecahedron(self, exact=True, base_ring=None, backend=None): (1, 120, 180, 62, 1) sage: ti.base_ring() # optional - pynormaliz Number Field in sqrt5 with defining polynomial x^2 - 5 with sqrt5 = 2.236067977499790? - """ if base_ring is None and exact: from sage.rings.number_field.number_field import QuadraticField @@ -1937,10 +1928,10 @@ def snub_dodecahedron(self, base_ring=None, backend=None, verbose=False): INPUT: - - ``base_ring`` -- the ring in which the coordinates will belong to. If - it is not provided it will be the real double field. + - ``base_ring`` -- the ring in which the coordinates will belong to; if + it is not provided it will be the real double field - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES: @@ -1973,7 +1964,6 @@ def snub_dodecahedron(self, base_ring=None, backend=None, verbose=False): (1, 60, 150, 92, 1) sage: sd.base_ring() # not tested Real Double Field - """ if base_ring is None: from sage.rings.real_double import RDF as base_ring @@ -2012,7 +2002,7 @@ def twenty_four_cell(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2061,10 +2051,10 @@ def runcitruncated_six_hundred_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2090,10 +2080,10 @@ def cantitruncated_six_hundred_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2119,10 +2109,10 @@ def bitruncated_six_hundred_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2148,10 +2138,10 @@ def cantellated_six_hundred_cell(self, exact=False, backend=None): INPUT: - - ``exact`` -- (boolean, default ``False``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``False``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2188,10 +2178,10 @@ def truncated_six_hundred_cell(self, exact=False, backend=None): INPUT: - - ``exact`` -- (boolean, default ``False``) if ``True`` use exact + - ``exact`` -- boolean (default: ``False``); if ``True`` use exact coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2222,10 +2212,10 @@ def rectified_six_hundred_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2248,10 +2238,10 @@ def six_hundred_cell(self, exact=False, backend=None): INPUT: - - ``exact`` -- (boolean, default ``False``) if ``True`` use exact + - ``exact`` -- boolean (default: ``False``); if ``True`` use exact coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2312,10 +2302,10 @@ def grand_antiprism(self, exact=True, backend=None, verbose=False): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``False`` use floating + - ``exact`` -- boolean (default: ``True``); if ``False`` use floating point approximations instead of exact coordinates - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2398,7 +2388,7 @@ def Gosset_3_21(self, backend=None): INPUT: - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2433,13 +2423,13 @@ def cyclic_polytope(self, dim, n, base_ring=QQ, backend=None): INPUT: - - ``dim`` -- positive integer. the dimension of the polytope. + - ``dim`` -- positive integer; the dimension of the polytope - - ``n`` -- positive integer. the number of vertices. + - ``n`` -- positive integer; the number of vertices - - ``base_ring`` -- either ``QQ`` (default) or ``RDF``. + - ``base_ring`` -- either ``QQ`` (default) or ``RDF`` - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2474,13 +2464,13 @@ def hypersimplex(self, dim, k, project=False, backend=None): - ``n`` -- the numbers ``(1,...,n)`` are permuted - - ``project`` -- (boolean, default ``False``) if ``True``, the polytope + - ``project`` -- boolean (default: ``False``); if ``True``, the polytope is (isometrically) projected to a vector space of dimension ``dim-1``. This operation turns the coordinates into floating point approximations and corresponds to the projection given by the matrix from :func:`zero_sum_projection`. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2525,13 +2515,13 @@ def permutahedron(self, n, project=False, backend=None): - ``n`` -- integer - - ``project`` -- (boolean, default ``False``) if ``True``, the polytope + - ``project`` -- boolean (default: ``False``); if ``True``, the polytope is (isometrically) projected to a vector space of dimension ``dim-1``. This operation turns the coordinates into floating point approximations and corresponds to the projection given by the matrix from :func:`zero_sum_projection`. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2595,7 +2585,7 @@ def tri(m): eqns = ((-tri(n),) + tuple(1 for _ in range(n)),) return parent([verts, [], []], [ieqs, eqns], - Vrep_minimal=True, Hrep_minimal=True, pref_rep="Hrep") + Vrep_minimal=True, Hrep_minimal=True, pref_rep='Hrep') def generalized_permutahedron(self, coxeter_type, point=None, exact=True, regular=False, backend=None): r""" @@ -2609,17 +2599,17 @@ def generalized_permutahedron(self, coxeter_type, point=None, exact=True, regula INPUT: - ``coxeter_type`` -- a Coxeter type; given as a pair [type,rank], - where type is a letter and rank is the number of generators. + where type is a letter and rank is the number of generators - - ``point`` -- a list (default: ``None``); a point given by its + - ``point`` -- list (default: ``None``); a point given by its coordinates in the weight basis. If ``None`` is given, the point `(1, 1, 1, \ldots)` is used. - - ``exact`` -- (boolean, default ``True``) if ``False`` use floating + - ``exact`` -- boolean (default: ``True``); if ``False`` use floating point approximations instead of exact coordinates - ``regular`` -- boolean (default: ``False``); whether to apply a - linear transformation making the vertex figures isometric. + linear transformation making the vertex figures isometric - ``backend`` -- backend to use to create the polytope; (default: ``None``) @@ -2855,10 +2845,10 @@ def omnitruncated_one_hundred_twenty_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2888,10 +2878,10 @@ def runcitruncated_one_hundred_twenty_cell(self, exact=False, backend=None): INPUT: - - ``exact`` -- (boolean, default ``False``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``False``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2928,10 +2918,10 @@ def cantitruncated_one_hundred_twenty_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2956,10 +2946,10 @@ def runcinated_one_hundred_twenty_cell(self, exact=False, backend=None): INPUT: - - ``exact`` -- (boolean, default ``False``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``False``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -2995,10 +2985,10 @@ def cantellated_one_hundred_twenty_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -3023,10 +3013,10 @@ def truncated_one_hundred_twenty_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -3051,10 +3041,10 @@ def rectified_one_hundred_twenty_cell(self, exact=True, backend=None): INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -3079,13 +3069,13 @@ def one_hundred_twenty_cell(self, exact=True, backend=None, construction='coxete INPUT: - - ``exact`` -- (boolean, default ``True``) if ``True`` use exact - coordinates instead of floating point approximations. + - ``exact`` -- boolean (default: ``True``); if ``True`` use exact + coordinates instead of floating point approximations - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope - - ``construction`` -- the construction to use (string, default 'coxeter'); - the other possibility is 'as_permutahedron'. + - ``construction`` -- string (default: ``'coxeter'``); the construction to use. + The other possibility is 'as_permutahedron'. EXAMPLES: @@ -3168,21 +3158,21 @@ def hypercube(self, dim, intervals=None, backend=None): INPUT: - - ``dim`` -- integer. The dimension of the hypercube. + - ``dim`` -- integer; the dimension of the hypercube - - ``intervals`` -- (default = None). It takes the following + - ``intervals`` -- (default: ``None``) it takes the following possible inputs: - If ``None`` (the default), it returns the `\pm 1`-cube of dimension ``dim``. - - ``'zero_one'`` -- (string). Return the `0/1`-cube. + - ``'zero_one'`` -- string; return the `0/1`-cube - a list of length ``dim``. Its elements are pairs of numbers `(a,b)` with `a < b`. The cube will be the product of these intervals. - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES: @@ -3356,16 +3346,14 @@ def cube(self, intervals=None, backend=None): - If the input is ``None`` (the default), returns the convex hull of the eight `\pm 1` vectors of length three. - - ``'zero_one'`` -- (string). Return the `0/1`-cube. + - ``'zero_one'`` -- string; return the `0/1`-cube - a list of 3 lists of length 2. The cube will be a product of these three intervals. - - ``backend`` -- the backend to use to create the polytope. - - OUTPUT: + - ``backend`` -- the backend to use to create the polytope - A cube as a polyhedron object. + OUTPUT: a cube as a polyhedron object EXAMPLES: @@ -3407,9 +3395,9 @@ def cross_polytope(self, dim, backend=None): INPUT: - - ``dim`` -- integer. The dimension of the cross-polytope. + - ``dim`` -- integer; the dimension of the cross-polytope - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: @@ -3451,9 +3439,9 @@ def parallelotope(self, generators, backend=None): INPUT: - - ``generators`` -- a list of vectors of same dimension + - ``generators`` -- list of vectors of same dimension - - ``backend`` -- the backend to use to create the polytope. + - ``backend`` -- the backend to use to create the polytope EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/misc.py b/src/sage/geometry/polyhedron/misc.py index b47e51f79b8..e61090e83c8 100644 --- a/src/sage/geometry/polyhedron/misc.py +++ b/src/sage/geometry/polyhedron/misc.py @@ -17,13 +17,11 @@ def _to_space_separated_string(l, base_ring=None): INPUT: - - ``l`` -- anything iterable. + - ``l`` -- anything iterable - ``base_ring`` -- ring (default: ``None``); convert this ring, if given - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -66,11 +64,9 @@ def _make_listlist(x): INPUT: - - ``x`` -- ``None`` or an iterable of iterables. - - OUTPUT: + - ``x`` -- ``None`` or an iterable of iterables - A list of lists. + OUTPUT: list of lists EXAMPLES:: @@ -91,7 +87,7 @@ def _common_length_of(l1, l2=None, l3=None): """ The arguments are containers or ``None``. The function applies ``len()`` to each element, and returns the common length. If the - length differs, ``ValueError`` is raised. Used to check arguments. + length differs, :exc:`ValueError` is raised. Used to check arguments. OUTPUT: diff --git a/src/sage/geometry/polyhedron/modules/formal_polyhedra_module.py b/src/sage/geometry/polyhedron/modules/formal_polyhedra_module.py index 6255650b84f..b17c2a1ce71 100644 --- a/src/sage/geometry/polyhedron/modules/formal_polyhedra_module.py +++ b/src/sage/geometry/polyhedron/modules/formal_polyhedra_module.py @@ -30,9 +30,9 @@ class FormalPolyhedraModule(CombinatorialFreeModule): A three-dimensional vector space of polyhedra:: - sage: I01 = closed_interval(0, 1); I01.rename("conv([0], [1])") - sage: I11 = closed_interval(1, 1); I11.rename("{[1]}") - sage: I12 = closed_interval(1, 2); I12.rename("conv([1], [2])") + sage: I01 = closed_interval(0, 1); I01.rename('conv([0], [1])') + sage: I11 = closed_interval(1, 1); I11.rename('{[1]}') + sage: I12 = closed_interval(1, 2); I12.rename('conv([1], [2])') sage: basis = [I01, I11, I12] sage: M = FormalPolyhedraModule(QQ, 1, basis=basis); M Free module generated by {conv([0], [1]), {[1]}, conv([1], [2])} over Rational Field @@ -67,7 +67,6 @@ class FormalPolyhedraModule(CombinatorialFreeModule): Q[conv([0], [1])] + Q[conv([1], [2])] sage: M_mod_lower.retract(M(I01) - 2*M(I11) + M(I12)) == M_mod_lower.retract(M(I01) + M(I12)) True - """ @staticmethod @@ -106,14 +105,14 @@ def __init__(self, base_ring, dimension, basis, category): sage: from sage.geometry.polyhedron.modules.formal_polyhedra_module import FormalPolyhedraModule sage: def closed_interval(a,b): return Polyhedron(vertices=[[a], [b]]) - sage: I01 = closed_interval(0, 1); I01.rename("conv([0], [1])") - sage: I11 = closed_interval(1, 1); I11.rename("{[1]}") - sage: I12 = closed_interval(1, 2); I12.rename("conv([1], [2])") - sage: I02 = closed_interval(0, 2); I02.rename("conv([0], [2])") + sage: I01 = closed_interval(0, 1); I01.rename('conv([0], [1])') + sage: I11 = closed_interval(1, 1); I11.rename('{[1]}') + sage: I12 = closed_interval(1, 2); I12.rename('conv([1], [2])') + sage: I02 = closed_interval(0, 2); I02.rename('conv([0], [2])') sage: M = FormalPolyhedraModule(QQ, 1, basis=[I01, I11, I12, I02]) sage: TestSuite(M).run() """ - super().__init__(base_ring, basis, prefix="", category=category) + super().__init__(base_ring, basis, prefix='', category=category) def degree_on_basis(self, m): r""" @@ -127,10 +126,10 @@ def degree_on_basis(self, m): sage: from sage.geometry.polyhedron.modules.formal_polyhedra_module import FormalPolyhedraModule sage: def closed_interval(a,b): return Polyhedron(vertices=[[a], [b]]) - sage: I01 = closed_interval(0, 1); I01.rename("conv([0], [1])") - sage: I11 = closed_interval(1, 1); I11.rename("{[1]}") - sage: I12 = closed_interval(1, 2); I12.rename("conv([1], [2])") - sage: I02 = closed_interval(0, 2); I02.rename("conv([0], [2])") + sage: I01 = closed_interval(0, 1); I01.rename('conv([0], [1])') + sage: I11 = closed_interval(1, 1); I11.rename('{[1]}') + sage: I12 = closed_interval(1, 2); I12.rename('conv([1], [2])') + sage: I02 = closed_interval(0, 2); I02.rename('conv([0], [2])') sage: M = FormalPolyhedraModule(QQ, 1, basis=[I01, I11, I12, I02]) We can extract homogeneous components:: diff --git a/src/sage/geometry/polyhedron/palp_database.py b/src/sage/geometry/polyhedron/palp_database.py index 60846d8df23..6432d62080f 100644 --- a/src/sage/geometry/polyhedron/palp_database.py +++ b/src/sage/geometry/polyhedron/palp_database.py @@ -48,10 +48,9 @@ class PALPreader(SageObject): """ Read PALP database of polytopes. - INPUT: - - ``dim`` -- integer. The dimension of the polyhedra + - ``dim`` -- integer; the dimension of the polyhedra - ``data_basename`` -- string or ``None`` (default). The directory and database base filename (PALP usually uses ``'zzdb'``) name @@ -96,7 +95,7 @@ class PALPreader(SageObject): def __init__(self, dim, data_basename=None, output='Polyhedron'): """ - The Python constructor + The Python constructor. See :class:`PALPreader` for documentation. @@ -125,9 +124,7 @@ def _palp_Popen(self): """ Open PALP. - OUTPUT: - - A PALP subprocess. + OUTPUT: a PALP subprocess EXAMPLES:: @@ -144,9 +141,7 @@ def _read_vertices(self, stdout, rows, cols): r""" Read vertex data from the PALP output pipe. - OUTPUT: - - A list of lists. + OUTPUT: list of lists EXAMPLES:: @@ -168,9 +163,7 @@ def _read_vertices_transposed(self, stdout, rows, cols): r""" Read vertex data from the PALP output pipe. - OUTPUT: - - A list of lists. + OUTPUT: list of lists EXAMPLES:: @@ -194,11 +187,9 @@ def _iterate_list(self, start, stop, step): INPUT: - ``start``, ``stop``, ``step`` -- integers specifying the - range to iterate over. - - OUTPUT: + range to iterate over - A generator for vertex data as a list of lists. + OUTPUT: a generator for vertex data as a list of lists EXAMPLES:: @@ -246,11 +237,9 @@ def _iterate_Polyhedron(self, start, stop, step): INPUT: - ``start``, ``stop``, ``step`` -- integers specifying the - range to iterate over. + range to iterate over - OUTPUT: - - A generator for lattice polyhedra. + OUTPUT: a generator for lattice polyhedra EXAMPLES:: @@ -272,11 +261,9 @@ def _iterate_PPL(self, start, stop, step): INPUT: - ``start``, ``stop``, ``step`` -- integers specifying the - range to iterate over. - - OUTPUT: + range to iterate over - A generator for PPL-based lattice polyhedra. + OUTPUT: a generator for PPL-based lattice polyhedra EXAMPLES:: @@ -296,11 +283,9 @@ def _iterate_PointCollection(self, start, stop, step): INPUT: - ``start``, ``stop``, ``step`` -- integers specifying the - range to iterate over. - - OUTPUT: + range to iterate over - A generator for PPL-based lattice polyhedra. + OUTPUT: a generator for PPL-based lattice polyhedra EXAMPLES:: @@ -326,11 +311,9 @@ def _iterate(self, output=None): INPUT: - - ``output`` -- as in the :class:`PALPreader` constructor. + - ``output`` -- as in the :class:`PALPreader` constructor - OUTPUT: - - A function generating lattice polytopes in the specified output format. + OUTPUT: a function generating lattice polytopes in the specified output format EXAMPLES:: @@ -360,9 +343,7 @@ def __iter__(self): """ Iterate over all polytopes. - OUTPUT: - - An iterator for all polytopes. + OUTPUT: an iterator for all polytopes TESTS:: @@ -405,8 +386,8 @@ class Reflexive4dHodge(PALPreader): INPUT: - - ``h11``, ``h21`` -- Integers. The Hodge numbers of the reflexive - polytopes to list. + - ``h11``, ``h21`` -- integer; the Hodge numbers of the reflexive + polytopes to list Any additional keyword arguments are passed to :class:`PALPreader`. @@ -449,9 +430,7 @@ def _palp_Popen(self): """ Open PALP. - OUTPUT: - - A PALP subprocess. + OUTPUT: a PALP subprocess EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/parent.py b/src/sage/geometry/polyhedron/parent.py index 79a77e51556..e26948de9fd 100644 --- a/src/sage/geometry/polyhedron/parent.py +++ b/src/sage/geometry/polyhedron/parent.py @@ -30,36 +30,36 @@ def Polyhedra(ambient_space_or_base_ring=None, ambient_dim=None, backend=None, *, ambient_space=None, base_ring=None): r""" - Construct a suitable parent class for polyhedra + Construct a suitable parent class for polyhedra. INPUT: - - ``base_ring`` -- A ring. Currently there are backends for `\ZZ`, - `\QQ`, and `\RDF`. + - ``base_ring`` -- a ring; currently there are backends for `\ZZ`, + `\QQ`, and `\RDF` - - ``ambient_dim`` -- integer. The ambient space dimension. + - ``ambient_dim`` -- integer; the ambient space dimension - - ``ambient_space`` -- A free module. + - ``ambient_space`` -- a free module - ``backend`` -- string. The name of the backend for computations. There are - several backends implemented: + several backends implemented: - * ``backend="ppl"`` uses the Parma Polyhedra Library + * ``backend="ppl"`` uses the Parma Polyhedra Library - * ``backend="cdd"`` uses CDD + * ``backend="cdd"`` uses CDD - * ``backend="normaliz"`` uses normaliz + * ``backend="normaliz"`` uses normaliz - * ``backend="polymake"`` uses polymake + * ``backend="polymake"`` uses polymake - * ``backend="field"`` a generic Sage implementation + * ``backend="field"`` a generic Sage implementation OUTPUT: A parent class for polyhedra over the given base ring if the backend supports it. If not, the parent base ring can be larger (for example, `\QQ` instead of `\ZZ`). If there is no - implementation at all, a ``ValueError`` is raised. + implementation at all, a :exc:`ValueError` is raised. EXAMPLES:: @@ -125,7 +125,6 @@ def Polyhedra(ambient_space_or_base_ring=None, ambient_dim=None, backend=None, * sage: Polyhedra(SCR, 2, backend='number_field') # needs sage.symbolic Polyhedra in (Symbolic Constants Subring)^2 - """ if ambient_space_or_base_ring is not None: if ambient_space_or_base_ring in Rings(): @@ -202,13 +201,13 @@ class Polyhedra_base(UniqueRepresentation, Parent): INPUT: - - ``base_ring`` -- either ``ZZ``, ``QQ``, or ``RDF``. The base - ring of the ambient module/vector space. + - ``base_ring`` -- either ``ZZ``, ``QQ``, or ``RDF``; the base + ring of the ambient module/vector space - - ``ambient_dim`` -- integer. The ambient space dimension. + - ``ambient_dim`` -- integer; the ambient space dimension - - ``backend`` -- string. The name of the backend for computations. There are - several backends implemented: + - ``backend`` -- string; the name of the backend for computations. There are + several backends implemented: * ``backend="ppl"`` uses the Parma Polyhedra Library @@ -263,7 +262,7 @@ def __init__(self, base_ring, ambient_dim, backend): def list(self): """ - Return the two polyhedra in ambient dimension 0, raise an error otherwise + Return the two polyhedra in ambient dimension 0, raise an error otherwise. EXAMPLES:: @@ -297,8 +296,7 @@ def recycle(self, polyhedron): INPUT: - - ``polyhedron`` -- a polyhedron whose parent is ``self``. - + - ``polyhedron`` -- a polyhedron whose parent is ``self`` EXAMPLES:: @@ -465,9 +463,7 @@ def Vrepresentation_space(self): This is the vector space or module containing the Vrepresentation vectors. - OUTPUT: - - A free module over the base ring of dimension :meth:`ambient_dim`. + OUTPUT: a free module over the base ring of dimension :meth:`ambient_dim` EXAMPLES:: @@ -490,9 +486,7 @@ def Hrepresentation_space(self): r""" Return the linear space containing the H-representation vectors. - OUTPUT: - - A free module over the base ring of dimension :meth:`ambient_dim` + 1. + OUTPUT: a free module over the base ring of dimension :meth:`ambient_dim` + 1 EXAMPLES:: @@ -540,9 +534,7 @@ def _repr_ambient_module(self) -> str: Return an abbreviated string representation of the ambient space. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -562,9 +554,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -582,16 +572,15 @@ def _element_constructor_(self, *args, **kwds): INPUT: - - ``Vrep`` -- a list ``[vertices, rays, lines]`` or ``None``. + - ``Vrep`` -- list ``[vertices, rays, lines]`` or ``None`` - - ``Hrep`` -- a list ``[ieqs, eqns]`` or ``None``. + - ``Hrep`` -- list ``[ieqs, eqns]`` or ``None`` - - ``convert`` -- boolean keyword argument (default: - ``True``). Whether to convert the coordinates into the base - ring. + - ``convert`` -- boolean (default: ``True``); whether to convert the + coordinates into the base ring - - ``**kwds`` -- optional remaining keywords that are passed to the - polyhedron constructor. + - ``**kwds`` -- (optional) remaining keywords that are passed to the + polyhedron constructor EXAMPLES:: @@ -747,9 +736,9 @@ def base_extend(self, base_ring, backend=None, ambient_dim=None): INPUT: - ``base_ring``, ``backend`` -- see - :func:`~sage.geometry.polyhedron.constructor.Polyhedron`. + :func:`~sage.geometry.polyhedron.constructor.Polyhedron` - ``ambient_dim`` -- if not ``None`` change ambient dimension - accordingly. + accordingly EXAMPLES:: @@ -783,9 +772,9 @@ def change_ring(self, base_ring, backend=None, ambient_dim=None): INPUT: - ``base_ring``, ``backend`` -- see - :func:`~sage.geometry.polyhedron.constructor.Polyhedron`. + :func:`~sage.geometry.polyhedron.constructor.Polyhedron` - ``ambient_dim`` -- if not ``None`` change ambient dimension - accordingly. + accordingly EXAMPLES:: @@ -835,7 +824,7 @@ def _coerce_base_ring(self, other): OUTPUT: - Either `\ZZ`, `\QQ`, or `RDF`. Raises :class:`TypeError` if + Either `\ZZ`, `\QQ`, or `RDF`. Raises :exc:`TypeError` if ``other`` is not a suitable input. .. NOTE:: @@ -918,11 +907,9 @@ def _coerce_map_from_(self, X): INPUT: - - ``X`` -- anything. - - OUTPUT: + - ``X`` -- anything - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -949,16 +936,14 @@ def _get_action_(self, other, op, self_is_left): INPUT: - - ``other`` -- a scalar or a vector. + - ``other`` -- a scalar or a vector - - ``op`` -- the operator. + - ``op`` -- the operator - - ``self_is_left`` -- boolean. Whether ``self`` is on the left - of the operator. + - ``self_is_left`` -- boolean; whether ``self`` is on the left + of the operator - OUTPUT: - - An action that is used by the coercion model. + OUTPUT: an action that is used by the coercion model EXAMPLES:: @@ -1003,7 +988,6 @@ def _get_action_(self, other, op, self_is_left): Identity endomorphism of Polyhedra in ZZ^2 with precomposition on right by Generic endomorphism of Ambient free module of rank 2 over the principal ideal domain Integer Ring - """ import operator from sage.structure.coerce_actions import ActedUponAction @@ -1046,13 +1030,11 @@ def _make_Inequality(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. + - ``polyhedron`` -- the new polyhedron - - ``data`` -- the H-representation data. + - ``data`` -- the H-representation data - OUTPUT: - - A new :class:`~sage.geometry.polyhedron.representation.Inequality` object. + OUTPUT: a new :class:`~sage.geometry.polyhedron.representation.Inequality` object EXAMPLES:: @@ -1073,13 +1055,11 @@ def _make_Equation(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. - - - ``data`` -- the H-representation data. + - ``polyhedron`` -- the new polyhedron - OUTPUT: + - ``data`` -- the H-representation data - A new :class:`~sage.geometry.polyhedron.representation.Equation` object. + OUTPUT: a new :class:`~sage.geometry.polyhedron.representation.Equation` object EXAMPLES:: @@ -1100,13 +1080,11 @@ def _make_Vertex(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. + - ``polyhedron`` -- the new polyhedron - - ``data`` -- the V-representation data. + - ``data`` -- the V-representation data - OUTPUT: - - A new :class:`~sage.geometry.polyhedron.representation.Vertex` object. + OUTPUT: a new :class:`~sage.geometry.polyhedron.representation.Vertex` object EXAMPLES:: @@ -1127,13 +1105,11 @@ def _make_Ray(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. - - - ``data`` -- the V-representation data. + - ``polyhedron`` -- the new polyhedron - OUTPUT: + - ``data`` -- the V-representation data - A new :class:`~sage.geometry.polyhedron.representation.Ray` object. + OUTPUT: a new :class:`~sage.geometry.polyhedron.representation.Ray` object EXAMPLES:: @@ -1154,13 +1130,11 @@ def _make_Line(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. - - - ``data`` -- the V-representation data. + - ``polyhedron`` -- the new polyhedron - OUTPUT: + - ``data`` -- the V-representation data - A new :class:`~sage.geometry.polyhedron.representation.Line` object. + OUTPUT: a new :class:`~sage.geometry.polyhedron.representation.Line` object EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/plot.py b/src/sage/geometry/polyhedron/plot.py index 9c8a93624ec..ed6657c6826 100644 --- a/src/sage/geometry/polyhedron/plot.py +++ b/src/sage/geometry/polyhedron/plot.py @@ -164,8 +164,8 @@ def __init__(self, projection_point): INPUT: - - ``projection_point`` -- a list of coordinates in the - appropriate dimension, which is the point projected from. + - ``projection_point`` -- list of coordinates in the + appropriate dimension, which is the point projected from EXAMPLES:: @@ -185,7 +185,7 @@ def __init__(self, projection_point): pproj = vector(RDF, self.projection_point) self.psize = norm(pproj) if (self.psize).is_zero(): - raise ValueError("projection direction must be a non-zero vector.") + raise ValueError("projection direction must be a nonzero vector.") v = vector(RDF, [0.0] * (self.dim - 1) + [-self.psize]) - pproj polediff = matrix(RDF, v).transpose() denom = RDF((polediff.transpose() * polediff)[0][0]) @@ -203,7 +203,7 @@ def __call__(self, x): INPUT: - - ``x`` -- a vector or anything convertible to a vector. + - ``x`` -- a vector or anything convertible to a vector OUTPUT: @@ -253,7 +253,7 @@ class ProjectionFuncSchlegel: """ def __init__(self, facet, projection_point): """ - Initializes the projection. + Initialize the projection. EXAMPLES:: @@ -297,7 +297,7 @@ def __call__(self, x): """ Apply the projection to a vector. - - ``x`` -- a vector or anything convertible to a vector. + - ``x`` -- a vector or anything convertible to a vector EXAMPLES:: @@ -453,8 +453,8 @@ def stereographic(self, projection_point=None): INPUT: - - ``projection_point`` -- The projection point. This must be - distinct from the polyhedron's vertices. Default is `(1,0,\dots,0)` + - ``projection_point`` -- the projection point. This must be + distinct from the polyhedron's vertices. Default is `(1,0,\dots,0)`. EXAMPLES:: @@ -481,7 +481,7 @@ def schlegel(self, facet=None, position=None): INPUT: - - ``facet`` -- a PolyhedronFace. The facet into which the Schlegel + - ``facet`` -- a PolyhedronFace; the facet into which the Schlegel diagram is created. The default is the first facet. - ``position`` -- a positive number. Determines a relative distance @@ -909,11 +909,9 @@ def render_points_1d(self, **kwds): INPUT: - ``**kwds`` -- options passed through to - :func:`~sage.plot.point.point2d`. + :func:`~sage.plot.point.point2d` - OUTPUT: - - A 2-d graphics object. + OUTPUT: a 2-d graphics object EXAMPLES:: @@ -932,11 +930,9 @@ def render_line_1d(self, **kwds): INPUT: - ``**kwds`` -- options passed through to - :func:`~sage.plot.line.line2d`. - - OUTPUT: + :func:`~sage.plot.line.line2d` - A 2-d graphics object. + OUTPUT: a 2-d graphics object EXAMPLES:: @@ -1071,9 +1067,7 @@ def render_0d(self, point_opts=None, line_opts=None, polygon_opts=None): See :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot`. - OUTPUT: - - A 2-d graphics object. + OUTPUT: a 2-d graphics object EXAMPLES:: @@ -1103,9 +1097,7 @@ def render_1d(self, point_opts=None, line_opts=None, polygon_opts=None): See :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.plot`. - OUTPUT: - - A 2-d graphics object. + OUTPUT: a 2-d graphics object EXAMPLES:: @@ -1251,28 +1243,26 @@ def tikz(self, view=[0, 0, 1], angle=0, scale=1, INPUT: - - ``view`` -- list (default: [0,0,1]) representing the rotation axis (see note below). - - ``angle`` -- integer (default: 0) angle of rotation in degree from 0 to 360 (see note - below). - - ``scale`` -- integer (default: 1) specifying the scaling of the tikz picture. - - ``edge_color`` -- string (default: 'blue!95!black') representing colors which tikz - recognize. - - ``facet_color`` -- string (default: 'blue!95!black') representing colors which tikz - recognize. - - ``vertex_color`` -- string (default: 'green') representing colors which tikz - recognize. + - ``view`` -- list (default: [0,0,1]) representing the rotation axis (see note below) + - ``angle`` -- integer (default: 0); angle of rotation in degree from 0 to 360 (see note + below) + - ``scale`` -- integer (default: 1); the scaling of the tikz picture + - ``edge_color`` -- string (default: ``'blue!95!black'``); representing colors which tikz + recognizes + - ``facet_color`` -- string (default: ``'blue!95!black'``); representing colors which tikz + recognizes + - ``vertex_color`` -- string (default: ``'green'``); representing colors which tikz + recognizes - ``opacity`` -- real number (default: 0.8) between 0 and 1 giving the opacity of - the front facets. - - ``axis`` -- Boolean (default: ``False``) draw the axes at the origin or not. - - ``output_type`` -- string (default: ``None``), valid values + the front facets + - ``axis`` -- boolean (default: ``False``); draw the axes at the origin or not + - ``output_type`` -- string (default: ``None``); valid values are ``None`` (deprecated), ``'LatexExpr'`` and ``'TikzPicture'``, whether to return a :class:`LatexExpr` object (which inherits from Python :class:`str`) or a :class:`TikzPicture` object from module :mod:`sage.misc.latex_standalone` - OUTPUT: - - :class:`LatexExpr` object or :class:`TikzPicture` object + OUTPUT: :class:`LatexExpr` object or :class:`TikzPicture` object .. NOTE:: @@ -1476,16 +1466,16 @@ def _tikz_2d(self, scale, edge_color, facet_color, opacity, vertex_color, axis): INPUT: - - ``scale`` -- integer specifying the scaling of the tikz picture. + - ``scale`` -- integer specifying the scaling of the tikz picture - ``edge_color`` -- string representing colors which tikz - recognize. + recognizes - ``facet_color`` -- string representing colors which tikz - recognize. + recognizes - ``vertex_color`` -- string representing colors which tikz - recognize. + recognizes - ``opacity`` -- real number between 0 and 1 giving the opacity of - the front facets. - - ``axis`` -- Boolean (default: ``False``) draw the axes at the origin or not. + the front facets + - ``axis`` -- boolean (default: ``False``); draw the axes at the origin or not OUTPUT: @@ -1606,22 +1596,20 @@ def _tikz_2d_in_3d(self, view, angle, scale, edge_color, facet_color, INPUT: - - ``view`` -- list (default: [0,0,1]) representing the rotation axis. - - ``angle`` -- integer angle of rotation in degree from 0 to 360. - - ``scale`` -- integer specifying the scaling of the tikz picture. + - ``view`` -- list (default: [0,0,1]) representing the rotation axis + - ``angle`` -- integer angle of rotation in degree from 0 to 360 + - ``scale`` -- integer specifying the scaling of the tikz picture - ``edge_color`` -- string representing colors which tikz - recognize. + recognizes - ``facet_color`` -- string representing colors which tikz - recognize. + recognizes - ``vertex_color`` -- string representing colors which tikz - recognize. + recognizes - ``opacity`` -- real number between 0 and 1 giving the opacity of - the front facets. - - ``axis`` -- Boolean draw the axes at the origin or not. - - OUTPUT: + the front facets + - ``axis`` -- boolean draw the axes at the origin or not - :class:`LatexExpr` -- containing the TikZ picture. + OUTPUT: :class:`LatexExpr` -- containing the TikZ picture EXAMPLES:: @@ -1760,22 +1748,20 @@ def _tikz_3d_in_3d(self, view, angle, scale, edge_color, INPUT: - - ``view`` -- list (default: [0,0,1]) representing the rotation axis. - - ``angle`` -- integer angle of rotation in degree from 0 to 360. - - ``scale`` -- integer specifying the scaling of the tikz picture. + - ``view`` -- list (default: [0,0,1]) representing the rotation axis + - ``angle`` -- integer angle of rotation in degree from 0 to 360 + - ``scale`` -- integer specifying the scaling of the tikz picture - ``edge_color`` -- string representing colors which tikz - recognize. + recognizes - ``facet_color`` -- string representing colors which tikz - recognize. + recognizes - ``vertex_color`` -- string representing colors which tikz - recognize. + recognizes - ``opacity`` -- real number between 0 and 1 giving the opacity of - the front facets. - - ``axis`` -- Boolean draw the axes at the origin or not. - - OUTPUT: + the front facets + - ``axis`` -- boolean draw the axes at the origin or not - :class:`LatexExpr` -- containing the TikZ picture. + OUTPUT: :class:`LatexExpr` -- containing the TikZ picture. EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/ppl_lattice_polygon.py b/src/sage/geometry/polyhedron/ppl_lattice_polygon.py index a3ddeda66a2..dc100230745 100644 --- a/src/sage/geometry/polyhedron/ppl_lattice_polygon.py +++ b/src/sage/geometry/polyhedron/ppl_lattice_polygon.py @@ -32,7 +32,7 @@ ######################################################################## class LatticePolygon_PPL_class(LatticePolytope_PPL_class): """ - A lattice polygon + A lattice polygon. This includes 2-dimensional polytopes as well as degenerate (0 and 1-dimensional) lattice polygons. Any polytope in 2d is a polygon. @@ -80,12 +80,12 @@ def ordered_vertices(self): def _find_isomorphism_degenerate(self, polytope): """ - Helper to pick an isomorphism of degenerate polygons + Helper to pick an isomorphism of degenerate polygons. INPUT: - - ``polytope`` -- a :class:`LatticePolytope_PPL_class`. The - polytope to compare with. + - ``polytope`` -- a :class:`LatticePolytope_PPL_class`; the + polytope to compare with EXAMPLES:: @@ -177,19 +177,19 @@ def _find_cyclic_isomorphism_matching_edge(self, polytope, polytope_origin, p_ray_left, p_ray_right): r""" - Helper to find an isomorphism of polygons + Helper to find an isomorphism of polygons. INPUT: - - ``polytope`` -- the lattice polytope to compare to. + - ``polytope`` -- the lattice polytope to compare to - - ``polytope_origin`` -- `\ZZ`-vector. a vertex of ``polytope`` + - ``polytope_origin`` -- `\ZZ`-vector; a vertex of ``polytope`` - - ``p_ray_left`` -- vector. the vector from ``polytope_origin`` - to one of its neighboring vertices. + - ``p_ray_left`` -- vector; the vector from ``polytope_origin`` + to one of its neighboring vertices - - ``p_ray_right`` -- vector. the vector from - ``polytope_origin`` to the other neighboring vertices. + - ``p_ray_right`` -- vector; the vector from + ``polytope_origin`` to the other neighboring vertices OUTPUT: @@ -247,7 +247,7 @@ def find_isomorphism(self, polytope): INPUT: - - ``polytope`` -- a polytope, potentially higher-dimensional. + - ``polytope`` -- a polytope, potentially higher-dimensional OUTPUT: @@ -337,11 +337,9 @@ def is_isomorphic(self, polytope): INPUT: - - ``polytope`` -- a lattice polytope. + - ``polytope`` -- a lattice polytope - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -399,9 +397,7 @@ def plot(self): """ Plot the lattice polygon. - OUTPUT: - - A graphics object. + OUTPUT: a graphics object EXAMPLES:: @@ -437,7 +433,7 @@ def plot(self): @cached_function def polar_P2_polytope(): """ - The polar of the `P^2` polytope + The polar of the `P^2` polytope. EXAMPLES:: @@ -453,7 +449,7 @@ def polar_P2_polytope(): @cached_function def polar_P1xP1_polytope(): r""" - The polar of the `P^1 \times P^1` polytope + The polar of the `P^1 \times P^1` polytope. EXAMPLES:: @@ -469,7 +465,7 @@ def polar_P1xP1_polytope(): @cached_function def polar_P2_112_polytope(): """ - The polar of the `P^2[1,1,2]` polytope + The polar of the `P^2[1,1,2]` polytope. EXAMPLES:: @@ -485,11 +481,9 @@ def polar_P2_112_polytope(): @cached_function def subpolygons_of_polar_P2(): """ - The lattice sub-polygons of the polar `P^2` polytope - - OUTPUT: + The lattice sub-polygons of the polar `P^2` polytope. - A tuple of lattice polytopes. + OUTPUT: a tuple of lattice polytopes EXAMPLES:: @@ -503,11 +497,9 @@ def subpolygons_of_polar_P2(): @cached_function def subpolygons_of_polar_P2_112(): """ - The lattice sub-polygons of the polar `P^2[1,1,2]` polytope - - OUTPUT: + The lattice sub-polygons of the polar `P^2[1,1,2]` polytope. - A tuple of lattice polytopes. + OUTPUT: a tuple of lattice polytopes EXAMPLES:: @@ -521,11 +513,9 @@ def subpolygons_of_polar_P2_112(): @cached_function def subpolygons_of_polar_P1xP1(): r""" - The lattice sub-polygons of the polar `P^1 \times P^1` polytope - - OUTPUT: + The lattice sub-polygons of the polar `P^1 \times P^1` polytope. - A tuple of lattice polytopes. + OUTPUT: a tuple of lattice polytopes EXAMPLES:: diff --git a/src/sage/geometry/polyhedron/ppl_lattice_polytope.py b/src/sage/geometry/polyhedron/ppl_lattice_polytope.py index 3cde1c6af81..27874340a51 100644 --- a/src/sage/geometry/polyhedron/ppl_lattice_polytope.py +++ b/src/sage/geometry/polyhedron/ppl_lattice_polytope.py @@ -87,11 +87,9 @@ def _class_for_LatticePolytope(dim): INPUT: - - ``dim`` -- integer. The ambient space dimension. + - ``dim`` -- integer; the ambient space dimension - OUTPUT: - - The appropriate class for the lattice polytope. + OUTPUT: the appropriate class for the lattice polytope EXAMPLES:: @@ -129,7 +127,7 @@ def LatticePolytope_PPL(*args): sage: LatticePolytope_PPL(P) # needs pplpy A 0-dimensional lattice polytope in ZZ^2 with 1 vertex - A ``TypeError`` is raised if the arguments do not specify a lattice polytope:: + A :exc:`TypeError` is raised if the arguments do not specify a lattice polytope:: sage: from sage.geometry.polyhedron.ppl_lattice_polytope import LatticePolytope_PPL sage: LatticePolytope_PPL((0,0), (1/2,1)) # needs pplpy @@ -195,11 +193,9 @@ class LatticePolytope_PPL_class(C_Polyhedron): def __repr__(self): """ - Return the string representation - - OUTPUT: + Return the string representation. - A string. + OUTPUT: string EXAMPLES:: @@ -233,9 +229,7 @@ def is_bounded(self): """ Return whether the lattice polytope is compact. - OUTPUT: - - Always ``True``, since polytopes are by definition compact. + OUTPUT: always ``True``, since polytopes are by definition compact EXAMPLES:: @@ -250,9 +244,7 @@ def n_vertices(self): """ Return the number of vertices. - OUTPUT: - - An integer, the number of vertices. + OUTPUT: integer; the number of vertices EXAMPLES:: @@ -344,7 +336,7 @@ def integral_points(self): OUTPUT: The list of integral points in the polyhedron. If the - polyhedron is not compact, a ``ValueError`` is raised. + polyhedron is not compact, a :exc:`ValueError` is raised. EXAMPLES:: @@ -508,7 +500,7 @@ def vertices_saturating(self, constraint): INPUT: - ``constraint`` -- a constraint (inequality or equation) of - the polytope. + the polytope OUTPUT: @@ -537,10 +529,8 @@ def is_full_dimensional(self): """ Return whether the lattice polytope is full dimensional. - OUTPUT: - - Boolean. Whether the :meth:`affine_dimension` equals the - ambient space dimension. + OUTPUT: boolean; whether the :meth:`affine_dimension` equals the + ambient space dimension EXAMPLES:: @@ -566,8 +556,8 @@ def fibration_generator(self, dim): INPUT: - - ``dim`` -- integer. The dimension of the lattice polytope - fiber. + - ``dim`` -- integer; the dimension of the lattice polytope + fiber OUTPUT: @@ -635,8 +625,8 @@ def pointsets_mod_automorphism(self, pointsets): INPUT: - - ``polytopes`` -- a tuple/list/iterable of subsets of the - integral points of ``self``. + - ``polytopes`` -- tuple/list/iterable of subsets of the + integral points of ``self`` OUTPUT: @@ -713,10 +703,10 @@ def contains(self, point_coordinates): INPUT: - - ``point_coordinates`` -- a list/tuple/iterable of rational - numbers. The coordinates of the point. + - ``point_coordinates`` -- list/tuple/iterable of rational + numbers; the coordinates of the point - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -737,9 +727,9 @@ def contains(self, point_coordinates): @cached_method def contains_origin(self): """ - Test whether the polytope contains the origin + Test whether the polytope contains the origin. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -877,13 +867,11 @@ def base_rays(self, fiber, points): INPUT: - ``fiber`` -- a sub-lattice polytope defining the - :meth:`base_projection`. + :meth:`base_projection` - - ``points`` -- the points to project to the base. - - OUTPUT: + - ``points`` -- the points to project to the base - A tuple of primitive `\ZZ`-vectors. + OUTPUT: a tuple of primitive `\ZZ`-vectors EXAMPLES:: @@ -922,7 +910,7 @@ def has_IP_property(self): That is, the polytope is full-dimensional and the origin is a interior point not on the boundary. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -957,7 +945,7 @@ def restricted_automorphism_group(self, vertex_labels=None): INPUT: - - ``vertex_labels`` -- a tuple or ``None`` (default). The + - ``vertex_labels`` -- tuple or ``None`` (default). The labels of the vertices that will be used in the output permutation group. By default, the vertices are used themselves. @@ -1029,12 +1017,12 @@ def lattice_automorphism_group(self, points=None, point_labels=None): INPUT: - - ``points`` -- A tuple of coordinate vectors or ``None`` + - ``points`` -- tuple of coordinate vectors or ``None`` (default). If specified, the points must form complete orbits under the lattice automorphism group. If ``None`` all vertices are used. - - ``point_labels`` -- A tuple of labels for the ``points`` or + - ``point_labels`` -- tuple of labels for the ``points`` or ``None`` (default). These will be used as labels for the do permutation group. If ``None``, the ``points`` will be used themselves. diff --git a/src/sage/geometry/polyhedron/representation.py b/src/sage/geometry/polyhedron/representation.py index 49993d6ada1..78e0cbf08d3 100644 --- a/src/sage/geometry/polyhedron/representation.py +++ b/src/sage/geometry/polyhedron/representation.py @@ -46,7 +46,7 @@ class PolyhedronRepresentation(SageObject): The internal base class for all representation objects of ``Polyhedron`` (vertices/rays/lines and inequalities/equations) - .. note:: + .. NOTE:: You should not (and cannot) instantiate it yourself. You can only obtain them from a Polyhedron() class. @@ -108,7 +108,7 @@ def __hash__(self): def __richcmp__(self, other, op): """ - Compare two representation objects + Compare two representation objects. This method defines a linear order on the H/V-representation objects. The order is first determined by the types of the objects, @@ -122,11 +122,9 @@ def __richcmp__(self, other, op): INPUT: - - ``other`` -- anything. + - ``other`` -- anything - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -218,7 +216,7 @@ def vector(self, base_ring=None): INPUT: - - ``base_ring`` -- the base ring of the vector. + - ``base_ring`` -- the base ring of the vector OUTPUT: @@ -321,11 +319,9 @@ def __add__(self, coordinate_list): INPUT: - - ``coordinate_list`` -- a list. + - ``coordinate_list`` -- list - OUTPUT: - - The coordinates of ``self`` concatenated with ``coordinate_list``. + OUTPUT: the coordinates of ``self`` concatenated with ``coordinate_list`` EXAMPLES:: @@ -345,11 +341,9 @@ def __radd__(self, coordinate_list): INPUT: - - ``coordinate_list`` -- a list. - - OUTPUT: + - ``coordinate_list`` -- list - ``coordinate_list`` concatenated with the coordinates of ``self``. + OUTPUT: ``coordinate_list`` concatenated with the coordinates of ``self`` EXAMPLES:: @@ -369,11 +363,9 @@ def count(self, i): INPUT: - - ``i`` -- Anything. - - OUTPUT: + - ``i`` -- anything - Integer. The number of occurrences of ``i`` in the coordinates. + OUTPUT: integer; the number of occurrences of ``i`` in the coordinates EXAMPLES:: @@ -394,7 +386,7 @@ class Hrepresentation(PolyhedronRepresentation): def __init__(self, polyhedron_parent): """ - Initializes the PolyhedronRepresentation object. + Initialize the PolyhedronRepresentation object. TESTS:: @@ -422,9 +414,9 @@ def _set_data(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. + - ``polyhedron`` -- the new polyhedron - - ``data`` -- the H-representation data. + - ``data`` -- the H-representation data TESTS:: @@ -448,7 +440,7 @@ def _set_data(self, polyhedron, data): def is_H(self): """ - Return True if the object is part of a H-representation + Return ``True`` if the object is part of a H-representation (inequality or equation). EXAMPLES:: @@ -462,7 +454,7 @@ def is_H(self): def is_inequality(self): """ - Return True if the object is an inequality of the H-representation. + Return ``True`` if the object is an inequality of the H-representation. EXAMPLES:: @@ -475,7 +467,7 @@ def is_inequality(self): def is_equation(self): """ - Return True if the object is an equation of the H-representation. + Return ``True`` if the object is an equation of the H-representation. EXAMPLES:: @@ -586,7 +578,7 @@ def adjacent(self): def is_incident(self, Vobj): """ - Return whether the incidence matrix element (Vobj,self) == 1 + Return whether the incidence matrix element (Vobj,self) == 1. EXAMPLES:: @@ -602,7 +594,7 @@ def is_incident(self, Vobj): def __mul__(self, Vobj): """ - Shorthand for ``self.eval(x)`` + Shorthand for ``self.eval(x)``. EXAMPLES:: @@ -619,7 +611,7 @@ def eval(self, Vobj): Evaluate the left hand side `A\vec{x}+b` on the given vertex/ray/line. - .. NOTE: + .. NOTE:: * Evaluating on a vertex returns `A\vec{x}+b` @@ -682,15 +674,13 @@ def repr_pretty(self, **kwds): INPUT: - - ``prefix`` -- a string - - - ``indices`` -- a tuple or other iterable + - ``prefix`` -- string - - ``latex`` -- a boolean + - ``indices`` -- tuple or other iterable - OUTPUT: + - ``latex`` -- boolean - A string + OUTPUT: string EXAMPLES:: @@ -708,9 +698,7 @@ def _latex_(self): r""" Return a LaTeX-representation of this equality/inequality. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -762,7 +750,7 @@ def type(self): def is_inequality(self): """ - Return True since this is, by construction, an inequality. + Return ``True`` since this is, by construction, an inequality. EXAMPLES:: @@ -877,7 +865,7 @@ def is_facet_defining_inequality(self, other): # See if ``self`` has the same incidences as an inequality of ``other``. # If this is the case, then the above check suffices to guarantee that all - # entries of ``cross_slack_matrix`` are non-negative. + # entries of ``cross_slack_matrix`` are nonnegative. return incidences.row(0) in other.incidence_matrix().columns() def _repr_(self): @@ -924,7 +912,7 @@ def _repr_(self): def contains(self, Vobj): """ - Tests whether the halfspace (including its boundary) defined + Test whether the halfspace (including its boundary) defined by the inequality contains the given vertex/ray/line. EXAMPLES:: @@ -950,7 +938,7 @@ def contains(self, Vobj): def interior_contains(self, Vobj): """ - Tests whether the interior of the halfspace (excluding its + Test whether the interior of the halfspace (excluding its boundary) defined by the inequality contains the given vertex/ray/line. @@ -988,9 +976,7 @@ def outer_normal(self): r""" Return the outer normal vector of ``self``. - OUTPUT: - - The normal vector directed away from the interior of the polyhedron. + OUTPUT: the normal vector directed away from the interior of the polyhedron EXAMPLES:: @@ -1040,7 +1026,7 @@ def type(self): def is_equation(self): """ - Tests if this object is an equation. By construction, it must be. + Test if this object is an equation. By construction, it must be. TESTS:: @@ -1080,7 +1066,7 @@ def _repr_(self): def contains(self, Vobj): """ - Tests whether the hyperplane defined by the equation contains + Test whether the hyperplane defined by the equation contains the given vertex/ray/line. EXAMPLES:: @@ -1099,7 +1085,7 @@ def contains(self, Vobj): def interior_contains(self, Vobj): """ - Tests whether the interior of the halfspace (excluding its + Test whether the interior of the halfspace (excluding its boundary) defined by the inequality contains the given vertex/ray/line. @@ -1130,7 +1116,7 @@ class Vrepresentation(PolyhedronRepresentation): def __init__(self, polyhedron_parent): """ - Initializes the PolyhedronRepresentation object. + Initialize the PolyhedronRepresentation object. TESTS:: @@ -1156,9 +1142,9 @@ def _set_data(self, polyhedron, data): INPUT: - - ``polyhedron`` -- the new polyhedron. + - ``polyhedron`` -- the new polyhedron - - ``data`` -- the V-representation data. + - ``data`` -- the V-representation data TESTS:: @@ -1181,7 +1167,7 @@ def _set_data(self, polyhedron, data): def is_V(self): """ - Return True if the object is part of a V-representation + Return ``True`` if the object is part of a V-representation (a vertex, ray, or line). EXAMPLES:: @@ -1195,7 +1181,7 @@ def is_V(self): def is_vertex(self): """ - Return True if the object is a vertex of the V-representation. + Return ``True`` if the object is a vertex of the V-representation. This method is over-ridden by the corresponding method in the derived class Vertex. @@ -1214,7 +1200,7 @@ def is_vertex(self): def is_ray(self): """ - Return True if the object is a ray of the V-representation. + Return ``True`` if the object is a ray of the V-representation. This method is over-ridden by the corresponding method in the derived class Ray. @@ -1234,7 +1220,7 @@ def is_ray(self): def is_line(self): """ - Return True if the object is a line of the V-representation. + Return ``True`` if the object is a line of the V-representation. This method is over-ridden by the corresponding method in the derived class Line. @@ -1283,7 +1269,7 @@ def adjacent(self): def is_incident(self, Hobj): """ - Return whether the incidence matrix element (self,Hobj) == 1 + Return whether the incidence matrix element (self,Hobj) == 1. EXAMPLES:: @@ -1301,7 +1287,7 @@ def is_incident(self, Hobj): def __mul__(self, Hobj): """ - Shorthand for self.evaluated_on(Hobj) + Shorthand for self.evaluated_on(Hobj). TESTS:: @@ -1377,7 +1363,7 @@ def type(self): def is_vertex(self): """ - Tests if this object is a vertex. By construction it always is. + Test if this object is a vertex. By construction it always is. EXAMPLES:: @@ -1392,9 +1378,7 @@ def _repr_(self): """ Return a string representation of the vertex. - OUTPUT: - - String. + OUTPUT: string TESTS:: @@ -1414,7 +1398,7 @@ def homogeneous_vector(self, base_ring=None): INPUT: - - ``base_ring`` -- the base ring of the vector. + - ``base_ring`` -- the base ring of the vector EXAMPLES:: @@ -1429,7 +1413,7 @@ def homogeneous_vector(self, base_ring=None): def evaluated_on(self, Hobj): r""" - Return `A\vec{x}+b` + Return `A\vec{x}+b`. EXAMPLES:: @@ -1449,9 +1433,7 @@ def is_integral(self): r""" Return whether the coordinates of the vertex are all integral. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1498,7 +1480,7 @@ def type(self): def is_ray(self): """ - Tests if this object is a ray. Always True by construction. + Test if this object is a ray. Always ``True`` by construction. EXAMPLES:: @@ -1531,7 +1513,7 @@ def homogeneous_vector(self, base_ring=None): INPUT: - - ``base_ring`` -- the base ring of the vector. + - ``base_ring`` -- the base ring of the vector EXAMPLES:: @@ -1546,7 +1528,7 @@ def homogeneous_vector(self, base_ring=None): def evaluated_on(self, Hobj): r""" - Return `A\vec{r}` + Return `A\vec{r}`. EXAMPLES:: @@ -1596,7 +1578,7 @@ def type(self): def is_line(self): """ - Tests if the object is a line. By construction it must be. + Test if the object is a line. By construction it must be. TESTS:: @@ -1629,7 +1611,7 @@ def homogeneous_vector(self, base_ring=None): INPUT: - - ``base_ring`` -- the base ring of the vector. + - ``base_ring`` -- the base ring of the vector EXAMPLES:: @@ -1644,7 +1626,7 @@ def homogeneous_vector(self, base_ring=None): def evaluated_on(self, Hobj): r""" - Return `A\vec{\ell}` + Return `A\vec{\ell}`. EXAMPLES:: @@ -1665,27 +1647,25 @@ def repr_pretty(coefficients, type, prefix='x', indices=None, INPUT: - - ``coefficients`` -- a tuple or other iterable + - ``coefficients`` -- tuple or other iterable - ``type`` -- either ``0`` (``PolyhedronRepresentation.INEQUALITY``) or ``1`` (``PolyhedronRepresentation.EQUATION``) - - ``prefix`` -- a string (default: ``x``) - - - ``indices`` -- a tuple or other iterable + - ``prefix`` -- string (default: ``'x'``) - - ``latex`` -- a boolean + - ``indices`` -- tuple or other iterable - - ``split`` -- a boolean; (Default: ``False``). If set to ``True``, - the output is split into a 3-tuple containing the left-hand side, - the relation, and the right-hand side of the object. + - ``latex`` -- boolean - - ``style`` -- either ``"positive"`` (making all coefficients positive), or - ``"<="`` or ``">="``. + - ``split`` -- boolean (default: ``False``); if set to ``True``, + the output is split into a 3-tuple containing the left-hand side, + the relation, and the right-hand side of the object - OUTPUT: + - ``style`` -- either ``'positive'`` (making all coefficients positive), or + ``'<='`` or ``'>='`` - A string or 3-tuple of strings (depending on ``split``). + OUTPUT: a string or 3-tuple of strings (depending on ``split``) EXAMPLES:: diff --git a/src/sage/geometry/pseudolines.py b/src/sage/geometry/pseudolines.py index 38283fae8f8..cb9f68a8ba5 100644 --- a/src/sage/geometry/pseudolines.py +++ b/src/sage/geometry/pseudolines.py @@ -170,20 +170,20 @@ class PseudolineArrangement: - def __init__(self, seq, encoding="auto"): + def __init__(self, seq, encoding='auto'): r""" - Creates an arrangement of pseudolines. + Create an arrangement of pseudolines. INPUT: - - ``seq`` (a sequence describing the line arrangement). It can be: + - ``seq`` -- a sequence describing the line arrangement. It can be: - A list of `n` permutations of size `n-1`. - A list of `\binom n 2` transpositions - A Felsner matrix, given as a sequence of `n` binary vectors of length `n-1`. - - ``encoding`` (information on how the data should be interpreted), and + - ``encoding`` -- information on how the data should be interpreted, and can assume any value among 'transpositions', 'permutations', 'Felsner' or 'auto'. In the latter case, the type will be guessed (default behaviour). @@ -462,8 +462,8 @@ def show(self, **args): l.append((x+2, l[-1][1])) L += line(l) - L += text(str(i), (0, l[0][1]+.3), horizontal_alignment="right") - L += text(str(i), (x+2, l[-1][1]+.3), horizontal_alignment="left") + L += text(str(i), (0, l[0][1]+.3), horizontal_alignment='right') + L += text(str(i), (x+2, l[-1][1]+.3), horizontal_alignment='left') return L.show(axes=False, **args) diff --git a/src/sage/geometry/relative_interior.py b/src/sage/geometry/relative_interior.py index e62a9182211..3d7aa5d1c36 100644 --- a/src/sage/geometry/relative_interior.py +++ b/src/sage/geometry/relative_interior.py @@ -17,7 +17,7 @@ class RelativeInterior(ConvexSet_relatively_open): r""" - The relative interior of a polyhedron or cone + The relative interior of a polyhedron or cone. This class should not be used directly. Use methods :meth:`~sage.geometry.polyhedron.Polyhedron_base.relative_interior`, @@ -43,7 +43,7 @@ def __init__(self, polyhedron): INPUT: - ``polyhedron`` -- an instance of :class:`Polyhedron_base` or - :class:`ConvexRationalPolyhedralCone`. + :class:`ConvexRationalPolyhedralCone` TESTS:: @@ -216,11 +216,9 @@ def closure(self): def is_universe(self): r""" - Return whether ``self`` is the whole ambient space + Return whether ``self`` is the whole ambient space. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -240,9 +238,7 @@ def is_closed(self): r""" Return whether ``self`` is closed. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -370,7 +366,7 @@ def dilation(self, scalar): INPUT: - - ``scalar`` -- A scalar + - ``scalar`` -- a scalar EXAMPLES:: @@ -406,7 +402,7 @@ def linear_transformation(self, linear_transf, **kwds): - ``linear_transf`` -- a matrix - ``**kwds`` -- passed to the :meth:`linear_transformation` method of - the closure of ``self``. + the closure of ``self`` EXAMPLES:: diff --git a/src/sage/geometry/ribbon_graph.py b/src/sage/geometry/ribbon_graph.py index 77128b94ad7..6f10912ff79 100644 --- a/src/sage/geometry/ribbon_graph.py +++ b/src/sage/geometry/ribbon_graph.py @@ -39,13 +39,13 @@ def _find(l, k): INPUT: - - ``l`` -- a list of lists + - ``l`` -- list of lists - ``k`` -- a candidate to be in a list in ``l`` OUTPUT: A list with two integers describing the position of the first - instance of `k`` in ``l``. + instance of ``k`` in ``l``. TESTS:: @@ -74,11 +74,9 @@ def _clean(l): INPUT: - - ``l`` -- a list of lists + - ``l`` -- list of lists - OUTPUT: - - - a list which is a copy of ``l`` with all empty sublists removed + OUTPUT: list which is a copy of ``l`` with all empty sublists removed EXAMPLES:: @@ -409,12 +407,10 @@ def contract_edge(self, k): INPUT: - - ``k`` -- non-negative integer; the position in `\rho` of the + - ``k`` -- nonnegative integer; the position in `\rho` of the transposition that is going to be contracted - OUTPUT: - - - a ribbon graph resulting from the contraction of that edge + OUTPUT: a ribbon graph resulting from the contraction of that edge EXAMPLES: @@ -609,7 +605,7 @@ def genus(self): OUTPUT: - - ``g`` -- non-negative integer representing the genus of the + - ``g`` -- nonnegative integer representing the genus of the thickening of the ribbon graph EXAMPLES:: @@ -1048,7 +1044,6 @@ def normalize(self): Ribbon graph of genus 1 and 1 boundary components (1,2,3)(4,5,6) (1,4)(2,5)(3,6) - """ #First we compute the vertices of valency 1 and store them in val_one. aux_sigma = [list(x) for x in self._sigma.cycle_tuples()] @@ -1090,7 +1085,7 @@ def make_ribbon(g, r): INPUT: - - ``g`` -- non-negative integer representing the genus of the + - ``g`` -- nonnegative integer representing the genus of the thickening - ``r`` -- positive integer representing the number of boundary @@ -1132,7 +1127,6 @@ def make_ribbon(g, r): (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,33,31)(16,32,34,17,18,19,20,21,22,23,24,25,26,27,28,29,30) sage: R.rho() (1,16)(2,17)(3,18)(4,19)(5,20)(6,21)(7,22)(8,23)(9,24)(10,25)(11,26)(12,27)(13,28)(14,29)(15,30)(31,32)(33,34) - """ #Initialize the two vertices of sigma and the edge joining them repr_sigma = [[1],[2*g+2]] @@ -1176,8 +1170,8 @@ def bipartite_ribbon_graph(p, q): INPUT: - - ``p`` -- a positive integer - - ``q`` -- a positive integer + - ``p`` -- positive integer + - ``q`` -- positive integer EXAMPLES:: @@ -1205,7 +1199,6 @@ def bipartite_ribbon_graph(p, q): Ribbon graph of genus 9 and 1 boundary components (1,2,3,4,5,6,7)(8,9,10,11,12,13,14)(15,16,17,18,19,20,21)(22,23,24,25,26,27,28)(29,30,31,32)(33,34,35,36)(37,38,39,40)(41,42,43,44)(45,46,47,48)(49,50,51,52)(53,54,55,56) (1,32)(2,36)(3,40)(4,44)(5,48)(6,52)(7,56)(8,31)(9,35)(10,39)(11,43)(12,47)(13,51)(14,55)(15,30)(16,34)(17,38)(18,42)(19,46)(20,50)(21,54)(22,29)(23,33)(24,37)(25,41)(26,45)(27,49)(28,53) - """ sigma = [] rho = [] diff --git a/src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py b/src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py index 43fecdc0609..27940e9a723 100644 --- a/src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py +++ b/src/sage/geometry/riemannian_manifolds/parametrized_surface3d.py @@ -33,14 +33,13 @@ def _simplify_full_rad(f): INPUT: - - ``f`` -- a symbolic expression. + - ``f`` -- a symbolic expression EXAMPLES:: sage: from sage.geometry.riemannian_manifolds.parametrized_surface3d import _simplify_full_rad sage: _simplify_full_rad(sqrt(x^2)/x) 1 - """ return f.simplify_full().canonicalize_radical() @@ -56,19 +55,18 @@ class ParametrizedSurface3D(SageObject): INPUT: - - ``surface_equation`` -- a 3-tuple of functions specifying a parametric - representation of the surface. + - ``surface_equation`` -- a 3-tuple of functions specifying a parametric + representation of the surface - - ``variables`` -- a 2-tuple of intrinsic coordinates `(u, v)` on the - surface, with `u` and `v` symbolic variables, or a 2-tuple of triples - `(u, u_{min}, u_{max})`, - `(v, v_{min}, v_{max})` when the parameter range - for the coordinates is known. + - ``variables`` -- a 2-tuple of intrinsic coordinates `(u, v)` on the + surface, with `u` and `v` symbolic variables, or a 2-tuple of triples + `(u, u_{min}, u_{max})`, `(v, v_{min}, v_{max})` when the parameter range + for the coordinates is known - - ``name`` -- name of the surface (optional). + - ``name`` -- name of the surface (optional) - .. note:: + .. NOTE:: Throughout the documentation, we use the Einstein summation convention: whenever an index appears twice, once as a @@ -76,7 +74,6 @@ class ParametrizedSurface3D(SageObject): is implied. For instance, `g_{ij} g^{jk}` stands for `\sum_j g_{ij}g^{jk}`. - EXAMPLES: We give several examples of standard surfaces in differential @@ -343,21 +340,19 @@ class ParametrizedSurface3D(SageObject): ....: (0,2*pi,100))] sage: (S.plot(opacity=0.3) + line3d(g1, color='red') # needs sage.plot ....: + line3d(g2, color='red') + line3d(g3, color='red')).show() - """ def __init__(self, equation, variables, name=None): r""" See ``ParametrizedSurface3D`` for full documentation. - .. note:: + .. NOTE:: The orientation of the surface is determined by the parametrization, that is, the natural frame with positive orientation is given by `\partial_1 \vec r`, `\partial_2 \vec r`. - EXAMPLES:: sage: u, v = var('u,v', domain='real') @@ -365,7 +360,6 @@ def __init__(self, equation, variables, name=None): sage: enneper = ParametrizedSurface3D(eq, (u, v),'Enneper Surface'); enneper Parametrized surface ('Enneper Surface') with equation (-u^3 + 3*u*v^2 + 3*u, 3*u^2*v - v^3 + 3*v, 3*u^2 - 3*v^2) - """ self.equation = tuple(equation) @@ -391,14 +385,13 @@ def _latex_(self): \left(\cos\left(u\right) \cos\left(v\right), \cos\left(v\right) \sin\left(u\right), \sin\left(v\right)\right) sage: sphere._latex_() \left(\cos\left(u\right) \cos\left(v\right), \cos\left(v\right) \sin\left(u\right), \sin\left(v\right)\right) - """ from sage.misc.latex import latex return latex(self.equation) def _repr_(self): r""" - Returns the string representation of this parametrized surface. + Return the string representation of this parametrized surface. EXAMPLES:: @@ -409,7 +402,6 @@ def _repr_(self): Parametrized surface ('enneper_surface') with equation (-u^3 + 3*u*v^2 + 3*u, 3*u^2*v - v^3 + 3*v, 3*u^2 - 3*v^2) sage: enneper._repr_() "Parametrized surface ('enneper_surface') with equation (-u^3 + 3*u*v^2 + 3*u, 3*u^2*v - v^3 + 3*v, 3*u^2 - 3*v^2)" - """ name = 'Parametrized surface' if self.name is not None: @@ -420,15 +412,13 @@ def _repr_(self): def point(self, coords): r""" - Returns a point on the surface given its intrinsic coordinates. + Return a point on the surface given its intrinsic coordinates. INPUT: - - ``coords`` -- 2-tuple specifying the intrinsic coordinates ``(u, v)`` of the point. + - ``coords`` -- 2-tuple specifying the intrinsic coordinates ``(u, v)`` of the point - OUTPUT: - - - 3-vector specifying the coordinates in `\RR^3` of the point. + OUTPUT: 3-vector specifying the coordinates in `\RR^3` of the point EXAMPLES:: @@ -442,7 +432,6 @@ def point(self, coords): (-2, 0, 1) sage: torus.point((pi, pi/2)) (0, 1, 0) - """ d = dict(zip(self.variables_list, coords)) @@ -450,19 +439,18 @@ def point(self, coords): def tangent_vector(self, coords, components): r""" - Returns the components of a tangent vector given the intrinsic + Return the components of a tangent vector given the intrinsic coordinates of the base point and the components of the vector in the intrinsic frame. INPUT: - - ``coords`` -- 2-tuple specifying the intrinsic coordinates ``(u, v)`` of the point. + - ``coords`` -- 2-tuple specifying the intrinsic coordinates ``(u, v)`` of the point - - ``components`` -- 2-tuple specifying the components of the tangent vector in the intrinsic coordinate frame. + - ``components`` -- 2-tuple specifying the components of the tangent + vector in the intrinsic coordinate frame - OUTPUT: - - - 3-vector specifying the components in `\RR^3` of the vector. + OUTPUT: 3-vector specifying the components in `\RR^3` of the vector EXAMPLES: @@ -485,7 +473,6 @@ def tangent_vector(self, coords, components): (-108, 216, -216) sage: n == w1.cross_product(w2) True - """ components = vector(components) @@ -506,8 +493,8 @@ def plot(self, urange=None, vrange=None, **kwds): INPUT: - - ``urange`` -- 2-tuple specifying the parameter range for `u`. - - ``vrange`` -- 2-tuple specifying the parameter range for `v`. + - ``urange`` -- 2-tuple specifying the parameter range for `u` + - ``vrange`` -- 2-tuple specifying the parameter range for `v` EXAMPLES:: @@ -516,7 +503,6 @@ def plot(self, urange=None, vrange=None, **kwds): sage: enneper = ParametrizedSurface3D(eq, (u, v), 'Enneper Surface') sage: enneper.plot((-5, 5), (-5, 5)) # needs sage.plot Graphics3d Object - """ from sage.plot.plot3d.parametric_plot3d import parametric_plot3d @@ -541,13 +527,11 @@ def plot(self, urange=None, vrange=None, **kwds): @cached_method def natural_frame(self): """ - Returns the natural tangent frame on the parametrized surface. + Return the natural tangent frame on the parametrized surface. The vectors of this frame are tangent to the coordinate lines on the surface. - OUTPUT: - - - The natural frame as a dictionary. + OUTPUT: the natural frame as a dictionary EXAMPLES:: @@ -570,15 +554,14 @@ def natural_frame(self): @cached_method def normal_vector(self, normalized=False): """ - Returns the normal vector field of the parametrized surface. + Return the normal vector field of the parametrized surface. INPUT: - - ``normalized`` -- (default ``False``); specifies whether the normal vector should be normalized. - - OUTPUT: + - ``normalized`` -- boolean (default: ``False``); specifies whether + the normal vector should be normalized - - Normal vector field. + OUTPUT: normal vector field EXAMPLES:: @@ -591,7 +574,6 @@ def normal_vector(self, normalized=False): (-2*u/sqrt(4*u^2 + 4*v^2 + 1), -2*v/sqrt(4*u^2 + 4*v^2 + 1), 1/sqrt(4*u^2 + 4*v^2 + 1)) - """ dr = self.natural_frame() @@ -616,7 +598,6 @@ def _compute_first_fundamental_form_coefficient(self, index): sage: eparaboloid = ParametrizedSurface3D((u, v, u^2+v^2), (u, v)) sage: eparaboloid._compute_first_fundamental_form_coefficient((1,2)) 4*u*v - """ dr = self.natural_frame() return _simplify_full_rad(dr[index[0]]*dr[index[1]]) @@ -630,11 +611,9 @@ def first_fundamental_form_coefficient(self, index): INPUT: - - ``index`` -- tuple ``(i, j)`` specifying the index of the component `g_{ij}`. + - ``index`` -- tuple ``(i, j)`` specifying the index of the component `g_{ij}` - OUTPUT: - - - Component `g_{ij}` of the first fundamental form + OUTPUT: component `g_{ij}` of the first fundamental form EXAMPLES:: @@ -651,7 +630,6 @@ def first_fundamental_form_coefficient(self, index): Traceback (most recent call last): ... ValueError: Index (1, 5) out of bounds. - """ index = tuple(sorted(index)) if len(index) == 2 and all(i == 1 or i == 2 for i in index): @@ -661,13 +639,11 @@ def first_fundamental_form_coefficient(self, index): def first_fundamental_form_coefficients(self): r""" - Returns the coefficients of the first fundamental form as a dictionary. + Return the coefficients of the first fundamental form as a dictionary. The keys are tuples `(i, j)`, where `i` and `j` range over `1, 2`, while the values are the corresponding coefficients `g_{ij}`. - OUTPUT: - - - Dictionary of first fundamental form coefficients. + OUTPUT: dictionary of first fundamental form coefficients EXAMPLES:: @@ -675,7 +651,6 @@ def first_fundamental_form_coefficients(self): sage: sphere = ParametrizedSurface3D((cos(u)*cos(v), sin(u)*cos(v), sin(v)), (u, v), 'sphere') sage: sphere.first_fundamental_form_coefficients() {(1, 1): cos(v)^2, (1, 2): 0, (2, 1): 0, (2, 2): 1} - """ coefficients = {} for index in product((1, 2), repeat=2): @@ -693,11 +668,9 @@ def first_fundamental_form(self, vector1, vector2): INPUT: - - ``vector1``, ``vector2`` -- vectors on the surface. - - OUTPUT: + - ``vector1``, ``vector2`` -- vectors on the surface - - First fundamental form evaluated on the input vectors. + OUTPUT: first fundamental form evaluated on the input vectors EXAMPLES:: @@ -720,16 +693,14 @@ def first_fundamental_form(self, vector1, vector2): def area_form_squared(self): """ - Returns the square of the coefficient of the area form on the surface. + Return the square of the coefficient of the area form on the surface. In terms of the coefficients `g_{ij}` (where `i, j = 1, 2`) of the first fundamental form, this invariant is given by `A^2 = g_{11}g_{22} - g_{12}^2`. See also :meth:`.area_form`. - OUTPUT: - - - Square of the area form + OUTPUT: square of the area form EXAMPLES:: @@ -737,7 +708,6 @@ def area_form_squared(self): sage: sphere = ParametrizedSurface3D([cos(u)*cos(v),sin(u)*cos(v),sin(v)],[u,v],'sphere') sage: sphere.area_form_squared() cos(v)^2 - """ gamma = self.first_fundamental_form_coefficients() sq = gamma[(1,1)] * gamma[(2,2)] - gamma[(1,2)]**2 @@ -745,16 +715,14 @@ def area_form_squared(self): def area_form(self): r""" - Returns the coefficient of the area form on the surface. In terms of + Return the coefficient of the area form on the surface. In terms of the coefficients `g_{ij}` (where `i, j = 1, 2`) of the first fundamental form, the coefficient of the area form is given by `A = \sqrt{g_{11}g_{22} - g_{12}^2}`. See also :meth:`.area_form_squared`. - OUTPUT: - - - Coefficient of the area form + OUTPUT: coefficient of the area form EXAMPLES:: @@ -762,21 +730,18 @@ def area_form(self): sage: sphere = ParametrizedSurface3D([cos(u)*cos(v),sin(u)*cos(v),sin(v)],[u,v],'sphere') sage: sphere.area_form() cos(v) - """ f = abs(sqrt(self.area_form_squared())) return _simplify_full_rad(f) def first_fundamental_form_inverse_coefficients(self): r""" - Returns the coefficients `g^{ij}` of the inverse of the fundamental + Return the coefficients `g^{ij}` of the inverse of the fundamental form, as a dictionary. The inverse coefficients are defined by `g^{ij} g_{jk} = \delta^i_k` with `\delta^i_k` the Kronecker delta. - OUTPUT: - - - Dictionary of the inverse coefficients. + OUTPUT: dictionary of the inverse coefficients EXAMPLES:: @@ -784,7 +749,6 @@ def first_fundamental_form_inverse_coefficients(self): sage: sphere = ParametrizedSurface3D([cos(u)*cos(v),sin(u)*cos(v),sin(v)],[u,v],'sphere') sage: sphere.first_fundamental_form_inverse_coefficients() {(1, 1): cos(v)^(-2), (1, 2): 0, (2, 1): 0, (2, 2): 1} - """ g = self.first_fundamental_form_coefficients() @@ -799,16 +763,14 @@ def first_fundamental_form_inverse_coefficients(self): def first_fundamental_form_inverse_coefficient(self, index): r""" - Returns a specific component `g^{ij}` of the inverse of the fundamental + Return a specific component `g^{ij}` of the inverse of the fundamental form. INPUT: - - ``index`` -- tuple ``(i, j)`` specifying the index of the component `g^{ij}`. + - ``index`` -- tuple ``(i, j)`` specifying the index of the component `g^{ij}` - OUTPUT: - - - Component of the inverse of the fundamental form. + OUTPUT: component of the inverse of the fundamental form EXAMPLES:: @@ -818,7 +780,6 @@ def first_fundamental_form_inverse_coefficient(self, index): 0 sage: sphere.first_fundamental_form_inverse_coefficient((1, 1)) cos(v)^(-2) - """ index = tuple(sorted(index)) @@ -830,16 +791,14 @@ def first_fundamental_form_inverse_coefficient(self, index): @cached_method def rotation(self,theta): r""" - Gives the matrix of the rotation operator over a given angle `\theta` + Give the matrix of the rotation operator over a given angle `\theta` with respect to the natural frame. INPUT: - - ``theta`` -- rotation angle + - ``theta`` -- rotation angle - OUTPUT: - - - Rotation matrix with respect to the natural frame. + OUTPUT: rotation matrix with respect to the natural frame ALGORITHM: @@ -864,7 +823,6 @@ def rotation(self,theta): sage: rotation^3 [-1 0] [ 0 -1] - """ from sage.functions.trig import sin, cos @@ -880,18 +838,16 @@ def rotation(self,theta): @cached_method def orthonormal_frame(self, coordinates='ext'): r""" - Returns the orthonormal frame field on the surface, expressed either + Return the orthonormal frame field on the surface, expressed either in exterior coordinates (i.e. expressed as vector fields in the ambient space `\mathbb{R}^3`, the default) or interior coordinates (with respect to the natural frame) INPUT: - - ``coordinates`` -- either ``ext`` (default) or ``int``. - - OUTPUT: + - ``coordinates`` -- either ``ext`` (default) or ``int`` - - Orthogonal frame field as a dictionary. + OUTPUT: orthogonal frame field as a dictionary ALGORITHM: @@ -945,18 +901,16 @@ def orthonormal_frame(self, coordinates='ext'): def orthonormal_frame_vector(self, index, coordinates='ext'): r""" - Returns a specific basis vector field of the orthonormal frame field on + Return a specific basis vector field of the orthonormal frame field on the surface, expressed in exterior or interior coordinates. See :meth:`orthogonal_frame` for more details. INPUT: - - ``index`` -- index of the basis vector; - - ``coordinates`` -- either ``ext`` (default) or ``int``. + - ``index`` -- index of the basis vector + - ``coordinates`` -- either ``ext`` (default) or ``int`` - OUTPUT: - - - Orthonormal frame vector field. + OUTPUT: orthonormal frame vector field EXAMPLES:: @@ -981,19 +935,16 @@ def orthonormal_frame_vector(self, index, coordinates='ext'): def lie_bracket(self, v, w): r""" - Returns the Lie bracket of two vector fields that are tangent + Return the Lie bracket of two vector fields that are tangent to the surface. The vector fields should be given in intrinsic coordinates, i.e. with respect to the natural frame. INPUT: - - ``v`` and ``w`` -- vector fields on the surface, expressed - as pairs of functions or as vectors of length 2. - - OUTPUT: - - - The Lie bracket `[v, w]`. + - ``v``, ``w`` -- vector fields on the surface, expressed + as pairs of functions or as vectors of length 2 + OUTPUT: the Lie bracket `[v, w]` EXAMPLES:: @@ -1019,22 +970,21 @@ def lie_bracket(self, v, w): def frame_structure_functions(self, e1, e2): r""" - Returns the structure functions `c^k_{ij}` for a frame field + Return the structure functions `c^k_{ij}` for a frame field `e_1, e_2`, i.e. a pair of vector fields on the surface which are linearly independent at each point. The structure functions are defined using the Lie bracket by `[e_i,e_j] = c^k_{ij}e_k`. INPUT: - - ``e1``, ``e2`` -- vector fields in intrinsic coordinates on - the surface, expressed as pairs of functions, or as vectors of - length 2. + - ``e1``, ``e2`` -- vector fields in intrinsic coordinates on + the surface, expressed as pairs of functions, or as vectors of + length 2 OUTPUT: - - Dictionary of structure functions, where the key ``(i, j, k)`` refers to - the structure function `c_{i,j}^k`. - + Dictionary of structure functions, where the key ``(i, j, k)`` refers to + the structure function `c_{i,j}^k`. EXAMPLES:: @@ -1095,7 +1045,6 @@ def _compute_second_order_frame_element(self, index): (0, 0, 0) sage: paraboloid._compute_second_order_frame_element((2, 2)) (0, 0, 2) - """ variables = [self.variables[i] for i in index] ddr_element = vector([_simplify_full_rad(diff(f, variables)) @@ -1105,7 +1054,7 @@ def _compute_second_order_frame_element(self, index): def second_order_natural_frame(self): r""" - Returns the second-order frame of the surface, i.e. computes the + Return the second-order frame of the surface, i.e. computes the second-order derivatives (with respect to the parameters on the surface) of the parametric expression `\vec r = \vec r(u^1,u^2)` of the surface. @@ -1125,7 +1074,6 @@ def second_order_natural_frame(self): (1, 2): (sin(u)*sin(v), -cos(u)*sin(v), 0), (2, 1): (sin(u)*sin(v), -cos(u)*sin(v), 0), (2, 2): (-cos(u)*cos(v), -cos(v)*sin(u), -sin(v))} - """ vectors = {} @@ -1137,18 +1085,16 @@ def second_order_natural_frame(self): def second_order_natural_frame_element(self, index): r""" - Returns a vector in the second-order frame of the surface, i.e. + Return a vector in the second-order frame of the surface, i.e. computes the second-order derivatives of the parametric expression `\vec{r}` of the surface with respect to the parameters listed in the argument. INPUT: - - ``index`` -- a 2-tuple ``(i, j)`` specifying the element of the second-order frame. - - OUTPUT: + - ``index`` -- a 2-tuple ``(i, j)`` specifying the element of the second-order frame - - The second-order derivative `r_{ij}`. + OUTPUT: the second-order derivative `r_{ij}` EXAMPLES:: @@ -1156,7 +1102,6 @@ def second_order_natural_frame_element(self, index): sage: sphere = ParametrizedSurface3D([cos(u)*cos(v),sin(u)*cos(v),sin(v)],[u,v],'sphere') sage: sphere.second_order_natural_frame_element((1, 2)) (sin(u)*sin(v), -cos(u)*sin(v), 0) - """ index = tuple(sorted(index)) @@ -1180,7 +1125,6 @@ def _compute_second_fundamental_form_coefficient(self, index): sage: paraboloid = ParametrizedSurface3D([u, v, u^2+v^2], [u, v], 'paraboloid') sage: paraboloid._compute_second_fundamental_form_coefficient((1,1)) 2/sqrt(4*u^2 + 4*v^2 + 1) - """ N = self.normal_vector(normalized=True) v = self.second_order_natural_frame_element(index) @@ -1188,18 +1132,16 @@ def _compute_second_fundamental_form_coefficient(self, index): def second_fundamental_form_coefficient(self, index): r""" - Returns the coefficient `h_{ij}` of the second fundamental form + Return the coefficient `h_{ij}` of the second fundamental form corresponding to the index `(i, j)`. If the equation of the surface is `\vec{r}(u^1, u^2)`, then `h_{ij} = \vec{r}_{u^i u^j} \cdot \vec{n}`, where `\vec{n}` is the unit normal. INPUT: - - ``index`` -- a 2-tuple ``(i, j)`` + - ``index`` -- a 2-tuple ``(i, j)`` - OUTPUT: - - - Component `h_{ij}` of the second fundamental form. + OUTPUT: component `h_{ij}` of the second fundamental form EXAMPLES:: @@ -1210,7 +1152,6 @@ def second_fundamental_form_coefficient(self, index): -cos(v)^2 sage: sphere.second_fundamental_form_coefficient((2, 1)) 0 - """ index = tuple(index) if len(index) == 2 and all(i == 1 or i == 2 for i in index): @@ -1220,16 +1161,14 @@ def second_fundamental_form_coefficient(self, index): def second_fundamental_form_coefficients(self): """ - Returns the coefficients `h_{ij}` of the second fundamental form as + Return the coefficients `h_{ij}` of the second fundamental form as a dictionary, where the keys are the indices `(i, j)` and the values are the corresponding components `h_{ij}`. When only one component is needed, consider instead the function :meth:`second_fundamental_form_coefficient`. - OUTPUT: - - Dictionary of second fundamental form coefficients. + OUTPUT: dictionary of second fundamental form coefficients EXAMPLES:: @@ -1238,7 +1177,6 @@ def second_fundamental_form_coefficients(self): sage: sphere = ParametrizedSurface3D([cos(u)*cos(v),sin(u)*cos(v),sin(v)],[u,v],'sphere') sage: sphere.second_fundamental_form_coefficients() {(1, 1): -cos(v)^2, (1, 2): 0, (2, 1): 0, (2, 2): -1} - """ coefficients = {} @@ -1255,11 +1193,9 @@ def second_fundamental_form(self,vector1,vector2): INPUT: - - ``vector1``, ``vector2`` -- 2-tuples representing the input vectors. - - OUTPUT: + - ``vector1``, ``vector2`` -- 2-tuples representing the input vectors - - Value of the second fundamental form evaluated on the given vectors. + OUTPUT: value of the second fundamental form evaluated on the given vectors EXAMPLES: @@ -1280,7 +1216,6 @@ def second_fundamental_form(self,vector1,vector2): -cos(v)^2 - 4 sage: sphere.second_fundamental_form([1,1], [2,1]) -2*cos(v)^2 - 1 - """ hh = self.second_fundamental_form_coefficients() return sum(hh[(i, j)] * vector1[i - 1] * vector2[j - 1] @@ -1293,9 +1228,7 @@ def gauss_curvature(self): where `g_{ij}` and `h_{ij}` are the coefficients of the first and second fundamental form, respectively. - OUTPUT: - - - Gaussian curvature of the surface. + OUTPUT: Gaussian curvature of the surface. EXAMPLES:: @@ -1306,7 +1239,6 @@ def gauss_curvature(self): sage: sphere = ParametrizedSurface3D([R*cos(u)*cos(v),R*sin(u)*cos(v),R*sin(v)],[u,v],'sphere') sage: sphere.gauss_curvature() R^(-2) - """ hh = self.second_fundamental_form_coefficients() return _simplify_full_rad( @@ -1319,9 +1251,7 @@ def mean_curvature(self): where `g_{ij}` and `h_{ij}` are the components of the first and second fundamental forms, respectively. - OUTPUT: - - - Mean curvature of the surface + OUTPUT: mean curvature of the surface EXAMPLES:: @@ -1332,7 +1262,6 @@ def mean_curvature(self): sage: sphere = ParametrizedSurface3D([R*cos(u)*cos(v),R*sin(u)*cos(v),R*sin(v)],[u,v],'sphere') sage: sphere.mean_curvature() -1/R - """ gg = self.first_fundamental_form_coefficients() hh = self.second_fundamental_form_coefficients() @@ -1344,13 +1273,13 @@ def mean_curvature(self): @cached_method def shape_operator_coefficients(self): r""" - Returns the components of the shape operator of the surface as a + Return the components of the shape operator of the surface as a dictionary. See ``shape_operator`` for more information. OUTPUT: - - Dictionary where the keys are two-tuples ``(i, j)``, with values the - corresponding component of the shape operator. + Dictionary where the keys are two-tuples ``(i, j)``, with values the + corresponding component of the shape operator. EXAMPLES:: @@ -1360,7 +1289,6 @@ def shape_operator_coefficients(self): sage: sphere = ParametrizedSurface3D([R*cos(u)*cos(v),R*sin(u)*cos(v),R*sin(v)],[u,v],'sphere') sage: sphere.shape_operator_coefficients() {(1, 1): -1/R, (1, 2): 0, (2, 1): 0, (2, 2): -1/R} - """ gi = self.first_fundamental_form_inverse_coefficients() @@ -1375,14 +1303,12 @@ def shape_operator_coefficients(self): def shape_operator(self): r""" - Returns the shape operator of the surface as a matrix. The shape + Return the shape operator of the surface as a matrix. The shape operator is defined as the derivative of the Gauss map, and is computed here in terms of the first and second fundamental form by means of the Weingarten equations. - OUTPUT: - - - Matrix of the shape operator + OUTPUT: matrix of the shape operator EXAMPLES:: @@ -1405,7 +1331,6 @@ def shape_operator(self): [ -8*u*v/(4*u^2 + 4*v^2 + 1)^(3/2) 2*(4*u^2 + 1)/(4*u^2 + 4*v^2 + 1)^(3/2)] sage: S.eigenvalues() [2*sqrt(4*u^2 + 4*v^2 + 1)/(16*u^4 + 16*v^4 + 8*(4*u^2 + 1)*v^2 + 8*u^2 + 1), 2/sqrt(4*u^2 + 4*v^2 + 1)] - """ shop = self.shape_operator_coefficients() @@ -1415,7 +1340,7 @@ def shape_operator(self): def principal_directions(self): r""" - Finds the principal curvatures and principal directions of the surface + Finds the principal curvatures and principal directions of the surface. OUTPUT: @@ -1447,7 +1372,7 @@ def principal_directions(self): @cached_method def connection_coefficients(self): r""" - Computes the connection coefficients or Christoffel symbols + Compute the connection coefficients or Christoffel symbols `\Gamma^k_{ij}` of the surface. If the coefficients of the first fundamental form are given by `g_{ij}` (where `i, j = 1, 2`), then `\Gamma^k_{ij} = \frac{1}{2} g^{kl} \left( \frac{\partial g_{li}}{\partial x^j} @@ -1478,7 +1403,6 @@ def connection_coefficients(self): (2, 1, 2): 0, (2, 2, 1): 0, (2, 2, 2): 0} - """ x = self.variables gg = self.first_fundamental_form_coefficients() @@ -1509,7 +1433,6 @@ def _create_geodesic_ode_system(self): sage: ode = sphere._create_geodesic_ode_system() sage: ode.function(0.0, (1.0, 0.0, 1.0, 1.0)) [1.00000000000000, 1.00000000000000, -0.4546487134128409, 3.114815449309804] - """ from sage.ext.fast_eval import fast_float from sage.calculus.ode import ode_solver @@ -1551,23 +1474,25 @@ def geodesics_numerical(self, p0, v0, tinterval): INPUT: - - ``p0`` -- 2-tuple with coordinates of the initial point. + - ``p0`` -- 2-tuple with coordinates of the initial point - - ``v0`` -- 2-tuple with components of the initial tangent vector to the geodesic. + - ``v0`` -- 2-tuple with components of the initial tangent vector to the geodesic - - ``tinterval`` -- List ``[a, b, M]``, where ``(a,b)`` is the domain of the geodesic and ``M`` is the number of subdivision points used when returning the solution. + - ``tinterval`` -- list ``[a, b, M]``, where ``(a,b)`` is the domain + of the geodesic and ``M`` is the number of subdivision points used + when returning the solution OUTPUT: List of lists ``[t, [u1(t), u2(t)], [v1(t), v2(t)], [x1(t), x2(t), x3(t)]]``, where - - ``t`` is a subdivision point; + - ``t`` -- a subdivision point; - - ``[u1(t), u2(t)]`` are the intrinsic coordinates of the geodesic point; + - ``[u1(t), u2(t)]`` are the intrinsic coordinates of the geodesic point; - - ``[v1(t), v2(t)]`` are the intrinsic coordinates of the tangent vector to the geodesic; + - ``[v1(t), v2(t)]`` are the intrinsic coordinates of the tangent vector to the geodesic; - - ``[x1(t), x2(t), x3(t)]`` are the coordinates of the geodesic point in the three-dimensional space. + - ``[x1(t), x2(t), x3(t)]`` are the coordinates of the geodesic point in the three-dimensional space. EXAMPLES:: @@ -1605,8 +1530,8 @@ def _create_pt_ode_system(self, curve, t): INPUT: - - ``curve`` -- curve in intrinsic coordinates along which to do parallel transport. - - ``t`` -- curve parameter + - ``curve`` -- curve in intrinsic coordinates along which to do parallel transport + - ``t`` -- curve parameter EXAMPLES:: @@ -1616,7 +1541,6 @@ def _create_pt_ode_system(self, curve, t): sage: ode = sphere._create_pt_ode_system((s, s), s) sage: ode.function(0.0, (1.0, 1.0)) [-0.0, 0.0] - """ from sage.ext.fast_eval import fast_float @@ -1647,7 +1571,7 @@ def _create_pt_ode_system(self, curve, t): def parallel_translation_numerical(self,curve,t,v0,tinterval): r""" - Numerically solves the equations for parallel translation of a vector + Numerically solve the equations for parallel translation of a vector along a curve on the surface. Explicitly, the equations for parallel translation are given by `\frac{d u^i}{dt} + u^j \frac{d c^k}{dt} \Gamma^i_{jk} = 0`, @@ -1663,24 +1587,24 @@ def parallel_translation_numerical(self,curve,t,v0,tinterval): INPUT: - - ``curve`` -- 2-tuple of functions which determine the curve with respect to - the local coordinate system; + - ``curve`` -- 2-tuple of functions which determine the curve with respect to + the local coordinate system - - ``t`` -- symbolic variable denoting the curve parameter; + - ``t`` -- symbolic variable denoting the curve parameter - - ``v0`` -- 2-tuple representing the initial vector; + - ``v0`` -- 2-tuple representing the initial vector - - ``tinterval`` -- list ``[a, b, N]``, where ``(a, b)`` is the domain of the curve - and ``N`` is the number of subdivision points. + - ``tinterval`` -- list ``[a, b, N]``, where ``(a, b)`` is the domain of the curve + and ``N`` is the number of subdivision points OUTPUT: The list consisting of lists ``[t, [v1(t), v2(t)]]``, where - - ``t`` is a subdivision point; + - ``t`` -- a subdivision point; - - ``[v1(t), v2(t)]`` is the list of coordinates of the vector parallel translated - along the curve. + - ``[v1(t), v2(t)]`` is the list of coordinates of the vector parallel translated + along the curve. EXAMPLES:: @@ -1697,7 +1621,6 @@ def parallel_translation_numerical(self,curve,t,v0,tinterval): [0.0000, 0.1571, 0.3142, 0.4712, 0.6283, 0.7854] sage: [round4(v) for v in components] [[1.000, 1.000], [0.9876, 1.025], [0.9499, 1.102], [0.8853, 1.238], [0.7920, 1.448], [0.6687, 1.762]] - """ solver = self._create_pt_ode_system(tuple(curve), t) diff --git a/src/sage/geometry/riemannian_manifolds/surface3d_generators.py b/src/sage/geometry/riemannian_manifolds/surface3d_generators.py index 859951befd2..76177dc279b 100644 --- a/src/sage/geometry/riemannian_manifolds/surface3d_generators.py +++ b/src/sage/geometry/riemannian_manifolds/surface3d_generators.py @@ -28,9 +28,9 @@ class SurfaceGenerators: in 3D. """ @staticmethod - def Catenoid(c=1, name="Catenoid"): + def Catenoid(c=1, name='Catenoid'): r""" - Return a catenoid surface, with parametric representation + Return a catenoid surface, with parametric representation. .. MATH:: @@ -42,9 +42,9 @@ def Catenoid(c=1, name="Catenoid"): INPUT: - - ``c`` -- surface parameter. + - ``c`` -- surface parameter - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Catenoid`. @@ -61,9 +61,9 @@ def Catenoid(c=1, name="Catenoid"): return ParametrizedSurface3D(catenoid_eq, coords, name) @staticmethod - def Crosscap(r=1, name="Crosscap"): + def Crosscap(r=1, name='Crosscap'): r""" - Return a crosscap surface, with parametrization + Return a crosscap surface, with parametrization. .. MATH:: @@ -75,9 +75,9 @@ def Crosscap(r=1, name="Crosscap"): INPUT: - - ``r`` -- surface parameter. + - ``r`` -- surface parameter - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Cross-cap`. @@ -97,7 +97,7 @@ def Crosscap(r=1, name="Crosscap"): @staticmethod def Dini(a=1, b=1, name="Dini's surface"): r""" - Return Dini's surface, with parametrization + Return Dini's surface, with parametrization. .. MATH:: @@ -109,9 +109,9 @@ def Dini(a=1, b=1, name="Dini's surface"): INPUT: - - ``a``, ``b`` -- surface parameters. + - ``a``, ``b`` -- surface parameters - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Dini%27s_surface`. @@ -129,7 +129,7 @@ def Dini(a=1, b=1, name="Dini's surface"): return ParametrizedSurface3D(dini_eq, coords, name) @staticmethod - def Ellipsoid(center=(0, 0, 0), axes=(1, 1, 1), name="Ellipsoid"): + def Ellipsoid(center=(0, 0, 0), axes=(1, 1, 1), name='Ellipsoid'): r""" Return an ellipsoid centered at ``center`` whose semi-principal axes have lengths given by the components of ``axes``. The @@ -145,11 +145,11 @@ def Ellipsoid(center=(0, 0, 0), axes=(1, 1, 1), name="Ellipsoid"): INPUT: - - ``center`` -- 3-tuple. Coordinates of the center of the ellipsoid. + - ``center`` -- 3-tuple; coordinates of the center of the ellipsoid - - ``axes`` -- 3-tuple. Lengths of the semi-principal axes. + - ``axes`` -- 3-tuple; lengths of the semi-principal axes - - ``name`` -- string. Name of the ellipsoid. + - ``name`` -- string; name of the ellipsoid For more information, see :wikipedia:`Ellipsoid`. @@ -172,7 +172,7 @@ def Ellipsoid(center=(0, 0, 0), axes=(1, 1, 1), name="Ellipsoid"): @staticmethod def Enneper(name="Enneper's surface"): r""" - Return Enneper's surface, with parametrization + Return Enneper's surface, with parametrization. .. MATH:: @@ -184,7 +184,7 @@ def Enneper(name="Enneper's surface"): INPUT: - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Enneper_surface`. @@ -201,9 +201,9 @@ def Enneper(name="Enneper's surface"): return ParametrizedSurface3D(enneper_eq, coords, name) @staticmethod - def Helicoid(h=1, name="Helicoid"): + def Helicoid(h=1, name='Helicoid'): r""" - Return a helicoid surface, with parametrization + Return a helicoid surface, with parametrization. .. MATH:: @@ -216,9 +216,9 @@ def Helicoid(h=1, name="Helicoid"): INPUT: - ``h`` -- distance along the z-axis between two - successive turns of the helicoid. + successive turns of the helicoid - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Helicoid`. @@ -249,9 +249,9 @@ def Klein(r=1, name="Klein bottle"): INPUT: - - ``r`` -- radius of the "figure-8" circle. + - ``r`` -- radius of the "figure-8" circle - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Klein_bottle`. @@ -282,7 +282,7 @@ def MonkeySaddle(name="Monkey saddle"): INPUT: - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Monkey_saddle`. @@ -302,7 +302,7 @@ def MonkeySaddle(name="Monkey saddle"): @staticmethod def Paraboloid(a=1, b=1, c=1, elliptic=True, name=None): r""" - Return a paraboloid with equation + Return a paraboloid with equation. .. MATH:: @@ -313,12 +313,12 @@ def Paraboloid(a=1, b=1, c=1, elliptic=True, name=None): INPUT: - - ``a``, ``b``, ``c`` -- Surface parameters. + - ``a``, ``b``, ``c`` -- surface parameters - - ``elliptic`` (default: ``True``) -- whether to create an elliptic or - hyperbolic paraboloid. + - ``elliptic`` -- boolean (default: ``True``); whether to create an + elliptic or hyperbolic paraboloid - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Paraboloid`. @@ -353,17 +353,17 @@ def Paraboloid(a=1, b=1, c=1, elliptic=True, name=None): return ParametrizedSurface3D(paraboloid_eq, coords, name) @staticmethod - def Sphere(center=(0, 0, 0), R=1, name="Sphere"): + def Sphere(center=(0, 0, 0), R=1, name='Sphere'): r""" Return a sphere of radius ``R`` centered at ``center``. INPUT: - - ``center`` -- 3-tuple, center of the sphere. + - ``center`` -- 3-tuple; center of the sphere - - ``R`` -- Radius of the sphere. + - ``R`` -- radius of the sphere - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Sphere`. @@ -394,7 +394,7 @@ def Sphere(center=(0, 0, 0), R=1, name="Sphere"): return SurfaceGenerators.Ellipsoid(center, (R, R, R), name) @staticmethod - def Torus(r=2, R=3, name="Torus"): + def Torus(r=2, R=3, name='Torus'): r""" Return a torus obtained by revolving a circle of radius ``r`` around a coplanar axis ``R`` units away from the center of the circle. The @@ -410,9 +410,9 @@ def Torus(r=2, R=3, name="Torus"): INPUT: - - ``r``, ``R`` -- Minor and major radius of the torus. + - ``r``, ``R`` -- minor and major radius of the torus - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Torus`. @@ -439,7 +439,7 @@ def WhitneyUmbrella(name="Whitney's umbrella"): INPUT: - - ``name`` -- string. Name of the surface. + - ``name`` -- string; name of the surface For more information, see :wikipedia:`Whitney_umbrella`. diff --git a/src/sage/geometry/toric_lattice.py b/src/sage/geometry/toric_lattice.py index d37888416b5..a79bac65c6e 100644 --- a/src/sage/geometry/toric_lattice.py +++ b/src/sage/geometry/toric_lattice.py @@ -169,11 +169,9 @@ def is_ToricLattice(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - - ``True`` if ``x`` is a toric lattice and ``False`` otherwise. + OUTPUT: ``True`` if ``x`` is a toric lattice and ``False`` otherwise EXAMPLES:: @@ -204,11 +202,9 @@ def is_ToricLatticeQuotient(x): INPUT: - - ``x`` -- anything. - - OUTPUT: + - ``x`` -- anything - - ``True`` if ``x`` is a toric lattice quotient and ``False`` otherwise. + OUTPUT: ``True`` if ``x`` is a toric lattice quotient and ``False`` otherwise EXAMPLES:: @@ -245,19 +241,17 @@ class ToricLatticeFactory(UniqueFactory): INPUT: - - ``rank`` -- nonnegative integer, the only mandatory parameter; + - ``rank`` -- nonnegative integer; the only mandatory parameter - - ``name`` -- string; + - ``name`` -- string - - ``dual_name`` -- string; + - ``dual_name`` -- string - - ``latex_name`` -- string; + - ``latex_name`` -- string - - ``latex_dual_name`` -- string. + - ``latex_dual_name`` -- string - OUTPUT: - - - lattice. + OUTPUT: lattice A toric lattice is uniquely determined by its rank and associated names. There are four such "associated names" whose meaning should be clear from @@ -413,9 +407,7 @@ def __call__(self, *args, **kwds): - anything that can be interpreted as coordinates, except for elements of other lattices. - OUTPUT: - - - :class:`~sage.geometry.toric_lattice_element.ToricLatticeElement`. + OUTPUT: :class:`~sage.geometry.toric_lattice_element.ToricLatticeElement` TESTS:: @@ -485,7 +477,6 @@ def _coerce_map_from_(self, other): Traceback (most recent call last): ... TypeError: N(1, 2, 3) cannot be converted to 3-d lattice M! - """ if (isinstance(other, ToricLattice_generic) and other.ambient_module() is not self.ambient_module()): @@ -498,12 +489,10 @@ def __contains__(self, point): INPUT: - - ``point`` -- anything. - - OUTPUT: + - ``point`` -- anything - - ``True`` if ``point`` is an element of ``self``, ``False`` - otherwise. + OUTPUT: ``True`` if ``point`` is an element of ``self``, ``False`` + otherwise TESTS:: @@ -541,9 +530,9 @@ def construction(self): OUTPUT: - - ``None``, we do not think of toric lattices as constructed from - simpler objects since we do not want to perform arithmetic involving - different lattices. + ``None``, we do not think of toric lattices as constructed from + simpler objects since we do not want to perform arithmetic involving + different lattices. TESTS:: @@ -558,7 +547,7 @@ def direct_sum(self, other): INPUT: - - ``other`` -- a toric lattice or more general module. + - ``other`` -- a toric lattice or more general module OUTPUT: @@ -658,10 +647,10 @@ def quotient(self, sub, check=True, INPUT: - - ``sub`` -- sublattice of self; + - ``sub`` -- sublattice of self - - ``check`` -- (default: ``True``) whether or not to check that ``sub`` is - a valid sublattice. + - ``check`` -- boolean (default: ``True``); whether or not to check that ``sub`` is + a valid sublattice If the quotient is one-dimensional and torsion free, the following two mutually exclusive keyword arguments are also @@ -693,7 +682,7 @@ def quotient(self, sub, check=True, by Sublattice Attempting to quotient one lattice by a sublattice of another - will result in a :class:`ValueError`:: + will result in a :exc:`ValueError`:: sage: N = ToricLattice(3) sage: M = ToricLattice(3, name='M') @@ -755,9 +744,7 @@ def saturation(self): r""" Return the saturation of ``self``. - OUTPUT: - - - a :class:`toric lattice `. + OUTPUT: a :class:`toric lattice ` EXAMPLES:: @@ -781,13 +768,11 @@ def span(self, gens, base_ring=ZZ, *args, **kwds): INPUT: - ``gens`` -- list of elements of the ambient vector space of - ``self``. + ``self`` - - ``base_ring`` -- (default: `\ZZ`) base ring for the generated module. - - OUTPUT: + - ``base_ring`` -- (default: `\ZZ`) base ring for the generated module - - submodule spanned by ``gens``. + OUTPUT: submodule spanned by ``gens`` .. NOTE:: @@ -827,13 +812,11 @@ def span_of_basis(self, basis, base_ring=ZZ, *args, **kwds): INPUT: - ``basis`` -- list of elements of the ambient vector space of - ``self``. + ``self`` - - ``base_ring`` -- (default: `\ZZ`) base ring for the generated module. + - ``base_ring`` -- (default: `\ZZ`) base ring for the generated module - OUTPUT: - - - submodule spanned by ``basis``. + OUTPUT: submodule spanned by ``basis`` .. NOTE:: @@ -943,11 +926,9 @@ def __richcmp__(self, right, op): INPUT: - - ``right`` -- anything. + - ``right`` -- anything - OUTPUT: - - boolean + OUTPUT: boolean There is equality if ``right`` is a toric lattice of the same dimension as ``self`` and their associated names are the @@ -984,9 +965,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1000,9 +979,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1016,9 +993,7 @@ def ambient_module(self): r""" Return the ambient module of ``self``. - OUTPUT: - - - :class:`toric lattice `. + OUTPUT: :class:`toric lattice ` .. NOTE:: @@ -1039,9 +1014,7 @@ def dual(self): r""" Return the lattice dual to ``self``. - OUTPUT: - - - :class:`toric lattice `. + OUTPUT: :class:`toric lattice ` EXAMPLES:: @@ -1077,9 +1050,7 @@ def plot(self, **options): - any options for toric plots (see :func:`toric_plotter.options `), none are mandatory. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -1105,17 +1076,15 @@ class ToricLattice_sublattice_with_basis(ToricLattice_generic, :class:`~sage.modules.free_module.FreeModule_submodule_with_basis_pid`): - ``ambient`` -- ambient :class:`toric lattice ` for - this sublattice; + this sublattice - ``basis`` -- list of linearly independent elements of ``ambient``, these elements will be used as the default basis of the constructed - sublattice; + sublattice - - see the base class for other available options. + - see the base class for other available options - OUTPUT: - - - sublattice of a toric lattice with a user-specified basis. + OUTPUT: sublattice of a toric lattice with a user-specified basis See also :class:`ToricLattice_sublattice` if you do not want to specify an explicit basis. @@ -1149,9 +1118,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1171,9 +1138,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1194,9 +1159,7 @@ def dual(self): r""" Return the lattice dual to ``self``. - OUTPUT: - - - a :class:`toric lattice quotient `. + OUTPUT: a :class:`toric lattice quotient ` EXAMPLES:: @@ -1223,9 +1186,7 @@ def plot(self, **options): - any options for toric plots (see :func:`toric_plotter.options `), none are mandatory. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -1236,7 +1197,7 @@ def plot(self, **options): Now we plot both the ambient lattice and its sublattice:: - sage: N.plot() + sublattice.plot(point_color="red") # needs sage.plot + sage: N.plot() + sublattice.plot(point_color='red') # needs sage.plot Graphics3d Object """ if "show_lattice" not in options: @@ -1262,16 +1223,14 @@ class ToricLattice_sublattice(ToricLattice_sublattice_with_basis, :class:`~sage.modules.free_module.FreeModule_submodule_pid`): - ``ambient`` -- ambient :class:`toric lattice ` for - this sublattice; + this sublattice - ``gens`` -- list of elements of ``ambient`` generating the constructed - sublattice; + sublattice - - see the base class for other available options. + - see the base class for other available options - OUTPUT: - - - sublattice of a toric lattice with an automatically chosen basis. + OUTPUT: sublattice of a toric lattice with an automatically chosen basis See also :class:`ToricLattice_sublattice_with_basis` if you want to specify an explicit basis. @@ -1315,9 +1274,7 @@ class ToricLattice_quotient_element(FGP_Element): - same as for :class:`~sage.modules.fg_pid.fgp_element.FGP_Element`. - OUTPUT: - - - element of a toric lattice quotient. + OUTPUT: element of a toric lattice quotient TESTS:: @@ -1342,9 +1299,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1360,9 +1315,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1378,11 +1331,9 @@ def set_immutable(self): r""" Make ``self`` immutable. - OUTPUT: - - - none. + OUTPUT: none - .. note:: Elements of toric lattice quotients are always immutable, so + .. NOTE:: Elements of toric lattice quotients are always immutable, so this method does nothing, it is introduced for compatibility purposes only. @@ -1402,12 +1353,12 @@ class ToricLattice_quotient(FGP_Module_class): INPUT: - - ``V`` -- ambient toric lattice; + - ``V`` -- ambient toric lattice - - ``W`` -- sublattice of ``V``; + - ``W`` -- sublattice of ``V`` - - ``check`` -- (default: ``True``) whether to check correctness of input - or not. + - ``check`` -- boolean (default: ``True``); whether to check correctness of input + or not If the quotient is one-dimensional and torsion free, the following two mutually exclusive keyword arguments are also allowed. They @@ -1428,9 +1379,7 @@ class ToricLattice_quotient(FGP_Module_class): Further given named arguments are passed to the constructor of an FGP module. - OUTPUT: - - - quotient of ``V`` by ``W``. + OUTPUT: quotient of ``V`` by ``W`` EXAMPLES: @@ -1472,7 +1421,7 @@ class ToricLattice_quotient(FGP_Module_class): def __init__(self, V, W, check=True, positive_point=None, positive_dual_point=None, **kwds): r""" - The constructor + The constructor. See :class:`ToricLattice_quotient` for an explanation of the arguments. @@ -1483,7 +1432,7 @@ def __init__(self, V, W, check=True, positive_point=None, positive_dual_point=No sage: ToricLattice_quotient(N, N.span([N(1,2,3)])) 2-d lattice, quotient of 3-d lattice N by Sublattice - An :class:`ArithmeticError` will be raised if ``W`` is not a + An :exc:`ArithmeticError` will be raised if ``W`` is not a sublattice of ``V``:: sage: N = ToricLattice(3) @@ -1607,9 +1556,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1629,9 +1576,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -1659,12 +1604,12 @@ def _module_constructor(self, V, W, check=True): INPUT: - - ``V`` -- ambient toric lattice; + - ``V`` -- ambient toric lattice - - ``W`` -- sublattice of ``V``; + - ``W`` -- sublattice of ``V`` - - ``check`` -- (default: ``True``) whether to check - correctness of input or not. + - ``check`` -- boolean (default: ``True``); whether to check + correctness of input or not TESTS:: @@ -1683,12 +1628,10 @@ def base_extend(self, R): INPUT: - - ``R`` -- either `\ZZ` or `\QQ`. + - ``R`` -- either `\ZZ` or `\QQ` - OUTPUT: - - - ``self`` if `R=\ZZ`, quotient of the base extension of the ambient - lattice by the base extension of the sublattice if `R=\QQ`. + OUTPUT: ``self`` if `R=\ZZ`, quotient of the base extension of the ambient + lattice by the base extension of the sublattice if `R=\QQ` EXAMPLES:: @@ -1716,9 +1659,7 @@ def is_torsion_free(self): r""" Check if ``self`` is torsion-free. - OUTPUT: - - - ``True`` is ``self`` has no torsion and ``False`` otherwise. + OUTPUT: ``True`` if ``self`` has no torsion and ``False`` otherwise EXAMPLES:: @@ -1738,9 +1679,7 @@ def dual(self): r""" Return the lattice dual to ``self``. - OUTPUT: - - - a :class:`toric lattice quotient `. + OUTPUT: a :class:`toric lattice quotient ` EXAMPLES:: @@ -1760,9 +1699,7 @@ def rank(self): r""" Return the rank of ``self``. - OUTPUT: - - Integer. The dimension of the free part of the quotient. + OUTPUT: integer; the dimension of the free part of the quotient EXAMPLES:: @@ -1793,12 +1730,10 @@ def coordinate_vector(self, x, reduce=False): - ``x`` -- element of ``self`` or convertible to ``self`` - - ``reduce`` -- (default: ``False``); if ``True``, reduce coefficients + - ``reduce`` -- (default: ``False``) if ``True``, reduce coefficients modulo invariants - OUTPUT: - - The coordinates as a vector. + OUTPUT: the coordinates as a vector EXAMPLES:: diff --git a/src/sage/geometry/toric_lattice_element.pyx b/src/sage/geometry/toric_lattice_element.pyx index 5fb647a60ba..1b8178077eb 100644 --- a/src/sage/geometry/toric_lattice_element.pyx +++ b/src/sage/geometry/toric_lattice_element.pyx @@ -109,11 +109,9 @@ def is_ToricLatticeElement(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - - ``True`` if ``x`` is an element of a toric lattice, ``False`` otherwise. + OUTPUT: ``True`` if ``x`` is an element of a toric lattice, ``False`` otherwise EXAMPLES:: @@ -154,9 +152,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): - same as for :class:`~sage.modules.vector_integer_dense.Vector_integer_dense`. - OUTPUT: - - - element of a toric lattice. + OUTPUT: element of a toric lattice TESTS:: @@ -176,9 +172,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): - ``right`` -- another ToricLatticeElement - OUTPUT: - - boolean + OUTPUT: boolean First compare the ambient toric lattice, then compare the vectors. @@ -212,9 +206,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): r""" Return the hash of ``self``. - OUTPUT: - - - integer. + OUTPUT: integer TESTS:: @@ -236,7 +228,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): INPUT: - - ``other`` -- :class:`ToricLatticeElement`. + - ``other`` -- :class:`ToricLatticeElement` OUTPUT: @@ -307,18 +299,16 @@ cdef class ToricLatticeElement(Vector_integer_dense): # is wrong from our point of view. cpdef _dot_product_(self, Vector right): """ - Raise a :class:`TypeError` exception. + Raise a :exc:`TypeError` exception. Dot product is not defined on toric lattices (there are actions of dual lattices on each other instead). INPUT: - - ``right`` -- vector. - - OUTPUT: + - ``right`` -- vector - - :class:`TypeError` exception is raised. + OUTPUT: :exc:`TypeError` exception is raised TESTS:: @@ -339,9 +329,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -357,9 +345,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -393,9 +379,7 @@ cdef class ToricLatticeElement(Vector_integer_dense): - any options for toric plots (see :func:`toric_plotter.options `), none are mandatory. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -412,21 +396,19 @@ cdef class ToricLatticeElement(Vector_integer_dense): def unpickle_v1(parent, entries, degree, is_mutable): """ - Unpickle a :class:`ToricLatticeElement` + Unpickle a :class:`ToricLatticeElement`. INPUT: - - ``parent`` -- The parent toric lattice. - - - ``entries`` -- a list. The coordinates of the lattice point. + - ``parent`` -- the parent toric lattice - - ``degree`` -- integer. the dimension of the toric lattice. + - ``entries`` -- list; the coordinates of the lattice point - - ``is_mutable`` -- boolean. Whether the lattice element is mutable. + - ``degree`` -- integer; the dimension of the toric lattice - OUTPUT: + - ``is_mutable`` -- boolean; whether the lattice element is mutable - The :class:`ToricLatticeElement` determined by the input data. + OUTPUT: the :class:`ToricLatticeElement` determined by the input data EXAMPLES:: diff --git a/src/sage/geometry/toric_plotter.py b/src/sage/geometry/toric_plotter.py index e6dfb454027..589be12b21d 100644 --- a/src/sage/geometry/toric_plotter.py +++ b/src/sage/geometry/toric_plotter.py @@ -116,17 +116,15 @@ class ToricPlotter(SageObject): - ``all_options`` -- a :class:`dictionary `, containing any of the options related to toric objects (see :func:`options`) and any other - options that will be passed to lower level plotting functions; + options that will be passed to lower level plotting functions - - ``dimension`` -- an integer (1, 2, or 3), dimension of toric objects to - be plotted; + - ``dimension`` -- integer (1, 2, or 3); dimension of toric objects to + be plotted - - ``generators`` -- (optional) a list of ray generators, see examples for - a detailed explanation of this argument. + - ``generators`` -- (optional) a list of ray generators; see examples for + a detailed explanation of this argument - OUTPUT: - - - a toric plotter. + OUTPUT: a toric plotter EXAMPLES: @@ -248,11 +246,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- anything. - - OUTPUT: + - ``other`` -- anything - - ``True`` if ``self`` is equal to ``other``, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is equal to ``other``, ``False`` otherwise TESTS:: @@ -273,9 +269,7 @@ def adjust_options(self): that were not specified by the user, based on the other options. See :class:`ToricPlotter` for a detailed example. - OUTPUT: - - - none. + OUTPUT: none TESTS:: @@ -325,15 +319,13 @@ def include_points(self, points, force=False): INPUT: - - ``points`` -- a list of points; + - ``points`` -- list of points - - ``force`` -- boolean (default: ``False``). by default, only bounds + - ``force`` -- boolean (default: ``False``); by default, only bounds that were not set before will be chosen to include ``points``. Use ``force=True`` if you don't mind increasing existing bounding box. - OUTPUT: - - - none. + OUTPUT: none EXAMPLES:: @@ -382,9 +374,7 @@ def plot_generators(self): Ray generators must be specified during construction or using :meth:`set_rays` before calling this method. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -429,13 +419,11 @@ def plot_labels(self, labels, positions): INPUT: - - ``labels`` -- a string or a list of strings; + - ``labels`` -- string or list of strings - - ``positions`` -- a list of points. + - ``positions`` -- list of points - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -466,9 +454,7 @@ def plot_lattice(self): r""" Plot the lattice (i.e. its points in the cut-off bounds of ``self``). - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -508,11 +494,9 @@ def plot_points(self, points): INPUT: - - ``points`` -- a list of points. - - OUTPUT: + - ``points`` -- list of points - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -535,9 +519,7 @@ def plot_ray_labels(self): Ray generators must be specified during construction or using :meth:`set_rays` before calling this method. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -556,9 +538,7 @@ def plot_rays(self): Ray generators must be specified during construction or using :meth:`set_rays` before calling this method. - OUTPUT: - - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -595,11 +575,9 @@ def plot_walls(self, walls): INPUT: - - ``walls`` -- a list of 2-d cones. - - OUTPUT: + - ``walls`` -- list of 2-d cones - - a plot. + OUTPUT: a plot EXAMPLES:: @@ -692,11 +670,9 @@ def set_rays(self, generators): INPUT: - - ``generators`` -- a list of primitive non-zero ray generators. + - ``generators`` -- list of primitive nonzero ray generators - OUTPUT: - - - none. + OUTPUT: none EXAMPLES:: @@ -742,11 +718,9 @@ def _unrecognized_option(option): INPUT: - - ``option`` -- a string. - - OUTPUT: + - ``option`` -- string - - none, a :class:`KeyError` exception is raised. + OUTPUT: none, a :exc:`KeyError` exception is raised TESTS:: @@ -770,11 +744,9 @@ def color_list(color, n): - ``color`` -- anything specifying a :class:`Color`, a list of such specifications, or the string "rainbow"; - - ``n`` -- an integer. + - ``n`` -- integer - OUTPUT: - - - a list of ``n`` colors. + OUTPUT: list of ``n`` colors If ``color`` specified a single color, it is repeated ``n`` times. If it was a list of ``n`` colors, it is returned without changes. If it was @@ -822,19 +794,17 @@ def label_list(label, n, math_mode, index_set=None): INPUT: - - ``label`` -- ``None``, a string, or a list of string; + - ``label`` -- ``None``, a string, or a list of string - - ``n`` -- an integer; + - ``n`` -- integer - - ``math_mode`` -- boolean, if ``True``, will produce LaTeX expressions - for labels; + - ``math_mode`` -- boolean; if ``True``, will produce LaTeX expressions + for labels - - ``index_set`` -- a list of integers (default: ``range(n)``) that will be - used as subscripts for labels. + - ``index_set`` -- list of integers (default: ``range(n)``) that will be + used as subscripts for labels - OUTPUT: - - - a list of ``n`` labels. + OUTPUT: list of ``n`` labels If ``label`` was a list of ``n`` entries, it is returned without changes. If ``label`` is ``None``, a list of ``n`` ``None``'s is returned. If @@ -886,7 +856,7 @@ def options(option=None, **kwds): OR: - - ``option`` -- a string, name of the option whose value you wish to get; + - ``option`` -- string, name of the option whose value you wish to get; OR: @@ -973,31 +943,31 @@ def options(option=None, **kwds): - ``wall_alpha`` -- a number between 0 and 1, the alpha-value for walls (determining their transparency); - - ``point_size`` -- an integer, the size of lattice points; + - ``point_size`` -- integer; the size of lattice points - - ``ray_thickness`` -- an integer, the thickness of rays; + - ``ray_thickness`` -- integer; the thickness of rays - - ``generator_thickness`` -- an integer, the thickness of generators; + - ``generator_thickness`` -- integer; the thickness of generators - - ``font_size`` -- an integer, the size of font used for labels; + - ``font_size`` -- integer; the size of font used for labels - - ``ray_label`` -- a string or a list of strings used for ray labels; use - ``None`` to hide labels; + - ``ray_label`` -- string or list of strings used for ray labels; use + ``None`` to hide labels - - ``wall_label`` -- a string or a list of strings used for wall labels; use - ``None`` to hide labels; + - ``wall_label`` -- string or list of strings used for wall labels; use + ``None`` to hide labels - ``radius`` -- a positive number, the radius of the cut-off region for - "round" mode; + "round" mode - ``xmin``, ``xmax``, ``ymin``, ``ymax``, ``zmin``, ``zmax`` -- numbers determining the cut-off region for "box" mode. Note that you cannot exclude the origin - if you try to do so, bounds will be automatically - expanded to include it; + expanded to include it. - ``lattice_filter`` -- a callable, taking as an argument a lattice point and returning ``True`` if this point should be included on the plot - (useful, e.g. for plotting sublattices); + (useful, e.g. for plotting sublattices) - ``wall_zorder``, ``ray_zorder``, ``generator_zorder``, ``point_zorder``, ``label_zorder`` -- integers, z-orders for different classes of objects. @@ -1022,12 +992,12 @@ def options(option=None, **kwds): The following line will make all subsequent toric plotting commands to draw "rainbows" from walls:: - sage: toric_plotter.options(wall_color="rainbow") + sage: toric_plotter.options(wall_color='rainbow') If you prefer a less colorful output (e.g. if you need black-and-white illustrations for a paper), you can use something like this:: - sage: toric_plotter.options(wall_color="grey") + sage: toric_plotter.options(wall_color='grey') """ global _options if option is None and not kwds: @@ -1052,9 +1022,7 @@ def reset_options(): r""" Reset options for plots of toric geometry objects. - OUTPUT: - - - none. + OUTPUT: none EXAMPLES:: @@ -1096,14 +1064,12 @@ def sector(ray1, ray2, **extra_options): INPUT: - ``ray1``, ``ray2`` -- rays in 2- or 3-dimensional space of the same - length; + length - - ``extra_options`` -- a dictionary of options that should be passed to - lower level plotting functions. - - OUTPUT: + - ``extra_options`` -- dictionary of options that should be passed to + lower level plotting functions - - a plot. + OUTPUT: a plot EXAMPLES:: diff --git a/src/sage/geometry/triangulation/base.pyx b/src/sage/geometry/triangulation/base.pyx index cb9cb948256..55144d1623c 100644 --- a/src/sage/geometry/triangulation/base.pyx +++ b/src/sage/geometry/triangulation/base.pyx @@ -50,18 +50,18 @@ cdef class Point(SageObject): INPUT: - - ``point_configuration`` -- :class:`PointConfiguration_base`. The - point configuration to which the point belongs. + - ``point_configuration`` -- :class:`PointConfiguration_base`; the + point configuration to which the point belongs - - ``i`` -- integer. The index of the point in the point - configuration. + - ``i`` -- integer; the index of the point in the point + configuration - - ``projective`` -- the projective coordinates of the point. + - ``projective`` -- the projective coordinates of the point - - ``affine`` -- the affine coordinates of the point. + - ``affine`` -- the affine coordinates of the point - ``reduced`` -- the reduced (with linearities removed) - coordinates of the point. + coordinates of the point EXAMPLES:: @@ -99,7 +99,7 @@ cdef class Point(SageObject): def __hash__(self): r""" - Hash value for a point in a point configuration + Hash value for a point in a point configuration. EXAMPLES:: @@ -113,9 +113,7 @@ cdef class Point(SageObject): r""" Return the point configuration to which the point belongs. - OUTPUT: - - A :class:`~sage.geometry.triangulation.point_configuration.PointConfiguration`. + OUTPUT: a :class:`~sage.geometry.triangulation.point_configuration.PointConfiguration` EXAMPLES:: @@ -176,9 +174,7 @@ cdef class Point(SageObject): r""" Return the projective coordinates of the point in the ambient space. - OUTPUT: - - A tuple containing the coordinates. + OUTPUT: a tuple containing the coordinates EXAMPLES:: @@ -202,9 +198,7 @@ cdef class Point(SageObject): r""" Return the affine coordinates of the point in the ambient space. - OUTPUT: - - A tuple containing the coordinates. + OUTPUT: a tuple containing the coordinates EXAMPLES:: @@ -229,9 +223,7 @@ cdef class Point(SageObject): Return the affine coordinates of the point on the hyperplane spanned by the point configuration. - OUTPUT: - - A tuple containing the coordinates. + OUTPUT: a tuple containing the coordinates EXAMPLES:: @@ -256,9 +248,7 @@ cdef class Point(SageObject): Return the projective coordinates of the point on the hyperplane spanned by the point configuration. - OUTPUT: - - A tuple containing the coordinates. + OUTPUT: a tuple containing the coordinates EXAMPLES:: @@ -283,9 +273,7 @@ cdef class Point(SageObject): Return the affine coordinates of the point on the hyperplane spanned by the point configuration. - OUTPUT: - - A tuple containing the coordinates. + OUTPUT: a tuple containing the coordinates EXAMPLES:: @@ -310,9 +298,7 @@ cdef class Point(SageObject): Return the affine coordinates of the point on the hyperplane spanned by the point configuration. - OUTPUT: - - A tuple containing the coordinates. + OUTPUT: a tuple containing the coordinates EXAMPLES:: @@ -338,9 +324,7 @@ cdef class Point(SageObject): """ Return a string representation of the point. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -372,12 +356,12 @@ cdef class PointConfiguration_base(Parent): INPUT: - - ``points`` -- a tuple of tuples of projective coordinates - with ``1`` as the final coordinate. + - ``points`` -- tuple of tuples of projective coordinates + with ``1`` as the final coordinate - - ``defined_affine`` -- Boolean. Whether the point + - ``defined_affine`` -- boolean; whether the point configuration is defined as a configuration of affine (as - opposed to projective) points. + opposed to projective) points TESTS:: @@ -470,9 +454,7 @@ cdef class PointConfiguration_base(Parent): """ Return the vector space that contains the affine points. - OUTPUT: - - A vector space over the fraction field of :meth:`base_ring`. + OUTPUT: a vector space over the fraction field of :meth:`base_ring` EXAMPLES:: @@ -491,9 +473,7 @@ cdef class PointConfiguration_base(Parent): Return the vector space that is spanned by the homogeneous coordinates. - OUTPUT: - - A vector space over the fraction field of :meth:`base_ring`. + OUTPUT: a vector space over the fraction field of :meth:`base_ring` EXAMPLES:: @@ -545,9 +525,7 @@ cdef class PointConfiguration_base(Parent): Return the base ring, that is, the ring containing the coordinates of the points. - OUTPUT: - - A ring. + OUTPUT: a ring EXAMPLES:: @@ -569,10 +547,8 @@ cdef class PointConfiguration_base(Parent): """ Return whether the configuration is defined by affine points. - OUTPUT: - - Boolean. If true, the homogeneous coordinates all have `1` as - their last entry. + OUTPUT: boolean; if true, the homogeneous coordinates all have `1` as + their last entry EXAMPLES:: @@ -588,7 +564,7 @@ cdef class PointConfiguration_base(Parent): def _assert_is_affine(self): """ - Raise a :class:`ValueError` if the point configuration is not + Raise a :exc:`ValueError` if the point configuration is not defined by affine points. EXAMPLES:: @@ -612,11 +588,9 @@ cdef class PointConfiguration_base(Parent): INPUT: - - ``i`` -- integer. - - OUTPUT: + - ``i`` -- integer - The ``i``-th point of the point configuration. + OUTPUT: the ``i``-th point of the point configuration EXAMPLES:: @@ -680,17 +654,15 @@ cdef class PointConfiguration_base(Parent): def point(self, i): """ - Return the i-th point of the configuration. + Return the `i`-th point of the configuration. Same as :meth:`__getitem__` INPUT: - - ``i`` -- integer. + - ``i`` -- integer - OUTPUT: - - A point of the point configuration. + OUTPUT: a point of the point configuration EXAMPLES:: @@ -742,11 +714,9 @@ cdef class PointConfiguration_base(Parent): INPUT: - ``simplex`` -- iterable, for example a list. The elements - are the vertex indices of the simplex. - - OUTPUT: + are the vertex indices of the simplex - An integer that uniquely specifies the simplex. + OUTPUT: integer that uniquely specifies the simplex EXAMPLES:: @@ -785,7 +755,7 @@ cdef class PointConfiguration_base(Parent): INPUT: - - ``s`` -- int. An integer that uniquely specifies a simplex. + - ``s`` -- integer that uniquely specifies a simplex OUTPUT: @@ -830,12 +800,12 @@ cdef class PointConfiguration_base(Parent): ######################################################################## cdef class ConnectedTriangulationsIterator(SageObject): r""" - A Python shim for the C++-class 'triangulations' + A Python shim for the C++-class 'triangulations'. INPUT: - ``point_configuration`` -- a - :class:`~sage.geometry.triangulation.point_configuration.PointConfiguration`. + :class:`~sage.geometry.triangulation.point_configuration.PointConfiguration` - ``seed`` -- a regular triangulation or ``None`` (default). In the latter case, a suitable triangulation is generated @@ -856,7 +826,7 @@ cdef class ConnectedTriangulationsIterator(SageObject): integer is passed, all returned triangulations will be star with respect to the - - ``fine`` -- boolean (default: ``False``). Whether to return only + - ``fine`` -- boolean (default: ``False``); whether to return only fine triangulations, that is, simplicial decompositions that make use of all the points of the configuration. diff --git a/src/sage/geometry/triangulation/element.py b/src/sage/geometry/triangulation/element.py index 3e6e0ed152d..2baf66a578e 100644 --- a/src/sage/geometry/triangulation/element.py +++ b/src/sage/geometry/triangulation/element.py @@ -55,13 +55,11 @@ def triangulation_render_2d(triangulation, **kwds): INPUT: - - ``triangulation`` -- a :class:`Triangulation`. + - ``triangulation`` -- a :class:`Triangulation` - - ``**kwds`` -- keywords that are passed on to the graphics primitives. + - ``**kwds`` -- keywords that are passed on to the graphics primitives - OUTPUT: - - A 2-d graphics object. + OUTPUT: a 2-d graphics object EXAMPLES:: @@ -116,13 +114,11 @@ def triangulation_render_3d(triangulation, **kwds): INPUT: - - ``triangulation`` -- a :class:`Triangulation`. - - - ``**kwds`` -- keywords that are passed on to the graphics primitives. + - ``triangulation`` -- a :class:`Triangulation` - OUTPUT: + - ``**kwds`` -- keywords that are passed on to the graphics primitives - A 3-d graphics object. + OUTPUT: a 3-d graphics object EXAMPLES:: @@ -236,9 +232,9 @@ def __init__(self, triangulation, parent, check=True): by the correspondence :meth:`PointConfiguration.simplex_to_int`. In the second case, a simplex is specified by listing the indices of the included points. - - ``check`` -- boolean. Whether to perform checks that the + - ``check`` -- boolean; whether to perform checks that the triangulation is, indeed, a triangulation of the point - configuration. + configuration NOTE: @@ -270,7 +266,7 @@ def __init__(self, triangulation, parent, check=True): def point_configuration(self): """ - Returns the point configuration underlying the triangulation. + Return the point configuration underlying the triangulation. EXAMPLES:: @@ -339,15 +335,15 @@ def __iter__(self): def __getitem__(self, i): """ - Access the point indices of the i-th simplex of the triangulation. + Access the point indices of the `i`-th simplex of the triangulation. INPUT: - - ``i`` -- integer. The index of a simplex. + - ``i`` -- integer; the index of a simplex OUTPUT: - A tuple of integers. The vertex indices of the i-th simplex. + A tuple of integers. The vertex indices of the `i`-th simplex. EXAMPLES:: @@ -433,9 +429,7 @@ def gkz_phi(self): that is, the total volume of all simplices containing `p_i`. See also [GKZ1994]_ page 220 equation 1.4. - OUTPUT: - - The phi vector of self. + OUTPUT: the phi vector of self EXAMPLES:: @@ -456,9 +450,7 @@ def enumerate_simplices(self): r""" Return the enumerated simplices. - OUTPUT: - - A tuple of integers that uniquely specifies the triangulation. + OUTPUT: a tuple of integers that uniquely specifies the triangulation EXAMPLES:: @@ -513,7 +505,7 @@ def fan(self, origin=None): coordinates of the points are shifted so that the apex of the fan is the origin of the coordinate system. - .. note:: If the set of cones over the simplices is not a fan, a + .. NOTE:: If the set of cones over the simplices is not a fan, a suitable exception is raised. EXAMPLES:: @@ -558,9 +550,7 @@ def simplicial_complex(self): r""" Return ``self`` as an (abstract) simplicial complex. - OUTPUT: - - A :class:`~sage.topology.simplicial_complex.SimplicialComplex`. + OUTPUT: a :class:`~sage.topology.simplicial_complex.SimplicialComplex` EXAMPLES:: @@ -660,9 +650,7 @@ def boundary_simplicial_complex(self): r""" Return the boundary of ``self`` as an (abstract) simplicial complex. - OUTPUT: - - A :class:`~sage.topology.simplicial_complex.SimplicialComplex`. + OUTPUT: a :class:`~sage.topology.simplicial_complex.SimplicialComplex` EXAMPLES:: @@ -918,7 +906,6 @@ def adjacency_graph(self): sage: t = p.triangulate() sage: t.adjacency_graph() # needs sage.graphs Graph on 8 vertices - """ vertices = [Set(_) for _ in list(self)] from sage.graphs.graph import Graph diff --git a/src/sage/geometry/triangulation/point_configuration.py b/src/sage/geometry/triangulation/point_configuration.py index d515f43ec8a..88aa25f6c46 100644 --- a/src/sage/geometry/triangulation/point_configuration.py +++ b/src/sage/geometry/triangulation/point_configuration.py @@ -20,7 +20,7 @@ triangulations is implemented natively in this package. However, for more advanced options [TOPCOM]_ needs to be installed; see :ref:`spkg_topcom`. -.. note:: +.. NOTE:: TOPCOM and the internal algorithms tend to enumerate triangulations in a different order. This is why we always @@ -215,25 +215,25 @@ class PointConfiguration(UniqueRepresentation, PointConfiguration_base): The constructor accepts the following arguments: - - ``points`` -- the points. Technically, any iterable of iterables + - ``points`` -- the points; technically, any iterable of iterables will do. In particular, a :class:`PointConfiguration` can be passed. - - ``projective`` -- boolean (default: ``False``). Whether the + - ``projective`` -- boolean (default: ``False``); whether the point coordinates should be interpreted as projective (``True``) or affine (``False``) coordinates. If necessary, points are projectivized by setting the last homogeneous coordinate to one and/or affine patches are chosen internally. - - ``connected`` -- boolean (default: ``True``). Whether the + - ``connected`` -- boolean (default: ``True``); whether the triangulations should be connected to the regular triangulations via bistellar flips. These are much easier to compute than all triangulations. - - ``fine`` -- boolean (default: ``False``). Whether the + - ``fine`` -- boolean (default: ``False``); whether the triangulations must be fine, that is, make use of all points of - the configuration. + the configuration - - ``regular`` -- boolean or ``None`` (default: ``None``). Whether + - ``regular`` -- boolean or ``None`` (default: ``None``); whether the triangulations must be regular. A regular triangulation is one that is induced by a piecewise-linear convex support function. In other words, the shadows of the faces of a @@ -245,7 +245,7 @@ class PointConfiguration(UniqueRepresentation, PointConfiguration_base): * ``None`` (default): Both kinds of triangulation. - - ``star`` -- either ``None`` or a point. Whether the + - ``star`` -- either ``None`` or a point; whether the triangulations must be star. A triangulation is star if all maximal simplices contain a common point. The central point can be specified by its index (an integer) in the given points or by @@ -402,7 +402,7 @@ def star_center(self): A :class:`~sage.geometry.triangulation.base.Point` if a distinguished star central point has been fixed. - :class:`ValueError` exception is raised otherwise. + :exc:`ValueError` exception is raised otherwise. EXAMPLES:: @@ -587,13 +587,13 @@ def _TOPCOM_exec(cls, executable, input_string, verbose=True): INPUT: - - ``executable`` -- string. The name of the executable. + - ``executable`` -- string; the name of the executable - - ``input_string`` -- string. Will be piped into the running - executable's stdin. + - ``input_string`` -- string; will be piped into the running + executable's stdin - - ``verbose`` -- boolean. Whether to print out the TOPCOM - interaction. + - ``verbose`` -- boolean; whether to print out the TOPCOM + interaction TESTS:: @@ -691,7 +691,7 @@ def _TOPCOM_communicate(self, executable, verbose=True): def _TOPCOM_triangulations(self, verbose=True): r""" - Returns all triangulations satisfying the restrictions imposed. + Return all triangulations satisfying the restrictions imposed. EXAMPLES:: @@ -729,13 +729,13 @@ def _TOPCOM_triangulate(self, verbose=True): INPUT: - - ``verbose`` -- boolean. Whether to print out the TOPCOM - interaction. + - ``verbose`` -- boolean; whether to print out the TOPCOM + interaction OUTPUT: A :class:`~sage.geometry.triangulation.element.Triangulation` - satisfying all restrictions imposed. This raises a :class:`ValueError` + satisfying all restrictions imposed. This raises a :exc:`ValueError` if no such triangulation exists. EXAMPLES:: @@ -771,9 +771,9 @@ def restrict_to_regular_triangulations(self, regular=True): INPUT: - - ``regular`` -- ``True``, ``False``, or ``None``. Whether to + - ``regular`` -- ``True``, ``False``, or ``None``; whether to restrict to regular triangulations, irregular - triangulations, or lift any restrictions on regularity. + triangulations, or lift any restrictions on regularity OUTPUT: @@ -815,9 +815,9 @@ def restrict_to_connected_triangulations(self, connected=True): INPUT: - - ``connected`` -- boolean. Whether to restrict to + - ``connected`` -- boolean; whether to restrict to triangulations that are connected by bistellar flips to the - regular triangulations. + regular triangulations OUTPUT: @@ -854,7 +854,7 @@ def restrict_to_fine_triangulations(self, fine=True): INPUT: - - ``fine`` -- boolean. Whether to restrict to fine triangulations. + - ``fine`` -- boolean; whether to restrict to fine triangulations OUTPUT: @@ -927,10 +927,10 @@ def restrict_to_star_triangulations(self, star): def triangulations(self, verbose=False): r""" - Returns all triangulations. + Return all triangulations. - - ``verbose`` -- boolean (default: ``False``). Whether to - print out the TOPCOM interaction, if any. + - ``verbose`` -- boolean (default: ``False``); whether to + print out the TOPCOM interaction, if any OUTPUT: @@ -1004,8 +1004,8 @@ def triangulations_list(self, verbose=False): INPUT: - - ``verbose`` -- boolean. Whether to print out the TOPCOM - interaction, if any. + - ``verbose`` -- boolean; whether to print out the TOPCOM + interaction, if any OUTPUT: @@ -1033,13 +1033,13 @@ def triangulate(self, verbose=False): INPUT: - - ``verbose`` -- boolean. Whether to print out the TOPCOM - interaction, if any. + - ``verbose`` -- boolean; whether to print out the TOPCOM + interaction, if any OUTPUT: A :class:`~sage.geometry.triangulation.element.Triangulation` - satisfying all restrictions imposed. This raises a :class:`ValueError` + satisfying all restrictions imposed. This raises a :exc:`ValueError` if no such triangulation exists. EXAMPLES:: @@ -1237,8 +1237,8 @@ def exclude_points(self, point_idx_list): INPUT: - - ``point_idx_list`` -- a list of integers. The indices of - points to exclude. + - ``point_idx_list`` -- list of integers; the indices of + points to exclude OUTPUT: @@ -1271,8 +1271,8 @@ def volume(self, simplex=None): INPUT: - - ``simplex`` (optional argument) -- a simplex from a - triangulation T specified as a list of point indices. + - ``simplex`` -- (optional argument) a simplex from a + triangulation T specified as a list of point indices OUTPUT: @@ -1297,7 +1297,7 @@ def volume(self, simplex=None): sage: p.volume() 2 - .. note:: + .. NOTE:: We return `n!` * (metric volume of the simplex) to ensure that the volume is an integer. Essentially, this normalizes @@ -1485,18 +1485,16 @@ def circuits(self): def positive_circuits(self, *negative): r""" - Returns the positive part of circuits with fixed negative part. + Return the positive part of circuits with fixed negative part. A circuit is a pair `(C_+, C_-)`, each consisting of a subset (actually, an ordered tuple) of point indices. INPUT: - - ``*negative`` -- integer. The indices of points. - - OUTPUT: + - ``*negative`` -- integer; the indices of points - A tuple of all circuits with `C_-` = ``negative``. + OUTPUT: a tuple of all circuits with `C_-` = ``negative`` EXAMPLES:: @@ -1656,7 +1654,7 @@ def make_cotriang(basepts): @cached_method def distance_affine(self, x, y): r""" - Returns the distance between two points. + Return the distance between two points. The distance function used in this method is `d_{aff}(x,y)^2`, the square of the usual affine distance function @@ -1667,7 +1665,7 @@ def distance_affine(self, x, y): INPUT: - - ``x``, ``y`` -- two points of the point configuration. + - ``x``, ``y`` -- two points of the point configuration OUTPUT: @@ -1691,7 +1689,7 @@ def distance_affine(self, x, y): @cached_method def distance_FS(self, x, y): r""" - Returns the distance between two points. + Return the distance between two points. The distance function used in this method is `1-\cos d_{FS}(x,y)^2`, where `d_{FS}` is the Fubini-Study distance of @@ -1703,7 +1701,7 @@ def distance_FS(self, x, y): INPUT: - - ``x``, ``y`` -- two points of the point configuration. + - ``x``, ``y`` -- two points of the point configuration OUTPUT: @@ -1728,11 +1726,11 @@ def distance_FS(self, x, y): @cached_method def distance(self, x, y): """ - Returns the distance between two points. + Return the distance between two points. INPUT: - - ``x``, ``y`` -- two points of the point configuration. + - ``x``, ``y`` -- two points of the point configuration OUTPUT: @@ -1764,9 +1762,9 @@ def farthest_point(self, points, among=None): INPUT: - - ``points`` -- a list of points. + - ``points`` -- list of points - - ``among`` -- a list of points or ``None`` (default). The set + - ``among`` -- list of points or ``None`` (default); the set of points from which to pick the farthest one. By default, all points of the configuration are considered. @@ -1804,17 +1802,17 @@ def contained_simplex(self, large=True, initial_point=None, point_order=None): INPUT: - - ``large`` -- boolean. Whether to attempt to return a large - simplex. + - ``large`` -- boolean; whether to attempt to return a large + simplex - ``initial_point`` -- a :class:`~sage.geometry.triangulation.base.Point` or ``None`` (default). A specific point to start with when picking the simplex vertices. - - ``point_order`` -- a list or tuple of (some or all) + - ``point_order`` -- list or tuple of (some or all) :class:`~sage.geometry.triangulation.base.Point` s or ``None`` - (default). + (default) OUTPUT: @@ -1911,9 +1909,7 @@ def placing_triangulation(self, point_order=None): will be placed in some arbitrary order that attempts to produce a small number of simplices. - OUTPUT: - - A :class:`~sage.geometry.triangulation.triangulation.Triangulation`. + OUTPUT: a :class:`~sage.geometry.triangulation.triangulation.Triangulation` EXAMPLES:: @@ -2049,13 +2045,11 @@ def Gale_transform(self, points=None): INPUT: - - ``points`` -- a tuple of points or point indices or ``None`` + - ``points`` -- tuple of points or point indices or ``None`` (default). A subset of points for which to compute the Gale transform. By default, all points are used. - OUTPUT: - - A matrix over :meth:`base_ring`. + OUTPUT: a matrix over :meth:`base_ring` EXAMPLES:: diff --git a/src/sage/geometry/voronoi_diagram.py b/src/sage/geometry/voronoi_diagram.py index a4c110ff647..1402e0b1e77 100644 --- a/src/sage/geometry/voronoi_diagram.py +++ b/src/sage/geometry/voronoi_diagram.py @@ -29,12 +29,10 @@ class VoronoiDiagram(SageObject): INPUT: - - ``points`` -- a list of points. Any valid input for the - :class:`PointConfiguration` will do. + - ``points`` -- list of points; any valid input for the + :class:`PointConfiguration` will do - OUTPUT: - - An instance of the VoronoiDiagram class. + OUTPUT: an instance of the VoronoiDiagram class EXAMPLES: @@ -251,11 +249,9 @@ def plot(self, cell_colors=None, **kwds): - ``cell_colors`` -- (default: ``None``) provide the colors for the cells, either as dictionary. Randomly colored cells are provided with ``None``. - ``**kwds`` -- optional keyword parameters, passed on as arguments for - plot(). - - OUTPUT: + plot() - A graphics object. + OUTPUT: a graphics object EXAMPLES:: diff --git a/src/sage/graphs/asteroidal_triples.pyx b/src/sage/graphs/asteroidal_triples.pyx index 19201431856..2056aa3d32c 100644 --- a/src/sage/graphs/asteroidal_triples.pyx +++ b/src/sage/graphs/asteroidal_triples.pyx @@ -70,7 +70,7 @@ from sage.graphs.base.static_sparse_graph cimport short_digraph, init_short_digr def is_asteroidal_triple_free(G, certificate=False): """ - Test if the input graph is asteroidal triple-free + Test if the input graph is asteroidal triple-free. An independent set of three vertices such that each pair is joined by a path that avoids the neighborhood of the third one is called an *asteroidal @@ -78,7 +78,7 @@ def is_asteroidal_triple_free(G, certificate=False): asteroidal triples. See the :mod:`module's documentation ` for more details. - This method returns ``True`` is the graph is AT-free and ``False`` otherwise. + This method returns ``True`` if the graph is AT-free and ``False`` otherwise. INPUT: diff --git a/src/sage/graphs/base/boost_graph.pyx b/src/sage/graphs/base/boost_graph.pyx index b38d8277037..31f3c6d0267 100644 --- a/src/sage/graphs/base/boost_graph.pyx +++ b/src/sage/graphs/base/boost_graph.pyx @@ -66,7 +66,7 @@ cdef boost_graph_from_sage_graph(BoostGenGraph *g, g_sage, vertex_to_int, revers - ``g_sage`` -- a Sage graph - - ``vertex_to_int`` -- a dictionary; it is a mapping from the vertex set of + - ``vertex_to_int`` -- dictionary; it is a mapping from the vertex set of ``g_sage`` to `(0, \ldots, n-1)` - ``reverse`` -- boolean (default: ``False``); when set to ``True``, the @@ -109,7 +109,7 @@ cdef boost_weighted_graph_from_sage_graph(BoostWeightedGraph *g, - ``g_sage`` -- a Sage graph - - ``vertex_to_int`` -- a dictionary; it is a mapping from the vertex set of + - ``vertex_to_int`` -- dictionary; it is a mapping from the vertex set of ``g_sage`` to `(0, \ldots, n-1)` - ``weight_function`` -- function (default: ``None``); a function which @@ -317,7 +317,7 @@ cpdef clustering_coeff(g, vertices=None): With labels:: sage: g.relabel(list("abcdefghiklm")) - sage: clustering_coeff(g, vertices="abde") + sage: clustering_coeff(g, vertices='abde') (0.5, {'a': 0.5, 'b': 0.5, 'd': 0.5, 'e': 0.5}) """ from sage.graphs.graph import Graph @@ -505,7 +505,7 @@ cpdef bandwidth_heuristics(g, algorithm='cuthill_mckee'): Use Boost heuristics to approximate the bandwidth of the input graph. The bandwidth `bw(M)` of a matrix `M` is the smallest integer `k` such that - all non-zero entries of `M` are at distance `k` from the diagonal. The + all nonzero entries of `M` are at distance `k` from the diagonal. The bandwidth `bw(g)` of an undirected graph `g` is the minimum bandwidth of the adjacency matrix of `g`, over all possible relabellings of its vertices (for more information, see the @@ -578,7 +578,6 @@ cpdef bandwidth_heuristics(g, algorithm='cuthill_mckee'): (0, []) sage: bandwidth_heuristics(graphs.RandomGNM(10,0)) # needs networkx (0, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) - """ from sage.graphs.graph import Graph @@ -1049,8 +1048,8 @@ cdef get_predecessors(BoostWeightedGraph g, result, int_to_v, directed, weight_t - ``result`` -- the matrix of shortest distances - - ``int_to_v`` -- a list; it is a mapping from `(0, \ldots, n-1)` - to the vertex set of the original sage graph. + - ``int_to_v`` -- list; it is a mapping from `(0, \ldots, n-1)` + to the vertex set of the original sage graph - ``directed`` -- boolean; whether the input graph is directed @@ -1426,9 +1425,7 @@ cpdef johnson_closeness_centrality(g, weight_function=None): ``g`` are used, if ``g.weighted()==True``, otherwise all edges have weight 1. - OUTPUT: - - A dictionary associating each vertex ``v`` to its closeness centrality. + OUTPUT: a dictionary associating each vertex ``v`` to its closeness centrality EXAMPLES: @@ -1648,7 +1645,7 @@ cpdef eccentricity_DHV(g, vertex_list=None, weight_function=None, check_weight=T INPUT: - - ``g`` -- the input Sage graph. + - ``g`` -- the input Sage graph - ``vertex_list`` -- list (default: ``None``); a list of `n` vertices specifying a mapping from `(0, \ldots, n-1)` to vertex labels in `g`. When @@ -1838,7 +1835,7 @@ cpdef radius_DHV(g, weight_function=None, check_weight=True): weight 1. - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check - that the ``weight_function`` outputs a number for each edge. + that the ``weight_function`` outputs a number for each edge EXAMPLES:: @@ -1869,7 +1866,6 @@ cpdef radius_DHV(g, weight_function=None, check_weight=True): Traceback (most recent call last): ... TypeError: this method works for undirected graphs only - """ if g.is_directed(): raise TypeError("this method works for undirected graphs only") @@ -2160,11 +2156,11 @@ cdef tuple diameter_lower_bound_2Dsweep(BoostVecWeightedDiGraphU g_boost, INPUT: - - ``g_boost`` -- a boost weighted digraph. + - ``g_boost`` -- a boost weighted digraph - - ``rev_g_boost`` -- a copy of ``g_boost`` with edges reversed. + - ``rev_g_boost`` -- a copy of ``g_boost`` with edges reversed - - ``source`` -- starting node for forward and backward distance computation. + - ``source`` -- starting node for forward and backward distance computation - ``algorithm`` -- string; algorithm for computing single source shortest distances. If ``g_boost`` contains negative edge weights then it will be @@ -2322,11 +2318,11 @@ cdef double diameter_DiFUB(BoostVecWeightedDiGraphU g_boost, INPUT: - - ``g_boost`` -- a boost weighted digraph. + - ``g_boost`` -- a boost weighted digraph - - ``rev_g_boost`` -- a copy of ``g_boost`` with edges reversed. + - ``rev_g_boost`` -- a copy of ``g_boost`` with edges reversed - - ``source`` -- starting node for forward and backward distance computation. + - ``source`` -- starting node for forward and backward distance computation - ``algorithm`` -- string; algorithm for computing single source shortest distances. If ``g_boost`` contains negative edge weights then it will be @@ -2500,16 +2496,16 @@ cpdef diameter(G, algorithm=None, source=None, INPUT: - - ``G`` -- the input sage digraph. + - ``G`` -- the input sage digraph - ``algorithm`` -- string (default: ``None``); specifies the algorithm to use among: - - ``'2Dsweep'`` -- Computes lower bound on the diameter of a weighted + - ``'2Dsweep'`` -- computes lower bound on the diameter of a weighted directed graph using the weighted version of the algorithm proposed in [Broder2000]_. See the code's documentation for more details. - - ``'DiFUB'`` -- Computes the diameter of a weighted directed graph + - ``'DiFUB'`` -- computes the diameter of a weighted directed graph using the weighted version of the algorithm proposed in [CGLM2012]_. See the code's documentation for more details. @@ -2523,7 +2519,7 @@ cpdef diameter(G, algorithm=None, source=None, weight 1. - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check - that the ``weight_function`` outputs a number for each edge. + that the ``weight_function`` outputs a number for each edge EXAMPLES:: @@ -2900,7 +2896,7 @@ cpdef wiener_index(g, algorithm=None, weight_function=None, check_weight=True): weight 1. - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check - that the ``weight_function`` outputs a number for each edge. + that the ``weight_function`` outputs a number for each edge EXAMPLES: @@ -2934,12 +2930,12 @@ cpdef wiener_index(g, algorithm=None, weight_function=None, check_weight=True): TESTS: - Using ``"Dijkstra"`` on a graph with negative weights:: + Using ``'Dijkstra'`` on a graph with negative weights:: sage: g = Graph([(0, 1, -1), (1, 2, 1)]) sage: def weight_of(e): ....: return e[2] - sage: wiener_index(g, algorithm="Dijkstra", weight_function=weight_of) + sage: wiener_index(g, algorithm='Dijkstra', weight_function=weight_of) Traceback (most recent call last): ... RuntimeError: Dijkstra algorithm does not work with negative weights, use Bellman-Ford instead @@ -2949,7 +2945,7 @@ cpdef wiener_index(g, algorithm=None, weight_function=None, check_weight=True): sage: g = DiGraph([(0, 1, -1), (1, 2, -1), (2, 0, -1)]) sage: def weight_of(e): ....: return e[2] - sage: wiener_index(g, algorithm="Bellman-Ford", weight_function=weight_of) + sage: wiener_index(g, algorithm='Bellman-Ford', weight_function=weight_of) Traceback (most recent call last): ... ValueError: the graph contains a negative cycle diff --git a/src/sage/graphs/base/c_graph.pyx b/src/sage/graphs/base/c_graph.pyx index 1f8e5a59c73..1aa7b32d691 100644 --- a/src/sage/graphs/base/c_graph.pyx +++ b/src/sage/graphs/base/c_graph.pyx @@ -69,20 +69,18 @@ cdef class CGraph: cpdef bint has_vertex(self, int n) except -1: """ - Determine whether the vertex ``n`` is in ``self``. + Determine whether the vertex `n` is in ``self``. This method is different from :meth:`check_vertex`. The current method - returns a boolean to signify whether or not ``n`` is a vertex of this + returns a boolean to signify whether or not `n` is a vertex of this graph. On the other hand, :meth:`check_vertex` raises an error if - ``n`` is not a vertex of this graph. + `n` is not a vertex of this graph. INPUT: - - ``n`` -- a nonnegative integer representing a vertex + - ``n`` -- nonnegative integer representing a vertex - OUTPUT: - - - ``True`` if ``n`` is a vertex of this graph; ``False`` otherwise. + OUTPUT: ``True`` if `n` is a vertex of this graph; ``False`` otherwise .. SEEALSO:: @@ -128,20 +126,18 @@ cdef class CGraph: cpdef check_vertex(self, int n): """ - Check that ``n`` is a vertex of ``self``. + Check that `n` is a vertex of ``self``. This method is different from :meth:`has_vertex`. The current method - raises an error if ``n`` is not a vertex of this graph. On the other + raises an error if `n` is not a vertex of this graph. On the other hand, :meth:`has_vertex` returns a boolean to signify whether or not - ``n`` is a vertex of this graph. + `n` is a vertex of this graph. INPUT: - - ``n`` -- a nonnegative integer representing a vertex - - OUTPUT: + - ``n`` -- nonnegative integer representing a vertex - - Raise an error if ``n`` is not a vertex of this graph + OUTPUT: raise an error if `n` is not a vertex of this graph .. SEEALSO:: @@ -189,7 +185,7 @@ cdef class CGraph: cdef int add_vertex_unsafe(self, int k) except -1: """ - Add the vertex ``k`` to the graph. + Add the vertex `k` to the graph. INPUT: @@ -204,7 +200,7 @@ cdef class CGraph: allocation is already full or the vertex is out of range - nonnegative integer -- this vertex is now guaranteed to be in the - graph. + graph .. WARNING:: @@ -223,7 +219,7 @@ cdef class CGraph: def add_vertex(self, int k=-1): """ - Adds vertex ``k`` to the graph. + Add vertex ``k`` to the graph. INPUT: @@ -235,15 +231,15 @@ cdef class CGraph: OUTPUT: - ``-1`` -- indicates that no vertex was added because the current - allocation is already full or the vertex is out of range. + allocation is already full or the vertex is out of range - nonnegative integer -- this vertex is now guaranteed to be in the - graph. + graph .. SEEALSO:: - ``add_vertex_unsafe`` -- add a vertex to a graph. This method is - potentially unsafe. You should instead use :meth:`add_vertex`. + potentially unsafe. You should instead use :meth:`add_vertex` - ``add_vertices`` -- add a bunch of vertices to a graph @@ -435,18 +431,18 @@ cdef class CGraph: cpdef del_vertex(self, int v): """ - Delete the vertex ``v``, along with all edges incident to it. + Delete the vertex `v`, along with all edges incident to it. - If ``v`` is not in ``self``, fails silently. + If `v` is not in ``self``, fails silently. INPUT: - - ``v`` -- a nonnegative integer representing a vertex + - ``v`` -- nonnegative integer representing a vertex .. SEEALSO:: - ``del_vertex_unsafe`` -- delete a vertex from a graph. This method - is potentially unsafe. Use :meth:`del_vertex` instead. + is potentially unsafe. Use :meth:`del_vertex` instead EXAMPLES: @@ -585,10 +581,6 @@ cdef class CGraph: """ Return a list of the vertices in ``self``. - OUTPUT: - - - A list of all vertices in this graph - EXAMPLES:: sage: from sage.graphs.base.sparse_graph import SparseGraph @@ -624,7 +616,7 @@ cdef class CGraph: OUTPUT: - - Raise a :class:`NotImplementedError`. This method is not implemented + - Raise a :exc:`NotImplementedError`. This method is not implemented in this base class. A child class should provide a suitable implementation. @@ -731,7 +723,7 @@ cdef class CGraph: INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self + - ``u``, ``v`` -- nonnegative integers; must be in self EXAMPLES: @@ -829,9 +821,9 @@ cdef class CGraph: INPUT: - - ``u`` -- integer; the tail of an arc. + - ``u`` -- integer; the tail of an arc - - ``v`` -- integer; the head of an arc. + - ``v`` -- integer; the head of an arc EXAMPLES: @@ -897,13 +889,13 @@ cdef class CGraph: INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self + - ``u``, ``v`` -- nonnegative integers; must be in self OUTPUT: one of - - positive integer -- indicates that there is a label on ``(u, v)``. + - positive integer -- indicates that there is a label on ``(u, v)`` - - ``0`` -- either the arc ``(u, v)`` is unlabeled, or there is no arc at all. + - ``0`` -- either the arc ``(u, v)`` is unlabeled, or there is no arc at all EXAMPLES:: @@ -927,7 +919,6 @@ cdef class CGraph: sage: G.add_arc_label(1,2,2) sage: G.arc_label(1,2) 2 - """ self.check_vertex(u) self.check_vertex(v) @@ -935,7 +926,7 @@ cdef class CGraph: cpdef list all_arcs(self, int u, int v): """ - Gives the labels of all arcs ``(u, v)``. An unlabeled arc is interpreted as + Give the labels of all arcs ``(u, v)``. An unlabeled arc is interpreted as having label 0. EXAMPLES:: @@ -951,7 +942,6 @@ cdef class CGraph: sage: G.add_arc_label(1,2,4) sage: G.all_arcs(1,2) [4, 3, 3, 2, 2, 2, 1] - """ cdef int size, num_arcs, i cdef int *arc_labels @@ -979,9 +969,9 @@ cdef class CGraph: INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self + - ``u``, ``v`` -- nonnegative integers; must be in self - - ``l`` -- a positive integer label, or zero for no label + - ``l`` -- positive integer label, or zero for no label EXAMPLES:: @@ -998,7 +988,6 @@ cdef class CGraph: sage: G.del_arc_label(0,1,0) sage: G.all_arcs(0,1) [3, 2, 1] - """ self.check_vertex(u) self.check_vertex(v) @@ -1012,9 +1001,9 @@ cdef class CGraph: INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self + - ``u``, ``v`` -- nonnegative integers; must be in self - - ``l`` -- a positive integer label, or zero for no label + - ``l`` -- positive integer label, or zero for no label EXAMPLES:: @@ -1030,7 +1019,6 @@ cdef class CGraph: True sage: G.has_arc_label(0,1,3) False - """ self.check_vertex(u) self.check_vertex(v) @@ -1054,7 +1042,7 @@ cdef class CGraph: INPUT: - - ``u`` -- non-negative integer; must be in self + - ``u`` -- nonnegative integer; must be in self - ``neighbors`` -- pointer to an (allocated) integer array @@ -1066,7 +1054,6 @@ cdef class CGraph: - ``-1`` -- indicates that the array has been filled with neighbors, but there were more - """ cdef int num_nbrs = 0 cdef int l @@ -1092,7 +1079,7 @@ cdef class CGraph: INPUT: - - ``v`` -- non-negative integer; must be in self + - ``v`` -- nonnegative integer; must be in self - ``neighbors`` -- pointer to an (allocated) integer array @@ -1104,7 +1091,6 @@ cdef class CGraph: - ``-1`` -- indicates that the array has been filled with neighbors, but there were more - """ cdef int num_nbrs = 0 cdef int l @@ -1155,10 +1141,9 @@ cdef class CGraph: .. SEEALSO:: - - :meth:`adjacency_sequence_in` -- Similar method for + - :meth:`adjacency_sequence_in` -- similar method for ``(vertices[i],v)`` instead of ``(v,vertices[i])`` (the difference only matters for digraphs) - """ cdef int i for i in range(n): @@ -1195,7 +1180,7 @@ cdef class CGraph: .. SEEALSO:: - - :meth:`adjacency_sequence_out` -- Similar method for ``(v, + - :meth:`adjacency_sequence_out` -- similar method for ``(v, vertices[i])`` instead of ``(vertices[i], v)`` (the difference only matters for digraphs) """ @@ -1267,7 +1252,7 @@ cdef class CGraph: OUTPUT: - - Raise :class:`NotImplementedError`. This method is not implemented at + - Raise :exc:`NotImplementedError`. This method is not implemented at the :class:`CGraph` level. A child class should provide a suitable implementation. @@ -1383,7 +1368,7 @@ cdef class CGraphBackend(GenericGraphBackend): def c_graph(self): r""" - Return the ``._cg`` and ``._cg_rev`` attributes + Return the ``._cg`` and ``._cg_rev`` attributes. .. NOTE:: @@ -1536,9 +1521,7 @@ cdef class CGraphBackend(GenericGraphBackend): """ Return the number of vertices in ``self``. - OUTPUT: - - - The order of this graph. + OUTPUT: the order of this graph .. SEEALSO:: @@ -1678,9 +1661,7 @@ cdef class CGraphBackend(GenericGraphBackend): - ``v`` -- any object - OUTPUT: - - - ``True`` if ``v`` is a vertex of this graph; ``False`` otherwise + OUTPUT: ``True`` if ``v`` is a vertex of this graph; ``False`` otherwise EXAMPLES:: @@ -1701,7 +1682,7 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - ``name`` -- the vertex to be added (must be hashable). If ``None``, - a new name is created. + a new name is created OUTPUT: @@ -1848,9 +1829,7 @@ cdef class CGraphBackend(GenericGraphBackend): - ``vertices`` -- iterator of vertex labels - OUTPUT: - - - Same as for :meth:`del_vertex`. + OUTPUT: same as for :meth:`del_vertex` .. SEEALSO:: @@ -1998,9 +1977,7 @@ cdef class CGraphBackend(GenericGraphBackend): - ``directed`` -- boolean; whether to take into account the orientation of this graph in counting the degree of ``v`` - OUTPUT: - - - The degree of vertex ``v`` + OUTPUT: the degree of vertex ``v`` EXAMPLES:: @@ -2131,11 +2108,11 @@ cdef class CGraphBackend(GenericGraphBackend): def out_degree(self, v): r""" - Return the out-degree of ``v`` + Return the out-degree of ``v``. INPUT: - - ``v`` -- a vertex of the graph. + - ``v`` -- a vertex of the graph EXAMPLES:: @@ -2158,7 +2135,7 @@ cdef class CGraphBackend(GenericGraphBackend): def in_degree(self, v): r""" - Return the in-degree of ``v`` + Return the in-degree of ``v``. INPUT: @@ -2186,9 +2163,7 @@ cdef class CGraphBackend(GenericGraphBackend): - ``v`` -- a vertex of this graph - OUTPUT: - - - An iterator over the neighbors the vertex ``v`` + OUTPUT: an iterator over the neighbors the vertex ``v`` .. SEEALSO:: @@ -2238,9 +2213,7 @@ cdef class CGraphBackend(GenericGraphBackend): - ``v`` -- a vertex of this graph - OUTPUT: - - - An iterator over the in-neighbors of the vertex ``v`` + OUTPUT: an iterator over the in-neighbors of the vertex ``v`` .. SEEALSO:: @@ -2281,9 +2254,7 @@ cdef class CGraphBackend(GenericGraphBackend): - ``v`` -- a vertex of this graph - OUTPUT: - - - An iterator over the out-neighbors of the vertex ``v`` + OUTPUT: an iterator over the out-neighbors of the vertex ``v`` .. SEEALSO:: @@ -2344,7 +2315,6 @@ cdef class CGraphBackend(GenericGraphBackend): (2, 3, None), (4, 5, None), (5, 6, None)] - """ cdef object u, v, l, e for e in edges: @@ -2359,15 +2329,15 @@ cdef class CGraphBackend(GenericGraphBackend): cpdef add_edge(self, object u, object v, object l, bint directed): """ - Add the edge ``(u,v)`` to self. + Add the edge ``(u,v)`` to ``self``. INPUT: - - ``u``, ``v`` -- the vertices of the edge + - ``u``, ``v`` -- the vertices of the edge - - ``l`` -- the edge label + - ``l`` -- the edge label - - ``directed`` -- if False, also add ``(v,u)`` + - ``directed`` -- if ``False``, also add ``(v,u)`` .. NOTE:: @@ -2478,7 +2448,6 @@ cdef class CGraphBackend(GenericGraphBackend): sage: D.del_edges([(0,1), (2,3), (4,5), (5,6)], False) sage: list(D.iterator_edges(range(9), True)) [] - """ cdef object u, v, l, e for e in edges: @@ -2609,7 +2578,7 @@ cdef class CGraphBackend(GenericGraphBackend): cdef list _all_edge_labels(self, int u, int v, uint32_t* edge=NULL): """ - Gives the labels of all arcs from ``u`` to ``v``. + Give the labels of all arcs from ``u`` to ``v``. ``u`` and ``v`` are the integers corresponding to vertices. @@ -2634,7 +2603,7 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean, whether to return labels as well @@ -2671,7 +2640,7 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean, whether to return labels as well @@ -2699,9 +2668,9 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - - ``labels`` -- boolean, whether to return labels as well + - ``labels`` -- boolean, whether to return labels as well EXAMPLES:: @@ -2722,7 +2691,7 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean, whether to return labels as well @@ -2745,7 +2714,7 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean, whether to return labels as well @@ -2960,9 +2929,9 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - ``other`` -- a (mutable) subclass of :class:`CGraphBackend` - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - .. NOTE: + .. NOTE:: ``other`` is assumed to be the empty graph. @@ -3164,10 +3133,10 @@ cdef class CGraphBackend(GenericGraphBackend): INPUT: - ``other`` -- a (mutable) subclass of :class:`CGraphBackend` - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``modus`` -- integer representing the modus: - ``0`` -- initialize ``other`` to be the subgraph induced by the vertices; - see :meth:`subgraph_given_vertices`` + see :meth:`subgraph_given_vertices` - ``1`` -- test whether subgraph of ``self`` induced by the vertices is a subgraph of ``other`` - ``2`` -- as ``1`` but ignore the labels """ @@ -3367,7 +3336,6 @@ cdef class CGraphBackend(GenericGraphBackend): [] sage: G._backend.shortest_path_special(1, 4, exclude_vertices=[2], exclude_edges=[(2, 3)]) [1, 5, 6, 7, 4] - """ cdef bint exclude_v = exclude_vertices cdef bint exclude_e = exclude_edges @@ -3544,7 +3512,6 @@ cdef class CGraphBackend(GenericGraphBackend): [0, 1] sage: G.shortest_path_length(0, 1) 1 - """ if x == y: if distance_flag: @@ -3702,7 +3669,7 @@ cdef class CGraphBackend(GenericGraphBackend): instead of the path. - ``reduced_weight`` -- dictionary (default: ``None``); a dictionary - that takes as input an edge ``(u, v)`` and outputs its reduced weight. + that takes as input an edge ``(u, v)`` and outputs its reduced weight OUTPUT: @@ -3723,7 +3690,6 @@ cdef class CGraphBackend(GenericGraphBackend): [1, 2, 3, 4] sage: G._backend.bidirectional_dijkstra_special(1, 4, weight_function=lambda e:e[2], include_vertices=[1, 5, 6, 4]) [1, 5, 6, 4] - """ cdef bint exclude_v = exclude_vertices cdef bint exclude_e = exclude_edges @@ -4705,7 +4671,7 @@ cdef class Search_iterator: search. The class does not build all at once in memory the whole list of visited vertices. The class maintains the following variables: - - ``graph`` -- a graph whose vertices are to be iterated over. + - ``graph`` -- a graph whose vertices are to be iterated over - ``direction`` -- integer; this determines the position at which vertices to be visited are removed from the list. For breadth-first search (BFS), @@ -4716,11 +4682,11 @@ cdef class Search_iterator: value ``direction=-1``. In this case, we use a stack to maintain the list of vertices to visit. - - ``stack`` -- a list of vertices to visit, used only when ``direction=-1`` + - ``stack`` -- list of vertices to visit, used only when ``direction=-1`` - ``queue`` -- a queue of vertices to visit, used only when ``direction=0`` - - ``seen`` -- a list of vertices that are already visited + - ``seen`` -- list of vertices that are already visited - ``test_out`` -- boolean; whether we want to consider the out-neighbors of the graph to be traversed. For undirected graphs, we consider both @@ -4764,7 +4730,7 @@ cdef class Search_iterator: - ``v`` -- a vertex in ``graph`` from which to start the traversal - - ``direction`` -- integer (default: ``0``); this determines the + - ``direction`` -- integer (default: `0`); this determines the position at which vertices to be visited are removed from the list. For breadth-first search (BFS), element removal follow a first-in first-out (FIFO) protocol, as signified by the value @@ -4822,7 +4788,6 @@ cdef class Search_iterator: sage: DiGraph([(1, 2)], immutable=True).connected_components(sort=True) [[1, 2]] - """ self.graph = graph self.direction = direction @@ -5025,7 +4990,7 @@ cdef inline bint _reorganize_edge(object v, object u, const int modus) noexcept: - ``2`` -- unsorted edges of an undirected graph - ``3`` -- sorted edges of an undirected graph - OUTPUT: Boolean according the modus: + OUTPUT: boolean according the modus: - ``modus == 0`` -- ``False`` - ``modus == 1`` -- ``True`` diff --git a/src/sage/graphs/base/dense_graph.pyx b/src/sage/graphs/base/dense_graph.pyx index abcd0809af1..45d09ced3d3 100644 --- a/src/sage/graphs/base/dense_graph.pyx +++ b/src/sage/graphs/base/dense_graph.pyx @@ -144,8 +144,8 @@ cdef class DenseGraph(CGraph): INPUT: - - ``nverts`` -- non-negative integer; the number of vertices - - ``extra_vertices`` -- non-negative integer (default: 10); how many extra + - ``nverts`` -- nonnegative integer; the number of vertices + - ``extra_vertices`` -- nonnegative integer (default: 10); how many extra vertices to allocate - ``verts`` -- list (default: ``None``); optional list of vertices to add - ``arcs`` -- list (default: ``None``); optional list of arcs to add @@ -155,7 +155,6 @@ cdef class DenseGraph(CGraph): ``extra_vertices`` can be freely added without reallocation. See top level documentation for more details. The input ``verts`` and ``arcs`` are mainly for use in pickling. - """ def __cinit__(self, int nverts, int extra_vertices=10, verts=None, arcs=None, directed=True): """ @@ -300,8 +299,7 @@ cdef class DenseGraph(CGraph): INPUT: - - ``u``, ``v`` -- non-negative integers - + - ``u``, ``v`` -- nonnegative integers """ if unlikely(l): raise ValueError("cannot add a labeled arc to an unlabeled graph") @@ -316,14 +314,14 @@ cdef class DenseGraph(CGraph): INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self + - ``u``, ``v`` -- nonnegative integers, must be in self - - ``l`` -- a positive integer label, or zero for no label, or ``-1`` for any label + - ``l`` -- positive integer label, or zero for no label, or ``-1`` for any label OUTPUT: - 0 -- False - 1 -- True + - 0 -- False + - 1 -- True """ if unlikely(l > 0): raise ValueError("cannot locate labeled arc in unlabeled graph") @@ -349,8 +347,7 @@ cdef class DenseGraph(CGraph): INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self - + - ``u``, ``v`` -- nonnegative integers, must be in self """ self._del_arc_unsafe(u, v) if u != v and not self._directed: @@ -366,7 +363,7 @@ cdef class DenseGraph(CGraph): cdef int all_arcs_unsafe(self, int u, int v, int* labels, int size) except -1: """ - Gives the labels of all arcs (u, v). + Give the labels of all arcs (u, v). INPUT: @@ -375,12 +372,9 @@ cdef class DenseGraph(CGraph): - ``labels`` -- must be a pointer to an (allocated) integer array - ``size`` -- the length of the array - OUTPUT: - - - integer -- the number of arcs ``(u, v)`` - ``-1`` -- indicates that the array has been filled with labels, but - there were more - + OUTPUT: integer; the number of arcs ``(u, v)``. + ``-1`` -- indicates that the array has been filled with labels, but + there were more. """ if self.has_arc_unsafe(u, v): if size > 0: @@ -392,7 +386,7 @@ cdef class DenseGraph(CGraph): def complement(self): r""" - Replace the graph with its complement + Replace the graph with its complement. .. NOTE:: @@ -571,7 +565,6 @@ cdef class DenseGraphBackend(CGraphBackend): Traceback (most recent call last): ... TypeError: an integer is required - """ def __init__(self, n, directed=True): @@ -584,7 +577,6 @@ cdef class DenseGraphBackend(CGraphBackend): sage: D.add_edge(0, 1, None, False) sage: list(D.iterator_edges(range(9), True)) [(0, 1, None)] - """ self._cg = DenseGraph(n, directed=directed) self._directed = directed @@ -622,7 +614,7 @@ cdef class DenseGraphBackend(CGraphBackend): INPUT: - ``edges`` -- an iterable of edges to be added; each edge can either be - of the form ``(u, v)`` or ``(u, v, l)`` + of the form ``(u, v)`` or ``(u, v, l)`` - ``directed`` -- if ``False``, adds ``(v, u)`` as well as ``(u, v)`` @@ -637,7 +629,6 @@ cdef class DenseGraphBackend(CGraphBackend): (2, 3, None), (4, 5, None), (5, 6, None)] - """ for e in edges: u, v = e[:2] @@ -678,7 +669,6 @@ cdef class DenseGraphBackend(CGraphBackend): Traceback (most recent call last): ... LookupError: (2, 4) is not an edge of the graph - """ if not self.has_edge(u, v, None): raise LookupError("({0}, {1}) is not an edge of the graph".format(repr(u), repr(v))) @@ -704,7 +694,6 @@ cdef class DenseGraphBackend(CGraphBackend): sage: D.add_edges([(0, 1), (2, 3), (4, 5), (5, 6)], False) sage: D.has_edge(0, 1, None) True - """ cdef int u_int = self.get_vertex_checked(u) cdef int v_int = self.get_vertex_checked(v) @@ -737,7 +726,6 @@ cdef class DenseGraphBackend(CGraphBackend): NotImplementedError: dense graphs do not support multiple edges sage: G.multiple_edges(None) False - """ if new is None: return False diff --git a/src/sage/graphs/base/graph_backends.pyx b/src/sage/graphs/base/graph_backends.pyx index a779c3f4f22..4363a812995 100644 --- a/src/sage/graphs/base/graph_backends.pyx +++ b/src/sage/graphs/base/graph_backends.pyx @@ -5,7 +5,7 @@ This module implements :class:`GenericGraphBackend` (the base class for backends). Any graph backend must redefine the following methods (for which -:class:`GenericGraphBackend` raises a :class:`NotImplementedError`) +:class:`GenericGraphBackend` raises a :exc:`NotImplementedError`) .. csv-table:: :class: contentstable @@ -69,7 +69,6 @@ cdef class GenericGraphBackend(SageObject): TESTS:: sage: import sage.graphs.base.graph_backends - """ _loops = False _multiple_edges = False @@ -128,9 +127,7 @@ cdef class GenericGraphBackend(SageObject): - ``name`` -- vertex label - OUTPUT: - - If ``name=None``, the new vertex name is returned, ``None`` otherwise. + OUTPUT: if ``name=None``, the new vertex name is returned, ``None`` otherwise TESTS:: @@ -176,9 +173,7 @@ cdef class GenericGraphBackend(SageObject): - ``v`` -- a vertex label - ``directed`` -- boolean - OUTPUT: - - degree of `v` + OUTPUT: degree of `v` TESTS:: @@ -192,7 +187,7 @@ cdef class GenericGraphBackend(SageObject): def in_degree(self, v): r""" - Return the in-degree of `v` + Return the in-degree of `v`. INPUT: @@ -210,7 +205,7 @@ cdef class GenericGraphBackend(SageObject): def out_degree(self, v): r""" - Return the out-degree of `v` + Return the out-degree of `v`. INPUT: @@ -313,9 +308,7 @@ cdef class GenericGraphBackend(SageObject): - ``u``, ``v`` -- vertex labels - ``l`` -- label - OUTPUT: - - boolean + OUTPUT: boolean TESTS:: @@ -335,8 +328,7 @@ cdef class GenericGraphBackend(SageObject): - ``v`` -- vertex label - OUTPUT: - boolean + OUTPUT: boolean TESTS:: @@ -359,7 +351,7 @@ cdef class GenericGraphBackend(SageObject): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean OUTPUT: @@ -386,12 +378,11 @@ cdef class GenericGraphBackend(SageObject): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean - OUTPUT: - a generator which yields edges, with or without labels - depending on the labels parameter. + OUTPUT: a generator which yields edges, with or without labels + depending on the labels parameter TESTS:: @@ -412,7 +403,7 @@ cdef class GenericGraphBackend(SageObject): INPUT: - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``labels`` -- boolean OUTPUT: @@ -442,9 +433,7 @@ cdef class GenericGraphBackend(SageObject): - ``v`` -- vertex label - OUTPUT: - - a generator which yields vertex labels + OUTPUT: a generator which yields vertex labels TESTS:: @@ -467,9 +456,7 @@ cdef class GenericGraphBackend(SageObject): - ``v`` -- vertex label - OUTPUT: - - a generator which yields vertex labels + OUTPUT: a generator which yields vertex labels TESTS:: @@ -492,9 +479,7 @@ cdef class GenericGraphBackend(SageObject): - ``v`` -- vertex label - OUTPUT: - - a generator which yields vertex labels + OUTPUT: a generator which yields vertex labels TESTS:: @@ -514,9 +499,7 @@ cdef class GenericGraphBackend(SageObject): - ``verts`` -- vertex labels - OUTPUT: - - a generator which yields vertices + OUTPUT: a generator which yields vertices TESTS:: @@ -530,7 +513,7 @@ cdef class GenericGraphBackend(SageObject): def loops(self, new=None): """ - Get/set whether or not self allows loops. + Get/set whether or not ``self`` allows loops. INPUT: @@ -554,7 +537,7 @@ cdef class GenericGraphBackend(SageObject): def multiple_edges(self, new=None): """ - Get/set whether or not self allows multiple edges. + Get/set whether or not ``self`` allows multiple edges. INPUT: @@ -578,7 +561,7 @@ cdef class GenericGraphBackend(SageObject): def name(self, new=None): """ - Get/set name of self. + Get/set name of ``self``. INPUT: @@ -602,7 +585,7 @@ cdef class GenericGraphBackend(SageObject): def num_edges(self, directed): """ - Return the number of edges in ``self`` + Return the number of edges in ``self``. INPUT: @@ -624,7 +607,7 @@ cdef class GenericGraphBackend(SageObject): def num_verts(self): """ - Return the number of vertices in ``self`` + Return the number of vertices in ``self``. TESTS:: @@ -757,7 +740,7 @@ cdef class GenericGraphBackend(SageObject): def unpickle_graph_backend(directed, vertices, edges, kwds): r""" - Return a backend from its pickled data + Return a backend from its pickled data. This methods is defined because Python's pickling mechanism can only build objects from a pair ``(f,args)`` by running ``f(*args)``. In particular, diff --git a/src/sage/graphs/base/sparse_graph.pyx b/src/sage/graphs/base/sparse_graph.pyx index 3e736bc6461..a02541436ac 100644 --- a/src/sage/graphs/base/sparse_graph.pyx +++ b/src/sage/graphs/base/sparse_graph.pyx @@ -235,23 +235,22 @@ cdef class SparseGraph(CGraph): INPUT: - - ``nverts`` -- non-negative integer, the number of vertices. + - ``nverts`` -- nonnegative integer, the number of vertices - - ``expected_degree`` -- non-negative integer (default: 16), expected upper - bound on degree of vertices. + - ``expected_degree`` -- nonnegative integer (default: 16); expected upper + bound on degree of vertices - - ``extra_vertices`` -- non-negative integer (default: 0), how many extra - vertices to allocate. + - ``extra_vertices`` -- nonnegative integer (default: 0); how many extra + vertices to allocate - - ``verts`` -- optional list of vertices to add + - ``verts`` -- (optional) list of vertices to add - - ``arcs`` -- optional list of arcs to add + - ``arcs`` -- (optional) list of arcs to add The first ``nverts`` are created as vertices of the graph, and the next ``extra_vertices`` can be freely added without reallocation. See top level documentation for more details. The input ``verts`` and ``arcs`` are mainly for use in pickling. - """ def __cinit__(self, int nverts, int expected_degree=16, int extra_vertices=10, @@ -379,7 +378,7 @@ cdef class SparseGraph(CGraph): INPUT: - - ``total`` -- integer, the total size to make the array + - ``total`` -- integer; the total size to make the array Returns -1 and fails if reallocation would destroy any active vertices. @@ -414,7 +413,6 @@ cdef class SparseGraph(CGraph): sage: S.realloc(30) sage: S.current_allocation() 30 - """ if not total: raise RuntimeError('Sparse graphs must allocate space for vertices!') @@ -582,16 +580,16 @@ cdef class SparseGraph(CGraph): cdef int del_arc_unsafe(self, int u, int v) except -1: """ - Deletes *all* arcs from u to v. + Delete *all* arcs from u to v. INPUT: - - ``u``, ``v`` -- non-negative integers + - ``u``, ``v`` -- nonnegative integers OUTPUT: - 0 -- No error. - 1 -- No arc to delete. + - 0 -- no error + - 1 -- no arc to delete """ cdef int n_arcs = self._del_arc_unsafe(u, v, self.vertices) if u != v or self.is_directed(): @@ -722,11 +720,11 @@ cdef class SparseGraph(CGraph): cpdef int out_degree(self, int u) noexcept: """ - Returns the out-degree of ``v`` + Return the out-degree of ``v`` INPUT: - - ``u`` -- integer + - ``u`` -- integer EXAMPLES:: @@ -792,11 +790,11 @@ cdef class SparseGraph(CGraph): cpdef int in_degree(self, int v) noexcept: """ - Returns the in-degree of ``v`` + Return the in-degree of ``v`` INPUT: - - ``v`` -- integer + - ``v`` -- integer EXAMPLES:: @@ -864,12 +862,11 @@ cdef class SparseGraph(CGraph): INPUT: - - ``u``, ``v`` -- non-negative integers + - ``u``, ``v`` -- nonnegative integers - - ``l`` -- a positive integer label, or zero for no label - - OUTPUT: ``0`` -- No error. + - ``l`` -- positive integer label, or zero for no label + OUTPUT: ``0`` -- no error """ self._add_arc_label_unsafe(u, v, l, self.vertices) if u != v or self.is_directed(): @@ -891,9 +888,9 @@ cdef class SparseGraph(CGraph): INPUT: - - ``u``, ``v`` -- non-negative integers, must be in self + - ``u``, ``v`` -- nonnegative integers, must be in ``self`` - - ``l`` -- a positive integer label, or zero for no label + - ``l`` -- positive integer label, or zero for no label EXAMPLES:: @@ -930,10 +927,9 @@ cdef class SparseGraph(CGraph): OUTPUT: one of - - positive integer -- indicates that there is a label on ``(u, v)``. + - positive integer -- indicates that there is a label on ``(u, v)`` - ``0`` -- either the arc ``(u, v)`` is unlabeled, or there is no arc at all. - """ cdef int i = (u * self.hash_length) + (v & self.hash_mask) cdef int compared @@ -952,7 +948,7 @@ cdef class SparseGraph(CGraph): cdef int all_arcs_unsafe(self, int u, int v, int *arc_labels, int size) except -1: """ - Gives the labels of all arcs (u, v). + Give the labels of all arcs (u, v). INPUT: @@ -961,12 +957,9 @@ cdef class SparseGraph(CGraph): - ``arc_labels`` -- must be a pointer to an (allocated) integer array - ``size`` -- the length of the array - OUTPUT: - - - integer -- the number of arcs ``(u, v)`` - ``-1`` -- indicates that the array has been filled with labels, but - there were more - + OUTPUT: integer; the number of arcs ``(u, v)``. + ``-1`` -- indicates that the array has been filled with labels, but + there were more. """ cdef int i = (u * self.hash_length) + (v & self.hash_mask), j cdef int compared, num_arcs @@ -1035,8 +1028,9 @@ cdef class SparseGraph(CGraph): Delete an arc (u, v) with label l. OUTPUT: - 0 -- No error. - 1 -- No arc with label l. + + - 0 -- no error + - 1 -- no arc with label l """ cdef int i = (u * self.hash_length) + (v & self.hash_mask) cdef SparseGraphBTNode **old_parent = parent @@ -1090,13 +1084,13 @@ cdef class SparseGraph(CGraph): - ``u``, ``v`` -- integers from `0`, ..., `n-1`, where `n` is the number of vertices - - ``l`` -- a positive integer label, or zero for no label + - ``l`` -- positive integer label, or zero for no label OUTPUT: one of - - ``0`` -- No error + - ``0`` -- no error - - ``1`` -- No arc with label ``l`` + - ``1`` -- no arc with label ``l`` """ if self._del_arc_label_unsafe(u, v, l, self.vertices): return 1 # indicate an error @@ -1123,13 +1117,13 @@ cdef class SparseGraph(CGraph): - ``u``, ``v`` -- integers from `0`, ..., `n-1`, where `n` is the number of vertices - - ``l`` -- a positive integer label, or zero for no label, or ``-1`` for any label + - ``l`` -- positive integer label, or zero for no label, or ``-1`` for any label OUTPUT: one of - - ``0`` -- False + - ``0`` -- false - - ``1`` -- True + - ``1`` -- true """ cdef int i = (u * self.hash_length) + (v & self.hash_mask) cdef int compared @@ -1249,7 +1243,6 @@ cdef class SparseGraphBackend(CGraphBackend): Traceback (most recent call last): ... TypeError: an integer is required - """ def __init__(self, int n, directed=True): @@ -1262,7 +1255,6 @@ cdef class SparseGraphBackend(CGraphBackend): sage: D.add_edge(0,1,None,False) sage: list(D.iterator_edges(range(9), True)) [(0, 1, None)] - """ self._cg = SparseGraph(n, directed=directed) self._directed = directed @@ -1305,7 +1297,7 @@ cdef class SparseGraphBackend(CGraphBackend): INPUT: - - ``u``, ``v`` -- the vertices of the edge + - ``u``, ``v`` -- the vertices of the edge EXAMPLES:: @@ -1333,15 +1325,15 @@ cdef class SparseGraphBackend(CGraphBackend): def has_edge(self, object u, object v, object l): """ - Returns whether this graph has edge ``(u,v)`` with label ``l``. If ``l`` + Return whether this graph has edge ``(u,v)`` with label ``l``. If ``l`` is ``None``, return whether this graph has an edge ``(u,v)`` with any label. INPUT: - - ``u``, ``v`` -- the vertices of the edge + - ``u``, ``v`` -- the vertices of the edge - - ``l`` -- the edge label, or ``None`` + - ``l`` -- the edge label, or ``None`` EXAMPLES:: @@ -1349,7 +1341,6 @@ cdef class SparseGraphBackend(CGraphBackend): sage: D.add_edges([(0,1), (2,3), (4,5), (5,6)], False) sage: D.has_edge(0,1,None) True - """ cdef int u_int = self.get_vertex_checked(u) cdef int v_int = self.get_vertex_checked(v) @@ -1378,7 +1369,7 @@ cdef class SparseGraphBackend(CGraphBackend): INPUT: - - ``new`` -- boolean (to set) or ``None`` (to get) + - ``new`` -- boolean (to set) or ``None`` (to get) EXAMPLES:: @@ -1393,7 +1384,6 @@ cdef class SparseGraphBackend(CGraphBackend): sage: G.add_edge(0,1,0,True) sage: list(G.iterator_out_edges(range(9), True)) [(0, 1, 0)] - """ if new is None: return self._multiple_edges @@ -1405,11 +1395,11 @@ cdef class SparseGraphBackend(CGraphBackend): INPUT: - - ``u``, ``v`` -- the vertices of the edge + - ``u``, ``v`` -- the vertices of the edge - - ``l`` -- the edge label + - ``l`` -- the edge label - - ``directed`` -- if ``False``, also set ``(v,u)`` with label ``l`` + - ``directed`` -- if ``False``, also set ``(v,u)`` with label ``l`` EXAMPLES:: @@ -1424,7 +1414,6 @@ cdef class SparseGraphBackend(CGraphBackend): sage: G.set_edge_label(2,1,'b',True) sage: list(G.iterator_out_edges(range(9), True)) [(1, 2, 'a')] - """ if not self.has_edge(u, v, None): return diff --git a/src/sage/graphs/base/static_dense_graph.pyx b/src/sage/graphs/base/static_dense_graph.pyx index fcd71c0143f..6a07565ecca 100644 --- a/src/sage/graphs/base/static_dense_graph.pyx +++ b/src/sage/graphs/base/static_dense_graph.pyx @@ -64,7 +64,7 @@ cdef dict dense_graph_init(binary_matrix_t m, g, translation=None, force_undirec - ``g`` -- a graph or digraph - - ``translation`` -- (default: `None``); several options for this parameter + - ``translation`` -- (default: ``None``) several options for this parameter used to specify the mapping from vertices to integers: - ``True``, ``False``, ``None`` -- the `i`-th vertex in the binary matrix @@ -393,7 +393,7 @@ def _format_result(G, edges, edges_only, labels): - ``edges_only`` -- boolean; whether to return DiGraph or list of vertices - - ``labels`` -- boolean; whether to return labelled edges or not. This + - ``labels`` -- boolean; whether to return labeled edges or not. This parameter is used only when ``edges_only`` is ``True``. EXAMPLES: @@ -426,7 +426,7 @@ def _yield_results_for_digraph(G, edges, edges_only, labels, min_edges, max_edge - ``edges_only`` -- boolean; whether to return DiGraph or list of vertices - - ``labels`` -- boolean; whether to return labelled edges or not. This + - ``labels`` -- boolean; whether to return labeled edges or not. This parameter is used only when ``edges_only`` is ``True``. - ``min_edges`` -- integer; minimum number of edges of reported subgraphs @@ -490,7 +490,7 @@ def connected_full_subgraphs(G, edges_only=False, labels=False, - ``edges_only`` -- boolean (default: ``False``); whether to return (Di)Graph or list of vertices - - ``labels`` -- boolean (default: ``False``); whether to return labelled + - ``labels`` -- boolean (default: ``False``); whether to return labeled edges or not. This parameter is used only when ``edges_only`` is ``True``. - ``min_edges`` -- integer (default: ``None``); minimum number of edges of @@ -776,7 +776,7 @@ def connected_subgraph_iterator(G, k=None, bint vertices_only=False, return (Di)Graph or list of edges. When ``vertices_only`` is ``True``, this parameter is ignored. - - ``labels`` -- boolean (default: ``False``); whether to return labelled + - ``labels`` -- boolean (default: ``False``); whether to return labeled edges or not. This parameter is used only when ``vertices_only`` is ``False`` and ``edges_only`` is ``True``. diff --git a/src/sage/graphs/base/static_sparse_backend.pyx b/src/sage/graphs/base/static_sparse_backend.pyx index ea65e2117d9..9e4983ab718 100644 --- a/src/sage/graphs/base/static_sparse_backend.pyx +++ b/src/sage/graphs/base/static_sparse_backend.pyx @@ -60,13 +60,13 @@ cdef class StaticSparseCGraph(CGraph): def __cinit__(self, G, vertex_list=None): r""" - Cython constructor + Cython constructor. INPUT: - ``G`` -- a :class:`Graph` object - - ``vertex_list`` -- optional list of all vertices of ``G`` + - ``vertex_list`` -- (optional) list of all vertices of ``G`` The optional argument ``vertex_list`` is assumed to be a list of all vertices of the graph ``G`` in some order. @@ -143,7 +143,7 @@ cdef class StaticSparseCGraph(CGraph): def __dealloc__(self): r""" - Freeing the memory + Free the memory. TESTS:: @@ -162,7 +162,7 @@ cdef class StaticSparseCGraph(CGraph): INPUT: - - ``n`` -- an integer + - ``n`` -- integer TESTS:: @@ -213,7 +213,7 @@ cdef class StaticSparseCGraph(CGraph): cpdef list verts(self): r""" - Returns the list of vertices + Return the list of vertices. TESTS:: @@ -320,7 +320,7 @@ cdef class StaticSparseCGraph(CGraph): cpdef list out_neighbors(self, int u): r""" - List the out-neighbors of a vertex + List the out-neighbors of a vertex. INPUT: @@ -345,7 +345,7 @@ cdef class StaticSparseCGraph(CGraph): cpdef list in_neighbors(self, int u): r""" - Return the in-neighbors of a vertex + Return the in-neighbors of a vertex. INPUT: @@ -447,8 +447,8 @@ cdef class StaticSparseBackend(CGraphBackend): :: sage: # needs sage.combinat - sage: g = DiGraph(digraphs.DeBruijn(4, 3), data_structure="static_sparse") - sage: gi = DiGraph(g, data_structure="static_sparse") + sage: g = DiGraph(digraphs.DeBruijn(4, 3), data_structure='static_sparse') + sage: gi = DiGraph(g, data_structure='static_sparse') sage: gi.edges(sort=True)[0] ('000', '000', '0') sage: sorted(gi.edges_incident('111')) @@ -463,7 +463,7 @@ cdef class StaticSparseBackend(CGraphBackend): :: sage: g = graphs.PetersenGraph() - sage: gi = Graph(g, data_structure="static_sparse") + sage: gi = Graph(g, data_structure='static_sparse') sage: g == gi True sage: set(g.edges(sort=False)) == set(gi.edges(sort=False)) @@ -471,7 +471,7 @@ cdef class StaticSparseBackend(CGraphBackend): :: - sage: gi = Graph({ 0: {1: 1}, 1: {2: 1}, 2: {3: 1}, 3: {4: 2}, 4: {0: 2}}, data_structure="static_sparse") + sage: gi = Graph({ 0: {1: 1}, 1: {2: 1}, 2: {3: 1}, 3: {4: 2}, 4: {0: 2}}, data_structure='static_sparse') sage: (0, 4, 2) in gi.edges(sort=False) True sage: gi.has_edge(0, 4) @@ -480,7 +480,7 @@ cdef class StaticSparseBackend(CGraphBackend): :: sage: G = Graph({1:{2:28, 6:10}, 2:{3:16, 7:14}, 3:{4:12}, 4:{5:22, 7:18}, 5:{6:25, 7:24}}) - sage: GI = Graph({1:{2:28, 6:10}, 2:{3:16, 7:14}, 3:{4:12}, 4:{5:22, 7:18}, 5:{6:25, 7:24}}, data_structure="static_sparse") + sage: GI = Graph({1:{2:28, 6:10}, 2:{3:16, 7:14}, 3:{4:12}, 4:{5:22, 7:18}, 5:{6:25, 7:24}}, data_structure='static_sparse') sage: G == GI True @@ -489,13 +489,13 @@ cdef class StaticSparseBackend(CGraphBackend): sage: G = graphs.OddGraph(4) sage: d = G.diameter() sage: H = G.distance_graph(list(range(d + 1))) - sage: HI = Graph(H, data_structure="static_sparse") + sage: HI = Graph(H, data_structure='static_sparse') sage: HI.size() == len(HI.edges(sort=False)) True :: - sage: g = Graph({1: {1: [1, 2, 3]}}, data_structure="static_sparse") + sage: g = Graph({1: {1: [1, 2, 3]}}, data_structure='static_sparse') sage: g.size() 3 sage: g.order() @@ -539,7 +539,7 @@ cdef class StaticSparseBackend(CGraphBackend): def has_vertex(self, v): r""" - Test if the vertex belongs to the graph + Test if the vertex belongs to the graph. INPUT: @@ -700,7 +700,7 @@ cdef class StaticSparseBackend(CGraphBackend): cdef inline list _all_edge_labels(self, int u, int v, uint32_t* edge=NULL): """ - Gives the labels of all arcs from ``u`` to ``v``. + Give the labels of all arcs from ``u`` to ``v``. ``u`` and ``v`` are the integers corresponding to vertices. @@ -781,7 +781,7 @@ cdef class StaticSparseBackend(CGraphBackend): INPUT: - - ``vertices`` -- a list of vertices + - ``vertices`` -- list of vertices - ``labels`` -- whether to return labels too @@ -829,7 +829,7 @@ cdef class StaticSparseBackend(CGraphBackend): INPUT: - - ``vertices`` -- a list of vertices + - ``vertices`` -- list of vertices - ``labels`` -- whether to return labels too @@ -841,7 +841,6 @@ cdef class StaticSparseBackend(CGraphBackend): [(0, 1), (0, 4), (0, 5)] sage: list(g.iterator_out_edges([0], True)) [(0, 1, None), (0, 4, None), (0, 5, None)] - """ try: vertices = [self._vertex_to_int[x] for x in vertices] @@ -862,11 +861,11 @@ cdef class StaticSparseBackend(CGraphBackend): def iterator_verts(self, vertices): r""" - Iterate over the vertices + Iterate over the vertices. INPUT: - - ``vertices`` -- a list of objects; the method will only return the + - ``vertices`` -- list of objects; the method will only return the elements of the graph which are contained in ``vertices``. It's not very efficient. If ``vertices`` is equal to ``None``, all the vertices are returned. @@ -893,7 +892,7 @@ cdef class StaticSparseBackend(CGraphBackend): def num_verts(self): r""" - Return the number of vertices + Return the number of vertices. TESTS:: @@ -906,7 +905,7 @@ cdef class StaticSparseBackend(CGraphBackend): def allows_loops(self, value=None): r""" - Return whether the graph allows loops + Return whether the graph allows loops. INPUT: @@ -931,7 +930,7 @@ cdef class StaticSparseBackend(CGraphBackend): def multiple_edges(self, value=None): r""" - Return whether the graph allows multiple edges + Return whether the graph allows multiple edges. INPUT: @@ -956,12 +955,12 @@ cdef class StaticSparseBackend(CGraphBackend): def num_edges(self, directed): r""" - Return the number of edges + Return the number of edges. INPUT: - ``directed`` -- boolean; whether to consider the graph as directed or - not. + not TESTS:: @@ -981,7 +980,7 @@ cdef class StaticSparseBackend(CGraphBackend): :issue:`15491`:: sage: g = digraphs.RandomDirectedGNP(10, .3) - sage: gi = DiGraph(g, data_structure="static_sparse") + sage: gi = DiGraph(g, data_structure='static_sparse') sage: gi.size() == len(gi.edges(sort=False)) True """ @@ -1069,10 +1068,10 @@ cdef class StaticSparseBackend(CGraphBackend): INPUT: - ``other`` -- a (mutable) subclass of :class:`CGraphBackend` - - ``vertices`` -- a list of vertex labels + - ``vertices`` -- list of vertex labels - ``modus`` -- integer representing the modus: - ``0`` -- initialize ``other`` to be the subgraph induced by the vertices; - see :meth:`subgraph_given_vertices`` + see :meth:`subgraph_given_vertices` - ``1`` -- test whether subgraph of ``self`` induced by the vertices is a subgraph of ``other`` - ``2`` -- as ``1`` but ignore the labels """ @@ -1200,7 +1199,7 @@ cdef class StaticSparseBackend(CGraphBackend): def degree(self, v, directed): r""" - Return the degree of a vertex + Return the degree of a vertex. INPUT: @@ -1211,7 +1210,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = Graph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = Graph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.degree(0) 3 @@ -1245,7 +1244,7 @@ cdef class StaticSparseBackend(CGraphBackend): def in_degree(self, v): r""" - Return the in-degree of a vertex + Return the in-degree of a vertex. INPUT: @@ -1253,7 +1252,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = DiGraph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = DiGraph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.in_degree(0) 3 """ @@ -1271,7 +1270,7 @@ cdef class StaticSparseBackend(CGraphBackend): def out_degree(self, v): r""" - Return the out-degree of a vertex + Return the out-degree of a vertex. INPUT: @@ -1279,7 +1278,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = DiGraph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = DiGraph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.out_degree(0) 3 """ @@ -1294,7 +1293,7 @@ cdef class StaticSparseBackend(CGraphBackend): def iterator_nbrs(self, v): r""" - Iterate over the neighbors of a vertex + Iterate over the neighbors of a vertex. INPUT: @@ -1302,7 +1301,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = Graph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = Graph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.neighbors(0) [1, 4, 5] @@ -1351,7 +1350,7 @@ cdef class StaticSparseBackend(CGraphBackend): def iterator_out_nbrs(self, v): r""" - Iterate over the out-neighbors of a vertex + Iterate over the out-neighbors of a vertex. INPUT: @@ -1359,7 +1358,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = DiGraph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = DiGraph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.neighbors_out(0) [1, 4, 5] """ @@ -1380,7 +1379,7 @@ cdef class StaticSparseBackend(CGraphBackend): def iterator_in_nbrs(self, v): r""" - Iterate over the in-neighbors of a vertex + Iterate over the in-neighbors of a vertex. INPUT: @@ -1388,7 +1387,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = DiGraph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = DiGraph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.neighbors_in(0) [1, 4, 5] @@ -1426,7 +1425,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = DiGraph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = DiGraph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.add_vertex(1) Traceback (most recent call last): ... @@ -1444,7 +1443,7 @@ cdef class StaticSparseBackend(CGraphBackend): EXAMPLES:: - sage: g = DiGraph(graphs.PetersenGraph(), data_structure="static_sparse") + sage: g = DiGraph(graphs.PetersenGraph(), data_structure='static_sparse') sage: g.delete_vertex(1) Traceback (most recent call last): ... @@ -1484,7 +1483,7 @@ def _run_it_on_static_instead(f): """ def same_function_on_static_version(*kwd, **kwds): if not isinstance(kwd[0]._backend, StaticSparseBackend): - gcopy = kwd[0].copy(data_structure="static_sparse") + gcopy = kwd[0].copy(data_structure='static_sparse') return getattr(gcopy, f.__name__)(*kwd[1:], **kwds) else: return f(*kwd, **kwds) diff --git a/src/sage/graphs/base/static_sparse_graph.pyx b/src/sage/graphs/base/static_sparse_graph.pyx index 898b69568d0..3bd7c9c9285 100644 --- a/src/sage/graphs/base/static_sparse_graph.pyx +++ b/src/sage/graphs/base/static_sparse_graph.pyx @@ -33,14 +33,14 @@ Data structure The data structure is actually pretty simple and compact. ``short_digraph`` has five fields -- ``n`` (``int``); the number of vertices in the graph +- ``n`` -- integer; the number of vertices in the graph -- ``m`` (``int``); the number of edges in the graph +- ``m`` -- integer; the number of edges in the graph -- ``edges`` (``uint32_t *``); array whose length is the number of edges of the +- ``edges`` -- ``uint32_t *``; array whose length is the number of edges of the graph -- ``neighbors`` (``uint32_t **``); this array has size `n+1`, and describes how +- ``neighbors`` -- ``uint32_t **``; this array has size `n+1`, and describes how the data of ``edges`` should be read : the neighbors of vertex `i` are the elements of ``edges`` addressed by ``neighbors[i]...neighbors[i+1]-1``. The element ``neighbors[n]``, which corresponds to no vertex (they are numbered @@ -48,7 +48,7 @@ five fields neighbors of vertex `n-1` : the last of them is the element addressed by ``neighbors[n]-1``. -- ``edge_labels`` (``list``); this cython list associates a label to each edge +- ``edge_labels`` -- list; this cython list associates a label to each edge of the graph. If a given edge is represented by ``edges[i]``, this its associated label can be found at ``edge_labels[i]``. This object is usually NULL, unless the call to ``init_short_digraph`` explicitly requires the labels @@ -514,7 +514,6 @@ cdef uint32_t simple_BFS(short_digraph g, - ``seen`` -- bitset of size ``n`` that must be initialized before calling this method (i.e., bitset_init(seen, n)). However, there is no need to clear it. - """ cdef uint32_t v, u cdef uint32_t waiting_beginning = 0 @@ -964,7 +963,7 @@ def triangles_count(G): INPUT: - - `G` -- a graph + - ``G`` -- a graph EXAMPLES:: @@ -1028,11 +1027,11 @@ def spectral_radius(G, prec=1e-10): INPUT: - - ``prec`` -- (default ``1e-10``) an upper bound for the relative precision + - ``prec`` -- (default: ``1e-10``) an upper bound for the relative precision of the interval - The algorithm is iterative and uses an inequality valid for non-negative - matrices. Namely, if `A` is a non-negative square matrix with + The algorithm is iterative and uses an inequality valid for nonnegative + matrices. Namely, if `A` is a nonnegative square matrix with Perron-Frobenius eigenvalue `\lambda` then the following inequality is valid for any vector `x` diff --git a/src/sage/graphs/bipartite_graph.py b/src/sage/graphs/bipartite_graph.py index 8ce6c3f4463..d5bfe02b9c8 100644 --- a/src/sage/graphs/bipartite_graph.py +++ b/src/sage/graphs/bipartite_graph.py @@ -81,7 +81,7 @@ class BipartiteGraph(Graph): #. From a NetworkX bipartite graph. - - ``partition`` -- (default: ``None``); a tuple defining vertices of the left + - ``partition`` -- (default: ``None``) a tuple defining vertices of the left and right partition of the graph. Partitions will be determined automatically if ``partition`` is ``None``. @@ -256,7 +256,7 @@ class BipartiteGraph(Graph): #. From an alist file:: sage: import tempfile - sage: with tempfile.NamedTemporaryFile(mode="w+t") as f: + sage: with tempfile.NamedTemporaryFile(mode='w+t') as f: ....: _ = f.write("7 4 \n 3 4 \n 3 3 1 3 1 1 1 \n\ ....: 3 3 3 4 \n 1 2 4 \n 1 3 4 \n 1 0 0 \n\ ....: 2 3 4 \n 2 0 0 \n 3 0 0 \n 4 0 0 \n\ @@ -354,7 +354,6 @@ class BipartiteGraph(Graph): Traceback (most recent call last): ... ValueError: cannot add edge from 0 to 0 in graph without loops - """ def __init__(self, data=None, partition=None, check=True, hash_labels=None, *args, **kwds): @@ -639,7 +638,7 @@ def _upgrade_from_graph(self): def __repr__(self): r""" - Return a short string representation of self. + Return a short string representation of ``self``. EXAMPLES:: @@ -659,16 +658,16 @@ def add_vertex(self, name=None, left=False, right=False): INPUT: - - ``name`` -- (default: ``None``); name of the new vertex. If no name is + - ``name`` -- (default: ``None``) name of the new vertex. If no name is specified, then the vertex will be represented by the least - non-negative integer not already representing a vertex. Name must be + nonnegative integer not already representing a vertex. Name must be an immutable object and cannot be ``None``. - ``left`` -- boolean (default: ``False``); if ``True``, puts the new - vertex in the left partition. + vertex in the left partition - ``right`` -- boolean (default: ``False``); if ``True``, puts the new - vertex in the right partition. + vertex in the right partition Obviously, ``left`` and ``right`` are mutually exclusive. @@ -756,13 +755,13 @@ def add_vertices(self, vertices, left=False, right=False): INPUT: - - ``vertices`` -- sequence of vertices to add. + - ``vertices`` -- sequence of vertices to add - - ``left`` -- (default: ``False``); either ``True`` or sequence of same - length as ``vertices`` with ``True``/``False`` elements. + - ``left`` -- (default: ``False``) either ``True`` or sequence of same + length as ``vertices`` with boolean elements - - ``right`` -- (default: ``False``); either ``True`` or sequence of the - same length as ``vertices`` with ``True``/``False`` elements. + - ``right`` -- (default: ``False``) either ``True`` or sequence of the + same length as ``vertices`` with boolean elements Only one of ``left`` and ``right`` keywords should be provided. See the examples below. @@ -846,11 +845,11 @@ def delete_vertex(self, vertex, in_order=False): INPUT: - - ``vertex`` -- a vertex to delete. + - ``vertex`` -- a vertex to delete - - ``in_order`` -- boolean (default ``False``); if ``True``, deletes the + - ``in_order`` -- boolean (default: ``False``); if ``True``, deletes the `i`-th vertex in the sorted list of vertices, - i.e. ``G.vertices(sort=True)[i]``. + i.e. ``G.vertices(sort=True)[i]`` EXAMPLES:: @@ -987,12 +986,12 @@ def add_edge(self, u, v=None, label=None): INPUT: - - ``u`` -- the tail of an edge. + - ``u`` -- the tail of an edge - - ``v`` -- (default: ``None``); the head of an edge. If ``v=None``, then - attempt to understand ``u`` as a edge tuple. + - ``v`` -- (default: ``None``) the head of an edge. If ``v=None``, then + attempt to understand ``u`` as a edge tuple - - ``label`` -- (default: ``None``); the label of the edge ``(u, v)``. + - ``label`` -- (default: ``None``) the label of the edge ``(u, v)`` The following forms are all accepted: @@ -1080,7 +1079,7 @@ def add_edges(self, edges, loops=True): INPUT: - ``edges`` -- an iterable of edges, given either as ``(u, v)`` - or ``(u, v, label)``. + or ``(u, v, label)`` - ``loops`` -- ignored @@ -1190,7 +1189,7 @@ def _check_bipartition_for_add_edges(self, edges): INPUT: - ``edges`` -- an iterable of edges, given either as ``(u, v)`` - or ``(u, v, label)``. + or ``(u, v, label)`` TESTS:: @@ -1254,7 +1253,7 @@ def _check_bipartition_for_add_edges(self, edges): def allow_loops(self, new, check=True): """ - Change whether loops are permitted in the (di)graph + Change whether loops are permitted in the (di)graph. .. NOTE:: @@ -1485,7 +1484,7 @@ def plot(self, *args, **kwds): kwds["pos"] = pos return Graph.plot(self, *args, **kwds) - def matching_polynomial(self, algorithm="Godsil", name=None): + def matching_polynomial(self, algorithm='Godsil', name=None): r""" Compute the matching polynomial. @@ -1498,7 +1497,7 @@ def matching_polynomial(self, algorithm="Godsil", name=None): INPUT: - - ``algorithm`` -- string (default: ``"Godsil"``); either "Godsil" or + - ``algorithm`` -- string (default: ``'Godsil'``); either "Godsil" or "rook"; "rook" is usually faster for larger graphs - ``name`` -- string (default: ``None``); name of the variable in the @@ -1539,7 +1538,7 @@ def matching_polynomial(self, algorithm="Godsil", name=None): sage: g = BipartiteGraph(matrix.ones(4, 3)) sage: g.matching_polynomial() # needs sage.libs.flint x^7 - 12*x^5 + 36*x^3 - 24*x - sage: g.matching_polynomial(algorithm="rook") + sage: g.matching_polynomial(algorithm='rook') x^7 - 12*x^5 + 36*x^3 - 24*x """ if algorithm == "Godsil": @@ -1724,7 +1723,7 @@ def load_afile(self, fname): EXAMPLES:: sage: import tempfile - sage: with tempfile.NamedTemporaryFile(mode="w+t") as f: + sage: with tempfile.NamedTemporaryFile(mode='w+t') as f: ....: _ = f.write("7 4 \n 3 4 \n 3 3 1 3 1 1 1 \n\ ....: 3 3 3 4 \n 1 2 4 \n 1 3 4 \n\ ....: 1 0 0 \n 2 3 4 \n 2 0 0 \n 3 0 0 \n\ @@ -1784,7 +1783,7 @@ def load_afile(self, fname): # read adjacency information for cidx in range(num_cols): for ridx in map(int, fi.readline().split()): - # A-list uses 1-based indices with 0's as place-holders + # A-list uses 1-based indices with 0s as place-holders if ridx > 0: self.add_edge(cidx, num_cols + ridx - 1) @@ -2061,29 +2060,29 @@ def matching(self, value_only=False, algorithm=None, - ``value_only`` -- boolean (default: ``False``); when set to ``True``, only the cardinal (or the weight) of the matching is returned - - ``algorithm`` -- string (default: ``"Hopcroft-Karp"`` if - ``use_edge_labels==False``, otherwise ``"Edmonds"``); algorithm to use + - ``algorithm`` -- string (default: ``'Hopcroft-Karp'`` if + ``use_edge_labels==False``, otherwise ``'Edmonds'``); algorithm to use among: - - ``"Hopcroft-Karp"`` selects the default bipartite graph algorithm as + - ``'Hopcroft-Karp'`` selects the default bipartite graph algorithm as implemented in NetworkX - - ``"Eppstein"`` selects Eppstein's algorithm as implemented in + - ``'Eppstein'`` selects Eppstein's algorithm as implemented in NetworkX - - ``"Edmonds"`` selects Edmonds' algorithm as implemented in NetworkX + - ``'Edmonds'`` selects Edmonds' algorithm as implemented in NetworkX - - ``"LP"`` uses a Linear Program formulation of the matching problem + - ``'LP'`` uses a Linear Program formulation of the matching problem - ``use_edge_labels`` -- boolean (default: ``False``) - when set to ``True``, computes a weighted matching where each edge is weighted by its label (if an edge has no label, `1` is assumed); - only if ``algorithm`` is ``"Edmonds"``, ``"LP"`` + only if ``algorithm`` is ``'Edmonds'``, ``'LP'`` - when set to ``False``, each edge has weight `1` - - ``solver`` -- string (default: ``None``); specify a Mixed + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the @@ -2092,7 +2091,7 @@ def matching(self, value_only=False, algorithm=None, class :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with @@ -2116,7 +2115,7 @@ class :class:`MixedIntegerLinearProgram Eppstein:: sage: G = BipartiteGraph(graphs.CompleteBipartiteGraph(4,5)) - sage: G.matching(algorithm="Eppstein", value_only=True) # needs networkx + sage: G.matching(algorithm='Eppstein', value_only=True) # needs networkx 4 TESTS: @@ -2125,7 +2124,7 @@ class :class:`MixedIntegerLinearProgram exception is raised:: sage: G = BipartiteGraph(graphs.CompleteBipartiteGraph(4,5)) - sage: G.matching(algorithm="somethingdifferent") + sage: G.matching(algorithm='somethingdifferent') Traceback (most recent call last): ... ValueError: algorithm must be "Hopcroft-Karp", "Eppstein", "Edmonds" or "LP" @@ -2225,11 +2224,11 @@ class :class:`MixedIntegerLinearProgram raise ValueError('algorithm must be "Hopcroft-Karp", ' '"Eppstein", "Edmonds" or "LP"') - def vertex_cover(self, algorithm="Konig", value_only=False, + def vertex_cover(self, algorithm='Konig', value_only=False, reduction_rules=True, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Return a minimum vertex cover of self represented by a set of vertices. + Return a minimum vertex cover of ``self`` represented by a set of vertices. A minimum vertex cover of a graph is a set `S` of vertices such that each edge is incident to at least one element of `S`, and such that `S` @@ -2249,19 +2248,19 @@ def vertex_cover(self, algorithm="Konig", value_only=False, INPUT: - - ``algorithm`` -- string (default: ``"Konig"``); algorithm to use + - ``algorithm`` -- string (default: ``'Konig'``); algorithm to use among: - - ``"Konig"`` will compute a minimum vertex cover using Konig's + - ``'Konig'`` will compute a minimum vertex cover using Konig's algorithm (:wikipedia:`Kőnig%27s_theorem_(graph_theory)`) - - ``"Cliquer"`` will compute a minimum vertex cover + - ``'Cliquer'`` will compute a minimum vertex cover using the Cliquer package - - ``"MILP"`` will compute a minimum vertex cover through a mixed + - ``'MILP'`` will compute a minimum vertex cover through a mixed integer linear program - - ``"mcqd"`` will use the MCQD solver + - ``'mcqd'`` will use the MCQD solver (``_), and the MCQD package must be installed @@ -2269,13 +2268,13 @@ def vertex_cover(self, algorithm="Konig", value_only=False, only the size of a minimum vertex cover is returned. Otherwise, a minimum vertex cover is returned as a list of vertices. - - ``reduction_rules`` -- (default: ``True``); specify if the reductions + - ``reduction_rules`` -- (default: ``True``) specify if the reductions rules from kernelization must be applied as pre-processing or not. See [ACFLSS04]_ for more details. Note that depending on the instance, it might be faster to disable reduction rules. This parameter is currently ignored when ``algorithm == "Konig"``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -2283,7 +2282,7 @@ def vertex_cover(self, algorithm="Konig", value_only=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -2304,8 +2303,8 @@ def vertex_cover(self, algorithm="Konig", value_only=False, sage: # needs networkx numpy sage: g = BipartiteGraph(graphs.RandomBipartite(10, 10, .5)) - sage: vc1 = g.vertex_cover(algorithm="Konig") - sage: vc2 = g.vertex_cover(algorithm="Cliquer") + sage: vc1 = g.vertex_cover(algorithm='Konig') + sage: vc2 = g.vertex_cover(algorithm='Cliquer') sage: len(vc1) == len(vc2) True @@ -2345,7 +2344,7 @@ def vertex_cover(self, algorithm="Konig", value_only=False, VC = [] for b in self.connected_components_subgraphs(): if b.size(): - VC.extend(b.vertex_cover(algorithm="Konig")) + VC.extend(b.vertex_cover(algorithm='Konig')) if value_only: return sum(VC) return VC @@ -2397,14 +2396,14 @@ def _subgraph_by_adding(self, vertices=None, edges=None, edge_property=None, imm - ``vertices`` -- list (default: ``None``); list of vertices - - ``edges`` -- (default: ``None``); either a single edge or an iterable + - ``edges`` -- (default: ``None``) either a single edge or an iterable container of edges (e.g., a list, set, file, numeric array, etc.). If no edges are specified, then all edges are assumed and the returned graph is an induced subgraph. In the case of multiple edges, specifying an edge as `(u, v)` means to keep all edges `(u, v)`, regardless of the label. - - ``edge_property`` -- (default: ``None``); if specified, this is + - ``edge_property`` -- (default: ``None``) if specified, this is expected to be a function on edges, which is intersected with the edges specified, if any are @@ -2478,7 +2477,7 @@ def _subgraph_by_deleting(self, vertices=None, edges=None, inplace=False, - ``vertices`` -- list (default: ``None``); list of vertices - - ``edges`` -- (default: ``None``); either a single edge or an iterable + - ``edges`` -- (default: ``None``) either a single edge or an iterable container of edges (e.g., a list, set, file, numeric array, etc.). If no edges are specified, then all edges are assumed and the returned graph is an induced subgraph. In the case of multiple edges, @@ -2489,7 +2488,7 @@ def _subgraph_by_deleting(self, vertices=None, edges=None, inplace=False, current graph is modified in place by deleting the extra vertices and edges. Otherwise a modified copy of the graph is returned - - ``edge_property`` -- (default: ``None``); if specified, this is + - ``edge_property`` -- (default: ``None``) if specified, this is expected to be a function on edges, which is intersected with the edges specified, if any are @@ -2567,15 +2566,15 @@ class by some canonization function `c`. If `G` and `H` are graphs, to this set partition will be computed. The default is the unit set partition. - - ``certificate`` -- boolean (default: ``False``). When set to + - ``certificate`` -- boolean (default: ``False``); when set to ``True``, a dictionary mapping from the vertices of the (di)graph - to its canonical label will also be returned. + to its canonical label will also be returned - - ``edge_labels`` -- boolean (default: ``False``). When set to - ``True``, allows only permutations respecting edge labels. + - ``edge_labels`` -- boolean (default: ``False``); when set to + ``True``, allows only permutations respecting edge labels - - ``algorithm`` -- a string (default: ``None``). The algorithm to use; - currently available: + - ``algorithm`` -- string (default: ``None``); the algorithm to use. + Currently available: * ``'bliss'``: use the optional package bliss (http://www.tcs.tkk.fi/Software/bliss/index.html); @@ -2587,9 +2586,9 @@ class by some canonization function `c`. If `G` and `H` are graphs, Make sure you always compare canonical forms obtained by the same algorithm. - - ``return_graph`` -- boolean (default: ``True``). When set to + - ``return_graph`` -- boolean (default: ``True``); when set to ``False``, returns the list of edges of the canonical graph - instead of the canonical graph; only available when ``'bliss'`` + instead of the canonical graph. Only available when ``'bliss'`` is explicitly set as algorithm. EXAMPLES:: @@ -2637,7 +2636,6 @@ class by some canonization function `c`. If `G` and `H` are graphs, .. SEEALSO:: :meth:`~sage.graphs.generic_graph.GenericGraph.canonical_label()` - """ if certificate: diff --git a/src/sage/graphs/bliss.pyx b/src/sage/graphs/bliss.pyx index f8491088abc..f9fc09db0ee 100644 --- a/src/sage/graphs/bliss.pyx +++ b/src/sage/graphs/bliss.pyx @@ -93,7 +93,7 @@ cdef void add_gen(void *user_param, unsigned int n, const unsigned int *aut) noe a Python object which is a pair ``(list_of_current_generators, vert_to_integer_labelling)``. - - ``n`` -- ``int``; number of points in the graph + - ``n`` -- integer; number of points in the graph - ``aut`` -- ``int *``; an automorphism of the graph """ @@ -157,17 +157,17 @@ cdef Graph *bliss_graph_from_labelled_edges(int Vnr, int Lnr, Vout, Vin, labels, INPUT: - - ``Vnr`` -- ``int``; number of vertices, such that the vertices are `0, + - ``Vnr`` -- integer; number of vertices, such that the vertices are `0, \ldots, Vnr-1` - - ``Lnr`` -- ``int``; number of labels, such that the labels are `0, \ldots, + - ``Lnr`` -- integer; number of labels, such that the labels are `0, \ldots, Lnr-1` - - ``Vout`` -- ``list``; the list of vertices of outgoing edges + - ``Vout`` -- list; the list of vertices of outgoing edges - - ``Vin`` -- ``list``; the list of vertices of ingoing edges + - ``Vin`` -- list; the list of vertices of ingoing edges - - ``labels`` -- ``list``; the list of edge labels + - ``labels`` -- list; the list of edge labels - ``partition`` -- an ordered partition of the vertex set """ @@ -234,17 +234,17 @@ cdef Digraph *bliss_digraph_from_labelled_edges(int Vnr, int Lnr, Vout, Vin, lab INPUT: - - ``Vnr`` -- ``int``; number of vertices, such that the vertices are `0, + - ``Vnr`` -- integer; number of vertices, such that the vertices are `0, \ldots, Vnr-1` - - ``Lnr`` -- ``int``; number of labels, such that the labels are `0, \ldots, + - ``Lnr`` -- integer; number of labels, such that the labels are `0, \ldots, Lnr-1` - - ``Vout`` -- ``list``; the list of vertices of outgoing edges + - ``Vout`` -- list; the list of vertices of outgoing edges - - ``Vin`` -- ``list``; the list of vertices of ingoing edges + - ``Vin`` -- list; the list of vertices of ingoing edges - - ``labels`` -- ``list``; the list of edge labels + - ``labels`` -- list; the list of edge labels - ``partition`` -- a partition of the vertex set """ @@ -306,19 +306,19 @@ cdef canonical_form_from_edge_list(int Vnr, list Vout, list Vin, int Lnr=1, list INPUT: - - ``Vnr`` -- ``int``; number of vertices, such that the vertices are `0, + - ``Vnr`` -- integer; number of vertices, such that the vertices are `0, \ldots, Vnr-1` - - ``Vout`` -- ``list``; the list of vertices of outgoing edges + - ``Vout`` -- list; the list of vertices of outgoing edges - - ``Vin`` -- ``list``; the list of vertices of ingoing edges + - ``Vin`` -- list; the list of vertices of ingoing edges - - ``Lnr`` -- ``int`` (default: 1); number of labels, such that the labels + - ``Lnr`` -- integer (default: 1); number of labels, such that the labels are `0, \ldots, Lnr-1` - - ``labels`` -- ``list`` (default: ``[]``); the list of edge labels + - ``labels`` -- list (default: ``[]``); the list of edge labels - - ``partition`` -- ``list`` (default: ``None``); a partition of the vertex + - ``partition`` -- list (default: ``None``); a partition of the vertex set - ``directed`` -- boolean (default: ``False``); whether the edges are @@ -389,7 +389,7 @@ cpdef canonical_form(G, partition=None, return_graph=False, use_edge_labels=True - ``G`` -- a Sage (Di)Graph - - ``partition`` -- ``list`` (default: ``None``); a partition of the vertices + - ``partition`` -- list (default: ``None``); a partition of the vertices of ``G`` into color classes - ``return_graph`` -- boolean (default: ``False``); whether to return the @@ -397,7 +397,7 @@ cpdef canonical_form(G, partition=None, return_graph=False, use_edge_labels=True - ``use_edge_labels`` -- boolean (default: ``True``); whether to consider edge labels. The edge labels are assumed to be hashable and - sortable. If this is not the case (ie a :class:`TypeError` is + sortable. If this is not the case (ie a :exc:`TypeError` is raised), the algorithm will consider the string representations of the labels instead of the labels. @@ -487,19 +487,19 @@ cpdef canonical_form(G, partition=None, return_graph=False, use_edge_labels=True Check that :issue:`32395` is fixed:: sage: g = Graph([[0, 2]]) # 1 is not a vertex! - sage: g.canonical_label(partition=[[0], [1], [2]], algorithm="bliss") # optional - bliss + sage: g.canonical_label(partition=[[0], [1], [2]], algorithm='bliss') # optional - bliss Traceback (most recent call last): ... ValueError: vertex 1 of the partition is not a vertex of the graph - sage: g.canonical_label(partition=[[0], [0, 2]], algorithm="bliss") # optional - bliss + sage: g.canonical_label(partition=[[0], [0, 2]], algorithm='bliss') # optional - bliss Traceback (most recent call last): ... ValueError: vertex 0 can appear only once in the partition - sage: g.canonical_label(partition=[[0, 0], [2]], algorithm="bliss") # optional - bliss + sage: g.canonical_label(partition=[[0, 0], [2]], algorithm='bliss') # optional - bliss Traceback (most recent call last): ... ValueError: vertex 0 can appear only once in the partition - sage: g.canonical_label(partition=[[0]], algorithm="bliss") # optional - bliss + sage: g.canonical_label(partition=[[0]], algorithm='bliss') # optional - bliss Traceback (most recent call last): ... ValueError: some vertices of the graph are not in the partition @@ -604,21 +604,21 @@ cdef automorphism_group_gens_from_edge_list(int Vnr, Vout, Vin, int Lnr=1, label INPUT: - - ``Vnr`` -- ``int``; number of vertices, such that the vertices are `0, + - ``Vnr`` -- integer; number of vertices, such that the vertices are `0, \ldots, Vnr-1` - - ``Vout`` -- ``list``; the list of vertices of outgoing edges + - ``Vout`` -- list; the list of vertices of outgoing edges - - ``Vin`` -- ``list``; the list of vertices of ingoing edges + - ``Vin`` -- list; the list of vertices of ingoing edges - - ``Lnr`` -- ``int`` (default: 1); number of labels, such that the labels + - ``Lnr`` -- integer (default: 1); number of labels, such that the labels are `0, \ldots, Lnr-1` - - ``labels`` -- ``list`` (default: ``[]``); the list of edge labels + - ``labels`` -- list (default: ``[]``); the list of edge labels - - ``int2vert`` -- ``list`` (default: ``[]``); ordering of the vertices + - ``int2vert`` -- list (default: ``[]``); ordering of the vertices - - ``partition`` -- ``list`` (default: ``None``); a partition of the vertex + - ``partition`` -- list (default: ``None``); a partition of the vertex set - ``directed`` -- boolean (default: ``False``); whether the edges are @@ -664,7 +664,7 @@ cpdef automorphism_group(G, partition=None, use_edge_labels=True) noexcept: - ``G`` -- a Sage graph - - ``partition`` -- ``list`` (default: ``None``); a partition of the vertices + - ``partition`` -- list (default: ``None``); a partition of the vertices of ``G`` into color classes. Defaults to ``None``, which is equivalent to a partition of size 1. @@ -855,9 +855,9 @@ cdef Graph *bliss_graph(G, partition, vert2int, int2vert) noexcept: - ``G`` -- a Sage Graph - - ``partition`` -- ``list``; a partition of the vertex set + - ``partition`` -- list; a partition of the vertex set - - ``vert2int, int2vert`` -- a empty ``dict`` and a empty ``list``; the + - ``vert2int, int2vert`` -- a empty ``dict`` and a empty list; the entries of the dictionary are later set to record the labeling of our graph. They are taken as arguments to avoid technicalities of returning Python objects in Cython functions. @@ -889,9 +889,9 @@ cdef Digraph *bliss_digraph(G, partition, vert2int, int2vert) noexcept: - ``G`` -- a Sage DiGraph - - ``partition`` -- ``list``; a partition of the vertex set + - ``partition`` -- list; a partition of the vertex set - - ``vert2int, int2vert`` -- a empty ``dict`` and a empty ``list``; the + - ``vert2int, int2vert`` -- a empty ``dict`` and a empty list; the entries of the dictionary are later set to record the labeling of our graph. They are taken as arguments to avoid technicalities of returning Python objects in Cython functions. diff --git a/src/sage/graphs/centrality.pyx b/src/sage/graphs/centrality.pyx index 1285dda406d..b3165b69232 100755 --- a/src/sage/graphs/centrality.pyx +++ b/src/sage/graphs/centrality.pyx @@ -38,7 +38,7 @@ cimport cython def centrality_betweenness(G, bint exact=False, bint normalize=True): r""" - Return the centrality betweenness of `G` + Return the centrality betweenness of `G`. The centrality betweenness of a vertex `v\in G` is defined by: @@ -54,7 +54,7 @@ def centrality_betweenness(G, bint exact=False, bint normalize=True): - ``G`` -- a (di)graph - ``exact`` -- boolean (default: ``False``); whether to compute over - rationals or on ``double`` C variables. + rationals or on ``double`` C variables - ``normalize`` -- boolean (default: ``True``); whether to renormalize the values by dividing them by `\binom {n-1} 2` (for graphs) or `2\binom {n-1} @@ -115,7 +115,6 @@ def centrality_betweenness(G, bint exact=False, bint normalize=True): {0: 0.0, 1: 0.0} sage: centrality_betweenness(Graph(2), exact=1) {0: 0, 1: 0} - """ if exact: return centrality_betweenness_C(G, 0, normalize=normalize) @@ -125,7 +124,7 @@ def centrality_betweenness(G, bint exact=False, bint normalize=True): @cython.cdivision(True) cdef dict centrality_betweenness_C(G, numerical_type _, bint normalize=True): r""" - Return the centrality betweenness of G (C implementation) + Return the centrality betweenness of G (C implementation). INPUT: @@ -852,9 +851,7 @@ def centrality_closeness_random_k(G, int k=1): - ``k`` -- integer (default: 1); number of random nodes to choose - OUTPUT: - - A dictionary associating to each vertex its estimated closeness centrality. + OUTPUT: a dictionary associating to each vertex its estimated closeness centrality EXAMPLES: @@ -887,7 +884,6 @@ def centrality_closeness_random_k(G, int k=1): Traceback (most recent call last): ... ValueError: G must be an undirected Graph - """ G._scream_if_not_simple() if G.is_directed(): diff --git a/src/sage/graphs/chrompoly.pyx b/src/sage/graphs/chrompoly.pyx index 920a2b0eee0..17a9837041b 100644 --- a/src/sage/graphs/chrompoly.pyx +++ b/src/sage/graphs/chrompoly.pyx @@ -55,16 +55,16 @@ def chromatic_polynomial(G, return_tree_basis=False, algorithm='C', cache=None): - ``return_tree_basis`` -- boolean (default: ``False``); not used yet - - ``algorithm`` -- string (default: ``"C"``); the algorithm to use among + - ``algorithm`` -- string (default: ``'C'``); the algorithm to use among - - ``"C"``, an implementation in C by Robert Miller and Gordon Royle. + - ``'C'``, an implementation in C by Robert Miller and Gordon Royle. - - ``"Python"``, an implementation in Python using caching to avoid + - ``'Python'``, an implementation in Python using caching to avoid recomputing the chromatic polynomial of a graph that has already been seen. This seems faster on some dense graphs. - ``cache`` -- dictionary (default: ``None``); this parameter is used only - for algorithm ``"Python"``. It is a dictionary keyed by canonical + for algorithm ``'Python'``. It is a dictionary keyed by canonical labelings of graphs and used to cache the chromatic polynomials of the graphs generated by the algorithm. In other words, it avoids computing twice the chromatic polynomial of isometric graphs. One will be created @@ -114,7 +114,7 @@ def chromatic_polynomial(G, return_tree_basis=False, algorithm='C', cache=None): sage: min(i for i in range(11) if P(i) > 0) == G.chromatic_number() True - Check that algorithms ``"C"`` and ``"Python"`` return the same results:: + Check that algorithms ``'C'`` and ``'Python'`` return the same results:: sage: G = graphs.RandomGNP(8, randint(1, 9)*0.1) sage: c = G.chromatic_polynomial(algorithm='C') @@ -136,7 +136,7 @@ def chromatic_polynomial(G, return_tree_basis=False, algorithm='C', cache=None): Giving a wrong algorithm:: - sage: Graph().chromatic_polynomial(algorithm="foo") + sage: Graph().chromatic_polynomial(algorithm='foo') Traceback (most recent call last): ... ValueError: algorithm must be "C" or "Python" diff --git a/src/sage/graphs/cographs.py b/src/sage/graphs/cographs.py index 35a45b47ff3..a78e8a24376 100644 --- a/src/sage/graphs/cographs.py +++ b/src/sage/graphs/cographs.py @@ -295,7 +295,7 @@ def cographs(n, as_graph=True, immutable=False): INPUT: - - ``n`` -- an integer larger or equal to 1 + - ``n`` -- integer larger or equal to 1 - ``as_graph`` -- boolean (default: ``True``); whether to return graphs or the tree data structure encoding the graph diff --git a/src/sage/graphs/comparability.pyx b/src/sage/graphs/comparability.pyx index ebafaac95f3..05d5d3b5185 100644 --- a/src/sage/graphs/comparability.pyx +++ b/src/sage/graphs/comparability.pyx @@ -15,12 +15,12 @@ The following methods are implemented in this module :widths: 30, 70 :delim: | - :meth:`~is_comparability_MILP` | Tests whether the graph is a comparability graph (MILP) - :meth:`~greedy_is_comparability` | Tests whether the graph is a comparability graph (greedy algorithm) - :meth:`~greedy_is_comparability_with_certificate` | Tests whether the graph is a comparability graph and returns certificates (greedy algorithm) - :meth:`~is_comparability` | Tests whether the graph is a comparability graph - :meth:`~is_permutation` | Tests whether the graph is a permutation graph. - :meth:`~is_transitive` | Tests whether the digraph is transitive. + :meth:`~is_comparability_MILP` | Test whether the graph is a comparability graph (MILP) + :meth:`~greedy_is_comparability` | Test whether the graph is a comparability graph (greedy algorithm) + :meth:`~greedy_is_comparability_with_certificate` | Test whether the graph is a comparability graph and returns certificates (greedy algorithm) + :meth:`~is_comparability` | Test whether the graph is a comparability graph + :meth:`~is_permutation` | Test whether the graph is a permutation graph. + :meth:`~is_transitive` | Test whether the digraph is transitive. Author: @@ -210,7 +210,7 @@ from copy import copy def greedy_is_comparability(g, no_certificate=False, equivalence_class=False): r""" - Tests whether the graph is a comparability graph (greedy algorithm) + Test whether the graph is a comparability graph (greedy algorithm). This method only returns no-certificates. @@ -224,7 +224,7 @@ def greedy_is_comparability(g, no_certificate=False, equivalence_class=False): each of which implies the next. It is set to ``False`` by default. - ``equivalence_class`` -- whether to return an equivalence class - if the graph is a comparability graph. + if the graph is a comparability graph OUTPUT: @@ -317,7 +317,7 @@ def greedy_is_comparability(g, no_certificate=False, equivalence_class=False): def greedy_is_comparability_with_certificate(g, certificate=False): r""" - Tests whether the graph is a comparability graph and returns + Test whether the graph is a comparability graph and returns certificates(greedy algorithm). This method can return certificates of both *yes* and *no* answers. @@ -327,7 +327,7 @@ def greedy_is_comparability_with_certificate(g, certificate=False): INPUT: - - ``certificate`` (boolean) -- whether to return a + - ``certificate`` -- boolean; whether to return a certificate. *Yes*-answers the certificate is a transitive orientation of `G`, and a *no* certificates is an odd cycle of sequentially forcing edges. @@ -393,20 +393,20 @@ def greedy_is_comparability_with_certificate(g, certificate=False): def is_comparability_MILP(g, certificate=False, solver=None, verbose=0): r""" - Tests whether the graph is a comparability graph (MILP) + Test whether the graph is a comparability graph (MILP). INPUT: - - ``certificate`` (boolean) -- whether to return a certificate for + - ``certificate`` -- boolean; whether to return a certificate for yes instances. This method cannot return negative certificates. - - ``solver`` -- (default: ``None``); Specify a Linear Program (LP) solver to + - ``solver`` -- (default: ``None``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`~sage.numerical.mip.MixedIntegerLinearProgram.solve` of the class :class:`~sage.numerical.mip.MixedIntegerLinearProgram`. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. EXAMPLES: @@ -491,39 +491,39 @@ def is_comparability_MILP(g, certificate=False, solver=None, verbose=0): # Empty shell # ############### -def is_comparability(g, algorithm="greedy", certificate=False, check=True, +def is_comparability(g, algorithm='greedy', certificate=False, check=True, solver=None, verbose=0): r""" - Tests whether the graph is a comparability graph + Test whether the graph is a comparability graph. INPUT: - - ``algorithm`` -- choose the implementation used to do the test. + - ``algorithm`` -- choose the implementation used to do the test - - ``"greedy"`` -- a greedy algorithm (see the documentation of the - :mod:`comparability module `). + - ``'greedy'`` -- a greedy algorithm (see the documentation of the + :mod:`comparability module `) - - ``"MILP"`` -- a Mixed Integer Linear Program formulation of the + - ``'MILP'`` -- a Mixed Integer Linear Program formulation of the problem. Beware, for this implementation is unable to return negative certificates ! When ``certificate = True``, negative certificates are - always equal to ``None``. True certificates are valid, though. + always equal to ``None``. ``True`` certificates are valid, though. - - ``certificate`` (boolean) -- whether to return a + - ``certificate`` -- boolean; whether to return a certificate. *Yes*-answers the certificate is a transitive orientation of `G`, and a *no* certificates is an odd cycle of sequentially forcing edges. - - ``check`` (boolean) -- whether to check that the + - ``check`` -- boolean; whether to check that the yes-certificates are indeed transitive. As it is very quick compared to the rest of the operation, it is enabled by default. - - ``solver`` -- (default: ``None``); Specify a Linear Program (LP) solver to + - ``solver`` -- (default: ``None``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`~sage.numerical.mip.MixedIntegerLinearProgram.solve` of the class :class:`~sage.numerical.mip.MixedIntegerLinearProgram`. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. EXAMPLES:: @@ -575,10 +575,10 @@ def is_comparability(g, algorithm="greedy", certificate=False, check=True, return isit, certif -def is_permutation(g, algorithm="greedy", certificate=False, check=True, +def is_permutation(g, algorithm='greedy', certificate=False, check=True, solver=None, verbose=0): r""" - Tests whether the graph is a permutation graph. + Test whether the graph is a permutation graph. For more information on permutation graphs, refer to the documentation of the :mod:`comparability module `. @@ -586,32 +586,32 @@ def is_permutation(g, algorithm="greedy", certificate=False, check=True, INPUT: - ``algorithm`` -- choose the implementation used for the subcalls to - :meth:`is_comparability`. + :meth:`is_comparability` - - ``"greedy"`` -- a greedy algorithm (see the documentation of the - :mod:`comparability module `). + - ``'greedy'`` -- a greedy algorithm (see the documentation of the + :mod:`comparability module `) - - ``"MILP"`` -- a Mixed Integer Linear Program formulation of the + - ``'MILP'`` -- a Mixed Integer Linear Program formulation of the problem. Beware, for this implementation is unable to return negative certificates ! When ``certificate = True``, negative certificates are - always equal to ``None``. True certificates are valid, though. + always equal to ``None``. ``True`` certificates are valid, though. - - ``certificate`` (boolean) -- whether to return a certificate for the + - ``certificate`` -- boolean; whether to return a certificate for the answer given. For ``True`` answers the certificate is a permutation, for ``False`` answers it is a no-certificate for the test of comparability or co-comparability. - - ``check`` (boolean) -- whether to check that the permutations returned + - ``check`` -- boolean; whether to check that the permutations returned indeed create the expected Permutation graph. Pretty cheap compared to the rest, hence a good investment. It is enabled by default. - - ``solver`` -- (default: ``None``); Specify a Linear Program (LP) solver to + - ``solver`` -- (default: ``None``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`~sage.numerical.mip.MixedIntegerLinearProgram.solve` of the class :class:`~sage.numerical.mip.MixedIntegerLinearProgram`. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. .. NOTE:: @@ -638,7 +638,7 @@ def is_permutation(g, algorithm="greedy", certificate=False, check=True, sage: p1 = Permutation([nn+1 for nn in perm[0]]) sage: p2 = Permutation([nn+1 for nn in perm[1]]) sage: p = p2 * p1.inverse() - sage: p.show(representation="braid") # needs sage.plot + sage: p.show(representation='braid') # needs sage.plot TESTS: @@ -663,7 +663,7 @@ def is_permutation(g, algorithm="greedy", certificate=False, check=True, sage: for i in range(20): # needs sage.numerical.mip ....: p = Permutations(10).random_element() ....: g1 = graphs.PermutationGraph(p) - ....: isit, certif = is_permutation(g1, algorithm="MILP", certificate=True) + ....: isit, certif = is_permutation(g1, algorithm='MILP', certificate=True) ....: if not isit: ....: print("Something is wrong here !!") ....: break @@ -671,7 +671,6 @@ def is_permutation(g, algorithm="greedy", certificate=False, check=True, ....: if not g1.is_isomorphic(g2): ....: print("Something is wrong here !!") ....: break - """ if not certificate: # No certificate... A piece of cake @@ -714,14 +713,14 @@ def is_permutation(g, algorithm="greedy", certificate=False, check=True, def is_transitive(g, certificate=False): r""" - Tests whether the digraph is transitive. + Test whether the digraph is transitive. A digraph is transitive if for any pair of vertices `u,v\in G` linked by a `uv`-path the edge `uv` belongs to `G`. INPUT: - - ``certificate`` -- whether to return a certificate for negative answers. + - ``certificate`` -- whether to return a certificate for negative answers - If ``certificate = False`` (default), this method returns ``True`` or ``False`` according to the graph. diff --git a/src/sage/graphs/connectivity.pyx b/src/sage/graphs/connectivity.pyx index ee387ab352b..2d299e254fe 100644 --- a/src/sage/graphs/connectivity.pyx +++ b/src/sage/graphs/connectivity.pyx @@ -23,7 +23,7 @@ Here is what the module can do: :meth:`connected_components_sizes` | Return the sizes of the connected components as a list. :meth:`blocks_and_cut_vertices` | Return the blocks and cut vertices of the graph. :meth:`blocks_and_cuts_tree` | Return the blocks-and-cuts tree of the graph. - :meth:`is_cut_edge` | Return True if the input edge is a cut-edge or a bridge. + :meth:`is_cut_edge` | Return ``True`` if the input edge is a cut-edge or a bridge. :meth:`is_cut_vertex` | Check whether the input vertex is a cut-vertex. :meth:`edge_connectivity` | Return the edge connectivity of the graph. :meth:`vertex_connectivity` | Return the vertex connectivity of the graph. @@ -48,7 +48,7 @@ Here is what the module can do: :widths: 30, 70 :delim: | - :meth:`bridges` | Returns an iterator over the bridges (or cut edges) of given undirected graph. + :meth:`bridges` | Return an iterator over the bridges (or cut edges) of given undirected graph. :meth:`cleave` | Return the connected subgraphs separated by the input vertex cut. :meth:`is_triconnected` | Check whether the graph is triconnected. :meth:`spqr_tree` | Return a SPQR-tree representing the triconnected components of the graph. @@ -416,7 +416,7 @@ def connected_components_sizes(G): return [len(cc) for cc in connected_components(G, sort=False)] -def blocks_and_cut_vertices(G, algorithm="Tarjan_Boost", sort=False, key=None): +def blocks_and_cut_vertices(G, algorithm='Tarjan_Boost', sort=False, key=None): """ Return the blocks and cut vertices of the graph. @@ -430,17 +430,17 @@ def blocks_and_cut_vertices(G, algorithm="Tarjan_Boost", sort=False, key=None): INPUT: - - ``algorithm`` -- string (default: ``"Tarjan_Boost"``); the algorithm to + - ``algorithm`` -- string (default: ``'Tarjan_Boost'``); the algorithm to use among: - - ``"Tarjan_Boost"`` (default) -- Tarjan's algorithm (Boost + - ``'Tarjan_Boost'`` -- default; Tarjan's algorithm (Boost implementation) - - ``"Tarjan_Sage"`` -- Tarjan's algorithm (Sage implementation) + - ``'Tarjan_Sage'`` -- Tarjan's algorithm (Sage implementation) - ``sort`` -- boolean (default: ``False``); whether to sort vertices inside the components and the list of cut vertices - **currently only available for ``"Tarjan_Sage"``** + **currently only available for ``'Tarjan_Sage'``** - ``key`` -- a function (default: ``None``); a function that takes a vertex as its one argument and returns a value that can be used for @@ -473,10 +473,10 @@ def blocks_and_cut_vertices(G, algorithm="Tarjan_Boost", sort=False, key=None): ([[0, 1, 4, 2, 3], [0, 6, 9, 7, 8]], [0]) sage: rings.blocks_and_cut_vertices() ([[0, 1, 4, 2, 3], [0, 6, 9, 7, 8]], [0]) - sage: B, C = blocks_and_cut_vertices(rings, algorithm="Tarjan_Sage", sort=True) + sage: B, C = blocks_and_cut_vertices(rings, algorithm='Tarjan_Sage', sort=True) sage: B, C ([[0, 1, 2, 3, 4], [0, 6, 7, 8, 9]], [0]) - sage: B2, C2 = blocks_and_cut_vertices(rings, algorithm="Tarjan_Sage", sort=False) + sage: B2, C2 = blocks_and_cut_vertices(rings, algorithm='Tarjan_Sage', sort=False) sage: Set(map(Set, B)) == Set(map(Set, B2)) and set(C) == set(C2) True @@ -502,7 +502,7 @@ def blocks_and_cut_vertices(G, algorithm="Tarjan_Boost", sort=False, key=None): sage: rings = graphs.CycleGraph(10) sage: rings.merge_vertices([0, 5]) sage: rings = rings.to_directed() - sage: blocks_and_cut_vertices(rings, algorithm="Tarjan_Boost") + sage: blocks_and_cut_vertices(rings, algorithm='Tarjan_Boost') ([[0, 1, 4, 2, 3], [0, 6, 9, 7, 8]], [0]) TESTS:: @@ -734,7 +734,7 @@ def blocks_and_cuts_tree(G): def is_cut_edge(G, u, v=None, label=None): """ - Returns True if the input edge is a cut-edge or a bridge. + Return ``True`` if the input edge is a cut-edge or a bridge. A cut edge (or bridge) is an edge that when removed increases the number of connected components. This function works with @@ -754,7 +754,7 @@ def is_cut_edge(G, u, v=None, label=None): OUTPUT: - - Returns True if (u,v) is a cut edge, False otherwise + - Returns ``True`` if (u,v) is a cut edge, False otherwise EXAMPLES:: @@ -1002,14 +1002,14 @@ def edge_connectivity(G, - ``implementation`` -- string (default: ``None``); selects an implementation: - - ``None`` (default) -- selects the best implementation available + - ``None`` -- default; selects the best implementation available - - ``"boost"`` -- use the Boost graph library (which is much more + - ``'boost'`` -- use the Boost graph library (which is much more efficient). It is not available when ``edge_labels=True``, and it is unreliable for directed graphs (see :issue:`18753`). - -``"Sage"`` -- use Sage's implementation based on integer linear - programming + - ``'Sage'`` -- use Sage's implementation based on integer linear + programming - ``use_edge_labels`` -- boolean (default: ``False``) @@ -1024,7 +1024,7 @@ def edge_connectivity(G, - When set to ``True``, also returns the two sets of vertices that are disconnected by the cut. Implies ``value_only=False``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1032,7 +1032,7 @@ def edge_connectivity(G, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -1091,26 +1091,26 @@ def edge_connectivity(G, It is the case for graphs which are not connected :: sage: g = 2 * graphs.PetersenGraph() - sage: edge_connectivity(g, implementation="sage") + sage: edge_connectivity(g, implementation='sage') 0.0 For directed graphs, the strong connectivity is tested through the dedicated function:: sage: g = digraphs.ButterflyGraph(3) - sage: edge_connectivity(g, implementation="sage") + sage: edge_connectivity(g, implementation='sage') 0.0 We check that the result with Boost is the same as the result without Boost:: sage: g = graphs.RandomGNP(15, .3) - sage: (edge_connectivity(g, implementation="boost") # needs sage.numerical.mip - ....: == edge_connectivity(g, implementation="sage")) + sage: (edge_connectivity(g, implementation='boost') # needs sage.numerical.mip + ....: == edge_connectivity(g, implementation='sage')) True Boost interface also works with directed graphs:: - sage: edge_connectivity(digraphs.Circuit(10), implementation="boost", + sage: edge_connectivity(digraphs.Circuit(10), implementation='boost', ....: vertices=True) [1, [(0, 1)], [{0}, {1, 2, 3, 4, 5, 6, 7, 8, 9}]] @@ -1120,12 +1120,12 @@ def edge_connectivity(G, sage: g = digraphs.Path(3) sage: edge_connectivity(g) 0.0 - sage: edge_connectivity(g, implementation="boost") + sage: edge_connectivity(g, implementation='boost') 1 sage: g.add_edge(1, 0) sage: edge_connectivity(g) 0.0 - sage: edge_connectivity(g, implementation="boost") + sage: edge_connectivity(g, implementation='boost') 0 TESTS: @@ -1134,8 +1134,8 @@ def edge_connectivity(G, sage: for i in range(10): # needs sage.numerical.mip ....: g = graphs.RandomGNP(30, 0.3) - ....: e1 = edge_connectivity(g, implementation="boost") - ....: e2 = edge_connectivity(g, implementation="sage") + ....: e1 = edge_connectivity(g, implementation='boost') + ....: e2 = edge_connectivity(g, implementation='sage') ....: assert (e1 == e2) Disconnected graphs and ``vertices=True``:: @@ -1342,7 +1342,7 @@ def vertex_connectivity(G, value_only=True, sets=False, k=None, solver=None, ver connectivity of the (di)graph is larger or equal to `k`. The method thus outputs a boolean only. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1350,7 +1350,7 @@ def vertex_connectivity(G, value_only=True, sets=False, k=None, solver=None, ver :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -1637,7 +1637,7 @@ def is_strongly_connected(G): def strongly_connected_components_digraph(G, keep_labels=False): r""" - Return the digraph of the strongly connected components + Return the digraph of the strongly connected components. The digraph of the strongly connected components of a graph `G` has a vertex per strongly connected component included in `G`. There is an edge from a @@ -1778,7 +1778,7 @@ def strongly_connected_components_subgraphs(G): def strongly_connected_component_containing_vertex(G, v): """ - Return the strongly connected component containing a given vertex + Return the strongly connected component containing a given vertex. INPUT: @@ -1820,7 +1820,6 @@ def strongly_connected_component_containing_vertex(G, v): Traceback (most recent call last): ... ValueError: vertex ('z') is not a vertex of the DiGraph - """ from sage.graphs.digraph import DiGraph if not isinstance(G, DiGraph): @@ -1848,7 +1847,7 @@ def strong_articulation_points(G): algorithm described in [ILS2012]_. The time complexity is dominated by the time complexity of the immediate dominators finding algorithm. - OUTPUT: The list of strong articulation points. + OUTPUT: the list of strong articulation points EXAMPLES: @@ -2075,7 +2074,7 @@ def cleave(G, cut_vertices=None, virtual_edges=True, solver=None, verbose=0, INPUT: - - ``G`` -- a Graph. + - ``G`` -- a Graph - ``cut_vertices`` -- iterable container of vertices (default: ``None``); a set of vertices representing a vertex cut of ``G``. If no vertex cut is @@ -2086,7 +2085,7 @@ def cleave(G, cut_vertices=None, virtual_edges=True, solver=None, verbose=0, edges to the sides of the cut or not. A virtual edge is an edge between a pair of vertices of the cut that are not connected by an edge in ``G``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -2094,14 +2093,14 @@ def cleave(G, cut_vertices=None, virtual_edges=True, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers over an inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. - OUTPUT: A triple `(S, C, f)`, where + OUTPUT: a triple `(S, C, f)`, where - `S` is a list of the graphs that are sides of the vertex cut. @@ -2263,7 +2262,7 @@ def cleave(G, cut_vertices=None, virtual_edges=True, solver=None, verbose=0, return cut_sides, cocycles, virtual_cut_graph -def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, +def spqr_tree(G, algorithm='Hopcroft_Tarjan', solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return an SPQR-tree representing the triconnected components of the graph. @@ -2273,17 +2272,17 @@ def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, them. A node of a SPQR-tree, and the graph associated with it, can be one of the following four types: - - ``"S"`` -- the associated graph is a cycle with at least three vertices. - ``"S"`` stands for ``series``. + - ``'S'`` -- the associated graph is a cycle with at least three vertices + ``'S'`` stands for ``series`` - - ``"P"`` -- the associated graph is a dipole graph, a multigraph with two - vertices and three or more edges. ``"P"`` stands for ``parallel``. + - ``'P'`` -- the associated graph is a dipole graph, a multigraph with two + vertices and three or more edges. ``'P'`` stands for ``parallel`` - - ``"Q"`` -- the associated graph has a single real edge. This trivial case - is necessary to handle the graph that has only one edge. + - ``'Q'`` -- the associated graph has a single real edge. This trivial case + is necessary to handle the graph that has only one edge - - ``"R"`` -- the associated graph is a 3-connected graph that is not a cycle - or dipole. ``"R"`` stands for ``rigid``. + - ``'R'`` -- the associated graph is a 3-connected graph that is not a cycle + or dipole. ``'R'`` stands for ``rigid`` This method decomposes a biconnected graph into cycles, cocycles, and 3-connected blocks summed over cocycles, and arranges them as a SPQR-tree. @@ -2297,17 +2296,17 @@ def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, - ``G`` -- the input graph - - ``algorithm`` -- string (default: ``"Hopcroft_Tarjan"``); the algorithm to + - ``algorithm`` -- string (default: ``'Hopcroft_Tarjan'``); the algorithm to use among: - - ``"Hopcroft_Tarjan"`` (default) -- use the algorithm proposed by + - ``'Hopcroft_Tarjan'`` -- default; use the algorithm proposed by Hopcroft and Tarjan in [Hopcroft1973]_ and later corrected by Gutwenger and Mutzel in [Gut2001]_. See :class:`~sage.graphs.connectivity.TriconnectivitySPQR`. - - ``"cleave"`` -- using method :meth:`~sage.graphs.connectivity.cleave` + - ``'cleave'`` -- using method :meth:`~sage.graphs.connectivity.cleave` - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -2315,7 +2314,7 @@ def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -2377,7 +2376,7 @@ def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, True sage: G = Graph('LlCG{O@?GBoMw?') - sage: T = spqr_tree(G, algorithm="Hopcroft_Tarjan") + sage: T = spqr_tree(G, algorithm='Hopcroft_Tarjan') sage: G.is_isomorphic(spqr_tree_to_graph(T)) True sage: T2 = spqr_tree(G, algorithm='cleave') # needs sage.numerical.mip @@ -2399,26 +2398,26 @@ def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, sage: from collections import Counter sage: G = graphs.PetersenGraph() - sage: T = G.spqr_tree(algorithm="Hopcroft_Tarjan") + sage: T = G.spqr_tree(algorithm='Hopcroft_Tarjan') sage: Counter(u[0] for u in T) Counter({'R': 1}) - sage: T = G.spqr_tree(algorithm="cleave") # needs sage.numerical.mip + sage: T = G.spqr_tree(algorithm='cleave') # needs sage.numerical.mip sage: Counter(u[0] for u in T) # needs sage.numerical.mip Counter({'R': 1}) sage: for u,v in list(G.edges(labels=False, sort=False)): ....: G.add_path([u, G.add_vertex(), G.add_vertex(), v]) - sage: T = G.spqr_tree(algorithm="Hopcroft_Tarjan") + sage: T = G.spqr_tree(algorithm='Hopcroft_Tarjan') sage: sorted(Counter(u[0] for u in T).items()) [('P', 15), ('R', 1), ('S', 15)] - sage: T = G.spqr_tree(algorithm="cleave") # needs sage.numerical.mip + sage: T = G.spqr_tree(algorithm='cleave') # needs sage.numerical.mip sage: sorted(Counter(u[0] for u in T).items()) # needs sage.numerical.mip [('P', 15), ('R', 1), ('S', 15)] sage: for u,v in list(G.edges(labels=False, sort=False)): ....: G.add_path([u, G.add_vertex(), G.add_vertex(), v]) - sage: T = G.spqr_tree(algorithm="Hopcroft_Tarjan") + sage: T = G.spqr_tree(algorithm='Hopcroft_Tarjan') sage: sorted(Counter(u[0] for u in T).items()) [('P', 60), ('R', 1), ('S', 75)] - sage: T = G.spqr_tree(algorithm="cleave") # long time # needs sage.numerical.mip + sage: T = G.spqr_tree(algorithm='cleave') # long time # needs sage.numerical.mip sage: sorted(Counter(u[0] for u in T).items()) # long time # needs sage.numerical.mip [('P', 60), ('R', 1), ('S', 75)] @@ -2436,7 +2435,7 @@ def spqr_tree(G, algorithm="Hopcroft_Tarjan", solver=None, verbose=0, ... ValueError: graph is not biconnected - sage: spqr_tree(Graph(), algorithm="easy") + sage: spqr_tree(Graph(), algorithm='easy') Traceback (most recent call last): ... NotImplementedError: SPQR tree algorithm 'easy' is not implemented @@ -2605,7 +2604,7 @@ def spqr_tree_to_graph(T): INPUT: - - ``T`` -- a SPQR tree as returned by :meth:`spqr_tree`. + - ``T`` -- a SPQR tree as returned by :meth:`spqr_tree` OUTPUT: a (multi) graph @@ -2770,7 +2769,7 @@ cdef _LinkedList_concatenate(_LinkedList * lst1, _LinkedList * lst2): cdef str _LinkedList_to_string(_LinkedList * ll): """ - Return a string representation of self. + Return a string representation of ``self``. """ cdef _LinkedListNode * temp = ll.head cdef list s = [] @@ -2788,9 +2787,9 @@ cdef class _Component: This class is used to store a connected component. It contains: - ``edge_list`` -- list of edges belonging to the component, - stored as a :class:`_LinkedList`. + stored as a :class:`_LinkedList` - - ``component_type`` -- the type of the component. + - ``component_type`` -- the type of the component - 0 if bond. - 1 if polygon. @@ -2802,9 +2801,9 @@ cdef class _Component: INPUT: - - ``edge_list`` -- list of edges to be added to the component. + - ``edge_list`` -- list of edges to be added to the component - - `type_c` -- type of the component (0, 1, or 2). + - ``type_c`` -- type of the component (0, 1, or 2) TESTS:: @@ -2899,18 +2898,18 @@ cdef class TriconnectivitySPQR: them. A node of a SPQR-tree, and the graph associated with it, can be one of the following four types: - - ``"S"`` -- the associated graph is a cycle with at least three vertices. - ``"S"`` stands for ``series`` and is also called a ``polygon``. + - ``'S'`` -- the associated graph is a cycle with at least three vertices + ``'S'`` stands for ``series`` and is also called a ``polygon`` - - ``"P"`` -- the associated graph is a dipole graph, a multigraph with two - vertices and three or more edges. ``"P"`` stands for ``parallel`` and the + - ``'P'`` -- the associated graph is a dipole graph, a multigraph with two + vertices and three or more edges. ``'P'`` stands for ``parallel`` and the node is called a ``bond``. - - ``"Q"`` -- the associated graph has a single real edge. This trivial case + - ``'Q'`` -- the associated graph has a single real edge. This trivial case is necessary to handle the graph that has only one edge. - - ``"R"`` -- the associated graph is a 3-vertex-connected graph that is not - a cycle or dipole. ``"R"`` stands for ``rigid``. + - ``'R'`` -- the associated graph is a 3-vertex-connected graph that is not + a cycle or dipole. ``'R'`` stands for ``rigid``. The edges of the tree indicate the 2-vertex cuts of the graph. @@ -4227,17 +4226,17 @@ cdef class TriconnectivitySPQR: separating them. A node of a SPQR-tree, and the graph associated with it, can be one of the following four types: - - ``"S"`` -- the associated graph is a cycle with at least three vertices. - ``"S"`` stands for ``series``. + - ``'S'`` -- the associated graph is a cycle with at least three vertices. + ``'S'`` stands for ``series``. - - ``"P"`` -- the associated graph is a dipole graph, a multigraph with - two vertices and three or more edges. ``"P"`` stands for ``parallel``. + - ``'P'`` -- the associated graph is a dipole graph, a multigraph with + two vertices and three or more edges. ``'P'`` stands for ``parallel``. - - ``"Q"`` -- the associated graph has a single real edge. This trivial + - ``'Q'`` -- the associated graph has a single real edge. This trivial case is necessary to handle the graph that has only one edge. - - ``"R"`` -- the associated graph is a 3-connected graph that is not a - cycle or dipole. ``"R"`` stands for ``rigid``. + - ``'R'`` -- the associated graph is a 3-connected graph that is not a + cycle or dipole. ``'R'`` stands for ``rigid``. The edges of the tree indicate the 2-vertex cuts of the graph. diff --git a/src/sage/graphs/convexity_properties.pyx b/src/sage/graphs/convexity_properties.pyx index d36124fc31d..a51c3db0102 100644 --- a/src/sage/graphs/convexity_properties.pyx +++ b/src/sage/graphs/convexity_properties.pyx @@ -142,7 +142,7 @@ cdef class ConvexityProperties: def __init__(self, G): r""" - Constructor + Constructor. EXAMPLES:: @@ -215,7 +215,7 @@ cdef class ConvexityProperties: def __dealloc__(self): r""" - Destructor + Destructor. EXAMPLES:: @@ -223,13 +223,12 @@ cdef class ConvexityProperties: sage: g = graphs.PetersenGraph() sage: ConvexityProperties(g) - """ binary_matrix_free(self._cache_hull_pairs) cdef list _vertices_to_integers(self, vertices): r""" - Converts a list of vertices to a list of integers with the cached data. + Convert a list of vertices to a list of integers with the cached data. """ return [self._dict_vertices_to_integers[v] for v in vertices] @@ -296,7 +295,7 @@ cdef class ConvexityProperties: INPUT: - * ``vertices`` -- A list of vertices. + - ``vertices`` -- list of vertices EXAMPLES:: @@ -352,11 +351,11 @@ cdef class ConvexityProperties: INPUT: - * ``value_only`` -- boolean (default: ``True``); whether to return only + - ``value_only`` -- boolean (default: ``True``); whether to return only the hull number (default) or a minimum set whose convex hull is the whole graph - * ``verbose`` -- boolean (default: ``False``); whether to display + - ``verbose`` -- boolean (default: ``False``); whether to display information on the LP **COMPLEXITY:** diff --git a/src/sage/graphs/digraph.py b/src/sage/graphs/digraph.py index 1b650b73a1b..2454834bd51 100644 --- a/src/sage/graphs/digraph.py +++ b/src/sage/graphs/digraph.py @@ -262,7 +262,7 @@ class DiGraph(GenericGraph): `__ digraph, or `igraph `__ digraph. - - ``pos`` -- dict (default: ``None``); a positioning dictionary. For + - ``pos`` -- dictionary (default: ``None``); a positioning dictionary. For example, the spring layout from NetworkX for the 5-cycle is:: {0: [-0.91679746, 0.88169588], @@ -272,7 +272,7 @@ class DiGraph(GenericGraph): 4: [-1.125 ,-0.50118505]} - ``name`` -- string (default: ``None``); gives the graph a name (e.g., - name="complete") + name='complete') - ``loops`` -- boolean (default: ``None``); whether to allow loops (ignored if data is an instance of the DiGraph class) @@ -286,24 +286,24 @@ class DiGraph(GenericGraph): - ``format`` -- string (default: ``None``); if set to ``None``, :class:`DiGraph` tries to guess input's format. To avoid this possibly time-consuming step, one of the following values can be specified (see - description above): ``"int"``, ``"dig6"``, ``"rule"``, - ``"list_of_edges"``, ``"dict_of_lists"``, ``"dict_of_dicts"``, - ``"adjacency_matrix"``, ``"weighted_adjacency_matrix"``, - ``"incidence_matrix"``, ``"NX"``, ``"igraph"``. + description above): ``'int'``, ``'dig6'``, ``'rule'``, + ``'list_of_edges'``, ``'dict_of_lists'``, ``'dict_of_dicts'``, + ``'adjacency_matrix'``, ``'weighted_adjacency_matrix'``, + ``'incidence_matrix'``, ``"NX"``, ``'igraph'``. - ``sparse`` -- boolean (default: ``True``); ``sparse=True`` is an alias for ``data_structure="sparse"``, and ``sparse=False`` is an alias for ``data_structure="dense"`` - - ``data_structure`` -- string (default: ``"sparse"``); one of the following + - ``data_structure`` -- string (default: ``'sparse'``); one of the following (for more information, see :mod:`~sage.graphs.base.overview`): - * ``"dense"`` -- selects the :mod:`~sage.graphs.base.dense_graph` backend + * ``'dense'`` -- selects the :mod:`~sage.graphs.base.dense_graph` backend - * ``"sparse"`` -- selects the :mod:`~sage.graphs.base.sparse_graph` + * ``'sparse'`` -- selects the :mod:`~sage.graphs.base.sparse_graph` backend - * ``"static_sparse"`` -- selects the + * ``'static_sparse'`` -- selects the :mod:`~sage.graphs.base.static_sparse_backend` (this backend is faster than the sparse backend and smaller in memory, and it is immutable, so that the resulting graphs can be used as dictionary keys). @@ -482,8 +482,8 @@ class DiGraph(GenericGraph): sage: import networkx sage: g = networkx.DiGraph({0:[1,2,3], 2:[4]}) sage: G = DiGraph(g) - sage: G_imm = DiGraph(G, data_structure="static_sparse") - sage: H_imm = DiGraph(G, data_structure="static_sparse") + sage: G_imm = DiGraph(G, data_structure='static_sparse') + sage: H_imm = DiGraph(G, data_structure='static_sparse') sage: H_imm is G_imm False sage: H_imm == G_imm == G @@ -521,7 +521,7 @@ class DiGraph(GenericGraph): _directed = True def __init__(self, data=None, pos=None, loops=None, format=None, - weighted=None, data_structure="sparse", + weighted=None, data_structure='sparse', vertex_labels=True, name=None, multiedges=None, convert_empty_dict_labels_to_None=None, sparse=True, immutable=False, hash_labels=None): @@ -581,7 +581,7 @@ def __init__(self, data=None, pos=None, loops=None, format=None, ....: 3:{5:4},4:{5:1,6:5},5:{4:1,6:7,5:1}} sage: grafo3 = DiGraph(B, weighted=True) sage: matad = grafo3.weighted_adjacency_matrix() # needs sage.modules - sage: grafo4 = DiGraph(matad, format="adjacency_matrix", weighted=True) # needs sage.modules + sage: grafo4 = DiGraph(matad, format='adjacency_matrix', weighted=True) # needs sage.modules sage: grafo4.shortest_path(0, 6, by_weight=True) # needs sage.modules [0, 1, 2, 5, 4, 6] @@ -613,7 +613,7 @@ def __init__(self, data=None, pos=None, loops=None, format=None, Unknown input format:: - sage: DiGraph(4, format="HeyHeyHey") + sage: DiGraph(4, format='HeyHeyHey') Traceback (most recent call last): ... ValueError: unknown input format 'HeyHeyHey' @@ -937,7 +937,7 @@ def is_directed_acyclic(self, certificate=False): OUTPUT: - * When ``certificate=False``, returns a boolean value. + * When ``certificate=False``, returns a boolean value * When ``certificate=True``: @@ -1025,13 +1025,13 @@ def to_undirected(self, data_structure=None, sparse=None): INPUT: - - ``data_structure`` -- string (default: ``None``); one of - ``"sparse"``, ``"static_sparse"``, or ``"dense"``. See the - documentation of :class:`Graph` or :class:`DiGraph`. + - ``data_structure`` -- string (default: ``None``); one of + ``'sparse'``, ``'static_sparse'``, or ``'dense'``. See the + documentation of :class:`Graph` or :class:`DiGraph`. - - ``sparse`` -- boolean (default: ``None``); ``sparse=True`` is an - alias for ``data_structure="sparse"``, and ``sparse=False`` is an - alias for ``data_structure="dense"``. + - ``sparse`` -- boolean (default: ``None``); ``sparse=True`` is an + alias for ``data_structure="sparse"``, and ``sparse=False`` is an + alias for ``data_structure="dense"``. EXAMPLES:: @@ -1057,7 +1057,6 @@ def to_undirected(self, data_structure=None, sparse=None): {0: 'foo', 1: None, 2: None} sage: G.get_vertices() {0: 'foo', 1: None, 2: None} - """ if sparse is not None: if data_structure is not None: @@ -1132,7 +1131,7 @@ def incoming_edges(self, vertices, labels=True): - ``vertices`` -- a vertex or a list of vertices - ``labels`` -- boolean (default: ``True``); whether to return edges as - pairs of vertices, or as triples containing the labels. + pairs of vertices, or as triples containing the labels EXAMPLES:: @@ -1151,7 +1150,7 @@ def outgoing_edge_iterator(self, vertices, labels=True): - ``vertices`` -- a vertex or a list of vertices - ``labels`` -- boolean (default: ``True``); whether to return edges as - pairs of vertices, or as triples containing the labels. + pairs of vertices, or as triples containing the labels EXAMPLES:: @@ -1179,7 +1178,7 @@ def outgoing_edges(self, vertices, labels=True): - ``vertices`` -- a vertex or a list of vertices - ``labels`` -- boolean (default: ``True``); whether to return edges as - pairs of vertices, or as triples containing the labels. + pairs of vertices, or as triples containing the labels EXAMPLES:: @@ -1443,9 +1442,7 @@ def sources(self): r""" Return a list of sources of the digraph. - OUTPUT: - - - list of the vertices of the digraph that have no edges going into them + OUTPUT: list of the vertices of the digraph that have no edges going into them EXAMPLES:: @@ -1462,9 +1459,7 @@ def sinks(self): """ Return a list of sinks of the digraph. - OUTPUT: - - - list of the vertices of the digraph that have no edges beginning at them + OUTPUT: list of the vertices of the digraph that have no edges beginning at them EXAMPLES:: @@ -1539,7 +1534,7 @@ def feedback_edge_set(self, constraint_generation=True, value_only=False, use constraint generation when solving the Mixed Integer Linear Program. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1547,7 +1542,7 @@ def feedback_edge_set(self, constraint_generation=True, value_only=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -1909,7 +1904,7 @@ def reverse_edge(self, u, v=None, label=None, inplace=True, multiedges=None): EXAMPLES: - If ``inplace`` is ``True`` (default value), ``self`` is modified:: + If ``inplace`` is ``True`` (default), ``self`` is modified:: sage: D = DiGraph([(0, 1 ,2)]) sage: D.reverse_edge(0, 1) @@ -2096,11 +2091,11 @@ def reverse_edges(self, edges, inplace=True, multiedges=None): INPUT: - - ``edges`` -- a list of edges in the DiGraph. + - ``edges`` -- list of edges in the DiGraph - ``inplace`` -- boolean (default: ``True``); if ``False``, a new digraph is created and returned as output, otherwise ``self`` is - modified. + modified - ``multiedges`` -- boolean (default: ``None``); if ``True``, input graph will be forced to allow parallel edges when necessary (for more @@ -2108,11 +2103,11 @@ def reverse_edges(self, edges, inplace=True, multiedges=None): .. SEEALSO:: - :meth:`~DiGraph.reverse_edge` -- Reverses a single edge. + :meth:`~DiGraph.reverse_edge` -- reverses a single edge EXAMPLES: - If ``inplace`` is ``True`` (default value), ``self`` is modified:: + If ``inplace`` is ``True`` (default), ``self`` is modified:: sage: D = DiGraph({ 0: [1, 1, 3], 2: [3, 3], 4: [1, 5]}, multiedges=true) sage: D.reverse_edges([[0, 1], [0, 3]]) @@ -2214,16 +2209,16 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, INPUT: - ``v`` -- either a single vertex or a list of vertices. If it is not - specified, then it is taken to be all vertices. + specified, then it is taken to be all vertices - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); one of the following algorithms: - ``'BFS'`` -- the computation is done through a BFS centered on each - vertex successively. Works only if ``by_weight==False``. + vertex successively. Works only if ``by_weight==False`` - ``'Floyd-Warshall-Cython'`` -- a Cython implementation of the Floyd-Warshall algorithm. Works only if ``by_weight==False`` and @@ -2239,7 +2234,7 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, allowed. - ``'Dijkstra_Boost'`` -- the Dijkstra algorithm, implemented in Boost - (works only with positive weights). + (works only with positive weights) - ``'Johnson_Boost'`` -- the Johnson algorithm, implemented in Boost (works also with negative weights, if there is no negative @@ -2247,7 +2242,7 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, vertices of ``self``. - ``'From_Dictionary'`` -- uses the (already computed) distances, that - are provided by input variable ``dist_dict``. + are provided by input variable ``dist_dict`` - ``None`` (default): Sage chooses the best algorithm: ``'From_Dictionary'`` if ``dist_dict`` is not None, ``'BFS'`` for @@ -2263,11 +2258,11 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check that the ``weight_function`` outputs a number for each edge - - ``dist_dict`` -- a dictionary (default: ``None``); a dict of dicts of + - ``dist_dict`` -- dictionary (default: ``None``); a dict of dicts of distances (used only if ``algorithm=='From_Dictionary'``) - ``with_labels`` -- boolean (default: ``False``); whether to return a - list or a dictionary keyed by vertices. + list or a dictionary keyed by vertices EXAMPLES:: @@ -2429,7 +2424,7 @@ def radius(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); see method :meth:`eccentricity` for the list of available algorithms @@ -2498,7 +2493,7 @@ def diameter(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); one of the following algorithms: @@ -2668,7 +2663,7 @@ def center(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); see method :meth:`eccentricity` for the list of available algorithms @@ -2739,7 +2734,7 @@ def periphery(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); see method :meth:`eccentricity` for the list of available algorithms @@ -2813,20 +2808,18 @@ def _all_cycles_iterator_vertex(self, vertex, starting_vertices=None, simple=Fal (e.g. ``['a', 'b', 'c', 'a']`` and ``['b', 'c', 'a', 'b']``). Otherwise, all cycles are enumerated. - - ``max_length`` -- non negative integer (default: ``None``); the + - ``max_length`` -- nonnegative integer (default: ``None``); the maximum length of the enumerated paths. If set to ``None``, then all lengths are allowed. - ``trivial`` -- boolean (default: ``False``); if set to ``True``, then - the empty paths are also enumerated. + the empty paths are also enumerated - ``remove_acyclic_edges`` -- boolean (default: ``True``); whether acyclic edges must be removed from the graph. Used to avoid recomputing it for each vertex - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -2933,16 +2926,14 @@ def all_cycles_iterator(self, starting_vertices=None, simple=False, (e.g. ``['a', 'b', 'c', 'a']`` and ``['b', 'c', 'a', 'b']``). Otherwise, all cycles are enumerated. - - ``max_length`` -- non negative integer (default: ``None``); the + - ``max_length`` -- nonnegative integer (default: ``None``); the maximum length of the enumerated paths. If set to ``None``, then all lengths are allowed. - ``trivial`` -- boolean (default: ``False``); if set to ``True``, then - the empty paths are also enumerated. + the empty paths are also enumerated - OUTPUT: - - iterator + OUTPUT: iterator .. SEEALSO:: @@ -3080,16 +3071,14 @@ def all_simple_cycles(self, starting_vertices=None, rooted=False, (e.g. ``['a', 'b', 'c', 'a']`` and ``['b', 'c', 'a', 'b']``). Otherwise, all cycles are enumerated. - - ``max_length`` -- non negative integer (default: ``None``); the + - ``max_length`` -- nonnegative integer (default: ``None``); the maximum length of the enumerated paths. If set to ``None``, then all lengths are allowed. - ``trivial`` -- boolean (default: ``False``); if set to ``True``, then - the empty paths are also enumerated. - - OUTPUT: + the empty paths are also enumerated - list + OUTPUT: list .. NOTE:: @@ -3220,7 +3209,6 @@ def path_semigroup(self): Partial semigroup formed by the directed paths of Multi-digraph on 3 vertices sage: list(F) # needs sage.libs.flint [e_1, e_2, e_3, a, c, b, a*b, c*b] - """ from sage.quivers.path_semigroup import PathSemigroup return PathSemigroup(self) @@ -3244,11 +3232,11 @@ def auslander_reiten_quiver(self): # Directed Acyclic Graphs (DAGs) - def topological_sort(self, implementation="default"): + def topological_sort(self, implementation='default'): """ Return a topological sort of the digraph if it is acyclic. - If the digraph contains a directed cycle, a :class:`TypeError` + If the digraph contains a directed cycle, a :exc:`TypeError` is raised. As topological sorts are not necessarily unique, different implementations may yield different results. @@ -3259,15 +3247,15 @@ def topological_sort(self, implementation="default"): INPUT: - - ``implementation`` -- string (default: ``"default"``); either use the + - ``implementation`` -- string (default: ``'default'``); either use the default Cython implementation, or the default NetworkX library (``implementation = "NetworkX"``) .. SEEALSO:: - - :meth:`is_directed_acyclic` -- Tests whether a directed graph is - acyclic (can also join a certificate -- a topological sort or a - circuit in the graph). + - :meth:`is_directed_acyclic` -- tests whether a directed graph is + acyclic (can also join a certificate; a topological sort or a + circuit in the graph) EXAMPLES:: @@ -3330,7 +3318,7 @@ def topological_sort_generator(self): Return an iterator over all topological sorts of the digraph if it is acyclic. - If the digraph contains a directed cycle, a :class:`TypeError` + If the digraph contains a directed cycle, a :exc:`TypeError` is raised. A topological sort is an ordering of the vertices of the digraph such @@ -3371,7 +3359,7 @@ def topological_sort_generator(self): # Visualization - def layout_acyclic(self, rankdir="up", **options): + def layout_acyclic(self, rankdir='up', **options): """ Return a ranked layout so that all edges point upward. @@ -3420,7 +3408,6 @@ def layout_acyclic(self, rankdir="up", **options): sage: pos = H.layout_acyclic(rankdir='left') sage: pos[1][0] < pos[0][0] - .5 True - """ if have_dot2tex(): return self.layout_graphviz(rankdir=rankdir, **options) @@ -3501,9 +3488,7 @@ def level_sets(self): r""" Return the level set decomposition of the digraph. - OUTPUT: - - - a list of non empty lists of vertices of this graph + OUTPUT: list of non empty lists of vertices of this graph The level set decomposition of the digraph is a list `l` such that the level `l[i]` contains all the vertices having all their predecessors in @@ -3710,7 +3695,7 @@ def flow_polytope(self, edges=None, ends=None, backend=None): ``(1, 3, None)``, then ``(1, 3)`` will not do! - ``ends`` -- (default: ``(self.sources(), self.sinks())``) a - pair `(S, T)` of an iterable `S` and an iterable `T`. + pair `(S, T)` of an iterable `S` and an iterable `T` - ``backend`` -- string or ``None`` (default); the backend to use; see :meth:`sage.geometry.polyhedron.constructor.Polyhedron` @@ -3989,20 +3974,18 @@ def out_branchings(self, source, spanning=True): contains all vertices of the digraph. If no spanning out branching rooted at ``source`` exist, raises - ValueError or return non spanning out branching rooted at ``source``, - depending on the value of ``spanning``. + :exc:`ValueError` or return non spanning out branching rooted at + ``source``, depending on the value of ``spanning``. INPUT: - - ``source`` -- vertex used as the source for all out branchings. + - ``source`` -- vertex used as the source for all out branchings - ``spanning`` -- boolean (default: ``True``); if ``False`` return maximum out branching from ``source``. Otherwise, return spanning out branching if exists. - OUTPUT: - - An iterator over the out branchings rooted in the given source. + OUTPUT: an iterator over the out branchings rooted in the given source .. SEEALSO:: @@ -4100,7 +4083,7 @@ def _rec_out_branchings(depth): This function makes use of the following to keep track of partial out branchings: - - ``list_edges`` -- list of edges in self. + - ``list_edges`` -- list of edges in self - ``list_merged_edges`` -- list of edges that are currently merged - ``graph`` -- a copy of self where edges have an appropriate label """ @@ -4163,7 +4146,7 @@ def _rec_out_branchings(depth): def _singleton_out_branching(): r""" - Returns a DiGraph containing only ``source`` and no edges. + Return a DiGraph containing only ``source`` and no edges. """ D = DiGraph() D.add_vertex(source) @@ -4207,20 +4190,18 @@ def in_branchings(self, source, spanning=True): contains all vertices of the digraph. If no spanning in branching rooted at ``source`` exist, raises - ValueError or return non spanning in branching rooted at ``source``, - depending on the value of ``spanning``. + :exc:`ValueError` or return non spanning in branching rooted at + ``source``, depending on the value of ``spanning``. INPUT: - - ``source`` -- vertex used as the source for all in branchings. + - ``source`` -- vertex used as the source for all in branchings - ``spanning`` -- boolean (default: ``True``); if ``False`` return maximum in branching to ``source``. Otherwise, return spanning in branching if exists. - OUTPUT: - - An iterator over the in branchings rooted in the given source. + OUTPUT: an iterator over the in branchings rooted in the given source .. SEEALSO:: @@ -4318,7 +4299,7 @@ def _rec_in_branchings(depth): This function makes use of the following to keep track of partial in branchings: - - ``list_edges`` -- list of edges in self. + - ``list_edges`` -- list of edges in self - ``list_merged_edges`` -- list of edges that are currently merged - ``graph`` -- a copy of self where edges have an appropriate label """ @@ -4381,7 +4362,7 @@ def _rec_in_branchings(depth): def _singleton_in_branching(): r""" - Returns a DiGraph containing only ``source`` and no edges. + Return a DiGraph containing only ``source`` and no edges. """ D = DiGraph() D.add_vertex(source) diff --git a/src/sage/graphs/digraph_generators.py b/src/sage/graphs/digraph_generators.py index 7ae9fe248fa..02590ac8f7c 100644 --- a/src/sage/graphs/digraph_generators.py +++ b/src/sage/graphs/digraph_generators.py @@ -118,7 +118,7 @@ class DiGraphGenerators: INPUT: - ``vertices`` -- natural number or ``None`` to infinitely generate bigger - and bigger digraphs. + and bigger digraphs - ``property`` -- any property to be tested on digraphs before generation @@ -214,7 +214,7 @@ def ButterflyGraph(self, n, vertices='strings'): INPUT: - - ``n`` -- a non negative integer; the dimension of the butterfly graph + - ``n`` -- nonnegative integer; the dimension of the butterfly graph - ``vertices`` -- string (default: ``'strings'``); specifies whether the vertices are zero-one strings (default) or tuples over GF(2) @@ -340,7 +340,7 @@ def Path(self, n): sage: g.automorphism_group().cardinality() # needs sage.groups 1 """ - g = DiGraph(n, name="Path") + g = DiGraph(n, name='Path') if n: g.add_path(list(range(n))) @@ -357,7 +357,7 @@ def StronglyRegular(self, n): INPUT: - - ``n`` -- integer, the number of vertices of the digraph. + - ``n`` -- integer; the number of vertices of the digraph .. SEEALSO:: @@ -385,7 +385,6 @@ def StronglyRegular(self, n): Traceback (most recent call last): ... ValueError: strongly regular digraph with 73 vertices not yet implemented - """ from sage.combinat.matrices.hadamard_matrix import skew_hadamard_matrix from sage.matrix.constructor import ones_matrix, identity_matrix @@ -635,7 +634,7 @@ def tournaments_nauty(self, n, yield G - def nauty_directg(self, graphs, options="", debug=False): + def nauty_directg(self, graphs, options='', debug=False): r""" Return an iterator yielding digraphs using nauty's ``directg`` program. @@ -651,7 +650,7 @@ def nauty_directg(self, graphs, options="", debug=False): :class:`Graph`. The graph6 string of these graphs is used as an input for ``directg``. - - ``options`` -- a string passed to ``directg`` as if it was run at + - ``options`` -- string passed to ``directg`` as if it was run at a system command line. Available options from ``directg --help``:: -e | -e: specify a value or range of the total number of arcs @@ -665,7 +664,7 @@ def nauty_directg(self, graphs, options="", debug=False): parts. Splitting is done per input graph independently. - ``debug`` -- boolean (default: ``False``); if ``True`` ``directg`` - standard error and standard output are displayed. + standard error and standard output are displayed EXAMPLES:: @@ -677,7 +676,7 @@ def nauty_directg(self, graphs, options="", debug=False): Digraph on 3 vertices sage: dgs[0]._bit_vector() '001001000' - sage: len(list(digraphs.nauty_directg(graphs.PetersenGraph(), options="-o"))) + sage: len(list(digraphs.nauty_directg(graphs.PetersenGraph(), options='-o'))) 324 Generate non-isomorphic acyclic orientations:: @@ -701,7 +700,7 @@ def nauty_directg(self, graphs, options="", debug=False): ... ValueError: directg output options [-u|-T|-G] are not allowed sage: next(digraphs.nauty_directg(graphs.nauty_geng("-c 3"), - ....: options="-o", debug=True)) + ....: options='-o', debug=True)) &BH? &BGO &B?o @@ -818,7 +817,7 @@ def Circuit(self, n): sage: len(circuit.strongly_connected_components()) == 1 True """ - g = DiGraph(n, name="Circuit") + g = DiGraph(n, name='Circuit') if n == 1: g.allow_loops(True) @@ -897,7 +896,7 @@ def DeBruijn(self, k, n, vertices='strings'): of the resulting digraph is the cardinality of the set of letters. - ``n`` -- integer; length of words in the De Bruijn digraph when - ``vertices == 'strings'``, and also the diameter of the digraph. + ``vertices == 'strings'``, and also the diameter of the digraph - ``vertices`` -- string (default: ``'strings'``); whether the vertices are words over an alphabet (default) or integers @@ -1150,7 +1149,6 @@ def Kautz(self, k, D, vertices='strings'): are words over an alphabet (default) or integers (``vertices='strings'``) - EXAMPLES:: sage: # needs sage.combinat @@ -1278,7 +1276,7 @@ def RandomDirectedAcyclicGraph(self, n, p, weight_max=None): - ``p`` -- probability of an edge - - ``weight_max`` -- (default: ``None``); by default, the returned DAG is + - ``weight_max`` -- (default: ``None``) by default, the returned DAG is unweighted. When ``weight_max`` is set to a positive integer, edges are assigned a random integer weight between ``1`` and ``weight_max``. diff --git a/src/sage/graphs/distances_all_pairs.pyx b/src/sage/graphs/distances_all_pairs.pyx index 249b4c4e92d..63ad747ebd9 100644 --- a/src/sage/graphs/distances_all_pairs.pyx +++ b/src/sage/graphs/distances_all_pairs.pyx @@ -413,7 +413,7 @@ def shortest_path_all_pairs(G): cdef unsigned short * c_distances_all_pairs(G, vertex_list=None) noexcept: r""" - Returns the matrix of distances in G. + Return the matrix of distances in G. The matrix `M` returned is of length `n^2`, and the distance between vertices `u` and `v` is `M[u,v]`. The integer corresponding to a vertex is @@ -492,7 +492,7 @@ def distances_all_pairs(G): def is_distance_regular(G, parameters=False): r""" - Test if the graph is distance-regular + Test if the graph is distance-regular. A graph `G` is distance-regular if for any integers `j,k` the value of `|\{x:d_G(x,u)=j,x\in V(G)\} \cap \{y:d_G(y,v)=j,y\in V(G)\}|` is constant @@ -546,7 +546,6 @@ def is_distance_regular(G, parameters=False): ([1, None], [None, 1]) sage: graphs.Tutte12Cage().is_distance_regular(parameters=True) # needs networkx ([3, 2, 2, 2, 2, 2, None], [None, 1, 1, 1, 1, 1, 3]) - """ cdef int i, u, v, d, b, c, k cdef int n = G.order() @@ -939,28 +938,28 @@ cdef uint32_t * c_eccentricity_DHV(short_digraph sd) except NULL: return ecc_upper_bound -def eccentricity(G, algorithm="standard", vertex_list=None): +def eccentricity(G, algorithm='standard', vertex_list=None): r""" Return the vector of eccentricities in G. The array returned is of length `n`, and its `i`-th component is the - eccentricity of the ith vertex in ``G.vertices(sort=True)``. + eccentricity of the `i`-th vertex in ``G.vertices(sort=True)``. INPUT: - - ``G`` -- a Graph or a DiGraph. + - ``G`` -- a Graph or a DiGraph - ``algorithm`` -- string (default: ``'standard'``); name of the method used - to compute the eccentricity of the vertices. + to compute the eccentricity of the vertices - - ``'standard'`` -- Computes eccentricity by performing a BFS from each - vertex. + - ``'standard'`` -- computes eccentricity by performing a BFS from each + vertex - - ``'bounds'`` -- Computes eccentricity using the fast algorithm proposed - in [TK2013]_ for undirected graphs. + - ``'bounds'`` -- computes eccentricity using the fast algorithm proposed + in [TK2013]_ for undirected graphs - - ``'DHV'`` -- Computes all eccentricities of undirected graph using the - algorithm proposed in [Dragan2018]_. + - ``'DHV'`` -- computes all eccentricities of undirected graph using the + algorithm proposed in [Dragan2018]_ - ``vertex_list`` -- list (default: ``None``); a list of `n` vertices specifying a mapping from `(0, \ldots, n-1)` to vertex labels in `G`. When @@ -1166,7 +1165,7 @@ cdef tuple diameter_lower_bound_2Dsweep(short_digraph g, - ``g`` -- a short_digraph - - ``rev_g`` -- a copy of `g` with edges reversed. + - ``rev_g`` -- a copy of `g` with edges reversed - ``source`` -- starting node of the forward and backward BFS @@ -1279,7 +1278,6 @@ cdef tuple diameter_lower_bound_multi_sweep(short_digraph g, - ``g`` -- a short_digraph - ``source`` -- starting node of the BFS - """ # The while loop below might not be entered so we have to make sure that # s and d which are returned are initialized. @@ -1351,7 +1349,6 @@ cdef uint32_t diameter_iFUB(short_digraph g, - ``g`` -- a short_digraph - ``source`` -- starting node of the first BFS - """ cdef uint32_t i, LB, m cdef uint32_t n = g.n @@ -1682,11 +1679,11 @@ def diameter(G, algorithm=None, source=None): - ``algorithm`` -- string (default: ``None``); specifies the algorithm to use among: - - ``'standard'`` -- Computes the diameter of the input (di)graph as the + - ``'standard'`` -- computes the diameter of the input (di)graph as the largest eccentricity of its vertices. This is the classical algorithm with time complexity in `O(nm)`. - - ``'2sweep'`` -- Computes a lower bound on the diameter of an + - ``'2sweep'`` -- computes a lower bound on the diameter of an unweighted undirected graph using 2 BFS, as proposed in [MLH2008]_. It first selects a vertex `v` that is at largest distance from an initial vertex source using BFS. Then it performs a second BFS from `v`. The @@ -1694,15 +1691,15 @@ def diameter(G, algorithm=None, source=None): of `G`. The time complexity of this algorithm is linear in the size of `G`. - - ``'2Dsweep'`` -- Computes lower bound on the diameter of an unweighted + - ``'2Dsweep'`` -- computes lower bound on the diameter of an unweighted directed graph using directed version of ``2sweep`` as proposed in [Broder2000]_. If the digraph is not strongly connected, the returned value is infinity. - - ``'DHV'`` -- Computes diameter of unweighted undirected graph using the - algorithm proposed in [Dragan2018]_. + - ``'DHV'`` -- computes diameter of unweighted undirected graph using the + algorithm proposed in [Dragan2018]_ - - ``'multi-sweep'`` -- Computes a lower bound on the diameter of an + - ``'multi-sweep'`` -- computes a lower bound on the diameter of an unweighted undirected graph using several iterations of the ``2sweep`` algorithms [CGHLM2013]_. Roughly, it first uses ``2sweep`` to identify two vertices `u` and `v` that are far apart. Then it selects a vertex @@ -1712,7 +1709,7 @@ def diameter(G, algorithm=None, source=None): This process is repeated as long as the lower bound on the diameter is improved. - - ``'iFUB'`` -- The iFUB (iterative Fringe Upper Bound) algorithm, + - ``'iFUB'`` -- the iFUB (iterative Fringe Upper Bound) algorithm, proposed in [CGILM2010]_, computes the exact value of the diameter of an unweighted undirected graph. It is based on the following observation: @@ -1740,7 +1737,7 @@ def diameter(G, algorithm=None, source=None): by the remark above. The worst case time complexity of the iFUB algorithm is `O(nm)`, but it can be very fast in practice. - - ``'DiFUB'`` -- The directed version of iFUB (iterative Fringe Upper + - ``'DiFUB'`` -- the directed version of iFUB (iterative Fringe Upper Bound) algorithm. See the code's documentation and [CGLM2012]_ for more details. If the digraph is not strongly connected, the returned value is infinity. @@ -2117,7 +2114,7 @@ cdef uint64_t c_szeged_index_low_memory(short_digraph sd) noexcept: EXAMPLES:: - sage: graphs.CycleGraph(4).szeged_index(algorithm="low") + sage: graphs.CycleGraph(4).szeged_index(algorithm='low') 16 """ cdef size_t n = sd.n @@ -2213,7 +2210,7 @@ cdef uint64_t c_szeged_index_high_memory(short_digraph sd) noexcept: EXAMPLES:: - sage: graphs.CycleGraph(4).szeged_index(algorithm="high") + sage: graphs.CycleGraph(4).szeged_index(algorithm='high') 16 """ cdef int n = sd.n @@ -2272,16 +2269,16 @@ def szeged_index(G, algorithm=None): - ``algorithm`` -- string (default: ``None``); algorithm to use among: - - ``"low"`` -- algorithm with time complexity in `O(nm)` and space + - ``'low'`` -- algorithm with time complexity in `O(nm)` and space complexity in `O(m)`. This implementation is currently valid only for simple (without loops or multiple edges) connected graphs. - - ``"high"`` -- algorithm with time complexity in `O(nm)` and space + - ``'high'`` -- algorithm with time complexity in `O(nm)` and space complexity in `O(n^2)`. It cannot be used on graphs with more than `65536 = 2^{16}` vertices. - By default (``None``), the ``"low"`` algorithm is used for graphs and the - ``"high"`` algorithm for digraphs. + By default (``None``), the ``'low'`` algorithm is used for graphs and the + ``'high'`` algorithm for digraphs. .. NOTE:: As the graph is converted to a short_digraph, the complexity for the @@ -2339,22 +2336,22 @@ def szeged_index(G, algorithm=None): Wrong name of algorithm:: - sage: szeged_index(Graph(1), algorithm="wheel") + sage: szeged_index(Graph(1), algorithm='wheel') Traceback (most recent call last): ... ValueError: unknown algorithm 'wheel' Algorithm `"low"` is for graphs without loops or multiple edges:: - sage: szeged_index(Graph([(0, 0)], loops=True), algorithm="low") + sage: szeged_index(Graph([(0, 0)], loops=True), algorithm='low') Traceback (most recent call last): ... ValueError: the 'low' algorithm is for simple connected undirected graphs only - sage: szeged_index(Graph([(0, 1), (0, 1)], multiedges=True), algorithm="low") + sage: szeged_index(Graph([(0, 1), (0, 1)], multiedges=True), algorithm='low') Traceback (most recent call last): ... ValueError: the 'low' algorithm is for simple connected undirected graphs only - sage: szeged_index(digraphs.Circuit(3), algorithm="low") + sage: szeged_index(digraphs.Circuit(3), algorithm='low') Traceback (most recent call last): ... ValueError: the 'low' algorithm cannot be used on digraphs @@ -2644,7 +2641,7 @@ def floyd_warshall(gg, paths=True, distances=False): INPUT: - - ``gg`` -- the graph on which to work. + - ``gg`` -- the graph on which to work - ``paths`` -- boolean (default: ``True``); whether to return the dictionary of shortest paths diff --git a/src/sage/graphs/domination.py b/src/sage/graphs/domination.py index 327201202be..37c0ca5fb51 100644 --- a/src/sage/graphs/domination.py +++ b/src/sage/graphs/domination.py @@ -18,7 +18,6 @@ :meth:`~greedy_dominating_set` | Return a greedy distance-`k` dominating set of the graph. :meth:`~maximum_leaf_number` | Return the maximum leaf number of the graph. - EXAMPLES: We compute the size of a minimum dominating set of the Petersen graph:: @@ -80,11 +79,11 @@ def is_dominating(G, dom, focus=None): INPUT: - ``dom`` -- iterable of vertices of ``G``; the vertices of the supposed - dominating set. + dominating set - ``focus`` -- iterable of vertices of ``G`` (default: ``None``); if specified, this method checks instead if ``dom`` dominates the vertices in - ``focus``. + ``focus`` EXAMPLES:: @@ -117,11 +116,11 @@ def is_redundant(G, dom, focus=None): INPUT: - ``dom`` -- iterable of vertices of ``G``; where we look for redundant - vertices. + vertices - ``focus`` -- iterable of vertices of ``G`` (default: ``None``); if specified, this method checks instead whether ``dom`` has a redundant - vertex in ``focus``. + vertex in ``focus`` .. WARNING:: @@ -181,10 +180,10 @@ def private_neighbors(G, vertex, dom): INPUT: - - ``vertex`` -- a vertex of ``G``. + - ``vertex`` -- a vertex of ``G`` - ``dom`` -- iterable of vertices of ``G``; the vertices possibly stealing - private neighbors from ``vertex``. + private neighbors from ``vertex`` OUTPUT: @@ -251,7 +250,7 @@ def dominating_sets(g, k=1, independent=False, total=False, connected=False, INPUT: - - ``k`` -- a non-negative integer (default: ``1``); the domination distance + - ``k`` -- nonnegative integer (default: `1`); the domination distance - ``independent`` -- boolean (default: ``False``); when ``True``, computes minimum independent dominating sets, that is minimum dominating sets that @@ -264,7 +263,7 @@ def dominating_sets(g, k=1, independent=False, total=False, connected=False, - ``connected`` -- boolean (default: ``False``); when ``True``, computes connected dominating sets (see :wikipedia:`Connected_dominating_set`) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -272,7 +271,7 @@ def dominating_sets(g, k=1, independent=False, total=False, connected=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -379,7 +378,7 @@ def dominating_sets(g, k=1, independent=False, total=False, connected=False, sage: next(g.dominating_sets(k=-1)) Traceback (most recent call last): ... - ValueError: the domination distance must be a non-negative integer + ValueError: the domination distance must be a nonnegative integer The method is robust to vertices with incomparable labels:: @@ -394,7 +393,7 @@ def dominating_sets(g, k=1, independent=False, total=False, connected=False, yield list(g) return if k < 0: - raise ValueError("the domination distance must be a non-negative integer") + raise ValueError("the domination distance must be a nonnegative integer") from sage.numerical.mip import MixedIntegerLinearProgram from sage.numerical.mip import MIPSolverException @@ -503,7 +502,7 @@ def dominating_set(g, k=1, independent=False, total=False, connected=False, valu INPUT: - - ``k`` -- a non-negative integer (default: ``1``); the domination distance + - ``k`` -- nonnegative integer (default: `1`); the domination distance - ``independent`` -- boolean (default: ``False``); when ``True``, computes a minimum independent dominating set, that is a minimum dominating set that @@ -520,7 +519,7 @@ def dominating_set(g, k=1, independent=False, total=False, connected=False, valu cardinality of the computed dominating set, or to return its list of vertices (default) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -528,7 +527,7 @@ def dominating_set(g, k=1, independent=False, total=False, connected=False, valu :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -655,7 +654,7 @@ def _peel(G, A): - ``G`` -- a graph - - ``A`` -- a set of vertices of `G` + - ``A`` -- set of vertices of `G` OUTPUT: @@ -681,7 +680,6 @@ def _peel(G, A): (4, {4, 6, 8}), (2, {2, 4, 6, 8}), (0, {0, 2, 4, 6, 8})] - """ Acomp = set(G) Acomp.difference_update(A) # Acomp = V - A @@ -716,9 +714,7 @@ def _cand_ext_enum(G, to_dom, u_next): - ``u_next`` -- a vertex of ``G`` that dominates ``to_dom`` - OUTPUT: - - An iterator over the minimal dominating sets of ``to_dom``. + OUTPUT: an iterator over the minimal dominating sets of ``to_dom`` TESTS:: @@ -808,16 +804,16 @@ def minimal_dominating_sets(G, to_dominate=None, work_on_copy=True, k=1): INPUT: - - ``G`` -- a graph. + - ``G`` -- a graph - ``to_dominate`` -- vertex iterable or ``None`` (default: ``None``); - the set of vertices to be dominated. + the set of vertices to be dominated - ``work_on_copy`` -- boolean (default: ``True``); whether or not to work on a copy of the input graph; if set to ``False``, the input graph will be - modified (relabeled). + modified (relabeled) - - ``k`` -- a non-negative integer (default: ``1``); the domination distance + - ``k`` -- nonnegative integer (default: `1`); the domination distance OUTPUT: @@ -966,7 +962,7 @@ def minimal_dominating_sets(G, to_dominate=None, work_on_copy=True, k=1): sage: next(Graph(1).minimal_dominating_sets(k=-1)) Traceback (most recent call last): ... - ValueError: the domination distance must be a non-negative integer + ValueError: the domination distance must be a nonnegative integer Trying to dominate vertices that are not part of the graph:: @@ -996,7 +992,7 @@ def tree_search(H, plng, dom, i): - ``dom`` -- a minimal dominating set of ``plng[i][1]`` - - ``i`` -- an integer, the current position in ``plng`` + - ``i`` -- integer; the current position in ``plng`` OUTPUT: @@ -1048,7 +1044,7 @@ def tree_search(H, plng, dom, i): # end of tree-search routine if k < 0: - raise ValueError("the domination distance must be a non-negative integer") + raise ValueError("the domination distance must be a nonnegative integer") if not k: yield set(G) if to_dominate is None else set(to_dominate) return @@ -1110,7 +1106,7 @@ def greedy_dominating_set(G, k=1, vertices=None, ordering=None, return_sets=Fals - ``G`` -- a Graph - - ``k`` -- integer (default: ``1``); the domination distance to consider + - ``k`` -- integer (default: `1`); the domination distance to consider - ``vertices`` -- iterable container of vertices (default: ``None``); when specified, return a dominating set of the specified vertices only @@ -1122,9 +1118,9 @@ def greedy_dominating_set(G, k=1, vertices=None, ordering=None, return_sets=Fals the order given by ``list(G)``. Otherwise, consider the vertices in the order of iteration of ``vertices``. - - ``"degree_min"`` -- consider the vertices by increasing degree + - ``'degree_min'`` -- consider the vertices by increasing degree - - ``"degree_max"`` -- consider the vertices by decreasing degree + - ``'degree_max'`` -- consider the vertices by decreasing degree - ``return_sets`` -- boolean (default: ``False``); whether to return the vertices of the dominating set only (default), or a dictionary mapping @@ -1142,19 +1138,19 @@ def greedy_dominating_set(G, k=1, vertices=None, ordering=None, return_sets=Fals sage: G = graphs.PathGraph(5) sage: sorted(greedy_dominating_set(G, ordering=None)) [0, 2, 4] - sage: sorted(greedy_dominating_set(G, ordering="degree_min")) + sage: sorted(greedy_dominating_set(G, ordering='degree_min')) [0, 2, 4] - sage: sorted(greedy_dominating_set(G, ordering="degree_max")) + sage: sorted(greedy_dominating_set(G, ordering='degree_max')) [1, 3] sage: sorted(greedy_dominating_set(G, k=2, ordering=None)) [0, 3] - sage: sorted(greedy_dominating_set(G, k=2, ordering="degree_min")) + sage: sorted(greedy_dominating_set(G, k=2, ordering='degree_min')) [0, 4] - sage: sorted(greedy_dominating_set(G, k=2, ordering="degree_max")) + sage: sorted(greedy_dominating_set(G, k=2, ordering='degree_max')) [1, 4] - sage: greedy_dominating_set(G, k=3, ordering="degree_min", return_sets=True, closest=False) + sage: greedy_dominating_set(G, k=3, ordering='degree_min', return_sets=True, closest=False) {0: {0, 1, 2, 3}, 4: {4}} - sage: greedy_dominating_set(G, k=3, ordering="degree_min", return_sets=True, closest=True) + sage: greedy_dominating_set(G, k=3, ordering='degree_min', return_sets=True, closest=True) {0: {0, 2, 3}, 4: {1, 4}} Asking for a dominating set of a subset of vertices:: @@ -1222,7 +1218,7 @@ def greedy_dominating_set(G, k=1, vertices=None, ordering=None, return_sets=Fals Check parameters:: - sage: greedy_dominating_set(G, ordering="foo") + sage: greedy_dominating_set(G, ordering='foo') Traceback (most recent call last): ... ValueError: ordering must be None, "degree_min" or "degree_max" @@ -1302,7 +1298,7 @@ def maximum_leaf_number(G, solver=None, verbose=0, integrality_tolerance=1e-3): - ``G`` -- a Graph - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1310,7 +1306,7 @@ def maximum_leaf_number(G, solver=None, verbose=0, integrality_tolerance=1e-3): :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers diff --git a/src/sage/graphs/dot2tex_utils.py b/src/sage/graphs/dot2tex_utils.py index f8eb55485ac..77446949886 100644 --- a/src/sage/graphs/dot2tex_utils.py +++ b/src/sage/graphs/dot2tex_utils.py @@ -16,8 +16,8 @@ @cached_function def have_dot2tex(): """ - Returns whether ``dot2tex`` >= 2.8.7 and graphviz are installed - and functional + Return whether ``dot2tex`` >= 2.8.7 and graphviz are installed + and functional. EXAMPLES:: @@ -29,15 +29,15 @@ def have_dot2tex(): try: import dot2tex # Test for this required feature from dot2tex 2.8.7 - return dot2tex.dot2tex("graph {}", format="positions") == {} + return dot2tex.dot2tex("graph {}", format='positions') == {} except (Exception, SystemExit): return False def assert_have_dot2tex(): """ - Tests whether ``dot2tex`` >= 2.8.7 and graphviz are installed and - functional, and raises an error otherwise + Test whether ``dot2tex`` >= 2.8.7 and graphviz are installed and + functional, and raises an error otherwise. EXAMPLES:: @@ -63,7 +63,7 @@ def assert_have_dot2tex(): print(import_error_string) raise # re-raise current exception else: - if dot2tex.dot2tex("graph {}", format="positions") != {}: + if dot2tex.dot2tex("graph {}", format='positions') != {}: raise RuntimeError(check_error_string) diff --git a/src/sage/graphs/generators/basic.py b/src/sage/graphs/generators/basic.py index 257d0b2278f..e231428445f 100644 --- a/src/sage/graphs/generators/basic.py +++ b/src/sage/graphs/generators/basic.py @@ -452,7 +452,7 @@ def CorrelationGraph(seqs, alpha, include_anticorrelation): adjacency_matrix = Matrix(boolean_adjacency_matrix.astype(int)) # call graph constructor - return Graph(adjacency_matrix, format="adjacency_matrix", name="Correlation Graph") + return Graph(adjacency_matrix, format='adjacency_matrix', name="Correlation Graph") def CompleteBipartiteGraph(p, q, set_position=True): @@ -467,7 +467,7 @@ def CompleteBipartiteGraph(p, q, set_position=True): - ``p``, ``q`` -- number of vertices in each side - - ``set_position`` -- boolean (default ``True``); if set to ``True``, we + - ``set_position`` -- boolean (default: ``True``); if set to ``True``, we assign positions to the vertices so that the set of cardinality `p` is on the line `y=1` and the set of cardinality `q` is on the line `y=0`. @@ -591,7 +591,7 @@ def CompleteMultipartiteGraph(L): INPUT: - - ``L`` -- a list of integers; the respective sizes of the components + - ``L`` -- list of integers; the respective sizes of the components PLOTTING: Produce a layout of the vertices so that vertices in the same vertex set are adjacent and clearly separated from vertices in other vertex @@ -893,7 +893,7 @@ def Grid2dGraph(p, q, set_positions=True): INPUT: - - ``p`` and ``q`` -- two positive integers + - ``p``, ``q`` -- two positive integers - ``set_positions`` -- boolean (default: ``True``); whether to set the position of the nodes @@ -954,8 +954,8 @@ def GridGraph(dim_list): INPUT: - - ``dim_list`` -- a list of integers representing the number of nodes to - extend in each dimension + - ``dim_list`` -- list of integers representing the number of nodes to + extend in each dimension PLOTTING: When plotting, this graph will use the default spring-layout algorithm, unless a position dictionary is specified. @@ -1182,12 +1182,12 @@ def MoebiusLadderGraph(n): INPUT: - - ``n`` -- a non negative integer; number of nodes is `2n` + - ``n`` -- a nonnegative integer; number of nodes is `2n` OUTPUT: - ``G`` -- a Möbius ladder graph of order `2n`; note that a - :class:`ValueError` is returned if `n < 0` + :exc:`ValueError` is returned if `n < 0` EXAMPLES: @@ -1214,12 +1214,12 @@ def MoebiusLadderGraph(n): TESTS: - The input parameter must be a non negative integer:: + The input parameter must be a nonnegative integer:: sage: G = graphs.MoebiusLadderGraph(-1) Traceback (most recent call last): ... - ValueError: parameter n must be a non negative integer + ValueError: parameter n must be a nonnegative integer REFERENCES: @@ -1235,7 +1235,7 @@ def MoebiusLadderGraph(n): - Janmenjaya Panda (2024-05-26) """ if n < 0: - raise ValueError("parameter n must be a non negative integer") + raise ValueError("parameter n must be a nonnegative integer") G = Graph(2 * n, name="Moebius ladder graph") G._circle_embedding(list(range(2 * n)), angle=pi/2) @@ -1421,7 +1421,7 @@ def StarGraph(n): sage: G = graphics_array(j) sage: G.show() # long time """ - G = Graph({0: list(range(1, n + 1))}, name="Star graph", format="dict_of_lists") + G = Graph({0: list(range(1, n + 1))}, name="Star graph", format='dict_of_lists') G.set_pos({0: (0, 0)}) G._circle_embedding(list(range(1, n + 1)), angle=pi/2) return G diff --git a/src/sage/graphs/generators/chessboard.py b/src/sage/graphs/generators/chessboard.py index a76d6f98de7..4759ad917e7 100644 --- a/src/sage/graphs/generators/chessboard.py +++ b/src/sage/graphs/generators/chessboard.py @@ -59,10 +59,10 @@ def ChessboardGraphGenerator(dim_list, rook=True, rook_radius=None, - ``knight`` -- boolean (default: ``True``); indicating whether the chess piece is able to move like a knight - - ``knight_x`` -- integer (default: ``1``); indicates the number on steps + - ``knight_x`` -- integer (default: `1`); indicates the number on steps the chess piece moves in one dimension when moving like a knight - - ``knight_y`` -- integer (default: ``2``); indicates the number on steps + - ``knight_y`` -- integer (default: `2`); indicates the number on steps the chess piece moves in the second dimension when moving like a knight - ``relabel`` -- boolean (default: ``False``); indicates whether the @@ -272,7 +272,7 @@ def QueenGraph(dim_list, radius=None, relabel=False): sage: G.is_isomorphic(H) True - Also True in higher dimensions:: + Also ``True`` in higher dimensions:: sage: G = graphs.QueenGraph([3, 4, 5], radius=1) sage: H = graphs.KingGraph([5, 3, 4]) @@ -289,7 +289,6 @@ def QueenGraph(dim_list, radius=None, relabel=False): ....: H.add_edges(B.edges(sort=False)) ....: if not G.is_isomorphic(H): ....: print("that's not good!") - """ G, dimstr = ChessboardGraphGenerator(dim_list, rook=True, rook_radius=radius, @@ -346,7 +345,7 @@ def KingGraph(dim_list, radius=None, relabel=False): sage: G.is_isomorphic( H ) True - Also True in higher dimensions:: + Also ``True`` in higher dimensions:: sage: G = graphs.KingGraph( [2, 5, 4], radius=5 ) sage: H = graphs.QueenGraph( [4, 5, 2] ) @@ -386,10 +385,10 @@ def KnightGraph(dim_list, one=1, two=2, relabel=False): - ``dim_list`` -- iterable (list, set, dict); provides the dimensions `n_1, n_2, \ldots, n_d`, with `n_i \geq 1`, of the chessboard - - ``one`` -- integer (default: ``1``); indicates the number of steps in the + - ``one`` -- integer (default: `1`); indicates the number of steps in the first dimension - - ``two`` -- integer (default: ``2``); indicates the number of steps in the + - ``two`` -- integer (default: `2`); indicates the number of steps in the second dimension - ``relabel`` -- boolean (default: ``False``); indicates whether the @@ -526,7 +525,6 @@ def BishopGraph(dim_list, radius=None, relabel=False): ....: H.add_edges( graphs.KnightGraph([d,d],one=r,two=r).edges(sort=False) ) ....: if not B.is_isomorphic(H): ....: print("that's not good!") - """ G, dimstr = ChessboardGraphGenerator(dim_list, rook=False, knight=False, diff --git a/src/sage/graphs/generators/classical_geometries.py b/src/sage/graphs/generators/classical_geometries.py index 957f88d2061..f5dbad17169 100644 --- a/src/sage/graphs/generators/classical_geometries.py +++ b/src/sage/graphs/generators/classical_geometries.py @@ -3,7 +3,7 @@ Families of graphs derived from classical geometries over finite fields These include graphs of polar spaces, affine polar graphs, graphs -related to Hermitean unitals, graphs on nonisotropic points, etc +related to Hermitean unitals, graphs on nonisotropic points, etc. The methods defined here appear in :mod:`sage.graphs.graph_generators`. """ @@ -37,7 +37,7 @@ def SymplecticPolarGraph(d, q, algorithm=None): INPUT: - ``d``, ``q`` -- integers; note that only even values of `d` are accepted - by the function. + by the function - ``algorithm`` -- string (default: ``None``); if set to ``'gap'``, then the computation is carried via GAP library interface, computing totally @@ -67,17 +67,17 @@ def SymplecticPolarGraph(d, q, algorithm=None): (40, 12, 2, 4) sage: O.is_isomorphic(G) False - sage: S = graphs.SymplecticPolarGraph(6, 4, algorithm="gap") # not tested (long time) + sage: S = graphs.SymplecticPolarGraph(6, 4, algorithm='gap') # not tested (long time) sage: S.is_strongly_regular(parameters=True) # not tested (long time) (1365, 340, 83, 85) TESTS:: - sage: graphs.SymplecticPolarGraph(4,4,algorithm="gap").is_strongly_regular(parameters=True) # needs sage.libs.gap + sage: graphs.SymplecticPolarGraph(4,4,algorithm='gap').is_strongly_regular(parameters=True) # needs sage.libs.gap (85, 20, 3, 5) sage: graphs.SymplecticPolarGraph(4,4).is_strongly_regular(parameters=True) # needs sage.libs.pari (85, 20, 3, 5) - sage: graphs.SymplecticPolarGraph(4,4,algorithm="blah") + sage: graphs.SymplecticPolarGraph(4,4,algorithm='blah') Traceback (most recent call last): ... ValueError: unknown algorithm! @@ -113,7 +113,7 @@ def SymplecticPolarGraph(d, q, algorithm=None): return G -def AffineOrthogonalPolarGraph(d, q, sign="+"): +def AffineOrthogonalPolarGraph(d, q, sign='+'): r""" Return the affine polar graph `VO^+(d,q),VO^-(d,q)` or `VO(d,q)`. @@ -134,7 +134,7 @@ def AffineOrthogonalPolarGraph(d, q, sign="+"): - ``q`` -- integer; a power of a prime number, as `F_q` must exist - - ``sign`` -- string (default: ``"+"``); must be equal to ``"+"``, ``"-"``, + - ``sign`` -- string (default: ``'+'``); must be equal to ``'+'``, ``'-'``, or ``None`` to compute (respectively) `VO^+(d,q),VO^-(d,q)` or `VO(d,q)` @@ -207,7 +207,7 @@ def AffineOrthogonalPolarGraph(d, q, sign="+"): return G -def _orthogonal_polar_graph(m, q, sign="+", point_type=[0]): +def _orthogonal_polar_graph(m, q, sign='+', point_type=[0]): r""" A helper function to build ``OrthogonalPolarGraph`` and ``NO2,3,5`` graphs. @@ -218,10 +218,10 @@ def _orthogonal_polar_graph(m, q, sign="+", point_type=[0]): - ``m``, ``q`` -- integers; `q` must be a prime power - - ``sign`` -- string (default: ``"+"``); must be ``"+"`` or ``"-"`` if `m` - is even, ``"+"`` (default) otherwise + - ``sign`` -- string (default: ``'+'``); must be ``'+'`` or ``'-'`` if `m` + is even, ``'+'`` (default) otherwise - - ``point_type`` -- a list of elements from `F_q` + - ``point_type`` -- list of elements from `F_q` EXAMPLES: @@ -285,7 +285,6 @@ def _orthogonal_polar_graph(m, q, sign="+", point_type=[0]): sage: g = _orthogonal_polar_graph(5,3,point_type=[1]) sage: g.is_strongly_regular(parameters=True) (36, 15, 6, 6) - """ from sage.schemes.projective.projective_space import ProjectiveSpace from sage.modules.free_module_element import free_module_element as vector @@ -331,7 +330,7 @@ def P(x, y): return G -def OrthogonalPolarGraph(m, q, sign="+"): +def OrthogonalPolarGraph(m, q, sign='+'): r""" Return the Orthogonal Polar Graph `O^{\epsilon}(m,q)`. @@ -342,8 +341,8 @@ def OrthogonalPolarGraph(m, q, sign="+"): - ``m``, ``q`` -- integers; `q` must be a prime power - - ``sign`` -- string (default: ``"+"``); must be ``"+"`` or ``"-"`` if `m` - is even, ``"+"`` (default) otherwise + - ``sign`` -- string (default: ``'+'``); must be ``'+'`` or ``'-'`` if `m` + is even, ``'+'`` (default) otherwise EXAMPLES:: @@ -387,9 +386,9 @@ def OrthogonalPolarGraph(m, q, sign="+"): return G -def NonisotropicOrthogonalPolarGraph(m, q, sign="+", perp=None): +def NonisotropicOrthogonalPolarGraph(m, q, sign='+', perp=None): r""" - Return the Graph `NO^{\epsilon,\perp}_{m}(q)` + Return the Graph `NO^{\epsilon,\perp}_{m}(q)`. Let the vectorspace of dimension `m` over `F_q` be endowed with a nondegenerate quadratic form `F`, of type ``sign`` for `m` even. @@ -417,7 +416,7 @@ def NonisotropicOrthogonalPolarGraph(m, q, sign="+", perp=None): - ``q`` -- a power of a prime number, the size of the underlying field - - ``sign`` -- string (default: ``"+"``); must be either ``"+"`` or ``"-"`` + - ``sign`` -- string (default: ``'+'``); must be either ``'+'`` or ``'-'`` EXAMPLES: @@ -551,7 +550,7 @@ def NonisotropicOrthogonalPolarGraph(m, q, sign="+", perp=None): def _polar_graph(m, q, g, intersection_size=None): r""" - The helper function to build graphs `(D)U(m,q)` and `(D)Sp(m,q)` + The helper function to build graphs `(D)U(m,q)` and `(D)Sp(m,q)`. Building a graph on an orbit of a group `g` of `m\times m` matrices over `GF(q)` on the points (or subspaces of dimension ``m//2``) isotropic @@ -570,7 +569,7 @@ def _polar_graph(m, q, g, intersection_size=None): - ``g`` -- the group acting - - ``intersection_size`` -- (default: ``None``); if ``None``, build the graph + - ``intersection_size`` -- (default: ``None``) if ``None``, build the graph on the isotropic points, with adjacency being orthogonality w.r.t. `F`. Otherwise, build the graph on the maximal totally isotropic subspaces, with adjacency specified by ``intersection_size`` being as given. @@ -604,7 +603,7 @@ def _polar_graph(m, q, g, intersection_size=None): loops=False) -def UnitaryPolarGraph(m, q, algorithm="gap"): +def UnitaryPolarGraph(m, q, algorithm='gap'): r""" Return the Unitary Polar Graph `U(m,q)`. @@ -615,7 +614,7 @@ def UnitaryPolarGraph(m, q, algorithm="gap"): - ``m``, ``q`` -- integers; `q` must be a prime power - - ``algorithm`` -- string (default: ``"gap"``); if set to 'gap' then the + - ``algorithm`` -- string (default: ``'gap'``); if set to ``'gap'`` then the computation is carried via GAP library interface, computing totally singular subspaces, which is faster for large examples (especially with `q>2`). Otherwise it is done directly. @@ -634,11 +633,11 @@ def UnitaryPolarGraph(m, q, algorithm="gap"): TESTS:: - sage: graphs.UnitaryPolarGraph(4,3, algorithm="gap").is_strongly_regular(parameters=True) # needs sage.libs.gap + sage: graphs.UnitaryPolarGraph(4,3, algorithm='gap').is_strongly_regular(parameters=True) # needs sage.libs.gap (280, 36, 8, 4) sage: graphs.UnitaryPolarGraph(4,3).is_strongly_regular(parameters=True) # needs sage.libs.gap (280, 36, 8, 4) - sage: graphs.UnitaryPolarGraph(4,3, algorithm="foo") + sage: graphs.UnitaryPolarGraph(4,3, algorithm='foo') Traceback (most recent call last): ... ValueError: unknown algorithm! @@ -1125,7 +1124,7 @@ def T2starGeneralizedQuadrangleGraph(q, dual=False, hyperoval=None, field=None, def HaemersGraph(q, hyperoval=None, hyperoval_matching=None, field=None, check_hyperoval=True): r""" - Return the Haemers graph obtained from `T_2^*(q)^*` + Return the Haemers graph obtained from `T_2^*(q)^*`. Let `q` be a power of 2. In Sect. 8.A of [BL1984]_ one finds a construction of a strongly regular graph with parameters `(q^2(q+2),q^2+q-1,q-2,q)` from @@ -1201,7 +1200,6 @@ def HaemersGraph(q, hyperoval=None, hyperoval_matching=None, field=None, check_h Haemers(8): Graph on 640 vertices sage: g.is_strongly_regular(parameters=True) # not tested (long time) # needs sage.rings.finite_rings (640, 71, 6, 8) - """ from sage.modules.free_module_element import free_module_element as vector from sage.rings.finite_rings.finite_field_constructor import GF @@ -1280,7 +1278,7 @@ def CossidentePenttilaGraph(q): INPUT: - - ``q`` -- an odd prime power. + - ``q`` -- an odd prime power EXAMPLES: @@ -1311,7 +1309,7 @@ def CossidentePenttilaGraph(q): raise ValueError('q(={}) must be an odd prime power'.format(q)) from sage.features.gap import GapPackage - GapPackage("grape", spkg="gap_packages").require() + GapPackage("grape", spkg='gap_packages').require() from sage.libs.gap.libgap import libgap adj_list = libgap.function_factory("""function(q) @@ -1380,8 +1378,8 @@ def Nowhere0WordsTwoWeightCodeGraph(q, hyperoval=None, field=None, check_hyperov particular, ``hyperoval`` we build is the classical one, i.e. a conic with the point of intersection of its tangent lines. - - ``field`` -- an instance of a finite field of order `q`, must be provided - if ``hyperoval`` is provided. + - ``field`` -- an instance of a finite field of order `q`; must be provided + if ``hyperoval`` is provided - ``check_hyperoval`` -- boolean (default: ``True``); whether to check ``hyperoval`` for correctness or not @@ -1483,7 +1481,7 @@ def OrthogonalDualPolarGraph(e, d, q): INPUT: - ``e`` -- integer; type of the orthogonal polar space to consider; - must be `-1, 0` or `1`. + must be `-1, 0` or `1` - ``d`` -- integer; diameter of the graph @@ -1607,6 +1605,6 @@ def hashable(v): == intersection_size: edges.append((i, j)) - G = Graph(edges, format="list_of_edges") + G = Graph(edges, format='list_of_edges') G.name("Dual Polar Graph on Orthogonal group (%d, %d, %d)" % (e, m, q)) return G diff --git a/src/sage/graphs/generators/degree_sequence.py b/src/sage/graphs/generators/degree_sequence.py index 5250bd9cb1a..fa3a6aebb02 100644 --- a/src/sage/graphs/generators/degree_sequence.py +++ b/src/sage/graphs/generators/degree_sequence.py @@ -97,7 +97,7 @@ def DegreeSequenceBipartite(s1, s2): True Some sequences being incompatible if, for example, their sums are different, - the functions raises a :class:`ValueError` when no graph corresponding + the functions raises a :exc:`ValueError` when no graph corresponding to the degree sequences exists:: sage: g = graphs.DegreeSequenceBipartite([2,2,2,2,1],[5,5]) # needs sage.combinat sage.modules diff --git a/src/sage/graphs/generators/distance_regular.pyx b/src/sage/graphs/generators/distance_regular.pyx index bb0797d8f42..795bfa58dc2 100644 --- a/src/sage/graphs/generators/distance_regular.pyx +++ b/src/sage/graphs/generators/distance_regular.pyx @@ -86,7 +86,7 @@ def cocliques_HoffmannSingleton(): if len(c1.intersection(c2)) == 8: edges.append((c1, c2)) - G = Graph(edges, format="list_of_edges") + G = Graph(edges, format='list_of_edges') return G @@ -578,11 +578,11 @@ def LeonardGraph(): if M[i, j] * M[i, l] * M[k, j] * M[k, l] == -1: edges.append(((i, j), (k, l))) - D = Graph(edges, format="list_of_edges") + D = Graph(edges, format='list_of_edges') blocks = [frozenset(cl) for cl in D.cliques_maximum()] edges = [(p, b) for b in blocks for p in b] - G = Graph(edges, format="list_of_edges") + G = Graph(edges, format='list_of_edges') return G @@ -1301,7 +1301,7 @@ def graph_from_GQ_spread(const int s, const int t): sig_check() edges.append((p1, p2)) - return Graph(edges, format="list_of_edges") + return Graph(edges, format='list_of_edges') def GeneralisedDodecagonGraph(const int s, const int t): @@ -1792,7 +1792,7 @@ def _line_graph_generalised_polygon(H): sig_check() edges.append((l1, l2)) - return Graph(edges, format="list_of_edges") + return Graph(edges, format='list_of_edges') def _intersection_array_from_graph(G): @@ -1806,7 +1806,7 @@ def _intersection_array_from_graph(G): INPUT: - - G -- a graph + - ``G`` -- a graph EXAMPLES:: @@ -2539,10 +2539,10 @@ def near_polygon_graph(family, params): INPUT: - - ``family`` -- int; an element of the enum ``NearPolygonGraph``. + - ``family`` -- integer; an element of the enum ``NearPolygonGraph`` - - ``params`` -- int or tuple; the parameters needed to construct a graph - of the family ``family``. + - ``params`` -- integer or tuple; the parameters needed to construct a graph + of the family ``family`` EXAMPLES:: @@ -2707,7 +2707,7 @@ def distance_regular_graph(list arr, existence=False, check=True): - ``False`` -- if there is no graph with the given intersection array; - - ``Unknown`` -- if Sage doesn't know if such a graph exists. + - ``Unknown`` -- if Sage doesn't know if such a graph exists - ``check`` -- boolean (default: ``True``); if ``True``, then checks that the result of this function has the given intersection array diff --git a/src/sage/graphs/generators/families.py b/src/sage/graphs/generators/families.py index c7e1c031ebf..4c42fe99632 100644 --- a/src/sage/graphs/generators/families.py +++ b/src/sage/graphs/generators/families.py @@ -26,7 +26,7 @@ def JohnsonGraph(n, k): r""" - Returns the Johnson graph with parameters `n, k`. + Return the Johnson graph with parameters `n, k`. Johnson graphs are a special class of undirected graphs defined from systems of sets. The vertices of the Johnson graph `J(n,k)` are the `k`-element @@ -76,7 +76,7 @@ def JohnsonGraph(n, k): def KneserGraph(n, k): r""" - Returns the Kneser Graph with parameters `n, k`. + Return the Kneser Graph with parameters `n, k`. The Kneser Graph with parameters `n,k` is the graph whose vertices are the `k`-subsets of `[0,1,\dots,n-1]`, and such @@ -148,19 +148,18 @@ def FurerGadget(k, prefix=None): INPUT: - - ``k`` -- The order of the returned Furer gadget, greater than 0. + - ``k`` -- the order of the returned Furer gadget, greater than 0 - - ``prefix`` -- Prefix of to be appended to each vertex label, - so as to individualise the returned Furer gadget. - Must be comparable for equality and hashable. + - ``prefix`` -- prefix of to be appended to each vertex label, + so as to individualise the returned Furer gadget; must be comparable for + equality and hashable OUTPUT: - - ``G`` -- The Furer gadget of order ``k`` + - ``G`` -- the Furer gadget of order ``k`` - - ``coloring`` -- A list of list of vertices, representing the - partition induced by the coloring of ``G``'s - vertices + - ``coloring`` -- list of list of vertices, representing the + partition induced by the coloring of ``G``'s vertices EXAMPLES: @@ -257,18 +256,18 @@ def CaiFurerImmermanGraph(G, twisted=False): INPUT: - - ``G`` -- An undirected graph on which to construct the - Cai-Furer-Immerman graph + - ``G`` -- an undirected graph on which to construct the + Cai-Furer-Immerman graph - - ``twisted`` -- A boolean indicating if the version to construct - is a twisted one or not + - ``twisted`` -- a boolean indicating if the version to construct + is a twisted one or not OUTPUT: - - ``H`` -- The Cai-Furer-Immerman graph on ``G`` + - ``H`` -- the Cai-Furer-Immerman graph on ``G`` - - ``coloring`` -- A list of list of vertices, representing the - partition induced by the coloring on ``H`` + - ``coloring`` -- list of list of vertices, representing the + partition induced by the coloring on ``H`` EXAMPLES: @@ -364,14 +363,14 @@ def EgawaGraph(p, s): INPUT: - ``p`` -- power to which the graph named `Y` in the reference - provided above will be raised + provided above will be raised - ``s`` -- power to which the graph named `X` in the reference - provided above will be raised + provided above will be raised OUTPUT: - - ``G`` -- The Egawa graph with parameters (p,s) + - ``G`` -- the Egawa graph with parameters (p,s) EXAMPLES: @@ -428,18 +427,17 @@ def HammingGraph(n, q, X=None): INPUT: - ``n`` -- power to which ``X`` will be raised to provide vertices - for the Hamming graph + for the Hamming graph - ``q`` -- cardinality of ``X`` - - ``X`` -- list of labels representing the vertices of the - underlying graph the Hamming graph will be based on; if - ``None`` (or left unused), the list `[0, ... , q-1]` - will be used + - ``X`` -- list of labels representing the vertices of the underlying graph + the Hamming graph will be based on; if ``None`` (or left unused), the + list `[0, ... , q-1]` will be used OUTPUT: - - ``G`` -- The Hamming graph with parameters `(n,q,X)` + - ``G`` -- the Hamming graph with parameters `(n,q,X)` EXAMPLES: @@ -505,9 +503,9 @@ def BalancedTree(r, h): INPUT: - - ``r`` -- positive integer `\geq 2`. The degree of the root node. + - ``r`` -- positive integer `\geq 2`; the degree of the root node - - ``h`` -- positive integer `\geq 1`. The height of the balanced tree. + - ``h`` -- positive integer `\geq 1`; the height of the balanced tree OUTPUT: @@ -596,7 +594,7 @@ def BalancedTree(r, h): def BarbellGraph(n1, n2): r""" - Returns a barbell graph with `2*n_1 + n_2` nodes. + Return a barbell graph with `2 n_1 + n_2` nodes. The argument `n_1` must be greater than or equal to 2. @@ -605,15 +603,15 @@ def BarbellGraph(n1, n2): INPUT: - - ``n1`` -- integer `\geq 2`. The order of each of the two - complete graphs. + - ``n1`` -- integer `\geq 2`; the order of each of the two + complete graphs - - ``n2`` -- nonnegative integer. The order of the path graph - connecting the two complete graphs. + - ``n2`` -- nonnegative integer; the order of the path graph + connecting the two complete graphs OUTPUT: - A barbell graph of order `2*n_1 + n_2`. A :class:`ValueError` is + A barbell graph of order `2*n_1 + n_2`. A :exc:`ValueError` is returned if `n_1 < 2` or `n_2 < 0`. PLOTTING: @@ -714,7 +712,7 @@ def BarbellGraph(n1, n2): def LollipopGraph(n1, n2): r""" - Returns a lollipop graph with `n_1 + n_2` nodes. + Return a lollipop graph with `n_1 + n_2` nodes. A lollipop graph is a path graph (order `n_2`) connected to a complete graph (order `n_1`). (A barbell graph minus one of the bells). @@ -885,9 +883,9 @@ def AztecDiamondGraph(n): def DipoleGraph(n): r""" - Returns a dipole graph with n edges. + Return a dipole graph with `n` edges. - A dipole graph is a multigraph consisting of 2 vertices connected with n + A dipole graph is a multigraph consisting of 2 vertices connected with `n` parallel edges. EXAMPLES: @@ -927,7 +925,7 @@ def DipoleGraph(n): def BubbleSortGraph(n): r""" - Returns the bubble sort graph `B(n)`. + Return the bubble sort graph `B(n)`. The vertices of the bubble sort graph are the set of permutations on `n` symbols. Two vertices are adjacent if one can be obtained @@ -943,12 +941,12 @@ def BubbleSortGraph(n): INPUT: - - ``n`` -- positive integer. The number of symbols to permute. + - ``n`` -- positive integer. The number of symbols to permute OUTPUT: The bubble sort graph `B(n)` on `n` symbols. If `n < 1`, a - :class:`ValueError` is returned. + :exc:`ValueError` is returned. EXAMPLES:: @@ -1055,7 +1053,6 @@ def chang_graphs(): sage: [T8.seidel_switching(x, inplace=False).is_isomorphic(G) # needs sage.modules ....: for x, G in zip(s, chang_graphs)] [True, True, True] - """ g1 = Graph("[}~~EebhkrRb_~SoLOIiAZ?LBBxDb?bQcggjHKEwoZFAaiZ?Yf[?dxb@@tdWGkwn", loops=False, multiedges=False) @@ -1068,19 +1065,17 @@ def chang_graphs(): def CirculantGraph(n, adjacency): r""" - Returns a circulant graph with `n` nodes. + Return a circulant graph with `n` nodes. A circulant graph has the property that the vertex `i` is connected with the vertices `i+j` and `i-j` for each `j` in ``adjacency``. INPUT: - - ``n`` -- number of vertices in the graph - ``adjacency`` -- the list of `j` values - PLOTTING: Upon construction, the position dictionary is filled to override the spring-layout algorithm. By convention, each circulant graph will be displayed with the first (0) node at the top, with @@ -1187,27 +1182,27 @@ def CubeGraph(n, embedding=1): - ``n`` -- integer; the dimension of the cube graph - - ``embedding`` -- integer (default: ``1``); two embeddings of the `n`-cube + - ``embedding`` -- integer (default: `1`); two embeddings of the `n`-cube are available: - - ``1``: the `n`-cube is projected inside a regular `2n`-gonal polygon by + - ``1`` -- the `n`-cube is projected inside a regular `2n`-gonal polygon by a skew orthogonal projection. See the :wikipedia:`Hypercube` for more details. - - ``2``: orthogonal projection of the `n`-cube. This orientation shows + - ``2`` -- orthogonal projection of the `n`-cube. This orientation shows columns of independent vertices such that the neighbors of a vertex are located in the columns on the left and on the right. The number of vertices in each column represents rows in Pascal's triangle. See for instance the :wikipedia:`10-cube` for more details. - - ``3``: oblique projection of the `n`-cube. Oblique projection involves + - ``3`` -- oblique projection of the `n`-cube. Oblique projection involves aligning one face parallel to the viewer and projecting at a specified angle, maintaining equal size for edges parallel to one axis while applying fixed foreshortening to others. This method simplifies the representation of a four-dimensional hypercube onto a two-dimensional plane, offering a geometrically consistent visualization. - - ``None`` or ``O``: no embedding is provided + - ``None`` or ``O`` -- no embedding is provided EXAMPLES: @@ -1320,7 +1315,7 @@ def CubeGraph(n, embedding=1): def GoethalsSeidelGraph(k, r): r""" - Returns the graph `\text{Goethals-Seidel}(k,r)`. + Return the graph `\text{Goethals-Seidel}(k,r)`. The graph `\text{Goethals-Seidel}(k,r)` comes from a construction presented in Theorem 2.4 of [GS1970]_. It relies on a :func:`(v,k)-BIBD @@ -1380,13 +1375,13 @@ def GoethalsSeidelGraph(k, r): for i in range(n): PP[i, i] = 0 - G = Graph(PP, format="seidel_adjacency_matrix") + G = Graph(PP, format='seidel_adjacency_matrix') return G def DorogovtsevGoltsevMendesGraph(n): """ - Construct the n-th generation of the Dorogovtsev-Goltsev-Mendes + Construct the `n`-th generation of the Dorogovtsev-Goltsev-Mendes graph. EXAMPLES:: @@ -1408,7 +1403,7 @@ def DorogovtsevGoltsevMendesGraph(n): def FoldedCubeGraph(n): r""" - Returns the folded cube graph of order `2^{n-1}`. + Return the folded cube graph of order `2^{n-1}`. The folded cube graph on `2^{n-1}` vertices can be obtained from a cube graph on `2^n` vertices by merging together opposed @@ -1461,7 +1456,7 @@ def FriendshipGraph(n): INPUT: - ``n`` -- positive integer; the number of copies of `C_3` to use in - constructing `F_n`. + constructing `F_n` OUTPUT: @@ -1677,7 +1672,7 @@ def fib(level, node, y): def GeneralizedPetersenGraph(n, k): r""" - Returns a generalized Petersen graph with `2n` nodes. The variables + Return a generalized Petersen graph with `2n` nodes. The variables `n`, `k` are integers such that `n>2` and `0 (n - 1) // 2: raise ValueError("k must be in 1<= k <=floor((n-1)/2)") - G = Graph(2 * n, name="Generalized Petersen graph (n="+str(n)+",k="+str(k)+")") + G = Graph(2 * n, name="Generalized Petersen graph (n='+str(n)+',k="+str(k)+")") for i in range(n): G.add_edge(i, (i+1) % n) G.add_edge(i, i+n) @@ -2090,7 +2085,7 @@ def TabacjnGraph(n, a, b, r): def HararyGraph(k, n): r""" - Returns the Harary graph on `n` vertices and connectivity `k`, where + Return the Harary graph on `n` vertices and connectivity `k`, where `2 \leq k < n`. A `k`-connected graph `G` on `n` vertices requires the minimum degree @@ -2158,9 +2153,9 @@ def HyperStarGraph(n, k): INPUT: - - ``n`` -- non-negative integer; length of the binary strings + - ``n`` -- nonnegative integer; length of the binary strings - - ``k`` -- non-negative integer; number of 1s per binary string + - ``k`` -- nonnegative integer; number of 1s per binary string EXAMPLES:: @@ -2175,22 +2170,22 @@ def HyperStarGraph(n, k): sage: graphs.HyperStarGraph(-1, 1) Traceback (most recent call last): ... - ValueError: parameters n and k must be non-negative integers satisfying n >= k >= 0 + ValueError: parameters n and k must be nonnegative integers satisfying n >= k >= 0 sage: graphs.HyperStarGraph(1, -1) Traceback (most recent call last): ... - ValueError: parameters n and k must be non-negative integers satisfying n >= k >= 0 + ValueError: parameters n and k must be nonnegative integers satisfying n >= k >= 0 sage: graphs.HyperStarGraph(1, 2) Traceback (most recent call last): ... - ValueError: parameters n and k must be non-negative integers satisfying n >= k >= 0 + ValueError: parameters n and k must be nonnegative integers satisfying n >= k >= 0 AUTHORS: - Michael Yurko (2009-09-01) """ if n < 0 or k < 0 or k > n: - raise ValueError("parameters n and k must be non-negative integers " + raise ValueError("parameters n and k must be nonnegative integers " "satisfying n >= k >= 0") if not n: adj = {} @@ -2237,11 +2232,11 @@ def LCFGraph(n, shift_list, repeats): INPUT: - - ``n`` -- the number of nodes. + - ``n`` -- the number of nodes - - ``shift_list`` -- a list of integer shifts mod `n`. + - ``shift_list`` -- a list of integer shifts mod `n` - - ``repeats`` -- the number of times to repeat the process. + - ``repeats`` -- the number of times to repeat the process EXAMPLES:: @@ -2283,7 +2278,7 @@ def LCFGraph(n, shift_list, repeats): def MycielskiGraph(k=1, relabel=True): r""" - Returns the `k`-th Mycielski Graph. + Return the `k`-th Mycielski Graph. The graph `M_k` is triangle-free and has chromatic number equal to `k`. These graphs show, constructively, that there @@ -2307,10 +2302,10 @@ def MycielskiGraph(k=1, relabel=True): INPUT: - - ``k`` Number of steps in the construction process. + - ``k`` -- number of steps in the construction process - - ``relabel`` Relabel the vertices so their names are the integers - ``range(n)`` where ``n`` is the number of vertices in the graph. + - ``relabel`` -- relabel the vertices so their names are the integers + ``range(n)`` where ``n`` is the number of vertices in the graph EXAMPLES: @@ -2397,7 +2392,7 @@ def MycielskiStep(g): def NKStarGraph(n, k): r""" - Returns the `(n,k)`-star graph. + Return the `(n,k)`-star graph. The vertices of the `(n,k)`-star graph are the set of all arrangements of `n` symbols into labels of length `k`. There are two adjacency rules for the @@ -2460,7 +2455,7 @@ def NKStarGraph(n, k): def NStarGraph(n): r""" - Returns the `n`-star graph. + Return the `n`-star graph. The vertices of the `n`-star graph are the set of permutations on `n` symbols. There is an edge between two vertices if their labels differ @@ -2508,7 +2503,7 @@ def NStarGraph(n): def OddGraph(n): r""" - Returns the Odd Graph with parameter `n`. + Return the Odd Graph with parameter `n`. The Odd Graph with parameter `n` is defined as the Kneser Graph with parameters `2n-1,n-1`. @@ -2546,7 +2541,7 @@ def OddGraph(n): def PaleyGraph(q): r""" - Paley graph with `q` vertices + Paley graph with `q` vertices. Parameter `q` must be the power of a prime number and congruent to 1 mod 4. @@ -2590,7 +2585,7 @@ def PaleyGraph(q): def PasechnikGraph(n): r""" - Pasechnik strongly regular graph on `(4n-1)^2` vertices + Pasechnik strongly regular graph on `(4n-1)^2` vertices. A strongly regular graph with parameters of the orthogonal array graph :func:`~sage.graphs.graph_generators.GraphGenerators.OrthogonalArrayBlockGraph`, @@ -2631,7 +2626,7 @@ def PasechnikGraph(n): def SquaredSkewHadamardMatrixGraph(n): r""" - Pseudo-`OA(2n,4n-1)`-graph from a skew Hadamard matrix of order `4n` + Pseudo-`OA(2n,4n-1)`-graph from a skew Hadamard matrix of order `4n`. A strongly regular graph with parameters of the orthogonal array graph :func:`~sage.graphs.graph_generators.GraphGenerators.OrthogonalArrayBlockGraph`, @@ -2726,17 +2721,17 @@ def SwitchedSquaredSkewHadamardMatrixGraph(n): def HanoiTowerGraph(pegs, disks, labels=True, positions=True): r""" - Returns the graph whose vertices are the states of the + Return the graph whose vertices are the states of the Tower of Hanoi puzzle, with edges representing legal moves between states. INPUT: - ``pegs`` -- the number of pegs in the puzzle, 2 or greater - ``disks`` -- the number of disks in the puzzle, 1 or greater - - ``labels`` -- default: ``True``, if ``True`` the graph contains + - ``labels`` -- (default: ``True``) if ``True`` the graph contains more meaningful labels, see explanation below. For large instances, turn off labels for much faster creation of the graph. - - ``positions`` -- default: ``True``, if ``True`` the graph contains + - ``positions`` -- (default: ``True``) if ``True`` the graph contains layout information. This creates a planar layout for the case of three pegs. For large instances, turn off layout information for much faster creation of the graph. @@ -2831,7 +2826,7 @@ def HanoiTowerGraph(pegs, disks, labels=True, positions=True): Some facts about this graph with `p` pegs and `d` disks: - - only automorphisms are the "obvious" ones -- renumber the pegs. + - only automorphisms are the "obvious" ones -- renumber the pegs - chromatic number is less than or equal to `p` - independence number is `p^{d-1}` @@ -2864,7 +2859,6 @@ def HanoiTowerGraph(pegs, disks, labels=True, positions=True): AUTHOR: - Rob Beezer, (2009-12-26), with assistance from Su Doree - """ # sanitize input from sage.rings.integer import Integer @@ -2975,7 +2969,7 @@ def HanoiTowerGraph(pegs, disks, labels=True, positions=True): def line_graph_forbidden_subgraphs(): r""" - Returns the 9 forbidden subgraphs of a line graph. + Return the 9 forbidden subgraphs of a line graph. See the :wikipedia:`Line_graph` for more information. @@ -2994,7 +2988,6 @@ def line_graph_forbidden_subgraphs(): Graph on 6 vertices, Graph on 6 vertices, Graph on 5 vertices] - """ from sage.graphs.graph import Graph from sage.graphs.generators.basic import ClawGraph @@ -3060,7 +3053,7 @@ def line_graph_forbidden_subgraphs(): def petersen_family(generate=False): r""" - Returns the Petersen family + Return the Petersen family. The Petersen family is a collection of 7 graphs which are the forbidden minors of the linklessly embeddable graphs. For more information see the @@ -3068,7 +3061,7 @@ def petersen_family(generate=False): INPUT: - - ``generate`` (boolean) -- whether to generate the family from the + - ``generate`` -- boolean; whether to generate the family from the `\Delta-Y` transformations. When set to ``False`` (default) a hardcoded version of the graphs (with a prettier layout) is returned. @@ -3170,7 +3163,7 @@ def SierpinskiGasketGraph(n): INPUT: - - `n` -- an integer + - ``n`` -- integer OUTPUT: @@ -3402,7 +3395,7 @@ def rec(H, kk): def WheelGraph(n): """ - Returns a Wheel graph with n nodes. + Return a Wheel graph with `n` nodes. A Wheel graph is a basic structure where one node is connected to all other nodes and those (outer) nodes are connected cyclically. @@ -3573,11 +3566,11 @@ def WindmillGraph(k, n): def trees(vertices): r""" - Returns a generator of the distinct trees on a fixed number of vertices. + Return a generator of the distinct trees on a fixed number of vertices. INPUT: - - ``vertices`` -- the size of the trees created. + - ``vertices`` -- the size of the trees created OUTPUT: @@ -3620,7 +3613,7 @@ def trees(vertices): return iter(TreeIterator(vertices)) -def nauty_gentreeg(options="", debug=False): +def nauty_gentreeg(options='', debug=False): r""" Return a generator which creates non-isomorphic trees from nauty's gentreeg program. @@ -3760,10 +3753,10 @@ def RingedTree(k, vertex_labels=True): INPUT: - - ``k`` -- the number of levels of the ringed tree. + - ``k`` -- the number of levels of the ringed tree - - ``vertex_labels`` (boolean) -- whether to label vertices as binary words - (default) or as integers. + - ``vertex_labels`` -- boolean; whether to label vertices as binary words + (default) or as integers EXAMPLES:: @@ -3828,16 +3821,16 @@ def RingedTree(k, vertex_labels=True): def MathonPseudocyclicMergingGraph(M, t): r""" - Mathon's merging of classes in a pseudo-cyclic 3-class association scheme + Mathon's merging of classes in a pseudo-cyclic 3-class association scheme. Construct strongly regular graphs from p.97 of [BL1984]_. INPUT: - - ``M`` -- the list of matrices in a pseudo-cyclic 3-class association scheme. - The identity matrix must be the first entry. + - ``M`` -- the list of matrices in a pseudo-cyclic 3-class association scheme; + the identity matrix must be the first entry - - ``t`` (integer) -- the number of the graph, from 0 to 2. + - ``t`` -- integer; the number of the graph, from 0 to 2 .. SEEALSO:: @@ -3901,7 +3894,7 @@ def MathonPseudocyclicStronglyRegularGraph(t, G=None, L=None): INPUT: - - ``t`` -- a positive integer + - ``t`` -- positive integer - ``G`` -- if ``None`` (default), try to construct the necessary graph with parameters `(4t+1,2t,t-1,t)`, otherwise use the user-supplied one, @@ -3948,12 +3941,12 @@ def MathonPseudocyclicStronglyRegularGraph(t, G=None, L=None): sage: G3x3 = graphs.MathonPseudocyclicStronglyRegularGraph(2, G=G, L=L) sage: G3x3.is_strongly_regular(parameters=True) (441, 220, 109, 110) - sage: G3x3.automorphism_group(algorithm="bliss").order() # optional - bliss + sage: G3x3.automorphism_group(algorithm='bliss').order() # optional - bliss 27 sage: G9 = graphs.MathonPseudocyclicStronglyRegularGraph(2) sage: G9.is_strongly_regular(parameters=True) (441, 220, 109, 110) - sage: G9.automorphism_group(algorithm="bliss").order() # optional - bliss + sage: G9.automorphism_group(algorithm='bliss').order() # optional - bliss 9 TESTS:: @@ -4034,7 +4027,7 @@ def Acon(i, j): def TuranGraph(n, r): r""" - Returns the Turan graph with parameters `n, r`. + Return the Turan graph with parameters `n, r`. Turan graphs are complete multipartite graphs with `n` vertices and `r` subsets, denoted `T(n,r)`, with the property that the sizes of the subsets @@ -4119,9 +4112,9 @@ def MuzychukS6Graph(n, d, Phi='fixed', Sigma='fixed', verbose=False): INPUT: - - ``n`` (integer) -- a prime power + - ``n`` -- integer; a prime power - - ``d`` (integer) -- must be odd if `n` is odd + - ``d`` -- integer; must be odd if `n` is odd - ``Phi`` is an optional parameter of the construction; it must be either @@ -4137,9 +4130,10 @@ def MuzychukS6Graph(n, d, Phi='fixed', Sigma='fixed', verbose=False): - ``'fixed'`` -- this will generate a fixed default `\Sigma`, or - - ``'random'`` -- `\Sigma` is generated at random. + - ``'random'`` -- `\Sigma` is generated at random - - ``verbose`` (Boolean) -- default is ``False``. If ``True``, print progress information + - ``verbose`` -- boolean (default: ``False``); if ``True``, print progress + information .. SEEALSO:: @@ -4369,9 +4363,9 @@ def CubeConnectedCycle(d): INPUT: - - ``d`` -- The dimension of the desired hypercube as well as the length - of the cycle to be placed at each vertex of the `d`-dimensional - hypercube. `d` must be a positive integer. + - ``d`` -- positive integer; the dimension of the desired hypercube as well + as the length of the cycle to be placed at each vertex of the + `d`-dimensional hypercube EXAMPLES: diff --git a/src/sage/graphs/generators/intersection.py b/src/sage/graphs/generators/intersection.py index 7087ca21752..3cdb3c681b8 100644 --- a/src/sage/graphs/generators/intersection.py +++ b/src/sage/graphs/generators/intersection.py @@ -31,7 +31,7 @@ def IntervalGraph(intervals, points_ordered=False): INPUT: - - ``intervals`` -- the list of pairs `(a_i,b_i)` defining the graph. + - ``intervals`` -- the list of pairs `(a_i,b_i)` defining the graph - ``points_ordered`` -- states whether every interval `(a_i,b_i)` of `intervals` satisfies `a_i= 0 and p <= 1): raise ValueError("parameter p is a probability, and so should be a real value between 0 and 1") @@ -290,9 +289,9 @@ def RandomRegularBipartite(n1, n2, d1, set_position=False, seed=None): - ``n1``, ``n2`` -- number of vertices in each side - - ``d1`` -- degree of the vertices in the set of cardinality `n1`. + - ``d1`` -- degree of the vertices in the set of cardinality `n1` - - ``set_position`` -- boolean (default ``False``); if set to ``True``, we + - ``set_position`` -- boolean (default: ``False``); if set to ``True``, we assign positions to the vertices so that the set of cardinality `n1` is on the line `y=1` and the set of cardinality `n2` is on the line `y=0`. @@ -450,16 +449,16 @@ def RandomBlockGraph(m, k, kmax=None, incidence_structure=False, seed=None): INPUT: - - ``m`` -- integer; number of blocks (at least one). + - ``m`` -- integer; number of blocks (at least one) - - ``k`` -- integer; minimum number of vertices of a block (at least two). + - ``k`` -- integer; minimum number of vertices of a block (at least two) - - ``kmax`` -- integer (default: ``None``) By default, each block has `k` + - ``kmax`` -- integer (default: ``None``); by default, each block has `k` vertices. When the parameter `kmax` is specified (with `kmax \geq k`), the number of vertices of each block is randomly chosen between `k` and `kmax`. - - ``incidence_structure`` -- boolean (default: ``False``) when set to + - ``incidence_structure`` -- boolean (default: ``False``); when set to ``True``, the incidence structure of the graphs is returned instead of the graph itself, that is the list of the lists of vertices in each block. This is useful for the creation of some hypergraphs. @@ -613,7 +612,7 @@ def RandomBoundedToleranceGraph(n, seed=None): INPUT: - - ``n`` -- number of vertices of the random graph. + - ``n`` -- number of vertices of the random graph - ``seed`` -- a ``random.Random`` seed or a Python ``int`` for the random number generator (default: ``None``) @@ -666,9 +665,9 @@ def RandomGNM(n, m, dense=False, seed=None): INPUT: - - ``n`` -- number of vertices. + - ``n`` -- number of vertices - - ``m`` -- number of edges. + - ``m`` -- number of edges - ``dense`` -- whether to use NetworkX's :func:`dense_gnm_random_graph` or :func:`gnm_random_graph` @@ -1068,7 +1067,7 @@ def compute_C(n, h): def growing_subtrees(T, k): r""" - Return a list of the vertex sets of ``n`` randomly chosen subtrees of ``T``. + Return a list of the vertex sets of `n` randomly chosen subtrees of `T`. For a tree of order `n`, the collection contains `n` subtrees with maximum order `k` and average order `\frac{k + 1}{2}`. @@ -1123,7 +1122,7 @@ def growing_subtrees(T, k): def connecting_nodes(T, l): r""" - Return a list of the vertex sets of ``n`` randomly chosen subtrees of ``T``. + Return a list of the vertex sets of `n` randomly chosen subtrees of `T`. This method is part of :meth:`~sage.graphs.generators.random.RandomChordalGraph`. @@ -1222,7 +1221,7 @@ def connecting_nodes(T, l): def pruned_tree(T, f, s): r""" - Return a list of the vertex sets of ``n`` randomly chosen subtrees of ``T``. + Return a list of the vertex sets of `n` randomly chosen subtrees of `T`. This method is part of :meth:`~sage.graphs.generators.random.RandomChordalGraph`. @@ -1244,7 +1243,7 @@ def pruned_tree(T, f, s): - ``T`` -- a tree - ``f`` -- a rational number; the edge deletion fraction. This value must be - chosen in `[0..1]`. + chosen in `[0..1]` - ``s`` -- a real number between 0 and 1; selection barrier for the size of trees @@ -1301,7 +1300,7 @@ def pruned_tree(T, f, s): return S -def RandomChordalGraph(n, algorithm="growing", k=None, l=None, f=None, s=None, seed=None): +def RandomChordalGraph(n, algorithm='growing', k=None, l=None, f=None, s=None, seed=None): r""" Return a random chordal graph of order ``n``. @@ -1321,23 +1320,23 @@ def RandomChordalGraph(n, algorithm="growing", k=None, l=None, f=None, s=None, s - ``n`` -- integer; the number of nodes of the graph - - ``algorithm`` -- string (default: ``"growing"``); the choice of the + - ``algorithm`` -- string (default: ``'growing'``); the choice of the algorithm for randomly selecting `n` subtrees of a random tree of order `n`. Possible choices are: - - ``"growing"`` -- for each subtree `T_i`, the algorithm picks a size + - ``'growing'`` -- for each subtree `T_i`, the algorithm picks a size `k_i` randomly from `[1,k]`. Then a random node of `T` is chosen as the first node of `T_i`. In each of the subsequent `k_i - 1` iterations, it picks a random node in the neighborhood of `T_i` and adds it to `T_i`. - - ``"connecting"`` -- for each subtree `T_i`, it first selects `k_i` nodes + - ``'connecting'`` -- for each subtree `T_i`, it first selects `k_i` nodes of `T`, where `k_i` is a random integer from a Poisson distribution with mean `l`. `T_i` is then generated to be the minimal subtree containing the selected `k_i` nodes. This implies that a subtree will most likely have many more nodes than those selected initially, and this must be taken into consideration when choosing `l`. - - ``"pruned"`` -- for each subtree `T_i`, it randomly selects a fraction + - ``'pruned'`` -- for each subtree `T_i`, it randomly selects a fraction `f` of the edges on the tree and removes them. The number of edges to delete, say `l`, is calculated as `\lfloor (n - 1) f \rfloor`, which will leave `l + 1` subtrees in total. Then, it determines the sizes of the `l @@ -1372,13 +1371,13 @@ def RandomChordalGraph(n, algorithm="growing", k=None, l=None, f=None, s=None, s EXAMPLES:: sage: from sage.graphs.generators.random import RandomChordalGraph - sage: T = RandomChordalGraph(20, algorithm="growing", k=5) + sage: T = RandomChordalGraph(20, algorithm='growing', k=5) sage: T.is_chordal() True - sage: T = RandomChordalGraph(20, algorithm="connecting", l=3) # needs numpy + sage: T = RandomChordalGraph(20, algorithm='connecting', l=3) # needs numpy sage: T.is_chordal() # needs numpy True - sage: T = RandomChordalGraph(20, algorithm="pruned", f=1/3, s=.5) + sage: T = RandomChordalGraph(20, algorithm='pruned', f=1/3, s=.5) sage: T.is_chordal() True @@ -1391,19 +1390,19 @@ def RandomChordalGraph(n, algorithm="growing", k=None, l=None, f=None, s=None, s Traceback (most recent call last): ... NotImplementedError: unknown algorithm 'Carmen Cru' - sage: RandomChordalGraph(3, algorithm="growing", k=0) + sage: RandomChordalGraph(3, algorithm='growing', k=0) Traceback (most recent call last): ... ValueError: parameter k must be >= 1 - sage: RandomChordalGraph(3, algorithm="connecting", l=0) + sage: RandomChordalGraph(3, algorithm='connecting', l=0) Traceback (most recent call last): ... ValueError: parameter l must be > 0 - sage: RandomChordalGraph(3, algorithm="pruned", f=2) + sage: RandomChordalGraph(3, algorithm='pruned', f=2) Traceback (most recent call last): ... ValueError: parameter f must be 0 <= f <= 1 - sage: RandomChordalGraph(3, algorithm="pruned", s=1) + sage: RandomChordalGraph(3, algorithm='pruned', s=1) Traceback (most recent call last): ... ValueError: parameter s must be 0 < s < 1 @@ -1485,15 +1484,12 @@ def RandomLobster(n, p, q, seed=None): - ``n`` -- expected number of vertices in the backbone - - ``p`` -- probability of adding an edge to the - backbone + - ``p`` -- probability of adding an edge to the backbone - - ``q`` -- probability of adding an edge (claw) to the - arms + - ``q`` -- probability of adding an edge (claw) to the arms - ``seed`` -- a ``random.Random`` seed or a Python ``int`` for the random - number generator (default: ``None``). - + number generator (default: ``None``) EXAMPLES: @@ -1527,7 +1523,7 @@ def RandomLobster(n, p, q, seed=None): def RandomTree(n, seed=None): r""" - Returns a random tree on `n` nodes numbered `0` through `n-1`. + Return a random tree on `n` nodes numbered `0` through `n-1`. By Cayley's theorem, there are `n^{n-2}` trees with vertex set `\{0,1,\dots,n-1\}`. This constructor chooses one of these uniformly @@ -1542,7 +1538,7 @@ def RandomTree(n, seed=None): INPUT: - - ``n`` -- number of vertices in the tree + - ``n`` -- number of vertices in the tree - ``seed`` -- a ``random.Random`` seed or a Python ``int`` for the random number generator (default: ``None``) @@ -1627,7 +1623,6 @@ def RandomTreePowerlaw(n, gamma=3, tries=1000, seed=None): - ``seed`` -- a ``random.Random`` seed or a Python ``int`` for the random number generator (default: ``None``) - EXAMPLES: We check that the generated graph is a tree:: @@ -1897,7 +1892,7 @@ def RandomShell(constructor, seed=None): INPUT: - - ``constructor`` -- a list of 3-tuples `(n, m, d)`, each representing a + - ``constructor`` -- list of 3-tuples `(n, m, d)`, each representing a shell, where: - ``n`` -- the number of vertices in the shell @@ -1995,9 +1990,9 @@ def _auxiliary_random_forest_word(n, k): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``k`` -- an integer + - ``k`` -- integer OUTPUT: @@ -2093,10 +2088,10 @@ def _contour_and_graph_from_words(pendant_word, forest_word): - ``seq`` is a sequence of pairs (label, integer) representing the contour walk along the `k`-gonal forest associated with the words - ``pendant_word`` and ``forest_word``. + ``pendant_word`` and ``forest_word`` - - ``G`` is the `k`-gonal forest associated with the words ``pendant_word`` - and ``forest_word``. + - ``G`` -- the `k`-gonal forest associated with the words ``pendant_word`` + and ``forest_word`` The underlying bijection from words to `k`-gonal forests is described in Section 5.1 of [PS2006]_. The ``pendant_word`` corresponds to the factor @@ -2232,8 +2227,8 @@ def RandomTriangulation(n, set_position=False, k=3, seed=None): - ``k`` -- the size of the outer face - - ``set_position`` -- boolean (default ``False``); if set to ``True``, this - will compute coordinates for a planar drawing of the graph. + - ``set_position`` -- boolean (default: ``False``); if set to ``True``, this + will compute coordinates for a planar drawing of the graph - ``seed`` -- a ``random.Random`` seed or a Python ``int`` for the random number generator (default: ``None``) @@ -2357,7 +2352,7 @@ def rotate_word_to_next_occurrence(word): assert graph.num_edges() == 3*n - 3 - k assert graph.num_verts() == n if set_position: - graph.layout(layout="planar", save_pos=True) + graph.layout(layout='planar', save_pos=True) return graph @@ -2381,13 +2376,11 @@ def blossoming_contour(t, shift=0, seed=None): INPUT: - - `t` -- a binary tree (non-empty) + - ``t`` -- a binary tree (non-empty) - - ``shift`` -- an integer (default `0`), used as a starting index - - OUTPUT: + - ``shift`` -- integer (default: `0`); used as a starting index - contour word of a random blossoming of `t` + OUTPUT: contour word of a random blossoming of `t` EXAMPLES:: @@ -2460,7 +2453,7 @@ def RandomBicubicPlanar(n, seed=None): INPUT: - `n` -- an integer (at least `1`) + - ``n`` -- integer (at least `1`) - ``seed`` -- a ``random.Random`` seed or a Python ``int`` for the random number generator (default: ``None``) @@ -2589,7 +2582,7 @@ def RandomUnitDiskGraph(n, radius=.1, side=1, seed=None): - ``n`` -- number of nodes - - ``radius`` -- float (default: ``0.1``); two vertices at distance less than + - ``radius`` -- float (default: `0.1`); two vertices at distance less than ``radius`` are connected by an edge - ``side`` -- float (default: ``1``); indicate the side of the area in which diff --git a/src/sage/graphs/generators/smallgraphs.py b/src/sage/graphs/generators/smallgraphs.py index 50b1905b7b0..c214edcaaa2 100644 --- a/src/sage/graphs/generators/smallgraphs.py +++ b/src/sage/graphs/generators/smallgraphs.py @@ -39,7 +39,6 @@ def HarborthGraph(): Harborth Graph: Graph on 52 vertices sage: g.is_regular(4) True - """ g = Graph(':s_OGKI?@_?g[QABAo__YEFCp@?iIEbqHWuWLbbh?}[OfcXpGhNHdYPY_SgdYX]' 'pZkfJPuo[lfZHys^mFcDs}`pG{UNNgoHC}DIgrI[qjMhTyDQrQlVydrBYmWkn', @@ -133,7 +132,7 @@ def HarriesGraph(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two embeddings are available, + - ``embedding`` -- integer (default: `1`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -252,7 +251,7 @@ def HarriesWongGraph(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two embeddings are available, + - ``embedding`` -- integer (default: `1`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -449,7 +448,7 @@ def Cell600(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two different embeddings for a + - ``embedding`` -- integer (default: `1`); two different embeddings for a plot EXAMPLES:: @@ -802,7 +801,7 @@ def Balaban10Cage(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two embeddings are available, + - ``embedding`` -- integer (default: `1`); two embeddings are available, and can be selected by setting ``embedding`` to be either 1 or 2 EXAMPLES:: @@ -870,7 +869,7 @@ def Balaban11Cage(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); three embeddings are available, + - ``embedding`` -- integer (default: `1`); three embeddings are available, and can be selected by setting ``embedding`` to be 1, 2, or 3 - The first embedding is the one appearing on page 9 of the Fifth Annual @@ -1111,7 +1110,7 @@ def BiggsSmithGraph(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two embeddings are available, + - ``embedding`` -- integer (default: `1`); two embeddings are available, and can be selected by setting ``embedding`` to be 1 or 2 EXAMPLES: @@ -1142,7 +1141,6 @@ def BiggsSmithGraph(embedding=1): Traceback (most recent call last): ... ValueError: the value of embedding must be 1 or 2 - """ L = [16, 24, -38, 17, 34, 48, -19, 41, -35, 47, -20, 34, -36, 21, 14, 48, -16, -36, -43, 28, -17, 21, 29, -43, 46, -24, @@ -1752,7 +1750,7 @@ def CameronGraph(): from sage.groups.perm_gps.permgroup_named import MathieuGroup from itertools import combinations g = Graph(name="Cameron Graph") - sets = MathieuGroup(22).orbit((1, 2, 3, 7, 10, 20), action="OnSets") + sets = MathieuGroup(22).orbit((1, 2, 3, 7, 10, 20), action='OnSets') for s in sets: for a, b, c, d in combinations(set(s), 4): g.add_edges([((a, b), (c, d)), ((a, c), (b, d)), ((a, d), (b, c))]) @@ -2196,7 +2194,7 @@ def EllinghamHorton54Graph(): 40: [41, 45, 46], 41: [47], 42: [48, 43], 43: [49, 44], 44: [50, 45], 45: [51], 46: [49], 50: [52], 51: [53], 52: [53]} - g = Graph(data=edge_dict, format="dict_of_lists", + g = Graph(data=edge_dict, format='dict_of_lists', name="Ellingham-Horton 54-graph") # The set of vertices on top is 0..15 @@ -2429,7 +2427,7 @@ def FlowerSnark(): d = {0: [1, 14, 15], 1: [2, 11], 2: [3, 7], 3: [2, 4, 16], 4: [5, 14], 5: [6, 10], 6: [5, 7, 17], 8: [7, 9, 13], 9: [10, 18], 11: [10, 12], 12: [13, 19], 13: [14], 15: [19], 16: [15, 17], 18: [17, 19]} - g = Graph(d, format="dict_of_lists", name="Flower Snark") + g = Graph(d, format='dict_of_lists', name="Flower Snark") g._circle_embedding(range(15), radius=2.5, angle=pi/2) g._circle_embedding(range(15, 20), radius=1, angle=pi/2) return g @@ -2718,7 +2716,7 @@ def GrayGraph(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two embeddings are available, + - ``embedding`` -- integer (default: `1`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -2986,9 +2984,7 @@ def HigmanSimsGraph(relabel=True): vertex `z` (zero through four) of that pentagon or pentagram. See [Haf2004]_ for more. - OUTPUT: - - The Higman-Sims graph. + OUTPUT: the Higman-Sims graph EXAMPLES: @@ -3419,7 +3415,7 @@ def LjubljanaGraph(embedding=1): INPUT: - - ``embedding`` -- integer (default: ``1``); two embeddings are available, + - ``embedding`` -- integer (default: `1`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -3515,7 +3511,7 @@ def LivingstoneGraph(): from sage.graphs.graph import Graph G = JankoGroup(1) g = Graph(name="Livingstone Graph") - g.add_edges(map(tuple, G.orbit((1, 24), action="OnSets"))) + g.add_edges(map(tuple, G.orbit((1, 24), action='OnSets'))) return g @@ -3541,7 +3537,7 @@ def M22Graph(): (77, 16, 0, 4) """ from sage.groups.perm_gps.permgroup_named import MathieuGroup - sets = [tuple(_) for _ in MathieuGroup(22).orbit((1, 2, 3, 7, 10, 20), action="OnSets")] + sets = [tuple(_) for _ in MathieuGroup(22).orbit((1, 2, 3, 7, 10, 20), action='OnSets')] g = Graph([sets, lambda x, y: not any(xx in y for xx in x)], name="M22 Graph") g.relabel() ordering = [0, 1, 3, 4, 5, 6, 7, 10, 12, 19, 20, 31, 2, 24, 35, 34, 22, 32, @@ -3611,7 +3607,7 @@ def McGeeGraph(embedding=2): INPUT: - - ``embedding`` -- integer (default: ``2``); two embeddings are available, + - ``embedding`` -- integer (default: `2`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -3825,7 +3821,7 @@ def NauruGraph(embedding=2): INPUT: - - ``embedding`` -- integer (default: ``2``); two embeddings are available, + - ``embedding`` -- integer (default: `2`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -4464,7 +4460,7 @@ def TutteCoxeterGraph(embedding=2): INPUT: - - ``embedding`` -- integer (default: ``2``); two embeddings are available, + - ``embedding`` -- integer (default: `2`); two embeddings are available, and can be selected by setting ``embedding`` to 1 or 2 EXAMPLES:: @@ -4768,7 +4764,6 @@ def MathonStronglyRegularGraph(t): sage: G = graphs.MathonStronglyRegularGraph(2) sage: G.is_strongly_regular(parameters=True) (784, 297, 116, 110) - """ from sage.graphs.generators.families import MathonPseudocyclicMergingGraph ES = _EllipticLinesProjectivePlaneScheme(3) @@ -4868,7 +4863,7 @@ def my_abs(M): return Graph([e for e, v in D.dict().items() if v == 1], multiedges=False, - name="Janko-Kharaghani") + name='Janko-Kharaghani') def JankoKharaghaniTonchevGraph(): @@ -5114,7 +5109,7 @@ def pi_vec(x): int_to_matrix[i + 1] = N(vec) M2 = matrix.block([[int_to_matrix[x] for x in R] for R in W.rows()]) - g = Graph(M2, name="Ionin-Kharaghani") + g = Graph(M2, name='Ionin-Kharaghani') return g @@ -5136,7 +5131,7 @@ def U42Graph216(): from sage.libs.gap.libgap import libgap from sage.features.gap import GapPackage - GapPackage("grape", spkg="gap_packages").require() + GapPackage("grape", spkg='gap_packages').require() adj_list = libgap.function_factory("""function() local gg, hl, o216, a216, x, h, re, G; @@ -5183,7 +5178,7 @@ def U42Graph540(): from sage.libs.gap.libgap import libgap from sage.features.gap import GapPackage - GapPackage("grape", spkg="gap_packages").require() + GapPackage("grape", spkg='gap_packages').require() adj_list = libgap.function_factory("""function() local f, o540, a540, x, oh, h, lo, G; diff --git a/src/sage/graphs/generators/world_map.py b/src/sage/graphs/generators/world_map.py index 588689d516c..5ccd80a0908 100644 --- a/src/sage/graphs/generators/world_map.py +++ b/src/sage/graphs/generators/world_map.py @@ -30,7 +30,7 @@ def AfricaMap(continental=False, year=2018): - ``continental`` -- boolean (default: ``False``); whether to only return states in the continental Africa or all African states - - ``year`` -- integer (default: ``2018``); reserved for future use + - ``year`` -- integer (default: 2018); reserved for future use EXAMPLES:: @@ -116,7 +116,7 @@ def EuropeMap(continental=False, year=2018): - ``continental`` -- boolean (default: ``False``); whether to only return states in the continental Europe or all European states - - ``year`` -- integer (default: ``2018``); reserved for future use + - ``year`` -- integer (default: 2018); reserved for future use EXAMPLES:: diff --git a/src/sage/graphs/generic_graph.py b/src/sage/graphs/generic_graph.py index 8904cff864a..46523fdfda5 100644 --- a/src/sage/graphs/generic_graph.py +++ b/src/sage/graphs/generic_graph.py @@ -80,7 +80,7 @@ :meth:`~GenericGraph.clear` | Empty the graph of vertices and edges and removes name, associated objects, and position information. :meth:`~GenericGraph.degree` | Return the degree (in + out for digraphs) of a vertex or of vertices. :meth:`~GenericGraph.average_degree` | Return the average degree of the graph. - :meth:`~GenericGraph.degree_histogram` | Return a list, whose ith entry is the frequency of degree i. + :meth:`~GenericGraph.degree_histogram` | Return a list, whose `i`-th entry is the frequency of degree i. :meth:`~GenericGraph.degree_iterator` | Return an iterator over the degrees of the (di)graph. :meth:`~GenericGraph.degree_sequence` | Return the degree sequence of this (di)graph. :meth:`~GenericGraph.random_subgraph` | Return a random subgraph containing each vertex with probability ``p``. @@ -90,8 +90,8 @@ :meth:`~GenericGraph.complement` | Return the complement of the (di)graph. :meth:`~GenericGraph.line_graph` | Return the line graph of the (di)graph. :meth:`~GenericGraph.to_simple` | Return a simple version of itself (i.e., undirected and loops and multiple edges are removed). - :meth:`~GenericGraph.disjoint_union` | Return the disjoint union of self and other. - :meth:`~GenericGraph.union` | Return the union of self and other. + :meth:`~GenericGraph.disjoint_union` | Return the disjoint union of ``self`` and ``other``. + :meth:`~GenericGraph.union` | Return the union of ``self`` and ``other``. :meth:`~GenericGraph.relabel` | Relabel the vertices of ``self`` :meth:`~GenericGraph.degree_to_cell` | Return the number of edges from vertex to an edge in cell. :meth:`~GenericGraph.subgraph` | Return the subgraph containing the given vertices and edges. @@ -104,11 +104,11 @@ :widths: 30, 70 :delim: | - :meth:`~GenericGraph.cartesian_product` | Return the Cartesian product of self and other. - :meth:`~GenericGraph.tensor_product` | Return the tensor product, also called the categorical product, of self and other. - :meth:`~GenericGraph.lexicographic_product` | Return the lexicographic product of self and other. - :meth:`~GenericGraph.strong_product` | Return the strong product of self and other. - :meth:`~GenericGraph.disjunctive_product` | Return the disjunctive product of self and other. + :meth:`~GenericGraph.cartesian_product` | Return the Cartesian product of ``self`` and ``other``. + :meth:`~GenericGraph.tensor_product` | Return the tensor product, also called the categorical product, of ``self`` and ``other``. + :meth:`~GenericGraph.lexicographic_product` | Return the lexicographic product of ``self`` and ``other``. + :meth:`~GenericGraph.strong_product` | Return the strong product of ``self`` and ``other``. + :meth:`~GenericGraph.disjunctive_product` | Return the disjunctive product of ``self`` and ``other``. **Paths and cycles:** @@ -161,10 +161,10 @@ :widths: 30, 70 :delim: | - :meth:`~GenericGraph.coarsest_equitable_refinement` | Return the coarsest partition which is finer than the input partition, and equitable with respect to self. + :meth:`~GenericGraph.coarsest_equitable_refinement` | Return the coarsest partition which is finer than the input partition, and equitable with respect to ``self``. :meth:`~GenericGraph.automorphism_group` | Return the largest subgroup of the automorphism group of the (di)graph whose orbit partition is finer than the partition given. - :meth:`~GenericGraph.is_vertex_transitive` | Return whether the automorphism group of self is transitive within the partition provided - :meth:`~GenericGraph.is_isomorphic` | Test for isomorphism between self and other. + :meth:`~GenericGraph.is_vertex_transitive` | Return whether the automorphism group of ``self`` is transitive within the partition provided + :meth:`~GenericGraph.is_isomorphic` | Test for isomorphism between ``self`` and ``other``. :meth:`~GenericGraph.canonical_label` | Return the canonical graph. :meth:`~GenericGraph.is_cayley` | Check whether the graph is a Cayley graph. @@ -189,7 +189,7 @@ :meth:`~GenericGraph.is_geodetic` | Check whether the input (di)graph is geodetic. :meth:`~GenericGraph.is_independent_set` | Check whether ``vertices`` is an independent set of ``self`` :meth:`~GenericGraph.is_transitively_reduced` | Test whether the digraph is transitively reduced. - :meth:`~GenericGraph.is_equitable` | Check whether the given partition is equitable with respect to self. + :meth:`~GenericGraph.is_equitable` | Check whether the given partition is equitable with respect to ``self``. :meth:`~GenericGraph.is_self_complementary` | Check whether the graph is self-complementary. **Traversals:** @@ -214,7 +214,7 @@ :delim: | :meth:`~GenericGraph.centrality_betweenness` | Return the betweenness centrality - :meth:`~GenericGraph.centrality_closeness` | Returns the closeness centrality (1/average distance to all vertices) + :meth:`~GenericGraph.centrality_closeness` | Return the closeness centrality (1/average distance to all vertices) :meth:`~GenericGraph.distance` | Return the (directed) distance from u to v in the (di)graph :meth:`~GenericGraph.distance_all_pairs` | Return the distances between all pairs of vertices. :meth:`~GenericGraph.distances_distribution` | Return the distances distribution of the (di)graph in a dictionary. @@ -243,8 +243,8 @@ :meth:`~GenericGraph.connected_components_sizes` | Return the sizes of the connected components as a list. :meth:`~GenericGraph.blocks_and_cut_vertices` | Compute the blocks and cut vertices of the graph. :meth:`~GenericGraph.blocks_and_cuts_tree` | Compute the blocks-and-cuts tree of the graph. - :meth:`~GenericGraph.is_cut_edge` | Return True if the input edge is a cut-edge or a bridge. - :meth:`~GenericGraph.is_cut_vertex` | Return True if the input vertex is a cut-vertex. + :meth:`~GenericGraph.is_cut_edge` | Return ``True`` if the input edge is a cut-edge or a bridge. + :meth:`~GenericGraph.is_cut_vertex` | Return ``True`` if the input vertex is a cut-vertex. :meth:`~GenericGraph.edge_cut` | Return a minimum edge cut between vertices `s` and `t` :meth:`~GenericGraph.vertex_cut` | Return a minimum vertex cut between non-adjacent vertices `s` and `t` :meth:`~GenericGraph.flow` | Return a maximum flow in the graph from ``x`` to ``y`` @@ -257,7 +257,7 @@ :meth:`~GenericGraph.transitive_reduction` | Return a transitive reduction of a graph. :meth:`~GenericGraph.min_spanning_tree` | Return the edges of a minimum spanning tree. :meth:`~GenericGraph.spanning_trees_count` | Return the number of spanning trees in a graph. - :meth:`~GenericGraph.dominator_tree` | Returns a dominator tree of the graph. + :meth:`~GenericGraph.dominator_tree` | Return a dominator tree of the graph. :meth:`~GenericGraph.connected_subgraph_iterator` | Iterator over the induced connected subgraphs of order at most `k` **Plot/embedding-related methods:** @@ -488,7 +488,7 @@ def __init__(self): def __setstate__(self, state): r""" - Set the state from a pickle dict + Set the state from a pickle dict. TESTS:: @@ -503,7 +503,7 @@ def __setstate__(self, state): def __add__(self, other): """ - Return a graph isomorphic to disjoint union of this graph with `other`. + Return a graph isomorphic to disjoint union of this graph with ``other``. Labels of the resulting graph will always be consecutive integers starting from zero. @@ -540,18 +540,19 @@ def __add__(self, other): def __eq__(self, other): """ - Compare self and other for equality. + Compare ``self`` and ``other`` for equality. Do not call this method directly. That is, for ``G.__eq__(H)`` write ``G == H``. Two graphs are considered equal if the following hold: - - they are either both directed, or both undirected; - - they have the same settings for loops, multiedges, and weightedness; - - they have the same set of vertices; - - they have the same (multi)set of arrows/edges, where labels of - arrows/edges are taken into account if *and only if* the graphs are - considered weighted. See :meth:`~GenericGraph.weighted`. + + - they are either both directed, or both undirected + - they have the same settings for loops, multiedges, and weightedness + - they have the same set of vertices + - they have the same (multi)set of arrows/edges, where labels of + arrows/edges are taken into account if *and only if* the graphs are + considered weighted. See :meth:`~GenericGraph.weighted`. Note that this is *not* an isomorphism test. @@ -600,7 +601,6 @@ def __eq__(self, other): sage: bar.weighted(True) sage: foo == bar False - """ # inputs must be (di)graphs: if not isinstance(other, GenericGraph): @@ -666,7 +666,7 @@ def __hash__(self): ... TypeError: This graph is mutable, and thus not hashable. Create an immutable copy by `g.copy(immutable=True)` - sage: G_imm = Graph(G, data_structure="static_sparse") + sage: G_imm = Graph(G, data_structure='static_sparse') sage: G_imm == G True sage: {G_imm: 1}[G_imm] # indirect doctest @@ -677,9 +677,9 @@ def __hash__(self): TESTS: Equality and hash do not depend on ordering of vertices. In other words, - `G1 == G2` can be `True` even when + `G1 == G2` can be ``True`` even when `G1.vertices(sort=True) == G2.vertices(sort=True)` is - `False`. This is parts 1 and 2 of issue :issue:`17086`. :: + ``False``. This is parts 1 and 2 of issue :issue:`17086`. :: sage: import functools sage: @functools.total_ordering @@ -1013,7 +1013,7 @@ def is_immutable(self): def copy(self, weighted=None, data_structure=None, sparse=None, immutable=None, hash_labels=None): """ - Change the graph implementation + Change the graph implementation. INPUT: @@ -1024,8 +1024,8 @@ def copy(self, weighted=None, data_structure=None, sparse=None, immutable=None, for ``data_structure="sparse"``, and ``sparse=False`` is an alias for ``data_structure="dense"``. Only used when ``data_structure=None``. - - ``data_structure`` -- string (default: ``None``); one of ``"sparse"``, - ``"static_sparse"``, or ``"dense"``. See the documentation of + - ``data_structure`` -- string (default: ``None``); one of ``'sparse'``, + ``'static_sparse'``, or ``'dense'``. See the documentation of :class:`Graph` or :class:`DiGraph`. - ``immutable`` -- boolean (default: ``None``); whether to create a @@ -1039,7 +1039,7 @@ def copy(self, weighted=None, data_structure=None, sparse=None, immutable=None, * ``immutable=False`` means that the created graph is mutable. When used to copy an immutable graph, the data structure used is - ``"sparse"`` unless anything else is specified. + ``'sparse'`` unless anything else is specified. - ``hash_labels`` -- boolean (default: ``None``); whether to include edge labels during hashing of the copy. This parameter defaults to @@ -1054,9 +1054,7 @@ def copy(self, weighted=None, data_structure=None, sparse=None, immutable=None, and the ``_immutable`` flag, then ``self`` is returned rather than a copy (unless one of the optional arguments is used). - OUTPUT: - - A Graph object. + OUTPUT: a Graph object .. WARNING:: @@ -1168,11 +1166,11 @@ def copy(self, weighted=None, data_structure=None, sparse=None, immutable=None, Bad input:: - sage: G.copy(data_structure="sparse", sparse=False) + sage: G.copy(data_structure='sparse', sparse=False) Traceback (most recent call last): ... ValueError: you cannot define 'immutable' or 'sparse' when 'data_structure' has a value - sage: G.copy(data_structure="sparse", immutable=True) + sage: G.copy(data_structure='sparse', immutable=True) Traceback (most recent call last): ... ValueError: you cannot define 'immutable' or 'sparse' when 'data_structure' has a value @@ -1183,11 +1181,11 @@ def copy(self, weighted=None, data_structure=None, sparse=None, immutable=None, Which backend? :: - sage: G.copy(data_structure="sparse")._backend + sage: G.copy(data_structure='sparse')._backend - sage: G.copy(data_structure="dense")._backend + sage: G.copy(data_structure='dense')._backend - sage: G.copy(data_structure="static_sparse")._backend + sage: G.copy(data_structure='static_sparse')._backend sage: G.copy(immutable=True)._backend @@ -1370,13 +1368,13 @@ def export_to_file(self, filename, format=None, **kwds): EXAMPLES:: sage: g = graphs.PetersenGraph() - sage: filename = tmp_filename(ext=".pajek") + sage: filename = tmp_filename(ext='.pajek') sage: g.export_to_file(filename) # needs networkx sage: import networkx # needs networkx sage: G_networkx = networkx.read_pajek(filename) # needs networkx sage: Graph(G_networkx).is_isomorphic(g) # needs networkx True - sage: filename = tmp_filename(ext=".edgelist") + sage: filename = tmp_filename(ext='.edgelist') sage: g.export_to_file(filename, data=False) # needs networkx sage: h = Graph(networkx.read_edgelist(filename)) # needs networkx sage: g.is_isomorphic(h) # needs networkx @@ -1505,7 +1503,7 @@ def networkx_graph(self, weight_function=None): INPUT: - ``weight_function`` -- function (default: ``None``); a function that - takes as input an edge ``(u, v, l)`` and outputs its weight. + takes as input an edge ``(u, v, l)`` and outputs its weight EXAMPLES:: @@ -1528,7 +1526,6 @@ def networkx_graph(self, weight_function=None): OutMultiEdgeDataView([(1, 2, {'weight': 1}), (1, 3, {'weight': 4}), (2, 3, {'weight': 3}), (3, 4, {'weight': 5}), (3, 4, {'weight': 4})]) - """ if weight_function is not None: self._check_weight_function(weight_function) @@ -1569,12 +1566,12 @@ def igraph_graph(self, vertex_list=None, vertex_attrs={}, edge_attrs={}): This routine needs the optional package igraph to be installed: to do so, it is enough to run ``sage -i python_igraph``. For more information on the Python version of igraph, see - http://igraph.org/python/. + https://python.igraph.org/. INPUT: - ``vertex_list`` -- list (default: ``None``); defines a mapping from - the vertices of the graph to consecutive integers in ``(0, \ldots, + the vertices of the graph to consecutive integers in `(0, \ldots, n-1)`. Otherwise, the result of :meth:`vertices` will be used instead. Because :meth:`vertices` only works if the vertices can be sorted, using ``vertex_list`` is useful when working with possibly @@ -1585,25 +1582,25 @@ def igraph_graph(self, vertex_list=None, vertex_attrs={}, edge_attrs={}): containing in position `i` the label of the `i`-th vertex in the list ``vertex_list`` if it is given or in :meth:`vertices` when ``vertex_list == None`` (see - http://igraph.org/python/doc/igraph.Graph-class.html#__init__ for more + https://python.igraph.org/en/stable/api/igraph.Graph.html#__init__ for more information) - ``edge_attrs`` -- dictionary (default: ``{}``); a dictionary where the key is a string (the attribute name), and the value is an iterable containing in position `i` the label of the `i`-th edge in the list outputted by :meth:`edge_iterator` (see - http://igraph.org/python/doc/igraph.Graph-class.html#__init__ for more + https://python.igraph.org/en/stable/api/igraph.Graph.html#__init__ for more information) .. NOTE:: - In ``igraph``, a graph is weighted if the edge labels have attribute - ``weight``. Hence, to create a weighted graph, it is enough to add - this attribute. + In ``igraph``, a graph is weighted if the edge attribute ``weight`` is + present. Hence, to create a weighted graph, it is enough to add this + attribute. .. NOTE:: - Often, Sage uses its own defined types for integer/floats. These + Often, Sage uses its own defined types for integers/floats. These types may not be igraph-compatible (see example below). EXAMPLES: @@ -1654,7 +1651,7 @@ def igraph_graph(self, vertex_list=None, vertex_attrs={}, edge_attrs={}): sage: H.vs()['name'] == V # optional - python_igraph True - Sometimes, Sage integer/floats are not compatible with igraph:: + Sometimes, Sage integers/floats are not compatible with igraph:: sage: G = Graph([(0, 1, 2)]) sage: E = list(G.edge_iterator()) @@ -1752,9 +1749,7 @@ def to_dictionary(self, edge_labels=False, multiple_edges=False): - ``multiple_edges`` -- boolean (default: ``False``); whether to include multiple edges in the output - OUTPUT: - - The output depends on the input: + OUTPUT: the output depends on the input: * If ``edge_labels == False`` and ``multiple_edges == False``, the output is a dictionary associating to each vertex the list of its @@ -1910,7 +1905,7 @@ def _vertex_indices_and_keys(self, vertices=None, *, sort=None): INPUT: - - ``vertices`` -- list, ``None``, or ``True`` (default: ``None``) + - ``vertices`` -- list; ``None``, or ``True`` (default: ``None``) - when a list, the `i`-th row and column of the matrix correspond to the `i`-th vertex in the ordering of ``vertices``, @@ -1921,11 +1916,11 @@ def _vertex_indices_and_keys(self, vertices=None, *, sort=None): a matrix, where the module's basis is indexed by the vertices. - ``sort`` -- boolean or ``None`` (default); passed to :meth:`vertices` - when ``vertices`` is not a list. + when ``vertices`` is not a list OUTPUT: pair of: - - ``vertex_indices`` -- a dictionary mapping vertices to numerical indices, + - ``vertex_indices`` -- dictionary mapping vertices to numerical indices, - ``keys`` -- either a tuple of basis keys (when using a :class:`CombinatorialFreeModule`) or ``None`` (when using a :class:`FreeModule`, :func:`matrix`). @@ -1977,7 +1972,7 @@ def adjacency_matrix(self, sparse=None, vertices=None, *, base_ring=None, **kwds - ``sparse`` -- boolean (default: ``None``); whether to represent with a sparse matrix - - ``vertices`` -- list, ``None``, or ``True`` (default: ``None``); + - ``vertices`` -- list; ``None``, or ``True`` (default: ``None``) - when a list, the `i`-th row and column of the matrix correspond to the `i`-th vertex in the ordering of ``vertices``, @@ -1988,14 +1983,14 @@ def adjacency_matrix(self, sparse=None, vertices=None, *, base_ring=None, **kwds a matrix, where the module's basis is indexed by the vertices. If the vertices are not comparable, the keyword ``vertices`` must be - used to specify an ordering, or a :class:`TypeError` exception will + used to specify an ordering, or a :exc:`TypeError` exception will be raised. - ``base_ring`` -- a ring (default: ``ZZ``); the base ring of the matrix - space to use. + space to use - ``**kwds`` -- other keywords to pass to - :func:`~sage.matrix.constructor.matrix`. + :func:`~sage.matrix.constructor.matrix` EXAMPLES:: @@ -2208,7 +2203,7 @@ def incidence_matrix(self, oriented=None, sparse=True, vertices=None, edges=None - ``sparse`` -- boolean (default: ``True``); whether to use a sparse or a dense matrix - - ``vertices`` -- list, ``None``, or ``True`` (default: ``None``); + - ``vertices`` -- list; ``None``, or ``True`` (default: ``None``) - when a list, the `i`-th row of the matrix corresponds to the `i`-th vertex in the ordering of ``vertices``, @@ -2217,7 +2212,7 @@ def incidence_matrix(self, oriented=None, sparse=True, vertices=None, edges=None - when ``True``, construct a morphism of free modules instead of a matrix, where the codomain's basis is indexed by the vertices. - - ``edges`` -- list, ``None``, or ``True`` (default: ``None``); + - ``edges`` -- list; ``None``, or ``True`` (default: ``None``) - when a list, the `i`-th column of the matrix corresponds to the `i`-th edge in the ordering of ``edges``, @@ -2227,10 +2222,10 @@ def incidence_matrix(self, oriented=None, sparse=True, vertices=None, edges=None where the domain's basis is indexed by the edges. - ``base_ring`` -- a ring (default: ``ZZ``); the base ring of the matrix - space to use. + space to use - ``**kwds`` -- other keywords to pass to - :func:`~sage.matrix.constructor.matrix`. + :func:`~sage.matrix.constructor.matrix` EXAMPLES:: @@ -2470,7 +2465,7 @@ def distance_matrix(self, vertices=None, *, base_ring=None, **kwds): when working with possibly non-sortable objects in Python 3. - ``base_ring`` -- a ring (default: determined from the weights); the base - ring of the matrix space to use. + ring of the matrix space to use - ``**kwds`` -- other keywords to pass to the subfunction :meth:`distance_all_pairs` or to @@ -2597,7 +2592,7 @@ def weighted_adjacency_matrix(self, sparse=True, vertices=None, - ``sparse`` -- boolean (default: ``True``); whether to use a sparse or a dense matrix - - ``vertices`` -- list, ``None``, or ``True`` (default: ``None``); + - ``vertices`` -- list; ``None``, or ``True`` (default: ``None``) - when a list, the `i`-th row and column of the matrix correspond to the `i`-th vertex in the ordering of ``vertices``, @@ -2608,15 +2603,15 @@ def weighted_adjacency_matrix(self, sparse=True, vertices=None, a matrix, where the module's basis is indexed by the vertices. If the vertices are not comparable, the keyword ``vertices`` must be - used to specify an ordering, or a :class:`TypeError` exception will + used to specify an ordering, or a :exc:`TypeError` exception will be raised. - - ``default_weight`` -- (default: ``None``); specifies the weight to + - ``default_weight`` -- (default: ``None``) specifies the weight to replace any ``None`` edge label. When not specified an error is raised if the label of an edge is ``None``. - ``base_ring`` -- a ring (default: determined from the weights); the base - ring of the matrix space to use. + ring of the matrix space to use - ``**kwds`` -- other keywords to pass to :func:`~sage.matrix.constructor.matrix` @@ -2762,7 +2757,7 @@ def kirchhoff_matrix(self, weighted=None, indegree=True, normalized=False, signl INPUT: - - ``weighted`` -- boolean (default: ``None``); + - ``weighted`` -- boolean (default: ``None``) - If ``True``, the weighted adjacency matrix is used for `M`, and the diagonal matrix `D` takes into account the weight of edges (replace @@ -2774,7 +2769,7 @@ def kirchhoff_matrix(self, weighted=None, indegree=True, normalized=False, signl is weighted. - ``indegree`` -- boolean (default: ``True``); this parameter is - considered only for digraphs. + considered only for digraphs - If ``True``, each diagonal entry of `D` is equal to the in-degree of the corresponding vertex @@ -2784,7 +2779,7 @@ def kirchhoff_matrix(self, weighted=None, indegree=True, normalized=False, signl By default, ``indegree`` is set to ``True`` - - ``normalized`` -- boolean (default: ``False``); + - ``normalized`` -- boolean (default: ``False``) - If ``True``, the returned matrix is `D^{-1/2}(D+M)D^{-1/2}` for signless and `D^{-1/2}(D-M)D^{-1/2}` otherwise, a normalized @@ -2795,13 +2790,13 @@ def kirchhoff_matrix(self, weighted=None, indegree=True, normalized=False, signl - Else, the matrix `D+M` for signless and `D-M` otherwise is returned - - ``signless`` -- boolean (default: ``False``); + - ``signless`` -- boolean (default: ``False``) - If ``True``, `D+M` is used in calculation of Kirchhoff matrix - Else, `D-M` is used in calculation of Kirchhoff matrix - - ``vertices`` -- list, ``None``, or ``True`` (default: ``None``); + - ``vertices`` -- list; ``None``, or ``True`` (default: ``None``) - when a list, the `i`-th row and column of the matrix correspond to the `i`-th vertex in the ordering of ``vertices``, @@ -2812,7 +2807,7 @@ def kirchhoff_matrix(self, weighted=None, indegree=True, normalized=False, signl a matrix, where the module's basis is indexed by the vertices. If the vertices are not comparable, the keyword ``vertices`` must be - used to specify an ordering, or a :class:`TypeError` exception will + used to specify an ordering, or a :exc:`TypeError` exception will be raised. Note that any additional keywords will be passed on to either the @@ -2911,7 +2906,6 @@ def kirchhoff_matrix(self, weighted=None, indegree=True, normalized=False, signl B⎜-1 3 -2 0⎟ C⎜-3 -2 5 0⎟ D⎝-4 0 0 4⎠ - """ from sage.matrix.constructor import diagonal_matrix, matrix @@ -3109,8 +3103,8 @@ def _check_embedding_validity(self, embedding=None, boolean=True): test. If set to ``None`` (default), the test is performed on ``_embedding`` - - ``boolean`` -- boolean (default: ``True``); -- whether to return a - boolean answer or raise a :class:`ValueError` exception + - ``boolean`` -- boolean (default: ``True``); whether to return a + boolean answer or raise a :exc:`ValueError` exception if the embedding is invalid EXAMPLES:: @@ -3149,7 +3143,6 @@ def _check_embedding_validity(self, embedding=None, boolean=True): Traceback (most recent call last): ... ValueError: the list associated with vertex 1 contains >1 occurrences of [0] - """ if embedding is None: try: @@ -3199,7 +3192,7 @@ def connected(u, v): def has_loops(self): """ - Return whether there are loops in the (di)graph + Return whether there are loops in the (di)graph. EXAMPLES:: @@ -3243,7 +3236,7 @@ def has_loops(self): def allows_loops(self): """ - Return whether loops are permitted in the (di)graph + Return whether loops are permitted in the (di)graph. EXAMPLES:: @@ -3287,7 +3280,7 @@ def allows_loops(self): def allow_loops(self, new, check=True): """ - Change whether loops are permitted in the (di)graph + Change whether loops are permitted in the (di)graph. INPUT: @@ -3340,7 +3333,7 @@ def allow_loops(self, new, check=True): def loop_edges(self, labels=True): """ - Return a list of all loops in the (di)graph + Return a list of all loops in the (di)graph. INPUT: @@ -3425,7 +3418,7 @@ def loop_edges(self, labels=True): def number_of_loops(self): """ - Return the number of edges that are loops + Return the number of edges that are loops. EXAMPLES:: @@ -3449,7 +3442,7 @@ def number_of_loops(self): def loop_vertices(self): """ - Return a list of vertices with loops + Return a list of vertices with loops. EXAMPLES:: @@ -3620,7 +3613,7 @@ def allow_multiple_edges(self, new, check=True, keep_label='any'): .. WARNING:: ``'min'`` and ``'max'`` only works if the labels can be compared. A - :class:`TypeError` might be raised when working with non-comparable + :exc:`TypeError` might be raised when working with non-comparable objects. EXAMPLES: @@ -4152,7 +4145,7 @@ def weighted(self, new=None): sage: H.weighted(True) sage: H == G False - sage: G_imm = Graph(G, data_structure="static_sparse") + sage: G_imm = Graph(G, data_structure='static_sparse') sage: G_imm == G True sage: G_imm.weighted() @@ -4170,7 +4163,6 @@ def weighted(self, new=None): False sage: G_mut == H True - """ if new is not None: if self.is_immutable(): @@ -4665,13 +4657,13 @@ def eulerian_circuit(self, return_vertices=False, labels=True, path=False): INPUT: - ``return_vertices`` -- boolean (default: ``False``); optionally - provide a list of vertices for the path + provide a list of vertices for the path - ``labels`` -- boolean (default: ``True``); whether to return edges - with labels (3-tuples) + with labels (3-tuples) - ``path`` -- boolean (default: ``False``); find an Eulerian path - instead + instead OUTPUT: @@ -4806,7 +4798,7 @@ def eulerian_circuit(self, return_vertices=False, labels=True, path=False): def min_spanning_tree(self, weight_function=None, - algorithm="Prim_Boost", + algorithm='Prim_Boost', starting_vertex=None, check=False, by_weight=False, @@ -4823,24 +4815,24 @@ def min_spanning_tree(self, INPUT: - - ``algorithm`` -- string (default: ``"Prim_Boost"``); the algorithm to + - ``algorithm`` -- string (default: ``'Prim_Boost'``); the algorithm to use in computing a minimum spanning tree of ``G``. The following algorithms are supported: - - ``"Prim_Boost"`` -- Prim's algorithm (Boost implementation) + - ``'Prim_Boost'`` -- Prim's algorithm (Boost implementation) - - ``"Prim_fringe"`` -- a variant of Prim's algorithm that ignores the + - ``'Prim_fringe'`` -- a variant of Prim's algorithm that ignores the labels on the edges - - ``"Prim_edge"`` -- a variant of Prim's algorithm + - ``'Prim_edge'`` -- a variant of Prim's algorithm - - ``"Kruskal"`` -- Kruskal's algorithm + - ``'Kruskal'`` -- Kruskal's algorithm - - ``"Filter_Kruskal"`` -- a variant of Kruskal's algorithm [OSS2009]_ + - ``'Filter_Kruskal'`` -- a variant of Kruskal's algorithm [OSS2009]_ - - ``"Kruskal_Boost"`` -- Kruskal's algorithm (Boost implementation) + - ``'Kruskal_Boost'`` -- Kruskal's algorithm (Boost implementation) - - ``"Boruvka"`` -- Boruvka's algorithm + - ``'Boruvka'`` -- Boruvka's algorithm - ``NetworkX`` -- uses NetworkX's minimum spanning tree implementation @@ -4867,7 +4859,7 @@ def min_spanning_tree(self, in the graph are weighted, otherwise all edges have weight 1 - ``check_weight`` -- boolean (default: ``True``); whether to check that - the ``weight_function`` outputs a number for each edge. + the ``weight_function`` outputs a number for each edge OUTPUT: @@ -5463,7 +5455,7 @@ def minimum_cycle_basis(self, algorithm=None, weight_function=None, by_weight=Fa in the graph are weighted, otherwise all edges have weight 1 - ``check_weight`` -- boolean (default: ``True``); whether to check that - the ``weight_function`` outputs a number for each edge. + the ``weight_function`` outputs a number for each edge EXAMPLES:: @@ -5789,7 +5781,7 @@ def is_circular_planar(self, on_embedding=None, kuratowski=False, set_embedding=True, boundary=None, ordered=False, set_pos=False): r""" - Check whether the graph is circular planar (outerplanar) + Check whether the graph is circular planar (outerplanar). A graph is circular planar if it has a planar embedding in which all vertices can be drawn in order on a circle. This method can also be used @@ -6135,7 +6127,6 @@ def layout_planar(self, set_embedding=False, on_embedding=None, Traceback (most recent call last): ... ValueError: Petersen graph is not a planar graph - """ from sage.graphs.graph import Graph from sage.graphs.schnyder import _triangulate, _normal_label, _realizer, _compute_coordinates @@ -6365,7 +6356,7 @@ def genus(self, set_embedding=True, on_embedding=None, minimal=True, maximal=Fal - ``ordered`` -- boolean (default: ``True``); if ``circular`` is ``True``, then whether or not the boundary order may be permuted - (default is ``True``, which means the boundary order is preserved) + (default: ``True``, which means the boundary order is preserved) EXAMPLES:: @@ -6434,7 +6425,6 @@ def genus(self, set_embedding=True, on_embedding=None, minimal=True, maximal=Fal sage: G = graphs.RandomBlockGraph(10, 5) sage: G.genus() 10 - """ if not self.is_connected(): raise TypeError("the input Graph must be connected to use Euler's Formula to compute minimal genus") @@ -6922,7 +6912,6 @@ def planar_dual(self, embedding=None): Implement the method for graphs that are not 3-vertex-connected, or at least have a faster 3-vertex-connectivity test (:issue:`24635`). - """ self._scream_if_not_simple() @@ -6960,15 +6949,14 @@ def steiner_tree(self, vertices, weighted=False, solver=None, verbose=0, INPUT: - - ``vertices`` -- the vertices to be connected by the Steiner - Tree. + - ``vertices`` -- the vertices to be connected by the Steiner Tree - ``weighted`` -- boolean (default: ``False``); whether to consider the graph as weighted, and use each edge's label as a weight, considering ``None`` as a weight of `1`. If ``weighted=False`` (default) all edges are considered to have a weight of `1`. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -6976,7 +6964,7 @@ def steiner_tree(self, vertices, weighted=False, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7116,21 +7104,21 @@ def edge_disjoint_spanning_trees(self, k, algorithm=None, root=None, solver=None - ``algorithm`` -- string (default: ``None``); specify the algorithm to use among: - * ``"Roskind-Tarjan"`` -- use the algorithm proposed by Roskind and + * ``'Roskind-Tarjan'`` -- use the algorithm proposed by Roskind and Tarjan [RT1985]_ for finding edge-disjoint spanning-trees in undirected simple graphs in time `O(m\log{m} + k^2n^2)`. - * ``"MILP"`` -- use a mixed integer linear programming + * ``'MILP'`` -- use a mixed integer linear programming formulation. This is the default method for directed graphs. - * ``None`` -- use ``"Roskind-Tarjan"`` for undirected graphs and - ``"MILP"`` for directed graphs. + * ``None`` -- use ``'Roskind-Tarjan'`` for undirected graphs and + ``'MILP'`` for directed graphs. - ``root`` -- vertex (default: ``None``); root of the disjoint arborescences when the graph is directed. If set to ``None``, the first vertex in the graph is picked. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7138,7 +7126,7 @@ def edge_disjoint_spanning_trees(self, k, algorithm=None, root=None, solver=None :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7207,12 +7195,12 @@ def edge_disjoint_spanning_trees(self, k, algorithm=None, root=None, solver=None sage: # needs sage.numerical.mip sage: g = graphs.RandomGNP(12, .7) sage: k = Integer(g.edge_connectivity()) // 2 - sage: trees = g.edge_disjoint_spanning_trees(k, algorithm="MILP") + sage: trees = g.edge_disjoint_spanning_trees(k, algorithm='MILP') sage: all(t.is_tree() for t in trees) True sage: all(g.order() == t.size() + 1 for t in trees) True - sage: trees = g.edge_disjoint_spanning_trees(k, algorithm="Roskind-Tarjan") + sage: trees = g.edge_disjoint_spanning_trees(k, algorithm='Roskind-Tarjan') sage: all(t.is_tree() for t in trees) True sage: all(g.order() == t.size() + 1 for t in trees) @@ -7258,19 +7246,19 @@ def edge_disjoint_spanning_trees(self, k, algorithm=None, root=None, solver=None sage: # needs sage.numerical.mip sage: Graph().edge_disjoint_spanning_trees(0, algorithm=None) [] - sage: Graph().edge_disjoint_spanning_trees(0, algorithm="Roskind-Tarjan") + sage: Graph().edge_disjoint_spanning_trees(0, algorithm='Roskind-Tarjan') [] - sage: Graph().edge_disjoint_spanning_trees(0, algorithm="MILP") + sage: Graph().edge_disjoint_spanning_trees(0, algorithm='MILP') [] - sage: Graph().edge_disjoint_spanning_trees(0, algorithm="foo") + sage: Graph().edge_disjoint_spanning_trees(0, algorithm='foo') Traceback (most recent call last): ... ValueError: algorithm must be None, "Rosking-Tarjan" or "MILP" for undirected graphs sage: DiGraph().edge_disjoint_spanning_trees(0, algorithm=None) [] - sage: DiGraph().edge_disjoint_spanning_trees(0, algorithm="MILP") + sage: DiGraph().edge_disjoint_spanning_trees(0, algorithm='MILP') [] - sage: DiGraph().edge_disjoint_spanning_trees(0, algorithm="foo") + sage: DiGraph().edge_disjoint_spanning_trees(0, algorithm='foo') Traceback (most recent call last): ... ValueError: algorithm must be None or "MILP" for directed graphs @@ -7383,11 +7371,11 @@ def edge_disjoint_spanning_trees(self, k, algorithm=None, root=None, solver=None return classes def edge_cut(self, s, t, value_only=True, use_edge_labels=False, vertices=False, - algorithm="FF", solver=None, verbose=0, *, integrality_tolerance=1e-3): + algorithm='FF', solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return a minimum edge cut between vertices `s` and `t`. - A minimum edge cut between two vertices `s` and `t` of self is a set `A` + A minimum edge cut between two vertices `s` and `t` of ``self`` is a set `A` of edges of minimum weight such that the graph obtained by removing `A` from the graph is disconnected. For more information, see the :wikipedia:`Cut_(graph_theory)`. @@ -7428,7 +7416,7 @@ def edge_cut(self, s, t, value_only=True, use_edge_labels=False, vertices=False, * If ``algorithm = None``, the problem is solved using the default maximum flow algorithm (see :meth:`flow`) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7436,7 +7424,7 @@ def edge_cut(self, s, t, value_only=True, use_edge_labels=False, vertices=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7499,7 +7487,7 @@ def edge_cut(self, s, t, value_only=True, use_edge_labels=False, vertices=False, If algorithm is set to an exotic value:: sage: g = graphs.PetersenGraph() - sage: g.edge_cut(0, 1, algorithm="Divination") + sage: g.edge_cut(0, 1, algorithm='Divination') Traceback (most recent call last): ... ValueError: the algorithm argument has to be equal to "FF", "LP", "igraph", or None @@ -7509,15 +7497,15 @@ def edge_cut(self, s, t, value_only=True, use_edge_labels=False, vertices=False, sage: g = graphs.RandomGNP(20,.3) sage: for u,v in g.edges(sort=True, labels=False): ....: g.set_edge_label(u,v,round(random(),5)) - sage: g.edge_cut(0, 1, algorithm="FF") == g.edge_cut(0, 1, algorithm="LP") # needs sage.numerical.mip + sage: g.edge_cut(0, 1, algorithm='FF') == g.edge_cut(0, 1, algorithm='LP') # needs sage.numerical.mip True - sage: g.edge_cut(0, 1, algorithm="FF") == g.edge_cut(0, 1, algorithm="igraph") # optional - python_igraph + sage: g.edge_cut(0, 1, algorithm='FF') == g.edge_cut(0, 1, algorithm='igraph') # optional - python_igraph True Rounded return value when using the LP method:: sage: g = graphs.PappusGraph() - sage: g.edge_cut(1, 2, value_only=True, algorithm="LP") # needs sage.numerical.mip + sage: g.edge_cut(1, 2, value_only=True, algorithm='LP') # needs sage.numerical.mip 3 :issue:`12797`:: @@ -7655,7 +7643,7 @@ def vertex_cut(self, s, t, value_only=True, vertices=False, solver=None, verbose the two sets of vertices that are disconnected by the cut. Implies ``value_only`` set to ``False``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7663,7 +7651,7 @@ def vertex_cut(self, s, t, value_only=True, vertices=False, solver=None, verbose :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7784,7 +7772,7 @@ def multiway_cut(self, vertices, value_only=False, use_edge_labels=False, defined by its label (if an edge has no label, `1` is assumed), or to compute a cut of minimum cardinality (i.e., edge weights are set to 1) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7792,7 +7780,7 @@ def multiway_cut(self, vertices, value_only=False, use_edge_labels=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7923,7 +7911,7 @@ def max_cut(self, value_only=True, use_edge_labels=False, vertices=False, two sets of vertices that are disconnected by the cut. This implies ``value_only=False``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7931,7 +7919,7 @@ def max_cut(self, value_only=True, use_edge_labels=False, vertices=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -8085,7 +8073,7 @@ def longest_cycle(self, induced=False, use_edge_labels=False, considered as a weight of `1`), or to compute a cycle with the largest possible number of edges (i.e., edge weights are set to 1) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -8093,8 +8081,8 @@ def longest_cycle(self, induced=False, use_edge_labels=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of - verbosity; set to ``0`` by default, which means quiet + - ``verbose`` -- integer (default: 0); sets the level of + verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers over an inexact base ring; see @@ -8372,7 +8360,7 @@ def F(e): best.set_pos({u: pp for u, pp in G.get_pos().items() if u in best}) return (best_w, best) if use_edge_labels else best - def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm="MILP", + def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm='MILP', solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return a longest path of ``self``. @@ -8384,14 +8372,14 @@ def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm="MILP", argument is set to ``None`` by default, which means that no constraint is set upon the first vertex in the path. - This parameter can only be used when ``algorithm`` is ``"MILP"``. + This parameter can only be used when ``algorithm`` is ``'MILP'``. - ``t`` -- a vertex (default: ``None``); forces the destination of the path (the method then returns the longest path ending at ``t``). The argument is set to ``None`` by default, which means that no constraint is set upon the last vertex in the path. - This parameter can only be used when ``algorithm`` is ``"MILP"``. + This parameter can only be used when ``algorithm`` is ``'MILP'``. - ``use_edge_labels`` -- boolean (default: ``False``); whether to compute a path with maximum weight where the weight of an edge is @@ -8399,21 +8387,21 @@ def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm="MILP", considered as a weight of `1`), or to compute a path with the longest possible number of edges (i.e., edge weights are set to 1) - This parameter can only be used when ``algorithm`` is ``"MILP"``. + This parameter can only be used when ``algorithm`` is ``'MILP'``. - - ``algorithm`` -- string (default: ``"MILP"``); the algorithm to use - among ``"MILP"``, ``"backtrack"`` and ``"heuristic"``: + - ``algorithm`` -- string (default: ``'MILP'``); the algorithm to use + among ``'MILP'``, ``'backtrack'`` and ``'heuristic'``: - * ``"MILP"`` returns an exact answer. + * ``'MILP'`` returns an exact answer. - * ``"backtrack"`` is renamed ``"heuristic"`` (:issue:`36574`). + * ``'backtrack'`` is renamed ``'heuristic'`` (:issue:`36574`). - * ``"heuristic"`` is a randomized heuristic for finding a long path in + * ``'heuristic'`` is a randomized heuristic for finding a long path in an unweighted (di)graph. This heuristic does not take into account parameters ``s``, ``t`` and ``use_edge_labels``. An error is raised if these parameters are set. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -8421,7 +8409,7 @@ def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm="MILP", :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -8456,7 +8444,7 @@ def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm="MILP", The heuristic totally agrees:: sage: g = graphs.PetersenGraph() - sage: p = g.longest_path(algorithm="heuristic").edges(sort=True, labels=False) + sage: p = g.longest_path(algorithm='heuristic').edges(sort=True, labels=False) sage: len(p) 9 @@ -8481,7 +8469,7 @@ def longest_path(self, s=None, t=None, use_edge_labels=False, algorithm="MILP", The argument ``algorithm`` must be either ``'backtrack'``, ``'heuristic'`` or ``'MILP'``:: - sage: graphs.PetersenGraph().longest_path(algorithm="abc") + sage: graphs.PetersenGraph().longest_path(algorithm='abc') Traceback (most recent call last): ... ValueError: algorithm must be either 'backtrack', 'heuristic' or 'MILP' @@ -8823,8 +8811,8 @@ def hamiltonian_path(self, s=None, t=None, use_edge_labels=False, hamiltonian path. This parameter is considered only if ``use_edge_labels == True``. - - ``algorithm`` -- string (default: ``"MILP"``); the algorithm the use - among ``"MILP"`` and ``"backtrack"``; two remarks on this respect: + - ``algorithm`` -- string (default: ``'MILP'``); the algorithm the use + among ``'MILP'`` and ``'backtrack'``; two remarks on this respect: * While the MILP formulation returns an exact answer, the backtrack algorithm is a randomized heuristic. @@ -8832,7 +8820,7 @@ def hamiltonian_path(self, s=None, t=None, use_edge_labels=False, * The backtrack algorithm does not support edge weighting, so setting ``use_edge_labels=True`` will force the use of the MILP algorithm. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -8840,7 +8828,7 @@ def hamiltonian_path(self, s=None, t=None, use_edge_labels=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -8994,7 +8982,7 @@ def hamiltonian_path(self, s=None, t=None, use_edge_labels=False, new_t = ones.pop() if not use_edge_labels and algorithm == "backtrack": - path = g.longest_path(s=new_s, t=new_t, algorithm="backtrack") + path = g.longest_path(s=new_s, t=new_t, algorithm='backtrack') return path if path.order() == g.order() else None # @@ -9051,7 +9039,7 @@ def traveling_salesman_problem(self, use_edge_labels=False, maximize=False, verbose=0, verbose_constraints=False, *, integrality_tolerance=1e-3): r""" - Solve the traveling salesman problem (TSP) + Solve the traveling salesman problem (TSP). Given a graph (resp. a digraph) `G` with weighted edges, the traveling salesman problem consists in finding a Hamiltonian cycle (resp. circuit) @@ -9073,7 +9061,7 @@ def traveling_salesman_problem(self, use_edge_labels=False, maximize=False, (or Hamiltonian cycle). This parameter is considered only if ``use_edge_labels == True``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -9088,7 +9076,7 @@ def traveling_salesman_problem(self, use_edge_labels=False, maximize=False, When ``constraint_generation = None``, constraint generation is used whenever the graph has a density larger than 70%. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``verbose_constraints`` -- boolean (default: ``False``); whether to @@ -9579,7 +9567,7 @@ def hamiltonian_cycle(self, algorithm='tsp', solver=None, constraint_generation= - ``algorithm`` -- string (default: ``'tsp'``); one of 'tsp' or 'backtrack' - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -9594,7 +9582,7 @@ def hamiltonian_cycle(self, algorithm='tsp', solver=None, constraint_generation= When ``constraint_generation = None``, constraint generation is used whenever the graph has a density larger than 70%. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``verbose_constraints`` -- boolean (default: ``False``); whether to @@ -9607,7 +9595,7 @@ def hamiltonian_cycle(self, algorithm='tsp', solver=None, constraint_generation= OUTPUT: If using the ``'tsp'`` algorithm, returns a Hamiltonian cycle/circuit if - it exists; otherwise, raises a ``EmptySetError`` exception. If using the + it exists; otherwise, raises a :exc:`EmptySetError` exception. If using the ``'backtrack'`` algorithm, returns a pair ``(B, P)``. If ``B`` is ``True`` then ``P`` is a Hamiltonian cycle and if ``B`` is ``False``, ``P`` is a longest path found by the algorithm. Observe that if ``B`` is @@ -9666,7 +9654,6 @@ def hamiltonian_cycle(self, algorithm='tsp', solver=None, constraint_generation= sage: G = graphs.CubeGraph(3) sage: G.hamiltonian_cycle(algorithm='backtrack') (True, [...]) - """ if self.order() < 2: raise ValueError("the traveling salesman problem is not defined for empty or one-element graph") @@ -9705,7 +9692,7 @@ def feedback_vertex_set(self, value_only=False, solver=None, verbose=0, the minimum cardinal of a minimum vertex set, or the ``Set`` of vertices of a minimal feedback vertex set - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -9713,7 +9700,7 @@ def feedback_vertex_set(self, value_only=False, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``constraint_generation`` -- boolean (default: ``True``); whether to @@ -9967,12 +9954,12 @@ def flow(self, x, y, value_only=True, integer=False, use_edge_labels=True, - ``algorithm`` -- string (default: ``None``); the algorithm to use among: - * ``"FF"``, a Python implementation of the Ford-Fulkerson algorithm + * ``'FF'``, a Python implementation of the Ford-Fulkerson algorithm (only available when ``vertex_bound = False``) - * ``"LP"``, the flow problem is solved using Linear Programming + * ``'LP'``, the flow problem is solved using Linear Programming - * ``"igraph"``, the ``igraph`` implementation of the Goldberg-Tarjan + * ``'igraph'``, the ``igraph`` implementation of the Goldberg-Tarjan algorithm is used (only available when ``igraph`` is installed and ``vertex_bound = False``) @@ -9980,7 +9967,7 @@ def flow(self, x, y, value_only=True, integer=False, use_edge_labels=True, True``, otherwise, we use ``igraph`` if it is available, ``FF`` if it is not available. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -9988,12 +9975,12 @@ def flow(self, x, y, value_only=True, integer=False, use_edge_labels=True, :class:`MixedIntegerLinearProgram `. - Only useful when algorithm ``"LP"`` is used to solve the flow problem. + Only useful when algorithm ``'LP'`` is used to solve the flow problem. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - Only useful when algorithm ``"LP"`` is used to solve the flow problem. + Only useful when algorithm ``'LP'`` is used to solve the flow problem. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers over an inexact base ring; see @@ -10056,18 +10043,18 @@ def flow(self, x, y, value_only=True, integer=False, use_edge_labels=True, = True``:: sage: g = graphs.PetersenGraph() - sage: g.flow(0, 1, vertex_bound=True, algorithm="FF") + sage: g.flow(0, 1, vertex_bound=True, algorithm='FF') Traceback (most recent call last): ... ValueError: this method does not support both vertex_bound=True and algorithm='FF' - sage: g.flow(0, 1, vertex_bound=True, algorithm="igraph") + sage: g.flow(0, 1, vertex_bound=True, algorithm='igraph') Traceback (most recent call last): ... ValueError: this method does not support both vertex_bound=True and algorithm='igraph' Or if the method is different from the expected values:: - sage: g.flow(0, 1, algorithm="Divination") + sage: g.flow(0, 1, algorithm='Divination') Traceback (most recent call last): ... ValueError: the algorithm argument has to be equal to either "FF", "LP", "igraph", or None @@ -10078,11 +10065,11 @@ def flow(self, x, y, value_only=True, integer=False, use_edge_labels=True, sage: g = graphs.RandomGNP(20, .3) sage: for u, v in g.edge_iterator(labels=False): ....: g.set_edge_label(u, v, round(random(), 5)) - sage: flow_ff = g.flow(0, 1, algorithm="FF") - sage: flow_lp = g.flow(0, 1, algorithm="LP") # needs sage.numerical.mip + sage: flow_ff = g.flow(0, 1, algorithm='FF') + sage: flow_lp = g.flow(0, 1, algorithm='LP') # needs sage.numerical.mip sage: abs(flow_ff - flow_lp) < 0.01 # needs sage.numerical.mip True - sage: flow_igraph = g.flow(0, 1, algorithm="igraph") # optional - python_igraph + sage: flow_igraph = g.flow(0, 1, algorithm='igraph') # optional - python_igraph sage: abs(flow_ff - flow_igraph) < 0.00001 # optional - python_igraph True """ @@ -10269,10 +10256,10 @@ def nowhere_zero_flow(self, k=None, solver=None, verbose=0, *, integrality_toler INPUT: - - ``k`` -- integer (default: ``6``); when set to a positive integer + - ``k`` -- integer (default: `6`); when set to a positive integer `\geq 2`, search for a `k`-nowhere zero flow - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -10280,7 +10267,7 @@ def nowhere_zero_flow(self, k=None, solver=None, verbose=0, *, integrality_toler :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -10645,11 +10632,11 @@ def multicommodity_flow(self, terminals, integer=True, use_edge_labels=False, INPUT: - - ``terminals`` -- a list of pairs `(s_i, t_i)` or triples `(s_i, t_i, + - ``terminals`` -- list of pairs `(s_i, t_i)` or triples `(s_i, t_i, w_i)` representing a flow from `s_i` to `t_i` of intensity `w_i`. When the pairs are of size `2`, an intensity of `1` is assumed. - - ``integer`` boolean (default: ``True``); whether to require an integer + - ``integer`` -- boolean (default: ``True``); whether to require an integer multicommodity flow - ``use_edge_labels`` -- boolean (default: ``False``); whether to @@ -10663,7 +10650,7 @@ def multicommodity_flow(self, terminals, integer=True, use_edge_labels=False, units of flow even though ``vertex_bound`` is set to ``True``, as this parameter is meant to represent topological properties. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -10671,7 +10658,7 @@ def multicommodity_flow(self, terminals, integer=True, use_edge_labels=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -10823,14 +10810,14 @@ def capacity_sum(i, u, v): def _build_flow_graph(self, flow, integer): r""" - Build a "clean" flow graph + Build a "clean" flow graph. This method first builds the flow graph, and then looks for circuits and removes them. INPUT: - - ``flow`` -- a dictionary associating positive numerical values to + - ``flow`` -- dictionary associating positive numerical values to edges - ``integer`` -- boolean; whether the values from ``flow`` are the @@ -10916,7 +10903,7 @@ def disjoint_routed_paths(self, pairs, solver=None, verbose=0, - ``pairs`` -- list of pairs of vertices - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -10924,7 +10911,7 @@ def disjoint_routed_paths(self, pairs, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -10957,7 +10944,7 @@ def disjoint_routed_paths(self, pairs, solver=None, verbose=0, except EmptySetError: raise EmptySetError("the disjoint routed paths do not exist") - def edge_disjoint_paths(self, s, t, algorithm="FF", solver=None, verbose=False, + def edge_disjoint_paths(self, s, t, algorithm='FF', solver=None, verbose=False, *, integrality_tolerance=1e-3): r""" Return a list of edge-disjoint paths between two vertices. @@ -10971,14 +10958,14 @@ def edge_disjoint_paths(self, s, t, algorithm="FF", solver=None, verbose=False, INPUT: - - ``algorithm`` -- string (default: ``"FF"``); the algorithm to use + - ``algorithm`` -- string (default: ``'FF'``); the algorithm to use among: - * ``"FF"``, a Python implementation of the Ford-Fulkerson algorithm + * ``'FF'``, a Python implementation of the Ford-Fulkerson algorithm - * ``"LP"``, the flow problem is solved using Linear Programming + * ``'LP'``, the flow problem is solved using Linear Programming - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -10986,18 +10973,18 @@ def edge_disjoint_paths(self, s, t, algorithm="FF", solver=None, verbose=False, :class:`MixedIntegerLinearProgram `. - Only used when `àlgorithm`` is ``"LP"``. + Only used when ``algorithm`` is ``'LP'``. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - Only used when `àlgorithm`` is ``"LP"``. + Only used when ``algorithm`` is ``'LP'``. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers over an inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. - Only used when `àlgorithm`` is ``"LP"``. + Only used when ``algorithm`` is ``'LP'``. .. NOTE:: @@ -11042,9 +11029,9 @@ def vertex_disjoint_paths(self, s, t, solver=None, verbose=0, INPUT: - - ``s``, ``t`` -- two vertices of the graph. + - ``s``, ``t`` -- two vertices of the graph - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -11052,7 +11039,7 @@ def vertex_disjoint_paths(self, s, t, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -11111,17 +11098,17 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, INPUT: - - ``alpha`` -- float (default: ``0.85``); damping parameter for + - ``alpha`` -- float (default: `0.85`); damping parameter for PageRank. ``alpha`` is the click-through probability useful for preventing sinks. The probability at any step, that an imaginary surfer who is randomly clicking on links will continue is a damping factor d. - - ``personalization`` -- dict (default: ``None``); a dictionary keyed - by vertices associating to each vertex a value. The personalization - can be specified for a subset of the vertices, if not specified a - nodes personalization value will be taken as zero. The sum of the - values must be nonzero. + - ``personalization`` -- dictionary (default: ``None``); a dictionary + keyed by vertices associating to each vertex a value. The + personalization can be specified for a subset of the vertices, if not + specified a nodes personalization value will be taken as zero. The + sum of the values must be nonzero. By default (``None``), a uniform distribution is used. - ``by_weight`` -- boolean (default: ``False``); if ``True``, the edges @@ -11134,9 +11121,9 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, is not ``None``, else ``1`` as a weight. - ``check_weight`` -- boolean (default: ``True``); whether to check that - the ``weight_function`` outputs a number for each edge. + the ``weight_function`` outputs a number for each edge - - ``dangling`` -- dict (default: ``None``); a dictionary keyed by a + - ``dangling`` -- dictionary (default: ``None``); a dictionary keyed by a vertex the outedge of "dangling" vertices, (i.e., vertices without any outedges) points to and the dict value is the weight of that outedge. By default, dangling vertices are given outedges according @@ -11145,16 +11132,16 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, dict. - ``algorithm`` -- string (default: ``None``); the algorithm to use in - computing PageRank of ``G``. The following algorithms are - supported: + computing PageRank of ``G``. The following algorithms are + supported: - - ``NetworkX`` -- uses NetworkX's default implementation (Scipy as of 2.6) + - ``'NetworkX'`` -- uses NetworkX's default implementation (Scipy as of 2.6) - - ``"Scipy"`` -- uses Scipy's PageRank algorithm implementation + - ``'Scipy'`` -- uses Scipy's PageRank algorithm implementation - - ``"igraph"`` -- uses igraph's PageRank algorithm implementation + - ``'igraph'`` -- uses igraph's PageRank algorithm implementation - - ``"None"`` -- uses best implementation available + - ``None`` -- uses best implementation available OUTPUT: a dictionary containing the PageRank value of each node @@ -11169,7 +11156,7 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, sage: G = graphs.CycleGraph(4) sage: G.pagerank(algorithm="Networkx") # needs networkx {0: 0.25, 1: 0.25, 2: 0.25, 3: 0.25} - sage: G.pagerank(alpha=0.50, algorithm="igraph") # abs tol 1e-9, optional - python_igraph + sage: G.pagerank(alpha=0.50, algorithm='igraph') # abs tol 1e-9, optional - python_igraph {0: 0.25, 1: 0.25, 2: 0.25, 3: 0.25} sage: G = Graph([(1, 2, 40), (2, 3, 50), (3, 4, 60), ....: (1, 4, 70), (4, 5, 80), (5, 6, 20)]) @@ -11180,28 +11167,28 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, 4: 0.2374999999999999, 5: 0.17775588228760858, 6: 0.100546895675278} - sage: G.pagerank(algorithm="NetworkX", by_weight=True) # abs tol 1e-9 # needs networkx + sage: G.pagerank(algorithm='NetworkX', by_weight=True) # abs tol 1e-9 # needs networkx {1: 0.16459583718588994, 2: 0.13977928595154515, 3: 0.16539840184339605, 4: 0.3063198690713853, 5: 0.1700057609707141, 6: 0.05390084497706962} - sage: G.pagerank(algorithm="Scipy") # abs tol 1e-9 # needs networkx scipy + sage: G.pagerank(algorithm='Scipy') # abs tol 1e-9 # needs networkx scipy {1: 0.16112205885619563, 2: 0.1619531043247219, 3: 0.16112205885619563, 4: 0.2374999999999999, 5: 0.17775588228760858, 6: 0.100546895675278} - sage: G.pagerank(algorithm="Scipy", by_weight=True) # abs tol 1e-9 # needs networkx scipy + sage: G.pagerank(algorithm='Scipy', by_weight=True) # abs tol 1e-9 # needs networkx scipy {1: 0.16459583718588994, 2: 0.13977928595154515, 3: 0.16539840184339605, 4: 0.3063198690713853, 5: 0.1700057609707141, 6: 0.05390084497706962} - sage: G.pagerank(algorithm="igraph") # abs tol 1e-9, optional - python_igraph + sage: G.pagerank(algorithm='igraph') # abs tol 1e-9, optional - python_igraph {1: 0.16112198303979128, 2: 0.16195368558382262, 3: 0.16112198303979125, @@ -11226,7 +11213,7 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, TESTS:: sage: G = Graph([(1, 2), (2, 3), (3, 4), (1, 3)]) - sage: G.pagerank(algorithm="NetworkX", # needs networkx + sage: G.pagerank(algorithm='NetworkX', # needs networkx ....: personalization={1:0, 2:3, 3:-2, 4:-1}) Traceback (most recent call last): ... @@ -11235,7 +11222,6 @@ def pagerank(self, alpha=0.85, personalization=None, by_weight=False, .. SEEALSO:: * :wikipedia:`PageRank` - """ if not self.order(): return {} @@ -11292,9 +11278,7 @@ def add_vertex(self, name=None): with numeric labels, then ``G.add_vertex()`` could potentially be slow, if ``name=None``. - OUTPUT: - - If ``name=None``, the new vertex name is returned. ``None`` otherwise. + OUTPUT: if ``name=None``, the new vertex name is returned. ``None`` otherwise EXAMPLES:: @@ -11307,7 +11291,6 @@ def add_vertex(self, name=None): sage: D = DiGraph(); D.add_vertex(); D 0 Digraph on 1 vertex - """ return self._backend.add_vertex(name) @@ -11345,7 +11328,6 @@ def add_vertices(self, vertices): sage: G.add_vertices([1, 2, 3]) sage: G.add_vertices([4, None, None, 5]) [0, 6] - """ return self._backend.add_vertices(vertices) @@ -11433,7 +11415,6 @@ def delete_vertices(self, vertices): Deleting a non-existent vertex will raise an exception, in which case none of the vertices in ``vertices`` is deleted. - EXAMPLES:: sage: D = DiGraph({0: [1, 2, 3, 4, 5], 1: [2], 2: [3], 3: [4], 4: [5], 5: [1]}) @@ -11629,7 +11610,7 @@ def random_edge_iterator(self, *args, **kwds): INPUT: - ``*args`` and ``**kwds`` -- arguments to be passed down to the - :meth:`edge_iterator` method. + :meth:`edge_iterator` method EXAMPLES: @@ -11765,7 +11746,6 @@ def set_vertex(self, vertex, object): - ``object`` -- object to associate to vertex - EXAMPLES:: sage: T = graphs.TetrahedralGraph() @@ -11854,7 +11834,7 @@ def vertex_iterator(self, vertices=None, degree=None, vertex_property=None): - ``vertices`` -- iterated vertices are these intersected with the vertices of the (di)graph - - ``degree`` -- a nonnegative integer (default: ``None``); + - ``degree`` -- nonnegative integer (default: ``None``); a vertex ``v`` is kept if ``degree(v) == degree`` - ``vertex_property`` -- function (default: ``None``); a function @@ -11931,7 +11911,7 @@ def neighbor_iterator(self, vertex, closed=False): - ``vertex`` -- a vertex of ``self`` - - ``closed`` -- a boolean (default: ``False``); whether to + - ``closed`` -- boolean (default: ``False``); whether to return the closed neighborhood of ``vertex``, i.e., including ``vertex``, or the open neighborhood in which ``vertex`` is included only if there is a loop on that vertex. @@ -12005,7 +11985,7 @@ def vertices(self, sort=False, key=None, degree=None, vertex_property=None): vertex as its one argument and returns a value that can be used for comparisons in the sorting algorithm (we must have ``sort=True``) - - ``degree`` -- a nonnegative integer (default: ``None``); + - ``degree`` -- nonnegative integer (default: ``None``); a vertex ``v`` is kept if ``degree(v) == degree`` - ``vertex_property`` -- function (default: ``None``); a function @@ -12026,7 +12006,6 @@ def vertices(self, sort=False, key=None, degree=None, vertex_property=None): sorting of the edges, use the ``key`` argument, as illustrated in the examples below. - EXAMPLES:: sage: P = graphs.PetersenGraph() @@ -12107,7 +12086,7 @@ def neighbors(self, vertex, closed=False): - ``vertex`` -- a vertex of ``self`` - - ``closed`` -- a boolean (default: ``False``); whether to + - ``closed`` -- boolean (default: ``False``); whether to return the closed neighborhood of ``vertex``, i.e., including ``vertex``, or the open neighborhood in which ``vertex`` is included only if there is a loop on that vertex. @@ -12135,7 +12114,7 @@ def merge_vertices(self, vertices): `\exists v'\in S: (u,v')\in G`. The new vertex is named after the first vertex in the list given in - argument. If this first name is `None`, a new vertex is created. + argument. If this first name is ``None``, a new vertex is created. In the case of multigraphs, the multiplicity is preserved. @@ -12203,7 +12182,6 @@ def merge_vertices(self, vertices): sage: G = Graph(edgelist, loops=True, multiedges=False) sage: G.merge_vertices([0, 2, 1]); G.edges(sort=True) [(0, 0, 'c')] - """ if len(vertices) <= 1: return None @@ -12263,7 +12241,7 @@ def add_edge(self, u, v=None, label=None): You must either use the ``label`` keyword:: sage: G = Graph() - sage: G.add_edge((1, 2), label="label") + sage: G.add_edge((1, 2), label='label') sage: G.edges(sort=False) [(1, 2, 'label')] @@ -12310,7 +12288,7 @@ def add_edges(self, edges, loops=True): INPUT: - ``edges`` -- an iterable of edges, given either as ``(u, v)`` - or ``(u, v, label)``. + or ``(u, v, label)`` - ``loops`` -- boolean (default: ``True``); if ``False``, remove all loops ``(v, v)`` from the input iterator. If ``None``, remove loops @@ -12374,7 +12352,7 @@ def subdivide_edge(self, *args): INPUT: The following forms are all accepted to subdivide `8` times the edge - between vertices `1` and `2` labeled with ``"my_label"``. + between vertices `1` and `2` labeled with ``'my_label'``. - ``G.subdivide_edge( 1, 2, 8 )`` - ``G.subdivide_edge( (1, 2), 8 )`` @@ -12494,7 +12472,7 @@ def subdivide_edges(self, edges, k): INPUT: - - ``edges`` -- a list of edges + - ``edges`` -- list of edges - ``k`` -- integer; common length of the subdivisions @@ -12600,7 +12578,6 @@ def delete_edge(self, u, v=None, label=None): True sage: C.has_edge( (4, 5, 'label') ) # correct! False - """ if label is None: if v is None: @@ -12736,7 +12713,7 @@ def contract_edges(self, edges): INPUT: - - ``edges`` -- a list containing 2-tuples or 3-tuples that represent + - ``edges`` -- list containing 2-tuples or 3-tuples that represent edges EXAMPLES:: @@ -12898,7 +12875,7 @@ def set_edge_label(self, u, v, l): - ``u``, ``v`` -- the vertices (and direction if digraph) of the edge - - ``l`` -- the new label + - ``l`` -- the new label EXAMPLES:: @@ -13048,15 +13025,14 @@ def edges(self, vertices=None, labels=True, sort=False, key=None, the sorting algorithm - ``ignore_direction`` -- boolean (default: ``False``); only applies to - directed graphs. If ``True``, searches across edges in either - direction. + directed graphs. If ``True``, searches across edges in either + direction. - ``sort_vertices`` -- boolean (default: ``True``); only applies to undirected graphs. If ``True``, sort the ends of the edges. Not sorting the ends is faster. - - OUTPUT: A :class:`~EdgesView`. + OUTPUT: a :class:`~EdgesView` .. WARNING:: @@ -13312,11 +13288,11 @@ def edge_iterator(self, vertices=None, labels=True, ignore_direction=False, sort vertices or ``None`` - ``labels`` -- boolean (default: ``True``); if ``False``, each edge is - a tuple `(u,v)` of vertices + a tuple `(u,v)` of vertices - ``ignore_direction`` -- boolean (default: ``False``); only applies to - directed graphs. If ``True``, searches across edges in either - direction. + directed graphs. If ``True``, searches across edges in either + direction. - ``sort_vertices`` -- boolean (default: ``True``); only applies to undirected graphs. If ``True``, sort the ends of the edges. @@ -13403,7 +13379,7 @@ def edges_incident(self, vertices=None, labels=True, sort=False): vertices or ``None`` - ``labels`` -- boolean (default: ``True``); if ``False``, each edge is - a tuple `(u,v)` of vertices + a tuple `(u,v)` of vertices - ``sort`` -- boolean (default: ``False``); if ``True`` the returned list is sorted @@ -14083,7 +14059,7 @@ def _subgraph_by_adding(self, vertices=None, edges=None, edge_property=None, imm INPUT: - - ``vertices`` -- (default: ``None``); an iterable container of + - ``vertices`` -- (default: ``None``) an iterable container of vertices, e.g. a list, set, graph, file or numeric array. If not passed (i.e., ``None``), defaults to the entire graph. @@ -14249,7 +14225,7 @@ def _subgraph_by_deleting(self, vertices=None, edges=None, inplace=False, INPUT: - - ``vertices`` -- (default: ``None``); an iterable container of + - ``vertices`` -- (default: ``None``) an iterable container of vertices, e.g. a list, set, graph, file or numeric array. If not passed (i.e., ``None``), defaults to the entire graph. @@ -14534,7 +14510,6 @@ def subgraph_search(self, G, induced=False): sage: C = G.subgraph_search(graphs.CycleGraph(4)) # needs sage.modules sage: C.edges(sort=True) # needs sage.modules [(0, 1, 0), (0, 3, 0), (1, 2, 1), (2, 3, 2)] - """ # return the first graph found by method subgraph_search_iterator for g in self.subgraph_search_iterator(G, induced=induced, return_graphs=True): @@ -14856,7 +14831,7 @@ def random_subgraph(self, p, inplace=False): vertices = [v for v in self if random() < p] return self.subgraph(vertices=vertices, inplace=inplace) - def is_chordal(self, certificate=False, algorithm="B"): + def is_chordal(self, certificate=False, algorithm='B'): r""" Check whether the given graph is chordal. @@ -14884,7 +14859,7 @@ def is_chordal(self, certificate=False, algorithm="B"): INPUT: - ``certificate`` -- boolean (default: ``False``); whether to return a - certificate. + certificate * If ``certificate = False`` (default), returns ``True`` or ``False`` accordingly. @@ -14898,8 +14873,8 @@ def is_chordal(self, certificate=False, algorithm="B"): ``Graph`` object) is an induced subgraph of ``self`` isomorphic to a hole. - - ``algorithm`` -- string (default: ``"B"``); the algorithm to choose - among ``"A"`` or ``"B"``. While they will agree on whether the given + - ``algorithm`` -- string (default: ``'B'``); the algorithm to choose + among ``'A'`` or ``'B'``. While they will agree on whether the given graph is chordal, they cannot be expected to return the same certificates. @@ -15255,9 +15230,9 @@ def is_interval(self, certificate=False): INPUT: - - ``certificate`` -- boolean (default: ``False``); + - ``certificate`` -- boolean (default: ``False``) - - When ``certificate=False``, returns ``True`` is the graph is an + - When ``certificate=False``, returns ``True`` if the graph is an interval graph and ``False`` otherwise - When ``certificate=True``, returns either ``(False, None)`` or @@ -15450,7 +15425,7 @@ def is_gallai_tree(self): def is_clique(self, vertices=None, directed_clique=False, induced=True, loops=False): """ - Check whether a set of vertices is a clique + Check whether a set of vertices is a clique. A clique is a set of vertices such that there is exactly one edge between any two vertices. @@ -15458,7 +15433,7 @@ def is_clique(self, vertices=None, directed_clique=False, induced=True, loops=Fa INPUT: - ``vertices`` -- a single vertex or an iterable container of vertices - (default: ``None); when set, check whether the set of vertices is a + (default: ``None``); when set, check whether the set of vertices is a clique, otherwise check whether ``self`` is a clique - ``directed_clique`` -- boolean (default: ``False``); if set to @@ -15693,7 +15668,7 @@ def is_independent_set(self, vertices=None): INPUT: - ``vertices`` -- a single vertex or an iterable container of vertices - (default: ``None); when set, check whether the given set of vertices + (default: ``None``); when set, check whether the given set of vertices is an independent set, otherwise, check whether the set of vertices of ``self`` is an independent set @@ -15796,7 +15771,6 @@ def is_subgraph(self, other, induced=True, up_to_isomorphism=False): Traceback (most recent call last): ... ValueError: the input parameter must be a DiGraph - """ from sage.graphs.graph import Graph from sage.graphs.digraph import DiGraph @@ -15836,7 +15810,7 @@ def cluster_triangles(self, nbunch=None, implementation=None): INPUT: - - ``nbunch`` -- a list of vertices (default: ``None); the vertices to + - ``nbunch`` -- list of vertices (default: ``None``); the vertices to inspect. If ``nbunch=None``, returns data for all vertices in the graph. @@ -15858,19 +15832,19 @@ def cluster_triangles(self, nbunch=None, implementation=None): :: sage: G = graphs.RandomGNP(20, .3) - sage: d1 = G.cluster_triangles(implementation="networkx") # needs networkx - sage: d2 = G.cluster_triangles(implementation="dense_copy") - sage: d3 = G.cluster_triangles(implementation="sparse_copy") + sage: d1 = G.cluster_triangles(implementation='networkx') # needs networkx + sage: d2 = G.cluster_triangles(implementation='dense_copy') + sage: d3 = G.cluster_triangles(implementation='sparse_copy') sage: d1 == d2 and d1 == d3 # needs networkx True TESTS:: - sage: DiGraph().cluster_triangles(implementation="networkx") # needs networkx + sage: DiGraph().cluster_triangles(implementation='networkx') # needs networkx Traceback (most recent call last): ... ValueError: the 'networkx' implementation does not support directed graphs - sage: Graph().cluster_triangles(implementation="welcome") + sage: Graph().cluster_triangles(implementation='welcome') Traceback (most recent call last): ... ValueError: the implementation can only be 'networkx', 'sparse_copy', 'dense_copy' or None @@ -15948,7 +15922,6 @@ def clustering_average(self, implementation=None): ....: for impl in impls] sage: max(coeffs) - min(coeffs) # tol abs 1e-12 0 - """ if implementation is None: from sage.graphs.base.dense_graph import DenseGraphBackend @@ -16161,7 +16134,7 @@ def distance(self, u, v, by_weight=False, weight_function=None, check_weight=Tru is not ``None``, else ``1`` as a weight. - ``check_weight`` -- boolean (default: ``True``); whether to check that - the ``weight_function`` outputs a number for each edge. + the ``weight_function`` outputs a number for each edge EXAMPLES:: @@ -16193,8 +16166,8 @@ def distance_all_pairs(self, by_weight=False, algorithm=None, INPUT: - - ``by_weight`` boolean (default: `False``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + - ``by_weight`` -- boolean (default: ``False``); if ``True``, the edges in + the graph are weighted. If ``False``, all edges have weight 1. - ``algorithm`` -- string (default: ``None``); one of the following algorithms: @@ -16231,11 +16204,9 @@ def distance_all_pairs(self, by_weight=False, algorithm=None, is not ``None``, else ``1`` as a weight. - ``check_weight`` -- boolean (default: ``True``); whether to check that - the ``weight_function`` outputs a number for each edge. - - OUTPUT: + the ``weight_function`` outputs a number for each edge - A doubly indexed dictionary + OUTPUT: a doubly indexed dictionary .. NOTE:: @@ -16298,11 +16269,9 @@ def power(self, k): INPUT: - ``k`` -- integer; the maximum path length for considering edges in - the power graph. + the power graph - OUTPUT: - - - The kth power graph based on shortest distances between nodes. + OUTPUT: the `k`-th power graph based on shortest distances between nodes EXAMPLES: @@ -16328,7 +16297,7 @@ def power(self, k): sage: PG = G.power(-2) Traceback (most recent call last): ... - ValueError: distance must be a non-negative integer, not -2 + ValueError: distance must be a nonnegative integer, not -2 Testing when k = 0:: @@ -16350,7 +16319,7 @@ def power(self, k): sage: PG = G.power(Infinity) Traceback (most recent call last): ... - ValueError: distance must be a non-negative integer, not +Infinity + ValueError: distance must be a nonnegative integer, not +Infinity Testing on graph with multiple edges:: @@ -16480,7 +16449,7 @@ def girth(self, certificate=False): return self._girth_bfs(odd=False, certificate=certificate) - def odd_girth(self, algorithm="bfs", certificate=False): + def odd_girth(self, algorithm='bfs', certificate=False): r""" Return the odd girth of the graph. @@ -16490,9 +16459,9 @@ def odd_girth(self, algorithm="bfs", certificate=False): INPUT: - - ``algorithm`` -- string (default: ``"bfs"``); the algorithm to use: + - ``algorithm`` -- string (default: ``'bfs'``); the algorithm to use: - - ``"bfs"`` -- BFS-based algorithm + - ``'bfs'`` -- BFS-based algorithm - any algorithm accepted by :meth:`~sage.matrix.matrix_integer_dense.Matrix_integer_dense.charpoly` @@ -16707,7 +16676,7 @@ def centrality_betweenness(self, k=None, normalized=True, weight=None, INPUT: - ``normalized`` -- boolean (default: ``True``); if set to ``False``, - result is not normalized. + result is not normalized - ``k`` -- integer (default: ``None``); if set to an integer, use ``k`` node samples to estimate betweenness. Higher values give better @@ -16725,7 +16694,7 @@ def centrality_betweenness(self, k=None, normalized=True, weight=None, rationals or on ``double`` C variables. Not available when ``algorithm="NetworkX"``. - - ``algorithm`` -- string (default: ``None``); can be either ``"Sage"`` + - ``algorithm`` -- string (default: ``None``); can be either ``'Sage'`` (see :mod:`~sage.graphs.centrality`), ``"NetworkX"`` or ``"None"``. In the latter case, Sage's algorithm will be used whenever possible. @@ -16762,8 +16731,8 @@ def centrality_betweenness(self, k=None, normalized=True, weight=None, sage: tests = ([graphs.RandomGNP(30,.1) for i in range(10)]+ # needs networkx ....: [digraphs.RandomDirectedGNP(30,.1) for i in range(10)]) sage: for g in tests: # needs networkx - ....: r1 = g.centrality_betweenness(algorithm="Sage",exact=0) - ....: r2 = g.centrality_betweenness(algorithm="Sage",exact=1) + ....: r1 = g.centrality_betweenness(algorithm='Sage',exact=0) + ....: r2 = g.centrality_betweenness(algorithm='Sage',exact=1) ....: r3 = g.centrality_betweenness(algorithm="NetworkX") ....: for x in g: ....: if max([r1[x],r2[x],r3[x]])-min([r1[x],r2[x],r3[x]]) > 0.01: @@ -16823,7 +16792,7 @@ def centrality_closeness(self, vert=None, by_weight=False, algorithm=None, INPUT: - ``vert`` -- the vertex or the list of vertices we want to analyze. If - ``None`` (default), all vertices are considered. + ``None`` (default), all vertices are considered - ``by_weight`` -- boolean (default: ``False``); if ``True``, the edges in the graph are weighted, and otherwise all edges have weight 1 @@ -16863,7 +16832,7 @@ def centrality_closeness(self, vert=None, by_weight=False, algorithm=None, weight, if ``l`` is not ``None``, else ``1`` as a weight. - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check - that the ``weight_function`` outputs a number for each edge. + that the ``weight_function`` outputs a number for each edge OUTPUT: @@ -16994,7 +16963,6 @@ def centrality_closeness(self, vert=None, by_weight=False, algorithm=None, sage: all( sum(abs(ci[v] - cj[v]) for v in g if g.degree(v)) < 1e-12 ....: for ci, cj in itertools.combinations(c, 2) ) True - """ by_weight, weight_function = self._get_weight_function(by_weight=by_weight, weight_function=weight_function, @@ -17106,8 +17074,8 @@ def triangles_count(self, algorithm=None): - ``'iter'`` iterates over the pairs of neighbors of each vertex. No copy of the graph is performed - - ``None`` -- for undirected graphs, uses ``"sparse_copy"`` or - ``"dense_copy"`` depending on whether the graph is stored as dense + - ``None`` -- for undirected graphs, uses ``'sparse_copy'`` or + ``'dense_copy'`` depending on whether the graph is stored as dense or sparse. For directed graphs, uses ``'iter'``. EXAMPLES: @@ -17157,7 +17125,7 @@ def triangles_count(self, algorithm=None): Traceback (most recent call last): ... ValueError: unknown algorithm "tip top" - sage: digraphs.Path(5).triangles_count(algorithm="sparse_copy") + sage: digraphs.Path(5).triangles_count(algorithm='sparse_copy') Traceback (most recent call last): ... ValueError: the value of algorithm(=sparse_copy) must be 'iter' or None for directed graphs @@ -17741,8 +17709,8 @@ def shortest_paths(self, u, by_weight=False, algorithm=None, - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check that the weight_function outputs a number for each edge - - ``cutoff`` -- integer (default: ``None``); integer depth to stop - search (used only if ``algorithm=='BFS'``) + - ``cutoff`` -- integer (default: ``None``); depth to stop search (used + only if ``algorithm=='BFS'``) EXAMPLES: @@ -18055,10 +18023,10 @@ def shortest_path_lengths(self, u, by_weight=False, algorithm=None, Checking that distances are equal regardless of the algorithm used:: sage: g = graphs.Grid2dGraph(5,5) - sage: d1 = g.shortest_path_lengths((0,0), algorithm="BFS") + sage: d1 = g.shortest_path_lengths((0,0), algorithm='BFS') sage: d2 = g.shortest_path_lengths((0,0), algorithm="Dijkstra_NetworkX") # needs networkx - sage: d3 = g.shortest_path_lengths((0,0), algorithm="Dijkstra_Boost") - sage: d4 = g.shortest_path_lengths((0,0), algorithm="Bellman-Ford_Boost") + sage: d3 = g.shortest_path_lengths((0,0), algorithm='Dijkstra_Boost') + sage: d4 = g.shortest_path_lengths((0,0), algorithm='Bellman-Ford_Boost') sage: d1 == d2 == d3 == d4 # needs networkx True """ @@ -18244,28 +18212,28 @@ def shortest_path_all_pairs(self, by_weight=False, algorithm=None, Checking that distances are equal regardless of the algorithm used:: sage: g = graphs.Grid2dGraph(5,5) - sage: d1, _ = g.shortest_path_all_pairs(algorithm="BFS") - sage: d2, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall-Cython") - sage: d3, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall-Python") + sage: d1, _ = g.shortest_path_all_pairs(algorithm='BFS') + sage: d2, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall-Cython') + sage: d3, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall-Python') sage: d4, _ = g.shortest_path_all_pairs(algorithm="Dijkstra_NetworkX") # needs networkx - sage: d5, _ = g.shortest_path_all_pairs(algorithm="Dijkstra_Boost") - sage: d6, _ = g.shortest_path_all_pairs(algorithm="Johnson_Boost") - sage: d7, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall_Boost") - sage: d8, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall_SciPy") # needs scipy + sage: d5, _ = g.shortest_path_all_pairs(algorithm='Dijkstra_Boost') + sage: d6, _ = g.shortest_path_all_pairs(algorithm='Johnson_Boost') + sage: d7, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall_Boost') + sage: d8, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall_SciPy') # needs scipy sage: d1 == d2 == d3 == d4 == d5 == d6 == d7 == d8 # needs networkx scipy True Checking that distances are equal regardless of the algorithm used:: sage: g = digraphs.RandomDirectedGNM(6,12) - sage: d1, _ = g.shortest_path_all_pairs(algorithm="BFS") - sage: d2, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall-Cython") - sage: d3, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall-Python") + sage: d1, _ = g.shortest_path_all_pairs(algorithm='BFS') + sage: d2, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall-Cython') + sage: d3, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall-Python') sage: d4, _ = g.shortest_path_all_pairs(algorithm="Dijkstra_NetworkX") # needs networkx - sage: d5, _ = g.shortest_path_all_pairs(algorithm="Dijkstra_Boost") - sage: d6, _ = g.shortest_path_all_pairs(algorithm="Johnson_Boost") - sage: d7, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall_Boost") - sage: d8, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall_SciPy") # needs scipy + sage: d5, _ = g.shortest_path_all_pairs(algorithm='Dijkstra_Boost') + sage: d6, _ = g.shortest_path_all_pairs(algorithm='Johnson_Boost') + sage: d7, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall_Boost') + sage: d8, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall_SciPy') # needs scipy sage: d1 == d2 == d3 == d4 == d5 == d6 == d7 == d8 # needs networkx scipy True @@ -18276,18 +18244,18 @@ def shortest_path_all_pairs(self, by_weight=False, algorithm=None, sage: import random sage: for v, w in g.edges(labels=False, sort=False): ....: g.add_edge(v, w, random.uniform(1, 10)) - sage: d1, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall-Python") + sage: d1, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall-Python') sage: d2, _ = g.shortest_path_all_pairs(algorithm="Dijkstra_NetworkX") # needs networkx - sage: d3, _ = g.shortest_path_all_pairs(algorithm="Dijkstra_Boost") - sage: d4, _ = g.shortest_path_all_pairs(algorithm="Johnson_Boost") - sage: d5, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall_Boost") - sage: d6, _ = g.shortest_path_all_pairs(algorithm="Floyd-Warshall_SciPy") # needs scipy + sage: d3, _ = g.shortest_path_all_pairs(algorithm='Dijkstra_Boost') + sage: d4, _ = g.shortest_path_all_pairs(algorithm='Johnson_Boost') + sage: d5, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall_Boost') + sage: d6, _ = g.shortest_path_all_pairs(algorithm='Floyd-Warshall_SciPy') # needs scipy sage: d1 == d2 == d3 == d4 == d5 == d6 # needs networkx scipy True Checking a random path is valid:: - sage: dist, path = g.shortest_path_all_pairs(algorithm="BFS") + sage: dist, path = g.shortest_path_all_pairs(algorithm='BFS') sage: u,v = g.random_vertex(), g.random_vertex() sage: p = [v] sage: while p[0] is not None: @@ -18345,7 +18313,7 @@ def shortest_path_all_pairs(self, by_weight=False, algorithm=None, Wrong name for ``algorithm``:: - sage: g.shortest_path_all_pairs(algorithm="Bob") + sage: g.shortest_path_all_pairs(algorithm='Bob') Traceback (most recent call last): ... ValueError: unknown algorithm "Bob" @@ -18353,11 +18321,11 @@ def shortest_path_all_pairs(self, by_weight=False, algorithm=None, Algorithms that do not work with weights:: sage: g = Graph({0: {1:1}, 1: {2:1}, 2: {3: 1}, 3: {4: 2}, 4: {0: 2}}, sparse=True) - sage: g.shortest_path_all_pairs(algorithm="BFS", by_weight=True) + sage: g.shortest_path_all_pairs(algorithm='BFS', by_weight=True) Traceback (most recent call last): ... ValueError: algorithm 'BFS' does not work with weights - sage: g.shortest_path_all_pairs(algorithm="Floyd-Warshall-Cython", by_weight=True) + sage: g.shortest_path_all_pairs(algorithm='Floyd-Warshall-Cython', by_weight=True) Traceback (most recent call last): ... ValueError: algorithm 'Floyd-Warshall-Cython' does not work with weights @@ -18365,7 +18333,7 @@ def shortest_path_all_pairs(self, by_weight=False, algorithm=None, Dijkstra with negative weights:: sage: g = Graph({0: {1:1}, 1: {2:1}, 2: {3: 1}, 3: {4: -2}, 4: {0: -2}}) - sage: g.shortest_path_all_pairs(algorithm="Dijkstra_Boost", by_weight=True) + sage: g.shortest_path_all_pairs(algorithm='Dijkstra_Boost', by_weight=True) Traceback (most recent call last): ... RuntimeError: Dijkstra algorithm does not work with negative weights, use Bellman-Ford instead @@ -18531,7 +18499,7 @@ def wiener_index(self, by_weight=False, algorithm=None, - For ``by_weight==False`` only: - ``'BFS'`` -- the computation is done through a BFS centered on - each vertex successively. + each vertex successively - ``'Floyd-Warshall-Cython'`` -- the Cython implementation of the Floyd-Warshall algorithm. Usually slower than ``'BFS'``. @@ -18827,7 +18795,7 @@ def breadth_first_search(self, start, ignore_direction=False, - :meth:`depth_first_search ` -- depth-first search for fast compiled graphs. - - :meth:`depth_first_search` -- depth-first search for generic graphs. + - :meth:`depth_first_search` -- depth-first search for generic graphs EXAMPLES:: @@ -18924,14 +18892,14 @@ def breadth_first_search(self, start, ignore_direction=False, sage: list(G.breadth_first_search(1, report_distance=True, edges=True)) Traceback (most recent call last): ... - ValueError: parameters edges and report_distance cannot be True simultaneously + ValueError: parameters edges and report_distance cannot be ``True`` simultaneously """ from sage.rings.semirings.non_negative_integer_semiring import NN if (distance is not None and distance not in NN): - raise ValueError("distance must be a non-negative integer, not {0}".format(distance)) + raise ValueError("distance must be a nonnegative integer, not {0}".format(distance)) if (report_distance and edges): - raise ValueError("parameters edges and report_distance cannot be True simultaneously") + raise ValueError("parameters edges and report_distance cannot be ``True`` simultaneously") # Preferably use the Cython implementation if (neighbors is None and not isinstance(start, list) and distance is None @@ -19085,7 +19053,6 @@ def depth_first_search(self, start, ignore_direction=False, [1, 3, 6, 4, 5, 7, 2] sage: list(D.depth_first_search(1, ignore_direction=True, edges=True)) [(1, 3), (3, 6), (6, 7), (7, 5), (5, 4), (1, 2)] - """ # Preferably use the Cython implementation if (neighbors is None and not isinstance(start, list) @@ -19359,7 +19326,6 @@ def complement(self): Graph on 10 vertices sage: g.complement() Graph on 10 vertices - """ self._scream_if_not_simple() @@ -19396,7 +19362,7 @@ def to_simple(self, to_undirected=True, keep_label='any', immutable=None): .. WARNING:: ``'min'`` and ``'max'`` only works if the labels can be compared. A - :class:`TypeError` might be raised when working with non-comparable + :exc:`TypeError` might be raised when working with non-comparable objects. - ``immutable`` -- boolean (default: ``Non``); whether to create a @@ -19437,7 +19403,7 @@ def to_simple(self, to_undirected=True, keep_label='any', immutable=None): g = g.copy(immutable=True) return g - def disjoint_union(self, other, labels="pairs", immutable=None): + def disjoint_union(self, other, labels='pairs', immutable=None): """ Return the disjoint union of ``self`` and ``other``. @@ -19485,7 +19451,6 @@ def disjoint_union(self, other, labels="pairs", immutable=None): Custom path disjoint_union Cycle graph: Graph on 5 vertices sage: J.vertices(sort=True) [(0, 'a'), (0, 'b'), (1, 0), (1, 1), (1, 2)] - """ if (self._directed and not other._directed) or (not self._directed and other._directed): raise TypeError('both arguments must be of the same class') @@ -20166,16 +20131,16 @@ def is_transitively_reduced(self): # Visualization - def _color_by_label(self, format='hex', as_function=False, default_color="black"): + def _color_by_label(self, format='hex', as_function=False, default_color='black'): """ - Coloring of the edges according to their label for plotting + Color the edges according to their label for plotting. INPUT: - ``format`` -- "rgbtuple", "hex", ``True`` (same as "hex"), or a - function or dictionary assigning colors to labels (default: "hex") + function or dictionary assigning colors to labels (default: ``'hex'``) - - ``default_color`` -- a string (default: ``"black"``); the color of the + - ``default_color`` -- string (default: ``'black'``); the color of the labels. Setting ``default_color=None`` is the same as ``default_color="black"``. @@ -20183,7 +20148,7 @@ def _color_by_label(self, format='hex', as_function=False, default_color="black" coloring as a function assigning a color to each label, or as a dictionary mapping colors to list of edges - OUTPUT: A coloring of the edges of this graph. + OUTPUT: a coloring of the edges of this graph If ``as_function`` is ``True``, then the coloring is returned as a function assigning a color to each label. Otherwise (the default, for @@ -20346,14 +20311,14 @@ def layout(self, layout=None, pos=None, dim=2, save_pos=False, **options): INPUT: - ``layout`` -- string (default: ``None``); specifies a layout algorithm - among ``"acyclic"``, ``"acyclic_dummy"``, ``"circular"``, - ``"ranked"``, ``"graphviz"``, ``"planar"``, ``"spring"``, - ``"forest"`` or ``"tree"`` + among ``'acyclic'``, ``'acyclic_dummy'``, ``'circular'``, + ``'ranked'``, ``'graphviz'``, ``'planar'``, ``'spring'``, + ``'forest'`` or ``'tree'`` - ``pos`` -- dictionary (default: ``None``); a dictionary of positions - - ``dim`` -- integer (default: ``2``); the number of dimensions of the - layout, 2 or 3 + - ``dim`` -- integer (default: `2`); the number of dimensions of the + layout, `2` or `3` - ``save_pos`` -- boolean (default: ``False``); whether to save the positions @@ -20380,7 +20345,7 @@ def layout(self, layout=None, pos=None, dim=2, save_pos=False, **options): ('1', 0): [0.89..., -0.42...], ('1', 1): [2.26..., -0.87...]} - sage: g.layout(layout="acyclic_dummy", save_pos=True) + sage: g.layout(layout='acyclic_dummy', save_pos=True) {('0', 0): [0.3..., 0], ('0', 1): [0.3..., 1], ('1', 0): [0.6..., 0], @@ -20413,7 +20378,7 @@ def layout(self, layout=None, pos=None, dim=2, save_pos=False, **options): sage: from sage.graphs.graph_plot import layout_options sage: for key, value in sorted(layout_options.items()): ....: print("option {} : {}".format(key, value)) - option by_component : Whether to do the spring layout by connected component -- a boolean. + option by_component : Whether to do the spring layout by connected component -- boolean. option dim : The dimension of the layout -- 2 or 3. option forest_roots : An iterable specifying which vertices to use as roots for the ``layout='forest'`` option. If no root is specified for a tree, then one is chosen close to the center of the tree. Ignored unless ``layout='forest'``. option heights : A dictionary mapping heights to the list of vertices at this height. @@ -20437,7 +20402,7 @@ def layout(self, layout=None, pos=None, dim=2, save_pos=False, **options): ``'acyclic'`` layout. See :meth:`.layout_graphviz` for installation instructions. - A subclass may implement another layout algorithm ``"blah"``, by + A subclass may implement another layout algorithm ``'blah'``, by implementing a method ``.layout_blah``. It may override the default layout by overriding :meth:`.layout_default`, and similarly override the predefined layouts. @@ -20479,9 +20444,9 @@ def layout_spring(self, by_component=True, **options): INPUT: - - ``by_components`` -- boolean (default: ``True``); + - ``by_components`` -- boolean (default: ``True``) - - ``**options`` -- options for method + - ``**options`` -- options for method :meth:`~sage.graphs.generic_graph_pyx.spring_layout_fast` OUTPUT: a dictionary mapping vertices to positions @@ -20497,7 +20462,7 @@ def layout_spring(self, by_component=True, **options): 4: [2.14..., -0.30...], 5: [2.80..., 0.22...]} sage: g = graphs.LadderGraph(7) - sage: g.plot(layout="spring") # needs sage.plot + sage: g.plot(layout='spring') # needs sage.plot Graphics object consisting of 34 graphics primitives """ return spring_layout_fast(self, by_component=by_component, **options) @@ -20506,17 +20471,17 @@ def layout_spring(self, by_component=True, **options): def layout_ranked(self, heights=None, dim=2, spring=False, **options): """ - Return a ranked layout for this graph + Return a ranked layout for this graph. INPUT: - ``heights`` -- dictionary (default: ``None``); a dictionary mapping heights to the list of vertices at this height - - ``dim`` -- integer (default: ``2``); the number of dimensions of the - layout, 2 or 3 + - ``dim`` -- integer (default: `2`); the number of dimensions of the + layout, `2` or `3` - - ``spring`` -- boolean (default: ``False``); + - ``spring`` -- boolean (default: ``False``) - ``**options`` -- options for method :meth:`~sage.graphs.generic_graph_pyx.spring_layout_fast` @@ -20537,7 +20502,7 @@ def layout_ranked(self, heights=None, dim=2, spring=False, **options): 4: [1.33..., 1], 5: [1.33..., 2]} sage: g = graphs.LadderGraph(7) - sage: g.plot(layout="ranked", heights={i: (i, i+7) for i in range(7)}) # needs sage.plot + sage: g.plot(layout='ranked', heights={i: (i, i+7) for i in range(7)}) # needs sage.plot Graphics object consisting of 34 graphics primitives """ assert heights is not None @@ -20582,14 +20547,14 @@ def layout_ranked(self, heights=None, dim=2, spring=False, **options): def layout_extend_randomly(self, pos, dim=2): """ - Extend randomly a partial layout + Extend randomly a partial layout. INPUT: - - ``pos`` -- a dictionary mapping vertices to positions + - ``pos`` -- dictionary mapping vertices to positions - - ``dim`` -- integer (default: ``2``); the number of dimensions of the - layout, 2 or 3 + - ``dim`` -- integer (default: `2`); the number of dimensions of the + layout, `2` or `3` OUTPUT: a dictionary mapping vertices to positions @@ -20626,26 +20591,26 @@ def layout_extend_randomly(self, pos, dim=2): def layout_circular(self, dim=2, center=(0, 0), radius=1, shift=0, angle=0, **options): r""" - Return a circular layout for this graph + Return a circular layout for this graph. INPUT: - - ``dim`` -- integer (default: ``2``); the number of dimensions of the - layout, 2 or 3 + - ``dim`` -- integer (default: `2`); the number of dimensions of the + layout, `2` or `3` - ``center`` -- tuple (default: ``(0, 0)``); position of the center of the circle - - ``radius`` -- (default: 1); the radius of the circle + - ``radius`` -- (default: 1) the radius of the circle - - ``shift`` -- (default: 0); rotation of the circle. A value of + - ``shift`` -- (default: 0) rotation of the circle. A value of ``shift=1`` will replace in the drawing the `i`-th element of the list by the `(i-1)`-th. Non-integer values are admissible, and a value of `\alpha` corresponds to a rotation of the circle by an angle of `\alpha 2\pi/n` (where `n` is the number of vertices set on the circle). - - ``angle`` -- (default: 0); rotate the embedding of all vertices. For + - ``angle`` -- (default: 0) rotate the embedding of all vertices. For instance, when ``angle == 0``, the first vertex get position ``(center[0] + radius, center[1])``. With a value of `\pi/2`, the first vertex get position ``(center[0], center[1] + radius)``. @@ -20665,7 +20630,7 @@ def layout_circular(self, dim=2, center=(0, 0), radius=1, shift=0, angle=0, **op 4: (0.43..., -0.90...), 5: (0.97..., -0.22...), 6: (0.78..., 0.62...)} - sage: G.plot(layout="circular") # needs sage.plot + sage: G.plot(layout='circular') # needs sage.plot Graphics object consisting of 22 graphics primitives """ assert dim == 2, "3D circular layout not implemented" @@ -20674,7 +20639,7 @@ def layout_circular(self, dim=2, center=(0, 0), radius=1, shift=0, angle=0, **op radius=1, shift=0, angle=pi/2, return_dict=True) - def layout_forest(self, tree_orientation="down", forest_roots=None, + def layout_forest(self, tree_orientation='down', forest_roots=None, **options): """ Return an ordered forest layout for this graph. @@ -20738,7 +20703,7 @@ def layout_forest(self, tree_orientation="down", forest_roots=None, forest_roots=forest_roots, **options) - def layout_tree(self, tree_orientation="down", tree_root=None, + def layout_tree(self, tree_orientation='down', tree_root=None, dim=2, **options): r""" Return an ordered tree layout for this graph. @@ -20757,8 +20722,8 @@ def layout_tree(self, tree_orientation="down", tree_root=None, which the tree is growing, can be ``'up'``, ``'down'``, ``'left'`` or ``'right'`` - - ``dim`` -- integer (default: ``2``); the number of dimensions of the - layout, 2 or 3 + - ``dim`` -- integer (default: `2`); the number of dimensions of the + layout, `2` or `3` - ``**options`` -- other parameters not used here @@ -20771,7 +20736,7 @@ def layout_tree(self, tree_orientation="down", tree_root=None, EXAMPLES:: sage: G = graphs.RandomTree(80) - sage: G.plot(layout="tree", tree_orientation="right") # needs sage.plot + sage: G.plot(layout='tree', tree_orientation='right') # needs sage.plot Graphics object consisting of 160 graphics primitives sage: T = graphs.RandomLobster(25, 0.3, 0.3) # needs networkx @@ -20793,7 +20758,7 @@ def layout_tree(self, tree_orientation="down", tree_root=None, 6: [0.0, -2]} sage: G = graphs.BalancedTree(2, 4) # needs networkx - sage: G.plot(layout="tree", tree_root=0, tree_orientation="up") # needs networkx sage.plot + sage: G.plot(layout='tree', tree_root=0, tree_orientation='up') # needs networkx sage.plot Graphics object consisting of 62 graphics primitives Using the embedding when it exists:: @@ -20811,7 +20776,7 @@ def layout_tree(self, tree_orientation="down", tree_root=None, 6: [2.0, -1], 7: [1.0, -2], 8: [0.0, -2]} - sage: T.plot(layout="tree", tree_root=3) # needs sage.plot + sage: T.plot(layout='tree', tree_root=3) # needs sage.plot Graphics object consisting of 18 graphics primitives TESTS:: @@ -20881,7 +20846,7 @@ def layout_tree(self, tree_orientation="down", tree_root=None, def slide(v, dx): """ - shift the vertex ``v`` and its descendants to the right by ``dx`` + Shift the vertex ``v`` and its descendants to the right by ``dx``. Precondition: ``v`` and its descendants have already had their positions computed. @@ -20959,8 +20924,8 @@ def layout_graphviz(self, dim=2, prog='dot', **options): INPUT: - - ``dim`` -- integer (default: ``2``); the number of dimensions of the - layout, 2 or 3 + - ``dim`` -- integer (default: `2`); the number of dimensions of the + layout, `2` or `3` - ``prog`` -- one of "dot", "neato", "twopi", "circo", or "fdp" @@ -20983,7 +20948,7 @@ def layout_graphviz(self, dim=2, prog='dot', **options): ('...', ...): [...,...], ('...', ...): [...,...], ('...', ...): [...,...]} - sage: g.plot(layout="graphviz") # optional - dot2tex graphviz + sage: g.plot(layout='graphviz') # optional - dot2tex graphviz Graphics object consisting of 29 graphics primitives Note: the actual coordinates are not deterministic @@ -20992,16 +20957,16 @@ def layout_graphviz(self, dim=2, prog='dot', **options): layout program. One may specify an alternative layout program:: sage: # optional - dot2tex graphviz - sage: g.plot(layout="graphviz", prog="dot") + sage: g.plot(layout='graphviz', prog='dot') Graphics object consisting of 29 graphics primitives - sage: g.plot(layout="graphviz", prog="neato") + sage: g.plot(layout='graphviz', prog='neato') Graphics object consisting of 29 graphics primitives - sage: g.plot(layout="graphviz", prog="twopi") + sage: g.plot(layout='graphviz', prog='twopi') Graphics object consisting of 29 graphics primitives - sage: g.plot(layout="graphviz", prog="fdp") + sage: g.plot(layout='graphviz', prog='fdp') Graphics object consisting of 29 graphics primitives sage: g = graphs.BalancedTree(5,2) # needs networkx - sage: g.plot(layout="graphviz", prog="circo") # needs networkx + sage: g.plot(layout='graphviz', prog='circo') # needs networkx Graphics object consisting of 62 graphics primitives .. TODO:: @@ -21042,7 +21007,7 @@ def layout_graphviz(self, dim=2, prog='dot', **options): key_to_vertex = {key(v): v for v in self} import dot2tex - positions = dot2tex.dot2tex(self.graphviz_string(**options), format="positions", prog=prog) + positions = dot2tex.dot2tex(self.graphviz_string(**options), format='positions', prog=prog) return {key_to_vertex[key]: pos for key, pos in positions.items()} @@ -21052,7 +21017,7 @@ def _layout_bounding_box(self, pos): INPUT: - - ``pos`` -- a dictionary of positions + - ``pos`` -- dictionary of positions EXAMPLES:: @@ -21101,18 +21066,18 @@ def _circle_embedding(self, vertices, center=(0, 0), radius=1, shift=0, angle=0, ``list(vertices)``. - ``center`` -- tuple (default: `(0, 0)`); position of the center of the - circle. + circle - - ``radius`` -- (default: 1); the radius of the circle. + - ``radius`` -- (default: 1) the radius of the circle - - ``shift`` -- (default: 0); rotation of the circle. A value of + - ``shift`` -- (default: 0) rotation of the circle. A value of ``shift=1`` will replace in the drawing the `i`-th element of the list by the `(i-1)`-th. Non-integer values are admissible, and a value of `\alpha` corresponds to a rotation of the circle by an angle of `\alpha 2\pi/n` (where `n` is the number of vertices set on the circle). - - ``angle`` -- (default: 0); rotate the embedding of all vertices. For + - ``angle`` -- (default: 0) rotate the embedding of all vertices. For instance, when ``angle == 0``, the first vertex get position ``(center[0] + radius, center[1])``. With a value of `\pi/2`, the first vertex get position ``(center[0], center[1] + radius)``. @@ -21193,9 +21158,9 @@ def _line_embedding(self, vertices, first=(0, 0), last=(0, 1), return_dict=False etc.). The order of the vertices in the line embedding is given by ``list(vertices)``. - - ``first`` -- tuple (default: `(0, 0)`); first coordinate of the line. + - ``first`` -- tuple (default: `(0, 0)`); first coordinate of the line - - ``last`` -- tuple (default: `(0, 1)`); last coordinate of the line. + - ``last`` -- tuple (default: `(0, 1)`); last coordinate of the line - ``return_dict`` -- boolean (default: ``False``); by default the computed positions of the specified vertices are stored in the @@ -21298,7 +21263,7 @@ def graphplot(self, **options): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -21380,7 +21345,7 @@ def plot(self, **options): - ``vertex_size`` -- size of vertices displayed - ``vertex_shape`` -- the shape to draw the vertices, for example - ``"o"`` for circle or ``"s"`` for square. Whole list is available at + ``'o'`` for circle or ``'s'`` for square. Whole list is available at https://matplotlib.org/api/markers_api.html. (Not available for multiedge digraphs.) @@ -21407,7 +21372,7 @@ def plot(self, **options): - ``iterations`` -- integer; how many iterations of the spring layout algorithm to go through, if applicable - - ``color_by_label`` -- a boolean or dictionary or function (default: + - ``color_by_label`` -- boolean or dictionary or function (default: ``False``); whether to color each edge with a different color according to its label; the colors are chosen along a rainbow, unless they are specified by a function or dictionary mapping labels to @@ -21426,7 +21391,7 @@ def plot(self, **options): Otherwise, then one is chosen at random. Ignored unless ``layout='tree'``. - - ``tree_orientation`` -- string (default: ``"down"``); one of "up" or + - ``tree_orientation`` -- string (default: ``'down'``); one of "up" or "down". If "up" (resp., "down"), then the root of the tree will appear on the bottom (resp., top) and the tree will grow upwards (resp. downwards). Ignored unless ``layout='tree'``. @@ -21614,7 +21579,7 @@ def plot(self, **options): :: sage: t = DiGraph('JCC???@A??GO??CO??GO??') - sage: t.plot(layout='tree', tree_root=0, tree_orientation="up") # needs sage.plot + sage: t.plot(layout='tree', tree_root=0, tree_orientation='up') # needs sage.plot Graphics object consisting of 22 graphics primitives sage: D = DiGraph({0: [1, 2, 3], 2: [1, 4], 3: [0]}) sage: D.plot() # needs sage.plot @@ -21662,30 +21627,29 @@ def plot(self, **options): """ return self.graphplot(**options).plot() - def show(self, method="matplotlib", **kwds): + def show(self, method='matplotlib', **kwds): """ Show the (di)graph. INPUT: - - ``method`` -- string (default: ``"matplotlib"``); method to use to - display the graph, either ``"matplotlib"``, or ``"js"`` to visualize + - ``method`` -- string (default: ``'matplotlib'``); method to use to + display the graph, either ``'matplotlib'``, or ``'js'`` to visualize it in a browser using `d3.js `_. - Any other argument supported by the drawing functions: - - ``"matplotlib"`` -- see :meth:`GenericGraph.plot + - ``'matplotlib'`` -- see :meth:`GenericGraph.plot ` and :meth:`sage.plot.graphics.Graphics.show` - - ``"js"`` -- see :meth:`~sage.graphs.graph_plot_js.gen_html_code` + - ``'js'`` -- see :meth:`~sage.graphs.graph_plot_js.gen_html_code` EXAMPLES:: sage: C = graphs.CubeGraph(8) sage: P = C.plot(vertex_labels=False, vertex_size=0, graph_border=True) # needs sage.plot sage: P.show() # long time (3s on sage.math, 2011), needs sage.plot - """ if method == "js": from sage.graphs.graph_plot_js import gen_html_code @@ -21722,9 +21686,9 @@ def plot3d(self, bgcolor=(1, 1, 1), - ``bgcolor`` -- rgb tuple (default: ``(1,1,1)``) - - ``vertex_size`` -- float (default: ``0.06``) + - ``vertex_size`` -- float (default: `0.06`) - - ``vertex_labels`` -- a boolean (default: ``False``); whether to + - ``vertex_labels`` -- boolean (default: ``False``); whether to display vertices using text labels instead of spheres - ``vertex_colors`` -- dictionary (default: ``None``); optional @@ -21739,15 +21703,15 @@ def plot3d(self, bgcolor=(1, 1, 1), :mod:`~sage.plot.plot3d.tachyon` (default: ``(0,0,0)``), and each entry is a list of edges. - - ``color_by_label`` -- a boolean or dictionary or function (default: + - ``color_by_label`` -- boolean or dictionary or function (default: ``False``) whether to color each edge with a different color according to its label; the colors are chosen along a rainbow, unless they are specified by a function or dictionary mapping labels to colors; this option is incompatible with ``edge_color`` and ``edge_colors``. - - ``edge_size`` -- float (default: ``0.02``) + - ``edge_size`` -- float (default: `0.02`) - - ``edge_size2`` -- float (default: ``0.0325``); used for + - ``edge_size2`` -- float (default: `0.0325`); used for :class:`~sage.plot.plot3d.tachyon.Tachyon` sleeves - ``pos3d`` -- a position dictionary for the vertices @@ -21979,9 +21943,9 @@ def show3d(self, bgcolor=(1, 1, 1), vertex_colors=None, vertex_size=0.06, - ``bgcolor`` -- rgb tuple (default: ``(1,1,1)``) - - ``vertex_size`` -- float (default: ``0.06``) + - ``vertex_size`` -- float (default: `0.06`) - - ``vertex_labels`` -- a boolean (default: ``False``); whether to + - ``vertex_labels`` -- boolean (default: ``False``); whether to display vertices using text labels instead of spheres - ``vertex_colors`` -- dictionary (default: ``None``); optional @@ -21996,15 +21960,15 @@ def show3d(self, bgcolor=(1, 1, 1), vertex_colors=None, vertex_size=0.06, :mod:`~sage.plot.plot3d.tachyon` (default: ``(0,0,0)``), and each entry is a list of edges. - - ``color_by_label`` -- a boolean or dictionary or function (default: + - ``color_by_label`` -- boolean or dictionary or function (default: ``False``) whether to color each edge with a different color according to its label; the colors are chosen along a rainbow, unless they are specified by a function or dictionary mapping labels to colors; this option is incompatible with ``edge_color`` and ``edge_colors``. - - ``edge_size`` -- float (default: ``0.02``) + - ``edge_size`` -- float (default: `0.02`) - - ``edge_size2`` -- float (default: ``0.0325``); used for + - ``edge_size2`` -- float (default: `0.0325`); used for :class:`~sage.plot.plot3d.tachyon.Tachyon` sleeves - ``pos3d`` -- a position dictionary for the vertices @@ -22101,7 +22065,7 @@ def get_label(vertex): return get_label # String representation to be used by other programs - @options(labels="string", + @options(labels='string', vertex_labels=True, edge_labels=False, edge_color=None, edge_colors=None, edge_options=(), @@ -22118,8 +22082,8 @@ def graphviz_string(self, **options): INPUT: - - ``labels`` -- string (default: ``"string"``); either ``"string"`` or - ``"latex"``. If labels is ``"string"``, latex commands are not + - ``labels`` -- string (default: ``'string'``); either ``'string'`` or + ``'latex'``. If labels is ``'string'``, latex commands are not interpreted. This option stands for both vertex labels and edge labels. @@ -22129,14 +22093,14 @@ def graphviz_string(self, **options): - ``edge_labels`` -- boolean (default: ``False``); whether to add the labels on edges - - ``edge_color`` -- (default: ``None``); specify a default color for the + - ``edge_color`` -- (default: ``None``) specify a default color for the edges. The color could be one of - - a name given as a string such as ``"blue"`` or ``"orchid"`` + - a name given as a string such as ``'blue'`` or ``'orchid'`` - - a HSV sequence in a string such as ``".52,.386,.22"`` + - a HSV sequence in a string such as ``'.52,.386,.22'`` - - a hexadecimal code such as ``"#DA3305"`` + - a hexadecimal code such as ``'#DA3305'`` - a 3-tuple of floating point (to be interpreted as RGB tuple). In this case the 3-tuple is converted in hexadecimal code. @@ -22146,7 +22110,7 @@ def graphviz_string(self, **options): not to be complete in which case the default color is used. See the option ``edge_color`` for a description of valid color formats. - - ``color_by_label`` -- a boolean or dictionary or function (default: + - ``color_by_label`` -- boolean or dictionary or function (default: ``False``); whether to color each edge with a different color according to its label; the colors are chosen along a rainbow, unless they are specified by a function or dictionary mapping labels to @@ -22158,11 +22122,11 @@ def graphviz_string(self, **options): dictionary of options for this edge - ``rankdir`` -- ``'left'``, ``'right'``, ``'up'``, or ``'down'`` - (default: ``'down'``, for consistency with ``graphviz``): the + (default: ``'down'``, for consistency with ``graphviz``); the preferred ranking direction for acyclic layouts; see the ``rankdir`` option of ``graphviz``. - - ``subgraph_clusters`` -- a list of lists of vertices (default: + - ``subgraph_clusters`` -- list of lists of vertices (default: ``[]``); From [dotspec]_: "If supported, the layout engine will do the layout so that the nodes belonging to the cluster are drawn together, with the entire drawing of the cluster contained within a bounding @@ -22191,7 +22155,7 @@ def graphviz_string(self, **options): A variant, with the labels in latex, for post-processing with ``dot2tex``:: - sage: print(G.graphviz_string(edge_labels=True, labels="latex")) + sage: print(G.graphviz_string(edge_labels=True, labels='latex')) graph { node [shape="plaintext"]; node_0 [label=" ", texlbl="$0$"]; @@ -22209,7 +22173,7 @@ def graphviz_string(self, **options): sage: G = DiGraph({0: {1: None, 2: None}, 1: {2: None}, 2: {3: 'foo'}, 3: {}}, ....: sparse=True) - sage: print(G.graphviz_string(edge_color="red")) + sage: print(G.graphviz_string(edge_color='red')) digraph { node_0 [label="0"]; node_1 [label="1"]; @@ -22231,7 +22195,7 @@ def graphviz_string(self, **options): sage: G = DiGraph() sage: G.add_edges((i, f(i), f) for i in (1, 2, 1/2, 1/4)) sage: G.add_edges((i, g(i), g) for i in (1, 2, 1/2, 1/4)) - sage: print(G.graphviz_string(labels="latex", # random + sage: print(G.graphviz_string(labels='latex', # random ....: edge_labels=True)) digraph { node [shape="plaintext"]; @@ -22258,7 +22222,7 @@ def graphviz_string(self, **options): node_4 -> node_9 [label=" ", texlbl="$x \ {\mapsto}\ \frac{1}{x + 1}$"]; } - sage: print(G.graphviz_string(labels="latex", # random # needs sage.symbolic + sage: print(G.graphviz_string(labels='latex', # random # needs sage.symbolic ....: color_by_label=True)) digraph { node [shape="plaintext"]; @@ -22285,7 +22249,7 @@ def graphviz_string(self, **options): node_4 -> node_9 [color = "#00ffff"]; } - sage: print(G.graphviz_string(labels="latex", # random # needs sage.symbolic + sage: print(G.graphviz_string(labels='latex', # random # needs sage.symbolic ....: color_by_label={f: "red", g: "blue"})) digraph { node [shape="plaintext"]; @@ -22317,7 +22281,7 @@ def graphviz_string(self, **options): alternative ranking directions for this layout:: sage: D = DiGraph([(1, 2)]) - sage: print(D.graphviz_string(rankdir="up")) + sage: print(D.graphviz_string(rankdir='up')) digraph { rankdir=BT node_0 [label="1"]; @@ -22325,14 +22289,14 @@ def graphviz_string(self, **options): node_0 -> node_1; } - sage: print(D.graphviz_string(rankdir="down")) + sage: print(D.graphviz_string(rankdir='down')) digraph { node_0 [label="1"]; node_1 [label="2"]; node_0 -> node_1; } - sage: print(D.graphviz_string(rankdir="left")) + sage: print(D.graphviz_string(rankdir='left')) digraph { rankdir=RL node_0 [label="1"]; @@ -22340,7 +22304,7 @@ def graphviz_string(self, **options): node_0 -> node_1; } - sage: print(D.graphviz_string(rankdir="right")) + sage: print(D.graphviz_string(rankdir='right')) digraph { rankdir=LR node_0 [label="1"]; @@ -22353,13 +22317,13 @@ def graphviz_string(self, **options): tuple thereof) which maps each edge to a dictionary of options. Valid options are - - ``"color"`` - - ``"dot"`` (a string containing a sequence of options in ``dot`` format) - - ``"label"`` (a string) - - ``"label_style"`` (``"string"`` or ``"latex"``) - - ``"edge_string"`` (``"--"`` or ``"->"``) - - ``"dir"`` (``"forward"``, ``"back"``, ``"both"`` or ``"none"``) - - ``"backward"`` (boolean), instead of defining the edge in the + - ``'color'`` + - ``'dot'`` (a string containing a sequence of options in ``dot`` format) + - ``'label'`` (a string) + - ``'label_style'`` (``'string'`` or ``'latex'``) + - ``'edge_string'`` (``'--'`` or ``'->'``) + - ``'dir'`` (``'forward'``, ``'back'``, ``'both'`` or ``'none'``) + - ``'backward'`` (boolean), instead of defining the edge in the graphviz string as ``u -> v`` it draws it as ``v -> u [dir=back]`` and instead of ``u -> v [dir=back]`` it draws it as ``v -> u``, this changes the way it is drawn by Graphviz's dot @@ -22421,7 +22385,7 @@ def graphviz_string(self, **options): node_9 [label="1"]; node_10 [label="2"]; - node_2 -> node_3 [label="coucou", color = "red"]; + node_2 -> node_3 [label='coucou', color = "red"]; node_2 -> node_7 [x=1,y=2, color = "blue"]; node_4 -> node_5 [color = "red"]; node_4 -> node_8 [color = "blue"]; @@ -22778,7 +22742,7 @@ def graphviz_to_file_named(self, filename, **options): ....: 2: {0: None, 1: None, 3: 'foo'}, 3: {2: 'foo'}}, ....: sparse=True) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(mode="a+t") as f: + sage: with tempfile.NamedTemporaryFile(mode='a+t') as f: ....: G.graphviz_to_file_named(f.name, edge_labels=True) ....: print(f.read()) graph { @@ -22888,7 +22852,7 @@ def characteristic_polynomial(self, var='x', laplacian=False): INPUT: - - ``x`` -- (default: ``'x'``); the variable of the characteristic + - ``x`` -- (default: ``'x'``) the variable of the characteristic polynomial - ``laplacian`` -- boolean (default: ``False``); if ``True``, use the @@ -23037,7 +23001,7 @@ def eigenspaces(self, laplacian=False): INPUT: - ``laplacian`` -- boolean (default: ``False``); if ``True``, use the - Laplacian matrix (see :meth:`kirchhoff_matrix`) + Laplacian matrix (see :meth:`kirchhoff_matrix`) OUTPUT: @@ -23147,28 +23111,28 @@ def eigenspaces(self, laplacian=False): def relabel(self, perm=None, inplace=True, return_map=False, check_input=True, complete_partial_function=True, immutable=None): r""" - Relabels the vertices of ``self`` + Relabel the vertices of ``self``. INPUT: - - ``perm`` -- a function, dictionary, iterable, permutation, or - ``None`` (default: ``None``) + - ``perm`` -- a function, dictionary, iterable, permutation, or + ``None`` (default: ``None``) - - ``inplace`` -- a boolean (default: ``True``) + - ``inplace`` -- boolean (default: ``True``) - - ``return_map`` -- a boolean (default: ``False``) + - ``return_map`` -- boolean (default: ``False``) - - ``check_input`` (boolean) -- whether to test input for - correctness. *This can potentially be very time-consuming !*. + - ``check_input`` -- boolean; whether to test input for + correctness. *This can potentially be very time-consuming !* - - ``complete_partial_function`` (boolean) -- whether to automatically - complete the permutation if some elements of the graph are not - associated with any new name. In this case, those elements are not - relabeled *This can potentially be very time-consuming !*. + - ``complete_partial_function`` -- boolean; whether to automatically + complete the permutation if some elements of the graph are not + associated with any new name. In this case, those elements are not + relabeled *This can potentially be very time-consuming !*. - - ``immutable`` (boolean) -- with ``inplace=False``, whether to create - a mutable/immutable relabelled copy. ``immutable=None`` (default) - means that the graph and its copy will behave the same way. + - ``immutable`` -- boolean; with ``inplace=False``, whether to create + a mutable/immutable relabelled copy. ``immutable=None`` (default) + means that the graph and its copy will behave the same way. If ``perm`` is a function ``f``, then each vertex ``v`` is relabeled to ``f(v)``. @@ -23470,7 +23434,7 @@ def relabel(self, perm=None, inplace=True, return_map=False, check_input=True, c def degree_to_cell(self, vertex, cell): """ - Returns the number of edges from vertex to an edge in cell. In the + Return the number of edges from vertex to an edge in cell. In the case of a digraph, returns a tuple (in_degree, out_degree). EXAMPLES:: @@ -23503,8 +23467,8 @@ def degree_to_cell(self, vertex, cell): def is_equitable(self, partition, quotient_matrix=False): """ - Checks whether the given partition is equitable with respect to - self. + Check whether the given partition is equitable with respect to + ``self``. A partition is equitable with respect to a graph if for every pair of cells C1, C2 of the partition, the number of edges from a vertex @@ -23512,16 +23476,14 @@ def is_equitable(self, partition, quotient_matrix=False): INPUT: + - ``partition`` -- list of lists - - ``partition`` -- a list of lists - - - ``quotient_matrix`` -- (default: ``False``) if True, and - the partition is equitable, returns a matrix over the integers - whose rows and columns represent cells of the partition, and whose - i,j entry is the number of vertices in cell j adjacent to each - vertex in cell i (since the partition is equitable, this is well - defined) - + - ``quotient_matrix`` -- boolean (default: ``False``); if ``True``, and + the partition is equitable, returns a matrix over the integers + whose rows and columns represent cells of the partition, and whose + i,j entry is the number of vertices in cell j adjacent to each + vertex in cell i (since the partition is equitable, this is well + defined) EXAMPLES:: @@ -23587,7 +23549,7 @@ def is_equitable(self, partition, quotient_matrix=False): def coarsest_equitable_refinement(self, partition, sparse=True): r""" Return the coarsest partition which is finer than the input - partition, and equitable with respect to self. + partition, and equitable with respect to ``self``. A partition is equitable with respect to a graph if for every pair of cells `C_1`, `C_2` of the partition, the number of edges from a vertex @@ -23598,10 +23560,10 @@ def coarsest_equitable_refinement(self, partition, sparse=True): INPUT: - - ``partition`` -- a list of lists + - ``partition`` -- list of lists - ``sparse`` -- boolean (default: ``False``); whether to use sparse or - dense representation - for small graphs, use dense for speed + dense representation - for small graphs, use dense for speed EXAMPLES:: @@ -23686,28 +23648,28 @@ def automorphism_group(self, partition=None, verbosity=0, INPUT: - - ``partition`` -- default is the unit partition, - otherwise computes the subgroup of the full automorphism group - respecting the partition. + - ``partition`` -- default is the unit partition, + otherwise computes the subgroup of the full automorphism group + respecting the partition. - - ``edge_labels`` -- default ``False``, otherwise allows - only permutations respecting edge labels. + - ``edge_labels`` -- (default: ``False``) whether to allow + only permutations respecting edge labels - - ``order`` -- (default ``False``) if ``True``, compute the - order of the automorphism group + - ``order`` -- (default: ``False``) if ``True``, compute the + order of the automorphism group - - ``return_group`` -- default ``True`` + - ``return_group`` -- (default: ``True``) - - ``orbits`` -- returns the orbits of the group acting - on the vertices of the graph + - ``orbits`` -- returns the orbits of the group acting + on the vertices of the graph - - ``algorithm`` -- If ``algorithm = "bliss"``, the automorphism group is + - ``algorithm`` -- if ``algorithm='bliss'``, the automorphism group is computed using the optional package bliss (http://www.tcs.tkk.fi/Software/bliss/index.html). Setting it to - ``"sage"`` uses Sage's implementation. If set to ``None`` (default), bliss + ``'sage'`` uses Sage's implementation. If set to ``None`` (default), bliss is used when available. - OUTPUT: The order of the output is group, order, orbits. However, there + OUTPUT: the order of the output is group, order, orbits. However, there are options to turn each of these on or off. EXAMPLES: @@ -23773,10 +23735,10 @@ def automorphism_group(self, partition=None, verbosity=0, sage: G.automorphism_group(edge_labels=True) # needs sage.groups Permutation Group with generators [(1,4)(2,3)] - sage: G.automorphism_group(edge_labels=True, algorithm="bliss") # optional - bliss + sage: G.automorphism_group(edge_labels=True, algorithm='bliss') # optional - bliss Permutation Group with generators [(1,4)(2,3)] - sage: G.automorphism_group(edge_labels=True, algorithm="sage") # needs sage.groups + sage: G.automorphism_group(edge_labels=True, algorithm='sage') # needs sage.groups Permutation Group with generators [(1,4)(2,3)] :: @@ -23832,7 +23794,7 @@ def automorphism_group(self, partition=None, verbosity=0, TESTS: - We get a :class:`KeyError` when given an invalid partition (:issue:`6087`):: + We get a :exc:`KeyError` when given an invalid partition (:issue:`6087`):: sage: g = graphs.CubeGraph(3) sage: g.relabel() @@ -23861,7 +23823,7 @@ def automorphism_group(self, partition=None, verbosity=0, sage: g = graphs.PetersenGraph() sage: ag = g.automorphism_group() # needs sage.groups - sage: all(len(ag.orbit(e, action="OnPairs")) == 30 # needs sage.groups + sage: all(len(ag.orbit(e, action='OnPairs')) == 30 # needs sage.groups ....: for e in g.edge_iterator(labels=False)) True @@ -24051,9 +24013,9 @@ def is_vertex_transitive(self, partition=None, verbosity=0, edge_labels=False, order=False, return_group=True, orbits=False): """ - Returns whether the automorphism group of self is transitive within + Return whether the automorphism group of ``self`` is transitive within the partition provided, by default the unit partition of the - vertices of self (thus by default tests for vertex transitivity in + vertices of ``self`` (thus by default tests for vertex transitivity in the usual sense). EXAMPLES:: @@ -24105,7 +24067,7 @@ def is_hamiltonian(self, solver=None, constraint_generation=None, INPUT: - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -24113,12 +24075,12 @@ def is_hamiltonian(self, solver=None, constraint_generation=None, :class:`MixedIntegerLinearProgram `. - - ``constraint_generation`` (boolean) -- whether to use constraint + - ``constraint_generation`` -- boolean; whether to use constraint generation when solving the Mixed Integer Linear Program. When ``constraint_generation = None``, constraint generation is used whenever the graph has a density larger than 70%. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``verbose_constraints`` -- boolean (default: ``False``); whether to @@ -24181,11 +24143,11 @@ def is_hamiltonian(self, solver=None, constraint_generation=None, def is_isomorphic(self, other, certificate=False, verbosity=0, edge_labels=False): r""" - Tests for isomorphism between self and other. + Test for isomorphism between ``self`` and ``other``. INPUT: - - ``certificate`` -- if True, then output is `(a, b)`, where `a` + - ``certificate`` -- if ``True``, then output is `(a, b)`, where `a` is a boolean and `b` is either a map or ``None`` - ``edge_labels`` -- boolean (default: ``False``); if ``True`` allows @@ -24409,7 +24371,6 @@ def is_isomorphic(self, other, certificate=False, verbosity=0, edge_labels=False (True, {6: 'x', 7: 'y'}) sage: A.is_isomorphic(B, certificate=True, edge_labels=True) (False, None) - """ if not self.order() and not other.order(): return (True, None) if certificate else True @@ -24519,15 +24480,15 @@ class by some canonization function `c`. If `G` and `H` are graphs, to this set partition will be computed. The default is the unit set partition. - - ``certificate`` -- boolean (default: ``False``). When set to + - ``certificate`` -- boolean (default: ``False``); when set to ``True``, a dictionary mapping from the vertices of the (di)graph to its canonical label will also be returned. - - ``edge_labels`` -- boolean (default: ``False``). When set to - ``True``, allows only permutations respecting edge labels. + - ``edge_labels`` -- boolean (default: ``False``); when set to + ``True``, allows only permutations respecting edge labels - - ``algorithm`` -- a string (default: ``None``). The algorithm to use; - currently available: + - ``algorithm`` -- string (default: ``None``); the algorithm to use. + Currently available: * ``'bliss'``: use the optional package bliss (http://www.tcs.tkk.fi/Software/bliss/index.html); @@ -24539,7 +24500,7 @@ class by some canonization function `c`. If `G` and `H` are graphs, Make sure you always compare canonical forms obtained by the same algorithm. - - ``return_graph`` -- boolean (default: ``True``). When set to + - ``return_graph`` -- boolean (default: ``True``); when set to ``False``, returns the list of edges of the canonical graph instead of the canonical graph; only available when ``'bliss'`` is explicitly set as algorithm. @@ -24596,11 +24557,11 @@ class by some canonization function `c`. If `G` and `H` are graphs, sage: G.add_edges( [(0,1,'a'),(1,2,'b'),(2,3,'c'),(3,4,'b'),(4,0,'a')] ) sage: G.canonical_label(edge_labels=True) Graph on 5 vertices - sage: G.canonical_label(edge_labels=True, algorithm="bliss", # optional - bliss + sage: G.canonical_label(edge_labels=True, algorithm='bliss', # optional - bliss ....: certificate=True) (Graph on 5 vertices, {0: 4, 1: 3, 2: 1, 3: 0, 4: 2}) - sage: G.canonical_label(edge_labels=True, algorithm="sage", + sage: G.canonical_label(edge_labels=True, algorithm='sage', ....: certificate=True) (Graph on 5 vertices, {0: 4, 1: 3, 2: 0, 3: 1, 4: 2}) @@ -24775,18 +24736,19 @@ def is_cayley(self, return_group=False, mapping=False, INPUT: - - ``return_group`` (boolean; ``False``) -- If ``True``, return a group for - which the graph is a Cayley graph. + - ``return_group`` -- boolean (default: ``False``); if ``True``, return + a group for which the graph is a Cayley graph - - ``mapping`` (boolean; ``False``) -- If ``True``, return a mapping from - vertices to group elements. + - ``mapping`` -- boolean (default: ``False``); if ``True``, return a + mapping from vertices to group elements - - ``generators`` (boolean; ``False``) -- If ``True``, return the generating - set of the Cayley graph. + - ``generators`` -- boolean (default: ``False``); if ``True``, return + the generating set of the Cayley graph - - ``allow_disconnected`` (boolean; ``False``) -- If ``True``, disconnected - graphs are considered Cayley if they can be obtained from the Cayley - construction with a generating set that does not generate the group. + - ``allow_disconnected`` -- boolean (default: ``False``); if ``True``, + disconnected graphs are considered Cayley if they can be obtained + from the Cayley construction with a generating set that does not + generate the group. ALGORITHM: @@ -25079,7 +25041,7 @@ def katz_matrix(self, alpha, nonedgesonly=False, vertices=None): absolute eigenvalue of the adjacency matrix) - ``nonedgesonly`` -- boolean (default: ``True``); if ``True``, value - for each edge present in the graph is set to zero. + for each edge present in the graph is set to zero - ``vertices`` -- list (default: ``None``); the ordering of the vertices defining how they should appear in the matrix. By default, @@ -25200,7 +25162,7 @@ def katz_centrality(self, alpha, u=None): - ``u`` -- the vertex whose Katz centrality needs to be measured (default: ``None``) - OUTPUT: a list containing the Katz centrality of each vertex if u=None + OUTPUT: list containing the Katz centrality of each vertex if u=None otherwise Katz centrality of the vertex u. EXAMPLES: @@ -25250,7 +25212,6 @@ def katz_centrality(self, alpha, u=None): 21/379 sage: (graphs.PathGraph(3) + graphs.PathGraph(4)).katz_centrality(1/20) {0: 11/199, 1: 21/199, 2: 11/199, 3: 21/379, 4: 41/379, 5: 41/379, 6: 21/379} - """ n = self.order() if n == 0: @@ -25512,9 +25473,10 @@ def tachyon_vertex_plot(g, bgcolor=(1, 1, 1), dictionary used for the plot. INPUT: - - ``pos3d`` -- a 3D layout of the vertices - - various rendering options + - ``pos3d`` -- a 3D layout of the vertices + + - various rendering options EXAMPLES:: @@ -25614,7 +25576,7 @@ def graph_isom_equivalent_non_edge_labeled_graph(g, partition=None, standard_lab vertices as a list of lists of vertices. If given, the partition of the vertices is as well relabeled - - ``standard_label`` -- (default: ``None``); edges in ``g`` with + - ``standard_label`` -- (default: ``None``) edges in ``g`` with this label are preserved in the new graph - ``return_relabeling`` -- boolean (default: ``False``); whether @@ -25629,7 +25591,7 @@ def graph_isom_equivalent_non_edge_labeled_graph(g, partition=None, standard_lab that attributes of ``g`` are *not* copied for speed issues, only edges and vertices. - - ``ignore_edge_labels`` -- boolean (default: ``False``): if + - ``ignore_edge_labels`` -- boolean (default: ``False``); if ``True``, ignore edge labels, so when constructing the new graph, only multiple edges are replaced with vertices. Labels on multiple edges are ignored -- only the multiplicity is relevant, diff --git a/src/sage/graphs/generic_graph_pyx.pyx b/src/sage/graphs/generic_graph_pyx.pyx index 9c6690bb8c5..c9969845710 100644 --- a/src/sage/graphs/generic_graph_pyx.pyx +++ b/src/sage/graphs/generic_graph_pyx.pyx @@ -123,7 +123,7 @@ def layout_split(layout_function, G, **options): def spring_layout_fast(G, iterations=50, int dim=2, vpos=None, bint rescale=True, bint height=False, by_component=False, **options): """ - Spring force model layout + Spring force model layout. This function primarily acts as a wrapper around :func:`run_spring`, converting to and from raw C types. @@ -134,7 +134,7 @@ def spring_layout_fast(G, iterations=50, int dim=2, vpos=None, bint rescale=True INPUT: - - ``by_component`` -- a boolean + - ``by_component`` -- boolean EXAMPLES:: @@ -272,25 +272,21 @@ cdef run_spring(int iterations, dimension_t _dim, double* pos, int* edges, int n INPUT: - iterations -- number of steps to take - _dim -- number of dimensions of freedom. Provide a value of type - `D_TWO` for 2 dimensions, or type `D_THREE` for three - dimensions. The actual value does not matter: only its - type is important. - pos -- already initialized initial positions - Each vertex is stored as [dim] consecutive doubles. - These doubles are then placed consecutively in the array. - For example, if dim=3, we would have - pos = [x_1, y_1, z_1, x_2, y_2, z_2, ... , x_n, y_n, z_n] - edges -- List of edges, sorted lexicographically by the first - (smallest) vertex, terminated by -1, -1. - The first two entries represent the first edge, and so on. - n -- number of vertices in the graph - height -- if True, do not update the last coordinate ever - - OUTPUT: - - Modifies contents of pos. + - ``iterations`` -- number of steps to take + - ``_dim`` -- number of dimensions of freedom. Provide a value of type `D_TWO` + for 2 dimensions, or type `D_THREE` for three dimensions. The actual + value does not matter: only its type is important. + - ``pos`` -- already initialized initial positions. Each vertex is stored as + [dim] consecutive doubles. These doubles are then placed consecutively + in the array. For example, if dim=3, we would have + pos = [x_1, y_1, z_1, x_2, y_2, z_2, ... , x_n, y_n, z_n] + - ``edges`` -- List of edges, sorted lexicographically by the first (smallest) + vertex, terminated by -1, -1. The first two entries represent the first + edge, and so on. + - ``n`` -- number of vertices in the graph + - ``height`` -- if ``True``, do not update the last coordinate ever + + OUTPUT: modifies contents of pos AUTHOR: @@ -417,7 +413,7 @@ def int_to_binary_string(n): INPUT: - - ``n`` (integer) + - ``n`` -- integer EXAMPLES:: @@ -447,7 +443,7 @@ def binary_string_to_graph6(x): INPUT: - - ``x`` -- a binary string. + - ``x`` -- a binary string EXAMPLES:: @@ -474,7 +470,7 @@ def small_integer_to_graph6(n): INPUT: - - ``n`` (integer) + - ``n`` -- integer EXAMPLES:: @@ -501,7 +497,7 @@ def length_and_string_from_graph6(s): INPUT: - ``s`` -- a graph6 string describing a binary vector (and encoding its - length). + length) EXAMPLES:: @@ -536,7 +532,7 @@ def length_and_string_from_graph6(s): def binary_string_from_graph6(s, n): r""" - Decode a binary string from its graph6 representation + Decode a binary string from its graph6 representation. This helper function is the inverse of `R` from [McK2015]_. @@ -544,7 +540,7 @@ def binary_string_from_graph6(s, n): - ``s`` -- a graph6 string - - ``n`` -- the length of the binary string encoded by ``s``. + - ``n`` -- the length of the binary string encoded by ``s`` EXAMPLES:: @@ -582,7 +578,7 @@ def binary_string_from_dig6(s, n): - ``s`` -- a graph6 string - - ``n`` -- the length of the binary string encoded by ``s``. + - ``n`` -- the length of the binary string encoded by ``s`` EXAMPLES:: @@ -637,11 +633,10 @@ cdef class SubgraphSearch: .. NOTE:: This algorithm does not take vertex/edge labels into account. - """ def __init__(self, G, H, induced=False): r""" - Constructor + Constructor. This constructor only checks there is no inconsistency in the input : `G` and `H` are both graphs or both digraphs and that `H` @@ -705,7 +700,7 @@ cdef class SubgraphSearch: def cardinality(self): r""" - Returns the number of labelled subgraphs of `G` isomorphic to + Return the number of labelled subgraphs of `G` isomorphic to `H`. .. NOTE:: @@ -807,7 +802,7 @@ cdef class SubgraphSearch: def __cinit__(self, G, H, induced=False): r""" - Cython constructor + Cython constructor. This method initializes all the C values. @@ -895,7 +890,7 @@ cdef class SubgraphSearch: def __next__(self): r""" - Returns the next isomorphic subgraph if any, and raises a + Return the next isomorphic subgraph if any, and raises a ``StopIteration`` otherwise. EXAMPLES:: @@ -981,20 +976,18 @@ cdef class SubgraphSearch: cdef inline bint vectors_equal(int n, int *a, int *b) noexcept: r""" - Tests whether the two given vectors are equal. Two integer vectors + Test whether the two given vectors are equal. Two integer vectors `a = (a_1, a_2, \dots, a_n)` and `b = (b_1, b_2, \dots, b_n)` are equal iff `a_i = b_i` for all `i = 1, 2, \dots, n`. See the function ``_test_vectors_equal_inferior()`` for unit tests. INPUT: - - ``n`` -- positive integer; length of the vectors. - - - ``a``, ``b`` -- two vectors of integers. + - ``n`` -- positive integer; length of the vectors - OUTPUT: + - ``a``, ``b`` -- two vectors of integers - - ``True`` if ``a`` and ``b`` are the same vector; ``False`` otherwise. + OUTPUT: ``True`` if ``a`` and ``b`` are the same vector; ``False`` otherwise """ cdef int i for i in range(n): @@ -1004,7 +997,7 @@ cdef inline bint vectors_equal(int n, int *a, int *b) noexcept: cdef inline bint vectors_inferior(int n, int *a, int *b) noexcept: r""" - Tests whether the second vector of integers is inferior to the first. Let + Test whether the second vector of integers is inferior to the first. Let `u = (u_1, u_2, \dots, u_k)` and `v = (v_1, v_2, \dots, v_k)` be two integer vectors of equal length. Then `u` is said to be less than (or inferior to) `v` if `u_i \leq v_i` for all `i = 1, 2, \dots, k`. See @@ -1015,9 +1008,9 @@ cdef inline bint vectors_inferior(int n, int *a, int *b) noexcept: INPUT: - - ``n`` -- positive integer; length of the vectors. + - ``n`` -- positive integer; length of the vectors - - ``a``, ``b`` -- two vectors of integers. + - ``a``, ``b`` -- two vectors of integers OUTPUT: @@ -1182,14 +1175,14 @@ cpdef tuple find_hamiltonian(G, long max_iter=100000, long reset_bound=30000, - ``max_iter`` -- maximum number of iterations - ``reset_bound`` -- number of iterations before restarting the - procedure + procedure - ``backtrack_bound`` -- number of iterations to elapse before - discarding the last 5 vertices of the path. + discarding the last 5 vertices of the path - - ``find_path`` -- (default: ``False``) if set to ``True``, will - search a Hamiltonian path; if ``False``, will search for a - Hamiltonian cycle + - ``find_path`` -- boolean (default: ``False``); if set to ``True``, will + search a Hamiltonian path. If ``False``, will search for a Hamiltonian + cycle. OUTPUT: @@ -1572,7 +1565,7 @@ def transitive_reduction_acyclic(G): INPUT: - - ``G`` -- an acyclic digraph. + - ``G`` -- an acyclic digraph EXAMPLES:: diff --git a/src/sage/graphs/genus.pyx b/src/sage/graphs/genus.pyx index 0ef32627af8..ec524fd1a7a 100644 --- a/src/sage/graphs/genus.pyx +++ b/src/sage/graphs/genus.pyx @@ -235,7 +235,6 @@ cdef class simple_connected_genus_backtracker: sage: gb = sage.graphs.genus.simple_connected_genus_backtracker(G._backend.c_graph()[0]) sage: gb.get_embedding() {} - """ if not self.num_verts: return {} @@ -402,7 +401,7 @@ cdef class simple_connected_genus_backtracker: def genus(self, int style=1, int cutoff=0, bint record_embedding=False): r""" - Compute the minimal or maximal genus of self's graph. + Compute the minimal or maximal genus of ``self``'s graph. Note, this is a remarkably naive algorithm for a very difficult problem. Most interesting cases will take millennia to finish, with the exception @@ -410,10 +409,10 @@ cdef class simple_connected_genus_backtracker: INPUT: - - ``style`` -- integer (default: ``1``); find minimum genus if 1, + - ``style`` -- integer (default: `1`); find minimum genus if 1, maximum genus if 2 - - ``cutoff`` -- integer (default: ``0``); stop searching if search style + - ``cutoff`` -- integer (default: `0`); stop searching if search style is 1 and ``genus`` `\leq` ``cutoff``, or if style is 2 and ``genus`` `\geq` ``cutoff``. This is useful where the genus of the graph has a known bound. @@ -422,9 +421,7 @@ cdef class simple_connected_genus_backtracker: to remember the best embedding seen. This embedding can be retrieved with ``self.get_embedding()``. - OUTPUT: - - the minimal or maximal genus for self's graph. + OUTPUT: the minimal or maximal genus for ``self``'s graph EXAMPLES:: @@ -480,8 +477,8 @@ cdef class simple_connected_genus_backtracker: """ Here's the main backtracking routine. - We iterate over all embeddings of self's graph by considering all - cyclic orderings of `self.vertex_darts`. We use the Steinhaus- + We iterate over all embeddings of ``self``'s graph by considering all + cyclic orderings of ``self.vertex_darts``. We use the Steinhaus- Johnson-Trotter algorithm to enumerate these by walking over a poly-ary Gray code, and each time the Gray code would flip a bit, we apply the next adjacent transposition from S-J-T at that vertex. @@ -588,7 +585,6 @@ def simple_connected_graph_genus(G, set_embedding=False, check=True, minimal=Tru REFERENCES: [1] http://www.springerlink.com/content/0776127h0r7548v7/ - """ cdef int style, cutoff oG = G # original graph diff --git a/src/sage/graphs/graph.py b/src/sage/graphs/graph.py index 01d4adc00ea..4b0b43e5adb 100644 --- a/src/sage/graphs/graph.py +++ b/src/sage/graphs/graph.py @@ -199,7 +199,7 @@ sage: G = Graph(M); G Graph on 10 vertices sage: G.plot().show() # or G.show() # needs sage.plot - sage: DiGraph(matrix(2, [0,0,-1,1]), format="incidence_matrix") + sage: DiGraph(matrix(2, [0,0,-1,1]), format='incidence_matrix') Traceback (most recent call last): ... ValueError: there must be two nonzero entries (-1 & 1) per column @@ -528,13 +528,13 @@ class Graph(GenericGraph): 3: [-1, 1]} - ``name`` -- (must be an explicitly named parameter, i.e., - ``name="complete")`` gives the graph a name + ``name='complete')`` gives the graph a name - ``loops`` -- boolean (default: ``None``); whether to allow loops (ignored - if data is an instance of the ``Graph`` class) + if data is an instance of the ``Graph`` class) - ``multiedges`` -- boolean (default: ``None``); whether to allow multiple - edges (ignored if data is an instance of the ``Graph`` class). + edges (ignored if data is an instance of the ``Graph`` class) - ``weighted`` -- boolean (default: ``None``); whether graph thinks of itself as weighted or not. See @@ -542,11 +542,11 @@ class Graph(GenericGraph): - ``format`` -- if set to ``None`` (default), :class:`Graph` tries to guess input's format. To avoid this possibly time-consuming step, one of the - following values can be specified (see description above): ``"int"``, - ``"graph6"``, ``"sparse6"``, ``"rule"``, ``"list_of_edges"``, - ``"dict_of_lists"``, ``"dict_of_dicts"``, ``"adjacency_matrix"``, - ``"weighted_adjacency_matrix"``, ``"seidel_adjacency_matrix"``, - ``"incidence_matrix"``, ``"NX"``, ``"igraph"``. + following values can be specified (see description above): ``'int'``, + ``'graph6'``, ``'sparse6'``, ``'rule'``, ``'list_of_edges'``, + ``'dict_of_lists'``, ``'dict_of_dicts'``, ``'adjacency_matrix'``, + ``'weighted_adjacency_matrix'``, ``'seidel_adjacency_matrix'``, + ``'incidence_matrix'``, ``"NX"``, ``'igraph'``. - ``sparse`` -- boolean (default: ``True``); ``sparse=True`` is an alias for ``data_structure="sparse"``, and ``sparse=False`` is an alias for @@ -555,13 +555,13 @@ class Graph(GenericGraph): - ``data_structure`` -- one of the following (for more information, see :mod:`~sage.graphs.base.overview`) - * ``"dense"`` -- selects the :mod:`~sage.graphs.base.dense_graph` + * ``'dense'`` -- selects the :mod:`~sage.graphs.base.dense_graph` backend. - * ``"sparse"`` -- selects the :mod:`~sage.graphs.base.sparse_graph` + * ``'sparse'`` -- selects the :mod:`~sage.graphs.base.sparse_graph` backend. - * ``"static_sparse"`` -- selects the + * ``'static_sparse'`` -- selects the :mod:`~sage.graphs.base.static_sparse_backend` (this backend is faster than the sparse backend and smaller in memory, and it is immutable, so that the resulting graphs can be used as dictionary keys). @@ -580,9 +580,9 @@ class Graph(GenericGraph): is the number of vertices. - ``convert_empty_dict_labels_to_None`` -- this arguments sets the default - edge labels used by NetworkX (empty dictionaries) to be replaced by - ``None``, the default Sage edge label. It is set to ``True`` iff a - NetworkX graph is on the input. + edge labels used by NetworkX (empty dictionaries) to be replaced by + ``None``, the default Sage edge label. It is set to ``True`` iff a + NetworkX graph is on the input. EXAMPLES: @@ -788,7 +788,7 @@ class Graph(GenericGraph): ....: regular_symmetric_hadamard_matrix_with_constant_diagonal as rshcd) sage: m = rshcd(16,1) - matrix.identity(16) # needs sage.combinat sage.modules sage: Graph(m, # needs sage.combinat sage.modules - ....: format="seidel_adjacency_matrix").is_strongly_regular(parameters=True) + ....: format='seidel_adjacency_matrix').is_strongly_regular(parameters=True) (16, 6, 2, 2) #. List of edges, or labelled edges:: @@ -880,7 +880,7 @@ class Graph(GenericGraph): TESTS:: - sage: Graph(4, format="HeyHeyHey") + sage: Graph(4, format='HeyHeyHey') Traceback (most recent call last): ... ValueError: Unknown input format 'HeyHeyHey' @@ -893,16 +893,16 @@ class Graph(GenericGraph): sage: # needs sage.modules sage: m = matrix([[0, -1], [-1, 0]]) - sage: Graph(m, format="seidel_adjacency_matrix") + sage: Graph(m, format='seidel_adjacency_matrix') Graph on 2 vertices sage: m[0,1] = 1 - sage: Graph(m, format="seidel_adjacency_matrix") + sage: Graph(m, format='seidel_adjacency_matrix') Traceback (most recent call last): ... ValueError: the adjacency matrix of a Seidel graph must be symmetric sage: m[0,1] = -1; m[1,1] = 1 # needs sage.modules - sage: Graph(m, format="seidel_adjacency_matrix") # needs sage.modules + sage: Graph(m, format='seidel_adjacency_matrix') # needs sage.modules Traceback (most recent call last): ... ValueError: the adjacency matrix of a Seidel graph must have 0s on the main diagonal @@ -922,7 +922,7 @@ class Graph(GenericGraph): _directed = False def __init__(self, data=None, pos=None, loops=None, format=None, - weighted=None, data_structure="sparse", + weighted=None, data_structure='sparse', vertex_labels=True, name=None, multiedges=None, convert_empty_dict_labels_to_None=None, sparse=True, immutable=False, hash_labels=None): @@ -993,7 +993,7 @@ def __init__(self, data=None, pos=None, loops=None, format=None, sage: B = {0:{1:2,2:5,3:4},1:{2:2,4:7},2:{3:1,4:4,5:3},3:{5:4},4:{5:1,6:5},5:{6:7}} sage: grafo3 = Graph(B, weighted=True) sage: matad = grafo3.weighted_adjacency_matrix() # needs sage.modules - sage: grafo4 = Graph(matad, format="adjacency_matrix", weighted=True) # needs sage.modules + sage: grafo4 = Graph(matad, format='adjacency_matrix', weighted=True) # needs sage.modules sage: grafo4.shortest_path(0, 6, by_weight=True) # needs sage.modules [0, 1, 2, 5, 4, 6] @@ -1351,8 +1351,8 @@ def sparse6_string(self): :: - sage: G = Graph(loops=True, multiedges=True, data_structure="sparse") - sage: Graph(':?', data_structure="sparse") == G + sage: G = Graph(loops=True, multiedges=True, data_structure='sparse') + sage: Graph(':?', data_structure='sparse') == G True TESTS:: @@ -1474,7 +1474,7 @@ def is_directed(self): @doc_index("Graph properties") def is_tree(self, certificate=False, output='vertex'): r""" - Tests if the graph is a tree + Test if the graph is a tree. The empty graph is defined to be not a tree. @@ -1634,7 +1634,7 @@ def vertices_to_edges(x): @doc_index("Graph properties") def is_forest(self, certificate=False, output='vertex'): """ - Tests if the graph is a forest, i.e. a disjoint union of trees. + Test if the graph is a forest, i.e. a disjoint union of trees. INPUT: @@ -1799,7 +1799,6 @@ def is_block_graph(self): - :meth:`~sage.graphs.generic_graph.GenericGraph.blocks_and_cut_vertices` - :meth:`~sage.graphs.generic_graph.GenericGraph.blocks_and_cuts_tree` - EXAMPLES:: sage: G = graphs.RandomBlockGraph(6, 2, kmax=4) @@ -2041,7 +2040,7 @@ def apex_vertices(self, k=None): sage: G.apex_vertices(k=-1) Traceback (most recent call last): ... - ValueError: parameter k must be a non negative integer + ValueError: parameter k must be a nonnegative integer The graph might be mutable or immutable:: @@ -2052,7 +2051,7 @@ def apex_vertices(self, k=None): if k is None: k = self.order() elif k < 0: - raise ValueError("parameter k must be a non negative integer") + raise ValueError("parameter k must be a nonnegative integer") # Easy cases: null graph, subgraphs of K_5 and K_3,3 if self.order() <= 5 or (self.order() <= 6 and self.is_bipartite()): @@ -2130,7 +2129,7 @@ def apex_vertices(self, k=None): @doc_index("Graph properties") def is_overfull(self): r""" - Tests whether the current graph is overfull. + Test whether the current graph is overfull. A graph `G` on `n` vertices and `m` edges is said to be overfull if: @@ -2228,7 +2227,7 @@ def is_overfull(self): @doc_index("Graph properties") def is_even_hole_free(self, certificate=False): r""" - Tests whether ``self`` contains an induced even hole. + Test whether ``self`` contains an induced even hole. A Hole is a cycle of length at least 4 (included). It is said to be even (resp. odd) if its length is even (resp. odd). @@ -2327,7 +2326,7 @@ def is_even_hole_free(self, certificate=False): @doc_index("Graph properties") def is_odd_hole_free(self, certificate=False): r""" - Tests whether ``self`` contains an induced odd hole. + Test whether ``self`` contains an induced odd hole. A Hole is a cycle of length at least 4 (included). It is said to be even (resp. odd) if its length is even (resp. odd). @@ -2398,7 +2397,7 @@ def is_odd_hole_free(self, certificate=False): @doc_index("Graph properties") def is_triangle_free(self, algorithm='dense_graph', certificate=False): r""" - Check whether ``self`` is triangle-free + Check whether ``self`` is triangle-free. INPUT: @@ -2406,7 +2405,7 @@ def is_triangle_free(self, algorithm='dense_graph', certificate=False): to use among: - ``'matrix'`` -- tests if the trace of the adjacency matrix is - positive. + positive - ``'bitset'`` -- encodes adjacencies into bitsets and uses fast bitset operations to test if the input graph contains a @@ -2520,7 +2519,7 @@ def is_triangle_free(self, algorithm='dense_graph', certificate=False): @doc_index("Graph properties") def is_split(self): r""" - Returns ``True`` if the graph is a Split graph, ``False`` otherwise. + Return ``True`` if the graph is a Split graph, ``False`` otherwise. A Graph `G` is said to be a split graph if its vertices `V(G)` can be partitioned into two sets `K` and `I` such that the vertices of `K` @@ -2539,7 +2538,6 @@ def is_split(self): where `\omega = max \{i:d_i\geq i-1\}`. - EXAMPLES: Split graphs are, in particular, chordal graphs. Hence, The Petersen @@ -2589,7 +2587,7 @@ def is_split(self): @doc_index("Algorithmically hard stuff") def is_perfect(self, certificate=False): r""" - Tests whether the graph is perfect. + Test whether the graph is perfect. A graph `G` is said to be perfect if `\chi(H)=\omega(H)` hold for any induced subgraph `H\subseteq_i G` (and so for `G` itself, too), where @@ -2604,7 +2602,7 @@ def is_perfect(self, certificate=False): INPUT: - ``certificate`` -- boolean (default: ``False``); whether to return a - certificate. + certificate OUTPUT: @@ -2682,7 +2680,6 @@ def is_perfect(self, certificate=False): Traceback (most recent call last): ... ValueError: This method is only defined for simple graphs, and yours is not one of them ! - """ if self.has_multiple_edges() or self.has_loops(): raise ValueError("This method is only defined for simple graphs," @@ -2706,7 +2703,7 @@ def is_perfect(self, certificate=False): @doc_index("Graph properties") def is_edge_transitive(self): r""" - Check if self is an edge transitive graph. + Check if ``self`` is an edge transitive graph. A graph is edge-transitive if its automorphism group acts transitively on its edge set. @@ -2751,7 +2748,7 @@ def is_edge_transitive(self): @doc_index("Graph properties") def is_arc_transitive(self): r""" - Check if self is an arc-transitive graph + Check if ``self`` is an arc-transitive graph. A graph is arc-transitive if its automorphism group acts transitively on its pairs of adjacent vertices. @@ -2791,7 +2788,7 @@ def is_arc_transitive(self): @doc_index("Graph properties") def is_half_transitive(self): """ - Check if self is a half-transitive graph. + Check if ``self`` is a half-transitive graph. A graph is half-transitive if it is both vertex and edge transitive but not arc-transitive. @@ -2828,7 +2825,7 @@ def is_half_transitive(self): @doc_index("Graph properties") def is_semi_symmetric(self): """ - Check if self is semi-symmetric. + Check if ``self`` is semi-symmetric. A graph is semi-symmetric if it is regular, edge-transitive but not vertex-transitive. @@ -2925,7 +2922,7 @@ def is_path(self): def degree_constrained_subgraph(self, bounds, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Returns a degree-constrained subgraph. + Return a degree-constrained subgraph. Given a graph `G` and two functions `f, g:V(G)\rightarrow \mathbb Z` such that `f \leq g`, a degree-constrained subgraph in `G` is @@ -2934,7 +2931,7 @@ def degree_constrained_subgraph(self, bounds, solver=None, verbose=0, INPUT: - - ``bounds`` -- (default: ``None``); Two possibilities: + - ``bounds`` -- (default: ``None``) two possibilities: - A dictionary whose keys are the vertices, and values a pair of real values ``(min,max)`` corresponding to the values @@ -2944,7 +2941,7 @@ def degree_constrained_subgraph(self, bounds, solver=None, verbose=0, real values ``(min,max)`` corresponding to the values `(f(v),g(v))`. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -2952,7 +2949,7 @@ def degree_constrained_subgraph(self, bounds, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -3028,7 +3025,7 @@ def weight(x): @doc_index("Connectivity, orientations, trees") def strong_orientation(self): r""" - Returns a strongly connected orientation of the current graph. + Return a strongly connected orientation of the current graph. An orientation of an undirected graph is a digraph obtained by giving an unique direction to each of its edges. An orientation is said to be @@ -3040,9 +3037,7 @@ def strong_orientation(self): the orientation returned will ensure that each 2-connected component has a strongly connected orientation. - OUTPUT: - - A digraph representing an orientation of the current graph. + OUTPUT: a digraph representing an orientation of the current graph .. NOTE:: @@ -3084,7 +3079,6 @@ def strong_orientation(self): sage: g = Graph([(1,2),(1,2)], multiedges=True) sage: g.strong_orientation() Multi-digraph on 2 vertices - """ from sage.graphs.digraph import DiGraph d = DiGraph(multiedges=self.allows_multiple_edges()) @@ -3147,7 +3141,7 @@ def strong_orientation(self): def minimum_outdegree_orientation(self, use_edge_labels=False, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Returns an orientation of ``self`` with the smallest possible maximum + Return an orientation of ``self`` with the smallest possible maximum outdegree. Given a Graph `G`, it is polynomial to compute an orientation `D` of the @@ -3165,7 +3159,7 @@ def minimum_outdegree_orientation(self, use_edge_labels=False, solver=None, verb - When set to ``False`` (default), gives a weight of 1 to all the edges. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -3173,7 +3167,7 @@ def minimum_outdegree_orientation(self, use_edge_labels=False, solver=None, verb :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -3257,12 +3251,12 @@ def outgoing(u, e, variable): def bounded_outdegree_orientation(self, bound, solver=None, verbose=False, *, integrality_tolerance=1e-3): r""" - Computes an orientation of ``self`` such that every vertex `v` has + Compute an orientation of ``self`` such that every vertex `v` has out-degree less than `b(v)` INPUT: - - ``bound`` -- Maximum bound on the out-degree. Can be of three + - ``bound`` -- maximum bound on the out-degree. Can be of three different types : * An integer `k`. In this case, computes an orientation whose maximum @@ -3274,7 +3268,7 @@ def bounded_outdegree_orientation(self, bound, solver=None, verbose=False, * A function associating to each vertex its associated maximum out-degree. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -3282,7 +3276,7 @@ def bounded_outdegree_orientation(self, bound, solver=None, verbose=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -3292,7 +3286,7 @@ def bounded_outdegree_orientation(self, bound, solver=None, verbose=False, OUTPUT: A DiGraph representing the orientation if it exists. - A :class:`ValueError` exception is raised otherwise. + A :exc:`ValueError` exception is raised otherwise. ALGORITHM: @@ -3357,7 +3351,6 @@ def bounded_outdegree_orientation(self, bound, solver=None, verbose=False, ....: all( D.out_degree(v) <= b(v) for v in g ) or ....: D.size() != g.size()): ....: print("Something wrong happened") - """ self._scream_if_not_simple() from sage.graphs.digraph import DiGraph @@ -3432,8 +3425,8 @@ def orientations(self, data_structure=None, sparse=None): INPUT: - - ``data_structure`` -- one of ``"sparse"``, ``"static_sparse"``, or - ``"dense"``; see the documentation of :class:`Graph` or + - ``data_structure`` -- one of ``'sparse'``, ``'static_sparse'``, or + ``'dense'``; see the documentation of :class:`Graph` or :class:`DiGraph`; default is the data structure of ``self`` - ``sparse`` -- boolean (default: ``None``); ``sparse=True`` is an alias @@ -3617,7 +3610,7 @@ def chromatic_index(self, solver=None, verbose=0, *, integrality_tolerance=1e-3) INPUT: - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -3625,7 +3618,7 @@ def chromatic_index(self, solver=None, verbose=0, *, integrality_tolerance=1e-3) :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -3684,7 +3677,7 @@ def chromatic_index(self, solver=None, verbose=0, *, integrality_tolerance=1e-3) integrality_tolerance=integrality_tolerance) @doc_index("Coloring") - def chromatic_number(self, algorithm="DLX", solver=None, verbose=0, + def chromatic_number(self, algorithm='DLX', solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return the minimal number of colors needed to color the vertices of the @@ -3692,31 +3685,31 @@ def chromatic_number(self, algorithm="DLX", solver=None, verbose=0, INPUT: - - ``algorithm`` -- string (default: ``"DLX"``); one of the following + - ``algorithm`` -- string (default: ``'DLX'``); one of the following algorithms: - - ``"DLX"`` (default): the chromatic number is computed using the + - ``'DLX'`` (default): the chromatic number is computed using the dancing link algorithm. It is inefficient speedwise to compute the chromatic number through the dancing link algorithm because this algorithm computes *all* the possible colorings to check that one exists. - - ``"CP"``: the chromatic number is computed using the coefficients of + - ``'CP'``: the chromatic number is computed using the coefficients of the chromatic polynomial. Again, this method is inefficient in terms of speed and it only useful for small graphs. - - ``"MILP"``: the chromatic number is computed using a mixed integer + - ``'MILP'``: the chromatic number is computed using a mixed integer linear program. The performance of this implementation is affected by whether optional MILP solvers have been installed (see the :mod:`MILP module `, or Sage's tutorial on Linear Programming). - - ``"parallel"``: all the above algorithms are executed in parallel + - ``'parallel'``: all the above algorithms are executed in parallel and the result is returned as soon as one algorithm ends. Observe that the speed of the above algorithms depends on the size and structure of the graph. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -3724,7 +3717,7 @@ def chromatic_number(self, algorithm="DLX", solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -3739,13 +3732,13 @@ def chromatic_number(self, algorithm="DLX", solver=None, verbose=0, EXAMPLES:: sage: G = Graph({0: [1, 2, 3], 1: [2]}) - sage: G.chromatic_number(algorithm="DLX") + sage: G.chromatic_number(algorithm='DLX') 3 - sage: G.chromatic_number(algorithm="MILP") + sage: G.chromatic_number(algorithm='MILP') 3 - sage: G.chromatic_number(algorithm="CP") # needs sage.libs.flint + sage: G.chromatic_number(algorithm='CP') # needs sage.libs.flint 3 - sage: G.chromatic_number(algorithm="parallel") + sage: G.chromatic_number(algorithm='parallel') 3 A bipartite graph has (by definition) chromatic number 2:: @@ -3780,17 +3773,17 @@ def chromatic_number(self, algorithm="DLX", solver=None, verbose=0, TESTS:: sage: G = Graph() - sage: G.chromatic_number(algorithm="DLX") + sage: G.chromatic_number(algorithm='DLX') 0 - sage: G.chromatic_number(algorithm="MILP") + sage: G.chromatic_number(algorithm='MILP') 0 - sage: G.chromatic_number(algorithm="CP") # needs sage.libs.flint + sage: G.chromatic_number(algorithm='CP') # needs sage.libs.flint 0 - sage: G.chromatic_number(algorithm="parallel") + sage: G.chromatic_number(algorithm='parallel') 0 sage: G = Graph({0: [1, 2, 3], 1: [2]}) - sage: G.chromatic_number(algorithm="foo") + sage: G.chromatic_number(algorithm='foo') Traceback (most recent call last): ... ValueError: the 'algorithm' keyword must be set to either 'DLX', 'MILP', 'CP' or 'parallel' @@ -3829,14 +3822,14 @@ def func(alg): raise ValueError("the 'algorithm' keyword must be set to either 'DLX', 'MILP', 'CP' or 'parallel'") @doc_index("Coloring") - def coloring(self, algorithm="DLX", hex_colors=False, solver=None, verbose=0, + def coloring(self, algorithm='DLX', hex_colors=False, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return the first (optimal) proper vertex-coloring found. INPUT: - - ``algorithm`` -- Select an algorithm from the following supported + - ``algorithm`` -- select an algorithm from the following supported algorithms: - If ``algorithm="DLX"`` (default), the coloring is computed using the @@ -3848,9 +3841,9 @@ def coloring(self, algorithm="DLX", hex_colors=False, solver=None, verbose=0, the :mod:`MILP module `). - ``hex_colors`` -- boolean (default: ``False``); if ``True``, return a - dictionary which can easily be used for plotting. + dictionary which can easily be used for plotting - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -3858,7 +3851,7 @@ def coloring(self, algorithm="DLX", hex_colors=False, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -3873,8 +3866,8 @@ def coloring(self, algorithm="DLX", hex_colors=False, solver=None, verbose=0, EXAMPLES:: sage: G = Graph("Fooba") - sage: P = G.coloring(algorithm="MILP") - sage: Q = G.coloring(algorithm="DLX") + sage: P = G.coloring(algorithm='MILP') + sage: Q = G.coloring(algorithm='DLX') sage: def are_equal_colorings(A, B): ....: return Set(map(Set, A)) == Set(map(Set, B)) sage: are_equal_colorings(P, [[1, 2, 3], [0, 5, 6], [4]]) @@ -3885,9 +3878,9 @@ def coloring(self, algorithm="DLX", hex_colors=False, solver=None, verbose=0, sage: # needs sage.plot sage: G.plot(partition=P) Graphics object consisting of 16 graphics primitives - sage: G.coloring(hex_colors=True, algorithm="MILP") + sage: G.coloring(hex_colors=True, algorithm='MILP') {'#0000ff': [4], '#00ff00': [0, 6, 5], '#ff0000': [2, 1, 3]} - sage: H = G.coloring(hex_colors=True, algorithm="DLX"); H + sage: H = G.coloring(hex_colors=True, algorithm='DLX'); H {'#0000ff': [4], '#00ff00': [1, 2, 3], '#ff0000': [0, 5, 6]} sage: G.plot(vertex_colors=H) Graphics object consisting of 16 graphics primitives @@ -3899,7 +3892,7 @@ def coloring(self, algorithm="DLX", hex_colors=False, solver=None, verbose=0, TESTS:: - sage: G.coloring(algorithm="foo") + sage: G.coloring(algorithm='foo') Traceback (most recent call last): ... ValueError: The 'algorithm' keyword must be set to either 'DLX' or 'MILP'. @@ -4130,7 +4123,7 @@ def asc(sigma): return ret @doc_index("Leftovers") - def matching(self, value_only=False, algorithm="Edmonds", + def matching(self, value_only=False, algorithm='Edmonds', use_edge_labels=False, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" @@ -4157,11 +4150,11 @@ def matching(self, value_only=False, algorithm="Edmonds", - ``value_only`` -- boolean (default: ``False``); when set to ``True``, only the cardinal (or the weight) of the matching is returned - - ``algorithm`` -- string (default: ``"Edmonds"``) + - ``algorithm`` -- string (default: ``'Edmonds'``) - - ``"Edmonds"`` selects Edmonds' algorithm as implemented in NetworkX + - ``'Edmonds'`` selects Edmonds' algorithm as implemented in NetworkX - - ``"LP"`` uses a Linear Program formulation of the matching problem + - ``'LP'`` uses a Linear Program formulation of the matching problem - ``use_edge_labels`` -- boolean (default: ``False``) @@ -4170,7 +4163,7 @@ def matching(self, value_only=False, algorithm="Edmonds", - when set to ``False``, each edge has weight `1` - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -4178,7 +4171,7 @@ def matching(self, value_only=False, algorithm="Edmonds", :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity: + - ``verbose`` -- integer (default: 0); sets the level of verbosity: set to 0 by default, which means quiet (only useful when ``algorithm == "LP"``) @@ -4212,7 +4205,7 @@ def matching(self, value_only=False, algorithm="Edmonds", Same test with the Linear Program formulation:: sage: g = graphs.PappusGraph() - sage: g.matching(algorithm="LP", value_only=True) # needs sage.numerical.mip + sage: g.matching(algorithm='LP', value_only=True) # needs sage.numerical.mip 9 .. PLOT:: @@ -4228,7 +4221,7 @@ def matching(self, value_only=False, algorithm="Edmonds", sage: g = Graph([(0,1,0), (1,2,999), (2,3,-5)]) sage: sorted(g.matching()) # needs sage.networkx [(0, 1, 0), (2, 3, -5)] - sage: sorted(g.matching(algorithm="LP")) # needs sage.numerical.mip + sage: sorted(g.matching(algorithm='LP')) # needs sage.numerical.mip [(0, 1, 0), (2, 3, -5)] When ``use_edge_labels`` is set to ``True``, with Edmonds' algorithm and @@ -4237,7 +4230,7 @@ def matching(self, value_only=False, algorithm="Edmonds", sage: g = Graph([(0,1,0), (1,2,999), (2,3,-5)]) sage: g.matching(use_edge_labels=True) # needs sage.networkx [(1, 2, 999)] - sage: g.matching(algorithm="LP", use_edge_labels=True) # needs sage.numerical.mip + sage: g.matching(algorithm='LP', use_edge_labels=True) # needs sage.numerical.mip [(1, 2, 999)] With loops and multiedges:: @@ -4253,11 +4246,11 @@ def matching(self, value_only=False, algorithm="Edmonds", TESTS: - If ``algorithm`` is set to anything different from ``"Edmonds"`` or - ``"LP"``, an exception is raised:: + If ``algorithm`` is set to anything different from ``'Edmonds'`` or + ``'LP'``, an exception is raised:: sage: g = graphs.PappusGraph() - sage: g.matching(algorithm="somethingdifferent") + sage: g.matching(algorithm='somethingdifferent') Traceback (most recent call last): ... ValueError: algorithm must be set to either "Edmonds" or "LP" @@ -4348,21 +4341,21 @@ def is_factor_critical(self, matching=None, algorithm='Edmonds', solver=None, ve INPUT: - - ``matching`` -- (default: ``None``); a near perfect matching of the + - ``matching`` -- (default: ``None``) a near perfect matching of the graph, that is a matching such that all vertices of the graph but one are incident to an edge of the matching. It can be given using any valid input format of :class:`~sage.graphs.graph.Graph`. If set to ``None``, a matching is computed using the other parameters. - - ``algorithm`` -- string (default: ``Edmonds``); the algorithm to use + - ``algorithm`` -- string (default: ``'Edmonds'``); the algorithm to use to compute a maximum matching of the graph among - - ``"Edmonds"`` selects Edmonds' algorithm as implemented in NetworkX + - ``'Edmonds'`` selects Edmonds' algorithm as implemented in NetworkX - - ``"LP"`` uses a Linear Program formulation of the matching problem + - ``'LP'`` uses a Linear Program formulation of the matching problem - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -4370,7 +4363,7 @@ def is_factor_critical(self, matching=None, algorithm='Edmonds', solver=None, ve :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity: + - ``verbose`` -- integer (default: 0); sets the level of verbosity: set to 0 by default, which means quiet (only useful when ``algorithm == "LP"``) @@ -4535,7 +4528,7 @@ def is_factor_critical(self, matching=None, algorithm='Edmonds', solver=None, ve def has_homomorphism_to(self, H, core=False, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Checks whether there is a homomorphism between two graphs. + Check whether there is a homomorphism between two graphs. A homomorphism from a graph `G` to a graph `H` is a function `\phi:V(G)\mapsto V(H)` such that for any edge `uv \in E(G)` the pair @@ -4548,13 +4541,13 @@ def has_homomorphism_to(self, H, core=False, solver=None, verbose=0, INPUT: - - ``H`` -- the graph to which ``self`` should be sent. + - ``H`` -- the graph to which ``self`` should be sent - ``core`` -- boolean (default: ``False``; whether to minimize the size of the mapping's image (see note below). This is set to ``False`` by default. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -4562,7 +4555,7 @@ def has_homomorphism_to(self, H, core=False, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -4664,7 +4657,7 @@ def fractional_clique_number(self, solver='PPL', verbose=0, INPUT: - - ``solver`` -- (default: ``"PPL"``); specify a Linear Program (LP) + - ``solver`` -- (default: ``'PPL'``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`solve @@ -4674,11 +4667,11 @@ def fractional_clique_number(self, solver='PPL', verbose=0, .. NOTE:: - The default solver used here is ``"PPL"`` which provides exact + The default solver used here is ``'PPL'`` which provides exact results, i.e. a rational number, although this may be slower that using other solvers. - - ``verbose`` -- integer (default: `0`); sets the level of verbosity of + - ``verbose`` -- integer (default: 0); sets the level of verbosity of the LP solver - ``check_components`` -- boolean (default: ``True``); whether the @@ -4714,14 +4707,14 @@ def maximum_average_degree(self, value_only=True, solver=None, verbose=0): INPUT: - - ``value_only`` -- boolean (default: ``True``); + - ``value_only`` -- boolean (default: ``True``) - If ``value_only=True``, only the numerical value of the `MAD` is returned. - Else, the subgraph of `G` realizing the `MAD` is returned. - - ``solver`` -- (default: ``None``); specify a Linear Program (LP) + - ``solver`` -- (default: ``None``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method @@ -4729,7 +4722,7 @@ def maximum_average_degree(self, value_only=True, solver=None, verbose=0): of the class :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. EXAMPLES: @@ -4810,7 +4803,7 @@ def maximum_average_degree(self, value_only=True, solver=None, verbose=0): # Paying attention to numerical error : # The zero values could be something like 0.000000000001 # so I can not write l > 0 - # And the non-zero, though they should be equal to + # And the nonzero, though they should be equal to # 1/(order of the optimal subgraph) may be a bit lower # setting the minimum to 1/(10 * size of the whole graph ) @@ -4841,10 +4834,10 @@ def independent_set_of_representatives(self, family, solver=None, verbose=0, INPUT: - - ``family`` -- A list of lists defining the family `F` (actually, a - Family of subsets of ``G.vertices(sort=False)``). + - ``family`` -- list of lists defining the family `F` (actually, a + Family of subsets of ``G.vertices(sort=False)``) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -4852,7 +4845,7 @@ def independent_set_of_representatives(self, family, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -4968,9 +4961,9 @@ def minor(self, H, solver=None, verbose=0, induced=False, *, integrality_toleran INPUT: - - ``H`` -- The minor to find for in the current graph. + - ``H`` -- the minor to find for in the current graph - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -4978,7 +4971,7 @@ def minor(self, H, solver=None, verbose=0, induced=False, *, integrality_toleran :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -4987,7 +4980,7 @@ def minor(self, H, solver=None, verbose=0, induced=False, *, integrality_toleran - ``induced`` -- boolean (default: ``False``); if ``True``, returns an induced minor isomorphic to `H` if it exists, and raises a - :class:`ValueError` otherwise. + :exc:`ValueError` otherwise. OUTPUT: @@ -5233,7 +5226,7 @@ def centrality_degree(self, v=None): INPUT: - ``v`` -- a vertex (default: ``None``); set to ``None`` (default) to - get a dictionary associating each vertex with its centrality degree. + get a dictionary associating each vertex with its centrality degree .. SEEALSO:: @@ -5287,19 +5280,19 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, INPUT: - ``v`` -- either a single vertex or a list of vertices. If it is not - specified, then it is taken to be all vertices. + specified, then it is taken to be all vertices - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); one of the following algorithms: - ``'BFS'`` -- the computation is done through a BFS centered on each - vertex successively. Works only if ``by_weight==False``. + vertex successively. Works only if ``by_weight==False`` - ``'DHV'`` -- the computation is done using the algorithm proposed in - [Dragan2018]_. Works only if ``self`` has non-negative edge weights + [Dragan2018]_. Works only if ``self`` has nonnegative edge weights and ``v is None`` or ``v`` should contain all vertices of ``self``. For more information see method :func:`sage.graphs.distances_all_pairs.eccentricity` and @@ -5319,7 +5312,7 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, allowed. - ``'Dijkstra_Boost'`` -- the Dijkstra algorithm, implemented in Boost - (works only with positive weights). + (works only with positive weights) - ``'Johnson_Boost'`` -- the Johnson algorithm, implemented in Boost (works also with negative weights, if there is no negative @@ -5327,7 +5320,7 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, vertices of ``self``. - ``'From_Dictionary'`` -- uses the (already computed) distances, that - are provided by input variable ``dist_dict``. + are provided by input variable ``dist_dict`` - ``None`` (default): Sage chooses the best algorithm: ``'From_Dictionary'`` if ``dist_dict`` is not None, ``'BFS'`` for @@ -5343,11 +5336,11 @@ def eccentricity(self, v=None, by_weight=False, algorithm=None, - ``check_weight`` -- boolean (default: ``True``); if ``True``, we check that the ``weight_function`` outputs a number for each edge - - ``dist_dict`` -- a dictionary (default: ``None``); a dict of dicts of + - ``dist_dict`` -- dictionary (default: ``None``); a dict of dicts of distances (used only if ``algorithm=='From_Dictionary'``) - ``with_labels`` -- boolean (default: ``False``); whether to return a - list or a dictionary keyed by vertices. + list or a dictionary keyed by vertices EXAMPLES:: @@ -5536,12 +5529,12 @@ def radius(self, by_weight=False, algorithm='DHV', weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - - ``algorithm`` -- string (default: ``'DHV'``). + - ``algorithm`` -- string (default: ``'DHV'``) - - ``'DHV'`` -- Radius computation is done using the algorithm proposed - in [Dragan2018]_. Works for graph with non-negative edge weights. + - ``'DHV'`` -- radius computation is done using the algorithm proposed + in [Dragan2018]_. Works for graph with nonnegative edge weights For more information see method :func:`sage.graphs.distances_all_pairs.radius_DHV` and :func:`sage.graphs.base.boost_graph.radius_DHV`. @@ -5622,7 +5615,7 @@ def diameter(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); one of the following algorithms: @@ -5644,7 +5637,7 @@ def diameter(self, by_weight=False, algorithm=None, weight_function=None, allowed. - ``'DHV'`` -- diameter computation is done using the algorithm - proposed in [Dragan2018]_. Works only for non-negative edge weights. + proposed in [Dragan2018]_. Works only for nonnegative edge weights For more information see method :func:`sage.graphs.distances_all_pairs.diameter_DHV` and :func:`sage.graphs.base.boost_graph.diameter_DHV`. @@ -5760,7 +5753,7 @@ def center(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); see method :meth:`eccentricity` for the list of available algorithms @@ -5832,7 +5825,7 @@ def periphery(self, by_weight=False, algorithm=None, weight_function=None, INPUT: - ``by_weight`` -- boolean (default: ``False``); if ``True``, edge - weights are taken into account; if False, all edges have weight 1 + weights are taken into account; if ``False``, all edges have weight 1 - ``algorithm`` -- string (default: ``None``); see method :meth:`eccentricity` for the list of available algorithms @@ -5885,7 +5878,7 @@ def distance_graph(self, dist): INPUT: - - ``dist`` -- a nonnegative integer or a list of nonnegative integers; + - ``dist`` -- nonnegative integer or a list of nonnegative integers; specified distance(s) for the connecting vertices. ``Infinity`` may be used here to describe vertex pairs in separate components. @@ -6060,13 +6053,13 @@ def to_directed(self, data_structure=None, sparse=None): INPUT: - - ``data_structure`` -- one of ``"sparse"``, ``"static_sparse"``, or - ``"dense"``. See the documentation of :class:`Graph` or - :class:`DiGraph`. + - ``data_structure`` -- one of ``'sparse'``, ``'static_sparse'``, or + ``'dense'``. See the documentation of :class:`Graph` or + :class:`DiGraph`. - - ``sparse`` -- boolean (default: ``None``); ``sparse=True`` is an - alias for ``data_structure="sparse"``, and ``sparse=False`` is an - alias for ``data_structure="dense"``. + - ``sparse`` -- boolean (default: ``None``); ``sparse=True`` is an + alias for ``data_structure="sparse"``, and ``sparse=False`` is an + alias for ``data_structure="dense"``. EXAMPLES:: @@ -6155,7 +6148,7 @@ def to_undirected(self): return self.copy() @doc_index("Basic methods") - def join(self, other, labels="pairs", immutable=None): + def join(self, other, labels='pairs', immutable=None): r""" Return the join of ``self`` and ``other``. @@ -6288,11 +6281,11 @@ def seidel_switching(self, s, inplace=True): INPUT: - - ``s`` -- a list of vertices of ``self``. + - ``s`` -- list of vertices of ``self`` - ``inplace`` -- boolean (default: ``True``); whether to do the modification inplace, or to return a copy of the graph after - switching. + switching EXAMPLES:: @@ -6321,7 +6314,7 @@ def seidel_switching(self, s, inplace=True): @doc_index("Leftovers") def twograph(self): r""" - Return the two-graph of ``self`` + Return the two-graph of ``self``. Returns the :class:`two-graph ` with the triples @@ -6352,7 +6345,7 @@ def twograph(self): .. SEEALSO:: - :meth:`~sage.combinat.designs.twographs.TwoGraph.descendant` -- - computes the descendant graph of the two-graph of self at a vertex + computes the descendant graph of the two-graph of ``self`` at a vertex - :func:`~sage.combinat.designs.twographs.twograph_descendant` -- ditto, but much faster. @@ -6387,8 +6380,8 @@ def write_to_eps(self, filename, **options): INPUT: - - ``filename`` -- a string - - ``**options`` -- same layout options as :meth:`.layout` + - ``filename`` -- string + - ``**options`` -- same layout options as :meth:`.layout` EXAMPLES:: @@ -6428,9 +6421,9 @@ def topological_minor(self, H, vertices=False, paths=False, solver=None, verbose INPUT: - - ``H`` -- The topological minor to find in the current graph. + - ``H`` -- the topological minor to find in the current graph - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -6438,7 +6431,7 @@ def topological_minor(self, H, vertices=False, paths=False, solver=None, verbose :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -6642,7 +6635,7 @@ def flow_balance(C, v): # Cliques @doc_index("Clique-related methods") - def cliques_maximal(self, algorithm="native"): + def cliques_maximal(self, algorithm='native'): """ Return the list of all maximal cliques. @@ -6652,9 +6645,9 @@ def cliques_maximal(self, algorithm="native"): INPUT: - - ``algorithm`` -- can be set to ``"native"`` (default) to use Sage's + - ``algorithm`` -- can be set to ``'native'`` (default) to use Sage's own implementation, or to ``"NetworkX"`` to use NetworkX' - implementation of the Bron and Kerbosch Algorithm [BK1973]_. + implementation of the Bron and Kerbosch Algorithm [BK1973]_ .. NOTE:: @@ -6699,7 +6692,7 @@ def cliques_maximal(self, algorithm="native"): sage: g = graphs.RandomGNP(20,.7) sage: s1 = Set(map(Set, g.cliques_maximal(algorithm="NetworkX"))) # needs networkx - sage: s2 = Set(map(Set, g.cliques_maximal(algorithm="native"))) + sage: s2 = Set(map(Set, g.cliques_maximal(algorithm='native'))) sage: s1 == s2 # needs networkx True """ @@ -6712,7 +6705,7 @@ def cliques_maximal(self, algorithm="native"): raise ValueError("Algorithm must be equal to 'native' or to 'NetworkX'.") @doc_index("Clique-related methods") - def clique_maximum(self, algorithm="Cliquer", solver=None, verbose=0, + def clique_maximum(self, algorithm='Cliquer', solver=None, verbose=0, *, integrality_tolerance=1e-3): """ Return the vertex set of a maximal order complete subgraph. @@ -6733,7 +6726,7 @@ def clique_maximum(self, algorithm="Cliquer", solver=None, verbose=0, (``_). Note that the MCQD package must be installed. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -6741,7 +6734,7 @@ def clique_maximum(self, algorithm="Cliquer", solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -6773,18 +6766,17 @@ def clique_maximum(self, algorithm="Cliquer", solver=None, verbose=0, Through a Linear Program:: - sage: len(C.clique_maximum(algorithm="MILP")) + sage: len(C.clique_maximum(algorithm='MILP')) 4 TESTS: Wrong algorithm:: - sage: C.clique_maximum(algorithm="BFS") + sage: C.clique_maximum(algorithm='BFS') Traceback (most recent call last): ... NotImplementedError: Only 'MILP', 'Cliquer' and 'mcqd' are supported. - """ self._scream_if_not_simple(allow_multiple_edges=True) if algorithm == "Cliquer": @@ -6798,10 +6790,10 @@ def clique_maximum(self, algorithm="Cliquer", solver=None, verbose=0, raise NotImplementedError("Only 'MILP', 'Cliquer' and 'mcqd' are supported.") @doc_index("Clique-related methods") - def clique_number(self, algorithm="Cliquer", cliques=None, solver=None, verbose=0, + def clique_number(self, algorithm='Cliquer', cliques=None, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Return the order of the largest clique of the graph + Return the order of the largest clique of the graph. This is also called as the clique number. @@ -6832,7 +6824,7 @@ def clique_number(self, algorithm="Cliquer", cliques=None, solver=None, verbose= - ``cliques`` -- an optional list of cliques that can be input if already computed. Ignored unless ``algorithm=="networkx"``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -6840,7 +6832,7 @@ def clique_number(self, algorithm="Cliquer", cliques=None, solver=None, verbose= :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -6881,11 +6873,11 @@ def clique_number(self, algorithm="Cliquer", cliques=None, solver=None, verbose= TESTS:: sage: g = graphs.PetersenGraph() - sage: g.clique_number(algorithm="MILP") # needs sage.numerical.mip + sage: g.clique_number(algorithm='MILP') # needs sage.numerical.mip 2 sage: for i in range(10): # optional - mcqd # needs sage.numerical.mip ....: g = graphs.RandomGNP(15,.5) - ....: if g.clique_number() != g.clique_number(algorithm="mcqd"): + ....: if g.clique_number() != g.clique_number(algorithm='mcqd'): ....: print("This is dead wrong !") """ self._scream_if_not_simple(allow_loops=False) @@ -6917,11 +6909,10 @@ def cliques_number_of(self, vertices=None, cliques=None): INPUT: - - ``vertices`` -- the vertices to inspect (default is entire graph) + - ``vertices`` -- the vertices to inspect (default: entire graph) - ``cliques`` -- list of cliques (if already computed) - EXAMPLES:: sage: C = Graph('DJ{') @@ -7059,7 +7050,7 @@ def cliques_get_clique_bipartite(self, **kwds): return BipartiteGraph(G, check=False) @doc_index("Algorithmically hard stuff") - def independent_set(self, algorithm="Cliquer", value_only=False, reduction_rules=True, + def independent_set(self, algorithm='Cliquer', value_only=False, reduction_rules=True, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return a maximum independent set. @@ -7097,12 +7088,12 @@ def independent_set(self, algorithm="Cliquer", value_only=False, reduction_rules only the size of a maximum independent set is returned. Otherwise, a maximum independent set is returned as a list of vertices. - - ``reduction_rules`` -- (default: ``True``); specify if the reductions + - ``reduction_rules`` -- (default: ``True``) specify if the reductions rules from kernelization must be applied as pre-processing or not. See [ACFLSS04]_ for more details. Note that depending on the instance, it might be faster to disable reduction rules. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7110,7 +7101,7 @@ def independent_set(self, algorithm="Cliquer", value_only=False, reduction_rules :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7134,7 +7125,7 @@ def independent_set(self, algorithm="Cliquer", value_only=False, reduction_rules As a linear program:: sage: C = graphs.PetersenGraph() - sage: len(C.independent_set(algorithm="MILP")) # needs sage.numerical.mip + sage: len(C.independent_set(algorithm='MILP')) # needs sage.numerical.mip 4 .. PLOT:: @@ -7152,11 +7143,11 @@ def independent_set(self, algorithm="Cliquer", value_only=False, reduction_rules return [u for u in self if u not in my_cover] @doc_index("Algorithmically hard stuff") - def vertex_cover(self, algorithm="Cliquer", value_only=False, + def vertex_cover(self, algorithm='Cliquer', value_only=False, reduction_rules=True, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Return a minimum vertex cover of self represented by a set of vertices. + Return a minimum vertex cover of ``self`` represented by a set of vertices. A minimum vertex cover of a graph is a set `S` of vertices such that each edge is incident to at least one element of `S`, and such that `S` @@ -7176,16 +7167,16 @@ def vertex_cover(self, algorithm="Cliquer", value_only=False, INPUT: - - ``algorithm`` -- string (default: ``"Cliquer"``). Indicating which + - ``algorithm`` -- string (default: ``'Cliquer'``); indicating which algorithm to use. It can be one of those values. - - ``"Cliquer"`` will compute a minimum vertex cover using the Cliquer - package. + - ``'Cliquer'`` will compute a minimum vertex cover using the Cliquer + package - - ``"MILP"`` will compute a minimum vertex cover through a mixed - integer linear program. + - ``'MILP'`` will compute a minimum vertex cover through a mixed + integer linear program - - ``"mcqd"`` will use the MCQD solver + - ``'mcqd'`` will use the MCQD solver (``_). Note that the MCQD package must be installed. @@ -7193,12 +7184,12 @@ def vertex_cover(self, algorithm="Cliquer", value_only=False, only the size of a minimum vertex cover is returned. Otherwise, a minimum vertex cover is returned as a list of vertices. - - ``reduction_rules`` -- (default: ``True``); specify if the reductions + - ``reduction_rules`` -- (default: ``True``) specify if the reductions rules from kernelization must be applied as pre-processing or not. See [ACFLSS04]_ for more details. Note that depending on the instance, it might be faster to disable reduction rules. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -7206,7 +7197,7 @@ def vertex_cover(self, algorithm="Cliquer", value_only=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -7231,8 +7222,8 @@ def vertex_cover(self, algorithm="Cliquer", value_only=False, The two algorithms should return the same result:: sage: g = graphs.RandomGNP(10, .5) - sage: vc1 = g.vertex_cover(algorithm="MILP") # needs sage.numerical.mip - sage: vc2 = g.vertex_cover(algorithm="Cliquer") + sage: vc1 = g.vertex_cover(algorithm='MILP') # needs sage.numerical.mip + sage: vc2 = g.vertex_cover(algorithm='Cliquer') sage: len(vc1) == len(vc2) # needs sage.numerical.mip True @@ -7271,12 +7262,12 @@ def vertex_cover(self, algorithm="Cliquer", value_only=False, Testing mcqd:: - sage: graphs.PetersenGraph().vertex_cover(algorithm="mcqd", value_only=True) # optional - mcqd + sage: graphs.PetersenGraph().vertex_cover(algorithm='mcqd', value_only=True) # optional - mcqd 6 Given a wrong algorithm:: - sage: graphs.PetersenGraph().vertex_cover(algorithm="guess") + sage: graphs.PetersenGraph().vertex_cover(algorithm='guess') Traceback (most recent call last): ... ValueError: the algorithm must be "Cliquer", "MILP" or "mcqd" @@ -7528,7 +7519,6 @@ def ear_decomposition(self): Traceback (most recent call last): ... ValueError: ear decomposition is defined for graphs of order at least 3 - """ # Ear decomposition of a graph of order < 3 is []. if self.order() < 3: @@ -7609,7 +7599,7 @@ def traverse(start, pointer): return chains @doc_index("Clique-related methods") - def cliques_vertex_clique_number(self, algorithm="cliquer", vertices=None, + def cliques_vertex_clique_number(self, algorithm='cliquer', vertices=None, cliques=None): """ Return a dictionary of sizes of the largest maximal cliques containing @@ -7624,14 +7614,14 @@ def cliques_vertex_clique_number(self, algorithm="cliquer", vertices=None, INPUT: - - ``algorithm`` -- either ``cliquer`` or ``networkx`` + - ``algorithm`` -- either ``cliquer`` or ``networkx`` - - ``cliquer`` -- This wraps the C program Cliquer [NO2003]_. + - ``cliquer`` -- this wraps the C program Cliquer [NO2003]_ - - ``networkx`` -- This function is based on NetworkX's implementation - of the Bron and Kerbosch Algorithm [BK1973]_. + - ``networkx`` -- this function is based on NetworkX's implementation + of the Bron and Kerbosch Algorithm [BK1973]_ - - ``vertices`` -- the vertices to inspect (default is entire graph). + - ``vertices`` -- the vertices to inspect (default: entire graph). Ignored unless ``algorithm=='networkx'``. - ``cliques`` -- list of cliques (if already computed). Ignored unless @@ -7644,11 +7634,11 @@ def cliques_vertex_clique_number(self, algorithm="cliquer", vertices=None, {0: 2, 1: 4, 2: 4, 3: 4, 4: 4} sage: E = C.cliques_maximal(); E [[0, 4], [1, 2, 3, 4]] - sage: C.cliques_vertex_clique_number(cliques=E, algorithm="networkx") # needs networkx + sage: C.cliques_vertex_clique_number(cliques=E, algorithm='networkx') # needs networkx {0: 2, 1: 4, 2: 4, 3: 4, 4: 4} sage: F = graphs.Grid2dGraph(2,3) - sage: F.cliques_vertex_clique_number(algorithm="networkx") # needs networkx + sage: F.cliques_vertex_clique_number(algorithm='networkx') # needs networkx {(0, 0): 2, (0, 1): 2, (0, 2): 2, (1, 0): 2, (1, 1): 2, (1, 2): 2} sage: F.cliques_vertex_clique_number(vertices=[(0, 1), (1, 2)]) # needs sage.plot {(0, 1): 2, (1, 2): 2} @@ -7687,7 +7677,7 @@ def cliques_containing_vertex(self, vertices=None, cliques=None): INPUT: - - ``vertices`` -- the vertices to inspect (default is entire graph) + - ``vertices`` -- the vertices to inspect (default: entire graph) - ``cliques`` -- list of cliques (if already computed) @@ -7754,10 +7744,10 @@ def cliques_containing_vertex(self, vertices=None, cliques=None): @doc_index("Clique-related methods") def clique_complex(self): """ - Return the clique complex of self. + Return the clique complex of ``self``. - This is the largest simplicial complex on the vertices of self whose - 1-skeleton is self. + This is the largest simplicial complex on the vertices of ``self`` whose + 1-skeleton is ``self``. This is only makes sense for undirected simple graphs. @@ -7776,7 +7766,6 @@ def clique_complex(self): True sage: x==i.clique_complex() True - """ if self.is_directed() or self.has_loops() or self.has_multiple_edges(): raise ValueError("Self must be an undirected simple graph to have a clique complex.") @@ -7788,7 +7777,7 @@ def clique_complex(self): @doc_index("Clique-related methods") def clique_polynomial(self, t=None): r""" - Return the clique polynomial of self. + Return the clique polynomial of ``self``. This is the polynomial where the coefficient of `t^n` is the number of cliques in the graph with `n` vertices. The constant term of the clique @@ -7805,7 +7794,6 @@ def clique_polynomial(self, t=None): sage: g = graphs.CycleGraph(4) sage: g.clique_polynomial() 4*t^2 + 4*t + 1 - """ if t is None: R = PolynomialRing(ZZ, 't') @@ -7864,7 +7852,7 @@ def cores(self, k=None, with_labels=False): INPUT: - - ``k`` -- integer (default: ``None``); + - ``k`` -- integer (default: ``None``) * If ``k = None`` (default), returns the core number for each vertex. @@ -7930,7 +7918,7 @@ def cores(self, k=None, with_labels=False): """ self._scream_if_not_simple(allow_multiple_edges=True) if k is not None and k < 0: - raise ValueError("parameter k must be a non negative integer") + raise ValueError("parameter k must be a nonnegative integer") if not self or not self.size(): if k is not None: return ([], list(self)) if not k else (list(self), []) @@ -8039,9 +8027,9 @@ def modular_decomposition(self, algorithm=None, style='tuple'): - ``style`` -- string (default: ``'tuple'``); specifies the output format: - - ``'tuple'`` -- as nested tuples. + - ``'tuple'`` -- as nested tuples - - ``'tree'`` -- as :class:`~sage.combinat.rooted_tree.LabelledRootedTree`. + - ``'tree'`` -- as :class:`~sage.combinat.rooted_tree.LabelledRootedTree` OUTPUT: @@ -8049,9 +8037,9 @@ def modular_decomposition(self, algorithm=None, style='tuple'): * The type of the current module : - * ``"PARALLEL"`` - * ``"PRIME"`` - * ``"SERIES"`` + * ``'PARALLEL'`` + * ``'PRIME'`` + * ``'SERIES'`` * The list of submodules (as list of pairs ``(type, list)``, recursively...) or the vertex's name if the module is a singleton. @@ -8138,7 +8126,7 @@ def modular_decomposition(self, algorithm=None, style='tuple'): .. SEEALSO:: - - :meth:`is_prime` -- Tests whether a graph is prime. + - :meth:`is_prime` -- tests whether a graph is prime - :class:`~sage.combinat.rooted_tree.LabelledRootedTree`. @@ -8278,7 +8266,6 @@ def is_polyhedral(self) -> bool: sage: G = Graph([[1, 2, 3], [[1, 2], [3, 1], [1, 2], [2, 3]]], multiedges=True) sage: G.is_polyhedral() False - """ return (not self.has_loops() and not self.has_multiple_edges() @@ -8286,7 +8273,7 @@ def is_polyhedral(self) -> bool: and self.is_planar()) @doc_index("Graph properties") - def is_circumscribable(self, solver="ppl", verbose=0): + def is_circumscribable(self, solver='ppl', verbose=0): """ Test whether the graph is the graph of a circumscribed polyhedron. @@ -8299,7 +8286,7 @@ def is_circumscribable(self, solver="ppl", verbose=0): INPUT: - - ``solver`` -- (default: ``"ppl"``); specify a Linear Program (LP) + - ``solver`` -- (default: ``'ppl'``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`solve @@ -8307,7 +8294,7 @@ def is_circumscribable(self, solver="ppl", verbose=0): :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. EXAMPLES:: @@ -8404,7 +8391,7 @@ def is_circumscribable(self, solver="ppl", verbose=0): return solution > 0 @doc_index("Graph properties") - def is_inscribable(self, solver="ppl", verbose=0): + def is_inscribable(self, solver='ppl', verbose=0): """ Test whether the graph is the graph of an inscribed polyhedron. @@ -8415,7 +8402,7 @@ def is_inscribable(self, solver="ppl", verbose=0): INPUT: - - ``solver`` -- (default: ``"ppl"``); specify a Linear Program (LP) + - ``solver`` -- (default: ``'ppl'``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`solve @@ -8423,7 +8410,7 @@ def is_inscribable(self, solver="ppl", verbose=0): :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. EXAMPLES:: @@ -8517,7 +8504,7 @@ def is_prime(self, algorithm=None): def _gomory_hu_tree(self, vertices, algorithm=None): r""" - Return a Gomory-Hu tree associated to self. + Return a Gomory-Hu tree associated to ``self``. This function is the private counterpart of ``gomory_hu_tree()``, with the difference that it has an optional argument needed for recursive @@ -8527,7 +8514,7 @@ def _gomory_hu_tree(self, vertices, algorithm=None): INPUT: - - ``vertices`` -- a set of "real" vertices, as opposed to the fakes one + - ``vertices`` -- set of "real" vertices, as opposed to the fakes one introduced during the computations. This variable is useful for the algorithm and for recursion purposes. @@ -8607,7 +8594,7 @@ def _gomory_hu_tree(self, vertices, algorithm=None): @doc_index("Connectivity, orientations, trees") def gomory_hu_tree(self, algorithm=None): r""" - Return a Gomory-Hu tree of self. + Return a Gomory-Hu tree of ``self``. Given a tree `T` with labeled edges representing capacities, it is very easy to determine the maximum flow between any pair of vertices : @@ -8626,9 +8613,7 @@ def gomory_hu_tree(self, algorithm=None): method. Refer to its documentation for allowed values and default behaviour. - OUTPUT: - - A graph with labeled edges + OUTPUT: a graph with labeled edges EXAMPLES: @@ -8719,7 +8704,7 @@ def two_factor_petersen(self, solver=None, verbose=0, *, integrality_tolerance=1 INPUT: - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -8727,7 +8712,7 @@ def two_factor_petersen(self, solver=None, verbose=0, *, integrality_tolerance=1 :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP @@ -8759,7 +8744,6 @@ def two_factor_petersen(self, solver=None, verbose=0, *, integrality_tolerance=1 sage: cl = g.two_factor_petersen() # needs sage.numerical.mip sage: g.plot(edge_colors={'black':cl[0], 'red':cl[1]}) # needs sage.numerical.mip sage.plot Graphics object consisting of 73 graphics primitives - """ self._scream_if_not_simple() d = self.eulerian_orientation() @@ -8805,9 +8789,7 @@ def kirchhoff_symanzik_polynomial(self, name='t'): - ``name`` -- name of the variables (default: ``'t'``) - OUTPUT: - - - a polynomial with integer coefficients + OUTPUT: a polynomial with integer coefficients ALGORITHM: @@ -9145,28 +9127,28 @@ def rec(G): yield from itertools.product(*[edges[frozenset(e)] for e in m]) @doc_index("Leftovers") - def has_perfect_matching(self, algorithm="Edmonds", solver=None, verbose=0, + def has_perfect_matching(self, algorithm='Edmonds', solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" Return whether this graph has a perfect matching. INPUT: - - ``algorithm`` -- string (default: ``"Edmonds"``) + - ``algorithm`` -- string (default: ``'Edmonds'``) - - ``"Edmonds"`` uses Edmonds' algorithm as implemented in NetworkX to + - ``'Edmonds'`` uses Edmonds' algorithm as implemented in NetworkX to find a matching of maximal cardinality, then check whether this cardinality is half the number of vertices of the graph. - - ``"LP_matching"`` uses a Linear Program to find a matching of + - ``'LP_matching'`` uses a Linear Program to find a matching of maximal cardinality, then check whether this cardinality is half the number of vertices of the graph. - - ``"LP"`` uses a Linear Program formulation of the perfect matching + - ``'LP'`` uses a Linear Program formulation of the perfect matching problem: put a binary variable ``b[e]`` on each edge `e`, and for each vertex `v`, require that the sum of the values of the edges incident to `v` is 1. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -9174,7 +9156,7 @@ def has_perfect_matching(self, algorithm="Edmonds", solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity: + - ``verbose`` -- integer (default: 0); sets the level of verbosity: set to 0 by default, which means quiet (only useful when ``algorithm == "LP_matching"`` or ``algorithm == "LP"``) @@ -9182,9 +9164,7 @@ def has_perfect_matching(self, algorithm="Edmonds", solver=None, verbose=0, solvers over an inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -9194,17 +9174,17 @@ def has_perfect_matching(self, algorithm="Edmonds", solver=None, verbose=0, True sage: graphs.WheelGraph(5).has_perfect_matching() # needs networkx False - sage: graphs.PetersenGraph().has_perfect_matching(algorithm="LP_matching") # needs sage.numerical.mip + sage: graphs.PetersenGraph().has_perfect_matching(algorithm='LP_matching') # needs sage.numerical.mip True - sage: graphs.WheelGraph(6).has_perfect_matching(algorithm="LP_matching") # needs sage.numerical.mip + sage: graphs.WheelGraph(6).has_perfect_matching(algorithm='LP_matching') # needs sage.numerical.mip True - sage: graphs.WheelGraph(5).has_perfect_matching(algorithm="LP_matching") + sage: graphs.WheelGraph(5).has_perfect_matching(algorithm='LP_matching') False - sage: graphs.PetersenGraph().has_perfect_matching(algorithm="LP_matching") # needs sage.numerical.mip + sage: graphs.PetersenGraph().has_perfect_matching(algorithm='LP_matching') # needs sage.numerical.mip True - sage: graphs.WheelGraph(6).has_perfect_matching(algorithm="LP_matching") # needs sage.numerical.mip + sage: graphs.WheelGraph(6).has_perfect_matching(algorithm='LP_matching') # needs sage.numerical.mip True - sage: graphs.WheelGraph(5).has_perfect_matching(algorithm="LP_matching") + sage: graphs.WheelGraph(5).has_perfect_matching(algorithm='LP_matching') False TESTS:: @@ -9227,11 +9207,11 @@ def has_perfect_matching(self, algorithm="Edmonds", solver=None, verbose=0, if algorithm == "Edmonds": return len(self) == 2*self.matching(value_only=True, use_edge_labels=False, - algorithm="Edmonds") + algorithm='Edmonds') elif algorithm == "LP_matching": return len(self) == 2*self.matching(value_only=True, use_edge_labels=False, - algorithm="LP", + algorithm='LP', solver=solver, verbose=verbose, integrality_tolerance=integrality_tolerance) @@ -9557,7 +9537,7 @@ def least_effective_resistance(self, nonedgesonly=True): INPUT: - - ``nonedgesonly`` -- Boolean (default: `True`); if true, assign zero + - ``nonedgesonly`` -- boolean (default: ``True``); if ``True``, assign zero resistance to pairs of adjacent vertices OUTPUT: list @@ -9779,7 +9759,7 @@ def most_common_neighbors(self, nonedgesonly=True): INPUT: - ``nonedgesonly`` -- boolean (default: ``True``); if ``True``, assigns - `0` value to adjacent vertices. + `0` value to adjacent vertices OUTPUT: list of tuples of edge pairs @@ -9859,7 +9839,7 @@ def arboricity(self, certificate=False): INPUT: - ``certificate`` -- boolean (default: ``False``); whether to return - a certificate. + a certificate OUTPUT: @@ -9982,9 +9962,7 @@ def folded_graph(self, check=False): graph is antipodal. If ``check`` is ``True`` and the graph is not antipodal, then return ``False``. - OUTPUT: - - This function returns a new graph and ``self`` is not touched. + OUTPUT: this function returns a new graph and ``self`` is not touched .. NOTE:: @@ -10072,9 +10050,7 @@ def antipodal_graph(self): two vertices are adjacent if their distance in `G` is equal to the diameter of `G`. - OUTPUT: - - A new graph. ``self`` is not touched. + OUTPUT: a new graph. ``self`` is not touched EXAMPLES:: @@ -10128,12 +10104,10 @@ def bipartite_double(self, extended=False): INPUT: - - ``extended`` -- boolean (default: ``False``); Whether to return the + - ``extended`` -- boolean (default: ``False``); whether to return the extended bipartite double, or only the bipartite double (default) - OUTPUT: - - A graph; ``self`` is left untouched. + OUTPUT: a graph; ``self`` is left untouched EXAMPLES:: diff --git a/src/sage/graphs/graph_coloring.pyx b/src/sage/graphs/graph_coloring.pyx index b650822bca7..30fb0cf3a53 100644 --- a/src/sage/graphs/graph_coloring.pyx +++ b/src/sage/graphs/graph_coloring.pyx @@ -149,22 +149,22 @@ def all_graph_colorings(G, n, count_only=False, hex_colors=False, INPUT: - * ``G`` -- a graph + - ``G`` -- a graph - * ``n`` -- a positive integer; the number of colors + - ``n`` -- positive integer; the number of colors - * ``count_only`` -- boolean (default: ``False``); when set to ``True``, it + - ``count_only`` -- boolean (default: ``False``); when set to ``True``, it returns 1 for each coloring and ignores other parameters - * ``hex_colors`` -- boolean (default: ``False``); when set to ``False``, + - ``hex_colors`` -- boolean (default: ``False``); when set to ``False``, colors are labeled [0, 1, ..., `n - 1`], otherwise the RGB Hex labeling is used - * ``vertex_color_dict`` -- boolean (default: ``False``); when set to + - ``vertex_color_dict`` -- boolean (default: ``False``); when set to ``True``, it returns a dictionary ``{vertex: color}``, otherwise it returns a dictionary ``{color: [list of vertices]}`` - * ``color_classes`` -- boolean (default: ``False``); when set to ``True``, + - ``color_classes`` -- boolean (default: ``False``); when set to ``True``, the method returns only a list of the color classes and ignores parameters ``hex_colors`` and ``vertex_color_dict`` @@ -234,7 +234,7 @@ def all_graph_colorings(G, n, count_only=False, hex_colors=False, ....: print(C) Traceback (most recent call last): ... - ValueError: n must be non-negative + ValueError: n must be nonnegative sage: G = Graph({0: [1], 1: [2]}) sage: for c in all_graph_colorings(G, 2, vertex_color_dict=True): ....: print(c) @@ -267,7 +267,7 @@ def all_graph_colorings(G, n, count_only=False, hex_colors=False, if not n or n > G.order(): return if n < 0: - raise ValueError("n must be non-negative") + raise ValueError("n must be nonnegative") cdef list V = list(G) @@ -338,7 +338,7 @@ cpdef first_coloring(G, n=0, hex_colors=False): INPUT: - - ``n`` -- integer (default: 0); the minimal number of colors to try + - ``n`` -- integer (default: 0); the minimal number of colors to try - ``hex_colors`` -- boolean (default: ``False``); when set to ``True``, the partition returned is a dictionary whose keys are colors and whose values @@ -368,13 +368,13 @@ cpdef first_coloring(G, n=0, hex_colors=False): cpdef number_of_n_colorings(G, n): r""" - Compute the number of `n`-colorings of a graph + Compute the number of `n`-colorings of a graph. INPUT: - ``G`` -- a graph - - ``n`` -- a positive integer; the number of colors + - ``n`` -- positive integer; the number of colors EXAMPLES:: @@ -467,7 +467,7 @@ def vertex_coloring(g, k=None, value_only=False, hex_colors=False, solver=None, INPUT: - - ``g`` -- a graph. + - ``g`` -- a graph - ``k`` -- integer (default: ``None``); tests whether the graph is `k`-colorable. The function returns a partition of the vertex set in `k` @@ -484,7 +484,7 @@ def vertex_coloring(g, k=None, value_only=False, hex_colors=False, solver=None, partition returned is a dictionary whose keys are colors and whose values are the color classes (ideal for plotting). - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -492,7 +492,7 @@ def vertex_coloring(g, k=None, value_only=False, hex_colors=False, solver=None, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -750,7 +750,7 @@ def fractional_chromatic_number(G, solver='PPL', verbose=0, - ``G`` -- a graph - - ``solver`` -- (default: ``"PPL"``); specify a Linear Program (LP) solver + - ``solver`` -- (default: ``'PPL'``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`solve ` of the @@ -759,11 +759,11 @@ def fractional_chromatic_number(G, solver='PPL', verbose=0, .. NOTE:: - The default solver used here is ``"PPL"`` which provides exact + The default solver used here is ``'PPL'`` which provides exact results, i.e. a rational number, although this may be slower that using other solvers. - - ``verbose`` -- integer (default: `0`); sets the level of verbosity of + - ``verbose`` -- integer (default: 0); sets the level of verbosity of the LP solver - ``check_components`` -- boolean (default: ``True``); whether the method is @@ -828,7 +828,7 @@ def fractional_chromatic_number(G, solver='PPL', verbose=0, return obj -def fractional_chromatic_index(G, solver="PPL", verbose_constraints=False, verbose=0): +def fractional_chromatic_index(G, solver='PPL', verbose_constraints=False, verbose=0): r""" Return the fractional chromatic index of the graph. @@ -861,7 +861,7 @@ def fractional_chromatic_index(G, solver="PPL", verbose_constraints=False, verbo - ``G`` -- a graph - - ``solver`` -- (default: ``"PPL"``); specify a Linear Program (LP) solver + - ``solver`` -- (default: ``'PPL'``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`solve ` of the @@ -870,7 +870,7 @@ def fractional_chromatic_index(G, solver="PPL", verbose_constraints=False, verbo .. NOTE:: - The default solver used here is ``"PPL"`` which provides exact + The default solver used here is ``'PPL'`` which provides exact results, i.e. a rational number, although this may be slower that using other solvers. Be aware that this method may loop endlessly when using some non exact solvers as reported in :issue:`23658` and @@ -879,7 +879,7 @@ def fractional_chromatic_index(G, solver="PPL", verbose_constraints=False, verbo - ``verbose_constraints`` -- boolean (default: ``False``); whether to display which constraints are being generated - - ``verbose`` -- integer (default: `0`); sets the level of verbosity of the + - ``verbose`` -- integer (default: 0); sets the level of verbosity of the LP solver EXAMPLES: @@ -1003,7 +1003,7 @@ def grundy_coloring(g, k, value_only=True, solver=None, verbose=0, coloring)`` is returned, where ``coloring`` is a dictionary associating its color (integer) to each vertex of the graph. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1011,7 +1011,7 @@ def grundy_coloring(g, k, value_only=True, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -1157,7 +1157,7 @@ def b_coloring(g, k, value_only=True, solver=None, verbose=0, coloring)`` is returned, where ``coloring`` is a dictionary associating its color (integer) to each vertex of the graph. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1165,7 +1165,7 @@ def b_coloring(g, k, value_only=True, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -1302,7 +1302,7 @@ def edge_coloring(g, value_only=False, vizing=False, hex_colors=False, solver=No INPUT: - - ``g`` -- a graph. + - ``g`` -- a graph - ``value_only`` -- boolean (default: ``False``): @@ -1328,7 +1328,7 @@ def edge_coloring(g, value_only=False, vizing=False, hex_colors=False, solver=No partition returned is a dictionary whose keys are colors and whose values are the color classes (ideal for plotting) - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1336,7 +1336,7 @@ def edge_coloring(g, value_only=False, vizing=False, hex_colors=False, solver=No :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -1542,9 +1542,7 @@ def _vizing_edge_coloring(g): - ``g`` -- a graph - OUTPUT: - - a partition of the edge set into at most `\Delta + 1` matchings + OUTPUT: a partition of the edge set into at most `\Delta + 1` matchings .. SEEALSO:: @@ -1807,7 +1805,7 @@ def linear_arboricity(g, plus_one=None, hex_colors=False, value_only=False, - If ``value_only = False``, returns the color classes according to the value of ``hex_colors`` - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1815,7 +1813,7 @@ def linear_arboricity(g, plus_one=None, hex_colors=False, value_only=False, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -2005,7 +2003,7 @@ def acyclic_edge_coloring(g, hex_colors=False, value_only=False, k=0, - If ``value_only = False``, returns the color classes according to the value of ``hex_colors`` - - ``k`` -- integer; the number of colors to use. + - ``k`` -- integer; the number of colors to use - If ``k > 0``, computes an acyclic edge coloring using `k` colors. @@ -2015,7 +2013,7 @@ def acyclic_edge_coloring(g, hex_colors=False, value_only=False, k=0, - If ``k = None``, computes a decomposition using the least possible number of colors. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -2023,7 +2021,7 @@ def acyclic_edge_coloring(g, hex_colors=False, value_only=False, k=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers diff --git a/src/sage/graphs/graph_database.py b/src/sage/graphs/graph_database.py index 653201c3d10..8549b208af6 100644 --- a/src/sage/graphs/graph_database.py +++ b/src/sage/graphs/graph_database.py @@ -99,7 +99,7 @@ def data_to_degseq(data, graph6=None): """ degseq = Integer(data).digits(10) if not degseq: - # compute number of 0's in list from graph6 string + # compute number of 0s in list from graph6 string from sage.graphs.generic_graph_pyx import length_and_string_from_graph6 return length_and_string_from_graph6(str(graph6))[0] * [0] return degseq @@ -266,12 +266,12 @@ def __init__(self, query_string, database=None, param_tuple=None): INPUT: - - ``query_string`` -- a string representing the SQL query + - ``query_string`` -- string representing the SQL query - - ``database`` -- (default: ``None``); the :class:`~GraphDatabase` + - ``database`` -- (default: ``None``) the :class:`~GraphDatabase` instance to query (if ``None`` then a new instance is created) - - ``param_tuple`` -- a tuple of strings (default: ``None``); what to + - ``param_tuple`` -- tuple of strings (default: ``None``); what to replace question marks in ``query_string`` with (optional, but a good idea) @@ -343,8 +343,8 @@ class located in :mod:`sage.databases.sql_db` to make the query - ``graph_db`` -- :class:`~GraphDatabase` (default: ``None``); instance to apply the query to (If ``None``, then a new instance is created) - - ``query_dict`` -- dict (default: ``None``); a dictionary specifying - the query itself. Format is: ``{'table_name': 'tblname', + - ``query_dict`` -- dictionary (default: ``None``); a dictionary + specifying the query itself. Format is: ``{'table_name': 'tblname', 'display_cols': ['col1', 'col2'], 'expression': [col, operator, value]}``. If not ``None``, ``query_dict`` will take precedence over all other arguments. @@ -728,7 +728,7 @@ class GraphDatabase(SQLDatabase): def __init__(self): """ - Graph Database + Graph Database. This class interfaces with the ``sqlite`` database ``graphs.db``. It is an immutable database that inherits from diff --git a/src/sage/graphs/graph_decompositions/bandwidth.pyx b/src/sage/graphs/graph_decompositions/bandwidth.pyx index 61bacd2daf5..a491bb50acd 100644 --- a/src/sage/graphs/graph_decompositions/bandwidth.pyx +++ b/src/sage/graphs/graph_decompositions/bandwidth.pyx @@ -6,7 +6,7 @@ Definition ---------- The bandwidth `bw(M)` of a matrix `M` is the smallest integer `k` such that all -non-zero entries of `M` are at distance `k` from the diagonal. The bandwidth +nonzero entries of `M` are at distance `k` from the diagonal. The bandwidth `bw(G)` of an undirected graph `G` is the minimum bandwidth of the adjacency matrix of `G`, over all possible relabellings of its vertices. @@ -209,7 +209,6 @@ def bandwidth(G, k=None): Traceback (most recent call last): ... ValueError: this method only works on unweighted graphs - """ if G.is_directed(): raise ValueError("this method only works on undirected graphs") diff --git a/src/sage/graphs/graph_decompositions/cutwidth.pyx b/src/sage/graphs/graph_decompositions/cutwidth.pyx index 8aa99a242c9..7929eac7a86 100644 --- a/src/sage/graphs/graph_decompositions/cutwidth.pyx +++ b/src/sage/graphs/graph_decompositions/cutwidth.pyx @@ -108,15 +108,15 @@ optimal layout for the cutwidth of `G`. **Variables:** -- `x_v^k` -- Variable set to 1 if vertex `v` is placed in the ordering at - position `i` with `i\leq k`, and 0 otherwise. +- `x_v^k` -- variable set to 1 if vertex `v` is placed in the ordering at + position `i` with `i\leq k`, and 0 otherwise -- `y_{u,v}^{k}` -- Variable set to 1 if one of `u` or `v` is at a position +- `y_{u,v}^{k}` -- variable set to 1 if one of `u` or `v` is at a position `i\leq k` and the other is at a position `j>k`, and so we have to count edge `uv` at position `k`. Otherwise, `y_{u,v}^{k}=0`. The value of `y_{u,v}^{k}` is a xor of the values of `x_u^k` and `x_v^k`. -- `z` -- Objective value to minimize. It is equal to the maximum over all +- `z` -- objective value to minimize. It is equal to the maximum over all position `k` of the number of edges with one extremity at position at most `k` and the other at position strictly more than `k`, that is `\sum_{uv\in E}y_{u,v}^{k}`. @@ -263,7 +263,7 @@ def width_of_cut_decomposition(G, L): # Front end method for cutwidth ################################################################################ -def cutwidth(G, algorithm="exponential", cut_off=0, solver=None, verbose=False, +def cutwidth(G, algorithm='exponential', cut_off=0, solver=None, verbose=False, *, integrality_tolerance=1e-3): r""" Return the cutwidth of the graph and the corresponding vertex ordering. @@ -272,21 +272,21 @@ def cutwidth(G, algorithm="exponential", cut_off=0, solver=None, verbose=False, - ``G`` -- a Graph or a DiGraph - - ``algorithm`` -- string (default: ``"exponential"``); algorithm to use + - ``algorithm`` -- string (default: ``'exponential'``); algorithm to use among: - - ``exponential`` -- Use an exponential time and space algorithm based on + - ``exponential`` -- use an exponential time and space algorithm based on dynamic programming. This algorithm only works on graphs with strictly less than 32 vertices. - - ``MILP`` -- Use a mixed integer linear programming formulation. This - algorithm has no size restriction but could take a very long time. + - ``MILP`` -- use a mixed integer linear programming formulation. This + algorithm has no size restriction but could take a very long time - ``cut_off`` -- integer (default: 0); used to stop the search as soon as a solution with width at most ``cut_off`` is found, if any. If this bound cannot be reached, the best solution found is returned. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -295,7 +295,7 @@ def cutwidth(G, algorithm="exponential", cut_off=0, solver=None, verbose=False, `. - ``verbose`` -- boolean (default: ``False``); whether to display - information on the computations. + information on the computations - ``integrality_tolerance`` -- float; parameter for use with MILP solvers over an inexact base ring; see @@ -337,15 +337,15 @@ def cutwidth(G, algorithm="exponential", cut_off=0, solver=None, verbose=False, sage: from sage.graphs.graph_decompositions.cutwidth import cutwidth sage: for i in range(2): # long time # needs sage.numerical.mip ....: G = graphs.RandomGNP(7, 0.3) - ....: ve, le = cutwidth(G, algorithm="exponential") - ....: vm, lm = cutwidth(G, algorithm="MILP", solver='GLPK') + ....: ve, le = cutwidth(G, algorithm='exponential') + ....: vm, lm = cutwidth(G, algorithm='MILP', solver='GLPK') ....: if ve != vm: ....: raise ValueError("Something goes wrong!") Given a wrong algorithm:: sage: from sage.graphs.graph_decompositions.cutwidth import cutwidth - sage: cutwidth(graphs.PathGraph(2), algorithm="SuperFast") + sage: cutwidth(graphs.PathGraph(2), algorithm='SuperFast') Traceback (most recent call last): ... ValueError: algorithm "SuperFast" has not been implemented yet, please contribute @@ -370,9 +370,9 @@ def cutwidth(G, algorithm="exponential", cut_off=0, solver=None, verbose=False, sage: from sage.graphs.graph_decompositions.cutwidth import cutwidth sage: G = Graph([(0, 1)]) - sage: cutwidth(G, algorithm="exponential") + sage: cutwidth(G, algorithm='exponential') (1, [0, 1]) - sage: cutwidth(G, algorithm="MILP", solver='GLPK') # needs sage.numerical.mip + sage: cutwidth(G, algorithm='MILP', solver='GLPK') # needs sage.numerical.mip (1, [0, 1]) Cutwidth of a disconnected graph:: @@ -380,9 +380,9 @@ def cutwidth(G, algorithm="exponential", cut_off=0, solver=None, verbose=False, sage: from sage.graphs.graph_decompositions.cutwidth import cutwidth sage: G = Graph(5) sage: G.add_edge(2, 3) - sage: cutwidth(G, algorithm="exponential") + sage: cutwidth(G, algorithm='exponential') (1, [2, 3, 0, 1, 4]) - sage: cutwidth(G, algorithm="MILP", solver='GLPK') # needs sage.numerical.mip + sage: cutwidth(G, algorithm='MILP', solver='GLPK') # needs sage.numerical.mip (1, [2, 3, 0, 1, 4]) """ from sage.graphs.graph import Graph @@ -494,7 +494,6 @@ def cutwidth_dyn(G, lower_bound=0): Traceback (most recent call last): ... ValueError: the specified lower bound must be an integer - """ from sage.graphs.graph import Graph if not isinstance(G, Graph): @@ -617,7 +616,7 @@ def cutwidth_MILP(G, lower_bound=0, solver=None, verbose=0, optimal. If the given bound is too high, the algorithm might not be able to find a feasible solution. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -625,7 +624,7 @@ def cutwidth_MILP(G, lower_bound=0, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers diff --git a/src/sage/graphs/graph_decompositions/fast_digraph.pyx b/src/sage/graphs/graph_decompositions/fast_digraph.pyx index 2d28ccf4d05..a661509d23d 100644 --- a/src/sage/graphs/graph_decompositions/fast_digraph.pyx +++ b/src/sage/graphs/graph_decompositions/fast_digraph.pyx @@ -117,7 +117,7 @@ cdef inline int compute_out_neighborhood_cardinality(FastDigraph g, int S) noexc - ``g`` -- a FastDigraph - - ``S`` -- an integer describing the set + - ``S`` -- integer describing the set EXAMPLES:: diff --git a/src/sage/graphs/graph_decompositions/graph_products.pyx b/src/sage/graphs/graph_decompositions/graph_products.pyx index 98bfb6ec0f5..187f6a7ec09 100644 --- a/src/sage/graphs/graph_decompositions/graph_products.pyx +++ b/src/sage/graphs/graph_decompositions/graph_products.pyx @@ -153,7 +153,7 @@ def is_cartesian_product(g, certificate=False, relabeling=False): - :meth:`sage.graphs.generic_graph.GenericGraph.cartesian_product` - :mod:`~sage.graphs.graph_decompositions.graph_products` -- a module on - graph products. + graph products .. NOTE:: diff --git a/src/sage/graphs/graph_decompositions/modular_decomposition.py b/src/sage/graphs/graph_decompositions/modular_decomposition.py index 03e9231bd65..001f127d63d 100644 --- a/src/sage/graphs/graph_decompositions/modular_decomposition.py +++ b/src/sage/graphs/graph_decompositions/modular_decomposition.py @@ -160,14 +160,14 @@ def __init__(self, node_type): def set_node_split(self, node_split): """ - Add node_split to the node split of self. + Add node_split to the node split of ``self``. ``LEFT_SPLIT`` and ``RIGHT_SPLIT`` can exist together in ``self`` as ``BOTH_SPLIT``. INPUT: - - ``node_split`` -- node_split to be added to self + - ``node_split`` -- ``node_split`` to be added to ``self`` EXAMPLES:: @@ -282,11 +282,9 @@ def __eq__(self, other): def create_prime_node(): """ - Return a prime node with no children + Return a prime node with no children. - OUTPUT: - - A node object with node_type set as NodeType.PRIME + OUTPUT: a node object with ``node_type`` set as ``NodeType.PRIME`` EXAMPLES:: @@ -300,11 +298,9 @@ def create_prime_node(): def create_parallel_node(): """ - Return a parallel node with no children - - OUTPUT: + Return a parallel node with no children. - A node object with node_type set as NodeType.PARALLEL + OUTPUT: a node object with ``node_type`` set as ``NodeType.PARALLEL`` EXAMPLES:: @@ -318,11 +314,9 @@ def create_parallel_node(): def create_series_node(): """ - Return a series node with no children + Return a series node with no children. - OUTPUT: - - A node object with node_type set as NodeType.SERIES + OUTPUT: a node object with ``node_type`` set as ``NodeType.SERIES`` EXAMPLES:: @@ -336,15 +330,14 @@ def create_series_node(): def create_normal_node(vertex): """ - Return a normal node with no children + Return a normal node with no children. INPUT: - ``vertex`` -- vertex number - OUTPUT: - - A node object representing the vertex with node_type set as NodeType.NORMAL + OUTPUT: a node object representing the vertex with ``node_type`` set as + ``NodeType.NORMAL`` EXAMPLES:: @@ -360,7 +353,7 @@ def create_normal_node(vertex): def print_md_tree(root): """ - Print the modular decomposition tree + Print the modular decomposition tree. INPUT: @@ -387,7 +380,7 @@ def print_md_tree(root): def recursive_print_md_tree(root, level): """ - Print the modular decomposition tree at root + Print the modular decomposition tree at root. INPUT: @@ -461,7 +454,7 @@ def gamma_classes(graph): def habib_maurer_algorithm(graph, g_classes=None): """ - Compute the modular decomposition by the algorithm of Habib and Maurer + Compute the modular decomposition by the algorithm of Habib and Maurer. Compute the modular decomposition of the given graph by the algorithm of Habib and Maurer [HM1979]_ . If the graph is disconnected or its complement @@ -483,9 +476,7 @@ def habib_maurer_algorithm(graph, g_classes=None): are the gamma classes of the graph, and whose keys are a frozenset of the vertices corresponding to the class. Used internally. - OUTPUT: - - The modular decomposition tree of the graph. + OUTPUT: the modular decomposition tree of the graph EXAMPLES: @@ -671,9 +662,7 @@ def test_modular_decomposition(tree_root, graph): - ``graph`` -- graph whose modular decomposition tree needs to be tested - OUTPUT: - - ``True`` if input tree is a modular decomposition else ``False`` + OUTPUT: ``True`` if input tree is a modular decomposition else ``False`` EXAMPLES:: @@ -755,7 +744,7 @@ def test_maximal_modules(tree_root, graph): def get_vertices(component_root): """ - Compute the list of vertices in the (co)component + Compute the list of vertices in the (co)component. INPUT: @@ -906,7 +895,7 @@ def form_module(index, other_index, tree_root, graph): # Function implemented for testing def test_module(module, graph): """ - Test whether input module is actually a module + Test whether input module is actually a module. INPUT: @@ -914,9 +903,7 @@ def test_module(module, graph): - ``graph`` -- input sage graph which contains the module - OUTPUT: - - ``True`` if input module is a module by definition else ``False`` + OUTPUT: ``True`` if input module is a module by definition else ``False`` EXAMPLES:: @@ -1073,9 +1060,7 @@ def nested_tuple_to_tree(nest): - ``nest`` -- a nested tuple of the form returned by :meth:`tree_to_nested_tuple` - OUTPUT: - - The root node of a modular decomposition tree. + OUTPUT: the root node of a modular decomposition tree EXAMPLES:: @@ -1146,7 +1131,7 @@ def node_id(root): def relabel_tree(root, perm): r""" - Relabel the leaves of a tree according to a dictionary + Relabel the leaves of a tree according to a dictionary. INPUT: @@ -1225,10 +1210,10 @@ def test_gamma_modules(trials, vertices, prob, verbose=False): - ``vertices`` -- the size of the graph to use - - ``prob`` -- the probability that any given edge is in the graph. - See :meth:`~sage.graphs.generators.random.RandomGNP` for more details. + - ``prob`` -- the probability that any given edge is in the graph + See :meth:`~sage.graphs.generators.random.RandomGNP` for more details - - ``verbose`` -- print information on each trial. + - ``verbose`` -- print information on each trial EXAMPLES:: @@ -1289,10 +1274,10 @@ def random_md_tree(max_depth, max_fan_out, leaf_probability): INPUT: - - ``max_depth`` -- the maximum depth of the tree. + - ``max_depth`` -- the maximum depth of the tree - ``max_fan_out`` -- the maximum number of children a node can have - (must be >=4 as a prime node must have at least 4 vertices). + (must be >=4 as a prime node must have at least 4 vertices) - ``leaf_probability`` -- the probability that a subtree is a leaf diff --git a/src/sage/graphs/graph_decompositions/tdlib.pyx b/src/sage/graphs/graph_decompositions/tdlib.pyx index 9940aa84883..847f6f49116 100644 --- a/src/sage/graphs/graph_decompositions/tdlib.pyx +++ b/src/sage/graphs/graph_decompositions/tdlib.pyx @@ -140,7 +140,6 @@ def treedecomposition_exact(G, lb=-1): sage: T = tdlib.treedecomposition_exact(G) sage: G = graphs.PetersenGraph() sage: T = tdlib.treedecomposition_exact(G) - """ cdef vector[unsigned int] V_G, E_G, E_T cdef vector[vector[int]] V_T @@ -172,9 +171,7 @@ def get_width(T): - ``T`` -- a tree decomposition - OUTPUT: - - - The width of ``T`` + OUTPUT: the width of ``T`` EXAMPLES:: diff --git a/src/sage/graphs/graph_decompositions/tree_decomposition.pyx b/src/sage/graphs/graph_decompositions/tree_decomposition.pyx index 8382cb85cdf..8ed9ee9d224 100644 --- a/src/sage/graphs/graph_decompositions/tree_decomposition.pyx +++ b/src/sage/graphs/graph_decompositions/tree_decomposition.pyx @@ -450,14 +450,14 @@ def treewidth(g, k=None, kmin=None, certificate=False, algorithm=None, nice=Fals when ``k`` is not ``None`` or when ``algorithm == 'tdlib'``. - ``certificate`` -- boolean (default: ``False``); whether to return the - tree-decomposition itself. + tree-decomposition itself - - ``algorithm`` -- whether to use ``"sage"`` or ``"tdlib"`` (requires the + - ``algorithm`` -- whether to use ``'sage'`` or ``'tdlib'`` (requires the installation of the :ref:`spkg_sagemath_tdlib` package). The default behaviour is to use 'tdlib' if it is available, and Sage's own algorithm when it is not. - ``nice`` -- boolean (default: ``False``); whether or not to return the - nice tree decomposition, provided ``certificate`` is ``True``. + nice tree decomposition, provided ``certificate`` is ``True`` OUTPUT: @@ -826,9 +826,7 @@ def make_nice_tree_decomposition(graph, tree_decomp): - ``tree_decomp`` -- a tree decomposition - OUTPUT: - - A nice tree decomposition. + OUTPUT: a nice tree decomposition .. WARNING:: @@ -1081,9 +1079,7 @@ def label_nice_tree_decomposition(nice_TD, root, directed=False): tree decomposition as a directed graph rooted at vertex ``root`` or as an undirected graph - OUTPUT: - - A nice tree decomposition with nodes labelled. + OUTPUT: a nice tree decomposition with nodes labelled EXAMPLES:: @@ -1361,7 +1357,7 @@ cdef class TreelengthConnected: ... ValueError: the graph is not connected - The parameter `k` must be non-negative:: + The parameter `k` must be nonnegative:: sage: TreelengthConnected(Graph(1), k=-1) Traceback (most recent call last): @@ -1439,11 +1435,11 @@ cdef class TreelengthConnected: if self.n <= 1 or (self.k_is_defined and self.n <= k): if certificate: if self.n: - self.tree = Graph({Set(G): []}, format="dict_of_lists", name=self.name) + self.tree = Graph({Set(G): []}, format='dict_of_lists', name=self.name) else: self.tree = Graph(name=self.name) self.length = 0 if self.n <= 1 else G.diameter(algorithm='DHV') - self.leq_k = True # We know that k is non negative + self.leq_k = True # We know that k is nonnegative return if self.k_is_defined and not k: @@ -1453,7 +1449,7 @@ cdef class TreelengthConnected: if G.is_clique(): if certificate: - self.tree = Graph({Set(G): []}, format="dict_of_lists", name=self.name) + self.tree = Graph({Set(G): []}, format='dict_of_lists', name=self.name) self.length = 1 self.leq_k = True return @@ -1485,7 +1481,7 @@ cdef class TreelengthConnected: if self.k_is_defined and k >= self.diameter: # All vertices fit in one bag if certificate: - self.tree = Graph({Set(G): []}, format="dict_of_lists", name=self.name) + self.tree = Graph({Set(G): []}, format='dict_of_lists', name=self.name) self.length = self.diameter self.leq_k = True return @@ -1508,7 +1504,7 @@ cdef class TreelengthConnected: def __dealloc__(self): r""" - Destroy the object + Destroy the object. TESTS:: @@ -1650,7 +1646,7 @@ cdef class TreelengthConnected: from sage.graphs.graph import Graph T = Graph([(good_label(x), good_label(y)) for x, y in TD if x != y], - format="list_of_edges") + format='list_of_edges') self.tree = reduced_tree_decomposition(T) self.tree.name(self.name) return True @@ -1900,7 +1896,7 @@ def treelength(G, k=None, certificate=False): answer = 0 if k is None else True if certificate: if G: - answer = answer, Graph({Set(G): []}, format="dict_of_lists", name=name) + answer = answer, Graph({Set(G): []}, format='dict_of_lists', name=name) else: answer = answer, Graph(name=name) return answer @@ -1947,7 +1943,7 @@ def treelength(G, k=None, certificate=False): ga = G.subgraph(atom) if ga.is_clique(): if certificate: - result.append(Graph({Set(atom): []}, format="dict_of_lists")) + result.append(Graph({Set(atom): []}, format='dict_of_lists')) continue gc, certif = ga.canonical_label(certificate=True) diff --git a/src/sage/graphs/graph_decompositions/vertex_separation.pyx b/src/sage/graphs/graph_decompositions/vertex_separation.pyx index 2b45805348e..e83c05d2c0e 100644 --- a/src/sage/graphs/graph_decompositions/vertex_separation.pyx +++ b/src/sage/graphs/graph_decompositions/vertex_separation.pyx @@ -136,16 +136,16 @@ sets such that an ordering `v_1, ..., v_n` of the vertices correspond to **Variables:** -- `y_v^t` -- Variable set to 1 if `v\in S_t`, and 0 otherwise. The order of +- `y_v^t` -- variable set to 1 if `v\in S_t`, and 0 otherwise. The order of `v` in the layout is the smallest `t` such that `y_v^t==1`. -- `u_v^t` -- Variable set to 1 if `v\not \in S_t` and `v` has an in-neighbor in +- `u_v^t` -- variable set to 1 if `v\not \in S_t` and `v` has an in-neighbor in `S_t`. It is set to 0 otherwise. -- `x_v^t` -- Variable set to 1 if either `v\in S_t` or if `v` has an in-neighbor +- `x_v^t` -- variable set to 1 if either `v\in S_t` or if `v` has an in-neighbor in `S_t`. It is set to 0 otherwise. -- `z` -- Objective value to minimize. It is equal to the maximum over all step +- `z` -- objective value to minimize. It is equal to the maximum over all step `t` of the number of vertices such that `u_v^t==1`. **MILP formulation:** @@ -294,7 +294,6 @@ def lower_bound(G): This method runs in exponential time but has no memory constraint. - EXAMPLES: On a circuit:: @@ -321,7 +320,6 @@ def lower_bound(G): Traceback (most recent call last): ... ValueError: the (di)graph can have at most 31 vertices - """ from sage.graphs.graph import Graph from sage.graphs.digraph import DiGraph @@ -369,7 +367,7 @@ def lower_bound(G): def linear_ordering_to_path_decomposition(G, L): """ - Return the path decomposition encoded in the ordering L + Return the path decomposition encoded in the ordering L. INPUT: @@ -377,9 +375,7 @@ def linear_ordering_to_path_decomposition(G, L): - ``L`` -- a linear ordering for G - OUTPUT: - - A path graph whose vertices are the bags of the path decomposition. + OUTPUT: a path graph whose vertices are the bags of the path decomposition EXAMPLES: @@ -471,10 +467,10 @@ def linear_ordering_to_path_decomposition(G, L): # Front end methods for path decomposition and vertex separation # ################################################################## -def pathwidth(self, k=None, certificate=False, algorithm="BAB", verbose=False, +def pathwidth(self, k=None, certificate=False, algorithm='BAB', verbose=False, max_prefix_length=20, max_prefix_number=10**6, *, solver=None): r""" - Compute the pathwidth of ``self`` (and provides a decomposition) + Compute the pathwidth of ``self`` (and provides a decomposition). INPUT: @@ -486,19 +482,19 @@ def pathwidth(self, k=None, certificate=False, algorithm="BAB", verbose=False, - ``certificate`` -- boolean (default: ``False``); whether to return the path-decomposition itself - - ``algorithm`` -- string (default: ``"BAB"``); algorithm to use among: + - ``algorithm`` -- string (default: ``'BAB'``); algorithm to use among: - - ``"BAB"`` -- Use a branch-and-bound algorithm. This algorithm has no + - ``'BAB'`` -- use a branch-and-bound algorithm. This algorithm has no size restriction but could take a very long time on large graphs. It can also be used to test is the input graph has pathwidth `\leq k`, in which cas it will return the first found solution with width `\leq k` is ``certificate==True``. - - ``exponential`` -- Use an exponential time and space algorithm. This - algorithm only works of graphs on less than 32 vertices. + - ``exponential`` -- use an exponential time and space algorithm. This + algorithm only works of graphs on less than 32 vertices - - ``MILP`` -- Use a mixed integer linear programming formulation. This - algorithm has no size restriction but could take a very long time. + - ``MILP`` -- use a mixed integer linear programming formulation. This + algorithm has no size restriction but could take a very long time - ``verbose`` -- boolean (default: ``False``); whether to display information on the computations @@ -511,7 +507,7 @@ def pathwidth(self, k=None, certificate=False, algorithm="BAB", verbose=False, number of stored prefixes used to prevent using too much memory. This parameter is used only when ``algorithm=="BAB"``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -568,7 +564,7 @@ def pathwidth(self, k=None, certificate=False, algorithm="BAB", verbose=False, Given a wrong algorithm:: sage: from sage.graphs.graph_decompositions.vertex_separation import pathwidth - sage: pathwidth(Graph(), algorithm="SuperFast") + sage: pathwidth(Graph(), algorithm='SuperFast') Traceback (most recent call last): ... ValueError: algorithm "SuperFast" has not been implemented yet, please contribute @@ -597,7 +593,7 @@ def pathwidth(self, k=None, certificate=False, algorithm="BAB", verbose=False, return (pw <= k, linear_ordering_to_path_decomposition(self, L)) if certificate else pw <= k -def path_decomposition(G, algorithm="BAB", cut_off=None, upper_bound=None, verbose=False, +def path_decomposition(G, algorithm='BAB', cut_off=None, upper_bound=None, verbose=False, max_prefix_length=20, max_prefix_number=10**6): r""" Return the pathwidth of the given graph and the ordering of the vertices @@ -607,28 +603,28 @@ def path_decomposition(G, algorithm="BAB", cut_off=None, upper_bound=None, verbo - ``G`` -- a Graph - - ``algorithm`` -- string (default: ``"BAB"``); algorithm to use among: + - ``algorithm`` -- string (default: ``'BAB'``); algorithm to use among: - - ``"BAB"`` -- Use a branch-and-bound algorithm. This algorithm has no + - ``'BAB'`` -- use a branch-and-bound algorithm. This algorithm has no size restriction but could take a very long time on large graphs. It can also be used to test is the input (di)graph has vertex separation at most ``upper_bound`` or to return the first found solution with vertex separation less or equal to a ``cut_off`` value. - - ``exponential`` -- Use an exponential time and space algorithm. This - algorithm only works of graphs on less than 32 vertices. + - ``exponential`` -- use an exponential time and space algorithm. This + algorithm only works of graphs on less than 32 vertices - - ``MILP`` -- Use a mixed integer linear programming formulation. This - algorithm has no size restriction but could take a very long time. + - ``MILP`` -- use a mixed integer linear programming formulation. This + algorithm has no size restriction but could take a very long time - ``upper_bound`` -- integer (default: ``None``); parameter used by the - ``"BAB"`` algorithm. If specified, the algorithm searches for a solution + ``'BAB'`` algorithm. If specified, the algorithm searches for a solution with ``width < upper_bound``. It helps cutting branches. However, if the given upper bound is too low, the algorithm may not be able to find a solution. - ``cut_off`` -- integer (default: ``None``); parameter used by the - ``"BAB"`` algorithm. This bound allows us to stop the search as soon as a + ``'BAB'`` algorithm. This bound allows us to stop the search as soon as a solution with width at most ``cut_off`` is found, if any. If this bound cannot be reached, the best solution found is returned, unless a too low ``upper_bound`` is given. @@ -659,11 +655,11 @@ def path_decomposition(G, algorithm="BAB", cut_off=None, upper_bound=None, verbo sage: from sage.graphs.graph_decompositions.vertex_separation import path_decomposition sage: g = graphs.CycleGraph(6) - sage: pw, L = path_decomposition(g, algorithm="BAB"); pw + sage: pw, L = path_decomposition(g, algorithm='BAB'); pw 2 - sage: pw, L = path_decomposition(g, algorithm="exponential"); pw + sage: pw, L = path_decomposition(g, algorithm='exponential'); pw 2 - sage: pw, L = path_decomposition(g, algorithm="MILP"); pw # needs sage.numerical.mip + sage: pw, L = path_decomposition(g, algorithm='MILP'); pw # needs sage.numerical.mip 2 TESTS: @@ -679,11 +675,10 @@ def path_decomposition(G, algorithm="BAB", cut_off=None, upper_bound=None, verbo Given a wrong algorithm:: sage: from sage.graphs.graph_decompositions.vertex_separation import path_decomposition - sage: path_decomposition(Graph(), algorithm="SuperFast") + sage: path_decomposition(Graph(), algorithm='SuperFast') Traceback (most recent call last): ... ValueError: algorithm "SuperFast" has not been implemented yet, please contribute - """ from sage.graphs.graph import Graph if not isinstance(G, Graph): @@ -694,7 +689,7 @@ def path_decomposition(G, algorithm="BAB", cut_off=None, upper_bound=None, verbo max_prefix_number=max_prefix_number) -def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbose=False, +def vertex_separation(G, algorithm='BAB', cut_off=None, upper_bound=None, verbose=False, max_prefix_length=20, max_prefix_number=10**6, *, solver=None, integrality_tolerance=1e-3): r""" @@ -705,28 +700,28 @@ def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbos - ``G`` -- a Graph or a DiGraph - - ``algorithm`` -- string (default: ``"BAB"``); algorithm to use among: + - ``algorithm`` -- string (default: ``'BAB'``); algorithm to use among: - - ``"BAB"`` -- Use a branch-and-bound algorithm. This algorithm has no + - ``'BAB'`` -- use a branch-and-bound algorithm. This algorithm has no size restriction but could take a very long time on large graphs. It can also be used to test is the input (di)graph has vertex separation at most ``upper_bound`` or to return the first found solution with vertex separation less or equal to a ``cut_off`` value. - - ``exponential`` -- Use an exponential time and space algorithm. This - algorithm only works of graphs on less than 32 vertices. + - ``exponential`` -- use an exponential time and space algorithm. This + algorithm only works of graphs on less than 32 vertices - - ``MILP`` -- Use a mixed integer linear programming formulation. This - algorithm has no size restriction but could take a very long time. + - ``MILP`` -- use a mixed integer linear programming formulation. This + algorithm has no size restriction but could take a very long time - ``upper_bound`` -- integer (default: ``None``); parameter used by the - ``"BAB"`` algorithm. If specified, the algorithm searches for a solution + ``'BAB'`` algorithm. If specified, the algorithm searches for a solution with ``width < upper_bound``. It helps cutting branches. However, if the given upper bound is too low, the algorithm may not be able to find a solution. - ``cut_off`` -- integer (default: ``None``); parameter used by the - ``"BAB"`` algorithm. This bound allows us to stop the search as soon as a + ``'BAB'`` algorithm. This bound allows us to stop the search as soon as a solution with width at most ``cut_off`` is found, if any. If this bound cannot be reached, the best solution found is returned, unless a too low ``upper_bound`` is given. @@ -742,7 +737,7 @@ def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbos number of stored prefixes used to prevent using too much memory. This parameter is used only when ``algorithm=="BAB"``. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -767,19 +762,19 @@ def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbos sage: # needs sage.combinat sage: G = digraphs.DeBruijn(2,3) - sage: vs,L = vertex_separation(G, algorithm="BAB"); vs + sage: vs,L = vertex_separation(G, algorithm='BAB'); vs 2 - sage: vs,L = vertex_separation(G, algorithm="exponential"); vs + sage: vs,L = vertex_separation(G, algorithm='exponential'); vs 2 - sage: vs,L = vertex_separation(G, algorithm="MILP"); vs # needs sage.numerical.mip + sage: vs,L = vertex_separation(G, algorithm='MILP'); vs # needs sage.numerical.mip 2 sage: G = graphs.Grid2dGraph(3,3) - sage: vs,L = vertex_separation(G, algorithm="BAB"); vs + sage: vs,L = vertex_separation(G, algorithm='BAB'); vs 3 - sage: vs,L = vertex_separation(G, algorithm="exponential"); vs + sage: vs,L = vertex_separation(G, algorithm='exponential'); vs 3 - sage: vs,L = vertex_separation(G, algorithm="MILP"); vs # needs sage.numerical.mip + sage: vs,L = vertex_separation(G, algorithm='MILP'); vs # needs sage.numerical.mip 3 Digraphs with multiple strongly connected components:: @@ -806,7 +801,7 @@ def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbos sage: from sage.graphs.graph_decompositions.vertex_separation import vertex_separation sage: G = graphs.PetersenGraph() - sage: vs, L = vertex_separation(G, algorithm="MILP", solver="SCIP"); vs # optional - pyscipopt, needs sage.numerical.mip + sage: vs, L = vertex_separation(G, algorithm='MILP', solver='SCIP'); vs # optional - pyscipopt, needs sage.numerical.mip 5 TESTS: @@ -814,7 +809,7 @@ def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbos Given a wrong algorithm:: sage: from sage.graphs.graph_decompositions.vertex_separation import vertex_separation - sage: vertex_separation(Graph(), algorithm="SuperFast") + sage: vertex_separation(Graph(), algorithm='SuperFast') Traceback (most recent call last): ... ValueError: algorithm "SuperFast" has not been implemented yet, please contribute @@ -885,7 +880,7 @@ def vertex_separation(G, algorithm="BAB", cut_off=None, upper_bound=None, verbos L.extend(LH) # We also update the cut_off parameter that could speed up - # resolution for other components (used when algorithm=="BAB") + # resolution for other components (used when algorithm=='BAB') cut_off = max(cut_off, vs) return vs, L @@ -1110,17 +1105,15 @@ def is_valid_ordering(G, L): INPUT: - - ``G`` -- a Graph or a DiGraph. - - - ``L`` -- an ordered list of the vertices of ``G``. + - ``G`` -- a Graph or a DiGraph + - ``L`` -- an ordered list of the vertices of ``G`` OUTPUT: Returns ``True`` if `L` is a valid vertex ordering for `G`, and ``False`` otherwise. - EXAMPLES: Path decomposition of a cycle:: @@ -1290,7 +1283,7 @@ def _vertex_separation_MILP_formulation(G, integrality=False, solver=None): no impact on the validity of the solution, but it is sometimes faster to solve the problem using binary variables only. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1298,9 +1291,7 @@ def _vertex_separation_MILP_formulation(G, integrality=False, solver=None): :class:`MixedIntegerLinearProgram `. - OUTPUT: - - - the :class:`~sage.numerical.mip.MixedIntegerLinearProgram` + OUTPUT: the :class:`~sage.numerical.mip.MixedIntegerLinearProgram` - :class:`sage.numerical.mip.MIPVariable` objects ``x``, ``u``, ``y``, ``z``. @@ -1396,7 +1387,7 @@ def vertex_separation_MILP(G, integrality=False, solver=None, verbose=0, no impact on the validity of the solution, but it is sometimes faster to solve the problem using binary variables only. - - ``solver`` -- string (default: ``None``); specify a Mixed Integer Linear + - ``solver`` -- string (default: ``None``); specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method :meth:`solve @@ -1404,7 +1395,7 @@ def vertex_separation_MILP(G, integrality=False, solver=None, verbose=0, :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- float; parameter for use with MILP solvers @@ -1517,7 +1508,7 @@ def vertex_separation_BAB(G, INPUT: - - ``G`` -- a Graph or a DiGraph. + - ``G`` -- a Graph or a DiGraph - ``cut_off`` -- integer (default: ``None``); bound to consider in the branch and bound algorithm. This allows us to stop the search as soon as a @@ -1539,9 +1530,7 @@ def vertex_separation_BAB(G, - ``verbose`` -- boolean (default: ``False``); display some information when set to ``True`` - OUTPUT: - - - ``width`` -- the computed vertex separation + OUTPUT: ``width`` -- the computed vertex separation - ``seq`` -- an ordering of the vertices of width ``width`` diff --git a/src/sage/graphs/graph_generators.py b/src/sage/graphs/graph_generators.py index 6814194ea37..3f481697b65 100644 --- a/src/sage/graphs/graph_generators.py +++ b/src/sage/graphs/graph_generators.py @@ -515,7 +515,7 @@ class GraphGenerators: INPUT: - ``vertices`` -- a natural number or ``None`` to infinitely generate - bigger and bigger graphs. + bigger and bigger graphs - ``property`` -- (default: ``lambda x: True``) any property to be tested on graphs before generation, but note that in general the @@ -550,20 +550,20 @@ class GraphGenerators: not hold, then all the graphs generated will satisfy the property, but there will be some missing. - - ``size`` -- (default: ``None``) the size of the graph to be generated. + - ``size`` -- (default: ``None``) the size of the graph to be generated - - ``degree_sequence`` -- (default: ``None``) a sequence of non-negative integers, + - ``degree_sequence`` -- (default: ``None``) a sequence of nonnegative integers, or ``None``. If specified, the generated graphs will have these integers for degrees. In this case, property and size are both ignored. - - ``loops`` -- (default: ``False``) whether to allow loops in the graph - or not. + - ``loops`` -- boolean (default: ``False``); whether to allow loops in the graph + or not - - ``sparse`` -- (default: ``True``); whether to use a sparse or dense data + - ``sparse`` -- (default: ``True``) whether to use a sparse or dense data structure. See the documentation of :class:`~sage.graphs.graph.Graph`. - - ``copy`` (boolean) -- If set to ``True`` (default) + - ``copy`` -- boolean; if set to ``True`` (default) this method makes copies of the graphs before returning them. If set to ``False`` the method returns the graph it is working on. The second alternative is faster, but modifying @@ -739,7 +739,7 @@ class GraphGenerators: def __call__(self, vertices=None, property=None, augment='edges', size=None, degree_sequence=None, loops=False, sparse=True, copy=True): """ - Accesses the generator of isomorphism class representatives. + Access the generator of isomorphism class representatives. Iterates over distinct, exhaustive representatives. See the docstring of this class for full documentation. @@ -856,13 +856,13 @@ def extra_property(x): else: raise NotImplementedError - def nauty_geng(self, options="", debug=False): + def nauty_geng(self, options='', debug=False): r""" Return a generator which creates graphs from nauty's geng program. INPUT: - - ``options`` -- string (default: ``""``); a string passed to ``geng`` + - ``options`` -- string (default: ``''``); a string passed to ``geng`` as if it was run at a system command line. At a minimum, you *must* pass the number of vertices you desire. Sage expects the graphs to be in nauty's "graph6" format, do not set an option to change this @@ -999,7 +999,7 @@ def nauty_geng(self, options="", debug=False): G = graph.Graph(s[:-1], format='graph6') yield G - def nauty_genbg(self, options="", debug=False): + def nauty_genbg(self, options='', debug=False): r""" Return a generator which creates bipartite graphs from nauty's ``genbg`` program. @@ -1199,7 +1199,7 @@ def nauty_genbg(self, options="", debug=False): G = BipartiteGraph(s[:-1], format='graph6', partition=partition) yield G - def nauty_genktreeg(self, options="", debug=False): + def nauty_genktreeg(self, options='', debug=False): r""" Return a generator which creates all `k`-trees using nauty.. @@ -1322,15 +1322,15 @@ def cospectral_graphs(self, vertices, matrix_function=None, graphs=None): INPUT: - - ``vertices`` -- The number of vertices in the graphs to be tested + - ``vertices`` -- the number of vertices in the graphs to be tested - - ``matrix_function`` -- A function taking a graph and giving back + - ``matrix_function`` -- a function taking a graph and giving back a matrix. This defaults to the adjacency matrix. The spectra examined are the spectra of these matrices. - - ``graphs`` -- One of three things: + - ``graphs`` -- one of three things: - - ``None`` (default) -- test all graphs having ``vertices`` + - ``None`` -- default; test all graphs having ``vertices`` vertices - a function taking a graph and returning ``True`` or ``False`` @@ -1436,7 +1436,7 @@ def cospectral_graphs(self, vertices, matrix_function=None, graphs=None): def _read_planar_code(self, code_input): r""" - Returns a generator for the plane graphs in planar code format in + Return a generator for the plane graphs in planar code format in the file code_input (see [BM2016]_). A file with planar code starts with a header ``>>planar_code<<``. @@ -1451,7 +1451,7 @@ def _read_planar_code(self, code_input): INPUT: - - ``code_input`` -- a file containing valid planar code data. + - ``code_input`` -- a file containing valid planar code data OUTPUT: @@ -1543,15 +1543,15 @@ def _read_planar_code(self, code_input): def fullerenes(self, order, ipr=False): r""" - Returns a generator which creates fullerene graphs using + Return a generator which creates fullerene graphs using the buckygen generator (see [BGM2012]_). INPUT: - - ``order`` -- a positive even integer smaller than or equal to 254. - This specifies the number of vertices in the generated fullerenes. + - ``order`` -- a positive even integer smaller than or equal to 254 + This specifies the number of vertices in the generated fullerenes - - ``ipr`` -- (default: ``False``); if ``True`` only fullerenes that + - ``ipr`` -- (default: ``False``) if ``True`` only fullerenes that satisfy the Isolated Pentagon Rule are generated. This means that no pentagonal faces share an edge. @@ -1621,7 +1621,7 @@ def fullerenes(self, order, ipr=False): """ # number of vertices should be positive if order < 0: - raise ValueError("number of vertices should be non-negative") + raise ValueError("number of vertices should be nonnegative") # buckygen can only output fullerenes on up to 254 vertices if order > 254: @@ -1650,18 +1650,18 @@ def fullerenes(self, order, ipr=False): def fusenes(self, hexagon_count, benzenoids=False): r""" - Returns a generator which creates fusenes and benzenoids using + Return a generator which creates fusenes and benzenoids using the benzene generator (see [BCH2002]_). Fusenes are planar polycyclic hydrocarbons with all bounded faces hexagons. Benzenoids are fusenes that are subgraphs of the hexagonal lattice. INPUT: - - ``hexagon_count`` -- a positive integer smaller than or equal to 30. - This specifies the number of hexagons in the generated benzenoids. + - ``hexagon_count`` -- positive integer smaller than or equal to 30; + this specifies the number of hexagons in the generated benzenoids - - ``benzenoids`` -- (default: ``False``); if ``True`` only benzenoids are - generated. + - ``benzenoids`` -- (default: ``False``) if ``True`` only benzenoids are + generated OUTPUT: @@ -1702,7 +1702,7 @@ def fusenes(self, hexagon_count, benzenoids=False): 6505 """ if hexagon_count < 0: - raise ValueError("number of hexagons should be non-negative") + raise ValueError("number of hexagons should be nonnegative") # benzene is only built for fusenes with up to 30 hexagons if hexagon_count > 30: @@ -1946,24 +1946,24 @@ def planar_graphs(self, order, minimum_degree=None, INPUT: - - ``order`` -- a positive integer smaller than or equal to 64. - This specifies the number of vertices in the generated graphs. + - ``order`` -- positive integer smaller than or equal to 64; + this specifies the number of vertices in the generated graphs - - ``minimum_degree`` -- (default: ``None``); a value `\geq 1` and `\leq + - ``minimum_degree`` -- (default: ``None``) a value `\geq 1` and `\leq 5`, or ``None``. This specifies the minimum degree of the generated graphs. If this is ``None`` and the order is 1, then this is set to 0. If this is ``None`` and the minimum connectivity is specified, then this is set to the same value as the minimum connectivity. If the minimum connectivity is also equal to ``None``, then this is set to 1. - - ``minimum_connectivity`` -- (default: ``None``); a value `\geq 1` + - ``minimum_connectivity`` -- (default: ``None``) a value `\geq 1` and `\leq 3`, or ``None``. This specifies the minimum connectivity of the generated graphs. If this is ``None`` and the minimum degree is specified, then this is set to the minimum of the minimum degree and 3. If the minimum degree is also equal to ``None``, then this is set to 1. - - ``exact_connectivity`` -- (default: ``False``); if ``True`` only + - ``exact_connectivity`` -- (default: ``False``) if ``True`` only graphs with exactly the specified connectivity will be generated. This option cannot be used with ``minimum_connectivity=3``, or if the minimum connectivity is not explicitly set. @@ -1977,12 +1977,12 @@ def planar_graphs(self, order, minimum_degree=None, - ``maximum_face_size`` -- integer (default: ``None``); upper bound on the size of a face and so on the maximum degree of the dual graph - - ``only_bipartite`` -- (default: ``False``); if ``True`` only bipartite + - ``only_bipartite`` -- (default: ``False``) if ``True`` only bipartite graphs will be generated. This option cannot be used for graphs with a minimum degree larger than 3. - - ``dual`` -- (default: ``False``); if ``True`` return instead the - planar duals of the generated graphs. + - ``dual`` -- (default: ``False``) if ``True`` return instead the + planar duals of the generated graphs OUTPUT: @@ -2073,7 +2073,7 @@ def planar_graphs(self, order, minimum_degree=None, True """ if order < 0: - raise ValueError("number of vertices should be non-negative") + raise ValueError("number of vertices should be nonnegative") # plantri can only output general planar graphs on up to 64 vertices if order > 64: @@ -2175,34 +2175,34 @@ def triangulations(self, order, minimum_degree=None, minimum_connectivity=None, INPUT: - - ``order`` -- a positive integer smaller than or equal to 64. - This specifies the number of vertices in the generated triangulations. + - ``order`` -- positive integer smaller than or equal to 64; + this specifies the number of vertices in the generated triangulations - - ``minimum_degree`` -- (default: ``None``); a value `\geq 3` and `\leq 5`, + - ``minimum_degree`` -- (default: ``None``) a value `\geq 3` and `\leq 5`, or ``None``. This specifies the minimum degree of the generated triangulations. If this is ``None`` and the minimum connectivity is specified, then this is set to the same value as the minimum connectivity. If the minimum connectivity is also equal to ``None``, then this is set to 3. - - ``minimum_connectivity`` -- (default: ``None``); a value `\geq 3` and + - ``minimum_connectivity`` -- (default: ``None``) a value `\geq 3` and `\leq 5`, or ``None``. This specifies the minimum connectivity of the generated triangulations. If this is ``None`` and the minimum degree is specified, then this is set to the minimum of the minimum degree and 3. If the minimum degree is also equal to ``None``, then this is set to 3. - - ``exact_connectivity`` -- (default: ``False``); if ``True`` only + - ``exact_connectivity`` -- (default: ``False``) if ``True`` only triangulations with exactly the specified connectivity will be generated. This option cannot be used with ``minimum_connectivity=3``, or if the minimum connectivity is not explicitly set. - - ``only_eulerian`` -- (default: ``False``); if ``True`` only Eulerian + - ``only_eulerian`` -- (default: ``False``) if ``True`` only Eulerian triangulations will be generated. This option cannot be used if the minimum degree is explicitly set to anything else than 4. - - ``dual`` -- (default: ``False``); if ``True`` return instead the - planar duals of the generated graphs. + - ``dual`` -- (default: ``False``) if ``True`` return instead the + planar duals of the generated graphs OUTPUT: @@ -2297,7 +2297,7 @@ def triangulations(self, order, minimum_degree=None, minimum_connectivity=None, [12, 12] """ if order < 0: - raise ValueError("number of vertices should be non-negative") + raise ValueError("number of vertices should be nonnegative") # plantri can only output planar triangulations on up to 64 vertices if order > 64: @@ -2361,17 +2361,17 @@ def quadrangulations(self, order, minimum_degree=None, minimum_connectivity=None INPUT: - - ``order`` -- a positive integer smaller than or equal to 64. - This specifies the number of vertices in the generated quadrangulations. + - ``order`` -- positive integer smaller than or equal to 64; + this specifies the number of vertices in the generated quadrangulations - - ``minimum_degree`` -- default: ``None``; a value `\geq 2` and `\leq + - ``minimum_degree`` -- (default: ``None``) a value `\geq 2` and `\leq 3`, or ``None``. This specifies the minimum degree of the generated quadrangulations. If this is ``None`` and the minimum connectivity is specified, then this is set to the same value as the minimum connectivity. If the minimum connectivity is also equal to ``None``, then this is set to 2. - - ``minimum_connectivity`` -- default: ``None``; a value `\geq 2` and + - ``minimum_connectivity`` -- (default: ``None``) a value `\geq 2` and `\leq 3`, or ``None``. This specifies the minimum connectivity of the generated quadrangulations. If this is ``None`` and the option ``no_nonfacial_quadrangles`` is set to ``True``, then this is set to @@ -2379,12 +2379,12 @@ def quadrangulations(self, order, minimum_degree=None, minimum_connectivity=None then this is set to the minimum degree. If the minimum degree is also equal to ``None``, then this is set to 3. - - ``no_nonfacial_quadrangles`` -- default: ``False``; if ``True`` only + - ``no_nonfacial_quadrangles`` -- (default: ``False``) if ``True`` only quadrangulations with no non-facial quadrangles are generated. This option cannot be used if ``minimum_connectivity`` is set to 2. - - ``dual`` -- default: ``False``; if ``True`` return instead the - planar duals of the generated graphs. + - ``dual`` -- (default: ``False``) if ``True`` return instead the + planar duals of the generated graphs OUTPUT: @@ -2440,7 +2440,7 @@ def quadrangulations(self, order, minimum_degree=None, minimum_connectivity=None [10, 10] """ if order < 0: - raise ValueError("number of vertices should be non-negative") + raise ValueError("number of vertices should be nonnegative") # plantri can only output planar quadrangulations on up to 64 vertices if order > 64: @@ -2808,19 +2808,15 @@ def canaug_traverse_vert(g, aut_gens, max_verts, property, dig=False, loops=Fals INPUT: + - ``g`` -- current position on the tree - - ``g`` -- current position on the tree. + - ``aut_gens`` -- list of generators of Aut(g), in list notation - - ``aut_gens`` -- list of generators of Aut(g), in - list notation. + - ``max_verts`` -- when to retreat - - ``max_verts`` -- when to retreat. - - - ``property`` -- check before traversing below g. - - - ``degree_sequence`` -- specify a degree sequence to try to - obtain. + - ``property`` -- check before traversing below g + - ``degree_sequence`` -- specify a degree sequence to try to obtain EXAMPLES:: @@ -3000,14 +2996,11 @@ def canaug_traverse_edge(g, aut_gens, property, dig=False, loops=False, sparse=T INPUT: + - ``g`` -- current position on the tree - - ``g`` -- current position on the tree. - - - ``aut_gens`` -- list of generators of Aut(g), in - list notation. - - - ``property`` -- check before traversing below g. + - ``aut_gens`` -- list of generators of Aut(g), in list notation + - ``property`` -- check before traversing below g EXAMPLES:: diff --git a/src/sage/graphs/graph_input.py b/src/sage/graphs/graph_input.py index b60ebde2e31..432cce4ec99 100644 --- a/src/sage/graphs/graph_input.py +++ b/src/sage/graphs/graph_input.py @@ -444,7 +444,7 @@ def from_dict_of_dicts(G, M, loops=False, multiedges=False, weighted=False, conv - ``G`` -- a graph - - ``M`` -- a dictionary of dictionaries + - ``M`` -- dictionary of dictionaries - ``loops``, ``multiedges``, ``weighted`` -- booleans (default: ``False``); whether to consider the graph as having loops, multiple edges, or weights @@ -541,7 +541,7 @@ def from_dict_of_lists(G, D, loops=False, multiedges=False, weighted=False): - ``G`` -- a :class:`Graph` or :class:`DiGraph` - - ``D`` -- a dictionary of lists + - ``D`` -- dictionary of lists - ``loops``, ``multiedges``, ``weighted`` -- booleans (default: ``False``); whether to consider the graph as having loops, multiple edges, or weights diff --git a/src/sage/graphs/graph_latex.py b/src/sage/graphs/graph_latex.py index bb1b727eda9..4606c56b4f9 100644 --- a/src/sage/graphs/graph_latex.py +++ b/src/sage/graphs/graph_latex.py @@ -251,7 +251,7 @@ here we color in red all edges touching the vertex ``0``:: sage: g = graphs.PetersenGraph() - sage: g.set_latex_options(format="dot2tex", edge_options=lambda u_v_label: {"color": "red"} if u_v_label[0] == 0 else {}) + sage: g.set_latex_options(format='dot2tex', edge_options=lambda u_v_label: {"color": "red"} if u_v_label[0] == 0 else {}) sage: latex(g) # optional - dot2tex graphviz \begin{tikzpicture}[>=latex,line join=bevel,] ... @@ -622,19 +622,19 @@ def set_option(self, option_name, option_value=None): INPUT: - - ``option_name`` -- a string for a latex option contained in the list - ``sage.graphs.graph_latex.GraphLatex.__graphlatex_options``. - A :class:`ValueError` is raised if the option is not allowed. + - ``option_name`` -- string for a latex option contained in the list + ``sage.graphs.graph_latex.GraphLatex.__graphlatex_options``; + a :exc:`ValueError` is raised if the option is not allowed - - ``option_value`` -- a value for the option. If omitted, or set to - ``None``, the option will use the default value. + - ``option_value`` -- a value for the option; if omitted, or set to + ``None``, the option will use the default value The output can be either handled internally by ``Sage``, or delegated to the external software ``dot2tex`` and ``graphviz``. This is controlled by the option ``format``: - ``format`` -- string (default: ``'tkz_graph'``); either ``'dot2tex'`` - or ``'tkz_graph'``. + or ``'tkz_graph'`` If format is ``'dot2tex'``, then all the LaTeX generation will be delegated to ``dot2tex`` (which must be installed). @@ -652,17 +652,17 @@ def set_option(self, option_name, option_value=None): effort. For a custom appearance set this to ``'Custom'`` and use the options described below to override the default values. - - ``units`` -- string (default: ``'cm'``) -- a natural unit of + - ``units`` -- string (default: ``'cm'``); a natural unit of measurement used for all dimensions. Possible values are: ``'in'``, ``'mm'``, ``'cm'``, ``'pt'``, ``'em'``, ``'ex'``. - - ``scale`` -- float (default: ``1.0``); a dimensionless number that + - ``scale`` -- float (default: `1.0`); a dimensionless number that multiplies every linear dimension. So you can design at sizes you are accustomed to, then shrink or expand to meet other needs. Though fonts do not scale. - ``graphic_size`` -- tuple (default: ``(5, 5)``); overall dimensions - (width, length) of the bounding box around the entire graphic image. + (width, length) of the bounding box around the entire graphic image - ``margins`` -- 4-tuple (default: ``(0, 0, 0, 0)``); portion of graphic given over to a plain border as a tuple of four numbers: (left, right, @@ -677,7 +677,7 @@ def set_option(self, option_name, option_value=None): pre-built style and modify it (other than editing the latex string by hand after the fact). - - ``vertex_color`` -- (default: ``'black'``); a single color to use as + - ``vertex_color`` -- (default: ``'black'``) a single color to use as the default for outline of vertices. For the ``sphere`` shape this color is used for the entire vertex, which is drawn with a 3D shading. Colors must be specified as a string recognized by the matplotlib @@ -687,19 +687,19 @@ def set_option(self, option_name, option_value=None): These color specifications are consistent throughout the options for a ``tikzpicture``. - - ``vertex_colors`` -- a dictionary whose keys are vertices of the graph + - ``vertex_colors`` -- dictionary whose keys are vertices of the graph and whose values are colors. These will be used to color the outline of vertices. See the explanation above for the ``vertex_color`` option to see possible values. These values need only be specified for a proper subset of the vertices. Specified values will supersede a default value. - - ``vertex_fill_color`` -- (default: ``'white'``); a single color to use + - ``vertex_fill_color`` -- (default: ``'white'``) a single color to use as the default for the fill color of vertices. See the explanation above for the ``vertex_color`` option to see possible values. This color is ignored for the ``sphere`` vertex shape. - - ``vertex_fill_colors`` -- a dictionary whose keys are vertices of the + - ``vertex_fill_colors`` -- dictionary whose keys are vertices of the graph and whose values are colors. These will be used to fill the interior of vertices. See the explanation above for the ``vertex_color`` option to see possible values. These values need only @@ -713,7 +713,7 @@ def set_option(self, option_name, option_value=None): ``vertex_color`` and ``vertex_colors``, which are normally used for the outline of the vertex. - - ``vertex_shapes`` -- a dictionary whose keys are vertices of the graph + - ``vertex_shapes`` -- dictionary whose keys are vertices of the graph and whose values are shapes. See ``vertex_shape`` for the allowable possibilities. @@ -724,7 +724,7 @@ def set_option(self, option_name, option_value=None): parameter), while still containing labels. However, if labels are not of a uniform size, then the vertices will not be either. - - ``vertex_sizes`` -- a dictionary of sizes for some of the vertices. + - ``vertex_sizes`` -- dictionary of sizes for some of the vertices - ``vertex_labels`` -- boolean (default: ``True``); determine whether or not to display the vertex labels. If ``False`` subsequent options @@ -738,33 +738,33 @@ def set_option(self, option_name, option_value=None): representation according to the ``_repr`` method. Support for arbitrarily-complicated mathematics is not especially robust. - - ``vertex_label_color`` -- (default: ``'black'``); a single color to + - ``vertex_label_color`` -- (default: ``'black'``) a single color to use as the default for labels of vertices. See the explanation above for the ``vertex_color`` option to see possible values. - - ``vertex_label_colors`` -- a dictionary whose keys are vertices of the + - ``vertex_label_colors`` -- dictionary whose keys are vertices of the graph and whose values are colors. These will be used for the text of the labels of vertices. See the explanation above for the ``vertex_color`` option to see possible values. These values need only be specified for a proper subset of the vertices. Specified values will supersede a default value. - - ``vertex_label_placement`` -- (default: ``'center'``); if ``'center'`` + - ``vertex_label_placement`` -- (default: ``'center'``) if ``'center'`` the label is centered in the interior of the vertex and the vertex will expand to contain the label. Giving instead a pair of numbers will place the label exterior to the vertex at a certain distance from the edge, and at an angle to the positive x-axis, similar in spirit to polar coordinates. - - ``vertex_label_placements`` -- a dictionary of placements indexed by + - ``vertex_label_placements`` -- dictionary of placements indexed by the vertices. See the explanation for ``vertex_label_placement`` for the possible values. - - ``edge_color`` -- (default: ``'black'``); a single color to use as the + - ``edge_color`` -- (default: ``'black'``) a single color to use as the default for an edge. See the explanation above for the ``vertex_color`` option to see possible values. - - ``edge_colors`` -- a dictionary whose keys are edges of the graph and + - ``edge_colors`` -- dictionary whose keys are edges of the graph and whose values are colors. These will be used to color the edges. See the explanation above for the ``vertex_color`` option to see possible values. These values need only be specified for a proper subset of the @@ -774,13 +774,13 @@ def set_option(self, option_name, option_value=None): second color running down the middle. This can be a useful effect for highlighting edge crossings. - - ``edge_fill_color`` -- (default: ``'black'``); a single color to use + - ``edge_fill_color`` -- (default: ``'black'``) a single color to use as the default for the fill color of an edge. The boolean switch - ``edge_fills`` must be set to True for this to have an effect. See + ``edge_fills`` must be set to ``True`` for this to have an effect. See the explanation above for the ``vertex_color`` option to see possible values. - - ``edge_fill_colors`` -- a dictionary whose keys are edges of the graph + - ``edge_fill_colors`` -- dictionary whose keys are edges of the graph and whose values are colors. See the explanation above for the ``vertex_color`` option to see possible values. These values need only be specified for a proper subset of the vertices. Specified @@ -790,7 +790,7 @@ def set_option(self, option_name, option_value=None): edges. Note that ``tkz-graph`` does not interpret this number for loops. - - ``edge_thicknesses`` -- a dictionary of thicknesses for some of the + - ``edge_thicknesses`` -- dictionary of thicknesses for some of the edges of a graph. These values need only be specified for a proper subset of the vertices. Specified values will supersede a default value. @@ -804,11 +804,11 @@ def set_option(self, option_name, option_value=None): ``vertex_labels_math`` option, which behaves identically. Support for arbitrarily-complicated mathematics is not especially robust. - - ``edge_label_color`` -- (default: ``'black'``); a single color to use + - ``edge_label_color`` -- (default: ``'black'``) a single color to use as the default for labels of edges. See the explanation above for the ``vertex_color`` option to see possible values. - - ``edge_label_colors`` -- a dictionary whose keys are edges of the + - ``edge_label_colors`` -- dictionary whose keys are edges of the graph and whose values are colors. These will be used for the text of the labels of edges. See the explanation above for the ``vertex_color`` option to see possible values. These values need only @@ -822,11 +822,11 @@ def set_option(self, option_name, option_value=None): ``True`` means the label is rotated to follow the direction of the edge it labels. - - ``edge_label_slopes`` -- a dictionary of booleans, indexed by some + - ``edge_label_slopes`` -- dictionary of booleans, indexed by some subset of the edges. See the ``edge_label_sloped`` option for a description of sloped edge labels. - - ``edge_label_placement`` -- (default: 0.50); either a number between + - ``edge_label_placement`` -- (default: 0.50) either a number between 0.0 and 1.0, or one of: ``'above'``, ``'below'``, ``'left'``, ``'right'``. These adjust the location of an edge label along an edge. A number specifies how far along the edge the label is located. @@ -835,7 +835,7 @@ def set_option(self, option_name, option_value=None): the midpoint of the edge. The default value of ``0.50`` places the label on the midpoint of the edge. - - ``edge_label_placements`` -- a dictionary of edge placements, indexed + - ``edge_label_placements`` -- dictionary of edge placements, indexed by the edges. See the ``edge_label_placement`` option for a description of the allowable values. @@ -845,7 +845,7 @@ def set_option(self, option_name, option_value=None): specifying a compass point (North, South, East, West) as one of ``'NO'``, ``'SO'``, ``'EA'``, ``'WE'``. - - ``loop_placements`` -- a dictionary of loop placements. See the + - ``loop_placements`` -- dictionary of loop placements. See the ``loop_placements`` option for the allowable values. While loops are technically edges, this dictionary is indexed by vertices. @@ -857,10 +857,10 @@ def set_option(self, option_name, option_value=None): ``'dot'``, ``'neato'``, ``'twopi'``, ``'circo'`` or ``'fdp'``. - ``edge_labels`` -- boolean (default: ``False)``; whether to display - the labels on edges. + the labels on edges - ``edge_colors`` -- a color; can be used to set a global color to the - edge of the graph. + edge of the graph - ``color_by_label`` -- boolean (default: ``False``); colors the edges according to their labels @@ -870,9 +870,7 @@ def set_option(self, option_name, option_value=None): same cluster subgraph are drawn together, with the entire drawing of the cluster contained within a bounding rectangle. - OUTPUT: - - There are none. Success happens silently. + OUTPUT: none; success happens silently EXAMPLES: @@ -1350,7 +1348,6 @@ def latex(self): \end{scope} ... \end{tikzpicture} - """ format = self.get_option('format') if format == "tkz_graph": @@ -1434,7 +1431,7 @@ def dot2tex_picture(self): new_edge_colors[col] = [edge] options['edge_colors'] = new_edge_colors - dotdata = self._graph.graphviz_string(labels="latex", **options) + dotdata = self._graph.graphviz_string(labels='latex', **options) import dot2tex return dot2tex.dot2tex(dotdata, format='tikz', diff --git a/src/sage/graphs/graph_list.py b/src/sage/graphs/graph_list.py index 6994a821948..4109d5d738a 100644 --- a/src/sage/graphs/graph_list.py +++ b/src/sage/graphs/graph_list.py @@ -241,7 +241,7 @@ def _to_graph6(graphs, file=None, output_list=False, sparse=False): def to_graphics_array(graph_list, **kwds): """ - Draw all graphs in a graphics array + Draw all graphs in a graphics array. INPUT: diff --git a/src/sage/graphs/graph_plot.py b/src/sage/graphs/graph_plot.py index 6e36a195197..c97a5892efe 100644 --- a/src/sage/graphs/graph_plot.py +++ b/src/sage/graphs/graph_plot.py @@ -168,7 +168,7 @@ 'Which graphviz layout program to use -- one of ' '"circo", "dot", "fdp", "neato", or "twopi".', 'by_component': - 'Whether to do the spring layout by connected component -- a boolean.'} + 'Whether to do the spring layout by connected component -- boolean.'} graphplot_options = layout_options.copy() @@ -1033,7 +1033,6 @@ def show(self, **kwds): P = C.graphplot(vertex_labels=False, vertex_size=0, graph_border=True) sphinx_plot(P) - """ # Setting the default values if needed for k, value in DEFAULT_SHOW_OPTIONS.items(): @@ -1334,7 +1333,7 @@ def plot(self, **kwds): t = DiGraph('JCC???@A??GO??CO??GO??') sphinx_plot(t.graphplot(layout='tree', tree_root=0, - tree_orientation="up")) + tree_orientation='up')) More examples:: @@ -1467,7 +1466,7 @@ def layout_tree(self, root, orientation): INPUT: - - ``root`` -- the root vertex. + - ``root`` -- the root vertex - ``orientation`` -- whether to place the root at the top or at the bottom: diff --git a/src/sage/graphs/graph_plot_js.py b/src/sage/graphs/graph_plot_js.py index 1ce82ff1a44..2c439a56dec 100644 --- a/src/sage/graphs/graph_plot_js.py +++ b/src/sage/graphs/graph_plot_js.py @@ -16,7 +16,7 @@ - ``vertices`` -- each vertex is a dictionary defining : - - ``name`` -- The vertex's label + - ``name`` -- the vertex's label - ``group`` -- the vertex' color (integer) @@ -28,7 +28,7 @@ - ``target`` -- the ID (int) of the edge's destination - - ``color`` -- the edge's color (integer) + - ``color`` -- the edge's color (integer) - ``value`` -- thickness of the edge @@ -40,7 +40,7 @@ center of the edge. It defines the curve of the edge, which can be useful for multigraphs. -- ``pos`` -- a list whose `i` th element is a dictionary defining the position +- ``pos`` -- list whose `i` th element is a dictionary defining the position of the `i` th vertex It also contains the definition of some numerical/boolean variables whose @@ -120,12 +120,12 @@ def gen_html_code(G, - ``vertex_partition`` -- list (default: ``[]``); a list of lists representing a partition of the vertex set. Vertices are then colored in - the graph according to the partition + the graph according to the partition. - - ``vertex_colors`` -- dict (default: ``None``); a dictionary representing a - partition of the vertex set. Keys are colors (ignored) and values are - lists of vertices. Vertices are then colored in the graph according to the - partition + - ``vertex_colors`` -- dictionary (default: ``None``); a dictionary + representing a partition of the vertex set. Keys are colors (ignored) and + values are lists of vertices. Vertices are then colored in the graph + according to the partition. - ``edge_partition`` -- list (default: ``[]``); same as ``vertex_partition``, with edges instead @@ -134,24 +134,24 @@ def gen_html_code(G, previously computed position of nodes into account if there is one, or to compute a spring layout - - ``vertex_size`` -- integer (default: ``7``); the size of a vertex' circle + - ``vertex_size`` -- integer (default: 7); the size of a vertex' circle - - ``edge_thickness`` -- integer (default: ``4``); thickness of an edge + - ``edge_thickness`` -- integer (default: 4); thickness of an edge - - ``charge`` -- integer (default: ``-120``); the vertices' charge. Defines + - ``charge`` -- integer (default: -120); the vertices' charge. Defines how they repulse each other. See ``_ for more information - - ``link_distance`` -- integer (default: ``30``); see + - ``link_distance`` -- integer (default: 30); see ``_ for more information - - ``link_strength`` -- integer (default: ``2``); see + - ``link_strength`` -- integer (default: 2); see ``_ for more information - - ``gravity`` -- float (default: ``0.04``); see + - ``gravity`` -- float (default: 0.04); see ``_ for more information @@ -165,15 +165,15 @@ def gen_html_code(G, EXAMPLES:: - sage: graphs.RandomTree(50).show(method="js") # optional - internet + sage: graphs.RandomTree(50).show(method='js') # optional - internet sage: g = graphs.PetersenGraph() - sage: g.show(method="js", vertex_partition=g.coloring()) # optional - internet + sage: g.show(method='js', vertex_partition=g.coloring()) # optional - internet - sage: graphs.DodecahedralGraph().show(method="js", # optional - internet + sage: graphs.DodecahedralGraph().show(method='js', # optional - internet ....: force_spring_layout=True) - sage: graphs.DodecahedralGraph().show(method="js") # optional - internet + sage: graphs.DodecahedralGraph().show(method='js') # optional - internet sage: # needs sage.combinat sage: g = digraphs.DeBruijn(2, 2) @@ -183,7 +183,7 @@ def gen_html_code(G, sage: g.add_edge("10", "10", "c") sage: g.add_edge("10", "10", "d") sage: g.add_edge("01", "11", "1") - sage: g.show(method="js", vertex_labels=True, edge_labels=True, # optional - internet + sage: g.show(method='js', vertex_labels=True, edge_labels=True, # optional - internet ....: link_distance=200, gravity=.05, charge=-500, ....: edge_partition=[[("11", "12", "2"), ("21", "21", "a")]], ....: edge_thickness=4) diff --git a/src/sage/graphs/hyperbolicity.pyx b/src/sage/graphs/hyperbolicity.pyx index 440a82de3d1..c24c8d3334f 100644 --- a/src/sage/graphs/hyperbolicity.pyx +++ b/src/sage/graphs/hyperbolicity.pyx @@ -273,13 +273,13 @@ cdef tuple hyperbolicity_basic_algorithm(int N, INPUT: - - ``N`` -- number of vertices of the graph. + - ``N`` -- number of vertices of the graph - ``distances`` -- path distance matrix (see the distance_all_pairs - module). + module) - ``verbose`` -- boolean (default: ``False``); set to ``True`` to display - some information during execution. + some information during execution OUTPUT: @@ -291,7 +291,6 @@ cdef tuple hyperbolicity_basic_algorithm(int N, - ``certificate`` -- 4-tuple of vertices maximizing the value `h`. If no such 4-tuple is found, the empty list [] is returned. - """ cdef int a, b, c, d, hh, h_LB cdef list certificate @@ -510,14 +509,14 @@ cdef inline pair** sort_pairs(uint32_t N, OUTPUT: - - ``nb_p`` -- the number of pairs to be included; + - ``nb_p`` -- the number of pairs to be included; - - ``nb_pairs_of_length`` -- an array containing in position k the number - of pairs (i,j) that are included and such that values[i][j] = k. + - ``nb_pairs_of_length`` -- an array containing in position k the number + of pairs (i,j) that are included and such that values[i][j] = k - - ``pairs_of_length`` -- this function returns this array, containing in - position k a pointer to the first included pair (i,j) such that - values[i][j] = k. + - ``pairs_of_length`` -- this function returns this array, containing in + position k a pointer to the first included pair (i,j) such that + values[i][j] = k. """ # pairs_of_length[d] is the list of pairs of vertices at distance d cdef pair** pairs_of_length = check_allocarray(D + 1, sizeof(pair*)) @@ -600,20 +599,20 @@ cdef tuple hyperbolicity_BCCM(int N, - ``distances`` -- path distance matrix - ``far_apart_pairs`` -- 0/1 matrix of far-apart pairs. Pair ``(i,j)`` is - far-apart if ``far_apart_pairs[i][j]\neq 0``. + far-apart if ``far_apart_pairs[i][j]\neq 0`` - ``D`` -- diameter of the graph - ``h_LB`` -- lower bound on the hyperbolicity - - ``approximation_factor`` -- When the approximation factor is set to some + - ``approximation_factor`` -- when the approximation factor is set to some value larger than 1.0, the function stop computations as soon as the ratio between the upper bound and the best found solution is less than the approximation factor. When the approximation factor is 1.0, the problem is solved optimally. - - ``additive_gap`` -- When sets to a positive number, the function stop - computations as soon as the difference between the upper bound and the + - ``additive_gap`` -- when set to a positive number, the function stop + computations as soon as the difference between the upper bound and the best found solution is less than additive gap. When the gap is 0.0, the problem is solved optimally. @@ -624,18 +623,18 @@ cdef tuple hyperbolicity_BCCM(int N, This function returns a tuple ( h, certificate, h_UB ), where: - - ``h`` -- is an integer. When 4-tuples with hyperbolicity larger or equal + - ``h`` -- integer; when 4-tuples with hyperbolicity larger or equal to `h_LB are found, h is the maximum computed value and so twice the hyperbolicity of the graph. If no such 4-tuple is found, it returns -1. - - ``certificate`` -- is a list of vertices. When 4-tuples with + - ``certificate`` -- is a list of vertices; when 4-tuples with hyperbolicity larger that h_LB are found, certificate is the list of the 4 vertices for which the maximum value (and so the hyperbolicity of the graph) has been computed. If no such 4-tuple is found, it returns the empty list []. - - ``h_UB`` -- is an integer equal to the proven upper bound for `h`. When - ``h == h_UB``, the returned solution is optimal. + - ``h_UB`` -- integer equal to the proven upper bound for `h`; when + ``h == h_UB``, the returned solution is optimal """ cdef MemoryAllocator mem = MemoryAllocator() cdef int h = 0, hh # can get negative value @@ -858,42 +857,42 @@ cdef tuple hyperbolicity_CCL(int N, - ``distances`` -- path distance matrix - ``far_apart_pairs`` -- 0/1 matrix of far-apart pairs. Pair ``(i,j)`` is - far-apart if ``far_apart_pairs[i][j]\neq 0``. + far-apart if ``far_apart_pairs[i][j]\neq 0`` - ``D`` -- diameter of the graph - ``h_LB`` -- lower bound on the hyperbolicity - - ``approximation_factor`` -- When the approximation factor is set to some + - ``approximation_factor`` -- when the approximation factor is set to some value larger than 1.0, the function stop computations as soon as the ratio between the upper bound and the best found solution is less than the approximation factor. When the approximation factor is 1.0, the problem is solved optimally. - - ``additive_gap`` -- When sets to a positive number, the function stop - computations as soon as the difference between the upper bound and the + - ``additive_gap`` -- when set to a positive number, the function stop + computations as soon as the difference between the upper bound and the best found solution is less than additive gap. When the gap is 0.0, the problem is solved optimally. - - ``verbose`` -- (default: ``False``) is boolean set to ``True`` to display + - ``verbose`` -- boolean (default: ``False``); set to ``True`` to display some information during execution OUTPUT: This function returns a tuple ( h, certificate, h_UB ), where: - - ``h`` -- is an integer. When 4-tuples with hyperbolicity larger or equal + - ``h`` -- integer; when 4-tuples with hyperbolicity larger or equal to `h_LB are found, h is the maximum computed value and so twice the hyperbolicity of the graph. If no such 4-tuple is found, it returns -1. - - ``certificate`` -- is a list of vertices. When 4-tuples with + - ``certificate`` -- is a list of vertices; when 4-tuples with hyperbolicity larger that h_LB are found, certificate is the list of the 4 vertices for which the maximum value (and so the hyperbolicity of the graph) has been computed. If no such 4-tuple is found, it returns the empty list []. - - ``h_UB`` -- is an integer equal to the proven upper bound for `h`. When - ``h == h_UB``, the returned solution is optimal. + - ``h_UB`` -- integer equal to the proven upper bound for `h`; when + ``h == h_UB``, the returned solution is optimal """ cdef int hh # can get negative value cdef int a, b, c, d, h, h_UB @@ -1072,7 +1071,7 @@ def hyperbolicity(G, - ``G`` -- a connected Graph - - ``algorithm`` -- (default: ``'BCCM'``); specifies the algorithm to use + - ``algorithm`` -- (default: ``'BCCM'``) specifies the algorithm to use among: - ``'basic'`` is an exhaustive algorithm considering all possible @@ -1098,30 +1097,30 @@ def hyperbolicity(G, The ``additive_gap`` and ``approximation_factor`` parameters cannot be used in combination with this method and so are ignored. - - ``approximation_factor`` -- (default: None) When the approximation factor + - ``approximation_factor`` -- (default: ``None``) when the approximation factor is set to some value (larger than 1.0), the function stop computations as soon as the ratio between the upper bound and the best found solution is less than the approximation factor. When the approximation factor is 1.0, the problem is solved optimally. This parameter is used only when the chosen algorithm is ``'CCL'``, ``'CCL+FA'``, or ``'BCCM'``. - - ``additive_gap`` -- (default: None) When sets to a positive number, the + - ``additive_gap`` -- (default: ``None``) when set to a positive number, the function stop computations as soon as the difference between the upper bound and the best found solution is less than additive gap. When the gap is 0.0, the problem is solved optimally. This parameter is used only when the chosen algorithm is ``'CCL'`` or ``'CCL+FA'``, or ``'BCCM'``. - - ``verbose`` -- (default: ``False``) is a boolean set to True to display + - ``verbose`` -- boolean (default: ``False``); set to ``True`` to display some information during execution: new upper and lower bounds, etc. OUTPUT: This function returns the tuple ( delta, certificate, delta_UB ), where: - - ``delta`` -- the hyperbolicity of the graph (half-integer value). + - ``delta`` -- the hyperbolicity of the graph (half-integer value) - ``certificate`` -- is the list of the 4 vertices for which the maximum - value has been computed, and so the hyperbolicity of the graph. + value has been computed, and so the hyperbolicity of the graph - ``delta_UB`` -- is an upper bound for ``delta``. When ``delta == delta_UB``, the returned solution is optimal. Otherwise, the approximation @@ -1493,8 +1492,8 @@ cdef dict __hyperbolicity_distribution__(int N, unsigned short** distances): OUTPUT: - - ``hdict`` -- A dictionary such that hdict[i] is the number of 4-tuples of - hyperbolicity i among the considered 4-tuples. + - ``hdict`` -- dictionary such that hdict[i] is the number of 4-tuples of + hyperbolicity i among the considered 4-tuples """ # We initialize the table of hyperbolicity. We use an array of unsigned long # int instead of a dictionary since it is much faster. @@ -1549,12 +1548,12 @@ cdef dict __hyperbolicity_sampling__(int N, unsigned short** distances, uint64_t - ``distances`` -- matrix of distances in the graph - - ``sampling_size`` -- number of 4-tuples considered. Default value is 1000. + - ``sampling_size`` -- number of 4-tuples considered. Default value is 1000 OUTPUT: - - ``hdict`` -- A dictionary such that hdict[i] is the number of 4-tuples of - hyperbolicity i among the considered 4-tuples. + - ``hdict`` -- dictionary such that hdict[i] is the number of 4-tuples of + hyperbolicity i among the considered 4-tuples """ cdef int i, a, b, c, d cdef uint64_t j @@ -1608,21 +1607,21 @@ def hyperbolicity_distribution(G, algorithm='sampling', sampling_size=10**6): INPUT: - - ``G`` -- a Graph. + - ``G`` -- a Graph - - ``algorithm`` -- (default: 'sampling') When algorithm is 'sampling', it + - ``algorithm`` -- (default: ``'sampling'``) when algorithm is 'sampling', it returns the distribution of the hyperbolicity over a sample of ``sampling_size`` 4-tuples. When algorithm is 'exact', it computes the distribution of the hyperbolicity over all 4-tuples. Be aware that the computation time can be HUGE. - ``sampling_size`` -- (default: `10^6`) number of 4-tuples considered in - the sampling. Used only when ``algorithm == 'sampling'``. + the sampling. Used only when ``algorithm == 'sampling'`` OUTPUT: - - ``hdict`` -- A dictionary such that hdict[i] is the number of 4-tuples of - hyperbolicity i. + - ``hdict`` -- dictionary such that hdict[i] is the number of 4-tuples of + hyperbolicity i EXAMPLES: diff --git a/src/sage/graphs/hypergraph_generators.py b/src/sage/graphs/hypergraph_generators.py index 642bb3f98e3..b4bae7292cf 100644 --- a/src/sage/graphs/hypergraph_generators.py +++ b/src/sage/graphs/hypergraph_generators.py @@ -44,40 +44,40 @@ def nauty(self, number_of_sets, number_of_vertices, regular=False, uniform=False, max_intersection=None, connected=False, - debug=False, options=""): + debug=False, options=''): r""" Enumerate hypergraphs up to isomorphism using Nauty. INPUT: - - ``number_of_sets`` -- integer, at most 64 minus ``number_of_vertices`` + - ``number_of_sets`` -- integer; at most 64 minus ``number_of_vertices`` - - ``number_of_vertices`` -- integer, at most 30 + - ``number_of_vertices`` -- integer; at most 30 - ``multiple_sets`` -- boolean (default: ``False``); whether to allow - several sets of the hypergraph to be equal. + several sets of the hypergraph to be equal - ``vertex_min_degree``, ``vertex_max_degree`` -- integers (default: ``None``); define the maximum and minimum degree of an element from - the ground set (i.e. the number of sets which contain it). + the ground set (i.e. the number of sets which contain it) - ``set_min_size``, ``set_max_size`` -- integers (default: ``None``); - define the maximum and minimum size of a set. + define the maximum and minimum size of a set - - ``regular`` -- integers (default: ``False``); if set to an integer + - ``regular`` -- integer (default: ``False``); if set to an integer value `k`, requires the hypergraphs to be `k`-regular. It is actually a shortcut for the corresponding min/max values. - - ``uniform`` -- integers (default: ``False``); if set to an integer + - ``uniform`` -- integer (default: ``False``); if set to an integer value `k`, requires the hypergraphs to be `k`-uniform. It is actually a shortcut for the corresponding min/max values. - - ``max_intersection`` -- integers (default: ``None``); constraints the + - ``max_intersection`` -- integer (default: ``None``); constraints the maximum cardinality of the intersection of two sets from the - hypergraphs. + hypergraphs - ``connected`` -- boolean (default: ``False``); whether to require the - hypergraphs to be connected. + hypergraphs to be connected - ``debug`` -- boolean (default: ``False``); if ``True`` the first line of genbgL's output to standard error is captured and the first call to @@ -86,7 +86,7 @@ def nauty(self, number_of_sets, number_of_vertices, program with some information on the arguments, while a line beginning with ">E" indicates an error with the input. - - ``options`` -- string (default: ``""``) -- anything else that should + - ``options`` -- string (default: ``''``); anything else that should be forwarded as input to Nauty's genbgL. See its documentation for more information : ``_. @@ -95,9 +95,7 @@ def nauty(self, number_of_sets, number_of_vertices, For genbgL the *first class* elements are vertices, and *second class* elements are the hypergraph's sets. - OUTPUT: - - A tuple of tuples. + OUTPUT: a tuple of tuples EXAMPLES: @@ -248,7 +246,7 @@ def UniformRandomUniform(self, n, k, m): sage: hypergraphs.UniformRandomUniform(-52, 3, 17) Traceback (most recent call last): ... - ValueError: number of vertices should be non-negative + ValueError: number of vertices should be nonnegative sage: hypergraphs.UniformRandomUniform(52.9, 3, 17) Traceback (most recent call last): ... @@ -256,7 +254,7 @@ def UniformRandomUniform(self, n, k, m): sage: hypergraphs.UniformRandomUniform(52, -3, 17) Traceback (most recent call last): ... - ValueError: the uniformity should be non-negative + ValueError: the uniformity should be nonnegative sage: hypergraphs.UniformRandomUniform(52, I, 17) # needs sage.symbolic Traceback (most recent call last): ... @@ -268,7 +266,7 @@ def UniformRandomUniform(self, n, k, m): # Construct the vertex set if n < 0: - raise ValueError("number of vertices should be non-negative") + raise ValueError("number of vertices should be nonnegative") try: nverts = Integer(n) except TypeError: @@ -277,7 +275,7 @@ def UniformRandomUniform(self, n, k, m): # Construct the edge set if k < 0: - raise ValueError("the uniformity should be non-negative") + raise ValueError("the uniformity should be nonnegative") try: uniformity = Integer(k) except TypeError: @@ -325,7 +323,7 @@ def BinomialRandomUniform(self, n, k, p): sage: hypergraphs.BinomialRandomUniform(-50, 3, 0.17) Traceback (most recent call last): ... - ValueError: number of vertices should be non-negative + ValueError: number of vertices should be nonnegative sage: hypergraphs.BinomialRandomUniform(50.9, 3, 0.17) Traceback (most recent call last): ... @@ -333,7 +331,7 @@ def BinomialRandomUniform(self, n, k, p): sage: hypergraphs.BinomialRandomUniform(50, -3, 0.17) Traceback (most recent call last): ... - ValueError: the uniformity should be non-negative + ValueError: the uniformity should be nonnegative sage: hypergraphs.BinomialRandomUniform(50, I, 0.17) Traceback (most recent call last): ... @@ -341,13 +339,13 @@ def BinomialRandomUniform(self, n, k, p): """ from sage.rings.integer import Integer if n < 0: - raise ValueError("number of vertices should be non-negative") + raise ValueError("number of vertices should be nonnegative") try: nverts = Integer(n) except TypeError: raise ValueError("number of vertices should be an integer") if k < 0: - raise ValueError("the uniformity should be non-negative") + raise ValueError("the uniformity should be nonnegative") try: uniformity = Integer(k) except TypeError: diff --git a/src/sage/graphs/independent_sets.pyx b/src/sage/graphs/independent_sets.pyx index ad761878d06..c880d9df424 100644 --- a/src/sage/graphs/independent_sets.pyx +++ b/src/sage/graphs/independent_sets.pyx @@ -40,10 +40,10 @@ cdef class IndependentSets: - ``G`` -- a graph - ``maximal`` -- boolean (default: ``False``); whether to only consider - (inclusionwise) maximal independent sets. + (inclusionwise) maximal independent sets - ``complement`` -- boolean (default: ``False``); whether to consider the - graph's complement (i.e. cliques instead of independent sets). + graph's complement (i.e. cliques instead of independent sets) ALGORITHM: @@ -129,7 +129,7 @@ cdef class IndependentSets: """ def __init__(self, G, maximal=False, complement=False): r""" - Constructor for this class + Constructor for this class. TESTS:: @@ -330,11 +330,11 @@ cdef class IndependentSets: def __contains__(self, S): r""" - Check whether the set is an independent set (possibly maximal) + Check whether the set is an independent set (possibly maximal). INPUT: - - ``S`` -- a set of vertices to be tested. + - ``S`` -- set of vertices to be tested TESTS: diff --git a/src/sage/graphs/isgci.py b/src/sage/graphs/isgci.py index 2315ea4679d..abbab8fac9b 100644 --- a/src/sage/graphs/isgci.py +++ b/src/sage/graphs/isgci.py @@ -293,7 +293,7 @@ What ISGCI knows is that perfect graphs contain unimodular graph which contain bipartite graphs. Therefore bipartite graphs are perfect ! -.. note:: +.. NOTE:: The inclusion digraph is **NOT ACYCLIC**. Indeed, several entries exist in the ISGCI database which represent the same graph class, for instance @@ -655,7 +655,7 @@ def get_class(self, id): INPUT: - - ``id`` (string) -- the desired class' ID + - ``id`` -- string; the desired class' ID .. SEEALSO:: @@ -719,9 +719,7 @@ def inclusions(self): r""" Return the graph class inclusions. - OUTPUT: - - a list of dictionaries + OUTPUT: list of dictionaries Upon the first call, this loads the database from the local XML file. Subsequent calls are cached. @@ -799,7 +797,7 @@ def _download_db(self): data_dir = os.path.dirname(DatabaseGraphs().absolute_filename()) u = urlopen('https://www.graphclasses.org/data.zip', context=default_context()) - with tempfile.NamedTemporaryFile(suffix=".zip") as f: + with tempfile.NamedTemporaryFile(suffix='.zip') as f: f.write(u.read()) z = zipfile.ZipFile(f.name) @@ -849,7 +847,7 @@ def _parse_db(self): def update_db(self): r""" - Updates the ISGCI database by downloading the latest version from + Update the ISGCI database by downloading the latest version from internet. This method downloads the ISGCI database from the website @@ -877,7 +875,7 @@ def update_db(self): def _get_ISGCI(self): r""" - Returns the contents of the ISGCI database. + Return the contents of the ISGCI database. This method is mostly for internal use, but often provides useful information during debugging operations. @@ -901,7 +899,7 @@ def _get_ISGCI(self): def show_all(self): r""" - Prints all graph classes stored in ISGCI + Print all graph classes stored in ISGCI. EXAMPLES:: @@ -974,11 +972,9 @@ def _XML_to_dict(root): INPUT: - - ``root`` -- an ``xml.etree.cElementTree.ElementTree`` object. - - OUTPUT: + - ``root`` -- an ``xml.etree.cElementTree.ElementTree`` object - A dictionary representing the XML data. + OUTPUT: a dictionary representing the XML data EXAMPLES:: diff --git a/src/sage/graphs/line_graph.pyx b/src/sage/graphs/line_graph.pyx index 796e15d44ab..e54caf52897 100644 --- a/src/sage/graphs/line_graph.pyx +++ b/src/sage/graphs/line_graph.pyx @@ -134,7 +134,7 @@ def is_line_graph(g, certificate=False): INPUT: - - ``certificate`` (boolean) -- whether to return a certificate along with + - ``certificate`` -- boolean; whether to return a certificate along with the boolean result. Here is what happens when ``certificate = True``: - If the graph is not a line graph, the method returns a pair ``(b, @@ -293,12 +293,12 @@ def line_graph(g, labels=True): .. SEEALSO:: - - The :mod:`line_graph ` module. + - The :mod:`line_graph ` module - :meth:`~sage.graphs.graph_generators.GraphGenerators.line_graph_forbidden_subgraphs` - -- the forbidden subgraphs of a line graph. + -- the forbidden subgraphs of a line graph - - :meth:`~Graph.is_line_graph` -- tests whether a graph is a line graph. + - :meth:`~Graph.is_line_graph` -- tests whether a graph is a line graph EXAMPLES:: @@ -421,7 +421,7 @@ def root_graph(g, verbose=False): - ``g`` -- a graph - ``verbose`` -- boolean (default: ``False``); display some information - about what is happening inside of the algorithm. + about what is happening inside of the algorithm .. WARNING:: diff --git a/src/sage/graphs/matchpoly.pyx b/src/sage/graphs/matchpoly.pyx index b289679d7b2..4fe8549ad6c 100644 --- a/src/sage/graphs/matchpoly.pyx +++ b/src/sage/graphs/matchpoly.pyx @@ -10,7 +10,7 @@ This module contains the following methods: :widths: 30, 70 :delim: | - :meth:`matching_polynomial` | Computes the matching polynomial of a given graph + :meth:`matching_polynomial` | Compute the matching polynomial of a given graph. :meth:`complete_poly` | Compute the matching polynomial of the complete graph on `n` vertices. AUTHORS: @@ -53,7 +53,7 @@ x = polygen(ZZ, 'x') def matching_polynomial(G, complement=True, name=None): r""" - Computes the matching polynomial of the graph `G`. + Compute the matching polynomial of the graph `G`. If `p(G, k)` denotes the number of `k`-matchings (matchings with `k` edges) in `G`, then the matching polynomial is defined as [God1993]_: @@ -64,11 +64,11 @@ def matching_polynomial(G, complement=True, name=None): INPUT: - - ``complement`` -- (default: ``True``) whether to use Godsil's duality + - ``complement`` -- boolean (default: ``True``); whether to use Godsil's duality theorem to compute the matching polynomial from that of the graphs - complement (see ALGORITHM). + complement (see ALGORITHM) - - ``name`` -- optional string for the variable name in the polynomial + - ``name`` -- (optional) string for the variable name in the polynomial .. NOTE:: diff --git a/src/sage/graphs/mcqd.pyx b/src/sage/graphs/mcqd.pyx index 1399a8d6257..6e6be4389cc 100644 --- a/src/sage/graphs/mcqd.pyx +++ b/src/sage/graphs/mcqd.pyx @@ -7,11 +7,11 @@ from memory_allocator cimport MemoryAllocator def mcqd(G): """ - Computes the max clique using MCQD + Compute the max clique using MCQD. INPUT: - - ``G`` -- A graph + - ``G`` -- a graph TESTS:: diff --git a/src/sage/graphs/orientations.py b/src/sage/graphs/orientations.py index 923ed9d2874..2dac79b7146 100644 --- a/src/sage/graphs/orientations.py +++ b/src/sage/graphs/orientations.py @@ -61,11 +61,9 @@ def acyclic_orientations(G): INPUT: - - ``G`` -- an undirected graph. + - ``G`` -- an undirected graph - OUTPUT: - - - An iterator over all acyclic orientations of the input graph. + OUTPUT: an iterator over all acyclic orientations of the input graph .. NOTE:: @@ -125,7 +123,6 @@ def acyclic_orientations(G): sage: len(list(Graph([(0, 1), (1, 2), (2, 0)]).acyclic_orientations())) 6 - """ if not G.size(): # A graph without edge cannot be oriented @@ -326,11 +323,9 @@ def strong_orientations_iterator(G): INPUT: - - ``G`` -- an undirected graph. + - ``G`` -- an undirected graph - OUTPUT: - - - an iterator which will produce all strong orientations of this graph. + OUTPUT: an iterator which will produce all strong orientations of this graph .. NOTE:: @@ -447,17 +442,15 @@ def _strong_orientations_of_a_mixed_graph(Dg, V, E): INPUT: - - ``Dg`` -- the mixed graph. The undirected edges are doubly oriented. + - ``Dg`` -- the mixed graph. The undirected edges are doubly oriented - ``V`` -- the set of vertices - ``E`` -- the set of undirected edges (they are oriented in both ways); - No labels are allowed. - - OUTPUT: + no labels are allowed - - an iterator which will produce all strong orientations of the input - partially directed graph. + OUTPUT: an iterator which will produce all strong orientations of the input + partially directed graph EXAMPLES:: @@ -524,7 +517,7 @@ def random_orientation(G): INPUT: - - ``G`` -- a Graph. + - ``G`` -- a Graph EXAMPLES:: diff --git a/src/sage/graphs/partial_cube.py b/src/sage/graphs/partial_cube.py index 79b1edc957c..7512f5acd1f 100644 --- a/src/sage/graphs/partial_cube.py +++ b/src/sage/graphs/partial_cube.py @@ -23,7 +23,7 @@ **Tokens** and their **action**: in the terminology of [Epp2008]_, a token represents a transition of the form: - *switch the k-th bit of the binary string from 0 to 1* + *switch the `k`-th bit of the binary string from 0 to 1* Each token can be matched with a 'reversed' token that performs the same switch in the opposite direction. Alternatively, a token can be @@ -104,9 +104,9 @@ def breadth_first_level_search(G, start): INPUT: - - ``G`` -- a graph to perform the search on. + - ``G`` -- a graph to perform the search on - - ``start`` -- vertex or list of vertices from which to start the traversal. + - ``start`` -- vertex or list of vertices from which to start the traversal EXAMPLES:: @@ -120,7 +120,6 @@ def breadth_first_level_search(G, start): '20': set(), '21': set(), '22': set()}] - """ neighbors = G.neighbor_out_iterator visited = set() @@ -150,9 +149,9 @@ def depth_first_traversal(G, start): INPUT: - - ``G`` -- a graph to perform the search on. + - ``G`` -- a graph to perform the search on - - ``start`` -- vertex or list of vertices from which to start the traversal. + - ``start`` -- vertex or list of vertices from which to start the traversal OUTPUT: diff --git a/src/sage/graphs/path_enumeration.pyx b/src/sage/graphs/path_enumeration.pyx index d9f12035528..50b992692e4 100644 --- a/src/sage/graphs/path_enumeration.pyx +++ b/src/sage/graphs/path_enumeration.pyx @@ -57,7 +57,7 @@ def all_paths(G, start, end, use_multiedges=False, report_edges=False, labels=Fa - ``end`` -- a vertex of a graph, where to end - ``use_multiedges`` -- boolean (default: ``False``); this parameter is - used only if the graph has multiple edges. + used only if the graph has multiple edges - If ``False``, the graph is considered as simple and an edge label is arbitrarily selected for each edge as in @@ -203,7 +203,6 @@ def all_paths(G, start, end, use_multiedges=False, report_edges=False, labels=Fa [[(0, 3), (3, 5)]] sage: G.all_paths(0, 5, report_edges=True, use_multiedges=True) [[(0, 3), (3, 5)], [(0, 3), (3, 5)]] - """ if start not in G: raise LookupError("start vertex ({0}) is not a vertex of the graph".format(start)) @@ -320,15 +319,15 @@ def shortest_simple_paths(self, source, target, weight_function=None, in the graph are weighted, otherwise all edges have weight 1 - ``check_weight`` -- boolean (default: ``True``); whether to check that the - ``weight_function`` outputs a number for each edge. + ``weight_function`` outputs a number for each edge - ``algorithm`` -- string (default: ``None``); the algorithm to use in computing ``k`` shortest paths of ``self``. The following algorithms are supported: - - ``"Yen"`` -- Yen's algorithm [Yen1970]_ + - ``'Yen'`` -- Yen's algorithm [Yen1970]_ - - ``"Feng"`` -- an improved version of Yen's algorithm but that works only + - ``'Feng'`` -- an improved version of Yen's algorithm but that works only for directed graphs [Feng2014]_ - ``report_edges`` -- boolean (default: ``False``); whether to report paths @@ -347,9 +346,9 @@ def shortest_simple_paths(self, source, target, weight_function=None, sage: g = DiGraph([(1, 2, 20), (1, 3, 10), (1, 4, 30), ....: (2, 5, 20), (3, 5, 10), (4, 5, 30)]) - sage: list(g.shortest_simple_paths(1, 5, by_weight=True, algorithm="Yen")) + sage: list(g.shortest_simple_paths(1, 5, by_weight=True, algorithm='Yen')) [[1, 3, 5], [1, 2, 5], [1, 4, 5]] - sage: list(g.shortest_simple_paths(1, 5, algorithm="Yen")) + sage: list(g.shortest_simple_paths(1, 5, algorithm='Yen')) [[1, 2, 5], [1, 3, 5], [1, 4, 5]] sage: list(g.shortest_simple_paths(1, 1)) [[1]] @@ -358,21 +357,21 @@ def shortest_simple_paths(self, source, target, weight_function=None, [(20, [(1, 3, 10), (3, 5, 10)]), (40, [(1, 2, 20), (2, 5, 20)]), (60, [(1, 4, 30), (4, 5, 30)])] - sage: list(g.shortest_simple_paths(1, 5, by_weight=True, algorithm="Feng", + sage: list(g.shortest_simple_paths(1, 5, by_weight=True, algorithm='Feng', ....: report_edges=True, report_weight=True)) [(20, [(1, 3), (3, 5)]), (40, [(1, 2), (2, 5)]), (60, [(1, 4), (4, 5)])] sage: list(g.shortest_simple_paths(1, 5, report_edges=True, report_weight=True)) [(2, [(1, 4), (4, 5)]), (2, [(1, 3), (3, 5)]), (2, [(1, 2), (2, 5)])] sage: list(g.shortest_simple_paths(1, 5, by_weight=True, report_edges=True)) [[(1, 3), (3, 5)], [(1, 2), (2, 5)], [(1, 4), (4, 5)]] - sage: list(g.shortest_simple_paths(1, 5, by_weight=True, algorithm="Feng", + sage: list(g.shortest_simple_paths(1, 5, by_weight=True, algorithm='Feng', ....: report_edges=True, labels=True)) [[(1, 3, 10), (3, 5, 10)], [(1, 2, 20), (2, 5, 20)], [(1, 4, 30), (4, 5, 30)]] sage: g = Graph([(1, 2, 20), (1, 3, 10), (1, 4, 30), (2, 5, 20), ....: (3, 5, 10), (4, 5, 30), (1, 6, 100), (5, 6, 5)]) sage: list(g.shortest_simple_paths(1, 6, by_weight = True)) [[1, 3, 5, 6], [1, 2, 5, 6], [1, 4, 5, 6], [1, 6]] - sage: list(g.shortest_simple_paths(1, 6, algorithm="Yen")) + sage: list(g.shortest_simple_paths(1, 6, algorithm='Yen')) [[1, 6], [1, 2, 5, 6], [1, 3, 5, 6], [1, 4, 5, 6]] sage: list(g.shortest_simple_paths(1, 6, ....: report_edges=True, report_weight=True, labels=True)) @@ -404,7 +403,7 @@ def shortest_simple_paths(self, source, target, weight_function=None, ....: (5, 6, 100), (4, 7, 3), (7, 6, 4), (3, 8, 5), ....: (8, 9, 2), (9, 6, 2), (9, 10, 7), (9, 11, 10), ....: (11, 6, 8), (10, 6, 2)]) - sage: list(g.shortest_simple_paths(1, 6, algorithm="Yen", by_weight=True)) + sage: list(g.shortest_simple_paths(1, 6, algorithm='Yen', by_weight=True)) [[1, 2, 3, 4, 7, 6], [1, 2, 3, 8, 9, 6], [1, 2, 3, 8, 9, 10, 6], @@ -422,7 +421,7 @@ def shortest_simple_paths(self, source, target, weight_function=None, (18, [(1, 2, 1), (2, 3, 1), (3, 8, 5), (8, 9, 2), (9, 10, 7), (6, 10, 2)]), (27, [(1, 2, 1), (2, 3, 1), (3, 8, 5), (8, 9, 2), (9, 11, 10), (6, 11, 8)]), (105, [(1, 2, 1), (2, 3, 1), (3, 4, 1), (4, 5, 2), (5, 6, 100)])] - sage: list(g.shortest_simple_paths(1, 6, algorithm="Yen")) + sage: list(g.shortest_simple_paths(1, 6, algorithm='Yen')) [[1, 2, 3, 4, 5, 6], [1, 2, 3, 4, 7, 6], [1, 2, 3, 8, 9, 6], @@ -432,7 +431,7 @@ def shortest_simple_paths(self, source, target, weight_function=None, ....: (1, 7, 1), (7, 8, 1), (8, 5, 1), (1, 6, 1), ....: (6, 9, 1), (9, 5, 1), (4, 2, 1), (9, 3, 1), ....: (9, 10, 1), (10, 5, 1), (9, 11, 1), (11, 10, 1)]) - sage: list(g.shortest_simple_paths(1, 5, algorithm="Feng")) + sage: list(g.shortest_simple_paths(1, 5, algorithm='Feng')) [[1, 7, 8, 5], [1, 6, 9, 5], [1, 6, 9, 10, 5], @@ -1189,7 +1188,7 @@ def feng_k_shortest_simple_paths(self, source, target, weight_function=None, cdef dict dist cdef dict successor dist, successor = shortest_paths(reverse_graph, target, weight_function=reverse_weight_function, - algorithm="Dijkstra_Boost") + algorithm='Dijkstra_Boost') # successor is a child node in the shortest path subtree cdef dict reduced_cost = {(e[0], e[1]): weight_function(e) + dist[e[1]] - dist[e[0]] @@ -1400,15 +1399,15 @@ def _all_paths_iterator(self, vertex, ending_vertices=None, two arcs share a head or share a tail, i.e. every vertex in the path is entered at most once and exited at most once. - - ``max_length`` -- non negative integer (default: ``None``); the + - ``max_length`` -- nonnegative integer (default: ``None``); the maximum length of the enumerated paths. If set to ``None``, then all lengths are allowed. - ``trivial`` -- boolean (default: ``False``); if set to ``True``, then - the empty paths are also enumerated. + the empty paths are also enumerated - ``use_multiedges`` -- boolean (default: ``False``); this parameter is - used only if the graph has multiple edges. + used only if the graph has multiple edges - If ``False``, the graph is considered as simple and an edge label is arbitrarily selected for each edge as in @@ -1432,9 +1431,7 @@ def _all_paths_iterator(self, vertex, ending_vertices=None, pass information about edge multiplicities of the graph, if ``None`` edge multiplicity values are computed inside the method. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -1667,15 +1664,15 @@ def all_paths_iterator(self, starting_vertices=None, ending_vertices=None, two arcs share a head or share a tail, i.e. every vertex in the path is entered at most once and exited at most once. - - ``max_length`` -- non negative integer (default: ``None``); the + - ``max_length`` -- nonnegative integer (default: ``None``); the maximum length of the enumerated paths. If set to ``None``, then all lengths are allowed. - ``trivial`` -- boolean (default: ``False``); if set to ``True``, then - the empty paths are also enumerated. + the empty paths are also enumerated - ``use_multiedges`` -- boolean (default: ``False``); this parameter is - used only if the graph has multiple edges. + used only if the graph has multiple edges - If ``False``, the graph is considered as simple and an edge label is arbitrarily selected for each edge as in @@ -1695,9 +1692,7 @@ def all_paths_iterator(self, starting_vertices=None, ending_vertices=None, is simply a pair ``(u, v)`` of vertices. Otherwise a list of edges along with its edge labels are used to represent the path. - OUTPUT: - - iterator + OUTPUT: iterator AUTHOR: @@ -1904,15 +1899,15 @@ def all_simple_paths(self, starting_vertices=None, ending_vertices=None, - ``ending_vertices`` -- iterable (default: ``None``); allowed ending vertices of the paths. If ``None``, then all vertices are allowed. - - ``max_length`` -- non negative integer (default: ``None``); the + - ``max_length`` -- nonnegative integer (default: ``None``); the maximum length of the enumerated paths. If set to ``None``, then all lengths are allowed. - ``trivial`` -- boolean (default: ``False``); if set to ``True``, then - the empty paths are also enumerated. + the empty paths are also enumerated - ``use_multiedges`` -- boolean (default: ``False``); this parameter is - used only if the graph has multiple edges. + used only if the graph has multiple edges - If ``False``, the graph is considered as simple and an edge label is arbitrarily selected for each edge as in @@ -1932,9 +1927,7 @@ def all_simple_paths(self, starting_vertices=None, ending_vertices=None, is simply a pair ``(u, v)`` of vertices. Otherwise a list of edges along with its edge labels are used to represent the path. - OUTPUT: - - list + OUTPUT: list .. NOTE:: diff --git a/src/sage/graphs/planarity.pyx b/src/sage/graphs/planarity.pyx index 987669d97fe..6fd1e2848a6 100644 --- a/src/sage/graphs/planarity.pyx +++ b/src/sage/graphs/planarity.pyx @@ -94,7 +94,6 @@ def is_planar(g, kuratowski=False, set_pos=False, set_embedding=False): ....: assert is_planar(G, set_embedding=set_embedding, set_pos=set_pos) ....: assert (hasattr(G, '_embedding') and G._embedding is not None) == set_embedding, (set_embedding, set_pos) ....: assert (hasattr(G, '_pos') and G._pos is not None) == set_pos, (set_embedding, set_pos) - """ g._scream_if_not_simple() if set_pos and not g.is_connected(): diff --git a/src/sage/graphs/pq_trees.py b/src/sage/graphs/pq_trees.py index fe7b00f415f..998e35fd845 100644 --- a/src/sage/graphs/pq_trees.py +++ b/src/sage/graphs/pq_trees.py @@ -236,11 +236,9 @@ def reorder_sets(sets): INPUT: - - ``sets`` -- a list of instances of ``list, Set`` or ``set`` + - ``sets`` -- list of instances of ``list, Set`` or ``set`` - ALGORITHM: - - PQ-Trees + ALGORITHM: PQ-Trees EXAMPLES: @@ -289,7 +287,7 @@ class PQ: def __init__(self, seq): r""" - Construction of a PQ-Tree + Construction of a PQ-Tree. EXAMPLES:: @@ -313,7 +311,7 @@ def __init__(self, seq): def reverse(self): r""" - Recursively reverses ``self`` and its children + Recursively reverse ``self`` and its children. EXAMPLES:: @@ -333,8 +331,8 @@ def reverse(self): def __contains__(self, v): r""" - Tests whether there exists an element of ``self`` containing - an element ``v`` + Test whether there exists an element of ``self`` containing + an element ``v``. INPUT: @@ -353,7 +351,7 @@ def __contains__(self, v): def __iter__(self): r""" - Iterates over the children of ``self``. + Iterate over the children of ``self``. EXAMPLES:: @@ -369,7 +367,7 @@ def __iter__(self): def number_of_children(self): r""" - Returns the number of children of ``self`` + Return the number of children of ``self``. EXAMPLES:: @@ -382,7 +380,7 @@ def number_of_children(self): def ordering(self): r""" - Returns the current ordering given by listing the leaves from + Return the current ordering given by listing the leaves from left to right. EXAMPLES:: @@ -403,7 +401,7 @@ def ordering(self): def __repr__(self) -> str: r""" - Succinctly represents ``self``. + Succinctly represent ``self``. EXAMPLES:: @@ -416,7 +414,7 @@ def __repr__(self) -> str: def simplify(self, v, left=False, right=False): r""" - Returns a simplified copy of self according to the element ``v`` + Return a simplified copy of ``self`` according to the element ``v``. If ``self`` is a partial P-tree for ``v``, we would like to restrict the permutations of its children to permutations @@ -502,9 +500,9 @@ def simplify(self, v, left=False, right=False): def flatten(self): r""" - Returns a flattened copy of ``self`` + Return a flattened copy of ``self``. - If self has only one child, we may as well consider its + If ``self`` has only one child, we may as well consider its child's children, as ``self`` encodes no information. This method recursively "flattens" trees having only on PQ-tree child, and returns it. @@ -531,7 +529,7 @@ class P(PQ): """ def set_contiguous(self, v): r""" - Updates ``self`` so that the sets containing ``v`` are + Update ``self`` so that the sets containing ``v`` are contiguous for any admissible permutation of its subtrees. INPUT: @@ -540,7 +538,7 @@ def set_contiguous(self, v): OUTPUT: - According to the cases : + According to the cases: * ``(EMPTY, ALIGNED)`` if no set of the tree contains an occurrence of ``v`` @@ -558,7 +556,7 @@ def set_contiguous(self, v): In any case, the sets containing ``v`` are contiguous when this function ends. If there is no possibility of doing so, the function - raises a :class:`ValueError` exception. + raises a :exc:`ValueError` exception. EXAMPLES: @@ -803,14 +801,14 @@ def orderings(self): class Q(PQ): r""" - A Q-Tree is a PQ-Tree whose children are ordered up to reversal + A Q-Tree is a PQ-Tree whose children are ordered up to reversal. For more information, see the documentation of :mod:`sage.graphs.pq_trees`. """ def set_contiguous(self, v): r""" - Updates ``self`` so that the sets containing ``v`` are + Update ``self`` so that the sets containing ``v`` are contiguous for any admissible permutation of its subtrees. INPUT: @@ -819,7 +817,7 @@ def set_contiguous(self, v): OUTPUT: - According to the cases : + According to the cases: * ``(EMPTY, ALIGNED)`` if no set of the tree contains an occurrence of ``v`` @@ -837,7 +835,7 @@ def set_contiguous(self, v): In any case, the sets containing ``v`` are contiguous when this function ends. If there is no possibility of doing so, the function - raises a :class:`ValueError` exception. + raises a :exc:`ValueError` exception. EXAMPLES: @@ -1104,7 +1102,7 @@ def cardinality(self): def orderings(self): r""" - Iterates over all orderings of the sets allowed by the structure + Iterate over all orderings of the sets allowed by the structure. .. SEEALSO:: diff --git a/src/sage/graphs/schnyder.py b/src/sage/graphs/schnyder.py index b22ab6d3302..636798ee2ea 100644 --- a/src/sage/graphs/schnyder.py +++ b/src/sage/graphs/schnyder.py @@ -41,12 +41,10 @@ def _triangulate(g, comb_emb): INPUT: - - g -- the graph to triangulate + - ``g`` -- the graph to triangulate - ``comb_emb`` -- a planar combinatorial embedding of g - OUTPUT: - - A list of edges that are added to the graph (in place) + OUTPUT: a list of edges that are added to the graph (in place) EXAMPLES:: @@ -153,13 +151,11 @@ def _normal_label(g, comb_emb, external_face): INPUT: - - g -- the graph to find the normal labeling of (g must be triangulated) + - ``g`` -- the graph to find the normal labeling of (g must be triangulated) - ``comb_emb`` -- a planar combinatorial embedding of g - ``external_face`` -- the list of three edges in the external face of g - OUTPUT: - - x -- tuple with entries + OUTPUT: x; tuple with entries x[0] = dict of dicts of normal labeling for each vertex of g and each adjacent neighbors u,v (u < v) of vertex: @@ -368,8 +364,8 @@ def _realizer(g, x, example=False): INPUT: - - g -- the graph to compute the realizer of - - x -- tuple with entries + - ``g`` -- the graph to compute the realizer of + - ``x`` -- tuple with entries x[0] = dict of dicts representing a normal labeling of g. For each vertex of g and each adjacent neighbors u,v (u < v) of @@ -378,9 +374,7 @@ def _realizer(g, x, example=False): x[1] = (v1, v2, v3) tuple of the three external vertices (also the roots of each tree) - OUTPUT: - - - x -- tuple with entries + OUTPUT: x; tuple with entries x[0] = dict of lists of TreeNodes: @@ -402,7 +396,6 @@ def _realizer(g, x, example=False): sage: _realizer(g, tn) ({0: []}, (1, 0, 2)) - """ normal_labeling, (v1, v2, v3) = x realizer = DiGraph() @@ -465,8 +458,8 @@ def _compute_coordinates(g, x): INPUT: - - g -- the graph to compute the coordinates of - - x -- tuple with entries + - ``g`` -- the graph to compute the coordinates of + - ``x`` -- tuple with entries x[0] = dict of tree nodes for the three trees with each external vertex as root: @@ -566,7 +559,7 @@ class TreeNode: INPUT: - ``parent`` -- the parent TreeNode of ``self`` - - ``children`` -- a list of TreeNode children of ``self`` + - ``children`` -- list of TreeNode children of ``self`` - ``label`` -- the associated realizer vertex label EXAMPLES:: @@ -591,7 +584,7 @@ def __init__(self, parent=None, children=None, label=None): INPUT: - ``parent`` -- the parent TreeNode of ``self`` - - ``children`` -- a list of TreeNode children of ``self`` + - ``children`` -- list of TreeNode children of ``self`` - ``label`` -- the associated realizer vertex label EXAMPLES:: @@ -620,9 +613,9 @@ def __init__(self, parent=None, children=None, label=None): def compute_number_of_descendants(self): """ - Computes the number of descendants of self and all descendants. + Compute the number of descendants of ``self`` and all descendants. - For each TreeNode, sets result as attribute self.number_of_descendants + For each TreeNode, sets result as attribute ``self.number_of_descendants``. EXAMPLES:: @@ -640,7 +633,6 @@ def compute_number_of_descendants(self): sage: tn.compute_depth_of_self_and_children() sage: tn3.depth 2 - """ n = 1 for child in self.children: @@ -650,9 +642,9 @@ def compute_number_of_descendants(self): def compute_depth_of_self_and_children(self): """ - Computes the depth of self and all descendants. + Compute the depth of ``self`` and all descendants. - For each TreeNode, sets result as attribute self.depth + For each TreeNode, sets result as ``attribute self.depth``. EXAMPLES:: @@ -711,16 +703,16 @@ def minimal_schnyder_wood(graph, root_edge=None, minimal=True, check=True): INPUT: - - graph -- a planar triangulation, given by a graph with an embedding. + - ``graph`` -- a planar triangulation, given by a graph with an embedding - - root_edge -- a pair of vertices (default is from ``-1`` to ``-2``) - The third boundary vertex is then determined using the orientation and - will be labelled ``-3``. + - ``root_edge`` -- a pair of vertices (default: from ``-1`` to ``-2``); + the third boundary vertex is then determined using the orientation and + will be labelled ``-3`` - - minimal -- boolean (default ``True``), whether to return a - minimal or a maximal Schnyder wood. + - ``minimal`` -- boolean (default: ``True``); whether to return a + minimal or a maximal Schnyder wood - - check -- boolean (default ``True``), whether to check if the input + - ``check`` -- boolean (default: ``True``); whether to check if the input is a planar triangulation OUTPUT: diff --git a/src/sage/graphs/spanning_tree.pyx b/src/sage/graphs/spanning_tree.pyx index c041bb471c8..cc73b401668 100644 --- a/src/sage/graphs/spanning_tree.pyx +++ b/src/sage/graphs/spanning_tree.pyx @@ -53,7 +53,7 @@ def kruskal(G, by_weight=True, weight_function=None, check_weight=False, check=F - ``G`` -- an undirected graph - ``by_weight`` -- boolean (default: ``True``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + the graph are weighted. If ``False``, all edges have weight 1. - ``weight_function`` -- function (default: ``None``); a function that takes as input an edge ``(u, v, l)`` and outputs its weight. If not ``None``, @@ -262,7 +262,7 @@ def kruskal_iterator(G, by_weight=True, weight_function=None, check_weight=False - ``G`` -- an undirected graph - ``by_weight`` -- boolean (default: ``True``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + the graph are weighted. If ``False``, all edges have weight 1. - ``weight_function`` -- function (default: ``None``); a function that takes as input an edge ``(u, v, l)`` and outputs its weight. If not ``None``, @@ -294,9 +294,7 @@ def kruskal_iterator(G, by_weight=True, weight_function=None, check_weight=False it directly instead of using it indirectly via :meth:`sage.graphs.generic_graph.GenericGraph.min_spanning_tree`. - OUTPUT: - - The edges of a minimum spanning tree of ``G``, one by one. + OUTPUT: the edges of a minimum spanning tree of ``G``, one by one .. SEEALSO:: :func:`kruskal` @@ -368,7 +366,7 @@ def kruskal_iterator_from_edges(edges, union_find, by_weight=True, forest - ``by_weight`` -- boolean (default: ``True``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + the graph are weighted. If ``False``, all edges have weight 1. - ``weight_function`` -- function (default: ``None``); a function that takes as input an edge ``(u, v, l)`` and outputs its weight. If not ``None``, @@ -379,9 +377,7 @@ def kruskal_iterator_from_edges(edges, union_find, by_weight=True, - ``check_weight`` -- boolean (default: ``False``); whether to check that the ``weight_function`` outputs a number for each edge - OUTPUT: - - The edges of a minimum spanning tree of ``G``, one by one. + OUTPUT: the edges of a minimum spanning tree of ``G``, one by one .. SEEALSO:: @@ -446,11 +442,11 @@ def filter_kruskal(G, threshold=10000, by_weight=True, weight_function=None, - ``G`` -- an undirected graph - ``threshold`` -- integer (default: 10000); maximum number of edges on - which to run kruskal algorithm. Above that value, edges are partitioned - into sets of size at most ``threshold`` + which to run kruskal algorithm. Above that value, edges are partitioned + into sets of size at most ``threshold`` - ``by_weight`` -- boolean (default: ``True``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + the graph are weighted. If ``False``, all edges have weight 1. - ``weight_function`` -- function (default: ``None``); a function that takes as input an edge ``(u, v, l)`` and outputs its weight. If not ``None``, @@ -519,11 +515,11 @@ def filter_kruskal_iterator(G, threshold=10000, by_weight=True, weight_function= - ``G`` -- an undirected graph - ``threshold`` -- integer (default: 10000); maximum number of edges on - which to run kruskal algorithm. Above that value, edges are partitioned - into sets of size at most ``threshold`` + which to run kruskal algorithm. Above that value, edges are partitioned + into sets of size at most ``threshold`` - ``by_weight`` -- boolean (default: ``True``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + the graph are weighted. If ``False``, all edges have weight 1. - ``weight_function`` -- function (default: ``None``); a function that takes as input an edge ``(u, v, l)`` and outputs its weight. If not ``None``, @@ -545,9 +541,7 @@ def filter_kruskal_iterator(G, threshold=10000, by_weight=True, weight_function= - Does ``G`` have self-loops? - Does ``G`` have multiple edges? - OUTPUT: - - The edges of a minimum spanning tree of ``G``, one by one. + OUTPUT: the edges of a minimum spanning tree of ``G``, one by one .. SEEALSO:: @@ -718,10 +712,10 @@ def boruvka(G, by_weight=True, weight_function=None, check_weight=True, check=Fa INPUT: - - ``G`` -- an undirected graph. + - ``G`` -- an undirected graph - ``by_weight`` -- boolean (default: ``True``); if ``True``, the edges in - the graph are weighted; if ``False``, all edges have weight 1. + the graph are weighted. If ``False``, all edges have weight 1 - ``weight_function`` -- function (default: ``None``); a function that takes as input an edge ``(u, v, l)`` and outputs its weight. If not ``None``, @@ -952,7 +946,7 @@ def random_spanning_tree(G, output_as_graph=False, by_weight=False, weight_funct not convertible to a float, an error is raised) - ``check_weight`` -- boolean (default: ``True``); whether to check that - the ``weight_function`` outputs a number for each edge. + the ``weight_function`` outputs a number for each edge .. SEEALSO:: @@ -1303,7 +1297,7 @@ def edge_disjoint_spanning_trees(G, k, by_weight=False, weight_function=None, ch sage: edge_disjoint_spanning_trees(G, -1) Traceback (most recent call last): ... - ValueError: parameter k must be a non-negative integer + ValueError: parameter k must be a nonnegative integer sage: edge_disjoint_spanning_trees(G, 0) [] sage: edge_disjoint_spanning_trees(G, 1) @@ -1332,14 +1326,14 @@ def edge_disjoint_spanning_trees(G, k, by_weight=False, weight_function=None, ch from sage.graphs.graph import Graph msg_no_solution = "this graph does not contain the required number of trees/arborescences" if k < 0: - raise ValueError("parameter k must be a non-negative integer") + raise ValueError("parameter k must be a nonnegative integer") elif not k: return [] elif k == 1: E = G.min_spanning_tree() if not E and G.order() != 1: raise EmptySetError(msg_no_solution) - return [Graph([G, E], format="vertices_and_edges")] + return [Graph([G, E], format='vertices_and_edges')] elif k > 1 + min(G.degree()) // 2: raise EmptySetError(msg_no_solution) @@ -1359,7 +1353,7 @@ def edge_disjoint_spanning_trees(G, k, by_weight=False, weight_function=None, ch # This is not a requirement of the algorithm as we can use the mapping # edge_index. However, it is convenient to maintain the forest as graphs to # simplify some operations. - H = Graph([G, []], format="vertices_and_edges") + H = Graph([G, []], format='vertices_and_edges') F = [H.copy() for _ in range(k + 1)] # We consider the edges by increasing weight diff --git a/src/sage/graphs/strongly_regular_db.pyx b/src/sage/graphs/strongly_regular_db.pyx index b11ad677a83..0fa241ba218 100644 --- a/src/sage/graphs/strongly_regular_db.pyx +++ b/src/sage/graphs/strongly_regular_db.pyx @@ -431,7 +431,6 @@ def is_orthogonal_polar(int v, int k, int l, int mu): (, 8, 2, '-') sage: is_orthogonal_polar(130,48,20,16) # needs sage.rings.finite_rings (, 6, 3, '+') - """ r, s = eigenvalues(v, k, l, mu) if r is None: @@ -1174,7 +1173,7 @@ def is_RSHCD(int v, int k, int l, int mu): def SRG_from_RSHCD(v, k, l, mu, existence=False, check=True): r""" - Return a `(v,k,l,mu)`-strongly regular graph from a RSHCD + Return a `(v,k,l,mu)`-strongly regular graph from a RSHCD. This construction appears in 8.D of [BL1984]_. For more information, see :func:`~sage.combinat.matrices.hadamard_matrix.regular_symmetric_hadamard_matrix_with_constant_diagonal`. @@ -1183,13 +1182,12 @@ def SRG_from_RSHCD(v, k, l, mu, existence=False, check=True): - ``v``, ``k``, ``l``, ``mu`` -- integers - - ``existence`` (boolean) -- whether to return a graph or to test if Sage - can build such a graph. + - ``existence`` -- boolean; whether to return a graph or to test if Sage + can build such a graph - - ``check`` (boolean) -- whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to ``True`` - by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES: @@ -1243,7 +1241,7 @@ def SRG_from_RSHCD(v, k, l, mu, existence=False, check=True): if list(H.column(0)[1:]).count(1) == k: H = -H G = Graph((J(n) - I(n) - H + H[0, 0]*I(n)) / 2, - loops=False, multiedges=False, format="adjacency_matrix") + loops=False, multiedges=False, format='adjacency_matrix') if check: assert G.is_strongly_regular(parameters=True) == (v, k, l, mu) return G @@ -1611,7 +1609,6 @@ def is_switch_skewhad(int v, int k, int l, int mu): sage: from sage.graphs.strongly_regular_db import is_switch_skewhad sage: t = is_switch_skewhad(5,5,5,5); t # needs sage.combinat sage.modules - """ from sage.combinat.matrices.hadamard_matrix import skew_hadamard_matrix from sage.graphs.generators.families import SwitchedSquaredSkewHadamardMatrixGraph @@ -1718,7 +1715,6 @@ def is_nowhere0_twoweight(int v, int k, int l, int mu): sage: t = is_nowhere0_twoweight(1800, 728, 268, 312); t # needs sage.libs.pari (, 16) sage: t = is_nowhere0_twoweight(5,5,5,5); t # needs sage.libs.pari - """ from sage.graphs.generators.classical_geometries import Nowhere0WordsTwoWeightCodeGraph cdef int q @@ -1746,7 +1742,6 @@ cdef eigenvalues(int v, int k, int l, int mu): INPUT: - ``v``, ``k``, ``l``, ``mu`` -- integers - """ # See 1.3.1 of [Distance-regular graphs] b = (mu-l) @@ -1858,7 +1853,7 @@ cpdef latin_squares_graph_parameters(int v, int k, int l,int mu): OUTPUT: - - ``(g, n)`` -- parameters of an `L_g(n)` graph, or `None` + - ``(g, n)`` -- parameters of an `L_g(n)` graph, or ``None`` TESTS:: @@ -1882,7 +1877,7 @@ cpdef latin_squares_graph_parameters(int v, int k, int l,int mu): def _H_3_cayley_graph(L): r""" - return the `L`-Cayley graph of the group `H_3` from Prop. 12 in [JK2003]_. + Return the `L`-Cayley graph of the group `H_3` from Prop. 12 in [JK2003]_. INPUT: @@ -1976,7 +1971,7 @@ def SRG_105_32_4_12(): a = IG.automorphism_group() h = a.stabilizer(a.domain()[0]) o = next(x for x in h.orbits() if len(x) == 32)[0] - e = a.orbit((a.domain()[0], o), action="OnSets") + e = a.orbit((a.domain()[0], o), action='OnSets') G = Graph() G.add_edges(e) G.name('Aut L(3,4) on flags') @@ -2105,7 +2100,7 @@ def SRG_176_105_68_54(): def SRG_210_99_48_45(): r""" - Return a strongly regular graph with parameters `(210, 99, 48, 45)` + Return a strongly regular graph with parameters `(210, 99, 48, 45)`. This graph is from Example 4.2 in [KPRWZ2010]_. One considers the action of the symmetric group `S_7` on the 210 digraphs isomorphic to the @@ -2370,7 +2365,7 @@ def strongly_regular_from_two_weight_code(L): INPUT: - - ``L`` -- a two-weight linear code, or its generating matrix. + - ``L`` -- a two-weight linear code, or its generating matrix EXAMPLES:: @@ -2424,7 +2419,7 @@ def SRG_416_100_36_20(): def SRG_560_208_72_80(): r""" - Return a `(560,208,72,80)`-strongly regular graph + Return a `(560,208,72,80)`-strongly regular graph. This graph is obtained as the union of 4 orbits of sets of cardinality 2 (among the 13 that exist) of the group `Sz(8)`. @@ -2473,8 +2468,8 @@ def strongly_regular_from_two_intersection_set(M): INPUT: - - `M` -- a `|S| \times k` matrix with entries in `F_q` representing the points of - the 2-intersection set. We assume that the first non-zero entry of each row is + - ``M`` -- a `|S| \times k` matrix with entries in `F_q` representing the points of + the 2-intersection set. We assume that the first nonzero entry of each row is equal to `1`, that is, they give points in homogeneous coordinates. The implementation does not check that `S` is actually a 2-intersection set. @@ -2512,7 +2507,7 @@ def strongly_regular_from_two_intersection_set(M): def SRG_120_63_30_36(): r""" - Return a `(120,63,30,36)`-strongly regular graph + Return a `(120,63,30,36)`-strongly regular graph. It is the distance-2 graph of :meth:`JohnsonGraph(10,3) `. @@ -2530,7 +2525,7 @@ def SRG_120_63_30_36(): def SRG_126_25_8_4(): r""" - Return a `(126,25,8,4)`-strongly regular graph + Return a `(126,25,8,4)`-strongly regular graph. It is the distance-(1 or 4) graph of :meth:`JohnsonGraph(9,4) `. @@ -2548,7 +2543,7 @@ def SRG_126_25_8_4(): def SRG_175_72_20_36(): r""" - Return a `(175,72,20,36)`-strongly regular graph + Return a `(175,72,20,36)`-strongly regular graph. This graph is obtained from the line graph of :meth:`~sage.graphs.graph_generators.GraphGenerators.HoffmanSingletonGraph`. Setting @@ -2569,7 +2564,7 @@ def SRG_175_72_20_36(): def SRG_176_90_38_54(): r""" - Return a `(176,90,38,54)`-strongly regular graph + Return a `(176,90,38,54)`-strongly regular graph. This graph is obtained from :func:`~sage.graphs.strongly_regular_db.SRG_175_72_20_36` @@ -2603,7 +2598,7 @@ def SRG_176_90_38_54(): def SRG_630_85_20_10(): r""" - Return a `(630,85,20,10)`-strongly regular graph + Return a `(630,85,20,10)`-strongly regular graph. This graph is the line graph of `pg(5,18,2)`; its point graph is :func:`~sage.graphs.strongly_regular_db.SRG_175_72_20_36`. @@ -2624,7 +2619,7 @@ def SRG_630_85_20_10(): mc = [0, 1, 5, 6, 12, 13, 16, 17, 22, 23, 29, 33, 39, 42, 47] assert(hs.subgraph(mc).is_regular(k=0)) # a maximum coclique assert(hs.subgraph(P).is_regular(k=3)) - h = hs.automorphism_group().stabilizer(mc, action="OnSets") + h = hs.automorphism_group().stabilizer(mc, action='OnSets') l = h.orbit(tuple((x[0], x[1]) for x in hs.subgraph(P).matching()), "OnSetsSets") return IntersectionGraph(l) @@ -2632,7 +2627,7 @@ def SRG_630_85_20_10(): def SRG_126_50_13_24(): r""" - Return a `(126,50,13,24)`-strongly regular graph + Return a `(126,50,13,24)`-strongly regular graph. This graph is a subgraph of :meth:`~sage.graphs.strongly_regular_db.SRG_175_72_20_36`. @@ -2786,24 +2781,23 @@ def strongly_regular_graph(int v, int k, int l, int mu=-1, bint existence=False, INPUT: - - ``v``, ``k``, ``l``, ``mu`` -- integers -- note that ``mu``, if unspecified, is - automatically determined from ``v``, ``k``, ``l``. + - ``v``, ``k``, ``l``, ``mu`` -- ``integers`` -- note that ``mu``, if unspecified, is + automatically determined from ``v``, ``k``, ``l`` - - ``existence`` (boolean;``False``) -- instead of building the graph, + - ``existence`` -- boolean;``False``; instead of building the graph, return: - ``True`` -- meaning that a `(v,k,\lambda,\mu)`-strongly regular graph - exists. + exists - ``Unknown`` -- meaning that Sage does not know if such a strongly - regular graph exists (see :mod:`sage.misc.unknown`). + regular graph exists (see :mod:`sage.misc.unknown`) - - ``False`` -- meaning that no such strongly regular graph exists. + - ``False`` -- meaning that no such strongly regular graph exists - - ``check`` -- (boolean) Whether to check that output is correct before - returning it. As this is expected to be useless (but we are cautious - guys), you may want to disable it whenever you want speed. Set to - ``True`` by default. + - ``check`` -- boolean (default: ``True``); whether to check that output is + correct before returning it. As this is expected to be useless, you may + want to disable it whenever you want speed. EXAMPLES: @@ -2914,7 +2908,7 @@ def strongly_regular_graph(int v, int k, int l, int mu=-1, bint existence=False, def strongly_regular_graph_lazy(int v, int k, int l, int mu=-1, bint existence=False): r""" - return a promise to build an `(v,k,l,mu)`-srg + Return a promise to build an `(v,k,l,mu)`-srg. Return a promise to build an `(v,k,l,mu)`-srg as a tuple `t`, with `t[0]` a function to evaluate on `*t[1:]`. @@ -3052,7 +3046,7 @@ def apparently_feasible_parameters(int n): INPUT: - - ``n`` (integer) -- return all a-priori feasible tuples `(v,k,\lambda,\mu)` + - ``n`` -- integer; return all a-priori feasible tuples `(v,k,\lambda,\mu)` for `v bool: return not self.is_trivial() @cached_method - def dual_group(self, names="X", base_ring=None): + def dual_group(self, names='X', base_ring=None): """ Return the dual group. INPUT: - ``names`` -- string or list of strings. The generator names - for the dual group. + for the dual group - - ``base_ring`` -- the base ring. If ``None`` (default), then - a suitable cyclotomic field is picked automatically. + - ``base_ring`` -- the base ring; if ``None`` (default), then + a suitable cyclotomic field is picked automatically OUTPUT: the :class:`dual abelian group ` @@ -861,7 +861,7 @@ def _libgap_(self): Requires the optional ``gap_packages`` for infinite groups:: - sage: G = AbelianGroup(3, [0,3,4], names="abc") + sage: G = AbelianGroup(3, [0,3,4], names='abc') sage: libgap(G) # optional - gap_package_polycyclic Pcp-group with orders [ 0, 3, 4 ] """ @@ -872,7 +872,7 @@ def _libgap_(self): # Make sure to LoadPackage("Polycyclic") in gap from sage.features.gap import GapPackage - GapPackage("polycyclic", spkg="gap_packages").require() + GapPackage("polycyclic", spkg='gap_packages').require() return libgap.AbelianPcpGroup(self.gens_orders()) def _gap_init_(self): @@ -889,7 +889,7 @@ def _gap_init_(self): Requires the optional ``gap_packages`` for infinite groups:: - sage: G = AbelianGroup(3,[0,3,4], names="abc"); G + sage: G = AbelianGroup(3,[0,3,4], names='abc'); G Multiplicative Abelian group isomorphic to Z x C3 x C4 sage: G._gap_init_() # optional - gap_package_polycyclic 'AbelianPcpGroup([0, 3, 4])' @@ -899,7 +899,7 @@ def _gap_init_(self): from sage.features.gap import GapPackage # Make sure to LoadPackage("Polycyclic") in gap - GapPackage("polycyclic", spkg="gap_packages").require() + GapPackage("polycyclic", spkg='gap_packages').require() return 'AbelianPcpGroup(%s)' % list(self.gens_orders()) def gen(self, i=0): @@ -1192,7 +1192,7 @@ def _repr_(self) -> str: g = self._group_notation(eldv) return "Multiplicative Abelian group isomorphic to " + g - def subgroup(self, gensH, names="f"): + def subgroup(self, gensH, names='f'): """ Create a subgroup of this group. @@ -1293,7 +1293,7 @@ def __iter__(self): sage: L[0] = 0 sage: list(G) [1, b, b^2, a, a*b, a*b^2] - sage: G = AbelianGroup([1], names="a") + sage: G = AbelianGroup([1], names='a') sage: list(G) [1] sage: G = AbelianGroup([]) @@ -1616,7 +1616,7 @@ class AbelianGroup_subgroup(AbelianGroup_class): There should be a way to coerce an element of a subgroup into the ambient group. """ - def __init__(self, ambient, gens, names="f", category=None): + def __init__(self, ambient, gens, names='f', category=None): """ EXAMPLES:: @@ -1646,7 +1646,7 @@ def __init__(self, ambient, gens, names="f", category=None): 5 sage: z.order() 64 - sage: A = AbelianGroup(5, [3, 5, 5, 7, 8], names="abcde") + sage: A = AbelianGroup(5, [3, 5, 5, 7, 8], names='abcde') sage: a,b,c,d,e = A.gens() sage: A.subgroup([a,b]) Multiplicative Abelian subgroup isomorphic to C3 x C5 generated by {a, b} @@ -1658,7 +1658,7 @@ def __init__(self, ambient, gens, names="f", category=None): Multiplicative Abelian subgroup isomorphic to C4 x C5 x C5 x C7 generated by {b, c, d, e^2} sage: B.gens_orders() (4, 5, 5, 7) - sage: A = AbelianGroup(4,[1009, 2003, 3001, 4001], names="abcd") + sage: A = AbelianGroup(4,[1009, 2003, 3001, 4001], names='abcd') sage: a,b,c,d = A.gens() sage: B = A.subgroup([a^3,b,c,d]) sage: B.gens_orders() @@ -1667,7 +1667,7 @@ def __init__(self, ambient, gens, names="f", category=None): 24266473210027 sage: B.order() 24266473210027 - sage: A = AbelianGroup(4, [1008, 2003, 3001, 4001], names="abcd") + sage: A = AbelianGroup(4, [1008, 2003, 3001, 4001], names='abcd') sage: a,b,c,d = A.gens() sage: B = A.subgroup([a^3,b,c,d]); B Multiplicative Abelian subgroup isomorphic @@ -1676,7 +1676,7 @@ def __init__(self, ambient, gens, names="f", category=None): Infinite groups can also be handled:: sage: # needs sage.libs.gap # optional - gap_package_polycyclic - sage: G = AbelianGroup([3,4,0], names="abc") + sage: G = AbelianGroup([3,4,0], names='abc') sage: a,b,c = G.gens() sage: F = G.subgroup([a, b^2, c]); F Multiplicative Abelian subgroup isomorphic to C2 x C3 x Z @@ -1808,7 +1808,7 @@ def equals(left, right): EXAMPLES:: sage: # needs sage.libs.gap # optional - gap_package_polycyclic - sage: G = AbelianGroup(3, [2,3,4], names="abc"); G + sage: G = AbelianGroup(3, [2,3,4], names='abc'); G Multiplicative Abelian group isomorphic to C2 x C3 x C4 sage: a,b,c = G.gens() sage: F = G.subgroup([a,b^2]); F @@ -1882,7 +1882,7 @@ def gens(self) -> tuple: def gen(self, n): """ - Return the nth generator of this subgroup. + Return the `n`-th generator of this subgroup. EXAMPLES:: diff --git a/src/sage/groups/abelian_gps/abelian_group_element.py b/src/sage/groups/abelian_gps/abelian_group_element.py index 172a671906c..956fff7bd9a 100644 --- a/src/sage/groups/abelian_gps/abelian_group_element.py +++ b/src/sage/groups/abelian_gps/abelian_group_element.py @@ -13,7 +13,6 @@ - Volker Braun (2012-11) port to new Parent base. Use tuples for immutables. - EXAMPLES: Recall an example from abelian groups:: @@ -105,7 +104,7 @@ def as_permutation(self): EXAMPLES:: - sage: G = AbelianGroup(3, [2,3,4], names="abc"); G + sage: G = AbelianGroup(3, [2,3,4], names='abc'); G Multiplicative Abelian group isomorphic to C2 x C3 x C4 sage: a,b,c = G.gens() sage: Gp = G.permutation_group(); Gp # needs sage.groups @@ -149,7 +148,7 @@ def word_problem(self, words): EXAMPLES:: sage: # needs sage.libs.gap - sage: G = AbelianGroup(2, [2,3], names="xy") + sage: G = AbelianGroup(2, [2,3], names='xy') sage: x,y = G.gens() sage: x.word_problem([x,y]) [[x, 1]] diff --git a/src/sage/groups/abelian_gps/abelian_group_gap.py b/src/sage/groups/abelian_gps/abelian_group_gap.py index 45a6a8bdd1a..199aa935f56 100644 --- a/src/sage/groups/abelian_gps/abelian_group_gap.py +++ b/src/sage/groups/abelian_gps/abelian_group_gap.py @@ -562,7 +562,7 @@ def quotient(self, N): INPUT: - ``N`` -- a subgroup - - ``check`` -- bool (default: ``True``) check if `N` is normal + - ``check`` -- boolean (default: ``True``); check if `N` is normal EXAMPLES:: @@ -584,7 +584,7 @@ def subgroup(self, gens): INPUT: - - ``gens`` -- a list of elements coercible into this group + - ``gens`` -- list of elements coercible into this group OUTPUT: a subgroup @@ -626,7 +626,7 @@ class AbelianGroupGap(AbelianGroup_gap): INPUT: - - ``generator_orders`` -- a list of nonnegative integers where `0` + - ``generator_orders`` -- list of nonnegative integers where `0` gives a factor isomorphic to `\ZZ` OUTPUT: an abelian group @@ -857,11 +857,12 @@ def retract(self, x): """ Convert an element of the ambient group into this subgroup. - The terminology comes from the category framework and the more general notion of a subquotient. + The terminology comes from the category framework and the more general + notion of a subquotient. INPUT: - - ``x`` -- an element of the ambient group that actually lies in this subgroup. + - ``x`` -- an element of the ambient group that actually lies in this subgroup OUTPUT: the corresponding element of this subgroup diff --git a/src/sage/groups/abelian_gps/abelian_group_morphism.py b/src/sage/groups/abelian_gps/abelian_group_morphism.py index eb41400065a..c635ad32cb6 100644 --- a/src/sage/groups/abelian_gps/abelian_group_morphism.py +++ b/src/sage/groups/abelian_gps/abelian_group_morphism.py @@ -55,10 +55,10 @@ class AbelianGroupMorphism(Morphism): EXAMPLES:: - sage: G = AbelianGroup(3,[2,3,4],names="abc"); G + sage: G = AbelianGroup(3,[2,3,4],names='abc'); G Multiplicative Abelian group isomorphic to C2 x C3 x C4 sage: a,b,c = G.gens() - sage: H = AbelianGroup(2,[2,3],names="xy"); H + sage: H = AbelianGroup(2,[2,3],names='xy'); H Multiplicative Abelian group isomorphic to C2 x C3 sage: x,y = H.gens() @@ -124,10 +124,10 @@ def _libgap_(self): EXAMPLES:: - sage: G = AbelianGroup(3,[2,3,4],names="abc"); G + sage: G = AbelianGroup(3,[2,3,4],names='abc'); G Multiplicative Abelian group isomorphic to C2 x C3 x C4 sage: a,b,c = G.gens() - sage: H = AbelianGroup(2,[2,3],names="xy"); H + sage: H = AbelianGroup(2,[2,3],names='xy'); H Multiplicative Abelian group isomorphic to C2 x C3 sage: x,y = H.gens() sage: phi = AbelianGroupMorphism(H,G,[x,y],[a,b]) # optional - gap_package_polycyclic @@ -156,19 +156,19 @@ def kernel(self): EXAMPLES:: - sage: H = AbelianGroup(3,[2,3,4],names="abc"); H + sage: H = AbelianGroup(3,[2,3,4],names='abc'); H Multiplicative Abelian group isomorphic to C2 x C3 x C4 sage: a,b,c = H.gens() - sage: G = AbelianGroup(2,[2,3],names="xy"); G + sage: G = AbelianGroup(2,[2,3],names='xy'); G Multiplicative Abelian group isomorphic to C2 x C3 sage: x,y = G.gens() sage: phi = AbelianGroupMorphism(G,H,[x,y],[a,b]) # optional - gap_package_polycyclic sage: phi.kernel() # optional - gap_package_polycyclic Group([ ]) - sage: H = AbelianGroup(3,[2,2,2],names="abc") + sage: H = AbelianGroup(3,[2,2,2],names='abc') sage: a,b,c = H.gens() - sage: G = AbelianGroup(2,[2,2],names="x") + sage: G = AbelianGroup(2,[2,2],names='x') sage: x,y = G.gens() sage: phi = AbelianGroupMorphism(G,H,[x,y],[a,a]) # optional - gap_package_polycyclic sage: phi.kernel() # optional - gap_package_polycyclic @@ -188,10 +188,10 @@ def image(self, S): EXAMPLES:: - sage: G = AbelianGroup(2,[2,3],names="xy") + sage: G = AbelianGroup(2,[2,3],names='xy') sage: x,y = G.gens() sage: subG = G.subgroup([x]) # optional - gap_package_polycyclic - sage: H = AbelianGroup(3,[2,3,4],names="abc") + sage: H = AbelianGroup(3,[2,3,4],names='abc') sage: a,b,c = H.gens() sage: phi = AbelianGroupMorphism(G,H,[x,y],[a,b]) # optional - gap_package_polycyclic sage: phi.image(subG) # optional - gap_package_polycyclic @@ -206,9 +206,9 @@ def _call_(self, g): EXAMPLES:: - sage: H = AbelianGroup(3, [2,3,4], names="abc") + sage: H = AbelianGroup(3, [2,3,4], names='abc') sage: a,b,c = H.gens() - sage: G = AbelianGroup(2, [2,3], names="xy") + sage: G = AbelianGroup(2, [2,3], names='xy') sage: x,y = G.gens() sage: phi = AbelianGroupMorphism(G,H,[x,y],[a,b]) # optional - gap_package_polycyclic sage: phi(y*x) # optional - gap_package_polycyclic diff --git a/src/sage/groups/abelian_gps/dual_abelian_group.py b/src/sage/groups/abelian_gps/dual_abelian_group.py index aaa231b0f81..1c353a90136 100644 --- a/src/sage/groups/abelian_gps/dual_abelian_group.py +++ b/src/sage/groups/abelian_gps/dual_abelian_group.py @@ -109,12 +109,12 @@ class DualAbelianGroup_class(UniqueRepresentation, AbelianGroupBase): EXAMPLES:: - sage: F = AbelianGroup(5,[3,5,7,8,9], names="abcde") + sage: F = AbelianGroup(5,[3,5,7,8,9], names='abcde') sage: F.dual_group() Dual of Abelian Group isomorphic to Z/3Z x Z/5Z x Z/7Z x Z/8Z x Z/9Z over Cyclotomic Field of order 2520 and degree 576 - sage: F = AbelianGroup(4,[15,7,8,9], names="abcd") + sage: F = AbelianGroup(4,[15,7,8,9], names='abcd') sage: F.dual_group(base_ring=CC) # needs sage.rings.real_mpfr Dual of Abelian Group isomorphic to Z/15Z x Z/7Z x Z/8Z x Z/9Z over Complex Field with 53 bits of precision @@ -127,7 +127,7 @@ def __init__(self, G, names, base_ring): EXAMPLES:: - sage: F = AbelianGroup(5,[3,5,7,8,9], names="abcde") + sage: F = AbelianGroup(5,[3,5,7,8,9], names='abcde') sage: F.dual_group() Dual of Abelian Group isomorphic to Z/3Z x Z/5Z x Z/7Z x Z/8Z x Z/9Z over Cyclotomic Field of order 2520 and degree 576 @@ -233,8 +233,8 @@ def random_element(self): sage: # needs sage.rings.real_mpfr sage: N = 43^2 - 1 - sage: G = AbelianGroup([N], names="a") - sage: Gd = G.dual_group(names="A", base_ring=CC) + sage: G = AbelianGroup([N], names='a') + sage: Gd = G.dual_group(names='A', base_ring=CC) sage: a, = G.gens() sage: A, = Gd.gens() sage: x = a^(N/4); y = a^(N/3); z = a^(N/14) @@ -257,7 +257,7 @@ def gen(self, i=0): EXAMPLES:: sage: F = AbelianGroup(3, [1,2,3], names='a') - sage: Fd = F.dual_group(names="A") + sage: Fd = F.dual_group(names='A') sage: Fd.0 1 sage: Fd.1 @@ -338,9 +338,9 @@ def __contains__(self, X): EXAMPLES:: - sage: F = AbelianGroup(5,[2, 3, 5, 7, 8], names="abcde") + sage: F = AbelianGroup(5,[2, 3, 5, 7, 8], names='abcde') sage: a,b,c,d,e = F.gens() - sage: Fd = F.dual_group(names="ABCDE") + sage: Fd = F.dual_group(names='ABCDE') sage: A,B,C,D,E = Fd.gens() sage: A*B^2*D^7 in Fd True @@ -383,8 +383,8 @@ def list(self): EXAMPLES:: - sage: G = AbelianGroup([2,3], names="ab") - sage: Gd = G.dual_group(names="AB") + sage: G = AbelianGroup([2,3], names='ab') + sage: Gd = G.dual_group(names='AB') sage: Gd.list() (1, B, B^2, A, A*B, A*B^2) """ @@ -399,15 +399,15 @@ def __iter__(self): EXAMPLES:: - sage: G = AbelianGroup([2,3], names="ab") - sage: Gd = G.dual_group(names="AB") + sage: G = AbelianGroup([2,3], names='ab') + sage: Gd = G.dual_group(names='AB') sage: [X for X in Gd] [1, B, B^2, A, A*B, A*B^2] sage: # needs sage.rings.real_mpfr sage: N = 43^2 - 1 - sage: G = AbelianGroup([N], names="a") - sage: Gd = G.dual_group(names="A", base_ring=CC) + sage: G = AbelianGroup([N], names='a') + sage: Gd = G.dual_group(names='A', base_ring=CC) sage: a, = G.gens() sage: A, = Gd.gens() sage: x = a^(N/4) diff --git a/src/sage/groups/abelian_gps/dual_abelian_group_element.py b/src/sage/groups/abelian_gps/dual_abelian_group_element.py index 048666b020f..db6683910b2 100644 --- a/src/sage/groups/abelian_gps/dual_abelian_group_element.py +++ b/src/sage/groups/abelian_gps/dual_abelian_group_element.py @@ -5,11 +5,11 @@ To obtain the dual group of a finite Abelian group, use the :meth:`~sage.groups.abelian_gps.abelian_group.dual_group` method:: - sage: F = AbelianGroup([2,3,5,7,8], names="abcde") + sage: F = AbelianGroup([2,3,5,7,8], names='abcde') sage: F Multiplicative Abelian group isomorphic to C2 x C3 x C5 x C7 x C8 - sage: Fd = F.dual_group(names="ABCDE"); Fd + sage: Fd = F.dual_group(names='ABCDE'); Fd Dual of Abelian Group isomorphic to Z/2Z x Z/3Z x Z/5Z x Z/7Z x Z/8Z over Cyclotomic Field of order 840 and degree 192 @@ -100,9 +100,9 @@ def __call__(self, g): EXAMPLES:: - sage: F = AbelianGroup(5, [2,3,5,7,8], names="abcde") + sage: F = AbelianGroup(5, [2,3,5,7,8], names='abcde') sage: a,b,c,d,e = F.gens() - sage: Fd = F.dual_group(names="ABCDE") + sage: Fd = F.dual_group(names='ABCDE') sage: A,B,C,D,E = Fd.gens() sage: A*B^2*D^7 A*B^2 @@ -117,9 +117,9 @@ def __call__(self, g): TESTS:: - sage: F = AbelianGroup(1, [7], names="a") + sage: F = AbelianGroup(1, [7], names='a') sage: a, = F.gens() - sage: Fd = F.dual_group(names="A", base_ring=GF(29)) + sage: Fd = F.dual_group(names='A', base_ring=GF(29)) sage: A, = Fd.gens() sage: A(a) # needs sage.libs.pari 16 @@ -150,8 +150,8 @@ def word_problem(self, words): EXAMPLES:: - sage: G = AbelianGroup(5,[3, 5, 5, 7, 8], names="abcde") - sage: Gd = G.dual_group(names="abcde") + sage: G = AbelianGroup(5,[3, 5, 5, 7, 8], names='abcde') + sage: Gd = G.dual_group(names='abcde') sage: a,b,c,d,e = Gd.gens() sage: u = a^3*b*c*d^2*e^5 sage: v = a^2*b*c^2*d^3*e^3 diff --git a/src/sage/groups/abelian_gps/element_base.py b/src/sage/groups/abelian_gps/element_base.py index 7712049e219..abaff8a225a 100644 --- a/src/sage/groups/abelian_gps/element_base.py +++ b/src/sage/groups/abelian_gps/element_base.py @@ -30,7 +30,7 @@ class AbelianGroupElementBase(MultiplicativeGroupElement): """ - Base class for abelian group elements + Base class for abelian group elements. The group element is defined by a tuple whose ``i``-th entry is an integer in the range from 0 (inclusively) to ``G.gen(i).order()`` @@ -39,16 +39,16 @@ class AbelianGroupElementBase(MultiplicativeGroupElement): INPUT: - - ``exponents`` -- ``1`` or a list/tuple/iterable of integers. The + - ``exponents`` -- ``1`` or a list/tuple/iterable of integers; the exponent vector (with respect to the parent generators) defining - the group element. + the group element - - ``parent`` -- Abelian group. The parent of the group element. + - ``parent`` -- abelian group; the parent of the group element EXAMPLES:: sage: F = AbelianGroup(3,[7,8,9]) - sage: Fd = F.dual_group(names="ABC") # needs sage.rings.number_field + sage: Fd = F.dual_group(names='ABC') # needs sage.rings.number_field sage: A,B,C = Fd.gens() # needs sage.rings.number_field sage: A*B^-1 in Fd # needs sage.rings.number_field True @@ -61,7 +61,7 @@ def __init__(self, parent, exponents): EXAMPLES:: sage: F = AbelianGroup(3,[7,8,9]) - sage: Fd = F.dual_group(names="ABC") # needs sage.rings.number_field + sage: Fd = F.dual_group(names='ABC') # needs sage.rings.number_field sage: A,B,C = Fd.gens() # needs sage.rings.number_field sage: A*B^-1 in Fd # needs sage.rings.number_field True @@ -148,9 +148,9 @@ def list(self): EXAMPLES:: sage: # needs sage.rings.number_field - sage: F = AbelianGroup(5,[2, 3, 5, 7, 8], names="abcde") + sage: F = AbelianGroup(5,[2, 3, 5, 7, 8], names='abcde') sage: a,b,c,d,e = F.gens() - sage: Ad = F.dual_group(names="ABCDE") + sage: Ad = F.dual_group(names='ABCDE') sage: A,B,C,D,E = Ad.gens() sage: (A*B*C^2*D^20*E^65).exponents() (1, 1, 2, 6, 1) diff --git a/src/sage/groups/abelian_gps/values.py b/src/sage/groups/abelian_gps/values.py index c38edcfb9f9..43f9e29cb75 100644 --- a/src/sage/groups/abelian_gps/values.py +++ b/src/sage/groups/abelian_gps/values.py @@ -84,19 +84,19 @@ def AbelianGroupWithValues(values, n, gens_orders=None, names='f', check=False, INPUT: - - ``values`` -- a list/tuple/iterable of values that you want to + - ``values`` -- list/tuple/iterable of values that you want to associate to the generators - - ``n`` -- integer (optional). If not specified, will be derived - from ``gens_orders`` + - ``n`` -- integer (optional); if not specified, will be derived + from ``gens_orders`` - - ``gens_orders`` -- a list of non-negative integers in the form + - ``gens_orders`` -- list of nonnegative integers in the form `[a_0, a_1, \dots, a_{n-1}]`, typically written in increasing order. This list is padded with zeros if it has length less than n. The orders of the commuting generators, with `0` denoting an infinite cyclic factor. - - ``names`` -- (optional) names of generators + - ``names`` -- (optional) names of generators - ``values_group`` -- a parent or ``None`` (default). The common parent of the values. This might be a group, but can also just @@ -358,12 +358,12 @@ class AbelianGroupWithValues_class(AbelianGroup_class): INPUT: - ``generator_orders`` -- tuple of integers; the orders of the - generators. + generators - ``names`` -- string or list of strings; the names for the generators - ``values`` -- tuple the same length as the number of - generators; the values assigned to the generators. + generators; the values assigned to the generators - ``values_group`` -- the common parent of the values diff --git a/src/sage/groups/additive_abelian/additive_abelian_group.py b/src/sage/groups/additive_abelian/additive_abelian_group.py index bbf91165437..b88fdb4846e 100644 --- a/src/sage/groups/additive_abelian/additive_abelian_group.py +++ b/src/sage/groups/additive_abelian/additive_abelian_group.py @@ -23,7 +23,7 @@ def AdditiveAbelianGroup(invs, remember_generators=True): - ``remember_generators`` -- boolean (default: ``True``); whether or not to fix a set of generators (corresponding to the given invariants, which - need not be in Smith form). + need not be in Smith form) OUTPUT: the abelian group `\bigoplus_i \ZZ / n_i \ZZ`, where `n_i` are the invariants @@ -409,7 +409,7 @@ class AdditiveAbelianGroup_fixed_gens(AdditiveAbelianGroup_class): """ def __init__(self, cover, rels, gens): r""" - Standard initialisation function + Standard initialisation function. EXAMPLES:: diff --git a/src/sage/groups/additive_abelian/additive_abelian_wrapper.py b/src/sage/groups/additive_abelian/additive_abelian_wrapper.py index 966b3137cdb..645b5cc8448 100644 --- a/src/sage/groups/additive_abelian/additive_abelian_wrapper.py +++ b/src/sage/groups/additive_abelian/additive_abelian_wrapper.py @@ -6,7 +6,6 @@ object from any given set of elements in some given parent, as long as an ``_add_`` method has been defined. - EXAMPLES: We create a toy example based on the Mordell-Weil group of an elliptic curve over `\QQ`:: diff --git a/src/sage/groups/additive_abelian/qmodnz.py b/src/sage/groups/additive_abelian/qmodnz.py index 8ae0dd35728..8bca7cbb460 100644 --- a/src/sage/groups/additive_abelian/qmodnz.py +++ b/src/sage/groups/additive_abelian/qmodnz.py @@ -47,12 +47,11 @@ class QmodnZ(Parent, UniqueRepresentation): #. ``QmodnZ(n)``, where - - `n` -- a rational number (including 0 or negative rational numbers). + - ``n`` -- a rational number (including 0 or negative rational numbers) #. ``QQ/(n*ZZ)``, where - - `n` -- integer (including 0 or negative integers). - + - ``n`` -- integer (including 0 or negative integers) OUTPUT: the abelian group `\Q/n\Z` diff --git a/src/sage/groups/additive_abelian/qmodnz_element.py b/src/sage/groups/additive_abelian/qmodnz_element.py index b3ebe8e2335..2978a665a36 100644 --- a/src/sage/groups/additive_abelian/qmodnz_element.py +++ b/src/sage/groups/additive_abelian/qmodnz_element.py @@ -76,7 +76,7 @@ def __init__(self, parent, x, construct=False): def lift(self): r""" - Return the smallest non-negative rational number reducing to + Return the smallest nonnegative rational number reducing to this element. EXAMPLES:: @@ -109,8 +109,8 @@ def _integer_(self, Z): r""" Lift to `\Z`. - This is the smallest non-negative integer reducing to this element, - or a :class:`ValueError` if none exists. + This is the smallest nonnegative integer reducing to this element, + or a :exc:`ValueError` if none exists. TESTS:: @@ -263,7 +263,7 @@ def division_by(self, other): Division of `x` by `m` does not yield a well defined result, since there are `m` elements `y` of `\Q/n\Z` with the property that `x = my`. We return the one - with the smallest non-negative lift. + with the smallest nonnegative lift. EXAMPLES:: diff --git a/src/sage/groups/affine_gps/affine_group.py b/src/sage/groups/affine_gps/affine_group.py index 07b63d4a2bc..d20f209788f 100644 --- a/src/sage/groups/affine_gps/affine_group.py +++ b/src/sage/groups/affine_gps/affine_group.py @@ -88,15 +88,15 @@ class AffineGroup(UniqueRepresentation, Group): - Degree and base ring: - * ``degree`` -- An integer. The degree of the affine group, that - is, the dimension of the affine space the group is acting on. + * ``degree`` -- integer; the degree of the affine group, that + is, the dimension of the affine space the group is acting on - * ``ring`` -- A ring or an integer. The base ring of the affine + * ``ring`` -- a ring or an integer; the base ring of the affine space. If an integer is given, it must be a prime power and the corresponding finite field is constructed. - * ``var`` -- (default: ``'a'``) Keyword argument to specify the finite - field generator name in the case where ``ring`` is a prime power. + * ``var`` -- (default: ``'a'``) keyword argument to specify the finite + field generator name in the case where ``ring`` is a prime power EXAMPLES:: @@ -230,7 +230,7 @@ def _element_constructor_check(self, A, b): """ Verify that ``A``, ``b`` define an affine group element. - This raises a :class:`TypeError` if the input does not define + This raises a :exc:`TypeError` if the input does not define a valid group element. This is called from the group element constructor and can be @@ -391,7 +391,7 @@ def linear(self, A): - ``A`` -- anything that determines a matrix - OUTPUT: The affine group element `x \mapsto A x` + OUTPUT: the affine group element `x \mapsto A x` EXAMPLES:: @@ -412,7 +412,7 @@ def translation(self, b): - ``b`` -- anything that determines a vector - OUTPUT: The affine group element `x \mapsto x + b` + OUTPUT: the affine group element `x \mapsto x + b` EXAMPLES:: diff --git a/src/sage/groups/affine_gps/euclidean_group.py b/src/sage/groups/affine_gps/euclidean_group.py index 000210ddeab..97677c777d1 100644 --- a/src/sage/groups/affine_gps/euclidean_group.py +++ b/src/sage/groups/affine_gps/euclidean_group.py @@ -76,15 +76,15 @@ class EuclideanGroup(AffineGroup): - Degree and base ring: - * ``degree`` -- An integer. The degree of the affine group, that - is, the dimension of the affine space the group is acting on. + * ``degree`` -- integer; the degree of the affine group, that + is, the dimension of the affine space the group is acting on - * ``ring`` -- A ring or an integer. The base ring of the affine + * ``ring`` -- a ring or an integer; the base ring of the affine space. If an integer is given, it must be a prime power and the corresponding finite field is constructed. - * ``var`` -- (default: ``'a'``) Keyword argument to specify the finite - field generator name in the case where ``ring`` is a prime power. + * ``var`` -- (default: ``'a'``) keyword argument to specify the finite + field generator name in the case where ``ring`` is a prime power EXAMPLES:: @@ -170,7 +170,7 @@ def _element_constructor_check(self, A, b): OUTPUT: - The return value is ignored. You must raise a :class:`TypeError` if + The return value is ignored. You must raise a :exc:`TypeError` if the input does not define a valid group element. TESTS:: diff --git a/src/sage/groups/affine_gps/group_element.py b/src/sage/groups/affine_gps/group_element.py index e2a6cd290c6..fff5881868f 100644 --- a/src/sage/groups/affine_gps/group_element.py +++ b/src/sage/groups/affine_gps/group_element.py @@ -61,11 +61,11 @@ class AffineGroupElement(MultiplicativeGroupElement): - ``parent`` -- the parent affine group - - ``convert`` -- bool (default: ``True``); whether to convert + - ``convert`` -- boolean (default: ``True``); whether to convert ``A`` into the correct matrix space and ``b`` into the correct vector space - - ``check`` -- bool (default: ``True``); whether to do some + - ``check`` -- boolean (default: ``True``); whether to do some checks or just accept the input as valid As a special case, ``A`` can be a matrix obtained from @@ -73,7 +73,7 @@ class AffineGroupElement(MultiplicativeGroupElement): that case, the group element defining that matrix is reconstructed. - OUTPUT: The affine group element `x \mapsto Ax + b` + OUTPUT: the affine group element `x \mapsto Ax + b` EXAMPLES:: @@ -145,7 +145,7 @@ def A(self): """ Return the general linear part of an affine group element. - OUTPUT: The matrix `A` of the affine group element `Ax + b` + OUTPUT: the matrix `A` of the affine group element `Ax + b` EXAMPLES:: @@ -162,7 +162,7 @@ def b(self): """ Return the translation part of an affine group element. - OUTPUT: The vector `b` of the affine group element `Ax + b` + OUTPUT: the vector `b` of the affine group element `Ax + b` EXAMPLES:: diff --git a/src/sage/groups/artin.py b/src/sage/groups/artin.py index 306569e546b..c6628c587e2 100644 --- a/src/sage/groups/artin.py +++ b/src/sage/groups/artin.py @@ -51,7 +51,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: a string; a valid LaTeX math command sequence + OUTPUT: string; a valid LaTeX math command sequence TESTS:: @@ -508,7 +508,7 @@ def cardinality(self): """ Return the number of elements of ``self``. - OUTPUT: Infinity + OUTPUT: infinity EXAMPLES:: @@ -530,7 +530,7 @@ def as_permutation_group(self): """ Return an isomorphic permutation group. - This raises a :class:`ValueError` error since Artin groups are + This raises a :exc:`ValueError` error since Artin groups are infinite and have no corresponding permutation group. EXAMPLES:: diff --git a/src/sage/groups/braid.py b/src/sage/groups/braid.py index d963a7b2e6a..88aa11802de 100644 --- a/src/sage/groups/braid.py +++ b/src/sage/groups/braid.py @@ -119,7 +119,7 @@ class Braid(FiniteTypeArtinGroupElement): """ def _richcmp_(self, other, op): """ - Compare ``self`` and ``other`` + Compare ``self`` and ``other``. TESTS:: @@ -373,9 +373,7 @@ def alexander_polynomial(self, var='t', normalized=True): - ``normalized`` -- boolean (default: ``True``); whether to return the normalized Alexander polynomial - OUTPUT: - - The Alexander polynomial of the braid closure of the braid. + OUTPUT: the Alexander polynomial of the braid closure of the braid This is computed using the reduced Burau representation. The unnormalized Alexander polynomial is a Laurent polynomial, @@ -467,7 +465,7 @@ def permutation(self, W=None): def plot(self, color='rainbow', orientation='bottom-top', gap=0.05, aspect_ratio=1, axes=False, **kwds): """ - Plot the braid + Plot the braid. The following options are available: @@ -491,14 +489,14 @@ def plot(self, color='rainbow', orientation='bottom-top', gap=0.05, aspect_ratio * ``'left-right'``, the braid is printed from left to right - - ``gap`` -- floating point number (default: 0.05). determines - the size of the gap left when a strand goes under another. + - ``gap`` -- floating point number (default: 0.05); determines + the size of the gap left when a strand goes under another - ``aspect_ratio`` -- floating point number (default: - ``1``). The aspect ratio. + ``1``); the aspect ratio - ``**kwds`` -- other keyword options that are passed to - :meth:`~sage.plot.bezier_path` and :meth:`~sage.plot.line`. + :meth:`~sage.plot.bezier_path` and :meth:`~sage.plot.line` EXAMPLES:: @@ -522,7 +520,7 @@ def plot(self, color='rainbow', orientation='bottom-top', gap=0.05, aspect_ratio sage: B. = BraidGroup(3) sage: b = t^-1*s^2 - sage: b.plot(orientation="left-right", color="red") # needs sage.plot + sage: b.plot(orientation='left-right', color='red') # needs sage.plot Graphics object consisting of 12 graphics primitives """ from sage.plot.bezier_path import bezier_path @@ -618,7 +616,7 @@ def plot3d(self, color='rainbow'): sage: b = B([1, 2, 3, 1, 2, 1]) sage: b.plot3d() # needs sage.plot sage.symbolic Graphics3d Object - sage: b.plot3d(color="red") # needs sage.plot sage.symbolic + sage: b.plot3d(color='red') # needs sage.plot sage.symbolic Graphics3d Object sage: b.plot3d(color=["red", "blue", "red", "blue"]) # needs sage.plot sage.symbolic Graphics3d Object @@ -669,8 +667,8 @@ def LKB_matrix(self, variables='x,y'): INPUT: - - ``variables`` -- string (default: ``'x,y'``). A string - containing the names of the variables, separated by a comma. + - ``variables`` -- string (default: ``'x,y'``); a string + containing the names of the variables, separated by a comma OUTPUT: the matrix corresponding to the Lawrence-Krammer-Bigelow representation of the braid @@ -726,9 +724,7 @@ def TL_matrix(self, drain_size, variab=None, sparse=True): - ``sparse`` -- boolean (default: ``True``); whether or not the result should be given as a sparse matrix - OUTPUT: - - The matrix of the TL representation of the braid. + OUTPUT: the matrix of the TL representation of the braid The parameter ``sparse`` can be set to ``False`` if it is expected that the resulting matrix will not be sparse. We @@ -801,7 +797,7 @@ def links_gould_matrix(self, symbolics=False): INPUT: - - ``symbolics`` -- boolean (default ``False``). If set to ``True`` the + - ``symbolics`` -- boolean (default: ``False``); if set to ``True`` the coefficients will be contained in the symbolic ring. Per default they are elements of a quotient ring of a three variate Laurent polynomial ring. @@ -841,7 +837,7 @@ def links_gould_polynomial(self, varnames=None, use_symbolics=False): INPUT: - - ``varnames`` -- string (default ``t0, t1``) + - ``varnames`` -- string (default: ``'t0, t1'``) OUTPUT: a Laurent polynomial in the given variable names @@ -900,7 +896,7 @@ def tropical_coordinates(self): r""" Return the tropical coordinates of ``self`` in the braid group `B_n`. - OUTPUT: a list of `2n` tropical integers + OUTPUT: list of `2n` tropical integers EXAMPLES:: @@ -1311,7 +1307,7 @@ def _annular_khovanov_complex_cached(self, qagrad, ring=None): INPUT: - - ``qagrad`` -- a tuple of the quantum and annular grading to compute + - ``qagrad`` -- tuple of the quantum and annular grading to compute - ``ring`` -- (default: ``ZZ``) the coefficient ring @@ -1356,14 +1352,14 @@ def _annular_khovanov_complex_cached(self, qagrad, ring=None): def annular_khovanov_complex(self, qagrad=None, ring=None): r""" Return the annular Khovanov complex of the closure of a braid, - as defined in [BG2013]_ + as defined in [BG2013]_. INPUT: - ``qagrad`` -- tuple of quantum and annular grading for which to compute - the chain complex. If not specified all gradings are computed. + the chain complex; if not specified all gradings are computed - - ``ring`` -- (default: ``ZZ``) the coefficient ring. + - ``ring`` -- (default: ``ZZ``) the coefficient ring OUTPUT: @@ -1980,7 +1976,7 @@ def sliding_circuits(self): """ Return the sliding circuits of the braid. - OUTPUT: a list of sliding circuits. Each sliding circuit is itself + OUTPUT: list of sliding circuits. Each sliding circuit is itself a list of braids. EXAMPLES:: @@ -2286,7 +2282,7 @@ def __init__(self, words): ....: ) = fig_8.deformed_burau_matrix().parent().base_ring().gens() sage: q = bp_1.base_ring().gen() sage: Q = RightQuantumWord(ap_1*cp_1 + q**3*bm_2*bp_1*am_0*cm_0) - sage: TestSuite(Q).run(skip="_test_pickling") + sage: TestSuite(Q).run(skip='_test_pickling') """ self._algebra = words.parent() self.q = self._algebra.base_ring().gen() @@ -2505,7 +2501,7 @@ def __init__(self, names): INPUT: - - ``names`` -- a tuple of strings; the names of the generators + - ``names`` -- tuple of strings; the names of the generators TESTS:: @@ -2620,7 +2616,7 @@ def as_permutation_group(self): """ Return an isomorphic permutation group. - OUTPUT: this raises a :class:`ValueError` error since braid groups + OUTPUT: this raises a :exc:`ValueError` error since braid groups are infinite TESTS:: @@ -2734,7 +2730,7 @@ def _links_gould_representation(self, symbolics=False): INPUT: - - ``symbolics`` -- boolean (default ``False``). If set to ``True`` the + - ``symbolics`` -- boolean (default: ``False``); if set to ``True`` the coefficients will be contained in the symbolic ring. Per default they are elements of a quotient ring of a three variate Laurent polynomial ring. @@ -2978,7 +2974,7 @@ def TL_basis_with_drain(self, drain_size): A basis element is specified as a list of integers obtained by considering the pairings as obtained as the 'highest term' of trivalent trees marked by Jones--Wenzl projectors (see e.g. [Wan2010]_). - In practice, this is a list of non-negative integers whose first + In practice, this is a list of nonnegative integers whose first element is ``drain_size``, whose last element is `0`, and satisfying that consecutive integers have difference `1`. Moreover, the length of each basis element is `n + 1`. @@ -2991,7 +2987,7 @@ def TL_basis_with_drain(self, drain_size): - ``drain_size`` -- integer between 0 and the number of strands (both inclusive) - OUTPUT: a list of basis elements, each of which is a list of integers + OUTPUT: list of basis elements, each of which is a list of integers EXAMPLES: @@ -3173,7 +3169,7 @@ def TL_representation(self, drain_size, variab=None): entries of the matrices; if ``None``, then use a default variable in `\ZZ[A,A^{-1}]` - OUTPUT: a list of matrices corresponding to the representations of each + OUTPUT: list of matrices corresponding to the representations of each of the standard generators and their inverses EXAMPLES:: @@ -3320,7 +3316,7 @@ def _element_from_libbraiding(self, nf): INPUT: - - ``nf`` -- a list of lists, as returned by libbraiding + - ``nf`` -- list of lists, as returned by libbraiding EXAMPLES:: @@ -3365,7 +3361,7 @@ def presentation_two_generators(self, isomorphisms=False): INPUT: - - ``isomorphism`` -- boolean (default ``False``); if ``True``, then an isomorphism + - ``isomorphism`` -- boolean (default: ``False``); if ``True``, then an isomorphism from ``self`` and the isomorphic group and its inverse is also returned EXAMPLES:: @@ -3412,7 +3408,7 @@ def epimorphisms(self, H): INPUT: - - `H` -- another group + - ``H`` -- another group EXAMPLES:: @@ -3461,7 +3457,7 @@ def BraidGroup(n=None, names='s'): group is assumed to have one more strand than generators. - ``names`` -- string or list/tuple/iterable of strings (default: - ``'x'``). The generator names or name prefix. + ``'x'``); the generator names or name prefix EXAMPLES:: diff --git a/src/sage/groups/cactus_group.py b/src/sage/groups/cactus_group.py index c8d6ba7241f..c1c1f696992 100644 --- a/src/sage/groups/cactus_group.py +++ b/src/sage/groups/cactus_group.py @@ -78,7 +78,7 @@ def __init__(self, n): sage: J3 = groups.misc.Cactus(3) sage: it = iter(J3) sage: elts = [next(it) for _ in range(100)] - sage: TestSuite(J3).run(elements=elts[::7], skip="_test_enumerated_set_contains") + sage: TestSuite(J3).run(elements=elts[::7], skip='_test_enumerated_set_contains') We run this test separately because the words grow very long, very quickly. This means the code needs to check a lot of normalizations, @@ -135,7 +135,7 @@ def _WG(self): G = Graph([list(range(len(PS))), [[i,j,-1] for j in range(1, len(PS)) for i in range(j) if PS[i] & PS[j] not in [frozenset(), PS[i], PS[j]]] - ], format="vertices_and_edges") + ], format='vertices_and_edges') self._subsets = PS self._subsets_inv = {X: i for i,X in enumerate(PS)} return G diff --git a/src/sage/groups/class_function.py b/src/sage/groups/class_function.py index 5d4dc0c1505..1e69c3d6080 100644 --- a/src/sage/groups/class_function.py +++ b/src/sage/groups/class_function.py @@ -4,7 +4,7 @@ This module implements a wrapper of GAP's ClassFunction function. -.. NOTE: +.. NOTE:: The ordering of the columns of the character table of a group corresponds to the ordering of the list. However, in general there is @@ -250,9 +250,7 @@ def domain(self): r""" Return the domain of the ``self``. - OUTPUT: - - The underlying group of the class function. + OUTPUT: the underlying group of the class function EXAMPLES:: @@ -293,7 +291,7 @@ def __call__(self, g): def __add__(self, other): r""" - Return the sum of the characters of ``self`` and other. + Return the sum of the characters of ``self`` and ``other``. INPUT: @@ -483,14 +481,14 @@ def symmetric_power(self, n): def exterior_power(self, n): r""" - Return the antisymmetrized product of ``self`` with itself ``n`` + Return the antisymmetrized product of ``self`` with itself `n` times. INPUT: - - ``n`` -- positive integer. + - ``n`` -- positive integer - OUTPUT: the ``n``-th antisymmetrized power of ``self`` as a :class:`ClassFunction` + OUTPUT: the `n`-th antisymmetrized power of ``self`` as a :class:`ClassFunction` EXAMPLES:: @@ -509,7 +507,7 @@ def exterior_power(self, n): def scalar_product(self, other): r""" - Return the scalar product of ``self`` with other. + Return the scalar product of ``self`` with ``other``. EXAMPLES:: @@ -540,7 +538,7 @@ def is_irreducible(self): def degree(self): r""" - Return the degree of the character self. + Return the degree of the character ``self``. EXAMPLES:: diff --git a/src/sage/groups/cubic_braid.py b/src/sage/groups/cubic_braid.py index 2d8952e3ab7..61db70925e1 100644 --- a/src/sage/groups/cubic_braid.py +++ b/src/sage/groups/cubic_braid.py @@ -22,7 +22,7 @@ Coxeter realized these groups as subgroups of unitary groups with respect to a certain Hermitian form over the complex numbers (in fact over `\QQ` -adjoined with a primitive 12-th root of unity). +adjoined with a primitive `12`-th root of unity). In "Einige endliche Faktorgruppen der Zopfgruppen" (Math. Z., 163 (1978), 291-302) J. Assion considered two series `S(m)` and `U(m)` of finite @@ -368,7 +368,7 @@ def burau_matrix(self, root_bur=None, domain=None, characteristic=None, - ``root_bur`` -- six (resp. twelfth) root of unity in some field (default: root of unity over `\QQ`) - - ``domain`` -- (default: cyclotomic field of order 3 and degree 2, resp. + - ``domain`` -- (default: cyclotomic field of order 3 and degree 2, resp. the domain of `root_bur` if given) base ring for the Burau matrix - ``characteristic`` -- integer giving the characteristic of the domain (default: 0 or the characteristic of ``domain`` if given) @@ -669,7 +669,7 @@ class type(Enum): r""" Enum class to select the type of the group: - - ``Coxeter`` -- ``'C'`` the full cubic braid group. + - ``Coxeter`` -- ``'C'`` the full cubic braid group - ``AssionS`` -- ``'S'`` finite factor group of type S considered by Assion - ``AssionU`` -- ``'U'`` finite factor group of type U considered by Assion @@ -1040,7 +1040,7 @@ def _create_classical_realization(self, just_embedded=False): - self._classical_group This is the classical group returned by as_classical_group method. - self._classical_base_group this only differs in special cases for Assion groups from the former. - self._classical_invariant_form invariant form of the classical base group. - - self._centralizing_matrix for Assion groups: element in classical base group commuting with self. + - self._centralizing_matrix for Assion groups: element in classical base group commuting with ``self``. - self._centralizing_element image under natural map of the former one in the projective classical group. - self._classical_embedding as subgroup of classical base group (if different from classical group). @@ -1150,7 +1150,7 @@ def create_sympl_realization(self, m): INPUT: - - ``m`` -- integer; the dimension of the classical groups + - ``m`` -- integer; the dimension of the classical groups vector-space of operation The function calculates the centralizing matrix and the @@ -1223,7 +1223,7 @@ def create_unitary_realization(self, m): INPUT: - - ``m`` -- integer; the dimension of the classical groups + - ``m`` -- integer; the dimension of the classical groups vector-space of operation The function calculates the centralizing_matrix and the @@ -1469,7 +1469,7 @@ def as_matrix_group(self, root_bur=None, domain=None, characteristic=None, var=' - ``root_bur`` -- (default: root of unity over `\QQ`) six (resp. twelfth) root of unity in some field - - ``domain`` -- (default: cyclotomic field of order 3 and degree 2, resp. + - ``domain`` -- (default: cyclotomic field of order 3 and degree 2, resp. the domain of ``root_bur`` if given) base ring for the Burau matrix - ``characteristic`` -- integer (optional); the characteristic of the domain; if none of the keywords ``root_bur``, ``domain`` and diff --git a/src/sage/groups/finitely_presented.py b/src/sage/groups/finitely_presented.py index 4bb52ee4efb..4ac2faa783b 100644 --- a/src/sage/groups/finitely_presented.py +++ b/src/sage/groups/finitely_presented.py @@ -319,7 +319,7 @@ def __call__(self, *values, **kwds): INPUT: - - ``*values`` -- a list/tuple/iterable of the same length as + - ``*values`` -- list/tuple/iterable of the same length as the number of generators - ``check=True`` -- boolean keyword (default: ``True``); whether to @@ -509,7 +509,7 @@ def __repr__(self): def free_group(self): """ - The free group after which the rewriting system is defined + The free group after which the rewriting system is defined. EXAMPLES:: @@ -945,7 +945,7 @@ def as_permutation_group(self, limit=4096000): A Sage :func:`~sage.groups.perm_gps.permgroup.PermutationGroup`. If the number of cosets exceeds the given ``limit``, a - :class:`ValueError` is returned. + :exc:`ValueError` is returned. EXAMPLES:: @@ -1003,10 +1003,10 @@ def direct_product(self, H, reduced=False, new_names=True): - ``H`` -- a finitely presented group - - ``reduced`` -- (default: ``False``) boolean; if ``True``, then + - ``reduced`` -- boolean (default: ``False``); if ``True``, then attempt to reduce the presentation of the product group - - ``new_names`` -- (default: ``True``) boolean; If ``True``, then + - ``new_names`` -- boolean (default: ``True``); if ``True``, then lexicographical variable names are assigned to the generators of the group to be returned. If ``False``, the group to be returned keeps the generator names of the two groups forming the direct @@ -1115,23 +1115,23 @@ def semidirect_product(self, H, hom, check=True, reduced=False): INPUT: - - ``H`` -- Finitely presented group which is implicitly acted on + - ``H`` -- finitely presented group which is implicitly acted on by ``self`` and can be naturally embedded as a normal subgroup - of the semidirect product. + of the semidirect product - - ``hom`` -- Homomorphism from ``self`` to the automorphism group + - ``hom`` -- homomorphism from ``self`` to the automorphism group of ``H``. Given as a pair, with generators of ``self`` in the first slot and the images of the corresponding generators in the second. These images must be automorphisms of ``H``, given again as a pair of generators and images. - - ``check`` -- Boolean (default ``True``). If ``False`` the defining + - ``check`` -- boolean (default: ``True``); if ``False`` the defining homomorphism and automorphism images are not tested for validity. This test can be costly with large groups, so it can be bypassed if the user is confident that his morphisms are valid. - - ``reduced`` -- Boolean (default ``False``). If ``True`` then the - method attempts to reduce the presentation of the output group. + - ``reduced`` -- boolean (default: ``False``); if ``True`` then the + method attempts to reduce the presentation of the output group OUTPUT: @@ -1375,17 +1375,17 @@ def abelianization_to_algebra(self, ring=QQ): INPUT: - - ``ring`` -- (default: ``QQ``); the base ring for + - ``ring`` -- (default: ``QQ``) the base ring for the group algebra of ``self`` OUTPUT: - ``ab`` -- the abelianization of ``self`` as a finitely presented group - with a minimal number `n` of generators. - - ``R`` -- a Laurent polynomial ring with `n` variables with base ring ``ring``. - - ``ideal`` -- a list of generators of an ideal ``I`` in ``R`` such that ``R/I`` + with a minimal number `n` of generators + - ``R`` -- a Laurent polynomial ring with `n` variables with base ring ``ring`` + - ``ideal`` -- list of generators of an ideal ``I`` in ``R`` such that ``R/I`` is the group algebra of the abelianization over ``ring`` - - ``image`` -- a list with the images of the generators of ``self`` in ``R/I`` + - ``image`` -- list with the images of the generators of ``self`` in ``R/I`` EXAMPLES:: @@ -1736,7 +1736,7 @@ def characteristic_varieties(self, ring=QQ, matrix_ideal=None, groebner=False): INPUT: - ``ring`` -- (default: ``QQ``) the base ring of the group algebra - - ``groebner`` -- boolean (default: ``False``); If set to + - ``groebner`` -- boolean (default: ``False``); if set to ``True`` the minimal associated primes of the ideals and their groebner bases are computed; ignored if the base ring is not a field diff --git a/src/sage/groups/fqf_orthogonal.py b/src/sage/groups/fqf_orthogonal.py index 47dac17281b..5da64f03212 100644 --- a/src/sage/groups/fqf_orthogonal.py +++ b/src/sage/groups/fqf_orthogonal.py @@ -64,7 +64,7 @@ class FqfIsometry(AbelianGroupAutomorphism): - ``parent`` -- the parent :class:`~FqfOrthogonalGroup` - ``x`` -- a libgap element - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) EXAMPLES:: @@ -275,7 +275,7 @@ def _preserves_form(self, f): INPUT: - Something that acts on the domain. + - ``f`` -- something that acts on the domain EXAMPLES:: @@ -387,10 +387,10 @@ class ActionOnFqf(Action): INPUT: - - ``orthogonal_grp`` -- an instance of :class:`GroupOfIsometries` + - ``orthogonal_grp`` -- an instance of :class:`GroupOfIsometries` - ``fqf`` -- a torsion quadratic module - - ``on_subquotient`` -- bool (default: ``False``) - - ``is_left`` -- bool (default: ``False``) + - ``on_subquotient`` -- boolean (default: ``False``) + - ``is_left`` -- boolean (default: ``False``) EXAMPLES:: @@ -407,7 +407,7 @@ class ActionOnFqf(Action): """ def __init__(self, orthogonal_grp, fqf, on_subquotient=False, is_left=False): r""" - Initialize the action + Initialize the action. TESTS:: @@ -495,12 +495,10 @@ def _isom_fqf(A, B=None): - ``A`` -- a torsion quadratic module - ``B`` -- (default: ``None``) a torsion quadratic module - OUTPUT: - - A list of generators of the orthogonal group of A. + OUTPUT: list of generators of the orthogonal group of A If ``B`` is given, this returns instead a single isometry of `A` and `B` - or raises a :class:`ValueError` if `A` and `B` are not isometric. + or raises a :exc:`ValueError` if `A` and `B` are not isometric. EXAMPLES:: @@ -525,9 +523,9 @@ def orbits(G, L): INPUT: - ``G`` -- an fqf_orthognal group - - ``L`` -- a list of tuples of elements of the domain of ``G`` + - ``L`` -- list of tuples of elements of the domain of ``G`` - A list of orbit representatives of `L` + OUTPUT: list of orbit representatives of `L` """ D = G.invariant_form() A = G.domain() diff --git a/src/sage/groups/free_group.py b/src/sage/groups/free_group.py index 09eb12d6a1c..207c80ea348 100644 --- a/src/sage/groups/free_group.py +++ b/src/sage/groups/free_group.py @@ -115,7 +115,7 @@ def _lexi_gen(zeroes=False): Python generator object which outputs a character from the alphabet on each ``next()`` call in lexicographical order. The integer `i` is appended - to the output string on the `i^{th}` iteration through the alphabet. + to the output string on the `i`-th iteration through the alphabet. EXAMPLES:: @@ -142,7 +142,6 @@ def _lexi_gen(zeroes=False): sage: ls = [next(test) for i in range(500)] sage: ls[234], ls[260] ('a9', 'a10') - """ count = Integer(0) while True: @@ -243,7 +242,7 @@ def _latex_(self): r""" Return a LaTeX representation. - OUTPUT: a string; a valid LaTeX math command sequence + OUTPUT: string; a valid LaTeX math command sequence EXAMPLES:: @@ -362,14 +361,14 @@ def fox_derivative(self, gen, im_gens=None, ring=None): derivative will be computed. If this is `x_j`, then the method will return `\partial_j`. - - ``im_gens`` (optional) -- the images of the generators + - ``im_gens`` -- (optional) the images of the generators (given as a list or iterable). This is the list `(a_1, a_2, \ldots, a_n)`. If not provided, it defaults to `(x_1, x_2, \ldots, x_n)` in the group ring `\ZZ [F]`. - - ``ring`` (optional) -- the ring in which the elements + - ``ring`` -- (optional) the ring in which the elements of the list `(a_1, a_2, \ldots, a_n)` lie. If not provided, this ring is inferred from these elements. @@ -488,7 +487,7 @@ def syllables(self): OUTPUT: The tuple of syllables. Each syllable is given as a pair - `(x_i, e_i)` consisting of a generator and a non-zero integer. + `(x_i, e_i)` consisting of a generator and a nonzero integer. EXAMPLES:: @@ -606,7 +605,7 @@ def FreeGroup(n=None, names='x', index_set=None, abelian=False, **kwds): - ``index_set`` -- (optional) an index set for the generators; if specified then the optional keyword ``abelian`` can be used - - ``abelian`` -- (default: ``False``) whether to construct a free + - ``abelian`` -- boolean (default: ``False``); whether to construct a free abelian group or a free group .. NOTE:: @@ -724,7 +723,7 @@ def wrap_FreeGroup(libgap_free_group): class FreeGroup_class(UniqueRepresentation, Group, ParentLibGAP): """ - A class that wraps GAP's FreeGroup + A class that wraps GAP's FreeGroup. See :func:`FreeGroup` for details. @@ -743,7 +742,7 @@ def __init__(self, generator_names, libgap_free_group=None): INPUT: - - ``generator_names`` -- a tuple of strings; the names of the + - ``generator_names`` -- tuple of strings; the names of the generators - ``libgap_free_group`` -- a LibGAP free group (default: ``None``); @@ -907,7 +906,7 @@ def quotient(self, relations, **kwds): INPUT: - - ``relations`` -- a list/tuple/iterable with the elements of + - ``relations`` -- list/tuple/iterable with the elements of the free group - further named arguments, that are passed to the constructor of a finitely presented group diff --git a/src/sage/groups/galois_group.py b/src/sage/groups/galois_group.py index 36495c846ad..5a4e706272d 100644 --- a/src/sage/groups/galois_group.py +++ b/src/sage/groups/galois_group.py @@ -37,7 +37,7 @@ def _alg_key(self, algorithm=None, recompute=False): sage: R. = ZZ[] sage: K. = NumberField(x^3 + 2*x + 2) # needs sage.rings.number_field sage: G = K.galois_group() # needs sage.rings.number_field - sage: _alg_key(G, algorithm="pari", recompute=True) # needs sage.rings.number_field + sage: _alg_key(G, algorithm='pari', recompute=True) # needs sage.rings.number_field 'pari' """ if recompute: @@ -56,7 +56,7 @@ class _GMixin: @lazy_attribute def _default_algorithm(self): """ - A string, the default algorithm used for computing the Galois group + A string, the default algorithm used for computing the Galois group. EXAMPLES:: diff --git a/src/sage/groups/galois_group_perm.py b/src/sage/groups/galois_group_perm.py index 3b81e0d5908..61a6e709c01 100644 --- a/src/sage/groups/galois_group_perm.py +++ b/src/sage/groups/galois_group_perm.py @@ -17,7 +17,7 @@ class GaloisGroup_perm(_GaloisMixin, PermutationGroup_generic): - ``field`` -- a field, separable over its base - - ``names`` -- a string or tuple of length 1, giving a variable name for + - ``names`` -- string or tuple of length 1, giving a variable name for the splitting field - ``gc_numbering`` -- boolean, whether to express permutations in terms of @@ -88,7 +88,7 @@ def _deg(self): r""" The number of moved points in the permutation representation. - This will be the degree of the original number field if `_gc_numbering`` + This will be the degree of the original number field if ``_gc_numbering`` is ``False``, or the degree of the Galois closure otherwise. EXAMPLES:: diff --git a/src/sage/groups/generic.py b/src/sage/groups/generic.py index e676bc547ed..c3831eb2bc5 100644 --- a/src/sage/groups/generic.py +++ b/src/sage/groups/generic.py @@ -300,10 +300,10 @@ def __init__(self, P, n, P0=None, indexed=False, operation='+', op=None): INPUT: - - ``P`` -- step value: any Sage object on which a binary operation is defined - - ``n`` -- number of multiples: non-negative integer - - ``P0`` -- offset (default 0): Sage object which can be 'added' to P - - ``indexed`` -- boolean (default ``False``) + - ``P`` -- step value; any Sage object on which a binary operation is defined + - ``n`` -- number of multiples; nonnegative integer + - ``P0`` -- offset (default: 0); Sage object which can be 'added' to P + - ``indexed`` -- boolean (default: ``False``) If ``indexed==False``, then the iterator delivers ``P0+i*P`` (if ``operation=='+'``) or ``P0*P**i`` (if @@ -392,13 +392,13 @@ def bsgs(a, b, bounds, operation='*', identity=None, inverse=None, op=None): - ``bounds`` -- a 2-tuple of integers ``(lower,upper)`` with ``0<=lower<=upper`` - ``operation`` -- string: ``'*'``, ``'+'``, other - ``identity`` -- the identity element of the group - - ``inverse()`` -- function of 1 argument ``x``, returning inverse of ``x`` - - ``op()`` -- function of 2 arguments ``x``, ``y`` returning ``x*y`` in the group + - ``inverse`` -- function of 1 argument ``x``, returning inverse of ``x`` + - ``op`` -- function of 2 arguments ``x``, ``y`` returning ``x*y`` in the group OUTPUT: An integer `n` such that `a^n = b` (or `na = b`). If no - such `n` exists, this function raises a :class:`ValueError` exception. + such `n` exists, this function raises a :exc:`ValueError` exception. .. NOTE:: @@ -526,11 +526,11 @@ def discrete_log_rho(a, base, ord=None, operation='*', identity=None, inverse=No - ``base`` -- a group element - ``ord`` -- the order of ``base`` or ``None``, in this case we try to compute it - - ``operation`` -- a string (default: ``'*'``) denoting whether we + - ``operation`` -- string (default: ``'*'``); denoting whether we are in an additive group or a multiplicative one - ``identity`` -- the group's identity - - ``inverse()`` -- function of 1 argument ``x``, returning inverse of ``x`` - - ``op()`` -- function of 2 arguments ``x``, ``y``, returning ``x*y`` in the group + - ``inverse`` -- function of 1 argument ``x``, returning inverse of ``x`` + - ``op`` -- function of 2 arguments ``x``, ``y``, returning ``x*y`` in the group - ``hash_function`` -- having an efficient hash function is critical for this algorithm (see examples) @@ -570,7 +570,7 @@ def discrete_log_rho(a, base, ord=None, operation='*', identity=None, inverse=No ... ValueError: for Pollard rho algorithm the order of the group must be prime - If it fails to find a suitable logarithm, it raises a :class:`ValueError`:: + If it fails to find a suitable logarithm, it raises a :exc:`ValueError`:: sage: I = IntegerModRing(171980) sage: discrete_log_rho(I(31002), I(15501)) # needs sage.libs.pari @@ -717,7 +717,7 @@ def discrete_log(a, base, ord=None, bounds=None, operation='*', identity=None, i assuming that ``ord`` is a multiple of the order of the base `b`. If ``ord`` is not specified, an attempt is made to compute it. - If no such `n` exists, this function raises a :class:`ValueError` exception. + If no such `n` exists, this function raises a :exc:`ValueError` exception. .. WARNING:: @@ -984,14 +984,14 @@ def discrete_log_lambda(a, base, bounds, operation='*', identity=None, inverse=N INPUT: - - a -- a group element - - base -- a group element - - bounds -- a couple (lb,ub) representing the range where we look for a logarithm - - operation -- string: '+', '*' or 'other' - - identity -- the identity element of the group - - inverse() -- function of 1 argument ``x`` returning inverse of ``x`` - - op() -- function of 2 arguments ``x``, ``y`` returning ``x*y`` in the group - - hash_function -- having an efficient hash function is critical for this algorithm + - ``a`` -- a group element + - ``base`` -- a group element + - ``bounds`` -- a couple (lb,ub) representing the range where we look for a logarithm + - ``operation`` -- string: '+', '*' or 'other' + - ``identity`` -- the identity element of the group + - ``inverse`` -- function of 1 argument ``x`` returning inverse of ``x`` + - ``op`` -- function of 2 arguments ``x``, ``y`` returning ``x*y`` in the group + - ``hash_function`` -- having an efficient hash function is critical for this algorithm OUTPUT: integer `n` such that `a=base^n` (or `a=n*base`) @@ -1025,7 +1025,6 @@ def discrete_log_lambda(a, base, bounds, operation='*', identity=None, inverse=N AUTHOR: -- Yann Laigle-Chapuy (2009-01-25) - """ from sage.rings.integer import Integer from operator import mul, add @@ -1201,13 +1200,13 @@ def order_from_multiple(P, m, plist=None, factorization=None, check=True, INPUT: - ``P`` -- a Sage object which is a group element - - ``m`` -- a Sage integer which is a multiple of the order of ``P``, + - ``m`` -- Sage integer which is a multiple of the order of ``P``, i.e. we require that ``m*P=0`` (or ``P**m=1``) - ``check`` -- a Boolean (default: ``True``), indicating whether we check if ``m`` really is a multiple of the order - ``factorization`` -- the factorization of ``m``, or ``None`` in which case this function will need to factor ``m`` - - ``plist`` -- a list of the prime factors of ``m``, or ``None``. Kept for compatibility only, + - ``plist`` -- list of the prime factors of ``m``, or ``None``. Kept for compatibility only, prefer the use of ``factorization`` - ``operation`` -- string: ``'+'`` (default), ``'*'`` or ``None`` - ``identity`` -- the identity element of the group @@ -1354,14 +1353,14 @@ def order_from_bounds(P, bounds, d=None, operation='+', - ``d`` -- (optional) a positive integer; only ``m`` which are multiples of this will be considered - - ``operation`` -- string: ``'+'`` (default ) or ``'*'`` or other. + - ``operation`` -- string; ``'+'`` (default) or ``'*'`` or other. If other, the following must be supplied: - - ``identity`` -- the identity element for the group; - - ``inverse()`` -- a function of one argument giving the inverse - of a group element; - - ``op()`` -- a function of 2 arguments defining the group binary - operation. + - ``identity`` -- the identity element for the group + - ``inverse`` -- a function of one argument giving the inverse + of a group element + - ``op`` -- a function of 2 arguments defining the group binary + operation .. NOTE:: @@ -1540,14 +1539,14 @@ def merge_points(P1, P2, operation='+', - ``P1`` -- a pair `(g_1,n_1)` where `g_1` is a group element of order `n_1` - ``P2`` -- a pair `(g_2,n_2)` where `g_2` is a group element of order `n_2` - - ``operation`` -- string: ``'+'`` (default) or ``'*'`` or other. If + - ``operation`` -- string; ``'+'`` (default) or ``'*'`` or other. If other, the following must be supplied: - - ``identity`` -- the identity element for the group; - - ``inverse()`` -- a function of one argument giving the inverse - of a group element; - - ``op()`` -- a function of 2 arguments defining the group - binary operation. + - ``identity`` -- the identity element for the group + - ``inverse`` -- a function of one argument giving the inverse + of a group element + - ``op`` -- a function of 2 arguments defining the group + binary operation OUTPUT: a pair `(g_3,n_3)` where `g_3` has order `n_3=\hbox{lcm}(n_1,n_2)` @@ -1626,7 +1625,7 @@ def structure_description(G, latex=False): INPUT: - - ``latex`` -- a boolean (default: ``False``); if ``True``, return a + - ``latex`` -- boolean (default: ``False``); if ``True``, return a LaTeX formatted string OUTPUT: string diff --git a/src/sage/groups/group.pyx b/src/sage/groups/group.pyx index 0a62fa0f12e..b5047594a9c 100644 --- a/src/sage/groups/group.pyx +++ b/src/sage/groups/group.pyx @@ -286,7 +286,7 @@ cdef class FiniteGroup(Group): def __init__(self, base=None, category=None): """ - The Python constructor + The Python constructor. TESTS:: diff --git a/src/sage/groups/group_exp.py b/src/sage/groups/group_exp.py index 434608c5264..a8677c05e4c 100644 --- a/src/sage/groups/group_exp.py +++ b/src/sage/groups/group_exp.py @@ -72,7 +72,7 @@ class GroupExp(Functor): sage: L = RootSystem(['A',2]).ambient_space() sage: EL = E(L) - sage: W = L.weyl_group(prefix="s") + sage: W = L.weyl_group(prefix='s') sage: s2 = W.simple_reflection(2) sage: def my_action(mu): ....: return s2.action(mu) @@ -88,7 +88,6 @@ class GroupExp(Functor): (2, 3, 2) sage: y.parent() Multiplicative form of Ambient space of the Root system of type ['A', 2] - """ def __init__(self): r""" @@ -194,7 +193,6 @@ class GroupExpElement(ElementWrapper, MultiplicativeGroupElement): Multiplicative form of Vector space of dimension 2 over Rational Field sage: EG(vector(QQ, (1, -3))) == z True - """ def __init__(self, parent, x): r""" diff --git a/src/sage/groups/group_semidirect_product.py b/src/sage/groups/group_semidirect_product.py index 7adc1868f8d..7287a79f614 100644 --- a/src/sage/groups/group_semidirect_product.py +++ b/src/sage/groups/group_semidirect_product.py @@ -33,8 +33,8 @@ def _repr_(self): sage: def twist(x,y): ....: return y - sage: GroupSemidirectProduct(WeylGroup(['A',2],prefix="s"), # indirect doctest - ....: WeylGroup(['A',3],prefix="t"), twist) + sage: GroupSemidirectProduct(WeylGroup(['A',2],prefix='s'), # indirect doctest + ....: WeylGroup(['A',3],prefix='t'), twist) Semidirect product of Weyl Group of type ['A', 2] (as a matrix group acting on the ambient space) acting on Weyl Group of type ['A', 3] @@ -72,7 +72,7 @@ def __invert__(self): sage: L = RootSystem(['A',2]).root_lattice() sage: from sage.groups.group_exp import GroupExp sage: EL = GroupExp()(L) - sage: W = L.weyl_group(prefix="s") + sage: W = L.weyl_group(prefix='s') sage: def twist(w,v): ....: return EL(w.action(v.value)) sage: G = GroupSemidirectProduct(W, EL, twist, prefix1='t') @@ -102,7 +102,7 @@ def to_opposite(self): Root lattice of the Root system of type ['A', 2] sage: from sage.groups.group_exp import GroupExp sage: EL = GroupExp()(L) - sage: W = L.weyl_group(prefix="s"); W + sage: W = L.weyl_group(prefix='s'); W Weyl Group of type ['A', 2] (as a matrix group acting on the root lattice) sage: def twist(w,v): @@ -141,14 +141,14 @@ class GroupSemidirectProduct(CartesianProduct): INPUT: - - ``G`` and ``H`` -- multiplicative groups + - ``G``, ``H`` -- multiplicative groups - ``twist`` -- (default: ``None``) a function defining a homomorphism (see below) - - ``act_to_right`` -- ``True`` or ``False`` (default: ``True``) - - ``prefix0`` -- (default: ``None``) optional string - - ``prefix1`` -- (default: ``None``) optional string - - ``print_tuple`` -- ``True`` or ``False`` (default: ``False``) - - ``category`` -- A category (default: ``Groups()``) + - ``act_to_right`` -- boolean (default: ``True``) + - ``prefix0`` -- string (default: ``None``) + - ``prefix1`` -- string (default: ``None``) + - ``print_tuple`` -- boolean (default: ``False``) + - ``category`` -- a category (default: ``Groups()``) A semidirect product of groups `G` and `H` is a group structure on the Cartesian product `G \times H` whose product agrees with that @@ -228,7 +228,7 @@ class GroupSemidirectProduct(CartesianProduct): sage: # needs sage.rings.number_field sage: cartan_type = CartanType(['A',2]) - sage: W = WeylGroup(cartan_type, prefix="s") + sage: W = WeylGroup(cartan_type, prefix='s') sage: def twist(w,v): ....: return w*v*(~w) sage: WW = GroupSemidirectProduct(W, W, twist=twist, print_tuple=True) @@ -256,8 +256,8 @@ def __init__(self, G, H, twist=None, act_to_right=True, prefix0=None, ....: return y sage: import __main__ sage: __main__.twist = twist - sage: G = GroupSemidirectProduct(WeylGroup(['A',2],prefix="s"), - ....: WeylGroup(['A',3],prefix="t"), twist) + sage: G = GroupSemidirectProduct(WeylGroup(['A',2],prefix='s'), + ....: WeylGroup(['A',3],prefix='t'), twist) sage: TestSuite(G).run() The ``__main__`` business is a trick to pass the pickling test. @@ -299,8 +299,8 @@ def act_to_right(self): sage: def twist(x,y): ....: return y - sage: GroupSemidirectProduct(WeylGroup(['A',2],prefix="s"), - ....: WeylGroup(['A',3],prefix="t"), twist).act_to_right() + sage: GroupSemidirectProduct(WeylGroup(['A',2],prefix='s'), + ....: WeylGroup(['A',3],prefix='t'), twist).act_to_right() True """ return self._act_to_right @@ -313,8 +313,8 @@ def _repr_(self): sage: def twist(x,y): ....: return y - sage: GroupSemidirectProduct(WeylGroup(['A',2],prefix="s"), # indirect doctest - ....: WeylGroup(['A',3],prefix="t"), twist) + sage: GroupSemidirectProduct(WeylGroup(['A',2],prefix='s'), # indirect doctest + ....: WeylGroup(['A',3],prefix='t'), twist) Semidirect product of Weyl Group of type ['A', 2] (as a matrix group acting on the ambient space) acting on Weyl Group of type ['A', 3] (as a matrix group acting on the ambient space) @@ -336,8 +336,8 @@ def _element_constructor_(self, x): ....: return y sage: import __main__ sage: __main__.twist = twist - sage: g = GroupSemidirectProduct(WeylGroup(['A',2],prefix="s"), - ....: WeylGroup(['A',3],prefix="t"), twist).an_element() + sage: g = GroupSemidirectProduct(WeylGroup(['A',2],prefix='s'), + ....: WeylGroup(['A',3],prefix='t'), twist).an_element() sage: TestSuite(g).run() """ def type_error(): @@ -493,8 +493,8 @@ def construction(self): sage: def twist(x,y): ....: return y - sage: H = GroupSemidirectProduct(WeylGroup(['A',2],prefix="s"), - ....: WeylGroup(['A',3],prefix="t"), twist) + sage: H = GroupSemidirectProduct(WeylGroup(['A',2],prefix='s'), + ....: WeylGroup(['A',3],prefix='t'), twist) sage: H.construction() """ return None diff --git a/src/sage/groups/libgap_mixin.py b/src/sage/groups/libgap_mixin.py index 931d22ccdc5..3491c9f9db0 100644 --- a/src/sage/groups/libgap_mixin.py +++ b/src/sage/groups/libgap_mixin.py @@ -9,7 +9,7 @@ If your group implementation uses libgap, then you should add :class:`GroupMixinLibGAP` as the first class that you are deriving from. This ensures that it properly overrides any default methods that -just raise :class:`NotImplementedError`. +just raise :exc:`NotImplementedError`. """ from sage.libs.gap.libgap import libgap @@ -578,7 +578,7 @@ def group_id(self): def exponent(self): r""" - Computes the exponent of the group. + Compute the exponent of the group. The exponent `e` of a group `G` is the LCM of the orders of its elements, that is, `e` is the smallest integer such that `g^e = 1` @@ -678,7 +678,7 @@ def character(self, values): INPUT: - - ``values`` -- a list of values of the character + - ``values`` -- list of values of the character OUTPUT: a group character diff --git a/src/sage/groups/libgap_morphism.py b/src/sage/groups/libgap_morphism.py index e0f75e7bd4f..3bcb28c1f94 100644 --- a/src/sage/groups/libgap_morphism.py +++ b/src/sage/groups/libgap_morphism.py @@ -48,8 +48,8 @@ class GroupMorphism_libgap(Morphism): - ``homset`` -- the parent - ``gap_hom`` -- a :class:`sage.libs.gap.element.GapElement` consisting of a group homomorphism - - ``check`` -- (default: ``True``) check if the ``gap_hom`` is a group - homomorphism; this can be expensive + - ``check`` -- boolean (default: ``True``); check if the ``gap_hom`` is a group + homomorphism (this can be expensive) EXAMPLES:: diff --git a/src/sage/groups/libgap_wrapper.pyx b/src/sage/groups/libgap_wrapper.pyx index ddba766e94d..fe09dc080c1 100644 --- a/src/sage/groups/libgap_wrapper.pyx +++ b/src/sage/groups/libgap_wrapper.pyx @@ -88,7 +88,7 @@ class ParentLibGAP(SageObject): - ``libgap_parent`` -- the libgap element that is the parent in GAP - - ``ambient`` -- A derived class of :class:`ParentLibGAP` or + - ``ambient`` -- a derived class of :class:`ParentLibGAP` or ``None`` (default); the ambient class if ``libgap_parent`` has been defined as a subgroup @@ -216,7 +216,7 @@ class ParentLibGAP(SageObject): INPUT: - - ``generators`` -- a list/tuple/iterable of group elements. + - ``generators`` -- list/tuple/iterable of group elements OUTPUT: the subgroup generated by ``generators`` @@ -481,7 +481,7 @@ cdef class ElementLibGAP(MultiplicativeGroupElement): def __init__(self, parent, libgap_element): """ - The Python constructor + The Python constructor. TESTS:: @@ -595,7 +595,7 @@ cdef class ElementLibGAP(MultiplicativeGroupElement): r""" Return a LaTeX representation. - OUTPUT: a string; a valid LaTeX math command sequence + OUTPUT: string; a valid LaTeX math command sequence EXAMPLES:: diff --git a/src/sage/groups/lie_gps/nilpotent_lie_group.py b/src/sage/groups/lie_gps/nilpotent_lie_group.py index 1164f28e056..aa9f6bd0dc8 100644 --- a/src/sage/groups/lie_gps/nilpotent_lie_group.py +++ b/src/sage/groups/lie_gps/nilpotent_lie_group.py @@ -83,7 +83,7 @@ class NilpotentLieGroup(Group, DifferentiableManifold): - ``L`` -- the Lie algebra of the Lie group; must be a finite dimensional nilpotent Lie algebra with basis over a topological field, e.g. `\QQ` or `\RR` - - ``name`` -- a string; name (symbol) given to the Lie group + - ``name`` -- string; name (symbol) given to the Lie group Two types of exponential coordinates are defined on any nilpotent Lie group using the basis of the Lie algebra, diff --git a/src/sage/groups/matrix_gps/coxeter_group.py b/src/sage/groups/matrix_gps/coxeter_group.py index b6a9e211ff0..1fc089d94c4 100644 --- a/src/sage/groups/matrix_gps/coxeter_group.py +++ b/src/sage/groups/matrix_gps/coxeter_group.py @@ -176,14 +176,14 @@ class CoxeterMatrixGroup(UniqueRepresentation, FinitelyGeneratedMatrixGroup_gene We can also create Coxeter groups from Cartan types using the ``implementation`` keyword:: - sage: W = CoxeterGroup(['D',5], implementation="reflection"); W + sage: W = CoxeterGroup(['D',5], implementation='reflection'); W Finite Coxeter group over Integer Ring with Coxeter matrix: [1 3 2 2 2] [3 1 3 2 2] [2 3 1 3 3] [2 2 3 1 2] [2 2 3 2 1] - sage: W = CoxeterGroup(['H',3], implementation="reflection"); W # needs sage.libs.gap sage.rings.number_field + sage: W = CoxeterGroup(['H',3], implementation='reflection'); W # needs sage.libs.gap sage.rings.number_field Finite Coxeter group over Number Field in a with defining polynomial x^2 - 5 with a = 2.236067977499790? with Coxeter matrix: @@ -198,7 +198,7 @@ def __classcall_private__(cls, data, base_ring=None, index_set=None): EXAMPLES:: - sage: W1 = CoxeterGroup(['A',2], implementation="reflection", base_ring=ZZ) + sage: W1 = CoxeterGroup(['A',2], implementation='reflection', base_ring=ZZ) sage: W2 = CoxeterGroup([[1,3],[3,1]], index_set=(1,2)) sage: W1 is W2 True @@ -362,7 +362,7 @@ def _coerce_map_from_(self, P): sage: W2 = WeylGroup(["A",4]) sage: W._coerce_map_from_(W2) True - sage: W3 = WeylGroup(["A",4], implementation="permutation") + sage: W3 = WeylGroup(["A",4], implementation='permutation') sage: W._coerce_map_from_(W3) True sage: W4 = WeylGroup(["A",3]) @@ -513,7 +513,7 @@ def simple_reflection(self, i): EXAMPLES:: - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: W.simple_reflection(1) [-1 1 0] [ 0 1 0] @@ -727,7 +727,7 @@ def first_descent(self, side='right', index_set=None, positive=False): EXAMPLES:: - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: a,b,c = W.gens() sage: elt = b*a*c sage: elt.first_descent() @@ -766,11 +766,11 @@ def descents(self, side='right', index_set=None, positive=False): - ``index_set`` -- (default: all of them) a subset (as a list or iterable) of the nodes of the Dynkin diagram - ``side`` -- (default: ``'right'``) ``'left'`` or ``'right'`` - - ``positive`` -- (default: ``False``) boolean + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: a,b,c = W.gens() sage: elt = b*a*c sage: elt.descents() @@ -809,7 +809,7 @@ def has_right_descent(self, i): `\ell(ws) < \ell(w)` then `w(\alpha_s) < 0`. Thus `i \in I` is a right descent if `w(\alpha_{s_i}) < 0` or equivalently if the matrix representing `w` has all entries - of the `i`-th column being non-positive. + of the `i`-th column being nonpositive. INPUT: @@ -817,7 +817,7 @@ def has_right_descent(self, i): EXAMPLES:: - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: a,b,c = W.gens() sage: elt = b*a*c sage: [elt.has_right_descent(i) for i in [1, 2, 3]] @@ -836,7 +836,7 @@ def canonical_matrix(self): EXAMPLES:: - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: a,b,c = W.gens() sage: elt = a*b*c sage: elt.canonical_matrix() @@ -847,7 +847,7 @@ def canonical_matrix(self): return self.matrix() @cached_method - def action_on_root_indices(self, i, side="left"): + def action_on_root_indices(self, i, side='left'): """ Return the action on the set of roots. @@ -855,7 +855,7 @@ def action_on_root_indices(self, i, side="left"): EXAMPLES:: - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: w = W.w0 sage: w.action_on_root_indices(0) 11 @@ -896,7 +896,7 @@ def _matrix_test_right_descent(M, i, n, zero): EXAMPLES:: sage: from sage.groups.matrix_gps.coxeter_group import _matrix_test_right_descent - sage: W = CoxeterGroup(['A',3], implementation="reflection") + sage: W = CoxeterGroup(['A',3], implementation='reflection') sage: a,b,c = W.gens() sage: elt = b*a*c sage: zero = W.base_ring().zero() diff --git a/src/sage/groups/matrix_gps/finitely_generated.py b/src/sage/groups/matrix_gps/finitely_generated.py index 909e92b80cc..b8dd5b8c01d 100644 --- a/src/sage/groups/matrix_gps/finitely_generated.py +++ b/src/sage/groups/matrix_gps/finitely_generated.py @@ -83,7 +83,7 @@ def normalize_square_matrices(matrices): """ Find a common space for all matrices. - OUTPUT: a list of matrices, all elements of the same matrix space + OUTPUT: list of matrices, all elements of the same matrix space EXAMPLES:: diff --git a/src/sage/groups/matrix_gps/finitely_generated_gap.py b/src/sage/groups/matrix_gps/finitely_generated_gap.py index 70c45d59162..d3403f22f40 100644 --- a/src/sage/groups/matrix_gps/finitely_generated_gap.py +++ b/src/sage/groups/matrix_gps/finitely_generated_gap.py @@ -118,7 +118,7 @@ def as_permutation_group(self, algorithm=None, seed=None): sage: G.cardinality() 21499084800 sage: P = G.as_permutation_group() - sage: Psmaller = G.as_permutation_group(algorithm="smaller", seed=6) + sage: Psmaller = G.as_permutation_group(algorithm='smaller', seed=6) sage: P.cardinality() 21499084800 sage: P.degree() @@ -426,7 +426,7 @@ def molien_series(self, chi=None, return_series=True, prec=20, variable='t'): INPUT: - ``chi`` -- (default: trivial character) a linear group character of this group - - ``return_series`` -- boolean (default: ``True``) if ``True``, then returns + - ``return_series`` -- boolean (default: ``True``); if ``True``, then returns the Molien series as a power series, ``False`` as a rational function - ``prec`` -- integer (default: 20); power series default precision (possibly infinite, in which case it is computed lazily) @@ -835,7 +835,7 @@ def invariants_of_degree(self, deg, chi=None, R=None): INPUT: - - ``degree`` -- a positive integer + - ``degree`` -- positive integer - ``chi`` -- (default: trivial character) a linear group character of this group diff --git a/src/sage/groups/matrix_gps/group_element.pyx b/src/sage/groups/matrix_gps/group_element.pyx index 952cdc0c6c2..5d00aa727bf 100644 --- a/src/sage/groups/matrix_gps/group_element.pyx +++ b/src/sage/groups/matrix_gps/group_element.pyx @@ -127,10 +127,10 @@ cdef class MatrixGroupElement_generic(MultiplicativeGroupElement): - ``parent`` -- the parent - - ``check`` -- bool (default: ``True``); if ``True``, then + - ``check`` -- boolean (default: ``True``); if ``True``, then do some type checking - - ``convert`` -- bool (default: ``True``); if ``True``, then + - ``convert`` -- boolean (default: ``True``); if ``True``, then convert ``M`` to the right matrix space EXAMPLES:: diff --git a/src/sage/groups/matrix_gps/group_element_gap.pyx b/src/sage/groups/matrix_gps/group_element_gap.pyx index a5a635540e5..e5d7d637fdf 100644 --- a/src/sage/groups/matrix_gps/group_element_gap.pyx +++ b/src/sage/groups/matrix_gps/group_element_gap.pyx @@ -37,10 +37,10 @@ cdef class MatrixGroupElement_gap(ElementLibGAP): - ``parent`` -- the parent - - ``check`` -- bool (default: ``True``); if ``True``, do some + - ``check`` -- boolean (default: ``True``); if ``True``, do some type checking - - ``convert`` -- bool (default: ``True``); if ``True``, convert + - ``convert`` -- boolean (default: ``True``); if ``True``, convert ``M`` to the right matrix space """ def __init__(self, parent, M, check=True, convert=True): @@ -310,7 +310,7 @@ cdef class MatrixGroupElement_gap(ElementLibGAP): INPUT: - - ``gens`` -- a list/tuple/iterable of elements (or objects + - ``gens`` -- list/tuple/iterable of elements (or objects that can be converted to group elements), or ``None`` (default); by default, the generators of the parent group are used @@ -318,7 +318,7 @@ cdef class MatrixGroupElement_gap(ElementLibGAP): OUTPUT: A factorization object that contains information about the - order of factors and the exponents. A :class:`ValueError` is raised + order of factors and the exponents. A :exc:`ValueError` is raised if the group element cannot be written as a word in ``gens``. ALGORITHM: diff --git a/src/sage/groups/matrix_gps/heisenberg.py b/src/sage/groups/matrix_gps/heisenberg.py index 8a262ddf1c7..f101c27153b 100644 --- a/src/sage/groups/matrix_gps/heisenberg.py +++ b/src/sage/groups/matrix_gps/heisenberg.py @@ -122,7 +122,7 @@ def __init__(self, n=1, R=0): sage: H = groups.matrix.Heisenberg(n=2, R=4) sage: TestSuite(H).run() # long time sage: H = groups.matrix.Heisenberg(n=3) - sage: TestSuite(H).run(max_runs=30, skip="_test_elements") # long time + sage: TestSuite(H).run(max_runs=30, skip='_test_elements') # long time sage: H = groups.matrix.Heisenberg(n=2, R=GF(4)) sage: TestSuite(H).run() # long time diff --git a/src/sage/groups/matrix_gps/isometries.py b/src/sage/groups/matrix_gps/isometries.py index c39c0e3bd80..8e0df5f154b 100644 --- a/src/sage/groups/matrix_gps/isometries.py +++ b/src/sage/groups/matrix_gps/isometries.py @@ -52,15 +52,15 @@ class GroupOfIsometries(FinitelyGeneratedMatrixGroup_gap): INPUT: - - ``degree`` -- integer, the degree (matrix size) of the matrix + - ``degree`` -- integer; the degree (matrix size) of the matrix - ``base_ring`` -- ring, the base ring of the matrices - - ``gens`` -- a list of matrices over the base ring + - ``gens`` -- list of matrices over the base ring - ``invariant_bilinear_form`` -- a symmetric matrix - ``category`` -- (default: ``None``) a category of groups - - ``check`` -- bool (default: ``True``) check if the generators + - ``check`` -- boolean (default: ``True``); check if the generators preserve the bilinear form - ``invariant_submodule`` -- a submodule preserved by the group action - (default: ``None``) registers an action on this submodule + (default: ``None``); registers an action on this submodule - ``invariant_quotient_module`` -- a quotient module preserved by the group action (default: ``None``) registers an action on this quotient module @@ -267,9 +267,9 @@ class GroupActionOnSubmodule(Action): INPUT: - - ``MatrixGroup`` -- an instance of :class:`GroupOfIsometries` + - ``MatrixGroup`` -- an instance of :class:`GroupOfIsometries` - ``submodule`` -- an invariant submodule - - ``is_left`` -- bool (default: ``False``) + - ``is_left`` -- boolean (default: ``False``) EXAMPLES:: @@ -290,7 +290,7 @@ class GroupActionOnSubmodule(Action): """ def __init__(self, MatrixGroup,submodule, is_left=False): r""" - Initialize the action + Initialize the action. TESTS:: @@ -356,7 +356,7 @@ class GroupActionOnQuotientModule(Action): INPUT: - - ``MatrixGroup`` -- the group acting + - ``MatrixGroup`` -- the group acting :class:`GroupOfIsometries` - ``submodule`` -- an invariant quotient module - ``is_left`` -- boolean (default: ``False``) diff --git a/src/sage/groups/matrix_gps/linear.py b/src/sage/groups/matrix_gps/linear.py index bd77d7ce19a..113a93cca44 100644 --- a/src/sage/groups/matrix_gps/linear.py +++ b/src/sage/groups/matrix_gps/linear.py @@ -89,13 +89,13 @@ def GL(n, R, var='a'): INPUT: - - ``n`` -- a positive integer. + - ``n`` -- positive integer - - ``R`` -- ring or an integer. If an integer is specified, the - corresponding finite field is used. + - ``R`` -- ring or an integer; if an integer is specified, the + corresponding finite field is used - ``var`` -- variable used to represent generator of the finite - field, if needed. + field, if needed EXAMPLES:: @@ -310,7 +310,7 @@ def _check_matrix(self, x, *args): raise TypeError('matrix must have determinant one') else: if x.determinant() == 0: - raise TypeError('matrix must non-zero determinant') + raise TypeError('matrix must nonzero determinant') def order(self): r""" diff --git a/src/sage/groups/matrix_gps/matrix_group.py b/src/sage/groups/matrix_gps/matrix_group.py index 8cd34aa4cb1..a11ca5a4448 100644 --- a/src/sage/groups/matrix_gps/matrix_group.py +++ b/src/sage/groups/matrix_gps/matrix_group.py @@ -134,10 +134,10 @@ def _check_matrix(self, x, *args): - ``x`` -- a Sage matrix in the correct matrix space (degree and base ring) - - ``*args`` -- optional other representations of ``x``, + - ``*args`` -- (optional) other representations of ``x``, depending on the group implementation. Ignored by default - OUTPUT: a :class:`TypeError` must be raised if ``x`` is invalid + OUTPUT: a :exc:`TypeError` must be raised if ``x`` is invalid EXAMPLES:: @@ -189,7 +189,7 @@ def subgroup(self, generators, check=True): INPUT: - - ``generators`` -- a list/tuple/iterable of group elements of ``self`` + - ``generators`` -- list/tuple/iterable of group elements of ``self`` - ``check`` -- boolean (default: ``True``); whether to check that each matrix is invertible @@ -596,12 +596,12 @@ def is_trivial(self): True sage: SL(2, ZZ).is_trivial() False - sage: CoxeterGroup(['B',3], implementation="matrix").is_trivial() + sage: CoxeterGroup(['B',3], implementation='matrix').is_trivial() False TESTS:: - sage: CoxeterGroup(['A',0], implementation="matrix").is_trivial() + sage: CoxeterGroup(['A',0], implementation='matrix').is_trivial() True sage: MatrixGroup([matrix(SR, [[1,x], [0,1]])]).is_trivial() False diff --git a/src/sage/groups/matrix_gps/matrix_group_gap.py b/src/sage/groups/matrix_gps/matrix_group_gap.py index d7de4c75f6e..552fcde3ff6 100644 --- a/src/sage/groups/matrix_gps/matrix_group_gap.py +++ b/src/sage/groups/matrix_gps/matrix_group_gap.py @@ -201,7 +201,7 @@ def _check_matrix(self, x_sage, x_gap): - ``x_gap`` -- the corresponding LibGAP matrix - OUTPUT: a :class:`TypeError` must be raised if ``x`` is invalid + OUTPUT: a :exc:`TypeError` must be raised if ``x`` is invalid EXAMPLES:: @@ -228,11 +228,11 @@ def subgroup(self, generators, check=True): INPUT: - - ``generators`` -- a list/tuple/iterable of group elements of ``self`` - - ``check`` -- boolean (default: ``True``). Whether to check that each + - ``generators`` -- list/tuple/iterable of group elements of ``self`` + - ``check`` -- boolean (default: ``True``); whether to check that each matrix is invertible - OUTPUT: The subgroup generated by ``generators`` as an instance of + OUTPUT: the subgroup generated by ``generators`` as an instance of :class:`FinitelyGeneratedMatrixGroup_gap` EXAMPLES:: diff --git a/src/sage/groups/matrix_gps/named_group.py b/src/sage/groups/matrix_gps/named_group.py index 142ea68ddfb..64d2b932662 100644 --- a/src/sage/groups/matrix_gps/named_group.py +++ b/src/sage/groups/matrix_gps/named_group.py @@ -67,16 +67,15 @@ def normalize_args_vectorspace(*args, **kwds): * Degree and base ring: - - ``degree`` -- integer. The degree of the affine group, that - is, the dimension of the affine space the group is acting on. + - ``degree`` -- integer; the degree of the affine group, that + is, the dimension of the affine space the group is acting on - ``ring`` -- a ring or an integer. The base ring of the affine space. If an integer is given, it must be a prime power and the corresponding finite field is constructed. - - ``var='a'`` -- optional keyword argument to specify the finite - field generator name in the case where ``ring`` is a prime - power. + - ``var='a'`` -- (optional) keyword argument to specify the finite + field generator name in the case where ``ring`` is a prime power OUTPUT: a pair ``(degree, ring)`` @@ -136,7 +135,7 @@ def normalize_args_invariant_form(R, d, invariant_form): - ``d`` -- integer giving the dimension of the module the classical group is operating on - - ``invariant_form`` -- (optional) instances being accepted by + - ``invariant_form`` -- (optional) instances being accepted by the matrix-constructor that define a `d \times d` square matrix over R describing the bilinear form to be kept invariant by the classical group @@ -209,7 +208,7 @@ def __init__(self, degree, base_ring, special, sage_name, latex_string, the constructor of :class:`sage.groups.matrix_gps.matrix_group.MatrixGroup_generic` - - ``invariant_form`` -- (optional) square-matrix of the given + - ``invariant_form`` -- (optional) square-matrix of the given degree over the given base_ring describing a bilinear form to be kept invariant by the group diff --git a/src/sage/groups/matrix_gps/orthogonal.py b/src/sage/groups/matrix_gps/orthogonal.py index 4d0a2e00994..0e8536fed5f 100644 --- a/src/sage/groups/matrix_gps/orthogonal.py +++ b/src/sage/groups/matrix_gps/orthogonal.py @@ -112,7 +112,7 @@ def normalize_args_e(degree, ring, e): - ``ring`` -- a ring; the base ring of the affine space - - ``e`` -- integer, one of `+1`, `0`, `-1`. Only relevant for + - ``e`` -- integer; one of `+1`, `0`, `-1`. Only relevant for finite fields and if the degree is even. A parameter that distinguishes inequivalent invariant forms. diff --git a/src/sage/groups/matrix_gps/symplectic.py b/src/sage/groups/matrix_gps/symplectic.py index efafae72e3c..bbcf92b1bcf 100644 --- a/src/sage/groups/matrix_gps/symplectic.py +++ b/src/sage/groups/matrix_gps/symplectic.py @@ -69,7 +69,7 @@ def Sp(n, R, var='a', invariant_form=None): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``R`` -- ring or an integer; if an integer is specified, the corresponding finite field is used @@ -77,7 +77,7 @@ def Sp(n, R, var='a', invariant_form=None): - ``var`` -- (default: ``'a'``) variable used to represent generator of the finite field, if needed - - ``invariant_form`` -- (optional) instances being accepted by + - ``invariant_form`` -- (optional) instances being accepted by the matrix-constructor which define a `n \times n` square matrix over ``R`` describing the alternating form to be kept invariant by the symplectic group diff --git a/src/sage/groups/matrix_gps/unitary.py b/src/sage/groups/matrix_gps/unitary.py index e36e01693ca..e16ffb6a46b 100644 --- a/src/sage/groups/matrix_gps/unitary.py +++ b/src/sage/groups/matrix_gps/unitary.py @@ -171,7 +171,7 @@ def GU(n, R, var='a', invariant_form=None): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``R`` -- ring or an integer; if an integer is specified, the corresponding finite field is used @@ -283,7 +283,7 @@ def SU(n, R, var='a', invariant_form=None): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``R`` -- ring or an integer; if an integer is specified, the corresponding finite field is used diff --git a/src/sage/groups/misc_gps/argument_groups.py b/src/sage/groups/misc_gps/argument_groups.py index edbdb7b7bad..43c2ef98770 100644 --- a/src/sage/groups/misc_gps/argument_groups.py +++ b/src/sage/groups/misc_gps/argument_groups.py @@ -61,7 +61,7 @@ class AbstractArgument(MultiplicativeGroupElement): - ``element`` -- an element of parent's base - - ``normalize`` -- a boolean (default: ``True``) + - ``normalize`` -- boolean (default: ``True``) """ def __init__(self, parent, element, normalize=True): @@ -108,7 +108,7 @@ def __init__(self, parent, element, normalize=True): @staticmethod def _normalize_(element): r""" - Normalizes the given element. + Normalize the given element. INPUT: @@ -396,13 +396,13 @@ class UnitCirclePoint(AbstractArgument): - ``exponent`` -- a number (of a subset of the reals) - - ``normalize`` -- a boolean (default: ``True``) + - ``normalize`` -- boolean (default: ``True``) """ @staticmethod def _normalize_(exponent): r""" - Normalizes the given exponent so that it is in `[0,1)`. + Normalize the given exponent so that it is in `[0,1)`. INPUT: @@ -1043,7 +1043,7 @@ class ArgumentByElement(AbstractArgument): - ``element`` -- a nonzero element of the parent's base - - ``normalize`` -- a boolean (default: ``True``) + - ``normalize`` -- boolean (default: ``True``) """ def __init__(self, parent, element, normalize=True): @@ -1064,7 +1064,7 @@ def __init__(self, parent, element, normalize=True): @staticmethod def _normalize_(element): r""" - Normalizes the given element. + Normalize the given element. This is the identity for :class:`ArgumentByElement`. @@ -1380,7 +1380,7 @@ class Sign(AbstractArgument): - ``element`` -- a nonzero element of the parent's base - - ``normalize`` -- a boolean (default: ``True``) + - ``normalize`` -- boolean (default: ``True``) """ def __init__(self, parent, element, normalize=True): @@ -1402,7 +1402,7 @@ def __init__(self, parent, element, normalize=True): @staticmethod def _normalize_(element): r""" - Normalizes the given element. + Normalize the given element. This is the identity for :class:`Sign`. @@ -1697,7 +1697,7 @@ class ArgumentGroupFactory(UniqueFactory): The factory will analyze ``data`` and interpret it as ``specification`` or ``domain``. - - ``specification`` -- a string + - ``specification`` -- string The following is possible: @@ -1713,12 +1713,12 @@ class ArgumentGroupFactory(UniqueFactory): a string representing a SageMath parent which is interpreted as ``domain`` - - ``domain`` -- a SageMath parent representing a subset of the complex plane. - An instance of :class:`ArgumentByElementGroup` will be created with the given - ``domain``. + - ``domain`` -- a SageMath parent representing a subset of the complex plane; + an instance of :class:`ArgumentByElementGroup` will be created with the given + ``domain`` - - ``exponents`` -- a SageMath parent representing a subset of the reals. - An instance of :class`UnitCircleGroup` will be created with the given + - ``exponents`` -- a SageMath parent representing a subset of the reals; + an instance of :class`UnitCircleGroup` will be created with the given ``exponents`` Exactly one of ``data``, ``specification``, ``exponents`` has to be provided. diff --git a/src/sage/groups/perm_gps/constructor.py b/src/sage/groups/perm_gps/constructor.py index ab912f7667d..63c9aecd5d3 100644 --- a/src/sage/groups/perm_gps/constructor.py +++ b/src/sage/groups/perm_gps/constructor.py @@ -35,7 +35,7 @@ def PermutationGroupElement(g, parent=None, check=True): r""" - Builds a permutation from ``g``. + Build a permutation from ``g``. INPUT: @@ -53,8 +53,8 @@ def PermutationGroupElement(g, parent=None, check=True): it is mandatory if you want a permutation on a domain different from `\{1, \ldots, n\}` - - ``check`` -- (default: ``True``) whether additional check are performed; - setting it to ``False`` is likely to result in faster code + - ``check`` -- boolean (default: ``True``); whether additional check are + performed. Setting it to ``False`` is likely to result in faster code. EXAMPLES: @@ -167,11 +167,11 @@ def standardize_generator(g, convert_dict=None, as_cycles=False): - ``convert_dict`` -- (optional) a dictionary used to convert the points to a number compatible with GAP - - ``as_cycles`` -- (default: ``False``) whether the output should be + - ``as_cycles`` -- boolean (default: ``False``); whether the output should be as cycles or in one-line notation OUTPUT: the permutation in as a list in one-line notation or a list of - cycles as tuples. + cycles as tuples EXAMPLES:: diff --git a/src/sage/groups/perm_gps/cubegroup.py b/src/sage/groups/perm_gps/cubegroup.py index 1ea023b502d..8eadbac39f1 100644 --- a/src/sage/groups/perm_gps/cubegroup.py +++ b/src/sage/groups/perm_gps/cubegroup.py @@ -563,7 +563,7 @@ def __init__(self): EXAMPLES:: sage: rubik = CubeGroup() - sage: TestSuite(rubik).run(skip="_test_enumerated_set_contains") # because the group is very large + sage: TestSuite(rubik).run(skip='_test_enumerated_set_contains') # because the group is very large TESTS: @@ -684,18 +684,18 @@ def parse(self, mv, check=True): INPUT: - - ``mv`` -- Can one of the following: + - ``mv`` -- can one of the following: - - ``list`` -- list of facets (as returned by - self.facets()) + - ``list`` -- list of facets (as returned by + self.facets()) - - ``dict`` -- list of faces (as returned by - ``self.faces()``) + - ``dict`` -- list of faces (as returned by + ``self.faces()``) - - ``str`` -- either cycle notation (passed to GAP) or - a product of generators or Singmaster notation + - ``str`` -- either cycle notation (passed to GAP) or + a product of generators or Singmaster notation - - ``perm_group element`` -- returned as an element of ``self`` + - ``perm_group element`` -- returned as an element of ``self`` - ``check`` -- check if the input is valid @@ -845,9 +845,9 @@ def move(self, mv): INPUT: - - ``mv`` -- A string of the form ``Xa*Yb*...``, + - ``mv`` -- string of the form ``Xa*Yb*...``, where ``X``, ``Y``, ... are in ``R``, ``L``, ``F``, ``B``, ``U``, - ``D`` and ``a``, ``b``, ... are integers. + ``D`` and ``a``, ``b``, ... are integers EXAMPLES:: @@ -982,8 +982,8 @@ def plot3d_cube(self, mv, title=True): INPUT: - - ``mv`` -- A string in the Singmaster notation - - ``title`` -- (Default: ``True``) Display the title information + - ``mv`` -- string in the Singmaster notation + - ``title`` -- boolean (default: ``True``); display the title information The first one below is "superflip+4 spot" (in 26q\* moves) and the second one is the superflip (in 20f\* moves). Type show(P) to view @@ -1018,7 +1018,7 @@ def plot3d_cube(self, mv, title=True): return P return P - def legal(self, state, mode="quiet"): + def legal(self, state, mode='quiet'): r""" Return 1 (true) if the dictionary ``state`` (in the same format as returned by the faces method) represents a legal @@ -1237,7 +1237,7 @@ def __init__(self, state=None, history=[], colors=[lpurple,yellow,red,green,oran if isinstance(state, str): state = self._group.faces(state) if not isinstance(state, PermutationGroupElement): - legal, state = self._group.legal(state, mode="gimme_group_element") + legal, state = self._group.legal(state, mode='gimme_group_element') if not legal: raise ValueError("not a legal cube") self._state = state @@ -1337,11 +1337,11 @@ def cubie(self, size, gap, x, y, z, colors, stickers=True): INPUT: - - ``size`` -- The size of the cubie - - ``gap`` -- The gap between cubies - - ``x``, ``y``, ``z`` -- The position of the cubie - - ``colors`` -- The list of colors - - ``stickers`` -- (Default ``True``) Boolean to display stickers + - ``size`` -- the size of the cubie + - ``gap`` -- the gap between cubies + - ``x``, ``y``, ``z`` -- the position of the cubie + - ``colors`` -- the list of colors + - ``stickers`` -- boolean (default: ``True``); whether to display stickers EXAMPLES:: @@ -1420,7 +1420,7 @@ def __richcmp__(self, other, op): return NotImplemented return richcmp(self._state, other._state, op) - def solve(self, algorithm="hybrid", timeout=15): + def solve(self, algorithm='hybrid', timeout=15): r""" Solve the Rubik's cube. @@ -1429,13 +1429,13 @@ def solve(self, algorithm="hybrid", timeout=15): - ``algorithm`` -- must be one of the following: - ``hybrid`` -- try ``kociemba`` for timeout seconds, then ``dietz`` - - ``kociemba`` -- Use Dik T. Winter's program + - ``kociemba`` -- use Dik T. Winter's program (reasonable speed, few moves) - - ``dietz`` -- Use Eric Dietz's cubex program + - ``dietz`` -- use Eric Dietz's cubex program (fast but lots of moves) - - ``optimal`` -- Use Michael Reid's optimal program + - ``optimal`` -- use Michael Reid's optimal program (may take a long time) - - ``gap`` -- Use GAP word solution (can be slow) + - ``gap`` -- use GAP word solution (can be slow) Any choice other than ``gap`` requires the optional package ``rubiks``. Otherwise, the ``gap`` algorithm is used. @@ -1487,7 +1487,7 @@ def solve(self, algorithm="hybrid", timeout=15): elif algorithm == "gap": solver = CubeGroup() - return solver.solve(self._state, algorithm="gap") + return solver.solve(self._state, algorithm='gap') else: raise ValueError(f"Unrecognized algorithm: {algorithm}") diff --git a/src/sage/groups/perm_gps/partn_ref/automorphism_group_canonical_label.pyx b/src/sage/groups/perm_gps/partn_ref/automorphism_group_canonical_label.pyx index 4547cc5863a..f8d9aaf2c1b 100644 --- a/src/sage/groups/perm_gps/partn_ref/automorphism_group_canonical_label.pyx +++ b/src/sage/groups/perm_gps/partn_ref/automorphism_group_canonical_label.pyx @@ -193,7 +193,6 @@ def test_intersect_parabolic_with_alternating(int n=9, list partition=[[0,1,2],[ 2520 sage: tipwa(9, [[0,1,2,3],[4,5,6,7,8]]) 1440 - """ cdef aut_gp_and_can_lab *output cdef Integer I = Integer(0) @@ -264,7 +263,6 @@ def coset_rep(list perm=[0,1,2,3,4,5], list gens=[[1,2,3,4,5,0]]): ....: reps.append(r) sage: len(reps) 8 - """ cdef int i, n = len(perm) assert all(len(g) == n for g in gens) @@ -319,7 +317,7 @@ cdef aut_gp_and_can_lab *allocate_agcl_output(int n) noexcept: cdef void deallocate_agcl_output(aut_gp_and_can_lab *output) noexcept: r""" - Deallocates an aut_gp_and_can_lab struct. + Deallocate an aut_gp_and_can_lab struct. """ if output is not NULL: SC_dealloc(output.group) @@ -329,7 +327,7 @@ cdef void deallocate_agcl_output(aut_gp_and_can_lab *output) noexcept: cdef agcl_work_space *allocate_agcl_work_space(int n) noexcept: r""" - Allocates work space for the get_aut_gp_and_can_lab function. It can be + Allocate work space for the get_aut_gp_and_can_lab function. It can be input to the function in which case it must be deallocated after the function is called. """ @@ -412,35 +410,36 @@ cdef aut_gp_and_can_lab *get_aut_gp_and_can_lab(void *S, Traverse the search space for subgroup/canonical label calculation. INPUT: - S -- pointer to the structure - partition -- PartitionStack representing a partition of the points - len_partition -- length of the partition - n -- the number of points (points are assumed to be 0,1,...,n-1) - canonical_label -- whether to search for canonical label; if True, return + + - ``S`` -- pointer to the structure + - ``partition`` -- PartitionStack representing a partition of the points + - ``len_partition`` -- length of the partition + - ``n`` -- the number of points (points are assumed to be 0,1,...,n-1) + - ``canonical_label`` -- whether to search for canonical label; if True, return the permutation taking S to its canonical label - all_children_are_equivalent -- pointer to a function + - ``all_children_are_equivalent`` -- pointer to a function INPUT: - PS -- pointer to a partition stack - S -- pointer to the structure + - ``PS`` -- pointer to a partition stack + - ``S`` -- pointer to the structure OUTPUT: - bint -- returns True if it can be determined that all refinements below - the current one will result in an equivalent discrete partition - refine_and_return_invariant -- pointer to a function + bint; returns ``True`` if it can be determined that all refinements below + the current one will result in an equivalent discrete partition + - ``refine_and_return_invariant`` -- pointer to a function INPUT: - PS -- pointer to a partition stack - S -- pointer to the structure - alpha -- an array consisting of numbers, which indicate the starting - positions of the cells to refine against (will likely be modified) + - ``PS`` -- pointer to a partition stack + - ``S`` -- pointer to the structure + - ``alpha`` -- an array consisting of numbers, which indicate the starting + positions of the cells to refine against (will likely be modified) OUTPUT: - int -- returns an invariant under application of arbitrary permutations - compare_structures -- pointer to a function + integer; returns an invariant under application of arbitrary permutations + - ``compare_structures`` -- pointer to a function INPUT: - gamma_1, gamma_2 -- (list) permutations of the points of S1 and S2 - S1, S2 -- pointers to the structures - degree -- degree of gamma_1 and 2 + - ``gamma_1``, ``gamma_2`` -- (list) permutations of the points of S1 and S2 + - ``S1``, ``S2`` -- pointers to the structures + - ``degree`` -- degree of gamma_1 and 2 OUTPUT: - int -- 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp), - such that the set of all structures is well-ordered + integer; 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp), + such that the set of all structures is well-ordered .. NOTE:: @@ -448,7 +447,6 @@ cdef aut_gp_and_can_lab *get_aut_gp_and_can_lab(void *S, cell, the smallest element occurs first! OUTPUT: a pointer to a ``aut_gp_and_can_lab`` struct - """ cdef PartitionStack *current_ps cdef PartitionStack *first_ps diff --git a/src/sage/groups/perm_gps/partn_ref/canonical_augmentation.pyx b/src/sage/groups/perm_gps/partn_ref/canonical_augmentation.pyx index 3898e611707..2775842c09d 100644 --- a/src/sage/groups/perm_gps/partn_ref/canonical_augmentation.pyx +++ b/src/sage/groups/perm_gps/partn_ref/canonical_augmentation.pyx @@ -400,74 +400,63 @@ cdef iterator *setup_canonical_generator(int degree, - ``all_children_are_equivalent`` -- pointer to a function INPUT: - PS -- pointer to a partition stack - S -- pointer to the structure + - ``PS`` -- pointer to a partition stack + - ``S`` -- pointer to the structure OUTPUT: - bint -- returns True if it can be determined that all refinements below - the current one will result in an equivalent discrete partition - + bint; returns ``True`` if it can be determined that all refinements below + the current one will result in an equivalent discrete partition - ``refine_and_return_invariant`` -- pointer to a function INPUT: - PS -- pointer to a partition stack - S -- pointer to the structure - alpha -- an array consisting of numbers, which indicate the starting - positions of the cells to refine against (will likely be modified) + - ``PS`` -- pointer to a partition stack + - ``S`` -- pointer to the structure + - ``alpha`` -- an array consisting of numbers, which indicate the starting + positions of the cells to refine against (will likely be modified) OUTPUT: - int -- returns an invariant under application of arbitrary permutations - + integer; returns an invariant under application of arbitrary permutations - ``compare_structures`` -- pointer to a function INPUT: - gamma_1, gamma_2 -- (list) permutations of the points of S1 and S2 - S1, S2 -- pointers to the structures - degree -- degree of gamma_1 and 2 + - ``gamma_1``, ``gamma_2`` -- (list) permutations of the points of S1 and S2 + - ``S1``, ``S2`` -- pointers to the structures + - ``degree`` -- degree of gamma_1 and 2 OUTPUT: - int -- 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp), - such that the set of all structures is well-ordered - + integer; 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp), + such that the set of all structures is well-ordered - ``generate_children`` -- pointer to a function INPUT: - S -- pointer to the structure - group -- pointer to an automorphism group (canonical relabeling is not guaranteed) - it -- preallocated iterator struct + - ``S`` -- pointer to the structure + - ``group`` -- pointer to an automorphism group (canonical relabeling is not guaranteed) + - ``it`` -- preallocated iterator struct OUTPUT: - iterator * -- pointer to an iterator over inequivalent augmentations of S - + iterator *; pointer to an iterator over inequivalent augmentations of S - ``apply_augmentation`` -- pointer to a function INPUT: - parent -- object to augment - aug -- the augmentation - child -- space to put the augmented object - degree -- pointer to an int, function should store the degree of the augmented object here - mem_err -- pointer where memory error can be reported - OUTPUT: - pointer to child - + - ``parent`` -- object to augment + - ``aug`` -- the augmentation + - ``child`` -- space to put the augmented object + - ``degree`` -- pointer to an int, function should store the degree of the augmented object here + - ``mem_err`` -- pointer where memory error can be reported + OUTPUT: pointer to child - ``free_object`` -- pointer to a function INPUT: - child -- object to be freed - + - ``child`` -- object to be freed - ``free_iter_data`` -- pointer to a function INPUT: - data -- data part of an iterator struct - + - ``data`` -- data part of an iterator struct - ``free_aug`` -- pointer to a function INPUT: - aug -- augmentation to be freed - + - ``aug`` -- augmentation to be freed - ``canonical_parent`` -- pointer to a function INPUT: - child -- pointer to the structure - parent -- space to store the canonical parent - permutation -- array representing a relabeling of the child - degree -- pointer to store the degree of the parent - mem_err -- pointer for indicating memory errors - OUTPUT: - pointer to the parent + - ``child`` -- pointer to the structure + - ``parent`` -- space to store the canonical parent + - ``permutation`` -- array representing a relabeling of the child + - ``degree`` -- pointer to store the degree of the parent + - ``mem_err`` -- pointer for indicating memory errors + OUTPUT: pointer to the parent - ``max_depth`` -- maximum depth of augmentations to be made from the seed object S OUTPUT: a pointer to an iterator of objects - """ if max_depth <= 1: raise ValueError("maximum depth (%d) must be at least two" % max_depth) diff --git a/src/sage/groups/perm_gps/partn_ref/data_structures.pxd b/src/sage/groups/perm_gps/partn_ref/data_structures.pxd index a71fa3cadd8..a6841f43f9f 100644 --- a/src/sage/groups/perm_gps/partn_ref/data_structures.pxd +++ b/src/sage/groups/perm_gps/partn_ref/data_structures.pxd @@ -141,11 +141,13 @@ cdef inline int OP_merge_list_perm(OrbitPartition *OP, int *gamma) noexcept: Joins the cells of OP which intersect the same orbit of gamma. INPUT: - gamma - an integer array representing i -> gamma[i]. + + - ``gamma`` - an integer array representing ``i -> gamma[i]``. OUTPUT: - 1 - something changed - 0 - orbits of gamma all contained in cells of OP + + - 1 -- something changed + - 0 -- orbits of gamma all contained in cells of OP """ cdef int i, i_root, gamma_i_root, changed = 0 for i from 0 <= i < OP.degree: @@ -218,7 +220,7 @@ cdef inline bint PS_is_fixed(PartitionStack *PS, int m) noexcept: cdef inline int PS_clear(PartitionStack *PS) noexcept: """ - Sets the current partition to the first shallower one, i.e. forgets about + Set the current partition to the first shallower one, i.e. forgets about boundaries between cells that are new to the current level. """ cdef int i, cur_start = 0 @@ -242,7 +244,7 @@ cdef inline int PS_move_all_mins_to_front(PartitionStack *PS) noexcept: cdef inline int PS_get_perm_from(PartitionStack *PS1, PartitionStack *PS2, int *gamma) noexcept: """ Store the permutation determined by PS2[i] -> PS1[i] for each i, where PS[i] - denotes the entry of the ith cell of the discrete partition PS. + denotes the entry of the `i`-th cell of the discrete partition PS. """ cdef int i for i from 0 <= i < PS1.degree: @@ -319,14 +321,13 @@ cdef inline int split_point_and_refine(PartitionStack *PS, int v, void *S, the refinement function. INPUT: - PS -- the partition stack to refine - v -- the point to split - S -- the structure - refine_and_return_invariant -- the refinement function provided - cells_to_refine_by -- an array, contents ignored - group -- the containing group, NULL for full S_n - perm_stack -- represents a partial traversal decomposition for group - + - ``PS`` -- the partition stack to refine + - ``v`` -- the point to split + - ``S`` -- the structure + - ``refine_and_return_invariant`` -- the refinement function provided + - ``cells_to_refine_by`` -- an array, contents ignored + - ``group`` -- the containing group, NULL for full S_n + - ``perm_stack`` -- represents a partial traversal decomposition for group """ PS.depth += 1 PS_clear(PS) @@ -384,7 +385,7 @@ cdef inline void SC_identify(int *perm, int degree) noexcept: cdef inline void SC_add_base_point(StabilizerChain *SC, int b) noexcept: """ - Adds base point b to the end of SC. Assumes b is not already in the base. + Add base point b to the end of SC. Assumes b is not already in the base. """ cdef int i, n = SC.degree SC.orbit_sizes[SC.base_size] = 1 @@ -480,8 +481,8 @@ cdef inline int SC_update_tree(StabilizerChain *SC, int level, int *pi, int num_ cdef inline void SC_order(StabilizerChain *SC, int i, mpz_t order) noexcept: """ - Gives the order of the stabilizer of base points up to but not including the - i-th, storing it to ``order``, which must be already initialized. + Give the order of the stabilizer of base points up to but not including the + `i`-th, storing it to ``order``, which must be already initialized. To get the order of the full group, let ``i = 0``. """ @@ -515,7 +516,7 @@ cdef inline bint SC_contains(StabilizerChain *SC, int level, int *pi, bint modif cdef inline void SC_random_element(StabilizerChain *SC, int level, int *perm) noexcept: """ - Gives a random element of the level-th stabilizer. For a random element of the + Give a random element of the level-th stabilizer. For a random element of the whole group, set level to 0. Must have level < SC.base_size. """ cdef int i, x, n = SC.degree @@ -532,7 +533,7 @@ cdef inline void update_perm_stack(StabilizerChain *group, int level, int point, int *perm_stack) noexcept: """ Ensure that perm_stack[level] is gamma_0^{-1}...gamma_{level-1}^{-1}, where - each gamma_i represents the coset representative at the ith level determined + each gamma_i represents the coset representative at the `i`-th level determined by our current position in the search tree. For internal use within the automorphism group, canonical label and double diff --git a/src/sage/groups/perm_gps/partn_ref/data_structures.pyx b/src/sage/groups/perm_gps/partn_ref/data_structures.pyx index b707727c2c9..28672d00038 100644 --- a/src/sage/groups/perm_gps/partn_ref/data_structures.pyx +++ b/src/sage/groups/perm_gps/partn_ref/data_structures.pyx @@ -121,7 +121,6 @@ def OP_represent(int n, merges, perm): 8 -> 8, root: size=1, mcr=8, rank=0 Deallocating OrbitPartition. Done. - """ cdef int i print("Allocating OrbitPartition...") @@ -455,7 +454,6 @@ def PS_represent(partition, splits): 0100000000 Deallocating PartitionStacks. Done. - """ cdef int i, n = sum([len(cell) for cell in partition]) cdef int *gamma @@ -779,7 +777,7 @@ cdef int SC_realloc_bitsets(StabilizerChain *SC, unsigned long size) noexcept: cdef StabilizerChain *SC_copy(StabilizerChain *SC, int level) noexcept: """ - Creates a copy of the first `level` levels of SC. Must have 0 < level. + Create a copy of the first `level` levels of SC. Must have 0 < level. Return a null pointer in case of allocation failure. """ @@ -1354,7 +1352,6 @@ def SC_test_list_perms(list L, int n, int limit, bint gap, bint limit_complain, ....: test_stab_chain_fns_7(n, 0, 1, 1) sage: test_stab_chain_fns_7(20, 1, 1, 1) sage: test_stab_chain_fns_7(20, 0, 1, 1) - """ if gap: from sage.groups.perm_gps.permgroup import PermutationGroup @@ -1623,11 +1620,10 @@ cdef int sort_by_function(PartitionStack *PS, int start, int *degrees) noexcept: INPUT: - - PS -- the partition stack to be checked - - start -- beginning index of the cell to be sorted - - degrees -- the values to be sorted by, must have extra scratch space for a + - ``PS`` -- the partition stack to be checked + - ``start`` -- beginning index of the cell to be sorted + - ``degrees`` -- the values to be sorted by, must have extra scratch space for a total of `3*n+1` - """ cdef int n = PS.degree cdef int i, j, max, max_location diff --git a/src/sage/groups/perm_gps/partn_ref/double_coset.pyx b/src/sage/groups/perm_gps/partn_ref/double_coset.pyx index 10430b64355..d4cedec1f3c 100644 --- a/src/sage/groups/perm_gps/partn_ref/double_coset.pyx +++ b/src/sage/groups/perm_gps/partn_ref/double_coset.pyx @@ -168,7 +168,6 @@ def coset_eq(list perm1=[0,1,2,3,4,5], list perm2=[1,2,3,4,5,0], list gens=[[1,2 ....: reps.append(p) sage: len(reps) 8 - """ cdef int i, n = len(perm1) assert all(len(g) == n for g in gens+[perm2]) @@ -202,7 +201,7 @@ def coset_eq(list perm1=[0,1,2,3,4,5], list perm2=[1,2,3,4,5,0], list gens=[[1,2 cdef dc_work_space *allocate_dc_work_space(int n) noexcept: r""" - Allocates work space for the double_coset function. It can be + Allocate work space for the double_coset function. It can be input to the function in which case it must be deallocated after the function is called. """ @@ -252,7 +251,7 @@ cdef dc_work_space *allocate_dc_work_space(int n) noexcept: cdef void deallocate_dc_work_space(dc_work_space *work_space) noexcept: r""" - Deallocates work space for the double_coset function. + Deallocate work space for the double_coset function. """ if work_space is NULL: return @@ -281,38 +280,38 @@ cdef int double_coset(void *S1, void *S2, PartitionStack *partition1, int *order Traverse the search space for double coset calculation. INPUT: - S1, S2 -- pointers to the structures - partition1 -- PartitionStack of depth 0 and degree n, - whose first partition is of the points of S1 - ordering2 -- an ordering of the points of S2 representing a second partition - n -- the number of points (points are assumed to be 0,1,...,n-1) - all_children_are_equivalent -- pointer to a function + - ``S1``, ``S2`` -- pointers to the structures + - ``partition1`` -- PartitionStack of depth 0 and degree n, + whose first partition is of the points of S1 + - ``ordering2`` -- an ordering of the points of S2 representing a second partition + - ``n`` -- the number of points (points are assumed to be 0,1,...,n-1) + - ``all_children_are_equivalent`` -- pointer to a function INPUT: - PS -- pointer to a partition stack - S -- pointer to the structure + - ``PS`` -- pointer to a partition stack + - ``S`` -- pointer to the structure OUTPUT: - bint -- returns True if it can be determined that all refinements below - the current one will result in an equivalent discrete partition - refine_and_return_invariant -- pointer to a function + bint; returns True if it can be determined that all refinements below + the current one will result in an equivalent discrete partition + - ``refine_and_return_invariant`` -- pointer to a function INPUT: - PS -- pointer to a partition stack - S -- pointer to the structure - alpha -- an array consisting of numbers, which indicate the starting - positions of the cells to refine against (will likely be modified) + - ``PS`` -- pointer to a partition stack + -n``S`` -- pointer to the structure + - ``alpha`` -- an array consisting of numbers, which indicate the starting + positions of the cells to refine against (will likely be modified) OUTPUT: - int -- returns an invariant under application of arbitrary permutations + integer; returns an invariant under application of arbitrary permutations compare_structures -- pointer to a function INPUT: - gamma_1, gamma_2 -- (list) permutations of the points of S1 and S2 - S1, S2 -- pointers to the structures - degree -- degree of gamma_1 and 2 + - ``gamma_1``, ``gamma_2`` -- (list) permutations of the points of S1 and S2 + - ``S1``, ``S2`` -- pointers to the structures + - ``degree`` -- degree of gamma_1 and 2 OUTPUT: - int -- 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp), - such that the set of all structures is well-ordered - input_group -- either a specified group to limit the search to, - or NULL for the full symmetric group - isom -- space to store the isomorphism to, - or NULL if isomorphism is not needed + integer; 0 if gamma_1(S1) = gamma_2(S2), otherwise -1 or 1 (see docs for cmp), + such that the set of all structures is well-ordered + - ``input_group`` -- either a specified group to limit the search to, + or NULL for the full symmetric group + - ``isom`` -- space to store the isomorphism to, + or NULL if isomorphism is not needed .. NOTE:: diff --git a/src/sage/groups/perm_gps/partn_ref/refinement_binary.pyx b/src/sage/groups/perm_gps/partn_ref/refinement_binary.pyx index 9f44aaec67b..1b8ace1cae0 100644 --- a/src/sage/groups/perm_gps/partn_ref/refinement_binary.pyx +++ b/src/sage/groups/perm_gps/partn_ref/refinement_binary.pyx @@ -479,8 +479,8 @@ cdef class NonlinearBinaryCodeStruct(BinaryCodeStruct): INPUT: - - ``partition`` -- an optional list of lists partition of the columns. - default is the unit partition. + - ``partition`` -- an optional list of lists partition of the columns + default is the unit partition EXAMPLES:: @@ -631,18 +631,17 @@ cdef int refine_by_bip_degree(PartitionStack *col_ps, void *S, int *cells_to_ref INPUT: - - col_ps -- a partition stack, whose finest partition is the partition to be refined - - S -- a binary code struct object - - cells_to_refine_by -- a list of pointers to cells to check degrees against + - ``col_ps`` -- a partition stack, whose finest partition is the partition to be refined + - ``S`` -- a binary code struct object + - ``cells_to_refine_by`` -- list of pointers to cells to check degrees against in refining the other cells (updated in place) - - ctrb_len -- how many cells in cells_to_refine_by + - ``ctrb_len`` -- how many cells in cells_to_refine_by OUTPUT: An integer $I$ invariant under the orbits of $S_n$. That is, if $\gamma$ is a permutation of the columns, then $$ I(G, PS, cells_to_refine_by) = I( \gamma(G), \gamma(PS), \gamma(cells_to_refine_by) ) .$$ - """ cdef BinaryCodeStruct BCS = S cdef int current_cell_against = 0 @@ -961,11 +960,11 @@ cdef inline int word_degree(PartitionStack *word_ps, BinaryCodeStruct BCS, int e INPUT: - - word_ps -- the partition stack to be checked - - col_ps -- corresponding partition stack on columns - - BCS -- a binary code struct object - - entry -- the position of the vertex in question in the entries of word_ps - - cell_index -- the starting position of the cell in question in the entries of PS + - ``word_ps`` -- the partition stack to be checked + - ``col_ps`` -- corresponding partition stack on columns + - ``BCS`` -- a binary code struct object + - ``entry`` -- the position of the vertex in question in the entries of word_ps + - ``cell_index`` -- the starting position of the cell in question in the entries of PS """ cdef bitset_t cell, word cdef int h @@ -991,11 +990,11 @@ cdef inline int col_degree(PartitionStack *col_ps, BinaryCodeStruct BCS, int ent INPUT: - - col_ps -- the partition stack to be checked - - word_ps -- corresponding partition stack on words - - BCS -- a binary code struct object - - entry -- the position of the vertex in question in the entries of word_ps - - cell_index -- the starting position of the cell in question in the entries of PS + - ``col_ps`` -- the partition stack to be checked + - ``word_ps`` -- corresponding partition stack on words + - ``BCS`` -- a binary code struct object + - ``entry`` -- the position of the vertex in question in the entries of word_ps + - ``cell_index`` -- the starting position of the cell in question in the entries of PS """ cdef bitset_t word bitset_init(word, BCS.degree) @@ -1016,9 +1015,9 @@ cdef inline int sort_by_function_codes(PartitionStack *PS, int start, int *degre INPUT: - - PS -- the partition stack to be checked - - start -- beginning index of the cell to be sorted - - degrees -- the values to be sorted by + - ``PS`` -- the partition stack to be checked + - ``start`` -- beginning index of the cell to be sorted + - ``degrees`` -- the values to be sorted by - count, count_max, output -- scratch space """ cdef int i, j, max, max_location diff --git a/src/sage/groups/perm_gps/partn_ref/refinement_graphs.pyx b/src/sage/groups/perm_gps/partn_ref/refinement_graphs.pyx index 34c911c51bf..1258ea280ab 100644 --- a/src/sage/groups/perm_gps/partn_ref/refinement_graphs.pyx +++ b/src/sage/groups/perm_gps/partn_ref/refinement_graphs.pyx @@ -186,18 +186,18 @@ def search_tree(G_in, partition, lab=True, dig=False, dict_rep=False, certificat INPUT: - ``G_in`` -- a Sage graph - - ``partition`` -- a list of lists representing a partition of the vertices - - ``lab`` -- if True, compute and return the canonical label in addition to the + - ``partition`` -- list of lists representing a partition of the vertices + - ``lab`` -- if ``True``, compute and return the canonical label in addition to the automorphism group - - ``dig`` -- set to True for digraphs and graphs with loops. If True, does not + - ``dig`` -- set to ``True`` for digraphs and graphs with loops; if ``True``, does not use optimizations based on Lemma 2.25 in [1] that are valid only for - simple graphs. + simple graphs - ``dict_rep`` -- if ``True``, return a dictionary with keys the vertices of the input graph G_in and values elements of the set the permutation group acts on. (The point is that graphs are arbitrarily labelled, often 0..n-1, and permutation groups always act on 1..n. This dictionary maps vertex labels (such as 0..n-1) to the domain of the permutations.) - - ``certificate`` -- if ``True``, return the permutation from G to its canonical label. + - ``certificate`` -- if ``True``, return the permutation from G to its canonical label - ``verbosity`` -- currently ignored - ``use_indicator_function`` -- option to turn off indicator function (``True`` is generally faster) @@ -518,7 +518,7 @@ cdef int refine_by_degree(PartitionStack *PS, void *S, int *cells_to_refine_by, refined - ``S`` -- a graph struct object, which contains scratch space, the graph in question, and some flags - - ``cells_to_refine_by`` -- a list of pointers to cells to check degrees against + - ``cells_to_refine_by`` -- list of pointers to cells to check degrees against in refining the other cells (updated in place). Must be allocated to length at least the degree of PS, since the array may grow - ``ctrb_len`` -- how many cells in cells_to_refine_by @@ -779,7 +779,6 @@ def all_labeled_graphs(n): 3 4 4 11 5 34 - """ from sage.graphs.graph import Graph TE = [] @@ -801,7 +800,7 @@ def all_labeled_graphs(n): def random_tests(num=10, n_max=60, perms_per_graph=5): """ - Tests to make sure that C(gamma(G)) == C(G) for random permutations gamma + Test to make sure that C(gamma(G)) == C(G) for random permutations gamma and random graphs G, and that isomorphic returns an isomorphism. INPUT: @@ -1300,7 +1299,6 @@ def generate_dense_graphs_edge_addition(int n, bint loops, G=None, depth=None, 1044 sage: generate_dense_graphs_edge_addition(8,0) # long time (about 14 seconds at 2.4 GHz) 12346 - """ from sage.graphs.graph import Graph cdef iterator *graph_iterator @@ -1573,7 +1571,6 @@ def generate_dense_graphs_vert_addition(int n, base_G=None, sage: from sage.groups.perm_gps.partn_ref.refinement_graphs import generate_dense_graphs_vert_addition sage: generate_dense_graphs_vert_addition(10, base_G=Graph('HEhf^rs')) 11 - """ from sage.graphs.graph import Graph cdef iterator *graph_iterator diff --git a/src/sage/groups/perm_gps/partn_ref/refinement_lists.pyx b/src/sage/groups/perm_gps/partn_ref/refinement_lists.pyx index 8946d7211c2..e15683bdd77 100644 --- a/src/sage/groups/perm_gps/partn_ref/refinement_lists.pyx +++ b/src/sage/groups/perm_gps/partn_ref/refinement_lists.pyx @@ -26,14 +26,13 @@ from sage.groups.perm_gps.partn_ref.double_coset cimport double_coset, int_cmp def is_isomorphic(self, other): r""" Return the bijection as a permutation if two lists are isomorphic, return - False otherwise. + ``False`` otherwise. EXAMPLES:: sage: from sage.groups.perm_gps.partn_ref.refinement_lists import is_isomorphic sage: is_isomorphic([0,0,1],[1,0,0]) [1, 2, 0] - """ cdef int i, n = len(self) cdef PartitionStack *part diff --git a/src/sage/groups/perm_gps/partn_ref/refinement_matrices.pyx b/src/sage/groups/perm_gps/partn_ref/refinement_matrices.pyx index 6a9d97be641..57bf05e2e6d 100644 --- a/src/sage/groups/perm_gps/partn_ref/refinement_matrices.pyx +++ b/src/sage/groups/perm_gps/partn_ref/refinement_matrices.pyx @@ -130,7 +130,7 @@ cdef class MatrixStruct: INPUT: - ``partition`` -- an optional list of lists partition of the columns; - default is the unit partition. + default is the unit partition EXAMPLES:: @@ -303,11 +303,11 @@ def random_tests(n=10, nrows_max=50, ncols_max=50, nsymbols_max=10, perms_per_ma INPUT: - - n -- run tests on this many matrices - - nrows_max -- test matrices with at most this many rows - - ncols_max -- test matrices with at most this many columns - - perms_per_matrix -- test each matrix with this many random permutations - - nsymbols_max -- maximum number of distinct symbols in the matrix + - ``n`` -- run tests on this many matrices + - ``nrows_max`` -- test matrices with at most this many rows + - ``ncols_max`` -- test matrices with at most this many columns + - ``perms_per_matrix`` -- test each matrix with this many random permutations + - ``nsymbols_max`` -- maximum number of distinct symbols in the matrix This code generates n random matrices M on at most ncols_max columns and at most nrows_max rows. The density of entries in the basis is chosen randomly diff --git a/src/sage/groups/perm_gps/partn_ref/refinement_python.pyx b/src/sage/groups/perm_gps/partn_ref/refinement_python.pyx index 9408c620367..0623c237b76 100644 --- a/src/sage/groups/perm_gps/partn_ref/refinement_python.pyx +++ b/src/sage/groups/perm_gps/partn_ref/refinement_python.pyx @@ -204,7 +204,7 @@ cdef class PythonPartitionStack: def set_entry(self, int i, int entry): """ - Set the ith entry of the entries array to entry. + Set the `i`-th entry of the entries array to entry. EXAMPLES:: @@ -219,7 +219,7 @@ cdef class PythonPartitionStack: def get_entry(self, int i): """ - Get the ith entry of the entries array. + Get the `i`-th entry of the entries array. EXAMPLES:: @@ -247,7 +247,7 @@ cdef class PythonPartitionStack: def set_level(self, int i, int level): """ - Set the ith entry of the levels array to entry. + Set the `i`-th entry of the levels array to entry. EXAMPLES:: @@ -264,7 +264,7 @@ cdef class PythonPartitionStack: def get_level(self, int i): """ - Get the ith entry of the levels array. + Get the `i`-th entry of the levels array. EXAMPLES:: @@ -450,7 +450,6 @@ def aut_gp_and_can_lab_python(S, partition, n, 48) sage: factorial(4)*factorial(2) 48 - """ obj_wrapper = PythonObjectWrapper(S, all_children_are_equivalent, refine_and_return_invariant, compare_structures, n) cdef aut_gp_and_can_lab *output @@ -492,7 +491,7 @@ def double_coset_python(S1, S2, partition1, ordering2, n, refine_and_return_invariant, compare_structures): """ - Calls the double coset function. + Call the double coset function. INPUT: @@ -533,7 +532,6 @@ def double_coset_python(S1, S2, partition1, ordering2, n, sage: double_coset_python([0,0,1], [1,0,0], [[0,1,2]], [0,1,2], 3, acae, rari, compare_lists) [1, 2, 0] - """ obj_wrapper1 = PythonObjectWrapper(S1, all_children_are_equivalent, refine_and_return_invariant, compare_structures, n) obj_wrapper2 = PythonObjectWrapper(S2, all_children_are_equivalent, refine_and_return_invariant, compare_structures, n) diff --git a/src/sage/groups/perm_gps/partn_ref/refinement_sets.pyx b/src/sage/groups/perm_gps/partn_ref/refinement_sets.pyx index ea55086d204..669e149ff09 100644 --- a/src/sage/groups/perm_gps/partn_ref/refinement_sets.pyx +++ b/src/sage/groups/perm_gps/partn_ref/refinement_sets.pyx @@ -135,7 +135,6 @@ def set_stab_py(generators, sett, relab=False): ([], [7, 8, 6, 3, 4, 5, 2, 0, 1]) sage: set_stab_py([[0,2,1,4,3,5,8,7,6],[8,7,6,3,5,4,2,1,0]], [0,3,5,6,8], True) ([], [2, 1, 0, 5, 4, 3, 7, 6, 8]) - """ if len(generators) == 0: return [] @@ -696,11 +695,11 @@ def sets_modulo_perm_group(list generators, int max_size, INPUT: - - ``generators`` -- (list of lists) list of generators in list form - - ``max_size`` -- (int) maximum size of subsets to be generated - - ``indicate_mem_err`` -- (bool) whether to raise an error - if we run out of memory, or simply append a :class:`MemoryError` - instance to the end of the output + - ``generators`` -- list of generators in list form + - ``max_size`` -- integer; maximum size of subsets to be generated + - ``indicate_mem_err`` -- boolean; whether to raise an error. + If we run out of memory, or simply append a :exc:`MemoryError` + instance to the end of the output. EXAMPLES:: diff --git a/src/sage/groups/perm_gps/partn_ref2/refinement_generic.pyx b/src/sage/groups/perm_gps/partn_ref2/refinement_generic.pyx index 668e8d55af5..af1960e4632 100644 --- a/src/sage/groups/perm_gps/partn_ref2/refinement_generic.pyx +++ b/src/sage/groups/perm_gps/partn_ref2/refinement_generic.pyx @@ -282,7 +282,7 @@ cdef class _BestValStore: cdef long * get_row(self, int i) noexcept: r""" - Return the i-th row. + Return the `i`-th row. If this row is not yet initialized (i >= self.storage_length), then we extend the array and fill the new positions @@ -494,15 +494,15 @@ cdef class PartitionRefinement_generic: ##################################################################### cdef bint _inner_min_(self, int pos, bint * inner_group_changed) noexcept: """ - Minimize the node by the action of the inner group on the ith position. + Minimize the node by the action of the inner group on the `i`-th position. INPUT: - - ``pos`` -- A position in ``range(self.n)`` + - ``pos`` -- a position in ``range(self.n)`` - ``inner_group_changed`` -- will be set to ``True`` if `G_y` got smaller OUTPUT: ``True`` if and only if the actual node compares less or equal - to the candidate for the canonical form. + to the candidate for the canonical form """ raise NotImplementedError @@ -825,12 +825,12 @@ cdef class PartitionRefinement_generic: There are to possibilities depending on the flag ``self._is_candidate_initialized``: - - ``True``: There is another leaf equal to this node. This defines an automorphism - which we add to the group of known automorphisms stored in - ``self._known_automorphisms``. - - ``False``: We have shown, that the current leaf is smaller than all - other leaf nodes already visited. We set it to be the - candidate for the canonical form. + - ``True`` -- There is another leaf equal to this node. This defines an automorphism + which we add to the group of known automorphisms stored in + ``self._known_automorphisms``. + - ``False`` -- We have shown, that the current leaf is smaller than all + other leaf nodes already visited. We set it to be the + candidate for the canonical form. """ from sage.libs.gap.libgap import libgap cdef int i @@ -865,7 +865,7 @@ cdef class PartitionRefinement_generic: # BACKTRACK_WITHLATEX_DEBUG = 1 in the setup.py script when # building this module! ########################################################################### - cdef void _latex_act_node(self, str comment="", int printlvl=0) noexcept: + cdef void _latex_act_node(self, str comment='', int printlvl=0) noexcept: r""" Append the actual node as a string of latex-commands to ``self._latex_debug_string``. diff --git a/src/sage/groups/perm_gps/permgroup.py b/src/sage/groups/perm_gps/permgroup.py index d97aad93b03..a4e60e771f9 100644 --- a/src/sage/groups/perm_gps/permgroup.py +++ b/src/sage/groups/perm_gps/permgroup.py @@ -165,7 +165,7 @@ def load_hap(): sage: sage.groups.perm_gps.permgroup.load_hap() # optional - gap_package_hap """ from sage.features.gap import GapPackage - GapPackage("hap", spkg="gap_packages").require() + GapPackage("hap", spkg='gap_packages').require() libgap.load_package("hap") @@ -205,7 +205,7 @@ def wrapped(self, n, p=0): def direct_product_permgroups(P): """ - Takes the direct product of the permutation groups listed in ``P``. + Take the direct product of the permutation groups listed in ``P``. EXAMPLES:: @@ -269,12 +269,12 @@ def PermutationGroup(gens=None, *args, **kwds): INPUT: - - ``gens`` -- (default: ``None``) list of generators + - ``gens`` -- (default: ``None``) list of generators - - ``gap_group`` -- (optional) a gap permutation group + - ``gap_group`` -- (optional) a gap permutation group - - ``canonicalize`` -- boolean (default: ``True``); if ``True``, - sort generators and remove duplicates + - ``canonicalize`` -- boolean (default: ``True``); if ``True``, + sort generators and remove duplicates OUTPUT: a permutation group @@ -387,7 +387,6 @@ def PermutationGroup(gens=None, *args, **kwds): ... DeprecationWarning: gap_group, domain, canonicalize, category will become keyword only See https://github.com/sagemath/sage/issues/31510 for details. - """ if not isinstance(gens, ExpectElement) and hasattr(gens, '_permgroup_'): return gens._permgroup_() @@ -451,7 +450,7 @@ def __init__(self, gens=None, gap_group=None, canonicalize=True, - ``gap_group`` -- a gap or libgap permutation group, or a string defining one (default: ``None``) - - ``canonicalize`` -- bool (default: ``True``); if ``True``, + - ``canonicalize`` -- boolean (default: ``True``); if ``True``, sort generators and remove duplicates OUTPUT: a permutation group @@ -618,7 +617,7 @@ def construction(self): @cached_method def _has_natural_domain(self): """ - Return whether the underlying domain is of the form (1,...,n) + Return whether the underlying domain is of the form (1,...,n). EXAMPLES:: @@ -1164,7 +1163,7 @@ def __iter__(self): return self._iteration_monogen() else: # TODO: this is too slow for moderatly small permutation groups - return self.iteration(algorithm="SGS") + return self.iteration(algorithm='SGS') def _iteration_monogen(self): r""" @@ -1188,24 +1187,24 @@ def _iteration_monogen(self): h *= g yield h - def iteration(self, algorithm="SGS"): + def iteration(self, algorithm='SGS'): """ Return an iterator over the elements of this group. INPUT: - - ``algorithm`` -- (default: ``"SGS"``) either + - ``algorithm`` -- (default: ``'SGS'``) either - * ``"SGS"`` -- using strong generating system - * ``"BFS"`` -- a breadth first search on the Cayley graph with + * ``'SGS'`` -- using strong generating system + * ``'BFS'`` -- a breadth first search on the Cayley graph with respect to ``self.gens()`` - * ``"DFS"`` -- a depth first search on the Cayley graph with + * ``'DFS'`` -- a depth first search on the Cayley graph with respect to ``self.gens()`` .. NOTE:: - In general, the algorithm ``"SGS"`` is faster. Yet, for - small groups, ``"BFS"`` and ``"DFS"`` might be faster. + In general, the algorithm ``'SGS'`` is faster. Yet, for + small groups, ``'BFS'`` and ``'DFS'`` might be faster. .. NOTE:: @@ -1219,10 +1218,10 @@ def iteration(self, algorithm="SGS"): sage: list(G.iteration()) [(), (1,2,3), (1,3,2), (2,3), (1,2), (1,3)] - sage: list(G.iteration(algorithm="BFS")) + sage: list(G.iteration(algorithm='BFS')) [(), (2,3), (1,2), (1,2,3), (1,3,2), (1,3)] - sage: list(G.iteration(algorithm="DFS")) + sage: list(G.iteration(algorithm='DFS')) [(), (1,2), (1,3,2), (1,3), (1,2,3), (2,3)] TESTS:: @@ -1235,9 +1234,9 @@ def iteration(self, algorithm="SGS"): sage: sum(1 for x in A.iteration()) == 60000 True - sage: sum(1 for x in A.iteration(algorithm="BFS")) == 60000 + sage: sum(1 for x in A.iteration(algorithm='BFS')) == 60000 True - sage: sum(1 for x in A.iteration(algorithm="DFS")) == 60000 + sage: sum(1 for x in A.iteration(algorithm='DFS')) == 60000 True """ if algorithm == "SGS": @@ -1250,7 +1249,7 @@ def elements(SGS): for g in S: yield s._mul_(g) - SGS = self.strong_generating_system(implementation="gap") + SGS = self.strong_generating_system(implementation='gap') return elements(SGS) elif algorithm in ["BFS", "DFS"]: from sage.sets.recursively_enumerated_set import RecursivelyEnumeratedSet @@ -1447,7 +1446,7 @@ def one(self): def exponent(self): r""" - Computes the exponent of the group. + Compute the exponent of the group. The exponent `e` of a group `G` is the LCM of the orders of its elements, that is, `e` is the smallest integer such that `g^e=1` for all @@ -1681,7 +1680,7 @@ def representative_action(self, x, y): INPUT: - - ``x``, ``y`` -- two elements of the domain. + - ``x``, ``y`` -- two elements of the domain EXAMPLES:: @@ -1741,27 +1740,27 @@ def orbits(self): for orbit in orbits.sage()) @cached_method - def orbit(self, point, action="OnPoints"): + def orbit(self, point, action='OnPoints'): """ Return the orbit of a point under a group action. INPUT: - ``point`` -- can be a point or any of the list above, depending on the - action to be considered. + action to be considered - - ``action`` -- string. if ``point`` is an element from the domain, a + - ``action`` -- string; if ``point`` is an element from the domain, a tuple of elements of the domain, a tuple of tuples [...], this - variable describes how the group is acting. + variable describes how the group is acting The actions currently available through this method are - ``"OnPoints"``, ``"OnTuples"``, ``"OnSets"``, ``"OnPairs"``, - ``"OnSetsSets"``, ``"OnSetsDisjointSets"``, - ``"OnSetsTuples"``, ``"OnTuplesSets"``, - ``"OnTuplesTuples"``. They are taken from GAP's list of + ``'OnPoints'``, ``'OnTuples'``, ``'OnSets'``, ``'OnPairs'``, + ``'OnSetsSets'``, ``'OnSetsDisjointSets'``, + ``'OnSetsTuples'``, ``'OnTuplesSets'``, + ``'OnTuplesTuples'``. They are taken from GAP's list of group actions, see ``gap.help('Group Actions')``. - It is set to ``"OnPoints"`` by default. See below for examples. + It is set to ``'OnPoints'`` by default. See below for examples. OUTPUT: @@ -1797,7 +1796,7 @@ def orbit(self, point, action="OnPoints"): Action of `S_4` on sets of disjoint sets:: sage: S4 = groups.permutation.Symmetric(4) - sage: O = S4.orbit(((1,2),(3,4)), action="OnSetsDisjointSets") + sage: O = S4.orbit(((1,2),(3,4)), action='OnSetsDisjointSets') sage: {1, 2} in O[0] and {3, 4} in O[0] True sage: {1, 4} in O[1] and {2, 3} in O[1] @@ -1897,7 +1896,7 @@ def transversals(self, point): self._domain_to_gap[i])) for i in self.orbit(point)] - def stabilizer(self, point, action="OnPoints"): + def stabilizer(self, point, action='OnPoints'): """ Return the subgroup of ``self`` which stabilize the given position. ``self`` and its stabilizers must have same degree. @@ -1905,9 +1904,9 @@ def stabilizer(self, point, action="OnPoints"): INPUT: - ``point`` -- a point of the :meth:`domain`, or a set of points - depending on the value of ``action``. + depending on the value of ``action`` - - ``action`` -- (string; default ``"OnPoints"``) should the group be + - ``action`` -- string (default: ``'OnPoints'``); should the group be considered to act on points (``action="OnPoints"``) or on sets of points (``action="OnSets"``)? In the latter case, the first argument must be a subset of :meth:`domain`. @@ -1999,7 +1998,7 @@ def base(self, seed=None): INPUT: - - ``seed`` (default: ``None``), if given must be a + - ``seed`` -- (default: ``None``) if given must be a subset of the domain of a base. When used, an attempt to create a base containing all or part of ``seed`` will be made. @@ -2037,7 +2036,7 @@ def base(self, seed=None): stab_chain = self._libgap_().StabChain(seed).BaseStabChain().sage() return [self._domain_from_gap[x] for x in stab_chain] - def strong_generating_system(self, base_of_group=None, implementation="sage"): + def strong_generating_system(self, base_of_group=None, implementation='sage'): r""" Return a Strong Generating System of ``self`` according the given base for the right action of ``self`` on itself. @@ -2064,21 +2063,21 @@ def strong_generating_system(self, base_of_group=None, implementation="sage"): a list containing the integers `1, 2, \ldots , d` in any order, where `d` is the degree of ``self`` - - ``implementation`` -- (default: ``"sage"``) either + - ``implementation`` -- (default: ``'sage'``) either - * ``"sage"`` -- use the direct implementation in Sage + * ``'sage'`` -- use the direct implementation in Sage - * ``"gap"`` -- if used, the ``base_of_group`` must be ``None`` + * ``'gap'`` -- if used, the ``base_of_group`` must be ``None`` and the computation is directly performed in GAP - OUTPUT: a list of lists of permutations from the group, which forms a + OUTPUT: list of lists of permutations from the group, which forms a strong generating system .. WARNING:: - The outputs for implementations ``"sage"`` and ``"gap"`` differ: + The outputs for implementations ``'sage'`` and ``'gap'`` differ: First, the output is reversed, and second, it might be that - ``"sage"`` does not contain the trivial subgroup while ``"gap"`` + ``'sage'`` does not contain the trivial subgroup while ``'gap'`` does. Also, both algorithms might yield different results based on the @@ -2124,7 +2123,7 @@ def strong_generating_system(self, base_of_group=None, implementation="sage"): sage: A = PermutationGroup([(1,2),(1,2,3,4,5,6,7,8,9)]) sage: X = A.strong_generating_system() - sage: Y = A.strong_generating_system(implementation="gap") + sage: Y = A.strong_generating_system(implementation='gap') sage: [len(x) for x in X] [9, 8, 7, 6, 5, 4, 3, 2, 1] sage: [len(y) for y in Y] @@ -2429,7 +2428,7 @@ def group_primitive_id(self): OUTPUT: A positive integer, following GAP's conventions. A - :class:`ValueError` is raised if the group is not primitive. + :exc:`ValueError` is raised if the group is not primitive. EXAMPLES:: @@ -2560,7 +2559,7 @@ def intersection(self, other): INPUT: - - ``other`` -- a permutation group. + - ``other`` -- a permutation group OUTPUT: @@ -2742,28 +2741,28 @@ def direct_product(self, other, maps=True): representation for the direct product. The direct product of permutation groups will be a permutation group again. For a direct product ``D``, the GAP operation ``Embedding(D,i)`` returns the - homomorphism embedding the i-th factor into ``D``. The GAP operation - ``Projection(D,i)`` gives the projection of ``D`` onto the i-th factor. + homomorphism embedding the `i`-th factor into ``D``. The GAP operation + ``Projection(D,i)`` gives the projection of ``D`` onto the `i`-th factor. This method returns a 5-tuple: a permutation group and 4 morphisms. INPUT: - - ``self``, ``other`` -- permutation groups + - ``self``, ``other`` -- permutation groups OUTPUT: - - ``D`` -- a direct product of the inputs, returned as - a permutation group as well + - ``D`` -- a direct product of the inputs, returned as + a permutation group as well - - ``iota1`` -- an embedding of ``self`` into ``D`` + - ``iota1`` -- an embedding of ``self`` into ``D`` - - ``iota2`` -- an embedding of ``other`` into ``D`` + - ``iota2`` -- an embedding of ``other`` into ``D`` - - ``pr1`` -- the projection of ``D`` onto ``self`` (giving a - splitting ``1 - other - D - self - 1``) + - ``pr1`` -- the projection of ``D`` onto ``self`` (giving a + splitting ``1 - other - D - self - 1``) - - ``pr2`` -- the projection of ``D`` onto ``other`` (giving a - splitting ``1 - self - D - other - 1``) + - ``pr2`` -- the projection of ``D`` onto ``other`` (giving a + splitting ``1 - self - D - other - 1``) EXAMPLES:: @@ -2817,16 +2816,16 @@ def semidirect_product(self, N, mapping, check=True): INPUT: - - ``N`` -- A group which is acted on by ``self`` and + - ``N`` -- a group which is acted on by ``self`` and naturally embeds as a normal subgroup of the returned semidirect - product. + product - - ``mapping`` -- A pair of lists that together define a + - ``mapping`` -- a pair of lists that together define a homomorphism, `\phi :` ``self`` `\rightarrow` Aut(``N``), by giving, in the second list, the images of the generators of ``self`` - in the order given in the first list. + in the order given in the first list - - ``check`` -- A boolean that, if set to ``False``, will skip the + - ``check`` -- a boolean that, if set to ``False``, will skip the initial tests which are made on ``mapping``. This may be beneficial for large ``N``, since in such cases the injectivity test can be expensive. Set to ``True`` by default. @@ -2858,7 +2857,6 @@ def semidirect_product(self, N, mapping, check=True): of the generators of ``self`` are placed on additional letters and adjoined to the output's generators of ``self``. - EXAMPLES: Perhaps the most common example of a semidirect product comes @@ -3110,18 +3108,16 @@ def as_finitely_presented_group(self, reduced=False): INPUT: - - ``reduced`` -- (default ``False``) if ``True``, :meth:`FinitelyPresentedGroup.simplified - ` + - ``reduced`` -- (default: ``False``) if ``True``, + :meth:`FinitelyPresentedGroup.simplified ` is called, attempting to simplify the presentation of the finitely presented group - to be returned. + to be returned OUTPUT: finite presentation of ``self``, obtained by taking the image of the isomorphism returned by the GAP function ``IsomorphismFpGroupByGenerators`` - ALGORITHM: - - Uses GAP. + ALGORITHM: uses GAP EXAMPLES:: @@ -3243,7 +3239,7 @@ def commutator(self, other=None): INPUT: - - ``other`` -- (default: ``None``) a permutation group. + - ``other`` -- (default: ``None``) a permutation group OUTPUT: @@ -3340,7 +3336,7 @@ def commutator(self, other=None): @hap_decorator def cohomology(self, n, p=0): r""" - Computes the group cohomology `H^n(G, F)`, where `F = \ZZ` + Compute the group cohomology `H^n(G, F)`, where `F = \ZZ` if `p=0` and `F = \ZZ / p \ZZ` if `p > 0` is a prime. Wraps HAP's ``GroupHomology`` function, written by Graham Ellis. @@ -3425,7 +3421,7 @@ def cohomology_part(self, n, p=0): @hap_decorator def homology(self, n, p=0): r""" - Computes the group homology `H_n(G, F)`, where + Compute the group homology `H_n(G, F)`, where `F = \ZZ` if `p=0` and `F = \ZZ / p \ZZ` if `p > 0` is a prime. Wraps HAP's ``GroupHomology`` function, written by Graham Ellis. @@ -3472,7 +3468,7 @@ def homology(self, n, p=0): @hap_decorator def homology_part(self, n, p=0): r""" - Computes the `p`-part of the group homology + Compute the `p`-part of the group homology `H_n(G, F)`, where `F = \ZZ` if `p=0` and `F = \ZZ / p \ZZ` if `p > 0` is a prime. Wraps HAP's ``Homology`` function, written by Graham Ellis, applied to the @@ -3819,7 +3815,7 @@ def has_regular_subgroup(self, return_group=False): INPUT: - - ``return_group`` -- (boolean) If ``True``, a regular + - ``return_group`` -- boolean; if ``True``, a regular subgroup is returned if there is one, and ``None`` if there isn't. When ``return_group=False`` (default), only a boolean indicating whether such a group exists is returned instead. @@ -3866,7 +3862,7 @@ def blocks_all(self, representatives=True): INPUT: - - ``representative`` -- (boolean) whether to return all possible block + - ``representative`` -- boolean; whether to return all possible block systems of imprimitivity or only one of their representatives (the block can be obtained from its representative set `S` by computing the orbit of `S` under ``self``). @@ -3940,10 +3936,10 @@ def cosets(self, S, side='right'): INPUT: - - ``S`` -- a subgroup of ``self``. An error is raised - if ``S`` is not a subgroup. + - ``S`` -- a subgroup of ``self``; an error is raised + if ``S`` is not a subgroup - - ``side`` -- (default: ``'right'``) Determines if right cosets or + - ``side`` -- (default: ``'right'``) determines if right cosets or left cosets are returned. ``side`` refers to where the representative is placed in the products forming the cosets and thus allowable values are only ``'right'`` and ``'left'``. @@ -4105,7 +4101,7 @@ def cosets(self, S, side='right'): def minimal_generating_set(self): r""" - Return a minimal generating set + Return a minimal generating set. EXAMPLES:: @@ -4303,9 +4299,9 @@ def isomorphism_to(self, right): INPUT: - - ``self`` -- this group + - ``self`` -- this group - - ``right`` -- a permutation group + - ``right`` -- a permutation group OUTPUT: ``None``, or a morphism of permutation groups @@ -4352,9 +4348,9 @@ def is_isomorphic(self, right): INPUT: - - ``self`` -- this group + - ``self`` -- this group - - ``right`` -- a permutation group + - ``right`` -- a permutation group OUTPUT: boolean; ``True`` if ``self`` and ``right`` are isomorphic groups; ``False`` otherwise @@ -4635,7 +4631,7 @@ def is_primitive(self, domain=None): INPUT: - - ``domain`` (optional) + - ``domain`` -- optional .. SEEALSO:: @@ -5090,10 +5086,10 @@ def __init__(self, ambient, gens=None, gap_group=None, domain=None, - ``gens`` -- the generators of the subgroup - ``gap_group`` -- a GAP permutation group contained in the ambient group; - constructed from ``gens`` if not given. + constructed from ``gens`` if not given - - ``check`` -- ``True``: checks if ``gens`` are indeed elements of the - ambient group + - ``check`` -- boolean (default: ``True``); checks if ``gens`` are + indeed elements of the ambient group - ``canonicalize`` -- boolean (default: ``True``); if ``True``, sort generators and remove duplicates @@ -5361,10 +5357,10 @@ def __init__(self, gens, action, domain, gap_group=None, category=None, canonica - ``gap_group`` -- a gap or libgap permutation group, or a string defining one (default: ``None``), this is currently not supported - - ``canonicalize`` -- bool (default: ``True``); if ``True``, + - ``canonicalize`` -- boolean (default: ``True``); if ``True``, sort generators and remove duplicates - OUTPUT: a finite group action given as a permutation group. + OUTPUT: a finite group action given as a permutation group EXAMPLES:: @@ -5403,7 +5399,7 @@ def __init__(self, gens, action, domain, gap_group=None, category=None, canonica def orbits(self): """ - Returns the orbits of the elements of the domain under the + Return the orbits of the elements of the domain under the default group action. EXAMPLES:: diff --git a/src/sage/groups/perm_gps/permgroup_element.pyx b/src/sage/groups/perm_gps/permgroup_element.pyx index 4d6a67fe41b..2addd364812 100644 --- a/src/sage/groups/perm_gps/permgroup_element.pyx +++ b/src/sage/groups/perm_gps/permgroup_element.pyx @@ -288,14 +288,13 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): INPUT: - - ``g`` -- defines element + - ``g`` -- defines element - - ``parent`` -- defines parent group (``g`` must be in - parent if specified, or a :class:`TypeError` is raised) - - - ``check`` -- bool (default: ``True``); if ``False`` assumes ``g`` - is a gap element in parent (if specified) + - ``parent`` -- defines parent group (``g`` must be in + parent if specified, or a :exc:`TypeError` is raised) + - ``check`` -- boolean (default: ``True``); if ``False`` assumes ``g`` + is a gap element in parent (if specified) EXAMPLES: @@ -976,7 +975,7 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): INPUT: - - ``i`` -- integer + - ``i`` -- integer OUTPUT: a permutation group element @@ -1039,9 +1038,9 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): def __call__(self, i): r""" - Return the image of the integer i under this permutation. - Alternately, if i is a list, tuple or string, returns the result of - self acting on i. + Return the image of the integer `i` under this permutation. + Alternately, if `i` is a list, tuple or string, returns the result of + ``self`` acting on `i`. EXAMPLES:: @@ -1688,7 +1687,7 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): sign(sigma) = (-1)^{\sum_c len(c)-1} - where the sum is over cycles in self. + where the sum is over cycles in ``self``. """ cdef int cycle_len_sum = 0 cdef int i, k @@ -1792,7 +1791,7 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): INPUT: - - ``singletons`` -- boolean (default: ``False``) whether or not consider the + - ``singletons`` -- boolean (default: ``False``); whether or not consider the cycle that correspond to fixed point EXAMPLES:: @@ -1873,10 +1872,10 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): - ``g`` -- an element of the permutation group ``self.parent()`` - - ``singletons`` -- ``True`` or ``False`` depending on whether or not + - ``singletons`` -- boolean depending on whether or not trivial cycles should be counted (default: ``True``) - - ``as_list`` -- ``True`` or ``False`` depending on whether the cycle + - ``as_list`` -- boolean depending on whether the cycle type should be returned as a :class:`list` or as a :class:`Partition` (default: ``False``) @@ -1910,7 +1909,7 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): from sage.combinat.partition import _Partitions return _Partitions(cycle_type) - def has_descent(self, i, side="right", positive=False): + def has_descent(self, i, side='right', positive=False): r""" Return whether ``self`` has a left (resp. right) descent at position ``i``. If ``positive`` is ``True``, then test for a non @@ -1924,8 +1923,8 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): INPUT: - ``i`` -- an element of the index set - - ``side`` -- ``"left"`` or ``"right"`` (default: ``"right"``) - - ``positive`` -- a boolean (default: ``False``) + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'right'``) + - ``positive`` -- boolean (default: ``False``) EXAMPLES:: @@ -1936,13 +1935,13 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): False sage: s = S.simple_reflections() sage: x = s[1]*s[2] - sage: x.has_descent(1, side="right") + sage: x.has_descent(1, side='right') False - sage: x.has_descent(2, side="right") + sage: x.has_descent(2, side='right') True - sage: x.has_descent(1, side="left") + sage: x.has_descent(1, side='left') True - sage: x.has_descent(2, side="left") + sage: x.has_descent(2, side='left') False sage: S._test_has_descent() @@ -1998,13 +1997,13 @@ cdef class PermutationGroupElement(MultiplicativeGroupElement): INPUT: - - ``words`` -- a list of elements of the ambient group, generating + - ``words`` -- list of elements of the ambient group, generating a subgroup - - ``display`` -- boolean (default ``True``) whether to display + - ``display`` -- boolean (default: ``True``); whether to display additional information - - ``as_list`` -- boolean (default ``False``) whether to return + - ``as_list`` -- boolean (default: ``False``); whether to return the result as a list of pairs (generator, exponent) OUTPUT: diff --git a/src/sage/groups/perm_gps/permgroup_morphism.py b/src/sage/groups/perm_gps/permgroup_morphism.py index c0596d94b85..69f12016e60 100644 --- a/src/sage/groups/perm_gps/permgroup_morphism.py +++ b/src/sage/groups/perm_gps/permgroup_morphism.py @@ -247,8 +247,8 @@ def __init__(self, G, H, gens=None): r""" Some python code for wrapping GAP's ``GroupHomomorphismByImages`` function but only for permutation groups. Can be expensive if G is - large. This returns "fail" if gens does not generate self or if the map - does not extend to a group homomorphism, self - other. + large. This returns "fail" if gens does not generate ``self`` or if the map + does not extend to a group homomorphism, ``self`` - ``other``. EXAMPLES:: diff --git a/src/sage/groups/perm_gps/permgroup_named.py b/src/sage/groups/perm_gps/permgroup_named.py index c1f2683907b..5c153b93d4c 100644 --- a/src/sage/groups/perm_gps/permgroup_named.py +++ b/src/sage/groups/perm_gps/permgroup_named.py @@ -153,7 +153,7 @@ class PermutationGroup_symalt(PermutationGroup_unique): @staticmethod def __classcall__(cls, domain): """ - Normalizes the input of the constructor into a set + Normalize the input of the constructor into a set. INPUT: @@ -208,7 +208,7 @@ class SymmetricGroup(PermutationGroup_symalt): INPUT: - - ``n`` -- a positive integer, or list or tuple thereof + - ``n`` -- positive integer, or list or tuple thereof .. NOTE:: @@ -381,7 +381,7 @@ def _from_cactus_group_element(self, x): def cartan_type(self): r""" - Return the Cartan type of ``self`` + Return the Cartan type of ``self``. The symmetric group `S_n` is a Coxeter group of type `A_{n-1}`. @@ -674,7 +674,7 @@ def __init__(self, domain=None): INPUT: - - ``n`` -- a positive integer, or list or tuple thereof + - ``n`` -- positive integer, or list or tuple thereof .. NOTE:: @@ -728,7 +728,7 @@ def _repr_(self): def _gap_init_(self, gap=None): """ - Returns the string used to create this group in GAP. + Return the string used to create this group in GAP. EXAMPLES:: @@ -749,7 +749,7 @@ def __init__(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer .. NOTE:: @@ -839,7 +839,7 @@ class DiCyclicGroup(PermutationGroup_unique): INPUT: - - ``n`` -- a positive integer, two or greater + - ``n`` -- positive integer, two or greater OUTPUT: @@ -948,11 +948,11 @@ class DiCyclicGroup(PermutationGroup_unique): """ def __init__(self, n): r""" - The dicyclic group of order `4*n`, as a permutation group. + The dicyclic group of order `4n`, as a permutation group. INPUT: - n -- a positive integer, two or greater + - ``n`` -- a positive integer; 2 or greater EXAMPLES:: @@ -1077,7 +1077,7 @@ def __init__(self, n): INPUT: - - ``n`` -- integer among `\{1,2,3\}`. + - ``n`` -- integer among `\{1,2,3\}` EXAMPLES:: @@ -1111,7 +1111,7 @@ def _repr_(self): class SuzukiSporadicGroup(PermutationGroup_unique): def __init__(self): r""" - Suzuki Sporadic Group + Suzuki Sporadic Group. EXAMPLES:: @@ -1216,7 +1216,7 @@ class GeneralDihedralGroup(PermutationGroup_generic): INPUT: - - ``factors`` -- a list of the sizes of the cyclic factors of the + - ``factors`` -- list of the sizes of the cyclic factors of the abelian group being dihedralized (this will be sorted once entered) @@ -1349,7 +1349,6 @@ class GeneralDihedralGroup(PermutationGroup_generic): AUTHOR: - Kevin Halasz (2012-7-12) - """ def __init__(self, factors): r""" @@ -1425,7 +1424,7 @@ def __init__(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer OUTPUT: the dihedral group of order `2n`, as a permutation group @@ -1517,7 +1516,7 @@ def __init__(self, p, m): - ``p`` -- a prime number that is the prime underlying this p-group - - ``m`` -- a positive integer such that the order of this + - ``m`` -- positive integer such that the order of this group is the `p^m`. Be aware that, for even `p`, `m` must be greater than 3, while for odd `p`, `m` must be greater than 2. @@ -1658,7 +1657,7 @@ def __init__(self, m): INPUT: - - ``m`` -- a positive integer; the power of 2 that is the + - ``m`` -- positive integer; the power of 2 that is the group's order OUTPUT: @@ -1767,7 +1766,7 @@ def __init__(self, n): INPUT: - - ``n`` -- a positive integer in {9, 10, 11, 12, 21, 22, 23, 24}. + - ``n`` -- positive integer in {9, 10, 11, 12, 21, 22, 23, 24} OUTPUT: the Mathieu group of degree `n`, as a permutation group @@ -1817,7 +1816,7 @@ def __init__(self, d, n): INPUT: - - ``d`` -- non-negative integer; the degree + - ``d`` -- nonnegative integer; the degree - ``n`` -- positive integer; the index of the group in the GAP database, starting at 1 @@ -1888,7 +1887,7 @@ def __init__(self, d, n): def transitive_number(self): """ - Return the index of this group in the GAP database, starting at 1 + Return the index of this group in the GAP database, starting at 1. EXAMPLES:: @@ -1899,7 +1898,7 @@ def transitive_number(self): def degree(self): """ - Return the degree of this permutation group + Return the degree of this permutation group. EXAMPLES:: @@ -1948,14 +1947,13 @@ def TransitiveGroups(d=None): ... NotImplementedError: only the transitive groups of degree at most 31 are available in GAP's database - """ if d is None: return TransitiveGroupsAll() d = Integer(d) if d < 0: - raise ValueError("a transitive group acts on a non negative integer number of positions") + raise ValueError("a transitive group acts on a nonnegative integer number of positions") return TransitiveGroupsOfDegree(d) @@ -2090,7 +2088,7 @@ def __getitem__(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -2209,9 +2207,9 @@ class PrimitiveGroup(PermutationGroup_unique): INPUT: - - ``d`` -- non-negative integer. the degree of the group. + - ``d`` -- nonnegative integer; the degree of the group - - ``n`` -- positive integer. the index of the group in the GAP + - ``n`` -- positive integer; the index of the group in the GAP database, starting at 1 OUTPUT: the ``n``-th primitive group of degree ``d`` @@ -2252,9 +2250,7 @@ def __init__(self, d, n): """ The Python constructor. - INPUT/OUTPUT: - - See :class:`PrimitiveGroup`. + INPUT/OUTPUT: see :class:`PrimitiveGroup` TESTS:: @@ -2312,7 +2308,7 @@ def group_primitive_id(self): def PrimitiveGroups(d=None): """ - Return the set of all primitive groups of a given degree ``d`` + Return the set of all primitive groups of a given degree ``d``. INPUT: @@ -2354,7 +2350,7 @@ def PrimitiveGroups(d=None): else: d = Integer(d) if d < 0: - raise ValueError("a primitive group acts on a non negative integer number of positions") + raise ValueError("a primitive group acts on a nonnegative integer number of positions") return PrimitiveGroupsOfDegree(d) @@ -2413,7 +2409,7 @@ def __contains__(self, G): INPUT: - - `G` -- anything. + - ``G`` -- anything OUTPUT: boolean @@ -2486,7 +2482,7 @@ def __contains__(self, G): INPUT: - - `G` -- anything. + - ``G`` -- anything OUTPUT: boolean @@ -2507,7 +2503,7 @@ def __getitem__(self, n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -2931,11 +2927,12 @@ def __init__(self, n, q, name='a'): INPUT: - - n -- positive integer; the degree - - q -- prime power; the size of the ground field - - name -- (default: 'a') variable name of indeterminate of finite field GF(q) + - ``n`` -- positive integer; the degree + - ``q`` -- prime power; the size of the ground field + - ``name`` -- (default: ``'a'``) variable name of indeterminate of finite + field `\GF(q)` - OUTPUT: PSU(n,q) + OUTPUT: PSU(`n`,`q`) .. NOTE:: diff --git a/src/sage/groups/raag.py b/src/sage/groups/raag.py index 22c44cb2312..4313f500319 100644 --- a/src/sage/groups/raag.py +++ b/src/sage/groups/raag.py @@ -90,7 +90,7 @@ class RightAngledArtinGroup(ArtinGroup): INPUT: - ``G`` -- a graph - - ``names`` -- a string or a list of generator names + - ``names`` -- string or list of generator names EXAMPLES:: diff --git a/src/sage/groups/semimonomial_transformations/semimonomial_transformation.pyx b/src/sage/groups/semimonomial_transformations/semimonomial_transformation.pyx index 013e27fa28a..72042533883 100644 --- a/src/sage/groups/semimonomial_transformations/semimonomial_transformation.pyx +++ b/src/sage/groups/semimonomial_transformations/semimonomial_transformation.pyx @@ -235,7 +235,7 @@ cdef class SemimonomialTransformation(MultiplicativeGroupElement): def __repr__(self): """ - String representation of `self`. + String representation of ``self``. EXAMPLES:: diff --git a/src/sage/groups/semimonomial_transformations/semimonomial_transformation_group.py b/src/sage/groups/semimonomial_transformations/semimonomial_transformation_group.py index 50b5e5741d5..108d8542c87 100644 --- a/src/sage/groups/semimonomial_transformations/semimonomial_transformation_group.py +++ b/src/sage/groups/semimonomial_transformations/semimonomial_transformation_group.py @@ -152,13 +152,13 @@ def _element_constructor_(self, arg1, v=None, perm=None, autom=None, check=True) INPUT: - - ``arg1`` (optional) -- either the integers 0, 1 or an element of ``self`` + - ``arg1`` -- (optional) either the integers 0, 1 or an element of ``self`` - - ``v`` (optional) -- a vector of length ``self.degree()`` + - ``v`` -- (optional) a vector of length ``self.degree()`` - - ``perm`` (optional) -- a permutation of degree ``self.degree()`` + - ``perm`` -- (optional) a permutation of degree ``self.degree()`` - - ``autom`` (optional) -- an automorphism of the ring + - ``autom`` -- (optional) an automorphism of the ring EXAMPLES:: diff --git a/src/sage/homology/chain_complex.py b/src/sage/homology/chain_complex.py index fd43e81fd14..97111a0cbfa 100644 --- a/src/sage/homology/chain_complex.py +++ b/src/sage/homology/chain_complex.py @@ -73,7 +73,7 @@ def _latex_module(R, m): INPUT: - ``R`` -- a commutative ring - - ``m`` -- non-negative integer + - ``m`` -- nonnegative integer This is used by the ``_latex_`` method for chain complexes. @@ -101,30 +101,28 @@ def ChainComplex(data=None, base_ring=None, grading_group=None, INPUT: - ``data`` -- the data defining the chain complex; see below for - more details. + more details The following keyword arguments are supported: - - ``base_ring`` -- a commutative ring (optional), the ring over + - ``base_ring`` -- a commutative ring (optional); the ring over which the chain complex is defined. If this is not specified, it is determined by the data defining the chain complex. - ``grading_group`` -- a additive free abelian group (optional, - default ``ZZ``), the group over which the chain complex is - indexed. + default ``ZZ``); the group over which the chain complex is + indexed - ``degree_of_differential`` -- element of grading_group - (default: ``1``). The degree of the differential. + (default: ``1``); the degree of the differential - - ``degree`` -- alias for ``degree_of_differential``. + - ``degree`` -- alias for ``degree_of_differential`` - - ``check`` -- boolean (default: ``True``). If ``True``, + - ``check`` -- boolean (default: ``True``); if ``True``, check that each consecutive pair of differentials are - composable and have composite equal to zero. + composable and have composite equal to zero - OUTPUT: - - A chain complex. + OUTPUT: a chain complex .. WARNING:: @@ -323,7 +321,7 @@ class Chain_class(ModuleElement): def __init__(self, parent, vectors, check=True): r""" - A Chain in a Chain Complex + A Chain in a Chain Complex. A chain is collection of module elements for each module `C_n` of the chain complex `(C_n, d_n)`. There is no restriction on @@ -425,7 +423,6 @@ def _ascii_art_(self): sage: C = ChainComplex(base_ring=ZZ) sage: ascii_art(C()) 0 - """ from sage.typeset.ascii_art import AsciiArt @@ -519,10 +516,8 @@ def is_cycle(self): """ Return whether the chain is a cycle. - OUTPUT: - - Boolean. Whether the elements of the chain are in the kernel - of the differentials. + OUTPUT: boolean; whether the elements of the chain are in the kernel + of the differentials EXAMPLES:: @@ -544,7 +539,7 @@ def is_boundary(self): OUTPUT: - Boolean. Whether the elements of the chain are in the image of + boolean; whether the elements of the chain are in the image of the differentials. EXAMPLES:: @@ -570,7 +565,7 @@ def is_boundary(self): def _add_(self, other): """ - Module addition + Module addition. EXAMPLES:: @@ -594,7 +589,7 @@ def _add_(self, other): def _lmul_(self, scalar): """ - Scalar multiplication + Scalar multiplication. EXAMPLES:: @@ -766,7 +761,7 @@ def random_element(self): @cached_method def rank(self, degree, ring=None): r""" - Return the rank of a differential + Return the rank of a differential. INPUT: @@ -851,7 +846,7 @@ def nonzero_degrees(self): @cached_method def ordered_degrees(self, start=None, exclude_first=False): r""" - Sort the degrees in the order determined by the differential + Sort the degrees in the order determined by the differential. INPUT: @@ -860,12 +855,10 @@ def ordered_degrees(self, start=None, exclude_first=False): - ``exclude_first`` -- boolean (optional; default: ``False``); whether to exclude the lowest degree -- this is a - handy way to just get the degrees of the non-zero modules, + handy way to just get the degrees of the nonzero modules, as the domain of the first differential is zero. - OUTPUT: - - If ``start`` has been specified, the longest tuple of degrees + OUTPUT: if ``start`` has been specified, the longest tuple of degrees * containing ``start`` (unless ``start`` would be the first and ``exclude_first=True``), @@ -875,7 +868,7 @@ def ordered_degrees(self, start=None, exclude_first=False): * such that none of the corresponding differentials are `0\times 0`. If ``start`` has not been specified, a tuple of such tuples of - degrees. One for each sequence of non-zero differentials. They + degrees. One for each sequence of nonzero differentials. They are returned in sort order. EXAMPLES:: @@ -926,11 +919,9 @@ def ordered_degrees(self, start=None, exclude_first=False): def degree_of_differential(self): """ - Return the degree of the differentials of the complex - - OUTPUT: + Return the degree of the differentials of the complex. - An element of the grading group. + OUTPUT: an element of the grading group EXAMPLES:: @@ -1045,7 +1036,7 @@ def free_module(self, degree=None): INPUT: - - ``degree`` -- an element of the grading group or ``None`` (default). + - ``degree`` -- an element of the grading group or ``None`` (default) OUTPUT: @@ -1072,7 +1063,7 @@ def free_module(self, degree=None): def __hash__(self): """ - The hash is formed by combining the hashes of + The hash is formed by combining the hashes of. - the base ring - the differentials -- the matrices and their degrees @@ -1393,7 +1384,7 @@ def betti(self, deg=None, base_ring=None): INPUT: - ``deg`` -- an element of the grading group for the chain - complex or None (default ``None``); if ``None``, + complex or ``None`` (default: ``None``); if ``None``, then return every Betti number, as a dictionary indexed by degree, or if an element of the grading group, then return the Betti number in that degree @@ -1442,11 +1433,11 @@ def torsion_list(self, max_prime, min_prime=2): INPUT: - - ``max_prime`` -- prime number; search for torsion mod `p` for - all `p` strictly less than this number + - ``max_prime`` -- prime number; search for torsion mod `p` for + all `p` strictly less than this number - - ``min_prime`` -- prime (default: 2); search for - torsion mod `p` for primes at least as big as this + - ``min_prime`` -- prime (default: 2); search for + torsion mod `p` for primes at least as big as this Return a list of pairs `(p, d)` where `p` is a prime at which there is torsion and `d` is a list of dimensions in which this @@ -1562,7 +1553,7 @@ def shift(self, n=1): INPUT: - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) The *shift* operation is also sometimes called *translation* or *suspension*. @@ -1826,7 +1817,7 @@ def cartesian_product(self, *factors, **kwds): INPUT: - - ``subdivide`` -- (default: ``False``) whether to subdivide the + - ``subdivide`` -- boolean (default: ``False``); whether to subdivide the the differential matrices EXAMPLES:: @@ -1954,7 +1945,7 @@ def tensor(self, *factors, **kwds): INPUT: - - ``subdivide`` -- (default: ``False``) whether to subdivide the + - ``subdivide`` -- boolean (default: ``False``); whether to subdivide the the differential matrices .. TODO:: diff --git a/src/sage/homology/chain_complex_homspace.py b/src/sage/homology/chain_complex_homspace.py index 1170b50b885..00fa8f1671a 100644 --- a/src/sage/homology/chain_complex_homspace.py +++ b/src/sage/homology/chain_complex_homspace.py @@ -121,7 +121,6 @@ def is_ChainComplexHomspace(x): use 'isinstance(..., ChainComplexHomspace)' instead. See https://github.com/sagemath/sage/issues/38184 for details. True - """ from sage.misc.superseded import deprecation deprecation(38184, @@ -144,7 +143,6 @@ class ChainComplexHomspace(sage.categories.homset.Homset): from Chain complex with at most 5 nonzero terms over Integer Ring to Chain complex with at most 5 nonzero terms over Integer Ring in Category of chain complexes over Integer Ring - """ def __call__(self, f): """ @@ -162,6 +160,5 @@ def __call__(self, f): sage: y = G(f) sage: x == y True - """ return ChainComplexMorphism(f, self.domain(), self.codomain()) diff --git a/src/sage/homology/chain_complex_morphism.py b/src/sage/homology/chain_complex_morphism.py index af68bf0c906..96080c9e33b 100644 --- a/src/sage/homology/chain_complex_morphism.py +++ b/src/sage/homology/chain_complex_morphism.py @@ -331,7 +331,6 @@ def __neg__(self): [ 0 -1 0 0] [ 0 0 -1 0] [ 0 0 0 -1]} - """ f = dict() for i in self._matrix_dictionary.keys(): @@ -431,7 +430,7 @@ def __mul__(self, x): [2] Before :issue:`19065`, the following multiplication produced a - :class:`KeyError` because `f` was not explicitly defined in degree 2:: + :exc:`KeyError` because `f` was not explicitly defined in degree 2:: sage: C0 = ChainComplex({0: zero_matrix(ZZ, 0, 1)}) sage: C1 = ChainComplex({1: zero_matrix(ZZ, 0, 1)}) diff --git a/src/sage/homology/chain_homotopy.py b/src/sage/homology/chain_homotopy.py index 3b5dece7d91..ae3324623f2 100644 --- a/src/sage/homology/chain_homotopy.py +++ b/src/sage/homology/chain_homotopy.py @@ -64,7 +64,7 @@ class ChainHomotopy(Morphism): - ``matrices`` -- dictionary of matrices, keyed by dimension - ``f`` -- chain map `C \to D` - - ``g`` (optional) -- chain map `C \to D` + - ``g`` -- (optional) chain map `C \to D` The dictionary ``matrices`` defines ``H`` by specifying the matrix defining it in each degree: the entry `m` corresponding to key `i` diff --git a/src/sage/homology/chains.py b/src/sage/homology/chains.py index b9a54940943..3489d69286c 100644 --- a/src/sage/homology/chains.py +++ b/src/sage/homology/chains.py @@ -29,13 +29,13 @@ class CellComplexReference(): def __init__(self, cell_complex, degree, cells=None): """ - Auxiliary base class for chains and cochains + Auxiliary base class for chains and cochains. INPUT: - - ``cell_complex`` -- The cell complex to reference + - ``cell_complex`` -- the cell complex to reference - - ``degree`` -- integer. The degree of the (co)chains + - ``degree`` -- integer; the degree of the (co)chains - ``cells`` -- tuple of cells or ``None``. Does not necessarily have to be the cells in the given degree, for computational purposes this @@ -60,11 +60,9 @@ def __init__(self, cell_complex, degree, cells=None): def cell_complex(self): """ - Return the underlying cell complex + Return the underlying cell complex. - OUTPUT: - - A cell complex. + OUTPUT: a cell complex EXAMPLES:: @@ -76,11 +74,9 @@ def cell_complex(self): def degree(self): """ - Return the dimension of the cells - - OUTPUT: + Return the dimension of the cells. - Integer. The dimension of the cells. + OUTPUT: integer; the dimension of the cells EXAMPLES:: @@ -99,7 +95,7 @@ class Chains(CellComplexReference, CombinatorialFreeModule): - ``n_cells`` -- tuple of `n`-cells, which thus forms a basis for this module - - ``base_ring`` -- optional (default `\ZZ`) + - ``base_ring`` -- (default: `\ZZ`) One difference between chains and cochains is notation. In a simplicial complex, for example, a simplex ``(0,1,2)`` is written @@ -175,9 +171,7 @@ def dual(self): """ Return the cochains. - OUTPUT: - - The cochains of the same cells with the same base ring. + OUTPUT: the cochains of the same cells with the same base ring EXAMPLES:: @@ -200,9 +194,7 @@ def chain_complex(self): """ Return the chain complex. - OUTPUT: - - Chain complex, see :mod:`sage.homology.chain_complex`. + OUTPUT: chain complex, see :mod:`sage.homology.chain_complex` EXAMPLES:: @@ -225,11 +217,9 @@ class Element(CombinatorialFreeModule.Element): def to_complex(self): """ - Return the corresponding chain complex element + Return the corresponding chain complex element. - OUTPUT: - - An element of the chain complex, see :mod:`sage.homology.chain_complex`. + OUTPUT: an element of the chain complex, see :mod:`sage.homology.chain_complex` EXAMPLES:: @@ -251,11 +241,9 @@ def to_complex(self): def boundary(self): """ - Return the boundary of the chain - - OUTPUT: + Return the boundary of the chain. - The boundary as a chain in one degree lower. + OUTPUT: the boundary as a chain in one degree lower EXAMPLES:: @@ -278,11 +266,9 @@ def boundary(self): def is_cycle(self): """ - Test whether the chain is a cycle - - OUTPUT: + Test whether the chain is a cycle. - Boolean. Whether the :meth:`boundary` vanishes. + OUTPUT: boolean; whether the :meth:`boundary` vanishes EXAMPLES:: @@ -304,12 +290,10 @@ def is_cycle(self): def is_boundary(self): """ - Test whether the chain is a boundary + Test whether the chain is a boundary. - OUTPUT: - - Boolean. Whether the chain is the :meth:`boundary` of a chain in one - degree higher. + OUTPUT: boolean; whether the chain is the :meth:`boundary` of a + chain in one degree higher EXAMPLES:: @@ -338,7 +322,7 @@ class Cochains(CellComplexReference, CombinatorialFreeModule): - ``n_cells`` -- tuple of `n`-cells, which thus forms a basis for this module - - ``base_ring`` -- optional (default `\ZZ`) + - ``base_ring`` -- (default: `\ZZ`) One difference between chains and cochains is notation. In a simplicial complex, for example, a simplex ``(0,1,2)`` is written @@ -413,11 +397,9 @@ def __init__(self, cell_complex, degree, cells=None, base_ring=None): def dual(self): """ - Return the chains - - OUTPUT: + Return the chains. - The chains of the same cells with the same base ring. + OUTPUT: the chains of the same cells with the same base ring EXAMPLES:: @@ -440,9 +422,7 @@ def cochain_complex(self): """ Return the cochain complex. - OUTPUT: - - Cochain complex, see :mod:`sage.homology.chain_complex`. + OUTPUT: cochain complex, see :mod:`sage.homology.chain_complex` EXAMPLES:: @@ -466,11 +446,9 @@ class Element(CombinatorialFreeModule.Element): def to_complex(self): """ - Return the corresponding cochain complex element - - OUTPUT: + Return the corresponding cochain complex element. - An element of the cochain complex, see :mod:`sage.homology.chain_complex`. + OUTPUT: an element of the cochain complex, see :mod:`sage.homology.chain_complex` EXAMPLES:: @@ -492,11 +470,9 @@ def to_complex(self): def coboundary(self): r""" - Return the coboundary of this cochain + Return the coboundary of this cochain. - OUTPUT: - - The coboundary as a cochain in one degree higher. + OUTPUT: the coboundary as a cochain in one degree higher EXAMPLES:: @@ -519,11 +495,9 @@ def coboundary(self): def is_cocycle(self): """ - Test whether the cochain is a cocycle - - OUTPUT: + Test whether the cochain is a cocycle. - Boolean. Whether the :meth:`coboundary` vanishes. + OUTPUT: boolean; whether the :meth:`coboundary` vanishes EXAMPLES:: @@ -545,12 +519,10 @@ def is_cocycle(self): def is_coboundary(self): """ - Test whether the cochain is a coboundary - - OUTPUT: + Test whether the cochain is a coboundary. - Boolean. Whether the cochain is the :meth:`coboundary` of a cochain - in one degree lower. + OUTPUT: boolean; whether the cochain is the :meth:`coboundary` of a cochain + in one degree lower EXAMPLES:: diff --git a/src/sage/homology/free_resolution.py b/src/sage/homology/free_resolution.py index 29c33e4e2a6..89b3352c560 100644 --- a/src/sage/homology/free_resolution.py +++ b/src/sage/homology/free_resolution.py @@ -230,7 +230,7 @@ def _repr_module(self, i): INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: @@ -271,11 +271,11 @@ def _repr_module(self, i): @abstract_method def differential(self, i): r""" - Return the ``i``-th differential map. + Return the `i`-th differential map. INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer TESTS:: @@ -375,7 +375,7 @@ def _repr_(self): INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: @@ -409,11 +409,11 @@ def __len__(self): def __getitem__(self, i): r""" - Return the ``i``-th free module of this resolution. + Return the `i`-th free module of this resolution. INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: @@ -443,11 +443,11 @@ def __getitem__(self, i): def differential(self, i): r""" - Return the ``i``-th differential map. + Return the `i`-th differential map. INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: @@ -542,11 +542,11 @@ def differential(self, i): def matrix(self, i): r""" - Return the matrix representing the ``i``-th differential map. + Return the matrix representing the `i`-th differential map. INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer EXAMPLES:: diff --git a/src/sage/homology/graded_resolution.py b/src/sage/homology/graded_resolution.py index ceadd15c2de..76361480d8e 100644 --- a/src/sage/homology/graded_resolution.py +++ b/src/sage/homology/graded_resolution.py @@ -101,12 +101,11 @@ class GradedFiniteFreeResolution(FiniteFreeResolution): - ``degrees`` -- (default: a list with all entries `1`) a list of integers or integer vectors giving degrees of variables of `S` - - ``shifts`` -- a list of integers or integer vectors giving shifts of + - ``shifts`` -- list of integers or integer vectors giving shifts of degrees of `n` summands of the free module `M`; this is a list of zero degrees of length `n` by default - - ``name`` -- a string; name of the base ring - + - ``name`` -- string; name of the base ring """ def __init__(self, module, degrees=None, shifts=None, name='S', **kwds): r""" @@ -337,7 +336,7 @@ def __init__(self, module, degrees=None, *args, **kwds): sage: M = matrix([[x^3, 3*x^3, 5*x^3], ....: [0, x, 2*x]]) sage: res = FreeResolution(M, graded=True) - sage: TestSuite(res).run(skip="_test_pickling") + sage: TestSuite(res).run(skip='_test_pickling') """ super().__init__(module, degrees=degrees, *args, **kwds) @@ -422,11 +421,11 @@ class GradedFiniteFreeResolution_singular(GradedFiniteFreeResolution, FiniteFree - ``degrees`` -- (default: a list with all entries `1`) a list of integers or integer vectors giving degrees of variables of `S` - - ``shifts`` -- a list of integers or integer vectors giving shifts of + - ``shifts`` -- list of integers or integer vectors giving shifts of degrees of `n` summands of the free module `M`; this is a list of zero degrees of length `n` by default - - ``name`` -- a string; name of the base ring + - ``name`` -- string; name of the base ring - ``algorithm`` -- Singular algorithm to compute a resolution of ``ideal`` diff --git a/src/sage/homology/hochschild_complex.py b/src/sage/homology/hochschild_complex.py index ea42164ef9d..a6412a1afc8 100644 --- a/src/sage/homology/hochschild_complex.py +++ b/src/sage/homology/hochschild_complex.py @@ -113,7 +113,7 @@ def _repr_(self): sage: SGA = SymmetricGroupAlgebra(QQ, 3) sage: T = SGA.trivial_representation() - sage: T.rename("Trivial representation of SGA") + sage: T.rename('Trivial representation of SGA') sage: SGA.hochschild_complex(T) Hochschild complex of Symmetric group algebra of order 3 over Rational Field with coefficients in Trivial representation of SGA @@ -184,7 +184,7 @@ def module(self, d): # Symmetric group algebra of order 3 over Rational Field """ if d < 0: - raise ValueError("only defined for non-negative degree") + raise ValueError("only defined for nonnegative degree") return tensor([self._M] + [self._A] * d) @cached_method @@ -668,7 +668,7 @@ def arrow_art(d): def _add_(self, other): """ - Module addition + Module addition. EXAMPLES:: @@ -703,7 +703,7 @@ def _add_(self, other): def _lmul_(self, scalar): """ - Scalar multiplication + Scalar multiplication. EXAMPLES:: diff --git a/src/sage/homology/homology_morphism.py b/src/sage/homology/homology_morphism.py index 01308d46b9e..6db0315945f 100644 --- a/src/sage/homology/homology_morphism.py +++ b/src/sage/homology/homology_morphism.py @@ -52,11 +52,11 @@ class InducedHomologyMorphism(Morphism): - ``map`` -- the map of simplicial complexes - ``base_ring`` -- a field (default: ``QQ``) - - ``cohomology`` -- boolean (default: ``False``). If + - ``cohomology`` -- boolean (default: ``False``); if ``True``, return the induced map in cohomology rather than - homology. + homology - .. note:: + .. NOTE:: This is not intended to be used directly by the user, but instead via the method @@ -136,9 +136,9 @@ def __init__(self, map, base_ring=None, cohomology=False): - ``map`` -- the map of simplicial complexes - ``base_ring`` -- a field (default: ``QQ``) - - ``cohomology`` -- boolean (default: ``False``). If + - ``cohomology`` -- boolean (default: ``False``); if ``True``, return the induced map in cohomology rather than - homology. + homology EXAMPLES:: diff --git a/src/sage/homology/homology_vector_space_with_basis.py b/src/sage/homology/homology_vector_space_with_basis.py index 04b880f814e..bb576a56462 100644 --- a/src/sage/homology/homology_vector_space_with_basis.py +++ b/src/sage/homology/homology_vector_space_with_basis.py @@ -70,7 +70,7 @@ class HomologyVectorSpaceWithBasis(CombinatorialFreeModule): - ``base_ring`` -- must be a field - ``cell_complex`` -- the cell complex whose homology we are computing - - ``cohomology`` -- (default: ``False``) if ``True``, return + - ``cohomology`` -- boolean (default: ``False``); if ``True``, return the cohomology as a module - ``category`` -- (optional) a subcategory of modules with basis @@ -340,7 +340,6 @@ def _repr_term(self, i): sage: co = simplicial_complexes.KleinBottle().cohomology_ring(GF(2)) sage: co.basis()[1,0] # indirect doctest h^{1,0} - """ sym = '^' if self._cohomology else '_' return 'h{}{{{},{}}}'.format(sym, i[0], i[1]) @@ -934,7 +933,6 @@ def cup_product(self, other): sage: a,b = K.cohomology_ring(QQ).basis(2) sage: a**0 h^{0,0} + h^{0,1} - """ return self * other @@ -1282,7 +1280,7 @@ def steenrod_module_map(self, deg_domain, deg_codomain, side='left'): - ``deg_codomain`` -- the degree of the codomain in the cohomology ring - - ``side`` -- (default ``'left'``) whether we are computing + - ``side`` -- (default: ``'left'``) whether we are computing the action as a left module action or a right module We will write this with respect to the left action; @@ -1419,7 +1417,7 @@ def sum_indices(k, i_k_plus_one, S_k_plus_one): INPUT: - - ``k`` -- non-negative integer + - ``k`` -- nonnegative integer - ``i_k_plus_one`` -- the positive integer `i_{k+1}` - ``S_k_plus_one`` -- the integer `S(k+1)` diff --git a/src/sage/homology/koszul_complex.py b/src/sage/homology/koszul_complex.py index 22a1ceb5d80..005d876a04c 100644 --- a/src/sage/homology/koszul_complex.py +++ b/src/sage/homology/koszul_complex.py @@ -53,7 +53,7 @@ class KoszulComplex(ChainComplex_class, UniqueRepresentation): INPUT: - ``R`` -- the base ring - - ``elements`` -- a tuple of elements of ``R`` + - ``elements`` -- tuple of elements of `R` EXAMPLES:: diff --git a/src/sage/homology/matrix_utils.py b/src/sage/homology/matrix_utils.py index 4f10ae415a3..b44a25060d5 100644 --- a/src/sage/homology/matrix_utils.py +++ b/src/sage/homology/matrix_utils.py @@ -33,7 +33,7 @@ def dhsw_snf(mat, verbose=False): INPUT: - - ``mat`` -- an integer matrix, either sparse or dense. + - ``mat`` -- integer matrix, either sparse or dense (They use the transpose of the matrix considered here, so they use rows instead of columns.) @@ -56,7 +56,7 @@ def dhsw_snf(mat, verbose=False): Suppose that there were `N` of these. The resulting matrix should be much smaller; we then feed it - to Sage's ``elementary_divisors`` function, and prepend `N` 1's to + to Sage's ``elementary_divisors`` function, and prepend `N` 1s to account for the rows deleted in the previous step. EXAMPLES:: diff --git a/src/sage/homology/tests.py b/src/sage/homology/tests.py index 206617843a9..5ac7d67bfb2 100644 --- a/src/sage/homology/tests.py +++ b/src/sage/homology/tests.py @@ -17,10 +17,9 @@ def random_chain_complex(level=1): random matrix in a random degree, with differential of degree either 1 or -1. The matrix is randomly sparse or dense. - :param level: measure of complexity: the larger this is, the - larger the matrix can be, and the larger its degree can be in - the chain complex. - :type level: positive integer; optional, default 1 + - ``level`` -- positive integer (default: 1); measure of complexity. The larger + this is, the larger the matrix can be, and the larger its degree can be + in the chain complex. EXAMPLES:: @@ -47,12 +46,11 @@ def random_simplicial_complex(level=1, p=0.5): """ Return a random simplicial complex. - :param level: measure of complexity: the larger this is, the more - vertices and therefore the larger the possible dimension of the - complex. - :type level: positive integer; optional, default 1 - :param p: probability, passed on to ``simplicial_complexes.RandomComplex`` - :type p: float between 0 and 1; optional; default 0.5 + - ``level`` -- positive integer (default: 1); measure of complexity. The + larger this is, the more vertices and therefore the larger the possible + dimension of the complex. + - ``p`` -- float between 0 and 1 (default: 0.5); probability, passed on to + ``simplicial_complexes.RandomComplex`` EXAMPLES:: diff --git a/src/sage/interacts/library.py b/src/sage/interacts/library.py index 16fadc5b594..a3da2cdc403 100644 --- a/src/sage/interacts/library.py +++ b/src/sage/interacts/library.py @@ -153,7 +153,7 @@ def library_wrapper(): def html(obj): r""" - Shorthand to pretty print HTML + Shorthand to pretty print HTML. EXAMPLES:: @@ -231,9 +231,9 @@ def taylor_polynomial(title, f, order: int): @library_interact( title=lambda: text_control("

Definite integral

"), - f=lambda: input_box(default="3*x", label="$f(x)=$"), - g=lambda: input_box(default="x^2", label="$g(x)=$"), - interval=lambda: range_slider(-10, 10, default=(0, 3), label="Interval"), + f=lambda: input_box(default='3*x', label="$f(x)=$"), + g=lambda: input_box(default='x^2', label="$g(x)=$"), + interval=lambda: range_slider(-10, 10, default=(0, 3), label='Interval'), x_range=lambda: range_slider(-10, 10, default=(0, 3), label="plot range (x)"), selection=lambda: selector( ["f", "g", "f and g", "f - g"], default="f and g", label="Select" @@ -278,11 +278,11 @@ def definite_integral(title, f, g, interval, x_range, selection): # Plot function f. if selection != "g": - f_plot = plot(f(x), x, x_range, color="blue", thickness=1.5) + f_plot = plot(f(x), x, x_range, color='blue', thickness=1.5) # Color and calculate the area between f and the horizontal axis. if selection == "f" or selection == "f and g": - f_plot += plot(f(x), x, interval, color="blue", fill=True, fillcolor="blue", fillalpha=0.15) + f_plot += plot(f(x), x, interval, color='blue', fill=True, fillcolor='blue', fillalpha=0.15) text += r"$\int_{%.2f}^{%.2f}(\color{Blue}{f(x)})\,\mathrm{d}x=\int_{%.2f}^{%.2f}(%s)\,\mathrm{d}x=%.2f$" % ( interval[0], interval[1], interval[0], interval[1], @@ -295,8 +295,8 @@ def definite_integral(title, f, g, interval, x_range, selection): # Plot function g. Also color and calculate the area between g and the horizontal axis. if selection == "g" or selection == "f and g": - g_plot = plot(g(x), x, x_range, color="green", thickness=1.5) - g_plot += plot(g(x), x, interval, color="green", fill=True, fillcolor="yellow", fillalpha=0.5) + g_plot = plot(g(x), x, x_range, color='green', thickness=1.5) + g_plot += plot(g(x), x, interval, color='green', fill=True, fillcolor='yellow', fillalpha=0.5) text += r"$\int_{%.2f}^{%.2f}(\color{Green}{g(x)})\,\mathrm{d}x=\int_{%.2f}^{%.2f}(%s)\,\mathrm{d}x=%.2f$" % ( interval[0], interval[1], interval[0], interval[1], @@ -306,9 +306,9 @@ def definite_integral(title, f, g, interval, x_range, selection): # Plot function f-g. Also color and calculate the area between f-g and the horizontal axis. if selection == "f - g": - g_plot = plot(g(x), x, x_range, color="green", thickness=1.5) - g_plot += plot(g(x), x, interval, color="green", fill=f(x), fillcolor="red", fillalpha=0.15) - h_plot = plot(f(x)-g(x), x, interval, color="red", thickness=1.5, fill=True, fillcolor="red", fillalpha=0.15) + g_plot = plot(g(x), x, x_range, color='green', thickness=1.5) + g_plot += plot(g(x), x, interval, color='green', fill=f(x), fillcolor='red', fillalpha=0.15) + h_plot = plot(f(x)-g(x), x, interval, color='red', thickness=1.5, fill=True, fillcolor='red', fillalpha=0.15) text = r"$\int_{%.2f}^{%.2f}(\color{Red}{f(x)-g(x)})\,\mathrm{d}x=\int_{%.2f}^{%.2f}(%s)\,\mathrm{d}x=%.2f$" % ( interval[0], interval[1], interval[0], interval[1], @@ -322,7 +322,7 @@ def definite_integral(title, f, g, interval, x_range, selection): @library_interact( title=lambda: text_control("

Derivative grapher

"), - function=lambda: input_box(default="x^5-3*x^3+1", label="Function:"), + function=lambda: input_box(default='x^5-3*x^3+1', label='Function:'), x_range=lambda: range_slider(-15, 15, 0.1, default=(-2, 2), label="Range (x)"), y_range=lambda: range_slider(-15, 15, 0.1, default=(-8, 6), label="Range (y)"), ) @@ -355,7 +355,7 @@ def function_derivative(title, function, x_range, y_range): f = symbolic_expression(function).function(x) df = derivative(f, x) ddf = derivative(df, x) - plots = plot(f(x), x_range, thickness=1.5) + plot(df(x), x_range, color="green") + plot(ddf(x), x_range, color="red") + plots = plot(f(x), x_range, thickness=1.5) + plot(df(x), x_range, color='green') + plot(ddf(x), x_range, color='red') if y_range == (0,0): show(plots, xmin=x_range[0], xmax=x_range[1]) else: @@ -368,9 +368,9 @@ def function_derivative(title, function, x_range, y_range): @library_interact( title=lambda: text_control("

Difference quotient

"), - f=lambda: input_box(default="sin(x)", label="f(x)"), - interval=lambda: range_slider(0, 10, 0.1, default=(0.0, 10.0), label="Range"), - a=lambda: slider(0, 10, None, 5.5, label="$a$"), + f=lambda: input_box(default='sin(x)', label="f(x)"), + interval=lambda: range_slider(0, 10, 0.1, default=(0.0, 10.0), label='Range'), + a=lambda: slider(0, 10, None, 5.5, label='$a$'), x0=lambda: slider(0, 10, None, 2.5, label="$x_0$ (start point)"), ) def difference_quotient(title, f, interval, a, x0): @@ -413,19 +413,19 @@ def difference_quotient(title, f, interval, a, x0): f_height = fmax - fmin measure_y = fmin - 0.1*f_height - measure_0 = line2d([(x0, measure_y), (a, measure_y)], rgbcolor="black") - measure_1 = line2d([(x0, measure_y + 0.02*f_height), (x0, measure_y-0.02*f_height)], rgbcolor="black") - measure_2 = line2d([(a, measure_y + 0.02*f_height), (a, measure_y-0.02*f_height)], rgbcolor="black") - text_x0 = text("x0", (x0, measure_y - 0.05*f_height), rgbcolor="black") - text_a = text("a", (a, measure_y - 0.05*f_height), rgbcolor="black") + measure_0 = line2d([(x0, measure_y), (a, measure_y)], rgbcolor='black') + measure_1 = line2d([(x0, measure_y + 0.02*f_height), (x0, measure_y-0.02*f_height)], rgbcolor='black') + measure_2 = line2d([(a, measure_y + 0.02*f_height), (a, measure_y-0.02*f_height)], rgbcolor='black') + text_x0 = text("x0", (x0, measure_y - 0.05*f_height), rgbcolor='black') + text_a = text("a", (a, measure_y - 0.05*f_height), rgbcolor='black') measure = measure_0 + measure_1 + measure_2 + text_x0 + text_a tanf = symbolic_expression((f(x0)-f(a))*(x-a)/(x0-a)+f(a)).function(x) fplot = plot(f(x), x, interval[0], interval[1]) - tanplot = plot(tanf(x), x, interval[0], interval[1], rgbcolor="#FF0000") - points = point([(x0, f(x0)), (a, f(a))], pointsize=20, rgbcolor="#005500") - dashline = line2d([(x0, f(x0)), (x0, f(a)), (a, f(a))], rgbcolor="#005500", linestyle="--") + tanplot = plot(tanf(x), x, interval[0], interval[1], rgbcolor='#FF0000') + points = point([(x0, f(x0)), (a, f(a))], pointsize=20, rgbcolor='#005500') + dashline = line2d([(x0, f(x0)), (x0, f(a)), (a, f(a))], rgbcolor='#005500', linestyle='--') html('

Difference Quotient

') show(fplot + tanplot + points + dashline + measure, xmin=interval[0], xmax=interval[1], ymin=fmin-0.2*f_height, ymax=fmax) html(r"
$\text{Line's equation:}$") @@ -497,9 +497,9 @@ def quadratic_equation(A, B, C): html(calc % (B, dis1, A, B, dis2, (2*A), sol)) @library_interact( - a0=lambda: slider(0, 360, 1, 30, label="A"), - a1=lambda: slider(0, 360, 1, 180, label="B"), - a2=lambda: slider(0, 360, 1, 300, label="C"), + a0=lambda: slider(0, 360, 1, 30, label='A'), + a1=lambda: slider(0, 360, 1, 180, label='B'), + a2=lambda: slider(0, 360, 1, 300, label='C'), ) def trigonometric_properties_triangle(a0, a1, a2): r""" @@ -563,7 +563,7 @@ def area(alpha, a, b): unit_circle = circle((0, 0), 1, aspect_ratio=1) # Triangle - triangle = line([xy[0], xy[1], xy[2], xy[0]], rgbcolor="black") + triangle = line([xy[0], xy[1], xy[2], xy[0]], rgbcolor='black') triangle_points = point(xy, pointsize=30) # Labels of the angles drawn in a distance from points @@ -612,41 +612,41 @@ def unit_circle(function, x): # Unit Circle C = circle((0, 0), 1, figsize=[5, 5], aspect_ratio=1) - C_line = line([(0, 0), (xy[0], xy[1])], rgbcolor="black") - C_point = point((xy[0], xy[1]), pointsize=40, rgbcolor="green") - C_inner = parametric_plot((cos(t), sin(t)), (t, 0, x + 0.001), color="green", thickness=3) - C_outer = parametric_plot((0.1 * cos(t), 0.1 * sin(t)), (t, 0, x + 0.001), color="black") + C_line = line([(0, 0), (xy[0], xy[1])], rgbcolor='black') + C_point = point((xy[0], xy[1]), pointsize=40, rgbcolor='green') + C_inner = parametric_plot((cos(t), sin(t)), (t, 0, x + 0.001), color='green', thickness=3) + C_outer = parametric_plot((0.1 * cos(t), 0.1 * sin(t)), (t, 0, x + 0.001), color='black') C_graph = C + C_line + C_point + C_inner + C_outer # Graphics related to the graph of the function - G_line = line([(0, 0), (x, 0)], rgbcolor="green", thickness=3) - G_point = point((x, 0), pointsize=30, rgbcolor="green") + G_line = line([(0, 0), (x, 0)], rgbcolor='green', thickness=3) + G_point = point((x, 0), pointsize=30, rgbcolor='green') G_graph = G_line + G_point # Sine if function == 0: Gf = plot(sin(t), t, 0, 2*pi, axes_labels=("x", "sin(x)")) - Gf_point = point((x, sin(x)), pointsize=30, rgbcolor="red") - Gf_line = line([(x, 0),(x, sin(x))], rgbcolor="red") - Cf_point = point((0, xy[1]), pointsize=40, rgbcolor="red") - Cf_line1 = line([(0, 0), (0, xy[1])], rgbcolor="red", thickness=3) - Cf_line2 = line([(0, xy[1]), (xy[0], xy[1])], rgbcolor="purple", linestyle="--") + Gf_point = point((x, sin(x)), pointsize=30, rgbcolor='red') + Gf_line = line([(x, 0),(x, sin(x))], rgbcolor='red') + Cf_point = point((0, xy[1]), pointsize=40, rgbcolor='red') + Cf_line1 = line([(0, 0), (0, xy[1])], rgbcolor='red', thickness=3) + Cf_line2 = line([(0, xy[1]), (xy[0], xy[1])], rgbcolor='purple', linestyle='--') # Cosine elif function == 1: Gf = plot(cos(t), t, 0, 2*pi, axes_labels=("x", "cos(x)")) - Gf_point = point((x, cos(x)), pointsize=30, rgbcolor="red") - Gf_line = line([(x, 0), (x, cos(x))], rgbcolor="red") - Cf_point = point((xy[0], 0), pointsize=40, rgbcolor="red") - Cf_line1 = line([(0, 0), (xy[0], 0)], rgbcolor="red", thickness=3) - Cf_line2 = line([(xy[0], 0), (xy[0], xy[1])], rgbcolor="purple", linestyle="--") + Gf_point = point((x, cos(x)), pointsize=30, rgbcolor='red') + Gf_line = line([(x, 0), (x, cos(x))], rgbcolor='red') + Cf_point = point((xy[0], 0), pointsize=40, rgbcolor='red') + Cf_line1 = line([(0, 0), (xy[0], 0)], rgbcolor='red', thickness=3) + Cf_line2 = line([(xy[0], 0), (xy[0], xy[1])], rgbcolor='purple', linestyle='--') # Tangent else: Gf = plot(tan(t), t, 0, 2*pi, ymin=-8, ymax=8, axes_labels=("x", "tan(x)")) - Gf_point = point((x, tan(x)), pointsize=30, rgbcolor="red") - Gf_line = line([(x, 0), (x, tan(x))], rgbcolor="red") - Cf_point = point((1, tan(x)), pointsize=40, rgbcolor="red") - Cf_line1 = line([(1, 0), (1, tan(x))], rgbcolor="red", thickness=3) - Cf_line2 = line([(xy[0], xy[1]), (1, tan(x))], rgbcolor="purple", linestyle="--") + Gf_point = point((x, tan(x)), pointsize=30, rgbcolor='red') + Gf_line = line([(x, 0), (x, tan(x))], rgbcolor='red') + Cf_point = point((1, tan(x)), pointsize=40, rgbcolor='red') + Cf_line1 = line([(1, 0), (1, tan(x))], rgbcolor='red', thickness=3) + Cf_line2 = line([(xy[0], xy[1]), (1, tan(x))], rgbcolor='purple', linestyle='--') C_graph += Cf_point + Cf_line1 + Cf_line2 G_graph += Gf + Gf_point + Gf_line @@ -656,14 +656,14 @@ def unit_circle(function, x): @library_interact( title=lambda: text_control("

Special points in triangle

"), - a0=lambda: slider(0, 360, 1, 30, label="A"), - a1=lambda: slider(0, 360, 1, 180, label="B"), - a2=lambda: slider(0, 360, 1, 300, label="C"), - show_median=lambda: checkbox(False, label="Medians"), + a0=lambda: slider(0, 360, 1, 30, label='A'), + a1=lambda: slider(0, 360, 1, 180, label='B'), + a2=lambda: slider(0, 360, 1, 300, label='C'), + show_median=lambda: checkbox(False, label='Medians'), show_pb=lambda: checkbox(False, label="Perpendicular Bisectors"), - show_alt=lambda: checkbox(False, label="Altitudes"), + show_alt=lambda: checkbox(False, label='Altitudes'), show_ab=lambda: checkbox(False, label="Angle Bisectors"), - show_incircle=lambda: checkbox(False, label="Incircle"), + show_incircle=lambda: checkbox(False, label='Incircle'), show_euler=lambda: checkbox(False, label="Euler's Line"), ) def special_points( @@ -749,7 +749,7 @@ def line_to_points(x1_y1, x2_y2, **plot_kwargs): C = circle((0, 0), 1, aspect_ratio=1) # Triangle - triangle = line([xy[0], xy[1], xy[2], xy[0]], rgbcolor="black") + triangle = line([xy[0], xy[1], xy[2], xy[0]], rgbcolor='black') triangle_points = point(xy, pointsize=30) # Side lengths (bc, ca, ab) corresponding to triangle vertices (a, b, c) @@ -778,34 +778,34 @@ def line_to_points(x1_y1, x2_y2, **plot_kwargs): # Angle Bisectors if show_ab: - a_ab = line([xy[0], half(a, 1, 2, 0)], rgbcolor="blue", alpha=0.6) - b_ab = line([xy[1], half(a, 2, 0, 1)], rgbcolor="blue", alpha=0.6) - c_ab = line([xy[2], half(a, 0, 1, 2)], rgbcolor="blue", alpha=0.6) - ab_point = point(incircle_center, rgbcolor="blue", pointsize=28) + a_ab = line([xy[0], half(a, 1, 2, 0)], rgbcolor='blue', alpha=0.6) + b_ab = line([xy[1], half(a, 2, 0, 1)], rgbcolor='blue', alpha=0.6) + c_ab = line([xy[2], half(a, 0, 1, 2)], rgbcolor='blue', alpha=0.6) + ab_point = point(incircle_center, rgbcolor='blue', pointsize=28) ab_graph = a_ab + b_ab + c_ab + ab_point else: ab_graph = Graphics() # Medians if show_median: - a_median = line([xy[0], a_middle[0]], rgbcolor="green", alpha=0.6) - b_median = line([xy[1], a_middle[1]], rgbcolor="green", alpha=0.6) - c_median = line([xy[2], a_middle[2]], rgbcolor="green", alpha=0.6) + a_median = line([xy[0], a_middle[0]], rgbcolor='green', alpha=0.6) + b_median = line([xy[1], a_middle[1]], rgbcolor='green', alpha=0.6) + c_median = line([xy[2], a_middle[2]], rgbcolor='green', alpha=0.6) median_point = point( ( (xy[0][0]+xy[1][0]+xy[2][0])/3.0, (xy[0][1]+xy[1][1]+xy[2][1])/3.0 - ), rgbcolor="green", pointsize=28) + ), rgbcolor='green', pointsize=28) median_graph = a_median + b_median + c_median + median_point else: median_graph = Graphics() # Perpendicular Bisectors if show_pb: - a_pb = line_to_points(a_middle[0], half(a, 1, 2, 0), rgbcolor="red", alpha=0.6) - b_pb = line_to_points(a_middle[1], half(a, 2, 0, 1), rgbcolor="red", alpha=0.6) - c_pb = line_to_points(a_middle[2], half(a, 0, 1, 2), rgbcolor="red", alpha=0.6) - pb_point = point((0, 0), rgbcolor="red", pointsize=28) + a_pb = line_to_points(a_middle[0], half(a, 1, 2, 0), rgbcolor='red', alpha=0.6) + b_pb = line_to_points(a_middle[1], half(a, 2, 0, 1), rgbcolor='red', alpha=0.6) + c_pb = line_to_points(a_middle[2], half(a, 0, 1, 2), rgbcolor='red', alpha=0.6) + pb_point = point((0, 0), rgbcolor='red', pointsize=28) pb_graph = a_pb + b_pb + c_pb + pb_point else: pb_graph = Graphics() @@ -814,12 +814,12 @@ def line_to_points(x1_y1, x2_y2, **plot_kwargs): if show_alt: xA, xB, xC = xy[0][0], xy[1][0], xy[2][0] yA, yB, yC = xy[0][1], xy[1][1], xy[2][1] - a_alt = plot(((xC-xB)*x+(xB-xC)*xA)/(yB-yC)+yA, (x,-3,3), rgbcolor="brown", alpha=0.6) - b_alt = plot(((xA-xC)*x+(xC-xA)*xB)/(yC-yA)+yB, (x,-3,3), rgbcolor="brown", alpha=0.6) - c_alt = plot(((xB-xA)*x+(xA-xB)*xC)/(yA-yB)+yC, (x,-3,3), rgbcolor="brown", alpha=0.6) + a_alt = plot(((xC-xB)*x+(xB-xC)*xA)/(yB-yC)+yA, (x,-3,3), rgbcolor='brown', alpha=0.6) + b_alt = plot(((xA-xC)*x+(xC-xA)*xB)/(yC-yA)+yB, (x,-3,3), rgbcolor='brown', alpha=0.6) + c_alt = plot(((xB-xA)*x+(xA-xB)*xC)/(yA-yB)+yC, (x,-3,3), rgbcolor='brown', alpha=0.6) alt_lx = (xA*xB*(yA-yB)+xB*xC*(yB-yC)+xC*xA*(yC-yA)-(yA-yB)*(yB-yC)*(yC-yA))/(xC*yB-xB*yC+xA*yC-xC*yA+xB*yA-xA*yB) alt_ly = (yA*yB*(xA-xB)+yB*yC*(xB-xC)+yC*yA*(xC-xA)-(xA-xB)*(xB-xC)*(xC-xA))/(yC*xB-yB*xC+yA*xC-yC*xA+yB*xA-yA*xB) - alt_intersection = point((alt_lx, alt_ly), rgbcolor="brown", pointsize=28) + alt_intersection = point((alt_lx, alt_ly), rgbcolor='brown', pointsize=28) alt_graph = a_alt + b_alt + c_alt + alt_intersection else: alt_graph = Graphics() @@ -832,7 +832,7 @@ def line_to_points(x1_y1, x2_y2, **plot_kwargs): (xy[0][0]+xy[1][0]+xy[2][0])/3.0, (xy[0][1]+xy[1][1]+xy[2][1])/3.0 ), - rgbcolor="purple", + rgbcolor='purple', thickness=2, alpha=0.7 ) @@ -892,7 +892,7 @@ def coin(n, interval): @library_interact( title=lambda: text_control("

Bisection method

"), f=lambda: input_box("x^2-2", label="f(x)"), - interval=lambda: range_slider(-5, 5, default=(0, 4), label="range"), + interval=lambda: range_slider(-5, 5, default=(0, 4), label='range'), d=lambda: slider(1, 8, 1, 3, label="$10^{-d}$ precision"), maxn=lambda: slider(0, 50, 1, 10, label="max iterations"), ) @@ -971,7 +971,7 @@ def _bisection_method(f, a, b, maxn, eps): @library_interact( title=lambda: text_control("

Secant method for numerical root finding

"), f=lambda: input_box("x^2-2", label="f(x)"), - interval=lambda: range_slider(-5, 5, default=(0, 4), label="range"), + interval=lambda: range_slider(-5, 5, default=(0, 4), label='range'), d=lambda: slider(1, 16, 1, 3, label="10^-d precision"), maxn=lambda: slider(0, 15, 1, 10, label="max iterations"), ) @@ -1033,7 +1033,7 @@ def _secant_method(f, a, b, maxn, h): L = sum(line([(c,k*i), (d,k*i)]) for i, (c,d) in enumerate(intervals) ) L += sum(line([(c,k*i-k/4), (c,k*i+k/4)]) for i, (c,d) in enumerate(intervals) ) L += sum(line([(d,k*i-k/4), (d,k*i+k/4)]) for i, (c,d) in enumerate(intervals) ) - S = sum(line([(c,f(c)), (d,f(d)), (d-(d-c)*f(d)/(f(d)-f(c)), 0)], color="green") for (c, d) in intervals) + S = sum(line([(c,f(c)), (d,f(d)), (d-(d-c)*f(d)/(f(d)-f(c)), 0)], color='green') for (c, d) in intervals) show(P + L + S, xmin=a, xmax=b) @@ -1043,7 +1043,7 @@ def _secant_method(f, a, b, maxn, h): c=lambda: slider(-10, 10, default=6, label="Start ($x$)"), d=lambda: slider(1, 16, 1, 3, label="$10^{-d}$ precision"), maxn=lambda: slider(0, 15, 1, 10, label="max iterations"), - interval=lambda: range_slider(-10, 10, default=(0, 6), label="Interval"), + interval=lambda: range_slider(-10, 10, default=(0, 6), label='Interval'), list_steps=lambda: checkbox(default=False, label="List steps"), ) def newton_method(title, f, c, d, maxn, interval, list_steps): @@ -1059,7 +1059,7 @@ def newton_method(title, f, c, d, maxn, interval, list_steps): - ``d`` -- slider for the precision (`10^{-d}`) - ``maxn`` -- max number of iterations - ``interval`` -- range slider for the search interval - - ``list_steps`` -- checkbox, if true shows the steps numerically + - ``list_steps`` -- checkbox, if ``True`` shows the steps numerically EXAMPLES: @@ -1104,10 +1104,10 @@ def _newton_method(f, c, maxn, h): s.append([i+1, c, f(c), (c-h)*f(c+h)]) pretty_print(table(s, header_row=True)) else: - P = plot(f, x, interval, color="blue") - L = sum(line([(c, 0), (c, f(c))], color="green") for c in midpoints[:-1]) + P = plot(f, x, interval, color='blue') + L = sum(line([(c, 0), (c, f(c))], color='green') for c in midpoints[:-1]) for i in range(len(midpoints) - 1): - L += line([(midpoints[i], f(midpoints[i])), (midpoints[i+1], 0)], color="red") + L += line([(midpoints[i], f(midpoints[i])), (midpoints[i+1], 0)], color='red') show(P + L, xmin=interval[0], xmax=interval[1], ymin=P.ymin(), ymax=P.ymax()) @@ -1240,7 +1240,7 @@ def trapezoid_integration( @library_interact( title=lambda: text_control("

Simpson integration

"), - f=lambda: input_box(default="x*sin(x)+x+1", label="$f(x)=$"), + f=lambda: input_box(default='x*sin(x)+x+1', label="$f(x)=$"), n=lambda: slider(2, 100, 2, 6, label="# divisions"), interval_input=lambda: selector( ["from slider", "from keyboard"], @@ -1321,11 +1321,11 @@ def parabola(a, b, c): for i in range(0, n-1, 2): p = parabola((xs[i],ys[i]),(xs[i+1],ys[i+1]),(xs[i+2],ys[i+2])) - parabolas += plot(p(x=x), (x, xs[i], xs[i+2]), color="red") - lines += line([(xs[i],ys[i]), (xs[i],0), (xs[i+2],0)],color="red") - lines += line([(xs[i+1],ys[i+1]), (xs[i+1],0)], linestyle="-.", color="red") + parabolas += plot(p(x=x), (x, xs[i], xs[i+2]), color='red') + lines += line([(xs[i],ys[i]), (xs[i],0), (xs[i+2],0)],color='red') + lines += line([(xs[i+1],ys[i+1]), (xs[i+1],0)], linestyle='-.', color='red') - lines += line([(xs[-1],ys[-1]), (xs[-1],0)], color="red") + lines += line([(xs[-1],ys[-1]), (xs[-1],0)], color='red') html(r'Function $f(x)=%s$' % latex(f(x))) @@ -1393,7 +1393,7 @@ def parabola(a, b, c): @library_interact( title=lambda: text_control("

Riemann integral with random sampling

"), - f=lambda: input_box("x^2+1", label="$f(x)=$", width=40), + f=lambda: input_box("x^2+1", label='$f(x)=$', width=40), n=lambda: slider(1, 30, 1, 5, label="# divisions"), hr1=lambda: text_control("
"), interval_input=lambda: selector( @@ -1420,7 +1420,7 @@ def riemann_sum( auto_update=False, ): r""" - Interact explaining the definition of Riemann integral + Interact explaining the definition of Riemann integral. INPUT: @@ -1500,7 +1500,7 @@ def riemann_sum( @library_interact( f=lambda: sin(x), g=lambda: cos(x), - xrange=lambda: range_slider(-3, 3, default=(0, 1), label="x-range"), + xrange=lambda: range_slider(-3, 3, default=(0, 1), label='x-range'), yrange=lambda: "auto", a=lambda: 1, action=lambda: selector( @@ -1544,7 +1544,7 @@ def function_tool(f, g, xrange, yrange, a, action, do_plot): - ``yrange`` -- range for plotting ('auto' is default, otherwise a tuple) - ``a`` -- factor ``a`` - ``action`` -- select given operation on or combination of functions - - ``do_plot`` -- if true, a plot is drawn + - ``do_plot`` -- if ``True``, a plot is drawn EXAMPLES: @@ -1658,7 +1658,7 @@ def function_tool(f, g, xrange, yrange, a, action, do_plot): zoom_x=lambda: range_slider(-2, 2, 0.01, (-1.5, 1.5), label="Zoom X"), zoom_y=lambda: range_slider(-2, 2, 0.01, (-1.5, 1.5), label="Zoom Y"), plot_points=lambda: slider(20, 400, 20, default=150, label="plot points"), - dpi=lambda: slider(20, 200, 10, default=80, label="dpi"), + dpi=lambda: slider(20, 200, 10, default=80, label='dpi'), ) def julia(expo, c_real, c_imag, iterations, zoom_x, zoom_y, plot_points, dpi): r""" @@ -1712,7 +1712,7 @@ def julia(expo, c_real, c_imag, iterations, zoom_x, zoom_y, plot_points, dpi): zoom_x=lambda: range_slider(-2, 2, 0.01, (-2, 1), label="Zoom X"), zoom_y=lambda: range_slider(-2, 2, 0.01, (-1.5, 1.5), label="Zoom Y"), plot_points=lambda: slider(20, 400, 20, default=150, label="plot points"), - dpi=lambda: slider(20, 200, 10, default=80, label="dpi"), + dpi=lambda: slider(20, 200, 10, default=80, label='dpi'), ) def mandelbrot(expo, iterations, zoom_x, zoom_y, plot_points, dpi): r""" @@ -1809,12 +1809,12 @@ def cellular_automaton(N, rule_number, size): @library_interact( - interval=lambda: range_slider(1, 4000, 10, default=(1, 1000), label="range"), + interval=lambda: range_slider(1, 4000, 10, default=(1, 1000), label='range'), show_factors=lambda: True, highlight_primes=lambda: True, show_curves=lambda: True, n=lambda: slider(1, 200, 1, default=89, label="number $n$"), - dpi=lambda: slider(10, 300, 10, default=100, label="dpi"), + dpi=lambda: slider(10, 300, 10, default=100, label='dpi'), ) def polar_prime_spiral(interval, show_factors, highlight_primes, show_curves, n, dpi): r""" @@ -1826,9 +1826,9 @@ def polar_prime_spiral(interval, show_factors, highlight_primes, show_curves, n, INPUT: - ``interval`` -- range slider to specify start and end - - ``show_factors`` -- if true, show factors - - ``highlight_primes`` -- if true, prime numbers are highlighted - - ``show_curves`` -- if true, curves are plotted + - ``show_factors`` -- if ``True``, show factors + - ``highlight_primes`` -- if ``True``, prime numbers are highlighted + - ``show_curves`` -- if ``True``, curves are plotted - ``n`` -- number `n` - ``dpi`` -- dots per inch resolution for plotting diff --git a/src/sage/interacts/library_cython.pyx b/src/sage/interacts/library_cython.pyx index 6647629d44c..52c68dd5922 100644 --- a/src/sage/interacts/library_cython.pyx +++ b/src/sage/interacts/library_cython.pyx @@ -62,7 +62,6 @@ cpdef mandel(ff_m, z, int iterations): sage: ff_m = fast_callable(f, vars=[z,c], domain=CDF) sage: mandel(ff_m, CDF(1,1), 3) 1.0 + 3.0*I - """ c = z for i in range(iterations): diff --git a/src/sage/interfaces/axiom.py b/src/sage/interfaces/axiom.py index 1a707eb1d16..461d8a342bd 100644 --- a/src/sage/interfaces/axiom.py +++ b/src/sage/interfaces/axiom.py @@ -25,7 +25,7 @@ - Bill Page (2006-10): Created this (based on Maxima interface) - .. note:: + .. NOTE:: Bill Page put a huge amount of effort into the Sage Axiom interface over several days during the Sage Days 2 coding @@ -35,7 +35,7 @@ - Bill Page (2007-08): Minor modifications to support axiom4sage-0.3 -.. note:: +.. NOTE:: The axiom4sage-0.3.spkg is based on an experimental version of the FriCAS fork of the Axiom project by Waldek Hebisch that uses @@ -43,7 +43,7 @@ clisp. If the string "error" (case insensitive) occurs in the output of -anything from axiom, a :class:`RuntimeError` exception is raised. +anything from axiom, a :exc:`RuntimeError` exception is raised. EXAMPLES: We evaluate a very simple expression in axiom. @@ -279,7 +279,7 @@ def _read_in_file_command(self, filename): def _quit_string(self): """ - Returns the string used to quit Axiom. + Return the string used to quit Axiom. EXAMPLES:: @@ -299,7 +299,7 @@ def _quit_string(self): def _commands(self): """ - Returns a list of commands available. This is done by parsing the + Return a list of commands available. This is done by parsing the result of the first section of the output of ')what things'. EXAMPLES:: @@ -322,7 +322,7 @@ def _commands(self): def _tab_completion(self, verbose=True, use_disk_cache=True): """ - Returns a list of all the commands defined in Axiom and optionally + Return a list of all the commands defined in Axiom and optionally (per default) store them to disk. EXAMPLES:: @@ -383,7 +383,6 @@ def set(self, var, value): sage: axiom.set('xx', '2') #optional - axiom sage: axiom.get('xx') #optional - axiom '2' - """ cmd = '%s := %s' % (var, value) out = self._eval_line(cmd, reformat=False) @@ -525,7 +524,7 @@ def _object_class(self): def _function_element_class(self): """ - Returns the Axiom function element class. + Return the Axiom function element class. EXAMPLES:: @@ -615,7 +614,7 @@ def _richcmp_(self, other, op): def type(self): """ - Returns the type of an AxiomElement. + Return the type of an AxiomElement. EXAMPLES:: @@ -644,9 +643,9 @@ def __len__(self): def __getitem__(self, n): r""" - Return the n-th element of this list. + Return the `n`-th element of this list. - .. note:: + .. NOTE:: Lists are 1-based. @@ -677,7 +676,7 @@ def __getitem__(self, n): def comma(self, *args): """ - Returns a Axiom tuple from self and args. + Return an Axiom tuple from ``self`` and ``args``. EXAMPLES:: @@ -724,7 +723,7 @@ def _latex_(self): def as_type(self, type): """ - Returns self as type. + Return ``self`` as type. EXAMPLES:: @@ -734,7 +733,6 @@ def as_type(self, type): 1.2 sage: _.type() #optional - axiom DoubleFloat - """ P = self._check_valid() type = P(type) @@ -752,7 +750,6 @@ def unparsed_input_form(self): x + 1 sage: a.unparsed_input_form() #optional - axiom 'x*x+1' - """ P = self._check_valid() s = P.eval('unparse(%s::InputForm)' % self._name) @@ -768,7 +765,7 @@ def unparsed_input_form(self): def _sage_(self): """ - Convert self to a Sage object. + Convert ``self`` to a Sage object. EXAMPLES:: @@ -824,8 +821,6 @@ def _sage_(self): y^2 + x^2 + 1/2 sage: _.parent() Multivariate Polynomial Ring in y, x over Rational Field - - """ P = self._check_valid() type = str(self.type()) @@ -949,7 +944,7 @@ def __init__(self, parent, name): def is_AxiomElement(x): """ - Return True if ``x`` is of type :class:`AxiomElement`. + Return ``True`` if ``x`` is of type :class:`AxiomElement`. EXAMPLES:: @@ -973,7 +968,7 @@ def is_AxiomElement(x): def reduce_load_Axiom(): """ - Returns the Axiom interface object defined in + Return the Axiom interface object defined in sage.interfaces.axiom. EXAMPLES:: @@ -1000,7 +995,6 @@ def axiom_console(): Issue )summary for a summary of useful system commands. Issue )quit to leave AXIOM and return to shell. ----------------------------------------------------------------------------- - """ from sage.repl.rich_output.display_manager import get_display_manager if not get_display_manager().is_in_terminal(): diff --git a/src/sage/interfaces/ecm.py b/src/sage/interfaces/ecm.py index 1d887064a76..5454cb868c7 100644 --- a/src/sage/interfaces/ecm.py +++ b/src/sage/interfaces/ecm.py @@ -68,116 +68,116 @@ def __init__(self, B1=10, B2=None, **kwds): INPUT: - - ``B1`` -- integer. Stage 1 bound + - ``B1`` -- integer; Stage 1 bound - - ``B2`` -- integer. Stage 2 bound (or interval B2min-B2max) + - ``B2`` -- integer; Stage 2 bound (or interval B2min-B2max) In addition the following keyword arguments can be used: - - ``x0`` -- integer `x`. use `x` as initial point + - ``x0`` -- integer `x`; use `x` as initial point - - ``sigma`` -- integer `s`. Use s as curve generator [ecm] + - ``sigma`` -- integer `s`; use s as curve generator [ecm] - - ``A`` -- integer `a`. Use a as curve parameter [ecm] + - ``A`` -- integer `a`; use a as curve parameter [ecm] - - ``k`` -- integer `n`. Perform `>= n` steps in stage 2 + - ``k`` -- integer `n`; perform `>= n` steps in stage 2 - - ``power`` -- integer `n`. Use `x^n` for Brent-Suyama's + - ``power`` -- integer `n`; use `x^n` for Brent-Suyama's extension - - ``dickson`` -- integer `n`. Use `n`-th Dickson's polynomial + - ``dickson`` -- integer `n`; use `n`-th Dickson's polynomial for Brent-Suyama's extension - - ``c`` -- integer `n`. Perform `n` runs for each input + - ``c`` -- integer `n`; perform `n` runs for each input - - ``pm1`` -- boolean. perform P-1 instead of ECM + - ``pm1`` -- boolean; perform P-1 instead of ECM - - ``pp1`` -- boolean. perform P+1 instead of ECM + - ``pp1`` -- boolean; perform P+1 instead of ECM - - ``q`` -- boolean. quiet mode + - ``q`` -- boolean; quiet mode - - ``v`` -- boolean. verbose mode + - ``v`` -- boolean; verbose mode - - ``timestamp`` -- boolean. print a time stamp with each number + - ``timestamp`` -- boolean; print a time stamp with each number - - ``mpzmod`` -- boolean. use GMP's mpz_mod for mod reduction + - ``mpzmod`` -- boolean; use GMP's mpz_mod for mod reduction - - ``modmuln`` -- boolean. use Montgomery's MODMULN for mod reduction + - ``modmuln`` -- boolean; use Montgomery's MODMULN for mod reduction - - ``redc`` -- boolean. use Montgomery's REDC for mod reduction + - ``redc`` -- boolean; use Montgomery's REDC for mod reduction - - ``nobase2`` -- boolean. Disable special base-2 code + - ``nobase2`` -- boolean; disable special base-2 code - - ``base2`` -- integer `n`. Force base 2 mode with 2^n+1 (n>0) + - ``base2`` -- integer `n`; force base 2 mode with 2^n+1 (n>0) or 2^n-1 (n<0) - - ``save`` -- string filename. Save residues at end of stage 1 + - ``save`` -- string filename; save residues at end of stage 1 to file - - ``savea`` -- string filename. Like -save, appends to + - ``savea`` -- string filename; Like -save, appends to existing files - - ``resume`` -- string filename. Resume residues from file, + - ``resume`` -- string filename; resume residues from file, reads from stdin if file is "-" - - ``primetest`` -- boolean. Perform a primality test on input + - ``primetest`` -- boolean; perform a primality test on input - - ``treefile`` -- string. Store product tree of F in files f.0 + - ``treefile`` -- string; store product tree of F in files f.0 f.1 ... - - ``i`` -- integer. increment B1 by this constant on each run + - ``i`` -- integer; increment B1 by this constant on each run - - ``I`` -- integer `f`. auto-calculated increment for B1 - multiplied by `f` scale factor. + - ``I`` -- integer `f`; auto-calculated increment for B1 + multiplied by `f` scale factor - - ``inp`` -- string. Use file as input (instead of redirecting + - ``inp`` -- string; use file as input (instead of redirecting stdin) - - ``b`` -- boolean. Use breadth-first mode of file processing + - ``b`` -- boolean; use breadth-first mode of file processing - - ``d`` -- boolean. Use depth-first mode of file processing + - ``d`` -- boolean; use depth-first mode of file processing (default) - - ``one`` -- boolean. Stop processing a candidate if a factor + - ``one`` -- boolean; stop processing a candidate if a factor is found (looping mode ) - - ``n`` -- boolean. Run ecm in 'nice' mode (below normal + - ``n`` -- boolean; run ecm in 'nice' mode (below normal priority) - - ``nn`` -- boolean. Run ecm in 'very nice' mode (idle + - ``nn`` -- boolean; run ecm in 'very nice' mode (idle priority) - - ``t`` -- integer `n`. Trial divide candidates before P-1, - P+1 or ECM up to `n`. + - ``t`` -- integer `n`; trial divide candidates before P-1, + P+1 or ECM up to `n` - - ``ve`` -- integer `n`. Verbosely show short (`< n` + - ``ve`` -- integer `n`; verbosely show short (`< n` character) expressions on each loop - - ``B2scale`` -- integer. Multiplies the default B2 value + - ``B2scale`` -- integer; multiplies the default B2 value - - ``go`` -- integer. Preload with group order val, which can + - ``go`` -- integer; preload with group order val, which can be a simple expression, or can use N as a placeholder for - the number being factored. + the number being factored - - ``prp`` -- string. use shell command cmd to do large + - ``prp`` -- string; use shell command cmd to do large primality tests - - ``prplen`` -- integer. only candidates longer than this + - ``prplen`` -- integer; only candidates longer than this number of digits are 'large' - - ``prpval`` -- integer. value>=0 which indicates the prp - command foundnumber to be PRP. + - ``prpval`` -- integer; value>=0 which indicates the prp + command foundnumber to be PRP - - ``prptmp`` -- file. outputs n value to temp file prior to + - ``prptmp`` -- file; outputs n value to temp file prior to running (NB. gets deleted) - - ``prplog`` -- file. otherwise get PRP results from this file + - ``prplog`` -- file; otherwise get PRP results from this file (NB. gets deleted) - - ``prpyes`` -- string. Literal string found in prplog file + - ``prpyes`` -- string; literal string found in prplog file when number is PRP - - ``prpno`` -- string. Literal string found in prplog file + - ``prpno`` -- string; literal string found in prplog file when number is composite """ self._cmd = self._make_cmd(B1, B2, kwds) @@ -203,14 +203,12 @@ def _run_ecm(self, cmd, n): INPUT: - - ``cmd`` -- list of strings. The command. + - ``cmd`` -- list of strings; the command - - ``n`` -- integer suitable for ECM. No argument checking is - performed. + - ``n`` -- integer suitable for ECM; no argument checking is + performed - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -233,11 +231,9 @@ def __call__(self, n): INPUT: - - ``n`` -- integer. - - OUTPUT: + - ``n`` -- integer - String. The ECM output. + OUTPUT: string; the ECM output EXAMPLES:: @@ -283,13 +279,11 @@ def _B1_table_value(self, factor_digits, min=15, max=70): INPUT: - - ``factor_digits`` -- integer. Number of digits. + - ``factor_digits`` -- integer; number of digits - - ``min``, ``max`` -- integer. Min and max values. + - ``min``, ``max`` -- integer; min and max values - OUTPUT: - - Integer. A key in _recommended_B1_list. + OUTPUT: integer; a key in ``_recommended_B1_list`` EXAMPLES:: @@ -309,7 +303,7 @@ def recommended_B1(self, factor_digits): INPUT: - - ``factor_digits`` -- integer. Number of digits. + - ``factor_digits`` -- integer; number of digits OUTPUT: @@ -340,9 +334,9 @@ def _parse_output(self, n, out): INPUT: - - ``n`` -- integer. The ECM input number. + - ``n`` -- integer; the ECM input number - - ``out`` -- string. The stdout from the ECM invocation. + - ``out`` -- string; the stdout from the ECM invocation OUTPUT: @@ -420,7 +414,7 @@ def _parse_output(self, n, out): return result raise ValueError('failed to parse ECM output') - def one_curve(self, n, factor_digits=None, B1=2000, algorithm="ECM", **kwds): + def one_curve(self, n, factor_digits=None, B1=2000, algorithm='ECM', **kwds): """ Run one single ECM (or P-1/P+1) curve on input n. @@ -430,18 +424,18 @@ def one_curve(self, n, factor_digits=None, B1=2000, algorithm="ECM", **kwds): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``factor_digits`` -- integer. Decimal digits estimate of the - wanted factor. + - ``factor_digits`` -- integer; decimal digits estimate of the + wanted factor - - ``B1`` -- integer. Stage 1 bound (default 2000) + - ``B1`` -- integer; Stage 1 bound (default: 2000) - - ``algorithm`` -- either "ECM" (default), "P-1" or "P+1" + - ``algorithm`` -- either "ECM" (default); "P-1" or "P+1" OUTPUT: - a list ``[p, q]`` where p and q are integers and n = p * q. + A list ``[p, q]`` where p and q are integers and n = p * q. If no factor was found, then p = 1 and q = n. .. WARNING:: @@ -457,10 +451,10 @@ def one_curve(self, n, factor_digits=None, B1=2000, algorithm="ECM", **kwds): sage: f.one_curve(n, B1=10000, sigma=1022170541) [79792266297612017, 6366805760909027985741435139224233] sage: n = 432132887883903108009802143314445113500016816977037257 - sage: f.one_curve(n, B1=500000, algorithm="P-1") + sage: f.one_curve(n, B1=500000, algorithm='P-1') [67872792749091946529, 6366805760909027985741435139224233] sage: n = 2088352670731726262548647919416588631875815083 - sage: f.one_curve(n, B1=2000, algorithm="P+1", x0=5) + sage: f.one_curve(n, B1=2000, algorithm='P+1', x0=5) [328006342451, 6366805760909027985741435139224233] """ n = self._validate(n) @@ -525,15 +519,15 @@ def find_factor(self, n, factor_digits=None, B1=2000, **kwds): INPUT: - - ``n`` -- a positive integer, + - ``n`` -- positive integer - - ``factor_digits`` -- integer or ``None`` (default). Decimal - digits estimate of the wanted factor. + - ``factor_digits`` -- integer or ``None`` (default); decimal + digits estimate of the wanted factor - - ``B1`` -- integer. Stage 1 bound (default 2000). This is - used as bound if ``factor_digits`` is not specified. + - ``B1`` -- integer; Stage 1 bound (default: 2000). This is + used as bound if ``factor_digits`` is not specified - - ``kwds`` -- optional keyword parameters. + - ``kwds`` -- optional keyword parameters OUTPUT: @@ -586,23 +580,21 @@ def factor(self, n, factor_digits=None, B1=2000, proof=False, **kwds): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - - ``factor_digits`` -- integer or ``None`` (default). Optional - guess at how many digits are in the smallest factor. + - ``factor_digits`` -- integer or ``None`` (default); optional + guess at how many digits are in the smallest factor - ``B1`` -- initial lower bound, defaults to 2000 (15 digit - factors). Used if ``factor_digits`` is not specified. + factors); used if ``factor_digits`` is not specified - - ``proof`` -- boolean (default: ``False``). Whether to prove - that the factors are prime. + - ``proof`` -- boolean (default: ``False``); whether to prove + that the factors are prime - - ``kwds`` -- keyword arguments to pass to ecm-gmp. See help - for :class:`ECM` for more details. - - OUTPUT: + - ``kwds`` -- keyword arguments to pass to ecm-gmp; see help + for :class:`ECM` for more details - A list of integers whose product is n. + OUTPUT: list of integers whose product is `n` .. NOTE:: @@ -696,7 +688,7 @@ def time(self, n, factor_digits, verbose=False): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``factor_digits`` -- the (estimated) number of digits of the smallest factor @@ -791,14 +783,13 @@ def _validate(self, n): INPUT: - - ``n`` -- integer. + - ``n`` -- integer OUTPUT: - The integer as a Sage integer. This function raises a - ValueError if the two conditions listed above are not both - satisfied. It is here because GMP-ECM silently ignores all - digits of input after the 4095th! + The integer as a Sage integer. This function raises a :exc:`ValueError` + if the two conditions listed above are not both satisfied. It is here + because GMP-ECM silently ignores all digits of input after the 4095th! EXAMPLES:: diff --git a/src/sage/interfaces/expect.py b/src/sage/interfaces/expect.py index 2e16fd3b2e4..dddebf0d1df 100644 --- a/src/sage/interfaces/expect.py +++ b/src/sage/interfaces/expect.py @@ -180,11 +180,11 @@ def set_server_and_command(self, server=None, command=None, server_tmpdir=None, """ Changes the server and the command to use for this interface. - This raises a :class:`RuntimeError` if the interface is already started. + This raises a :exc:`RuntimeError` if the interface is already started. INPUT: - - ``server`` -- string or ``None`` (default); name of a remote host to connect to using ``ssh``. + - ``server`` -- string or ``None`` (default); name of a remote host to connect to using ``ssh`` - ``command`` -- one of: @@ -295,7 +295,7 @@ def _send(self, cmd): def is_running(self): """ - Return True if self is currently running. + Return ``True`` if ``self`` is currently running. """ if self._expect is None: return False @@ -374,7 +374,6 @@ def pid(self): sage: gap.quit() sage: pid == gap.pid() False - """ if self._expect is None: self._start() @@ -448,7 +447,7 @@ def _install_hints_ssh_through_gate(self): their own way. If this all works, you can then make calls like: - math = Mathematica(server="remote_for_sage") + math = Mathematica(server='remote_for_sage') """ def _do_cleaner(self): @@ -635,8 +634,8 @@ def quit(self, verbose=False): INPUT: - - ``verbose`` -- (boolean, default ``False``) print a message - when quitting this process? + - ``verbose`` -- boolean (default: ``False``); whether to print a + message when quitting the process EXAMPLES:: @@ -712,7 +711,7 @@ def _send_interrupt(self): def _local_tmpfile(self): """ - Return a filename that is used to buffer long command lines for this interface + Return a filename that is used to buffer long command lines for this interface. INPUT: @@ -768,7 +767,7 @@ def _local_tmpfile(self): # FriCAS uses the ".input" suffix, and the other # interfaces are suffix-agnostic, so using ".input" here # lets us avoid a subclass override for FriCAS. - with NamedTemporaryFile(suffix=".input", delete=False) as f: + with NamedTemporaryFile(suffix='.input', delete=False) as f: self.__local_tmpfile = f.name atexit.register(lambda: os.remove(f.name)) return self.__local_tmpfile @@ -818,11 +817,11 @@ def _eval_line_using_file(self, line, restart_if_needed=True): INPUT: - - ``line`` -- (string) a command. - - ``restart_if_needed`` -- (optional bool, default ``True``) -- - If it is ``True``, the command evaluation is evaluated + - ``line`` -- string; a command + - ``restart_if_needed`` -- boolean (default: ``True``); + if it is ``True``, the command evaluation is evaluated a second time after restarting the interface, if an - :class:`EOFError` occurred. + :exc:`EOFError` occurred. TESTS:: @@ -851,7 +850,6 @@ def _eval_line_using_file(self, line, restart_if_needed=True): sage: singular(3) Singular crashed -- automatically restarting. 3 - """ with open(self._local_tmpfile(), 'w') as F: F.write(line + '\n') @@ -916,15 +914,15 @@ def _eval_line(self, line, allow_use_file=True, wait_for_prompt=True, restart_if INPUT: - - ``line`` -- (string) a command. - - ``allow_use_file`` (optional bool, default ``True``) -- + - ``line`` -- string; a command + - ``allow_use_file`` -- boolean (default: ``True``); allow to evaluate long commands using :meth:`_eval_line_using_file`. - - ``wait_for_prompt`` (optional bool, default ``True``) -- + - ``wait_for_prompt`` -- boolean (default: ``True``); wait until the prompt appears in the sub-process' output. - - ``restart_if_needed`` (optional bool, default ``True``) -- - If it is ``True``, the command evaluation is evaluated + - ``restart_if_needed`` -- boolean (default: ``True``); + if it is ``True``, the command evaluation is evaluated a second time after restarting the interface, if an - :class:`EOFError` occurred. + :exc:`EOFError` occurred. TESTS:: @@ -982,7 +980,6 @@ def _eval_line(self, line, allow_use_file=True, wait_for_prompt=True, restart_if sage: singular('2+3') Singular crashed -- automatically restarting. 5 - """ if allow_use_file and wait_for_prompt and self._eval_using_file_cutoff and len(line) > self._eval_using_file_cutoff: return self._eval_line_using_file(line) @@ -1186,10 +1183,10 @@ def _expect_expr(self, expr=None, timeout=None): INPUT: - - ``expr`` -- None or a string or list of strings - (default: None) + - ``expr`` -- ``None`` or a string or list of strings + (default: ``None``) - - ``timeout`` -- None or a number (default: None) + - ``timeout`` -- ``None`` or a number (default: ``None``) EXAMPLES: @@ -1269,7 +1266,7 @@ def _sendstr(self, string): INPUT: - - ``string`` -- a string + - ``string`` -- string EXAMPLES: We illustrate this function using the Singular interface:: @@ -1359,32 +1356,34 @@ def _synchronize(self, cmd='1+%s;\n'): ########################################################################### def eval(self, code, strip=True, synchronize=False, locals=None, allow_use_file=True, - split_lines="nofile", **kwds): + split_lines='nofile', **kwds): """ INPUT: - - ``code`` -- text to evaluate + - ``code`` -- text to evaluate - - ``strip`` -- bool; whether to strip output prompts, - etc. (ignored in the base class). + - ``strip`` -- boolean; whether to strip output prompts, + etc. (ignored in the base class) - - ``locals`` -- None (ignored); this is used for compatibility - with the Sage notebook's generic system interface. + - ``locals`` -- None (ignored); this is used for compatibility + with the Sage notebook's generic system interface - - ``allow_use_file`` -- bool (default: ``True``); if True and ``code`` exceeds an - interface-specific threshold then ``code`` will be communicated - via a temporary file rather that the character-based interface. - If False then the code will be communicated via the character interface. + - ``allow_use_file`` -- boolean (default: ``True``); if ``True`` and + ``code`` exceeds an interface-specific threshold then ``code`` will + be communicated via a temporary file rather that the character-based + interface. If ``False`` then the code will be communicated via the + character interface. - - ``split_lines`` -- Tri-state (default: "nofile"); if "nofile" then ``code`` is sent line by line - unless it gets communicated via a temporary file. - If True then ``code`` is sent line by line, but some lines individually - might be sent via temporary file. Depending on the interface, this may transform - grammatical ``code`` into ungrammatical input. - If False, then the whole block of code is evaluated all at once. + - ``split_lines`` -- Tri-state (default: ``'nofile'``); if "nofile" + then ``code`` is sent line by line unless it gets communicated via a + temporary file. If ``True`` then ``code`` is sent line by line, but + some lines individually might be sent via temporary file. Depending + on the interface, this may transform grammatical ``code`` into + ungrammatical input. If ``False``, then the whole block of code is + evaluated all at once. - - ``**kwds`` -- All other arguments are passed onto the _eval_line - method. An often useful example is reformat=False. + - ``**kwds`` -- all other arguments are passed onto the ``_eval_line`` + method. An often useful example is ``reformat=False``. """ if synchronize: try: @@ -1476,7 +1475,7 @@ class FunctionElement(InterfaceFunctionElement): def is_ExpectElement(x): """ - Return True if ``x`` is of type :class:`ExpectElement` + Return ``True`` if ``x`` is of type :class:`ExpectElement`. This function is deprecated; use :func:`isinstance` (of :class:`sage.interfaces.abc.ExpectElement`) instead. @@ -1529,10 +1528,10 @@ def __init__(self, parent, value, is_name=False, name=None): def __hash__(self): """ - Return the hash of self. + Return the hash of ``self``. This is a default implementation of hash - which just takes the hash of the string of self. + which just takes the hash of the string of ``self``. """ return hash('%s%s' % (self, self._session_number)) @@ -1582,11 +1581,11 @@ def __init__(self, interface, silent=False, stdout=None): INPUT: - - ``interface`` -- the interface whose communication shall be dumped. + - ``interface`` -- the interface whose communication shall be dumped - ``silent`` -- if ``True`` this context does nothing - - ``stdout`` -- optional parameter for alternative stdout device (default: ``None``) + - ``stdout`` -- (optional) parameter for alternative stdout device (default: ``None``) EXAMPLES:: diff --git a/src/sage/interfaces/four_ti_2.py b/src/sage/interfaces/four_ti_2.py index 7815c9eda62..7a1034243ad 100644 --- a/src/sage/interfaces/four_ti_2.py +++ b/src/sage/interfaces/four_ti_2.py @@ -119,9 +119,9 @@ def write_matrix(self, mat, filename): INPUT: - - ``mat`` -- A matrix of integers or something that can be - converted to that. - - ``filename`` -- A file name not including a path. + - ``mat`` -- a matrix of integers or something that can be + converted to that + - ``filename`` -- a file name not including a path EXAMPLES:: @@ -144,8 +144,8 @@ def write_single_row(self, row, filename): INPUT: - - ``row`` -- A list of integers. - - ``filename`` -- A file name not including a path. + - ``row`` -- list of integers + - ``filename`` -- a file name not including a path EXAMPLES:: @@ -164,11 +164,11 @@ def write_array(self, array, nrows, ncols, filename): INPUT: - - ``array`` -- A matrix of integers. Can be represented as a list - of lists. - - ``nrows`` -- The number of rows in ``array``. - - ``ncols`` -- The number of columns in ``array``. - - ``file`` -- A file name not including a path. + - ``array`` -- a matrix of integers. Can be represented as a list + of lists + - ``nrows`` -- the number of rows in ``array`` + - ``ncols`` -- the number of columns in ``array`` + - ``file`` -- a file name not including a path EXAMPLES:: @@ -189,11 +189,9 @@ def read_matrix(self, filename): INPUT: - - ``filename`` -- The name of the file to read from. + - ``filename`` -- the name of the file to read from - OUTPUT: - - The data from the file as a matrix over `\ZZ`. + OUTPUT: the data from the file as a matrix over `\ZZ` EXAMPLES:: @@ -236,11 +234,9 @@ def _process_input(self, kwds): INPUT: - - ``kwds`` -- A dict controlling what data is written to what files. - - OUTPUT: + - ``kwds`` -- dictionary controlling what data is written to what files - The value of the key ``project``. + OUTPUT: the value of the key ``project`` EXAMPLES:: @@ -283,10 +279,10 @@ def call(self, command, project, verbose=True, *, options=()): INPUT: - - ``command`` -- The 4ti2 program to run. - - ``project`` -- The file name of the project to run on. - - ``verbose`` -- Display the output of 4ti2 if ``True``. - - ``options`` -- A list of strings to pass to the program. + - ``command`` -- the 4ti2 program to run + - ``project`` -- the file name of the project to run on + - ``verbose`` -- display the output of 4ti2 if ``True`` + - ``options`` -- list of strings to pass to the program EXAMPLES:: @@ -333,7 +329,6 @@ def zsolve(self, mat=None, rel=None, rhs=None, sign=None, lat=None, project=None [1 2 3] [0 0 0], [], [1 1 1] ] - """ project = self._process_input(locals()) self.call('zsolve', project, options=['-q']) @@ -441,7 +436,6 @@ def ppi(self, n): [-1 -1 1] [-3 0 1] [ 1 -2 1] - """ self.call('ppi', f'{n} 2> /dev/null') return self.read_matrix('ppi%s.gra' % n) diff --git a/src/sage/interfaces/fricas.py b/src/sage/interfaces/fricas.py index 630283d5262..39f41ec2045 100644 --- a/src/sage/interfaces/fricas.py +++ b/src/sage/interfaces/fricas.py @@ -19,7 +19,6 @@ - Martin Rubey, Bill Page (2016-08): Completely separate from Axiom, implement more complete translation from FriCAS to SageMath types. - EXAMPLES:: sage: fricas('3 * 5') @@ -280,7 +279,7 @@ def __init__(self, name='fricas', command=None, sage: fricas(I) %i - sage: integrate(sin(x)*exp(I*x), x, -pi, 0, algorithm="fricas") + sage: integrate(sin(x)*exp(I*x), x, -pi, 0, algorithm='fricas') 1/2*I*pi sage: fricas(I*sin(x)).sage() @@ -380,7 +379,6 @@ def _quit_string(self): sage: fricas.quit() sage: fricas.pid() == p False - """ return ')quit' @@ -463,11 +461,9 @@ def _read_in_file_command(self, filename): INPUT: - - ``filename``, a string ending in '.input'. - - OUTPUT: + - ``filename`` -- string ending in '.input'. - - a string with the command for reading filename without output. + OUTPUT: string with the command for reading filename without output TESTS: @@ -475,7 +471,6 @@ def _read_in_file_command(self, filename): sage: len(fricas([i for i in range(600)])) # indirect doctest 600 - """ if not filename.endswith('.input'): raise ValueError("the filename must end with .input") @@ -486,7 +481,6 @@ def _remote_tmpfile(self): """ Return a remote tmpfile ending with ".input" used to buffer long command lines sent to FriCAS. - """ try: return self.__remote_tmpfile @@ -515,13 +509,11 @@ def _check_errors(self, line, output): INPUT: - - ``line``, a string that was sent to FriCAS. + - ``line`` -- string that was sent to FriCAS - - ``output``, a string returned by FriCAS + - ``output`` -- string returned by FriCAS - OUTPUT: - - None + OUTPUT: none TESTS:: @@ -552,7 +544,6 @@ def _check_errors(self, line, output): Perhaps you should use "@" to indicate the required return type, or "$" to specify which version of the function you need. - """ # otherwise there might be a message m = re.search(r"\|startKeyedMsg\|\n(.*)\n\|endOfKeyedMsg\|", @@ -656,17 +647,16 @@ def set(self, var, value): INPUT: - - ``var``, ``value``: strings, the first representing a valid - FriCAS variable identifier, the second a FriCAS expression. + - ``var``, ``value`` -- strings; the first representing a valid + FriCAS variable identifier, the second a FriCAS expression - OUTPUT: None + OUTPUT: none EXAMPLES:: sage: fricas.set('xx', '2') sage: fricas.get('xx') '2' - """ cmd = '%s%s%s;' % (var, self._assign_symbol(), value) output = self.eval(cmd, reformat=False) @@ -735,19 +725,18 @@ def get_string(self, var): sage: var("a b"); f = 1/(1+a*cos(x)) (a, b) - sage: lF = integrate(f, x, algorithm="fricas") + sage: lF = integrate(f, x, algorithm='fricas') sage: (diff(lF[0], x) - f).simplify_trig() 0 sage: (diff(lF[1], x) - f).simplify_trig() 0 - sage: f = 1/(b*x^2+a); lF = integrate(f, x, algorithm="fricas"); lF + sage: f = 1/(b*x^2+a); lF = integrate(f, x, algorithm='fricas'); lF [1/2*log((2*a*b*x + (b*x^2 - a)*sqrt(-a*b))/(b*x^2 + a))/sqrt(-a*b), arctan(sqrt(a*b)*x/a)/sqrt(a*b)] sage: (diff(lF[0], x) - f).simplify_trig() 0 sage: (diff(lF[1], x) - f).simplify_trig() 0 - """ # strip removes leading and trailing whitespace, after that # we can assume that the first and the last character are @@ -763,7 +752,6 @@ def get_integer(self, var): sage: fricas.get_integer('factorial 1111') == factorial(1111) True - """ return int(self.get_unparsed_InputForm(str(var))) @@ -790,7 +778,7 @@ def get_unparsed_InputForm(self, var): - catch errors, especially when InputForm is not available: - - for example when integration returns ``"failed"`` + - for example when integration returns ``'failed'`` - ``UnivariatePolynomial`` @@ -800,7 +788,6 @@ def get_unparsed_InputForm(self, var): sage: fricas.get_unparsed_InputForm('1..3') '(1..3)$Segment(PositiveInteger())' - """ return self.get_string('unparse((%s)::InputForm)' % var) @@ -812,7 +799,6 @@ def get_InputForm(self, var): sage: fricas.get_InputForm('1..3') '(($elt (Segment (PositiveInteger)) SEGMENT) 1 3)' - """ return self.get_string('sageprint((%s)::InputForm)' % str(var)) @@ -904,7 +890,7 @@ def __reduce__(self): return reduce_load_fricas, tuple([]) def eval(self, code, strip=True, synchronize=False, locals=None, allow_use_file=True, - split_lines="nofile", reformat=True, **kwds): + split_lines='nofile', reformat=True, **kwds): """ Evaluate ``code`` using FriCAS. @@ -913,7 +899,7 @@ def eval(self, code, strip=True, synchronize=False, locals=None, allow_use_file= INPUT: - - ``reformat`` -- bool; remove the output markers when True. + - ``reformat`` -- boolean; remove the output markers when True This can also be used to pass system commands to FriCAS. @@ -925,7 +911,6 @@ def eval(self, code, strip=True, synchronize=False, locals=None, allow_use_file= '' sage: fricas("x") x - """ output = Expect.eval(self, code, strip=strip, synchronize=synchronize, locals=locals, @@ -1203,11 +1188,9 @@ def _get_sage_type(self, domain): """ INPUT: - - ``domain``, a FriCAS SExpression + - ``domain`` -- a FriCAS SExpression - OUTPUT: - - - a corresponding Sage type + OUTPUT: a corresponding Sage type EXAMPLES:: @@ -1309,7 +1292,6 @@ def _parse_and_eval(s, start=0): Traceback (most recent call last): ... TypeError: cannot coerce arguments: no canonical coercion from to Symbolic Ring - """ a = start while s[a] in FriCASElement._WHITESPACE: @@ -1348,7 +1330,6 @@ def _parse_list(s, start=0): sage: FriCASElement._parse_list('(bcd)') (bcd(), 4) - """ a = start assert s[a] == FriCASElement._LEFTBRACKET @@ -1386,8 +1367,8 @@ def _parse_other(s, start=0, make_fun=False): - ``s`` -- string - ``start`` -- integer; specifies where the symbol begins - - ``make_fun`` -- (default: ``False``) a Boolean; specifying - whether the atom should be interpreted as a function call + - ``make_fun`` -- boolean (default: ``False``); whether the atom should + be interpreted as a function call TESTS:: @@ -1401,12 +1382,12 @@ def _parse_other(s, start=0, make_fun=False): This function cannot use the symbol table to translate symbols which are not function calls, as :issue:`31849` shows - - ``D`` would erroneously be interpreted as differential + ``D`` would erroneously be interpreted as differential then:: sage: var("D") D - sage: integrate(D/x, x, algorithm="fricas") + sage: integrate(D/x, x, algorithm='fricas') D*log(x) However, it does have to check for constants, for example @@ -1414,7 +1395,6 @@ def _parse_other(s, start=0, make_fun=False): sage: FriCASElement._parse_other("%pi") (pi, 2) - """ a = start b = len(s) @@ -1469,7 +1449,6 @@ def _parse_string(s, start=0): sage: FriCASElement._parse_string('"(b c)"') ('(b c)', 6) - """ a = start assert s[a] == FriCASElement._STRINGMARKER @@ -1592,7 +1571,7 @@ def _sage_expression(fricas_InputForm): Check that :issue:`25987` is fixed:: - sage: integrate(lambert_w(x), x, algorithm="fricas") + sage: integrate(lambert_w(x), x, algorithm='fricas') (x*lambert_w(x)^2 - x*lambert_w(x) + x)/lambert_w(x) Check that :issue:`25838` is fixed:: @@ -2084,7 +2063,6 @@ def __init__(self, object, name): upperCase! sage: a.upperCase_e() "HELLO" - """ if name.endswith("_q"): name = name[:-2] + "?" @@ -2106,7 +2084,6 @@ def __init__(self, parent, name): upperCase? sage: fricas.upperCase_e upperCase! - """ if name.endswith("_q"): name = name[:-2] + "?" diff --git a/src/sage/interfaces/frobby.py b/src/sage/interfaces/frobby.py index 498a5a6da58..75200dc0694 100644 --- a/src/sage/interfaces/frobby.py +++ b/src/sage/interfaces/frobby.py @@ -37,14 +37,12 @@ def __call__(self, action, input=None, options=[], verbose=False): INPUT: - - action -- A string telling Frobby what to do. - - input -- None or a string that is passed to Frobby as standard in. - - options -- A list of options without the dash in front. - - verbose -- bool (default: false) Print detailed information. + - ``action`` -- string telling Frobby what to do + - ``input`` -- ``None`` or string that is passed to Frobby as standard in + - ``options`` -- list of options without the dash in front + - ``verbose`` -- boolean (default: ``False``); print detailed information - OUTPUT: - - - string -- What Frobby wrote to the standard output stream. + OUTPUT: string; what Frobby wrote to the standard output stream EXAMPLES: @@ -104,11 +102,9 @@ def alexander_dual(self, monomial_ideal): INPUT: - - monomial_ideal -- The monomial ideal to decompose. + - ``monomial_ideal`` -- the monomial ideal to decompose - OUTPUT: - - The monomial corresponding to the Alexander dual. + OUTPUT: the monomial corresponding to the Alexander dual EXAMPLES: @@ -131,8 +127,6 @@ def alexander_dual(self, monomial_ideal): sage: I=R.ideal([prod([R.gen(i-1) for i in a]) for a in t.facets()]) sage: len(frobby.alexander_dual(I).gens()) 643 - - """ frobby_input = self._ideal_to_string(monomial_ideal) frobby_output = self('alexdual', input=frobby_input) @@ -140,7 +134,7 @@ def alexander_dual(self, monomial_ideal): def hilbert(self, monomial_ideal): r""" - Computes the multigraded Hilbert-Poincaré series of the input + Compute the multigraded Hilbert-Poincaré series of the input ideal. Use the -univariate option to get the univariate series. The Hilbert-Poincaré series of a monomial ideal is the sum of all @@ -151,13 +145,11 @@ def hilbert(self, monomial_ideal): INPUT: - - monomial_ideal -- A monomial ideal. + - ``monomial_ideal`` -- a monomial ideal OUTPUT: - - A polynomial in the same ring as the ideal. + A polynomial in the same ring as the ideal. EXAMPLES:: @@ -165,7 +157,6 @@ def hilbert(self, monomial_ideal): sage: I=[d*b*c,b^2*c,b^10,d^10]*R # optional - frobby sage: frobby.hilbert(I) # optional - frobby d^10*b^10*c + d^10*b^10 + d^10*b*c + b^10*c + d^10 + b^10 + d*b^2*c + d*b*c + b^2*c + 1 - """ frobby_input = self._ideal_to_string(monomial_ideal) frobby_output = self('hilbert', input=frobby_input) @@ -189,7 +180,7 @@ def associated_primes(self, monomial_ideal): INPUT: - - monomial_ideal -- The monomial ideal to decompose. + - ``monomial_ideal`` -- the monomial ideal to decompose OUTPUT: @@ -203,7 +194,6 @@ def associated_primes(self, monomial_ideal): sage: frobby.associated_primes(I) # optional - frobby [Ideal (d, b) of Multivariate Polynomial Ring in d, b, c over Rational Field, Ideal (d, b, c) of Multivariate Polynomial Ring in d, b, c over Rational Field] - """ frobby_input = self._ideal_to_string(monomial_ideal) frobby_output = self('assoprimes', input=frobby_input) @@ -224,11 +214,9 @@ def dimension(self, monomial_ideal): INPUT: - - monomial_ideal -- The monomial ideal to decompose. - - OUTPUT: + - ``monomial_ideal`` -- the monomial ideal to decompose - The dimension of the zero set of the ideal. + OUTPUT: the dimension of the zero set of the ideal EXAMPLES:: @@ -236,7 +224,6 @@ def dimension(self, monomial_ideal): sage: I=[d*b*c,b^2*c,b^10,d^10]*R # optional - frobby sage: frobby.dimension(I) # optional - frobby 1 - """ frobby_input = self._ideal_to_string(monomial_ideal) frobby_output = self('dimension', input=frobby_input) @@ -250,7 +237,7 @@ def irreducible_decomposition(self, monomial_ideal): INPUT: - - monomial_ideal -- The monomial ideal to decompose. + - ``monomial_ideal`` -- the monomial ideal to decompose OUTPUT: @@ -309,9 +296,9 @@ def _parse_ideals(self, string, ring): INPUT: - - string -- The string to be parsed. - - ring -- The ring within which to construct the irreducible - monomial ideals within. + - ``string`` -- the string to be parsed + - ``ring`` -- the ring within which to construct the irreducible + monomial ideals within OUTPUT: @@ -327,7 +314,6 @@ def _parse_ideals(self, string, ring): sage: frobby._parse_ideals(string, ring) [Ideal (x*y^2*z^3, y^5) of Multivariate Polynomial Ring in x, y, z over Rational Field, Ideal (x*y^2*z^3, x^4*y^5*z^6) of Multivariate Polynomial Ring in x, y, z over Rational Field] - """ lines = string.split('\n') if lines[-1] == '': @@ -359,7 +345,7 @@ def _parse_4ti2_matrix(self, string): INPUT: - - string -- The string to be parsed. + - ``string`` -- the string to be parsed OUTPUT: @@ -412,11 +398,9 @@ def _ideal_to_string(self, monomial_ideal): INPUT: - - monomial_ideal -- The monomial ideal to be formatted as a string. + - ``monomial_ideal`` -- the monomial ideal to be formatted as a string - OUTPUT: - - A string in 4ti2 format representing the ideal. + OUTPUT: string in ``4ti2`` format representing the ideal EXAMPLES:: @@ -446,11 +430,9 @@ def _monomial_to_string(self, monomial): INPUT: - - monomial -- The monomial whose exponent vector is to be formatted. - - OUTPUT: + - ``monomial`` -- the monomial whose exponent vector is to be formatted - A string representing the exponent vector of monomial. + OUTPUT: string representing the exponent vector of monomial EXAMPLES:: diff --git a/src/sage/interfaces/gap.py b/src/sage/interfaces/gap.py index f093e865d4c..ffd4d48723c 100644 --- a/src/sage/interfaces/gap.py +++ b/src/sage/interfaces/gap.py @@ -9,13 +9,13 @@ The interface offers three pieces of functionality: -#. ``gap_console()`` -- A function that dumps you into +#. ``gap_console()`` -- a function that dumps you into an interactive command-line GAP session. -#. ``gap(expr)`` -- Evaluation of arbitrary GAP +#. ``gap(expr)`` -- evaluation of arbitrary GAP expressions, with the result returned as a string. -#. ``gap.new(expr)`` -- Creation of a Sage object that +#. ``gap.new(expr)`` -- creation of a Sage object that wraps a GAP object. This provides a Pythonic interface to GAP. For example, if ``f=gap.new(10)``, then ``f.Factors()`` returns the prime factorization of @@ -129,7 +129,7 @@ The GAP interface reads in even very long input (using files) in a robust manner, as long as you are creating a new object. -.. note:: +.. NOTE:: Using ``gap.eval`` for long input is much less robust, and is not recommended. @@ -254,7 +254,6 @@ class Gap_generic(ExtraTabCompletion, Expect): - Franco Saliola (Feb 2010): refactored to separate out the generic code - """ _identical_function = "IsIdenticalObj" @@ -299,7 +298,7 @@ def _synchronize(self, timeout=0.5, cmd='%s;'): def interrupt(self, tries=None, timeout=1, quit_on_fail=True): """ - Interrupt the GAP process + Interrupt the GAP process. Gap installs a SIGINT handler, we call it directly instead of trying to sent Ctrl-C. Unlike @@ -379,13 +378,12 @@ def _assign_symbol(self): sage: gap = Gap() sage: print(gap._assign_symbol()) := - """ return ":=" def _quit_string(self): """ - Returns the string used to quit GAP. + Return the string used to quit GAP. EXAMPLES:: @@ -405,7 +403,7 @@ def _quit_string(self): def _read_in_file_command(self, filename): r""" - Returns the command use to read in a file in GAP. + Return the command use to read in a file in GAP. EXAMPLES:: @@ -425,7 +423,7 @@ def _read_in_file_command(self, filename): def _continuation_prompt(self): """ - Returns the continuation prompt in GAP. + Return the continuation prompt in GAP. EXAMPLES:: @@ -438,7 +436,7 @@ def load_package(self, pkg, verbose=False): """ Load the Gap package with the given name. - If loading fails, raise a :class:`RuntimeError` exception. + If loading fails, raise a :exc:`RuntimeError` exception. TESTS:: @@ -461,17 +459,16 @@ def eval(self, x, newlines=False, strip=True, split_lines=True, **kwds): INPUT: - - ``s`` -- string containing GAP code. + - ``s`` -- string containing GAP code - - ``newlines`` -- bool (default: ``True``); if False, - remove all backslash-newlines inserted by the GAP output - formatter. + - ``newlines`` -- boolean (default: ``True``); if ``False``, + remove all backslash-newlines inserted by the GAP output formatter - - ``strip`` -- ignored + - ``strip`` -- ignored - - ``split_lines`` -- bool (default: ``True``); if True then each - line is evaluated separately. If False, then the whole - block of code is evaluated all at once. + - ``split_lines`` -- boolean (default: ``True``); if ``True`` then each + line is evaluated separately. If ``False``, then the whole + block of code is evaluated all at once. EXAMPLES:: @@ -632,15 +629,15 @@ def _eval_line(self, line, allow_use_file=True, wait_for_prompt=True, restart_if INPUT: - - ``line`` -- (string) a command. - - ``allow_use_file`` (optional bool, default ``True``) -- - allow to evaluate long commands using :meth:`_eval_line_using_file`. - - ``wait_for_prompt`` (optional bool, default ``True``) -- - wait until the prompt appears in the sub-process' output. - - ``restart_if_needed`` (optional bool, default ``True``) -- - If it is ``True``, the command evaluation is evaluated + - ``line`` -- string; a command + - ``allow_use_file`` -- boolean (default: ``True``); + allow to evaluate long commands using :meth:`_eval_line_using_file` + - ``wait_for_prompt`` -- boolean (default: ``True``); + wait until the prompt appears in the sub-process' output + - ``restart_if_needed`` -- boolean (default: ``True``); + if it is ``True``, the command evaluation is evaluated a second time after restarting the interface, if an - :class:`EOFError` occurred. + :exc:`EOFError` occurred. TESTS:: @@ -775,7 +772,7 @@ def _contains(self, v1, v2): def _true_symbol(self): """ - Returns the symbol for truth in GAP. + Return the symbol for truth in GAP. EXAMPLES:: @@ -788,7 +785,7 @@ def _true_symbol(self): def _false_symbol(self): """ - Returns the symbol for falsity in GAP. + Return the symbol for falsity in GAP. EXAMPLES:: @@ -801,7 +798,7 @@ def _false_symbol(self): def _equality_symbol(self): """ - Returns the symbol for equality in GAP. + Return the symbol for equality in GAP. EXAMPLES:: @@ -816,7 +813,7 @@ def _equality_symbol(self): def version(self): """ - Returns the version of GAP being used. + Return the version of GAP being used. EXAMPLES:: @@ -827,7 +824,7 @@ def version(self): def function_call(self, function, args=None, kwds=None): """ - Calls the GAP function with args and kwds. + Call the GAP function with ``args`` and ``kwds``. EXAMPLES:: @@ -899,11 +896,9 @@ def get_record_element(self, record, name): INPUT: - ``record`` -- a GAP record - - ``name`` -- str + - ``name`` -- string - OUTPUT: - - - :class:`GapElement` + OUTPUT: :class:`GapElement` EXAMPLES:: @@ -1005,7 +1000,6 @@ def is_string(self): True sage: gap('[1,2,3]').is_string() False - """ return bool(self.IsString()) @@ -1136,7 +1130,7 @@ def __reduce__(self): def _next_var_name(self): r""" - Returns the next unused variable name. + Return the next unused variable name. Note that names starting with dollar signs are valid GAP identifiers, but need to be escaped with a backslash starting @@ -1216,7 +1210,7 @@ def _start(self): def _function_class(self): """ - Returns the GapFunction class. + Return the GapFunction class. EXAMPLES:: @@ -1232,7 +1226,7 @@ def _function_class(self): def cputime(self, t=None): r""" - Returns the amount of CPU time that the GAP session has used. If + Return the amount of CPU time that the GAP session has used. If ``t`` is not None, then it returns the difference between the current CPU time and ``t``. @@ -1428,7 +1422,7 @@ def console(self): def _object_class(self): """ - Returns the GapElement class. + Return the GapElement class. EXAMPLES:: @@ -1450,7 +1444,7 @@ def _an_element_(self): def _function_element_class(self): """ - Returns the GapFunctionElement class. + Return the GapFunctionElement class. EXAMPLES:: @@ -1464,11 +1458,9 @@ def _function_element_class(self): @cached_method def _tab_completion(self): """ - Return additional tab completion entries - - OUTPUT: + Return additional tab completion entries. - List of strings + OUTPUT: list of strings EXAMPLES:: @@ -1573,9 +1565,7 @@ def _tab_completion(self): """ Return additional tab completion entries. - OUTPUT: - - List of strings + OUTPUT: list of strings EXAMPLES:: @@ -1633,7 +1623,7 @@ def _instancedoc_(self): def is_GapElement(x): """ - Return True if ``x`` is a :class:`GapElement` + Return ``True`` if ``x`` is a :class:`GapElement`. This function is deprecated; use :func:`isinstance` (of :class:`sage.interfaces.abc.GapElement`) instead. @@ -1720,7 +1710,7 @@ def intmod_gap_to_sage(x): r""" INPUT: - - x -- Gap integer mod ring element + - ``x`` -- Gap integer mod ring element EXAMPLES:: @@ -1770,7 +1760,7 @@ def intmod_gap_to_sage(x): def reduce_load_GAP(): """ - Returns the GAP interface object defined in sage.interfaces.gap. + Return the GAP interface object defined in ``sage.interfaces.gap``. EXAMPLES:: diff --git a/src/sage/interfaces/gap3.py b/src/sage/interfaces/gap3.py index 2781ac4f994..de6a35586e3 100644 --- a/src/sage/interfaces/gap3.py +++ b/src/sage/interfaces/gap3.py @@ -52,7 +52,7 @@ The interface to GAP3 offers the following functionality. -#. ``gap3(expr)`` -- Evaluation of arbitrary GAP3 expressions, with the +#. ``gap3(expr)`` -- evaluation of arbitrary GAP3 expressions, with the result returned as a Sage object wrapping the corresponding GAP3 element:: sage: # optional - gap3 @@ -296,9 +296,9 @@ def __init__(self, command=gap3_cmd): INPUT: - - command -- string (default "gap3"); points to the gap3 - executable on your system; by default, it is assumed the - executable is in your path. + - command -- string (default: ``'gap3'``); points to the gap3 + executable on your system. By default, it is assumed the + executable is in your path. EXAMPLES:: @@ -624,13 +624,11 @@ def _install_hints(self): @cached_method def _tab_completion(self): """ - Return additional tab completion entries + Return additional tab completion entries. - Currently this is empty + Currently this is empty. - OUTPUT: - - List of strings + OUTPUT: list of strings EXAMPLES:: @@ -645,7 +643,7 @@ def _tab_completion(self): class GAP3Element(GapElement_generic): r""" - A GAP3 element + A GAP3 element. .. NOTE:: @@ -658,11 +656,11 @@ class GAP3Element(GapElement_generic): - ``value`` -- the GAP3 command as a string - - ``is_name`` -- bool (default: ``False``); if True, then ``value`` is + - ``is_name`` -- boolean (default: ``False``); if ``True``, then ``value`` is the variable name for the object - - ``name`` -- str (default: ``None``); the variable name to use for the - object. If ``None``, then a variable name is generated. + - ``name`` -- string (default: ``None``); the variable name to use for the + object. If ``None``, then a variable name is generated .. NOTE:: @@ -771,7 +769,7 @@ def _latex_(self): class GAP3Record(GAP3Element): r""" - A GAP3 record + A GAP3 record. .. NOTE:: @@ -788,9 +786,7 @@ def recfields(self): Return a list of the fields for the record. (Record fields are akin to object attributes in Sage.) - OUTPUT: - - - list of strings -- the field records + OUTPUT: list of strings -- the field records EXAMPLES:: @@ -813,9 +809,7 @@ def operations(self): r""" Return a list of the GAP3 operations for the record. - OUTPUT: - - - list of strings -- operations of the record + OUTPUT: list of strings -- operations of the record EXAMPLES:: @@ -864,7 +858,7 @@ def __getattr__(self, attrname): def _tab_completion(self): r""" - Defines the list of methods and attributes that will appear for tab + Define the list of methods and attributes that will appear for tab completion. OUTPUT: diff --git a/src/sage/interfaces/gap_workspace.py b/src/sage/interfaces/gap_workspace.py index 70bb584fdef..c7df7ffaed1 100644 --- a/src/sage/interfaces/gap_workspace.py +++ b/src/sage/interfaces/gap_workspace.py @@ -20,19 +20,19 @@ from sage.env import DOT_SAGE, HOSTNAME, GAP_ROOT_PATHS -def gap_workspace_file(system="gap", name="workspace", dir=None): +def gap_workspace_file(system='gap', name='workspace', dir=None): r""" Return the filename for the GAP workspace. INPUT: - - ``system`` -- the name of the system, either ``"gap"`` or - ``"libgap"`` + - ``system`` -- the name of the system, either ``'gap'`` or + ``'libgap'`` - - ``name`` -- the kind of workspace, usually ``"workspace"`` but + - ``name`` -- the kind of workspace, usually ``'workspace'`` but the library interface also uses other files - - ``dir`` -- the directory where the workspaces should be stored. + - ``dir`` -- the directory where the workspaces should be stored By default, this is ``DOT_SAGE/gap`` EXAMPLES:: @@ -79,7 +79,7 @@ def prepare_workspace_dir(dir=None): INPUT: - - ``dir`` -- the directory where the workspaces should be stored. + - ``dir`` -- the directory where the workspaces should be stored By default, this is ``DOT_SAGE/gap`` OUTPUT: the actual workspace directory diff --git a/src/sage/interfaces/genus2reduction.py b/src/sage/interfaces/genus2reduction.py index 8cd13286830..913188f9182 100644 --- a/src/sage/interfaces/genus2reduction.py +++ b/src/sage/interfaces/genus2reduction.py @@ -192,7 +192,7 @@ def divisors_to_string(divs): - ``divs`` -- a (possibly empty) list of numbers - OUTPUT: a string representation of these numbers + OUTPUT: string representation of these numbers EXAMPLES:: diff --git a/src/sage/interfaces/gfan.py b/src/sage/interfaces/gfan.py index d8f2157034f..a169848c678 100644 --- a/src/sage/interfaces/gfan.py +++ b/src/sage/interfaces/gfan.py @@ -54,13 +54,13 @@ class Gfan(): @rename_keyword(deprecation=33468, I='input') def __call__(self, input, cmd='', verbose=False, format=None): r""" - Call Groebner Fan program with given input + Call Groebner Fan program with given input. INPUT: - - ``input`` -- string, input - - ``cmd`` -- string (default:``''``), GFan command - - ``verbose`` -- bool (default:``False``) + - ``input`` -- string; input + - ``cmd`` -- string (default: ``''``); GFan command + - ``verbose`` -- boolean (default: ``False``) EXAMPLES:: @@ -90,7 +90,6 @@ def __call__(self, input, cmd='', verbose=False, format=None): doctest:...: DeprecationWarning: use the option 'input' instead of 'I' See https://github.com/sagemath/sage/issues/33468 for details. - """ if format is not None: from sage.misc.superseded import deprecation diff --git a/src/sage/interfaces/giac.py b/src/sage/interfaces/giac.py index 2464d5c4664..00c9ff429c3 100644 --- a/src/sage/interfaces/giac.py +++ b/src/sage/interfaces/giac.py @@ -25,7 +25,6 @@ $SAGE_LOCAL/share/giac/doc/en/cascmd_local/index.html - EXAMPLES:: sage: giac('3 * 5') @@ -48,7 +47,7 @@ If the string "error" (case insensitive) occurs in the output of -anything from Giac, a :class:`RuntimeError` exception is raised. +anything from Giac, a :exc:`RuntimeError` exception is raised. Tutorial -------- @@ -481,7 +480,6 @@ def console(self): Press CTRL and D simultaneously to finish session Type ?commandname for help 0>> - """ giac_console() @@ -610,7 +608,6 @@ def _eval_line(self, line, allow_use_file=True, wait_for_prompt=True, restart_if sage: giac_result = giac(h1) + giac(h2) sage: bool(giac_result.sage() == x) True - """ with gc_disabled(): z = Expect._eval_line(self, line, allow_use_file=allow_use_file, @@ -629,8 +626,8 @@ def eval(self, code, strip=True, **kwds): INPUT: - - code -- str - - strip -- Default is True and removes ``\n`` + - ``code`` -- str + - ``strip`` -- default is ``True`` and removes ``\n`` EXAMPLES:: @@ -772,7 +769,7 @@ def help(self, string): INPUT: - - ``string`` -- a string to search for in the giac help system + - ``string`` -- string to search for in the giac help system EXAMPLES:: @@ -804,7 +801,6 @@ def version(self): sage: giac.version() "giac... - """ return giac('version()') @@ -814,7 +810,7 @@ class GiacFunction(ExpectFunction): def _instancedoc_(self): """ Return the Giac help for this function. This gets called when - doing "?" on self. + doing ``?`` on ``self``. EXAMPLES:: @@ -830,7 +826,7 @@ class GiacFunctionElement(FunctionElement): def _instancedoc_(self): """ Return the Giac help for this function. This gets called when - doing "?" on self. + doing ``?`` on ``self``. EXAMPLES:: @@ -845,7 +841,7 @@ def _instancedoc_(self): class GiacElement(ExpectElement): def __float__(self): """ - Return a floating point version of self. + Return a floating point version of ``self``. EXAMPLES:: @@ -858,7 +854,7 @@ def __float__(self): def unapply(self, var): """ - Creates a Giac function in the given arguments from a Giac symbol. + Create a Giac function in the given arguments from a Giac symbol. EXAMPLES:: @@ -888,7 +884,7 @@ def __hash__(self): def _richcmp_(self, other, op): """ - Compare equality between self and other, using giac. + Compare equality between ``self`` and ``other``, using giac. These examples are optional, and require Giac to be installed. You do not need to install any Sage packages for this. @@ -1012,7 +1008,6 @@ def _latex_(self): sage: gf = giac('(x^4 - y)/(y^2-3*x)') sage: latex(gf) # output changed slightly from 1.5.0-63 to 1.5.0-87 \frac{...x^{4}...-...y...}{...y^{2}-3...x...} - """ s = self.parent().eval('latex(%s)' % self.name()) if s.startswith('"'): @@ -1145,19 +1140,17 @@ def _sage_(self, locals=None): def integral(self, var='x', min=None, max=None): r""" - Return the integral of self with respect to the variable x. + Return the integral of ``self`` with respect to the variable `x`. INPUT: + - ``var`` -- variable - - ``var`` -- variable - - - ``min`` -- default: None - - - ``max`` -- default: None + - ``min`` -- (default: ``None``) + - ``max`` -- (default: ``None``) - This returns the definite integral if xmin is not None, otherwise + This returns the definite integral if xmin is not ``None``, otherwise an indefinite integral. EXAMPLES:: @@ -1185,17 +1178,17 @@ def integral(self, var='x', min=None, max=None): def sum(self, var, min=None, max=None): r""" - Return the sum of self with respect to the variable x. + Return the sum of ``self`` with respect to the variable `x`. INPUT: - - ``var`` -- variable + - ``var`` -- variable - - ``min`` -- default: None + - ``min`` -- (default: ``None``) - - ``max`` -- default: None + - ``max`` -- (default: ``None``) - This returns the definite integral if xmin is not None, otherwise + This returns the definite integral if xmin is not ``None``, otherwise an indefinite integral. EXAMPLES:: diff --git a/src/sage/interfaces/gnuplot.py b/src/sage/interfaces/gnuplot.py index 3b3d7db7b9b..f9ddc8da914 100644 --- a/src/sage/interfaces/gnuplot.py +++ b/src/sage/interfaces/gnuplot.py @@ -63,22 +63,18 @@ def plot(self, cmd, file=None, verbose=True, reset=True): INPUT: + - ``cmd`` -- string - - ``cmd`` -- string + - ``file`` -- string (default: ``None``); if specified save + plot to given file, which may be either an eps (default) or png file - - ``file`` -- string (default: None), if specified save - plot to given file, which may be either an eps (default) or png - file. - - - ``verbose`` -- print some info - - - ``reset`` -- True: reset gnuplot before making - graph + - ``verbose`` -- print some info + - ``reset`` -- true; reset gnuplot before making graph OUTPUT: displays graph - .. note:: + .. NOTE:: Note that ``^`` s are replaced by ``**`` s before being passed to gnuplot. """ @@ -144,19 +140,18 @@ def plot3d_parametric(self, f='cos(u)*(3 + v*cos(u/2)), sin(u)*(3 + v*cos(u/2)), INPUT: - - ``f`` -- (string) a function of two variables, e.g., - 'cos(u)\*(3 + v\*cos(u/2)), sin(u)\*(3 + v\*cos(u/2)), - v\*sin(u/2)' + - ``f`` -- string; a function of two variables, e.g., + ``'cos(u)\*(3 + v\*cos(u/2)), sin(u)\*(3 + v\*cos(u/2)), v\*sin(u/2)'`` - - ``range1`` -- (string) range of values for one - variable, e.g., '[u=-pi:pi]' + - ``range1`` -- string; range of values for one + variable, e.g., ``'[u=-pi:pi]'`` - - ``range2`` -- (string) range of values for another - variable, e.g., '[v=-0.2:0.2]' + - ``range2`` -- string; range of values for another + variable, e.g., ``'[v=-0.2:0.2]'`` - - ``samples`` -- (int) number of sample points to use + - ``samples`` -- integer; number of sample points to use - - ``title`` -- (string) title of the graph. + - ``title`` -- string; title of the graph EXAMPLES:: @@ -181,7 +176,7 @@ def plot3d_parametric(self, f='cos(u)*(3 + v*cos(u/2)), sin(u)*(3 + v*cos(u/2)), def interact(self, cmd): import tempfile - with tempfile.NamedTemporaryFile(mode="w+t") as f: + with tempfile.NamedTemporaryFile(mode='w+t') as f: f.write(cmd + '\n pause -1 "Press return to continue (no further rotation possible)"') os.system(f'gnuplot -persist {f.name}') diff --git a/src/sage/interfaces/gp.py b/src/sage/interfaces/gp.py index 9459396d3e4..b98c050d889 100644 --- a/src/sage/interfaces/gp.py +++ b/src/sage/interfaces/gp.py @@ -167,14 +167,18 @@ class Gp(ExtraTabCompletion, Expect): INPUT: - - ``stacksize`` (int, default 10000000) -- the initial PARI - stacksize in bytes (default 10MB) - - ``script_subdirectory`` (string, default None) -- name of the subdirectory of SAGE_EXTCODE/pari from which to read scripts - - ``logfile`` (string, default None) -- log file for the pexpect interface + - ``stacksize`` -- integer (default: 10000000); the initial PARI + stacksize in bytes (default: 10MB) + - ``script_subdirectory`` -- string (default: ``None``); name of the + subdirectory of ``SAGE_EXTCODE/pari`` from which to read scripts + - ``logfile`` -- string (default: ``None``); log file for the pexpect + interface - ``server`` -- name of remote server - ``server_tmpdir`` -- name of temporary directory on remote server - - ``init_list_length`` (int, default 1024) -- length of initial list of local variables. - - ``seed`` (int, default random) -- random number generator seed for pari + - ``init_list_length`` -- integer (default: 1024); length of initial + list of local variables + - ``seed`` -- integer (default: random); random number generator seed + for pari EXAMPLES:: @@ -193,14 +197,18 @@ def __init__(self, stacksize=10000000, # 10MB INPUT: - - ``stacksize`` (int, default 10000000) -- the initial PARI - stacksize in bytes (default 10MB) - - ``script_subdirectory`` (string, default None) -- name of the subdirectory of SAGE_EXTCODE/pari from which to read scripts - - ``logfile`` (string, default None) -- log file for the pexpect interface + - ``stacksize`` -- integer (default: 10000000); the initial PARI + stacksize in bytes (default: 10MB) + - ``script_subdirectory`` -- string (default: ``None``); name of the + subdirectory of SAGE_EXTCODE/pari from which to read scripts + - ``logfile`` -- string (default: ``None``); log file for the pexpect + interface - ``server`` -- name of remote server - ``server_tmpdir`` -- name of temporary directory on remote server - - ``init_list_length`` (int, default 1024) -- length of initial list of local variables. - - ``seed`` (int,default random nonzero 31 bit integer) -- value of random seed + - ``init_list_length`` -- integer (default: 1024); length of initial + list of local variables. + - ``seed`` -- integer (default random nonzero 31 bit integer); value of + random seed EXAMPLES:: @@ -290,7 +298,7 @@ def __reduce__(self): def _function_class(self): """ - Returns the GpFunction class. + Return the GpFunction class. EXAMPLES:: @@ -303,7 +311,7 @@ def _function_class(self): def _quit_string(self): """ - Returns the string used to quit the GP interpreter. + Return the string used to quit the GP interpreter. EXAMPLES:: @@ -324,7 +332,7 @@ def _quit_string(self): def _read_in_file_command(self, filename): r""" - Returns the string used to read filename into GP. + Return the string used to read filename into GP. EXAMPLES:: @@ -376,7 +384,7 @@ def get_precision(self): def set_precision(self, prec): """ - Sets the PARI precision (in decimal digits) for real + Set the PARI precision (in decimal digits) for real computations, and returns the old value. .. NOTE:: @@ -415,7 +423,7 @@ def get_series_precision(self): def set_series_precision(self, prec=None): """ - Sets the PARI power series precision, and returns the old precision. + Set the PARI power series precision, and returns the old precision. EXAMPLES:: @@ -466,9 +474,8 @@ def cputime(self, t=None): INPUT: - - - ``t`` -- (default: None); if not None, then returns - time since t + - ``t`` -- (default: ``None``) if not None, then returns + time since t .. warning:: @@ -501,9 +508,9 @@ def set_default(self, var, value): INPUT: - - ``var`` (string) -- the name of a PARI gp - configuration variable. (See ``gp.default()`` for a list.) - - ``value`` -- the value to set the variable to. + - ``var`` -- string; the name of a PARI gp + configuration variable (see ``gp.default()`` for a list) + - ``value`` -- the value to set the variable to EXAMPLES:: @@ -526,12 +533,10 @@ def get_default(self, var): INPUT: - - ``var`` (string) -- the name of a PARI gp - configuration variable. (See ``gp.default()`` for a list.) - - OUTPUT: + - ``var`` -- string; the name of a PARI gp + configuration variable (see ``gp.default()`` for a list) - (string) the value of the variable. + OUTPUT: string; the value of the variable EXAMPLES:: @@ -553,7 +558,7 @@ def set(self, var, value): INPUT: - - ``var`` (string) -- a valid GP variable identifier + - ``var`` -- string; a valid GP variable identifier - ``value`` -- a value for the variable EXAMPLES:: @@ -573,7 +578,7 @@ def get(self, var): INPUT: - - ``var`` (string) -- a valid GP variable identifier + - ``var`` -- string; a valid GP variable identifier EXAMPLES:: @@ -589,7 +594,7 @@ def kill(self, var): INPUT: - - ``var`` (string) -- a valid GP variable identifier + - ``var`` -- string; a valid GP variable identifier EXAMPLES:: @@ -673,7 +678,7 @@ def console(self): def version(self): """ - Returns the version of GP being used. + Return the version of GP being used. EXAMPLES:: @@ -684,7 +689,7 @@ def version(self): def _object_class(self): """ - Returns the GpElement class. + Return the GpElement class. EXAMPLES:: @@ -697,7 +702,7 @@ def _object_class(self): def _function_element_class(self): """ - Returns the GpFunctionElement class. + Return the GpFunctionElement class. EXAMPLES:: @@ -710,7 +715,7 @@ def _function_element_class(self): def _true_symbol(self): """ - Returns the symbol used for truth in GP. + Return the symbol used for truth in GP. EXAMPLES:: @@ -726,7 +731,7 @@ def _true_symbol(self): def _false_symbol(self): """ - Returns the symbol used for falsity in GP. + Return the symbol used for falsity in GP. EXAMPLES:: @@ -742,7 +747,7 @@ def _false_symbol(self): def _equality_symbol(self): """ - Returns the symbol used for equality in GP. + Return the symbol used for equality in GP. EXAMPLES:: @@ -758,7 +763,7 @@ def _equality_symbol(self): def _exponent_symbol(self): """ - Returns the symbol to denote the exponent of a number in GP. + Return the symbol to denote the exponent of a number in GP. EXAMPLES:: @@ -775,7 +780,7 @@ def _exponent_symbol(self): def help(self, command): r""" - Returns GP's help for ``command``. + Return GP's help for ``command``. EXAMPLES:: @@ -786,7 +791,7 @@ def help(self, command): def new_with_bits_prec(self, s, precision=0): r""" - Creates a GP object from s with ``precision`` bits of + Create a GP object from s with ``precision`` bits of precision. GP actually automatically increases this precision to the nearest word (i.e. the next multiple of 32 on a 32-bit machine, or the next multiple of 64 on a 64-bit machine). @@ -955,11 +960,11 @@ def __bool__(self): def _complex_mpfr_field_(self, CC): """ - Return ComplexField element of self. + Return ComplexField element of ``self``. INPUT: - - ``CC`` -- a Complex or Real Field. + - ``CC`` -- a Complex or Real Field EXAMPLES:: @@ -982,7 +987,7 @@ def _complex_mpfr_field_(self, CC): def _complex_double_(self, CDF): """ - Returns this value as a CDF element. + Return this value as a CDF element. EXAMPLES:: @@ -1046,7 +1051,7 @@ def _tab_completion(self): def is_GpElement(x): """ - Return True if ``x`` is of type :class:`GpElement` + Return ``True`` if ``x`` is of type :class:`GpElement`. This function is deprecated; use :func:`isinstance` (of :class:`sage.interfaces.abc.GpElement`) instead. @@ -1074,7 +1079,7 @@ def is_GpElement(x): def reduce_load_GP(): """ - Returns the GP interface object defined in sage.interfaces.gp. + Return the GP interface object defined in ``sage.interfaces.gp``. EXAMPLES:: diff --git a/src/sage/interfaces/interface.py b/src/sage/interfaces/interface.py index 9b398ded62f..c15f0342de4 100644 --- a/src/sage/interfaces/interface.py +++ b/src/sage/interfaces/interface.py @@ -179,7 +179,7 @@ def interact(self): Press :kbd:`Ctrl` + :kbd:`D` or type 'quit' or 'exit' to exit and return to Sage. - .. note:: + .. NOTE:: This is completely different than the console() member function. The console function opens a new copy of the @@ -320,10 +320,10 @@ def __call__(self, x, name=None): def _coerce_from_special_method(self, x): """ - Tries to coerce to self by calling a special underscore method. + Try to coerce to ``self`` by calling a special underscore method. - If no such method is defined, raises an AttributeError instead of a - TypeError. + If no such method is defined, raises an :exc:`AttributeError` instead + of a :exc:`TypeError`. """ s = '_%s_' % self.name() if s == '_maxima_lib_': @@ -434,7 +434,7 @@ def _inequality_symbol(self): def _relation_symbols(self): """ - Returns a dictionary with operators as the keys and their + Return a dictionary with operators as the keys and their string representation as the values. EXAMPLES:: @@ -450,7 +450,7 @@ def _relation_symbols(self): def _exponent_symbol(self): """ - Return the symbol used to denote ``*10^`` in floats, e.g 'e' in 1.5e6 + Return the symbol used to denote ``*10^`` in floats, e.g 'e' in 1.5e6. EXAMPLES:: @@ -549,7 +549,7 @@ def _function_element_class(self): def _convert_args_kwds(self, args=None, kwds=None): """ - Converts all of the args and kwds to be elements of this + Convert all of the ``args`` and ``kwds`` to be elements of this interface. EXAMPLES:: @@ -579,7 +579,7 @@ def _convert_args_kwds(self, args=None, kwds=None): def _check_valid_function_name(self, function): """ - Checks to see if function is a valid function name in this + Check to see if function is a valid function name in this interface. If it is not, an exception is raised. Otherwise, nothing is done. @@ -618,7 +618,7 @@ def function_call(self, function, args=None, kwds=None): def _function_call_string(self, function, args, kwds): """ - Returns the string used to make function calls. + Return the string used to make function calls. EXAMPLES:: @@ -713,7 +713,7 @@ def _instancedoc_(self): def is_InterfaceElement(x): """ - Return True if ``x`` is of type :class:`InterfaceElement`. + Return ``True`` if ``x`` is of type :class:`InterfaceElement`. EXAMPLES:: @@ -789,7 +789,7 @@ def __len__(self): def __reduce__(self): """ - The default linearisation is to return self's parent, + The default linearisation is to return ``self``'s parent, which will then get the items returned by :meth:`_reduce` as arguments to reconstruct the element. @@ -843,7 +843,6 @@ def __reduce__(self): Traceback (most recent call last): ... TypeError: unable to make sense of Maxima expression '"abc"' in Sage - """ return self.parent(), (self._reduce(),) @@ -851,11 +850,11 @@ def _reduce(self): """ Helper for pickling. - By default, if self is a string, then the representation of + By default, if ``self`` is a string, then the representation of that string is returned (not the string itself). Otherwise, it is attempted to return the corresponding Sage object. - If this fails with a NotImplementedError, the string - representation of self is returned instead. + If this fails with a :exc:`NotImplementedError`, the string + representation of ``self`` is returned instead. EXAMPLES:: @@ -890,7 +889,6 @@ def _reduce(self): ....: # does not accidentally lead to success sage: loads(b) [1] "abc" - """ if self.is_string(): return repr(self.sage()) @@ -921,8 +919,8 @@ def _instancedoc_(self): def __hash__(self): """ - Returns the hash of self. This is a default implementation of hash - which just takes the hash of the string of self. + Return the hash of ``self``. This is a default implementation of hash + which just takes the hash of the string of ``self``. """ return hash('%s' % self) @@ -961,7 +959,6 @@ def _richcmp_(self, other, op): sage: gap('DihedralGroup(8)')==gap('DihedralGroup(8)') False - """ P = self._check_valid() try: @@ -1161,7 +1158,6 @@ def __repr__(self): sage: singular.quit() sage: s (invalid Singular object -- The singular session in which this object was defined is no longer running.) - """ try: self._check_valid() @@ -1217,7 +1213,6 @@ def _repr_(self): sage: mupad.package('"MuPAD-Combinat"') # optional - mupad-Combinat sage: S = mupad.examples.SymmetricFunctions(); S # optional - mupad-Combinat examples::SymmetricFunctions(Dom::ExpressionField()) - """ P = self.parent() try: @@ -1238,7 +1233,7 @@ def __getattr__(self, attrname): def get_using_file(self): """ Return this element's string representation using a file. Use this - if self has a huge string representation. It'll be way faster. + if ``self`` has a huge string representation. It'll be way faster. EXAMPLES:: @@ -1254,7 +1249,7 @@ def get_using_file(self): def hasattr(self, attrname): """ - Returns whether the given attribute is already defined by this + Return whether the given attribute is already defined by this object, and in particular is not dynamically generated. EXAMPLES:: @@ -1318,7 +1313,6 @@ def bool(self): False sage: singular(1).bool() True - """ return bool(self) @@ -1396,9 +1390,9 @@ def _rational_(self): def name(self, new_name=None): """ - Returns the name of self. If new_name is passed in, then this - function returns a new object identical to self whose name is - new_name. + Return the name of ``self``. If ``new_name`` is passed in, then this + function returns a new object identical to ``self`` whose name is + ``new_name``. Note that this can overwrite existing variables in the system. @@ -1447,11 +1441,11 @@ def _operation(self, operation, other=None): INPUT: - - ``operation`` -- a string representing the operation - being performed. For example, '*', or '1/'. + - ``operation`` -- string representing the operation + being performed; for example, '*', or '1/' - - ``other`` -- the other operand. If ``other`` is ``None``, - then the operation is assumed to be unary rather than binary. + - ``other`` -- the other operand; if ``other`` is ``None``, + then the operation is assumed to be unary rather than binary OUTPUT: an interface element diff --git a/src/sage/interfaces/jmoldata.py b/src/sage/interfaces/jmoldata.py index add4b453b3d..f8f497172b9 100644 --- a/src/sage/interfaces/jmoldata.py +++ b/src/sage/interfaces/jmoldata.py @@ -52,7 +52,7 @@ def __init__(self): def is_jvm_available(self): """ - Returns True if the Java Virtual Machine is available and False if not. + Return ``True`` if the Java Virtual Machine is available and ``False`` if not. EXAMPLES: @@ -81,7 +81,6 @@ def jmolpath(self): sage: JData = JmolData() sage: JData.jmolpath() # needs jmol '.../JmolData.jar' - """ jmolpath = JmolDataJar().absolute_filename() @@ -89,7 +88,7 @@ def jmolpath(self): def is_jmol_available(self): """ - Returns True if jmol is available and False if not. + Return ``True`` if jmol is available and ``False`` if not. EXAMPLES: @@ -120,24 +119,22 @@ def export_image(self, INPUT: - - targetfile -- the full path to the file where the image - should be written. - - - datafile -- full path to the data file Jmol can read or - text of a script telling Jmol what to read or load. + - ``targetfile`` -- the full path to the file where the image + should be written - - datafile_cmd -- (default ``'script'``) ``'load'`` or ``'script'`` - should be ``"load"`` for a data file. + - ``datafile`` -- full path to the data file Jmol can read or + text of a script telling Jmol what to read or load - - image_type -- (default ``"PNG"``) ``'PNG'`` ``'JPG'`` or ``'GIF'`` + - ``datafile_cmd`` -- (default: ``'script'``) ``'load'`` or ``'script'`` + should be ``'load'`` for a data file - - figsize -- number (default 5) equal to (pixels/side)/100 + - ``image_type`` -- (default: ``"PNG"``) ``'PNG'`` ``'JPG'`` or ``'GIF'`` - OUTPUT: + - ``figsize`` -- number (default: 5) equal to (pixels/side)/100 - Image file, .png, .gif or .jpg (default .png) + OUTPUT: image file, .png, .gif or .jpg (default: .png) - .. note:: + .. NOTE:: Examples will generate an error message if a functional Java Virtual Machine (JVM) is not installed on the machine the Sage instance is running on. @@ -147,7 +144,7 @@ def export_image(self, Programmers using this module should check that the JVM is available before making calls to avoid the user getting error messages. Check for the JVM using the function - :meth:`is_jvm_available`, which returns True if a JVM is available. + :meth:`is_jvm_available`, which returns ``True`` if a JVM is available. EXAMPLES: @@ -171,12 +168,12 @@ def export_image(self, sage: JData = JmolData() sage: D = dodecahedron() # needs sage.plot sage: from tempfile import NamedTemporaryFile - sage: archive = NamedTemporaryFile(suffix=".zip") + sage: archive = NamedTemporaryFile(suffix='.zip') sage: D.export_jmol(archive.name) # needs sage.plot sage: archive_native = archive.name sage: script = f'set defaultdirectory "f{archive_native}"\n' sage: script += 'script SCRIPT\n' - sage: with NamedTemporaryFile(suffix=".png") as testfile: # optional - java, needs sage.plot + sage: with NamedTemporaryFile(suffix='.png') as testfile: # optional - java, needs sage.plot ....: JData.export_image(targetfile=testfile.name, ....: datafile=script, ....: image_type="PNG") @@ -196,7 +193,7 @@ def export_image(self, imagescript = 'write {} {!r}\n'.format(image_type, target_native) size_arg = "%sx%s" % (figsize * 100, figsize * 100) # Scratch file for Jmol errors - scratchout = tmp_filename(ext=".txt") + scratchout = tmp_filename(ext='.txt') with open(scratchout, 'w') as jout: # Now call the java application and write the file. env = dict(os.environ) diff --git a/src/sage/interfaces/kash.py b/src/sage/interfaces/kash.py index c86180e920b..ddcc2128588 100644 --- a/src/sage/interfaces/kash.py +++ b/src/sage/interfaces/kash.py @@ -142,7 +142,7 @@ ext1 := 1, ext2 := Unassign -.. note:: +.. NOTE:: For some very large numbers KASH's integer factorization seems much faster than PARI's (which is the default in Sage). @@ -405,7 +405,7 @@ The KASH interface reads in even very long input (using files) in a robust manner, as long as you are creating a new object. -.. note:: +.. NOTE:: Using ``kash.eval`` for long input is much less robust, and is not recommended. @@ -460,11 +460,12 @@ def __init__(self, server_tmpdir=None): """ INPUT: - max_workspace_size -- (default: None) - set maximal workspace memory usage to - stands for byte-wise allocation - k stands for kilobyte-wise allocation - m stands for megabyte-wise allocation + + - ``max_workspace_size`` -- (default: ``None``) + set maximal workspace memory usage to + stands for byte-wise allocation + k stands for kilobyte-wise allocation + m stands for megabyte-wise allocation """ cmd = "kash3 -b -c -d " if max_workspace_size is not None: @@ -541,14 +542,12 @@ def eval(self, x, newlines=False, strip=True, **kwds): INPUT: + - ``s`` -- string containing Kash code - - ``s`` -- string containing Kash code. - - - ``newlines`` -- bool (default: ``True``); if False, - remove all backslash-newlines inserted by the Kash output - formatter. + - ``newlines`` -- boolean (default: ``True``); if ``False``, + remove all backslash-newlines inserted by the Kash output formatter - - ``strip`` -- ignored + - ``strip`` -- ignored """ x = str(x) x = x.rstrip() @@ -763,7 +762,6 @@ def _sage_(self, locals={}, *args): sage541.1^2 + sage541.1 sage: ka.sage({kR.1: x}) # optional -- kash x^2 + x - """ string = self._sage_repr() @@ -791,7 +789,7 @@ def __repr__(self): def is_KashElement(x): """ - Returns True if ``x`` is of type :class:`KashElement`. + Return ``True`` if ``x`` is of type :class:`KashElement`. EXAMPLES:: diff --git a/src/sage/interfaces/kenzo.py b/src/sage/interfaces/kenzo.py index 16d4bb25708..85d4e82772d 100644 --- a/src/sage/interfaces/kenzo.py +++ b/src/sage/interfaces/kenzo.py @@ -119,15 +119,13 @@ def Sphere(n): r""" - Return the ``n`` dimensional sphere as a Kenzo simplicial set. + Return the `n` dimensional sphere as a Kenzo simplicial set. INPUT: - ``n`` -- the dimension of the sphere - OUTPUT: - - - A :class:`KenzoSimplicialSet` + OUTPUT: a :class:`KenzoSimplicialSet` EXAMPLES:: @@ -145,21 +143,19 @@ def Sphere(n): def MooreSpace(m, n): r""" - Return the Moore space ``M(m, n)`` as a Kenzo simplicial set. + Return the Moore space `M(m, n)` as a Kenzo simplicial set. - The Moore space ``M(m, n)`` is the space whose n'th homology group - is isomorphic to the cyclic group of order ``m``, and the rest of the + The Moore space `M(m, n)` is the space whose `n`-th homology group + is isomorphic to the cyclic group of order `m`, and the rest of the homology groups are trivial. INPUT: - - ``m`` -- A positive integer. The order of the nontrivial homology group. - - - ``n`` -- The dimension in which the homology is not trivial + - ``m`` -- positive integer; the order of the nontrivial homology group - OUTPUT: + - ``n`` -- the dimension in which the homology is not trivial - - A KenzoSimplicialSet + OUTPUT: a KenzoSimplicialSet EXAMPLES:: @@ -184,14 +180,12 @@ def EilenbergMacLaneSpace(G, n): INPUT: - - ``G`` -- group. Currently only ``ZZ`` and the additive group of two - elements are supported. + - ``G`` -- group; currently only ``ZZ`` and the additive group of two + elements are supported - ``n`` -- the dimension in which the homotopy is not trivial - OUTPUT: - - - A :class:`KenzoSimplicialGroup` + OUTPUT: a :class:`KenzoSimplicialGroup` EXAMPLES:: @@ -219,12 +213,12 @@ def EilenbergMacLaneSpace(G, n): class KenzoObject(SageObject): r""" - Wrapper to Kenzo objects + Wrapper to Kenzo objects. INPUT: - ``kenzo_object`` -- a wrapper around a Kenzo object - (which is an ecl object). + (which is an ecl object) """ def __init__(self, kenzo_object): @@ -243,7 +237,6 @@ def __init__(self, kenzo_object): sage: s2 [K1 Simplicial-Set] sage: TestSuite(s2).run(skip='_test_pickling') - """ self._kenzo = kenzo_object @@ -272,15 +265,15 @@ class KenzoSpectralSequence(KenzoObject): def group(self, p, i, j): r""" - Return the ``i,j``'th group of the ``p`` page. + Return the ``i,j``-th group of the ``p`` page. INPUT: - - ``p`` -- the page to take the group from. + - ``p`` -- the page to take the group from - - ``i`` -- the column where the group is taken from. + - ``i`` -- the column where the group is taken from - - ``j`` -- the row where the group is taken from. + - ``j`` -- the row where the group is taken from EXAMPLES:: @@ -301,15 +294,15 @@ def group(self, p, i, j): def matrix(self, p, i, j): r""" Return the matrix that determines the differential from the - ``i,j``'th group of the ``p``'th page. + ``i,j``-th group of the ``p``-th page. INPUT: - - ``p`` -- the page. + - ``p`` -- the page - - ``i`` -- the column of the differential domain. + - ``i`` -- the column of the differential domain - - ``j`` -- the row of the differential domain. + - ``j`` -- the row of the differential domain EXAMPLES:: @@ -342,11 +335,11 @@ def differential(self, p, i, j): INPUT: - - ``p`` -- the page. + - ``p`` -- the page - - ``i`` -- the column of the differential domain. + - ``i`` -- the column of the differential domain - - ``j`` -- the row of the differential domain. + - ``j`` -- the row of the differential domain EXAMPLES:: @@ -377,15 +370,15 @@ def table(self, p, i1, i2, j1, j2): INPUT: - - ``p`` -- the page to print. + - ``p`` -- the page to print - -- ``i1`` -- the first column to print. + -- ``i1`` -- the first column to print - -- ``i2`` -- the last column to print. + -- ``i2`` -- the last column to print - -- ``j1`` -- the first row to print. + -- ``j1`` -- the first row to print - -- ``j2`` -- the last row to print. + -- ``j2`` -- the last row to print EXAMPLES:: @@ -421,16 +414,14 @@ class KenzoChainComplex(KenzoObject): """ def homology(self, n): r""" - Return the ``n``'th homology group of the chain complex associated to this + Return the `n`-th homology group of the chain complex associated to this kenzo object. INPUT: - ``n`` -- the dimension in which compute the homology - OUTPUT: - - - A homology group. + OUTPUT: a homology group EXAMPLES:: @@ -459,11 +450,9 @@ def tensor_product(self, other): INPUT: - - ``other`` -- The Kenzo object with which to compute the tensor product - - OUTPUT: + - ``other`` -- The Kenzo object with which to compute the tensor product - - A :class:`KenzoChainComplex` + OUTPUT: a :class:`KenzoChainComplex` EXAMPLES:: @@ -486,11 +475,9 @@ def basis(self, dim): INPUT: - - ``dim`` -- An integer number - - OUTPUT: + - ``dim`` -- integer - - A list of the form ['G"dim"G0', 'G"dim"G1', 'G"dim"G2', ...]. + OUTPUT: list of the form ['G"dim"G0', 'G"dim"G1', 'G"dim"G2', ...] EXAMPLES:: @@ -518,9 +505,7 @@ def identity_morphism(self): r""" Return the identity morphism (degree 0) between ``self`` and itself. - OUTPUT: - - - A :class:`KenzoChainComplexMorphism` + OUTPUT: a :class:`KenzoChainComplexMorphism` EXAMPLES:: @@ -541,14 +526,14 @@ def null_morphism(self, target=None, degree=None): INPUT: - - ``target`` -- A KenzoChainComplex or None (default). - - ``degree`` -- An integer number or None (default). + - ``target`` -- a KenzoChainComplex or ``None`` (default) + - ``degree`` -- integer or ``None`` (default) OUTPUT: - A :class:`KenzoChainComplexMorphism` representing the null morphism between - ``self`` and ``target`` of degree ``degree``. If ``target`` takes None value, - ``self`` is assumed as the target chain complex; if ``degree`` takes None value, + ``self`` and ``target`` of degree ``degree``. If ``target`` takes ``None`` value, + ``self`` is assumed as the target chain complex; if ``degree`` takes ``None`` value, 0 is assumed as the degree of the null morphism. EXAMPLES:: @@ -587,10 +572,10 @@ def differential(self, dim=None, comb=None): INPUT: - - ``dim`` -- An integer number or None (default) + - ``dim`` -- integer or ``None`` (default) - - ``comb`` -- A list representing a formal sum of generators in the module - of dimension ``dim`` or None (default). For example, to represent + - ``comb`` -- list representing a formal sum of generators in the module + of dimension ``dim`` or ``None`` (default). For example, to represent G7G12 + 3*G7G0 - 5*G7G3 we use the list [3, 'G7G0', -5, 'G7G3', 1, 'G7G12']. Note that the generators must be in ascending order respect to the number after the second G in their representation; the parameter @@ -599,10 +584,10 @@ def differential(self, dim=None, comb=None): OUTPUT: - - If ``dim`` and ``comb`` are not None, it returns a Kenzo combination + - If ``dim`` and ``comb`` are not ``None``, it returns a Kenzo combination representing the differential of the formal combination represented by ``comb`` in the chain complex ``self`` in dimension ``dim``. On the other - hand, if `dim`` or ``comb`` (or both) take None value, the differential + hand, if ``dim`` or ``comb`` (or both) take ``None`` value, the differential :class:`KenzoMorphismChainComplex` of ``self`` is returned. EXAMPLES:: @@ -643,7 +628,7 @@ def differential(self, dim=None, comb=None): def orgn(self): r""" - Return the :orgn slot of Kenzo, which stores as a list the origin of the object + Return the :orgn slot of Kenzo, which stores as a list the origin of the object. EXAMPLES:: @@ -670,16 +655,14 @@ class KenzoSimplicialSet(KenzoChainComplex): def loop_space(self, n=1): r""" - Return the ``n`` th iterated loop space. + Return the `n`-th iterated loop space. INPUT: - ``n`` -- (default: 1) the number of times to iterate the loop space construction - OUTPUT: - - - A :class:`KenzoSimplicialGroup` + OUTPUT: a :class:`KenzoSimplicialGroup` EXAMPLES:: @@ -703,9 +686,7 @@ def cartesian_product(self, other): - ``other`` -- the Kenzo simplicial set with which the product is made - OUTPUT: - - - A :class:`KenzoSimplicialSet` + OUTPUT: a :class:`KenzoSimplicialSet` EXAMPLES:: @@ -726,9 +707,7 @@ def suspension(self): r""" Return the suspension of the simplicial set. - OUTPUT: - - - A :class:`KenzoSimplicialSet` + OUTPUT: a :class:`KenzoSimplicialSet` EXAMPLES:: @@ -745,7 +724,7 @@ def suspension(self): def homotopy_group(self, n): """ - Return the n'th homotopy group of ``self`` + Return the `n`-th homotopy group of ``self``. INPUT: @@ -780,9 +759,7 @@ def em_spectral_sequence(self): r""" Return the Eilenberg-Moore spectral sequence of ``self``. - OUTPUT: - - - A :class:`KenzoSpectralSequence` + OUTPUT: a :class:`KenzoSpectralSequence` EXAMPLES:: @@ -812,9 +789,7 @@ def sw_spectral_sequence(self): r""" Return the Serre sequence of the first step of the Whitehead tower. - OUTPUT: - - - A :class:`KenzoSpectralSequence` + OUTPUT: a :class:`KenzoSpectralSequence` EXAMPLES:: @@ -839,11 +814,9 @@ def serre_spectral_sequence(self): r""" Return the spectral sequence of ``self``. - The object self must be created as a cartesian product (twisted or not). - - OUTPUT: + The object ``self`` must be created as a cartesian product (twisted or not). - - A :class:`KenzoSpectralSequence` + OUTPUT: a :class:`KenzoSpectralSequence` EXAMPLES:: @@ -877,9 +850,7 @@ def wedge(self, other): - ``other`` -- the Kenzo simplicial set with which the wedge is made - OUTPUT: - - - A :class:`KenzoSimplicialSet` + OUTPUT: a :class:`KenzoSimplicialSet` EXAMPLES:: @@ -904,9 +875,7 @@ def join(self, other): - ``other`` -- the Kenzo simplicial set with which the join is made - OUTPUT: - - - A :class:`KenzoSimplicialSet` + OUTPUT: a :class:`KenzoSimplicialSet` EXAMPLES:: @@ -931,9 +900,7 @@ def smash_product(self, other): - ``other`` -- the Kenzo simplicial set with which the smash product is made - OUTPUT: - - - A :class:`KenzoSimplicialSet` + OUTPUT: a :class:`KenzoSimplicialSet` EXAMPLES:: @@ -960,9 +927,7 @@ def classifying_space(self): r""" Return the classifying space. - OUTPUT: - - - A :class:`KenzoSimplicialGroup` + OUTPUT: a :class:`KenzoSimplicialGroup` EXAMPLES:: @@ -985,7 +950,7 @@ def k2s_matrix(kmatrix): INPUT: - - ``kmatrix`` -- An array in ECL + - ``kmatrix`` -- an array in ECL EXAMPLES:: @@ -1008,11 +973,9 @@ def s2k_matrix(smatrix): INPUT: - - ``smatrix`` -- A matrix in Sage + - ``smatrix`` -- a matrix in Sage - OUTPUT: - - - A :class:`EclObject` + OUTPUT: a :class:`EclObject` EXAMPLES:: @@ -1035,11 +998,9 @@ def s2k_dictmat(sdictmat): INPUT: - - ``sdictmat`` -- A dictionary in Sage - - OUTPUT: + - ``sdictmat`` -- dictionary in Sage - - A :class:`EclObject` + OUTPUT: a :class:`EclObject` EXAMPLES:: @@ -1049,7 +1010,6 @@ def s2k_dictmat(sdictmat): sage: d = {1 : A, 2 : B} sage: s2k_dictmat(d) # optional - kenzo - """ rslt = EclObject([]) for k in sdictmat.keys(): @@ -1063,11 +1023,9 @@ def pairing(slist): INPUT: - - ``slist`` -- A list in Sage + - ``slist`` -- list in Sage - OUTPUT: - - - A :class:`EclObject` + OUTPUT: a :class:`EclObject` EXAMPLES:: @@ -1084,16 +1042,14 @@ def pairing(slist): def KChainComplex(chain_complex): r""" - Construct a KenzoChainComplex from a ChainComplex of degree = -1 in + Construct a KenzoChainComplex from a ChainComplex of degree `-1` in Sage. INPUT: - - ``chain_complex`` -- A ChainComplex of degree = -1 - - OUTPUT: + - ``chain_complex`` -- a ChainComplex of degree `-1` - - A KenzoChainComplex + OUTPUT: a KenzoChainComplex EXAMPLES:: @@ -1122,15 +1078,13 @@ def SChainComplex(kchaincomplex, start=0, end=15): INPUT: - - ``kchaincomplex`` -- A KenzoChainComplex + - ``kchaincomplex`` -- a KenzoChainComplex - - ``start`` -- An integer number (default: 0) + - ``start`` -- integer (default: 0) - - ``end`` -- An integer number greater than or equal to ``start`` (default: 15) + - ``end`` -- integer greater than or equal to ``start`` (default: 15) - OUTPUT: - - - A ChainComplex + OUTPUT: a ChainComplex EXAMPLES:: @@ -1173,13 +1127,11 @@ def SAbstractSimplex(simplex, dim): INPUT: - - ``simplex`` -- An abstract simplex of Kenzo. - - - ``dim`` -- The dimension of ``simplex``. + - ``simplex`` -- an abstract simplex of Kenzo - OUTPUT: + - ``dim`` -- the dimension of ``simplex`` - - An AbstractSimplex. + OUTPUT: an AbstractSimplex EXAMPLES:: @@ -1212,11 +1164,9 @@ def KAbstractSimplex(simplex): INPUT: - - ``simplex`` -- An AbstractSimplex. + - ``simplex`` -- an AbstractSimplex - OUTPUT: - - - An abstract simplex of Kenzo. + OUTPUT: an abstract simplex of Kenzo EXAMPLES:: @@ -1242,11 +1192,9 @@ def KFiniteSimplicialSet(sset): INPUT: - - ``sset`` -- A finite SimplicialSet. - - OUTPUT: + - ``sset`` -- a finite SimplicialSet - - A finite simplicial set of Kenzo. + OUTPUT: a finite simplicial set of Kenzo EXAMPLES:: @@ -1309,13 +1257,11 @@ def SFiniteSimplicialSet(ksimpset, limit): INPUT: - - ``ksimpset`` -- A finite simplicial set in Kenzo. - - - ``limit`` -- A natural number. + - ``ksimpset`` -- a finite simplicial set in Kenzo - OUTPUT: + - ``limit`` -- a natural number - - A finite SimplicialSet. + OUTPUT: a finite SimplicialSet EXAMPLES:: @@ -1392,9 +1338,7 @@ def source_complex(self): r""" Return the source chain complex of the morphism. - OUTPUT: - - - A :class:`KenzoChainComplex` + OUTPUT: a :class:`KenzoChainComplex` EXAMPLES:: @@ -1419,9 +1363,7 @@ def target_complex(self): r""" Return the target chain complex of the morphism. - OUTPUT: - - - A :class:`KenzoChainComplex` + OUTPUT: a :class:`KenzoChainComplex` EXAMPLES:: @@ -1446,9 +1388,7 @@ def degree(self): r""" Return the degree of the morphism. - OUTPUT: - - - An integer number, the degree of the morphism. + OUTPUT: integer; the degree of the morphism EXAMPLES:: @@ -1479,9 +1419,9 @@ def evaluation(self, dim, comb): INPUT: - - ``dim`` -- An integer number + - ``dim`` -- integer - - ``comb`` -- A list representing a formal sum of generators in the module + - ``comb`` -- list representing a formal sum of generators in the module of dimension ``dim``. For example, to represent G7G12 + 3*G7G0 - 5*G7G3 we use the list [3, 'G7G0', -5, 'G7G3', 1, 'G7G12']. Note that the generators must be in ascending order respect to the number after the @@ -1563,9 +1503,7 @@ def opposite(self): r""" Return the opposite morphism of ``self``, i.e., -1 x ``self``. - OUTPUT: - - - A :class:`KenzoChainComplexMorphism` + OUTPUT: a :class:`KenzoChainComplexMorphism` EXAMPLES:: @@ -1609,8 +1547,9 @@ def composite(self, object=None): INPUT: - - ``object`` -- A KenzoChainComplexMorphism instance, a KenzoChainComplex instance, a tuple - of KenzoChainComplexMorphism and KenzoChainComplex instances, or None (default). + - ``object`` -- a KenzoChainComplexMorphism instance, a + KenzoChainComplex instance, a tuple of KenzoChainComplexMorphism and + KenzoChainComplex instances, or ``None`` (default). OUTPUT: @@ -1619,7 +1558,7 @@ def composite(self, object=None): the composite of ``self`` and the differential morphism of ``object`` is returned; if ``object`` is a tuple, the composite of ``self`` and the morphisms or the differential morphisms of the given chain complexes in ``object`` is returned (if ``object`` is - None, ``self`` morphism is returned). + ``None``, ``self`` morphism is returned). EXAMPLES:: @@ -1657,13 +1596,14 @@ def sum(self, object=None): INPUT: - - ``object`` -- A KenzoChainComplexMorphism instance, a tuple of KenzoChainComplexMorphism - instances or None (default). + - ``object`` -- a KenzoChainComplexMorphism instance, a tuple of + KenzoChainComplexMorphism instances or ``None`` (default) OUTPUT: - - A :class:`KenzoChainComplexMorphism`, sum of the morphism ``self`` and the morphism(s) - given by ``object`` (if ``object`` is None, ``self`` morphism is returned). + A :class:`KenzoChainComplexMorphism`, sum of the morphism ``self`` + and the morphism(s given by ``object`` (if ``object`` is ``None``, + ``self`` morphism is returned). EXAMPLES:: @@ -1717,20 +1657,20 @@ def sum(self, object=None): def substract(self, object=None): r""" - Return a morphism, difference of the morphism ``self`` and the morphism(s) given by the - parameter ``object``. + Return a morphism, difference of the morphism ``self`` and the + morphism(s) given by the parameter ``object``. INPUT: - - ``object`` -- A KenzoChainComplexMorphism instance, a tuple of KenzoChainComplexMorphism - instances or None (default). + - ``object`` -- a KenzoChainComplexMorphism instance, a tuple of + KenzoChainComplexMorphism instances or ``None`` (default) OUTPUT: - - A :class:`KenzoChainComplexMorphism`, difference of the morphism ``self`` and the - morphism(s) given by ``object`` (if ``object`` is None, ``self`` morphism is returned). - For example, if ``object`` = (mrph1, mrph2, mrph3) the result is - ``self`` - mrph1 - mrph2 - mrph3. + A :class:`KenzoChainComplexMorphism`, difference of the morphism + ``self`` and the morphism(s) given by ``object`` (if ``object`` is + ``None``, ``self`` morphism is returned). For example, if ``object`` = + (mrph1, mrph2, mrph3) the result is ``self`` - mrph1 - mrph2 - mrph3. EXAMPLES:: @@ -1789,9 +1729,9 @@ def change_source_target_complex(self, source=None, target=None): INPUT: - - ``source`` -- A KenzoChainComplex instance or None (default). + - ``source`` -- a KenzoChainComplex instance or ``None`` (default) - - ``target`` -- A KenzoChainComplex instance or None (default). + - ``target`` -- a KenzoChainComplex instance or ``None`` (default) OUTPUT: @@ -1838,9 +1778,9 @@ def destructive_change_source_target_complex(self, source=None, target=None): INPUT: - - ``source`` -- A KenzoChainComplex instance or None (default). + - ``source`` -- a KenzoChainComplex instance or ``None`` (default) - - ``target`` -- A KenzoChainComplex instance or None (default). + - ``target`` -- a KenzoChainComplex instance or ``None`` (default) OUTPUT: @@ -1884,24 +1824,22 @@ def build_morphism(source_complex, target_complex, degree, algorithm, strategy, INPUT: - - ``source_complex`` -- The source object as a KenzoChainComplex instance + - ``source_complex`` -- the source object as a KenzoChainComplex instance - - ``target_complex`` -- The target object as a KenzoChainComplex instance + - ``target_complex`` -- the target object as a KenzoChainComplex instance - - ``degree`` -- An integer number representing the degree of the morphism + - ``degree`` -- integer representing the degree of the morphism - - ``algorithm`` -- A Lisp function defining the mapping (:intr slot in Kenzo) + - ``algorithm`` -- a Lisp function defining the mapping (:intr slot in Kenzo) - - ``strategy`` -- The strategy (:strt slot in Kenzo), which must be one of + - ``strategy`` -- the strategy (:strt slot in Kenzo), which must be one of the two strings ``gnrt`` or ``cmbn``, depending if the ``algorithm`` (a Lisp function) uses as arguments a degree and a generator or a combination, respectively. - - ``orgn`` -- A list containing a description about the origin of the morphism - - OUTPUT: + - ``orgn`` -- list containing a description about the origin of the morphism - - A :class:`KenzoChainComplexMorphism` + OUTPUT: a :class:`KenzoChainComplexMorphism` EXAMPLES:: @@ -1928,15 +1866,13 @@ def build_morphism(source_complex, target_complex, degree, algorithm, strategy, def morphism_dictmat(morphism): r""" - Computes a list of matrices in ECL associated to a morphism in Sage. + Compute a list of matrices in ECL associated to a morphism in Sage. INPUT: - - ``morphism`` -- A morphism of chain complexes - - OUTPUT: + - ``morphism`` -- a morphism of chain complexes - - A :class:`EclObject` + OUTPUT: a :class:`EclObject` EXAMPLES:: @@ -1962,11 +1898,9 @@ def KChainComplexMorphism(morphism): INPUT: - - ``morphism`` -- A morphism of chain complexes + - ``morphism`` -- a morphism of chain complexes - OUTPUT: - - - A :class:`KenzoChainComplexMorphism` + OUTPUT: a :class:`KenzoChainComplexMorphism` EXAMPLES:: @@ -1991,15 +1925,13 @@ def KChainComplexMorphism(morphism): def s2k_listofmorphisms(l): r""" - Computes a list of morphisms of chain complexes in Kenzo from a list of morphisms in Sage. + Compute a list of morphisms of chain complexes in Kenzo from a list of morphisms in Sage. INPUT: - - ``l`` -- A list of morphisms of chain complexes - - OUTPUT: + - ``l`` -- list of morphisms of chain complexes - - A :class:`EclObject` + OUTPUT: a :class:`EclObject` EXAMPLES:: @@ -2025,11 +1957,9 @@ def BicomplexSpectralSequence(l): INPUT: - - ``l`` -- A list of morphisms of chain complexes - - OUTPUT: + - ``l`` -- list of morphisms of chain complexes - - A :class:`KenzoSpectralSequence` + OUTPUT: a :class:`KenzoSpectralSequence` EXAMPLES:: diff --git a/src/sage/interfaces/latte.py b/src/sage/interfaces/latte.py index 6923be55d53..3d78543257c 100644 --- a/src/sage/interfaces/latte.py +++ b/src/sage/interfaces/latte.py @@ -21,13 +21,13 @@ def count(arg, ehrhart_polynomial=False, multivariate_generating_function=False, raw_output=False, verbose=False, **kwds): r""" - Call to the program count from LattE integrale + Call to the program count from LattE integrale. INPUT: - ``arg`` -- a cdd or LattE description string - - ``ehrhart_polynomial``, ``multivariate_generating_function`` -- to + - ``ehrhart_polynomial``, ``multivariate_generating_function`` -- to compute Ehrhart polynomial or multivariate generating function instead of just counting points @@ -222,23 +222,21 @@ def integrate(arg, polynomial=None, algorithm='triangulate', raw_output=False, v INPUT: - - ``arg`` -- a cdd or LattE description string. - - - ``polynomial`` -- multivariate polynomial or valid LattE polynomial description string. - If given, the valuation parameter of LattE is set to integrate, and is set to volume otherwise. + - ``arg`` -- a cdd or LattE description string - - ``algorithm`` -- (default: 'triangulate') the integration method. Use 'triangulate' for - polytope triangulation or 'cone-decompose' for tangent cone decomposition method. + - ``polynomial`` -- multivariate polynomial or valid LattE polynomial description string + If given, the valuation parameter of LattE is set to integrate, and is set to volume otherwise - - ``raw_output`` -- if ``True`` then return directly the output string from LattE. + - ``algorithm`` -- (default: ``'triangulate'``) the integration method; use 'triangulate' for + polytope triangulation or 'cone-decompose' for tangent cone decomposition method - - ``verbose`` -- if ``True`` then return directly verbose output from LattE. + - ``raw_output`` -- if ``True`` then return directly the output string from LattE - - For all other options of the integrate program, consult the LattE manual. + - ``verbose`` -- if ``True`` then return directly verbose output from LattE - OUTPUT: + - For all other options of the integrate program, consult the LattE manual - Either a string (if ``raw_output`` if set to ``True``) or a rational. + OUTPUT: either a string (if ``raw_output`` if set to ``True``) or a rational EXAMPLES:: @@ -425,11 +423,9 @@ def to_latte_polynomial(polynomial): INPUT: - - ``polynomial`` -- a multivariate polynomial. - - OUTPUT: + - ``polynomial`` -- a multivariate polynomial - A string that describes the monomials list and exponent vectors. + OUTPUT: string that describes the monomials list and exponent vectors TESTS: diff --git a/src/sage/interfaces/lie.py b/src/sage/interfaces/lie.py index 71413162fd5..1824d2efcdb 100644 --- a/src/sage/interfaces/lie.py +++ b/src/sage/interfaces/lie.py @@ -17,7 +17,6 @@ To access the LiE interpreter directly, run lie_console(). - EXAMPLES:: sage: a4 = lie('A4') # optional - lie @@ -805,7 +804,6 @@ def _sage_(self): [ 3 -5 -2 9] sage: lie('-1X[1,1]').sage() # optional - lie -x0*x1 - """ t = self.type() if t == 'grp': diff --git a/src/sage/interfaces/lisp.py b/src/sage/interfaces/lisp.py index 158ed0f91c7..a324d7b76a8 100644 --- a/src/sage/interfaces/lisp.py +++ b/src/sage/interfaces/lisp.py @@ -82,7 +82,7 @@ def __init__(self, prompt='> ', # This is the command that starts up your program - command="ecl", + command='ecl', server=server, server_tmpdir=server_tmpdir, @@ -291,7 +291,7 @@ def console(self): def version(self): """ - Returns the version of Lisp being used. + Return the version of Lisp being used. EXAMPLES:: @@ -342,9 +342,9 @@ def _false_symbol(self): def _equality_symbol(self): """ - We raise a NotImplementedError when _equality_symbol is called since - equality testing in Lisp does not use infix notation and cannot be - done the same way as in the other interfaces. + We raise a :exc:`NotImplementedError` when ``_equality_symbol`` is + called since equality testing in Lisp does not use infix notation and + cannot be done the same way as in the other interfaces. EXAMPLES:: @@ -369,8 +369,8 @@ def help(self, command): def function_call(self, function, args=None, kwds=None): """ - Calls the Lisp function with given args and kwds. - For Lisp functions, the kwds are ignored. + Call the Lisp function with given ``args`` and ``kwds``. + For Lisp functions, the ``kwds`` are ignored. EXAMPLES:: @@ -404,7 +404,6 @@ def _richcmp_(self, other, op): False sage: two == 2 True - """ P = self._check_valid() if parent(other) is not P: diff --git a/src/sage/interfaces/macaulay2.py b/src/sage/interfaces/macaulay2.py index 866ef8e1fbf..da15f7c26e4 100644 --- a/src/sage/interfaces/macaulay2.py +++ b/src/sage/interfaces/macaulay2.py @@ -14,13 +14,13 @@ The Macaulay2 interface offers three pieces of functionality: -- ``macaulay2_console()`` -- A function that dumps you - into an interactive command-line Macaulay2 session. +- ``macaulay2_console()`` -- a function that dumps you + into an interactive command-line Macaulay2 session -- ``macaulay2.eval(expr)`` -- Evaluation of arbitrary Macaulay2 - expressions, with the result returned as a string. +- ``macaulay2.eval(expr)`` -- evaluation of arbitrary Macaulay2 + expressions, with the result returned as a string -- ``macaulay2(expr)`` -- Creation of a Sage object that wraps a +- ``macaulay2(expr)`` -- creation of a Sage object that wraps a Macaulay2 object. This provides a Pythonic interface to Macaulay2. For example, if ``f = macaulay2(10)``, then ``f.gcd(25)`` returns the GCD of `10` and `25` computed using Macaulay2. @@ -152,7 +152,7 @@ def remove_output_labels(s) -> str: Return type: string - .. note:: + .. NOTE:: If ``s`` consists of several outputs and their labels have different width, it is possible that some strings will have leading @@ -255,8 +255,8 @@ def _read_in_file_command(self, filename): INPUT: - - filename: the name of the file to be loaded and executed - (type: string) + - ``filename`` -- string; the name of the file to be loaded and + executed OUTPUT: @@ -310,8 +310,8 @@ def eval(self, code, strip=True, **kwds): INPUT: - - code -- str - - strip -- ignored + - ``code`` -- string + - ``strip`` -- ignored EXAMPLES:: @@ -343,8 +343,8 @@ def set_seed(self, seed=None): INPUT: - - ``seed`` -- number (default: ``None``). If ``None``, it - is set to a random number. + - ``seed`` -- number (default: ``None``); if ``None``, it + is set to a random number OUTPUT: the new seed @@ -401,7 +401,7 @@ def get(self, var): - ``var`` -- string; the name of the variable in Macaulay2 - OUTPUT: a string of the textual representation of the variable in + OUTPUT: string of the textual representation of the variable in Macaulay2 EXAMPLES:: @@ -427,7 +427,7 @@ def set(self, var, value): INPUT: - ``var`` -- string; the name of the variable in Macaulay2 - - ``value`` -- a string to evaluate + - ``value`` -- string to evaluate EXAMPLES:: @@ -544,7 +544,6 @@ def console(self): Macaulay 2, version 1.1 with packages: Classic, Core, Elimination, IntegralClosure, LLLBases, Parsing, PrimaryDecomposition, SchurRings, TangentCone ... - """ macaulay2_console() @@ -584,7 +583,7 @@ def _install_hints(self): def _left_list_delim(self): """ - Returns the Macaulay2 left delimiter for lists. + Return the Macaulay2 left delimiter for lists. EXAMPLES:: @@ -595,7 +594,7 @@ def _left_list_delim(self): def _right_list_delim(self): """ - Returns the Macaulay2 right delimiter for lists. + Return the Macaulay2 right delimiter for lists. EXAMPLES:: @@ -606,7 +605,7 @@ def _right_list_delim(self): def _true_symbol(self): """ - Returns the Macaulay2 symbol for True. + Return the Macaulay2 symbol for True. EXAMPLES:: @@ -617,7 +616,7 @@ def _true_symbol(self): def _false_symbol(self): """ - Returns the Macaulay2 symbol for False. + Return the Macaulay2 symbol for False. EXAMPLES:: @@ -628,7 +627,7 @@ def _false_symbol(self): def _equality_symbol(self): """ - Returns the Macaulay2 symbol for equality. + Return the Macaulay2 symbol for equality. EXAMPLES:: @@ -674,12 +673,10 @@ def ideal(self, *gens): INPUT: - - gens -- list or tuple of Macaulay2 objects (or objects that can be + - ``gens`` -- list or tuple of Macaulay2 objects (or objects that can be made into Macaulay2 objects via evaluation) - OUTPUT: - - the Macaulay2 ideal generated by the given list of gens + OUTPUT: the Macaulay2 ideal generated by the given list of gens EXAMPLES:: @@ -693,7 +690,6 @@ def ideal(self, *gens): {-7} | xy6-2xy5+xy4-y7+2y6-y5 | {-5} | x2y3-x2y2-2xy4+2xy3+y5-y4 | {-3} | x3-3x2y+3xy2-y3 | - """ if len(gens) == 1 and isinstance(gens[0], (list, tuple)): gens = gens[0] @@ -712,8 +708,8 @@ def ring(self, base_ring='ZZ', vars='[x]', order='Lex'): INPUT: - ``base_ring`` -- base ring (see examples below) - - ``vars`` -- a tuple or string that defines the variable names - - ``order`` -- string (default: 'Lex'); the monomial order + - ``vars`` -- tuple or string that defines the variable names + - ``order`` -- string (default: ``'Lex'``); the monomial order OUTPUT: a Macaulay2 ring @@ -850,7 +846,6 @@ def new_from(self, type, value): MutableList{...3...} sage: list(l) # optional - macaulay2 [1, 2, 3] - """ type = self(type) value = self(value) @@ -1001,8 +996,8 @@ def name(self, new_name=None): INPUT: - - ``new_name`` -- string (default: ``None``). If ``None``, return the - name of this element; else return a new object identical to ``self`` + - ``new_name`` -- string (default: ``None``); if ``None``, return the + name of this element. Else return a new object identical to ``self`` whose name is ``new_name``. Note that this can overwrite existing variables in the system. @@ -1085,7 +1080,6 @@ def __setitem__(self, index, value): sage: l[0] = 4 # optional - macaulay2 sage: list(l) # optional - macaulay2 [4, 2, 3] - """ P = self.parent() index = P(index) @@ -1113,7 +1107,7 @@ def __call__(self, x): def __floordiv__(self, x): """ - Quotient of division of self by other. This is denoted //. + Quotient of division of ``self`` by ``other``. This is denoted ``//``. EXAMPLES:: @@ -1141,7 +1135,7 @@ def __floordiv__(self, x): def __mod__(self, x): """ - Remainder of division of self by other. This is denoted %. + Remainder of division of ``self`` by ``other``. This is denoted ``%``. EXAMPLES:: @@ -1256,7 +1250,6 @@ def subs(self, *args, **kwds): sage: a = a.substitute(P) sage: a.sage().parent() Univariate Polynomial Ring in x over Finite Field of size 7 - """ return self.__getattr__("substitute")(*args, **kwds) @@ -1363,8 +1356,8 @@ def dot(self, x): def _operator(self, opstr, x): """ - Returns the infix binary operation specified by opstr applied - to self and x. + Return the infix binary operation specified by opstr applied + to ``self`` and x. EXAMPLES:: @@ -1399,7 +1392,6 @@ def starstar(self, x): sage: a = macaulay2([1,2]).set() # optional - macaulay2 sage: a.starstar(a) # optional - macaulay2 set {(1, 1), (1, 2), (2, 1), (2, 2)} - """ return self._operator("**", x) @@ -1570,7 +1562,6 @@ def _sage_(self): 2*x*y^18 + y^14 sage: f.parent() # optional - macaulay2 Quotient of Multivariate Polynomial Ring in x, y over Finite Field of size 7 by the ideal (x^3 - y^2) - """ repr_str = str(self) cls_str = str(self.cls()) @@ -1871,7 +1862,7 @@ def _sage_src_(self): def is_Macaulay2Element(x): """ - Return True if ``x`` is a :class:`Macaulay2Element` + Return ``True`` if ``x`` is a :class:`Macaulay2Element`. This function is deprecated; use :func:`isinstance` (of :class:`sage.interfaces.abc.Macaulay2Element`) instead. diff --git a/src/sage/interfaces/magma.py b/src/sage/interfaces/magma.py index 4cf4a77f8bf..d20340717a5 100644 --- a/src/sage/interfaces/magma.py +++ b/src/sage/interfaces/magma.py @@ -5,7 +5,7 @@ system. This system provides extensive functionality for number theory, group theory, combinatorics and algebra. -.. note:: +.. NOTE:: You must have Magma installed on your computer for this interface to work. Magma is not free, so it is @@ -14,15 +14,15 @@ The Magma interface offers three pieces of functionality: -#. ``magma_console()`` -- A function that dumps you into an interactive command-line Magma session. +#. ``magma_console()`` -- a function that dumps you into an interactive command-line Magma session. -#. ``magma.new(obj)`` and alternatively ``magma(obj)`` -- Creation of a Magma object from a Sage object ``obj``. +#. ``magma.new(obj)`` and alternatively ``magma(obj)`` -- creation of a Magma object from a Sage object ``obj``. This provides a Pythonic interface to Magma. For example, if ``f=magma.new(10)``, then ``f.Factors()`` returns the prime factorization of 10 computed using Magma. If obj is a string containing an arbitrary Magma expression, then the expression is evaluated in Magma to create a Magma object. An example is ``magma.new('10 div 3')``, which returns Magma integer 3. -#. ``magma.eval(expr)`` -- Evaluation of the Magma expression ``expr``, with the result returned as a string. +#. ``magma.eval(expr)`` -- evaluation of the Magma expression ``expr``, with the result returned as a string. Type ``magma.[tab]`` for a list of all functions available from your Magma. Type ``magma.Function?`` for Magma's help about the Magma ``Function``. @@ -281,7 +281,7 @@ class Magma(ExtraTabCompletion, Expect): object, and ``magma.eval(...)`` to run a string using Magma (and get the result back as a string). - .. note:: + .. NOTE:: If you do not own a local copy of Magma, try using the ``magma_free`` command instead, which uses the free demo web @@ -309,23 +309,23 @@ def __init__(self, script_subdirectory=None, """ INPUT: - - ``script_subdirectory`` -- directory where scripts - are read from + - ``script_subdirectory`` -- directory where scripts + are read from - - ``logfile`` -- output logged to this file + - ``logfile`` -- output logged to this file - - ``server`` -- address of remote server + - ``server`` -- address of remote server - ``server_tmpdir`` -- temporary directory to use in remote server - - ``user_config`` -- if True, then local user - configuration files will be read by Magma. If False (the default), - then Magma is started with the -n option which suppresses user - configuration files. + - ``user_config`` -- if ``True``, then local user + configuration files will be read by Magma. If ``False`` (the default), + then Magma is started with the -n option which suppresses user + configuration files. - - ``seed`` -- Seed to use in the random number generator. + - ``seed`` -- seed to use in the random number generator - - ``command`` -- (Default: 'magma') The command to execute to start Magma. + - ``command`` -- (default: ``'magma'``) the command to execute to start Magma EXAMPLES:: @@ -344,8 +344,8 @@ def __init__(self, script_subdirectory=None, seed = os.getenv('SAGE_MAGMA_SEED') Expect.__init__(self, - name="magma", - prompt=">>SAGE>>", + name='magma', + prompt='>>SAGE>>', command=command, server=server, server_tmpdir=server_tmpdir, @@ -420,15 +420,11 @@ def _read_in_file_command(self, filename): INPUT: - - - ``filename`` -- string - + - ``filename`` -- string OUTPUT: - - - ``string`` -- a magma command - + - ``string`` -- a magma command EXAMPLES:: @@ -446,11 +442,9 @@ def _post_process_from_file(self, s): INPUT: + - ``s`` -- string - - ``s`` -- a string - - - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -471,15 +465,13 @@ def _post_process_from_file(self, s): def __getattr__(self, attrname): """ Return a formal wrapper around a Magma function, or raise an - AttributeError if attrname starts with an underscore. + :exc:`AttributeError` if attrname starts with an underscore. INPUT: + - ``attrname`` -- string - - ``attrname`` -- a string - - - OUTPUT: MagmaFunction instance + OUTPUT: :class:`MagmaFunction` instance EXAMPLES:: @@ -509,10 +501,9 @@ def eval(self, x, strip=True, **kwds): INPUT: - - ``x`` -- string of code - - - ``strip`` -- ignored + - ``x`` -- string of code + - ``strip`` -- ignored OUTPUT: string @@ -552,7 +543,6 @@ def eval(self, x, strip=True, **kwds): True sage: magma.eval("[a,b];") # optional - magma '[ 3, 5 ]' - """ x = self._preparse(x) x = str(x).rstrip() @@ -615,11 +605,9 @@ def set(self, var, value): INPUT: + - ``var`` -- string; a variable name - - ``var`` -- string; a variable name - - - ``value`` -- string; what to set var equal to - + - ``value`` -- string; what to set var equal to EXAMPLES:: @@ -637,17 +625,10 @@ def get(self, var): INPUT: + - ``var`` -- string; name of a variable defined in the + Magma session - - ``var`` -- string; name of a variable defined in the - Magma session - - - OUTPUT: - - - - ``string`` -- string representation of the value of - the variable. - + OUTPUT: string representation of the value of the variable EXAMPLES:: @@ -663,13 +644,11 @@ def objgens(self, value, gens): INPUT: - - ``value`` -- something coercible to an element of this Magma - interface + interface - ``gens`` -- string; comma separated list of variable names - OUTPUT: new Magma element that is equal to value with given gens EXAMPLES:: @@ -706,14 +685,12 @@ def __call__(self, x, gens=None): INPUT: + - ``x`` -- object - - ``x`` -- object - - - ``gens`` -- string; names of generators of self, - separated by commas + - ``gens`` -- string; names of generators of self, + separated by commas - - OUTPUT: MagmaElement + OUTPUT: :class:`MagmaElement` EXAMPLES:: @@ -816,10 +793,10 @@ def __call__(self, x, gens=None): def _coerce_from_special_method(self, x): """ - Tries to coerce to self by calling a special underscore method. + Try to coerce to ``self`` by calling a special underscore method. - If no such method is defined, raises an AttributeError instead of a - TypeError. + If no such method is defined, raises an :exc:`AttributeError` instead + of a :exc:`TypeError`. EXAMPLES:: @@ -852,11 +829,9 @@ def _with_names(self, s, names): INPUT: + - ``s`` -- string - - ``s`` -- string - - - ``names`` -- list of strings - + - ``names`` -- list of strings OUTPUT: string @@ -875,9 +850,7 @@ def clear(self, var): INPUT: - - - ``var`` -- a string - + - ``var`` -- string EXAMPLES:: @@ -926,16 +899,12 @@ def cputime(self, t=None): INPUT: - - - ``t`` -- float (default: None); if not None, return - cputime since t - + - ``t`` -- float (default: ``None``); if not None, return + cputime since t OUTPUT: - - - ``float`` -- seconds - + - ``float`` -- seconds EXAMPLES:: @@ -959,7 +928,7 @@ def chdir(self, dir): INPUT: - - ``dir`` -- a string + - ``dir`` -- string EXAMPLES:: @@ -982,9 +951,7 @@ def attach(self, filename): INPUT: - - - ``filename`` -- a string - + - ``filename`` -- string EXAMPLES: Attaching a file that exists is fine:: @@ -1012,9 +979,7 @@ def attach_spec(self, filename): INPUT: - - - ``filename`` -- a string - + - ``filename`` -- string EXAMPLES:: @@ -1043,16 +1008,14 @@ def load(self, filename): INPUT: - - - ``filename`` -- string - + - ``filename`` -- string OUTPUT: output printed when loading the file EXAMPLES:: sage: from tempfile import NamedTemporaryFile as NTF - sage: with NTF(mode="w+t", suffix=".m") as f: # optional - magma + sage: with NTF(mode='w+t', suffix='.m') as f: # optional - magma ....: _ = f.write('function f(n) return n^2; end function;\nprint "hi";') ....: print(magma.load(f.name)) Loading ".../a.m" @@ -1120,20 +1083,19 @@ def function_call(self, function, args=[], params={}, nvals=1): INPUT: + - ``function`` -- string, a Magma function name - - ``function`` -- string, a Magma function name - - - ``args`` -- list of objects coercible into this magma - interface - - - ``params`` -- Magma parameters, passed in after a - colon + - ``args`` -- list of objects coercible into this magma + interface - - ``nvals`` -- number of return values from the - function to ask Magma for + - ``params`` -- Magma parameters, passed in after a + colon + - ``nvals`` -- number of return values from the + function to ask Magma for - OUTPUT: MagmaElement or tuple of nvals MagmaElement's + OUTPUT: instance of :class:`MagmaElement` or a tuple of ``nvals`` many + :class:`MagmaElement` instances EXAMPLES:: @@ -1178,11 +1140,9 @@ def _do_call(self, code, nvals): INPUT: + - ``code`` -- string; code to evaluate - - ``code`` -- a string; code to evaluate - - - ``nvals`` -- an integer; number of return values - + - ``nvals`` -- integer; number of return values OUTPUT: nvals distinct values @@ -1232,7 +1192,7 @@ def _do_call(self, code, nvals): def bar_call(self, left, name, gens, nvals=1): """ - This is a wrapper around the Magma constructor + This is a wrapper around the Magma constructor. nameleft gens @@ -1240,18 +1200,16 @@ def bar_call(self, left, name, gens, nvals=1): INPUT: + - ``left`` -- something coerceable to a magma object - - ``left`` -- something coerceable to a magma object - - - ``name`` -- name of the constructor, e.g., sub, quo, - ideal, etc. - - - ``gens`` -- if a list/tuple, each item is coerced to - magma; otherwise gens itself is converted to magma + - ``name`` -- name of the constructor, e.g., sub, quo, + ideal, etc. - - ``nvals`` -- positive integer; number of return - values + - ``gens`` -- if a list/tuple, each item is coerced to + magma; otherwise gens itself is converted to magma + - ``nvals`` -- positive integer; number of return + values OUTPUT: a single magma object if nvals == 1; otherwise a tuple of nvals magma objects. @@ -1420,11 +1378,9 @@ def version(self): OUTPUT: + - ``numbers`` -- 3-tuple: major, minor, etc. - - ``numbers`` -- 3-tuple: major, minor, etc. - - - ``string`` -- version as a string - + - ``string`` -- version as a string EXAMPLES:: @@ -1442,9 +1398,7 @@ def help(self, s): INPUT: - - - ``s`` -- string - + - ``s`` -- string OUTPUT: string @@ -1474,14 +1428,12 @@ def _tab_completion(self, verbose=True, use_disk_cache=True): INPUT: + - ``verbose`` -- boolean (default: ``True``); whether to + verbosely output status info the first time the command list is + built - - ``verbose`` -- bool (default: ``True``); whether to - verbosely output status info the first time the command list is - built - - - ``use_disk_cache`` -- bool (default: ``True``); use - cached command list, which is saved to disk. - + - ``use_disk_cache`` -- boolean (default: ``True``); use + cached command list, which is saved to disk OUTPUT: list of strings @@ -1536,12 +1488,10 @@ def ideal(self, L): INPUT: + - ``L`` -- list of elements of a Sage multivariate + polynomial ring - - ``L`` -- a list of elements of a Sage multivariate - polynomial ring. - - - OUTPUT: The magma ideal generated by the elements of L. + OUTPUT: the magma ideal generated by the elements of L EXAMPLES:: @@ -1574,9 +1524,9 @@ def set_verbose(self, type, level): INPUT: - - ``type`` -- string (e.g. 'Groebner') + - ``type`` -- string (e.g. 'Groebner') - - ``level`` -- integer >= 0 + - ``level`` -- integer >= 0 EXAMPLES:: @@ -1596,10 +1546,8 @@ def get_verbose(self, type): INPUT: - - - ``type`` -- string (e.g. 'Groebner'), see Magma - documentation - + - ``type`` -- string (e.g. 'Groebner'), see Magma + documentation EXAMPLES:: @@ -1828,13 +1776,14 @@ def _instancedoc_(self): def is_MagmaElement(x): """ - Return True if ``x`` is of type :class:`MagmaElement`, and False otherwise. + Return ``True`` if ``x`` is of type :class:`MagmaElement`, and ``False`` + otherwise. INPUT: - - ``x`` -- any object + - ``x`` -- any object - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -1901,15 +1850,15 @@ def __getattr__(self, attrname): """ INPUT: - - ``attrname`` -- string + - ``attrname`` -- string - OUTPUT: a Magma function partially evaluated with self as the first - input. + OUTPUT: a Magma function partially evaluated with ``self`` as the first + input - .. note:: + .. NOTE:: If the input ``attrname`` starts with an underscore, an - :class:`AttributeError` is raised so that the actual + :exc:`AttributeError` is raised so that the actual Python _ method/value can be accessed. EXAMPLES:: @@ -2121,16 +2070,15 @@ def AssignNames(self, names): def gen(self, n): """ - Return the n-th generator of this Magma element. Note that - generators are 1-based in Magma rather than 0 based! + Return the `n`-th generator of this Magma element. Note that + generators are 1-based in Magma rather than 0-based! INPUT: - - - ``n`` -- a *positive* integer + - ``n`` -- *positive* integer - OUTPUT: MagmaElement + OUTPUT: :class:`MagmaElement` EXAMPLES:: @@ -2162,7 +2110,7 @@ def gens(self) -> tuple: """ Return generators for ``self``. - If self is named X in Magma, this function evaluates X.1, X.2, + If ``self`` is named X in Magma, this function evaluates X.1, X.2, etc., in Magma until an error occurs. It then returns a Sage tuple of the resulting X.i. Note - I don't think there is a Magma command that returns the list of valid X.i. There are numerous ad hoc @@ -2201,9 +2149,9 @@ def gens(self) -> tuple: def gen_names(self): """ - Return list of Magma variable names of the generators of self. + Return list of Magma variable names of the generators of ``self``. - .. note:: + .. NOTE:: As illustrated below, these are not the print names of the the generators of the Magma object, but special variable @@ -2226,11 +2174,11 @@ def gen_names(self): def evaluate(self, *args): r""" - Evaluate self at the inputs. + Evaluate ``self`` at the inputs. INPUT: - - ``*args`` -- import arguments + - ``*args`` -- import arguments OUTPUT: self(\*args) @@ -2292,7 +2240,7 @@ def __iter__(self): .. warning:: - Internally this constructs the list of elements in self in + Internally this constructs the list of elements in ``self`` in Magma, which is not a lazy operation. This is because Magma doesn't have a notion of lazy iterators, unfortunately. @@ -2338,8 +2286,8 @@ def __len__(self): def _polynomial_(self, R): """ - Try to convert self into a polynomial in the univariate polynomial - ring R. + Try to convert ``self`` into a polynomial in the univariate polynomial + ring `R`. EXAMPLES:: @@ -2356,32 +2304,30 @@ def _polynomial_(self, R): def _latex_(self): r""" - Return latex representation of self. + Return latex representation of ``self``. AUTHORS: - Jennifer Balakrishnan - Types that are nicely latex include: - - - - rationals + Types that are nicely latexed include: - - matrices + - rationals - - polynomials + - matrices - - binary quadratic forms + - polynomials - - elements of quadratic, cyclotomic number fields, and general - number fields + - binary quadratic forms - - points + - elements of quadratic, cyclotomic number fields, and general + number fields - - elliptic curves + - points - - power series + - elliptic curves + - power series IMPLEMENTATION: Calls latex.m, which is in SAGE_EXTCODE/magma/latex.m @@ -2465,7 +2411,7 @@ def _latex_(self): sage: latex(magma('(-1/(2+x + O(x^3)))')) \frac{-1}{2}+\frac{1}{4}x-\frac{1}{8}x^{2}+O(x^{3}) - p-adic Numbers:: + `p`-adic Numbers:: sage: latex(magma('pAdicField(7,4)!9333294394/49')) # optional - magma 4\cdot{}7^{-2} + 5\cdot{}7^{-1} + 5+ 6\cdot{}7^{1} + O(7^{2}) @@ -2479,8 +2425,10 @@ def _latex_(self): def set_magma_attribute(self, attrname, value): """ - INPUT: attrname - string value - something coercible to a - MagmaElement + INPUT: + + - ``attrname`` -- string + - ``value`` -- something coercible to a MagmaElement EXAMPLES:: @@ -2502,7 +2450,7 @@ def get_magma_attribute(self, attrname): Return value of a given Magma attribute. This is like selfattrname in Magma. - OUTPUT: MagmaElement + OUTPUT: :class:`MagmaElement` EXAMPLES:: @@ -2539,19 +2487,17 @@ def _tab_completion(self): Return all Magma functions that have this Magma element as first input. This is used for tab completion. - .. note:: + .. NOTE:: This function can unfortunately be slow if there are a very - large number of functions, e.g., when self is an + large number of functions, e.g., when ``self`` is an integer. (This could be fixed by the addition of an appropriate function to the Magma kernel, which is something that can only be done by the Magma developers.) OUTPUT: - - - ``list`` -- sorted list of distinct strings - + - ``list`` -- sorted list of distinct strings EXAMPLES:: @@ -2570,13 +2516,13 @@ def _tab_completion(self): def methods(self, any=False): """ - Return signatures of all Magma intrinsics that can take self as the + Return signatures of all Magma intrinsics that can take ``self`` as the first argument, as strings. INPUT: - - ``any`` -- (bool: default is False) if True, also - include signatures with Any as first argument. + - ``any`` -- boolean (default: ``False``); if ``True``, also + include signatures with Any as first argument OUTPUT: list of strings @@ -2602,8 +2548,8 @@ def methods(self, any=False): def __floordiv__(self, x): """ - Quotient of division of self by other. This is denoted // ("div" in - magma). + Quotient of division of ``self`` by ``other``. This is denoted ``//`` + (``div`` in magma). EXAMPLES:: @@ -2685,11 +2631,11 @@ def __bool__(self): def sub(self, gens): """ - Return the sub-object of self with given gens. + Return the sub-object of ``self`` with given gens. INPUT: - - ``gens`` -- object or list/tuple of generators + - ``gens`` -- object or list/tuple of generators EXAMPLES:: @@ -2707,24 +2653,20 @@ def sub(self, gens): def quo(self, gens, **args): """ - Return the quotient of self by the given object or list of + Return the quotient of ``self`` by the given object or list of generators. INPUT: - - - ``gens`` -- object or list/tuple of generators + - ``gens`` -- object or list/tuple of generators - further named arguments that are ignored - OUTPUT: + - ``magma element`` -- the quotient object - - ``magma element`` -- the quotient object - - - ``magma element`` -- mapping from self to the - quotient object - + - ``magma element`` -- mapping from ``self`` to the + quotient object EXAMPLES:: @@ -2756,19 +2698,15 @@ def quo(self, gens, **args): def ideal(self, gens): """ - Return the ideal of self with given list of generators. + Return the ideal of ``self`` with given list of generators. INPUT: - - - ``gens`` -- object or list/tuple of generators - + - ``gens`` -- object or list/tuple of generators OUTPUT: - - - ``magma element`` -- a Magma ideal - + - ``magma element`` -- a Magma ideal EXAMPLES:: @@ -2840,7 +2778,7 @@ def __init__(self, verbosity=1, style='magma'): - ``style`` -- if "magma" the full Magma log is printed; if 'sage' only the current degree and the number of pairs in - the queue is printed (default: "magma"). + the queue is printed (default: ``'magma'``). EXAMPLES:: diff --git a/src/sage/interfaces/maple.py b/src/sage/interfaces/maple.py index ce42a9b87db..5929582742e 100644 --- a/src/sage/interfaces/maple.py +++ b/src/sage/interfaces/maple.py @@ -37,7 +37,7 @@ (x-y)*(x^4+x^3*y+x^2*y^2+x*y^3+y^4) If the string "error" (case insensitive) occurs in the output of -anything from Maple, a :class:`RuntimeError` exception is raised. +anything from Maple, a :exc:`RuntimeError` exception is raised. Tutorial -------- @@ -750,10 +750,8 @@ def source(self, s): INPUT: - - - ``s`` -- a string representing the function whose - source code you want - + - ``s`` -- string representing the function whose + source code you want EXAMPLES:: @@ -785,8 +783,8 @@ def help(self, string): INPUT: - - ``string`` -- a string to search for in the maple help - system + - ``string`` -- string to search for in the maple help + system EXAMPLES:: @@ -802,7 +800,7 @@ def with_package(self, package): INPUT: - - ``package`` -- string + - ``package`` -- string EXAMPLES: Some functions are unknown to Maple until you use with to include the appropriate package. @@ -852,7 +850,7 @@ class MapleFunction(ExpectFunction): def _instancedoc_(self): """ Return the Maple help for this function. This gets called when - doing "?" on self. + doing ``?`` on ``self``. EXAMPLES:: @@ -923,7 +921,7 @@ class MapleElement(ExtraTabCompletion, ExpectElement): def __float__(self): """ - Return a floating point version of self. + Return a floating point version of ``self``. EXAMPLES:: @@ -936,7 +934,7 @@ def __float__(self): def __hash__(self): """ - Return a 64-bit integer representing the hash of self. Since + Return a 64-bit integer representing the hash of ``self``. Since Python uses 32-bit hashes, it will automatically convert the result of this to a 32-bit hash. @@ -961,7 +959,7 @@ def __hash__(self): def _richcmp_(self, other, op): """ - Compare equality between self and other, using maple. + Compare equality between ``self`` and ``other``, using maple. These examples are optional, and require Maple to be installed. You don't need to install any Sage packages for this. @@ -1093,7 +1091,7 @@ def _latex_(self): sage: print(maple(pi - e^3)._latex_()) # optional - maple \pi-{{\rm e}^{3}} - .. note:: + .. NOTE:: Some expressions might require the Maple style file ``maple2e.sty`` in order to latex correctly. @@ -1102,11 +1100,11 @@ def _latex_(self): def op(self, i=None): """ - Return the i-th operand of this expression. + Return the `i`-th operand of this expression. INPUT: - - i -- an integer or ``None`` + - ``i`` -- integer or ``None`` EXAMPLES:: diff --git a/src/sage/interfaces/mathematica.py b/src/sage/interfaces/mathematica.py index 44b3176489e..71f233746e7 100644 --- a/src/sage/interfaces/mathematica.py +++ b/src/sage/interfaces/mathematica.py @@ -627,7 +627,7 @@ def _eval_line(self, line, allow_use_file=True, wait_for_prompt=True, restart_if def _function_call_string(self, function, args, kwds): """ - Returns the string used to make function calls. + Return the string used to make function calls. EXAMPLES:: @@ -649,7 +649,7 @@ def _right_func_delim(self): return "]" ########################################### - # System -- change directory, etc + # System -- change directory, etc. ########################################### def chdir(self, dir): """ @@ -677,7 +677,7 @@ def _assign_symbol(self): def _exponent_symbol(self): """ - Returns the symbol used to denote the exponent of a number in + Return the symbol used to denote the exponent of a number in Mathematica. EXAMPLES:: @@ -925,11 +925,9 @@ def __len__(self): @cached_method def _is_graphics(self): """ - Test whether the mathematica expression is graphics + Test whether the mathematica expression is graphics. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -942,14 +940,14 @@ def _is_graphics(self): def save_image(self, filename, ImageSize=600): r""" - Save a mathematica graphics + Save a mathematica graphics. INPUT: - - ``filename`` -- string. The filename to save as. The - extension determines the image file format. + - ``filename`` -- string; the filename to save as. The + extension determines the image file format - - ``ImageSize`` -- integer. The size of the resulting image. + - ``ImageSize`` -- integer; the size of the resulting image EXAMPLES:: @@ -967,7 +965,7 @@ def save_image(self, filename, ImageSize=600): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -1010,7 +1008,7 @@ def show(self, ImageSize=600): INPUT: - - ``ImageSize`` -- integer. The size of the resulting image. + - ``ImageSize`` -- integer; the size of the resulting image OUTPUT: @@ -1069,7 +1067,7 @@ def __bool__(self): def n(self, *args, **kwargs): r""" - Numerical approximation by converting to Sage object first + Numerical approximation by converting to Sage object first. Convert the object into a Sage object and return its numerical approximation. See documentation of the function @@ -1130,11 +1128,9 @@ def request_wolfram_alpha(input, verbose=False): INPUT: - ``input`` -- string - - ``verbose`` -- bool (default: ``False``) - - OUTPUT: + - ``verbose`` -- boolean (default: ``False``) - json + OUTPUT: json EXAMPLES:: @@ -1231,16 +1227,14 @@ def request_wolfram_alpha(input, verbose=False): def parse_moutput_from_json(page_data, verbose=False): r""" - Return the list of outputs found in the json (with key ``'moutput'``) + Return the list of outputs found in the json (with key ``'moutput'``). INPUT: - ``page_data`` -- json obtained from Wolfram Alpha - - ``verbose`` -- bool (default: ``False``) + - ``verbose`` -- boolean (default: ``False``) - OUTPUT: - - list of unicode strings + OUTPUT: list of unicode strings EXAMPLES:: @@ -1296,15 +1290,13 @@ def parse_moutput_from_json(page_data, verbose=False): def symbolic_expression_from_mathematica_string(mexpr): r""" - Translate a mathematica string into a symbolic expression + Translate a mathematica string into a symbolic expression. INPUT: - ``mexpr`` -- string - OUTPUT: - - symbolic expression + OUTPUT: symbolic expression EXAMPLES:: diff --git a/src/sage/interfaces/mathics.py b/src/sage/interfaces/mathics.py index 473bb9dae71..3104fefe665 100644 --- a/src/sage/interfaces/mathics.py +++ b/src/sage/interfaces/mathics.py @@ -610,7 +610,7 @@ def get(self, var): def _function_call_string(self, function, args, kwds): """ - Returns the string used to make function calls. + Return the string used to make function calls. EXAMPLES:: @@ -656,7 +656,7 @@ def _right_func_delim(self): return "]" # ######################################### - # System -- change directory, etc + # System -- change directory, etc. # ######################################### def chdir(self, dir): """ @@ -708,7 +708,7 @@ def _assign_symbol(self): def _exponent_symbol(self): r""" - Returns the symbol used to denote the exponent of a number in + Return the symbol used to denote the exponent of a number in Mathics. EXAMPLES:: @@ -735,7 +735,6 @@ def _object_class(self): sage: mathics._object_class() - """ return MathicsElement @@ -868,7 +867,7 @@ def _tab_completion(self): r""" Return a list of all methods of this object. - .. note:: + .. NOTE:: Currently returns all methods of :class:`mathics.expression.Expression`. @@ -1048,7 +1047,6 @@ def _sage_(self, locals={}): bla sage: bla^2 - mb 0 - """ if locals: # if locals are given we use `_sage_repr` @@ -1099,9 +1097,7 @@ def _is_graphics(self): """ Test whether the mathics expression is graphics. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1113,14 +1109,14 @@ def _is_graphics(self): def save_image(self, filename, ImageSize=600): r""" - Save a mathics graphics + Save a mathics graphics. INPUT: - - ``filename`` -- string. The filename to save as. The - extension determines the image file format. + - ``filename`` -- string; the filename to save as. The + extension determines the image file format - - ``ImageSize`` -- integer. The size of the resulting image. + - ``ImageSize`` -- integer; the size of the resulting image EXAMPLES:: @@ -1137,7 +1133,7 @@ def save_image(self, filename, ImageSize=600): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -1180,7 +1176,7 @@ def show(self, ImageSize=600): INPUT: - - ``ImageSize`` -- integer. The size of the resulting image. + - ``ImageSize`` -- integer; the size of the resulting image OUTPUT: @@ -1247,7 +1243,7 @@ def __bool__(self): def n(self, *args, **kwargs): r""" - Numerical approximation by converting to Sage object first + Numerical approximation by converting to Sage object first. Convert the object into a Sage object and return its numerical approximation. See documentation of the function diff --git a/src/sage/interfaces/matlab.py b/src/sage/interfaces/matlab.py index 61f5563f4a6..7e701f515f3 100644 --- a/src/sage/interfaces/matlab.py +++ b/src/sage/interfaces/matlab.py @@ -192,7 +192,7 @@ def __reduce__(self): def _read_in_file_command(self, filename): """ - Returns the command used to read in and execute a file in Matlab. + Return the command used to read in and execute a file in Matlab. EXAMPLES:: @@ -268,7 +268,7 @@ def get(self, var): def strip_answer(self, s): r""" - Returns the string s with Matlab's answer prompt removed. + Return the string s with Matlab's answer prompt removed. EXAMPLES:: @@ -294,7 +294,6 @@ def chdir(self, directory): sage: matlab.chdir('/') # optional - matlab sage: matlab.pwd() # optional - matlab / - """ self.eval("cd('{0}')".format(directory)) @@ -302,9 +301,11 @@ def sage2matlab_matrix_string(self, A): """ Return a matlab matrix from a Sage matrix. - INPUT: A Sage matrix with entries in the rationals or reals. + INPUT: + + - ``A`` -- Sage matrix with entries in the rationals or reals - OUTPUT: A string that evaluates to a Matlab matrix. + OUTPUT: string that evaluates to a Matlab matrix EXAMPLES:: @@ -347,7 +348,6 @@ def _matrix_(self, R): sage: a = matlab('eye(50)') # optional - matlab sage: matrix(RR, a) # optional - matlab 50 x 50 dense matrix over Real Field with 53 bits of precision - """ from sage.matrix.constructor import matrix matlab = self.parent() diff --git a/src/sage/interfaces/maxima.py b/src/sage/interfaces/maxima.py index dd63daa08a8..96158d73039 100644 --- a/src/sage/interfaces/maxima.py +++ b/src/sage/interfaces/maxima.py @@ -35,7 +35,7 @@ If the string "error" (case insensitive) occurs in the output of -anything from Maxima, a :class:`RuntimeError` exception is raised. +anything from Maxima, a :exc:`RuntimeError` exception is raised. EXAMPLES: We evaluate a very simple expression in Maxima. @@ -410,7 +410,7 @@ The MAXIMA interface reads in even very long input (using files) in a robust manner, as long as you are creating a new object. -.. note:: +.. NOTE:: Using ``maxima.eval`` for long input is much less robust, and is not recommended. @@ -625,7 +625,6 @@ def _start(self): sage: m._start() sage: m.is_running() True - """ Expect._start(self) self._sendline(r":lisp (defun tex-derivative (x l r) (tex (if $derivabbrev (tex-dabbrev x) (tex-d x '\\partial)) l r lop rop ))") @@ -777,8 +776,6 @@ def _eval_line(self, line, allow_use_file=False, Traceback (most recent call last): ... TypeError: Error executing code in Maxima... - - """ if len(line) == 0: return '' @@ -975,7 +972,7 @@ def lisp(self, cmd): """ Send a lisp command to Maxima. - .. note:: + .. NOTE:: The output of this command is very raw - not pretty. @@ -1120,7 +1117,7 @@ def _object_function_class(self): def is_MaximaElement(x): """ - Return True if ``x`` is of type :class:`MaximaElement`. + Return ``True`` if ``x`` is of type :class:`MaximaElement`. EXAMPLES:: diff --git a/src/sage/interfaces/maxima_abstract.py b/src/sage/interfaces/maxima_abstract.py index 68c465d71c9..b8df280857c 100644 --- a/src/sage/interfaces/maxima_abstract.py +++ b/src/sage/interfaces/maxima_abstract.py @@ -114,7 +114,7 @@ def __init__(self, name='maxima_abstract'): Interface.__init__(self, name) ########################################### - # System -- change directory, etc + # System -- change directory, etc. ########################################### def chdir(self, dir): r""" @@ -189,9 +189,7 @@ def help(self, s): - ``s`` -- string - OUTPUT: - - Maxima's help for ``s`` + OUTPUT: Maxima's help for ``s`` EXAMPLES:: @@ -211,9 +209,7 @@ def example(self, s): - ``s`` -- string - OUTPUT: - - Maxima's examples for ``s`` + OUTPUT: Maxima's examples for ``s`` EXAMPLES:: @@ -374,8 +370,6 @@ def console(self): maxima session from this interface. To interact with this session, you should instead use ``maxima.interact()``. - INPUT: none - OUTPUT: none EXAMPLES:: @@ -402,12 +396,12 @@ def console(self): def cputime(self, t=None): r""" - Returns the amount of CPU time that this Maxima session has used. + Return the amount of CPU time that this Maxima session has used. INPUT: - - ``t`` -- float (default: None); If \var{t} is not None, then - it returns the difference between the current CPU time and \var{t}. + - ``t`` -- float (default: ``None``); if \var{t} is not None, then + it returns the difference between the current CPU time and \var{t} OUTPUT: float @@ -427,8 +421,6 @@ def version(self): r""" Return the version of Maxima that Sage includes. - INPUT: none - OUTPUT: none EXAMPLES:: @@ -446,8 +438,6 @@ def _assign_symbol(self): r""" Return the assign symbol in Maxima. - INPUT: none - OUTPUT: string EXAMPLES:: @@ -465,8 +455,6 @@ def _true_symbol(self): """ Return the true symbol in Maxima. - INPUT: none - OUTPUT: string EXAMPLES:: @@ -482,8 +470,6 @@ def _false_symbol(self): """ Return the false symbol in Maxima. - INPUT: none - OUTPUT: string EXAMPLES:: @@ -497,9 +483,7 @@ def _false_symbol(self): def _equality_symbol(self): """ - Returns the equality symbol in Maxima. - - INPUT: none + Return the equality symbol in Maxima. OUTPUT: string @@ -516,9 +500,7 @@ def _equality_symbol(self): def _inequality_symbol(self): """ - Returns the inequality symbol in Maxima. - - INPUT: none + Return the inequality symbol in Maxima. OUTPUT: string @@ -535,8 +517,6 @@ def _function_class(self): """ Return the Python class of Maxima functions. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -550,8 +530,6 @@ def _object_class(self): """ Return the Python class of Maxima elements. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -565,8 +543,6 @@ def _function_element_class(self): """ Return the Python class of Maxima functions of elements. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -580,8 +556,6 @@ def _object_function_class(self): """ Return the Python class of Maxima user-defined functions. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -601,14 +575,14 @@ def function(self, args, defn, rep=None, latex=None): INPUT: - - ``args`` -- a string with variable names separated by - commas + - ``args`` -- string with variable names separated by + commas - - ``defn`` -- a string (or Maxima expression) that - defines a function of the arguments in Maxima. + - ``defn`` -- string (or Maxima expression) that + defines a function of the arguments in Maxima - ``rep`` -- an optional string; if given, this is how - the function will print. + the function will print OUTPUT: Maxima function @@ -669,7 +643,7 @@ def function(self, args, defn, rep=None, latex=None): # INPUT: -# flag -- bool (default: ``True``) +# flag -- boolean (default: ``True``) # EXAMPLES:: @@ -692,11 +666,11 @@ def plot2d(self, *args): INPUT: - - ``f`` -- a string representing a function (such as - f="sin(x)") [var, xmin, xmax] + - ``f`` -- string representing a function (such as + f="sin(x)") [var, xmin, xmax] - ``options`` -- an optional string representing plot2d - options in gnuplot format + options in gnuplot format EXAMPLES:: @@ -715,18 +689,18 @@ def plot2d_parametric(self, r, var, trange, nticks=50, options=None): INPUT: - - ``r`` -- a string representing a function (such as - r="[x(t),y(t)]") + - ``r`` -- string representing a function (such as + r="[x(t),y(t)]") - - ``var`` -- a string representing the variable (such - as var = "t") + - ``var`` -- string representing the variable (such + as var = "t") - ``trange`` -- [tmin, tmax] are numbers with tmintmax - - ``nticks`` -- int (default: 50) + - ``nticks`` -- integer (default: 50) - ``options`` -- an optional string representing plot2d - options in gnuplot format + options in gnuplot format EXAMPLES:: @@ -762,8 +736,8 @@ def plot3d(self, *args): INPUT: - - ``f`` -- a string representing a function (such as - f="sin(x)") [var, min, max] + - ``f`` -- string representing a function (such as + f="sin(x)") [var, min, max] - ``args`` should be of the form '[x, xmin, xmax]', '[y, ymin, ymax]', '[grid, nx, ny]', options @@ -787,17 +761,17 @@ def plot3d_parametric(self, r, vars, urange, vrange, options=None): INPUT: - - ``x``, ``y``, ``z`` -- a string representing a function (such - as ``x="u2+v2"``, ...) vars is a list or two strings - representing variables (such as vars = ["u","v"]) + - ``x``, ``y``, ``z`` -- string representing a function (such + as ``x="u2+v2"``, ...) vars is a list or two strings + representing variables (such as vars = ["u","v"]) - ``urange`` -- [umin, umax] - ``vrange`` -- [vmin, vmax] are lists of numbers with - umin umax, vmin vmax + umin umax, vmin vmax - - ``options`` -- optional string representing plot2d - options in gnuplot format + - ``options`` -- (optional) string representing plot2d + options in gnuplot format OUTPUT: displays a plot on screen or saves to a file @@ -835,18 +809,18 @@ def plot3d_parametric(self, r, vars, urange, vrange, options=None): def de_solve(self, de, vars, ics=None): """ - Solves a 1st or 2nd order ordinary differential equation (ODE) in + Solve a 1st or 2nd order ordinary differential equation (ODE) in two variables, possibly with initial conditions. INPUT: - - ``de`` -- a string representing the ODE + - ``de`` -- string representing the ODE - - ``vars`` -- a list of strings representing the two - variables. + - ``vars`` -- list of strings representing the two + variables - ``ics`` -- a triple of numbers [a,b1,b2] representing - y(a)=b1, y'(a)=b2 + y(a)=b1, y'(a)=b2 EXAMPLES:: @@ -877,20 +851,20 @@ def de_solve(self, de, vars, ics=None): def de_solve_laplace(self, de, vars, ics=None): """ - Solves an ordinary differential equation (ODE) using Laplace + Solve an ordinary differential equation (ODE) using Laplace transforms. INPUT: - - ``de`` -- a string representing the ODE (e.g., de = - "diff(f(x),x,2)=diff(f(x),x)+sin(x)") + - ``de`` -- string representing the ODE (e.g., de = + "diff(f(x),x,2)=diff(f(x),x)+sin(x)") - - ``vars`` -- a list of strings representing the - variables (e.g., vars = ["x","f"]) + - ``vars`` -- list of strings representing the + variables (e.g., ``vars = ["x","f"]``) - - ``ics`` -- a list of numbers representing initial - conditions, with symbols allowed which are represented by strings - (eg, f(0)=1, f'(0)=2 is ics = [0,1,2]) + - ``ics`` -- list of numbers representing initial + conditions, with symbols allowed which are represented by strings + (eg, f(0)=1, f'(0)=2 is ics = [0,1,2]) EXAMPLES:: @@ -911,7 +885,7 @@ def de_solve_laplace(self, de, vars, ics=None): dx ! !x = 0 - .. note:: + .. NOTE:: The second equation sets the values of `f(0)` and `f'(0)` in Maxima, so subsequent ODEs involving these @@ -932,10 +906,10 @@ def solve_linear(self, eqns, vars): INPUT: - - ``eqns`` -- a list of m strings; each representing a linear + - ``eqns`` -- list of m strings; each representing a linear question in m = n variables - - ``vars`` -- a list of n strings; each + - ``vars`` -- list of n strings; each representing a variable EXAMPLES:: @@ -966,7 +940,7 @@ def unit_quadratic_integer(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -1002,18 +976,18 @@ def plot_list(self, ptsx, ptsy, options=None): INPUT: - ``ptsx`` -- [x1,...,xn], where the xi and yi are - real, + real, - ``ptsy`` -- [y1,...,yn] - - ``options`` -- a string representing maxima plot2d - options. + - ``options`` -- string representing maxima plot2d + options The points are (x1,y1), (x2,y2), etc. This function requires maxima 5.9.2 or newer. - .. note:: + .. NOTE:: More that 150 points can sometimes lead to the program hanging. Why? @@ -1051,7 +1025,7 @@ def plot_multilist(self, pts_list, options=None): Requires maxima 5.9.2 at least. - .. note:: + .. NOTE:: More that 150 points can sometimes lead to the program hanging. @@ -1113,8 +1087,6 @@ def __str__(self): """ Printing an object explicitly gives ASCII art. - INPUT: none - OUTPUT: string EXAMPLES:: @@ -1133,8 +1105,6 @@ def __bool__(self): """ Convert ``self`` into a boolean. - INPUT: none - OUTPUT: boolean EXAMPLES:: @@ -1208,8 +1178,6 @@ def _sage_(self): This is useful for automatic coercions in addition to other things. - INPUT: none - OUTPUT: Sage object EXAMPLES:: @@ -1290,8 +1258,6 @@ def __complex__(self): """ Return a complex number equivalent to this Maxima object. - INPUT: none - OUTPUT: complex EXAMPLES:: @@ -1383,8 +1349,6 @@ def real(self): """ Return the real part of this Maxima element. - INPUT: none - OUTPUT: Maxima real EXAMPLES:: @@ -1398,8 +1362,6 @@ def imag(self): """ Return the imaginary part of this Maxima element. - INPUT: none - OUTPUT: Maxima real EXAMPLES:: @@ -1411,9 +1373,7 @@ def imag(self): def numer(self): """ - Return numerical approximation to self as a Maxima object. - - INPUT: none + Return numerical approximation to ``self`` as a Maxima object. OUTPUT: Maxima object @@ -1430,8 +1390,6 @@ def str(self): """ Return string representation of this Maxima object. - INPUT: none - OUTPUT: string EXAMPLES:: @@ -1444,15 +1402,15 @@ def str(self): def diff(self, var='x', n=1): """ - Return the n-th derivative of self. + Return the `n`-th derivative of ``self``. INPUT: - - ``var`` -- variable (default: 'x') + - ``var`` -- variable (default: ``'x'``) - ``n`` -- integer (default: 1) - OUTPUT: n-th derivative of self with respect to the variable var + OUTPUT: `n`-th derivative of ``self`` with respect to the variable var EXAMPLES:: @@ -1482,8 +1440,8 @@ def nintegral(self, var='x', a=0, b=1, desired_relative_error='1e-8', maximum_num_subintervals=200): r""" - Return a numerical approximation to the integral of self from a to - b. + Return a numerical approximation to the integral of ``self`` from `a` + to `b`. INPUT: @@ -1493,18 +1451,16 @@ def nintegral(self, var='x', a=0, b=1, - ``b`` -- upper endpoint of integration - - ``desired_relative_error`` -- (default: '1e-8') the - desired relative error + - ``desired_relative_error`` -- (default: ``'1e-8'``) the + desired relative error - ``maximum_num_subintervals`` -- (default: 200) - maxima number of subintervals - - OUTPUT: + maxima number of subintervals - - approximation to the integral + OUTPUT: approximation to the integral - estimated absolute error of the - approximation + approximation - the number of integrand evaluations @@ -1546,19 +1502,17 @@ def nintegral(self, var='x', a=0, b=1, def integral(self, var='x', min=None, max=None): r""" - Return the integral of self with respect to the variable x. + Return the integral of ``self`` with respect to the variable `x`. INPUT: - ``var`` -- variable - - ``min`` -- default: None + - ``min`` -- (default: ``None``) - - ``max`` -- default: None + - ``max`` -- (default: ``None``) - OUTPUT: - - - the definite integral if xmin is not None + OUTPUT: the definite integral if xmin is not ``None`` - an indefinite integral otherwise @@ -1599,8 +1553,6 @@ def __float__(self): """ Return floating point version of this Maxima element. - INPUT: none - OUTPUT: real EXAMPLES:: @@ -1621,8 +1573,6 @@ def __len__(self): """ Return the length of a list. - INPUT: none - OUTPUT: integer EXAMPLES:: @@ -1636,11 +1586,11 @@ def __len__(self): def dot(self, other): """ - Implements the notation self . other. + Implement the notation ``self . other``. INPUT: - - ``other`` -- matrix; argument to dot. + - ``other`` -- matrix; argument to dot OUTPUT: Maxima matrix @@ -1657,7 +1607,7 @@ def dot(self, other): def __getitem__(self, n): r""" - Return the n-th element of this list. + Return the `n`-th element of this list. INPUT: @@ -1665,7 +1615,7 @@ def __getitem__(self, n): OUTPUT: Maxima object - .. note:: + .. NOTE:: Lists are 0-based when accessed via the Sage interface, not 1-based as they are in the Maxima interpreter. @@ -1691,9 +1641,7 @@ def __getitem__(self, n): def __iter__(self): """ - Return an iterator for self. - - INPUT: none + Return an iterator for ``self``. OUTPUT: iterator @@ -1753,8 +1701,6 @@ def _latex_(self): r""" Return Latex representation of this Maxima object. - INPUT: none - OUTPUT: string This calls the tex command in Maxima, then does a little @@ -1818,7 +1764,7 @@ def _tab_completion(self, verbose=False): def _matrix_(self, R): r""" - If self is a Maxima matrix, return the corresponding Sage matrix + If ``self`` is a Maxima matrix, return the corresponding Sage matrix over the Sage ring `R`. INPUT: @@ -1828,7 +1774,7 @@ def _matrix_(self, R): OUTPUT: matrix This may or may not work depending in how complicated the entries - of self are! It only works if the entries of self can be coerced as + of ``self`` are! It only works if the entries of ``self`` can be coerced as strings to produce meaningful elements of `R`. EXAMPLES:: @@ -1866,7 +1812,7 @@ def _matrix_(self, R): def partial_fraction_decomposition(self, var='x'): """ - Return the partial fraction decomposition of self with respect to + Return the partial fraction decomposition of ``self`` with respect to the variable var. INPUT: @@ -1899,11 +1845,11 @@ def _operation(self, operation, other=None): INPUT: - - ``operation`` -- a string representing the operation - being performed. For example, '*', or '1/'. + - ``operation`` -- string representing the operation + being performed. For example, '*', or '1/' - ``other`` -- the other operand. If ``other`` is ``None``, - then the operation is assumed to be unary rather than binary. + then the operation is assumed to be unary rather than binary OUTPUT: Maxima object @@ -1990,11 +1936,7 @@ def __reduce__(self): """ Implement __reduce__ for ``MaximaAbstractElementFunction``. - INPUT: none - - OUTPUT: - - A couple consisting of: + OUTPUT: a couple consisting of: - the function to call for unpickling @@ -2038,8 +1980,6 @@ def _repr_(self): """ Return print representation of this Maxima function. - INPUT: none - OUTPUT: string EXAMPLES:: @@ -2069,16 +2009,14 @@ def _latex_(self): def arguments(self, split=True): r""" - Returns the arguments of this Maxima function. + Return the arguments of this Maxima function. INPUT: - - ``split`` -- boolean; if True return a tuple of strings, + - ``split`` -- boolean; if ``True`` return a tuple of strings, otherwise return a string of comma-separated arguments - OUTPUT: - - - a string if ``split`` is False + OUTPUT: string if ``split`` is False - a list of strings if ``split`` is True @@ -2100,11 +2038,7 @@ def arguments(self, split=True): def definition(self): """ - Returns the definition of this Maxima function as a string. - - INPUT: none - - OUTPUT: string + Return the definition of this Maxima function as a string. EXAMPLES:: @@ -2116,7 +2050,7 @@ def definition(self): def integral(self, var): """ - Returns the integral of self with respect to the variable var. + Return the integral of ``self`` with respect to the variable var. INPUT: @@ -2155,12 +2089,12 @@ def _operation(self, operation, f=None): INPUT: - - ``operation`` -- A string representing the operation - being performed. For example, '\*', or '1/'. + - ``operation`` -- string representing the operation + being performed. For example, '\*', or '1/' - - ``f`` -- The other operand. If f is - ``None``, then the operation is assumed to be unary - rather than binary. + - ``f`` -- the other operand; if ``f`` is + ``None``, then the operation is assumed to be unary + rather than binary EXAMPLES:: diff --git a/src/sage/interfaces/maxima_lib.py b/src/sage/interfaces/maxima_lib.py index 7fadf1e27c1..1e6f85cfae0 100644 --- a/src/sage/interfaces/maxima_lib.py +++ b/src/sage/interfaces/maxima_lib.py @@ -343,8 +343,6 @@ class MaximaLib(MaximaAbstract): """ Interface to Maxima as a Library. - INPUT: none - OUTPUT: Maxima interface as a Library EXAMPLES:: @@ -392,7 +390,7 @@ def __init__(self): def _coerce_from_special_method(self, x): r""" - Coerce ``x`` into self trying to call a special underscore method. + Coerce ``x`` into ``self`` trying to call a special underscore method. INPUT: @@ -415,11 +413,7 @@ def __reduce__(self): r""" Implement __reduce__ for ``MaximaLib``. - INPUT: none - - OUTPUT: - - A couple consisting of: + OUTPUT: a couple consisting of: - the function to call for unpickling @@ -442,12 +436,12 @@ def _eval_line(self, line, locals=None, reformat=True, **kwds): - ``line`` -- string; text to evaluate - - ``locals`` -- None (ignored); this is used for compatibility with the - Sage notebook's generic system interface. + - ``locals`` -- ``None`` (ignored); this is used for compatibility with the + Sage notebook's generic system interface - ``reformat`` -- boolean; whether to strip output or not - - ``**kwds`` -- All other arguments are currently ignored. + - ``**kwds`` -- all other arguments are currently ignored OUTPUT: string representing Maxima output @@ -502,7 +496,7 @@ def lisp(self, cmd): OUTPUT: ECL object - .. note:: + .. NOTE:: The output of this command is very raw - not pretty. @@ -520,9 +514,9 @@ def set(self, var, value): INPUT: - - ``var`` -- string + - ``var`` -- string - - ``value`` -- string + - ``value`` -- string OUTPUT: none @@ -592,12 +586,10 @@ def _create(self, value, name=None): - ``value`` -- string or ECL object - - ``name`` -- string (default: None); name to use for the variable, + - ``name`` -- string (default: ``None``); name to use for the variable, an automatically generated name is used if this is none - OUTPUT: - - - string; the name of the created variable + OUTPUT: string; the name of the created variable EXAMPLES: @@ -641,8 +633,6 @@ def _function_class(self): r""" Return the Python class of Maxima functions. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -657,8 +647,6 @@ def _object_class(self): r""" Return the Python class of Maxima elements. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -673,8 +661,6 @@ def _function_element_class(self): r""" Return the Python class of Maxima functions of elements. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -689,8 +675,6 @@ def _object_function_class(self): r""" Return the Python class of Maxima user-defined functions. - INPUT: none - OUTPUT: type EXAMPLES:: @@ -810,7 +794,6 @@ def sr_integral(self, *args): 0.124756040961038 sage: a.imag().abs() < 3e-17 True - """ try: return max_to_sr(maxima_eval(([max_integrate], @@ -928,7 +911,6 @@ def sr_prod(self, *args): factorial(n) sage: symbolic_product(2*x,x,1,n) 2^n*factorial(n) - """ try: return max_to_sr(maxima_eval([[max_ratsimp], @@ -1013,7 +995,6 @@ def sr_limit(self, expr, v, a, dir=None): sage: limit(gamma(x + 1/2)/(sqrt(x)*gamma(x)), x=infinity) 1 sage: _ = m.eval('domain: complex') - """ try: L = [sr_to_max(SR(aa)) for aa in [expr, v, a]] @@ -1075,7 +1056,7 @@ def _missing_assumption(self, errstr): def is_MaximaLibElement(x): r""" - Return True if ``x`` is of type :class:`MaximaLibElement`. + Return ``True`` if ``x`` is of type :class:`MaximaLibElement`. EXAMPLES:: @@ -1115,8 +1096,6 @@ def ecl(self): r""" Return the underlying ECL object of this MaximaLib object. - INPUT: none - OUTPUT: ECL object EXAMPLES:: @@ -1414,7 +1393,7 @@ def mlist_to_sage(expr): - ``expr`` -- ECL object; a Maxima MLIST expression (i.e., a list) - OUTPUT: a Python list of converted expressions. + OUTPUT: a Python list of converted expressions EXAMPLES:: @@ -1573,7 +1552,7 @@ def pyobject_to_max(obj): OUTPUT: ECL object - .. note:: + .. NOTE:: This uses functions defined in sage.libs.ecl. diff --git a/src/sage/interfaces/mupad.py b/src/sage/interfaces/mupad.py index cd36a6356cc..074350d9230 100644 --- a/src/sage/interfaces/mupad.py +++ b/src/sage/interfaces/mupad.py @@ -151,7 +151,6 @@ def __reduce__(self): sage: Mupad().__reduce__() (, ()) - """ return reduce_load_mupad, tuple([]) @@ -190,7 +189,6 @@ def _install_hints(self): In order to use the MuPAD interface you need to have MuPAD installed ... - """ return """ In order to use the MuPAD interface you need to have MuPAD installed @@ -229,7 +227,6 @@ def console(self): | *--|-* All rights reserved. |/ |/ *----* Licensed to: ... - """ mupad_console() @@ -239,7 +236,6 @@ def eval(self, code, strip=True, **kwds): sage: mupad.eval('2+2') # optional - mupad 4 - """ s = Expect.eval(self, code, **kwds) return AsciiArtString(s) @@ -255,7 +251,6 @@ def _eval_line(self, line, allow_use_file=True, wait_for_prompt=True, Traceback (most recent call last): ... RuntimeError: Unknown slot "x::asdf" [slot] - """ if self._expect is None: self._start() @@ -323,7 +318,6 @@ def get(self, var): sage: mupad.set('a', 4) # optional - mupad sage: mupad.get('a').strip() # optional - mupad '4' - """ s = self.eval('%s' % var) i = s.find('=') @@ -470,7 +464,6 @@ def _tab_completion(self): 'addRow', ... 'wiedemann'] - """ res = self._parent.completions(self._name+"::", strip=True) return res if res != [] else self._parent._tab_completion() @@ -485,7 +478,6 @@ def _instancedoc_(self): sage: x = mupad('x') # optional - mupad sage: x.diff.__doc__ # optional - mupad No help on diff available - """ return self._obj.parent().help(self._name) @@ -566,7 +558,6 @@ def __getattr__(self, attrname): sage: x = mupad('x') # optional - mupad-Combinat sage: x.diff(x) # optional - mupad-Combinat 1 - """ if attrname[:1] == "_": if attrname not in self.__dict__: @@ -615,7 +606,7 @@ def _latex_(self): def __len__(self): r""" - The analogue in MuPAD of Python's len is the method nops + The analogue in MuPAD of Python's len is the method nops. EXAMPLES:: @@ -638,7 +629,6 @@ def __len__(self): sage: [int(x) for x in mupad("{1,2,3,5}") ] # optional - mupad [1, 2, 3, 5] - """ return mupad.nops(self) @@ -673,7 +663,6 @@ def mupad_console(): | *--|-* All rights reserved. |/ |/ *----* Licensed to: ... - """ from sage.repl.rich_output.display_manager import get_display_manager if not get_display_manager().is_in_terminal(): diff --git a/src/sage/interfaces/mwrank.py b/src/sage/interfaces/mwrank.py index 63dcb214bdf..8d6af9b81d6 100644 --- a/src/sage/interfaces/mwrank.py +++ b/src/sage/interfaces/mwrank.py @@ -24,23 +24,23 @@ instances = {} -def Mwrank(options="", server=None, server_tmpdir=None): +def Mwrank(options='', server=None, server_tmpdir=None): """ Create and return an mwrank interpreter, with given options. INPUT: - - ``options`` -- string; passed when starting mwrank. - The format is:: + - ``options`` -- string; passed when starting mwrank. + The format is:: -h help prints this info and quits -q quiet turns OFF banner display and prompt -v n verbosity sets verbosity to n (default=1) - -o PARI/GP output turns ON extra PARI/GP short output (default is OFF) + -o PARI/GP output turns ON extra PARI/GP short output (default: OFF) -p n precision sets precision to n decimals (default=15) -b n quartic bound bound on quartic point search (default=10) -x n n aux number of aux primes used for sieving (default=6) - -l list turns ON listing of points (default ON unless v=0) + -l list turns ON listing of points (default: ON, unless v=0) -s selmer_only if set, computes Selmer rank only (default: not set) -d skip_2nd_descent if set, skips the second descent for curves with 2-torsion (default: not set) -S n sat_bd upper bound on saturation primes (default=100, -1 for automatic) @@ -56,7 +56,6 @@ def Mwrank(options="", server=None, server_tmpdir=None): Curve [0,0,1,-1,0] : Rank = 1 Generator 1 is [0:-1:1]; height 0.051... Regulator = 0.051... - """ global instances try: @@ -79,11 +78,11 @@ def Mwrank(options="", server=None, server_tmpdir=None): def validate_mwrank_input(s): r""" - Returns a string suitable for mwrank input, or raises an error. + Return a string suitable for mwrank input, or raises an error. INPUT: - - `s` -- one of the following: + - ``s`` -- one of the following: - a list or tuple of 5 integers [a1,a2,a3,a4,a6] or (a1,a2,a3,a4,a6) - a string of the form '[a1,a2,a3,a4,a6]' or 'a1 a2 a3 a4 a6' where a1, a2, a3, a4, a6 are integers @@ -91,7 +90,7 @@ def validate_mwrank_input(s): OUTPUT: For valid input, a string of the form '[a1,a2,a3,a4,a6]'. - For invalid input a :class:`ValueError` is raised. + For invalid input a :exc:`ValueError` is raised. EXAMPLES: @@ -124,7 +123,6 @@ def validate_mwrank_input(s): Traceback (most recent call last): ... ValueError: 0 -1 1 -7 is not valid input to mwrank - """ if isinstance(s, (list, tuple)): from sage.rings.integer_ring import ZZ @@ -150,21 +148,21 @@ class Mwrank_class(Expect): """ Interface to the Mwrank interpreter. """ - def __init__(self, options="", server=None, server_tmpdir=None): + def __init__(self, options='', server=None, server_tmpdir=None): """ INPUT: - - ``options`` -- string; passed when starting mwrank. - The format is:: + - ``options`` -- string; passed when starting mwrank. + The format is:: -h help prints this info and quits -q quiet turns OFF banner display and prompt -v n verbosity sets verbosity to n (default=1) - -o PARI/GP output turns ON extra PARI/GP short output (default is OFF) + -o PARI/GP output turns ON extra PARI/GP short output (default: OFF) -p n precision sets precision to n decimals (default=15) -b n quartic bound bound on quartic point search (default=10) -x n n aux number of aux primes used for sieving (default=6) - -l list turns ON listing of points (default ON unless v=0) + -l list turns ON listing of points (default: ON, unless v=0) -s selmer_only if set, computes Selmer rank only (default: not set) -d skip_2nd_descent if set, skips the second descent for curves with 2-torsion (default: not set) -S n sat_bd upper bound on saturation primes (default=100, -1 for automatic) @@ -245,8 +243,8 @@ def __call__(self, cmd): TESTS: - Invalid input raises an ValueError (see :issue:`10108`); this includes - syntactically valid input which defines a singular curve:: + Invalid input raises an :exc:`ValueError` (see :issue:`10108`); this + includes syntactically valid input which defines a singular curve:: sage: mwrank(10) Traceback (most recent call last): @@ -262,7 +260,6 @@ def __call__(self, cmd): Traceback (most recent call last): ... ValueError: Invalid input ([0,0,0,-3,2]) to mwrank (singular curve) - """ try: s = validate_mwrank_input(cmd) @@ -281,7 +278,7 @@ def eval(self, s, **kwds): INPUT: - - ``s`` (str) -- a Sage object which when converted to a string + - ``s`` -- string; a Sage object which when converted to a string gives valid input to ``mwrank``. The conversion is done by :meth:`validate_mwrank_input`. Possible formats are: @@ -296,7 +293,7 @@ def eval(self, s, **kwds): .. NOTE:: - If a :class:`RuntimeError` exception is raised, then the mwrank + If a :exc:`RuntimeError` exception is raised, then the mwrank interface is restarted and the command is retried once. EXAMPLES:: @@ -332,7 +329,6 @@ def console(self): sage: mwrank.console() # not tested: expects console input Program mwrank: ... - """ mwrank_console() @@ -343,7 +339,7 @@ def console(self): def _reduce_load_mwrank(): """ - Return the standard mwrank instance + Return the standard mwrank instance. EXAMPLES:: diff --git a/src/sage/interfaces/octave.py b/src/sage/interfaces/octave.py index 93bd12ade5a..5241989836b 100644 --- a/src/sage/interfaces/octave.py +++ b/src/sage/interfaces/octave.py @@ -486,7 +486,7 @@ def version(self): def solve_linear_system(self, A, b): r""" - Use octave to compute a solution x to A\*x = b, as a list. + Use Octave to compute a solution x to ``A*x = b``, as a list. INPUT: @@ -494,7 +494,7 @@ def solve_linear_system(self, A, b): - ``b`` -- m-vector b entries in `\QQ` or `\RR` (resp) - OUTPUT: A list x (if it exists) which solves M\*x = b + OUTPUT: list x (if it exists) which solves ``M*x = b`` EXAMPLES:: @@ -531,9 +531,11 @@ def sage2octave_matrix_string(self, A): """ Return an octave matrix from a Sage matrix. - INPUT: A Sage matrix with entries in the rationals or reals. + INPUT: + + - ``A`` - Sage matrix with entries in the rationals or reals - OUTPUT: A string that evaluates to an Octave matrix. + OUTPUT: string that evaluates to an Octave matrix EXAMPLES:: @@ -555,16 +557,13 @@ def de_system_plot(self, f, ics, trange): INPUT: + - ``f`` -- a pair of strings representing the + differential equations; the independent variable must be called x + and the dependent variable must be called y - - ``f`` -- a pair of strings representing the - differential equations; The independent variable must be called x - and the dependent variable must be called y. - - - ``ics`` -- a pair [x0,y0] such that x(t0) = x0, y(t0) - = y0 - - - ``trange`` -- a pair [t0,t1] + - ``ics`` -- a pair [x0,y0] such that x(t0) = x0, y(t0) = y0 + - ``trange`` -- a pair [t0,t1] OUTPUT: a gnuplot window appears @@ -607,7 +606,7 @@ def _object_class(self): def to_complex(octave_string, R): r""" - Helper function to convert octave complex number + Helper function to convert octave complex number. TESTS:: diff --git a/src/sage/interfaces/phc.py b/src/sage/interfaces/phc.py index 23dd8f3546e..3aa5964352b 100644 --- a/src/sage/interfaces/phc.py +++ b/src/sage/interfaces/phc.py @@ -52,12 +52,10 @@ def get_solution_dicts(output_file_contents, input_ring, get_failures=True): INPUT: - - output_file_contents -- phc solution output as a string - - input_ring -- a PolynomialRing that variable names can be coerced into + - ``output_file_contents`` -- phc solution output as a string + - ``input_ring`` -- a PolynomialRing that variable names can be coerced into - OUTPUT: - - a list of dictionaries of solutions + OUTPUT: list of dictionaries of solutions EXAMPLES:: @@ -103,12 +101,10 @@ def get_classified_solution_dicts(output_file_contents, input_ring, get_failures INPUT: - - output_file_contents -- phc solution output as a string - - input_ring -- a PolynomialRing that variable names can be coerced into - - OUTPUT: + - ``output_file_contents`` -- phc solution output as a string + - ``input_ring`` -- a PolynomialRing that variable names can be coerced into - - a dictionary of lists if dictionaries of solutions, classifies by type + OUTPUT: a dictionary of lists if dictionaries of solutions, classifies by type EXAMPLES:: @@ -189,8 +185,8 @@ def __init__(self, output_file_contents, input_ring): INPUT: - - output_file_contents: the string output of PHCpack - - input_ring: for coercion of the variables into the desired ring. + - ``output_file_contents`` -- the string output of PHCpack + - ``input_ring`` -- for coercion of the variables into the desired ring EXAMPLES:: @@ -269,9 +265,7 @@ def classified_solution_dicts(self): - None - OUTPUT: - - - A dictionary of lists of dictionaries of solutions + OUTPUT: a dictionary of lists of dictionaries of solutions EXAMPLES:: @@ -297,10 +291,9 @@ def solution_dicts(self, get_failures=False): INPUT: - - self -- for access to self_out_file_contents, the string - of raw PHCpack output. - - - get_failures (optional) -- a boolean. The default (False) + - ``self`` -- for access to self_out_file_contents, the string + of raw PHCpack output + - ``get_failures`` -- boolean (default: ``False``); the default is to not process failed homotopies. These either lie on positive-dimensional components or at infinity. @@ -340,15 +333,13 @@ def solutions(self, get_failures=False): INPUT: - - self -- for access to self_out_file_contents, the string - of raw PHCpack output. - - get_failures (optional) -- a boolean. The default (False) + - ``self`` -- for access to self_out_file_contents, the string + of raw PHCpack output + - ``get_failures`` -- boolean (default: ``False``); the default is to not process failed homotopies. These either lie on positive-dimensional components or at infinity. - OUTPUT: - - - solutions: a list of lists of ComplexField-valued solutions. + OUTPUT: solutions: a list of lists of ComplexField-valued solutions EXAMPLES:: @@ -427,12 +418,10 @@ def _output_from_command_list(self, command_list, polys, verbose=False): INPUT: - - command_list -- a list of commands to phc - - polys -- a polynomial system as a list of polynomials - - OUTPUT: + - ``command_list`` -- list of commands to phc + - ``polys`` -- a polynomial system as a list of polynomials - - an output string from phc + OUTPUT: an output string from phc EXAMPLES:: @@ -486,12 +475,11 @@ def _input_file(self, polys): INPUT: - - polys -- a list of polynomials in a Sage polynomial ring + - ``polys`` -- list of polynomials in a Sage polynomial ring over a field that embeds into the complex numbers - OUTPUT: - - a PHC input file (as a text string) that describes these polynomials + OUTPUT: a PHC input file (as a text string) that describes these + polynomials EXAMPLES:: @@ -510,18 +498,16 @@ def _input_file(self, polys): def _parse_path_file(self, input_filename, verbose=False): """ - Takes a phpack output file containing path tracking information + Take a phpack output file containing path tracking information and parses it into a list of lists of dictionaries - i.e. a list of solutions paths, where each solution path is a list of dictionaries of variable and homotopy parameter values. INPUT: - - input_filename -- file must have path-tracking information + - ``input_filename`` -- file must have path-tracking information - OUTPUT: - - - a list of lists of dictionaries, described above + OUTPUT: list of lists of dictionaries, described above EXAMPLES:: @@ -639,21 +625,23 @@ def _path_track_file(self, start_filename_or_string, polys, input_ring, c_skew=0 def path_track(self, start_sys, end_sys, input_ring, c_skew=.001, saved_start=None): """ - This function computes homotopy paths between the solutions of start_sys and end_sys. + This function computes homotopy paths between the solutions of + ``start_sys`` and ``end_sys``. INPUT: - - start_sys -- a square polynomial system, given as a list of polynomials - - end_sys -- same type as start_sys - - input_ring -- for coercion of the variables into the desired ring. - - c_skew -- optional. the imaginary part of homotopy multiplier; nonzero values - are often necessary to avoid intermediate path collisions - - saved_start -- optional. A phc output file. If not given, start system solutions - are computed via the phc.blackbox function. - - OUTPUT: + - ``start_sys`` -- a square polynomial system, given as a list of + polynomials + - ``end_sys`` -- same type as ``start_sys`` + - ``input_ring`` -- for coercion of the variables into the desired ring + - ``c_skew`` -- (optional) the imaginary part of homotopy multiplier; + nonzero values are often necessary to avoid intermediate path + collisions + - ``saved_start`` -- (optional) a phc output file; if not given, start + system solutions are computed via the ``phc.blackbox`` function - - a list of paths as dictionaries, with the keys variables and t-values on the path. + OUTPUT: list of paths as dictionaries, with the keys variables and + t-values on the path EXAMPLES:: @@ -681,18 +669,19 @@ def plot_paths_2d(self, start_sys, end_sys, input_ring, c_skew=.001, endpoints=T INPUT: - - start_sys -- a square polynomial system, given as a list of polynomials - - end_sys -- same type as start_sys - - input_ring -- for coercion of the variables into the desired ring. - - c_skew -- optional. the imaginary part of homotopy multiplier; nonzero values - are often necessary to avoid intermediate path collisions - - endpoints -- optional. Whether to draw in the ends of paths as points. - - saved_start -- optional. A phc output file. If not given, start system solutions - are computed via the phc.blackbox function. - - OUTPUT: + - ``start_sys`` -- a square polynomial system, given as a list of + polynomials + - ``end_sys`` -- same type as start_sys + - ``input_ring`` -- for coercion of the variables into the desired ring + - ``c_skew`` -- (optional) the imaginary part of homotopy multiplier; + nonzero values are often necessary to avoid intermediate path + collisions + - ``endpoints`` -- (optional) whether to draw in the ends of paths as + points + - ``saved_start`` -- (optional) a phc output file; if not given, start + system solutions are computed via the ``phc.blackbox`` function - - lines and points of solution paths + OUTPUT: lines and points of solution paths EXAMPLES:: @@ -742,13 +731,11 @@ def mixed_volume(self, polys, verbose=False): INPUT: - - polys -- a list of multivariate polynomials (elements of a multivariate + - ``polys`` -- list of multivariate polynomials (elements of a multivariate polynomial ring). - - verbose -- print lots of verbose information about what this function does. + - ``verbose`` -- print lots of verbose information about what this function does - OUTPUT: - - - The mixed volume. + OUTPUT: the mixed volume EXAMPLES:: @@ -783,19 +770,17 @@ def start_from(self, start_filename_or_string, polys, input_ring, path_track_fil INPUT: - - start_filename_or_string -- the filename for a phcpack start system, + - ``start_filename_or_string`` -- the filename for a phcpack start system, or the contents of such a file as a string. Variable names must match the inputring variables. The value of the homotopy variable t should be 1, not 0. - - polys -- a list of multivariate polynomials (elements of a multivariate + - ``polys`` -- list of multivariate polynomials (elements of a multivariate polynomial ring). - input_ring: for coercion of the variables into the desired ring. - path_track_file: whether to save path-tracking information - - verbose -- print lots of verbose information about what this function does. - - OUTPUT: + - ``verbose`` -- print lots of verbose information about what this function does - - A solution in the form of a PHCObject. + OUTPUT: a solution in the form of a PHCObject EXAMPLES:: @@ -887,14 +872,12 @@ def blackbox(self, polys, input_ring, verbose=False): INPUT: - - polys -- a list of multivariate polynomials (elements of a multivariate + - ``polys`` -- list of multivariate polynomials (elements of a multivariate polynomial ring). - - input_ring -- for coercion of the variables into the desired ring. - - verbose -- print lots of verbose information about what this function does. - - OUTPUT: + - ``input_ring`` -- for coercion of the variables into the desired ring + - ``verbose`` -- print lots of verbose information about what this function does - - a PHC_Object object containing the phcpack output string. + OUTPUT: a PHC_Object object containing the phcpack output string EXAMPLES:: diff --git a/src/sage/interfaces/polymake.py b/src/sage/interfaces/polymake.py index a3418e1a773..94ad62153a9 100644 --- a/src/sage/interfaces/polymake.py +++ b/src/sage/interfaces/polymake.py @@ -59,7 +59,6 @@ class PolymakeError(RuntimeError): Traceback (most recent call last): ... PolymakeError: Unquoted string "foo" may clash with future reserved word... - """ pass @@ -86,7 +85,6 @@ def polymake_console(command=''): 4ti2, bliss, cdd, latte, libnormaliz, lrs, permlib, ppl, sketch, sympol, threejs, tikz, topcom, tosimplex For more details: show_credits; polytope > - """ from sage.repl.rich_output.display_manager import get_display_manager if not get_display_manager().is_in_terminal(): @@ -149,7 +147,7 @@ def version(self): """ return self.get('$Polymake::Version') - # Pickling etc + # Pickling, etc. def __reduce__(self): """ @@ -158,7 +156,6 @@ def __reduce__(self): sage: from sage.interfaces.polymake import polymake sage: loads(dumps(polymake)) is polymake True - """ return reduce_load_Polymake, () @@ -173,7 +170,6 @@ def _object_class(self): cube of dimension 3 sage: type(C) # optional - jupymake - """ return PolymakeElement @@ -211,7 +207,6 @@ def _function_element_class(self): N_FACETS : FACETS precondition : COMBINATORIAL_DIM ( F_VECTOR : N_FACETS, N_RAYS, GRAPH.N_EDGES, DUAL_GRAPH.N_EDGES, COMBINATORIAL_DIM ) F_VECTOR : N_FACETS, N_RAYS, GRAPH.N_EDGES, DUAL_GRAPH.N_EDGES, COMBINATORIAL_DIM - """ return PolymakeFunctionElement @@ -221,7 +216,6 @@ def function_call(self, function, args=None, kwds=None): sage: polymake.rand_sphere(4, 30, seed=15) # optional - jupymake # indirect doctest Random spherical polytope of dimension 4; seed=15... - """ args, kwds = self._convert_args_kwds(args, kwds) self._check_valid_function_name(function) @@ -232,7 +226,7 @@ def function_call(self, function, args=None, kwds=None): def _function_call_string(self, function, args, kwds): """ - Returns the string used to make function calls. + Return the string used to make function calls. EXAMPLES:: @@ -247,7 +241,6 @@ def _function_call_string(self, function, args, kwds): 1 7 7 sage: c.GROUP full combinatorial group - """ if kwds: if args: @@ -347,7 +340,6 @@ def console(self): Traceback (most recent call last): ... NotImplementedError: Please use polymake_console() function or the .interact() method - """ raise NotImplementedError("Please use polymake_console() function or the .interact() method") @@ -361,7 +353,6 @@ def _install_hints(self): Please install the optional polymake package for sage or install polymake system-wide (use the shell command 'sage --info polymake' for more information) - """ return "Please install the optional polymake package for sage" + os.linesep + "or install polymake system-wide" + os.linesep + "(use the shell command 'sage --info polymake' for more information)" @@ -383,7 +374,6 @@ def _start(self): sage: 'normal_fan' in dir(polymake) # optional - jupymake False - """ self.application("polytope") self.eval('use Scalar::Util qw(reftype);') @@ -430,7 +420,7 @@ def _read_in_file_command(self, filename): def _next_var_name(self): r""" - Returns the next unused variable name. + Return the next unused variable name. TESTS:: @@ -464,7 +454,6 @@ def clear(self, var): 1 sage: polymake._next_var_name() in old True - """ self._available_vars.append(_name_pattern.search(var).group()) @@ -496,15 +485,14 @@ def _create(self, value, name=None): EXAMPLES:: sage: # optional - jupymake - sage: polymake._create("('foo', 'bar')", name="my_array") + sage: polymake._create("('foo', 'bar')", name='my_array') '@my_array' sage: print(polymake.eval('print join(", ", @my_array);')) foo, bar - sage: polymake._create('"foobar"', name="my_string") + sage: polymake._create('"foobar"', name='my_string') '$my_string[0]' sage: print(polymake.eval('print $my_string[0];')) foobar - """ name = self._next_var_name() if name is None else name self.set(name, value) @@ -591,7 +579,6 @@ def set(self, var, value): 1 0 0 0 3/2 0 0 0 0 sage: P.F_VECTOR # optional - jupymake 9 36 84 126 126 84 36 9 - """ if isinstance(value, str): value = value.strip().rstrip(';').strip() @@ -612,8 +599,6 @@ def get(self, cmd): sage: polymake('cube(3)') # optional - jupymake cube of dimension 3 - - """ return self.eval("print {};".format(cmd)).strip() @@ -623,8 +608,9 @@ def help(self, topic, pager=True): INPUT: - - ``topic``, a string - - ``pager``, optional bool, default ``True``: When True, display help, otherwise return as a string. + - ``topic`` -- string + - ``pager`` -- boolean (default: ``True``); when ``True``, display + help, otherwise return as a string EXAMPLES:: @@ -654,7 +640,7 @@ def help(self, topic, pager=True): 4: objects/PointConfiguration/properties/Triangulation and volume/TRIANGULATION 5: objects/Polytope/properties/Triangulation and volume/TRIANGULATION - If an unknown help topic is requested, a :class:`PolymakeError` + If an unknown help topic is requested, a :exc:`PolymakeError` results:: sage: polymake.help('Triangulation') # optional - jupymake @@ -729,8 +715,9 @@ def application(self, app): INPUT: - - ``app``, a string, one of "common", "fulton", "group", "matroid", "topaz", - "fan", "graph", "ideal", "polytope", "tropical" + - ``app`` -- string; one of ``'common'``, ``'fulton'``, ``'group'``, + ``'matroid'``, ``'topaz'``, ``'fan'``, ``'graph'``, ``'ideal'``, + ``'polytope'``, ``'tropical'`` EXAMPLES: @@ -808,7 +795,6 @@ def application(self, app): Traceback (most recent call last): ... PolymakeError: Unknown application killerapp - """ if app not in ["common", "fulton", "group", "matroid", "topaz", "fan", "graph", "ideal", "polytope", "tropical"]: raise ValueError("Unknown polymake application '{}'".format(app)) @@ -839,7 +825,6 @@ def new_object(self, name, *args, **kwds): 1 3 1 8 sage: q.full_typename() 'Polytope' - """ try: f = self.__new[name] @@ -874,7 +859,6 @@ class PolymakeElement(ExtraTabCompletion, InterfaceElement): sage: p.VERTICES[2][2] # optional - jupymake 1450479926727001/2251799813685248 - """ def _repr_(self): """ @@ -958,7 +942,6 @@ def _repr_(self): 'Map' sage: p.TWO_FACE_SIZES # optional - jupymake {(3 20)} - """ T1, T2 = self.typeof() P = self._check_valid() @@ -1019,7 +1002,6 @@ def _richcmp_(self, other, op): 12 30 20 sage: p1.get_member('list_properties') == p2.get_member('list_properties') # optional - jupymake False - """ P = self._check_valid() if P.eval("print {} {} {};".format(self.name(), P._equality_symbol(), other.name())).strip() == P._true_symbol(): @@ -1041,7 +1023,6 @@ def __bool__(self): False sage: bool(polymake(1)) # optional - jupymake True - """ P = self._check_valid() t = P._true_symbol() @@ -1085,7 +1066,6 @@ def known_properties(self): 'CONE_DIM', ... 'VERTICES_IN_FACETS'] - """ P = self._check_valid() try: @@ -1108,7 +1088,6 @@ def _member_list(self): ... 'WEAKLY_CENTERED', ...] - """ # return the members of a "big" object. P = self._check_valid() @@ -1135,7 +1114,6 @@ def typename(self): 'Polytope' sage: c.VERTICES.typename() # optional - jupymake 'Matrix' - """ P = self._check_valid() try: @@ -1154,7 +1132,6 @@ def full_typename(self): 'Polytope' sage: c.VERTICES.full_typename() # optional - jupymake 'Matrix' - """ P = self._check_valid() try: @@ -1173,7 +1150,6 @@ def qualified_typename(self): 'polytope::Polytope' sage: c.VERTICES.qualified_typename() # optional - jupymake 'common::Matrix' - """ P = self._check_valid() try: @@ -1204,7 +1180,6 @@ def _tab_completion(self): 'zonotope', 'zonotope_tiling_lattice', 'zonotope_vertices_fukuda'] - """ return sorted(self._member_list()+self.parent()._tab_completion()) @@ -1260,7 +1235,6 @@ def __getattr__(self, attrname): Member function 'contains' of Polymake::polytope::Polytope__Rational object sage: c.contains(V) true - """ P = self._check_valid() if attrname[:1] == "_": @@ -1348,7 +1322,6 @@ def get_member(self, attrname): sage: p.type() # optional - jupymake Polytope[SAGE...] - """ P = self._check_valid() return P('{}->{}'.format(self.name(), attrname)) @@ -1420,7 +1393,6 @@ def __len__(self): 20 sage: len(p.list_properties()) >= 12 # optional - jupymake True - """ P = self._check_valid() T1, T2 = self.typeof() @@ -1470,7 +1442,7 @@ def typeof(self): def _sage_(self): """ - Convert self to a Sage object. + Convert ``self`` to a Sage object. EXAMPLES:: @@ -1521,7 +1493,6 @@ def _sage_(self): A 3-dimensional polyhedron in (Number Field in a with defining polynomial x^2 - 5 with a = 2.236067977499790?)^3 defined as the convex hull of 12 vertices - """ T1, T2 = self.typeof() self._check_valid() @@ -1627,7 +1598,6 @@ def _sage_doc_(self): (5) (5) (0 3) (1 -1) . - """ P = self._check_valid() # according to Julian Pfeifle, the only case in which the fully qualified @@ -1683,17 +1653,18 @@ class PolymakeFunctionElement(InterfaceFunctionElement): Member function 'contains' of Polymake::polytope::Polytope__Rational object sage: c.contains(V) true - """ def __init__(self, obj, name, memberfunction=False): """ INPUT: - - Polymake object that this function is bound to - - name (string): It actually says how to call this function in polymake. - So, if it is a member function, it will look like `"$SAGE123[0]->func_name"`. - - ``memberfunction`` (bool, default: ``False``): Whether this is a member function - or a plain function applied with this element as first argument. + - ``obj`` -- Polymake object that this function is bound to + - ``name`` -- string; it actually says how to call this function in + polymake. So, if it is a member function, it will look like + `"$SAGE123[0]->func_name"`. + - ``memberfunction`` -- boolean (default: ``False``); whether this is a + member function or a plain function applied with this element as + first argument EXAMPLES:: @@ -1702,7 +1673,6 @@ def __init__(self, obj, name, memberfunction=False): minkowski_sum_fukuda (bound to Polymake::polytope::Polytope__Rational object) sage: p.get_schedule # optional - jupymake Member function 'get_schedule' of Polymake::polytope::Polytope__Rational object - """ self._obj = obj self._name = name @@ -1717,7 +1687,6 @@ def _repr_(self): minkowski_sum_fukuda (bound to Polymake::polytope::Polytope__Rational object) sage: p.contains # optional - jupymake Member function 'contains' of Polymake::polytope::Polytope__Rational object - """ if self._is_memberfunc: return "Member function '{}' of {} object".format(self._name.split("->")[-1], self._obj.typeof()[0]) @@ -1736,7 +1705,6 @@ def __call__(self, *args, **kwds): cdd.convex_hull.canon: POINTED, RAYS, LINEALITY_SPACE : INPUT_RAYS sage: p.minkowski_sum_fukuda(p).F_VECTOR # optional - jupymake # not tested 13 33 22 - """ if self._is_memberfunc: return self._obj._check_valid().function_call(self._name, list(args), kwds) @@ -1793,7 +1761,6 @@ def _sage_doc_(self): 1 -2 2 1 -1 3 1 1 3 - """ P = self._obj._check_valid() return P.help(self._name.split("->")[-1], pager=False) @@ -1956,7 +1923,7 @@ def eval(self, code, **kwds): sage: set_verbose(0) If polymake raises an error, the polymake *interface* raises - a :class:`PolymakeError`:: + a :exc:`PolymakeError`:: sage: polymake.eval('FOOBAR(3);') # optional - jupymake Traceback (most recent call last): diff --git a/src/sage/interfaces/povray.py b/src/sage/interfaces/povray.py index b892cb112cd..6e7a6c8ef94 100644 --- a/src/sage/interfaces/povray.py +++ b/src/sage/interfaces/povray.py @@ -16,9 +16,7 @@ class POVRay: - ``outfile`` -- the filename you want to save your result to - ``**kwargs`` -- additionally keyword arguments you want to pass to POVRay - OUTPUT: - - Image is written to the file you specified in outfile + OUTPUT: image is written to the file you specified in outfile EXAMPLES: diff --git a/src/sage/interfaces/process.pyx b/src/sage/interfaces/process.pyx index 016de82a30f..4003324f7aa 100644 --- a/src/sage/interfaces/process.pyx +++ b/src/sage/interfaces/process.pyx @@ -37,15 +37,15 @@ cdef class ContainChildren(): INPUT: - - ``exitcode`` -- (integer, default 0) exit code to use when a + - ``exitcode`` -- integer (default: 0); exit code to use when a child process tries to exit the with block normally (not due to an exception) - - ``exceptcode`` -- (integer, default 1) exit code to use when a + - ``exceptcode`` -- integer (default: 1); exit code to use when a child process tries to exit the with block due to an exception - - ``silent`` -- (boolean, default ``False``) if ``False``, print - exceptions raised by the child process. + - ``silent`` -- boolean (default: ``False``); if ``False``, print + exceptions raised by the child process EXAMPLES:: @@ -186,7 +186,7 @@ def terminate(sp, interval=1, signals=[signal.SIGTERM, signal.SIGKILL]): INPUT: - ``sp`` -- a `subprocess.Popen` instance - - ``interval`` -- (float, default 1) interval in seconds between + - ``interval`` -- float (default: 1); interval in seconds between termination attempts - ``signals`` -- (list, default [signal.SIGTERM, signal.SIGKILL]) the signals to send the process in order to terminate it diff --git a/src/sage/interfaces/psage.py b/src/sage/interfaces/psage.py index ec583218c1e..96d4233bbeb 100644 --- a/src/sage/interfaces/psage.py +++ b/src/sage/interfaces/psage.py @@ -72,7 +72,6 @@ def _repr_(self): sage: from sage.interfaces.psage import PSage sage: PSage() # indirect doctest A running non-blocking (parallel) instance of Sage (number ...) - """ return 'A running non-blocking (parallel) instance of Sage (number %s)' % (self._number) diff --git a/src/sage/interfaces/qepcad.py b/src/sage/interfaces/qepcad.py index 68d8724e79b..df9f1583c86 100644 --- a/src/sage/interfaces/qepcad.py +++ b/src/sage/interfaces/qepcad.py @@ -627,7 +627,7 @@ def _qepcad_atoms(formula): INPUT: - - `formula` (string) -- a quantifier-free formula. + - ``formula`` -- string; a quantifier-free formula .. NOTE:: @@ -773,7 +773,7 @@ def __init__(self, memcells=None, Qepcad """ Expect.__init__(self, - name="QEPCAD", + name='QEPCAD', # yuck: when QEPCAD first starts, # it doesn't give prompts prompt="\nEnter an .*:\r", @@ -1528,7 +1528,7 @@ def qepcad(formula, assume=None, interact=False, solution=None, sage: qepcad(qf.all_but_finitely_many(x, a*x^2 + b*x + c != 0)) # not tested (random order) b /= 0 \/ a /= 0 \/ c /= 0 - The non-zeroes are continuous iff there are no zeroes or if + The nonzeroes are continuous iff there are no zeroes or if the polynomial is zero. :: sage: qepcad(qf.connected_subset(x, a*x^2 + b*x + c != 0)) # not tested (random order) @@ -1871,12 +1871,12 @@ def _combine_formulas(self, formulas): INPUT: - - ``formulas`` -- a list of unquantified formulas + - ``formulas`` -- list of unquantified formulas OUTPUT: - - form_strs -- a list of formulas as strings - - vars -- a frozenset of all variables in the formulas + - ``form_strs`` -- list of formulas as strings + - ``vars`` -- frozenset of all variables in the formulas EXAMPLES:: @@ -1947,7 +1947,7 @@ def atomic(self, lhs, op='=', rhs=0): def formula(self, formula): r""" - Constructs a QEPCAD formula from the given input. + Construct a QEPCAD formula from the given input. INPUT: diff --git a/src/sage/interfaces/quit.py b/src/sage/interfaces/quit.py index d93cdf2730a..9392ffe094f 100644 --- a/src/sage/interfaces/quit.py +++ b/src/sage/interfaces/quit.py @@ -24,7 +24,6 @@ def sage_spawned_process_file(): sage: from sage.interfaces.quit import sage_spawned_process_file sage: len(sage_spawned_process_file()) > 1 True - """ # This is the old value of SAGE_TMP. Until sage-cleaner is # completely removed, we need to leave these spawned_processes @@ -88,7 +87,7 @@ def kill_spawned_jobs(verbose=False): """ INPUT: - - ``verbose`` -- bool (default: ``False``); if ``True``, display a + - ``verbose`` -- boolean (default: ``False``); if ``True``, display a message each time a process is sent a kill signal EXAMPLES:: @@ -124,7 +123,7 @@ def kill_spawned_jobs(verbose=False): def is_running(pid): """ - Return True if and only if there is a process with id pid running. + Return ``True`` if and only if there is a process with id pid running. """ try: os.kill(int(pid), 0) diff --git a/src/sage/interfaces/r.py b/src/sage/interfaces/r.py index 33addb28afa..b44fe1381ff 100644 --- a/src/sage/interfaces/r.py +++ b/src/sage/interfaces/r.py @@ -156,7 +156,7 @@ Distributions:: - sage: r.options(width="60") + sage: r.options(width='60') $width [1] 80 @@ -347,7 +347,7 @@ def _setup_r_to_sage_converter(): '_Names': ['Min.', '1st Qu.', 'Median', 'Mean', '3rd Qu.', 'Max.'], '_r_class': ['summaryDefault', 'table']} - sage: r.options(width="60").sage() + sage: r.options(width='60').sage() {'DATA': {'width': 60}, '_Names': 'width'} The conversion can handle "not a number", infinity, imaginary values and @@ -606,7 +606,7 @@ def _start(self): def png(self, *args, **kwds): """ - Creates an R PNG device. + Create an R PNG device. This should primarily be used to save an R graphic to a custom file. Note that when using this in the notebook, one must plot in the same cell that @@ -645,7 +645,7 @@ def png(self, *args, **kwds): def convert_r_list(self, l): r""" - Converts an R list to a Python list. + Convert an R list to a Python list. EXAMPLES:: @@ -772,11 +772,11 @@ def _install_hints(self): def _source(self, s): """ - Returns the source code of an R function as a string. + Return the source code of an R function as a string. INPUT: - - s -- the name of the function as a string + - ``s`` -- the name of the function as a string EXAMPLES:: @@ -793,9 +793,9 @@ def source(self, s): INPUT: - - s -- a string representing the function whose source code you want to see + - ``s`` -- string representing the function whose source code you want to see - OUTPUT: string -- source code + OUTPUT: string; source code EXAMPLES:: @@ -836,12 +836,12 @@ def library(self, library_name): """ Load the library library_name into the R interpreter. - This function raises an ImportError if the given library + This function raises an :exc:`ImportError` if the given library is not known. INPUT: - - library_name -- string + - ``library_name`` -- string EXAMPLES:: @@ -870,13 +870,13 @@ def library(self, library_name): def available_packages(self): """ - Returns a list of all available R package names. + Return a list of all available R package names. This list is not necessarily sorted. OUTPUT: list of strings - .. note:: + .. NOTE:: This requires an internet connection. The CRAN server is that is checked is defined at the top of sage/interfaces/r.py. @@ -912,7 +912,7 @@ def _object_class(self): def _true_symbol(self): """ - Return the symbol that represents True in R. + Return the symbol that represents ``True`` in R. OUTPUT: string @@ -927,7 +927,7 @@ def _true_symbol(self): def _false_symbol(self): """ - Return the symbol that represents True in R. + Return the symbol that represents ``True`` in R. OUTPUT: string @@ -971,12 +971,14 @@ def _loaded_package_pages(self, topic): def help(self, command): """ - Returns help string for a given command. + Return help string for a given command. INPUT: - - command -- a string - OUTPUT: HelpExpression -- a subclass of string whose __repr__ method is __str__, so it prints nicely + - ``command`` -- string + + OUTPUT: HelpExpression; a subclass of string whose ``__repr__`` + method is ``__str__``, so it prints nicely EXAMPLES:: @@ -1016,7 +1018,7 @@ def _assign_symbol(self): def _left_list_delim(self): """ - Return the left delimiter for lists in R, which is 'c(' + Return the left delimiter for lists in R, which is 'c('. OUTPUT: string @@ -1029,7 +1031,7 @@ def _left_list_delim(self): def _right_list_delim(self): """ - Return the right delimiter for lists in R, which is 'c(' + Return the right delimiter for lists in R, which is 'c('. OUTPUT: string @@ -1042,7 +1044,7 @@ def _right_list_delim(self): def console(self): """ - Runs the R console as a separate new R process. + Run the R console as a separate new R process. EXAMPLES:: @@ -1058,7 +1060,7 @@ def function_call(self, function, args=None, kwds=None): """ Return the result of calling an R function, with given args and keyword args. - OUTPUT: RElement -- an object in R + OUTPUT: RElement; an object in R EXAMPLES:: @@ -1083,10 +1085,10 @@ def call(self, function_name, *args, **kwds): def _an_element_(self): """ - Returns an element belonging to the R interpreter. This is used + Return an element belonging to the R interpreter. This is used behind the scenes when doing things like comparisons, etc. - OUTPUT: RElement -- an R element. + OUTPUT: RElement; an R element EXAMPLES:: @@ -1103,8 +1105,8 @@ def set(self, var, value): INPUT: - - var -- a string - - value -- a string + - ``var`` -- string + - ``value`` -- string EXAMPLES:: @@ -1116,11 +1118,11 @@ def set(self, var, value): def get(self, var): """ - Returns the string representation of the variable var. + Return the string representation of the variable var. INPUT: - - var -- a string + - ``var`` -- string OUTPUT: string @@ -1134,9 +1136,9 @@ def get(self, var): def na(self): """ - Returns the NA in R. + Return the NA in R. - OUTPUT: RElement -- an element of R + OUTPUT: RElement; an element of R EXAMPLES:: @@ -1152,9 +1154,9 @@ def completions(self, s): INPUT: - - s -- string + - ``s`` -- string - OUTPUT: list -- a list of strings + OUTPUT: list of strings EXAMPLES:: @@ -1168,7 +1170,7 @@ def _commands(self): """ Return list of all commands defined in R. - OUTPUT: list -- a sorted list of strings + OUTPUT: list; a sorted list of strings EXAMPLES:: @@ -1214,11 +1216,12 @@ def _tab_completion(self, verbose=True, use_disk_cache=True): INPUT: - - verbose -- bool (default: ``True``); if True, display debugging information - - use_disk_cache -- bool (default: ``True``); if True, use the disk cache of - tab completions to save time. + - ``verbose`` -- boolean (default: ``True``); if ``True``, display + debugging information + - ``use_disk_cache`` -- boolean (default: ``True``); if ``True``, use + the disk cache of tab completions to save time - OUTPUT: list -- list of string + OUTPUT: list of string EXAMPLES:: @@ -1299,7 +1302,7 @@ def plot(self, *args, **kwds): sage: r.quartz() sage: r.hist("rnorm(100)") sage: r.library("lattice") - sage: r.histogram(x = "~ wt | cyl", data="mtcars") + sage: r.histogram(x = '~ wt | cyl', data='mtcars') sage: r.dev_off() In the notebook, one can use r.png() to open the device, but @@ -1333,15 +1336,15 @@ def eval(self, code, *args, **kwds): def _r_to_sage_name(self, s): """ - Returns a Sage/Python identifier from an R one. This involves + Return a Sage/Python identifier from an R one. This involves replacing periods with underscores, <- with __, and prepending _ in front of Python keywords. INPUT: - - s -- a string + - ``s`` -- string - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -1389,13 +1392,13 @@ def _sage_to_r_name(self, s): def __getitem__(self, s): """ - Returns the RFunction with name s. + Return the RFunction with name s. INPUT: - - s -- a string + - ``s`` -- string - OUTPUT: RFunction -- the R function that in R has name s + OUTPUT: RFunction; the R function that in R has name s EXAMPLES:: @@ -1408,11 +1411,11 @@ def __getitem__(self, s): def chdir(self, dir): """ - Changes the working directory to ``dir`` + Changes the working directory to ``dir``. INPUT: - - ``dir`` -- the directory to change to. + - ``dir`` -- the directory to change to EXAMPLES:: @@ -1439,7 +1442,7 @@ def _tab_completion(self): """ Return a list of all methods of this object. - .. note:: + .. NOTE:: Currently returns all R commands. @@ -1482,7 +1485,6 @@ def is_string(self): True sage: r([1,2,3]).is_string() False - """ return isinstance(self.sage(), str) @@ -1507,7 +1509,7 @@ def __getattr__(self, attrname): INPUT: - - attrname -- string + - ``attrname`` -- string OUTPUT: RFunctionElement @@ -1533,11 +1535,12 @@ def __getattr__(self, attrname): def __getitem__(self, n): """ - Return element(s) of self. + Return element(s) of ``self``. INPUT: - - n -- an integer, a tuple, a string that makes sense to R, or an RElement + - ``n`` -- integer, a tuple, a string that makes sense to R, or an + RElement OUTPUT: RElement @@ -1593,11 +1596,12 @@ def __getitem__(self, n): def __bool__(self): """ - Implements bool(self). + Implement ``bool(self)``. - .. note:: + .. NOTE:: - bool(self) will only return True if self == 0 contains a FALSE in its representation. + bool(self) will only return ``True`` if ``self == 0`` contains a + FALSE in its representation. EXAMPLES:: @@ -1620,10 +1624,10 @@ def _comparison(self, other, symbol): INPUT: - - other -- RElement - - symbol -- string + - ``other`` -- RElement + - ``symbol`` -- string - OUTPUT: RElement -- output is an R element; not a bool! + OUTPUT: RElement; output is an R element (not a bool!) TESTS:: @@ -1641,9 +1645,9 @@ def __eq__(self, other): INPUT: - - other -- RElement + - ``other`` -- RElement - OUTPUT: RElement -- an R element; not a bool! + OUTPUT: RElement; an R element (not a bool!) EXAMPLES: @@ -1661,9 +1665,9 @@ def __lt__(self, other): INPUT: - - other -- RElement + - ``other`` -- RElement - OUTPUT: RElement -- an R element; not a bool! + OUTPUT: RElement; an R element (not a bool!) EXAMPLES: @@ -1681,9 +1685,9 @@ def __gt__(self, other): INPUT: - - other -- RElement + - ``other`` -- RElement - OUTPUT: RElement -- an R element; not a bool! + OUTPUT: RElement; an R element (not a bool!) EXAMPLES: @@ -1701,9 +1705,9 @@ def __le__(self, other): INPUT: - - other -- RElement + - ``other`` -- RElement - OUTPUT: RElement -- an R element; not a bool! + OUTPUT: RElement; an R element (not a bool!) EXAMPLES:: @@ -1719,9 +1723,9 @@ def __ge__(self, other): INPUT: - - other -- RElement + - ``other`` -- RElement - OUTPUT: RElement -- an R element; not a bool! + OUTPUT: RElement; an R element (not a bool!) EXAMPLES:: @@ -1737,26 +1741,25 @@ def __ne__(self, other): INPUT: - - other -- RElement + - ``other`` -- RElement - OUTPUT: RElement -- an R element; not a bool! + OUTPUT: RElement; an R element (not a bool!) EXAMPLES:: sage: x = r([10.4,5.6,3.1,6.4,21.7]) sage: x != 10.4 [1] FALSE TRUE TRUE TRUE TRUE - """ return self._comparison(other, "!=") def dot_product(self, other): """ - Implements the notation self . other. + Implement the notation ``self . other``. INPUT: - - self, other -- R elements + - ``self``, ``other`` -- R elements OUTPUT: R element @@ -1782,7 +1785,7 @@ def dot_product(self, other): def _sage_(self): r""" - Returns Sage representation of the R object. + Return Sage representation of the R object. R objects are basic C structures, of different kind, that can be stacked together. This is similar to Python lists with @@ -1790,7 +1793,7 @@ def _sage_(self): names, they are translated to a Python dictionary, with anonymous list entries called ``#{number}``. - OUTPUT: object -- Python object + OUTPUT: object; Python object EXAMPLES:: @@ -1849,7 +1852,7 @@ def __reduce__(self): def _instancedoc_(self): """ - Returns the help for self as a string. + Return the help for ``self`` as a string. EXAMPLES:: @@ -1872,7 +1875,7 @@ def _instancedoc_(self): def _sage_src_(self): """ - Returns the source code of self. + Return the source code of ``self``. EXAMPLES:: @@ -1904,9 +1907,9 @@ def __init__(self, parent, name, r_name=None): INPUT: - - parent -- the R interface - - name -- the name of the function for Python - - r_name -- the name of the function in R itself (which can have dots in it) + - ``parent`` -- the R interface + - ``name`` -- the name of the function for Python + - ``r_name`` -- the name of the function in R itself (which can have dots in it) EXAMPLES:: @@ -1947,7 +1950,7 @@ def __ne__(self, other): def _instancedoc_(self): """ - Returns the help for self. + Return the help for ``self``. EXAMPLES:: @@ -1969,14 +1972,13 @@ def _instancedoc_(self): def _sage_src_(self): """ - Returns the source of self. + Return the source of ``self``. EXAMPLES:: sage: length = r.length sage: print(length._sage_src_()) function (x) .Primitive("length") - """ M = self._parent return M.source(self._name) @@ -1994,13 +1996,13 @@ def __call__(self, *args, **kwds): def is_RElement(x): """ - Return True if x is an element in an R interface. + Return ``True`` if x is an element in an R interface. INPUT: - - x -- object + - ``x`` -- object - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/interfaces/read_data.py b/src/sage/interfaces/read_data.py index 15d71a06b12..cc6f0b82fab 100644 --- a/src/sage/interfaces/read_data.py +++ b/src/sage/interfaces/read_data.py @@ -12,17 +12,15 @@ def read_data(f, t): r""" - Read data from file 'f' and class 't' (one element per line), + Read data from file ``f`` and class ``t`` (one element per line), and returns a list of elements. INPUT: - - 'f' -- a file name - - 't' -- a class (objects will be coerced to that class) + - ``f`` -- a file name + - ``t`` -- a class (objects will be coerced to that class) - OUTPUT: - - a list of elements of class 't' + OUTPUT: list of elements of class ``t`` EXAMPLES:: diff --git a/src/sage/interfaces/sage0.py b/src/sage/interfaces/sage0.py index 7843b799416..eb72c0a7186 100644 --- a/src/sage/interfaces/sage0.py +++ b/src/sage/interfaces/sage0.py @@ -35,12 +35,11 @@ class Sage(ExtraTabCompletion, Expect): INPUT: - - - ``server`` -- (optional); if specified runs Sage on a - remote machine with address. You must have ssh keys setup so you - can login to the remote machine by typing "ssh remote_machine" and - no password, call _install_hints_ssh() for hints on how to do - that. + - ``server`` -- (optional) if specified runs Sage on a + remote machine with address. You must have ssh keys setup so you + can login to the remote machine by typing "ssh remote_machine" and + no password, call _install_hints_ssh() for hints on how to do + that. The version of Sage should be the same as on the local machine, @@ -126,8 +125,7 @@ class Sage(ExtraTabCompletion, Expect): The double quotes are needed because the call to s3 first evaluates its arguments using the s interpreter, so the call to s3 is passed - ``s('"x"')``, which is the string ``"x"`` - in the s interpreter. + ``s('"x"')``, which is the string ``'x'`` in the s interpreter. """ def __init__(self, logfile=None, @@ -246,7 +244,6 @@ def __call__(self, x): sage: sage0(axiom(x^2+1)) #optional - axiom x^2 + 1 - """ if isinstance(x, ExpectElement): if x.parent() is self: @@ -289,7 +286,7 @@ def _quit_string(self): def preparse(self, x): """ - Returns the preparsed version of the string s. + Return the preparsed version of the string s. EXAMPLES:: @@ -308,11 +305,9 @@ def eval(self, line, strip=True, **kwds): INPUT: + - ``line`` -- input line of code - - ``line`` -- input line of code - - - ``strip`` -- ignored - + - ``strip`` -- ignored EXAMPLES:: @@ -355,8 +350,8 @@ def clear(self, var): """ Clear the variable named var. - Note that the exact format of the NameError for a cleared variable - is slightly platform dependent, see :issue:`10539`. + Note that the exact format of the :exc:`NameError` for a cleared + variable is slightly platform dependent, see :issue:`10539`. EXAMPLES:: @@ -459,7 +454,7 @@ class SageElement(ExpectElement): def _rich_repr_(self, display_manager, **kwds): """ - Disable rich output + Disable rich output. This is necessary because otherwise our :meth:`__getattr__` would be called. @@ -503,7 +498,7 @@ def __getattr__(self, attrname): def _sage_(self): """ - Return local copy of self. + Return local copy of ``self``. EXAMPLES:: diff --git a/src/sage/interfaces/sagespawn.pyx b/src/sage/interfaces/sagespawn.pyx index f146fa01ddb..9cd5bf799c1 100644 --- a/src/sage/interfaces/sagespawn.pyx +++ b/src/sage/interfaces/sagespawn.pyx @@ -40,13 +40,13 @@ class SageSpawn(spawn): """ Spawn a subprocess in a pseudo-tty. - - ``*args``, ``**kwds``: see :class:`pexpect.spawn`. + - ``*args``, ``**kwds`` -- see :class:`pexpect.spawn` - ``name`` -- human-readable name for this process, used for - display purposes only. + display purposes only - ``quit_string`` -- (default: ``None``) if not ``None``, send - this string to the child process before killing it. + this string to the child process before killing it EXAMPLES:: @@ -217,7 +217,7 @@ class SagePtyProcess(PtyProcess): INPUT: - ``interval`` -- (default: 5) how much seconds to wait between - sending two signals. + sending two signals EXAMPLES: diff --git a/src/sage/interfaces/scilab.py b/src/sage/interfaces/scilab.py index c650d8f9ba2..c2d689ef059 100644 --- a/src/sage/interfaces/scilab.py +++ b/src/sage/interfaces/scilab.py @@ -220,7 +220,7 @@ def __init__(self, maxread=None, script_subdirectory=None, logfile=None, server=None, server_tmpdir=None, seed=None): """ - Initializes the Scilab class. + Initialize the Scilab class. EXAMPLES:: @@ -275,7 +275,7 @@ def set_seed(self, seed=None): def _quit_string(self): """ - Returns the string used to quit the pexpect interface. + Return the string used to quit the pexpect interface. EXAMPLES:: @@ -330,7 +330,7 @@ def eval(self, command, *args, **kwds): def whos(self, name=None, typ=None): """ - Returns information about current objects. + Return information about current objects. Arguments: nam: first characters of selected names typ: name of selected Scilab variable type @@ -386,13 +386,12 @@ def console(self): EXAMPLES:: sage: scilab.console() # optional - scilab; not tested - """ scilab_console() def version(self): """ - Returns the version of the Scilab software used. + Return the version of the Scilab software used. EXAMPLES:: @@ -406,10 +405,10 @@ def sage2scilab_matrix_string(self, A): Return a Scilab matrix from a Sage matrix. INPUT: - A Sage matrix with entries in the rationals or reals. - OUTPUT: - A string that evaluates to a Scilab matrix. + - ``A`` -- Sage matrix with entries in the rationals or reals + + OUTPUT: string that evaluates to a Scilab matrix EXAMPLES:: @@ -423,7 +422,7 @@ def sage2scilab_matrix_string(self, A): def _object_class(self): """ - Returns the class of the object. + Return the class of the object. EXAMPLES:: @@ -460,7 +459,7 @@ def __getitem__(self, n): def __setitem__(self, n, value): """ - Sets an element of a matrix. + Set an element of a matrix. EXAMPLES:: diff --git a/src/sage/interfaces/singular.py b/src/sage/interfaces/singular.py index c0ab80e0a68..3bb7d49aaf5 100644 --- a/src/sage/interfaces/singular.py +++ b/src/sage/interfaces/singular.py @@ -12,16 +12,16 @@ your computer; this should be the case, since Singular is included with Sage. The interface offers three pieces of functionality: -#. ``singular_console()`` -- A function that dumps you +#. ``singular_console()`` -- a function that dumps you into an interactive command-line Singular session. -#. ``singular(expr, type='def')`` -- Creation of a +#. ``singular(expr, type='def')`` -- creation of a Singular object. This provides a Pythonic interface to Singular. For example, if ``f=singular(10)``, then ``f.factorize()`` returns the factorization of `10` computed using Singular. -#. ``singular.eval(expr)`` -- Evaluation of arbitrary +#. ``singular.eval(expr)`` -- evaluation of arbitrary Singular expressions, with the result returned as a string. Of course, there are polynomial rings and ideals in Sage as well @@ -538,7 +538,6 @@ def _send_interrupt(self): True sage: 3*a 3 - """ # Work around for Singular bug # http://www.singular.uni-kl.de:8002/trac/ticket/727 @@ -580,12 +579,12 @@ def eval(self, x, allow_semicolon=True, strip=True, **kwds): INPUT: - - ``x`` -- string (of code) + - ``x`` -- string (of code) - - ``allow_semicolon`` -- default: ``False``; if False then - raise a :class:`TypeError` if the input line contains a semicolon. + - ``allow_semicolon`` -- (default: ``False``) if ``False`` then + raise a :exc:`TypeError` if the input line contains a semicolon - - ``strip`` -- ignored + - ``strip`` -- ignored EXAMPLES:: @@ -700,7 +699,6 @@ def set(self, type, name, value): sage: singular.set('int', 'y', '5') sage: singular.eval('defined(%s)'%n) '0' - """ cmd = ''.join('if(defined(%s)){kill %s;};' % (v, v) for v in self.__to_clear) @@ -741,7 +739,6 @@ def clear(self, var): sage: a = singular(3) sage: singular.get('x') '`x`' - """ # We add the variable to the list of vars to clear when we do an eval. # We queue up all the clears and do them at once to avoid synchronizing @@ -752,7 +749,7 @@ def clear(self, var): def _create(self, value, type='def'): """ - Creates a new variable in the Singular session and returns the name + Create a new variable in the Singular session and returns the name of that variable. EXAMPLES:: @@ -774,7 +771,7 @@ def __call__(self, x, type='def'): could be anything, and can be recovered using X.name(). The object X returned can be used like any Sage object, and wraps - an object in self. The standard arithmetic operators work. Moreover + an object in ``self``. The standard arithmetic operators work. Moreover if foo is a function then X.foo(y,z,...) calls foo(X, y, z, ...) and returns the corresponding object. @@ -855,8 +852,8 @@ def lib(self, lib, reload=False): Load the Singular library named lib. Note that if the library was already loaded during this session it - is not reloaded unless the optional reload argument is True (the - default is False). + is not reloaded unless the optional reload argument is ``True`` (the + default is ``False``). EXAMPLES:: @@ -882,10 +879,8 @@ def ideal(self, *gens): INPUT: - - - ``gens`` -- list or tuple of Singular objects (or - objects that can be made into Singular objects via evaluation) - + - ``gens`` -- list or tuple of Singular objects (or + objects that can be made into Singular objects via evaluation) OUTPUT: the Singular ideal generated by the given list of gens @@ -930,7 +925,7 @@ def ideal(self, *gens): def list(self, x): r""" - Creates a list in Singular from a Sage list ``x``. + Create a list in Singular from a Sage list ``x``. EXAMPLES:: @@ -1052,19 +1047,17 @@ def ring(self, char=0, vars='(x)', order='lp', check=None): INPUT: + - ``char`` -- string; a string specifying the characteristic + of the base ring, in the format accepted by Singular (see + examples below) - - ``char`` (string) -- a string specifying the characteristic - of the base ring, in the format accepted by Singular (see - examples below). - - - ``vars`` -- a tuple or string defining the variable names - - - ``order`` (string) -- the monomial order (default: "lp") + - ``vars`` -- tuple or string defining the variable names + - ``order`` -- string; the monomial order (default: ``'lp'``) OUTPUT: a Singular ring - .. note:: + .. NOTE:: This function is *not* identical to calling the Singular ``ring`` function. In particular, it also attempts to @@ -1139,7 +1132,7 @@ def ring(self, char=0, vars='(x)', order='lp', check=None): def string(self, x): """ - Creates a Singular string from a Sage string. Note that the Sage + Create a Singular string from a Sage string. Note that the Sage string has to be "double-quoted". EXAMPLES:: @@ -1151,7 +1144,7 @@ def string(self, x): def set_ring(self, R): """ - Sets the current Singular ring to R. + Set the current Singular ring to `R`. EXAMPLES:: @@ -1395,8 +1388,6 @@ def _repr_(self): sage: M T[1,1],y, 0, 1 - - """ s = super()._repr_() if self._name in s: @@ -1479,19 +1470,17 @@ def __len__(self): def __setitem__(self, n, value): """ - Set the n-th element of self to x. + Set the `n`-th element of ``self`` to `x`. INPUT: + - ``n`` -- integer *or* a 2-tuple (for setting + matrix elements) - - ``n`` -- an integer *or* a 2-tuple (for setting - matrix elements) + - ``value`` -- anything (is coerced to a Singular + object if it is not one already) - - ``value`` -- anything (is coerced to a Singular - object if it is not one already) - - - OUTPUT: Changes elements of self. + OUTPUT: changes elements of ``self`` EXAMPLES:: @@ -1636,7 +1625,6 @@ def sage_global_ring(self): AUTHOR: - Simon King (2011-06-06) - """ # extract the ring of coefficients singular = self.parent() @@ -1712,16 +1700,15 @@ def sage_poly(self, R=None, kcache=None): INPUT: + - ``R`` -- (default: ``None``) an optional polynomial ring. + If it is provided, then you have to make sure that it + matches the current singular ring as, e.g., returned by + ``singular.current_ring()``. By default, the output of + :meth:`sage_global_ring` is used. - - ``R`` -- (default: None); an optional polynomial ring. - If it is provided, then you have to make sure that it - matches the current singular ring as, e.g., returned by - singular.current_ring(). By default, the output of - :meth:`sage_global_ring` is used. - - - ``kcache`` -- (default: None); an optional dictionary - for faster finite field lookups, this is mainly useful for finite - extension fields + - ``kcache`` -- (default: ``None``) an optional dictionary + for faster finite field lookups, this is mainly useful for finite + extension fields OUTPUT: MPolynomial @@ -1732,7 +1719,7 @@ def sage_poly(self, R=None, kcache=None): sage: f = R('a^20*x^2*y+a^10+x') sage: f._singular_().sage_poly(R) == f True - sage: R = PolynomialRing(GF(2^8,'a'), 'x', implementation="singular") + sage: R = PolynomialRing(GF(2^8,'a'), 'x', implementation='singular') sage: f = R('a^20*x^3+x^2+a^10') sage: f._singular_().sage_poly(R) == f True @@ -1786,7 +1773,7 @@ def sage_poly(self, R=None, kcache=None): - Simon King (2011-06-06): Deal with Singular's short polynomial representation, automatic construction of a polynomial ring, if it is not explicitly given. - .. note:: + .. NOTE:: For very simple polynomials ``eval(SingularElement.sage_polystring())`` is faster than @@ -1797,7 +1784,7 @@ def sage_poly(self, R=None, kcache=None): # TODO: Refactor imports to move this to the top from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_polydict from sage.rings.polynomial.multi_polynomial_libsingular import MPolynomialRing_libsingular - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polydict import ETuple from sage.rings.polynomial.polynomial_singular_interface import can_convert_to_singular from sage.rings.quotient_ring import QuotientRing_generic @@ -1888,7 +1875,7 @@ def sage_poly(self, R=None, kcache=None): return R(sage_repr) - elif is_PolynomialRing(R) and (ring_is_fine or can_convert_to_singular(R)): + elif isinstance(R, PolynomialRing_general) and (ring_is_fine or can_convert_to_singular(R)): sage_repr = [0] * int(self.deg() + 1) @@ -1922,12 +1909,12 @@ def sage_matrix(self, R, sparse=True): INPUT: - - ``R`` -- (default: None); an optional ring, over which - the resulting matrix is going to be defined. - By default, the output of :meth:`sage_global_ring` is used. + - ``R`` -- (default: ``None``) an optional ring, over which + the resulting matrix is going to be defined. + By default, the output of :meth:`sage_global_ring` is used. - - ``sparse`` -- (default: ``True``); determines whether the - resulting matrix is sparse or not. + - ``sparse`` -- boolean (default: ``True``); whether the + resulting matrix is sparse or not EXAMPLES:: @@ -1962,7 +1949,7 @@ def sage_matrix(self, R, sparse=True): def _sage_(self, R=None): r""" - Convert self to Sage. + Convert ``self`` to Sage. EXAMPLES:: @@ -2086,13 +2073,12 @@ def is_string(self): True sage: singular('1').is_string() False - """ return self.type() == 'string' def set_ring(self): """ - Sets the current ring in Singular to be self. + Set the current ring in Singular to be ``self``. EXAMPLES:: @@ -2133,7 +2119,7 @@ def sage_flattened_str_list(self): def sage_structured_str_list(self): r""" - If self is a Singular list of lists of Singular elements, returns + If ``self`` is a Singular list of lists of Singular elements, return corresponding Sage list of lists of strings. EXAMPLES:: @@ -2237,16 +2223,14 @@ def _singular_(self): def attrib(self, name, value=None): """ - Get and set attributes for self. + Get and set attributes for ``self``. INPUT: + - ``name`` -- string to choose the attribute - - ``name`` -- string to choose the attribute - - - ``value`` -- boolean value or None for reading, - (default:None) - + - ``value`` -- boolean value or ``None`` for reading, + (default: ``None``) VALUES: isSB - the standard basis property is set by all commands computing a standard basis like groebner, std, stdhilb etc.; used @@ -2336,7 +2320,7 @@ def _instancedoc_(self): def is_SingularElement(x): r""" - Return True is ``x`` is of type :class:`SingularElement`. + Return ``True`` if ``x`` is of type :class:`SingularElement`. This function is deprecated; use :func:`isinstance` (of :class:`sage.interfaces.abc.SingularElement`) instead. @@ -2426,7 +2410,6 @@ def get_docstring(name): True sage: 'standard.lib' in get_docstring('groebner') True - """ if not nodes: generate_docstring_dictionary() @@ -2502,7 +2485,7 @@ class SingularGBLogPrettyPrinter: deg_lead = re.compile(r"\d+") # the degree of the leading terms is currently d # SlimGB - red_para = re.compile(r"M\[(\d+),(\d+)\]") # parallel reduction of n elements with m non-zero output elements + red_para = re.compile(r"M\[(\d+),(\d+)\]") # parallel reduction of n elements with m nonzero output elements red_betr = re.compile("b") # exchange of a reductor by a 'better' one non_mini = re.compile("e") # a new reductor with non-minimal leading term @@ -2554,7 +2537,7 @@ def write(self, s): sage: s3.write("(S:1337)") Performing complete reduction of 1337 elements. sage: s3.write("M[389,12]") - Parallel reduction of 389 elements with 12 non-zero output elements. + Parallel reduction of 389 elements with 12 nonzero output elements. """ verbosity = self.verbosity @@ -2636,7 +2619,7 @@ def write(self, s): elif re.match(SingularGBLogPrettyPrinter.red_para, token) and verbosity >= 3: m, n = re.match(SingularGBLogPrettyPrinter.red_para, token).groups() - print("Parallel reduction of %s elements with %s non-zero output elements." % (m, n)) + print("Parallel reduction of %s elements with %s nonzero output elements." % (m, n)) elif re.match(SingularGBLogPrettyPrinter.red_betr, token) and verbosity >= 3: print("Replaced reductor by 'better' one.") @@ -2672,7 +2655,7 @@ def __init__(self, singular=None): INPUT: - - ``singular`` -- Singular instance (default: default instance) + - ``singular`` -- Singular instance (default: default instance) EXAMPLES:: @@ -2704,7 +2687,7 @@ def __init__(self, singular=None): sage: (7*a-420*c^3+158*c^2+8*c-7)/7 < (a+2*b+2*c-1) True - .. note:: + .. NOTE:: This context is used automatically internally whenever a Groebner basis is computed so the user does not need to use @@ -2807,7 +2790,7 @@ def singular_gb_standard_options(func): ... ' return self.basis.reduced()\n'], ...) - .. note:: + .. NOTE:: This decorator is used automatically internally so the user does not need to use it manually. diff --git a/src/sage/interfaces/sympy.py b/src/sage/interfaces/sympy.py index d291727ee0e..2ccaf13035d 100644 --- a/src/sage/interfaces/sympy.py +++ b/src/sage/interfaces/sympy.py @@ -765,7 +765,7 @@ def _sympysage_piecewise(self): sage: assert ex == sp._sage_() sage: _ = var('y, z') - sage: (x^y - z).integrate(y, algorithm="sympy") + sage: (x^y - z).integrate(y, algorithm='sympy') -y*z + cases(((log(x) != 0, x^y/log(x)), (1, y))) """ from sage.functions.other import cases @@ -1197,7 +1197,7 @@ def sympy_init(): def check_expression(expr, var_symbols, only_from_sympy=False): """ - Does ``eval(expr)`` both in Sage and SymPy and does other checks. + Do ``eval(expr)`` both in Sage and SymPy and other checks. EXAMPLES:: diff --git a/src/sage/interfaces/sympy_wrapper.py b/src/sage/interfaces/sympy_wrapper.py index 5ad6095a787..40c96d60d26 100644 --- a/src/sage/interfaces/sympy_wrapper.py +++ b/src/sage/interfaces/sympy_wrapper.py @@ -157,7 +157,6 @@ def _contains(self, element): Traceback (most recent call last): ... TypeError: did not evaluate to a bool: None - """ if element.is_symbol: # keep symbolic diff --git a/src/sage/interfaces/tab_completion.py b/src/sage/interfaces/tab_completion.py index ca106a67273..fdbe51ffd8e 100644 --- a/src/sage/interfaces/tab_completion.py +++ b/src/sage/interfaces/tab_completion.py @@ -31,7 +31,7 @@ class ExtraTabCompletion(): def __dir__(self): """ - Add to the dir() output + Add to the ``dir()`` output. This is used by IPython to read off the tab completions. @@ -58,14 +58,12 @@ def completions(s, globs): INPUT: - - ``s`` -- a string + - ``s`` -- string - - ``globs`` -- a string: object dictionary; context in which to + - ``globs`` -- string: object dictionary; context in which to search for completions, e.g., :func:`globals()` - OUTPUT: - - a list of strings + OUTPUT: list of strings EXAMPLES:: diff --git a/src/sage/interfaces/tachyon.py b/src/sage/interfaces/tachyon.py index 024092fdc8f..c4596c825d3 100644 --- a/src/sage/interfaces/tachyon.py +++ b/src/sage/interfaces/tachyon.py @@ -695,48 +695,46 @@ class TachyonRT(SageObject): r""" - The Tachyon Ray Tracer + The Tachyon Ray Tracer. Usage: ``tachyon_rt(model, outfile='sage.png', verbose=1, block=True, extra_opts='')`` INPUT: - - ``model`` -- a string that describes a 3d model in - the Tachyon modeling format. Type ``sage.interfaces.tachyon?`` for a - description of this format. + - ``model`` -- string that describes a 3d model in + the Tachyon modeling format. Type ``sage.interfaces.tachyon?`` for a + description of this format. - - ``outfile`` -- (default: 'sage.png') output filename; - the extension of the filename determines the type. Supported types - include: + - ``outfile`` -- (default: ``'sage.png'``) output filename; + the extension of the filename determines the type. Supported types + include: - - ``tga`` -- 24-bit (uncompressed) + - ``tga`` -- 24-bit (uncompressed) - - ``bmp`` -- 24-bit Windows BMP (uncompressed) + - ``bmp`` -- 24-bit Windows BMP (uncompressed) - - ``ppm`` -- 24-bit PPM (uncompressed) + - ``ppm`` -- 24-bit PPM (uncompressed) - - ``rgb`` -- 24-bit SGI RGB (uncompressed) + - ``rgb`` -- 24-bit SGI RGB (uncompressed) - - ``png`` -- 24-bit PNG (compressed, lossless) + - ``png`` -- 24-bit PNG (compressed, lossless) - - ``verbose`` -- integer; (default: 1) + - ``verbose`` -- integer; (default: 1) - - ``0`` -- silent + - ``0`` -- silent - - ``1`` -- some output + - ``1`` -- some output - - ``2`` -- very verbose output + - ``2`` -- very verbose output - - ``block`` -- bool (default: ``True``); if False, run the - rendering command in the background. + - ``block`` -- boolean (default: ``True``); if ``False``, run the + rendering command in the background - - ``extra_opts`` -- passed directly to tachyon command - line. Use tachyon_rt.usage() to see some of the possibilities. + - ``extra_opts`` -- passed directly to tachyon command + line. Use ``tachyon_rt.usage()`` to see some of the possibilities - OUTPUT: - - - Some text may be displayed onscreen. + OUTPUT: some text may be displayed onscreen - The file outfile is created. @@ -746,7 +744,8 @@ class TachyonRT(SageObject): """ def _repr_(self): """ - Returns a brief description of this interface object (the Tachyon raytracer written by John Stone). + Return a brief description of this interface object (the Tachyon + raytracer written by John Stone). TESTS:: @@ -763,15 +762,15 @@ def __call__(self, model, outfile='sage.png', verbose=1, extra_opts=''): INPUT: - - ``model`` -- string. The tachyon model. + - ``model`` -- string; the tachyon model - - ``outfile`` -- string, default ``'sage.png'``. The filename - to save the model to. + - ``outfile`` -- string (default: ``'sage.png'``); the filename + to save the model to - - ``verbose`` -- 0, 1, (default) or 2. The verbosity level. + - ``verbose`` -- 0, 1, (default) or 2; the verbosity level - - ``extra_opts`` -- string (default: empty string). Extra - options that will be appended to the tachyon commandline. + - ``extra_opts`` -- string (default: empty string); extra + options that will be appended to the tachyon commandline EXAMPLES:: @@ -838,7 +837,9 @@ def __call__(self, model, outfile='sage.png', verbose=1, extra_opts=''): def usage(self, use_pager=True): """ - Returns the basic description of using the Tachyon raytracer (simply what is returned by running tachyon with no input). The output is paged unless use_pager=False. + Return the basic description of using the Tachyon raytracer (simply + what is returned by running tachyon with no input). The output is + paged unless ``use_pager=False``. TESTS:: @@ -861,7 +862,7 @@ def usage(self, use_pager=True): @cached_method def version(self): """ - Returns the version of the Tachyon raytracer being used. + Return the version of the Tachyon raytracer being used. TESTS:: @@ -879,7 +880,7 @@ def version(self): def help(self, use_pager=True): """ - Deprecated: type 'sage.interfaces.tachyon?' for help + Deprecated: type 'sage.interfaces.tachyon?' for help. TESTS:: diff --git a/src/sage/interfaces/tides.py b/src/sage/interfaces/tides.py index 309046f30ac..c1076496cea 100644 --- a/src/sage/interfaces/tides.py +++ b/src/sage/interfaces/tides.py @@ -56,11 +56,11 @@ def subexpressions_list(f, pars=None): INPUT: - - ``f`` -- a symbolic function of several components. + - ``f`` -- a symbolic function of several components - - ``pars`` -- a list of the parameters that appear in the function + - ``pars`` -- list of the parameters that appear in the function this should be the symbolic constants that appear in f but are not - arguments. + arguments OUTPUT: @@ -74,7 +74,6 @@ def subexpressions_list(f, pars=None): For the trigonometric functions, some extra expressions will be added. These extra expressions will be used later to compute their derivatives. - EXAMPLES:: sage: from sage.interfaces.tides import subexpressions_list @@ -145,8 +144,6 @@ def subexpressions_list(f, pars=None): ('cos', y), ('add', sin(y), x^2), ('exp', x^2 + sin(y))]) - - """ from sage.functions.trig import sin, cos, arcsin, arctan, arccos variables = f[0].arguments() @@ -332,8 +329,6 @@ def remove_repeated(l1, l2): ('add', 1, -a^2), ('pow', -a^2 + 1, 0.5), ('asin', a)]) - - """ for i in range(len(l1)-1): j = i+1 @@ -361,7 +356,6 @@ def remove_constants(l1,l2): sage: remove_constants(l1,l2) sage: l1, l2 ([a*cos(7), a*cos(7) + 1], [('mul', cos(7), a), ('add', 1, a*cos(7))]) - """ i = 0 while i < len(l1): @@ -379,25 +373,25 @@ def genfiles_mintides(integrator, driver, f, ics, initial, final, delta, INPUT: - - ``integrator`` -- the name of the integrator file. + - ``integrator`` -- the name of the integrator file - - ``driver`` -- the name of the driver file. + - ``driver`` -- the name of the driver file - - ``f`` -- the function that determines the differential equation. + - ``f`` -- the function that determines the differential equation - - ``ics`` -- a list or tuple with the initial conditions. + - ``ics`` -- list or tuple with the initial conditions - - ``initial`` -- the initial time for the integration. + - ``initial`` -- the initial time for the integration - - ``final`` -- the final time for the integration. + - ``final`` -- the final time for the integration - - ``delta`` -- the step of the output. + - ``delta`` -- the step of the output - - ``tolrel`` -- the relative tolerance. + - ``tolrel`` -- the relative tolerance - - ``tolabs`` -- the absolute tolerance. + - ``tolabs`` -- the absolute tolerance - - ``output`` -- the name of the file that the compiled integrator will write to + - ``output`` -- the name of the file that the compiled integrator will write to This function creates two files, integrator and driver, that can be used later with the min_tides library [TIDES]_. @@ -462,8 +456,6 @@ def genfiles_mintides(integrator, driver, f, ics, initial, final, delta, sage: l[18] ' \tv[0] = 3.1415926535897931 ; \n' sage: shutil.rmtree(tempdir) - - """ RR = RealField() @@ -639,33 +631,33 @@ def genfiles_mpfr(integrator, driver, f, ics, initial, final, delta, INPUT: - - ``integrator`` -- the name of the integrator file. + - ``integrator`` -- the name of the integrator file - - ``driver`` -- the name of the driver file. + - ``driver`` -- the name of the driver file - - ``f`` -- the function that determines the differential equation. + - ``f`` -- the function that determines the differential equation - - ``ics`` -- a list or tuple with the initial conditions. + - ``ics`` -- list or tuple with the initial conditions - - ``initial`` -- the initial time for the integration. + - ``initial`` -- the initial time for the integration - - ``final`` -- the final time for the integration. + - ``final`` -- the final time for the integration - - ``delta`` -- the step of the output. + - ``delta`` -- the step of the output - ``parameters`` -- the variables inside the function that should be treated - as parameters. + as parameters - ``parameter_values`` -- the values of the parameters for the particular - initial value problem. + initial value problem - ``dig`` -- the number of digits of precision that will be used in the integration - - ``tolrel`` -- the relative tolerance. + - ``tolrel`` -- the relative tolerance - - ``tolabs`` -- the absolute tolerance. + - ``tolabs`` -- the absolute tolerance - - ``output`` -- the name of the file that the compiled integrator will write to + - ``output`` -- the name of the file that the compiled integrator will write to This function creates two files, integrator and driver, that can be used later with the tides library ([TIDES]_). @@ -743,7 +735,6 @@ def genfiles_mpfr(integrator, driver, f, ics, initial, final, delta, sage: l[24] '\tmpfr_set_str(v[0], "3.141592653589793238462643383279502884197169399375101", 10, TIDES_RND);\n' sage: shutil.rmtree(tempdir) - """ if parameters is None: parameters = [] diff --git a/src/sage/knots/knot.py b/src/sage/knots/knot.py index 97d2d737e1b..21dd0b59f12 100644 --- a/src/sage/knots/knot.py +++ b/src/sage/knots/knot.py @@ -47,7 +47,7 @@ class Knot(Link, Element, metaclass=InheritComparisonClasscallMetaclass): INPUT: - ``data`` -- see :class:`Link` for the allowable inputs - - ``check`` -- optional, default ``True``. If ``True``, make sure + - ``check`` -- boolean (default: ``True``); if ``True``, make sure that the data define a knot, not a link EXAMPLES: @@ -148,14 +148,6 @@ def _unicode_art_(self): """ Return unicode art for the knot. - INPUT: - - - a knot - - OUTPUT: - - - unicode art for the knot - EXAMPLES:: sage: W = Knots() @@ -404,9 +396,7 @@ def connected_sum(self, other): - ``other`` -- a knot - OUTPUT: - - A knot equivalent to the connected sum of ``self`` and ``other``. + OUTPUT: a knot equivalent to the connected sum of ``self`` and ``other`` EXAMPLES:: @@ -545,11 +535,9 @@ def from_gauss_code(self, gauss): INPUT: - - a signed Gauss code - - OUTPUT: + - ``gauss`` -- a signed Gauss code - - a knot + OUTPUT: a knot EXAMPLES:: @@ -581,11 +569,10 @@ def from_dowker_code(self, code): INPUT: - a list of signed even numbers, the Dowker-Thistlethwaite code of a knot + - ``code`` -- list of signed even numbers; the Dowker-Thistlethwaite + code of a knot - OUTPUT: - - a knot + OUTPUT: a knot .. WARNING:: @@ -633,11 +620,9 @@ def from_table(self, n, k): INPUT: - ``n`` -- the crossing number - - ``k`` -- a positive integer - - OUTPUT: + - ``k`` -- positive integer - the knot `K_{n,k}` in the Rolfsen table + OUTPUT: the knot `K_{n,k}` in the Rolfsen table EXAMPLES:: diff --git a/src/sage/knots/knotinfo.py b/src/sage/knots/knotinfo.py index efd5da177ec..bcd43194ee7 100644 --- a/src/sage/knots/knotinfo.py +++ b/src/sage/knots/knotinfo.py @@ -252,8 +252,8 @@ def eval_knotinfo(string, locals={}, to_tuple=True): INPUT: - - ``string`` -- string that gives a value of some database entry - - ``locals`` -- dictionary of locals passed to ``sage_eval`` + - ``string`` -- string that gives a value of some database entry + - ``locals`` -- dictionary of locals passed to ``sage_eval`` EXAMPLES:: @@ -312,7 +312,7 @@ def knotinfo_bool(string): INPUT: - - ``string`` -- string that gives a value of some database entry + - ``string`` -- string that gives a value of some database entry EXAMPLES:: @@ -543,7 +543,7 @@ def pd_notation(self, original=False): INPUT: - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string OUTPUT: @@ -585,7 +585,7 @@ def dt_notation(self, original=False): INPUT: - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string OUTPUT: @@ -628,13 +628,9 @@ def gauss_notation(self, original=False): INPUT: - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string - OUTPUT: - - Python list of - EXAMPLES:: sage: L = KnotInfo.L4a1_0 @@ -662,7 +658,7 @@ def braid_notation(self, original=False): INPUT: - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string OUTPUT: @@ -742,7 +738,6 @@ def braid_index(self): Traceback (most recent call last): ... NotImplementedError: this integer is not provided by the database - """ if self.is_knot(): return knotinfo_int(self[self.items.braid_index]) @@ -1016,13 +1011,11 @@ def is_amphicheiral(self, positive=False): INPUT: - - ``positive`` -- boolean (default: ``False``) whether to check + - ``positive`` -- boolean (default: ``False``); whether to check if ``self`` is positive or negative amphicheiral (see documentation of :meth:`symmetry_type`) - OUTPUT: - - Boolean or ``None`` if this cannot be determined. + OUTPUT: boolean or ``None`` if this cannot be determined ``True`` if ``self`` is fully or negative amphicheiral per default. If ``positive`` is set to ``True`` than fully and positive amphicheiral @@ -1244,9 +1237,9 @@ def homfly_polynomial(self, var1='v', var2='z', original=False): INPUT: - - ``var1`` -- string (default ``v``) for the name of the first variable - - ``var2`` -- string (default ``z``) for the name of the second variable - - ``original`` -- boolean (default ``False``) if set to + - ``var1`` -- string (default: ``'v'``); for the name of the first variable + - ``var2`` -- string (default: ``'z'``); for the name of the second variable + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string OUTPUT: @@ -1350,7 +1343,7 @@ def kauffman_polynomial(self, var1='a', var2='z', original=False): - ``var1`` -- (default: ``'a'``) the first variable - ``var2`` -- (default: ``'z'``) the second variable - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string OUTPUT: @@ -1432,17 +1425,17 @@ def jones_polynomial(self, variab=None, skein_normalization=False, puiseux=False INPUT: - - ``variab`` -- variable (default: ``None``) used according to :meth:`Link.jones_polynomial` - - ``skein_normalization`` -- boolean (default: ``False``) used according - to :meth:`Link.jones_polynomial` - - ``puiseux`` -- boolean (default ``True``) only used in case + - ``variab`` -- variable (default: ``None``); used according to + :meth:`Link.jones_polynomial` + - ``skein_normalization`` -- boolean (default: ``False``); used + according to :meth:`Link.jones_polynomial` + - ``puiseux`` -- boolean (default: ``True``); only used in case ``skein_normalization=False``. If set to ``True`` instead of an element of the symbolic ring an instance of :class:`~sage.rings.puiseux_series_ring_element.PuiseuxSeries` is returned - - ``original`` -- boolean (default ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string - - ``use_sqrt`` -- boolean (default ``False``) see the note below - + - ``use_sqrt`` -- boolean (default: ``False``); see the note below OUTPUT: @@ -1622,9 +1615,9 @@ def alexander_polynomial(self, var='t', original=False, laurent_poly=False): INPUT: - ``var`` -- (default: ``'t'``) the variable - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string - - ``laurent_poly`` -- boolean (default ``False``) see the note below + - ``laurent_poly`` -- boolean (default: ``False``); see the note below OUTPUT: @@ -1712,7 +1705,7 @@ def conway_polynomial(self, var='t', original=False): INPUT: - ``var`` -- (default: ``'t'``) the variable - - ``original`` -- boolean (default: ``False``) if set to + - ``original`` -- boolean (default: ``False``); if set to ``True`` the original table entry is returned as a string OUTPUT: @@ -1968,11 +1961,11 @@ def link(self, use_item=db.columns().pd_notation, snappy=False): - ``self.items.dt_notation`` (only for knots and ``snappy=False``) - ``self.items.gauss_notation`` (only for knots and ``snappy=False``) - - ``snappy`` boolean (default ``False``) if set to ``True`` + - ``snappy`` -- boolean (default: ``False``); if set to ``True`` the target of the conversion is the ``pip`` installable package `SnapPy `__ (explicitely, ``spherogram.links.invariants.Link``). - If SnapPy is not installed an :class:`ImportError` is raised. To + If SnapPy is not installed an :exc:`ImportError` is raised. To install SnapPy use ``sage -pip install snappy``. .. NOTE:: @@ -2101,9 +2094,7 @@ def is_unique(self): r""" Return whether there is no other isotopic link in the database or not. - OUTPUT: - - Boolean or ``None`` if this cannot be determined. + OUTPUT: boolean or ``None`` if this cannot be determined EXAMPLES:: @@ -2155,7 +2146,7 @@ def is_recoverable(self, unique=True): INPUT: - - ``unique`` -- boolean (default: ``True``) if set to ``False`` + - ``unique`` -- boolean (default: ``True``); if set to ``False`` it is only checked if ``self`` is among the recovered items EXAMPLES:: @@ -2221,7 +2212,7 @@ def inject(self, verbose=True): INPUT: - - ``verbose`` -- boolean (default: ``True``) to suppress + - ``verbose`` -- boolean (default: ``True``); whether to suppress the message printed on the invocation EXAMPLES:: @@ -2244,11 +2235,11 @@ def series(self, oriented=False): INPUT: - - ``oriented`` -- boolean (default: ``False``) it only affects proper links. - By default the items of the series will be again series of links - collecting all orientation mutants of an unoriented name. To obtain - the series of the individual links this keyword has to be set to - ``True``. + - ``oriented`` -- boolean (default: ``False``); it only affects proper + links. By default the items of the series will be again series of + links collecting all orientation mutants of an unoriented name. To + obtain the series of the individual links this keyword has to be set + to ``True``. EXAMPLES:: @@ -2278,11 +2269,11 @@ def diagram(self, single=False, new=0, autoraise=True): INPUT: - - ``single`` -- boolean (default ``False``) if set to ``True`` only one - diagram is shown. - - ``new`` -- ``int`` according to :func:`open` of :mod:`webbrowser` + - ``single`` -- boolean (default: ``False``); if set to ``True`` only one + diagram is shown + - ``new`` -- integer according to :func:`open` of :mod:`webbrowser` (``0`` default, ``1`` new window, ``2`` new tab) - - ``autoraise`` -- boolean (default ``True``) + - ``autoraise`` -- boolean (default: ``True``) EXAMPLES:: @@ -2309,9 +2300,9 @@ def knot_atlas_webpage(self, new=0, autoraise=True): INPUT: - - ``new`` -- ``int`` according to :func:`open` of :mod:`webbrowser` + - ``new`` -- integer according to :func:`open` of :mod:`webbrowser` (``0`` default, ``1`` new window, ``2`` new tab) - - ``autoraise`` -- boolean (default ``True``) + - ``autoraise`` -- boolean (default: ``True``) EXAMPLES:: @@ -2328,9 +2319,9 @@ def knotilus_webpage(self, new=0, autoraise=True): INPUT: - - ``new`` -- ``int`` according to :func:`open` of :mod:`webbrowser` + - ``new`` -- integer according to :func:`open` of :mod:`webbrowser` (``0`` default, ``1`` new window, ``2`` new tab) - - ``autoraise`` -- boolean (default ``True``) + - ``autoraise`` -- boolean (default: ``True``) EXAMPLES:: @@ -2352,11 +2343,11 @@ class KnotInfoSeries(UniqueRepresentation, SageObject): INPUT: - - ``crossing_number`` -- integer giving the crossing numer of this series + - ``crossing_number`` -- integer giving the crossing number of this series of links - - ``is_knot`` -- boolean whether this series is a series of knots + - ``is_knot`` -- boolean; whether this series is a series of knots or proper links - - ``is_alternating`` -- boolean whether this series is restriced to + - ``is_alternating`` -- boolean; whether this series is restricted to alternating links or not This is not relevant for knots with less than 11 crossings - ``name_unoriented`` -- string restricting the series to all links with @@ -2407,24 +2398,24 @@ def list(self, oriented=False, comp=None, det=None, homfly=None): INPUT: - - ``oriented`` -- boolean (default: ``False``) it only affects + - ``oriented`` -- boolean (default: ``False``); it only affects series of proper links. By default the list items of a series of proper links are again series of links collecting all orientation types of an unoriented name. To obtain the list of the individual links this - keyword has to be set to ``True`` + keyword has to be set to ``True``. - - ``comp`` (default: ``None``) if given an integer for this + - ``comp`` -- (default: ``None``) if given an integer for this keyword the list is restriced to links having the according number - of components. This keyword implies ``oriented=True`` + of components. This keyword implies ``oriented=True``. - - ``det`` (default: ``None``) if given an integer for this + - ``det`` -- (default: ``None``) if given an integer for this keyword the list is restriced to links having the according value - for its determinant. This keyword implies ``oriented=True`` + for its determinant. This keyword implies ``oriented=True``. - - ``homfly`` (default: ``None``) if given a HOMFLY-PT polynomial + - ``homfly`` -- (default: ``None``) if given a HOMFLY-PT polynomial having ``normalization='vz'`` for this keyword the list is restriced to links having the according value for its HOMFLY-PT polynomial. This - keyword implies ``oriented=True`` + keyword implies ``oriented=True``. EXAMPLES:: @@ -2499,16 +2490,16 @@ def lower_list(self, oriented=False, comp=None, det=None, homfly=None): INPUT: - - ``oriented`` -- boolean (default: ``False``) see the + - ``oriented`` -- boolean (default: ``False``); see the description for :meth:`list` - - ``comp`` (default: ``None``) see the description for + - ``comp`` -- (default: ``None``) see the description for :meth:`list` - - ``det`` (default: ``None``) see the description for + - ``det`` -- (default: ``None``) see the description for :meth:`list` - - ``homfly`` (default: ``None``) see the description for + - ``homfly`` -- (default: ``None``) see the description for :meth:`list` EXAMPLES:: @@ -2571,7 +2562,7 @@ def __getitem__(self, item): l = self.list() max_item = len(l) if item < 0 or item > max_item: - raise ValueError('item must be non negative and smaller than %s' % (max_item)) + raise ValueError('item must be nonnegative and smaller than %s' % (max_item)) return l[item] @@ -2658,10 +2649,10 @@ def is_recoverable(self, unique=True, max_samples=8): INPUT: - - ``unique`` -- boolean (default: ``True``) see + - ``unique`` -- boolean (default: ``True``); see :meth:`KnotInfoBase.is_recoverable` - - ``max_samples`` -- non negative integer or ``infinity`` (optional, - default ``8``) limits the number of items to check (random sample). + - ``max_samples`` -- nonnegative integer or ``infinity`` + (default: `8`); limits the number of items to check (random sample). If set to ``infinity`` then no limit is set. EXAMPLES:: @@ -2719,7 +2710,7 @@ def inject(self, verbose=True): INPUT: - - ``verbose`` -- boolean (default: ``True``) to suppress + - ``verbose`` -- boolean (default: ``True``); to suppress the message printed on the invocation EXAMPLES:: diff --git a/src/sage/knots/link.py b/src/sage/knots/link.py index 0f9d25974ce..f307798adfd 100644 --- a/src/sage/knots/link.py +++ b/src/sage/knots/link.py @@ -404,9 +404,7 @@ def arcs(self, presentation='pd'): following negative one; of there exist a closed arc, it is returned as a list of positive numbers only - OUTPUT: - - A list of lists representing the arcs based upon ``presentation``. + OUTPUT: list of lists representing the arcs based upon ``presentation`` EXAMPLES:: @@ -476,9 +474,7 @@ def fundamental_group(self, presentation='wirtinger'): * ``'braid'`` -- the presentation is given by the braid action on the free group (see chapter 2 of [Bir1975]_) - OUTPUT: - - - a finitely presented group + OUTPUT: a finitely presented group EXAMPLES:: @@ -614,7 +610,7 @@ def braid(self, remove_loops=False): INPUT: - - ``remove_loops`` -- boolean (default: ``False``). If set to ``True`` + - ``remove_loops`` -- boolean (default: ``False``); if set to ``True`` loops will be removed first. This can reduce the number of strands needed for an ambient isotopic braid closure. However, this can lead to a loss of the regular isotopy. @@ -1892,8 +1888,8 @@ def omega_signature(self, omega): INPUT: - - `\omega` -- a complex number of modulus 1. This is assumed to be - coercible to ``QQbar``. + - `\omega` -- a complex number of modulus 1; this is assumed to be + coercible to ``QQbar`` This is defined as the signature of the Hermitian matrix @@ -2968,9 +2964,7 @@ def homfly_polynomial(self, var1=None, var2=None, normalization='lm'): polynomials of three links that vary only in one crossing; that is the positive, negative, or smoothed links respectively - OUTPUT: - - A Laurent polynomial over the integers. + OUTPUT: a Laurent polynomial over the integers .. NOTE:: @@ -3141,11 +3135,9 @@ def links_gould_polynomial(self, varnames='t0, t1'): INPUT: - - ``varnames`` -- string (default ``t0, t1``) + - ``varnames`` -- string (default: ``'t0, t1'``) - OUTPUT: - - A Laurent polynomial in the given variable names. + OUTPUT: a Laurent polynomial in the given variable names EXAMPLES:: @@ -3167,9 +3159,7 @@ def _coloring_matrix(self, n=None): - ``n`` -- the number of colors to consider (if ommitted the value of the determinant of ``self`` will be taken) - OUTPUT: - - a matrix over the residue class ring of integers modulo ``n``. + OUTPUT: a matrix over the residue class ring of integers modulo ``n`` EXAMPLES:: @@ -3334,9 +3324,9 @@ def colorings(self, n=None): def coloring_maps(self, n=None, finitely_presented=False): r""" - Return the ``n``-coloring maps of ``self``. These are group + Return the `n`-coloring maps of ``self``. These are group homomorphisms from the fundamental group of ``self`` to the - ``n``-th dihedral group. + `n`-th dihedral group. INPUT: @@ -3344,14 +3334,14 @@ def coloring_maps(self, n=None, finitely_presented=False): of the determinant of ``self`` will be taken). Note that there are no coloring maps if n is coprime to the determinant of ``self`` - - ``finitely_presented`` (default ``False``) whether to choose the - dihedral groups as finitely presented groups. If not set to ``True`` - they are represented as permutation groups. + - ``finitely_presented`` -- boolean (default: ``False``); whether to + choose the dihedral groups as finitely presented groups. If not set + to ``True`` they are represented as permutation groups. OUTPUT: a list of group homomporhisms from the fundamental group of ``self`` - to the ``n``-th dihedral group (represented according to the key + to the `n`-th dihedral group (represented according to the key argument ``finitely_presented``). EXAMPLES:: @@ -3435,10 +3425,10 @@ def plot(self, gap=0.1, component_gap=0.5, solver=None, components - ``solver`` -- the linear solver to use, see - :class:`~sage.numerical.mip.MixedIntegerLinearProgram`. + :class:`~sage.numerical.mip.MixedIntegerLinearProgram` - - ``color`` -- (default: 'blue') a color or a coloring (as returned - by :meth:`colorings`. + - ``color`` -- string (default: ``'blue'``); a color or a coloring (as + returned by :meth:`colorings` The usual keywords for plots can be used here too. @@ -3986,7 +3976,7 @@ def _knotinfo_matching_list(self): OUTPUT: A tuple ``(l, proved)`` where ``l`` is the matching list and ``proved`` a boolean - telling if the entries of ``l`` are checked to be isotopic to self or not. + telling if the entries of ``l`` are checked to be isotopic to ``self`` or not. EXAMPLES:: @@ -4004,7 +3994,6 @@ def _knotinfo_matching_list(self): sage: k = k4_1.connected_sum(k5_2) sage: k._knotinfo_matching_list() # optional - database_knotinfo # needs sage.libs.homfly ([], False) - """ from sage.knots.knotinfo import KnotInfoSeries pd_code = self.pd_code() @@ -4111,14 +4100,14 @@ def get_knotinfo(self, mirror_version=True, unique=True): INPUT: - - ``mirror_version`` -- boolean (default is ``True``). If set to ``False`` + - ``mirror_version`` -- boolean (default: ``True``); if set to ``False`` the result of the method will be just the instance of :class:`~sage.knots.knotinfo.KnotInfoBase` (by default the result is a tuple of the instance and an enum, see explanation of the output below) - - ``unique`` -- boolean (default is ``True``). This only affects the case + - ``unique`` -- boolean (default: ``True``); this only affects the case where a unique identification is not possible. If set to ``False`` you - can obtain a matching list (see explanation of the output below) + can obtain a matching list (see explanation of the output below). OUTPUT: @@ -4136,7 +4125,7 @@ def get_knotinfo(self, mirror_version=True, unique=True): (that is: ``m`` is suppressed). If it is not possible to determine a unique result - a :class:`NotImplementedError` + a :exc:`NotImplementedError` will be raised. To avoid this you can set ``unique`` to ``False``. You will get a list of matching candidates instead. @@ -4598,7 +4587,6 @@ def is_isotopic(self, other): verbose 1 (... link.py, is_isotopic) identified by KnotInfoSeries ([, ], SymmetryMutant.reverse) True sage: set_verbose(0) - """ from sage.misc.verbose import verbose if not isinstance(other, Link): diff --git a/src/sage/lfunctions/dokchitser.py b/src/sage/lfunctions/dokchitser.py index f8a7465521f..f461690728d 100644 --- a/src/sage/lfunctions/dokchitser.py +++ b/src/sage/lfunctions/dokchitser.py @@ -42,7 +42,7 @@ class Dokchitser(SageObject): r""" - Dokchitser's `L`-functions Calculator + Dokchitser's `L`-functions Calculator. Create a Dokchitser `L`-series with @@ -51,10 +51,10 @@ class Dokchitser(SageObject): where - - ``conductor`` -- integer, the conductor + - ``conductor`` -- integer; the conductor - ``gammaV`` -- list of Gamma-factor parameters, e.g. [0] for - Riemann zeta, [0,1] for ell.curves, (see examples). + Riemann zeta, [0,1] for ell.curves, (see examples) - ``weight`` -- positive real number, usually an integer e.g. 1 for Riemann zeta, 2 for `H^1` of curves/`\QQ` @@ -66,9 +66,9 @@ class Dokchitser(SageObject): included - ``residues`` -- vector of residues of `L^*(s)` in those poles or - set residues='automatic' (default value) + set ``residues='automatic'`` (default) - - ``prec`` -- integer (default: 53) number of *bits* of precision + - ``prec`` -- integer (default: 53); number of *bits* of precision RIEMANN ZETA FUNCTION: @@ -232,7 +232,7 @@ def __del__(self): def gp(self): """ Return the gp interpreter that is used to implement this Dokchitser - L-function. + `L`-function. EXAMPLES:: @@ -254,7 +254,7 @@ def gp(self): template = string.Template(tf.read()) from tempfile import NamedTemporaryFile - with NamedTemporaryFile(suffix=".gp", mode="w+t") as f: + with NamedTemporaryFile(suffix='.gp', mode='w+t') as f: f.write(template.substitute(i=str(self.__instance))) f.flush() self.__gp.read(f.name) @@ -365,7 +365,7 @@ def num_coeffs(self, T=1): 4 Verify that ``num_coeffs`` works with non-real spectral - parameters, e.g. for the L-function of the level 10 Maass form + parameters, e.g. for the `L`-function of the level 10 Maass form with eigenvalue 2.7341055592527126:: sage: ev = 2.7341055592527126 @@ -388,21 +388,20 @@ def init_coeffs(self, v, cutoff=1, INPUT: - - ``v`` -- list of complex numbers or string (pari function of k) + - ``v`` -- list of complex numbers or string (pari function of k) - - ``cutoff`` -- real number = 1 (default: 1) + - ``cutoff`` -- real number (default: 1) - - ``w`` -- list of complex numbers or string (pari function of k) + - ``w`` -- list of complex numbers or string (pari function of k) - - ``pari_precode`` -- some code to execute in pari - before calling initLdata + - ``pari_precode`` -- some code to execute in pari + before calling initLdata - - ``max_imaginary_part`` -- (default: 0): redefine if - you want to compute L(s) for s having large imaginary part, + - ``max_imaginary_part`` -- (default: 0) redefine if + you want to compute L(s) for s having large imaginary part - - ``max_asymp_coeffs`` -- (default: 40): at most this - many terms are generated in asymptotic series for phi(t) and - G(s,t). + - ``max_asymp_coeffs`` -- (default: 40) at most this + many terms are generated in asymptotic series for phi(t) and G(s,t) EXAMPLES:: @@ -410,8 +409,8 @@ def init_coeffs(self, v, cutoff=1, sage: pari_precode = 'tau(n)=(5*sigma(n,3)+7*sigma(n,5))*n/12 - 35*sum(k=1,n-1,(6*k-4*(n-k))*sigma(k,3)*sigma(n-k,5))' sage: L.init_coeffs('tau(k)', pari_precode=pari_precode) - Evaluate the resulting L-function at a point, and compare with - the answer that one gets "by definition" (of L-function + Evaluate the resulting `L`-function at a point, and compare with + the answer that one gets "by definition" (of `L`-function attached to a modular form):: sage: L(14) @@ -490,7 +489,7 @@ def __call__(self, s, c=None): r""" INPUT: - - ``s`` -- complex number + - ``s`` -- complex number .. NOTE:: @@ -574,14 +573,11 @@ def taylor_series(self, a=0, k=6, var='z'): INPUT: - - ``a`` -- complex number (default: 0); point about - which to expand + - ``a`` -- complex number (default: 0); point about which to expand - - ``k`` -- integer (default: 6), series is - `O(``var``^k)` + - ``k`` -- integer (default: 6); series is `O(``var``^k)` - - ``var`` -- string (default: 'z'), variable of power - series + - ``var`` -- string (default: ``'z'``); variable of power series EXAMPLES:: @@ -645,26 +641,26 @@ def check_functional_equation(self, T=1.2): and also determines the residues if ``self.poles != []`` and residues='automatic'. - More specifically: for `T>1` (default 1.2), + More specifically: for `T>1` (default: 1.2), ``self.check_functional_equation(T)`` should ideally return 0 (to the current precision). - - if what this function returns does not look like 0 at all, - probably the functional equation is wrong (i.e. some of the - parameters gammaV, conductor etc., or the coefficients are wrong), + - if what this function returns does not look like 0 at all, + probably the functional equation is wrong (i.e. some of the + parameters gammaV, conductor etc., or the coefficients are wrong), - - if checkfeq(T) is to be used, more coefficients have to be - generated (approximately T times more), e.g. call cflength(1.3), - initLdata("a(k)",1.3), checkfeq(1.3) + - if checkfeq(T) is to be used, more coefficients have to be + generated (approximately T times more), e.g. call cflength(1.3), + initLdata("a(k)",1.3), checkfeq(1.3) - - T=1 always (!) returns 0, so T has to be away from 1 + - T=1 always (!) returns 0, so T has to be away from 1 - - default value `T=1.2` seems to give a reasonable - balance + - default value `T=1.2` seems to give a reasonable + balance - - if you don't have to verify the functional equation or the - L-values, call num_coeffs(1) and initLdata("a(k)",1), you need - slightly less coefficients. + - if you don't have to verify the functional equation or the + L-values, call num_coeffs(1) and initLdata("a(k)",1), you need + slightly less coefficients. EXAMPLES:: @@ -698,8 +694,8 @@ def set_coeff_growth(self, coefgrow): INPUT: - - ``coefgrow`` -- string that evaluates to a PARI - function of n that defines a coefgrow function. + - ``coefgrow`` -- string that evaluates to a PARI function of n that + defines a coefgrow function EXAMPLES:: diff --git a/src/sage/lfunctions/lcalc.py b/src/sage/lfunctions/lcalc.py index 45b0e93b540..f695712abc1 100644 --- a/src/sage/lfunctions/lcalc.py +++ b/src/sage/lfunctions/lcalc.py @@ -6,7 +6,7 @@ functionality compiled in and is a standard part of Sage. -.. note:: +.. NOTE:: Each call to ``lcalc`` runs a complete ``lcalc`` process. On a typical Linux system, this @@ -44,22 +44,19 @@ class LCalc(SageObject): r""" - Rubinstein's `L`-functions Calculator + Rubinstein's `L`-functions Calculator. Type ``lcalc.[tab]`` for a list of useful commands that are implemented using the command line interface, but return objects that make sense in Sage. For each command the possible - inputs for the L-function are: + inputs for the `L`-function are: - - ``"`` -- (default) the Riemann zeta function + - ``"`` -- (default) the Riemann zeta function - - ``'tau'`` -- the L function of the Ramanujan delta - function - - - elliptic curve E -- where E is an elliptic curve over - `\QQ`; defines `L(E,s)` + - ``'tau'`` -- the L function of the Ramanujan delta function + - ``E`` -- an elliptic curve over `\QQ`; defines `L(E,s)` You can also use the complete command-line interface of Rubinstein's `L`-functions calculations program via this @@ -108,12 +105,9 @@ def zeros(self, n, L=''): INPUT: + - ``n`` -- integer - - ``n`` -- integer - - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - + - ``L`` -- defines `L`-function (default: Riemann zeta function) This function also checks the Riemann Hypothesis and makes sure no zeros are missed. This means it looks for several dozen zeros to @@ -144,13 +138,9 @@ def zeros_in_interval(self, x, y, stepsize, L=''): INPUT: + - ``x, y, stepsize`` -- positive floating point numbers - - ``x, y, stepsize`` -- positive floating point - numbers - - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - + - ``L`` -- defines `L`-function (default: Riemann zeta function) OUTPUT: list of pairs (zero, S(T)). @@ -177,12 +167,9 @@ def value(self, s, L=''): INPUT: + - ``s`` -- complex number - - ``s`` -- complex number - - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - + - ``L`` -- defines `L`-function (default: Riemann zeta function) EXAMPLES:: @@ -210,21 +197,14 @@ def values_along_line(self, s0, s1, number_samples, L=''): INPUT: + - ``s0, s1`` -- complex numbers - - ``s0, s1`` -- complex numbers + - ``number_samples`` -- integer - - ``number_samples`` -- integer - - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - - - OUTPUT: - - - - ``list`` -- list of pairs (s, zeta(s)), where the s - are equally spaced sampled points on the line from s0 to s1. + - ``L`` -- defines `L`-function (default: Riemann zeta function) + OUTPUT: list of pairs `(s, L(s))`, where the `s` are equally spaced + sampled points on the line from `s_0` to `s_1` EXAMPLES:: @@ -276,7 +256,6 @@ def values_along_line(self, s0, s1, number_samples, L=''): 2.0 sage: values[4][1] # abs tol 1e-8 0.552975867 + 0.0*I - """ L = self._compute_L(L) CC = ComplexField(prec) @@ -301,22 +280,15 @@ def twist_values(self, s, dmin, dmax, L=''): INPUT: + - ``s`` -- complex numbers - - ``s`` -- complex numbers + - ``dmin`` -- integer - - ``dmin`` -- integer + - ``dmax`` -- integer - - ``dmax`` -- integer - - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - - - OUTPUT: - - - - ``list`` -- list of pairs (d, L(s,chi_d)) + - ``L`` -- defines `L`-function (default: Riemann zeta function) + OUTPUT: list of pairs `(d, L(s,\chi_d))` EXAMPLES:: @@ -372,23 +344,16 @@ def twist_zeros(self, n, dmin, dmax, L=''): INPUT: + - ``n`` -- integer - - ``n`` -- integer - - - ``dmin`` -- integer + - ``dmin`` -- integer - - ``dmax`` -- integer + - ``dmax`` -- integer - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - - - OUTPUT: - - - - ``dict`` -- keys are the discriminants `d`, - and values are list of corresponding zeros. + - ``L`` -- defines `L`-function (default: Riemann zeta function) + OUTPUT: dictionary; keys are the discriminants `d`, and values are list + of corresponding zeros EXAMPLES:: @@ -421,14 +386,11 @@ def analytic_rank(self, L=''): INPUT: - - - ``L`` -- defines `L`-function (default: - Riemann zeta function) - + - ``L`` -- defines `L`-function (default: Riemann zeta function) OUTPUT: integer - .. note:: + .. NOTE:: Of course this is not provably correct in general, since it is an open problem to compute analytic ranks provably diff --git a/src/sage/lfunctions/pari.py b/src/sage/lfunctions/pari.py index 807f48efea6..78af0a49b9e 100644 --- a/src/sage/lfunctions/pari.py +++ b/src/sage/lfunctions/pari.py @@ -1,7 +1,7 @@ """ `L`-functions from PARI -This is a wrapper around the general PARI L-functions functionality. +This is a wrapper around the general PARI `L`-functions functionality. AUTHORS: @@ -36,10 +36,10 @@ class lfun_generic(): where - - ``conductor`` -- integer, the conductor + - ``conductor`` -- integer; the conductor - ``gammaV`` -- list of Gamma-factor parameters, e.g. [0] for - Riemann zeta, [0,1] for ell.curves, (see examples). + Riemann zeta, [0,1] for ell.curves, (see examples) - ``weight`` -- positive real number, usually an integer e.g. 1 for Riemann zeta, 2 for `H^1` of curves/`\QQ` @@ -51,7 +51,7 @@ class lfun_generic(): included - ``residues`` -- vector of residues of `L^*(s)` in those poles or - set residues='automatic' (default value) + set ``residues='automatic'`` (default) - ``init`` -- list of coefficients @@ -63,7 +63,7 @@ class lfun_generic(): sage: lf = lfun_generic(conductor=1, gammaV=[0], weight=1, eps=1, poles=[1], residues=[1]) sage: lf.init_coeffs([1]*2000) - Now we can wrap this PARI L-function into one Sage L-function:: + Now we can wrap this PARI `L`-function into one Sage `L`-function:: sage: L = LFunction(lf); L L-series of conductor 1 and weight 1 @@ -118,11 +118,11 @@ def init_coeffs(self, v, cutoff=None, w=1): INPUT: - - ``v`` -- list of complex numbers or unary function + - ``v`` -- list of complex numbers or unary function - - ``cutoff`` -- unused + - ``cutoff`` -- unused - - ``w`` -- list of complex numbers or unary function + - ``w`` -- list of complex numbers or unary function EXAMPLES:: @@ -131,8 +131,8 @@ def init_coeffs(self, v, cutoff=None, w=1): sage: pari_coeffs = pari('k->vector(k,n,(5*sigma(n,3)+7*sigma(n,5))*n/12 - 35*sum(k=1,n-1,(6*k-4*(n-k))*sigma(k,3)*sigma(n-k,5)))') sage: lf.init_coeffs(pari_coeffs) - Evaluate the resulting L-function at a point, and compare with - the answer that one gets "by definition" (of L-function + Evaluate the resulting `L`-function at a point, and compare with + the answer that one gets "by definition" (of `L`-function attached to a modular form):: sage: L = LFunction(lf) @@ -182,7 +182,7 @@ def init_coeffs(self, v, cutoff=None, w=1): def __pari__(self): """ - Return the PARI L-function object. + Return the PARI `L`-function object. EXAMPLES:: @@ -205,14 +205,12 @@ def __pari__(self): def lfun_character(chi): """ - Create the L-function of a primitive Dirichlet character. + Create the `L`-function of a primitive Dirichlet character. If the given character is not primitive, it is replaced by its associated primitive character. - OUTPUT: - - one :pari:`lfun` object + OUTPUT: one :pari:`lfun` object EXAMPLES:: @@ -256,11 +254,9 @@ def lfun_character(chi): def lfun_hgm(motif, t): """ - Create the L-function of an hypergeometric motive. - - OUTPUT: + Create the `L`-function of an hypergeometric motive. - one :pari:`lfun` object + OUTPUT: one :pari:`lfun` object EXAMPLES:: @@ -278,11 +274,9 @@ def lfun_hgm(motif, t): def lfun_elliptic_curve(E): """ - Create the L-function of an elliptic curve. + Create the `L`-function of an elliptic curve. - OUTPUT: - - one :pari:`lfun` object + OUTPUT: one :pari:`lfun` object EXAMPLES:: @@ -309,9 +303,7 @@ def lfun_number_field(K): """ Create the Dedekind zeta function of a number field. - OUTPUT: - - one :pari:`lfun` object + OUTPUT: one :pari:`lfun` object EXAMPLES:: @@ -333,15 +325,15 @@ def lfun_number_field(K): def lfun_eta_quotient(scalings, exponents): """ - Return the L-function of an eta-quotient. + Return the `L`-function of an eta-quotient. This uses :pari:`lfunetaquo`. INPUT: - - scalings -- a list of integers, the scaling factors + - ``scalings`` -- list of integers; the scaling factors - - exponents -- a list of integers, the exponents + - ``exponents`` -- list of integers; the exponents EXAMPLES:: @@ -368,7 +360,7 @@ def lfun_eta_quotient(scalings, exponents): def lfun_delta(): """ - Return the L-function of Ramanujan's Delta modular form. + Return the `L`-function of Ramanujan's Delta modular form. EXAMPLES:: @@ -382,7 +374,7 @@ def lfun_delta(): def lfun_quadratic_form(qf): """ - Return the L-function of a positive definite quadratic form. + Return the `L`-function of a positive definite quadratic form. This uses :pari:`lfunqf`. @@ -401,7 +393,7 @@ def lfun_quadratic_form(qf): def lfun_genus2(C): """ - Return the L-function of a curve of genus 2. + Return the `L`-function of a curve of genus 2. INPUT: @@ -444,14 +436,14 @@ def lfun_genus2(C): class LFunction(SageObject): r""" - Build the L-function from a PARI L-function. + Build the `L`-function from a PARI `L`-function. .. RUBRIC:: Rank 1 elliptic curve We compute with the `L`-series of a rank `1` curve. :: sage: E = EllipticCurve('37a') - sage: L = E.lseries().dokchitser(algorithm="pari"); L + sage: L = E.lseries().dokchitser(algorithm='pari'); L PARI L-function associated to Elliptic Curve defined by y^2 + y = x^3 - x over Rational Field sage: L(1) 0.000000000000000 @@ -472,7 +464,7 @@ class LFunction(SageObject): `L`-series of a rank `2` elliptic curve:: sage: E = EllipticCurve('389a') - sage: L = E.lseries().dokchitser(algorithm="pari") + sage: L = E.lseries().dokchitser(algorithm='pari') sage: L.num_coeffs() 163 sage: L.derivative(1, E.rank()) @@ -486,7 +478,7 @@ class LFunction(SageObject): sage: x = var('x') sage: K = NumberField(x**4 - x**2 - 1,'a') - sage: L = K.zeta_function(algorithm="pari") + sage: L = K.zeta_function(algorithm='pari') sage: L.conductor 400 sage: L.num_coeffs() @@ -515,12 +507,12 @@ class LFunction(SageObject): """ def __init__(self, lfun, prec=None): """ - Initialization of the L-function from a PARI L-function. + Initialization of the `L`-function from a PARI `L`-function. INPUT: - - lfun -- a PARI :pari:`lfun` object or an instance of :class:`lfun_generic` - - prec -- integer (default: 53) number of *bits* of precision + - ``lfun`` -- a PARI :pari:`lfun` object or an instance of :class:`lfun_generic` + - ``prec`` -- integer (default: 53); number of *bits* of precision EXAMPLES:: @@ -592,11 +584,11 @@ def num_coeffs(self, T=1): EXAMPLES:: sage: E = EllipticCurve('11a') - sage: L = E.lseries().dokchitser(algorithm="pari") + sage: L = E.lseries().dokchitser(algorithm='pari') sage: L.num_coeffs() 27 sage: E = EllipticCurve('5077a') - sage: L = E.lseries().dokchitser(algorithm="pari") + sage: L = E.lseries().dokchitser(algorithm='pari') sage: L.num_coeffs() 591 @@ -612,7 +604,7 @@ def num_coeffs(self, T=1): def Lambda(self, s): """ - Evaluate the completed L-function at s. + Evaluate the completed `L`-function at s. EXAMPLES:: @@ -653,13 +645,13 @@ def hardy(self, t): def derivative(self, s, D=1): """ - Return the derivative of the L-function at point s and order D. + Return the derivative of the `L`-function at point s and order D. INPUT: - - ``s`` -- complex number + - ``s`` -- complex number - - ``D`` -- optional integer (default 1) + - ``D`` -- integer (default: 1) EXAMPLES:: @@ -681,13 +673,11 @@ def taylor_series(self, s, k=6, var='z'): INPUT: - - ``s`` -- complex number; point about which to expand + - ``s`` -- complex number; point about which to expand - - ``k`` -- optional integer (default: 6), series is - `O(``var``^k)` + - ``k`` -- integer (default: 6); series is `O(``var``^k)` - - ``var`` -- optional string (default: 'z'), variable of power - series + - ``var`` -- string (default: ``'z'``); variable of power series EXAMPLES:: @@ -697,7 +687,7 @@ def taylor_series(self, s, k=6, var='z'): sage: L.taylor_series(2, 3) 1.64493406684823 - 0.937548254315844*z + 0.994640117149451*z^2 + O(z^3) sage: E = EllipticCurve('37a') - sage: L = E.lseries().dokchitser(algorithm="pari") + sage: L = E.lseries().dokchitser(algorithm='pari') sage: L.taylor_series(1) 0.000000000000000 + 0.305999773834052*z + 0.186547797268162*z^2 - 0.136791463097188*z^3 + 0.0161066468496401*z^4 + 0.0185955175398802*z^5 + O(z^6) @@ -705,7 +695,7 @@ def taylor_series(self, s, k=6, var='z'): precision:: sage: E = EllipticCurve('389a') - sage: L = E.lseries().dokchitser(200,algorithm="pari") + sage: L = E.lseries().dokchitser(200,algorithm='pari') sage: L.taylor_series(1, 3) 2...e-63 + (...e-63)*z + 0.75931650028842677023019260789472201907809751649492435158581*z^2 + O(z^3) @@ -751,11 +741,11 @@ def _clear_value_cache(self): def __call__(self, s): r""" - Return the value of the L-function at point ``s``. + Return the value of the `L`-function at point ``s``. INPUT: - - ``s`` -- complex number + - ``s`` -- complex number .. NOTE:: @@ -766,7 +756,7 @@ def __call__(self, s): EXAMPLES:: sage: E = EllipticCurve('5077a') - sage: L = E.lseries().dokchitser(100, algorithm="pari") + sage: L = E.lseries().dokchitser(100, algorithm='pari') sage: L(1) 0.00000000000000000000000000000 sage: L(1 + I) diff --git a/src/sage/lfunctions/sympow.py b/src/sage/lfunctions/sympow.py index f500221e398..8368b150eab 100644 --- a/src/sage/lfunctions/sympow.py +++ b/src/sage/lfunctions/sympow.py @@ -2,11 +2,11 @@ Watkins symmetric power `L`-function calculator SYMPOW is a package to compute special values of symmetric power -elliptic curve L-functions. It can compute up to about 64 digits of +elliptic curve `L`-functions. It can compute up to about 64 digits of precision. This interface provides complete access to sympow, which is a standard part of Sage (and includes the extra data files). -.. note:: +.. NOTE:: Each call to ``sympow`` runs a complete ``sympow`` process. This incurs about 0.2 seconds @@ -56,7 +56,7 @@ class Sympow(SageObject): r""" - Watkins Symmetric Power `L`-function Calculator + Watkins Symmetric Power `L`-function Calculator. Type ``sympow.[tab]`` for a list of useful commands that are implemented using the command line interface, but return @@ -100,22 +100,15 @@ def L(self, E, n, prec): INPUT: + - ``E`` -- elliptic curve - - ``E`` -- elliptic curve + - ``n`` -- even integer - - ``n`` -- even integer + - ``prec`` -- integer - - ``prec`` -- integer + OUTPUT: real number to prec digits of precision as a string - - OUTPUT: - - - - ``string`` -- real number to prec digits of precision - as a string. - - - .. note:: + .. NOTE:: Before using this function for the first time for a given `n`, you may have to type ``sympow('-new_data n')``, @@ -156,26 +149,24 @@ def L(self, E, n, prec): def Lderivs(self, E, n, prec, d): r""" - Return `0^{th}` to `d^{th}` derivatives of + Return `0`-th to `d`-th derivatives of `L(\mathrm{Sym}^{(n)}(E,s)` to prec digits of precision, where `s` is the right edge if `n` is even and the center if `n` is odd. INPUT: + - ``E`` -- elliptic curve - - ``E`` -- elliptic curve - - - ``n`` -- integer (even or odd) - - - ``prec`` -- integer + - ``n`` -- integer (even or odd) - - ``d`` -- integer + - ``prec`` -- integer + - ``d`` -- integer - OUTPUT: a string, exactly as output by sympow + OUTPUT: string, exactly as output by sympow - .. note:: + .. NOTE:: To use this function you may have to run a few commands like ``sympow('-new_data 1d2')``, each which takes a @@ -207,15 +198,11 @@ def modular_degree(self, E): INPUT: - - - ``E`` -- elliptic curve over Q - + - ``E`` -- elliptic curve over Q OUTPUT: - - - ``integer`` -- modular degree - + - ``integer`` -- modular degree EXAMPLES: We compute the modular degrees of the lowest known conductor curves of the first few ranks:: @@ -246,24 +233,20 @@ def analytic_rank(self, E): INPUT: - - - ``E`` -- elliptic curve over Q - + - ``E`` -- elliptic curve over Q OUTPUT: + - ``integer`` -- analytic rank - - ``integer`` -- analytic rank - - - ``string`` -- leading coefficient (as string) + - ``string`` -- leading coefficient (as string) - .. note:: + .. NOTE:: - The analytic rank is *not* computed provably correctly in - general. + The analytic rank is *not* computed provably correctly in general. - .. note:: + .. NOTE:: In computing the analytic rank we consider `L^{(r)}(E,1)` to be `0` if @@ -303,7 +286,7 @@ def analytic_rank(self, E): def new_data(self, n): """ - Pre-compute data files needed for computation of n-th symmetric + Pre-compute data files needed for computation of `n`-th symmetric powers. """ print(self('-new_data %s' % n)) @@ -376,11 +359,11 @@ def help(self): sympow('-new_data 6d0h') -will add the data for the 0th derivative of the 6th Hecke power, and +will add the data for the `0`-th derivative of the `6`-th Hecke power, and sympow('-new_data 4c') -will add data for the 4th symmetric power for curves with CM +will add data for the `4`-th symmetric power for curves with CM (these need to be done separately for powers divisible by 4). The mesh files are stored in binary form, and thus endian-ness is a diff --git a/src/sage/lfunctions/zero_sums.pyx b/src/sage/lfunctions/zero_sums.pyx index ce1d06f118c..cefed0fd4ef 100644 --- a/src/sage/lfunctions/zero_sums.pyx +++ b/src/sage/lfunctions/zero_sums.pyx @@ -44,9 +44,8 @@ cdef NCPUS cdef class LFunctionZeroSum_abstract(SageObject): r""" - Abstract class for computing certain sums over zeros of a motivic L-function + Abstract class for computing certain sums over zeros of a motivic `L`-function without having to determine the zeros themselves. - """ cdef _pi # Pi to 64 bits cdef _euler_gamma # Euler-Mascheroni constant = 0.5772... @@ -61,16 +60,14 @@ cdef class LFunctionZeroSum_abstract(SageObject): Set or return the number of CPUs to be used in parallel computations. If called with no input, the number of CPUs currently set is returned; - else this value is set to n. If n is 0 then the number of CPUs is set + else this value is set to `n`. If `n` is 0 then the number of CPUs is set to the max available. INPUT: - - ``n`` -- (default: ``None``) If not ``None``, a nonnegative integer - - OUTPUT: + - ``n`` -- (default: ``None``) if not ``None``, a nonnegative integer - If n is not ``None``, returns a positive integer + OUTPUT: if `n` is not ``None``, returns a positive integer EXAMPLES:: @@ -144,9 +141,9 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - - ``include_euler_gamma`` -- bool (default: ``True``); if set to + - ``include_euler_gamma`` -- boolean (default: ``True``); if set to ``False``, return the constant `\log(N)/2 - \log(2\pi)`, i.e., do - not subtract off the Euler-Mascheroni constant. + not subtract the Euler-Mascheroni constant EXAMPLES:: @@ -165,20 +162,18 @@ cdef class LFunctionZeroSum_abstract(SageObject): Return a list of Dirichlet coefficient of the logarithmic derivative of the `L`-function attached to ``self``, shifted so that the critical line lies on the imaginary axis, up to and - including n. + including `n`. - The i-th element of the returned list is a[i]. + The `i`-th element of the returned list is ``a[i]``. INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer - - ``python_floats`` -- bool (default: ``False``); if ``True`` return a list of - Python floats instead of Sage Real Double Field elements. - - OUTPUT: + - ``python_floats`` -- boolean (default: ``False``); if ``True`` return + a list of Python floats instead of Sage Real Double Field elements - A list of real numbers + OUTPUT: list of real numbers .. SEEALSO:: @@ -224,13 +219,12 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - - ``s`` -- A complex number + - ``s`` -- complex number - - ``include_constant_term`` -- (default: ``True``) boolean; if set - to ``False``, - only the value of the sum over `k` is returned without subtracting - off the Euler-Mascheroni constant, i.e. the returned value is - equal to `\sum_{k=1}^{\infty} \frac{s-1}{k(k+s-1)}`. + - ``include_constant_term`` -- boolean (default: ``True``); if set + to ``False``, only the value of the sum over `k` is returned without + subtracting the Euler-Mascheroni constant, i.e., the returned value + is equal to `\sum_{k=1}^{\infty} \frac{s-1}{k(k+s-1)}` OUTPUT: @@ -298,10 +292,10 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - - ``s`` -- Real or complex value + - ``s`` -- real or complex value - - ``num_terms`` -- (default: 10000) the maximum number of terms - summed in the Dirichlet series. + - ``num_terms`` -- integer (default: 10000); the maximum number of + terms summed in the Dirichlet series OUTPUT: @@ -410,10 +404,10 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - - ``s`` -- Real or complex value + - ``s`` -- real or complex value - - ``num_terms`` -- (default: 10000) the maximum number of terms - summed in the Dirichlet series. + - ``num_terms`` -- integer (default: 10000); the maximum number of + terms summed in the Dirichlet series OUTPUT: @@ -457,7 +451,7 @@ cdef class LFunctionZeroSum_abstract(SageObject): Ls = self.logarithmic_derivative(2 - s, num_terms) return (-self._C1 - self.digamma(2 - s) - Ls[0], Ls[1]) - def zerosum(self, Delta=1, tau=0, function="sincsquared_fast", ncpus=None): + def zerosum(self, Delta=1, tau=0, function='sincsquared_fast', ncpus=None): r""" Bound from above the analytic rank of the form attached to ``self``. @@ -473,7 +467,7 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - ``Delta`` -- positive real number (default: 1) parameter denoting the - tightness of the zero sum. + tightness of the zero sum - ``tau`` -- real parameter (default: 0) denoting the offset of the sum to be computed. When `\tau=0` the sum will converge to the analytic rank @@ -483,27 +477,27 @@ cdef class LFunctionZeroSum_abstract(SageObject): Currently only implemented for the sincsquared and cauchy functions; otherwise ignored. - - ``function`` -- string (default: "sincsquared_fast"); the function + - ``function`` -- string (default: ``'sincsquared_fast'``); the function `f(x)` as described above. Currently implemented options for `f` are - ``sincsquared`` -- `f(x) = \left(\frac{\sin(\pi x)}{\pi x}\right)^2` - - ``gaussian`` -- `f(x) = e^{-x^2}` + - ``gaussian`` -- `f(x) = e^{-x^2}` - - ``sincsquared_fast`` -- Same as "sincsquared", but implementation + - ``sincsquared_fast`` -- same as "sincsquared", but implementation optimized for elliptic curve `L`-functions, and tau must be 0. self must be attached to an elliptic curve over `\QQ` given by its global minimal model, otherwise the returned result will be incorrect. - - ``sincsquared_parallel`` -- Same as "sincsquared_fast", but optimized - for parallel computation with large (>2.0) `\Delta` values. self must + - ``sincsquared_parallel`` -- same as "sincsquared_fast", but optimized + for parallel computation with large (>2.0) `\Delta` values. ``self`` must be attached to an elliptic curve over `\QQ` given by its global minimal model, otherwise the returned result will be incorrect. - ``cauchy`` -- `f(x) = \frac{1}{1+x^2}`; this is only computable to - low precision, and only when `\Delta < 2`. + low precision, and only when `\Delta < 2` - - ``ncpus`` -- (default: ``None``) If not ``None``, a positive integer + - ``ncpus`` -- (default: ``None``) if not ``None``, a positive integer defining the number of CPUs to be used for the computation. If left as ``None``, the maximum available number of CPUs will be used. Only implemented for algorithm="sincsquared_parallel"; ignored @@ -536,17 +530,17 @@ cdef class LFunctionZeroSum_abstract(SageObject): sage: Z = LFunctionZeroSum(E) sage: E.lseries().zeros(3) [0.000000000, 0.000000000, 2.87609907] - sage: Z.zerosum(Delta=1,function="sincsquared_fast") # tol 1.0e-13 + sage: Z.zerosum(Delta=1,function='sincsquared_fast') # tol 1.0e-13 2.037500084595065 - sage: Z.zerosum(Delta=1,function="sincsquared_parallel") # tol 1.0e-11 + sage: Z.zerosum(Delta=1,function='sincsquared_parallel') # tol 1.0e-11 2.037500084595065 - sage: Z.zerosum(Delta=1,function="sincsquared") # tol 1.0e-13 + sage: Z.zerosum(Delta=1,function='sincsquared') # tol 1.0e-13 2.0375000845950644 - sage: Z.zerosum(Delta=1,tau=2.876,function="sincsquared") # tol 1.0e-13 + sage: Z.zerosum(Delta=1,tau=2.876,function='sincsquared') # tol 1.0e-13 1.075551295651154 - sage: Z.zerosum(Delta=1,tau=1.2,function="sincsquared") # tol 1.0e-13 + sage: Z.zerosum(Delta=1,tau=1.2,function='sincsquared') # tol 1.0e-13 0.10831555377490683 - sage: Z.zerosum(Delta=1,function="gaussian") # tol 1.0e-13 + sage: Z.zerosum(Delta=1,function='gaussian') # tol 1.0e-13 2.056890425029435 """ # If Delta>6.95, then exp(2*pi*Delta)>sys.maxsize, so we get overflow @@ -582,7 +576,7 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - ``Delta`` -- positive real number (default: 1) parameter denoting the - tightness of the zero sum. + tightness of the zero sum - ``tau`` -- real parameter (default: 0) denoting the offset of the sum to be computed. When tau=0 the sum will converge from above to the @@ -698,7 +692,7 @@ cdef class LFunctionZeroSum_abstract(SageObject): def _zerosum_gaussian(self, Delta=1): r""" - Return an upper bound on the analytic rank of the L-series attached + Return an upper bound on the analytic rank of the `L`-series attached to ``self`` by computing `\sum_{\gamma} f(\Delta*\gamma)`, where `\gamma` ranges over the imaginary parts of the zeros of `L_E(s)` along the critical strip, and `f(x) = \exp(-x^2)`. @@ -784,8 +778,8 @@ cdef class LFunctionZeroSum_abstract(SageObject): INPUT: - - ``Delta`` -- positive real number (default: 1) parameter denoting the - tightness of the zero sum. + - ``Delta`` -- positive real number (default: 1); parameter denoting the + tightness of the zero sum - ``tau`` -- real parameter (default: 0) denoting the offset of the sum to be computed. When tau=0 the sum will converge from above to the @@ -794,8 +788,8 @@ cdef class LFunctionZeroSum_abstract(SageObject): be 1 (assuming GRH, the zero is simple); otherwise the limit will be 0. - - ``num_terms`` -- positive integer (default: ``None``): the number of - terms computed in the truncated Dirichlet series for the L-function + - ``num_terms`` -- positive integer (default: ``None``); the number of + terms computed in the truncated Dirichlet series for the `L`-function attached to ``self``. If left at ``None``, this is set to `\ceil(e^{2 \pi \Delta})`, the same number of terms used in the other zero sum methods for this value of Delta. @@ -896,7 +890,7 @@ cdef class LFunctionZeroSum_abstract(SageObject): cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): r""" - Subclass for computing certain sums over zeros of an elliptic curve L-function + Subclass for computing certain sums over zeros of an elliptic curve `L`-function without having to determine the zeros themselves. """ cdef _E # The Elliptic curve attached to self @@ -904,18 +898,18 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): def __init__(self, E, N=None, ncpus=1): r""" - Initialize self. + Initialize ``self``. INPUT: - - ``E`` -- An elliptic curve defined over the rational numbers + - ``E`` -- an elliptic curve defined over the rational numbers - - ``N`` -- (default: ``None``) If not ``None``, a positive integer equal to + - ``N`` -- (default: ``None``) if not ``None``, a positive integer equal to the conductor of E. This is passable so that rank estimation can be done for curves whose (large) conductor has been precomputed. - - ``ncpus`` -- (default: 1) The number of CPUs to use for computations. - If set to ``None``, the max available amount will be used. + - ``ncpus`` -- (default: 1) the number of CPUs to use for computations; + if set to ``None``, the max available amount will be used EXAMPLES:: @@ -991,8 +985,8 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): def cn(self, n): r""" - Return the nth Dirichlet coefficient of the logarithmic - derivative of the L-function attached to ``self``, shifted so that + Return the `n`-th Dirichlet coefficient of the logarithmic + derivative of the `L`-function attached to ``self``, shifted so that the critical line lies on the imaginary axis. The returned value is @@ -1006,7 +1000,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer OUTPUT: @@ -1101,7 +1095,6 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): summand for the sinc^2 sum at prime values for when sqrt(bound) < n < bound, bound = exp(t) Called in self._zerosum_sincsquared_fast() method - """ ap = self._e.ellap(n) p = n @@ -1123,7 +1116,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): tightness of the zero sum, and thus the closeness of the returned estimate to the actual analytic rank of the form attached to ``self`` - - ``bad_primes`` -- (default: ``None``) If not ``None``, a list of primes dividing + - ``bad_primes`` -- (default: ``None``) if not ``None``, a list of primes dividing the level of the form attached to ``self``. This is passable so that this method can be run on curves whose conductor is large enough to warrant precomputing bad primes. @@ -1254,7 +1247,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): def _get_residue_data(self, n): r""" - Method called by self._zerosum_sincsquared_parallel() to determine + Method called by ``self._zerosum_sincsquared_parallel()`` to determine the optimal residue class breakdown when sieving for primes. Return a list of small primes, the product thereof, and a list of @@ -1262,19 +1255,19 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): INPUT: - - ``n`` -- Positive integer denoting the number of required chunks. + - ``n`` -- positive integer denoting the number of required chunks OUTPUT: A triple ``(small_primes, M, residue_chunks)`` such that - - ``small_primes`` -- a list of small primes + - ``small_primes`` -- list of small primes - ``modulus`` -- the product of the small primes - - ``residue_chunks`` -- a list of lists consisting of all integers - less than the modulus that are coprime to it, broken into n - sublists of approximately equal size. + - ``residue_chunks`` -- list of lists consisting of all integers + less than the modulus that are coprime to it, broken into `n` + sublists of approximately equal size EXAMPLES:: @@ -1401,12 +1394,12 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): tightness of the zero sum, and thus the closeness of the returned estimate to the actual analytic rank of the form attached to ``self``. - - ``bad_primes`` -- (default: ``None``) If not ``None``, a list of primes dividing + - ``bad_primes`` -- (default: ``None``) if not ``None``, a list of primes dividing the level of the form attached to ``self``. This is passable so that this method can be run on curves whose conductor is large enough to warrant precomputing bad primes. - - ``ncpus`` -- (default: ``None``) If not ``None``, a positive integer + - ``ncpus`` -- (default: ``None``) if not ``None``, a positive integer defining the number of CPUs to be used for the computation. If left as ``None``, the maximum available number of CPUs will be used. @@ -1435,7 +1428,6 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): sage: Z = LFunctionZeroSum(E) sage: print(Z._zerosum_sincsquared_parallel(Delta=1.5,ncpus=2)) # tol 1.0e-11 0.01047120600865063 - """ # If Delta>6.619, then we will most likely get overflow: some ap values # will be too large to fit into a c int @@ -1524,11 +1516,11 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): def analytic_rank_upper_bound(self, max_Delta=None, adaptive=True, - root_number="compute", + root_number='compute', bad_primes=None, ncpus=None): r""" - Return an upper bound for the analytic rank of the L-function + Return an upper bound for the analytic rank of the `L`-function `L_E(s)` attached to ``self``, conditional on the Generalized Riemann Hypothesis, via computing the zero sum `\sum_{\gamma} f(\Delta\gamma)`, where `\gamma` ranges over the imaginary parts of the zeros of `L(E,s)` @@ -1544,7 +1536,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): INPUT: - - ``max_Delta`` -- (default: ``None``) If not ``None``, a positive real value + - ``max_Delta`` -- (default: ``None``) if not ``None``, a positive real value specifying the maximum Delta value used in the zero sum; larger values of Delta yield better bounds - but runtime is exponential in Delta. If left as ``None``, Delta is set @@ -1555,7 +1547,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): results show that for about 99.7% of all curves the returned value is the actual analytic rank. - - ``adaptive`` -- (default: ``True``) Boolean + - ``adaptive`` -- boolean (default: ``True``) - If ``True``, the computation is first run with small and then successively larger Delta values up to max_Delta. If at any @@ -1565,24 +1557,24 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): - If ``False``, the computation is run a single time with Delta=max_Delta, and the resulting bound returned. - - ``root_number`` -- (default: "compute") String or integer + - ``root_number`` -- (default: ``'compute'``) string or integer - - ``"compute"`` -- the root number of self is computed and used to - (possibly) lower the analytic rank estimate by 1. - - ``"ignore"`` -- the above step is omitted + - ``'compute'`` -- the root number of ``self`` is computed and used to + (possibly) lower the analytic rank estimate by 1 + - ``'ignore'`` -- the above step is omitted - ``1`` -- this value is assumed to be the root number of - self. This is passable so that rank estimation can be done for + ``self``. This is passable so that rank estimation can be done for curves whose root number has been precomputed. - ``-1`` -- this value is assumed to be the root number of - self. This is passable so that rank estimation can be done for + ``self``. This is passable so that rank estimation can be done for curves whose root number has been precomputed. - - ``bad_primes`` -- (default: ``None``) If not ``None``, a list of the primes + - ``bad_primes`` -- (default: ``None``) if not ``None``, a list of the primes of bad reduction for the curve attached to ``self``. This is passable so that rank estimation can be done for curves of large conductor whose bad primes have been precomputed. - - ``ncpus`` -- (default: ``None``) If not ``None``, a positive integer + - ``ncpus`` -- (default: ``None``) if not ``None``, a positive integer defining the maximum number of CPUs to be used for the computation. If left as ``None``, the maximum available number of CPUs will be used. Note: Multiple processors will only be used for Delta values >= 1.75. @@ -1601,9 +1593,9 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): OUTPUT: - A non-negative integer greater than or equal to the analytic rank of - self. If the returned value is 0 or 1 (the latter if parity is not - False), then this is the true analytic rank of self. + A nonnegative integer greater than or equal to the analytic rank of + ``self``. If the returned value is 0 or 1 (the latter if parity is not + ``False``), then this is the true analytic rank of ``self``. .. NOTE:: @@ -1645,7 +1637,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): sage: for r in range(9): ....: E = elliptic_curves.rank(r)[0] ....: print((r, E.analytic_rank_upper_bound(max_Delta=1, - ....: adaptive=False,root_number="ignore"))) + ....: adaptive=False,root_number='ignore'))) (0, 0) (1, 1) (2, 2) @@ -1665,9 +1657,9 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): sage: r = E.rank(); r 0 sage: Z = LFunctionZeroSum(E) - sage: Z.analytic_rank_upper_bound(max_Delta=1,root_number="ignore") + sage: Z.analytic_rank_upper_bound(max_Delta=1,root_number='ignore') 1 - sage: Z.analytic_rank_upper_bound(max_Delta=1.3,root_number="ignore") + sage: Z.analytic_rank_upper_bound(max_Delta=1.3,root_number='ignore') 0 Knowing the root number of E allows us to use smaller Delta values @@ -1675,7 +1667,7 @@ cdef class LFunctionZeroSum_EllipticCurve(LFunctionZeroSum_abstract): :: - sage: Z.analytic_rank_upper_bound(max_Delta=0.6,root_number="compute") + sage: Z.analytic_rank_upper_bound(max_Delta=0.6,root_number='compute') 0 The are a small number of curves which have pathologically low-lying @@ -1819,12 +1811,10 @@ def LFunctionZeroSum(X, *args, **kwds): INPUT: - - ``X`` -- A motivic object. Currently only implemented for X = an elliptic curve - over the rational numbers. - - OUTPUT: + - ``X`` -- a motivic object; currently only implemented for X = an elliptic curve + over the rational numbers - An LFunctionZeroSum object. + OUTPUT: an LFunctionZeroSum object EXAMPLES:: diff --git a/src/sage/libs/arb/arith.pyx b/src/sage/libs/arb/arith.pyx index 8bc843aa2a3..bd498f13f43 100644 --- a/src/sage/libs/arb/arith.pyx +++ b/src/sage/libs/arb/arith.pyx @@ -69,7 +69,7 @@ def hilbert_class_polynomial(D): - ``D`` -- negative integer - OUTPUT: an integer polynomial. + OUTPUT: integer polynomial EXAMPLES:: diff --git a/src/sage/libs/braiding.pyx b/src/sage/libs/braiding.pyx index f3849a55d7e..fb856c918c9 100644 --- a/src/sage/libs/braiding.pyx +++ b/src/sage/libs/braiding.pyx @@ -66,7 +66,6 @@ def conjugatingbraid(braid1, braid2): sage: c = B([1,2]) sage: conjugatingbraid(b,c) [[0], [2]] - """ nstrands = max(braid1.parent().strands(), braid2.parent().strands()) l1 = braid1.Tietze() @@ -98,7 +97,6 @@ def leftnormalform(braid): sage: b = B([1,2,1,-2]) sage: leftnormalform(b) [[0], [2, 1]] - """ nstrands = braid.parent().strands() l1 = braid.Tietze() @@ -129,7 +127,6 @@ def rightnormalform(braid): sage: b = B([1,2,1,-2]) sage: rightnormalform(b) [[2, 1], [0]] - """ nstrands = braid.parent().strands() l1 = braid.Tietze() @@ -148,9 +145,7 @@ def greatestcommondivisor(braid1, braid2): - ``braid1`` -- a braid - ``braid2`` -- a braid - OUTPUT: - - A list of lists representing the gcd of ``braid1`` and ``braid2``. + OUTPUT: list of lists representing the gcd of ``braid1`` and ``braid2`` EXAMPLES:: @@ -160,7 +155,6 @@ def greatestcommondivisor(braid1, braid2): sage: b2 = B([2, 2, 2]) sage: greatestcommondivisor(b1, b2) [[-1], [2, 1]] - """ nstrands = max(braid1.parent().strands(), braid2.parent().strands()) l1 = braid1.Tietze() @@ -180,9 +174,7 @@ def leastcommonmultiple(braid1, braid2): - ``braid1`` -- a braid - ``braid2`` -- a braid - OUTPUT: - - A list of lists representing the lcm of ``braid1`` and ``braid2``. + OUTPUT: list of lists representing the lcm of ``braid1`` and ``braid2`` EXAMPLES:: @@ -222,7 +214,6 @@ def centralizer(braid): sage: b = B([1,2,-1]) sage: centralizer(b) [[[-1], [2, 1], [1, 2]], [[0], [1], [1, 2], [2]]] - """ nstrands = braid.parent().strands() lnf = leftnormalform(braid) @@ -248,9 +239,7 @@ def supersummitset(braid): - ``braid`` -- a braid - OUTPUT: - - A list of lists representing the super summit set of ``braid``. + OUTPUT: list of lists representing the super summit set of ``braid`` EXAMPLES:: @@ -259,7 +248,6 @@ def supersummitset(braid): sage: b = B([1,2,-1]) sage: supersummitset(b) [[[0], [2]], [[0], [1]]] - """ nstrands = braid.parent().strands() l = braid.Tietze() @@ -345,9 +333,7 @@ def rigidity(braid): - ``braid`` -- a braid - OUTPUT: - - The rigidity of the braid. + OUTPUT: the rigidity of the braid EXAMPLES:: @@ -356,7 +342,6 @@ def rigidity(braid): sage: c = B([1,1,1,2,2]) sage: rigidity(c) 3 - """ nstrands = braid.parent().strands() l = braid.Tietze() diff --git a/src/sage/libs/coxeter3/coxeter.pyx b/src/sage/libs/coxeter3/coxeter.pyx index 655fc65545c..6f8a651e7eb 100644 --- a/src/sage/libs/coxeter3/coxeter.pyx +++ b/src/sage/libs/coxeter3/coxeter.pyx @@ -55,7 +55,7 @@ cdef class String: def __hash__(self): """ - Return the hash of this String + Return the hash of this String. This is the hash of the tuple consisting of the class name and the name of this type. @@ -595,9 +595,7 @@ cdef class CoxGroup(SageObject): - ``w`` -- a word for an element of ``self``, not necessarily reduced - OUTPUT: - - - a reduced expression for ``w`` + OUTPUT: a reduced expression for ``w`` EXAMPLES:: @@ -623,7 +621,6 @@ cdef class CoxGroup(SageObject): [2 3 1 3 2] [2 2 3 1 3] [2 2 2 3 1] - """ from sage.matrix.constructor import matrix rank = self.rank() @@ -750,13 +747,12 @@ cdef class CoxGroupElement: sage: w = W([1,2,3]) sage: w.parent_group() Coxeter group of type A and rank 5 - """ return self._parent_group def __getitem__(self, i): """ - Return the `i^{th}` entry of this element. + Return the `i`-th entry of this element. EXAMPLES:: @@ -798,7 +794,6 @@ cdef class CoxGroupElement: sage: W = CoxGroup(['A',5]) sage: w = W([1,2,3]); w [1, 2, 3] - """ return repr(list(self)) @@ -1006,7 +1001,6 @@ cdef class CoxGroupElement: [2, 1, 2] sage: w.normal_form() [1, 2, 1] - """ cdef CoxGroupElement res = self._new() self.group.normalForm(res.word) diff --git a/src/sage/libs/coxeter3/coxeter_group.py b/src/sage/libs/coxeter3/coxeter_group.py index 5fa494d4ea3..845feb2fd38 100644 --- a/src/sage/libs/coxeter3/coxeter_group.py +++ b/src/sage/libs/coxeter3/coxeter_group.py @@ -36,7 +36,6 @@ def __classcall__(cls, cartan_type, *args, **options): Coxeter group of type ['B', 2] implemented by Coxeter3 sage: CoxeterGroup(CartanType(['B', 3]).relabel({1: 3, 2: 2, 3: 1})) Coxeter group of type ['B', 3] relabelled by {1: 3, 2: 2, 3: 1} implemented by Coxeter3 - """ from sage.combinat.root_system.cartan_type import CartanType ct = CartanType(cartan_type) @@ -146,7 +145,6 @@ def one(self): sage: W = CoxeterGroup(['A', 3], implementation='coxeter3') sage: W.one() [] - """ return self.element_class(self, []) @@ -194,7 +192,7 @@ def rank(self): def is_finite(self): """ - Return True if this is a finite Coxeter group. + Return ``True`` if this is a finite Coxeter group. EXAMPLES:: @@ -216,7 +214,6 @@ def length(self, x): 2 sage: W.length(W([1,1])) 0 - """ return x.length() @@ -237,7 +234,6 @@ def coxeter_matrix(self): [2 3 1] sage: m.index_set() == W.index_set() True - """ return CoxeterMatrix(self._coxgroup.coxeter_matrix(), self.index_set()) @@ -265,7 +261,6 @@ def _an_element_(self): sage: W = CoxeterGroup(['A', 3], implementation='coxeter3') sage: W._an_element_() [] - """ return self.element_class(self, []) @@ -293,8 +288,9 @@ def kazhdan_lusztig_polynomial(self, u, v, constant_term_one=True): INPUT: - ``u``, ``v`` -- elements of the underlying Coxeter group - - ``constant_term_one`` -- (default: ``True``) True uses the constant equals one convention, - False uses the Leclerc-Thibon convention + - ``constant_term_one`` -- boolean (default: ``True``); ``True`` uses + the constant equals one convention, ``False`` uses the Leclerc-Thibon + convention .. SEEALSO:: @@ -345,7 +341,7 @@ def kazhdan_lusztig_polynomial(self, u, v, constant_term_one=True): We check that Coxeter3 and Sage's implementation give the same results:: sage: C = CoxeterGroup(['B', 3], implementation='coxeter3') - sage: W = WeylGroup("B3",prefix="s") + sage: W = WeylGroup("B3",prefix='s') sage: [s1,s2,s3] = W.simple_reflections() sage: R. = LaurentPolynomialRing(QQ) sage: KL = KazhdanLusztigPolynomial(W,q) @@ -540,7 +536,6 @@ def __getitem__(self, i): 1 sage: w0[1] 2 - """ # Allow the error message to be raised by the underlying element return self.value[i] @@ -625,7 +620,7 @@ def has_right_descent(self, i): def has_left_descent(self, i): """ - Return True if ``i`` is a left descent of this element. + Return ``True`` if ``i`` is a left descent of this element. EXAMPLES:: diff --git a/src/sage/libs/ecl.pyx b/src/sage/libs/ecl.pyx index 1cc38a3ab3a..07650bd3810 100644 --- a/src/sage/libs/ecl.pyx +++ b/src/sage/libs/ecl.pyx @@ -140,7 +140,7 @@ def test_sigint_before_ecl_sig_on(): def test_ecl_options(): """ - Print an overview of the ECL options + Print an overview of the ECL options. TESTS:: @@ -386,7 +386,7 @@ def shutdown_ecl(): # these should be all non-immediate EclObject wrapped objects def print_objects(): r""" - Print GC-protection list + Print GC-protection list. Diagnostic function. ECL objects that are bound to Python objects need to be protected from being garbage collected. We do this by including them @@ -666,7 +666,6 @@ cdef class EclObject: sage: EclObject('"Mαξιμα"') - """ cdef cl_object obj # the wrapped object cdef cl_object node # linked list pointer: car(node) == obj @@ -681,7 +680,7 @@ cdef class EclObject: def __init__(self, *args): r""" - Create an EclObject + Create an EclObject. See EclObject for full documentation. @@ -690,7 +689,6 @@ cdef class EclObject: sage: from sage.libs.ecl import * sage: EclObject([None,true,false]) - """ if not args: return @@ -703,7 +701,7 @@ cdef class EclObject: def __reduce__(self): r""" - This is used for pickling. Not implemented + This is used for pickling. Not implemented. Ecl does not natively support serialization of its objects, so the python wrapper class EclObject does not support pickling. There are @@ -735,13 +733,12 @@ cdef class EclObject: sage: L = EclObject([1,2,("three",'"four"')]) sage: L.python() [1, 2, ('THREE', '"four"')] - """ return ecl_to_python(self.obj) def __dealloc__(self): r""" - Deallocate EclObject + Deallocate EclObject. It is important to remove the GC preventing reference to the object upon deletion of the wrapper. @@ -751,7 +748,6 @@ cdef class EclObject: sage: from sage.libs.ecl import * sage: L=EclObject("symbol") sage: del L - """ if self.node: remove_node(self.node) @@ -769,7 +765,6 @@ cdef class EclObject: sage: L=EclObject("symbol") sage: repr(L) '' - """ return "" @@ -786,7 +781,6 @@ cdef class EclObject: sage: L=EclObject("symbol") sage: str(L) 'SYMBOL' - """ cdef cl_object s s = cl_write_to_string(1, self.obj) @@ -794,7 +788,7 @@ cdef class EclObject: def __hash__(self): r""" - Return a hash value of the object + Return a hash value of the object. Returns the hash value returned by SXHASH, which is a routine that is specified in Common Lisp. According to the specification, lisp objects that @@ -818,13 +812,12 @@ cdef class EclObject: sage: hash(L) #random 140404060 - """ return ecl_fixint(cl_sxhash(self.obj)) def __call__(self, *args): r""" - Apply self to arguments. + Apply ``self`` to arguments. EXAMPLES:: @@ -832,7 +825,6 @@ cdef class EclObject: sage: sqr=EclObject("(lambda (x) (* x x))").eval() sage: sqr(10) - """ lispargs = EclObject(list(args)) return ecl_wrap(ecl_safe_apply(self.obj, (lispargs).obj)) @@ -879,7 +871,7 @@ cdef class EclObject: def __iter__(self): r""" - Implements the iterator protocol for EclObject. + Implement the iterator protocol for EclObject. EclObject implements the iterator protocol for lists. This means one can use an EclObject in the context where an iterator is @@ -926,13 +918,12 @@ cdef class EclObject: Traceback (most recent call last): ... TypeError: ECL object is not iterable - """ return EclListIterator(self) def eval(self): r""" - Evaluate object as an S-Expression + Evaluate object as an S-Expression. EXAMPLES:: @@ -942,7 +933,6 @@ cdef class EclObject: sage: S.eval() - """ cdef cl_object o o=ecl_safe_eval(self.obj) @@ -952,7 +942,7 @@ cdef class EclObject: def cons(self, EclObject d): r""" - apply cons to self and argument and return the result. + Apply cons to ``self`` and argument and return the result. EXAMPLES:: @@ -961,7 +951,6 @@ cdef class EclObject: sage: b=EclObject(2) sage: a.cons(b) - """ return ecl_wrap(cl_cons(self.obj, d.obj)) @@ -979,7 +968,6 @@ cdef class EclObject: sage: L.rplaca(a) sage: L - """ if not(bint_consp(self.obj)): raise TypeError("rplaca can only be applied to a cons") @@ -999,7 +987,6 @@ cdef class EclObject: sage: L.rplacd(a) sage: L - """ if not(bint_consp(self.obj)): raise TypeError("rplacd can only be applied to a cons") @@ -1007,7 +994,7 @@ cdef class EclObject: def car(self): r""" - Return the car of self + Return the car of ``self``. EXAMPLES:: @@ -1032,7 +1019,7 @@ cdef class EclObject: def cdr(self): r""" - Return the cdr of self + Return the cdr of ``self``. EXAMPLES:: @@ -1057,7 +1044,7 @@ cdef class EclObject: def caar(self): r""" - Return the caar of self + Return the caar of ``self``. EXAMPLES:: @@ -1082,7 +1069,7 @@ cdef class EclObject: def cadr(self): r""" - Return the cadr of self + Return the cadr of ``self``. EXAMPLES:: @@ -1107,7 +1094,7 @@ cdef class EclObject: def cdar(self): r""" - Return the cdar of self + Return the cdar of ``self``. EXAMPLES:: @@ -1132,7 +1119,7 @@ cdef class EclObject: def cddr(self): r""" - Return the cddr of self + Return the cddr of ``self``. EXAMPLES:: @@ -1157,7 +1144,7 @@ cdef class EclObject: def fixnump(self): r""" - Return True if self is a fixnum, False otherwise + Return ``True`` if ``self`` is a fixnum, ``False`` otherwise. EXAMPLES:: @@ -1166,13 +1153,12 @@ cdef class EclObject: True sage: EclObject(2**200).fixnump() False - """ return bint_fixnump(self.obj) def characterp(self): r""" - Return True if self is a character, False otherwise + Return ``True`` if ``self`` is a character, ``False`` otherwise. Strings are not characters @@ -1181,13 +1167,12 @@ cdef class EclObject: sage: from sage.libs.ecl import * sage: EclObject('"a"').characterp() False - """ return bint_characterp(self.obj) def nullp(self): r""" - Return True if self is NIL, False otherwise + Return ``True`` if ``self`` is NIL, ``False`` otherwise. EXAMPLES:: @@ -1201,7 +1186,7 @@ cdef class EclObject: def listp(self): r""" - Return True if self is a list, False otherwise. NIL is a list. + Return ``True`` if ``self`` is a list, ``False`` otherwise. NIL is a list. EXAMPLES:: @@ -1215,7 +1200,7 @@ cdef class EclObject: def consp(self): r""" - Return True if self is a cons, False otherwise. NIL is not a cons. + Return ``True`` if ``self`` is a cons, ``False`` otherwise. NIL is not a cons. EXAMPLES:: @@ -1229,7 +1214,7 @@ cdef class EclObject: def atomp(self): r""" - Return True if self is atomic, False otherwise. + Return ``True`` if ``self`` is atomic, ``False`` otherwise. EXAMPLES:: @@ -1238,13 +1223,12 @@ cdef class EclObject: True sage: EclObject([[]]).atomp() False - """ return bint_atomp(self.obj) def symbolp(self): r""" - Return True if self is a symbol, False otherwise. + Return ``True`` if ``self`` is a symbol, ``False`` otherwise. EXAMPLES:: @@ -1253,7 +1237,6 @@ cdef class EclObject: True sage: EclObject([[]]).symbolp() False - """ return bint_symbolp(self.obj) @@ -1279,13 +1262,12 @@ cdef class EclListIterator: Traceback (most recent call last): ... TypeError: ECL object is not iterable - """ cdef EclObject current def __init__(EclListIterator self, EclObject o): r""" - Initialize EclListIterator + Initialize EclListIterator. EXAMPLES:: @@ -1293,7 +1275,6 @@ cdef class EclListIterator: sage: I=EclListIterator(EclObject("(1 2 3)")) sage: type(I) - """ if not o.listp(): raise TypeError("ECL object is not iterable") @@ -1301,7 +1282,7 @@ cdef class EclListIterator: def __iter__(EclListIterator self): r""" - Return self + Return ``self``. It seems standard that iterators return themselves if asked to produce an iterator. @@ -1312,13 +1293,12 @@ cdef class EclListIterator: sage: I=EclListIterator(EclObject("(1 2 3)")) sage: id(I) == id(I.__iter__()) True - """ return self def __next__(EclListIterator self): r""" - Get next element from iterator + Get next element from iterator. EXAMPLES:: @@ -1334,7 +1314,6 @@ cdef class EclListIterator: Traceback (most recent call last): ... StopIteration - """ if self.current.nullp(): @@ -1356,7 +1335,7 @@ cdef EclObject ecl_wrap(cl_object o): # convenience routine to more easily evaluate strings cpdef EclObject ecl_eval(str s): r""" - Read and evaluate string in Lisp and return the result + Read and evaluate string in Lisp and return the result. EXAMPLES:: @@ -1374,7 +1353,6 @@ cpdef EclObject ecl_eval(str s): sage: _(4711) - """ cdef cl_object o o = ecl_safe_eval(python_to_ecl(s, True)) diff --git a/src/sage/libs/eclib/constructor.py b/src/sage/libs/eclib/constructor.py index 4a782cf5a61..79d28b90c1c 100644 --- a/src/sage/libs/eclib/constructor.py +++ b/src/sage/libs/eclib/constructor.py @@ -6,10 +6,12 @@ def CremonaModularSymbols(level, sign=0, cuspidal=False, verbose=0): INPUT: - - ``level`` -- an integer >= 2 (at least 2, not just positive!) - - ``sign`` -- an integer either 0 (the default) or 1 or -1. - - ``cuspidal`` -- (default: ``False``); if True, compute only the cuspidal subspace - - ``verbose`` -- (default: ``False``): if True, print verbose information while creating space + - ``level`` -- integer; at least 2, not just positive! + - ``sign`` -- integer (default: 0); either 0 or 1 or -1 + - ``cuspidal`` -- boolean (default: ``False``); if ``True``, compute only + the cuspidal subspace + - ``verbose`` -- boolean (default: ``False``); if ``True``, print verbose + information while creating space EXAMPLES:: @@ -44,7 +46,7 @@ def CremonaModularSymbols(level, sign=0, cuspidal=False, verbose=0): sage: M Cremona Modular Symbols space of dimension 7 for Gamma_0(43) of weight 2 with sign 0 - The input must be valid or a :class:`ValueError` is raised:: + The input must be valid or a :exc:`ValueError` is raised:: sage: M = CremonaModularSymbols(-1) Traceback (most recent call last): diff --git a/src/sage/libs/eclib/homspace.pyx b/src/sage/libs/eclib/homspace.pyx index d9bb6150540..a502062ff79 100644 --- a/src/sage/libs/eclib/homspace.pyx +++ b/src/sage/libs/eclib/homspace.pyx @@ -29,10 +29,10 @@ cdef class ModularSymbols: INPUT: - - ``level`` (int) -- the level: an integer, at least 2. - - ``sign`` (int, default 0) -- the sign: 0, +1 or -1 - - ``cuspidal`` (boolean, default: ``False``) -- True for cuspidal homology - - ``verbose`` (int, default 0) -- verbosity level + - ``level`` -- integer; the level: at least 2 + - ``sign`` -- integer (default: 0); the sign: 0, +1 or -1 + - ``cuspidal`` -- boolean (default: ``False``); ``True`` for cuspidal homology + - ``verbose`` -- integer (default: 0); verbosity level EXAMPLES:: @@ -164,11 +164,11 @@ cdef class ModularSymbols: - ``p`` -- a prime number - - ``dual`` -- (default: ``False``) whether to compute the Hecke - operator acting on the dual space, i.e., the - transpose of the Hecke operator + - ``dual`` -- boolean (default: ``False``); whether to compute the + Hecke operator acting on the dual space, i.e., the transpose of the + Hecke operator - - ``verbose`` -- (default: ``False``) print verbose output + - ``verbose`` -- boolean (default: ``False``); print verbose output OUTPUT: @@ -224,11 +224,11 @@ cdef class ModularSymbols: - ``p`` -- a prime number - - ``dual`` -- (default: ``False``) whether to compute the Hecke - operator acting on the dual space, i.e., the - transpose of the Hecke operator + - ``dual`` -- boolean (default: ``False``); whether to compute the + Hecke operator acting on the dual space, i.e., the transpose of the Hecke + operator - - ``verbose`` -- (default: ``False``) print verbose output + - ``verbose`` -- boolean (default: ``False``); print verbose output OUTPUT: diff --git a/src/sage/libs/eclib/interface.py b/src/sage/libs/eclib/interface.py index 6c15997c09f..a5e65a37d4d 100644 --- a/src/sage/libs/eclib/interface.py +++ b/src/sage/libs/eclib/interface.py @@ -9,7 +9,7 @@ :class:`EllipticCurve ` and call methods that are implemented using this module. -.. note:: +.. NOTE:: This interface is a direct library-level interface to ``eclib``, including the 2-descent program ``mwrank``. @@ -47,10 +47,10 @@ class mwrank_EllipticCurve(SageObject): INPUT: - - ``ainvs`` (list or tuple) -- a list of 5 or less integers, the - coefficients of a nonsingular Weierstrass equation. + - ``ainvs`` -- list or tuple list of 5 or less integers, the + coefficients of a nonsingular Weierstrass equation - - ``verbose`` (bool, default ``False``) -- verbosity flag. If ``True``, + - ``verbose`` -- boolean (default: ``False``); verbosity flag. If ``True``, then all Selmer group computations will be verbose. EXAMPLES: @@ -146,8 +146,8 @@ def set_verbose(self, verbose): INPUT: - - ``verbose`` (int) -- if positive, print lots of output when - doing 2-descent. + - ``verbose`` -- integer; if positive, print lots of output when + doing 2-descent EXAMPLES:: @@ -196,7 +196,7 @@ def set_verbose(self, verbose): def _curve_data(self): r""" - Returns the underlying :class:`_Curvedata` class for this mwrank elliptic curve. + Return the underlying :class:`_Curvedata` class for this mwrank elliptic curve. EXAMPLES:: @@ -212,7 +212,7 @@ def _curve_data(self): def ainvs(self): r""" - Returns the `a`-invariants of this mwrank elliptic curve. + Return the `a`-invariants of this mwrank elliptic curve. EXAMPLES:: @@ -224,7 +224,7 @@ def ainvs(self): def isogeny_class(self, verbose=False): r""" - Returns the isogeny class of this mwrank elliptic curve. + Return the isogeny class of this mwrank elliptic curve. EXAMPLES:: @@ -236,7 +236,7 @@ def isogeny_class(self, verbose=False): def __repr__(self): r""" - Returns the string representation of this mwrank elliptic curve. + Return the string representation of this mwrank elliptic curve. EXAMPLES:: @@ -256,42 +256,34 @@ def __repr__(self): ' '.join([coeff(a4), 'x']) if a4 else '', ' '.join([" +" if a6 > 0 else " -", str(abs(a6))]) if a6 else '']) - def two_descent(self, - verbose=True, - selmer_only=False, - first_limit=20, - second_limit=8, - n_aux=-1, - second_descent=True): + def two_descent(self, verbose=True, selmer_only=False, first_limit=20, + second_limit=8, n_aux=-1, second_descent=True): r""" Compute 2-descent data for this curve. INPUT: - - ``verbose`` (bool, default ``True``) -- print what mwrank is doing. + - ``verbose`` -- boolean (default: ``True``); print what mwrank is doing - - ``selmer_only`` (bool, default ``False``) -- ``selmer_only`` switch. + - ``selmer_only`` -- boolean (default: ``False``); ``selmer_only`` switch - - ``first_limit`` (int, default 20) -- bound on `|x|+|z|` in - quartic point search. + - ``first_limit`` -- integer (default: 20); bound on `|x|+|z|` in + quartic point search - - ``second_limit`` (int, default 8) -- bound on - `\log \max(|x|,|z|)`, i.e. logarithmic. + - ``second_limit`` -- integer (default: 8); bound on + `\log \max(|x|,|z|)`, i.e. logarithmic - - ``n_aux`` (int, default -1) -- (only relevant for general + - ``n_aux`` -- integer (default: -1); (only relevant for general 2-descent when 2-torsion trivial) number of primes used for quartic search. ``n_aux=-1`` causes default (8) to be used. Increase for curves of higher rank. - - ``second_descent`` (bool, default ``True``) -- (only relevant + - ``second_descent`` -- boolean (default: ``True``); (only relevant for curves with 2-torsion, where mwrank uses descent via 2-isogeny) flag determining whether or not to do second descent. *Default strongly recommended.* - - OUTPUT: - - Nothing -- nothing is returned. + OUTPUT: nothing TESTS: @@ -357,7 +349,7 @@ def two_descent(self, def __two_descent_data(self): r""" - Returns the 2-descent data for this elliptic curve. + Return the 2-descent data for this elliptic curve. EXAMPLES:: @@ -374,7 +366,7 @@ def conductor(self): Return the conductor of this curve, computed using Cremona's implementation of Tate's algorithm. - .. note:: + .. NOTE:: This is independent of PARI's. @@ -388,7 +380,7 @@ def conductor(self): def rank(self): """ - Returns the rank of this curve, computed using :meth:`two_descent()`. + Return the rank of this curve, computed using :meth:`two_descent()`. In general this may only be a lower bound for the rank; an upper bound may be obtained using the function :meth:`rank_bound()`. @@ -410,13 +402,12 @@ def rank(self): 0 sage: E.certain() False - """ return self.__two_descent_data().getrank() def rank_bound(self): """ - Returns an upper bound for the rank of this curve, computed + Return an upper bound for the rank of this curve, computed using :meth:`two_descent()`. If the curve has no 2-torsion, this is equal to the 2-Selmer @@ -460,13 +451,12 @@ def rank_bound(self): 0 sage: E.certain() False - """ return self.__two_descent_data().getrankbound() def selmer_rank(self): r""" - Returns the rank of the 2-Selmer group of the curve. + Return the rank of the 2-Selmer group of the curve. EXAMPLES: @@ -510,7 +500,6 @@ def selmer_rank(self): 0 sage: E.certain() False - """ return self.__two_descent_data().getselmer() @@ -536,13 +525,13 @@ def saturate(self, bound=-1, lower=2): INPUT: - - ``bound`` (int, default -1) -- If `-1`, saturate at *all* + - ``bound`` -- integer (default: -1); if `-1`, saturate at *all* primes by computing a bound on the saturation index, otherwise saturate at all primes up to the minimum of - ``bound`` and the saturation index bound. + ``bound`` and the saturation index bound - - ``lower`` (int, default 2) -- Only saturate at primes not - less than this. + - ``lower`` -- integer (default: 2); only saturate at primes not + less than this EXAMPLES: @@ -584,7 +573,7 @@ def gens(self) -> list: def certain(self): r""" - Returns ``True`` if the last :meth:`two_descent()` call provably correctly + Return ``True`` if the last :meth:`two_descent()` call provably correctly computed the rank. If :meth:`two_descent()` hasn't been called, then it is first called by :meth:`certain()` using the default parameters. @@ -675,21 +664,21 @@ class mwrank_MordellWeil(SageObject): INPUT: - - ``curve`` (:class:`mwrank_EllipticCurve`) -- the underlying - elliptic curve. + - ``curve`` -- :class:`mwrank_EllipticCurve`; the underlying + elliptic curve - - ``verbose`` (bool, default ``False``) -- verbosity flag (controls - amount of output produced in point searches). + - ``verbose`` -- boolean (default: ``False``); verbosity flag (controls + amount of output produced in point searches) - - ``pp`` (int, default 1) -- process points flag (if nonzero, + - ``pp`` -- integer (default: 1); process points flag (if nonzero, the points found are processed, so that at all times only a `\ZZ`-basis for the subgroup generated by the points found - so far is stored; if zero, no processing is done and all + so far is stored. If zero, no processing is done and all points found are stored). - - ``maxr`` (int, default 999) -- maximum rank (quit point + - ``maxr`` -- integer (default: 999); maximum rank (quit point searching once the points found generate a subgroup of this - rank; useful if an upper bound for the rank is already + rank. Useful if an upper bound for the rank is already known). EXAMPLES:: @@ -850,13 +839,13 @@ def process(self, v, saturation_bound=0): INPUT: - - ``v`` (list of 3-tuples or lists of ints or Integers) -- a + - ``v`` -- list of 3-tuples or lists of ints or Integers; a list of triples of integers, which define points on the - curve. + curve - - ``saturation_bound`` (int, default 0) -- saturate at primes up to - ``saturation_bound``, or at *all* primes if ``saturation_bound`` is -1; when ``saturation_bound`` - is 0 (the default), do no saturation.. + - ``saturation_bound`` -- integer (default: 0); saturate at primes up to + ``saturation_bound``, or at *all* primes if ``saturation_bound`` is + -1. When ``saturation_bound`` is 0 (the default), do no saturation. OUTPUT: @@ -1000,7 +989,7 @@ def regulator(self): Return the regulator of the points in this subgroup of the Mordell-Weil group. - .. note:: + .. NOTE:: ``eclib`` can compute the regulator to arbitrary precision, but the interface currently returns the output as a ``float``. @@ -1025,9 +1014,7 @@ def rank(self): """ Return the rank of this subgroup of the Mordell-Weil group. - OUTPUT: - - (int) The rank of this subgroup of the Mordell-Weil group. + OUTPUT: integer EXAMPLES:: @@ -1067,7 +1054,6 @@ def rank(self): 0.417143558758384 We do in fact now have a full Mordell-Weil basis. - """ return self.__mw.rank() @@ -1076,13 +1062,13 @@ def saturate(self, max_prime=-1, min_prime=2): INPUT: - - ``max_prime`` (int, default -1) -- If `-1` (the default), an + - ``max_prime`` -- integer (default: -1); if `-1`, an upper bound is computed for the primes at which the subgroup may not be saturated, and saturation is performed for all primes up to this bound. Otherwise, the bound used is the minimum of ``max_prime`` and the computed bound. - - ``min_prime`` (int, default 2) -- only do saturation at + - ``min_prime`` -- integer (default: 2); only do saturation at primes no less than this. (For example, if the points have been found via :meth:`two_descent` they should already be 2-saturated so a value of 3 is appropriate.) @@ -1091,18 +1077,18 @@ def saturate(self, max_prime=-1, min_prime=2): (3-tuple) (``ok``, ``index``, ``unsatlist``) where: - - ``ok`` (bool) -- ``True`` if and only if the saturation was + - ``ok`` -- boolean; ``True`` if and only if the saturation was provably successful at all primes attempted. If the default was used for ``max_prime``, then ``True`` indicates that the subgroup is saturated at *all* primes. - - ``index`` (int) -- the index of the group generated by the - original points in their saturation. + - ``index`` -- integer; the index of the group generated by the + original points in their saturation - - ``unsatlist`` (list of ints) -- list of primes at which - saturation could not be proved or achieved. + - ``unsatlist`` -- list of ints list of primes at which + saturation could not be proved or achieved - .. note:: + .. NOTE:: In versions up to v20190909, ``eclib`` used floating point methods based on elliptic logarithms to divide points, and @@ -1111,7 +1097,7 @@ def saturate(self, max_prime=-1, min_prime=2): on division polynomials, which should mean that such failures does not happen. - .. note:: + .. NOTE:: We emphasize that if this function returns ``True`` as the first return argument (``ok``), and if the default was used @@ -1230,7 +1216,6 @@ def saturate(self, max_prime=-1, min_prime=2): index of the points in their saturation is at most 3, then proves saturation at 2 and at 3, by reducing the points modulo all primes of good reduction up to 11, respectively 13. - """ ok, index, unsat = self.__mw.saturate(int(max_prime), int(min_prime)) return bool(ok), int(str(index)), unsat @@ -1242,10 +1227,10 @@ def search(self, height_limit=18, verbose=False): INPUT: - - ``height_limit`` (float, default: 18) -- search up to this - logarithmic height. + - ``height_limit``-- float (default: 18); search up to this + logarithmic height - .. note:: + .. NOTE:: On 32-bit machines, this *must* be < 21.48 (`31\log(2)`) else `\exp(h_{\text{lim}}) > 2^{31}` and overflows. On 64-bit machines, it @@ -1254,15 +1239,15 @@ def search(self, height_limit=18, verbose=False): by (roughly) `\exp(1.5)=4.5`, so searching up to even 20 takes a very long time. - .. note:: + .. NOTE:: The search is carried out with a quadratic sieve, using code adapted from a version of Michael Stoll's ``ratpoints`` program. It would be preferable to use a newer version of ``ratpoints``. - - ``verbose`` (bool, default ``False``) -- turn verbose operation on - or off. + - ``verbose`` -- boolean (default: ``False``)turn verbose operation on + or off EXAMPLES: @@ -1311,11 +1296,9 @@ def points(self): Return a list of the generating points in this Mordell-Weil group. - OUTPUT: - - (list) A list of lists of length 3, each holding the + OUTPUT: list of lists of length 3, each holding the primitive integer coordinates `[x,y,z]` of a generating - point. + point EXAMPLES:: diff --git a/src/sage/libs/eclib/mat.pyx b/src/sage/libs/eclib/mat.pyx index e43fd01cec6..a5ef4f45c68 100644 --- a/src/sage/libs/eclib/mat.pyx +++ b/src/sage/libs/eclib/mat.pyx @@ -151,7 +151,7 @@ cdef class Matrix: def add_scalar(self, scalar s): """ - Return new matrix obtained by adding s to each diagonal entry of self. + Return new matrix obtained by adding `s` to each diagonal entry of ``self``. EXAMPLES:: @@ -193,7 +193,7 @@ cdef class Matrix: INPUT: - - ``sparse`` -- (default: ``True``) whether the return matrix has + - ``sparse`` -- boolean (default: ``True``); whether the return matrix has a sparse representation EXAMPLES:: diff --git a/src/sage/libs/eclib/mwrank.pyx b/src/sage/libs/eclib/mwrank.pyx index c4f9ed87d18..cdac5a145cb 100644 --- a/src/sage/libs/eclib/mwrank.pyx +++ b/src/sage/libs/eclib/mwrank.pyx @@ -85,9 +85,7 @@ def get_precision(): Return the working floating point bit precision of mwrank, which is equal to the global NTL real number precision. - OUTPUT: - - (int) The current precision in bits. + OUTPUT: integer; the current precision in bits See also :meth:`set_precision`. @@ -101,7 +99,7 @@ def get_precision(): def set_precision(n): """ - Sets the working floating point bit precision of mwrank, which is + Set the working floating point bit precision of mwrank, which is equal to the global NTL real number precision. NTL real number bit precision. This has a massive effect on the @@ -111,7 +109,7 @@ def set_precision(n): INPUT: - - ``n`` -- a positive integer: the number of bits of precision. + - ``n`` -- positive integer; the number of bits of precision .. warning:: @@ -146,9 +144,9 @@ def initprimes(filename, verb=False): INPUT: - - ``filename`` (string) -- the name of a file of primes. + - ``filename`` -- string; the name of a file of primes - - ``verb`` (bool: default ``False``) -- verbose or not? + - ``verb`` -- boolean (default: ``False``); verbose or not EXAMPLES:: @@ -187,7 +185,7 @@ cdef class _bigint: """ cdef bigint* x - def __init__(self, x="0"): + def __init__(self, x='0'): """ Constructor for bigint class. @@ -252,18 +250,16 @@ cdef make_bigint(bigint* x): cdef class _Curvedata: # cython class wrapping eclib's Curvedata class cdef Curvedata* x - def __init__(self, a1, a2, a3, - a4, a6, min_on_init=0): + def __init__(self, a1, a2, a3, a4, a6, min_on_init=0): """ Constructor for Curvedata class. INPUT: - - ``a1``, ``a2``, ``a3``, ``a4``, ``a6`` (int) -- integer - coefficients of a Weierstrass equation (must be - nonsingular). + - ``a1``, ``a2``, ``a3``, ``a4``, ``a6`` -- integer coefficients of a + Weierstrass equation (must be nonsingular) - - ``min_on_init`` (int, default 0) -- flag controlling whether + - ``min_on_init`` -- integer (default: 0); flag controlling whether the constructed curve is replaced by a global minimal model. If nonzero then this minimisation does take place. @@ -312,11 +308,7 @@ cdef class _Curvedata: # cython class wrapping eclib's Curvedata class def __repr__(self): r""" - String representation of Curvedata - - OUTPUT: - - (string) the Curvedata as a string + String representation of Curvedata. EXAMPLES:: @@ -340,7 +332,7 @@ cdef class _Curvedata: # cython class wrapping eclib's Curvedata class OUTPUT: - (float) A non-negative real number `B` such that for every + (float) A nonnegative real number `B` such that for every rational point on this elliptic curve `E`, `h(P)\le\hat{h}(P) + B`, where `h(P)` is the naive height and `\hat{h}(P)` the canonical height. @@ -369,7 +361,7 @@ cdef class _Curvedata: # cython class wrapping eclib's Curvedata class OUTPUT: - (float) A non-negative real number `B` such that for every + (float) A nonnegative real number `B` such that for every rational point on this elliptic curve `E`, `h(P)\le\hat{h}(P) + B`, where `h(P)` is the naive height and `\hat{h}(P)` the canonical height. @@ -403,7 +395,7 @@ cdef class _Curvedata: # cython class wrapping eclib's Curvedata class OUTPUT: - (float) A non-negative real number `B` such that for every + (float) A nonnegative real number `B` such that for every rational point on this elliptic curve `E`, `h(P)\le\hat{h}(P) + B`, where `h(P)` is the naive height and `\hat{h}(P)` the canonical height. This is the minimum of the Silverman and @@ -492,7 +484,6 @@ cdef class _Curvedata: # cython class wrapping eclib's Curvedata class 14 sage: E.isogeny_class() ([[1, 0, 1, 4, -6], [1, 0, 1, -36, -70], [1, 0, 1, -1, 0], [1, 0, 1, -171, -874], [1, 0, 1, -11, 12], [1, 0, 1, -2731, -55146]], [[0, 2, 3, 3, 0, 0], [2, 0, 0, 0, 3, 3], [3, 0, 0, 0, 2, 0], [3, 0, 0, 0, 0, 2], [0, 3, 2, 0, 0, 0], [0, 3, 0, 2, 0, 0]]) - """ sig_on() s = string_sigoff(Curvedata_isogeny_class(self.x, verbose)) @@ -507,12 +498,11 @@ def parse_point_list(s): INPUT: - - ``s`` (string) -- string representation of a list of points, for - example '[]', '[[1:2:3]]', or '[[1:2:3],[4:5:6]]'. + - ``s`` -- string representation of a list of points; for + example '[]', '[[1:2:3]]', or '[[1:2:3],[4:5:6]]' - OUTPUT: - - (list) a list of triples of integers, for example [], [[1,2,3]], [[1,2,3],[4,5,6]]. + OUTPUT: list of triples of integers, for example [], [[1,2,3]], + [[1,2,3],[4,5,6]] EXAMPLES:: @@ -523,7 +513,6 @@ def parse_point_list(s): [[1, 2, 3]] sage: parse_point_list('[[1:2:3],[4:5:6]]') [[1, 2, 3], [4, 5, 6]] - """ s = s.replace(":", ",").replace(" ", "") if s == '[]': @@ -546,21 +535,20 @@ cdef class _mw: INPUT: - - ``curve`` (_Curvedata) -- an elliptic curve + - ``curve`` -- _Curvedata; an elliptic curve - - ``verb`` (bool, default ``False``) -- verbosity flag (controls + - ``verb`` -- boolean (default: ``False``); verbosity flag (controls amount of output produced in point searches) - - ``pp`` (int, default 1) -- process points flag (if nonzero, + - ``pp`` -- integer (default: 1); process points flag (if nonzero, the points found are processed, so that at all times only a `\ZZ`-basis for the subgroup generated by the points found - so far is stored; if zero, no processing is done and all + so far is stored. If zero, no processing is done and all points found are stored). - - ``maxr`` (int, default 999) -- maximum rank (quit point + - ``maxr`` -- integer (default: 999); maximum rank (quit point searching once the points found generate a subgroup of this - rank; useful if an upper bound for the rank is already - known). + rank. Useful if an upper bound for the rank is already known). EXAMPLES:: @@ -649,7 +637,6 @@ cdef class _mw: sage: EQ = _mw(E, pp=0) sage: EQ.search(1); EQ [[-3:0:1], [-2:3:1], [-14:25:8], [-1:3:1], [0:2:1], [2:13:8], [1:0:1], [2:0:1], [18:7:8], [3:3:1], [4:6:1], [36:69:64], [68:-25:64], [12:35:27]] - """ self.curve = curve.x self.x = new mw(curve.x, verb, pp, maxr) @@ -690,16 +677,15 @@ cdef class _mw: INPUT: - - ``point`` (tuple or list) -- tuple or list of 3 integers. - An ``ArithmeticError`` is raised if the point is not on the - curve. + - ``point`` -- tuple or list of 3 integers; an :exc:`ArithmeticError` is + raised if the point is not on the curve - - ``saturation_bound`` (int, default 0) --saturate at primes up to ``saturation_bound``. - No saturation is done if ``saturation_bound=0``. If ``saturation_bound=-1`` then + - ``saturation_bound`` -- integer (default: 0); saturate at primes up + to ``saturation_bound``. No saturation is done if + ``saturation_bound=0``. If ``saturation_bound=-1`` then saturation is done at all primes, by computing a bound on the saturation index. Note that it is more efficient to add - several points at once and then saturate just once at the - end. + several points at once and then saturate just once at the end. .. NOTE:: @@ -738,7 +724,6 @@ cdef class _mw: sage: EQ.process([4,8,1]) sage: EQ [[-1:1:1], [0:-1:1]] - """ if not isinstance(point, (tuple, list)) and len(point) == 3: raise TypeError("point must be a list or tuple of length 3.") @@ -838,13 +823,13 @@ cdef class _mw: INPUT: - - ``sat_bnd`` (int, default -1) -- upper bound on primes at + - ``sat_bnd`` -- integer (default: -1); upper bound on primes at which to saturate. If -1 (default), compute a bound for the primes which may not be saturated, and use that. Otherwise, the bound used is the minimum of the value of ``sat_bnd`` and the computed bound. - - ``sat_low_bd`` (int, default 2) -- only do saturation at + - ``sat_low_bd`` -- integer (default: 2); only do saturation at prime not less than this. For exampe, if the points have been found via 2-descent they should already be 2-saturated, and ``sat_low_bd=3`` is appropriate. @@ -896,7 +881,6 @@ cdef class _mw: (1, 1, '[ ]') sage: EQ [[494:-5720:6859]] - """ cdef long index cdef char* s @@ -912,13 +896,13 @@ cdef class _mw: INPUT: - - ``h_lim`` (int) -- bound on logarithmic naive height of points + - ``h_lim`` -- integer; bound on logarithmic naive height of points - - ``moduli_option`` (int, default 0) -- option for sieving + - ``moduli_option`` -- integer (default: 0); option for sieving strategy. The default (0) uses an adapted version of Stoll's ratpoints code and is recommended. - - ``verb`` (int, default 0) -- level of verbosity. If 0, no + - ``verb`` -- integer (default: 0); level of verbosity. If 0, no output. If positive, the points are output as found and some details of the processing, finding linear relations, and partial saturation are output. @@ -932,9 +916,7 @@ cdef class _mw: will always contain a `\ZZ`-span of the saturation of the points found, modulo torsion. - OUTPUT: - - None. The effect of the search is to update the list of generators. + OUTPUT: none; the effect of the search is to update the list of generators EXAMPLES:: @@ -1001,25 +983,25 @@ cdef class _two_descent: INPUT: - - ``curvedata`` (_Curvedata) -- the curve on which to do descent. + - ``curvedata`` -- _Curvedata; the curve on which to do descent - - ``verb`` (int, default 1) -- verbosity level. + - ``verb`` -- integer (default: 1); verbosity level - - ``sel`` (int, default 0) -- Selmer-only flag. If 1, only + - ``sel`` -- integer (default: 0); Selmer-only flag. If 1, only the 2-Selmer group will be computed, with no rational points. Useful as a faster way of getting an upper bound on the rank. - - ``firstlim`` (int, default 20) -- naive height bound on + - ``firstlim`` -- integer (default: 20); naive height bound on first point search on quartic homogeneous spaces (before testing local solubility; very simple search with no overheads). - - ``secondlim`` (int, default 8) -- naive height bound on + - ``secondlim`` -- integer (default: 8); naive height bound on second point search on quartic homogeneous spaces (after testing local solubility; sieve-assisted search) - - ``n_aux`` (int, default -1) -- If positive, the number of + - ``n_aux`` -- integer (default: -1); if positive, the number of auxiliary primes used in sieve-assisted search for quartics. If -1 (the default) use a default value (set in the eclib code in ``src/qrank/mrank1.cc`` in DEFAULT_NAUX: currently 8). @@ -1028,15 +1010,13 @@ cdef class _two_descent: expected to be of rank > 6 to one or two more than the expected rank. - - ``second_descent`` (int, default 1) -- flag specifying + - ``second_descent`` -- integer (default: 1); flag specifying whether or not a second descent will be carried out (yes if 1, the default; no if 0). Only relevant for curves with 2-torsion. Recommended left as the default except for experts interested in details of Selmer groups. - OUTPUT: - - None + OUTPUT: none EXAMPLES:: @@ -1167,9 +1147,7 @@ cdef class _two_descent: """ Return the success flag (after doing a 2-descent). - OUTPUT: - - (bool) Flag indicating whether or not 2-descent was successful. + OUTPUT: boolean flag indicating whether or not 2-descent was successful EXAMPLES:: @@ -1196,9 +1174,7 @@ cdef class _two_descent: """ Return the certainty flag (after doing a 2-descent). - OUTPUT: - - (bool) ``True`` if the rank upper and lower bounds are equal. + OUTPUT: boolean; ``True`` if the rank upper and lower bounds are equal EXAMPLES:: @@ -1227,18 +1203,16 @@ cdef class _two_descent: INPUT: - - ``saturation_bound`` (int) -- an upper bound on the primes + - ``saturation_bound`` -- integer; an upper bound on the primes `p` at which `p`-saturation will be carried out, or -1, in which case ``eclib`` will compute an upper bound on the saturation index. - - ``lower`` (int, default 3) -- do no `p`-saturation for `p` + - ``lower`` -- integer (default: 3); do no `p`-saturation for `p` less than this. The default is 3 since the points found during 2-descent will be 2-saturated. - OUTPUT: - - None. + OUTPUT: none EXAMPLES:: @@ -1280,7 +1254,7 @@ cdef class _two_descent: .. NOTE:: - You must call ``saturate()`` first, or a ``RunTimeError`` + You must call ``saturate()`` first, or a :exc:`RunTimeError` will be raised. OUTPUT: diff --git a/src/sage/libs/eclib/newforms.pyx b/src/sage/libs/eclib/newforms.pyx index 65bd5412db5..d2af433a801 100644 --- a/src/sage/libs/eclib/newforms.pyx +++ b/src/sage/libs/eclib/newforms.pyx @@ -134,11 +134,11 @@ cdef class ECModularSymbol: - ``E``- an elliptic curve defined over Q. - - ``sign`` (int) -- 0 or +1. If +1, only plus modular symbols + - ``sign`` -- integer; 0 or +1. If +1, only plus modular symbols of this sign are available. If 0, modular symbols of both signs are available but the construction is more expensive. - - ``nap`` -- (int, default 1000): the number of ap of E to use + - ``nap`` -- integer (default: 1000); the number of ap of E to use in determining the normalisation of the modular symbols. Note that eclib will increase this to 100*sqrt(N) if necessary. @@ -240,18 +240,20 @@ cdef class ECModularSymbol: return "Modular symbol with sign %s over Rational Field attached to %s"%(self.sign, self._E) def __call__(self, r, sign=None, base_at_infinity=True): - """ - Computes the value of self on {0,r} or {oo,r} for rational r. + r""" + Compute the value of ``self`` on `\{0,r\}` or `\{\infty, r\}` for + rational `r`. INPUT: - - ``r`` (rational) -- a rational number + - ``r`` -- rational; a rational number - - ``sign`` (int) -- either +1, -1 or 0. If the sign of the - space is +1, only sign +1 is allowed. Default: self.sign, or +1 when self.sign=0. + - ``sign`` -- integer; either +1, -1 or 0. If the sign of the + space is +1, only sign +1 is allowed. Default: ``self.sign``, or +1 + when ``self.sign==0``. - - ``base_at_infinity`` (bool) -- if True, evaluates - {oo,r}. otherwise (default) evaluates {0,r}. + - ``base_at_infinity`` -- boolean; if ``True``, evaluates + `\{\infty, r\}`. Otherwise (default) evaluates `\{0,r\}`. OUTPUT: diff --git a/src/sage/libs/flint/fmpz_poly_sage.pyx b/src/sage/libs/flint/fmpz_poly_sage.pyx index d86d025a3e0..5b8e9276732 100644 --- a/src/sage/libs/flint/fmpz_poly_sage.pyx +++ b/src/sage/libs/flint/fmpz_poly_sage.pyx @@ -111,7 +111,7 @@ cdef class Fmpz_poly(SageObject): def __repr__(self): """ - Print self according to the native FLINT format. + Print ``self`` according to the native FLINT format. EXAMPLES:: @@ -126,7 +126,7 @@ cdef class Fmpz_poly(SageObject): def degree(self): """ - The degree of self. + The degree of ``self``. EXAMPLES:: @@ -144,7 +144,7 @@ cdef class Fmpz_poly(SageObject): def list(self): """ - Return self as a list of coefficients, lowest terms first. + Return ``self`` as a list of coefficients, lowest terms first. EXAMPLES:: @@ -189,7 +189,7 @@ cdef class Fmpz_poly(SageObject): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. EXAMPLES:: @@ -239,7 +239,7 @@ cdef class Fmpz_poly(SageObject): def __pow__(self, n, dummy): """ - Return self raised to the power of n. + Return ``self`` raised to the power of `n`. EXAMPLES:: @@ -267,7 +267,7 @@ cdef class Fmpz_poly(SageObject): def pow_truncate(self, exp, n): """ - Return self raised to the power of exp mod x^n. + Return ``self`` raised to the power of ``exp`` mod `x^n`. EXAMPLES:: @@ -310,7 +310,7 @@ cdef class Fmpz_poly(SageObject): def div_rem(self, Fmpz_poly other): """ - Return self / other, self, % other. + Return ``self / other, self % other``. EXAMPLES:: @@ -338,7 +338,7 @@ cdef class Fmpz_poly(SageObject): def left_shift(self, unsigned long n) : """ - Left shift self by n. + Left shift ``self`` by `n`. EXAMPLES:: @@ -355,7 +355,7 @@ cdef class Fmpz_poly(SageObject): def right_shift(self, unsigned long n) : """ - Right shift self by n. + Right shift ``self`` by `n`. EXAMPLES:: @@ -385,7 +385,7 @@ cdef class Fmpz_poly(SageObject): def derivative(self) : """ - Return the derivative of self. + Return the derivative of ``self``. EXAMPLES:: @@ -407,7 +407,7 @@ cdef class Fmpz_poly(SageObject): def truncate(self, n): """ - Return the truncation of self at degree n. + Return the truncation of ``self`` at degree `n`. EXAMPLES:: @@ -424,7 +424,7 @@ cdef class Fmpz_poly(SageObject): def _unsafe_mutate_truncate(self, n): """ - Return the truncation of self at degree n. + Return the truncation of ``self`` at degree `n`. Don't do this unless you know there are no other references to this polynomial!!!!! @@ -443,7 +443,7 @@ cdef class Fmpz_poly(SageObject): def _sage_(self, var='x'): """ - Return self as an element of the sage ZZ[var]. + Return ``self`` as an element of the sage ``ZZ[var]``. EXAMPLES:: diff --git a/src/sage/libs/flint/nmod_poly_linkage.pxi b/src/sage/libs/flint/nmod_poly_linkage.pxi index f9340b416a8..db9e5d61204 100644 --- a/src/sage/libs/flint/nmod_poly_linkage.pxi +++ b/src/sage/libs/flint/nmod_poly_linkage.pxi @@ -474,13 +474,13 @@ cdef inline int celement_pow(nmod_poly_t res, nmod_poly_t x, long e, nmod_poly_t INPUT: - - ``x`` -- polynomial; the base. + - ``x`` -- polynomial; the base - - ``e`` -- integer; the exponent. + - ``e`` -- integer; the exponent - - ``modulus`` -- polynomial or NULL; if not NULL, then perform a modular exponentiation. + - ``modulus`` -- polynomial or NULL; if not NULL, then perform a modular exponentiation - - ``n`` -- integer; not used, but all polynomials' coefficients are understood modulo ``n``. + - ``n`` -- integer; not used, but all polynomials' coefficients are understood modulo ``n`` EXAMPLES:: diff --git a/src/sage/libs/flint/qsieve_sage.pyx b/src/sage/libs/flint/qsieve_sage.pyx index 93c2ce6b7ed..e172c7cb93e 100644 --- a/src/sage/libs/flint/qsieve_sage.pyx +++ b/src/sage/libs/flint/qsieve_sage.pyx @@ -19,7 +19,7 @@ def qsieve(n): INPUT: - - ``n`` -- an integer; neither prime nor a perfect power. + - ``n`` -- integer; neither prime nor a perfect power OUTPUT: @@ -43,7 +43,6 @@ def qsieve(n): Traceback (most recent call last): ... ArithmeticError: factorization of 0 is not defined - """ n = Integer(n) diff --git a/src/sage/libs/gap/assigned_names.py b/src/sage/libs/gap/assigned_names.py index e8d1f1707cc..216bee639ec 100644 --- a/src/sage/libs/gap/assigned_names.py +++ b/src/sage/libs/gap/assigned_names.py @@ -37,17 +37,15 @@ def load_or_compute(name, function): """ - Helper to load a cached value or compute it + Helper to load a cached value or compute it. INPUT: - - ``name`` -- string. Part of the cache filename + - ``name`` -- string; part of the cache filename - - ``function`` -- function. To compute the value if not cached. + - ``function`` -- function; to compute the value if not cached - OUTPUT: - - The value of ``function``, possibly cached. + OUTPUT: the value of ``function``, possibly cached EXAMPLES:: @@ -72,11 +70,9 @@ def load_or_compute(name, function): def list_keywords(): """ - Return the GAP reserved keywords - - OUTPUT: + Return the GAP reserved keywords. - Tuple of strings. + OUTPUT: tuple of strings EXAMPLES:: @@ -93,11 +89,9 @@ def list_keywords(): def list_globals(): """ - Return the GAP reserved keywords + Return the GAP reserved keywords. - OUTPUT: - - Tuple of strings. + OUTPUT: tuple of strings EXAMPLES:: @@ -118,11 +112,9 @@ def list_globals(): def list_functions(): """ - Return the GAP documented global functions - - OUTPUT: + Return the GAP documented global functions. - Tuple of strings. + OUTPUT: tuple of strings EXAMPLES:: diff --git a/src/sage/libs/gap/context_managers.py b/src/sage/libs/gap/context_managers.py index b42e9c02f4f..539b721af83 100644 --- a/src/sage/libs/gap/context_managers.py +++ b/src/sage/libs/gap/context_managers.py @@ -57,9 +57,9 @@ def __init__(self, variable, value): INPUT: - - ``variable`` -- string. The variable name. + - ``variable`` -- string; the variable name - - ``value`` -- anything that defines a GAP object. + - ``value`` -- anything that defines a GAP object EXAMPLES:: @@ -75,7 +75,7 @@ def __init__(self, variable, value): def __enter__(self): """ - Called when entering the with-block + Called when entering the with-block. EXAMPLES:: @@ -91,7 +91,7 @@ def __enter__(self): def __exit__(self, exc_type, exc_val, exc_tb): """ - Called when exiting the with-block + Called when exiting the with-block. EXAMPLES:: diff --git a/src/sage/libs/gap/element.pyx b/src/sage/libs/gap/element.pyx index 8bf63697d4d..d70e8bad6b2 100644 --- a/src/sage/libs/gap/element.pyx +++ b/src/sage/libs/gap/element.pyx @@ -43,11 +43,9 @@ cdef Obj make_gap_list(sage_list) except NULL: INPUT: - - ``a`` -- list of :class:`GapElement`. + - ``a`` -- list of :class:`GapElement` - OUTPUT: - - The list of the elements in ``a`` as a Gap ``Obj``. + OUTPUT: list of the elements in ``a`` as a Gap ``Obj`` """ cdef Obj l cdef GapElement elem @@ -74,7 +72,7 @@ cdef Obj make_gap_matrix(sage_list, gap_ring) except NULL: INPUT: - - ``sage_list`` -- list of :class:`GapElement`. + - ``sage_list`` -- list of :class:`GapElement` - ``gap_ring`` -- the base ring @@ -188,11 +186,9 @@ cdef Obj make_gap_record(sage_dict) except NULL: INPUT: - - ``a`` -- list of :class:`GapElement`. + - ``a`` -- list of :class:`GapElement` - OUTPUT: - - The list of the elements in ``a`` as a Gap ``Obj``. + OUTPUT: the list of the elements in ``a`` as a Gap ``Obj`` TESTS:: @@ -223,11 +219,9 @@ cdef Obj make_gap_integer(sage_int) except NULL: INPUT: - - ``sage_int`` -- a Sage integer. + - ``sage_int`` -- Sage integer - OUTPUT: - - The integer as a GAP ``Obj``. + OUTPUT: the integer as a GAP ``Obj`` TESTS:: @@ -243,11 +237,9 @@ cdef Obj make_gap_string(sage_string) except NULL: INPUT: - - ``sage_string`` -- a Python str. - - OUTPUT: + - ``sage_string`` -- a Python str - The string as a GAP ``Obj``. + OUTPUT: the string as a GAP ``Obj`` TESTS:: @@ -270,7 +262,7 @@ cdef Obj make_gap_string(sage_string) except NULL: cdef GapElement make_any_gap_element(parent, Obj obj): """ - Return the GAP element wrapper of ``obj`` + Return the GAP element wrapper of ``obj``. The most suitable subclass of GapElement is determined automatically. Use this function to wrap GAP objects unless you @@ -364,7 +356,7 @@ cdef GapElement make_GapElement(parent, Obj obj): - ``parent`` -- the parent of the new :class:`GapElement` - - ``obj`` -- a GAP object. + - ``obj`` -- a GAP object OUTPUT: @@ -416,7 +408,7 @@ cdef class GapElement(RingElement): sage: libgap(0) 0 - If Gap finds an error while evaluating, a :class:`GAPError` + If Gap finds an error while evaluating, a :exc:`GAPError` exception is raised:: sage: libgap.eval('1/0') @@ -424,7 +416,7 @@ cdef class GapElement(RingElement): ... GAPError: Error, Rational operations: must not be zero - Also, a ``GAPError`` is raised if the input is not a simple expression:: + Also, a :exc:`GAPError` is raised if the input is not a simple expression:: sage: libgap.eval('1; 2; 3') Traceback (most recent call last): @@ -446,7 +438,7 @@ cdef class GapElement(RingElement): def __init__(self): """ - The ``GapElement`` constructor + The ``GapElement`` constructor. Users must use the ``libgap`` instance to construct instances of :class:`GapElement`. Cython programmers must use @@ -493,7 +485,7 @@ cdef class GapElement(RingElement): def __dealloc__(self): r""" - The Cython destructor + The Cython destructor. TESTS:: @@ -548,14 +540,14 @@ cdef class GapElement(RingElement): cpdef GapElement deepcopy(self, bint mut): r""" - Return a deepcopy of this Gap object + Return a deepcopy of this Gap object. Note that this is the same thing as calling ``StructuralCopy`` but much faster. INPUT: - - ``mut`` -- (boolean) whether to return a mutable copy + - ``mut`` -- boolean; whether to return a mutable copy EXAMPLES:: @@ -655,9 +647,7 @@ cdef class GapElement(RingElement): This is only useful for libgap development purposes. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -671,7 +661,7 @@ cdef class GapElement(RingElement): def __dir__(self): """ - Customize tab completion + Customize tab completion. EXAMPLES:: @@ -780,7 +770,7 @@ cdef class GapElement(RingElement): cpdef _set_compare_by_id(self): """ - Set comparison to compare by ``id`` + Set comparison to compare by ``id``. By default, GAP is used to compare GAP objects. However, this is not defined for all GAP objects. To have GAP play @@ -818,13 +808,13 @@ cdef class GapElement(RingElement): cpdef _assert_compare_by_id(self): """ - Ensure that comparison is by ``id`` + Ensure that comparison is by ``id``. See :meth:`_set_compare_by_id`. OUTPUT: - This method returns nothing. A ``ValueError`` is raised if + This method returns nothing. A :exc:`ValueError` is raised if :meth:`_set_compare_by_id` has not been called on this libgap object. @@ -863,7 +853,7 @@ cdef class GapElement(RingElement): OUTPUT: Boolean, depending on the comparison of ``self`` and - ``other``. Raises a ``ValueError`` if GAP does not support + ``other``. Raises a :exc:`ValueError` if GAP does not support comparison of ``self`` and ``other``, unless :meth:`_set_compare_by_id` was called on both ``self`` and ``other``. @@ -882,7 +872,7 @@ cdef class GapElement(RingElement): True GAP does not have a comparison function for two ``FreeGroup`` - objects. LibGAP signals this by raising a ``ValueError`` :: + objects. LibGAP signals this by raising a :exc:`ValueError` :: sage: F1 = libgap.FreeGroup(['a']) sage: F2 = libgap.FreeGroup(['a']) @@ -1184,9 +1174,7 @@ cdef class GapElement(RingElement): """ Return whether the wrapped GAP object is a function. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1203,9 +1191,7 @@ cdef class GapElement(RingElement): r""" Return whether the wrapped GAP object is a GAP List. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1220,9 +1206,7 @@ cdef class GapElement(RingElement): r""" Return whether the wrapped GAP object is a GAP record. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1237,9 +1221,7 @@ cdef class GapElement(RingElement): r""" Return whether the wrapped GAP object is a GAP boolean. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1255,9 +1237,7 @@ cdef class GapElement(RingElement): r""" Return whether the wrapped GAP object is a GAP string. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1270,9 +1250,7 @@ cdef class GapElement(RingElement): r""" Return whether the wrapped GAP object is a GAP permutation. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1288,7 +1266,7 @@ cdef class GapElement(RingElement): def sage(self): r""" - Return the Sage equivalent of the :class:`GapElement` + Return the Sage equivalent of the :class:`GapElement`. EXAMPLES:: @@ -1404,7 +1382,7 @@ cdef class GapElement(RingElement): cdef GapElement_Integer make_GapElement_Integer(parent, Obj obj): r""" - Turn a Gap integer object into a GapElement_Integer Sage object + Turn a Gap integer object into a GapElement_Integer Sage object. EXAMPLES:: @@ -1439,9 +1417,7 @@ cdef class GapElement_Integer(GapElement): is subject to the usual size limits. Larger integers are stored in GAP as GMP integers. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1476,14 +1452,12 @@ cdef class GapElement_Integer(GapElement): def sage(self, ring=None): r""" - Return the Sage equivalent of the :class:`GapElement_Integer` + Return the Sage equivalent of the :class:`GapElement_Integer`. - - ``ring`` -- Integer ring or ``None`` (default). If not - specified, the default Sage integer ring is used. + - ``ring`` -- integer ring or ``None`` (default); if not + specified, the default Sage integer ring is used - OUTPUT: - - A Sage integer + OUTPUT: a Sage integer EXAMPLES:: @@ -1574,7 +1548,7 @@ cdef class GapElement_Integer(GapElement): cdef GapElement_Float make_GapElement_Float(parent, Obj obj): r""" - Turn a Gap macfloat object into a GapElement_Float Sage object + Turn a Gap macfloat object into a GapElement_Float Sage object. EXAMPLES:: @@ -1609,14 +1583,12 @@ cdef class GapElement_Float(GapElement): """ def sage(self, ring=None): r""" - Return the Sage equivalent of the :class:`GapElement_Float` + Return the Sage equivalent of the :class:`GapElement_Float`. - - ``ring`` -- a floating point field or ``None`` (default). If not - specified, the default Sage ``RDF`` is used. - - OUTPUT: + - ``ring`` -- a floating point field or ``None`` (default); if not + specified, the default Sage ``RDF`` is used - A Sage double precision floating point number + OUTPUT: a Sage double precision floating point number EXAMPLES:: @@ -1646,7 +1618,7 @@ cdef class GapElement_Float(GapElement): cdef GapElement_IntegerMod make_GapElement_IntegerMod(parent, Obj obj): r""" - Turn a Gap integer object into a :class:`GapElement_IntegerMod` Sage object + Turn a Gap integer object into a :class:`GapElement_IntegerMod` Sage object. EXAMPLES:: @@ -1693,17 +1665,15 @@ cdef class GapElement_IntegerMod(GapElement): def sage(self, ring=None): r""" - Return the Sage equivalent of the :class:`GapElement_IntegerMod` + Return the Sage equivalent of the :class:`GapElement_IntegerMod`. INPUT: - - ``ring`` -- Sage integer mod ring or ``None`` (default). If + - ``ring`` -- Sage integer mod ring or ``None`` (default); if not specified, a suitable integer mod ring is used - automatically. + automatically - OUTPUT: - - A Sage integer modulo another integer. + OUTPUT: a Sage integer modulo another integer EXAMPLES:: @@ -1739,7 +1709,7 @@ cdef class GapElement_IntegerMod(GapElement): cdef GapElement_FiniteField make_GapElement_FiniteField(parent, Obj obj): r""" - Turn a GAP finite field object into a :class:`GapElement_FiniteField` Sage object + Turn a GAP finite field object into a :class:`GapElement_FiniteField` Sage object. EXAMPLES:: @@ -1941,12 +1911,10 @@ cdef class GapElement_Cyclotomic(GapElement): INPUT: - ``ring`` -- a Sage cyclotomic field or ``None`` - (default). If not specified, a suitable minimal cyclotomic - field will be constructed. - - OUTPUT: + (default); if not specified, a suitable minimal cyclotomic + field will be constructed - A Sage cyclotomic field element. + OUTPUT: a Sage cyclotomic field element EXAMPLES:: @@ -2037,12 +2005,10 @@ cdef class GapElement_Rational(GapElement): INPUT: - - ``ring`` -- the Sage rational ring or ``None`` (default). If - not specified, the rational ring is used automatically. + - ``ring`` -- the Sage rational ring or ``None`` (default); if + not specified, the rational ring is used automatically - OUTPUT: - - A Sage rational number. + OUTPUT: a Sage rational number EXAMPLES:: @@ -2180,11 +2146,9 @@ cdef class GapElement_Ring(GapElement): INPUT: - ``**kwds`` -- keywords that are passed on to the ``ring_`` - method. - - OUTPUT: + method - A Sage ring. + OUTPUT: a Sage ring EXAMPLES:: @@ -2256,13 +2220,13 @@ cdef class GapElement_Boolean(GapElement): def sage(self): r""" - Return the Sage equivalent of the :class:`GapElement` + Return the Sage equivalent of the :class:`GapElement`. OUTPUT: A Python boolean if the values is either true or false. GAP booleans can have the third value ``Fail``, in which case a - ``ValueError`` is raised. + :exc:`ValueError` is raised. EXAMPLES:: @@ -2294,9 +2258,7 @@ cdef class GapElement_Boolean(GapElement): This is syntactic sugar for using libgap. See the examples below. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -2353,9 +2315,7 @@ cdef class GapElement_String(GapElement): r""" Convert this :class:`GapElement_String` to a Python string. - OUTPUT: - - A Python string. + OUTPUT: a Python string EXAMPLES:: @@ -2387,11 +2347,9 @@ cdef GapElement_Function make_GapElement_Function(parent, Obj obj): - ``parent`` -- the parent of the new :class:`GapElement` - - ``obj`` -- a GAP function object. - - OUTPUT: + - ``obj`` -- a GAP function object - A :class:`GapElement_Function` instance. + OUTPUT: a :class:`GapElement_Function` instance EXAMPLES:: @@ -2418,11 +2376,9 @@ cdef class GapElement_Function(GapElement): def __repr__(self): r""" - Return a string representation - - OUTPUT: + Return a string representation. - String. + OUTPUT: string EXAMPLES:: @@ -2441,7 +2397,7 @@ cdef class GapElement_Function(GapElement): INPUT: - ``*args`` -- arguments. Will be converted to `GapElement` if - they are not already of this type. + they are not already of this type OUTPUT: @@ -2566,7 +2522,7 @@ cdef class GapElement_Function(GapElement): def _instancedoc_(self): r""" - Return the help string + Return the help string. EXAMPLES:: @@ -2597,13 +2553,11 @@ cdef GapElement_MethodProxy make_GapElement_MethodProxy(parent, Obj function, Ga - ``parent`` -- the parent of the new :class:`GapElement` - - ``obj`` -- a GAP function object. - - - ``base_object`` -- The first argument to be inserted into the function. + - ``obj`` -- a GAP function object - OUTPUT: + - ``base_object`` -- the first argument to be inserted into the function - A :class:`GapElement_MethodProxy` instance. + OUTPUT: a :class:`GapElement_MethodProxy` instance EXAMPLES:: @@ -2649,7 +2603,7 @@ cdef class GapElement_MethodProxy(GapElement_Function): INPUT: - ``*args`` -- arguments. Will be converted to `GapElement` if - they are not already of this type. + they are not already of this type OUTPUT: @@ -2728,7 +2682,7 @@ cdef class GapElement_List(GapElement): def __bool__(self): r""" - Return True if the list is non-empty, as with Python ``list``s. + Return ``True`` if the list is non-empty, as with Python ``list``s. EXAMPLES:: @@ -2745,9 +2699,7 @@ cdef class GapElement_List(GapElement): r""" Return the length of the list. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -2766,7 +2718,7 @@ cdef class GapElement_List(GapElement): INPUT: - - ``i`` -- integer. + - ``i`` -- integer OUTPUT: @@ -2819,7 +2771,7 @@ cdef class GapElement_List(GapElement): def __setitem__(self, i, elt): r""" - Set the ``i``-th item of this list + Set the `i`-th item of this list. EXAMPLES:: @@ -2898,11 +2850,9 @@ cdef class GapElement_List(GapElement): def sage(self, **kwds): r""" - Return the Sage equivalent of the :class:`GapElement` - - OUTPUT: + Return the Sage equivalent of the :class:`GapElement`. - A Python list. + OUTPUT: a Python list EXAMPLES:: @@ -2921,9 +2871,7 @@ cdef class GapElement_List(GapElement): lists of lists. This function converts a GAP list of lists to a Sage matrix. - OUTPUT: - - A Sage matrix. + OUTPUT: a Sage matrix EXAMPLES:: @@ -2974,9 +2922,7 @@ cdef class GapElement_List(GapElement): GAP does not have a special vector data type, they are just lists. This function converts a GAP list to a Sage vector. - OUTPUT: - - A Sage vector. + OUTPUT: a Sage vector EXAMPLES:: @@ -3043,7 +2989,7 @@ cdef class GapElement_Permutation(GapElement): def sage(self, parent=None): r""" - Return the Sage equivalent of the :class:`GapElement` + Return the Sage equivalent of the :class:`GapElement`. If the permutation group is given as parent, this method is *much* faster. @@ -3124,9 +3070,7 @@ cdef class GapElement_Record(GapElement): r""" Return the length of the record. - OUTPUT: - - Integer. The number of entries in the record. + OUTPUT: integer; the number of entries in the record EXAMPLES:: @@ -3140,9 +3084,7 @@ cdef class GapElement_Record(GapElement): r""" Iterate over the elements of the record. - OUTPUT: - - A :class:`GapElement_RecordIterator`. + OUTPUT: a :class:`GapElement_RecordIterator` EXAMPLES:: @@ -3161,7 +3103,7 @@ cdef class GapElement_Record(GapElement): INPUT: - - ``py_name`` -- a python string. + - ``py_name`` -- a python string OUTPUT: @@ -3186,11 +3128,9 @@ cdef class GapElement_Record(GapElement): INPUT: - - ``name`` -- string. - - OUTPUT: + - ``name`` -- string - The record element labelled by ``name`` as a :class:`GapElement`. + OUTPUT: the record element labelled by ``name`` as a :class:`GapElement` EXAMPLES:: @@ -3211,7 +3151,7 @@ cdef class GapElement_Record(GapElement): def sage(self): r""" - Return the Sage equivalent of the :class:`GapElement` + Return the Sage equivalent of the :class:`GapElement`. EXAMPLES:: @@ -3238,14 +3178,14 @@ cdef class GapElement_Record(GapElement): cdef class GapElement_RecordIterator(): r""" - Iterator for :class:`GapElement_Record` + Iterator for :class:`GapElement_Record`. Since Cython does not support generators yet, we implement the older iterator specification with this auxiliary class. INPUT: - - ``rec`` -- the :class:`GapElement_Record` to iterate over. + - ``rec`` -- the :class:`GapElement_Record` to iterate over EXAMPLES:: @@ -3262,7 +3202,7 @@ cdef class GapElement_RecordIterator(): INPUT: - - ``rec`` -- the :class:`GapElement_Record` to iterate over. + - ``rec`` -- the :class:`GapElement_Record` to iterate over EXAMPLES:: diff --git a/src/sage/libs/gap/libgap.pyx b/src/sage/libs/gap/libgap.pyx index 328a5096160..f5b58a929f3 100644 --- a/src/sage/libs/gap/libgap.pyx +++ b/src/sage/libs/gap/libgap.pyx @@ -72,7 +72,7 @@ corresponding Sage datatype: #. GAP booleans ``true`` / ``false`` to Sage booleans ``True`` / ``False``. The third GAP boolean value ``fail`` raises a - ``ValueError``. + :exc:`ValueError`. #. GAP integers to Sage integers. @@ -134,7 +134,7 @@ convert the entries into Sage objects, you should use the Now ``rec['a']`` is a Sage integer. We have not implemented the conversion of the GAP symmetric group to the Sage symmetric group yet, -so you end up with a ``NotImplementedError`` exception object. The +so you end up with a :exc:`NotImplementedError` exception object. The exception is returned and not raised so that you can work with the partial result. @@ -257,9 +257,7 @@ class Gap(Parent): """ Whether a coercion from `S` exists. - INPUT / OUTPUT: - - See :mod:`sage.structure.parent`. + INPUT / OUTPUT: see :mod:`sage.structure.parent` EXAMPLES:: @@ -276,11 +274,9 @@ class Gap(Parent): INPUT: - - ``x`` -- anything that defines a GAP object. - - OUTPUT: + - ``x`` -- anything that defines a GAP object - A :class:`GapElement`. + OUTPUT: a :class:`GapElement` EXAMPLES:: @@ -296,7 +292,6 @@ class Gap(Parent): [ 1/3, 2/3, 4/5 ] sage: libgap(vector((1/3, 0.8, 3))) [ 0.333333, 0.8, 3. ] - """ initialize() if isinstance(x, GapElement): @@ -328,7 +323,7 @@ class Gap(Parent): INPUT: - - ``M`` -- a matrix. + - ``M`` -- a matrix OUTPUT: @@ -362,7 +357,7 @@ class Gap(Parent): We gracefully handle the case that the conversion fails (:issue:`18039`):: - sage: F. = GF(9, modulus="first_lexicographic") # needs sage.rings.finite_rings + sage: F. = GF(9, modulus='first_lexicographic') # needs sage.rings.finite_rings sage: libgap(Matrix(F, [[a]])) # needs sage.rings.finite_rings Traceback (most recent call last): ... @@ -383,12 +378,10 @@ class Gap(Parent): INPUT: - - ``gap_command`` -- a string containing a valid gap command - without the trailing semicolon. + - ``gap_command`` -- string containing a valid gap command + without the trailing semicolon - OUTPUT: - - A :class:`GapElement`. + OUTPUT: a :class:`GapElement` EXAMPLES:: @@ -413,7 +406,7 @@ class Gap(Parent): def load_package(self, pkg): """ - If loading fails, raise a :class:`RuntimeError` exception. + If loading fails, raise a :exc:`RuntimeError` exception. TESTS:: @@ -438,7 +431,7 @@ class Gap(Parent): @cached_method def function_factory(self, function_name): """ - Return a GAP function wrapper + Return a GAP function wrapper. This is almost the same as calling ``libgap.eval(function_name)``, but faster and makes it @@ -446,7 +439,7 @@ class Gap(Parent): INPUT: - - ``function_name`` -- string. The name of a GAP function. + - ``function_name`` -- string; the name of a GAP function OUTPUT: @@ -465,13 +458,13 @@ class Gap(Parent): def set_global(self, variable, value): """ - Set a GAP global variable + Set a GAP global variable. INPUT: - - ``variable`` -- string. The variable name. + - ``variable`` -- string; the variable name - - ``value`` -- anything that defines a GAP object. + - ``value`` -- anything that defines a GAP object EXAMPLES:: @@ -490,11 +483,11 @@ class Gap(Parent): def unset_global(self, variable): """ - Remove a GAP global variable + Remove a GAP global variable. INPUT: - - ``variable`` -- string. The variable name. + - ``variable`` -- string; the variable name EXAMPLES:: @@ -514,16 +507,16 @@ class Gap(Parent): def get_global(self, variable): """ - Get a GAP global variable + Get a GAP global variable. INPUT: - - ``variable`` -- string. The variable name. + - ``variable`` -- string; the variable name OUTPUT: A :class:`~sage.libs.gap.element.GapElement` wrapping the GAP - output. A ``ValueError`` is raised if there is no such + output. A :exc:`ValueError` is raised if there is no such variable in GAP. EXAMPLES:: @@ -539,17 +532,15 @@ class Gap(Parent): def global_context(self, variable, value): """ - Temporarily change a global variable + Temporarily change a global variable. INPUT: - - ``variable`` -- string. The variable name. + - ``variable`` -- string; the variable name - - ``value`` -- anything that defines a GAP object. - - OUTPUT: + - ``value`` -- anything that defines a GAP object - A context manager that sets/reverts the given global variable. + OUTPUT: a context manager that sets/reverts the given global variable EXAMPLES:: @@ -590,9 +581,7 @@ class Gap(Parent): r""" Return a :class:`GapElement`. - OUTPUT: - - A :class:`GapElement`. + OUTPUT: a :class:`GapElement` EXAMPLES:: @@ -605,9 +594,7 @@ class Gap(Parent): """ Return (integer) zero in GAP. - OUTPUT: - - A :class:`GapElement`. + OUTPUT: a :class:`GapElement` EXAMPLES:: @@ -646,9 +633,7 @@ class Gap(Parent): r""" Return a string representation of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -660,7 +645,7 @@ class Gap(Parent): @cached_method def __dir__(self): """ - Customize tab completion + Customize tab completion. EXAMPLES:: @@ -677,12 +662,12 @@ class Gap(Parent): INPUT: - - ``name`` -- string. The name of the GAP function you want to - call. + - ``name`` -- string; the name of the GAP function you want to + call OUTPUT: - A :class:`GapElement`. A ``AttributeError`` is raised + A :class:`GapElement`. A :exc:`AttributeError` is raised if there is no such function or global variable. EXAMPLES:: @@ -705,7 +690,7 @@ class Gap(Parent): def show(self): """ - Return statistics about the GAP owned object list + Return statistics about the GAP owned object list. This includes the total memory allocated by GAP as returned by ``libgap.eval('TotalMemoryAllocated()'), as well as garbage collection @@ -718,7 +703,7 @@ class Gap(Parent): allocated for GAP objects (see ``libgap.eval('TotalMemoryAllocated()')``). - .. note:: + .. NOTE:: Slight complication is that we want to do it without accessing libgap objects, so we don't create new GapElements as a side @@ -755,9 +740,7 @@ class Gap(Parent): Return the number of GAP objects that are being tracked by GAP. - OUTPUT: - - An integer + OUTPUT: integer EXAMPLES:: @@ -768,7 +751,7 @@ class Gap(Parent): def collect(self): """ - Manually run the garbage collector + Manually run the garbage collector. EXAMPLES:: diff --git a/src/sage/libs/gap/operations.py b/src/sage/libs/gap/operations.py index 434d1a01511..b2106583f0b 100644 --- a/src/sage/libs/gap/operations.py +++ b/src/sage/libs/gap/operations.py @@ -31,11 +31,11 @@ class OperationInspector(SageObject): def __init__(self, libgap_element): """ - Information about operations that can act on a given LibGAP element + Information about operations that can act on a given LibGAP element. INPUT: - - ``libgap_element`` -- libgap element. + - ``libgap_element`` -- libgap element EXAMPLES:: @@ -48,11 +48,9 @@ def __init__(self, libgap_element): def _repr_(self): """ - Return the string representation + Return the string representation. - OUTPUT: - - String + OUTPUT: string EXAMPLES:: @@ -66,11 +64,9 @@ def _repr_(self): @property def obj(self): """ - The first argument for the operations - - OUTPUT: + The first argument for the operations. - A Libgap object. + OUTPUT: a Libgap object EXAMPLES:: @@ -83,11 +79,9 @@ def obj(self): def operations(self): """ - Return the GAP operations for :meth:`obj` + Return the GAP operations for :meth:`obj`. - OUTPUT: - - List of GAP operations + OUTPUT: list of GAP operations EXAMPLES:: @@ -106,11 +100,9 @@ def mfi(o): def op_names(self): """ - Return the names of the operations - - OUTPUT: + Return the names of the operations. - List of strings + OUTPUT: list of strings EXAMPLES:: diff --git a/src/sage/libs/gap/saved_workspace.py b/src/sage/libs/gap/saved_workspace.py index fdaf18f4644..c26993ac638 100644 --- a/src/sage/libs/gap/saved_workspace.py +++ b/src/sage/libs/gap/saved_workspace.py @@ -14,7 +14,7 @@ def timestamp(): """ - Return a time stamp for (lib)gap + Return a time stamp for (lib)gap. OUTPUT: @@ -51,8 +51,8 @@ def workspace(name='workspace'): INPUT: - - ``name`` -- string. A name that will become part of the - workspace filename. + - ``name`` -- string; a name that will become part of the + workspace filename OUTPUT: diff --git a/src/sage/libs/gap/test.py b/src/sage/libs/gap/test.py index eee697218ee..72daa93acb6 100644 --- a/src/sage/libs/gap/test.py +++ b/src/sage/libs/gap/test.py @@ -8,7 +8,7 @@ def test_write_to_file(): """ - Test that libgap can write to files + Test that libgap can write to files. See :issue:`16502`, :issue:`15833`. diff --git a/src/sage/libs/gap/util.pyx b/src/sage/libs/gap/util.pyx index 3e75d71ff06..e585431cda9 100644 --- a/src/sage/libs/gap/util.pyx +++ b/src/sage/libs/gap/util.pyx @@ -38,7 +38,7 @@ from sage.interfaces.gap_workspace import prepare_workspace_dir cdef class ObjWrapper(): """ - Wrapper for GAP master pointers + Wrapper for GAP master pointers. EXAMPLES:: @@ -55,13 +55,11 @@ cdef class ObjWrapper(): INPUT: - - ``lhs``, ``rhs`` -- :class:`ObjWrapper`. + - ``lhs``, ``rhs`` -- :class:`ObjWrapper` - - ``op`` -- integer. The comparison operation to be performed. + - ``op`` -- integer; the comparison operation to be performed - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -91,7 +89,7 @@ cdef class ObjWrapper(): def __hash__(self): """ - Return a hash value + Return a hash value. EXAMPLES:: @@ -297,7 +295,7 @@ cdef Obj gap_eval(str gap_string) except? NULL: INPUT: - - ``gap_string`` -- string. A valid statement in GAP. + - ``gap_string`` -- string; a valid statement in GAP OUTPUT: @@ -433,7 +431,7 @@ cdef void error_handler() noexcept with gil: """ The libgap error handler. - If an error occurred, we raise a ``GAPError``; when the original + If an error occurred, we raise a :exc:`GAPError`; when the original ``GAP_EvalString`` returns, this exception will be seen. TODO: We should probably prevent re-entering this function if we diff --git a/src/sage/libs/giac/__init__.py b/src/sage/libs/giac/__init__.py index 874cfe4e54f..208fc9af930 100644 --- a/src/sage/libs/giac/__init__.py +++ b/src/sage/libs/giac/__init__.py @@ -57,7 +57,6 @@ def __enter__(self): sage: with GiacSettingsDefaultContext(): giacsettings.proba_epsilon = 1e-12 sage: giacsettings.proba_epsilon < 1e-14 True - """ self.proba_epsilon = giacsettings.proba_epsilon self.threads = giacsettings.threads @@ -74,7 +73,6 @@ def __exit__(self, typ, value, tb): sage: with GiacSettingsDefaultContext(): giacsettings.proba_epsilon = 1e-30 sage: giacsettings.proba_epsilon < 1e-20 False - """ # Restore the debug level first to not have messages at each modification libgiac('debug_infolevel')(self.debuginfolevel) @@ -104,7 +102,6 @@ def local_giacsettings(func): True sage: gp0, Gamma(a)=int(e^{-t}*t^{a-1},t=0..inf)) and Gamma(a)=Gamma(a+1)/a and Gamma(a,b)=ugamma(a,b). - See also: 1/ Psi 2/ Beta 3/ ugamma 4/ igamma + See also: 1/ Psi 2/ Beta 3/ ugamma 4/ igamma Ex1:Gamma(5) Ex2:Gamma(1/2) Ex3:Gamma(gamma(-5.1)) Ex4:Gamma(-5.1,2.1) - ''' return GiacMethods['Gamma'](self,*args) @@ -210,11 +194,10 @@ cdef class GiacMethods_base: Help for Heaviside: Heaviside(Real) Function equal to 0 if x<0 and 1 if x>=0. - See also: 1/ Dirac 2/ laplace + See also: 1/ Dirac 2/ laplace Ex1:Heaviside(1) Ex2:Heaviside(-1) Ex3:Heaviside(0) - ''' return GiacMethods['Heaviside'](self,*args) @@ -223,9 +206,8 @@ cdef class GiacMethods_base: Help for JordanBlock: JordanBlock(Expr(a),Intg(n)) Returns an n*n matrix with a on the diagonal, 1 above and 0 everywhere else. - See also: 1/ jordan + See also: 1/ jordan Ex1:JordanBlock(7,3) - ''' return GiacMethods['JordanBlock'](self,*args) @@ -234,10 +216,9 @@ cdef class GiacMethods_base: Help for LU: LU(Mtrx(A),Var(L),Var(U),Var(P)) For a numerical matrix A, stores in L a lower triangular matrix, in U an upper triangular matrix and in P a permutation matrix such that P*A=L*U. - See also: 1/ lu 2/ QR + See also: 1/ lu 2/ QR Ex1:LU([[1,2],[3,4]],L,U,P) Ex2:LU([[6,12,18],[5,14,31],[3,8,18]],L,U,P) - ''' return GiacMethods['LU'](self,*args) @@ -249,7 +230,6 @@ cdef class GiacMethods_base: Ex1:LambertW(1.0) Ex2:LambertW(ln(4)) Ex3:LambertW(-0.1,-1) - ''' return GiacMethods['LambertW'](self,*args) @@ -258,9 +238,8 @@ cdef class GiacMethods_base: Help for Li: Li(Expr) Logarithm integral Li(x)=Ei(ln(x)) primitive of 1/ln(x). - See also: 1/ Si 2/ Ci 3/ Ei + See also: 1/ Si 2/ Ci 3/ Ei Ex1:Li(2.0) - ''' return GiacMethods['Li'](self,*args) @@ -269,9 +248,8 @@ cdef class GiacMethods_base: Help for Line: Line(Expr(a),Expr(b),Expr(c),Expr(d)) Draws the segment [a+i*b,c+i*d]. - See also: 1/ segment + See also: 1/ segment Ex1:Line(-1,-2,1,2) - ''' return GiacMethods['Line'](self,*args) @@ -280,9 +258,8 @@ cdef class GiacMethods_base: Help for LineHorz: LineHorz(Expr(a)) Draws the horizontal line y=a. - See also: 1/ Line 2/ LineVert + See also: 1/ Line 2/ LineVert Ex1:LineHorz(-1) - ''' return GiacMethods['LineHorz'](self,*args) @@ -291,13 +268,12 @@ cdef class GiacMethods_base: Help for LineTan: LineTan(Expr(f(x)),[Var],Expr(a)) Draws the tangent to y=f(x) at x=a. Do not use parentheses or put the parenthesis around the entire expression. - See also: 1/ tangent 2/ droite_tangente + See also: 1/ tangent 2/ droite_tangente Ex1: LineTan sin(x),pi/4 Ex2: LineTan sin(t),t=pi/4) Ex3: LineTan sin(t),t,pi/4 Ex4: LineTan x^2-x,1 Ex5: (LineTan sin(t),t,pi/4) - ''' return GiacMethods['LineTan'](self,*args) @@ -306,9 +282,8 @@ cdef class GiacMethods_base: Help for LineVert: LineVert(Expr(a)) Draws the vertical line x=a. - See also: 1/ Line 2/ LineHorz + See also: 1/ Line 2/ LineHorz Ex1:LineVert(2) - ''' return GiacMethods['LineVert'](self,*args) @@ -317,10 +292,9 @@ cdef class GiacMethods_base: Help for Phi: Phi(Intg(n)) Euler's function (euler(n)=card({p1 sum(1/n^a,n,1,+infinity). - See also: 1/ sum + See also: 1/ sum Ex1:Zeta(2) - ''' return GiacMethods['Zeta'](self,*args) @@ -507,10 +466,9 @@ cdef class GiacMethods_base: Help for a2q: a2q(Mtrx,VectVar) a2q(A,X)=the quadratic form q associated to A, X=vector of variables. - See also: 1/ q2a + See also: 1/ q2a Ex1:a2q([[1,2],[4,4]],[x,y]) Ex2:a2q([[1,3],[3,4]],[x,y]) - ''' return GiacMethods['a2q'](self,*args) @@ -519,13 +477,12 @@ cdef class GiacMethods_base: Help for abcuv: abcuv(Poly(a),Poly(b),Poly(c),[Var]) Returns [u,v] such that au+bv=c for 3 polynomials a,b,c. - See also: 1/ egcd 2/ iabcuv + See also: 1/ egcd 2/ iabcuv Ex1:abcuv(x^2+2*x+1,x^2-1,x+1) Ex2:abcuv(X^2+2*X+1,X^2-1,X+1,X) Ex3:abcuv(x^2+2*x+1,x^2-1,x^3+1) Ex4:abcuv(X^2+2*X+1,X^2-1,X^3+1,X) Ex5:abcuv([1,2,1],[1,0,-1],[1,0,0,1]) - ''' return GiacMethods['abcuv'](self,*args) @@ -534,10 +491,9 @@ cdef class GiacMethods_base: Help for about: about(Var(a)) Returns the hypothesis made with assume on the variable a. - See also: 1/ assume 2/ purge + See also: 1/ assume 2/ purge Ex1:about(a) Ex2:about(n) - ''' return GiacMethods['about'](self,*args) @@ -546,12 +502,11 @@ cdef class GiacMethods_base: Help for abs: abs(Cplx||LstCplx) Returns the absolute value or the norm of its argument. - See also: 1/ arg + See also: 1/ arg Ex1:abs(-4) Ex2:abs(1+2*i) Ex3:abs((1+2*i)^2) Ex4:abs([-2,1+i,-4]) - ''' return GiacMethods['abs'](self,*args) @@ -560,12 +515,11 @@ cdef class GiacMethods_base: Help for abscissa: abscissa(Pnt or Vect) Returns the abscissa of a point or a vector. - See also: 1/ ordinate 2/ affix 3/ cote 4/ coordinates + See also: 1/ ordinate 2/ affix 3/ cote 4/ coordinates Ex1:abscissa(point(1+2*i)) Ex2:abscissa(point(i)-point(1+2*i)) Ex3:abscissa(-1-i) Ex4:abscissa(point(1,2,3)) - ''' return GiacMethods['abscissa'](self,*args) @@ -574,9 +528,8 @@ cdef class GiacMethods_base: Help for accumulate_head_tail: accumulate_head_tail(Lst(l),Intg(p),Intg(q)) Returns the list where the first p and the last q elements of l are replaced by their sum. - See also: 1/ + See also: 1/ Ex1:accumulate_head_tail([0,1,2,3,4,5,6,7,8,9],3,2) - ''' return GiacMethods['accumulate_head_tail'](self,*args) @@ -585,9 +538,8 @@ cdef class GiacMethods_base: Help for acos: acos(Expr) Arccosine. - See also: 1/ cos 2/ acosh + See also: 1/ cos 2/ acosh Ex1:acos(0) - ''' return GiacMethods['acos'](self,*args) @@ -596,10 +548,9 @@ cdef class GiacMethods_base: Help for acos2asin: acos2asin(Expr) Replaces arccos(x) by pi/2-arcsin(x) in the argument. - See also: 1/ acos2atan + See also: 1/ acos2atan Ex1:acos2asin(acos(x)+asin(x)) Ex2:acos2asin(2*acos(x)) - ''' return GiacMethods['acos2asin'](self,*args) @@ -608,10 +559,9 @@ cdef class GiacMethods_base: Help for acos2atan: acos2atan(Expr) Replaces arccos(x) by pi/2-arctan(x/sqrt(1-x^2)) in the argument. - See also: 1/ acos2asin + See also: 1/ acos2asin Ex1:acos2atan(2*acos(x)) Ex2:acos2atan(acos(sqrt(1-x^2))+acos(x)) - ''' return GiacMethods['acos2atan'](self,*args) @@ -620,9 +570,8 @@ cdef class GiacMethods_base: Help for acosh: acosh(Expr) Hyperbolic arccosine. - See also: 1/ cosh 2/ acos + See also: 1/ cosh 2/ acos Ex1:acosh(1) - ''' return GiacMethods['acosh'](self,*args) @@ -631,9 +580,8 @@ cdef class GiacMethods_base: Help for acot: acot(Expr) Arccotangent. - See also: 1/ atan 2/ arccos + See also: 1/ atan 2/ arccos Ex1:acot(0) - ''' return GiacMethods['acot'](self,*args) @@ -642,10 +590,9 @@ cdef class GiacMethods_base: Help for acsc: acsc(Expr) Arccosecant: acsc(x)=asin(1/x). - See also: 1/ asin 2/ csc + See also: 1/ asin 2/ csc Ex1:acsc(1) Ex2:acsc(2) - ''' return GiacMethods['acsc'](self,*args) @@ -654,8 +601,7 @@ cdef class GiacMethods_base: Help for acyclic: acyclic(Opt) Option for the random_network command. - See also: 1/ random_network - + See also: 1/ random_network ''' return GiacMethods['acyclic'](self,*args) @@ -664,7 +610,7 @@ cdef class GiacMethods_base: Help for add: add(Expr,Var,VarMin(a),VarMax(b),[VarStep(p)]) Discrete sum (with 2 or 4 arguments return then sum from a to b if a<=b or of the opposite of the sum from b+1 to a-1 if a>b+1 or 0 if a=b+1) or the discrete primitive or sum of the elements of a list or a sequence. - See also: 1/ + + See also: 1/ + Ex1:add(1/n^2,n,1,17) Ex2:add(1/n^2,n=1..17) Ex3:add(1/n^2,n,17,1) @@ -675,7 +621,6 @@ cdef class GiacMethods_base: Ex8:add([[1,2,3,4,5,6,7,8,9],[1,2,3,4,5,6,7,8,9]]) Ex9:add(1/(x*(x+1)),x) Ex10:add(cos(n*x),n) - ''' return GiacMethods['add'](self,*args) @@ -684,9 +629,8 @@ cdef class GiacMethods_base: Help for add_arc: add_arc(Graph(G),Edge(e)||Trail(T)||Lst(E)) Returns a modified copy of digraph G with added arc e (or trail T or list of arcs E). - See also: 1/ add_edge 2/ delete_arc 3/ digraph 4/ edges 5/ has_arc 6/ trail + See also: 1/ add_edge 2/ delete_arc 3/ digraph 4/ edges 5/ has_arc 6/ trail Ex1:add_arc(digraph(trail(1,2,3,4,5,1)),[[1,3],[2,4]]) - ''' return GiacMethods['add_arc'](self,*args) @@ -695,9 +639,8 @@ cdef class GiacMethods_base: Help for add_edge: add_edge(Graph(G),Edge(e)||Trail(T)||Lst(E)) Returns a modified copy of undirected graph G with added edge e (or trail T or list of edges E). - See also: 1/ add_arc 2/ delete_edge 3/ edges 4/ graph 5/ has_edge 6/ trail + See also: 1/ add_arc 2/ delete_edge 3/ edges 4/ graph 5/ has_edge 6/ trail Ex1:add_edge(graph(trail(1,2,3,4)),[4,1]) - ''' return GiacMethods['add_edge'](self,*args) @@ -706,9 +649,8 @@ cdef class GiacMethods_base: Help for add_vertex: add_vertex(Graph(G),Vrtx(v)||Lst(V)) Returns a modified copy of G with added vertex v [or vertices from list V]. - See also: 1/ add_arc 2/ add_edge 3/ delete_vertex + See also: 1/ add_arc 2/ add_edge 3/ delete_vertex Ex1:add_vertex(cycle_graph(5),["a","b"]) - ''' return GiacMethods['add_vertex'](self,*args) @@ -717,10 +659,9 @@ cdef class GiacMethods_base: Help for additionally: additionally(Expr) Makes an additionally assumption on a variable. - See also: 1/ purge 2/ about 3/ assume + See also: 1/ purge 2/ about 3/ assume Ex1: assume(n,integer);additionally(n>5) Ex2: assume(n,integer);assume(n>=2,additionally) - ''' return GiacMethods['additionally'](self,*args) @@ -729,9 +670,8 @@ cdef class GiacMethods_base: Help for addtable: addtable(fourier||laplace,f(x),F(s),Var(x),Var(s)) Stores an unknown Fourier/Laplace transform pair (f,F). - See also: 1/ fourier 2/ laplace + See also: 1/ fourier 2/ laplace Ex1:addtable(fourier,y(x),Y(s),x,s) - ''' return GiacMethods['addtable'](self,*args) @@ -740,9 +680,8 @@ cdef class GiacMethods_base: Help for adjacency_matrix: adjacency_matrix(Graph(G)) Returns the adjacency matrix of G (rows and columns are indexed by the vertices). - See also: 1/ neighbors + See also: 1/ neighbors Ex1:adjacency_matrix(graph(trail(1,2,3,4,2,5,1,3))) - ''' return GiacMethods['adjacency_matrix'](self,*args) @@ -751,9 +690,8 @@ cdef class GiacMethods_base: Help for adjoint_matrix: adjoint_matrix(Mtrx) Returns the characteristic polynomial of A and the comatrix of A-xI. - See also: 1/ pcar + See also: 1/ pcar Ex1:adjoint_matrix([[1,i],[2,3]]) - ''' return GiacMethods['adjoint_matrix'](self,*args) @@ -762,11 +700,10 @@ cdef class GiacMethods_base: Help for affix: affix(Pnt||Vect) Complex number equal to the affix of a point or of a vector. - See also: 1/ point 2/ vector + See also: 1/ point 2/ vector Ex1:affix(point(i)) Ex2:affix(point(i)-point(1+2*i)) Ex3:affix([1,2]) - ''' return GiacMethods['affix'](self,*args) @@ -775,11 +712,10 @@ cdef class GiacMethods_base: Help for algsubs: algsubs(Equal(Xpr1=Xpr2),Expr(Xpr)) Substitutes in the expression Xpr, the algebraic expression Xpr1 by the algebraic expression Xpr2. - See also: 1/ subst 2/ subs + See also: 1/ subst 2/ subs Ex1:algsubs(x^2=u,1+x^2+x^4) Ex2:algsubs(a*b/c=d, 2*a*b^2/c) Ex3:algsubs(2a=p^2-q^2,algsubs(2c=p^2+q^2,c^2-a^2)) - ''' return GiacMethods['algsubs'](self,*args) @@ -788,9 +724,8 @@ cdef class GiacMethods_base: Help for algvar: algvar(Expr) List of the variables by ascending algebraic extension order. - See also: 1/ lvar 2/ lname + See also: 1/ lvar 2/ lname Ex1:algvar(sqrt(x)+y) - ''' return GiacMethods['algvar'](self,*args) @@ -799,10 +734,9 @@ cdef class GiacMethods_base: Help for all_trig_solutions: all_trig_solutions(:=Intg(0 or 1)) Pseudo-variable to return the general solution (all_trig_solutions:=1) or principal solution (all_trig_solutions:=0). - See also: 1/ cas_setup + See also: 1/ cas_setup Ex1: all_trig_solutions:=1 Ex2: all_trig_solutions:=0 - ''' return GiacMethods['all_trig_solutions'](self,*args) @@ -811,9 +745,8 @@ cdef class GiacMethods_base: Help for allpairs_distance: allpairs_distance(Graph(G)) Returns a square matrix D of order equal to the number of vertices in G such that D(i,j) is the distance between i-th and j-th vertex of the (weighted) graph G. - See also: 1/ dijkstra 2/ graph_diameter 3/ vertex_distance + See also: 1/ dijkstra 2/ graph_diameter 3/ vertex_distance Ex1:allpairs_distance(graph(%{[1,2],[1,3],[1,4],[1,5],[2,3],[3,4],[4,5],[5,2]%})) - ''' return GiacMethods['allpairs_distance'](self,*args) @@ -822,9 +755,8 @@ cdef class GiacMethods_base: Help for alog10: alog10(Expr) Function x->10^x. - See also: 1/ log10 + See also: 1/ log10 Ex1:alog10(3) - ''' return GiacMethods['alog10'](self,*args) @@ -833,9 +765,8 @@ cdef class GiacMethods_base: Help for altitude: altitude((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) altitude(A,B,C) draws the altitude through A of the triangle ABC. - See also: 1/ perpendicular 2/ orthogonal 3/ orthocenter 4/ common_perpendicular + See also: 1/ perpendicular 2/ orthogonal 3/ orthocenter 4/ common_perpendicular Ex1:altitude(-1,1-i,i) - ''' return GiacMethods['altitude'](self,*args) @@ -844,13 +775,12 @@ cdef class GiacMethods_base: Help for angle: angle((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) angle(A,B,C) is the value of the measure of the angle (AB,AC). - See also: 1/ triangle 2/ bissector 3/ legend 4/ labels 5/ angleat 6/ angleatraw + See also: 1/ triangle 2/ bissector 3/ legend 4/ labels 5/ angleat 6/ angleatraw Ex1:angle(point(0),point(i),point(1)) Ex2:angle(0,1,i) Ex3:angle(0,1,i,"") Ex4:angle(0,1,i,"a") Ex5:angle(i,1,1+i,"b") - ''' return GiacMethods['angle'](self,*args) @@ -859,10 +789,9 @@ cdef class GiacMethods_base: Help for angle_radian: angle_radian(:=Intg(0 or 1)) Pseudo-variable to work with radians (angle_radian:=1) or degrees (angle_radian:=0). - See also: 1/ cas_setup + See also: 1/ cas_setup Ex1: angle_radian:=1 Ex2: angle_radian:=0 - ''' return GiacMethods['angle_radian'](self,*args) @@ -871,9 +800,8 @@ cdef class GiacMethods_base: Help for angleat: angleat(Pnt(A),Pnt(B),Pnt(C),(Pnt or Cplx(z0))) angleat(A,B,C,z0) displays at point(z0) with a legend, the value of the measure of the angle (AB,AC). - See also: 1/ angle 2/ angleatraw 3/ legend + See also: 1/ angle 2/ angleatraw 3/ legend Ex1: A:=point(0);B:=point(1);C:=point(i);angleat(A,B,C,-2-i) - ''' return GiacMethods['angleat'](self,*args) @@ -882,9 +810,8 @@ cdef class GiacMethods_base: Help for angleatraw: angleatraw(Pnt(A)),Pnt(B),Pnt(C),(Pnt or Cplx(z0))) angleatraw(A,B,C,z0) displays at point(z0), the value of the measure of the angle (AB,AC). - See also: 1/ angle 2/ angleat + See also: 1/ angle 2/ angleat Ex1: A:=point(0);B:=point(1);C:=point(i);angleatraw(A,B,C,-2-i) - ''' return GiacMethods['angleatraw'](self,*args) @@ -893,11 +820,10 @@ cdef class GiacMethods_base: Help for ans: ans(Intg(n)) Returns the (n+1)th answer of the command history if n>=0 or, the (-n)th previous answer if n<0 (by default n=-1 for the previous answer). - See also: 1/ quest + See also: 1/ quest Ex1:ans() Ex2:ans(2) Ex3:ans(-2) - ''' return GiacMethods['ans'](self,*args) @@ -906,9 +832,8 @@ cdef class GiacMethods_base: Help for antiprism_graph: antiprism_graph(Intg(n)) Returns the antiprism graph of order n. - See also: 1/ prism_graph + See also: 1/ prism_graph Ex1:antiprism_graph(5) - ''' return GiacMethods['antiprism_graph'](self,*args) @@ -917,14 +842,13 @@ cdef class GiacMethods_base: Help for append: append((Lst||Set||Str(L),Elem)) Append an element to a set or at the end of a list or of a string (L:=append(L,a) or L.append(a)). - See also: 1/ concat 2/ prepend + See also: 1/ concat 2/ prepend Ex1:append([1,2,4],6) Ex2:append(%{1,2,4%},6) Ex3: L:=[1,2,4];L:=append(L,6) Ex4: L:=[1,2,4];L.append(6) Ex5: S:=set[1,2,4];S:=append(S,6) Ex6: S:=set[1,2,4];S.append(6) - ''' return GiacMethods['append'](self,*args) @@ -933,10 +857,9 @@ cdef class GiacMethods_base: Help for apply: apply(Fnc(f),Lst(l)) Applies the function f at the elements of the list l (option matrix for a matrix). - See also: 1/ map 2/ unapply 3/ matrix + See also: 1/ map 2/ unapply 3/ matrix Ex1:apply(x->x^3,[1,2,3]) Ex2:apply(x->x+1,[[1,2,3],[1,2,3]],matrix) - ''' return GiacMethods['apply'](self,*args) @@ -945,14 +868,13 @@ cdef class GiacMethods_base: Help for approx: approx(Expr,[Int]) Numerical evaluation of the first argument (we can give the number of digits as second argument). - See also: 1/ evalb 2/ eval + See also: 1/ evalb 2/ eval Ex1:approx(2/3) Ex2:approx(2/3,2) Ex3:approx(2*sin(1)) Ex4:approx(2*sin(1),40) Ex5:approx(sqrt(2)+pi) Ex6:approx(sqrt(2)+pi,30) - ''' return GiacMethods['approx'](self,*args) @@ -961,12 +883,11 @@ cdef class GiacMethods_base: Help for arc: arc(Pnt, Pnt, Real,[Var(C)],[Var(r)],[Opt(segment)]) Draws a circular arc given by 2 vertices and the central angle [Xcas will put the center in C and the radius in r]. - See also: 1/ circle 2/ segment 3/ plotparam + See also: 1/ circle 2/ segment 3/ plotparam Ex1:arc(0,1,pi/4) Ex2:arc(i,1,pi/4,C,r) Ex3:arc(i,1,pi/4,segment) Ex4:arc(i,1,pi/4,segment,affichage=1+rempli) - ''' return GiacMethods['arc'](self,*args) @@ -975,11 +896,10 @@ cdef class GiacMethods_base: Help for arcLen: arcLen(Expr(Xpr) or Lst([Xpr1,Xpr2]),Var,Real(a),Real(b)) Returns the length of the arc of the curve defined by y=Xpr(or by x=Xpr1,y=Xpr2) when the parameter values are between a and b. - See also: 1/ int + See also: 1/ int Ex1:arcLen(t^2,t,1,2) Ex2:arcLen([t,t^2],t,1,2) Ex3:arcLen([cos(t),sin(t)],t,1,2) - ''' return GiacMethods['arcLen'](self,*args) @@ -988,9 +908,8 @@ cdef class GiacMethods_base: Help for arccos: arccos(Expr) Arccosine. - See also: 1/ cos 2/ acosh + See also: 1/ cos 2/ acosh Ex1:arccos(0) - ''' return GiacMethods['arccos'](self,*args) @@ -999,9 +918,8 @@ cdef class GiacMethods_base: Help for arccosh: arccosh(Expr) Hyperbolic arccosine. - See also: 1/ cosh 2/ acos + See also: 1/ cosh 2/ acos Ex1:arccosh(1) - ''' return GiacMethods['arccosh'](self,*args) @@ -1010,11 +928,10 @@ cdef class GiacMethods_base: Help for arclen: arclen(Expr(Xpr) or Lst([Xpr1,Xpr2]),Var,Real(a),Real(b)) Returns the length of the arc of the curve defined by y=Xpr(or by x=Xpr1,y=Xpr2) when the parameter values are between a and b. - See also: 1/ int + See also: 1/ int Ex1:arclen(t^2,t,1,2) Ex2:arclen([t,t^2],t,1,2) Ex3:arclen([cos(t),sin(t)],t,1,2) - ''' return GiacMethods['arclen'](self,*args) @@ -1023,9 +940,8 @@ cdef class GiacMethods_base: Help for arcsin: arcsin(Expr) Arcsine. - See also: 1/ sin + See also: 1/ sin Ex1:arcsin(0) - ''' return GiacMethods['arcsin'](self,*args) @@ -1034,9 +950,8 @@ cdef class GiacMethods_base: Help for arcsinh: arcsinh(Expr) Hyperbolic arcsine. - See also: 1/ sinh 2/ asin + See also: 1/ sinh 2/ asin Ex1:arcsinh(0) - ''' return GiacMethods['arcsinh'](self,*args) @@ -1045,9 +960,8 @@ cdef class GiacMethods_base: Help for arctan: arctan(Expr) Arctangent. - See also: 1/ tan 2/ atanh + See also: 1/ tan 2/ atanh Ex1:arctan(0) - ''' return GiacMethods['arctan'](self,*args) @@ -1056,9 +970,8 @@ cdef class GiacMethods_base: Help for arctanh: arctanh(Expr) Hyperbolic arctangent. - See also: 1/ atan 2/ tanh + See also: 1/ atan 2/ tanh Ex1:arctanh(0) - ''' return GiacMethods['arctanh'](self,*args) @@ -1067,7 +980,7 @@ cdef class GiacMethods_base: Help for area: area(Polygone || Expr,x=a..b,[n],[Method]) Algebraic area of a circle, a circular arc or of a (star) polygon (e.g. triangle, square, ...) or of the area below a curve, optionally with a quadrature method (trapezoid,left_rectangle,right_rectangle,middle_point,simpson,rombergt,rombergm). - See also: 1/ trapezoid 2/ perimeter 3/ areaatraw 4/ areaat 5/ areaplot + See also: 1/ trapezoid 2/ perimeter 3/ areaatraw 4/ areaat 5/ areaplot Ex1:area(triangle(0,1,i)) Ex2:area(square(0,2)) Ex3:area(circle(0,2)) @@ -1075,7 +988,6 @@ cdef class GiacMethods_base: Ex5:area(x^2,x=0..1,5,trapezoid) Ex6:area(x^2,x=0..1,5,simpson) Ex7:area(x^2,x=0..1,5,rombergm) - ''' return GiacMethods['area'](self,*args) @@ -1084,13 +996,12 @@ cdef class GiacMethods_base: Help for areaat: areaat(Polygone, Pnt||Cplx(z0)) Displays at point(z0), with a legend, the algebraic area of a circle or of a (star) polygon (e.g. triangle, square, ...) - See also: 1/ area 2/ areaatraw 3/ polygon 4/ perimeteratraw 5/ areaplot + See also: 1/ area 2/ areaatraw 3/ polygon 4/ perimeteratraw 5/ areaplot Ex1: t:=triangle(0,1,i);areaat(t,(1+i)/2) Ex2: c:=square(0,2);areaat(c,1+i) Ex3: c2:=circle(0,2);areaat(c2,1+i) Ex4: p:=polygon(0,1,i);areaat(p,1+i) Ex5: A:=point(0);B:=point(1+i);c:=carre(A,B);areaat(c,i) - ''' return GiacMethods['areaat'](self,*args) @@ -1099,13 +1010,12 @@ cdef class GiacMethods_base: Help for areaatraw: areaatraw(Polygone, Pnt||Cplx(z0)) Displays at point(z0), the algebraic area of a circle or of a (star-)polygon (e.g. triangle, square, ...) - See also: 1/ area 2/ areaat 3/ polygon 4/ perimeteratraw 5/ areaplot + See also: 1/ area 2/ areaat 3/ polygon 4/ perimeteratraw 5/ areaplot Ex1:areaatraw(triangle(0,1,i),(1+i)/2) Ex2:areaatraw(square(0,2),1+i) Ex3:areaatraw(circle(0,2),1+i) Ex4:areaatraw(polygon(0,1,i),1+i) Ex5: A:=point(0);B:=point(1+i);c:=carre(A,B);areaatraw(c,i) - ''' return GiacMethods['areaatraw'](self,*args) @@ -1114,11 +1024,10 @@ cdef class GiacMethods_base: Help for areaplot: areaplot(Expr,x=a..b,[n],[Method]) Displays the area below a curve, optionally with a quadrature method (trapezoid,left_rectangle,right_rectangle,middle_point). - See also: 1/ integrate 2/ plot 3/ area 4/ areaat 5/ areaatraw + See also: 1/ integrate 2/ plot 3/ area 4/ areaat 5/ areaatraw Ex1:areaplot(sin(x),x=0..pi) Ex2:areaplot(x^2,x=0..1,5,trapezoid) Ex3:areaplot(x^2,x=0..1,5,middle_point) - ''' return GiacMethods['areaplot'](self,*args) @@ -1127,11 +1036,10 @@ cdef class GiacMethods_base: Help for arg: arg(Expr) Returns the argument of a complex number. - See also: 1/ abs + See also: 1/ abs Ex1:arg(1+i) Ex2:arg(1+2*i) Ex3:arg((1+2*i)^2) - ''' return GiacMethods['arg'](self,*args) @@ -1140,10 +1048,9 @@ cdef class GiacMethods_base: Help for array: array(Opt) Option for convert for definitions of sparse matrices. - See also: 1/ convert 2/ table + See also: 1/ convert 2/ table Ex1: A[0..2,0..2]:=1;A[0..1,1..2]:=2;convert(A,array) Ex2: B[0..1,1..2]:=1;B[2,2]:=2;convert(B,array) - ''' return GiacMethods['array'](self,*args) @@ -1152,9 +1059,8 @@ cdef class GiacMethods_base: Help for arrivals: arrivals(Graph(G),[Vrtx(v)]) Returns the list of vertices in digraph G which are connected by v with arcs such that heads are in v. If v is omitted, a list of arrivals is computed for every vertex in G. - See also: 1/ in_degree + See also: 1/ in_degree Ex1:arrivals(digraph(%{[1,2],[1,3],[2,3]%}),1) - ''' return GiacMethods['arrivals'](self,*args) @@ -1163,10 +1069,9 @@ cdef class GiacMethods_base: Help for articulation_points: articulation_points(Graph(G)) Returns the list of articulation points (cut vertices) of G. - See also: 1/ biconnected_components 2/ is_biconnected 3/ is_connected 4/ is_triconnected + See also: 1/ biconnected_components 2/ is_biconnected 3/ is_connected 4/ is_triconnected Ex1:articulation_points(path_graph(5)) Ex2:articulation_points(cycle_graph(5)) - ''' return GiacMethods['articulation_points'](self,*args) @@ -1175,9 +1080,8 @@ cdef class GiacMethods_base: Help for asin: asin(Expr) Arcsine. - See also: 1/ sin + See also: 1/ sin Ex1:asin(0) - ''' return GiacMethods['asin'](self,*args) @@ -1186,10 +1090,9 @@ cdef class GiacMethods_base: Help for asin2acos: asin2acos(Expr) Replaces arcsin(x) by pi/2-arccos(x) in the argument. - See also: 1/ asin2atan + See also: 1/ asin2atan Ex1:asin2acos(acos(x)+asin(x)) Ex2:asin2acos(2*asin(x)) - ''' return GiacMethods['asin2acos'](self,*args) @@ -1198,10 +1101,9 @@ cdef class GiacMethods_base: Help for asin2atan: asin2atan(Expr) Replaces arcsin(x) by arctan(x/sqrt(1-x^2)) in the argument. - See also: 1/ asin2acos + See also: 1/ asin2acos Ex1:asin2atan(2*asin(x)) Ex2:asin2atan(asin(sqrt(1-x^2))+asin(x)) - ''' return GiacMethods['asin2atan'](self,*args) @@ -1210,9 +1112,8 @@ cdef class GiacMethods_base: Help for asinh: asinh(Expr) Hyperbolic arcsine. - See also: 1/ sinh 2/ asin + See also: 1/ sinh 2/ asin Ex1:asinh(0) - ''' return GiacMethods['asinh'](self,*args) @@ -1221,10 +1122,9 @@ cdef class GiacMethods_base: Help for assign_edge_weights: assign_edge_weights(Graph(G),Seq(m,n)||Intrv(a..b)) Assigns random edge weights to the edges of G and returns a modified copy of G. If integers n and m such that n>=m are specified, weights are integers randomly chosen in [m,n]. If an interval a..b is specified, weights are uniformly distributed in the interval [a,b). - See also: 1/ set_edge_weight 2/ get_edge_weight 3/ weight_matrix 4/ random_digraph 5/ random_tournament + See also: 1/ set_edge_weight 2/ get_edge_weight 3/ weight_matrix 4/ random_digraph 5/ random_tournament Ex1:assign_edge_weights(digraph(trail(1,2,3,4,1)),1,9) Ex2:assign_edge_weights(digraph(trail(1,2,3,4,1)),0..1) - ''' return GiacMethods['assign_edge_weights'](self,*args) @@ -1233,7 +1133,7 @@ cdef class GiacMethods_base: Help for assume: assume(Expr) Makes an assumption on a variable. - See also: 1/ purge 2/ about 3/ additionally + See also: 1/ purge 2/ about 3/ additionally Ex1:assume(a>0) Ex2:assume(a=0.3) Ex3:assume(a:=[pi/4,0,pi/2]) @@ -1244,7 +1144,6 @@ cdef class GiacMethods_base: Ex8:assume((a>=2 and a<4) or a>6) Ex9:assume(a>=2);additionally(a<6) Ex10:assume(a) - ''' return GiacMethods['assume'](self,*args) @@ -1253,10 +1152,9 @@ cdef class GiacMethods_base: Help for at: at(Lst(l)||Mtrx(m),Index(j)||Lst([j,k])) at(l,j) (or at(m,[j,k])) is the element of the list l (or matrix m) for index=j (or for index j,k). - See also: 1/ of + See also: 1/ of Ex1:at([10,11,12],1) Ex2:at([[1,2],[3,4]],[1,0]) - ''' return GiacMethods['at'](self,*args) @@ -1265,9 +1163,8 @@ cdef class GiacMethods_base: Help for atan: atan(Expr) Arctangent. - See also: 1/ tan 2/ atanh + See also: 1/ tan 2/ atanh Ex1:atan(0) - ''' return GiacMethods['atan'](self,*args) @@ -1276,8 +1173,7 @@ cdef class GiacMethods_base: Help for atan2acos: atan2acos(Expr) Replaces arctan(x) by pi/2-arccos(x/sqrt(1+x^2)) in the argument. - See also: 1/ atan2acos(atan(x)) - + See also: 1/ atan2acos(atan(x)) ''' return GiacMethods['atan2acos'](self,*args) @@ -1286,8 +1182,7 @@ cdef class GiacMethods_base: Help for atan2asin: atan2asin(Expr) Replaces arctan(x) by arcsin(x/sqrt(1+x^2)) in the argument. - See also: 1/ atan2asin(atan(x)) - + See also: 1/ atan2asin(atan(x)) ''' return GiacMethods['atan2asin'](self,*args) @@ -1296,9 +1191,8 @@ cdef class GiacMethods_base: Help for atanh: atanh(Expr) Hyperbolic arctangent. - See also: 1/ atan 2/ tanh + See also: 1/ atan 2/ tanh Ex1:atanh(0) - ''' return GiacMethods['atanh'](self,*args) @@ -1307,11 +1201,10 @@ cdef class GiacMethods_base: Help for atrig2ln: atrig2ln(Expr) Rewrites the expression containing inverse trigonometric functions into logarithmic functions. - See also: 1/ trig2exp 2/ exp2trig + See also: 1/ trig2exp 2/ exp2trig Ex1:atrig2ln(atan(x)) Ex2:atrig2ln(asin(x)) Ex3:atrig2ln(acos(x)) - ''' return GiacMethods['atrig2ln'](self,*args) @@ -1320,13 +1213,12 @@ cdef class GiacMethods_base: Help for augment: augment(Lst,Lst||Seq,Seq||Str,Str||Mtrx,Mtrx) Concatenates two lists or two strings or two sequences or 2 matrices; L:=concat(L,L1) or L.concat(L1). - See also: 1/ append 2/ cat 3/ semi_augment 4/ border 5/ + + See also: 1/ append 2/ cat 3/ semi_augment 4/ border 5/ + Ex1:augment([1,2],[3,4,5]) Ex2:augment("bon","jour") Ex3:augment([[1,2],[3,4]],[[4,5,6],[6,7,8]]) Ex4: L:=[1,2];L.concat([3,4,5]) Ex5: S:="abcd";S.concat("efghi") - ''' return GiacMethods['augment'](self,*args) @@ -1335,9 +1227,8 @@ cdef class GiacMethods_base: Help for auto_correlation: auto_correlation(Lst) Returns the cross-correlation of the given signal with itself. - See also: 1/ cross_correlation 2/ correlation + See also: 1/ cross_correlation 2/ correlation Ex1:auto_correlation([1,-1,0,2,1]) - ''' return GiacMethods['auto_correlation'](self,*args) @@ -1346,14 +1237,13 @@ cdef class GiacMethods_base: Help for autosimplify: autosimplify(Cmds) The argument is a command that Xcas will use to rewrite answers (initial value is regroup and for no simplification it is nop or 0). - See also: 1/ simplify 2/ factor 3/ regroup + See also: 1/ simplify 2/ factor 3/ regroup Ex1:autosimplify(nop) Ex2:autosimplify(0) Ex3:autosimplify(regroup) Ex4:autosimplify(1) Ex5:autosimplify(factor) Ex6:autosimplify(simplify) - ''' return GiacMethods['autosimplify'](self,*args) @@ -1362,10 +1252,9 @@ cdef class GiacMethods_base: Help for avance: avance(NULL or Real(n)) The turtle takes n steps forward (by default n=10). - See also: 1/ recule 2/ saute + See also: 1/ recule 2/ saute Ex1: avance 30 Ex2:avance(30) - ''' return GiacMethods['avance'](self,*args) @@ -1374,11 +1263,10 @@ cdef class GiacMethods_base: Help for avgRC: avgRC(Expr(Xpr),Var(Var),[Real(h)]) Returns (Xpr(var+h)-Xpr(Var))/h (by default h=0.001). - See also: 1/ nDeriv + See also: 1/ nDeriv Ex1:avgRC(f(x),x,h) Ex2:avgRC(x^2,x,0.1) Ex3:avgRC(x^2,x) - ''' return GiacMethods['avgRC'](self,*args) @@ -1387,10 +1275,9 @@ cdef class GiacMethods_base: Help for axes: axes(Opt) Global option (Maple compatibility) of a graphic command to put or not the axes. - See also: 1/ line_width 2/ gl_showaxes 3/ switch_axes + See also: 1/ line_width 2/ gl_showaxes 3/ switch_axes Ex1: axes=0;segment(0,point(1,1)) Ex2: axes=1;segment(0,point(1,1),epaisseur=5) - ''' return GiacMethods['axes'](self,*args) @@ -1400,7 +1287,6 @@ cdef class GiacMethods_base: axis(xmin,xmax,ymin,ymax,[zmin,zmaz]) Defines the graphic display Ex1:axis(-2,4,-1,6) - ''' return GiacMethods['axis'](self,*args) @@ -1409,11 +1295,10 @@ cdef class GiacMethods_base: Help for back: back(Vect or Seq or Str) Returns the last element of a vector or a sequence or a string. - See also: 1/ inter 2/ head 3/ mid 4/ left 5/ right + See also: 1/ inter 2/ head 3/ mid 4/ left 5/ right Ex1:back(1,2,3) Ex2:back([1,2,3]) Ex3:back("bonjour") - ''' return GiacMethods['back'](self,*args) @@ -1422,10 +1307,9 @@ cdef class GiacMethods_base: Help for backward: backward(NULL or Real(n)) The turtle takes n steps back (by default n=10). - See also: 1/ avance 2/ saute + See also: 1/ avance 2/ saute Ex1: recule 30 Ex2:backward(30) - ''' return GiacMethods['backward'](self,*args) @@ -1434,9 +1318,8 @@ cdef class GiacMethods_base: Help for baisse_crayon: baisse_crayon(NULL) Presses the pencil down so that the turtle move with traces. - See also: 1/ leve_crayon 2/ crayon + See also: 1/ leve_crayon 2/ crayon Ex1:baisse_crayon() - ''' return GiacMethods['baisse_crayon'](self,*args) @@ -1445,8 +1328,7 @@ cdef class GiacMethods_base: Help for bandwidth: bandwidth(Opt) Option for the kernel_density command. - See also: 1/ kernel_density 2/ bins - + See also: 1/ kernel_density 2/ bins ''' return GiacMethods['bandwidth'](self,*args) @@ -1455,11 +1337,10 @@ cdef class GiacMethods_base: Help for bar_plot: bar_plot(Mtrx) Draws a barplot of a one variable statistical series. - See also: 1/ camembert 2/ histogram 3/ frequencies + See also: 1/ camembert 2/ histogram 3/ frequencies Ex1:bar_plot([["France",6],["Allemagne",12],["Suisse",5]]) Ex2:bar_plot([3/2,2/3,5/4,4/5,7/6,6/7,9/8,8/9,11/10]) Ex3:bar_plot([[2,"xyz","abc"],["A",2,5],["B",5,6],["C",7,7]]) - ''' return GiacMethods['bar_plot'](self,*args) @@ -1468,11 +1349,10 @@ cdef class GiacMethods_base: Help for barplot: barplot(Mtrx) Draws a barplot of a one variable statistical series. - See also: 1/ camembert 2/ histogram 3/ frequencies + See also: 1/ camembert 2/ histogram 3/ frequencies Ex1:barplot([["France",6],["Allemagne",12],["Suisse",5]]) Ex2:barplot([3/2,2/3,5/4,4/5,7/6,6/7,9/8,8/9,11/10]) Ex3:barplot([[2,"xyz","abc"],["A",2,5],["B",5,6],["C",7,7]]) - ''' return GiacMethods['barplot'](self,*args) @@ -1481,9 +1361,8 @@ cdef class GiacMethods_base: Help for bartlett_hann_window: bartlett_hann_window(Lst,[Interval(n1..n2)]) Applies the Bartlett-Hann windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(bartlett_hann_window(randvector(1000,0..1))) - ''' return GiacMethods['bartlett_hann_window'](self,*args) @@ -1492,11 +1371,10 @@ cdef class GiacMethods_base: Help for barycenter: barycenter([Pnt,Real],[Pnt,Real],[Pnt,Real]) barycenter([point1,coeff1],...) draws the barycenter of point1 with weight coeff1... - See also: 1/ isobarycenter 2/ midpoint + See also: 1/ isobarycenter 2/ midpoint Ex1:barycenter([point(-1),1],[point(1+i),2],[point(1-i),1]) Ex2:barycenter([[point(-1),1],[point(1+i),2],[point(1-i),1]]) Ex3:barycenter([point(-1),point(1+i),point(1-i)],[1,2,1]) - ''' return GiacMethods['barycenter'](self,*args) @@ -1505,11 +1383,10 @@ cdef class GiacMethods_base: Help for base: base(Opt) Option for convert : convert(p,base,b)= [a0,a1,..an] or convert([a0,a1,..an],base,b)=p with p=a0+a1*b+....an*b^(n-1). - See also: 1/ convert 2/ horner 3/ revlist + See also: 1/ convert 2/ horner 3/ revlist Ex1: convert(123,base,8) Ex2: convert([3,7,1],base,8) Ex3: horner(revlist([3,7,1]),8) - ''' return GiacMethods['base'](self,*args) @@ -1518,9 +1395,8 @@ cdef class GiacMethods_base: Help for basis: basis(Lst(vector1,..,vectorn)) Extracts a basis from a spanning set of vectors. - See also: 1/ ker 2/ ibasis + See also: 1/ ker 2/ ibasis Ex1:basis([[1,2,3],[4,5,6],[7,8,9],[10,11,12]]) - ''' return GiacMethods['basis'](self,*args) @@ -1529,11 +1405,10 @@ cdef class GiacMethods_base: Help for batons: batons(Mtrx) Draws for k=0..nrows, the segments (xk,0)-(xk,yk) where xk=element row k column 0 and yk=element row k column j (j=1..ncols). - See also: 1/ polygonplot 2/ scatterplot 3/ listplot + See also: 1/ polygonplot 2/ scatterplot 3/ listplot Ex1:batons([1,3],[2,5],[3,2]) Ex2:batons([[1,3],[2,5],[3,2]]) Ex3:batons([1,2,3],[3,5,2]) - ''' return GiacMethods['batons'](self,*args) @@ -1542,9 +1417,8 @@ cdef class GiacMethods_base: Help for bellman_ford: bellman_ford(Graph(G),Vrtx(s),Vrtx(t)||Lst(T)) Returns the length of the shortest path resp. paths from s to vertex t resp. vertices in T in weighted graph G. - See also: 1/ dijkstra 2/ shortest_path + See also: 1/ dijkstra 2/ shortest_path Ex1:bellman_ford(graph(%{[[1,2],-1],[[2,3],-3],[[3,4],-7],[[4,5],-3],[[5,6],-3],[[1,6],-3]%}),1,4) - ''' return GiacMethods['bellman_ford'](self,*args) @@ -1553,10 +1427,9 @@ cdef class GiacMethods_base: Help for bernoulli: bernoulli(Intg||(Intg,Var)) bernoulli(n) is the n-th number of Bernoulli and bernoulli(n,x) is the n-th polynomial of Bernoulli and the second argument is the variable. - See also: 1/ + See also: 1/ Ex1:bernoulli(6) Ex2:bernoulli(6,x) - ''' return GiacMethods['bernoulli'](self,*args) @@ -1565,10 +1438,9 @@ cdef class GiacMethods_base: Help for besselJ: besselJ(Real(x),Int(p)) besselJ(x,p) returns the Bessel function of the first kind Jp(x). - See also: 1/ BesselJ 2/ BesselY 3/ besselY + See also: 1/ BesselJ 2/ BesselY 3/ besselY Ex1:besselJ(sqrt(2),2) Ex2:besselJ(sqrt(2),-2) - ''' return GiacMethods['besselJ'](self,*args) @@ -1577,10 +1449,9 @@ cdef class GiacMethods_base: Help for besselY: besselY(Real(x),Int(p)) besselY(x,p) returns the Bessel function of the second kind Yp(x). - See also: 1/ BesselY 2/ BesselJ 3/ besselJ + See also: 1/ BesselY 2/ BesselJ 3/ besselJ Ex1:besselY(sqrt(2),2) Ex2:besselY(sqrt(2),-2) - ''' return GiacMethods['besselY'](self,*args) @@ -1589,9 +1460,8 @@ cdef class GiacMethods_base: Help for betad: betad(Real(a>0),Real(b>0),Real(0<=x<=1)) Returns the probability density of the Beta law (=Gamma(a+b)*x^(a-1)*(1-x)^(b-1)/(Gamma(a)*Gamma(b))). - See also: 1/ betad_cdf 2/ betad_icdf + See also: 1/ betad_cdf 2/ betad_icdf Ex1:betad(2.2,1.5,0.8) - ''' return GiacMethods['betad'](self,*args) @@ -1600,10 +1470,9 @@ cdef class GiacMethods_base: Help for betad_cdf: betad_cdf(Real(a>0),Real(b>0),Real(0<=x0<=1),[Real(0<=y0<=1)]) Returns the probability that a Beta random variable (with a and b as parameters) is less than x0 or between x0 and y0. - See also: 1/ betad 2/ betad_icdf + See also: 1/ betad 2/ betad_icdf Ex1:betad_cdf(2,1,0.2) Ex2:betad_cdf(2,1,0.1,0.3) - ''' return GiacMethods['betad_cdf'](self,*args) @@ -1612,10 +1481,9 @@ cdef class GiacMethods_base: Help for betad_icdf: betad_icdf(Real(a>0),Real(b>0),Real(0<=p<=1)) Returns h such that the probability that a Beta random variable is less than h is p (0<=p<=1). - See also: 1/ betad_cdf 2/ betad + See also: 1/ betad_cdf 2/ betad Ex1:betad_icdf(2,1,0.95) Ex2:betad_icdf(2,1,0.5) - ''' return GiacMethods['betad_icdf'](self,*args) @@ -1624,10 +1492,9 @@ cdef class GiacMethods_base: Help for betavariate: betavariate(Real(a),Real(b)) Returns a random real according to the Beta distribution with parameters a>0 and b>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:betavariate(1,2) Ex2:betavariate(1.5,4) - ''' return GiacMethods['betavariate'](self,*args) @@ -1636,12 +1503,11 @@ cdef class GiacMethods_base: Help for bezier: bezier(Lst,[plot]) Bezier curve defined by control points. - See also: 1/ parameq + See also: 1/ parameq Ex1:bezier(1,1+i,2+i,3-i,plot) Ex2:bezier(point([0,0,0]),point([1,1,0]),point([0,1,1]),plot) Ex3: parameq(bezier(1,1+i,2+i,3-i)) Ex4: parameq(bezier(point([0,0,0]),point([1,1,0]),point([0,1,1]))) - ''' return GiacMethods['bezier'](self,*args) @@ -1650,11 +1516,10 @@ cdef class GiacMethods_base: Help for bezout_entiers: bezout_entiers(Intg,Intg) Extended greatest common divisor of 2 integers. - See also: 1/ gcd 2/ iabcuv 3/ egcd + See also: 1/ gcd 2/ iabcuv 3/ egcd Ex1:bezout_entiers(45,75) Ex2:bezout_entiers(21,28) Ex3:bezout_entiers(30,49) - ''' return GiacMethods['bezout_entiers'](self,*args) @@ -1663,9 +1528,8 @@ cdef class GiacMethods_base: Help for biconnected_components: biconnected_components(Graph(G)) Returns the biconnected components of G as a list of lists of vertices. - See also: 1/ articulation_points 2/ is_biconnected 3/ is_connected 4/ trail + See also: 1/ articulation_points 2/ is_biconnected 3/ is_connected 4/ trail Ex1:biconnected_components(graph(trail(1,2,3,4,2),trail(4,5,6,7,5))) - ''' return GiacMethods['biconnected_components'](self,*args) @@ -1674,7 +1538,7 @@ cdef class GiacMethods_base: Help for binomial: binomial(Intg(n),Intg(k),[Real(p in 0..1)]) Returns comb(n,k)*p^k*(1-p)^(n-k) or comb(n,k) if no 3rd argument. - See also: 1/ binomial_cdf 2/ binomial_icdf 3/ multinomial 4/ randvector 5/ ranm + See also: 1/ binomial_cdf 2/ binomial_icdf 3/ multinomial 4/ randvector 5/ ranm Ex1:binomial(4,2) Ex2:binomial(4,0,0.5) Ex3:binomial(4,2,0.5) @@ -1682,7 +1546,6 @@ cdef class GiacMethods_base: Ex5: assume(p>=0 and p<=1);binomial(4,p,2) Ex6: randvector(6,binomial,4,0.2) Ex7: ranm(4,6,binomial,4,0.7) - ''' return GiacMethods['binomial'](self,*args) @@ -1691,11 +1554,10 @@ cdef class GiacMethods_base: Help for binomial_cdf: binomial_cdf(Intg(n),Real(p),Real(x),[Real(y)]) Returns Proba(X<=x) or Proba(x<=X<=y) when X follows the B(n,p) law. - See also: 1/ binomial 2/ binomial_icdf + See also: 1/ binomial 2/ binomial_icdf Ex1:binomial_cdf(4,0.5,2) Ex2:binomial_cdf(4,0.1,2) Ex3:binomial_cdf(4,0.5,2,3) - ''' return GiacMethods['binomial_cdf'](self,*args) @@ -1704,10 +1566,9 @@ cdef class GiacMethods_base: Help for binomial_icdf: binomial_icdf(Intg(n),Real(p),Real(t)) Returns h such as Proba(X<=h)=t when X follows the B(n,p) law. - See also: 1/ binomial 2/ binomial_cdf + See also: 1/ binomial 2/ binomial_cdf Ex1:binomial_icdf(4,0.5,0.68) Ex2:binomial_icdf(4,0.1,0.95) - ''' return GiacMethods['binomial_icdf'](self,*args) @@ -1716,8 +1577,7 @@ cdef class GiacMethods_base: Help for bins: bins(Opt) Option for the kernel_density command. - See also: 1/ kernel_density 2/ bandwidth - + See also: 1/ kernel_density 2/ bandwidth ''' return GiacMethods['bins'](self,*args) @@ -1726,8 +1586,7 @@ cdef class GiacMethods_base: Help for bipartite: bipartite(Opt) Option for the draw_graph command - See also: 1/ draw_graph - + See also: 1/ draw_graph ''' return GiacMethods['bipartite'](self,*args) @@ -1736,9 +1595,8 @@ cdef class GiacMethods_base: Help for bipartite_matching: bipartite_matching(Graph(G)) Returns the list of edges in a maximum matching of the undirected unweighted bipartite graph G. - See also: 1/ is_bipartite 2/ maximum_matching + See also: 1/ is_bipartite 2/ maximum_matching Ex1:bipartite_matching(graph("desargues")) - ''' return GiacMethods['bipartite_matching'](self,*args) @@ -1747,14 +1605,13 @@ cdef class GiacMethods_base: Help for bisection_solver: bisection_solver(Opt) Argument for fsolve giving the method for solving a numerical equation. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve(cos(x)=x,x,0..1,bisection_solver) Ex2: fsolve(cos(x)=x,x,0..1,brent_solver) Ex3: fsolve(cos(x)=x,x,0..1,falsepos_solver) Ex4: fsolve(cos(x)=x,x,0,newton_solver) Ex5: fsolve(cos(x)=x,x,0,secant_solver) Ex6: fsolve(cos(x)=x,x,0,steffenson_solver) - ''' return GiacMethods['bisection_solver'](self,*args) @@ -1763,9 +1620,8 @@ cdef class GiacMethods_base: Help for bisector: bisector((Pnt(A) or Cplx),(Pnt(B) or Cplx),(Pnt(C) or Cplx)) Draws the bisector of the angle (AB,AC) given by 3 points A,B,C. - See also: 1/ angle 2/ exbisector + See also: 1/ angle 2/ exbisector Ex1:bisector(0,1,i) - ''' return GiacMethods['bisector'](self,*args) @@ -1774,9 +1630,8 @@ cdef class GiacMethods_base: Help for bit_depth: bit_depth(Lst(clip)) Returns the bit depth of an audio clip. - See also: 1/ channels 2/ channel_data 3/ duration 4/ samplerate + See also: 1/ channels 2/ channel_data 3/ duration 4/ samplerate Ex1:bit_depth(readwav("/some/file")) - ''' return GiacMethods['bit_depth'](self,*args) @@ -1785,9 +1640,8 @@ cdef class GiacMethods_base: Help for bitand: bitand(Intg,Intg) Logical bit and. - See also: 1/ bitxor 2/ bitor + See also: 1/ bitxor 2/ bitor Ex1:bitand(0x12,0x38) - ''' return GiacMethods['bitand'](self,*args) @@ -1796,9 +1650,8 @@ cdef class GiacMethods_base: Help for bitor: bitor(Intg,Intg) Inclusive logical bit or. - See also: 1/ bitxor 2/ bitand + See also: 1/ bitxor 2/ bitand Ex1:bitor(0x12,0x38) - ''' return GiacMethods['bitor'](self,*args) @@ -1807,9 +1660,8 @@ cdef class GiacMethods_base: Help for bitxor: bitxor(Intg,Intg) Exclusive logical bit or. - See also: 1/ bitor 2/ bitand + See also: 1/ bitor 2/ bitand Ex1:bitxor(0x12,0x38) - ''' return GiacMethods['bitxor'](self,*args) @@ -1818,9 +1670,8 @@ cdef class GiacMethods_base: Help for blackman_harris_window: blackman_harris_window(Lst,[Interval(n1..n2)]) Applies the Blackman-Harris windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ bartlett_hann_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ bartlett_hann_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(blackman_harris_window(randvector(1000,0..1))) - ''' return GiacMethods['blackman_harris_window'](self,*args) @@ -1829,9 +1680,8 @@ cdef class GiacMethods_base: Help for blackman_window: blackman_window(Lst,[Real(a)],[Interval(n1..n2)]) Applies the Blackman windowing function with parameter a (by default a=0.16) to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ bartlett_harris_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ bartlett_harris_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(blackman_window(randvector(1000,0..1))) - ''' return GiacMethods['blackman_window'](self,*args) @@ -1840,10 +1690,9 @@ cdef class GiacMethods_base: Help for blockmatrix: blockmatrix(Intg(n),Intg(m),Lst) Returns the matrix obtained from the list divided into n lists of dimension m. - See also: 1/ list2mat + See also: 1/ list2mat Ex1:blockmatrix(2,3,[idn(2),idn(2),idn(2),idn(2),idn(2),idn(2)]) Ex2:blockmatrix(2,2,[idn(2),newMat(2,3),newMat(3,2),idn(3)]) - ''' return GiacMethods['blockmatrix'](self,*args) @@ -1852,9 +1701,8 @@ cdef class GiacMethods_base: Help for bohman_window: bohman_window(Lst,[Interval(n1..n2)]) Applies the Bohman windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bartlett_hann_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bartlett_hann_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(bohman_window(randvector(1000,0..1))) - ''' return GiacMethods['bohman_window'](self,*args) @@ -1863,10 +1711,9 @@ cdef class GiacMethods_base: Help for border: border(Mtrx(A),Lst(b)) Returns the matrix obtained by augmenting A with b as the last column, if nrows(A)=size(b), border(A,b)=tran(append(tran(A),b)). - See also: 1/ tran 2/ append 3/ augment + See also: 1/ tran 2/ append 3/ augment Ex1:border([[1,2,3,4],[4,5,6,8],[7,8,9,10]],[1,3,5]) Ex2:border([[1,2,3],[4,5,6],[7,8,9]],[1,0,1]) - ''' return GiacMethods['border'](self,*args) @@ -1875,9 +1722,8 @@ cdef class GiacMethods_base: Help for boxcar: boxcar(Real(a),Real(b),Expr(x)) Returns the value at x of the boxcar function corresponding to a and b. - See also: 1/ rect 2/ Heaviside + See also: 1/ rect 2/ Heaviside Ex1:boxcar(1,2,x) - ''' return GiacMethods['boxcar'](self,*args) @@ -1886,12 +1732,11 @@ cdef class GiacMethods_base: Help for boxwhisker: boxwhisker(Lst,[Lst],[x=a..b||y=a..b]) Box and Whisker plot for a statistical series. - See also: 1/ quartiles + See also: 1/ quartiles Ex1:boxwhisker([-1,1,2,2.2,3,4,-2,5]) Ex2:boxwhisker([1,2,3,5,10,4],x=1..2) Ex3:boxwhisker([1,2,3,5,10,4],[1,2,3,1,2,3]) Ex4:boxwhisker([[6,0,1,3,4,2,5],[0,1,3,4,2,5,6],[1,3,4,2,5,6,0],[3,4,2,5,6,0,1],[4,2,5,6,0,1,3],[2,5,6,0,1,3,4]]) - ''' return GiacMethods['boxwhisker'](self,*args) @@ -1900,14 +1745,13 @@ cdef class GiacMethods_base: Help for brent_solver: brent_solver(Opt) Argument for fsolve giving the method for solving a numerical equation. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve(cos(x)=x,x,0..1,bisection_solver) Ex2: fsolve(cos(x)=x,x,0..1,brent_solver) Ex3: fsolve(cos(x)=x,x,0..1,falsepos_solver) Ex4: fsolve(cos(x)=x,x,0,newton_solver) Ex5: fsolve(cos(x)=x,x,0,secant_solver) Ex6: fsolve(cos(x)=x,x,0,steffenson_solver) - ''' return GiacMethods['brent_solver'](self,*args) @@ -1916,10 +1760,9 @@ cdef class GiacMethods_base: Help for bvpsolve: bvpsolve(Expr(f(x,y,y')),Lst(x=a..b,y),Lst(y(a),y(b),[y'(1)]),[options]) Returns an approximation of the function y (and optionally of y') on the interval a..b. - See also: 1/ odesolve + See also: 1/ odesolve Ex1:bvpsolve((32+2x^3-y*diff(y(x),x))/8,[x=1..3,y],[17,43/3],20) Ex2:bvpsolve((x^2*diff(y(x),x)^2-9y^2+4x^6)/x^5,[x=1..2,y],[0,ln(256),1],10,output=spline) - ''' return GiacMethods['bvpsolve'](self,*args) @@ -1928,11 +1771,10 @@ cdef class GiacMethods_base: Help for cFactor: cFactor(Expr) Factorization of the expression in ℂ (on the Gaussian integers if there are more than 2 variables). - See also: 1/ factor + See also: 1/ factor Ex1:cFactor(x^2*y+y) Ex2:cFactor(x^2*y^2+y^2+4*x^2+4) Ex3:cFactor(x^2*y^2+y^2+2*x^2+2) - ''' return GiacMethods['cFactor'](self,*args) @@ -1941,12 +1783,11 @@ cdef class GiacMethods_base: Help for cSolve: cSolve(LstEq,LstVar) Returns the list of complex solutions of an equation or a matrix where the rows are ℂ-solutions of a system of polynomial equations. - See also: 1/ cZeros 2/ solve 3/ fslove + See also: 1/ cZeros 2/ solve 3/ fslove Ex1:cSolve(x^4-1,x) Ex2:cSolve(x^4-y^4 and x+y=2,[x,y]) Ex3:cSolve(x^4-y^4 and x+y=0 and x^2=2*x,[x,y]) Ex4:cSolve(u*v-u=v and v^2=u,[u,v]) - ''' return GiacMethods['cSolve'](self,*args) @@ -1955,10 +1796,9 @@ cdef class GiacMethods_base: Help for cZeros: cZeros(Expr(Xpr)||LstExpr, [Var||LstVar]) Returns the list of complex solutions of Xpr=0 or the matrix where the rows are the solutions of the system : Xpr1=0,Xpr2=0... - See also: 1/ solve + See also: 1/ solve Ex1:cZeros(x^2-1) Ex2:cZeros([x^2-1,x^2-y^2],[x,y]) - ''' return GiacMethods['cZeros'](self,*args) @@ -1967,11 +1807,10 @@ cdef class GiacMethods_base: Help for camembert: camembert(Mtrx) Draws pie chart of a one variable statistical series. - See also: 1/ bar_plot + See also: 1/ bar_plot Ex1:camembert([["France",6],["Allemagne",12],["Suisse",5]]) Ex2:camembert([3/2,2/3,5/4,4/5,7/6,6/7,9/8,8/9,11/10]) Ex3:camembert([[2,"xyz","abc"],["A",2,5],["B",5,6],["C",7,7]]) - ''' return GiacMethods['camembert'](self,*args) @@ -1980,10 +1819,9 @@ cdef class GiacMethods_base: Help for canonical_form: canonical_form(Trinom(a*x^2+b*x+c),[Var]) Canonical_form of a 2nd degree polynomial. - See also: 1/ + See also: 1/ Ex1:canonical_form(2*x^2-12*x+1) Ex2:canonical_form(2*a^2-12*a+1,a) - ''' return GiacMethods['canonical_form'](self,*args) @@ -1992,9 +1830,8 @@ cdef class GiacMethods_base: Help for canonical_labeling: canonical_labeling(Graph(G)) Returns the permutation representing the canonical labeling of G. - See also: 1/ isomorphic_copy 2/ relabel_vertices + See also: 1/ isomorphic_copy 2/ relabel_vertices Ex1:canonical_labeling(graph("petersen")) - ''' return GiacMethods['canonical_labeling'](self,*args) @@ -2003,9 +1840,8 @@ cdef class GiacMethods_base: Help for cartesian_product: cartesian_product(Seq(G1,G2,..)) Returns the Cartesian product of graphs G1, G2, ... with vertices labelled as "u:v:..." where u, v, ... are vertices from G1, G2, ..., respectively. - See also: 1/ tensor_product + See also: 1/ tensor_product Ex1:cartesian_product(graph(trail(1,2,3,4,5,2)),star_graph(3)) - ''' return GiacMethods['cartesian_product'](self,*args) @@ -2014,9 +1850,8 @@ cdef class GiacMethods_base: Help for cauchy: cauchy(Real(x0),Real(a),Real(x)) Returns the density of probability at x of the Cauchy law with parameters x0 and a (by default x0=0 and a=1). - See also: 1/ cauchy_cdf 2/ cauchy_icdf + See also: 1/ cauchy_cdf 2/ cauchy_icdf Ex1:cauchy(0.0,2.0,1.0) - ''' return GiacMethods['cauchy'](self,*args) @@ -2025,10 +1860,9 @@ cdef class GiacMethods_base: Help for cauchy_cdf: cauchy_cdf(Real(x0),Real(a),Real(x),[Real(y)]) Returns the probability that a Cauchy random variable is less than x. - See also: 1/ cauchyd 2/ cauchy_icdf + See also: 1/ cauchyd 2/ cauchy_icdf Ex1:cauchy_cdf(0.0,2.0,2.1) Ex2:cauchy_cdf(2,3,-1.9,1.4) - ''' return GiacMethods['cauchy_cdf'](self,*args) @@ -2037,9 +1871,8 @@ cdef class GiacMethods_base: Help for cauchy_icdf: cauchy_icdf(Real(x0),Real(a),Real(p)) Returns h such that the probability that a Cauchy random variable is less than h is p (0<=p<=1). - See also: 1/ cauchy_cdf 2/ cauchy + See also: 1/ cauchy_cdf 2/ cauchy Ex1:cauchy_icdf(0.0,2.0,0.95) - ''' return GiacMethods['cauchy_icdf'](self,*args) @@ -2048,9 +1881,8 @@ cdef class GiacMethods_base: Help for cauchyd: cauchyd(Real(x0),Real(a),Real(x)) Returns the density of probability at x of the Cauchy law with parameters x0 and a (by default x0=0 and a=1). - See also: 1/ cauchy_cdf 2/ cauchy_icdf + See also: 1/ cauchy_cdf 2/ cauchy_icdf Ex1:cauchyd(0.0,2.0,1.0) - ''' return GiacMethods['cauchyd'](self,*args) @@ -2059,10 +1891,9 @@ cdef class GiacMethods_base: Help for cauchyd_cdf: cauchyd_cdf(Real(x0),Real(a),Real(x),[Real(y)]) Returns the probability that a Cauchy random variable is less than x. - See also: 1/ cauchyd 2/ cauchy_icdf + See also: 1/ cauchyd 2/ cauchy_icdf Ex1:cauchyd_cdf(0.0,2.0,2.1) Ex2:cauchyd_cdf(2,3,-1.9,1.4) - ''' return GiacMethods['cauchyd_cdf'](self,*args) @@ -2071,9 +1902,8 @@ cdef class GiacMethods_base: Help for cauchyd_icdf: cauchyd_icdf(Real(x0),Real(a),Real(p)) Returns h such that the probability that a Cauchy random variable is less than h is p (0<=p<=1). - See also: 1/ cauchy_cdf 2/ cauchy + See also: 1/ cauchy_cdf 2/ cauchy Ex1:cauchyd_icdf(0.0,2.0,0.95) - ''' return GiacMethods['cauchyd_icdf'](self,*args) @@ -2082,12 +1912,11 @@ cdef class GiacMethods_base: Help for cdf: cdf(Func,FuncParams) Cumulative distribution function. - See also: 1/ icdf 2/ binomial_cdf 3/ normald_cdf 4/ plotcdf + See also: 1/ icdf 2/ binomial_cdf 3/ normald_cdf 4/ plotcdf Ex1:cdf(binomial,10,0.5,4) Ex2:cdf(normald,0.0,1.0,2.0) Ex3:cdf([1,3,4,3,5,6],4) Ex4:cdf([1,3,4,3,5,6],plot) - ''' return GiacMethods['cdf'](self,*args) @@ -2096,10 +1925,9 @@ cdef class GiacMethods_base: Help for ceil: ceil(Real or Cplx) Returns the smallest integer >= to the argument. - See also: 1/ floor 2/ round + See also: 1/ floor 2/ round Ex1:ceil(-4.2) Ex2:ceil(4.3+2.4*i) - ''' return GiacMethods['ceil'](self,*args) @@ -2108,10 +1936,9 @@ cdef class GiacMethods_base: Help for ceiling: ceiling(Real or Cplx) Returns the smallest integer >= to the argument. - See also: 1/ floor 2/ round + See also: 1/ floor 2/ round Ex1:ceiling(-4.2) Ex2:ceiling(4.3+2.4*i) - ''' return GiacMethods['ceiling'](self,*args) @@ -2120,10 +1947,9 @@ cdef class GiacMethods_base: Help for center: center(Crcle) Shows the center of a circle. - See also: 1/ circle 2/ radius + See also: 1/ circle 2/ radius Ex1:center(circle(1+i,2)) Ex2:center(circumcircle(0,1,1+i)) - ''' return GiacMethods['center'](self,*args) @@ -2132,10 +1958,9 @@ cdef class GiacMethods_base: Help for center2interval: center2interval(LstVal(l),[Real(a0)]) Returns the list of intervals beginning with a0 and with l as centers. - See also: 1/ interval2center + See also: 1/ interval2center Ex1:center2interval([2,5,9],1) Ex2:center2interval([2,5,8]) - ''' return GiacMethods['center2interval'](self,*args) @@ -2144,10 +1969,9 @@ cdef class GiacMethods_base: Help for centered_cube: centered_cube(Pnt(A),Pnt(B),Pnt(C)) Draws the direct cube with center A, vertex B and such that the plane ABC contains an axis of symmetry of the cube. - See also: 1/ parallelepiped 2/ cube 3/ icosahedron 4/ dodecahedron 5/ octahedron 6/ centered_tetrahedron + See also: 1/ parallelepiped 2/ cube 3/ icosahedron 4/ dodecahedron 5/ octahedron 6/ centered_tetrahedron Ex1:centered_cube([0,0,0],[3,0,0],[0,0,1]) Ex2:centered_cube(evalf([0,0,0],[3,2,4],[1,1,0])) - ''' return GiacMethods['centered_cube'](self,*args) @@ -2156,10 +1980,9 @@ cdef class GiacMethods_base: Help for centered_tetrahedron: centered_tetrahedron(Pnt(A),Pnt(B),Pnt(C)) Draws the regular direct pyramid with center A, vertex B and a vertex in the plane (A,B,C). - See also: 1/ cube 2/ tetrahedron 3/ icosahedron 4/ dodecahedron 5/ octahedron + See also: 1/ cube 2/ tetrahedron 3/ icosahedron 4/ dodecahedron 5/ octahedron Ex1:centered_tetrahedron([0,0,0],[3,0,0],[0,1,0]) Ex2:centered_tetrahedron(evalf([0,0,0],[3,2,4],[1,1,0])) - ''' return GiacMethods['centered_tetrahedron'](self,*args) @@ -2168,11 +1991,10 @@ cdef class GiacMethods_base: Help for cfactor: cfactor(Expr) Factorization of the expression in ℂ (on the Gaussian integers if there are more than 2 variables). - See also: 1/ factor + See also: 1/ factor Ex1:cfactor(x^2*y+y) Ex2:cfactor(x^2*y^2+y^2+4*x^2+4) Ex3:cfactor(x^2*y^2+y^2+2*x^2+2) - ''' return GiacMethods['cfactor'](self,*args) @@ -2181,10 +2003,9 @@ cdef class GiacMethods_base: Help for cfsolve: cfsolve(Expr,Var,[Guess or Interval],[Method]) Numerical solution of an equation or a system of equations on ℂ. - See also: 1/ fsolve 2/ nSolve 3/ csolve 4/ solve + See also: 1/ fsolve 2/ nSolve 3/ csolve 4/ solve Ex1:cfsolve(cos(x)=2) Ex2:cfsolve([x^2+y+2,x+y^2+2],[x,y]) - ''' return GiacMethods['cfsolve'](self,*args) @@ -2193,10 +2014,9 @@ cdef class GiacMethods_base: Help for changebase: changebase(Mtrx(A),Mtrx(P)) Returns the matrix B=inv(P)*A*P. - See also: 1/ + See also: 1/ Ex1:changebase([[1,2],[1,3]],[[1,1],[0,1]]) Ex2:changebase([[1,2],[1,3]],[[1,0],[1,1]]) - ''' return GiacMethods['changebase'](self,*args) @@ -2205,12 +2025,11 @@ cdef class GiacMethods_base: Help for channel_data: channel_data(Lst(clip),[Intg(chn) or matrix],[range=a..b]) Extracts the data from an audio clip (optionally specifying the channel and range). - See also: 1/ bit_depth 2/ channels 3/ duration 4/ samplerate + See also: 1/ bit_depth 2/ channels 3/ duration 4/ samplerate Ex1:channel_data(readwav("/some/file")) Ex2:channel_data(readwav("/some/file"),matrix) Ex3:channel_data(readwav("/some/file"),2) Ex4:channel_data(readwav("/some/file"),matrix,range=1.0..2.5) - ''' return GiacMethods['channel_data'](self,*args) @@ -2219,9 +2038,8 @@ cdef class GiacMethods_base: Help for channels: channels(Lst(clip)) Returns the number of channels in audio clip. - See also: 1/ bit_depth 2/ channel_data 3/ duration 4/ samplerate + See also: 1/ bit_depth 2/ channel_data 3/ duration 4/ samplerate Ex1:channels(readwav("/some/file")) - ''' return GiacMethods['channels'](self,*args) @@ -2230,10 +2048,9 @@ cdef class GiacMethods_base: Help for char: char(Intg or Lst(Intg)) Returns the string corresponding to the character code of the argument. - See also: 1/ asc 2/ ord + See also: 1/ asc 2/ ord Ex1:char(65) Ex2:char([65,66,67]) - ''' return GiacMethods['char'](self,*args) @@ -2242,12 +2059,11 @@ cdef class GiacMethods_base: Help for charpoly: charpoly(Mtrx,[Var]) List of the coefficients of the characteristic polynomial of a matrix or characteristic polynomial of a matrix with the second argument as variable. - See also: 1/ jordan 2/ egv 3/ egvl 4/ companion 5/ rat_jordan 6/ pmin 7/ adjoint_matrix + See also: 1/ jordan 2/ egv 3/ egvl 4/ companion 5/ rat_jordan 6/ pmin 7/ adjoint_matrix Ex1:charpoly([[1,2],[3,4]]) Ex2:charpoly([[1,2],[3,4]],x) Ex3:charpoly([[1,2,3],[1,3,6],[2,5,7]]) Ex4:charpoly([[1,2,3],[1,3,6],[2,5,7]],z) - ''' return GiacMethods['charpoly'](self,*args) @@ -2256,10 +2072,9 @@ cdef class GiacMethods_base: Help for chinrem: chinrem([Lst||Expr,Lst||Expr],[Lst||Expr,Lst||Expr]) Chinese remainder for polynomials written as lists or no. - See also: 1/ ichinrem + See also: 1/ ichinrem Ex1:chinrem([x+2,x^2+1],[x+1,x^2+x+1]) Ex2:chinrem([[1,2],[1,0,1]],[[1,1],[1,1,1]]) - ''' return GiacMethods['chinrem'](self,*args) @@ -2268,12 +2083,11 @@ cdef class GiacMethods_base: Help for chisquare: chisquare(Intg(n),Real(x0)) Returns the probability density of the Chi^2 law at x0 (n is the number of degrees of freedom). - See also: 1/ chisquare_cdf 2/ chisquare_icdf 3/ randvector 4/ ranm + See also: 1/ chisquare_cdf 2/ chisquare_icdf 3/ randvector 4/ ranm Ex1:chisquare(2,3.2) Ex2:chisquare(4,10.5) Ex3: randvector(3,chisquare,2) Ex4: ranm(4,3,chisquare,2) - ''' return GiacMethods['chisquare'](self,*args) @@ -2282,10 +2096,9 @@ cdef class GiacMethods_base: Help for chisquare_cdf: chisquare_cdf(Intg(n),Real(x0)) Returns the probability that a Chi^2 random variable is less than x0 (n is the number of degrees of freedom). - See also: 1/ UTPC 2/ chisquare_icdf 3/ chisquared + See also: 1/ UTPC 2/ chisquare_icdf 3/ chisquared Ex1:chisquare_cdf(2,6.1) Ex2:chisquare_cdf(4,6.1) - ''' return GiacMethods['chisquare_cdf'](self,*args) @@ -2294,10 +2107,9 @@ cdef class GiacMethods_base: Help for chisquare_icdf: chisquare_icdf(Intg(n),Real(p)) Returns h such as the probability that a Chi^2 random variable is less than h is p (n is the number of degrees of freedom and 0<=p<=1). - See also: 1/ chisquare_cdf 2/ chisquared + See also: 1/ chisquare_cdf 2/ chisquared Ex1:chisquare_icdf(2,0.95) Ex2:chisquare_icdf(4,0.05) - ''' return GiacMethods['chisquare_icdf'](self,*args) @@ -2306,12 +2118,11 @@ cdef class GiacMethods_base: Help for chisquared: chisquared(Intg(n),Real(x0)) Returns the probability density of the Chi^2 law at x0 (n is the number of degrees of freedom). - See also: 1/ chisquare_cdf 2/ chisquare_icdf 3/ randvector 4/ ranm + See also: 1/ chisquare_cdf 2/ chisquare_icdf 3/ randvector 4/ ranm Ex1:chisquared(2,3.2) Ex2:chisquared(4,10.5) Ex3: randvector(3,chisquare,2) Ex4: ranm(4,3,chisquare,2) - ''' return GiacMethods['chisquared'](self,*args) @@ -2320,10 +2131,9 @@ cdef class GiacMethods_base: Help for chisquared_cdf: chisquared_cdf(Intg(n),Real(x0)) Returns the probability that a Chi^2 random variable is less than x0 (n is the number of degrees of freedom). - See also: 1/ UTPC 2/ chisquare_icdf 3/ chisquared + See also: 1/ UTPC 2/ chisquare_icdf 3/ chisquared Ex1:chisquared_cdf(2,6.1) Ex2:chisquared_cdf(4,6.1) - ''' return GiacMethods['chisquared_cdf'](self,*args) @@ -2332,10 +2142,9 @@ cdef class GiacMethods_base: Help for chisquared_icdf: chisquared_icdf(Intg(n),Real(p)) Returns h such as the probability that a Chi^2 random variable is less than h is p (n is the number of degrees of freedom and 0<=p<=1). - See also: 1/ chisquare_cdf 2/ chisquared + See also: 1/ chisquare_cdf 2/ chisquared Ex1:chisquared_icdf(2,0.95) Ex2:chisquared_icdf(4,0.05) - ''' return GiacMethods['chisquared_icdf'](self,*args) @@ -2344,7 +2153,7 @@ cdef class GiacMethods_base: Help for chisquaret: chisquaret(Data,[Func],[FuncParams]) Chi^2 test : fitness between 2 (or n) samples or between 1 sample and a distribution law (multinomial or given by a law). - See also: 1/ normalt 2/ studentt 3/ kolmogorovt + See also: 1/ normalt 2/ studentt 3/ kolmogorovt Ex1:chisquaret([57,54]) Ex2:chisquaret([1,1,1,1,1,0,0,1,0,0,1,1,1,0,1,1,0,1,1,0,0,0,0],[.4,.6]) Ex3:chisquaret([57,30],[.6,.4]) @@ -2354,7 +2163,6 @@ cdef class GiacMethods_base: Ex7:chisquaret(ranv(1000,normald,0,.2),normald) Ex8:chisquaret([11,16,17,22,14,10],[1/6,1/6,1/6,1/6,1/6,1/6]) Ex9:chisquaret([11,16,17,22,14,10],[(1/6)$6]) - ''' return GiacMethods['chisquaret'](self,*args) @@ -2363,12 +2171,11 @@ cdef class GiacMethods_base: Help for choice: choice(Lst(L)) choice(L)=rand(L)=one extracted element of L. - See also: 1/ rand 2/ sample + See also: 1/ rand 2/ sample Ex1:choice([1,2,3,4,5,6]) Ex2:choice(["r","r","r","b","n"]) Ex3: L:=[1,2,3,4,5,6];L:=choice(L) Ex4: L:=[1,2,3,4,5,6];L.choice() - ''' return GiacMethods['choice'](self,*args) @@ -2377,9 +2184,8 @@ cdef class GiacMethods_base: Help for cholesky: cholesky(Mtrx) For a numerical symmetric matrix A, returns L matrix such that A=L*tran(L). - See also: 1/ lu 2/ qr 3/ gauss + See also: 1/ lu 2/ qr 3/ gauss Ex1:cholesky([[3,1],[1,4]]) - ''' return GiacMethods['cholesky'](self,*args) @@ -2388,10 +2194,9 @@ cdef class GiacMethods_base: Help for chr: chr(Intg or Lst(Intg)) Returns the string corresponding to the character code of the argument. - See also: 1/ asc 2/ ord + See also: 1/ asc 2/ ord Ex1:chr(65) Ex2:chr([65,66,67]) - ''' return GiacMethods['chr'](self,*args) @@ -2400,13 +2205,12 @@ cdef class GiacMethods_base: Help for chrem: chrem(LstIntg(a,b,c....),LstIntg(p,q,r,....)) Chinese remainders for integers or for polynomials. - See also: 1/ gcd 2/ fracmod 3/ chinrem 4/ ichinrem + See also: 1/ gcd 2/ fracmod 3/ chinrem 4/ ichinrem Ex1:chrem(symbolique.) Ex2:chrem([2,3],[7,5]) Ex3:chrem([2,4,6],[3,5,7]) Ex4:chrem([2,4,6,7],[3,5,7,11]) Ex5:chrem([2*x+1,4*x+2,6*x-1,x+1],[3,5,7,11]) - ''' return GiacMethods['chrem'](self,*args) @@ -2415,10 +2219,9 @@ cdef class GiacMethods_base: Help for chromatic_index: chromatic_index(Graph(G),[Lst(cols)]) Returns the number of colors in the minimal edge coloring of G. If an unassigned identifier cols is given, the coloring is stored to it. - See also: 1/ minimal_edge_coloring 2/ chromatic_number + See also: 1/ minimal_edge_coloring 2/ chromatic_number Ex1:chromatic_index(graph("petersen")) Ex2:chromatic_index(graph("dodecahedron"),colors) - ''' return GiacMethods['chromatic_index'](self,*args) @@ -2428,7 +2231,6 @@ cdef class GiacMethods_base: chromatic_number(Graph(G)) Returns the chromatic number of G. Ex1:chromatic_number(graph("petersen")) - ''' return GiacMethods['chromatic_number'](self,*args) @@ -2437,10 +2239,9 @@ cdef class GiacMethods_base: Help for chromatic_polynomial: chromatic_polynomial(Graph(G),[Var(t)]) Returns the chromatic polynomial [or its value at point t] of undirected unweighted graph G. - See also: 1/ flow_polynomial 2/ reliability_polynomial 3/ tutte_polynomial + See also: 1/ flow_polynomial 2/ reliability_polynomial 3/ tutte_polynomial Ex1:chromatic_polynomial(graph("petersen")) Ex2:chromatic_polynomial(graph("petersen"),3) - ''' return GiacMethods['chromatic_polynomial'](self,*args) @@ -2449,7 +2250,7 @@ cdef class GiacMethods_base: Help for circle: circle((Pnt(M) or Cplx(M),(Pnt(N) or Cplx(zN)),[Real(a)],[Real(b)],[Var(A)],[Var(B)]) Define for 2-d a circle with a diameter MN (arg1=M or zM,arg2=N) or with center and radius (arg1=M or zM,arg2=zN) and (center=M and radius=abs(zN)) [or the arc AB, A angle a, B angle b, (MN=angle 0) or M(M+zN)=angle 0] or by its equation and for 3-d with a diameter and a third point. - See also: 1/ circumcircle 2/ incircle 3/ excircle 4/ center 5/ radius 6/ sphere 7/ Circle + See also: 1/ circumcircle 2/ incircle 3/ excircle 4/ center 5/ radius 6/ sphere 7/ Circle Ex1:circle(0,point(2*i)) Ex2:circle(i,i) Ex3:circle(i,1) @@ -2458,7 +2259,6 @@ cdef class GiacMethods_base: Ex6:circle(x^2+y^2-x-y) Ex7:circle(cercle(point([-1,0,0]),point([1,0,0]),point([0,2,0]))) Ex8:circle(cercle([-1,0,0],point([1,0,0]),[0,2,0])) - ''' return GiacMethods['circle'](self,*args) @@ -2467,9 +2267,8 @@ cdef class GiacMethods_base: Help for circumcircle: circumcircle((Pnt or Cplx),(Pnt or Cplx),((Pnt or Cplx)) circumcircle(A,B,C)=circumcircle of the triangle ABC. - See also: 1/ circle 2/ incircle 3/ excircle + See also: 1/ circle 2/ incircle 3/ excircle Ex1:circumcircle(0,1,1+i) - ''' return GiacMethods['circumcircle'](self,*args) @@ -2478,13 +2277,12 @@ cdef class GiacMethods_base: Help for classes: classes(Lst(l),[ClassMin],[ClassSize||Lst(Center)]) Returns the matrix [[class,number],...] obtained with class_min and class_size: see init of geo or argument 2 and 3 or with the list of centers. - See also: 1/ histogram 2/ cumulated_frequencies 3/ bar_plot 4/ frequencies + See also: 1/ histogram 2/ cumulated_frequencies 3/ bar_plot 4/ frequencies Ex1:classes([1,1.2,1.4,1.6,1.8,2,2.5]) Ex2:classes([1,1.2,1.4,1.6,1.8,2,2.5],1.2,0.5) Ex3:classes([1,1.2,1.4,1.6,1.8,2,2.5],1,[1.2,1.6,2,2.4]) Ex4:classes([1,1.2,1.4,1.6,1.8,2,2.5],1,[1.2,1.6,2.2]) Ex5:classes([0,0.5,1,1.5,2,2.5,3,3.5,4],[0..2,2..4,4..6]) - ''' return GiacMethods['classes'](self,*args) @@ -2493,9 +2291,8 @@ cdef class GiacMethods_base: Help for clear: clear(NULL) Clears the list of pixels. - See also: 1/ set_pixel 2/ show_pixels + See also: 1/ set_pixel 2/ show_pixels Ex1:clear() - ''' return GiacMethods['clear'](self,*args) @@ -2504,11 +2301,10 @@ cdef class GiacMethods_base: Help for clique_cover: clique_cover(Graph(G),[Intg(k)]) Returns a clique vertex cover of G [containing at most k cliques]. - See also: 1/ clique_cover_number 2/ maximal_cliques + See also: 1/ clique_cover_number 2/ maximal_cliques Ex1:clique_cover(graph("petersen")) Ex2:clique_cover(cycle_graph(5)) Ex3:clique_cover(graph_complement(complete_graph(3,4))) - ''' return GiacMethods['clique_cover'](self,*args) @@ -2517,11 +2313,10 @@ cdef class GiacMethods_base: Help for clique_cover_number: clique_cover_number(Graph(G)) Returns the clique cover number of G. - See also: 1/ clique_cover 3/ maximal_cliques + See also: 1/ clique_cover 3/ maximal_cliques Ex1:clique_cover_number(graph("petersen")) Ex2:clique_cover_number(cycle_graph(5)) Ex3:clique_cover_number(graph_complement(complete_graph(3,4))) - ''' return GiacMethods['clique_cover_number'](self,*args) @@ -2530,9 +2325,8 @@ cdef class GiacMethods_base: Help for clique_number: clique_number(Graph(G)) Returns the clique number of G, which is equal to the size of a maximum clique in G. - See also: 1/ maximum_clique + See also: 1/ maximum_clique Ex1:clique_number(graph_complement(complete_graph(3,4))) - ''' return GiacMethods['clique_number'](self,*args) @@ -2541,11 +2335,10 @@ cdef class GiacMethods_base: Help for clique_stats: clique_stats(Graph(G),[Intg(k)||Intrv(m..n)]) Returns the list of numbers of maximal cliques of size s in G for each s. If parameter k is given, the number of k-cliques is returned. If an interval m..n is given, only cliques with size between m and n (inclusive) are counted (m also may be +infinity). - See also: 1/ maximum_clique 2/ clique_cover + See also: 1/ maximum_clique 2/ clique_cover Ex1:clique_stats(random_graph(50,0.5)) Ex2:clique_stats(random_graph(50,0.5),5) Ex3:clique_stats(random_graph(50,0.5),3..5) - ''' return GiacMethods['clique_stats'](self,*args) @@ -2554,10 +2347,9 @@ cdef class GiacMethods_base: Help for clustering_coefficient: clustering_coefficient(Graph(G),[Vrtx(v)]) Returns the average clustering coefficient of undirected graph G, or the local clustering coefficient of the vertex v in G. - See also: 1/ network_transitivity 2/ number_of_triangles + See also: 1/ network_transitivity 2/ number_of_triangles Ex1:clustering_coefficient(graph(%{[1,2],[2,3],[2,4],[3,4],[4,1]%})) Ex2:clustering_coefficient(graph(%{[1,2],[2,3],[2,4],[3,4],[4,1]%}),2) - ''' return GiacMethods['clustering_coefficient'](self,*args) @@ -2566,11 +2358,10 @@ cdef class GiacMethods_base: Help for coeff: coeff(Expr(P),[Var]) Returns the list of coefficients of a polynomial with respect to the 2nd argument or the coefficient of degree the 3rd argument. - See also: 1/ pcoeff 2/ fcoeff + See also: 1/ pcoeff 2/ fcoeff Ex1:coeff(x*3+2) Ex2:coeff(5*y^2-3,y) Ex3:coeff(5*y^2-3,y,2) - ''' return GiacMethods['coeff'](self,*args) @@ -2579,11 +2370,10 @@ cdef class GiacMethods_base: Help for coeffs: coeffs(Expr(P),[Var]) Returns the list of coefficients of a polynomial with respect to the 2nd argument or the coefficient of degree the 3rd argument. - See also: 1/ pcoeff 2/ fcoeff + See also: 1/ pcoeff 2/ fcoeff Ex1:coeffs(x*3+2) Ex2:coeffs(5*y^2-3,y) Ex3:coeffs(5*y^2-3,y,2) - ''' return GiacMethods['coeffs'](self,*args) @@ -2592,11 +2382,10 @@ cdef class GiacMethods_base: Help for col: col(Mtrx(A),Intg(n)||Interval(n1..n2)) Returns column n or the sequence of the columns n1..n2 of the matrix A, or optional argument of count,count_eq,count_inf,count_sup. - See also: 1/ row 2/ count 3/ count_eq 4/ count_inf 5/ count_sup + See also: 1/ row 2/ count 3/ count_eq 4/ count_inf 5/ count_sup Ex1:col([[1,2,3],[4,5,6],[7,8,9]],1) Ex2:col([[1,2,3],[4,5,6],[7,8,9]],0..1) Ex3: count_eq(3,[[3,2,3],[4,3,2],[3,2,1]],col) - ''' return GiacMethods['col'](self,*args) @@ -2605,10 +2394,9 @@ cdef class GiacMethods_base: Help for colDim: colDim(Mtrx) Number of columns of a matrix. - See also: 1/ rowdim + See also: 1/ rowdim Ex1:colDim([[1,2,3],[4,5,6]]) Ex2:colDim([[1,2],[3,4],[5,6]]) - ''' return GiacMethods['colDim'](self,*args) @@ -2617,10 +2405,9 @@ cdef class GiacMethods_base: Help for colNorm: colNorm(Vect or Mtrx) Returns the max of the l1_norm of the columns of a matrix: colNorm(a_{j,k})=max_k(sum_j(|a_{j,k}|)). - See also: 1/ norm + See also: 1/ norm Ex1:colNorm([[1,2],[3,-4]]) Ex2:colNorm([[1,2,3,-4],[-5,3,2,1]]) - ''' return GiacMethods['colNorm'](self,*args) @@ -2629,9 +2416,8 @@ cdef class GiacMethods_base: Help for colSwap: colSwap(Mtrx(A),Intg(n1),Intg(n2)) Returns the matrix obtained from A by swapping the n1-th column and the n2-th column. - See also: 1/ rowSwap + See also: 1/ rowSwap Ex1:colSwap([[1,2],[3,4],[5,6]],0,1) - ''' return GiacMethods['colSwap'](self,*args) @@ -2640,10 +2426,9 @@ cdef class GiacMethods_base: Help for coldim: coldim(Mtrx) Number of columns of a matrix. - See also: 1/ rowdim + See also: 1/ rowdim Ex1:coldim([[1,2,3],[4,5,6]]) Ex2:coldim([[1,2],[3,4],[5,6]]) - ''' return GiacMethods['coldim'](self,*args) @@ -2652,11 +2437,10 @@ cdef class GiacMethods_base: Help for collect: collect(Poly or LstPoly) Integer factorization of a polynomial (or of a list of poly). - See also: 1/ factor 2/ factors + See also: 1/ factor 2/ factors Ex1:collect(x^2-4) Ex2:collect(x^2-2) Ex3:collect([x^2-2,x^2-4]) - ''' return GiacMethods['collect'](self,*args) @@ -2665,10 +2449,9 @@ cdef class GiacMethods_base: Help for colnorm: colnorm(Vect or Mtrx) Returns the max of the l1_norm of the columns of a matrix: colNorm(a_{j,k})=max_k(sum_j(|a_{j,k}|)). - See also: 1/ norm + See also: 1/ norm Ex1:colnorm([[1,2],[3,-4]]) Ex2:colnorm([[1,2,3,-4],[-5,3,2,1]]) - ''' return GiacMethods['colnorm'](self,*args) @@ -2677,7 +2460,7 @@ cdef class GiacMethods_base: Help for color: color([GeoObj or legende],Intg) Draws a geometrical object with colors black=0 red=1 green=2 yellow=3 blue=4, filled with the color in the interior of a closed curve,line_width_n (00 (by default a=1 for sine window) to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ bartlett_hann_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ bartlett_hann_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(cosine_window(randvector(1000,0..1),1.5)) - ''' return GiacMethods['cosine_window'](self,*args) @@ -3260,9 +2999,8 @@ cdef class GiacMethods_base: Help for cot: cot(Expr) Cotangent. - See also: 1/ acot 2/ tan + See also: 1/ acot 2/ tan Ex1:cot(pi/2) - ''' return GiacMethods['cot'](self,*args) @@ -3271,10 +3009,9 @@ cdef class GiacMethods_base: Help for cote: cote(Vect) Third coordinate (z) of a 3-d point. - See also: 1/ abscissa 2/ ordinate 3/ coordinates + See also: 1/ abscissa 2/ ordinate 3/ coordinates Ex1:cote(point[1,2,3]) Ex2:cote(point(1,2,3)) - ''' return GiacMethods['cote'](self,*args) @@ -3283,7 +3020,7 @@ cdef class GiacMethods_base: Help for count: count(Fnc(f)||LstIntg,(Lst||Mtrx)(l),[Opt(row||col)]) Returns f(l[0])+f(l[1])+...+f(l[size(l)-1]) or counts the number of occurrences if the argument is a vector of integers. - See also: 1/ count_eq 2/ count_inf 3/ count_sup + See also: 1/ count_eq 2/ count_inf 3/ count_sup Ex1:count(id,[-2/5,-1,0,1,2,3/5]) Ex2:count(1,[-2,-1,0,1,2,3]) Ex3:count([1,3,1,1,2,10,3]) @@ -3294,7 +3031,6 @@ cdef class GiacMethods_base: Ex8:count((x)->x>2,[[3,5/2],[4,1]],col) Ex9:count((x)->x>2 && x<4,[[3,9/2],[4,1]]) Ex10:count((x)->x<2 || x>4,[[3,9/2],[4,1]]) - ''' return GiacMethods['count'](self,*args) @@ -3303,12 +3039,11 @@ cdef class GiacMethods_base: Help for count_eq: count_eq(Real(a),(Lst||Mtrx)(L),[Opt(row||col)]) Returns the number of elements of L equal to a. - See also: 1/ count 2/ count_inf 3/ count_sup + See also: 1/ count 2/ count_inf 3/ count_sup Ex1:count_eq(1,[-2,1,0,1,2,-3]) Ex2:count_eq(4,[[3,4],[4,1]]) Ex3:count_eq(4,[[3,4],[4,1]],row) Ex4:count_eq(4,[[3,4],[4,1]],col) - ''' return GiacMethods['count_eq'](self,*args) @@ -3317,12 +3052,11 @@ cdef class GiacMethods_base: Help for count_inf: count_inf(Real(a),(Lst||Mtrx)(L),[Opt(row||col)]) Returns the number of elements of L strictly less than a. - See also: 1/ count 2/ count_eq 3/ count_sup + See also: 1/ count 2/ count_eq 3/ count_sup Ex1:count_inf(1,[-2,-1,0,1,2,3]) Ex2:count_inf(4,[[3,5],[4,1]]) Ex3:count_inf(4,[[3,5],[4,1]],row) Ex4:count_inf(4,[[3,5],[4,1]],col) - ''' return GiacMethods['count_inf'](self,*args) @@ -3331,12 +3065,11 @@ cdef class GiacMethods_base: Help for count_sup: count_sup(Real(a),(Lst||Mtrx)(L),[Opt(row||col)]) Returns the number of elements of L strictly greater than a. - See also: 1/ count 2/ count_inf 3/ count_eq + See also: 1/ count 2/ count_inf 3/ count_eq Ex1:count_sup(1,[-2,-1,0,1,2,3]) Ex2:count_sup(3,[[3,5],[4,1]]) Ex3:count_sup(3,[[3,5],[4,1]],row) Ex4:count_sup(3,[[3,5],[4,1]],col) - ''' return GiacMethods['count_sup'](self,*args) @@ -3345,7 +3078,7 @@ cdef class GiacMethods_base: Help for courbe_parametrique: courbe_parametrique(Cplx||Lst,Var||Lst(Var)) plotparam(a(x)+i*b(x),x=x0..x1) draws the curve X=a(x),Y=b(x) x=x0..x1 or plotparam([a(u,v),b(u,v),c(u,v)],[u=u0..u1,v=v0..v1]) draws the surface X=a(u,v),Y=b(u,v),Z=c(u,v) u=u0..u1 and v=v0..v1. - See also: 1/ plotfunc 2/ plotpolar 3/ arc + See also: 1/ plotfunc 2/ plotpolar 3/ arc Ex1:courbe_parametrique(sin(t)+i*cos(t),t) Ex2:courbe_parametrique(exp(i*t),t=0..pi/2,affichage=1) Ex3:courbe_parametrique(exp(i*t),t=0..pi/2,affichage=1+rempli) @@ -3354,7 +3087,6 @@ cdef class GiacMethods_base: Ex6:courbe_parametrique(sin(x)+i*cos(x),x=0..1,tstep=0.01) Ex7:courbe_parametrique([v*cos(u),v*sin(u),v],[u,v]) Ex8:courbe_parametrique([v*cos(u),v*sin(u),v],[u=0..pi,v=0..3],ustep=0.1,vstep=0.2) - ''' return GiacMethods['courbe_parametrique'](self,*args) @@ -3363,10 +3095,9 @@ cdef class GiacMethods_base: Help for courbe_polaire: courbe_polaire(Expr,Var,VarMin,VarMax) plotpolar(f(x),x,a,b) draws the polar curve r=f(x) for x in [a,b]. - See also: 1/ plotparam 2/ plotfunc 3/ plotpolar + See also: 1/ plotparam 2/ plotfunc 3/ plotpolar Ex1:courbe_polaire(sin(2*x),x,0,pi) Ex2:courbe_polaire(sin(2*x),x,0,pi,tstep=0.1) - ''' return GiacMethods['courbe_polaire'](self,*args) @@ -3375,9 +3106,8 @@ cdef class GiacMethods_base: Help for covariance: covariance(Lst||Mtrx,[Lst]) Returns the covariance of the elements of its argument. - See also: 1/ correlation 2/ covariance_correlation + See also: 1/ correlation 2/ covariance_correlation Ex1:covariance([[1,2],[1,1],[4,7]]) - ''' return GiacMethods['covariance'](self,*args) @@ -3386,9 +3116,8 @@ cdef class GiacMethods_base: Help for covariance_correlation: covariance_correlation(Lst||Mtrx,[Lst]) Returns the list of the covariance and the correlation of the elements of its argument. - See also: 1/ covariance 2/ correlation + See also: 1/ covariance 2/ correlation Ex1:covariance_correlation([[1,2],[1,1],[4,7]]) - ''' return GiacMethods['covariance_correlation'](self,*args) @@ -3397,11 +3126,10 @@ cdef class GiacMethods_base: Help for cpartfrac: cpartfrac(RatFrac) Performs partial fraction decomposition in ℂ of a fraction. - See also: 1/ factor 2/ normal + See also: 1/ factor 2/ normal Ex1:cpartfrac((x)/(4-x^2)) Ex2:cpartfrac((x^2-2*x+3)/(x^2-3*x+2)) Ex3:cpartfrac(a/(z*(z-b)),z) - ''' return GiacMethods['cpartfrac'](self,*args) @@ -3410,9 +3138,8 @@ cdef class GiacMethods_base: Help for crationalroot: crationalroot(Poly(P)) Returns the list of complex rational roots of P without indicating the multiplicity. - See also: 1/ proot 2/ froot 3/ complexroot 4/ rationalroot 5/ realroot + See also: 1/ proot 2/ froot 3/ complexroot 4/ rationalroot 5/ realroot Ex1:crationalroot(2*x^3+(-5-7*i)*x^2+(-4+14*i)*x+8-4*i) - ''' return GiacMethods['crationalroot'](self,*args) @@ -3421,12 +3148,11 @@ cdef class GiacMethods_base: Help for crayon: crayon(Color) Changes the color of the pencil (without parameter, returns the current color). - See also: 1/ leve_crayon 2/ baisse_crayon + See also: 1/ leve_crayon 2/ baisse_crayon Ex1: crayon vert Ex2:crayon(rouge) Ex3:crayon(5) Ex4:crayon(gomme) - ''' return GiacMethods['crayon'](self,*args) @@ -3435,13 +3161,12 @@ cdef class GiacMethods_base: Help for createwav: createwav(Lst(data),[opts]) Returns an audio clip from data, optionally setting channel count, bit depth, sample rate, duration and normalization level. - See also: 1/ readwav 2/ writewav 3/ playsnd + See also: 1/ readwav 2/ writewav 3/ playsnd Ex1:createwav(duration=3.5) Ex2:createwav(sin(2*pi*440*soundsec(2)),samplerate=48000) Ex3:createwav(sin(2*pi*440*soundsec(2)),bit_depth=8) Ex4:createwav(10*sin(2*pi*440*soundsec(2)),normalize=-3) Ex5: t:=soundsec(3):;L,R:=sin(2*pi*440*t),sin(2*pi*445*t):;createwav([L,R]) - ''' return GiacMethods['createwav'](self,*args) @@ -3450,10 +3175,9 @@ cdef class GiacMethods_base: Help for cross: cross(Vect(v1),Vect(v2)) Wedge product. - See also: 1/ dot + See also: 1/ dot Ex1:cross([1,2],[3,4]) Ex2:cross([1,2,3],[4,5,6]) - ''' return GiacMethods['cross'](self,*args) @@ -3462,10 +3186,9 @@ cdef class GiacMethods_base: Help for crossP: crossP(Vect(v1),Vect(v2)) Wedge product. - See also: 1/ dot + See also: 1/ dot Ex1:crossP([1,2],[3,4]) Ex2:crossP([1,2,3],[4,5,6]) - ''' return GiacMethods['crossP'](self,*args) @@ -3474,9 +3197,8 @@ cdef class GiacMethods_base: Help for cross_correlation: cross_correlation(cross_correlation(Lst(u),Lst(v))) Returns the cross_correlation of two signals u and v. - See also: 1/ auto_correlation 2/ correlation + See also: 1/ auto_correlation 2/ correlation Ex1:cross_correlation([1,2],[3,4,5]) - ''' return GiacMethods['cross_correlation'](self,*args) @@ -3485,10 +3207,9 @@ cdef class GiacMethods_base: Help for cross_point: cross_point(Opt) Option of the display command for a point. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),point_point) Ex2: F:=display(point(2+1.5*i),rhombus_point) - ''' return GiacMethods['cross_point'](self,*args) @@ -3497,11 +3218,10 @@ cdef class GiacMethods_base: Help for cross_ratio: cross_ratio(Pnt or Cplx(a),Pnt or Cplx(b),Pnt or Cplx(c),Pnt or Cplx(d)) Returns the complex number equal to ((c-a)/(c-b))/((d-a)/(d-b)). - See also: 1/ harmonic_conjugate 2/ is_conjugate + See also: 1/ harmonic_conjugate 2/ is_conjugate Ex1:cross_ratio(i,2+i,3/2+i,3+i) Ex2:cross_ratio(0,1+i,1,i) Ex3:cross_ratio(0,1,2,3) - ''' return GiacMethods['cross_ratio'](self,*args) @@ -3510,10 +3230,9 @@ cdef class GiacMethods_base: Help for crossproduct: crossproduct(Vect(v1),Vect(v2)) Wedge product. - See also: 1/ dot + See also: 1/ dot Ex1:crossproduct([1,2],[3,4]) Ex2:crossproduct([1,2,3],[4,5,6]) - ''' return GiacMethods['crossproduct'](self,*args) @@ -3522,9 +3241,8 @@ cdef class GiacMethods_base: Help for csc: csc(Expr) Cosecant: csc(x)=1/sin(x). - See also: 1/ sin 2/ acsc + See also: 1/ sin 2/ acsc Ex1:csc(pi/2) - ''' return GiacMethods['csc'](self,*args) @@ -3533,12 +3251,11 @@ cdef class GiacMethods_base: Help for csolve: csolve(LstEq,LstVar) Returns the list of complex solutions of an equation or a matrix where the rows are ℂ-solutions of a system of polynomial equations. - See also: 1/ cZeros 2/ solve 3/ fslove + See also: 1/ cZeros 2/ solve 3/ fslove Ex1:csolve(x^4-1,x) Ex2:csolve(x^4-y^4 and x+y=2,[x,y]) Ex3:csolve(x^4-y^4 and x+y=0 and x^2=2*x,[x,y]) Ex4:csolve(u*v-u=v and v^2=u,[u,v]) - ''' return GiacMethods['csolve'](self,*args) @@ -3547,9 +3264,8 @@ cdef class GiacMethods_base: Help for csv2gen: csv2gen(Strng(filename),Strng(sep),Strng(nl),Strng(decsep),Strng(eof),[string]) Reads a file (or string) in CSV format. - See also: 1/ read + See also: 1/ read Ex1:csv2gen("mat.txt",",",char(10),".") - ''' return GiacMethods['csv2gen'](self,*args) @@ -3558,13 +3274,12 @@ cdef class GiacMethods_base: Help for cube: cube(Pnt(A),Pnt(B),Pnt(C)) Draws the direct cube with vertices A,B with a face in the plane (A,B,C). - See also: 1/ parallelepiped 2/ cylinder 3/ icosahedron 4/ dodecahedron 5/ octahedron 6/ tetrahedron 7/ centered_cube - Ex1:cube([0,0,0],[3,0,0],[0,0,1]) - Ex2: A,B,C:=point(1,0,0),point(1,1,0),point(0,1,0);c:=cube(A,B,C);A,B,C,D,E,F,G,H:=sommets(c); - Ex3: A,B,K:=point(1,0,0),point(1,1,0),point(0,2,0);c:=cube(A,B,C);A,B,C,D,E,F,G,H:=sommets(c); - Ex4: c:=cube([0,0,0],[1,0,0],[0,1,0]);c1,c2,c4,c3,c5,c6,c7,c8:=sommets(c); - Ex5: c:=cube([0,0,0],[0,2,0],[0,0,1]);c1,c2,c4,c3,c5,c6,c7,c8:=sommets(c); - + See also: 1/ parallelepiped 2/ cylinder 3/ icosahedron 4/ dodecahedron 5/ octahedron 6/ tetrahedron 7/ centered_cube + Ex1: cube([0,0,0],[3,0,0],[0,0,1]) + Ex2: A,B,C:=point(1,0,0),point(1,1,0),point(0,1,0);c:=cube(A,B,C);A,B,C,D,E,F,G,H:=sommets(c); + Ex3: A,B,K:=point(1,0,0),point(1,1,0),point(0,2,0);c:=cube(A,B,C);A,B,C,D,E,F,G,H:=sommets(c); + Ex4: c:=cube([0,0,0],[1,0,0],[0,1,0]);c1,c2,c4,c3,c5,c6,c7,c8:=sommets(c); + Ex5: c:=cube([0,0,0],[0,2,0],[0,0,1]);c1,c2,c4,c3,c5,c6,c7,c8:=sommets(c); ''' return GiacMethods['cube'](self,*args) @@ -3573,11 +3288,10 @@ cdef class GiacMethods_base: Help for cumSum: cumSum(Lst(l)||Seq||Str) Returns the list (or the sequence or the string) lr where the elements are the cumulative sum of the list l: lr[k]=sum(l[j],j=0..k) (or lr=sum(l[j],j=0..k)$(k=0..size(l)-1)). - See also: 1/ sum + See also: 1/ sum Ex1:cumSum([0,1,2,3,4]) Ex2:cumSum(1.2,3,4.5,6) Ex3:cumSum("a","b","c","d") - ''' return GiacMethods['cumSum'](self,*args) @@ -3586,11 +3300,10 @@ cdef class GiacMethods_base: Help for cumsum: cumsum(Lst(l)||Seq||Str) Returns the list (or the sequence or the string) lr where the elements are the cumulative sum of the list l: lr[k]=sum(l[j],j=0..k) (or lr=sum(l[j],j=0..k)$(k=0..size(l)-1)). - See also: 1/ sum + See also: 1/ sum Ex1:cumsum([0,1,2,3,4]) Ex2:cumsum(1.2,3,4.5,6) Ex3:cumsum("a","b","c","d") - ''' return GiacMethods['cumsum'](self,*args) @@ -3599,13 +3312,12 @@ cdef class GiacMethods_base: Help for cumulated_frequencies: cumulated_frequencies(Lst || Mtrx) Draws the diagram of the cumulated frequencies (rows=[value,frequencies]) - See also: 1/ histogram 2/ classes 3/ bar_plot + See also: 1/ histogram 2/ classes 3/ bar_plot Ex1:cumulated_frequencies([1,2,1,1,2,1,2,4,3,3]) Ex2:cumulated_frequencies([(rand(6)+1)$(k=1..100)]) Ex3:cumulated_frequencies([[1,0.3],[2,0.5],[3,0.2]]) Ex4:cumulated_frequencies([[1..2,0.3],[2..3,0.5],[3..4,0.2]]) Ex5:cumulated_frequencies([[1..2,0.3,0.5],[2..3,0.5,0.2],[3..4,0.2,0.3]]) - ''' return GiacMethods['cumulated_frequencies'](self,*args) @@ -3614,9 +3326,8 @@ cdef class GiacMethods_base: Help for curl: curl(Lst(A,B,C),Lst(x,y,z)) curl([A,B,C],[x,y,z])=[dC/dy-dB/dz,dA/dz-dC/dx,dB/dx-dA/dy]. - See also: 1/ derive 2/ divergence + See also: 1/ derive 2/ divergence Ex1:curl([2*x*y,x*z,y*z],[x,y,z]) - ''' return GiacMethods['curl'](self,*args) @@ -3627,7 +3338,6 @@ cdef class GiacMethods_base: Content of the matrix editor or spreadsheet. Ex1:current_sheet(1,2) Ex2:current_sheet(A1..A5,B,G) - ''' return GiacMethods['current_sheet'](self,*args) @@ -3636,7 +3346,7 @@ cdef class GiacMethods_base: Help for curvature: curvature(Curve,Point) Curvature of curve C at point M. - See also: 1/ osculating_circle 2/ evolute + See also: 1/ osculating_circle 2/ evolute Ex1:curvature(plot(x^2),point(1,1)) Ex2:curvature([5*cos(t),5*sin(t)],t) Ex3:curvature([t,t^2],t) @@ -3644,7 +3354,6 @@ cdef class GiacMethods_base: Ex5:curvature([3*exp(t/2)*cos(t),3*exp(t/2)*sin(t)],t) Ex6:curvature([3*exp(t/2)*cos(t),3*exp(t/2)*sin(t)],t,7) Ex7: trigcos(curvature([2*cos(t),2*sin(t),3*t],t)) - ''' return GiacMethods['curvature'](self,*args) @@ -3653,8 +3362,7 @@ cdef class GiacMethods_base: Help for curve: curve(Expr) Reserved word. - See also: 1/ - + See also: 1/ ''' return GiacMethods['curve'](self,*args) @@ -3663,10 +3371,9 @@ cdef class GiacMethods_base: Help for cyan: cyan(Opt) Option of the display command to display with color. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),red) Ex2: F:=display(point(2+1.5*i),point_point+green) - ''' return GiacMethods['cyan'](self,*args) @@ -3675,9 +3382,8 @@ cdef class GiacMethods_base: Help for cycle2perm: cycle2perm(Cycle) Converts the cycle c to a permutation. - See also: 1/ cycles2permu 2/ permu2cycles + See also: 1/ cycles2permu 2/ permu2cycles Ex1:cycle2perm([1,3,5]) - ''' return GiacMethods['cycle2perm'](self,*args) @@ -3686,10 +3392,9 @@ cdef class GiacMethods_base: Help for cycle_graph: cycle_graph(Intg(n)||Lst(V)) Returns a cyclic graph with n vertices (or with vertices from list V). - See also: 1/ graph 2/ path_graph + See also: 1/ graph 2/ path_graph Ex1:cycle_graph(4) Ex2:cycle_graph(["one","two","three","four","five"]) - ''' return GiacMethods['cycle_graph'](self,*args) @@ -3698,9 +3403,8 @@ cdef class GiacMethods_base: Help for cycleinv: cycleinv(Cycle(c)) Returns the inverse cycle of the cycle c. - See also: 1/ perminv + See also: 1/ perminv Ex1:cycleinv([1,3,5]) - ''' return GiacMethods['cycleinv'](self,*args) @@ -3709,9 +3413,8 @@ cdef class GiacMethods_base: Help for cycles2permu: cycles2permu(Lst(Cycle)) Converts a product of cycles into a permutation. - See also: 1/ permu2cycles 2/ cycle2perm + See also: 1/ permu2cycles 2/ cycle2perm Ex1:cycles2permu([[1,3,5],[3,4]]) - ''' return GiacMethods['cycles2permu'](self,*args) @@ -3720,9 +3423,8 @@ cdef class GiacMethods_base: Help for cyclotomic: cyclotomic(Expr) N-th cyclotomic polynomial. - See also: 1/ none + See also: 1/ none Ex1:cyclotomic(20) - ''' return GiacMethods['cyclotomic'](self,*args) @@ -3731,10 +3433,9 @@ cdef class GiacMethods_base: Help for cylinder: cylinder(Pnt(A),Vect(v),Real(r),[Real(h)]) Draws a cylinder with axis (A,v), with radius r [and with altitude h]. - See also: 1/ half_cone 2/ cone + See also: 1/ half_cone 2/ cone Ex1:cylinder([0,0,0],[0,1,0],2) Ex2:cylinder([0,0,0],[0,1,0],2,-3) - ''' return GiacMethods['cylinder'](self,*args) @@ -3743,10 +3444,9 @@ cdef class GiacMethods_base: Help for dash_line: dash_line(Opt) Option of the display command for a line. - See also: 1/ display + See also: 1/ display Ex1: display(line(y=x),green+dash_line+line_width_2) Ex2: d:=display(line(2+i,1),cap_round_line) - ''' return GiacMethods['dash_line'](self,*args) @@ -3755,10 +3455,9 @@ cdef class GiacMethods_base: Help for dashdot_line: dashdot_line(Opt) Option of the display command for a line. - See also: 1/ display + See also: 1/ display Ex1: display(line(y=x),green+dash_line+line_width_2) Ex2: d:=display(line(2+i,1),cap_round_line) - ''' return GiacMethods['dashdot_line'](self,*args) @@ -3767,10 +3466,9 @@ cdef class GiacMethods_base: Help for dashdotdot_line: dashdotdot_line(Opt) Option of the display command for a line. - See also: 1/ display + See also: 1/ display Ex1: display(line(y=x),green+dash_line+line_width_2) Ex2: d:=display(line(2+i,1),cap_round_line) - ''' return GiacMethods['dashdotdot_line'](self,*args) @@ -3781,7 +3479,6 @@ cdef class GiacMethods_base: dayofweek(d,m,y) returns the day of the given date (day,month,year) : 0 for sunday, 1 for monday ...6 for saturday. Ex1:dayofweek(21,4,2014) Ex2:dayofweek(15,10,1582) - ''' return GiacMethods['dayofweek'](self,*args) @@ -3790,12 +3487,12 @@ cdef class GiacMethods_base: Help for deSolve: deSolve(Eq,[TimeVar],FncVar) Solves a differential equation or a differential linear system with constant coefficients. - See also: 1/ integrate 2/ diff 3/ odesolve 4/ plotode 5/ plotfiefd + See also: 1/ integrate 2/ diff 3/ odesolve 4/ plotode 5/ plotfiefd Ex1:deSolve(y'+x*y=0) Ex2:deSolve(y'+x*y=0,y) Ex3:deSolve(y'+x*y=0,[0,1]) Ex4:deSolve([y'+x*y=0,y(0)=1],y) - Ex5:deSolve([y'=[[1,2],[2,1]]*y+[x,x+1],y(0)=[1,2]]) + Ex5:deSolve([y'=[[1,2],[2,1]]*y+[x,x+1],y(0)=[1,2]]) Ex6:deSolve(y''+y=0,y) Ex7:deSolve([y''+y=sin(x),y(0)=1,y'(0)=2],y) Ex8:deSolve([y''+y=sin(x),y(0)=1,y'(0)=2],x,y) @@ -3807,7 +3504,6 @@ cdef class GiacMethods_base: Ex14:deSolve([z''+2*z'+z,z(0)=1,z'(0)=0],z(u)) Ex15:deSolve([z'=[[1,2],[2,1]]*z+[t,t+1],z(0)=[1,2]],t,z) Ex16:deSolve([z'=[[1,2],[2,1]]*z+[t,t+1],z(0)=[1,2]],z(t)) - ''' return GiacMethods['deSolve'](self,*args) @@ -3816,10 +3512,9 @@ cdef class GiacMethods_base: Help for debut_enregistrement: debut_enregistrement(Var(nom_du_dessin)) Begins recording the commands making up the drawing; the name of the resulting procedure is the argument. - See also: 1/ fin_enregistrement + See also: 1/ fin_enregistrement Ex1:debut_enregistrement(maison) Ex2:debut_enregistrement(arbre) - ''' return GiacMethods['debut_enregistrement'](self,*args) @@ -3828,11 +3523,10 @@ cdef class GiacMethods_base: Help for degree: degree(Poly(P),Var(Var)) Degree of the polynomial P with respect to the second argument. - See also: 1/ valuation 2/ size 3/ total_degree + See also: 1/ valuation 2/ size 3/ total_degree Ex1:degree(x^3+x) Ex2:degree([1,0,1,0]) Ex3:degree(x^3+x*y,y) - ''' return GiacMethods['degree'](self,*args) @@ -3841,9 +3535,8 @@ cdef class GiacMethods_base: Help for degree_sequence: degree_sequence(Graph(G)) Returns the list of degrees of vertices of G (arc directions are ignored). - See also: 1/ is_graphic_sequence 2/ is_regular 2/ sequence_graph 3/ vertex_degree + See also: 1/ is_graphic_sequence 2/ is_regular 2/ sequence_graph 3/ vertex_degree Ex1:degree_sequence(graph(trail(1,2,3,4,2))) - ''' return GiacMethods['degree_sequence'](self,*args) @@ -3852,11 +3545,10 @@ cdef class GiacMethods_base: Help for delcols: delcols(Mtrx(A),Interval(n1..n2)||n1) Returns the matrix where the columns n1..n2 (or n1) of the matrix A are deleted. - See also: 1/ delrows + See also: 1/ delrows Ex1:delcols([[1,2,3],[4,5,6],[7,8,9]],1..1) Ex2:delcols([[1,2,3],[4,5,6],[7,8,9]],0..1) Ex3:delcols([[1,2,3],[4,5,6],[7,8,9]],1) - ''' return GiacMethods['delcols'](self,*args) @@ -3865,9 +3557,8 @@ cdef class GiacMethods_base: Help for delete_arc: delete_arc(Graph(G),Edge(e)||Trail(T)||Lst(E)) Returns a modified copy of digraph G with arc e (or trail T or list of arcs E) removed. - See also: 1/ add_arc 2/ delete_edge 3/ digraph 4/ edges 5/ has_arc 6/ trail + See also: 1/ add_arc 2/ delete_edge 3/ digraph 4/ edges 5/ has_arc 6/ trail Ex1:delete_arc(digraph(trail(1,2,3,4,5,1)),[5,1]) - ''' return GiacMethods['delete_arc'](self,*args) @@ -3876,9 +3567,8 @@ cdef class GiacMethods_base: Help for delete_edge: delete_edge(Graph(G),Edge(e)||Trail(T)||Lst(E)) Returns a modified copy of undirected graph G with edge e (or trail T or list of edges E) removed. - See also: 1/ add_edge 2/ delete_arc 3/ edges 4/ graph 5/ has_edge 6/ trail + See also: 1/ add_edge 2/ delete_arc 3/ edges 4/ graph 5/ has_edge 6/ trail Ex1:delete_edge(cycle_graph(4),[1,2]) - ''' return GiacMethods['delete_edge'](self,*args) @@ -3887,9 +3577,8 @@ cdef class GiacMethods_base: Help for delete_vertex: delete_vertex(Graph(G),Vrtx(v)||Lst(V)) Returns a modified copy of G with vertex v (or vertices from V) removed. - See also: 1/ add_vertex 2/ induced_subgraph + See also: 1/ add_vertex 2/ induced_subgraph Ex1:delete_vertex(cycle_graph(5),[1,4]) - ''' return GiacMethods['delete_vertex'](self,*args) @@ -3898,11 +3587,10 @@ cdef class GiacMethods_base: Help for delrows: delrows(Mtrx(A),Interval(n1..n2)||n1) Returns the matrix where the rows n1..n2 (or n1) of the matrix A are deleted. - See also: 1/ delcols + See also: 1/ delcols Ex1:delrows([[1,2,3],[4,5,6],[7,8,9]],1..1) Ex2:delrows([[1,2,3],[4,5,6],[7,8,9]],0..1) Ex3:delrows([[1,2,3],[4,5,6],[7,8,9]],1) - ''' return GiacMethods['delrows'](self,*args) @@ -3911,10 +3599,9 @@ cdef class GiacMethods_base: Help for deltalist: deltalist(Lst) Returns the list of the differences of two terms in succession. - See also: 1/ + See also: 1/ Ex1:deltalist([1,4,8,9]) Ex2:deltalist([1,8,4,9]) - ''' return GiacMethods['deltalist'](self,*args) @@ -3923,11 +3610,10 @@ cdef class GiacMethods_base: Help for denom: denom(Frac(a/b) or RatFrac) Returns the denominator of the simplified fraction. - See also: 1/ getDenom 2/ getNum 3/ numer 4/ f2nd + See also: 1/ getDenom 2/ getNum 3/ numer 4/ f2nd Ex1:denom(25/15) Ex2:denom((x^3-1)/(x^2-1)) Ex3:denom(1+(x^3-1)/x^2) - ''' return GiacMethods['denom'](self,*args) @@ -3936,10 +3622,9 @@ cdef class GiacMethods_base: Help for densityplot: densityplot(Expr,[x=xrange,y=yrange],[z],[xstep],[ystep]) Shows in the plane with colors the graph of an expression of 2 variables. - See also: 1/ plotfunc 2/ plotcontour + See also: 1/ plotfunc 2/ plotcontour Ex1:densityplot(x^2-y^2,[x=-2..2,y=-2..2],xstep=0.1,ystep=0.1) Ex2:densityplot(x^2-y^2,[x=-2..2,y=-2..2],z=-2..2,xstep=0.1,ystep=0.1) - ''' return GiacMethods['densityplot'](self,*args) @@ -3948,9 +3633,8 @@ cdef class GiacMethods_base: Help for departures: departures(Graph(G),[Vrtx(v)]) Returns the list of vertices of digraph G which are connected by v with arcs such that tails are in v. If v is omitted, a list of departures is computed for every vertex in G. - See also: 1/ out_degree + See also: 1/ out_degree Ex1:departures(digraph(%{[1,2],[1,3],[2,3]%}),1) - ''' return GiacMethods['departures'](self,*args) @@ -3959,7 +3643,7 @@ cdef class GiacMethods_base: Help for derive: derive(Expr or Fnc,[SeqVar or LstVar],[n]) Returns the derivative with respect to the 2nd argument. - See also: 1/ ' 2/ function_diff 3/ integrate 4/ taux_accroissement 5/ implicitdiff + See also: 1/ ' 2/ function_diff 3/ integrate 4/ taux_accroissement 5/ implicitdiff Ex1:derive(x^3-x) Ex2:derive(x^3-x,x,3) Ex3:derive(x^3-x,quote(x)$3) @@ -3968,7 +3652,6 @@ cdef class GiacMethods_base: Ex6:derive(x*y+z*y,y,z) Ex7:derive(x*y+z*y,[y,z]) Ex8: f(x):=sin(2x);g:=diff(f);h:=diff(diff(f)) - ''' return GiacMethods['derive'](self,*args) @@ -3977,7 +3660,7 @@ cdef class GiacMethods_base: Help for deriver: deriver(Expr or Fnc,[SeqVar or LstVar],[n]) Returns the derivative with respect to the 2nd argument. - See also: 1/ ' 2/ function_diff 3/ integrate 4/ taux_accroissement 5/ implicitdiff + See also: 1/ ' 2/ function_diff 3/ integrate 4/ taux_accroissement 5/ implicitdiff Ex1:deriver(x^3-x) Ex2:deriver(x^3-x,x,3) Ex3:deriver(x^3-x,quote(x)$3) @@ -3986,7 +3669,6 @@ cdef class GiacMethods_base: Ex6:deriver(x*y+z*y,y,z) Ex7:deriver(x*y+z*y,[y,z]) Ex8: f(x):=sin(2x);g:=diff(f);h:=diff(diff(f)) - ''' return GiacMethods['deriver'](self,*args) @@ -3995,12 +3677,12 @@ cdef class GiacMethods_base: Help for desolve: desolve(Eq,[TimeVar],FncVar) Solves a differential equation or a differential linear system with constant coefficients. - See also: 1/ integrate 2/ diff 3/ odesolve 4/ plotode 5/ plotfiefd + See also: 1/ integrate 2/ diff 3/ odesolve 4/ plotode 5/ plotfiefd Ex1:desolve(y'+x*y=0) Ex2:desolve(y'+x*y=0,y) Ex3:desolve(y'+x*y=0,[0,1]) Ex4:desolve([y'+x*y=0,y(0)=1],y) - Ex5:desolve([y'=[[1,2],[2,1]]*y+[x,x+1],y(0)=[1,2]]) + Ex5:desolve([y'=[[1,2],[2,1]]*y+[x,x+1],y(0)=[1,2]]) Ex6:desolve(y''+y=0,y) Ex7:desolve([y''+y=sin(x),y(0)=1,y'(0)=2],y) Ex8:desolve([y''+y=sin(x),y(0)=1,y'(0)=2],x,y) @@ -4012,7 +3694,6 @@ cdef class GiacMethods_base: Ex14:desolve([z''+2*z'+z,z(0)=1,z'(0)=0],z(u)) Ex15:desolve([z'=[[1,2],[2,1]]*z+[t,t+1],z(0)=[1,2]],t,z) Ex16:desolve([z'=[[1,2],[2,1]]*z+[t,t+1],z(0)=[1,2]],z(t)) - ''' return GiacMethods['desolve'](self,*args) @@ -4021,11 +3702,10 @@ cdef class GiacMethods_base: Help for dessine_tortue: dessine_tortue([Intg(n)]) Draws the full (or not full if n=1) triangle representing the turtle. - See also: 1/ crayon + See also: 1/ crayon Ex1:dessine_tortue() Ex2:dessine_tortue(0) Ex3:dessine_tortue(1) - ''' return GiacMethods['dessine_tortue'](self,*args) @@ -4034,10 +3714,9 @@ cdef class GiacMethods_base: Help for det: det(Mtrx) Determinant of a square matrix M. - See also: 1/ rref 2/ det_minor 3/ Det + See also: 1/ rref 2/ det_minor 3/ Det Ex1:det([[1,2],[3,4]]) Ex2:det([[1,2,3],[1,3,6],[2,5,7]]) - ''' return GiacMethods['det'](self,*args) @@ -4046,9 +3725,8 @@ cdef class GiacMethods_base: Help for det_minor: det_minor(Mtrx(A)) Returns the determinant calculated with the calculus of minors. - See also: 1/ det + See also: 1/ det Ex1:det_minor([[1,2],[3,4]]) - ''' return GiacMethods['det_minor'](self,*args) @@ -4057,13 +3735,12 @@ cdef class GiacMethods_base: Help for developper: developper(Expr) Full distribution of * and / over + and -. - See also: 1/ texpand 2/ normal 3/ simplify 4/ ratnormal + See also: 1/ texpand 2/ normal 3/ simplify 4/ ratnormal Ex1:developper((x+y)*(z+1)) Ex2:developper((a+b+c)/d) Ex3:developper((y+x)*(z+y)*(x+z)) Ex4:developper((x+3)^4) Ex5:developper((2*x-2*1)*(x^2-3*x+2)+(x^2-2*x+3)*(2*x-3*1)) - ''' return GiacMethods['developper'](self,*args) @@ -4072,11 +3749,10 @@ cdef class GiacMethods_base: Help for developper_transcendant: developper_transcendant(Expr) Expands transcendental expressions. - See also: 1/ tcollect 2/ tlin 3/ lin 4/ trigexpand + See also: 1/ tcollect 2/ tlin 3/ lin 4/ trigexpand Ex1:developper_transcendant(sin(2*x)+exp(x+y)) Ex2:developper_transcendant(cos(x+y)) Ex3:developper_transcendant(cos(3*x)) - ''' return GiacMethods['developper_transcendant'](self,*args) @@ -4085,13 +3761,12 @@ cdef class GiacMethods_base: Help for dfc: dfc(Real(x0),Int(n)||Real(eps)) Returns the continued fraction development at x0 of order n or with precision eps. - See also: 1/ dfc2f 2/ convert + See also: 1/ dfc2f 2/ convert Ex1:dfc(sqrt(2),5) Ex2:dfc(pi,4) Ex3:dfc(evalf(pi),1e-09) Ex4: convert(sqrt(2),confrac,'dev');dev Ex5: convert(9976/6961,confrac,'l');l - ''' return GiacMethods['dfc'](self,*args) @@ -4100,10 +3775,9 @@ cdef class GiacMethods_base: Help for dfc2f: dfc2f(LstFrac_Cont)) Converts a continued fraction into a real. - See also: 1/ dfc 2/ convert + See also: 1/ dfc 2/ convert Ex1:dfc2f([1,1,1]) Ex2:dfc2f([1,2,[2]]) - ''' return GiacMethods['dfc2f'](self,*args) @@ -4112,14 +3786,13 @@ cdef class GiacMethods_base: Help for diag: diag(Lst(l)||(Mtrx(A),[left||right||lu])||Lst(l),Lst(d),Lst(u)) With 1 argument returns either the diagonal matrix with diagonal l or the diagonal of A, with 2 arguments returns the large left (lower) triangular part of A or the large right (upper) triangular part of A or factors A into 3 parts : strict left (lower) triangular, diagonal, strict right (upper) triangular and with 3 arguments returns the tridiagonal matrix with diagonals l,d,u. - See also: 1/ identity 2/ lu 3/ BlockDiagonal 4/ upper 5/ lower + See also: 1/ identity 2/ lu 3/ BlockDiagonal 4/ upper 5/ lower Ex1:diag([[1,2],[3,4]]) Ex2:diag([1,2,3]) Ex3:diag([[1,2],[3,4]],left) Ex4:diag([[1,2],[3,4]],right) Ex5:diag([[1,2],[3,4]],lu) Ex6:diag([1,2],[3,4,5],[6,7]) - ''' return GiacMethods['diag'](self,*args) @@ -4128,7 +3801,7 @@ cdef class GiacMethods_base: Help for diff: diff(Expr or Fnc,[SeqVar or LstVar],[n]) Returns the derivative with respect to the 2nd argument. - See also: 1/ ' 2/ function_diff 3/ integrate 4/ taux_accroissement 5/ implicitdiff + See also: 1/ ' 2/ function_diff 3/ integrate 4/ taux_accroissement 5/ implicitdiff Ex1:diff(x^3-x) Ex2:diff(x^3-x,x,3) Ex3:diff(x^3-x,quote(x)$3) @@ -4137,7 +3810,6 @@ cdef class GiacMethods_base: Ex6:diff(x*y+z*y,y,z) Ex7:diff(x*y+z*y,[y,z]) Ex8: f(x):=sin(2x);g:=diff(f);h:=diff(diff(f)) - ''' return GiacMethods['diff'](self,*args) @@ -4146,10 +3818,9 @@ cdef class GiacMethods_base: Help for digraph: digraph([Lst(V)],[Set(E)],[Mtrx(A)],[options]) Create a directed (un)weighted graph from vertices V, edges E and/or adjacency or weight matrix A. All parameters are optional. - See also: 1/ graph 2/ trail + See also: 1/ graph 2/ trail Ex1:digraph(%{[1,2],[2,3],[3,4],[4,1]%}) Ex2:digraph([a,b,c,d],%{[[a,b],1.0],[[a,c],2.3],[[b,d],3.1],[[c,d],4]%}) - ''' return GiacMethods['digraph'](self,*args) @@ -4158,9 +3829,8 @@ cdef class GiacMethods_base: Help for dijkstra: dijkstra(Graph(G),Vrtx(v),[Vrtx(w)||Lst(W)]) Returns the cheapest weighted path from vertex v to w (or to vertices from W) in undirected graph G. Output is in the form [[v1,v2,...,vk],d] (or list of these) where v1,v2,...,vk are vertices along each path and d is the weight of the path. - See also: 1/ allpairs_distance 2/ shortest_path + See also: 1/ allpairs_distance 2/ shortest_path Ex1:dijkstra(graph(%{[[1,2],1],[[2,3],3],[[3,4],7],[[4,5],3],[[5,6],3],[[1,6],3]%}),1,4) - ''' return GiacMethods['dijkstra'](self,*args) @@ -4169,9 +3839,8 @@ cdef class GiacMethods_base: Help for dim: dim(Mtrx) Returns the list which gives the dimension of the matrix specified as argument. - See also: 1/ rowdim 2/ coldim 3/ sizes 4/ size + See also: 1/ rowdim 2/ coldim 3/ sizes 4/ size Ex1:dim([[1,2,3],[4,5,6]]) - ''' return GiacMethods['dim'](self,*args) @@ -4180,8 +3849,7 @@ cdef class GiacMethods_base: Help for directed: directed(Opt) Option for graph and digraph commands. - See also: 1/ weighted 2/ graph 3/ digraph - + See also: 1/ weighted 2/ graph 3/ digraph ''' return GiacMethods['directed'](self,*args) @@ -4190,9 +3858,8 @@ cdef class GiacMethods_base: Help for discard_edge_attribute: discard_edge_attribute(Graph(G),Edge(e),Seq(tag1=value1,tag2=value2,..)) Discards the attributes with tags tag1, tag2, ... assigned to edge e in G and returns the modified copy of G. - See also: 1/ get_edge_attribute 2/ set_edge_attribute 3/ list_edge_attributes + See also: 1/ get_edge_attribute 2/ set_edge_attribute 3/ list_edge_attributes Ex1:discard_edge_attribute(cycle_graph(3),[1,2],"cost") - ''' return GiacMethods['discard_edge_attribute'](self,*args) @@ -4201,9 +3868,8 @@ cdef class GiacMethods_base: Help for discard_graph_attribute: discard_graph_attribute(Graph(G),Seq(tag1=value1,tag2=value2,..)) Discards the graph attributes with tags tag1, tag2, ... and returns the modified copy of G. - See also: 1/ get_graph_attribute 2/ set_graph_attribute 3/ list_graph_attributes + See also: 1/ get_graph_attribute 2/ set_graph_attribute 3/ list_graph_attributes Ex1:discard_graph_attribute(cycle_graph(3),"name") - ''' return GiacMethods['discard_graph_attribute'](self,*args) @@ -4212,9 +3878,8 @@ cdef class GiacMethods_base: Help for discard_vertex_attribute: discard_vertex_attribute(Graph(G),Vrtx(v),Seq(tag1=value1,tag2=value2,..)) Discards the attributes with tags tag1, tag2, ... assigned to vertex v in G and returns the modified copy of G. - See also: 1/ get_vertex_attribute 2/ set_vertex_attribute 3/ list_vertex_attributes + See also: 1/ get_vertex_attribute 2/ set_vertex_attribute 3/ list_vertex_attributes Ex1:discard_vertex_attribute(cycle_graph(3),1,"supply") - ''' return GiacMethods['discard_vertex_attribute'](self,*args) @@ -4223,9 +3888,8 @@ cdef class GiacMethods_base: Help for disjoint_union: disjoint_union(Seq(G1,G2,...)) Returns the disjoint union of the graphs G1, G2, ... Vertices in the resulting graph are labelled with "k:v", where k is index of the corresponding k-th graph Gk and v is vertex in Gk. - See also: 1/ graph_join 2/ graph_union + See also: 1/ graph_join 2/ graph_union Ex1:disjoint_union(is_connected(disjoint_union(cycle_graph(5),path_graph(4)))) - ''' return GiacMethods['disjoint_union'](self,*args) @@ -4234,7 +3898,7 @@ cdef class GiacMethods_base: Help for display: display([GeoObj or legende],Intg) Draws a geometrical object with colors black=0 red=1 green=2 yellow=3 blue=4, filled with the color in the interior of a closed curve,line_width_n (0=0 or, the (-n)th previous question if n<0 (by default n=-1 for the previous question). - See also: 1/ ans + See also: 1/ ans Ex1:entry() Ex2:entry(2) Ex3:entry(-2) - ''' return GiacMethods['entry'](self,*args) @@ -4916,10 +4528,9 @@ cdef class GiacMethods_base: Help for envelope: envelope(Expr(Xpr),Var(t)||[x,y,t]) Returns the envelope of the curves with equation Xpr=0 as t varies. - See also: 1/ tangent 2/ locus + See also: 1/ tangent 2/ locus Ex1:envelope(y+x*tan(t)-2*sin(t),t) Ex2:envelope(v+u*tan(t)-3*sin(t),[u,v,t]) - ''' return GiacMethods['envelope'](self,*args) @@ -4928,9 +4539,8 @@ cdef class GiacMethods_base: Help for epsilon: epsilon(NULL) Returns the value of epsilon of the CAS configuration. - See also: 1/ epsilon2zero + See also: 1/ epsilon2zero Ex1:epsilon() - ''' return GiacMethods['epsilon'](self,*args) @@ -4939,9 +4549,8 @@ cdef class GiacMethods_base: Help for epsilon2zero: epsilon2zero(Expr) Values < epsilon are replaced by zero. - See also: 1/ evalf + See also: 1/ evalf Ex1:epsilon2zero(1e-13+x+5) - ''' return GiacMethods['epsilon2zero'](self,*args) @@ -4950,11 +4559,10 @@ cdef class GiacMethods_base: Help for equal: equal(Expr,Expr) Prefixed version of =. - See also: 1/ = 2/ equal2diff 3/ equal2list 4/ left 5/ right + See also: 1/ = 2/ equal2diff 3/ equal2list 4/ left 5/ right Ex1: 2*x=4 Ex2:equal(2*x,4) Ex3:equal(x^2-3x+2,0) - ''' return GiacMethods['equal'](self,*args) @@ -4963,10 +4571,9 @@ cdef class GiacMethods_base: Help for equal2diff: equal2diff(Equal) A=B or equal(A,B) is converted into the difference A-B. - See also: 1/ left 2/ right 3/ equal2list 4/ equal 5/ = + See also: 1/ left 2/ right 3/ equal2list 4/ equal 5/ = Ex1:equal2diff(x=2) Ex2:equal2diff(equal(x,2)) - ''' return GiacMethods['equal2diff'](self,*args) @@ -4975,10 +4582,9 @@ cdef class GiacMethods_base: Help for equal2list: equal2list(Equal) A=B or equal(A,B) is converted into the list [A,B]. - See also: 1/ left 2/ right 3/ equal2diff 4/ equal 5/ = + See also: 1/ left 2/ right 3/ equal2diff 4/ equal 5/ = Ex1:equal2list(x=2) Ex2:equal2list(equal(x,2)) - ''' return GiacMethods['equal2list'](self,*args) @@ -4987,9 +4593,8 @@ cdef class GiacMethods_base: Help for equation: equation(GeoObj, VectParam) equation returns the cartesian equation of a curve. - See also: 1/ parameq + See also: 1/ parameq Ex1:equation(line(1-i,i),[x,y]) - ''' return GiacMethods['equation'](self,*args) @@ -4998,12 +4603,11 @@ cdef class GiacMethods_base: Help for equilateral_triangle: equilateral_triangle((Pnt(A) or Cplx),(Pnt(B) or Cplx),[Pnt(P)],[Var(C)]) equilateral_triangle(A,B) (resp equilateral_triangle(A,B,P)) draws the direct equilateral triangle ABC with side AB (resp in the half-plane ABP). - See also: 1/ triangle + See also: 1/ triangle Ex1:equilateral_triangle(point(1+i),0) Ex2:equilateral_triangle(0,1+i,C) Ex3:equilateral_triangle(point(0,0,0),point(3,3,3),point(0,0,3)) Ex4:equilateral_triangle(point(0,0,0),point(3,3,3),point(0,0,3),C) - ''' return GiacMethods['equilateral_triangle'](self,*args) @@ -5012,10 +4616,9 @@ cdef class GiacMethods_base: Help for erf: erf(Real(x0)) Returns the approximate value of 2/sqrt(pi)*int(exp(-t^2),t,0,x0). - See also: 1/ erfc + See also: 1/ erfc Ex1:erf(1) Ex2:erf(1/(sqrt(2)))*1/2 - ''' return GiacMethods['erf'](self,*args) @@ -5024,10 +4627,9 @@ cdef class GiacMethods_base: Help for erfc: erfc(Real(x0)) Returns the approximate value of 2/sqrt(pi)*int(exp(-t^2),t,x0,+infinity). - See also: 1/ erf + See also: 1/ erf Ex1:erfc(1) Ex2:erfc(1/(sqrt(2)))*1/2 - ''' return GiacMethods['erfc'](self,*args) @@ -5036,10 +4638,9 @@ cdef class GiacMethods_base: Help for error: error(Str) Generates the display of an error in a program. - See also: 1/ try 2/ catch + See also: 1/ try 2/ catch Ex1:error("Argument should be integer") Ex2:error("je provoque une erreur") - ''' return GiacMethods['error'](self,*args) @@ -5048,10 +4649,9 @@ cdef class GiacMethods_base: Help for est_permu: est_permu(Lst) Returns 1 if the argument is a permutation and 0 otherwise. - See also: 1/ is_cycle 2/ permu2cycles + See also: 1/ is_cycle 2/ permu2cycles Ex1:est_permu([4,2,3,1]) Ex2:est_permu([4,2,3,1,0]) - ''' return GiacMethods['est_permu'](self,*args) @@ -5060,10 +4660,9 @@ cdef class GiacMethods_base: Help for euler: euler(Intg(n)) Euler's function (euler(n)=card({p=0):; euler_lagrange(sqrt((1+y'^2)/y),t,y) - ''' return GiacMethods['euler_lagrange'](self,*args) @@ -5100,7 +4697,6 @@ cdef class GiacMethods_base: Ex3: purge(a,b,c);eval_level(1);a:=b+1; b:=c+1;c:=3; Ex4: purge(a,b,c);eval_level(2);a:=b+1; b:=c+1;c:=3; Ex5: purge(a,b,c);eval_level(3);a:=b+1; b:=c+1;c:=3; - ''' return GiacMethods['eval_level'](self,*args) @@ -5109,11 +4705,10 @@ cdef class GiacMethods_base: Help for evala: evala(Expr) Simplifies the expression. - See also: 1/ simplify + See also: 1/ simplify Ex1:evala(2*x+y=1) Ex2:evala(2*x*2) Ex3:evala((2*x+1)^2) - ''' return GiacMethods['evala'](self,*args) @@ -5122,10 +4717,9 @@ cdef class GiacMethods_base: Help for evalb: evalb(Expr) Boolean evaluation of the argument. - See also: 1/ evalf 2/ eval + See also: 1/ evalf 2/ eval Ex1:evalb(a==2) Ex2:evalb(sqrt(2)+pi>a) - ''' return GiacMethods['evalb'](self,*args) @@ -5134,10 +4728,9 @@ cdef class GiacMethods_base: Help for evalc: evalc(Expr) Returns a complex expression simplified to the format real+i*imag. - See also: 1/ normal + See also: 1/ normal Ex1:evalc(-3+4*i+exp(i)) Ex2:evalc(1/(x+y*i)) - ''' return GiacMethods['evalc'](self,*args) @@ -5146,14 +4739,13 @@ cdef class GiacMethods_base: Help for evalf: evalf(Expr,[Int]) Numerical evaluation of the first argument (we can give the number of digits as second argument). - See also: 1/ evalb 2/ eval + See also: 1/ evalb 2/ eval Ex1:evalf(2/3) Ex2:evalf(2/3,2) Ex3:evalf(2*sin(1)) Ex4:evalf(2*sin(1),40) Ex5:evalf(sqrt(2)+pi) Ex6:evalf(sqrt(2)+pi,30) - ''' return GiacMethods['evalf'](self,*args) @@ -5162,9 +4754,8 @@ cdef class GiacMethods_base: Help for evalm: evalm(Expr) Evaluates its argument. - See also: 1/ evalf + See also: 1/ evalf Ex1:evalm(2*sin(pi)) - ''' return GiacMethods['evalm'](self,*args) @@ -5173,10 +4764,9 @@ cdef class GiacMethods_base: Help for even: even(Intg(n)) Returns 1 if the integer is even, else returns 0. - See also: 1/ odd + See also: 1/ odd Ex1:even(6) Ex2:even(1251) - ''' return GiacMethods['even'](self,*args) @@ -5185,11 +4775,10 @@ cdef class GiacMethods_base: Help for evolute: evolute(Curve) Evolute of a curve C. - See also: 1/ curvature 2/ osculating_circle + See also: 1/ curvature 2/ osculating_circle Ex1:evolute(plot(x^2)) Ex2:evolute([t,t^2],t) Ex3:evolute([3*exp(t/2)*cos(t),3*exp(t/2)*sin(t)],t) - ''' return GiacMethods['evolute'](self,*args) @@ -5198,12 +4787,11 @@ cdef class GiacMethods_base: Help for exact: exact(Expr) Converts the expression to a rational or real expression. - See also: 1/ + See also: 1/ Ex1:exact(-2) Ex2:exact(1.5) Ex3:exact(1.4141) Ex4:exact(0.156381102937) - ''' return GiacMethods['exact'](self,*args) @@ -5212,9 +4800,8 @@ cdef class GiacMethods_base: Help for exbisector: exbisector((Pnt(A) or Cplx),(Pnt(B) or Cplx),(Pnt(C) or Cplx)) Draws the exterior bisector of the angle (AB,AC) given by 3 points A,B,C. - See also: 1/ angle 2/ bisector + See also: 1/ angle 2/ bisector Ex1:exbisector(0,1,i) - ''' return GiacMethods['exbisector'](self,*args) @@ -5223,9 +4810,8 @@ cdef class GiacMethods_base: Help for excircle: excircle((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) excircle(A,B,C) draws the A-excircle of the triangle ABC. - See also: 1/ incircle 2/ circumcircle + See also: 1/ incircle 2/ circumcircle Ex1:excircle(0,1,1+i) - ''' return GiacMethods['excircle'](self,*args) @@ -5234,12 +4820,11 @@ cdef class GiacMethods_base: Help for execute: execute(Str) Instruction transforming a string into a command or into a number. - See also: 1/ string + See also: 1/ string Ex1:execute("ifactor(54)") Ex2:execute("123") Ex3:execute("0123") Ex4:execute(sin,x) - ''' return GiacMethods['execute'](self,*args) @@ -5248,10 +4833,9 @@ cdef class GiacMethods_base: Help for exp: exp(Expr or Opt) Exponential or option of the convert or convertir command (id trig2exp). - See also: 1/ ln 2/ convert 3/ trig2exp + See also: 1/ ln 2/ convert 3/ trig2exp Ex1:exp(0) Ex2: convert(cos(x),exp) - ''' return GiacMethods['exp'](self,*args) @@ -5260,10 +4844,9 @@ cdef class GiacMethods_base: Help for exp2list: exp2list(Expr) Returns the list made with the righthand member of (var=expr0 or var=expr1), to be used after solve in TI mode. - See also: 1/ list2exp + See also: 1/ list2exp Ex1:exp2list((x=2) or (x=0)) Ex2:exp2list((x=3 and y=9) or (x=-1 and y=1) ) - ''' return GiacMethods['exp2list'](self,*args) @@ -5272,10 +4855,9 @@ cdef class GiacMethods_base: Help for exp2pow: exp2pow(Expr) Transforms exp(n*ln(x)) to x^n. - See also: 1/ pow2exp + See also: 1/ pow2exp Ex1:exp2pow(exp(3*ln(x))) Ex2:exp2pow(exp(x*ln(x))) - ''' return GiacMethods['exp2pow'](self,*args) @@ -5284,10 +4866,9 @@ cdef class GiacMethods_base: Help for exp2trig: exp2trig(Expr) Transforms the complex exponential into sine and cosine. - See also: 1/ trig2exp 2/ atrig2ln + See also: 1/ trig2exp 2/ atrig2ln Ex1:exp2trig(exp(i*x)) Ex2:exp2trig(exp(-i*x)) - ''' return GiacMethods['exp2trig'](self,*args) @@ -5296,13 +4877,12 @@ cdef class GiacMethods_base: Help for expand: expand(Expr) Full distribution of * and / over + and -. - See also: 1/ texpand 2/ normal 3/ simplify 4/ ratnormal + See also: 1/ texpand 2/ normal 3/ simplify 4/ ratnormal Ex1:expand((x+y)*(z+1)) Ex2:expand((a+b+c)/d) Ex3:expand((y+x)*(z+y)*(x+z)) Ex4:expand((x+3)^4) Ex5:expand((2*x-2*1)*(x^2-3*x+2)+(x^2-2*x+3)*(2*x-3*1)) - ''' return GiacMethods['expand'](self,*args) @@ -5311,9 +4891,8 @@ cdef class GiacMethods_base: Help for expexpand: expexpand(Expr) Expands exponentials. - See also: 1/ texpand 2/ lnexpand 3/ trigexpand + See also: 1/ texpand 2/ lnexpand 3/ trigexpand Ex1:expexpand(exp(3*x)) - ''' return GiacMethods['expexpand'](self,*args) @@ -5322,9 +4901,8 @@ cdef class GiacMethods_base: Help for expln: expln(Opt) Option of the convert or convertir command (id trig2exp). - See also: 1/ exp 2/ ln 3/ convert 4/ trig2exp + See also: 1/ exp 2/ ln 3/ convert 4/ trig2exp Ex1: convert(cos(x),expln) - ''' return GiacMethods['expln'](self,*args) @@ -5333,12 +4911,11 @@ cdef class GiacMethods_base: Help for exponential: exponential(Real(lambda),Real(x)) Returns the probability density at x of the exponential law of parameter lambda. - See also: 1/ exponential_cdf 2/ exponential_icdf 3/ randvector 4/ ranm + See also: 1/ exponential_cdf 2/ exponential_icdf 3/ randvector 4/ ranm Ex1:exponential(2.1,3.5) Ex2:exponential(2.1,0.5) Ex3: randvector(3,exponential,1.2) Ex4: ranm(4,3,exponential,1.2) - ''' return GiacMethods['exponential'](self,*args) @@ -5347,10 +4924,9 @@ cdef class GiacMethods_base: Help for exponential_cdf: exponential_cdf(Real(lambda),Real(x0),[Real(y0)]) Returns the probability that a exponential random variable of parameter lambda is less than x0 (or between x0 and y0). - See also: 1/ exponentiald 2/ exponential_icdf + See also: 1/ exponentiald 2/ exponential_icdf Ex1:exponential_cdf(4.2,2.1) Ex2:exponential_cdf(4.2,2.1,3.2) - ''' return GiacMethods['exponential_cdf'](self,*args) @@ -5359,10 +4935,9 @@ cdef class GiacMethods_base: Help for exponential_icdf: exponential_icdf(Real(lambda),Real(x0),Real(p)) Returns h such that the probability that a exponential random variable of parameter lambda is less than h is p (0<=p<=1). - See also: 1/ exponential_cdf 2/ exponentiald + See also: 1/ exponential_cdf 2/ exponentiald Ex1:exponential_icdf(4.2,0.95) Ex2:exponential_icdf(4.2,0.6) - ''' return GiacMethods['exponential_icdf'](self,*args) @@ -5371,10 +4946,9 @@ cdef class GiacMethods_base: Help for exponential_regression: exponential_regression(Lst||Mtrx(A),[Lst]) Returns the coefficients (a,b) of y=b*a^x : it is the best exponential which approx the points where the coordinates are the rows of A (or the 2 lists). - See also: 1/ logarithmic_regression + See also: 1/ logarithmic_regression Ex1:exponential_regression([[1.0,2.0],[0.0,1.0],[4.0,7.0]]) Ex2:exponential_regression([1.0,0.0,4.0],[2.0,1.0,7.0]) - ''' return GiacMethods['exponential_regression'](self,*args) @@ -5383,10 +4957,9 @@ cdef class GiacMethods_base: Help for exponential_regression_plot: exponential_regression_plot(Lst||Mtrx(A),[Lst]) Returns the plot of y=b*a^x : it is the best exponential which approx the points where the coordinates are the rows of A (or the 2 lists). - See also: 1/ logarithmic_regression_plot + See also: 1/ logarithmic_regression_plot Ex1:exponential_regression_plot([[1.0,2.0],[0.0,1.0],[4.0,7.0]]) Ex2:exponential_regression_plot([1.0,0.0,4.0],[2.0,1.0,7.0]) - ''' return GiacMethods['exponential_regression_plot'](self,*args) @@ -5395,12 +4968,11 @@ cdef class GiacMethods_base: Help for exponentiald: exponentiald(Real(lambda),Real(x)) Returns the probability density at x of the exponential law of parameter lambda. - See also: 1/ exponential_cdf 2/ exponential_icdf 3/ randvector 4/ ranm + See also: 1/ exponential_cdf 2/ exponential_icdf 3/ randvector 4/ ranm Ex1:exponentiald(2.1,3.5) Ex2:exponentiald(2.1,0.5) Ex3: randvector(3,exponential,1.2) Ex4: ranm(4,3,exponential,1.2) - ''' return GiacMethods['exponentiald'](self,*args) @@ -5409,10 +4981,9 @@ cdef class GiacMethods_base: Help for exponentiald_cdf: exponentiald_cdf(Real(lambda),Real(x0),[Real(y0)]) Returns the probability that a exponential random variable of parameter lambda is less than x0 (or between x0 and y0). - See also: 1/ exponentiald 2/ exponential_icdf + See also: 1/ exponentiald 2/ exponential_icdf Ex1:exponentiald_cdf(4.2,2.1) Ex2:exponentiald_cdf(4.2,2.1,3.2) - ''' return GiacMethods['exponentiald_cdf'](self,*args) @@ -5421,10 +4992,9 @@ cdef class GiacMethods_base: Help for exponentiald_icdf: exponentiald_icdf(Real(lambda),Real(x0),Real(p)) Returns h such that the probability that a exponential random variable of parameter lambda is less than h is p (0<=p<=1). - See also: 1/ exponential_cdf 2/ exponentiald + See also: 1/ exponential_cdf 2/ exponentiald Ex1:exponentiald_icdf(4.2,0.95) Ex2:exponentiald_icdf(4.2,0.6) - ''' return GiacMethods['exponentiald_icdf'](self,*args) @@ -5433,9 +5003,8 @@ cdef class GiacMethods_base: Help for export_graph: export_graph(Graph(G),Str("path/to/graphname")) Writes G to the file 'graphname.dot' in directory 'path/to' in dot format, returns 1 on success and 0 on failure. - See also: 1/ import_graph + See also: 1/ import_graph Ex1:export_graph(complete_graph(5),"K5") - ''' return GiacMethods['export_graph'](self,*args) @@ -5444,11 +5013,10 @@ cdef class GiacMethods_base: Help for export_mathml: export_mathml(Expr,[display||content]) Converts an expression to presentation or content MathML block. - See also: 1/ mathml 2/ latex + See also: 1/ mathml 2/ latex Ex1:export_mathml(a+2*b) Ex2:export_mathml(a+2*b,display) Ex3:export_mathml(a+2*b,content) - ''' return GiacMethods['export_mathml'](self,*args) @@ -5457,10 +5025,9 @@ cdef class GiacMethods_base: Help for expovariate: expovariate(Real(a)) Returns a random real according to the exponential distribution with parameter a>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:expovariate(1) Ex2:expovariate(2) - ''' return GiacMethods['expovariate'](self,*args) @@ -5469,12 +5036,11 @@ cdef class GiacMethods_base: Help for expr: expr(Str) Instruction transforming a string into a command or into a number. - See also: 1/ string + See also: 1/ string Ex1:expr("ifactor(54)") Ex2:expr("123") Ex3:expr("0123") Ex4:expr(sin,x) - ''' return GiacMethods['expr'](self,*args) @@ -5483,13 +5049,12 @@ cdef class GiacMethods_base: Help for extend: extend(Lst,Lst||Seq,Seq||Str,Str||Mtrx,Mtrx) Concatenates two lists or two strings or two sequences or 2 matrices; L:=concat(L,L1) or L.concat(L1). - See also: 1/ append 2/ cat 3/ semi_augment 4/ border 5/ + + See also: 1/ append 2/ cat 3/ semi_augment 4/ border 5/ + Ex1:extend([1,2],[3,4,5]) Ex2:extend("bon","jour") Ex3:extend([[1,2],[3,4]],[[4,5,6],[6,7,8]]) Ex4: L:=[1,2];L.concat([3,4,5]) Ex5: S:="abcd";S.concat("efghi") - ''' return GiacMethods['extend'](self,*args) @@ -5498,11 +5063,10 @@ cdef class GiacMethods_base: Help for extract_measure: extract_measure(Var) extract_measure gives as answer the value calculated by the argument. - See also: 1/ angleatraw 2/ distanceatraw 3/ angleat 4/ distanceat 5/ slopeatraw 6/ areaatraw 7/ perimeteratraw 8/ slopeat 5/ areaat 10/ perimeterat + See also: 1/ angleatraw 2/ distanceatraw 3/ angleat 4/ distanceat 5/ slopeatraw 6/ areaatraw 7/ perimeteratraw 8/ slopeat 5/ areaat 10/ perimeterat Ex1:extract_measure(distanceatraw(0,1+i,(1+i)/2)) Ex2:extract_measure(angleatraw(0,1,1+i,1)) Ex3: A:=point(0);B:=point(1+i);a:=distanceatraw(A,B,(1+i)/2);extract_measure(a) - ''' return GiacMethods['extract_measure'](self,*args) @@ -5556,7 +5120,7 @@ cdef class GiacMethods_base: Ex43:extrema(4x*y-x^4-y^4,[x,y]) Ex44:extrema(x*sin(y),[x,y]) Ex45:extrema(x^4+y^4,[x,y]) - Ex46:extrema(x^3*y-x*y^3,[x,y]) + Ex46:extrema(x^3*y-x*y^3,[x,y]) Ex47:extrema(x^2+y^2+z^2,x^4+y^4+z^4=1,[x,y,z]) Ex48:extrema(3x+3y+8z,[x^2+z^2=1,y^2+z^2=1],[x,y,z]) Ex49:extrema(2x^2+y^2,x^4-x^2+y^2=5,[x,y]) @@ -5565,10 +5129,9 @@ cdef class GiacMethods_base: Ex52:extrema(ln(x)+2*ln(y)+3*ln(z)+4*ln(u)+5*ln(v),x+y+z+u+v=1,[x,y,z,u,v]) Ex53:extrema(x*y*z,-2x^3+15x^2*y+11y^3-24y=0,[x,y,z]) Ex54:extrema(x+y-exp(x)-exp(y)-exp(x+y),[x,y]) - Ex55:extrema(x^2*sin(y)-4*x,[x,y]) + Ex55:extrema(x^2*sin(y)-4*x,[x,y]) Ex56:extrema((1+y*sinh(x))/(1+y^2+tanh(x)^2),[x,y]) Ex57:extrema((1+y*sinh(x))/(1+y^2+tanh(x)^2),y=x^2,[x,y]) - ''' return GiacMethods['extrema'](self,*args) @@ -5577,11 +5140,10 @@ cdef class GiacMethods_base: Help for ezgcd: ezgcd(Poly,Poly) GCD of 2 polynomials with at least 2 variables, with the ezgcd algorithm. - See also: 1/ gcd 2/ modgcd 3/ heugcd 4/ psrgcd + See also: 1/ gcd 2/ modgcd 3/ heugcd 4/ psrgcd Ex1:ezgcd(x^2-2*xy+y^2-1,x-y) Ex2:ezgcd((x+1)^4-y^4,(x+1-y)^2) Ex3:ezgcd((x+y-1)*(x+y+1),(x+y+1)^2) - ''' return GiacMethods['ezgcd'](self,*args) @@ -5590,10 +5152,9 @@ cdef class GiacMethods_base: Help for f2nd: f2nd(Frac or RatFrac) Returns the list built with the numerator and the denominator of the simplified fraction. - See also: 1/ simp2 2/ numer 3/ denom 4/ getNum 5/ getDenom + See also: 1/ simp2 2/ numer 3/ denom 4/ getNum 5/ getDenom Ex1:f2nd(42/12) Ex2:f2nd((x^2+2*x+1)/(x^2-1)) - ''' return GiacMethods['f2nd'](self,*args) @@ -5602,10 +5163,9 @@ cdef class GiacMethods_base: Help for fMax: fMax(Expr,[Var]) Returns the abscissa of the maximum of the expression. - See also: 1/ fMin + See also: 1/ fMin Ex1:fMax(-x^2+2*x+1,x) Ex2:fMax(-x^2+2*x+1,x=1..2) - ''' return GiacMethods['fMax'](self,*args) @@ -5614,12 +5174,11 @@ cdef class GiacMethods_base: Help for fMin: fMin(Expr,[Var]) Returns the abscissa of the minimum of the expression. - See also: 1/ fMax + See also: 1/ fMax Ex1:fMin(x^2-2*x+1,x) Ex2:fMin(x^2-2*x+1,x=1..2) Ex3:fMin((x-3)^2+(y-5)^2+1,[],[x,y],[1,1]) Ex4:fMin((x-3)^2+(y-5)^2+1,[x+y^2=1],[x,y],[1,1]) - ''' return GiacMethods['fMin'](self,*args) @@ -5628,13 +5187,12 @@ cdef class GiacMethods_base: Help for fPart: fPart(Real||LstReal) Returns the fractional part (if x<0 then frac(x)+floor(x)+1=x else frac(x)+floor(x)=x). - See also: 1/ floor 2/ iPart 3/ trunc + See also: 1/ floor 2/ iPart 3/ trunc Ex1:fPart(1/2) Ex2:fPart(-1/2) Ex3:fPart(1.2) Ex4:fPart(-1.2) Ex5:fPart([3.4,sqrt(2)]) - ''' return GiacMethods['fPart'](self,*args) @@ -5643,10 +5201,9 @@ cdef class GiacMethods_base: Help for faces: faces(Polygon or Polyedr(P)) Returns the list of the faces (1 face=matrix(n,3) where the n rows are the n vertices of the face) of the polyhedron P. - See also: 1/ polyhedron + See also: 1/ polyhedron Ex1:faces(polyhedron([0,0,0],[0,5,0],[0,0,5],[1,2,6])) Ex2:faces(polyhedron([0,0,0],[0,5,0],[0,0,5],[1,2,6]))[2] - ''' return GiacMethods['faces'](self,*args) @@ -5655,10 +5212,9 @@ cdef class GiacMethods_base: Help for facteurs_premiers: facteurs_premiers(Intg(a) or LstIntg) Returns the list of prime factors of an integer (each factor is followed by its multiplicity). - See also: 1/ ifactor 2/ factors + See also: 1/ ifactor 2/ factors Ex1:facteurs_premiers(36) Ex2:facteurs_premiers([36,52]) - ''' return GiacMethods['facteurs_premiers'](self,*args) @@ -5667,11 +5223,10 @@ cdef class GiacMethods_base: Help for factor: factor(Expr) Factors a polynomial. - See also: 1/ ifactor 2/ cfactor 3/ partfrac 4/ normal + See also: 1/ ifactor 2/ cfactor 3/ partfrac 4/ normal Ex1:factor(x^4-1) Ex2:factor(x^4-4,sqrt(2)) Ex3:factor(x^4+12*x^3+54*x^2+108*x+81) - ''' return GiacMethods['factor'](self,*args) @@ -5680,10 +5235,9 @@ cdef class GiacMethods_base: Help for factor_xn: factor_xn(Poly(P)) Factors x^n in P (n=degree of polynomial P). - See also: 1/ ifactor 2/ partfrac 3/ normal + See also: 1/ ifactor 2/ partfrac 3/ normal Ex1:factor_xn(x^4-1) Ex2:factor_xn(x^4+12*x^3+54*x^2+108*x+81) - ''' return GiacMethods['factor_xn'](self,*args) @@ -5692,10 +5246,9 @@ cdef class GiacMethods_base: Help for factorial: factorial(Intg(n)|| Real(a)) factorial(n)=n!. For non-integers, factorial(a)=a! = G(a + 1). This calculates the Gamma function. - See also: 1/ comb 2/ perm + See also: 1/ comb 2/ perm Ex1:factorial(4) Ex2:factorial(1.2) - ''' return GiacMethods['factorial'](self,*args) @@ -5704,11 +5257,10 @@ cdef class GiacMethods_base: Help for factoriser: factoriser(Expr) Factors a polynomial. - See also: 1/ ifactor 2/ cfactor 3/ partfrac 4/ normal + See also: 1/ ifactor 2/ cfactor 3/ partfrac 4/ normal Ex1:factoriser(x^4-1) Ex2:factoriser(x^4-4,sqrt(2)) Ex3:factoriser(x^4+12*x^3+54*x^2+108*x+81) - ''' return GiacMethods['factoriser'](self,*args) @@ -5717,10 +5269,9 @@ cdef class GiacMethods_base: Help for factoriser_entier: factoriser_entier(Intg(a)) Factorization of an integer into prime factors. - See also: 1/ factor 2/ ecm_factor + See also: 1/ factor 2/ ecm_factor Ex1:factoriser_entier(50) Ex2:factoriser_entier(123456789) - ''' return GiacMethods['factoriser_entier'](self,*args) @@ -5729,11 +5280,10 @@ cdef class GiacMethods_base: Help for factoriser_sur_C: factoriser_sur_C(Expr) Factorization of the expression in ℂ (on the Gaussian integers if there are more than 2 variables). - See also: 1/ factor + See also: 1/ factor Ex1:factoriser_sur_C(x^2*y+y) Ex2:factoriser_sur_C(x^2*y^2+y^2+4*x^2+4) Ex3:factoriser_sur_C(x^2*y^2+y^2+2*x^2+2) - ''' return GiacMethods['factoriser_sur_C'](self,*args) @@ -5742,10 +5292,9 @@ cdef class GiacMethods_base: Help for factors: factors(Poly or LstPoly) Returns the list of prime factors of a polynomial (each factor is followed by its multiplicity). - See also: 1/ factor 2/ ifactors + See also: 1/ factor 2/ ifactors Ex1:factors(x^4-1) Ex2:factors([x^2,x^2-1]) - ''' return GiacMethods['factors'](self,*args) @@ -5754,9 +5303,8 @@ cdef class GiacMethods_base: Help for fadeev: fadeev(Opt) Option of the pcar or charpoly command to specify the algorithm. - See also: 1/ pcar + See also: 1/ pcar Ex1: pcar([[4,1,-2],[1,2,-1],[2,1,0]],fadeev) - ''' return GiacMethods['fadeev'](self,*args) @@ -5765,9 +5313,8 @@ cdef class GiacMethods_base: Help for false: false() Boolean equal to false or 0. - See also: 1/ true + See also: 1/ true Ex1: a:=false - ''' return GiacMethods['false'](self,*args) @@ -5776,14 +5323,13 @@ cdef class GiacMethods_base: Help for falsepos_solver: falsepos_solver(Opt) Argument for fsolve giving the method for solving a numerical equation. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve(cos(x)=x,x,0..1,bisection_solver) Ex2: fsolve(cos(x)=x,x,0..1,brent_solver) Ex3: fsolve(cos(x)=x,x,0..1,falsepos_solver) Ex4: fsolve(cos(x)=x,x,0,newton_solver) Ex5: fsolve(cos(x)=x,x,0,secant_solver) Ex6: fsolve(cos(x)=x,x,0,steffenson_solver) - ''' return GiacMethods['falsepos_solver'](self,*args) @@ -5792,9 +5338,8 @@ cdef class GiacMethods_base: Help for fclose: fclose(File(f)) Closes the file f. - See also: 1/ fprint 2/ fopen + See also: 1/ fprint 2/ fopen Ex1:fclose(f) - ''' return GiacMethods['fclose'](self,*args) @@ -5803,9 +5348,8 @@ cdef class GiacMethods_base: Help for fcoeff: fcoeff(Lst(root||pole,order)) Returns the polynomial described by the list (root or pole, order). - See also: 1/ pcoeff 2/ froot 3/ proot + See also: 1/ pcoeff 2/ froot 3/ proot Ex1:fcoeff([1,2,0,1,3,-1]) - ''' return GiacMethods['fcoeff'](self,*args) @@ -5814,13 +5358,12 @@ cdef class GiacMethods_base: Help for fdistrib: fdistrib(Expr) Full distribution of * and / over + and -. - See also: 1/ texpand 2/ normal 3/ simplify 4/ ratnormal + See also: 1/ texpand 2/ normal 3/ simplify 4/ ratnormal Ex1:fdistrib((x+y)*(z+1)) Ex2:fdistrib((a+b+c)/d) Ex3:fdistrib((y+x)*(z+y)*(x+z)) Ex4:fdistrib((x+3)^4) Ex5:fdistrib((2*x-2*1)*(x^2-3*x+2)+(x^2-2*x+3)*(2*x-3*1)) - ''' return GiacMethods['fdistrib'](self,*args) @@ -5829,10 +5372,9 @@ cdef class GiacMethods_base: Help for fft: fft(Vect or (Vect(L),Intg(a),Intg(p)) Fast Fourier Transform in ℝ or in the field ℤ/pℤ, with a as primitive n-th root of 1 (n=size(L)). - See also: 1/ ifft + See also: 1/ ifft Ex1:fft([1,2,3,4,0,0,0,0]) Ex2:fft(ranm(128),22798,35969) - ''' return GiacMethods['fft'](self,*args) @@ -5841,13 +5383,12 @@ cdef class GiacMethods_base: Help for fieldplot: fieldplot(Expr,VectVar,[Opt]) fieldplot(f(t,y),[t,y]) draws the plotfield of the diff equation y'=f(t,y). - See also: 1/ interactive_plotode 2/ odeplot 3/ odesolve 4/ desolve + See also: 1/ interactive_plotode 2/ odeplot 3/ odesolve 4/ desolve Ex1:fieldplot(sin(t*y),[t=-5..5,y=-3..3],xstep=0.5,ystep=0.5) Ex2:fieldplot(-t*y,[t,y]) Ex3:fieldplot(-t*y,[t,y],normalize) Ex4:fieldplot(-t*y,[t,y],normalize,xstep=0.5,ystep=0.5) Ex5:fieldplot(-t*y,[t=-6.868..6.868,y=-6.868..6.868],normalize) - ''' return GiacMethods['fieldplot'](self,*args) @@ -5856,13 +5397,12 @@ cdef class GiacMethods_base: Help for find: find(Expr,Vect) List of positions of an object in a list, a string or a set. - See also: 1/ index 2/ member + See also: 1/ index 2/ member Ex1:find(1,[3,x,1,2,1,3]) Ex2:find(2,[0,1,3,2,4,2,5])[0] Ex3:find("a","abracadabrant") Ex4:find("ab","abracadabrant") Ex5:find(1,%{4,3,1,2%}) - ''' return GiacMethods['find'](self,*args) @@ -5871,11 +5411,10 @@ cdef class GiacMethods_base: Help for find_cycles: find_cycles(Graph(G,[length=k||l..u])) Returns the list of elementary cycles of the digraph G. If option "length" is specified, only cycles of length k resp. of length between l and u are returned. - See also: 1/ is_acyclic + See also: 1/ is_acyclic Ex1:find_cycles(digraph(%{[1,2],[1,3],[3,1],[1,4],[2,3],[4,3],[4,5],[5,3],[5,6],[7,6],[8,6],[8,7]%})) Ex2:find_cycles(digraph(%{[1,2],[1,3],[3,1],[1,4],[2,3],[4,3],[4,5],[5,3],[5,6],[7,6],[8,6],[8,7]%}),length=3) Ex3:find_cycles(digraph(%{[1,2],[1,3],[3,1],[1,4],[2,3],[4,3],[4,5],[5,3],[5,6],[7,6],[8,6],[8,7]%}),length=3..4) - ''' return GiacMethods['find_cycles'](self,*args) @@ -5884,9 +5423,8 @@ cdef class GiacMethods_base: Help for findhelp: findhelp(Cmd) Returns help about the command (if ? is infixed see when) . - See also: 1/ ifte 2/ when + See also: 1/ ifte 2/ when Ex1:findhelp(ifactor) - ''' return GiacMethods['findhelp'](self,*args) @@ -5895,12 +5433,11 @@ cdef class GiacMethods_base: Help for fisher: fisher(Intg(n),Intg(m),Real(x0)) Returns the probability density of the Fisher-Snedecor law (n and m are the numbers of degrees of freedom). - See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm + See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm Ex1:fisher(4,10,2.1) Ex2:fisher(4,4,2.1) Ex3: randvector(5,fisher,4,6) Ex4: ranm(2,3,fisher,4,6) - ''' return GiacMethods['fisher'](self,*args) @@ -5909,10 +5446,9 @@ cdef class GiacMethods_base: Help for fisher_cdf: fisher_cdf(Intg(n),Intg(m),Real(x0)) Returns the probability that a Fisher-Snedecor random variable is less than x0 (n and m are the numbers of degrees of freedom). - See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd + See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd Ex1:fisher_cdf(4,4,2.1) Ex2:fisher_cdf(4,10,3.5) - ''' return GiacMethods['fisher_cdf'](self,*args) @@ -5921,10 +5457,9 @@ cdef class GiacMethods_base: Help for fisher_icdf: fisher_icdf(Intg(n),Intg(m),Real(p)) Returns h such as the probability that a Fisher-Snedecor random variable is less than h is p (n and m are the numbers of degrees of freedom and 0<=p<=1). - See also: 1/ fisher_cdf 2/ fisherd + See also: 1/ fisher_cdf 2/ fisherd Ex1:fisher_icdf(4,10,0.95) Ex2:fisher_icdf(4,10,0.05) - ''' return GiacMethods['fisher_icdf'](self,*args) @@ -5933,12 +5468,11 @@ cdef class GiacMethods_base: Help for fisherd: fisherd(Intg(n),Intg(m),Real(x0)) Returns the probability density of the Fisher-Snedecor law (n and m are the numbers of degrees of freedom). - See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm + See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm Ex1:fisherd(4,10,2.1) Ex2:fisherd(4,4,2.1) Ex3: randvector(5,fisher,4,6) Ex4: ranm(2,3,fisher,4,6) - ''' return GiacMethods['fisherd'](self,*args) @@ -5947,10 +5481,9 @@ cdef class GiacMethods_base: Help for fisherd_cdf: fisherd_cdf(Intg(n),Intg(m),Real(x0)) Returns the probability that a Fisher-Snedecor random variable is less than x0 (n and m are the numbers of degrees of freedom). - See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd + See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd Ex1:fisherd_cdf(4,4,2.1) Ex2:fisherd_cdf(4,10,3.5) - ''' return GiacMethods['fisherd_cdf'](self,*args) @@ -5959,10 +5492,9 @@ cdef class GiacMethods_base: Help for fisherd_icdf: fisherd_icdf(Intg(n),Intg(m),Real(p)) Returns h such as the probability that a Fisher-Snedecor random variable is less than h is p (n and m are the numbers of degrees of freedom and 0<=p<=1). - See also: 1/ fisher_cdf 2/ fisherd + See also: 1/ fisher_cdf 2/ fisherd Ex1:fisherd_icdf(4,10,0.95) Ex2:fisherd_icdf(4,10,0.05) - ''' return GiacMethods['fisherd_icdf'](self,*args) @@ -5971,11 +5503,10 @@ cdef class GiacMethods_base: Help for fitdistr: fitdistr(Lst(L),Fnc(D)) Returns the distribution of type D which fits most closely to the i.i.d. samples in the list L. - See also: 1/ normald 2/ poisson 3/ exponentiald 4/ geometric 5/ gammad 6/ betad 7/ cauchyd 8/ weibulld 9/ sample 10/ randvector 11/ randvar + See also: 1/ normald 2/ poisson 3/ exponentiald 4/ geometric 5/ gammad 6/ betad 7/ cauchyd 8/ weibulld 9/ sample 10/ randvector 11/ randvar Ex1:fitdistr(randvector(1000,weibulld,1/2,1),weibull) Ex2: X:=randvar(normal,stddev=9.5):;Y:=randvar(normal,stddev=1.5):;S:=sample(eval(X/Y,0),1000):;Z:=fitdistr(S,cauchy) Ex3: X:=randvar(normal,mean=5,variance=2):;S:=sample(exp(X),1000):;fitdistr(log(S),normal) - ''' return GiacMethods['fitdistr'](self,*args) @@ -5984,9 +5515,8 @@ cdef class GiacMethods_base: Help for flatten: flatten(Lst) Recursively flatten a list containing lists. - See also: 1/ mat2list + See also: 1/ mat2list Ex1:flatten([[1,[2,3],4],[5,6]]) - ''' return GiacMethods['flatten'](self,*args) @@ -5995,12 +5525,11 @@ cdef class GiacMethods_base: Help for float2rational: float2rational(Expr) Converts the expression to a rational or real expression. - See also: 1/ + See also: 1/ Ex1:float2rational(-2) Ex2:float2rational(1.5) Ex3:float2rational(1.4141) Ex4:float2rational(0.156381102937) - ''' return GiacMethods['float2rational'](self,*args) @@ -6009,10 +5538,9 @@ cdef class GiacMethods_base: Help for floor: floor(Real or Cplx) Returns the greatest integer <= to the argument. - See also: 1/ round 2/ ceil 3/ iPart 4/ trunc + See also: 1/ round 2/ ceil 3/ iPart 4/ trunc Ex1:floor(-2.5) Ex2:floor(2.5-4.2*i) - ''' return GiacMethods['floor'](self,*args) @@ -6021,10 +5549,9 @@ cdef class GiacMethods_base: Help for flow_polynomial: flow_polynomial(Graph(G),[Var(x)]) Returns the flow polynomial [or its value at point x] of undirected unweighted graph G. - See also: 1/ chromatic_polynomial 2/ reliability_polynomial 3/ tutte_polynomial + See also: 1/ chromatic_polynomial 2/ reliability_polynomial 3/ tutte_polynomial Ex1:flow_polynomial(graph("tetrahedron")) Ex2:flow_polynomial(graph("tetrahedron"),5) - ''' return GiacMethods['flow_polynomial'](self,*args) @@ -6034,7 +5561,6 @@ cdef class GiacMethods_base: fmod(Real(a),Real(b)) Returns a mod b for a and b floats. Ex1:fmod(10.0,pi) - ''' return GiacMethods['fmod'](self,*args) @@ -6043,9 +5569,8 @@ cdef class GiacMethods_base: Help for foldl: foldl(op,id,Seq(r1,r2,...)) Returns the composition of the binary operator or function op, with an identity or initial value id onto its arguments r1, r2, ..., associating from the left. - See also: 1/ apply 2/ foldr 3/ map + See also: 1/ apply 2/ foldr 3/ map Ex1:foldl(F,init,a,b,c) - ''' return GiacMethods['foldl'](self,*args) @@ -6054,9 +5579,8 @@ cdef class GiacMethods_base: Help for foldr: foldr(op,id,Seq(r1,r2,...)) Returns the composition of the binary operator or function op, with an identity or initial value id onto its arguments r1, r2, ..., associating from the right. - See also: 1/ apply 2/ foldl 3/ map + See also: 1/ apply 2/ foldl 3/ map Ex1:foldr(F,init,a,b,c) - ''' return GiacMethods['foldr'](self,*args) @@ -6065,13 +5589,12 @@ cdef class GiacMethods_base: Help for fonction_derivee: fonction_derivee(Fnc(f)) Returns the derivative function of the function f. - See also: 1/ diff 2/ ' 3/ @ + See also: 1/ diff 2/ ' 3/ @ Ex1:fonction_derivee(sin+id) Ex2:fonction_derivee(sq@sin+id) Ex3:fonction_derivee(ln)(x,y) Ex4:fonction_derivee(ln)([x,y]) - Ex5: (function_diff @@3)(ln)('x') - + Ex5: (function_diff @@3)(ln)('x') ''' return GiacMethods['fonction_derivee'](self,*args) @@ -6080,10 +5603,9 @@ cdef class GiacMethods_base: Help for forward: forward(NULL or Real(n)) The turtle takes n steps forward (by default n=10). - See also: 1/ recule 2/ saute + See also: 1/ recule 2/ saute Ex1: avance 30 Ex2:forward(30) - ''' return GiacMethods['forward'](self,*args) @@ -6092,7 +5614,7 @@ cdef class GiacMethods_base: Help for fourier: fourier(Expr(f(x)),[Var(x),[Var(s)]]) Returns the Fourier transform F(s) of f(x). - See also: 1/ ifourier 2/ fourier_cn 3/ fft + See also: 1/ ifourier 2/ fourier_cn 3/ fft Ex1:fourier(x/(x^3-19x+30),x,s) Ex2:fourier((x^2+1)/(x^2-1),x,s) Ex3:fourier(3x^2+2x+1,x,s) @@ -6109,7 +5631,6 @@ cdef class GiacMethods_base: Ex14:fourier(Gamma(1+i*x/3),x,s) Ex15:fourier(atan(x/4)/x,x,s) Ex16:fourier(piecewise(x<=-1,exp(x+1),x<=1,1,exp(2-2x)),x,s) - ''' return GiacMethods['fourier'](self,*args) @@ -6118,10 +5639,9 @@ cdef class GiacMethods_base: Help for fourier_an: fourier_an(Expr(f(x)),Var(x),Period(T),Intg(n),Real(a)) Returns the n-th Fourier coefficient an=2/T*integrate(f(x)*cos(2*pi*n*x/T),a,a+T). - See also: 1/ fourier_cn 2/ fourier_bn 3/ assume + See also: 1/ fourier_cn 2/ fourier_bn 3/ assume Ex1:fourier_an(x^2,x,2,0,-1) Ex2:fourier_an(x^2,x,2,n,-1) - ''' return GiacMethods['fourier_an'](self,*args) @@ -6130,10 +5650,9 @@ cdef class GiacMethods_base: Help for fourier_bn: fourier_bn(Expr(f(x)),Var(x),Period(T),Intg(n),Real(a)) Returns the n-th Fourier coefficient bn=2/T*integrate(f(x)*sin(2*pi*n*x/T),a,a+T). - See also: 1/ fourier_cn 2/ fourier_an 3/ assume + See also: 1/ fourier_cn 2/ fourier_an 3/ assume Ex1:fourier_bn(x^2,x,2,0,-1) Ex2:fourier_bn(x^2,x,2,n,-1) - ''' return GiacMethods['fourier_bn'](self,*args) @@ -6142,10 +5661,9 @@ cdef class GiacMethods_base: Help for fourier_cn: fourier_cn(Expr(f(x)),Var(x),Period(T),Intg(n),Real(a)) Returns the n-th Fourier coefficient cn=1/T*integrate(f(x)*exp(-2*i*pi*n*x/T),a,a+T). - See also: 1/ fourier_an 2/ fourier_bn 3/ assume + See also: 1/ fourier_an 2/ fourier_bn 3/ assume Ex1:fourier_cn(x^2,x,2,0,-1) Ex2:fourier_cn(x^2,x,2,n,-1) - ''' return GiacMethods['fourier_cn'](self,*args) @@ -6154,11 +5672,10 @@ cdef class GiacMethods_base: Help for fprint: fprint(File(f),Var,[Var,Var...]) Writes in the file f some data. - See also: 1/ fopen 2/ fclose + See also: 1/ fopen 2/ fclose Ex1:fprint(f,x+1,"2") Ex2:fprint(f,"blabla") Ex3:fprint(f,Unquoted,"blabla") - ''' return GiacMethods['fprint'](self,*args) @@ -6167,13 +5684,12 @@ cdef class GiacMethods_base: Help for frac: frac(Real||LstReal) Returns the fractional part (if x<0 then frac(x)+floor(x)+1=x else frac(x)+floor(x)=x). - See also: 1/ floor 2/ iPart 3/ trunc + See also: 1/ floor 2/ iPart 3/ trunc Ex1:frac(1/2) Ex2:frac(-1/2) Ex3:frac(1.2) Ex4:frac(-1.2) Ex5:frac([3.4,sqrt(2)]) - ''' return GiacMethods['frac'](self,*args) @@ -6182,9 +5698,8 @@ cdef class GiacMethods_base: Help for fracmod: fracmod(Expr(Xpr),Intg(n)) Returns the fraction a/b such as b*Xpr=a mod n, -sqrt(n)/20),Real(b>0),Real(x>=0)) Returns the probability density of the Gamma law (=x^(a-1)*exp(-b*x)*b^a/Gamma(a)). - See also: 1/ gammad_cdf; 2/ gammad_icdf + See also: 1/ gammad_cdf; 2/ gammad_icdf Ex1:gammad(2.2,1.5,0.8) - ''' return GiacMethods['gammad'](self,*args) @@ -6318,10 +5823,9 @@ cdef class GiacMethods_base: Help for gammad_cdf: gammad_cdf(Real(a>0),Real(b>0),Real(x0>=0),[Real(y0>=0)]) Returns the probability that a Gamma random variable (with a and b as parameters) is less than x0 or between x0 and y0. - See also: 1/ gammad 2/ gammad_icdf + See also: 1/ gammad 2/ gammad_icdf Ex1:gammad_cdf(2,1,2.96) Ex2:gammad_cdf(2,1,1.4,2.96) - ''' return GiacMethods['gammad_cdf'](self,*args) @@ -6330,10 +5834,9 @@ cdef class GiacMethods_base: Help for gammad_icdf: gammad_icdf(Real(a>0),Real(b>0),Real(0<=p<=1)) Returns h such that the probability that a Gamma random variable is less than h is p (0<=p<=1). - See also: 1/ gammad_cdf 2/ gammad + See also: 1/ gammad_cdf 2/ gammad Ex1:gammad_icdf(2,1,0.95) Ex2:gammad_icdf(2,1,0.5) - ''' return GiacMethods['gammad_icdf'](self,*args) @@ -6342,10 +5845,9 @@ cdef class GiacMethods_base: Help for gammavariate: gammavariate(Real(a),Real(b)) Returns a random real according to the Gamma distribution with parameters a>0 and b>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:gammavariate(1,2) Ex2:gammavariate(1.5,4) - ''' return GiacMethods['gammavariate'](self,*args) @@ -6354,9 +5856,8 @@ cdef class GiacMethods_base: Help for gauss: gauss(Expr,VectVar) Splits a quadratic form as a sum/difference of squares. - See also: 1/ cholesky + See also: 1/ cholesky Ex1:gauss(x^2+2*a*x*y,[x,y]) - ''' return GiacMethods['gauss'](self,*args) @@ -6365,12 +5866,11 @@ cdef class GiacMethods_base: Help for gauss15: gauss15(Opt) Option of the area command. - See also: 1/ area + See also: 1/ area Ex1: area(x^2,x=0..1,5,simpson) Ex2: area(x^2,x=0..1,5,rombergt) Ex3: area(x^2,x=0..1,5,rombergm) Ex4:gauss15(area(x^2,x=0..1,5,gauss15)) - ''' return GiacMethods['gauss15'](self,*args) @@ -6379,12 +5879,11 @@ cdef class GiacMethods_base: Help for gauss_seidel_linsolve: gauss_seidel_linsolve([Real(omega)],Mtrx(A),Vect(b),Real(eps),[Int(maxiter)]) Resolution of a linear system A*X=b by the iterative Gauss-Seidel method (by defaut omega=1) or by relaxation method, with eps as error margin and a number of iterations less than maxiter. - See also: 1/ jacobi_linsolve 2/ linsolve + See also: 1/ jacobi_linsolve 2/ linsolve Ex1: a:=[[100,2],[2,100]];gauss_seidel_linsolve(a,[0,1],1e-12); - Ex2: a:=[[100,2],[2,100]];gauss_seidel_linsolve(table(a),[0,1],1e-12); + Ex2: a:=[[100,2],[2,100]];gauss_seidel_linsolve(table(a),[0,1],1e-12); Ex3: a:=[[100,2],[2,100]];gauss_seidel_linsolve(1.5,a,[0,1],1e-12); - Ex4: a:=[[100,2],[2,100]];gauss_seidel_linsolve(1.5,table(a),[0,1],1e-12); - + Ex4: a:=[[100,2],[2,100]];gauss_seidel_linsolve(1.5,table(a),[0,1],1e-12); ''' return GiacMethods['gauss_seidel_linsolve'](self,*args) @@ -6393,9 +5892,8 @@ cdef class GiacMethods_base: Help for gaussian_window: gaussian_window(Lst,[Real(a)],[Interval(n1..n2)]) Applies the Gaussian windowing function with parameter 0= b (default a=0.2 and b=1/6.) - See also: 1/ gbasis 2/ gbasis_max_pairs 3/ gbasis_reinject + See also: 1/ gbasis 2/ gbasis_max_pairs 3/ gbasis_reinject Ex1:gbasis_reinject(0.1) Ex2:gbasis_reinject(0.1,0.05) - ''' return GiacMethods['gbasis_reinject'](self,*args) @@ -6470,9 +5963,8 @@ cdef class GiacMethods_base: Help for gbasis_simult_primes: gbasis_simult_primes(Intg) Gbasis fine-tuning: maximal number of Groebner basis modulo a prime that are computed simultaneously to rebuild a Groebner basis over Q (default 16). Set it to a smaller value if short in memory. - See also: 1/ gbasis 2/ gbasis_max_pairs 3/ gbasis_reinject + See also: 1/ gbasis 2/ gbasis_max_pairs 3/ gbasis_reinject Ex1:gbasis_simult_primes(3) - ''' return GiacMethods['gbasis_simult_primes'](self,*args) @@ -6481,13 +5973,12 @@ cdef class GiacMethods_base: Help for gcd: gcd((Intg(a) or Poly),(Intg(b) or Poly)) Returns the greatest common divisor of 2 polynomials of several variables or of 2 integers or of 2 rationals. - See also: 1/ lcm 2/ euler 2/ modgcd 3/ ezgcd 4/ psrgcd 5/ heugcd 6/ Gcd + See also: 1/ lcm 2/ euler 2/ modgcd 3/ ezgcd 4/ psrgcd 5/ heugcd 6/ Gcd Ex1:gcd(45,75) Ex2:gcd(15/7,50/9) Ex3:gcd(x^2-2*x+1,x^3-1) Ex4:gcd(t^2-2*t+1,t^2+t-2) Ex5:gcd((x^2-1)*(y^2-1)*z^2,x^3*y^3*z+(-(y^3))*z+x^3*z-z) - ''' return GiacMethods['gcd'](self,*args) @@ -6496,12 +5987,11 @@ cdef class GiacMethods_base: Help for gcdex: gcdex((Poly or Lst),(Poly or Lst),[Var]) Extended greatest common divisor of 2 polynomials. - See also: 1/ gcd 2/ iegcd + See also: 1/ gcd 2/ iegcd Ex1:gcdex((x-1)^2,x^3-1) Ex2:gcdex((X-1)^2,X^3-1,X) Ex3:gcdex([1,-2,1],[1,0,0,-1]) Ex4:gcdex([1,-2,1],[1,-1,2]) - ''' return GiacMethods['gcdex'](self,*args) @@ -6510,11 +6000,10 @@ cdef class GiacMethods_base: Help for genpoly: genpoly(Poly(P),Intg(b),Var) Returns the reconstruction of a n-variables polynomial Q(-b/2<=coef<=b/2) from an (n-1)-variable polynomial P and a base b (subst(Q,var=b)=P). - See also: 1/ + See also: 1/ Ex1:genpoly(15,4,x) Ex2:genpoly(7*y+5,6,x) Ex3:genpoly(7*y-5*z,10,x) - ''' return GiacMethods['genpoly'](self,*args) @@ -6523,12 +6012,11 @@ cdef class GiacMethods_base: Help for geometric: geometric(Real(p),Intg(k)) Returns the value at k of the geometric law with parameter p (0cos(2*x)) Ex4:getType(1.414) - ''' return GiacMethods['getType'](self,*args) @@ -6611,9 +6093,8 @@ cdef class GiacMethods_base: Help for get_edge_attribute: get_edge_attribute(Graph(G),Edge(e),Seq(tag1=value1,tag2=value2,..)) Returns the attributes tag1, tag2, ... assigned to edge e in G as a sequence of the corresponding values. - See also: 1/ discard_edge_attribute 2/ set_edge_attribute 3/ list_edge_attributes + See also: 1/ discard_edge_attribute 2/ set_edge_attribute 3/ list_edge_attributes Ex1:get_edge_attribute(cycle_graph(3),[1,2],"cost") - ''' return GiacMethods['get_edge_attribute'](self,*args) @@ -6622,9 +6103,8 @@ cdef class GiacMethods_base: Help for get_edge_weight: get_edge_weight(Graph(G),Edge(e)) Returns the weight of the edge e in the weighted graph G. - See also: 1/ is_weighted 2/ make_weighted 3/ set_edge_weight 4/ weight_matrix + See also: 1/ is_weighted 2/ make_weighted 3/ set_edge_weight 4/ weight_matrix Ex1:get_edge_weight(graph(%{[[1,2],5],[[2,3],6]%}),[1,2]) - ''' return GiacMethods['get_edge_weight'](self,*args) @@ -6633,9 +6113,8 @@ cdef class GiacMethods_base: Help for get_graph_attribute: get_graph_attribute(Graph(G),Seq(tag1=value1,tag2=value2,..)) Return the graph attributes tag1, tag2, ..., as a sequence of the corresponding values. - See also: 1/ discard_graph_attribute 2/ set_graph_attribute 3/ list_graph_attributes + See also: 1/ discard_graph_attribute 2/ set_graph_attribute 3/ list_graph_attributes Ex1:get_graph_attribute(cycle_graph(3),"name") - ''' return GiacMethods['get_graph_attribute'](self,*args) @@ -6644,9 +6123,8 @@ cdef class GiacMethods_base: Help for get_vertex_attribute: get_vertex_attribute(Graph(G),Vrtx(v),Seq(tag1=value1,tag2=value2,..)) Returns the attributes tag1, tag2, ... assigned to vertex v in G as a sequence of the corresponding values. - See also: 1/ discard_vertex_attribute 2/ set_vertex_attribute 3/ list_vertex_attributes + See also: 1/ discard_vertex_attribute 2/ set_vertex_attribute 3/ list_vertex_attributes Ex1:get_vertex_attribute(cycle_graph(3),1,"supply") - ''' return GiacMethods['get_vertex_attribute'](self,*args) @@ -6655,10 +6133,9 @@ cdef class GiacMethods_base: Help for girth: girth(Graph(G)) Returns the length of the shortest cycle in the undirected unweighted graph G. - See also: 1/ odd_girth + See also: 1/ odd_girth Ex1:girth(graph("petersen")) Ex2:girth(hypercube_graph(3)) - ''' return GiacMethods['girth'](self,*args) @@ -6667,10 +6144,9 @@ cdef class GiacMethods_base: Help for gl_showaxes: gl_showaxes(Opt=Boolean) Option that shows or hides axes. - See also: 1/ switch_axes 2/ axes + See also: 1/ switch_axes 2/ axes Ex1: gl_showaxes=true;plot(sin(x)) - Ex2: gl_showaxes=false;plot(sin(x)) - + Ex2: gl_showaxes=false;plot(sin(x)) ''' return GiacMethods['gl_showaxes'](self,*args) @@ -6679,9 +6155,8 @@ cdef class GiacMethods_base: Help for grad: grad(Expr(Xpr),LstVar) Returns the gradient of the expression Xpr. - See also: 1/ hessian + See also: 1/ hessian Ex1:grad(2*x^2*y-x*z^3,[x,y,z]) - ''' return GiacMethods['grad'](self,*args) @@ -6690,10 +6165,9 @@ cdef class GiacMethods_base: Help for gramschmidt: gramschmidt(Basis(B),ScalarProd(Sp)) Returns an orthonormal basis of E with basis B for the scalar product Sp. - See also: 1/ + See also: 1/ Ex1:gramschmidt(-2) Ex2:gramschmidt([1,1+x],(p,q)->integrate(p*q,x,-1,1)) - ''' return GiacMethods['gramschmidt'](self,*args) @@ -6702,7 +6176,7 @@ cdef class GiacMethods_base: Help for graph: graph([Lst(V)],[Set(E)],[Mtrx(A)],[options]) Create an (un)directed (un)weighted graph from vertices V, edges E, and/or adjacency or weight matrix A. All parameters are optional. - See also: 1/ digraph 2/ trail + See also: 1/ digraph 2/ trail Ex1:graph(5) Ex2:graph([a,b,c]) Ex3:graph([1,2,3],%{[1,2],[2,3],[3,1]%}) @@ -6710,7 +6184,6 @@ cdef class GiacMethods_base: Ex5:graph([a,b,c],[[0,2,0],[2,0,3],[0,3,0]]) Ex6:graph("petersen") Ex7:graph([[0,1,1,0],[1,0,0,1],[1,0,0,0],[0,1,0,0]]) - ''' return GiacMethods['graph'](self,*args) @@ -6719,9 +6192,8 @@ cdef class GiacMethods_base: Help for graph_automorphisms: graph_automorphisms(Graph(G)) Returns the sequence of generators of Aut(G), the automorphism group of G. Each element is a permutation in the form of list of disjoint cycles. - See also: 1/ cycles2permu 2/ isomorphic_copy 3/ permute_vertices + See also: 1/ cycles2permu 2/ isomorphic_copy 3/ permute_vertices Ex1:graph_automorphisms(graph("petersen")) - ''' return GiacMethods['graph_automorphisms'](self,*args) @@ -6730,10 +6202,9 @@ cdef class GiacMethods_base: Help for graph_charpoly: graph_charpoly(Graph(G),[Var(x)]) Returns the value p(x) of the characteristic polynomial p of G. If x is omitted, a list of coefficients of p is returned. - See also: 1/ graph_spectrum 2/ charpoly + See also: 1/ graph_spectrum 2/ charpoly Ex1:graph_charpoly(graph(%{[1,2],[2,3]%})) Ex2:graph_charpoly(graph("shrikhande")) - ''' return GiacMethods['graph_charpoly'](self,*args) @@ -6742,9 +6213,8 @@ cdef class GiacMethods_base: Help for graph_complement: graph_complement(Graph(G)) Return the graph with the same vertex set as G, but whose edge (arc) set consists of the edges (arcs) not present in G. - See also: 1/ edges + See also: 1/ edges Ex1:graph_complement(cycle_graph(5)) - ''' return GiacMethods['graph_complement'](self,*args) @@ -6753,9 +6223,8 @@ cdef class GiacMethods_base: Help for graph_diameter: graph_diameter(Graph(G)) Returns the maximum distance between a pair of vertices in G or +infinity if G is disconnected. - See also: 1/ allpairs_distance 2/ dijkstra 3/ shortest_path 4/ vertex_distance + See also: 1/ allpairs_distance 2/ dijkstra 3/ shortest_path 4/ vertex_distance Ex1:graph_diameter(graph("petersen")) - ''' return GiacMethods['graph_diameter'](self,*args) @@ -6764,9 +6233,8 @@ cdef class GiacMethods_base: Help for graph_equal: graph_equal(Graph(G1),Graph(G2)) Returns true iff the input graphs G1 and G2 are equal, that is when the sets of vertices and edges of G1 and G2, as well as the orderings of vertices in both graphs, mutually coincide. If the graphs are weighted (they must both be (un)weighted and (un)directed), weights given to the same edge in two graphs must be equal. - See also: 1/ edges 2/ graph_vertices + See also: 1/ edges 2/ graph_vertices Ex1:graph_equal(graph([1,2,3],%{[1,2],[2,3],[3,1]%}),graph(trail(1,2,3,1))) - ''' return GiacMethods['graph_equal'](self,*args) @@ -6775,9 +6243,8 @@ cdef class GiacMethods_base: Help for graph_join: graph_join(Graph(G),Graph(H)) Returns the graph obtained by connecting every vertex from G with every vertex from H. The vertex labels in the resulting graph are strings of form "1:u" and "2:v" where u and v are vertices from G and H, respectively. - See also: 1/ disjoint_union 2/ graph_union + See also: 1/ disjoint_union 2/ graph_union Ex1:graph_join(edges(graph_join(cycle_graph(3),graph(2)))) - ''' return GiacMethods['graph_join'](self,*args) @@ -6786,9 +6253,8 @@ cdef class GiacMethods_base: Help for graph_power: graph_power(Graph(G),Intg(k)) Returns the k-th power of G, where two vertices are connected iff there exists a path of length at most k in the original graph. - See also: 1/ adjacency matrix 2/ graph_diameter 3/ shortest_path + See also: 1/ adjacency matrix 2/ graph_diameter 3/ shortest_path Ex1:graph_power(edges(graph_power(path_graph(5),3))) - ''' return GiacMethods['graph_power'](self,*args) @@ -6797,10 +6263,9 @@ cdef class GiacMethods_base: Help for graph_rank: graph_rank(Graph(G),[Lst(E)]) Returns the graph rank of G. If optional set E of edges is given, the rank of the spanning subgraph of G with edge set E is returned. - See also: 1/ connected_components 2/ number_of_vertices + See also: 1/ connected_components 2/ number_of_vertices Ex1:graph_rank(graph(%{[1,2],[3,4],[4,5]%})) Ex2:graph_rank(graph(%{[1,2],[3,4],[4,5]%}),[[1,2],[3,4]) - ''' return GiacMethods['graph_rank'](self,*args) @@ -6809,9 +6274,8 @@ cdef class GiacMethods_base: Help for graph_spectrum: graph_spectrum(Graph(G)) Returns the graph spectrum of G as a list of lists with two elements, each containing an eigenvalue and its multiplicity. - See also: 1/ graph_charpoly 2/ seidel_spectrum 3/ is_integer_graph + See also: 1/ graph_charpoly 2/ seidel_spectrum 3/ is_integer_graph Ex1:graph_spectrum(cycle_graph(5)) - ''' return GiacMethods['graph_spectrum'](self,*args) @@ -6820,9 +6284,8 @@ cdef class GiacMethods_base: Help for graph_union: graph_union(Seq(G1,G2,...)) Returns the union of the graphs G1, G2, ... The set of vertices of the resulting graph is the union of the sets of vertices of the input graphs and the set of edges of the resulting graph is the union of sets of edges of the input graphs. If the input graphs are weighted, the weight of any common edge is the sum of the weights of that edge in G1, G2, ... - See also: 1/ disjoint_union 2/ graph_join + See also: 1/ disjoint_union 2/ graph_join Ex1:graph_union(edges(graph_union(cycle_graph(4),path_graph(5)))) - ''' return GiacMethods['graph_union'](self,*args) @@ -6831,9 +6294,8 @@ cdef class GiacMethods_base: Help for graph_vertices: graph_vertices(Graph(G)) Return the list of vertices in G. - See also: 1/ add_vertex 2/ graph 3/ neighbors 4/ permute_vertices 5/ relabel_vertices + See also: 1/ add_vertex 2/ graph 3/ neighbors 4/ permute_vertices 5/ relabel_vertices Ex1:graph_vertices(graph(%{[a,c],[b,c],[a,b]%})) - ''' return GiacMethods['graph_vertices'](self,*args) @@ -6842,11 +6304,10 @@ cdef class GiacMethods_base: Help for greduce: greduce(Poly,LstPoly,LstVar,[order]) Returns the remainder of the division of a polynomial by a Groebner basis. - See also: 1/ gbasis + See also: 1/ gbasis Ex1:greduce(x*y-1,[x^2-y^2,2*x*y-y^2,y^3],[x,y]) Ex2:greduce(x1^2*x3^2,[x3^3-1,-x2^2-x2*x3-x3^2,x1+x2+x3],[x1,x2,x3],tdeg) Ex3:greduce(x1^2*x3^2-x2,[x3^3-1,-x2^2-x2*x3-x3^2,x1+x2+x3],[x1,x2,x3]) - ''' return GiacMethods['greduce'](self,*args) @@ -6855,9 +6316,8 @@ cdef class GiacMethods_base: Help for greedy_color: greedy_color(Graph(G),[Permu(p)]) Returns the list of vertex colors (positive integers) obtained by coloring vertices one at a time [in the order given by permutation p], assigning to it the smallest available color. - See also: 1/ is_vertex_colorable 2/ chromatic_number + See also: 1/ is_vertex_colorable 2/ chromatic_number Ex1:greedy_color(graph("petersen")) - ''' return GiacMethods['greedy_color'](self,*args) @@ -6866,9 +6326,8 @@ cdef class GiacMethods_base: Help for grid_graph: grid_graph(Intg(m),Intg(n),[triangle]) Returns a [triangular] grid graph on m*n vertices, where m,n>=2. - See also: 1/ torus_grid_graph + See also: 1/ torus_grid_graph Ex1:grid_graph(5,8) - ''' return GiacMethods['grid_graph'](self,*args) @@ -6877,9 +6336,8 @@ cdef class GiacMethods_base: Help for groupermu: groupermu(Permut(a),Permut(b)) Returns the group of permutations generated by a and b. - See also: 1/ + See also: 1/ Ex1:groupermu([1,2,0],[3,1,2,0]) - ''' return GiacMethods['groupermu'](self,*args) @@ -6888,10 +6346,9 @@ cdef class GiacMethods_base: Help for hadamard: hadamard(Mtrx,Mtrx) Hadamard bound of a matrix or element by element multiplication of 2 matrices. - See also: 1/ .* 2/ * + See also: 1/ .* 2/ * Ex1:hadamard([[1,2],[3,4]]) Ex2:hadamard([[1,2],[3,4]],[[3,4],[5,6]]) - ''' return GiacMethods['hadamard'](self,*args) @@ -6900,10 +6357,9 @@ cdef class GiacMethods_base: Help for half_cone: half_cone(Pnt(A),Vect(v),Real(t),[Real(h)]) Draws a half-cone with vertex A, direction v and with half_angle=t [and with altitude h]. - See also: 1/ cone 2/ cylinder + See also: 1/ cone 2/ cylinder Ex1:half_cone([0,0,0],[0,0,1],pi/6) Ex2:half_cone([0,0,0],[0,1,1],pi/6,-4) - ''' return GiacMethods['half_cone'](self,*args) @@ -6912,10 +6368,9 @@ cdef class GiacMethods_base: Help for half_line: half_line((Pnt or Cplx),(Pnt or Cplx)) half_line(A,B) draws the half-line AB with A as origin. - See also: 1/ line + See also: 1/ line Ex1:half_line(i,1+i) Ex2:half_line(point(i),point(1+i)) - ''' return GiacMethods['half_line'](self,*args) @@ -6927,7 +6382,6 @@ cdef class GiacMethods_base: Ex1:halftan(sin(x)) Ex2:halftan(cos(x)) Ex3:halftan(tan(x)) - ''' return GiacMethods['halftan'](self,*args) @@ -6936,9 +6390,8 @@ cdef class GiacMethods_base: Help for halftan_hyp2exp: halftan_hyp2exp(ExprTrig) Transforms the trigonometric functions in tan(x/2) and hyperbolic functions to exp. - See also: 1/ hyp2exp 2/ halftan + See also: 1/ hyp2exp 2/ halftan Ex1:halftan_hyp2exp(sin(x)+sinh(x)) - ''' return GiacMethods['halftan_hyp2exp'](self,*args) @@ -6947,9 +6400,8 @@ cdef class GiacMethods_base: Help for halt: halt(NULL) Puts a program in step-by-step debug mode. - See also: 1/ + See also: 1/ Ex1:halt() - ''' return GiacMethods['halt'](self,*args) @@ -6959,7 +6411,6 @@ cdef class GiacMethods_base: hamdist(Intg,Intg) Bitwise Hamming distance. Ex1:hamdist(0x12,0x38) - ''' return GiacMethods['hamdist'](self,*args) @@ -6968,9 +6419,8 @@ cdef class GiacMethods_base: Help for hamming_window: hamming_window(Lst,[Interval(n1..n2)]) Applies the Hamming windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ bartlett_hann_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ bartlett_hann_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(hamming_window(randvector(1000,0..1))) - ''' return GiacMethods['hamming_window'](self,*args) @@ -6979,9 +6429,8 @@ cdef class GiacMethods_base: Help for hann_poisson_window: hann_poisson_window(Lst,[Interval(n1..n2)]) Applies the Hann-Poisson windowing function with parameter a (by default a=1) to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ bartlett_hann_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ bartlett_hann_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(hann_poisson_window(randvector(1000,0..1),2)) - ''' return GiacMethods['hann_poisson_window'](self,*args) @@ -6990,9 +6439,8 @@ cdef class GiacMethods_base: Help for hann_window: hann_window(Lst,[Interval(n1..n2)]) Applies the Hann windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ bartlett_hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ bartlett_hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(hann_window(randvector(1000,0..1))) - ''' return GiacMethods['hann_window'](self,*args) @@ -7001,12 +6449,11 @@ cdef class GiacMethods_base: Help for harmonic_conjugate: harmonic_conjugate(Line or Pnt(A),Line or Pnt(B),Line or Pnt(C)) Returns the harmonic conjugate C with respect to A and B of 3 points or of 3 parallel or concurrent lines or the line of conjugates of a point with respect to 2 lines. - See also: 1/ is_harmonic 2/ harmonic_division + See also: 1/ is_harmonic 2/ harmonic_division Ex1:harmonic_conjugate(0,2,3/2) Ex2:harmonic_conjugate(0,1+i,2+2*i) Ex3:harmonic_conjugate(line(0,1+i),line(0,3+i),line(0,i)) Ex4:harmonic_conjugate(line(0,1+i),line(0,3+i),point(3/2+i)) - ''' return GiacMethods['harmonic_conjugate'](self,*args) @@ -7015,12 +6462,11 @@ cdef class GiacMethods_base: Help for harmonic_division: harmonic_division(Pnt or Line,Pnt or Line,Pnt or Line,Var) Returns 4 points (resp lines) and affects the last argument, such that the 4 points (resp lines) are in a harmonic division and assigns the fourth point to the variable name. - See also: 1/ harmonic_conjugate 2/ is_harmonic + See also: 1/ harmonic_conjugate 2/ is_harmonic Ex1:harmonic_division(0,2,3/2,D) Ex2:harmonic_division(0,1+i,2+2*i,D) Ex3:harmonic_division(line(i,0),line(i,1+i),line(i,3+2*i),D) Ex4:harmonic_division(line(0,1+i),line(0,3+i),line(0,i),D) - ''' return GiacMethods['harmonic_division'](self,*args) @@ -7029,10 +6475,9 @@ cdef class GiacMethods_base: Help for has: has(Expr,Var) Checks if a variable is in an expression. - See also: 1/ lname 2/ lvar + See also: 1/ lname 2/ lvar Ex1:has(x+y,x) Ex2:has(x+y,n) - ''' return GiacMethods['has'](self,*args) @@ -7041,10 +6486,9 @@ cdef class GiacMethods_base: Help for has_arc: has_arc(Graph(G),Edge(e)) Returns true iff the arc e=[i,j] is contained in digraph G or, if e={i,j} is a set, iff G has both edges [i,j] and [j,i]. - See also: 1/ edges 2/ has_edge + See also: 1/ edges 2/ has_edge Ex1:has_arc(digraph(trail(1,2,3,4,1)),[4,2]) Ex2:has_arc(digraph(trail(1,2,3,4,1)),%{4,2%}) - ''' return GiacMethods['has_arc'](self,*args) @@ -7053,9 +6497,8 @@ cdef class GiacMethods_base: Help for has_edge: has_edge(Graph(G),Edge(e)) Returns true iff the edge e=[i,j] is contained in undirected graph G. - See also: 1/ edges 2/ has_arc + See also: 1/ edges 2/ has_arc Ex1:has_edge(graph(trail(1,2,3,4,1)),[2,4]) - ''' return GiacMethods['has_edge'](self,*args) @@ -7064,7 +6507,7 @@ cdef class GiacMethods_base: Help for hasard: hasard(Intg(n) or Interval(p..n) or NULL,[Intg(b1) or Lst(L)],[Intg(b2)]) (hasard n)=a random integer (resp (hasard p,n)=a real or hasard(p..n)=a real function) with uniform distribution in 0..n-1 (resp in [p;n])(hasard= (hasard 0,1)=a random real in [0,1[) or hasard(n,b1,b2)=n integers between b1 and b2 or hasard(n,L)=n elements of L. If hasard has only one argument, () are not necessary (compatibility with turtle language). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ srand + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ srand Ex1: hasard 4 Ex2: hasard(4) Ex3:hasard(0,2) @@ -7072,7 +6515,6 @@ cdef class GiacMethods_base: Ex5: f:=hasard 0..2 Ex6:hasard(3,1,10) Ex7:hasard(3,["r","r","r","b","n"]) - ''' return GiacMethods['hasard'](self,*args) @@ -7081,11 +6523,10 @@ cdef class GiacMethods_base: Help for head: head(Vect or Seq or Str) Shows the first element of a vector or a sequence or a string. - See also: 1/ back 2/ tail 3/ mid 4/ left 5/ right + See also: 1/ back 2/ tail 3/ mid 4/ left 5/ right Ex1:head(1,2,3) Ex2:head([1,2,3]) Ex3:head("bonjour") - ''' return GiacMethods['head'](self,*args) @@ -7094,11 +6535,10 @@ cdef class GiacMethods_base: Help for heading: heading(NULL or Real) Returns the turtle cap in degrees or turns the turtle in the direction given by the argument. - See also: 1/ position 2/ initialise + See also: 1/ position 2/ initialise Ex1: cap Ex2:heading() Ex3:heading(cap 90) - ''' return GiacMethods['heading'](self,*args) @@ -7107,8 +6547,7 @@ cdef class GiacMethods_base: Help for heapify: heapify(List) Partial ordering of a list as a heap. - See also: 1/ heappush 2/ heappop - + See also: 1/ heappush 2/ heappop ''' return GiacMethods['heapify'](self,*args) @@ -7117,8 +6556,7 @@ cdef class GiacMethods_base: Help for heappop: heappop(List) Removes and returns the root node of a heap. - See also: 1/ heapify 2/ heappush - + See also: 1/ heapify 2/ heappush ''' return GiacMethods['heappop'](self,*args) @@ -7127,8 +6565,7 @@ cdef class GiacMethods_base: Help for heappush: heappush(List,Object) Adds an object in a heap. - See also: 1/ heapify 2/ heappop - + See also: 1/ heapify 2/ heappop ''' return GiacMethods['heappush'](self,*args) @@ -7137,10 +6574,9 @@ cdef class GiacMethods_base: Help for hermite: hermite(Intg(n)||Matr(A)) Returns the Hermite polynomial of degree n or the Hermite normal form for a matrix with polynomial coefficients (I,U such that I*A=U). - See also: 1/ legendre 2/ laguerre 3/ smith 4/ ihermite 5/ ismith + See also: 1/ legendre 2/ laguerre 3/ smith 4/ ihermite 5/ ismith Ex1:hermite(3) Ex2: n:=5; a:=ranm(n,n) % 17; l,u:=hermite(x-a);normal(l*(x-a)-u); - ''' return GiacMethods['hermite'](self,*args) @@ -7149,13 +6585,12 @@ cdef class GiacMethods_base: Help for hessenberg: hessenberg(Mtrx(A),[Intg(n)]) Matrix reduction to Hessenberg form. Returns [P,B] such that B=inv(P)*A*P, by default n=0 the result is exact else the result is numeric. For n=-1 B is triangular, n=-2 P is orthogonal and if n is prime the result is mod n. - See also: 1/ SCHUR + See also: 1/ SCHUR Ex1:hessenberg([[1,2,3],[4,5,6],[7,8,1]]) Ex2:hessenberg([[1,2,3,4],[4,5,6,7],[7,8,9,0],[0,1,2,3]]) Ex3:hessenberg([[1,2,3],[4,5,6],[7,8,1]],-1) Ex4:hessenberg([[1,2,3],[4,5,6],[7,8,1]],-2) Ex5:hessenberg([[1,2,3],[4,5,6],[7,8,1]],3) - ''' return GiacMethods['hessenberg'](self,*args) @@ -7164,9 +6599,8 @@ cdef class GiacMethods_base: Help for hessian: hessian(Expr(Xpr),LstVar) Returns the hessian of the expression Xpr. - See also: 1/ grad + See also: 1/ grad Ex1:hessian(2*x^2*y-x*z,[x,y,z]) - ''' return GiacMethods['hessian'](self,*args) @@ -7175,9 +6609,8 @@ cdef class GiacMethods_base: Help for heugcd: heugcd(Poly,Poly) GCD of 2 polynomials, with the algorithm called heuristic pgcd. - See also: 1/ gcd 2/ modgcd 3/ ezgcd 4/ psrgcd + See also: 1/ gcd 2/ modgcd 3/ ezgcd 4/ psrgcd Ex1:heugcd(x^4-1,(x-1)^2) - ''' return GiacMethods['heugcd'](self,*args) @@ -7186,12 +6619,11 @@ cdef class GiacMethods_base: Help for hexagon: hexagon(Pnt(A)||Cplx,Pnt(B)||Cplx,[Pnt(P)],[Var(C)],[Var(D)],[Var(E)],[Var(F)]) Returns and draws the hexagon of side AB (ABCDEF is direct) (in the plane ABP). - See also: 1/ isopolygon 2/ polygon + See also: 1/ isopolygon 2/ polygon Ex1:hexagon(i,1+i) Ex2:hexagon(i,1+i,C,D,E,F) Ex3:hexagon(point(0,0,0),point(3,3,3),point(0,0,3)) Ex4:hexagon(point(0,0,0),point(3,3,3),point(0,0,3),C,D,E,F) - ''' return GiacMethods['hexagon'](self,*args) @@ -7200,9 +6632,8 @@ cdef class GiacMethods_base: Help for highlight_edges: highlight_edges(Graph(G),Edge(e)||Lst(E),[Color(c)||Lst(C)]) Changes color of edge e resp. colors of edges in E of the input graph V to c resp C (by default red) and returns the modified copy of G. - See also: 1/ highlight_vertex 2/ highlight_subgraph 3/ highlight_trail + See also: 1/ highlight_vertex 2/ highlight_subgraph 3/ highlight_trail Ex1: draw_graph(highlight_edges(cycle_graph(3),[1,2])) - ''' return GiacMethods['highlight_edges'](self,*args) @@ -7211,9 +6642,8 @@ cdef class GiacMethods_base: Help for highlight_subgraph: highlight_subgraph(Graph(G),Graph(S)||Lst(S1,S2,..),Seq(c1,c2)) Changes colors of edges and vertices from the sugbraph S or list of subgraphs S1, S2, ... of G to c1 and c2, respectively (red and green by default), and returns the modified copy of G. - See also: 1/ highlight_edges 2/ highlight_vertex 3/ highlight_trail + See also: 1/ highlight_edges 2/ highlight_vertex 3/ highlight_trail Ex1: draw_graph(highlight_subgraph(cycle_graph(5),path_graph(3))) - ''' return GiacMethods['highlight_subgraph'](self,*args) @@ -7222,9 +6652,8 @@ cdef class GiacMethods_base: Help for highlight_trail: highlight_trail(Graph(G),Trail(t)||Lst(T),[Color(c)||Lst(C)]) Changes colors of edges in G which lie along the trail t resp. trails in T to c resp. C (by default red) and returns the modified copy of G. - See also: 1/ highlight_edges 2/ highlight_subgraph 3/ highlight_vertex + See also: 1/ highlight_edges 2/ highlight_subgraph 3/ highlight_vertex Ex1: draw_graph(highlight_trail(cycle_graph(5),trail(1,2,3),green) - ''' return GiacMethods['highlight_trail'](self,*args) @@ -7233,9 +6662,8 @@ cdef class GiacMethods_base: Help for highlight_vertex: highlight_vertex(Graph(G),Vrtx(v)||Lst(V),[Color(c)||Lst(C)]) Changes the color of vertex v resp. colors of vertices from V in G to c resp. C (green by default) and returns the modified copy of G. - See also: 1/ highlight_edges 2/ highlight_subgraph 3/ highlight_trail + See also: 1/ highlight_edges 2/ highlight_subgraph 3/ highlight_trail Ex1: draw_graph(highlight_vertex(cycle_graph(3),1)) - ''' return GiacMethods['highlight_vertex'](self,*args) @@ -7244,9 +6672,8 @@ cdef class GiacMethods_base: Help for highpass: highpass(Lst(s),Real(c),[Intg(samplerate)]) Returns the result of applying a simple first-order highpass RC filter with cutoff frequency c (the default samplerate is 44100) to the given signal s. - See also: 1/ lowpass 2/ moving_average + See also: 1/ lowpass 2/ moving_average Ex1: f:=unapply(periodic(sign(x),x,-1/880,1/880),x):;s:=createwav(apply(f,soundsec(1))):;playsnd(highpass(s,5000)) - ''' return GiacMethods['highpass'](self,*args) @@ -7255,9 +6682,8 @@ cdef class GiacMethods_base: Help for hilbert: hilbert(Intg(n)) Returns the order n Hilbert matrix : Hjk=1/(j+k+1) j,k=1..n. - See also: 1/ + See also: 1/ Ex1:hilbert(4) - ''' return GiacMethods['hilbert'](self,*args) @@ -7266,7 +6692,7 @@ cdef class GiacMethods_base: Help for histogram: histogram(Lst(data),[Lst(eff) || Intg(nc) || Real(classmin)],[Real(classsize)]) Draws the histogram of data, optional arguments are eff (number of data for each data element) or nc the number of classes or the classes minimum and size. - See also: 1/ cumulated_frequencies 2/ classes 3/ bar_plot 4/ frequencies + See also: 1/ cumulated_frequencies 2/ classes 3/ bar_plot 4/ frequencies Ex1:histogram([1,2,1,1,2,1,2,4,3,3]) Ex2:histogram([1,2,1,1,2,1,2,4,3,3],0.5,1) Ex3:histogram(seq(rand(1000),k,0,100),0,100) @@ -7275,7 +6701,6 @@ cdef class GiacMethods_base: Ex6:histogram([[1.5..1.65,50],[1.65..1.7,20],[1.7..1.8,30]]) Ex7:histogram(seq(rand(1000),k,0,100),0,100) Ex8:histogram(seq(rand(1000),k,0,100),10) - ''' return GiacMethods['histogram'](self,*args) @@ -7284,11 +6709,10 @@ cdef class GiacMethods_base: Help for hold: hold(Expr) Returns its argument unevaluated (and also a:=quote(a) purges a). - See also: 1/ + See also: 1/ Ex1:hold(1+2) Ex2:hold(1/x+1/(x-1)) Ex3:hold((x+1)*(x-1)) - ''' return GiacMethods['hold'](self,*args) @@ -7299,7 +6723,6 @@ cdef class GiacMethods_base: Make P homogeneous by adding a variable (by default t) Ex1:homogeneize(x^2-1) Ex2:homogeneize(x^2-y,z) - ''' return GiacMethods['homogeneize'](self,*args) @@ -7308,12 +6731,11 @@ cdef class GiacMethods_base: Help for homothety: homothety(Pnt(C),Real(k),Pnt(A)) homothety(C,k,A)=point A1 such as vect(C,A1)=k*vect(C,A) i.e in 2d it is the similarity with center C, coeff abs(k) and angle arg(k). - See also: 1/ similarity 2/ inversion + See also: 1/ similarity 2/ inversion Ex1:homothety(1+i,1/3,i) Ex2:homothety(point(1,1,1),1/3,point(0,1,0)) Ex3: h:=homothety(1+i,1/3);h(i) Ex4: h:=homothety(point(1,1,1),1/3);h(point(0,1,0)) - ''' return GiacMethods['homothety'](self,*args) @@ -7322,12 +6744,11 @@ cdef class GiacMethods_base: Help for horner: horner(Poly(P),Real(a)) Returns the value of P(a) calculated with Horner's method. With horner(list_alpha_i,list_x_i,x), evals an interpolation polynomial from the divided differences of x. - See also: 1/ convert 2/ base 3/ revlist + See also: 1/ convert 2/ base 3/ revlist Ex1:horner(x^2+1,2) Ex2:horner([1,0,1],2) Ex3:horner(x^2+y*x+y^3-1,2,y) Ex4: X:=[0.0,1.0,2.0]; A:=lagrange(X,exp,lagrange); horner(A,X,1.5); - ''' return GiacMethods['horner'](self,*args) @@ -7336,14 +6757,13 @@ cdef class GiacMethods_base: Help for hybrid_solver: hybrid_solver(Opt) Argument for fsolve giving the method for solving a system of numerical equations. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],dnewton_solver) Ex2: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrid_solver) Ex3: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrids_solver) Ex4: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridj_solver) Ex5: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridsj_solver) Ex6: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],newtonj_solver) - ''' return GiacMethods['hybrid_solver'](self,*args) @@ -7352,14 +6772,13 @@ cdef class GiacMethods_base: Help for hybridj_solver: hybridj_solver(Opt) Argument for fsolve giving the method for solving a system of numerical equations. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],dnewton_solver) Ex2: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrid_solver) Ex3: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrids_solver) Ex4: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridj_solver) Ex5: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridsj_solver) Ex6: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],newtonj_solver) - ''' return GiacMethods['hybridj_solver'](self,*args) @@ -7368,14 +6787,13 @@ cdef class GiacMethods_base: Help for hybrids_solver: hybrids_solver(Opt) Argument for fsolve giving the method for solving a system of numerical equations. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],dnewton_solver) Ex2: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrid_solver) Ex3: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrids_solver) Ex4: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridj_solver) Ex5: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridsj_solver) Ex6: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],newtonj_solver) - ''' return GiacMethods['hybrids_solver'](self,*args) @@ -7384,14 +6802,13 @@ cdef class GiacMethods_base: Help for hybridsj_solver: hybridsj_solver(Opt) Argument for fsolve giving the method for solving a system of numerical equations. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],dnewton_solver) Ex2: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrid_solver) Ex3: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrids_solver) Ex4: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridj_solver) Ex5: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridsj_solver) Ex6: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],newtonj_solver) - ''' return GiacMethods['hybridsj_solver'](self,*args) @@ -7400,9 +6817,8 @@ cdef class GiacMethods_base: Help for hyp2exp: hyp2exp(ExprHyperb) Transforms the hyperbolic functions to the exponential function. - See also: 1/ halftan_hyp2exp + See also: 1/ halftan_hyp2exp Ex1:hyp2exp(cosh(x)) - ''' return GiacMethods['hyp2exp'](self,*args) @@ -7411,12 +6827,11 @@ cdef class GiacMethods_base: Help for hyperbola: hyperbola(Focus(F1),Focus(F2),(Pnt(M) or Real(a))) hyperbola(F1,F2,M)=hyperbola with foci F1,F2 through M or (|MF1-MF2|=2*a geo2d) and hyperbola(p(x,y)) draws the conic if deg(p)=2. - See also: 1/ ellipse 2/ parabola + See also: 1/ ellipse 2/ parabola Ex1:hyperbola(-1,1,point(1+i)) Ex2:hyperbola(-1,1,sqrt(5)-1) Ex3:hyperbola(point(-1,0,0),point(1,0,0),point(1,1,1)) Ex4:hyperbola(x^2-y^2+y+2) - ''' return GiacMethods['hyperbola'](self,*args) @@ -7425,9 +6840,8 @@ cdef class GiacMethods_base: Help for hypercube_graph: hypercube_graph(Intg(n)) Constructs and returns the hypercube graph in dimension n (with 2^n vertices). - See also: 1/ graph + See also: 1/ graph Ex1:hypercube_graph(3) - ''' return GiacMethods['hypercube_graph'](self,*args) @@ -7436,11 +6850,10 @@ cdef class GiacMethods_base: Help for iPart: iPart(Real||LstReal) Returns the argument without its fractional part (type=DOM_FLOAT). - See also: 1/ fPart 2/ floor 3/ trunc + See also: 1/ fPart 2/ floor 3/ trunc Ex1:iPart(4.3) Ex2:iPart(sqrt(2)) Ex3:iPart(4.3,sqrt(2)) - ''' return GiacMethods['iPart'](self,*args) @@ -7449,11 +6862,10 @@ cdef class GiacMethods_base: Help for iabcuv: iabcuv(Intg(a),Intg(b),Intg(c)) Returns [u,v] such that au+bv=c for 3 integers a,b,c. - See also: 1/ iegcd 2/ abcuv + See also: 1/ iegcd 2/ abcuv Ex1:iabcuv(21,28,7) Ex2:iabcuv(21,28,14) Ex3:iabcuv(21,28,1) - ''' return GiacMethods['iabcuv'](self,*args) @@ -7462,9 +6874,8 @@ cdef class GiacMethods_base: Help for ibasis: ibasis(Lst(Vect,..,Vect),Lst(Vect,..,Vect)) Basis of the intersection of two vector spaces. - See also: 1/ basis + See also: 1/ basis Ex1:ibasis([[1,0,0],[0,1,0]],[[1,1,1],[0,0,1]]) - ''' return GiacMethods['ibasis'](self,*args) @@ -7473,13 +6884,12 @@ cdef class GiacMethods_base: Help for ibpdv: ibpdv(Expr(f(x)),Expr(v(x)),[Var(x)],[Real(a)],[Real(b)]) Integration by parts of f(x)=u(x)*v'(x) with f(x) as 1st argument and v(x) (or 0) as 2nd argument. You can specify a variable of integration and also calculate the integral (bounds a and b). - See also: 1/ ibpu 2/ int + See also: 1/ ibpu 2/ int Ex1:ibpdv(ln(x),x) Ex2:ibpdv(ln(x),x,x,1,3) Ex3:ibpdv(x*ln(x),x^2/2) Ex4:ibpdv([x*ln(x),-1],0) Ex5:ibpdv(ibpdv(ln(x),x,x,2,3),0,x,2,3) - ''' return GiacMethods['ibpdv'](self,*args) @@ -7488,13 +6898,12 @@ cdef class GiacMethods_base: Help for ibpu: ibpu(Expr(f(x)),Expr(u(x)),[Var(x)],[Real(a)],[Real(b)]) Integration by parts of f(x)=u(x)*v'(x) with f(x) as 1st argument and u(x) (or 0) as 2nd argument. You can specify a variable of integration and also calculate the integral (bounds a and b). - See also: 1/ ibpdv 2/ int + See also: 1/ ibpdv 2/ int Ex1:ibpu(ln(x),ln(x)) Ex2:ibpu(ln(x),ln(x),x,1,3) Ex3:ibpu(x*ln(x),ln(x)) Ex4:ibpu([x*ln(x),-1],0) Ex5:ibpu(ibpu(ln(x),ln(x),x,2,3),0,x,2,3) - ''' return GiacMethods['ibpu'](self,*args) @@ -7503,10 +6912,9 @@ cdef class GiacMethods_base: Help for icdf: icdf(Func,FuncParams) Inverse cumulative distribution function. - See also: 1/ cdf 2/ binomial_icdf 3/ normald_icdf + See also: 1/ cdf 2/ binomial_icdf 3/ normald_icdf Ex1:icdf(binomial,10,0.5,0.6) Ex2:icdf(normald,0.0,1.0,0.975) - ''' return GiacMethods['icdf'](self,*args) @@ -7515,12 +6923,11 @@ cdef class GiacMethods_base: Help for ichinrem: ichinrem(LstIntg(a,p),LstIntg(b,q)) Chinese remainders for integers. - See also: 1/ gcd 2/ fracmod 3/ chinrem 4/ chrem + See also: 1/ gcd 2/ fracmod 3/ chinrem 4/ chrem Ex1:ichinrem([2,7],[3,5]) Ex2:ichinrem([2%7,3%5]) Ex3:ichinrem([2%7,3%5,1%9]) Ex4:ichinrem([(x+1)%2,(x+2)%3,(3*x-1)%5]) - ''' return GiacMethods['ichinrem'](self,*args) @@ -7529,12 +6936,11 @@ cdef class GiacMethods_base: Help for ichrem: ichrem(LstIntg(a,p),LstIntg(b,q)) Chinese remainders for integers. - See also: 1/ gcd 2/ fracmod 3/ chinrem 4/ chrem + See also: 1/ gcd 2/ fracmod 3/ chinrem 4/ chrem Ex1:ichrem([2,7],[3,5]) Ex2:ichrem([2%7,3%5]) Ex3:ichrem([2%7,3%5,1%9]) Ex4:ichrem([(x+1)%2,(x+2)%3,(3*x-1)%5]) - ''' return GiacMethods['ichrem'](self,*args) @@ -7543,10 +6949,9 @@ cdef class GiacMethods_base: Help for icomp: icomp(Intg(n),Intg(k),[zeros=true||false]) Returns the list of compositions of n into k parts. - See also: 1/ sum + See also: 1/ sum Ex1:icomp(4,2) Ex2:icomp(6,3,zeros=false) - ''' return GiacMethods['icomp'](self,*args) @@ -7555,10 +6960,9 @@ cdef class GiacMethods_base: Help for icontent: icontent(Poly,[Var]) GCD of the integer coefficients of a polynomial. - See also: 1/ + See also: 1/ Ex1:icontent(24x^3+6x^2-12x+18) Ex2:icontent(24t^3+6t^2-12t+18,t) - ''' return GiacMethods['icontent'](self,*args) @@ -7567,10 +6971,9 @@ cdef class GiacMethods_base: Help for icosahedron: icosahedron(Pnt(A),Pnt(B),Pnt(C)) Draws an icosahedron with center A, vertex B and such that the plane ABC contains one vertex among the 5 nearest vertices from B. - See also: 1/ octahedron 2/ dodecahedron 3/ cube 4/ tetrahedron + See also: 1/ octahedron 2/ dodecahedron 3/ cube 4/ tetrahedron Ex1:icosahedron([0,0,0],[sqrt(5),0,0],[1,2,0]) Ex2:icosahedron(evalf([0,0,0],[3,2,4],[1,1,0])) - ''' return GiacMethods['icosahedron'](self,*args) @@ -7579,9 +6982,8 @@ cdef class GiacMethods_base: Help for id: id(Seq) The name of the identity function (ℝ^n -> ℝ^n). - See also: 1/ sq 2/ sqrt + See also: 1/ sq 2/ sqrt Ex1:id(1,2,3) - ''' return GiacMethods['id'](self,*args) @@ -7590,10 +6992,9 @@ cdef class GiacMethods_base: Help for identity: identity(Intg(n)) Returns the identity matrix of specified dimension n. - See also: 1/ ranm + See also: 1/ ranm Ex1:identity(3) Ex2:identity(5) - ''' return GiacMethods['identity'](self,*args) @@ -7602,10 +7003,9 @@ cdef class GiacMethods_base: Help for idivis: idivis(Intg(a) or LstIntg) Returns the list of divisors of an integer. - See also: 1/ divis 2/ ifactors + See also: 1/ divis 2/ ifactors Ex1:idivis(36) Ex2:idivis([36,49]) - ''' return GiacMethods['idivis'](self,*args) @@ -7614,10 +7014,9 @@ cdef class GiacMethods_base: Help for idn: idn(Intg(n)) Returns the identity matrix of specified dimension n. - See also: 1/ ranm + See also: 1/ ranm Ex1:idn(3) Ex2:idn(5) - ''' return GiacMethods['idn'](self,*args) @@ -7626,11 +7025,10 @@ cdef class GiacMethods_base: Help for iegcd: iegcd(Intg,Intg) Extended greatest common divisor of 2 integers. - See also: 1/ gcd 2/ iabcuv 3/ egcd + See also: 1/ gcd 2/ iabcuv 3/ egcd Ex1:iegcd(45,75) Ex2:iegcd(21,28) Ex3:iegcd(30,49) - ''' return GiacMethods['iegcd'](self,*args) @@ -7639,10 +7037,9 @@ cdef class GiacMethods_base: Help for ifactor: ifactor(Intg(a)) Factorization of an integer into prime factors. - See also: 1/ factor 2/ ecm_factor + See also: 1/ factor 2/ ecm_factor Ex1:ifactor(50) Ex2:ifactor(123456789) - ''' return GiacMethods['ifactor'](self,*args) @@ -7651,10 +7048,9 @@ cdef class GiacMethods_base: Help for ifactors: ifactors(Intg(a) or LstIntg) Returns the list of prime factors of an integer (each factor is followed by its multiplicity). - See also: 1/ ifactor 2/ factors + See also: 1/ ifactor 2/ factors Ex1:ifactors(36) Ex2:ifactors([36,52]) - ''' return GiacMethods['ifactors'](self,*args) @@ -7663,7 +7059,7 @@ cdef class GiacMethods_base: Help for ifourier: ifourier(Expr(F(s)),[Var(s),[Var(x)]]) Returns the inverse Fourier transform f(x) of F(s). - See also: 1/ fourier 2/ fourier_cn 3/ ifft + See also: 1/ fourier 2/ fourier_cn 3/ ifft Ex1:ifourier(2*pi*(Dirac(s)-sign(s)*sin(s)),s,x) Ex2:ifourier(-2/(s^2-1),s,x) Ex3:ifourier(pi/(exp(pi*s/4)+exp(-pi*s/4)),s,x) @@ -7671,7 +7067,6 @@ cdef class GiacMethods_base: Ex5:ifourier(pi*ugamma(0,4*abs(s)),s,x) Ex6:ifourier(fourier(exp(-abs(x)),x,s)^2,s,x) Ex7:ifourier(sinc(s),s,x) - ''' return GiacMethods['ifourier'](self,*args) @@ -7680,11 +7075,10 @@ cdef class GiacMethods_base: Help for igamma: igamma(Real(a),Real(x),[1]) Calculates of gamma at a point (a,x). If a and x>0, igamma(a,x)=int(e^{-t}*t^{a-1},t=0..x), (igamma(a,x,1)=igamma(a,x)/Gamma(a)). - See also: 1/ Psi 2/ Beta 3/ Gamma 3/ ugamma + See also: 1/ Psi 2/ Beta 3/ Gamma 3/ ugamma Ex1:igamma(5.0,2.0) Ex2:igamma(-5.1,2.1) Ex3:igamma(5.0,2.0,1) - ''' return GiacMethods['igamma'](self,*args) @@ -7693,13 +7087,12 @@ cdef class GiacMethods_base: Help for igcd: igcd((Intg(a) or Poly),(Intg(b) or Poly)) Returns the greatest common divisor of 2 polynomials of several variables or of 2 integers or of 2 rationals. - See also: 1/ lcm 2/ euler 2/ modgcd 3/ ezgcd 4/ psrgcd 5/ heugcd 6/ Gcd + See also: 1/ lcm 2/ euler 2/ modgcd 3/ ezgcd 4/ psrgcd 5/ heugcd 6/ Gcd Ex1:igcd(45,75) Ex2:igcd(15/7,50/9) Ex3:igcd(x^2-2*x+1,x^3-1) Ex4:igcd(t^2-2*t+1,t^2+t-2) Ex5:igcd((x^2-1)*(y^2-1)*z^2,x^3*y^3*z+(-(y^3))*z+x^3*z-z) - ''' return GiacMethods['igcd'](self,*args) @@ -7708,11 +7101,10 @@ cdef class GiacMethods_base: Help for igcdex: igcdex(Intg,Intg) Extended greatest common divisor of 2 integers. - See also: 1/ gcd 2/ iabcuv 3/ egcd + See also: 1/ gcd 2/ iabcuv 3/ egcd Ex1:igcdex(45,75) Ex2:igcdex(21,28) Ex3:igcdex(30,49) - ''' return GiacMethods['igcdex'](self,*args) @@ -7721,10 +7113,9 @@ cdef class GiacMethods_base: Help for ihermite: ihermite(Mtrx(A)) Hermite normal form of a matrix with coefficients in ℤ : returns L,U such that L is invertible in ℤ, U is upper triangular and U=L*A. - See also: 1/ ismith + See also: 1/ ismith Ex1:ihermite([[9,-36,30], [-36,192,-180], [30,-180,180]]) Ex2:ihermite([[1,2,3],[4,5,6],[7,8,9]]) - ''' return GiacMethods['ihermite'](self,*args) @@ -7733,11 +7124,10 @@ cdef class GiacMethods_base: Help for ilaplace: ilaplace(Expr,[Var],[IlapVar]) Inverse Laplace transform of a rational fraction. - See also: 1/ laplace 2/ ztrans 3/ invztrans 4/ Heaviside + See also: 1/ laplace 2/ ztrans 3/ invztrans 4/ Heaviside Ex1:ilaplace(1/(x^2+1)^2) Ex2:ilaplace(s/(s^4-1),s,x) Ex3:ilaplace(exp(-s)/s,s,x) - ''' return GiacMethods['ilaplace'](self,*args) @@ -7746,11 +7136,10 @@ cdef class GiacMethods_base: Help for im: im(Cplx) Returns the imaginary part of a complex number. - See also: 1/ re 2/ conj + See also: 1/ re 2/ conj Ex1:im(1+2*i) Ex2:im((1+2*i)^2) Ex3:im([1+2*i,(1+2*i)^2]) - ''' return GiacMethods['im'](self,*args) @@ -7759,11 +7148,10 @@ cdef class GiacMethods_base: Help for imag: imag(Cplx) Returns the imaginary part of a complex number. - See also: 1/ re 2/ conj + See also: 1/ re 2/ conj Ex1:imag(1+2*i) Ex2:imag((1+2*i)^2) Ex3:imag([1+2*i,(1+2*i)^2]) - ''' return GiacMethods['imag'](self,*args) @@ -7772,10 +7160,9 @@ cdef class GiacMethods_base: Help for image: image(Mtrx(M)) Image of a linear map with matrix M. - See also: 1/ ker 2/ rref + See also: 1/ ker 2/ rref Ex1:image([[1,2],[3,6]]) Ex2:image([[1,2,3],[1,3,6],[2,5,9]]) - ''' return GiacMethods['image'](self,*args) @@ -7784,7 +7171,7 @@ cdef class GiacMethods_base: Help for implicitdiff: implicitdiff(constr,[depvars],y,diffvars) Implicit differentiation. - See also: 1/ diff + See also: 1/ diff Ex1:implicitdiff(x^2*y+y^2=1,y,x) Ex2:implicitdiff(R=P*V/T,P,T) Ex3:implicitdiff([x^2+y=z,x+y*z=1],[y(x),z(x)],y,x) @@ -7803,7 +7190,6 @@ cdef class GiacMethods_base: Ex16:implicitdiff(x*y*z,-2x^3+15x^2*y+11y^3-24y=0,[x,z,y],order=1) Ex17:implicitdiff(x*y*z,-2x^3+15x^2*y+11y^3-24y=0,[x,z,y],order=2,[1,-1,0]) Ex18: pd:=implicitdiff(x*y*z,-2x^3+15x^2*y+11y^3-24y=0,[x,z,y],order=4,[0,z,0]);pd[4,0,0] - ''' return GiacMethods['implicitdiff'](self,*args) @@ -7812,7 +7198,7 @@ cdef class GiacMethods_base: Help for implicitplot: implicitplot(Expr,Var1,Var2) plotimplicit(f(x,y),x,y) or plotimplicit(f(x,y),[x,y]) draws graph of f(x,y)=0. - See also: 1/ plotcontour 2/ unfactored 3/ plotinequation + See also: 1/ plotcontour 2/ unfactored 3/ plotinequation Ex1:implicitplot(x^2+y^2-1,x,y) Ex2:implicitplot(x^4+y^4=x^2-y^2) Ex3:implicitplot(x^2+y^2-1,x,y,unfactored) @@ -7822,7 +7208,6 @@ cdef class GiacMethods_base: Ex7:implicitplot(y^3=x^3-x^2,[x,y],xstep=0.1,ystep=0.1) Ex8:implicitplot((x+5)^2+(y+4)^2-1,x=-6..-4,y=-5..-3) Ex9:implicitplot((x+5)^2+(y+4)^2-1,[x=-6..-4,y=-5..-3]) - ''' return GiacMethods['implicitplot'](self,*args) @@ -7832,7 +7217,6 @@ cdef class GiacMethods_base: import_graph(Str("path/to/graphname[.dot]")) Returns the graph constructed from instructions in the file 'path/to/graphname.dot' (in dot format), or "undef" on failure. Ex1:import_graph("K5.dot") - ''' return GiacMethods['import_graph'](self,*args) @@ -7841,10 +7225,9 @@ cdef class GiacMethods_base: Help for inString: inString(Str(l),Elem(e)) Tests if e is in the string l (returns -1 or k if l[k]=e). - See also: 1/ contains + See also: 1/ contains Ex1:inString("abcd","b") Ex2:inString("abcd","e") - ''' return GiacMethods['inString'](self,*args) @@ -7853,10 +7236,9 @@ cdef class GiacMethods_base: Help for in_ideal: in_ideal(Poly,Lst,LstVar,[order]) Checks whether a polynomial or list of polynomials belongs to an ideal given by a Grobner basis (2nd argument) with respect to a variable list. - See also: 1/ gbasis 2/ greduce + See also: 1/ gbasis 2/ greduce Ex1:in_ideal((x+y)^2,[y^2,x^2+2*x*y],[x,y]) Ex2:in_ideal(x+y,[y^2,x^2+2*x*y],[x,y]) - ''' return GiacMethods['in_ideal'](self,*args) @@ -7865,9 +7247,8 @@ cdef class GiacMethods_base: Help for incidence_matrix: incidence_matrix(Graph(G)) Returns the incidence matrix of G whose rows are indexed by the vertices and columns by the edges (in order defined by the command 'edges'). - See also: 1/ incident_edges + See also: 1/ incident_edges Ex1:incidence_matrix(graph("tetrahedron")) - ''' return GiacMethods['incidence_matrix'](self,*args) @@ -7876,9 +7257,8 @@ cdef class GiacMethods_base: Help for incident_edges: incident_edges(Graph(G),Vrtx(v)) Returns the list of all edges incident to the vertex v of G (or to the vertices in the list v). - See also: 1/ adjacency_matrix 2/ vertex_degree 3/ incidence_matrix 4/ neighbors + See also: 1/ adjacency_matrix 2/ vertex_degree 3/ incidence_matrix 4/ neighbors Ex1:incident_edges(cycle_graph(8),[1,5,7]) - ''' return GiacMethods['incident_edges'](self,*args) @@ -7887,9 +7267,8 @@ cdef class GiacMethods_base: Help for incircle: incircle((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) incircle(A,B,C) draws the incircle of the triangle ABC. - See also: 1/ excircle 2/ circumcircle + See also: 1/ excircle 2/ circumcircle Ex1:incircle(0,1,1+i) - ''' return GiacMethods['incircle'](self,*args) @@ -7898,10 +7277,9 @@ cdef class GiacMethods_base: Help for increasing_power: increasing_power(:=Intg(0 or 1)) Pseudo-variable to control the display of polynomials. - See also: 1/ cas_setup + See also: 1/ cas_setup Ex1: increasing_power:=1 Ex2: increasing_power:=0 - ''' return GiacMethods['increasing_power'](self,*args) @@ -7910,9 +7288,8 @@ cdef class GiacMethods_base: Help for independence_number: independence_number(Graph(G)) Returns the independence number of G. - See also: 1/ clique_number 2/ graph_complement 3/ maximum_clique 4/ maximum_independent_set + See also: 1/ clique_number 2/ graph_complement 3/ maximum_clique 4/ maximum_independent_set Ex1:independence_number(complete_graph(3,4)) - ''' return GiacMethods['independence_number'](self,*args) @@ -7921,9 +7298,8 @@ cdef class GiacMethods_base: Help for indets: indets(Expr) List of variables in the expression. - See also: 1/ has 2/ lvar + See also: 1/ has 2/ lvar Ex1:indets(exp(x)*2*sin(y)) - ''' return GiacMethods['indets'](self,*args) @@ -7932,12 +7308,11 @@ cdef class GiacMethods_base: Help for index: index(Vect,Expr) Index of the first position of an object in a list, a string or a set or returns an error message. - See also: 1/ find 2/ member + See also: 1/ find 2/ member Ex1:index([3,x,1,2,1,3],1) Ex2:index([0,1,3,2,4,2,5],2) Ex3:index(%{4,3,1,2%},1) Ex4:index("abracadabrant","c") - ''' return GiacMethods['index'](self,*args) @@ -7946,9 +7321,8 @@ cdef class GiacMethods_base: Help for induced_subgraph: induced_subgraph(Graph(G),Lst(V)) Returns the subgraph of G induced by the vertices in list V. - See also: 1/ subgraph + See also: 1/ subgraph Ex1:induced_subgraph(cycle_graph(6),[1,2,6]) - ''' return GiacMethods['induced_subgraph'](self,*args) @@ -7957,12 +7331,11 @@ cdef class GiacMethods_base: Help for inequationplot: inequationplot(Expr,[x=xrange,y=yrange],[xstep],[ystep]) Shows the graph of the solutions of inequalities with 2 variables. - See also: 1/ plotfunc 2/ plotcontour 3/ plotdensity 4/ plotimplicit + See also: 1/ plotfunc 2/ plotcontour 3/ plotdensity 4/ plotimplicit Ex1:inequationplot(x^2-y^2<3) Ex2:inequationplot(x^2-y^2<3,[x=-2..2,y=-2..2],xstep=0.1,ystep=0.1) Ex3:inequationplot(3-(x^2-y^2),[x=-2..2,y=-2..2],xstep=0.1,ystep=0.1) Ex4:inequationplot([x+y>3,x^2ln(a*b^n) for integers n. - See also: 1/ texpand + See also: 1/ texpand Ex1:lncollect(ln(x)+2*ln(y)) - ''' return GiacMethods['lncollect'](self,*args) @@ -9904,9 +9124,8 @@ cdef class GiacMethods_base: Help for lnexpand: lnexpand(Expr) Expands logarithms. - See also: 1/ texpand 2/ expexpand 3/ trigexpand + See also: 1/ texpand 2/ expexpand 3/ trigexpand Ex1:lnexpand(ln(3*x)) - ''' return GiacMethods['lnexpand'](self,*args) @@ -9915,10 +9134,9 @@ cdef class GiacMethods_base: Help for locus: locus(Pnt,Elem) locus(M,A) draws the locus of M (or locus(d,A) draws the envelope of d) when A:=element(C) (C is a curve). The example instructions below must be written in a geometric level on different lines. - See also: 1/ envelope 2/ trace + See also: 1/ envelope 2/ trace Ex1: A:=element(circle(i,1+i));M:=homothety(0,2,A);locus(M,A) Ex2: A:=element(line(x=0));d:=perpen_bisector(1,A);locus(d,A) - ''' return GiacMethods['locus'](self,*args) @@ -9927,11 +9145,10 @@ cdef class GiacMethods_base: Help for log: log(Expr or Opt) Natural logarithm or option of the convert or convertir command (id trig2exp). - See also: 1/ exp 2/ convert 3/ trig2exp 4/ log10 + See also: 1/ exp 2/ convert 3/ trig2exp 4/ log10 Ex1:log(1) Ex2:log(e) Ex3: convert(cos(x),ln) - ''' return GiacMethods['log'](self,*args) @@ -9940,9 +9157,8 @@ cdef class GiacMethods_base: Help for log10: log10(Expr) Common logarithm (base 10). - See also: 1/ alog10 2/ ln + See also: 1/ alog10 2/ ln Ex1:log10(10) - ''' return GiacMethods['log10'](self,*args) @@ -9951,10 +9167,9 @@ cdef class GiacMethods_base: Help for logarithmic_regression: logarithmic_regression(Lst||Mtrx(A),[Lst]) Returns the coefficients a and b of y=a*ln(x)+b : it is the best logarithm which approx the points where the coordinates are the rows of A (or the 2 lists). - See also: 1/ exponential_regression + See also: 1/ exponential_regression Ex1:logarithmic_regression([[1.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]]) Ex2:logarithmic_regression([1.0,2.0,3.0,4.0],[1.0,4.0,9.0,16.0]) - ''' return GiacMethods['logarithmic_regression'](self,*args) @@ -9963,10 +9178,9 @@ cdef class GiacMethods_base: Help for logarithmic_regression_plot: logarithmic_regression_plot(Lst||Mtrx(A),[Lst]) Returns the plot of y=a*ln(x)+b : it is the best logarithm which approx the points where the coordinates are the rows of A (or the 2 lists). - See also: 1/ exponential_regression_plot + See also: 1/ exponential_regression_plot Ex1:logarithmic_regression_plot([[1.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]]) Ex2:logarithmic_regression_plot([1.0,2.0,3.0,4.0],[1.0,4.0,9.0,16.0]) - ''' return GiacMethods['logarithmic_regression_plot'](self,*args) @@ -9975,10 +9189,9 @@ cdef class GiacMethods_base: Help for logb: logb(Real) Logarithm with base b. - See also: 1/ log 2/ log10 + See also: 1/ log 2/ log10 Ex1:logb(5,2) Ex2:logb(7,10) - ''' return GiacMethods['logb'](self,*args) @@ -9987,10 +9200,9 @@ cdef class GiacMethods_base: Help for logistic_regression: logistic_regression(Lst(L),Real(x0),Real(y0)) Returns y,y',C,y'max,xmax,R : y is a logistic function (sol of y'/y=a*y+b), such that y(x0)=y0 and where [y'(x0),y'(x0+1)...] is the best approximation of L. - See also: 1/ polynomial_regression 2/ power_regression 3/ linear_regression + See also: 1/ polynomial_regression 2/ power_regression 3/ linear_regression Ex1:logistic_regression(evalf([1,2,4,6,8,7,5]),1,2) Ex2:logistic_regression([0.0,1.0,2.0,3.0,4.0],0.0,1.0) - ''' return GiacMethods['logistic_regression'](self,*args) @@ -9999,10 +9211,9 @@ cdef class GiacMethods_base: Help for logistic_regression_plot: logistic_regression_plot(Lst(L),Real(x0),Real(y0)) Returns the plot of a logistic function y such that y(x0)=y0 and where [y'(x0),y'(x0+1)...] is the best approximation of L. - See also: 1/ polynomial_regression_plot 2/ power_regression_plot 3/ linear_regression_plot + See also: 1/ polynomial_regression_plot 2/ power_regression_plot 3/ linear_regression_plot Ex1:logistic_regression_plot(evalf([1,2,4,6,8,7,5]),1,2) Ex2:logistic_regression_plot([0.0,1.0,2.0,3.0,4.0],0.0,1.0) - ''' return GiacMethods['logistic_regression_plot'](self,*args) @@ -10011,10 +9222,9 @@ cdef class GiacMethods_base: Help for lower: lower(Mtrx||Strng) Returns the lower triangular matrix (under the diagonal, included) or writes a string in lowercase. - See also: 1/ diag 2/ upper + See also: 1/ diag 2/ upper Ex1:lower([[1,2,3],[4,5,6],[7,8,9]]) Ex2:lower("HELLO") - ''' return GiacMethods['lower'](self,*args) @@ -10023,10 +9233,9 @@ cdef class GiacMethods_base: Help for lowest_common_ancestor: lowest_common_ancestor(Graph(T),Vrtx(r),Seq(u,v)||Lst([u1,v1],[u2,v2],...)) Returns the lowest common ancestor of nodes u and v in the tree graph T with root r, or the list of lowest common ancestors of all pairs [uk,vk]. - See also: 1/ is_tree 2/ tree_height + See also: 1/ is_tree 2/ tree_height Ex1: T:=random_tree(30); lowest_common_ancestor(T,15,10,20) Ex2: T:=random_tree(30); lowest_common_ancestor(T,15,[[10,20],[11,19]]) - ''' return GiacMethods['lowest_common_ancestor'](self,*args) @@ -10035,9 +9244,8 @@ cdef class GiacMethods_base: Help for lowpass: lowpass(Lst(s),Real(c),[Intg(samplerate)]) Returns the result of applying a simple first-order lowpass RC filter with cutoff frequency c (the default samplerate is 44100) to the given signal s. - See also: 1/ highpass 2/ moving_average + See also: 1/ highpass 2/ moving_average Ex1: f:=unapply(periodic(sign(x),x,-1/880,1/880),x):;s:=createwav(apply(f,soundsec(1))):;playsnd(lowpass(s,1000)) - ''' return GiacMethods['lowpass'](self,*args) @@ -10046,8 +9254,7 @@ cdef class GiacMethods_base: Help for lp_assume: lp_assume(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_assume'](self,*args) @@ -10056,8 +9263,7 @@ cdef class GiacMethods_base: Help for lp_bestprojection: lp_bestprojection(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_bestprojection'](self,*args) @@ -10066,8 +9272,7 @@ cdef class GiacMethods_base: Help for lp_binary: lp_binary(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_binary'](self,*args) @@ -10076,8 +9281,7 @@ cdef class GiacMethods_base: Help for lp_binaryvariables: lp_binaryvariables(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_binaryvariables'](self,*args) @@ -10086,8 +9290,7 @@ cdef class GiacMethods_base: Help for lp_breadthfirst: lp_breadthfirst(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_breadthfirst'](self,*args) @@ -10096,8 +9299,7 @@ cdef class GiacMethods_base: Help for lp_depthfirst: lp_depthfirst(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_depthfirst'](self,*args) @@ -10106,8 +9308,7 @@ cdef class GiacMethods_base: Help for lp_depthlimit: lp_depthlimit(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_depthlimit'](self,*args) @@ -10116,8 +9317,7 @@ cdef class GiacMethods_base: Help for lp_firstfractional: lp_firstfractional(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_firstfractional'](self,*args) @@ -10126,8 +9326,7 @@ cdef class GiacMethods_base: Help for lp_gaptolerance: lp_gaptolerance(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_gaptolerance'](self,*args) @@ -10136,8 +9335,7 @@ cdef class GiacMethods_base: Help for lp_hybrid: lp_hybrid(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_hybrid'](self,*args) @@ -10146,8 +9344,7 @@ cdef class GiacMethods_base: Help for lp_initialpoint: lp_initialpoint(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_initialpoint'](self,*args) @@ -10156,8 +9353,7 @@ cdef class GiacMethods_base: Help for lp_integer: lp_integer(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_integer'](self,*args) @@ -10166,8 +9362,7 @@ cdef class GiacMethods_base: Help for lp_integertolerance: lp_integertolerance(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_integertolerance'](self,*args) @@ -10176,8 +9371,7 @@ cdef class GiacMethods_base: Help for lp_integervariables: lp_integervariables(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_integervariables'](self,*args) @@ -10186,8 +9380,7 @@ cdef class GiacMethods_base: Help for lp_interiorpoint: lp_interiorpoint(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_interiorpoint'](self,*args) @@ -10196,8 +9389,7 @@ cdef class GiacMethods_base: Help for lp_iterationlimit: lp_iterationlimit(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_iterationlimit'](self,*args) @@ -10206,8 +9398,7 @@ cdef class GiacMethods_base: Help for lp_lastfractional: lp_lastfractional(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_lastfractional'](self,*args) @@ -10216,8 +9407,7 @@ cdef class GiacMethods_base: Help for lp_maxcuts: lp_maxcuts(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_maxcuts'](self,*args) @@ -10226,8 +9416,7 @@ cdef class GiacMethods_base: Help for lp_maximize: lp_maximize(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_maximize'](self,*args) @@ -10236,8 +9425,7 @@ cdef class GiacMethods_base: Help for lp_method: lp_method(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_method'](self,*args) @@ -10246,8 +9434,7 @@ cdef class GiacMethods_base: Help for lp_mostfractional: lp_mostfractional(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_mostfractional'](self,*args) @@ -10256,8 +9443,7 @@ cdef class GiacMethods_base: Help for lp_nodelimit: lp_nodelimit(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_nodelimit'](self,*args) @@ -10266,8 +9452,7 @@ cdef class GiacMethods_base: Help for lp_nodeselect: lp_nodeselect(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_nodeselect'](self,*args) @@ -10276,8 +9461,7 @@ cdef class GiacMethods_base: Help for lp_nonnegative: lp_nonnegative(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_nonnegative'](self,*args) @@ -10286,8 +9470,7 @@ cdef class GiacMethods_base: Help for lp_nonnegint: lp_nonnegint(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_nonnegint'](self,*args) @@ -10296,8 +9479,7 @@ cdef class GiacMethods_base: Help for lp_pseudocost: lp_pseudocost(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_pseudocost'](self,*args) @@ -10306,8 +9488,7 @@ cdef class GiacMethods_base: Help for lp_simplex: lp_simplex(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_simplex'](self,*args) @@ -10316,8 +9497,7 @@ cdef class GiacMethods_base: Help for lp_timelimit: lp_timelimit(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_timelimit'](self,*args) @@ -10326,8 +9506,7 @@ cdef class GiacMethods_base: Help for lp_variables: lp_variables(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_variables'](self,*args) @@ -10336,8 +9515,7 @@ cdef class GiacMethods_base: Help for lp_varselect: lp_varselect(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_varselect'](self,*args) @@ -10346,8 +9524,7 @@ cdef class GiacMethods_base: Help for lp_verbose: lp_verbose(Opt) Options for lpsolve command. - See also: 1/ lpsolve - + See also: 1/ lpsolve ''' return GiacMethods['lp_verbose'](self,*args) @@ -10356,7 +9533,7 @@ cdef class GiacMethods_base: Help for lpsolve: lpsolve(Expr(o),[List(c)],[bounds],[options]) Solves a (mixed integer/binary) LP problem in general form. - See also: 1/ nlpsolve 2/ fsolve + See also: 1/ nlpsolve 2/ fsolve Ex1:lpsolve(2x+y-z+4,[x<=1,y>=2,x+3y-z=2,2x-y+z<=8,-x+y<=5]) Ex2:lpsolve(-4x-5y,[x+2y<=6,5x+4y<=20,0<=x,0<=y]) Ex3:lpsolve(-7x+2y,[4x-12y<=20,-x+3y<=3],x=-5..5,y=0..inf,lp_maximize=true) @@ -10372,7 +9549,6 @@ cdef class GiacMethods_base: Ex13:lpsolve(x1+x2,[2x1+5x2<=16,6x1+5x2<=30],assume=nonnegint,lp_maximize) Ex14:lpsolve(8x1+11x2+6x3+4x4,[5x1+7x2+4x3+3x4<=14],assume=lp_binary,lp_maximize) Ex15:lpsolve(x1+x2,[1867x1+1913x2=3618894],assume=nonnegint,lp_verbose=true) - ''' return GiacMethods['lpsolve'](self,*args) @@ -10381,9 +9557,8 @@ cdef class GiacMethods_base: Help for lsmod: lsmod(NULL) Displays the installed dynamic libraries. - See also: 1/ insmod 2/ rmmod + See also: 1/ insmod 2/ rmmod Ex1:lsmod() - ''' return GiacMethods['lsmod'](self,*args) @@ -10392,10 +9567,9 @@ cdef class GiacMethods_base: Help for lsq: lsq(Mtrx(A),(Mtrx || Vect)(B)) Returns the vector (resp matrix) X which is the minimum of the euclidean (resp Frobenius) norm of A*X-B corresponding to the linear system A*X=B when B is a vector (resp matrix). - See also: 1/ lu 2/ QR + See also: 1/ lu 2/ QR Ex1:lsq([[1,2],[3,4]],[5,11]) Ex2:lsq([[1,2],[3,4]],[[5,-1],[11,-1]]) - ''' return GiacMethods['lsq'](self,*args) @@ -10404,10 +9578,9 @@ cdef class GiacMethods_base: Help for lu: lu(Mtrx) For a numerical matrix A, returns p permutation, L and U such that PA=LU (P=permu2mat(p)). - See also: 1/ qr 2/ cholesky 3/ LU + See also: 1/ qr 2/ cholesky 3/ LU Ex1:lu([[1,2],[3,4]]) Ex2:lu([[6,12,18],[5,14,31],[3,8,18]]) - ''' return GiacMethods['lu'](self,*args) @@ -10416,10 +9589,9 @@ cdef class GiacMethods_base: Help for lvar: lvar(Expr) List of variables of an object (with rational dependence). - See also: 1/ lname 2/ has + See also: 1/ lname 2/ has Ex1:lvar(exp(x)*2*sin(y)) Ex2:lvar(exp(x)*2*sin(y)+ln(x)) - ''' return GiacMethods['lvar'](self,*args) @@ -10428,9 +9600,8 @@ cdef class GiacMethods_base: Help for mRow: mRow(Expr(Xpr),Mtrx(A),Intg(n1)) Multiplies row n1 of the matrix A by Xpr. - See also: 1/ rowAdd 2/ mRowAdd + See also: 1/ rowAdd 2/ mRowAdd Ex1:mRow(12,[[1,2],[3,4],[5,6]],0) - ''' return GiacMethods['mRow'](self,*args) @@ -10439,9 +9610,8 @@ cdef class GiacMethods_base: Help for mRowAdd: mRowAdd(Expr(Xpr),Mtrx(A),Intg(n1),Intg(n2)) Multiplies row n1 of the matrix A by Xpr, then adds it to the row n2. - See also: 1/ rowAdd 2/ mRow + See also: 1/ rowAdd 2/ mRow Ex1:mRowAdd(12,[[1,2],[3,4],[5,6]],0,2) - ''' return GiacMethods['mRowAdd'](self,*args) @@ -10450,10 +9620,9 @@ cdef class GiacMethods_base: Help for magenta: magenta(Opt) Option of the display command to display with color. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),red) Ex2: F:=display(point(2+1.5*i),point_point+green) - ''' return GiacMethods['magenta'](self,*args) @@ -10462,9 +9631,8 @@ cdef class GiacMethods_base: Help for make_directed: make_directed(Graph(G),[Mrtx(A)]) Returns the copy of undirected graph G in which every edge is converted to a pair of arcs [and with weights specified by matrix A]. - See also: 1/ is_directed 2/ make_weighted 3/ underlying_graph + See also: 1/ is_directed 2/ make_weighted 3/ underlying_graph Ex1:make_directed(cycle_graph(4),[[0,0,0,1],[2,0,1,3],[0,1,0,4],[5,0,4,0]]) - ''' return GiacMethods['make_directed'](self,*args) @@ -10473,9 +9641,8 @@ cdef class GiacMethods_base: Help for make_weighted: make_weighted(Graph(G),[Mrtx(M)]) Returns a copy of G with edge/arc weights set as specified by matrix M. If M is omitted, a square matrix of ones is used. If G is undirected, M is assumed to be symmetric. - See also: 1/ get_edge_weight 2/ is_weighted 3/ make_directed 4/ set_edge_weight 5/ underlying_graph 6/ weight_matrix + See also: 1/ get_edge_weight 2/ is_weighted 3/ make_directed 4/ set_edge_weight 5/ underlying_graph 6/ weight_matrix Ex1:make_weighted(cycle_graph(3),[[0,2,3],[2,0,1],[3,1,0]]) - ''' return GiacMethods['make_weighted'](self,*args) @@ -10484,12 +9651,11 @@ cdef class GiacMethods_base: Help for makelist: makelist(Fnc,InitVal,FinalVal,StepVal) Returns a list made with a function or with a constant. - See also: 1/ seq 2/ range 3/ makemat 4/ $ + See also: 1/ seq 2/ range 3/ makemat 4/ $ Ex1:makelist(x->x^2,1,10,2) Ex2:makelist(4,1,10) Ex3:makelist(4,5,10) Ex4:makelist(x->ifte(x<5,"A","B"),1,10) - ''' return GiacMethods['makelist'](self,*args) @@ -10498,11 +9664,10 @@ cdef class GiacMethods_base: Help for makemat: makemat(Fnct(f),RowsNumb,ColsNumb) Creates a matrix. - See also: 1/ matrix + See also: 1/ matrix Ex1:makemat((j,k)->j+k,3,2) Ex2:makemat((j,k)->1/(j+k+1),2,3) Ex3:makemat(sqrt(2),2,3) - ''' return GiacMethods['makemat'](self,*args) @@ -10511,9 +9676,8 @@ cdef class GiacMethods_base: Help for makesuite: makesuite(Vect||Lst) Returns a sequence made with a vector. - See also: 1/ makevector 2/ op + See also: 1/ makevector 2/ op Ex1:makesuite([1,2,3]) - ''' return GiacMethods['makesuite'](self,*args) @@ -10522,9 +9686,8 @@ cdef class GiacMethods_base: Help for makevector: makevector(Seq) Returns a vector made with a sequence. - See also: 1/ makesuite + See also: 1/ makesuite Ex1:makevector(1,2,3) - ''' return GiacMethods['makevector'](self,*args) @@ -10533,11 +9696,10 @@ cdef class GiacMethods_base: Help for map: map(Lst(l),Fnc(f)) Applies the function f at the elements of the list l or at a polynomial of internal format. - See also: 1/ apply 2/ set 3/ unapply + See also: 1/ apply 2/ set 3/ unapply Ex1:map([1,2,3],x->x^3) Ex2:map([1,2,3],unapply(x^3,x)) Ex3:map(%%%{1,[2,0]%%%}+%%%{2,[1,1]%%%},(a,b,c)->a*(b+2*c)) - ''' return GiacMethods['map'](self,*args) @@ -10546,8 +9708,7 @@ cdef class GiacMethods_base: Help for maple2mupad: maple2mupad(Str("Name_Maplefile"),Str("Name_Mupadfile")) maple2mupad("file1","file2") translates file1(Maple) to file2(MuPAD). - See also: 1/ maple2xcas - + See also: 1/ maple2xcas ''' return GiacMethods['maple2mupad'](self,*args) @@ -10556,8 +9717,7 @@ cdef class GiacMethods_base: Help for maple2xcas: maple2xcas(Str("NameMapleFile"),Str("NameXcasFile")) maple2xcas("file1","file2") translates file1(Maple) to file2(Xcas). - See also: 1/ maple2mupad - + See also: 1/ maple2mupad ''' return GiacMethods['maple2xcas'](self,*args) @@ -10566,9 +9726,8 @@ cdef class GiacMethods_base: Help for maple_ifactors: maple_ifactors(Intg(n)) Returns 1 or -1 for the sign and the prime factors with their multiplicity of n in a matrix, such as ifactors in Maple. - See also: 1/ ifactors + See also: 1/ ifactors Ex1:maple_ifactors(120) - ''' return GiacMethods['maple_ifactors'](self,*args) @@ -10577,10 +9736,9 @@ cdef class GiacMethods_base: Help for maple_mode: maple_mode(Intg(0) or 1 or 2 or 3) Switches to mode Xcas (0), Maple (1), Mupad (2), TI89 (3). - See also: 1/ python_compat + See also: 1/ python_compat Ex1:maple_mode(1) Ex2:maple_mode(0) - ''' return GiacMethods['maple_mode'](self,*args) @@ -10589,9 +9747,8 @@ cdef class GiacMethods_base: Help for markov: markov(Mtrx(M),[Real(eps)]) Computation of the proper elements of a Markov chain transition matrix M, returns the list of sequence of positive recurrent states, the list of corresponding invariant probabilities, the list of other strongly connected components, the list of probabilities to end up in the sequence of recurrent states. - See also: 1/ randmarkov 2/ plotproba + See also: 1/ randmarkov 2/ plotproba Ex1:markov([[0,0,1/2,0,1/2],[0,0,1,0,0],[1/4,1/4,0,1/4,1/4],[0,0,1/2,0,1/2],[0,0,0,0,1]]) - ''' return GiacMethods['markov'](self,*args) @@ -10600,9 +9757,8 @@ cdef class GiacMethods_base: Help for mat2list: mat2list(Mtrx) Returns the list of the terms of the matrix. - See also: 1/ list2mat 2/ flatten + See also: 1/ list2mat 2/ flatten Ex1:mat2list([[1,8],[4,9]]) - ''' return GiacMethods['mat2list'](self,*args) @@ -10611,9 +9767,8 @@ cdef class GiacMethods_base: Help for mathml: mathml(Expr) Converts the expression into a string to display maths for the web. - See also: 1/ export_mathml 2/ latex + See also: 1/ export_mathml 2/ latex Ex1:mathml(1/2) - ''' return GiacMethods['mathml'](self,*args) @@ -10622,9 +9777,8 @@ cdef class GiacMethods_base: Help for matpow: matpow(Mtrx,Intg(n)) Calculates the nth power of a matrix by jordanization. - See also: 1/ &^ 2/ ^ + See also: 1/ &^ 2/ ^ Ex1:matpow([[1,2],[3,4]],n) - ''' return GiacMethods['matpow'](self,*args) @@ -10633,12 +9787,11 @@ cdef class GiacMethods_base: Help for matrix: matrix(Intg(p),Intg(q),(Fnc(f) or Val(a))) Makes a matrix m(j,k) with p rows and q cols, m(j,k)=f(j,k) or m(j,k)=a : the index start at 0 or 1 according to the mode (Xcas or Maple) (or option of apply) or make a matrix with a table. - See also: 1/ makemat 2/ makelist 3/ apply + See also: 1/ makemat 2/ makelist 3/ apply Ex1:matrix(2,3,(j,k)->1/(j+k+1)) Ex2:matrix(3,2,(j,k)->j+k) Ex3:matrix(2,3,4) - Ex4: A[0..2,0..2]:=1;A[0..1,1..2]:=2;a:=matrix(A) - + Ex4: A[0..2,0..2]:=1;A[0..1,1..2]:=2;a:=matrix(A) ''' return GiacMethods['matrix'](self,*args) @@ -10647,12 +9800,11 @@ cdef class GiacMethods_base: Help for matrix_norm: matrix_norm(Mtrx,[2]||[inf]) Matrix norm induced by l1norm or by l2norm or by linfinty norm. - See also: 1/ l1norm 2/ l2 norm 3/ linfnorm 4/ frobenius_norm + See also: 1/ l1norm 2/ l2 norm 3/ linfnorm 4/ frobenius_norm Ex1:matrix_norm([[1,2,3],[3,-9,6],[4,5,6]]) Ex2:matrix_norm([[1,2,3],[3,-9,6],[4,5,6]],1) Ex3:matrix_norm([[1,2,3],[3,-9,6],[4,5,6]],2) Ex4:matrix_norm([[1,2,3],[3,-9,6],[4,5,6]],inf) - ''' return GiacMethods['matrix_norm'](self,*args) @@ -10661,9 +9813,8 @@ cdef class GiacMethods_base: Help for max: max(Seq||Lst) Maximum of elements of a sequence or a list of reals. - See also: 1/ min + See also: 1/ min Ex1:max(25,35) - ''' return GiacMethods['max'](self,*args) @@ -10672,9 +9823,8 @@ cdef class GiacMethods_base: Help for maxflow: maxflow(Graph(G),Vrtx(s),Vrtx(t)) Returns the optimal value for the max flow problem for network G with the source s and sink t along with an optimal flow (as a matrix). - See also: 1/ minimum_cut + See also: 1/ minimum_cut Ex1:maxflow(digraph(%{[[1,2],2],[[2,3],4],[[3,4],3],[[1,5],3],[[5,2],1],[[5,4],2]%}),1,4) - ''' return GiacMethods['maxflow'](self,*args) @@ -10683,9 +9833,8 @@ cdef class GiacMethods_base: Help for maximal_independent_set: maximal_independent_set(Graph(G)) Returns a maximal set of mutually independent (non-adjacent) vertices in G. - See also: 1/ maximum_independent_set + See also: 1/ maximum_independent_set Ex1:maximal_independent_set(graph("petersen")) - ''' return GiacMethods['maximal_independent_set'](self,*args) @@ -10702,7 +9851,6 @@ cdef class GiacMethods_base: Ex6:maximize(sqrt(x^2+y^2)-z,[x^2+y^2<=16,x+y+z=10],[x,y,z]) Ex7:maximize((1+x^2+3y+5x-4*x*y)/(1+x^2+y^2),x^2/4+y^2/3=9,[x,y]) Ex8:maximize(cos(x)^2+cos(y)^2,x+y=pi/4,[x,y],locus) - ''' return GiacMethods['maximize'](self,*args) @@ -10711,9 +9859,8 @@ cdef class GiacMethods_base: Help for maximum_clique: maximum_clique(Graph(G)) Returns the maximum clique of undirected graph G as a list of vertices. - See also: 1/ clique_number 2/ is_clique 3/ maximum_independent_set + See also: 1/ clique_number 2/ is_clique 3/ maximum_independent_set Ex1:maximum_clique(graph_complement(complete_graph(3,4))) - ''' return GiacMethods['maximum_clique'](self,*args) @@ -10722,9 +9869,8 @@ cdef class GiacMethods_base: Help for maximum_degree: maximum_degree(Graph(G)) Returns the largest degree among the vertices of G. - See also: 1/ minimum_degree 2/ vertex_degree + See also: 1/ minimum_degree 2/ vertex_degree Ex1:maximum_degree(digraph(trail(1,2,3,4,5,6,4,7,8,2))) - ''' return GiacMethods['maximum_degree'](self,*args) @@ -10733,9 +9879,8 @@ cdef class GiacMethods_base: Help for maximum_independent_set: maximum_independent_set(Graph(G)) Returns the maximum independent vertex set of G. - See also: 1/ clique_number 2/ graph_complement 3/ independence_number 4/ maximum_clique + See also: 1/ clique_number 2/ graph_complement 3/ independence_number 4/ maximum_clique Ex1:maximum_independent_set(complete_graph(3,4)) - ''' return GiacMethods['maximum_independent_set'](self,*args) @@ -10744,9 +9889,8 @@ cdef class GiacMethods_base: Help for maximum_matching: maximum_matching(Graph(G)) Returns the list of edges representing maximum matching in G. - See also: 1/ maximum_independent_set + See also: 1/ maximum_independent_set Ex1: G:=graph("soccerball"); draw_graph(highlight_edges(G,maximum_matching(G))) - ''' return GiacMethods['maximum_matching'](self,*args) @@ -10755,11 +9899,10 @@ cdef class GiacMethods_base: Help for maxnorm: maxnorm(Vect or Mtrx) Norm with the max of a vector (or of a matrix): maxnorm([x1,x2,..,xn])=max(|x1|,..,|xn|). - See also: 1/ l2norm 2/ l1norm + See also: 1/ l2norm 2/ l1norm Ex1:maxnorm([1,2]) Ex2:maxnorm([1,2,3,-4]) Ex3:maxnorm([[1,2],[3,-4]]) - ''' return GiacMethods['maxnorm'](self,*args) @@ -10768,11 +9911,10 @@ cdef class GiacMethods_base: Help for mean: mean(Lst||Mtrx,[Lst]) Mean of a list with the second argument as weight or of the columns of a matrix. - See also: 1/ stddev + See also: 1/ stddev Ex1:mean([1,2,3]) Ex2:mean([1,2,3],[1,2,3]) Ex3:mean([[1,2,3],[1,2,3]]) - ''' return GiacMethods['mean'](self,*args) @@ -10781,10 +9923,9 @@ cdef class GiacMethods_base: Help for median: median(Lst||Mtrx,[Lst]) Returns the median of a list with the second argument as weight or of the columns of a matrix. - See also: 1/ quartiles + See also: 1/ quartiles Ex1:median([1,2,3,5,10,4]) Ex2:median([1,2,3,5,10,4],[1,2,3,1,2,3]) - ''' return GiacMethods['median'](self,*args) @@ -10793,9 +9934,8 @@ cdef class GiacMethods_base: Help for median_line: median_line((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) median_line(A,B,C) draws the median-line through A of the triangle ABC. - See also: 1/ midpoint 2/ perpen_bisector + See also: 1/ midpoint 2/ perpen_bisector Ex1:median_line(-1,1-i,i) - ''' return GiacMethods['median_line'](self,*args) @@ -10804,10 +9944,9 @@ cdef class GiacMethods_base: Help for member: member(Elem(e),(Lst(l) or Set(l))) Tests if e is in the list or set l (=0, or k+1 with l[k]=e). - See also: 1/ contains 2/ est_element 3/ find 4/ index + See also: 1/ contains 2/ est_element 3/ find 4/ index Ex1:member(1,[4,3,1,2]) Ex2:member(1,%{4,3,1,2%}) - ''' return GiacMethods['member'](self,*args) @@ -10819,7 +9958,6 @@ cdef class GiacMethods_base: Ex1:mgf(normald,1,0) Ex2:mgf(poisson,5) Ex3:mgf(binomial,n,p) - ''' return GiacMethods['mgf'](self,*args) @@ -10828,13 +9966,12 @@ cdef class GiacMethods_base: Help for mid: mid(Lst(l) or Str(l),Intg(d),Intg(n)) Returns the extracted list of l with n elements (by default n=size(l)-d) and beginning at index d. - See also: 1/ head 2/ tail 3/ left 4/ right 5/ subMat + See also: 1/ head 2/ tail 3/ left 4/ right 5/ subMat Ex1:mid([0,1,2,3,4,5,6],2,3) Ex2:mid([0,1,2,3,4,5,6],2) Ex3:mid("azertyuiop",2,4) Ex4:mid("azertyuiop",2) Ex5:mid([[1,2],[3,4],[5,6]],1) - ''' return GiacMethods['mid'](self,*args) @@ -10843,14 +9980,13 @@ cdef class GiacMethods_base: Help for middle_point: middle_point(Opt) Option of the plotarea command and of the area command. - See also: 1/ plotarea 2/ area + See also: 1/ plotarea 2/ area Ex1: plotarea(x^2,x=0..1,5,trapezoid) Ex2: plotarea(x^2,x=0..1,5,middle_point) Ex3: plotarea(x^2,x=0..1,5,right_rectangle) Ex4: plotarea(x^2,x=0..1,5,left_rectangle) Ex5: area(x^2,x=0..1,5,middle_point) Ex6: area(x^2,x=0..1,5,trapezoid) - ''' return GiacMethods['middle_point'](self,*args) @@ -10859,9 +9995,8 @@ cdef class GiacMethods_base: Help for midpoint: midpoint((Pnt or Cplx),(Pnt or Cplx)) midpoint(A,B) draws the midpoint of the segment AB. - See also: 1/ median_line 2/ perpen_bisector + See also: 1/ median_line 2/ perpen_bisector Ex1:midpoint(-2,2i) - ''' return GiacMethods['midpoint'](self,*args) @@ -10870,9 +10005,8 @@ cdef class GiacMethods_base: Help for min: min(Seq||Lst) Minimum of elements of a sequence or a list of reals. - See also: 1/ max + See also: 1/ max Ex1:min(25,35) - ''' return GiacMethods['min'](self,*args) @@ -10881,10 +10015,9 @@ cdef class GiacMethods_base: Help for minimal_edge_coloring: minimal_edge_coloring(Graph(G),[sto]) Finds the minimal edge coloring of G and returns the sequence n,L where n is the class of G (1 for D colors and 2 for D+1 colors) and L is the list of colors of edges of G as returned by the edges command, or a copy of G with colored edges if the option 'sto' is specified. - See also: 1/ chromatic_index 2/ minimal_vertex_coloring 3/ edges + See also: 1/ chromatic_index 2/ minimal_vertex_coloring 3/ edges Ex1:minimal_edge_coloring(graph("petersen")) Ex2: G:=minimal_edge_coloring(graph("dodecahedron"),sto); draw_graph(G) - ''' return GiacMethods['minimal_edge_coloring'](self,*args) @@ -10893,9 +10026,8 @@ cdef class GiacMethods_base: Help for minimal_spanning_tree: minimal_spanning_tree(Graph(G)) Returns the minimal spanning tree of undirected graph G. - See also: 1/ spanning_tree + See also: 1/ spanning_tree Ex1:minimal_spanning_tree(graph([[0,1,0,4,0,0],[1,0,1,0,4,0],[0,1,0,3,0,1],[4,0,3,0,1,0],[0,4,0,1,0,4],[0,0,1,0,4,0]])) - ''' return GiacMethods['minimal_spanning_tree'](self,*args) @@ -10904,10 +10036,9 @@ cdef class GiacMethods_base: Help for minimal_vertex_coloring: minimal_vertex_coloring(Graph(G),[sto]) Computes the minimal vertex coloring for G and returns the colors in the order of vertices. If optional parameter "sto" is given, the colors are assigned to vertices and the modified copy of G is returned. - See also: 1/ chromatic_number 2/ is_vertex_colorable + See also: 1/ chromatic_number 2/ is_vertex_colorable Ex1:minimal_vertex_coloring(graph("petersen")) Ex2: draw_graph(minimal_vertex_coloring(graph("petersen"),sto)) - ''' return GiacMethods['minimal_vertex_coloring'](self,*args) @@ -10926,7 +10057,6 @@ cdef class GiacMethods_base: Ex8:minimax(abs(x)*sqrt(abs(x)),x=-2..2,15) Ex9:minimax(min(1/cosh(3*sin(x)),sin(9x/10)),x=-3..4,30) Ex10:minimax(when(x==0,0,exp(-1/x^2)),x=-1..1,25) - ''' return GiacMethods['minimax'](self,*args) @@ -10943,7 +10073,6 @@ cdef class GiacMethods_base: Ex6:minimize(sqrt(x^2+y^2)-z,[x^2+y^2<=16,x+y+z=10],[x,y,z]) Ex7:minimize((1+x^2+3y+5x-4*x*y)/(1+x^2+y^2),x^2/4+y^2/3=9,[x,y]) Ex8:minimize(cos(x)^2+cos(y)^2,x+y=pi/4,[x,y],locus) - ''' return GiacMethods['minimize'](self,*args) @@ -10952,9 +10081,8 @@ cdef class GiacMethods_base: Help for minimum_cut: minimum_cut(Graph(G),Vrtx(s),Vrtx(t)) Returns the list of edges forming a minimum cut in a directed graph G with the source s and sink t. - See also: 1/ maxflow + See also: 1/ maxflow Ex1:minimum_cut(digraph(%{[[1,2],2],[[2,3],4],[[3,4],3],[[1,5],3],[[5,2],1],[[5,4],2]%}),1,4) - ''' return GiacMethods['minimum_cut'](self,*args) @@ -10963,9 +10091,8 @@ cdef class GiacMethods_base: Help for minimum_degree: minimum_degree(Graph(G)) Returns the smallest degree among the vertices of G. - See also: 1/ maximum_degree 2/ vertex_degree + See also: 1/ maximum_degree 2/ vertex_degree Ex1:minimum_degree(digraph(trail(1,2,3,4,5,6,4,7,8,2))) - ''' return GiacMethods['minimum_degree'](self,*args) @@ -10974,11 +10101,10 @@ cdef class GiacMethods_base: Help for mkisom: mkisom(Vect,(Sign(1) or -1)) Matrix of an isometry given by its proper elements. - See also: 1/ isom + See also: 1/ isom Ex1:mkisom([1,2],1) Ex2:mkisom([[1,0,0],pi/3],-1) Ex3:mkisom(pi,1) - ''' return GiacMethods['mkisom'](self,*args) @@ -10987,9 +10113,8 @@ cdef class GiacMethods_base: Help for mksa: mksa(Unit) Converts units to the MKSA international unit system. - See also: 1/ convert 2/ ufactor + See also: 1/ convert 2/ ufactor Ex1:mksa(1_N) - ''' return GiacMethods['mksa'](self,*args) @@ -10998,9 +10123,8 @@ cdef class GiacMethods_base: Help for modgcd: modgcd(Poly,Poly) GCD of 2 polynomials, with the modular algorithm. - See also: 1/ gcd 2/ heugcd 3/ ezgcd 4/ psrgcd + See also: 1/ gcd 2/ heugcd 3/ ezgcd 4/ psrgcd Ex1:modgcd(x^4-1,(x-1)^2) - ''' return GiacMethods['modgcd'](self,*args) @@ -11009,11 +10133,10 @@ cdef class GiacMethods_base: Help for mods: mods(Intg,Intg) Returns the Euclidean symmetric remainder of two integers. - See also: 1/ irem 2/ iquo 3/ mod 4/ fracmod + See also: 1/ irem 2/ iquo 3/ mod 4/ fracmod Ex1:mods(8,3) Ex2:mods(10,4) Ex3:mods(11,7) - ''' return GiacMethods['mods'](self,*args) @@ -11023,7 +10146,6 @@ cdef class GiacMethods_base: monotonic() Returns a real that increases as time passes Ex1:monotonic() - ''' return GiacMethods['monotonic'](self,*args) @@ -11032,9 +10154,8 @@ cdef class GiacMethods_base: Help for montre_tortue: montre_tortue(NULL) Shows the turtle. - See also: 1/ cache_tortue + See also: 1/ cache_tortue Ex1:montre_tortue() - ''' return GiacMethods['montre_tortue'](self,*args) @@ -11043,12 +10164,11 @@ cdef class GiacMethods_base: Help for moustache: moustache(Lst,[Lst],[x=a..b||y=a..b]) Box and Whisker plot for a statistical series. - See also: 1/ quartiles + See also: 1/ quartiles Ex1:moustache([-1,1,2,2.2,3,4,-2,5]) Ex2:moustache([1,2,3,5,10,4],x=1..2) Ex3:moustache([1,2,3,5,10,4],[1,2,3,1,2,3]) Ex4:moustache([[6,0,1,3,4,2,5],[0,1,3,4,2,5,6],[1,3,4,2,5,6,0],[3,4,2,5,6,0,1],[4,2,5,6,0,1,3],[2,5,6,0,1,3,4]]) - ''' return GiacMethods['moustache'](self,*args) @@ -11057,9 +10177,8 @@ cdef class GiacMethods_base: Help for moving_average: moving_average(Lst(A),Intg(n)) Applies a moving average filter of length n to a signal sample A, and returns its result as an array of length nops(A)-n+1. - See also: 1/ lowpass + See also: 1/ lowpass Ex1: snd:=soundsec(2):;data:=0.5*threshold(3*sin(2*pi*220*snd),[-1.0,1.0])+randvector(length(snd),normald,0,0.05):;moving_average(data,25) - ''' return GiacMethods['moving_average'](self,*args) @@ -11068,9 +10187,8 @@ cdef class GiacMethods_base: Help for moyal: moyal(Expr,Expr,VectVar) Moyal product of 2 symbols. - See also: 1/ + See also: 1/ Ex1:moyal(x^2+y^4,x^4-y^2,[x,y],5) - ''' return GiacMethods['moyal'](self,*args) @@ -11079,11 +10197,10 @@ cdef class GiacMethods_base: Help for moyenne: moyenne(Lst||Mtrx,[Lst]) Mean of a list with the second argument as weight or of the columns of a matrix. - See also: 1/ stddev + See also: 1/ stddev Ex1:moyenne([1,2,3]) Ex2:moyenne([1,2,3],[1,2,3]) Ex3:moyenne([[1,2,3],[1,2,3]]) - ''' return GiacMethods['moyenne'](self,*args) @@ -11092,7 +10209,7 @@ cdef class GiacMethods_base: Help for mul: mul(Expr||Lst,[Var||Lst],[Intg(a)],[Intg(b)],[Intg(p)]) Multiplies the values of the expression when the variable go from a to b with a step p (product(expression,var,begin,end,step) by default p=1) or product of the elements of a list or product element by element of 2 lists or matrices. - See also: 1/ sum + See also: 1/ sum Ex1:mul(n,n,1,10,2) Ex2:mul(1/n,n,1,10) Ex3:mul(1/n,n,11,1) @@ -11100,7 +10217,6 @@ cdef class GiacMethods_base: Ex5:mul([2,3,4,5]) Ex6:mul([2,3,4],[5,6,7]) Ex7:mul([[2,3,4],[5,6,7]],[[2,3,4],[5,6,7]]) - ''' return GiacMethods['mul'](self,*args) @@ -11109,10 +10225,9 @@ cdef class GiacMethods_base: Help for mult_c_conjugate: mult_c_conjugate(Expr) Returns the expression after multiplication by the complex conjugate of the denominator (or of the numerator if no denominator). - See also: 1/ mult_conjugate + See also: 1/ mult_conjugate Ex1:mult_c_conjugate(1/(3+i*2)) Ex2:mult_c_conjugate(3+i*2) - ''' return GiacMethods['mult_c_conjugate'](self,*args) @@ -11121,10 +10236,9 @@ cdef class GiacMethods_base: Help for mult_conjugate: mult_conjugate(Expr) Returns the expression after multiplication by the conjugate of the denominator (or of the numerator if no denominator). - See also: 1/ mult_c_conjugate + See also: 1/ mult_c_conjugate Ex1:mult_conjugate(sqrt(3)-sqrt(2)) Ex2:mult_conjugate(1/(sqrt(3)-sqrt(2))) - ''' return GiacMethods['mult_conjugate'](self,*args) @@ -11133,12 +10247,11 @@ cdef class GiacMethods_base: Help for multinomial: multinomial(Intg(n),Vect(p),Vect(k)) Returns n!/(k0!*k1!*..;kj!)*(p0^k0*p1^k1..*pj^kj) (sum(p)=1 and sum(k)=n). - See also: 1/ binomial 2/ randvector 3/ ranm + See also: 1/ binomial 2/ randvector 3/ ranm Ex1:multinomial(10,[0.5,0.5],[3,7]) Ex2:multinomial(10,[0.2,0.3,0.5],[1,3,6]) Ex3: randvector(3,multinomial,[1/2,1/3,1/6]) Ex4: ranm(4,3,multinomial,[1/2,1/3,1/6]) - ''' return GiacMethods['multinomial'](self,*args) @@ -11147,10 +10260,9 @@ cdef class GiacMethods_base: Help for multiplier_conjugue: multiplier_conjugue(Expr) Returns the expression after multiplication by the conjugate of the denominator (or of the numerator if no denominator). - See also: 1/ mult_c_conjugate + See also: 1/ mult_c_conjugate Ex1:multiplier_conjugue(sqrt(3)-sqrt(2)) Ex2:multiplier_conjugue(1/(sqrt(3)-sqrt(2))) - ''' return GiacMethods['multiplier_conjugue'](self,*args) @@ -11159,10 +10271,9 @@ cdef class GiacMethods_base: Help for multiplier_conjugue_complexe: multiplier_conjugue_complexe(Expr) Returns the expression after multiplication by the complex conjugate of the denominator (or of the numerator if no denominator). - See also: 1/ mult_conjugate + See also: 1/ mult_conjugate Ex1:multiplier_conjugue_complexe(1/(3+i*2)) Ex2:multiplier_conjugue_complexe(3+i*2) - ''' return GiacMethods['multiplier_conjugue_complexe'](self,*args) @@ -11171,11 +10282,10 @@ cdef class GiacMethods_base: Help for multiply: multiply(Intg or Lst, Intg or Lst) Returns the product of the 2 arguments. - See also: 1/ * + See also: 1/ * Ex1:multiply(41,-4) Ex2:multiply([4,1],[-4,2]) Ex3:multiply([[4,1],[-4,1]],[[4,1],[-4,1]]) - ''' return GiacMethods['multiply'](self,*args) @@ -11184,8 +10294,7 @@ cdef class GiacMethods_base: Help for mupad2maple: mupad2maple(Str("NameMupadFile"),Str("NameMapleFile")) mupad2maple("file1","file2") translates file1(MuPAD) to file2(Maple). - See also: 1/ mupad2xcas - + See also: 1/ mupad2xcas ''' return GiacMethods['mupad2maple'](self,*args) @@ -11194,8 +10303,7 @@ cdef class GiacMethods_base: Help for mupad2xcas: mupad2xcas(Str("NameMupadFile"),Str("NameXcasFile")) mupad2xcas("file1","file2") translates file1(MuPAD) to file2(Xcas). - See also: 1/ mupad2maple - + See also: 1/ mupad2maple ''' return GiacMethods['mupad2xcas'](self,*args) @@ -11204,10 +10312,9 @@ cdef class GiacMethods_base: Help for mycielski: mycielski(Graph(G)) Returns the Mycielskian of undirected graph G. - See also: 1/ chromatic_number 2/ number_of_triangles + See also: 1/ chromatic_number 2/ number_of_triangles Ex1:mycielski(graph("petersen")) Ex2: is_isomorphic(mycielski(mycielski(path_graph(2))),graph("grotzsch")) - ''' return GiacMethods['mycielski'](self,*args) @@ -11216,9 +10323,8 @@ cdef class GiacMethods_base: Help for nCr: nCr(Intg(n),Intg(r)) comb(n,r)=number of combinations of r objects taken among n : n!/(r!(n-r)!) (If n<0 comb(n,r)=n(n-1)..(n-r+1)/r!). - See also: 1/ factorial 2/ perm + See also: 1/ factorial 2/ perm Ex1:nCr(4,2) - ''' return GiacMethods['nCr'](self,*args) @@ -11227,11 +10333,10 @@ cdef class GiacMethods_base: Help for nDeriv: nDeriv(Expr(Xpr),Var(Var),[Real(h)]) Returns an approximation of the derivative number at a point: (Xpr(var+h)-Xpr(var-h))/(2*h) (by default h=0.001). - See also: 1/ avgRC + See also: 1/ avgRC Ex1:nDeriv(f(x),x,h) Ex2:nDeriv(x^2,x,0.1) Ex3:nDeriv(x^2,x) - ''' return GiacMethods['nDeriv'](self,*args) @@ -11240,11 +10345,10 @@ cdef class GiacMethods_base: Help for nInt: nInt(Expr(f(x)),Var(x),Real(a),Real(b)) Returns the approximate value of integrate(f(x),x,a,b) by Romberg's method. - See also: 1/ integrate 2/ gaussquad + See also: 1/ integrate 2/ gaussquad Ex1:nInt(exp(x^2),x,0,1) Ex2:nInt(x^2,x,0,1) Ex3:nInt(exp(-x^2),x,-1,1) - ''' return GiacMethods['nInt'](self,*args) @@ -11253,9 +10357,8 @@ cdef class GiacMethods_base: Help for nPr: nPr(Intg(n),Intg(p)) perm(n,p)=number of arrangements of p objects taken among n : n!/(n-p)! - See also: 1/ comb 2/ factorial + See also: 1/ comb 2/ factorial Ex1:nPr(4,2) - ''' return GiacMethods['nPr'](self,*args) @@ -11264,10 +10367,9 @@ cdef class GiacMethods_base: Help for nSolve: nSolve(Expr,Var,[Guess or Interval],[Method]) Numerical solution of an equation or a system of equations. - See also: 1/ solve 2/ fsolve 3/ csolve + See also: 1/ solve 2/ fsolve 3/ csolve Ex1:nSolve(cos(x)=x,x) Ex2:nSolve(cos(x)=x,x=1.3) - ''' return GiacMethods['nSolve'](self,*args) @@ -11276,10 +10378,9 @@ cdef class GiacMethods_base: Help for ncols: ncols(Mtrx) Number of columns of a matrix. - See also: 1/ rowdim + See also: 1/ rowdim Ex1:ncols([[1,2,3],[4,5,6]]) Ex2:ncols([[1,2],[3,4],[5,6]]) - ''' return GiacMethods['ncols'](self,*args) @@ -11288,11 +10389,10 @@ cdef class GiacMethods_base: Help for negbinomial: negbinomial(Intg(n),Intg(k),Real(p in 0..1)) Returns comb(n+k-1,k)*p^k*(1-p)^n. - See also: 1/ negbinomial_cdf 2/ negbinomial_icdf 3/ binomial + See also: 1/ negbinomial_cdf 2/ negbinomial_icdf 3/ binomial Ex1:negbinomial(4,0,0.5) Ex2:negbinomial(4,2,0.6) Ex3:negbinomial(4,6,0.3) - ''' return GiacMethods['negbinomial'](self,*args) @@ -11301,11 +10401,10 @@ cdef class GiacMethods_base: Help for negbinomial_cdf: negbinomial_cdf(Intg(n),Real(p),Real(x),[Real(y)]) Returns Proba(X<=x) or Proba(x<=X<=y) when X follows the negbinomial(n,p) law. - See also: 1/ negbinomial 2/ negbinomial_icdf + See also: 1/ negbinomial 2/ negbinomial_icdf Ex1:negbinomial_cdf(4,0.5,2) Ex2:negbinomial_cdf(4,0.1,2) Ex3:negbinomial_cdf(4,0.5,2,3) - ''' return GiacMethods['negbinomial_cdf'](self,*args) @@ -11314,10 +10413,9 @@ cdef class GiacMethods_base: Help for negbinomial_icdf: negbinomial_icdf(Intg(n),Real(p),Real(t)) Returns h such as Proba(X<=h)=t when X follows the negbinomial(n,p) law. - See also: 1/ negbinomial 2/ negbinomial_cdf + See also: 1/ negbinomial 2/ negbinomial_cdf Ex1:negbinomial_icdf(4,0.5,0.68) Ex2:negbinomial_icdf(4,0.1,0.95) - ''' return GiacMethods['negbinomial_icdf'](self,*args) @@ -11326,9 +10424,8 @@ cdef class GiacMethods_base: Help for neighbors: neighbors(Graph(G),[Vrtx(v)]) Returns the list of vertices adjacent to vertex v of G. If v is omitted, a list of adjacency lists of all vertices in G is returned. - See also: 1/ adjacency_matrix 2/ vertex_degree 3/ in_degree 3/ out_degree + See also: 1/ adjacency_matrix 2/ vertex_degree 3/ in_degree 3/ out_degree Ex1:neighbors(digraph(trail(1,2,3,4,5,6,4,7,8,2)),4) - ''' return GiacMethods['neighbors'](self,*args) @@ -11337,9 +10434,8 @@ cdef class GiacMethods_base: Help for network_transitivity: network_transitivity(Graph(G)) Returns the transitivity (also called triangle density or global clustering coefficient) of G. - See also: 1/ clustering_coefficient 2/ number_of_triangles + See also: 1/ clustering_coefficient 2/ number_of_triangles Ex1:network_transitivity(graph(%{[1,2],[2,3],[2,4],[3,4],[4,1]%})) - ''' return GiacMethods['network_transitivity'](self,*args) @@ -11348,9 +10444,8 @@ cdef class GiacMethods_base: Help for newList: newList(Intg(n)) Returns the list made with n zeros. - See also: 1/ newMat 2/ makelist + See also: 1/ newMat 2/ makelist Ex1:newList(4) - ''' return GiacMethods['newList'](self,*args) @@ -11359,9 +10454,8 @@ cdef class GiacMethods_base: Help for newMat: newMat(Intg(n),Intg(p)) Returns the list with n rows and p columns, made with zeros. - See also: 1/ newList 2/ makemat + See also: 1/ newList 2/ makemat Ex1:newMat(2,3) - ''' return GiacMethods['newMat'](self,*args) @@ -11370,12 +10464,11 @@ cdef class GiacMethods_base: Help for newton: newton(Expr(f(x)),Var(x),[ApproxVal(a),NumIter(p)]) newton(f(x),x,a,p)=one root of f(x) by Newton method beginning with a and p iterations (by default p=20). - See also: 1/ rootof + See also: 1/ rootof Ex1:newton(x^2-2,x) Ex2:newton(x^2-2,x,2) Ex3:newton(x^2-2,x,-2) Ex4:newton(x^2-2,x,2,5,1e-7) - ''' return GiacMethods['newton'](self,*args) @@ -11384,14 +10477,13 @@ cdef class GiacMethods_base: Help for newton_solver: newton_solver(Opt) Argument for fsolve giving the method for solving a numerical equation. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve(cos(x)=x,x,0..1,bisection_solver) Ex2: fsolve(cos(x)=x,x,0..1,brent_solver) Ex3: fsolve(cos(x)=x,x,0..1,falsepos_solver) Ex4: fsolve(cos(x)=x,x,0,newton_solver) Ex5: fsolve(cos(x)=x,x,0,secant_solver) Ex6: fsolve(cos(x)=x,x,0,steffenson_solver) - ''' return GiacMethods['newton_solver'](self,*args) @@ -11400,14 +10492,13 @@ cdef class GiacMethods_base: Help for newtonj_solver: newtonj_solver(Opt) Argument for fsolve giving the method for solving a system of numerical equations. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],dnewton_solver) Ex2: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrid_solver) Ex3: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybrids_solver) Ex4: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridj_solver) Ex5: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],hybridsj_solver) Ex6: fsolve([x^2+y-2,x+y^2-2],[x,y],[2,2],newtonj_solver) - ''' return GiacMethods['newtonj_solver'](self,*args) @@ -11416,10 +10507,9 @@ cdef class GiacMethods_base: Help for nextperm: nextperm(Intg(n)) Returns the next permutation with the lexicographic order. - See also: 1/ prevperm 2/ is_permu + See also: 1/ prevperm 2/ is_permu Ex1:nextperm([0,2,1,3]) Ex2:nextperm([0,3,2,1]) - ''' return GiacMethods['nextperm'](self,*args) @@ -11428,10 +10518,9 @@ cdef class GiacMethods_base: Help for nextprime: nextprime(Intg(a)) Next prime or pseudo-prime after a given integer. - See also: 1/ prevprime 2/ is_prime 3/ ithprime + See also: 1/ prevprime 2/ is_prime 3/ ithprime Ex1:nextprime(9856989898990) Ex2:nextprime(97160249868928888261606009) - ''' return GiacMethods['nextprime'](self,*args) @@ -11440,7 +10529,7 @@ cdef class GiacMethods_base: Help for nlpsolve: nlpsolve(objective, [constr], [bd], [opts]) Solves a nonlinear programming problem of optimizing the objective obj under constraints constr (list of equations and/or inequations) and within bounds bd (sequence of x=a..b) with optional options (for example setting an initial point). - See also: 1/ lpsolve 2/ fsolve 3/ fMin 4/ fMax + See also: 1/ lpsolve 2/ fsolve 3/ fMin 4/ fMax Ex1:nlpsolve((x1-10)^3+(x2-20)^3,[(x1-5)^2+(x2-5)^2>=100,(x2-5)^2+(x1-6)^2<=82.81],nlp_initialpoint=[x1=20.1,x2=5.84]) Ex2:nlpsolve(sin(x1+x2)+(x1-x2)^2-1.5x1+2.5x2+1,x1=-1.5..4,x2=-3..3) Ex3:nlpsolve(ln(1+x1^2)-x2,[(1+x1^2)^2+x2^2=4]) @@ -11448,10 +10537,9 @@ cdef class GiacMethods_base: Ex5:nlpsolve(-x1*x2*x3,[72-x1-2x2-2x3>=0],x1=0..20,x2=0..11,x3=0..42) Ex6:nlpsolve(2-1/120*x1*x2*x3*x4*x5,[x1<=1,x2<=2,x3<=3,x4<=4,x5<=5],assume=nlp_nonnegative) Ex7:nlpsolve(sin(x)/x,x=1..30) - Ex8:nlpsolve(x^3+2x*y-2y^2,x=-10..10,y=-10..10,nlp_initialpoint=[x=3,y=4],maximize) + Ex8:nlpsolve(x^3+2x*y-2y^2,x=-10..10,y=-10..10,nlp_initialpoint=[x=3,y=4],maximize) Ex9:nlpsolve(w^3*(v-w)^2+(w-x-1)^2+(x-y-2)^2+(y-z-3)^2,[w+x+y+z<=5,3z+2v=3],assume=nlp_nonnegative) Ex10:nlpsolve(sin(x)*Psi(x),x=1..20,nlp_initialpoint=[x=16]) - ''' return GiacMethods['nlpsolve'](self,*args) @@ -11461,7 +10549,6 @@ cdef class GiacMethods_base: nodisp(Expr) Displays Done in place of a value. Ex1:nodisp(A:=ranm(50,50)) - ''' return GiacMethods['nodisp'](self,*args) @@ -11470,10 +10557,9 @@ cdef class GiacMethods_base: Help for non_recursive_normal: non_recursive_normal(Expr) Simplifies the expressions, but without simplification inside of non-rational expressions. - See also: 1/ normal + See also: 1/ normal Ex1:non_recursive_normal(sin(x+x)+sin(2*x)+x+x) Ex2:non_recursive_normal(sin(2*x)+sin(2*x)+x+x) - ''' return GiacMethods['non_recursive_normal'](self,*args) @@ -11482,9 +10568,8 @@ cdef class GiacMethods_base: Help for nop: nop(NULL) No OPeration instruction. - See also: 1/ + See also: 1/ Ex1:nop() - ''' return GiacMethods['nop'](self,*args) @@ -11493,11 +10578,10 @@ cdef class GiacMethods_base: Help for nops: nops(Lst or Str or Seq) Returns the size of a list, a string or a sequence. - See also: 1/ sizes 2/ dim 3/ degree + See also: 1/ sizes 2/ dim 3/ degree Ex1:nops([1,2,3]) Ex2:nops("bonjour") Ex3:nops(1,2,3) - ''' return GiacMethods['nops'](self,*args) @@ -11506,12 +10590,11 @@ cdef class GiacMethods_base: Help for norm: norm(Vect or Mtrx) Returns the l2 norm of a vector = sqrt(x1^2+x2^2+...xn^2) or matrix norm induced by l2 norm. - See also: 1/ maxnorm 2/ l1norm + See also: 1/ maxnorm 2/ l1norm Ex1:norm([1,2]) Ex2:norm([1,2,3,-4]) Ex3:norm([[1,2],[3,-4]]) Ex4:norm([[1,2,3],[3,-9,6],[4,5,6]]) - ''' return GiacMethods['norm'](self,*args) @@ -11520,11 +10603,10 @@ cdef class GiacMethods_base: Help for normal: normal(Expr) Simplifies the expression. - See also: 1/ simplify + See also: 1/ simplify Ex1:normal(2*x+y=1) Ex2:normal(2*x*2) Ex3:normal((2*x+1)^2) - ''' return GiacMethods['normal'](self,*args) @@ -11533,11 +10615,10 @@ cdef class GiacMethods_base: Help for normal_cdf: normal_cdf(Real(mu),Real(sigma),Real(x0),[Real(y0)]) Returns the probability that a Normal random variable is less than x0 or between x0 and y0 (mu is the mean and sigma the standard deviation). - See also: 1/ UTPN 2/ normal_icdf 3/ normald + See also: 1/ UTPN 2/ normal_icdf 3/ normald Ex1:normal_cdf(1.96) Ex2:normal_cdf(1,2,2.96*sqrt(2)) Ex3:normal_cdf(1,2,1.4*sqrt(2),2.96*sqrt(2)) - ''' return GiacMethods['normal_cdf'](self,*args) @@ -11546,10 +10627,9 @@ cdef class GiacMethods_base: Help for normal_icdf: normal_icdf(Real(mu),Real(sigma),Real(p)) Returns h such as the probability that a Normal random variable is less than h is p (mu is the mean and sigma the standard deviation and 0<=p<=1). - See also: 1/ normal_cdf 2/ normald + See also: 1/ normal_cdf 2/ normald Ex1:normal_icdf(0.95) Ex2:normal_icdf(1,2,0.95) - ''' return GiacMethods['normal_icdf'](self,*args) @@ -11558,12 +10638,11 @@ cdef class GiacMethods_base: Help for normald: normald(Real(mu),Real(sigma),Real(x0)) Returns the probability density of the Normal law (mu is the mean and sigma the standard deviation). - See also: 1/ normal_cdf 2/ normal_icdf 3/ randvector 4/ ranm + See also: 1/ normal_cdf 2/ normal_icdf 3/ randvector 4/ ranm Ex1:normald(1) Ex2:normald(1,2,3.5) Ex3: randvector(3,normald,1,0.5) Ex4: ranm(4,3,normald,1,0.5) - ''' return GiacMethods['normald'](self,*args) @@ -11572,11 +10651,10 @@ cdef class GiacMethods_base: Help for normald_cdf: normald_cdf(Real(mu),Real(sigma),Real(x0),[Real(y0)]) Returns the probability that a Normal random variable is less than x0 or between x0 and y0 (mu is the mean and sigma the standard deviation). - See also: 1/ UTPN 2/ normal_icdf 3/ normald + See also: 1/ UTPN 2/ normal_icdf 3/ normald Ex1:normald_cdf(1.96) Ex2:normald_cdf(1,2,2.96*sqrt(2)) Ex3:normald_cdf(1,2,1.4*sqrt(2),2.96*sqrt(2)) - ''' return GiacMethods['normald_cdf'](self,*args) @@ -11585,10 +10663,9 @@ cdef class GiacMethods_base: Help for normald_icdf: normald_icdf(Real(mu),Real(sigma),Real(p)) Returns h such as the probability that a Normal random variable is less than h is p (mu is the mean and sigma the standard deviation and 0<=p<=1). - See also: 1/ normal_cdf 2/ normald + See also: 1/ normal_cdf 2/ normald Ex1:normald_icdf(0.95) Ex2:normald_icdf(1,2,0.95) - ''' return GiacMethods['normald_icdf'](self,*args) @@ -11597,12 +10674,11 @@ cdef class GiacMethods_base: Help for normalize: normalize(Lst||Cplx) Returns the vector divided by its l2norm. It is also an option for plotfield. - See also: 1/ l2norm + See also: 1/ l2norm Ex1:normalize(3+4*i) Ex2:normalize([3,4]) Ex3: fieldplot(-t*y,[t,y],normalize) Ex4: fieldplot(-t*y,[t,y],normalize,xstep=0.5,ystep=0.5) - ''' return GiacMethods['normalize'](self,*args) @@ -11611,10 +10687,9 @@ cdef class GiacMethods_base: Help for normalt: normalt(Lst,Real,[Real],Fnc,[Real]) Z-Test/normal law: arg1=[success,trial] or [mean,sample size] or data, arg2=proportion or data, arg3 optional if data=sigma, arg4 alternative '!=' or '>' or '<', arg5 optional alpha confidence level. - See also: 1/ studentt 2/ chisquaret 3/ kolmogorovt + See also: 1/ studentt 2/ chisquaret 3/ kolmogorovt Ex1:normalt([10,30],.5,.02,'!=',0.1) Ex2:normalt([0.48,50],0.5,0.1,'<') - ''' return GiacMethods['normalt'](self,*args) @@ -11623,10 +10698,9 @@ cdef class GiacMethods_base: Help for normalvariate: normalvariate(Real(mu),Real(sigma)) Returns a random real with normal distribution N(mu,sigma). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randpoisson 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randpoisson 8/ randgeometric 9/ randmultinomial Ex1:normalvariate(0,1) Ex2:normalvariate(2,1) - ''' return GiacMethods['normalvariate'](self,*args) @@ -11635,9 +10709,8 @@ cdef class GiacMethods_base: Help for nprimes: nprimes(Intg(n)) Counts the number of primes less than n. - See also: 1/ ithprime 2/ prevprime 3/ nextprime 4/ isprime + See also: 1/ ithprime 2/ prevprime 3/ nextprime 4/ isprime Ex1:nprimes(20) - ''' return GiacMethods['nprimes'](self,*args) @@ -11646,10 +10719,9 @@ cdef class GiacMethods_base: Help for nrows: nrows(Mtrx) Number of rows of a matrix. - See also: 1/ ncols + See also: 1/ ncols Ex1:nrows([[1,2,3],[4,5,6]]) Ex2:nrows([[1,2],[3,4],[5,6]]) - ''' return GiacMethods['nrows'](self,*args) @@ -11658,9 +10730,8 @@ cdef class GiacMethods_base: Help for nuage_points: nuage_points(Mtrx) Draws for k=0..nrows, the points (xk,yk) where xk=element row k column 0 and yk=element row k column j (j=1..ncols). - See also: 1/ polygonplot 2/ polygonscatterplot 3/ listplot + See also: 1/ polygonplot 2/ polygonscatterplot 3/ listplot Ex1:nuage_points([[1,2,3],[2,0,1],[-1,2,3]]) - ''' return GiacMethods['nuage_points'](self,*args) @@ -11669,10 +10740,9 @@ cdef class GiacMethods_base: Help for nullspace: nullspace(Mtrx) Kernel of a linear map with matrix M. - See also: 1/ image 2/ rref 3/ Nullspace + See also: 1/ image 2/ rref 3/ Nullspace Ex1:nullspace([[1,2],[3,6]]) Ex2:nullspace([[1,2,3],[1,3,6],[2,5,9]]) - ''' return GiacMethods['nullspace'](self,*args) @@ -11681,9 +10751,8 @@ cdef class GiacMethods_base: Help for number_of_edges: number_of_edges(Graph(G)) Returns the number of edges/arcs of G. - See also: 1/ edges 2/ number_of_vertices + See also: 1/ edges 2/ number_of_vertices Ex1:number_of_edges(complete_graph(5)) - ''' return GiacMethods['number_of_edges'](self,*args) @@ -11692,10 +10761,9 @@ cdef class GiacMethods_base: Help for number_of_spanning_trees: number_of_spanning_trees(Graph(G)) Returns the number of spanning trees in undirected graph G. - See also: 1/ spanning_tree + See also: 1/ spanning_tree Ex1:number_of_spanning_trees(complete_graph(4)) Ex2:number_of_spanning_trees(graph(trail(1,2,3,4,1,3))) - ''' return GiacMethods['number_of_spanning_trees'](self,*args) @@ -11704,9 +10772,8 @@ cdef class GiacMethods_base: Help for number_of_triangles: number_of_triangles(Graph(G)) Returns the number of 3-cliques if G is undirected resp. the number of directed cycles on 3 vertices if G is directed. - See also: 1/ is_clique 2/ maximal_clique + See also: 1/ is_clique 2/ maximal_clique Ex1:number_of_triangles(graph("tetrahedron")) - ''' return GiacMethods['number_of_triangles'](self,*args) @@ -11715,9 +10782,8 @@ cdef class GiacMethods_base: Help for number_of_vertices: number_of_vertices(Graph(G)) Returns the number of vertices of G. - See also: 1/ graph_vertices 2/ number_of_edges + See also: 1/ graph_vertices 2/ number_of_edges Ex1:number_of_vertices(graph("petersen")) - ''' return GiacMethods['number_of_vertices'](self,*args) @@ -11726,11 +10792,10 @@ cdef class GiacMethods_base: Help for numer: numer(Frac(a/b) or RatFrac) Returns the numerator of the simplified fraction. - See also: 1/ getNum 2/ getDenom 3/ denom 4/ f2nd + See also: 1/ getNum 2/ getDenom 3/ denom 4/ f2nd Ex1:numer(25/15) Ex2:numer((x^3-1)/(x^2-1)) Ex3:numer(1+(x^3-1)/x^2) - ''' return GiacMethods['numer'](self,*args) @@ -11739,10 +10804,9 @@ cdef class GiacMethods_base: Help for octahedron: octahedron(Pnt(A),Pnt(B),Pnt(C)) Draws an octahedron with center A, vertex B and such that the plane ABC contains 4 vertices. - See also: 1/ icosahedron 2/ dodecahedron 3/ cube 4/ tetrahedron + See also: 1/ icosahedron 2/ dodecahedron 3/ cube 4/ tetrahedron Ex1:octahedron([0,0,0],[0,0,5],[0,5,0]) Ex2:octahedron(evalf([0,0,0],[3,2,4],[1,1,0])) - ''' return GiacMethods['octahedron'](self,*args) @@ -11751,10 +10815,9 @@ cdef class GiacMethods_base: Help for odd: odd(Intg(n)) Returns 1 if the integer is odd, else returns 0. - See also: 1/ even + See also: 1/ even Ex1:odd(6) Ex2:odd(1251) - ''' return GiacMethods['odd'](self,*args) @@ -11763,10 +10826,9 @@ cdef class GiacMethods_base: Help for odd_girth: odd_girth(Graph(G)) Returns the length of the shortest odd cycle in the undirected unweighted graph G. - See also: 1/ girth + See also: 1/ girth Ex1:odd_girth(graph("petersen")) Ex2:odd_girth(hypercube_graph(3)) - ''' return GiacMethods['odd_girth'](self,*args) @@ -11775,9 +10837,8 @@ cdef class GiacMethods_base: Help for odd_graph: odd_graph(Intg(n)) Returns the odd graph of order n as Kneser graph K(2n-1,n-1), where n<=8. - See also: 1/ kneser_graph + See also: 1/ kneser_graph Ex1:odd_graph(3) - ''' return GiacMethods['odd_graph'](self,*args) @@ -11786,7 +10847,7 @@ cdef class GiacMethods_base: Help for odeplot: odeplot(Expr,VectVar,VectInitCond) odeplot(f(t,y),[t,y],[t0,y0]) draws the solution of y'=f(t,y) and y(t0)=y0 or of the system [x'=g(t,x,y),y'=h(t,x,y)] with x(t0)=x0 and y(t0)=y0. - See also: 1/ interactive_plotode 2/ fieldplot 3/ odesolve 4/ desolve + See also: 1/ interactive_plotode 2/ fieldplot 3/ odesolve 4/ desolve Ex1:odeplot(sin(t*y),[t,y],[0,1]) Ex2:odeplot(sin(t*y),[t=-10..10,y],[0,1]) Ex3:odeplot(sin(t*y),[t=-3..3,y],[0,1],tstep=0.1,color=vert) @@ -11794,7 +10855,6 @@ cdef class GiacMethods_base: Ex5:odeplot([x-0.3*x*y, 0.3*x*y-y], [t,x,y],[0,0.3,0.7],plan) Ex6:odeplot([-y+b,-1+(x-a)^2+(y-b)^2],[t=-3..3,x,y],[0,a+1,b+0.5],plan) Ex7:odeplot(5*[-y,x],[t=0..1,x,y],[0,0.3,0.7],tstep=0.05,plan) - ''' return GiacMethods['odeplot'](self,*args) @@ -11803,13 +10863,12 @@ cdef class GiacMethods_base: Help for odesolve: odesolve(Expr,VectVar,VectInitCond,FinalVal,[tstep=Val,curve]) odesolve(f(t,y),[t,y],[t0,y0],t1)=odesolve(t0..t1,f,y0)=y(t1) for y approx sol of y'=f(t,y) and y(t0)=y0 with y=vector for systems. - See also: 1/ plotode 2/ plotfield 3/ interactive_plotode 4/ desolve + See also: 1/ plotode 2/ plotfield 3/ interactive_plotode 4/ desolve Ex1:odesolve(sin(t*y),[t,y],[0,1],2) Ex2:odesolve(0..2,(t,y)->sin(t*y),1) Ex3:odesolve(0..pi,(t,v)->{[-v[1],v[0]]},[0,1]) Ex4:odesolve(sin(t*y),t=0..2,y,1,tstep=0.5) Ex5:odesolve(sin(t*y),t=0..2,y,1,tstep=0.5,curve) - ''' return GiacMethods['odesolve'](self,*args) @@ -11818,13 +10877,12 @@ cdef class GiacMethods_base: Help for op: op(Op or Fnc) Returns the arguments of an operator as a sequence. - See also: 1/ sommet 2/ quote 3/ makesuite + See also: 1/ sommet 2/ quote 3/ makesuite Ex1:op(quote(gcd(45,126))) Ex2:op('gcd(45,126)') Ex3:op('1+2')[1] Ex4:op([1,2,3]) Ex5:op(set[1,2,3]) - ''' return GiacMethods['op'](self,*args) @@ -11833,10 +10891,9 @@ cdef class GiacMethods_base: Help for open_polygon: open_polygon(LstPnt||LstCplx) Returns and draws the polygonal line where its vertices are the element of l. - See also: 1/ isopolygon 2/ quadrilateral + See also: 1/ isopolygon 2/ quadrilateral Ex1:open_polygon(i,1+i,2-i,-1,-1+i/2) Ex2:open_polygon(point(0,0,0),point(3,3,3),point(0,0,3),point(3,0,0)) - ''' return GiacMethods['open_polygon'](self,*args) @@ -11845,11 +10902,10 @@ cdef class GiacMethods_base: Help for ord: ord(Char||LstChar) Returns the ASCII code of a character or of the first character of a string. - See also: 1/ asc 2/ char + See also: 1/ asc 2/ char Ex1:ord("A") Ex2:ord("ABC") Ex3:ord(["a","b","c"]) - ''' return GiacMethods['ord'](self,*args) @@ -11860,7 +10916,6 @@ cdef class GiacMethods_base: Returns element order of g in (Z/nZ)^* or in a finite field. Ex1:order(3 % 7) Ex2: GF(3,5,g); order(g^2+g+1); - ''' return GiacMethods['order'](self,*args) @@ -11869,10 +10924,9 @@ cdef class GiacMethods_base: Help for order_size: order_size(Expr) Remainder (O term) of a series expansion: limit(x^a*order_size(x),x=0)=0 if a>0. - See also: 1/ series + See also: 1/ series Ex1:order_size(x) Ex2: limit(sqrt(x)*order_size(x),x=0) - ''' return GiacMethods['order_size'](self,*args) @@ -11881,12 +10935,11 @@ cdef class GiacMethods_base: Help for ordinate: ordinate(Pnt or Vect) Returns the ordinate of a point or a vector. - See also: 1/ abscissa 2/ affix 3/ cote 4/ coordinates + See also: 1/ abscissa 2/ affix 3/ cote 4/ coordinates Ex1:ordinate(point(1+2*i)) Ex2:ordinate(point(i)-point(1+2*i)) Ex3:ordinate(-1-i) Ex4:ordinate(point(1,2,3)) - ''' return GiacMethods['ordinate'](self,*args) @@ -11895,11 +10948,10 @@ cdef class GiacMethods_base: Help for orthocenter: orthocenter((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) Shows the orthocenter of a triangle or of the triangle made with 3 points. - See also: 1/ altitude 2/ triangle + See also: 1/ altitude 2/ triangle Ex1:orthocenter(1+i,2,i) Ex2:orthocenter(point(1+i),point(2),point(i)) Ex3:orthocenter(triangle(0,1,1+i)) - ''' return GiacMethods['orthocenter'](self,*args) @@ -11908,10 +10960,9 @@ cdef class GiacMethods_base: Help for orthogonal: orthogonal((Pnt),(Line or Plan)) orthogonal(A,line(B,C)) draws the orthogonal plane of line BC through A and orthogonal(A,plane(B,C,D)) draws the orthogonal line of plane(B,C,D) through A. - See also: 1/ altitude 2/ perpendicular + See also: 1/ altitude 2/ perpendicular Ex1:orthogonal(point(0,0,0),line(point(1,0,0),point(0,1,0))) Ex2:orthogonal(point(0,0,0),plane(point(1,0,0),point(0,1,0),point(0,0,1))) - ''' return GiacMethods['orthogonal'](self,*args) @@ -11920,14 +10971,13 @@ cdef class GiacMethods_base: Help for osculating_circle: osculating_circle(Curve,Point) Osculating circle at point M to the curve C. - See also: 1/ curvature 2/ evolute + See also: 1/ curvature 2/ evolute Ex1:osculating_circle(plot(x^2),point(1,1)) Ex2:osculating_circle([5*cos(t),5*sin(t)],t,0) Ex3:osculating_circle([t,t^2],t) Ex4:osculating_circle([t,t^2],t,1) Ex5:osculating_circle([3*exp(t/2)*cos(t),3*exp(t/2)*sin(t)],t) Ex6:osculating_circle([3*exp(t/2)*cos(t),3*exp(t/2)*sin(t)],t,7) - ''' return GiacMethods['osculating_circle'](self,*args) @@ -11936,9 +10986,8 @@ cdef class GiacMethods_base: Help for p1oc2: p1oc2(Permut,Cycle) Returns the permutation product of p1 and c2. - See also: 1/ c1op2 2/ p1op2 + See also: 1/ c1op2 2/ p1op2 Ex1:p1oc2([0,2,1],[2,1,3]) - ''' return GiacMethods['p1oc2'](self,*args) @@ -11947,9 +10996,8 @@ cdef class GiacMethods_base: Help for p1op2: p1op2(Permut,Permut) Returns the permutation product of p1 and p2. - See also: 1/ c1op2 2/ p1oc2 + See also: 1/ c1op2 2/ p1oc2 Ex1:p1op2([0,2,1],[1,0,3,2]) - ''' return GiacMethods['p1op2'](self,*args) @@ -11961,7 +11009,6 @@ cdef class GiacMethods_base: Ex1:pa2b2(17) Ex2:pa2b2(209) Ex3:pa2b2(229) - ''' return GiacMethods['pa2b2'](self,*args) @@ -11970,9 +11017,8 @@ cdef class GiacMethods_base: Help for pade: pade(Expr(Xpr), Var(x), (Intg(n) || Poly(N)), Intg(p)) Pade approximation P/Q=Xpr mod x^(n+1) or mod N with degree(P)3,x^20 (by default a=1) to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ bartlett_hann_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ bartlett_hann_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(poisson_window(randvector(1000,0..1),0.5)) - ''' return GiacMethods['poisson_window'](self,*args) @@ -12932,10 +11905,9 @@ cdef class GiacMethods_base: Help for polar: polar(Crcle,Pnt or Cplxe(A)) Returns the line of the conjugated points of A with respect to the circle. - See also: 1/ pole 2/ is_conjugate + See also: 1/ pole 2/ is_conjugate Ex1:polar(circle(0,1),point(1+i)/2) Ex2:polar(circle(0,1),point(1+i)) - ''' return GiacMethods['polar'](self,*args) @@ -12944,12 +11916,11 @@ cdef class GiacMethods_base: Help for polar_coordinates: polar_coordinates(Pnt or Cplx or LstRectCoord) Returns the list of the norm and of the argument of the affix of a point (for 2D) or of a complex number or of the list of rectangular coordinates. - See also: 1/ abscissapoint 2/ ordinate 3/ rectangular_coordinates 4/ polar_point + See also: 1/ abscissapoint 2/ ordinate 3/ rectangular_coordinates 4/ polar_point Ex1:polar_coordinates(point(1+2*i)) Ex2:polar_coordinates(-1-i) Ex3:polar_coordinates([-1,2]) Ex4:polar_coordinates(point(1+2*i)-point(-1+i)) - ''' return GiacMethods['polar_coordinates'](self,*args) @@ -12958,10 +11929,9 @@ cdef class GiacMethods_base: Help for polar_point: polar_point(Real(r),Real(t)) Returns the point (for 2D) with the arguments r and t as polar coordinates (i.e. with r*exp(i*t) as affix). - See also: 1/ abscissa 2/ ordinate 3/ polar_coordinates 4/ rectangular_coordinates 5/ point + See also: 1/ abscissa 2/ ordinate 3/ polar_coordinates 4/ rectangular_coordinates 5/ point Ex1:polar_point(1,pi/4) Ex2:polar_point(2,-pi/3) - ''' return GiacMethods['polar_point'](self,*args) @@ -12970,10 +11940,9 @@ cdef class GiacMethods_base: Help for polarplot: polarplot(Expr,Var,VarMin,VarMax) plotpolar(f(x),x,a,b) draws the polar curve r=f(x) for x in [a,b]. - See also: 1/ plotparam 2/ plotfunc 3/ plotpolar + See also: 1/ plotparam 2/ plotfunc 3/ plotpolar Ex1:polarplot(sin(2*x),x,0,pi) Ex2:polarplot(sin(2*x),x,0,pi,tstep=0.1) - ''' return GiacMethods['polarplot'](self,*args) @@ -12982,10 +11951,9 @@ cdef class GiacMethods_base: Help for pole: pole(Crcle,Line) Returns the point having the line as polar with respect to the circle . - See also: 1/ polar 2/ is_conjugate + See also: 1/ polar 2/ is_conjugate Ex1:pole(circle(0,1),line(i,1)) Ex2:pole(circle(0,1),line((1+i),2)) - ''' return GiacMethods['pole'](self,*args) @@ -12994,12 +11962,11 @@ cdef class GiacMethods_base: Help for poly2symb: poly2symb(Lst,Var) Gives the polynomial (or its value) : the first argument is the vector of coefficients and the second argument is the variable (by default x). - See also: 1/ e2r 2/ symb2poly + See also: 1/ e2r 2/ symb2poly Ex1:poly2symb([1,2,3]) Ex2:poly2symb([1,2,3],x) Ex3:poly2symb([1,2,3],-1) Ex4:poly2symb([1,2,-1],y) - ''' return GiacMethods['poly2symb'](self,*args) @@ -13008,10 +11975,9 @@ cdef class GiacMethods_base: Help for polyEval: polyEval(Vect,Real(x0)) Evaluates at a point x0, a polynomial given by its coefficients. - See also: 1/ proot 2/ pcoeff + See also: 1/ proot 2/ pcoeff Ex1:polyEval([1,0,-2],1) Ex2:polyEval([1,2,-25,-26,120],8) - ''' return GiacMethods['polyEval'](self,*args) @@ -13020,10 +11986,9 @@ cdef class GiacMethods_base: Help for polygon: polygon(LstPnt||LstCplx) Returns and draws the polygon where its vertices are the elements of l. - See also: 1/ isopolygon 2/ quadrilateral 3/ convexhull 4/ hexagon + See also: 1/ isopolygon 2/ quadrilateral 3/ convexhull 4/ hexagon Ex1:polygon(i,1+i,2-i,-1,-1+i/2) Ex2:polygon(point(0,0,0),point(3,3,3),point(0,0,3),point(3,0,0)) - ''' return GiacMethods['polygon'](self,*args) @@ -13032,11 +11997,10 @@ cdef class GiacMethods_base: Help for polygone_rempli: polygone_rempli(Intg(n)) The argument is an integer <-1 which gives the number of previous turtle positions drawing a polygon and created this full polygon. - See also: 1/ + See also: 1/ Ex1: repete(4,avance 40,tourne_droite);polygone_rempli -8 Ex2: repete(3,avance 40,tourne_droite 120);polygone_rempli -6 Ex3: repete(3,avance 40,avance 40,tourne_droite 120);polygone_rempli -9 - ''' return GiacMethods['polygone_rempli'](self,*args) @@ -13045,9 +12009,8 @@ cdef class GiacMethods_base: Help for polygonplot: polygonplot(Mtrx) Draws the polygons joining for j fixed and for k=0..nrows, the points (xk,yk) where xk=element row k column 0 and yk=element row k column j, after the xk are sorted (we obtain ncols-1 polygons). - See also: 1/ scatterplot 2/ listplot 3/ polygonscatterplot + See also: 1/ scatterplot 2/ listplot 3/ polygonscatterplot Ex1:polygonplot([[1,2,3],[2,0,1],[-1,2,3]]) - ''' return GiacMethods['polygonplot'](self,*args) @@ -13056,9 +12019,8 @@ cdef class GiacMethods_base: Help for polygonscatterplot: polygonscatterplot(Mtrx) Draws the points (xk,yk) and the polygons joining for j fixed and for k=0..nrows, the points (xk,yk) where xk=element row k column 0 et yk=element row k column j, after the xk are sorted (we obtain ncols-1 polygons). - See also: 1/ scatterplot 2/ polygonplot 3/ listplot + See also: 1/ scatterplot 2/ polygonplot 3/ listplot Ex1:polygonscatterplot([[1,2,3],[2,0,1],[-1,2,3]]) - ''' return GiacMethods['polygonscatterplot'](self,*args) @@ -13067,9 +12029,8 @@ cdef class GiacMethods_base: Help for polyhedron: polyhedron(SeqPnt(A,B,C...)) Draws a convex polyhedron with vertices among the arguments. - See also: 1/ cube 2/ parallelepiped + See also: 1/ cube 2/ parallelepiped Ex1:polyhedron([0,0,0],[0,5,0],[0,0,5],[1,2,6]) - ''' return GiacMethods['polyhedron'](self,*args) @@ -13078,13 +12039,12 @@ cdef class GiacMethods_base: Help for polynom: polynom(Opt) Option of the convert or convertir command and of the taylor and series commands (list=>n-poly or series=>poly). - See also: 1/ poly2symb 2/ taylor 3/ series 4/ convert + See also: 1/ poly2symb 2/ taylor 3/ series 4/ convert Ex1: convert([[10,[3,1]],[12,[2,2]]],polynom) Ex2: convert(taylor(sin(x)),polynom) Ex3: convert(series(sin(x),x=0,6),polynom) Ex4: taylor(sin(x),x=0,5,polynom) Ex5: series(sin(x),x=0,6,,polynom) - ''' return GiacMethods['polynom'](self,*args) @@ -13093,11 +12053,10 @@ cdef class GiacMethods_base: Help for polynomial_regression: polynomial_regression(Lst||Mtrx(A),[Lst],Intg(n)) Returns the coefficients (an,...a1,a0) of y=an*x^n+..a1x+a0 : it is the best polynomial which approx the points where the coordinates are the rows of A (or the 2 lists) (n is the 2nd argument). - See also: 1/ linear_regression 2/ power_regression + See also: 1/ linear_regression 2/ power_regression Ex1:polynomial_regression([[1.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]],3) Ex2:polynomial_regression([[0.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]],3) Ex3:polynomial_regression([0.0,2.0,3.0,4.0],[1.0,4.0,9.0,16.0],3) - ''' return GiacMethods['polynomial_regression'](self,*args) @@ -13106,11 +12065,10 @@ cdef class GiacMethods_base: Help for polynomial_regression_plot: polynomial_regression_plot(Lst||Mtrx(A),[Lst],Intg(n)) Returns the plot of y=an*x^n+..a1x+a0 : it is the best polynomial which approx the points where the coordinates are the rows of A (or the 2 lists) (n is the 2nd argument). - See also: 1/ linear_regression_plot 2/ power_regression_plot + See also: 1/ linear_regression_plot 2/ power_regression_plot Ex1:polynomial_regression_plot([[1.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]],3) Ex2:polynomial_regression_plot([[0.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]],3) Ex3:polynomial_regression_plot([0.0,2.0,3.0,4.0],[1.0,4.0,9.0,16.0],3) - ''' return GiacMethods['polynomial_regression_plot'](self,*args) @@ -13119,11 +12077,10 @@ cdef class GiacMethods_base: Help for position: position(NULL or LstCoord) Returns the turtle position in pixels or puts the turtle at the position given by the argument with the same direction. - See also: 1/ cap 2/ initialise + See also: 1/ cap 2/ initialise Ex1:position() Ex2:position(50,70) Ex3:position([50,70]) - ''' return GiacMethods['position'](self,*args) @@ -13132,9 +12089,8 @@ cdef class GiacMethods_base: Help for poslbdLMQ: poslbdLMQ(Poly(P)) Returns a lower bound on the values of the positive roots of P. Akritas-Strzebonski-Vigklas' Local Max Quadratic (LMQ) method is used. - See also: 1/ posubLMQ 2/ VAS_positive 3/ realroot + See also: 1/ posubLMQ 2/ VAS_positive 3/ realroot Ex1:poslbdLMQ(x^3-7*x+7) - ''' return GiacMethods['poslbdLMQ'](self,*args) @@ -13143,9 +12099,8 @@ cdef class GiacMethods_base: Help for posubLMQ: posubLMQ(Poly(P)) Returns an upper bound on the values of the positive roots of P. Akritas-Strzebonski-Vigklas' Local Max Quadratic (LMQ) method is used. - See also: 1/ poslbdLMQ 2/ VAS_positive 3/ realroot + See also: 1/ poslbdLMQ 2/ VAS_positive 3/ realroot Ex1:posubLMQ(x^3-7*x+7) - ''' return GiacMethods['posubLMQ'](self,*args) @@ -13154,9 +12109,8 @@ cdef class GiacMethods_base: Help for potential: potential(Vect(V),VectVar) Returns U such that derive(U,Vector_of_variable)=V. - See also: 1/ derive 2/ vpotential + See also: 1/ derive 2/ vpotential Ex1:potential([2*x*y+3,x^2-4*z,-4*y],[x,y,z]) - ''' return GiacMethods['potential'](self,*args) @@ -13165,9 +12119,8 @@ cdef class GiacMethods_base: Help for pow2exp: pow2exp(Expr) Converts powers to exponentials. - See also: 1/ exp2pow + See also: 1/ exp2pow Ex1:pow2exp(a^b) - ''' return GiacMethods['pow2exp'](self,*args) @@ -13176,11 +12129,10 @@ cdef class GiacMethods_base: Help for power_regression: power_regression(Lst|Mtrx(A),[Lst]) Returns the coefficients (m,b) of y=b*x^m : it is the best monomial which approx the points where the coordinates are the rows of A (or the 2 lists). - See also: 1/ polynomial_regression 2/ linear_regressiont + See also: 1/ polynomial_regression 2/ linear_regressiont Ex1:power_regression([[1.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]]) Ex2:power_regression([[1.0,2.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]]) Ex3:power_regression([1.0,2.0,3.0,4.0],[2.0,4.0,9.0,16.0]) - ''' return GiacMethods['power_regression'](self,*args) @@ -13189,11 +12141,10 @@ cdef class GiacMethods_base: Help for power_regression_plot: power_regression_plot(Lst||Mtrx(A),[Lst]) Returns the plot of y=b*x^m : it is the best monomial which approx the points where the coordinates are the rows of A (or the 2 lists). - See also: 1/ polynomial_regression_plot 2/ linear_regression_plot + See also: 1/ polynomial_regression_plot 2/ linear_regression_plot Ex1:power_regression_plot([[1.0,1.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]]) Ex2:power_regression_plot([[1.0,2.0],[2.0,4.0],[3.0,9.0],[4.0,16.0]]) Ex3:power_regression_plot([1.0,2.0,3.0,4.0],[2.0,4.0,9.0,16.0]) - ''' return GiacMethods['power_regression_plot'](self,*args) @@ -13202,10 +12153,9 @@ cdef class GiacMethods_base: Help for powermod: powermod(Intg(a),Intg(n),Intg(p),[Expr(P(x))],[Var]) Computes a^n modulo p or modulo p,P(x) (fast algorithm). - See also: 1/ pow 2/ ^ + See also: 1/ pow 2/ ^ Ex1:powermod(17,452,19) Ex2:powermod(x+1,452,19,x^4+x+1,x) - ''' return GiacMethods['powermod'](self,*args) @@ -13214,10 +12164,9 @@ cdef class GiacMethods_base: Help for powerpc: powerpc(Cercle,Pnt or Cplx) Returns the real number d^2-R^2 (d=distance between point and center, R=radius). - See also: 1/ radical_axis + See also: 1/ radical_axis Ex1:powerpc(circle(0,1+i),3+i) Ex2:powerpc(circle(0,point(1+i)),3+i) - ''' return GiacMethods['powerpc'](self,*args) @@ -13226,10 +12175,9 @@ cdef class GiacMethods_base: Help for powexpand: powexpand(Expr) Expands the expression as a function of the exponent. - See also: 1/ + See also: 1/ Ex1:powexpand(2^(x+y)) Ex2:powexpand(3^(2*x)) - ''' return GiacMethods['powexpand'](self,*args) @@ -13238,10 +12186,9 @@ cdef class GiacMethods_base: Help for powmod: powmod(Intg(a),Intg(n),Intg(p),[Expr(P(x))],[Var]) Computes a^n modulo p or modulo p,P(x) (fast algorithm). - See also: 1/ pow 2/ ^ + See also: 1/ pow 2/ ^ Ex1:powmod(17,452,19) Ex2:powmod(x+1,452,19,x^4+x+1,x) - ''' return GiacMethods['powmod'](self,*args) @@ -13250,14 +12197,13 @@ cdef class GiacMethods_base: Help for prepend: prepend(Lst||Set||Str(L),Elem(n)) Adds an element to a set or at the beginning of a list or of a string (L:=prepend(L,a) or L.prepend(a)). - See also: 1/ append 2/ concat + See also: 1/ append 2/ concat Ex1:prepend([1,2],3) Ex2:prepend(set[1,2],3) Ex3: L:=[1,2];L:=prepend(L,3) - Ex4: L:=[1,2];L.prepend(L,3) + Ex4: L:=[1,2];L.prepend(L,3) Ex5: S:=set[1,2];S:=prepend(L,3) Ex6: S:=set[1,2];S.prepend(L,3) - ''' return GiacMethods['prepend'](self,*args) @@ -13266,12 +12212,11 @@ cdef class GiacMethods_base: Help for preval: preval(Expr(F(Var)),Real(a),Real(b),[Var]) Returns F(b)-F(a). - See also: 1/ subst 2/ int + See also: 1/ subst 2/ int Ex1:preval(x^2-2,2,3) Ex2:preval(y^2-2,2,3,y) Ex3:preval(int(x),0,1) Ex4:preval(int(y,y),0,1,y) - ''' return GiacMethods['preval'](self,*args) @@ -13280,10 +12225,9 @@ cdef class GiacMethods_base: Help for prevperm: prevperm(Intg(n)) Returns the previous permutation with the lexicographic order. - See also: 1/ nextperm 2/ is_permu + See also: 1/ nextperm 2/ is_permu Ex1:prevperm([0,1,3,2]) Ex2:prevperm([0,1,2,3]) - ''' return GiacMethods['prevperm'](self,*args) @@ -13292,10 +12236,9 @@ cdef class GiacMethods_base: Help for prevprime: prevprime(Intg(a)) Previous prime or pseudo-prime before a given integer a. - See also: 1/ nextprime 2/ is_prime 3/ ithprime + See also: 1/ nextprime 2/ is_prime 3/ ithprime Ex1:prevprime(9856989898999) Ex2:prevprime(97160249868928888261606009) - ''' return GiacMethods['prevprime'](self,*args) @@ -13304,10 +12247,9 @@ cdef class GiacMethods_base: Help for primpart: primpart(Poly(P),[Var]) Returns the polynomial P divided by the gcd of its coefficients. - See also: 1/ content + See also: 1/ content Ex1:primpart(2x^2+10x+6) Ex2:primpart(2t^2+10t+6,t) - ''' return GiacMethods['primpart'](self,*args) @@ -13316,10 +12258,9 @@ cdef class GiacMethods_base: Help for printf: printf(Expr) 2d printing. - See also: 1/ print + See also: 1/ print Ex1:printf(sqrt(2)) Ex2:printf("%gen+%gen=%gen",a,b,a+b) - ''' return GiacMethods['printf'](self,*args) @@ -13328,9 +12269,8 @@ cdef class GiacMethods_base: Help for prism: prism(LstPnt([A,B,C,D]),Pnt(A1)) Draws a prism with plane base ABCD...and with edges parallel to AA1 (the faces are parallelograms). - See also: 1/ cube 2/ polyhedron + See also: 1/ cube 2/ polyhedron Ex1:prism([[0,0,0],[5,0,0],[0,5,0],[-5,5,0]],[0,0,5]) - ''' return GiacMethods['prism'](self,*args) @@ -13339,9 +12279,8 @@ cdef class GiacMethods_base: Help for prism_graph: prism_graph(Intg(n)) Returns the generalized Petersen graph GP(n,1). - See also: 1/ antiprism_graph 2/ web_graph + See also: 1/ antiprism_graph 2/ web_graph Ex1:prism_graph(5) - ''' return GiacMethods['prism_graph'](self,*args) @@ -13350,7 +12289,7 @@ cdef class GiacMethods_base: Help for product: product(Expr||Lst,[Var||Lst],[Intg(a)],[Intg(b)],[Intg(p)]) Multiplies the values of the expression when the variable go from a to b with a step p (product(expression,var,begin,end,step) by default p=1) or product of the elements of a list or product element by element of 2 lists or matrices. - See also: 1/ sum + See also: 1/ sum Ex1:product(n,n,1,10,2) Ex2:product(1/n,n,1,10) Ex3:product(1/n,n,11,1) @@ -13358,7 +12297,6 @@ cdef class GiacMethods_base: Ex5:product([2,3,4,5]) Ex6:product([2,3,4],[5,6,7]) Ex7:product([[2,3,4],[5,6,7]],[[2,3,4],[5,6,7]]) - ''' return GiacMethods['product'](self,*args) @@ -13367,11 +12305,10 @@ cdef class GiacMethods_base: Help for projection: projection(Curve,Pnt) projection(C,A) is the orthogonal projection of A on the curve C. - See also: 1/ perpendicular + See also: 1/ perpendicular Ex1: H:=projection(line(i,1-i),1+i) Ex2: K:=projection(circle(0,1),1+i) Ex3: J:=projection(circle(0,1),point(1+2*i)) - ''' return GiacMethods['projection'](self,*args) @@ -13380,12 +12317,11 @@ cdef class GiacMethods_base: Help for proot: proot(Vect||Poly,[Intg(n)]) Returns all computed roots of a polynomial given by its coefficients (may not work if roots are not simple). - See also: 1/ pcoeff 2/ peval 3/ realroot 4/ complexroot 5/ rationalroot 6/ crationalroot + See also: 1/ pcoeff 2/ peval 3/ realroot 4/ complexroot 5/ rationalroot 6/ crationalroot Ex1:proot([1,0,-2]) Ex2:proot(x^2-2) Ex3:proot([1,2,-25,-26,120]) Ex4:proot(x^4+5x-3,30) - ''' return GiacMethods['proot'](self,*args) @@ -13394,10 +12330,9 @@ cdef class GiacMethods_base: Help for propFrac: propFrac(Frac or RatFrac) Simplifies and writes the fraction (or rational fraction) A/B as Q+R/B with R=0 or, the (-n)th previous question if n<0 (by default n=-1 for the previous question). - See also: 1/ ans + See also: 1/ ans Ex1:quest() Ex2:quest(2) Ex3:quest(-2) - ''' return GiacMethods['quest'](self,*args) @@ -13604,11 +12523,10 @@ cdef class GiacMethods_base: Help for quo: quo((Vect or Poly),(Vect or Poly),[Var]) Euclidean quotient of 2 polynomials. - See also: 1/ rem 2/ quorem 3/ Quo 4/ iquo + See also: 1/ rem 2/ quorem 3/ Quo 4/ iquo Ex1:quo([1,2,3,4],[-1,2]) Ex2:quo(x^3+2x^2+3x+4,-x+2) Ex3:quo(t^3+2t^2+3t+4,-t+2,t) - ''' return GiacMethods['quo'](self,*args) @@ -13617,12 +12535,11 @@ cdef class GiacMethods_base: Help for quorem: quorem((Vect or Poly),(Vect or Poly),[Var]) Euclidean quotient and remainder of 2 polynomials. - See also: 1/ rem 2/ quo 3/ iquorem + See also: 1/ rem 2/ quo 3/ iquorem Ex1:quorem([1,2,3,4],[-1,2]) Ex2:quorem(x^3+2x^2+3x+4,-x+2) Ex3:quorem(t^3+2t^2+3t+4,-t+2,t) Ex4:quorem(t^4-1,(t+1)^2,t) - ''' return GiacMethods['quorem'](self,*args) @@ -13631,11 +12548,10 @@ cdef class GiacMethods_base: Help for quote: quote(Expr) Returns its argument unevaluated (and also a:=quote(a) purges a). - See also: 1/ + See also: 1/ Ex1:quote(1+2) Ex2:quote(1/x+1/(x-1)) Ex3:quote((x+1)*(x-1)) - ''' return GiacMethods['quote'](self,*args) @@ -13644,12 +12560,11 @@ cdef class GiacMethods_base: Help for r2e: r2e(Lst,Var) Gives the polynomial (or its value) : the first argument is the vector of coefficients and the second argument is the variable (by default x). - See also: 1/ e2r 2/ symb2poly + See also: 1/ e2r 2/ symb2poly Ex1:r2e([1,2,3]) Ex2:r2e([1,2,3],x) Ex3:r2e([1,2,3],-1) Ex4:r2e([1,2,-1],y) - ''' return GiacMethods['r2e'](self,*args) @@ -13658,10 +12573,9 @@ cdef class GiacMethods_base: Help for radical_axis: radical_axis(Crcle,Crcle) Returns the line of points with same powerpc with respect to the 2 circles. - See also: 1/ powerpc + See also: 1/ powerpc Ex1:radical_axis(circle(0,1+i),circle(1,1+i)) Ex2:radical_axis(circle(0,point(1+i)),circle(1,point(1+i))) - ''' return GiacMethods['radical_axis'](self,*args) @@ -13670,9 +12584,8 @@ cdef class GiacMethods_base: Help for radius: radius(Crcle) radius(C) gives the radius of the circle C. - See also: 1/ center 2/ circle + See also: 1/ center 2/ circle Ex1:radius(incircle(-1,1-i,i)) - ''' return GiacMethods['radius'](self,*args) @@ -13681,9 +12594,8 @@ cdef class GiacMethods_base: Help for ramene: ramene(Str(fich_name)) Reads variables and their values from the file fich_name. - See also: 1/ write 2/ readrgb 3/ readwav 4/ csv2gen + See also: 1/ write 2/ readrgb 3/ readwav 4/ csv2gen Ex1:ramene("toto") - ''' return GiacMethods['ramene'](self,*args) @@ -13692,7 +12604,7 @@ cdef class GiacMethods_base: Help for rand: rand(Intg(n) or Interval(p..n) or NULL,[Intg(b1) or Lst(L)],[Intg(b2)]) rand(n)=a random integer (resp rand(p,n)=a real or rand(p..n)=a real function) with uniform distribution in 0..n-1 (resp in [p;n])(rand()=rand(0,1)=a real in [0,1[) or rand(n,b1,b2)=n integers between b1 and b2 or rand(n,L)=list of n elements of L. - See also: 1/ srand 2/ randpoly 3/ ranm 4/ randvector 5/ hasard + See also: 1/ srand 2/ randpoly 3/ ranm 4/ randvector 5/ hasard Ex1:rand(4) Ex2:rand() Ex3:rand(0,2) @@ -13704,7 +12616,6 @@ cdef class GiacMethods_base: Ex9: L:=["r","r","r","b","n"];L3:=L.rand(3) Ex10: L:=["r","r","r","b","n"];a:=rand(L) Ex11: L:=["r","r","r","b","n"];a:=L.rand() - ''' return GiacMethods['rand'](self,*args) @@ -13713,7 +12624,7 @@ cdef class GiacMethods_base: Help for randMat: randMat(Intg(n), [Intg(m)],[Interval or quote(DistribLaw)]) Returns a list of size n or an n*m matrix that contains random integers in the range -99 through 99 with uniform distribution or contains random numbers according to the law put between quotes. - See also: 1/ idn 2/ randPoly 3/ rand 4/ randvector + See also: 1/ idn 2/ randPoly 3/ rand 4/ randvector Ex1:randMat(3) Ex2:randMat(3,2) Ex3:randMat(3,2,6) @@ -13727,7 +12638,6 @@ cdef class GiacMethods_base: Ex11:randMat(3,2,1..2) Ex12:randMat(3,5,multinomial,[1/2,1/3,1/6],["R","V","B"]) Ex13: GF(2,8,g);ranm(3,3,g) - ''' return GiacMethods['randMat'](self,*args) @@ -13736,10 +12646,9 @@ cdef class GiacMethods_base: Help for randNorm: randNorm(Real(mu),Real(sigma)) Returns a random real with normal distribution N(mu,sigma). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randpoisson 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randpoisson 8/ randgeometric 9/ randmultinomial Ex1:randNorm(0,1) Ex2:randNorm(2,1) - ''' return GiacMethods['randNorm'](self,*args) @@ -13748,14 +12657,13 @@ cdef class GiacMethods_base: Help for randPoly: randPoly([Var(Var)],Intg(n),[law]) Returns a polynomial with variable var (or x), of degree n and where the coefficients are random integers in the range -99 through 99 with uniform distribution or according to a law. - See also: 1/ ranm 2/ randvector + See also: 1/ ranm 2/ randvector Ex1:randPoly(5) Ex2:randPoly(t,8) Ex3:randPoly(t,8,-1..1) Ex4:randPoly([x,y],[10,3]) Ex5:randPoly([x,y],[10,3],1 mod 7) Ex6: GF(2,8,g);randpoly(t,8,g);randpoly([x,y],[2,3],g) - ''' return GiacMethods['randPoly'](self,*args) @@ -13764,10 +12672,9 @@ cdef class GiacMethods_base: Help for randbetad: randbetad(Real(a),Real(b)) Returns a random real according to the Beta distribution with parameters a>0 and b>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:randbetad(1,2) Ex2:randbetad(1.5,4) - ''' return GiacMethods['randbetad'](self,*args) @@ -13776,10 +12683,9 @@ cdef class GiacMethods_base: Help for randbinomial: randbinomial(Intg(n),Real(p)) Returns a random integer with binomial distribution B(n,p) i.e. the number of successes in n independant tests where for each test, the success of probability is p. - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randnorm 7/ randpoisson 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randnorm 7/ randpoisson 8/ randgeometric 9/ randmultinomial Ex1:randbinomial(10,0.4) Ex2:randbinomial(100,0.8) - ''' return GiacMethods['randbinomial'](self,*args) @@ -13788,10 +12694,9 @@ cdef class GiacMethods_base: Help for randchisquare: randchisquare(Intg(n)) Returns a random integer with chi^2 distribution, χ^2(n). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial Ex1:randchisquare(5) Ex2:randchisquare(2) - ''' return GiacMethods['randchisquare'](self,*args) @@ -13800,10 +12705,9 @@ cdef class GiacMethods_base: Help for randexp: randexp(Real(a)) Returns a random real according to the exponential distribution with parameter a>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:randexp(1) Ex2:randexp(2) - ''' return GiacMethods['randexp'](self,*args) @@ -13812,10 +12716,9 @@ cdef class GiacMethods_base: Help for randfisher: randfisher(Intg(n),Intg(m)) Returns a random integer with Fisher-Snedecor distribution F(n,m). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial Ex1:randfisher(5,2) Ex2:randfisher(2,4) - ''' return GiacMethods['randfisher'](self,*args) @@ -13824,10 +12727,9 @@ cdef class GiacMethods_base: Help for randgammad: randgammad(Real(a),Real(b)) Returns a random real according to the Gamma distribution with parameters a>0 and b>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:randgammad(1,2) Ex2:randgammad(1.5,4) - ''' return GiacMethods['randgammad'](self,*args) @@ -13836,9 +12738,8 @@ cdef class GiacMethods_base: Help for randgeometric: randgeometric(Real(p)) Returns a random integer following the geometric distribution with parameter p. - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randnorm 7/ randpoisson 8/ randbinomial 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randnorm 7/ randpoisson 8/ randbinomial 9/ randmultinomial Ex1:randgeometric(0.4) - ''' return GiacMethods['randgeometric'](self,*args) @@ -13847,10 +12748,9 @@ cdef class GiacMethods_base: Help for randint: randint(Intg(n1),Intg(n2)) randint(n1,n2)=an integer in [n1, n2] or [n2,n1]. - See also: 1/ rand + See also: 1/ rand Ex1:randint(1,10) Ex2:randint(-1,-10) - ''' return GiacMethods['randint'](self,*args) @@ -13859,10 +12759,9 @@ cdef class GiacMethods_base: Help for randmarkov: randmarkov(Mtrx(M) || Vctr(v),Intg(i0),[Intg(n)]) Returns a random sequence of n states (Markov chain) starting from i0, with probability transition matrix M, or returns a stochastic matrix with p recurrent loops v=[n1,..,np] and i0 transient states. - See also: 1/ markov 2/ plotproba + See also: 1/ markov 2/ plotproba Ex1:randmarkov([[0,0,1/2,0,1/2],[0,0,1,0,0],[1/4,1/4,0,1/4,1/4],[0,0,1/2,0,1/2],[0,0,0,0,1]],2,20) Ex2:randmarkov([1,2,1,3],4) - ''' return GiacMethods['randmarkov'](self,*args) @@ -13871,7 +12770,7 @@ cdef class GiacMethods_base: Help for randmatrix: randmatrix(Intg(n), [Intg(m)],[Interval or quote(DistribLaw)]) Returns a list of size n or an n*m matrix that contains random integers in the range -99 through 99 with uniform distribution or contains random numbers according to the law put between quotes. - See also: 1/ idn 2/ randPoly 3/ rand 4/ randvector + See also: 1/ idn 2/ randPoly 3/ rand 4/ randvector Ex1:randmatrix(3) Ex2:randmatrix(3,2) Ex3:randmatrix(3,2,6) @@ -13885,7 +12784,6 @@ cdef class GiacMethods_base: Ex11:randmatrix(3,2,1..2) Ex12:randmatrix(3,5,multinomial,[1/2,1/3,1/6],["R","V","B"]) Ex13: GF(2,8,g);ranm(3,3,g) - ''' return GiacMethods['randmatrix'](self,*args) @@ -13894,10 +12792,9 @@ cdef class GiacMethods_base: Help for randmultinomial: randmultinomial(List(P),[List(K)]) Returns a random index or list element according to a multinomial distribution probability list P. - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randnorm 7/ randpoisson 8/ randgeometric 9/ randbinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randnorm 7/ randpoisson 8/ randgeometric 9/ randbinomial Ex1:randmultinomial([1/2,1/3,1/6]) Ex2:randmultinomial([1/2,1/3,1/6],["R","V","B"]) - ''' return GiacMethods['randmultinomial'](self,*args) @@ -13906,10 +12803,9 @@ cdef class GiacMethods_base: Help for randnorm: randnorm(Real(mu),Real(sigma)) Returns a random real with normal distribution N(mu,sigma). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randpoisson 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randpoisson 8/ randgeometric 9/ randmultinomial Ex1:randnorm(0,1) Ex2:randnorm(2,1) - ''' return GiacMethods['randnorm'](self,*args) @@ -13918,7 +12814,7 @@ cdef class GiacMethods_base: Help for random: random(Intg(n) or Interval(p..n) or NULL,[Intg(b1) or Lst(L)],[Intg(b2)]) rand(n)=a random integer (resp rand(p,n)=a real or rand(p..n)=a real function) with uniform distribution in 0..n-1 (resp in [p;n])(rand()=rand(0,1)=a real in [0,1[) or rand(n,b1,b2)=n integers between b1 and b2 or rand(n,L)=list of n elements of L. - See also: 1/ srand 2/ randpoly 3/ ranm 4/ randvector 5/ hasard + See also: 1/ srand 2/ randpoly 3/ ranm 4/ randvector 5/ hasard Ex1:random(4) Ex2:random() Ex3:random(0,2) @@ -13930,7 +12826,6 @@ cdef class GiacMethods_base: Ex9: L:=["r","r","r","b","n"];L3:=L.rand(3) Ex10: L:=["r","r","r","b","n"];a:=rand(L) Ex11: L:=["r","r","r","b","n"];a:=L.rand() - ''' return GiacMethods['random'](self,*args) @@ -13939,10 +12834,9 @@ cdef class GiacMethods_base: Help for random_bipartite_graph: random_bipartite_graph(Intg(n)||Lst(a,b),Real(p)||Intg(m)) Returns a random undirected unweighted bipartite graph with n vertices where each possible edge is present with probability p or where m edges are created at random. When the first argument is list [a,b] of integers, two groups of vertices with sizes a and b are created. - See also: 1/ random_digraph 2/ random_graph 3/ random_planar_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree + See also: 1/ random_digraph 2/ random_graph 3/ random_planar_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree Ex1:random_bipartite_graph(10,0.5) Ex2:random_bipartite_graph([2,3],1.0) - ''' return GiacMethods['random_bipartite_graph'](self,*args) @@ -13951,10 +12845,9 @@ cdef class GiacMethods_base: Help for random_digraph: random_digraph(Intg(n)||Lst(V),Real(p)||Intg(m)) Returns a random directed unweighted graph with n vertices (list V of labels may me specified) where two vertices are connected with probability p or where m edges are created at random. - See also: 1/ random_bipartite_graph 2/ random_graph 3/ random_planar_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree + See also: 1/ random_bipartite_graph 2/ random_graph 3/ random_planar_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree Ex1:random_digraph(8,0.5) Ex2:random_digraph(8,10) - ''' return GiacMethods['random_digraph'](self,*args) @@ -13963,10 +12856,9 @@ cdef class GiacMethods_base: Help for random_graph: random_graph(Intg(n)||Lst(V),Real(p)||Intg(m)) Returns a random undirected unweighted graph with n vertices (list V of labels may be specified) where two vertices are connected with probability p or where m edges are created at random. - See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_planar_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree + See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_planar_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree Ex1:random_graph(8,0.5) Ex2:random_graph(8,10) - ''' return GiacMethods['random_graph'](self,*args) @@ -13975,11 +12867,10 @@ cdef class GiacMethods_base: Help for random_network: random_network(Intg(a),Intg(b),[Real(p)],[opts]) Returns a random network with b grid frames of size a*a in which every edge appears with the probability p (by default 0.5). - See also: 1/ is_network 2/ maxflow + See also: 1/ is_network 2/ maxflow Ex1:random_network(3,3) Ex2:random_network(3,3,acyclic) Ex3:random_network(3,4,0.75) - ''' return GiacMethods['random_network'](self,*args) @@ -13988,8 +12879,7 @@ cdef class GiacMethods_base: Help for random_planar_graph: random_planar_graph(Intg(n)||Lst(V),Real(p),[Intg(c)]) Returns a random planar graph with n vertices, which can also be specified as a list V of their labels, obtained by trying to remove each edge of a random triangulated graph with probability 0<=p<1 [c is connectivity level : 0 - any, 1 - connected, 2 - biconnected, 3 - triconnected (by default, c=1)]. - See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree - + See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_regular_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree ''' return GiacMethods['random_planar_graph'](self,*args) @@ -13998,9 +12888,8 @@ cdef class GiacMethods_base: Help for random_regular_graph: random_regular_graph(Intg(n)||Lst(V),Intg(d),[connected]) Returns a random d-regular graph with n vertices, which may be specified as list V of their labels. - See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree + See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree Ex1:random_regular_graph(100,80,connected) - ''' return GiacMethods['random_regular_graph'](self,*args) @@ -14009,9 +12898,8 @@ cdef class GiacMethods_base: Help for random_sequence_graph: random_sequence_graph(Lst(L)) Returns a random undirected graph with degree sequence L. - See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree + See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_sequence_graph 6/ random_tournament 7/ random_tree Ex1:random_sequence_graph([1,3,3,2,1,2,2,2,3,3]) - ''' return GiacMethods['random_sequence_graph'](self,*args) @@ -14020,9 +12908,8 @@ cdef class GiacMethods_base: Help for random_tournament: random_tournament(Intg(n)||Lst(V)) Returns a random tournament graph with n vertices, which may be specified as list V of their labels. - See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_regular_graph 6/ random_sequence_graph 7/ random_tree + See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_regular_graph 6/ random_sequence_graph 7/ random_tree Ex1:random_tournament(5) - ''' return GiacMethods['random_tournament'](self,*args) @@ -14031,8 +12918,7 @@ cdef class GiacMethods_base: Help for random_tree: random_tree(Intg(n)||Lst(V),[Intg(d)||root[=Vrtx(v)]]) Returns a random tree graph with n vertices, which may be specified as list V of their labels [with the upper bound d (positive integer) for the degree of graph or 'root' for rooted trees]. - See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_regular_graph 6/ random_sequence_graph 7/ random_tournament - + See also: 1/ random_bipartite_graph 2/ random_digraph 3/ random_graph 4/ random_planar_graph 5/ random_regular_graph 6/ random_sequence_graph 7/ random_tournament ''' return GiacMethods['random_tree'](self,*args) @@ -14041,7 +12927,7 @@ cdef class GiacMethods_base: Help for random_variable: random_variable(Lst(W)||Mtrx(M)||Fnc(f),[params]) Returns a random variable from a probability density function f or from list of weights (discrete variable). - See also: 1/ randvector 2/ randmatrix 3/ rand + See also: 1/ randvector 2/ randmatrix 3/ rand Ex1:random_variable(fisher,2,3) Ex2:random_variable([["apple",1/3],["orange",1/4],["pear",1/5],["plum",13/60]]) Ex3:random_variable(k->1-(k/10)^2,range=-10..10) @@ -14052,7 +12938,6 @@ cdef class GiacMethods_base: Ex8:random_variable(weibull,mean=12.5,variance=1) Ex9:random_variable(uniform,mean=10,stddev=2) Ex10:random_variable(uniform,e..pi) - ''' return GiacMethods['random_variable'](self,*args) @@ -14061,13 +12946,12 @@ cdef class GiacMethods_base: Help for randperm: randperm(Intg(n)||Lst(L)) Returns a random permutation of [0,1,2,..,n-1] or of the list L. - See also: 1/ permu2cycles 2/ is_permu 3/ permu2mat + See also: 1/ permu2cycles 2/ is_permu 3/ permu2mat Ex1:randperm(4) Ex2:randperm(7) Ex3:randperm([1,3,5,7,9]) Ex4: L:=[1,3,5,7,9];L:=randperm(L) Ex5: L:=[1,3,5,7,9];L.randperm() - ''' return GiacMethods['randperm'](self,*args) @@ -14076,10 +12960,9 @@ cdef class GiacMethods_base: Help for randpoisson: randpoisson(Real(λ)) Returns a random integer with poisson distribution P(λ). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial Ex1:randpoisson(5.4) Ex2:randpoisson(2.8) - ''' return GiacMethods['randpoisson'](self,*args) @@ -14088,14 +12971,13 @@ cdef class GiacMethods_base: Help for randpoly: randpoly([Var(Var)],Intg(n),[law]) Returns a polynomial with variable var (or x), of degree n and where the coefficients are random integers in the range -99 through 99 with uniform distribution or according to a law. - See also: 1/ ranm 2/ randvector + See also: 1/ ranm 2/ randvector Ex1:randpoly(5) Ex2:randpoly(t,8) Ex3:randpoly(t,8,-1..1) Ex4:randpoly([x,y],[10,3]) Ex5:randpoly([x,y],[10,3],1 mod 7) Ex6: GF(2,8,g);randpoly(t,8,g);randpoly([x,y],[2,3],g) - ''' return GiacMethods['randpoly'](self,*args) @@ -14104,10 +12986,9 @@ cdef class GiacMethods_base: Help for randseed: randseed() srand returns an integer and initializes the sequence of random numbers. - See also: 1/ RandSeed + See also: 1/ RandSeed Ex1:randseed(12) Ex2: srand - ''' return GiacMethods['randseed'](self,*args) @@ -14116,10 +12997,9 @@ cdef class GiacMethods_base: Help for randstudent: randstudent(Intg(n)) Returns a random integer with Student distribution S(n). - See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial + See also: 1/ rand 2/ randpoly 3/ ranm 4/ randvector 5/ randexp 6/ randbinomial 7/ randnorm 8/ randgeometric 9/ randmultinomial Ex1:randstudent(5) Ex2:randstudent(2) - ''' return GiacMethods['randstudent'](self,*args) @@ -14128,7 +13008,7 @@ cdef class GiacMethods_base: Help for randvar: randvar(Lst(W)||Mtrx(M)||Fnc(f),[params]) Returns a random variable from a probability density function f or from list of weights (discrete variable). - See also: 1/ randvector 2/ randmatrix 3/ rand + See also: 1/ randvector 2/ randmatrix 3/ rand Ex1:randvar(fisher,2,3) Ex2:randvar([["apple",1/3],["orange",1/4],["pear",1/5],["plum",13/60]]) Ex3:randvar(k->1-(k/10)^2,range=-10..10) @@ -14139,7 +13019,6 @@ cdef class GiacMethods_base: Ex8:randvar(weibull,mean=12.5,variance=1) Ex9:randvar(uniform,mean=10,stddev=2) Ex10:randvar(uniform,e..pi) - ''' return GiacMethods['randvar'](self,*args) @@ -14148,7 +13027,7 @@ cdef class GiacMethods_base: Help for randvector: randvector(Intg(n), [Intg(m)],[Interval or quote(DistribLaw)]) Returns a list of size n that contains random integers in the range -99 through 99 (or in 0..m-1) with uniform distribution or contains random numbers according to the law put between quotes. - See also: 1/ idn 2/ randPoly 3/ rand 4/ ranm + See also: 1/ idn 2/ randPoly 3/ rand 4/ ranm Ex1:randvector(3) Ex2:randvector(3,6) Ex3:randvector(3,normald,0,1) @@ -14159,7 +13038,6 @@ cdef class GiacMethods_base: Ex8:randvector(3,'rand(3)') Ex9:randvector(3,1..2) Ex10: GF(2,8,g);randvector(3,g) - ''' return GiacMethods['randvector'](self,*args) @@ -14168,10 +13046,9 @@ cdef class GiacMethods_base: Help for randweibulld: randweibulld(Real(a),Real(b)) Returns a random real according to the Weibull distribution with parameters a>0 and b>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:randweibulld(1,2) Ex2:randweibulld(1.5,4) - ''' return GiacMethods['randweibulld'](self,*args) @@ -14180,10 +13057,9 @@ cdef class GiacMethods_base: Help for rank: rank(Mtrx) Returns the rank of the matrix. - See also: 1/ det 2/ image + See also: 1/ det 2/ image Ex1:rank([[1,1,2],[2,1,3],[3,1,4]]) Ex2:rank([[1,1,2],[2,1,3],[3,1,5]]) - ''' return GiacMethods['rank'](self,*args) @@ -14192,7 +13068,7 @@ cdef class GiacMethods_base: Help for ranm: ranm(Intg(n), [Intg(m)],[Interval or quote(DistribLaw)]) Returns a list of size n or an n*m matrix that contains random integers in the range -99 through 99 with uniform distribution or contains random numbers according to the law put between quotes. - See also: 1/ idn 2/ randPoly 3/ rand 4/ randvector + See also: 1/ idn 2/ randPoly 3/ rand 4/ randvector Ex1:ranm(3) Ex2:ranm(3,2) Ex3:ranm(3,2,6) @@ -14206,7 +13082,6 @@ cdef class GiacMethods_base: Ex11:ranm(3,2,1..2) Ex12:ranm(3,5,multinomial,[1/2,1/3,1/6],["R","V","B"]) Ex13: GF(2,8,g);ranm(3,3,g) - ''' return GiacMethods['ranm'](self,*args) @@ -14215,7 +13090,7 @@ cdef class GiacMethods_base: Help for ranv: ranv(Intg(n), [Intg(m)],[Interval or quote(DistribLaw)]) Returns a list of size n that contains random integers in the range -99 through 99 (or in 0..m-1) with uniform distribution or contains random numbers according to the law put between quotes. - See also: 1/ idn 2/ randPoly 3/ rand 4/ ranm + See also: 1/ idn 2/ randPoly 3/ rand 4/ ranm Ex1:ranv(3) Ex2:ranv(3,6) Ex3:ranv(3,normald,0,1) @@ -14226,7 +13101,6 @@ cdef class GiacMethods_base: Ex8:ranv(3,'rand(3)') Ex9:ranv(3,1..2) Ex10: GF(2,8,g);randvector(3,g) - ''' return GiacMethods['ranv'](self,*args) @@ -14235,9 +13109,8 @@ cdef class GiacMethods_base: Help for rassembler_trigo: rassembler_trigo(Expr) Collects trigonometric expressions. - See also: 1/ texpand 2/ tlin + See also: 1/ texpand 2/ tlin Ex1:rassembler_trigo(sin(x)+cos(x)) - ''' return GiacMethods['rassembler_trigo'](self,*args) @@ -14246,11 +13119,10 @@ cdef class GiacMethods_base: Help for rat_jordan: rat_jordan(Mtrx) Returns the list made by the transition matrix and the rational Jordan form of a matrix. - See also: 1/ egv 2/ egvl 3/ jordan 4/ companion + See also: 1/ egv 2/ egvl 3/ jordan 4/ companion Ex1:rat_jordan([[0,2],[1,0]]) Ex2:rat_jordan([[-2,-2,1],[-2,1,-2],[1,-2,-2]]) Ex3:rat_jordan([[1,1,-1,2,-1],[2,0,1,-4,-1],[0,1,1,1,1],[0,1,2,0,1],[0,0,-3,3,-1]]) - ''' return GiacMethods['rat_jordan'](self,*args) @@ -14259,11 +13131,10 @@ cdef class GiacMethods_base: Help for rational: rational(Opt) DOM_RAT or rational is the type of a rational, as returned by the type command. It is also an option of the assume command. - See also: 1/ type 2/ assume 3/ DOM_INT 4/ DOM_FLOAT + See also: 1/ type 2/ assume 3/ DOM_INT 4/ DOM_FLOAT Ex1: assume(a,rational) Ex2: assume(a,DOM_RAT) Ex3: a:=1/2;type(a) - ''' return GiacMethods['rational'](self,*args) @@ -14272,9 +13143,8 @@ cdef class GiacMethods_base: Help for rationalroot: rationalroot(Poly(P)) Returns the list of rational roots of P without indicating the multiplicity. - See also: 1/ proot 2/ froot 3/ complexroot 4/ realroot 5/ crationalroot + See also: 1/ proot 2/ froot 3/ complexroot 4/ realroot 5/ crationalroot Ex1:rationalroot(2*x^3-9*x^2+13*x-6) - ''' return GiacMethods['rationalroot'](self,*args) @@ -14283,11 +13153,10 @@ cdef class GiacMethods_base: Help for ratnormal: ratnormal(Expr) Rewrites as an irreducible rational fraction. - See also: 1/ normal 2/ simplify 3/ factor 4/ expand + See also: 1/ normal 2/ simplify 3/ factor 4/ expand Ex1:ratnormal((x^2-1)/(x^3-1)) Ex2:ratnormal(c/d+b/d+a/d) Ex3:ratnormal((x^2-1)/(x^3-1)+(x-1)/(x^3-1)+1) - ''' return GiacMethods['ratnormal'](self,*args) @@ -14296,10 +13165,9 @@ cdef class GiacMethods_base: Help for rdiv: rdiv(Expr(a),Expr(b)) Division of a by b (prefixed version of /). - See also: 1/ / + See also: 1/ / Ex1:rdiv(3,5) Ex2:rdiv(3.2,5.4) - ''' return GiacMethods['rdiv'](self,*args) @@ -14308,11 +13176,10 @@ cdef class GiacMethods_base: Help for re: re(Cplx or LstCplx) Returns the real part of a complex number. - See also: 1/ im 2/ conj + See also: 1/ im 2/ conj Ex1:re(1+2*i) Ex2:re((1+2*i)^2) Ex3:re([1+2*i,(1+2*i)^2]) - ''' return GiacMethods['re'](self,*args) @@ -14321,9 +13188,8 @@ cdef class GiacMethods_base: Help for read: read(Str(fich_name)) Reads variables and their values from the file fich_name. - See also: 1/ write 2/ readrgb 3/ readwav 4/ csv2gen + See also: 1/ write 2/ readrgb 3/ readwav 4/ csv2gen Ex1:read("toto") - ''' return GiacMethods['read'](self,*args) @@ -14332,10 +13198,9 @@ cdef class GiacMethods_base: Help for readrgb: readrgb(Str(s),[Intg(w)],[Intg(h)]) Reads a picture file, using it's natural dimensions, or using specified dimensions. - See also: 1/ writergb 2/ readwav + See also: 1/ writergb 2/ readwav Ex1:readrgb("image.png") Ex2:readrgb("image.png",50,50) - ''' return GiacMethods['readrgb'](self,*args) @@ -14344,9 +13209,8 @@ cdef class GiacMethods_base: Help for readwav: readwav(Str(s)) Reads a WAV sound file. - See also: 1/ writewav 2/ readrgb + See also: 1/ writewav 2/ readrgb Ex1:readwav("pop.wav") - ''' return GiacMethods['readwav'](self,*args) @@ -14355,11 +13219,10 @@ cdef class GiacMethods_base: Help for real: real(Cplx or LstCplx) Returns the real part of a complex number. - See also: 1/ im 2/ conj + See also: 1/ im 2/ conj Ex1:real(1+2*i) Ex2:real((1+2*i)^2) Ex3:real([1+2*i,(1+2*i)^2]) - ''' return GiacMethods['real'](self,*args) @@ -14368,14 +13231,13 @@ cdef class GiacMethods_base: Help for realroot: realroot([sturm],Poly(P),[Real(l)],[Cplx(a)],[Cplx(b)]) Returns the list of intervals of length <=l containing the real roots of P inside a..b with their multiplicity. By default the Vincent-Akritas-Strzebonski (VAS) method is used. realroot(sturm,P) uses Sturm's method. - See also: 1/ proot 2/ froot 3/ complexroot 4/ rationalroot 5/ crationalroot 6/ sturmab 7/ VAS + See also: 1/ proot 2/ froot 3/ complexroot 4/ rationalroot 5/ crationalroot 6/ sturmab 7/ VAS Ex1:realroot(x^3+7,0.1) Ex2:realroot(x^3-7*x+7) Ex3:realroot(sturm,x^3-7*x+7) Ex4:realroot(x^5-2*x^4+x^3+1) Ex5:realroot(x^5-2*x^4+x^3+1,0.1) Ex6:realroot(x^3+x+8,1e-5,-4,4) - ''' return GiacMethods['realroot'](self,*args) @@ -14384,10 +13246,9 @@ cdef class GiacMethods_base: Help for reciprocation: reciprocation(Crcle,Lst(Pnt,Line)) Returns the list where the points (resp lines) are replaced with their polars (resp poles) with respect to the circle C. - See also: 1/ pole 2/ polar + See also: 1/ pole 2/ polar Ex1:reciprocation(circle(0,1),[point((1+i)/2), line(1,-1+i)]) Ex2:reciprocation(circle(0,1),[line(1+i,2),point(1+i*2)]) - ''' return GiacMethods['reciprocation'](self,*args) @@ -14396,9 +13257,8 @@ cdef class GiacMethods_base: Help for rect: rect(Expr(x)) Returns the value of the rectangle function at x. - See also: 1/ boxcar 2/ tri 3/ Heaviside + See also: 1/ boxcar 2/ tri 3/ Heaviside Ex1:rect(x/2) - ''' return GiacMethods['rect'](self,*args) @@ -14407,12 +13267,11 @@ cdef class GiacMethods_base: Help for rectangle: rectangle(Pnt(A)||Cplx,Pnt(B)||Cplx,Real(k)||Pnt(P)||Lst(P,k),[Var(D)],[Var(C)]) Returns and draws the rectangle ABCD, AD=k*AB; if k>0 ABCD is direct else indirect (in the plane ABP AD=AP or AD=k*AB). - See also: 1/ quadrilateral 2/ square + See also: 1/ quadrilateral 2/ square Ex1:rectangle(-i,1,2) Ex2:rectangle(-i,1,-2,D,C) Ex3:rectangle(point(0,0,0),point(3,3,3),point(0,0,3),D,C) Ex4:rectangle(point(0,0,0),point(3,3,3),2,D,C) - ''' return GiacMethods['rectangle'](self,*args) @@ -14421,14 +13280,13 @@ cdef class GiacMethods_base: Help for rectangle_droit: rectangle_droit(Opt) Option of the plotarea command and of the area command. - See also: 1/ plotarea 2/ area + See also: 1/ plotarea 2/ area Ex1: plotarea(x^2,x=0..1,5,trapezoid) Ex2: plotarea(x^2,x=0..1,5,middle_point) Ex3: plotarea(x^2,x=0..1,5,right_rectangle) Ex4: plotarea(x^2,x=0..1,5,left_rectangle) Ex5: area(x^2,x=0..1,5,middle_point) Ex6: area(x^2,x=0..1,5,trapezoid) - ''' return GiacMethods['rectangle_droit'](self,*args) @@ -14437,14 +13295,13 @@ cdef class GiacMethods_base: Help for rectangle_gauche: rectangle_gauche(Opt) Option of the plotarea command and of the area command. - See also: 1/ plotarea 2/ area + See also: 1/ plotarea 2/ area Ex1: plotarea(x^2,x=0..1,5,trapezoid) Ex2: plotarea(x^2,x=0..1,5,middle_point) Ex3: plotarea(x^2,x=0..1,5,right_rectangle) Ex4: plotarea(x^2,x=0..1,5,left_rectangle) Ex5: area(x^2,x=0..1,5,middle_point) Ex6: area(x^2,x=0..1,5,trapezoid) - ''' return GiacMethods['rectangle_gauche'](self,*args) @@ -14453,11 +13310,10 @@ cdef class GiacMethods_base: Help for rectangle_plein: rectangle_plein(Real(a),[Real(b)]) Draws a full direct rectangle (resp square) with sides a,b (resp a) from the turtle position and on the left (by default b=a). - See also: 1/ triangle_plein + See also: 1/ triangle_plein Ex1: rectangle_plein 20 Ex2:rectangle_plein(20) Ex3:rectangle_plein(20,40) - ''' return GiacMethods['rectangle_plein'](self,*args) @@ -14466,10 +13322,9 @@ cdef class GiacMethods_base: Help for rectangular_coordinates: rectangular_coordinates(LstPolCoord) Returns the list of the abscissa and of the ordinate of a point given by the list of its polar coordinates. - See also: 1/ abscissa 2/ ordinate 3/ rectangular_coordinates 4/ polar_point + See also: 1/ abscissa 2/ ordinate 3/ rectangular_coordinates 4/ polar_point Ex1:rectangular_coordinates([1,pi/4]) Ex2:rectangular_coordinates(polar_point(1,pi/4)) - ''' return GiacMethods['rectangular_coordinates'](self,*args) @@ -14478,10 +13333,9 @@ cdef class GiacMethods_base: Help for recule: recule(NULL or Real(n)) The turtle takes n steps back (by default n=10). - See also: 1/ avance 2/ saute + See also: 1/ avance 2/ saute Ex1: recule 30 Ex2:recule(30) - ''' return GiacMethods['recule'](self,*args) @@ -14490,10 +13344,9 @@ cdef class GiacMethods_base: Help for red: red(Opt) Option of the display command to display with color. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),red) Ex2: F:=display(point(2+1.5*i),point_point+green) - ''' return GiacMethods['red'](self,*args) @@ -14502,12 +13355,11 @@ cdef class GiacMethods_base: Help for reduced_conic: reduced_conic(Expr,[LstVar]) Returns the origin and the matrix of a base in which the conic given by its equation is reduced, 0 or 1 (0 if the conic is degenerate) and the equation of the conic in this base and also its parametric equation. - See also: 1/ gauss 2/ conic + See also: 1/ gauss 2/ conic Ex1:reduced_conic(x^2+2*x-2*y+1) Ex2:reduced_conic(a*x^2-2*x*y+a*y^2-2*x+2*y+3,[x,y]) Ex3:reduced_conic(2*u^2+2*u*v+2*v^2+5*u+3,[u,v]) Ex4:reduced_conic((x+y)^2-2*x+1,x,y) - ''' return GiacMethods['reduced_conic'](self,*args) @@ -14516,12 +13368,11 @@ cdef class GiacMethods_base: Help for reduced_quadric: reduced_quadric(Expr, [LstVar]) Returns the origin and the matrix of a basis in which the quadric (given by its equation) is reduced, the list of its eigenvalues, the equation of the quadric in this basis and its parametric equation. - See also: 1/ gauss 2/ quadric + See also: 1/ gauss 2/ quadric Ex1:reduced_quadric(4*x^2+y^2+z^2-4*x*y+4*x*z-2*y*z+8*x-4*y+4*z+2) Ex2:reduced_quadric(x^2+3*y^2-3*z^2-8*y*z+2*z*x-4*x*y-1,x,y,z) Ex3:reduced_quadric((u+v)*(v-w)+3*u-5*v,[u,v,w]) Ex4:reduced_quadric(7*x^2+4*y^2+4*z^2+4*x*y-4*x*z-2*y*z-4*x+5*y+4*z-18,[x,y,z]) - ''' return GiacMethods['reduced_quadric'](self,*args) @@ -14530,10 +13381,9 @@ cdef class GiacMethods_base: Help for ref: ref(Mtrx(M)) Gaussian reduction of AX=b (M=A|(-b)). - See also: 1/ rref 2/ det + See also: 1/ rref 2/ det Ex1:ref([[3,1,-2],[3,2,2]]) Ex2:ref([[2,1,1,-1],[1,1,2,-1],[1,2,1,-4]]) - ''' return GiacMethods['ref'](self,*args) @@ -14542,11 +13392,10 @@ cdef class GiacMethods_base: Help for reflection: reflection((Pnt(A) or Line(D)),(Pnt(C) or Curve(C))) reflection(D,C) (or reflection(A,C))=symmetry of C with the symmetry-line D (or sym-point A). - See also: 1/ rotation 2/ translation + See also: 1/ rotation 2/ translation Ex1:reflection(line(0,1+i),A) Ex2:reflection(B,A) Ex3:reflection(line(0,1+i),circle(i,1+i)) - ''' return GiacMethods['reflection'](self,*args) @@ -14555,9 +13404,8 @@ cdef class GiacMethods_base: Help for regroup: regroup(Expr) Collects terms in an expression. - See also: 1/ simplify 2/ normal + See also: 1/ simplify 2/ normal Ex1:regroup(x+3*x+5*4/x) - ''' return GiacMethods['regroup'](self,*args) @@ -14566,9 +13414,8 @@ cdef class GiacMethods_base: Help for relabel_vertices: relabel_vertices(Graph(G),Lst(L)) Returns a copy of G with vertex labels changed to those in the list L. - See also: 1/ graph_vertices 2/ isomorphic_copy 3/ permute_vertices + See also: 1/ graph_vertices 2/ isomorphic_copy 3/ permute_vertices Ex1:relabel_vertices(graph([a,b,c]),["first","second","third"]) - ''' return GiacMethods['relabel_vertices'](self,*args) @@ -14577,10 +13424,9 @@ cdef class GiacMethods_base: Help for reliability_polynomial: reliability_polynomial(Graph(G),[Var(p)]) Returns the reliability polynomial [or its value at point p] of undirected graph G. If G is weighted, all weights must be positive integers and are interpreted as edge multiplicities. - See also: 1/ chromatic_polynomial 2/ flow_polynomial 3/ tutte_polynomial + See also: 1/ chromatic_polynomial 2/ flow_polynomial 3/ tutte_polynomial Ex1:reliability_polynomial(graph("petersen")) Ex2:reliability_polynomial(graph("petersen"),0.5) - ''' return GiacMethods['reliability_polynomial'](self,*args) @@ -14589,11 +13435,10 @@ cdef class GiacMethods_base: Help for rem: rem((Vect or Poly),(Vect or Poly),[Var]) Euclidean remainder of 2 polynomials. - See also: 1/ quo 2/ quorem 3/ Rem 4/ irem + See also: 1/ quo 2/ quorem 3/ Rem 4/ irem Ex1:rem([1,2,3,4],[-1,2]) Ex2:rem(x^3+2x^2+3x+4,-x+2) Ex3:rem(t^3+2t^2+3t+4,-t+2,t) - ''' return GiacMethods['rem'](self,*args) @@ -14602,12 +13447,11 @@ cdef class GiacMethods_base: Help for remain: remain(Intg(a),Intg(b)) Euclidean remainder of 2 integers. - See also: 1/ iquo 2/ smod 3/ rem 4/ mod + See also: 1/ iquo 2/ smod 3/ rem 4/ mod Ex1:remain(125,15) Ex2:remain(125,41) Ex3:remain(-7,3) Ex4:remain(25+12*i,5+7*i) - ''' return GiacMethods['remain'](self,*args) @@ -14616,10 +13460,9 @@ cdef class GiacMethods_base: Help for remove: remove(FncBool(f)||a,Lst(l)) Remove the occurrences a of l or the elements a such that f(a)=true. - See also: 1/ select 2/ suppress + See also: 1/ select 2/ suppress Ex1:remove(x->x>=5,[1,2,6,7]) Ex2:remove(5,[1,2,5,6,7,5]) - ''' return GiacMethods['remove'](self,*args) @@ -14628,10 +13471,9 @@ cdef class GiacMethods_base: Help for reorder: reorder(Expr, LstVar) Reorders the variables in E according to the order of the 2nd argument. - See also: 1/ + See also: 1/ Ex1:reorder(-2) Ex2:reorder(x^2+2*x+y^2,[y,x]) - ''' return GiacMethods['reorder'](self,*args) @@ -14640,10 +13482,9 @@ cdef class GiacMethods_base: Help for resample: resample(Lst(clip),[Intg(s),[Intg(q)]]) Returns a copy of the input audio clip resampled to the rate s (by default 44100), optionally with quality level q (from 0 to 4, by default 2). - See also: 1/ samplerate 2/ playsnd 3/ readwav 4/ writewav + See also: 1/ samplerate 2/ playsnd 3/ readwav 4/ writewav Ex1:resample(readwav("/some/file"),48000) Ex2:resample(readwav("/some/file"),48000,3) - ''' return GiacMethods['resample'](self,*args) @@ -14652,12 +13493,11 @@ cdef class GiacMethods_base: Help for residue: residue(Expr,Var(v),Cplx(a)) Returns the residue in a of the expression with v as variable. - See also: 1/ series + See also: 1/ series Ex1:residue(1/z,z,0) Ex2:residue(5/z,z=0) Ex3:residue(cos(z)/(z*(z-b)),z,0) Ex4:residue(c/(z*(z-b)),z=b) - ''' return GiacMethods['residue'](self,*args) @@ -14666,12 +13506,11 @@ cdef class GiacMethods_base: Help for resoudre: resoudre(Expr,[Var]) Solves a (or a set of) polynomial equation. - See also: 1/ linsolve 2/ proot 3/ fsolve 4/ csolve 5/ nSolve + See also: 1/ linsolve 2/ proot 3/ fsolve 4/ csolve 5/ nSolve Ex1:resoudre(x^2-3=1) Ex2:resoudre(x^3-3*y,y) Ex3:resoudre([y-z=0,z-x=0,x-y=0,x-1+y+z=0],[x,y,z]) Ex4:resoudre([x^2-y^2=0,x^2-z^2=0],[x,y,z]) - ''' return GiacMethods['resoudre'](self,*args) @@ -14680,12 +13519,11 @@ cdef class GiacMethods_base: Help for resoudre_dans_C: resoudre_dans_C(LstEq,LstVar) Returns the list of complex solutions of an equation or a matrix where the rows are ℂ-solutions of a system of polynomial equations. - See also: 1/ cZeros 2/ solve 3/ fslove + See also: 1/ cZeros 2/ solve 3/ fslove Ex1:resoudre_dans_C(x^4-1,x) Ex2:resoudre_dans_C(x^4-y^4 and x+y=2,[x,y]) Ex3:resoudre_dans_C(x^4-y^4 and x+y=0 and x^2=2*x,[x,y]) Ex4:resoudre_dans_C(u*v-u=v and v^2=u,[u,v]) - ''' return GiacMethods['resoudre_dans_C'](self,*args) @@ -14694,17 +13532,16 @@ cdef class GiacMethods_base: Help for resoudre_systeme_lineaire: resoudre_systeme_lineaire(LstLinEq,LstVar) Linear equations system solver. - See also: 1/ solve 2/ proot 3/ simult 4/ gaussjord 5/ pivot 6/ ref 7/ conjugate_gradient + See also: 1/ solve 2/ proot 3/ simult 4/ gaussjord 5/ pivot 6/ ref 7/ conjugate_gradient Ex1:resoudre_systeme_lineaire([x+y+z=1,x-y=2,2*x-z=3],[x,y,z]) Ex2:resoudre_systeme_lineaire([m*x+y=a,x+m*y=b],[x,y]) Ex3:resoudre_systeme_lineaire([x+y-z-1,x-y+1,x-y-z-1]%2,[x,y,z]) Ex4:resoudre_systeme_lineaire([[3,4],[1,2]],[0,1]) - Ex5: p,l,u:=lu([[3,4],[1,2]]); linsolve(p,l,u,[0,1]) + Ex5: p,l,u:=lu([[3,4],[1,2]]); linsolve(p,l,u,[0,1]) Ex6:resoudre_systeme_lineaire([2*x+y+z=1,x+y+2*z=1,x+2*y+z=4],[x,y,z]) Ex7:resoudre_systeme_lineaire([[2,1,1],[1,1,2],[1,2,1]],[1,1,4]) Ex8: p,l,u:=lu([[2,1,1],[1,1,2],[1,2,1]]);linsolve(p,l,u,[1,1,4]) Ex9: a:=[[100,2],[2,100]];linsolve(evalf(a),[0,1]); - ''' return GiacMethods['resoudre_systeme_lineaire'](self,*args) @@ -14713,10 +13550,9 @@ cdef class GiacMethods_base: Help for resultant: resultant(Poly,Poly,Var) Resultant of two polynomials. - See also: 1/ sylvester 2/ gcd + See also: 1/ sylvester 2/ gcd Ex1:resultant(x^2-1,x^3-1,x) Ex2:resultant(x^3-p*x+q,3*x^2-p,x) - ''' return GiacMethods['resultant'](self,*args) @@ -14729,7 +13565,6 @@ cdef class GiacMethods_base: Ex2: L:=[1,2,3,4];L:=revlist(L) Ex3: L:=[1,2,3,4];L.revlist() Ex4: L:=[1,2,3,4];L.reverse() - ''' return GiacMethods['reverse'](self,*args) @@ -14738,9 +13573,8 @@ cdef class GiacMethods_base: Help for reverse_graph: reverse_graph(Graph(G)) Returns the copy of G with the directions of all edges reversed. - See also: 1/ digraph + See also: 1/ digraph Ex1:reverse_graph(digraph(%{[1,2],[1,3],[2,3]%})) - ''' return GiacMethods['reverse_graph'](self,*args) @@ -14749,9 +13583,8 @@ cdef class GiacMethods_base: Help for reverse_rsolve: reverse_rsolve(Vect(v)) If v=[v_0 ... v_(2n-1)], returns [b_n,...,b_0] such that b_n*v_{n+k}+...+b_0*v_k=0 for k=0..n-1. - See also: 1/ rsolve + See also: 1/ rsolve Ex1:reverse_rsolve([1,-1,3,3]) - ''' return GiacMethods['reverse_rsolve'](self,*args) @@ -14760,9 +13593,8 @@ cdef class GiacMethods_base: Help for revert: revert(Expr) Returns the inverse expansion of a series expansion at 0. - See also: 1/ series + See also: 1/ series Ex1:revert(x+x^2+x^4) - ''' return GiacMethods['revert'](self,*args) @@ -14771,8 +13603,7 @@ cdef class GiacMethods_base: Help for revlex: revlex(Opt) Option of the gbasis or greduce command to specify an order for monomials (complete degree then inverse lexicographic order). - See also: 1/ gbasis 2/ greduce - + See also: 1/ gbasis 2/ greduce ''' return GiacMethods['revlex'](self,*args) @@ -14785,7 +13616,6 @@ cdef class GiacMethods_base: Ex2: L:=[1,2,3,4];L:=revlist(L) Ex3: L:=[1,2,3,4];L.revlist() Ex4: L:=[1,2,3,4];L.reverse() - ''' return GiacMethods['revlist'](self,*args) @@ -14794,14 +13624,13 @@ cdef class GiacMethods_base: Help for rgb: rgb(Opt) Option of the display (or affichage) command to defined colors RGB. - See also: 1/ display 2/ filled + See also: 1/ display 2/ filled Ex1: redcolor:=rgb(0.99,0,0);display(square(0,2+i),filled+redcolor) Ex2: greencolor:=rgb(0,0.99,0);display(square(0,2+i),filled+greencolor) Ex3: bluecolor:=rgb(0,0,0.99);display(square(0,2+i),filled+bluecolor) Ex4: greycolor:=rgb(0.5,0.5,0.5);display(square(0,2+i),filled+greycolor) Ex5: F:=display(square(0,2+i),filled+rgb(rand(),rand(),rand())) Ex6: L:=rand(),rand(),rand();affichage(square(0,2+i),rgb(L)+rempli);legend(0.2,[L]) - ''' return GiacMethods['rgb'](self,*args) @@ -14810,13 +13639,12 @@ cdef class GiacMethods_base: Help for rhombus: rhombus(Pnt(A)||Cplx,Pnt(B)||Cplx,Angle(a)||Pnt(P)||Lst(P,a)),[Var(C)],[Var(D)]) Returns and draws the rhombus ABCD such that the angle (AB,AD)=a (or in the plane ABP angle(AB,AD)=angle(AB,AP) or such that angle(AB,AD)=a). - See also: 1/ square 2/ quadrilateral + See also: 1/ square 2/ quadrilateral Ex1:rhombus(i,1+i,pi/4) Ex2:rhombus(i,1+i,pi/4,C,D) Ex3:rhombus(point(0,0,0),point(3,3,3),[point(0,0,3),pi/4]) Ex4:rhombus(point(0,0,0),point(3,3,3),point(0,0,3),C,D) Ex5:rhombus(point(0,0,0),point(3,3,3),[point(0,0,3),pi/4],C,D) - ''' return GiacMethods['rhombus'](self,*args) @@ -14825,10 +13653,9 @@ cdef class GiacMethods_base: Help for rhombus_point: rhombus_point(Opt) Option of the display command for a point. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),point_point) Ex2: F:=display(point(2+1.5*i),rhombus_point) - ''' return GiacMethods['rhombus_point'](self,*args) @@ -14837,12 +13664,11 @@ cdef class GiacMethods_base: Help for rhs: rhs(Equal(a=b) or Interval(a..b) or Str,Intg) Returns the right part of an equality, of an interval, of a list or of a string. - See also: 1/ left 2/ mid 3/ tail 4/ head + See also: 1/ left 2/ mid 3/ tail 4/ head Ex1:rhs(a=b) Ex2:rhs(x^2+1=5) Ex3:rhs(1..5) Ex4:rhs("abcdefg",3) - ''' return GiacMethods['rhs'](self,*args) @@ -14851,9 +13677,8 @@ cdef class GiacMethods_base: Help for riemann_window: riemann_window(Lst,[Interval(n1..n2)]) Applies the Riemann windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ bartlett_hann_window 12/ triangle_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ bartlett_hann_window 12/ triangle_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(riemann_window(randvector(1000,0..1))) - ''' return GiacMethods['riemann_window'](self,*args) @@ -14862,12 +13687,11 @@ cdef class GiacMethods_base: Help for right: right(Equal(a=b) or Interval(a..b) or Str,Intg) Returns the right part of an equality, of an interval, of a list or of a string. - See also: 1/ left 2/ mid 3/ tail 4/ head + See also: 1/ left 2/ mid 3/ tail 4/ head Ex1:right(a=b) Ex2:right(x^2+1=5) Ex3:right(1..5) Ex4:right("abcdefg",3) - ''' return GiacMethods['right'](self,*args) @@ -14876,14 +13700,13 @@ cdef class GiacMethods_base: Help for right_rectangle: right_rectangle(Opt) Option of the plotarea command and of the area command. - See also: 1/ plotarea 2/ area + See also: 1/ plotarea 2/ area Ex1: plotarea(x^2,x=0..1,5,trapezoid) Ex2: plotarea(x^2,x=0..1,5,middle_point) Ex3: plotarea(x^2,x=0..1,5,right_rectangle) Ex4: plotarea(x^2,x=0..1,5,left_rectangle) Ex5: area(x^2,x=0..1,5,middle_point) Ex6: area(x^2,x=0..1,5,trapezoid) - ''' return GiacMethods['right_rectangle'](self,*args) @@ -14892,13 +13715,12 @@ cdef class GiacMethods_base: Help for right_triangle: right_triangle((Pnt(A) or Cplx),(Pnt(B) or Cplx),(Real(k) or Pnt(P) or Lst(P,k)),[Var(C)]) Draws the A_rectangular triangle ABC with AC=k*AB (or in the plane ABP AC=AP or AC=k*AB). - See also: 1/ triangle + See also: 1/ triangle Ex1:right_triangle(1,i,tan(pi/3)) Ex2:right_triangle(1,i,1/2,C) Ex3:right_triangle(point(0,0,0),point(3,3,3),point(0,0,3)) Ex4:right_triangle(point(0,0,0),point(3,3,3),[point(0,0,3),1/2],C) Ex5:right_triangle(point(0,0,0),point(3,3,3),[point(0,0,3),1/2],C) - ''' return GiacMethods['right_triangle'](self,*args) @@ -14907,11 +13729,10 @@ cdef class GiacMethods_base: Help for risch: risch(Expr,[Var]) Returns a primitive of the expression calculated with the Risch algorithm. - See also: 1/ int + See also: 1/ int Ex1:risch(ln(x),x) Ex2:risch(ln(x)) Ex3:risch(exp(x^2),x) - ''' return GiacMethods['risch'](self,*args) @@ -14920,9 +13741,8 @@ cdef class GiacMethods_base: Help for rm_a_z: rm_a_z(NULL) Erases all the variable name made up of only one lowercase a..z character. - See also: 1/ rm_all_vars + See also: 1/ rm_all_vars Ex1:rm_a_z() - ''' return GiacMethods['rm_a_z'](self,*args) @@ -14931,9 +13751,8 @@ cdef class GiacMethods_base: Help for rm_all_vars: rm_all_vars(NULL) Erases all the variable names. - See also: 1/ rm_a_z + See also: 1/ rm_a_z Ex1:rm_all_vars() - ''' return GiacMethods['rm_all_vars'](self,*args) @@ -14942,9 +13761,8 @@ cdef class GiacMethods_base: Help for rmbreakpoint: rmbreakpoint(Intg) Removes a breakpoint. - See also: 1/ breakpoint + See also: 1/ breakpoint Ex1:rmbreakpoint(1) - ''' return GiacMethods['rmbreakpoint'](self,*args) @@ -14953,9 +13771,8 @@ cdef class GiacMethods_base: Help for rmmod: rmmod(Str(pwd)) Removes the installed dynamic libraries. - See also: 1/ lsmod 2/ insmod + See also: 1/ lsmod 2/ insmod Ex1:rmmod("/home/parisse/giac/src/libprogfr.so") - ''' return GiacMethods['rmmod'](self,*args) @@ -14964,9 +13781,8 @@ cdef class GiacMethods_base: Help for rmwatch: rmwatch(Var) Clears a variables from the table of displayed variables in step/step. - See also: 1/ watch + See also: 1/ watch Ex1:rmwatch(a) - ''' return GiacMethods['rmwatch'](self,*args) @@ -14975,11 +13791,10 @@ cdef class GiacMethods_base: Help for romberg: romberg(Expr(f(x)),Var(x),Real(a),Real(b)) Returns the approximate value of integrate(f(x),x,a,b) by Romberg's method. - See also: 1/ integrate 2/ gaussquad + See also: 1/ integrate 2/ gaussquad Ex1:romberg(exp(x^2),x,0,1) Ex2:romberg(x^2,x,0,1) Ex3:romberg(exp(-x^2),x,-1,1) - ''' return GiacMethods['romberg'](self,*args) @@ -14988,12 +13803,11 @@ cdef class GiacMethods_base: Help for rombergm: rombergm(Opt) Option of the area command. - See also: 1/ area + See also: 1/ area Ex1: area(x^2,x=0..1,5,simpson) Ex2: area(x^2,x=0..1,5,rombergt) Ex3: area(x^2,x=0..1,5,rombergm) Ex4:rombergm(area(x^2,x=0..1,5,gauss15)) - ''' return GiacMethods['rombergm'](self,*args) @@ -15002,12 +13816,11 @@ cdef class GiacMethods_base: Help for rombergt: rombergt(Opt) Option of the area command. - See also: 1/ area + See also: 1/ area Ex1: area(x^2,x=0..1,5,simpson) Ex2: area(x^2,x=0..1,5,rombergt) Ex3: area(x^2,x=0..1,5,rombergm) Ex4:rombergt(area(x^2,x=0..1,5,gauss15)) - ''' return GiacMethods['rombergt'](self,*args) @@ -15016,12 +13829,11 @@ cdef class GiacMethods_base: Help for rond: rond(Real(r),[Real(a)],[Real(b)]) Draws a circle (resp a arc) with radius r (resp and with angle (0,a) or (a,b)), tangent at the turtle position. - See also: 1/ disque + See also: 1/ disque Ex1: rond 30 Ex2:rond(40) Ex3:rond(40,90) Ex4:rond(40,10,100) - ''' return GiacMethods['rond'](self,*args) @@ -15030,12 +13842,11 @@ cdef class GiacMethods_base: Help for root: root(Expr(a),Expr(b)) Returns b^(1/a) (root(2,3)=sqrt(3)). - See also: 1/ + See also: 1/ Ex1:root(3,2) Ex2:root(1/3,2) Ex3:root(3,1.2) Ex4:root(3.2,1.2) - ''' return GiacMethods['root'](self,*args) @@ -15044,11 +13855,10 @@ cdef class GiacMethods_base: Help for rootof: rootof(LstPoly(P),LstPoly(Q)) Polynomial in terms of a root of an irreducible polynomial on Q. Returns P(a) with a the greatest root of Q. - See also: 1/ + See also: 1/ Ex1: normal(1/rootof([1,0],[1,0,10,0,1])) Ex2: normal(1/rootof([1,0,0],[1,1,0,-1])) - Ex3: rootof(x^4+x+1):='j'; normal(j^5); - + Ex3: rootof(x^4+x+1):='j'; normal(j^5); ''' return GiacMethods['rootof'](self,*args) @@ -15057,10 +13867,9 @@ cdef class GiacMethods_base: Help for roots: roots(Poly,[Var]) Returns a matrix having 2 columns and where the rows are the roots of the polynomial with their multiplicity (for 1 variable). - See also: 1/ proot 2/ cZeros + See also: 1/ proot 2/ cZeros Ex1:roots(t^3-1,t) Ex2:roots(x^5-2*x^4+x^3) - ''' return GiacMethods['roots'](self,*args) @@ -15069,7 +13878,7 @@ cdef class GiacMethods_base: Help for rotate: rotate(Lst||Str(L),[Intg(n)]) Returns the list where the last element [or the tail beginning with the n-th element] is moved to the first element (by default n=-1);L:=rotate(L,n) or L.rotate(n). - See also: 1/ tail 2/ mid 3/ shift + See also: 1/ tail 2/ mid 3/ shift Ex1:rotate([0,1,2,3],2) Ex2:rotate([[1,2,3],[4,5,6],[7,8,9]]) Ex3:rotate([0,1,2,3,4]) @@ -15078,7 +13887,6 @@ cdef class GiacMethods_base: Ex6: L:=[0,1,2,3,4];L.rotate() Ex7: L:=[0,1,2,3];L:=rotate([0,1,2,3],2) Ex8: L:=[0,1,2,3];L.rotate(2) - ''' return GiacMethods['rotate'](self,*args) @@ -15087,13 +13895,12 @@ cdef class GiacMethods_base: Help for rotation: rotation((Pnt(B) or Cplx or Dr3),Angle(a1),(Pnt(A) or Curve)) rotation(B,a1,A) (resp rotation(d,a1,A)) is the transformation of A by rotation with center B (resp of axis d) and angle a1. - See also: 1/ translation 2/ reflection + See also: 1/ translation 2/ reflection Ex1:rotation(point(1+i),pi/2,point(i)) Ex2:rotation(1+i,pi/3,line(i,1)) Ex3:rotation(line(x=y,y=z),pi/2,point(1,-1,2)) Ex4: r:=rotation(1+i,pi/2);r(i) Ex5: r:=rotation(line(x=y,y=z),pi/2);r(point(1,-1,2)) - ''' return GiacMethods['rotation'](self,*args) @@ -15102,13 +13909,12 @@ cdef class GiacMethods_base: Help for round: round(Real or Cplx,[Intg(n)]) Rounds the real or complex to the nearest integer (resp the nearest decimal number) or to the nearest element of ℤ[i], (resp with n decimals). - See also: 1/ floor 2/ ceil + See also: 1/ floor 2/ ceil Ex1:round(2.5) Ex2:round(-2.4) Ex3:round(-2.5+i*2.4) Ex4:round(1.237,2) Ex5:round(sqrt(2)+i*sqrt(5),4) - ''' return GiacMethods['round'](self,*args) @@ -15117,11 +13923,10 @@ cdef class GiacMethods_base: Help for row: row(Mtrx(A),Intg(n)||Interval(n1..n2)) Returns row n or the sequence of the rows n1..n2 of the matrix A, or optional argument of count,count_eq,count_inf,count_sup. - See also: 1/ col 2/ count 3/ count_eq 4/ count_inf 5/ count_sup + See also: 1/ col 2/ count 3/ count_eq 4/ count_inf 5/ count_sup Ex1:row([[1,2,3],[4,5,6],[7,8,9]],1) Ex2:row([[1,2,3],[4,5,6],[7,8,9]],0..1) Ex3: count_eq(3,[[1,2,3],[4,3,2],[3,2,1]],row) - ''' return GiacMethods['row'](self,*args) @@ -15130,9 +13935,8 @@ cdef class GiacMethods_base: Help for rowAdd: rowAdd(Mtrx(A),Intg(n1),Intg(n2)) Returns the matrix obtained from A by replacing the n2-th row by the sum of the n1-th and n2-th rows. - See also: 1/ rowSwap + See also: 1/ rowSwap Ex1:rowAdd([[1,2],[3,4],[5,6]],1,2) - ''' return GiacMethods['rowAdd'](self,*args) @@ -15141,10 +13945,9 @@ cdef class GiacMethods_base: Help for rowDim: rowDim(Mtrx) Number of rows of a matrix. - See also: 1/ ncols + See also: 1/ ncols Ex1:rowDim([[1,2,3],[4,5,6]]) Ex2:rowDim([[1,2],[3,4],[5,6]]) - ''' return GiacMethods['rowDim'](self,*args) @@ -15153,10 +13956,9 @@ cdef class GiacMethods_base: Help for rowNorm: rowNorm(Vect or Mtrx) Returns the max of the l1_norm of the rows of a matrix: rowNorm(a_{j,k})=max_j(sum_k(|a_{j,k}|)). - See also: 1/ norm + See also: 1/ norm Ex1:rowNorm([[1,2],[3,-4]]) Ex2:rowNorm([[1,2,3,-4],[-5,3,2,1]]) - ''' return GiacMethods['rowNorm'](self,*args) @@ -15165,9 +13967,8 @@ cdef class GiacMethods_base: Help for rowSwap: rowSwap(Mtrx(A),Intg(n1),Intg(n2)) Returns the matrix obtained from A by swapping the n1-th row and the n2-th row. - See also: 1/ rowAdd 2/ colSwap + See also: 1/ rowAdd 2/ colSwap Ex1:rowSwap([[1,2],[3,4],[5,6]],1,2) - ''' return GiacMethods['rowSwap'](self,*args) @@ -15176,10 +13977,9 @@ cdef class GiacMethods_base: Help for rowdim: rowdim(Mtrx) Number of rows of a matrix. - See also: 1/ ncols + See also: 1/ ncols Ex1:rowdim([[1,2,3],[4,5,6]]) Ex2:rowdim([[1,2],[3,4],[5,6]]) - ''' return GiacMethods['rowdim'](self,*args) @@ -15188,10 +13988,9 @@ cdef class GiacMethods_base: Help for rownorm: rownorm(Vect or Mtrx) Returns the max of the l1_norm of the rows of a matrix: rowNorm(a_{j,k})=max_j(sum_k(|a_{j,k}|)). - See also: 1/ norm + See also: 1/ norm Ex1:rownorm([[1,2],[3,-4]]) Ex2:rownorm([[1,2,3,-4],[-5,3,2,1]]) - ''' return GiacMethods['rownorm'](self,*args) @@ -15200,10 +13999,9 @@ cdef class GiacMethods_base: Help for rowspace: rowspace(Mtrx(A), [Var(d)]) Returns a matrix where the rows are a basis of the vector space generated by the rows of the matrix A [d is the dimension of this space]. - See also: 1/ colspace + See also: 1/ colspace Ex1:rowspace([[1,2,3],[1,2,3],[1,2,4],[1,2,5]]) Ex2:rowspace([[1,2,3],[1,3,6],[2,5,9]],d) - ''' return GiacMethods['rowspace'](self,*args) @@ -15212,9 +14010,8 @@ cdef class GiacMethods_base: Help for rowswap: rowswap(Mtrx(A),Intg(n1),Intg(n2)) Returns the matrix obtained from A by swapping the n1-th row and the n2-th row. - See also: 1/ rowAdd 2/ colSwap + See also: 1/ rowAdd 2/ colSwap Ex1:rowswap([[1,2],[3,4],[5,6]],1,2) - ''' return GiacMethods['rowswap'](self,*args) @@ -15223,12 +14020,11 @@ cdef class GiacMethods_base: Help for rref: rref(Mtrx(M),[Intg(k)]||Opt) Row reduction to echelon form of AX=b (M=A|(-b)) [Reduction on columns 0..k-1]. - See also: 1/ ker 2/ image 3/ det 4/ Rref 5/ pivot 6/ ref 7/ keep_pivot + See also: 1/ ker 2/ image 3/ det 4/ Rref 5/ pivot 6/ ref 7/ keep_pivot Ex1:rref([[3,1,-2],[3,2,2]]) Ex2:rref([[2,1,1,-1],[1,1,2,-1],[1,2,1,-4]]) Ex3:rref([[2,1,1,-1],[1,1,2,-1],[1,2,1,-4]],2) Ex4:rref([[1,1,0,0,-a1],[0,1,1,0,-a2],[0,0,1,1,-a3],[1,0,0,1,-a4]],keep_pivot) - ''' return GiacMethods['rref'](self,*args) @@ -15237,13 +14033,12 @@ cdef class GiacMethods_base: Help for rsolve: rsolve((Expr or LstExpr),(Var or LstVar),(InitVal or LstInitVal)) Gives the value of a recurrent sequence or of a system of recurrent sequences. - See also: 1/ seqsolve 2/ plotseq 3/ tableseq 4/ reverse_rsolve + See also: 1/ seqsolve 2/ plotseq 3/ tableseq 4/ reverse_rsolve Ex1:rsolve(u(n+1)=2*u(n)+n,u(n),u(0)=1) Ex2:rsolve(u(n+1)=2*u(n)+n,u(n),u(1)^2=1) Ex3:rsolve(u(n+1)=(u(n)-1)/(u(n)-2),u(n),u(0)=4) Ex4:rsolve(u(n+2)=u(n)+2*u(n+1)+n+1,u(n),[u(0)=0,u(1)=1]) Ex5:rsolve([u(n+1)=3*v(n)+u(n),v(n+1)=v(n)+u(n)],[u(n),v(n)],[u(0)=1,v(0)=2]) - ''' return GiacMethods['rsolve'](self,*args) @@ -15252,10 +14047,9 @@ cdef class GiacMethods_base: Help for same: same(Expr,Expr) Equality test. - See also: 1/ + See also: 1/ Ex1:same(a,b) Ex2:same((2-1)^2,2^2-2*2+1) - ''' return GiacMethods['same'](self,*args) @@ -15264,14 +14058,13 @@ cdef class GiacMethods_base: Help for sample: sample(Lst(L),Intg(n)) sample(L,n)= rand(n,L)=list of the n extracted elements of L without replacement. - See also: 1/ rand + See also: 1/ rand Ex1:sample([1,2,3,4,5,6],6) Ex2:sample([1,2,3,4,5,6],3) Ex3:sample(["r","r","r","b","n"],3) Ex4: L:=[1,2,3,4,5,6];L:=sample(L,3) Ex5: L:=[1,2,3,4,5,6];L.sample(3) - Ex6: - + Ex6: ''' return GiacMethods['sample'](self,*args) @@ -15280,9 +14073,8 @@ cdef class GiacMethods_base: Help for samplerate: samplerate(Lst(clip)) Returns the sampling rate of an audio clip, in Hertz. - See also: 1/ bit_depth 2/ channels 3/ channel_data 4/ duration + See also: 1/ bit_depth 2/ channels 3/ channel_data 4/ duration Ex1:samplerate(readwav("/some/file")) - ''' return GiacMethods['samplerate'](self,*args) @@ -15291,13 +14083,12 @@ cdef class GiacMethods_base: Help for sans_factoriser: sans_factoriser(Opt.) Option of the plotimplicit command. - See also: 1/ plotimplicit + See also: 1/ plotimplicit Ex1: plotimplicit(x^2+y^2-1,x,y,unfactored) Ex2: plotimplicit(x^2+y^2-1,[x,y],unfactored) Ex3: plotimplicit(x^2+y^2+z^2-1,x,y,z,xstep=0.2,ystep=0.2,zstep=0.2,unfactored) Ex4: plotimplicit(x^2+y^2+z^2-1,[x,y,z],xstep=0.2,ystep=0.2,zstep=0.2,unfactored) Ex5: plotimplicit(x^2+y^2+z^2-1,x=0..1,y=0..1,z=0..1,xstep=0.2,ystep=0.2,zstep=0.2,unfactored) - ''' return GiacMethods['sans_factoriser'](self,*args) @@ -15306,10 +14097,9 @@ cdef class GiacMethods_base: Help for saute: saute(NULL or Real(n)) The turtle takes n steps forward without traces (by default n=10). - See also: 1/ avance 2/ recule + See also: 1/ avance 2/ recule Ex1: saute 30 Ex2:saute(30) - ''' return GiacMethods['saute'](self,*args) @@ -15318,11 +14108,10 @@ cdef class GiacMethods_base: Help for scalarProduct: scalarProduct(Vect(v1),Vect(v2)) Scalar product. - See also: 1/ * 2/ cross 3/ .* 4/ hadamard + See also: 1/ * 2/ cross 3/ .* 4/ hadamard Ex1:scalarProduct([1,2],[3,4]) Ex2:scalarProduct([3,2,4],[3,2,4]) Ex3:scalarProduct([[1,2],[3,4]],[[3,2],[4,5]]) - ''' return GiacMethods['scalarProduct'](self,*args) @@ -15331,11 +14120,10 @@ cdef class GiacMethods_base: Help for scalar_product: scalar_product(Vect(v1),Vect(v2)) Scalar product. - See also: 1/ * 2/ cross 3/ .* 4/ hadamard + See also: 1/ * 2/ cross 3/ .* 4/ hadamard Ex1:scalar_product([1,2],[3,4]) Ex2:scalar_product([3,2,4],[3,2,4]) Ex3:scalar_product([[1,2],[3,4]],[[3,2],[4,5]]) - ''' return GiacMethods['scalar_product'](self,*args) @@ -15344,9 +14132,8 @@ cdef class GiacMethods_base: Help for scatterplot: scatterplot(Mtrx) Draws for k=0..nrows, the points (xk,yk) where xk=element row k column 0 and yk=element row k column j (j=1..ncols). - See also: 1/ polygonplot 2/ polygonscatterplot 3/ listplot + See also: 1/ polygonplot 2/ polygonscatterplot 3/ listplot Ex1:scatterplot([[1,2,3],[2,0,1],[-1,2,3]]) - ''' return GiacMethods['scatterplot'](self,*args) @@ -15355,10 +14142,9 @@ cdef class GiacMethods_base: Help for schur: schur(Mtrx(A)) Matrix reduction to Hessenberg form. Returns [P,B] such that B=inv(P)*A*P:SCHUR(A)=hessenberg(A,-1). - See also: 1/ hessenberg + See also: 1/ hessenberg Ex1:schur([[1,2,3],[4,5,6],[7,8,1]]) Ex2:schur([[1,2,3,4],[4,5,6,7],[7,8,9,0],[0,1,2,3]]) - ''' return GiacMethods['schur'](self,*args) @@ -15367,9 +14153,8 @@ cdef class GiacMethods_base: Help for sec: sec(Expr) Secant: sec(x)=1/cos(x). - See also: 1/ cos 2/ asec + See also: 1/ cos 2/ asec Ex1:sec(pi/3) - ''' return GiacMethods['sec'](self,*args) @@ -15378,14 +14163,13 @@ cdef class GiacMethods_base: Help for secant_solver: secant_solver(Opt) Argument for fsolve giving the method for solving a numerical equation. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve(cos(x)=x,x,0..1,bisection_solver) Ex2: fsolve(cos(x)=x,x,0..1,brent_solver) Ex3: fsolve(cos(x)=x,x,0..1,falsepos_solver) Ex4: fsolve(cos(x)=x,x,0,newton_solver) Ex5: fsolve(cos(x)=x,x,0,secant_solver) Ex6: fsolve(cos(x)=x,x,0,steffenson_solver) - ''' return GiacMethods['secant_solver'](self,*args) @@ -15394,7 +14178,7 @@ cdef class GiacMethods_base: Help for segment: segment((Pnt or Cplx or Lst([xM,yM])),(Pnt or Cplx or Lst([xN,yN]),[Var],[Var] or Opt) segment(A,B) draws the segment AB and segment([xM,yM],[xN,yN]) draws the vector as origin [xM,yM], of coordinates [xN,yN] (i.e draws segment(M,point(M+N)) or Option of the arc command. - See also: 1/ line 2/ arc + See also: 1/ line 2/ arc Ex1:segment(i,1+i) Ex2:segment(point(i),point(1+i)) Ex3:segment(point(i),point(1+i),A,B) @@ -15402,7 +14186,6 @@ cdef class GiacMethods_base: Ex5:segment([-1,0],point([-1,0]+[2,1])) Ex6: arc(i,1,pi/4,segment) Ex7: affichage( arc(i,1,pi/4,segment),1+rempli) - ''' return GiacMethods['segment'](self,*args) @@ -15411,9 +14194,8 @@ cdef class GiacMethods_base: Help for seidel_spectrum: seidel_spectrum(Graph(G)) Returns the Seidel spectrum of G as a list of lists with two elements, each containing an eigenvalue and its multiplicity. - See also: 1/ graph_spectrum + See also: 1/ graph_spectrum Ex1:seidel_spectrum(graph("clebsch")) - ''' return GiacMethods['seidel_spectrum'](self,*args) @@ -15422,9 +14204,8 @@ cdef class GiacMethods_base: Help for seidel_switch: seidel_switch(Graph(G),Lst(V)) Returns a copy of G in which the edges between vertices in list V and vertices not in V are inverted (replaced with a set of edges from V to other vertices which are not present in G). - See also: 1/ neighbors 2/ graph_complement + See also: 1/ neighbors 2/ graph_complement Ex1:seidel_switch(cycle_graph(5),[1,2]) - ''' return GiacMethods['seidel_switch'](self,*args) @@ -15433,10 +14214,9 @@ cdef class GiacMethods_base: Help for select: select(FncBool(f),Lst(l)) Selects the elements e of l such that f(e)=true. - See also: 1/ remove 2/ range + See also: 1/ remove 2/ range Ex1:select(x->x>=5,[1,2,6,7]) Ex2:select(x->isprime(x),range(20)).^2 - ''' return GiacMethods['select'](self,*args) @@ -15445,9 +14225,8 @@ cdef class GiacMethods_base: Help for semi_augment: semi_augment(Mtrx(A),Mtrx(B)) Returns a matrix made with A and B, with n1+n2 rows and p columns if dim(A)=[n1,p] and dim(B)=[n2,p]. - See also: 1/ augment + See also: 1/ augment Ex1:semi_augment([[68,-21],[56,59],[1,2]],[[68,-21],[56,59]]) - ''' return GiacMethods['semi_augment'](self,*args) @@ -15455,8 +14234,8 @@ cdef class GiacMethods_base: r'''From Giac's documentation: Help for seq: seq(Expr(Xpr),Var(Var)=Int(a..b),[Real(p)]||Expr(Xpr),Var(Var),Real(a),Real(b),[Real(p)]) - Returns the sequence (2 or 3 arg) or the list (4 or 5 arg) obtained when var goes from a to b (step p) in Xpr (or the Xpr is repeated n times or returns the sequence of reals from a to b (step p)). And also seq(expression,variable,list) is equivalent to map(list,unapply(expression,variable)) - See also: 1/ $ 2/ makelist 3/ range 4/ map 5/ unapply + Returns the sequence (2 or 3 arg) or the list (4 or 5 arg) obtained when var goes from a to b (step p) in Xpr (or the Xpr is repeated n times or returns the sequence of reals from a to b (step p)). And also seq(expression,variable,list) is equivalent to map(list,unapply(expression,variable)) + See also: 1/ $ 2/ makelist 3/ range 4/ map 5/ unapply Ex1:seq(0.3,4) Ex2:seq(t,4) Ex3:seq(0,0) @@ -15466,9 +14245,8 @@ cdef class GiacMethods_base: Ex7:seq(2^k,k,0,8) Ex8:seq(2^k,k,0,8,2) Ex9:seq(x^3,x,[1,2,3]) - Ex10: [seq(0.3..2,0.2)] + Ex10: [seq(0.3..2,0.2)] Ex11: a:=(1,2,3);eval(seq(a,4)) - ''' return GiacMethods['seq'](self,*args) @@ -15477,11 +14255,10 @@ cdef class GiacMethods_base: Help for seqplot: seqplot(Expr(f(Var)),Var=[a,xm,xM],Intg(p)) For seeing the pth terms of the sequence u(0)=a,u(n)=f(u(n-1)). - See also: 1/ seqsolve 2/ rsolve + See also: 1/ seqsolve 2/ rsolve Ex1:seqplot(sqrt(2+x),6,5) Ex2:seqplot(sqrt(2+t),t=6,5) Ex3:seqplot(sqrt(2+x),x=[6,1,7],5,affichage=epaisseur_ligne_2) - ''' return GiacMethods['seqplot'](self,*args) @@ -15490,14 +14267,13 @@ cdef class GiacMethods_base: Help for seqsolve: seqsolve((Expr or LstExpr),(Var or LstVar),(InitVal or LstInitVal)) Gives the value of a recurrent sequence (u_{n+1}=f(u_n) or u_{n+k}=f(u_n,u_{n+1}...u_{n+k-1})) or of a system of recurrent sequences. - See also: 1/ rsolve 2/ plotseq 3/ tableseq + See also: 1/ rsolve 2/ plotseq 3/ tableseq Ex1:seqsolve(2x+n,[x,n],1) Ex2:seqsolve(2x+n*3^n,[x,n],1) Ex3:seqsolve(x+y,[x,y,n],[1,1]) Ex4:seqsolve(x+2*y+n+1,[x,y,n],[0,1]) Ex5:seqsolve([x+2*y,n+1+x],[x,y,n],[0,1]) Ex6:seqsolve([x+2*y+n+1,x],[x,y,n],[0,1]) - ''' return GiacMethods['seqsolve'](self,*args) @@ -15506,9 +14282,8 @@ cdef class GiacMethods_base: Help for sequence_graph: sequence_graph(Lst(L)) Returns an undirected graph with the degree sequence equal to the list L. - See also: 1/ degree_sequence 2/ is_graphic_sequence + See also: 1/ degree_sequence 2/ is_graphic_sequence Ex1:sequence_graph(degree_sequence(sequence_graph([3,2,4,2,3,4,5,7]))) - ''' return GiacMethods['sequence_graph'](self,*args) @@ -15517,13 +14292,13 @@ cdef class GiacMethods_base: Help for series: series(Expr,Equal(var=limit_point),[Order],[Dir(1,0,-1)]) Series expansion at finite or infinite points. - See also: 1/ limit 2/ taylor 3/ pad 4/ polynom 5/ truncate + See also: 1/ limit 2/ taylor 3/ pad 4/ polynom 5/ truncate Ex1:series(sin(x)/x,x=0) Ex2:series(sin(x),x=0,6,polynom) Ex3:series(ln(x+x^2)-ln(x),x=0,1) Ex4:series((x^4+x+2)/(x^2+1),x=0,5) Ex5: series("h",8); ln(1+h); - Ex6:series(1/(1+x+y),[x,y],[0,0],5) + Ex6:series(1/(1+x+y),[x,y],[0,0],5) Ex7:series(sin(x*y),[x,y],[1,pi/2],3) Ex8:series(sin((1+h*t)*(pi/2+k*t)),t=0,3,polynom)(t=1) Ex9:series(y^2/x^3,[x,y],[1,-1],3) @@ -15531,7 +14306,6 @@ cdef class GiacMethods_base: Ex11:series(subst(sin(x+y)+cos(y*x),[x,y],h*[x,y]),h=0,6,polynom) Ex12:series(subst(sin(x+y)+cos(y*x),[x,y],h*[x,y]),h=0,6,polynom)(h=1) Ex13: truncate(series(sin(x),x=0,6),6) - ''' return GiacMethods['series'](self,*args) @@ -15540,9 +14314,8 @@ cdef class GiacMethods_base: Help for set_edge_attribute: set_edge_attribute(Graph(G),Edge(e),Seq(tag1=value1,tag2=value2,..)) Stores the attributes to edge e and returns the modified copy of G. - See also: 1/ discard_edge_attribute 2/ get_edge_attribute 3/ list_edge_attributes + See also: 1/ discard_edge_attribute 2/ get_edge_attribute 3/ list_edge_attributes Ex1:set_edge_attribute(cycle_graph(3),[1,2],"cost"=12.4) - ''' return GiacMethods['set_edge_attribute'](self,*args) @@ -15551,9 +14324,8 @@ cdef class GiacMethods_base: Help for set_edge_weight: set_edge_weight(Graph(G),Edge(e),Real(w)) Sets the weight of the edge e in the weighted graph G to w and returns the modified copy of G. - See also: 1/ is_weighted 2/ get_edge_weight 3/ make_weighted 4/ weight_matrix + See also: 1/ is_weighted 2/ get_edge_weight 3/ make_weighted 4/ weight_matrix Ex1:set_edge_weight(graph(%{[1,2],[2,3]%}),[1,2],5) - ''' return GiacMethods['set_edge_weight'](self,*args) @@ -15562,9 +14334,8 @@ cdef class GiacMethods_base: Help for set_graph_attribute: set_graph_attribute(Graph(G),Seq(tag1=value1,tag2=value2,..)) Stores the attributes where each tag is a string, and returns the modified copy of G. - See also: 1/ discard_graph_attribute 2/ get_graph_attribute 3/ list_graph_attributes + See also: 1/ discard_graph_attribute 2/ get_graph_attribute 3/ list_graph_attributes Ex1:set_graph_attribute(cycle_graph(3),"name"="cycle graph") - ''' return GiacMethods['set_graph_attribute'](self,*args) @@ -15573,9 +14344,8 @@ cdef class GiacMethods_base: Help for set_pixel: set_pixel(Intg(x),Intg(y),Intg(col)) Pixel on and adds to the list of pixels. Run show_pixels() to display - See also: 1/ clear 2/ show_pixels 3/ draw_line 4/ draw_rectangle 5/ draw_polygon + See also: 1/ clear 2/ show_pixels 3/ draw_line 4/ draw_rectangle 5/ draw_polygon Ex1: clear(); set_pixel(4); draw_pixel(1,2,red); show_pixels(); - ''' return GiacMethods['set_pixel'](self,*args) @@ -15584,9 +14354,8 @@ cdef class GiacMethods_base: Help for set_vertex_attribute: set_vertex_attribute(Graph(G),Vrtx(v),Seq(tag1=value1,tag2=value2,..)) Stores the attributes to vertex v and returns the modified copy of G. - See also: 1/ discard_vertex_attribute 2/ get_vertex_attribute 3/ list_vertex_attributes + See also: 1/ discard_vertex_attribute 2/ get_vertex_attribute 3/ list_vertex_attributes Ex1:set_vertex_attribute(cycle_graph(3),1,"supply"=27) - ''' return GiacMethods['set_vertex_attribute'](self,*args) @@ -15595,9 +14364,8 @@ cdef class GiacMethods_base: Help for set_vertex_positions: set_vertex_positions(Graph(G),Lst(vp)) Sets the coordinates, given in the list vp, to the vertices of G and returns the modified copy of G. - See also: 1/ draw_graph + See also: 1/ draw_graph Ex1: G:=graph([1,2,3,4,5,6],%{[1,2],[1,4],[4,5],[2,5],[2,3],[3,6],[5,6]%}); G:=set_vertex_positions(G,[[0,0],[0.5,0],[1,0],[0,0.5],[0.5,0.5],[1,0.5]]) - ''' return GiacMethods['set_vertex_positions'](self,*args) @@ -15606,13 +14374,12 @@ cdef class GiacMethods_base: Help for shift: shift(Lst,[Intg(n)]) Returns the list where the last element [or the tail beginning with the n-th element] is moved to the first element and then completed with 0s (by default n=-1);L:=shift(L,2) o L.shift(2). - See also: 1/ rotate 2/ tail + See also: 1/ rotate 2/ tail Ex1:shift([0,1,2,3],2) Ex2:shift([0,1,2,3]) Ex3:shift([0,1,2,3,4]) Ex4: L:=[0,1,2,3];L:=shift(L,2) Ex5: L:=[0,1,2,3];L.shift(2) - ''' return GiacMethods['shift'](self,*args) @@ -15621,14 +14388,13 @@ cdef class GiacMethods_base: Help for shift_phase: shift_phase(Expr) shift_phase returns the expressions where the phase of the evaluated trigonometric expressions is increased by pi/2. - See also: 1/ series + See also: 1/ series Ex1:shift_phase(sin(x)) Ex2:shift_phase('sin(x+pi/2)') Ex3:shift_phase(x+sin(x)) Ex4:shift_phase(x+sin(x)) Ex5:shift_phase(cos(t)) Ex6:shift_phase(tan(u)) - ''' return GiacMethods['shift_phase'](self,*args) @@ -15637,9 +14403,8 @@ cdef class GiacMethods_base: Help for shortest_path: shortest_path(Graph(G),Vrtx(s),Vrtx(t)||Lst(T)) Returns the shortest path from vertex s to vertex t in G. If such path does not exist, returns an empty list. If vector T of vertices from G is given, the list of shortest paths from s to each t int T is returned. - See also: 1/ dijkstra 2/ vertex_distance + See also: 1/ dijkstra 2/ vertex_distance Ex1:shortest_path(cycle_graph(6),1,5) - ''' return GiacMethods['shortest_path'](self,*args) @@ -15648,9 +14413,8 @@ cdef class GiacMethods_base: Help for show_pixels: show_pixels(NULL) Displays the list of pixels. - See also: 1/ set_pixel 2/ clear + See also: 1/ set_pixel 2/ clear Ex1:show_pixels() - ''' return GiacMethods['show_pixels'](self,*args) @@ -15659,13 +14423,12 @@ cdef class GiacMethods_base: Help for shuffle: shuffle(Intg(n)||Lst(L)) Returns a random permutation of [0,1,2,..,n-1] or of the list L. - See also: 1/ permu2cycles 2/ is_permu 3/ permu2mat + See also: 1/ permu2cycles 2/ is_permu 3/ permu2mat Ex1:shuffle(4) Ex2:shuffle(7) Ex3:shuffle([1,3,5,7,9]) Ex4: L:=[1,3,5,7,9];L:=randperm(L) Ex5: L:=[1,3,5,7,9];L.randperm() - ''' return GiacMethods['shuffle'](self,*args) @@ -15674,13 +14437,12 @@ cdef class GiacMethods_base: Help for sierpinski_graph: sierpinski_graph(Intg(n),Intg(k),[triangle]) Returns Sierpiński (triangle) graph S(n,k) (resp. ST(n,k)). - See also: 1/ graph + See also: 1/ graph Ex1:sierpinski_graph(2,4) Ex2:sierpinski_graph(4,3) Ex3:sierpinski_graph(3,4) Ex4:sierpinski_graph(3,2) Ex5:sierpinski_graph(3,3,at_triangle) - ''' return GiacMethods['sierpinski_graph'](self,*args) @@ -15689,10 +14451,9 @@ cdef class GiacMethods_base: Help for sign: sign(Expr) Returns the sign (-1,0,+1) of its argument. - See also: 1/ abs + See also: 1/ abs Ex1:sign(-4) Ex2:sign(4-5) - ''' return GiacMethods['sign'](self,*args) @@ -15701,9 +14462,8 @@ cdef class GiacMethods_base: Help for signature: signature(Permut) Returns the signature of a permutation. - See also: 1/ permu2cycles 2/ is_permu + See also: 1/ permu2cycles 2/ is_permu Ex1:signature([1,0,3,4,2]) - ''' return GiacMethods['signature'](self,*args) @@ -15712,10 +14472,9 @@ cdef class GiacMethods_base: Help for signe: signe(Str(s)) Writes the string s with the font 20 at the point [10,10]. - See also: 1/ ecris + See also: 1/ ecris Ex1:signe("Thomas") Ex2:signe(Thomas) - ''' return GiacMethods['signe'](self,*args) @@ -15724,12 +14483,11 @@ cdef class GiacMethods_base: Help for similarity: similarity(Pnt or Dr3,Real,Angle,Pnt) similarity(B,k,a1,A)=transformation of A in the similarity (center B or axis d, coeff k,angle a1) (or also homothety(B,k*exp(i*a1),A)). - See also: 1/ homothety + See also: 1/ homothety Ex1:similarity(1+i,2,pi/3,i) Ex2:similarity(line(x=y,y=z),2,pi/3,point(-1,2,1)) Ex3: s:=similarity(1+i,2,pi/3);s(i) Ex4: s:=similarity(line(x=y,y=z),2,pi/3),s(point(-1,2,1)) - ''' return GiacMethods['similarity'](self,*args) @@ -15738,10 +14496,9 @@ cdef class GiacMethods_base: Help for simp2: simp2(Intg(A) or Poly(A),Intg(B) or Poly(B)) Returns the list [A/gcd(A,B),B/gcd(A,B)]. - See also: 1/ gcd + See also: 1/ gcd Ex1:simp2(12,18) Ex2:simp2(x^3-1,x^2-1) - ''' return GiacMethods['simp2'](self,*args) @@ -15755,7 +14512,6 @@ cdef class GiacMethods_base: Ex3:simplex_reduce([[-3,2],[1,1]],[3,4],[1,2]) Ex4:simplex_reduce([[-3,2,1,0,3],[1,1,0,1,4],[-1,-2,0,0,0]]) Ex5:simplex_reduce([[2,1,1,1,0,0,2],[1,2,3,0,1,0,5],[2,2,1,0,0,1,6],[-3,-1,-3,1,-1,2,0]]) - ''' return GiacMethods['simplex_reduce'](self,*args) @@ -15764,11 +14520,10 @@ cdef class GiacMethods_base: Help for simplifier: simplifier(Expr) Simplifies an expression. - See also: 1/ normal + See also: 1/ normal Ex1:simplifier(4*atan(1/5)-atan(1/239)) Ex2:simplifier(texpand((sin(3*x)+sin(7*x))/sin(5*x))) Ex3:simplifier(texpand((cos(3*x)+cos(7*x))/cos(5*x))) - ''' return GiacMethods['simplifier'](self,*args) @@ -15777,11 +14532,10 @@ cdef class GiacMethods_base: Help for simplify: simplify(Expr) Simplifies an expression. - See also: 1/ normal + See also: 1/ normal Ex1:simplify(4*atan(1/5)-atan(1/239)) Ex2:simplify(texpand((sin(3*x)+sin(7*x))/sin(5*x))) Ex3:simplify(texpand((cos(3*x)+cos(7*x))/cos(5*x))) - ''' return GiacMethods['simplify'](self,*args) @@ -15790,12 +14544,11 @@ cdef class GiacMethods_base: Help for simpson: simpson(Opt) Option of the area command. - See also: 1/ area + See also: 1/ area Ex1: area(x^2,x=0..1,5,simpson) Ex2: area(x^2,x=0..1,5,rombergt) Ex3: area(x^2,x=0..1,5,rombergm) Ex4:simpson(area(x^2,x=0..1,5,gauss15)) - ''' return GiacMethods['simpson'](self,*args) @@ -15804,10 +14557,9 @@ cdef class GiacMethods_base: Help for simult: simult(Mtrx(A),Mtrx(B)) Returns the matrix where the column of index k is solution of A*X=column of index k of B (=B[0..nr-1,k..k] with nr=number of rows of B). - See also: 1/ rref 2/ linsolve + See also: 1/ rref 2/ linsolve Ex1:simult([[3,1],[3,2]],[[-2],[2]]) Ex2:simult([[3,1],[3,2]],[[-2,1],[2,-1]]) - ''' return GiacMethods['simult'](self,*args) @@ -15816,10 +14568,9 @@ cdef class GiacMethods_base: Help for sin: sin(Expr or Opt) Sine or option of the convert or convertir command (id trigsin). - See also: 1/ asin 2/ convert 3/ trigsin + See also: 1/ asin 2/ convert 3/ trigsin Ex1:sin(0) Ex2: convert(cos(x)^4+sin(x)^2,sin) - ''' return GiacMethods['sin'](self,*args) @@ -15828,9 +14579,8 @@ cdef class GiacMethods_base: Help for sin2costan: sin2costan(Expr) Replaces sin(x) by cos(x)*tan(x) in the argument. - See also: 1/ tan2sincos 2/ cos2sintan 3/ tan2sincos2 4/ tan2cossin2 + See also: 1/ tan2sincos 2/ cos2sintan 3/ tan2sincos2 4/ tan2cossin2 Ex1:sin2costan(sin(x)) - ''' return GiacMethods['sin2costan'](self,*args) @@ -15839,9 +14589,8 @@ cdef class GiacMethods_base: Help for sinc: sinc(Expr(x)) Returns the value of the cardinal sine function at x. - See also: 1/ sin + See also: 1/ sin Ex1:sinc(pi*x) - ''' return GiacMethods['sinc'](self,*args) @@ -15850,11 +14599,10 @@ cdef class GiacMethods_base: Help for sincos: sincos(Expr or Opt) Transforms the complex exponential into sine and cosine (id exp2trig) or option of the convert or convertir command (id sincos). - See also: 1/ trig2trig 2/ trig2exp 3/ atrig2ln 4/ convert + See also: 1/ trig2trig 2/ trig2exp 3/ atrig2ln 4/ convert Ex1:sincos(exp(i*x)) Ex2:sincos(exp(-i*x)) Ex3: convert(exp(i*x),sincos) - ''' return GiacMethods['sincos'](self,*args) @@ -15863,7 +14611,7 @@ cdef class GiacMethods_base: Help for single_inter: single_inter(Curve,Curve,[Pnt(A)||LstPnt(L)]) Gives one of the points of intersection of 2 curves or surfaces (or the intersection near A or not in L). - See also: 1/ intersect 2/ head + See also: 1/ intersect 2/ head Ex1:single_inter(line(i,1-i),line(0,1)) Ex2:single_inter(line(i,1-i),circle(0,1)) Ex3:single_inter(line(i,1+2*i),circle(0,1),[point(i)]) @@ -15871,7 +14619,6 @@ cdef class GiacMethods_base: Ex5:single_inter(circle(1,sqrt(2)),circle(0,1)) Ex6:single_inter(plane(x=y),plane(y=z)) Ex7:single_inter(line(x=y+1,y=2*z),plane(y=z)) - ''' return GiacMethods['single_inter'](self,*args) @@ -15880,9 +14627,8 @@ cdef class GiacMethods_base: Help for sinh: sinh(Expr) Hyperbolic sine. - See also: 1/ asinh + See also: 1/ asinh Ex1:sinh(0) - ''' return GiacMethods['sinh'](self,*args) @@ -15891,9 +14637,8 @@ cdef class GiacMethods_base: Help for sizes: sizes(Lst or Str or Seq) Returns the list of sizes of a list of lists. - See also: 1/ size 2/ dim + See also: 1/ size 2/ dim Ex1:sizes([[1,2,3],[1,2],[1]]) - ''' return GiacMethods['sizes'](self,*args) @@ -15902,7 +14647,7 @@ cdef class GiacMethods_base: Help for slope: slope(Line||Pnt||Cplx,[Pnt||Cplx]) Returns the slope of the line defined in the argument or is an attribute of line. - See also: 1/ line 2/ tangent 3/ LinTan 4/ slopeatraw 5/ slopeat + See also: 1/ line 2/ tangent 3/ LinTan 4/ slopeatraw 5/ slopeat Ex1:slope(line(1,2i)) Ex2:slope(segment(1,2i)) Ex3:slope(1,2i) @@ -15911,7 +14656,6 @@ cdef class GiacMethods_base: Ex6:slope(tangent(plotfunc(sin(x)),pi/4)) Ex7:slope(LineTan(sin(x),pi/4)) Ex8: line(point(1,2),slope=-1) - ''' return GiacMethods['slope'](self,*args) @@ -15920,11 +14664,10 @@ cdef class GiacMethods_base: Help for slopeat: slopeat(Line, Pnt||Cplx(z0)) slopeat(d,z0) displays at the point(z0), with a legend, the value of the slope of the line or segment d. - See also: 1/ slope 2/ slopeatraw + See also: 1/ slope 2/ slopeatraw Ex1: A:=point(0);B:=point(1+i);slopeat(droite(A,B),(1+i)/2) Ex2: s:=segment(1-i,i);slopeat(s,point(0.4)) Ex3: t:=tangent(plotfunc(sin(x)),pi/4);slopeat(t,0) - ''' return GiacMethods['slopeat'](self,*args) @@ -15933,12 +14676,11 @@ cdef class GiacMethods_base: Help for slopeatraw: slopeatraw(Line, Pnt||Cplx(z0)) slopeatraw(d,z0) displays at point(z0), the value of the slope of the line or segment d. - See also: 1/ slope 2/ slopeat + See also: 1/ slope 2/ slopeat Ex1: A:=point(0);B:=point(1+i);slopeatraw(droite(A,B),(1+i)/2) Ex2: s:=segment(1-i,i);slopeatraw(s,point(0.4)) Ex3:slopeatraw(tangent(plotfunc(sin(x)),pi/4),0) Ex4:slopeatraw((LineTan sin(x),pi/4),i) - ''' return GiacMethods['slopeatraw'](self,*args) @@ -15947,10 +14689,9 @@ cdef class GiacMethods_base: Help for smith: smith(Mtrx(A)) Smith normal form of a matrix with polynomial coefficients : returns U,D,V such that U and V are invertible, D is diagonal, and U*A*V=D. - See also: 1/ hermite 2/ ismith 3/ ihermite + See also: 1/ hermite 2/ ismith 3/ ihermite Ex1: n:=10; A:=ranm(n,n) % 17; U,D,V:=smith(x*idn(n)-A);normal(U*(x*idn(n)-A)*V-D); diag(D); Ex2: GF(3,5,g); n:=3; A:=ranm(n,n,g); U,D,V:=smith(x*idn(n)-A);normal(U*(x*idn(n)-A)*V-D); diag(D); - ''' return GiacMethods['smith'](self,*args) @@ -15959,11 +14700,10 @@ cdef class GiacMethods_base: Help for smod: smod(Intg,Intg) Returns the Euclidean symmetric remainder of two integers. - See also: 1/ irem 2/ iquo 3/ mod 4/ fracmod + See also: 1/ irem 2/ iquo 3/ mod 4/ fracmod Ex1:smod(8,3) Ex2:smod(10,4) Ex3:smod(11,7) - ''' return GiacMethods['smod'](self,*args) @@ -15972,12 +14712,11 @@ cdef class GiacMethods_base: Help for snedecor: snedecor(Intg(n),Intg(m),Real(x0)) Returns the probability density of the Fisher-Snedecor law (n and m are the numbers of degrees of freedom). - See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm + See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm Ex1:snedecor(4,10,2.1) Ex2:snedecor(4,4,2.1) Ex3: randvector(5,fisher,4,6) Ex4: ranm(2,3,fisher,4,6) - ''' return GiacMethods['snedecor'](self,*args) @@ -15986,10 +14725,9 @@ cdef class GiacMethods_base: Help for snedecor_cdf: snedecor_cdf(Intg(n),Intg(m),Real(x0)) Returns the probability that a Fisher-Snedecor random variable is less than x0 (n and m are the numbers of degrees of freedom). - See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd + See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd Ex1:snedecor_cdf(4,4,2.1) Ex2:snedecor_cdf(4,10,3.5) - ''' return GiacMethods['snedecor_cdf'](self,*args) @@ -15998,10 +14736,9 @@ cdef class GiacMethods_base: Help for snedecor_icdf: snedecor_icdf(Intg(n),Intg(m),Real(p)) Returns h such as the probability that a Fisher-Snedecor random variable is less than h is p (n and m are the numbers of degrees of freedom and 0<=p<=1). - See also: 1/ fisher_cdf 2/ fisherd + See also: 1/ fisher_cdf 2/ fisherd Ex1:snedecor_icdf(4,10,0.95) Ex2:snedecor_icdf(4,10,0.05) - ''' return GiacMethods['snedecor_icdf'](self,*args) @@ -16010,12 +14747,11 @@ cdef class GiacMethods_base: Help for snedecord: snedecord(Intg(n),Intg(m),Real(x0)) Returns the probability density of the Fisher-Snedecor law (n and m are the numbers of degrees of freedom). - See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm + See also: 1/ fisher_cdf 2/ fisher_icdf 3/ randvector 4/ ranm Ex1:snedecord(4,10,2.1) Ex2:snedecord(4,4,2.1) Ex3: randvector(5,fisher,4,6) Ex4: ranm(2,3,fisher,4,6) - ''' return GiacMethods['snedecord'](self,*args) @@ -16024,10 +14760,9 @@ cdef class GiacMethods_base: Help for snedecord_cdf: snedecord_cdf(Intg(n),Intg(m),Real(x0)) Returns the probability that a Fisher-Snedecor random variable is less than x0 (n and m are the numbers of degrees of freedom). - See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd + See also: 1/ UTPF 2/ fisher_icdf 3/ fisherd Ex1:snedecord_cdf(4,4,2.1) Ex2:snedecord_cdf(4,10,3.5) - ''' return GiacMethods['snedecord_cdf'](self,*args) @@ -16036,10 +14771,9 @@ cdef class GiacMethods_base: Help for snedecord_icdf: snedecord_icdf(Intg(n),Intg(m),Real(p)) Returns h such as the probability that a Fisher-Snedecor random variable is less than h is p (n and m are the numbers of degrees of freedom and 0<=p<=1). - See also: 1/ fisher_cdf 2/ fisherd + See also: 1/ fisher_cdf 2/ fisherd Ex1:snedecord_icdf(4,10,0.95) Ex2:snedecord_icdf(4,10,0.05) - ''' return GiacMethods['snedecord_icdf'](self,*args) @@ -16048,10 +14782,9 @@ cdef class GiacMethods_base: Help for solid_line: solid_line(Opt) Option of the display command for a line. - See also: 1/ display + See also: 1/ display Ex1: display(line(y=x),green+dash_line+line_width_2) Ex2: d:=display(line(2+i,1),cap_round_line) - ''' return GiacMethods['solid_line'](self,*args) @@ -16060,12 +14793,11 @@ cdef class GiacMethods_base: Help for solve: solve(Expr,[Var]) Solves a (or a set of) polynomial equation. - See also: 1/ linsolve 2/ proot 3/ fsolve 4/ csolve 5/ nSolve + See also: 1/ linsolve 2/ proot 3/ fsolve 4/ csolve 5/ nSolve Ex1:solve(x^2-3=1) Ex2:solve(x^3-3*y,y) Ex3:solve([y-z=0,z-x=0,x-y=0,x-1+y+z=0],[x,y,z]) Ex4:solve([x^2-y^2=0,x^2-z^2=0],[x,y,z]) - ''' return GiacMethods['solve'](self,*args) @@ -16074,7 +14806,7 @@ cdef class GiacMethods_base: Help for somme: somme(Expr,Var,VarMin(a),VarMax(b),[VarStep(p)]) Discrete sum (with 2 or 4 arguments return then sum from a to b if a<=b or of the opposite of the sum from b+1 to a-1 if a>b+1 or 0 if a=b+1) or the discrete primitive or sum of the elements of a list or a sequence. - See also: 1/ + + See also: 1/ + Ex1:somme(1/n^2,n,1,17) Ex2:somme(1/n^2,n=1..17) Ex3:somme(1/n^2,n,17,1) @@ -16085,7 +14817,6 @@ cdef class GiacMethods_base: Ex8:somme([[1,2,3,4,5,6,7,8,9],[1,2,3,4,5,6,7,8,9]]) Ex9:somme(1/(x*(x+1)),x) Ex10:somme(cos(n*x),n) - ''' return GiacMethods['somme'](self,*args) @@ -16094,10 +14825,9 @@ cdef class GiacMethods_base: Help for sommet: sommet(Op or Fnct) Returns the top of an operator. - See also: 1/ feuille 2/ quote + See also: 1/ feuille 2/ quote Ex1:sommet(quote(gcd(45,123))) Ex2:sommet('gcd(45,123)') - ''' return GiacMethods['sommet'](self,*args) @@ -16106,13 +14836,12 @@ cdef class GiacMethods_base: Help for sort: sort(LstReal or Seq [Fnc]) Returns the sorted list (or sequence) with increasing order according to the second argument which defines a weak strict ordering or sorts and collects equal terms in sums and products. - See also: 1/ SortA 2/ SortD + See also: 1/ SortA 2/ SortD Ex1:sort([3,2,2,4,1,0]) Ex2:sort(3,2.1,2,4,1,0) Ex3:sort([3,4,2],(x,y)->x>y) Ex4:sort([[1,2],[2,3],[4,3]],(x,y)->when(x[1]==y[1],x[0]>y[0],x[1]>y[1])) Ex5:sort(y*x*2+x*y) - ''' return GiacMethods['sort'](self,*args) @@ -16121,11 +14850,10 @@ cdef class GiacMethods_base: Help for sorta: sorta(LstReal||Seq×||Mtrx) Sorts the list in increasing order or sorts the columns of the matrix so the first row is in increasing order. - See also: 1/ SortA 2/ sortd 3/ sort + See also: 1/ SortA 2/ sortd 3/ sort Ex1:sorta(3,4,2) Ex2:sorta([3,4,2]) Ex3:sorta([[3,4,2],[6,4,5]]) - ''' return GiacMethods['sorta'](self,*args) @@ -16134,11 +14862,10 @@ cdef class GiacMethods_base: Help for sortd: sortd(LstReal||Seq||Mtrx) Sorts the list in decreasing order or sorts the columns of the matrix so the first row is in decreasing order. - See also: 1/ SortD 2/ sorta 3/ sort + See also: 1/ SortD 2/ sorta 3/ sort Ex1:sortd(3,4,2) Ex2:sortd([3,4,2]) Ex3:sortd([[3,4,2],[6,4,5]]) - ''' return GiacMethods['sortd'](self,*args) @@ -16147,13 +14874,12 @@ cdef class GiacMethods_base: Help for sorted: sorted(LstReal or Seq [Fnc]) Returns the sorted list (or sequence) with increasing order according to the second argument which defines a weak strict ordering or sorts and collects equal terms in sums and products. - See also: 1/ SortA 2/ SortD + See also: 1/ SortA 2/ SortD Ex1:sorted([3,2,2,4,1,0]) Ex2:sorted(3,2.1,2,4,1,0) Ex3:sorted([3,4,2],(x,y)->x>y) Ex4:sorted([[1,2],[2,3],[4,3]],(x,y)->when(x[1]==y[1],x[0]>y[0],x[1]>y[1])) Ex5:sorted(y*x*2+x*y) - ''' return GiacMethods['sorted'](self,*args) @@ -16162,10 +14888,9 @@ cdef class GiacMethods_base: Help for soundsec: soundsec(Intg(n),[Intg(N)]) Generates a vector coding n seconds of time/N (default N=44100). - See also: 1/ readwav 2/ writewav 3/ playsnd + See also: 1/ readwav 2/ writewav 3/ playsnd Ex1:soundsec(1) Ex2:soundsec(1,22100) - ''' return GiacMethods['soundsec'](self,*args) @@ -16174,10 +14899,9 @@ cdef class GiacMethods_base: Help for spanning_tree: spanning_tree(Graph(G),[Vrtx(r)]) Returns a spanning tree of undirected graph G [with the vertex r as the root node]. - See also: 1/ number_of_spanning_trees 2/ minimal_spanning_tree + See also: 1/ number_of_spanning_trees 2/ minimal_spanning_tree Ex1:spanning_tree(graph("petersen")) Ex2:spanning_tree(graph("petersen"),5) - ''' return GiacMethods['spanning_tree'](self,*args) @@ -16186,10 +14910,9 @@ cdef class GiacMethods_base: Help for sphere: sphere((Pnt or Vect),(Pnt or Real)) sphere(A,B) (resp sphere(A,r)) draws the sphere with diameter AB (resp center A and radius r) in 3D space. - See also: 1/ circle + See also: 1/ circle Ex1:sphere([0,0,0],[2,2,2]) Ex2:sphere([1,1,1],1) - ''' return GiacMethods['sphere'](self,*args) @@ -16198,9 +14921,8 @@ cdef class GiacMethods_base: Help for spline: spline(Lst(lx),Lst(ly),Var(x),Intg(d)) Natural spline through the points given by the lx and ly lists, variable x, degree d. - See also: 1/ lagrange + See also: 1/ lagrange Ex1:spline([0,1,2],[1,3,0],x,3) - ''' return GiacMethods['spline'](self,*args) @@ -16209,10 +14931,9 @@ cdef class GiacMethods_base: Help for split: split(Expr(Xpr),Lst(var1,var2)) Splits the two variables var1,var2 of the expression Xpr (without denominator) or returns [0]. - See also: 1/ factor + See also: 1/ factor Ex1:split(x^3*y^2-y^2+x^3-1,[x,y]) Ex2:split(x^3*y^2-y^2+x^3+1,[x,y]) - ''' return GiacMethods['split'](self,*args) @@ -16221,8 +14942,7 @@ cdef class GiacMethods_base: Help for spring: spring(Opt) Option for the draw_graph command. - See also: 1/ planar 2/ tree 3/ draw_graph - + See also: 1/ planar 2/ tree 3/ draw_graph ''' return GiacMethods['spring'](self,*args) @@ -16231,10 +14951,9 @@ cdef class GiacMethods_base: Help for sq: sq(Seq) Is the name of the function (ℝ^n -> ℝ)=sum of the squares of the arguments. - See also: 1/ sqrt + See also: 1/ sqrt Ex1:sq(5) Ex2:sq(1,2,3) - ''' return GiacMethods['sq'](self,*args) @@ -16243,10 +14962,9 @@ cdef class GiacMethods_base: Help for sqrfree: sqrfree(Expr) Factorization of the its argument gathering the terms with the same exponent. - See also: 1/ factor + See also: 1/ factor Ex1:sqrfree(x^4-2*x^2+1) Ex2:sqrfree((x-2)^7*(x+2)^7*(x^4-2*x^2+1)) - ''' return GiacMethods['sqrfree'](self,*args) @@ -16255,10 +14973,9 @@ cdef class GiacMethods_base: Help for sqrt: sqrt(Expr) Square root. - See also: 1/ surd 2/ ^ + See also: 1/ surd 2/ ^ Ex1:sqrt(50) Ex2:sqrt(x^2) - ''' return GiacMethods['sqrt'](self,*args) @@ -16267,12 +14984,11 @@ cdef class GiacMethods_base: Help for square: square((Pnt(A) or Cplx),(Pnt(B) or Cplx),[Pnt(P),Var(C),Var(D)]) Returns and draws the square of side AB (ABCD is direct) (in the plane ABP). - See also: 1/ rhombus 2/ quadrilateral + See also: 1/ rhombus 2/ quadrilateral Ex1:square(i,1+i) Ex2:square(i,1+i,C,D) Ex3:square(point(0,0,0),point(3,3,3),point(0,0,3)) Ex4:square(point(0,0,0),point(3,3,3),point(0,0,3),C,D) - ''' return GiacMethods['square'](self,*args) @@ -16281,10 +14997,9 @@ cdef class GiacMethods_base: Help for square_point: square_point(Opt) Option of the display command for a point. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),point_point) Ex2: F:=display(point(2+1.5*i),rhombus_point) - ''' return GiacMethods['square_point'](self,*args) @@ -16293,10 +15008,9 @@ cdef class GiacMethods_base: Help for srand: srand() srand returns an integer and initializes the sequence of random numbers. - See also: 1/ RandSeed + See also: 1/ RandSeed Ex1:srand(12) Ex2: srand - ''' return GiacMethods['srand'](self,*args) @@ -16305,9 +15019,8 @@ cdef class GiacMethods_base: Help for sst: sst(NULL) Steps 1 instruction. - See also: 1/ + See also: 1/ Ex1:sst() - ''' return GiacMethods['sst'](self,*args) @@ -16316,9 +15029,8 @@ cdef class GiacMethods_base: Help for sst_in: sst_in(NULL) Enters into a function in step-by-step mode. - See also: 1/ + See also: 1/ Ex1:sst_in() - ''' return GiacMethods['sst_in'](self,*args) @@ -16327,9 +15039,8 @@ cdef class GiacMethods_base: Help for st_ordering: st_ordering(Graph(G),Vrtx(s),Vrtx(t)) Returns ST numbering for the biconnected graph G with source s and sink (target) t. - See also: 1/ is_biconnected + See also: 1/ is_biconnected Ex1:st_ordering(graph("petersen"),1,2) - ''' return GiacMethods['st_ordering'](self,*args) @@ -16338,9 +15049,8 @@ cdef class GiacMethods_base: Help for star_graph: star_graph(Intg(n)) Returns the complete bipartite graph complete_graph(1,n). - See also: 1/ complete_graph 2/ wheel_graph + See also: 1/ complete_graph 2/ wheel_graph Ex1:star_graph(5) - ''' return GiacMethods['star_graph'](self,*args) @@ -16349,10 +15059,9 @@ cdef class GiacMethods_base: Help for star_point: star_point(Opt) Option of the display command for a point. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),point_point) Ex2: F:=display(point(2+1.5*i),rhombus_point) - ''' return GiacMethods['star_point'](self,*args) @@ -16361,11 +15070,10 @@ cdef class GiacMethods_base: Help for stdDev: stdDev(Lst||Mtrx,[Lst]) Returns an unbiased estimate of the population standard deviation of the sample (first argument) with an optional list of weight as second argument. - See also: 1/ mean 2/ stddev + See also: 1/ mean 2/ stddev Ex1:stdDev([1,2,3]) Ex2:stdDev([1,2,3],[1,2,1]) Ex3:stdDev([[1,2,3],[5,6,7]]) - ''' return GiacMethods['stdDev'](self,*args) @@ -16374,11 +15082,10 @@ cdef class GiacMethods_base: Help for stddev: stddev(Lst||Mtrx,[Lst]) Returns the standard deviation of the elements of its argument with an optional second argument as weight or the list of standard deviations of the columns of a matrix. - See also: 1/ mean 2/ variance 3/ stddevp + See also: 1/ mean 2/ variance 3/ stddevp Ex1:stddev([1,2,3]) Ex2:stddev([1,2,3],[1,2,1]) Ex3:stddev([[1,2,3],[5,6,7]]) - ''' return GiacMethods['stddev'](self,*args) @@ -16387,11 +15094,10 @@ cdef class GiacMethods_base: Help for stddevp: stddevp(Lst||Mtrx,[Lst]) Returns an unbiased estimate of the population standard deviation of the sample (first argument) with an optional list of weight as second argument. - See also: 1/ mean 2/ stddev + See also: 1/ mean 2/ stddev Ex1:stddevp([1,2,3]) Ex2:stddevp([1,2,3],[1,2,1]) Ex3:stddevp([[1,2,3],[5,6,7]]) - ''' return GiacMethods['stddevp'](self,*args) @@ -16400,14 +15106,13 @@ cdef class GiacMethods_base: Help for steffenson_solver: steffenson_solver(Opt) Argument for fsolve giving the method for solving a numerical equation. - See also: 1/ fsolve + See also: 1/ fsolve Ex1: fsolve(cos(x)=x,x,0..1,bisection_solver) Ex2: fsolve(cos(x)=x,x,0..1,brent_solver) Ex3: fsolve(cos(x)=x,x,0..1,falsepos_solver) Ex4: fsolve(cos(x)=x,x,0,newton_solver) Ex5: fsolve(cos(x)=x,x,0,secant_solver) Ex6: fsolve(cos(x)=x,x,0,steffenson_solver) - ''' return GiacMethods['steffenson_solver'](self,*args) @@ -16416,9 +15121,8 @@ cdef class GiacMethods_base: Help for stereo2mono: stereo2mono(Lst(clip)) Returns an audio clip with all channels in the input clip downmixed to a single one. - See also: 1/ channel_data 2/ mean 3/ createwav + See also: 1/ channel_data 2/ mean 3/ createwav Ex1:stereo2mono(readwav("/some/file")) - ''' return GiacMethods['stereo2mono'](self,*args) @@ -16427,12 +15131,11 @@ cdef class GiacMethods_base: Help for str: str(Expr or Opt) Returns the evaluated expression as a string or is an option of the convert or convertir command (id string). - See also: 1/ expr 2/ format 3/ convert + See also: 1/ expr 2/ format 3/ convert Ex1:str(1.23) Ex2:str(a:=12) Ex3:str(quote(a:=12)) Ex4: convert(quote(a:=12),string) - ''' return GiacMethods['str'](self,*args) @@ -16441,9 +15144,8 @@ cdef class GiacMethods_base: Help for strongly_connected_components: strongly_connected_components(Graph(G)) Returns the list of strongly connected components in digraph G. - See also: 1/ connected_components 2/ is_connected 3/ is_strongly_connected + See also: 1/ connected_components 2/ is_connected 3/ is_strongly_connected Ex1:strongly_connected_components(digraph([1,2,3],%{[1,2],[1,3],[2,3],[3,2]%})) - ''' return GiacMethods['strongly_connected_components'](self,*args) @@ -16452,10 +15154,9 @@ cdef class GiacMethods_base: Help for student: student(Intg(n),Real(x0)) Returns the probability density of the Student law (n is the number of degrees of freedom). - See also: 1/ student_cdf 2/ student_icdf + See also: 1/ student_cdf 2/ student_icdf Ex1:student(3,5.2) Ex2:student(1,5.2) - ''' return GiacMethods['student'](self,*args) @@ -16464,10 +15165,9 @@ cdef class GiacMethods_base: Help for student_cdf: student_cdf(Intg(n),Real(x0)) Returns the probability that a Student random variable is less than x0 (n is the number of degrees of freedom). - See also: 1/ UTPT 2/ student_icdf 3/ studentd + See also: 1/ UTPT 2/ student_icdf 3/ studentd Ex1:student_cdf(3,2.35) Ex2:student_cdf(3,-3.2) - ''' return GiacMethods['student_cdf'](self,*args) @@ -16476,10 +15176,9 @@ cdef class GiacMethods_base: Help for student_icdf: student_icdf(Intg(n),Real(p)) Returns h such as the probability that a Student random variable is less than h is p (n is the number of degrees of freedom and 0<=p<=1). - See also: 1/ student_cdf 2/ studentd + See also: 1/ student_cdf 2/ studentd Ex1:student_icdf(3,0.95) Ex2:student_icdf(3,0.05) - ''' return GiacMethods['student_icdf'](self,*args) @@ -16488,10 +15187,9 @@ cdef class GiacMethods_base: Help for studentd: studentd(Intg(n),Real(x0)) Returns the probability density of the Student law (n is the number of degrees of freedom). - See also: 1/ student_cdf 2/ student_icdf + See also: 1/ student_cdf 2/ student_icdf Ex1:studentd(3,5.2) Ex2:studentd(1,5.2) - ''' return GiacMethods['studentd'](self,*args) @@ -16500,10 +15198,9 @@ cdef class GiacMethods_base: Help for studentt: studentt(Lst,Real,[Real],Fnc,[Real]) T-Test/Student law: arg1=[success,trial] or [mean,sample size] or data, arg2=proportion or data, arg3 optional if data=sigma, arg4 alternative '!=' or '>' or '<', arg5 optional alpha confidence level. - See also: 1/ normalt 2/ chisquaret 3/ kolmogorovt + See also: 1/ normalt 2/ chisquaret 3/ kolmogorovt Ex1:studentt([10,20],.5,.02,'!=',0.1) Ex2:studentt([0.48,20],0.5,0.1,'<') - ''' return GiacMethods['studentt'](self,*args) @@ -16512,13 +15209,12 @@ cdef class GiacMethods_base: Help for sturm: sturm(Poly,[Var],[Cplx(a)],[Cplx(b)]) Sturm sequence corresponding to a polynomial or number of sign changes of this polynomial in ]a;b]. - See also: 1/ sturmseq 2/ sturmab + See also: 1/ sturmseq 2/ sturmab Ex1:sturm(x^3-1,x) Ex2:sturm(x^5-x^3,x) Ex3:sturm((x^5-x^3)/(x+2),x) Ex4:sturm(x^5-x^3,x,-2,5) Ex5:sturm(x^3-1,x,-2-i,5+3i) - ''' return GiacMethods['sturm'](self,*args) @@ -16527,10 +15223,9 @@ cdef class GiacMethods_base: Help for sturmab: sturmab(Poly,Var,Cplx(a),Cplx(b)) Number of sign changes of a polynomial in ]a;b] or of complex roots in a..b if a or b is non-real. - See also: 1/ sturm 2/ sturmseq 3/ realroot + See also: 1/ sturm 2/ sturmseq 3/ realroot Ex1:sturmab(x^3-1,x,-2,5) Ex2:sturmab(x^3-1,x,-2-i,5+3i) - ''' return GiacMethods['sturmab'](self,*args) @@ -16539,11 +15234,10 @@ cdef class GiacMethods_base: Help for sturmseq: sturmseq(Poly,[Var]) Sturm sequence corresponding to a polynomial or to a rational fraction. - See also: 1/ sturm 2/ sturmab + See also: 1/ sturm 2/ sturmab Ex1:sturmseq(x^3-1,x) Ex2:sturmseq(x^5-x^3,x) Ex3:sturmseq((x^5-x^3)/(x+2),x) - ''' return GiacMethods['sturmseq'](self,*args) @@ -16552,10 +15246,9 @@ cdef class GiacMethods_base: Help for style: style(Opt) Local option (Maple compatibility) of a graphic command to plot a line with dots with style=point. - See also: 1/ line_width + See also: 1/ line_width Ex1: segment(0,point(1,1),style=point) Ex2: line(y=x,style=point,display=green+line_width_2) - ''' return GiacMethods['style'](self,*args) @@ -16564,9 +15257,8 @@ cdef class GiacMethods_base: Help for subMat: subMat(Mtrx(A),Intg(n1),Intg(n2),Intg(n3),Intg(n4).) Extracts a sub matrix with first element=A[n1,n2] and last element=A[n3,n4]. - See also: 1/ mid + See also: 1/ mid Ex1:subMat([[1,2],[3,4],[5,6]],1,0,2,1) - ''' return GiacMethods['subMat'](self,*args) @@ -16575,9 +15267,8 @@ cdef class GiacMethods_base: Help for subdivide_edges: subdivide_edges(Graph(G),Lst(E),[Intg(r)]) Inserts r (by default 1) new vertices to each edge/arc in G contained in the list E (which may be a single edge/arc) and returns the modified copy of G. New vertices are labelled with smallest available integers. - See also: 1/ edges + See also: 1/ edges Ex1:subdivide_edges(complete_graph(2,3),[[1,3],[1,4]],2) - ''' return GiacMethods['subdivide_edges'](self,*args) @@ -16586,9 +15277,8 @@ cdef class GiacMethods_base: Help for subgraph: subgraph(Graph(G),Lst(E)) Returns the subgraph of G defined by the edges in list E. - See also: 1/ induced_subgraph 2/ highlight_subgraph + See also: 1/ induced_subgraph 2/ highlight_subgraph Ex1:subgraph(complete_graph(5),[[1,2],[2,3],[3,4],[4,1]]) - ''' return GiacMethods['subgraph'](self,*args) @@ -16597,11 +15287,10 @@ cdef class GiacMethods_base: Help for subs: subs(Expr or Var=value,Var=value or Expr) Equivalent of subst except in maple_mode where the arguments are switched over, in maple_mode choose the second example. - See also: 1/ subst 2/ maple_mode 3/ algsubs 4/ () + See also: 1/ subst 2/ maple_mode 3/ algsubs 4/ () Ex1:subs(1/(4+x^2),x=2) Ex2:subs(x=2,1/(4+x^2)) Ex3: f:=1/(4+x^2);f(x=2) - ''' return GiacMethods['subs'](self,*args) @@ -16614,7 +15303,6 @@ cdef class GiacMethods_base: Ex2:subsop([[1,2],[3,4]],[1,1]=5) Ex3:subsop([[1,2],[3,4]],1=[10,8]) Ex4:subsop([0,1,2,3],'1=NULL') - ''' return GiacMethods['subsop'](self,*args) @@ -16623,7 +15311,7 @@ cdef class GiacMethods_base: Help for subst: subst(Expr,Var(v)=value(a)) Substitutes a value for a variable in an expression. - See also: 1/ eval 2/ algsubs 3/ subs 4/ () + See also: 1/ eval 2/ algsubs 3/ subs 4/ () Ex1:subst(1/(4+x^2),x=2) Ex2:subst(1/(x^2+y^2),x=2,y=3) Ex3:subst(1/(x^2+y^2+z^2),[x=2,y=3,z=1]) @@ -16631,7 +15319,6 @@ cdef class GiacMethods_base: Ex5:subst('integrate(sin(x^2)*x,x)',x=sqrt(t)) Ex6:subst('sum(x^(n+1)/((n+p+1)*(n+1)),n,0,inf)',n=k-1) Ex7: f:=1/(x^2+y^2;f(x=2,y=3) - ''' return GiacMethods['subst'](self,*args) @@ -16640,7 +15327,7 @@ cdef class GiacMethods_base: Help for substituer: substituer(Expr,Var(v)=value(a)) Substitutes a value for a variable in an expression. - See also: 1/ eval 2/ algsubs 3/ subs 4/ () + See also: 1/ eval 2/ algsubs 3/ subs 4/ () Ex1:substituer(1/(4+x^2),x=2) Ex2:substituer(1/(x^2+y^2),x=2,y=3) Ex3:substituer(1/(x^2+y^2+z^2),[x=2,y=3,z=1]) @@ -16648,7 +15335,6 @@ cdef class GiacMethods_base: Ex5:substituer('integrate(sin(x^2)*x,x)',x=sqrt(t)) Ex6:substituer('sum(x^(n+1)/((n+p+1)*(n+1)),n,0,inf)',n=k-1) Ex7: f:=1/(x^2+y^2;f(x=2,y=3) - ''' return GiacMethods['substituer'](self,*args) @@ -16657,12 +15343,11 @@ cdef class GiacMethods_base: Help for subtype: subtype(Expr) Returns 1 for a sequence,2 for a set, 10 for a polynomial and 0 otherwise. - See also: 1/ DOM_LIST 2/ type + See also: 1/ DOM_LIST 2/ type Ex1:subtype(1,2,3) Ex2:subtype(set[1,2,3]) Ex3:subtype(poly1[1,2,3]) Ex4:subtype([1,2,3]) - ''' return GiacMethods['subtype'](self,*args) @@ -16671,7 +15356,7 @@ cdef class GiacMethods_base: Help for sum: sum(Expr,Var,VarMin(a),VarMax(b),[VarStep(p)]) Discrete sum (with 2 or 4 arguments return then sum from a to b if a<=b or of the opposite of the sum from b+1 to a-1 if a>b+1 or 0 if a=b+1) or the discrete primitive or sum of the elements of a list or a sequence. - See also: 1/ + + See also: 1/ + Ex1:sum(1/n^2,n,1,17) Ex2:sum(1/n^2,n=1..17) Ex3:sum(1/n^2,n,17,1) @@ -16682,7 +15367,6 @@ cdef class GiacMethods_base: Ex8:sum([[1,2,3,4,5,6,7,8,9],[1,2,3,4,5,6,7,8,9]]) Ex9:sum(1/(x*(x+1)),x) Ex10:sum(cos(n*x),n) - ''' return GiacMethods['sum'](self,*args) @@ -16691,11 +15375,10 @@ cdef class GiacMethods_base: Help for sum_riemann: sum_riemann(Expr(Xpr),Lst(var1,var2)) Returns an equivalent when var1=+infinity of the sum of Xpr(var1,var2) for var2 from 1 to var1 when the sum is a Riemann sum. - See also: 1/ + See also: 1/ Ex1:sum_riemann(1/(n+k),[n,k]) Ex2:sum_riemann(n/(n^2+k),[n,k]) Ex3:sum_riemann(n/(n^2+k^2),[n,k]) - ''' return GiacMethods['sum_riemann'](self,*args) @@ -16704,12 +15387,11 @@ cdef class GiacMethods_base: Help for suppress: suppress(Vect(L)||Str(l),Intg(n)) Returns L without the element of index n; L:=suppress(L,n) or L.suppress(n). - See also: 1/ tail 2/ mid 3/ remove 4/ insert + See also: 1/ tail 2/ mid 3/ remove 4/ insert Ex1:suppress([0,1,2,3],2) Ex2:suppress("0123",2) Ex3: L:=[0,1,2,3];L:=suppress(L,2) Ex4: L:=[0,1,2,3];L.suppress(2) - ''' return GiacMethods['suppress'](self,*args) @@ -16718,10 +15400,9 @@ cdef class GiacMethods_base: Help for surd: surd(Expr,Intg(n)) Power 1/n. - See also: 1/ sqrt 2/ ^ + See also: 1/ sqrt 2/ ^ Ex1:surd(8,3) Ex2:surd(-8,3) - ''' return GiacMethods['surd'](self,*args) @@ -16731,7 +15412,6 @@ cdef class GiacMethods_base: svd(Mtrx(A)) For a square numerical real matrix A, returns U orthogonal, S vector of singular values, Q orthogonal such that A=U*diag(S)*tran(Q). Ex1:svd([[1,2],[3,4]]) - ''' return GiacMethods['svd'](self,*args) @@ -16740,9 +15420,8 @@ cdef class GiacMethods_base: Help for swapcol: swapcol(Mtrx(A),Intg(n1),Intg(n2)) Returns the matrix obtained from A by swapping the n1-th column and the n2-th column. - See also: 1/ rowSwap + See also: 1/ rowSwap Ex1:swapcol([[1,2],[3,4],[5,6]],0,1) - ''' return GiacMethods['swapcol'](self,*args) @@ -16751,9 +15430,8 @@ cdef class GiacMethods_base: Help for swaprow: swaprow(Mtrx(A),Intg(n1),Intg(n2)) Returns the matrix obtained from A by swapping the n1-th row and the n2-th row. - See also: 1/ rowAdd 2/ colSwap + See also: 1/ rowAdd 2/ colSwap Ex1:swaprow([[1,2],[3,4],[5,6]],1,2) - ''' return GiacMethods['swaprow'](self,*args) @@ -16762,11 +15440,10 @@ cdef class GiacMethods_base: Help for switch_axes: switch_axes([Intg(0 or 1)]) switch_axes() puts or erases the axes of the graphic-screen. - See also: 1/ gl_showaxes 2/ axes + See also: 1/ gl_showaxes 2/ axes Ex1:switch_axes() Ex2:switch_axes(0) Ex3:switch_axes(1) - ''' return GiacMethods['switch_axes'](self,*args) @@ -16775,10 +15452,9 @@ cdef class GiacMethods_base: Help for sylvester: sylvester(Poly,Poly,Var) Sylvester matrix of two polynomials. - See also: 1/ resultant + See also: 1/ resultant Ex1:sylvester(x^2-1,x^3-1,x) Ex2:sylvester(x^3-p*x+q,3*x^2-p,x) - ''' return GiacMethods['sylvester'](self,*args) @@ -16787,14 +15463,13 @@ cdef class GiacMethods_base: Help for symb2poly: symb2poly(Expr, LstVar or [Var]) Returns the coefficients of a polynomial with respect to the 2nd argument or if the second argument is a list the internal format of the polynomial. - See also: 1/ poly2symb 2/ r2e + See also: 1/ poly2symb 2/ r2e Ex1:symb2poly(x*3+2.1) Ex2:symb2poly(3*x*y+2*y+1,y) Ex3:symb2poly(3*x*y+2*y+1,x,y) Ex4:symb2poly(3*x*y+2*y+1,[x,y]) Ex5:symb2poly(-x^4+x*3*y+2+y^2*z,[x,y,z]) Ex6:symb2poly(-x^4+x*3*y+2+y^2*z,[x,y,z]) - ''' return GiacMethods['symb2poly'](self,*args) @@ -16803,12 +15478,11 @@ cdef class GiacMethods_base: Help for symbol: symbol(Opt) DOM_SYMBOLIC or symbol is the type of a symbolic variable, as returned by the type command. It is also an option of the assume command. - See also: 1/ type 2/ assume 3/ DOM_INT 4/ DOM_FLOAT + See also: 1/ type 2/ assume 3/ DOM_INT 4/ DOM_FLOAT Ex1: assume(a,symbol) Ex2: assume(a,DOM_SYMBOLIC) Ex3: a:=sqrt(2);type(a) Ex4: type(2x+1) - ''' return GiacMethods['symbol'](self,*args) @@ -16817,9 +15491,8 @@ cdef class GiacMethods_base: Help for syst2mat: syst2mat(LstLinEq,LstVar) Returns the matrix M=A|(-b) associate to the system Y=AX+b. - See also: 1/ linsolve 2/ rref + See also: 1/ linsolve 2/ rref Ex1:syst2mat([x-y=1,x+2*y],[x,y]) - ''' return GiacMethods['syst2mat'](self,*args) @@ -16828,9 +15501,8 @@ cdef class GiacMethods_base: Help for tCollect: tCollect(Expr) Collects trigonometric expressions. - See also: 1/ texpand 2/ tlin + See also: 1/ texpand 2/ tlin Ex1:tCollect(sin(x)+cos(x)) - ''' return GiacMethods['tCollect'](self,*args) @@ -16839,11 +15511,10 @@ cdef class GiacMethods_base: Help for tExpand: tExpand(Expr) Expands transcendental expressions. - See also: 1/ tcollect 2/ tlin 3/ lin 4/ trigexpand + See also: 1/ tcollect 2/ tlin 3/ lin 4/ trigexpand Ex1:tExpand(sin(2*x)+exp(x+y)) Ex2:tExpand(cos(x+y)) Ex3:tExpand(cos(3*x)) - ''' return GiacMethods['tExpand'](self,*args) @@ -16852,11 +15523,10 @@ cdef class GiacMethods_base: Help for table: table(SeqEqual(index=value)) Defines an array where the indices are strings or real numbers or defines a table with a matrix. - See also: 1/ matrix 2/ convert 3/ array + See also: 1/ matrix 2/ convert 3/ array Ex1:table(3=-10,"a"=10,"b"=20,"c"=30,"d"=40) - Ex2: A:=[[0,1],[2,3]];table(A) + Ex2: A:=[[0,1],[2,3]];table(A) Ex3: B:=table([1,2]=12,[2,5]=25);matrix(B) - ''' return GiacMethods['table'](self,*args) @@ -16865,10 +15535,9 @@ cdef class GiacMethods_base: Help for tablefunc: tablefunc(Expr,Var) Table of values of a function : you must be in a spreadsheet. - See also: 1/ tabvar 2/ tableseq + See also: 1/ tabvar 2/ tableseq Ex1:tablefunc(sin(x),x) Ex2:tablefunc(x^2-x-2,x) - ''' return GiacMethods['tablefunc'](self,*args) @@ -16877,10 +15546,9 @@ cdef class GiacMethods_base: Help for tableseq: tableseq(Expr,(Var or LstVar),(InitVal or LstInitVal)) Table of values of a sequence (in a spreadsheet.) - See also: 1/ tablefunc + See also: 1/ tablefunc Ex1:tableseq(cos(x),x,0.0) Ex2:tableseq(x+y,[x,y],[1,1]) - ''' return GiacMethods['tableseq'](self,*args) @@ -16889,11 +15557,10 @@ cdef class GiacMethods_base: Help for tabsign: tabsign(Expr,Var) Table of signs of a function. - See also: 1/ tablefunc 2/ tabvar + See also: 1/ tablefunc 2/ tabvar Ex1:tabsign(x^2-x,x) Ex2:tabsign(x^2,x,-3,5) Ex3:tabsign(sin(x),x) - ''' return GiacMethods['tabsign'](self,*args) @@ -16902,13 +15569,12 @@ cdef class GiacMethods_base: Help for tabvar: tabvar(Expr,Var) Table of variations of a function with its graph on DispG. - See also: 1/ tablefunc 2/ tabsign + See also: 1/ tablefunc 2/ tabsign Ex1:tabvar(sin(x),x) Ex2:tabvar(1/ln(x^2-1),x,diff=1) Ex3:tabvar(x^2+x+1,x) Ex4:tabvar(x^2,x,-3,5) Ex5:tabvar([sin(2t),cos(3t)]) - ''' return GiacMethods['tabvar'](self,*args) @@ -16917,11 +15583,10 @@ cdef class GiacMethods_base: Help for tail: tail(Lst or Seq or Str) Returns the list (or sequence or string) without its first element. - See also: 1/ head 2/ mid 3/ left 4/ right 5/ back + See also: 1/ head 2/ mid 3/ left 4/ right 5/ back Ex1:tail([3,2,4,1,0]) Ex2:tail(3,2,4,1,0) Ex3:tail("bonjour") - ''' return GiacMethods['tail'](self,*args) @@ -16930,11 +15595,10 @@ cdef class GiacMethods_base: Help for tan: tan(Expr) Tangent or option of the convert or convertir command (id halftan). - See also: 1/ atan or Opt 2/ convert 3/ halftan + See also: 1/ atan or Opt 2/ convert 3/ halftan Ex1:tan(0) Ex2:tan(pi/4) Ex3: convert(tan(x),tan) - ''' return GiacMethods['tan'](self,*args) @@ -16943,9 +15607,8 @@ cdef class GiacMethods_base: Help for tan2cossin2: tan2cossin2(Expr) Replaces tan(x) by (1-cos(2*x))/sin(2*x) in the argument. - See also: 1/ tan2sincos2 2/ tan2sincos 3/ sin2costan 4/ cos2sintan + See also: 1/ tan2sincos2 2/ tan2sincos 3/ sin2costan 4/ cos2sintan Ex1:tan2cossin2(tan(x)) - ''' return GiacMethods['tan2cossin2'](self,*args) @@ -16954,9 +15617,8 @@ cdef class GiacMethods_base: Help for tan2sincos: tan2sincos(Expr) Replaces tan(x) by sin(x)/cos(x) in the argument. - See also: 1/ sin2costan 2/ cos2sintan 3/ tan2sincos2 4/ tan2cossin2 + See also: 1/ sin2costan 2/ cos2sintan 3/ tan2sincos2 4/ tan2cossin2 Ex1:tan2sincos(tan(x)) - ''' return GiacMethods['tan2sincos'](self,*args) @@ -16965,9 +15627,8 @@ cdef class GiacMethods_base: Help for tan2sincos2: tan2sincos2(Expr) Replaces tan(x) by sin(2*x)/(1+cos(2*x)) in the argument. - See also: 1/ tan2cossin2 2/ tan2sincos 3/ sin2costan 4/ cos2sintan + See also: 1/ tan2cossin2 2/ tan2sincos 3/ sin2costan 4/ cos2sintan Ex1:tan2sincos2(tan(x)) - ''' return GiacMethods['tan2sincos2'](self,*args) @@ -16976,7 +15637,7 @@ cdef class GiacMethods_base: Help for tangent: tangent(Curve(C),Pnt(A)) tangent(C,A) draws the tangents (line or plane) to C through A. - See also: 1/ LineTan 2/ droite_tangente + See also: 1/ LineTan 2/ droite_tangente Ex1:tangent(circle(i,1+i),A) Ex2:tangent(plotfunc(sin(x)),3*pi/4) Ex3:tangent(plotfunc(sin(x)),point(3*pi/4+i*sqrt(2)/2)) @@ -16985,7 +15646,6 @@ cdef class GiacMethods_base: Ex6:tangent(plotparam(3*exp(t/2)*exp(i*t),t),7) Ex7:tangent(plotpolar(3*exp(t/2),t),7) Ex8: equation(tangente([2*cos(t),2*sin(t),3*t],t)) - ''' return GiacMethods['tangent'](self,*args) @@ -16994,7 +15654,7 @@ cdef class GiacMethods_base: Help for tangente: tangente(Curve(C),Pnt(A)) tangent(C,A) draws the tangents (line or plane) to C through A. - See also: 1/ LineTan 2/ droite_tangente + See also: 1/ LineTan 2/ droite_tangente Ex1:tangente(circle(i,1+i),A) Ex2:tangente(plotfunc(sin(x)),3*pi/4) Ex3:tangente(plotfunc(sin(x)),point(3*pi/4+i*sqrt(2)/2)) @@ -17003,7 +15663,6 @@ cdef class GiacMethods_base: Ex6:tangente(plotparam(3*exp(t/2)*exp(i*t),t),7) Ex7:tangente(plotpolar(3*exp(t/2),t),7) Ex8: equation(tangente([2*cos(t),2*sin(t),3*t],t)) - ''' return GiacMethods['tangente'](self,*args) @@ -17012,10 +15671,9 @@ cdef class GiacMethods_base: Help for tanh: tanh(Expr) Hyperbolic tangent. - See also: 1/ atanh 2/ hyp2exp + See also: 1/ atanh 2/ hyp2exp Ex1:tanh(0) Ex2:tanh(hyp2exp(tanh(1))) - ''' return GiacMethods['tanh'](self,*args) @@ -17024,11 +15682,10 @@ cdef class GiacMethods_base: Help for taux_accroissement: taux_accroissement(Expr,Var,Val1,(Val1+Var or Val2)) Returns the rate of change of an expression when the variable goes from Val1 to Val2 (by default Var=x). - See also: 1/ diff 2/ limit + See also: 1/ diff 2/ limit Ex1:taux_accroissement(x^2,1,1+h) Ex2:taux_accroissement(x^2,1,2) Ex3:taux_accroissement(a^2,a,1,1+h) - ''' return GiacMethods['taux_accroissement'](self,*args) @@ -17037,7 +15694,7 @@ cdef class GiacMethods_base: Help for taylor: taylor(Expr,[Var=limit_point],[Order]) Series expansion at finite or infinite points (by default x=0, and relative order=5). - See also: 1/ series 2/ limit 3/ pade 4/ polynom + See also: 1/ series 2/ limit 3/ pade 4/ polynom Ex1:taylor(sin(x)/x,x,0) Ex2:taylor(sin(x),x=0,5,polynom) Ex3:taylor(ln(y+y^2)-ln(y),y) @@ -17045,10 +15702,9 @@ cdef class GiacMethods_base: Ex5:taylor(ln(x+x^2)-ln(x),x=0,2) Ex6:taylor(ln(x+x^2)-ln(x),x=1,2) Ex7:taylor((x^4+x+2)/(x^2+1),x,5) - Ex8:taylor(sin(t*x+t*y)+cos(t*x*t*y),t=0,6,polynom)(h=1) + Ex8:taylor(sin(t*x+t*y)+cos(t*x*t*y),t=0,6,polynom)(h=1) Ex9:taylor(sin((1+h*t)*(pi/2+k*t)),t=0,3,polynom)(t=1) Ex10:taylor((-1+k*t)^2/(1+h*t)^3,t=0,3,polynom)(t=1) - ''' return GiacMethods['taylor'](self,*args) @@ -17057,9 +15713,8 @@ cdef class GiacMethods_base: Help for tchebyshev1: tchebyshev1(Intg(n)) Returns the n-th Tchebyshev polynomial of first kind. - See also: 1/ tchebyshev2 2/ hermite + See also: 1/ tchebyshev2 2/ hermite Ex1:tchebyshev1(3) - ''' return GiacMethods['tchebyshev1'](self,*args) @@ -17068,9 +15723,8 @@ cdef class GiacMethods_base: Help for tchebyshev2: tchebyshev2(Intg(n)) Returns the nt-h Tchebyshev polynomial of second kind. - See also: 1/ tchebyshev1 2/ hermite + See also: 1/ tchebyshev1 2/ hermite Ex1:tchebyshev2(3) - ''' return GiacMethods['tchebyshev2'](self,*args) @@ -17079,10 +15733,9 @@ cdef class GiacMethods_base: Help for tcoeff: tcoeff(Poly||Lst) Returns the coefficient of the term of lowest degree of a polynomial (t=trailing). - See also: 1/ lcoeff + See also: 1/ lcoeff Ex1:tcoeff(-2*x^3+x^2+7*x) Ex2:tcoeff([-2,1,7,0]) - ''' return GiacMethods['tcoeff'](self,*args) @@ -17091,9 +15744,8 @@ cdef class GiacMethods_base: Help for tcollect: tcollect(Expr) Collects trigonometric expressions. - See also: 1/ texpand 2/ tlin + See also: 1/ texpand 2/ tlin Ex1:tcollect(sin(x)+cos(x)) - ''' return GiacMethods['tcollect'](self,*args) @@ -17102,8 +15754,7 @@ cdef class GiacMethods_base: Help for tdeg: tdeg(Opt) Option of the gbasis or greduce command to specify an order for monomials (complete degree then lexicographic order). - See also: 1/ gbasis 2/ greduce - + See also: 1/ gbasis 2/ greduce ''' return GiacMethods['tdeg'](self,*args) @@ -17112,9 +15763,8 @@ cdef class GiacMethods_base: Help for tensor_product: tensor_product(Seq(G1,G2,..)) Returns the tensor product of the input graphs G1, G2, ... with vertices labelled as "u:v:..." where u, v, ... are vertices from G1, G2, ..., respectively. - See also: 1/ cartesian_product + See also: 1/ cartesian_product Ex1:tensor_product(graph(trail(1,2,3,4,5,2)),star_graph(3)) - ''' return GiacMethods['tensor_product'](self,*args) @@ -17123,10 +15773,9 @@ cdef class GiacMethods_base: Help for tetrahedron: tetrahedron(Pnt(A),Pnt(B),Pnt(C),[Pnt(D)]) Draws the regular direct pyramid ABCD with vertices A,B and a face in the plane (A,B,C) when there is 3 arguments and the pyramid ABCD when there are 4 arguments. - See also: 1/ cube 2/ cylinder 3/ icosahedron 4/ dodecahedron 5/ octahedron + See also: 1/ cube 2/ cylinder 3/ icosahedron 4/ dodecahedron 5/ octahedron Ex1:tetrahedron([0,0,0],[3,0,0],[0,1,0]) Ex2:tetrahedron([0,0,0],[3,0,0],[0,3,0],[0,0,4]) - ''' return GiacMethods['tetrahedron'](self,*args) @@ -17135,11 +15784,10 @@ cdef class GiacMethods_base: Help for texpand: texpand(Expr) Expands transcendental expressions. - See also: 1/ tcollect 2/ tlin 3/ lin 4/ trigexpand + See also: 1/ tcollect 2/ tlin 3/ lin 4/ trigexpand Ex1:texpand(sin(2*x)+exp(x+y)) Ex2:texpand(cos(x+y)) Ex3:texpand(cos(3*x)) - ''' return GiacMethods['texpand'](self,*args) @@ -17148,10 +15796,9 @@ cdef class GiacMethods_base: Help for thickness: thickness(Opt) Option (Maple compatibility) of a graphic command to define the thickness of lines. - See also: 1/ line_width + See also: 1/ line_width Ex1: segment(0,point(1,1),thickness=5) Ex2: segment(0,point(1,1),epaisseur=5) - ''' return GiacMethods['thickness'](self,*args) @@ -17160,10 +15807,9 @@ cdef class GiacMethods_base: Help for threshold: threshold(Lst,Real(bound)[=Expr(repl)] or Lst[Real(lower)[=Expr(rl)],Real(upper)[=Expr(ru)]],[Fnc(compare)],[abs[=true or false]]) Performs thresholding operations on a list of real or complex numbers. - See also: 1/ max 2/ min + See also: 1/ max 2/ min Ex1:threshold([1,3,2,4,5,4,3,2,3,1],3,'>=') Ex2:threshold([-10,-5,0,5,10],7=a,abs=true) - ''' return GiacMethods['threshold'](self,*args) @@ -17172,10 +15818,9 @@ cdef class GiacMethods_base: Help for throw: throw(Str) Generates the display of an error in a program. - See also: 1/ try 2/ catch + See also: 1/ try 2/ catch Ex1:throw("Argument should be integer") Ex2:throw("je provoque une erreur") - ''' return GiacMethods['throw'](self,*args) @@ -17184,10 +15829,9 @@ cdef class GiacMethods_base: Help for title: title(Opt) Global option of a graphic command to put a title in a graphic. - See also: 1/ line_width + See also: 1/ line_width Ex1: title="segment";segment(0,point(1,1),epaisseur=5) Ex2: titre="segment";segment(0,point(1,1),epaisseur=5) - ''' return GiacMethods['title'](self,*args) @@ -17196,10 +15840,9 @@ cdef class GiacMethods_base: Help for titre: titre(Opt) Global option of a graphic command to put a title in a graphic. - See also: 1/ line_width + See also: 1/ line_width Ex1: title="segment";segment(0,point(1,1),epaisseur=5) Ex2: titre="segment";segment(0,point(1,1),epaisseur=5) - ''' return GiacMethods['titre'](self,*args) @@ -17208,10 +15851,9 @@ cdef class GiacMethods_base: Help for tlin: tlin(ExprTrig) Trigonometric linearization. - See also: 1/ texpand 2/ lin + See also: 1/ texpand 2/ lin Ex1:tlin(sin(x)^3) Ex2:tlin(cos(x)*cos(y)) - ''' return GiacMethods['tlin'](self,*args) @@ -17220,10 +15862,9 @@ cdef class GiacMethods_base: Help for tonnetz: tonnetz(Intg(a),Intg(b),Intg(c),[Intg(d)]) Returns the graph corresponding to the [a,b,c] resp. [a,b,c,d] tone network (tonnetz) used in neo-Riemannian music theory. - See also: 1/ is_regular 2/ clique_stats + See also: 1/ is_regular 2/ clique_stats Ex1:tonnetz(3,4,5) Ex2:tonnetz(2,3,3,4) - ''' return GiacMethods['tonnetz'](self,*args) @@ -17232,9 +15873,8 @@ cdef class GiacMethods_base: Help for topologic_sort: topologic_sort(Graph(G)) Returns the list of vertices sorted according to the topological ordering in the directed acyclic graph G. - See also: 1/ digraph 2/ is_acyclic + See also: 1/ digraph 2/ is_acyclic Ex1:topologic_sort(digraph(%{[c,a],[c,b],[c,d],[a,d],[b,d],[a,b]%})) - ''' return GiacMethods['topologic_sort'](self,*args) @@ -17243,9 +15883,8 @@ cdef class GiacMethods_base: Help for topological_sort: topological_sort(Graph(G)) Returns the list of vertices sorted according to the topological ordering in the directed acyclic graph G. - See also: 1/ digraph 2/ is_acyclic + See also: 1/ digraph 2/ is_acyclic Ex1:topological_sort(digraph(%{[c,a],[c,b],[c,d],[a,d],[b,d],[a,b]%})) - ''' return GiacMethods['topological_sort'](self,*args) @@ -17254,9 +15893,8 @@ cdef class GiacMethods_base: Help for torus_grid_graph: torus_grid_graph(Intg(m),Intg(n)) Returns a torus grid graph on m*n vertices, where m,n>=3. - See also: 1/ grid_graph + See also: 1/ grid_graph Ex1:torus_grid_graph(6,12) - ''' return GiacMethods['torus_grid_graph'](self,*args) @@ -17265,9 +15903,8 @@ cdef class GiacMethods_base: Help for total_degree: total_degree(Poly(P),Lst(Vars)) Total degree of the polynomial P with respect to the second argument. - See also: 1/ valuation 2/ size 3/ degree + See also: 1/ valuation 2/ size 3/ degree Ex1:total_degree(x^3*y+x*y,[x,y]) - ''' return GiacMethods['total_degree'](self,*args) @@ -17276,10 +15913,9 @@ cdef class GiacMethods_base: Help for tourne_droite: tourne_droite(NULL or Real(n)) The turtle turns right by n degrees (by default n=90). - See also: 1/ tourne_gauche 2/ pas_de_cote + See also: 1/ tourne_gauche 2/ pas_de_cote Ex1: tourne_droite 60 Ex2:tourne_droite(60) - ''' return GiacMethods['tourne_droite'](self,*args) @@ -17288,10 +15924,9 @@ cdef class GiacMethods_base: Help for tourne_gauche: tourne_gauche(NULL or Real(n)) The turtle turns left by n degrees (by defaults n=90). - See also: 1/ tourne_droite + See also: 1/ tourne_droite Ex1: tourne_gauche 60 Ex2:tourne_gauche(60) - ''' return GiacMethods['tourne_gauche'](self,*args) @@ -17304,7 +15939,6 @@ cdef class GiacMethods_base: Ex2:tpsolve([7,10,8,8,9,6],[9,6,12,8,10],[[36,40,32,43,29],[28,27,29,40,38],[34,35,41,29,31],[41,42,35,27,36],[25,28,40,34,38],[31,30,43,38,40]]) Ex3:tpsolve([95,70,165,165],[195,150,30,45,75],[[15,M,45,M,0],[12,40,M,M,0],[0,15,25,25,0],[M,0,M,12,0]]) Ex4:tpsolve([1,1,1,1],[1,1,1,1],[[10,12,9,11],[5,10,7,8],[12,14,13,11],[8,15,11,9]]) - ''' return GiacMethods['tpsolve'](self,*args) @@ -17313,12 +15947,11 @@ cdef class GiacMethods_base: Help for trace: trace(Mtrx or GeoObj) Returns the trace of a square matrix or draws the trace of a geometric object when the parameter changes (see Trace in Menu button of a geometric level and write only one instruction on each line). - See also: 1/ det 2/ lieu + See also: 1/ det 2/ lieu Ex1:trace([[1,2,3],[1,3,6],[2,5,7]]) Ex2:trace([[1+i,2,3],[1,3,6],[2,5,9-i]]) Ex3: assume(a=[0.7,-5,5,0.1]);trace(point(a-i*a)) Ex4: assume(a=[0.7,-5,5,0.1]);trace(inter_unique(droite(y=a*x+a),droite(y=2*a*x+1))) - ''' return GiacMethods['trace'](self,*args) @@ -17327,9 +15960,8 @@ cdef class GiacMethods_base: Help for trail: trail(Seq(V)) Returns a trail of vertices from V (inert command). - See also: 1/ graph 2/ digraph + See also: 1/ graph 2/ digraph Ex1:trail(1,2,3,4,1) - ''' return GiacMethods['trail'](self,*args) @@ -17338,10 +15970,9 @@ cdef class GiacMethods_base: Help for trail2edges: trail2edges(Trail(T)) Converts a trail T to the list of its edges. - See also: 1/ subgraph 2/ trail + See also: 1/ subgraph 2/ trail Ex1:trail2edges(trail(1,2,3,4,1,3)) Ex2:trail2edges([1,2,3,4,1,3]) - ''' return GiacMethods['trail2edges'](self,*args) @@ -17350,10 +15981,9 @@ cdef class GiacMethods_base: Help for trames: trames(Opt) Option of animate and animate3d commands to give the number of pictures. - See also: 1/ animate 2/ animate3d + See also: 1/ animate 2/ animate3d Ex1: animate(sin(x*t),x=-pi..pi,t=-3..3,frames=30) Ex2: animate3d(x^2+t*y^2,[x=-2..2,y=-2..2],t=-3..3,frames=10) - ''' return GiacMethods['trames'](self,*args) @@ -17362,11 +15992,10 @@ cdef class GiacMethods_base: Help for tran: tran(Mtrx) Transposes a matrix (without conjugation). - See also: 1/ conj 2/ trn + See also: 1/ conj 2/ trn Ex1:tran([[1,2,3],[1,3,6],[2,5,7]]) Ex2:tran([[1+i,2,3],[1,3,6],[2,5,9-i]]) Ex3:tran(conj([[1+i,2,3],[1,3,6],[2,5,9-i]])) - ''' return GiacMethods['tran'](self,*args) @@ -17375,9 +16004,8 @@ cdef class GiacMethods_base: Help for transitive_closure: transitive_closure(Graph(G),[weighted[=true||false]]) Returns the [weighted, by default false] transitive closure of G. - See also: 1/ allpairs_distance 2/ is_connected 3/ shortest_path 4/ vertex_distance + See also: 1/ allpairs_distance 2/ is_connected 3/ shortest_path 4/ vertex_distance Ex1:transitive_closure(digraph([1,2,3,4,5,6],%{[1,2],[2,3],[2,4],[4,5],[3,5]%}),weighted) - ''' return GiacMethods['transitive_closure'](self,*args) @@ -17386,12 +16014,11 @@ cdef class GiacMethods_base: Help for translation: translation(Vect, Pnt(C)) translation(B-A,C) (resp translation([a,b,c],C)) is the translation of C in the translation of vector AB (resp [a,b,c]). - See also: 1/ rotation 2/ reflection + See also: 1/ rotation 2/ reflection Ex1:translation(1+i,i) Ex2:translation([1,1,1],point([1,2,3])) Ex3: t:=translation(1+i);t(i) Ex4: t:=translation([1,1,1]);t(point([1,2,3])) - ''' return GiacMethods['translation'](self,*args) @@ -17400,11 +16027,10 @@ cdef class GiacMethods_base: Help for transpose: transpose(Mtrx) Transposes a matrix (without conjugation). - See also: 1/ conj 2/ trn + See also: 1/ conj 2/ trn Ex1:transpose([[1,2,3],[1,3,6],[2,5,7]]) Ex2:transpose([[1+i,2,3],[1,3,6],[2,5,9-i]]) Ex3:transpose(conj([[1+i,2,3],[1,3,6],[2,5,9-i]])) - ''' return GiacMethods['transpose'](self,*args) @@ -17413,14 +16039,13 @@ cdef class GiacMethods_base: Help for trapeze: trapeze(Opt) Option of the plotarea command and of the area command. - See also: 1/ plotarea 2/ area + See also: 1/ plotarea 2/ area Ex1: plotarea(x^2,x=0..1,5,trapezoid) Ex2: plotarea(x^2,x=0..1,5,middle_point) Ex3: plotarea(x^2,x=0..1,5,right_rectangle) Ex4: plotarea(x^2,x=0..1,5,left_rectangle) Ex5: area(x^2,x=0..1,5,middle_point) Ex6: area(x^2,x=0..1,5,trapezoid) - ''' return GiacMethods['trapeze'](self,*args) @@ -17429,14 +16054,13 @@ cdef class GiacMethods_base: Help for trapezoid: trapezoid(Opt) Option of the plotarea command and of the area command. - See also: 1/ plotarea 2/ area + See also: 1/ plotarea 2/ area Ex1: plotarea(x^2,x=0..1,5,trapezoid) Ex2: plotarea(x^2,x=0..1,5,middle_point) Ex3: plotarea(x^2,x=0..1,5,right_rectangle) Ex4: plotarea(x^2,x=0..1,5,left_rectangle) Ex5: area(x^2,x=0..1,5,middle_point) Ex6: area(x^2,x=0..1,5,trapezoid) - ''' return GiacMethods['trapezoid'](self,*args) @@ -17445,13 +16069,12 @@ cdef class GiacMethods_base: Help for traveling_salesman: traveling_salesman(Graph(G),[Mtrx(M)],[opts]) Returns a Hamiltonian cycle in an unweighted graph G or solves traveling salesman problem if G is weighted (matrix M can be used for edge weights), returning a sequence containing the minimal cost and the corresponding Hamiltonian cycle. - See also: 1/ is_hamiltonian + See also: 1/ is_hamiltonian Ex1:traveling_salesman(hypercube_graph(5)) Ex2:traveling_salesman(digraph(%{[[1,2],1],[[1,3],2],[[2,3],2],[[2,4],3],[[3,2],3],[[3,4],2],[[4,1],1]%})) Ex3: M:=randmatrix(4,4,99); traveling_salesman(graph("tetrahedron"),M) Ex4: G:=set_vertex_positions(complete_graph(42),[randvector(2,1000)$(k=1..42)]); traveling_salesman(G,vertex_distance) Ex5: G:=set_vertex_positions(complete_graph(120),[randvector(2,1000)$(k=1..120)]); c,T:=traveling_salesman(G,vertex_distance,approx) - ''' return GiacMethods['traveling_salesman'](self,*args) @@ -17460,8 +16083,7 @@ cdef class GiacMethods_base: Help for tree: tree(Opt) Option for the draw_graph command. - See also: 1/ planar 2/ spring 3/ draw_graph - + See also: 1/ planar 2/ spring 3/ draw_graph ''' return GiacMethods['tree'](self,*args) @@ -17470,9 +16092,8 @@ cdef class GiacMethods_base: Help for tree_height: tree_height(Graph(T),Vrtx(r)) Returns the height of the tree graph T with r as the root node. - See also: 1/ is_tree 2/ random_tree + See also: 1/ is_tree 2/ random_tree Ex1:tree_height(graph(%{[1,2],[2,3],[2,4],[4,5]%}),1) - ''' return GiacMethods['tree_height'](self,*args) @@ -17481,9 +16102,8 @@ cdef class GiacMethods_base: Help for tri: tri(Expr(x)) Returns the value of the triangle function at x. - See also: 1/ rect 2/ Heaviside + See also: 1/ rect 2/ Heaviside Ex1:tri(x-1) - ''' return GiacMethods['tri'](self,*args) @@ -17492,11 +16112,10 @@ cdef class GiacMethods_base: Help for triangle: triangle((Pnt or Cplx),(Pnt or Cplx),(Pnt or Cplx)) triangle(A,B,C) draws the triangle ABC. - See also: 1/ equilateral_triangle 2/ isosceles_triangle 3/ right_triangle + See also: 1/ equilateral_triangle 2/ isosceles_triangle 3/ right_triangle Ex1:triangle(point(1+i),1,0) Ex2:triangle(0,1,1+i) Ex3:triangle(point(0,0,0),point(3,3,3),point(0,3,3)) - ''' return GiacMethods['triangle'](self,*args) @@ -17509,7 +16128,6 @@ cdef class GiacMethods_base: Ex2:triangle_paper(1,pi/3,sqrt(3)/2,x=-1..4,y=-2..2) Ex3:triangle_paper(papier_triangule(1,pi/3,sqrt(3)/2,x=-2..6,y=-4*sqrt(3)..4*sqrt(3))) Ex4:triangle_paper(0.5,3*pi/4,0.5) - ''' return GiacMethods['triangle_paper'](self,*args) @@ -17518,12 +16136,11 @@ cdef class GiacMethods_base: Help for triangle_plein: triangle_plein(Real(a),[Real(b)],[Real(t)]) Draws a full direct triangle with sides a,b and with angle t, from the turtle position (by default t=90 or (b=a and t=60)). - See also: 1/ rectangle_plein + See also: 1/ rectangle_plein Ex1: triangle_plein 30 Ex2:triangle_plein(30) Ex3:triangle_plein(30,40) Ex4:triangle_plein(30,40,60) - ''' return GiacMethods['triangle_plein'](self,*args) @@ -17532,10 +16149,9 @@ cdef class GiacMethods_base: Help for triangle_point: triangle_point(Opt) Option of the display command for a point. - See also: 1/ display + See also: 1/ display Ex1: F:=display(point(2+1.5*i),point_point) Ex2: F:=display(point(2+1.5*i),rhombus_point) - ''' return GiacMethods['triangle_point'](self,*args) @@ -17544,9 +16160,8 @@ cdef class GiacMethods_base: Help for triangle_window: triangle_window(Lst,[Intg(d)],[Interval(n1..n2)]) Applies the triangular windowing function with parameter d in {-1,0,1} (by default L=0) to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ bartlett_hann_window 13/ tukey_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ bartlett_hann_window 13/ tukey_window 14/ welch_window Ex1: scatterplot(triangle_window(randvector(1000,0..1),1)) - ''' return GiacMethods['triangle_window'](self,*args) @@ -17555,9 +16170,8 @@ cdef class GiacMethods_base: Help for trig2exp: trig2exp(Expr) Replaces in the argument the trigonometric functions by complex exponentials without linearisation. - See also: 1/ exp2trig 2/ atrig2ln + See also: 1/ exp2trig 2/ atrig2ln Ex1:trig2exp(sin(x)) - ''' return GiacMethods['trig2exp'](self,*args) @@ -17566,9 +16180,8 @@ cdef class GiacMethods_base: Help for trigcos: trigcos(Expr) Simplifies the argument with the formulas sin(x)^2+cos(x)^2=1 and tan(x)=sin(x)/cos(x) privileging cosine. - See also: 1/ trigsin 2/ trigtan + See also: 1/ trigsin 2/ trigtan Ex1:trigcos(sin(x)^4+sin(x)^2) - ''' return GiacMethods['trigcos'](self,*args) @@ -17577,9 +16190,8 @@ cdef class GiacMethods_base: Help for trigexpand: trigexpand(Expr) Expands trigonometric functions. - See also: 1/ texpand 2/ lnexpand 3/ expexpand + See also: 1/ texpand 2/ lnexpand 3/ expexpand Ex1:trigexpand(sin(3*x)) - ''' return GiacMethods['trigexpand'](self,*args) @@ -17588,10 +16200,9 @@ cdef class GiacMethods_base: Help for triginterp: triginterp(List,Var=xmin..xmax) Returns a trigonometric polynomial interpolation (with respect to variable x) of the points with ordinate given in list y and the abscissa equally spaced between a and b. - See also: 1/ lagrange 2/ thiele + See also: 1/ lagrange 2/ thiele Ex1:triginterp([11,10,17,24,32,26,23,19],x=0..21) Ex2:triginterp([11,10,17,24,32,26,23,19],0,21,x) - ''' return GiacMethods['triginterp'](self,*args) @@ -17600,9 +16211,8 @@ cdef class GiacMethods_base: Help for trigsimplify: trigsimplify(Expr) Simplifies a trigonometric expression. - See also: 1/ simplify + See also: 1/ simplify Ex1:trigsimplify(3*sin(x)-4*sin(x)^3) - ''' return GiacMethods['trigsimplify'](self,*args) @@ -17611,9 +16221,8 @@ cdef class GiacMethods_base: Help for trigsin: trigsin(Expr) Simplifies the argument with the formulas sin(x)^2+cos(x)^2=1 and tan(x)=sin(x)/cos(x) privileging sine. - See also: 1/ trigcos 2/ trigtan + See also: 1/ trigcos 2/ trigtan Ex1:trigsin(cos(x)^4+sin(x)^2) - ''' return GiacMethods['trigsin'](self,*args) @@ -17622,9 +16231,8 @@ cdef class GiacMethods_base: Help for trigtan: trigtan(Expr) Simplifies the argument with the formulas sin(x)^2+cos(x)^2=1 and tan(x)=sin(x)/cos(x) privileging tangent. - See also: 1/ trigsin 2/ trigcos + See also: 1/ trigsin 2/ trigcos Ex1:trigtan(cos(x)^4+sin(x)^2) - ''' return GiacMethods['trigtan'](self,*args) @@ -17633,9 +16241,8 @@ cdef class GiacMethods_base: Help for trn: trn(Mtrx) Returns the adjoint matrix of A =tran(conj(A)). - See also: 1/ tran 2/ conj + See also: 1/ tran 2/ conj Ex1:trn([[1,2+i],[3,4]]) - ''' return GiacMethods['trn'](self,*args) @@ -17644,9 +16251,8 @@ cdef class GiacMethods_base: Help for true: true() Boolean equal to true or 1. - See also: 1/ false + See also: 1/ false Ex1: a:=true - ''' return GiacMethods['true'](self,*args) @@ -17655,13 +16261,12 @@ cdef class GiacMethods_base: Help for trunc: trunc(Real||LstReal,Int(n)) Truncates value to n decimal places (by default n=0). Accepts complex numbers.(type=DOM_COMPLEX or DOM_FLOAT). - See also: 1/ fPart 2/ floor 3/ iPart + See also: 1/ fPart 2/ floor 3/ iPart Ex1:trunc(4.3) Ex2:trunc(sqrt(2),3) Ex3:trunc([4.3333,sqrt(2)]) Ex4:trunc([4.3333,sqrt(2)],2) Ex5:trunc(sqrt(2)+i*sqrt(5),4) - ''' return GiacMethods['trunc'](self,*args) @@ -17670,9 +16275,8 @@ cdef class GiacMethods_base: Help for truncate: truncate(Poly(P),Intg(n)) Truncates the polynomial P at order n. - See also: 1/ series + See also: 1/ series Ex1:truncate((x^2+x)^2,3) - ''' return GiacMethods['truncate'](self,*args) @@ -17681,9 +16285,8 @@ cdef class GiacMethods_base: Help for truncate_graph: truncate_graph(Graph(G)) Returns the graph obtained by truncating the biconnected planar graph G. - See also: 1/ is_biconnected 2/ is_planar 3/ plane_dual + See also: 1/ is_biconnected 2/ is_planar 3/ plane_dual Ex1:truncate_graph(graph("tetrahedron")) - ''' return GiacMethods['truncate_graph'](self,*args) @@ -17692,9 +16295,8 @@ cdef class GiacMethods_base: Help for tsimplify: tsimplify(Expr) Lowers the number of non rational variables. - See also: 1/ simplify + See also: 1/ simplify Ex1:tsimplify(exp(2*x)+exp(x)) - ''' return GiacMethods['tsimplify'](self,*args) @@ -17703,9 +16305,8 @@ cdef class GiacMethods_base: Help for tuer: tuer(NULL) Stop step-by-step execution of a program (with debug). - See also: 1/ + See also: 1/ Ex1:tuer() - ''' return GiacMethods['tuer'](self,*args) @@ -17714,9 +16315,8 @@ cdef class GiacMethods_base: Help for tukey_window: tukey_window(Lst,[Real(a)],[Interval(n1..n2)]) Applies the Tukey windowing function with parameter a in [0,1] (by default a=0.5) to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ bartlett_hann_window 14/ welch_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ bartlett_hann_window 14/ welch_window Ex1: scatterplot(tukey_window(randvector(1000,0..1),0.4)) - ''' return GiacMethods['tukey_window'](self,*args) @@ -17725,10 +16325,9 @@ cdef class GiacMethods_base: Help for tutte_polynomial: tutte_polynomial(Graph(G),[Var(x),Var(y)]) Returns the Tutte polynomial [or its value at point (x,y)] of undirected graph G. If G is weighted, all weights must be positive integers and are interpreted as edge multiplicities. - See also: 1/ chromatic_polynomial 2/ flow_polynomial 3/ reliability_polynomial 4/ delete_edge 5/ contract_edge + See also: 1/ chromatic_polynomial 2/ flow_polynomial 3/ reliability_polynomial 4/ delete_edge 5/ contract_edge Ex1:tutte_polynomial(graph("tetrahedron")) Ex2:tutte_polynomial(graph("tetrahedron"),1,1) - ''' return GiacMethods['tutte_polynomial'](self,*args) @@ -17737,9 +16336,8 @@ cdef class GiacMethods_base: Help for two_edge_connected_components: two_edge_connected_components(Graph(G)) Returns the list of two-edge-connected components of undirected graph G, each of them represented by the list of its vertices. - See also: 1/ is_two_edge_connected 2/ connected_components + See also: 1/ is_two_edge_connected 2/ connected_components Ex1:two_edge_connected_components(graph(trail(1,2,3,4,5,3,1),trail(5,6,7,8,6))) - ''' return GiacMethods['two_edge_connected_components'](self,*args) @@ -17748,9 +16346,8 @@ cdef class GiacMethods_base: Help for ufactor: ufactor(Unit,Unit) Factors a unit in a unit object. - See also: 1/ convert 2/ mksa 3/ usimplify + See also: 1/ convert 2/ mksa 3/ usimplify Ex1:ufactor(100_C,1_A) - ''' return GiacMethods['ufactor'](self,*args) @@ -17759,10 +16356,9 @@ cdef class GiacMethods_base: Help for ugamma: ugamma(Real(a),Real(x),[1]) Calculates ugamma function at a point (a,x):if a and x>=0 ugamma(a,x)=int(e^{-t}*t^{a-1},t=x..inf),(ugamma(a,x)+igamma(a,x)=Gamma(a)). - See also: 1/ Psi 2/ Beta 3/ Gamma 4/ igamma + See also: 1/ Psi 2/ Beta 3/ Gamma 4/ igamma Ex1:ugamma(5.0,2.0) Ex2:ugamma(-5.1,2.1) - ''' return GiacMethods['ugamma'](self,*args) @@ -17771,10 +16367,9 @@ cdef class GiacMethods_base: Help for unapply: unapply(Expr,Var) Returns a function defined by an expression. - See also: 1/ apply + See also: 1/ apply Ex1:unapply(2*x^2,x) Ex2: f(x):=x*exp(x);g:=unapply(diff(f(x),x),x) - ''' return GiacMethods['unapply'](self,*args) @@ -17783,10 +16378,9 @@ cdef class GiacMethods_base: Help for unarchive: unarchive(Str(namefich),Seq(Var)) Reads the value of a variable or of a list of variables which are in the file given as argument (file created with archive). - See also: 1/ archive 2/ Archive 3/ Unarchiv + See also: 1/ archive 2/ Archive 3/ Unarchiv Ex1:unarchive("toto") Ex2:unarchive("aa.txt") - ''' return GiacMethods['unarchive'](self,*args) @@ -17795,9 +16389,8 @@ cdef class GiacMethods_base: Help for underlying_graph: underlying_graph(Graph(G)) Returns the graph obtained by stripping directions and weights from arcs (pairs of arcs connecting the same vertices are merged to a single edge). - See also: 1/ is_directed 2/ is_weighted 3/ make_directed 4/ make_weighted + See also: 1/ is_directed 2/ is_weighted 3/ make_directed 4/ make_weighted Ex1:underlying_graph(digraph(trail(1,2,3,4,1))) - ''' return GiacMethods['underlying_graph'](self,*args) @@ -17806,13 +16399,12 @@ cdef class GiacMethods_base: Help for unfactored: unfactored(Opt.) Option of the plotimplicit command. - See also: 1/ plotimplicit + See also: 1/ plotimplicit Ex1: plotimplicit(x^2+y^2-1,x,y,unfactored) Ex2: plotimplicit(x^2+y^2-1,[x,y],unfactored) Ex3: plotimplicit(x^2+y^2+z^2-1,x,y,z,xstep=0.2,ystep=0.2,zstep=0.2,unfactored) Ex4: plotimplicit(x^2+y^2+z^2-1,[x,y,z],xstep=0.2,ystep=0.2,zstep=0.2,unfactored) Ex5: plotimplicit(x^2+y^2+z^2-1,x=0..1,y=0..1,z=0..1,xstep=0.2,ystep=0.2,zstep=0.2,unfactored) - ''' return GiacMethods['unfactored'](self,*args) @@ -17821,12 +16413,11 @@ cdef class GiacMethods_base: Help for uniform: uniform(Real(a),Real(b),Real(x)) Returns the probability density at x of the uniform law on [a,b]. - See also: 1/ uniform_cdf 2/ uniform_icdf 3/ randvector 4/ ranm + See also: 1/ uniform_cdf 2/ uniform_icdf 3/ randvector 4/ ranm Ex1:uniform(2,5,4) Ex2:uniform(1.2,3.5,3) Ex3: randvector(3,uniform,1.2,3.5) Ex4: ranm(4,3,uniform,1.2,3.5) - ''' return GiacMethods['uniform'](self,*args) @@ -17835,10 +16426,9 @@ cdef class GiacMethods_base: Help for uniform_cdf: uniform_cdf(Real(a),Real(b),Real(x0),[Real(y0)]) Returns the probability that a uniform random variable on [a,b] is less than x0 (or between x0 and y0). - See also: 1/ uniformd 2/ uniform_icdf + See also: 1/ uniformd 2/ uniform_icdf Ex1:uniform_cdf(3.2,5.7,4.4) Ex2:uniform_cdf(3.2,5.7,4.4,5.4) - ''' return GiacMethods['uniform_cdf'](self,*args) @@ -17847,10 +16437,9 @@ cdef class GiacMethods_base: Help for uniform_icdf: uniform_icdf(Real(a),Real(b),Real(p)) Returns h such that the probability that a uniform random variable on [a,b] is less than h is p (0<=p<=1). - See also: 1/ uniform_cdf 2/ uniformd + See also: 1/ uniform_cdf 2/ uniformd Ex1:uniform_icdf(4.2,10.3,0.95) Ex2:uniform_icdf(3.2,5.7,0.48) - ''' return GiacMethods['uniform_icdf'](self,*args) @@ -17859,12 +16448,11 @@ cdef class GiacMethods_base: Help for uniformd: uniformd(Real(a),Real(b),Real(x)) Returns the probability density at x of the uniform law on [a,b]. - See also: 1/ uniform_cdf 2/ uniform_icdf 3/ randvector 4/ ranm + See also: 1/ uniform_cdf 2/ uniform_icdf 3/ randvector 4/ ranm Ex1:uniformd(2,5,4) Ex2:uniformd(1.2,3.5,3) Ex3: randvector(3,uniform,1.2,3.5) Ex4: ranm(4,3,uniform,1.2,3.5) - ''' return GiacMethods['uniformd'](self,*args) @@ -17873,10 +16461,9 @@ cdef class GiacMethods_base: Help for uniformd_cdf: uniformd_cdf(Real(a),Real(b),Real(x0),[Real(y0)]) Returns the probability that a uniform random variable on [a,b] is less than x0 (or between x0 and y0). - See also: 1/ uniformd 2/ uniform_icdf + See also: 1/ uniformd 2/ uniform_icdf Ex1:uniformd_cdf(3.2,5.7,4.4) Ex2:uniformd_cdf(3.2,5.7,4.4,5.4) - ''' return GiacMethods['uniformd_cdf'](self,*args) @@ -17885,10 +16472,9 @@ cdef class GiacMethods_base: Help for uniformd_icdf: uniformd_icdf(Real(a),Real(b),Real(p)) Returns h such that the probability that a uniform random variable on [a,b] is less than h is p (0<=p<=1). - See also: 1/ uniform_cdf 2/ uniformd + See also: 1/ uniform_cdf 2/ uniformd Ex1:uniformd_icdf(4.2,10.3,0.95) Ex2:uniformd_icdf(3.2,5.7,0.48) - ''' return GiacMethods['uniformd_icdf'](self,*args) @@ -17897,12 +16483,11 @@ cdef class GiacMethods_base: Help for unitV: unitV(Lst||Cplx) Returns the vector divided by its l2norm. It is also an option for plotfield. - See also: 1/ l2norm + See also: 1/ l2norm Ex1:unitV(3+4*i) Ex2:unitV([3,4]) Ex3: fieldplot(-t*y,[t,y],normalize) Ex4: fieldplot(-t*y,[t,y],normalize,xstep=0.5,ystep=0.5) - ''' return GiacMethods['unitV'](self,*args) @@ -17911,9 +16496,8 @@ cdef class GiacMethods_base: Help for unquote: unquote(Expr) Evaluates a quoted expression (for example purge(c);a:=c;unquote(a):=3; put 3 in the variables a and c). - See also: 1/ quote + See also: 1/ quote Ex1:unquote(a) - ''' return GiacMethods['unquote'](self,*args) @@ -17922,10 +16506,9 @@ cdef class GiacMethods_base: Help for upper: upper(Mtrx||Strng) Returns the upper triangular matrix (over the diagonal, included) or writes a string in uppercase. - See also: 1/ diag 2/ lower + See also: 1/ diag 2/ lower Ex1:upper([[1,2,3],[4,5,6],[7,8,9]]) Ex2:upper("hello") - ''' return GiacMethods['upper'](self,*args) @@ -17934,10 +16517,9 @@ cdef class GiacMethods_base: Help for user_operator: user_operator(Str(R),Fnc(f),Opt(Binary||Unary||Delete)) Defines a binary operator and returns 0 (failure) or 1(success). - See also: 1/ + See also: 1/ Ex1:user_operator("R",(x,y)->x*y+x+y,Binary) Ex2:user_operator("R",(x,y)->x*y+x+y,Delete) - ''' return GiacMethods['user_operator'](self,*args) @@ -17946,9 +16528,8 @@ cdef class GiacMethods_base: Help for usimplify: usimplify(Unit) Simplifies a unit in a unit object. - See also: 1/ convert 2/ mksa 3/ ufactor + See also: 1/ convert 2/ mksa 3/ ufactor Ex1:usimplify(100_(W*s)) - ''' return GiacMethods['usimplify'](self,*args) @@ -17957,12 +16538,11 @@ cdef class GiacMethods_base: Help for valuation: valuation(Poly(P)) Returns the valuation (degree of the term of lowest degree) of the polynomial P. - See also: 1/ degree 2/ tcoeff + See also: 1/ degree 2/ tcoeff Ex1:valuation(x^4+x^3) Ex2:valuation([1,1,0,0,0]) Ex3:valuation(x^5+3*x^2) Ex4:valuation([5,0,0,3,0,0]) - ''' return GiacMethods['valuation'](self,*args) @@ -17971,9 +16551,8 @@ cdef class GiacMethods_base: Help for vandermonde: vandermonde(Vect(V)) Returns the Vandermonde matrix=[V^0,V^1,..]. - See also: 1/ det + See also: 1/ det Ex1:vandermonde([1,2,a]) - ''' return GiacMethods['vandermonde'](self,*args) @@ -17982,10 +16561,9 @@ cdef class GiacMethods_base: Help for variables_are_files: variables_are_files(:=Intg(0 or 1)) Pseudo-variable to specify if you want to save the variables as file "nameofthevariable.cas". - See also: 1/ cas_setup + See also: 1/ cas_setup Ex1: variables_are_files:=1 Ex2: variables_are_files:=0 - ''' return GiacMethods['variables_are_files'](self,*args) @@ -17994,11 +16572,10 @@ cdef class GiacMethods_base: Help for variance: variance(Lst||Mtrx,[Lst]) Returns the variance of a list with the second argument as weights or the list of variances of the columns of a matrix. - See also: 1/ stddev 2/ mean + See also: 1/ stddev 2/ mean Ex1:variance([3,4,2]) Ex2:variance([1,2,3],[1,2,1]) Ex3:variance([[1,2,3],[5,6,7]]) - ''' return GiacMethods['variance'](self,*args) @@ -18007,9 +16584,8 @@ cdef class GiacMethods_base: Help for version: version(NULL) Returns the giac version number; for example, you are using : giac 0.4.0 - See also: 1/ + See also: 1/ Ex1:version() - ''' return GiacMethods['version'](self,*args) @@ -18018,11 +16594,10 @@ cdef class GiacMethods_base: Help for vertex_connectivity: vertex_connectivity(Graph(G)) Returns the largest integer k such that undirected connected graph G remains connected when fewer than k vertices are removed. - See also: 1/ edge_connectivity 2/ is_connected + See also: 1/ edge_connectivity 2/ is_connected Ex1:vertex_connectivity(graph("petersen")) Ex2:vertex_connectivity(graph("clebsch")) Ex3:vertex_connectivity(complete_graph(5)) - ''' return GiacMethods['vertex_connectivity'](self,*args) @@ -18031,9 +16606,8 @@ cdef class GiacMethods_base: Help for vertex_degree: vertex_degree(Graph(G),Vrtx(v)) Returns the degree of the vertex v in G (i.e. the number of edges incident to v). - See also: 1/ degree_sequence 2/ is_regular 3/ maximum_degree 4/ minimum_degree 5/ vertex_in_degree 6/ vertex_out_degree + See also: 1/ degree_sequence 2/ is_regular 3/ maximum_degree 4/ minimum_degree 5/ vertex_in_degree 6/ vertex_out_degree Ex1:vertex_degree(digraph(trail(1,2,3,4,2)),2) - ''' return GiacMethods['vertex_degree'](self,*args) @@ -18042,10 +16616,9 @@ cdef class GiacMethods_base: Help for vertex_distance: vertex_distance(Graph(G),Vrtx(s),Vrtx(t)||Lst(T)) Returns the number of edges in the shortest path from vertex s to vertex t in G. If such path does not exist, returns +infinity. For vector T of vertices from G returns the list of distances from s to each vertex t in T. - See also: 1/ allpairs_distance 2/ graph_diameter 3/ dijkstra 4/ shortest_path + See also: 1/ allpairs_distance 2/ graph_diameter 3/ dijkstra 4/ shortest_path Ex1:vertex_distance(graph("petersen"),1,4) Ex2:vertex_distance(graph("petersen"),1,[2,4]) - ''' return GiacMethods['vertex_distance'](self,*args) @@ -18054,9 +16627,8 @@ cdef class GiacMethods_base: Help for vertex_in_degree: vertex_in_degree(Graph(G),Vrtx(v)) Returns the number of arcs in G entering the vertex v. - See also: 1/ degree_sequence 2/ is_regular 3/ maximum_degree 4/ minimum_degree 5/ vertex_degree 6/ vertex_out_degree + See also: 1/ degree_sequence 2/ is_regular 3/ maximum_degree 4/ minimum_degree 5/ vertex_degree 6/ vertex_out_degree Ex1:vertex_in_degree(digraph(trail(1,2,3,4,2)),2) - ''' return GiacMethods['vertex_in_degree'](self,*args) @@ -18065,9 +16637,8 @@ cdef class GiacMethods_base: Help for vertex_out_degree: vertex_out_degree(Graph(G),Vrtx(v)) Returns the number of arcs in G emanating from the vertex v. - See also: 1/ degree_sequence 2/ is_regular 3/ maximum_degree 4/ minimum_degree 5/ vertex_degree 6/ vertex_in_degree + See also: 1/ degree_sequence 2/ is_regular 3/ maximum_degree 4/ minimum_degree 5/ vertex_degree 6/ vertex_in_degree Ex1:vertex_out_degree(digraph(trail(1,2,3,4,2)),2) - ''' return GiacMethods['vertex_out_degree'](self,*args) @@ -18076,11 +16647,10 @@ cdef class GiacMethods_base: Help for vertices: vertices(Polygon or Polyedr(P)) Returns the list of the vertices of the polygon or polyhedron P. - See also: 1/ isosceles_triangle 2/ polyhedron + See also: 1/ isosceles_triangle 2/ polyhedron Ex1:vertices(isosceles_triangle(0,1,pi/4)) Ex2:vertices(polyhedron([0,0,0],[0,5,0],[0,0,5],[1,2,6])) Ex3:vertices(isosceles_triangle(0,1,pi/4))[2] - ''' return GiacMethods['vertices'](self,*args) @@ -18089,11 +16659,10 @@ cdef class GiacMethods_base: Help for vertices_abc: vertices_abc(Polygon or Polyedr(P)) Returns the list of the vertices of the polygon or polyhedron P. - See also: 1/ isosceles_triangle 2/ polyhedron + See also: 1/ isosceles_triangle 2/ polyhedron Ex1:vertices_abc(isosceles_triangle(0,1,pi/4)) Ex2:vertices_abc(polyhedron([0,0,0],[0,5,0],[0,0,5],[1,2,6])) Ex3:vertices_abc(isosceles_triangle(0,1,pi/4))[2] - ''' return GiacMethods['vertices_abc'](self,*args) @@ -18102,11 +16671,10 @@ cdef class GiacMethods_base: Help for vertices_abca: vertices_abca(Polygon or Polyedr(P)) Returns the closed list [A,B,...A] of the vertices of the polygon or polyhedron P. - See also: 1/ isosceles_triangle 2/ polyhedron + See also: 1/ isosceles_triangle 2/ polyhedron Ex1:vertices_abca(isosceles_triangle(0,1,pi/4)) Ex2:vertices_abca(polyhedron([0,0,0],[0,5,0],[0,0,5],[1,2,6])) Ex3:vertices_abca(isosceles_triangle(0,1,pi/4))[2] - ''' return GiacMethods['vertices_abca'](self,*args) @@ -18115,9 +16683,8 @@ cdef class GiacMethods_base: Help for vpotential: vpotential(Vect(V),LstVar) Returns U such that curl(U)=V. - See also: 1/ curl 2/ potential + See also: 1/ curl 2/ potential Ex1:vpotential([2*x*y+3,x^2-4*z,-2*y*z],[x,y,z]) - ''' return GiacMethods['vpotential'](self,*args) @@ -18126,9 +16693,8 @@ cdef class GiacMethods_base: Help for web_graph: web_graph(Intg(a),Intg(b)) Returns a web graph on a*b vertices, where a>=3 and b>=2. - See also: 1/ prism_graph 2/ wheel_graph + See also: 1/ prism_graph 2/ wheel_graph Ex1:web_graph(5,3) - ''' return GiacMethods['web_graph'](self,*args) @@ -18137,11 +16703,10 @@ cdef class GiacMethods_base: Help for weibull: weibull(Real(k),Real(lambda),Real(theta),Real(x)) Returns the density of probability at x of the Weibull law with parameters k, lambda, theta (by default theta=0). - See also: 1/ weibull_cdf 2/ weibull_icdf + See also: 1/ weibull_cdf 2/ weibull_icdf Ex1:weibull(2.1,1.2,1.3) Ex2:weibull(2.1,1.2,0.0,1.3) Ex3:weibull(2.1,1.2,0.5,1.8) - ''' return GiacMethods['weibull'](self,*args) @@ -18150,13 +16715,12 @@ cdef class GiacMethods_base: Help for weibull_cdf: weibull_cdf(Real(k),Real(lambda),Real(theta),Real(x0)) Returns the probability that a Weibull random variable of parameters k, lambda, theta is less than x0. - See also: 1/ weibulld 2/ weibull_icdf + See also: 1/ weibulld 2/ weibull_icdf Ex1:weibull_cdf(2.1,1.2,1.9) Ex2:weibull_cdf(2.1,1.2,0.0,1.9) Ex3:weibull_cdf(2.2,1.5,0.4,1.9) Ex4:weibull_cdf(2.2,1.5,0.4,1.2) Ex5:weibull_cdf(2.2,1.5,0.4,1.2,1.9) - ''' return GiacMethods['weibull_cdf'](self,*args) @@ -18165,10 +16729,9 @@ cdef class GiacMethods_base: Help for weibull_icdf: weibull_icdf(Real(k),Real(lambda),Real(theta),Real(p)) Returns h such that the probability that a Weibull random variable of parameters k, lambda, theta is less than h is p (0<=p<=1). - See also: 1/ weibull_cdf 2/ weibull + See also: 1/ weibull_cdf 2/ weibull Ex1:weibull_icdf(4.2,1.3,0.0,0.95) Ex2:weibull_icdf(2.2,1.5,0.4,0.632) - ''' return GiacMethods['weibull_icdf'](self,*args) @@ -18177,11 +16740,10 @@ cdef class GiacMethods_base: Help for weibulld: weibulld(Real(k),Real(lambda),Real(theta),Real(x)) Returns the density of probability at x of the Weibull law with parameters k, lambda, theta (by default theta=0). - See also: 1/ weibull_cdf 2/ weibull_icdf + See also: 1/ weibull_cdf 2/ weibull_icdf Ex1:weibulld(2.1,1.2,1.3) Ex2:weibulld(2.1,1.2,0.0,1.3) Ex3:weibulld(2.1,1.2,0.5,1.8) - ''' return GiacMethods['weibulld'](self,*args) @@ -18190,13 +16752,12 @@ cdef class GiacMethods_base: Help for weibulld_cdf: weibulld_cdf(Real(k),Real(lambda),Real(theta),Real(x0)) Returns the probability that a Weibull random variable of parameters k, lambda, theta is less than x0. - See also: 1/ weibulld 2/ weibull_icdf + See also: 1/ weibulld 2/ weibull_icdf Ex1:weibulld_cdf(2.1,1.2,1.9) Ex2:weibulld_cdf(2.1,1.2,0.0,1.9) Ex3:weibulld_cdf(2.2,1.5,0.4,1.9) Ex4:weibulld_cdf(2.2,1.5,0.4,1.2) Ex5:weibulld_cdf(2.2,1.5,0.4,1.2,1.9) - ''' return GiacMethods['weibulld_cdf'](self,*args) @@ -18205,10 +16766,9 @@ cdef class GiacMethods_base: Help for weibulld_icdf: weibulld_icdf(Real(k),Real(lambda),Real(theta),Real(p)) Returns h such that the probability that a Weibull random variable of parameters k, lambda, theta is less than h is p (0<=p<=1). - See also: 1/ weibull_cdf 2/ weibull + See also: 1/ weibull_cdf 2/ weibull Ex1:weibulld_icdf(4.2,1.3,0.0,0.95) Ex2:weibulld_icdf(2.2,1.5,0.4,0.632) - ''' return GiacMethods['weibulld_icdf'](self,*args) @@ -18217,10 +16777,9 @@ cdef class GiacMethods_base: Help for weibullvariate: weibullvariate(Real(a),Real(b)) Returns a random real according to the Weibull distribution with parameters a>0 and b>0. - See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector + See also: 1/ rand 2/ randpoly 3/ randnorm 4/ randvector Ex1:weibullvariate(1,2) Ex2:weibullvariate(1.5,4) - ''' return GiacMethods['weibullvariate'](self,*args) @@ -18229,9 +16788,8 @@ cdef class GiacMethods_base: Help for weight_matrix: weight_matrix(Graph(G)) Returns the weight matrix of G. - See also: 1/ set_edge_weight 2/ get_edge_weights 3/ is_weighted 4/ make_weighted 5/ assign_edge_weights + See also: 1/ set_edge_weight 2/ get_edge_weights 3/ is_weighted 4/ make_weighted 5/ assign_edge_weights Ex1:weight_matrix(graph(%{[[1,2],2],[[2,3],1]%}) - ''' return GiacMethods['weight_matrix'](self,*args) @@ -18240,8 +16798,7 @@ cdef class GiacMethods_base: Help for weighted: weighted(Opt) Option for graph and digraph commands. - See also: 1/ directed 2/ graph 3/ digraph - + See also: 1/ directed 2/ graph 3/ digraph ''' return GiacMethods['weighted'](self,*args) @@ -18250,8 +16807,7 @@ cdef class GiacMethods_base: Help for weights: weights(Opt) Option for the edges command. - See also: 1/ edges - + See also: 1/ edges ''' return GiacMethods['weights'](self,*args) @@ -18260,9 +16816,8 @@ cdef class GiacMethods_base: Help for welch_window: welch_window(Lst,[Interval(n1..n2)]) Applies the Welch windowing function to the given signal u (or to the elements with indices between n1 and n2) and returns the result in a new list. - See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ bartlett_hann_window + See also: 1/ blackman_harris_window 2/ blackman_window 3/ bohman_window 4/ cosine_window 5/ gaussian_window 6/ hamming_window 7/ hann_poisson_window 8/ hann_window 9/ parzen_window 10/ poisson_window 11/ riemann_window 12/ triangle_window 13/ tukey_window 14/ bartlett_hann_window Ex1: scatterplot(welch_window(randvector(1000,0..1))) - ''' return GiacMethods['welch_window'](self,*args) @@ -18271,9 +16826,8 @@ cdef class GiacMethods_base: Help for wheel_graph: wheel_graph(Intg(n)) Returns a wheel graph with n+1 vertices. - See also: 1/ star_graph 2/ web_graph + See also: 1/ star_graph 2/ web_graph Ex1:wheel_graph(5) - ''' return GiacMethods['wheel_graph'](self,*args) @@ -18282,11 +16836,10 @@ cdef class GiacMethods_base: Help for widget_size: widget_size(Intg(n)) Changes the character sizes of the display on the xcas screen (size=n) and with more parameters define the general configuration. - See also: 1/ cas_setup + See also: 1/ cas_setup Ex1:widget_size(20) Ex2:widget_size(8) Ex3:widget_size(20,58,49,697,563,1,1,0) - ''' return GiacMethods['widget_size'](self,*args) @@ -18295,10 +16848,9 @@ cdef class GiacMethods_base: Help for wilcoxonp: wilcoxonp(Intg,[Intg]) Distribution of the Wilcoxon or Mann-Whitney test for one or two samples. - See also: 1/ wilcoxont 2/ wilcoxons + See also: 1/ wilcoxont 2/ wilcoxons Ex1:wilcoxonp(4) Ex2:wilcoxonp(7,5) - ''' return GiacMethods['wilcoxonp'](self,*args) @@ -18307,10 +16859,9 @@ cdef class GiacMethods_base: Help for wilcoxons: wilcoxons(List,List || Real) Rank statistic of Wilcoxon or Mann-Whitney for 1 sample and one median or 2 samples. - See also: 1/ wilcoxont 2/ wilcoxonp + See also: 1/ wilcoxont 2/ wilcoxonp Ex1:wilcoxons([1, 3, 4, 5, 7, 8, 8, 12, 15, 17] , [2, 6, 10, 11, 13, 14, 15, 18, 19, 20]) Ex2:wilcoxons([1, 3, 4, 5, 7, 8, 8, 12, 15, 17] , 10) - ''' return GiacMethods['wilcoxons'](self,*args) @@ -18319,12 +16870,11 @@ cdef class GiacMethods_base: Help for wilcoxont: wilcoxont(List,List || Real,[Func],[Real]) Wilcoxon or Mann-Whitney test for one sample and a median or 2 samples. - See also: 1/ wilcoxonp 2/ wilcoxons 3/ studentt 4/ normalt + See also: 1/ wilcoxonp 2/ wilcoxons 3/ studentt 4/ normalt Ex1:wilcoxont([1, 3, 4, 5, 7, 8, 8, 12, 15, 17] , [2, 6, 10, 11, 13, 14, 15, 18, 19, 20]) Ex2:wilcoxont([1, 3, 4, 5, 7, 8, 8, 12, 15, 17] , [2, 6, 10, 11, 13, 14, 15, 18, 19, 20],0.01) Ex3:wilcoxont([1, 3, 4, 5, 7, 8, 8, 12, 15, 17] , 10,'>') Ex4:wilcoxont([1, 3, 4, 5, 7, 8, 8, 12, 15, 17] , 10,'>',0.05) - ''' return GiacMethods['wilcoxont'](self,*args) @@ -18333,11 +16883,10 @@ cdef class GiacMethods_base: Help for writergb: writergb(Str(s),Lst) Write a PNG picture file named s either from a list [[number_channels,width,height],red,green,alpha,blue] where red,green,alpha,blue are matrices of pixels color or from a matrix of grey pixels or from 3 matrices of RGB colored pixels. - See also: 1/ readrgb + See also: 1/ readrgb Ex1:writergb("image.png",[[255,0],[0,255]]) Ex2:writergb("image.png",[[255,0],[0,0]],[[0,255],[0,0]],[[0,0],[255,0]]) Ex3: a:=readrgb("rgb_image.png");writergb("brg_image.png",[a[0],a[4],a[1],a[3],a[2]]) - ''' return GiacMethods['writergb'](self,*args) @@ -18346,10 +16895,9 @@ cdef class GiacMethods_base: Help for writewav: writewav(Str(s),Lst(l)) Writes a WAV sound file. - See also: 1/ readwav + See also: 1/ readwav Ex1:writewav("la.wav",2^14*(sin(2*pi*440*soundsec(1)))) Ex2:writewav("beep.wav",[[1,16,44100,80000],[65000$10000,0$10000,65000$10000,0$10000]]) - ''' return GiacMethods['writewav'](self,*args) @@ -18358,10 +16906,9 @@ cdef class GiacMethods_base: Help for xcas_mode: xcas_mode(Intg(0) or 1 or 2 or 3) Switches to mode Xcas (0), Maple (1), Mupad (2), TI89 (3). - See also: 1/ python_compat + See also: 1/ python_compat Ex1:xcas_mode(1) Ex2:xcas_mode(0) - ''' return GiacMethods['xcas_mode'](self,*args) @@ -18370,9 +16917,8 @@ cdef class GiacMethods_base: Help for xml_print: xml_print(Str) Indents a XML code given in a string (pretty print). - See also: 1/ export_mathml + See also: 1/ export_mathml Ex1:xml_print(export_mathml(a+2*b)) - ''' return GiacMethods['xml_print'](self,*args) @@ -18382,7 +16928,6 @@ cdef class GiacMethods_base: xyztrange(SeqReal) xyztrange puts or erases the axes on the graphic-screen (cf button Cfg). Ex1:xyztrange(-5.0,5.0,-5.0,2.0,-10.0,10.0,-1.0,6.0,-5.0,5.0,-1.2384,2.0,1,0.0,1.0) - ''' return GiacMethods['xyztrange'](self,*args) @@ -18391,12 +16936,11 @@ cdef class GiacMethods_base: Help for zeros: zeros(Expr,[Var]) Returns the zeros (real or complex according to the mode) of the expression (or the matrix where the lines are the solutions of the system : expression1=0,expression2=0...). - See also: 1/ + See also: 1/ Ex1:zeros(x^2+4) Ex2:zeros(ln(x)^2-4) Ex3:zeros(ln(y)^2-2,y) Ex4:zeros([x^2-1,x^2-y^2],[x,y]) - ''' return GiacMethods['zeros'](self,*args) @@ -18405,10 +16949,9 @@ cdef class GiacMethods_base: Help for ztrans: ztrans(Expr,[Var],[ZtransVar]) z transform of a sequence. - See also: 1/ invztrans 2/ laplace 3/ invlaplace + See also: 1/ invztrans 2/ laplace 3/ invlaplace Ex1:ztrans(a^x) Ex2:ztrans(a^n,n,z) - ''' return GiacMethods['ztrans'](self,*args) @@ -18417,10 +16960,9 @@ cdef class GiacMethods_base: Help for type: type(Expr) Returns n in [1..12] that defines the type of the argument. - See also: 1/ DOM_FLOAT 2/ DOM_INT 3/ DOM_COMPLEX 4/ DOM_IDENT 5/ DOM_LIST 6/ DOM_SYMBOLIC 7/ DOM_RAT 8/ DOM_STRING 9/ DOM_FUNC 10/ subtype + See also: 1/ DOM_FLOAT 2/ DOM_INT 3/ DOM_COMPLEX 4/ DOM_IDENT 5/ DOM_LIST 6/ DOM_SYMBOLIC 7/ DOM_RAT 8/ DOM_STRING 9/ DOM_FUNC 10/ subtype Ex1:type("abc") Ex2:type([1,2,3]) - ''' return GiacMethods['type'](self,*args) @@ -18429,12 +16971,11 @@ cdef class GiacMethods_base: Help for zip: zip(Fnc2d(f),Lst(l1),Lst(l2),[Val(default)]) Returns a list whose j-th entry is f(l1[j],l2[j]): without default value its length is the minimum of the lengths of the two input lists and otherwise the shorter list is padded with the default value. - See also: 1/ + See also: 1/ Ex1:zip('+',[a,b,c,d], [1,2,3,4]) Ex2:zip('+',[a,b,c,d], [1,2,3]) Ex3:zip('+',[a,b,c,d], [1,2,3],5) Ex4:zip(sum,[a,b,c,d], [1,2,3,4]) - ''' return GiacMethods['zip'](self,*args) diff --git a/src/sage/libs/giac/giac.pyx b/src/sage/libs/giac/giac.pyx index 111cd284ef8..3042220118c 100644 --- a/src/sage/libs/giac/giac.pyx +++ b/src/sage/libs/giac/giac.pyx @@ -303,7 +303,7 @@ def _giac(s): sage: A = libgiac.table(()); A # create an empty giac table table( ) - sage: A[2,3] = 33; A[0,2] = '2/7' # set non zero entries of the sparse matrix + sage: A[2,3] = 33; A[0,2] = '2/7' # set nonzero entries of the sparse matrix sage: A*A # basic matrix operation are supported with sparse matrices table( (0,3) = 66/7 @@ -538,7 +538,6 @@ def _giac(s): - *Set* * ``intersect``, ``minus``, ``union``, ``is_element``, ``is_included`` - """ return Pygen(s).eval() @@ -548,7 +547,7 @@ def _giac(s): ####################################### cdef class GiacSetting(Pygen): """ - A class to customise the Computer Algebra System settings + A class to customise the Computer Algebra System settings. EXAMPLES:: @@ -907,7 +906,6 @@ cdef class Pygen(GiacMethods_base): sage: from sage.libs.giac.giac import libgiac sage: l=libgiac("seq[]");len(l) # 29552 comment28 0 - """ if (self._type == 7): sig_on() @@ -1045,7 +1043,7 @@ cdef class Pygen(GiacMethods_base): def __iter__(self): """ - Pygen lists of 10^6 elements should be yield + Pygen lists of 10^6 elements should be yield. TESTS:: @@ -1262,7 +1260,7 @@ cdef class Pygen(GiacMethods_base): def redim(self, a, b=None): """ - Increase the size of a matrix when possible, otherwise return self. + Increase the size of a matrix when possible, otherwise return ``self``. EXAMPLES:: @@ -1289,7 +1287,7 @@ cdef class Pygen(GiacMethods_base): # def htmlhelp(self, str lang='en'): # """ - # Open the giac html detailled help about self in an external browser + # Open the giac html detailled help about ``self`` in an external browser # There are currently 3 supported languages: 'en', 'fr', 'el' @@ -1346,7 +1344,7 @@ cdef class Pygen(GiacMethods_base): def _integer_(self,Z=None): """ - Convert giac integers or modular integers to sage Integers (via gmp) + Convert giac integers or modular integers to sage Integers (via gmp). EXAMPLES:: @@ -1360,11 +1358,10 @@ cdef class Pygen(GiacMethods_base): sage: c=libgiac('2 % nextprime(2**40)') sage: ZZ(c^1000) -233775163595 - sage: Mod(2,next_prime(2^40))^1000 - ZZ(c^1000) + sage: Mod(2,next_prime(2^40))^1000 - ZZ(c^1000) 0 sage: 2^320-(c^320).sage() 0 - """ cdef Integer n = PY_NEW(Integer) typ = self._type @@ -1395,7 +1392,7 @@ cdef class Pygen(GiacMethods_base): def _rational_(self, Z=None): """ - Convert giac rationals to sage rationals + Convert giac rationals to sage rationals. EXAMPLES:: @@ -1473,7 +1470,6 @@ cdef class Pygen(GiacMethods_base): sage: sage.symbolic.expression.register_symbol(sin, {'giac':'myFun'}) sage: ex.sage() sin(x) - """ typ = self._type @@ -1513,8 +1509,7 @@ cdef class Pygen(GiacMethods_base): def _symbolic_(self, R): r""" - Convert self object to the ring R via a basic string evaluation. (slow) - + Convert ``self`` object to the ring R via a basic string evaluation. (slow) EXAMPLES:: @@ -1563,7 +1558,6 @@ cdef class Pygen(GiacMethods_base): Return matrix over the (Sage) ring R where self should be a Giac matrix. The default ring is ZZ. - EXAMPLES:: sage: from sage.libs.giac.giac import * @@ -1598,7 +1592,6 @@ cdef class Pygen(GiacMethods_base): Return vector over the (Sage) ring R where self should be a Giac matrix. The default ring is ZZ. - EXAMPLES:: sage: from sage.libs.giac.giac import * diff --git a/src/sage/libs/gmp/pylong.pyx b/src/sage/libs/gmp/pylong.pyx index 30366841177..41587396120 100644 --- a/src/sage/libs/gmp/pylong.pyx +++ b/src/sage/libs/gmp/pylong.pyx @@ -57,7 +57,7 @@ cdef size_t PyLong_nails = 8*sizeof(digit) - PyLong_SHIFT cdef mpz_get_pylong_large(mpz_srcptr z): """ - Convert a non-zero ``mpz`` to a Python ``long``. + Convert a nonzero ``mpz`` to a Python ``long``. """ cdef size_t nbits = mpz_sizeinbase(z, 2) cdef size_t pylong_size = (nbits + PyLong_SHIFT - 1) // PyLong_SHIFT diff --git a/src/sage/libs/homfly.pyx b/src/sage/libs/homfly.pyx index 550c5f02a65..b051e67cc63 100644 --- a/src/sage/libs/homfly.pyx +++ b/src/sage/libs/homfly.pyx @@ -57,11 +57,9 @@ def homfly_polynomial_string(link): INPUT: - - ``link`` -- a string of space-separated integers representing the link + - ``link`` -- string of space-separated integers representing the link - OUTPUT: - - A string with the HOMFLY polynomial in the variables `M` and `L` + OUTPUT: string with the HOMFLY polynomial in the variables `M` and `L` EXAMPLES:: @@ -83,11 +81,7 @@ def homfly_polynomial_dict(link): INPUT: - - ``link`` -- a string of space-separated integers representing the link - - OUTPUT: - - A dictionary representing the HOMFLY polynomial. + - ``link`` -- string of space-separated integers representing the link EXAMPLES:: diff --git a/src/sage/libs/lcalc/lcalc_Lfunction.pyx b/src/sage/libs/lcalc/lcalc_Lfunction.pyx index 87023b47741..c528b136f93 100644 --- a/src/sage/libs/lcalc/lcalc_Lfunction.pyx +++ b/src/sage/libs/lcalc/lcalc_Lfunction.pyx @@ -55,7 +55,7 @@ cdef class Lfunction: def __init__(self, name, what_type_L, dirichlet_coefficient, period, Q, OMEGA, gamma, lambd, pole, residue): """ - Initialization of L-function objects. + Initialization of `L`-function objects. See derived class for details, this class is not supposed to be instantiated directly. @@ -113,7 +113,7 @@ cdef class Lfunction: def __repr__(self): """ - Return string representation of this L-function. + Return string representation of this `L`-function. EXAMPLES:: @@ -128,27 +128,27 @@ cdef class Lfunction: def value(self, s, derivative=0): """ - Computes the value of the L-function at ``s`` + Compute the value of the `L`-function at ``s``. INPUT: - - ``s`` -- a complex number - - ``derivative`` -- integer (default: 0) the derivative to be evaluated - - ``rotate`` -- (default: ``False``) If True, this returns the value of the + - ``s`` -- a complex number + - ``derivative`` -- integer (default: 0); the derivative to be evaluated + - ``rotate`` -- boolean (default: ``False``); if True, this returns the value of the Hardy Z-function (sometimes called the Riemann-Siegel Z-function or - the Siegel Z-function). + the Siegel Z-function) EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] # This is a quadratic character - sage: L = Lfunction_from_character(chi, type="int") + sage: L = Lfunction_from_character(chi, type='int') sage: (L.value(0.5) - 0.231750947504016).abs() < 1e-8 True sage: v = L.value(0.2 + 0.4*I) sage: (v - (0.102558603193 + 0.190840777924*I)).abs() < 1e-8 True - sage: L = Lfunction_from_character(chi, type="double") + sage: L = Lfunction_from_character(chi, type='double') sage: (L.value(0.6) - 0.274633355856345).abs() < 1e-8 True sage: v = L.value(0.6 + I) @@ -159,7 +159,7 @@ cdef class Lfunction: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[1] - sage: L = Lfunction_from_character(chi, type="complex") + sage: L = Lfunction_from_character(chi, type='complex') sage: v = L.value(0.5) sage: (v - (0.763747880117 + 0.21696476751*I)).abs() < 1e-8 True @@ -176,7 +176,6 @@ cdef class Lfunction: sage: v = L.value(0.4 + 0.5*I) sage: (v - (-0.450728958517 - 0.780511403019*I)).abs() < 1e-8 True - """ cdef ComplexNumber complexified_s = CCC(s) cdef c_Complex z = new_Complex(mpfr_get_d(complexified_s.__re, MPFR_RNDN), mpfr_get_d(complexified_s.__im, MPFR_RNDN)) @@ -185,7 +184,7 @@ cdef class Lfunction: def hardy_z_function(self, s): """ - Computes the Hardy Z-function of the L-function at s + Compute the Hardy Z-function of the `L`-function at s. INPUT: @@ -195,7 +194,7 @@ cdef class Lfunction: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] # Quadratic character - sage: L = Lfunction_from_character(chi, type="int") + sage: L = Lfunction_from_character(chi, type='int') sage: (L.hardy_z_function(0) - 0.231750947504).abs() < 1e-8 True sage: L.hardy_z_function(0.5).imag().abs() < 1e-8 @@ -205,7 +204,7 @@ cdef class Lfunction: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[1] - sage: L = Lfunction_from_character(chi, type="complex") + sage: L = Lfunction_from_character(chi, type='complex') sage: (L.hardy_z_function(0) - 0.793967590477).abs() < 1e-8 True sage: L.hardy_z_function(0.5).imag().abs() < 1e-8 @@ -218,7 +217,6 @@ cdef class Lfunction: sage: L = Lfunction_from_elliptic_curve(E, number_of_coeffs=40000) sage: (L.hardy_z_function(2.1) - (-0.006431791768)).abs() < 1e-8 True - """ #This takes s -> .5 + I*s cdef ComplexNumber complexified_s = CCC(0.5)+ CCC(0,1)*CCC(s) @@ -228,14 +226,14 @@ cdef class Lfunction: def compute_rank(self): """ - Computes the analytic rank (the order of vanishing at the center) of - of the L-function + Compute the analytic rank (the order of vanishing at the center) of + of the `L`-function. EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] # This is a quadratic character - sage: L = Lfunction_from_character(chi, type="int") + sage: L = Lfunction_from_character(chi, type='int') sage: L.compute_rank() 0 @@ -246,7 +244,6 @@ cdef class Lfunction: sage: L = Lfunction_from_elliptic_curve(E, number_of_coeffs=40000) sage: L.compute_rank() 3 - """ return self._compute_rank() @@ -260,7 +257,7 @@ cdef class Lfunction: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] #This is a quadratic character - sage: L=Lfunction_from_character(chi, type="complex") + sage: L=Lfunction_from_character(chi, type='complex') sage: L._N(10) # abs tol 1e-8 4.0 """ @@ -273,9 +270,9 @@ cdef class Lfunction: """ Finds zeros on critical line between ``T1`` and ``T2`` using step size of stepsize. This function might miss zeros if step size is too - large. This function computes the zeros of the L-function by using + large. This function computes the zeros of the `L`-function by using change in signs of areal valued function whose zeros coincide with - the zeros of L-function. + the zeros of `L`-function. Use :meth:`find_zeros_via_N` for slower but more rigorous computation. @@ -285,18 +282,16 @@ cdef class Lfunction: - ``T2`` -- a real number giving the upper bound - ``stepsize`` -- step size to be used for the zero search - OUTPUT: - - list -- A list of the imaginary parts of the zeros which were found. + OUTPUT: list of the imaginary parts of the zeros which were found EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] # This is a quadratic character - sage: L = Lfunction_from_character(chi, type="int") + sage: L = Lfunction_from_character(chi, type='int') sage: L.find_zeros(5,15,.1) [6.64845334472..., 9.83144443288..., 11.9588456260...] - sage: L = Lfunction_from_character(chi, type="double") + sage: L = Lfunction_from_character(chi, type='double') sage: L.find_zeros(1,15,.1) [6.64845334472..., 9.83144443288..., 11.9588456260...] @@ -304,7 +299,7 @@ cdef class Lfunction: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[1] - sage: L = Lfunction_from_character(chi, type="complex") + sage: L = Lfunction_from_character(chi, type='complex') sage: L.find_zeros(-8,8,.1) [-4.13290370521..., 6.18357819545...] @@ -338,7 +333,7 @@ cdef class Lfunction: their imaginary parts. This function verifies that no zeros are missed, and that all values output are indeed zeros. - If this L-function is self-dual (if its Dirichlet coefficients + If this `L`-function is self-dual (if its Dirichlet coefficients are real, up to a tolerance of 1e-6), then only the zeros with positive imaginary parts are output. Their conjugates, which are also zeros, are not output. @@ -351,22 +346,20 @@ cdef class Lfunction: size used to find zeros is refined. max_refine gives an upper limit on when lcalc should give up. Use default value unless you know what you are doing. - - ``rank`` -- integer (default: -1) analytic rank of the L-function. + - ``rank`` -- integer (default: -1); analytic rank of the `L`-function. If -1 is passed, then we attempt to compute it. (Use default if in doubt) - OUTPUT: - - list -- A list of the imaginary parts of the zeros that have been found + OUTPUT: list of the imaginary parts of the zeros that have been found EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] #This is a quadratic character - sage: L = Lfunction_from_character(chi, type="int") + sage: L = Lfunction_from_character(chi, type='int') sage: L.find_zeros_via_N(3) [6.64845334472..., 9.83144443288..., 11.9588456260...] - sage: L = Lfunction_from_character(chi, type="double") + sage: L = Lfunction_from_character(chi, type='double') sage: L.find_zeros_via_N(3) [6.64845334472..., 9.83144443288..., 11.9588456260...] @@ -374,7 +367,7 @@ cdef class Lfunction: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[1] - sage: L = Lfunction_from_character(chi, type="complex") + sage: L = Lfunction_from_character(chi, type='complex') sage: zeros = L.find_zeros_via_N(3) sage: (zeros[0] - (-4.13290370521286)).abs() < 1e-8 True @@ -389,7 +382,6 @@ cdef class Lfunction: sage: L = Lfunction_Zeta() sage: L.find_zeros_via_N(3) [14.1347251417..., 21.0220396387..., 25.0108575801...] - """ # This is the default value for message_stamp, but we have to @@ -434,8 +426,8 @@ cdef class Lfunction: cdef class Lfunction_I(Lfunction): r""" - The ``Lfunction_I`` class is used to represent L-functions - with integer Dirichlet Coefficients. We assume that L-functions + The ``Lfunction_I`` class is used to represent `L`-functions + with integer Dirichlet Coefficients. We assume that `L`-functions satisfy the following functional equation. .. MATH:: @@ -452,43 +444,43 @@ cdef class Lfunction_I(Lfunction): INPUT: - - ``what_type_L`` -- integer, this should be set to 1 if the coefficients - are periodic and 0 otherwise. + - ``what_type_L`` -- integer; this should be set to 1 if the coefficients + are periodic and 0 otherwise - - ``dirichlet_coefficient`` -- List of Dirichlet coefficients of the - L-function. Only first `M` coefficients are needed if they are periodic. + - ``dirichlet_coefficient`` -- list of Dirichlet coefficients of the + `L`-function. Only first `M` coefficients are needed if they are periodic. - - ``period`` -- If the coefficients are periodic, this should be the - period of the coefficients. + - ``period`` -- if the coefficients are periodic, this should be the + period of the coefficients - - ``Q`` -- See above + - ``Q`` -- see above - - ``OMEGA`` -- See above + - ``OMEGA`` -- see above - - ``kappa`` -- List of the values of `\kappa_j` in the functional equation + - ``kappa`` -- list of the values of `\kappa_j` in the functional equation - - ``gamma`` -- List of the values of `\gamma_j` in the functional equation + - ``gamma`` -- list of the values of `\gamma_j` in the functional equation - - ``pole`` -- List of the poles of L-function + - ``pole`` -- list of the poles of `L`-function - - ``residue`` -- List of the residues of the L-function + - ``residue`` -- list of the residues of the `L`-function .. NOTE:: - If an L-function satisfies `\Lambda(s) = \omega Q^s \Lambda(k-s)`, + If an `L`-function satisfies `\Lambda(s) = \omega Q^s \Lambda(k-s)`, by replacing `s` by `s+(k-1)/2`, one can get it in the form we need. """ def __init__(self, name, what_type_L, dirichlet_coefficient, period, Q, OMEGA, gamma, lambd, pole, residue): r""" - Initialize an L-function with integer coefficients + Initialize an `L`-function with integer coefficients. EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] #This is a quadratic character - sage: L=Lfunction_from_character(chi, type="int") + sage: L=Lfunction_from_character(chi, type='int') sage: type(L) """ @@ -534,7 +526,7 @@ cdef class Lfunction_I(Lfunction): sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] #This is a quadratic character - sage: L=Lfunction_from_character(chi, type="int") + sage: L=Lfunction_from_character(chi, type='int') sage: L._print_data_to_standard_output() # tol 1e-8 ----------------------------------------------- @@ -566,13 +558,13 @@ cdef class Lfunction_I(Lfunction): del_c_Lfunction_I((self.thisptr)) ############################################################################## -# Lfunction_D: L-functions with double (real) Dirichlet Coefficients +# Lfunction_D: `L`-functions with double (real) Dirichlet Coefficients ############################################################################## cdef class Lfunction_D(Lfunction): r""" - The ``Lfunction_D`` class is used to represent L-functions - with real Dirichlet coefficients. We assume that L-functions + The ``Lfunction_D`` class is used to represent `L`-functions + with real Dirichlet coefficients. We assume that `L`-functions satisfy the following functional equation. .. MATH:: @@ -589,42 +581,42 @@ cdef class Lfunction_D(Lfunction): INPUT: - - ``what_type_L`` -- integer, this should be set to 1 if the coefficients are - periodic and 0 otherwise. + - ``what_type_L`` -- integer; this should be set to 1 if the coefficients are + periodic and 0 otherwise - - ``dirichlet_coefficient`` -- List of Dirichlet coefficients of the - L-function. Only first `M` coefficients are needed if they are periodic. + - ``dirichlet_coefficient`` -- list of Dirichlet coefficients of the + `L`-function. Only first `M` coefficients are needed if they are periodic. - - ``period`` -- If the coefficients are periodic, this should be the - period of the coefficients. + - ``period`` -- if the coefficients are periodic, this should be the + period of the coefficients - - ``Q`` -- See above + - ``Q`` -- see above - - ``OMEGA`` -- See above + - ``OMEGA`` -- see above - - ``kappa`` -- List of the values of `\kappa_j` in the functional equation + - ``kappa`` -- list of the values of `\kappa_j` in the functional equation - - ``gamma`` -- List of the values of `\gamma_j` in the functional equation + - ``gamma`` -- list of the values of `\gamma_j` in the functional equation - - ``pole`` -- List of the poles of L-function + - ``pole`` -- list of the poles of `L`-function - - ``residue`` -- List of the residues of the L-function + - ``residue`` -- list of the residues of the `L`-function .. NOTE:: - If an L-function satisfies `\Lambda(s) = \omega Q^s \Lambda(k-s)`, + If an `L`-function satisfies `\Lambda(s) = \omega Q^s \Lambda(k-s)`, by replacing `s` by `s+(k-1)/2`, one can get it in the form we need. """ def __init__(self, name, what_type_L, dirichlet_coefficient, period, Q, OMEGA, gamma, lambd, pole, residue): r""" - Initialize an L-function with real coefficients + Initialize an `L`-function with real coefficients. EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] #This is a quadratic character - sage: L=Lfunction_from_character(chi, type="double") + sage: L=Lfunction_from_character(chi, type='double') sage: type(L) """ @@ -671,7 +663,7 @@ cdef class Lfunction_D(Lfunction): sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[2] #This is a quadratic character - sage: L=Lfunction_from_character(chi, type="double") + sage: L=Lfunction_from_character(chi, type='double') sage: L._print_data_to_standard_output() # tol 1e-8 ----------------------------------------------- @@ -693,7 +685,6 @@ cdef class Lfunction_D(Lfunction): number of poles (of the completed L function) = 0 ----------------------------------------------- - """ (self.thisptr).print_data_L() @@ -709,8 +700,8 @@ cdef class Lfunction_D(Lfunction): cdef class Lfunction_C: r""" - The ``Lfunction_C`` class is used to represent L-functions - with complex Dirichlet Coefficients. We assume that L-functions + The ``Lfunction_C`` class is used to represent `L`-functions + with complex Dirichlet Coefficients. We assume that `L`-functions satisfy the following functional equation. .. MATH:: @@ -727,43 +718,43 @@ cdef class Lfunction_C: INPUT: - - ``what_type_L`` -- integer, this should be set to 1 if the coefficients are - periodic and 0 otherwise. + - ``what_type_L`` -- integer; this should be set to 1 if the coefficients are + periodic and 0 otherwise - - ``dirichlet_coefficient`` -- List of Dirichlet coefficients of the - L-function. Only first `M` coefficients are needed if they are periodic. + - ``dirichlet_coefficient`` -- list of Dirichlet coefficients of the + `L`-function. Only first `M` coefficients are needed if they are periodic. - - ``period`` -- If the coefficients are periodic, this should be the - period of the coefficients. + - ``period`` -- if the coefficients are periodic, this should be the + period of the coefficients - - ``Q`` -- See above + - ``Q`` -- see above - - ``OMEGA`` -- See above + - ``OMEGA`` -- see above - - ``kappa`` -- List of the values of `\kappa_j` in the functional equation + - ``kappa`` -- list of the values of `\kappa_j` in the functional equation - - ``gamma`` -- List of the values of `\gamma_j` in the functional equation + - ``gamma`` -- list of the values of `\gamma_j` in the functional equation - - ``pole`` -- List of the poles of L-function + - ``pole`` -- list of the poles of `L`-function - - ``residue`` -- List of the residues of the L-function + - ``residue`` -- list of the residues of the `L`-function .. NOTE:: - If an L-function satisfies `\Lambda(s) = \omega Q^s \Lambda(k-s)`, + If an `L`-function satisfies `\Lambda(s) = \omega Q^s \Lambda(k-s)`, by replacing `s` by `s+(k-1)/2`, one can get it in the form we need. """ def __init__(self, name, what_type_L, dirichlet_coefficient, period, Q, OMEGA, gamma, lambd, pole, residue): r""" - Initialize an L-function with complex coefficients + Initialize an `L`-function with complex coefficients. EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[1] - sage: L=Lfunction_from_character(chi, type="complex") + sage: L=Lfunction_from_character(chi, type='complex') sage: type(L) """ @@ -814,7 +805,7 @@ cdef class Lfunction_C: sage: from sage.libs.lcalc.lcalc_Lfunction import * sage: chi = DirichletGroup(5)[1] - sage: L=Lfunction_from_character(chi, type="complex") + sage: L=Lfunction_from_character(chi, type='complex') sage: L._print_data_to_standard_output() # tol 1e-8 ----------------------------------------------- @@ -836,8 +827,6 @@ cdef class Lfunction_C: number of poles (of the completed L function) = 0 ----------------------------------------------- - - """ (self.thisptr).print_data_L() @@ -898,35 +887,32 @@ cdef class Lfunction_Zeta(Lfunction): # Tools ############################################################################## -def Lfunction_from_character(chi, type="complex"): +def Lfunction_from_character(chi, type='complex'): """ Given a primitive Dirichlet character, this function returns - an lcalc L-function object for the L-function of the character. + an lcalc `L`-function object for the `L`-function of the character. INPUT: - - ``chi`` -- A Dirichlet character - - ``use_type`` -- string (default: "complex") type used for the Dirichlet - coefficients. This can be "int", "double" or "complex". + - ``chi`` -- a Dirichlet character + - ``use_type`` -- string (default: ``'complex'``); type used for the Dirichlet + coefficients. This can be ``'int'``, ``'double'`` or ``'complex'``. - OUTPUT: - - L-function object for ``chi``. + OUTPUT: `L`-function object for ``chi`` EXAMPLES:: sage: from sage.libs.lcalc.lcalc_Lfunction import Lfunction_from_character sage: Lfunction_from_character(DirichletGroup(5)[1]) L-function with complex Dirichlet coefficients - sage: Lfunction_from_character(DirichletGroup(5)[2], type="int") + sage: Lfunction_from_character(DirichletGroup(5)[2], type='int') L-function with integer Dirichlet coefficients - sage: Lfunction_from_character(DirichletGroup(5)[2], type="double") + sage: Lfunction_from_character(DirichletGroup(5)[2], type='double') L-function with real Dirichlet coefficients - sage: Lfunction_from_character(DirichletGroup(5)[1], type="int") + sage: Lfunction_from_character(DirichletGroup(5)[1], type='int') Traceback (most recent call last): ... ValueError: For non quadratic characters you must use type="complex" - """ if (not chi.is_primitive()): raise TypeError("Dirichlet character is not primitive") @@ -960,20 +946,18 @@ def Lfunction_from_character(chi, type="complex"): def Lfunction_from_elliptic_curve(E, number_of_coeffs=10000): """ - Given an elliptic curve E, return an L-function object for + Given an elliptic curve E, return an `L`-function object for the function `L(s, E)`. INPUT: - - ``E`` -- An elliptic curve - - ``number_of_coeffs`` -- integer (default: 10000) The number of - coefficients to be used when constructing the L-function object. Right + - ``E`` -- an elliptic curve + - ``number_of_coeffs`` -- integer (default: 10000); the number of + coefficients to be used when constructing the `L`-function object. Right now this is fixed at object creation time, and is not automatically set intelligently. - OUTPUT: - - L-function object for ``L(s, E)``. + OUTPUT: `L`-function object for ``L(s, E)`` EXAMPLES:: diff --git a/src/sage/libs/libecm.pyx b/src/sage/libs/libecm.pyx index 7df776b5d44..9d53d7284d4 100644 --- a/src/sage/libs/libecm.pyx +++ b/src/sage/libs/libecm.pyx @@ -73,12 +73,13 @@ def ecmfactor(number, double B1, verbose=False, sigma=0): - ``B1`` -- bound for step 1 of ECM - - ``verbose`` (default: ``False``) -- print some debugging information + - ``verbose`` -- boolean (default: ``False``); print some debugging + information OUTPUT: Either ``(False, None)`` if no factor was found, or ``(True, f)`` - if the factor ``f`` was found. + if the factor `f` was found. EXAMPLES:: diff --git a/src/sage/libs/linbox/conversion.pxd b/src/sage/libs/linbox/conversion.pxd index a443431adbb..9ca94ce79fd 100644 --- a/src/sage/libs/linbox/conversion.pxd +++ b/src/sage/libs/linbox/conversion.pxd @@ -83,8 +83,8 @@ cdef inline void set_linbox_matrix_modn_sparse(SparseMatrix_Modular_uint64& A, M INPUT: - - A -- LinBox matrix - - m -- Sage matrix + - ``A`` -- LinBox matrix + - ``m`` -- Sage matrix """ cdef c_vector_modint * row cdef size_t i, j @@ -101,8 +101,8 @@ cdef inline SparseMatrix_Modular_uint64 * new_linbox_matrix_modn_sparse(Modular_ INPUT: - - F -- LinBox field - - m -- Sage matrix + - ``F`` -- LinBox field + - ``m`` -- Sage matrix """ cdef SparseMatrix_Modular_uint64 * A = new SparseMatrix_Modular_uint64(F, m._nrows, m._ncols) set_linbox_matrix_modn_sparse(A[0], m) @@ -118,8 +118,8 @@ cdef inline void set_linbox_matrix_integer_sparse(SparseMatrix_integer& A, Matri INPUT: - - A -- LinBox matrix - - m -- Sage matrix + - ``A`` -- LinBox matrix + - ``m`` -- Sage matrix """ cdef size_t i, j, k cdef mpz_vector * v @@ -139,7 +139,7 @@ cdef inline SparseMatrix_integer * new_linbox_matrix_integer_sparse(ZRing &ZZ, M INPUT: - - m -- Sage matrix + - ``m`` -- Sage matrix """ cdef SparseMatrix_integer * A = new SparseMatrix_integer(ZZ, m._nrows, m._ncols) set_linbox_matrix_integer_sparse(A[0], m) @@ -155,7 +155,7 @@ cdef inline DenseVector_integer * new_linbox_vector_integer_dense(ZRing &ZZ, Vec INPUT: - - v -- a Sage dense integer vector + - ``v`` -- a Sage dense integer vector """ cdef cppvector[Integer] * vec = new cppvector[Integer]( v._degree) cdef size_t i @@ -173,8 +173,8 @@ cdef inline Vector_integer_dense new_sage_vector_integer_dense(P, DenseVector_in INPUT: - - P -- parent for the Sage vector - - v -- linbox vector + - ``P`` -- parent for the Sage vector + - ``v`` -- linbox vector """ cdef Vector_integer_dense res = P() cdef size_t i diff --git a/src/sage/libs/linkages/padics/API.pxi b/src/sage/libs/linkages/padics/API.pxi index ec69c5bbaa3..62e61551e07 100644 --- a/src/sage/libs/linkages/padics/API.pxi +++ b/src/sage/libs/linkages/padics/API.pxi @@ -17,11 +17,11 @@ file gives the function signatures. - :meth:`cadd` -- addition - :meth:`creduce` -- reduce modulo a power of the maximal ideal - :meth:`creduce_small` -- reduce modulo a power of the maximal ideal, - assuming only a single addition/subtraction. + assuming only a single addition/subtraction - :meth:`cremove` -- extract the maximum power of the uniformizer - dividing this element. + dividing this element - :meth:`cvaluation` -- return the maximum power of the uniformizer - dividing this element. + dividing this element - :meth:`cisunit` -- returns whether this element has valuation zero - :meth:`cshift` -- multiplies by a power of the uniformizer - :meth:`cshift_notrunc` -- multiplies by a power of the uniformizer, @@ -42,7 +42,7 @@ file gives the function signatures. - :meth:`chash` -- hashing - :meth:`cexpansion_next` -- gets the next digit in the series expansion - :meth:`cexpansion_getitem` -- gets a specified digit in the series expansion -- :meth:`ccoefficients` -- a list of coefficients as elements of the base ring +- :meth:`ccoefficients` -- list of coefficients as elements of the base ring - :meth:`cteichmuller` -- Teichmuller lifting - :meth:`cconv` -- conversion from other types in Sage - :meth:`cconv_mpz_t` -- conversion from mpz_t, separated for speed and @@ -83,8 +83,8 @@ cdef inline int cconstruct(celement value, PowComputer_class prime_pow) except - INPUT: - - ``unit`` -- an ``celement`` to be initialized. - - ``prime_pow`` -- the PowComputer for the ring. + - ``unit`` -- an ``celement`` to be initialized + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -94,8 +94,8 @@ cdef inline int cdestruct(celement value, PowComputer_class prime_pow) except -1 INPUT: - - ``unit`` -- an ``celement`` to be cleared. - - ``prime_pow`` -- the PowComputer for the ring. + - ``unit`` -- an ``celement`` to be cleared + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -105,12 +105,12 @@ cdef inline int ccmp(celement a, celement b, long prec, bint reduce_a, bint redu INPUT: - - ``a`` -- an ``celement``. - - ``b`` -- an ``celement``. - - ``prec`` -- a long, the precision of the comparison. - - ``reduce_a`` -- a bint, whether ``a`` needs to be reduced. - - ``reduce_b`` -- a bint, whether ``b`` needs to be reduced. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- an ``celement`` + - ``b`` -- an ``celement`` + - ``prec`` -- a long, the precision of the comparison + - ``reduce_a`` -- a bint, whether ``a`` needs to be reduced + - ``reduce_b`` -- a bint, whether ``b`` needs to be reduced + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: @@ -130,10 +130,10 @@ cdef inline int cneg(celement out, celement a, long prec, PowComputer_class prim INPUT: - - ``out`` -- an ``celement`` to store the negation. - - ``a`` -- an ``celement`` to be negated. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the negation + - ``a`` -- an ``celement`` to be negated + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -145,11 +145,11 @@ cdef inline int cadd(celement out, celement a, celement b, long prec, PowCompute INPUT: - - ``out`` -- an ``celement`` to store the sum. - - ``a`` -- an ``celement``, the first summand. - - ``b`` -- an ``celement``, the second summand. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the sum + - ``a`` -- an ``celement``, the first summand + - ``b`` -- an ``celement``, the second summand + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -159,14 +159,12 @@ cdef inline bint creduce(celement out, celement a, long prec, PowComputer_class INPUT: - - ``out`` -- an ``celement`` to store the reduction. - - ``a`` -- the element to be reduced. - - ``prec`` -- a long, the precision to reduce modulo. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the reduction + - ``a`` -- the element to be reduced + - ``prec`` -- a long, the precision to reduce modulo + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - returns True if the reduction is zero; False otherwise. + OUTPUT: returns ``True`` if the reduction is zero; ``False`` otherwise """ pass @@ -180,14 +178,14 @@ cdef inline bint creduce_small(celement out, celement a, long prec, PowComputer_ INPUT: - - ``out`` -- an ``celement`` to store the reduction. - - ``a`` -- the element to be reduced. - - ``prec`` -- a long, the precision to reduce modulo. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the reduction + - ``a`` -- the element to be reduced + - ``prec`` -- a long, the precision to reduce modulo + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: - - returns True if the reduction is zero; False otherwise. + - returns ``True`` if the reduction is zero; ``False`` otherwise. """ pass @@ -197,10 +195,10 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_class INPUT: - - ``out`` -- an ``celement`` to store the unit. - - ``a`` -- the element whose valuation and unit are desired. - - ``prec`` -- a long, used if `a = 0`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the unit + - ``a`` -- the element whose valuation and unit are desired + - ``prec`` -- a long, used if `a = 0` + - ``prime_pow`` -- the PowComputer for the ring - ``reduce_relative`` -- a bint: whether the final result should be reduced at precision ``prec`` (case ``False``) or ``prec - valuation`` (case ``True``) @@ -214,7 +212,7 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_class cdef inline long cvaluation(celement a, long prec, PowComputer_class prime_pow) except -1: """ - Returns the maximum power of the uniformizer dividing this + Return the maximum power of the uniformizer dividing this element. This function differs from :meth:`cremove` in that the unit is @@ -222,9 +220,9 @@ cdef inline long cvaluation(celement a, long prec, PowComputer_class prime_pow) INPUT: - - ``a`` -- the element whose valuation is desired. - - ``prec`` -- a long, used if `a = 0`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element whose valuation is desired + - ``prec`` -- a long, used if `a = 0` + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: @@ -235,53 +233,51 @@ cdef inline long cvaluation(celement a, long prec, PowComputer_class prime_pow) cdef inline bint cisunit(celement a, PowComputer_class prime_pow) except -1: """ - Returns whether this element has valuation zero. + Return whether this element has valuation zero. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - returns True if `a` has valuation 0, and False otherwise. + OUTPUT: returns ``True`` if `a` has valuation 0, and ``False`` otherwise """ pass cdef inline int cshift(celement out, celement rem, celement a, long n, long prec, PowComputer_class prime_pow, bint reduce_afterward) except -1: """ - Multiplies by a power of the uniformizer. + Multiply by a power of the uniformizer. INPUT: - ``out`` -- an ``celement`` to store the result. If `n >= 0` - then out will be set to `a * p^n`. + then out will be set to `a * p^n` If `n < 0`, out will be set to `a // p^-n`. - ``rem`` -- a ``celement`` to store the remainder, when `n < 0` - - ``a`` -- the element to shift. - - ``n`` -- long, the amount to shift by. - - ``prec`` -- long, a precision modulo which to reduce. - - ``prime_pow`` -- the PowComputer for the ring. - - ``reduce_afterward`` -- whether to reduce afterward. + - ``a`` -- the element to shift + - ``n`` -- long, the amount to shift by + - ``prec`` -- long, a precision modulo which to reduce + - ``prime_pow`` -- the PowComputer for the ring + - ``reduce_afterward`` -- whether to reduce afterward """ pass cdef inline int cshift_notrunc(celement out, celement a, long n, long prec, PowComputer_class prime_pow, bint reduce_afterward) except -1: """ - Multiplies by a power of the uniformizer, assuming that the + Multiply by a power of the uniformizer, assuming that the valuation of a is at least -n. INPUT: - ``out`` -- an ``celement`` to store the result. If `n >= 0` - then out will be set to `a * p^n`. + then out will be set to `a * p^n` If `n < 0`, out will be set to `a // p^-n`. - ``a`` -- the element to shift. Assumes that the valuation of a is at least -n. - - ``n`` -- long, the amount to shift by. - - ``prec`` -- long, a precision modulo which to reduce. - - ``prime_pow`` -- the PowComputer for the ring. - - ``reduce_afterward`` -- whether to reduce afterward. + - ``n`` -- long, the amount to shift by + - ``prec`` -- long, a precision modulo which to reduce + - ``prime_pow`` -- the PowComputer for the ring + - ``reduce_afterward`` -- whether to reduce afterward """ pass @@ -293,11 +289,11 @@ cdef inline int csub(celement out, celement a, celement b, long prec, PowCompute INPUT: - - ``out`` -- an ``celement`` to store the difference. - - ``a`` -- an ``celement``, the first input. - - ``b`` -- an ``celement``, the second input. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the difference + - ``a`` -- an ``celement``, the first input + - ``b`` -- an ``celement``, the second input + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -309,10 +305,10 @@ cdef inline int cinvert(celement out, celement a, long prec, PowComputer_class p INPUT: - - ``out`` -- an ``celement`` to store the inverse. - - ``a`` -- an ``celement``, the element to be inverted. - - ``prec`` -- a long, the precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the inverse + - ``a`` -- an ``celement``, the element to be inverted + - ``prec`` -- a long, the precision + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -324,11 +320,11 @@ cdef inline int cmul(celement out, celement a, celement b, long prec, PowCompute INPUT: - - ``out`` -- an ``celement`` to store the product. - - ``a`` -- an ``celement``, the first input. - - ``b`` -- an ``celement``, the second input. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the product + - ``a`` -- an ``celement``, the first input + - ``b`` -- an ``celement``, the second input + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -341,63 +337,63 @@ cdef inline int cdivunit(celement out, celement a, celement b, long prec, PowCom INPUT: - - ``out`` -- an ``celement`` to store the quotient. - - ``a`` -- an ``celement``, the first input. - - ``b`` -- an ``celement``, the second input. - - ``prec`` -- a long, the precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the quotient + - ``a`` -- an ``celement``, the first input + - ``b`` -- an ``celement``, the second input + - ``prec`` -- a long, the precision + - ``prime_pow`` -- the PowComputer for the ring """ pass cdef inline int csetone(celement out, PowComputer_class prime_pow) except -1: """ - Sets to 1. + Set to 1. INPUT: - - ``out`` -- the ``celement`` in which to store 1. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store 1 + - ``prime_pow`` -- the PowComputer for the ring """ pass cdef inline int csetzero(celement out, PowComputer_class prime_pow) except -1: """ - Sets to 0. + Set to 0. INPUT: - - ``out`` -- the ``celement`` in which to store 0. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store 0 + - ``prime_pow`` -- the PowComputer for the ring """ pass cdef inline bint cisone(celement a, PowComputer_class prime_pow) except -1: """ - Returns whether this element is equal to 1. + Return whether this element is equal to 1. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: - - returns True if `a = 1`, and False otherwise. + - returns ``True`` if `a = 1`, and ``False`` otherwise. """ pass cdef inline bint ciszero(celement a, PowComputer_class prime_pow) except -1: """ - Returns whether this element is equal to 0. + Return whether this element is equal to 0. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: - - returns True if `a = 0`, and False otherwise. + - returns ``True`` if `a = 0`, and ``False`` otherwise. """ pass @@ -407,11 +403,11 @@ cdef inline int cpow(celement out, celement a, mpz_t n, long prec, PowComputer_c INPUT: - - ``out`` -- the ``celement`` in which to store the result. - - ``a`` -- the base. - - ``n`` -- an ``mpz_t``, the exponent. - - ``prec`` -- a long, the working absolute precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store the result + - ``a`` -- the base + - ``n`` -- an ``mpz_t``, the exponent + - ``prec`` -- a long, the working absolute precision + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -421,9 +417,9 @@ cdef inline int ccopy(celement out, celement a, PowComputer_class prime_pow) exc INPUT: - - ``out`` -- the ``celement`` to store the result. - - ``a`` -- the element to copy. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` to store the result + - ``a`` -- the element to copy + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -433,8 +429,8 @@ cdef inline cpickle(celement a, PowComputer_class prime_pow): INPUT: - - ``a`` the element to pickle. - - ``prime_pow`` the PowComputer for the ring. + - ``a`` -- the element to pickle + - ``prime_pow`` the PowComputer for the ring OUTPUT: @@ -448,9 +444,9 @@ cdef inline int cunpickle(celement out, x, PowComputer_class prime_pow) except - INPUT: - - ``out`` -- the ``celement`` in which to store the result. - - ``x`` -- the result of :meth:`cpickle`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store the result + - ``x`` -- the result of :meth:`cpickle` + - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -460,10 +456,10 @@ cdef inline long chash(celement a, long ordp, long prec, PowComputer_class prime INPUT: - - ``a`` -- an ``celement`` storing the underlying element to hash. - - ``ordp`` -- a long storing the valuation. - - ``prec`` -- a long storing the precision. - - ``prime_pow`` -- a PowComputer for the ring. + - ``a`` -- an ``celement`` storing the underlying element to hash + - ``ordp`` -- a long storing the valuation + - ``prec`` -- a long storing the precision + - ``prime_pow`` -- a PowComputer for the ring """ pass @@ -474,23 +470,23 @@ cdef inline cexpansion_next(celement value, expansion_mode mode, long curpower, INPUT: - - ``value`` -- the `\pi`-adic element whose expansion is desired. + - ``value`` -- the `\pi`-adic element whose expansion is desired - ``mode`` -- either ``simple_mode`` or ``smallest_mode`` - ``curpower`` -- the current power of `\pi` for which the coefficient - is being found. Only used in ``smallest_mode``. - - ``prime_pow`` -- A ``PowComputer`` holding `\pi`-adic data. + is being found. Only used in ``smallest_mode`` + - ``prime_pow`` -- a ``PowComputer`` holding `\pi`-adic data """ pass cdef inline cexpansion_getitem(celement value, long m, PowComputer_ prime_pow): r""" - Return the `m`th `\pi`-adic digit in the ``simple_mode`` expansion. + Return the `m`-th `\pi`-adic digit in the ``simple_mode`` expansion. INPUT: - - ``value`` -- the `\pi`-adic element whose expansion is desired. - - ``m`` -- a non-negative integer: which entry in the `\pi`-adic expansion to return. - - ``prime_pow`` -- A ``PowComputer`` holding `\pi`-adic data. + - ``value`` -- the `\pi`-adic element whose expansion is desired + - ``m`` -- nonnegative integer: which entry in the `\pi`-adic expansion to return + - ``prime_pow`` -- a ``PowComputer`` holding `\pi`-adic data """ pass @@ -504,8 +500,8 @@ cdef list ccoefficients(celement x, long valshift, PowComputer_class prime_pow): INPUT: - - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part. - - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by. + - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part + - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by - ``prec`` -- a long, the (relative) precision desired, used in rational reconstruction - ``prime_pow`` -- the ``PowComputer`` of the ring """ @@ -518,11 +514,10 @@ cdef int cteichmuller(celement out, celement value, long prec, PowComputer_class INPUT: - ``out`` -- an ``celement`` which is set to a `q-1` root of unity - congruent to `value` mod `\pi`; or 0 if `a \equiv 0 - \pmod{\pi}`. - - ``value`` -- an ``celement``, the element mod `\pi` to lift. - - ``prec`` -- a long, the precision to which to lift. - - ``prime_pow`` -- the ``PowComputer`` of the ring. + congruent to `value` mod `\pi`; or 0 if `a \equiv 0 \pmod{\pi}` + - ``value`` -- an ``celement``, the element mod `\pi` to lift + - ``prec`` -- a long, the precision to which to lift + - ``prime_pow`` -- the ``PowComputer`` of the ring """ pass @@ -532,13 +527,13 @@ cdef int cconv(celement out, x, long prec, long valshift, PowComputer_class prim INPUT: - - ``out`` -- an ``celement`` to store the output. - - ``x`` -- a Sage element that can be converted to a `p`-adic element. + - ``out`` -- an ``celement`` to store the output + - ``x`` -- a Sage element that can be converted to a `p`-adic element - ``prec`` -- a long, giving the precision desired: absolute if - `valshift = 0`, relative if `valshift > 0`. + `valshift = 0`, relative if `valshift > 0` - ``valshift`` -- the power of the uniformizer to divide by before - storing the result in ``out``. - - ``prime_pow`` -- a PowComputer for the ring. + storing the result in ``out`` + - ``prime_pow`` -- a PowComputer for the ring """ pass @@ -549,14 +544,14 @@ cdef inline long cconv_mpz_t(celement out, mpz_t x, long prec, bint absolute, Po INPUT: - - ``out`` -- an ``celement`` to store the output. - - ``x`` -- an ``mpz_t`` giving the integer to be converted. + - ``out`` -- an ``celement`` to store the output + - ``x`` -- an ``mpz_t`` giving the integer to be converted - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. + relative depending on the ``absolute`` input - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -567,15 +562,15 @@ cdef inline long cconv_mpz_t(celement out, mpz_t x, long prec, bint absolute, Po cdef inline int cconv_mpz_t_out(mpz_t out, celement x, long valshift, long prec, PowComputer_class prime_pow) except -1: """ - Converts the underlying `p`-adic element into an integer if + Convert the underlying `p`-adic element into an integer if possible. - ``out`` -- stores the resulting integer as an integer between 0 - and `p^{prec + valshift}`. - - ``x`` -- an ``celement`` giving the underlying `p`-adic element. - - ``valshift`` -- a long giving the power of `p` to shift `x` by. - -` ``prec`` -- a long, the precision of ``x``: currently not used. - - ``prime_pow`` -- a PowComputer for the ring. + and `p^{prec + valshift}` + - ``x`` -- an ``celement`` giving the underlying `p`-adic element + - ``valshift`` -- a long giving the power of `p` to shift `x` by + -` ``prec`` -- a long, the precision of ``x``: currently not used + - ``prime_pow`` -- a PowComputer for the ring """ pass @@ -586,14 +581,14 @@ cdef inline long cconv_mpq_t(celement out, mpq_t x, long prec, bint absolute, Po INPUT: - - ``out`` -- an ``celement`` to store the output. - - ``x`` -- an ``mpq_t`` giving the rational to be converted. + - ``out`` -- an ``celement`` to store the output + - ``x`` -- an ``mpq_t`` giving the rational to be converted - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. + relative depending on the ``absolute`` input - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -604,16 +599,16 @@ cdef inline long cconv_mpq_t(celement out, mpq_t x, long prec, bint absolute, Po cdef inline int cconv_mpq_t_out(mpq_t out, celement x, long valshift, long prec, PowComputer_class prime_pow) except -1: """ - Converts the underlying `p`-adic element into a rational. + Convert the underlying `p`-adic element into a rational. - ``out`` -- gives a rational approximating the input. Currently - uses rational reconstruction but may change in the - future to use a more naive method. - - ``x`` -- an ``celement`` giving the underlying `p`-adic element. - - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by. - -` ``prec`` -- a long, the precision of ``x``, used in rational - reconstruction. - - ``prime_pow`` -- a PowComputer for the ring. + uses rational reconstruction but may change in the future to use a more + naive method + - ``x`` -- an ``celement`` giving the underlying `p`-adic element + - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by + - ``prec`` -- a long, the precision of ``x``, used in rational + reconstruction + - ``prime_pow`` -- a PowComputer for the ring """ pass diff --git a/src/sage/libs/linkages/padics/Polynomial_ram.pxi b/src/sage/libs/linkages/padics/Polynomial_ram.pxi index 687b5a5cf15..6863b4156c5 100644 --- a/src/sage/libs/linkages/padics/Polynomial_ram.pxi +++ b/src/sage/libs/linkages/padics/Polynomial_ram.pxi @@ -46,10 +46,7 @@ cdef inline bint creduce(celement out, celement a, long prec, PowComputer_ prime - ``prime_pow`` -- the ``PowComputer`` for the ring - OUTPUT: - - ``True`` if the reduction is zero, ``False`` otherwise - + OUTPUT: ``True`` if the reduction is zero, ``False`` otherwise """ cdef celement ared = a % prime_pow.modulus if ared is a and out is not a: @@ -83,10 +80,7 @@ cdef inline bint creduce_small(celement out, celement a, long prec, PowComputer_ - ``prime_pow`` -- the ``PowComputer`` for the ring - OUTPUT: - - ``True`` if the reduction is zero, ``False`` otherwise - + OUTPUT: ``True`` if the reduction is zero, ``False`` otherwise """ return creduce(out, a, prec, prime_pow) @@ -112,7 +106,6 @@ cdef inline long cvaluation(celement a, long prec, PowComputer_ prime_pow) excep The number of times the uniformizer divides ``a``, or ``prec`` if that is higher. - """ C = a._coeffs if not C: @@ -148,8 +141,7 @@ cdef inline int cshift(celement shifted, celement rem, celement a, long n, long - ``prime_pow`` -- the ``PowComputer`` for the ring - ``reduce_afterward`` -- whether to :meth:`creduce` ``shifted`` before - returning. - + returning """ cdef long v notrunc = False @@ -206,7 +198,7 @@ cdef inline int cshift_notrunc(celement out, celement a, long n, long prec, PowC - ``prime_pow`` -- the ``PowComputer`` for the ring - ``reduce_afterward`` -- whether to :meth:`creduce` ``out`` before - returning. + returning """ cdef long q, r @@ -249,7 +241,6 @@ cdef inline int cinvert(celement out, celement a, long prec, PowComputer_ prime_ - ``prec`` -- a ``long``, ``out`` is reduced to this precision - ``prime_pow`` -- the ``PowComputer`` for the ring - """ out._coeffs = prime_pow.invert(a, prec)._coeffs creduce(out, out, prec, prime_pow) @@ -273,7 +264,6 @@ cdef inline int cdivunit(celement out, celement a, celement b, long prec, PowCom determined - ``prime_pow`` -- the ``PowComputer`` for the ring - """ binv = prime_pow.invert(b, prec) cmul(out, a, binv, prec, prime_pow) @@ -293,7 +283,6 @@ cdef inline int cpow(celement out, celement a, mpz_t n, long prec, PowComputer_ - ``prec`` -- a ``long``, the working absolute precision - ``prime_pow`` -- the ``PowComputer`` for the ring - """ cdef Integer zn = PY_NEW(Integer) mpz_set(zn.value, n) @@ -339,13 +328,13 @@ cdef inline cexpansion_next(celement value, expansion_mode mode, long curpower, cdef inline cexpansion_getitem(celement value, long m, PowComputer_ prime_pow): """ - Return the `m`th `p`-adic digit in the ``simple_mode`` expansion. + Return the `m`-th `p`-adic digit in the ``simple_mode`` expansion. INPUT: - - ``value`` -- the `p`-adic element whose expansion is desired. - - ``m`` -- a non-negative integer: which entry in the `p`-adic expansion to return. - - ``prime_pow`` -- A ``PowComputer`` holding `p`-adic data. + - ``value`` -- the `p`-adic element whose expansion is desired + - ``m`` -- nonnegative integer; which entry in the `p`-adic expansion to return + - ``prime_pow`` -- a ``PowComputer`` holding `p`-adic data """ R = value.base_ring() p = R.prime() @@ -367,14 +356,13 @@ cdef int cteichmuller(celement out, celement value, long prec, PowComputer_ prim INPUT: - ``out`` -- a ``celement`` which is set to a `q-1`-th root of unity - congruent to ``value`` modulo π; or 0 if `a \equiv 0 \pmod{π}`. + congruent to ``value`` modulo π; or 0 if `a \equiv 0 \pmod{π}` - ``value`` -- n ``celement``, the element mod π to lift - ``prec`` -- a ``long``, the precision to which to lift - ``prime_pow`` -- the ``PowComputer`` of the ring - """ if value[0].valuation() > 0: out._coeffs = [] @@ -387,8 +375,8 @@ cdef list ccoefficients(celement x, long valshift, long prec, PowComputer_ prime INPUT: - - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part. - - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by. + - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part + - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by - ``prec`` -- a long, the (relative) precision desired, used in rational reconstruction - ``prime_pow`` -- the Powcomputer of the ring """ diff --git a/src/sage/libs/linkages/padics/Polynomial_shared.pxi b/src/sage/libs/linkages/padics/Polynomial_shared.pxi index b88b928a347..e471ce947ad 100644 --- a/src/sage/libs/linkages/padics/Polynomial_shared.pxi +++ b/src/sage/libs/linkages/padics/Polynomial_shared.pxi @@ -51,7 +51,6 @@ cdef inline int cconstruct(celement value, PowComputer_ prime_pow) except -1: For Polynomial elements, this function calls the ``__init__`` method of ``celement``. When creating ``celement`` instances, we use ``__new__`` which does not call ``__init__``, because of the metaclass that we are using. - """ value.__init__(prime_pow.poly_ring) @@ -69,7 +68,6 @@ cdef inline int cdestruct(celement value, PowComputer_ prime_pow) except -1: This function has no effect for polynomials. There is no manual garbage collection necessary, as ``celement`` is a managed Python type. - """ pass @@ -100,7 +98,6 @@ cdef inline int ccmp(celement a, celement b, long prec, bint reduce_a, bint redu - ``reduce_b`` -- whether ``b`` is already reduced with respect to ``prec`` - ``prime_pow`` -- the ``PowComputer`` for the ring - """ if not (reduce_a or reduce_b): return 0 if a == b else 1 @@ -142,7 +139,6 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_ prime The number of times the uniformizer divides ``a``, or ``prec`` if ``a`` is zero. - """ if a == 0: return prec @@ -162,7 +158,6 @@ cdef inline bint cisunit(celement a, PowComputer_ prime_pow) except -1: - ``a`` -- the ``celement`` to test - ``prime_pow`` -- the ``PowComputer`` for the ring - """ return cvaluation(a, 1, prime_pow) == 0 @@ -181,7 +176,6 @@ cdef inline int cneg(celement out, celement a, long prec, PowComputer_ prime_pow - ``prec`` -- a ``long``, the precision - ``prime_pow`` -- the ``PowComputer`` for the ring - """ cdef celement ma = -a if ma is a: @@ -206,7 +200,6 @@ cdef inline int cadd(celement out, celement a, celement b, long prec, PowCompute - ``prec`` -- a ``long``, the precision - ``prime_pow`` -- the ``PowComputer`` for the ring - """ cdef celement sm = a + b if sm is a or sm is b: @@ -231,7 +224,6 @@ cdef inline int csub(celement out, celement a, celement b, long prec, PowCompute - ``prec`` -- a ``long``, the precision - ``prime_pow`` -- the ``PowComputer`` for the ring - """ cdef celement df = a - b if df is a or df is b: @@ -256,7 +248,6 @@ cdef inline int cmul(celement out, celement a, celement b, long prec, PowCompute - ``prec`` -- a ``long``, the precision - ``prime_pow`` -- the ``PowComputer`` for the ring - """ cdef celement pd = a*b if pd is a or pd is b: @@ -273,7 +264,6 @@ cdef inline int csetone(celement out, PowComputer_ prime_pow) except -1: - ``out`` -- the ``celement`` in which to store 1 - ``prime_pow`` -- the ``PowComputer`` for the ring - """ out._coeffs = [prime_pow.base_ring(1)] @@ -286,7 +276,6 @@ cdef inline int csetzero(celement out, PowComputer_ prime_pow) except -1: - ``out`` -- the ``celement`` in which to store 0 - ``prime_pow`` -- the ``PowComputer`` for the ring - """ out._coeffs = [] @@ -299,7 +288,6 @@ cdef inline bint cisone(celement a, PowComputer_ prime_pow) except -1: - ``a`` -- the element to test - ``prime_pow`` -- the ``PowComputer`` for the ring - """ return a.is_one() @@ -312,7 +300,6 @@ cdef inline bint ciszero(celement a, PowComputer_ prime_pow) except -1: - ``a`` -- the element to test - ``prime_pow`` -- the ``PowComputer`` for the ring - """ return a.is_zero() @@ -327,7 +314,6 @@ cdef inline int ccopy(celement out, celement a, PowComputer_ prime_pow) except - - ``a`` -- the element from which to copy - ``prime_pow`` -- the ``PowComputer`` for the ring - """ out._coeffs = a._coeffs[:] @@ -337,10 +323,9 @@ cdef inline cpickle(celement a, PowComputer_ prime_pow): INPUT: - - ``a`` the element to pickle - - - ``prime_pow`` the ``PowComputer`` for the ring + - ``a`` -- the element to pickle + - ``prime_pow`` -- the ``PowComputer`` for the ring """ return a._coeffs @@ -355,7 +340,6 @@ cdef inline int cunpickle(celement out, x, PowComputer_ prime_pow) except -1: - ``x`` -- the result of `meth`:cpickle - ``prime_pow`` -- the ``PowComputer`` for the ring - """ out._coeffs = x @@ -372,7 +356,6 @@ cdef inline long chash(celement a, long ordp, long prec, PowComputer_ prime_pow) - ``prec`` -- the precision as a ``long`` - ``prime_pow`` -- the ``PowComputer`` for the ring - """ if ciszero(a, prime_pow): return 0 @@ -396,7 +379,6 @@ cdef int cconv(celement out, x, long prec, long valshift, PowComputer_ prime_pow the result in ``out`` - ``prime_pow`` -- a ``PowComputer`` for the ring - """ cdef celement xx, shift if valshift < 0: @@ -449,7 +431,6 @@ cdef inline long cconv_mpz_t(celement out, mpz_t x, long prec, bint absolute, Po If ``absolute`` is ``False``, the valuation that was extracted (``maxordp`` when `x = 0`). - """ cdef long valuation = maxordp @@ -482,7 +463,6 @@ cdef inline int cconv_mpz_t_out(mpz_t out, celement x, long valshift, long prec, -` ``prec`` -- a ``long``, the precision of ``x`` and ``out`` - ``prime_pow`` -- a ``PowComputer`` for the ring - """ cdef Integer n @@ -527,7 +507,6 @@ cdef inline long cconv_mpq_t(celement out, mpq_t x, long prec, bint absolute, Po If ``absolute`` is ``False``, the valuation that was extracted (``maxordp`` when `x = 0`) - """ cdef Rational r = PY_NEW(Rational) mpq_set(r.value, x) @@ -555,7 +534,6 @@ cdef inline int cconv_mpq_t_out(mpq_t out, celement x, long valshift, long prec, - ``prec`` -- a long, the precision of ``x``; ignored - ``prime_pow`` -- a ``PowComputer`` for the ring - """ cdef Rational c diff --git a/src/sage/libs/linkages/padics/fmpz_poly_unram.pxi b/src/sage/libs/linkages/padics/fmpz_poly_unram.pxi index fcacaa024d9..f019a1832be 100644 --- a/src/sage/libs/linkages/padics/fmpz_poly_unram.pxi +++ b/src/sage/libs/linkages/padics/fmpz_poly_unram.pxi @@ -42,8 +42,8 @@ cdef inline int cconstruct(celement value, PowComputer_ prime_pow) except -1: INPUT: - - ``unit`` -- an ``celement`` to be initialized. - - ``prime_pow`` -- the PowComputer for the ring. + - ``unit`` -- an ``celement`` to be initialized + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_init(value) @@ -53,8 +53,8 @@ cdef inline int cdestruct(celement value, PowComputer_ prime_pow) except -1: INPUT: - - ``unit`` -- an ``celement`` to be cleared. - - ``prime_pow`` -- the PowComputer for the ring. + - ``unit`` -- an ``celement`` to be cleared + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_clear(value) @@ -64,12 +64,12 @@ cdef inline int ccmp(celement a, celement b, long prec, bint reduce_a, bint redu INPUT: - - ``a`` -- an ``celement``. - - ``b`` -- an ``celement``. - - ``prec`` -- a long, the precision of the comparison. - - ``reduce_a`` -- a bint, whether ``a`` needs to be reduced. - - ``reduce_b`` -- a bint, whether ``b`` needs to be reduced. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- an ``celement`` + - ``b`` -- an ``celement`` + - ``prec`` -- a long, the precision of the comparison + - ``reduce_a`` -- a bint, whether ``a`` needs to be reduced + - ``reduce_b`` -- a bint, whether ``b`` needs to be reduced + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: @@ -117,10 +117,10 @@ cdef inline int cneg(celement out, celement a, long prec, PowComputer_ prime_pow INPUT: - - ``out`` -- an ``celement`` to store the negation. - - ``a`` -- an ``celement`` to be negated. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the negation + - ``a`` -- an ``celement`` to be negated + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_neg(out, a) @@ -132,11 +132,11 @@ cdef inline int cadd(celement out, celement a, celement b, long prec, PowCompute INPUT: - - ``out`` -- an ``celement`` to store the sum. - - ``a`` -- an ``celement``, the first summand. - - ``b`` -- an ``celement``, the second summand. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the sum + - ``a`` -- an ``celement``, the first summand + - ``b`` -- an ``celement``, the second summand + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_add(out, a, b) @@ -146,14 +146,12 @@ cdef inline bint creduce(celement out, celement a, long prec, PowComputer_ prime INPUT: - - ``out`` -- an ``celement`` to store the reduction. - - ``a`` -- the element to be reduced. - - ``prec`` -- a long, the precision to reduce modulo. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the reduction + - ``a`` -- the element to be reduced + - ``prec`` -- a long, the precision to reduce modulo + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - returns True if the reduction is zero; False otherwise. + OUTPUT: ``True`` if the reduction is zero; ``False`` otherwise """ if prec == 0: csetzero(out, prime_pow) @@ -174,14 +172,12 @@ cdef inline bint creduce_small(celement out, celement a, long prec, PowComputer_ INPUT: - - ``out`` -- an ``celement`` to store the reduction. - - ``a`` -- the element to be reduced. - - ``prec`` -- a long, the precision to reduce modulo. - - ``prime_pow`` -- the PowComputer for the ring. - - OUTPUT: + - ``out`` -- an ``celement`` to store the reduction + - ``a`` -- the element to be reduced + - ``prec`` -- a long, the precision to reduce modulo + - ``prime_pow`` -- the PowComputer for the ring - - returns True if the reduction is zero; False otherwise. + OUTPUT: ``True`` if the reduction is zero; ``False`` otherwise """ return creduce(out, a, prec, prime_pow) @@ -191,10 +187,10 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_ prime INPUT: - - ``out`` -- an ``celement`` to store the unit. - - ``a`` -- the element whose valuation and unit are desired. - - ``prec`` -- a long, used if `a = 0`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the unit + - ``a`` -- the element whose valuation and unit are desired + - ``prec`` -- a long, used if `a = 0` + - ``prime_pow`` -- the PowComputer for the ring - ``reduce_relative`` -- a bint: whether the final result should be reduced at precision ``prec`` (case ``False``) or ``prec - valuation`` (case ``True``) @@ -217,7 +213,7 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_ prime cdef inline long cvaluation(celement a, long prec, PowComputer_ prime_pow) except -1: """ - Returns the maximum power of the uniformizer dividing this + Return the maximum power of the uniformizer dividing this element. This function differs from :meth:`cremove` in that the unit is @@ -225,9 +221,9 @@ cdef inline long cvaluation(celement a, long prec, PowComputer_ prime_pow) excep INPUT: - - ``a`` -- the element whose valuation is desired. - - ``prec`` -- a long, used if `a = 0`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element whose valuation is desired + - ``prec`` -- a long, used if `a = 0` + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: @@ -250,16 +246,14 @@ cdef inline long cvaluation(celement a, long prec, PowComputer_ prime_pow) excep cdef inline bint cisunit(celement a, PowComputer_ prime_pow) except -1: """ - Returns whether this element has valuation zero. + Return whether this element has valuation zero. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. - - OUTPUT: + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - - returns True if `a` has valuation 0, and False otherwise. + OUTPUT: ``True`` if `a` has valuation 0, and ``False`` otherwise """ fmpz_poly_scalar_mod_fmpz(prime_pow.poly_cisunit, a, prime_pow.fprime) return not ciszero(prime_pow.poly_cisunit, prime_pow) @@ -271,15 +265,15 @@ cdef inline int cshift(celement out, celement rem, celement a, long n, long prec INPUT: - ``out`` -- a ``celement`` to store the result. If `n >= 0` - then out will be set to `a * p^n`. + then out will be set to `a * p^n` If `n < 0`, out will be set to `a // p^-n`. - - ``rem`` -- a ``celement`` to store the remainder of the division. - Should not be aliased with `a`. - - ``a`` -- the element to shift. - - ``n`` -- long, the amount to shift by. - - ``prec`` -- long, a precision modulo which to reduce. - - ``prime_pow`` -- the PowComputer for the ring. - - ``reduce_afterward`` -- whether to reduce afterward. + - ``rem`` -- a ``celement`` to store the remainder of the division + Should not be aliased with `a` + - ``a`` -- the element to shift + - ``n`` -- long, the amount to shift by + - ``prec`` -- long, a precision modulo which to reduce + - ``prime_pow`` -- the PowComputer for the ring + - ``reduce_afterward`` -- whether to reduce afterward """ if n > 0: fmpz_poly_zero(rem) @@ -303,14 +297,14 @@ cdef inline int cshift_notrunc(celement out, celement a, long n, long prec, PowC INPUT: - ``out`` -- an ``celement`` to store the result. If `n >= 0` - then out will be set to `a * p^n`. + then out will be set to `a * p^n` If `n < 0`, out will be set to `a // p^-n`. - ``a`` -- the element to shift. Assumes that the valuation of a is at least -n. - - ``n`` -- long, the amount to shift by. - - ``prec`` -- long, a precision modulo which to reduce. - - ``prime_pow`` -- the PowComputer for the ring. - - ``reduce_afterward`` -- whether to reduce afterward. + - ``n`` -- long, the amount to shift by + - ``prec`` -- long, a precision modulo which to reduce + - ``prime_pow`` -- the PowComputer for the ring + - ``reduce_afterward`` -- whether to reduce afterward """ if n > 0: fmpz_poly_scalar_mul_fmpz(out, a, prime_pow.pow_fmpz_t_tmp(n)[0]) @@ -331,11 +325,11 @@ cdef inline int csub(celement out, celement a, celement b, long prec, PowCompute INPUT: - - ``out`` -- an ``celement`` to store the difference. - - ``a`` -- an ``celement``, the first input. - - ``b`` -- an ``celement``, the second input. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the difference + - ``a`` -- an ``celement``, the first input + - ``b`` -- an ``celement``, the second input + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_sub(out, a, b) @@ -347,10 +341,10 @@ cdef inline int cinvert(celement out, celement a, long prec, PowComputer_ prime_ INPUT: - - ``out`` -- an ``celement`` to store the inverse. - - ``a`` -- an ``celement``, the element to be inverted. - - ``prec`` -- a long, the precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the inverse + - ``a`` -- an ``celement``, the element to be inverted + - ``prec`` -- a long, the precision + - ``prime_pow`` -- the PowComputer for the ring """ sig_on() try: @@ -381,11 +375,11 @@ cdef inline int cmul(celement out, celement a, celement b, long prec, PowCompute INPUT: - - ``out`` -- an ``celement`` to store the product. - - ``a`` -- an ``celement``, the first input. - - ``b`` -- an ``celement``, the second input. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the product + - ``a`` -- an ``celement``, the first input + - ``b`` -- an ``celement``, the second input + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_mul(out, a, b) @@ -398,64 +392,60 @@ cdef inline int cdivunit(celement out, celement a, celement b, long prec, PowCom INPUT: - - ``out`` -- an ``celement`` to store the quotient. - - ``a`` -- an ``celement``, the first input. - - ``b`` -- an ``celement``, the second input. - - ``prec`` -- a long, the precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``celement`` to store the quotient + - ``a`` -- an ``celement``, the first input + - ``b`` -- an ``celement``, the second input + - ``prec`` -- a long, the precision + - ``prime_pow`` -- the PowComputer for the ring """ cinvert(prime_pow.aliasing, b, prec, prime_pow) cmul(out, a, prime_pow.aliasing, prec, prime_pow) cdef inline int csetone(celement out, PowComputer_ prime_pow) except -1: """ - Sets to 1. + Set to 1. INPUT: - - ``out`` -- the ``celement`` in which to store 1. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store 1 + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_set_ui(out, 1) cdef inline int csetzero(celement out, PowComputer_ prime_pow) except -1: """ - Sets to 0. + Set to 0. INPUT: - - ``out`` -- the ``celement`` in which to store 0. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store 0 + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_set_ui(out, 0) cdef inline bint cisone(celement a, PowComputer_ prime_pow) except -1: """ - Returns whether this element is equal to 1. + Return whether this element is equal to 1. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - returns True if `a = 1`, and False otherwise. + OUTPUT: ``True`` if `a = 1`, and ``False`` otherwise """ return fmpz_poly_is_one(a) cdef inline bint ciszero(celement a, PowComputer_ prime_pow) except -1: """ - Returns whether this element is equal to 0. + Return whether this element is equal to 0. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. - - OUTPUT: + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - - returns True if `a = 0`, and False otherwise. + OUTPUT: ``True`` if `a = 0`, and ``False`` otherwise """ return fmpz_poly_is_zero(a) @@ -465,11 +455,11 @@ cdef inline int cpow(celement out, celement a, mpz_t n, long prec, PowComputer_ INPUT: - - ``out`` -- the ``celement`` in which to store the result. - - ``a`` -- the base. - - ``n`` -- an ``mpz_t``, the exponent. - - ``prec`` -- a long, the working absolute precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store the result + - ``a`` -- the base + - ``n`` -- an ``mpz_t``, the exponent + - ``prec`` -- a long, the working absolute precision + - ``prime_pow`` -- the PowComputer for the ring """ if mpz_sgn(n) < 0: raise NotImplementedError("negative exponent") @@ -492,9 +482,9 @@ cdef inline int ccopy(celement out, celement a, PowComputer_ prime_pow) except - INPUT: - - ``out`` -- the ``celement`` to store the result. - - ``a`` -- the element to copy. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` to store the result + - ``a`` -- the element to copy + - ``prime_pow`` -- the PowComputer for the ring """ fmpz_poly_set(out, a) @@ -504,8 +494,8 @@ cdef inline cpickle(celement a, PowComputer_ prime_pow): INPUT: - - ``a`` the element to pickle. - - ``prime_pow`` the PowComputer for the ring. + - ``a`` -- the element to pickle + - ``prime_pow`` the PowComputer for the ring OUTPUT: @@ -519,9 +509,9 @@ cdef inline int cunpickle(celement out, x, PowComputer_ prime_pow) except -1: INPUT: - - ``out`` -- the ``celement`` in which to store the result. - - ``x`` -- the result of :meth:`cpickle`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``celement`` in which to store the result + - ``x`` -- the result of :meth:`cpickle` + - ``prime_pow`` -- the PowComputer for the ring """ byte_string = x.encode("UTF-8") cdef char* c_str = byte_string @@ -533,10 +523,10 @@ cdef inline long chash(celement a, long ordp, long prec, PowComputer_ prime_pow) INPUT: - - ``a`` -- a ``celement`` storing the underlying element to hash. - - ``ordp`` -- a long storing the valuation. - - ``prec`` -- a long storing the precision. - - ``prime_pow`` -- a PowComputer for the ring. + - ``a`` -- a ``celement`` storing the underlying element to hash + - ``ordp`` -- a long storing the valuation + - ``prec`` -- a long storing the precision + - ``prime_pow`` -- a PowComputer for the ring """ if ciszero(a, prime_pow): return 0 @@ -551,12 +541,12 @@ cdef inline cmodp_rep(fmpz_poly_t rep, fmpz_poly_t value, expansion_mode mode, b INPUT: - - ``rep`` -- the reduction mod p. - - ``value`` -- the element to be reduced. + - ``rep`` -- the reduction mod p + - ``value`` -- the element to be reduced - ``mode`` -- if ``smallest_mode``, the coefficients of the reduction -` will be between -p/2 and p/2 instead of between 0 and p. - - ``return_list`` -- boolean, whether to return a list of integers giving the coefficients of the expansion. - - ``prime_pow`` -- a PowComputer for the ring. +` will be between -p/2 and p/2 instead of between 0 and p + - ``return_list`` -- boolean, whether to return a list of integers giving the coefficients of the expansion + - ``prime_pow`` -- a PowComputer for the ring """ cdef long i cdef fmpz* c @@ -584,11 +574,11 @@ cdef inline cexpansion_next(fmpz_poly_t value, expansion_mode mode, long curpowe INPUT: - - ``value`` -- the `p`-adic element whose expansion is desired. + - ``value`` -- the `p`-adic element whose expansion is desired - ``mode`` -- either ``simple_mode`` or ``smallest_mode`` - ``curpower`` -- the current power of `p` for which the coefficient - is being found. Only used in ``smallest_mode``. - - ``prime_pow`` -- A ``PowComputer`` holding `p`-adic data. + is being found. Only used in ``smallest_mode`` + - ``prime_pow`` -- a ``PowComputer`` holding `p`-adic data """ if mode == teichmuller_mode: raise NotImplementedError @@ -610,13 +600,13 @@ cdef inline cexpansion_next(fmpz_poly_t value, expansion_mode mode, long curpowe cdef inline cexpansion_getitem(fmpz_poly_t value, long m, PowComputer_ prime_pow): """ - Return the `m`th `p`-adic digit in the ``simple_mode`` expansion. + Return the `m`-th `p`-adic digit in the ``simple_mode`` expansion. INPUT: - - ``value`` -- the `p`-adic element whose expansion is desired. - - ``m`` -- a non-negative integer: which entry in the `p`-adic expansion to return. - - ``prime_pow`` -- A ``PowComputer`` holding `p`-adic data. + - ``value`` -- the `p`-adic element whose expansion is desired + - ``m`` -- nonnegative integer: which entry in the `p`-adic expansion to return + - ``prime_pow`` -- a ``PowComputer`` holding `p`-adic data """ ans = [] cdef fmpz* c @@ -644,8 +634,8 @@ cdef list ccoefficients(celement x, long valshift, long prec, PowComputer_ prime INPUT: - - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part. - - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by. + - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part + - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by - ``prec`` -- a long, the (relative) precision desired, used in rational reconstruction - ``prime_pow`` -- the ``PowComputer`` of the ring """ @@ -677,9 +667,9 @@ cdef int cteichmuller(celement out, celement value, long prec, PowComputer_ prim - ``out`` -- an ``celement`` which is set to a `q-1` root of unity congruent to `value` mod `\pi`; or 0 if `a \equiv 0 \pmod{\pi}`. - - ``value`` -- an ``celement``, the element mod `\pi` to lift. - - ``prec`` -- a long, the precision to which to lift. - - ``prime_pow`` -- the ``PowComputer`` of the ring. + - ``value`` -- an ``celement``, the element mod `\pi` to lift + - ``prec`` -- a long, the precision to which to lift + - ``prime_pow`` -- the ``PowComputer`` of the ring ALGORITHM: @@ -688,7 +678,6 @@ cdef int cteichmuller(celement out, celement value, long prec, PowComputer_ prim digits coincide with `f'`. This does probably not yield quadratic convergence but taking inverses would be much more expensive than what is done here. - """ fmpz_poly_set(out, value) @@ -719,17 +708,17 @@ cdef int cconv(celement out, x, long prec, long valshift, PowComputer_ prime_pow INPUT: - - ``out`` -- an ``celement`` to store the output. + - ``out`` -- an ``celement`` to store the output - - ``x`` -- a Sage element that can be converted to a `p`-adic element. + - ``x`` -- a Sage element that can be converted to a `p`-adic element - - ``prec`` -- a long, giving the precision desired: absolute if - `valshift = 0`, relative if `valshift != 0`. + - ``prec`` -- a long, giving the precision desired; absolute if + `valshift = 0`, relative if `valshift != 0` - ``valshift`` -- the power of the uniformizer to divide by before - storing the result in ``out``. + storing the result in ``out`` - - ``prime_pow`` -- a PowComputer for the ring. + - ``prime_pow`` -- a PowComputer for the ring """ cdef long i cdef long degree @@ -757,19 +746,19 @@ cdef inline long cconv_mpq_t(celement out, mpq_t x, long prec, bint absolute, Po INPUT: - - ``out`` -- an ``celement`` to store the output. - - ``x`` -- an ``mpq_t`` giving the integer to be converted. + - ``out`` -- an ``celement`` to store the output + - ``x`` -- an ``mpq_t`` giving the integer to be converted - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. - - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + relative depending on the ``absolute`` input + - ``absolute`` -- if ``False`` then extracts the valuation and returns + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision. + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: - - If ``absolute`` is False then returns the valuation that was - extracted (``maxordp`` when `x = 0`). + If ``absolute`` is ``False`` then returns the valuation that was + extracted (``maxordp`` when `x = 0`). """ cdef long val val = cconv_mpq_t_shared(prime_pow.mpz_cconv, x, prec, absolute, prime_pow) @@ -778,7 +767,7 @@ cdef inline long cconv_mpq_t(celement out, mpq_t x, long prec, bint absolute, Po cdef inline int cconv_mpq_t_out(mpq_t out, celement x, long valshift, long prec, PowComputer_ prime_pow) except -1: """ - Converts the underlying `p`-adic element into a rational + Convert the underlying `p`-adic element into a rational. - ``out`` -- gives a rational approximating the input. Currently uses rational reconstruction but may change in the future to use a more naive method @@ -804,14 +793,14 @@ cdef inline long cconv_mpz_t(celement out, mpz_t x, long prec, bint absolute, Po INPUT: - - ``out`` -- an ``celement`` to store the output. - - ``x`` -- an ``mpz_t`` giving the integer to be converted. + - ``out`` -- an ``celement`` to store the output + - ``x`` -- an ``mpz_t`` giving the integer to be converted - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. + relative depending on the ``absolute`` input - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -825,15 +814,15 @@ cdef inline long cconv_mpz_t(celement out, mpz_t x, long prec, bint absolute, Po cdef inline int cconv_mpz_t_out(mpz_t out, celement x, long valshift, long prec, PowComputer_ prime_pow) except -1: """ - Converts the underlying `p`-adic element into an integer if + Convert the underlying `p`-adic element into an integer if possible. - ``out`` -- stores the resulting integer as an integer between 0 - and `p^{prec + valshift}`. - - ``x`` -- an ``celement`` giving the underlying `p`-adic element. - - ``valshift`` -- a long giving the power of `p` to shift `x` by. - -` ``prec`` -- a long, the precision of ``x``: currently not used. - - ``prime_pow`` -- a PowComputer for the ring. + and `p^{prec + valshift}` + - ``x`` -- an ``celement`` giving the underlying `p`-adic element + - ``valshift`` -- a long giving the power of `p` to shift `x` by + -` ``prec`` -- a long, the precision of ``x``: currently not used + - ``prime_pow`` -- a PowComputer for the ring """ cdef long degree = fmpz_poly_degree(x) if degree > 0: @@ -850,7 +839,7 @@ cdef inline int cconv_mpz_t_out(mpz_t out, celement x, long valshift, long prec, cdef cmatrix_mod_pn(celement a, long aprec, long valshift, PowComputer_ prime_pow): r""" - Returns the matrix of right multiplication by the element on + Return the matrix of right multiplication by the element on the power basis `1, x, x^2, \ldots, x^{d-1}` for this extension field. Thus the *rows* of this matrix give the images of each of the `x^i`. The entries of the matrices are diff --git a/src/sage/libs/linkages/padics/mpz.pxi b/src/sage/libs/linkages/padics/mpz.pxi index 3a555e441dc..01ff197488e 100644 --- a/src/sage/libs/linkages/padics/mpz.pxi +++ b/src/sage/libs/linkages/padics/mpz.pxi @@ -40,8 +40,8 @@ cdef inline int cconstruct(mpz_t value, PowComputer_ prime_pow) except -1: INPUT: - - ``unit`` -- an ``mpz_t`` to be initialized. - - ``prime_pow`` -- the PowComputer for the ring. + - ``unit`` -- an ``mpz_t`` to be initialized + - ``prime_pow`` -- the PowComputer for the ring """ mpz_init(value) @@ -51,8 +51,8 @@ cdef inline int cdestruct(mpz_t value, PowComputer_ prime_pow) except -1: INPUT: - - ``unit`` -- an ``mpz_t`` to be cleared. - - ``prime_pow`` -- the PowComputer for the ring. + - ``unit`` -- an ``mpz_t`` to be cleared + - ``prime_pow`` -- the PowComputer for the ring """ mpz_clear(value) @@ -62,12 +62,12 @@ cdef inline int ccmp(mpz_t a, mpz_t b, long prec, bint reduce_a, bint reduce_b, INPUT: - - ``a`` -- an ``mpz_t``. - - ``b`` -- an ``mpz_t``. - - ``prec`` -- a long, the precision of the comparison. - - ``reduce_a`` -- a bint, whether a needs to be reduced. - - ``reduce_b`` -- a bint, whether b needs to be reduced. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- an ``mpz_t`` + - ``b`` -- an ``mpz_t`` + - ``prec`` -- a long, the precision of the comparison + - ``reduce_a`` -- a bint, whether a needs to be reduced + - ``reduce_b`` -- a bint, whether b needs to be reduced + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: @@ -97,10 +97,10 @@ cdef inline int cneg(mpz_t out, mpz_t a, long prec, PowComputer_ prime_pow) exce INPUT: - - ``out`` -- an ``mpz_t`` to store the negation. - - ``a`` -- an ``mpz_t`` to be negated. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the negation + - ``a`` -- an ``mpz_t`` to be negated + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ mpz_neg(out, a) @@ -112,11 +112,11 @@ cdef inline int cadd(mpz_t out, mpz_t a, mpz_t b, long prec, PowComputer_ prime_ INPUT: - - ``out`` -- an ``mpz_t`` to store the sum. - - ``a`` -- an ``mpz_t``, the first summand. - - ``b`` -- an ``mpz_t``, the second summand. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the sum + - ``a`` -- an ``mpz_t``, the first summand + - ``b`` -- an ``mpz_t``, the second summand + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ mpz_add(out, a, b) @@ -126,14 +126,12 @@ cdef inline bint creduce(mpz_t out, mpz_t a, long prec, PowComputer_ prime_pow) INPUT: - - ``out`` -- an ``mpz_t`` to store the reduction. - - ``a`` -- the element to be reduced. - - ``prec`` -- a long, the precision to reduce modulo. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the reduction + - ``a`` -- the element to be reduced + - ``prec`` -- a long, the precision to reduce modulo + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - returns True if the reduction is zero; False otherwise. + OUTPUT: ``True`` if the reduction is zero; ``False`` otherwise """ # The following could fail if the value returned by # prime_pow.pow_mpz_t_tmp(prec) is zero. We could add a sig_on()/sig_off() @@ -151,14 +149,12 @@ cdef inline bint creduce_small(mpz_t out, mpz_t a, long prec, PowComputer_ prime INPUT: - - ``out`` -- an ``mpz_t`` to store the reduction. - - ``a`` -- the element to be reduced. - - ``prec`` -- a long, the precision to reduce modulo. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the reduction + - ``a`` -- the element to be reduced + - ``prec`` -- a long, the precision to reduce modulo + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - returns True if the reduction is zero; False otherwise. + OUTPUT: ``True`` if the reduction is zero; ``False`` otherwise """ if mpz_sgn(a) < 0: mpz_add(out, a, prime_pow.pow_mpz_t_tmp(prec)) @@ -175,10 +171,10 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_ prime INPUT: - - ``out`` -- an ``mpz_t`` to store the unit. - - ``a`` -- the element whose valuation and unit are desired. - - ``prec`` -- a long, used if `a = 0`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the unit + - ``a`` -- the element whose valuation and unit are desired + - ``prec`` -- a long, used if `a = 0` + - ``prime_pow`` -- the PowComputer for the ring - ``reduce_relative`` -- a bint: whether the final result should be reduced at precision ``prec`` (case ``False``) or ``prec - valuation`` (case ``True``) @@ -195,7 +191,7 @@ cdef inline long cremove(celement out, celement a, long prec, PowComputer_ prime cdef inline long cvaluation(mpz_t a, long prec, PowComputer_ prime_pow) except -1: """ - Returns the maximum power of the uniformizer dividing this + Return the maximum power of the uniformizer dividing this element. This function differs from :meth:`cremove` in that the unit is @@ -203,9 +199,9 @@ cdef inline long cvaluation(mpz_t a, long prec, PowComputer_ prime_pow) except - INPUT: - - ``a`` -- the element whose valuation is desired. - - ``prec`` -- a long, used if `a = 0`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``a`` -- the element whose valuation is desired + - ``prec`` -- a long, used if `a = 0` + - ``prime_pow`` -- the PowComputer for the ring OUTPUT: @@ -218,34 +214,31 @@ cdef inline long cvaluation(mpz_t a, long prec, PowComputer_ prime_pow) except - cdef inline bint cisunit(mpz_t a, PowComputer_ prime_pow) except -1: """ - Returns whether this element has valuation zero. + Return whether this element has valuation zero. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. - - OUTPUT: + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - - returns True if `a` has valuation 0, and False otherwise. + OUTPUT: ``True`` if `a` has valuation 0, and ``False`` otherwise """ return mpz_divisible_p(a, prime_pow.prime.value) == 0 cdef inline int cshift(mpz_t out, mpz_t rem, mpz_t a, long n, long prec, PowComputer_ prime_pow, bint reduce_afterward) except -1: """ - Multiplies by a power of the uniformizer. + Multiply by a power of the uniformizer. INPUT: - ``out`` -- an ``mpz_t`` to store the result. If `n >= 0` then - out will be set to `a * p^n`. If `n < 0`, out will - be set to `a // p^n`. + out will be set to `a * p^n`. If `n < 0`, out will be set to `a // p^n`. - ``rem`` -- an ``mpz_t`` to store the remainder, when `n < 0` - - ``a`` -- the element to shift. - - ``n`` -- long, the amount to shift by. - - ``prec`` -- long, a precision modulo which to reduce. - - ``prime_pow`` -- the PowComputer for the ring. - - ``reduce_afterward`` -- whether to reduce afterward. + - ``a`` -- the element to shift + - ``n`` -- long, the amount to shift by + - ``prec`` -- long, a precision modulo which to reduce + - ``prime_pow`` -- the PowComputer for the ring + - ``reduce_afterward`` -- whether to reduce afterward """ if n > 0: mpz_mul(out, a, prime_pow.pow_mpz_t_tmp(n)) @@ -260,20 +253,19 @@ cdef inline int cshift(mpz_t out, mpz_t rem, mpz_t a, long n, long prec, PowComp cdef inline int cshift_notrunc(mpz_t out, mpz_t a, long n, long prec, PowComputer_ prime_pow, bint reduce_afterward) except -1: """ - Multiplies by a power of the uniformizer, assuming that the + Multiply by a power of the uniformizer, assuming that the valuation of a is at least -n. INPUT: - ``out`` -- an ``mpz_t`` to store the result. If `n >= 0` then - out will be set to `a * p^n`. If `n < 0`, out will - be set to `a // p^n`. + out will be set to `a * p^n`. If `n < 0`, out will be set to `a // p^n`. - ``a`` -- the element to shift. Assumes that the valuation of a is at least -n. - - ``n`` -- long, the amount to shift by. - - ``prec`` -- long, a precision modulo which to reduce. - - ``prime_pow`` -- the PowComputer for the ring. - - ``reduce_afterward`` -- whether to reduce afterward. + - ``n`` -- long, the amount to shift by + - ``prec`` -- long, a precision modulo which to reduce + - ``prime_pow`` -- the PowComputer for the ring + - ``reduce_afterward`` -- whether to reduce afterward """ if n > 0: mpz_mul(out, a, prime_pow.pow_mpz_t_tmp(n)) @@ -294,11 +286,11 @@ cdef inline int csub(mpz_t out, mpz_t a, mpz_t b, long prec, PowComputer_ prime_ INPUT: - - ``out`` -- an ``mpz_t`` to store the difference. - - ``a`` -- an ``mpz_t``, the first input. - - ``b`` -- an ``mpz_t``, the second input. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the difference + - ``a`` -- an ``mpz_t``, the first input + - ``b`` -- an ``mpz_t``, the second input + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ mpz_sub(out, a, b) @@ -310,10 +302,10 @@ cdef inline int cinvert(mpz_t out, mpz_t a, long prec, PowComputer_ prime_pow) e INPUT: - - ``out`` -- an ``mpz_t`` to store the inverse. - - ``a`` -- an ``mpz_t``, the element to be inverted. - - ``prec`` -- a long, the precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the inverse + - ``a`` -- an ``mpz_t``, the element to be inverted + - ``prec`` -- a long, the precision + - ``prime_pow`` -- the PowComputer for the ring """ cdef bint success success = mpz_invert(out, a, prime_pow.pow_mpz_t_tmp(prec)) @@ -328,11 +320,11 @@ cdef inline int cmul(mpz_t out, mpz_t a, mpz_t b, long prec, PowComputer_ prime_ INPUT: - - ``out`` -- an ``mpz_t`` to store the product. - - ``a`` -- an ``mpz_t``, the first input. - - ``b`` -- an ``mpz_t``, the second input. - - ``prec`` -- a long, the precision: ignored. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the product + - ``a`` -- an ``mpz_t``, the first input + - ``b`` -- an ``mpz_t``, the second input + - ``prec`` -- a long, the precision: ignored + - ``prime_pow`` -- the PowComputer for the ring """ mpz_mul(out, a, b) @@ -345,11 +337,11 @@ cdef inline int cdivunit(mpz_t out, mpz_t a, mpz_t b, long prec, PowComputer_ pr INPUT: - - ``out`` -- an ``mpz_t`` to store the quotient. - - ``a`` -- an ``mpz_t``, the first input. - - ``b`` -- an ``mpz_t``, the second input. - - ``prec`` -- a long, the precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the quotient + - ``a`` -- an ``mpz_t``, the first input + - ``b`` -- an ``mpz_t``, the second input + - ``prec`` -- a long, the precision + - ``prime_pow`` -- the PowComputer for the ring """ cdef bint success success = mpz_invert(prime_pow.aliasing, b, prime_pow.pow_mpz_t_tmp(prec)) @@ -359,53 +351,49 @@ cdef inline int cdivunit(mpz_t out, mpz_t a, mpz_t b, long prec, PowComputer_ pr cdef inline int csetone(mpz_t out, PowComputer_ prime_pow) except -1: """ - Sets to 1. + Set to 1. INPUT: - - ``out`` -- the ``mpz_t`` in which to store 1. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``mpz_t`` in which to store 1 + - ``prime_pow`` -- the PowComputer for the ring """ mpz_set_ui(out, 1) cdef inline int csetzero(mpz_t out, PowComputer_ prime_pow) except -1: """ - Sets to 0. + Set to 0. INPUT: - - ``out`` -- the ``mpz_t`` in which to store 0. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``mpz_t`` in which to store 0 + - ``prime_pow`` -- the PowComputer for the ring """ mpz_set_ui(out, 0) cdef inline bint cisone(mpz_t out, PowComputer_ prime_pow) except -1: """ - Returns whether this element is equal to 1. + Return whether this element is equal to 1. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. - - OUTPUT: + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - - returns True if `a = 1`, and False otherwise. + OUTPUT: ``True`` if `a = 1`, and ``False`` otherwise """ return mpz_cmp_ui(out, 1) == 0 cdef inline bint ciszero(mpz_t out, PowComputer_ prime_pow) except -1: """ - Returns whether this element is equal to 0. + Return whether this element is equal to 0. INPUT: - - ``a`` -- the element to test. - - ``prime_pow`` -- the PowComputer for the ring. - - OUTPUT: + - ``a`` -- the element to test + - ``prime_pow`` -- the PowComputer for the ring - - returns True if `a = 0`, and False otherwise. + OUTPUT: ``True`` if `a = 0`, and ``False`` otherwise """ return mpz_cmp_ui(out, 0) == 0 @@ -415,11 +403,11 @@ cdef inline int cpow(mpz_t out, mpz_t a, mpz_t n, long prec, PowComputer_ prime_ INPUT: - - ``out`` -- the ``mpz_t`` in which to store the result. - - ``a`` -- the base. - - ``n`` -- an ``mpz_t``, the exponent. - - ``prec`` -- a long, the working absolute precision. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``mpz_t`` in which to store the result + - ``a`` -- the base + - ``n`` -- an ``mpz_t``, the exponent + - ``prec`` -- a long, the working absolute precision + - ``prime_pow`` -- the PowComputer for the ring """ mpz_powm(out, a, n, prime_pow.pow_mpz_t_tmp(prec)) @@ -429,9 +417,9 @@ cdef inline int ccopy(mpz_t out, mpz_t a, PowComputer_ prime_pow) except -1: INPUT: - - ``out`` -- the ``mpz_t`` to store the result. - - ``a`` -- the element to copy. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``mpz_t`` to store the result + - ``a`` -- the element to copy + - ``prime_pow`` -- the PowComputer for the ring """ mpz_set(out, a) @@ -441,12 +429,10 @@ cdef inline cpickle(mpz_t a, PowComputer_ prime_pow): INPUT: - - ``a`` the element to pickle. - - ``prime_pow`` the PowComputer for the ring. + - ``a`` -- the element to pickle + - ``prime_pow`` -- the PowComputer for the ring - OUTPUT: - - - an Integer storing ``a``. + OUTPUT: an Integer storing ``a`` """ cdef Integer pic = PY_NEW(Integer) mpz_set(pic.value, a) @@ -458,9 +444,9 @@ cdef inline int cunpickle(mpz_t out, x, PowComputer_ prime_pow) except -1: INPUT: - - ``out`` -- the ``mpz_t`` in which to store the result. - - ``x`` -- the result of :meth:`cpickle`. - - ``prime_pow`` -- the PowComputer for the ring. + - ``out`` -- the ``mpz_t`` in which to store the result + - ``x`` -- the result of :meth:`cpickle` + - ``prime_pow`` -- the PowComputer for the ring """ mpz_set(out, (x).value) @@ -470,10 +456,10 @@ cdef inline long chash(mpz_t a, long ordp, long prec, PowComputer_ prime_pow) ex INPUT: - - ``a`` -- an ``mpz_t`` storing the underlying element to hash. - - ``ordp`` -- a long storing the valuation. - - ``prec`` -- a long storing the precision. - - ``prime_pow`` -- a PowComputer for the ring. + - ``a`` -- an ``mpz_t`` storing the underlying element to hash + - ``ordp`` -- a long storing the valuation + - ``prec`` -- a long storing the precision + - ``prime_pow`` -- a PowComputer for the ring """ # This implementation is for backward compatibility and may be changed in the future cdef long n, d @@ -499,11 +485,11 @@ cdef inline cexpansion_next(mpz_t value, expansion_mode mode, long curpower, Pow INPUT: - - ``value`` -- the `p`-adic element whose expansion is desired. + - ``value`` -- the `p`-adic element whose expansion is desired - ``mode`` -- either ``simple_mode`` or ``smallest_mode`` - ``curpower`` -- the current power of `p` for which the coefficient is being found. Only used in ``smallest_mode``. - - ``prime_pow`` -- A ``PowComputer`` holding `p`-adic data. + - ``prime_pow`` -- a ``PowComputer`` holding `p`-adic data """ if mode == teichmuller_mode: raise NotImplementedError @@ -525,13 +511,13 @@ cdef inline cexpansion_next(mpz_t value, expansion_mode mode, long curpower, Pow cdef inline cexpansion_getitem(mpz_t value, long m, PowComputer_ prime_pow): """ - Return the `m`th `p`-adic digit in the ``simple_mode`` expansion. + Return the `m`-th `p`-adic digit in the ``simple_mode`` expansion. INPUT: - - ``value`` -- the `p`-adic element whose expansion is desired. - - ``m`` -- a non-negative integer: which entry in the `p`-adic expansion to return. - - ``prime_pow`` -- A ``PowComputer`` holding `p`-adic data. + - ``value`` -- the `p`-adic element whose expansion is desired + - ``m`` -- nonnegative integer; which entry in the `p`-adic expansion to return + - ``prime_pow`` -- a ``PowComputer`` holding `p`-adic data """ cdef Integer ans = PY_NEW(Integer) if m > 0: @@ -551,8 +537,8 @@ cdef list ccoefficients(mpz_t x, long valshift, long prec, PowComputer_ prime_po INPUT: - - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part. - - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by. + - ``x`` -- a ``celement`` giving the underlying `p`-adic element, or possibly its unit part + - ``valshift`` -- a long giving the power of the uniformizer to shift `x` by - ``prec`` -- a long, the (relative) precision desired, used in rational reconstruction - ``prime_pow`` -- the ``PowComputer`` of the ring """ @@ -574,11 +560,10 @@ cdef int cteichmuller(mpz_t out, mpz_t value, long prec, PowComputer_ prime_pow) INPUT: - ``out`` -- an ``mpz_t`` which is set to a `p-1` root of unity - congruent to `value` mod `p`; or 0 if `a \equiv 0 - \pmod{p}`. - - ``value`` -- an ``mpz_t``, the element mod `p` to lift. - - ``prec`` -- a long, the precision to which to lift. - - ``prime_pow`` -- the ``PowComputer`` of the ring. + congruent to `value` mod `p`; or 0 if `a \equiv 0 \pmod{p}` + - ``value`` -- an ``mpz_t``, the element mod `p` to lift + - ``prec`` -- a long, the precision to which to lift + - ``prime_pow`` -- the ``PowComputer`` of the ring """ if mpz_divisible_p(value, prime_pow.prime.value) != 0: mpz_set_ui(out, 0) @@ -617,17 +602,17 @@ cdef int cconv(mpz_t out, x, long prec, long valshift, PowComputer_ prime_pow) e INPUT: - - ``out`` -- an ``mpz_t`` to store the output. + - ``out`` -- an ``mpz_t`` to store the output - - ``x`` -- a Sage element that can be converted to a `p`-adic element. + - ``x`` -- a Sage element that can be converted to a `p`-adic element - ``prec`` -- a long, giving the precision desired: absolute if - `valshift = 0`, relative if `valshift != 0`. + `valshift = 0`, relative if `valshift != 0` - ``valshift`` -- the power of the uniformizer to divide by before - storing the result in ``out``. + storing the result in ``out`` - - ``prime_pow`` -- a PowComputer for the ring. + - ``prime_pow`` -- a PowComputer for the ring """ return cconv_shared(out, x, prec, valshift, prime_pow) @@ -638,14 +623,14 @@ cdef inline long cconv_mpq_t(mpz_t out, mpq_t x, long prec, bint absolute, PowCo INPUT: - - ``out`` -- an ``mpz_t`` to store the output. - - ``x`` -- an ``mpq_t`` giving the integer to be converted. + - ``out`` -- an ``mpz_t`` to store the output + - ``x`` -- an ``mpq_t`` giving the integer to be converted - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. + relative depending on the ``absolute`` input - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -656,7 +641,7 @@ cdef inline long cconv_mpq_t(mpz_t out, mpq_t x, long prec, bint absolute, PowCo cdef inline int cconv_mpq_t_out(mpq_t out, mpz_t x, long valshift, long prec, PowComputer_ prime_pow) except -1: """ - Converts the underlying `p`-adic element into a rational + Convert the underlying `p`-adic element into a rational. - ``out`` -- gives a rational approximating the input. Currently uses rational reconstruction but may change in the future to use a more naive method @@ -674,14 +659,14 @@ cdef inline long cconv_mpz_t(mpz_t out, mpz_t x, long prec, bint absolute, PowCo INPUT: - - ``out`` -- an ``mpz_t`` to store the output. - - ``x`` -- an ``mpz_t`` giving the integer to be converted. + - ``out`` -- an ``mpz_t`` to store the output + - ``x`` -- an ``mpz_t`` giving the integer to be converted - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. + relative depending on the ``absolute`` input - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -692,14 +677,14 @@ cdef inline long cconv_mpz_t(mpz_t out, mpz_t x, long prec, bint absolute, PowCo cdef inline int cconv_mpz_t_out(mpz_t out, mpz_t x, long valshift, long prec, PowComputer_ prime_pow) except -1: """ - Converts the underlying `p`-adic element into an integer if + Convert the underlying `p`-adic element into an integer if possible. - ``out`` -- stores the resulting integer as an integer between 0 - and `p^{prec + valshift}`. - - ``x`` -- an ``mpz_t`` giving the underlying `p`-adic element. - - ``valshift`` -- a long giving the power of `p` to shift `x` by. - -` ``prec`` -- a long, the precision of ``x``: currently not used. - - ``prime_pow`` -- a PowComputer for the ring. + and `p^{prec + valshift}` + - ``x`` -- an ``mpz_t`` giving the underlying `p`-adic element + - ``valshift`` -- a long giving the power of `p` to shift `x` by + -` ``prec`` -- a long, the precision of ``x``: currently not used + - ``prime_pow`` -- a PowComputer for the ring """ return cconv_mpz_t_out_shared(out, x, valshift, prec, prime_pow) diff --git a/src/sage/libs/linkages/padics/relaxed/API.pxi b/src/sage/libs/linkages/padics/relaxed/API.pxi index 4e9ea075bb2..07934c1322d 100644 --- a/src/sage/libs/linkages/padics/relaxed/API.pxi +++ b/src/sage/libs/linkages/padics/relaxed/API.pxi @@ -17,9 +17,9 @@ of its reduction modulo `\pi`) and propagate the carry accordingly. Our API is based on two template types (which have to be instantiated in implementations): -- ``cdigit``: the type of a digit +- ``cdigit`` -- the type of a digit -- ``celement``: the type of an element (which is then a polynomial whose +- ``celement`` -- the type of an element (which is then a polynomial whose coefficients are elements of type ``cdigit``) The remainder of the file gives the function signatures. @@ -100,7 +100,7 @@ cdef inline void digit_set_ui(cdigit a, long b): INPUT: - ``a`` -- the ``cdigit`` to set up - - ``b`` -- an integer, the value of assign + - ``b`` -- integer; the value of assign """ pass @@ -134,12 +134,12 @@ cdef inline bint digit_equal(cdigit a, cdigit b): cdef inline bint digit_equal_ui(cdigit a, long b): r""" - Comparison of a digit and an integer + Comparison of a digit and an integer. INPUT: - ``a`` -- a ``cdigit`` - - ``b`` -- an integer + - ``b`` -- integer OUTPUT: @@ -149,7 +149,7 @@ cdef inline bint digit_equal_ui(cdigit a, long b): cdef inline bint digit_is_zero(cdigit a): r""" - Comparison to zero + Comparison to zero. INPUT: @@ -163,7 +163,7 @@ cdef inline bint digit_is_zero(cdigit a): cdef inline void digit_random_init(randgen generator, long seed): r""" - Initialize the random generator with a new seed + Initialize the random generator with a new seed. INPUT: @@ -326,7 +326,7 @@ cdef inline Element element_get_sage(celement x, PowComputer_class prime_pow): cdef inline void element_set(celement x, celement y): r""" - Set an element + Set an element. INPUT: @@ -344,7 +344,7 @@ cdef inline cdigit element_get_digit(celement x, long i): INPUT: - ``x`` -- a ``celement`` - - ``i`` -- an integer + - ``i`` -- integer """ pass @@ -356,8 +356,8 @@ cdef inline void element_get_slice(celement res, celement x, long start, long le - ``res`` -- a ``celement`` to store the slice - ``x`` -- a ``celement``, the element from which the slice is extracted - - ``start`` -- an integer, the start position of the slice - - ``length`` -- an integer, the length of the slice + - ``start`` -- integer; the start position of the slice + - ``length`` -- integer; the length of the slice .. NOTE:: @@ -375,7 +375,7 @@ cdef inline void element_set_digit(celement x, cdigit a, long i): - ``x`` -- a ``celement`` - ``a`` -- a ``cdigit`` - - ``i`` -- an integer + - ``i`` -- integer """ pass @@ -386,8 +386,8 @@ cdef inline void element_set_digit_ui(celement x, long a, long i): INPUT: - ``x`` -- a ``celement`` - - ``a`` -- an integer - - ``i`` -- an integer + - ``a`` -- integer + - ``i`` -- integer """ pass @@ -399,7 +399,7 @@ cdef inline void element_set_digit_sage(celement x, Element a, long i): - ``x`` -- a ``celement`` - ``a`` -- a Sage element - - ``i`` -- an integer + - ``i`` -- integer """ pass @@ -414,7 +414,7 @@ cdef inline void element_iadd_digit(celement x, cdigit a, long i): - ``x`` -- a ``celement`` - ``a`` -- a ``cdigit`` - - ``i`` -- an integer + - ``i`` -- integer """ pass @@ -427,7 +427,7 @@ cdef inline void element_isub_digit(celement x, cdigit a, long i): - ``x`` -- a ``celement`` - ``a`` -- a ``cdigit`` - - ``i`` -- an integer + - ``i`` -- integer """ pass @@ -475,7 +475,7 @@ cdef inline void element_reduce_digit(celement x, long i, PowComputer_class prim INPUT: - ``x`` -- a ``celement``, the element to update - - ``i`` -- an integer + - ``i`` -- integer - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -488,7 +488,7 @@ cdef inline void element_reducesmall_digit(fmpz_poly_t x, long i, PowComputer_fl INPUT: - ``x`` -- a ``celement``, the element to update - - ``i`` -- an integer + - ``i`` -- integer - ``prime_pow`` -- the PowComputer for the ring """ pass @@ -501,7 +501,7 @@ cdef inline void element_reduceneg_digit(fmpz_poly_t x, long i, PowComputer_flin INPUT: - ``x`` -- a ``celement``, the element to update - - ``i`` -- an integer + - ``i`` -- integer - ``prime_pow`` -- the PowComputer for the ring """ pass diff --git a/src/sage/libs/linkages/padics/relaxed/flint.pxi b/src/sage/libs/linkages/padics/relaxed/flint.pxi index 7085fd76ac8..11ead5edef5 100644 --- a/src/sage/libs/linkages/padics/relaxed/flint.pxi +++ b/src/sage/libs/linkages/padics/relaxed/flint.pxi @@ -101,7 +101,7 @@ cdef inline void digit_set_ui(fmpz_t a, slong b) noexcept: INPUT: - ``a`` -- the ``cdigit`` to set up - - ``b`` -- an integer, the value of assign + - ``b`` -- integer; the value of assign """ fmpz_set_ui(a, b) @@ -140,7 +140,7 @@ cdef inline bint digit_equal_ui(fmpz_t a, slong b) noexcept: INPUT: - ``a`` -- a ``cdigit`` - - ``b`` -- an integer + - ``b`` -- integer OUTPUT: @@ -369,7 +369,7 @@ cdef inline fmpz* element_get_digit(fmpz_poly_t x, slong i) noexcept: INPUT: - ``x`` -- a ``celement`` - - ``i`` -- an integer + - ``i`` -- integer """ return get_coeff(x, i) @@ -381,8 +381,8 @@ cdef inline void element_get_slice(fmpz_poly_t res, fmpz_poly_t x, slong start, - ``res`` -- a ``celement`` to store the slice - ``x`` -- a ``celement``, the element from which the slice is extracted - - ``start`` -- an integer, the start position of the slice - - ``length`` -- an integer, the length of the slice + - ``start`` -- integer; the start position of the slice + - ``length`` -- integer; the length of the slice .. NOTE:: @@ -400,7 +400,7 @@ cdef inline void element_set_digit(fmpz_poly_t x, fmpz_t a, slong i) noexcept: - ``x`` -- a ``celement`` - ``a`` -- a ``cdigit`` - - ``i`` -- an integer + - ``i`` -- integer """ fmpz_poly_set_coeff_fmpz(x, i, a) @@ -411,8 +411,8 @@ cdef inline void element_set_digit_ui(fmpz_poly_t x, slong a, slong i) noexcept: INPUT: - ``x`` -- a ``celement`` - - ``a`` -- an integer - - ``i`` -- an integer + - ``a`` -- integer + - ``i`` -- integer """ fmpz_poly_set_coeff_ui(x, i, a) @@ -424,7 +424,7 @@ cdef inline void element_set_digit_sage(fmpz_poly_t x, Integer a, slong i) noexc - ``x`` -- a ``celement`` - ``a`` -- a Sage element - - ``i`` -- an integer + - ``i`` -- integer """ fmpz_poly_set_coeff_mpz(x, i, a.value) @@ -439,7 +439,7 @@ cdef inline void element_iadd_digit(fmpz_poly_t x, fmpz_t a, slong i) noexcept: - ``x`` -- a ``celement`` - ``a`` -- a ``cdigit`` - - ``i`` -- an integer + - ``i`` -- integer """ iadd_coeff(x, a, i) @@ -452,7 +452,7 @@ cdef inline void element_isub_digit(fmpz_poly_t x, fmpz_t a, slong i) noexcept: - ``x`` -- a ``celement`` - ``a`` -- a ``cdigit`` - - ``i`` -- an integer + - ``i`` -- integer """ isub_coeff(x, a, i) @@ -500,7 +500,7 @@ cdef inline void element_reduce_digit(fmpz_poly_t x, slong i, PowComputer_flint INPUT: - ``x`` -- a ``celement``, the element to update - - ``i`` -- an integer + - ``i`` -- integer - ``prime_pow`` -- the PowComputer for the ring """ reduce_coeff(x, i, prime_pow.fprime) @@ -513,7 +513,7 @@ cdef inline void element_reducesmall_digit(fmpz_poly_t x, slong i, PowComputer_f INPUT: - ``x`` -- a ``celement``, the element to update - - ``i`` -- an integer + - ``i`` -- integer - ``prime_pow`` -- the PowComputer for the ring """ reducesmall_coeff(x, i, prime_pow.fprime) @@ -526,7 +526,7 @@ cdef inline void element_reduceneg_digit(fmpz_poly_t x, slong i, PowComputer_fli INPUT: - ``x`` -- a ``celement``, the element to update - - ``i`` -- an integer + - ``i`` -- integer - ``prime_pow`` -- the PowComputer for the ring """ reduceneg_coeff(x, i, prime_pow.fprime) diff --git a/src/sage/libs/linkages/padics/unram_shared.pxi b/src/sage/libs/linkages/padics/unram_shared.pxi index 7ffbebc5f52..2cb22461b21 100644 --- a/src/sage/libs/linkages/padics/unram_shared.pxi +++ b/src/sage/libs/linkages/padics/unram_shared.pxi @@ -8,7 +8,7 @@ def frobenius_unram(self, arithmetic=True): INPUT: - - ``self`` -- an element of an unramified extension. + - ``self`` -- an element of an unramified extension - ``arithmetic`` -- whether to apply the arithmetic Frobenius (acting by raising to the `p`-th power on the residue field). If ``False`` is provided, the image of geometric Frobenius (raising to the `(1/p)`-th @@ -39,7 +39,7 @@ def frobenius_unram(self, arithmetic=True): sage: c.frobenius().frobenius() (a + 1)*7^-1 + O(7^3) - An error will be raised if the parent of self is a ramified extension:: + An error will be raised if the parent of ``self`` is a ramified extension:: sage: x = polygen(ZZ, 'x') sage: K. = Qp(5).extension(x^2 - 5) @@ -55,7 +55,6 @@ def frobenius_unram(self, arithmetic=True): sage: x = R.random_element() sage: x.frobenius(arithmetic=false).frobenius() == x True - """ if self == 0: return self @@ -95,9 +94,9 @@ def norm_unram(self, base = None): INPUT: - - ``base`` -- a subfield of the parent `L` of this element. - The norm is the relative norm from ``L`` to ``base``. - Defaults to the absolute norm down to `\QQ_p` or `\ZZ_p`. + - ``base`` -- a subfield of the parent `L` of this element; the norm is the + relative norm from ``L`` to ``base``. Defaults to the absolute norm down + to `\QQ_p` or `\ZZ_p`. EXAMPLES:: diff --git a/src/sage/libs/lrcalc/lrcalc.py b/src/sage/libs/lrcalc/lrcalc.py index b3c788ba57f..2a5144c0934 100644 --- a/src/sage/libs/lrcalc/lrcalc.py +++ b/src/sage/libs/lrcalc/lrcalc.py @@ -215,7 +215,7 @@ def lrcoef_unsafe(outer, inner1, inner2): INPUT: - - ``outer`` -- a partition (weakly decreasing list of non-negative integers) + - ``outer`` -- a partition (weakly decreasing list of nonnegative integers) - ``inner1`` -- a partition - ``inner2`` -- a partition @@ -246,7 +246,7 @@ def lrcoef(outer, inner1, inner2): INPUT: - - ``outer`` -- a partition (weakly decreasing list of non-negative integers) + - ``outer`` -- a partition (weakly decreasing list of nonnegative integers) - ``inner1`` -- a partition - ``inner2`` -- a partition @@ -280,9 +280,9 @@ def mult(part1, part2, maxrows=None, level=None, quantum=None) -> dict: - ``part1`` -- a partition - ``part2`` -- a partition - - ``maxrows`` -- (optional) an integer - - ``level`` -- (optional) an integer - - ``quantum`` -- (optional) an element of a ring + - ``maxrows`` -- integer (optional) + - ``level`` -- integer (optional) + - ``quantum`` -- an element of a ring (optional) If ``maxrows`` is specified, then only partitions with at most this number of rows are included in the result. @@ -364,7 +364,7 @@ def skew(outer, inner, maxrows=-1) -> dict: - ``outer`` -- a partition - ``inner`` -- a partition - - ``maxrows`` -- an integer or ``None`` + - ``maxrows`` -- integer or ``None`` If ``maxrows`` is specified, then only partitions with at most this number of rows are included in the result. @@ -389,9 +389,9 @@ def coprod(part, all=0) -> dict: INPUT: - ``part`` -- a partition - - ``all`` -- an integer + - ``all`` -- integer - If ``all`` is non-zero then all terms are included in the result. + If ``all`` is nonzero then all terms are included in the result. If ``all`` is zero, then only pairs of partitions ``(part1, part2)`` for which the weight of ``part1`` is greater than or equal to the weight of ``part2`` are included; the rest of the @@ -423,9 +423,9 @@ def mult_schubert(w1, w2, rank=0) -> dict: - ``w1`` -- a permutation - ``w2`` -- a permutation - - ``rank`` -- an integer + - ``rank`` -- integer - If ``rank`` is non-zero, then only permutations from the symmetric + If ``rank`` is nonzero, then only permutations from the symmetric group `S(\mathrm{rank})` are included in the result. EXAMPLES:: @@ -451,7 +451,7 @@ def lrskew(outer, inner, weight=None, maxrows=-1): - ``outer`` -- a partition - ``inner`` -- a partition - ``weight`` -- a partition (optional) - - ``maxrows`` -- a positive integer (optional) + - ``maxrows`` -- positive integer (optional) OUTPUT: an iterator of :class:`SkewTableau` diff --git a/src/sage/libs/meataxe.pyx b/src/sage/libs/meataxe.pyx index 46559e9e99c..09c25b45155 100644 --- a/src/sage/libs/meataxe.pyx +++ b/src/sage/libs/meataxe.pyx @@ -41,7 +41,7 @@ cdef Matrix_t *rawMatrix(int Field, list entries) except NULL: INPUT: - - ``Field`` -- Integer, the field size + - ``Field`` -- integer; the field size - ``entries`` -- list of lists, the entries of the matrix, also defining the matrix dimensions. It is *not* tested that all rows in ``entries`` have the same length, and it is assumed that both diff --git a/src/sage/libs/mpmath/ext_impl.pyx b/src/sage/libs/mpmath/ext_impl.pyx index d915d9f5a9b..97f135d7219 100644 --- a/src/sage/libs/mpmath/ext_impl.pyx +++ b/src/sage/libs/mpmath/ext_impl.pyx @@ -397,7 +397,7 @@ cdef MPF_to_fixed(mpz_t r, MPF *x, long prec, bint truncate): cdef int MPF_sgn(MPF *x) noexcept: """ - Gives the sign of an MPF (-1, 0, or 1). + Give the sign of an MPF (-1, 0, or 1). """ if x.special: if x.special == S_INF: @@ -409,7 +409,7 @@ cdef int MPF_sgn(MPF *x) noexcept: cdef void MPF_neg(MPF *r, MPF *s) noexcept: """ - Sets r = -s. MPF_neg(x, x) negates in place. + Set r = -s. MPF_neg(x, x) negates in place. """ if s.special: if s.special == S_ZERO: @@ -430,7 +430,7 @@ cdef void MPF_neg(MPF *r, MPF *s) noexcept: cdef void MPF_abs(MPF *r, MPF *s) noexcept: """ - Sets r = abs(s). MPF_abs(r, r) sets the absolute value in place. + Set r = abs(s). MPF_abs(r, r) sets the absolute value in place. """ if s.special: if s.special == S_NINF: @@ -1108,7 +1108,7 @@ cdef mpz_set_ln2(mpz_t x, int prec): cdef void _cy_exp_mpfr(mpz_t y, mpz_t x, int prec) noexcept: """ - Computes y = exp(x) for fixed-point numbers y and x using MPFR, + Compute y = exp(x) for fixed-point numbers y and x using MPFR, assuming that no overflow will occur. """ cdef mpfr_t yf, xf @@ -1124,7 +1124,7 @@ cdef void _cy_exp_mpfr(mpz_t y, mpz_t x, int prec) noexcept: cdef cy_exp_basecase(mpz_t y, mpz_t x, int prec): """ - Computes y = exp(x) for fixed-point numbers y and x, assuming + Compute y = exp(x) for fixed-point numbers y and x, assuming that x is small (|x| ~< 1). At small precisions, this function is equivalent to the exp_basecase function in mpmath.libmp.exp_fixed. @@ -1421,7 +1421,7 @@ cdef MPF_set_ln2(MPF *x, MPopts opts): def exp_fixed(Integer x, int prec, ln2=None): """ - Returns a fixed-point approximation of exp(x) where x is a fixed-point + Return a fixed-point approximation of exp(x) where x is a fixed-point number. EXAMPLES:: @@ -1430,7 +1430,6 @@ def exp_fixed(Integer x, int prec, ln2=None): sage: y = exp_fixed(1<<53, 53) sage: float(y) / 2^53 2.718281828459044 - """ cdef Integer v cdef mpz_t n, t @@ -1456,7 +1455,7 @@ def exp_fixed(Integer x, int prec, ln2=None): def cos_sin_fixed(Integer x, int prec, pi2=None): """ - Returns fixed-point approximations of cos(x), sin(x) where + Return fixed-point approximations of cos(x), sin(x) where x is a fixed-point number. EXAMPLES:: @@ -1467,7 +1466,6 @@ def cos_sin_fixed(Integer x, int prec, pi2=None): 0.5403023058681398 sage: float(s) / 2^53 0.8414709848078965 - """ cdef Integer cv, sv cdef mpfr_t t, cf, sf @@ -1511,7 +1509,7 @@ cdef mpz_log_int(mpz_t v, mpz_t n, int prec): def log_int_fixed(n, long prec, ln2=None): """ - Returns fixed-point approximation of log(n). + Return fixed-point approximation of log(n). EXAMPLES:: @@ -1520,7 +1518,6 @@ def log_int_fixed(n, long prec, ln2=None): 1.6094379124341003 sage: float(log_int_fixed(5, 53)) / 2^53 # exercise cache 1.6094379124341003 - """ global log_int_cache_initialized cdef Integer t @@ -1548,7 +1545,7 @@ def log_int_fixed(n, long prec, ln2=None): cdef _MPF_cos_python(MPF *c, MPF *x, MPopts opts): """ - Computes c = cos(x) by calling the mpmath.libmp Python implementation. + Compute c = cos(x) by calling the mpmath.libmp Python implementation. """ from mpmath.libmp.libelefun import mpf_cos_sin ct = mpf_cos_sin(MPF_to_tuple(x), opts.prec, @@ -1557,7 +1554,7 @@ cdef _MPF_cos_python(MPF *c, MPF *x, MPopts opts): cdef _MPF_sin_python(MPF *s, MPF *x, MPopts opts): """ - Computes s = sin(x) by calling the mpmath.libmp Python implementation. + Compute s = sin(x) by calling the mpmath.libmp Python implementation. """ from mpmath.libmp.libelefun import mpf_cos_sin st = mpf_cos_sin(MPF_to_tuple(x), opts.prec, @@ -1992,7 +1989,6 @@ cdef MPF_hypsum(MPF *a, MPF *b, int p, int q, param_types, str ztype, coeffs, z, This function is not intended to be called directly; it is wrapped by the hypsum_internal function in ext_main.pyx. - """ cdef long i, j, k, n, p_mag, cancellable_real, MAX, magn cdef int have_complex_param, have_complex_arg, have_complex diff --git a/src/sage/libs/mpmath/ext_libmp.pyx b/src/sage/libs/mpmath/ext_libmp.pyx index 10d1b32eb36..487a12d45bc 100644 --- a/src/sage/libs/mpmath/ext_libmp.pyx +++ b/src/sage/libs/mpmath/ext_libmp.pyx @@ -218,7 +218,6 @@ def mpf_pow(tuple x, tuple y, int prec, str rnd='d'): sage: z = mpf_pow(x, y, 53, 'n') sage: to_float(z) 8.0 - """ cdef MPopts opts MPF_set_tuple(&tmp1, x) diff --git a/src/sage/libs/mpmath/ext_main.pyx b/src/sage/libs/mpmath/ext_main.pyx index d4ffc5fa5c0..96d5e9ff828 100644 --- a/src/sage/libs/mpmath/ext_main.pyx +++ b/src/sage/libs/mpmath/ext_main.pyx @@ -114,7 +114,7 @@ cdef __isint(MPF *v): cdef int MPF_set_any(MPF *re, MPF *im, x, MPopts opts, bint str_tuple_ok) except -1: """ - Sets re + im*i = x, where x is any Python number. + Set re + im*i = x, where x is any Python number. Returns 0 if unable to coerce x; 1 if x is real and re was set; 2 if x is complex and both re and im were set. @@ -392,7 +392,7 @@ cdef class Context: def __cinit__(ctx): """ - At present, only a single global context should exist :: + At present, only a single global context should exist:: sage: from mpmath import mp sage: type(mp) @@ -409,9 +409,9 @@ cdef class Context: def default(ctx): """ - Sets defaults. + Set defaults. - TESTS :: + TESTS:: sage: import mpmath sage: mpmath.mp.prec = 100 @@ -426,7 +426,7 @@ cdef class Context: def _get_prec(ctx): """ - Controls the working precision in bits :: + Controls the working precision in bits:: sage: from mpmath import mp sage: mp.prec = 100 @@ -440,7 +440,7 @@ cdef class Context: def _set_prec(ctx, prec): """ - Controls the working precision in bits :: + Controls the working precision in bits:: sage: from mpmath import mp sage: mp.prec = 100 @@ -454,7 +454,7 @@ cdef class Context: def _set_dps(ctx, n): """ - Controls the working precision in decimal digits :: + Controls the working precision in decimal digits:: sage: from mpmath import mp sage: mp.dps = 100 @@ -468,7 +468,7 @@ cdef class Context: def _get_dps(ctx): """ - Controls the working precision in decimal digits :: + Controls the working precision in decimal digits:: sage: from mpmath import mp sage: mp.dps = 100 @@ -487,7 +487,7 @@ cdef class Context: def _get_prec_rounding(ctx): """ - Returns the precision and rounding mode :: + Return the precision and rounding mode:: sage: from mpmath import mp sage: mp._get_prec_rounding() @@ -499,7 +499,7 @@ cdef class Context: cpdef mpf make_mpf(ctx, tuple v): """ - Creates an mpf from tuple data :: + Create an mpf from tuple data:: sage: import mpmath sage: float(mpmath.mp.make_mpf((0,1,-1,1))) @@ -512,7 +512,7 @@ cdef class Context: cpdef mpc make_mpc(ctx, tuple v): """ - Creates an mpc from tuple data :: + Create an mpc from tuple data:: sage: import mpmath sage: complex(mpmath.mp.make_mpc(((0,1,-1,1), (1,1,-2,1)))) @@ -526,7 +526,7 @@ cdef class Context: def convert(ctx, x, strings=True): """ - Converts *x* to an ``mpf``, ``mpc`` or ``mpi``. If *x* is of type ``mpf``, + Convert *x* to an ``mpf``, ``mpc`` or ``mpi``. If *x* is of type ``mpf``, ``mpc``, ``int``, ``float``, ``complex``, the conversion will be performed losslessly. @@ -534,7 +534,7 @@ cdef class Context: working precision. Strings representing fractions or complex numbers are permitted. - TESTS :: + TESTS:: sage: from mpmath import mp, convert sage: mp.dps = 15; mp.pretty = False @@ -546,7 +546,6 @@ cdef class Context: mpf('0.75') sage: convert('2+3j') mpc(real='2.0', imag='3.0') - """ cdef mpf rr cdef mpc rc @@ -614,7 +613,6 @@ cdef class Context: True sage: isinf(mpc(inf,3)) True - """ cdef int s, t, typ if isinstance(x, mpf): @@ -645,7 +643,7 @@ cdef class Context: complex number *x* is considered "normal" if its magnitude is normal. - TESTS :: + TESTS:: sage: from mpmath import isnormal, inf, nan, mpc sage: isnormal(3) @@ -686,7 +684,7 @@ cdef class Context: Return *True* if *x* is integer-valued; otherwise return *False*. - TESTS :: + TESTS:: sage: from mpmath import isint, mpf, inf sage: isint(3) @@ -737,7 +735,7 @@ cdef class Context: def fsum(ctx, terms, bint absolute=False, bint squared=False): """ - Calculates a sum containing a finite number of terms (for infinite + Calculate a sum containing a finite number of terms (for infinite series, see :func:`nsum`). The terms will be converted to mpmath numbers. For len(terms) > 2, this function is generally faster and produces more accurate results than the builtin @@ -746,7 +744,7 @@ cdef class Context: With ``squared=True`` each term is squared, and with ``absolute=True`` the absolute value of each term is used. - TESTS :: + TESTS:: sage: from mpmath import mp, fsum sage: mp.dps = 15; mp.pretty = False @@ -859,7 +857,7 @@ cdef class Context: def fdot(ctx, A, B=None, bint conjugate=False): r""" - Compute the dot product of the iterables `A` and `B`, + Compute the dot product of the iterables `A` and `B`. .. MATH:: @@ -982,7 +980,7 @@ cdef class Context: type of the parameter, and with x converted to the canonical mpmath type. - TESTS :: + TESTS:: sage: from mpmath import mp sage: mp.pretty = True @@ -999,7 +997,6 @@ cdef class Context: sage: (x, type(x).__name__, T) ((2.0 + 3.0j), 'mpc', 'C') sage: mp.pretty = False - """ cdef MPF v cdef bint ismpf, ismpc @@ -1069,7 +1066,7 @@ cdef class Context: sage: mag(0), mag(inf), mag(-inf), mag(nan) (-inf, +inf, +inf, nan) - :: + :: sage: class MyInt(int): ....: pass @@ -1077,7 +1074,6 @@ cdef class Context: ....: pass sage: mag(MyInt(10)) 4 - """ cdef int typ if isinstance(x, (int, Integer)): @@ -1133,7 +1129,7 @@ cdef class Context: Create a high-level mpmath function from base functions working on mpf, mpc and mpi tuple data. - TESTS :: + TESTS:: sage: from mpmath import mp sage: mp.pretty = False @@ -1141,7 +1137,6 @@ cdef class Context: sage: g = mp._wrap_libmp_function(f) sage: g(mp.mpf(2)) mpf('2.0') - """ name = mpf_f.__name__[4:] doc = function_docs.__dict__.get(name, "Computes the %s of x" % doc) @@ -1153,19 +1148,18 @@ cdef class Context: @classmethod def _wrap_specfun(cls, name, f, wrap): """ - Adds the given function as a method to the context object, + Add the given function as a method to the context object, optionally wrapping it to do automatic conversions and allocating a small number of guard bits to suppress typical roundoff error. - TESTS :: + TESTS:: sage: from mpmath import mp sage: mp._wrap_specfun("foo", lambda ctx, x: ctx.prec + x, True) sage: mp.pretty = False; mp.prec = 53 sage: mp.foo(5) # 53 + 10 guard bits + 5 mpf('68.0') - """ doc = function_docs.__dict__.get(name, getattr(f, '__doc__', '')) if wrap: @@ -1199,7 +1193,7 @@ cdef class Context: """ Square root of an mpmath number x, using the Sage mpmath backend. - TESTS :: + TESTS:: sage: from mpmath import mp sage: mp.dps = 15 @@ -1209,7 +1203,6 @@ cdef class Context: (0.0 + 1.4142135623731j) sage: print(mp.sqrt(2+2j)) (1.55377397403004 + 0.643594252905583j) - """ cdef MPopts opts cdef int typx @@ -1245,7 +1238,6 @@ cdef class Context: 7.38905609893065 sage: print(mp.exp(2+2j)) (-3.07493232063936 + 6.71884969742825j) - """ cdef MPopts opts cdef int typx @@ -1277,7 +1269,6 @@ cdef class Context: -0.416146836547142 sage: print(mp.cos(2+2j)) (-1.56562583531574 - 3.29789483631124j) - """ cdef MPopts opts cdef int typx @@ -1314,7 +1305,6 @@ cdef class Context: 0.909297426825682 sage: print(mp.sin(2+2j)) (3.42095486111701 - 1.50930648532362j) - """ cdef MPopts opts cdef int typx @@ -1352,7 +1342,6 @@ cdef class Context: (0.693147180559945 + 3.14159265358979j) sage: print(mp.ln(2+2j)) (1.03972077083992 + 0.785398163397448j) - """ cdef MPopts opts cdef int typx @@ -1403,7 +1392,7 @@ cdef class wrapped_libmp_function: Create a high-level mpmath function from base functions working on mpf, mpc and mpi tuple data. - TESTS :: + TESTS:: sage: from sage.libs.mpmath.ext_main import wrapped_libmp_function sage: from mpmath import mp @@ -1431,7 +1420,7 @@ cdef class wrapped_libmp_function: """ A wrapped mpmath library function performs automatic conversions and uses the default working precision - unless overridden :: + unless overridden:: sage: from mpmath import mp sage: mp.sinh(2) @@ -1491,10 +1480,10 @@ cdef class wrapped_specfun: def __init__(self, name, f): """ - Creates an object holding a wrapped mpmath function + Create an object holding a wrapped mpmath function along with metadata (name and documentation). - TESTS :: + TESTS:: sage: import mpmath sage: from sage.libs.mpmath.ext_main import wrapped_specfun @@ -1510,14 +1499,13 @@ cdef class wrapped_specfun: """ Call wrapped mpmath function. Arguments are automatically converted to mpmath number, and the internal working precision is increased - by a few bits to suppress typical rounding errors :: + by a few bits to suppress typical rounding errors:: sage: from mpmath import mp sage: from sage.libs.mpmath.ext_main import wrapped_specfun sage: f = wrapped_specfun("f", lambda ctx, x: x + ctx.prec) sage: f("1") # 53 + 10 guard bits + 1 mpf('64.0') - """ cdef int origprec args = [global_context.convert(a) for a in args] @@ -1535,7 +1523,7 @@ cdef class mpnumber: def __richcmp__(self, other, int op): """ Comparison of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf, mpc sage: mpf(3) == mpc(3) @@ -1550,14 +1538,13 @@ cdef class mpnumber: Traceback (most recent call last): ... ValueError: cannot compare complex numbers - """ return binop(OP_RICHCMP+op, self, other, global_opts) def __add__(self, other): """ Addition of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf, mpc sage: mpf(3) + mpc(3) @@ -1570,7 +1557,7 @@ cdef class mpnumber: def __sub__(self, other): """ Subtraction of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf, mpc sage: mpf(5) - mpc(3) @@ -1583,7 +1570,7 @@ cdef class mpnumber: def __mul__(self, other): """ Multiplication of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf, mpc sage: mpf(5) * mpc(3) @@ -1596,7 +1583,7 @@ cdef class mpnumber: def __truediv__(self, other): """ Division of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf, mpc sage: mpf(10) / mpc(5) @@ -1609,7 +1596,7 @@ cdef class mpnumber: def __mod__(self, other): """ Remainder of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf sage: mpf(12) % float(7) @@ -1620,7 +1607,7 @@ cdef class mpnumber: def __pow__(self, other, mod): """ Exponentiation of mpmath numbers. Compatible numerical types - are automatically converted to mpmath numbers :: + are automatically converted to mpmath numbers:: sage: from mpmath import mpf, mpc sage: mpf(10) ** mpc(3) @@ -1635,7 +1622,7 @@ cdef class mpnumber: def ae(s, t, rel_eps=None, abs_eps=None): """ Check if two numbers are approximately equal to within the specified - tolerance (see mp.almosteq for documentation) :: + tolerance (see mp.almosteq for documentation):: sage: from mpmath import mpf, mpc sage: mpf(3).ae(mpc(3,1e-10)) @@ -1654,7 +1641,7 @@ cdef class mpf_base(mpnumber): def __hash__(self): """ - Support hashing of derived classes :: + Support hashing of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1666,7 +1653,7 @@ cdef class mpf_base(mpnumber): def __repr__(self): """ - Support repr() of derived classes :: + Support repr() of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1681,7 +1668,7 @@ cdef class mpf_base(mpnumber): def __str__(self): """ - Support str() of derived classes :: + Support str() of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1694,7 +1681,7 @@ cdef class mpf_base(mpnumber): @property def real(self): """ - Support real part of derived classes :: + Support real part of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1707,7 +1694,7 @@ cdef class mpf_base(mpnumber): @property def imag(self): """ - Support imaginary part of derived classes :: + Support imaginary part of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1719,7 +1706,7 @@ cdef class mpf_base(mpnumber): def conjugate(self): """ - Support complex conjugate of derived classes :: + Support complex conjugate of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1732,7 +1719,7 @@ cdef class mpf_base(mpnumber): @property def man(self): """ - Support mantissa extraction of derived classes :: + Support mantissa extraction of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1745,7 +1732,7 @@ cdef class mpf_base(mpnumber): @property def exp(self): """ - Support exponent extraction of derived classes :: + Support exponent extraction of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1758,7 +1745,7 @@ cdef class mpf_base(mpnumber): @property def bc(self): """ - Support bitcount extraction of derived classes :: + Support bitcount extraction of derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1771,7 +1758,7 @@ cdef class mpf_base(mpnumber): # XXX: optimize def __int__(self): """ - Support integer conversion for derived classes :: + Support integer conversion for derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1783,7 +1770,7 @@ cdef class mpf_base(mpnumber): def __float__(self): """ - Support float conversion for derived classes :: + Support float conversion for derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1795,7 +1782,7 @@ cdef class mpf_base(mpnumber): def __complex__(self): """ - Support complex conversion for derived classes :: + Support complex conversion for derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1807,7 +1794,7 @@ cdef class mpf_base(mpnumber): def to_fixed(self, prec): """ - Support conversion to a fixed-point integer for derived classes :: + Support conversion to a fixed-point integer for derived classes:: sage: from mpmath import mpf sage: from sage.libs.mpmath.ext_main import mpf_base @@ -1838,7 +1825,7 @@ cdef class mpf(mpf_base): Create an mpf from a recognized type, optionally rounding to a precision and in a direction different from the default. - TESTS :: + TESTS:: sage: from mpmath import mpf sage: mpf() @@ -1859,7 +1846,6 @@ cdef class mpf(mpf_base): mpf('0.2998046875') sage: mpf("0.3", prec=10, rounding='u') mpf('0.30029296875') - """ cdef MPopts opts opts = global_opts @@ -1872,7 +1858,7 @@ cdef class mpf(mpf_base): def __reduce__(self): """ - Support pickling :: + Support pickling:: sage: from mpmath import mpf sage: loads(dumps(mpf(0.5))) == mpf(0.5) @@ -1882,8 +1868,8 @@ cdef class mpf(mpf_base): def _get_mpf(self): """ - Returns internal representation of self as a tuple - of (sign bit, mantissa, exponent, bitcount) :: + Return internal representation of ``self`` as a tuple + of (sign bit, mantissa, exponent, bitcount):: sage: from mpmath import mp sage: mp.mpf(-3)._mpf_ @@ -1893,7 +1879,7 @@ cdef class mpf(mpf_base): def _set_mpf(self, v): """ - Sets tuple value of self (warning: unsafe) :: + Set tuple value of ``self`` (warning: unsafe):: sage: from mpmath import mp sage: x = mp.mpf(-3) @@ -1907,7 +1893,7 @@ cdef class mpf(mpf_base): def __bool__(self): """ - Returns whether the number is nonzero :: + Return whether the number is nonzero:: sage: from mpmath import mpf sage: bool(mpf(3.5)) @@ -1920,7 +1906,7 @@ cdef class mpf(mpf_base): def __hash__(self): """ Hash values are compatible with builtin Python floats - when the precision is small enough :: + when the precision is small enough:: sage: from mpmath import mpf sage: hash(mpf(2.5)) == hash(float(2.5)) @@ -1933,7 +1919,7 @@ cdef class mpf(mpf_base): @property def real(self): """ - Real part, leaves self unchanged :: + Real part, leaves ``self`` unchanged:: sage: from mpmath import mpf sage: mpf(2.5).real @@ -1944,7 +1930,7 @@ cdef class mpf(mpf_base): @property def imag(self): """ - Imaginary part, equal to zero :: + Imaginary part, equal to zero:: sage: from mpmath import mpf sage: mpf(2.5).imag @@ -1954,7 +1940,7 @@ cdef class mpf(mpf_base): def conjugate(self): """ - Complex conjugate, leaves self unchanged :: + Complex conjugate, leaves ``self`` unchanged:: sage: from mpmath import mpf sage: mpf(2.5).conjugate() @@ -1965,8 +1951,8 @@ cdef class mpf(mpf_base): @property def man(self): """ - Returns the binary mantissa of self. The result is a Sage - integer :: + Return the binary mantissa of ``self``. The result is a Sage + integer:: sage: from mpmath import mpf sage: mpf(-500.5).man @@ -1979,7 +1965,7 @@ cdef class mpf(mpf_base): @property def exp(self): """ - Returns the binary exponent of self :: + Return the binary exponent of ``self``:: sage: from mpmath import mpf sage: mpf(1/64.).exp @@ -1990,7 +1976,7 @@ cdef class mpf(mpf_base): @property def bc(self): """ - Returns the number of bits in the mantissa of self :: + Return the number of bits in the mantissa of ``self``:: sage: from mpmath import mpf sage: mpf(-256).bc @@ -2002,7 +1988,7 @@ cdef class mpf(mpf_base): def to_fixed(self, long prec): """ - Convert to a fixed-point integer of the given precision :: + Convert to a fixed-point integer of the given precision:: sage: from mpmath import mpf sage: mpf(7.25).to_fixed(30) @@ -2019,7 +2005,7 @@ cdef class mpf(mpf_base): def __int__(self): """ - Convert to a Python integer (truncating if necessary) :: + Convert to a Python integer (truncating if necessary):: sage: from mpmath import mpf sage: int(mpf(2.5)) @@ -2032,7 +2018,7 @@ cdef class mpf(mpf_base): def __float__(self): """ - Convert to a double-precision Python float :: + Convert to a double-precision Python float:: sage: from mpmath import mpf sage: float(mpf(2.5)) @@ -2044,7 +2030,7 @@ cdef class mpf(mpf_base): def __getstate__(self): """ - Support pickling :: + Support pickling:: sage: from mpmath import mpf sage: loads(dumps(mpf(3))) == mpf(3) @@ -2054,7 +2040,7 @@ cdef class mpf(mpf_base): def __setstate__(self, val): """ - Support pickling :: + Support pickling:: sage: from mpmath import mpf sage: loads(dumps(mpf(3))) == mpf(3) @@ -2064,11 +2050,10 @@ cdef class mpf(mpf_base): def __cinit__(self): """ - Create a new mpf :: + Create a new mpf:: sage: from mpmath import mpf sage: x = mpf() - """ MPF_init(&self.value) @@ -2077,7 +2062,7 @@ cdef class mpf(mpf_base): def __neg__(s): """ - Negates self, rounded to the current working precision :: + Negate ``self``, rounded to the current working precision:: sage: from mpmath import mpf sage: -mpf(2) @@ -2090,7 +2075,7 @@ cdef class mpf(mpf_base): def __pos__(s): """ - Rounds the number to the current working precision :: + Round the number to the current working precision:: sage: from mpmath import mp, mpf sage: mp.prec = 200 @@ -2110,8 +2095,8 @@ cdef class mpf(mpf_base): def __abs__(s): """ - Computes the absolute value, rounded to the current - working precision :: + Compute the absolute value, rounded to the current + working precision:: sage: from mpmath import mpf sage: abs(mpf(-2)) @@ -2124,8 +2109,8 @@ cdef class mpf(mpf_base): def sqrt(s): """ - Computes the square root, rounded to the current - working precision :: + Compute the square root, rounded to the current + working precision:: sage: from mpmath import mpf sage: mpf(2).sqrt() @@ -2140,7 +2125,7 @@ cdef class mpf(mpf_base): def __richcmp__(self, other, int op): """ - Compares numbers :: + Compare numbers:: sage: from mpmath import mpf sage: mpf(3) > 2 @@ -2155,7 +2140,7 @@ cdef class mpf(mpf_base): cdef class constant(mpf_base): """ - Represents a mathematical constant with dynamic precision. + Represent a mathematical constant with dynamic precision. When printed or used in an arithmetic operation, a constant is converted to a regular mpf at the working precision. A regular mpf can also be obtained using the operation +x. @@ -2165,8 +2150,8 @@ cdef class constant(mpf_base): def __init__(self, func, name, docname=''): """ - Creates a constant from a function computing an mpf - tuple value :: + Create a constant from a function computing an mpf + tuple value:: sage: from mpmath import mp, mpf sage: q = mp.constant(lambda prec, rnd: mpf(0.25)._mpf_, "quarter", "q") @@ -2174,7 +2159,6 @@ cdef class constant(mpf_base): sage: q + 1 mpf('1.25') - """ self.name = name self.func = func @@ -2183,14 +2167,13 @@ cdef class constant(mpf_base): def __call__(self, prec=None, dps=None, rounding=None): """ Calling a constant is equivalent to rounding it. A - custom precision and rounding direction can also be passed :: + custom precision and rounding direction can also be passed:: sage: from mpmath import pi sage: print(pi(dps=5, rounding='d')) 3.1415901184082 sage: print(pi(dps=5, rounding='u')) 3.14159393310547 - """ prec2 = global_opts.prec rounding2 = rndmode_to_python(global_opts.rounding) @@ -2202,8 +2185,8 @@ cdef class constant(mpf_base): @property def _mpf_(self): """ - Returns the tuple value of the constant as if rounded - to an mpf at the present working precision :: + Return the tuple value of the constant as if rounded + to an mpf at the present working precision:: sage: from mpmath import pi sage: pi._mpf_ @@ -2217,8 +2200,8 @@ cdef class constant(mpf_base): def __repr__(self): """ - Represents self as a string. With mp.pretty=False, the - representation differs from that of an ordinary mpf :: + Represent ``self`` as a string. With mp.pretty=False, the + representation differs from that of an ordinary mpf:: sage: from mpmath import mp, pi sage: mp.pretty = True @@ -2227,7 +2210,6 @@ cdef class constant(mpf_base): sage: mp.pretty = False sage: repr(pi) '' - """ if global_context.pretty: return str(self) @@ -2235,7 +2217,7 @@ cdef class constant(mpf_base): def __bool__(self): """ - Returns whether the constant is nonzero :: + Return whether the constant is nonzero:: sage: from mpmath import pi sage: bool(pi) @@ -2245,7 +2227,7 @@ cdef class constant(mpf_base): def __neg__(self): """ - Negates the constant :: + Negate the constant:: sage: from mpmath import pi sage: -pi @@ -2255,7 +2237,7 @@ cdef class constant(mpf_base): def __pos__(self): """ - Instantiates the constant as an mpf :: + Instantiate the constant as an mpf:: sage: from mpmath import pi sage: +pi @@ -2265,7 +2247,7 @@ cdef class constant(mpf_base): def __abs__(self): """ - Computes the absolute value of the constant :: + Compute the absolute value of the constant:: sage: from mpmath import pi sage: abs(pi) @@ -2275,7 +2257,7 @@ cdef class constant(mpf_base): def sqrt(self): """ - Computes the square root of the constant :: + Compute the square root of the constant:: sage: from mpmath import pi sage: print(pi.sqrt()) @@ -2286,7 +2268,7 @@ cdef class constant(mpf_base): # XXX: optimize def to_fixed(self, prec): """ - Convert to a fixed-point integer :: + Convert to a fixed-point integer:: sage: from mpmath import pi sage: float(pi.to_fixed(10) / 2.0**10) @@ -2303,7 +2285,7 @@ cdef class constant(mpf_base): # WHY is this method not inherited from the base class by Cython? def __hash__(self): """ - A constant hashes as if instantiated to a number :: + A constant hashes as if instantiated to a number:: sage: from mpmath import pi sage: hash(pi) == hash(+pi) @@ -2313,7 +2295,7 @@ cdef class constant(mpf_base): def __richcmp__(self, other, int op): """ - A constant hashes as if instantiated to a number :: + A constant hashes as if instantiated to a number:: sage: from mpmath import pi sage: pi == pi @@ -2338,12 +2320,11 @@ cdef class mpc(mpnumber): def __init__(self, real=0, imag=0): """ - Creates a new mpc:: + Create a new mpc:: sage: from mpmath import mpc sage: mpc() == mpc(0,0) == mpc(1,0)-1 == 0 True - """ cdef int typx, typy typx = MPF_set_any(&self.re, &self.im, real, global_opts, 1) @@ -2356,11 +2337,10 @@ cdef class mpc(mpnumber): def __cinit__(self): """ - Create a new mpc :: + Create a new mpc:: sage: from mpmath import mpc sage: x = mpc() - """ MPF_init(&self.re) MPF_init(&self.im) @@ -2371,7 +2351,7 @@ cdef class mpc(mpnumber): def __reduce__(self): """ - Support pickling :: + Support pickling:: sage: from mpmath import mpc sage: loads(dumps(mpc(1,3))) == mpc(1,3) @@ -2381,7 +2361,7 @@ cdef class mpc(mpnumber): def __setstate__(self, val): """ - Support pickling :: + Support pickling:: sage: from mpmath import mpc sage: loads(dumps(mpc(1,3))) == mpc(1,3) @@ -2391,7 +2371,7 @@ cdef class mpc(mpnumber): def __repr__(self): """ - TESTS :: + TESTS:: sage: from mpmath import mp sage: mp.pretty = True @@ -2409,7 +2389,7 @@ cdef class mpc(mpnumber): def __str__(s): """ - TESTS :: + TESTS:: sage: from mpmath import mp sage: str(mp.mpc(2,3)) @@ -2419,7 +2399,7 @@ cdef class mpc(mpnumber): def __bool__(self): """ - TESTS :: + TESTS:: sage: from mpmath import mp sage: bool(mp.mpc(0,1)) @@ -2437,7 +2417,7 @@ cdef class mpc(mpnumber): def __complex__(self): """ - TESTS :: + TESTS:: sage: from mpmath import mp sage: complex(mp.mpc(1,2)) == complex(1,2) @@ -2447,7 +2427,7 @@ cdef class mpc(mpnumber): def _get_mpc(self): """ - Returns tuple value of self :: + Return tuple value of ``self``:: sage: from mpmath import mp sage: mp.mpc(2,3)._mpc_ @@ -2457,7 +2437,7 @@ cdef class mpc(mpnumber): def _set_mpc(self, tuple v): """ - Sets tuple value of self (warning: unsafe) :: + Set tuple value of ``self`` (warning: unsafe):: sage: from mpmath import mp sage: x = mp.mpc(2,3) @@ -2473,7 +2453,7 @@ cdef class mpc(mpnumber): @property def real(self): """ - Returns the real part of self as an mpf :: + Return the real part of ``self`` as an mpf:: sage: from mpmath import mp sage: mp.mpc(1,2).real @@ -2486,7 +2466,7 @@ cdef class mpc(mpnumber): @property def imag(self): """ - Returns the imaginary part of self as an mpf :: + Return the imaginary part of ``self`` as an mpf:: sage: from mpmath import mp sage: mp.mpc(1,2).imag @@ -2498,7 +2478,7 @@ cdef class mpc(mpnumber): def __hash__(self): """ - Returns the hash value of self :: + Return the hash value of ``self``:: EXAMPLES:: @@ -2518,7 +2498,7 @@ cdef class mpc(mpnumber): def __neg__(s): """ - Negates the number :: + Negate the number:: sage: from mpmath import mpc sage: -mpc(1,2) @@ -2533,7 +2513,7 @@ cdef class mpc(mpnumber): def conjugate(s): """ - Returns the complex conjugate :: + Return the complex conjugate:: sage: from mpmath import mpc sage: mpc(1,2).conjugate() @@ -2548,7 +2528,7 @@ cdef class mpc(mpnumber): def __pos__(s): """ - Rounds the number to the current working precision :: + Round the number to the current working precision:: sage: from mpmath import mp sage: mp.prec = 200 @@ -2570,7 +2550,7 @@ cdef class mpc(mpnumber): def __abs__(s): """ - Returns the absolute value of self :: + Return the absolute value of ``self``:: sage: from mpmath import mpc sage: abs(mpc(3,4)) @@ -2582,7 +2562,7 @@ cdef class mpc(mpnumber): def __richcmp__(self, other, int op): """ - Complex numbers can be compared for equality :: + Complex numbers can be compared for equality:: sage: from mpmath import mpc sage: mpc(2,3) == complex(2,3) diff --git a/src/sage/libs/mpmath/utils.pyx b/src/sage/libs/mpmath/utils.pyx index b7a4f532823..0123d4190be 100644 --- a/src/sage/libs/mpmath/utils.pyx +++ b/src/sage/libs/mpmath/utils.pyx @@ -35,7 +35,6 @@ cpdef int bitcount(n) noexcept: 2 sage: bitcount(2L) 2 - """ cdef Integer m if isinstance(n, Integer): @@ -64,7 +63,6 @@ cpdef isqrt(n): 3 sage: isqrt(10L) 3 - """ cdef Integer m, y if isinstance(n, Integer): @@ -317,7 +315,6 @@ def sage_to_mpmath(x, prec): (mpf('0.5'), mpf('1.5')) sage: a.sage_to_mpmath({'n':0.5}, 53) {'n': mpf('0.5')} - """ cdef RealNumber y if isinstance(x, Element): @@ -421,7 +418,6 @@ def call(func, *args, **kwargs): sage: a.call(a.log, -1.0r, parent=float) 3.141592653589793j - """ from mpmath import mp orig = mp.prec diff --git a/src/sage/libs/ntl/conversion.pxd b/src/sage/libs/ntl/conversion.pxd index 81801682d51..8988399d2b2 100644 --- a/src/sage/libs/ntl/conversion.pxd +++ b/src/sage/libs/ntl/conversion.pxd @@ -41,8 +41,8 @@ cdef inline void set_ntl_matrix_modn_dense_float(mat_ZZ_p_c& A, ntl_ZZ_pContext_ INPUT: - - A -- NTL matrix - - m -- Sage matrix + - ``A`` -- NTL matrix + - ``m`` -- Sage matrix """ cdef size_t i, j cdef ntl_ZZ_p tmp @@ -58,8 +58,8 @@ cdef inline void set_ntl_matrix_modn_dense_double(mat_ZZ_p_c& A, ntl_ZZ_pContext INPUT: - - A -- NTL matrix - - m -- Sage matrix + - ``A`` -- NTL matrix + - ``m`` -- Sage matrix """ cdef size_t i, j cdef ntl_ZZ_p tmp @@ -75,8 +75,8 @@ cdef inline void set_ntl_matrix_modn_generic_dense(mat_ZZ_p_c& A, ntl_ZZ_pContex INPUT: - - A -- NTL matrix - - m -- Sage matrix + - ``A`` -- NTL matrix + - ``m`` -- Sage matrix """ cdef size_t i, j cdef ntl_ZZ_p tmp @@ -92,8 +92,8 @@ cdef inline void set_ntl_matrix_modn_dense(mat_ZZ_p_c& A, ntl_ZZ_pContext_class INPUT: - - A -- NTL matrix - - m -- Sage matrix + - ``A`` -- NTL matrix + - ``m`` -- Sage matrix """ if isinstance(m, Matrix_modn_dense_float): set_ntl_matrix_modn_dense_float(A, c, m) diff --git a/src/sage/libs/ntl/misc.pxi b/src/sage/libs/ntl/misc.pxi index e9dcd9807b0..1724dccf1ea 100644 --- a/src/sage/libs/ntl/misc.pxi +++ b/src/sage/libs/ntl/misc.pxi @@ -10,7 +10,7 @@ cdef extern from *: cdef object string(char* s): """ - Takes a char* allocated using malloc, and converts it to a Python + Take a char* allocated using malloc, and converts it to a Python string, then deletes the allocated memory. Also unsets the signal handler, so you *must* call sig_on() right before calling this! """ @@ -22,7 +22,7 @@ cdef object string(char* s): cdef object string_delete(char* s): """ - Takes a char* allocated using C++ new, and converts it to a Python + Take a char* allocated using C++ new, and converts it to a Python string, then deletes the allocated memory. Also unsets the signal handler, so you *must* call sig_on() right before calling this! """ diff --git a/src/sage/libs/ntl/ntl_GF2.pyx b/src/sage/libs/ntl/ntl_GF2.pyx index 9d4d8a0b5e4..ab45f95dae3 100644 --- a/src/sage/libs/ntl/ntl_GF2.pyx +++ b/src/sage/libs/ntl/ntl_GF2.pyx @@ -41,7 +41,7 @@ cdef class ntl_GF2(): """ def __init__(self, v=None): r""" - Initializes a NTL bit. + Initialize a NTL bit. EXAMPLES:: @@ -61,7 +61,7 @@ cdef class ntl_GF2(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -72,7 +72,7 @@ cdef class ntl_GF2(): def __reduce__(self): """ - Serializes self. + Serialize ``self``. EXAMPLES:: @@ -84,7 +84,7 @@ cdef class ntl_GF2(): def __richcmp__(ntl_GF2 self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -237,7 +237,7 @@ cdef class ntl_GF2(): def __int__(self): """ - Return self as an int. + Return ``self`` as an int. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_GF2E.pyx b/src/sage/libs/ntl/ntl_GF2E.pyx index b50a1233137..f0a576bd693 100644 --- a/src/sage/libs/ntl/ntl_GF2E.pyx +++ b/src/sage/libs/ntl/ntl_GF2E.pyx @@ -50,7 +50,7 @@ from sage.misc.randstate cimport current_randstate def ntl_GF2E_random(ntl_GF2EContext_class ctx): """ - Returns a random element from GF2E modulo the current modulus. + Return a random element from GF2E modulo the current modulus. INPUT: @@ -84,19 +84,19 @@ cdef class ntl_GF2E(): def __init__(self, x=None, modulus=None): """ - Constructs a new finite field element in GF(2**x). + Construct a new finite field element in GF(2**x). If you pass a string to the constructor please note that byte sequences and the hexadecimal notation are Little Endian in NTL. So e.g. '[0 1]' == '0x2' == x. INPUT: - x -- value to be assigned to this element. Same types as - ntl.GF2X() are accepted. - modulus -- the context/modulus of the field - OUTPUT: - a new ntl.GF2E element + - ``x`` -- value to be assigned to this element. Same types as + ``ntl.GF2X()`` are accepted. + - ``modulus`` -- the context/modulus of the field + + OUTPUT: a new ``ntl.GF2E`` element EXAMPLES:: @@ -176,7 +176,7 @@ cdef class ntl_GF2E(): def modulus_context(self): """ - Returns the structure that holds the underlying NTL GF2E modulus. + Return the structure that holds the underlying NTL GF2E modulus. EXAMPLES:: @@ -191,7 +191,7 @@ cdef class ntl_GF2E(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -204,7 +204,7 @@ cdef class ntl_GF2E(): def __copy__(self): """ - Return a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -319,7 +319,7 @@ cdef class ntl_GF2E(): def __richcmp__(ntl_GF2E self, other, int op): r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -350,7 +350,7 @@ cdef class ntl_GF2E(): def IsZero(ntl_GF2E self): """ - Returns True if this element equals zero, False otherwise. + Return ``True`` if this element equals zero, ``False`` otherwise. EXAMPLES:: @@ -365,7 +365,7 @@ cdef class ntl_GF2E(): def IsOne(ntl_GF2E self): """ - Returns True if this element equals one, False otherwise. + Return ``True`` if this element equals one, ``False`` otherwise. EXAMPLES:: @@ -380,7 +380,7 @@ cdef class ntl_GF2E(): def trace(ntl_GF2E self): """ - Returns the trace of this element. + Return the trace of this element. EXAMPLES:: @@ -397,7 +397,7 @@ cdef class ntl_GF2E(): def rep(ntl_GF2E self): """ - Returns a ntl.GF2X copy of this element. + Return a ntl.GF2X copy of this element. EXAMPLES:: @@ -414,7 +414,7 @@ cdef class ntl_GF2E(): def list(ntl_GF2E self): """ - Represents this element as a list of binary digits. + Represent this element as a list of binary digits. EXAMPLES:: @@ -425,9 +425,8 @@ cdef class ntl_GF2E(): sage: e.list() [1, 1, 1, 1, 1, 1, 1, 1] - OUTPUT: - a list of digits representing the coefficients in this element's - polynomial representation + OUTPUT: list of digits representing the coefficients in this element's + polynomial representation """ cdef int i cdef GF2X_c x = GF2E_rep(self.x) @@ -451,11 +450,9 @@ cdef class ntl_GF2E(): INPUT: - - `k` -- (optional) a field `\GF{2^d}` - - OUTPUT: + - ``k`` -- (optional) a field `\GF{2^d}` - :class:`FiniteFieldElement` over `k` + OUTPUT: :class:`FiniteFieldElement` over `k` EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_GF2EContext.pyx b/src/sage/libs/ntl/ntl_GF2EContext.pyx index eef625bb03e..03c02253eb7 100644 --- a/src/sage/libs/ntl/ntl_GF2EContext.pyx +++ b/src/sage/libs/ntl/ntl_GF2EContext.pyx @@ -68,7 +68,7 @@ cdef class ntl_GF2EContext_class(): def __repr__(self): """ - Returns a print representation of self. + Return a print representation of ``self``. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_GF2EX.pyx b/src/sage/libs/ntl/ntl_GF2EX.pyx index 0b7beb873df..152d8885f72 100644 --- a/src/sage/libs/ntl/ntl_GF2EX.pyx +++ b/src/sage/libs/ntl/ntl_GF2EX.pyx @@ -119,7 +119,7 @@ cdef class ntl_GF2EX(): def __richcmp__(ntl_GF2EX self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -148,7 +148,7 @@ cdef class ntl_GF2EX(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_GF2X.pyx b/src/sage/libs/ntl/ntl_GF2X.pyx index 5e6ef736763..7f790b540e0 100644 --- a/src/sage/libs/ntl/ntl_GF2X.pyx +++ b/src/sage/libs/ntl/ntl_GF2X.pyx @@ -55,7 +55,7 @@ def GF2XHexOutput(have_hex=None): INPUT: - - have_hex -- if True hex representation will be used + - ``have_hex`` -- if ``True`` hex representation will be used EXAMPLES:: @@ -91,7 +91,7 @@ cdef class ntl_GF2X(): """ def __init__(self, x=[]): """ - Constructs a new polynomial over GF(2). + Construct a new polynomial over GF(2). A value may be passed to this constructor. If you pass a string to the constructor please note that byte sequences and the hexadecimal @@ -102,10 +102,10 @@ cdef class ntl_GF2X(): extension fields over GF(2) (uses modulus). INPUT: - x -- value to be assigned to this element. See examples. - OUTPUT: - a new ntl.GF2X element + - ``x`` -- value to be assigned to this element. See examples. + + OUTPUT: a new ntl.GF2X element EXAMPLES:: @@ -180,7 +180,7 @@ cdef class ntl_GF2X(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -339,7 +339,7 @@ cdef class ntl_GF2X(): def __richcmp__(ntl_GF2X self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -365,11 +365,12 @@ cdef class ntl_GF2X(): def __lshift__(ntl_GF2X self, int i): """ - Return left shift of self by i bits ( == multiplication by + Return left shift of ``self`` by i bits ( == multiplication by `X^i`). INPUT: - i -- offset/power of X + + - ``i`` -- offset/power of X EXAMPLES:: @@ -384,11 +385,12 @@ cdef class ntl_GF2X(): def __rshift__(ntl_GF2X self, int offset): """ - Return right shift of self by i bits ( == floor division by + Return right shift of ``self`` by i bits ( == floor division by `X^i`). INPUT: - i -- offset/power of X + + - ``i`` -- offset/power of X EXAMPLES:: @@ -403,10 +405,11 @@ cdef class ntl_GF2X(): def GCD(ntl_GF2X self, other): """ - Return GCD of self and other. + Return GCD of ``self`` and ``other``. INPUT: - other -- ntl.GF2X + + - ``other`` -- ntl.GF2X EXAMPLES:: @@ -425,12 +428,13 @@ cdef class ntl_GF2X(): def XGCD(ntl_GF2X self, other): """ - Return the extended gcd of self and other, i.e., elements r, s, t such that + Return the extended gcd of ``self`` and ``other``, i.e., elements r, s, t such that. r = s * self + t * other. INPUT: - other -- ntl.GF2X + + - ``other`` -- ntl.GF2X EXAMPLES:: @@ -439,7 +443,6 @@ cdef class ntl_GF2X(): sage: r,s,t = a.XGCD(b) sage: r == a*s + t*b True - """ cdef ntl_GF2X r = ntl_GF2X.__new__(ntl_GF2X) cdef ntl_GF2X s = ntl_GF2X.__new__(ntl_GF2X) @@ -453,7 +456,7 @@ cdef class ntl_GF2X(): def deg(ntl_GF2X self): """ - Returns the degree of this polynomial + Return the degree of this polynomial. EXAMPLES:: @@ -464,7 +467,7 @@ cdef class ntl_GF2X(): def list(ntl_GF2X self): """ - Represents this element as a list of binary digits. + Represent this element as a list of binary digits. EXAMPLES:: @@ -475,15 +478,14 @@ cdef class ntl_GF2X(): sage: e.list() [1, 1, 1, 1, 1, 1, 1, 1] - OUTPUT: - a list of digits representing the coefficients in this element's - polynomial representation + OUTPUT: list of digits representing the coefficients in this element's + polynomial representation """ return [self[i] for i in range(GF2X_deg(self.x)+1)] def bin(ntl_GF2X self): r""" - Returns binary representation of this element. + Return binary representation of this element. It is the same as setting \code{ntl.GF2XHexOutput(False)} and representing this element afterwards. However it should be @@ -513,9 +515,7 @@ cdef class ntl_GF2X(): representing this element afterwards. However it should be faster and preserves the HexOutput state as opposed to the above code. - OUTPUT: - - string representing this element in hexadecimal + OUTPUT: string representing this element in hexadecimal EXAMPLES:: @@ -541,12 +541,10 @@ cdef class ntl_GF2X(): INPUT: - - self -- GF2X element - - R -- PolynomialRing over GF(2) - - OUTPUT: + - ``self`` -- GF2X element + - ``R`` -- PolynomialRing over GF(2) - polynomial in R + OUTPUT: polynomial in R EXAMPLES:: @@ -569,7 +567,7 @@ cdef class ntl_GF2X(): INPUT: - - i -- degree of X + - ``i`` -- degree of X EXAMPLES:: @@ -599,9 +597,9 @@ cdef class ntl_GF2X(): def LeadCoeff(self): """ - Return the leading coefficient of self. + Return the leading coefficient of ``self``. - This is always 1 except when self == 0. + This is always 1 except when ``self == 0``. EXAMPLES:: @@ -618,7 +616,7 @@ cdef class ntl_GF2X(): def ConstTerm(self): """ - Return the constant term of self. + Return the constant term of ``self``. EXAMPLES:: @@ -635,7 +633,7 @@ cdef class ntl_GF2X(): def SetCoeff(self, int i, a): """ - Set the value of a coefficient of self. + Set the value of a coefficient of ``self``. EXAMPLES:: @@ -664,7 +662,7 @@ cdef class ntl_GF2X(): def diff(self): """ - Differentiate self. + Differentiate ``self``. EXAMPLES:: @@ -683,7 +681,7 @@ cdef class ntl_GF2X(): INPUT: - - hi -- bit position until which reverse is requested + - ``hi`` -- bit position until which reverse is requested EXAMPLES:: @@ -699,7 +697,7 @@ cdef class ntl_GF2X(): def weight(self): """ - Return the number of nonzero coefficients in self. + Return the number of nonzero coefficients in ``self``. EXAMPLES:: @@ -751,7 +749,7 @@ cdef class ntl_GF2X(): def NumBytes(self): """ - Return the number of bytes of self, i.e., floor((NumBits(self)+7)/8) + Return the number of bytes of ``self``, i.e., floor((NumBits(self)+7)/8). EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_GF2X_linkage.pxi b/src/sage/libs/ntl/ntl_GF2X_linkage.pxi index 8f5edce14c1..7d7af70f36f 100644 --- a/src/sage/libs/ntl/ntl_GF2X_linkage.pxi +++ b/src/sage/libs/ntl/ntl_GF2X_linkage.pxi @@ -348,7 +348,6 @@ cdef inline int celement_pow(GF2X_c* res, GF2X_c* x, long e, GF2X_c *modulus, lo x sage: pow(x^2+1, 2, x^2+x+1) x + 1 - """ cdef GF2XModulus_c mod cdef GF2X_c xmod diff --git a/src/sage/libs/ntl/ntl_ZZ.pyx b/src/sage/libs/ntl/ntl_ZZ.pyx index 2821db96243..c424defd38d 100644 --- a/src/sage/libs/ntl/ntl_ZZ.pyx +++ b/src/sage/libs/ntl/ntl_ZZ.pyx @@ -60,7 +60,7 @@ cdef class ntl_ZZ(): # See ntl.pxd for definition of data members def __init__(self, v=None): r""" - Initializes and NTL integer. + Initialize and NTL integer. EXAMPLES:: @@ -100,7 +100,7 @@ cdef class ntl_ZZ(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -120,7 +120,7 @@ cdef class ntl_ZZ(): def __richcmp__(ntl_ZZ self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -253,7 +253,7 @@ cdef class ntl_ZZ(): def __int__(self): """ - Return self as an int. + Return ``self`` as an int. EXAMPLES:: @@ -271,7 +271,7 @@ cdef class ntl_ZZ(): cdef int get_as_int(ntl_ZZ self) noexcept: r""" - Returns value as C int. + Return value as C int. Return value is only valid if the result fits into an int. @@ -298,7 +298,7 @@ cdef class ntl_ZZ(): def _integer_(self, ZZ=None): r""" - Gets the value as a sage int. + Get the value as a sage int. EXAMPLES:: @@ -314,7 +314,7 @@ cdef class ntl_ZZ(): cdef void set_from_int(ntl_ZZ self, int value) noexcept: r""" - Sets the value from a C int. + Set the value from a C int. AUTHOR: David Harvey (2006-08-05) """ @@ -322,7 +322,7 @@ cdef class ntl_ZZ(): def set_from_sage_int(self, Integer value): r""" - Sets the value from a sage int. + Set the value from a sage int. EXAMPLES:: @@ -355,7 +355,7 @@ cdef class ntl_ZZ(): def valuation(self, ntl_ZZ prime): """ Uses code in ``ntlwrap_impl.h`` to compute the number of times - prime divides self. + prime divides ``self``. EXAMPLES:: @@ -383,8 +383,8 @@ cdef class ntl_ZZ(): def val_unit(self, ntl_ZZ prime): """ - Uses code in ``ntlwrap_impl.h`` to compute p-adic valuation and - unit of self. + Uses code in ``ntlwrap_impl.h`` to compute `p`-adic valuation and + unit of ``self``. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_ZZX.pyx b/src/sage/libs/ntl/ntl_ZZX.pyx index 3e23bcd1250..3606aa27997 100644 --- a/src/sage/libs/ntl/ntl_ZZX.pyx +++ b/src/sage/libs/ntl/ntl_ZZX.pyx @@ -152,7 +152,7 @@ cdef class ntl_ZZX(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -167,7 +167,7 @@ cdef class ntl_ZZX(): def __copy__(self): """ - Return a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -202,7 +202,7 @@ cdef class ntl_ZZX(): cdef void setitem_from_int(ntl_ZZX self, long i, int value) noexcept: r""" - Sets ith coefficient to value. + Set `i`-th coefficient to value. AUTHOR: David Harvey (2006-08-05) """ @@ -247,7 +247,7 @@ cdef class ntl_ZZX(): cdef int getitem_as_int(ntl_ZZX self, long i) noexcept: r""" - Returns ith coefficient as C int. + Return `i`-th coefficient as C int. Return value is only valid if the result fits into an int. AUTHOR: David Harvey (2006-08-05) @@ -336,7 +336,7 @@ cdef class ntl_ZZX(): def __truediv__(ntl_ZZX self, ntl_ZZX other): """ - Compute quotient self / other, if the quotient is a polynomial. + Compute quotient ``self / other``, if the quotient is a polynomial. Otherwise an Exception is raised. EXAMPLES:: @@ -394,8 +394,8 @@ cdef class ntl_ZZX(): def quo_rem(self, ntl_ZZX other): """ - Returns the unique integral q and r such that self = q*other + - r, if they exist. Otherwise raises an Exception. + Return the unique integral q and r such that ``self = q*other + + r``, if they exist. Otherwise raises an Exception. EXAMPLES:: @@ -430,7 +430,7 @@ cdef class ntl_ZZX(): def __pow__(ntl_ZZX self, long n, ignored): """ - Return the n-th nonnegative power of self. + Return the `n`-th nonnegative power of ``self``. EXAMPLES:: @@ -455,7 +455,7 @@ cdef class ntl_ZZX(): def __richcmp__(ntl_ZZX self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -482,7 +482,7 @@ cdef class ntl_ZZX(): def is_zero(self): """ - Return True exactly if this polynomial is 0. + Return ``True`` exactly if this polynomial is 0. EXAMPLES:: @@ -499,7 +499,7 @@ cdef class ntl_ZZX(): def is_one(self): """ - Return True exactly if this polynomial is 1. + Return ``True`` exactly if this polynomial is 1. EXAMPLES:: @@ -514,7 +514,7 @@ cdef class ntl_ZZX(): def is_monic(self): """ - Return True exactly if this polynomial is monic. + Return ``True`` exactly if this polynomial is monic. EXAMPLES:: @@ -537,7 +537,7 @@ cdef class ntl_ZZX(): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. EXAMPLES:: @@ -638,7 +638,7 @@ cdef class ntl_ZZX(): def pseudo_quo_rem(self, ntl_ZZX other): r""" - Performs pseudo-division: computes q and r with deg(r) < + Perform pseudo-division: computes q and r with deg(r) < deg(b), and \code{LeadCoeff(b)\^(deg(a)-deg(b)+1) a = b q + r}. Only the classical algorithm is used. @@ -680,7 +680,7 @@ cdef class ntl_ZZX(): def lcm(self, ntl_ZZX other): """ - Return the least common multiple of self and other. + Return the least common multiple of ``self`` and ``other``. EXAMPLES:: @@ -817,7 +817,7 @@ cdef class ntl_ZZX(): def is_x(self): """ - True if this is the polynomial "x". + ``True`` if this is the polynomial "x". EXAMPLES:: @@ -933,8 +933,8 @@ cdef class ntl_ZZX(): def invert_and_truncate(self, long m): """ - Compute and return the inverse of self modulo `x^m`. - The constant term of self must be 1 or -1. + Compute and return the inverse of ``self`` modulo `x^m`. + The constant term of ``self`` must be 1 or -1. EXAMPLES:: @@ -955,8 +955,8 @@ cdef class ntl_ZZX(): def multiply_mod(self, ntl_ZZX other, ntl_ZZX modulus): """ - Return self*other % modulus. The modulus must be monic with - deg(modulus) > 0, and self and other must have smaller degree. + Return ``self*other % modulus``. The modulus must be monic with + deg(modulus) > 0, and ``self`` and ``other`` must have smaller degree. EXAMPLES:: @@ -973,7 +973,7 @@ cdef class ntl_ZZX(): """ Return the trace of this polynomial modulus the modulus. The modulus must be monic, and of positive degree bigger - than the degree of self. + than the degree of ``self``. EXAMPLES:: @@ -997,7 +997,7 @@ cdef class ntl_ZZX(): sage: f.trace_list() [5, 0, -6, 0, 10] - The input polynomial must be monic or a :class:`ValueError` is raised:: + The input polynomial must be monic or a :exc:`ValueError` is raised:: sage: f = ntl.ZZX([1,2,0,3,0,2]) sage: f.trace_list() @@ -1016,7 +1016,7 @@ cdef class ntl_ZZX(): def resultant(self, ntl_ZZX other, proof=None): """ - Return the resultant of self and other. If proof = False (the + Return the resultant of ``self`` and ``other``. If proof = False (the default is proof=None, see proof.polynomial or sage.structure.proof, but the global default is True), then this function may use a randomized strategy that errors with probability no more than @@ -1041,7 +1041,7 @@ cdef class ntl_ZZX(): Return the norm of this polynomial modulo the modulus. The modulus must be monic, and of positive degree strictly - greater than the degree of self. If proof=False (the default + greater than the degree of ``self``. If proof=False (the default is proof=None, see proof.polynomial or sage.structure.proof, but the global default is proof=True) then it may use a randomized strategy that errors with probability no more than @@ -1096,7 +1096,7 @@ cdef class ntl_ZZX(): """ Return the characteristic polynomial of this polynomial modulo the modulus. The modulus must be monic of degree bigger than - self. If proof=False (the default is proof=None, see + ``self``. If proof=False (the default is proof=None, see proof.polynomial or sage.structure.proof, but the global default is proof=True), then this function may use a randomized strategy that errors with probability no more than @@ -1108,7 +1108,6 @@ cdef class ntl_ZZX(): sage: mod = ntl.ZZX([-5,2,0,0,1]) sage: f.charpoly_mod(mod) [-8846 -594 -60 14 1] - """ proof = proof_flag(proof) sig_on() @@ -1118,7 +1117,7 @@ cdef class ntl_ZZX(): """ Return the minimal polynomial of this polynomial modulo the modulus. The modulus must be monic of degree bigger than - self. In all cases, this function may use a randomized + ``self``. In all cases, this function may use a randomized strategy that errors with probability no more than `2^{-80}`. EXAMPLES:: @@ -1176,11 +1175,11 @@ cdef class ntl_ZZX(): def squarefree_decomposition(self): """ - Returns the square-free decomposition of self (a partial + Return the square-free decomposition of ``self`` (a partial factorization into square-free, relatively prime polynomials) as a list of 2-tuples, where the first element in each tuple is a factor, and the second is its exponent. - Assumes that self is primitive. + Assumes that ``self`` is primitive. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_ZZ_p.pyx b/src/sage/libs/ntl/ntl_ZZ_p.pyx index dfa016a7674..3dea1323680 100644 --- a/src/sage/libs/ntl/ntl_ZZ_p.pyx +++ b/src/sage/libs/ntl/ntl_ZZ_p.pyx @@ -92,7 +92,7 @@ cdef class ntl_ZZ_p(): def __init__(self, v=None, modulus=None): r""" - Initializes an NTL integer mod p. + Initialize an NTL integer mod p. EXAMPLES:: @@ -173,7 +173,7 @@ cdef class ntl_ZZ_p(): def modulus_context(self): """ - Return the modulus for self. + Return the modulus for ``self``. EXAMPLES:: @@ -191,7 +191,7 @@ cdef class ntl_ZZ_p(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -203,7 +203,7 @@ cdef class ntl_ZZ_p(): def __richcmp__(ntl_ZZ_p self, other, int op): r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -336,7 +336,7 @@ cdef class ntl_ZZ_p(): def __int__(self): """ - Return self as an int. + Return ``self`` as an int. EXAMPLES:: @@ -350,7 +350,7 @@ cdef class ntl_ZZ_p(): cdef int get_as_int(ntl_ZZ_p self) noexcept: r""" - Returns value as C int. + Return value as C int. Return value is only valid if the result fits into an int. AUTHOR: David Harvey (2006-08-05) @@ -377,7 +377,7 @@ cdef class ntl_ZZ_p(): cdef void set_from_int(ntl_ZZ_p self, int value) noexcept: r""" - Sets the value from a C int. + Set the value from a C int. AUTHOR: David Harvey (2006-08-05) """ @@ -405,7 +405,7 @@ cdef class ntl_ZZ_p(): def lift(self): """ - Return a lift of self as an ntl.ZZ object. + Return a lift of ``self`` as an ntl.ZZ object. EXAMPLES:: @@ -422,7 +422,7 @@ cdef class ntl_ZZ_p(): def modulus(self): r""" - Returns the modulus as an NTL ZZ. + Return the modulus as an NTL ZZ. EXAMPLES:: @@ -466,7 +466,7 @@ cdef class ntl_ZZ_p(): def _integer_(self, ZZ=None): """ - Return a lift of self as a Sage integer. + Return a lift of ``self`` as a Sage integer. EXAMPLES:: @@ -485,7 +485,7 @@ cdef class ntl_ZZ_p(): def _sage_(self): r""" - Returns the value as a sage IntegerModRing. + Return the value as a sage IntegerModRing. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_ZZ_pContext.pyx b/src/sage/libs/ntl/ntl_ZZ_pContext.pyx index 38f211a5ea1..0a4d5b14e68 100644 --- a/src/sage/libs/ntl/ntl_ZZ_pContext.pyx +++ b/src/sage/libs/ntl/ntl_ZZ_pContext.pyx @@ -69,7 +69,7 @@ cdef class ntl_ZZ_pContext_class(): def __repr__(self): """ - Returns a print representation of self. + Return a print representation of ``self``. EXAMPLES:: @@ -164,10 +164,11 @@ cdef class ntl_ZZ_pContext_factory(): cdef ntl_ZZ_pContext_class make_c(self, ntl_ZZ v): """ - Creates a new ZZ_pContext. + Create a new ZZ_pContext. INPUT: - v -- an ntl_ZZ + + - ``v`` -- an ntl_ZZ """ cdef ntl_ZZ_pContext_class context if v in self.context_dict: diff --git a/src/sage/libs/ntl/ntl_ZZ_pE.pyx b/src/sage/libs/ntl/ntl_ZZ_pE.pyx index 5109386a72a..2763c41cb54 100644 --- a/src/sage/libs/ntl/ntl_ZZ_pE.pyx +++ b/src/sage/libs/ntl/ntl_ZZ_pE.pyx @@ -68,7 +68,7 @@ cdef class ntl_ZZ_pE(): def __init__(self, v=None, modulus=None): r""" - Initializes an ntl ZZ_pE. + Initialize an ntl ZZ_pE. EXAMPLES:: @@ -175,7 +175,7 @@ cdef class ntl_ZZ_pE(): def __richcmp__(ntl_ZZ_pE self, other, int op): r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -269,7 +269,7 @@ cdef class ntl_ZZ_pE(): cdef ntl_ZZ_pX get_as_ZZ_pX(ntl_ZZ_pE self): r""" - Returns value as ntl_ZZ_pX. + Return value as ntl_ZZ_pX. """ self.c.restore_c() cdef ntl_ZZ_pX y = ntl_ZZ_pX.__new__(ntl_ZZ_pX) @@ -295,7 +295,7 @@ cdef class ntl_ZZ_pE(): cdef void set_from_ZZ_pX(ntl_ZZ_pE self, ntl_ZZ_pX value) noexcept: r""" - Sets the value from a ZZ_pX. + Set the value from a ZZ_pX. """ self.c.restore_c() self.x = ZZ_pX_to_ZZ_pE(value.x) @@ -320,7 +320,7 @@ cdef class ntl_ZZ_pE(): def modulus(self): r""" - Returns the modulus as an NTL ZZ_pX. + Return the modulus as an NTL ZZ_pX. sage: c=ntl.ZZ_pEContext(ntl.ZZ_pX([1,1,1],11)) sage: n=ntl.ZZ_pE([2983,233],c) diff --git a/src/sage/libs/ntl/ntl_ZZ_pEContext.pyx b/src/sage/libs/ntl/ntl_ZZ_pEContext.pyx index 03ff00f21d4..84f5f55f9ec 100644 --- a/src/sage/libs/ntl/ntl_ZZ_pEContext.pyx +++ b/src/sage/libs/ntl/ntl_ZZ_pEContext.pyx @@ -75,7 +75,7 @@ cdef class ntl_ZZ_pEContext_class(): def __repr__(self): """ - Returns a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -86,7 +86,7 @@ cdef class ntl_ZZ_pEContext_class(): def get_pc(self): """ - Returns the ZZ_pContext contained within self. + Return the ZZ_pContext contained within ``self``. EXAMPLES:: @@ -99,7 +99,7 @@ cdef class ntl_ZZ_pEContext_class(): def polynomial(self): """ - Returns the ZZ_pX polynomial defining self. + Return the ZZ_pX polynomial defining ``self``. EXAMPLES:: @@ -111,7 +111,7 @@ cdef class ntl_ZZ_pEContext_class(): def restore(self): """ - Manually sets the global NTL modulus to be self. + Manually set the global NTL modulus to be ``self``. This should be done automatically by all of the NTL wrapper classes. @@ -124,7 +124,7 @@ cdef class ntl_ZZ_pEContext_class(): cdef void restore_c(self) noexcept: """ - Sets the global NTL modulus to be self. + Set the global NTL modulus to be ``self``. CRUCIAL: If you are writing your own classes that use ZZ_p_c, ZZ_pX_c, ZZ_pE_c, ZZ_pEX_c then you MUST restore the context before calling off to NTL for anything. If the context has been @@ -138,9 +138,9 @@ cdef class ntl_ZZ_pEContext_class(): # from ntl_ZZ_pX import ntl_ZZ_pX # return ntl_ZZ_pX(v,modulus=self) - def ZZ_pE(self,v = None): + def ZZ_pE(self, v = None): """ - Returns a ZZ_pE object with modulus self out of the data v. + Return a ZZ_pE object with modulus ``self`` out of the data v. EXAMPLES:: @@ -153,7 +153,7 @@ cdef class ntl_ZZ_pEContext_class(): def ZZ_pEX(self, v = None): """ - Returns a ZZ_pE object with modulus self out of the data v. + Return a ZZ_pE object with modulus ``self`` out of the data v. EXAMPLES:: @@ -207,7 +207,7 @@ cdef class ntl_ZZ_pEContext_class(): def ntl_ZZ_pEContext( ntl_ZZ_pX f): """ - Creates an ntl_ZZ_pEContext. + Create an ntl_ZZ_pEContext. Such an object must be created before any ZZ_pE or ZZ_pEX objects can be used. diff --git a/src/sage/libs/ntl/ntl_ZZ_pEX.pyx b/src/sage/libs/ntl/ntl_ZZ_pEX.pyx index c12df77c2f0..caeaa26e984 100644 --- a/src/sage/libs/ntl/ntl_ZZ_pEX.pyx +++ b/src/sage/libs/ntl/ntl_ZZ_pEX.pyx @@ -155,7 +155,7 @@ cdef class ntl_ZZ_pEX(): def __repr__(self): """ - Returns a string representation of self. + Return a string representation of ``self``. TESTS:: @@ -171,7 +171,7 @@ cdef class ntl_ZZ_pEX(): def __copy__(self): """ - Return a copy of self. + Return a copy of ``self``. TESTS:: @@ -196,7 +196,7 @@ cdef class ntl_ZZ_pEX(): def get_modulus_context(self): """ - Returns the structure that holds the underlying NTL modulus. + Return the structure that holds the underlying NTL modulus. EXAMPLES:: @@ -211,7 +211,7 @@ cdef class ntl_ZZ_pEX(): def __setitem__(self, long i, a): r""" - Sets the ith coefficient of self to be a. + Set the i-th coefficient of ``self`` to be a. EXAMPLES:: @@ -234,7 +234,7 @@ cdef class ntl_ZZ_pEX(): def __getitem__(self, long i): r""" - Returns the ith coefficient of self. + Return the i-th coefficient of ``self``. EXAMPLES:: @@ -279,7 +279,7 @@ cdef class ntl_ZZ_pEX(): def __add__(ntl_ZZ_pEX self, ntl_ZZ_pEX other): """ - Adds self and other. + Add ``self`` and ``other``. EXAMPLES:: @@ -302,7 +302,7 @@ cdef class ntl_ZZ_pEX(): def __sub__(ntl_ZZ_pEX self, ntl_ZZ_pEX other): """ - Subtracts other from self. + Subtracts ``other`` from ``self``. EXAMPLES:: @@ -325,7 +325,7 @@ cdef class ntl_ZZ_pEX(): def __mul__(ntl_ZZ_pEX self, ntl_ZZ_pEX other): """ - Returns the product self * other. + Return the product ``self * other``. EXAMPLES:: @@ -354,7 +354,7 @@ cdef class ntl_ZZ_pEX(): def __truediv__(ntl_ZZ_pEX self, ntl_ZZ_pEX other): """ - Compute quotient self / other, if the quotient is a polynomial. + Compute quotient ``self / other``, if the quotient is a polynomial. Otherwise an Exception is raised. EXAMPLES:: @@ -390,7 +390,7 @@ cdef class ntl_ZZ_pEX(): function returns r. If p is not prime or the modulus is not irreducible, this - function may raise a :class:`RuntimeError` due to division by + function may raise a :exc:`RuntimeError` due to division by a noninvertible element of ZZ_p. EXAMPLES:: @@ -421,7 +421,7 @@ cdef class ntl_ZZ_pEX(): function returns (q, r). If p is not prime or the modulus is not irreducible, this function may raise a - RuntimeError due to division by a noninvertible element of ZZ_p. + :exc:`RuntimeError` due to division by a noninvertible element of ZZ_p. EXAMPLES:: @@ -467,7 +467,7 @@ cdef class ntl_ZZ_pEX(): def __pow__(ntl_ZZ_pEX self, long n, ignored): """ - Return the n-th nonnegative power of self. + Return the `n`-th nonnegative power of ``self``. EXAMPLES:: @@ -495,7 +495,7 @@ cdef class ntl_ZZ_pEX(): def __richcmp__(ntl_ZZ_pEX self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -527,7 +527,7 @@ cdef class ntl_ZZ_pEX(): def is_zero(self): """ - Return True exactly if this polynomial is 0. + Return ``True`` exactly if this polynomial is 0. EXAMPLES:: @@ -546,7 +546,7 @@ cdef class ntl_ZZ_pEX(): def is_one(self): """ - Return True exactly if this polynomial is 1. + Return ``True`` exactly if this polynomial is 1. EXAMPLES:: @@ -565,7 +565,7 @@ cdef class ntl_ZZ_pEX(): def is_monic(self): """ - Return True exactly if this polynomial is monic. + Return ``True`` exactly if this polynomial is monic. EXAMPLES:: @@ -592,7 +592,7 @@ cdef class ntl_ZZ_pEX(): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. EXAMPLES:: @@ -610,11 +610,11 @@ cdef class ntl_ZZ_pEX(): def convert_to_modulus(self, ntl_ZZ_pContext_class c): """ - Returns a new ntl_ZZ_pX which is the same as self, but considered modulo a different p (but the SAME polynomial). + Return a new ntl_ZZ_pX which is the same as self, but considered modulo a different p (but the SAME polynomial). In order for this to make mathematical sense, c.p should divide self.c.p - (in which case self is reduced modulo c.p) or self.c.p should divide c.p - (in which case self is lifted to something modulo c.p congruent to self modulo self.c.p) + (in which case ``self`` is reduced modulo c.p) or self.c.p should divide c.p + (in which case ``self`` is lifted to something modulo c.p congruent to ``self`` modulo self.c.p) EXAMPLES:: @@ -701,7 +701,7 @@ cdef class ntl_ZZ_pEX(): def gcd(self, ntl_ZZ_pEX other, check=True): """ - Returns gcd(self, other) if we are working over a field. + Return ``gcd(self, other)`` if we are working over a field. NOTE: Does not work if p is not prime or if the modulus is not irreducible. @@ -731,9 +731,9 @@ cdef class ntl_ZZ_pEX(): def xgcd(self, ntl_ZZ_pEX other): """ - Returns r,s,t such that r = s*self + t*other. + Return `r`, `s`, `t` such that ``r = s*self + t*other``. - Here r is the gcd of self and other. + Here `r` is the gcd of ``self`` and ``other``. EXAMPLES:: @@ -833,7 +833,7 @@ cdef class ntl_ZZ_pEX(): def is_x(self): """ - True if this is the polynomial "x". + ``True`` if this is the polynomial "x". EXAMPLES:: @@ -995,8 +995,8 @@ cdef class ntl_ZZ_pEX(): def invert_and_truncate(self, long m): """ - Compute and return the inverse of self modulo `x^m`. - The constant term of self must be invertible. + Compute and return the inverse of ``self`` modulo `x^m`. + The constant term of ``self`` must be invertible. EXAMPLES:: @@ -1022,8 +1022,8 @@ cdef class ntl_ZZ_pEX(): def multiply_mod(self, ntl_ZZ_pEX other, ntl_ZZ_pEX modulus): """ - Return self*other % modulus. The modulus must be monic with - deg(modulus) > 0, and self and other must have smaller degree. + Return ``self*other % modulus``. The modulus must be monic with + ``deg(modulus) > 0``, and ``self`` and ``other`` must have smaller degree. EXAMPLES:: @@ -1047,7 +1047,7 @@ cdef class ntl_ZZ_pEX(): """ Return the trace of this polynomial modulo the modulus. The modulus must be monic, and of positive degree bigger - than the degree of self. + than the degree of ``self``. EXAMPLES:: @@ -1079,7 +1079,7 @@ cdef class ntl_ZZ_pEX(): # sage: f.trace_list() # [5, 0, 14, 0, 10] # - # The input polynomial must be monic or a :class:`ValueError` is raised:: + # The input polynomial must be monic or a :exc:`ValueError` is raised:: # # sage: c=ntl.ZZ_pContext(ntl.ZZ(20)) # sage: f = c.ZZ_pX([1,2,0,3,0,2] @@ -1100,7 +1100,7 @@ cdef class ntl_ZZ_pEX(): def resultant(self, ntl_ZZ_pEX other): """ - Return the resultant of self and other. + Return the resultant of ``self`` and ``other``. EXAMPLES:: @@ -1125,7 +1125,7 @@ cdef class ntl_ZZ_pEX(): """ Return the norm of this polynomial modulo the modulus. The modulus must be monic, and of positive degree strictly greater - than the degree of self. + than the degree of ``self``. EXAMPLES:: @@ -1174,7 +1174,7 @@ cdef class ntl_ZZ_pEX(): """ Return the minimal polynomial of this polynomial modulo the modulus. The modulus must be monic of degree bigger than - self. + ``self``. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_ZZ_pX.pyx b/src/sage/libs/ntl/ntl_ZZ_pX.pyx index a39ee7ee2b5..23a0b0d7373 100644 --- a/src/sage/libs/ntl/ntl_ZZ_pX.pyx +++ b/src/sage/libs/ntl/ntl_ZZ_pX.pyx @@ -158,7 +158,7 @@ cdef class ntl_ZZ_pX(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -173,7 +173,7 @@ cdef class ntl_ZZ_pX(): def __copy__(self): """ - Return a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -193,7 +193,7 @@ cdef class ntl_ZZ_pX(): def get_modulus_context(self): """ - Return the modulus for self. + Return the modulus for ``self``. EXAMPLES:: @@ -224,7 +224,7 @@ cdef class ntl_ZZ_pX(): cdef void setitem_from_int(ntl_ZZ_pX self, long i, int value) noexcept: r""" - Sets ith coefficient to value. + Set `i`-th coefficient to value. AUTHOR: David Harvey (2006-08-05) """ @@ -248,7 +248,7 @@ cdef class ntl_ZZ_pX(): def __getitem__(self, long i): r""" - Returns the ith entry of self. + Return the `i`-th entry of ``self``. EXAMPLES:: @@ -269,7 +269,8 @@ cdef class ntl_ZZ_pX(): cdef int getitem_as_int(ntl_ZZ_pX self, long i) noexcept: r""" - Returns ith coefficient as C int. + Return `i`-th coefficient as C int. + Return value is only valid if the result fits into an int. AUTHOR: David Harvey (2006-08-05) @@ -380,7 +381,7 @@ cdef class ntl_ZZ_pX(): def __truediv__(ntl_ZZ_pX self, ntl_ZZ_pX other): """ - Compute quotient self / other, if the quotient is a polynomial. + Compute quotient ``self / other``, if the quotient is a polynomial. Otherwise an Exception is raised. EXAMPLES:: @@ -417,7 +418,7 @@ cdef class ntl_ZZ_pX(): in ZZ_p[X] such that a = b*q + r, deg(r) < deg(b). This function returns r. - If p is not prime this function may raise a :class:`RuntimeError` + If p is not prime this function may raise a :exc:`RuntimeError` due to division by a noninvertible element of ZZ_p. EXAMPLES:: @@ -448,8 +449,8 @@ cdef class ntl_ZZ_pX(): def quo_rem(self, ntl_ZZ_pX other): """ - Returns the unique integral q and r such that self = q*other + - r, if they exist. Otherwise raises an Exception. + Return the unique integral `q` and `r` such that ``self = q*other + + r``, if they exist. Otherwise raises an Exception. EXAMPLES:: @@ -566,7 +567,7 @@ cdef class ntl_ZZ_pX(): def __richcmp__(ntl_ZZ_pX self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -596,7 +597,7 @@ cdef class ntl_ZZ_pX(): def is_zero(self): """ - Return True exactly if this polynomial is 0. + Return ``True`` exactly if this polynomial is 0. EXAMPLES:: @@ -615,7 +616,7 @@ cdef class ntl_ZZ_pX(): def is_one(self): """ - Return True exactly if this polynomial is 1. + Return ``True`` exactly if this polynomial is 1. EXAMPLES:: @@ -632,7 +633,7 @@ cdef class ntl_ZZ_pX(): def is_monic(self): """ - Return True exactly if this polynomial is monic. + Return ``True`` exactly if this polynomial is monic. EXAMPLES:: @@ -656,7 +657,7 @@ cdef class ntl_ZZ_pX(): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. EXAMPLES:: @@ -724,7 +725,7 @@ cdef class ntl_ZZ_pX(): def _left_pshift(self, ntl_ZZ n): """ - Multiplies all coefficients by n and the context by n. + Multiply all coefficients by `n` and the context by `n`. """ cdef ntl_ZZ new_c_p = ntl_ZZ.__new__(ntl_ZZ) ZZ_mul(new_c_p.x, (self.c.p).x, n.x) @@ -737,7 +738,8 @@ cdef class ntl_ZZ_pX(): def _right_pshift(self, ntl_ZZ n): """ - Divides all coefficients by n and the context by n. Only really makes sense when n divides self.c.p + Divide all coefficients by `n` and the context by `n`. Only really + makes sense when `n` divides ``self.c.p``. """ cdef ntl_ZZ new_c_p = ntl_ZZ.__new__(ntl_ZZ) ZZ_div(new_c_p.x, (self.c.p).x, n.x) @@ -772,7 +774,7 @@ cdef class ntl_ZZ_pX(): def xgcd(self, ntl_ZZ_pX other, plain=True): """ - Returns r,s,t such that r = s*self + t*other. + Return `r`, `s`, `t` such that ``r = s*self + t*other``. Here r is the resultant of a and b; if r != 0, then this function computes s and t such that: a*s + b*t = r; otherwise @@ -895,7 +897,7 @@ cdef class ntl_ZZ_pX(): def is_x(self): """ - True if this is the polynomial "x". + ``True`` if this is the polynomial "x". EXAMPLES:: @@ -915,11 +917,11 @@ cdef class ntl_ZZ_pX(): def convert_to_modulus(self, ntl_ZZ_pContext_class c): """ - Returns a new ntl_ZZ_pX which is the same as self, but considered modulo a different p. + Return a new ntl_ZZ_pX which is the same as self, but considered modulo a different p. In order for this to make mathematical sense, c.p should divide self.c.p - (in which case self is reduced modulo c.p) or self.c.p should divide c.p - (in which case self is lifted to something modulo c.p congruent to self modulo self.c.p) + (in which case ``self`` is reduced modulo c.p) or self.c.p should divide c.p + (in which case ``self`` is lifted to something modulo c.p congruent to ``self`` modulo self.c.p) EXAMPLES:: @@ -963,7 +965,7 @@ cdef class ntl_ZZ_pX(): def factor(self, verbose=False): """ - Return the factorization of self. Assumes self is + Return the factorization of ``self``. Assumes ``self`` is monic. NOTE: The roots are returned in a random order. @@ -1158,9 +1160,9 @@ cdef class ntl_ZZ_pX(): def invert_and_truncate(self, long m): """ - Compute and return the inverse of self modulo `x^m`. + Compute and return the inverse of ``self`` modulo `x^m`. - The constant term of self must be a unit. + The constant term of ``self`` must be a unit. EXAMPLES:: @@ -1182,7 +1184,7 @@ cdef class ntl_ZZ_pX(): def invmod(self, ntl_ZZ_pX modulus): """ - Returns the inverse of self modulo the modulus using NTL's InvMod. + Return the inverse of ``self`` modulo the modulus using NTL's InvMod. """ cdef ntl_ZZ_pX r = self._new() sig_on() @@ -1192,7 +1194,7 @@ cdef class ntl_ZZ_pX(): def invmod_newton(self, ntl_ZZ_pX modulus): """ - Returns the inverse of self modulo the modulus using Newton lifting. + Return the inverse of ``self`` modulo the modulus using Newton lifting. Only works if modulo a power of a prime, and if modulus is either unramified or Eisenstein. """ @@ -1237,8 +1239,8 @@ cdef class ntl_ZZ_pX(): def multiply_mod(self, ntl_ZZ_pX other, ntl_ZZ_pX modulus): """ - Return self*other % modulus. The modulus must be monic with - deg(modulus) > 0, and self and other must have smaller degree. + Return ``self*other % modulus``. The modulus must be monic with + ``deg(modulus) > 0``, and ``self`` and ``other`` must have smaller degree. EXAMPLES:: @@ -1259,7 +1261,7 @@ cdef class ntl_ZZ_pX(): """ Return the trace of this polynomial modulus the modulus. The modulus must be monic, and of positive degree bigger - than the degree of self. + than the degree of ``self``. EXAMPLES:: @@ -1291,7 +1293,7 @@ cdef class ntl_ZZ_pX(): sage: f.trace_list() [5, 0, 14, 0, 10] - The input polynomial must be monic or a :class:`ValueError` is raised:: + The input polynomial must be monic or a :exc:`ValueError` is raised:: sage: c = ntl.ZZ_pContext(20) sage: f = ntl.ZZ_pX([1,2,0,3,0,2],c) @@ -1313,7 +1315,7 @@ cdef class ntl_ZZ_pX(): def resultant(self, ntl_ZZ_pX other): """ - Return the resultant of self and other. + Return the resultant of ``self`` and ``other``. EXAMPLES:: @@ -1335,7 +1337,7 @@ cdef class ntl_ZZ_pX(): """ Return the norm of this polynomial modulo the modulus. The modulus must be monic, and of positive degree strictly greater - than the degree of self. + than the degree of ``self``. EXAMPLES:: @@ -1386,7 +1388,7 @@ cdef class ntl_ZZ_pX(): """ Return the characteristic polynomial of this polynomial modulo the modulus. The modulus must be monic of degree bigger than - self. + ``self``. EXAMPLES:: @@ -1406,7 +1408,7 @@ cdef class ntl_ZZ_pX(): """ Return the minimal polynomial of this polynomial modulo the modulus. The modulus must be monic of degree bigger than - self. + ``self``. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_lzz_p.pyx b/src/sage/libs/ntl/ntl_lzz_p.pyx index 632252e8960..e364e105c68 100644 --- a/src/sage/libs/ntl/ntl_lzz_p.pyx +++ b/src/sage/libs/ntl/ntl_lzz_p.pyx @@ -178,7 +178,7 @@ cdef class ntl_zz_p(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -259,7 +259,7 @@ cdef class ntl_zz_p(): def __pow__(ntl_zz_p self, long n, ignored): """ - Return the n-th nonnegative power of self. + Return the `n`-th nonnegative power of ``self``. EXAMPLES:: @@ -302,7 +302,7 @@ cdef class ntl_zz_p(): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. EXAMPLES:: @@ -318,7 +318,7 @@ cdef class ntl_zz_p(): def __richcmp__(ntl_zz_p self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -349,7 +349,7 @@ cdef class ntl_zz_p(): def __int__(self): """ - Return self as an int. + Return ``self`` as an int. EXAMPLES:: @@ -380,7 +380,7 @@ cdef class ntl_zz_p(): def is_zero(self): """ - Return True exactly if this element is 0. + Return ``True`` exactly if this element is 0. EXAMPLES:: @@ -396,7 +396,7 @@ cdef class ntl_zz_p(): def is_one(self): """ - Return True exactly if this element is 1. + Return ``True`` exactly if this element is 1. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_lzz_pContext.pyx b/src/sage/libs/ntl/ntl_lzz_pContext.pyx index 2c1c941b9e8..9b0065332cf 100644 --- a/src/sage/libs/ntl/ntl_lzz_pContext.pyx +++ b/src/sage/libs/ntl/ntl_lzz_pContext.pyx @@ -70,7 +70,7 @@ cdef class ntl_zz_pContext_class(): def modulus(self): """ - Print the modulus for self. + Print the modulus for ``self``. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_lzz_pX.pyx b/src/sage/libs/ntl/ntl_lzz_pX.pyx index 46537024353..4df5df47a3c 100644 --- a/src/sage/libs/ntl/ntl_lzz_pX.pyx +++ b/src/sage/libs/ntl/ntl_lzz_pX.pyx @@ -177,7 +177,7 @@ cdef class ntl_zz_pX(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -189,7 +189,7 @@ cdef class ntl_zz_pX(): def __getitem__(self, long i): """ - Return the ith coefficient of f. + Return the i-th coefficient of f. EXAMPLES:: @@ -212,7 +212,7 @@ cdef class ntl_zz_pX(): def __setitem__(self, long i, val): """ - Set the ith coefficient of self to val. If + Set the i-th coefficient of ``self`` to val. If i is out of range, raise an exception. EXAMPLES:: @@ -234,7 +234,7 @@ cdef class ntl_zz_pX(): cdef ntl_zz_pX _new(self): """ Quick and dirty method for creating a new object with the - same zz_pContext as self. + same zz_pContext as ``self``. EXAMPLES:: @@ -249,7 +249,7 @@ cdef class ntl_zz_pX(): def __add__(ntl_zz_pX self, other): """ - Return self + other. + Return ``self + other``. EXAMPLES:: @@ -272,7 +272,7 @@ cdef class ntl_zz_pX(): def __sub__(ntl_zz_pX self, other): """ - Return self - other. + Return ``self - other``. EXAMPLES:: @@ -318,7 +318,7 @@ cdef class ntl_zz_pX(): def __truediv__(ntl_zz_pX self, other): """ - Compute quotient self / other, if the quotient is a polynomial. + Compute quotient ``self / other``, if the quotient is a polynomial. Otherwise an Exception is raised. EXAMPLES:: @@ -386,7 +386,7 @@ cdef class ntl_zz_pX(): def __pow__(ntl_zz_pX self, long n, ignored): """ - Return the n-th nonnegative power of self. + Return the `n`-th nonnegative power of ``self``. EXAMPLES:: @@ -405,9 +405,9 @@ cdef class ntl_zz_pX(): def quo_rem(ntl_zz_pX self, ntl_zz_pX right): """ - Returns the quotient and remainder when self is divided by right. + Return the quotient and remainder when ``self`` is divided by ``right``. - Specifically, this return r, q such that `self = q * right + r` + Specifically, this returns `r`, `q` such that ``self = q * right + r``. EXAMPLES:: @@ -432,14 +432,13 @@ cdef class ntl_zz_pX(): def __floordiv__(ntl_zz_pX self, ntl_zz_pX right): """ - Returns the whole part of `self / right`. + Return the whole part of ``self / right``. EXAMPLES:: sage: f = ntl.zz_pX(range(10), 19); g = ntl.zz_pX([1]*5, 19) sage: f // g ## indirect doctest [8, 18, 18, 18, 18, 9] - """ cdef ntl_zz_pX q = self._new() self.c.restore_c() @@ -450,7 +449,7 @@ cdef class ntl_zz_pX(): def __lshift__(ntl_zz_pX self, long n): """ - Shifts this polynomial to the left, which is multiplication by `x^n`. + Shift this polynomial to the left, which is multiplication by `x^n`. EXAMPLES:: @@ -465,7 +464,7 @@ cdef class ntl_zz_pX(): def __rshift__(ntl_zz_pX self, long n): """ - Shifts this polynomial to the right, which is division by `x^n` (and truncation). + Shift this polynomial to the right, which is division by `x^n` (and truncation). EXAMPLES:: @@ -480,7 +479,7 @@ cdef class ntl_zz_pX(): def diff(self): """ - The formal derivative of self. + The formal derivative of ``self``. EXAMPLES:: @@ -495,7 +494,7 @@ cdef class ntl_zz_pX(): def reverse(self): """ - Returns self with coefficients reversed, i.e. `x^n self(x^{-n})`. + Return ``self`` with coefficients reversed, i.e. ``x^n self(x^{-n})``. EXAMPLES:: @@ -510,7 +509,8 @@ cdef class ntl_zz_pX(): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. + EXAMPLES:: sage: f = ntl.zz_pX([2,0,0,1],20) @@ -527,7 +527,7 @@ cdef class ntl_zz_pX(): def __richcmp__(ntl_zz_pX self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -720,8 +720,8 @@ cdef class ntl_zz_pX(): def invert_and_truncate(self, long m): """ - Compute and return the inverse of self modulo `x^m`. - The constant term of self must be 1 or -1. + Compute and return the inverse of ``self`` modulo `x^m`. + The constant term of ``self`` must be 1 or -1. EXAMPLES:: @@ -751,7 +751,7 @@ cdef class ntl_zz_pX(): def is_zero(self): """ - Return True exactly if this polynomial is 0. + Return ``True`` exactly if this polynomial is 0. EXAMPLES:: @@ -769,7 +769,7 @@ cdef class ntl_zz_pX(): def is_one(self): """ - Return True exactly if this polynomial is 1. + Return ``True`` exactly if this polynomial is 1. EXAMPLES:: @@ -785,7 +785,7 @@ cdef class ntl_zz_pX(): def is_monic(self): """ - Return True exactly if this polynomial is monic. + Return ``True`` exactly if this polynomial is monic. EXAMPLES:: @@ -823,14 +823,13 @@ cdef class ntl_zz_pX(): Though f and g are equal, they are not the same objects in memory: sage: f is g False - """ self.c.restore_c() zz_pX_SetX(self.x) def is_x(self): """ - True if this is the polynomial "x". + ``True`` if this is the polynomial "x". EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_mat_GF2.pyx b/src/sage/libs/ntl/ntl_mat_GF2.pyx index 5ffef1c6b31..2eee4fe34f2 100644 --- a/src/sage/libs/ntl/ntl_mat_GF2.pyx +++ b/src/sage/libs/ntl/ntl_mat_GF2.pyx @@ -55,9 +55,9 @@ cdef class ntl_mat_GF2(): INPUT: - - nrows -- number of rows - - ncols -- number of columns - - v -- either a list or a matrix over GF(2^x) + - ``nrows`` -- number of rows + - ``ncols`` -- number of columns + - ``v`` -- either a list or a matrix over GF(2^x) EXAMPLES:: @@ -244,7 +244,7 @@ cdef class ntl_mat_GF2(): def __richcmp__(ntl_mat_GF2 self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -522,7 +522,7 @@ cdef class ntl_mat_GF2(): def IsIdent(self, n = -1): """ - test if this matrix is the n x n identity matrix. + Test if this matrix is the n x n identity matrix. EXAMPLES:: @@ -542,7 +542,7 @@ cdef class ntl_mat_GF2(): def IsDiag(self, long n, ntl_GF2 d): """ - test if X is an n x n diagonal matrix with d on diagonal. + Test if X is an n x n diagonal matrix with d on diagonal. EXAMPLES:: @@ -587,7 +587,7 @@ cdef class ntl_mat_GF2(): def kernel(self): """ - Computes a basis for the kernel of the map x -> x*A. where x + Compute a basis for the kernel of the map x -> x*A. where x is a row vector. EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_mat_GF2E.pyx b/src/sage/libs/ntl/ntl_mat_GF2E.pyx index 720310c9884..795ad9674fa 100644 --- a/src/sage/libs/ntl/ntl_mat_GF2E.pyx +++ b/src/sage/libs/ntl/ntl_mat_GF2E.pyx @@ -51,13 +51,14 @@ cdef class ntl_mat_GF2E(): """ def __init__(self, modulus = None, nrows=0, ncols=0, v=None): """ - Constructs a matrix over ntl.GF2E. + Construct a matrix over ntl.GF2E. INPUT: - modulus -- GF2E context - nrows -- number of rows - ncols -- number of columns - v -- either a list or a matrix over GF(2^x) + + - ``modulus`` -- GF2E context + - ``nrows`` -- number of rows + - ``ncols`` -- number of columns + - ``v`` -- either a list or a matrix over GF(2^x) EXAMPLES:: @@ -153,7 +154,7 @@ cdef class ntl_mat_GF2E(): def modulus_context(self): """ - Returns the structure that holds the underlying NTL GF2E modulus. + Return the structure that holds the underlying NTL GF2E modulus. EXAMPLES:: @@ -182,7 +183,7 @@ cdef class ntl_mat_GF2E(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -306,7 +307,7 @@ cdef class ntl_mat_GF2E(): def __richcmp__(ntl_mat_GF2E self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -335,7 +336,7 @@ cdef class ntl_mat_GF2E(): def NumRows(self): """ - Return the number of rows in self. + Return the number of rows in ``self``. EXAMPLES:: @@ -347,7 +348,7 @@ cdef class ntl_mat_GF2E(): def NumCols(self): """ - Return the number of columns in self. + Return the number of columns in ``self``. EXAMPLES:: @@ -428,7 +429,7 @@ cdef class ntl_mat_GF2E(): def determinant(self): """ - Returns the determinant. + Return the determinant. EXAMPLES:: @@ -474,7 +475,7 @@ cdef class ntl_mat_GF2E(): def list(self): """ - Returns a list of the entries in this matrix + Return a list of the entries in this matrix. EXAMPLES:: @@ -487,13 +488,12 @@ cdef class ntl_mat_GF2E(): True sage: all(a.modulus_context() is ctx for a in l) True - """ return [self[i,j] for i in range(self.NumRows()) for j in range(self.x.NumCols())] def IsZero(self): """ - Return True if self is zero, and false otherwise. + Return ``True`` if ``self`` is zero, and ``False`` otherwise. EXAMPLES:: @@ -513,15 +513,14 @@ cdef class ntl_mat_GF2E(): def _sage_(ntl_mat_GF2E self, k=None): """ - Returns a ``Matrix`` over a ``FiniteField`` representation + Return a ``Matrix`` over a ``FiniteField`` representation of this element. INPUT: - - ``k`` -- optional GF(2**deg) + - ``k`` -- (optional) GF(2**deg) - OUTPUT: - Matrix over k + OUTPUT: Matrix over k EXAMPLES:: @@ -549,10 +548,7 @@ cdef class ntl_mat_GF2E(): def transpose(ntl_mat_GF2E self): """ - Returns the transposed matrix of self. - - OUTPUT: - transposed Matrix + Return the transposed matrix of ``self``. EXAMPLES:: @@ -590,8 +586,8 @@ cdef class ntl_mat_GF2E(): return r def IsIdent(self, n = -1): - """ - test if A is the n x n identity matrix + r""" + Test if `A` is the `n \times n` identity matrix. EXAMPLES:: @@ -645,7 +641,7 @@ cdef class ntl_mat_GF2E(): def kernel(self): """ - Computes a basis for the kernel of the map ``x -> x*A``, where + Compute a basis for the kernel of the map ``x -> x*A``, where ``x`` is a row vector. EXAMPLES:: @@ -669,10 +665,10 @@ cdef class ntl_mat_GF2E(): INPUT: - - ``density`` -- float; proportion (roughly) to be considered for - changes - - ``nonzero`` -- Bool (default: ``False``); whether the new entries - are forced to be non-zero + - ``density`` -- float; proportion (roughly) to be considered for + changes + - ``nonzero`` -- boolean (default: ``False``); whether the new entries + are forced to be nonzero EXAMPLES:: diff --git a/src/sage/libs/ntl/ntl_mat_ZZ.pyx b/src/sage/libs/ntl/ntl_mat_ZZ.pyx index f8411113807..69340c00f31 100644 --- a/src/sage/libs/ntl/ntl_mat_ZZ.pyx +++ b/src/sage/libs/ntl/ntl_mat_ZZ.pyx @@ -129,7 +129,7 @@ cdef class ntl_mat_ZZ(): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -163,7 +163,7 @@ cdef class ntl_mat_ZZ(): def __sub__(ntl_mat_ZZ self, other): """ - Return self - other. + Return ``self - other``. EXAMPLES:: @@ -186,7 +186,7 @@ cdef class ntl_mat_ZZ(): def __add__(ntl_mat_ZZ self, other): """ - Return self + other. + Return ``self + other``. EXAMPLES:: @@ -209,7 +209,7 @@ cdef class ntl_mat_ZZ(): def __richcmp__(ntl_mat_ZZ self, other, int op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -237,7 +237,7 @@ cdef class ntl_mat_ZZ(): def __pow__(ntl_mat_ZZ self, long e, ignored): """ - Return self to the e power. + Return ``self`` to the e power. EXAMPLES:: @@ -269,7 +269,7 @@ cdef class ntl_mat_ZZ(): def nrows(self): """ - Return the number of rows in self. + Return the number of rows in ``self``. EXAMPLES:: @@ -281,7 +281,7 @@ cdef class ntl_mat_ZZ(): def ncols(self): """ - Return the number of columns in self. + Return the number of columns in ``self``. EXAMPLES:: @@ -362,7 +362,7 @@ cdef class ntl_mat_ZZ(): def determinant(self, deterministic=True): """ - Return the determinant of self. + Return the determinant of ``self``. EXAMPLES:: @@ -392,7 +392,7 @@ cdef class ntl_mat_ZZ(): - W is lower triangular, - the diagonal entries are positive, - - any entry below the diagonal is a non-negative number + - any entry below the diagonal is a nonnegative number strictly less than the diagonal entry in its column. This is implemented using the algorithm of [P. Domich, @@ -491,11 +491,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -561,11 +562,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -631,11 +633,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -701,11 +704,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -771,11 +775,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -841,11 +846,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -911,11 +917,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -981,11 +988,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -1051,11 +1059,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -1121,11 +1130,12 @@ cdef class ntl_mat_ZZ(): precision uniformly throughout. INPUT: - U -- optional permutation matrix (see LLL, default: None) - delta -- reduction parameter (default: 0.99) - BlockSize -- see above (default: 10) - prune -- see above (default: 0) - verbose -- print verbose output (default: ``False``) + + - ``U`` -- permutation matrix (see LLL, default: ``None``) + - ``delta`` -- reduction parameter (default: 0.99) + - ``BlockSize`` -- see above (default: 10) + - ``prune`` -- see above (default: 0) + - ``verbose`` -- print verbose output (default: ``False``) EXAMPLES:: @@ -1166,21 +1176,21 @@ cdef class ntl_mat_ZZ(): def LLL(self, a=3, b=4, return_U=False, verbose=False): r""" - Performs LLL reduction of self (puts \code{self} in an LLL form). + Perform LLL reduction of ``self`` (puts \code{self} in an LLL form). \code{self} is an `m x n` matrix, viewed as `m` rows of `n`-vectors. `m` may be less than, equal to, or greater than `n`, - and the rows need not be linearly independent. self is + and the rows need not be linearly independent. ``self`` is transformed into an LLL-reduced basis, and the return value is - the rank r of self so as det2 (see below). The first `m-r` rows - of self are zero. + the rank r of ``self`` so as det2 (see below). The first `m-r` rows + of ``self`` are zero. More specifically, elementary row transformations are - performed on \code{self} so that the non-zero rows of + performed on \code{self} so that the nonzero rows of new-\code{self} form an LLL-reduced basis for the lattice spanned by the rows of old-\code{self}. The default reduction parameter is `\delta=3/4`, which means that the squared length - of the first non-zero basis vector is no more than `2^{r-1}` + of the first nonzero basis vector is no more than `2^{r-1}` times that of the shortest vector in the lattice. det2 is calculated as the \emph{square} of the determinant of @@ -1196,7 +1206,7 @@ cdef class ntl_mat_ZZ(): The parameters a and b allow an arbitrary reduction parameter `\delta=a/b`, where `1/4 < a/b \leq 1`, where a and b are positive integers. For a basis reduced with parameter delta, the - squared length of the first non-zero basis vector is no more + squared length of the first nonzero basis vector is no more than `1/(delta-1/4)^{r-1}` times that of the shortest vector in the lattice. @@ -1205,16 +1215,17 @@ cdef class ntl_mat_ZZ(): Theory, Springer, 1993] INPUT: - a -- parameter a as described above (default: 3) - b -- parameter b as described above (default: 4) - return_U -- return U as described above - verbose -- if True NTL will produce some verbatim messages on - what's going on internally (default: ``False``) + + - ``a`` -- parameter a as described above (default: 3) + - ``b`` -- parameter b as described above (default: 4) + - ``return_U`` -- return U as described above + - ``verbose`` -- if ``True`` NTL will produce some verbatim messages on + what's going on internally (default: ``False``) OUTPUT: - (rank,det2,[U]) where rank,det2, and U are as described - above and U is an optional return value if return_U is - True. + + (rank,det2,[U]) where rank,det2, and U are as described + above and U is an optional return value if return_U is ``True``. EXAMPLES:: @@ -1262,7 +1273,7 @@ cdef class ntl_mat_ZZ(): def LLL_FP(self, delta=0.75 , return_U=False, verbose=False): r""" - Performs approximate LLL reduction of \code{self} (puts + Perform approximate LLL reduction of \code{self} (puts \code{self} in an LLL form) subject to the following conditions: @@ -1294,14 +1305,16 @@ cdef class ntl_mat_ZZ(): status report is also printed every once in a while. INPUT: - delta -- as described above (0.5 <= delta < 1.0) (default: 0.75) - return_U -- return U as described above - verbose -- if True NTL will produce some verbatim messages on - what's going on internally (default: ``False``) + + - ``delta`` -- as described above (0.5 <= delta < 1.0) (default: 0.75) + - ``return_U`` -- return U as described above + - ``verbose`` -- if ``True`` NTL will produce some verbatim messages on + what's going on internally (default: ``False``) OUTPUT: - (rank,[U]) where rank and U are as described above and U - is an optional return value if return_U is True. + + (rank,[U]) where rank and U are as described above and U + is an optional return value if ``return_U`` is ``True``. EXAMPLES:: @@ -1349,7 +1362,7 @@ cdef class ntl_mat_ZZ(): def LLL_QP(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as \code{self.LLL_FP} using the + Perform the same reduction as \code{self.LLL_FP} using the same calling conventions but with quad float precision. EXAMPLES:: @@ -1373,7 +1386,7 @@ cdef class ntl_mat_ZZ(): def LLL_XD(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as \code{self.LLL_FP} using the + Perform the same reduction as \code{self.LLL_FP} using the same calling conventions but with extended exponent double precision. @@ -1398,7 +1411,7 @@ cdef class ntl_mat_ZZ(): def LLL_RR(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as \code{self.LLL_FP} using the + Perform the same reduction as \code{self.LLL_FP} using the same calling conventions but with arbitrary precision floating point numbers. @@ -1429,7 +1442,7 @@ cdef class ntl_mat_ZZ(): def G_LLL_FP(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as self.LLL_FP using the same + Perform the same reduction as self.LLL_FP using the same calling conventions but uses the Givens Orthogonalization. Givens Orthogonalization. This is a bit slower, but generally @@ -1453,7 +1466,7 @@ cdef class ntl_mat_ZZ(): def G_LLL_QP(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as self.G_LLL_FP using the same + Perform the same reduction as self.G_LLL_FP using the same calling conventions but with quad float precision. """ cdef ntl_mat_ZZ U @@ -1471,7 +1484,7 @@ cdef class ntl_mat_ZZ(): def G_LLL_XD(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as self.G_LLL_FP using the same + Perform the same reduction as self.G_LLL_FP using the same calling conventions but with extended exponent double precision. """ @@ -1490,7 +1503,7 @@ cdef class ntl_mat_ZZ(): def G_LLL_RR(self, delta, return_U=False, verbose=False): r""" - Performs the same reduction as self.G_LLL_FP using the same + Perform the same reduction as self.G_LLL_FP using the same calling conventions but with arbitrary precision floating point numbers. """ diff --git a/src/sage/libs/pari/convert_sage.pyx b/src/sage/libs/pari/convert_sage.pyx index a163dbf2b33..64386bcf632 100644 --- a/src/sage/libs/pari/convert_sage.pyx +++ b/src/sage/libs/pari/convert_sage.pyx @@ -60,12 +60,10 @@ cpdef gen_to_sage(Gen z, locals=None): - ``z`` -- PARI ``gen`` - - ``locals`` -- optional dictionary used in fallback cases that + - ``locals`` -- (optional) dictionary used in fallback cases that involve :func:`sage_eval` - OUTPUT: - - One of the following depending on the PARI type of ``z`` + OUTPUT: one of the following depending on the PARI type of ``z`` - a :class:`~sage.rings.integer.Integer` if ``z`` is an integer (type ``t_INT``) @@ -88,7 +86,7 @@ cpdef gen_to_sage(Gen z, locals=None): - a matrix if ``z`` is a matrix (type ``t_MAT``) - - a padic element (type ``t_PADIC``) + - a `p`-adic element (type ``t_PADIC``) - a :class:`~sage.rings.infinity.Infinity` if ``z`` is an infinity (type ``t_INF``) @@ -248,7 +246,7 @@ cpdef gen_to_sage(Gen z, locals=None): sage: a.parent() Full MatrixSpace of 2 by 2 dense matrices over Integer Ring - Conversion of p-adics:: + Conversion of `p`-adics:: sage: # needs sage.rings.padics sage: z = pari('569 + O(7^8)'); z diff --git a/src/sage/libs/pari/tests.py b/src/sage/libs/pari/tests.py index 43018a338d6..1ed571cd4b9 100644 --- a/src/sage/libs/pari/tests.py +++ b/src/sage/libs/pari/tests.py @@ -188,7 +188,7 @@ Reading a gp file:: sage: import tempfile - sage: gpfile = tempfile.NamedTemporaryFile(mode="w") + sage: gpfile = tempfile.NamedTemporaryFile(mode='w') sage: __ = gpfile.file.write("mysquare(n) = {\n") sage: __ = gpfile.file.write(" n^2;\n") sage: __ = gpfile.file.write("}\n") @@ -1195,7 +1195,7 @@ sage: k(2).__pari__().fforder(o=4) 4 -p-adic functions:: +`p`-adic functions:: sage: # needs sage.rings.padics sage: K = Qp(11,5) diff --git a/src/sage/libs/singular/function.pyx b/src/sage/libs/singular/function.pyx index a3b13cac604..b1ca9b511de 100644 --- a/src/sage/libs/singular/function.pyx +++ b/src/sage/libs/singular/function.pyx @@ -56,7 +56,7 @@ TESTS:: AUTHORS: - Michael Brickenstein (2009-07): initial implementation, overall design -- Martin Albrecht (2009-07): clean up, enhancements, etc +- Martin Albrecht (2009-07): clean up, enhancements, etc. - Michael Brickenstein (2009-10): extension to more Singular types - Martin Albrecht (2010-01): clean up, support for attributes - Simon King (2011-04): include the documentation provided by Singular as a code block @@ -358,7 +358,7 @@ cdef free_leftv(leftv *args, ring *r = NULL): INPUT: - - ``args`` -- a list of Singular arguments + - ``args`` -- list of Singular arguments """ args.CleanUp(r) omFreeBin(args, sleftv_bin) @@ -385,7 +385,6 @@ def is_sage_wrapper_for_singular_ring(ring): sage: P = A.g_algebra(relations={y*x:-x*y}, order = 'lex') sage: is_sage_wrapper_for_singular_ring(P) True - """ if isinstance(ring, MPolynomialRing_libsingular): return True @@ -420,7 +419,7 @@ def is_singular_poly_wrapper(p): def all_singular_poly_wrapper(s): """ - Tests for a sequence ``s``, whether it consists of + Test for a sequence ``s``, whether it consists of singular polynomials. EXAMPLES:: @@ -496,7 +495,7 @@ cdef class Converter(SageObject): INPUT: - - ``args`` -- a list of Python objects + - ``args`` -- list of Python objects - ``ring`` -- a multivariate polynomial ring - ``attributes`` -- an optional dictionary of Singular attributes (default: ``None``) @@ -1209,13 +1208,13 @@ cdef class SingularFunction(SageObject): INPUT: - - ``args`` -- a list of arguments + - ``args`` -- list of arguments - ``ring`` -- a multivariate polynomial ring - ``interruptible`` -- if ``True`` pressing :kbd:`Ctrl` + :kbd:`C` during the execution of this function will interrupt the computation (default: ``True``) - - ``attributes`` -- a dictionary of optional Singular + - ``attributes`` -- dictionary of optional Singular attributes assigned to Singular objects (default: ``None``) If ``ring`` is not specified, it is guessed from the given arguments. @@ -1303,7 +1302,7 @@ cdef class SingularFunction(SageObject): if dummy_ring is None: from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.rings.rational_field import QQ - dummy_ring = PolynomialRing(QQ, "dummy", implementation="singular") # seems a reasonable default + dummy_ring = PolynomialRing(QQ, "dummy", implementation='singular') # seems a reasonable default ring = dummy_ring if not (isinstance(ring, MPolynomialRing_libsingular) or isinstance(ring, NCPolynomialRing_plural)): raise TypeError("cannot call Singular function '%s' with ring parameter of type '%s'" % (self._name,type(ring))) @@ -1331,12 +1330,12 @@ accepts the following keyword parameters: INPUT: -- ``args`` -- a list of arguments +- ``args`` -- list of arguments - ``ring`` -- a multivariate polynomial ring - ``interruptible`` -- if ``True`` pressing :kbd:`Ctrl` + :kbd:`C` during the execution of this function will interrupt the computation (default: ``True``) -- ``attributes`` -- a dictionary of optional Singular attributes +- ``attributes`` -- dictionary of optional Singular attributes assigned to Singular objects (default: ``None``) If ``ring`` is not specified, it is guessed from the given arguments. @@ -1381,7 +1380,7 @@ The Singular documentation for '%s' is given below. INPUT: - - ``args`` -- a list of Python objects + - ``args`` -- list of Python objects - ``ring`` -- an optional ring to check """ from sage.matrix.matrix_mpolynomial_dense import Matrix_mpolynomial_dense @@ -1830,7 +1829,7 @@ def list_of_functions(packages=False): INPUT: - - ``packages`` -- include local functions in packages. + - ``packages`` -- include local functions in packages EXAMPLES:: diff --git a/src/sage/libs/singular/groebner_strategy.pyx b/src/sage/libs/singular/groebner_strategy.pyx index f493b5dbbc3..4861527e697 100644 --- a/src/sage/libs/singular/groebner_strategy.pyx +++ b/src/sage/libs/singular/groebner_strategy.pyx @@ -95,7 +95,7 @@ cdef class GroebnerStrategy(SageObject): Check that :issue:`27508` is fixed:: - sage: R2. = PolynomialRing(QQ, 2, order="lex") + sage: R2. = PolynomialRing(QQ, 2, order='lex') sage: I2 = R2.ideal(["x^2 - x", "y^2 - y"]) sage: R2("x^2 + y").mod(I2), R2("x + y^2").mod(I2) (x + y, x + y) @@ -351,7 +351,6 @@ cdef class NCGroebnerStrategy(SageObject): Defining x1, x2, x3, x4, x5, x6 sage: I.reduce(x1*x2*x3 + x2^2*x4) x1*x2*x3 - """ if not isinstance(L, NCPolynomialIdeal): raise TypeError("First parameter must be an ideal in a g-algebra.") @@ -454,7 +453,6 @@ cdef class NCGroebnerStrategy(SageObject): sage: strat = NCGroebnerStrategy(I) sage: strat.ideal() == I True - """ return self._ideal @@ -529,7 +527,6 @@ cdef class NCGroebnerStrategy(SageObject): x*y^2 sage: ST.normal_form(x*y^2) y*z - """ if unlikely(p._parent is not self._parent): raise TypeError("parent(p) must be the same as this object's parent.") diff --git a/src/sage/libs/singular/option.pyx b/src/sage/libs/singular/option.pyx index 5f788301cdb..e729255e2d9 100644 --- a/src/sage/libs/singular/option.pyx +++ b/src/sage/libs/singular/option.pyx @@ -146,7 +146,7 @@ cdef class LibSingularOptions_abstract: """ INPUT: - - ``**kwds`` -- all keyword parameters are immediately applied. + - ``**kwds`` -- all keyword parameters are immediately applied EXAMPLES:: @@ -302,72 +302,72 @@ cdef class LibSingularOptions(LibSingularOptions_abstract): Supported options are: - - ``return_sb`` or ``returnSB`` -- the functions ``syz``, - ``intersect``, ``quotient``, ``modulo`` return a standard - base instead of a generating set if ``return_sb`` - is set. This option should not be used for ``lift``. + - ``return_sb`` or ``returnSB`` -- the functions ``syz``, + ``intersect``, ``quotient``, ``modulo`` return a standard + base instead of a generating set if ``return_sb`` + is set. This option should not be used for ``lift``. - - ``fast_hc`` or ``fastHC`` -- tries to find the highest corner - of the staircase (HC) as fast as possible during a standard - basis computation (only used for local orderings). + - ``fast_hc`` or ``fastHC`` -- tries to find the highest corner + of the staircase (HC) as fast as possible during a standard + basis computation (only used for local orderings). - - ``int_strategy`` or ``intStrategy`` -- avoids division of - coefficients during standard basis computations. This option - is ring dependent. By default, it is set for rings with - characteristic 0 and not set for all other rings. + - ``int_strategy`` or ``intStrategy`` -- avoids division of + coefficients during standard basis computations. This option + is ring dependent. By default, it is set for rings with + characteristic 0 and not set for all other rings. - - ``lazy`` -- uses a more lazy approach in std computations, which - was used in SINGULAR version before 2-0 (and which may lead to - faster or slower computations, depending on the example). + - ``lazy`` -- uses a more lazy approach in std computations, which + was used in SINGULAR version before 2-0 (and which may lead to + faster or slower computations, depending on the example). - - ``length`` -- select shorter reducers in std computations. + - ``length`` -- select shorter reducers in std computations - - ``not_regularity`` or ``notRegularity`` -- disables the - regularity bound for ``res`` and ``mres``. + - ``not_regularity`` or ``notRegularity`` -- disables the + regularity bound for ``res`` and ``mres`` - - ``not_sugar`` or ``notSugar`` -- disables the sugar strategy - during standard basis computation. + - ``not_sugar`` or ``notSugar`` -- disables the sugar strategy + during standard basis computation - - ``not_buckets`` or ``notBuckets`` -- disables the bucket - representation of polynomials during standard basis - computations. This option usually decreases the memory - usage but increases the computation time. It should only - be set for memory-critical standard basis computations. + - ``not_buckets`` or ``notBuckets`` -- disables the bucket + representation of polynomials during standard basis + computations. This option usually decreases the memory + usage but increases the computation time. It should only + be set for memory-critical standard basis computations. - - ``old_std`` or ``oldStd`` -- uses a more lazy approach in std - computations, which was used in SINGULAR version before 2-0 - (and which may lead to faster or slower computations, depending - on the example). + - ``old_std`` or ``oldStd`` -- uses a more lazy approach in std + computations, which was used in SINGULAR version before 2-0 + (and which may lead to faster or slower computations, depending + on the example). - - ``prot`` -- shows protocol information indicating the progress - during the following computations: ``facstd``, ``fglm``, - ``groebner``, ``lres``, ``mres``, ``minres``, ``mstd``, - ``res``, ``slimgb``, ``sres``, ``std``, ``stdfglm``, - ``stdhilb``, ``syz``. + - ``prot`` -- shows protocol information indicating the progress + during the following computations: ``facstd``, ``fglm``, + ``groebner``, ``lres``, ``mres``, ``minres``, ``mstd``, + ``res``, ``slimgb``, ``sres``, ``std``, ``stdfglm``, + ``stdhilb``, ``syz``. - - ``red_sb`` or ``redSB`` -- computes a reduced standard basis in - any standard basis computation. + - ``red_sb`` or ``redSB`` -- computes a reduced standard basis in + any standard basis computation - - ``red_tail`` or ``redTail`` -- reduction of the tails of - polynomials during standard basis computations. This option - is ring dependent. By default, it is set for rings with global - degree orderings and not set for all other rings. + - ``red_tail`` or ``redTail`` -- reduction of the tails of + polynomials during standard basis computations. This option + is ring dependent. By default, it is set for rings with global + degree orderings and not set for all other rings. - - ``red_through`` or ``redThrough`` -- for inhomogeneous input, - polynomial reductions during standard basis computations are - never postponed, but always finished through. This option is - ring dependent. By default, it is set for rings with global - degree orderings and not set for all other rings. + - ``red_through`` or ``redThrough`` -- for inhomogeneous input, + polynomial reductions during standard basis computations are + never postponed, but always finished through. This option is + ring dependent. By default, it is set for rings with global + degree orderings and not set for all other rings. - - ``sugar_crit`` or ``sugarCrit`` -- uses criteria similar to the - homogeneous case to keep more useless pairs. + - ``sugar_crit`` or ``sugarCrit`` -- uses criteria similar to the + homogeneous case to keep more useless pairs - - ``weight_m`` or ``weightM`` -- automatically computes suitable - weights for the weighted ecart and the weighted sugar method. + - ``weight_m`` or ``weightM`` -- automatically computes suitable + weights for the weighted ecart and the weighted sugar method In addition, two integer valued parameters are supported, namely: - - ``deg_bound`` or ``degBound`` -- The standard basis computation + - ``deg_bound`` or ``degBound`` -- the standard basis computation is stopped if the total (weighted) degree exceeds ``deg_bound``. ``deg_bound`` should not be used for a global ordering with inhomogeneous input. Reset this bound by setting ``deg_bound`` @@ -375,7 +375,7 @@ cdef class LibSingularOptions(LibSingularOptions_abstract): and the command: ``slimgb`` uses always the total degree with weights 1, ``std`` does so for block orderings, only. - - ``mult_bound`` or ``multBound`` -- The standard basis computation + - ``mult_bound`` or ``multBound`` -- the standard basis computation is stopped if the ideal is zero-dimensional in a ring with local ordering and its multiplicity is lower than ``mult_bound``. Reset this bound by setting ``mult_bound`` to 0. @@ -408,7 +408,6 @@ cdef class LibSingularOptions(LibSingularOptions_abstract): sage: opt['red_tail'] = True # the previous commands reset opt['red_tail'] to False sage: J.groebner_basis() [x^3*y^2 + y^3*z^2 + x^2*z^3, x^2*y^3 + x^3*z^2 + y^2*z^3, y^5, x^6, x^4*z^2 - y^4*z^2 - x^2*y*z^3 + x*y^2*z^3, z^6, y^4*z^3 - y^3*z^4 - x^2*z^5, x^3*y*z^4 - x^2*y^2*z^4 + x*y^3*z^4, x^3*z^5, x^2*y*z^5 + y^3*z^5, x*y^3*z^5] - """ def __init__(self, **kwds): """ @@ -475,27 +474,27 @@ cdef class LibSingularVerboseOptions(LibSingularOptions_abstract): Supported options are: - - ``mem`` -- shows memory usage in square brackets. - - ``yacc`` -- Only available in debug version. - - ``redefine`` -- warns about variable redefinitions. - - ``reading`` -- shows the number of characters read from a file. - - ``loadLib`` or ``load_lib`` -- shows loading of libraries. - - ``debugLib`` or ``debug_lib`` -- warns about syntax errors - when loading a library. - - ``loadProc`` or ``load_proc`` -- shows loading of procedures - from libraries. - - ``defRes`` or ``def_res`` -- shows the names of the syzygy - modules while converting ``resolution`` to ``list``. - - ``usage`` -- shows correct usage in error messages. - - ``Imap`` or ``imap`` -- shows the mapping of variables with - the ``fetch`` and ``imap`` commands. - - ``notWarnSB`` or ``not_warn_sb`` -- do not warn if - a basis is not a standard basis - - ``contentSB`` or ``content_sb`` -- avoids to divide by the - content of a polynomial in ``std`` and related algorithms. - Should usually not be used. - - ``cancelunit`` -- avoids to divide polynomials by non-constant - units in ``std`` in the local case. Should usually not be used. + - ``mem`` -- shows memory usage in square brackets + - ``yacc`` -- only available in debug version + - ``redefine`` -- warns about variable redefinitions + - ``reading`` -- shows the number of characters read from a file + - ``loadLib`` or ``load_lib`` -- shows loading of libraries + - ``debugLib`` or ``debug_lib`` -- warns about syntax errors + when loading a library + - ``loadProc`` or ``load_proc`` -- shows loading of procedures + from libraries + - ``defRes`` or ``def_res`` -- shows the names of the syzygy + modules while converting ``resolution`` to ``list`` + - ``usage`` -- shows correct usage in error messages + - ``Imap`` or ``imap`` -- shows the mapping of variables with + the ``fetch`` and ``imap`` commands + - ``notWarnSB`` or ``not_warn_sb`` -- do not warn if + a basis is not a standard basis + - ``contentSB`` or ``content_sb`` -- avoids to divide by the + content of a polynomial in ``std`` and related algorithms. + Should usually not be used. + - ``cancelunit`` -- avoids to divide polynomials by non-constant + units in ``std`` in the local case. Should usually not be used EXAMPLES:: @@ -536,7 +535,7 @@ cdef class LibSingularVerboseOptions(LibSingularOptions_abstract): def reset_default(self): """ - Return to libSingular's default verbosity options + Return to libSingular's default verbosity options. EXAMPLES:: @@ -549,7 +548,6 @@ cdef class LibSingularVerboseOptions(LibSingularOptions_abstract): sage: opt_verb.reset_default() sage: opt_verb['not_warn_sb'] False - """ from sage.libs.singular.singular import _saved_verbose_options self.global_options[0] = int(_saved_verbose_options) diff --git a/src/sage/libs/singular/polynomial.pyx b/src/sage/libs/singular/polynomial.pyx index 8908bb8a414..e9ce19c6553 100644 --- a/src/sage/libs/singular/polynomial.pyx +++ b/src/sage/libs/singular/polynomial.pyx @@ -142,11 +142,10 @@ cdef int singular_polynomial_call(poly **ret, poly *p, ring *r, list args, - ``ret`` -- a pointer to a Singular polynomial to store the result in - ``p`` -- a Singular polynomial - ``r`` -- a Singular ring - - ``args`` -- a list/tuple of elements which can be converted to - Singular polynomials using the ``(get_element)`` function - provided. + - ``args`` -- list/tuple of elements which can be converted to Singular + polynomials using the ``(get_element)`` function provided - ``(*get_element)`` -- a function to turn a Sage element into a - Singular element. + Singular element EXAMPLES:: @@ -178,7 +177,7 @@ cdef int singular_polynomial_call(poly **ret, poly *p, ring *r, list args, Loop (at most 30 times) until we have 6 consecutive zeros when calling ``leak(10000)``. Depending on the operating system, it is - possible to have several non-zero leak values in the beginning, but + possible to have several nonzero leak values in the beginning, but after a while we should get only zeros. The fact that we require 6 zeros also means that Singular's pre-allocated buckets should not be sufficient if there really would be a memory leak. :: @@ -591,7 +590,7 @@ cdef int singular_polynomial_length_bounded(poly *p, int bound) noexcept: INPUT: - ``p`` -- a Singular polynomial - - ``bound`` -- an integer > 0 + - ``bound`` -- integer > 0 """ cdef int count = 0 while p != NULL and count < bound: @@ -620,7 +619,7 @@ cdef int singular_polynomial_subst(poly **p, int var_index, poly *value, ring *r INPUT: - ``p`` -- a polynomial - - ``var_index`` -- an integer < ngens (zero based indexing) + - ``var_index`` -- integer < ngens (zero based indexing) - ``value`` -- a polynomial - ``r`` -- a ring """ diff --git a/src/sage/libs/singular/ring.pyx b/src/sage/libs/singular/ring.pyx index cc6d1cf9d41..ef91e60a2a4 100644 --- a/src/sage/libs/singular/ring.pyx +++ b/src/sage/libs/singular/ring.pyx @@ -91,7 +91,7 @@ cdef ring *singular_ring_new(base_ring, n, names, term_order) except NULL: - ``n`` -- the number of variables (> 0) - - ``names`` -- a list of names of length ``n`` + - ``names`` -- list of names of length ``n`` - ``term_order`` -- a term ordering @@ -170,7 +170,6 @@ cdef ring *singular_ring_new(base_ring, n, names, term_order) except NULL: sage: sing_print = singular_function('print') sage: sing_print(R) 'polynomial ring, over a field, global ordering\n// coefficients: QQ(s, t)\n// number of vars : 3\n// block 1 : ordering dp\n// : names x y z\n// block 2 : ordering C' - """ cdef long cexponent cdef GFInfo* _param @@ -299,7 +298,7 @@ cdef ring *singular_ring_new(base_ring, n, names, term_order) except NULL: elif isinstance(base_ring, FractionField_generic) and isinstance(base_ring.base(), (MPolynomialRing_libsingular, PolynomialRing_field)) and isinstance(base_ring.base().base_ring(), RationalField): characteristic = 1 k = PolynomialRing(RationalField(), - names=base_ring.variable_names(), order="lex", implementation="singular") + names=base_ring.variable_names(), order='lex', implementation='singular') ngens = len(k.gens()) @@ -325,7 +324,7 @@ cdef ring *singular_ring_new(base_ring, n, names, term_order) except NULL: raise NotImplementedError("Transcental extension are not implemented for non-prime finite fields") characteristic = int(base_ring.characteristic()) k = PolynomialRing(base_ring.base_ring(), - names=base_ring.variable_names(), order="lex", implementation="singular") + names=base_ring.variable_names(), order='lex', implementation='singular') ngens = len(k.gens()) @@ -349,7 +348,7 @@ cdef ring *singular_ring_new(base_ring, n, names, term_order) except NULL: elif isinstance(base_ring, NumberField) and base_ring.is_absolute(): characteristic = 1 k = PolynomialRing(RationalField(), - name=base_ring.variable_name(), order="lex", implementation="singular") + name=base_ring.variable_name(), order='lex', implementation='singular') minpoly = base_ring.polynomial()(k.gen()) @@ -395,7 +394,7 @@ cdef ring *singular_ring_new(base_ring, n, names, term_order) except NULL: # TODO: This is lazy, it should only call Singular stuff not PolynomialRing() k = PolynomialRing(base_ring.prime_subfield(), - name=base_ring.variable_name(), order="lex", implementation="singular") + name=base_ring.variable_name(), order='lex', implementation='singular') minpoly = base_ring.polynomial()(k.gen()) ch = base_ring.characteristic() @@ -545,9 +544,7 @@ cdef class ring_wrapper_Py(): """ Return a hash value so that instances can be used as dictionary keys. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -562,9 +559,7 @@ cdef class ring_wrapper_Py(): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -588,9 +583,7 @@ cdef class ring_wrapper_Py(): - ``right`` -- a :class:`ring_wrapper_Py` - OUTPUT: - - True if both ``ring_wrapper_Py`` wrap the same pointer. + OUTPUT: ``True`` if both ``ring_wrapper_Py`` wrap the same pointer EXAMPLES:: @@ -627,7 +620,7 @@ cdef wrap_ring(ring* R): INPUT: - - ``R`` -- a singular ring (a C datastructure). + - ``R`` -- a singular ring (a C datastructure) OUTPUT: @@ -644,7 +637,7 @@ cdef ring *singular_ring_reference(ring *existing_ring) except NULL: INPUT: - - ``existing_ring`` -- a Singular ring. + - ``existing_ring`` -- a Singular ring OUTPUT: @@ -760,7 +753,7 @@ cpdef poison_currRing(frame, event, arg): INPUT: - ``frame``, ``event``, ``arg`` -- the standard arguments for the - CPython debugger hook. They are not used. + CPython debugger hook; they are not used OUTPUT: @@ -802,7 +795,8 @@ cpdef print_currRing(): def currRing_wrapper(): """ - Returns a wrapper for the current ring, for use in debugging ring_refcount_dict. + Return a wrapper for the current ring, for use in debugging + ``ring_refcount_dict``. EXAMPLES:: diff --git a/src/sage/libs/singular/singular.pyx b/src/sage/libs/singular/singular.pyx index 465d0841396..6a848a405e0 100644 --- a/src/sage/libs/singular/singular.pyx +++ b/src/sage/libs/singular/singular.pyx @@ -69,9 +69,7 @@ cdef Rational si2sa_QQ(number *n, number **nn, ring *_ring): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - OUTPUT: - - - A sage Rational + OUTPUT: a sage Rational TESTS:: @@ -139,9 +137,7 @@ cdef Integer si2sa_ZZ(number *n, ring *_ring): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - OUTPUT: - - - A sage Integer + OUTPUT: a sage Integer TESTS:: @@ -174,11 +170,9 @@ cdef FFgivE si2sa_GFqGivaro(number *n, ring *_ring, Cache_givaro cache): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``cache`` -- A Givaro number field - - OUTPUT: + - ``cache`` -- a Givaro number field - - A sage element of ``cache`` + OUTPUT: a sage element of ``cache`` TESTS:: @@ -230,11 +224,9 @@ cdef FFgf2eE si2sa_GFqNTLGF2E(number *n, ring *_ring, Cache_ntl_gf2e cache): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``cache`` -- A ntl_gf2e number field + - ``cache`` -- a ntl_gf2e number field - OUTPUT: - - - A sage element of ``cache`` + OUTPUT: a sage element of ``cache`` TESTS:: @@ -281,11 +273,9 @@ cdef object si2sa_GFq_generic(number *n, ring *_ring, object base): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``base`` -- A sage finite field + - ``base`` -- a sage finite field - OUTPUT: - - - A sage element of ``base`` + OUTPUT: a sage element of ``base`` TESTS:: @@ -345,11 +335,9 @@ cdef object si2sa_transext_QQ(number *n, ring *_ring, object base): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``base`` -- A sage FractionField + - ``base`` -- a sage FractionField - OUTPUT: - - - A sage element of ``base`` + OUTPUT: a sage element of ``base`` TESTS:: @@ -434,11 +422,9 @@ cdef object si2sa_transext_FF(number *n, ring *_ring, object base): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``base`` -- A sage FractionField - - OUTPUT: + - ``base`` -- a sage FractionField - - A sage element of ``base`` + OUTPUT: a sage element of ``base`` TESTS:: @@ -514,11 +500,9 @@ cdef object si2sa_NF(number *n, ring *_ring, object base): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``base`` -- A sage NumberField - - OUTPUT: + - ``base`` -- a sage NumberField - - A sage element of ``base`` + OUTPUT: a sage element of ``base`` TESTS:: @@ -579,11 +563,9 @@ cdef inline object si2sa_ZZmod(number *n, ring *_ring, object base): - ``_ ring`` -- a (pointer to) a singular ring, in whose coefficient field lives ``n`` - - ``base`` -- A sage IntegerModRing + - ``base`` -- a sage IntegerModRing - OUTPUT: - - - A sage element of ``base`` + OUTPUT: a sage element of ``base`` TESTS:: @@ -932,7 +914,7 @@ cdef number *sa2si_GFqGivaro(int quo, ring *_ring) noexcept: INPUT: - - ``quo`` -- a sage integer + - ``quo`` -- sage integer - ``_ ring`` -- a (pointer to) a singular ring, where the resul will live @@ -1581,7 +1563,7 @@ cdef inline number *sa2si_ZZmod(IntegerMod_abstract d, ring *_ring) noexcept: cdef object si2sa(number *n, ring *_ring, object base): r""" - Create a sage number from a singular one + Create a sage number from a singular one. INPUT: @@ -1636,10 +1618,10 @@ cdef number *sa2si(Element elem, ring * _ring) noexcept: INPUT: - - ``elem`` -- a sage element from a parent. The parent must have a - corresponding singular coefficient type. + - ``elem`` -- a sage element from a parent; the parent must have a + corresponding singular coefficient type - - ``_ring`` -- a (pointer to) the singular ring where the result will live. + - ``_ring`` -- a (pointer to) the singular ring where the result will live OUTPUT: @@ -1680,7 +1662,7 @@ cdef number *sa2si(Element elem, ring * _ring) noexcept: cdef object si2sa_intvec(intvec *v): r""" - create a sage tuple from a singular vector of integers + Create a sage tuple from a singular vector of integers. INPUT: @@ -1698,7 +1680,7 @@ cdef object si2sa_intvec(intvec *v): cdef object si2sa_bigintvec(bigintmat *v): r""" - create a sage tuple from a singular vector of big integers + Create a sage tuple from a singular vector of big integers. INPUT: @@ -1726,13 +1708,13 @@ from posix.dlfcn cimport dlopen, dlclose, dlerror, RTLD_LAZY, RTLD_GLOBAL cdef int overflow_check(unsigned long e, ring *_ring) except -1: """ - Raise an ``OverflowError`` if e is > max degree per variable. + Raise an :exc:`OverflowError` if e is > max degree per variable. INPUT: - - ``e`` -- some integer representing a degree. + - ``e`` -- some integer representing a degree - - ``_ring`` -- a pointer to some ring. + - ``_ring`` -- a pointer to some ring Whether an overflow occurs or not partially depends @@ -1742,7 +1724,6 @@ cdef int overflow_check(unsigned long e, ring *_ring) except -1: which in both cases makes a maximal default exponent of 2^16-1. - EXAMPLES:: sage: P. = QQ[] @@ -1839,9 +1820,7 @@ def get_resource(id): - ``id`` -- a single-character string; see https://github.com/Singular/Singular/blob/spielwiese/resources/feResource.cc - OUTPUT: - - A string, or ``None``. + OUTPUT: string or ``None`` EXAMPLES:: diff --git a/src/sage/libs/singular/standard_options.py b/src/sage/libs/singular/standard_options.py index 341650fa6ba..476961b2f09 100644 --- a/src/sage/libs/singular/standard_options.py +++ b/src/sage/libs/singular/standard_options.py @@ -27,7 +27,6 @@ def __init__(self): sage: with LibSingularGBDefaultContext(): rgb = groebner(I) sage: rgb [84*c^4 - 40*c^3 + c^2 + c, 7*b + 210*c^3 - 79*c^2 + 3*c, 7*a - 420*c^3 + 158*c^2 + 8*c - 7] - """ from sage.libs.singular.option import opt_ctx self.libsingular_option_context = opt_ctx @@ -60,7 +59,6 @@ def __enter__(self): 5913075*c + 371438283744*d^7 - 237550027104*d^6 + 22645939824*d^5 + 11520686172*d^4 - 2024910556*d^3 - 132524276*d^2 + 30947828*d, 1971025*b - 97197721632*d^7 + 73975630752*d^6 - 12121915032*d^5 - 2760941496*d^4 + 814792828*d^3 - 1678512*d^2 - 9158924*d, 5913075*a - 159690237696*d^7 + 31246269696*d^6 + 27439610544*d^5 - 6475723368*d^4 - 838935856*d^3 + 275119624*d^2 + 4884038*d - 5913075] - """ self.libsingular_option_context.__enter__() self.libsingular_option_context.opt.reset_default() @@ -127,7 +125,7 @@ def libsingular_gb_standard_options(func): ... ' return self.basis.reduced()\n'], ...) - .. note:: + .. NOTE:: This decorator is used automatically internally so the user does not need to use it manually. diff --git a/src/sage/libs/sirocco.pyx b/src/sage/libs/sirocco.pyx index 8cca0892c55..ca3b267fa66 100644 --- a/src/sage/libs/sirocco.pyx +++ b/src/sage/libs/sirocco.pyx @@ -45,7 +45,6 @@ cpdef list[list] contpath_mp(int deg, list values, RealNumber y0r, RealNumber y0 [(0.000000000000000, 0.000000000000000, 0.000000000000000), (0.500000000000000, -0.250000000000000, 0.000000000000000), (1.00000000000000, -1.00000000000000, 0.000000000000000)] - """ cdef mpfr_t* cvalues = check_allocarray(len(values), sizeof(mpfr_t)) cdef mpfr_t* rop @@ -113,7 +112,6 @@ cpdef list[list] contpath_mp_comps(int deg, list values, RealNumber y0r, RealNum (0.750000000000000, -0.562500000000000, 0.000000000000000), (0.875000000000000, -0.765625000000000, 0.000000000000000), (1.00000000000000, -1.00000000000000, 0.000000000000000)] - """ cdef mpfr_t* cvalues = check_allocarray(len(values), sizeof(mpfr_t)) @@ -199,7 +197,6 @@ cpdef list[list] contpath(int deg, list values, double y0r, double y0i) noexcept (0.3535533905932738, -0.12500000000000003, 0.0), (0.7071067811865476, -0.5000000000000001, 0.0), (1.0, -1.0, 0.0)] - """ cdef double* rop cdef double* c_values = check_allocarray(len(values), sizeof(double)) @@ -260,7 +257,6 @@ cpdef list[list] contpath_comps(int deg, list values, double y0r, double y0i, li (0.75, -0.5625, 0.0), (0.875, -0.765625, 0.0), (1.0, -1.0, 0.0)] - """ cdef double* rop cdef double* c_values = check_allocarray(len(values), sizeof(double)) diff --git a/src/sage/libs/symmetrica/kostka.pxi b/src/sage/libs/symmetrica/kostka.pxi index d69aefc7c2c..8c2656b2b17 100644 --- a/src/sage/libs/symmetrica/kostka.pxi +++ b/src/sage/libs/symmetrica/kostka.pxi @@ -8,7 +8,7 @@ cdef extern from 'symmetrica/def.h': def kostka_number_symmetrica(shape, content): """ - computes the kostkanumber, i.e. the number of + Compute the kostkanumber, i.e. the number of tableaux of given shape, which is a PARTITION object, and of given content, which also is a PARTITION object, or a VECTOR object with INTEGER entries. The @@ -55,7 +55,7 @@ def kostka_number_symmetrica(shape, content): def kostka_tab_symmetrica(shape, content): """ - computes the list of tableaux of given shape + Compute the list of tableaux of given shape and content. shape is a PARTITION object or a SKEWPARTITION object and content is a PARTITION object or a VECTOR object with @@ -77,8 +77,6 @@ def kostka_tab_symmetrica(shape, content): [[None, 2], [None, 3], [1]]] sage: symmetrica.kostka_tab([[2,2],[1]],[1,1,1]) [[[None, 1], [2, 3]], [[None, 2], [1, 3]]] - - """ late_import() @@ -115,7 +113,7 @@ def kostka_tab_symmetrica(shape, content): def kostka_tafel_symmetrica(n): """ - Returns the table of Kostka numbers of weight n. + Return the table of Kostka numbers of weight `n`. EXAMPLES:: diff --git a/src/sage/libs/symmetrica/part.pxi b/src/sage/libs/symmetrica/part.pxi index 37a3c0ff8f0..ee94a8a1557 100644 --- a/src/sage/libs/symmetrica/part.pxi +++ b/src/sage/libs/symmetrica/part.pxi @@ -8,10 +8,9 @@ cdef extern from 'symmetrica/def.h': def strict_to_odd_part_symmetrica(part): """ - implements the bijection between strict partitions + Implement the bijection between strict partitions and partitions with odd parts. input is a VECTOR type partition, the result is a partition of the same weight with only odd parts. - """ #Make sure that the partition is strict @@ -39,7 +38,7 @@ def strict_to_odd_part_symmetrica(part): def odd_to_strict_part_symmetrica(part): """ - implements the bijection between partitions with odd parts + Implement the bijection between partitions with odd parts and strict partitions. input is a VECTOR type partition, the result is a partition of the same weight with different parts. """ @@ -70,12 +69,11 @@ def odd_to_strict_part_symmetrica(part): def q_core_symmetrica(part, d): """ - computes the q-core of a PARTITION object + Compute the q-core of a PARTITION object part. This is the remaining partition (=res) after removing of all hooks of length d (= INTEGER object). The result may be an empty object, if the whole partition disappears. - """ @@ -102,7 +100,7 @@ def q_core_symmetrica(part, d): def gupta_nm_symmetrica(n, m): """ - this routine computes the number of partitions + This routine computes the number of partitions of n with maximal part m. The result is erg. The input n,m must be INTEGER objects. The result is freed first to an empty object. The result must @@ -133,7 +131,7 @@ def gupta_nm_symmetrica(n, m): def gupta_tafel_symmetrica(max): """ - it computes the table of the above values. The entry + It computes the table of the above values. The entry n,m is the result of gupta_nm. mat is freed first. max must be an INTEGER object, it is the maximum weight for the partitions. max must be different from diff --git a/src/sage/libs/symmetrica/plet.pxi b/src/sage/libs/symmetrica/plet.pxi index b1f8450c621..e2b82aa8b07 100644 --- a/src/sage/libs/symmetrica/plet.pxi +++ b/src/sage/libs/symmetrica/plet.pxi @@ -3,9 +3,6 @@ cdef extern from 'symmetrica/def.h': INT schur_schur_plet(OP p1, OP p2, OP res) def plethysm_symmetrica(outer, inner): - """ - """ - cdef OP couter = callocobject(), cinner = callocobject(), cresult = callocobject() _op_schur(outer, couter) @@ -25,9 +22,6 @@ def plethysm_symmetrica(outer, inner): def schur_schur_plet_symmetrica(outer, inner): - """ - """ - cdef OP couter = callocobject(), cinner = callocobject(), cresult = callocobject() _op_partition(outer, couter) diff --git a/src/sage/libs/symmetrica/sab.pxi b/src/sage/libs/symmetrica/sab.pxi index b7900106b35..04c23540656 100644 --- a/src/sage/libs/symmetrica/sab.pxi +++ b/src/sage/libs/symmetrica/sab.pxi @@ -10,7 +10,7 @@ cdef extern from 'symmetrica/def.h': def dimension_symmetrization_symmetrica(n, part): """ - computes the dimension of the degree of a irreducible + Compute the dimension of the degree of a irreducible representation of the GL_n, n is a INTEGER object, labeled by the PARTITION object a. """ @@ -37,7 +37,7 @@ def dimension_symmetrization_symmetrica(n, part): def bdg_symmetrica(part, perm): """ - Calculates the irreducible matrix representation + Calculate the irreducible matrix representation D^part(perm), whose entries are of integral numbers. REFERENCE: H. Boerner: @@ -64,7 +64,7 @@ def bdg_symmetrica(part, perm): def sdg_symmetrica(part, perm): """ - Calculates the irreducible matrix representation + Calculate the irreducible matrix representation D^part(perm), which consists of rational numbers. REFERENCE: G. James/ A. Kerber: @@ -93,7 +93,7 @@ def sdg_symmetrica(part, perm): def odg_symmetrica(part, perm): """ - Calculates the irreducible matrix representation + Calculate the irreducible matrix representation D^part(perm), which consists of real numbers. REFERENCE: G. James/ A. Kerber: @@ -122,12 +122,8 @@ def odg_symmetrica(part, perm): def ndg_symmetrica(part, perm): - """ - - """ cdef OP cpart, cperm, cD - cpart = callocobject() cperm = callocobject() cD = callocobject() @@ -145,12 +141,8 @@ def ndg_symmetrica(part, perm): return res def specht_dg_symmetrica(part, perm): - """ - - """ cdef OP cpart, cperm, cD - cpart = callocobject() cperm = callocobject() cD = callocobject() diff --git a/src/sage/libs/symmetrica/sb.pxi b/src/sage/libs/symmetrica/sb.pxi index b884d33dafd..1d6731fdb89 100644 --- a/src/sage/libs/symmetrica/sb.pxi +++ b/src/sage/libs/symmetrica/sb.pxi @@ -31,7 +31,7 @@ cdef object _check_schubert(object a, OP ca): def mult_schubert_schubert_symmetrica(a, b): """ - Multiplies the Schubert polynomials a and b. + Multiply the Schubert polynomials `a` and `b`. EXAMPLES:: @@ -66,7 +66,7 @@ def mult_schubert_schubert_symmetrica(a, b): def t_SCHUBERT_POLYNOM_symmetrica(a): """ - Converts a Schubert polynomial to a 'regular' multivariate + Convert a Schubert polynomial to a 'regular' multivariate polynomial. EXAMPLES:: @@ -98,7 +98,7 @@ def t_SCHUBERT_POLYNOM_symmetrica(a): def t_POLYNOM_SCHUBERT_symmetrica(a): """ - Converts a multivariate polynomial a to a Schubert polynomial. + Convert a multivariate polynomial a to a Schubert polynomial. EXAMPLES:: @@ -137,7 +137,7 @@ def t_POLYNOM_SCHUBERT_symmetrica(a): def mult_schubert_variable_symmetrica(a, i): """ - Returns the product of a and x_i. Note that indexing with i + Return the product of `a` and `x_i`. Note that indexing with `i` starts at 1. EXAMPLES:: @@ -176,9 +176,9 @@ def mult_schubert_variable_symmetrica(a, i): def divdiff_perm_schubert_symmetrica(perm, a): r""" - Returns the result of applying the divided difference operator + Return the result of applying the divided difference operator `\delta_i` to `a` where `a` is either a permutation or a - Schubert polynomial over QQ. + Schubert polynomial over `\QQ`. EXAMPLES:: @@ -272,9 +272,9 @@ def scalarproduct_schubert_symmetrica(a, b): def divdiff_schubert_symmetrica(i, a): r""" - Returns the result of applying the divided difference operator + Return the result of applying the divided difference operator `\delta_i` to `a` where `a` is either a permutation or a - Schubert polynomial over QQ. + Schubert polynomial over `\QQ`. EXAMPLES:: diff --git a/src/sage/libs/symmetrica/sc.pxi b/src/sage/libs/symmetrica/sc.pxi index 4d9fa4f009d..77fe02802a1 100644 --- a/src/sage/libs/symmetrica/sc.pxi +++ b/src/sage/libs/symmetrica/sc.pxi @@ -7,7 +7,7 @@ cdef extern from 'symmetrica/def.h': def chartafel_symmetrica(n): """ - you enter the degree of the symmetric group, as INTEGER + You enter the degree of the symmetric group, as INTEGER object and the result is a MATRIX object: the charactertable of the symmetric group of the given degree. @@ -43,7 +43,7 @@ def chartafel_symmetrica(n): def charvalue_symmetrica(irred, cls, table=None): """ - you enter a PARTITION object part, labelling the irreducible + You enter a PARTITION object part, labelling the irreducible character, you enter a PARTITION object class, labeling the class or class may be a PERMUTATION object, then result becomes the value of that character on that class or permutation. Note that the @@ -98,7 +98,7 @@ def charvalue_symmetrica(irred, cls, table=None): def kranztafel_symmetrica(a, b): r""" - you enter the INTEGER objects, say `a` and `b`, and ``res`` becomes a + You enter the INTEGER objects, say `a` and `b`, and ``res`` becomes a MATRIX object, the charactertable of `S_b \wr S_a`, ``co`` becomes a VECTOR object of classorders and ``cl`` becomes a VECTOR object of the classlabels. diff --git a/src/sage/libs/symmetrica/schur.pxi b/src/sage/libs/symmetrica/schur.pxi index 82e77d0d251..a9a5c7bf1d7 100644 --- a/src/sage/libs/symmetrica/schur.pxi +++ b/src/sage/libs/symmetrica/schur.pxi @@ -55,7 +55,7 @@ cdef extern from 'symmetrica/def.h': def outerproduct_schur_symmetrica(parta, partb): """ - you enter two PARTITION objects, and the result is + You enter two PARTITION objects, and the result is a SCHUR object, which is the expansion of the product of the two schurfunctions, labeled by the two PARTITION objects parta and partb. @@ -92,7 +92,7 @@ def outerproduct_schur_symmetrica(parta, partb): def dimension_schur_symmetrica(s): """ - you enter a SCHUR object a, and the result is the + You enter a SCHUR object a, and the result is the dimension of the corresponding representation of the symmetric group sn. """ @@ -115,7 +115,7 @@ def dimension_schur_symmetrica(s): def newtrans_symmetrica(perm): """ - computes the decomposition of a schubertpolynomial labeled by + Compute the decomposition of a schubertpolynomial labeled by the permutation perm, as a sum of Schurfunction. FIXME! @@ -138,7 +138,7 @@ def newtrans_symmetrica(perm): def compute_schur_with_alphabet_symmetrica(part, length, alphabet='x'): """ - Computes the expansion of a schurfunction labeled by a + Compute the expansion of a schurfunction labeled by a partition PART as a POLYNOM erg. The INTEGER length specifies the length of the alphabet. @@ -182,7 +182,7 @@ def compute_schur_with_alphabet_symmetrica(part, length, alphabet='x'): def compute_homsym_with_alphabet_symmetrica(n, length, alphabet='x'): """ - computes the expansion of a homogeneous(=complete) symmetric + Compute the expansion of a homogeneous(=complete) symmetric function labeled by a INTEGER number as a POLYNOM erg. The object number may also be a PARTITION or a HOM_SYM object. The INTEGER laenge specifies the length of the alphabet. @@ -200,7 +200,6 @@ def compute_homsym_with_alphabet_symmetrica(n, length, alphabet='x'): a^3 + 2*a^2*b + 2*a*b^2 + b^3 sage: symmetrica.compute_homsym_with_alphabet([2,1],2,'x').parent() Multivariate Polynomial Ring in x0, x1 over Integer Ring - """ late_import() cdef OP cn = callocobject(), clength = callocobject(), cresult = callocobject() @@ -229,7 +228,7 @@ def compute_homsym_with_alphabet_symmetrica(n, length, alphabet='x'): def compute_elmsym_with_alphabet_symmetrica(n, length, alphabet='x'): """ - computes the expansion of a elementary symmetric + Compute the expansion of a elementary symmetric function labeled by a INTEGER number as a POLYNOM erg. The object number may also be a PARTITION or a ELM_SYM object. The INTEGER length specifies the length of the alphabet. @@ -247,7 +246,6 @@ def compute_elmsym_with_alphabet_symmetrica(n, length, alphabet='x'): 0 sage: symmetrica.compute_elmsym_with_alphabet([3,2,1],2) 0 - """ late_import() cdef OP cn = callocobject(), clength = callocobject(), cresult = callocobject() @@ -280,7 +278,7 @@ def compute_elmsym_with_alphabet_symmetrica(n, length, alphabet='x'): def compute_monomial_with_alphabet_symmetrica(n, length, alphabet='x'): """ - computes the expansion of a monomial symmetric + Compute the expansion of a monomial symmetric function labeled by a PARTITION number as a POLYNOM erg. The INTEGER laenge specifies the length of the alphabet. @@ -296,7 +294,6 @@ def compute_monomial_with_alphabet_symmetrica(n, length, alphabet='x'): a^2 + b^2 sage: symmetrica.compute_monomial_with_alphabet(2,2,'x').parent() Multivariate Polynomial Ring in x0, x1 over Integer Ring - """ late_import() cdef OP cn = callocobject(), clength = callocobject(), cresult = callocobject() @@ -326,7 +323,7 @@ def compute_monomial_with_alphabet_symmetrica(n, length, alphabet='x'): def compute_powsym_with_alphabet_symmetrica(n, length, alphabet='x'): """ - computes the expansion of a power symmetric + Compute the expansion of a power symmetric function labeled by a INTEGER label or by a PARTITION label or a POW_SYM label as a POLYNOM erg. The INTEGER laenge specifies the length of the alphabet. @@ -343,7 +340,6 @@ def compute_powsym_with_alphabet_symmetrica(n, length, alphabet='x'): a^2 + b^2 sage: symmetrica.compute_powsym_with_alphabet([2,1],2,'a,b') a^3 + a^2*b + a*b^2 + b^3 - """ late_import() cdef OP cn = callocobject(), clength = callocobject(), cresult = callocobject() @@ -436,7 +432,7 @@ def part_part_skewschur_symmetrica(outer, inner): def hall_littlewood_symmetrica(part): """ - computes the so called Hall Littlewood Polynomials, i.e. + Compute the so called Hall Littlewood Polynomials, i.e. a SCHUR object, whose coefficient are polynomials in one variable. The method, which is used for the computation is described in the paper: A.O. Morris The Characters of the group GL(n,q) @@ -464,9 +460,6 @@ def hall_littlewood_symmetrica(part): def t_SCHUR_MONOMIAL_symmetrica(schur): - """ - """ - cdef OP cschur = callocobject(), cresult = callocobject() _op_schur(schur, cschur) @@ -484,9 +477,6 @@ def t_SCHUR_MONOMIAL_symmetrica(schur): def t_SCHUR_HOMSYM_symmetrica(schur): - """ - """ - cdef OP cschur = callocobject(), cresult = callocobject() _op_schur(schur, cschur) @@ -504,9 +494,6 @@ def t_SCHUR_HOMSYM_symmetrica(schur): def t_SCHUR_ELMSYM_symmetrica(schur): - """ - """ - cdef OP cschur = callocobject(), cresult = callocobject() _op_schur(schur, cschur) @@ -524,10 +511,6 @@ def t_SCHUR_ELMSYM_symmetrica(schur): def t_SCHUR_POWSYM_symmetrica(schur): - """ - - """ - cdef OP cschur = callocobject(), cresult = callocobject() _op_schur(schur, cschur) @@ -544,9 +527,9 @@ def t_SCHUR_POWSYM_symmetrica(schur): return res def t_POLYNOM_SCHUR_symmetrica(p): - """ - Converts a symmetric polynomial with base ring QQ or ZZ into a symmetric function - in the Schur basis. + r""" + Convert a symmetric polynomial with base ring `\QQ` or `\ZZ` into a + symmetric function in the Schur basis. """ cdef OP polynom = callocobject(), cresult = callocobject() @@ -568,10 +551,6 @@ def t_POLYNOM_SCHUR_symmetrica(p): def t_MONOMIAL_HOMSYM_symmetrica(monomial): - """ - - """ - cdef OP cmonomial = callocobject(), cresult = callocobject() _op_monomial(monomial, cmonomial) @@ -588,10 +567,6 @@ def t_MONOMIAL_HOMSYM_symmetrica(monomial): return res def t_MONOMIAL_ELMSYM_symmetrica(monomial): - """ - - """ - cdef OP cmonomial = callocobject(), cresult = callocobject() _op_monomial(monomial, cmonomial) @@ -609,10 +584,6 @@ def t_MONOMIAL_ELMSYM_symmetrica(monomial): def t_MONOMIAL_SCHUR_symmetrica(monomial): - """ - - """ - cdef OP cmonomial = callocobject(), cresult = callocobject() _op_monomial(monomial, cmonomial) @@ -630,10 +601,6 @@ def t_MONOMIAL_SCHUR_symmetrica(monomial): def t_MONOMIAL_POWSYM_symmetrica(monomial): - """ - - """ - cdef OP cmonomial = callocobject(), cresult = callocobject() _op_monomial(monomial, cmonomial) @@ -650,9 +617,9 @@ def t_MONOMIAL_POWSYM_symmetrica(monomial): return res def t_POLYNOM_MONOMIAL_symmetrica(p): - """ - Converts a symmetric polynomial with base ring QQ or ZZ into a symmetric function - in the monomial basis. + r""" + Convert a symmetric polynomial with base ring `\QQ` or `\ZZ` into a + symmetric function in the monomial basis. """ cdef OP polynom = callocobject(), cresult = callocobject() @@ -674,10 +641,6 @@ def t_POLYNOM_MONOMIAL_symmetrica(p): def t_ELMSYM_SCHUR_symmetrica(elmsym): - """ - - """ - cdef OP celmsym = callocobject(), cresult = callocobject() _op_elmsym(elmsym, celmsym) @@ -695,10 +658,6 @@ def t_ELMSYM_SCHUR_symmetrica(elmsym): def t_ELMSYM_POWSYM_symmetrica(elmsym): - """ - - """ - cdef OP celmsym = callocobject(), cresult = callocobject() _op_elmsym(elmsym, celmsym) @@ -715,10 +674,6 @@ def t_ELMSYM_POWSYM_symmetrica(elmsym): return res def t_ELMSYM_MONOMIAL_symmetrica(elmsym): - """ - - """ - cdef OP celmsym = callocobject(), cresult = callocobject() _op_elmsym(elmsym, celmsym) @@ -736,10 +691,6 @@ def t_ELMSYM_MONOMIAL_symmetrica(elmsym): def t_ELMSYM_HOMSYM_symmetrica(elmsym): - """ - - """ - cdef OP celmsym = callocobject(), cresult = callocobject() _op_elmsym(elmsym, celmsym) @@ -756,9 +707,9 @@ def t_ELMSYM_HOMSYM_symmetrica(elmsym): return res def t_POLYNOM_ELMSYM_symmetrica(p): - """ - Converts a symmetric polynomial with base ring QQ or ZZ into a symmetric function - in the elementary basis. + r""" + Convert a symmetric polynomial with base ring `\QQ` or `\ZZ` into a + symmetric function in the elementary basis. """ cdef OP polynom = callocobject(), cresult = callocobject() @@ -780,10 +731,6 @@ def t_POLYNOM_ELMSYM_symmetrica(p): def t_HOMSYM_SCHUR_symmetrica(homsym): - """ - - """ - cdef OP chomsym = callocobject(), cresult = callocobject() _op_homsym(homsym, chomsym) @@ -800,10 +747,6 @@ def t_HOMSYM_SCHUR_symmetrica(homsym): return res def t_HOMSYM_POWSYM_symmetrica(homsym): - """ - - """ - cdef OP chomsym = callocobject(), cresult = callocobject() _op_homsym(homsym, chomsym) @@ -821,10 +764,6 @@ def t_HOMSYM_POWSYM_symmetrica(homsym): def t_HOMSYM_MONOMIAL_symmetrica(homsym): - """ - - """ - cdef OP chomsym = callocobject(), cresult = callocobject() _op_homsym(homsym, chomsym) @@ -841,10 +780,6 @@ def t_HOMSYM_MONOMIAL_symmetrica(homsym): return res def t_HOMSYM_ELMSYM_symmetrica(homsym): - """ - - """ - cdef OP chomsym = callocobject(), cresult = callocobject() _op_homsym(homsym, chomsym) @@ -862,10 +797,6 @@ def t_HOMSYM_ELMSYM_symmetrica(homsym): def t_POWSYM_MONOMIAL_symmetrica(powsym): - """ - - """ - cdef OP cpowsym = callocobject(), cresult = callocobject() _op_powsym(powsym, cpowsym) @@ -883,10 +814,6 @@ def t_POWSYM_MONOMIAL_symmetrica(powsym): def t_POWSYM_SCHUR_symmetrica(powsym): - """ - - """ - cdef OP cpowsym = callocobject(), cresult = callocobject() _op_powsym(powsym, cpowsym) @@ -903,10 +830,6 @@ def t_POWSYM_SCHUR_symmetrica(powsym): return res def t_POWSYM_ELMSYM_symmetrica(powsym): - """ - - """ - cdef OP cpowsym = callocobject(), cresult = callocobject() _op_powsym(powsym, cpowsym) @@ -923,10 +846,6 @@ def t_POWSYM_ELMSYM_symmetrica(powsym): return res def t_POWSYM_HOMSYM_symmetrica(powsym): - """ - - """ - cdef OP cpowsym = callocobject(), cresult = callocobject() _op_powsym(powsym, cpowsym) @@ -943,9 +862,9 @@ def t_POWSYM_HOMSYM_symmetrica(powsym): return res def t_POLYNOM_POWER_symmetrica(p): - """ - Converts a symmetric polynomial with base ring QQ or ZZ into a symmetric function - in the power sum basis. + r""" + Convert a symmetric polynomial with base ring `\QQ` or `\ZZ` into a + symmetric function in the power sum basis. """ cdef OP polynom = callocobject(), cresult = callocobject() @@ -967,8 +886,6 @@ def t_POLYNOM_POWER_symmetrica(p): def mult_schur_schur_symmetrica(s1, s2): - """ - """ cdef OP cs1 = callocobject(), cs2 = callocobject(), cresult = callocobject() _op_schur(s1, cs1) @@ -988,8 +905,6 @@ def mult_schur_schur_symmetrica(s1, s2): def mult_monomial_monomial_symmetrica(m1, m2): - """ - """ cdef OP cm1 = callocobject(), cm2 = callocobject(), cresult = callocobject() _op_monomial(m1, cm1) diff --git a/src/sage/libs/symmetrica/symmetrica.pxi b/src/sage/libs/symmetrica/symmetrica.pxi index 1dbe23a6675..5786870caca 100644 --- a/src/sage/libs/symmetrica/symmetrica.pxi +++ b/src/sage/libs/symmetrica/symmetrica.pxi @@ -524,7 +524,7 @@ cdef int _op(object a, OP result) except -1: def test_integer(object x): """ - Tests functionality for converting between Sage's integers + Test functionality for converting between Sage's integers and symmetrica's integers. EXAMPLES:: @@ -792,13 +792,12 @@ cdef object _py_polynom(OP a): cdef object _py_polynom_alphabet(OP a, object alphabet, object length): """ - Converts a symmetrica multivariate polynomial a to a Sage multivariate + Convert a symmetrica multivariate polynomial a to a Sage multivariate polynomials. Alphabet specifies the names of the variables which are fed into PolynomialRing. length specifies the number of variables; if it is set to 0, then the number of variables is autodetected based on the number of variables in alphabet or the result obtained from symmetrica. - """ late_import() cdef OP pointer = a diff --git a/src/sage/logic/booleval.py b/src/sage/logic/booleval.py index 84da89f0c3f..3775d6e5e3a 100644 --- a/src/sage/logic/booleval.py +++ b/src/sage/logic/booleval.py @@ -45,14 +45,12 @@ def eval_formula(tree, vdict): INPUT: - - ``tree`` -- a list of three elements corresponding to a branch of a + - ``tree`` -- list of three elements corresponding to a branch of a parse tree - - ``vdict`` -- a dictionary containing variable keys and boolean values + - ``vdict`` -- dictionary containing variable keys and boolean values - OUTPUT: - - The result of the evaluation as a boolean value. + OUTPUT: the result of the evaluation as a boolean value EXAMPLES: @@ -81,12 +79,10 @@ def eval_f(tree): INPUT: - - ``tree`` -- a list of three elements corresponding to a branch of a + - ``tree`` -- list of three elements corresponding to a branch of a parse tree - OUTPUT: - - The result of the evaluation as a boolean value. + OUTPUT: the result of the evaluation as a boolean value EXAMPLES: @@ -111,15 +107,13 @@ def eval_op(op, lv, rv): INPUT: - - ``op`` -- a string or character representing a boolean operator - - - ``lv`` -- a boolean or variable + - ``op`` -- string or character representing a boolean operator - - ``rv`` -- a boolean or variable + - ``lv`` -- boolean or variable - OUTPUT: + - ``rv`` -- boolean or variable - The evaluation of ``lv op rv`` as a boolean value. + OUTPUT: the evaluation of ``lv op rv`` as a boolean value EXAMPLES: diff --git a/src/sage/logic/boolformula.py b/src/sage/logic/boolformula.py index 304664e79ba..817132fb8f8 100644 --- a/src/sage/logic/boolformula.py +++ b/src/sage/logic/boolformula.py @@ -155,12 +155,12 @@ class BooleanFormula: - ``self`` -- calling object - - ``exp`` -- a string; this contains the boolean expression + - ``exp`` -- string; this contains the boolean expression to be manipulated - - ``tree`` -- a list; this contains the parse tree of the expression. + - ``tree`` -- list; this contains the parse tree of the expression - - ``vo`` -- a list; this contains the variables in the expression, in the + - ``vo`` -- list; this contains the variables in the expression, in the order that they appear; each variable only occurs once in the list """ __expression = "" @@ -188,10 +188,6 @@ def __repr__(self): r""" Return a string representation of this statement. - OUTPUT: - - A string representation of calling statement - EXAMPLES:: sage: import sage.logic.propcalc as propcalc @@ -204,9 +200,7 @@ def _latex_(self): r""" Return a LaTeX representation of this statement. - OUTPUT: - - A string containing the latex code for the statement + OUTPUT: string containing the latex code for the statement EXAMPLES:: @@ -228,9 +222,7 @@ def polish_notation(self): r""" Convert the calling boolean formula into polish notation. - OUTPUT: - - A string representation of the formula in polish notation. + OUTPUT: string representation of the formula in polish notation EXAMPLES: @@ -255,9 +247,7 @@ def tree(self): r""" Return the parse tree of this boolean expression. - OUTPUT: - - The parse tree as a nested list + OUTPUT: the parse tree as a nested list EXAMPLES: @@ -288,9 +278,7 @@ def full_tree(self): r""" Return a full syntax parse tree of the calling formula. - OUTPUT: - - The full syntax parse tree as a nested list + OUTPUT: the full syntax parse tree as a nested list EXAMPLES: @@ -327,7 +315,7 @@ def __or__(self, other): INPUT: - - ``other`` -- a boolean formula; this is the statement + - ``other`` -- boolean formula; this is the statement on the right side of the operator OUTPUT: @@ -352,12 +340,10 @@ def __and__(self, other): INPUT: - - ``other`` -- a boolean formula; this is the formula on + - ``other`` -- boolean formula; this is the formula on the right side of the operator - OUTPUT: - - A boolean formula of the form ``self & other``. + OUTPUT: a boolean formula of the form ``self & other`` EXAMPLES: @@ -377,12 +363,10 @@ def __xor__(self, other): INPUT: - - ``other`` -- a boolean formula; this is the formula on + - ``other`` -- boolean formula; this is the formula on the right side of the operator - OUTPUT: - - A boolean formula of the form ``self ^ other``. + OUTPUT: a boolean formula of the form ``self ^ other`` EXAMPLES: @@ -402,12 +386,10 @@ def __pow__(self, other): INPUT: - - ``other`` -- a boolean formula; this is the formula on + - ``other`` -- boolean formula; this is the formula on the right side of the operator - OUTPUT: - - A boolean formula of the form ``self ^ other``. + OUTPUT: a boolean formula of the form ``self ^ other`` EXAMPLES: @@ -432,9 +414,7 @@ def __invert__(self): r""" Overload the ``~`` operator to 'not' a statement. - OUTPUT: - - A boolean formula of the form ``~self``. + OUTPUT: a boolean formula of the form ``~self`` EXAMPLES: @@ -455,7 +435,7 @@ def ifthen(self, other): INPUT: - - ``other`` -- a boolean formula; this is the formula + - ``other`` -- boolean formula; this is the formula on the right side of the operator OUTPUT: @@ -480,7 +460,7 @@ def iff(self, other): INPUT: - - ``other`` -- a boolean formula; this is the formula + - ``other`` -- boolean formula; this is the formula on the right side of the operator OUTPUT: @@ -505,12 +485,10 @@ def __eq__(self, other): INPUT: - - ``other`` -- a boolean formula; this is the formula + - ``other`` -- boolean formula; this is the formula on the right side of the comparator - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if ``self`` and ``other`` are logically equivalent @@ -546,9 +524,7 @@ def truthtable(self, start=0, end=-1): - ``end`` -- (default: -1) an integer; this is the last row of the truth table to be created - OUTPUT: - - The truth table as a 2-D array + OUTPUT: the truth table as a 2-D array EXAMPLES: @@ -624,12 +600,10 @@ def evaluate(self, var_values): INPUT: - - ``var_values`` -- a dictionary; this contains the - pairs of variables and their boolean values. - - OUTPUT: + - ``var_values`` -- dictionary; this contains the + pairs of variables and their boolean values - The result of the evaluation as a boolean. + OUTPUT: the result of the evaluation as a boolean EXAMPLES: @@ -648,9 +622,7 @@ def is_satisfiable(self): r""" Determine if the formula is ``True`` for some assignment of values. - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if there is an assignment of values that makes the formula ``True``. @@ -678,9 +650,7 @@ def is_tautology(self): r""" Determine if the formula is always ``True``. - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if the formula is a tautology. @@ -709,9 +679,7 @@ def is_contradiction(self): r""" Determine if the formula is always ``False``. - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if the formula is a contradiction. @@ -748,9 +716,7 @@ def is_consequence(self, *hypotheses): - ``*hypotheses`` -- instances of :class:`BooleanFormula` - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` -- if ``self`` (the desired conclusion) is a logical consequence of the set of hypotheses @@ -832,9 +798,7 @@ def implies(self, other): - ``other`` -- instance of :class:`BooleanFormula` - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` -- if ``self`` implies ``other`` @@ -876,15 +840,13 @@ def equivalent(self, other): - ``self`` -- calling object - - ``other`` -- instance of BooleanFormula class. - - OUTPUT: + - ``other`` -- instance of BooleanFormula class - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - True - if the two formulas are logically equivalent + ``True`` -- if the two formulas are logically equivalent - False - if the two formulas are not logically equivalent + ``False`` -- if the two formulas are not logically equivalent EXAMPLES: @@ -906,9 +868,7 @@ def convert_cnf_table(self): r""" Convert boolean formula to conjunctive normal form. - OUTPUT: - - An instance of :class:`BooleanFormula` in conjunctive normal form. + OUTPUT: an instance of :class:`BooleanFormula` in conjunctive normal form EXAMPLES: @@ -960,9 +920,7 @@ def convert_cnf_recur(self): r""" Convert boolean formula to conjunctive normal form. - OUTPUT: - - An instance of :class:`BooleanFormula` in conjunctive normal form. + OUTPUT: an instance of :class:`BooleanFormula` in conjunctive normal form EXAMPLES: @@ -995,9 +953,7 @@ def satformat(self): r""" Return the satformat representation of a boolean formula. - OUTPUT: - - The satformat of the formula as a string. + OUTPUT: the satformat of the formula as a string EXAMPLES: @@ -1062,11 +1018,7 @@ def satformat(self): # This function uses the propcalc package to simplify an expression to # its minimal form. # -# INPUT: -# self -- the calling object. -# -# OUTPUT: -# A simplified expression. +# OUTPUT: a simplified expression # # EXAMPLES:: @@ -1132,13 +1084,11 @@ def convert_opt(self, tree): INPUT: - - ``tree`` -- a list; this is a branch of a + - ``tree`` -- list; this is a branch of a parse tree and can only contain the '&', '|' and '~' operators along with variables - OUTPUT: - - A 3-tuple. + OUTPUT: a 3-tuple EXAMPLES: @@ -1184,12 +1134,10 @@ def add_statement(self, other, op): - ``other`` -- instance of :class:`BooleanFormula`; this is the formula on the right of the operator - - ``op`` -- a string; this is the operator used to + - ``op`` -- string; this is the operator used to combine the two formulas - OUTPUT: - - The result as an instance of :class:`BooleanFormula`. + OUTPUT: the result as an instance of :class:`BooleanFormula` EXAMPLES: @@ -1214,15 +1162,13 @@ def get_bit(self, x, c): INPUT: - - ``x`` -- an integer; this is the number from + - ``x`` -- integer; this is the number from which to take the bit - - ``c`` -- an integer; this is the but number to + - ``c`` -- integer; this is the but number to be taken, where 0 is the low order bit - OUTPUT: - - A boolean to be determined as follows: + OUTPUT: a boolean to be determined as follows: - ``True`` if bit ``c`` of ``x`` is 1. @@ -1277,7 +1223,7 @@ def reduce_op(self, tree): INPUT: - - ``tree`` -- a list; this represents a branch + - ``tree`` -- list; this represents a branch of a parse tree OUTPUT: @@ -1326,9 +1272,7 @@ def dist_not(self, tree): - ``tree`` a list; this represents a branch of a parse tree - OUTPUT: - - A new list. + OUTPUT: a new list EXAMPLES: @@ -1365,12 +1309,10 @@ def dist_ors(self, tree): INPUT: - - ``tree`` -- a list; this represents a branch of + - ``tree`` -- list; this represents a branch of a parse tree - OUTPUT: - - A new list. + OUTPUT: a new list EXAMPLES: @@ -1405,12 +1347,10 @@ def to_infix(self, tree): INPUT: - - ``tree`` -- a list; this represents a branch + - ``tree`` -- list; this represents a branch of a parse tree - OUTPUT: - - A new list. + OUTPUT: a new list EXAMPLES: @@ -1475,12 +1415,10 @@ def get_next_op(self, str): INPUT: - - ``str`` -- a string; this contains a logical + - ``str`` -- string; this contains a logical expression - OUTPUT: - - The next operator as a string. + OUTPUT: the next operator as a string EXAMPLES: diff --git a/src/sage/logic/logic.py b/src/sage/logic/logic.py index 058da0ff633..26d8daab4e7 100644 --- a/src/sage/logic/logic.py +++ b/src/sage/logic/logic.py @@ -61,21 +61,19 @@ class SymbolicLogic: """ def statement(self, s): r""" - Return a token list to be used by other functions in the class + Return a token list to be used by other functions in the class. INPUT: - - ``s`` -- a string containing the logic expression to be manipulated + - ``s`` -- string containing the logic expression to be manipulated - - ``global vars`` -- a dictionary with variable names as keys and the + - ``global vars`` -- dictionary with variable names as keys and the variables' current boolean values as dictionary values - - ``global vars_order`` -- a list of the variables in the order + - ``global vars_order`` -- list of the variables in the order that they are found - OUTPUT: - - A list of length three containing the following in this order: + OUTPUT: list of length three containing the following in this order: 1. a list of tokens 2. a dictionary of variable/value pairs @@ -119,13 +117,13 @@ def truthtable(self, statement, start=0, end=-1): INPUT: - - ``statement`` -- a list; it contains the tokens and the two global + - ``statement`` -- list; it contains the tokens and the two global variables vars and vars_order - - ``start`` -- (default: 0) an integer; this represents the row of + - ``start`` -- integer (default: 0); this represents the row of the truth table from which to start - - ``end`` -- (default: -1) an integer; this represents the last row + - ``end`` -- integer (default: -1); this represents the last row of the truth table to be created OUTPUT: @@ -206,9 +204,7 @@ def print_table(self, table): - ``table`` -- object created by :meth:`truthtable()` method; it contains the variable values and the evaluation of the statement - OUTPUT: - - A formatted version of the truth table. + OUTPUT: a formatted version of the truth table EXAMPLES: @@ -292,9 +288,7 @@ def combine(self, statement1, statement2): - ``statement1`` -- the first statement - ``statement2`` -- the second statement - OUTPUT: - - A new statement which or'd the given statements together. + OUTPUT: a new statement which or'd the given statements together EXAMPLES:: @@ -375,13 +369,11 @@ def get_bit(x, c): INPUT: - - ``x`` -- an integer; this is the number from which to take the bit - - - ``c`` -- an integer; this is the bit number to be taken + - ``x`` -- integer; this is the number from which to take the bit - OUTPUT: + - ``c`` -- integer; this is the bit number to be taken - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if bit ``c`` of ``x`` is 1. @@ -416,11 +408,9 @@ def eval(toks): INPUT: - - ``toks`` -- a list of tokens; this represents a boolean expression - - OUTPUT: + - ``toks`` -- list of tokens; this represents a boolean expression - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if expression evaluates to ``True``. @@ -459,12 +449,10 @@ def eval_ltor_toks(lrtoks): INPUT: - - ``lrtoks`` -- a list of tokens; this represents a part of a boolean + - ``lrtoks`` -- list of tokens; this represents a part of a boolean formula that contains no inner parentheses - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if expression evaluates to ``True``. @@ -498,7 +486,7 @@ def reduce_bins(lrtoks): INPUT: - - ``lrtoks`` -- a list of tokens; this represents a part of a boolean + - ``lrtoks`` -- list of tokens; this represents a part of a boolean formula that contains no inner parentheses or monotonic operators OUTPUT: @@ -536,7 +524,7 @@ def reduce_monos(lrtoks): INPUT: - - ``lrtoks`` -- a list of tokens; this represents a part of a boolean + - ``lrtoks`` -- list of tokens; this represents a part of a boolean expression that contains now inner parentheses OUTPUT: @@ -573,12 +561,10 @@ def eval_mon_op(args): INPUT: - - ``args`` -- a list of length 2; this contains the token 'NOT' and + - ``args`` -- list of length 2; this contains the token 'NOT' and then a variable name - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` if the variable in ``args`` is ``False``. @@ -611,7 +597,7 @@ def eval_bin_op(args): INPUT: - - ``args`` -- a list of length 3; this contains a variable name, + - ``args`` -- list of length 3; this contains a variable name, then a binary operator, and then a variable name, in that order OUTPUT: @@ -663,15 +649,13 @@ def eval_and_op(lval, rval): INPUT: - - ``lval`` -- a string; this represents the value of the variable + - ``lval`` -- string; this represents the value of the variable appearing to the left of the 'and' operator - - ``rval`` -- a string; this represents the value of the variable + - ``rval`` -- string; this represents the value of the variable appearing to the right of the 'and' operator - OUTPUT: - - The result of applying 'and' to ``lval`` and ``rval`` as a string. + OUTPUT: the result of applying 'and' to ``lval`` and ``rval`` as a string .. NOTE:: @@ -697,15 +681,13 @@ def eval_or_op(lval, rval): INPUT: - - ``lval`` -- a string; this represents the value of the variable + - ``lval`` -- string; this represents the value of the variable appearing to the left of the 'or' operator - - ``rval`` -- a string; this represents the value of the variable + - ``rval`` -- string; this represents the value of the variable appearing to the right of the 'or' operator - OUTPUT: - - A string representing the result of applying 'or' to ``lval`` and ``rval``. + OUTPUT: string representing the result of applying 'or' to ``lval`` and ``rval`` .. NOTE:: @@ -731,10 +713,10 @@ def eval_ifthen_op(lval, rval): INPUT: - - ``lval`` -- a string; this represents the value of the variable + - ``lval`` -- string; this represents the value of the variable appearing to the left of the 'if then' operator - - ``rval`` -- a string;t his represents the value of the variable + - ``rval`` -- string; this represents the value of the variable appearing to the right of the 'if then' operator OUTPUT: @@ -766,10 +748,10 @@ def eval_iff_op(lval, rval): INPUT: - - ``lval`` -- a string; this represents the value of the variable + - ``lval`` -- string; this represents the value of the variable appearing to the left of the 'if and only if' operator - - ``rval`` -- a string; this represents the value of the variable + - ``rval`` -- string; this represents the value of the variable appearing to the right of the 'if and only if' operator OUTPUT: @@ -801,13 +783,11 @@ def tokenize(s, toks): INPUT: - - ``s`` -- a string; this contains a boolean expression + - ``s`` -- string; this contains a boolean expression - - ``toks`` -- a list; this will be populated with the tokens of ``s`` - - OUTPUT: + - ``toks`` -- list; this will be populated with the tokens of ``s`` - ``None``; the tokens of ``s`` are placed in ``toks``. + OUTPUT: none; the tokens of ``s`` are placed in ``toks`` .. NOTE:: diff --git a/src/sage/logic/logicparser.py b/src/sage/logic/logicparser.py index e3d74f512e1..c5431091a68 100644 --- a/src/sage/logic/logicparser.py +++ b/src/sage/logic/logicparser.py @@ -98,7 +98,7 @@ def parse(s): INPUT: - - ``s`` -- a string containing a boolean formula + - ``s`` -- string containing a boolean formula OUTPUT: @@ -133,11 +133,9 @@ def polish_parse(s): INPUT: - - ``s`` -- a string containing a boolean expression + - ``s`` -- string containing a boolean expression - OUTPUT: - - The full syntax parse tree as a nested list. + OUTPUT: the full syntax parse tree as a nested list EXAMPLES: @@ -173,9 +171,7 @@ def get_trees(*statements): - ``*statements`` -- strings or :class:`BooleanFormula` instances - OUTPUT: - - The parse trees in a list. + OUTPUT: the parse trees in a list EXAMPLES: @@ -229,12 +225,10 @@ def recover_formula(prefix_tree): INPUT: - - ``prefix_tree`` -- a list; this is a full syntax parse + - ``prefix_tree`` -- list; this is a full syntax parse tree in prefix form - OUTPUT: - - The formula as a string. + OUTPUT: the formula as a string EXAMPLES: @@ -284,12 +278,10 @@ def recover_formula_internal(prefix_tree): INPUT: - - ``prefix_tree`` -- a list; this is a simple tree + - ``prefix_tree`` -- list; this is a simple tree with at most one operator in prefix form - OUTPUT: - - The formula as a string. + OUTPUT: the formula as a string EXAMPLES: @@ -350,12 +342,10 @@ def prefix_to_infix(prefix_tree): INPUT: - - ``prefix_tree`` -- a list; this is a full syntax parse + - ``prefix_tree`` -- list; this is a full syntax parse tree in prefix form - OUTPUT: - - A list containing the tree in infix form. + OUTPUT: list containing the tree in infix form EXAMPLES: @@ -394,12 +384,10 @@ def to_infix_internal(prefix_tree): INPUT: - - ``prefix_tree`` -- a list; this is a simple parse tree + - ``prefix_tree`` -- list; this is a simple parse tree in prefix form with at most one operator - OUTPUT: - - The tree in infix form as a list. + OUTPUT: the tree in infix form as a list EXAMPLES: @@ -445,7 +433,7 @@ def tokenize(s): INPUT: - - ``s`` -- a string representation of a boolean formula + - ``s`` -- string representation of a boolean formula OUTPUT: @@ -527,9 +515,9 @@ def tree_parse(toks, polish=False): INPUT: - - ``toks`` -- a list of tokens from a boolean formula + - ``toks`` -- list of tokens from a boolean formula - - ``polish`` -- (default: ``False``) a boolean; when ``True``, + - ``polish`` -- boolean (default: ``False``); when ``True``, :func:`~sage.logic.logicparser.tree_parse()` will return the full syntax parse tree @@ -584,18 +572,16 @@ def parse_ltor(toks, n=0, polish=False): INPUT: - - ``toks`` -- a list of tokens. Each token is atomic. + - ``toks`` -- list of tokens; each token is atomic - - ``n`` -- (default: 0) an integer representing which order of + - ``n`` -- integer (default: 0) representing which order of operations are occurring - - ``polish`` -- (default: ``False``) a boolean; when ``True``, double + - ``polish`` -- boolean (default: ``False``); when ``True``, double negations are not cancelled and negated statements are turned into - list of length two. + list of length two - OUTPUT: - - The parse tree as a nested list that depends on ``polish`` as follows: + OUTPUT: the parse tree as a nested list that depends on ``polish`` as follows: - If ``False``, then return a simplified parse tree. @@ -675,9 +661,7 @@ def apply_func(tree, func): - ``func`` -- a function to be applied to each node of tree; this may be a function that comes from elsewhere in the logic module - OUTPUT: - - The new parse tree in the form of a nested list. + OUTPUT: the new parse tree in the form of a nested list EXAMPLES: diff --git a/src/sage/logic/logictable.py b/src/sage/logic/logictable.py index 90107513a0b..d317c31d5c9 100644 --- a/src/sage/logic/logictable.py +++ b/src/sage/logic/logictable.py @@ -130,7 +130,7 @@ class Truthtable: - ``t`` -- a 2-D array containing the table values - - ``vo`` -- a list of the variables in the expression in order, + - ``vo`` -- list of the variables in the expression in order, with each variable occurring only once """ def __init__(self, t, vo): @@ -163,9 +163,7 @@ def _latex_(self): r""" Return a latex representation of the calling table object. - OUTPUT: - - The latex representation of the table. + OUTPUT: the latex representation of the table EXAMPLES: @@ -203,9 +201,7 @@ def __repr__(self): r""" Return a string representation of the calling table object. - OUTPUT: - - The table as a 2-D string array. + OUTPUT: the table as a 2-D string array EXAMPLES: @@ -260,9 +256,7 @@ def get_table_list(self): r""" Return a list representation of the calling table object. - OUTPUT: - - A list representation of the table. + OUTPUT: list representation of the table EXAMPLES: @@ -272,7 +266,6 @@ def get_table_list(self): sage: s = propcalc.formula("man->monkey&human") sage: s.truthtable().get_table_list() [['man', 'monkey', 'human'], [False, False, False, True], [False, False, True, True], [False, True, False, True], [False, True, True, True], [True, False, False, False], [True, False, True, False], [True, True, False, False], [True, True, True, True]] - """ t = self.__table[:] t.insert(0, self.__vars_order) diff --git a/src/sage/logic/propcalc.py b/src/sage/logic/propcalc.py index 830185d6156..2ef5a88b3c2 100644 --- a/src/sage/logic/propcalc.py +++ b/src/sage/logic/propcalc.py @@ -154,11 +154,9 @@ def formula(s): INPUT: - - ``s`` -- a string that contains a logical expression + - ``s`` -- string that contains a logical expression - OUTPUT: - - An instance of :class:`BooleanFormula`. + OUTPUT: an instance of :class:`BooleanFormula` EXAMPLES: @@ -201,9 +199,7 @@ def get_formulas(*statements): full syntax parse tree of a formula, and a string must be a string representation of a formula - OUTPUT: - - The converted formulas in a list. + OUTPUT: the converted formulas in a list EXAMPLES: @@ -271,9 +267,7 @@ def consistent(*formulas): - ``*formulas`` -- instances of :class:`BooleanFormula` - OUTPUT: - - A boolean value to be determined as follows: + OUTPUT: a boolean value to be determined as follows: - ``True`` -- if the formulas are logically consistent diff --git a/src/sage/manifolds/calculus_method.py b/src/sage/manifolds/calculus_method.py index 859301365bf..e4a217bbbab 100644 --- a/src/sage/manifolds/calculus_method.py +++ b/src/sage/manifolds/calculus_method.py @@ -46,9 +46,7 @@ def _SR_to_Sympy(expression): - ``expression`` -- ``SR`` or ``sympy`` symbolic expression - OUTPUT: - - - ``expression`` -- ``sympy`` symbolic expression + OUTPUT: ``expression`` -- ``sympy`` symbolic expression EXAMPLES:: @@ -66,7 +64,6 @@ def _SR_to_Sympy(expression): sage: _SR_to_Sympy(b) is b True - """ # Nothing to do if expression is already a SymPy object: if isinstance(expression, sympy.Basic): @@ -84,9 +81,7 @@ def _Sympy_to_SR(expression): - ``expression`` -- ``sympy`` symbolic expression - OUTPUT: - - - ``expression`` -- ``SR`` or ``sympy`` symbolic expression + OUTPUT: ``expression`` -- ``SR`` or ``sympy`` symbolic expression EXAMPLES:: @@ -102,7 +97,6 @@ def _Sympy_to_SR(expression): x^2 + sin(x)^2 == x^2 + sin(x)^2 sage: bool(_) True - """ try: return SR(expression) @@ -175,7 +169,6 @@ class CalculusMethod(SageObject): See :meth:`simplify_function` for the default simplification algorithms associated with each calculus method and :meth:`set_simplify_function` for introducing a new simplification algorithm. - """ _default = 'SR' # default calculus method _methods = ('SR', 'sympy') # implemented methods @@ -183,7 +176,7 @@ class CalculusMethod(SageObject): def __init__(self, current=None, base_field_type='real'): r""" - Initializes ``self``. + Initialize ``self``. TESTS:: @@ -193,7 +186,6 @@ def __init__(self, current=None, base_field_type='real'): Available calculus methods (* = current): - SR (default) (*) - sympy - """ self._current = self._default if current is None else current # Initialization of the dictionary of simplifying functions: @@ -222,11 +214,9 @@ def simplify(self, expression, method=None): - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - ``'sympy'``: SymPy - - ``None``: the current calculus method of ``self`` is used. - - OUTPUT: + - ``None``: the current calculus method of ``self`` is used - - the simplified version of ``expression`` + OUTPUT: the simplified version of ``expression`` EXAMPLES:: @@ -273,7 +263,6 @@ def simplify(self, expression, method=None): sage: cm.simplify(f, method='SR') x^2 + 1 - """ if method is None: method = self._current @@ -289,11 +278,9 @@ def is_trivial_zero(self, expression, method=None): - ``expression`` -- expression - ``method`` -- (default: ``None``) string defining the calculus method - to use; if ``None`` the current calculus method of ``self`` is used. - - OUTPUT: + to use; if ``None`` the current calculus method of ``self`` is used - - ``True`` is expression is trivially zero, ``False`` elsewhere. + OUTPUT: ``True`` is expression is trivially zero, ``False`` elsewhere EXAMPLES:: @@ -312,7 +299,6 @@ def is_trivial_zero(self, expression, method=None): False sage: cm.is_trivial_zero(f._sympy_(), method='sympy') False - """ if method is None: method = self._current @@ -347,7 +333,6 @@ def set(self, method): Traceback (most recent call last): ... NotImplementedError: method lala not implemented - """ if method not in self._methods: raise NotImplementedError("method {} not ".format(method) + @@ -360,10 +345,10 @@ def current(self): OUTPUT: - - string defining the calculus method, one of + String defining the calculus method; one of - - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - - ``'sympy'``: SymPy + - ``'SR'`` -- Sage's default symbolic engine (Symbolic Ring) + - ``'sympy'`` -- SymPy EXAMPLES:: @@ -377,7 +362,6 @@ def current(self): sage: cm.set('sympy') sage: cm.current() 'sympy' - """ return self._current @@ -441,7 +425,6 @@ def set_simplify_function(self, simplifying_func, method=None): sage: cm.simplify_function() is \ ....: sage.manifolds.utilities.simplify_chain_real True - """ if method is None: method = self._current @@ -468,9 +451,7 @@ def simplify_function(self, method=None): - ``None``: the currently active calculus method of ``self`` is assumed - OUTPUT: - - - the simplifying function + OUTPUT: the simplifying function EXAMPLES:: @@ -519,7 +500,6 @@ def simplify_function(self, method=None): Note that the simplifying functions can be customized via :meth:`set_simplify_function`. - """ if method is None: method = self._current @@ -547,7 +527,6 @@ def reset(self): Available calculus methods (* = current): - SR (default) (*) - sympy - """ self._current = self._default @@ -561,7 +540,6 @@ def _repr_(self): sage: cm = CalculusMethod(base_field_type='complex') sage: cm._repr_() 'Available calculus methods (* = current):\n - SR (default) (*)\n - sympy' - """ resu = 'Available calculus methods (* = current):\n' for method in self._methods: diff --git a/src/sage/manifolds/catalog.py b/src/sage/manifolds/catalog.py index 91b0997de7b..0cbd69b6768 100644 --- a/src/sage/manifolds/catalog.py +++ b/src/sage/manifolds/catalog.py @@ -54,7 +54,7 @@ def Minkowski(positive_spacelike=True, names=None): INPUT: - - ``positive_spacelike`` -- (default: ``True``) if ``False``, then + - ``positive_spacelike`` -- boolean (default: ``True``); if ``False``, then the spacelike vectors yield a negative sign (i.e., the signature is `(+ - - - )`) - ``names`` -- (default: ``None``) name of the coordinates, @@ -93,7 +93,7 @@ def Minkowski(positive_spacelike=True, names=None): g[1,1], g[2,2], g[3,3] = sgn, sgn, sgn return M -def Kerr(m=1, a=0, coordinates="BL", names=None): +def Kerr(m=1, a=0, coordinates='BL', names=None): """ Generate a Kerr spacetime. @@ -109,15 +109,13 @@ def Kerr(m=1, a=0, coordinates="BL", names=None): (`c=1`, `G=1`) - ``a`` -- (default: ``0``) angular momentum in natural units; if set to ``0``, the resulting spacetime corresponds to a Schwarzschild black hole - - ``coordinates`` -- (default: ``"BL"``) either ``"BL"`` for - Boyer-Lindquist coordinates or ``"Kerr"`` for Kerr coordinates (3+1 + - ``coordinates`` -- (default: ``'BL'``) either ``'BL'`` for + Boyer-Lindquist coordinates or ``'Kerr'`` for Kerr coordinates (3+1 version) - ``names`` -- (default: ``None``) name of the coordinates, automatically set by the shortcut operator - OUTPUT: - - - Lorentzian manifold + OUTPUT: Lorentzian manifold EXAMPLES:: @@ -153,7 +151,7 @@ def Kerr(m=1, a=0, coordinates="BL", names=None): The Kerr spacetime in Kerr coordinates:: sage: m, a = var('m, a') - sage: K. = manifolds.Kerr(m, a, coordinates="Kerr") + sage: K. = manifolds.Kerr(m, a, coordinates='Kerr') sage: K 4-dimensional Lorentzian manifold M sage: K.atlas() @@ -176,7 +174,7 @@ def Kerr(m=1, a=0, coordinates="BL", names=None): from sage.misc.functional import sqrt from sage.functions.trig import cos, sin from sage.manifolds.manifold import Manifold - M = Manifold(4, 'M', structure="Lorentzian") + M = Manifold(4, 'M', structure='Lorentzian') if coordinates == "Kerr": if names is None: names = (r't:(-oo,+oo)', r'r:(0,+oo)', r'th:(0,pi):\theta', @@ -233,9 +231,7 @@ def Torus(R=2, r=1, names=None): - ``names`` -- (default: ``None``) name of the coordinates, automatically set by the shortcut operator - OUTPUT: - - - Riemannian manifold + OUTPUT: Riemannian manifold EXAMPLES:: @@ -257,7 +253,7 @@ def Torus(R=2, r=1, names=None): from sage.manifolds.manifold import Manifold from sage.manifolds.differentiable.examples.euclidean import EuclideanSpace E = EuclideanSpace(3, symbols='X Y Z') - M = Manifold(2, 'T', ambient=E, structure="Riemannian") + M = Manifold(2, 'T', ambient=E, structure='Riemannian') if names is None: names = ("th", "ph") names = tuple([names[i] + ":(-pi,pi):periodic" for i in range(2)]) @@ -278,16 +274,14 @@ def RealProjectiveSpace(dim=2): This is the topological space of lines through the origin in `\RR^{d+1}`. The standard atlas consists of `d+2` charts, which sends the set `U_i = \{[x_1, x_2, \ldots, x_{d+1}] : x_i \neq 0 \}` to - `k^{d}` by dividing by `x_i` and omitting the `i`th coordinate + `k^{d}` by dividing by `x_i` and omitting the `i`-th coordinate `x_i/x_i = 1`. INPUT: - ``dim`` -- (default: ``2``) the dimension of projective space - OUTPUT: - - - ``P`` -- the projective space `\Bold{RP}^d` where `d =` ``dim``. + OUTPUT: ``P`` -- the projective space `\Bold{RP}^d` where `d =` ``dim`` EXAMPLES:: @@ -356,7 +350,6 @@ def RealProjectiveSpace(dim=2): False sage: C0(p) (1/3,) - """ from sage.manifolds.manifold import Manifold diff --git a/src/sage/manifolds/chart.py b/src/sage/manifolds/chart.py index acb88bf241a..86c3087d101 100644 --- a/src/sage/manifolds/chart.py +++ b/src/sage/manifolds/chart.py @@ -96,7 +96,7 @@ class Chart(UniqueRepresentation, SageObject): ``coordinates`` is not provided; it must then be a tuple containing the coordinate symbols (this is guaranteed if the shortcut operator ``<,>`` is used) - - ``coord_restrictions``: Additional restrictions on the coordinates. + - ``coord_restrictions`` -- additional restrictions on the coordinates. A restriction can be any symbolic equality or inequality involving the coordinates, such as ``x > y`` or ``x^2 + y^2 != 0``. The items of the list (or set or frozenset) ``coord_restrictions`` are combined @@ -284,7 +284,6 @@ class Chart(UniqueRepresentation, SageObject): :class:`sage.manifolds.chart.RealChart` for charts on topological manifolds over `\RR`. - """ @staticmethod @@ -353,7 +352,6 @@ def __init__(self, domain, coordinates, calc_method=None, periods=None, sage: XV = V.chart('x y') sage: M.top_charts() [Chart (U, (x, y)), Chart (V, (x, y))] - """ from sage.manifolds.manifold import TopologicalManifold if not isinstance(domain, TopologicalManifold): @@ -430,7 +428,7 @@ def _parse_coordinates(cls, domain, coordinates): - a tuple of variables (as elements of ``SR``) - a dictionary with possible keys: - - ``"periods"``: a tuple of periods + - ``'periods'`` -- a tuple of periods TESTS:: @@ -490,7 +488,6 @@ def _normalize_coord_restrictions(coordinates, coord_restrictions): frozenset({(x != 0, y != 0)}) sage: Chart._normalize_coord_restrictions(coordinates, [x > y, (x != 0, y != 0), z^2 < x]) frozenset({(x != 0, y != 0), x > y, z^2 < x}) - """ def normalize(r): if isinstance(r, tuple): # or @@ -524,7 +521,6 @@ def _repr_(self): sage: X. = M.chart() sage: X Chart (M, (x, y)) - """ return 'Chart ({}, {})'.format(self.domain()._name, self._xx) @@ -543,7 +539,6 @@ def _latex_(self): '\\left(M,({\\zeta_1}, {\\zeta2})\\right)' sage: latex(Y) \left(M,({\zeta_1}, {\zeta2})\right) - """ description = r'\left(' + latex(self.domain()).strip() + ',(' n = len(self._xx) @@ -560,7 +555,6 @@ def _first_ngens(self, n): sage: preparse("c_cart. = M.chart()") "c_cart = M.chart(names=('x', 'y', 'z',)); (x, y, z,) = c_cart._first_ngens(3)" - """ return self[:] @@ -625,9 +619,7 @@ def __call__(self, point): - ``point`` -- point in the domain of the chart - OUTPUT: - - - tuple of the coordinates of the point + OUTPUT: tuple of the coordinates of the point EXAMPLES:: @@ -638,7 +630,6 @@ def __call__(self, point): (I + 1, -I + 2) sage: X(M.an_element()) (0, 0) - """ return point.coord(self) @@ -656,7 +647,6 @@ def domain(self): sage: Y. = U.chart() sage: Y.domain() Open subset U of the 2-dimensional topological manifold M - """ return self._domain @@ -673,7 +663,6 @@ def manifold(self): 2-dimensional topological manifold M sage: X.domain() Open subset U of the 2-dimensional topological manifold M - """ return self._manifold @@ -718,7 +707,6 @@ def periods(self): sage: X. = M.chart(r"xq:period=3/2 yq:\zeta:period=2") sage: X.periods() (3/2, 2) - """ return self._periods @@ -762,7 +750,6 @@ def add_restrictions(self, restrictions): True sage: X.valid_coordinates(i, 1) False - """ from sage.misc.superseded import deprecation deprecation(32102, "Chart.add_restrictions is deprecated; provide the restrictions at the time of creating the chart") @@ -815,7 +802,6 @@ def restrict(self, subset, restrictions=None): sage: B = M.open_subset('B') sage: X_B = X.restrict(B, abs(z1)^2 + abs(z2)^2 < 1); X_B Chart (B, (z1, z2)) - """ if subset == self.domain(): return self @@ -887,7 +873,6 @@ def valid_coordinates(self, *coordinates, **kwds): True sage: Y.valid_coordinates(1, 2*i, parameters={a: 2}) False - """ if len(coordinates) != self.domain()._dim: return False @@ -910,15 +895,13 @@ def _check_restrictions(self, restrict, substitutions): INPUT: - - restrict: a tuple of conditions (combined with 'or'), a list of + - ``restrict`` -- a tuple of conditions (combined with 'or'), a list of conditions (combined with 'and') or a single coordinate condition - - substitutions: dictionary (keys: coordinates of ``self``) giving the + - ``substitutions`` -- dictionary (keys: coordinates of ``self``) giving the value of each coordinate - OUTPUT: - - - boolean stating whether the conditions are fulfilled by the - coordinate values + OUTPUT: boolean stating whether the conditions are fulfilled by the + coordinate values TESTS:: @@ -942,7 +925,6 @@ def _check_restrictions(self, restrict, substitutions): True sage: X._check_restrictions([(x0], {x: 2, y: 1}) False - """ if isinstance(restrict, tuple): # case of 'or' conditions return any(self._check_restrictions(cond, substitutions) @@ -963,7 +945,6 @@ def codomain(self): sage: X. = M.chart() sage: X.codomain() Vector space of dimension 2 over Complex Field with 53 bits of precision - """ from sage.modules.free_module import VectorSpace ambient = VectorSpace(self.manifold().base_field(), self.manifold().dimension()) @@ -1118,7 +1099,6 @@ def transition_map(self, other, transformations, intersection_name=None, sage: M.atlas() [Chart (R^2, (x, y)), Chart (U, (r, phi)), Chart (U, (x, y))] - """ dom1 = self.domain() dom2 = other.domain() @@ -1149,7 +1129,7 @@ def preimage(self, codomain_subset, name=None, latex_name=None): object with a ``__contains__`` method that accepts coordinate vectors - ``name`` -- string; name (symbol) given to the subset - - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to + - ``latex_name`` -- string (default: ``None``); LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` OUTPUT: @@ -1279,7 +1259,7 @@ def function(self, expression, calc_method=None, expansion_symbol=None, - ``expression`` -- a symbolic expression involving the chart coordinates, to represent `f(x^1,\ldots, x^n)` - - ``calc_method`` -- string (default: ``None``): the calculus method + - ``calc_method`` -- string (default: ``None``); the calculus method with respect to which the internal expression of the function must be initialized from ``expression``; one of @@ -1336,7 +1316,6 @@ def function(self, expression, calc_method=None, expansion_symbol=None, {'SR': sin(x*y)} See :class:`~sage.manifolds.chart_func.ChartFunction` for more examples. - """ parent = self.function_ring() return parent.element_class(parent, expression, calc_method=calc_method, @@ -1383,7 +1362,7 @@ def zero_function(self): sage: X.zero_function() is X.zero_function() True - Zero function on a p-adic manifold:: + Zero function on a `p`-adic manifold:: sage: # needs sage.rings.padics sage: M = Manifold(2, 'M', structure='topological', field=Qp(5)); M @@ -1394,7 +1373,6 @@ def zero_function(self): 0 sage: X.zero_function().display() (x, y) ↦ 0 - """ return self.function_ring().zero() @@ -1438,7 +1416,7 @@ def one_function(self): sage: X.one_function() is X.one_function() True - One function on a p-adic manifold:: + One function on a `p`-adic manifold:: sage: # needs sage.rings.padics sage: M = Manifold(2, 'M', structure='topological', field=Qp(5)); M @@ -1449,7 +1427,6 @@ def one_function(self): 1 + O(5^20) sage: X.one_function().display() (x, y) ↦ 1 + O(5^20) - """ return self.function_ring().one() @@ -1469,9 +1446,7 @@ def calculus_method(self): :class:`~sage.manifolds.calculus_method.CalculusMethod` for a complete documentation. - OUTPUT: - - - an instance of :class:`~sage.manifolds.calculus_method.CalculusMethod` + OUTPUT: an instance of :class:`~sage.manifolds.calculus_method.CalculusMethod` EXAMPLES: @@ -1515,7 +1490,6 @@ def calculus_method(self): sage: X.calculus_method().set('SR') sage: f.display() (x, y) ↦ x^2 + cos(y)*sin(x) - """ return self._calc_method @@ -1571,7 +1545,6 @@ def multifunction(self, *expressions): sage: type(f) - """ from sage.manifolds.chart_func import MultiCoordFunction return MultiCoordFunction(self, expressions) @@ -1635,7 +1608,7 @@ class RealChart(Chart): ``coordinates`` is not provided; it must then be a tuple containing the coordinate symbols (this is guaranteed if the shortcut operator ``<,>`` is used) - - ``coord_restrictions``: Additional restrictions on the coordinates. + - ``coord_restrictions`` -- additional restrictions on the coordinates. A restriction can be any symbolic equality or inequality involving the coordinates, such as ``x > y`` or ``x^2 + y^2 != 0``. The items of the list (or set or frozenset) ``coord_restrictions`` are combined @@ -1857,7 +1830,6 @@ class RealChart(Chart): Chart grids can be drawn in 2D or 3D graphics thanks to the method :meth:`plot`. - """ def __init__(self, domain, coordinates, calc_method=None, bounds=None, periods=None, coord_restrictions=None): @@ -1876,7 +1848,6 @@ def __init__(self, domain, coordinates, calc_method=None, bounds=None, sage: assumptions() # assumptions set in X._init_coordinates [x is real, y is real] sage: TestSuite(X).run() - """ super().__init__(domain, coordinates, calc_method=calc_method, periods=periods, coord_restrictions=coord_restrictions) @@ -1906,8 +1877,8 @@ def _parse_coordinates(cls, domain, coordinates): - a tuple of variables (as elements of ``SR``) - a dictionary with possible keys: - - ``"periods"``: a tuple of periods - - ``"bounds"``: a tuple of coordinate ranges + - ``'periods'`` -- a tuple of periods + - ``'bounds'`` -- a tuple of coordinate ranges TESTS:: @@ -2050,7 +2021,6 @@ def coord_bounds(self, i=None): [x is real] sage: assumptions(y) [y is real, y >= 0, y < 1] - """ if i is None: return self._bounds @@ -2134,7 +2104,6 @@ def coord_range(self, xx=None): sage: latex(XU.coord_range(y)) y :\ \left( -\infty, \pi \right) - """ from sage.tensor.modules.format_utilities import FormattedExpansion @@ -2252,14 +2221,13 @@ def add_restrictions(self, restrictions): sage: X_U.add_restrictions([x<0, y>1/2]) sage: X_U.coord_range() x: (-oo, 0); y: (1/2, +oo) - """ super().add_restrictions(restrictions) self._tighten_bounds() def _tighten_bounds(self): """ - Update coordinate bounds from the coordinate restrictions + Update coordinate bounds from the coordinate restrictions. EXAMPLES:: @@ -2269,7 +2237,6 @@ def _tighten_bounds(self): sage: X_U = X.restrict(U, restrictions=[x<0, y>1/2]) sage: X_U.coord_range() x: (-oo, 0); y: (1/2, +oo) - """ import operator bounds = list(self._bounds) # convert to a list for modifications @@ -2395,7 +2362,6 @@ def restrict(self, subset, restrictions=None): x: (0, 1); y: [0, 2] (periodic) sage: XU.periods() (None, 2) - """ if subset == self.domain(): return self @@ -2439,7 +2405,6 @@ def valid_coordinates(self, *coordinates, **kwds): coordinate ranges - ``parameters=None``, to set some numerical values to parameters - OUTPUT: - ``True`` if the coordinate values are admissible in the chart range @@ -2485,7 +2450,6 @@ def valid_coordinates(self, *coordinates, **kwds): False sage: XB.valid_coordinates(3/2, 1/2) True - """ n = len(coordinates) if n != self._manifold._dim: @@ -2584,7 +2548,6 @@ def valid_coordinates_numerical(self, *coordinates): False sage: XB.valid_coordinates_numerical(3/2, 1/2) True - """ # case fast callable already computed if self._fast_valid_coordinates is not None: @@ -2740,7 +2703,7 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, representing the number of points to plot the lines along which the coordinate varies, the other being kept constant; if ``plot_points`` is a single integer, it is used for all coordinate lines - - ``label_axes`` -- (default: ``True``) boolean determining whether the + - ``label_axes`` -- boolean (default: ``True``); determining whether the labels of the ambient coordinate axes shall be added to the graph; can be set to ``False`` if the graph is 3D and must be superposed with another graph @@ -3039,7 +3002,6 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, To restore the original default options, it suffices to type:: sage: X.plot.reset() - """ from sage.misc.functional import numerical_approx from sage.plot.graphics import Graphics @@ -3349,7 +3311,6 @@ class CoordChange(SageObject): sage: X_to_Y.display() u = x + y v = x - y - """ def __init__(self, chart1, chart2, *transformations): r""" @@ -3366,7 +3327,6 @@ def __init__(self, chart1, chart2, *transformations): sage: type(X_to_Y) sage: TestSuite(X_to_Y).run() - """ self._n1 = len(chart1._xx) self._n2 = len(chart2._xx) @@ -3402,7 +3362,6 @@ def _repr_(self): 'Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v))' sage: X_to_Y # indirect doctest Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v)) - """ return "Change of coordinates from {} to {}".format(self._chart1, self._chart2) @@ -3421,7 +3380,6 @@ def _latex_(self): \left(M,(x, y)\right) \rightarrow \left(M,(u, v)\right) sage: latex(X_to_Y) # indirect doctest \left(M,(x, y)\right) \rightarrow \left(M,(u, v)\right) - """ return latex(self._chart1) + r' \rightarrow ' + latex(self._chart2) @@ -3447,7 +3405,6 @@ def __eq__(self, other): sage: X_to_Z = X.transition_map(Z, [x+y, x-y]) sage: X_to_Y == X_to_Z False - """ if other is self: return True @@ -3470,7 +3427,6 @@ def __ne__(self, other): sage: X_to_Y2 = X.transition_map(Y, [2*y, -x]) sage: X_to_Y != X_to_Y2 True - """ return not (self == other) @@ -3482,9 +3438,7 @@ def __call__(self, *coords): - ``coords`` -- values of coordinates of ``chart1`` - OUTPUT: - - - tuple of values of coordinates of ``chart2`` + OUTPUT: tuple of values of coordinates of ``chart2`` EXAMPLES:: @@ -3494,7 +3448,6 @@ def __call__(self, *coords): sage: X_to_Y = X.transition_map(Y, [x+y, x-y]) sage: X_to_Y(1,2) (3, -1) - """ return self._transf(*coords) @@ -3546,7 +3499,6 @@ def inverse(self): sage: uv_to_xy.inverse() is xy_to_uv True - """ from sage.symbolic.relation import solve if self._inverse is not None: @@ -3631,7 +3583,7 @@ def inverse(self): def set_inverse(self, *transformations, **kwds): r""" - Sets the inverse of the coordinate transformation. + Set the inverse of the coordinate transformation. This is useful when the automatic computation via :meth:`inverse()` fails. @@ -3643,10 +3595,10 @@ def set_inverse(self, *transformations, **kwds): "new" ones - ``kwds`` -- optional arguments; valid keywords are - - ``check`` (default: ``True``) -- boolean determining whether the + - ``check`` -- boolean (default: ``True``); whether the provided transformations are checked to be indeed the inverse coordinate transformations - - ``verbose`` (default: ``False``) -- boolean determining whether + - ``verbose`` -- boolean (default: ``False``); whether some details of the check are printed out; if ``False``, no output is printed if the check is passed (see example below) @@ -3736,7 +3688,6 @@ def set_inverse(self, *transformations, **kwds): Traceback (most recent call last): ... TypeError: bla is not a valid keyword argument - """ check = kwds.pop('check', True) verbose = kwds.pop('verbose', False) @@ -3803,7 +3754,6 @@ def __mul__(self, other): sage: X_to_W.display() w = 1/2*cos(x)*cos(y) - 1/2*sin(x)*sin(y) + x + y z = -1/2*cos(y)*sin(x) + 1/2*cos(x)*sin(y) + x - y - """ if not isinstance(other, CoordChange): raise TypeError("{} is not a change of coordinate".format(other)) @@ -3846,7 +3796,6 @@ def restrict(self, dom1, dom2=None): sage: X_to_Y.restrict(U) is X_to_Y_U True - """ if dom2 is None: dom2 = dom1 @@ -3885,7 +3834,6 @@ def display(self): sage: spher_to_cart.disp() x = r*cos(ph) y = r*sin(ph) - """ from sage.misc.latex import latex from sage.tensor.modules.format_utilities import FormattedExpansion diff --git a/src/sage/manifolds/chart_func.py b/src/sage/manifolds/chart_func.py index 454f6489441..fed078a2baa 100644 --- a/src/sage/manifolds/chart_func.py +++ b/src/sage/manifolds/chart_func.py @@ -85,9 +85,9 @@ class ChartFunction(AlgebraElement, ModuleElementWithMutability): `f(x^1, \ldots, x^n)`, where `(x^1, \ldots, x^n)` are the coordinates of the chart `(U, \varphi)` - - ``calc_method`` -- string (default: ``None``): the calculus method with + - ``calc_method`` -- string (default: ``None``); the calculus method with respect to which the internal expression of ``self`` must be initialized - from ``expression``; one of + from ``expression``. One of - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - ``'sympy'``: SymPy @@ -325,7 +325,6 @@ class ChartFunction(AlgebraElement, ModuleElementWithMutability): u(x, y)*v(x, y) .. automethod:: __call__ - """ def __init__(self, parent, expression=None, calc_method=None, @@ -360,7 +359,6 @@ def __init__(self, parent, expression=None, calc_method=None, sage: g = Y.function(i*z + 2*w); g 2*w + I*z sage: TestSuite(g).run() - """ ModuleElementWithMutability.__init__(self, parent) self._chart = parent._chart @@ -390,9 +388,7 @@ def _simplify(self, expr): - ``expr`` -- expression to simplify - OUTPUT: - - - simplified expression + OUTPUT: simplified expression EXAMPLES: @@ -401,7 +397,6 @@ def _simplify(self, expr): sage: fc = c_xy.function(x+2*y^3) sage: fc._simplify(x+x) 2*x - """ res = self._calc_method.simplify(expr) if (self._expansion_symbol is not None and @@ -413,9 +408,7 @@ def chart(self): r""" Return the chart with respect to which ``self`` is defined. - OUTPUT: - - - a :class:`~sage.manifolds.chart.Chart` + OUTPUT: a :class:`~sage.manifolds.chart.Chart` EXAMPLES:: @@ -426,7 +419,6 @@ def chart(self): Chart (M, (x, y)) sage: f.chart() is X True - """ return self._chart @@ -444,9 +436,7 @@ def scalar_field(self, name=None, latex_name=None): - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the scalar field; if ``None``, the LaTeX symbol is set to ``name`` - OUTPUT: - - - a :class:`~sage.manifolds.scalarfield.ScalarField` + OUTPUT: a :class:`~sage.manifolds.scalarfield.ScalarField` EXAMPLES: @@ -462,7 +452,6 @@ def scalar_field(self, name=None, latex_name=None): (x, y) ↦ 2*y^3 + x sage: f.coord_function(c_xy) is fc True - """ alg = self._chart.domain().scalar_field_algebra() return alg.element_class(alg, @@ -476,8 +465,8 @@ def expr(self, method=None): INPUT: - - ``method`` -- string (default: ``None``): the calculus method which - the returned expression belongs to; one of + - ``method`` -- string (default: ``None``); the calculus method which + the returned expression belongs to. One of - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - ``'sympy'``: SymPy @@ -552,7 +541,6 @@ def expr(self, method=None): 3*a*x sage: bool( f(x,3) == f.expr().subs(y=3) ) True - """ if method is None: method = self._calc_method._current @@ -580,7 +568,6 @@ def set_expr(self, calc_method, expression): - ``expression`` -- symbolic expression - EXAMPLES:: sage: M = Manifold(2, 'M', structure='topological') @@ -599,7 +586,6 @@ def set_expr(self, calc_method, expression): Traceback (most recent call last): ... ValueError: Expressions are not equal - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element cannot " @@ -625,7 +611,6 @@ def _repr_(self): 'x*y + 1' sage: f # indirect doctest x*y + 1 - """ curr = self._calc_method._current if (curr == 'SR' and @@ -647,7 +632,6 @@ def _latex_(self): \cos\left(\frac{1}{2} \, x y\right) sage: latex(f) # indirect doctest \cos\left(\frac{1}{2} \, x y\right) - """ curr = self._calc_method._current if (curr == 'SR' and @@ -686,7 +670,6 @@ def display(self): sage: X.zero_function().display() (x, y) ↦ 0 - """ from sage.typeset.unicode_characters import unicode_mapsto from sage.tensor.modules.format_utilities import FormattedExpansion @@ -756,7 +739,6 @@ def __call__(self, *coords, **options): 1 sage: type(f(pi, 1/2)) - """ if len(coords) != self._nc: raise ValueError("bad number of coordinates") @@ -811,7 +793,6 @@ def __bool__(self): True sage: X.zero_function() == 0 True - """ curr = self._calc_method._current if curr == 'SR': @@ -863,7 +844,6 @@ def is_trivial_zero(self): True sage: f == 0 True - """ curr = self._calc_method._current return self._calc_method.is_trivial_zero(self.expr(curr)) @@ -910,7 +890,6 @@ def is_trivial_one(self): True sage: f == 1 True - """ curr = self._calc_method._current return self._calc_method.is_trivial_zero(self.expr(curr) - SR.one()) @@ -932,7 +911,6 @@ def is_unit(self): sage: zero = X.function(0) sage: zero.is_unit() False - """ return not self.is_trivial_zero() @@ -940,9 +918,7 @@ def copy(self): r""" Return an exact copy of the object. - OUTPUT: - - - a :class:`ChartFunctionSymb` + OUTPUT: a :class:`ChartFunctionSymb` EXAMPLES:: @@ -963,7 +939,6 @@ def copy(self): sage: g is f False - """ resu = type(self)(self.parent()) for kk, vv in self._express.items(): @@ -1048,7 +1023,6 @@ def derivative(self, coord): 2*x sage: f.diff(y) 3 - """ from sage.calculus.functional import diff from sage.rings.integer import Integer @@ -1087,9 +1061,7 @@ def __eq__(self, other): - ``other`` -- a :class:`ChartFunction` or a value - OUTPUT: - - - ``True`` if ``self`` is equal to ``other``, or ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other``, or ``False`` otherwise TESTS: @@ -1121,7 +1093,6 @@ def __eq__(self, other): True sage: X.zero_function() == 0 True - """ if other is self: return True @@ -1165,7 +1136,6 @@ def __ne__(self, other): True sage: f != X.function(x-y) False - """ return not (self == other) @@ -1173,9 +1143,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the opposite of ``self`` + OUTPUT: the opposite of ``self`` TESTS: @@ -1190,7 +1158,6 @@ def __neg__(self): sage: -g == f True - """ curr = self._calc_method._current resu = type(self)(self.parent()) @@ -1208,9 +1175,7 @@ def __invert__(self): chart function `1/f`, where `1` of the multiplicative identity of `K`. - OUTPUT: - - - the inverse of ``self`` + OUTPUT: the inverse of ``self`` TESTS: @@ -1241,7 +1206,6 @@ def __invert__(self): True sage: g.__invert__() == f True - """ curr = self._calc_method._current if curr == 'SR': @@ -1438,7 +1402,6 @@ def _mul_(self, other): 0 sage: (f * (1/f)).expr() 1 - """ curr = self._calc_method._current if other._expansion_symbol is not None: @@ -1482,7 +1445,6 @@ def _rmul_(self, other): pi*(x + y) sage: (x * f).expr() x*(x + y) - """ curr = self._calc_method._current try: @@ -1518,7 +1480,6 @@ def _lmul_(self, other): (x, y) ↦ 2*x + 2*y sage: (f * pi).display() (x, y) ↦ pi*(x + y) - """ curr = self._calc_method._current try: @@ -1578,8 +1539,6 @@ def _div_(self, other): (x, y) ↦ (x + y)/(x**2 + y**2 + 1) sage: (f / g) == ~(g / f) True - - """ if other.is_zero(): raise ZeroDivisionError("division of a chart function by zero") @@ -1627,7 +1586,6 @@ def exp(self): (x, y) ↦ exp(x + y) sage: exp(X.zero_function()) 1 - """ curr = self._calc_method._current if curr == 'SR': @@ -1682,7 +1640,6 @@ def log(self, base=None): log(x + y)/log(2) sage: log(f, 2) log(x + y)/log(2) - """ curr = self._calc_method._current if curr == 'SR': @@ -1740,7 +1697,6 @@ def __pow__(self, exponent): (x, y) ↦ x**3 + 3*x**2*y + 3*x*y**2 + y**3 sage: pow(X.zero_function(), 3).display() (x, y) ↦ 0 - """ curr = self._calc_method._current if curr == 'SR': @@ -1773,7 +1729,6 @@ def sqrt(self): (x, y) ↦ sqrt(x + y) sage: sqrt(X.zero_function()).display() (x, y) ↦ 0 - """ curr = self._calc_method._current if curr == 'SR': @@ -1814,7 +1769,6 @@ def cos(self): cos(x*y) sage: cos(f) # equivalent to f.cos() cos(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -1860,7 +1814,6 @@ def sin(self): sin(x*y) sage: sin(f) # equivalent to f.sin() sin(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -1904,7 +1857,6 @@ def tan(self): tan(x*y) sage: tan(g).display() (x, y) ↦ tan(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -1952,7 +1904,6 @@ def arccos(self): acos(x*y) sage: arccos(f).display() (x, y) ↦ acos(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -1997,7 +1948,6 @@ def arcsin(self): asin(x*y) sage: asin(f) # equivalent to f.arcsin() asin(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2042,7 +1992,6 @@ def arctan(self): atan(x*y) sage: atan(f) # equivalent to f.arctan() atan(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2083,7 +2032,6 @@ def cosh(self): cosh(x*y) sage: cosh(f) # equivalent to f.cosh() cosh(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2124,7 +2072,6 @@ def sinh(self): sinh(x*y) sage: sinh(f) # equivalent to f.sinh() sinh(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2165,7 +2112,6 @@ def tanh(self): tanh(x*y) sage: tanh(f) # equivalent to f.tanh() tanh(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2210,7 +2156,6 @@ def arccosh(self): acosh(x*y) sage: acosh(f) # equivalent to f.arccosh() acosh(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2255,7 +2200,6 @@ def arcsinh(self): asinh(x*y) sage: asinh(f) # equivalent to f.arcsinh() asinh(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2300,7 +2244,6 @@ def arctanh(self): atanh(x*y) sage: atanh(f) # equivalent to f.arctanh() atanh(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2341,7 +2284,6 @@ def __abs__(self): Abs(x*y) sage: abs(f) # equivalent to f.abs() Abs(x*y) - """ curr = self._calc_method._current if curr == 'SR': @@ -2382,7 +2324,6 @@ def _del_derived(self): sage: f._del_derived() sage: f._der - """ self._der = None # reset of the partial derivatives @@ -2402,9 +2343,7 @@ def simplify(self): expression of ``self`` will be expanded in power series of that parameter and truncated to the given order. - OUTPUT: - - - ``self`` with its coordinate expression simplified + OUTPUT: ``self`` with its coordinate expression simplified EXAMPLES: @@ -2504,7 +2443,6 @@ def simplify(self): 1/6*t^3*x^3 + 1/2*t^2*x^2 + t*x + 1 sage: f.display() (x, y) ↦ 1/6*t^3*x^3 + 1/2*t^2*x^2 + t*x + 1 - """ curr = self._calc_method._current self._express[curr] = self._simplify(self.expr(curr)) @@ -2515,9 +2453,7 @@ def factor(self): r""" Factorize the coordinate expression of ``self``. - OUTPUT: - - - ``self`` with its expression factorized + OUTPUT: ``self`` with its expression factorized EXAMPLES: @@ -2544,7 +2480,6 @@ def factor(self): (x, y) ↦ x**2 + 2*x*y + y**2 sage: g.factor() (x + y)**2 - """ curr = self._calc_method._current self._express[curr] = self.expr().factor() @@ -2555,9 +2490,7 @@ def expand(self): r""" Expand the coordinate expression of ``self``. - OUTPUT: - - - ``self`` with its expression expanded + OUTPUT: ``self`` with its expression expanded EXAMPLES: @@ -2582,7 +2515,6 @@ def expand(self): sage: g = X.function((x - y)^2) sage: g.expand() x**2 - 2*x*y + y**2 - """ curr = self._calc_method._current self._express[curr] = self.expr().expand() @@ -2628,7 +2560,6 @@ def collect(self, s): (x, y) ↦ x**2*y**2 + x**2*y + x*y sage: f.collect(y) x**2*y**2 + y*(x**2 + x) - """ curr = self._calc_method._current self._express[curr] = self.expr().collect(s) @@ -2673,7 +2604,6 @@ def collect_common_factors(self): (x, y) ↦ x/(x**2*y + x*y) sage: g.collect_common_factors() 1/(y*(x + 1)) - """ curr = self._calc_method._current if curr == 'sympy': @@ -2720,7 +2650,6 @@ class ChartFunctionRing(Parent, UniqueRepresentation): sage: FR_Y = Y.function_ring() sage: FR_Y.has_coerce_map_from(FR_X) False - """ Element = ChartFunction @@ -2734,7 +2663,6 @@ def __init__(self, chart): sage: X. = M.chart() sage: FR = X.function_ring() sage: TestSuite(FR).run() - """ self._chart = chart Parent.__init__(self, base=SR, category=CommutativeAlgebras(SR)) @@ -2763,7 +2691,6 @@ def _element_constructor_(self, expression, calc_method=None): sage: FR_D = X_D.function_ring() sage: FR_D(f) sin(x*y) - """ if isinstance(expression, ChartFunction): if self._chart in expression._chart._subcharts: @@ -2786,7 +2713,6 @@ def _coerce_map_from_(self, other): sage: FR_D = X_D.function_ring() sage: FR_D.has_coerce_map_from(FR) True - """ if SR.has_coerce_map_from(other): return True @@ -2967,7 +2893,6 @@ class MultiCoordFunction(SageObject, Mutability): (a - b, a*b, cos(a)*e^b) sage: g(1,2) (4,) - """ def __init__(self, chart, expressions): r""" @@ -2982,7 +2907,6 @@ def __init__(self, chart, expressions): sage: type(f) sage: TestSuite(f).run() - """ self._chart = chart self._nc = len(self._chart._xx) # number of coordinates @@ -3004,7 +2928,6 @@ def _repr_(self): 'Coordinate functions (x - y, x*y, cos(x)*e^y) on the Chart (M, (x, y))' sage: f Coordinate functions (x - y, x*y, cos(x)*e^y) on the Chart (M, (x, y)) - """ return "Coordinate functions {} on the {}".format(self._functions, self._chart) @@ -3022,7 +2945,6 @@ def _latex_(self): \left(x - y, x y, \cos\left(x\right) e^{y}\right) sage: latex(f) \left(x - y, x y, \cos\left(x\right) e^{y}\right) - """ from sage.misc.latex import latex return latex(self._functions) @@ -3038,8 +2960,8 @@ def expr(self, method=None): INPUT: - - ``method`` -- string (default: ``None``): the calculus method which - the returned expressions belong to; one of + - ``method`` -- string (default: ``None``); the calculus method which + the returned expressions belong to. One of - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - ``'sympy'``: SymPy @@ -3071,7 +2993,6 @@ def expr(self, method=None): sage: f.chart().multifunction(*(f.expr())) == f True - """ return tuple(func.expr(method=method) for func in self._functions) @@ -3079,9 +3000,7 @@ def chart(self): r""" Return the chart with respect to which ``self`` is defined. - OUTPUT: - - - a :class:`~sage.manifolds.chart.Chart` + OUTPUT: a :class:`~sage.manifolds.chart.Chart` EXAMPLES:: @@ -3092,7 +3011,6 @@ def chart(self): Chart (M, (x, y)) sage: f.chart() is X True - """ return self._chart @@ -3104,9 +3022,7 @@ def __eq__(self, other): - ``other`` -- a :class:`MultiCoordFunction` - OUTPUT: - - - ``True`` if ``self`` is equal to ``other``, ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other``, ``False`` otherwise TESTS:: @@ -3122,7 +3038,6 @@ def __eq__(self, other): sage: Y. = M.chart() sage: f == Y.multifunction(u-v, u*v, cos(u*v)) False - """ if other is self: return True @@ -3159,7 +3074,6 @@ def __ne__(self, other): True sage: f != X.multifunction(x-y, x*y, cos(x*y)) False - """ return not (self == other) @@ -3188,7 +3102,6 @@ def __getitem__(self, index): cos(x*y) sage: f[0], f[1], f[2] (x - y, x*y, cos(x*y)) - """ return self._functions[index] @@ -3204,9 +3117,7 @@ def __call__(self, *coords, **options): ``simplify=False`` to disable simplification for symbolic coordinate functions - OUTPUT: - - - tuple containing the values of the `m` functions + OUTPUT: tuple containing the values of the `m` functions TESTS:: @@ -3219,7 +3130,6 @@ def __call__(self, *coords, **options): (-1, 6, cos(6)) sage: f.__call__(x,y) (x - y, x*y, cos(x*y)) - """ return tuple(func(*coords, **options) for func in self._functions) @@ -3293,9 +3203,7 @@ def jacobian_det(self): The number `m` of coordinate functions must equal the number `n` of coordinates. - OUTPUT: - - - a :class:`ChartFunction` representing the determinant + OUTPUT: a :class:`ChartFunction` representing the determinant EXAMPLES: @@ -3351,7 +3259,6 @@ def jacobian_det(self): sage: f.jacobian_det() == det(matrix([[f[i].diff(j).expr() for j in range(3)] ....: for i in range(3)])) True - """ from sage.matrix.constructor import matrix if self._nf != self._nc: @@ -3388,7 +3295,6 @@ def set_immutable(self): Ring of chart functions on Chart (M, (x, y, z)) sage: f[0].is_immutable() True - """ for func in self._functions: func.set_immutable() diff --git a/src/sage/manifolds/continuous_map.py b/src/sage/manifolds/continuous_map.py index 56f1ee139bd..f715d2e5738 100644 --- a/src/sage/manifolds/continuous_map.py +++ b/src/sage/manifolds/continuous_map.py @@ -60,7 +60,7 @@ class ContinuousMap(Morphism): - ``parent`` -- homset `\mathrm{Hom}(M,N)` to which the continuous map belongs - - ``coord_functions`` -- a dictionary of the coordinate expressions + - ``coord_functions`` -- dictionary of the coordinate expressions (as lists or tuples of the coordinates of the image expressed in terms of the coordinates of the considered point) with the pairs of charts ``(chart1, chart2)`` as keys (``chart1`` being a chart @@ -69,12 +69,12 @@ class ContinuousMap(Morphism): - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the continuous map; if ``None``, the LaTeX symbol is set to ``name`` - - ``is_isomorphism`` -- (default: ``False``) determines whether the - constructed object is a isomorphism (i.e. a homeomorphism); if set to - ``True``, then the manifolds `M` and `N` must have the same dimension - - ``is_identity`` -- (default: ``False``) determines whether the - constructed object is the identity map; if set to ``True``, - then `N` must be `M` and the entry ``coord_functions`` is not used + - ``is_isomorphism`` -- boolean (default: ``False``); determines whether the + constructed object is a isomorphism (i.e. a homeomorphism). If set to + ``True``, then the manifolds `M` and `N` must have the same dimension. + - ``is_identity`` -- boolean (default: ``False``); determines whether the + constructed object is the identity map. If set to ``True``, + then `N` must be `M` and the entry ``coord_functions`` is not used. .. NOTE:: @@ -341,7 +341,6 @@ class ContinuousMap(Morphism): True sage: ~id is id True - """ def __init__(self, parent, coord_functions=None, name=None, latex_name=None, is_isomorphism=False, is_identity=False): @@ -370,7 +369,6 @@ def __init__(self, parent, coord_functions=None, name=None, latex_name=None, Id_M: M → M (x, y) ↦ (x, y) sage: TestSuite(f).run() - """ Morphism.__init__(self, parent) domain = parent.domain() @@ -467,7 +465,6 @@ def _repr_(self): sage: f = Hom(M,M)({}, name='f', is_identity=True) sage: f Identity map f of the 2-dimensional topological manifold M - """ if self._is_identity: return "Identity map {} of the {}".format(self._name, self._domain) @@ -501,7 +498,6 @@ def _latex_(self): sage: f = Hom(M,M)({(X,X): (x+y,x*y)}, name='f', latex_name=r'\Phi') sage: latex(f) \Phi - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -530,7 +526,6 @@ def __hash__(self): sage: {f: 1}[f] 1 - """ return hash((self._domain, self._codomain)) @@ -542,9 +537,7 @@ def __eq__(self, other): - ``other`` -- a :class:`ContinuousMap` - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise TESTS:: @@ -559,7 +552,6 @@ def __eq__(self, other): sage: g = M.continuous_map(N, {(X,Y): [x+y+z, 1]}, name='g') sage: f == g False - """ if other is self: return True @@ -605,7 +597,6 @@ def __ne__(self, other): sage: g = M.continuous_map(N, {(X,Y): [x+y+z, 1]}, name='g') sage: f != g True - """ return not (self == other) @@ -622,9 +613,7 @@ def _call_(self, point): - ``point`` -- :class:`~sage.manifolds.point.TopologicalManifoldPoint`; point in the domain of ``self`` - OUTPUT: - - - image of the point by ``self`` + OUTPUT: image of the point by ``self`` EXAMPLES: @@ -659,7 +648,6 @@ def _call_(self, point): sage: q2 = rot(p2) # computation on c_spher sage: q2 == q True - """ # NB: checking that ``point`` belongs to the map's domain has been # already performed by Map.__call__(); this check is therefore not @@ -740,7 +728,6 @@ def is_identity(self): (x, y) ↦ (u, v) = (x, y) sage: a.is_identity() False - """ if self._is_identity: return True @@ -796,7 +783,6 @@ def _composition_(self, other, homset): (x, y, z) ↦ (a, b, c, d) = ((x*y + 1)*z + x + y, x*y*z^2 + (x^2*y + x*y^2)*z, x + y + z + 1, -x*y*z + 2) sage: s == f*g True - """ # This method is invoked by Map._composition (single underscore), # which is itself invoked by Map.__mul__ . The latter performs the @@ -833,8 +819,8 @@ def image(self, subset=None, inverse=None): EXAMPLES:: - sage: M = Manifold(2, 'M', structure="topological") - sage: N = Manifold(1, 'N', ambient=M, structure="topological") + sage: M = Manifold(2, 'M', structure='topological') + sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart(coord_restrictions=lambda u: [u > -1, u < 1]) sage: Phi = N.continuous_map(M, {(CN,CM): [u, u^2]}, name='Phi') @@ -875,7 +861,7 @@ def preimage(self, codomain_subset, name=None, latex_name=None): - ``codomain_subset`` -- an instance of :class:`~sage.manifolds.subset.ManifoldSubset` - ``name`` -- string; name (symbol) given to the subset - - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to + - ``latex_name`` -- string (default: ``None``); LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` OUTPUT: @@ -975,7 +961,6 @@ def _mul_(self, other): True sage: M.identity_map()._mul_(f) == f True - """ dom = self._domain return self._composition_(other, Hom(dom, dom)) @@ -1015,7 +1000,6 @@ def _init_derived(self): sage: g.inverse().restrict(U)[:] # used to be wrong [ 1 0] [ 0 1/2] - """ self._restrictions = {} # dict. of restrictions to subdomains of # self._domain @@ -1048,7 +1032,6 @@ def _del_derived(self): Homeomorphism of the 2-dimensional topological manifold M sage: f._del_derived() sage: f._inverse # has been set to None by _del_derived() - """ self._restrictions.clear() self._restrictions_graph = {(self._domain, self._codomain): self} @@ -1180,7 +1163,6 @@ def display(self, chart1=None, chart2=None): \frac{2 y}{x^{2} + y^{2} + 1}, \frac{x^{2} + y^{2} - 1}{x^{2} + y^{2} + 1}\right) \end{array} - """ from sage.misc.latex import latex from sage.typeset.unicode_characters import unicode_to, unicode_mapsto @@ -1362,7 +1344,6 @@ def coord_functions(self, chart1=None, chart2=None): - 2*V**2 + 6*V)/(2*(U - V)), (U**3/4 - U**2*V/4 - U*V**2/4 + U*V - U + V**3/4 - V**2 - V)/(U - V), (U**3 - U**2*V - U*V**2 - 4*U*V - 8*U + V**3 + 4*V**2 - 8*V)/(4*(U - V))) on the Chart (M, (U, V)) - """ dom1 = self._domain dom2 = self._codomain @@ -1547,7 +1528,6 @@ def expr(self, chart1=None, chart2=None): NB: a failed report can reflect a mere lack of simplification. sage: rot.expr(c_cart, c_cart) (-1/2*sqrt(3)*y + 1/2*x, 1/2*sqrt(3)*x + 1/2*y) - """ return self.coord_functions(chart1, chart2).expr() @@ -1792,7 +1772,6 @@ def add_expr(self, chart1, chart2, coord_functions): sage: q1 = rot(p1) # computation by means of spherical coordinates sage: q1 == q True - """ if self._is_identity: raise NotImplementedError("add_expr() must not be used for the identity map") @@ -1889,7 +1868,6 @@ def restrict(self, subdomain, subcodomain=None): sage: Phi.restrict(D, subcodomain=D) Continuous map from the Open subset D of the 2-dimensional topological manifold R^2 to itself - """ if subcodomain is None: if self._is_identity: @@ -1993,9 +1971,7 @@ def __invert__(self): r""" Return the inverse of ``self`` if it is an isomorphism. - OUTPUT: - - - the inverse isomorphism + OUTPUT: the inverse isomorphism EXAMPLES: @@ -2067,7 +2043,6 @@ def __invert__(self): sage: si == s True - """ from sage.symbolic.ring import SR from sage.symbolic.relation import solve diff --git a/src/sage/manifolds/continuous_map_image.py b/src/sage/manifolds/continuous_map_image.py index c2ccb64f7a1..cf3b073e875 100644 --- a/src/sage/manifolds/continuous_map_image.py +++ b/src/sage/manifolds/continuous_map_image.py @@ -31,8 +31,8 @@ class ImageManifoldSubset(ManifoldSubset): of `\Phi` is the inverse of `\Phi` onto its image if the latter exists (NB: no check of this is performed) - ``name`` -- (default: computed from the names of the map and the subset) - string; name (symbol) given to the subset - - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to + string; name (symbol) given to the subset + - ``latex_name`` -- string (default: ``None``); LaTeX symbol to denote the subset; if none is provided, it is set to ``name`` - ``domain_subset`` -- (default: the domain of ``map``) a subset of the domain of ``map`` @@ -44,8 +44,8 @@ def __init__(self, map, inverse=None, name=None, latex_name=None, domain_subset= TESTS:: - sage: M = Manifold(2, 'M', structure="topological") - sage: N = Manifold(1, 'N', ambient=M, structure="topological") + sage: M = Manifold(2, 'M', structure='topological') + sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart(coord_restrictions=lambda u: [u > -1, u < 1]) sage: Phi = N.continuous_map(M, {(CN,CM): [u, 1 + u^2]}, name='Phi') @@ -76,8 +76,8 @@ def _repr_(self): TESTS:: - sage: M = Manifold(2, 'M', structure="topological") - sage: N = Manifold(1, 'N', ambient=M, structure="topological") + sage: M = Manifold(2, 'M', structure='topological') + sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart(coord_restrictions=lambda u: [u > -1, u < 1]) sage: Phi = N.continuous_map(M, {(CN,CM): [u, 1 + u^2]}, name='Phi') @@ -108,8 +108,8 @@ def _an_element_(self): EXAMPLES:: - sage: M = Manifold(2, 'M', structure="topological") - sage: N = Manifold(1, 'N', ambient=M, structure="topological") + sage: M = Manifold(2, 'M', structure='topological') + sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart(coord_restrictions=lambda u: [u > -1, u < 1]) sage: Phi = N.continuous_map(M, {(CN,CM): [u, 1 + u^2]}, name='Phi') @@ -127,8 +127,8 @@ def __contains__(self, point): TESTS:: - sage: M = Manifold(2, 'M', structure="topological") - sage: N = Manifold(1, 'N', ambient=M, structure="topological") + sage: M = Manifold(2, 'M', structure='topological') + sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart(coord_restrictions=lambda u: [u > -1, u < 1]) sage: Phi = N.continuous_map(M, {(CN,CM): [u, 1 + u^2]}, name='Phi') @@ -138,7 +138,6 @@ def __contains__(self, point): False sage: M((0, 1)) in Phi_N True - """ if super().__contains__(point): return True diff --git a/src/sage/manifolds/differentiable/affine_connection.py b/src/sage/manifolds/differentiable/affine_connection.py index fce8737df84..2c24b7c3ba9 100644 --- a/src/sage/manifolds/differentiable/affine_connection.py +++ b/src/sage/manifolds/differentiable/affine_connection.py @@ -112,7 +112,7 @@ class AffineConnection(SageObject): :class:`~sage.manifolds.differentiable.manifold.DifferentiableManifold`) - ``name`` -- name given to the affine connection - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the affine - connection; if ``None``, it is set to ``name``. + connection; if ``None``, it is set to ``name`` EXAMPLES: @@ -362,7 +362,6 @@ class AffineConnection(SageObject): True sage: nab_copy.is_immutable() False - """ def __init__(self, domain, name, latex_name=None): r""" @@ -380,7 +379,6 @@ def __init__(self, domain, name, latex_name=None): sage: X. = M.chart() sage: nab[0,1,0] = x*y*z sage: TestSuite(nab).run() - """ if not isinstance(domain, DifferentiableManifold): raise TypeError("the first argument must be a differentiable " + @@ -409,7 +407,6 @@ def _repr_(self): 'Affine connection nabla on the 5-dimensional differentiable manifold M' sage: repr(nab) # indirect doctest 'Affine connection nabla on the 5-dimensional differentiable manifold M' - """ description = "Affine connection" if self._name is not None: @@ -434,7 +431,6 @@ def _latex_(self): 'D' sage: latex(nab) # indirect doctest D - """ return self._latex_name @@ -447,7 +443,6 @@ def _init_derived(self): sage: M = Manifold(4, 'M') sage: nab = M.affine_connection('nabla', latex_name=r'\nabla') sage: nab._init_derived() - """ self._restrictions = {} # dict. of restrictions of ``self`` on some # subdomains, with the subdomains as keys @@ -470,7 +465,6 @@ def _del_derived(self): sage: M = Manifold(4, 'M') sage: nab = M.affine_connection('nabla', latex_name=r'\nabla') sage: nab._del_derived() - """ self._restrictions.clear() self._torsion = None @@ -488,9 +482,7 @@ def __eq__(self, other): - ``other`` -- an affine connection - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise TESTS:: @@ -522,7 +514,6 @@ def __eq__(self, other): sage: nab2.set_coef(f)[1,0,1] = x-y sage: (nab2 == nab) or (nab == nab2) False - """ if other is self: return True @@ -568,7 +559,6 @@ def __ne__(self, other): sage: nab1[0,1,0], nab1[0,1,1] = 1+x, x*y sage: (nab1 != nab) or (nab != nab1) False - """ return not (self == other) @@ -593,7 +583,6 @@ def domain(self): sage: nabU = U.affine_connection('D') sage: nabU.domain() Open subset U of the 3-dimensional differentiable manifold M - """ return self._domain @@ -612,7 +601,6 @@ def _new_coef(self, frame): sage: nab = M.affine_connection('nabla', latex_name=r'\nabla') sage: nab._new_coef(X.frame()) 3-indices components w.r.t. Coordinate frame (M, (∂/∂x,∂/∂y)) - """ from sage.tensor.modules.comp import Components from sage.manifolds.differentiable.scalarfield import DiffScalarField @@ -669,7 +657,6 @@ def coef(self, frame=None): [[[0, x^2, 0], [0, 0, 0], [0, 0, 0]], [[0, 0, 0], [0, 0, 0], [0, 0, 0]], [[0, 0, 0], [0, 0, y*z], [0, 0, 0]]] - """ if frame is None: frame = self._domain.default_frame() @@ -778,7 +765,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such ValueError: no common frame found for the computation To keep them, use the method :meth:`add_coef` instead. - """ if self.is_immutable(): raise ValueError("the coefficients of an immutable element " @@ -825,7 +811,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such See method :meth:`coef` for the storage convention of the connection coefficients. - EXAMPLES: Setting the coefficients of an affine connection w.r.t. some coordinate @@ -869,8 +854,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such Gam^x_yx = x*y To delete them, use the method :meth:`set_coef` instead. - - """ if self.is_immutable(): raise ValueError("the coefficients of an immutable element " @@ -925,7 +908,6 @@ def del_other_coef(self, frame=None): Traceback (most recent call last): ... ValueError: no common frame found for the computation - """ if frame is None: frame = self._domain._def_frame @@ -972,7 +954,6 @@ def set_immutable(self): sage: nabU = nab.restrict(U) sage: nabU.is_immutable() True - """ for rst in self._restrictions.values(): rst.set_immutable() @@ -995,7 +976,6 @@ def is_immutable(self): sage: nab.set_immutable() sage: nab.is_immutable() True - """ return self._is_immutable @@ -1014,7 +994,6 @@ def is_mutable(self): sage: nab.set_immutable() sage: nab.is_mutable() False - """ return not self._is_immutable @@ -1051,7 +1030,6 @@ def copy(self, name, latex_name=None): sage: nab_copy.display() Gam^x_yx = x*y Gam^x_yy = x + y - """ copy = type(self)(self._domain, name, latex_name=latex_name) for dom, rst in self._restrictions.items(): @@ -1116,7 +1094,6 @@ def __getitem__(self, args): Scalar field on the 2-dimensional differentiable manifold M sage: nab.__getitem__(([X.frame(),1,2,1])).coord_function() is nab[1,2,1] True - """ if isinstance(args, list): # case of [[...]] syntax if isinstance(args[0], (int, Integer, slice)): @@ -1184,7 +1161,6 @@ def __setitem__(self, args, value): sage: nab.__setitem__((1,2,1), f) sage: nab[1,2,1] x*y - """ if isinstance(args, list): # case of [[...]] syntax if isinstance(args[0], (int, Integer, slice)): @@ -1236,12 +1212,12 @@ def display(self, frame=None, chart=None, symbol=None, latex_symbol=None, labels are used, except if ``frame`` is a coordinate frame and ``coordinate_symbols`` is set to ``True``, in which case the coordinate LaTeX symbols are used - - ``coordinate_labels`` -- (default: ``True``) boolean; if ``True``, + - ``coordinate_labels`` -- boolean (default: ``True``); if ``True``, coordinate symbols are used by default (instead of integers) as index labels whenever ``frame`` is a coordinate frame - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero connection coefficients are displayed - - ``only_nonredundant`` -- (default: ``False``) boolean; if ``True``, + - ``only_nonredundant`` -- boolean (default: ``False``); if ``True``, only nonredundant connection coefficients are displayed in case of symmetries @@ -1328,7 +1304,6 @@ def display(self, frame=None, chart=None, symbol=None, latex_symbol=None, Gam^ph_th,ph = cos(th)/sin(th) Gam^ph_ph,r = 1/r Gam^ph_ph,th = cos(th)/sin(th) - """ from sage.misc.latex import latex from sage.manifolds.differentiable.vectorframe import CoordFrame @@ -1363,9 +1338,7 @@ def restrict(self, subdomain): an instance of :class:`~sage.manifolds.differentiable.manifold.DifferentiableManifold`) - OUTPUT: - - - instance of :class:`AffineConnection` representing the restriction. + OUTPUT: instance of :class:`AffineConnection` representing the restriction EXAMPLES: @@ -1398,7 +1371,6 @@ def restrict(self, subdomain): False sage: nab.restrict(U)[:] [[[0, x^2], [0, -y]], [[x + y, 0], [0, 0]]] - """ if subdomain == self._domain: return self @@ -1443,9 +1415,7 @@ def _common_frame(self, other): instance of :class:`~sage.manifolds.differentiable.tensorfield_paral.TensorFieldParal` - OUTPUT: - - - common frame; if no common frame is found, None is returned. + OUTPUT: common frame; if no common frame is found, ``None`` is returned TESTS:: @@ -1461,7 +1431,6 @@ def _common_frame(self, other): sage: u = M.vector_field() sage: u[e,:] = [-3, 2] sage: nab._common_frame(u) # no common frame is found - """ # The domain of search is restricted to other._domain: dom = other._domain @@ -1515,9 +1484,7 @@ def __call__(self, tensor): - ``tensor`` -- a tensor field `T`, of type `(k,\ell)` - OUTPUT: - - - tensor field `\nabla T`. + OUTPUT: tensor field `\nabla T` TESTS:: @@ -1534,7 +1501,6 @@ def __call__(self, tensor): See documentation of :class:`~sage.manifolds.differentiable.affine_connection.AffineConnection` for more examples. - """ from sage.manifolds.differentiable.tensorfield_paral import \ TensorFieldParal @@ -1583,9 +1549,7 @@ def _derive_paral(self, tensor): - ``tensor`` -- a tensor field `T`, of type `(k,\ell)` - OUTPUT: - - - tensor field `\nabla T`. + OUTPUT: tensor field `\nabla T` TESTS:: @@ -1598,7 +1562,6 @@ def _derive_paral(self, tensor): sage: nab._derive_paral(v) Tensor field of type (1,1) on the 2-dimensional differentiable manifold M - """ from sage.manifolds.differentiable.scalarfield import DiffScalarField from sage.tensor.modules.comp import Components, CompWithSym @@ -1818,7 +1781,6 @@ def torsion(self): (1/8*u^3 - 1/8*u*v^2 - 1/2*u*v) du∧dv sage: 2*DDf.antisymmetrize() == nab(f).contract(nab.torsion()) True - """ if self._torsion is None: manif = self._domain @@ -1956,7 +1918,6 @@ def riemann(self): sage: r == r_backup # long time True sage: Parallelism().set(nproc=1) # switch off parallelization - """ if self._riemann is None: manif = self._domain @@ -2066,7 +2027,6 @@ def ricci(self): sage: nab.ricci() is r True - """ if self._ricci is None: self._ricci = self.riemann().trace(0,2) @@ -2189,7 +2149,6 @@ def connection_form(self, i, j, frame=None): True True True - """ if frame is None: frame = self._domain._def_frame @@ -2400,7 +2359,6 @@ def curvature_form(self, i, j, frame=None): ....: sum( omega(i,k,e).wedge(omega(k,j,e)) for k in M.irange()) ) sage: check # long time [True, True, True, True, True, True, True, True, True] - """ if frame is None: frame = self._domain._def_frame @@ -2440,7 +2398,7 @@ def set_calc_order(self, symbol, order, truncate=False): - ``order`` -- integer; the order `n` of the expansion, defined as the degree of the polynomial representing the truncated power series in ``symbol`` - - ``truncate`` -- (default: ``False``) determines whether the + - ``truncate`` -- boolean (default: ``False``); determines whether the connection coefficients are replaced by their expansions to the given order @@ -2465,7 +2423,6 @@ def set_calc_order(self, symbol, order, truncate=False): sage: nab.set_calc_order(e, 1, truncate=True) sage: nab[0, 1, 1] -e - """ for coef in self._coefficients.values(): for ind in coef.non_redundant_index_generator(): @@ -2510,7 +2467,6 @@ def __hash__(self): 1 sage: d[nab2] 2 - """ if self.is_mutable(): raise ValueError('element must be immutable in order to be ' diff --git a/src/sage/manifolds/differentiable/automorphismfield.py b/src/sage/manifolds/differentiable/automorphismfield.py index 04d099b4e4e..4143e29228a 100644 --- a/src/sage/manifolds/differentiable/automorphismfield.py +++ b/src/sage/manifolds/differentiable/automorphismfield.py @@ -69,7 +69,7 @@ class AutomorphismField(TensorField): - ``name`` -- (default: ``None``) name given to the field - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the field; if none is provided, the LaTeX symbol is set to ``name`` - - ``is_identity`` -- (default: ``False``) determines whether the + - ``is_identity`` -- boolean (default: ``False``); determines whether the constructed object is a field of identity automorphisms EXAMPLES: @@ -136,7 +136,6 @@ class AutomorphismField(TensorField): sage: ia is ~a True - """ def __init__(self, vector_field_module, name=None, latex_name=None): r""" @@ -182,7 +181,6 @@ def __init__(self, vector_field_module, name=None, latex_name=None): .. TODO:: Fix ``_test_pickling`` (in the superclass :class:`TensorField`). - """ TensorField.__init__(self, vector_field_module, (1,1), name=name, latex_name=latex_name, @@ -205,7 +203,6 @@ def _repr_(self): sage: a # indirect doctest Field of tangent-space automorphisms a on the 2-dimensional differentiable manifold M - """ description = "Field of tangent-space " if self is self.parent().one(): @@ -225,7 +222,6 @@ def _init_derived(self): sage: M = Manifold(2, 'M') sage: a = M.automorphism_field(name='a') sage: a._init_derived() - """ TensorField._init_derived(self) self._inverse = None # inverse not set yet @@ -239,7 +235,6 @@ def _del_derived(self): sage: M = Manifold(2, 'M') sage: a = M.automorphism_field(name='a') sage: a._del_derived() - """ # First delete the derived quantities pertaining to the mother class: TensorField._del_derived(self) @@ -312,7 +307,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such ... ValueError: the components of an immutable element cannot be changed - """ comp = super().set_comp(basis=basis) self._is_identity = False # a priori @@ -385,7 +379,6 @@ class :class:`~sage.tensor.modules.comp.Components`; ... ValueError: the components of an immutable element cannot be changed - """ comp = super().add_comp(basis=basis) self._is_identity = False # a priori @@ -405,7 +398,6 @@ def _new_instance(self): differentiable manifold M sage: a._new_instance().parent() is a.parent() True - """ return type(self)(self._vmodule) @@ -483,7 +475,6 @@ def __call__(self, *arg): True sage: s.restrict(U) == a(z, w.restrict(U)) True - """ if self._is_identity: if len(arg) == 1: @@ -555,7 +546,6 @@ def copy(self, name=None, latex_name=None): sage: one = Id.copy('1'); one Field of tangent-space automorphisms 1 on the 2-dimensional differentiable manifold M - """ copy = super().copy(name=name, latex_name=latex_name) copy._is_identity = self._is_identity @@ -629,7 +619,6 @@ def __invert__(self): sage: ia is ~a True - """ if self._is_identity: return self @@ -709,7 +698,6 @@ def _mul_(self, other): sage: w.add_comp_by_continuation(e_uv, U.intersection(V), c_uv) sage: s(w) == a(b(w)) # long time True - """ # No need for consistency check since self and other are guaranteed # to have the same parent. In particular, they are defined on the same @@ -766,7 +754,6 @@ def __mul__(self, other): True sage: s = a.__mul__(w); s # tensor product Tensor field of type (2,1) on the 2-dimensional differentiable manifold M - """ if isinstance(other, AutomorphismField): return self._mul_(other) # general linear group law @@ -803,7 +790,6 @@ def __imul__(self, other): sage: a *= b sage: a == s True - """ return self.__mul__(other) @@ -826,9 +812,7 @@ def restrict(self, subdomain, dest_map=None): subdomain of ``self._codomain``; if ``None``, the restriction of ``self.base_module().destination_map()`` to `V` is used - OUTPUT: - - - a :class:`AutomorphismField` representing the restriction + OUTPUT: a :class:`AutomorphismField` representing the restriction EXAMPLES: @@ -897,7 +881,6 @@ def restrict(self, subdomain, dest_map=None): sage: id.restrict(W)[eS_W,:] [1 0] [0 1] - """ if subdomain == self._domain: return self @@ -1003,7 +986,6 @@ class AutomorphismFieldParal(FreeModuleAutomorphism, TensorFieldParal): sage: inv is ~rot True - """ def __init__(self, vector_field_module, name=None, latex_name=None): r""" @@ -1038,7 +1020,6 @@ def __init__(self, vector_field_module, name=None, latex_name=None): [1 0] [0 1] sage: TestSuite(b).run() - """ FreeModuleAutomorphism.__init__(self, vector_field_module, name=name, latex_name=latex_name) @@ -1066,7 +1047,6 @@ def _repr_(self): sage: a # indirect doctest Field of tangent-space automorphisms a on the 2-dimensional differentiable manifold M - """ description = "Field of tangent-space " if self is self.parent().one(): @@ -1083,8 +1063,8 @@ def _del_derived(self, del_restrictions=True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the - restrictions of ``self`` to subdomains are deleted. + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the + restrictions of ``self`` to subdomains are deleted TESTS:: @@ -1092,7 +1072,6 @@ def _del_derived(self, del_restrictions=True): sage: X. = M.chart() sage: a = M.automorphism_field(name='a') sage: a._del_derived() - """ # Delete the derived quantities pertaining to the mother classes: FreeModuleAutomorphism._del_derived(self) @@ -1132,7 +1111,6 @@ def __call__(self, *arg): sage: s.display() a(z,v): U → ℝ (x, y) ↦ 2*x*y^2 + x - """ if len(arg) == 1: # the automorphism acting as such (map of a vector field to a @@ -1188,7 +1166,6 @@ def __invert__(self): sage: b is ~a True - """ from sage.matrix.constructor import matrix from sage.tensor.modules.comp import Components @@ -1262,9 +1239,7 @@ def restrict(self, subdomain, dest_map=None): ``self._codomain``; if ``None``, the restriction of ``self.base_module().destination_map()`` to `V` is used - OUTPUT: - - - a :class:`AutomorphismFieldParal` representing the restriction + OUTPUT: a :class:`AutomorphismFieldParal` representing the restriction EXAMPLES: @@ -1297,7 +1272,6 @@ def restrict(self, subdomain, dest_map=None): [0 1] sage: id.restrict(D) == D.tangent_identity_field() True - """ if subdomain == self._domain: return self @@ -1387,7 +1361,6 @@ def at(self, point): 2-dimensional differentiable manifold M sage: idp * ap == ap True - """ if point not in self._domain: raise TypeError("the {} is not in the domain of the {}".format( diff --git a/src/sage/manifolds/differentiable/automorphismfield_group.py b/src/sage/manifolds/differentiable/automorphismfield_group.py index 273deab226d..78a906466b3 100644 --- a/src/sage/manifolds/differentiable/automorphismfield_group.py +++ b/src/sage/manifolds/differentiable/automorphismfield_group.py @@ -137,7 +137,6 @@ class AutomorphismFieldGroup(UniqueRepresentation, Parent): Id = ∂/∂x⊗dx + ∂/∂y⊗dy sage: e.display(eV) Id = ∂/∂u⊗du + ∂/∂v⊗dv - """ Element = AutomorphismField @@ -166,7 +165,6 @@ def __init__(self, vector_field_module): ``_test_elements`` does not pass due to the failure of ``_test_pickling`` in :class:`sage.manifolds.differentiable.tensorfield.TensorField`. - """ if not isinstance(vector_field_module, VectorFieldModule): raise TypeError("{} is not a module of vector fields".format( @@ -181,9 +179,7 @@ def _element_constructor_(self, comp=[], frame=None, name=None, r""" Construct a field of tangent-space automorphisms. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField` + OUTPUT: :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField` TESTS:: @@ -204,7 +200,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, differentiable manifold M sage: a.display(c_xy.frame()) a = (x^2 + 1) ∂/∂x⊗dx + (y^2 + 1) ∂/∂y⊗dy - """ if hasattr(comp, 'is_trivial_zero'): if (comp - 1).is_trivial_zero(): @@ -225,9 +220,7 @@ def _an_element_(self): r""" Construct some specific field of tangent-space automorphisms. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField` + OUTPUT: :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField` TESTS:: @@ -249,7 +242,6 @@ def _an_element_(self): 2 ∂/∂u⊗du + 2 ∂/∂v⊗dv sage: a == G.an_element() # indirect doctest True - """ resu = self.element_class(self._vmodule) for dom in resu.domain().subsets(): @@ -302,7 +294,6 @@ def one(self): sage: G.one().restrict(V)[:] [1 0] [0 1] - """ # Specific initializations for the field of identity maps: resu = self._element_constructor_(name='Id', latex_name=r'\mathrm{Id}') @@ -335,7 +326,6 @@ def _repr_(self): sage: G # indirect doctest General linear group of the Module X(M) of vector fields on the 2-dimensional differentiable manifold M - """ return "General linear group of the {}".format(self._vmodule) @@ -351,7 +341,6 @@ def _latex_(self): \mathrm{GL}\left( \mathfrak{X}\left(M\right) \right) sage: latex(G) # indirect doctest \mathrm{GL}\left( \mathfrak{X}\left(M\right) \right) - """ from sage.misc.latex import latex return r"\mathrm{GL}\left(" + latex(self._vmodule) + r"\right)" @@ -361,9 +350,7 @@ def base_module(self): Return the vector-field module of which ``self`` is the general linear group. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.vectorfield_module.VectorFieldModule` + OUTPUT: :class:`~sage.manifolds.differentiable.vectorfield_module.VectorFieldModule` EXAMPLES: @@ -386,7 +373,6 @@ def base_module(self): manifold M sage: G.base_module() is M.vector_field_module() True - """ return self._vmodule @@ -587,7 +573,6 @@ class AutomorphismFieldParalGroup(FreeModuleLinearGroup): TESTS:: sage: TestSuite(G).run() - """ Element = AutomorphismFieldParal @@ -606,7 +591,6 @@ def __init__(self, vector_field_module): General linear group of the Free module X(M) of vector fields on the 2-dimensional differentiable manifold M sage: TestSuite(G).run() - """ if not isinstance(vector_field_module, VectorFieldFreeModule): raise TypeError("{} is not a free module of vector fields".format( diff --git a/src/sage/manifolds/differentiable/bundle_connection.py b/src/sage/manifolds/differentiable/bundle_connection.py index c4ae9379aca..184e9641eeb 100644 --- a/src/sage/manifolds/differentiable/bundle_connection.py +++ b/src/sage/manifolds/differentiable/bundle_connection.py @@ -90,7 +90,7 @@ class BundleConnection(SageObject, Mutability): connection (1,1) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1,e_2)) = 0 - Now, we want to specify some non-zero entries:: + Now, we want to specify some nonzero entries:: sage: nab[e, 1, 2][:] = [x*z, y*z, z^2] sage: nab[e, 2, 1][:] = [x, x^2, x^3] @@ -235,7 +235,6 @@ class BundleConnection(SageObject, Mutability): ....: for k in E.irange())) sage: check # long time [True, True, True, True] - """ def __init__(self, vbundle, name, latex_name=None): @@ -258,7 +257,6 @@ def __init__(self, vbundle, name, latex_name=None): sage: nab[:] = 0 sage: nab.set_connection_form(1, 0)[:] = [x*z, y*z, z^2] sage: TestSuite(nab).run() - """ if not isinstance(vbundle, DifferentiableVectorBundle): raise TypeError("the first argument must be a differentiable " + @@ -293,7 +291,6 @@ def _repr_(self): 'Bundle connection nabla on the Differentiable real vector bundle E -> M of rank 3 over the base space 5-dimensional differentiable manifold M' - """ description = "Bundle connection" if self._name is not None: @@ -319,7 +316,6 @@ def _latex_(self): 'D' sage: latex(nab) # indirect doctest D - """ return self._latex_name @@ -333,7 +329,6 @@ def _init_derived(self): sage: E = M.vector_bundle(2, 'E') sage: nab = E.bundle_connection('nabla', latex_name=r'\nabla') sage: nab._init_derived() - """ self._curvature_forms = {} # dict. of dict. of curvature forms # (key: local frame) @@ -349,7 +344,6 @@ def _del_derived(self): sage: E = M.vector_bundle(2, 'E') sage: nab = E.bundle_connection('nabla', latex_name=r'\nabla') sage: nab._del_derived() - """ self._curvature_forms.clear() @@ -361,9 +355,7 @@ def __eq__(self, other): - ``other`` -- a bundle connection - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise TESTS:: @@ -387,7 +379,6 @@ def __eq__(self, other): sage: nab1[1, 0][:] = [y^2, y] sage: (nab1 == nab) and (nab == nab1) True - """ if other is self: return True @@ -441,7 +432,6 @@ def __ne__(self, other): sage: nab1[1, 0][:] = [y^2, y] sage: (nab1 != nab) or (nab != nab1) False - """ return not (self == other) @@ -464,7 +454,6 @@ def vector_bundle(self): sage: nab.vector_bundle() Differentiable real vector bundle E -> M of rank 2 over the base space 3-dimensional differentiable manifold M - """ return self._vbundle @@ -493,7 +482,6 @@ def _new_forms(self, frame): 1-form connection (2,2) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1,e_2)) on the 2-dimensional differentiable manifold M] - """ dom = frame._domain forms_dict = {} @@ -562,7 +550,6 @@ def connection_forms(self, frame=None): 1-form connection (2,2) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1,e_2)) on the 3-dimensional differentiable manifold M] - """ if frame is None: smodule = self._vbundle.section_module(domain=self._domain) @@ -634,7 +621,6 @@ def connection_form(self, i, j, frame=None): sage: nab.connection_form(1, 0).display() connection (1,0) of bundle connection nabla w.r.t. Local frame (E|_M, (e_0,e_1)) = y^2 dx + y dy - """ return self.connection_forms(frame)[(i, j)] @@ -647,9 +633,7 @@ def __call__(self, v, s): - ``v`` -- a vector field `v` on the base space - ``s`` -- a local section `s` - OUTPUT: - - - local section `\nabla_v s` + OUTPUT: local section `\nabla_v s` TESTS:: @@ -667,7 +651,6 @@ def __call__(self, v, s): sage: nab.__call__(v, s) Section nabla_v(s) on the 2-dimensional differentiable manifold M with values in the real vector bundle E of rank 2 - """ from sage.manifolds.section import TrivialSection from sage.tensor.modules.format_utilities import format_unop_latex @@ -708,9 +691,7 @@ def _derive_trivial(self, v, s): - ``v`` -- a vector field `v` on the base space - ``s`` -- a local section `s` whose module is free - OUTPUT: - - - local section `\nabla_v s` + OUTPUT: local section `\nabla_v s` TESTS:: @@ -728,7 +709,6 @@ def _derive_trivial(self, v, s): sage: nab._derive_trivial(v, s) Section nabla_v(s) on the 2-dimensional differentiable manifold M with values in the real vector bundle E of rank 2 - """ vb = self._vbundle dom = s.domain() @@ -827,7 +807,6 @@ def add_connection_form(self, i, j, frame=None): (E|_M, (e_0,e_1)) = x^2 dx + x dy To delete them, use the method :meth:`set_connection_form` instead. - """ self._require_mutable() if frame is None: @@ -911,7 +890,6 @@ def set_connection_form(self, i, j, frame=None): the Local frame (E|_M, (f_0,f_1)) To keep them, use the method :meth:`add_connection_form` instead. - """ self._require_mutable() omega = self.add_connection_form(i, j, frame=frame) @@ -963,7 +941,6 @@ def del_other_forms(self, frame=None): ... ValueError: no basis could be found for computing the components in the Local frame (E|_M, (e_1,e_2)) - """ if frame is None: smodule = self._vbundle.section_module(domain=self._domain) @@ -1019,7 +996,6 @@ def curvature_form(self, i, j, frame=None): sage: curv.display() curvature (1,1) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1)) = dx∧dy - """ if frame is None: smodule = self._vbundle.section_module(domain=self._domain) @@ -1063,7 +1039,6 @@ def __hash__(self): sage: {nab: 1}[nab] 1 - """ self._require_immutable() if self._hash == -1: @@ -1121,7 +1096,6 @@ def __getitem__(self, args): 1-form connection (2,2) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1,e_2)) on the 2-dimensional differentiable manifold M]] - """ # extract frame from first index: vb = self._vbundle @@ -1158,7 +1132,7 @@ def __getitem__(self, args): def __setitem__(self, args, value): r""" - Sets the components of ``self`` corresponding to the given indices. + Set the components of ``self`` corresponding to the given indices. INPUT: @@ -1194,7 +1168,6 @@ def __setitem__(self, args, value): sage: nab[e, 1, 2].display() connection (1,2) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1,e_2)) = x^2 dx + x dy - """ # extract frame from first index: vb = self._vbundle @@ -1282,7 +1255,7 @@ def display(self, frame=None, vector_frame=None, chart=None, - ``chart`` -- (default: ``None``) chart specifying the coordinate expression of the connection 1-forms; if ``None``, the default chart of the domain of ``frame`` is used - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero connection coefficients are displayed EXAMPLES: @@ -1345,7 +1318,6 @@ def display(self, frame=None, vector_frame=None, chart=None, (E|_M, (e_1,e_2)) = 0 connection (2,2) of bundle connection nabla w.r.t. Local frame (E|_M, (e_1,e_2)) = x^2 dx + y^2 dy + z^2 dz - """ vb = self._vbundle if frame is None: @@ -1428,7 +1400,6 @@ def copy(self, name, latex_name=None): (E|_M, (e_1,e_2)) = dx + x dy + y^3*z dz connection (2,1) of bundle connection nablo w.r.t. Local frame (E|_M, (e_1,e_2)) = dx + 2 dy + 3 dz - """ copy = type(self)(self._vbundle, name, latex_name=latex_name) for frame, form_dict in self._connection_forms.items(): @@ -1467,7 +1438,6 @@ def set_immutable(self): Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead - """ for form_dict in self._connection_forms.values(): for form in form_dict.values(): diff --git a/src/sage/manifolds/differentiable/characteristic_cohomology_class.py b/src/sage/manifolds/differentiable/characteristic_cohomology_class.py index 86ba9eb3c6b..51f32ffb4b8 100644 --- a/src/sage/manifolds/differentiable/characteristic_cohomology_class.py +++ b/src/sage/manifolds/differentiable/characteristic_cohomology_class.py @@ -344,7 +344,7 @@ def __init__(self, parent, x, name=None, latex_name=None): self._latex_name = self._name else: self._latex_name = latex_name - self._mixed_forms = {} # dict. of characteristic forms of `self` + self._mixed_forms = {} # dict. of characteristic forms of self # (key: bundle connection) super().__init__(parent, x) @@ -502,9 +502,9 @@ def get_form(self, nab): # set names of components from sage.arith.misc import gcd - step = gcd(parent._degrees) # step size of (possibly) non-zero + step = gcd(parent._degrees) # step size of (possibly) nonzero for i in range(dom._dim // step + 1): - # enumerate (possibly) non-zero components + # enumerate (possibly) nonzero components comp_name = name + f'_{i}' + append_name comp_latex_name = latex_name + r'_{' + str(i) + '}' comp_latex_name += append_latex_name @@ -1065,13 +1065,11 @@ def multiplicative_sequence(q, n=None): INPUT: - - ``q`` -- polynomial to turn into its multiplicative sequence. + - ``q`` -- polynomial to turn into its multiplicative sequence - ``n`` -- (default: ``None``) the highest order `n` of the sequence; - if ``None``, the order of ``q`` is assumed. + if ``None``, the order of ``q`` is assumed - OUTPUT: - - - A symmetric polynomial representing the multiplicative sequence. + OUTPUT: a symmetric polynomial representing the multiplicative sequence EXAMPLES:: @@ -1122,14 +1120,12 @@ def additive_sequence(q, k, n=None): INPUT: - - ``q`` -- polynomial to turn into its additive sequence. + - ``q`` -- polynomial to turn into its additive sequence - ``k`` -- maximal index `k` of the sum - ``n`` -- (default: ``None``) the highest order of the sequence `n`; - if ``None``, the order of ``q`` is assumed. - - OUTPUT: + if ``None``, the order of ``q`` is assumed - - A symmetric polynomial representing the additive sequence. + OUTPUT: a symmetric polynomial representing the additive sequence EXAMPLES:: @@ -1170,7 +1166,7 @@ def fast_wedge_power(form, n): INPUT: - ``form`` -- a differential form - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -1190,7 +1186,7 @@ def fast_wedge_power(form, n): if n == 0: return form._domain._one_scalar_field elif n < 0: - raise ValueError("'n' must be non-negative") + raise ValueError("'n' must be nonnegative") val = form while not (n & 1): val = val.wedge(val) @@ -1284,9 +1280,7 @@ def get_local(self, cmat): Abstract method to get the local forms of the generators w.r.t. a given curvature form matrix ``cmat``. - OUTPUT: - - - a list containing the generator's local characteristic forms + OUTPUT: list containing the generator's local characteristic forms ALGORITHM: @@ -1481,9 +1475,7 @@ def get_local(self, cmat): r""" Return the local Pontryagin forms w.r.t. a given curvature form matrix. - OUTPUT: - - - a list containing the local characteristic Pontryagin forms + OUTPUT: list containing the local characteristic Pontryagin forms ALGORITHM:: @@ -1566,11 +1558,9 @@ def get(self, nab): INPUT: - - a metric connection `\nabla` - - OUTPUT: + - ``nab`` -- a metric connection `\nabla` - - a list containing the global characteristic Euler form + OUTPUT: list containing the global characteristic Euler form ALGORITHM: @@ -1654,9 +1644,7 @@ def get_local(self, cmat): `\left(\frac{1}{2 \pi}\right)^{\frac{k}{2}}`, where `k` is the dimension of the curvature matrix. - OUTPUT: - - - a list containing the normalized Pfaffian of a given curvature form + OUTPUT: list containing the normalized Pfaffian of a given curvature form .. NOTE:: diff --git a/src/sage/manifolds/differentiable/chart.py b/src/sage/manifolds/differentiable/chart.py index cbdad556734..af74ac85669 100644 --- a/src/sage/manifolds/differentiable/chart.py +++ b/src/sage/manifolds/differentiable/chart.py @@ -75,16 +75,15 @@ class DiffChart(Chart): method for computations involving coordinates of the chart; must be one of - - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - - ``'sympy'``: SymPy - - ``None``: the default of - :class:`~sage.manifolds.calculus_method.CalculusMethod` will be - used + - ``'SR'`` -- Sage's default symbolic engine (Symbolic Ring) + - ``'sympy'`` -- SymPy + - ``None`` -- the default of :class:`~sage.manifolds.calculus_method.CalculusMethod` + will be used - ``names`` -- (default: ``None``) unused argument, except if ``coordinates`` is not provided; it must then be a tuple containing the coordinate symbols (this is guaranteed if the shortcut operator ``<,>`` is used). - - ``coord_restrictions``: Additional restrictions on the coordinates. + - ``coord_restrictions`` -- additional restrictions on the coordinates. A restriction can be any symbolic equality or inequality involving the coordinates, such as ``x > y`` or ``x^2 + y^2 != 0``. The items of the list (or set or frozenset) ``coord_restrictions`` are combined @@ -273,7 +272,6 @@ class DiffChart(Chart): :class:`~sage.manifolds.differentiable.chart.RealDiffChart` for charts on differentiable manifolds over `\RR`. - """ def __init__(self, domain, coordinates, calc_method=None, periods=None, coord_restrictions=None): r""" @@ -290,7 +288,6 @@ def __init__(self, domain, coordinates, calc_method=None, periods=None, coord_re sage: assumptions() # no assumptions on x,y set by X._init_coordinates [] sage: TestSuite(X).run() - """ super().__init__(domain, coordinates, calc_method=calc_method, periods=periods, coord_restrictions=coord_restrictions) @@ -405,7 +402,6 @@ def transition_map(self, other, transformations, intersection_name=None, sage: M.atlas() [Chart (R^2, (x, y)), Chart (U, (r, phi)), Chart (U, (x, y))] - """ dom1 = self.domain() dom2 = other.domain() @@ -462,7 +458,6 @@ def frame(self): sage: ey(M.scalar_field(y)).display() 1: M → ℝ (x, y) ↦ 1 - """ return self._frame @@ -511,7 +506,6 @@ def coframe(self): sage: dy(ey).display() dy(∂/∂y): M → ℝ (x, y) ↦ 1 - """ return self._coframe @@ -562,7 +556,6 @@ def restrict(self, subset, restrictions=None): sage: B = M.open_subset('B') sage: X_B = X.restrict(B, abs(z1)^2 + abs(z2)^2 < 1); X_B Chart (B, (z1, z2)) - """ if subset == self.domain(): return self @@ -600,9 +593,7 @@ def symbolic_velocities(self, left='D', right=None): - ``right`` -- (default: ``None``) string to concatenate to the right of each coordinate functions of the chart - OUTPUT: - - - a list of symbolic expressions with the desired names + OUTPUT: list of symbolic expressions with the desired names EXAMPLES: @@ -613,25 +604,24 @@ def symbolic_velocities(self, left='D', right=None): sage: cart. = R3.chart() sage: D = cart.symbolic_velocities(); D [DX, DY, DZ] - sage: D = cart.symbolic_velocities(left='d', right="/dt"); D + sage: D = cart.symbolic_velocities(left='d', right='/dt'); D Traceback (most recent call last): ... ValueError: The name "dX/dt" is not a valid Python identifier. - sage: D = cart.symbolic_velocities(left='d', right="_dt"); D + sage: D = cart.symbolic_velocities(left='d', right='_dt'); D [dX_dt, dY_dt, dZ_dt] sage: D = cart.symbolic_velocities(left='', right="'"); D Traceback (most recent call last): ... ValueError: The name "X'" is not a valid Python identifier. - sage: D = cart.symbolic_velocities(left='', right="_dot"); D + sage: D = cart.symbolic_velocities(left='', right='_dot'); D [X_dot, Y_dot, Z_dot] sage: R. = manifolds.RealLine() sage: canon_chart = R.default_chart() sage: D = canon_chart.symbolic_velocities() ; D [Dt] - """ from sage.symbolic.ring import var @@ -728,16 +718,15 @@ class RealDiffChart(DiffChart, RealChart): method for computations involving coordinates of the chart; must be one of - - ``'SR'``: Sage's default symbolic engine (Symbolic Ring) - - ``'sympy'``: SymPy - - ``None``: the default of - :class:`~sage.manifolds.calculus_method.CalculusMethod` will be - used + - ``'SR'`` -- Sage's default symbolic engine (Symbolic Ring) + - ``'sympy'`` -- SymPy + - ``None`` -- the default of :class:`~sage.manifolds.calculus_method.CalculusMethod` + will be used - ``names`` -- (default: ``None``) unused argument, except if ``coordinates`` is not provided; it must then be a tuple containing the coordinate symbols (this is guaranteed if the shortcut operator ``<,>`` is used). - - ``coord_restrictions``: Additional restrictions on the coordinates. + - ``coord_restrictions`` -- additional restrictions on the coordinates. A restriction can be any symbolic equality or inequality involving the coordinates, such as ``x > y`` or ``x^2 + y^2 != 0``. The items of the list (or set or frozenset) ``coord_restrictions`` are combined @@ -972,7 +961,6 @@ class RealDiffChart(DiffChart, RealChart): Chart grids can be drawn in 2D or 3D graphics thanks to the method :meth:`~sage.manifolds.chart.RealChart.plot`. - """ def __init__(self, domain, coordinates, calc_method=None, bounds=None, periods=None, coord_restrictions=None): @@ -991,7 +979,6 @@ def __init__(self, domain, coordinates, calc_method=None, sage: assumptions() # assumptions set in X._init_coordinates [x is real, y is real] sage: TestSuite(X).run() - """ RealChart.__init__(self, domain, coordinates, calc_method=calc_method, bounds=bounds, periods=periods, coord_restrictions=coord_restrictions) @@ -1061,7 +1048,6 @@ def restrict(self, subset, restrictions=None): sage: a = M.point((3/2,0)) sage: a in A True - """ if subset == self.domain(): return self @@ -1129,7 +1115,6 @@ class DiffCoordChange(CoordChange): sage: X_to_Y.display() u = x + y v = x - y - """ def __init__(self, chart1, chart2, *transformations): r""" @@ -1150,7 +1135,6 @@ def __init__(self, chart1, chart2, *transformations): .. TODO:: fix _test_pickling - """ CoordChange.__init__(self, chart1, chart2, *transformations) # Jacobian matrix: @@ -1217,7 +1201,6 @@ def jacobian(self): sage: parent(X_to_Y.jacobian()[0,0]) Ring of chart functions on Chart (M, (x, y)) - """ return self._jacobian # has been computed in __init__ @@ -1252,6 +1235,5 @@ def jacobian_det(self): sage: parent(X_to_Y.jacobian_det()) Ring of chart functions on Chart (M, (x, y)) - """ return self._transf.jacobian_det() diff --git a/src/sage/manifolds/differentiable/curve.py b/src/sage/manifolds/differentiable/curve.py index 05e26c17023..8b88a0351eb 100644 --- a/src/sage/manifolds/differentiable/curve.py +++ b/src/sage/manifolds/differentiable/curve.py @@ -63,10 +63,10 @@ class DifferentiableCurve(DiffMap): - ``name`` -- (default: ``None``) string; symbol given to the curve - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the curve; if none is provided, ``name`` will be used - - ``is_isomorphism`` -- (default: ``False``) determines whether the + - ``is_isomorphism`` -- boolean (default: ``False``); determines whether the constructed object is a diffeomorphism; if set to ``True``, then `M` must have dimension one - - ``is_identity`` -- (default: ``False``) determines whether the + - ``is_identity`` -- boolean (default: ``False``); determines whether the constructed object is the identity map; if set to ``True``, then `M` must be the interval `I` @@ -344,7 +344,6 @@ class DifferentiableCurve(DiffMap): sage: tau = Np[FS, 3] sage: tau 1/9*sqrt(5) - """ def __init__(self, parent, coord_expression=None, name=None, latex_name=None, is_isomorphism=False, is_identity=False): @@ -366,7 +365,6 @@ def __init__(self, parent, coord_expression=None, name=None, sage: c = Hom(I,I)({}, is_identity=True) ; c Identity map Id_(0, 2*pi) of the Real interval (0, 2*pi) sage: TestSuite(c).run() - """ if coord_expression is None: coord_functions = None @@ -400,7 +398,6 @@ def _repr_(self): Curve in the 2-dimensional differentiable manifold M sage: M.curve([cos(t), sin(2*t)], (t, 0, 2*pi), name='c') Curve c in the 2-dimensional differentiable manifold M - """ if self._codomain._dim == 1: return DiffMap._repr_(self) @@ -435,7 +432,6 @@ def __reduce__(self): sage: loads(dumps(c)) Curve in the 2-dimensional differentiable manifold M - """ return (type(self), (self.parent(), None, self._name, self._latex_name, self._is_isomorphism, self._is_identity)) @@ -449,9 +445,7 @@ def coord_expr(self, chart=None): - ``chart`` -- (default: ``None``) chart on the curve's codomain; if ``None``, the codomain's default chart is assumed - OUTPUT: - - - symbolic expression representing the curve in the above chart + OUTPUT: symbolic expression representing the curve in the above chart EXAMPLES: @@ -490,7 +484,6 @@ def coord_expr(self, chart=None): sage: c = U.curve({c_spher: (2*(1+cos(t)), t)}, (t, 0, 2*pi), name='c') sage: c.coord_expr(c_cart) (2*cos(t)^2 + 2*cos(t), 2*(cos(t) + 1)*sin(t)) - """ return self.expr(chart1=self._domain.canonical_chart(), chart2=chart) @@ -523,7 +516,6 @@ def __call__(self, t, simplify=True): Point c(t) on the 2-dimensional differentiable manifold M sage: c(t).coord(X) (cos(t), sin(t)) - """ # Case of a point in the domain: if isinstance(t, ManifoldPoint): @@ -643,7 +635,6 @@ def tangent_vector_field(self, name=None, latex_name=None): mapped into the 2-dimensional differentiable manifold M sage: vc.display(c_spher.frame().along(c.restrict(R,A))) c' = -1/5*e^(1/10*t)/(e^(1/5*t) + 1) ∂/∂th + ∂/∂ph - """ vmodule = self._domain.vector_field_module(dest_map=self) if latex_name is None: @@ -730,16 +721,16 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, prange=None, values of the parameters that may appear in the coordinate expression of the curve - - ``color`` -- (default: 'red') color of the drawn curve + - ``color`` -- (default: ``'red'``) color of the drawn curve - - ``style`` -- (default: '-') color of the drawn curve; NB: ``style`` + - ``style`` -- (default: ``'-'``) color of the drawn curve; NB: ``style`` is effective only for 2D plots - ``thickness`` -- (default: 1) thickness of the drawn curve - ``plot_points`` -- (default: 75) number of points to plot the curve - - ``label_axes`` -- (default: ``True``) boolean determining whether the + - ``label_axes`` -- boolean (default: ``True``); determining whether the labels of the coordinate axes of ``chart`` shall be added to the graph; can be set to ``False`` if the graph is 3D and must be superposed with another graph. @@ -878,7 +869,6 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, prange=None, c = R2.curve([a*cos(t) + b, a*sin(t)], (t, 0, 2*pi), name='c') g = c.plot(parameters={a: 2, b: -3}, aspect_ratio=1) sphinx_plot(g) - """ from sage.rings.infinity import Infinity from sage.misc.functional import numerical_approx @@ -1003,7 +993,6 @@ def _graphics(self, plot_curve, ambient_coords, thickness=1, sage: l = [r'$'+latex(x)+r'$', r'$'+latex(y)+r'$'] sage: graph._extra_kwds['axes_labels'] == l True - """ from sage.plot.graphics import Graphics from sage.plot.line import line diff --git a/src/sage/manifolds/differentiable/de_rham_cohomology.py b/src/sage/manifolds/differentiable/de_rham_cohomology.py index 1e38b50f753..53a5b50aaa0 100644 --- a/src/sage/manifolds/differentiable/de_rham_cohomology.py +++ b/src/sage/manifolds/differentiable/de_rham_cohomology.py @@ -95,7 +95,6 @@ class DeRhamCohomologyClass(AlgebraElement): Traceback (most recent call last): ... NotImplementedError: comparison via exact forms is currently not supported - """ def __init__(self, parent, representative): r""" @@ -110,7 +109,6 @@ def __init__(self, parent, representative): sage: omega = M.diff_form(1, [1,1], name='omega', latex_name=r'\omega') sage: u = H(omega) sage: TestSuite(u).run(skip=['_test_eq', '_test_nonzero_equal']) # equality not fully supported yet - """ super().__init__(parent=parent) self._representative = representative @@ -128,7 +126,6 @@ def _repr_(self): [one] sage: H.an_element()._repr_() '[one]' - """ name = self._representative._name if name is None: @@ -151,7 +148,6 @@ def _latex_(self): \left[\omega\right] sage: u._latex_() '\\left[\\omega\\right]' - """ latex_name = self._representative._latex_name if latex_name is None: @@ -178,7 +174,6 @@ def representative(self): sage: u.representative() Mixed differential form omega on the 2-dimensional differentiable manifold M - """ return self._representative @@ -198,7 +193,6 @@ def _add_(self, other): sage: eta = M.diff_form(1, [1,-1], name='eta') sage: H(omega) + H(eta) [omega+eta] - """ return self.parent()(self.representative() + other.representative()) @@ -220,7 +214,6 @@ def cup(self, other): sage: eta = M.diff_form(1, [1,-1], name='eta') sage: H(omega).cup(H(eta)) [omega∧eta] - """ return self * other @@ -238,7 +231,6 @@ def _mul_(self, other): sage: eta = M.diff_form(1, [1,-1], name='eta') sage: H(omega) * H(eta) [omega∧eta] - """ return self.parent()(self.representative().wedge(other.representative())) @@ -255,7 +247,6 @@ def _rmul_(self, scalar): sage: omega = M.diff_form(1, [1,1], name='omega') sage: 1/2*H(omega) [1/2∧omega] - """ return self.parent(scalar * self.representative()) @@ -273,7 +264,6 @@ def _sub_(self, other): sage: eta = M.diff_form(1, [1,-1], name='eta') sage: H(omega) - H(eta) [omega-eta] - """ return self.parent()(self.representative() - other.representative()) @@ -300,7 +290,6 @@ def __eq__(self, other): Traceback (most recent call last): ... NotImplementedError: comparison via exact forms is currently not supported - """ if self is other: return True @@ -360,7 +349,6 @@ class DeRhamCohomologyRing(Parent, UniqueRepresentation): [zero] sage: H.one() [one] - """ def __init__(self, de_rham_complex): r""" @@ -378,7 +366,6 @@ def __init__(self, de_rham_complex): ....: '_test_elements_eq_symmetric', ....: '_test_elements_eq_transitive', ....: '_test_elements_neq']) # equality not fully supported yet - """ base_field = de_rham_complex.base_ring() Parent.__init__(self, base=base_field, category=Algebras(base_field)) @@ -411,7 +398,6 @@ def _element_constructor_(self, x): ... ValueError: Mixed differential form omega on the 2-dimensional differentiable manifold M must be a closed form - """ if isinstance(x, CharacteristicCohomologyClassRingElement): x = x.representative() @@ -445,7 +431,6 @@ def _coerce_map_from_(self, other): TM over the 4-dimensional differentiable manifold M sage: H.has_coerce_map_from(C) True - """ if isinstance(other, CharacteristicCohomologyClassRing): # TODO: we need to be careful if manifolds have boundary! @@ -463,7 +448,6 @@ def _repr_(self): sage: H = C.cohomology(); H De Rham cohomology ring on the 2-dimensional differentiable manifold M - """ desc = "De Rham cohomology ring " if self._module._dest_map is self._manifold.identity_map(): @@ -491,7 +475,6 @@ def _latex_(self): 'H^*_{\\mathrm{dR}}\\left(\\mathcal{M}\\right)' sage: latex(H) # indirect doctest H^*_{\mathrm{dR}}\left(\mathcal{M}\right) - """ latex_name = r"H^*_{\mathrm{dR}}\left(" + self._manifold._latex_name if self._module._dest_map is not self._manifold.identity_map(): @@ -513,7 +496,6 @@ def _an_element_(self): sage: H = C.cohomology() sage: H.an_element() [one] - """ return self.one() @@ -532,7 +514,6 @@ def zero(self): sage: H.zero().representative() Mixed differential form zero on the 2-dimensional differentiable manifold M - """ return self.element_class(self, self._module.zero()) @@ -551,6 +532,5 @@ def one(self): sage: H.one().representative() Mixed differential form one on the 2-dimensional differentiable manifold M - """ return self.element_class(self, self._module.one()) diff --git a/src/sage/manifolds/differentiable/degenerate.py b/src/sage/manifolds/differentiable/degenerate.py index 82de8c39d74..da83139ed6e 100644 --- a/src/sage/manifolds/differentiable/degenerate.py +++ b/src/sage/manifolds/differentiable/degenerate.py @@ -122,7 +122,6 @@ def __init__(self, n, name, metric_name=None, signature=None, sage: M.metric() degenerate metric g on the 3-dimensional degenerate_metric manifold M sage: TestSuite(M).run() - """ if base_manifold and not isinstance(base_manifold, DegenerateManifold): raise TypeError("the argument 'base_manifold' must be a " + @@ -249,7 +248,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` sage: M.metric('g') is M.metric() True - """ if signature is None: signature = self._metric_signature @@ -287,7 +285,7 @@ def open_subset(self, name, latex_name=None, coord_def={}): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none is provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -337,7 +335,6 @@ def open_subset(self, name, latex_name=None, coord_def={}): g = -dx⊗dx + dy⊗dy sage: gV is g.restrict(V) True - """ resu = DegenerateManifold(self._dim, name, metric_name=self._metric_name, @@ -391,7 +388,7 @@ class TangentTensor(TensorFieldParal): Section of the lightcone of the Minkowski space with a hyperplane passing through the origin:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -427,14 +424,13 @@ class TangentTensor(TensorFieldParal): sqrt(u^2 + v^2) ∂/∂t sage: T2(xi.along(Phi)).display() sqrt(u^2 + v^2) ∂/∂t - """ def __init__(self, tensor, embedding, screen=None): r""" TESTS:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -456,7 +452,6 @@ def __init__(self, tensor, embedding, screen=None): Tensor field of type (1,1) along the degenerate hypersurface S embedded in 4-dimensional differentiable manifold M with values on the 4-dimensional Lorentzian manifold M - """ if not isinstance(tensor, TensorField): raise TypeError("the second argument must be a tensor field") @@ -487,7 +482,7 @@ def __call__(self, *args): TESTS:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -509,7 +504,6 @@ def __call__(self, *args): Vector field along the degenerate hypersurface S embedded in 4-dimensional differentiable manifold M with values on the 4-dimensional Lorentzian manifold M - """ for vector in args: try: @@ -534,7 +528,7 @@ def extension(self): Section of the lightcone of the Minkowski space with a hyperplane passing through the origin:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -557,6 +551,5 @@ def extension(self): False sage: T3 is T1 True - """ return self._tensor diff --git a/src/sage/manifolds/differentiable/degenerate_submanifold.py b/src/sage/manifolds/differentiable/degenerate_submanifold.py index 0a146853e22..5b35607d53c 100644 --- a/src/sage/manifolds/differentiable/degenerate_submanifold.py +++ b/src/sage/manifolds/differentiable/degenerate_submanifold.py @@ -59,7 +59,7 @@ being `m` the inertial mass of the star. It can be seen as an open ball in a Lorentzian manifold structure on `\RR^4`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X_M. = \ ....: M.chart(r"t r:(0,oo) th:(0,pi):\theta ph:(0,2*pi):\phi") sage: var('m'); assume(m>0) @@ -77,7 +77,7 @@ A `2`-dimensional degenerate submanifold of a Lorentzian manifold:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: S @@ -174,7 +174,7 @@ class DegenerateSubmanifold(DegenerateManifold, DifferentiableSubmanifold): r""" - Degenerate submanifolds + Degenerate submanifolds. An *embedded (resp. immersed) degenerate submanifold of a proper pseudo-Riemannian manifold* `(M,g)` is an embedded (resp. immersed) @@ -223,7 +223,6 @@ class DegenerateSubmanifold(DegenerateManifold, DifferentiableSubmanifold): :mod:`~sage.manifolds.manifold` and :mod:`~sage.manifolds.differentiable.differentiable_submanifold` - """ def __init__(self, n, name, ambient=None, metric_name=None, signature=None, base_manifold=None, diff_degree=infinity, latex_name=None, @@ -236,12 +235,11 @@ def __init__(self, n, name, ambient=None, metric_name=None, signature=None, A `2`-dimensional degenerate submanifold of a Lorentzian manifold:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: S 2-dimensional degenerate submanifold S embedded in 4-dimensional differentiable manifold M - """ DegenerateManifold.__init__(self, n, name=name, metric_name=metric_name, @@ -295,12 +293,11 @@ def _repr_(self): A `2`-dimensional degenerate submanifold of a Lorentzian manifold:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: S.__repr__() '2-dimensional degenerate submanifold S embedded in 4-dimensional differentiable manifold M' - """ if self._ambient is None: return super(DegenerateManifold, self).__repr__() @@ -319,15 +316,13 @@ def ambient_metric(self): Return the metric of the ambient manifold. The submanifold has to be embedded - OUTPUT: - - - the metric of the ambient manifold + OUTPUT: the metric of the ambient manifold EXAMPLES: The lightcone of the 3D Minkowski space:: - sage: M = Manifold(3, 'M', structure="Lorentzian") + sage: M = Manifold(3, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -338,7 +333,6 @@ def ambient_metric(self): sage: S.set_immersion(Phi, inverse=Phi_inv); S.declare_embedding() sage: S.ambient_metric() Lorentzian metric g on the 3-dimensional Lorentzian manifold M - """ if self._ambient_metric is None: if not self._embedded or not isinstance(self._ambient, @@ -350,7 +344,7 @@ def ambient_metric(self): def default_screen(self): r""" - Return the default screen distribution + Return the default screen distribution. OUTPUT: @@ -361,7 +355,7 @@ def default_screen(self): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -380,7 +374,6 @@ def default_screen(self): screen distribution Sc along the degenerate hypersurface S embedded in 4-dimensional differentiable manifold M mapped into the 4-dimensional Lorentzian manifold M - """ return self._default_screen @@ -397,7 +390,7 @@ def list_of_screens(self): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -416,7 +409,6 @@ def list_of_screens(self): {'Sc': screen distribution Sc along the degenerate hypersurface S embedded in 4-dimensional differentiable manifold M mapped into the 4-dimensional Lorentzian manifold M} - """ return self._screens @@ -446,7 +438,7 @@ def set_transverse(self, rigging=None, normal=None): The lightcone of the 3-dimensional Minkowski space `\RR^3_1`:: - sage: M = Manifold(3, 'M', structure="Lorentzian") + sage: M = Manifold(3, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -458,7 +450,6 @@ def set_transverse(self, rigging=None, normal=None): sage: g = M.metric() sage: g[0,0], g[1,1], g[2,2] = -1,1,1 sage: S.set_transverse(rigging=t) - """ if isinstance(rigging, (list, tuple)): rigging = [elt for elt in rigging] @@ -529,7 +520,7 @@ def screen(self, name, screen, rad, latex_name=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -608,7 +599,7 @@ def induced_metric(self) -> DegenerateMetric: Section of the lightcone of the Minkowski space with a hyperplane passing through the origin:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -622,7 +613,6 @@ def induced_metric(self) -> DegenerateMetric: sage: h = S.induced_metric(); h # long time degenerate metric gamma on the 2-dimensional degenerate submanifold S embedded in 4-dimensional differentiable manifold M - """ if self._induced_metric is None or self._induced_metric._components == {}: self._induced_metric = self.metric() @@ -647,7 +637,7 @@ def first_fundamental_form(self): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -663,7 +653,6 @@ def first_fundamental_form(self): sage: U = M.vector_field(); U[2] = 1; V = M.vector_field(); V[3] = 1 sage: Sc = S.screen('Sc', (U,V), xi); # long time sage: h = S.first_fundamental_form() # long time - """ if self._first_fundamental_form is None: g = self.ambient_metric() @@ -705,7 +694,7 @@ def _ambient_decomposition(self, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -726,7 +715,6 @@ def _ambient_decomposition(self, screen=None): [Vector field on the 4-dimensional Lorentzian manifold M], (), [Vector field N on the 4-dimensional Lorentzian manifold M]] - """ try: normal = self._transverse['normal'] @@ -768,15 +756,13 @@ def _adapted_frame_(self, screen=None): :class:`~sage.manifolds.differentiable.degenerate_submanifold.Screen`; if ``None`` default screen is used. - OUTPUT: - - - a frame on the ambient manifold + OUTPUT: a frame on the ambient manifold EXAMPLES: A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -792,7 +778,6 @@ def _adapted_frame_(self, screen=None): sage: U = M.vector_field(); U[2] = 1; V = M.vector_field(); V[3] = 1 sage: Sc = S.screen('Sc', (U,V), xi); # long time sage: T = S._adapted_frame_(); # long time - """ if screen is None: @@ -862,15 +847,13 @@ def adapted_frame(self, screen=None): :class:`~sage.manifolds.differentiable.degenerate_submanifold.Screen`. if ``None`` default screen is used. - OUTPUT: - - - a frame on the ambient manifold along the submanifold + OUTPUT: a frame on the ambient manifold along the submanifold EXAMPLES: A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -888,7 +871,6 @@ def adapted_frame(self, screen=None): sage: T = S.adapted_frame(); T # long time Vector frame (S, (vv_0,vv_1,vv_2,vv_3)) with values on the 4-dimensional Lorentzian manifold M - """ e = self._adapted_frame_(screen).along(self.immersion()) b = e.dual_basis() @@ -937,7 +919,7 @@ def second_fundamental_form(self, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -955,7 +937,6 @@ def second_fundamental_form(self, screen=None): sage: B = S.second_fundamental_form(); # long time sage: B.display() # long time B = 0 - """ if self._ambient._dim-self._dim != 1: raise ValueError("'second_fundamental_form' is defined" + @@ -999,7 +980,7 @@ def projection(self, tensor, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1015,7 +996,6 @@ def projection(self, tensor, screen=None): sage: U = M.vector_field(); U[2] = 1; V = M.vector_field(); V[3] = 1 sage: Sc = S.screen('Sc', (U,V), xi); # long time sage: U1 = S.projection(U) # long time - """ if tensor.tensor_type()[0] != 1: raise NotImplementedError("``projection`` is implemented only for " @@ -1042,7 +1022,7 @@ def screen_projection(self, tensor, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1058,7 +1038,6 @@ def screen_projection(self, tensor, screen=None): sage: U = M.vector_field(); U[2] = 1; V = M.vector_field(); V[3] = 1 sage: Sc = S.screen('Sc', (U,V), xi); # long time sage: U1 = S.screen_projection(U); # long time - """ if tensor.tensor_type()[0] != 1: raise NotImplementedError("``projection`` is implemented only for " + @@ -1108,7 +1087,7 @@ def weingarten_map(self, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1127,7 +1106,6 @@ def weingarten_map(self, screen=None): sage: W = S.weingarten_map(); # long time sage: W.display() # long time nabla_g(xi)|X(S) = 0 - """ im = self.immersion() @@ -1165,7 +1143,7 @@ def shape_operator(self, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1184,7 +1162,6 @@ def shape_operator(self, screen=None): sage: SO = S.shape_operator(); # long time sage: SO.display() # long time A^* = 0 - """ if screen is None: screen = self.default_screen() @@ -1214,15 +1191,13 @@ def gauss_curvature(self, screen=None): :class:`~sage.manifolds.differentiable.degenerate_submanifold.Screen`. If ``None`` the default screen is used. - OUTPUT: - - - a scalar function on ``self`` + OUTPUT: a scalar function on ``self`` EXAMPLES: A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1241,7 +1216,6 @@ def gauss_curvature(self, screen=None): sage: K.display() # long time S → ℝ (u, v, w) ↦ 0 - """ if self._ambient._dim-self._dim != 1: raise ValueError("'gauss_curvature' is defined" @@ -1277,7 +1251,7 @@ def principal_directions(self, screen=None): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1295,7 +1269,6 @@ def principal_directions(self, screen=None): sage: PD = S.principal_directions() # long time sage: PD[2][0].display(T) # long time e_2 = xi - """ if self._codim != 1: raise ValueError("'principal directions' is defined" + @@ -1334,15 +1307,13 @@ def mean_curvature(self, screen=None): :class:`~sage.manifolds.differentiable.degenerate_submanifold.Screen`. If ``None`` the default screen is used. - OUTPUT: - - - the mean curvature, as a scalar field on the submanifold + OUTPUT: the mean curvature, as a scalar field on the submanifold EXAMPLES: A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1363,7 +1334,6 @@ def mean_curvature(self, screen=None): sage: m.display() # long time S → ℝ (u, v, w) ↦ 0 - """ if self._codim != 1: raise ValueError("'mean_curvature' is defined" + @@ -1395,7 +1365,7 @@ def is_tangent(self, v): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1415,7 +1385,6 @@ def is_tangent(self, v): True sage: S.is_tangent(v.along(Phi)) # long time False - """ g = self.ambient_metric() im = self.immersion() @@ -1459,7 +1428,7 @@ class Screen(VectorFieldModule): The horizon of the Schwarzschild black hole:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X_M. = \ ....: M.chart(r"t r:(0,oo) th:(0,pi):\theta ph:(0,2*pi):\phi") sage: var('m'); assume(m>0) @@ -1509,7 +1478,7 @@ def __init__(self, submanifold, name, screen, rad, latex_name=None): TESTS:: - sage: M = Manifold(3, 'M', structure="Lorentzian") + sage: M = Manifold(3, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1524,7 +1493,6 @@ def __init__(self, submanifold, name, screen, rad, latex_name=None): sage: xi = M.vector_field(); xi[0] = sqrt(x^2+y^2); xi[1] = x; xi[2] = y sage: U = M.vector_field(); U[1] = -y; U[2] = x sage: Sc = S.screen('Sc', U, xi); - """ if not isinstance(submanifold, DegenerateSubmanifold): raise TypeError("the first argument must be a null submanifold") @@ -1546,7 +1514,7 @@ def _repr_(self): TESTS:: - sage: M = Manifold(3, 'M', structure="Lorentzian") + sage: M = Manifold(3, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1564,7 +1532,6 @@ def _repr_(self): 'screen distribution Sc along the degenerate hypersurface S embedded in 3-dimensional differentiable manifold M mapped into the 3-dimensional Lorentzian manifold M' - """ description = "screen distribution "+self._name if self._dest_map is self._domain.identity_map(): @@ -1590,7 +1557,7 @@ def __getitem__(self, i): TESTS:: - sage: M = Manifold(3, 'M', structure="Lorentzian") + sage: M = Manifold(3, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(2, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1628,7 +1595,7 @@ def normal_tangent_vector(self): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1646,7 +1613,6 @@ def normal_tangent_vector(self): sage: Sc = S.screen('Sc', (U,V), xi); # long time sage: Rad = Sc.normal_tangent_vector(); Rad.display() # long time xi = ∂/∂t + ∂/∂x - """ rad = [elt.along(self._domain.immersion()) for elt in self._rad] if self._domain._codim == 1: @@ -1672,7 +1638,7 @@ def rigging(self): A degenerate hyperplane the 4-dimensional Minkowski space `\RR^4_1`:: - sage: M = Manifold(4, 'M', structure="Lorentzian") + sage: M = Manifold(4, 'M', structure='Lorentzian') sage: X. = M.chart() sage: S = Manifold(3, 'S', ambient=M, structure='degenerate_metric') sage: X_S. = S.chart() @@ -1690,7 +1656,6 @@ def rigging(self): sage: Sc = S.screen('Sc', (U,V), xi); # long time sage: rig = Sc.rigging(); rig.display() # long time N = -1/2 ∂/∂t + 1/2 ∂/∂x - """ im = self._domain.immersion() rig = [elt.along(im) for elt in self._domain._transverse['rigging']] diff --git a/src/sage/manifolds/differentiable/diff_form.py b/src/sage/manifolds/differentiable/diff_form.py index bb1c0e3d341..ae924713ffd 100644 --- a/src/sage/manifolds/differentiable/diff_form.py +++ b/src/sage/manifolds/differentiable/diff_form.py @@ -22,7 +22,7 @@ - Eric Gourgoulhon, Michal Bejger (2013, 2014): initial version - Joris Vankerschaver (2010): developed a previous class, ``DifferentialForm`` (cf. :issue:`24444`), which inspired the storage of the - non-zero components as a dictionary whose keys are the indices. + nonzero components as a dictionary whose keys are the indices. - Travis Scrimshaw (2016): review tweaks REFERENCES: @@ -278,7 +278,6 @@ class DiffForm(TensorField): f*a = y*(-x**2 - 2*x*y - y**2) dx + x*(x**2 + 2*x*y + y**2) dy sage: s.display(eV) f*a = u**2*v/2 du - u**3/2 dv - """ def __init__(self, vector_field_module, degree, name=None, latex_name=None): r""" @@ -319,7 +318,6 @@ def __init__(self, vector_field_module, degree, name=None, latex_name=None): .. TODO:: Fix ``_test_pickling`` (in the superclass :class:`TensorField`). - """ TensorField.__init__(self, vector_field_module, (0, degree), name=name, latex_name=latex_name, antisym=range(degree), @@ -343,7 +341,6 @@ def _repr_(self): sage: b = M.diff_form(2) sage: b._repr_() '2-form on the 3-dimensional differentiable manifold M' - """ description = "{}-form ".format(self._tensor_rank) if self._name is not None: @@ -365,7 +362,6 @@ def _new_instance(self): True sage: a1.parent() is a.parent() True - """ return type(self)(self._vmodule, self._tensor_rank) @@ -378,7 +374,6 @@ def _del_derived(self): sage: M = Manifold(3, 'M') sage: a = M.diff_form(2, name='a') sage: a._del_derived() - """ TensorField._del_derived(self) self.exterior_derivative.clear_cache() @@ -445,7 +440,6 @@ def exterior_derivative(self) -> DiffForm: sage: v.add_comp_by_continuation(e_uv, U.intersection(V), c_uv) sage: a.lie_der(v) == v.contract(diff(a)) + diff(a(v)) # long time True - """ from sage.tensor.modules.format_utilities import ( format_unop_txt, @@ -528,7 +522,6 @@ def wedge(self, other: DiffForm) -> DiffForm: sage: t = a.wedge(f) sage: t.display() f*a = x*y dx + x^2 dy - """ if other._tensor_rank == 0: return self * other @@ -594,9 +587,7 @@ def degree(self) -> int: r""" Return the degree of ``self``. - OUTPUT: - - - integer `p` such that the differential form is a `p`-form + OUTPUT: integer `p` such that the differential form is a `p`-form EXAMPLES:: @@ -609,7 +600,6 @@ def degree(self) -> int: 1-form on the 3-dimensional differentiable manifold M sage: b.degree() 1 - """ return self._tensor_rank @@ -645,7 +635,7 @@ def hodge_dual( INPUT: - - ``nondegenerate_tensor``: a non-degenerate bilinear form defined on the same manifold + - ``nondegenerate_tensor`` -- a non-degenerate bilinear form defined on the same manifold as the current differential form; must be an instance of :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric` or :class:`~sage.manifolds.differentiable.symplectic_form.SymplecticForm`. @@ -898,7 +888,6 @@ def interior_product(self, qvect): True sage: s.restrict(V) == 2 * a[[e_uv,1,2]] * b[[e_uv,1,2]] True - """ from sage.tensor.modules.format_utilities import is_atomic if self._domain.is_subset(qvect._domain): @@ -1033,7 +1022,7 @@ class DiffFormParal(FreeModuleAltForm, TensorFieldParal, DiffForm): sage: type(a.comp()) - Setting a component with repeated indices to a non-zero value + Setting a component with repeated indices to a nonzero value results in an error:: sage: a[1,1] = 3 @@ -1249,7 +1238,6 @@ class DiffFormParal(FreeModuleAltForm, TensorFieldParal, DiffForm): [18 15 12] sage: c.symmetries() # c has no symmetries: no symmetry; no antisymmetry - """ def __init__(self, vector_field_module: VectorFieldModule, degree: int, name: Optional[str] = None, latex_name: Optional[str] = None): @@ -1284,7 +1272,6 @@ def __init__(self, vector_field_module: VectorFieldModule, degree: int, name: Op sage: a = M.diff_form(2, [[0, x*y], [-x*y, 0]], name='a') sage: a.display() a = x*y dx∧dy - """ FreeModuleAltForm.__init__(self, vector_field_module, degree, name=name, latex_name=latex_name) @@ -1313,7 +1300,6 @@ def _repr_(self): sage: b = M.diff_form(2) sage: b._repr_() '2-form on the 3-dimensional differentiable manifold M' - """ description = "{}-form ".format(self._tensor_rank) if self._name is not None: @@ -1336,7 +1322,6 @@ def _new_instance(self): True sage: a1.parent() is a.parent() True - """ return type(self)(self._fmodule, self._tensor_rank) @@ -1351,7 +1336,6 @@ def _init_derived(self): sage: X. = M.chart() # makes M parallelizable sage: a = M.diff_form(2, name='a') sage: a._init_derived() - """ TensorFieldParal._init_derived(self) @@ -1361,7 +1345,7 @@ def _del_derived(self, del_restrictions: bool = True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the restrictions of ``self`` to subdomains are deleted TESTS:: @@ -1370,7 +1354,6 @@ def _del_derived(self, del_restrictions: bool = True): sage: X. = M.chart() # makes M parallelizable sage: a = M.diff_form(2, name='a') sage: a._del_derived() - """ TensorFieldParal._del_derived(self, del_restrictions=del_restrictions) self.exterior_derivative.clear_cache() @@ -1400,7 +1383,6 @@ def __call__(self, *args): True sage: s == a(u,v) # indirect doctest True - """ return TensorFieldParal.__call__(self, *args) @@ -1455,7 +1437,6 @@ def exterior_derivative(self) -> DiffFormParal: sage: v = M.vector_field(-y, x, t, z, name='v') sage: a.lie_der(v) == v.contract(diff(a)) + diff(a(v)) # long time True - """ from sage.tensor.modules.format_utilities import (format_unop_txt, format_unop_latex) @@ -1559,7 +1540,6 @@ def wedge(self, other): sage: t = a.wedge(f) sage: t.display() f*a = 2*x dx + (x^2 + x) dy + x*y*z dz - """ if other._tensor_rank == 0: return self * other @@ -1658,7 +1638,6 @@ def interior_product(self, qvect): sage: f = X.coframe()[2] # 1-form dy sage: f.interior_product(v) Scalar field zero on the 3-dimensional differentiable manifold M - """ if self._domain.is_subset(qvect._domain): if not self._ambient_domain.is_subset(qvect._ambient_domain): diff --git a/src/sage/manifolds/differentiable/diff_form_module.py b/src/sage/manifolds/differentiable/diff_form_module.py index e5497762adb..291893b6cc9 100644 --- a/src/sage/manifolds/differentiable/diff_form_module.py +++ b/src/sage/manifolds/differentiable/diff_form_module.py @@ -142,7 +142,7 @@ class DiffFormModule(UniqueRepresentation, Parent): sage: z is A.zero() True - while non-zero elements are constructed by providing their components in a + while nonzero elements are constructed by providing their components in a given vector frame:: sage: a = A([[0,3*x],[-3*x,0]], frame=eU, name='a') ; a @@ -254,7 +254,6 @@ class DiffFormModule(UniqueRepresentation, Parent): manifold M sage: a_U.display(eU) a = 3*x dx∧dy - """ Element = DiffForm @@ -284,7 +283,6 @@ def __init__(self, vector_field_module, degree): In the above test suite, ``_test_elements`` is skipped because of the ``_test_pickling`` error of the elements (to be fixed in :class:`sage.manifolds.differentiable.tensorfield.TensorField`) - """ domain = vector_field_module._domain dest_map = vector_field_module._dest_map @@ -333,7 +331,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, a = x*y dx∧dy sage: A(0) is A.zero() True - """ try: if comp.is_trivial_zero(): @@ -386,7 +383,6 @@ def _an_element_(self): sage: A = M.diff_form_module(2) sage: A._an_element_() 2-form on the 2-dimensional differentiable manifold M - """ resu = self.element_class(self._vmodule, self._degree) for oc in self._domain.open_covers(trivial=False): @@ -418,7 +414,6 @@ def _coerce_map_from_(self, other): True sage: A2._coerce_map_from_(A2U) False - """ if isinstance(other, (DiffFormModule, DiffFormFreeModule)): # coercion by domain restriction @@ -445,7 +440,6 @@ def zero(self): sage: A2 = M.diff_form_module(2) sage: A2.zero() 2-form zero on the 3-dimensional differentiable manifold M - """ zero = self._element_constructor_(name='zero', latex_name='0') for frame in self._domain._frames: @@ -469,7 +463,6 @@ def _repr_(self): sage: A2 Module Omega^2(M) of 2-forms on the 3-dimensional differentiable manifold M - """ description = "Module " if self._name is not None: @@ -494,7 +487,6 @@ def _latex_(self): '\\Omega^{2}\\left(\\mathcal{M}\\right)' sage: latex(A2) # indirect doctest \Omega^{2}\left(\mathcal{M}\right) - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -530,7 +522,6 @@ def base_module(self): sage: A2U.base_module() Module X(U) of vector fields on the Open subset U of the 3-dimensional differentiable manifold M - """ return self._vmodule @@ -563,9 +554,7 @@ def degree(self): r""" Return the degree of the differential forms in ``self``. - OUTPUT: - - - integer `p` such that ``self`` is a set of `p`-forms + OUTPUT: integer `p` such that ``self`` is a set of `p`-forms EXAMPLES:: @@ -576,7 +565,6 @@ def degree(self): 2 sage: M.diff_form_module(3).degree() 3 - """ return self._degree @@ -665,7 +653,7 @@ class DiffFormFreeModule(ExtPowerDualFreeModule): sage: A(0) is A.zero() True - while non-zero elements are constructed by providing their components + while nonzero elements are constructed by providing their components in a given vector frame:: sage: comp = [[0,3*x,-z],[-3*x,0,4],[z,-4,0]] @@ -741,7 +729,6 @@ class DiffFormFreeModule(ExtPowerDualFreeModule): manifold M sage: a_U.display() a = 3*x dx∧dy - z dx∧dz + 4 dy∧dz - """ Element = DiffFormParal @@ -759,7 +746,6 @@ def __init__(self, vector_field_module, degree): Free module Omega^2(M) of 2-forms on the 3-dimensional differentiable manifold M sage: TestSuite(A).run() - """ domain = vector_field_module._domain dest_map = vector_field_module._dest_map @@ -806,7 +792,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, sage: f = M.scalar_field(x) sage: f in A False - """ try: if comp.is_trivial_zero(): @@ -870,7 +855,6 @@ def _coerce_map_from_(self, other): True sage: A1._coerce_map_from_(M.tensor_field_module((1,0))) False - """ if isinstance(other, (DiffFormModule, DiffFormFreeModule)): # coercion by domain restriction @@ -899,7 +883,6 @@ def _repr_(self): sage: A Free module Omega^2(M) of 2-forms on the 3-dimensional differentiable manifold M - """ description = "Free module " if self._name is not None: @@ -994,7 +977,7 @@ class VectorFieldDualFreeModule(DiffFormFreeModule): sage: A(0) is A.zero() True - while non-zero elements are constructed by providing their components + while nonzero elements are constructed by providing their components in a given vector frame:: sage: comp = [3*x,-z,4] @@ -1056,7 +1039,6 @@ def __init__(self, vector_field_module): sage: A = M.vector_field_module().dual(); A Free module Omega^1(M) of 1-forms on the 3-dimensional differentiable manifold M sage: TestSuite(A).run() - """ DiffFormFreeModule.__init__(self, vector_field_module, 1) @@ -1072,6 +1054,5 @@ def tensor_type(self): Free module Omega^1(M) of 1-forms on the 3-dimensional differentiable manifold M sage: A.tensor_type() (0, 1) - """ return (0, 1) diff --git a/src/sage/manifolds/differentiable/diff_map.py b/src/sage/manifolds/differentiable/diff_map.py index d684d064827..c238bcd54d5 100644 --- a/src/sage/manifolds/differentiable/diff_map.py +++ b/src/sage/manifolds/differentiable/diff_map.py @@ -82,11 +82,11 @@ class is - ``name`` -- (default: ``None``) name given to the differentiable map - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the differentiable map; if ``None``, the LaTeX symbol is set to ``name`` - - ``is_isomorphism`` -- (default: ``False``) determines whether the - constructed object is a isomorphism (i.e. a diffeomorphism); if set to + - ``is_isomorphism`` -- boolean (default: ``False``); determines whether the + constructed object is a isomorphism (i.e. a diffeomorphism). If set to ``True``, then the manifolds `M` and `N` must have the same dimension. - - ``is_identity`` -- (default: ``False``) determines whether the - constructed object is the identity map; if set to ``True``, + - ``is_identity`` -- boolean (default: ``False``); determines whether the + constructed object is the identity map. If set to ``True``, then `N` must be `M` and the entry ``coord_functions`` is not used. .. NOTE:: @@ -397,7 +397,6 @@ class is True sage: ~id is id True - """ def __init__(self, parent, coord_functions=None, name=None, latex_name=None, is_isomorphism=False, is_identity=False): @@ -426,7 +425,6 @@ def __init__(self, parent, coord_functions=None, name=None, Id_M: M → M (x, y) ↦ (x, y) sage: TestSuite(f).run() - """ ContinuousMap.__init__(self, parent, coord_functions=coord_functions, name=name, latex_name=latex_name, @@ -465,7 +463,6 @@ def _repr_(self): sage: f = Hom(M,M)({}, name='f', is_identity=True) sage: f._repr_() 'Identity map f of the 2-dimensional differentiable manifold M' - """ if self._is_identity: return "Identity map " + self._name + \ @@ -499,7 +496,6 @@ def _init_derived(self): sage: f._restrictions {} sage: f._inverse - """ ContinuousMap._init_derived(self) # derived quantities of the mother class @@ -522,7 +518,6 @@ def _del_derived(self): Diffeomorphism of the 2-dimensional differentiable manifold M sage: f._del_derived() sage: f._inverse # has been set to None by _del_derived() - """ ContinuousMap._del_derived(self) # derived quantities of the mother # class @@ -596,7 +591,6 @@ def differential(self, point: ManifoldPoint) -> FiniteRankFreeModuleMorphism: [ 1 -2] [-1 2] [ 4 -3] - """ image_point = self(point) tsp_image = image_point._manifold.tangent_space(image_point) @@ -776,7 +770,6 @@ def differential_functions(self, chart1=None, chart2=None): sage: bool( JJ[2,0] == J[2][0].expr() ) True - """ dom1 = self._domain dom2 = self._codomain @@ -821,9 +814,7 @@ def jacobian_matrix(self, chart1=None, chart2=None): `\Phi`; if none is provided, the codomain's default chart is assumed - OUTPUT: - - - the matrix `J` defined above + OUTPUT: the matrix `J` defined above EXAMPLES: @@ -845,7 +836,6 @@ def jacobian_matrix(self, chart1=None, chart2=None): [ 2*x -3*y^2] sage: J.parent() Full MatrixSpace of 3 by 2 dense matrices over Symbolic Ring - """ from sage.matrix.constructor import matrix diff_funct = self.differential_functions(chart1, chart2) @@ -954,7 +944,6 @@ def pullback(self, tensor_or_codomain_subset, name=None, latex_name=None): sage: gM = F.pullback(g) sage: gM.display() (2*cos(t) + 2) dt⊗dt - """ if not hasattr(tensor_or_codomain_subset, '_domain'): return super().pullback(tensor_or_codomain_subset, @@ -985,10 +974,7 @@ def _pullback_chart(diff_map, tensor, chart1, chart2): - ``chart1`` -- chart on the domain of ``diff_map`` - ``chart2`` -- chart on the codomain of ``diff_map`` - OUTPUT: - - - the pull back of ``tensor`` by ``diff_map`` - + OUTPUT: the pull back of ``tensor`` by ``diff_map`` """ dom1 = diff_map._domain dom2 = diff_map._codomain @@ -1209,7 +1195,6 @@ def pushforward(self, tensor): the 3-dimensional differentiable manifold R^3 sage: pu.display() Psi_*(u) = -sin(t) ∂/∂x + cos(t) ∂/∂y + ∂/∂z - """ from sage.manifolds.differentiable.tensorfield_paral import TensorFieldParal from sage.tensor.modules.comp import ( diff --git a/src/sage/manifolds/differentiable/differentiable_submanifold.py b/src/sage/manifolds/differentiable/differentiable_submanifold.py index 06e861c98d0..51dd2962557 100644 --- a/src/sage/manifolds/differentiable/differentiable_submanifold.py +++ b/src/sage/manifolds/differentiable/differentiable_submanifold.py @@ -158,7 +158,6 @@ class DifferentiableSubmanifold(DifferentiableManifold, TopologicalSubmanifold): :mod:`~sage.manifolds.manifold` and :mod:`~sage.manifolds.topological_submanifold` - """ def __init__(self, n, name, field, structure, ambient=None, base_manifold=None, diff_degree=infinity, @@ -180,7 +179,6 @@ def __init__(self, n, name, field, structure, ambient=None, \Sigma sage: S.start_index() 1 - """ DifferentiableManifold.__init__(self, n, name, field, structure, base_manifold=base_manifold, @@ -212,7 +210,6 @@ def _repr_(self): sage: N 2-dimensional differentiable submanifold N embedded in the 3-dimensional differentiable manifold M - """ if self is not self._manifold: return "Open subset {} of the {}".format(self._name, self._manifold) @@ -240,7 +237,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none is provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -249,14 +246,12 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): - ``supersets`` -- (default: only ``self``) list of sets that the new open subset is a subset of - OUTPUT: - - - the open subset, as an instance of :class:`DifferentiableSubmanifold` + OUTPUT: the open subset, as an instance of :class:`DifferentiableSubmanifold` EXAMPLES:: - sage: M = Manifold(3, 'M', structure="differentiable") - sage: N = Manifold(2, 'N', ambient=M, structure="differentiable"); N + sage: M = Manifold(3, 'M', structure='differentiable') + sage: N = Manifold(2, 'N', ambient=M, structure='differentiable'); N 2-dimensional differentiable submanifold N immersed in the 3-dimensional differentiable manifold M sage: S = N.subset('S'); S @@ -281,7 +276,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): Open subset O of the 2-dimensional differentiable submanifold N embedded in the 3-dimensional differentiable manifold M - """ resu = DifferentiableSubmanifold(self._dim, name, self._field, self._structure, ambient=self._ambient, diff --git a/src/sage/manifolds/differentiable/examples/euclidean.py b/src/sage/manifolds/differentiable/examples/euclidean.py index 6a4b0bd2899..555881193cf 100644 --- a/src/sage/manifolds/differentiable/examples/euclidean.py +++ b/src/sage/manifolds/differentiable/examples/euclidean.py @@ -641,7 +641,6 @@ class EuclideanSpace(PseudoRiemannianManifold): Riemannian metric g on the 4-dimensional Euclidean space E^4 sage: g.display() g = dx1⊗dx1 + dx2⊗dx2 + dx3⊗dx3 + dx4⊗dx4 - """ @staticmethod def __classcall_private__(cls, n=None, name=None, latex_name=None, @@ -762,7 +761,6 @@ def __init__(self, n, name=None, latex_name=None, sage: E.metric() Riemannian metric g on the 4-dimensional Euclidean space E^4 sage: TestSuite(E).run() - """ if name is None: name = 'E^{}'.format(n) @@ -812,7 +810,6 @@ def _repr_(self): '4-dimensional Euclidean space E^4' sage: E # indirect doctest 4-dimensional Euclidean space E^4 - """ return "{}-dimensional Euclidean space {}".format(self._dim, self._name) @@ -834,7 +831,6 @@ def _first_ngens(self, n): sage: E. = EuclideanSpace() sage: E._first_ngens(2) (u, v) - """ return self._def_chart[:] @@ -847,7 +843,6 @@ def _init_cartesian(self, symbols): sage: E = EuclideanSpace(2) sage: E._init_cartesian('x y') - """ chart = self.chart(coordinates=symbols) self._cartesian_chart = chart @@ -900,7 +895,6 @@ def cartesian_coordinates(self, symbols=None, names=None): (x1, x2, x3, x4) sage: latex(X[:]) \left({x_{1}}, {x_{2}}, {x_{3}}, {x_{4}}\right) - """ if self._cartesian_chart is None: if symbols is None: @@ -920,9 +914,7 @@ def cartesian_frame(self): Return the orthonormal vector frame associated with Cartesian coordinates. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.vectorframe.CoordFrame` + OUTPUT: :class:`~sage.manifolds.differentiable.vectorframe.CoordFrame` EXAMPLES:: @@ -940,7 +932,6 @@ def cartesian_frame(self): sage: E.cartesian_frame() is E.cartesian_coordinates().frame() True - """ if self._cartesian_chart is None: self.cartesian_coordinates() # creates the Cartesian chart @@ -970,7 +961,6 @@ def dist(self, p, q): sqrt(5) sage: p.dist(q) # indirect doctest sqrt(5) - """ chart = self.cartesian_coordinates() coords_p = chart(p) @@ -1040,7 +1030,6 @@ def sphere(self, radius=1, center=None, name=None, latex_name=None, See :class:`~sage.manifolds.differentiable.examples.sphere.Sphere` for more examples. - """ n = self._dim if n == 1: @@ -1171,7 +1160,6 @@ class EuclideanPlane(EuclideanSpace): .. SEEALSO:: :ref:`EuclideanSpace_example1` - """ def __init__(self, name=None, latex_name=None, coordinates='Cartesian', symbols=None, metric_name='g', metric_latex_name=None, @@ -1186,7 +1174,6 @@ def __init__(self, name=None, latex_name=None, coordinates='Cartesian', sage: E.metric() Riemannian metric g on the Euclidean plane E^2 sage: TestSuite(E).run() - """ if coordinates not in ['Cartesian', 'polar']: raise TypeError("unknown coordinate type") @@ -1227,7 +1214,6 @@ def _repr_(self): sage: E = EuclideanSpace(2, name='E') sage: E._repr_() 'Euclidean plane E' - """ return "Euclidean plane {}".format(self._name) @@ -1244,7 +1230,6 @@ def _init_polar(self, symbols): sage: E._init_polar(r"R Phi:\Phi") sage: E.atlas() [Chart (E^2, (x, y)), Chart (E^2, (R, Phi))] - """ coords = symbols.split() # list of strings, one per coordinate # Adding the coordinate ranges: @@ -1299,7 +1284,6 @@ def _transition_polar_cartesian(self): sage: E.change_of_frame(polar_f, cart_f)[:, polar] [ cos(ph) sin(ph)] [-sin(ph) cos(ph)] - """ # Transition maps polar chart <-> Cartesian chart chart_cart = self._cartesian_chart @@ -1416,7 +1400,6 @@ def cartesian_coordinates(self, symbols=None, names=None): sage: cartesian = E.cartesian_coordinates(symbols='u v') sage: u, v = cartesian[:] - """ if self._cartesian_chart is None: if symbols is None: @@ -1507,7 +1490,6 @@ def polar_coordinates(self, symbols=None, names=None): sage: E.polar_coordinates(symbols=r"R Th:\Theta") Chart (E^2, (r, th)) - """ if self._polar_chart is None: if symbols is None: @@ -1561,7 +1543,6 @@ def polar_frame(self): ....: e.display(E.polar_coordinates()) e_r = ∂/∂r e_ph = 1/r ∂/∂ph - """ if self._polar_frame is None: # create the polar chart and the associated orthonormal frame @@ -1700,7 +1681,6 @@ class Euclidean3dimSpace(EuclideanSpace): .. SEEALSO:: :ref:`EuclideanSpace_example2` - """ def __init__(self, name=None, latex_name=None, coordinates='Cartesian', symbols=None, metric_name='g', metric_latex_name=None, @@ -1715,7 +1695,6 @@ def __init__(self, name=None, latex_name=None, coordinates='Cartesian', sage: E.metric() Riemannian metric g on the Euclidean space E^3 sage: TestSuite(E).run() - """ if coordinates not in ['Cartesian', 'spherical', 'cylindrical']: raise TypeError("unknown coordinate type") @@ -1765,7 +1744,6 @@ def _repr_(self): sage: E = EuclideanSpace(3, name='E') sage: E._repr_() 'Euclidean space E' - """ return "Euclidean space {}".format(self._name) @@ -1782,7 +1760,6 @@ def _init_spherical(self, symbols): sage: E._init_spherical(r"R Th:\Theta Ph:\Phi") sage: E.atlas() [Chart (E^3, (x, y, z)), Chart (E^3, (R, Th, Ph))] - """ coords = symbols.split() # list of strings, one per coordinate # Adding the coordinate ranges: @@ -1826,7 +1803,6 @@ def _init_cylindrical(self, symbols): sage: E._init_cylindrical(r"r ph:\phi z") sage: E.atlas() [Chart (E^3, (x, y, z)), Chart (E^3, (r, ph, z))] - """ coords = symbols.split() # list of strings, one per coordinate # Adding the coordinate ranges: @@ -1890,7 +1866,6 @@ def _transition_spherical_cartesian(self): [cos(ph)*sin(th) sin(ph)*sin(th) cos(th)] [cos(ph)*cos(th) cos(th)*sin(ph) -sin(th)] [ -sin(ph) cos(ph) 0] - """ # Transition maps spherical chart <-> Cartesian chart chart_cart = self._cartesian_chart @@ -1970,7 +1945,6 @@ def _transition_cylindrical_cartesian(self): [ cos(ph) sin(ph) 0] [-sin(ph) cos(ph) 0] [ 0 0 1] - """ # Transition maps cylindrical chart <-> Cartesian chart chart_cart = self._cartesian_chart @@ -2048,7 +2022,6 @@ def _transition_spherical_cylindrical(self): [ sin(th) 0 cos(th)] [ cos(th) 0 -sin(th)] [ 0 1 0] - """ # Transition maps spherical chart <-> cylindrical chart cylind = self._cylindrical_chart @@ -2159,7 +2132,6 @@ def cartesian_coordinates(self, symbols=None, names=None): sage: cartesian = E.cartesian_coordinates(symbols='u v w') sage: u, v, w = cartesian[:] - """ if self._cartesian_chart is None: if symbols is None: @@ -2256,7 +2228,6 @@ def spherical_coordinates(self, symbols=None, names=None): sage: E.spherical_coordinates(symbols=r"r th:\theta ph:\phi") Chart (E^3, (R, T, F)) - """ if self._spherical_chart is None: if symbols is None: @@ -2281,9 +2252,7 @@ def spherical_frame(self): Return the orthonormal vector frame associated with spherical coordinates. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame` + OUTPUT: :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame` EXAMPLES:: @@ -2315,7 +2284,6 @@ def spherical_frame(self): e_r = ∂/∂r e_th = 1/r ∂/∂th e_ph = 1/(r*sin(th)) ∂/∂ph - """ if self._spherical_frame is None: # create the spherical chart and the associated orthonormal frame @@ -2404,7 +2372,6 @@ def cylindrical_coordinates(self, symbols=None, names=None): sage: E.cylindrical_coordinates(symbols=r"rh:\rho ph:\phi z") Chart (E^3, (R, Phi, Z)) - """ if self._cylindrical_chart is None: if symbols is None: @@ -2429,9 +2396,7 @@ def cylindrical_frame(self): Return the orthonormal vector frame associated with cylindrical coordinates. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame` + OUTPUT: :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame` EXAMPLES:: @@ -2463,7 +2428,6 @@ def cylindrical_frame(self): e_rh = ∂/∂rh e_ph = 1/rh ∂/∂ph e_z = ∂/∂z - """ if self._cylindrical_frame is None: # create the cylindrical chart and the associated orthonormal frame @@ -2537,7 +2501,6 @@ def scalar_triple_product(self, name=None, latex_name=None): 3-form Omega on the Euclidean space E^3 sage: latex(_) \Omega - """ eps = self.volume_form() if latex_name is None: diff --git a/src/sage/manifolds/differentiable/examples/real_line.py b/src/sage/manifolds/differentiable/examples/real_line.py index be587304cfc..746bae34c91 100644 --- a/src/sage/manifolds/differentiable/examples/real_line.py +++ b/src/sage/manifolds/differentiable/examples/real_line.py @@ -294,7 +294,6 @@ class OpenInterval(DifferentiableManifold): Chart ((1/2, 1), (t,)) sage: XK.coord_range() t: (1/2, 1) - """ @staticmethod def __classcall_private__(cls, lower, upper, ambient_interval=None, @@ -311,7 +310,6 @@ def __classcall_private__(cls, lower, upper, ambient_interval=None, sage: J = manifolds.OpenInterval(0,1, ambient_interval=I, coordinate='t') sage: I.open_interval(0,1) Real interval (0, 1) - """ if ambient_interval: # cope the UniqueRepresentation framework for subintervals and @@ -338,7 +336,6 @@ def __init__(self, lower, upper, ambient_interval=None, sage: J = manifolds.OpenInterval(-oo, 2); J Real interval (-Infinity, 2) sage: TestSuite(J).run(skip='_test_elements') # pickling of elements fails - """ if latex_name is None: if name is None: @@ -410,7 +407,6 @@ def _repr_(self): sage: I = manifolds.OpenInterval(-oo,0) sage: I Real interval (-Infinity, 0) - """ return "Real interval " + self._name @@ -435,7 +431,6 @@ def _first_ngens(self, n): sage: I = manifolds.OpenInterval(-1, 1, names=('x',)) sage: I._first_ngens(1) (x,) - """ return self._canon_chart[:] @@ -461,14 +456,12 @@ def _element_constructor_(self, coords=None, chart=None, name=None, - ``name`` -- (default: ``None``) name given to the point - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the point; if none is provided, the LaTeX symbol is set to ``name`` - - ``check_coords`` -- (default: ``True``) determines whether ``coords`` - are valid coordinates for the chart ``chart``; for symbolic - coordinates, it is recommended to set ``check_coords`` to ``False`` - - OUTPUT: + - ``check_coords`` -- boolean (default: ``True``); determines whether + ``coords`` are valid coordinates for the chart ``chart``. For symbolic + coordinates, it is recommended to set ``check_coords`` to ``False``. - - :class:`~sage.manifolds.point.TopologicalManifoldPoint` - representing a point in the current interval + OUTPUT: :class:`~sage.manifolds.point.TopologicalManifoldPoint` + representing a point in the current interval EXAMPLES:: @@ -490,7 +483,6 @@ def _element_constructor_(self, coords=None, chart=None, name=None, ... ValueError: the coordinates (8,) are not valid on the Chart ((-1, 4), (t,)) - """ if coords in SR: coords = (coords,) @@ -508,9 +500,7 @@ def _Hom_(self, other, category=None): - ``category`` -- (default: ``None``) not used here (to ensure compatibility with generic hook ``_Hom_``) - OUTPUT: - - - the set of curves `I \to M`, where `I` is ``self`` + OUTPUT: the set of curves `I \to M`, where `I` is ``self`` .. SEEALSO:: @@ -527,7 +517,6 @@ def _Hom_(self, other, category=None): Field with 53 bits of precision sage: H is Hom(I, M) True - """ from sage.manifolds.differentiable.manifold_homset import DifferentiableCurveSet return DifferentiableCurveSet(self, other) @@ -536,9 +525,7 @@ def canonical_chart(self): r""" Return the canonical chart defined on ``self``. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.chart.RealDiffChart` + OUTPUT: :class:`~sage.manifolds.differentiable.chart.RealDiffChart` EXAMPLES: @@ -556,7 +543,6 @@ def canonical_chart(self): sage: I. = manifolds.OpenInterval(0, pi) sage: I.canonical_chart() Chart ((0, pi), (x,)) - """ return self._canon_chart @@ -564,9 +550,7 @@ def canonical_coordinate(self): r""" Return the canonical coordinate defined on the interval. - OUTPUT: - - - the symbolic variable representing the canonical coordinate + OUTPUT: the symbolic variable representing the canonical coordinate EXAMPLES: @@ -595,7 +579,6 @@ def canonical_coordinate(self): sage: I. = manifolds.OpenInterval(0, pi) sage: I.canonical_coordinate() x - """ return self._canon_chart._xx[0] @@ -618,7 +601,6 @@ def lower_bound(self): 1/4 sage: J.inf() -Infinity - """ return self._lower @@ -643,7 +625,6 @@ def upper_bound(self): 3 sage: J.sup() +Infinity - """ return self._upper @@ -691,7 +672,6 @@ def open_interval(self, lower, upper, name=None, latex_name=None): sage: I.open_interval(-4, 4) is I True - """ if lower == self._lower and upper == self._upper: return self @@ -860,7 +840,6 @@ class RealLine(OpenInterval): Real number line ℝ sage: list(R.subset_family()) [Real interval (0, 1), Real number line ℝ] - """ @staticmethod def __classcall__(cls, name=unicode_mathbbR, latex_name=r'\Bold{R}', @@ -876,7 +855,6 @@ def __classcall__(cls, name=unicode_mathbbR, latex_name=r'\Bold{R}', Real number line ℝ sage: R is R1 True - """ return super().__classcall__(cls, name=name, latex_name=latex_name, @@ -896,7 +874,6 @@ def __init__(self, name=unicode_mathbbR, latex_name=r'\Bold{R}', Category of smooth connected manifolds over Real Field with 53 bits of precision sage: TestSuite(R).run(skip='_test_elements') # pickling of elements fails - """ OpenInterval.__init__(self, minus_infinity, infinity, name=name, latex_name=latex_name, coordinate=coordinate, @@ -914,6 +891,5 @@ def _repr_(self): sage: R = manifolds.RealLine(name='r') sage: R._repr_() 'Real number line r' - """ return "Real number line " + self._name diff --git a/src/sage/manifolds/differentiable/examples/sphere.py b/src/sage/manifolds/differentiable/examples/sphere.py index 387a31c10bc..ceb9ad849e1 100644 --- a/src/sage/manifolds/differentiable/examples/sphere.py +++ b/src/sage/manifolds/differentiable/examples/sphere.py @@ -284,7 +284,6 @@ class Sphere(PseudoRiemannianSubmanifold): coordinates and their transition maps is computational complex in higher dimensions. Henceforth, high computation times are expected with increasing dimension. - """ @staticmethod def __classcall_private__(cls, n=None, radius=1, ambient_space=None, @@ -308,7 +307,6 @@ def __classcall_private__(cls, n=None, radius=1, ambient_space=None, 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 sage: S._first_ngens(2) (x, y) - """ if n is None: if names is None: @@ -342,7 +340,6 @@ def __init__(self, n, radius=1, ambient_space=None, center=None, name=None, Riemannian metric g on the 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 sage: TestSuite(S2).run() - """ # radius if radius <= 0: @@ -411,7 +408,6 @@ def _init_embedding(self): iota: S^2 → E^3 on A: (theta, phi) ↦ (x, y, z) = (cos(phi)*sin(theta), sin(phi)*sin(theta), cos(theta)) - """ name = 'iota' latex_name = r'\iota' @@ -429,7 +425,6 @@ def _repr_(self): '2-sphere S^2_3 of radius 3 smoothly embedded in the Euclidean space E^3' sage: S2_3 # indirect doctest 2-sphere S^2_3 of radius 3 smoothly embedded in the Euclidean space E^3 - """ s = "{}-sphere {} of radius {} smoothly embedded in " \ "the {}".format(self._dim, self._name, self._radius, self._ambient) @@ -443,7 +438,7 @@ def coordinate_charts(self, coord_name, names=None): INPUT: - - ``coord_name`` -- string describing the type of coordinates + - ``coord_name`` -- string describing the type of coordinates - ``names`` -- (default: ``None``) must be a tuple containing the coordinate symbols for the first chart in the list; if ``None``, the standard convention is used @@ -461,7 +456,6 @@ def coordinate_charts(self, coord_name, names=None): sage: stereo_charts = S1.coordinate_charts('stereographic', names=['a']) sage: stereo_charts [Chart (S^1-{NP}, (a,)), Chart (S^1-{SP}, (ap,))] - """ if coord_name not in self._coordinates: if coord_name not in self._init_coordinates: @@ -487,7 +481,6 @@ def _first_ngens(self, n): sage: S2. = manifolds.Sphere(2) sage: S2._first_ngens(2) (u, v) - """ return self._def_chart[:] @@ -507,7 +500,6 @@ def _init_chart_domains(self): Open subset S^2-{NP,SP} of the Euclidean 2-sphere S^2 of radius 1, Open subset S^2-{NP} of the Euclidean 2-sphere S^2 of radius 1, Open subset S^2-{SP} of the Euclidean 2-sphere S^2 of radius 1}) - """ # without north pole: name = self._name + '-{NP}' @@ -551,7 +543,6 @@ def _shift_coords(self, coordfunc, s='+'): (cos(phi)*sin(theta) + 1, sin(phi)*sin(theta) + 2, cos(theta) + 3) sage: S2c._shift_coords(coordfunc, s='-') (cos(phi)*sin(theta), sin(phi)*sin(theta), cos(theta)) - """ cart = self._ambient.cartesian_coordinates() c_coords = cart(self._center) @@ -586,7 +577,6 @@ def _init_spherical(self, names=None): Chart (A, (phi,)), Chart (A, (y1,)), Chart (A, (yp1,))] - """ # speed-up via simplification method... self.set_simplify_function(lambda expr: expr.simplify_trig()) @@ -740,7 +730,6 @@ def stereographic_coordinates(self, pole='north', names=None): Chart (S^3-{NP}, (y1, y2, y3)) sage: S3.stereographic_coordinates(pole='south') Chart (S^3-{SP}, (yp1, yp2, yp3)) - """ coordinates = 'stereographic' if coordinates not in self._coordinates: @@ -856,7 +845,6 @@ def spherical_coordinates(self, names=None): sage: spher.coord_range() chi: (0, pi); theta: (0, pi); phi: [-pi, pi] (periodic) - """ coordinates = 'spherical' if coordinates not in self._coordinates: @@ -906,7 +894,6 @@ def _init_stereographic(self, names, default_pole='north'): sage: S1.metric().display() g = dphi⊗dphi - """ # speed-up via simplification method... self.set_simplify_function(lambda expr: expr.simplify_rational()) @@ -1006,7 +993,6 @@ def _transition_spher_stereo(self): Chart (S^1-{NP}, (y1,)) sage: S1.coord_change(spher, stereoN.restrict(A)) Change of coordinates from Chart (A, (phi,)) to Chart (A, (y1,)) - """ # speed-up via simplification method... self.set_simplify_function(lambda expr: expr.simplify()) @@ -1108,7 +1094,6 @@ def dist(self, p, q): sage: S2_r.dist(p, q) pi*r - """ from sage.functions.trig import acos # get Euclidean points: @@ -1146,7 +1131,6 @@ def radius(self): Euclidean space E^4 sage: S2_r.radius() r - """ return self._radius @@ -1166,7 +1150,6 @@ def minimal_triangulation(self): sage: S.euler_characteristic() 2 - """ from sage.topology.simplicial_complex_examples import Sphere as SymplicialSphere return SymplicialSphere(self._dim) @@ -1195,6 +1178,5 @@ def center(self): on A: (theta, phi) ↦ (x, y, z) = (cos(phi)*sin(theta) + 1, sin(phi)*sin(theta) + 2, cos(theta) + 3) - """ return self._center diff --git a/src/sage/manifolds/differentiable/examples/symplectic_space.py b/src/sage/manifolds/differentiable/examples/symplectic_space.py index be02c965fe7..6ce44f821d4 100644 --- a/src/sage/manifolds/differentiable/examples/symplectic_space.py +++ b/src/sage/manifolds/differentiable/examples/symplectic_space.py @@ -50,11 +50,12 @@ def __init__( - ``dimension`` -- dimension of the space over the real field (has to be even) - ``name`` -- name (symbol) given to the underlying vector space; - if ``None``, the name will be set to ``'Rn'``, where ``n`` is the ``dimension`` - - ``latex_name`` -- LaTeX symbol to denote the underlying vector space; if ``None``, it is set to ``name`` + if ``None``, the name will be set to ``'Rn'``, where ``n`` is the ``dimension`` + - ``latex_name`` -- LaTeX symbol to denote the underlying vector space; + if ``None``, it is set to ``name`` - ``coordinates`` -- (default: ``'Cartesian'``) the - type of coordinates to be initialized at the Euclidean space - creation; allowed values are + type of coordinates to be initialized at the Euclidean space + creation; allowed values are - ``'Cartesian'`` (canonical coordinates on `\RR^{2n}`) - ``'polar'`` for ``dimension=2`` only (see @@ -111,7 +112,6 @@ def __init__( Inner product matrix: [0.000000000000000 -1.00000000000000] [ 1.00000000000000 0.000000000000000] - """ # Check that manifold is even dimensional if dimension % 2 == 1: diff --git a/src/sage/manifolds/differentiable/examples/symplectic_space_test.py b/src/sage/manifolds/differentiable/examples/symplectic_space_test.py index 0372470bd73..9cfdf6da123 100644 --- a/src/sage/manifolds/differentiable/examples/symplectic_space_test.py +++ b/src/sage/manifolds/differentiable/examples/symplectic_space_test.py @@ -9,7 +9,7 @@ class TestR2VectorSpace: @pytest.fixture def M(self): - return StandardSymplecticSpace(2, "R2", symplectic_name="omega") + return StandardSymplecticSpace(2, 'R2', symplectic_name='omega') @pytest.fixture def omega(self, M: StandardSymplecticSpace): @@ -25,7 +25,7 @@ def test_display(self, omega: SymplecticForm): class TestR4VectorSpace: @pytest.fixture def M(self): - return StandardSymplecticSpace(4, "R4", symplectic_name="omega") + return StandardSymplecticSpace(4, 'R4', symplectic_name='omega') @pytest.fixture def omega(self, M: StandardSymplecticSpace): diff --git a/src/sage/manifolds/differentiable/integrated_curve.py b/src/sage/manifolds/differentiable/integrated_curve.py index 3976f7c4b9d..6867448cdce 100644 --- a/src/sage/manifolds/differentiable/integrated_curve.py +++ b/src/sage/manifolds/differentiable/integrated_curve.py @@ -361,7 +361,6 @@ class IntegratedCurve(DifferentiableCurve): color_tangent='orange') graph = c_plot_3d_1 + c_plot_3d_100 sphinx_plot(graph) - """ def __init__(self, parent, equations_rhs, velocities, @@ -423,7 +422,6 @@ def __init__(self, parent, equations_rhs, velocities, sage: t = var('t') sage: c = E.integrated_geodesic(E.metric(), (t, 0, 10), v); c Integrated geodesic in the Euclidean plane E^2 - """ from sage.symbolic.ring import SR @@ -633,7 +631,6 @@ def _repr_(self): sage: c = M.integrated_curve(eqns, D, (t,0,5), v, name='c'); c Integrated curve c in the 3-dimensional differentiable manifold M - """ description = "Integrated curve " @@ -681,7 +678,6 @@ def __reduce__(self): sage: loads(dumps(c)) Integrated curve c in the 3-dimensional differentiable manifold M - """ return (type(self), (self.parent(), self._equations_rhs, self._velocities, self._curve_parameter, @@ -696,12 +692,10 @@ def system(self, verbose=False): INPUT: - - ``verbose`` -- (default: ``False``) prints a detailed + - ``verbose`` -- boolean (default: ``False``); prints a detailed description of the curve - OUTPUT: - - - list containing + OUTPUT: list containing * the equations * the initial conditions @@ -744,7 +738,6 @@ def system(self, verbose=False): sage: sys_mute = c.system() sage: sys_mute == sys True - """ v0 = self._initial_tangent_vector @@ -812,7 +805,7 @@ def solve_analytical(self, verbose=False): zero, although the parameter range may not contain zero. Yet, assuming that it does, values of the coordinates functions at such zero initial parameter value are denoted by the name of - the coordinate function followed by the string ``"_0"``. + the coordinate function followed by the string ``'_0'``. OUTPUT: @@ -862,7 +855,6 @@ def solve_analytical(self, verbose=False): (B_0*q*x2_0 + Dx1_0*m*cos(B_0*q*t/m) + Dx2_0*m*sin(B_0*q*t/m) - Dx1_0*m)/(B_0*q), Dx3_0*t + x3_0) - """ from sage.calculus.var import function @@ -890,7 +882,7 @@ def solve_analytical(self, verbose=False): des[i] = diff(y[i],par) == des[i] for j in range(dim): coord = self._chart[:][j] # important to use '[:]' on - # 'chart' to avoid problems due to non zero starting + # 'chart' to avoid problems due to nonzero starting # index (i0) veloc = self._velocities[j] des[dim+i] = des[dim+i].substitute({coord: y[j]}) @@ -903,7 +895,7 @@ def solve_analytical(self, verbose=False): y_ics_second_half = [] for i in range(dim): coord = self._chart[:][i] # important to use '[:]' - # on 'chart' to avoid problems due to non zero + # on 'chart' to avoid problems due to nonzero # starting index (i0) veloc = self._velocities[i] str_var_coord = "{}_0".format(coord) @@ -983,14 +975,12 @@ def solve(self, step=None, method='odeint', solution_key=None, - ``parameters_values`` -- (default: ``None``) list of numerical values of the parameters present in the system defining the curve, to be substituted in the equations before integration - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the computation in progress - ``**control_param`` -- extra control parameters to be passed to the chosen solver; see the example with ``rtol`` and ``atol`` below - OUTPUT: - - - list of the numerical points of the computed solution + OUTPUT: list of the numerical points of the computed solution EXAMPLES: @@ -1059,7 +1049,6 @@ def solve(self, step=None, method='odeint', solution_key=None, ... ValueError: no available method of integration referred to as 'my method' - """ from sage.symbolic.ring import SR @@ -1318,7 +1307,7 @@ def jacobian(t,y): for j in range(dim): coord = chart[:][j] # important to use # '[:]' on 'chart' to avoid problems due - # to non zero starting index (i0) + # to nonzero starting index (i0) vel = self._velocities[j] AUX = eqns_num[i].derivative(coord) AUX2 = eqns_num[i].derivative(vel) @@ -1327,7 +1316,7 @@ def jacobian(t,y): for k in range(dim): coordin = chart[:][k] # important to # use '[:]' on 'chart' to avoid - # problems due to non zero starting + # problems due to nonzero starting # index (i0) veloc = self._velocities[k] AUX = AUX.substitute({coordin: y[k]}) @@ -1346,7 +1335,7 @@ def jacobian(t,y): for m in range(dim): coordin = chart[:][m] # important to use # '[:]' on 'chart' to avoid problems due - # to non zero starting index (i0) + # to nonzero starting index (i0) veloc = self._velocities[m] AUX3 = AUX3.substitute({coordin: y[m]}) AUX3 = AUX3.substitute({veloc: y[dim+m]}) @@ -1444,14 +1433,12 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None, - ``parameters_values`` -- (default: ``None``) list of numerical values of the parameters present in the system defining the curve, to be substituted in the equations before integration - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the computation in progress - ``**control_param`` -- extra control parameters to be passed to the solver - OUTPUT: - - - list of the numerical points of the computed solution + OUTPUT: list of the numerical points of the computed solution EXAMPLES: @@ -1470,7 +1457,7 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None, charts `P` en `C` (for "Polar" and "Cartesian") and their transition maps:: - sage: M = Manifold(2, 'M', structure="Riemannian") + sage: M = Manifold(2, 'M', structure='Riemannian') sage: C. = M.chart(coord_restrictions=lambda x,y: x**2+y**2 < 3**2) sage: P. = M.chart(coord_restrictions=lambda r, th: r > 2) sage: P_to_C = P.transition_map(C,(r*cos(th), r*sin(th))) @@ -1571,7 +1558,7 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None, .. PLOT:: - M = Manifold(2, 'M', structure="Riemannian") + M = Manifold(2, 'M', structure='Riemannian') C= M.chart(names = ("x", "y"), coord_restrictions=lambda x,y: x**2+y**2 < 3**2) x, y = C[:] P = M.chart(names = ("r", "th"), coord_restrictions=lambda r,th: r > 2) @@ -1597,7 +1584,6 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None, fig += c.plot_integrated(mapping=phi, color=["green","red"], thickness=3, plot_points=100, across_charts=True) sphinx_plot(fig) - """ import numpy as np @@ -1840,12 +1826,10 @@ def solution(self, solution_key=None, verbose=False): - ``solution_key`` -- (default: ``None``) key which the requested numerical solution is associated to; a default value is chosen if none is provided - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the solution returned - OUTPUT: - - - list of the numerical points of the solution requested + OUTPUT: list of the numerical points of the solution requested EXAMPLES: @@ -1914,12 +1898,10 @@ def interpolate(self, solution_key=None, method=None, - ``interpolation_key`` -- (default: ``None``) key which the resulting interpolation will be associated to ; a default value is given if none is provided - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the interpolation in progress - OUTPUT: - - - built interpolation object + OUTPUT: built interpolation object EXAMPLES: @@ -1971,7 +1953,6 @@ def interpolate(self, solution_key=None, method=None, ... ValueError: no available method of interpolation referred to as 'my method' - """ if solution_key is None: if 'odeint' in self._solutions: @@ -2045,12 +2026,10 @@ def interpolation(self, interpolation_key=None, verbose=False): - ``interpolation_key`` -- (default: ``None``) key which the requested interpolation is associated to; a default value is chosen if none is provided - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the interpolation object returned - OUTPUT: - - - requested interpolation object + OUTPUT: requested interpolation object EXAMPLES: @@ -2090,7 +2069,6 @@ def interpolation(self, interpolation_key=None, verbose=False): ... ValueError: no existing key 'my interp' referring to any interpolation - """ if interpolation_key is None: @@ -2122,7 +2100,7 @@ def __call__(self, t, interpolation_key=None, - ``interpolation_key`` -- (default: ``None``) key which the interpolation requested to compute the point is associated to; a default value is chosen if none is provided - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the interpolation used OUTPUT: @@ -2160,7 +2138,6 @@ def __call__(self, t, interpolation_key=None, associated with the key 'interp_T1' by default... sage: p.coordinates() # abs tol 1e-12 (1.060743337877276, -0.21538352256822146, 1.1) - """ if interpolation_key is None: @@ -2204,7 +2181,7 @@ def tangent_vector_eval_at(self, t, - ``interpolation_key`` -- (default: ``None``) key which the interpolation requested to compute the tangent vector is associated to; a default value is chosen if none is provided - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the interpolation used OUTPUT: @@ -2255,7 +2232,6 @@ def tangent_vector_eval_at(self, t, ... ValueError: no existing key 'my interp' referring to any interpolation - """ if interpolation_key is None: if 'cubic spline' in self._interpolations: @@ -2314,9 +2290,9 @@ def plot_integrated(self, chart=None, ambient_coords=None, - ``interpolation_key`` -- (default: ``None``) key associated to the interpolation object used for the plot; a default value is chosen if none is provided - - ``verbose`` -- (default: ``False``) prints information about + - ``verbose`` -- boolean (default: ``False``); prints information about the interpolation object used and the plotting in progress - - ``display_tangent`` -- (default: ``False``) determines whether + - ``display_tangent`` -- boolean (default: ``False``); determines whether some tangent vectors should also be plotted - ``color_tangent`` -- (default: ``blue``) color of the tangent vectors when these are plotted @@ -2379,7 +2355,6 @@ def plot_integrated(self, chart=None, ambient_coords=None, plot_points_tangent=10, scale=0.5, color='blue', color_tangent='red') sphinx_plot(c_plot_2d_1) - """ from sage.manifolds.chart import RealChart @@ -3173,7 +3148,7 @@ class IntegratedAutoparallelCurve(IntegratedCurve): The vectors tangent to such a curve make an angle different from 0 or `\pi/2` with the lines of latitude and longitude. Then, compute a curve such that both components of its initial - tangent vectors are non zero:: + tangent vectors are nonzero:: sage: sol = c.solve(solution_key='sol-angle', ....: parameters_values={tmin:0,tmax:2,th0:pi/4,ph0:0.1,v_th0:1,v_ph0:8}) @@ -3403,7 +3378,6 @@ class IntegratedAutoparallelCurve(IntegratedCurve): graph = graph3D_embedded_angle_curve + graph3D_embedded_loxo graph += graph3D_embedded_polar_coords sphinx_plot(graph) - """ def __init__(self, parent, affine_connection, curve_parameter, @@ -3428,7 +3402,6 @@ def __init__(self, parent, affine_connection, curve_parameter, Integrated autoparallel curve c in the 3-dimensional differentiable manifold M sage: TestSuite(c).run() - """ # setting the chart to gain access to the coordinate functions @@ -3510,7 +3483,6 @@ def _repr_(self): ....: name='c') ; c Integrated autoparallel curve c in the 3-dimensional differentiable manifold M - """ description = "Integrated autoparallel curve " @@ -3556,7 +3528,6 @@ def __reduce__(self): sage: loads(dumps(c)) Integrated autoparallel curve c in the 3-dimensional differentiable manifold M - """ return (type(self), (self.parent(), self._affine_connection, @@ -3572,7 +3543,7 @@ def system(self, verbose=False): INPUT: - - ``verbose`` -- (default: ``False``) prints a detailed + - ``verbose`` -- boolean (default: ``False``); prints a detailed description of the curve OUTPUT: @@ -3621,7 +3592,6 @@ def system(self, verbose=False): sage: sys_bis = c.system() sage: sys_bis == sys True - """ v0 = self._initial_tangent_vector @@ -3830,7 +3800,6 @@ class IntegratedGeodesic(IntegratedAutoparallelCurve): number_values=15, color='yellow') graph = graph3D_embedded_geods + graph3D_embedded_polar_coords sphinx_plot(graph) - """ def __init__(self, parent, metric, curve_parameter, @@ -3855,7 +3824,6 @@ def __init__(self, parent, metric, curve_parameter, Integrated geodesic c in the 2-dimensional Riemannian manifold S^2 sage: TestSuite(c).run() - """ affine_connection = metric.connection() @@ -3890,7 +3858,6 @@ def _repr_(self): sage: c = S2.integrated_geodesic(g, (t,0,pi), v, name='c'); c Integrated geodesic c in the 2-dimensional Riemannian manifold S^2 - """ description = "Integrated geodesic " @@ -3936,7 +3903,6 @@ def __reduce__(self): sage: loads(dumps(c)) Integrated geodesic c in the 2-dimensional Riemannian manifold S^2 - """ return (type(self), (self.parent(), self._metric, @@ -3951,12 +3917,10 @@ def system(self, verbose=False): INPUT: - - ``verbose`` -- (default: ``False``) prints a detailed + - ``verbose`` -- boolean (default: ``False``); prints a detailed description of the curve - OUTPUT: - - - list containing + OUTPUT: list containing * the equations * the initial equations @@ -3999,7 +3963,6 @@ def system(self, verbose=False): sage: sys_bis = c.system() sage: sys_bis == sys True - """ v0 = self._initial_tangent_vector diff --git a/src/sage/manifolds/differentiable/levi_civita_connection.py b/src/sage/manifolds/differentiable/levi_civita_connection.py index 6b40a99d440..a995cf804cd 100644 --- a/src/sage/manifolds/differentiable/levi_civita_connection.py +++ b/src/sage/manifolds/differentiable/levi_civita_connection.py @@ -115,7 +115,7 @@ class LeviCivitaConnection(AffineConnection): - ``name`` -- name given to the connection - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the connection - - ``init_coef`` -- (default: ``True``) determines whether the Christoffel + - ``init_coef`` -- boolean (default: ``True``); determines whether the Christoffel symbols are initialized (in the top charts on the domain, i.e. disregarding the subcharts) @@ -198,7 +198,6 @@ class LeviCivitaConnection(AffineConnection): Gam^th_ph,ph = -cos(th)*sin(th) Gam^ph_r,ph = 1/r Gam^ph_th,ph = cos(th)/sin(th) - """ def __init__(self, metric, name, latex_name=None, init_coef=True): r""" @@ -219,7 +218,6 @@ def __init__(self, metric, name, latex_name=None, init_coef=True): Levi-Civita connection nabla associated with the Riemannian metric g on the 2-dimensional differentiable manifold M sage: TestSuite(nab).run() - """ AffineConnection.__init__(self, metric.domain(), name, latex_name) self._metric = metric @@ -244,7 +242,6 @@ def _repr_(self): 'Levi-Civita connection nabla_g associated with the Riemannian metric g on the 5-dimensional differentiable manifold M' sage: repr(nab) # indirect doctest 'Levi-Civita connection nabla_g associated with the Riemannian metric g on the 5-dimensional differentiable manifold M' - """ description = "Levi-Civita connection" if self._name is not None: @@ -262,7 +259,6 @@ def _init_derived(self): sage: g = M.metric('g') sage: nab = g.connection() sage: nab._init_derived() - """ AffineConnection._init_derived(self) @@ -276,7 +272,6 @@ def _del_derived(self): sage: g = M.metric('g') sage: nab = g.connection() sage: nab._del_derived() - """ AffineConnection._del_derived(self) @@ -321,7 +316,6 @@ def restrict(self, subdomain): sage: nabU(g.restrict(U)).display() nabla_g(g) = 0 - """ if subdomain == self._domain: return self @@ -368,7 +362,6 @@ def _new_coef(self, frame): sage: e = M.vector_frame('e') sage: nab._new_coef(e) 3-indices components w.r.t. Vector frame (M, (e_0,e_1)) - """ from sage.tensor.modules.comp import Components, CompWithSym from sage.manifolds.differentiable.scalarfield import DiffScalarField @@ -436,7 +429,7 @@ def coef(self, frame=None): [[0, 1/r, 0], [1/r, 0, 0], [0, 0, -cos(th)*sin(th)]], [[0, 0, 1/r], [0, 0, cos(th)/sin(th)], [1/r, cos(th)/sin(th), 0]]] - The only non-zero Christoffel symbols:: + The only nonzero Christoffel symbols:: sage: gam[1,2,2], gam[1,3,3] (-r, -r*sin(th)^2) @@ -458,7 +451,7 @@ def coef(self, frame=None): [[0, 1/r, 0], [0, 0, 0], [0, 0, -cos(th)/(r*sin(th))]], [[0, 0, 1/r], [0, 0, cos(th)/(r*sin(th))], [0, 0, 0]]] - The only non-zero connection coefficients:: + The only nonzero connection coefficients:: sage: gam_e[1,2,2], gam_e[2,1,2] (-1/r, 1/r) @@ -581,7 +574,6 @@ def torsion(self): sage: t.display() 0 - """ if self._torsion is None: resu = self._domain.tensor_field(1, 2, antisym=(1,2)) @@ -822,7 +814,6 @@ def ricci(self, name=None, latex_name=None): differentiable manifold M sage: ric == 0 True - """ if self._ricci is None: if name is None: diff --git a/src/sage/manifolds/differentiable/manifold.py b/src/sage/manifolds/differentiable/manifold.py index b5bb4be4d6f..285a160e7ff 100644 --- a/src/sage/manifolds/differentiable/manifold.py +++ b/src/sage/manifolds/differentiable/manifold.py @@ -634,7 +634,6 @@ class DifferentiableManifold(TopologicalManifold): category:: sage: TestSuite(M).run() - """ def __init__(self, n, name, field, structure, base_manifold=None, diff_degree=infinity, latex_name=None, start_index=0, @@ -664,7 +663,6 @@ def __init__(self, n, name, field, structure, base_manifold=None, sage: U.category() is M.category().Subobjects() True sage: TestSuite(U).run() - """ if base_manifold is None: if category is None: @@ -731,7 +729,6 @@ def diff_degree(self): sage: M = Manifold(2, 'M', structure='differentiable', diff_degree=3) sage: M.diff_degree() 3 - """ return self._diff_degree @@ -747,7 +744,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none is provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -756,9 +753,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): - ``supersets`` -- (default: only ``self``) list of sets that the new open subset is a subset of - OUTPUT: - - - the open subset, as an instance of :class:`DifferentiableManifold` + OUTPUT: the open subset, as an instance of :class:`DifferentiableManifold` EXAMPLES: @@ -832,7 +827,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): False sage: M((-1/2,1/3)) in U True - """ resu = DifferentiableManifold(self._dim, name, self._field, self._structure, base_manifold=self._manifold, @@ -852,7 +846,7 @@ def _init_open_subset(self, resu, coord_def): INPUT: - ``resu`` -- an instance of :class:`TopologicalManifold` or - a subclass. + a subclass - ``coord_def`` -- (default: ``{}``) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -959,7 +953,6 @@ def diff_map(self, codomain, coord_functions=None, chart1=None, See the documentation of class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` for more examples. - """ homset = Hom(self, codomain) if coord_functions is None: @@ -1055,7 +1048,6 @@ def diffeomorphism(self, codomain=None, coord_functions=None, chart1=None, See the documentation of class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` for more examples. - """ if codomain is None: codomain = self @@ -1091,7 +1083,7 @@ class as the manifold. - ``name`` -- name given to the total space - ``field`` -- (default: ``'real'``) topological field giving the vector space structure to the fibers - - ``latex_name`` -- optional LaTeX name for the total space + - ``latex_name`` -- (optional) LaTeX name for the total space OUTPUT: @@ -1104,7 +1096,6 @@ class as the manifold. sage: M.vector_bundle(2, 'E') Differentiable real vector bundle E -> M of rank 2 over the base space 2-dimensional differentiable manifold M - """ from sage.manifolds.differentiable.vector_bundle \ import DifferentiableVectorBundle @@ -1135,7 +1126,6 @@ def tangent_bundle(self, dest_map=None): sage: M = Manifold(2, 'M') sage: TM = M.tangent_bundle(); TM Tangent bundle TM over the 2-dimensional differentiable manifold M - """ return self.tensor_bundle(1, 0, dest_map=dest_map) @@ -1164,7 +1154,6 @@ def cotangent_bundle(self, dest_map=None): sage: cTM = M.cotangent_bundle(); cTM Cotangent bundle T*M over the 2-dimensional differentiable manifold M - """ return self.tensor_bundle(0, 1, dest_map=dest_map) @@ -1215,7 +1204,6 @@ def tensor_bundle(self, k, l, dest_map=None): :class:`~sage.manifolds.differentiable.vector_bundle.TensorBundle` for more examples and documentation. - """ if dest_map is None: dest_map = self.identity_map() @@ -1251,7 +1239,7 @@ def vector_field_module( identity map (case of vector fields *on* `M`), otherwise ``dest_map`` must be a :class:`~sage.manifolds.differentiable.diff_map.DiffMap` - - ``force_free`` -- (default: ``False``) if set to ``True``, force + - ``force_free`` -- boolean (default: ``False``); if set to ``True``, force the construction of a *free* module (this implies that `N` is parallelizable) @@ -1377,7 +1365,6 @@ def vector_field_module( True sage: M.is_manifestly_parallelizable() True - """ from sage.manifolds.differentiable.vectorfield_module import \ VectorFieldModule, VectorFieldFreeModule @@ -1450,7 +1437,6 @@ def tensor_field_module(self, tensor_type, dest_map=None): 3-dimensional differentiable manifold M sage: TU.an_element().display() 2 ∂/∂x⊗∂/∂x⊗dx - """ return self.vector_field_module(dest_map=dest_map).tensor_module(*tensor_type) @@ -1509,7 +1495,6 @@ def diff_form_module(self, degree, dest_map=None): sage: M.diff_form_module(2) is M.diff_form_module(2) True - """ return self.vector_field_module(dest_map=dest_map).dual_exterior_power(degree) @@ -1558,7 +1543,6 @@ def mixed_form_algebra(self, dest_map=None): sage: M.mixed_form_algebra() is M.mixed_form_algebra() True - """ vmodule = self.vector_field_module(dest_map=dest_map) return MixedFormAlgebra(vmodule) @@ -1621,7 +1605,6 @@ def multivector_module(self, degree, dest_map=None): sage: M.multivector_module(2) is M.multivector_module(2) True - """ return self.vector_field_module(dest_map=dest_map).exterior_power(degree) @@ -1771,7 +1754,6 @@ def vector_field(self, *comp, **kwargs): For more examples, see :class:`~sage.manifolds.differentiable.vectorfield.VectorField` and :class:`~sage.manifolds.differentiable.vectorfield.VectorFieldParal`. - """ name = kwargs.pop('name', None) latex_name = kwargs.pop('latex_name', None) @@ -1791,7 +1773,7 @@ def tensor_field(self, *args, **kwargs): take its values on another manifold. More precisely, if `M` is the current manifold, `N` a differentiable manifold, `\Phi:\ M \rightarrow N` a differentiable map and `(k,l)` - a pair of non-negative integers, a *tensor field of type* `(k,l)` + a pair of nonnegative integers, a *tensor field of type* `(k,l)` *along* `M` *with values on* `N` is a differentiable map .. MATH:: @@ -1890,7 +1872,6 @@ def tensor_field(self, *args, **kwargs): For more examples, see :class:`~sage.manifolds.differentiable.tensorfield.TensorField` and :class:`~sage.manifolds.differentiable.tensorfield_paral.TensorFieldParal`. - """ k = args[0] l = args[1] @@ -2057,7 +2038,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` sage: s2[:] [-1 -1] [ 3 10] - """ name = kwargs.pop('name', None) latex_name = kwargs.pop('latex_name', None) @@ -2078,7 +2058,7 @@ def multivector_field(self, *args, **kwargs): multivector field take its values on another manifold. More precisely, if `M` is the current manifold, `N` a differentiable manifold, `\Phi:\ M \rightarrow N` a differentiable map and `p` - a non-negative integer, a *multivector field of degree* `p` (or + a nonnegative integer, a *multivector field of degree* `p` (or `p`-*vector field*) *along* `M` *with values on* `N` is a differentiable map @@ -2162,7 +2142,6 @@ def multivector_field(self, *args, **kwargs): :class:`~sage.manifolds.differentiable.multivectorfield.MultivectorField` and :class:`~sage.manifolds.differentiable.multivectorfield.MultivectorFieldParal`. - """ degree = args[0] name = kwargs.pop('name', None) @@ -2184,7 +2163,7 @@ def diff_form(self, *args, **kwargs) -> DiffForm: differential form take its values on another manifold. More precisely, if `M` is the current manifold, `N` a differentiable manifold, `\Phi:\ M \rightarrow N` a differentiable map and `p` - a non-negative integer, a *differential form of degree* `p` (or + a nonnegative integer, a *differential form of degree* `p` (or `p`-*form*) *along* `M` *with values on* `N` is a differentiable map @@ -2266,7 +2245,6 @@ def diff_form(self, *args, **kwargs) -> DiffForm: For more examples, see :class:`~sage.manifolds.differentiable.diff_form.DiffForm` and :class:`~sage.manifolds.differentiable.diff_form.DiffFormParal`. - """ degree = args[0] name = kwargs.pop('name', None) @@ -2364,7 +2342,6 @@ def one_form(self, *comp, **kwargs) -> DiffForm: For more examples, see :class:`~sage.manifolds.differentiable.diff_form.DiffForm` and :class:`~sage.manifolds.differentiable.diff_form.DiffFormParal`. - """ name = kwargs.pop('name', None) latex_name = kwargs.pop('latex_name', None) @@ -2444,7 +2421,6 @@ def mixed_form(self, comp=None, name=None, latex_name=None, dest_map=None): See the documentation of class :class:`~sage.manifolds.differentiable.mixed_form.MixedForm` for more examples. - """ algebra = self.mixed_form_algebra(dest_map=dest_map) resu = algebra.element_class(algebra, name=name, latex_name=latex_name) @@ -2472,7 +2448,6 @@ def symplectic_form( sage: omega.set_comp()[1,2] = -1 sage: omega.display() omega = -dq∧dp - """ return self.vector_field_module().symplectic_form(name, latex_name) @@ -2496,7 +2471,6 @@ def poisson_tensor( sage: poisson.set_comp()[1,2] = -1 sage: poisson.display() varpi = -e_q∧e_p - """ return self.vector_field_module().poisson_tensor(name, latex_name) @@ -2591,7 +2565,6 @@ def automorphism_field(self, *comp, **kwargs): :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField` and :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismFieldParal`. - """ name = kwargs.pop('name', None) latex_name = kwargs.pop('latex_name', None) @@ -2668,7 +2641,6 @@ def tangent_identity_field(self, dest_map=None): For more examples, see :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField`. - """ vmodule = self.vector_field_module(dest_map) return vmodule.identity_map() @@ -2722,7 +2694,6 @@ def set_orientation(self, orientation): sage: M.orientation() [Coordinate frame (U, (∂/∂x,∂/∂y)), Coordinate frame (V, (∂/∂u,∂/∂v))] - """ from .vectorframe import VectorFrame chart_type = self._structure.chart @@ -2818,7 +2789,6 @@ def orientation(self): sage: W = U.intersection(V, name='W') sage: W.orientation() [Vector frame (W, (∂/∂x,∂/∂y))] - """ if not self._orientation: # try to get an orientation from super domains: @@ -2873,7 +2843,6 @@ def default_frame(self): sage: c_xy. = M.chart() sage: M.default_frame() Coordinate frame (M, (∂/∂x,∂/∂y)) - """ return self._def_frame @@ -2899,7 +2868,6 @@ def set_default_frame(self, frame): sage: M.set_default_frame(e) sage: M.default_frame() Vector frame (M, (e_0,e_1)) - """ from sage.manifolds.differentiable.vectorframe import VectorFrame if not isinstance(frame, VectorFrame): @@ -2969,7 +2937,6 @@ def change_of_frame(self, frame1, frame2): sage: M.change_of_frame(c_xy.frame(), c_uv.frame()) is \ ....: XM.change_of_basis(c_xy.frame(), c_uv.frame()) True - """ if (frame1, frame2) not in self._frame_changes: raise ValueError("the change of frame from {} to {}".format(frame1, frame2) + @@ -2991,7 +2958,7 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame, :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismFieldParal` describing the automorphism `P` that relates the basis `(e_i)` to the basis `(f_i)` according to `f_i = P(e_i)` - - ``compute_inverse`` (default: ``True``) -- if set to True, the inverse + - ``compute_inverse`` -- boolean (default: ``True``); if set to True, the inverse automorphism is computed and the change from basis `(f_i)` to `(e_i)` is set to it in the internal dictionary ``self._frame_changes`` @@ -3017,7 +2984,6 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame, sage: M.change_of_frame(e,f)[e,:] [1 2] [0 3] - """ from sage.manifolds.differentiable.automorphismfield import AutomorphismFieldParal fmodule = frame1._fmodule @@ -3172,7 +3138,6 @@ def vector_frame(self, *args, **kwargs) -> VectorFrame: For more options, in particular for the choice of symbols and indices, see :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame`. - """ from sage.manifolds.differentiable.vectorframe import VectorFrame # Input processing @@ -3241,7 +3206,6 @@ def _set_covering_frame(self, frame): sage: M._set_covering_frame(e) sage: M._covering_frames [Vector frame (M, (e_0,e_1))] - """ self._covering_frames.append(frame) self._parallelizable_parts = set([self]) @@ -3254,9 +3218,7 @@ def frames(self): r""" Return the list of vector frames defined on open subsets of ``self``. - OUTPUT: - - - list of vector frames defined on open subsets of ``self`` + OUTPUT: list of vector frames defined on open subsets of ``self`` EXAMPLES: @@ -3277,7 +3239,6 @@ def frames(self): [Coordinate frame (R^2, (∂/∂x,∂/∂y)), Vector frame (R^2, (e_0,e_1)), Coordinate frame (U, (∂/∂x,∂/∂y))] - """ return list(self._frames) @@ -3285,9 +3246,7 @@ def coframes(self): r""" Return the list of coframes defined on open subsets of ``self``. - OUTPUT: - - - list of coframes defined on open subsets of ``self`` + OUTPUT: list of coframes defined on open subsets of ``self`` EXAMPLES: @@ -3312,7 +3271,6 @@ def coframes(self): Coframe (R^2, (e^0,e^1)), Coordinate coframe (U, (dx,dy)), Coframe (U, (e^0,e^1))] - """ return list(self._coframes) @@ -3364,7 +3322,6 @@ def changes_of_frame(self): True sage: M.changes_of_frame()[(f,e)] == a^(-1) True - """ return self._frame_changes.copy() @@ -3397,7 +3354,6 @@ def is_manifestly_parallelizable(self): sage: X. = N.chart() sage: N.is_manifestly_parallelizable() True - """ return bool(self._covering_frames) @@ -3437,7 +3393,6 @@ def tangent_space(self, point, base_ring=None): :class:`~sage.manifolds.differentiable.tangent_space.TangentSpace` for more examples. - """ from sage.manifolds.point import ManifoldPoint from sage.manifolds.differentiable.tangent_space import TangentSpace @@ -3470,7 +3425,7 @@ def curve(self, coord_expression, param, chart=None, in both cases, if the dimension of the manifold is 1, a single coordinate expression can be passed instead of a tuple with a single element - - ``param`` -- a tuple of the type ``(t, t_min, t_max)``, where + - ``param`` -- tuple of the type ``(t, t_min, t_max)``, where * ``t`` is the curve parameter used in ``coord_expression``; * ``t_min`` is its minimal value; @@ -3486,9 +3441,7 @@ def curve(self, coord_expression, param, chart=None, - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the curve; if none is provided, ``name`` will be used - OUTPUT: - - - :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` EXAMPLES: @@ -3520,7 +3473,6 @@ def curve(self, coord_expression, param, chart=None, :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` for more examples, including plots. - """ from sage.manifolds.differentiable.examples.real_line import RealLine if not isinstance(param, (tuple, list)): @@ -3566,7 +3518,7 @@ def integrated_curve(self, equations_rhs, velocities, curve_param, equations on the velocities only - ``velocities`` -- list of the symbolic expressions used in ``equations_rhs`` to denote the velocities - - ``curve_param`` -- a tuple of the type ``(t, t_min, t_max)``, + - ``curve_param`` -- tuple of the type ``(t, t_min, t_max)``, where * ``t`` is the symbolic variable used in ``equations_rhs`` to @@ -3584,9 +3536,7 @@ def integrated_curve(self, equations_rhs, velocities, curve_param, - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the curve; if none is provided, ``name`` will be used - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedCurve` EXAMPLES: @@ -3640,7 +3590,6 @@ def integrated_curve(self, equations_rhs, velocities, curve_param, by default... sage: tgt_vec[:] # abs tol 1e-12 [-0.8481007454066425, 0.5298350137284363, 1.0] - """ from sage.manifolds.differentiable.examples.real_line import RealLine @@ -3679,7 +3628,7 @@ def integrated_autoparallel_curve(self, affine_connection, - ``affine_connection`` -- :class:`~sage.manifolds.differentiable.affine_connection.AffineConnection`; affine connection with respect to which the curve is autoparallel - - ``curve_param`` -- a tuple of the type ``(t, t_min, t_max)``, + - ``curve_param`` -- tuple of the type ``(t, t_min, t_max)``, where * ``t`` is the symbolic variable to be used as the parameter @@ -3700,9 +3649,7 @@ def integrated_autoparallel_curve(self, affine_connection, - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the curve; if none is provided, ``name`` will be used - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedAutoparallelCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedAutoparallelCurve` EXAMPLES: @@ -3775,7 +3722,6 @@ def integrated_autoparallel_curve(self, affine_connection, by default... sage: tgt_vec[:] # abs tol 1e-12 [1.000000000000011, 1.148779968412235] - """ from sage.manifolds.differentiable.examples.real_line import RealLine @@ -3816,7 +3762,7 @@ def integrated_geodesic(self, metric, curve_param, - ``metric`` -- :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric` metric with respect to which the curve is a geodesic - - ``curve_param`` -- a tuple of the type ``(t, t_min, t_max)``, + - ``curve_param`` -- tuple of the type ``(t, t_min, t_max)``, where * ``t`` is the symbolic variable to be used as the parameter @@ -3837,9 +3783,7 @@ def integrated_geodesic(self, metric, curve_param, - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the curve; if none is provided, ``name`` will be used - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedGeodesic` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedGeodesic` EXAMPLES: @@ -3897,7 +3841,6 @@ def integrated_geodesic(self, metric, curve_param, by default... sage: tgt_vec[:] # abs tol 1e-12 [-1.0907409234671228, 0.6205670379855032] - """ from sage.manifolds.differentiable.examples.real_line import RealLine from sage.manifolds.differentiable.manifold_homset import IntegratedGeodesicSet @@ -3949,7 +3892,6 @@ def affine_connection(self, name, latex_name=None): :class:`~sage.manifolds.differentiable.affine_connection.AffineConnection` for more examples. - """ from sage.manifolds.differentiable.affine_connection import \ AffineConnection @@ -4002,7 +3944,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric` for more examples. - """ vmodule = self.vector_field_module(dest_map) return vmodule.metric(name, signature=signature, latex_name=latex_name) @@ -4062,7 +4003,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` :class:`~sage.manifolds.differentiable.metric.DegenerateMetric` for more examples. - """ vmodule = self.vector_field_module(dest_map) dim = vmodule.ambient_domain().dimension() @@ -4115,7 +4055,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric` for more examples. - """ vmodule = self.vector_field_module(dest_map) dim = vmodule.ambient_domain().dimension() @@ -4137,7 +4076,7 @@ def lorentzian_metric(self, name, signature='positive', latex_name=None, INPUT: - ``name`` -- name given to the metric - - ``signature`` -- (default: 'positive') sign of the metric + - ``signature`` -- (default: ``'positive'``) sign of the metric signature: * if set to 'positive', the signature is n-2, where n is the @@ -4181,7 +4120,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` g = dt⊗dt - dx⊗dx - dy⊗dy - dz⊗dz sage: g.signature() -2 - """ vmodule = self.vector_field_module(dest_map) dim = vmodule.ambient_domain().dimension() @@ -4217,7 +4155,6 @@ def tangent_vector(self, *args, **kwargs): - :class:`~sage.manifolds.differentiable.tangent_vector.TangentVector` representing the tangent vector at point `p` - EXAMPLES: Vector at a point `p` of the Euclidean plane:: @@ -4282,7 +4219,6 @@ def tangent_vector(self, *args, **kwargs): Traceback (most recent call last): ... ValueError: 2 components must be provided - """ basis = kwargs.pop('basis', None) name = kwargs.pop('name', None) diff --git a/src/sage/manifolds/differentiable/manifold_homset.py b/src/sage/manifolds/differentiable/manifold_homset.py index 90759e74afa..52a75ac61ad 100644 --- a/src/sage/manifolds/differentiable/manifold_homset.py +++ b/src/sage/manifolds/differentiable/manifold_homset.py @@ -153,7 +153,6 @@ class DifferentiableManifoldHomset(TopologicalManifoldHomset): This test suite includes more tests than in the case of ``H``, since ``E`` has some extra structure (monoid). - """ Element = DiffMap @@ -179,7 +178,6 @@ def __init__(self, domain, codomain, name=None, latex_name=None): 2-dimensional differentiable manifold M in Category of smooth manifolds over Real Field with 53 bits of precision sage: TestSuite(E).run() - """ from sage.manifolds.differentiable.manifold import \ DifferentiableManifold @@ -211,7 +209,6 @@ def _coerce_map_from_(self, other): False sage: H._coerce_map_from_(N) False - """ #!# for the time being: return False @@ -368,7 +365,6 @@ class DifferentiableCurveSet(DifferentiableManifoldHomset): The test suite is passed by ``EI``:: sage: TestSuite(EI).run() - """ Element = DifferentiableCurve @@ -405,7 +401,6 @@ def __init__(self, domain, codomain, name=None, latex_name=None): manifolds over Real Field with 53 bits of precision and Category of connected manifolds over Real Field with 53 bits of precision sage: TestSuite(H).run() - """ from sage.manifolds.differentiable.examples.real_line import OpenInterval if not isinstance(domain, OpenInterval): @@ -423,9 +418,7 @@ def _element_constructor_(self, coord_expression, name=None, `I \to M`, where `I` is a real interval and `M` some differentiable manifold. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` EXAMPLES:: @@ -438,7 +431,6 @@ def _element_constructor_(self, coord_expression, name=None, Curve c in the 2-dimensional differentiable manifold M sage: c = Hom(R, R)({}, is_identity=True) ; c Identity map Id_ℝ of the Real number line ℝ - """ # Standard construction return self.element_class(self, coord_expression=coord_expression, @@ -450,9 +442,7 @@ def _an_element_(self): r""" Construct some element of ``self``. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.curve.DifferentiableCurve` EXAMPLES:: @@ -481,7 +471,6 @@ def _an_element_(self): sage: c.display() (0, pi) → (0, pi) t ↦ 1/4*pi + 1/2*pi/(t^2 + 1) - """ from sage.rings.infinity import Infinity from sage.rings.rational_field import QQ @@ -693,7 +682,6 @@ class IntegratedCurveSet(DifferentiableCurveSet): skipped for reasons mentioned above:: sage: TestSuite(H).run(skip=["_test_one", "_test_prod"]) - """ Element = IntegratedCurve @@ -724,7 +712,6 @@ def __init__(self, domain, codomain, name=None, latex_name=None): (-1, 2) in Category of endsets of subobjects of sets and topological spaces which actually are integrated curves sage: TestSuite(H).run(skip=["_test_one", "_test_prod"]) - """ from sage.rings.infinity import Infinity @@ -768,7 +755,6 @@ def _repr_(self): Set of Morphisms from Real interval (-1, 2) to 3-dimensional differentiable manifold M in Category of homsets of topological spaces which actually are integrated curves - """ description = "Set of Morphisms " description += "from {} to {} in {} ".format(self._domain, @@ -784,9 +770,7 @@ def _element_constructor_(self, equations_rhs, velocities, `I \to M`, where `I` is a real interval and `M` some differentiable manifold. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedCurve` EXAMPLES:: @@ -805,7 +789,6 @@ def _element_constructor_(self, equations_rhs, velocities, sage: c = H(eqns_rhs, vels, t, v, name='c') ; c Integrated curve c in the 2-dimensional differentiable manifold M - """ # Standard construction return self.element_class(self, equations_rhs, velocities, @@ -816,9 +799,7 @@ def _an_element_(self): r""" Construct some element of ``self``. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedCurve` EXAMPLES:: @@ -876,7 +857,6 @@ def _an_element_(self): Point on the Real number line ℝ sage: p.coordinates() # abs tol 1e-12 (0.8409865343211089,) - """ from sage.categories.homset import Hom @@ -971,7 +951,6 @@ def one(self): ... ValueError: the identity is not implemented for integrated curves and associated subclasses - """ if self.codomain() != self.domain(): @@ -1130,7 +1109,6 @@ class IntegratedAutoparallelCurveSet(IntegratedCurveSet): skipped for reasons mentioned above:: sage: TestSuite(H).run(skip=["_test_one", "_test_prod"]) - """ Element = IntegratedAutoparallelCurve @@ -1164,7 +1142,6 @@ def __init__(self, domain, codomain, name=None, latex_name=None): topological spaces which actually are integrated autoparallel curves with respect to a certain affine connection sage: TestSuite(H).run(skip=["_test_one", "_test_prod"]) - """ from sage.rings.infinity import Infinity @@ -1209,7 +1186,6 @@ def _repr_(self): differentiable manifold M in Category of homsets of topological spaces which actually are integrated autoparallel curves with respect to a certain affine connection - """ description = "Set of Morphisms " @@ -1227,9 +1203,7 @@ def _element_constructor_(self, affine_connection, curve_parameter, autoparallel curve `I \to M`, where `I` is a real interval and `M` some differentiable manifold. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedAutoparallelCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedAutoparallelCurve` EXAMPLES:: @@ -1250,7 +1224,6 @@ def _element_constructor_(self, affine_connection, curve_parameter, sage: c = H(nab, t, v, name='c') ; c Integrated autoparallel curve c in the 2-dimensional differentiable manifold M - """ # Standard construction return self.element_class(self, affine_connection, @@ -1261,9 +1234,7 @@ def _an_element_(self): r""" Construct some element of ``self``. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedAutoparallelCurve` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedAutoparallelCurve` EXAMPLES:: @@ -1329,7 +1300,6 @@ def _an_element_(self): Point on the Real number line ℝ sage: p.coordinates() # abs tol 1e-12 (1.0565635217644918,) - """ from sage.rings.infinity import Infinity @@ -1586,7 +1556,6 @@ class IntegratedGeodesicSet(IntegratedAutoparallelCurveSet): skipped for reasons mentioned above:: sage: TestSuite(H).run(skip=["_test_one", "_test_prod"]) - """ Element = IntegratedGeodesic @@ -1620,7 +1589,6 @@ def __init__(self, domain, codomain, name=None, latex_name=None): topological spaces which actually are integrated geodesics with respect to a certain metric sage: TestSuite(H).run(skip=["_test_one", "_test_prod"]) - """ from sage.rings.infinity import Infinity @@ -1664,7 +1632,6 @@ def _repr_(self): differentiable manifold M in Category of homsets of topological spaces which actually are integrated geodesics with respect to a certain metric - """ description = "Set of Morphisms " description += "from {} to {} in {} ".format(self._domain, @@ -1681,9 +1648,7 @@ def _element_constructor_(self, metric, curve_parameter, `I \to M`, where `I` is a real interval and `M` some differentiable manifold. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedGeodesic` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedGeodesic` EXAMPLES:: @@ -1702,7 +1667,6 @@ def _element_constructor_(self, metric, curve_parameter, sage: c = H(g, t, v, name='c') ; c Integrated geodesic c in the 2-dimensional differentiable manifold M - """ # Standard construction return self.element_class(self, metric, curve_parameter, @@ -1713,9 +1677,7 @@ def _an_element_(self): r""" Construct some element of ``self``. - OUTPUT: - - - :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedGeodesic` + OUTPUT: :class:`~sage.manifolds.differentiable.integrated_curve.IntegratedGeodesic` EXAMPLES:: @@ -1785,7 +1747,6 @@ def _an_element_(self): Point on the Real number line ℝ sage: p.coordinates() # abs tol 1e-12 (1.0565635217644918,) - """ from sage.categories.homset import Hom diff --git a/src/sage/manifolds/differentiable/metric.py b/src/sage/manifolds/differentiable/metric.py index 4b4c6cf1a37..e25033a8cb7 100644 --- a/src/sage/manifolds/differentiable/metric.py +++ b/src/sage/manifolds/differentiable/metric.py @@ -333,7 +333,6 @@ class PseudoRiemannianMetric(TensorField): sage: delta = M.tangent_identity_field() sage: riem == - r*(g*delta).antisymmetrize(2,3) True - """ _derived_objects = ('_connection', '_ricci_scalar', '_weyl', '_schouten', '_cotton', '_cotton_york') @@ -370,7 +369,6 @@ def __init__(self, vector_field_module, name, signature=None, - fix _test_pickling (in the superclass TensorField) - add a specific parent to the metrics, to fit with the category framework - """ TensorField.__init__(self, vector_field_module, (0,2), name=name, latex_name=latex_name, sym=(0,1)) @@ -411,7 +409,6 @@ def _repr_(self): sage: g = M.metric('g', signature=1) sage: g._repr_() 'Pseudo-Riemannian metric g on the 5-dimensional differentiable manifold M' - """ n = self._ambient_domain.dimension() s = self._signature @@ -442,7 +439,6 @@ def _new_instance(self): True sage: g1.signature() == g.signature() True - """ return type(self)(self._vmodule, 'unnamed metric', signature=self._signature, @@ -457,7 +453,6 @@ def _init_derived(self): sage: M = Manifold(5, 'M') sage: g = M.metric('g') sage: g._init_derived() - """ # Initialization of quantities pertaining to the mother class: TensorField._init_derived(self) @@ -482,7 +477,6 @@ def _del_derived(self): sage: M = Manifold(5, 'M') sage: g = M.metric('g') sage: g._del_derived() - """ # First the derived quantities from the mother class are deleted: TensorField._del_derived(self) @@ -507,7 +501,6 @@ def _del_inverse(self): sage: M = Manifold(5, 'M') sage: g = M.metric('g') sage: g._del_inverse() - """ self._inverse._restrictions.clear() self._inverse._del_derived() @@ -534,7 +527,6 @@ def signature(self): sage: h = M.metric('h', signature=0) sage: h.signature() 0 - """ return self._signature @@ -552,7 +544,7 @@ def restrict(self, subdomain, dest_map=None): `\Phi:\ U \rightarrow V`, where `V` is a subdomain of ``self._codomain`` (type: :class:`~sage.manifolds.differentiable.diff_map.DiffMap`) - If None, the restriction of ``self._vmodule._dest_map`` to `U` is + If ``None``, the restriction of ``self._vmodule._dest_map`` to `U` is used. OUTPUT: @@ -573,7 +565,6 @@ def restrict(self, subdomain, dest_map=None): See the top documentation of :class:`PseudoRiemannianMetric` for more examples. - """ if subdomain == self._domain: return self @@ -603,7 +594,7 @@ def restrict(self, subdomain, dest_map=None): def set(self, symbiform): r""" - Defines the metric from a field of symmetric bilinear forms + Define the metric from a field of symmetric bilinear forms. INPUT: @@ -640,7 +631,6 @@ def set(self, symbiform): sage: g.display(eV) g = (1/8*u^2 - 1/8*v^2 + 1/4*v + 1/2) du⊗du + 1/4*u du⊗dv + 1/4*u dv⊗du + (-1/8*u^2 + 1/8*v^2 + 1/4*v + 1/2) dv⊗dv - """ if not isinstance(symbiform, TensorField): raise TypeError("the argument must be a tensor field") @@ -719,7 +709,6 @@ def inverse(self, expansion_symbol=None, order=1): Tensor field of type (1,1) on the 2-dimensional differentiable manifold S^2 sage: s == M.tangent_identity_field() True - """ # Is the inverse metric up to date? for dom, rst in self._restrictions.items(): @@ -744,7 +733,7 @@ def connection(self, name=None, latex_name=None, init_coef=True): Levi-Civita connection; if ``None``, it is set to ``name``, or if the latter is None as well, it formed from the symbol `\nabla` and the metric symbol - - ``init_coef`` -- (default: ``True``) determines whether the + - ``init_coef`` -- boolean (default: ``True``); determines whether the connection coefficients are initialized, as Christoffel symbols in the top charts of the domain of ``self`` (i.e. disregarding the subcharts) @@ -794,7 +783,6 @@ def connection(self, name=None, latex_name=None, init_coef=True): the 3-dimensional differentiable manifold R^3 sage: Dig == 0 True - """ from sage.manifolds.differentiable.levi_civita_connection import \ LeviCivitaConnection @@ -868,8 +856,6 @@ def christoffel_symbols(self, chart=None): Gam^th_ph,ph = -cos(th)*sin(th) Gam^ph_r,ph = 1/r Gam^ph_th,ph = cos(th)/sin(th) - - """ if chart is None: frame = self._domain._def_chart._frame @@ -905,11 +891,11 @@ def christoffel_symbols_display(self, chart=None, symbol=None, representing the LaTeX labels of each index; if ``None``, coordinate LaTeX symbols are used, except if ``coordinate_symbols`` is set to ``False``, in which case integer labels are used - - ``coordinate_labels`` -- (default: ``True``) boolean; if ``True``, + - ``coordinate_labels`` -- boolean (default: ``True``); if ``True``, coordinate symbols are used by default (instead of integers) - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero connection coefficients are displayed - - ``only_nonredundant`` -- (default: ``True``) boolean; if ``True``, + - ``only_nonredundant`` -- boolean (default: ``True``); if ``True``, only nonredundant (w.r.t. the symmetry of the last two indices) connection coefficients are displayed @@ -979,7 +965,6 @@ def christoffel_symbols_display(self, chart=None, symbol=None, Gam^2_33 = -cos(th)*sin(th) Gam^3_13 = 1/r Gam^3_23 = cos(th)/sin(th) - """ if chart is None: chart = self._domain.default_chart() @@ -1062,7 +1047,6 @@ def riemann(self, name=None, latex_name=None): [[0, sin(2*th)/(2*tan(th)) - cos(2*th)], [-sin(2*th)/(2*tan(th)) + cos(2*th), 0]]], [[[0, -1], [1, 0]], [[0, 0], [0, 0]]]] - """ return self.connection().riemann(name, latex_name) @@ -1116,7 +1100,6 @@ def ricci(self, name=None, latex_name=None): [ 0 sin(th)^2] sage: g.ricci() == a^(-2) * g True - """ return self.connection().ricci(name, latex_name) @@ -1283,7 +1266,6 @@ def schouten(self, name=None, latex_name=None): sage: g.schouten().display() Schouten(g) = -3/8 dx⊗dx + (5/8*x^2 - 3/8) dy⊗dy - 5/8*x dy⊗dz - 5/8*x dz⊗dy + 5/8 dz⊗dz - """ n = self._ambient_domain.dimension() if n < 3: @@ -1341,7 +1323,6 @@ def cotton(self, name=None, latex_name=None): 3-dimensional differentiable manifold H^3 sage: Cot == 0 # long time True - """ n = self._ambient_domain.dimension() if n < 3: @@ -1401,7 +1382,6 @@ def cotton_york(self, name=None, latex_name=None): CY(g) = 1/2 dx⊗dx + (-x^2 + 1/2) dy⊗dy + x dy⊗dz + x dz⊗dy - dz⊗dz sage: det(CY[:]) # long time -1/4 - """ n = self._ambient_domain.dimension() if n != 3: @@ -1493,7 +1473,6 @@ def determinant(self, frame=None): sage: s = g.determinant() # determinant in M's default frame sage: s.expr() -x**2*y**2 + x - y*(x + 1) + 1 - """ from sage.matrix.constructor import matrix dom = self._domain @@ -1601,7 +1580,6 @@ def sqrt_abs_det(self, frame=None): sqrt(-x**2*y**2 - x*y + x - y + 1)/2 sage: g.sqrt_abs_det(Y.frame()).expr(Y) sqrt(-u**4 + 2*u**2*v**2 - 4*u**2 - v**4 + 4*v**2 + 16*v + 16)/8 - """ dom = self._domain if frame is None: @@ -1771,7 +1749,6 @@ def volume_form(self, contra=0): Note the minus sign in the above expression, reflecting the fact that ``eV`` is left-handed with respect to the chosen orientation. - """ dom = self._domain orient = dom.orientation() @@ -1830,7 +1807,7 @@ def hodge_star(self, pform: DiffForm) -> DiffForm: INPUT: - - ``pform``: a `p`-form `A`; must be an instance of + - ``pform`` -- a `p`-form `A`; must be an instance of :class:`~sage.manifolds.differentiable.scalarfield.DiffScalarField` for `p=0` and of :class:`~sage.manifolds.differentiable.diff_form.DiffForm` or @@ -1971,7 +1948,6 @@ def hodge_star(self, pform: DiffForm) -> DiffForm: sage: epsilon = g.volume_form() sage: g.hodge_star(a.wedge(b)) == epsilon.contract(0,a.up(g)).contract(0,b.up(g)) True - """ return pform.hodge_dual(self) @@ -2097,7 +2073,6 @@ class PseudoRiemannianMetricParal(PseudoRiemannianMetric, TensorFieldParal): inv_g = (x - 1)/(x^2*y^2 + x^2 - 1) ∂/∂x⊗∂/∂x + x*y/(x^2*y^2 + x^2 - 1) ∂/∂x⊗∂/∂y + x*y/(x^2*y^2 + x^2 - 1) ∂/∂y⊗∂/∂x - (x + 1)/(x^2*y^2 + x^2 - 1) ∂/∂y⊗∂/∂y - """ def __init__(self, vector_field_module, name, signature=None, latex_name=None): @@ -2120,7 +2095,6 @@ def __init__(self, vector_field_module, name, signature=None, - add a specific parent to the metrics, to fit with the category framework - """ TensorFieldParal.__init__(self, vector_field_module, (0,2), name=name, latex_name=latex_name, sym=(0,1)) @@ -2155,7 +2129,6 @@ def _init_derived(self): sage: X. = M.chart() # makes M parallelizable sage: g = M.metric('g') sage: g._init_derived() - """ # Initialization of quantities pertaining to the mother classes: TensorFieldParal._init_derived(self) @@ -2167,8 +2140,8 @@ def _del_derived(self, del_restrictions=True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the - restrictions of ``self`` to subdomains are deleted. + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the + restrictions of ``self`` to subdomains are deleted TESTS:: @@ -2177,7 +2150,6 @@ def _del_derived(self, del_restrictions=True): sage: g = M.metric('g') sage: g._del_derived(del_restrictions=False) sage: g._del_derived() - """ # The derived quantities from the mother classes are deleted: TensorFieldParal._del_derived(self, del_restrictions=del_restrictions) @@ -2193,7 +2165,6 @@ def _del_inverse(self): sage: X. = M.chart() # makes M parallelizable sage: g = M.metric('g') sage: g._del_inverse() - """ self._inverse._components.clear() self._inverse._del_derived() @@ -2213,7 +2184,7 @@ def restrict(self, subdomain, dest_map=None): `\Phi:\ U \rightarrow V`, where `V` is a subdomain of ``self._codomain`` (type: :class:`~sage.manifolds.differentiable.diff_map.DiffMap`) - If None, the restriction of ``self._vmodule._dest_map`` to `U` is + If ``None``, the restriction of ``self._vmodule._dest_map`` to `U` is used. OUTPUT: @@ -2237,7 +2208,6 @@ def restrict(self, subdomain, dest_map=None): 0 sage: gU.display() g = -dx⊗dx + dy⊗dy - """ if subdomain == self._domain: return self @@ -2287,7 +2257,6 @@ def set(self, symbiform): sage: g.set(s) sage: g.display() g = (x^2 + 1) dx⊗dx + x*y dx⊗dy + x*y dy⊗dx + (y^2 + 1) dy⊗dy - """ if not isinstance(symbiform, TensorFieldParal): raise TypeError("the argument must be a tensor field with " + @@ -2407,7 +2376,6 @@ def inverse(self, expansion_symbol=None, order=1): [ e 1 -e 0] [ 0 -e 1 -e] [ 0 0 -e 1] - """ if expansion_symbol is not None: if (self._inverse is not None and bool(self._inverse._components) @@ -2616,7 +2584,6 @@ class DegenerateMetric(TensorField): sage: g(v, v).disp() M → ℝ (x, y, z) ↦ 0 - """ def __init__(self, vector_field_module, name, signature=None, @@ -2641,8 +2608,6 @@ def __init__(self, vector_field_module, name, signature=None, sage: g.disp(e) g = (2*m/r - 1) dt⊗dt + 2*m/r dt⊗dr + 2*m/r dr⊗dt + (2*m/r + 1) dr⊗dr + r^2 dth⊗dth + r^2*sin(th)^2 dph⊗dph - - """ TensorField.__init__(self, vector_field_module, (0,2), name=name, latex_name=latex_name, sym=(0,1)) @@ -2676,7 +2641,6 @@ def _repr_(self): sage: g = M.metric('g', signature=(1,1,1)) sage: g._repr_() 'degenerate metric g on the 3-dimensional differentiable manifold M' - """ return self._final_repr("degenerate metric "+self._name + " ") @@ -2697,7 +2661,6 @@ def _new_instance(self): True sage: g1.signature() == g.signature() True - """ return type(self)(self._vmodule, 'unnamed metric', signature=self._signature, @@ -2725,13 +2688,12 @@ def signature(self): sage: g = M.metric() sage: g.signature() (0, 2, 1) - """ return self._signature def set(self, symbiform): r""" - Defines the metric from a field of symmetric bilinear forms + Define the metric from a field of symmetric bilinear forms. INPUT: @@ -2768,7 +2730,6 @@ def set(self, symbiform): sage: g.display(eV) g = (1/8*u^2 - 1/8*v^2 + 1/4*v + 1/2) du⊗du + 1/4*u du⊗dv + 1/4*u dv⊗du + (-1/8*u^2 + 1/8*v^2 + 1/4*v + 1/2) dv⊗dv - """ if not isinstance(symbiform, TensorField): raise TypeError("the argument must be a tensor field") @@ -2802,7 +2763,7 @@ def restrict(self, subdomain, dest_map=None): `\Phi:\ U \rightarrow V`, where `V` is a subdomain of ``self._codomain`` (type: :class:`~sage.manifolds.differentiable.diff_map.DiffMap`) - If None, the restriction of ``self._vmodule._dest_map`` to `U` is + If ``None``, the restriction of ``self._vmodule._dest_map`` to `U` is used. OUTPUT: @@ -2823,7 +2784,6 @@ def restrict(self, subdomain, dest_map=None): See the top documentation of :class:`DegenerateMetric` for more examples. - """ if subdomain == self._domain: return self @@ -2840,7 +2800,7 @@ def restrict(self, subdomain, dest_map=None): def determinant(self): r""" - Determinant of a degenerate metric is always '0' + Determinant of a degenerate metric is always '0'. EXAMPLES:: @@ -2848,7 +2808,6 @@ def determinant(self): sage: g = S.metric('g', signature=([0,1,1])) sage: g.determinant() Scalar field zero on the 2-dimensional differentiable manifold S - """ return self._domain.zero_scalar_field() @@ -2932,7 +2891,6 @@ class DegenerateMetricParal(DegenerateMetric, TensorFieldParal): sage: g(v, v).disp() M → ℝ (x, y, z) ↦ 0 - """ def __init__(self, vector_field_module, name, signature=None, @@ -2958,8 +2916,6 @@ def __init__(self, vector_field_module, name, signature=None, + (x^2 + z^2)/(x^2 + y^2 + z^2) dy⊗dy - y*z/(x^2 + y^2 + z^2) dy⊗dz - x*z/(x^2 + y^2 + z^2) dz⊗dx - y*z/(x^2 + y^2 + z^2) dz⊗dy + (x^2 + y^2)/(x^2 + y^2 + z^2) dz⊗dz - - """ TensorFieldParal.__init__(self, vector_field_module, (0,2), name=name, latex_name=latex_name, sym=(0,1)) @@ -2983,7 +2939,7 @@ def __init__(self, vector_field_module, name, signature=None, def set(self, symbiform): r""" - Defines the metric from a field of symmetric bilinear forms + Define the metric from a field of symmetric bilinear forms. INPUT: @@ -3005,7 +2961,6 @@ def set(self, symbiform): sage: g.set(b) sage: g.display() g = dx⊗dx + dy⊗dy - """ if not isinstance(symbiform, TensorFieldParal): raise TypeError("the argument must be a tensor field with " + @@ -3038,7 +2993,7 @@ def restrict(self, subdomain, dest_map=None): `\Phi:\ U \rightarrow V`, where `V` is a subdomain of ``self._codomain`` (type: :class:`~sage.manifolds.differentiable.diff_map.DiffMap`) - If None, the restriction of ``self._vmodule._dest_map`` to `U` is + If ``None``, the restriction of ``self._vmodule._dest_map`` to `U` is used. OUTPUT: @@ -3058,7 +3013,6 @@ def restrict(self, subdomain, dest_map=None): See the top documentation of :class:`DegenerateMetric` for more examples. - """ if subdomain == self._domain: return self diff --git a/src/sage/manifolds/differentiable/mixed_form.py b/src/sage/manifolds/differentiable/mixed_form.py index 4ca5cf56c49..65e2a25891e 100644 --- a/src/sage/manifolds/differentiable/mixed_form.py +++ b/src/sage/manifolds/differentiable/mixed_form.py @@ -211,7 +211,6 @@ class MixedForm(AlgebraElement, ModuleElementWithMutability): Traceback (most recent call last): ... ValueError: the components of an immutable element cannot be changed - """ def __init__(self, parent, name=None, latex_name=None): r""" @@ -238,7 +237,6 @@ def __init__(self, parent, name=None, latex_name=None): sage: A = M.mixed_form_algebra() sage: F = A([x, omega, eta], name='F') sage: TestSuite(F).run(skip='_test_pickling') - """ if parent is None: raise ValueError("a parent must be provided") @@ -277,7 +275,6 @@ def _init_comp(self): [Scalar field A_0 on the 2-dimensional differentiable manifold M, 1-form A_1 on the 2-dimensional differentiable manifold M, 2-form A_2 on the 2-dimensional differentiable manifold M] - """ self._comp = [] for i in self.irange(): @@ -315,7 +312,6 @@ def _repr_(self): Mixed differential form one along the 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 with values on the Euclidean space E^3 via the map iota - """ desc = "Mixed differential form " if self._name is not None: @@ -343,7 +339,6 @@ def _latex_(self): '\\omega' sage: latex(omega) # indirect doctest \omega - """ if self._name is None: return r'\text{' + repr(self) + r'}' @@ -365,7 +360,6 @@ def _new_instance(self, name=None, latex_name=None): True sage: F1.parent() is F.parent() True - """ return type(self)(self.parent(), name=name, latex_name=latex_name) @@ -417,7 +411,6 @@ def display_expansion(self, frame=None, chart=None, from_chart=None): F = (1/4*u + 1/4*v) du + (1/4*u + 1/4*v) dv + u*v du∧dv sage: F.display_expansion(e_xy) F = x dx + (2*x^2 - 2*y^2) dx∧dy - """ from sage.misc.latex import latex from sage.typeset.unicode_characters import unicode_wedge @@ -529,7 +522,6 @@ def display(self): manifold M sage: F.display() # display names of homogeneous components F = f + omega + eta - """ from sage.misc.latex import latex from sage.tensor.modules.format_utilities import FormattedExpansion @@ -574,8 +566,8 @@ def set_name(self, name=None, latex_name=None, apply_to_comp=True): - ``name`` -- (default: ``None``) name given to the mixed form - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the mixed form; if none is provided, the LaTeX symbol is set to ``name`` - - ``apply_to_comp`` -- (default: ``True``) if ``True`` all homogeneous - components will be renamed accordingly; if ``False`` only the mixed + - ``apply_to_comp`` -- boolean (default: ``True``); if ``True`` all homogeneous + components will be renamed accordingly. If ``False`` only the mixed form will be renamed EXAMPLES: @@ -665,7 +657,6 @@ def __bool__(self): True sage: F.is_zero() # indirect doctest False - """ if self._is_zero: return False @@ -683,7 +674,7 @@ def _richcmp_(self, other, op): - ``other`` -- a mixed form - ``op`` -- comparison operator for which ``self`` and ``other`` shall - be compared with. + be compared with TESTS:: @@ -712,14 +703,13 @@ def _richcmp_(self, other, op): sage: F == G # False since G has not been defined on V False sage: G.set_restriction(F.restrict(V)) - sage: F == G # True now + sage: F == G # ``True`` now True sage: H = M.mixed_form([f, 0, 0]) sage: F != H # this is fixed by issue #30108 True sage: F.parent().zero() == 0 True - """ from sage.structure.richcmp import op_NE, op_EQ if op == op_NE: @@ -787,7 +777,6 @@ def _add_(self, other): True sage: Z._add_(A) == A True - """ # Case zero: if self._is_zero: @@ -861,7 +850,6 @@ def _sub_(self, other): True sage: Z._sub_(A) == -A True - """ # Case zero: if self._is_zero: @@ -977,7 +965,6 @@ def wedge(self, other): x∧A = x^2 + x^2 dx + x*z dx∧dz sage: F = A*eta; F.display_expansion() A∧eta = x*y dy + x*y dx∧dy - y*z dx∧dy∧dz - """ # Case zero: if self._is_zero or other._is_zero: @@ -1029,7 +1016,6 @@ def _lmul_(self, other): differentiable manifold M sage: A.display_expansion() y∧(x∧F) = x^2*y^2 dx - """ try: if other.is_trivial_zero(): @@ -1108,7 +1094,6 @@ def exterior_derivative(self): sage: F.exterior_derivative() is dF True - """ resu = self._new_instance() resu[0] = self._domain.zero_scalar_field() @@ -1178,7 +1163,6 @@ def copy(self, name=None, latex_name=None): True sage: A is B False - """ resu = self._new_instance() resu._comp = [form.copy() for form in self] @@ -1189,7 +1173,7 @@ def copy(self, name=None, latex_name=None): def __setitem__(self, index, values): r""" - Sets a component with respect to some vector frame. + Set a component with respect to some vector frame. - ``index`` -- list of indices; if ``[:]`` is provided, all the components are set @@ -1210,7 +1194,6 @@ def __setitem__(self, index, values): A = f + a + b sage: A.display_expansion() A = x + y dx + x*y dx∧dy - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1261,7 +1244,6 @@ def __getitem__(self, deg): [Scalar field f on the 2-dimensional differentiable manifold M, 1-form a on the 2-dimensional differentiable manifold M, 2-form b on the 2-dimensional differentiable manifold M] - """ if self._comp is None: self._init_comp() @@ -1317,7 +1299,6 @@ def set_restriction(self, rst): A = u/(u^2 + v^2) - (u^2*v - v^3)/(u^6 + 3*u^4*v^2 + 3*u^2*v^4 + v^6) du - 2*u*v^2/(u^6 + 3*u^4*v^2 + 3*u^2*v^4 + v^6) dv sage: A.restrict(U) == AU True - """ if not isinstance(rst, MixedForm): raise TypeError("the argument must be a mixed form") @@ -1345,9 +1326,7 @@ def restrict(self, subdomain, dest_map=None): used, `\Phi` being the differentiable map `S \rightarrow M` associated with the mixed form - OUTPUT: - - - :class:`MixedForm` representing the restriction + OUTPUT: :class:`MixedForm` representing the restriction EXAMPLES: @@ -1392,7 +1371,6 @@ def restrict(self, subdomain, dest_map=None): differentiable manifold M] sage: FV.display_expansion(e_uv) F = u^2/(u^4 + 2*u^2*v^2 + v^4) - (u^2*v^2 - v^4)/(u^8 + 4*u^6*v^2 + 6*u^4*v^4 + 4*u^2*v^6 + v^8) du - 2*u*v^3/(u^8 + 4*u^6*v^2 + 6*u^4*v^4 + 4*u^2*v^6 + v^8) dv - u^2*v^2/(u^12 + 6*u^10*v^2 + 15*u^8*v^4 + 20*u^6*v^6 + 15*u^4*v^8 + 6*u^2*v^10 + v^12) du∧dv - """ resu = type(self)(subdomain.mixed_form_algebra(dest_map=dest_map), name=self._name, latex_name=self._latex_name) @@ -1448,7 +1426,6 @@ def add_comp_by_continuation(self, frame, subdomain, chart=None): F = x + x dx - x*y/(x^8 + 4*x^6*y^2 + 6*x^4*y^4 + 4*x^2*y^6 + y^8) dx∧dy sage: F.display_expansion(e_uv) F = u/(u^2 + v^2) - (u^3 - u*v^2)/(u^6 + 3*u^4*v^2 + 3*u^2*v^4 + v^6) du - 2*u^2*v/(u^6 + 3*u^4*v^2 + 3*u^2*v^4 + v^6) dv + u*v du∧dv - """ if chart is None: chart = frame._chart @@ -1479,7 +1456,6 @@ def irange(self, start=None): [0, 1, 2, 3] sage: list(a.irange(2)) [2, 3] - """ return self.parent().irange(start=start) @@ -1499,7 +1475,6 @@ def set_comp(self, i): A = A_0 + A_1 + A_2 sage: A.display_expansion() A = x^2 - y dx + x dy + (x - y) dx∧dy - """ return self[i] @@ -1520,7 +1495,6 @@ def set_immutable(self): True sage: f.is_immutable() False - """ for form in self: form.set_immutable() diff --git a/src/sage/manifolds/differentiable/mixed_form_algebra.py b/src/sage/manifolds/differentiable/mixed_form_algebra.py index 8266b19e172..c3ab8bbbbe9 100644 --- a/src/sage/manifolds/differentiable/mixed_form_algebra.py +++ b/src/sage/manifolds/differentiable/mixed_form_algebra.py @@ -140,7 +140,6 @@ class MixedFormAlgebra(Parent, UniqueRepresentation): subset U of the 3-dimensional differentiable manifold M sage: OmegaU.has_coerce_map_from(Omega) True - """ Element = MixedForm @@ -165,7 +164,6 @@ def __init__(self, vector_field_module): ....: import MixedFormAlgebra sage: A = MixedFormAlgebra(M.vector_field_module()) sage: TestSuite(A).run() - """ if vector_field_module is None: raise ValueError("underlying vector field module must be provided") @@ -212,7 +210,6 @@ def _element_constructor_(self, comp, name=None, latex_name=None): sage: a = A([x,0,0], name='a'); a Mixed differential form a on the 2-dimensional differentiable manifold M - """ try: if comp.is_trivial_zero(): @@ -269,7 +266,6 @@ def _an_element_(self): sage: A._an_element_() Mixed differential form on the 2-dimensional differentiable manifold M - """ res = self.element_class(self) dom = self._domain @@ -301,7 +297,6 @@ def _coerce_map_from_(self, S): True sage: A._coerce_map_from_(AU) False - """ if isinstance(S, type(self)): # coercion by domain restriction @@ -336,7 +331,6 @@ def zero(self): sage: A.zero() Mixed differential form zero on the 3-dimensional differentiable manifold M - """ res = self.element_class(self, name='zero', latex_name='0') res._comp = [self._domain.diff_form_module(j, dest_map=self._dest_map).zero() @@ -357,7 +351,6 @@ def one(self): sage: A.one() Mixed differential form one on the 3-dimensional differentiable manifold M - """ res = self.element_class(self, name='one', latex_name='1') res._comp = [self._domain.one_scalar_field(), @@ -385,7 +378,6 @@ def vector_field_module(self): Module X(M,Phi) of vector fields along the 2-dimensional differentiable manifold M mapped into the 3-dimensional differentiable manifold N - """ return self._vmodule @@ -399,7 +391,6 @@ def _repr_(self): sage: A = M.mixed_form_algebra(); A Graded algebra Omega^*(M) of mixed differential forms on the 3-dimensional differentiable manifold M - """ desc = "Graded algebra " + self._name desc += " of mixed differential forms " @@ -427,7 +418,6 @@ def _latex_(self): '\\Omega^*\\left(\\mathcal{M}\\right)' sage: latex(A) # indirect doctest \Omega^*\left(\mathcal{M}\right) - """ return self._latex_name @@ -461,7 +451,6 @@ def differential(self, degree=None): (x, y) ↦ x sage: d0(f).display() df = dx - """ if degree is None: domain = codomain = self @@ -503,7 +492,6 @@ def cohomology(self, *args, **kwargs): sage: A.cohomology() De Rham cohomology ring on the 3-dimensional differentiable manifold M - """ from .de_rham_cohomology import DeRhamCohomologyRing return DeRhamCohomologyRing(self) @@ -533,7 +521,6 @@ def irange(self, start=None): [0, 1, 2, 3] sage: list(A.irange(2)) [2, 3] - """ imax = self._max_deg + 1 if start is None: @@ -564,6 +551,5 @@ def lift_from_homology(self, x): sage: C.lift_from_homology(a) Mixed differential form alpha on the 2-dimensional differentiable manifold M - """ return x.lift() diff --git a/src/sage/manifolds/differentiable/multivector_module.py b/src/sage/manifolds/differentiable/multivector_module.py index 51264368ccd..2dc036a878c 100644 --- a/src/sage/manifolds/differentiable/multivector_module.py +++ b/src/sage/manifolds/differentiable/multivector_module.py @@ -141,7 +141,7 @@ class :class:`MultivectorFreeModule` must be used instead. sage: z is A.zero() True - while non-zero elements are constructed by providing their + while nonzero elements are constructed by providing their components in a given vector frame:: sage: a = A([[0,3*x],[-3*x,0]], frame=eU, name='a') ; a @@ -214,7 +214,6 @@ class :class:`MultivectorFreeModule` must be used instead. differentiable manifold M sage: a_U.display(eU) a = 3*x ∂/∂x∧∂/∂y - """ Element = MultivectorField @@ -245,7 +244,6 @@ def __init__(self, vector_field_module, degree): In the above test suite, ``_test_elements`` is skipped because of the ``_test_pickling`` error of the elements (to be fixed in :class:`sage.manifolds.differentiable.tensorfield.TensorField`) - """ domain = vector_field_module._domain dest_map = vector_field_module._dest_map @@ -298,7 +296,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, a = x*y ∂/∂x∧∂/∂y sage: A(0) is A.zero() True - """ try: if comp.is_trivial_zero(): @@ -340,7 +337,6 @@ def _an_element_(self): sage: A._an_element_() 2-vector field on the 2-dimensional differentiable manifold M - """ resu = self.element_class(self._vmodule, self._degree) for oc in self._domain.open_covers(trivial=False): @@ -369,7 +365,6 @@ def _coerce_map_from_(self, other): True sage: A2._coerce_map_from_(A2U) False - """ if isinstance(other, (MultivectorModule, MultivectorFreeModule)): # coercion by domain restriction @@ -391,7 +386,6 @@ def zero(self): sage: A2.zero() 2-vector field zero on the 3-dimensional differentiable manifold M - """ zero = self._element_constructor_(name='zero', latex_name='0') for frame in self._domain._frames: @@ -415,7 +409,6 @@ def _repr_(self): sage: A2 Module A^2(M) of 2-vector fields on the 3-dimensional differentiable manifold M - """ description = "Module " if self._name is not None: @@ -440,7 +433,6 @@ def _latex_(self): 'A^{2}\\left(\\mathcal{M}\\right)' sage: latex(A2) # indirect doctest A^{2}\left(\mathcal{M}\right) - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -476,7 +468,6 @@ def base_module(self): sage: A2U.base_module() Module X(U) of vector fields on the Open subset U of the 3-dimensional differentiable manifold M - """ return self._vmodule @@ -484,9 +475,7 @@ def degree(self): r""" Return the degree of the multivector fields in ``self``. - OUTPUT: - - - integer `p` such that ``self`` is a set of `p`-vector fields + OUTPUT: integer `p` such that ``self`` is a set of `p`-vector fields EXAMPLES:: @@ -495,7 +484,6 @@ def degree(self): 2 sage: M.multivector_module(3).degree() 3 - """ return self._degree @@ -589,7 +577,7 @@ class MultivectorFreeModule(ExtPowerFreeModule): sage: A(0) is A.zero() True - while non-zero elements are constructed by providing their + while nonzero elements are constructed by providing their components in a given vector frame:: sage: comp = [[0,3*x,-z],[-3*x,0,4],[z,-4,0]] @@ -662,7 +650,6 @@ class MultivectorFreeModule(ExtPowerFreeModule): differentiable manifold M sage: a_U.display() a = 3*x ∂/∂x∧∂/∂y - z ∂/∂x∧∂/∂z + 4 ∂/∂y∧∂/∂z - """ Element = MultivectorFieldParal @@ -682,7 +669,6 @@ def __init__(self, vector_field_module, degree): Free module A^2(M) of 2-vector fields on the 3-dimensional differentiable manifold M sage: TestSuite(A).run() - """ domain = vector_field_module._domain dest_map = vector_field_module._dest_map @@ -725,7 +711,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, a = x ∂/∂x∧∂/∂y sage: A(0) is A.zero() True - """ try: if comp.is_trivial_zero(): @@ -775,7 +760,6 @@ def _coerce_map_from_(self, other): False sage: A2._coerce_map_from_(M.tensor_field_module((2,0))) False - """ if isinstance(other, (MultivectorModule, MultivectorFreeModule)): # coercion by domain restriction @@ -799,7 +783,6 @@ def _repr_(self): sage: A Free module A^2(M) of 2-vector fields on the 3-dimensional differentiable manifold M - """ description = "Free module " if self._name is not None: diff --git a/src/sage/manifolds/differentiable/multivectorfield.py b/src/sage/manifolds/differentiable/multivectorfield.py index 1d15c4cae41..08b6d4d75a8 100644 --- a/src/sage/manifolds/differentiable/multivectorfield.py +++ b/src/sage/manifolds/differentiable/multivectorfield.py @@ -152,7 +152,6 @@ class MultivectorField(TensorField): sage: s.display(eV) f*(a∧b) = (1/2*u^5 - 1/2*u^3*v^2 - 1/2*u^2*v^3 + u^3 + 1/2*(u^4 + 2*u^2)*v) ∂/∂u∧∂/∂v - """ def __init__(self, vector_field_module, degree, name=None, latex_name=None): r""" @@ -193,7 +192,6 @@ def __init__(self, vector_field_module, degree, name=None, latex_name=None): .. TODO:: Fix ``_test_pickling`` (in the superclass :class:`TensorField`). - """ TensorField.__init__(self, vector_field_module, (degree, 0), name=name, latex_name=latex_name, antisym=range(degree), @@ -217,7 +215,6 @@ def _repr_(self): sage: b = M.multivector_field(2) sage: b._repr_() '2-vector field on the 3-dimensional differentiable manifold M' - """ description = "{}-vector field ".format(self._tensor_rank) if self._name is not None: @@ -239,7 +236,6 @@ def _new_instance(self): True sage: a1.parent() is a.parent() True - """ return type(self)(self._vmodule, self._tensor_rank) @@ -247,9 +243,7 @@ def degree(self): r""" Return the degree of ``self``. - OUTPUT: - - - integer `p` such that ``self`` is a `p`-vector field + OUTPUT: integer `p` such that ``self`` is a `p`-vector field EXAMPLES:: @@ -262,7 +256,6 @@ def degree(self): Vector field on the 3-dimensional differentiable manifold M sage: b.degree() 1 - """ return self._tensor_rank @@ -305,7 +298,6 @@ def wedge(self, other): a∧b = (-x^3 - (x - 1)*y^2) ∂/∂x∧∂/∂y sage: c.display(e_uv) a∧b = (-v^2 + u) ∂/∂u∧∂/∂v - """ from sage.typeset.unicode_characters import unicode_wedge from sage.tensor.modules.format_utilities import is_atomic @@ -458,7 +450,6 @@ def interior_product(self, form): True sage: s.restrict(V) == 2 * a[[e_uv,1,2]] * b[[e_uv,1,2]] True - """ from sage.tensor.modules.format_utilities import is_atomic if self._domain.is_subset(form._domain): @@ -631,7 +622,6 @@ def bracket(self, other): :meth:`MultivectorFieldParal.bracket` for more examples and check of standards identities involving the Schouten-Nijenhuis bracket - """ from sage.manifolds.differentiable.scalarfield import DiffScalarField pp = self._tensor_rank @@ -754,7 +744,7 @@ class MultivectorFieldParal(AlternatingContrTensor, TensorFieldParal): sage: type(a.comp()) - Setting a component with repeated indices to a non-zero value results in + Setting a component with repeated indices to a nonzero value results in an error:: sage: a[1,1] = 3 @@ -863,7 +853,6 @@ class MultivectorFieldParal(AlternatingContrTensor, TensorFieldParal): sage: ab.lie_der(a) 2-vector field on the 3-dimensional differentiable manifold R3 - """ def __init__(self, vector_field_module, degree, name=None, latex_name=None): @@ -892,7 +881,6 @@ def __init__(self, vector_field_module, degree, name=None, True sage: a1.parent() is a.parent() True - """ AlternatingContrTensor.__init__(self, vector_field_module, degree, name=name, latex_name=latex_name) @@ -921,7 +909,6 @@ def _repr_(self): sage: b = M.multivector_field(2) sage: b._repr_() '2-vector field on the 3-dimensional differentiable manifold M' - """ description = "{}-vector field ".format(self._tensor_rank) if self._name is not None: @@ -944,7 +931,6 @@ def _new_instance(self): True sage: a1.parent() is a.parent() True - """ return type(self)(self._fmodule, self._tensor_rank) @@ -959,7 +945,6 @@ def _init_derived(self): sage: X. = M.chart() # makes M parallelizable sage: a = M.multivector_field(2, name='a') sage: a._init_derived() - """ TensorFieldParal._init_derived(self) @@ -969,7 +954,7 @@ def _del_derived(self, del_restrictions=True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the restrictions of ``self`` to subdomains are deleted TESTS:: @@ -978,7 +963,6 @@ def _del_derived(self, del_restrictions=True): sage: X. = M.chart() # makes M parallelizable sage: a = M.multivector_field(2, name='a') sage: a._del_derived() - """ TensorFieldParal._del_derived(self, del_restrictions=del_restrictions) @@ -1007,7 +991,6 @@ def __call__(self, *args): True sage: s == a(b,c) # indirect doctest True - """ return TensorFieldParal.__call__(self, *args) @@ -1059,7 +1042,6 @@ def wedge(self, other): True sage: s == f.wedge(b) True - """ if other._tensor_rank == 0: # wedge product with a scalar field return self * other @@ -1177,7 +1159,6 @@ def interior_product(self, form): sage: f = X.coframe()[1] # 1-form dx sage: v.interior_product(f) Scalar field zero on the 4-dimensional differentiable manifold M - """ if self._domain.is_subset(form._domain): if not self._ambient_domain.is_subset(form._ambient_domain): @@ -1417,7 +1398,6 @@ def bracket(self, other): sage: d_ac = d.bracket(a.bracket(c)) sage: a_cd + c_da - d_ac == 0 True - """ from itertools import combinations from sage.combinat.permutation import Permutation diff --git a/src/sage/manifolds/differentiable/poisson_tensor.py b/src/sage/manifolds/differentiable/poisson_tensor.py index 41f178dff5c..51da2de5f90 100644 --- a/src/sage/manifolds/differentiable/poisson_tensor.py +++ b/src/sage/manifolds/differentiable/poisson_tensor.py @@ -86,7 +86,6 @@ class PoissonTensorField(MultivectorField): sage: varpi.bracket(varpi).display() [varpi,varpi] = 0 - """ def __init__( @@ -106,7 +105,6 @@ def __init__( sage: varpi 2-vector field varpi on the 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 - """ try: vector_field_module = manifold.vector_field_module() @@ -245,7 +243,6 @@ class PoissonTensorFieldParal(PoissonTensorField, MultivectorFieldParal): 2-vector field varpi on the Euclidean plane E^2 sage: varpi.display() varpi = -e_q∧e_p - """ def __init__( @@ -264,7 +261,6 @@ def __init__( sage: poisson = PoissonTensorFieldParal(M, name='varpi', latex_name=r'\varpi') sage: poisson 2-vector field varpi on the Euclidean plane E^2 - """ PoissonTensorField.__init__(self, manifold, name, latex_name) MultivectorFieldParal.__init__(self, self._vmodule, 2, name, latex_name) diff --git a/src/sage/manifolds/differentiable/pseudo_riemannian.py b/src/sage/manifolds/differentiable/pseudo_riemannian.py index 8d3578cfe1f..3ad49659de8 100644 --- a/src/sage/manifolds/differentiable/pseudo_riemannian.py +++ b/src/sage/manifolds/differentiable/pseudo_riemannian.py @@ -409,7 +409,6 @@ class PseudoRiemannianManifold(DifferentiableManifold): Lorentzian metric g on the 4-dimensional Lorentzian manifold M sage: M.metric().signature() -2 - """ def __init__(self, n, name, metric_name=None, signature=None, base_manifold=None, diff_degree=infinity, latex_name=None, @@ -430,7 +429,6 @@ def __init__(self, n, name, metric_name=None, signature=None, sage: M.metric() Pseudo-Riemannian metric g on the 4-dimensional pseudo-Riemannian manifold M sage: TestSuite(M).run() - """ if base_manifold and not isinstance(base_manifold, PseudoRiemannianManifold): raise TypeError("the argument 'base_manifold' must be a " + @@ -564,7 +562,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` sage: h = M.metric('h', signature=1); h Lorentzian metric h on the 3-dimensional Riemannian manifold M - """ if name is None or name == self._metric_name: # Default metric associated with the manifold @@ -669,7 +666,6 @@ def volume_form(self, contra=0): 3-vector field on the 3-dimensional Riemannian manifold M sage: eps3.display() ∂/∂x∧∂/∂y∧∂/∂z - """ return self.metric().volume_form(contra=contra) @@ -687,7 +683,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none is provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -738,7 +734,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): g = dx⊗dx + dy⊗dy sage: gV is g.restrict(V) True - """ resu = PseudoRiemannianManifold(self._dim, name, metric_name=self._metric_name, diff --git a/src/sage/manifolds/differentiable/pseudo_riemannian_submanifold.py b/src/sage/manifolds/differentiable/pseudo_riemannian_submanifold.py index 996364cf188..e791cef6781 100644 --- a/src/sage/manifolds/differentiable/pseudo_riemannian_submanifold.py +++ b/src/sage/manifolds/differentiable/pseudo_riemannian_submanifold.py @@ -14,8 +14,8 @@ We start by declaring the ambient manifold `M` and the submanifold `N`:: - sage: M = Manifold(3, 'M', structure="Lorentzian") - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian", start_index=1) + sage: M = Manifold(3, 'M', structure='Lorentzian') + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian', start_index=1) The considered slices being spacelike hypersurfaces, they are Riemannian manifolds. @@ -263,8 +263,8 @@ class PseudoRiemannianSubmanifold(PseudoRiemannianManifold, Let `N` be a 2-dimensional submanifold of a 3-dimensional Riemannian manifold `M`:: - sage: M = Manifold(3, 'M', structure ="Riemannian") - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: M = Manifold(3, 'M', structure ='Riemannian') + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: N 2-dimensional Riemannian submanifold N immersed in the 3-dimensional Riemannian manifold M @@ -301,7 +301,6 @@ class PseudoRiemannianSubmanifold(PseudoRiemannianManifold, :mod:`~sage.manifolds.manifold` and :mod:`~sage.manifolds.differentiable.differentiable_submanifold` - """ def __init__(self, n, name, ambient=None, metric_name=None, signature=None, base_manifold=None, diff_degree=infinity, @@ -323,7 +322,7 @@ def __init__(self, n, name, ambient=None, metric_name=None, 2-dimensional Riemannian submanifold N embedded in the 3-dimensional Lorentzian manifold M sage: S = Manifold(2, 'S', latex_name=r"\Sigma", ambient=M, - ....: structure="Riemannian", start_index=1) + ....: structure='Riemannian', start_index=1) sage: latex(S) \Sigma sage: S.start_index() @@ -338,7 +337,6 @@ def __init__(self, n, name, ambient=None, metric_name=None, sage: N 4-dimensional pseudo-Riemannian submanifold N immersed in the 5-dimensional pseudo-Riemannian manifold M - """ if metric_name is None: metric_name = 'gamma' @@ -383,8 +381,8 @@ def _repr_(self): TESTS:: - sage: M = Manifold(3, 'M', structure="Lorentzian") - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: M = Manifold(3, 'M', structure='Lorentzian') + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: N 2-dimensional Riemannian submanifold N immersed in the 3-dimensional Lorentzian manifold M @@ -393,7 +391,6 @@ def _repr_(self): sage: N 2-dimensional Riemannian submanifold N embedded in the 3-dimensional Lorentzian manifold M - """ if self is not self._manifold: return "Open subset {} of the {}".format(self._name, self._manifold) @@ -422,7 +419,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none is provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -438,8 +435,8 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): EXAMPLES:: - sage: M = Manifold(3, 'M', structure="Riemannian") - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian"); N + sage: M = Manifold(3, 'M', structure='Riemannian') + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian'); N 2-dimensional Riemannian submanifold N immersed in the 3-dimensional Riemannian manifold M sage: S = N.subset('S'); S @@ -464,7 +461,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): Open subset O of the 2-dimensional Riemannian submanifold N embedded in the 3-dimensional Riemannian manifold M - """ resu = PseudoRiemannianSubmanifold(self._dim, name, ambient=self._ambient, @@ -485,21 +481,18 @@ def ambient_metric(self): r""" Return the metric of the ambient manifold. - OUTPUT: - - - the metric of the ambient manifold + OUTPUT: the metric of the ambient manifold EXAMPLES:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: N.ambient_metric() Riemannian metric g on the Euclidean space E^3 sage: N.ambient_metric().display() g = dx⊗dx + dy⊗dy + dz⊗dz sage: N.ambient_metric() is M.metric() True - """ if self._ambient_metric is None: self._ambient_metric = self._ambient.metric() @@ -558,7 +551,6 @@ def first_fundamental_form(self): embedded in the Euclidean space E^3 sage: P.induced_metric().display() g = 14 dt⊗dt - """ if self._first_fundamental_form is None: self._first_fundamental_form = super().metric() @@ -622,7 +614,7 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` gamma = 5 dt⊗dt Setting the argument ``name`` to that declared while constructing - the submanifold (default = ``'gamma'``) yields the same result:: + the submanifold (default: ``'gamma'``) yields the same result:: sage: N.metric(name='gamma') is N.metric() True @@ -636,7 +628,6 @@ class :class:`~sage.manifolds.differentiable.diff_map.DiffMap` sage: h[0, 0] = 1 # initialization sage: h.display() h = dt⊗dt - """ if name is None or name == self._metric_name: return self.first_fundamental_form() @@ -653,9 +644,7 @@ def difft(self): The result is cached, so calling this method multiple times always returns the same result at no additional cost. - OUTPUT: - - - 1-form field on the ambient manifold + OUTPUT: 1-form field on the ambient manifold EXAMPLES: @@ -663,7 +652,7 @@ def difft(self): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') sage: assume(r>0) @@ -680,7 +669,6 @@ def difft(self): sage: N.difft().display() dr = x/sqrt(x^2 + y^2 + z^2) dx + y/sqrt(x^2 + y^2 + z^2) dy + z/sqrt(x^2 + y^2 + z^2) dz - """ if self._dim_foliation == 0: raise ValueError("A foliation is needed to " @@ -700,9 +688,7 @@ def gradt(self): The result is cached, so calling this method multiple times always returns the same result at no additional cost. - OUTPUT: - - - vector field on the ambient manifold + OUTPUT: vector field on the ambient manifold EXAMPLES: @@ -710,7 +696,7 @@ def gradt(self): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') sage: assume(r>0) @@ -727,7 +713,6 @@ def gradt(self): sage: N.gradt().display() grad(r) = x/sqrt(x^2 + y^2 + z^2) e_x + y/sqrt(x^2 + y^2 + z^2) e_y + z/sqrt(x^2 + y^2 + z^2) e_z - """ if self._dim_foliation == 0: raise ValueError("A foliation is needed to perform " @@ -780,7 +765,7 @@ def normal(self): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -808,7 +793,7 @@ def normal(self): part of a foliation, in stereographic coordinates:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U, V) @@ -868,7 +853,6 @@ def normal(self): n = -cos(phi)*sin(the) e_X - sin(phi)*sin(the) e_Y - cos(the) e_Z sage: n.restrict(U).display(format_spec=spher) # long time n = -cos(phi)*sin(the) e_X - sin(phi)*sin(the) e_Y - cos(the) e_Z - """ if self._dim_foliation != 0: # case of a foliation self._normal = self._sgn * self.lapse() * self.gradt() @@ -877,7 +861,7 @@ def normal(self): # case of no foliation: max_frame = self._ambient.default_frame().along(self._immersion) self._normal = self.multivector_field(self._ambient._dim - self._dim, - name="n", + name='n', dest_map=self._immersion) # an auxiliary function: @@ -967,7 +951,7 @@ def ambient_first_fundamental_form(self): A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -995,7 +979,6 @@ def ambient_first_fundamental_form(self): sage: N.ambient_induced_metric()[:] [ x^2/(x^2 + 4) -2*x/(x^2 + 4)] [-2*x/(x^2 + 4) 4/(x^2 + 4)] - """ if self._ambient._dim - self._dim != 1: raise NotImplementedError("ambient_first_fundamental_form() is " @@ -1019,9 +1002,7 @@ def lapse(self): The result is cached, so calling this method multiple times always returns the same result at no additional cost. - OUTPUT: - - - the lapse function, as a scalar field on the ambient manifold + OUTPUT: the lapse function, as a scalar field on the ambient manifold EXAMPLES: @@ -1029,7 +1010,7 @@ def lapse(self): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -1048,7 +1029,6 @@ def lapse(self): N: E^3 → ℝ (x, y, z) ↦ 1 (th_E3, ph_E3, r_E3) ↦ 1 - """ if self._dim_foliation == 0: raise ValueError("A foliation is needed " @@ -1067,9 +1047,7 @@ def shift(self): The result is cached, so calling this method multiple times always returns the same result at no additional cost. - OUTPUT: - - - shift vector field on the ambient manifold + OUTPUT: shift vector field on the ambient manifold EXAMPLES: @@ -1077,7 +1055,7 @@ def shift(self): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -1094,7 +1072,6 @@ def shift(self): Vector field beta on the Euclidean space E^3 sage: N.shift().display() # long time beta = 0 - """ if self._dim_foliation == 0: raise ValueError("A foliation is needed " @@ -1123,7 +1100,7 @@ def ambient_second_fundamental_form(self): A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1151,7 +1128,6 @@ def ambient_second_fundamental_form(self): sage: N.ambient_extrinsic_curvature()[:] # long time [-x^2/(x^2 + 4) 2*x/(x^2 + 4)] [ 2*x/(x^2 + 4) -4/(x^2 + 4)] - """ if self._ambient._dim - self._dim != 1: raise ValueError("ambient_second_fundamental_form is defined only " @@ -1211,7 +1187,7 @@ def second_fundamental_form(self): A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1253,7 +1229,6 @@ def second_fundamental_form(self): submanifold N embedded in the 2-dimensional Riemannian manifold M sage: N.second_fundamental_form().display() K = 2*sqrt(u^4 + 2*u^2 + 2)*u/(u^6 + 3*u^4 + 4*u^2 + 2) du⊗du - """ if self._ambient._dim - self._dim != 1: raise ValueError("second_fundamental_form is defined only for" @@ -1330,7 +1305,7 @@ def projector(self): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -1355,7 +1330,6 @@ def projector(self): sage: N.projector().contract(N.normal()).display() # long time 0 - """ if self._ambient._dim - self._dim != 1: raise NotImplementedError("projector() is implemented only for " @@ -1389,7 +1363,7 @@ def project(self, tensor): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -1412,7 +1386,6 @@ def project(self, tensor): True Note that the output of ``project()`` is not cached. - """ if self._ambient._dim - self._dim != 1: raise NotImplementedError("project() is implemented only for " @@ -1439,7 +1412,7 @@ def mixed_projection(self, tensor, indices=0): INPUT: - ``tensor`` -- any tensor field, eventually along the submanifold if - no foliation is provided. + no foliation is provided - ``indices`` -- (default: ``0``) list of integers containing the indices on which the projection is made on the normal vector. By default, all projections are made on the submanifold. If @@ -1447,9 +1420,7 @@ def mixed_projection(self, tensor, indices=0): the normal vector, all the other ones with the orthogonal projection operator. - OUTPUT: - - - tensor field of rank `k`-``len(indices)`` + OUTPUT: tensor field of rank `k`-``len(indices)`` EXAMPLES: @@ -1457,7 +1428,7 @@ def mixed_projection(self, tensor, indices=0): radii:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -1496,7 +1467,6 @@ def mixed_projection(self, tensor, indices=0): E^3 → ℝ (x, y, z) ↦ 1 (th_E3, ph_E3, r_E3) ↦ 1 - """ if self._ambient._dim - self._dim != 1: raise NotImplementedError("mixed_projection() is implemented only " @@ -1539,16 +1509,14 @@ def gauss_curvature(self): The result is cached, so calling this method multiple times always returns the same result at no additional cost. - OUTPUT: - - - the Gauss curvature as a scalar field on the submanifold + OUTPUT: the Gauss curvature as a scalar field on the submanifold EXAMPLES: A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1570,7 +1538,6 @@ def gauss_curvature(self): N → ℝ on U: x ↦ -1 on V: y ↦ -1 - """ if self._ambient._dim - self._dim != 1: raise ValueError("gauss_curvature is defined only for " @@ -1595,7 +1562,7 @@ def principal_directions(self, chart): INPUT: - - ``chart`` -- chart in which the principal directions are to be + - ``chart`` -- chart in which the principal directions are to be computed OUTPUT: @@ -1608,7 +1575,7 @@ def principal_directions(self, chart): A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1628,7 +1595,6 @@ def principal_directions(self, chart): embedded in the Euclidean plane E^2, -1)] sage: N.principal_directions(stereoN)[0][0].display() # long time e_0 = ∂/∂x - """ if self._ambient._dim - self._dim != 1: raise ValueError("principal directions is defined only for " @@ -1662,7 +1628,7 @@ def principal_curvatures(self, chart): INPUT: - - ``chart`` -- chart in which the principal curvatures are to be + - ``chart`` -- chart in which the principal curvatures are to be computed OUTPUT: @@ -1675,7 +1641,7 @@ def principal_curvatures(self, chart): A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1697,7 +1663,6 @@ def principal_curvatures(self, chart): k_0: N → ℝ on U: x ↦ -1 on W: y ↦ -1 - """ if self._ambient._dim - self._dim != 1: raise ValueError("principal_curvatures is defined only for " @@ -1724,16 +1689,14 @@ def mean_curvature(self): The result is cached, so calling this method multiple times always returns the same result at no additional cost. - OUTPUT: - - - the mean curvature, as a scalar field on the submanifold + OUTPUT: the mean curvature, as a scalar field on the submanifold EXAMPLES: A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1755,7 +1718,6 @@ def mean_curvature(self): N → ℝ on U: x ↦ -1 on V: y ↦ -1 - """ if self._ambient._dim - self._dim != 1: raise ValueError("mean_curvature is defined only for " @@ -1787,7 +1749,7 @@ def shape_operator(self): A unit circle embedded in the Euclidean plane:: sage: M. = EuclideanSpace() - sage: N = Manifold(1, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(1, 'N', ambient=M, structure='Riemannian') sage: U = N.open_subset('U') sage: V = N.open_subset('V') sage: N.declare_union(U,V) @@ -1807,7 +1769,6 @@ def shape_operator(self): submanifold N embedded in the Euclidean plane E^2 sage: N.shape_operator().display() # long time -∂/∂x⊗dx - """ if self._ambient._dim - self._dim != 1: raise ValueError("shape_operator is defined only for " @@ -1827,7 +1788,7 @@ def clear_cache(self): EXAMPLES:: sage: M. = EuclideanSpace() - sage: N = Manifold(2, 'N', ambient=M, structure="Riemannian") + sage: N = Manifold(2, 'N', ambient=M, structure='Riemannian') sage: C. = N.chart(r'th:(0,pi):\theta ph:(-pi,pi):\phi') sage: r = var('r', domain='real') # foliation parameter sage: assume(r>0) @@ -1848,7 +1809,6 @@ def clear_cache(self): False sage: n == N.normal() True - """ self.difft.clear_cache() self.gradt.clear_cache() diff --git a/src/sage/manifolds/differentiable/scalarfield.py b/src/sage/manifolds/differentiable/scalarfield.py index 179909868a8..be1d6d3b97e 100644 --- a/src/sage/manifolds/differentiable/scalarfield.py +++ b/src/sage/manifolds/differentiable/scalarfield.py @@ -619,7 +619,6 @@ class DiffScalarField(ScalarField): sage: TestSuite(f).run() sage: TestSuite(zer).run() - """ def __init__(self, parent, coord_expression=None, chart=None, name=None, latex_name=None): @@ -639,7 +638,6 @@ def __init__(self, parent, coord_expression=None, chart=None, name=None, Algebra of differentiable scalar fields on the 2-dimensional differentiable manifold M sage: TestSuite(f).run() - """ ScalarField.__init__(self, parent, coord_expression=coord_expression, chart=chart, name=name, latex_name=latex_name) @@ -658,7 +656,6 @@ def _init_derived(self): sage: X. = M.chart() sage: f = M.scalar_field({X: x+y}) sage: f._init_derived() - """ ScalarField._init_derived(self) # derived quantities of the parent class self._differential = None # differential 1-form of the scalar field @@ -684,12 +681,11 @@ def _del_derived(self): sage: f._del_derived() sage: f._restrictions # restrictions are derived quantities {} - """ ScalarField._del_derived(self) # derived quantities of the mother class self._differential = None # reset of the differential # First deletes any reference to self in the vectors' dictionaries: - for vid, val in self._lie_derivatives.items(): + for val in self._lie_derivatives.values(): del val[0]._lie_der_along_self[id(self)] # Then clears the dictionary of Lie derivatives self._lie_derivatives.clear() @@ -710,7 +706,6 @@ def tensor_type(self): sage: f = M.scalar_field(x+2*y) sage: f.tensor_type() (0, 0) - """ return self._tensor_type @@ -793,7 +788,6 @@ def differential(self) -> DiffForm: 2-form ddg on the 3-dimensional differentiable manifold M sage: ddg == 0 True - """ from sage.tensor.modules.format_utilities import (format_unop_txt, format_unop_latex) @@ -873,7 +867,6 @@ def lie_derivative(self, vector): sage: f.lie_der(v).display() M → ℝ (x, y) ↦ 0 - """ # The Lie derivative is cached in _lie_derivatives if neither # the scalar field nor ``vector`` have been modified. @@ -906,14 +899,12 @@ def hodge_dual( INPUT: - - ``nondegenerate_tensor``: a non-degenerate bilinear form defined on the same manifold + - ``nondegenerate_tensor`` -- a non-degenerate bilinear form defined on the same manifold as the current differential form; must be an instance of :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric` or :class:`~sage.manifolds.differentiable.symplectic_form.SymplecticForm`. - OUTPUT: - - - the `n`-form `*f` + OUTPUT: the `n`-form `*f` EXAMPLES: @@ -943,7 +934,6 @@ def hodge_dual( sage: f.hodge_dual(g) == g.hodge_star(f) True - """ from sage.tensor.modules.format_utilities import ( format_unop_txt, @@ -1009,7 +999,6 @@ def bracket(self, other): See :meth:`~sage.manifolds.differentiable.multivectorfield.MultivectorFieldParal.bracket` for other examples. - """ if isinstance(other, DiffScalarField): return self._domain.intersection(other._domain).zero_scalar_field() @@ -1035,9 +1024,7 @@ def wedge(self, other): - ``other`` -- a differential form or a multivector field `a` - OUTPUT: - - - the product `f a`, where `f` is ``self`` + OUTPUT: the product `f a`, where `f` is ``self`` EXAMPLES:: @@ -1050,7 +1037,6 @@ def wedge(self, other): 2-form f*a on the 2-dimensional differentiable manifold M sage: s.display() f*a = (x*y^3 + x^2*y) dx∧dy - """ return self * other @@ -1066,9 +1052,7 @@ def degree(self): :meth:`~sage.manifolds.differentiable.multivectorfield.MultivectorField.degree` (multivector fields). - OUTPUT: - - - 0 + OUTPUT: 0 EXAMPLES:: @@ -1077,7 +1061,6 @@ def degree(self): sage: f = M.scalar_field({X: x+y^2}) sage: f.degree() 0 - """ return self._tensor_rank @@ -1164,7 +1147,6 @@ def gradient(self, metric=None): Vector field grad_h(f) on the Euclidean plane E^2 sage: v.display() grad_h(f) = -cos(phi) e_r + (-r^2*sin(phi) - sin(phi)) e_phi - """ default_metric = metric is None if default_metric: @@ -1257,7 +1239,6 @@ def laplacian(self, metric=None): sage: s == f.gradient(h).div(h) True - """ default_metric = metric is None if default_metric: @@ -1334,7 +1315,6 @@ def dalembertian(self, metric=None): sage: from sage.manifolds.operators import dalembertian sage: dalembertian(f) == s True - """ default_metric = metric is None if default_metric: diff --git a/src/sage/manifolds/differentiable/scalarfield_algebra.py b/src/sage/manifolds/differentiable/scalarfield_algebra.py index 3ee079f5720..205f8cef841 100644 --- a/src/sage/manifolds/differentiable/scalarfield_algebra.py +++ b/src/sage/manifolds/differentiable/scalarfield_algebra.py @@ -367,7 +367,6 @@ class DiffScalarFieldAlgebra(ScalarFieldAlgebra): It is passed also for `C^k(W)`:: sage: TestSuite(CW).run() - """ Element = DiffScalarField @@ -388,7 +387,6 @@ def __init__(self, domain): sage: type(CM).__base__ sage: TestSuite(CM).run() - """ ScalarFieldAlgebra.__init__(self, domain) @@ -396,7 +394,7 @@ def __init__(self, domain): def _coerce_map_from_(self, other): r""" - Determine whether coercion to self exists from other parent + Determine whether coercion to ``self`` exists from other parent. TESTS:: @@ -417,7 +415,6 @@ def _coerce_map_from_(self, other): False sage: CU._coerce_map_from_(CM) True - """ from sage.manifolds.chart_func import ChartFunctionRing @@ -447,7 +444,6 @@ def _repr_(self): 'Algebra of differentiable scalar fields on the 2-dimensional differentiable manifold M' sage: repr(CM) # indirect doctest 'Algebra of differentiable scalar fields on the 2-dimensional differentiable manifold M' - """ return "Algebra of differentiable scalar fields on " + \ "the {}".format(self._domain) diff --git a/src/sage/manifolds/differentiable/symplectic_form.py b/src/sage/manifolds/differentiable/symplectic_form.py index aa0f0caac73..52a076bfbe8 100644 --- a/src/sage/manifolds/differentiable/symplectic_form.py +++ b/src/sage/manifolds/differentiable/symplectic_form.py @@ -102,7 +102,6 @@ class SymplecticForm(DiffForm): sage: diff(omega).display() domega = 0 - """ _name: str @@ -129,7 +128,6 @@ def __init__( sage: omega Symplectic form omega on the 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 - """ try: vector_field_module = manifold.vector_field_module() @@ -239,11 +237,9 @@ def restrict( - ``subdomain`` -- open subset `U` of the symplectic form's domain - ``dest_map`` -- (default: ``None``) smooth destination map `\Phi:\ U \to V`, where `V` is a subdomain of the symplectic form's domain - If None, the restriction of the initial vector field module is used. - - OUTPUT: + If ``None``, the restriction of the initial vector field module is used. - - the restricted symplectic form. + OUTPUT: the restricted symplectic form EXAMPLES:: @@ -555,7 +551,7 @@ def hodge_star(self, pform: DiffForm) -> DiffForm: INPUT: - - ``pform``: a `p`-form `A`; must be an instance of + - ``pform`` -- a `p`-form `A`; must be an instance of :class:`~sage.manifolds.differentiable.scalarfield.DiffScalarField` for `p=0` and of :class:`~sage.manifolds.differentiable.diff_form.DiffForm` or @@ -657,7 +653,7 @@ class SymplecticFormParal(SymplecticForm, DiffFormParal): Standard symplectic form on `\RR^2`:: - sage: M. = EuclideanSpace(name="R2", latex_name=r"\mathbb{R}^2") + sage: M. = EuclideanSpace(name='R2', latex_name=r"\mathbb{R}^2") sage: omega = M.symplectic_form(name='omega', latex_name=r'\omega') sage: omega Symplectic form omega on the Euclidean plane R2 @@ -683,7 +679,6 @@ def __init__( sage: omega = SymplecticFormParal(M, name='omega', latex_name=r'\omega') sage: omega Symplectic form omega on the Euclidean plane E^2 - """ try: vector_field_module = manifold.vector_field_module() @@ -729,8 +724,8 @@ def _del_derived(self, del_restrictions: bool = True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the - restrictions of ``self`` to subdomains are deleted. + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the + restrictions of ``self`` to subdomains are deleted TESTS:: @@ -762,12 +757,10 @@ def restrict( - ``subdomain`` -- open subset `U` of the symplectic form's domain - ``dest_map`` -- (default: ``None``) smooth destination map - `\Phi:\ U \rightarrow V`, where `V` is a subdomain of the symplectic form's domain - If None, the restriction of the initial vector field module is used. - - OUTPUT: + `\Phi:\ U \rightarrow V`, where `V` is a subdomain of the symplectic form's domain. + If ``None``, the restriction of the initial vector field module is used. - - the restricted symplectic form. + OUTPUT: the restricted symplectic form EXAMPLES: @@ -890,7 +883,7 @@ def poisson( self_matrix = matrix( [ [ - self.comp(frame)[i, j, chart].expr(method="SR") + self.comp(frame)[i, j, chart].expr(method='SR') for j in fmodule.irange() ] for i in fmodule.irange() diff --git a/src/sage/manifolds/differentiable/symplectic_form_test.py b/src/sage/manifolds/differentiable/symplectic_form_test.py index 5bc519af6d3..c38feb90cef 100644 --- a/src/sage/manifolds/differentiable/symplectic_form_test.py +++ b/src/sage/manifolds/differentiable/symplectic_form_test.py @@ -56,11 +56,11 @@ class TestCoherenceOfFormulas: We check it for the examples of `\R^2` and `S^2`, which should be enough. """ - @pytest.fixture(params=["R2", "S2"]) + @pytest.fixture(params=['R2', 'S2']) def M(self, request: FixtureRequest): - if request.param == "R2": - return StandardSymplecticSpace(2, "R2", symplectic_name="omega") - elif request.param == "S2": + if request.param == 'R2': + return StandardSymplecticSpace(2, 'R2', symplectic_name='omega') + elif request.param == 'S2': # Init stereographic coordinates to get a complete atlas return Sphere(2, coordinates='stereographic') @@ -166,7 +166,7 @@ def generic_scalar_field(M: DifferentiableManifold, name: str) -> DiffScalarFiel class TestR2VectorSpace: @pytest.fixture def M(self): - return StandardSymplecticSpace(2, "R2", symplectic_name="omega") + return StandardSymplecticSpace(2, 'R2', symplectic_name='omega') @pytest.fixture def omega(self, M): @@ -187,7 +187,7 @@ def test_hamiltonian_vector_field( assert str(XH.display()) == r"XH = d(H)/dp e_q - d(H)/dq e_p" def test_flat(self, M: StandardSymplecticSpace, omega: SymplecticForm): - X = M.vector_field(1, 2, name="X") + X = M.vector_field(1, 2, name='X') assert str(X.display()) == r"X = e_q + 2 e_p" assert str(omega.flat(X).display()) == r"X_flat = 2 dq - dp" diff --git a/src/sage/manifolds/differentiable/tangent_space.py b/src/sage/manifolds/differentiable/tangent_space.py index 62cf268094e..fd2576f8917 100644 --- a/src/sage/manifolds/differentiable/tangent_space.py +++ b/src/sage/manifolds/differentiable/tangent_space.py @@ -228,7 +228,6 @@ class TangentSpace(FiniteRankFreeModule): :class:`~sage.tensor.modules.finite_rank_free_module.FiniteRankFreeModule` for more documentation. - """ Element = TangentVector @@ -246,7 +245,6 @@ def __init__(self, point: ManifoldPoint, base_ring=None): Tangent space at Point p on the 2-dimensional differentiable manifold M sage: TestSuite(Tp).run() - """ manif = point._manifold name = "T_{} {}".format(point._name, manif._name) @@ -342,7 +340,6 @@ def _repr_(self): sage: Tp Tangent space at Point p on the 2-dimensional differentiable manifold M - """ return "Tangent space at {}".format(self._point) @@ -361,7 +358,6 @@ def _an_element_(self): manifold M sage: Tp._an_element_().display() ∂/∂x + 2 ∂/∂y - """ resu = self.element_class(self) if self._def_basis is not None: @@ -390,7 +386,6 @@ def dimension(self): sage: dim(Tp) 2 - """ # The dimension is the rank of self as a free module: return self._rank @@ -411,6 +406,5 @@ def base_point(self): Point p on the 2-dimensional differentiable manifold M sage: Tp.base_point() is p True - """ return self._point diff --git a/src/sage/manifolds/differentiable/tangent_vector.py b/src/sage/manifolds/differentiable/tangent_vector.py index d7a18d51e5f..1bd1dd5c647 100644 --- a/src/sage/manifolds/differentiable/tangent_vector.py +++ b/src/sage/manifolds/differentiable/tangent_vector.py @@ -120,7 +120,6 @@ class TangentVector(FiniteRankFreeModuleElement): :class:`~sage.tensor.modules.free_module_element.FiniteRankFreeModuleElement` for more documentation. - """ def __init__(self, parent, name=None, latex_name=None): r""" @@ -137,7 +136,6 @@ def __init__(self, parent, name=None, latex_name=None): manifold M sage: v[:] = 5, -3/2 sage: TestSuite(v).run() - """ FiniteRankFreeModuleElement.__init__(self, parent, name=name, latex_name=latex_name) @@ -159,7 +157,6 @@ def _repr_(self): 'Tangent vector v at Point p on the 2-dimensional differentiable manifold M' sage: repr(v) # indirect doctest 'Tangent vector v at Point p on the 2-dimensional differentiable manifold M' - """ from sage.manifolds.differentiable.examples.euclidean import EuclideanSpace if isinstance(self._point.parent(), EuclideanSpace): @@ -210,10 +207,10 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, - ``scale`` -- (default: 1) value by which the length of the arrow representing the vector is multiplied - - ``color`` -- (default: 'blue') color of the arrow representing the + - ``color`` -- (default: ``'blue'``) color of the arrow representing the vector - - ``print_label`` -- (boolean; default: ``True``) determines whether a + - ``print_label`` -- boolean (default: ``True``); determines whether a label is printed next to the arrow representing the vector - ``label`` -- (string; default: ``None``) label printed next to the @@ -450,7 +447,6 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, graph_v = v.plot(mapping=F) graph_S2 = XS.plot(chart=X3, mapping=F, number_values=9) sphinx_plot(graph_v + graph_S2) - """ from sage.plot.arrow import arrow2d from sage.plot.text import text @@ -605,7 +601,6 @@ def __call__(self, f): sage: bool( v(omega) == omega(v) ) True - """ if isinstance(f, FreeModuleAltForm): # Case of self acting on a linear form diff --git a/src/sage/manifolds/differentiable/tensorfield.py b/src/sage/manifolds/differentiable/tensorfield.py index 2a958a20640..3ef7ccff001 100644 --- a/src/sage/manifolds/differentiable/tensorfield.py +++ b/src/sage/manifolds/differentiable/tensorfield.py @@ -73,7 +73,7 @@ TensorType = Tuple[int, int] -T = TypeVar("T", bound="TensorField") +T = TypeVar("T", bound='TensorField') class TensorField(ModuleElementWithMutability): @@ -83,7 +83,7 @@ class TensorField(ModuleElementWithMutability): An instance of this class is a tensor field along a differentiable manifold `U` with values on a differentiable manifold `M`, via a differentiable map `\Phi: U \rightarrow M`. More precisely, given two - non-negative integers `k` and `l` and a differentiable map + nonnegative integers `k` and `l` and a differentiable map .. MATH:: @@ -407,7 +407,6 @@ class TensorField(ModuleElementWithMutability): Traceback (most recent call last): ... ValueError: the name of an immutable element cannot be changed - """ _name: Optional[str] @@ -467,7 +466,6 @@ def __init__( manifold M sage: type(t1) == type(t) True - """ if parent is None: parent = vector_field_module.tensor_module(*tensor_type) @@ -559,7 +557,6 @@ def _repr_(self): sage: t = M.tensor_field(1, 3, name='t') sage: t Tensor field t of type (1,3) on the 2-dimensional differentiable manifold M - """ # Special cases if self._tensor_type == (0,2) and self._sym == ((0,1),): @@ -588,7 +585,6 @@ def _latex_(self): sage: t = M.tensor_field(1, 3, name='t', latex_name=r'\tau') sage: latex(t) \tau - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -628,7 +624,6 @@ def set_name(self, name: Optional[str] = None, latex_name: Optional[str] = None) manifold M sage: latex(t) a - """ if self.is_immutable(): raise ValueError("the name of an immutable element " @@ -658,7 +653,6 @@ def _new_instance(self): True sage: t1.parent() is t.parent() True - """ return type(self)(self._vmodule, self._tensor_type, sym=self._sym, antisym=self._antisym, parent=self.parent()) @@ -674,7 +668,6 @@ def _final_repr(self, description: str) -> str: sage: t = M.tensor_field(1, 3, name='t') sage: t._final_repr('Tensor field t ') 'Tensor field t on the 2-dimensional differentiable manifold M' - """ if self._domain == self._ambient_domain: description += "on the {}".format(self._domain) @@ -692,7 +685,6 @@ def _init_derived(self): sage: M = Manifold(2, 'M') sage: t = M.tensor_field(1, 3, name='t') sage: t._init_derived() - """ self._lie_derivatives = {} # dict. of Lie derivatives of self (keys: id(vector)) @@ -705,10 +697,9 @@ def _del_derived(self): sage: M = Manifold(2, 'M') sage: t = M.tensor_field(1, 3, name='t') sage: t._del_derived() - """ # First deletes any reference to self in the vectors' dictionaries: - for vid, val in self._lie_derivatives.items(): + for val in self._lie_derivatives.values(): del val[0]._lie_der_along_self[id(self)] # Then clears the dictionary of Lie derivatives self._lie_derivatives.clear() @@ -731,7 +722,6 @@ def _del_restrictions(self): sage: t._del_restrictions() sage: t._restrictions {} - """ self._restrictions.clear() self._extensions_graph = {self._domain: self} @@ -782,7 +772,6 @@ def _init_components(self, *comp, **kwargs): sage: v._init_components(1/2, -1) sage: v.display() 1/2 ∂/∂x - ∂/∂y - """ comp0 = comp[0] self._is_zero = False # a priori @@ -827,7 +816,6 @@ def domain(self) -> DifferentiableManifold: sage: h = t.restrict(U) sage: h.domain() Open subset U of the 2-dimensional differentiable manifold M - """ return self._domain @@ -854,7 +842,6 @@ def base_module(self) -> VectorFieldModule: sage: XM = M.vector_field_module() sage: XM.an_element().base_module() is XM True - """ return self._vmodule @@ -876,7 +863,6 @@ def tensor_type(self) -> TensorType: sage: v = M.vector_field() sage: v.tensor_type() (1, 0) - """ return self._tensor_type @@ -898,7 +884,6 @@ def tensor_rank(self): sage: v = M.vector_field() sage: v.tensor_rank() 1 - """ return self._tensor_rank @@ -921,7 +906,6 @@ def symmetries(self): sage: t = M.tensor_field(2,2, antisym=[(0,1),(2,3)]) sage: t.symmetries() no symmetry; antisymmetries: [(0, 1), (2, 3)] - """ if not self._sym: s = "no symmetry; " @@ -953,7 +937,6 @@ def set_immutable(self): sage: a.set_immutable() sage: aU.is_immutable() True - """ for rst in self._restrictions.values(): rst.set_immutable() @@ -993,7 +976,6 @@ def set_restriction(self, rst: TensorField): sage: v.set_restriction(t) sage: v.restrict(U) == t.restrict(U) True - """ if self.is_immutable(): raise ValueError("the restrictions of an immutable element " @@ -1047,9 +1029,7 @@ def restrict( to `U` is used, `\Phi` being the differentiable map `S \rightarrow M` associated with the tensor field - OUTPUT: - - - :class:`TensorField` representing the restriction + OUTPUT: :class:`TensorField` representing the restriction EXAMPLES: @@ -1109,7 +1089,6 @@ def restrict( True sage: vU.restrict(U) is vU True - """ if (subdomain == self._domain and (dest_map is None or dest_map == self._vmodule._dest_map)): @@ -1236,7 +1215,6 @@ def _set_comp_unsafe(self, basis=None): ... ValueError: no basis could be found for computing the components in the Coordinate frame (V, (∂/∂u,∂/∂v)) - """ if basis is None: basis = self._domain._def_frame @@ -1307,7 +1285,6 @@ def set_comp(self, basis=None): ... ValueError: the components of an immutable element cannot be changed - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1370,7 +1347,6 @@ def _add_comp_unsafe(self, basis=None): sage: t.display(e_uv) t = (u + v) ∂/∂v⊗du⊗dv - """ if basis is None: basis = self._domain._def_frame @@ -1437,7 +1413,6 @@ def add_comp(self, basis=None) -> Components: ... ValueError: the components of an immutable element cannot be changed - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1512,7 +1487,6 @@ def add_comp_by_continuation(self, frame, subdomain, chart=None): a = (-4*u*v - u) ∂/∂u + (2*u^2 - 2*v^2 - v) ∂/∂v and `a` is defined on the entire manifold `S^2`. - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1538,14 +1512,14 @@ def add_expr_from_subdomain(self, frame, subdomain): - ``frame`` -- vector frame `e` in which the components are to be set - ``subdomain`` -- open subset of `e`'s domain in which the - components have additional expressions. + components have additional expressions EXAMPLES: We are going to consider a vector field in `\RR^3` along the 2-sphere:: - sage: M = Manifold(3, 'M', structure="Riemannian") - sage: S = Manifold(2, 'S', structure="Riemannian") + sage: M = Manifold(3, 'M', structure='Riemannian') + sage: S = Manifold(2, 'S', structure='Riemannian') sage: E. = M.chart() Let us define ``S`` in terms of stereographic charts:: @@ -1612,7 +1586,6 @@ def add_expr_from_subdomain(self, frame, subdomain): S → ℝ on U: (x, y) ↦ x^2 + y^2 on V: (xp, yp) ↦ 1/(xp^2 + yp^2) - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -1702,7 +1675,6 @@ def comp(self, basis=None, from_basis=None): sage: t.comp(h)[:] [ 0 -u^3*v/(v + 1)] [ 0 -u*v] - """ if basis is None: basis = self._domain._def_frame @@ -1823,7 +1795,6 @@ def display(self, frame=None, chart=None): sage: t.disp(e_uv) t = (1/2*u + 1/2) ∂/∂u⊗du + (1/2*u - 1/2) ∂/∂u⊗dv + (1/2*v + 1/2) ∂/∂v⊗du + (1/2*v - 1/2) ∂/∂v⊗dv - """ if frame is None: if chart is not None: @@ -1877,12 +1848,12 @@ def display_comp(self, frame=None, chart=None, coordinate_labels=True, - ``chart`` -- (default: ``None``) chart specifying the coordinate expression of the components; if ``None``, the default chart of the tensor field domain is used - - ``coordinate_labels`` -- (default: ``True``) boolean; if ``True``, + - ``coordinate_labels`` -- boolean (default: ``True``); if ``True``, coordinate symbols are used by default (instead of integers) as index labels whenever ``frame`` is a coordinate frame - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero components are displayed - - ``only_nonredundant`` -- (default: ``False``) boolean; if ``True``, + - ``only_nonredundant`` -- boolean (default: ``False``); if ``True``, only nonredundant components are displayed in case of symmetries EXAMPLES: @@ -1919,7 +1890,6 @@ def display_comp(self, frame=None, chart=None, coordinate_labels=True, See documentation of :meth:`sage.manifolds.differentiable.tensorfield_paral.TensorFieldParal.display_comp` for more options. - """ if frame is None: if chart is not None: @@ -1986,7 +1956,6 @@ def __getitem__(self, args): sage: t.__getitem__('^a_a').display() M → ℝ on U: (x, y) ↦ (x + 1)*y + x - """ if isinstance(args, str): # tensor with specified indices return TensorWithIndices(self, args).update() @@ -2008,7 +1977,7 @@ def __getitem__(self, args): def __setitem__(self, args, value): r""" - Sets a component with respect to some vector frame. + Set a component with respect to some vector frame. INPUT: @@ -2038,7 +2007,6 @@ def __setitem__(self, args, value): sage: t.__setitem__(slice(None), [[x+y, -2], [3*y^2, x*y]]) sage: t.display() t = (x + y) ∂/∂x⊗dx - 2 ∂/∂x⊗dy + 3*y^2 ∂/∂y⊗dx + x*y ∂/∂y⊗dy - """ if isinstance(args, list): # case of [[...]] syntax if not isinstance(args[0], (int, Integer, slice)): @@ -2102,7 +2070,6 @@ def copy_from(self, other): s = (x + y) ∂/∂x⊗dx + 2 ∂/∂y⊗dx + (-y + 1) ∂/∂y⊗dy sage: s == t False - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -2164,7 +2131,6 @@ def copy(self, name=None, latex_name=None): (x + y) ∂/∂x⊗dx + 2 ∂/∂y⊗dx + (-y + 1) ∂/∂y⊗dy sage: s == t False - """ resu = self._new_instance() # set resu name @@ -2214,7 +2180,6 @@ def _common_subdomains(self, other): sage: sorted(t._common_subdomains(a), key=str) [Open subset U of the 2-dimensional differentiable manifold M, Open subset V of the 2-dimensional differentiable manifold M] - """ resu = [] for dom in self._restrictions: @@ -2230,9 +2195,7 @@ def __eq__(self, other): - ``other`` -- a tensor field or 0 - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise TESTS:: @@ -2345,7 +2308,6 @@ def __ne__(self, other): False sage: t != 0 True - """ return not (self == other) @@ -2353,9 +2315,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of ``self`` + OUTPUT: an exact copy of ``self`` TESTS:: @@ -2376,7 +2336,6 @@ def __pos__(self): manifold M sage: s.display(e_xy) +t = (x + y) ∂/∂x⊗dx + 2 ∂/∂y⊗dx + (-y + 1) ∂/∂y⊗dy - """ resu = self._new_instance() for dom, rst in self._restrictions.items(): @@ -2392,9 +2351,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the tensor field `-T`, where `T` is ``self`` + OUTPUT: the tensor field `-T`, where `T` is ``self`` TESTS:: @@ -2423,7 +2380,6 @@ def __neg__(self): -t = -u ∂/∂u⊗dv - v ∂/∂v⊗dv sage: s == -t # indirect doctest True - """ resu = self._new_instance() for dom, rst in self._restrictions.items(): @@ -2485,7 +2441,6 @@ def _add_(self, other): True sage: z._add_(a) == a True - """ # Case zero: if self._is_zero: @@ -2554,7 +2509,6 @@ def _sub_(self, other): True sage: z._sub_(a) == -a True - """ # Case zero: if self._is_zero: @@ -2579,7 +2533,7 @@ def _sub_(self, other): def _rmul_(self, scalar): r""" - Reflected multiplication operator: performs ``scalar * self`` + Reflected multiplication operator: performs ``scalar * self``. This is actually the multiplication by an element of the ring over which the tensor field module is constructed. @@ -2589,9 +2543,7 @@ def _rmul_(self, scalar): - ``scalar`` -- scalar field in the scalar field algebra over which the module containing ``self`` is defined - OUTPUT: - - - the tensor field ``scalar * self`` + OUTPUT: the tensor field ``scalar * self`` TESTS:: @@ -2633,7 +2585,6 @@ def _rmul_(self, scalar): True sage: z._rmul_(f) == z True - """ # Case zero: if scalar._is_zero: @@ -2755,7 +2706,6 @@ def __mul__(self, other: TensorField) -> TensorField: v**2/8) ∂/∂v⊗dv sage: s == f*a True - """ from sage.manifolds.differentiable.mixed_form import MixedForm if isinstance(other, MixedForm): @@ -2802,9 +2752,7 @@ def __truediv__(self, scalar) -> TensorField: - ``scalar`` -- scalar field in the scalar field algebra over which the module containing ``self`` is defined - OUTPUT: - - - the tensor field ``scalar * self`` + OUTPUT: the tensor field ``scalar * self`` TESTS:: @@ -2849,7 +2797,6 @@ def __truediv__(self, scalar) -> TensorField: True sage: 2*s == a True - """ resu = self._new_instance() for dom, rst in self._restrictions.items(): @@ -2930,7 +2877,6 @@ def __call__(self, *args): True sage: s.restrict(V) == t.restrict(V)(w.restrict(V)) True - """ p = len(args) if p == 1 and self._tensor_type == (1,1): @@ -3159,7 +3105,6 @@ def trace( sage: b['^k_.k'] == s # long time True - """ if using is not None: if self.tensor_type() != (0, 2): @@ -3370,7 +3315,6 @@ def contract(self, *args: Union[int, TensorField]) -> TensorField: zero: M → ℝ on U: (x, y) ↦ 0 on V: (u, v) ↦ 0 - """ nargs = len(args) for i, arg in enumerate(args): @@ -3496,7 +3440,6 @@ def symmetrize(self, *pos): For more details and examples, see :meth:`sage.tensor.modules.free_module_tensor.FreeModuleTensor.symmetrize`. - """ resu_rst = [] for rst in self._restrictions.values(): @@ -3558,7 +3501,6 @@ def antisymmetrize(self, *pos): For more details and examples, see :meth:`sage.tensor.modules.free_module_tensor.FreeModuleTensor.antisymmetrize`. - """ resu_rst = [] for rst in self._restrictions.values(): @@ -3640,7 +3582,6 @@ def lie_derivative(self, vector): sage: f = M.scalar_field({c_xy: 3*x-1, c_uv: 3/2*(u+v)-1}) sage: a.lie_der(w)(f) == w(a(f)) - a(w(f)) # long time True - """ if vector._tensor_type != (1,0): raise TypeError("the argument must be a vector field") @@ -3729,7 +3670,6 @@ def at(self, point: ManifoldPoint) -> FreeModuleTensor: a = 11/2 ∂/∂u⊗du - 3/2 ∂/∂u⊗dv + 1/2 ∂/∂v⊗du + 7/2 ∂/∂v⊗dv sage: p.coord(c_uv) # to check the above expression (5, -1) - """ if point not in self._domain: raise ValueError("the {} is not a point in the ".format(point) + @@ -3872,7 +3812,6 @@ def up( False sage: dd1tuu == t # should be true True - """ n_con = self._tensor_type[0] # number of contravariant indices = k if pos is None: @@ -4031,7 +3970,6 @@ def down( True sage: uu1tdd == t # not true, because of the order of index raising to get uu1tdd False - """ n_con = self._tensor_type[0] # number of contravariant indices = k if pos is None: @@ -4166,7 +4104,6 @@ def divergence(self, metric=None): Vector field div(v⊗w) on the Euclidean plane E^2 sage: s.display() div(v⊗w) = -y e_x + x e_y - """ n_con = self._tensor_type[0] # number of contravariant indices = k n_cov = self._tensor_type[1] # number of covariant indices = l @@ -4265,7 +4202,6 @@ def laplacian(self, metric=None): sage: Dv.display() Delta_h(v) = -(8*x^5 - 2*x^4 - x^2*y^2 + 15*x^3 - 4*x^2 + 6*x - 2)/(x^4 + 2*x^2 + 1) e_x - 3*x^3*y/(x^4 + 2*x^2 + 1) e_y - """ n_con = self._tensor_type[0] # number of contravariant indices = k trank = self._tensor_rank # k + l @@ -4357,7 +4293,6 @@ def dalembertian(self, metric=None): sage: De.display() # long time Box(e) = 0 - """ default_metric = metric is None if default_metric: @@ -4399,9 +4334,7 @@ def along(self, mapping): - ``mapping`` -- differentiable map `\Phi: U \rightarrow M` - OUTPUT: - - - tensor field `\tilde t` along `U` defined above. + OUTPUT: tensor field `\tilde t` along `U` defined above EXAMPLES: @@ -4465,7 +4398,6 @@ def along(self, mapping): True sage: wa.at(K(7*pi/4)) == eU[0].at(Phi(I(7*pi/4))) # since eU[0]=∂/∂x True - """ dom = self._domain if self._ambient_domain is not dom: @@ -4526,7 +4458,7 @@ def set_calc_order(self, symbol, order, truncate=False): - ``order`` -- integer; the order `n` of the expansion, defined as the degree of the polynomial representing the truncated power series in ``symbol`` - - ``truncate`` -- (default: ``False``) determines whether the + - ``truncate`` -- boolean (default: ``False``); determines whether the components of ``self`` are replaced by their expansions to the given order @@ -4581,7 +4513,6 @@ def set_calc_order(self, symbol, order, truncate=False): sage: a[eV,:] [-1/8*(u^2 + 2*u*v + v^2)*h^2 - 1/2*u + 1/2*v + 1, -1/8*(u^2 + 2*u*v + v^2)*h^2 + 1/2*u - 1/2*v + 1] - """ for rst in self._restrictions.values(): rst.set_calc_order(symbol, order, truncate) @@ -4609,7 +4540,7 @@ def apply_map(self, fun, frame=None, chart=None, with respect to ``chart`` of the components w.r.t. ``frame``; if ``None``, the operation ``fun`` is performed on all available coordinate expressions - - ``keep_other_components`` -- (default: ``False``) determine whether + - ``keep_other_components`` -- boolean (default: ``False``); determine whether the components with respect to vector frames distinct from ``frame`` and having the same domain as ``frame`` are kept. If ``fun`` is non-destructive, ``keep_other_components`` can be set to ``True``; @@ -4707,7 +4638,6 @@ def apply_map(self, fun, frame=None, chart=None, -2*x ∂/∂x sage: diff(w[[0]]).display() -2 dx - """ # The dictionary of components w.r.t. frame: if keep_other_components: diff --git a/src/sage/manifolds/differentiable/tensorfield_module.py b/src/sage/manifolds/differentiable/tensorfield_module.py index 42d921327e8..fcdd93a9f0f 100644 --- a/src/sage/manifolds/differentiable/tensorfield_module.py +++ b/src/sage/manifolds/differentiable/tensorfield_module.py @@ -60,7 +60,7 @@ class TensorFieldModule(UniqueRepresentation, ReflexiveModule_tensor): manifold `U` with values on a differentiable manifold `M`, via a differentiable map `U \rightarrow M`. - Given two non-negative integers `k` and `l` and a differentiable map + Given two nonnegative integers `k` and `l` and a differentiable map .. MATH:: @@ -234,7 +234,6 @@ class TensorFieldModule(UniqueRepresentation, ReflexiveModule_tensor): sage: T11.tensor_factors() [Module X(M) of vector fields on the 2-dimensional differentiable manifold M, Module Omega^1(M) of 1-forms on the 2-dimensional differentiable manifold M] - """ Element = TensorField @@ -266,7 +265,6 @@ def __init__(self, vector_field_module, tensor_type, category=None): In the above test suite, ``_test_elements`` is skipped because of the ``_test_pickling`` error of the elements (to be fixed in :class:`~sage.manifolds.differentiable.tensorfield.TensorField`) - """ domain = vector_field_module._domain dest_map = vector_field_module._dest_map @@ -318,7 +316,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, + (-y + 3) ∂/∂y⊗∂/∂y sage: T20(0) is T20.zero() True - """ try: if comp.is_trivial_zero(): @@ -411,7 +408,6 @@ def _an_element_(self): sage: T31._an_element_() Tensor field of type (3,1) on the 2-dimensional differentiable manifold M - """ resu = self.element_class(self._vmodule, self._tensor_type) for oc in self._domain.open_covers(trivial=False): @@ -445,7 +441,6 @@ def _coerce_map_from_(self, other): sage: T11 = M.tensor_field_module((1,1)) sage: T11._coerce_map_from_(M.automorphism_field_group()) True - """ from sage.manifolds.differentiable.diff_form_module import \ DiffFormModule @@ -489,7 +484,6 @@ def _repr_(self): sage: T13 # indirect doctest Module T^(1,3)(M) of type-(1,3) tensors fields on the 2-dimensional differentiable manifold M - """ description = "Module " if self._name is not None: @@ -516,7 +510,6 @@ def _latex_(self): '\\mathcal{T}^{(1,3)}\\left(M\\right)' sage: latex(T13) # indirect doctest \mathcal{T}^{(1,3)}\left(M\right) - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -545,7 +538,6 @@ def base_module(self): sage: T13.base_module().base_ring() Algebra of differentiable scalar fields on the 2-dimensional differentiable manifold M - """ return self._vmodule @@ -553,10 +545,8 @@ def tensor_type(self): r""" Return the tensor type of ``self``. - OUTPUT: - - - pair `(k,l)` of non-negative integers such that the tensor fields - belonging to this module are of type `(k,l)` + OUTPUT: pair `(k,l)` of nonnegative integers such that the tensor + fields belonging to this module are of type `(k,l)` EXAMPLES:: @@ -567,7 +557,6 @@ def tensor_type(self): sage: T20 = M.tensor_field_module((2,0)) sage: T20.tensor_type() (2, 0) - """ return self._tensor_type @@ -604,7 +593,7 @@ class TensorFieldFreeModule(TensorFreeModule): differentiable manifold `U` with values on a parallelizable manifold `M`, via a differentiable map `U \rightarrow M`. - Given two non-negative integers `k` and `l` and a differentiable map + Given two nonnegative integers `k` and `l` and a differentiable map .. MATH:: @@ -739,7 +728,6 @@ class TensorFieldFreeModule(TensorFreeModule): [1 0 0] [0 1 0] [0 0 1] - """ Element = TensorFieldParal @@ -760,7 +748,6 @@ def __init__(self, vector_field_module, tensor_type): sage: T12 is M.tensor_field_module((1,2)) True sage: TestSuite(T12).run() - """ domain = vector_field_module._domain dest_map = vector_field_module._dest_map @@ -808,7 +795,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, + 3 ∂/∂y⊗dy⊗dy sage: T12(0) is T12.zero() True - """ try: if comp.is_trivial_zero(): @@ -913,7 +899,6 @@ def _coerce_map_from_(self, other): sage: T11 = M.tensor_field_module((1,1)) sage: T11._coerce_map_from_(M.automorphism_field_group()) True - """ from sage.manifolds.differentiable.diff_form_module import \ DiffFormFreeModule @@ -958,7 +943,6 @@ def _repr_(self): sage: T12 # indirect doctest Free module T^(1,2)(M) of type-(1,2) tensors fields on the 2-dimensional differentiable manifold M - """ description = "Free module " if self._name is not None: diff --git a/src/sage/manifolds/differentiable/tensorfield_paral.py b/src/sage/manifolds/differentiable/tensorfield_paral.py index 188f9970e24..2c34656d757 100644 --- a/src/sage/manifolds/differentiable/tensorfield_paral.py +++ b/src/sage/manifolds/differentiable/tensorfield_paral.py @@ -328,7 +328,7 @@ class TensorFieldParal(FreeModuleTensor, TensorField): An instance of this class is a tensor field along a differentiable manifold `U` with values on a parallelizable manifold `M`, via a differentiable map `\Phi: U \rightarrow M`. More precisely, given two - non-negative integers `k` and `l` and a differentiable map + nonnegative integers `k` and `l` and a differentiable map .. MATH:: @@ -612,7 +612,6 @@ class TensorFieldParal(FreeModuleTensor, TensorField): sage: h[0,0], h[0,1], h[2,0] = 1+t, t^2, sin(t) sage: h.display() h = (t + 1) ∂/∂x⊗∂/∂x + t^2 ∂/∂x⊗∂/∂y + sin(t) ∂/∂z⊗∂/∂x - """ def __init__(self, vector_field_module, tensor_type, name=None, latex_name=None, sym=None, antisym=None): @@ -638,7 +637,6 @@ def __init__(self, vector_field_module, tensor_type, name=None, Free module T^(0,2)(M) of type-(0,2) tensors fields on the 2-dimensional differentiable manifold M sage: TestSuite(t).run() - """ FreeModuleTensor.__init__(self, vector_field_module, tensor_type, name=name, latex_name=latex_name, @@ -672,7 +670,6 @@ def _repr_(self): sage: t # indirect doctest Tensor field t of type (1,1) on the 2-dimensional differentiable manifold M - """ return TensorField._repr_(self) @@ -691,7 +688,6 @@ def _new_instance(self): manifold M sage: type(t._new_instance()) is type(t) True - """ return type(self)(self._fmodule, self._tensor_type, sym=self._sym, antisym=self._antisym) @@ -706,7 +702,6 @@ def _init_derived(self): sage: X. = M.chart() # makes M parallelizable sage: t = M.tensor_field(1,1, name='t') sage: t._init_derived() - """ FreeModuleTensor._init_derived(self) TensorField._init_derived(self) @@ -721,7 +716,7 @@ def _del_derived(self, del_restrictions: bool = True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the restrictions of ``self`` to subdomains are deleted TESTS:: @@ -730,7 +725,6 @@ def _del_derived(self, del_restrictions: bool = True): sage: X. = M.chart() # makes M parallelizable sage: t = M.tensor_field(1,1, name='t') sage: t._del_derived() - """ FreeModuleTensor._del_derived(self) TensorField._del_derived(self) @@ -754,7 +748,6 @@ def _preparse_display(self, basis=None, format_spec=None): (Coordinate frame (M, (∂/∂x,∂/∂y)), Chart (M, (x, y))) sage: t._preparse_display(X) # passing a chart instead of a frame (Coordinate frame (M, (∂/∂x,∂/∂y)), Chart (M, (x, y))) - """ if basis is None: basis = self._fmodule._def_basis @@ -833,7 +826,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such ... ValueError: no basis could be found for computing the components in the Vector frame (M, (e_0,e_1)) - """ if basis is None: basis = self._fmodule._def_basis @@ -922,7 +914,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such ... ValueError: no basis could be found for computing the components in the Vector frame (M, (e_0,e_1)) - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1013,7 +1004,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such t = 2 ∂/∂y⊗dx sage: t.display(e) t = x e_0⊗e^1 - """ if basis is None: basis = self._fmodule._def_basis @@ -1100,7 +1090,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such t = 2 ∂/∂y⊗dx sage: t.display(e) t = x e_0⊗e^1 - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1169,7 +1158,6 @@ class :class:`~sage.tensor.modules.comp.Components` 3-indices components w.r.t. Vector frame (M, (e_1,e_2)) sage: t.comp(e)[:] [[[0, 0], [0, 0]], [[x - 3, 0], [0, 0]]] - """ if basis is None: basis = self._fmodule._def_basis @@ -1241,7 +1229,6 @@ def _common_coord_frame(self, other): sage: c.display(a._common_coord_frame(c)) c = (1/2*x^2 - 1/2*y^2 + 1/2*x + 1/2*y + 1/2) ∂/∂x + (-1/2*x^2 + 1/2*y^2 + 1/2*x + 1/2*y + 1/2) ∂/∂y - """ from sage.manifolds.differentiable.vectorframe import CoordFrame # Compatibility checks: @@ -1404,7 +1391,6 @@ def lie_derivative(self, vector): sage: om.lie_der(v) == (v.contract(0, om.exterior_derivative(), 0) ....: + om(v).exterior_derivative()) True - """ if vector._tensor_type != (1,0): raise TypeError("the argument must be a vector field") @@ -1537,9 +1523,7 @@ def restrict(self, subdomain: DifferentiableManifold, dest_map: Optional[DiffMap being the differentiable map `S \rightarrow M` associated with the tensor field - OUTPUT: - - - instance of :class:`TensorFieldParal` representing the restriction + OUTPUT: instance of :class:`TensorFieldParal` representing the restriction EXAMPLES: @@ -1579,7 +1563,6 @@ def restrict(self, subdomain: DifferentiableManifold, dest_map: Optional[DiffMap sage: v.restrict(M) is v True - """ if (subdomain == self._domain and (dest_map is None or dest_map == self._vmodule._dest_map)): @@ -1719,7 +1702,6 @@ def __call__(self, *args): True sage: s == t(v) # indirect doctest True - """ from sage.categories.homset import End p = len(args) @@ -1818,7 +1800,6 @@ def contract(self, *args: Union[int, TensorField]) -> TensorFieldParal: :meth:`sage.manifolds.differentiable.tensorfield.TensorField.contract` for more examples. - """ # This is to ensure the call to the TensorField version instead of # the FreeModuleTensor one @@ -1871,7 +1852,6 @@ def __mul__(self, other): + (x*y + y^2) dy⊗dx + (-x^3 - x^2*y) dy⊗dy sage: s == f*a True - """ # This is to ensure the call to the TensorField version instead of # the FreeModuleTensor one @@ -1899,12 +1879,12 @@ def display_comp(self, frame=None, chart=None, coordinate_labels=True, - ``chart`` -- (default: ``None``) chart specifying the coordinate expression of the components; if ``None``, the default chart of the tensor field domain is used - - ``coordinate_labels`` -- (default: ``True``) boolean; if ``True``, + - ``coordinate_labels`` -- boolean (default: ``True``); if ``True``, coordinate symbols are used by default (instead of integers) as index labels whenever ``frame`` is a coordinate frame - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero components are displayed - - ``only_nonredundant`` -- (default: ``False``) boolean; if ``True``, + - ``only_nonredundant`` -- boolean (default: ``False``); if ``True``, only nonredundant components are displayed in case of symmetries EXAMPLES: @@ -1994,7 +1974,6 @@ def display_comp(self, frame=None, chart=None, coordinate_labels=True, t^01_0 = (u^2 - v^2)/(u^2 + 2*u*v + v^2 + 8) t^10_0 = (u^2 - v^2)/(u^2 + 2*u*v + v^2 + 8) t^11_1 = -12/(u^2 + 2*u*v + v^2 + 8) - """ from sage.misc.latex import latex from sage.manifolds.differentiable.vectorframe import CoordFrame @@ -2131,7 +2110,6 @@ def at(self, point): True sage: vp.display() v = (1/6*pi + 1) ∂/∂x + 1/36*pi^2 ∂/∂y - """ if point not in self._domain: raise ValueError("the {} is not in the domain of ".format(point) + @@ -2169,9 +2147,7 @@ def along(self, mapping): - ``mapping`` -- differentiable map `\Phi: U \rightarrow M` - OUTPUT: - - - tensor field `\tilde t` along `U` defined above. + OUTPUT: tensor field `\tilde t` along `U` defined above EXAMPLES: @@ -2225,7 +2201,6 @@ def along(self, mapping): differentiable manifold M sage: aU.at(p) == a.at(Phi(p)) True - """ dom = self._domain if self._ambient_domain is not dom: @@ -2328,7 +2303,6 @@ def series_expansion(self, symbol: Expression, order: int) -> list[TensorFieldPa [0 1 0 0] sage: all([g_ser[1] == h1, g_ser[2] == h2]) True - """ from sage.tensor.modules.comp import Components orderp1 = order + 1 @@ -2406,7 +2380,6 @@ def truncate(self, symbol, order): [ e 1 e 0] [ 0 e 1 e] [ 0 0 e 1] - """ series = self.series_expansion(symbol, order) return sum(symbol**i * s for i, s in enumerate(series)) @@ -2438,7 +2411,7 @@ def set_calc_order(self, symbol: Expression, order: int, truncate: bool = False) - ``order`` -- integer; the order `n` of the expansion, defined as the degree of the polynomial representing the truncated power series in ``symbol`` - - ``truncate`` -- (default: ``False``) determines whether the + - ``truncate`` -- boolean (default: ``False``); determines whether the components of ``self`` are replaced by their expansions to the given order @@ -2466,7 +2439,6 @@ def set_calc_order(self, symbol: Expression, order: int, truncate: bool = False) [ e 1 e 0] [ 0 e 1 e] [ 0 0 e 1] - """ for frame in self._components: for ind in self._components[frame].non_redundant_index_generator(): diff --git a/src/sage/manifolds/differentiable/vector_bundle.py b/src/sage/manifolds/differentiable/vector_bundle.py index 3c12a81da42..4a2c5372419 100644 --- a/src/sage/manifolds/differentiable/vector_bundle.py +++ b/src/sage/manifolds/differentiable/vector_bundle.py @@ -85,7 +85,6 @@ class DifferentiableVectorBundle(TopologicalVectorBundle): sage: M.diff_degree() == E.diff_degree() True - """ def __init__(self, rank, name, base_space, field='real', latex_name=None, category=None, unique_tag=None): @@ -99,7 +98,6 @@ def __init__(self, rank, name, base_space, field='real', latex_name=None, sage: DifferentiableVectorBundle(2, 'E', M) Differentiable real vector bundle E -> M of rank 2 over the base space 2-dimensional differentiable manifold M - """ diff_degree = base_space._diff_degree if category is None: @@ -130,7 +128,6 @@ def _repr_(self): sage: E._repr_() 'Differentiable real vector bundle E -> M of rank 1 over the base space 2-dimensional differentiable manifold M' - """ desc = "Differentiable " return desc + TopologicalVectorBundle._repr_object_name(self) @@ -159,7 +156,6 @@ def bundle_connection(self, name, latex_name=None): Further examples can be found in :class:`~sage.manifolds.differentiable.bundle_connection.BundleConnection`. - """ from .bundle_connection import BundleConnection return BundleConnection(self, name, latex_name) @@ -188,7 +184,6 @@ def characteristic_cohomology_class_ring(self, base=QQ): sage: 1 + p1 Characteristic cohomology class (1 + p_1)(TM) of the Tangent bundle TM over the 4-dimensional differentiable manifold M - """ from .characteristic_cohomology_class import CharacteristicCohomologyClassRing @@ -271,7 +266,6 @@ def characteristic_cohomology_class(self, *args, **kwargs): More examples can be found in :class:`~sage.manifolds.differentiable.characteristic_class.CharacteristicClass`. - """ base_ring = kwargs.get('base_ring', QQ) R = self.characteristic_cohomology_class_ring(base_ring) @@ -299,7 +293,6 @@ def diff_degree(self): sage: E = M.vector_bundle(2, 'E') sage: E.diff_degree() 3 - """ return self._diff_degree @@ -322,7 +315,6 @@ def total_space(self): sage: E = M.vector_bundle(2, 'E') sage: E.total_space() 6-dimensional differentiable manifold E - """ if self._total_space is None: from sage.manifolds.manifold import Manifold @@ -431,7 +423,6 @@ class TensorBundle(DifferentiableVectorBundle): sage: R_tensor_module = R.tensor_field_module((1,0), dest_map=Phi) sage: R_tensor_module is PhiTM.section_module() True - """ def __init__(self, base_space, k, l, dest_map=None): r""" @@ -448,7 +439,6 @@ def __init__(self, base_space, k, l, dest_map=None): manifold M along the Differentiable map Phi from the 2-dimensional differentiable manifold M to the 2-dimensional differentiable manifold N - """ if dest_map is None: self._dest_map = base_space.identity_map() @@ -494,7 +484,6 @@ def _init_derived(self): sage: M = Manifold(2, 'M') sage: TM = M.tangent_bundle() sage: TM._init_derived() - """ self._def_frame = None @@ -520,7 +509,6 @@ def _repr_(self): sage: T12M._repr_() 'Tensor bundle T^(1,2)M over the 2-dimensional differentiable manifold M' - """ if self._tensor_type == (1, 0): desc = "Tangent bundle " @@ -571,7 +559,6 @@ def fiber(self, point): on the 3-dimensional differentiable manifold M sage: T11M.fiber(p) is M.tangent_space(p).tensor_module(1,1) True - """ amb_point = self._dest_map(point) return self._ambient_domain.tangent_space(amb_point).tensor_module(*self._tensor_type) @@ -597,7 +584,6 @@ def atlas(self): sage: TM = M.tangent_bundle() sage: TM.atlas() [Chart (M, (x, y)), Chart (M, (u, v))] - """ return self._base_space.atlas() @@ -639,7 +625,6 @@ def section_module(self, domain=None): 2-dimensional differentiable manifold M sage: TUM is U.tensor_field_module((1,0)) True - """ if domain is None: base_space = self.base_space() @@ -730,7 +715,6 @@ def section(self, *args, **kwargs): differentiable manifold M sage: w.display() -y ∂/∂x + x ∂/∂y - """ nargs = [self._tensor_type[0], self._tensor_type[1]] nargs.extend(args) @@ -767,7 +751,7 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame, :class:`~sage.tensor.modules.free_module_automorphism.FreeModuleAutomorphism` describing the automorphism `P` that relates the basis `(e_i)` to the basis `(f_i)` according to `f_i = P(e_i)` - - ``compute_inverse`` (default: ``True``) -- if set to ``True``, the inverse + - ``compute_inverse`` -- boolean (default: ``True``); if set to ``True``, the inverse automorphism is computed and the change from basis `(f_i)` to `(e_i)` is set to it in the internal dictionary ``self._frame_changes`` @@ -792,7 +776,6 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame, sage: TM.change_of_frame(e,f)[e,:] [1 2] [0 3] - """ if not frame1._domain.is_subset(self._ambient_domain): raise ValueError("the frames must be defined on a subset of " @@ -853,7 +836,6 @@ def change_of_frame(self, frame1, frame2): sage: TM.change_of_frame(c_uv.frame(), c_xy.frame()) == \ ....: M.change_of_frame(c_xy.frame(), c_uv.frame()).inverse() True - """ return self._base_space.change_of_frame(frame1=frame1, frame2=frame2) @@ -912,7 +894,6 @@ def changes_of_frame(self): True sage: TM.changes_of_frame()[(f,e)] == a^(-1) True - """ base_cof = self._base_space.changes_of_frame() # Filter out all frames with respect to dest_map: @@ -932,9 +913,7 @@ def frames(self): For further details on frames on ``self`` see :meth:`local_frame`. - OUTPUT: - - - list of local frames defined on ``self`` + OUTPUT: list of local frames defined on ``self`` EXAMPLES: @@ -983,7 +962,6 @@ def frames(self): sage: PhiT11.frames() [Vector frame (R, (∂/∂x,∂/∂y)) with values on the 2-dimensional differentiable manifold M] - """ if self._dest_map.is_identity(): return self._base_space.frames() @@ -1005,9 +983,7 @@ def coframes(self): For further details on frames on ``self`` see :meth:`local_frame`. - OUTPUT: - - - list of coframes defined on ``self`` + OUTPUT: list of coframes defined on ``self`` EXAMPLES: @@ -1034,7 +1010,6 @@ def coframes(self): Coframe (R^2, (e^0,e^1)), Coordinate coframe (U, (dx,dy)), Coframe (U, (e^0,e^1))] - """ if self._dest_map.is_identity(): return self._base_space.coframes() @@ -1062,7 +1037,7 @@ def trivialization(self, coordinates='', names=None, calc_method=None): INPUT: - - ``coordinates`` -- (default: ``''`` (empty string)) string + - ``coordinates`` -- (default: ``''`` (empty string)) string defining the coordinate symbols, ranges and possible periodicities, see below - ``names`` -- (default: ``None``) unused argument, except if @@ -1130,7 +1105,6 @@ def trivialization(self, coordinates='', names=None, calc_method=None): y sage: X[:] (x, y) - """ return self._ambient_domain.chart(coordinates=coordinates, names=names, calc_method=calc_method) @@ -1196,7 +1170,6 @@ def transitions(self): (Chart (M, (x, y)), Chart (M, (r, s))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (r, s))} - """ return self._ambient_domain.coord_changes() @@ -1239,7 +1212,6 @@ def transition(self, chart1, chart2): sage: TM = M.tangent_bundle() sage: TM.transition(c_xy, c_uv) # returns the coord. change above Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v)) - """ return self._ambient_domain.coord_change(chart1, chart2) @@ -1315,7 +1287,6 @@ def is_manifestly_trivial(self): differentiable manifold S^2 sage: PhiTU.is_manifestly_trivial() True - """ if self._dest_map.is_identity(): # The standard case: @@ -1437,7 +1408,6 @@ def local_frame(self, *args, **kwargs): For more options, in particular for the choice of symbols and indices, see :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame`. - """ domain = kwargs.pop('domain', None) if domain is None: @@ -1478,7 +1448,6 @@ def ambient_domain(self): sage: PhiT11 = R.tensor_bundle(1, 1, dest_map=Phi) sage: PhiT11.ambient_domain() 2-dimensional differentiable manifold M - """ return self._ambient_domain @@ -1508,7 +1477,6 @@ def destination_map(self): sage: PhiT11.destination_map() Differentiable map Phi from the 1-dimensional differentiable manifold R to the 2-dimensional differentiable manifold M - """ return self._dest_map @@ -1542,7 +1510,6 @@ def default_frame(self): sage: TM = M.tangent_bundle() sage: TM.default_frame() Coordinate frame (M, (∂/∂x,∂/∂y)) - """ def_bframe = self._base_space.default_frame() if self._def_frame is None and def_bframe is not None: @@ -1581,7 +1548,6 @@ def set_default_frame(self, frame): Vector frame (M, (e_0,e_1)) sage: M.default_frame() Vector frame (M, (e_0,e_1)) - """ from sage.manifolds.differentiable.vectorframe import VectorFrame if not isinstance(frame, VectorFrame): @@ -1642,7 +1608,6 @@ def set_orientation(self, orientation): sage: T12.set_orientation([e, f]) sage: T12.orientation() [Vector frame (U, (e_0,e_1)), Vector frame (V, (f_0,f_1))] - """ if self._dest_map.is_identity(): base_space = self._base_space @@ -1741,7 +1706,6 @@ def orientation(self): sage: T11.orientation() [Coordinate frame (U, (∂/∂t,∂/∂z)), Coordinate frame (V, (∂/∂u,∂/∂v))] - """ if self._dest_map.is_identity(): self._orientation = self._base_space.orientation() diff --git a/src/sage/manifolds/differentiable/vectorfield.py b/src/sage/manifolds/differentiable/vectorfield.py index fd71f2ee2e6..6b0b51582a3 100644 --- a/src/sage/manifolds/differentiable/vectorfield.py +++ b/src/sage/manifolds/differentiable/vectorfield.py @@ -195,7 +195,6 @@ class VectorField(MultivectorField): v(f): W → ℝ (x, y) ↦ 2*x^2 - 2*y^2 + 2*x + 2*y (t, u) ↦ 2*t*u + 2*t - """ def __init__(self, vector_field_module, name=None, latex_name=None): r""" @@ -229,7 +228,6 @@ def __init__(self, vector_field_module, name=None, latex_name=None): .. TODO:: Fix ``_test_pickling`` (in the superclass :class:`TensorField`). - """ MultivectorField.__init__(self, vector_field_module, 1, name=name, latex_name=latex_name) @@ -252,7 +250,6 @@ def _repr_(self): 'Vector field v on the 2-dimensional differentiable manifold M' sage: v # indirect doctest Vector field v on the 2-dimensional differentiable manifold M - """ description = "Vector field " if self._name is not None: @@ -271,7 +268,6 @@ def _new_instance(self): Vector field on the 2-dimensional differentiable manifold M sage: u.parent() is v.parent() True - """ return type(self)(self._vmodule) @@ -284,7 +280,6 @@ def _init_dependencies(self): sage: M = Manifold(2, 'M') sage: v = M.vector_field(name='v') sage: v._init_dependencies() - """ self._lie_der_along_self = {} @@ -297,10 +292,9 @@ def _del_dependencies(self): sage: M = Manifold(2, 'M') sage: v = M.vector_field(name='v') sage: v._del_dependencies() - """ if self._lie_der_along_self != {}: - for idtens, tens in self._lie_der_along_self.items(): + for tens in self._lie_der_along_self.values(): del tens._lie_derivatives[id(self)] self._lie_der_along_self.clear() @@ -337,7 +331,6 @@ def __call__(self, scalar): on V: (u, v) ↦ 2*(u^2 + v^2)/(u^4 + 2*u^2*v^2 + v^4 + 1) sage: s == f.differential()(a) True - """ if scalar._tensor_type == (0,1): # This is actually the action of the vector field on a 1-form, @@ -424,12 +417,12 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, values of the parameters that may appear in the coordinate expression of the vector field (see example below) - - ``label_axes`` -- (default: ``True``) boolean determining whether + - ``label_axes`` -- boolean (default: ``True``); determining whether the labels of the coordinate axes of ``chart`` shall be added to the graph; can be set to ``False`` if the graph is 3D and must be superposed with another graph - - ``color`` -- (default: 'blue') color of the arrows representing + - ``color`` -- (default: ``'blue'``) color of the arrows representing the vectors - ``max_range`` -- (default: 8) numerical value substituted to @@ -669,7 +662,6 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, color. To restore the original default options, it suffices to type:: sage: v.plot.reset() - """ from sage.rings.infinity import Infinity from sage.misc.functional import numerical_approx @@ -906,9 +898,7 @@ def bracket(self, other): - ``other`` -- a :class:`VectorField` - OUTPUT: - - - the :class:`VectorField` ``[self, other]`` + OUTPUT: the :class:`VectorField` ``[self, other]`` EXAMPLES:: @@ -930,7 +920,6 @@ def bracket(self, other): True sage: vw == w.lie_derivative(v) True - """ # Call of the Schouten-Nijenhuis bracket return MultivectorField.bracket(self, other) @@ -983,9 +972,7 @@ def curl(self, metric=None): :class:`~sage.manifolds.differentiable.pseudo_riemannian.PseudoRiemannianManifold`) and the latter is used to define the curl - OUTPUT: - - - instance of :class:`VectorField` representing the curl of ``self`` + OUTPUT: instance of :class:`VectorField` representing the curl of ``self`` EXAMPLES: @@ -1024,7 +1011,6 @@ def curl(self, metric=None): Vector field on the Euclidean space E^3 sage: s.display() 0 - """ if self._domain.dim() < 3: raise ValueError("the curl is not defined in dimension lower " + @@ -1140,7 +1126,6 @@ def dot_product(self, other, metric=None): sage: s.display() u.e_x: (0, 2*pi) → ℝ t ↦ cos(t) - """ default_metric = metric is None if default_metric: @@ -1238,7 +1223,6 @@ def norm(self, metric=None): sage: s.display() |C'|: (0, 2*pi) → ℝ t ↦ sqrt(4*cos(t)^4 - 3*cos(t)^2 + 1) - """ default_metric = metric is None if default_metric: @@ -1362,7 +1346,6 @@ def cross_product(self, other, metric=None): on the Euclidean space E^3 sage: w.display() C' x e_x = e_y - cos(t) e_z - """ if self._ambient_domain.dim() != 3: raise ValueError("the cross product is not defined in dimension " + @@ -1598,7 +1581,6 @@ class VectorFieldParal(FiniteRankFreeModuleElement, MultivectorFieldParal, w = ∂/∂y sage: w.at(p) == v.at(Phi(p)) True - """ def __init__(self, vector_field_module, name=None, latex_name=None): r""" @@ -1628,7 +1610,6 @@ def __init__(self, vector_field_module, name=None, latex_name=None): sage: u.parent() is v.parent() True sage: TestSuite(u).run() - """ FiniteRankFreeModuleElement.__init__(self, vector_field_module, name=name, latex_name=latex_name) @@ -1658,7 +1639,6 @@ def _repr_(self) : 'Vector field v on the 2-dimensional differentiable manifold M' sage: v # indirect doctest Vector field v on the 2-dimensional differentiable manifold M - """ return VectorField._repr_(self) @@ -1675,7 +1655,6 @@ def _new_instance(self): Vector field on the 2-dimensional differentiable manifold M sage: u.parent() is v.parent() True - """ return type(self)(self._fmodule) @@ -1685,7 +1664,7 @@ def _del_derived(self, del_restrictions=True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the restrictions of ``self`` to subdomains are deleted TESTS:: @@ -1694,7 +1673,6 @@ def _del_derived(self, del_restrictions=True): sage: X. = M.chart() # makes M parallelizable sage: v = M.vector_field(name='v') sage: v._del_derived() - """ MultivectorFieldParal._del_derived(self, del_restrictions=del_restrictions) @@ -1728,7 +1706,6 @@ def __call__(self, scalar): sage: v(f).display() M → ℝ (x, y) ↦ 2*x^2*y - y^3 - """ # This method enforces VectorField.__call__ # instead of FiniteRankFreeModuleElement.__call__, which would have diff --git a/src/sage/manifolds/differentiable/vectorfield_module.py b/src/sage/manifolds/differentiable/vectorfield_module.py index d5c3bc83e6a..43efcb19aa6 100644 --- a/src/sage/manifolds/differentiable/vectorfield_module.py +++ b/src/sage/manifolds/differentiable/vectorfield_module.py @@ -192,7 +192,6 @@ class VectorFieldModule(UniqueRepresentation, ReflexiveModule_base): The conversion map is actually the restriction of vector fields defined on `M` to `U`. - """ Element = VectorField @@ -223,7 +222,6 @@ def __init__(self, domain: DifferentiableManifold, dest_map: Optional[DiffMap] = In the above test suite, _test_elements is skipped because of the _test_pickling error of the elements (to be fixed in class TensorField) - """ self._domain = domain name = "X(" + domain._name @@ -266,7 +264,7 @@ def __init__(self, domain: DifferentiableManifold, dest_map: Optional[DiffMap] = def _element_constructor_(self, comp=[], frame=None, name=None, latex_name=None): r""" - Construct an element of the module + Construct an element of the module. TESTS:: @@ -281,7 +279,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, v = -x ∂/∂x + y ∂/∂y sage: XM(0) is XM.zero() True - """ try: if comp.is_trivial_zero(): @@ -318,7 +315,6 @@ def _an_element_(self): sage: XM = M.vector_field_module() sage: XM._an_element_() Vector field on the 2-dimensional differentiable manifold M - """ resu = self.element_class(self) for oc in self._domain.open_covers(trivial=False): @@ -332,7 +328,7 @@ def _an_element_(self): def _coerce_map_from_(self, other): r""" - Determine whether coercion to self exists from other parent. + Determine whether coercion to ``self`` exists from other parent. TESTS:: @@ -344,7 +340,6 @@ def _coerce_map_from_(self, other): False sage: XU._coerce_map_from_(XM) True - """ if isinstance(other, (VectorFieldModule, VectorFieldFreeModule)): return self._domain.is_subset(other._domain) and \ @@ -369,7 +364,6 @@ def _repr_(self): sage: XM # indirect doctest Module X(M) of vector fields on the 2-dimensional differentiable manifold M - """ description = "Module " if self._name is not None: @@ -394,7 +388,6 @@ def _latex_(self): '\\mathfrak{X}\\left(M\\right)' sage: latex(XM) # indirect doctest \mathfrak{X}\left(M\right) - """ if self._latex_name is None: return r"\text{" + str(self) + r"}" @@ -426,7 +419,6 @@ def domain(self) -> DifferentiableManifold: sage: XU = U.vector_field_module(dest_map=Phi) sage: XU.domain() 2-dimensional differentiable manifold U - """ return self._domain @@ -456,7 +448,6 @@ def ambient_domain(self) -> DifferentiableManifold: sage: XU = U.vector_field_module(dest_map=Phi) sage: XU.ambient_domain() 5-dimensional differentiable manifold M - """ return self._ambient_domain @@ -504,7 +495,6 @@ def destination_map(self): sage: XU.destination_map() Differentiable map Phi from the 2-dimensional differentiable manifold U to the 5-dimensional differentiable manifold M - """ return self._dest_map @@ -514,9 +504,9 @@ def tensor_module(self, k, l, *, sym=None, antisym=None): INPUT: - - ``k`` -- non-negative integer; the contravariant rank, + - ``k`` -- nonnegative integer; the contravariant rank, the tensor type being `(k,l)` - - ``l`` -- non-negative integer; the covariant rank, + - ``l`` -- nonnegative integer; the covariant rank, the tensor type being `(k,l)` OUTPUT: @@ -552,7 +542,6 @@ def tensor_module(self, k, l, *, sym=None, antisym=None): See :class:`~sage.manifolds.differentiable.tensorfield_module.TensorFieldModule` for more examples and documentation. - """ if sym or antisym: raise NotImplementedError @@ -577,7 +566,7 @@ def exterior_power(self, p): INPUT: - - ``p`` -- non-negative integer + - ``p`` -- nonnegative integer OUTPUT: @@ -610,7 +599,6 @@ def exterior_power(self, p): :class:`~sage.manifolds.differentiable.multivector_module.MultivectorModule` for more examples and documentation. - """ try: return self._exterior_powers[p] @@ -637,7 +625,7 @@ def dual_exterior_power(self, p): INPUT: - - ``p`` -- non-negative integer + - ``p`` -- nonnegative integer OUTPUT: @@ -668,7 +656,6 @@ def dual_exterior_power(self, p): :class:`~sage.manifolds.differentiable.diff_form_module.DiffFormModule` for more examples and documentation. - """ try: return self._dual_exterior_powers[p] @@ -693,7 +680,6 @@ def dual(self): sage: XM.dual() Module Omega^1(M) of 1-forms on the 2-dimensional differentiable manifold M - """ return self.dual_exterior_power(1) @@ -725,7 +711,6 @@ def general_linear_group(self): :class:`~sage.manifolds.differentiable.automorphismfield_group.AutomorphismFieldGroup` for more examples and documentation. - """ if self._general_linear_group is None: from sage.manifolds.differentiable.automorphismfield_group import \ @@ -783,7 +768,6 @@ def _tensor(self, tensor_type, name=None, latex_name=None, sym=None, :class:`~sage.manifolds.differentiable.tensorfield.TensorField` for more examples and documentation. - """ from sage.manifolds.differentiable.automorphismfield import \ AutomorphismField @@ -824,7 +808,8 @@ def _tensor(self, tensor_type, name=None, latex_name=None, sym=None, def tensor(self, *args, **kwds): r""" - Construct a tensor field on the domain of ``self`` or a tensor product of ``self`` with other modules. + Construct a tensor field on the domain of ``self`` or a tensor product + of ``self`` with other modules. If ``args`` consist of other parents, just delegate to :meth:`tensor_product`. @@ -942,7 +927,6 @@ def alternating_contravariant_tensor(self, degree, name=None, :class:`~sage.manifolds.differentiable.multivectorfield.MultivectorField` for more examples and documentation. - """ if degree == 0: return self._domain.scalar_field(name=name, latex_name=latex_name) @@ -996,7 +980,6 @@ def alternating_form(self, degree: int, name=None, latex_name=None) -> DiffForm: :class:`~sage.manifolds.differentiable.diff_form.DiffForm` for more examples and documentation. - """ if degree == 0: return self._domain.scalar_field(name=name, latex_name=latex_name) @@ -1036,7 +1019,6 @@ def linear_form(self, name=None, latex_name=None): :class:`~sage.manifolds.differentiable.diff_form.DiffForm` for more examples and documentation. - """ return self.dual_exterior_power(1).element_class(self, 1, name=name, latex_name=latex_name) @@ -1076,7 +1058,6 @@ def automorphism(self, name=None, latex_name=None): :class:`~sage.manifolds.differentiable.automorphismfield.AutomorphismField` for more examples and documentation. - """ return self.general_linear_group().element_class(self, name=name, latex_name=latex_name) @@ -1114,7 +1095,6 @@ def identity_map(self): sage: one = Id.copy('1'); one Field of tangent-space automorphisms 1 on the 2-dimensional differentiable manifold M - """ return self.general_linear_group().one() @@ -1131,7 +1111,6 @@ def zero(self): sage: XM.zero() Vector field zero on the 2-dimensional differentiable manifold M - """ zero = self.element_class(self, name='zero', latex_name='0') for frame in self._domain._frames: @@ -1153,8 +1132,8 @@ def metric(self, name: str, signature: Optional[int] = None, latex_name: Optiona INPUT: - - ``name`` -- (string) name given to the metric - - ``signature`` -- (integer; default: ``None``) signature `S` of the + - ``name`` -- string; name given to the metric + - ``signature`` -- integer (default: ``None``); signature `S` of the metric: `S = n_+ - n_-`, where `n_+` (resp. `n_-`) is the number of positive terms (resp. number of negative terms) in any diagonal writing of the metric components; if ``signature`` is not provided, @@ -1181,7 +1160,6 @@ def metric(self, name: str, signature: Optional[int] = None, latex_name: Optiona :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetric` for more documentation. - """ # signature: ndim = self._ambient_domain.dimension() @@ -1235,7 +1213,6 @@ def symplectic_form( sage: omega Symplectic form omega on the 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 - """ from sage.manifolds.differentiable.symplectic_form import SymplecticForm @@ -1261,7 +1238,6 @@ def poisson_tensor( sage: varpi = XM.poisson_tensor(name='varpi', latex_name=r'\varpi') sage: varpi 2-vector field varpi on the 2-sphere S^2 of radius 1 smoothly embedded in the Euclidean space E^3 - """ from sage.manifolds.differentiable.poisson_tensor import PoissonTensorField @@ -1516,7 +1492,6 @@ class VectorFieldFreeModule(FiniteRankFreeModule): The Sage test suite for modules is passed:: sage: TestSuite(XM).run() - """ Element = VectorFieldParal @@ -1538,7 +1513,6 @@ def __init__(self, domain, dest_map=None): sage: XM is M.vector_field_module() True sage: TestSuite(XM).run() - """ from sage.manifolds.differentiable.scalarfield import DiffScalarField self._domain = domain @@ -1619,7 +1593,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, v = -y ∂/∂x + x ∂/∂y sage: XM(0) is XM.zero() True - """ try: if comp.is_trivial_zero(): @@ -1660,7 +1633,6 @@ def _coerce_map_from_(self, other): False sage: XU._coerce_map_from_(XM) True - """ if isinstance(other, (VectorFieldModule, VectorFieldFreeModule)): return (self._domain.is_subset(other._domain) @@ -1688,7 +1660,6 @@ def _repr_(self): sage: XM # indirect doctest Free module X(M) of vector fields on the 2-dimensional differentiable manifold M - """ description = "Free module " if self._name is not None: @@ -1728,7 +1699,6 @@ def domain(self) -> DifferentiableManifold: sage: XU = U.vector_field_module(dest_map=Phi) sage: XU.domain() 2-dimensional differentiable manifold U - """ return self._domain @@ -1760,7 +1730,6 @@ def ambient_domain(self) -> DifferentiableManifold: sage: XU = U.vector_field_module(dest_map=Phi) sage: XU.ambient_domain() 3-dimensional differentiable manifold M - """ return self._ambient_domain @@ -1809,7 +1778,6 @@ def destination_map(self) -> DiffMap: sage: XU.destination_map() Differentiable map Phi from the 2-dimensional differentiable manifold U to the 3-dimensional differentiable manifold M - """ return self._dest_map @@ -1820,9 +1788,9 @@ def tensor_module(self, k, l, *, sym=None, antisym=None): INPUT: - - ``k`` -- non-negative integer; the contravariant rank, + - ``k`` -- nonnegative integer; the contravariant rank, the tensor type being `(k, l)` - - ``l`` -- non-negative integer; the covariant rank, + - ``l`` -- nonnegative integer; the covariant rank, the tensor type being `(k, l)` OUTPUT: @@ -1860,7 +1828,6 @@ def tensor_module(self, k, l, *, sym=None, antisym=None): :class:`~sage.manifolds.differentiable.tensorfield_module.TensorFieldFreeModule` for more examples and documentation. - """ if sym or antisym: raise NotImplementedError @@ -1890,7 +1857,7 @@ def exterior_power(self, p): INPUT: - - ``p`` -- non-negative integer + - ``p`` -- nonnegative integer OUTPUT: @@ -1924,7 +1891,6 @@ def exterior_power(self, p): :class:`~sage.manifolds.differentiable.multivector_module.MultivectorFreeModule` for more examples and documentation. - """ try: return self._exterior_powers[p] @@ -1952,7 +1918,7 @@ def dual_exterior_power(self, p): INPUT: - - ``p`` -- non-negative integer + - ``p`` -- nonnegative integer OUTPUT: @@ -1983,7 +1949,6 @@ def dual_exterior_power(self, p): :class:`~sage.manifolds.differentiable.diff_form_module.DiffFormFreeModule` for more examples and documentation. - """ try: return self._dual_exterior_powers[p] @@ -2030,7 +1995,6 @@ def general_linear_group(self): :class:`~sage.manifolds.differentiable.automorphismfield_group.AutomorphismFieldParalGroup` for more examples and documentation. - """ from sage.manifolds.differentiable.automorphismfield_group import \ AutomorphismFieldParalGroup @@ -2093,7 +2057,6 @@ def basis(self, symbol=None, latex_symbol=None, from_frame=None, See :class:`~sage.manifolds.differentiable.vectorframe.VectorFrame` for more examples and documentation. - """ from sage.manifolds.differentiable.vectorframe import VectorFrame if symbol is None: @@ -2173,7 +2136,6 @@ def _tensor(self, tensor_type, name=None, latex_name=None, sym=None, See :class:`~sage.manifolds.differentiable.tensorfield_paral.TensorFieldParal` for more examples and documentation. - """ from sage.manifolds.differentiable.automorphismfield import ( AutomorphismField, AutomorphismFieldParal) @@ -2264,7 +2226,6 @@ def tensor_from_comp(self, tensor_type, comp, name=None, manifold M sage: t.display() t = (x + 1) dx⊗dx - y dx⊗dy + x*y dy⊗dx + (-y^2 + 2) dy⊗dy - """ from sage.tensor.modules.comp import (CompWithSym, CompFullyAntiSym) @@ -2342,7 +2303,6 @@ def sym_bilinear_form(self, name=None, latex_name=None): :class:`~sage.manifolds.differentiable.tensorfield_paral.TensorFieldParal` for more examples and documentation. - """ return self.tensor((0,2), name=name, latex_name=latex_name, sym=(0,1)) @@ -2360,8 +2320,8 @@ def metric(self, name, signature=None, latex_name=None): INPUT: - - ``name`` -- (string) name given to the metric - - ``signature`` -- (integer; default: ``None``) signature `S` of the + - ``name`` -- string; name given to the metric + - ``signature`` -- integer (default: ``None``); signature `S` of the metric: `S = n_+ - n_-`, where `n_+` (resp. `n_-`) is the number of positive terms (resp. number of negative terms) in any diagonal writing of the metric components; if ``signature`` is not provided, @@ -2389,7 +2349,6 @@ def metric(self, name, signature=None, latex_name=None): :class:`~sage.manifolds.differentiable.metric.PseudoRiemannianMetricParal` for more documentation. - """ ndim = self._ambient_domain.dimension() try: diff --git a/src/sage/manifolds/differentiable/vectorframe.py b/src/sage/manifolds/differentiable/vectorframe.py index 63c293a3e56..a284c6487b6 100644 --- a/src/sage/manifolds/differentiable/vectorframe.py +++ b/src/sage/manifolds/differentiable/vectorframe.py @@ -296,7 +296,6 @@ class CoFrame(FreeModuleCoBasis): (0, 1, 0) sage: e[3](v[1]).expr(), e[3](v[2]).expr(), e[3](v[3]).expr() (0, 0, 1) - """ def __init__(self, frame, symbol, latex_symbol=None, indices=None, latex_indices=None): @@ -311,7 +310,6 @@ def __init__(self, frame, symbol, latex_symbol=None, indices=None, sage: f = CoFrame(e, 'f'); f Coframe (M, (f^0,f^1)) sage: TestSuite(f).run() - """ self._domain = frame._domain self._manifold = self._domain.manifold() @@ -346,7 +344,6 @@ def _repr_(self): sage: h = M.vector_frame('h', dest_map=phi) sage: h.coframe()._repr_() 'Coframe (M, (h^1,h^2,h^3)) with values on the 3-dimensional differentiable manifold N' - """ description = "Coframe " + self._name dest_map = self._basis.destination_map() @@ -394,7 +391,6 @@ def at(self, point): differentiable manifold M sage: fp is X.frame().at(p).dual_basis() True - """ return self._basis.at(point).dual_basis() @@ -424,7 +420,7 @@ def set_name(self, symbol, latex_symbol=None, indices=None, - ``index_position`` -- (default: ``'up'``) determines the position of the indices labelling the 1-forms of the coframe; can be either ``'down'`` or ``'up'`` - - ``include_domain`` -- (default: ``True``) boolean determining whether + - ``include_domain`` -- boolean (default: ``True``); determining whether the name of the domain is included in the beginning of the coframe name @@ -449,7 +445,6 @@ def set_name(self, symbol, latex_symbol=None, indices=None, Coframe (M, (e^x,e^y)) sage: latex(e) \left(M, \left(e^{\xi},e^{\zeta}\right)\right) - """ super().set_name(symbol, latex_symbol=latex_symbol, indices=indices, @@ -631,7 +626,6 @@ class VectorFrame(FreeModuleBasis): True sage: f in U.vector_field_module(dest_map=Phi).bases() True - """ # The following class attribute must be redefined by any derived class: @@ -657,7 +651,6 @@ def __classcall_private__(cls, vector_field_module, symbol, Coframe (M, (A,B)) sage: e is VectorFrame(XM, ('a', 'b'), symbol_dual=('A', 'B')) True - """ if isinstance(symbol, list): symbol = tuple(symbol) @@ -692,7 +685,6 @@ def __init__(self, vector_field_module, symbol, latex_symbol=None, sage: e = VectorFrame(XM, 'e', latex_symbol=r'\epsilon'); e Vector frame (M, (e_0,e_1)) sage: TestSuite(e).run() - """ from sage.manifolds.differentiable.manifold import DifferentiableManifold # Some sanity check: @@ -788,7 +780,6 @@ def _repr_(self): sage: h = M.vector_frame('h', dest_map=phi) sage: h._repr_() 'Vector frame (M, (h_1,h_2,h_3)) with values on the 3-dimensional differentiable manifold N' - """ description = "Vector frame " + self._name if self._dest_map is not self._domain.identity_map(): @@ -831,9 +822,7 @@ def _new_instance(self, symbol, latex_symbol=None, indices=None, - ``latex_symbol_dual`` -- (default: ``None``) same as ``latex_symbol`` but for the dual coframe - OUTPUT: - - - instance of :class:`VectorFrame` + OUTPUT: instance of :class:`VectorFrame` TESTS:: @@ -841,7 +830,6 @@ def _new_instance(self, symbol, latex_symbol=None, indices=None, sage: e = M.vector_frame('e') sage: e._new_instance('f') Vector frame (M, (f_0,f_1)) - """ return VectorFrame(self._fmodule, symbol, latex_symbol=latex_symbol, indices=indices, latex_indices=latex_indices, @@ -869,7 +857,6 @@ def domain(self): sage: f = e.restrict(U) sage: f.domain() Open subset U of the 2-dimensional differentiable manifold M - """ return self._domain @@ -913,7 +900,6 @@ def ambient_domain(self): 2-dimensional differentiable manifold M sage: f.domain() 1-dimensional differentiable manifold U - """ return self._ambient_domain @@ -952,7 +938,6 @@ def destination_map(self): sage: f.destination_map() Differentiable map Phi from the 1-dimensional differentiable manifold U to the 2-dimensional differentiable manifold M - """ return self._dest_map @@ -969,7 +954,6 @@ def coframe(self): sage: X. = M.chart() sage: X.frame().coframe() Coordinate coframe (M, (dx,dy)) - """ return self._coframe @@ -1060,7 +1044,6 @@ def new_frame(self, change_of_frame, symbol, latex_symbol=None, [1/2*sqrt(3), -1/2] sage: e[1].comp(n)[:] [1/2, 1/2*sqrt(3)] - """ the_new_frame = self.new_basis(change_of_frame, symbol, latex_symbol=latex_symbol, @@ -1085,9 +1068,7 @@ def restrict(self, subdomain): - ``subdomain`` -- open subset `V` of the current frame domain `U` - OUTPUT: - - - the restriction of the current frame to `V` as a :class:`VectorFrame` + OUTPUT: the restriction of the current frame to `V` as a :class:`VectorFrame` EXAMPLES: @@ -1117,7 +1098,6 @@ def restrict(self, subdomain): True sage: e_U[2] is e[2].restrict(U) True - """ if subdomain == self._domain: return self @@ -1239,7 +1219,6 @@ def structure_coeff(self): -1/r sage: c[3,2,3] # C^3_{23} -cos(th)/(r*sin(th)) - """ from sage.tensor.modules.comp import CompWithSym @@ -1278,9 +1257,7 @@ def along(self, mapping): - ``mapping`` -- differentiable map `\Phi: U \rightarrow V` - OUTPUT: - - - vector frame `\tilde e` along `U` defined above. + OUTPUT: vector frame `\tilde e` along `U` defined above EXAMPLES: @@ -1313,7 +1290,6 @@ def along(self, mapping): sage: te is e.along(Phi) True - """ dom = self._domain if mapping.codomain().is_subset(dom): @@ -1426,7 +1402,6 @@ def at(self, point): 2-dimensional differentiable manifold M sage: fp.dual_basis() is f.coframe().at(p) True - """ # Case of a non-trivial destination map if self._from_frame is not None: @@ -1539,7 +1514,7 @@ def set_name(self, symbol, latex_symbol=None, indices=None, - ``index_position`` -- (default: ``'down'``) determines the position of the indices labelling the vector fields of the frame; can be either ``'down'`` or ``'up'`` - - ``include_domain`` -- (default: ``True``) boolean determining whether + - ``include_domain`` -- boolean (default: ``True``); determining whether the name of the domain is included in the beginning of the vector frame name @@ -1566,7 +1541,6 @@ def set_name(self, symbol, latex_symbol=None, indices=None, ....: latex_indices=[r'\alpha', r'\beta']) sage: latex(e) \left(M, \left(E_{\alpha},E_{\beta}\right)\right) - """ super().set_name(symbol, latex_symbol=latex_symbol, indices=indices, @@ -1652,7 +1626,6 @@ class CoordCoFrame(CoFrame): 2-form ddx on the 3-dimensional differentiable manifold M sage: dX[1].exterior_derivative() == 0 True - """ def __init__(self, coord_frame, symbol, latex_symbol=None, indices=None, latex_indices=None): @@ -1667,7 +1640,6 @@ def __init__(self, coord_frame, symbol, latex_symbol=None, indices=None, sage: f = CoordCoFrame(X.frame(), 'omega'); f Coordinate coframe (M, (omega^0,omega^1)) sage: TestSuite(f).run() - """ if not isinstance(coord_frame, CoordFrame): raise TypeError("the first argument must be a coordinate frame") @@ -1690,7 +1662,6 @@ def _repr_(self): 'Coordinate coframe (M, (dx,dy))' sage: f # indirect doctest Coordinate coframe (M, (dx,dy)) - """ return "Coordinate coframe " + self._name @@ -1724,7 +1695,6 @@ class CoordFrame(VectorFrame): Vector field ∂/∂ph on the 2-dimensional differentiable manifold S^2 sage: latex(b) \left(S^2, \left(\frac{\partial}{\partial {\theta} },\frac{\partial}{\partial {\phi} }\right)\right) - """ # The following class attribute must be redefined by any derived class: @@ -1742,7 +1712,6 @@ def __init__(self, chart): sage: e = CoordFrame(X); e Coordinate frame (M, (∂/∂x,∂/∂y)) sage: TestSuite(e).run() - """ from sage.misc.latex import latex from sage.typeset.unicode_characters import unicode_partial @@ -1793,7 +1762,6 @@ def _repr_(self): 'Coordinate frame (M, (∂/∂x,∂/∂y))' sage: e # indirect doctest Coordinate frame (M, (∂/∂x,∂/∂y)) - """ return "Coordinate frame " + self._name @@ -1813,7 +1781,6 @@ def chart(self): sage: U = M.open_subset('U', coord_def={X: x>0}) sage: e.restrict(U).chart() Chart (U, (x, y)) - """ return self._chart @@ -1854,7 +1821,6 @@ def structure_coeff(self): positions (1, 2) sage: c == 0 True - """ from sage.tensor.modules.comp import CompWithSym # A zero CompWithSym diff --git a/src/sage/manifolds/family.py b/src/sage/manifolds/family.py index 1b150b46d89..f9c3404535e 100644 --- a/src/sage/manifolds/family.py +++ b/src/sage/manifolds/family.py @@ -63,7 +63,6 @@ class ManifoldObjectFiniteFamily(FiniteFamily): Traceback (most recent call last): ... TypeError: all objects must have the same manifold - """ def __init__(self, objects=(), keys=None): r""" @@ -89,7 +88,6 @@ def __init__(self, objects=(), keys=None): sage: ManifoldSubsetFiniteFamily(gen) Set {I, M} of subsets of the 2-dimensional topological manifold M - """ if isinstance(objects, dict): dictionary = objects @@ -124,7 +122,6 @@ def _repr_object_type(self): sage: B = M.subset('B') sage: ManifoldObjectFiniteFamily([A, B]).__repr__() # indirect doctest 'Set {A, B} of objects of the 2-dimensional topological manifold M' - """ return "objects" @@ -163,7 +160,6 @@ def __repr__(self): sage: B = M.subset('B') sage: ManifoldObjectFiniteFamily([A, B]).__repr__() 'Set {A, B} of objects of the 2-dimensional topological manifold M' - """ if self: return "Set {} of {} of the {}".format(self._name, self._repr_object_type(), self._manifold) @@ -216,7 +212,6 @@ class ManifoldSubsetFiniteFamily(ManifoldObjectFiniteFamily): Traceback (most recent call last): ... TypeError: all open subsets must have the same manifold - """ @classmethod @@ -257,7 +252,6 @@ def _repr_object_type(self): sage: B = M.subset('B') sage: ManifoldSubsetFiniteFamily([A, B]).__repr__() # indirect doctest 'Set {A, B} of subsets of the 2-dimensional topological manifold M' - """ if all(subset.is_open() for subset in self): return "open subsets" diff --git a/src/sage/manifolds/local_frame.py b/src/sage/manifolds/local_frame.py index 21b506d3eb9..99fcbe4acff 100644 --- a/src/sage/manifolds/local_frame.py +++ b/src/sage/manifolds/local_frame.py @@ -252,7 +252,6 @@ class LocalCoFrame(FreeModuleCoBasis): (0, 1, 0) sage: f[3](e[1]).expr(), f[3](e[2]).expr(), f[3](e[3]).expr() (0, 0, 1) - """ def __init__(self, frame, symbol, latex_symbol=None, indices=None, latex_indices=None): @@ -268,7 +267,6 @@ def __init__(self, frame, symbol, latex_symbol=None, indices=None, sage: f = LocalCoFrame(e, 'f'); f Local coframe (E|_M, (f^0,f^1)) sage: TestSuite(f).run() - """ self._domain = frame.domain() self._base_space = frame.base_space() @@ -295,7 +293,6 @@ def _repr_(self): 'Local coframe (E|_M, (e^0,e^1))' sage: f # indirect doctest Local coframe (E|_M, (e^0,e^1)) - """ desc = "Local coframe " + self._name return desc @@ -340,7 +337,6 @@ def at(self, point): topological manifold M sage: e_dual_p is e.at(p).dual_basis() True - """ return self._basis.at(point).dual_basis() @@ -370,7 +366,7 @@ def set_name(self, symbol, latex_symbol=None, indices=None, - ``index_position`` -- (default: ``'up'``) determines the position of the indices labelling the linear forms of the coframe; can be either ``'down'`` or ``'up'`` - - ``include_domain`` -- (default: ``True``) boolean determining whether + - ``include_domain`` -- boolean (default: ``True``); determining whether the name of the domain is included in the beginning of the coframe name @@ -396,7 +392,6 @@ def set_name(self, symbol, latex_symbol=None, indices=None, Local coframe (E|_M, (e^x,e^y)) sage: latex(e) \left(E|_{M}, \left(e^{\xi},e^{\zeta}\right)\right) - """ super().set_name(symbol, latex_symbol=latex_symbol, indices=indices, @@ -556,7 +551,6 @@ class LocalFrame(FreeModuleBasis): sage: f.at(p) Basis (f_1,f_2) on the Fiber of F at Point p on the 2-dimensional topological manifold N - """ # The following class attribute must be redefined by any derived class: @@ -583,7 +577,6 @@ def __classcall_private__(cls, section_module, symbol, Local coframe (E|_M, (A,B)) sage: e is LocalFrame(C0, ('a', 'b'), symbol_dual=('A', 'B')) True - """ if isinstance(symbol, list): symbol = tuple(symbol) @@ -618,7 +611,6 @@ def __init__(self, section_module, symbol, latex_symbol=None, indices=None, sage: e = LocalFrame(C0, 'e', latex_symbol=r'\epsilon'); e Local frame (E|_M, (e_0,e_1)) sage: TestSuite(e).run() - """ ### # Some sanity check: @@ -679,7 +671,6 @@ def _repr_(self): 'Local frame (E|_M, (e_0,e_1))' sage: e # indirect doctest Local frame (E|_M, (e_0,e_1)) - """ desc = "Local frame " + self._name return desc @@ -716,9 +707,7 @@ def _new_instance(self, symbol, latex_symbol=None, indices=None, - ``latex_symbol_dual`` -- (default: ``None``) same as ``latex_symbol`` but for the dual coframe - OUTPUT: - - - instance of :class:`LocalFrame` + OUTPUT: instance of :class:`LocalFrame` TESTS:: @@ -727,7 +716,6 @@ def _new_instance(self, symbol, latex_symbol=None, indices=None, sage: e = E.local_frame('e') sage: e._new_instance('f') Local frame (E|_M, (f_0,f_1)) - """ return LocalFrame(self._fmodule, symbol, latex_symbol=latex_symbol, indices=indices, latex_indices=latex_indices, @@ -749,7 +737,6 @@ def domain(self): Local frame (E|_U, (e_0,e_1)) sage: e.domain() Open subset U of the 3-dimensional topological manifold M - """ return self._domain @@ -765,7 +752,6 @@ def base_space(self): sage: e = E.local_frame('e', domain=U) sage: e.base_space() 3-dimensional topological manifold M - """ return self._base_space @@ -784,7 +770,6 @@ def vector_bundle(self): 3-dimensional topological manifold M sage: e.vector_bundle() is E True - """ return self._vbundle @@ -800,7 +785,6 @@ def coframe(self): Local frame (E|_M, (e_0,e_1)) sage: e.coframe() Local coframe (E|_M, (e^0,e^1)) - """ return self._coframe @@ -892,7 +876,6 @@ def new_frame(self, change_of_frame, symbol, latex_symbol=None, [1/2*sqrt(3), -1/2] sage: e[2].comp(f)[:] [1/2, 1/2*sqrt(3)] - """ the_new_frame = self.new_basis(change_of_frame, symbol, latex_symbol=latex_symbol, @@ -916,9 +899,7 @@ def restrict(self, subdomain): - ``subdomain`` -- open subset `V` of the current frame domain `U` - OUTPUT: - - - the restriction of the current frame to `V` as a :class:`LocalFrame` + OUTPUT: the restriction of the current frame to `V` as a :class:`LocalFrame` EXAMPLES: @@ -954,7 +935,6 @@ def restrict(self, subdomain): True sage: f_U[2] is f[2].restrict(U) True - """ if subdomain == self._domain: return self @@ -1111,7 +1091,6 @@ def at(self, point): 2-dimensional topological manifold M sage: fp.dual_basis() is f.coframe().at(p) True - """ # Determination of the vector bundle fiber: if point not in self._domain: @@ -1209,7 +1188,7 @@ def set_name(self, symbol, latex_symbol=None, indices=None, - ``index_position`` -- (default: ``'down'``) determines the position of the indices labelling the local sections of the frame; can be either ``'down'`` or ``'up'`` - - ``include_domain`` -- (default: ``True``) boolean determining whether + - ``include_domain`` -- boolean (default: ``True``); determining whether the name of the domain is included in the beginning of the vector frame name @@ -1237,7 +1216,6 @@ def set_name(self, symbol, latex_symbol=None, indices=None, ....: latex_indices=[r'\alpha', r'\beta']) sage: latex(e) \left(E|_{M}, \left(E_{\alpha},E_{\beta}\right)\right) - """ super().set_name(symbol, latex_symbol=latex_symbol, indices=indices, @@ -1341,7 +1319,6 @@ class `C^k` and rank `n` over the topological field `K` and over a (0, 1, 0) sage: f[3](e[1]).expr(), f[3](e[2]).expr(), f[3](e[3]).expr() (0, 0, 1) - """ def __init__(self, triv_frame, symbol, latex_symbol=None, indices=None, latex_indices=None): @@ -1357,7 +1334,6 @@ def __init__(self, triv_frame, symbol, latex_symbol=None, sage: f = TrivializationCoFrame(phi.frame(), 'omega'); f Trivialization coframe (E|_M, (omega^0,omega^1)) sage: TestSuite(f).run() - """ if not isinstance(triv_frame, TrivializationFrame): raise TypeError("the first argument must be a local trivialization " @@ -1383,7 +1359,6 @@ def _repr_(self): 'Trivialization coframe (E|_M, ((phi^*e^1),(phi^*e^2)))' sage: e # indirect doctest Trivialization coframe (E|_M, ((phi^*e^1),(phi^*e^2))) - """ return "Trivialization coframe " + self._name @@ -1419,7 +1394,6 @@ class TrivializationFrame(LocalFrame): Trivialization frame (E|_U, ((phi_U^*e_1),(phi_U^*e_2))) sage: latex(phi_U.frame()) \left(E|_{U}, \left(\left(phi_U^* e_{ 1 }\right),\left(phi_U^* e_{ 2 }\right)\right)\right) - """ # The following class attribute must be redefined by any derived class: @@ -1436,7 +1410,6 @@ def __init__(self, trivialization): sage: phi = E.trivialization('phi') sage: e = phi.frame() sage: TestSuite(e).run() - """ from sage.misc.latex import latex from .trivialization import Trivialization @@ -1492,7 +1465,6 @@ def _repr_(self): 'Trivialization frame (E|_M, ((phi^*e_1),(phi^*e_2)))' sage: e # indirect doctest Trivialization frame (E|_M, ((phi^*e_1),(phi^*e_2))) - """ return "Trivialization frame " + self._name @@ -1511,6 +1483,5 @@ def trivialization(self): Trivialization (phi_U, E|_U) sage: e.trivialization() is phi_U True - """ return self._trivialization diff --git a/src/sage/manifolds/manifold.py b/src/sage/manifolds/manifold.py index 616eab15786..c27cd0b6434 100644 --- a/src/sage/manifolds/manifold.py +++ b/src/sage/manifolds/manifold.py @@ -2,7 +2,7 @@ Topological Manifolds Given a topological field `K` (in most applications, `K = \RR` or -`K = \CC`) and a non-negative integer `n`, a *topological manifold of +`K = \CC`) and a nonnegative integer `n`, a *topological manifold of dimension* `n` *over K* is a topological space `M` such that - `M` is a Hausdorff space, @@ -365,7 +365,7 @@ class TopologicalManifold(ManifoldSubset): Topological manifold over a topological field `K`. Given a topological field `K` (in most applications, `K = \RR` or - `K = \CC`) and a non-negative integer `n`, a *topological manifold of + `K = \CC`) and a nonnegative integer `n`, a *topological manifold of dimension* `n` *over K* is a topological space `M` such that - `M` is a Hausdorff space, @@ -688,7 +688,6 @@ def _an_element_(self): True sage: p.coord() (-pi - 1, 2) - """ from sage.rings.infinity import Infinity if self._def_chart is None: @@ -781,7 +780,6 @@ def __contains__(self, point): False sage: p in V # indirect doctest False - """ # for efficiency, a quick test first: if point.parent() is self: @@ -811,7 +809,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -820,9 +818,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): - ``supersets`` -- (default: only ``self``) list of sets that the new open subset is a subset of - OUTPUT: - - - the open subset, as an instance of :class:`TopologicalManifold` + OUTPUT: the open subset, as an instance of :class:`TopologicalManifold` EXAMPLES: @@ -884,7 +880,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): True sage: M.point((1,2)) in U False - """ resu = TopologicalManifold(self._dim, name, self._field, self._structure, @@ -904,7 +899,7 @@ def _init_open_subset(self, resu, coord_def): INPUT: - ``resu`` -- an instance of :class:`TopologicalManifold` or - a subclass. + a subclass - ``coord_def`` -- (default: ``{}``) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -948,7 +943,7 @@ def get_chart(self, coordinates, domain=None): INPUT: - - ``coordinates`` -- single string composed of the coordinate symbols + - ``coordinates`` -- single string composed of the coordinate symbols separated by a space - ``domain`` -- (default: ``None``) string containing the name of the chart's domain, which must be a subset of the current manifold; if @@ -983,7 +978,6 @@ def get_chart(self, coordinates, domain=None): Chart (U, (r, ph)) sage: M.get_chart('r ph', domain='U') is Y True - """ if domain is None: dom = self @@ -1015,7 +1009,6 @@ def dimension(self): sage: dim(M) 2 - """ return self._dim @@ -1025,9 +1018,7 @@ def base_field(self): r""" Return the field on which the manifold is defined. - OUTPUT: - - - a topological field + OUTPUT: a topological field EXAMPLES:: @@ -1040,7 +1031,6 @@ def base_field(self): sage: M = Manifold(3, 'M', structure='topological', field=QQ) sage: M.base_field() Rational Field - """ return self._field @@ -1050,12 +1040,11 @@ def base_field_type(self): OUTPUT: - - a string describing the field, with three possible values: + A string describing the field, with three possible values: - - ``'real'`` for the real field `\RR` - - ``'complex'`` for the complex field `\CC` - - ``'neither_real_nor_complex'`` for a field different from `\RR` - and `\CC` + - ``'real'`` for the real field `\RR` + - ``'complex'`` for the complex field `\CC` + - ``'neither_real_nor_complex'`` for a field different from `\RR` and `\CC` EXAMPLES:: @@ -1068,7 +1057,6 @@ def base_field_type(self): sage: M = Manifold(3, 'M', structure='topological', field=QQ) sage: M.base_field_type() 'neither_real_nor_complex' - """ return self._field_type @@ -1093,7 +1081,6 @@ def start_index(self): sage: M = Manifold(3, 'M', structure='topological', start_index=1) sage: M.start_index() 1 - """ return self._sindex @@ -1109,9 +1096,7 @@ def irange(self, start=None, end=None): if ``None``, the value returned by :meth:`start_index()` plus `n - 1`, where `n` is the manifold dimension, is assumed - OUTPUT: - - - an iterable index, starting from `i_0` and ending at `i_0 + i_n` + OUTPUT: an iterable index, starting from `i_0` and ending at `i_0 + i_n` EXAMPLES: @@ -1143,7 +1128,6 @@ def irange(self, start=None, end=None): sage: next(M.irange()) == M.start_index() True - """ si = self._sindex if start is None: @@ -1248,7 +1232,6 @@ def atlas(self) -> list[Chart]: .. SEEALSO:: :meth:`top_charts` - """ return list(self._atlas) # Make a (shallow) copy @@ -1283,7 +1266,6 @@ def top_charts(self): :meth:`atlas` for the complete list of charts defined on the manifold. - """ return list(self._top_charts) # Make a (shallow) copy @@ -1315,7 +1297,6 @@ def default_chart(self): Chart (A, (t, z)) sage: A.default_chart() Chart (A, (t, z)) - """ return self._def_chart @@ -1339,7 +1320,6 @@ def set_default_chart(self, chart): sage: M.set_default_chart(c_uv) sage: M.default_chart() Chart (M, (u, v)) - """ from .chart import Chart if not isinstance(chart, Chart): @@ -1378,7 +1358,6 @@ def coord_change(self, chart1, chart2): Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v)) sage: M.coord_change(c_xy, c_uv) # returns the coord. change defined above Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v)) - """ if (chart1, chart2) not in self._coord_changes: raise TypeError("the change of coordinates from " + @@ -1391,9 +1370,7 @@ def coord_changes(self): Return the changes of coordinates (transition maps) defined on subsets of the manifold. - OUTPUT: - - - dictionary of changes of coordinates, with pairs of charts as keys + OUTPUT: dictionary of changes of coordinates, with pairs of charts as keys EXAMPLES: @@ -1431,7 +1408,6 @@ def coord_changes(self): Chart (M, (u, v))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (u, v)), (Chart (M, (x, y)), Chart (M, (r, s))): Change of coordinates from Chart (M, (x, y)) to Chart (M, (r, s))} - """ return self._coord_changes.copy() @@ -1455,7 +1431,6 @@ def is_manifestly_coordinate_domain(self): sage: Y. = M.chart() sage: M.is_manifestly_coordinate_domain() True - """ return bool(self._covering_charts) @@ -1483,7 +1458,7 @@ def chart( INPUT: - - ``coordinates`` -- (default: ``''`` (empty string)) string + - ``coordinates`` -- (default: ``''`` (empty string)) string defining the coordinate symbols, ranges and possible periodicities, see below - ``names`` -- (default: ``None``) unused argument, except if @@ -1497,7 +1472,7 @@ def chart( - ``'sympy'``: SymPy - ``None``: the current calculus method defined on the manifold is used (cf. :meth:`set_calculus_method`) - - ``coord_restrictions``: Additional restrictions on the coordinates. + - ``coord_restrictions`` -- additional restrictions on the coordinates. See below. The coordinates declared in the string ``coordinates`` are @@ -1632,7 +1607,6 @@ def chart( :class:`~sage.manifolds.chart.Chart` and :class:`~sage.manifolds.chart.RealChart` for more examples, especially regarding the coordinates ranges and restrictions. - """ if calc_method is None: calc_method = self._calculus_method @@ -1652,7 +1626,6 @@ def is_open(self): sage: M = Manifold(2, 'M', structure='topological') sage: M.is_open() True - """ return True @@ -1690,7 +1663,6 @@ def set_orientation(self, orientation): sage: M.set_orientation([c_xy, c_uv]) sage: M.orientation() [Chart (U, (x, y)), Chart (V, (u, v))] - """ chart_type = self._structure.chart if isinstance(orientation, chart_type): @@ -1778,7 +1750,6 @@ def orientation(self): sage: W = U.intersection(V, name='W') sage: W.orientation() [Chart (W, (x, y))] - """ if not self._orientation: # try to get an orientation from super domains: @@ -1840,7 +1811,6 @@ def has_orientation(self): sage: M.set_orientation([c_xy, c_uv]) sage: M.has_orientation() True - """ return bool(self.orientation()) @@ -1853,9 +1823,7 @@ def _get_min_covering(self, object_list): - list of objects having an `domain` method - OUTPUT: - - - set of objects + OUTPUT: set of objects TESTS:: @@ -1865,7 +1833,6 @@ def _get_min_covering(self, object_list): sage: c3. = M.chart() sage: M._get_min_covering([c1, c2, c3]) {Chart (M, (z,))} - """ min_obj_set = set() for obj in object_list: @@ -1891,7 +1858,7 @@ def vector_bundle(self, rank, name, field='real', latex_name=None): - ``name`` -- name given to the total space - ``field`` -- (default: ``'real'``) topological field giving the vector space structure to the fibers - - ``latex_name`` -- optional LaTeX name for the total space + - ``latex_name`` -- (optional) LaTeX name for the total space OUTPUT: @@ -1904,7 +1871,6 @@ def vector_bundle(self, rank, name, field='real', latex_name=None): sage: M.vector_bundle(2, 'E') Topological real vector bundle E -> M of rank 2 over the base space 2-dimensional topological manifold M - """ from sage.manifolds.vector_bundle import TopologicalVectorBundle return TopologicalVectorBundle(rank, name, self, field=field, @@ -1941,7 +1907,6 @@ def scalar_field_algebra(self): sage: U.scalar_field_algebra() is CU True - """ return self._scalar_field_algebra @@ -2032,7 +1997,6 @@ def scalar_field( :meth:`constant_scalar_field`, :meth:`zero_scalar_field`, :meth:`one_scalar_field` - """ if isinstance(coord_expression, dict): # check validity of entry @@ -2122,7 +2086,6 @@ def zero_scalar_field(self): Algebra of scalar fields on the 2-dimensional topological manifold M sage: f is M.scalar_field_algebra().zero() True - """ return self._zero_scalar_field @@ -2150,13 +2113,12 @@ def one_scalar_field(self): Algebra of scalar fields on the 2-dimensional topological manifold M sage: f is M.scalar_field_algebra().one() True - """ return self._one_scalar_field class options(GlobalOptions): r""" - Sets and displays the options for manifolds. If no parameters + Set and displays the options for manifolds. If no parameters are set, then the function returns a copy of the options dictionary. The ``options`` to manifolds can be accessed as the method @@ -2249,7 +2211,6 @@ def _Hom_(self, other, category=None): sage: H is Hom(M, N) True - """ return self._structure.homset(self, other) @@ -2345,7 +2306,6 @@ def continuous_map(self, codomain, coord_functions=None, chart1=None, Allow the construction of continuous maps from ``self`` to the base field (considered as a trivial 1-dimensional manifold). - """ if (not isinstance(codomain, TopologicalManifold) or codomain.base_field() != self.base_field()): @@ -2442,7 +2402,6 @@ def homeomorphism(self, codomain, coord_functions=None, chart1=None, See the documentation of :class:`~sage.manifolds.continuous_map.ContinuousMap` for more examples. - """ homset = Hom(self, codomain) if coord_functions is None: @@ -2516,7 +2475,6 @@ def identity_map(self): See :class:`~sage.manifolds.continuous_map.ContinuousMap` for the complete documentation. - """ return Hom(self, self).one() @@ -2593,7 +2551,6 @@ def set_calculus_method(self, method): :meth:`~sage.manifolds.chart.Chart.calculus_method` for a control of the calculus method chart by chart - """ self._calculus_method = method for chart in self._atlas: @@ -2713,7 +2670,6 @@ def set_simplify_function(self, simplifying_func, method=None): 1 sage: type(s.expr()) - """ for chart in self._atlas: chart.calculus_method().set_simplify_function(simplifying_func, @@ -2739,7 +2695,7 @@ def Manifold( Construct a manifold of a given type over a topological field. Given a topological field `K` (in most applications, `K = \RR` or - `K = \CC`) and a non-negative integer `n`, a *topological manifold of + `K = \CC`) and a nonnegative integer `n`, a *topological manifold of dimension* `n` *over K* is a topological space `M` such that - `M` is a Hausdorff space, @@ -2795,7 +2751,7 @@ def Manifold( - ``extra_kwds`` -- keywords meaningful only for some specific types of manifolds: - - ``diff_degree`` -- (only for differentiable manifolds; default: + - ``diff_degree`` -- (only for differentiable manifolds; default: ``infinity``): the degree of differentiability - ``ambient`` -- (only to construct a submanifold): the ambient manifold - ``metric_name`` -- (only for pseudo-Riemannian manifolds; default: diff --git a/src/sage/manifolds/manifold_homset.py b/src/sage/manifolds/manifold_homset.py index 664c8f422a7..78c9bc9984c 100644 --- a/src/sage/manifolds/manifold_homset.py +++ b/src/sage/manifolds/manifold_homset.py @@ -1,5 +1,5 @@ r""" -Sets of Morphisms between Topological Manifolds +Set of Morphisms between Topological Manifolds The class :class:`TopologicalManifoldHomset` implements sets of morphisms between two topological manifolds over the same topological @@ -134,7 +134,6 @@ class TopologicalManifoldHomset(UniqueRepresentation, Homset): This test suite includes more tests than in the case of ``H``, since ``E`` has some extra structure (monoid). - """ Element = ContinuousMap @@ -171,7 +170,6 @@ def __init__(self, domain, codomain, name=None, latex_name=None): sage: iota * phi Differentiable map iota from the 1-sphere S^1 of radius 1 smoothly embedded in the Euclidean plane E^2 to the Euclidean plane E^2 - """ from sage.manifolds.manifold import TopologicalManifold if not isinstance(domain, TopologicalManifold): @@ -220,7 +218,7 @@ def _element_constructor_(self, coord_functions, name=None, latex_name=None, INPUT: - - ``coord_functions`` -- a dictionary of the coordinate expressions + - ``coord_functions`` -- dictionary of the coordinate expressions (as lists or tuples of the coordinates of the image expressed in terms of the coordinates of the considered point) with the pairs of charts ``(chart1, chart2)`` as keys (``chart1`` being a chart @@ -230,10 +228,10 @@ def _element_constructor_(self, coord_functions, name=None, latex_name=None, - ``name`` -- (default: ``None``) name given to the continuous map - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the continuous map; if ``None``, the LaTeX symbol is set to ``name`` - - ``is_isomorphism`` -- (default: ``False``) determines whether the + - ``is_isomorphism`` -- boolean (default: ``False``); determines whether the constructed object is a isomorphism (i.e. a homeomorphism); if set to ``True``, then the manifolds `M` and `N` must have the same dimension - - ``is_identity`` -- (default: ``False``) determines whether the + - ``is_identity`` -- boolean (default: ``False``); determines whether the constructed object is the identity map; if set to ``True``, then `N` must be `M` and the entry ``coord_functions`` is not used @@ -244,9 +242,7 @@ def _element_constructor_(self, coord_functions, name=None, latex_name=None, continuous map, further coordinate expressions, in other charts, can be subsequently added by means of the method :meth:`add_expr` - OUTPUT: - - - a :class:`~sage.manifolds.continuous_map.ContinuousMap` + OUTPUT: a :class:`~sage.manifolds.continuous_map.ContinuousMap` EXAMPLES:: @@ -267,7 +263,6 @@ def _element_constructor_(self, coord_functions, name=None, latex_name=None, sage: id.display() Id_M: M → M (x, y) ↦ (x, y) - """ # Standard construction return self.element_class(self, coord_functions=coord_functions, @@ -279,9 +274,7 @@ def _an_element_(self): r""" Construct some element of ``self``. - OUTPUT: - - - a :class:`~sage.manifolds.continuous_map.ContinuousMap` + OUTPUT: a :class:`~sage.manifolds.continuous_map.ContinuousMap` EXAMPLES:: @@ -303,7 +296,6 @@ def _an_element_(self): sage: f(p).coord(Y) (0, 0, 0) sage: TestSuite(f).run() - """ dom = self.domain() codom = self.codomain() @@ -335,7 +327,6 @@ def _coerce_map_from_(self, other): False sage: H._coerce_map_from_(H) True - """ if isinstance(other, TopologicalManifoldHomset): return (other.domain().has_coerce_map_from(self.domain()) @@ -434,7 +425,6 @@ def one(self): to 3-dimensional topological manifold N in Category of manifolds over Real Field with 53 bits of precision is not a monoid - """ if self.codomain() != self.domain(): raise TypeError("{} is not a monoid".format(self)) diff --git a/src/sage/manifolds/operators.py b/src/sage/manifolds/operators.py index a437f4a08e0..636c11db149 100644 --- a/src/sage/manifolds/operators.py +++ b/src/sage/manifolds/operators.py @@ -91,7 +91,6 @@ def grad(scalar): :meth:`~sage.manifolds.differentiable.scalarfield.DiffScalarField.gradient` of :class:`~sage.manifolds.differentiable.scalarfield.DiffScalarField` for more details and examples. - """ return scalar.gradient() @@ -165,7 +164,6 @@ def div(tensor): :meth:`~sage.manifolds.differentiable.tensorfield.TensorField.divergence` of :class:`~sage.manifolds.differentiable.tensorfield.TensorField` for more details and examples. - """ return tensor.divergence() @@ -233,7 +231,6 @@ def curl(vector): :meth:`~sage.manifolds.differentiable.vectorfield.VectorField.curl` of :class:`~sage.manifolds.differentiable.vectorfield.VectorField` for more details and examples. - """ return vector.curl() @@ -294,7 +291,6 @@ def laplacian(field): :meth:`~sage.manifolds.differentiable.tensorfield.TensorField.laplacian` of :class:`~sage.manifolds.differentiable.tensorfield.TensorField` for more details and examples. - """ return field.laplacian() @@ -350,7 +346,6 @@ def dalembertian(field): :meth:`~sage.manifolds.differentiable.tensorfield.TensorField.dalembertian` of :class:`~sage.manifolds.differentiable.tensorfield.TensorField` for more details and examples. - """ return field.dalembertian() diff --git a/src/sage/manifolds/point.py b/src/sage/manifolds/point.py index a2bc5ff3182..3971a85c776 100644 --- a/src/sage/manifolds/point.py +++ b/src/sage/manifolds/point.py @@ -111,9 +111,9 @@ class ManifoldPoint(Element): - ``name`` -- (default: ``None``) name given to the point - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the point; if ``None``, the LaTeX symbol is set to ``name`` - - ``check_coords`` -- (default: ``True``) determines whether ``coords`` - are valid coordinates for the chart ``chart``; for symbolic - coordinates, it is recommended to set ``check_coords`` to ``False`` + - ``check_coords`` -- boolean (default: ``True``); determines whether ``coords`` + are valid coordinates for the chart ``chart``. For symbolic + coordinates, it is recommended to set ``check_coords`` to ``False``. EXAMPLES: @@ -179,7 +179,6 @@ def __init__(self, parent, coords=None, chart=None, name=None, sage: q = U((-1,2), name='q'); q Point q on the 2-dimensional topological manifold M sage: TestSuite(q).run() - """ if parent.is_empty(): raise TypeError(f'cannot define a point on the {parent} because it has been declared empty') @@ -231,7 +230,6 @@ def _repr_(self): 'Point p on the 2-dimensional topological manifold M' sage: repr(p) # indirect doctest 'Point p on the 2-dimensional topological manifold M' - """ description = "Point" if self._name is not None: @@ -258,7 +256,6 @@ def _latex_(self): '\\mathcal{P}' sage: latex(p) # indirect doctest \mathcal{P} - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -366,7 +363,6 @@ def coordinates(self, chart=None, old_chart=None): {Chart (M, (u, v)): (a - b, a + b), Chart (M, (w, z)): (a^3 - 3*a^2*b + 3*a*b^2 - b^3, a^3 + 3*a^2*b + 3*a*b^2 + b^3)} - """ if chart is None: dom = self.parent() @@ -436,7 +432,7 @@ def coordinates(self, chart=None, old_chart=None): def set_coordinates(self, coords, chart=None): r""" - Sets the point coordinates in the specified chart. + Set the point coordinates in the specified chart. Coordinates with respect to other charts are deleted, in order to avoid any inconsistency. To keep them, use the method :meth:`add_coord` @@ -484,7 +480,6 @@ def set_coordinates(self, coords, chart=None): sage: p.set_coord(Y(p), chart=Y) sage: p._coordinates {Chart (M, (u, v)): (-1, 5)} - """ self._coordinates.clear() self.add_coord(coords, chart) @@ -493,7 +488,7 @@ def set_coordinates(self, coords, chart=None): def add_coordinates(self, coords, chart=None): r""" - Adds some coordinates in the specified chart. + Add some coordinates in the specified chart. The previous coordinates with respect to other charts are kept. To clear them, use :meth:`set_coord` instead. @@ -551,7 +546,6 @@ def add_coordinates(self, coords, chart=None): sage: p.set_coordinates((-1,5), chart=Y) sage: p._coordinates {Chart (M, (u, v)): (-1, 5)} - """ if len(coords) != self.parent().manifold()._dim: raise ValueError("the number of coordinates must be equal to " + @@ -568,7 +562,7 @@ def add_coordinates(self, coords, chart=None): def __eq__(self, other): r""" - Compares the current point with another one. + Compare the current point with another one. EXAMPLES: @@ -627,7 +621,6 @@ def __eq__(self, other): sage: q = M((3*pi,1), chart=Y) sage: p == q or q == p False - """ if other is self: return True @@ -719,7 +712,6 @@ def __ne__(self, other): True sage: p != M((2,-3), chart=X) False - """ return not (self == other) @@ -746,7 +738,6 @@ def __hash__(self): sage: p = M((2,-3), chart=X) sage: hash(p) == hash(M) True - """ return hash(self.parent().manifold()) @@ -942,7 +933,6 @@ def plot(self, chart=None, ambient_coords=None, mapping=None, g = p.plot(X, ambient_coords=(y,z), label_offset=0.4) gX = X.plot(X, ambient_coords=(y,z)) sphinx_plot(g+gX) - """ from sage.plot.point import point2d from sage.plot.text import text diff --git a/src/sage/manifolds/scalarfield.py b/src/sage/manifolds/scalarfield.py index 6c1ea6e2f14..62c728ff5bb 100644 --- a/src/sage/manifolds/scalarfield.py +++ b/src/sage/manifolds/scalarfield.py @@ -1104,7 +1104,6 @@ class ScalarField(CommutativeAlgebraElement, ModuleElementWithMutability): sage: TestSuite(f).run() sage: TestSuite(zer).run() - """ _name: Optional[str] @@ -1127,7 +1126,6 @@ def __init__(self, parent, coord_expression=None, chart=None, name=None, Algebra of scalar fields on the 2-dimensional topological manifold M sage: TestSuite(f).run() - """ super().__init__(parent) # both super classes have same signature domain = parent._domain @@ -1259,7 +1257,6 @@ def is_trivial_zero(self): True sage: f == 0 True - """ if self._is_zero: return True @@ -1318,7 +1315,6 @@ def is_trivial_one(self): True sage: f == 1 True - """ return all(func.is_trivial_one() for func in self._express.values()) @@ -1338,7 +1334,6 @@ def is_unit(self): sage: zero = M.scalar_field_algebra().zero() sage: zero.is_unit() False - """ if self._is_zero: return False @@ -1353,9 +1348,7 @@ def __eq__(self, other): - ``other`` -- a scalar field (or something else) - OUTPUT: - - - ``True`` if ``self`` is equal to ``other``, ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other``, ``False`` otherwise TESTS:: @@ -1374,7 +1367,6 @@ def __eq__(self, other): True sage: h == 1 True - """ from sage.manifolds.differentiable.mixed_form import MixedForm @@ -1413,9 +1405,7 @@ def __ne__(self, other): - ``other`` -- a scalar field - OUTPUT: - - - ``True`` if ``self`` differs from ``other``, ``False`` otherwise + OUTPUT: ``True`` if ``self`` differs from ``other``, ``False`` otherwise TESTS:: @@ -1446,7 +1436,7 @@ def _init_derived(self): sage: f._init_derived() """ self._restrictions = {} - # dict. of restrictions of self on subsets + # dict. of restrictions of ``self`` on subsets # of self._domain, with the subsets as keys def _del_derived(self): @@ -1546,7 +1536,6 @@ def set_name(self, name=None, latex_name=None): Scalar field f on the 2-dimensional topological manifold M sage: latex(f) \Phi - """ if self.is_immutable(): raise ValueError("the name of an immutable element " @@ -1582,7 +1571,6 @@ def domain(self): sage: g = f.restrict(U) sage: g.domain() Open subset U of the 2-dimensional topological manifold M - """ return self._domain @@ -1597,7 +1585,6 @@ def codomain(self): sage: f = M.scalar_field(x+2*y) sage: f.codomain() Real Field with 53 bits of precision - """ return self._domain.base_field() @@ -1627,7 +1614,6 @@ def copy(self, name=None, latex_name=None): True sage: g is f False - """ result = type(self)(self.parent(), name=name, latex_name=latex_name) for chart, funct in self._express.items(): @@ -1678,7 +1664,6 @@ def copy_from(self, other): (x, y) ↦ x*y^2 sage: f == g False - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -1755,7 +1740,6 @@ def coord_function(self, chart=None, from_chart=None): Change of coordinates from Chart (M, (T, X)) to Chart (M, (t, x)) sage: f.coord_function(o2) -T^2 + X^2 - """ if chart is None: chart = self._domain._def_chart @@ -1858,7 +1842,6 @@ def expr(self, chart=None, from_chart=None): sage: f.expr() # note the SymPy exponent notation x*y**2 - """ return self.coord_function(chart, from_chart).expr() @@ -1911,7 +1894,6 @@ def set_expr(self, coord_expression, chart=None): ... ValueError: the expressions of an immutable element cannot be changed - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -1975,7 +1957,6 @@ def add_expr(self, coord_expression, chart=None): ... ValueError: the expressions of an immutable element cannot be changed - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -2045,7 +2026,6 @@ def add_expr_by_continuation(self, chart, subdomain): f: S^2 → ℝ on U: (x, y) ↦ arctan(x^2 + y^2) on V: (u, v) ↦ arctan(1/(u^2 + v^2)) - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -2083,7 +2063,6 @@ def set_restriction(self, rst): on U: (x, y) ↦ x^2 + y sage: f.restrict(U) == g True - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -2294,7 +2273,6 @@ def restrict(self, subdomain): topological manifold M sage: M.zero_scalar_field().restrict(U) is U.zero_scalar_field() True - """ if subdomain == self._domain: return self @@ -2426,7 +2404,6 @@ def common_charts(self, other): [Chart (W, (x, y))] sage: h.expr(c_xy_W) x + 2*y - """ if not isinstance(other, ScalarField): raise TypeError("the second argument must be a scalar field") @@ -2483,9 +2460,7 @@ def __call__(self, p, chart=None): are known is searched, starting from the default chart of ``self._domain`` - OUTPUT: - - - value at ``p`` + OUTPUT: value at ``p`` EXAMPLES:: @@ -2513,7 +2488,6 @@ def __call__(self, p, chart=None): -21 sage: p.coord(Y) (-3, 7) - """ # ! # it should be "if p not in self_domain:" instead, but this test is # skipped for efficiency @@ -2567,7 +2541,7 @@ def preimage(self, codomain_subset, name=None, latex_name=None): - ``codomain_subset`` -- an instance of :class:`~sage.sets.real_set.RealSet` - ``name`` -- string; name (symbol) given to the subset - - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to + - ``latex_name`` -- string (default: ``None``); LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` OUTPUT: @@ -2602,9 +2576,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of the scalar field + OUTPUT: an exact copy of the scalar field TESTS:: @@ -2615,7 +2587,6 @@ def __pos__(self): Scalar field +f on the 2-dimensional topological manifold M sage: g == f True - """ result = type(self)(self.parent()) for chart in self._express: @@ -2630,9 +2601,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the negative of the scalar field + OUTPUT: the negative of the scalar field TESTS:: @@ -2646,7 +2615,6 @@ def __neg__(self): (x, y) ↦ -x - y sage: g.__neg__() == f True - """ result = type(self)(self.parent()) for chart in self._express: @@ -2687,7 +2655,6 @@ def _add_(self, other): True sage: f._add_(M.zero_scalar_field()) == f True - """ # Trivial cases: if self.is_trivial_zero(): @@ -2736,7 +2703,6 @@ def _sub_(self, other): True sage: f._sub_(M.zero_scalar_field()) == f True - """ # Trivial cases: if self.is_trivial_zero(): @@ -2789,7 +2755,6 @@ def _mul_(self, other): True sage: f._mul_(M.one_scalar_field()) == f True - """ # Trivial cases: if self.is_trivial_zero() or other.is_trivial_zero(): @@ -2882,9 +2847,7 @@ def _lmul_(self, number): field on which the manifold is constructed (possibly represented by a symbolic expression) - OUTPUT: - - - the scalar field ``number * self`` + OUTPUT: the scalar field ``number * self`` TESTS:: @@ -2909,7 +2872,6 @@ def _lmul_(self, number): True sage: f._lmul_(1) == f True - """ # Trivial cases: try: @@ -3001,9 +2963,7 @@ def exp(self): r""" Exponential of the scalar field. - OUTPUT: - - - the scalar field `\exp f`, where `f` is the current scalar field + OUTPUT: the scalar field `\exp f`, where `f` is the current scalar field EXAMPLES:: @@ -3036,7 +2996,6 @@ def exp(self): True sage: exp(M.constant_scalar_field(1)) == M.constant_scalar_field(e) True - """ name, latex_name = self._function_name("exp", r"\exp") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3048,9 +3007,7 @@ def log(self): r""" Natural logarithm of the scalar field. - OUTPUT: - - - the scalar field `\ln f`, where `f` is the current scalar field + OUTPUT: the scalar field `\ln f`, where `f` is the current scalar field EXAMPLES:: @@ -3069,7 +3026,6 @@ def log(self): sage: exp(log(f)) == f True - """ name, latex_name = self._function_name("ln", r"\ln") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3119,7 +3075,6 @@ def __pow__(self, exponent): True sage: pow(pow(f, 1/2), 2) == f True - """ from sage.misc.latex import latex if self._name is None: @@ -3140,9 +3095,7 @@ def sqrt(self): r""" Square root of the scalar field. - OUTPUT: - - - the scalar field `\sqrt f`, where `f` is the current scalar field + OUTPUT: the scalar field `\sqrt f`, where `f` is the current scalar field EXAMPLES:: @@ -3164,7 +3117,6 @@ def sqrt(self): True sage: sqrt(M.zero_scalar_field()) == M.zero_scalar_field() True - """ name, latex_name = self._function_name("sqrt", r"\sqrt", parentheses=False) @@ -3177,9 +3129,7 @@ def cos(self): r""" Cosine of the scalar field. - OUTPUT: - - - the scalar field `\cos f`, where `f` is the current scalar field + OUTPUT: the scalar field `\cos f`, where `f` is the current scalar field EXAMPLES:: @@ -3200,7 +3150,6 @@ def cos(self): True sage: cos(M.constant_scalar_field(pi/2)) == M.zero_scalar_field() True - """ name, latex_name = self._function_name("cos", r"\cos") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3212,9 +3161,7 @@ def sin(self): r""" Sine of the scalar field. - OUTPUT: - - - the scalar field `\sin f`, where `f` is the current scalar field + OUTPUT: the scalar field `\sin f`, where `f` is the current scalar field EXAMPLES:: @@ -3235,7 +3182,6 @@ def sin(self): True sage: sin(M.constant_scalar_field(pi/2)) == M.constant_scalar_field(1) True - """ name, latex_name = self._function_name("sin", r"\sin") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3247,9 +3193,7 @@ def tan(self): r""" Tangent of the scalar field. - OUTPUT: - - - the scalar field `\tan f`, where `f` is the current scalar field + OUTPUT: the scalar field `\tan f`, where `f` is the current scalar field EXAMPLES:: @@ -3272,7 +3216,6 @@ def tan(self): True sage: tan(M.constant_scalar_field(pi/4)) == M.constant_scalar_field(1) True - """ name, latex_name = self._function_name("tan", r"\tan") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3284,9 +3227,7 @@ def arccos(self): r""" Arc cosine of the scalar field. - OUTPUT: - - - the scalar field `\arccos f`, where `f` is the current scalar field + OUTPUT: the scalar field `\arccos f`, where `f` is the current scalar field EXAMPLES:: @@ -3316,7 +3257,6 @@ def arccos(self): True sage: arccos(M.zero_scalar_field()) == M.constant_scalar_field(pi/2) True - """ name, latex_name = self._function_name("arccos", r"\arccos") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3328,9 +3268,7 @@ def arcsin(self): r""" Arc sine of the scalar field. - OUTPUT: - - - the scalar field `\arcsin f`, where `f` is the current scalar field + OUTPUT: the scalar field `\arcsin f`, where `f` is the current scalar field EXAMPLES:: @@ -3360,7 +3298,6 @@ def arcsin(self): True sage: arcsin(M.constant_scalar_field(1)) == M.constant_scalar_field(pi/2) True - """ name, latex_name = self._function_name("arcsin", r"\arcsin") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3372,9 +3309,7 @@ def arctan(self): r""" Arc tangent of the scalar field. - OUTPUT: - - - the scalar field `\arctan f`, where `f` is the current scalar field + OUTPUT: the scalar field `\arctan f`, where `f` is the current scalar field EXAMPLES:: @@ -3404,7 +3339,6 @@ def arctan(self): True sage: arctan(M.constant_scalar_field(1)) == M.constant_scalar_field(pi/4) True - """ name, latex_name = self._function_name("arctan", r"\arctan") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3416,9 +3350,7 @@ def cosh(self): r""" Hyperbolic cosine of the scalar field. - OUTPUT: - - - the scalar field `\cosh f`, where `f` is the current scalar field + OUTPUT: the scalar field `\cosh f`, where `f` is the current scalar field EXAMPLES:: @@ -3437,7 +3369,6 @@ def cosh(self): sage: cosh(M.zero_scalar_field()) == M.constant_scalar_field(1) True - """ name, latex_name = self._function_name("cosh", r"\cosh") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3449,9 +3380,7 @@ def sinh(self): r""" Hyperbolic sine of the scalar field. - OUTPUT: - - - the scalar field `\sinh f`, where `f` is the current scalar field + OUTPUT: the scalar field `\sinh f`, where `f` is the current scalar field EXAMPLES:: @@ -3470,7 +3399,6 @@ def sinh(self): sage: sinh(M.zero_scalar_field()) == M.zero_scalar_field() True - """ name, latex_name = self._function_name("sinh", r"\sinh") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3482,9 +3410,7 @@ def tanh(self): r""" Hyperbolic tangent of the scalar field. - OUTPUT: - - - the scalar field `\tanh f`, where `f` is the current scalar field + OUTPUT: the scalar field `\tanh f`, where `f` is the current scalar field EXAMPLES:: @@ -3505,7 +3431,6 @@ def tanh(self): True sage: tanh(M.zero_scalar_field()) == M.zero_scalar_field() True - """ name, latex_name = self._function_name("tanh", r"\tanh") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3548,7 +3473,6 @@ def arccosh(self): True sage: arccosh(M.constant_scalar_field(1)) == M.zero_scalar_field() True - """ name, latex_name = self._function_name("arccosh", r"\,\mathrm{arccosh}") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3591,7 +3515,6 @@ def arcsinh(self): True sage: arcsinh(M.zero_scalar_field()) == M.zero_scalar_field() True - """ name, latex_name = self._function_name("arcsinh", r"\,\mathrm{arcsinh}") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3636,7 +3559,6 @@ def arctanh(self): True sage: arctanh(M.constant_scalar_field(1/2)) == M.constant_scalar_field(log(3)/2) True - """ name, latex_name = self._function_name("arctanh", r"\,\mathrm{arctanh}") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3665,7 +3587,6 @@ def __abs__(self): sage: g.display() abs(f): M → ℝ (x, y) ↦ abs(x)*abs(y) - """ name, latex_name = self._function_name("abs", r"\,\mathrm{abs}") resu = type(self)(self.parent(), name=name, latex_name=latex_name) @@ -3707,7 +3628,7 @@ def set_calc_order(self, symbol, order, truncate=False): The order of the big `O` in the power series expansion is `n+1`, where `n` is ``order``. - - ``truncate`` -- (default: ``False``) determines whether the + - ``truncate`` -- boolean (default: ``False``); determines whether the coordinate expressions of ``self`` are replaced by their expansions to the given order @@ -3722,7 +3643,6 @@ def set_calc_order(self, symbol, order, truncate=False): sage: f.set_calc_order(t, 2, truncate=True) sage: f.expr() 1/2*t^2*x^2 - t*x + 1 - """ for expr in self._express.values(): expr._expansion_symbol = symbol @@ -3748,7 +3668,6 @@ def set_immutable(self): True sage: f.restrict(V).is_immutable() True - """ for rst in self._restrictions.values(): rst.set_immutable() @@ -3781,7 +3700,6 @@ def __hash__(self): sage: {f: 1}[f] 1 - """ if self.is_mutable(): raise ValueError('element must be immutable in order to be ' diff --git a/src/sage/manifolds/scalarfield_algebra.py b/src/sage/manifolds/scalarfield_algebra.py index 3923247367d..311f749adf3 100644 --- a/src/sage/manifolds/scalarfield_algebra.py +++ b/src/sage/manifolds/scalarfield_algebra.py @@ -356,7 +356,6 @@ class ScalarFieldAlgebra(UniqueRepresentation, Parent): It is passed also for `C^0(W)`:: sage: TestSuite(CW).run() - """ Element = ScalarField @@ -377,7 +376,6 @@ def __init__(self, domain): sage: type(CM).__base__ sage: TestSuite(CM).run() - """ base_field = domain.base_field() if domain.base_field_type() in ['real', 'complex']: @@ -449,7 +447,6 @@ def _element_constructor_(self, coord_expression=None, chart=None, sage: fU.display() f: U → ℝ (x, y) ↦ y^2 + x - """ try: if coord_expression.is_trivial_zero(): @@ -481,7 +478,7 @@ def _element_constructor_(self, coord_expression=None, chart=None, def _an_element_(self): r""" - Construct some element of the algebra + Construct some element of the algebra. TESTS:: @@ -493,7 +490,6 @@ def _an_element_(self): sage: f.display() M → ℝ (x, y) ↦ 2 - """ return self.element_class(self, coord_expression=2, chart='all') @@ -520,7 +516,6 @@ def _coerce_map_from_(self, other): False sage: CU._coerce_map_from_(CM) True - """ from .chart_func import ChartFunctionRing if isinstance(other, SymbolicRing): @@ -549,7 +544,6 @@ def _repr_(self): 'Algebra of scalar fields on the 2-dimensional topological manifold M' sage: CM Algebra of scalar fields on the 2-dimensional topological manifold M - """ return "Algebra of scalar fields on the {}".format(self._domain) @@ -565,7 +559,6 @@ def _latex_(self): 'C^0 \\left(M\\right)' sage: latex(CM) C^0 \left(M\right) - """ return r"C^0 \left(" + self._domain._latex_() + r"\right)" @@ -592,7 +585,6 @@ def zero(self): sage: CM.zero() is z True - """ coord_express = {chart: chart.zero_function() for chart in self._domain.atlas()} @@ -626,7 +618,6 @@ def one(self): sage: CM.one() is h True - """ coord_express = {chart: chart.one_function() for chart in self._domain.atlas()} diff --git a/src/sage/manifolds/section.py b/src/sage/manifolds/section.py index 987f9663b96..50ab4531cb6 100644 --- a/src/sage/manifolds/section.py +++ b/src/sage/manifolds/section.py @@ -209,7 +209,6 @@ class Section(ModuleElementWithMutability): Traceback (most recent call last): ... ValueError: the name of an immutable element cannot be changed - """ def __init__(self, section_module, name=None, latex_name=None): r""" @@ -237,7 +236,6 @@ def __init__(self, section_module, name=None, latex_name=None): sage: s in C0 True sage: TestSuite(s).run() - """ ModuleElementWithMutability.__init__(self, section_module) self._smodule = section_module @@ -287,7 +285,6 @@ def __bool__(self): True sage: s.is_zero() # indirect doctest False - """ if self._is_zero: return False @@ -317,7 +314,6 @@ def _repr_(self): sage: s # indirect doctest Section s on the 3-dimensional differentiable manifold M with values in the real vector bundle E of rank 2 - """ desc = "Section " if self._name is not None: @@ -341,7 +337,6 @@ def _latex_(self): '\\sigma' sage: latex(sigma) # indirect doctest \sigma - """ if self._latex_name is None: return r'\text{' + str(self) + r'}' @@ -358,7 +353,6 @@ def _init_derived(self): sage: E = M.vector_bundle(2, 'E') sage: s = E.section(name='s') sage: s._init_derived() - """ self._restrictions = {} # dict. of restrictions of self on subdomains # of self._domain, with the subdomains as keys @@ -375,7 +369,6 @@ def _del_derived(self, del_restrictions=False): sage: E = M.vector_bundle(2, 'E') sage: s = E.section(name='s') sage: s._del_derived() - """ if del_restrictions: self._restrictions.clear() @@ -415,7 +408,6 @@ def set_name(self, name=None, latex_name=None): the real vector bundle E of rank 2 sage: latex(s) a - """ if self.is_immutable(): raise ValueError("the name of an immutable element " @@ -449,7 +441,6 @@ def _new_instance(self): True sage: s1.parent() is s.parent() True - """ return type(self)(self._smodule) @@ -473,7 +464,6 @@ def _del_restrictions(self): sage: s._del_restrictions() sage: s._restrictions {} - """ self._restrictions.clear() self._extensions_graph = {self._domain: self} @@ -517,7 +507,6 @@ def _init_components(self, *comp, **kwargs): sage: s._init_components({(f, Y): [t, v^3]}) sage: s.display(f, Y) s = t f_0 + v^3 f_1 - """ comp0 = comp[0] self._is_zero = False # a priori @@ -558,7 +547,6 @@ def domain(self): sage: z = C0_U.zero() sage: z.domain() Open subset U of the 3-dimensional topological manifold M - """ return self._domain @@ -581,7 +569,6 @@ def base_module(self): Module C^0(U;E) of sections on the Open subset U of the 3-dimensional topological manifold M with values in the real vector bundle E of rank 2 - """ return self._smodule @@ -619,7 +606,6 @@ def set_restriction(self, rst): s = (x + y) (phi_U^*e_1) + x (phi_U^*e_2) sage: s.restrict(U) == sU True - """ if self.is_immutable(): raise ValueError("the restrictions of an immutable element " @@ -640,9 +626,7 @@ def restrict(self, subdomain): :class:`~sage.manifolds.differentiable.manifold.DifferentiableManifold`; open subset `U` of the section domain `S` - OUTPUT: - - - :class:`Section` representing the restriction + OUTPUT: :class:`Section` representing the restriction EXAMPLES: @@ -708,7 +692,6 @@ def restrict(self, subdomain): True sage: sU.restrict(U) is sU True - """ if subdomain == self._domain: return self @@ -837,7 +820,6 @@ def _set_comp_unsafe(self, basis=None): ... ValueError: no basis could be found for computing the components in the Trivialization frame (E|_V, ((phi_V^*e_1),(phi_V^*e_2))) - """ if basis is None: basis = self._smodule.default_frame() @@ -909,8 +891,6 @@ def set_comp(self, basis=None): ... ValueError: no basis could be found for computing the components in the Trivialization frame (E|_V, ((phi_V^*e_1),(phi_V^*e_2))) - - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -982,7 +962,6 @@ def _add_comp_unsafe(self, basis=None): sage: s.display(fS) s = (u + v) (phi_V^*e_1) - """ if basis is None: basis = self._smodule.default_frame() @@ -1048,7 +1027,6 @@ def add_comp(self, basis=None): sage: s.display(fS) s = (u + v) (phi_V^*e_1) - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1130,7 +1108,6 @@ def add_comp_by_continuation(self, frame, subdomain, chart=None): (phi_V^*e_2) and `a` is defined on the entire manifold `S^2`. - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1156,7 +1133,7 @@ def add_expr_from_subdomain(self, frame, subdomain): - ``frame`` -- local frame `e` in which the components are to be set - ``subdomain`` -- open subset of `e`'s domain in which the - components have additional expressions. + components have additional expressions EXAMPLES: @@ -1214,7 +1191,6 @@ def add_expr_from_subdomain(self, frame, subdomain): S^2 → ℝ on U: (x, y) ↦ y on V: (u, v) ↦ v/(u^2 + v^2) - """ if self.is_immutable(): raise ValueError("the expressions of an immutable element " @@ -1292,7 +1268,6 @@ def comp(self, basis=None, from_basis=None): True sage: s.restrict(U).comp() is s.comp(e) True - """ if basis is None: basis = self._smodule.default_frame() @@ -1393,7 +1368,6 @@ def display(self, frame=None, chart=None): sage: s.disp(fS) s = v/(u^2 + v^2) (phi_V^*e_1) + u/(u^2 + v^2) (phi_V^*e_2) - """ if frame is None: frame = self._smodule.default_frame() @@ -1420,7 +1394,7 @@ def display_comp(self, frame=None, chart=None, only_nonzero=True): - ``chart`` -- (default: ``None``) chart specifying the coordinate expression of the components; if ``None``, the default chart of the section domain is used - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero components are displayed EXAMPLES: @@ -1449,7 +1423,6 @@ def display_comp(self, frame=None, chart=None, only_nonzero=True): See documentation of :meth:`sage.manifolds.section.TrivialSection.display_comp` for more options. - """ if frame is None: frame = self._smodule.default_frame() @@ -1520,7 +1493,6 @@ def at(self, point): s = 4 (phi_V^*e_1) + 8 (phi_V^*e_2) sage: p.coord(c_uv) # to check the above expression (5, -1) - """ if point not in self._domain: raise ValueError("the {} is not a point in the ".format(point) + @@ -1569,7 +1541,6 @@ def __getitem__(self, args): [Scalar field on the 3-dimensional topological manifold M, Scalar field on the 3-dimensional topological manifold M, Scalar field on the 3-dimensional topological manifold M] - """ if isinstance(args, str): # section with specified indices return TensorWithIndices(self, args).update() @@ -1591,7 +1562,7 @@ def __getitem__(self, args): def __setitem__(self, args, value): r""" - Sets a component with respect to some local frame. + Set a component with respect to some local frame. INPUT: @@ -1622,7 +1593,6 @@ def __setitem__(self, args, value): sage: s.__setitem__(slice(None), [x+y, 3*y^2, x*y]) sage: s.display() s = (x + y) e_0 + 3*y^2 e_1 + x*y e_2 - """ if isinstance(args, list): # case of [[...]] syntax if not isinstance(args[0], (int, Integer, slice)): @@ -1691,7 +1661,6 @@ def copy_from(self, other): t = 2 (phi_U^*e_1) + (-y + 1) (phi_U^*e_2) sage: s == t False - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1759,7 +1728,6 @@ def copy(self, name=None, latex_name=None): 2 (phi_U^*e_1) + (-y + 1) (phi_U^*e_2) sage: t == s False - """ resu = self._new_instance() # set resu name @@ -1814,7 +1782,6 @@ def _common_subdomains(self, other): sage: sorted(t._common_subdomains(s), key=str) [Open subset U of the 2-dimensional topological manifold M, Open subset V of the 2-dimensional topological manifold M] - """ resu = [] for dom in self._restrictions: @@ -1830,9 +1797,7 @@ def __eq__(self, other): - ``other`` -- a section or 0 - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise TESTS:: @@ -1869,7 +1834,6 @@ def __eq__(self, other): False sage: s.parent().zero() == 0 True - """ if other is self: return True @@ -1949,7 +1913,6 @@ def __ne__(self, other): False sage: s != 0 True - """ return not (self == other) @@ -1957,9 +1920,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of ``self`` + OUTPUT: an exact copy of ``self`` TESTS:: @@ -1985,7 +1946,6 @@ def __pos__(self): in the real vector bundle E of rank 2 sage: t.display(fU) +s = x (phi_U^*e_1) + (phi_U^*e_2) - """ resu = self._new_instance() for dom, rst in self._restrictions.items(): @@ -2000,9 +1960,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the tensor field `-T`, where `T` is ``self`` + OUTPUT: the tensor field `-T`, where `T` is ``self`` TESTS:: @@ -2036,7 +1994,6 @@ def __neg__(self): -s = (-1/2*u - 1/2*v) (phi_V^*e_1) + (-1/4*u^2 - 1/2*u*v - 1/4*v^2) (phi_V^*e_2) sage: s == -t # indirect doctest True - """ resu = self._new_instance() for dom, rst in self._restrictions.items(): @@ -2057,9 +2014,7 @@ def _add_(self, other): - ``other`` -- a section, in the same section module as ``self`` - OUTPUT: - - - the section resulting from the addition of ``self`` and ``other`` + OUTPUT: the section resulting from the addition of ``self`` and ``other`` TESTS:: @@ -2101,7 +2056,6 @@ def _add_(self, other): True sage: z._add_(s) == s True - """ # Case zero: if self._is_zero: @@ -2128,9 +2082,7 @@ def _sub_(self, other): - ``other`` -- a section in the same section module as ``self`` - OUTPUT: - - - the section resulting from the subtraction of ``other`` from ``self`` + OUTPUT: the section resulting from the subtraction of ``other`` from ``self`` TESTS:: @@ -2170,7 +2122,6 @@ def _sub_(self, other): True sage: z._sub_(s) == -s True - """ # Case zero: if self._is_zero: @@ -2191,7 +2142,7 @@ def _sub_(self, other): def _rmul_(self, scalar): r""" - Reflected multiplication operator: performs ``scalar * self`` + Reflected multiplication operator: performs ``scalar * self``. This is actually the multiplication by an element of the ring over which the tensor field module is constructed. @@ -2201,9 +2152,7 @@ def _rmul_(self, scalar): - ``scalar`` -- scalar field in the scalar field algebra over which the module containing ``self`` is defined - OUTPUT: - - - the tensor field ``scalar * self`` + OUTPUT: the tensor field ``scalar * self`` TESTS:: @@ -2250,7 +2199,6 @@ def _rmul_(self, scalar): True sage: z._rmul_(g) == z True - """ ### # Case zero: @@ -2295,7 +2243,6 @@ def set_immutable(self): True sage: sU.is_immutable() True - """ for rst in self._restrictions.values(): rst.set_immutable() @@ -2381,7 +2328,6 @@ class TrivialSection(FiniteRankFreeModuleElement, Section): manifold S^3 with values in the real vector bundle E of rank 3 sage: isinstance(s.parent(), FiniteRankFreeModule) True - """ def __init__(self, section_module, name=None, latex_name=None): r""" @@ -2407,7 +2353,6 @@ def __init__(self, section_module, name=None, latex_name=None): Free module C^0(M;E) of sections on the 2-dimensional topological manifold M with values in the real vector bundle E of rank 2 sage: TestSuite(s).run() - """ FiniteRankFreeModuleElement.__init__(self, section_module, name=name, latex_name=latex_name) @@ -2430,7 +2375,6 @@ def _init_derived(self): sage: e = E.local_frame('e') # makes E trivial sage: s = E.section(name='s') sage: s._init_derived() - """ FiniteRankFreeModuleElement._init_derived(self) Section._init_derived(self) @@ -2441,7 +2385,7 @@ def _del_derived(self, del_restrictions=True): INPUT: - - ``del_restrictions`` -- (default: ``True``) determines whether the + - ``del_restrictions`` -- boolean (default: ``True``); determines whether the restrictions of ``self`` to subdomains are deleted TESTS:: @@ -2451,7 +2395,6 @@ def _del_derived(self, del_restrictions=True): sage: e = E.local_frame('e') # makes E trivial sage: s = E.section(name='s') sage: s._del_derived() - """ FiniteRankFreeModuleElement._del_derived(self) Section._del_derived(self, del_restrictions=del_restrictions) @@ -2475,7 +2418,6 @@ def _repr_(self) : sage: s # indirect doctest Section s on the 2-dimensional topological manifold M with values in the real vector bundle E of rank 2 - """ return Section._repr_(self) @@ -2495,7 +2437,6 @@ def _new_instance(self): the real vector bundle E of rank 2 sage: type(s._new_instance()) is type(s) True - """ return type(self)(self._smodule) @@ -2566,7 +2507,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such ... ValueError: no basis could be found for computing the components in the Local frame (E|_M, (f_0,f_1)) - """ if basis is None: basis = self._smodule.default_frame() @@ -2654,7 +2594,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such ... ValueError: no basis could be found for computing the components in the Local frame (E|_M, (f_0,f_1)) - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -2742,7 +2681,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such s = 2 e_0 sage: s.display(f) s = x f_0 - """ if basis is None: basis = self._smodule.default_frame() @@ -2828,7 +2766,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such s = 2 e_0 sage: s.display(f) s = x f_0 - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -2894,7 +2831,6 @@ class :class:`~sage.tensor.modules.comp.Components` 1-index components w.r.t. Local frame (E|_M, (f_1,f_2)) sage: s.comp(f)[:] [x - 3, 0] - """ if basis is None: basis = self._smodule.default_frame() @@ -2920,9 +2856,7 @@ def restrict(self, subdomain): :class:`~sage.manifolds.differentiable.manifold.DifferentiableManifold`; open subset `U` of the section module domain `S` - OUTPUT: - - - instance of :class:`TrivialSection` representing the restriction + OUTPUT: instance of :class:`TrivialSection` representing the restriction EXAMPLES: @@ -2964,7 +2898,6 @@ def restrict(self, subdomain): sage: s.restrict(M) is s True - """ if subdomain == self._domain: return self @@ -3054,7 +2987,7 @@ def display_comp(self, frame=None, chart=None, only_nonzero=False): - ``chart`` -- (default: ``None``) chart specifying the coordinate expression of the components; if ``None``, the default chart of the section module domain is used - - ``only_nonzero`` -- (default: ``False``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``False``); if ``True``, only nonzero components are displayed EXAMPLES: @@ -3108,7 +3041,6 @@ def display_comp(self, frame=None, chart=None, only_nonzero=False): s^0 = 4*u/(u^2 - 2*u*v + v^2 + 4) s^1 = 0 s^2 = 1/4*u^2 - 1/4*v^2 - """ if frame is None: frame = self._smodule.default_basis() @@ -3160,7 +3092,6 @@ def at(self, point): Fiber of E at Point p on the 2-dimensional topological manifold M sage: sp.display() s = 3 e_0 + 4 e_1 - """ if point not in self._domain: raise ValueError("the {} is not in the domain of ".format(point) + diff --git a/src/sage/manifolds/section_module.py b/src/sage/manifolds/section_module.py index 94c7ca6b4ba..5c654762977 100644 --- a/src/sage/manifolds/section_module.py +++ b/src/sage/manifolds/section_module.py @@ -139,7 +139,6 @@ class SectionModule(UniqueRepresentation, Parent): The conversion map is actually the restriction of sections defined on `M` to `U`. - """ Element = Section @@ -170,7 +169,6 @@ def __init__(self, vbundle, domain): Module C^0(S^1;E) of sections on the 1-dimensional topological manifold S^1 with values in the real vector bundle E of rank 1 sage: TestSuite(C0).run() - """ base_space = vbundle.base_space() if not domain.is_subset(base_space): @@ -217,7 +215,6 @@ def _element_constructor_(self, comp=[], frame=None, name=None, s = -x e_0 + y e_1 sage: C0(0) is C0.zero() True - """ try: if comp.is_trivial_zero(): @@ -255,7 +252,6 @@ def _an_element_(self): sage: C0._an_element_() Section on the 2-dimensional topological manifold M with values in the real vector bundle E of rank 2 - """ resu = self.element_class(self) for oc in self._domain.open_covers(trivial=False): @@ -281,7 +277,6 @@ def _coerce_map_from_(self, other): False sage: C0_U._coerce_map_from_(C0) True - """ if isinstance(other, (SectionModule, SectionFreeModule)): return self._domain.is_subset(other._domain) @@ -308,7 +303,6 @@ def _repr_(self): sage: C0 # indirect doctest Module C^0(M;E) of sections on the 2-dimensional topological manifold M with values in the real vector bundle E of rank 2 - """ desc = "Module {} of sections on the {} with values in the {} vector " \ "bundle {} of rank {}" @@ -331,7 +325,6 @@ def _latex_(self): 'C^{\\infty}(M;E)' sage: latex(C) # indirect doctest C^{\infty}(M;E) - """ return self._latex_name @@ -350,7 +343,6 @@ def base_space(self): bundle E of rank 2 sage: C0.base_space() Open subset U of the 3-dimensional topological manifold M - """ return self._base_space @@ -369,7 +361,6 @@ def domain(self): bundle E of rank 2 sage: C0_U.domain() Open subset U of the 3-dimensional topological manifold M - """ return self._domain @@ -390,7 +381,6 @@ def vector_bundle(self): 3-dimensional topological manifold M sage: E is C0.vector_bundle() True - """ return self._vbundle @@ -410,7 +400,6 @@ def zero(self): in the real vector bundle E of rank 2 sage: z == 0 True - """ res = self.element_class(self, name='zero', latex_name='0') for frame in self._vbundle._frames: @@ -442,7 +431,6 @@ def default_frame(self): sage: e is C0.default_frame() True - """ return self._def_frame @@ -477,7 +465,6 @@ def set_default_frame(self, basis): sage: C0.default_frame().domain() Open subset U of the 3-dimensional topological manifold M - """ from .local_frame import LocalFrame if not isinstance(basis, LocalFrame): @@ -577,7 +564,6 @@ class SectionFreeModule(FiniteRankFreeModule): The test suite is passed as well:: sage: TestSuite(C0).run() - """ Element = TrivialSection @@ -598,7 +584,6 @@ def __init__(self, vbundle, domain): sage: C0 is E.section_module(force_free=True) True sage: TestSuite(C0).run() - """ from .scalarfield import ScalarField self._domain = domain @@ -639,7 +624,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, s = -x e_0 + y e_1 sage: C0(0) is C0.zero() True - """ try: if comp.is_trivial_zero(): @@ -679,7 +663,6 @@ def _coerce_map_from_(self, other): False sage: C0_U._coerce_map_from_(C0) True - """ if isinstance(other, (SectionModule, SectionFreeModule)): return self._domain.is_subset(other._domain) @@ -706,7 +689,6 @@ def _repr_(self): sage: C0 # indirect doctest Free module C^0(M;E) of sections on the 2-dimensional topological manifold M with values in the real vector bundle E of rank 2 - """ desc = "Free module {} of sections on the {} with values in the {} " \ "vector bundle {} of rank {}" @@ -731,7 +713,6 @@ def domain(self): bundle E of rank 2 sage: C0_U.domain() Open subset U of the 3-dimensional topological manifold M - """ return self._domain @@ -770,7 +751,6 @@ def vector_bundle(self): 3-dimensional topological manifold M sage: E is C0.vector_bundle() True - """ return self._vbundle @@ -826,7 +806,6 @@ def basis(self, symbol=None, latex_symbol=None, from_frame=None, See :class:`~sage.manifolds.local_frame.LocalFrame` for more examples and documentation. - """ from sage.manifolds.local_frame import LocalFrame if symbol is None: diff --git a/src/sage/manifolds/structure.py b/src/sage/manifolds/structure.py index 25ff96ac9df..cf6a9466f9a 100644 --- a/src/sage/manifolds/structure.py +++ b/src/sage/manifolds/structure.py @@ -55,7 +55,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: TopologicalStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -80,7 +79,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: RealTopologicalStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -105,7 +103,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: DifferentialStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -130,7 +127,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: RealDifferentialStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -154,7 +150,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: PseudoRiemannianStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -178,7 +173,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: RiemannianStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -202,7 +196,6 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: LorentzianStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat @@ -226,6 +219,5 @@ def subcategory(self, cat): sage: from sage.categories.manifolds import Manifolds sage: DegenerateStructure().subcategory(Manifolds(RR)) Category of manifolds over Real Field with 53 bits of precision - """ return cat diff --git a/src/sage/manifolds/subset.py b/src/sage/manifolds/subset.py index bf945ebb0c1..5a3f9238a9a 100644 --- a/src/sage/manifolds/subset.py +++ b/src/sage/manifolds/subset.py @@ -19,7 +19,6 @@ - [Lee2011]_ - EXAMPLES: Two subsets on a manifold:: @@ -94,7 +93,7 @@ class :class:`~sage.structure.parent.Parent`. - ``manifold`` -- topological manifold on which the subset is defined - ``name`` -- string; name (symbol) given to the subset - - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to + - ``latex_name`` -- string (default: ``None``); LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` - ``category`` -- (default: ``None``) to specify the category; if ``None``, the category for generic subsets is used @@ -144,7 +143,6 @@ class :class:`~sage.structure.parent.Parent`. True sage: p in M True - """ Element = ManifoldPoint @@ -170,7 +168,6 @@ def __init__(self, manifold, name: str, latex_name=None, category=None): ``_test_elements`` cannot be passed without a proper coordinate definition of the subset. - """ if not isinstance(name, str): raise TypeError("{} is not a string".format(name)) @@ -219,7 +216,6 @@ def _repr_(self): 'Subset A of the 2-dimensional topological manifold M' sage: repr(A) # indirect doctest 'Subset A of the 2-dimensional topological manifold M' - """ return "Subset {} of the {}".format(self._name, self._manifold) @@ -271,15 +267,15 @@ def _element_constructor_(self, coords=None, chart=None, name=None, - ``name`` -- (default: ``None``) name given to the point - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the point; if none are provided, the LaTeX symbol is set to ``name`` - - ``check_coords`` -- (default: ``True``) determines whether - ``coords`` are valid coordinates for the chart ``chart``; - for symbolic coordinates, it is recommended to set ``check_coords`` - to ``False`` + - ``check_coords`` -- boolean (default: ``True``); determines whether + ``coords`` are valid coordinates for the chart ``chart``. + For symbolic coordinates, it is recommended to set ``check_coords`` + to ``False``. OUTPUT: - - an instance of :class:`~sage.manifolds.point.ManifoldPoint` - representing a point in the current subset. + An instance of :class:`~sage.manifolds.point.ManifoldPoint` + representing a point in the current subset. EXAMPLES:: @@ -330,7 +326,6 @@ def _element_constructor_(self, coords=None, chart=None, name=None, Point p on the 2-dimensional topological manifold M sage: X(q) (-2, 3) - """ if isinstance(coords, ManifoldPoint): point = coords # for readability @@ -363,7 +358,6 @@ def _an_element_(self): Point on the 2-dimensional topological manifold M sage: p in A True - """ #!# should be improved... return self.element_class(self) @@ -409,9 +403,7 @@ def lift(self, p): - ``p`` -- point of the subset - OUTPUT: - - - the same point, considered as a point of the ambient manifold + OUTPUT: the same point, considered as a point of the ambient manifold EXAMPLES:: @@ -430,7 +422,6 @@ def lift(self, p): (1, -2) sage: (p == q) and (q == p) True - """ return self._manifold(p) @@ -442,9 +433,7 @@ def retract(self, p): - ``p`` -- point of the ambient manifold - OUTPUT: - - - the same point, considered as a point of the subset + OUTPUT: the same point, considered as a point of the subset EXAMPLES:: @@ -473,7 +462,6 @@ def retract(self, p): ... ValueError: the Point on the 2-dimensional topological manifold M is not in Open subset A of the 2-dimensional topological manifold M - """ return self(p) @@ -499,7 +487,6 @@ def manifold(self): sage: A.ambient() is A.manifold() True - """ return self._manifold @@ -520,7 +507,6 @@ def is_open(self): sage: A = M.subset('A') sage: A.is_open() False - """ return False @@ -552,7 +538,6 @@ def is_closed(self): sage: M.declare_union(N, complement_N, disjoint=True) sage: complement_N.is_closed() True - """ if self.manifold().is_subset(self): return True @@ -599,10 +584,11 @@ def open_covers(self, trivial=True, supersets=False): INPUT: - - ``trivial`` -- (default: ``True``) if ``self`` is open, include the trivial - open cover of ``self`` by itself - - ``supersets`` -- (default: ``False``) if ``True``, include open covers of - all the supersets; it can also be an iterable of supersets to include + - ``trivial`` -- boolean (default: ``True``); if ``self`` is open, + include the trivial open cover of ``self`` by itself + - ``supersets`` -- boolean (default: ``False``); if ``True``, include + open covers of all the supersets. It can also be an iterable of + supersets to include. EXAMPLES:: @@ -628,7 +614,6 @@ def open_covers(self, trivial=True, supersets=False): [Set {M} of open subsets of the 2-dimensional topological manifold M, Set {U, V} of open subsets of the 2-dimensional topological manifold M, Set {A, B, V} of open subsets of the 2-dimensional topological manifold M] - """ if supersets is False: supersets = [self] @@ -671,10 +656,11 @@ def open_cover_family(self, trivial=True, supersets=False): INPUT: - - ``trivial`` -- (default: ``True``) if ``self`` is open, include the trivial - open cover of ``self`` by itself - - ``supersets`` -- (default: ``False``) if ``True``, include open covers of - all the supersets; it can also be an iterable of supersets to include + - ``trivial`` -- boolean (default: ``True``); if ``self`` is open, + include the trivial open cover of ``self`` by itself + - ``supersets`` -- boolean (default: ``False``); if ``True``, include + open covers of all the supersets. It can also be an iterable of + supersets to include EXAMPLES:: @@ -695,7 +681,6 @@ def open_cover_family(self, trivial=True, supersets=False): sage: M.declare_union(U,V) sage: M.open_cover_family() Set {{A, B, V}, {M}, {U, V}} of objects of the 2-dimensional topological manifold M - """ return ManifoldObjectFiniteFamily(self.open_covers( trivial=trivial, supersets=supersets)) @@ -718,7 +703,6 @@ def open_supersets(self): sage: sorted(W.open_supersets(), key=lambda S: S._name) [2-dimensional topological manifold M, Open subset U of the 2-dimensional topological manifold M] - """ for superset in self._supersets: if superset.is_open(): @@ -749,7 +733,6 @@ def open_superset_family(self): sage: W = V.subset('W') sage: W.open_superset_family() Set {M, U} of open subsets of the 2-dimensional topological manifold M - """ return ManifoldSubsetFiniteFamily(self.open_supersets()) @@ -781,7 +764,6 @@ def subsets(self): sage: M.subset_family() Set {M, U, V} of subsets of the 2-dimensional topological manifold M - """ yield from self._subsets @@ -834,7 +816,6 @@ def list_of_subsets(self): {Subset V of the 2-dimensional topological manifold M, 2-dimensional topological manifold M, Open subset U of the 2-dimensional topological manifold M} - """ deprecation(31727, "the method list_of_subsets of ManifoldSubset is deprecated; use subset_family or subsets instead") return sorted(self._subsets, key=lambda x: x._name) @@ -864,7 +845,6 @@ def subset_family(self): sage: V = M.subset('V') sage: M.subset_family() Set {M, U, V} of subsets of the 2-dimensional topological manifold M - """ return ManifoldSubsetFiniteFamily(self.subsets()) @@ -874,20 +854,18 @@ def subset_digraph(self, loops=False, quotient=False, open_covers=False, points= INPUT: - - ``loops`` -- (default: ``False``) whether to include the trivial containment + - ``loops`` -- boolean (default: ``False``); whether to include the trivial containment of each subset in itself as loops of the digraph - - ``quotient`` -- (default: ``False``) whether to contract directed cycles in the graph, - replacing equivalence classes of equal subsets by a single vertex. - In this case, each vertex of the digraph is a set of :class:`ManifoldSubset` - instances. - - ``open_covers`` -- (default: ``False``) whether to include vertices for open covers - - ``points`` -- (default: ``False``) whether to include vertices for declared points; + - ``quotient`` -- boolean (default: ``False``); whether to contract directed + cycles in the graph, replacing equivalence classes of equal subsets by a + single vertex. In this case, each vertex of the digraph is a set of + :class:`ManifoldSubset` instances. + - ``open_covers`` -- boolean (default: ``False``); whether to include vertices for open covers + - ``points`` -- boolean (default: ``False``); whether to include vertices for declared points; this can also be an iterable for the points to include - ``lower_bound`` -- (default: ``None``) only include supersets of this - OUTPUT: - - A digraph. Each vertex of the digraph is either: + OUTPUT: a digraph; each vertex of the digraph is either: - a :class:`ManifoldSubsetFiniteFamily` containing one instance of :class:`ManifoldSubset`. - (if ``open_covers`` is ``True``) a tuple of :class:`ManifoldSubsetFiniteFamily` instances, @@ -949,7 +927,6 @@ def label(element): D = M.subset_digraph(open_covers=True) g3 = D.relabel(label, inplace=False).plot(layout='acyclic') sphinx_plot(graphics_array([g1, g2, g3]), figsize=(8, 3)) - """ from sage.graphs.digraph import DiGraph D = DiGraph(multiedges=False, loops=loops) @@ -1048,8 +1025,8 @@ def subset_poset(self, open_covers=False, points=False, lower_bound=None): INPUT: - - ``open_covers`` -- (default: ``False``) whether to include vertices for open covers - - ``points`` -- (default: ``False``) whether to include vertices for declared points; + - ``open_covers`` -- boolean (default: ``False``); whether to include vertices for open covers + - ``points`` -- boolean (default: ``False``); whether to include vertices for declared points; this can also be an iterable for the points to include - ``lower_bound`` -- (default: ``None``) only include supersets of this @@ -1114,7 +1091,6 @@ def label(element): P = M.subset_poset(open_covers=True) g3 = P.plot(element_labels={element: label(element) for element in P}) sphinx_plot(graphics_array([g1, g2, g3]), figsize=(8, 3)) - """ from sage.combinat.posets.posets import Poset return Poset(self.subset_digraph(open_covers=open_covers, points=points, @@ -1139,7 +1115,6 @@ def equal_subsets(self): [2-dimensional topological manifold M, Open subset U of the 2-dimensional topological manifold M, Subset V of the 2-dimensional topological manifold M] - """ for S in self.supersets(): if S in self._subsets: @@ -1162,7 +1137,6 @@ def equal_subset_family(self): sage: V.declare_equal(M) sage: V.equal_subset_family() Set {M, U, V} of subsets of the 2-dimensional topological manifold M - """ return ManifoldSubsetFiniteFamily(self.equal_subsets()) @@ -1183,7 +1157,6 @@ def supersets(self): sage: sorted(V.supersets(), key=lambda v: v._name) [2-dimensional topological manifold M, Subset V of the 2-dimensional topological manifold M] - """ yield from self._supersets @@ -1210,7 +1183,6 @@ def superset_family(self): sage: V = M.subset('V') sage: V.superset_family() Set {M, V} of subsets of the 2-dimensional topological manifold M - """ return ManifoldSubsetFiniteFamily(self.supersets()) @@ -1220,14 +1192,14 @@ def superset_digraph(self, loops=False, quotient=False, open_covers=False, point INPUT: - - ``loops`` -- (default: ``False``) whether to include the trivial containment + - ``loops`` -- boolean (default: ``False``); whether to include the trivial containment of each subset in itself as loops of the digraph - - ``quotient`` -- (default: ``False``) whether to contract directed cycles in the graph, - replacing equivalence classes of equal subsets by a single vertex. - In this case, each vertex of the digraph is a set of :class:`ManifoldSubset` - instances. - - ``open_covers`` -- (default: ``False``) whether to include vertices for open covers - - ``points`` -- (default: ``False``) whether to include vertices for declared points; + - ``quotient`` -- boolean (default: ``False``); whether to contract + directed cycles in the graph, replacing equivalence classes of equal + subsets by a single vertex. In this case, each vertex of the digraph + is a set of :class:`ManifoldSubset` instances. + - ``open_covers`` -- boolean (default: ``False``); whether to include vertices for open covers + - ``points`` -- boolean (default: ``False``); whether to include vertices for declared points; this can also be an iterable for the points to include - ``upper_bound`` -- (default: ``None``) only include subsets of this @@ -1238,7 +1210,6 @@ def superset_digraph(self, loops=False, quotient=False, open_covers=False, point sage: VW = V.union(W) sage: P = V.superset_digraph(loops=False, upper_bound=VW); P # needs sage.graphs Digraph on 2 vertices - """ if upper_bound is None: upper_bound = self._manifold @@ -1251,8 +1222,8 @@ def superset_poset(self, open_covers=False, points=False, upper_bound=None): INPUT: - - ``open_covers`` -- (default: ``False``) whether to include vertices for open covers - - ``points`` -- (default: ``False``) whether to include vertices for declared points; + - ``open_covers`` -- boolean (default: ``False``); whether to include vertices for open covers + - ``points`` -- boolean (default: ``False``); whether to include vertices for declared points; this can also be an iterable for the points to include - ``upper_bound`` -- (default: ``None``) only include subsets of this @@ -1265,7 +1236,6 @@ def superset_poset(self, open_covers=False, points=False, upper_bound=None): Finite poset containing 3 elements sage: P.plot(element_labels={element: element._name for element in P}) # needs sage.graphs sage.plot Graphics object consisting of 6 graphics primitives - """ if upper_bound is None: upper_bound = self._manifold @@ -1282,7 +1252,7 @@ def get_subset(self, name): INPUT: - - ``name`` -- (string) name of the subset + - ``name`` -- string; name of the subset OUTPUT: @@ -1311,7 +1281,6 @@ def get_subset(self, name): Open subset U of the 4-dimensional topological manifold M sage: M.get_subset('U') is U True - """ for ss in self._subsets: if ss._name == name: @@ -1355,7 +1324,7 @@ def declare_union(self, *subsets_or_families, disjoint=False): INPUT: - ``subsets_or_families`` -- finitely many subsets or iterables of subsets - - ``disjoint`` -- (default: ``False``) whether to declare the subsets + - ``disjoint`` -- boolean (default: ``False``); whether to declare the subsets pairwise disjoint EXAMPLES:: @@ -1413,7 +1382,6 @@ def label(element): P = M.subset_poset(open_covers=True); P g3 = P.plot(element_labels={element: label(element) for element in P}) sphinx_plot(graphics_array([g1, g2, g3]), figsize=(8, 3)) - """ subsets = ManifoldSubsetFiniteFamily.from_subsets_or_families(*subsets_or_families) if disjoint: @@ -1455,7 +1423,6 @@ def _declare_union_2_subsets(self, dom1, dom2): sage: M.declare_union(A, B) sage: A.union(B) 2-dimensional topological manifold M - """ if dom1 == dom2: if dom1 != self: @@ -1485,7 +1452,7 @@ def declare_equal(self, *others): INPUT: - ``others`` -- finitely many subsets or iterables of subsets of the same - manifold as ``self``. + manifold as ``self`` EXAMPLES:: @@ -1528,7 +1495,6 @@ def label(element): P = M.subset_poset() g3 = P.plot(element_labels={element: label(element) for element in P}) sphinx_plot(graphics_array([g1, g2, g3]), figsize=(8, 3)) - """ F = ManifoldSubsetFiniteFamily.from_subsets_or_families equal_sets = F(self, *others) @@ -1759,7 +1725,6 @@ def label(element): P = M.subset_poset(open_covers=True, points=[b]) g2 = P.plot(element_labels={element: label(element) for element in P}) sphinx_plot(graphics_array([g1, g2]), figsize=(8, 5)) - """ if self.has_defined_points(): raise TypeError('cannot be empty because it has defined points') @@ -1789,7 +1754,6 @@ def is_empty(self): True sage: AA.is_empty() True - """ if self.has_defined_points(subsets=False): # Fast path, do not check subsets @@ -1819,7 +1783,6 @@ def declare_nonempty(self): Traceback (most recent call last): ... TypeError: cannot be empty because it has defined points - """ if self.has_defined_points(subsets=False): # Fast path, do not check subsets @@ -1834,8 +1797,8 @@ def has_defined_points(self, subsets=True): INPUT: - - ``subsets`` -- (default: ``True``) if ``False``, only consider points that have - been defined directly on ``self``; if ``True``, also consider points on all subsets. + - ``subsets`` -- boolean (default: ``True``); if ``False``, only consider points that have + been defined directly on ``self``. If ``True``, also consider points on all subsets. EXAMPLES:: @@ -1850,7 +1813,6 @@ def has_defined_points(self, subsets=True): False sage: A.has_defined_points() True - """ if subsets: return any(subset._has_defined_points for subset in self.subsets()) @@ -1924,7 +1886,6 @@ def declare_closed(self): sage: A.declare_closed() sage: cl_B2.is_subset(A) True - """ if self.is_closed(): return @@ -1944,9 +1905,9 @@ def subset(self, name, latex_name=None, is_open=False): INPUT: - ``name`` -- name given to the subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` - - ``is_open`` -- (default: ``False``) if ``True``, the created subset + - ``is_open`` -- boolean (default: ``False``); if ``True``, the created subset is assumed to be open with respect to the manifold's topology OUTPUT: @@ -2000,7 +1961,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -2049,7 +2010,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): True sage: D.is_subset(M) True - """ if supersets is None: supersets = set() @@ -2068,7 +2028,7 @@ def _init_open_subset(self, resu, coord_def): INPUT: - ``resu`` -- an instance of :class:`TopologicalManifold` or - a subclass. + a subclass - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -2087,7 +2047,6 @@ def _init_open_subset(self, resu, coord_def): sage: cl_D._init_open_subset(D, coord_def) sage: D.is_subset(cl_D) True - """ resu._supersets.update(self._supersets) self._subsets.add(resu) @@ -2106,10 +2065,10 @@ def superset(self, name, latex_name=None, is_open=False): INPUT: - ``name`` -- name given to the superset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the superset; if none are provided, it is set to ``name`` - - ``is_open`` -- (default: ``False``) if ``True``, the created subset - is assumed to be open with respect to the manifold's topology + - ``is_open`` -- boolean (default: ``False``); if ``True``, the created + subset is assumed to be open with respect to the manifold's topology OUTPUT: @@ -2141,7 +2100,6 @@ def superset(self, name, latex_name=None, is_open=False): sage: c = a.superset('C') sage: c == b False - """ if self is self._manifold: return self @@ -2171,7 +2129,7 @@ def intersection(self, *others: ManifoldSubset, name: Optional[str] = None, late - ``name`` -- (default: ``None``) name given to the intersection in the case the latter has to be created; the default is ``self._name`` inter ``other._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the intersection in the case the latter has to be created; the default is built upon the symbol `\cap` @@ -2254,7 +2212,6 @@ def label(element): True sage: a.intersection(M) is a True - """ subsets = ManifoldSubsetFiniteFamily.from_subsets_or_families(self, *others) subset_iter = iter(self._reduce_intersection_members(subsets)) @@ -2284,7 +2241,7 @@ def _reduce_intersection_members(subsets): INPUT: - ``subsets`` -- a non-empty iterable of :class:`ManifoldSubset` instances - of the same manifold. + of the same manifold EXAMPLES:: @@ -2303,7 +2260,6 @@ def _reduce_intersection_members(subsets): Traceback (most recent call last): ... TypeError: input set must be nonempty - """ subsets = set(subsets) if not subsets: @@ -2344,10 +2300,10 @@ def _intersection_subset(self, *others, name=None, latex_name=None): INPUT: - ``others`` -- an iterable of :class:`ManifoldSubset` instances - of the same manifold. + of the same manifold - ``name`` -- (default: ``None``) name given to the intersection; the default is ``self._name`` inter [...] inter ``last_other._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the intersection; the default is built upon the symbol `\cap` EXAMPLES:: @@ -2360,7 +2316,6 @@ def _intersection_subset(self, *others, name=None, latex_name=None): Subset B1_inter_B2 of the 2-dimensional topological manifold M sage: B1._intersection_subset(B2, B3) Subset B1_inter_B2_inter_B3 of the 2-dimensional topological manifold M - """ subsets = ManifoldSubsetFiniteFamily.from_subsets_or_families(self, *others) if latex_name is None: @@ -2396,7 +2351,7 @@ def union(self, *others, name=None, latex_name=None): - ``name`` -- (default: ``None``) name given to the union in the case the latter has to be created; the default is ``self._name`` union ``other._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the union in the case the latter has to be created; the default is built upon the symbol `\cup` @@ -2486,7 +2441,6 @@ def label(element): sage: e = a.subset('E') sage: d.union(e).is_subset(a) True - """ subsets = ManifoldSubsetFiniteFamily.from_subsets_or_families(self, *others) subsets = self._reduce_union_members(subsets) @@ -2515,7 +2469,7 @@ def _reduce_union_members(subsets): INPUT: - ``subsets`` -- an iterable of :class:`ManifoldSubset` instances - of the same manifold. + of the same manifold EXAMPLES:: @@ -2530,7 +2484,6 @@ def _reduce_union_members(subsets): Set {B1_union_B2} of subsets of the 2-dimensional topological manifold M sage: M._reduce_union_members([A, B1, B2]) Set {A} of subsets of the 2-dimensional topological manifold M - """ subsets = set(subsets) @@ -2569,7 +2522,7 @@ def _union_subset(self, other, name=None, latex_name=None): - ``other`` -- an instance of :class:`ManifoldSubset` - ``name`` -- (default: ``None``) name given to the union; the default is ``self._name`` union ``other._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the union; the default is built upon the symbol `\cup` EXAMPLES:: @@ -2579,7 +2532,6 @@ def _union_subset(self, other, name=None, latex_name=None): sage: B2 = M.subset('B2') sage: B1._union_subset(B2) Subset B1_union_B2 of the 2-dimensional topological manifold M - """ if latex_name is None: if name is None: @@ -2626,11 +2578,11 @@ def complement(self, superset=None, name=None, latex_name=None, is_open=False): - ``name`` -- (default: ``None``) name given to the complement in the case the latter has to be created; the default is ``superset._name`` minus ``self._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the complement in the case the latter has to be created; the default is built upon the symbol `\setminus` - - ``is_open`` -- (default: ``False``) if ``True``, the created subset - is assumed to be open with respect to the manifold's topology + - ``is_open`` -- boolean (default: ``False``); if ``True``, the created + subset is assumed to be open with respect to the manifold's topology OUTPUT: @@ -2660,7 +2612,6 @@ def complement(self, superset=None, name=None, latex_name=None, is_open=False): Open subset M_minus_A of the 2-dimensional topological manifold M sage: A.is_closed() True - """ if superset is None: superset = self.manifold() @@ -2680,11 +2631,11 @@ def difference(self, other, name=None, latex_name=None, is_open=False): - ``name`` -- (default: ``None``) name given to the difference in the case the latter has to be created; the default is ``self._name`` minus ``other._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the difference in the case the latter has to be created; the default is built upon the symbol `\setminus` - - ``is_open`` -- (default: ``False``) if ``True``, the created subset - is assumed to be open with respect to the manifold's topology + - ``is_open`` -- boolean (default: ``False``); if ``True``, the created + subset is assumed to be open with respect to the manifold's topology OUTPUT: @@ -2725,7 +2676,6 @@ def difference(self, other, name=None, latex_name=None, is_open=False): sage: O.is_closed() and O.is_open() True - """ # See if it has been created already diffs = [] @@ -2771,7 +2721,7 @@ def closure(self, name=None, latex_name=None): - ``name`` -- (default: ``None``) name given to the difference in the case the latter has to be created; the default prepends ``cl_`` to ``self._name`` - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the difference in the case the latter has to be created; the default is built upon the operator `\mathrm{cl}` @@ -2801,7 +2751,6 @@ def closure(self, name=None, latex_name=None): Open subset D1 of the 2-dimensional topological manifold R^2 sage: D1.closure().is_subset(D2.closure()) True - """ if self.is_closed(): return self diff --git a/src/sage/manifolds/subsets/closure.py b/src/sage/manifolds/subsets/closure.py index 922d77ba263..9be9f7f9939 100644 --- a/src/sage/manifolds/subsets/closure.py +++ b/src/sage/manifolds/subsets/closure.py @@ -27,8 +27,8 @@ class ManifoldSubsetClosure(ManifoldSubset): - ``subset`` -- a :class:`~sage.manifolds.subset.ManifoldSubset` - ``name`` -- (default: computed from the name of the subset) string; name (symbol) given to the closure - - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to - denote the subset; if none is provided, it is set to ``name`` + - ``latex_name`` -- string (default: ``None``); LaTeX symbol to + denote the subset. If none is provided, it is set to ``name``. EXAMPLES:: @@ -54,7 +54,6 @@ class ManifoldSubsetClosure(ManifoldSubset): sage: S.declare_closed() sage: cl_D.is_subset(S) True - """ def __init__(self, subset, name=None, latex_name=None): @@ -78,7 +77,6 @@ def __init__(self, subset, name=None, latex_name=None): False sage: cl_D == also_cl_D False - """ self._subset = subset base_manifold = subset.manifold() @@ -127,6 +125,5 @@ def is_closed(self): Topological closure cl_D of the Open subset D of the 2-dimensional topological manifold R^2 sage: cl_D.is_closed() True - """ return True diff --git a/src/sage/manifolds/subsets/pullback.py b/src/sage/manifolds/subsets/pullback.py index 95518f2ef0e..d62f9936368 100644 --- a/src/sage/manifolds/subsets/pullback.py +++ b/src/sage/manifolds/subsets/pullback.py @@ -35,7 +35,6 @@ class ManifoldSubsetPullback(ManifoldSubset): - """ Manifold subset defined as a pullback of a subset under a continuous map. @@ -104,8 +103,8 @@ class ManifoldSubsetPullback(ManifoldSubset): Using the embedding map of a submanifold:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological"); N + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological'); N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M sage: CM. = M.chart() @@ -134,7 +133,6 @@ class ManifoldSubsetPullback(ManifoldSubset): embedded in the 3-dimensional topological manifold M sage: N.point((2,0)) in D False - """ @staticmethod def __classcall_private__(cls, map, codomain_subset, inverse=None, @@ -154,7 +152,6 @@ def __classcall_private__(cls, map, codomain_subset, inverse=None, Subset x_y_inv_P of the 2-dimensional topological manifold R^2 sage: S is ManifoldSubsetPullback(c_cart, P) True - """ try: @@ -291,7 +288,6 @@ def _is_open(codomain_subset): A 2-dimensional polyhedron in QQ^2 defined as the convex hull of 1 point, 3 closure_points sage: ManifoldSubsetPullback._is_open(T) False - """ if isinstance(codomain_subset, ManifoldSubset): @@ -361,7 +357,6 @@ def _interval_restriction(expr, interval): () sage: _interval_restriction(t^2, RealSet.unbounded_above_closed(0)[0]) [] - """ conjunction = [] @@ -428,7 +423,6 @@ def _realset_restriction(expr, realset): () sage: _realset_restriction(t, RealSet([-5, -4], (-1, 1), [3, 4], [6, 7])) ([t > -1, t < 1], [t >= 3, t <= 4]) - """ disjunction = [] for interval in realset: @@ -453,7 +447,7 @@ def _polyhedron_restriction(expr, polyhedron, relint=False): - ``expr`` -- a symbolic expression - ``polyhedron`` -- an instance of :class:`~sage.geometry.polyhedron.base.Polyhedron_base` - - ``relint`` -- whether the restriction should use the relative interior. + - ``relint`` -- whether the restriction should use the relative interior OUTPUT: @@ -501,12 +495,13 @@ def _coord_def(map, codomain_subset): INPUT: - - ``map`` -- an instance of :class:`ScalarField` or :class:`Chart`. + - ``map`` -- an instance of :class:`ScalarField` or :class:`Chart` - - ``codomain_subset`` -- if ``map`` is a :class:`ScalarField`, an instance of :class:`RealSet`; - if ``map`` is a :class:`Chart`, the relative interior of a polyhedron. + - ``codomain_subset`` -- if ``map`` is a :class:`ScalarField`, an + instance of :class:`RealSet`; if ``map`` is a :class:`Chart`, the + relative interior of a polyhedron - For other inputs, a :class:`NotImplementedError` will be raised. + For other inputs, a :exc:`NotImplementedError` will be raised. OUTPUT: @@ -536,7 +531,6 @@ def _coord_def(map, codomain_subset): (1, 4) sage: _coord_def(r_squared, I) {Chart (R^2, (x, y)): [x^2 + y^2 > 1, x^2 + y^2 < 4]} - """ if isinstance(map, ScalarField) and isinstance(codomain_subset, RealSet): @@ -574,7 +568,6 @@ def __init__(self, map, codomain_subset, inverse, name, latex_name): sage: cl_O = ManifoldSubsetPullback(r_squared, cl_I); cl_O Subset f_inv_[1, 4] of the 2-dimensional topological manifold R^2 sage: TestSuite(cl_O).run(skip='_test_elements') - """ if inverse is None and isinstance(map, Chart): chart = map @@ -814,7 +807,6 @@ def is_closed(self): Subset McF of the 2-dimensional topological manifold R^2 sage: McF.is_closed() True - """ if self.manifold().dimension() == 0: return True @@ -878,7 +870,6 @@ def closure(self, name=None, latex_name=None): Subset f_inv_[1, 2] of the 2-dimensional topological manifold R^2 sage: cl_O.is_closed() True - """ if self.is_closed(): return self diff --git a/src/sage/manifolds/topological_submanifold.py b/src/sage/manifolds/topological_submanifold.py index 2333e29fd06..a99e6d1fca1 100644 --- a/src/sage/manifolds/topological_submanifold.py +++ b/src/sage/manifolds/topological_submanifold.py @@ -123,8 +123,8 @@ class TopologicalSubmanifold(TopologicalManifold): Let `N` be a 2-dimensional submanifold of a 3-dimensional manifold `M`:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M @@ -173,7 +173,6 @@ class TopologicalSubmanifold(TopologicalManifold): .. SEEALSO:: :mod:`~sage.manifolds.manifold` - """ def __init__(self, n, name, field, structure, ambient=None, base_manifold=None, latex_name=None, start_index=0, @@ -183,12 +182,11 @@ def __init__(self, n, name, field, structure, ambient=None, TESTS:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M - """ TopologicalManifold.__init__(self, n, name, field, structure, base_manifold=base_manifold, @@ -215,7 +213,6 @@ def _init_immersion(self, ambient=None): sage: M = Manifold(2, 'M', structure='topological') sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: N._init_immersion(ambient=M) - """ self._immersion = None self._immersion_inv = None @@ -244,8 +241,8 @@ def _repr_(self): TESTS:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M @@ -254,7 +251,6 @@ def _repr_(self): sage: N 2-dimensional topological submanifold N embedded in the 3-dimensional topological manifold M - """ if self is not self._manifold: return "Open subset {} of the {}".format(self._name, self._manifold) @@ -282,7 +278,7 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): INPUT: - ``name`` -- name given to the open subset - - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote + - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the subset; if none are provided, it is set to ``name`` - ``coord_def`` -- (default: {}) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -291,14 +287,12 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): - ``supersets`` -- (default: only ``self``) list of sets that the new open subset is a subset of - OUTPUT: - - - the open subset, as an instance of :class:`TopologicalSubmanifold` + OUTPUT: the open subset, as an instance of :class:`TopologicalSubmanifold` EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological"); N + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological'); N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M sage: S = N.subset('S'); S @@ -323,7 +317,6 @@ def open_subset(self, name, latex_name=None, coord_def={}, supersets=None): Open subset O of the 2-dimensional topological submanifold N embedded in the 3-dimensional topological manifold M - """ resu = TopologicalSubmanifold(self._dim, name, self._field, self._structure, self._ambient, @@ -343,7 +336,7 @@ def _init_open_subset(self, resu, coord_def): INPUT: - ``resu`` -- an instance of :class:`TopologicalManifold` or - a subclass. + a subclass - ``coord_def`` -- (default: ``{}``) definition of the subset in terms of coordinates; ``coord_def`` must a be dictionary with keys @@ -352,8 +345,8 @@ def _init_open_subset(self, resu, coord_def): EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: phi = N.continuous_map(M) sage: N.set_embedding(phi) sage: N @@ -413,8 +406,8 @@ def set_immersion(self, phi, inverse=None, var=None, EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M @@ -435,7 +428,6 @@ def set_immersion(self, phi, inverse=None, var=None, (x, y, z) ↦ -x^2 - y^2 + z sage: N.set_immersion(phi, inverse=phi_inv, var=t, ....: t_inverse={t: phi_inv_t}) - """ if not isinstance(phi, ContinuousMap): raise TypeError("the argument phi must be a continuous map") @@ -482,8 +474,8 @@ def declare_embedding(self): EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M @@ -504,7 +496,6 @@ def declare_embedding(self): True sage: N._embedded True - """ if not self._immersed: raise ValueError("please declare an embedding using set_immersion " @@ -539,8 +530,8 @@ def set_embedding( EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M @@ -567,7 +558,6 @@ def set_embedding( sage: N 2-dimensional topological submanifold N embedded in the 3-dimensional topological manifold M - """ self.set_immersion(phi, inverse, var, t_inverse) self.declare_embedding() @@ -606,15 +596,13 @@ def adapted_chart(self, postscript=None, latex_postscript=None): of the parameters `(t_1,\ldots,t_{m-n})`, If ``None``, ``"_" + self.ambient()._latex_()`` is used - OUTPUT: - - - list of adapted charts on `M` created from the charts of ``self`` + OUTPUT: list of adapted charts on `M` created from the charts of ``self`` EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological", + sage: M = Manifold(3, 'M', structure='topological', ....: latex_name=r"\mathcal{M}") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M @@ -645,7 +633,6 @@ def adapted_chart(self, postscript=None, latex_postscript=None): [Chart (M, (u1, v1, t1))] sage: latex(_) \left[\left(\mathcal{M},({{u}_1}, {{v}_1}, {{t}_1})\right)\right] - """ if not self._embedded: raise ValueError("an embedding is required") @@ -730,7 +717,7 @@ def plot(self, param, u, v, chart1=None, chart2=None, **kwargs): INPUT: - ``param`` -- dictionary of values indexed by the free variables - appearing in the foliation. + appearing in the foliation - ``u`` -- iterable of the values taken by the first coordinate of the surface to plot - ``v`` -- iterable of the values taken by the second coordinate of the @@ -744,8 +731,8 @@ def plot(self, param, u, v, chart1=None, chart2=None, **kwargs): EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient = M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient = M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart() sage: t = var('t') @@ -769,8 +756,8 @@ def plot(self, param, u, v, chart1=None, chart2=None, **kwargs): .. PLOT:: - M = Manifold(3, 'M', structure="topological") - N = Manifold(2, 'N', ambient = M, structure="topological") + M = Manifold(3, 'M', structure='topological') + N = Manifold(2, 'N', ambient = M, structure='topological') CM = M.chart('x y z'); x, y, z = CM[:] CN = N.chart('u v'); u, v = CN[:] t = var('t') @@ -793,7 +780,6 @@ def plot(self, param, u, v, chart1=None, chart2=None, **kwargs): .. SEEALSO:: :class:`~sage.plot.plot3d.parametric_surface.ParametricSurface` - """ if self._dim != 2 or self._ambient._dim != 3: @@ -817,8 +803,8 @@ def ambient(self) -> TopologicalManifold: EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: N.ambient() 3-dimensional topological manifold M """ @@ -830,8 +816,8 @@ def immersion(self) -> ContinuousMap: EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart() sage: t = var('t') @@ -844,7 +830,6 @@ def immersion(self) -> ContinuousMap: Continuous map from the 2-dimensional topological submanifold N immersed in the 3-dimensional topological manifold M to the 3-dimensional topological manifold M - """ if not self._immersed: raise ValueError("the submanifold is not immersed") @@ -857,8 +842,8 @@ def embedding(self) -> ContinuousMap: EXAMPLES:: - sage: M = Manifold(3, 'M', structure="topological") - sage: N = Manifold(2, 'N', ambient=M, structure="topological") + sage: M = Manifold(3, 'M', structure='topological') + sage: N = Manifold(2, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart() sage: t = var('t') @@ -871,7 +856,6 @@ def embedding(self) -> ContinuousMap: Continuous map from the 2-dimensional topological submanifold N embedded in the 3-dimensional topological manifold M to the 3-dimensional topological manifold M - """ if not self._embedded: raise ValueError("the submanifold is not embedded") @@ -886,8 +870,8 @@ def as_subset(self): EXAMPLES:: - sage: M = Manifold(2, 'M', structure="topological") - sage: N = Manifold(1, 'N', ambient=M, structure="topological") + sage: M = Manifold(2, 'M', structure='topological') + sage: N = Manifold(1, 'N', ambient=M, structure='topological') sage: CM. = M.chart() sage: CN. = N.chart(coord_restrictions=lambda u: [u > -1, u < 1]) sage: phi = N.continuous_map(M, {(CN,CM): [u, u^2]}) @@ -900,6 +884,5 @@ def as_subset(self): from the 1-dimensional topological submanifold N embedded in the 2-dimensional topological manifold M to the 2-dimensional topological manifold M - """ return self.embedding().image() diff --git a/src/sage/manifolds/trivialization.py b/src/sage/manifolds/trivialization.py index 7e822c86e5d..940ce857132 100644 --- a/src/sage/manifolds/trivialization.py +++ b/src/sage/manifolds/trivialization.py @@ -120,7 +120,6 @@ class Trivialization(UniqueRepresentation, SageObject): [0, 1] sage: fU[1].comp(fV.restrict(W))[:] [1, 0] - """ def __init__(self, vector_bundle, name, domain, latex_name=None): @@ -133,7 +132,6 @@ def __init__(self, vector_bundle, name, domain, latex_name=None): sage: E = M.vector_bundle(2, 'E') sage: phi = E.trivialization('phi') sage: TestSuite(phi).run() - """ self._name = name if latex_name is None: @@ -162,7 +160,6 @@ def _repr_(self): sage: phi = E.trivialization('phi', domain=M) sage: phi._repr_() 'Trivialization (phi, E|_M)' - """ desc = "Trivialization (" desc += self._name + ", " @@ -180,7 +177,6 @@ def _latex_(self): sage: phi = E.trivialization('phi', domain=M, latex_name=r'\varphi') sage: phi._latex_() '\\varphi : E |_{M} \\to M \\times \\Bold{R}^1' - """ latex = self._latex_name + r' : ' latex += r'{} |_{{{}}} \to {} \times {}^{}'.format(self._vbundle._latex_name, @@ -200,7 +196,6 @@ def base_space(self): sage: phi = E.trivialization('phi', domain=U) sage: phi.base_space() 2-dimensional topological manifold M - """ return self._base_space @@ -230,7 +225,6 @@ def transition_map(self, other, transf, compute_inverse=True): sage: phi_U.transition_map(phi_V, 1) Transition map from Trivialization (phi_U, E|_U) to Trivialization (phi_V, E|_V) - """ return TransitionMap(self, other, transf, compute_inverse=compute_inverse) @@ -248,7 +242,6 @@ def vector_bundle(self): sage: phi.vector_bundle() Topological real vector bundle E -> M of rank 2 over the base space 2-dimensional topological manifold M - """ return self._vbundle @@ -264,7 +257,6 @@ def domain(self): sage: phi = E.trivialization('phi', domain=U) sage: phi.domain() Open subset U of the 2-dimensional topological manifold M - """ return self._domain @@ -287,7 +279,6 @@ def frame(self): sage: phi = E.trivialization('phi') sage: phi.frame() Trivialization frame (E|_M, ((phi^*e_1),(phi^*e_2))) - """ return self._frame @@ -306,7 +297,6 @@ def coframe(self): sage: phi = E.trivialization('phi') sage: phi.coframe() Trivialization coframe (E|_M, ((phi^*e^1),(phi^*e^2))) - """ return self._frame._coframe @@ -344,7 +334,7 @@ class TransitionMap(SageObject): or coordinate functions (:class:`~sage.manifolds.chart_func.ChartFunction`), or a bundle automorphism (:class:`~sage.tensor.modules.free_module_automorphism.FreeModuleAutomorphism`) - - ``compute_inverse`` -- (default: ``True``) determines whether the inverse + - ``compute_inverse`` -- boolean (default: ``True``); determines whether the inverse shall be computed or not EXAMPLES: @@ -369,7 +359,6 @@ class TransitionMap(SageObject): sage: phi_U_to_phi_V Transition map from Trivialization (phi_U, E|_U) to Trivialization (phi_V, E|_V) - """ def __init__(self, triv1, triv2, transf, compute_inverse=True): r""" @@ -392,7 +381,6 @@ def __init__(self, triv1, triv2, transf, compute_inverse=True): sage: phi_V = E.trivialization('phi_V', domain=V) sage: phi_U_to_phi_V = phi_U.transition_map(phi_V, [[0,1],[1,0]]) sage: TestSuite(phi_U_to_phi_V).run() - """ bs1 = triv1.base_space() bs2 = triv2.base_space() @@ -462,7 +450,6 @@ def _repr_(self): sage: phi_U_to_phi_V # indirect doctest Transition map from Trivialization (phi_U, E|_U) to Trivialization (phi_V, E|_V) - """ desc = "Transition map from {} to {}".format(self._triv1, self._triv2) return desc @@ -491,7 +478,6 @@ def _latex_(self): sage: latex(phi_U_to_phi_V) \varphi_V\circ \varphi_U^{-1}:U\cap V\times \Bold{R}^2 \to U\cap V\times \Bold{R}^2 - """ vspace_lname = r'\times {}^{}'.format(self._triv1._base_field._latex_(), self._bdl_rank) @@ -552,7 +538,6 @@ def automorphism(self): sage: aut.display(phi_U.frame().restrict(W)) phi_U^(-1)*phi_V = (phi_U^*e_1)⊗(phi_U^*e^2) + (phi_U^*e_2)⊗(phi_U^*e^1) - """ return self._automorphism @@ -577,7 +562,6 @@ def inverse(self): Transition map from Trivialization (phi_V, E|_V) to Trivialization (phi_U, E|_U) sage: phi_V_to_phi_U.automorphism() == phi_U_to_phi_V.automorphism().inverse() True - """ if self._inverse is None: self._vbundle.set_change_of_frame(self._frame1, self._frame2, @@ -592,9 +576,7 @@ def det(self): r""" Return the determinant of ``self``. - OUTPUT: - - - An instance of :class:`~sage.manifolds.scalarfield.ScalarField`. + OUTPUT: an instance of :class:`~sage.manifolds.scalarfield.ScalarField` EXAMPLES:: @@ -623,7 +605,6 @@ def det(self): det(phi_U^(-1)*phi_V): W → ℝ (x, y) ↦ -1 (u, v) ↦ -1 - """ aut = self._automorphism det = aut.det() @@ -688,7 +669,6 @@ def matrix(self): zero: W → ℝ (x, y) ↦ 0 (u, v) ↦ 0 - """ return self._automorphism.matrix(self._frame1) @@ -719,7 +699,6 @@ def __eq__(self, other): sage: phi_U_to_psi_V = phi_U.transition_map(psi_V, [[1,2],[3,-2]]) sage: phi_U_to_phi_V == phi_U_to_psi_V False - """ if other is self: return True @@ -747,6 +726,5 @@ def __ne__(self, other): sage: phi_U_to_phi_V_1 = phi_U.transition_map(phi_V, [[1,2],[2,-1]]) sage: phi_U_to_phi_V != phi_U_to_phi_V_1 True - """ return not (self == other) diff --git a/src/sage/manifolds/utilities.py b/src/sage/manifolds/utilities.py index 2ede73552da..b51b7ace03d 100644 --- a/src/sage/manifolds/utilities.py +++ b/src/sage/manifolds/utilities.py @@ -118,7 +118,6 @@ class SimplifySqrtReal(ExpressionTreeWalker): :func:`simplify_sqrt_real` for more examples with :class:`SimplifySqrtReal` at work. - """ def arithmetic(self, ex, operator): r""" @@ -159,7 +158,6 @@ def arithmetic(self, ex, operator): sage: a = x + 1 + sqrt(function('f')(x)^2) sage: s.arithmetic(a, a.operator()) x + abs(f(x)) + 1 - """ if operator is _pow: operands = ex.operands() @@ -263,7 +261,6 @@ class SimplifyAbsTrig(ExpressionTreeWalker): :func:`simplify_abs_trig` for more examples with :class:`SimplifyAbsTrig` at work. - """ def composition(self, ex, operator): r""" @@ -311,7 +308,6 @@ def composition(self, ex, operator): sage: a = abs(sin(cos(x))) # not simplifiable sage: s.composition(a, a.operator()) abs(sin(cos(x))) - """ if operator is abs_symbolic: argum = ex.operands()[0] # argument of abs @@ -405,7 +401,6 @@ def simplify_sqrt_real(expr): sage: simplify_sqrt_real( sqrt(x^3*diff(f(g(x)), x)^2) ) # x<0 (-x)^(3/2)*abs(D[0](f)(g(x)))*abs(diff(g(x), x)) sage: forget() # for doctests below - """ w0 = SR.wild() one_half = Rational((1,2)) @@ -495,7 +490,6 @@ def simplify_abs_trig(expr): sage: simplify_abs_trig(s) abs(sin(x))*D[0](f)(y^2) + cos(y) sage: forget() # for doctests below - """ w0 = SR.wild() if expr.has(abs_symbolic(sin(w0))) or expr.has(abs_symbolic(cos(w0))): @@ -594,7 +588,6 @@ def simplify_chain_real(expr): TESTS:: sage: forget() # for doctests below - """ if expr.number_of_operands() == 0: return expr @@ -669,7 +662,6 @@ def simplify_chain_generic(expr): TESTS:: sage: forget() # for doctests below - """ if expr.number_of_operands() == 0: return expr @@ -732,7 +724,6 @@ def simplify_chain_generic_sympy(expr): sage: s = (cos(2*x) - 2*cos(x)^2 + 1)._sympy_() sage: simplify_chain_generic_sympy(s) 0 - """ expr = expr.combsimp() expr = expr.trigsimp() @@ -796,7 +787,6 @@ def simplify_chain_real_sympy(expr): sage: s = (cos(y)^2 + sin(y)^2)._sympy_() sage: simplify_chain_real_sympy(s) 1 - """ # TODO: introduce pure SymPy functions instead of simplify_sqrt_real and # simplify_abs_trig @@ -907,7 +897,6 @@ class ExpressionNice(Expression): f(x, y)*(d(f)/dy)^2 sage: latex(ExpressionNice(fun)) f\left(x, y\right) \left(\frac{\partial\,f}{\partial y}\right)^{2} - """ def __init__(self, ex): r""" @@ -923,7 +912,6 @@ def __init__(self, ex): sage: df_nice = ExpressionNice(df) sage: df_nice d(f)/dx - """ from sage.symbolic.ring import SR self._parent = SR @@ -952,7 +940,6 @@ def _repr_(self): sage: ExpressionNice(function('f')(x+y, x-y).diff(y)) d(f)/d(x + y) - d(f)/d(x - y) - """ d = self._parent._repr_element_(self) @@ -1051,7 +1038,6 @@ def _latex_(self): sage: latex(ExpressionNice(function('f')(x+y, x-y).diff(y))) \frac{\partial\,f}{\partial \left( x + y \right)} - \frac{\partial\,f}{\partial \left( x - y \right)} - """ from sage.misc.latex import latex @@ -1150,7 +1136,6 @@ def _list_derivatives(ex, list_d, exponent=0): sage: _list_derivatives(df, list_d) sage: list_d [(diff(f_x(x), x), 'f_x', {\cal F}, [0], [x], 2)] - """ op = ex.operator() operands = ex.operands() @@ -1213,7 +1198,6 @@ def _list_functions(ex, list_f): sage: list_f [(f, 'f', '(x, y)', {\cal F}, \left(x, y\right)), (g_x, 'g_x', '(x, y)', 'g_{x}', \left(x, y\right))] - """ op = ex.operator() operands = ex.operands() @@ -1263,9 +1247,7 @@ def set_axes_labels(graph, xlabel, ylabel, zlabel, **kwds): - ``zlabel`` -- string for the z-axis label - ``**kwds`` -- options (e.g. color) for text3d - OUTPUT: - - - the 3D graphic object with text3d labels added + OUTPUT: the 3D graphic object with text3d labels added EXAMPLES:: @@ -1278,7 +1260,6 @@ def set_axes_labels(graph, xlabel, ylabel, zlabel, **kwds): sage: ga.all # the 3D frame has now axes labels [Graphics3d Object, Graphics3d Object, Graphics3d Object, Graphics3d Object] - """ from sage.plot.plot3d.shapes2 import text3d xmin, ymin, zmin = graph.bounding_box()[0] @@ -1353,7 +1334,6 @@ def exterior_derivative(form): :class:`sage.manifolds.differentiable.diff_form.DiffFormParal.exterior_derivative` or :class:`sage.manifolds.differentiable.diff_form.DiffForm.exterior_derivative` for more examples. - """ return form.exterior_derivative() diff --git a/src/sage/manifolds/vector_bundle.py b/src/sage/manifolds/vector_bundle.py index e122cdf1125..fa2d277d012 100644 --- a/src/sage/manifolds/vector_bundle.py +++ b/src/sage/manifolds/vector_bundle.py @@ -188,7 +188,6 @@ class TopologicalVectorBundle(CategoryObject, UniqueRepresentation): the real vector bundle E of rank 2 sage: s in E.section_module() True - """ def __init__(self, rank, name, base_space, field='real', latex_name=None, category=None, unique_tag=None): @@ -202,7 +201,6 @@ def __init__(self, rank, name, base_space, field='real', sage: TopologicalVectorBundle(2, 'E', M) Topological real vector bundle E -> M of rank 2 over the base space 2-dimensional topological manifold M - """ if base_space is None: raise ValueError("a base space must be provided") @@ -265,7 +263,6 @@ def _init_attributes(self): sage: M = Manifold(2, 'M', structure='topological') sage: E = M.vector_bundle(2, 'E') sage: E._init_attributes() - """ self._section_modules = {} # dict of section modules with domains as # keys @@ -289,7 +286,6 @@ def base_space(self): sage: E = M.vector_bundle(2, 'E') sage: E.base_space() 2-dimensional topological manifold M - """ return self._base_space @@ -299,12 +295,11 @@ def base_field_type(self): OUTPUT: - - a string describing the field, with three possible values: + A string describing the field, with three possible values: - - ``'real'`` for the real field `\RR` - - ``'complex'`` for the complex field `\CC` - - ``'neither_real_nor_complex'`` for a field different - from `\RR` and `\CC` + - ``'real'`` for the real field `\RR` + - ``'complex'`` for the complex field `\CC` + - ``'neither_real_nor_complex'`` for a field different from `\RR` and `\CC` EXAMPLES:: @@ -312,7 +307,6 @@ def base_field_type(self): sage: E = M.vector_bundle(2, 'E', field=CC) sage: E.base_field_type() 'complex' - """ return self._field_type @@ -320,9 +314,7 @@ def base_field(self): r""" Return the field on which the fibers are defined. - OUTPUT: - - - a topological field + OUTPUT: a topological field EXAMPLES:: @@ -330,7 +322,6 @@ def base_field(self): sage: E = M.vector_bundle(2, 'E', field=CC) sage: E.base_field() Complex Field with 53 bits of precision - """ return self._field @@ -344,7 +335,6 @@ def rank(self): sage: E = M.vector_bundle(3, 'E') sage: E.rank() 3 - """ return self._rank @@ -359,7 +349,6 @@ def _repr_object_name(self): sage: E._repr_object_name() 'real vector bundle E -> M of rank 1 over the base space 2-dimensional topological manifold M' - """ desc = self.base_field_type() + " " desc += "vector bundle " @@ -379,7 +368,6 @@ def _repr_(self): sage: E._repr_() 'Topological real vector bundle E -> M of rank 1 over the base space 2-dimensional topological manifold M' - """ desc = "Topological " desc += self._repr_object_name() @@ -395,7 +383,6 @@ def _latex_(self): sage: E = M.vector_bundle(1, 'E') sage: E._latex_() 'E\\to M' - """ latex = self._latex_name latex += r'\to ' @@ -418,7 +405,6 @@ def _add_local_frame(self, frame): sage: E._add_local_frame(e) sage: E._frames [Local frame (E|_M, (e_0,e_1)), Local frame (E|_M, (e_0,e_1))] - """ self._trivial_parts.add(frame.domain()) self._frames.append(frame) @@ -447,7 +433,6 @@ def trivialization(self, name, domain=None, latex_name=None): sage: E = M.vector_bundle(2, 'E') sage: phi = E.trivialization('phi', domain=U); phi Trivialization (phi, E|_U) - """ if domain is None: domain = self._base_space @@ -458,9 +443,7 @@ def transitions(self): r""" Return the transition maps defined over subsets of the base space. - OUTPUT: - - - dictionary of transition maps, with pairs of trivializations as keys + OUTPUT: dictionary of transition maps, with pairs of trivializations as keys EXAMPLES:: @@ -480,7 +463,6 @@ def transitions(self): (Trivialization (phi_U, E|_V), Trivialization (phi_U, E|_U)): Transition map from Trivialization (phi_U, E|_V) to Trivialization (phi_U, E|_U)} - """ return self._transitions.copy() @@ -518,7 +500,6 @@ def transition(self, triv1, triv2): sage: E.transition(phi_V, phi_U) Transition map from Trivialization (phi_V, E|_V) to Trivialization (phi_U, E|_U) - """ if (triv1, triv2) not in self._transitions: raise TypeError("the transition map from " + @@ -543,7 +524,6 @@ def atlas(self): [Trivialization (phi_U, E|_U), Trivialization (phi_V, E|_V), Trivialization (phi_M, E|_M)] - """ return list(self._atlas) # Make a (shallow) copy @@ -569,7 +549,6 @@ def is_manifestly_trivial(self): Trivialization (phi_M, E|_M) sage: E.is_manifestly_trivial() True - """ return self.base_space() in self._trivial_parts @@ -584,7 +563,7 @@ def section_module(self, domain=None, force_free=False): - ``domain`` -- (default: ``None``) the domain on which the module is defined; if ``None`` the base space is assumed - - ``force_free`` -- (default: ``False``) if set to ``True``, force + - ``force_free`` -- boolean (default: ``False``); if set to ``True``, force the construction of a *free* module (this implies that `E` is trivial) OUTPUT: @@ -655,7 +634,6 @@ def section_module(self, domain=None, force_free=False): manifold RP^1 with values in the real vector bundle E of rank 1 sage: C0_U.an_element().display(phi_U.frame()) 2 (phi_U^*e_1) - """ if domain is None: domain = self._base_space @@ -694,7 +672,6 @@ def fiber(self, point): 3-dimensional topological manifold M sage: E.fiber(p) Fiber of E at Point p on the 3-dimensional topological manifold M - """ return VectorBundleFiber(self, point) @@ -789,7 +766,6 @@ def local_frame(self, *args, **kwargs): For more options, in particular for the choice of symbols and indices, see :class:`~sage.manifolds.local_frame.LocalFrame`. - """ from sage.manifolds.local_frame import LocalFrame # Input processing @@ -864,7 +840,6 @@ def section(self, *comp, **kwargs): sage: s = E.section(name='s'); s Section s on the 2-dimensional topological manifold M with values in the real vector bundle E of rank 2 - """ domain = kwargs.pop('domain', self._base_space) name = kwargs.pop('name', None) @@ -895,7 +870,6 @@ def total_space(self): sage: E = M.vector_bundle(2, 'E') sage: E.total_space() 6-dimensional topological manifold E - """ if self._total_space is None: from sage.manifolds.manifold import Manifold @@ -926,9 +900,10 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame, :class:`~sage.tensor.modules.free_module_automorphism.FreeModuleAutomorphism` describing the automorphism `P` that relates the basis `(e_i)` to the basis `(f_i)` according to `f_i = P(e_i)` - - ``compute_inverse`` (default: ``True``) -- if set to True, the inverse - automorphism is computed and the change from basis `(f_i)` to `(e_i)` - is set to it in the internal dictionary ``self._frame_changes`` + - ``compute_inverse`` -- boolean (default: ``True``); if set to True, + the inverse automorphism is computed and the change from basis + `(f_i)` to `(e_i)` is set to it in the internal dictionary + ``self._frame_changes`` EXAMPLES:: @@ -951,7 +926,6 @@ def set_change_of_frame(self, frame1, frame2, change_of_frame, sage: E.change_of_frame(e,f)[e,:] [1 2] [0 3] - """ from sage.tensor.modules.free_module_automorphism import \ FreeModuleAutomorphism @@ -1003,7 +977,6 @@ def change_of_frame(self, frame1, frame2): True sage: a.inverse() == E.change_of_frame(f, e) True - """ if (frame1, frame2) not in self._frame_changes: raise ValueError("the change of frame from {} to {}".format(frame1, frame2) + @@ -1043,7 +1016,6 @@ def changes_of_frame(self): Local frame (E|_M, (f_0,f_1))): Automorphism of the Free module C^0(M;E) of sections on the 3-dimensional topological manifold M with values in the real vector bundle E of rank 2} - """ return self._frame_changes.copy() @@ -1051,9 +1023,7 @@ def frames(self): r""" Return the list of local frames defined on ``self``. - OUTPUT: - - - list of local frames defined on ``self`` + OUTPUT: list of local frames defined on ``self`` EXAMPLES:: @@ -1065,7 +1035,6 @@ def frames(self): sage: E.frames() [Trivialization frame (E|_U, ((phi_U^*e_1),(phi_U^*e_2))), Local frame (E|_V, (e_0,e_1))] - """ return list(self._frames) @@ -1073,9 +1042,7 @@ def coframes(self): r""" Return the list of coframes defined on ``self``. - OUTPUT: - - - list of coframes defined on ``self`` + OUTPUT: list of coframes defined on ``self`` EXAMPLES:: @@ -1087,7 +1054,6 @@ def coframes(self): sage: E.coframes() [Trivialization coframe (E|_U, ((phi_U^*e^1),(phi_U^*e^2))), Local coframe (E|_V, (e^0,e^1))] - """ return list(self._coframes) @@ -1107,7 +1073,6 @@ def default_frame(self): sage: e = E.local_frame('e') sage: E.default_frame() Local frame (E|_M, (e_0,e_1)) - """ return self._def_frame @@ -1131,7 +1096,6 @@ def set_default_frame(self, frame): sage: E.set_default_frame(f) sage: E.default_frame() Local frame (E|_M, (f_0,f_1)) - """ from sage.manifolds.local_frame import LocalFrame if not isinstance(frame, LocalFrame): @@ -1188,7 +1152,6 @@ def set_orientation(self, orientation): sage: E.orientation() [Local frame (E|_U, (e_0,e_1)), Local frame (E|_V, (f_0,f_1))] - """ from .local_frame import LocalFrame if isinstance(orientation, LocalFrame): @@ -1268,7 +1231,6 @@ def orientation(self): sage: E.orientation() [Local frame (E|_U, (e_0,e_1)), Local frame (E|_V, (f_0,f_1))] - """ if not self._orientation: # Trivial case: @@ -1324,7 +1286,6 @@ def has_orientation(self): sage: E.set_orientation([e, f]) sage: E.has_orientation() True - """ return bool(self.orientation()) @@ -1369,7 +1330,6 @@ def irange(self, start=None): sage: next(E.irange()) == M.start_index() True - """ si = self._base_space._sindex imax = self._rank + si diff --git a/src/sage/manifolds/vector_bundle_fiber.py b/src/sage/manifolds/vector_bundle_fiber.py index 19b5c6f6acb..da255d46fd7 100644 --- a/src/sage/manifolds/vector_bundle_fiber.py +++ b/src/sage/manifolds/vector_bundle_fiber.py @@ -156,7 +156,6 @@ class VectorBundleFiber(FiniteRankFreeModule): :class:`~sage.tensor.modules.finite_rank_free_module.FiniteRankFreeModule` for more documentation. - """ Element = VectorBundleFiberElement @@ -173,7 +172,6 @@ def __init__(self, vector_bundle, point): sage: e = E.local_frame('e') sage: Ep = E.fiber(p) sage: TestSuite(Ep).run() - """ if point._manifold is not vector_bundle._base_space: raise ValueError("Point must be an element " @@ -266,7 +264,6 @@ def _repr_(self): sage: E = M.vector_bundle(2, 'E') sage: E.fiber(p)._repr_() 'Fiber of E at Point p on the 3-dimensional topological manifold M' - """ return "Fiber of {} at {}".format(self._vbundle._name, self._point) @@ -284,7 +281,6 @@ def dimension(self): sage: Ep = E.fiber(p) sage: Ep.dim() 2 - """ # The dimension is the rank of self as a free module: return self._rank @@ -308,7 +304,6 @@ def _an_element_(self): manifold M sage: Ep._an_element_().display() e_0 + 2 e_1 - """ resu = self.element_class(self) if self._def_basis is not None: @@ -331,6 +326,5 @@ def base_point(self): Point p on the 2-dimensional topological manifold M sage: p is Ep.base_point() True - """ return self._point diff --git a/src/sage/manifolds/vector_bundle_fiber_element.py b/src/sage/manifolds/vector_bundle_fiber_element.py index 3cb37025ef9..19eaf08bb77 100644 --- a/src/sage/manifolds/vector_bundle_fiber_element.py +++ b/src/sage/manifolds/vector_bundle_fiber_element.py @@ -26,7 +26,7 @@ class VectorBundleFiberElement(FiniteRankFreeModuleElement): INPUT: - - parent -- :class:`~sage.manifolds.vector_bundle_fiber.VectorBundleFiber`; + - ``parent`` -- :class:`~sage.manifolds.vector_bundle_fiber.VectorBundleFiber`; the fiber to which the vector belongs - ``name`` -- (default: ``None``) string; symbol given to the vector - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote @@ -56,7 +56,6 @@ class VectorBundleFiberElement(FiniteRankFreeModuleElement): :class:`~sage.tensor.modules.free_module_element.FiniteRankFreeModuleElement` for more documentation. - """ def __init__(self, parent, name=None, latex_name=None): r""" @@ -75,7 +74,6 @@ def __init__(self, parent, name=None, latex_name=None): topological manifold M sage: v[:] = 5, -3/2 sage: TestSuite(v).run() - """ FiniteRankFreeModuleElement.__init__(self, parent, name=name, latex_name=latex_name) @@ -102,7 +100,6 @@ def _repr_(self): sage: repr(v) # indirect doctest 'Vector v in the fiber of E at Point p on the 2-dimensional topological manifold M' - """ desc = "Vector " if self._name: diff --git a/src/sage/matrix/action.pyx b/src/sage/matrix/action.pyx index 96587b99cbc..732a1312ca1 100644 --- a/src/sage/matrix/action.pyx +++ b/src/sage/matrix/action.pyx @@ -267,7 +267,6 @@ cdef class MatrixMatrixAction(MatrixMulAction): [ 5360 7303] [ 8168 11143] [11056 15077] - """ cdef Matrix A = g cdef Matrix B = s @@ -439,7 +438,7 @@ cdef class MatrixPolymapAction(MatrixMulAction): cpdef _act_(self, mat, f): """ - Call the action + Call the action. INPUT: diff --git a/src/sage/matrix/args.pxd b/src/sage/matrix/args.pxd index 8deb4d434c9..eda2e428801 100644 --- a/src/sage/matrix/args.pxd +++ b/src/sage/matrix/args.pxd @@ -88,7 +88,7 @@ cdef class MatrixArgs: value was previously set, it must remain the same. """ if n < 0: - raise ArithmeticError("number of columns must be non-negative") + raise ArithmeticError("number of columns must be nonnegative") cdef long p = self.ncols if p != -1 and p != n: raise ValueError(f"inconsistent number of columns: should be {p} " @@ -104,7 +104,7 @@ cdef class MatrixArgs: value was previously set, it must remain the same. """ if n < 0: - raise ArithmeticError("number of rows must be non-negative") + raise ArithmeticError("number of rows must be nonnegative") cdef long p = self.nrows if p != -1 and p != n: raise ValueError(f"inconsistent number of rows: should be {p} but got {n}") diff --git a/src/sage/matrix/args.pyx b/src/sage/matrix/args.pyx index 47633736f25..6d74468e179 100644 --- a/src/sage/matrix/args.pyx +++ b/src/sage/matrix/args.pyx @@ -296,7 +296,7 @@ cdef class MatrixArgs: Test invalid input:: - sage: MatrixArgs(ZZ, 2, 2, entries="abcd").finalized() + sage: MatrixArgs(ZZ, 2, 2, entries='abcd').finalized() Traceback (most recent call last): ... TypeError: unable to convert 'abcd' to a matrix @@ -473,7 +473,7 @@ cdef class MatrixArgs: def __iter__(self): """ - Default iteration (dense with conversion) + Default iteration (dense with conversion). EXAMPLES:: @@ -486,14 +486,14 @@ cdef class MatrixArgs: def iter(self, bint convert=True, bint sparse=False): """ - Iteration over the entries in the matrix + Iteration over the entries in the matrix. INPUT: - - ``convert`` -- If ``True``, the entries are converted to the - base right. If ``False``, the entries are returned as given. + - ``convert`` -- if ``True``, the entries are converted to the + base right; if ``False``, the entries are returned as given - - ``sparse`` -- See OUTPUT below. + - ``sparse`` -- see OUTPUT below OUTPUT: iterator @@ -765,7 +765,7 @@ cdef class MatrixArgs: INPUT: - - ``immutable`` -- boolean; if ``True``, the result will be immutable. + - ``immutable`` -- boolean; if ``True``, the result will be immutable OUTPUT: an element of ``self.space`` @@ -819,8 +819,8 @@ cdef class MatrixArgs: INPUT: - - ``convert`` -- If ``True``, the entries are converted to the base - ring. Otherwise, the entries are returned as given. + - ``convert`` -- if ``True``, the entries are converted to the base + ring; otherwise, the entries are returned as given .. NOTE:: @@ -881,7 +881,7 @@ cdef class MatrixArgs: """ Return the entries of the matrix as a :class:`dict`. - The keys of this :class:`dict` are the non-zero positions ``(i,j)``. The + The keys of this :class:`dict` are the nonzero positions ``(i,j)``. The corresponding value is the entry at that position. Zero values are skipped. If ``convert`` is ``True``, the entries are converted to the base diff --git a/src/sage/matrix/benchmark.py b/src/sage/matrix/benchmark.py index c3a236b21d3..8567f869511 100644 --- a/src/sage/matrix/benchmark.py +++ b/src/sage/matrix/benchmark.py @@ -39,9 +39,9 @@ def report(F, title, systems=['sage', 'magma'], **kwds): INPUT: - - ``F`` -- a list of callables used for benchmarking - - ``title`` -- a string describing this report - - ``systems`` -- a list of systems (supported entries are 'sage' and 'magma') + - ``F`` -- list of callables used for benchmarking + - ``title`` -- string describing this report + - ``systems`` -- list of systems (supported entries are 'sage' and 'magma') - ``**kwds`` -- keyword arguments passed to all functions in ``F`` EXAMPLES:: @@ -132,7 +132,7 @@ def nullspace_ZZ(n=200, min=0, max=2**32, system='sage'): - ``n`` -- matrix dimension (default: ``200``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - ``max`` -- maximal value for entries of matrix (default: ``2**32``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -172,7 +172,7 @@ def charpoly_ZZ(n=100, min=0, max=9, system='sage'): - ``n`` -- matrix dimension (default: ``100``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -212,7 +212,7 @@ def rank_ZZ(n=700, min=0, max=9, system='sage'): - ``n`` -- matrix dimension (default: ``700``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -251,7 +251,7 @@ def rank2_ZZ(n=400, min=0, max=2**64, system='sage'): - ``n`` -- matrix dimension (default: ``400``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - ``max`` -- maximal value for entries of matrix (default: ``2**64``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -292,7 +292,7 @@ def smithform_ZZ(n=128, min=0, max=9, system='sage'): - ``n`` -- matrix dimension (default: ``128``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -332,7 +332,7 @@ def matrix_multiply_ZZ(n=300, min=-9, max=9, system='sage', times=1): - ``n`` -- matrix dimension (default: ``300``) - ``min`` -- minimal value for entries of matrix (default: ``-9``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) - ``times`` -- number of experiments (default: ``1``) EXAMPLES:: @@ -377,7 +377,7 @@ def matrix_add_ZZ(n=200, min=-9, max=9, system='sage', times=50): - ``n`` -- matrix dimension (default: ``200``) - ``min`` -- minimal value for entries of matrix (default: ``-9``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) - ``times`` -- number of experiments (default: ``50``) EXAMPLES:: @@ -423,7 +423,7 @@ def matrix_add_ZZ_2(n=200, bits=16, system='sage', times=50): - ``n`` -- matrix dimension (default: ``200``) - ``bits`` -- bitsize of entries - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) - ``times`` -- number of experiments (default: ``50``) EXAMPLES:: @@ -446,7 +446,7 @@ def det_ZZ(n=200, min=1, max=100, system='sage'): - ``n`` -- matrix dimension (default: ``200``) - ``min`` -- minimal value for entries of matrix (default: ``1``) - ``max`` -- maximal value for entries of matrix (default: ``100``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -486,7 +486,7 @@ def det_QQ(n=300, num_bound=10, den_bound=10, system='sage'): - ``n`` -- matrix dimension (default: ``200``) - ``num_bound`` -- numerator bound, inclusive (default: ``10``) - ``den_bound`` -- denominator bound, inclusive (default: ``10``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -529,7 +529,7 @@ def vecmat_ZZ(n=300, min=-9, max=9, system='sage', times=200): - ``n`` -- matrix dimension (default: ``300``) - ``min`` -- minimal value for entries of matrix (default: ``-9``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) - ``times`` -- number of runs (default: ``200``) EXAMPLES:: @@ -570,7 +570,7 @@ def vecmat_ZZ(n=300, min=-9, max=9, system='sage', times=200): def report_GF(p=16411, **kwds): """ - Runs all the reports for finite field matrix operations, for + Run all the reports for finite field matrix operations, for prime p=16411. INPUT: @@ -578,7 +578,7 @@ def report_GF(p=16411, **kwds): - ``p`` -- ignored - ``**kwds`` -- passed through to :func:`report` - .. note:: + .. NOTE:: right now, even though p is an input, it is being ignored! If you need to check the performance for other primes, you can @@ -611,7 +611,7 @@ def nullspace_GF(n=300, p=16411, system='sage'): - ``n`` -- matrix dimension (default: 300) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) EXAMPLES:: @@ -651,7 +651,7 @@ def charpoly_GF(n=100, p=16411, system='sage'): - ``n`` -- matrix dimension (default: 100) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) EXAMPLES:: @@ -687,7 +687,7 @@ def matrix_add_GF(n=1000, p=16411, system='sage',times=100): - ``n`` -- matrix dimension (default: 300) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) - ``times`` -- number of experiments (default: ``100``) EXAMPLES:: @@ -733,7 +733,7 @@ def matrix_multiply_GF(n=100, p=16411, system='sage', times=3): - ``n`` -- matrix dimension (default: 100) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) - ``times`` -- number of experiments (default: ``3``) EXAMPLES:: @@ -777,7 +777,7 @@ def rank_GF(n=500, p=16411, system='sage'): - ``n`` -- matrix dimension (default: 300) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) EXAMPLES:: @@ -814,7 +814,7 @@ def rank2_GF(n=500, p=16411, system='sage'): - ``n`` -- matrix dimension (default: 300) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) EXAMPLES:: @@ -852,7 +852,7 @@ def det_GF(n=400, p=16411 , system='sage'): - ``n`` -- matrix dimension (default: 300) - ``p`` -- prime number (default: ``16411``) - - ``system`` -- either 'magma' or 'sage' (default: 'sage') + - ``system`` -- either 'magma' or 'sage' (default: ``'sage'``) EXAMPLES:: @@ -887,7 +887,7 @@ def det_GF(n=400, p=16411 , system='sage'): def hilbert_matrix(n): """ - Returns the Hilbert matrix of size n over rationals. + Return the Hilbert matrix of size n over rationals. EXAMPLES:: @@ -915,7 +915,7 @@ def echelon_QQ(n=100, min=0, max=9, system='sage'): - ``n`` -- matrix dimension (default: ``300``) - ``min`` -- minimal value for entries of matrix (default: ``-9``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -955,7 +955,7 @@ def inverse_QQ(n=100, min=0, max=9, system='sage'): - ``n`` -- matrix dimension (default: ``300``) - ``min`` -- minimal value for entries of matrix (default: ``-9``) - ``max`` -- maximal value for entries of matrix (default: ``9``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -995,7 +995,7 @@ def matrix_multiply_QQ(n=100, bnd=2, system='sage', times=1): - ``n`` -- matrix dimension (default: ``300``) - ``bnd`` -- numerator and denominator bound (default: ``bnd``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) - ``times`` -- number of experiments (default: ``1``) EXAMPLES:: @@ -1034,13 +1034,13 @@ def matrix_multiply_QQ(n=100, bnd=2, system='sage', times=1): # Determinant of Hilbert matrix def det_hilbert_QQ(n=80, system='sage'): """ - Runs the benchmark for calculating the determinant of the hilbert + Run the benchmark for calculating the determinant of the hilbert matrix over rationals of dimension n. INPUT: - ``n`` -- matrix dimension (default: ``300``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -1069,13 +1069,13 @@ def det_hilbert_QQ(n=80, system='sage'): # inverse of Hilbert matrix def invert_hilbert_QQ(n=40, system='sage'): """ - Runs the benchmark for calculating the inverse of the hilbert + Run the benchmark for calculating the inverse of the hilbert matrix over rationals of dimension n. INPUT: - ``n`` -- matrix dimension (default: ``300``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -1110,7 +1110,7 @@ def MatrixVector_QQ(n=1000,h=100,system='sage',times=1): - ``n`` -- matrix dimension (default: ``300``) - ``h`` -- numerator and denominator bound (default: ``bnd``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) - ``times`` -- number of experiments (default: ``1``) EXAMPLES:: @@ -1167,7 +1167,7 @@ def nullspace_RR(n=300, min=0, max=10, system='sage'): - ``n`` -- matrix dimension (default: ``300``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - ``max`` -- maximal value for entries of matrix (default: ``10``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: @@ -1207,8 +1207,8 @@ def nullspace_RDF(n=300, min=0, max=10, system='sage'): - ``n`` -- matrix dimension (default: ``300``) - ``min`` -- minimal value for entries of matrix (default: ``0``) - - ``max`` -- maximal value for entries of matrix (default: `10``) - - ``system`` -- either 'sage' or 'magma' (default: 'sage') + - ``max`` -- maximal value for entries of matrix (default: ``10``) + - ``system`` -- either ``'sage'`` or ``'magma'`` (default: ``'sage'``) EXAMPLES:: diff --git a/src/sage/matrix/berlekamp_massey.py b/src/sage/matrix/berlekamp_massey.py index a6fe70c50e6..e9284f3c08e 100644 --- a/src/sage/matrix/berlekamp_massey.py +++ b/src/sage/matrix/berlekamp_massey.py @@ -37,7 +37,7 @@ def berlekamp_massey(a): INPUT: - - ``a`` -- a list of even length of elements of a field (or domain) + - ``a`` -- list of even length of elements of a field (or domain) OUTPUT: diff --git a/src/sage/matrix/change_ring.pyx b/src/sage/matrix/change_ring.pyx index f942b753275..e5b5ee5c38f 100644 --- a/src/sage/matrix/change_ring.pyx +++ b/src/sage/matrix/change_ring.pyx @@ -15,10 +15,10 @@ def integer_to_real_double_dense(Matrix_integer_dense A): real double entries. INPUT: - A -- a dense matrix over the integers - OUTPUT: - -- a dense real double matrix + - ``A`` -- a dense matrix over the integers + + OUTPUT: a dense real double matrix EXAMPLES:: diff --git a/src/sage/matrix/compute_J_ideal.py b/src/sage/matrix/compute_J_ideal.py index f7005c04d31..4155745e856 100644 --- a/src/sage/matrix/compute_J_ideal.py +++ b/src/sage/matrix/compute_J_ideal.py @@ -131,7 +131,7 @@ def lifting(p, t, A, G): - ``p`` -- a prime element of some principal ideal domain `D` - - ``t`` -- a non-negative integer + - ``t`` -- nonnegative integer - ``A`` -- a `c\times d` matrix over `D[X]` @@ -243,7 +243,7 @@ def p_part(f, p): OUTPUT: A polynomial `g` such that `\deg g \le \deg f` and - all non-zero coefficients of `f - p g` are not divisible by `p`. + all nonzero coefficients of `f - p g` are not divisible by `p`. EXAMPLES:: @@ -262,7 +262,6 @@ def p_part(f, p): sage: g = p_part(X+1, 2) sage: g.parent() Univariate Polynomial Ring in X over Integer Ring - """ DX = f.parent() (X,) = DX.gens() @@ -359,9 +358,9 @@ def find_monic_replacements(self, p, t, pt_generators, prev_nu): - ``p`` -- a prime element of `D` - - ``t`` -- a non-negative integer + - ``t`` -- nonnegative integer - - ``pt_generators`` -- a list `(g_1, \ldots, g_s)` of polynomials in + - ``pt_generators`` -- list `(g_1, \ldots, g_s)` of polynomials in `D[X]` such that `N_{(p^t)}(B) = (g_1, \ldots, g_s) + pN_{(p^{t-1})}(B)` - ``prev_nu`` -- a `(p^{t-1})`-minimal polynomial of `B` @@ -438,9 +437,9 @@ def current_nu(self, p, t, pt_generators, prev_nu): - ``p`` -- a prime element of `D` - - ``t`` -- a positive integer + - ``t`` -- positive integer - - ``pt_generators`` -- a list `(g_1, \ldots, g_s)` of polynomials in + - ``pt_generators`` -- list `(g_1, \ldots, g_s)` of polynomials in `D[X]` such that `N_{(p^t)}(B) = (g_1, \ldots, g_s) + pN_{(p^{t-1})}(B)` - ``prev_nu`` -- a `(p^{t-1})`-minimal polynomial of `B` @@ -523,7 +522,7 @@ def mccoy_column(self, p, t, nu): - ``p`` -- a prime element in `D` - - ``t`` -- a positive integer + - ``t`` -- positive integer - ``nu`` -- a `(p^t)`-minimal polynomial of `B` @@ -557,7 +556,6 @@ def mccoy_column(self, p, t, nu): Traceback (most recent call last): ... ValueError: x^2 + x not in (2^2)-ideal - """ if not (nu(self._B) % p**t).is_zero(): raise ValueError( @@ -590,7 +588,7 @@ def p_minimal_polynomials(self, p, s_max=None): - ``p`` -- a prime in `D` - - ``s_max`` -- a positive integer (default: ``None``); if set, only + - ``s_max`` -- positive integer (default: ``None``); if set, only `(p^s)`-minimal polynomials for ``s <= s_max`` are computed (see below for details) @@ -813,9 +811,7 @@ def null_ideal(self, b=0): - ``b`` -- an element of `D` (default: 0) - OUTPUT: - - An ideal in `D[X]`. + OUTPUT: an ideal in `D[X]` EXAMPLES:: @@ -874,9 +870,7 @@ def prime_candidates(self): Determine those primes `p` where `\mu_B` might not be a `(p)`-minimal polynomial. - OUTPUT: - - A list of primes. + OUTPUT: list of primes EXAMPLES:: diff --git a/src/sage/matrix/constructor.pyx b/src/sage/matrix/constructor.pyx index bf19830a0ae..de060a11425 100644 --- a/src/sage/matrix/constructor.pyx +++ b/src/sage/matrix/constructor.pyx @@ -68,7 +68,7 @@ def matrix(*args, **kwds): - ``ncols`` -- the number of columns in the matrix, or a finite or enumerated family of arbitrary objects that index the columns of the matrix - - ``entries`` -- see examples below. + - ``entries`` -- see examples below If any of ``nrows``, ``ncols``, ``row_keys``, ``column_keys`` is given as keyword argument, then none of these may be given as @@ -76,7 +76,7 @@ def matrix(*args, **kwds): Keyword-only arguments: - - ``sparse`` -- (boolean) create a sparse matrix. This defaults to + - ``sparse`` -- boolean; create a sparse matrix. This defaults to ``True`` when the entries are given as a dictionary, otherwise defaults to ``False``. @@ -90,10 +90,9 @@ def matrix(*args, **kwds): matrix. This determines ``base_ring``, ``nrows``, ``row_keys``, ``ncols``, ``column_keys``, and ``sparse``. - - ``immutable`` -- (boolean) make the matrix immutable. By default, + - ``immutable`` -- boolean; make the matrix immutable. By default, the output matrix is mutable. - OUTPUT: a matrix or, more generally, a homomorphism between free modules diff --git a/src/sage/matrix/docs.py b/src/sage/matrix/docs.py index 3f70f122489..274796b1694 100644 --- a/src/sage/matrix/docs.py +++ b/src/sage/matrix/docs.py @@ -370,7 +370,7 @@ class derived from Matrix). They can be either sparse or dense, and * __dealloc__ -- use sig_free (only needed if allocate memory) * set_unsafe(self, size_t i, size_t j, x) -- doesn't do bounds or any other checks; assumes x is in self._base_ring * get_unsafe(self, size_t i, size_t j) -- doesn't do checks - * __richcmp__ -- always the same (I don't know why its needed -- bug in PYREX). + * __richcmp__ -- always the same (I don't know why its needed -- bug in PYREX) Note that the __init__ function must construct the all zero matrix if ``entries == None``. @@ -415,7 +415,7 @@ class derived from Matrix). They can be either sparse or dense, and * Other functions, e.g., transpose, for which knowing the specific representation can be helpful. - .. note:: + .. NOTE:: - For caching, use self.fetch and self.cache. diff --git a/src/sage/matrix/echelon_matrix.pyx b/src/sage/matrix/echelon_matrix.pyx index c075220152c..526900e2a72 100644 --- a/src/sage/matrix/echelon_matrix.pyx +++ b/src/sage/matrix/echelon_matrix.pyx @@ -25,13 +25,13 @@ def reduced_echelon_matrix_iterator(K, k, n, bint sparse=False, bint copy=True, - ``n`` -- number of columns (or the dimension of the ambient space) - - ``sparse`` -- boolean (default is ``False``) + - ``sparse`` -- boolean (default: ``False``) - - ``copy`` -- boolean. If set to ``False`` then iterator yields the same matrix - over and over (but with different entries). Default is ``True`` which is - safer but might be slower. + - ``copy`` -- boolean (default: ``True``); if set to ``False`` then + iterator yields the same matrix over and over (but with different + entries). Default is ``True`` which is safer but might be slower. - - ``set_immutable`` -- boolean. If set to ``True`` then the output matrices + - ``set_immutable`` -- boolean; if set to ``True`` then the output matrices are immutable. This option automatically turns ``copy`` into ``True``. diff --git a/src/sage/matrix/matrix0.pyx b/src/sage/matrix/matrix0.pyx index b792627346b..28c990d0954 100644 --- a/src/sage/matrix/matrix0.pyx +++ b/src/sage/matrix/matrix0.pyx @@ -238,7 +238,7 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``copy`` -- (default: ``True``) make a copy of the ``dict`` + - ``copy`` -- boolean (default: ``True``); make a copy of the ``dict`` corresponding to ``self`` If ``copy=True``, then is safe to change the returned dictionary. @@ -391,7 +391,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: m=Matrix(QQ,2,range(0,4)) sage: m._get_cache() {} - """ if self._cache is None: self._cache = {} @@ -404,7 +403,7 @@ cdef class Matrix(sage.structure.element.Matrix): cdef check_bounds(self, Py_ssize_t i, Py_ssize_t j): """ This function gets called when you're about to access the i,j entry - of this matrix. If i, j are out of range, an :class:`IndexError` is + of this matrix. If i, j are out of range, an :exc:`IndexError` is raised. """ if i < 0 or i >= self._nrows or j < 0 or j >= self._ncols: @@ -414,10 +413,10 @@ cdef class Matrix(sage.structure.element.Matrix): """ This function gets called when you're about to change this matrix. - If self is immutable, a :class:`ValueError` is raised, since you should + If ``self`` is immutable, a :exc:`ValueError` is raised, since you should never change a mutable matrix. - If self is mutable, the cache of results about self is deleted. + If ``self`` is mutable, the cache of results about ``self`` is deleted. """ if self._is_immutable: raise ValueError("matrix is immutable; please change a copy instead (i.e., use copy(M) to change a copy of M).") @@ -427,13 +426,13 @@ cdef class Matrix(sage.structure.element.Matrix): cdef check_bounds_and_mutability(self, Py_ssize_t i, Py_ssize_t j): """ This function gets called when you're about to set the i,j entry of - this matrix. If i or j is out of range, an :class:`IndexError` + this matrix. If i or j is out of range, an :exc:`IndexError` exception is raised. - If self is immutable, a :class:`ValueError` is raised, since you should + If ``self`` is immutable, a :exc:`ValueError` is raised, since you should never change a mutable matrix. - If self is mutable, the cache of results about self is deleted. + If ``self`` is mutable, the cache of results about ``self`` is deleted. """ if self._is_immutable: raise ValueError("matrix is immutable; please change a copy instead (i.e., use copy(M) to change a copy of M).") @@ -500,7 +499,7 @@ cdef class Matrix(sage.structure.element.Matrix): def is_immutable(self): """ - Return True if this matrix is immutable. + Return ``True`` if this matrix is immutable. See the documentation for self.set_immutable for more details about mutability. @@ -518,7 +517,7 @@ cdef class Matrix(sage.structure.element.Matrix): def is_mutable(self): """ - Return True if this matrix is mutable. + Return ``True`` if this matrix is mutable. See the documentation for self.set_immutable for more details about mutability. @@ -625,7 +624,7 @@ cdef class Matrix(sage.structure.element.Matrix): def __iter__(self): """ - Return an iterator for the rows of self. + Return an iterator for the rows of ``self``. EXAMPLES:: @@ -637,7 +636,7 @@ cdef class Matrix(sage.structure.element.Matrix): def __getitem__(self, key): """ - Return element, row, or slice of self. + Return element, row, or slice of ``self``. INPUT: @@ -1094,7 +1093,7 @@ cdef class Matrix(sage.structure.element.Matrix): - ``key`` -- any legal indexing (i.e., such that self[key] works) - - ``value`` -- values that are used to set the elements indicated by key. + - ``value`` -- values that are used to set the elements indicated by key EXAMPLES:: @@ -1581,7 +1580,7 @@ cdef class Matrix(sage.structure.element.Matrix): cdef _coerce_element(self, x): """ - Return coercion of x into the base ring of self. + Return coercion of x into the base ring of ``self``. """ if isinstance(x, Element) and ( x)._parent is self._base_ring: return x @@ -1616,7 +1615,7 @@ cdef class Matrix(sage.structure.element.Matrix): def _test_reduce(self, **options): """ - Checks that the pickling function works. + Check that the pickling function works. EXAMPLES:: @@ -1647,8 +1646,8 @@ cdef class Matrix(sage.structure.element.Matrix): Return the matrix obtained by coercing the entries of this matrix into the given ring. - Always returns a copy (unless self is immutable, in which case - returns self). + Always returns a copy (unless ``self`` is immutable, in which case + returns ``self``). EXAMPLES:: @@ -1696,7 +1695,7 @@ cdef class Matrix(sage.structure.element.Matrix): def _test_change_ring(self, **options): """ - Checks that :meth:`change_ring` works. + Check that :meth:`change_ring` works. EXAMPLES:: @@ -1765,7 +1764,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: [A]*2 [100 x 100 dense matrix over Integer Ring, 100 x 100 dense matrix over Integer Ring] - """ from sage.matrix.constructor import options if self._nrows <= options.max_rows() and self._ncols <= options.max_cols(): @@ -1820,8 +1818,8 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``rep_mapping`` -- a dictionary or callable used to override - the usual representation of elements. + - ``rep_mapping`` -- dictionary or callable used to override + the usual representation of elements If ``rep_mapping`` is a dictionary then keys should be elements of the base ring and values the desired string @@ -1848,11 +1846,11 @@ cdef class Matrix(sage.structure.element.Matrix): use the value of ``minus_one`` as the representation of the negative of the one element. - - ``unicode`` -- boolean (default: ``False``). - Whether to use Unicode symbols instead of ASCII symbols - for brackets and subdivision lines. + - ``unicode`` -- boolean (default: ``False``); + whether to use Unicode symbols instead of ASCII symbols + for brackets and subdivision lines - - ``shape`` -- one of ``"square"`` or ``"round"`` (default: ``None``). + - ``shape`` -- one of ``'square'`` or ``'round'`` (default: ``None``). Switches between round and square brackets. The default depends on the setting of the ``unicode`` keyword argument. For Unicode symbols, the default is round brackets @@ -1886,7 +1884,7 @@ cdef class Matrix(sage.structure.element.Matrix): '[ 1 0]\n[ 2 -1]' sage: M.str(plus_one='+',minus_one='-',zero='.') '[+ .]\n[2 -]' - sage: M.str({1:"not this one",2:"II"},minus_one="*",plus_one="I") + sage: M.str({1:"not this one",2:"II"},minus_one='*',plus_one='I') '[ I 0]\n[II *]' sage: def print_entry(x): @@ -1908,7 +1906,7 @@ cdef class Matrix(sage.structure.element.Matrix): ⎜4 5│6⎟ ⎝7 8│9⎠ sage: M.subdivide([0,1,1,3], [0,2,3,3]) - sage: print(M.str(unicode=True, shape="square")) + sage: print(M.str(unicode=True, shape='square')) ⎡┼───┼─┼┼⎤ ⎢│1 2│3││⎥ ⎢┼───┼─┼┼⎥ @@ -2439,15 +2437,13 @@ cdef class Matrix(sage.structure.element.Matrix): def act_on_polynomial(self, f): r""" - Return the polynomial f(self\*x). + Return the polynomial ``f(self*x)``. INPUT: - - ``self`` -- an nxn matrix + - ``self`` -- an nxn matrix - - ``f`` -- a polynomial in n variables x=(x1,...,xn) - - OUTPUT: The polynomial f(self\*x). + - ``f`` -- a polynomial in n variables x=(x1,...,xn) EXAMPLES:: @@ -2577,7 +2573,7 @@ cdef class Matrix(sage.structure.element.Matrix): def swap_columns(self, Py_ssize_t c1, Py_ssize_t c2): """ - Swap columns c1 and c2 of self. + Swap columns c1 and c2 of ``self``. EXAMPLES: We create a rational matrix:: @@ -2664,7 +2660,7 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``permutation`` -- a ``PermutationGroupElement``. + - ``permutation`` -- a ``PermutationGroupElement`` EXAMPLES: We create a matrix:: @@ -2691,7 +2687,6 @@ cdef class Matrix(sage.structure.element.Matrix): [0 3 0 0 0] [0 0 0 0 4] [0 0 0 5 0] - """ self.check_mutability() for cycle in permutation.cycle_tuples(): @@ -2712,11 +2707,9 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``permutation``, a ``PermutationGroupElement`` - - OUTPUT: + - ``permutation`` -- a ``PermutationGroupElement`` - - A matrix. + OUTPUT: a matrix EXAMPLES: We create some matrix:: @@ -2762,7 +2755,7 @@ cdef class Matrix(sage.structure.element.Matrix): def swap_rows(self, r1, r2): """ - Swap rows r1 and r2 of self. + Swap rows r1 and r2 of ``self``. EXAMPLES: We create a rational matrix:: @@ -2897,9 +2890,7 @@ cdef class Matrix(sage.structure.element.Matrix): - ``permutation`` -- a ``PermutationGroupElement`` - OUTPUT: - - - A matrix. + OUTPUT: a matrix EXAMPLES: We create a matrix:: @@ -2956,9 +2947,7 @@ cdef class Matrix(sage.structure.element.Matrix): - ``row_permutation`` -- a ``PermutationGroupElement`` - ``column_permutation`` -- a ``PermutationGroupElement`` - OUTPUT: - - - A matrix. + OUTPUT: a matrix EXAMPLES: We create a matrix:: @@ -3002,9 +2991,7 @@ cdef class Matrix(sage.structure.element.Matrix): - ``row_permutation`` -- a ``PermutationGroupElement`` - ``column_permutation`` -- a ``PermutationGroupElement`` - OUTPUT: - - - A matrix. + OUTPUT: a matrix EXAMPLES: We create a matrix:: @@ -3204,18 +3191,16 @@ cdef class Matrix(sage.structure.element.Matrix): def rescale_row(self, Py_ssize_t i, s, Py_ssize_t start_col=0): """ - Replace i-th row of self by s times i-th row of self. + Replace `i`-th row of ``self`` by `s` times `i`-th row of ``self``. INPUT: + - ``i`` -- `i`-th row - - ``i`` -- ith row - - - ``s`` -- scalar - - - ``start_col`` -- only rescale entries at this column - and to the right + - ``s`` -- scalar + - ``start_col`` -- only rescale entries at this column + and to the right EXAMPLES: We rescale the second row of a matrix over the rational numbers:: @@ -3277,7 +3262,7 @@ cdef class Matrix(sage.structure.element.Matrix): def with_rescaled_row(self, Py_ssize_t i, s, Py_ssize_t start_col=0): """ - Replaces i-th row of self by s times i-th row of self, returning + Replace `i`-th row of ``self`` by s times `i`-th row of self, returning new matrix. EXAMPLES: We rescale the second row of a matrix over the integers:: @@ -3323,18 +3308,16 @@ cdef class Matrix(sage.structure.element.Matrix): def rescale_col(self, Py_ssize_t i, s, Py_ssize_t start_row=0): """ - Replace i-th col of self by s times i-th col of self. + Replace `i`-th col of ``self`` by `s` times `i`-th col of ``self``. INPUT: + - ``i`` -- `i`-th column - - ``i`` -- ith column - - - ``s`` -- scalar - - - ``start_row`` -- only rescale entries at this row - and lower + - ``s`` -- scalar + - ``start_row`` -- only rescale entries at this row + and lower EXAMPLES: We rescale the last column of a matrix over the rational numbers:: @@ -3392,7 +3375,7 @@ cdef class Matrix(sage.structure.element.Matrix): def with_rescaled_col(self, Py_ssize_t i, s, Py_ssize_t start_row=0): """ - Replaces i-th col of self by s times i-th col of self, returning + Replaces `i`-th col of ``self`` by `s` times `i`-th col of self, returning new matrix. EXAMPLES: We rescale the last column of a matrix over the @@ -3596,23 +3579,21 @@ cdef class Matrix(sage.structure.element.Matrix): Py_ssize_t r, cols, cols_index=None): """ - Set row i of self to -(row r of A), but where we only take the + Set row i of ``self`` to -(row r of A), but where we only take the given column positions in that row of A. We do not zero out the - other entries of self's row i either. + other entries of ``self``'s row i either. INPUT: + - ``i`` -- integer, index into the rows of self - - ``i`` -- integer, index into the rows of self - - - ``A`` -- a matrix - - - ``r`` -- integer, index into rows of A + - ``A`` -- a matrix - - ``cols`` -- a *sorted* list of integers. + - ``r`` -- integer, index into rows of A - - ``(cols_index`` -- ignored) + - ``cols`` -- a *sorted* list of integers + - ``(cols_index`` -- ignored) EXAMPLES:: @@ -3715,7 +3696,7 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``k`` -- integer at which row/column ``self`` is mutated. + - ``k`` -- integer at which row/column ``self`` is mutated EXAMPLES: @@ -3790,17 +3771,15 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``d`` -- dictionary modelling partial entries of a diagonal matrix. + - ``d`` -- dictionary modelling partial entries of a diagonal matrix - - ``k`` -- integer for which row and column of self should be tested with the dictionary d. + - ``k`` -- integer for which row and column of ``self`` should be tested with the dictionary d - - ``sign`` -- `\pm 1`, depending on symmetric or skew-symmetric is tested. + - ``sign`` -- `\pm 1`, depending on symmetric or skew-symmetric is tested - - ``positive`` -- if True, only positive entries for the values of the dictionary are allowed. + - ``positive`` -- if ``True``, only positive entries for the values of the dictionary are allowed - OUTPUT: - - - ``L`` -- list of new keys in d + OUTPUT: ``L`` -- list of new keys in d EXAMPLES:: @@ -3833,20 +3812,30 @@ cdef class Matrix(sage.structure.element.Matrix): def _check_symmetrizability(self, return_diag=False, skew=False, positive=True): r""" - This function takes a square matrix over an *ordered integral domain* and checks if it is (skew-)symmetrizable. - A matrix `B` is (skew-)symmetrizable iff there exists an invertible diagonal matrix `D` such that `DB` is (skew-)symmetric. + This function takes a square matrix over an *ordered integral domain* + and checks if it is (skew-)symmetrizable. + + A matrix `B` is (skew-)symmetrizable iff there exists an invertible + diagonal matrix `D` such that `DB` is (skew-)symmetric. INPUT: - - ``return_diag`` -- bool(default: ``False``) if True and ``self`` is (skew)-symmetrizable the diagonal entries of the matrix `D` are returned. - - ``skew`` -- bool(default: ``False``) if True, (skew-)symmetrizability is checked. - - ``positive`` -- bool(default: ``True``) if True, the condition that `D` has positive entries is added. + - ``return_diag`` -- boolean (default: ``False``); if ``True`` and + ``self`` is (skew)-symmetrizable the diagonal entries of the matrix + `D` are returned + - ``skew`` -- boolean (default: ``False``); if ``True``, + (skew-)symmetrizability is checked + - ``positive`` -- boolean (default: ``True``); if ``True``, the + condition that `D` has positive entries is added OUTPUT: - - True -- if ``self`` is (skew-)symmetrizable and ``return_diag`` is False - - the diagonal entries of the matrix `D` such that `DB` is (skew-)symmetric -- iff ``self`` is (skew-)symmetrizable and ``return_diag`` is True - - False -- iff ``self`` is not (skew-)symmetrizable + - ``True`` -- if ``self`` is (skew-)symmetrizable and ``return_diag`` + is ``False`` + - the diagonal entries of the matrix `D` such that `DB` is + (skew-)symmetric -- iff ``self`` is (skew-)symmetrizable and + ``return_diag`` is ``True`` + - ``False`` -- iff ``self`` is not (skew-)symmetrizable EXAMPLES:: @@ -3905,8 +3894,8 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``v`` -- a list of scalars. The length can be less than - the number of rows of ``self`` but not greater. + - ``v`` -- a list of scalars. The length can be less than + the number of rows of ``self`` but not greater. OUTPUT: @@ -3982,8 +3971,8 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``v`` -- a list of scalars. The length can be less than - the number of columns of ``self`` but not greater. + - ``v`` -- a list of scalars. The length can be less than + the number of columns of ``self`` but not greater. OUTPUT: @@ -4075,7 +4064,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: m = Matrix(QQ, 1, (2,)) sage: m.is_symmetric() True - """ if self._ncols != self._nrows: return False # could be bigger than an int on a 64-bit platform, this @@ -4098,8 +4086,8 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``skew`` -- boolean (default: ``False``); Set to ``True`` to - check if the matrix is skew-Hermitian instead of Hermitian. + - ``skew`` -- boolean (default: ``False``); set to ``True`` to + check if the matrix is skew-Hermitian instead of Hermitian - ``tolerance`` -- a real number; the maximum difference we'll tolerate between entries of the given matrix and its conjugate- @@ -4199,7 +4187,7 @@ cdef class Matrix(sage.structure.element.Matrix): # The dense algorithm checks all of the on-or-below-diagonal # entries, of which there are (n^2 + n)/2. If the matrix # is sparse, however, we can get away with checking only - # the non-zero positions. This will be faster if the matrix + # the nonzero positions. This will be faster if the matrix # is truly sparse (if there are not so many of those positions) # even after taking numerical issues into account. # @@ -4469,21 +4457,29 @@ cdef class Matrix(sage.structure.element.Matrix): def is_symmetrizable(self, return_diag=False, positive=True): r""" - This function takes a square matrix over an *ordered integral domain* and checks if it is symmetrizable. - A matrix `B` is symmetrizable iff there exists an invertible diagonal matrix `D` such that `DB` is symmetric. + This function takes a square matrix over an *ordered integral domain* + and checks if it is symmetrizable. + + A matrix `B` is symmetrizable iff there exists an invertible diagonal + matrix `D` such that `DB` is symmetric. .. warning:: Expects ``self`` to be a matrix over an *ordered integral domain*. INPUT: - - ``return_diag`` -- bool(default: ``False``) if True and ``self`` is symmetrizable the diagonal entries of the matrix `D` are returned. - - ``positive`` -- bool(default: ``True``) if True, the condition that `D` has positive entries is added. + - ``return_diag`` -- boolean (default: ``False``); if ``True`` and + ``self`` is symmetrizable the diagonal entries of the matrix `D` are + returned + - ``positive`` -- boolean (default: ``True``); if ``True``, the + condition that `D` has positive entries is added OUTPUT: - - True -- if ``self`` is symmetrizable and ``return_diag`` is False - - the diagonal entries of a matrix `D` such that `DB` is symmetric -- iff ``self`` is symmetrizable and ``return_diag`` is True - - False -- iff ``self`` is not symmetrizable + - ``True`` -- if ``self`` is symmetrizable and ``return_diag`` is + ``False`` + - the diagonal entries of a matrix `D` such that `DB` is symmetric -- + iff ``self`` is symmetrizable and ``return_diag`` is ``True`` + - ``False`` -- iff ``self`` is not symmetrizable EXAMPLES:: @@ -4512,21 +4508,29 @@ cdef class Matrix(sage.structure.element.Matrix): def is_skew_symmetrizable(self, return_diag=False, positive=True): r""" - This function takes a square matrix over an *ordered integral domain* and checks if it is skew-symmetrizable. - A matrix `B` is skew-symmetrizable iff there exists an invertible diagonal matrix `D` such that `DB` is skew-symmetric. + This function takes a square matrix over an *ordered integral domain* + and checks if it is skew-symmetrizable. + A matrix `B` is skew-symmetrizable iff there exists an invertible + diagonal matrix `D` such that `DB` is skew-symmetric. .. warning:: Expects ``self`` to be a matrix over an *ordered integral domain*. INPUT: - - ``return_diag`` -- bool(default: ``False``) if True and ``self`` is skew-symmetrizable the diagonal entries of the matrix `D` are returned. - - ``positive`` -- bool(default: ``True``) if True, the condition that `D` has positive entries is added. + - ``return_diag`` -- boolean (default: ``False``); if ``True`` and + ``self`` is skew-symmetrizable the diagonal entries of the matrix `D` + are returned + - ``positive`` -- boolean (default: ``True``); if ``True``, the + condition that `D` has positive entries is added OUTPUT: - - True -- if ``self`` is skew-symmetrizable and ``return_diag`` is False - - the diagonal entries of a matrix `D` such that `DB` is skew-symmetric -- iff ``self`` is skew-symmetrizable and ``return_diag`` is True - - False -- iff ``self`` is not skew-symmetrizable + - ``True`` -- if ``self`` is skew-symmetrizable and ``return_diag`` is + ``False`` + - the diagonal entries of a matrix `D` such that `DB` is + skew-symmetric -- iff ``self`` is skew-symmetrizable and ``return_diag`` + is ``True`` + - ``False`` -- iff ``self`` is not skew-symmetrizable EXAMPLES:: @@ -4563,7 +4567,7 @@ cdef class Matrix(sage.structure.element.Matrix): def is_dense(self): """ - Return True if this is a dense matrix. + Return ``True`` if this is a dense matrix. In Sage, being dense is a property of the underlying representation, not the number of nonzero entries. @@ -4579,7 +4583,7 @@ cdef class Matrix(sage.structure.element.Matrix): def is_sparse(self): """ - Return True if this is a sparse matrix. + Return ``True`` if this is a sparse matrix. In Sage, being sparse is a property of the underlying representation, not the number of nonzero entries. @@ -4595,7 +4599,7 @@ cdef class Matrix(sage.structure.element.Matrix): def is_square(self): """ - Return True precisely if this matrix is square, i.e., has the same + Return ``True`` precisely if this matrix is square, i.e., has the same number of rows and columns. EXAMPLES:: @@ -4609,7 +4613,7 @@ cdef class Matrix(sage.structure.element.Matrix): def is_invertible(self): r""" - Return True if this matrix is invertible. + Return ``True`` if this matrix is invertible. EXAMPLES: The following matrix is invertible over `\QQ` but not over `\ZZ`. @@ -4799,8 +4803,8 @@ cdef class Matrix(sage.structure.element.Matrix): def nonpivots(self): """ - Return the list of i such that the i-th column of self is NOT a - pivot column of the reduced row echelon form of self. + Return the list of `i` such that the `i`-th column of ``self`` is NOT a + pivot column of the reduced row echelon form of ``self``. OUTPUT: sorted tuple of (Python) integers @@ -4836,13 +4840,13 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``copy`` -- (default: ``True``) it is safe to change the - resulting list (unless you give the option ``copy=False``) + - ``copy`` -- boolean (default: ``True``); it is safe to change the + resulting list (unless you give the option ``copy=False``) - - ``column_order`` -- (default: ``False``) If ``True``, - returns the list of pairs ``(i,j)`` such that ``self[i,j] != 0``, but - sorted by columns, i.e., column ``j=0`` entries occur first, then - column ``j=1`` entries, etc. + - ``column_order`` -- boolean (default: ``False``); if ``True``, + returns the list of pairs ``(i,j)`` such that ``self[i,j] != 0``, but + sorted by columns, i.e., column ``j=0`` entries occur first, then + column ``j=1`` entries, etc. EXAMPLES:: @@ -4938,7 +4942,7 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``i`` -- an integer + - ``i`` -- integer OUTPUT: list @@ -4953,7 +4957,7 @@ cdef class Matrix(sage.structure.element.Matrix): sage: a.nonzero_positions_in_column(1) [0, 1] - You will get an ``IndexError`` if you select an invalid column:: + You will get an :exc:`IndexError` if you select an invalid column:: sage: a.nonzero_positions_in_column(2) Traceback (most recent call last): @@ -4977,7 +4981,7 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``i`` -- an integer + - ``i`` -- integer OUTPUT: list @@ -5164,9 +5168,9 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``v`` -- a free module element. + - ``v`` -- a free module element - OUTPUT: The vector times matrix product v\*A. + OUTPUT: the vector times matrix product ``v*A`` EXAMPLES:: @@ -5206,7 +5210,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: v = vector(R, [1, x]) sage: v*I (1 + O(5^5), O(5)) - """ M = self.row_ambient_module() if self._nrows != v._degree: @@ -5241,7 +5244,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: v = vector(R, [1, x]) sage: I*v (1 + O(5^5), O(5)) - """ M = self.column_ambient_module() if self._ncols != v._degree: @@ -5339,7 +5341,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: a + b # indirect doctest [ 2 4] [x*y + y*x 2*y*x] - """ cdef Py_ssize_t i, j cdef Matrix A @@ -5363,7 +5364,6 @@ cdef class Matrix(sage.structure.element.Matrix): sage: a - b # indirect doctest [ 0 0] [x*y - y*x 0] - """ cdef Py_ssize_t i, j cdef Matrix A @@ -5676,7 +5676,7 @@ cdef class Matrix(sage.structure.element.Matrix): cdef bint _will_use_strassen(self, Matrix right) except -2: """ - Whether or not matrix multiplication of self by right should be + Whether or not matrix multiplication of ``self`` by ``right`` should be done using Strassen. Overload _strassen_default_cutoff to return -1 to not use @@ -5693,7 +5693,7 @@ cdef class Matrix(sage.structure.element.Matrix): cdef bint _will_use_strassen_echelon(self) except -2: """ - Whether or not matrix multiplication of self by right should be + Whether or not matrix multiplication of ``self`` by ``right`` should be done using Strassen. Overload this in derived classes to not use Strassen by default. @@ -5708,7 +5708,7 @@ cdef class Matrix(sage.structure.element.Matrix): def __neg__(self): """ - Return the negative of self. + Return the negative of ``self``. EXAMPLES:: @@ -5727,8 +5727,8 @@ cdef class Matrix(sage.structure.element.Matrix): Return the inverse of this matrix, as a matrix over the fraction field. - Raises a ``ZeroDivisionError`` if the matrix has zero - determinant, and raises an ``ArithmeticError``, if the + Raises a :exc:`ZeroDivisionError` if the matrix has zero + determinant, and raises an :exc:`ArithmeticError`, if the inverse doesn't exist because the matrix is nonsquare. Also, note, e.g., that the inverse of a matrix over `\ZZ` is always a matrix defined over `\QQ` (even if the @@ -5791,7 +5791,7 @@ cdef class Matrix(sage.structure.element.Matrix): [ 1 422550200076076467165567735125] [1267650600228229401496703205375 422550200076076467165567735126] - Matrices over p-adics. See :issue:`17272` :: + Matrices over `p`-adics. See :issue:`17272` :: sage: # needs sage.rings.padics sage: R = ZpCA(5, 5, print_mode='val-unit') @@ -5907,7 +5907,7 @@ cdef class Matrix(sage.structure.element.Matrix): Return the inverse of this matrix in the same matrix space. The matrix must be invertible on the base ring. Otherwise, an - ``ArithmeticError`` is raised. + :exc:`ArithmeticError` is raised. The computation goes through the matrix of cofactors and avoids division. In particular the base ring does not need to have a @@ -5915,7 +5915,7 @@ cdef class Matrix(sage.structure.element.Matrix): INPUT: - - ``algorithm`` -- (default: ``None``) either ``None`` or ``"df"`` (for + - ``algorithm`` -- (default: ``None``) either ``None`` or ``'df'`` (for division free) EXAMPLES:: @@ -6287,7 +6287,8 @@ def unpickle(cls, parent, immutability, cache, data, version): def set_max_rows(n): """ - Sets the global variable max_rows (which is used in deciding how to output a matrix). + Set the global variable ``max_rows`` (which is used in deciding how to + output a matrix). EXAMPLES:: @@ -6295,7 +6296,6 @@ def set_max_rows(n): sage: set_max_rows(20) doctest:...: DeprecationWarning: 'set_max_rows' is replaced by 'matrix.options.max_rows' See https://github.com/sagemath/sage/issues/30552 for details. - """ from sage.misc.superseded import deprecation deprecation(30552, "'set_max_rows' is replaced by 'matrix.options.max_rows'") @@ -6305,7 +6305,8 @@ def set_max_rows(n): def set_max_cols(n): """ - Sets the global variable max_cols (which is used in deciding how to output a matrix). + Set the global variable ``max_cols`` (which is used in deciding how to + output a matrix). EXAMPLES:: @@ -6313,7 +6314,6 @@ def set_max_cols(n): sage: set_max_cols(50) doctest:...: DeprecationWarning: 'set_max_cols' is replaced by 'matrix.options.max_cols' See https://github.com/sagemath/sage/issues/30552 for details. - """ from sage.misc.superseded import deprecation deprecation(30552, "'set_max_cols' is replaced by 'matrix.options.max_cols'") diff --git a/src/sage/matrix/matrix1.pyx b/src/sage/matrix/matrix1.pyx index c38df5412f0..3edb9ead54d 100644 --- a/src/sage/matrix/matrix1.pyx +++ b/src/sage/matrix/matrix1.pyx @@ -32,7 +32,7 @@ cdef class Matrix(Matrix0): def _pari_init_(self): """ - Return a string defining a GP representation of self. + Return a string defining a GP representation of ``self``. EXAMPLES:: @@ -61,7 +61,7 @@ cdef class Matrix(Matrix0): def __pari__(self): """ - Return the Pari matrix corresponding to self. + Return the Pari matrix corresponding to ``self``. EXAMPLES:: @@ -92,7 +92,7 @@ cdef class Matrix(Matrix0): def _gap_init_(self): """ - Returns a string defining a gap representation of self. + Return a string defining a gap representation of ``self``. EXAMPLES:: @@ -147,7 +147,7 @@ cdef class Matrix(Matrix0): INPUT: - - ``M`` -- a matrix. + - ``M`` -- a matrix OUTPUT: @@ -405,7 +405,7 @@ cdef class Matrix(Matrix0): def _polymake_(self, polymake=None): """ - Tries to coerce this matrix to a polymake matrix. + Try to coerce this matrix to a polymake matrix. EXAMPLES:: @@ -424,7 +424,7 @@ cdef class Matrix(Matrix0): def _singular_(self, singular=None): """ - Tries to coerce this matrix to a singular matrix. + Try to coerce this matrix to a singular matrix. """ if singular is None: from sage.interfaces.singular import singular as singular_default @@ -510,7 +510,7 @@ cdef class Matrix(Matrix0): def _scilab_(self, scilab=None): """ - Creates a ScilabElement object based on self and returns it. + Create a ScilabElement object based on ``self`` and returns it. EXAMPLES:: @@ -605,7 +605,6 @@ cdef class Matrix(Matrix0): [] sage: sZeroRow = ZeroRow._sympy_(); sZeroRow # needs sympy Matrix(0, 2, []) - """ from sage.interfaces.sympy import sympy_init sympy_init() @@ -677,7 +676,7 @@ cdef class Matrix(Matrix0): INPUT: - - ``dtype`` -- The desired data-type for the array. If not given, + - ``dtype`` -- the desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence. @@ -763,7 +762,7 @@ cdef class Matrix(Matrix0): def lift(self): """ - Return lift of self to the covering ring of the base ring R, + Return lift of ``self`` to the covering ring of the base ring R, which is by definition the ring returned by calling cover_ring() on R, or just R itself if the cover_ring method is not defined. @@ -803,14 +802,14 @@ cdef class Matrix(Matrix0): def lift_centered(self): """ - Apply the lift_centered method to every entry of self. + Apply the lift_centered method to every entry of ``self``. OUTPUT: - If self is a matrix over the Integers mod `n`, this method returns the - unique matrix `m` such that `m` is congruent to self mod `n` and for + If ``self`` is a matrix over the Integers mod `n`, this method returns the + unique matrix `m` such that `m` is congruent to ``self`` mod `n` and for every entry `m[i,j]` we have `-n/2 < m[i,j] \\leq n/2`. If the - coefficient ring does not have a cover_ring method, return self. + coefficient ring does not have a cover_ring method, return ``self``. EXAMPLES:: @@ -972,12 +971,12 @@ cdef class Matrix(Matrix0): def columns(self, copy=True): r""" - Return a list of the columns of self. + Return a list of the columns of ``self``. INPUT: - - ``copy`` -- (default: ``True``) if True, return a copy of the list - of columns which is safe to change. + - ``copy`` -- boolean (default: ``True``); if ``True``, return a copy of the list + of columns which is safe to change If ``self`` is a sparse matrix, columns are returned as sparse vectors, otherwise returned vectors are dense. @@ -1009,10 +1008,10 @@ cdef class Matrix(Matrix0): sage: A.columns('junk') Traceback (most recent call last): ... - ValueError: 'copy' must be True or False, not junk + ValueError: 'copy' must be ``True`` or False, not junk """ if copy not in [True, False]: - msg = "'copy' must be True or False, not {0}" + msg = "'copy' must be ``True`` or False, not {0}" raise ValueError(msg.format(copy)) x = self.fetch('columns') if x is not None: @@ -1028,12 +1027,12 @@ cdef class Matrix(Matrix0): def rows(self, copy=True): r""" - Return a list of the rows of self. + Return a list of the rows of ``self``. INPUT: - - ``copy`` -- (default: ``True``) if True, return a copy of the list - of rows which is safe to change. + - ``copy`` -- boolean (default: ``True``); if ``True``, return a copy of the list + of rows which is safe to change If ``self`` is a sparse matrix, rows are returned as sparse vectors, otherwise returned vectors are dense. @@ -1065,10 +1064,10 @@ cdef class Matrix(Matrix0): sage: A.rows('junk') Traceback (most recent call last): ... - ValueError: 'copy' must be True or False, not junk + ValueError: 'copy' must be ``True`` or False, not junk """ if copy not in [True, False]: - msg = "'copy' must be True or False, not {0}" + msg = "'copy' must be ``True`` or False, not {0}" raise ValueError(msg.format(copy)) x = self.fetch('rows') if x is not None: @@ -1084,11 +1083,11 @@ cdef class Matrix(Matrix0): def dense_columns(self, copy=True): """ - Return list of the dense columns of self. + Return list of the dense columns of ``self``. INPUT: - - ``copy`` -- (default: ``True``) if True, return a copy so you can + - ``copy`` -- boolean (default: ``True``); if ``True``, return a copy so you can modify it safely EXAMPLES: @@ -1147,11 +1146,11 @@ cdef class Matrix(Matrix0): def dense_rows(self, copy=True): """ - Return list of the dense rows of self. + Return list of the dense rows of ``self``. INPUT: - - ``copy`` -- (default: ``True``) if True, return a copy so you can + - ``copy`` -- boolean (default: ``True``); if ``True``, return a copy so you can modify it safely (note that the individual vectors in the copy should not be modified since they are mutable!) @@ -1206,8 +1205,8 @@ cdef class Matrix(Matrix0): INPUT: - - ``copy`` -- (default: ``True``) if True, return a copy so you can - modify it safely + - ``copy`` -- boolean (default: ``True``); if ``True``, return a copy so you can + modify it safely EXAMPLES:: @@ -1282,8 +1281,8 @@ cdef class Matrix(Matrix0): INPUT: - - ``copy`` -- (default: ``True``) if True, return a copy so you can - modify it safely + - ``copy`` -- boolean (default: ``True``); if ``True``, return a copy so you can + modify it safely EXAMPLES:: @@ -1360,7 +1359,7 @@ cdef class Matrix(Matrix0): def column(self, Py_ssize_t i, from_list=False): """ - Return the ``i``'th column of this matrix as a vector. + Return the ``i``-th column of this matrix as a vector. This column is a dense vector if and only if the matrix is a dense matrix. @@ -1369,13 +1368,12 @@ cdef class Matrix(Matrix0): - ``i`` -- integer - - ``from_list`` -- bool (default: ``False``); if true, returns the - ``i``'th element of ``self.columns()`` (see :func:`columns()`), + - ``from_list`` -- boolean (default: ``False``); if ``True``, returns the + ``i``-th element of ``self.columns()`` (see :func:`columns()`), which may be faster, but requires building a list of all columns the first time it is called after an entry of the matrix is changed. - EXAMPLES:: sage: a = matrix(2, 3, range(6)); a @@ -1420,7 +1418,7 @@ cdef class Matrix(Matrix0): def row(self, Py_ssize_t i, from_list=False): """ - Return the ``i``'th row of this matrix as a vector. + Return the ``i``-th row of this matrix as a vector. This row is a dense vector if and only if the matrix is a dense matrix. @@ -1429,8 +1427,8 @@ cdef class Matrix(Matrix0): - ``i`` -- integer - - ``from_list`` -- bool (default: ``False``); if true, returns the - ``i``'th element of ``self.rows()`` (see :func:`rows`), which + - ``from_list`` -- boolean (default: ``False``); if ``True``, returns the + ``i``-th element of ``self.rows()`` (see :func:`rows`), which may be faster, but requires building a list of all rows the first time it is called after an entry of the matrix is changed. @@ -1490,10 +1488,10 @@ cdef class Matrix(Matrix0): INPUT: - ``bottom`` -- a matrix, vector or free module element, whose - dimensions are compatible with ``self``. + dimensions are compatible with ``self`` - - ``subdivide`` -- (default: ``False``); request the resulting - matrix to have a new subdivision, separating ``self`` from ``bottom``. + - ``subdivide`` -- (default: ``False``) request the resulting + matrix to have a new subdivision, separating ``self`` from ``bottom`` OUTPUT: @@ -1774,15 +1772,15 @@ cdef class Matrix(Matrix0): def augment(self, right, subdivide=False): r""" - Returns a new matrix formed by appending the matrix (or vector) + Return a new matrix formed by appending the matrix (or vector) ``right`` on the right side of ``self``. INPUT: - ``right`` -- a matrix, vector or free module element, whose - dimensions are compatible with ``self``. + dimensions are compatible with ``self`` - - ``subdivide`` -- (default: ``False``); request the resulting + - ``subdivide`` -- (default: ``False``) request the resulting matrix to have a new subdivision, separating ``self`` from ``right``. @@ -1812,7 +1810,6 @@ cdef class Matrix(Matrix0): :func:`~sage.matrix.constructor.block_diagonal_matrix` useful and simpler in some instances. - EXAMPLES: Augmenting with a matrix. :: @@ -1979,7 +1976,7 @@ cdef class Matrix(Matrix0): def matrix_from_columns(self, columns): """ - Return the matrix constructed from self using columns with indices + Return the matrix constructed from ``self`` using columns with indices in the columns list. EXAMPLES:: @@ -2013,8 +2010,9 @@ cdef class Matrix(Matrix0): INPUT: - * ``dcols`` -- list of indices of columns to be deleted from self. - * ``check`` -- checks whether any index in ``dcols`` is out of range. Defaults to ``True``. + - ``dcols`` -- list of indices of columns to be deleted from ``self`` + - ``check`` -- boolean (default: ``True``); check whether any index in + ``dcols`` is out of range .. SEEALSO:: @@ -2077,7 +2075,7 @@ cdef class Matrix(Matrix0): def matrix_from_rows(self, rows): """ - Return the matrix constructed from self using rows with indices in + Return the matrix constructed from ``self`` using rows with indices in the rows list. EXAMPLES:: @@ -2110,8 +2108,9 @@ cdef class Matrix(Matrix0): INPUT: - * ``drows`` -- list of indices of rows to be deleted from ``self``. - * ``check`` -- (boolean, default: ``True``); whether to check if any index in ``drows`` is out of range. + - ``drows`` -- list of indices of rows to be deleted from ``self`` + - ``check`` -- boolean (default: ``True``); whether to check if any + index in ``drows`` is out of range .. SEEALSO:: @@ -2233,13 +2232,13 @@ cdef class Matrix(Matrix0): def submatrix(self, Py_ssize_t row=0, Py_ssize_t col=0, Py_ssize_t nrows=-1, Py_ssize_t ncols=-1): """ - Return the matrix constructed from self using the specified + Return the matrix constructed from ``self`` using the specified range of rows and columns. INPUT: - - ``row``, ``col`` -- index of the starting row and column. - Indices start at zero. + - ``row``, ``col`` -- index of the starting row and column (indices + start at zero) - ``nrows``, ``ncols`` -- (optional) number of rows and columns to take. If not provided, take all rows below and all columns to @@ -2290,13 +2289,13 @@ cdef class Matrix(Matrix0): def set_row(self, row, v): r""" - Sets the entries of row ``row`` to the entries of ``v``. + Set the entries of row ``row`` to the entries of ``v``. INPUT: - - ``row`` -- index of row to be set. + - ``row`` -- index of row to be set - - ``v`` -- a list or vector of the new entries. + - ``v`` -- list or vector of the new entries OUTPUT: @@ -2363,13 +2362,13 @@ cdef class Matrix(Matrix0): def set_column(self, col, v): r""" - Sets the entries of column ``col`` to the entries of ``v``. + Set the entries of column ``col`` to the entries of ``v``. INPUT: - - ``col`` -- index of column to be set. + - ``col`` -- index of column to be set - - ``v`` -- a list or vector of the new entries. + - ``v`` -- list or vector of the new entries OUTPUT: @@ -2661,15 +2660,15 @@ cdef class Matrix(Matrix0): def matrix_space(self, nrows=None, ncols=None, sparse=None): """ - Return the ambient matrix space of self. + Return the ambient matrix space of ``self``. INPUT: - ``nrows``, ``ncols`` -- (optional) number of rows and columns in - returned matrix space. + returned matrix space - ``sparse`` -- whether the returned matrix space uses sparse or - dense matrices. + dense matrices EXAMPLES:: @@ -2718,7 +2717,7 @@ cdef class Matrix(Matrix0): """ Create a matrix in the parent of this matrix with the given number of rows, columns, etc. The default parameters are the same as for - self. + ``self``. INPUT: @@ -2726,9 +2725,9 @@ cdef class Matrix(Matrix0): - ``nrows``, ``ncols`` -- number of rows and columns in returned matrix. If not specified, defaults to ``None`` and will give a - matrix of the same size as self. + matrix of the same size as ``self``. - ``sparse`` -- whether returned matrix is sparse or not. Defaults - to same value as self. + to same value as self The remaining three variables (``coerce``, ``entries``, and ``copy``) are used by @@ -2738,7 +2737,7 @@ cdef class Matrix(Matrix0): .. warning:: This function called with no arguments returns the zero - matrix of the same dimension and sparseness of self. + matrix of the same dimension and sparseness of ``self``. EXAMPLES:: @@ -2787,7 +2786,7 @@ cdef class Matrix(Matrix0): def block_sum(self, Matrix other): """ - Return the block matrix that has self and other on the diagonal:: + Return the block matrix that has ``self`` and ``other`` on the diagonal:: [ self 0 ] [ 0 other ] diff --git a/src/sage/matrix/matrix2.pyx b/src/sage/matrix/matrix2.pyx index 37042bafa43..b88dee771f3 100644 --- a/src/sage/matrix/matrix2.pyx +++ b/src/sage/matrix/matrix2.pyx @@ -120,7 +120,7 @@ _Fields = Fields() cdef class Matrix(Matrix1): """ - Base class for matrices, part 2 + Base class for matrices, part 2. TESTS:: @@ -242,7 +242,7 @@ cdef class Matrix(Matrix1): some solvers will return solutions over a larger ring than the base ring of the inputs (a typical case are rational solutions for integer linear systems). When set to ``False``, a solution - over the base ring is returned, with a :class:`ValueError` + over the base ring is returned, with a :exc:`ValueError` being raised if none exists. - ``check`` -- boolean (default: ``True``); verify the answer @@ -442,7 +442,6 @@ cdef class Matrix(Matrix1): sage: A.solve_left(b, check=False) # needs sage.symbolic (2) - """ if isinstance(B, Vector): try: @@ -477,7 +476,7 @@ cdef class Matrix(Matrix1): some solvers will return solutions over a larger ring than the base ring of the inputs (a typical case are rational solutions for integer linear systems). When set to ``False``, a solution - over the base ring is returned, with a :class:`ValueError` + over the base ring is returned, with a :exc:`ValueError` being raised if none exists. - ``check`` -- boolean (default: ``True``); verify the answer @@ -555,7 +554,7 @@ cdef class Matrix(Matrix1): ... ValueError: matrix equation has no solutions - A :class:`ValueError` is raised if the input is invalid:: + A :exc:`ValueError` is raised if the input is invalid:: sage: A = matrix(QQ, 4,2, [0, -1, 1, 0, -2, 2, 1, 0]) sage: B = matrix(QQ, 2,2, [1, 0, 1, -1]) @@ -638,7 +637,7 @@ cdef class Matrix(Matrix1): sage: A*X == B True - Solving a system over the p-adics:: + Solving a system over the `p`-adics:: sage: # needs sage.rings.padics sage: k = Qp(5, 4) @@ -1032,18 +1031,16 @@ cdef class Matrix(Matrix1): def _solve_right_general(self, B, check=True): r""" This is used internally by the ``solve_right`` command - to solve for self\*X = B when self is not square or not of full + to solve for ``self*X = B`` when ``self`` is not square or not of full rank. It does some linear algebra, then solves a full-rank square system. INPUT: + - ``B`` -- a matrix - - ``B`` -- a matrix - - - ``check`` -- bool (default: ``True``); if False, if there - is no solution this function will not detect that fact. - + - ``check`` -- boolean (default: ``True``); if ``False``, if there + is no solution this function will not detect that fact OUTPUT: matrix @@ -1239,7 +1236,7 @@ cdef class Matrix(Matrix1): def elementwise_product(self, right): r""" - Returns the elementwise product of two matrices + Return the elementwise product of two matrices of the same size (also known as the Hadamard product). INPUT: @@ -1249,7 +1246,7 @@ cdef class Matrix(Matrix1): of elements of the base rings of ``self`` and ``right`` is defined, once Sage's coercion model is applied. If the matrices have different sizes, or if multiplication - of individual entries cannot be achieved, a ``TypeError`` + of individual entries cannot be achieved, a :exc:`TypeError` will result. OUTPUT: @@ -1415,7 +1412,7 @@ cdef class Matrix(Matrix1): raise TypeError("elementwise_product() argument should be a matrix or coercible to a matrix") return (A)._elementwise_product(B) - def permanent(self, algorithm="Ryser"): + def permanent(self, algorithm='Ryser'): r""" Return the permanent of this matrix. @@ -1495,7 +1492,7 @@ cdef class Matrix(Matrix1): sage: n, w = 50, 5 sage: A = matrix(ZZ, n, n, lambda i,j: (i+j)%5 + 1 if abs(i-j) <= w else 0) - sage: A.permanent(algorithm="ButeraPernici") + sage: A.permanent(algorithm='ButeraPernici') 57766972735511097036962481710892268404670105604676932908 See Minc: Permanents, Example 2.1, p. 5. @@ -1564,7 +1561,7 @@ cdef class Matrix(Matrix1): perm = perm + sn * _binomial(n-r, m-r) * s return perm - def permanental_minor(self, Py_ssize_t k, algorithm="Ryser"): + def permanental_minor(self, Py_ssize_t k, algorithm='Ryser'): r""" Return the permanental `k`-minor of this matrix. @@ -1573,9 +1570,9 @@ cdef class Matrix(Matrix1): maximal permanental minor is just the permanent. For a (0,1)-matrix `A` the permanental `k`-minor - counts the number of different selections of `k` 1's of - `A` with no two of the 1's on the same row and no two of the - 1's on the same column. + counts the number of different selections of `k` 1s of + `A` with no two of the 1s on the same row and no two of the + 1s on the same column. See Brualdi and Ryser: Combinatorial Matrix Theory, p. 203. Note the typo `p_0(A) = 0` in that reference! For applications @@ -1590,8 +1587,8 @@ cdef class Matrix(Matrix1): - ``k`` -- the size of the minor - - ``algorithm`` -- either "Ryser" (default) or "ButeraPernici". The - Butera-Pernici algorithm is well suited for band matrices. + - ``algorithm`` -- either "Ryser" (default) or "ButeraPernici"; the + Butera-Pernici algorithm is well suited for band matrices EXAMPLES:: @@ -1681,18 +1678,18 @@ cdef class Matrix(Matrix1): INPUT: - - ``algorithm`` (default: guess) -- one of the following: + - ``algorithm`` -- (default: guess) one of the following: - - ``"numpy"`` -- Use numpy's ``linalg.pinv()`` which is - suitable over real or complex fields. + - ``'numpy'`` -- use numpy's ``linalg.pinv()`` which is + suitable over real or complex fields - - ``"exact"`` -- Use a simple algorithm which is not + - ``'exact'`` -- use a simple algorithm which is not numerically stable but useful over exact fields. Assume that no conjugation is needed, that the conjugate transpose is just the transpose. - - ``"exactconj"`` -- Like ``exact`` but use the conjugate - transpose. + - ``'exactconj'`` -- like ``exact`` but use the conjugate + transpose OUTPUT: a matrix @@ -1728,10 +1725,10 @@ cdef class Matrix(Matrix1): sage: M = matrix.hilbert(12, ring=RR) sage: (~M * M).norm() # a considerable error # needs scipy 1.3... - sage: Mx = M.pseudoinverse(algorithm="exact") + sage: Mx = M.pseudoinverse(algorithm='exact') sage: (Mx * M).norm() # huge error # needs scipy 11.5... - sage: Mx = M.pseudoinverse(algorithm="numpy") # needs numpy + sage: Mx = M.pseudoinverse(algorithm='numpy') # needs numpy sage: (Mx * M).norm() # still OK 1.00... @@ -1744,10 +1741,10 @@ cdef class Matrix(Matrix1): sage: M * M.pseudoinverse() [ 0.2500000000000000? 0.4330127018922193?*I] [-0.4330127018922193?*I 0.750000000000000?] - sage: M * M.pseudoinverse(algorithm="exactconj") + sage: M * M.pseudoinverse(algorithm='exactconj') [ 1/4 0.4330127018922193?*I] [-0.4330127018922193?*I 3/4] - sage: M * M.pseudoinverse(algorithm="exact") + sage: M * M.pseudoinverse(algorithm='exact') [ -1/2 0.866025403784439?*I] [0.866025403784439?*I 3/2] @@ -1764,21 +1761,21 @@ cdef class Matrix(Matrix1): Numpy gives a strange answer due to rounding errors:: - sage: M.pseudoinverse(algorithm="numpy") # random # needs numpy + sage: M.pseudoinverse(algorithm='numpy') # random # needs numpy [-1286742750677287/643371375338643 1000799917193445/1000799917193444] [ 519646110850445/346430740566963 -300239975158034/600479950316067] Although it is not too far off:: - sage: (~M - M.pseudoinverse(algorithm="numpy")).norm() < 1e-14 # needs numpy + sage: (~M - M.pseudoinverse(algorithm='numpy')).norm() < 1e-14 # needs numpy True TESTS:: - sage: M.pseudoinverse(algorithm="exact") + sage: M.pseudoinverse(algorithm='exact') [ -2 1] [ 3/2 -1/2] - sage: M.pseudoinverse(algorithm="whatever") + sage: M.pseudoinverse(algorithm='whatever') Traceback (most recent call last): ... ValueError: unknown algorithm 'whatever', valid values are ('numpy', 'exact', 'exactconj') @@ -1861,16 +1858,16 @@ cdef class Matrix(Matrix1): - ``self`` -- an `m` by `n` matrix - - ``algorithm`` -- a string which must be either "Ryser" or - "ButeraPernici" (default) or "Godsil"; Ryser one might be faster on - simple and small instances. Godsil only accepts input in 0,1. + - ``algorithm`` -- string which must be either ``'Ryser'`` or + ``'ButeraPernici'`` (default) or ``'Godsil'``; Ryser one might be + faster on simple and small instances. Godsil only accepts input in 0,1. - - ``complement`` -- boolean (default: ``False``) whether we consider the + - ``complement`` -- boolean (default: ``False``); whether we consider the rook vector of the complement matrix. If set to ``True`` then the matrix must have entries in {0, 1} and the complement matrix is the - one for which the 0's are replaced by 1's and 1's by 0's. + one for which the 0s are replaced by 1s and 1s by 0s. - - ``use_complement`` -- Boolean (default: ``None``) whether to compute the + - ``use_complement`` -- boolean (default: ``None``); whether to compute the rook vector of a (0,1)-matrix from its complement. By default this is determined by the density of ones in the matrix. @@ -1917,11 +1914,11 @@ cdef class Matrix(Matrix1): Different algorithms are available:: sage: A = matrix([[1,0,0,1],[0,1,1,0],[0,1,1,0],[1,0,0,1]]) - sage: A.rook_vector(algorithm="ButeraPernici") + sage: A.rook_vector(algorithm='ButeraPernici') [1, 8, 20, 16, 4] - sage: A.rook_vector(algorithm="Ryser") + sage: A.rook_vector(algorithm='Ryser') [1, 8, 20, 16, 4] - sage: A.rook_vector(algorithm="Godsil") # needs sage.graphs sage.libs.flint + sage: A.rook_vector(algorithm='Godsil') # needs sage.graphs sage.libs.flint [1, 8, 20, 16, 4] When the matrix `A` has more ones then zeroes it is usually faster @@ -1941,27 +1938,27 @@ cdef class Matrix(Matrix1): sage: R. = PolynomialRing(GF(5)) sage: A = matrix(R, [[1, x, y], [x*y, x**2+y, 0]]) - sage: A.rook_vector(algorithm="ButeraPernici") + sage: A.rook_vector(algorithm='ButeraPernici') [1, x^2 + x*y + x + 2*y + 1, 2*x^2*y + x*y^2 + x^2 + y^2 + y] - sage: A.rook_vector(algorithm="Ryser") + sage: A.rook_vector(algorithm='Ryser') [1, x^2 + x*y + x + 2*y + 1, 2*x^2*y + x*y^2 + x^2 + y^2 + y] - sage: A.rook_vector(algorithm="Godsil") + sage: A.rook_vector(algorithm='Godsil') Traceback (most recent call last): ... ValueError: coefficients must be zero or one, but we have 'x' in position (0,1). sage: B = A.transpose() - sage: B.rook_vector(algorithm="ButeraPernici") + sage: B.rook_vector(algorithm='ButeraPernici') [1, x^2 + x*y + x + 2*y + 1, 2*x^2*y + x*y^2 + x^2 + y^2 + y] - sage: B.rook_vector(algorithm="Ryser") + sage: B.rook_vector(algorithm='Ryser') [1, x^2 + x*y + x + 2*y + 1, 2*x^2*y + x*y^2 + x^2 + y^2 + y] TESTS:: - sage: matrix([[0,0],[0,0]]).rook_vector(algorithm="ButeraPernici") + sage: matrix([[0,0],[0,0]]).rook_vector(algorithm='ButeraPernici') [1, 0, 0] - sage: matrix([[0,0],[0,0]]).rook_vector(algorithm="Ryser") + sage: matrix([[0,0],[0,0]]).rook_vector(algorithm='Ryser') [1, 0, 0] - sage: matrix([[0,0],[0,0]]).rook_vector(algorithm="Godsil") # needs sage.graphs sage.libs.flint + sage: matrix([[0,0],[0,0]]).rook_vector(algorithm='Godsil') # needs sage.graphs sage.libs.flint [1, 0, 0] sage: matrix.ones(4, 2).rook_vector("Ryser") [1, 8, 12] @@ -1993,7 +1990,7 @@ cdef class Matrix(Matrix1): algorithm = "ButeraPernici" # we first run through the coefficients of the matrix to compute the - # number of non-zero coefficients and to see whether or not it contains + # number of nonzero coefficients and to see whether or not it contains # only elements in {0,1}... but this is not always needed if complement or use_complement is None or algorithm == "Godsil": # z2 flag is True if all coefficients belong to {0,1} @@ -2027,7 +2024,7 @@ cdef class Matrix(Matrix1): complement = not complement elif algorithm == "Ryser": - b = [self.permanental_minor(k, algorithm="Ryser") + b = [self.permanental_minor(k, algorithm='Ryser') for k in range(mn + 1)] elif algorithm == "ButeraPernici": @@ -2061,7 +2058,7 @@ cdef class Matrix(Matrix1): def minors(self, k): r""" - Return the list of all `k \times k` minors of self. + Return the list of all `k \times k` minors of ``self``. Let `A` be an `m \times n` matrix and `k` an integer with `0 \leq k`, `k \leq m` and `k \leq n`. @@ -2145,18 +2142,18 @@ cdef class Matrix(Matrix1): naive formula. In the specific case of matrices over the integers modulo a non-prime, the determinant of a lift is computed over the integers. In general, the characteristic polynomial is computed either using - the Hessenberg form (specified by ``"hessenberg"``) or the generic - division-free algorithm (specified by ``"df"``). When the base ring - is an exact field, the default choice is ``"hessenberg"``, otherwise - it is ``"df"``. Note that for matrices over most rings, more + the Hessenberg form (specified by ``'hessenberg'``) or the generic + division-free algorithm (specified by ``'df'``). When the base ring + is an exact field, the default choice is ``'hessenberg'``, otherwise + it is ``'df'``. Note that for matrices over most rings, more sophisticated algorithms can be used. (Type ``A.determinant?`` to see what is done for a specific matrix ``A``.) INPUT: - - ``algorithm`` -- string: - - ``"df"`` -- Generic O(n^4) division-free algorithm - - ``"hessenberg"`` -- Use the Hessenberg form of the matrix + - ``algorithm`` -- string; one of + - ``'df'`` -- generic O(n^4) division-free algorithm + - ``'hessenberg'`` -- use the Hessenberg form of the matrix EXAMPLES:: @@ -2319,7 +2316,7 @@ cdef class Matrix(Matrix1): # seems to be quite large for Q[x].) if (algorithm is None and R in _Fields and R.is_exact()) or (algorithm == "hessenberg"): try: - charp = self.charpoly('x', algorithm="hessenberg") + charp = self.charpoly('x', algorithm='hessenberg') except ValueError: # Hessenberg algorithm not supported, so we use whatever the default algorithm is. charp = self.charpoly('x') @@ -2340,7 +2337,7 @@ cdef class Matrix(Matrix1): var = 'A0123456789' if isinstance(R, sage.rings.abc.SymbolicRing) else 'x' try: - charp = self.charpoly(var, algorithm="df") + charp = self.charpoly(var, algorithm='df') except ValueError: # Division free algorithm not supported, so we use whatever the default algorithm is. charp = self.charpoly(var) @@ -2354,7 +2351,7 @@ cdef class Matrix(Matrix1): cdef _det_by_minors(self, Py_ssize_t level): """ Compute the determinant of the upper-left level x level submatrix - of self. Does not handle degenerate cases, level MUST be >= 2 + of ``self``. Does not handle degenerate cases, level MUST be >= 2 """ cdef Py_ssize_t i if level == 2: @@ -2460,14 +2457,14 @@ cdef class Matrix(Matrix1): INPUT: - - ``algorithm`` (default: ``None``) -- string, the algorithm to use; - currently the following algorithms have been implemented: + - ``algorithm`` -- string (default: ``None``); the algorithm to use. + Currently the following algorithms have been implemented: * ``'bfl'`` -- using the Bär-Faddeev-LeVerrier algorithm * ``'definition'`` -- using the definition given by perfect matchings - - ``check`` (default: ``True``) -- boolean determining whether to + - ``check`` -- boolean (default: ``True``); whether to check ``self`` for alternatingness and squareness. This has to be set to ``False`` if ``self`` is defined over a non-discrete ring. @@ -2612,7 +2609,6 @@ cdef class Matrix(Matrix1): sage: A.pfaffian() # needs sage.combinat 2 - """ pf = self.fetch('pfaffian') # check out cache @@ -2680,12 +2676,10 @@ cdef class Matrix(Matrix1): def _pf_perfect_matchings(self): r""" - Computes the Pfaffian of ``self`` using the definition given by perfect + Compute the Pfaffian of ``self`` using the definition given by perfect matchings. - OUTPUT: - - - an element of the base ring of ``self`` representing the Pfaffian + OUTPUT: an element of the base ring of ``self`` representing the Pfaffian EXAMPLES:: @@ -2697,7 +2691,6 @@ cdef class Matrix(Matrix1): ....: (1/2, -3/2, -1, -5/2, -1/2, 0)]) sage: A._pf_perfect_matchings() # needs sage.combinat -1/2 - """ R = self._base_ring k = self._nrows @@ -2723,7 +2716,7 @@ cdef class Matrix(Matrix1): cdef _pf_bfl(self): r""" - Computes the Pfaffian of ``self`` using the Baer-Faddeev-LeVerrier + Compute the Pfaffian of ``self`` using the Baer-Faddeev-LeVerrier algorithm. .. WARNING:: @@ -2755,7 +2748,6 @@ cdef class Matrix(Matrix1): sage: A = A - A.transpose() sage: A.pfaffian(algorithm='bfl') == A._pf_perfect_matchings() # needs sage.combinat True - """ cdef Py_ssize_t n = self._ncols cdef Py_ssize_t q = n // 2 @@ -2788,10 +2780,8 @@ cdef class Matrix(Matrix1): INPUT: - - - ``phi`` -- a morphism, so phi is callable and - phi.domain() and phi.codomain() are defined. The codomain must be a - ring. + - ``phi`` -- a morphism, so ``phi`` is callable and ``phi.domain()`` + and ``phi.codomain()`` are defined. The codomain must be a ring OUTPUT: a matrix over the codomain of phi @@ -2836,11 +2826,12 @@ cdef class Matrix(Matrix1): INPUT: - - ``sparse`` -- True to make the output a sparse matrix; default: ``False`` + - ``sparse`` -- boolean (default: ``False); ``True`` to make the output + a sparse matrix - - ``phi`` -- arbitrary Python function or callable object + - ``phi`` -- arbitrary Python function or callable object - - ``R`` -- (optional) ring + - ``R`` -- (optional) ring OUTPUT: a matrix over R @@ -2871,7 +2862,7 @@ cdef class Matrix(Matrix1): Full MatrixSpace of 3 by 3 dense matrices over Finite Field in a of size 3^2 - If self is subdivided, the result will be as well:: + If ``self`` is subdivided, the result will be as well:: sage: m = matrix(2, 2, srange(4)) sage: m.subdivide(None, 1); m @@ -2969,7 +2960,7 @@ cdef class Matrix(Matrix1): def minimal_polynomial(self, var='x', **kwds): r""" - This is a synonym for ``self.minpoly`` + This is a synonym for ``self.minpoly``. EXAMPLES:: @@ -2983,7 +2974,7 @@ cdef class Matrix(Matrix1): def minpoly(self, var='x', **kwds): r""" - Return the minimal polynomial of self. + Return the minimal polynomial of ``self``. This uses a simplistic - and potentially very very slow - algorithm that involves computing kernels to determine the powers of the @@ -3060,7 +3051,7 @@ cdef class Matrix(Matrix1): def charpoly(self, var='x', algorithm=None): r""" - Returns the characteristic polynomial of self, as a polynomial over + Return the characteristic polynomial of self, as a polynomial over the base ring. ALGORITHM: @@ -3069,8 +3060,8 @@ cdef class Matrix(Matrix1): In the generic case of matrices over a ring (commutative and with unity), there is a division-free algorithm, which can be accessed - using ``"df"``, with complexity `O(n^4)`. Alternatively, by - specifying ``"hessenberg"``, this method computes the Hessenberg + using ``'df'``, with complexity `O(n^4)`. Alternatively, by + specifying ``'hessenberg'``, this method computes the Hessenberg form of the matrix and then reads off the characteristic polynomial. Moreover, for matrices over number fields, this method can use PARI's charpoly implementation instead. @@ -3090,10 +3081,10 @@ cdef class Matrix(Matrix1): INPUT: - - ``var`` -- a variable name (default: 'x') - - ``algorithm`` -- string: - - ``"df"`` -- Generic `O(n^4)` division-free algorithm - - ``"hessenberg"`` -- Use the Hessenberg form of the matrix + - ``var`` -- a variable name (default: ``'x'``) + - ``algorithm`` -- string; one of + - ``'df'`` -- generic `O(n^4)` division-free algorithm + - ``'hessenberg'`` -- use the Hessenberg form of the matrix EXAMPLES: @@ -3226,7 +3217,6 @@ cdef class Matrix(Matrix1): y^2 - 3.00000000000000*y - 2.00000000000000 sage: A._cache['charpoly'] x^2 - 3.00000000000000*x - 2.00000000000000 - """ f = self.fetch('charpoly') if f is not None: @@ -3256,15 +3246,13 @@ cdef class Matrix(Matrix1): def _charpoly_df(self, var='x'): r""" - Computes the characteristic polynomial of ``self`` without divisions. + Compute the characteristic polynomial of ``self`` without divisions. INPUT: - ``var`` -- a variable name (default: ``'x'``) - OUTPUT: - - - polynomial -- the characteristic polynomial of ``self`` + OUTPUT: polynomial; the characteristic polynomial of ``self`` EXAMPLES: @@ -3330,7 +3318,6 @@ cdef class Matrix(Matrix1): Note that there is a missing minus sign in front of the last term in the penultimate line of Algorithm 3.1. - """ # Validate assertions @@ -3410,11 +3397,11 @@ cdef class Matrix(Matrix1): def fcp(self, var='x'): """ - Return the factorization of the characteristic polynomial of self. + Return the factorization of the characteristic polynomial of ``self``. INPUT: - - ``var`` -- (default: 'x') name of variable of charpoly + - ``var`` -- (default: ``'x'``) name of variable of charpoly EXAMPLES:: @@ -3431,10 +3418,10 @@ cdef class Matrix(Matrix1): def denominator(self): r""" Return the least common multiple of the denominators of the - elements of self. + elements of ``self``. If there is no denominator function for the base field, or no LCM - function for the denominators, raise a TypeError. + function for the denominators, raise a :exc:`TypeError`. EXAMPLES:: @@ -3540,13 +3527,11 @@ cdef class Matrix(Matrix1): def trace(self): """ Return the trace of self, which is the sum of the diagonal entries - of self. + of ``self``. INPUT: - - - ``self`` -- a square matrix - + - ``self`` -- a square matrix OUTPUT: element of the base ring of self @@ -3577,7 +3562,7 @@ cdef class Matrix(Matrix1): def trace_of_product(self, Matrix other): """ - Returns the trace of self * other without computing the entire product. + Return the trace of ``self * other`` without computing the entire product. EXAMPLES:: @@ -3599,7 +3584,7 @@ cdef class Matrix(Matrix1): ##################################################################################### def hessenberg_form(self): """ - Return Hessenberg form of self. + Return Hessenberg form of ``self``. If the base ring is merely an integral domain (and not a field), the Hessenberg form will (in general) only be defined over the @@ -3640,7 +3625,7 @@ cdef class Matrix(Matrix1): def hessenbergize(self): """ - Transform self to Hessenberg form. + Transform ``self`` to Hessenberg form. The hessenberg form of a matrix `A` is a matrix that is similar to `A`, so has the same characteristic polynomial @@ -3697,7 +3682,7 @@ cdef class Matrix(Matrix1): zero = self._base_ring(0) one = self._base_ring(1) for m from 1 <= m < n-1: - # Search for a non-zero entry in column m-1 + # Search for a nonzero entry in column m-1 i = -1 for r from m+1 <= r < n: if not self.get_is_zero_unsafe(r, m-1): @@ -3735,16 +3720,16 @@ cdef class Matrix(Matrix1): def _charpoly_hessenberg(self, var): """ - Transforms self in place to its Hessenberg form then computes and + Transform ``self`` in place to its Hessenberg form then computes and returns the coefficients of the characteristic polynomial of this matrix. INPUT: - - ``var`` -- name of the indeterminate of the charpoly + - ``var`` -- name of the indeterminate of the charpoly The characteristic polynomial is represented as a vector of ints, - where the constant term of the characteristic polynomial is the 0th + where the constant term of the characteristic polynomial is the `0`-th coefficient of the vector. EXAMPLES:: @@ -3763,7 +3748,7 @@ cdef class Matrix(Matrix1): if self._nrows != self._ncols: raise ArithmeticError("charpoly not defined for non-square matrix.") - # Replace self by its Hessenberg form + # Replace ``self`` by its Hessenberg form # (note the entries might now live in the fraction field) cdef Matrix H H = self.hessenberg_form() @@ -4117,25 +4102,25 @@ cdef class Matrix(Matrix1): def right_kernel_matrix(self, *args, **kwds): r""" - Returns a matrix whose rows form a basis + Return a matrix whose rows form a basis for the right kernel of ``self``. INPUT: - - ``algorithm`` -- (default: 'default'); a keyword that selects the + - ``algorithm`` -- (default: ``'default'``) a keyword that selects the algorithm employed. Allowable values are: - - 'default' -- allows the algorithm to be chosen automatically - - 'generic' -- naive algorithm usable for matrices over any field - - 'flint' -- FLINT library code for matrices over the rationals + - ``'default'`` -- allows the algorithm to be chosen automatically + - ``'generic'`` -- naive algorithm usable for matrices over any field + - ``'flint'`` -- FLINT library code for matrices over the rationals or the integers - - 'pari' -- PARI library code for matrices over number fields + - ``'pari'`` -- PARI library code for matrices over number fields or the integers - - 'padic' -- padic algorithm from IML library for matrices + - ``'padic'`` -- padic algorithm from IML library for matrices over the rationals and integers - - 'pluq' -- PLUQ matrix factorization for matrices mod 2 + - ``'pluq'`` -- PLUQ matrix factorization for matrices mod 2 - - ``basis`` -- (default: 'default'); a keyword that describes + - ``basis`` -- (default: ``'default'``) a keyword that describes the format of the basis returned. Allowable values are: - 'default': uses 'echelon' over fields; 'computed' otherwise. @@ -4789,7 +4774,7 @@ cdef class Matrix(Matrix1): def left_kernel_matrix(self, *args, **kwds): r""" - Returns a matrix whose rows form a basis for the left kernel + Return a matrix whose rows form a basis for the left kernel of ``self``. This method is a thin wrapper around :meth:`right_kernel_matrix`. @@ -4807,7 +4792,7 @@ cdef class Matrix(Matrix1): def right_kernel(self, *args, **kwds): r""" - Returns the right kernel of this matrix, as a vector space or + Return the right kernel of this matrix, as a vector space or free module. This is the set of vectors ``x`` such that ``self*x = 0``. .. NOTE:: @@ -4820,20 +4805,20 @@ cdef class Matrix(Matrix1): INPUT: - - ``algorithm`` -- (default: 'default'); a keyword that selects the + - ``algorithm`` -- (default: ``'default'``) a keyword that selects the algorithm employed. Allowable values are: - - 'default' -- allows the algorithm to be chosen automatically - - 'generic' -- naive algorithm usable for matrices over any field - - 'flint' -- FLINT library code for matrices over the rationals + - ``'default'`` -- allows the algorithm to be chosen automatically + - ``'generic'`` -- naive algorithm usable for matrices over any field + - ``'flint'`` -- FLINT library code for matrices over the rationals or the integers - - 'pari' -- PARI library code for matrices over number fields + - ``'pari'`` -- PARI library code for matrices over number fields or the integers - - 'padic' -- padic algorithm from IML library for matrices + - ``'padic'`` -- padic algorithm from IML library for matrices over the rationals and integers - - 'pluq' -- PLUQ matrix factorization for matrices mod 2 + - ``'pluq'`` -- PLUQ matrix factorization for matrices mod 2 - - ``basis`` -- (default: 'echelon'); a keyword that describes the + - ``basis`` -- (default: ``'echelon'``) a keyword that describes the format of the basis used to construct the right kernel. Allowable values are: @@ -4988,7 +4973,7 @@ cdef class Matrix(Matrix1): For matrices over the integers, several options are possible. The basis can be an LLL-reduced basis or an echelon basis. The pivot basis isnot available. A heuristic will decide whether - to use a p-adic algorithm from the IML library or an algorithm + to use a `p`-adic algorithm from the IML library or an algorithm from the PARI library. Note how specifying the algorithm can mildly influence the LLL basis. :: @@ -5175,7 +5160,7 @@ cdef class Matrix(Matrix1): def left_kernel(self, *args, **kwds): r""" - Returns the left kernel of this matrix, as a vector space or free module. + Return the left kernel of this matrix, as a vector space or free module. This is the set of vectors ``x`` such that ``x*self = 0``. .. NOTE:: @@ -5188,20 +5173,20 @@ cdef class Matrix(Matrix1): INPUT: - - ``algorithm`` -- (default: 'default'); a keyword that selects the + - ``algorithm`` -- (default: ``'default'``) a keyword that selects the algorithm employed. Allowable values are: - - 'default' -- allows the algorithm to be chosen automatically - - 'generic' -- naive algorithm usable for matrices over any field - - 'flint' -- FLINT library code for matrices over the rationals + - ``'default'`` -- allows the algorithm to be chosen automatically + - ``'generic'`` -- naive algorithm usable for matrices over any field + - ``'flint'`` -- FLINT library code for matrices over the rationals or the integers - - 'pari' -- PARI library code for matrices over number fields + - ``'pari'`` -- PARI library code for matrices over number fields or the integers - - 'padic' -- padic algorithm from IML library for matrices + - ``'padic'`` -- padic algorithm from IML library for matrices over the rationals and integers - - 'pluq' -- PLUQ matrix factorization for matrices mod 2 + - ``'pluq'`` -- PLUQ matrix factorization for matrices mod 2 - - ``basis`` -- (default: 'echelon'); a keyword that describes + - ``basis`` -- (default: ``'echelon'``) a keyword that describes the format of the basis used to construct the left kernel. Allowable values are: @@ -5331,29 +5316,27 @@ cdef class Matrix(Matrix1): def kernel_on(self, V, poly=None, check=True): """ - Return the kernel of self restricted to the invariant subspace V. - The result is a vector subspace of V, which is also a subspace + Return the kernel of ``self`` restricted to the invariant subspace `V`. + The result is a vector subspace of `V`, which is also a subspace of the ambient space. INPUT: - ``V`` -- vector subspace - - ``check`` -- (optional) default: ``True``; whether to check that - V is invariant under the action of self. + - ``check`` -- boolean (default: ``True``); whether to check that + `V` is invariant under the action of ``self`` - - ``poly`` -- (optional) default: None; if not None, compute instead - the kernel of poly(self) on V. - - OUTPUT: + - ``poly`` -- (default: ``None``) if not ``None``, compute instead + the kernel of ``poly(self)`` on `V` - - a subspace + OUTPUT: a subspace .. warning:: - This function does *not* check that V is in fact - invariant under self if check is False. With check False this - function is much faster. + This function does *not* check that `V` is in fact + invariant under ``self`` if check is ``False``. With check + ``False`` this function is much faster. EXAMPLES:: @@ -5433,7 +5416,7 @@ cdef class Matrix(Matrix1): Assume that the base field of this matrix has a numerator and denominator functions for its elements, e.g., it is the rational numbers or a fraction field. This function computes a basis over - the integers for the kernel of self. + the integers for the kernel of ``self``. If the matrix is not coercible into QQ, then the PID itself should be given as a second argument, as in the third example below. @@ -5469,7 +5452,6 @@ cdef class Matrix(Matrix1): with defining polynomial x^2 - x + 2 Echelon basis matrix: [ -1 -w + 1] - """ try: A, _ = self._clear_denom() @@ -5519,7 +5501,7 @@ cdef class Matrix(Matrix1): def row_module(self, base_ring=None): """ Return the free module over the base ring spanned by the rows of - self. + ``self``. EXAMPLES:: @@ -5619,7 +5601,7 @@ cdef class Matrix(Matrix1): def decomposition(self, algorithm='spin', is_diagonalizable=False, dual=False): """ - Returns the decomposition of the free module on which this matrix A + Return the decomposition of the free module on which this matrix A acts from the right (i.e., the action is x goes to x A), along with whether this matrix acts irreducibly on each factor. The factors are guaranteed to be sorted in the same way as the corresponding @@ -5637,38 +5619,34 @@ cdef class Matrix(Matrix1): INPUT: + - ``self`` -- a matrix - - ``self`` -- a matrix - - - ``algorithm`` -- 'spin' (default): algorithm involves - iterating the action of self on a vector. 'kernel': naively just - compute `ker(f_i(A))` for each factor `f_i`. + - ``algorithm`` -- string (default: ``'spin'``); ``'spin'``: involves + iterating the action of ``self`` on a vector. ``'kernel'``: naively + just compute `ker(f_i(A))` for each factor `f_i`. - - ``dual`` -- bool (default: ``False``): If True, also - returns the corresponding decomposition of V under the action of - the transpose of A. The factors are guaranteed to correspond. + - ``dual`` -- boolean (default: ``False``); if True, also + returns the corresponding decomposition of V under the action of + the transpose of A. The factors are guaranteed to correspond. - - ``is_diagonalizable`` -- if the matrix is known to - be diagonalizable, set this to True, which might speed up the - algorithm in some cases. + - ``is_diagonalizable`` -- if the matrix is known to + be diagonalizable, set this to True, which might speed up the + algorithm in some cases. .. NOTE:: If the base ring is not a field, the kernel algorithm is used. - OUTPUT: - - ``Sequence`` -- list of pairs (V,t), where V is a vector - spaces and t is a bool, and t is True exactly when the - charpoly of self on V is irreducible. - + spaces and t is a boolean, and t is ``True`` exactly when the + charpoly of ``self`` on V is irreducible. - (optional) list -- list of pairs (W,t), where W is a vector - space and t is a bool, and t is True exactly when the - charpoly of the transpose of self on W is irreducible. + space and t is a boolean, and t is ``True`` exactly when the + charpoly of the transpose of ``self`` on W is irreducible. EXAMPLES:: @@ -5718,7 +5696,7 @@ cdef class Matrix(Matrix1): - ``self`` -- a matrix with field entries - OUTPUT: a list of reduced row echelon form basis + OUTPUT: list of reduced row echelon form basis """ if not self.is_square(): raise ValueError("self must be a square matrix") @@ -5853,9 +5831,9 @@ cdef class Matrix(Matrix1): def decomposition_of_subspace(self, M, check_restrict=True, **kwds): """ - Suppose the right action of self on M leaves M invariant. Return + Suppose the right action of ``self`` on M leaves M invariant. Return the decomposition of M as a list of pairs (W, is_irred) where - is_irred is True if the charpoly of self acting on the factor W is + is_irred is ``True`` if the charpoly of ``self`` acting on the factor W is irreducible. Additional inputs besides M are passed onto the decomposition @@ -5863,10 +5841,10 @@ cdef class Matrix(Matrix1): INPUT: - - `M` -- A subspace of the free module ``self`` acts on. - - ``check_restrict`` -- A boolean (default: ``True``); Call restrict - with or without check. - - ``kwds`` -- Keywords that will be forwarded to :meth:`~.decomposition`. + - ``M`` -- a subspace of the free module ``self`` acts on + - ``check_restrict`` -- boolean (default: ``True``); call restrict + with or without check + - ``kwds`` -- keywords that will be forwarded to :meth:`~.decomposition` EXAMPLES:: @@ -5962,18 +5940,16 @@ cdef class Matrix(Matrix1): def restrict(self, V, check=True): """ - Returns the matrix that defines the action of self on the chosen + Return the matrix that defines the action of ``self`` on the chosen basis for the invariant subspace V. If V is an ambient, returns - self (not a copy of self). + ``self`` (not a copy of self). INPUT: + - ``V`` -- vector subspace - - ``V`` -- vector subspace - - - ``check`` -- (optional) default: ``True``; if False may - not check that V is invariant (hence can be faster). - + - ``check`` -- boolean (default: ``True``); if ``False`` may + not check that V is invariant (hence can be faster) OUTPUT: a matrix @@ -6035,15 +6011,14 @@ cdef class Matrix(Matrix1): def restrict_domain(self, V): """ Compute the matrix relative to the basis for V on the domain - obtained by restricting self to V, but not changing the codomain of + obtained by restricting ``self`` to V, but not changing the codomain of the matrix. This is the matrix whose rows are the images of the basis for V. INPUT: - - - ``V`` -- vector space (subspace of ambient space on - which self acts) + - ``V`` -- vector space (subspace of ambient space on + which ``self`` acts) .. SEEALSO:: @@ -6067,8 +6042,8 @@ cdef class Matrix(Matrix1): def restrict_codomain(self, V): r""" - Suppose that self defines a linear map from some domain to a - codomain that contains `V` and that the image of self is + Suppose that ``self`` defines a linear map from some domain to a + codomain that contains `V` and that the image of ``self`` is contained in `V`. This function returns a new matrix `A` that represents this linear map but as a map to `V`, in the sense that if `x` is in the domain, @@ -6077,10 +6052,8 @@ cdef class Matrix(Matrix1): INPUT: - - - ``V`` -- vector space (space of degree - ``self.ncols()``) that contains the image of self. - + - ``V`` -- vector space (space of degree + ``self.ncols()``) that contains the image of ``self`` .. SEEALSO:: @@ -6110,23 +6083,17 @@ cdef class Matrix(Matrix1): def maxspin(self, v): """ - Computes the largest integer n such that the list of vectors + Compute the largest integer n such that the list of vectors `S=[v, v*A, ..., v * A^n]` are linearly independent, and returns that list. INPUT: + - ``self`` -- matrix - - ``self`` -- Matrix - - - ``v`` -- Vector - - - OUTPUT: - - - - ``list`` -- list of Vectors + - ``v`` -- vector + OUTPUT: list of Vectors ALGORITHM: The current implementation just adds vectors to a vector space until the dimension doesn't grow. This could be optimized by @@ -6169,17 +6136,15 @@ cdef class Matrix(Matrix1): def wiedemann(self, i, t=0): """ - Application of Wiedemann's algorithm to the i-th standard basis + Application of Wiedemann's algorithm to the `i`-th standard basis vector. INPUT: + - ``i`` -- integer - - ``i`` -- an integer - - - ``t`` -- an integer (default: 0) if t is nonzero, use - only the first t linear recurrence relations. - + - ``t`` -- integer (default: 0); if t is nonzero, use + only the first t linear recurrence relations IMPLEMENTATION: This is a toy implementation. @@ -6243,7 +6208,7 @@ cdef class Matrix(Matrix1): EXAMPLES: - Pass-through first. :: + Pass-through first:: sage: A = matrix(QQ, 2, range(4)) sage: A._eigenspace_format('all') == 'all' @@ -6295,16 +6260,16 @@ cdef class Matrix(Matrix1): INPUT: - ``self`` -- a square matrix over an exact field. For inexact - matrices consult the numerical or symbolic matrix classes. + matrices consult the numerical or symbolic matrix classes - ``format`` -- one of: - - ``'all'`` -- Attempts to create every eigenspace. This will - always be possible for matrices with rational entries. - - ``'galois'`` -- For each irreducible factor of the characteristic + - ``'all'`` -- attempts to create every eigenspace. This will + always be possible for matrices with rational entries + - ``'galois'`` -- for each irreducible factor of the characteristic polynomial, a single eigenspace will be output for a - single root/eigenvalue for the irreducible factor. - - ``None`` (default) -- Uses the ``'all'`` format if the base ring is contained + single root/eigenvalue for the irreducible factor + - ``None`` -- default; uses the ``'all'`` format if the base ring is contained in an algebraically closed field which is implemented. Otherwise, uses the ``'galois'`` format. @@ -6316,7 +6281,7 @@ cdef class Matrix(Matrix1): the irreducible factors of the characteristic polynomial, even for linear factors. - - ``algebraic_multiplicity`` -- (boolean, default: ``False``); + - ``algebraic_multiplicity`` -- boolean (default: ``False``); whether to include the algebraic multiplicity of each eigenvalue in the output. See the discussion below. @@ -6665,20 +6630,20 @@ cdef class Matrix(Matrix1): INPUT: - ``self`` -- a square matrix over an exact field. For inexact - matrices consult the numerical or symbolic matrix classes. + matrices consult the numerical or symbolic matrix classes - - ``format`` -- default: ``None`` + - ``format`` -- (default: ``None``) - ``'all'`` -- attempts to create every eigenspace. This will - always be possible for matrices with rational entries. + always be possible for matrices with rational entries - ``'galois'`` -- for each irreducible factor of the characteristic polynomial, a single eigenspace will be output for a - single root/eigenvalue for the irreducible factor. - - ``None`` -- Uses the 'all' format if the base ring is contained + single root/eigenvalue for the irreducible factor + - ``None`` -- uses the 'all' format if the base ring is contained in an algebraically closed field which is implemented. Otherwise, uses the 'galois' format. - - ``var`` -- (default: 'a'); variable name used to + - ``var`` -- (default: ``'a'``) variable name used to represent elements of the root field of each irreducible factor of the characteristic polynomial. If var='a', then the root fields will be in terms of @@ -6686,7 +6651,7 @@ cdef class Matrix(Matrix1): the irreducible factors of the characteristic polynomial, even for linear factors. - - ``algebraic_multiplicity`` -- (default: ``False``); whether or + - ``algebraic_multiplicity`` -- (default: ``False``) whether or not to include the algebraic multiplicity of each eigenvalue in the output. See the discussion below. @@ -7588,7 +7553,6 @@ cdef class Matrix(Matrix1): sage: D, P = A.eigenmatrix_right() sage: (A*P - P*D).norm() < 10^(-2) True - """ D, P = self.transpose().eigenmatrix_left(None if other is None else other.transpose()) @@ -7744,13 +7708,13 @@ cdef class Matrix(Matrix1): def _echelonize_ring(self, **kwds): r""" - Echelonize self in place, where the base ring of self is assumed to + Echelonize ``self`` in place, where the base ring of ``self`` is assumed to be a ring (not a field). Right now this *only* works over ZZ and some principal ideal domains; - otherwise a ``NotImplementedError`` is raised. In the special case of + otherwise a :exc:`NotImplementedError` is raised. In the special case of sparse matrices over ZZ it makes them dense, gets the echelon form of - the dense matrix, then sets self equal to the result. + the dense matrix, then sets ``self`` equal to the result. EXAMPLES:: @@ -7829,10 +7793,10 @@ cdef class Matrix(Matrix1): else: return - def echelonize(self, algorithm="default", cutoff=0, **kwds): + def echelonize(self, algorithm='default', cutoff=0, **kwds): r""" Transform ``self`` into a matrix in echelon form over the same - base ring as self. + base ring as ``self``. .. NOTE:: @@ -7863,10 +7827,10 @@ cdef class Matrix(Matrix1): - ``'strassen'``: use a Strassen divide and conquer algorithm (if available) - - ``cutoff`` -- integer. Only used if the Strassen algorithm - is selected. + - ``cutoff`` -- integer; only used if the Strassen algorithm + is selected - - ``transformation`` -- boolean. Whether to also return the + - ``transformation`` -- boolean; whether to also return the transformation matrix. Some matrix backends do not provide this information, in which case this option is ignored. @@ -7927,7 +7891,7 @@ cdef class Matrix(Matrix1): [ 1 y/x] [ 0 0] - We check that the echelon form works for matrices over p-adics. + We check that the echelon form works for matrices over `p`-adics. See :issue:`17272`:: sage: # needs sage.rings.padics @@ -8022,7 +7986,7 @@ cdef class Matrix(Matrix1): except ArithmeticError as msg: raise NotImplementedError("%s\nEchelon form not implemented over '%s'."%(msg, basring)) - def echelon_form(self, algorithm="default", cutoff=0, **kwds): + def echelon_form(self, algorithm='default', cutoff=0, **kwds): r""" Return the echelon form of ``self``. @@ -8046,7 +8010,7 @@ cdef class Matrix(Matrix1): - ``'partial_pivoting'``: Gauss elimination, using partial pivoting (if base ring has absolute value) - - ``'scaled_partial_pivoting'``: Gauss elimination, using scaled + - ``'scaled_partial_pivoting'`` -- Gauss elimination, using scaled partial pivoting (if base ring has absolute value) - ``'scaled_partial_pivoting_valuation'``: Gauss elimination, using @@ -8055,16 +8019,16 @@ cdef class Matrix(Matrix1): - ``'strassen'``: use a Strassen divide and conquer algorithm (if available) - - ``cutoff`` -- integer. Only used if the Strassen algorithm is selected. + - ``cutoff`` -- integer; only used if the Strassen algorithm is selected - - ``transformation`` -- boolean. Whether to also return the + - ``transformation`` -- boolean; whether to also return the transformation matrix. Some matrix backends do not provide this information, in which case this option is ignored. OUTPUT: The reduced row echelon form of ``self``, as an immutable - matrix. Note that self is *not* changed by this command. Use + matrix. Note that ``self`` is *not* changed by this command. Use :meth:`echelonize` to change ``self`` in place. If the optional parameter ``transformation=True`` is @@ -8362,7 +8326,7 @@ cdef class Matrix(Matrix1): def _echelon_in_place_classical(self): """ - Transform self into echelon form and return the pivots of self. + Transform ``self`` into echelon form and return the pivots of ``self``. EXAMPLES:: @@ -8387,11 +8351,11 @@ cdef class Matrix(Matrix1): INPUT: - - ``subdivide`` -- (boolean, default: ``False``) whether to + - ``subdivide`` -- boolean (default: ``False``); whether to subdivide the returned matrix. See the description of the (output) below for details. - ``kwds`` -- additional keywords that can be passed to - the method that computes the echelon form. + the method that computes the echelon form OUTPUT: @@ -8403,7 +8367,7 @@ cdef class Matrix(Matrix1): If ``subdivide`` is ``True`` then the returned matrix has a single division among the columns and a single division among the rows. The column subdivision has `n` columns to the left and `m` - columns to the right. The row division separates the non-zero rows + columns to the right. The row division separates the nonzero rows from the zero rows, when restricted to the first `n` columns. For a nonsingular matrix the final `m` columns of the extended @@ -8590,9 +8554,7 @@ cdef class Matrix(Matrix1): a matrix under row and column permutations. See :meth:`automorphisms_of_rows_and_columns`. - OUTPUT: - - - A bipartite graph. + OUTPUT: a bipartite graph EXAMPLES:: @@ -8686,14 +8648,12 @@ cdef class Matrix(Matrix1): INPUT: - - ``check`` -- (default: ``False``) If ``True`` return a tuple of + - ``check`` -- boolean (default: ``False``); if ``True`` return a tuple of the maximal matrix and the permutations taking ``self`` to the maximal matrix. If ``False``, return only the maximal matrix. - OUTPUT: - - The maximal matrix. + OUTPUT: the maximal matrix EXAMPLES:: @@ -8863,18 +8823,16 @@ cdef class Matrix(Matrix1): INPUT: - - ``N`` -- a matrix. + - ``N`` -- a matrix - - ``check`` -- boolean (default: ``False``). If ``False`` - return Boolean indicating whether there exists a permutation of - rows and columns sending ``self`` to ``N`` and False otherwise. - If ``True`` return a tuple of a Boolean and a permutation mapping - ``self`` to ``N`` if such a permutation exists, and - (``False``, ``None``) if it does not. + - ``check`` -- boolean (default: ``False``); if ``False`` + return Boolean indicating whether there exists a permutation of + rows and columns sending ``self`` to ``N`` and ``False`` otherwise. + If ``True`` return a tuple of a Boolean and a permutation mapping + ``self`` to ``N`` if such a permutation exists, and + (``False``, ``None``) if it does not. - OUTPUT: - - A Boolean or a tuple of a Boolean and a permutation. + OUTPUT: a Boolean or a tuple of a Boolean and a permutation EXAMPLES:: @@ -8947,7 +8905,7 @@ cdef class Matrix(Matrix1): ##################################################################################### def _multiply_strassen(self, Matrix right, int cutoff=0): """ - Multiply self by the matrix right using a Strassen-based + Multiply ``self`` by the matrix right using a Strassen-based asymptotically fast arithmetic algorithm. ALGORITHM: Custom algorithm for arbitrary size matrices designed by @@ -8955,10 +8913,8 @@ cdef class Matrix(Matrix1): INPUT: - - - ``cutoff`` -- integer (default: 0 -- let class - decide). - + - ``cutoff`` -- integer (default: 0 -- let class + decide) EXAMPLES:: @@ -9081,7 +9037,7 @@ cdef class Matrix(Matrix1): def set_block(self, row, col, block): """ - Sets the sub-matrix of self, with upper left corner given by row, + Set the sub-matrix of self, with upper left corner given by row, col to block. EXAMPLES:: @@ -9110,7 +9066,7 @@ cdef class Matrix(Matrix1): def subdivide(self, row_lines=None, col_lines=None): r""" - Divides ``self`` into logical submatrices which can then be queried + Divide ``self`` into logical submatrices which can then be queried and extracted. If a subdivision already exists, this method forgets the @@ -9119,12 +9075,12 @@ cdef class Matrix(Matrix1): INPUT: - ``row_lines`` -- ``None``, an integer, or a list of - integers (lines at which self must be split) + integers (lines at which ``self`` must be split) - ``col_lines`` -- ``None``, an integer, or a list of - integers (columns at which self must be split) + integers (columns at which ``self`` must be split) - OUTPUT: ``None`` but changes ``self`` + OUTPUT: none but changes ``self`` .. NOTE:: @@ -9244,11 +9200,11 @@ cdef class Matrix(Matrix1): def subdivision(self, i, j): """ - Returns an immutable copy of the (i,j)th submatrix of self, + Return an immutable copy of the (i,j)th submatrix of ``self``, according to a previously set subdivision. Before a subdivision is set, the only valid arguments are (0,0) - which returns self. + which returns ``self``. EXAMPLES:: @@ -9302,7 +9258,7 @@ cdef class Matrix(Matrix1): def subdivision_entry(self, i, j, x, y): """ - Returns the x,y entry of the i,j submatrix of self. + Return the x,y entry of the i,j submatrix of ``self``. EXAMPLES:: @@ -9442,7 +9398,7 @@ cdef class Matrix(Matrix1): def subdivisions(self): """ - Returns the current subdivision of self. + Return the current subdivision of ``self``. EXAMPLES:: @@ -9471,12 +9427,12 @@ cdef class Matrix(Matrix1): def tensor_product(self, A, subdivide=True): r""" - Returns the tensor product of two matrices. + Return the tensor product of two matrices. INPUT: - ``A`` -- a matrix - - ``subdivide`` -- (default: ``True``); whether or not to return + - ``subdivide`` -- (default: ``True``) whether or not to return natural subdivisions with the matrix OUTPUT: @@ -9586,12 +9542,12 @@ cdef class Matrix(Matrix1): INPUT: - - ``density`` -- ``float`` (default: ``1``); upper bound for the - proportion of entries that are changed - - ``nonzero`` -- Bool (default: ``False``); if ``True``, then new - entries will be nonzero - - ``*args, **kwds`` -- Remaining parameters may be passed to the - ``random_element`` function of the base ring + - ``density`` -- ``float`` (default: ``1``); upper bound for the + proportion of entries that are changed + - ``nonzero`` -- boolean (default: ``False``); if ``True``, then new + entries will be nonzero + - ``*args, **kwds`` -- remaining parameters may be passed to the + ``random_element`` function of the base ring EXAMPLES: @@ -9674,7 +9630,7 @@ cdef class Matrix(Matrix1): def is_one(self): """ - Return True if this matrix is the identity matrix. + Return ``True`` if this matrix is the identity matrix. EXAMPLES:: @@ -9695,17 +9651,17 @@ cdef class Matrix(Matrix1): def is_scalar(self, a=None): """ - Return True if this matrix is a scalar matrix. + Return ``True`` if this matrix is a scalar matrix. INPUT: - - base_ring element a, which is chosen as self[0][0] if - a = None + - ``a`` -- base_ring element; chosen as ``self[0][0]`` if + ``a==None`` OUTPUT: - - whether self is a scalar matrix (in fact the scalar matrix - aI if a is input) + Whether ``self`` is a scalar matrix (in fact the scalar matrix + aI if a is input). EXAMPLES:: @@ -9745,9 +9701,7 @@ cdef class Matrix(Matrix1): """ Return ``True`` if this matrix is a diagonal matrix. - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -9775,17 +9729,15 @@ cdef class Matrix(Matrix1): return False return True - def is_triangular(self, side="lower") -> bool: + def is_triangular(self, side='lower') -> bool: """ Return ``True`` if this matrix is a triangular matrix. INPUT: - - ``side`` -- either ``"lower"`` (default) or ``"upper"`` - - OUTPUT: + - ``side`` -- either ``'lower'`` (default) or ``'upper'`` - boolean + OUTPUT: boolean EXAMPLES:: @@ -9883,7 +9835,7 @@ cdef class Matrix(Matrix1): def is_bistochastic(self, normalized=True): r""" - Returns ``True`` if this matrix is bistochastic. + Return ``True`` if this matrix is bistochastic. A matrix is said to be bistochastic if both the sums of the entries of each row and the sum of the entries of each column @@ -9931,7 +9883,7 @@ cdef class Matrix(Matrix1): def is_normal(self): r""" - Returns ``True`` if the matrix commutes with its conjugate-transpose. + Return ``True`` if the matrix commutes with its conjugate-transpose. OUTPUT: @@ -10129,7 +10081,7 @@ cdef class Matrix(Matrix1): def as_sum_of_permutations(self): r""" - Returns the current matrix as a sum of permutation matrices + Return the current matrix as a sum of permutation matrices. According to the Birkhoff-von Neumann Theorem, any bistochastic matrix can be written as a positive sum of permutation matrices, which also @@ -10179,7 +10131,7 @@ cdef class Matrix(Matrix1): def visualize_structure(self, maxsize=512): r""" - Visualize the non-zero entries + Visualize the nonzero entries. White pixels are put at positions with zero entries. If 'maxsize' is given, then the maximal dimension in either x or y direction is @@ -10191,7 +10143,7 @@ cdef class Matrix(Matrix1): INPUT: - - ``maxsize`` -- integer (default: ``512``). Maximal dimension + - ``maxsize`` -- integer (default: `512`); maximal dimension in either x or y direction of the resulting image. If ``None`` or a maxsize larger than ``max(self.nrows(),self.ncols())`` is given the image will @@ -10307,7 +10259,7 @@ cdef class Matrix(Matrix1): def inverse(self): """ - Returns the inverse of self, without changing self. + Return the inverse of self, without changing ``self``. Note that one can use the Python inverse operator to obtain the inverse as well. @@ -10354,7 +10306,6 @@ cdef class Matrix(Matrix1): sage: ~M [t^-1 t^-2] [ 0 t^-1] - """ return ~self @@ -10431,9 +10382,7 @@ cdef class Matrix(Matrix1): r""" Return the adjugate of this matrix. - OUTPUT: - - - matrix -- the adjugate of the matrix + OUTPUT: matrix; the adjugate of the matrix EXAMPLES: @@ -10520,7 +10469,6 @@ cdef class Matrix(Matrix1): Note that this method does not utilise a lookup if the adjugate has already been computed previously, and it does not cache the result. This is all left to the method `adjugate`. - """ n = self._ncols @@ -10532,12 +10480,12 @@ cdef class Matrix(Matrix1): def QR(self, full=True): r""" - Returns a factorization of ``self`` as a unitary matrix + Return a factorization of ``self`` as a unitary matrix and an upper-triangular matrix. INPUT: - - ``full`` -- (default: ``True``); if ``True`` then the + - ``full`` -- (default: ``True``) if ``True`` then the returned matrices have dimensions as described below. If ``False`` the ``R`` matrix has no zero rows and the columns of ``Q`` are a basis for the column space of @@ -10548,7 +10496,7 @@ cdef class Matrix(Matrix1): If ``self`` is an `m\times n` matrix and ``full=True`` then this method returns a pair of matrices: `Q` is an `m\times m` unitary matrix (meaning its inverse is its conjugate-transpose) and `R` - is an `m\times n` upper-triangular matrix with non-negative entries + is an `m\times n` upper-triangular matrix with nonnegative entries on the diagonal. For a matrix of full rank this factorization is unique (due to the restriction to positive entries on the diagonal). @@ -10830,7 +10778,7 @@ cdef class Matrix(Matrix1): def _gram_schmidt_noscale(self): r""" - Performs Gram-Schmidt orthogonalization, with no scaling to unit vectors. + Perform Gram-Schmidt orthogonalization, with no scaling to unit vectors. INPUT: @@ -10838,16 +10786,14 @@ cdef class Matrix(Matrix1): The base ring of the matrix needs to have its fraction field implemented. - OUTPUT: - - Two matrices, ``Q`` and ``R`` such that if ``A`` represents ``self``: + OUTPUT: two matrices, ``Q`` and ``R`` such that if ``A`` represents ``self``: - ``A = Q*R`` - The columns of ``Q`` are an orthogonal set which spans the - column space of ``A``. - - The conjugate-transpose of ``Q`` times ``Q`` is a diagonal matrix. - - ``R`` is a full-rank matrix, that has all entries below the - main diagonal equal to zero. + column space of ``A`` + - The conjugate-transpose of ``Q`` times ``Q`` is a diagonal matrix + - ``R`` -- a full-rank matrix, that has all entries below the + main diagonal equal to zero This is basically a "reduced" QR decomposition of ``self`` with the distinction that the orthogonal column vectors of ``Q`` have @@ -10958,7 +10904,7 @@ cdef class Matrix(Matrix1): zero = F(0) Bstar = [] R = zero_matrix(F, n) - nnz = 0 # number non-zero rows in R, or number of nonzero vectors in Bstar + nnz = 0 # number nonzero rows in R, or number of nonzero vectors in Bstar for i in range(n): ortho = B[i] for j in range(nnz): @@ -10977,13 +10923,13 @@ cdef class Matrix(Matrix1): def gram_schmidt(self, orthonormal=False): r""" - Performs Gram-Schmidt orthogonalization on the rows of the matrix, + Perform Gram-Schmidt orthogonalization on the rows of the matrix, returning a new matrix and a matrix accomplishing the transformation. INPUT: - - ``self`` -- a matrix whose rows are to be orthogonalized. - - ``orthonormal`` -- (default: ``False``); if ``True`` the + - ``self`` -- a matrix whose rows are to be orthogonalized + - ``orthonormal`` -- (default: ``False``) if ``True`` the returned orthogonal vectors are unit vectors. This keyword is ignored if the matrix is over ``RDF`` or ``CDF`` and the results are always orthonormal. @@ -10996,11 +10942,11 @@ cdef class Matrix(Matrix1): - ``A = M*G`` - The rows of ``G`` are an orthogonal (resp. orthonormal) - set of vectors. + set of vectors - ``G`` times the conjugate-transpose of ``G`` is a diagonal - (resp. identity) matrix. - - The row space of ``G`` equals the row space of ``A``. - - ``M`` is a full-rank matrix with zeros above the diagonal. + (resp. identity) matrix + - The row space of ``G`` equals the row space of ``A`` + - ``M`` is a full-rank matrix with zeros above the diagonal For exact rings, any zero vectors produced (when the original vectors are linearly dependent) are not output, thus the @@ -11333,18 +11279,18 @@ cdef class Matrix(Matrix1): INPUT: - - ``base_ring`` -- Ring in which to compute the Jordan form. + - ``base_ring`` -- ring in which to compute the Jordan form - - ``sparse`` -- (default ``False``) If ``sparse=True``, return a sparse - matrix. + - ``sparse`` -- (default: ``False``) if ``sparse=True``, return a sparse + matrix - - ``subdivide`` -- (default ``True``) If ``subdivide=True``, the - subdivisions for the Jordan blocks in the matrix are shown. + - ``subdivide`` -- (default: ``True``) if ``subdivide=True``, the + subdivisions for the Jordan blocks in the matrix are shown - - ``transformation`` -- (default ``False``) If ``transformation=True``, - computes also the transformation matrix. + - ``transformation`` -- (default: ``False``) if ``transformation=True``, + computes also the transformation matrix - - ``eigenvalues`` -- (default ``None``) A complete set of roots, with + - ``eigenvalues`` -- (default: ``None``) a complete set of roots, with multiplicity, of the characteristic polynomial of `A`, encoded as a list of pairs, each having the form `(r, m)` with `r` a root and `m` its multiplicity. If this is ``None``, then Sage computes this @@ -11353,7 +11299,7 @@ cdef class Matrix(Matrix1): other rings, providing this list manually is the only way to compute Jordan normal forms. - - ``check_input`` -- (default ``True``) A Boolean specifying whether + - ``check_input`` -- boolean (default: ``True``); whether the list ``eigenvalues`` (if provided) has to be checked for correctness. Set this to ``False`` for a speedup if the eigenvalues are known to be correct. @@ -12042,7 +11988,7 @@ cdef class Matrix(Matrix1): INPUT: - - ``base_field`` -- a new field to use for entries of the matrix. + - ``base_field`` -- a new field to use for entries of the matrix OUTPUT: @@ -12238,9 +12184,9 @@ cdef class Matrix(Matrix1): INPUT: - ``other`` -- a matrix, which should be square, and of the same size - as ``self``. + as ``self`` - - ``transformation`` -- (default: ``False``); if ``True``, the output + - ``transformation`` -- (default: ``False``) if ``True``, the output may include the change-of-basis matrix (also known as the similarity transformation). See below for an exact description. @@ -12308,7 +12254,7 @@ cdef class Matrix(Matrix1): provide a transformation. But Jordan form will require that the eigenvalues of the matrix can be represented within Sage, requiring the existence of the appropriate extension field. - When this is not possible, a ``RuntimeError`` is raised, as + When this is not possible, a :exc:`RuntimeError` is raised, as demonstrated in an example below. EXAMPLES: @@ -12410,7 +12356,7 @@ cdef class Matrix(Matrix1): eigenvalues of the matrix, which may not lie in the field used for entries of the matrix. In this unfortunate case, the computation of the transformation may fail with a - ``RuntimeError``, EVEN when the matrices are similar. This + :exc:`RuntimeError`, EVEN when the matrices are similar. This is not the case for matrices over the integers, rationals or algebraic numbers, since the computations are done in the algebraically closed field of algebraic numbers. @@ -12585,14 +12531,14 @@ cdef class Matrix(Matrix1): def symplectic_form(self): r""" - Find a symplectic form for self if self is an anti-symmetric, + Find a symplectic form for ``self`` if ``self`` is an anti-symmetric, alternating matrix defined over a field. Returns a pair (F, C) such that the rows of C form a symplectic - basis for self and F = C \* self \* C.transpose(). + basis for ``self`` and ``F = C \* self \* C.transpose()``. - Raises a :class:`ValueError` if not over a field, or self is not - anti-symmetric, or self is not alternating. + Raises a :exc:`ValueError` if not over a field, or ``self`` is not + anti-symmetric, or ``self`` is not alternating. Anti-symmetric means that `M = -M^t`. Alternating means that the diagonal of `M` is identically zero. @@ -12653,9 +12599,9 @@ cdef class Matrix(Matrix1): INPUT: - - ``self`` -- a square matrix over a field. + - ``self`` -- a square matrix over a field - - ``v`` -- a vector with a degree equal to the size of the matrix. + - ``v`` -- a vector with a degree equal to the size of the matrix There is no explicit error-checking, it is the responsibility of the calling routine to provide accurate input. @@ -12787,12 +12733,12 @@ cdef class Matrix(Matrix1): INPUT: - - ``self`` -- a square matrix with entries from a field. + - ``self`` -- a square matrix with entries from a field - ``v`` -- a vector with a degree equal to the size of the matrix - and entries compatible with the entries of the matrix. + and entries compatible with the entries of the matrix - - ``var`` -- (default: ``None``); if specified as a string or + - ``var`` -- (default: ``None``) if specified as a string or a generator of a polynomial ring, then this will be used to construct a polynomial reflecting a relation of linear dependence on the powers `A^iv` *and* this will cause @@ -12800,7 +12746,7 @@ cdef class Matrix(Matrix1): A generator must create polynomials with coefficients from the same field as the matrix entries. - - ``basis`` -- (default: ``echelon``); the basis for the + - ``basis`` -- (default: ``echelon``) the basis for the subspace is "echelonized" by default, but the keyword 'iterates' will return a subspace with a user basis equal to the largest linearly independent @@ -13009,16 +12955,13 @@ cdef class Matrix(Matrix1): def cholesky(self): r""" - Returns the Cholesky decomposition of a Hermitian matrix. - - INPUT: + Return the Cholesky decomposition of a Hermitian matrix. - A positive-definite matrix. Generally, the base ring for the - entries of the matrix needs to be a subfield of the algebraic - numbers (``QQbar``). Examples include the rational numbers - (``QQ``), some number fields, and real algebraic numbers and - the algebraic numbers themselves. Symbolic matrices can also - occasionally be factored. + Applies to a positive-definite matrix. Generally, the base ring for the + entries of the matrix needs to be a subfield of the algebraic numbers + (``QQbar``). Examples include the rational numbers (``QQ``), some + number fields, and real algebraic numbers and the algebraic numbers + themselves. Symbolic matrices can also occasionally be factored. OUTPUT: @@ -13031,7 +12974,7 @@ cdef class Matrix(Matrix1): where `L^\ast` is the conjugate-transpose. If the matrix is not positive-definite (for example, if it is not Hermitian) - then a ``ValueError`` results. + then a :exc:`ValueError` results. If possible, the output matrix will be over the fraction field of the base ring of the input matrix. If that fraction field @@ -13272,7 +13215,6 @@ cdef class Matrix(Matrix1): sage: all( matrix(R,[]).cholesky().is_immutable() # needs sage.rings.number_field ....: for R in (RR,CC,RDF,CDF,ZZ,QQ,AA,QQbar) ) True - """ cdef Matrix C # output matrix C = self.fetch('cholesky') @@ -13493,21 +13435,21 @@ cdef class Matrix(Matrix1): is the best choice for general routines that may call this for matrix entries of a variety of types. - - 'partial' -- each column is examined for + - ``'partial'`` -- each column is examined for the element with the largest absolute value and the - row containing this element is swapped into place. + row containing this element is swapped into place - - 'nonzero' -- the first nonzero element in a column - is located and the row with this element is used. + - ``'nonzero'`` -- the first nonzero element in a column + is located and the row with this element is used - ``format`` -- contents of output, see more discussion - below about output. + below about output - 'plu' (default) -- a triple; matrices P, L and U - such that A = P*L*U. + such that A = P*L*U - - 'compact' -- a pair; row permutation as a tuple, and the - matrices L and U combined into one matrix. + - ``'compact'`` -- a pair; row permutation as a tuple, and the + matrices L and U combined into one matrix OUTPUT: @@ -13973,14 +13915,14 @@ cdef class Matrix(Matrix1): INPUT: - ``self`` -- a matrix that is symmetric or Hermitian, - over a ring that has a fraction field implemented. + over a ring that has a fraction field implemented - ``algorithm`` -- ``'symmetric'`` or ``'hermitian'``, - according to the corresponding property of the matrix. + according to the corresponding property of the matrix - - ``check`` -- (default: ``True``); if ``True`` then + - ``check`` -- (default: ``True``) if ``True`` then performs the check that the matrix is consistent with the - ``algorithm`` keyword. + ``algorithm`` keyword OUTPUT: @@ -14000,7 +13942,7 @@ cdef class Matrix(Matrix1): the conjugate-transpose. If any leading principal submatrix is singular, then the - computation cannot be performed and a ``ValueError`` results. + computation cannot be performed and a :exc:`ValueError` results. Results are cached, and hence are immutable. Caching eliminates redundant computations across @@ -14233,16 +14175,16 @@ cdef class Matrix(Matrix1): INPUT: - - ``self`` -- a square matrix over a ring. The base ring - must have an implemented fraction field. + - ``self`` -- a square matrix over a ring; the base ring + must have an implemented fraction field - - ``algorithm`` -- default: ``'symmetric'``. Either - ``'symmetric'`` or ``'hermitian'``, according to if - the input matrix is symmetric or hermitian. + - ``algorithm`` -- (default: ``'symmetric'``) either + ``'symmetric'`` or ``'hermitian'``, according to whether + the input matrix is symmetric or hermitian - - ``check`` -- (default: ``True``); if ``True`` then + - ``check`` -- (default: ``True``) if ``True`` then performs the check that the matrix is consistent with the - ``algorithm`` keyword. + ``algorithm`` keyword OUTPUT: @@ -14263,7 +14205,7 @@ cdef class Matrix(Matrix1): If any leading principal submatrix (a square submatrix in the upper-left corner) is singular then this method will - fail with a ``ValueError``. + fail with a :exc:`ValueError`. ALGORITHM: @@ -14419,7 +14361,6 @@ cdef class Matrix(Matrix1): All of the real documentation, examples, and tests for this method can be found in the user-facing :meth:`block_ldlt` method. - """ cdef str cache_string = "_block_ldlt" if classical: @@ -14703,9 +14644,9 @@ cdef class Matrix(Matrix1): INPUT: - * ``classical`` -- (default: ``False``) whether or not to - attempt a classical non-block `LDL^{T}` factorization - with no row/column swaps. + - ``classical`` -- boolean (default: ``False``); whether or not to + attempt a classical non-block `LDL^{T}` factorization with no + row/column swaps. .. WARNING:: @@ -14727,7 +14668,7 @@ cdef class Matrix(Matrix1): With ``classical=True``, the permutation matrix `P` is always an identity matrix and the diagonal blocks are always - one-by-one. A ``ValueError`` is raised if the matrix has no + one-by-one. A :exc:`ValueError` is raised if the matrix has no classical `LDL^{T}` factorization. ALGORITHM: @@ -14974,7 +14915,6 @@ cdef class Matrix(Matrix1): sage: l,d = A.indefinite_factorization() sage: L == l and D == matrix.diagonal(d) True - """ cdef Py_ssize_t n # size of the matrices cdef Py_ssize_t i, j # loop indices @@ -15045,7 +14985,7 @@ cdef class Matrix(Matrix1): def is_positive_semidefinite(self): r""" - Returns whether or not this matrix is positive-semidefinite. + Return whether or not this matrix is positive-semidefinite. By SageMath convention, positive (semi)definite matrices must be either real symmetric or complex Hermitian. @@ -15167,7 +15107,6 @@ cdef class Matrix(Matrix1): ... ValueError: Could not see Finite Field in z2 of size 5^2 as a subring of the real or complex numbers - """ return self._is_positive_definite_or_semidefinite(True) @@ -15176,7 +15115,7 @@ cdef class Matrix(Matrix1): Determine if a matrix is positive-definite. A matrix `A` is positive definite if it - :meth:`~.Matrix.is_hermitian` and if, for every non-zero + :meth:`~.Matrix.is_hermitian` and if, for every nonzero vector `x`, .. MATH:: @@ -15194,7 +15133,7 @@ cdef class Matrix(Matrix1): INPUT: - ``self`` -- a matrix - - ``certificate`` -- (default: ``False``) return the + - ``certificate`` -- boolean (default: ``False``); return the lower-triangular and diagonal parts of the :meth:`block_ldlt` factorization when the matrix is positive-definite. Deprecated. @@ -15448,15 +15387,13 @@ cdef class Matrix(Matrix1): INPUT: + - ``f`` -- a function that is evaluated on each + element of this matrix - - ``f`` -- a function that is evaluated on each - element of this matrix. - - - ``indices`` -- whether or not to return the indices - and elements of this matrix that satisfy the function. + - ``indices`` -- whether or not to return the indices + and elements of this matrix that satisfy the function - - OUTPUT: If ``indices`` is not specified, return a + OUTPUT: if ``indices`` is not specified, return a matrix with 1 where `f` is satisfied and 0 where it is not. If ``indices`` is specified, return a dictionary containing the elements of this matrix satisfying `f`. @@ -15535,7 +15472,7 @@ cdef class Matrix(Matrix1): def conjugate(self): r""" Return the conjugate of self, i.e. the matrix whose entries are the - conjugates of the entries of self. + conjugates of the entries of ``self``. EXAMPLES:: @@ -15683,19 +15620,17 @@ cdef class Matrix(Matrix1): INPUT: + - ``self`` -- a matrix whose entries are coercible into ``CDF`` - - ``self`` -- a matrix whose entries are coercible into ``CDF`` - - - ``p`` -- one of the following options: + - ``p`` -- one of the following options: - - ``1`` -- the largest column-sum norm + - ``1`` -- the largest column-sum norm - - ``2 (default)`` -- the Euclidean norm + - ``2`` -- (default) the Euclidean norm - - ``Infinity`` -- the largest row-sum norm - - - ``'frob'`` -- the Frobenius (sum of squares) norm + - ``Infinity`` -- the largest row-sum norm + - ``'frob'`` -- the Frobenius (sum of squares) norm OUTPUT: RDF number @@ -15796,7 +15731,7 @@ cdef class Matrix(Matrix1): - ``algorithm`` -- ignored for matrices - OUTPUT: A matrix converted to a real or complex field + OUTPUT: a matrix converted to a real or complex field EXAMPLES:: @@ -15850,7 +15785,6 @@ cdef class Matrix(Matrix1): sage: M = matrix(3, [1,1,1,1,0,0,0,1,0]) sage: A, B = M.diagonalization(QQbar) # needs sage.rings.number_field sage: _ = A.n() # needs sage.rings.number_field - """ from sage.rings.real_mpfr import RealField from sage.rings.complex_mpfr import ComplexField @@ -15933,7 +15867,7 @@ cdef class Matrix(Matrix1): def exp(self): r""" - Calculate the exponential of this matrix X, which is the matrix + Calculate the exponential of this matrix X, which is the matrix. .. MATH:: @@ -16050,7 +15984,7 @@ cdef class Matrix(Matrix1): INPUT: - - ``transformation`` -- a boolean (default: ``True``); whether the + - ``transformation`` -- boolean (default: ``True``); whether the matrices `U` and `V` should be returned - ``integral`` -- a subring of the base ring, boolean or ``None`` @@ -16062,7 +15996,7 @@ cdef class Matrix(Matrix1): by the denominator must map the entries into the subring; in this case the transformation matrices will have entries in this subring. - - ``exact`` -- a boolean (default: ``True``), only used for local rings/fields. + - ``exact`` -- boolean (default: ``True``); only used for local rings/fields. See ``LOCAL RINGS`` for more details. OUTPUT: @@ -16215,7 +16149,6 @@ cdef class Matrix(Matrix1): [ O(2^4) 3 + O(2^4) 11 + O(2^4)] [ 0 0 1 + O(2^5)] ) - """ R = self.base_ring() if hasattr(R, '_matrix_smith_form'): @@ -16276,11 +16209,9 @@ cdef class Matrix(Matrix1): INPUT: - - ``i`` -- an integer - - OUTPUT: + - ``i`` -- integer - An ideal on the base ring. + OUTPUT: an ideal on the base ring EXAMPLES:: @@ -16355,7 +16286,6 @@ cdef class Matrix(Matrix1): sage: M.smith_form()[0] [ 1 0 0] [ 0 x - 1 0] - """ R = self.base_ring() if not R.is_exact(): @@ -16547,17 +16477,17 @@ cdef class Matrix(Matrix1): INPUT: - - ``include_zero_rows`` -- bool (default: ``True``); if False - the zero rows in the output matrix are deleted. + - ``include_zero_rows`` -- boolean (default: ``True``); if ``False`` + the zero rows in the output matrix are deleted - - ``transformation`` -- bool (default: ``False``) a matrix U such that U*self == H. + - ``transformation`` -- boolean (default: ``False``); a matrix `U` such + that ``U*self == H`` OUTPUT: - - matrix H - - (optional) transformation matrix U such that U*self == H, possibly with zero - rows deleted... - + - matrix H + - (optional) transformation matrix `U` such that ``U*self == H``, + possibly with zero rows deleted EXAMPLES:: @@ -16667,7 +16597,6 @@ cdef class Matrix(Matrix1): sage: M = A.span([x*L.0]) sage: M.0 in L True - """ if self.ncols() == 0: return self.new_matrix(self.nrows(), self.nrows(), 1), self, [] @@ -16731,11 +16660,11 @@ cdef class Matrix(Matrix1): INPUT: - - ``self`` -- a square matrix over an exact field. + - ``self`` -- a square matrix over an exact field - ``basis`` -- (default; ``True``); controls whether or not to compute a change-of-basis matrix (also called a transformation - matrix). + matrix) OUTPUT: @@ -16974,12 +16903,12 @@ cdef class Matrix(Matrix1): INPUT: - - ``self`` -- a square matrix with entries from an exact field. + - ``self`` -- a square matrix with entries from an exact field - - ``transformation`` -- (default: ``False``); if ``True`` return a - change-of-basis matrix relating the matrix and its ZigZag form. + - ``transformation`` -- (default: ``False``) if ``True`` return a + change-of-basis matrix relating the matrix and its ZigZag form - - ``subdivide`` -- (default: ``True``); if ``True`` the ZigZag + - ``subdivide`` -- (default: ``True``) if ``True`` the ZigZag form matrix is subdivided according to the companion matrices described in the output section below. @@ -17245,22 +17174,22 @@ cdef class Matrix(Matrix1): def rational_form(self, format='right', subdivide=True): r""" - Returns the rational canonical form, also known as Frobenius form. + Return the rational canonical form, also known as Frobenius form. INPUT: - - ``self`` -- a square matrix with entries from an exact field. + - ``self`` -- a square matrix with entries from an exact field - - ``format`` -- (default: 'right'); one of 'right', 'bottom', - 'left', 'top' or 'invariants'. The first four will cause a - matrix to be returned with companion matrices dictated by the + - ``format`` -- (default: ``'right'``) one of ``'right'``, ``'bottom'``, + ``'left'``, ``'top'`` or ``'invariants'``. The first four will cause + a matrix to be returned with companion matrices dictated by the keyword. The value 'invariants' will cause a list of lists to be returned, where each list contains coefficients of a polynomial associated with a companion matrix. - - ``subdivide`` -- (default: 'True'); if 'True' and a matrix is + - ``subdivide`` -- (default: ``'True'``) if 'True' and a matrix is returned, then it contains subdivisions delineating the - companion matrices along the diagonal. + companion matrices along the diagonal OUTPUT: @@ -17687,10 +17616,10 @@ cdef class Matrix(Matrix1): INPUT: - - ``K1`` -- a polyhedral closed convex cone. + - ``K1`` -- a polyhedral closed convex cone - ``K2`` -- (default: ``K1``) the codomain cone; this matrix is - a positive operator if the image of ``K1`` is a subset of ``K2``. + a positive operator if the image of ``K1`` is a subset of ``K2`` OUTPUT: @@ -17858,7 +17787,7 @@ cdef class Matrix(Matrix1): INPUT: - - ``K`` -- a polyhedral closed convex cone. + - ``K`` -- a polyhedral closed convex cone OUTPUT: @@ -18001,7 +17930,7 @@ cdef class Matrix(Matrix1): INPUT: - - ``K`` -- a polyhedral closed convex cone. + - ``K`` -- a polyhedral closed convex cone OUTPUT: @@ -18097,7 +18026,6 @@ cdef class Matrix(Matrix1): ... ValueError: The base ring of the matrix is neither symbolic nor exact. - """ return (-self).is_cross_positive_on(K) @@ -18122,7 +18050,7 @@ cdef class Matrix(Matrix1): INPUT: - - ``K`` -- a polyhedral closed convex cone. + - ``K`` -- a polyhedral closed convex cone OUTPUT: @@ -18273,7 +18201,7 @@ cdef class Matrix(Matrix1): - ``self`` -- the Gram matrix of a quadratic form or of a lattice equipped with a bilinear form - - ``flag`` -- an optional flag passed to ``qflllgram``. + - ``flag`` -- an optional flag passed to ``qflllgram`` According to :pari:`qflllgram`'s documentation the options are: - ``0`` -- (default), assume that ``self`` has either exact @@ -18326,7 +18254,7 @@ cdef class Matrix(Matrix1): [ 0 -1] [ 1 0] - However, it might fail for others, either raising a ``ValueError``:: + However, it might fail for others, either raising a :exc:`ValueError`:: sage: Matrix(ZZ, 1, 1, [0]).LLL_gram() # needs sage.libs.pari Traceback (most recent call last): @@ -18382,7 +18310,7 @@ cdef class Matrix(Matrix1): @property def T(self): r""" - Returns the transpose of a matrix. + Return the transpose of a matrix. EXAMPLES:: @@ -18399,7 +18327,7 @@ cdef class Matrix(Matrix1): @property def C(self): r""" - Returns the conjugate matrix. + Return the conjugate matrix. EXAMPLES:: @@ -18410,14 +18338,13 @@ cdef class Matrix(Matrix1): [ -3 5 + 3*I 7 + 4*I] [ 7 - 3*I -1 - 6*I 3 - 5*I] [ 3 - 3*I -3 - 6*I 5 - 1*I] - """ return self.conjugate() @property def H(self): r""" - Returns the conjugate-transpose (Hermitian) matrix. + Return the conjugate-transpose (Hermitian) matrix. EXAMPLES:: @@ -18706,7 +18633,7 @@ def decomp_seq(v): def _choose(Py_ssize_t n, Py_ssize_t t): """ - Returns all possible sublists of length t from range(n) + Return all possible sublists of length `t` from ``range(n)``. Based on algorithm T from Knuth's taocp part 4: 7.2.1.3 p.5 This function replaces the one based on algorithm L because it is @@ -18826,7 +18753,7 @@ def _jordan_form_vector_in_difference(V, W): def _matrix_power_symbolic(A, n): r""" - Return the symbolic `n`-th power `A^n` of the matrix `A` + Return the symbolic `n`-th power `A^n` of the matrix `A`. This function implements the computation of `A^n` for symbolic `n`, relying on the Jordan normal form of `A`, available for exact rings diff --git a/src/sage/matrix/matrix_cdv.pyx b/src/sage/matrix/matrix_cdv.pyx index 7a6b1887518..238d875844f 100644 --- a/src/sage/matrix/matrix_cdv.pyx +++ b/src/sage/matrix/matrix_cdv.pyx @@ -36,7 +36,7 @@ cpdef hessenbergize_cdvf(Matrix_generic_dense H): TESTS:: sage: # needs sage.rings.padics - sage: K = Qp(5, print_mode="digits", prec=5) + sage: K = Qp(5, print_mode='digits', prec=5) sage: H = matrix(K, 3, 3, range(9)) sage: H [ 0 ...00001 ...00002] diff --git a/src/sage/matrix/matrix_complex_ball_dense.pyx b/src/sage/matrix/matrix_complex_ball_dense.pyx index 07857217309..b8b193145c7 100644 --- a/src/sage/matrix/matrix_complex_ball_dense.pyx +++ b/src/sage/matrix/matrix_complex_ball_dense.pyx @@ -95,7 +95,7 @@ cdef Matrix_generic_dense acb_mat_to_matrix(acb_mat_t source, Parent CIF): - ``source`` -- an ``acb_mat_t`` - - ``precision`` -- a positive integer. + - ``precision`` -- positive integer OUTPUT: @@ -181,7 +181,7 @@ cdef class Matrix_complex_ball_dense(Matrix_dense): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring EXAMPLES: @@ -264,7 +264,7 @@ cdef class Matrix_complex_ball_dense(Matrix_dense): - ``j`` -- column - - ``x`` -- must be ComplexBall! The value to set self[i,j] to. + - ``x`` -- must be ComplexBall! The value to set ``self[i,j]`` to. EXAMPLES:: @@ -650,7 +650,7 @@ cdef class Matrix_complex_ball_dense(Matrix_dense): TESTS:: - sage: mat.charpoly(algorithm="hessenberg") + sage: mat.charpoly(algorithm='hessenberg') x^5 + ([-1.8 +/- 0.04...])*x^4 + ([0.3 +/- 0.08...])*x^3 + ([+/- 0.0...])*x^2 + ([+/- ...e-4])*x + [+/- ...e-6] sage: mat.charpoly('y') diff --git a/src/sage/matrix/matrix_cyclo_dense.pyx b/src/sage/matrix/matrix_cyclo_dense.pyx index 4fdfe5f1118..ab5542dda7b 100644 --- a/src/sage/matrix/matrix_cyclo_dense.pyx +++ b/src/sage/matrix/matrix_cyclo_dense.pyx @@ -119,7 +119,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring EXAMPLES: @@ -161,7 +161,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): cdef set_unsafe(self, Py_ssize_t i, Py_ssize_t j, value): """ - Set the ij-th entry of self. + Set the ij-th entry of ``self``. WARNING: This function does no bounds checking whatsoever, as the name suggests. It also assumes certain facts about the @@ -288,7 +288,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): cdef get_unsafe(self, Py_ssize_t i, Py_ssize_t j): """ - Get the ij-th of self. + Get the ij-th of ``self``. WARNING: As the name suggests, expect segfaults if i,j are out of bounds!! This is for internal use only. @@ -433,8 +433,9 @@ cdef class Matrix_cyclo_dense(Matrix_dense): underlying data and pickle version. OUTPUT: - data -- output of pickle - version -- int + + - data; output of pickle + - version; integer EXAMPLES:: @@ -451,10 +452,11 @@ cdef class Matrix_cyclo_dense(Matrix_dense): Called when unpickling matrices. INPUT: - data -- a string - version -- int - This modifies self. + - ``data`` -- string + - ``version`` -- integer + + This modifies ``self``. EXAMPLES:: @@ -493,10 +495,11 @@ cdef class Matrix_cyclo_dense(Matrix_dense): Return the sum of two dense cyclotomic matrices. INPUT: - self, right -- dense cyclotomic matrices with the same - parents - OUTPUT: - a dense cyclotomic matrix + + - ``self``, ``right`` -- dense cyclotomic matrices with the same + parents + + OUTPUT: a dense cyclotomic matrix EXAMPLES:: @@ -521,10 +524,11 @@ cdef class Matrix_cyclo_dense(Matrix_dense): Return the difference of two dense cyclotomic matrices. INPUT: - self, right -- dense cyclotomic matrices with the same - parent - OUTPUT: - a dense cyclotomic matrix + + - ``self``, ``right`` -- dense cyclotomic matrices with the same + parent + + OUTPUT: a dense cyclotomic matrix EXAMPLES:: @@ -589,16 +593,17 @@ cdef class Matrix_cyclo_dense(Matrix_dense): Return the product of two cyclotomic dense matrices. INPUT: - self, right -- cyclotomic dense matrices with compatible - parents (same base ring, and compatible - dimensions for matrix multiplication). - OUTPUT: - cyclotomic dense matrix + - ``self``, ``right`` -- cyclotomic dense matrices with compatible + parents (same base ring, and compatible dimensions for matrix + multiplication) + + OUTPUT: cyclotomic dense matrix ALGORITHM: - Use a multimodular algorithm that involves multiplying the - two matrices modulo split primes. + + Use a multimodular algorithm that involves multiplying the two matrices + modulo split primes. EXAMPLES:: @@ -682,7 +687,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): """ Return hash of an immutable matrix. - This raises a :class:`TypeError` if input matrix is mutable. + This raises a :exc:`TypeError` if input matrix is mutable. EXAMPLES: @@ -715,7 +720,6 @@ cdef class Matrix_cyclo_dense(Matrix_dense): sage: A.set_immutable() sage: A.__hash__() # random 2347601038649299176 - """ return hash(self._matrix) @@ -797,8 +801,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): """ Return the negative of this matrix. - OUTPUT: - matrix + OUTPUT: matrix EXAMPLES:: @@ -858,7 +861,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def _rational_matrix(self): """ - Return the underlying rational matrix corresponding to self. + Return the underlying rational matrix corresponding to ``self``. EXAMPLES:: @@ -883,9 +886,8 @@ cdef class Matrix_cyclo_dense(Matrix_dense): """ Return the denominator of the entries of this matrix. - OUTPUT: - integer -- the smallest integer d so that d * self has - entries in the ring of integers + OUTPUT: integer; the smallest integer `d` so that ``d * self`` has + entries in the ring of integers EXAMPLES:: @@ -901,7 +903,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def coefficient_bound(self): r""" Return an upper bound for the (complex) absolute values of all - entries of self with respect to all embeddings. + entries of ``self`` with respect to all embeddings. Use ``self.height()`` for a sharper bound. @@ -942,10 +944,10 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def height(self): r""" - Return the height of self. + Return the height of ``self``. If we let `a_{ij}` be the `i,j` entry of self, then we define - the height of self to be + the height of ``self`` to be `\max_v \max_{i,j} |a_{ij}|_v`, @@ -983,20 +985,18 @@ cdef class Matrix_cyclo_dense(Matrix_dense): INPUT: - - ``col`` -- Integer, indicating the column; must be coercable to - ``int``, and this must lie between 0 (inclusive) and - ``self._ncols`` (exclusive), since no bounds-checking is performed - - ``nump1`` -- Integer, numerator bound plus one - - ``denp1`` -- Integer, denominator bound plus one - - ``distribution`` -- ``None`` or '1/n' (default: ``None``); if '1/n' - then ``num_bound``, ``den_bound`` are ignored and numbers are chosen - using the GMP function ``mpq_randomize_entry_recip_uniform`` - - ``nonzero`` -- Bool (default: ``False``); whether the new entries - are forced to be non-zero - - OUTPUT: + - ``col`` -- integer indicating the column; must be coercable to + ``int``, and this must lie between 0 (inclusive) and + ``self._ncols`` (exclusive), since no bounds-checking is performed + - ``nump1`` -- integer; numerator bound plus one + - ``denp1`` -- integer; denominator bound plus one + - ``distribution`` -- ``None`` or '1/n' (default: ``None``); if '1/n' + then ``num_bound``, ``den_bound`` are ignored and numbers are chosen + using the GMP function ``mpq_randomize_entry_recip_uniform`` + - ``nonzero`` -- boolean (default: ``False``); whether the new entries + are forced to be nonzero - - None, the matrix is modified in-space + OUTPUT: none, the matrix is modified in-space WARNING: @@ -1117,7 +1117,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): while col_is_zero: self._randomize_rational_column_unsafe(col, B.value, C.value, distribution) - # Check whether the new column is non-zero + # Check whether the new column is nonzero for i in range(self._degree): if not fmpq_is_zero(fmpq_mat_entry(self._matrix._matrix, i, col)): col_is_zero = False @@ -1130,7 +1130,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): while col_is_zero: self._randomize_rational_column_unsafe(col, B.value, C.value, distribution) - # Check whether the new column is non-zero + # Check whether the new column is nonzero for i in range(self._degree): if not fmpq_is_zero(fmpq_mat_entry(self._matrix._matrix, i, col)): col_is_zero = False @@ -1219,26 +1219,24 @@ cdef class Matrix_cyclo_dense(Matrix_dense): return M - def charpoly(self, var='x', algorithm="multimodular", proof=None): + def charpoly(self, var='x', algorithm='multimodular', proof=None): r""" Return the characteristic polynomial of self, as a polynomial over the base ring. INPUT: - - algorithm - - - 'multimodular' (default): reduce modulo primes, compute charpoly - mod p, and lift (very fast) - - 'pari': use pari (quite slow; comparable to Magma v2.14 though) - - 'hessenberg': put matrix in Hessenberg form (double dog slow) + - ``algorithm`` -- options: - - proof -- bool (default: None) proof flag determined by global linalg - proof. + - ``'multimodular'`` (default): reduce modulo primes, compute + charpoly mod p, and lift (very fast) + - ``'pari'``: use pari (quite slow; comparable to Magma v2.14 though) + - ``'hessenberg'``: put matrix in Hessenberg form (double dog slow) - OUTPUT: + - ``proof`` -- boolean (default: ``None``); proof flag determined by + global linalg proof - polynomial + OUTPUT: polynomial EXAMPLES:: @@ -1310,12 +1308,12 @@ cdef class Matrix_cyclo_dense(Matrix_dense): This is used internally by the multimodular charpoly algorithm. INPUT: - p -- a prime that splits completely - OUTPUT: - matrix over GF(p) whose columns correspond to the entries - of all the characteristic polynomials of the reduction of self modulo all - the primes over p. + - ``p`` -- a prime that splits completely + + OUTPUT: matrix over GF(p) whose columns correspond to the entries + of all the characteristic polynomials of the reduction of ``self`` + modulo all the primes over `p` EXAMPLES:: @@ -1347,15 +1345,15 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def _charpoly_multimodular(self, var='x', proof=None): """ - Compute the characteristic polynomial of self using a + Compute the characteristic polynomial of ``self`` using a multimodular algorithm. INPUT: - proof -- bool (default: global flag); if False, compute - using primes `p_i` until the lift modulo all - primes up to `p_i` is the same as the lift modulo - all primes up to `p_{i+3}` or the bound is - reached. + + - ``proof`` -- boolean (default: global flag); if ``False``, compute + using primes `p_i` until the lift modulo all primes up to `p_i` is + the same as the lift modulo all primes up to `p_{i+3}` or the bound + is reached EXAMPLES:: @@ -1429,15 +1427,17 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def _reductions(self, p): """ Compute the reductions modulo all primes over p of denom*self, - where denom is the denominator of self. + where denom is the denominator of ``self``. INPUT: - p -- a prime that splits completely in the base cyclotomic field. + + - ``p`` -- a prime that splits completely in the base cyclotomic field OUTPUT: - list -- of r distinct matrices modulo p, where r is - the degree of the cyclotomic base field. - denom -- an integer + + - ``list`` -- of r distinct matrices modulo p, where r is + the degree of the cyclotomic base field + - ``denom`` -- integer EXAMPLES:: @@ -1473,13 +1473,14 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def _reduction_matrix(self, p): """ INPUT: - p -- a prime that splits completely in the base field. + + - ``p`` -- a prime that splits completely in the base field OUTPUT: - -- Matrix over GF(p) whose action from the left - gives the map from O_K to GF(p) x ... x GF(p) - given by reducing modulo all the primes over p. - -- inverse of this matrix + + - Matrix over GF(p) whose action from the left gives the map from O_K + to GF(p) x ... x GF(p) given by reducing modulo all the primes over p + - inverse of this matrix EXAMPLES:: @@ -1637,13 +1638,11 @@ cdef class Matrix_cyclo_dense(Matrix_dense): INPUT: - - num_primes -- number of primes to work modulo + - ``num_primes`` -- number of primes to work modulo - - height_guess -- guess for the height of the echelon form of self - - OUTPUT: + - ``height_guess`` -- guess for the height of the echelon form of self - - matrix in reduced row echelon form + OUTPUT: matrix in reduced row echelon form EXAMPLES:: @@ -1790,21 +1789,23 @@ cdef class Matrix_cyclo_dense(Matrix_dense): def _echelon_form_one_prime(self, p): """ - Find the echelon form of self mod the primes dividing p. Return + Find the echelon form of ``self`` mod the primes dividing p. Return the rational matrix representing this lift. If the pivots of the reductions mod the primes over p are different, then no such lift - exists, and we raise a ValueError. If this happens, then the - denominator of the echelon form of self is divisible by p. (Note + exists, and we raise a :exc:`ValueError`. If this happens, then the + denominator of the echelon form of ``self`` is divisible by p. (Note that the converse need not be true.) INPUT: - p -- a prime that splits completely in the cyclotomic base field. - OUTPUT: - matrix -- Lift via CRT of the echelon forms of self modulo - each of the primes over p. - tuple -- the tuple of pivots for the echelon form of self mod the - primes dividing p + - ``p`` -- a prime that splits completely in the cyclotomic base field + + OUTPUT: tuple of + + - ``matrix`` -- Lift via CRT of the echelon forms of ``self`` modulo + each of the primes over p. + - ``tuple`` -- the tuple of pivots for the echelon form of ``self`` mod the + primes dividing p EXAMPLES:: @@ -1869,7 +1870,7 @@ cdef class Matrix_cyclo_dense(Matrix_dense): INPUT: - ``A`` -- a matrix - - ``subdivide`` -- (default: ``True``) whether or not to return + - ``subdivide`` -- boolean (default: ``True``); whether or not to return natural subdivisions with the matrix OUTPUT: diff --git a/src/sage/matrix/matrix_dense.pyx b/src/sage/matrix/matrix_dense.pyx index a954dde39d2..b0de42539a0 100644 --- a/src/sage/matrix/matrix_dense.pyx +++ b/src/sage/matrix/matrix_dense.pyx @@ -5,7 +5,7 @@ TESTS:: sage: R. = QQ[] sage: m = matrix(R,2,[0,a,b,b^2]) - sage: TestSuite(m).run(skip="_test_minpoly") + sage: TestSuite(m).run(skip='_test_minpoly') """ cimport sage.matrix.matrix as matrix @@ -97,7 +97,7 @@ cdef class Matrix_dense(matrix.Matrix): def transpose(self): """ - Returns the transpose of self, without changing self. + Return the transpose of ``self``, without changing ``self``. EXAMPLES: We create a matrix, compute its transpose, and note that the original matrix is not changed. @@ -147,7 +147,7 @@ cdef class Matrix_dense(matrix.Matrix): def antitranspose(self): """ - Returns the antitranspose of self, without changing self. + Return the antitranspose of ``self``, without changing ``self``. EXAMPLES:: @@ -220,7 +220,7 @@ cdef class Matrix_dense(matrix.Matrix): def _elementwise_product(self, right): r""" - Returns the elementwise product of two dense + Return the elementwise product of two dense matrices with identical base rings. This routine assumes that ``self`` and ``right`` diff --git a/src/sage/matrix/matrix_double_dense.pyx b/src/sage/matrix/matrix_double_dense.pyx index 23415be73ac..255523b0273 100644 --- a/src/sage/matrix/matrix_double_dense.pyx +++ b/src/sage/matrix/matrix_double_dense.pyx @@ -13,7 +13,6 @@ AUTHORS: - William Stein: many bug fixes and touch ups. - EXAMPLES:: sage: b = Mat(RDF,2,3).basis() @@ -171,7 +170,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): cpdef _sub_(self, right): """ - Return self - right + Return ``self - right``. EXAMPLES:: @@ -373,7 +372,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``p`` -- (default: 'frob'); controls which norm is used + - ``p`` -- (default: ``'frob'``) controls which norm is used to compute the condition number, allowable values are 'frob' (for the Frobenius norm), integers -2, -1, 1, 2, positive and negative infinity. See output discussion @@ -560,7 +559,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``p`` -- (default: 2); controls which norm is computed, + - ``p`` -- (default: 2) controls which norm is computed, allowable values are 'frob' (for the Frobenius norm), integers -2, -1, 1, 2, positive and negative infinity. See output discussion for specifics. @@ -697,7 +696,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``eps`` -- (default: ``None``); the largest number which + - ``eps`` -- (default: ``None``) the largest number which will be considered to be zero. May also be set to the string 'auto'. See the discussion below. @@ -712,10 +711,10 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): the list is the minimum of the row count and column count for the matrix. - The number of non-zero singular values will be the rank of the + The number of nonzero singular values will be the rank of the matrix. However, as a numerical matrix, it is impossible to control the difference between zero entries and very small - non-zero entries. As an informed consumer it is up to you + nonzero entries. As an informed consumer it is up to you to use the output responsibly. We will do our best, and give you the tools to work with the output, but we cannot give you a guarantee. @@ -740,7 +739,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): EXAMPLES: Singular values close to zero have trailing digits that may vary - on different hardware. For exact matrices, the number of non-zero + on different hardware. For exact matrices, the number of nonzero singular values will equal the rank of the matrix. So for some of the doctests we round the small singular values that ideally would be zero, to control the variability across hardware. @@ -865,7 +864,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): if scipy is None: import scipy eps = 2*max(self._nrows, self._ncols)*numpy.finfo(float).eps*sv[0] eps = RDF(eps) - # locate non-zero entries + # locate nonzero entries rank = 0 while rank < diag and sv[rank] > eps: rank = rank + 1 @@ -897,11 +896,11 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): - ``A = P*L*U`` - ``P`` is a square permutation matrix, of size `m\times m`, so is all zeroes, but with exactly a single one in each - row and each column. + row and each column - ``L`` is lower-triangular, square of size `m\times m`, - with every diagonal entry equal to one. + with every diagonal entry equal to one - ``U`` is upper-triangular with size `m\times n`, i.e. - entries below the "diagonal" are all zero. + entries below the "diagonal" are all zero The computed decomposition is cached and returned on subsequent calls, thus requiring the results to be immutable. @@ -909,7 +908,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): Effectively, ``P`` permutes the rows of ``A``. Then ``L`` can be viewed as a sequence of row operations on this matrix, where each operation is adding a multiple of a row to a - subsequent row. There is no scaling (thus 1's on the diagonal + subsequent row. There is no scaling (thus 1s on the diagonal of ``L``) and no row-swapping (``P`` does that). As a result ``U`` is close to being the result of Gaussian-elimination. However, round-off errors can make it hard to determine @@ -1065,7 +1064,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): solved; if ``algorithm`` is ``'symmetric'`` or ``'hermitian'``, `B` must be real symmetric or hermitian positive definite, respectively - - ``algorithm`` -- default: ``'default'`` + - ``algorithm`` -- (default: ``'default'``) - ``'default'`` -- applicable to any matrix with double-precision floating point entries. @@ -1085,7 +1084,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): This algorithm can be significantly faster than the ``'default'`` algorithm. - - ``'tol'`` -- (default: ``None``); if set to a value other than + - ``'tol'`` -- (default: ``None``) if set to a value other than ``None``, this is interpreted as a small real number used to aid in grouping eigenvalues that are numerically similar, but is ignored when ``homogeneous`` is set. See the output description for more @@ -1440,7 +1439,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): The SciPy routines used for these computations produce eigenvectors normalized to have length 1, but on different hardware they may vary by a complex sign. So for doctests we have normalized output by forcing - their eigenvectors to have their first non-zero entry equal to one. + their eigenvectors to have their first nonzero entry equal to one. ALGORITHM: @@ -1514,7 +1513,6 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): ....: spectrum[i][1][0] = matrix(CDF, spectrum[i][1]).echelon_form()[0] sage: spectrum [(1.0*I, [(1.0, 0.0)], 1), (1.0, [(0.0, 1.0)], 1)] - """ if not self.is_square(): raise ArithmeticError("self must be a square matrix") @@ -1598,7 +1596,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): The SciPy routines used for these computations produce eigenvectors normalized to have length 1, but on different hardware they may vary by a complex sign. So for doctests we have normalized output by forcing - their eigenvectors to have their first non-zero entry equal to one. + their eigenvectors to have their first nonzero entry equal to one. ALGORITHM: @@ -1834,7 +1832,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): def conjugate(self): r""" Return the conjugate of this matrix, i.e. the matrix whose entries are - the conjugates of the entries of self. + the conjugates of the entries of ``self``. EXAMPLES:: @@ -1871,22 +1869,22 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): r""" Return the singular value decomposition of this matrix. - The U and V matrices are not unique and may be returned with different - values in the future or on different systems. The S matrix is unique + The `U` and `V` matrices are not unique and may be returned with different + values in the future or on different systems. The `S` matrix is unique and contains the singular values in descending order. The computed decomposition is cached and returned on subsequent calls. INPUT: - - A -- a matrix + - ``A`` -- a matrix OUTPUT: - - U, S, V -- immutable matrices such that `A = U*S*V.conj().transpose()` - where U and V are orthogonal and S is zero off of the diagonal. + ``U, S, V`` -- immutable matrices such that ``A = U*S*V.conj().transpose()`` + where `U` and `V` are orthogonal and `S` is zero off of the diagonal - Note that if self is m-by-n, then the dimensions of the + Note that if ``self`` is m-by-n, then the dimensions of the matrices that this returns are (m,m), (m,n), and (n, n). .. NOTE:: @@ -2012,9 +2010,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): Return a factorization into a unitary matrix and an upper-triangular matrix. - INPUT: - - Any matrix over ``RDF`` or ``CDF``. + Applies to any matrix over ``RDF`` or ``CDF``. OUTPUT: @@ -2215,13 +2211,13 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``tol`` -- (default: ``1e-12``); the largest value of the + - ``tol`` -- (default: ``1e-12``) the largest value of the absolute value of the difference between two matrix entries - for which they will still be considered equal. + for which they will still be considered equal - - ``algorithm`` -- (default: 'orthonormal'); set to 'orthonormal' - for a stable procedure and set to 'naive' for a fast - procedure. + - ``algorithm`` -- (default: ``'orthonormal'``) set to + ``'orthonormal'`` for a stable procedure and set to 'naive' for a + fast procedure OUTPUT: @@ -2345,7 +2341,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): """ if self.dimensions() == (0,0): # The "orthonormal" algorithm would otherwise fail in this - # corner case. Returning `True` is consistent with the + # corner case. Returning ``True`` is consistent with the # other implementations of this method. return True @@ -2405,11 +2401,11 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``tol`` -- (default: ``1e-12``); the largest value of the + - ``tol`` -- (default: ``1e-12``) the largest value of the absolute value of the difference between two matrix entries - for which they will still be considered equal. + for which they will still be considered equal - - ``skew`` -- (default: ``False``); Specifies the type of the + - ``skew`` -- (default: ``False``) specifies the type of the test. Set to ``True`` to check whether the matrix is skew-Hermitian. @@ -2484,7 +2480,6 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): AUTHOR: - Rob Beezer (2011-03-30) - """ import sage.rings.complex_double global numpy @@ -2524,12 +2519,12 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``tol`` -- (default: ``1e-12``); the largest value of the + - ``tol`` -- (default: ``1e-12``) the largest value of the absolute value of the difference between two matrix entries for which they will still be considered equal. - - ``algorithm`` -- string (default: "naive"); either "naive" - or "orthonormal" + - ``algorithm`` -- string (default: ``'naive'``); either ``'naive'`` + or ``'orthonormal'`` OUTPUT: @@ -2652,13 +2647,13 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``tol`` -- (default: ``1e-12``); the largest value of the + - ``tol`` -- (default: ``1e-12``) the largest value of the absolute value of the difference between two matrix entries for which they will still be considered equal. - - ``algorithm`` -- (default: 'orthonormal'); set to 'orthonormal' - for a stable procedure and set to 'naive' for a fast - procedure. + - ``algorithm`` -- (default: ``'orthonormal'``) set to + ``'orthonormal'`` for a stable procedure and set to ``'naive'`` for a + fast procedure OUTPUT: @@ -2759,7 +2754,6 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): AUTHOR: - Rob Beezer (2011-03-30) - """ if algorithm == "naive": return super()._is_hermitian(skew=True, tolerance=tol) @@ -2774,13 +2768,13 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``tol`` -- (default: ``1e-12``); the largest value of the + - ``tol`` -- (default: ``1e-12``) the largest value of the absolute value of the difference between two matrix entries for which they will still be considered equal. - - ``algorithm`` -- (default: 'orthonormal'); set to 'orthonormal' - for a stable procedure and set to 'naive' for a fast - procedure. + - ``algorithm`` -- (default: ``'orthonormal'``) set to + ``'orthonormal'`` for a stable procedure and set to ``'naive'`` for a + fast procedure OUTPUT: @@ -2970,9 +2964,9 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``base_ring`` -- optional, defaults to the base ring of ``self``. - Use this to request the base ring of the returned matrices, which - will affect the format of the results. + - ``base_ring`` -- defaults to the base ring of ``self``; use this to + request the base ring of the returned matrices, which will affect the + format of the results OUTPUT: @@ -3279,7 +3273,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): where `L^\ast` is the conjugate-transpose in the complex case, and just the transpose in the real case. If the matrix fails to be positive definite (perhaps because it is not symmetric - or Hermitian), then this function raises a ``ValueError``. + or Hermitian), then this function raises a :exc:`ValueError`. IMPLEMENTATION: @@ -3288,7 +3282,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): method and the :meth:`is_positive_definite` method compute and cache both the Cholesky decomposition and the positive-definiteness. So the :meth:`is_positive_definite` - method or catching a ``ValueError`` from the :meth:`cholesky` + method or catching a :exc:`ValueError` from the :meth:`cholesky` method are equally expensive computationally and if the decomposition exists, it is cached as a side-effect of either routine. @@ -3399,7 +3393,6 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): Traceback (most recent call last): ... ValueError: matrix is not Hermitian - """ from sage.rings.real_double import RDF from sage.rings.complex_double import CDF @@ -3453,9 +3446,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): eigenvalues and only positive determinants of leading principal submatrices. - INPUT: - - Any matrix over ``RDF`` or ``CDF``. + Applies to any matrix over ``RDF`` or ``CDF``. OUTPUT: @@ -3470,7 +3461,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): method and the :meth:`cholesky` method compute and cache both the Cholesky decomposition and the positive-definiteness. So the :meth:`is_positive_definite` - method or catching a ``ValueError`` from the :meth:`cholesky` + method or catching a :exc:`ValueError` from the :meth:`cholesky` method are equally expensive computationally and if the decomposition exists, it is cached as a side-effect of either routine. @@ -3716,11 +3707,9 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): INPUT: - - ``eps`` -- Cutoff value - - OUTPUT: + - ``eps`` -- cutoff value - A modified copy of the matrix. + OUTPUT: a modified copy of the matrix EXAMPLES:: @@ -3754,15 +3743,13 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): def round(self, ndigits=0): """ Return a copy of the matrix where all entries have been rounded - to a given precision in decimal digits (default 0 digits). + to a given precision in decimal digits (default: 0 digits). INPUT: - - ``ndigits`` -- The precision in number of decimal digits - - OUTPUT: + - ``ndigits`` -- the precision in number of decimal digits - A modified copy of the matrix + OUTPUT: a modified copy of the matrix EXAMPLES:: @@ -3794,9 +3781,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): the columns, for example an algorithm which should produce an orthogonal matrix. - OUTPUT: - - A modified copy of the matrix. + OUTPUT: a modified copy of the matrix EXAMPLES:: @@ -3833,9 +3818,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense): the rows, for example an algorithm which should produce an upper triangular matrix. - OUTPUT: - - A modified copy of the matrix. + OUTPUT: a modified copy of the matrix EXAMPLES:: diff --git a/src/sage/matrix/matrix_double_sparse.pyx b/src/sage/matrix/matrix_double_sparse.pyx index f6d3494cc08..0014121dcb8 100644 --- a/src/sage/matrix/matrix_double_sparse.pyx +++ b/src/sage/matrix/matrix_double_sparse.pyx @@ -14,7 +14,6 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): sage: A = matrix.random(CDF, ZZ.random_element(5), sparse=True) sage: A.__class__ - """ def is_hermitian(self, tolerance=1e-12): @@ -23,7 +22,7 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): entry-wise ``tolerance``. A matrix is said to be Hermitian if it is equal to its - conjugate-transpose. We default to a small but non-zero + conjugate-transpose. We default to a small but nonzero entry-wise tolerance because, otherwise, numerical issues can cause false negatives (Issue #33023). @@ -36,9 +35,7 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): tolerate between entries of the given matrix and its conjugate- transpose. - OUTPUT: - - A boolean, either ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -54,7 +51,6 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): sage: A = matrix.random(CDF, 2, sparse=True) sage: (A*A.conjugate_transpose()).is_hermitian() True - """ return self._is_hermitian(skew=False, tolerance=tolerance) @@ -65,7 +61,7 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): A matrix is said to be skew-Hermitian if it is equal to the negation of its conjugate-transpose. We default to a small but - non-zero entry-wise tolerance because, otherwise, numerical + nonzero entry-wise tolerance because, otherwise, numerical issues can cause false negatives (Issue #33023). Otherwise this method is identical to the superclass method, @@ -78,9 +74,7 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): tolerate between entries of the given matrix and the negation of its conjugate-transpose. - OUTPUT: - - A boolean, either ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -96,17 +90,14 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): sage: A = matrix.random(CDF, 2, sparse=True) sage: (A - A.conjugate_transpose()).is_skew_hermitian() True - """ return self._is_hermitian(skew=True, tolerance=tolerance) def cholesky(self): r""" - Returns the Cholesky decomposition of a Hermitian matrix. - - INPUT: + Return the Cholesky decomposition of a Hermitian matrix. - A positive-definite matrix over ``RDF`` or ``CDF``. + Applies to a positive-definite matrix over ``RDF`` or ``CDF``. OUTPUT: @@ -119,7 +110,7 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): where `L^\ast` is the conjugate-transpose. If the matrix is not positive-definite (for example, if it is not Hermitian) - then a ``ValueError`` results. + then a :exc:`ValueError` results. ALGORITHM: @@ -245,7 +236,7 @@ cdef class Matrix_double_sparse(Matrix_generic_sparse): cvx_L = cholmod.getfactor(cvx_symbolic) # The (I[k],J[k]) entry of cvx_L has value V[k]. But beware that V - # contains only the non-zero entries of the matrix; as a result, the + # contains only the nonzero entries of the matrix; as a result, the # dict below contains keys only for those nonzero entries. L = self.matrix_space()({ (cvx_L.I[k], cvx_L.J[k]): cvx_L.V[k] diff --git a/src/sage/matrix/matrix_generic_dense.pyx b/src/sage/matrix/matrix_generic_dense.pyx index 1ac4c3711c6..28603b5a930 100644 --- a/src/sage/matrix/matrix_generic_dense.pyx +++ b/src/sage/matrix/matrix_generic_dense.pyx @@ -61,7 +61,7 @@ cdef class Matrix_generic_dense(matrix_dense.Matrix_dense): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring TESTS: @@ -151,8 +151,8 @@ cdef class Matrix_generic_dense(matrix_dense.Matrix_dense): def __copy__(self): """ - Creates a copy of self, which may be changed without altering - self. + Create a copy of self, which may be changed without altering + ``self``. EXAMPLES:: @@ -330,7 +330,7 @@ cdef class Matrix_generic_dense(matrix_dense.Matrix_dense): def _list(self): """ - Return reference to list of entries of self. For internal use + Return reference to list of entries of ``self``. For internal use only, since this circumvents immutability. EXAMPLES:: diff --git a/src/sage/matrix/matrix_generic_sparse.pyx b/src/sage/matrix/matrix_generic_sparse.pyx index ef4e99d890e..8c57e50b08a 100644 --- a/src/sage/matrix/matrix_generic_sparse.pyx +++ b/src/sage/matrix/matrix_generic_sparse.pyx @@ -98,7 +98,7 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse): The datastructure can potentially be optimized. Firstly, as noticed in :issue:`17663`, we lose time in using 2-tuples to store indices. - Secondly, there is no fast way to access non-zero elements in a given + Secondly, there is no fast way to access nonzero elements in a given row/column. """ def __cinit__(self): @@ -117,7 +117,7 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring TESTS:: @@ -169,7 +169,7 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse): def __bool__(self): r""" - Test whether this matrix is non-zero. + Test whether this matrix is nonzero. TESTS:: @@ -288,7 +288,6 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse): True sage: (A+D).__class__ == D.__class__ True - """ # Compute the sum of two sparse matrices. # This is complicated because of how we represent sparse matrices. @@ -346,7 +345,7 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse): def _list(self): """ - Return all entries of self as a list of numbers of rows times + Return all entries of ``self`` as a list of numbers of rows times number of columns entries. """ cdef Py_ssize_t i,j @@ -360,7 +359,7 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse): def _dict(self): """ - Return the underlying dictionary of self. + Return the underlying dictionary of ``self``. This is used in comparisons. @@ -425,10 +424,9 @@ def Matrix_sparse_from_rows(X): """ INPUT: - - ``X`` -- nonempty list of SparseVector rows - + - ``X`` -- nonempty list of ``SparseVector`` rows - OUTPUT: Sparse_matrix with those rows. + OUTPUT: ``Sparse_matrix`` with those rows EXAMPLES:: diff --git a/src/sage/matrix/matrix_gf2e_dense.pyx b/src/sage/matrix/matrix_gf2e_dense.pyx index 6a4fd3bfed2..b8660ad08dc 100644 --- a/src/sage/matrix/matrix_gf2e_dense.pyx +++ b/src/sage/matrix/matrix_gf2e_dense.pyx @@ -205,7 +205,7 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring EXAMPLES:: @@ -232,9 +232,10 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): cdef set_unsafe(self, Py_ssize_t i, Py_ssize_t j, value): """ - A[i,j] = value without bound checks + A[i,j] = value without bound checks. INPUT: + - ``i`` -- row index - ``j`` -- column index - ``value`` -- a finite field element (not checked but assumed) @@ -262,6 +263,7 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): Get A[i,j] without bound checks. INPUT: + - ``i`` -- row index - ``j`` -- column index @@ -297,8 +299,8 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): return mzed_read_elem(self._entries, i, j) == self._zero_word cpdef _add_(self, right): - """ - Return A+B + r""" + Return ``A+B``. INPUT: @@ -384,8 +386,8 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): return ans cdef _matrix_times_matrix_(self, Matrix right): - """ - Return A*B + r""" + Return ``A*B``. Uses the M4RIE machinery to decide which function to call. @@ -707,14 +709,12 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): INPUT: - - ``density`` -- float; proportion (roughly) to be considered for - changes - - ``nonzero`` -- Bool (default: ``False``); whether the new entries - are forced to be non-zero - - OUTPUT: + - ``density`` -- float; proportion (roughly) to be considered for + changes + - ``nonzero`` -- boolean (default: ``False``); whether the new entries + are forced to be nonzero - - None, the matrix is modified in-place + OUTPUT: none, the matrix is modified in-place EXAMPLES:: @@ -927,7 +927,7 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): sig_off() elif algorithm == 'builtin': - self._echelon_in_place(algorithm="classical") + self._echelon_in_place(algorithm='classical') else: raise ValueError("No algorithm '%s'."%algorithm) @@ -976,7 +976,6 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): [1 0 0] [0 1 0] [0 0 1] - """ cdef Matrix_gf2e_dense A A = Matrix_gf2e_dense.__new__(Matrix_gf2e_dense, self._parent, 0, 0, 0) @@ -993,13 +992,13 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): cdef rescale_row_c(self, Py_ssize_t row, multiple, Py_ssize_t start_col): """ - Return ``multiple * self[row][start_col:]`` + Return ``multiple * self[row][start_col:]``. INPUT: - ``row`` -- row index for row to rescale - ``multiple`` -- finite field element to scale by - - ``start_col`` -- only start at this column index. + - ``start_col`` -- only start at this column index EXAMPLES:: @@ -1039,7 +1038,7 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): - ``row_to`` -- row index of source - ``row_from`` -- row index of destination - - ``multiple`` -- finite field element + - ``multiple`` -- finite field element - ``start_col`` -- only start at this column index EXAMPLES:: @@ -1323,7 +1322,7 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): EXAMPLES:: sage: K. = GF(2^4) - sage: A = random_matrix(K, 10, 10, algorithm="unimodular") + sage: A = random_matrix(K, 10, 10, algorithm='unimodular') sage: A.rank() 10 sage: A = matrix(K, 10, 0) @@ -1445,7 +1444,7 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense): INPUT: - - ``C`` -- a list of matrices over GF(2) + - ``C`` -- list of matrices over GF(2) EXAMPLES:: diff --git a/src/sage/matrix/matrix_gfpn_dense.pyx b/src/sage/matrix/matrix_gfpn_dense.pyx index e3d704dd771..9d4e113e522 100644 --- a/src/sage/matrix/matrix_gfpn_dense.pyx +++ b/src/sage/matrix/matrix_gfpn_dense.pyx @@ -109,8 +109,8 @@ cdef class FieldConverter_class: """ INPUT: - A finite field with Givaro implementation and at most 251 - elements. These assumptions are not tested. + - ``field`` -- a finite field with Givaro implementation and at most 251 + elements. These assumptions are not tested. EXAMPLES:: @@ -202,8 +202,8 @@ cdef class PrimeFieldConverter_class(FieldConverter_class): """ INPUT: - A finite *prime* field with at most 251 elements. - This assumption is not tested. + - ``field`` -- a finite *prime* field with at most 251 elements. + This assumption is not tested. EXAMPLES:: @@ -266,7 +266,6 @@ cdef FieldConverter_class FieldConverter(field) noexcept: sage: A = MS.random_element() sage: A*2 == A+A True - """ try: return _converter_cache[field] @@ -343,7 +342,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): The documentation of the ``__init__`` methods shows further ways of creating a :class:`Matrix_gfpn_dense` instance. However, these should only be of internal use. - """ ################## ## Init, Dealloc, Copy @@ -377,7 +375,7 @@ cdef class Matrix_gfpn_dense(Matrix_dense): - ``coerce`` -- ignored - - ``mutable`` -- if False, the resulting matrix cannot be + - ``mutable`` -- if ``False``, the resulting matrix cannot be changed, and it can be used as key in a Python dictionary EXAMPLES:: @@ -563,7 +561,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 0 1 2] [ z z + 1 z + 2] [ 2*z 2*z + 1 2*z + 2] - """ if self.Data == NULL: raise IndexError("Matrix is empty") @@ -617,7 +614,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [2 3 4] sage: type(_) is MTX True - """ if not 0 <= i < j <= self.Data.Nor: raise IndexError("Indices i={}, j={} violate the condition 0 < i < j < {}".format(i,j,self.Data.Nor)) @@ -652,7 +648,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [0 0 0 0 0 0 0 0 0] [0 0 0 0 0 0 0 0 0] [0 0 0 0 0 0 0 0 0] - """ # ASSUMPTION: value's parent is the base ring if self.Data == NULL: @@ -685,10 +680,10 @@ cdef class Matrix_gfpn_dense(Matrix_dense): INPUT: - - ``density`` (optional real number between zero and one) -- - the expected density of the resulting matrix - - ``nonzero`` (optional bool, default ``False``) -- - If true, all inserted marks are non-zero. + - ``density`` -- (optional) real number between zero and one the + expected density of the resulting matrix + - ``nonzero`` -- boolean (default: ``False``); if ``True``, all + inserted marks are nonzero EXAMPLES:: @@ -872,7 +867,7 @@ cdef class Matrix_gfpn_dense(Matrix_dense): INPUT: - ``i`` -- index of the first row to be extracted - - ``j`` -- (default: -1); -1, or index of the last + - ``j`` -- (default: -1) -1, or index of the last row to be extracted OUTPUT: @@ -900,7 +895,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [['15', '14', '1', '0', '10'], ['24', '13', '20', '1', '16'], ['18', '8', '7', '6', '17']] - """ cdef int k if self.Data: @@ -1020,7 +1014,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 1 2 y y + 1 y + 2] [ 2*y 2*y + 1 2*y + 2 0 1] [ 2 y y + 1 y + 2 2*y] - """ if self.Data == NULL or start_col >= self.Data.Noc: return @@ -1089,7 +1082,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 2 y y + 1 y + 2 2*y] sage: y-(2*y+1)/y 2 - """ if self.Data == NULL or start_col >= self.Data.Noc: return @@ -1132,7 +1124,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 2*x 2*x + 1 2*x + 2 2*x + 3 2*x + 4] [ x x + 1 x + 2 x + 3 x + 4] [ 4*x 4*x + 1 4*x + 2 4*x + 3 4*x + 4] - """ if not self.Data: raise ValueError("This matrix is empty") @@ -1149,7 +1140,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: K. = GF(125) sage: MatrixSpace(K,7,7)(x).trace() 2*x - """ if self._nrows != self._ncols: raise ValueError("self must be a square matrix") @@ -1207,7 +1197,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 2*x 1 2] [ x 1 x + 2] [ 2*x 2*x + 1 x + 2] - """ cdef Matrix_gfpn_dense Self = self cdef Matrix_gfpn_dense Right = right @@ -1234,7 +1223,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ x 1 2] [ x 2*x + 1 x + 2] [ 2*x 2*x + 1 2] - """ cdef Matrix_gfpn_dense Self = self cdef Matrix_gfpn_dense Right = right @@ -1266,7 +1254,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: N = MatrixSpace(GF(125,'x'),10,30).random_element() sage: M + (-N) == M - N == -(N - M) True - """ if self.Data == NULL: raise ValueError("The matrix must not be empty") @@ -1296,7 +1283,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: M == M*int(4) == int(4)*M True - """ if self.Data == NULL: return self.__copy__() @@ -1329,7 +1315,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: N = MatrixSpace(GF(9,'x'),500,2000).random_element() sage: M*N == M._multiply_classical(N) True - """ "multiply two meataxe matrices by the school book algorithm" if self.Data == NULL or right.Data == NULL: @@ -1351,7 +1336,7 @@ cdef class Matrix_gfpn_dense(Matrix_dense): INPUT: - ``right`` -- a matrix of dimensions suitable to do multiplication - - ``cutoff`` (optional integer) -- indicates the minimal size of submatrices + - ``cutoff`` -- (optional integer) indicates the minimal size of submatrices that will be considered in the divide-and-conquer algorithm. The size is *not* expressed by the number of rows/columns, but the rowsize expressed in bytes. Depending on the base field, one byte may represent up to eight @@ -1365,7 +1350,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: N = MatrixSpace(GF(9,'x'),600,1500).random_element() sage: M._multiply_strassen(N) == M._multiply_strassen(N,80) == M._multiply_strassen(N,2) True - """ if self.Data == NULL or right.Data == NULL: raise ValueError("The matrices must not be empty") @@ -1426,7 +1410,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 0 x + 2 2*x + 1] [ 1 x 2*x + 2] [ 2 x + 1 2*x] - """ if self.Data == NULL: return self.__copy__() @@ -1472,7 +1455,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): Traceback (most recent call last): ... ZeroDivisionError: Division by zero in file matinv.c (line 50) - """ if self.Data == NULL: raise ValueError("The matrix must not be empty") @@ -1504,7 +1486,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): [ 2 2*x] [ x 2*x + 1] [ x + 1 2*x + 2] - """ if self.Data == NULL: raise ValueError("The matrix must not be empty") @@ -1531,7 +1512,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): True sage: M^103 == 1 False - """ if self.Data == NULL: raise ValueError("The matrix must not be empty") @@ -1582,7 +1562,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: M.left_kernel_matrix() [0 0 0 0 1 0 0 0 0 0] [0 0 0 0 0 0 0 1 0 0] - """ cdef Matrix_gfpn_dense OUT = self.fetch("left_kernel_matrix") if OUT is not None: @@ -1608,7 +1587,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): Use :meth:`_echelon_in_place_classical`, which can take the keyword ``reduced``. - EXAMPLES:: sage: K. = GF(25) @@ -1649,9 +1627,9 @@ cdef class Matrix_gfpn_dense(Matrix_dense): INPUT: - - ``reduced`` (default: ``True``) -- will result + - ``reduced`` -- boolean (default: ``True``); will result in the row-reduced echelon form (otherwise, only a - semi-echelon form results). + semi-echelon form results) EXAMPLES:: @@ -1740,7 +1718,6 @@ cdef class Matrix_gfpn_dense(Matrix_dense): sage: M [ 1 0 3*a + 4 2*a + 2] [ 0 1 2*a 3*a + 3] - """ if self._nrows == 0 or self._ncols == 0: self.cache('in_echelon_form',True) @@ -1896,7 +1873,7 @@ def mtx_unpickle(f, int nr, int nc, data, bint m): [0 0 0 0 0] [0 0 0 0 0] - We test further corner cases. A ``ValueError`` is raised if the number + We test further corner cases. A :exc:`ValueError` is raised if the number of bytes in the pickle does not comply with either the old or the new pickle format (we test several code paths here):: diff --git a/src/sage/matrix/matrix_integer_dense.pyx b/src/sage/matrix/matrix_integer_dense.pyx index 036d1bb7998..e561c459e4a 100644 --- a/src/sage/matrix/matrix_integer_dense.pyx +++ b/src/sage/matrix/matrix_integer_dense.pyx @@ -250,8 +250,8 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the - entries are of type :class:`Integer`. + - ``coerce`` -- if ``False``, assume without checking that the + entries are of type :class:`Integer` EXAMPLES: @@ -323,7 +323,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``j`` -- column - - ``x`` -- must be Integer! The value to set self[i,j] to. + - ``x`` -- must be Integer! The value to set ``self[i,j]`` to. EXAMPLES:: @@ -347,8 +347,8 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``j`` -- column - - ``value`` -- The value to set self[i,j] to. This will make a - copy of ``value``. + - ``value`` -- the value to set ``self[i,j]`` to; this will make a + copy of ``value`` EXAMPLES:: @@ -376,7 +376,7 @@ cdef class Matrix_integer_dense(Matrix_dense): cdef get_unsafe(self, Py_ssize_t i, Py_ssize_t j): """ - Return the (i, j) entry of self as a new Integer. + Return the (i, j) entry of ``self`` as a new Integer. .. WARNING:: @@ -430,7 +430,7 @@ cdef class Matrix_integer_dense(Matrix_dense): cdef inline int get_unsafe_int(self, Py_ssize_t i, Py_ssize_t j) noexcept: """ - Return the (i, j) entry of self as a new Integer. + Return the (i, j) entry of ``self`` as a new Integer. .. WARNING:: @@ -441,7 +441,7 @@ cdef class Matrix_integer_dense(Matrix_dense): cdef inline double get_unsafe_double(self, Py_ssize_t i, Py_ssize_t j) noexcept: """ - Return the (i, j) entry of self as a new Integer. + Return the (i, j) entry of ``self`` as a new Integer. .. WARNING:: @@ -496,7 +496,6 @@ cdef class Matrix_integer_dense(Matrix_dense): sage: matrix(ZZ,1,3,[1,193,15])._pickle() == (b'1 61 f', 0) # indirect doctest True - """ return str_to_bytes(self._export_as_string(32), 'ascii') @@ -507,7 +506,7 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - base -- an integer <= 36; (default: 10) + - ``base`` -- integer <= 36; (default: 10) EXAMPLES:: @@ -671,7 +670,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def __bool__(self): r""" - Tests whether self is not the zero matrix. + Test whether ``self`` is not the zero matrix. EXAMPLES:: @@ -1056,9 +1055,9 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``v`` -- a free module element. + - ``v`` -- a free module element - OUTPUT: The vector times matrix product ``v*A``. + OUTPUT: the vector times matrix product ``v*A`` EXAMPLES:: @@ -1104,7 +1103,7 @@ cdef class Matrix_integer_dense(Matrix_dense): r""" Test whether the matrix is primitive. - An integral matrix `A` is primitive if all its entries are non-negative + An integral matrix `A` is primitive if all its entries are nonnegative and for some positive integer `n` the matrix `A^n` has all its entries positive. @@ -1185,7 +1184,7 @@ cdef class Matrix_integer_dense(Matrix_dense): try: fmpz_mat_init(m, dim, dim) - # 1. check that self._matrix is non-negative and set + # 1. check that self._matrix is nonnegative and set # m as a 0/1 matrix zero = 0 diag = 0 @@ -1245,9 +1244,9 @@ cdef class Matrix_integer_dense(Matrix_dense): """ INPUT: - - ``self`` -- a matrix + - ``self`` -- a matrix - OUTPUT: self, 1 + OUTPUT: ``self, 1`` EXAMPLES:: @@ -1268,11 +1267,10 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: + - ``var`` -- a variable name - - ``var`` -- a variable name - - - ``algorithm`` -- (optional) either 'generic', 'flint' or 'linbox'. - Default is set to 'linbox'. + - ``algorithm`` -- (default: ``'linbox'``) either ``'generic'``, + ``'flint'`` or ``'linbox'`` EXAMPLES:: @@ -1386,10 +1384,9 @@ cdef class Matrix_integer_dense(Matrix_dense): r""" INPUT: + - ``var`` -- a variable name - - ``var`` -- a variable name - - - ``algorithm`` -- (optional) either 'linbox' (default) or 'generic' + - ``algorithm`` -- either ``'linbox'`` (default) or ``'generic'`` EXAMPLES:: @@ -1471,7 +1468,7 @@ cdef class Matrix_integer_dense(Matrix_dense): Return the height of this matrix, i.e., the max absolute value of the entries of the matrix. - OUTPUT: A nonnegative integer. + OUTPUT: nonnegative integer EXAMPLES:: @@ -1709,7 +1706,7 @@ cdef class Matrix_integer_dense(Matrix_dense): Return a pair (F, C) such that the rows of C form a symplectic basis for ``self`` and ``F = C * self * C.transpose()``. - Raise a :class:`ValueError` if ``self`` is not anti-symmetric, + Raise a :exc:`ValueError` if ``self`` is not anti-symmetric, or ``self`` is not alternating. Anti-symmetric means that `M = -M^t`. Alternating means @@ -1765,7 +1762,7 @@ cdef class Matrix_integer_dense(Matrix_dense): hermite_form = echelon_form - def echelon_form(self, algorithm="default", proof=None, include_zero_rows=True, + def echelon_form(self, algorithm='default', proof=None, include_zero_rows=True, transformation=False, D=None): r""" Return the echelon form of this matrix over the integers, also known @@ -1773,9 +1770,9 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``algorithm`` -- String. The algorithm to use. Valid options are: + - ``algorithm`` -- string; the algorithm to use. Valid options are: - - ``'default'`` -- Let Sage pick an algorithm (default). + - ``'default'`` -- let Sage pick an algorithm (default). Up to 75 rows or columns with no transformation matrix, use pari with flag 0; otherwise, use flint. @@ -1784,7 +1781,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``'ntl'`` -- use NTL (only works for square matrices of full rank!) - - ``'padic'`` -- an asymptotically fast p-adic modular + - ``'padic'`` -- an asymptotically fast `p`-adic modular algorithm, If your matrix has large coefficients and is small, you may also want to try this. @@ -1796,25 +1793,25 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``'pari4'`` -- use PARI with flag 4 (use heuristic LLL) - - ``proof`` -- (default: ``True``); if proof=False certain - determinants are computed using a randomized hybrid p-adic - multimodular strategy until it stabilizes twice (instead of up to - the Hadamard bound). It is *incredibly* unlikely that one would - ever get an incorrect result with proof=False. + - ``proof`` -- (default: ``True``) if proof=False certain + determinants are computed using a randomized hybrid `p`-adic + multimodular strategy until it stabilizes twice (instead of up to + the Hadamard bound). It is *incredibly* unlikely that one would + ever get an incorrect result with proof=False. - - ``include_zero_rows`` -- (default: ``True``) if False, - don't include zero rows + - ``include_zero_rows`` -- boolean (default: ``True``); if ``False``, + don't include zero rows - - ``transformation`` -- if given, also compute - transformation matrix; only valid for flint and padic algorithm + - ``transformation`` -- if given, also compute + transformation matrix; only valid for flint and padic algorithm - - ``D`` -- (default: None) if given and the algorithm - is 'ntl', then D must be a multiple of the determinant and this - function will use that fact. + - ``D`` -- (default: ``None``) if given and the algorithm + is ``'ntl'``, then D must be a multiple of the determinant and this + function will use that fact OUTPUT: - The Hermite normal form (=echelon form over `\ZZ`) of self as + The Hermite normal form (=echelon form over `\ZZ`) of ``self`` as an immutable matrix. EXAMPLES:: @@ -1873,7 +1870,7 @@ cdef class Matrix_integer_dense(Matrix_dense): .. NOTE:: If 'ntl' is chosen for a non square matrix this function - raises a ValueError. + raises a :exc:`ValueError`. Special cases: 0 or 1 rows:: @@ -1996,7 +1993,7 @@ cdef class Matrix_integer_dense(Matrix_dense): sage: m = random_matrix(ZZ, 15, 15, x=-1000, y=1000, density=0.1) sage: m.parent() Full MatrixSpace of 15 by 15 dense matrices over Integer Ring - sage: H, U = m.hermite_form(algorithm="flint", + sage: H, U = m.hermite_form(algorithm='flint', ....: transformation=True) sage: H == U*m True @@ -2116,7 +2113,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def saturation(self, p=0, proof=None, max_dets=5): r""" Return a saturation matrix of self, which is a matrix whose rows - span the saturation of the row span of self. This is not unique. + span the saturation of the row span of ``self``. This is not unique. The saturation of a `\ZZ` module `M` embedded in `\ZZ^n` is a module `S` that @@ -2127,25 +2124,21 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``p`` -- (default: 0); if nonzero given, saturate - only at the prime `p`, i.e., return a matrix whose row span - is a `\ZZ`-module `S` that contains self and - such that the index of `S` in its saturation is coprime to - `p`. If `p` is None, return full saturation of - self. - - - ``proof`` -- (default: use proof.linear_algebra()); - if False, the determinant calculations are done with proof=False. + - ``p`` -- (default: 0) if nonzero given, saturate + only at the prime `p`, i.e., return a matrix whose row span + is a `\ZZ`-module `S` that contains ``self`` and + such that the index of `S` in its saturation is coprime to + `p`. If `p` is None, return full saturation of ``self``. - - ``max_dets`` -- (default: 5); technical parameter - - max number of determinant to compute when bounding prime divisor of - self in its saturation. + - ``proof`` -- (default: use proof.linear_algebra()); + if ``False``, the determinant calculations are done with + ``proof=False`` + - ``max_dets`` -- (default: 5) technical parameter - + max number of determinant to compute when bounding prime divisor of + ``self`` in its saturation. - OUTPUT: - - - - ``matrix`` -- a matrix over ZZ + OUTPUT: matrix over ZZ .. NOTE:: @@ -2199,26 +2192,23 @@ cdef class Matrix_integer_dense(Matrix_dense): def index_in_saturation(self, proof=None): """ - Return the index of self in its saturation. + Return the index of ``self`` in its saturation. INPUT: + - ``proof`` -- (default: use proof.linear_algebra()); + if ``False``, the determinant calculations are done with + ``proof=False`` - - ``proof`` -- (default: use proof.linear_algebra()); - if False, the determinant calculations are done with proof=False. - - - OUTPUT: + OUTPUT: positive integer; the index of the row span of + this matrix in its saturation - - ``positive integer`` -- the index of the row span of - this matrix in its saturation - + ALGORITHM: - ALGORITHM: Use Hermite normal form twice to find an invertible - matrix whose inverse transforms a matrix with the same row span as - self to its saturation, then compute the determinant of that - matrix. + Use Hermite normal form twice to find an invertible matrix whose + inverse transforms a matrix with the same row span as ``self`` to its + saturation, then compute the determinant of that matrix. EXAMPLES:: @@ -2293,16 +2283,14 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: + - ``self`` -- matrix - - ``self`` -- matrix - - - ``algorithm`` -- (default: 'pari') + - ``algorithm`` -- (default: ``'pari'``) - - ``'pari'``: works robustly, but is slower. + - ``'pari'`` -- works robustly, but is slower. - ``'linbox'`` -- use linbox (currently off, broken) - OUTPUT: list of integers @@ -2374,12 +2362,12 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``transformation`` -- a boolean (default: ``True``); whether to + - ``transformation`` -- boolean (default: ``True``); whether to return the transformation matrices `U` and `V` such that `S=U\cdot - self\cdot V`. + self\cdot V` - ``integral`` -- a subring of the base ring or ``True`` (default: - ``None``); ignored for matrices with integer entries. + ``None``); ignored for matrices with integer entries .. NOTE:: @@ -2478,19 +2466,19 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``flag`` -- 0 (default), 1 or 2 as follows: + - ``flag`` -- 0 (default), 1 or 2 as follows: - - ``0`` -- (default) return the Frobenius form of this - matrix. + - ``0`` -- (default) return the Frobenius form of this + matrix - - ``1`` -- return only the elementary divisor - polynomials, as polynomials in var. + - ``1`` -- return only the elementary divisor + polynomials, as polynomials in var - - ``2`` -- return a two-components vector [F,B] where F + - ``2`` -- return a two-components vector [F,B] where F is the Frobenius form and B is the basis change so that - `M=B^{-1}FB`. + `M=B^{-1}FB` - - ``var`` -- a string (default: 'x') + - ``var`` -- string (default: ``'x'``) ALGORITHM: uses PARI's :pari:`matfrobenius` @@ -2558,14 +2546,14 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``algorithm`` -- determines which algorithm to use, options are: - - 'flint' -- use the algorithm from the FLINT library - - 'pari' -- use the :pari:`matkerint` function from the PARI library - - 'padic' -- use the p-adic algorithm from the IML library - - 'default' -- use a heuristic to decide which of the three above - routines is fastest. This is the default value. + - ``'flint'`` -- use the algorithm from the FLINT library + - ``'pari'`` -- use the :pari:`matkerint` function from the PARI library + - ``'padic'`` -- use the `p`-adic algorithm from the IML library + - ``'default'`` -- use a heuristic to decide which of the three above + routines is fastest. This is the default value - - ``proof`` -- this is passed to the p-adic IML algorithm. - If not specified, the global flag for linear algebra will be used. + - ``proof`` -- this is passed to the `p`-adic IML algorithm; + if not specified, the global flag for linear algebra will be used OUTPUT: @@ -2721,7 +2709,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def _ntl_(self): r""" - ntl.mat_ZZ representation of self. + ntl.mat_ZZ representation of ``self``. EXAMPLES:: @@ -2740,7 +2728,7 @@ cdef class Matrix_integer_dense(Matrix_dense): # LLL ####################################################################### - def BKZ(self, delta=None, algorithm="fpLLL", fp=None, block_size=10, prune=0, + def BKZ(self, delta=None, algorithm='fpLLL', fp=None, block_size=10, prune=0, use_givens=False, precision=0, proof=None, **kwds): """ Return the result of running Block Korkin-Zolotarev reduction on @@ -2750,7 +2738,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``delta`` -- (default: ``0.99``) LLL parameter - - ``algorithm`` -- (default: ``"fpLLL"``) ``"fpLLL"`` or ``"NTL"`` + - ``algorithm`` -- (default: ``'fpLLL'``) ``'fpLLL'`` or ``"NTL"`` - ``fp`` -- floating point number implementation @@ -2762,7 +2750,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``'qd'`` -- NTL's QP - -``'qd1'`` -- quad doubles: Uses ``quad_float`` precision + - ``'qd1'`` -- quad doubles: Uses ``quad_float`` precision to compute Gram-Schmidt, but uses double precision in the search phase of the block reduction algorithm. This seems adequate for most purposes, and is faster than @@ -2773,7 +2761,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``'rr'`` -- arbitrary precision: NTL'RR or fpLLL's MPFR - - ``block_size`` -- (default: ``10``) Specifies the size + - ``block_size`` -- (default: ``10``) specifies the size of the blocks in the reduction. High values yield shorter vectors, but the running time increases double exponentially with ``block_size``. ``block_size`` @@ -2786,7 +2774,7 @@ cdef class Matrix_integer_dense(Matrix_dense): NTL SPECIFIC INPUT: - - ``prune`` -- (default: ``0``) The optional parameter + - ``prune`` -- (default: ``0``) the optional parameter ``prune`` can be set to any positive number to invoke the Volume Heuristic from [SH1995]_. This can significantly reduce the running time, and hence allow much bigger block size, @@ -2796,7 +2784,7 @@ cdef class Matrix_integer_dense(Matrix_dense): disabled. Recommended usage: for ``block_size==30``, set ``10 <= prune <=15``. - - ``use_givens`` -- Use Givens orthogonalization. Only + - ``use_givens`` -- use Givens orthogonalization. Only applies to approximate reduction using NTL. This is a bit slower, but generally much more stable, and is really the preferred orthogonalization strategy. For a nice @@ -2807,8 +2795,8 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``precision`` -- (default: ``0`` for automatic choice) bit precision to use if ``fp='rr'`` is set - - ``**kwds`` -- keywords to be passed to :mod:`fpylll`. See - :class:`fpylll.BKZ.Param` for details. + - ``**kwds`` -- keywords to be passed to :mod:`fpylll`; see + :class:`fpylll.BKZ.Param` for details Also, if the verbose level is at least `2`, some output is printed during the computation. @@ -2828,7 +2816,7 @@ cdef class Matrix_integer_dense(Matrix_dense): [-1 1 3] sage: A = Matrix(ZZ,3,3,range(1,10)) - sage: A.BKZ(fp="fp") + sage: A.BKZ(fp='fp') [ 0 0 0] [ 2 1 0] [-1 1 3] @@ -2948,10 +2936,10 @@ cdef class Matrix_integer_dense(Matrix_dense): R = A.to_matrix(self.new_matrix()) return R - def LLL(self, delta=None, eta=None, algorithm="fpLLL:wrapper", fp=None, prec=0, early_red=False, use_givens=False, use_siegel=False, transformation=False, **kwds): + def LLL(self, delta=None, eta=None, algorithm='fpLLL:wrapper', fp=None, prec=0, early_red=False, use_givens=False, use_siegel=False, transformation=False, **kwds): r""" Return LLL-reduced or approximated LLL reduced matrix `R` of the lattice - generated by the rows of self. + generated by the rows of ``self``. A set of vectors `(b_1, b_2, ..., b_d)` is `(\delta, \eta)`-LLL-reduced if the two following conditions hold: @@ -2988,7 +2976,7 @@ cdef class Matrix_integer_dense(Matrix_dense): ignored by NTL and pari - ``algorithm`` -- string; one of the algorithms listed below - (default: ``"fpLLL:wrapper"``). + (default: ``'fpLLL:wrapper'``) - ``fp`` -- floating point number implementation, ignored by pari: @@ -3001,42 +2989,40 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``prec`` -- (default: auto choose) precision, ignored by NTL and pari - - ``early_red`` -- (default: ``False``) perform early reduction, + - ``early_red`` -- boolean (default: ``False``); perform early reduction, ignored by NTL and pari - - ``use_givens`` -- (default: ``False``) use Givens + - ``use_givens`` -- boolean (default: ``False``); use Givens orthogonalization. Only applies to approximate reduction using NTL. This is slower but generally more stable. - - ``use_siegel`` -- (default: ``False``) use Siegel's condition + - ``use_siegel`` -- boolean (default: ``False``); use Siegel's condition instead of Lovász's condition, ignored by NTL and pari - - ``transformation`` -- (default: ``False``) also return transformation - matrix. + - ``transformation`` -- boolean (default: ``False``); also return transformation + matrix - - ``**kwds`` -- keywords to be passed to :mod:`fpylll`. See - :meth:`fpylll.LLL.reduction` for details. + - ``**kwds`` -- keywords to be passed to :mod:`fpylll`; see + :meth:`fpylll.LLL.reduction` for details Also, if the verbose level is at least `2`, some output is printed during the computation. AVAILABLE ALGORITHMS: - - ``'NTL:LLL'`` -- NTL's LLL + choice of ``fp``. + - ``'NTL:LLL'`` -- NTL's LLL + choice of ``fp`` - - ``'fpLLL:heuristic'`` -- fpLLL's heuristic + choice of ``fp``. + - ``'fpLLL:heuristic'`` -- fpLLL's heuristic + choice of ``fp`` - - ``'fpLLL:fast'`` -- fpLLL's fast + choice of ``fp``. + - ``'fpLLL:fast'`` -- fpLLL's fast + choice of ``fp`` - - ``'fpLLL:proved'`` -- fpLLL's proved + choice of ``fp``. + - ``'fpLLL:proved'`` -- fpLLL's proved + choice of ``fp`` - - ``'fpLLL:wrapper'`` -- fpLLL's automatic choice (default). + - ``'fpLLL:wrapper'`` -- fpLLL's automatic choice (default) - - ``'pari'`` -- pari's qflll. + - ``'pari'`` -- pari's qflll - OUTPUT: - - A matrix over the integers. + OUTPUT: a matrix over the integers EXAMPLES:: @@ -3086,11 +3072,11 @@ cdef class Matrix_integer_dense(Matrix_dense): sage: U * A == R True - sage: R, U = A.LLL(algorithm="NTL:LLL", transformation=True) + sage: R, U = A.LLL(algorithm='NTL:LLL', transformation=True) sage: U * A == R True - sage: R, U = A.LLL(algorithm="pari", transformation=True) + sage: R, U = A.LLL(algorithm='pari', transformation=True) sage: U * A == R True @@ -3105,7 +3091,7 @@ cdef class Matrix_integer_dense(Matrix_dense): [0 0 0] [0 0 0] - sage: M.LLL(algorithm="pari")[0:2] + sage: M.LLL(algorithm='pari')[0:2] [0 0 0] [0 0 0] @@ -3146,7 +3132,7 @@ cdef class Matrix_integer_dense(Matrix_dense): sage: M._cache {'rank': 2} sage: M._clear_cache() - sage: R = M.LLL(algorithm="pari") + sage: R = M.LLL(algorithm='pari') sage: M._cache {'rank': 2} @@ -3366,10 +3352,10 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``cols`` -- a list (or set) of integers representing columns + - ``cols`` -- list (or set) of integers representing columns of ``self`` - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -3382,7 +3368,6 @@ cdef class Matrix_integer_dense(Matrix_dense): 40 sage: a.prod_of_row_sums(set([0,2])) 40 - """ cdef Py_ssize_t c, row cdef fmpz_t s,pr @@ -3405,22 +3390,16 @@ cdef class Matrix_integer_dense(Matrix_dense): return z def rational_reconstruction(self, N): - """ - Use rational reconstruction to lift self to a matrix over the - rational numbers (if possible), where we view self as a matrix + r""" + Use rational reconstruction to lift ``self`` to a matrix over the + rational numbers (if possible), where we view ``self`` as a matrix modulo N. INPUT: + - ``N`` -- integer - - ``N`` -- an integer - - - OUTPUT: - - - - ``matrix`` -- over QQ or raise a ValueError - + OUTPUT: matrix over `\QQ` or raise a :exc:`ValueError` EXAMPLES: We create a random 4x4 matrix over ZZ. @@ -3471,23 +3450,21 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``self`` -- a mutable matrix over ZZ + - ``self`` -- a mutable matrix over ZZ - - ``density`` -- a float between 0 and 1 + - ``density`` -- a float between 0 and 1 - - ``x, y`` -- if not ``None``, these are passed to the + - ``x``, ``y`` -- if not ``None``, these are passed to the ``ZZ.random_element`` function as the upper and lower endpoints in the uniform distribution - - ``distribution`` -- would also be passed into ``ZZ.random_element`` - if given + - ``distribution`` -- would also be passed into ``ZZ.random_element`` + if given - - ``nonzero`` -- bool (default: ``False``); whether the new entries - are guaranteed to be zero - - OUTPUT: + - ``nonzero`` -- boolean (default: ``False``); whether the new entries + are guaranteed to be zero - - None, the matrix is modified in-place + OUTPUT: None, the matrix is modified in-place EXAMPLES:: @@ -3544,7 +3521,7 @@ cdef class Matrix_integer_dense(Matrix_dense): else: # New code, to implement the ``nonzero`` option. Note that this # code is almost the same as above, the only difference being that - # each entry is set until it's non-zero. + # each entry is set until it's nonzero. sig_on() if density == 1: for i from 0 <= i < self._nrows: @@ -3578,9 +3555,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``algorithm`` -- either ``'modp'`` (default) or ``'flint'`` or ``'linbox'`` - OUTPUT: - - - a nonnegative integer -- the rank + OUTPUT: nonnegative integer -- the rank .. NOTE:: @@ -3679,7 +3654,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``'flint'`` -- let flint do the determinant - - ``'padic'`` -- uses a p-adic / multimodular + - ``'padic'`` -- uses a `p`-adic / multimodular algorithm that relies on code in IML and linbox - ``'linbox'`` -- calls linbox det (you *must* set @@ -3689,20 +3664,19 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``'pari'`` -- uses PARI - - ``proof`` -- bool or None; if None use - proof.linear_algebra(); only relevant for the padic algorithm. + - ``proof`` -- boolean or ``None``; if ``None`` use + proof.linear_algebra(); only relevant for the padic algorithm .. NOTE:: It would be *VERY VERY* hard for det to fail even with proof=False. - - ``stabilize`` -- if proof is False, require det to be - the same for this many CRT primes in a row. Ignored if proof is - True. + - ``stabilize`` -- if proof is ``False``, require det to be the same + for this many CRT primes in a row. Ignored if proof is ``True``. - ALGORITHM: The p-adic algorithm works by first finding a random + ALGORITHM: The `p`-adic algorithm works by first finding a random vector v, then solving `Ax = v` and taking the denominator `d`. This gives a divisor of the determinant. Then we compute `\det(A)/d` using a multimodular algorithm and the @@ -3907,12 +3881,12 @@ cdef class Matrix_integer_dense(Matrix_dense): def _rational_kernel_iml(self): """ - Return the rational (left) kernel of this matrix + Return the rational (left) kernel of this matrix. OUTPUT: A matrix ``K`` such that ``self * K = 0``, and the number of columns of - K equals the nullity of self. + K equals the nullity of ``self``. EXAMPLES:: @@ -3954,12 +3928,12 @@ cdef class Matrix_integer_dense(Matrix_dense): def _rational_kernel_flint(self): """ - Return the rational (left) kernel of this matrix + Return the rational (left) kernel of this matrix. OUTPUT: A matrix ``K`` such that ``self * K = 0``, and the number of columns of - K equals the nullity of self. + K equals the nullity of ``self``. EXAMPLES:: @@ -4001,26 +3975,22 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: + - ``self`` -- an invertible matrix - - ``self`` -- an invertible matrix - - - ``use_nullspace`` -- (default: ``False``): whether to - use nullspace algorithm, which is slower, but doesn't require - checking that the matrix is invertible as a precondition. + - ``use_nullspace`` -- boolean (default: ``False``); whether to + use nullspace algorithm, which is slower, but doesn't require + checking that the matrix is invertible as a precondition - - ``check_invertible`` -- (default: ``True``) whether to - check that the matrix is invertible. + - ``check_invertible`` -- boolean (default: ``True``); whether to + check that the matrix is invertible + OUTPUT: `A`, `d` such that ``A*self == d`` - OUTPUT: A, d such that ``A*self == d`` + - ``A`` -- a matrix over ZZ + - ``d`` -- integer - - ``A`` -- a matrix over ZZ - - - ``d`` -- an integer - - - ALGORITHM: Uses IML's p-adic nullspace function. + ALGORITHM: Uses IML's `p`-adic nullspace function. EXAMPLES:: @@ -4066,15 +4036,13 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - ``self`` -- an invertible matrix - - OUTPUT: A, d such that ``A*self == d`` + - ``self`` -- an invertible matrix + OUTPUT: `A`, `d` such that ``A*self == d`` - - ``A`` -- a matrix over ZZ - - - ``d`` -- an integer + - ``A`` -- a matrix over ZZ + - ``d`` -- integer EXAMPLES:: @@ -4120,7 +4088,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def __invert__(self): r""" - Return the inverse of self. + Return the inverse of ``self``. EXAMPLES:: @@ -4156,7 +4124,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def inverse_of_unit(self): r""" - If self is a matrix with determinant `1` or `-1` return the inverse of + If ``self`` is a matrix with determinant `1` or `-1` return the inverse of ``self`` as a matrix over `ZZ`. EXAMPLES:: @@ -4180,7 +4148,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def _solve_right_nonsingular_square(self, B, check_rank=True, algorithm = 'iml'): r""" - If self is a matrix `A` of full rank, then this function + If ``self`` is a matrix `A` of full rank, then this function returns a vector or matrix `X` such that `A X = B`. If `B` is a vector then `X` is a vector and if `B` is a matrix, then `X` is a matrix. The base @@ -4199,11 +4167,10 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: + - ``B`` -- a matrix or vector - - ``B`` -- a matrix or vector - - - ``check_rank`` -- bool (default: ``True``); if True - verify that in fact the rank is full. + - ``check_rank`` -- boolean (default: ``True``); if ``True`` + verify that in fact the rank is full - ``algorithm`` -- ``'iml'`` (default) or ``'flint'`` @@ -4275,7 +4242,6 @@ cdef class Matrix_integer_dense(Matrix_dense): sage: x = a._solve_right_nonsingular_square(v,algorithm = 'flint') sage: a * x == v True - """ t = verbose('starting %s solve_right...' % algorithm) @@ -4330,17 +4296,15 @@ cdef class Matrix_integer_dense(Matrix_dense): def _solve_iml(self, Matrix_integer_dense B, right=True): """ - Let A equal self be a square matrix. Given B return an integer - matrix C and an integer d such that self ``C*A == d*B`` if right is + Let A equal ``self`` be a square matrix. Given B return an integer + matrix C and an integer d such that ``self`` ``C*A == d*B`` if right is False or ``A*C == d*B`` if right is True. OUTPUT: + - ``C`` -- integer matrix - - ``C`` -- integer matrix - - - ``d`` -- integer denominator - + - ``d`` -- integer denominator EXAMPLES:: @@ -4496,17 +4460,15 @@ cdef class Matrix_integer_dense(Matrix_dense): def _solve_flint(self, Matrix_integer_dense B, right=True): """ - Let A equal self be a square matrix. Given B return an integer - matrix C and an integer d such that self ``C*A == d*B`` if right is - False or ``A*C == d*B`` if right is True. + Let A equal ``self`` be a square matrix. Given B return an integer + matrix C and an integer d such that ``self`` ``C*A == d*B`` if right is + ``False`` or ``A*C == d*B`` if right is ``True``. OUTPUT: + - ``C`` -- integer matrix - - ``C`` -- integer matrix - - - ``d`` -- integer denominator - + - ``d`` -- integer denominator EXAMPLES:: @@ -4628,29 +4590,26 @@ cdef class Matrix_integer_dense(Matrix_dense): def _rational_echelon_via_solve(self, solver = 'iml'): r""" - Computes information that gives the reduced row echelon form (over + Compute information that gives the reduced row echelon form (over QQ!) of a matrix with integer entries. INPUT: - - - ``self`` -- a matrix over the integers. + - ``self`` -- a matrix over the integers - ``solver`` -- either ``'iml'`` (default) or ``'flint'`` OUTPUT: + - ``pivots`` -- ordered list of integers that give the + pivot column positions - - ``pivots`` -- ordered list of integers that give the - pivot column positions - - - ``nonpivots`` -- ordered list of the nonpivot column - positions - - - ``X`` -- matrix with integer entries + - ``nonpivots`` -- ordered list of the nonpivot column + positions - - ``d`` -- integer + - ``X`` -- matrix with integer entries + - ``d`` -- integer If you put standard basis vectors in order at the pivot columns, and put the matrix ``(1/d)*X`` everywhere else, then you get the @@ -4821,12 +4780,10 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: + - ``self`` -- a matrix over the integers - - ``self`` -- a matrix over the integers - - - ``**kwds`` -- these are passed onto to the - decomposition over QQ command. - + - ``**kwds`` -- these are passed onto to the + decomposition over QQ command EXAMPLES:: @@ -4864,38 +4821,35 @@ cdef class Matrix_integer_dense(Matrix_dense): return decomp_seq([(W.intersection(V), t) for W, t in X]) def _add_row_and_maintain_echelon_form(self, row, pivots): - """ - Assuming self is a full rank n x m matrix in reduced row Echelon - form over ZZ and row is a vector of degree m, this function creates - a new matrix that is the echelon form of self with row appended to + r""" + Assuming ``self`` is a full rank n x m matrix in reduced row Echelon + form over `\ZZ` and row is a vector of degree m, this function creates + a new matrix that is the echelon form of ``self`` with row appended to the bottom. .. WARNING:: - It is assumed that self is in echelon form. + It is assumed that ``self`` is in echelon form. INPUT: + - ``row`` -- a vector of degree m over `\ZZ` - - ``row`` -- a vector of degree m over ZZ - - - ``pivots`` -- a list of integers that are the pivot - columns of self. - - - OUTPUT: + - ``pivots`` -- list of integers that are the pivot + columns of ``self`` + OUTPUT: tuple of - - ``matrix`` -- a matrix of in reduced row echelon form - over ZZ + - ``matrix`` -- a matrix of in reduced row echelon form + over `\ZZ` - - ``pivots`` -- list of integers + - ``pivots`` -- list of integers ALGORITHM: For each pivot column of self, we use the extended Euclidean algorithm to clear the column. The result is a new matrix B whose row span is the same as self.stack(row), and whose last row - is 0 if and only if row is in the QQ-span of the rows of self. If + is 0 if and only if row is in the QQ-span of the rows of ``self``. If row is not in the QQ-span of the rows of self, then row is nonzero and suitable to be inserted into the top n rows of A to form a new matrix that is in reduced row echelon form. We then clear that @@ -5039,16 +4993,14 @@ cdef class Matrix_integer_dense(Matrix_dense): """ INPUT: - - ``D`` -- a small integer that is assumed to be a - multiple of ``2*det(self)`` + - ``D`` -- small integer that is assumed to be a + multiple of ``2*det(self)`` - OUTPUT: - - - ``matrix`` -- the Hermite normal form of self + OUTPUT: ``matrix`` -- the Hermite normal form of self EXAMPLES: - A ``ValueError`` is raised if the matrix is not square, + A :exc:`ValueError` is raised if the matrix is not square, fixing :issue:`5548`:: sage: random_matrix(ZZ,16,4)._hnf_mod(100) @@ -5067,7 +5019,7 @@ cdef class Matrix_integer_dense(Matrix_dense): cdef int _hnf_modn(Matrix_integer_dense self, Matrix_integer_dense res, unsigned int det) except -1: """ - Puts self into HNF form modulo det. Changes self in place. + Puts ``self`` into HNF form modulo det. Changes ``self`` in place. """ cdef int* res_l cdef Py_ssize_t i,j,k @@ -5209,13 +5161,13 @@ cdef class Matrix_integer_dense(Matrix_dense): def row(self, Py_ssize_t i, from_list=False): """ - Return the i-th row of this matrix as a dense vector. + Return the `i`-th row of this matrix as a dense vector. INPUT: - - ``i`` -- integer + - ``i`` -- integer - - ``from_list`` -- ignored + - ``from_list`` -- ignored EXAMPLES:: @@ -5252,13 +5204,13 @@ cdef class Matrix_integer_dense(Matrix_dense): def column(self, Py_ssize_t i, from_list=False): """ - Return the i-th column of this matrix as a dense vector. + Return the `i`-th column of this matrix as a dense vector. INPUT: - - ``i`` -- integer + - ``i`` -- integer - - ``from_list`` -- ignored + - ``from_list`` -- ignored EXAMPLES:: @@ -5356,10 +5308,10 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - ``right`` -- a matrix, vector or free module element, whose - dimensions are compatible with ``self``. + dimensions are compatible with ``self`` - - ``subdivide`` -- default: ``False`` -- request the resulting - matrix to have a new subdivision, separating ``self`` from ``right``. + - ``subdivide`` -- (default: ``False``) request the resulting + matrix to have a new subdivision, separating ``self`` from ``right`` OUTPUT: @@ -5436,7 +5388,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def insert_row(self, Py_ssize_t index, row): """ - Create a new matrix from self with. + Create a new matrix from ``self`` with. INPUT: @@ -5492,7 +5444,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def _delete_zero_columns(self): """ - Return matrix obtained from self by deleting all zero columns along + Return matrix obtained from ``self`` by deleting all zero columns along with the positions of those columns. OUTPUT: (matrix, list of integers) @@ -5515,12 +5467,12 @@ cdef class Matrix_integer_dense(Matrix_dense): def _insert_zero_columns(self, cols): """ - Return matrix obtained by self by inserting zero columns so that + Return matrix obtained by ``self`` by inserting zero columns so that the columns with positions specified in cols are all 0. INPUT: - - ``cols`` -- list of nonnegative integers + - ``cols`` -- list of nonnegative integers OUTPUT: matrix @@ -5556,7 +5508,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def _factor_out_common_factors_from_each_row(self): """ - Very very quickly modifies self so that the gcd of the entries in + Very very quickly modify ``self`` so that the gcd of the entries in each row is 1 by dividing each row by the common gcd. EXAMPLES:: @@ -5643,10 +5595,8 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - - - ``singular`` -- Singular interface instance (default: - None) - + - ``singular`` -- Singular interface instance (default: + ``None``) EXAMPLES:: @@ -5671,7 +5621,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def transpose(self): """ - Return the transpose of self, without changing self. + Return the transpose of self, without changing ``self``. EXAMPLES: @@ -5722,7 +5672,7 @@ cdef class Matrix_integer_dense(Matrix_dense): def antitranspose(self): """ - Return the antitranspose of self, without changing self. + Return the antitranspose of ``self``, without changing ``self``. EXAMPLES:: @@ -5809,11 +5759,10 @@ cdef class Matrix_integer_dense(Matrix_dense): INPUT: - ``flag`` -- 0 (default), 1, 3 or 4 (see docstring for - ``pari.mathnf``). + ``pari.mathnf``) - - ``include_zero_rows`` -- boolean. if False, do not include - any of the zero rows at the bottom of the matrix in the - output. + - ``include_zero_rows`` -- boolean; if ``False``, do not include + any of the zero rows at the bottom of the matrix in the output .. NOTE:: @@ -5890,7 +5839,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``p`` -- a prime in `\ZZ` - - ``s_max`` -- a positive integer (default: ``None``); if set, only + - ``s_max`` -- positive integer (default: ``None``); if set, only `(p^s)`-minimal polynomials for ``s <= s_max`` are computed (see below for details) @@ -5935,9 +5884,7 @@ cdef class Matrix_integer_dense(Matrix_dense): - ``b`` -- an element of `\ZZ` (default: 0) - OUTPUT: - - An ideal in `\ZZ[X]`. + OUTPUT: an ideal in `\ZZ[X]` EXAMPLES:: @@ -6054,16 +6001,13 @@ cpdef _lift_crt(Matrix_integer_dense M, residues, moduli=None): """ INPUT: - - ``M`` -- A ``Matrix_integer_dense``. Will be modified to hold - the output. - - - ``residues`` -- a list of ``Matrix_modn_dense_template``. The - matrix to reconstruct modulo primes. + - ``M`` -- a ``Matrix_integer_dense``; will be modified to hold + the output - OUTPUT: + - ``residues`` -- list of ``Matrix_modn_dense_template``; the + matrix to reconstruct modulo primes - The matrix whose reductions modulo primes are the input - ``residues``. + OUTPUT: the matrix whose reductions modulo primes are the input ``residues`` TESTS:: diff --git a/src/sage/matrix/matrix_integer_dense_hnf.py b/src/sage/matrix/matrix_integer_dense_hnf.py index c30927c6131..e64134ea184 100644 --- a/src/sage/matrix/matrix_integer_dense_hnf.py +++ b/src/sage/matrix/matrix_integer_dense_hnf.py @@ -24,11 +24,9 @@ def max_det_prime(n): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - a prime number + OUTPUT: a prime number EXAMPLES:: @@ -48,18 +46,18 @@ def max_det_prime(n): def det_from_modp_and_divisor(A, d, p, z_mod, moduli, z_so_far=ZZ(1), N_so_far=ZZ(1)): """ This is used for internal purposes for computing determinants - quickly (with the hybrid p-adic / multimodular algorithm). + quickly (with the hybrid `p`-adic / multimodular algorithm). INPUT: - - A -- a square matrix - - d -- a divisor of the determinant of A - - p -- a prime - - z_mod -- values of det/d (mod ...) - - moduli -- the moduli so far - - z_so_far -- for a modulus p in the list moduli, - (z_so_far mod p) is the determinant of A modulo p. - - N_so_far -- N_so_far is the product over the primes in the list moduli. + - ``A`` -- a square matrix + - ``d`` -- a divisor of the determinant of A + - ``p`` -- a prime + - ``z_mod`` -- values of det/d (mod ...) + - ``moduli`` -- the moduli so far + - ``z_so_far`` -- for a modulus p in the list moduli, + (z_so_far mod p) is the determinant of A modulo p + - ``N_so_far`` -- N_so_far is the product over the primes in the list moduli OUTPUT: @@ -97,19 +95,17 @@ def det_given_divisor(A, d, proof=True, stabilize=2): INPUT: - - ``A`` -- a square integer matrix - - ``d`` -- a nonzero integer that is assumed to divide the determinant of A - - ``proof`` -- bool (default: ``True``) compute det modulo enough primes + - ``A`` -- square integer matrix + - ``d`` -- nonzero integer that is assumed to divide the determinant of A + - ``proof`` -- boolean (default: ``True``); compute det modulo enough primes so that the determinant is computed provably correctly (via the Hadamard bound). It would be VERY hard for ``det()`` to fail even - with proof=False. - - ``stabilize`` -- int (default: 2) if proof = False, then compute + when ``proof`` is ``False``. + - ``stabilize`` -- integer (default: 2); if proof = False, then compute the determinant modulo `p` until ``stabilize`` successive modulo determinant computations stabilize. - OUTPUT: - - integer -- determinant + OUTPUT: integer; determinant EXAMPLES:: @@ -135,7 +131,7 @@ def det_given_divisor(A, d, proof=True, stabilize=2): 0 This still works, because we do not work modulo primes that divide - the determinant bound, which is found using a p-adic algorithm:: + the determinant bound, which is found using a `p`-adic algorithm:: sage: a.det(proof=False, stabilize=2) 70368442188091 @@ -194,7 +190,7 @@ def det_given_divisor(A, d, proof=True, stabilize=2): def det_padic(A, proof=True, stabilize=2): """ - Return the determinant of A, computed using a p-adic/multimodular + Return the determinant of A, computed using a `p`-adic/multimodular algorithm. INPUT: @@ -203,8 +199,8 @@ def det_padic(A, proof=True, stabilize=2): - ``proof`` -- boolean - - ``stabilize`` (default: 2) -- if proof False, number of successive primes so that - CRT det must stabilize. + - ``stabilize`` -- (default: 2) if proof False, number of successive primes so that + CRT det must stabilize EXAMPLES:: @@ -235,15 +231,13 @@ def double_det(A, b, c, proof): INPUT: - - A -- an (n-1) x n matrix - - b -- a 1 x n matrix - - c -- a 1 x n matrix - - proof -- whether or not to compute the det modulo enough times to - provably compute the determinant. - - OUTPUT: + - ``A`` -- an (n-1) x n matrix + - ``b`` -- a 1 x n matrix + - ``c`` -- a 1 x n matrix + - ``proof`` -- whether or not to compute the det modulo enough times to + provably compute the determinant - - a pair of two integers. + OUTPUT: a pair of two integers EXAMPLES:: @@ -293,13 +287,12 @@ def add_column_fallback(B, a, proof): INPUT: - B -- a square matrix (may be singular) - a -- an n x 1 matrix, where B has n rows - proof -- bool; whether to prove result correct + - ``B`` -- a square matrix (may be singular) + - ``a`` -- an n x 1 matrix, where B has n rows + - ``proof`` -- boolean; whether to prove result correct - OUTPUT: - - x -- a vector such that H' = H_B.augment(x) is the HNF of A = B.augment(a). + OUTPUT: x; a vector such that ``H' = H_B.augment(x)`` is the HNF of + ``A = B.augment(a)`` EXAMPLES:: @@ -329,20 +322,18 @@ def add_column_fallback(B, a, proof): def solve_system_with_difficult_last_row(B, a): """ - Solve B*x = a when the last row of `B` contains huge entries using - a clever trick that reduces the problem to solve C*x = a where `C` + Solve ``B*x = a`` when the last row of `B` contains huge entries using + a clever trick that reduces the problem to solve ``C*x = a`` where `C` is `B` but with the last row replaced by something small, along with one easy null space computation. The latter are both solved `p`-adically. INPUT: - - B -- a square n x n nonsingular matrix with painful big bottom row. - - a -- an n x 1 column matrix - - OUTPUT: + - ``B`` -- a square n x n nonsingular matrix with painful big bottom row + - ``a`` -- an n x 1 column matrix - - the unique solution to B*x = a. + OUTPUT: the unique solution to ``B*x = a`` EXAMPLES:: @@ -419,14 +410,14 @@ def add_column(B, H_B, a, proof): INPUT: - - B -- a square matrix (may be singular) - - H_B -- the Hermite normal form of B - - a -- an n x 1 matrix, where B has n rows - - proof -- bool; whether to prove result correct, in case we use fallback method. + - ``B`` -- a square matrix (may be singular) + - ``H_B`` -- the Hermite normal form of B + - ``a`` -- an n x 1 matrix, where B has n rows + - ``proof`` -- boolean; whether to prove result correct, in case we use fallback method OUTPUT: - - x -- a vector such that H' = H_B.augment(x) is the HNF of A = B.augment(a). + - x -- a vector such that H' = H_B.augment(x) is the HNF of A = B.augment(a) EXAMPLES:: @@ -469,14 +460,14 @@ def add_row(A, b, pivots, include_zero_rows): INPUT: - - A -- a matrix in Hermite normal form with n column - - b -- an n x 1 row matrix - - pivots -- sorted list of integers; the pivot positions of A. + - ``A`` -- a matrix in Hermite normal form with n column + - ``b`` -- an n x 1 row matrix + - ``pivots`` -- sorted list of integers; the pivot positions of A OUTPUT: - - H -- the Hermite normal form of A.stack(b). - - new_pivots -- the pivot columns of H. + - ``H`` -- the Hermite normal form of A.stack(b) + - ``new_pivots`` -- the pivot columns of H EXAMPLES:: @@ -508,11 +499,9 @@ def pivots_of_hnf_matrix(H): INPUT: - - H -- a matrix that must be HNF - - OUTPUT: + - ``H`` -- a matrix that must be HNF - - list -- list of pivots + OUTPUT: list of pivots EXAMPLES:: @@ -542,11 +531,9 @@ def hnf_square(A, proof): """ INPUT: - - a nonsingular n x n matrix A over the integers. + - ``A`` -- a nonsingular n x n matrix over the integers - OUTPUT: - - - the Hermite normal form of A. + OUTPUT: the Hermite normal form of A EXAMPLES:: @@ -568,7 +555,7 @@ def hnf_square(A, proof): # Small cases -- do not use this algorithm if n <= 3: - return A.echelon_form(algorithm="pari") + return A.echelon_form(algorithm='pari') if A.rank() < A.nrows(): raise ValueError("matrix must have full rank") @@ -675,11 +662,9 @@ def probable_pivot_rows(A): INPUT: - - A -- a matrix - - OUTPUT: + - ``A`` -- a matrix - a tuple of integers + OUTPUT: a tuple of integers EXAMPLES:: @@ -699,11 +684,9 @@ def probable_pivot_columns(A): """ INPUT: - - A -- a matrix + - ``A`` -- a matrix - OUTPUT: - - a tuple of integers + OUTPUT: a tuple of integers EXAMPLES:: @@ -729,8 +712,8 @@ def ones(H, pivots): INPUT: - - H -- matrix in Hermite form - - pivots -- list of integers (all pivot positions of H). + - ``H`` -- matrix in Hermite form + - ``pivots`` -- list of integers (all pivot positions of H) OUTPUT: @@ -770,8 +753,8 @@ def extract_ones_data(H, pivots): INPUT: - - H -- a matrix in HNF - - pivots -- list of all pivot column positions of H + - ``H`` -- a matrix in HNF + - ``pivots`` -- list of all pivot column positions of H OUTPUT: @@ -779,9 +762,9 @@ def extract_ones_data(H, pivots): where onecol, onerow, non_onecol, non_onerow are as for the ones function, and C, D, E are matrices: - - C -- submatrix of all non-onecol columns and onecol rows - - D -- all non-onecol columns and other rows - - E -- inverse of D + - ``C`` -- submatrix of all non-onecol columns and onecol rows + - ``D`` -- all non-onecol columns and other rows + - ``E`` -- inverse of D If D is not invertible or there are 0 or more than 2 non onecols, then C, D, and E are set to None. @@ -833,9 +816,7 @@ def is_in_hnf_form(H, pivots): - ``H`` -- matrix - ``pivots`` -- sorted list of integers - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -880,9 +861,9 @@ def probable_hnf(A, include_zero_rows, proof): INPUT: - - A -- a matrix - - include_zero_rows -- bool - - proof -- bool + - ``A`` -- a matrix + - ``include_zero_rows`` -- boolean + - ``proof`` -- boolean OUTPUT: @@ -1012,12 +993,10 @@ def pad_zeros(A, nrows): INPUT: - - A -- a matrix - - nrows -- an integer that is at least as big as the number of rows of A. - - OUTPUT: + - ``A`` -- a matrix + - ``nrows`` -- integer that is at least as big as the number of rows of A - a matrix with nrows rows. + OUTPUT: a matrix with nrows rows EXAMPLES:: @@ -1047,15 +1026,15 @@ def hnf(A, include_zero_rows=True, proof=True): INPUT: - - A -- an n x m matrix A over the integers. - - include_zero_rows -- bool (default: ``True``) whether or not to include zero + - ``A`` -- an n x m matrix A over the integers + - ``include_zero_rows`` -- boolean (default: ``True``); whether or not to include zero rows in the output matrix - - proof -- whether or not to prove the result correct. + - ``proof`` -- whether or not to prove the result correct - OUTPUT: + OUTPUT: tuple of: - - matrix -- the Hermite normal form of A - - pivots -- the pivot column positions of A + - ``matrix`` -- the Hermite normal form of A + - ``pivots`` -- the pivot column positions of A EXAMPLES:: @@ -1123,13 +1102,13 @@ def hnf_with_transformation(A, proof=True): INPUT: - - A -- an n x m matrix A over the integers. - - proof -- whether or not to prove the result correct. + - ``A`` -- an n x m matrix A over the integers + - ``proof`` -- whether or not to prove the result correct - OUTPUT: + OUTPUT: tuple of: - - matrix -- the Hermite normal form H of A - - U -- a unimodular matrix such that U * A = H + - ``matrix`` -- the Hermite normal form H of A + - ``U`` -- a unimodular matrix such that U * A = H EXAMPLES:: @@ -1223,17 +1202,17 @@ def benchmark_magma_hnf(nrange, bits=4): def sanity_checks(times=50, n=8, m=5, proof=True, stabilize=2, check_using_magma=True): """ - Run random sanity checks on the modular p-adic HNF with tall and wide matrices + Run random sanity checks on the modular `p`-adic HNF with tall and wide matrices both dense and sparse. INPUT: - - times -- number of times to randomly try matrices with each shape - - n -- number of rows - - m -- number of columns - - proof -- test with proof true - - stabilize -- parameter to pass to hnf algorithm when proof is False - - check_using_magma -- if True use Magma instead of PARI to check + - ``times`` -- number of times to randomly try matrices with each shape + - ``n`` -- number of rows + - ``m`` -- number of columns + - ``proof`` -- test with proof true + - ``stabilize`` -- parameter to pass to hnf algorithm when proof is False + - ``check_using_magma`` -- if ``True`` use Magma instead of PARI to check correctness of computed HNF's. Since PARI's HNF is buggy and slow (as of 2008-02-16 non-pivot entries sometimes are not normalized to be nonnegative) the default is Magma. diff --git a/src/sage/matrix/matrix_integer_dense_saturation.py b/src/sage/matrix/matrix_integer_dense_saturation.py index 5b6c181de15..b537b041e08 100644 --- a/src/sage/matrix/matrix_integer_dense_saturation.py +++ b/src/sage/matrix/matrix_integer_dense_saturation.py @@ -17,9 +17,9 @@ def p_saturation(A, p, proof=True): """ INPUT: - - A -- a matrix over ZZ - - p -- a prime - - proof -- bool (default: ``True``) + - ``A`` -- a matrix over ZZ + - ``p`` -- a prime + - ``proof`` -- boolean (default: ``True``) OUTPUT: @@ -72,12 +72,10 @@ def random_sublist_of_size(k, n): """ INPUT: - - k -- an integer - - n -- an integer + - ``k`` -- integer + - ``n`` -- integer - OUTPUT: - - a randomly chosen sublist of range(k) of size n. + OUTPUT: a randomly chosen sublist of ``range(k)`` of size `n` EXAMPLES:: @@ -119,17 +117,15 @@ def random_sublist_of_size(k, n): def solve_system_with_difficult_last_row(B, A): """ - Solve the matrix equation B*Z = A when the last row of `B` + Solve the matrix equation ``B*Z = A`` when the last row of `B` contains huge entries. INPUT: - - B -- a square n x n nonsingular matrix with painful big bottom row. - - A -- an n x k matrix. + - ``B`` -- a square n x n nonsingular matrix with painful big bottom row + - ``A`` -- an n x k matrix - OUTPUT: - - the unique solution to B*Z = A. + OUTPUT: the unique solution to ``B*Z = As`` EXAMPLES:: @@ -186,21 +182,19 @@ def solve_system_with_difficult_last_row(B, A): return X def saturation(A, proof=True, p=0, max_dets=5): - """ - Compute a saturation matrix of A. + r""" + Compute a saturation matrix of `A`. INPUT: - - A -- a matrix over ZZ - - proof -- bool (default: ``True``) - - p -- int (default: 0); if not 0 only guarantees that output is - p-saturated - - max_dets -- int (default: 4) max number of dets of submatrices to - compute. - - OUTPUT: + - ``A`` -- a matrix over `\ZZ` + - ``proof`` -- boolean (default: ``True``) + - ``p`` -- integer (default: 0); if not 0 only guarantees that output is + `p`-saturated + - ``max_dets`` -- integer (default: 4); max number of dets of submatrices to + compute - matrix -- saturation of the matrix A. + OUTPUT: matrix; saturation of the matrix `A` EXAMPLES:: @@ -299,9 +293,7 @@ def index_in_saturation(A, proof=True): - ``proof`` -- boolean (``True`` or ``False``) - OUTPUT: - - An integer + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/matrix/matrix_integer_sparse.pyx b/src/sage/matrix/matrix_integer_sparse.pyx index 4771953bb63..ca8949e5cad 100644 --- a/src/sage/matrix/matrix_integer_sparse.pyx +++ b/src/sage/matrix/matrix_integer_sparse.pyx @@ -98,8 +98,8 @@ cdef class Matrix_integer_sparse(Matrix_sparse): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the - entries are of type :class:`Integer`. + - ``coerce`` -- if ``False``, assume without checking that the + entries are of type :class:`Integer` """ ma = MatrixArgs_init(parent, entries) cdef Integer z @@ -297,7 +297,7 @@ cdef class Matrix_integer_sparse(Matrix_sparse): def _nonzero_positions_by_row(self, copy=True): """ - Returns the list of pairs (i,j) such that self[i,j] != 0. + Return the list of pairs (i,j) such that ``self[i,j] != 0``. It is safe to change the resulting list (unless you give the option copy=False). @@ -326,7 +326,7 @@ cdef class Matrix_integer_sparse(Matrix_sparse): def _nonzero_positions_by_column(self, copy=True): """ - Returns the list of pairs (i,j) such that self[i,j] != 0, but + Return the list of pairs (i,j) such that ``self[i,j] != 0``, but sorted by columns, i.e., column j=0 entries occur first, then column j=1 entries, etc. @@ -358,16 +358,14 @@ cdef class Matrix_integer_sparse(Matrix_sparse): return nzc def _mod_int(self, modulus): - """ + r""" Helper function in reducing matrices mod n. INPUT: - - `modulus` -- a number - - OUTPUT: + - ``modulus`` -- a number - This matrix, over `ZZ/nZZ`. + OUTPUT: this matrix, over `\ZZ/n\ZZ` TESTS:: @@ -375,7 +373,6 @@ cdef class Matrix_integer_sparse(Matrix_sparse): sage: B = M._mod_int(7) sage: B.parent() Full MatrixSpace of 0 by 0 sparse matrices over Ring of integers modulo 7 - """ return self._mod_int_c(modulus) @@ -424,20 +421,20 @@ cdef class Matrix_integer_sparse(Matrix_sparse): def _right_kernel_matrix(self, **kwds): r""" - Returns a pair that includes a matrix of basis vectors + Return a pair that includes a matrix of basis vectors for the right kernel of ``self``. INPUT: - ``algorithm`` -- determines which algorithm to use, options are: - - 'pari' -- use the :pari:`matkerint` function from the PARI library - - 'padic' -- use the p-adic algorithm from the IML library - - 'default' -- use a heuristic to decide which of the two above + - ``'pari'`` -- use the :pari:`matkerint` function from the PARI library + - ``'padic'`` -- use the `p`-adic algorithm from the IML library + - ``'default'`` -- use a heuristic to decide which of the two above routines is fastest. This is the default value. - - ``proof`` -- this is passed to the p-adic IML algorithm. - If not specified, the global flag for linear algebra will be used. + - ``proof`` -- this is passed to the `p`-adic IML algorithm + If not specified, the global flag for linear algebra will be used OUTPUT: @@ -539,15 +536,13 @@ cdef class Matrix_integer_sparse(Matrix_sparse): INPUT: - - self -- matrix - - algorithm -- (default: 'pari') + - ``self`` -- matrix + - ``algorithm`` -- (default: ``'pari'``) - * 'pari': works robustly, but is slower. + * 'pari': works robustly, but is slower * 'linbox' -- use linbox (currently off, broken) - OUTPUT: - - list of integers + OUTPUT: list of integers EXAMPLES:: @@ -579,12 +574,12 @@ cdef class Matrix_integer_sparse(Matrix_sparse): INPUT: - - ``transformation`` -- a boolean (default: ``True``); whether to + - ``transformation`` -- boolean (default: ``True``); whether to return the transformation matrices `U` and `V` such that `S = U\cdot - self\cdot V`. + self\cdot V` - ``integral`` -- a subring of the base ring or ``True`` (default: - ``None``); ignored for matrices with integer entries. + ``None``); ignored for matrices with integer entries This version is for sparse matrices and simply makes the matrix dense and calls the version for dense integer matrices. @@ -803,9 +798,9 @@ cdef class Matrix_integer_sparse(Matrix_sparse): TESTS:: - sage: matrix(ZZ, 0, 0, sparse=True).charpoly(algorithm="linbox") + sage: matrix(ZZ, 0, 0, sparse=True).charpoly(algorithm='linbox') 1 - sage: matrix(ZZ, 0, 0, sparse=True).charpoly(algorithm="generic") + sage: matrix(ZZ, 0, 0, sparse=True).charpoly(algorithm='generic') 1 """ if self._nrows != self._ncols: @@ -904,9 +899,9 @@ cdef class Matrix_integer_sparse(Matrix_sparse): TESTS:: - sage: matrix(ZZ, 0, 0, sparse=True).minpoly(algorithm="linbox") + sage: matrix(ZZ, 0, 0, sparse=True).minpoly(algorithm='linbox') 1 - sage: matrix(ZZ, 0, 0, sparse=True).minpoly(algorithm="generic") + sage: matrix(ZZ, 0, 0, sparse=True).minpoly(algorithm='generic') 1 """ if self._nrows != self._ncols: @@ -980,7 +975,7 @@ cdef class Matrix_integer_sparse(Matrix_sparse): def _solve_right_nonsingular_square(self, B, algorithm=None, check_rank=False): r""" - If self is a matrix `A`, then this function returns a + If ``self`` is a matrix `A`, then this function returns a vector or matrix `X` such that `A X = B`. If `B` is a vector then `X` is a vector and if `B` is a matrix, then `X` is a matrix. @@ -993,25 +988,24 @@ cdef class Matrix_integer_sparse(Matrix_sparse): INPUT: + - ``B`` -- a matrix or vector - - ``B`` -- a matrix or vector - - - ``algorithm`` -- one of the following: + - ``algorithm`` -- one of the following: - ``'linbox'`` or ``'linbox_default'`` -- (default) use LinBox and let it chooses the appropriate algorithm - - ``linbox_dense_elimination'`` -- use LinBox dense elimination + - ``linbox_dense_elimination'`` -- use LinBox dense elimination - ``'linbox_sparse_elimination'`` -- use LinBox sparse elimination - - ``'linbox_ blackbox'`` -- LinBox via a Blackbox algorithm + - ``'linbox_ blackbox'`` -- LinBox via a Blackbox algorithm - - ``'linbox_wiedemann'`` -- use LinBox implementation of - Wiedemann's algorithm + - ``'linbox_wiedemann'`` -- use LinBox implementation of + Wiedemann's algorithm - - ``'generic'`` -- use the Sage generic implementation - (via inversion) + - ``'generic'`` -- use the Sage generic implementation + (via inversion) - ``check_rank`` -- whether to check that the rank is maximal @@ -1061,22 +1055,22 @@ cdef class Matrix_integer_sparse(Matrix_sparse): def _solve_vector_linbox(self, v, algorithm=None): r""" - Return a pair ``(a, d)`` so that ``d * b = m * a`` + Return a pair ``(a, d)`` so that ``d * b = m * a``. - If there is no solution a ``ValueError`` is raised. + If there is no solution a :exc:`ValueError` is raised. INPUT: - - ``b`` -- a dense integer vector + - ``b`` -- dense integer vector - ``algorithm`` -- (optional) either ``None``, ``'dense_elimination'``, - ``'sparse_elimination'``, ``'wiedemann'`` or ``'blackbox'``. + ``'sparse_elimination'``, ``'wiedemann'`` or ``'blackbox'`` OUTPUT: a pair ``(a, d)`` consisting of - - ``a`` -- a dense integer vector + - ``a`` -- dense integer vector - - ``d`` -- an integer + - ``d`` -- integer EXAMPLES:: diff --git a/src/sage/matrix/matrix_laurent_mpolynomial_dense.pyx b/src/sage/matrix/matrix_laurent_mpolynomial_dense.pyx index c352b52cea2..d18140c1ce8 100644 --- a/src/sage/matrix/matrix_laurent_mpolynomial_dense.pyx +++ b/src/sage/matrix/matrix_laurent_mpolynomial_dense.pyx @@ -76,11 +76,9 @@ cdef class Matrix_laurent_mpolynomial_dense(Matrix_generic_dense): INPUT: - - ``i`` -- an integer + - ``i`` -- integer - OUTPUT: - - An ideal on the base ring. + OUTPUT: an ideal on the base ring EXAMPLES:: @@ -107,7 +105,6 @@ cdef class Matrix_laurent_mpolynomial_dense(Matrix_generic_dense): (1,) sage: [R.ideal(M.minors(i)) == M._fitting_ideal(4 - i) for i in range(5)] [True, True, True, True, True] - """ R = self.base_ring() S = R.polynomial_ring() diff --git a/src/sage/matrix/matrix_misc.py b/src/sage/matrix/matrix_misc.py index 3513a97da7d..35591735e57 100644 --- a/src/sage/matrix/matrix_misc.py +++ b/src/sage/matrix/matrix_misc.py @@ -38,7 +38,7 @@ def prm_mul(p1, p2, mask_free, prec): - `p1,p2` -- polynomials as dictionaries - - ``mask_free`` -- an integer mask that give the list of free variables + - ``mask_free`` -- integer mask that give the list of free variables (the `i`-th variable is free if the `i`-th bit of ``mask_free`` is `1`) - ``prec`` -- if ``prec`` is not ``None``, truncate the product at precision ``prec`` @@ -79,13 +79,13 @@ def permanental_minor_polynomial(A, permanent_only=False, var='t', prec=None): INPUT: - - `A` -- a matrix + - ``A`` -- a matrix - - `permanent_only` -- if True, return only the permanent of `A` + - ``permanent_only`` -- if ``True``, return only the permanent of `A` - - `var` -- name of the polynomial variable + - ``var`` -- name of the polynomial variable - - `prec` -- if prec is not None, truncate the polynomial at precision `prec` + - ``prec`` -- if prec is not None, truncate the polynomial at precision `prec` The polynomial of the sums of permanental minors is @@ -109,8 +109,8 @@ def permanental_minor_polynomial(A, permanent_only=False, var='t', prec=None): - ``A`` -- matrix - - ``permanent_only`` -- optional boolean. If ``True``, only the permanent - is computed (might be faster). + - ``permanent_only`` -- boolean (default: ``False``); if ``True``, only the + permanent is computed (might be faster) - ``var`` -- a variable name @@ -243,7 +243,7 @@ def permanental_minor_polynomial(A, permanent_only=False, var='t', prec=None): \right\rangle In fact the `t^k` coefficient of `g(t)` corresponds to choosing - `k` rows of `A`; `\eta_i` is associated to the i-th column; + `k` rows of `A`; `\eta_i` is associated to the `i`-th column; nilpotency avoids having twice the same column in a product of `A`'s. For more details, see the article [BP2015]_. diff --git a/src/sage/matrix/matrix_mod2_dense.pyx b/src/sage/matrix/matrix_mod2_dense.pyx index e84601ac37c..07c54d6add9 100644 --- a/src/sage/matrix/matrix_mod2_dense.pyx +++ b/src/sage/matrix/matrix_mod2_dense.pyx @@ -223,7 +223,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring EXAMPLES:: @@ -330,7 +330,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse # this exists for compatibility with matrix_modn_dense cdef void set_unsafe_int(self, Py_ssize_t i, Py_ssize_t j, int value) noexcept: """ - Set the (i,j) entry of self to the int value. + Set the (i,j) entry of ``self`` to the int value. """ mzd_write_bit(self._entries, i, j, int(value)) @@ -352,7 +352,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - ``rep_mapping`` -- a dictionary or callable used to override + - ``rep_mapping`` -- dictionary or callable used to override the usual representation of elements. For a dictionary, keys should be elements of the base ring and values the desired string representation. @@ -365,14 +365,14 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse use the value of ``plus_one`` as the representation of the one element. - - ``minus_one`` -- Ignored. Only for compatibility with + - ``minus_one`` -- ignored. Only for compatibility with generic matrices. - - ``unicode`` -- boolean (default: ``False``). - Whether to use Unicode symbols instead of ASCII symbols - for brackets and subdivision lines. + - ``unicode`` -- boolean (default: ``False``); + whether to use Unicode symbols instead of ASCII symbols + for brackets and subdivision lines - - ``shape`` -- one of ``"square"`` or ``"round"`` (default: ``None``). + - ``shape`` -- one of ``'square'`` or ``'round'`` (default: ``None``). Switches between round and square brackets. The default depends on the setting of the ``unicode`` keyword argument. For Unicode symbols, the default is round brackets @@ -477,7 +477,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def row(self, Py_ssize_t i, from_list=False): """ - Return the ``i``'th row of this matrix as a vector. + Return the ``i``-th row of this matrix as a vector. This row is a dense vector if and only if the matrix is a dense matrix. @@ -486,8 +486,8 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse - ``i`` -- integer - - ``from_list`` -- bool (default: ``False``); if ``True``, - returns the ``i``'th element of ``self.rows()`` (see + - ``from_list`` -- boolean (default: ``False``); if ``True``, + returns the ``i``-th element of ``self.rows()`` (see :func:`rows`), which may be faster, but requires building a list of all rows the first time it is called after an entry of the matrix is changed. @@ -527,7 +527,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def columns(self, copy=True): """ - Return list of the columns of self. + Return list of the columns of ``self``. INPUT: @@ -582,7 +582,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - right -- matrix of dimension self.nrows() x self.ncols() + - ``right`` -- matrix of dimension self.nrows() x self.ncols() EXAMPLES:: @@ -620,7 +620,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - right -- matrix of dimension self.nrows() x self.ncols() + - ``right`` -- matrix of dimension self.nrows() x self.ncols() EXAMPLES:: @@ -713,8 +713,8 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - right -- Matrix - - k -- parameter `k` for the Gray Code table size. If `k=0` a suitable + - ``right`` -- Matrix + - ``k`` -- parameter `k` for the Gray Code table size. If `k=0` a suitable value is chosen by the function. (`0<= k <= 16`, default: 0) EXAMPLES:: @@ -847,7 +847,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - ``right`` -- a matrix of matching dimensions. + - ``right`` -- a matrix of matching dimensions - ``cutoff`` -- matrix dimension where M4RM should be used instead of Strassen (default: let M4RI decide) @@ -921,10 +921,10 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def __invert__(self): """ - Inverts self using the 'Method of the Four Russians' + Invert ``self`` using the 'Method of the Four Russians' inversion. - If ``self`` is not invertible a ``ZeroDivisionError`` is + If ``self`` is not invertible a :exc:`ZeroDivisionError` is raised. EXAMPLES:: @@ -971,7 +971,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def __copy__(self): """ - Returns a copy of ``self``. + Return a copy of ``self``. EXAMPLES:: @@ -991,7 +991,6 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse sage: A.echelonize() sage: A.__copy__() == A True - """ cdef Matrix_mod2_dense A A = Matrix_mod2_dense.__new__(Matrix_mod2_dense, self._parent, 0, 0, 0) @@ -1006,7 +1005,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def _list(self): """ - Returns list of the elements of ``self`` in row major + Return list of the elements of ``self`` in row major ordering. EXAMPLES:: @@ -1044,22 +1043,22 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def echelonize(self, algorithm='heuristic', cutoff=0, reduced=True, **kwds): """ - Puts self in (reduced) row echelon form. + Puts ``self`` in (reduced) row echelon form. INPUT: - - self -- a mutable matrix - - algorithm + - ``self`` -- a mutable matrix + - ``algorithm`` -- string; one of - - 'heuristic' -- uses M4RI and PLUQ (default) - - 'm4ri' -- uses M4RI - - 'pluq' -- uses PLUQ factorization - - 'classical' -- uses classical Gaussian elimination + - ``'heuristic'`` -- uses M4RI and PLUQ (default) + - ``'m4ri'`` -- uses M4RI + - ``'pluq'`` -- uses PLUQ factorization + - ``'classical'`` -- uses classical Gaussian elimination - - k -- the parameter 'k' of the M4RI algorithm. It MUST be between 1 + - ``k`` -- the parameter 'k' of the M4RI algorithm. It MUST be between 1 and 16 (inclusive). If it is not specified it will be calculated as 3/4 * log_2( min(nrows, ncols) ) as suggested in the M4RI paper. - - reduced -- return reduced row echelon form (default: ``True``) + - ``reduced`` -- return reduced row echelon form (default: ``True``) EXAMPLES:: @@ -1168,7 +1167,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def _pivots(self): """ - Returns the pivot columns of ``self`` if ``self`` is in + Return the pivot columns of ``self`` if ``self`` is in row echelon form. EXAMPLES:: @@ -1207,14 +1206,12 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - ``density`` -- float; proportion (roughly) to be considered for - changes - - ``nonzero`` -- Bool (default: ``False``); whether the new entries - are forced to be non-zero - - OUTPUT: + - ``density`` -- float; proportion (roughly) to be considered for + changes + - ``nonzero`` -- boolean (default: ``False``); whether the new entries + are forced to be nonzero - - None, the matrix is modified in-space + OUTPUT: None, the matrix is modified in-space EXAMPLES:: @@ -1379,7 +1376,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def _magma_init_(self, magma): """ - Returns a string of self in ``Magma`` form. Does not return + Return a string of ``self`` in ``Magma`` form. Does not return ``Magma`` object but string. EXAMPLES:: @@ -1425,7 +1422,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def transpose(self): """ - Returns transpose of self and leaves self untouched. + Return transpose of ``self`` and leaves ``self`` untouched. EXAMPLES:: @@ -1700,10 +1697,10 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - row -- index of start row - - col -- index of start column - - nrows -- number of rows of submatrix - - ncols -- number of columns of submatrix + - ``row`` -- index of start row + - ``col`` -- index of start column + - ``nrows`` -- number of rows of submatrix + - ``ncols`` -- number of columns of submatrix EXAMPLES:: @@ -1853,7 +1850,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse INPUT: - - approx -- return floating point approximation (default: ``False``) + - ``approx`` -- return floating point approximation (default: ``False``) EXAMPLES:: @@ -1924,7 +1921,7 @@ cdef class Matrix_mod2_dense(matrix_dense.Matrix_dense): # dense or sparse def _right_kernel_matrix(self, **kwds): r""" - Returns a pair that includes a matrix of basis vectors + Return a pair that includes a matrix of basis vectors for the right kernel of ``self``. INPUT: @@ -2051,9 +2048,9 @@ def unpickle_matrix_mod2_dense_v2(r, c, data, size, immutable=False): - ``r`` -- number of rows of matrix - ``c`` -- number of columns of matrix - - ``s`` -- a string + - ``s`` -- string - ``size`` -- length of the string ``s`` - - ``immutable`` -- (default: ``False``) whether the + - ``immutable`` -- boolean (default: ``False``); whether the matrix is immutable or not EXAMPLES:: @@ -2127,13 +2124,13 @@ register_unpickle_override('sage.matrix.matrix_mod2_dense', def from_png(filename): """ - Returns a dense matrix over GF(2) from a 1-bit PNG image read from + Return a dense matrix over GF(2) from a 1-bit PNG image read from ``filename``. No attempt is made to verify that the filename string actually points to a PNG image. INPUT: - - filename -- a string + - ``filename`` -- string EXAMPLES:: @@ -2176,12 +2173,12 @@ def from_png(filename): def to_png(Matrix_mod2_dense A, filename): """ - Saves the matrix ``A`` to filename as a 1-bit PNG image. + Save the matrix ``A`` to filename as a 1-bit PNG image. INPUT: - ``A`` -- a matrix over GF(2) - - ``filename`` -- a string for a file in a writable position + - ``filename`` -- string for a file in a writable position EXAMPLES:: @@ -2219,21 +2216,21 @@ def to_png(Matrix_mod2_dense A, filename): fclose(out) -def pluq(Matrix_mod2_dense A, algorithm="standard", int param=0): +def pluq(Matrix_mod2_dense A, algorithm='standard', int param=0): """ Return PLUQ factorization of A. INPUT: - - A -- matrix - - algorithm + - ``A`` -- matrix + - ``algorithm`` -- string; one of - * 'standard' asymptotically fast (default) - * 'mmpf' M4RI inspired - * 'naive' naive cubic + * ``'standard'`` asymptotically fast (default) + * ``'mmpf'`` M4RI inspired + * ``'naive'`` naive cubic - - param -- either k for 'mmpf' is chosen or matrix multiplication cutoff - for 'standard' (default: 0) + - ``param`` -- either k for 'mmpf' is chosen or matrix multiplication cutoff + for ``'standard'`` (default: 0) EXAMPLES:: @@ -2283,20 +2280,20 @@ def pluq(Matrix_mod2_dense A, algorithm="standard", int param=0): return B, P, Q -def ple(Matrix_mod2_dense A, algorithm="standard", int param=0): +def ple(Matrix_mod2_dense A, algorithm='standard', int param=0): """ Return PLE factorization of A. INPUT: - - A -- matrix - - algorithm + - ``A`` -- matrix + - ``algorithm`` -- string; one of - - 'standard' asymptotically fast (default) - - 'russian' M4RI inspired - - 'naive' naive cubic + - ``'standard'`` asymptotically fast (default) + - ``'russian'`` M4RI inspired + - ``'naive'`` naive cubic - - param -- either k for 'mmpf' is chosen or matrix multiplication + - ``param`` -- either k for 'mmpf' is chosen or matrix multiplication cutoff for 'standard' (default: 0) EXAMPLES:: diff --git a/src/sage/matrix/matrix_modn_dense_double.pyx b/src/sage/matrix/matrix_modn_dense_double.pyx index b112ffba912..ecb41e7d5dd 100644 --- a/src/sage/matrix/matrix_modn_dense_double.pyx +++ b/src/sage/matrix/matrix_modn_dense_double.pyx @@ -47,7 +47,7 @@ include "matrix_modn_dense_template.pxi" cdef class Matrix_modn_dense_double(Matrix_modn_dense_template): r""" - Dense matrices over `\ZZ/n\ZZ` for `n < 94906266` using LinBox's ``Modular`` + Dense matrices over `\ZZ/n\ZZ` for `n < 94906266` using LinBox's ``Modular``. These are matrices with integer entries mod ``n`` represented as floating-point numbers in a 64-bit word for use with LinBox routines. @@ -61,7 +61,7 @@ cdef class Matrix_modn_dense_double(Matrix_modn_dense_template): def __cinit__(self): """ - The Cython constructor + The Cython constructor. TESTS:: @@ -75,7 +75,7 @@ cdef class Matrix_modn_dense_double(Matrix_modn_dense_template): cdef void set_unsafe_int(self, Py_ssize_t i, Py_ssize_t j, int value) noexcept: r""" - Set the (i,j) entry of self to the int value. + Set the (i,j) entry of ``self`` to the int value. EXAMPLES:: diff --git a/src/sage/matrix/matrix_modn_dense_float.pyx b/src/sage/matrix/matrix_modn_dense_float.pyx index 73fbe175d95..13dedf8441c 100644 --- a/src/sage/matrix/matrix_modn_dense_float.pyx +++ b/src/sage/matrix/matrix_modn_dense_float.pyx @@ -44,7 +44,7 @@ include "matrix_modn_dense_template.pxi" cdef class Matrix_modn_dense_float(Matrix_modn_dense_template): r""" - Dense matrices over `\ZZ/n\ZZ` for `n < 2^{8}` using LinBox's ``Modular`` + Dense matrices over `\ZZ/n\ZZ` for `n < 2^{8}` using LinBox's ``Modular``. These are matrices with integer entries mod ``n`` represented as floating-point numbers in a 32-bit word for use with LinBox routines. @@ -57,7 +57,7 @@ cdef class Matrix_modn_dense_float(Matrix_modn_dense_template): """ def __cinit__(self): """ - The Cython constructor + The Cython constructor. TESTS:: @@ -69,7 +69,7 @@ cdef class Matrix_modn_dense_float(Matrix_modn_dense_template): cdef void set_unsafe_int(self, Py_ssize_t i, Py_ssize_t j, int value) noexcept: r""" - Set the (i,j) entry of self to the int value. + Set the (i,j) entry of ``self`` to the int value. EXAMPLES:: diff --git a/src/sage/matrix/matrix_modn_dense_template.pxi b/src/sage/matrix/matrix_modn_dense_template.pxi index 500f531e3b6..ebf1bdeb7e9 100644 --- a/src/sage/matrix/matrix_modn_dense_template.pxi +++ b/src/sage/matrix/matrix_modn_dense_template.pxi @@ -403,7 +403,7 @@ cpdef __matrix_from_rows_of_matrices(X): INPUT: - ``X`` -- a nonempty list of matrices of the same size mod a - single modulus `n` + single modulus `n` EXAMPLES:: @@ -412,9 +412,9 @@ cpdef __matrix_from_rows_of_matrices(X): sage: all(list(Y[i]) == X[i].list() for i in range(10)) True - OUTPUT: A single matrix mod ``p`` whose ``i``-th row is ``X[i].list()``. + OUTPUT: a single matrix mod ``p`` whose ``i``-th row is ``X[i].list()``. - .. note:: + .. NOTE:: Do not call this function directly but use the static method ``Matrix_modn_dense_float/double._matrix_from_rows_of_matrices`` @@ -857,7 +857,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): cpdef _add_(self, right): r""" - Add two dense matrices over `\Z/n\Z` + Add two dense matrices over `\Z/n\Z`. INPUT: @@ -901,7 +901,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): cpdef _sub_(self, right): r""" - Subtract two dense matrices over `\Z/n\Z` + Subtract two dense matrices over `\Z/n\Z`. EXAMPLES:: @@ -989,7 +989,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): cdef _matrix_times_matrix_(self, Matrix right): """ - return ``self*right`` + Return ``self*right``. INPUT: @@ -1147,7 +1147,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): cdef _vector_times_matrix_(self, Vector v): """ - ``v*self`` + Return ``v*self``. INPUT: @@ -1174,7 +1174,6 @@ cdef class Matrix_modn_dense_template(Matrix_dense): sage: v = random_vector(Integers(16337), 10) # needs sage.rings.finite_rings sage: matrix(v*A) == matrix(v)*A True - """ if not isinstance(v, Vector_modn_dense): return (self.new_matrix(1,self._nrows, entries=v.list()) * self)[0] @@ -1204,7 +1203,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): cdef _matrix_times_vector_(self, Vector v): """ - ``self*v`` + Return ``self*v``. EXAMPLES:: @@ -1381,7 +1380,6 @@ cdef class Matrix_modn_dense_template(Matrix_dense): (y,) sage: A._cache['charpoly_linbox'].variables() (x,) - """ cache_key = 'charpoly_%s' % algorithm g = self.fetch(cache_key) @@ -1409,7 +1407,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def minpoly(self, var='x', algorithm='linbox', proof=None): """ - Returns the minimal polynomial of`` self``. + Return the minimal polynomial of ``self``. INPUT: @@ -1418,7 +1416,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): - ``algorithm`` -- ``generic`` or ``linbox`` (default: ``linbox``) - - ``proof`` -- (default: ``True``); whether to provably return + - ``proof`` -- (default: ``True``) whether to provably return the true minimal polynomial; if ``False``, we only guarantee to return a divisor of the minimal polynomial. There are also certainly cases where the computed results is @@ -1545,7 +1543,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def _charpoly_linbox(self, var='x'): """ - Computes the characteristic polynomial using LinBox. No checks + Compute the characteristic polynomial using LinBox. No checks are performed. This function is called internally by ``charpoly``. @@ -1578,7 +1576,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): r = R(v) return r - def echelonize(self, algorithm="linbox_noefd", **kwds): + def echelonize(self, algorithm='linbox_noefd', **kwds): """ Put ``self`` in reduced row echelon form. @@ -1593,23 +1591,21 @@ cdef class Matrix_modn_dense_template(Matrix_dense): - ``linbox_noefd`` -- uses the FFPACK directly, less memory and faster (default) - ``gauss`` -- uses a custom slower `O(n^3)` Gauss - elimination implemented in Sage. + elimination implemented in Sage - ``all`` -- compute using both algorithms and verify that - the results are the same. + the results are the same - ``**kwds`` -- these are all ignored - OUTPUT: - - - ``self`` is put in reduced row echelon form. + OUTPUT: ``self`` is put in reduced row echelon form - - the rank of self is computed and cached + - the rank of ``self`` is computed and cached - - the pivot columns of self are computed and cached. + - the pivot columns of ``self`` are computed and cached - - the fact that self is now in echelon form is recorded and - cached so future calls to echelonize return immediately. + - the fact that ``self`` is now in echelon form is recorded and + cached so future calls to echelonize return immediately EXAMPLES:: @@ -1853,7 +1849,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def right_kernel_matrix(self, algorithm='linbox', basis='echelon'): r""" - Returns a matrix whose rows form a basis for the right kernel + Return a matrix whose rows form a basis for the right kernel of ``self``. If the base ring is the ring of integers modulo a composite, @@ -1962,7 +1958,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def hessenbergize(self): """ - Transforms self in place to its Hessenberg form. + Transform ``self`` in place to its Hessenberg form. EXAMPLES:: @@ -2032,19 +2028,19 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def _charpoly_hessenberg(self, var): """ - Transforms self in place to its Hessenberg form then computes + Transform ``self`` in place to its Hessenberg form then computes and returns the coefficients of the characteristic polynomial of this matrix. INPUT: - - ``var`` -- name of the indeterminate of the charpoly. + - ``var`` -- name of the indeterminate of the charpoly OUTPUT: The characteristic polynomial is represented as a vector of ints, where the constant term of the characteristic - polynomial is the 0th coefficient of the vector. + polynomial is the `0`-th coefficient of the vector. EXAMPLES:: @@ -2293,9 +2289,9 @@ cdef class Matrix_modn_dense_template(Matrix_dense): - ``row1``, ``row2`` -- the two rows to be transformed (within ``self``) - -``start_col`` -- the column of the pivots in ``row1`` and - ``row2``. It is assumed that all entries before ``start_col`` - in ``row1`` and ``row2`` are zero. + - ``start_col`` -- the column of the pivots in ``row1`` and + ``row2``. It is assumed that all entries before ``start_col`` + in ``row1`` and ``row2`` are zero. OUTPUT: @@ -2535,14 +2531,12 @@ cdef class Matrix_modn_dense_template(Matrix_dense): INPUT: - - ``density`` -- Integer; proportion (roughly) to be considered - for changes - - ``nonzero`` -- Bool (default: ``False``); whether the new - entries are forced to be non-zero + - ``density`` -- integer; proportion (roughly) to be considered + for changes + - ``nonzero`` -- boolean (default: ``False``); whether the new + entries are forced to be nonzero - OUTPUT: - - - None, the matrix is modified in-space + OUTPUT: none, the matrix is modified in-space EXAMPLES:: @@ -2650,11 +2644,11 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def _magma_init_(self, magma): """ - Returns a string representation of ``self`` in Magma form. + Return a string representation of ``self`` in Magma form. INPUT: - - ``magma`` -- a Magma session + - ``magma`` -- a Magma session OUTPUT: string @@ -2967,16 +2961,16 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def submatrix(self, Py_ssize_t row=0, Py_ssize_t col=0, Py_ssize_t nrows=-1, Py_ssize_t ncols=-1): r""" - Return the matrix constructed from self using the specified + Return the matrix constructed from ``self`` using the specified range of rows and columns. INPUT: - - ``row``, ``col`` -- index of the starting row and column. - Indices start at zero + - ``row``, ``col`` -- index of the starting row and column; + indices start at zero - ``nrows``, ``ncols`` -- (optional) number of rows and columns to - take. If not provided, take all rows below and all columns to + take; if not provided, take all rows below and all columns to the right of the starting entry .. SEEALSO:: @@ -3065,9 +3059,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): [2 3], [6 7], [10 11], [14 15] ] - OUTPUT: - - - ``list`` -- a list of matrices + OUTPUT: list of matrices """ if nrows * ncols != self._ncols: raise ValueError("nrows * ncols must equal self's number of columns") @@ -3084,7 +3076,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def matrix_from_columns(self, columns): """ - Return the matrix constructed from self using columns with indices + Return the matrix constructed from ``self`` using columns with indices in the columns list. EXAMPLES:: @@ -3114,7 +3106,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def matrix_from_rows(self, rows): """ - Return the matrix constructed from self using rows with indices in + Return the matrix constructed from ``self`` using rows with indices in the rows list. EXAMPLES:: @@ -3143,7 +3135,7 @@ cdef class Matrix_modn_dense_template(Matrix_dense): def matrix_from_rows_and_columns(self, rows, columns): """ - Return the matrix constructed from self from the given rows and + Return the matrix constructed from ``self`` from the given rows and columns. EXAMPLES:: diff --git a/src/sage/matrix/matrix_modn_sparse.pyx b/src/sage/matrix/matrix_modn_sparse.pyx index e5b7ca0b619..3334744500c 100644 --- a/src/sage/matrix/matrix_modn_sparse.pyx +++ b/src/sage/matrix/matrix_modn_sparse.pyx @@ -163,7 +163,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the + - ``coerce`` -- if ``False``, assume without checking that the entries lie in the base ring """ ma = MatrixArgs_init(parent, entries) @@ -257,7 +257,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): cdef Matrix _matrix_times_matrix_(self, Matrix _right): """ - This code is implicitly called for multiplying self by another + This code is implicitly called for multiplying ``self`` by another sparse matrix. EXAMPLES:: @@ -332,7 +332,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): def _matrix_times_matrix_dense(self, Matrix _right): """ - Multiply self by the sparse matrix _right, and return the + Multiply ``self`` by the sparse matrix ``_right``, and return the result as a dense matrix. EXAMPLES:: @@ -403,7 +403,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): cpdef _echelon_in_place(self, str algorithm): """ - Replace self by its reduction to reduced row echelon form. + Replace ``self`` by its reduction to reduced row echelon form. ALGORITHM: We use Gauss elimination, in a slightly intelligent way, in that we clear each column using a row with the minimum number of @@ -504,9 +504,8 @@ cdef class Matrix_modn_sparse(Matrix_sparse): def density(self): """ - Return the density of self, i.e., the ratio of the number of - nonzero entries of self to the total size of self. - + Return the density of ``self``, i.e., the ratio of the number of + nonzero entries of ``self`` to the total size of ``self``. EXAMPLES:: @@ -540,7 +539,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): def transpose(self): """ - Return the transpose of self. + Return the transpose of ``self``. EXAMPLES:: @@ -577,14 +576,12 @@ cdef class Matrix_modn_sparse(Matrix_sparse): def matrix_from_rows(self, rows): """ - Return the matrix constructed from self using rows with indices in + Return the matrix constructed from ``self`` using rows with indices in the rows list. INPUT: - - - ``rows`` -- list or tuple of row indices - + - ``rows`` -- list or tuple of row indices EXAMPLES:: @@ -620,7 +617,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): def matrix_from_columns(self, cols): """ - Return the matrix constructed from self using columns with indices + Return the matrix constructed from ``self`` using columns with indices in the columns list. EXAMPLES:: @@ -722,8 +719,8 @@ cdef class Matrix_modn_sparse(Matrix_sparse): INPUT: - - ``algorithm`` -- either ``"linbox"`` (only available for - matrices over prime fields) or ``"generic"`` + - ``algorithm`` -- either ``'linbox'`` (only available for + matrices over prime fields) or ``'generic'`` EXAMPLES:: @@ -736,19 +733,19 @@ cdef class Matrix_modn_sparse(Matrix_sparse): 2 sage: A._clear_cache() - sage: A.rank(algorithm="generic") + sage: A.rank(algorithm='generic') 2 sage: A._clear_cache() - sage: A.rank(algorithm="hey") + sage: A.rank(algorithm='hey') Traceback (most recent call last): ... ValueError: no algorithm 'hey' TESTS:: - sage: matrix(GF(3), 0, sparse=True).rank(algorithm="generic") + sage: matrix(GF(3), 0, sparse=True).rank(algorithm='generic') 0 - sage: matrix(GF(3), 0, sparse=True).rank(algorithm="linbox") + sage: matrix(GF(3), 0, sparse=True).rank(algorithm='linbox') 0 sage: for _ in range(50): @@ -757,8 +754,8 @@ cdef class Matrix_modn_sparse(Matrix_sparse): ....: p = random_prime(10000) ....: M = MatrixSpace(GF(p), nrows, ncols, sparse=True) ....: m = M.random_element() - ....: rank_linbox = m.rank(algorithm="linbox") - ....: rank_generic = m.rank(algorithm="generic") + ....: rank_linbox = m.rank(algorithm='linbox') + ....: rank_generic = m.rank(algorithm='generic') ....: if rank_linbox != rank_generic: ....: print(m) ....: raise RuntimeError @@ -806,7 +803,7 @@ cdef class Matrix_modn_sparse(Matrix_sparse): INPUT: - - ``algorithm`` -- either ``"linbox"`` (default) or ``"generic"``. + - ``algorithm`` -- either ``'linbox'`` (default) or ``'generic'`` EXAMPLES:: @@ -814,11 +811,11 @@ cdef class Matrix_modn_sparse(Matrix_sparse): sage: B = identity_matrix(GF(3), 4, sparse=True) sage: (A + B).det() 2 - sage: (A + B).det(algorithm="linbox") + sage: (A + B).det(algorithm='linbox') 2 - sage: (A + B).det(algorithm="generic") + sage: (A + B).det(algorithm='generic') 2 - sage: (A + B).det(algorithm="hey") + sage: (A + B).det(algorithm='hey') Traceback (most recent call last): ... ValueError: no algorithm 'hey' @@ -830,9 +827,9 @@ cdef class Matrix_modn_sparse(Matrix_sparse): TESTS:: - sage: matrix(GF(3), 0, sparse=True).det(algorithm="generic") + sage: matrix(GF(3), 0, sparse=True).det(algorithm='generic') 1 - sage: matrix(GF(3), 0, sparse=True).det(algorithm="linbox") + sage: matrix(GF(3), 0, sparse=True).det(algorithm='linbox') 1 sage: for _ in range(100): @@ -840,8 +837,8 @@ cdef class Matrix_modn_sparse(Matrix_sparse): ....: p = random_prime(10000) ....: M = MatrixSpace(GF(p), dim, sparse=True) ....: m = M.random_element() - ....: det_linbox = m.det(algorithm="linbox") - ....: det_generic = m.det(algorithm="generic") + ....: det_linbox = m.det(algorithm='linbox') + ....: det_generic = m.det(algorithm='generic') ....: assert parent(det_linbox) == m.base_ring() ....: assert parent(det_generic) == m.base_ring() ....: if det_linbox != det_generic: diff --git a/src/sage/matrix/matrix_mpolynomial_dense.pyx b/src/sage/matrix/matrix_mpolynomial_dense.pyx index 8117911fa38..66462800f30 100644 --- a/src/sage/matrix/matrix_mpolynomial_dense.pyx +++ b/src/sage/matrix/matrix_mpolynomial_dense.pyx @@ -129,9 +129,7 @@ cdef class Matrix_mpolynomial_dense(Matrix_generic_dense): This returns a list, of the position of the first nonzero entry in each row of the echelon form. - OUTPUT: - - A list of Python ints. + OUTPUT: list of Python ints EXAMPLES:: @@ -158,7 +156,7 @@ cdef class Matrix_mpolynomial_dense(Matrix_generic_dense): def echelonize(self, algorithm='row_reduction', **kwds): """ - Transform self into a matrix in echelon form over the same base ring as + Transform ``self`` into a matrix in echelon form over the same base ring as ``self``. If Gauss-Bareiss algorithm is chosen, column swaps are recorded and can @@ -425,14 +423,14 @@ cdef class Matrix_mpolynomial_dense(Matrix_generic_dense): def swapped_columns(self): """ - Return which columns were swapped during the Gauss-Bareiss reduction + Return which columns were swapped during the Gauss-Bareiss reduction. OUTPUT: Return a tuple representing the column swaps during the last application of the Gauss-Bareiss algorithm (see :meth:`echelon_form` for details). - The tuple as length equal to the rank of self and the value at the + The tuple as length equal to the rank of ``self`` and the value at the `i`-th position indicates the source column which was put as the `i`-th column. @@ -459,11 +457,9 @@ cdef class Matrix_mpolynomial_dense(Matrix_generic_dense): INPUT: - - ``i`` -- an integer + - ``i`` -- integer - OUTPUT: - - An ideal on the base ring. + OUTPUT: an ideal on the base ring EXAMPLES:: @@ -485,7 +481,6 @@ cdef class Matrix_mpolynomial_dense(Matrix_generic_dense): Ideal (1) of Multivariate Polynomial Ring in x, y, z over Rational Field sage: [R.ideal(M.minors(i)) == M._fitting_ideal(4 - i) for i in range(5)] [True, True, True, True, True] - """ minor = singular_function("minor") R = self.base_ring() diff --git a/src/sage/matrix/matrix_numpy_dense.pyx b/src/sage/matrix/matrix_numpy_dense.pyx index 6a4027bd622..e6420bf29c8 100644 --- a/src/sage/matrix/matrix_numpy_dense.pyx +++ b/src/sage/matrix/matrix_numpy_dense.pyx @@ -183,9 +183,8 @@ cdef class Matrix_numpy_dense(Matrix_dense): INPUT: - - nrows -- (default self._nrows) number of rows in returned matrix - - ncols -- (default self._ncols) number of columns in returned matrix - + - ``nrows`` -- (default: ``self._nrows``) number of rows in returned matrix + - ``ncols`` -- (default: ``self._ncols``) number of columns in returned matrix """ cdef Matrix_numpy_dense m if nrows == -1 and ncols == -1: @@ -240,7 +239,7 @@ cdef class Matrix_numpy_dense(Matrix_dense): def transpose(self): """ - Return the transpose of this matrix, without changing self. + Return the transpose of this matrix, without changing ``self``. EXAMPLES:: @@ -267,7 +266,6 @@ cdef class Matrix_numpy_dense(Matrix_dense): [] sage: m.transpose().parent() Full MatrixSpace of 3 by 0 dense matrices over Real Double Field - """ if self._nrows == 0 or self._ncols == 0: return self.new_matrix(self._ncols, self._nrows) @@ -336,7 +334,7 @@ cdef class Matrix_numpy_dense(Matrix_dense): INPUT: - - ``tol`` -- the largest value of the absolute value of the + - ``tol`` -- the largest value of the absolute value of the difference between two matrix entries for which they will still be considered equal. @@ -374,7 +372,7 @@ cdef class Matrix_numpy_dense(Matrix_dense): INPUT: - - ``dtype`` -- The desired data-type for the array. If not given, + - ``dtype`` -- the desired data-type for the array. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence. diff --git a/src/sage/matrix/matrix_numpy_integer_dense.pyx b/src/sage/matrix/matrix_numpy_integer_dense.pyx index 8c449a86abf..d241ca57ac1 100644 --- a/src/sage/matrix/matrix_numpy_integer_dense.pyx +++ b/src/sage/matrix/matrix_numpy_integer_dense.pyx @@ -2,7 +2,6 @@ r""" Dense integer matrices using a NumPy backend - EXAMPLES:: sage: from sage.matrix.matrix_numpy_integer_dense import Matrix_numpy_integer_dense diff --git a/src/sage/matrix/matrix_polynomial_dense.pyx b/src/sage/matrix/matrix_polynomial_dense.pyx index 57f7bc5338c..6d01a42a126 100644 --- a/src/sage/matrix/matrix_polynomial_dense.pyx +++ b/src/sage/matrix/matrix_polynomial_dense.pyx @@ -110,11 +110,11 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``shifts`` -- list of integers, or ``None``. + - ``shifts`` -- list of integers, or ``None`` - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then shifts apply to the columns of the matrix and otherwise to its - rows (see the class description for more details). + rows (see the class description for more details) EXAMPLES:: @@ -140,7 +140,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): of all its entries. If the matrix is nonzero, this is a nonnegative integer; here, the degree of the zero matrix is -1. - OUTPUT: an integer. + OUTPUT: integer EXAMPLES:: @@ -188,13 +188,13 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then shifts apply to the columns of the matrix and otherwise to its - rows (see the class description for more details). + rows (see the class description for more details) - OUTPUT: an integer matrix. + OUTPUT: integer matrix EXAMPLES:: @@ -242,7 +242,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): Return the constant coefficient of this matrix seen as a polynomial with matrix coefficients; this is also this matrix evaluated at zero. - OUTPUT: a matrix over the base field. + OUTPUT: a matrix over the base field EXAMPLES:: @@ -267,7 +267,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): Return whether this polynomial matrix is constant, that is, all its entries are constant. - OUTPUT: a boolean. + OUTPUT: boolean EXAMPLES:: @@ -300,20 +300,20 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): entries; - if `d` is a list `(d_1,\ldots,d_m)` and ``row_wise`` is ``True``, this selects the coefficient of degree `d_i` for all entries of the - `i`th row for each `i`; + `i`-th row for each `i`; - if `d` is a list `(d_1,\ldots,d_n)` and ``row_wise`` is ``False``, this selects the coefficient of degree `d_i` for all entries of the - `j`th column for each `j`. + `j`-th column for each `j`. INPUT: - - ``d`` -- a list of integers, or an integer, + - ``d`` -- list of integers, or an integer, - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` (resp. ``False``) then `d` should be a list of length equal to the - row (resp. column) dimension of this matrix. + row (resp. column) dimension of this matrix - OUTPUT: a matrix over the base field. + OUTPUT: a matrix over the base field EXAMPLES:: @@ -392,10 +392,10 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): - if `d` is an integer, the truncation is at precision `d` for all entries; - if `d` is a list `(d_1,\ldots,d_m)` and ``row_wise`` is ``True``, all - entries of the `i`th row are truncated at precision `d_i` for each + entries of the `i`-th row are truncated at precision `d_i` for each `i`; - if `d` is a list `(d_1,\ldots,d_n)` and ``row_wise`` is ``False``, - all entries of the `j`th column are truncated at precision `d_j` for + all entries of the `j`-th column are truncated at precision `d_j` for each `j`. Here the convention for univariate polynomials is to take zero @@ -403,13 +403,13 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``d`` -- a list of integers, or an integer, + - ``d`` -- list of integers, or an integer, - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` (resp. ``False``) then `d` should be a list of length equal to the - row (resp. column) dimension of this matrix. + row (resp. column) dimension of this matrix - OUTPUT: a polynomial matrix. + OUTPUT: a polynomial matrix EXAMPLES:: @@ -484,9 +484,9 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): - if `d` is an integer, the shift is by `d` for all entries; - if `d` is a list `(d_1,\ldots,d_m)` and ``row_wise`` is ``True``, all - entries of the `i`th row are shifted by `d_i` for each `i`; + entries of the `i`-th row are shifted by `d_i` for each `i`; - if `d` is a list `(d_1,\ldots,d_n)` and ``row_wise`` is ``False``, - all entries of the `j`th column are shifted by `d_j` for each `j`. + all entries of the `j`-th column are shifted by `d_j` for each `j`. Shifting by `d` means multiplying by the variable to the power `d`; if `d` is negative then terms of negative degree after shifting are @@ -494,13 +494,13 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``d`` -- a list of integers, or an integer, + - ``d`` -- list of integers, or an integer, - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` (resp. ``False``) then `d` should be a list of length equal to the - row (resp. column) dimension of this matrix. + row (resp. column) dimension of this matrix - OUTPUT: a polynomial matrix. + OUTPUT: a polynomial matrix EXAMPLES:: @@ -590,25 +590,25 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): - if ``degree`` is not provided, then all entries are reversed with respect to the degree of the whole matrix; - if ``degree`` is a list `(d_1,\ldots,d_m)` and ``row_wise`` is - ``True``, all entries of the `i`th row are reversed with respect to + ``True``, all entries of the `i`-th row are reversed with respect to `d_i` for each `i`; - if ``degree`` is a list `(d_1,\ldots,d_n)` and ``row_wise`` is - ``False``, all entries of the `j`th column are reversed with respect + ``False``, all entries of the `j`-th column are reversed with respect to `d_j` for each `j`. INPUT: - ``degree`` -- (default: ``None``) a list of nonnegative - integers, or a nonnegative integer, + integers, or a nonnegative integer - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` (resp. ``False``) then ``degree`` should be a list of length equal to - the row (resp. column) dimension of this matrix. + the row (resp. column) dimension of this matrix - - ``entry_wise`` -- (default: ``False``) boolean, if ``True`` - then the input ``degree`` and ``row_wise`` are ignored. + - ``entry_wise`` -- boolean (default: ``False``); if ``True`` + then the input ``degree`` and ``row_wise`` are ignored - OUTPUT: a polynomial matrix. + OUTPUT: a polynomial matrix EXAMPLES:: @@ -680,7 +680,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): sage: M.reverse([2,3,-1]) Traceback (most recent call last): ... - ValueError: degree argument must be a non-negative integer, got -1 + ValueError: degree argument must be a nonnegative integer, got -1 .. SEEALSO:: @@ -729,12 +729,14 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): on that univariate polynomial, and 3) converts back to a matrix of polynomials. - Raises a ``ZeroDivisionError`` if the constant matrix of ``self`` is + Raises a :exc:`ZeroDivisionError` if the constant matrix of ``self`` is not invertible (i.e. has zero determinant); raises an - ``ArithmeticError`` if ``self`` is nonsquare; and raises a - ``ValueError`` if the precision ``d`` is not positive. + :exc:`ArithmeticError` if ``self`` is nonsquare; and raises a + :exc:`ValueError` if the precision ``d`` is not positive. - INPUT: a positive integer `d` . + INPUT: + + - ``d`` -- positive integer OUTPUT: the unique polynomial matrix `B` of degree less than `d` such that `AB` and `BA` are the identity matrix modulo `x^d`, where `A` is @@ -816,15 +818,15 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): matrix `X` such that `X A = B \bmod x^d`. If `B` is a vector then `X` is a vector, and if `B` is a matrix then `X` is a matrix. - Raises ``ValueError`` if ``d`` is not strictly positive, or if there is + Raises :exc:`ValueError` if ``d`` is not strictly positive, or if there is a dimension mismatch between `A` and `B`, or if there is no solution to the given matrix equation at the specified precision. INPUT: - - ``B`` -- a polynomial matrix or polynomial vector. + - ``B`` -- a polynomial matrix or polynomial vector - - ``d`` -- a positive integer. + - ``d`` -- positive integer OUTPUT: @@ -964,15 +966,15 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): matrix `X` such that `A X = B \bmod x^d`. If `B` is a vector then `X` is a vector, and if `B` is a matrix then `X` is a matrix. - Raises ``ValueError`` if ``d`` is not strictly positive, or if there is + Raises :exc:`ValueError` if ``d`` is not strictly positive, or if there is a dimension mismatch between `A` and `B`, or if there is no solution to the given matrix equation at the specified precision. INPUT: - - ``B`` -- a polynomial matrix or polynomial vector. + - ``B`` -- a polynomial matrix or polynomial vector - - ``d`` -- a positive integer. + - ``d`` -- positive integer OUTPUT: @@ -1085,9 +1087,9 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - OUTPUT: a list of integers. + OUTPUT: list of integers REFERENCES: @@ -1160,9 +1162,9 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - OUTPUT: a list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -1234,12 +1236,12 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - OUTPUT: a matrix over the base field. + OUTPUT: a matrix over the base field REFERENCES: @@ -1311,14 +1313,14 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - one considers the row-wise shifted Popov form. + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + one considers the row-wise shifted Popov form - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if one does not allow zero rows in row reduced forms (resp. - zero columns in column reduced forms). + zero columns in column reduced forms) - OUTPUT: a boolean. + OUTPUT: boolean EXAMPLES:: @@ -1376,16 +1378,16 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if one does not allow zero rows in row reduced forms (resp. - zero columns in column reduced forms). + zero columns in column reduced forms) - OUTPUT: a boolean value. + OUTPUT: boolean REFERENCES: @@ -1456,16 +1458,16 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``return_degree`` -- (default: ``False``) boolean, ``True`` - implies that the pivot degrees are returned. + - ``return_degree`` -- boolean (default: ``False``); ``True`` + implies that the pivot degrees are returned - OUTPUT: a list of integers if ``return_degree=False``; a pair of lists - of integers otherwise. + OUTPUT: list of integers if ``return_degree=False``; a pair of lists + of integers otherwise REFERENCES: @@ -1584,19 +1586,19 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``ordered`` -- (default: ``False``) boolean, ``True`` if - checking for an ordered weak Popov form. + - ``ordered`` -- boolean (default: ``False``); ``True`` if + checking for an ordered weak Popov form - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if one does not allow zero rows (resp. zero columns) in - (ordered) weak Popov forms. + (ordered) weak Popov forms - OUTPUT: a boolean. + OUTPUT: boolean REFERENCES: @@ -1723,20 +1725,20 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - ``up_to_permutation`` -- (option, default: ``False``) boolean, ``True`` if testing Popov form up to row permutation (if working row-wise). - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if one does not allow zero rows (resp. zero columns) in - Popov forms. + Popov forms - OUTPUT: a boolean. + OUTPUT: boolean REFERENCES: @@ -1868,18 +1870,18 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``lower_echelon`` -- (default: ``False``) boolean, + - ``lower_echelon`` -- boolean (default: ``False``); ``False`` if working with upper triangular Hermite forms, ``True`` if working with lower triangular Hermite forms. - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if one does not allow zero rows (resp. zero columns) in - Hermite forms. + Hermite forms - OUTPUT: a boolean. + OUTPUT: boolean EXAMPLES:: @@ -1968,28 +1970,28 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``transformation`` -- (default: ``False``). If this - is ``True``, the transformation matrix `U` will be returned as well. + - ``transformation`` -- (default: ``False``) if this + is ``True``, the transformation matrix `U` will be returned as well - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``ordered`` -- (default: ``False``) boolean, ``True`` if - seeking an ordered weak Popov form. + - ``ordered`` -- boolean (default: ``False``); ``True`` if + seeking an ordered weak Popov form - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if zero rows (resp. zero columns) should be discarded from - the (ordered) weak Popov forms. + the (ordered) weak Popov forms OUTPUT: - - A polynomial matrix which is a weak Popov form of ``self`` if - ``transformation`` is ``False``; otherwise two polynomial matrices - which are a weak Popov form of ``self`` and the corresponding - unimodular transformation. + A polynomial matrix which is a weak Popov form of ``self`` if + ``transformation`` is ``False``; otherwise two polynomial matrices + which are a weak Popov form of ``self`` and the corresponding + unimodular transformation. ALGORITHM: @@ -2255,18 +2257,18 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``transformation`` -- (default: ``False``). If this - is ``True``, the transformation matrix `U` will be returned as well. + - ``transformation`` -- (default: ``False``) if this + is ``True``, the transformation matrix `U` will be returned as well - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if zero rows (resp. zero columns) should be discarded from - the Popov forms. + the Popov forms OUTPUT: @@ -2453,20 +2455,20 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``transformation`` -- (default: ``False``). If this + - ``transformation`` -- (default: ``False``) if this is ``True``, the transformation matrix `U` will be returned as well: this is a unimodular matrix over `\Bold{K}[x]` such that ``self`` equals `UR`, where `R` is the output matrix. - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``include_zero_vectors`` -- (default: ``True``) boolean, + - ``include_zero_vectors`` -- boolean (default: ``True``); ``False`` if one does not allow zero rows in row reduced forms (resp. - zero columns in column reduced forms). + zero columns in column reduced forms) OUTPUT: @@ -2496,8 +2498,8 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): sage: R2.is_reduced() False - If the matrix is an `n \times 1` matrix with at least one non-zero entry, - `R` has a single non-zero entry and that entry is a scalar multiple of + If the matrix is an `n \times 1` matrix with at least one nonzero entry, + `R` has a single nonzero entry and that entry is a scalar multiple of the greatest-common-divisor of the entries of the matrix:: sage: A = matrix([[x*(x-1)*(x+1)], [x*(x-2)*(x+2)], [x]]) @@ -2574,10 +2576,10 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``include_zero_rows`` -- boolean (default: ``True``); if ``False``, - the zero rows in the output matrix are deleted. + the zero rows in the output matrix are deleted - ``transformation`` -- boolean (default: ``False``); if ``True``, - return the transformation matrix. + return the transformation matrix OUTPUT: @@ -2737,7 +2739,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): remainder, or it does satisfy this degree constraint, and then this `R` can be returned as a remainder along with the quotient `Q`. - A ``ValueError`` is raised if the dimensions of ``self`` and `B` are + A :exc:`ValueError` is raised if the dimensions of ``self`` and `B` are not conformal, or if there exists no quotient and remainder. EXAMPLES: @@ -2937,7 +2939,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): """ # Step 0: find parameter d (delta in above reference) cdegA = self.column_degrees() # zero columns of A --> entries -1 in cdegA - cdeg = B.column_degrees() # all non-negative since column reduced + cdeg = B.column_degrees() # all nonnegative since column reduced d = max([cdegA[i]-cdeg[i]+1 for i in range(B.nrows())]) if d<=0: # A already reduced modulo B, quotient is zero return (self.parent().zero().__copy__(), self) @@ -2972,7 +2974,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): implies the existence of a quotient and remainder as described above, and such a quotient and remainder is returned by the method. Or this matrix equation has no solution and this method fails: this raises - ``ValueError``; however this is not a proof that there is no valid + :exc:`ValueError`; however this is not a proof that there is no valid division with remainder (see the last example below). EXAMPLES:: @@ -3122,21 +3124,21 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): since `P` and `B` have the same row space (or column space, if ``row_wise`` is ``False``). - A ``ValueError`` is raised if the dimensions of the shifts and/or of + A :exc:`ValueError` is raised if the dimensions of the shifts and/or of the matrices are not conformal. INPUT: - - ``B`` -- polynomial matrix. + - ``B`` -- polynomial matrix - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, ``True`` if - working row-wise (see the class description). + - ``row_wise`` -- boolean (default: ``True``); ``True`` if + working row-wise (see the class description) - - ``return_quotient`` -- (default: ``False``). If this - is ``True``, the quotient will be returned as well. + - ``return_quotient`` -- (default: ``False``) if this + is ``True``, the quotient will be returned as well OUTPUT: a polynomial matrix if ``return_quotient=False``, two polynomial matrices otherwise. @@ -3274,22 +3276,22 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``pmat`` -- a polynomial matrix. + - ``pmat`` -- a polynomial matrix - - ``order`` -- a list of positive integers, or a positive integer. + - ``order`` -- list of positive integers, or a positive integer - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then the basis considered row-wise and operates on the left of - ``pmat``; otherwise it is column-wise and operates on the right of + ``pmat``. Otherwise it is column-wise and operates on the right of ``pmat``. - - ``normal_form`` -- (default: ``False``) boolean, if - ``True`` then checks for a basis in ``shifts``-Popov form. + - ``normal_form`` -- boolean (default: ``False``); if + ``True`` then checks for a basis in ``shifts``-Popov form - OUTPUT: a boolean. + OUTPUT: boolean ALGORITHM: @@ -3490,20 +3492,20 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``order`` -- a list of positive integers, or a positive integer. + - ``order`` -- list of positive integers, or a positive integer - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then the output basis is considered row-wise and operates on the left - of ``self``; otherwise it is column-wise and operates on the right + of ``self``. Otherwise it is column-wise and operates on the right of ``self``. - - ``normal_form`` -- (default: ``False``) boolean, if - ``True`` then the output basis is in ``shifts``-Popov form. + - ``normal_form`` -- boolean (default: ``False``); if + ``True`` then the output basis is in ``shifts``-Popov form - OUTPUT: a polynomial matrix. + OUTPUT: a polynomial matrix ALGORITHM: @@ -3649,9 +3651,9 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``order`` -- a list of positive integers. + - ``order`` -- list of positive integers - - ``shifts`` -- a list of integers. + - ``shifts`` -- list of integers OUTPUT: @@ -3793,20 +3795,20 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``pmat`` -- a polynomial matrix. + - ``pmat`` -- a polynomial matrix - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then the basis is considered row-wise and operates on the left of - ``pmat``; otherwise it is column-wise and operates on the right of + ``pmat``. Otherwise it is column-wise and operates on the right of ``pmat``. - - ``normal_form`` -- (default: ``False``) boolean, if - ``True`` then checks for a basis in ``shifts``-Popov form. + - ``normal_form`` -- boolean (default: ``False``); if + ``True`` then checks for a basis in ``shifts``-Popov form - OUTPUT: a boolean. + OUTPUT: boolean ALGORITHM: @@ -3923,17 +3925,17 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - ``shifts`` -- (default: ``None``) list of integers; - ``None`` is interpreted as ``shifts=[0,...,0]``. + ``None`` is interpreted as ``shifts=[0,...,0]`` - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then the output basis considered row-wise and operates on the left - of ``self``; otherwise it is column-wise and operates on the right + of ``self``. Otherwise it is column-wise and operates on the right of ``self``. - - ``normal_form`` -- (default: ``False``) boolean, if - ``True`` then the output basis is in ``shifts``-Popov form. + - ``normal_form`` -- boolean (default: ``False``); if + ``True`` then the output basis is in ``shifts``-Popov form - OUTPUT: a polynomial matrix. + OUTPUT: a polynomial matrix ALGORITHM: uses minimal approximant basis computation at a sufficiently large order so that the approximant basis contains @@ -4248,7 +4250,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): return completion - def basis_completion(self, row_wise=True, algorithm="approximant"): + def basis_completion(self, row_wise=True, algorithm='approximant'): r""" Return a Smith form-preserving nonsingular completion of a basis of this matrix: row-wise completing a row basis if ``row_wise`` is True; @@ -4280,24 +4282,24 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` then - compute a row-wise completion, else compute a column-wise completion. + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then + compute a row-wise completion, else compute a column-wise completion - - ``algorithm`` -- (default: ``"approximant"``) selects the + - ``algorithm`` -- (default: ``'approximant'``) selects the approach for computing the completion; currently supported: - ``"approximant"`` and ``"smith"``. + ``'approximant'`` and ``'smith'`` - OUTPUT: a matrix over the same base ring as the input matrix, which forms a - completion as defined above. + OUTPUT: a matrix over the same base ring as the input matrix, which + forms a completion as defined above ALGORITHM: - - ``approximant``: the approximant-based algorithm follows the ideas in + - ``'approximant'`` -- the approximant-based algorithm follows the ideas in [ZL2014]_ , based on polynomial reversals combined with the computation of a minimal kernel basis and a minimal approximant basis. - - ``smith``: the Smith form-based algorithm computes the Smith form of + - ``'smith'`` -- the Smith form-based algorithm computes the Smith form of this matrix along with corresponding unimodular transformations, from which a completion is readily obtained. @@ -4369,7 +4371,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): sage: mat = matrix([[x*(x-1)*(x-2), (x-2)*(x-3)*(x-4), (x-4)*(x-5)*(x-6)]]) sage: mat [ x^3 - 3*x^2 + 2*x x^3 - 9*x^2 + 26*x - 24 x^3 - 15*x^2 + 74*x - 120] - sage: rcomp = mat.basis_completion(algorithm="smith"); rcomp + sage: rcomp = mat.basis_completion(algorithm='smith'); rcomp [ -1/12*x - 1/12 -1/12*x + 5/12 0] [ 1/12 1/12 1/24*x^2 - 13/24*x + 2] sage: mat.stack(rcomp).determinant() @@ -4382,7 +4384,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): [1 0] [0 x] [0 0] - sage: ccomp = mat.basis_completion(row_wise=False, algorithm="smith") + sage: ccomp = mat.basis_completion(row_wise=False, algorithm='smith') sage: ccomp [1/2*x - 1/2] [ 1/2*x - 1] @@ -4395,7 +4397,7 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): sage: field. = NumberField(x**2 - 2) sage: ring. = field[] sage: mat = matrix([[3*a*y - 1, (-8*a - 1)*y - 2*a + 1]]) - sage: rcomp = mat.basis_completion(algorithm="smith"); rcomp + sage: rcomp = mat.basis_completion(algorithm='smith'); rcomp [ 39/119*a - 30/119 -99/119*a + 67/119] sage: mat.stack(rcomp).determinant() 1 @@ -4408,28 +4410,28 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): [] sage: matrix(ring, 0, 0).basis_completion(row_wise=False) [] - sage: matrix(ring, 0, 0).basis_completion(algorithm="smith") + sage: matrix(ring, 0, 0).basis_completion(algorithm='smith') [] - sage: matrix(ring, 0, 0).basis_completion(row_wise=False,algorithm="smith") + sage: matrix(ring, 0, 0).basis_completion(row_wise=False,algorithm='smith') [] sage: matrix(ring, 0, 2).basis_completion() [1 0] [0 1] sage: matrix(ring, 0, 2).basis_completion(row_wise=False) [] - sage: matrix(ring, 0, 2).basis_completion(algorithm="smith") + sage: matrix(ring, 0, 2).basis_completion(algorithm='smith') [1 0] [0 1] - sage: matrix(ring, 0, 2).basis_completion(row_wise=False,algorithm="smith") + sage: matrix(ring, 0, 2).basis_completion(row_wise=False,algorithm='smith') [] sage: matrix(ring, 2, 0).basis_completion() [] sage: matrix(ring, 2, 0).basis_completion(row_wise=False) [1 0] [0 1] - sage: matrix(ring, 2, 0).basis_completion(algorithm="smith") + sage: matrix(ring, 2, 0).basis_completion(algorithm='smith') [] - sage: matrix(ring, 2, 0).basis_completion(row_wise=False,algorithm="smith") + sage: matrix(ring, 2, 0).basis_completion(row_wise=False,algorithm='smith') [1 0] [0 1] """ @@ -4482,11 +4484,10 @@ cdef class Matrix_polynomial_dense(Matrix_generic_dense): INPUT: - - ``row_wise`` -- (default: ``True``) boolean, if ``True`` then - check for row-wise completion, else check for column-wise completion. + - ``row_wise`` -- boolean (default: ``True``); if ``True`` then + check for row-wise completion, else check for column-wise completion - OUTPUT: a boolean indicating whether this matrix is a completion of - ``mat``. + OUTPUT: boolean indicating whether this matrix is a completion of ``mat`` EXAMPLES: diff --git a/src/sage/matrix/matrix_rational_dense.pyx b/src/sage/matrix/matrix_rational_dense.pyx index 60ef434904a..ee22058d4fe 100644 --- a/src/sage/matrix/matrix_rational_dense.pyx +++ b/src/sage/matrix/matrix_rational_dense.pyx @@ -168,8 +168,8 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the - entries are of type :class:`Rational`. + - ``coerce`` -- if ``False``, assume without checking that the + entries are of type :class:`Rational` TESTS:: @@ -193,7 +193,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def matrix_from_columns(self, columns): """ - Return the matrix constructed from self using columns with indices + Return the matrix constructed from ``self`` using columns with indices in the columns list. EXAMPLES:: @@ -227,7 +227,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def add_to_entry(self, Py_ssize_t i, Py_ssize_t j, elt): r""" - Add ``elt`` to the entry at position ``(i,j)`` + Add ``elt`` to the entry at position ``(i,j)``. EXAMPLES:: @@ -308,7 +308,7 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: - - ``base`` -- an optional integer (default is ``10``) + - ``base`` -- integer (default: `10`) EXAMPLES:: @@ -510,7 +510,7 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``v`` -- a free module element - OUTPUT: The vector times matrix product v\*A + OUTPUT: the vector times matrix product v\*A EXAMPLES:: @@ -646,11 +646,10 @@ cdef class Matrix_rational_dense(Matrix_dense): def inverse(self, algorithm=None, check_invertible=True): """ - Return the inverse of this matrix + Return the inverse of this matrix. INPUT: - - ``algorithm`` -- an optional specification of an algorithm. It can be one of - ``None``: (default) uses flint @@ -661,8 +660,8 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``'iml'``: uses IML library - - ``check_invertible`` -- only used when ``algorithm=iml``. Whether to - check that matrix is invertible + - ``check_invertible`` -- only used when ``algorithm=iml``; whether to + check that matrix is invertible EXAMPLES:: @@ -673,40 +672,40 @@ cdef class Matrix_rational_dense(Matrix_dense): [1/2 1/2 -2] sage: a = matrix(QQ, 2, [1, 5, 17, 3]) - sage: a.inverse(algorithm="flint") + sage: a.inverse(algorithm='flint') [-3/82 5/82] [17/82 -1/82] - sage: a.inverse(algorithm="flint") * a + sage: a.inverse(algorithm='flint') * a [1 0] [0 1] sage: a = matrix(QQ, 2, [-1, 5, 12, -3]) - sage: a.inverse(algorithm="iml") + sage: a.inverse(algorithm='iml') [1/19 5/57] [4/19 1/57] - sage: a.inverse(algorithm="iml") * a + sage: a.inverse(algorithm='iml') * a [1 0] [0 1] sage: a = matrix(QQ, 4, primes_first_n(16)) - sage: a.inverse(algorithm="pari") + sage: a.inverse(algorithm='pari') [ 3/11 -12/55 -1/5 2/11] [ -5/11 -2/55 3/10 -3/22] [ -13/22 307/440 -1/10 -9/88] [ 15/22 -37/88 0 7/88] - On singular matrices this method raises a ``ZeroDivisionError``:: + On singular matrices this method raises a :exc:`ZeroDivisionError`:: sage: a = matrix(QQ, 2) - sage: a.inverse(algorithm="flint") + sage: a.inverse(algorithm='flint') Traceback (most recent call last): ... ZeroDivisionError: input matrix must be nonsingular - sage: a.inverse(algorithm="iml") + sage: a.inverse(algorithm='iml') Traceback (most recent call last): ... ZeroDivisionError: input matrix must be nonsingular - sage: a.inverse(algorithm="pari") + sage: a.inverse(algorithm='pari') Traceback (most recent call last): ... ZeroDivisionError: input matrix must be nonsingular @@ -771,8 +770,8 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``'generic'``: calls the generic Sage implementation - - ``proof`` -- bool or None; if None use - proof.linear_algebra(); only relevant for the padic algorithm. + - ``proof`` -- boolean or ``None``; if ``None`` use + proof.linear_algebra(); only relevant for the padic algorithm .. NOTE:: @@ -788,18 +787,18 @@ cdef class Matrix_rational_dense(Matrix_dense): x^3 - 17/5*x^2 - 122/15*x + 34/15 sage: m = matrix(QQ, 3, [(1/i)**j for i in range(2,5) for j in range(3)]) - sage: m.determinant(algorithm="flint") + sage: m.determinant(algorithm='flint') -1/288 sage: m = matrix(QQ, 4, [(-1)**n/n for n in range(1,17)]) - sage: m.determinant(algorithm="pari") + sage: m.determinant(algorithm='pari') 2/70945875 sage: m = matrix(QQ, 5, [1/(i+j+1) for i in range(5) for j in range(5)]) - sage: m.determinant(algorithm="integer") + sage: m.determinant(algorithm='integer') 1/266716800000 - On non-square matrices, the method raises a ``ValueError``:: + On non-square matrices, the method raises a :exc:`ValueError`:: sage: matrix(QQ, 2, 3).determinant(algorithm='flint') Traceback (most recent call last): @@ -857,7 +856,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def _det_flint(self): r""" - Return the determinant (computed using flint) + Return the determinant (computed using flint). EXAMPLES:: @@ -918,7 +917,7 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``self`` -- a matrix - OUTPUT: D\*self, D + OUTPUT: ``D*self, D`` The product is a matrix over `\ZZ`. @@ -976,10 +975,10 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: - - ``var`` -- (optional) name of the variable as a string + - ``var`` -- (optional) name of the variable as a string - - ``algorithm`` -- an optional specification of an algorithm. It can be - one of: + - ``algorithm`` -- an optional specification of an algorithm. It can be + one of: - ``None``: (default) will use flint for small dimensions and linbox otherwise @@ -990,7 +989,7 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``'generic'``: uses Sage generic implementation - OUTPUT: a polynomial over the rational numbers. + OUTPUT: a polynomial over the rational numbers EXAMPLES:: @@ -1052,15 +1051,14 @@ cdef class Matrix_rational_dense(Matrix_dense): def minpoly(self, var='x', algorithm=None): """ - Return the minimal polynomial of this matrix + Return the minimal polynomial of this matrix. INPUT: + - ``var`` -- (optional) the variable name as a string (default: ``'x'``) - - ``var`` -- (optional) the variable name as a string (default is 'x') - - - ``algorithm`` -- an optional specification of an algorithm. It can - be one of + - ``algorithm`` -- an optional specification of an algorithm. It can + be one of - ``None``: (default) will use linbox @@ -1183,11 +1181,11 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: - - ``self`` -- matrix over QQ + - ``self`` -- matrix over QQ - - ``right`` -- matrix over QQ + - ``right`` -- matrix over QQ - - ``algorithm`` + - ``algorithm`` - 'default': use whatever is the default for A\*B when A, B are over ZZ. @@ -1247,7 +1245,7 @@ cdef class Matrix_rational_dense(Matrix_dense): absolute values of all numerators and denominators of entries in this matrix. - OUTPUT: an Integer + OUTPUT: integer EXAMPLES:: @@ -1288,7 +1286,7 @@ cdef class Matrix_rational_dense(Matrix_dense): """ Return the adjugate of this matrix. - Assumes self is a square matrix (checked in adjugate). + Assumes ``self`` is a square matrix (checked in adjugate). EXAMPLES:: @@ -1343,7 +1341,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def _right_kernel_matrix(self, **kwds): r""" - Returns a pair that includes a matrix of basis vectors + Return a pair that includes a matrix of basis vectors for the right kernel of ``self``. INPUT: @@ -1419,7 +1417,7 @@ cdef class Matrix_rational_dense(Matrix_dense): # ############################################### def change_ring(self, R): """ - Create the matrix over R with entries the entries of self coerced + Create the matrix over R with entries the entries of ``self`` coerced into R. EXAMPLES:: @@ -1499,13 +1497,13 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: - - ``algorithm`` -- an optional specification of an algorithm. One of + - ``algorithm`` -- an optional specification of an algorithm. One of - ``None``: (default) uses flint for small dimension and multimodular otherwise - ``'flint'``: use the flint library, - - ``'padic'``: an algorithm based on the IML p-adic solver, + - ``'padic'``: an algorithm based on the IML `p`-adic solver, - ``'multimodular'``: uses a multimodular algorithm the uses linbox modulo many primes (likely to be faster when coefficients @@ -1513,13 +1511,13 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``'classical'``: just clear each column using Gauss elimination. - - ``height_guess``, ``**kwds`` -- all passed to the - multimodular algorithm; ignored by other algorithms. + - ``height_guess``, ``**kwds`` -- all passed to the + multimodular algorithm; ignored by other algorithms - - ``proof`` -- bool or None (default: None, see - proof.linear_algebra or sage.structure.proof). Passed to the - multimodular algorithm. Note that the Sage global default is - ``proof=True``. + - ``proof`` -- boolean or ``None`` (default: None, see + proof.linear_algebra or sage.structure.proof). Passed to the + multimodular algorithm. Note that the Sage global default is + ``proof=True``. EXAMPLES:: @@ -1702,7 +1700,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def _echelonize_padic(self): """ - Echelonize self using a p-adic nullspace algorithm. + Echelonize ``self`` using a `p`-adic nullspace algorithm. EXAMPLES:: @@ -1777,12 +1775,11 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: + - ``height_guess`` -- integer or ``None`` - - ``height_guess`` -- integer or None - - - ``proof`` -- boolean (default: None, see - proof.linear_algebra or sage.structure.proof) Note that the Sage - global default is proof=True. + - ``proof`` -- boolean (default: ``None``, see + proof.linear_algebra or sage.structure.proof); Note that the Sage + global default is ``proof=True`` EXAMPLES:: @@ -1843,7 +1840,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def decomposition(self, is_diagonalizable=False, dual=False, algorithm=None, height_guess=None, proof=None): """ - Returns the decomposition of the free module on which this matrix A + Return the decomposition of the free module on which this matrix A acts from the right (i.e., the action is x goes to x A), along with whether this matrix acts irreducibly on each factor. The factors are guaranteed to be sorted in the same way as the corresponding @@ -1865,13 +1862,12 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: + - ``is_diagonalizable`` -- ignored - - ``is_diagonalizable`` -- ignored + - ``dual`` -- whether to also return decompositions for + the dual - - ``dual`` -- whether to also return decompositions for - the dual - - - ``algorithm`` -- an optional specification of an algorithm + - ``algorithm`` -- an optional specification of an algorithm - ``None`` -- (default) use default algorithm for computing Echelon forms @@ -1879,13 +1875,13 @@ cdef class Matrix_rational_dense(Matrix_dense): - 'multimodular': much better if the answers factors have small height - - ``height_guess`` -- positive integer; only used by - the multimodular algorithm + - ``height_guess`` -- positive integer; only used by + the multimodular algorithm - - ``proof`` -- bool or None (default: None, see - proof.linear_algebra or sage.structure.proof); only used by the - multimodular algorithm. Note that the Sage global default is - proof=True. + - ``proof`` -- boolean or ``None`` (default: ``None``, see + proof.linear_algebra or sage.structure.proof); only used by the + multimodular algorithm. Note that the Sage global default is + proof=True. .. NOTE:: @@ -1913,7 +1909,6 @@ cdef class Matrix_rational_dense(Matrix_dense): [ 1 0 -1] [ 0 1 2], True) ] - """ X = self._decomposition_rational(is_diagonalizable=is_diagonalizable, echelon_algorithm=algorithm, @@ -1930,7 +1925,7 @@ cdef class Matrix_rational_dense(Matrix_dense): kernel_algorithm='default', **kwds): """ - Returns the decomposition of the free module on which this matrix A + Return the decomposition of the free module on which this matrix A acts from the right (i.e., the action is x goes to x A), along with whether this matrix acts irreducibly on each factor. The factors are guaranteed to be sorted in the same way as the corresponding @@ -1938,17 +1933,16 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: + - ``self`` -- a square matrix over the rational + numbers - - ``self`` -- a square matrix over the rational - numbers - - - ``echelon_algorithm`` -- an optional algorithm to be passed to the - method ``echelon_form`` + - ``echelon_algorithm`` -- an optional algorithm to be passed to the + method ``echelon_form`` - - ``'multimodular'`` -- use this if the answers have - small height + - ``'multimodular'`` -- use this if the answers have + small height - - ``**kwds`` -- passed on to echelon function. + - ``**kwds`` -- passed on to echelon function .. NOTE:: @@ -1959,14 +1953,12 @@ cdef class Matrix_rational_dense(Matrix_dense): will be very small, use algorithm='multimodular', height_guess=bound on height, proof=False - OUTPUT: - - - ``Sequence`` -- list of tuples (V,t), where V is a - vector spaces and t is True if and only if the charpoly of self on - V is irreducible. The tuples are in order corresponding to the - elements of the sorted list self.charpoly().factor(). + - ``Sequence`` -- list of tuples (V,t), where V is a + vector spaces and t is ``True`` if and only if the charpoly of ``self`` on + V is irreducible. The tuples are in order corresponding to the + elements of the sorted list self.charpoly().factor(). """ cdef Py_ssize_t k @@ -2209,19 +2201,17 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: - - ``density`` -- number between 0 and 1 (default: 1) + - ``density`` -- number between 0 and 1 (default: 1) - - ``num_bound`` -- numerator bound (default: 2) + - ``num_bound`` -- numerator bound (default: 2) - - ``den_bound`` -- denominator bound (default: 2) + - ``den_bound`` -- denominator bound (default: 2) - - ``distribution`` -- ``None`` or '1/n' (default: ``None``); if '1/n' - then ``num_bound``, ``den_bound`` are ignored and numbers are chosen - using the GMP function ``mpq_randomize_entry_recip_uniform`` - - OUTPUT: + - ``distribution`` -- ``None`` or '1/n' (default: ``None``); if '1/n' + then ``num_bound``, ``den_bound`` are ignored and numbers are chosen + using the GMP function ``mpq_randomize_entry_recip_uniform`` - - None, the matrix is modified in-space + OUTPUT: none; the matrix is modified in-space EXAMPLES: @@ -2474,13 +2464,13 @@ cdef class Matrix_rational_dense(Matrix_dense): - ``algorithm`` -- an optional specification of an algorithm. One of - - ``None``: (default) will use flint + - ``None`` -- (default) will use flint - - ``'flint'``: uses the flint library + - ``'flint'`` -- uses the flint library - - ``'pari'``: uses the PARI library + - ``'pari'`` -- uses the PARI library - - ``'integer'``: eliminate denominators and calls the rank function + - ``'integer'`` -- eliminate denominators and calls the rank function on the corresponding integer matrix EXAMPLES:: @@ -2523,7 +2513,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def transpose(self): """ - Returns the transpose of self, without changing self. + Return the transpose of ``self``, without changing ``self``. EXAMPLES: @@ -2579,7 +2569,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def antitranspose(self): """ - Returns the antitranspose of self, without changing self. + Return the antitranspose of ``self``, without changing ``self``. EXAMPLES:: @@ -2660,10 +2650,9 @@ cdef class Matrix_rational_dense(Matrix_dense): Py_ssize_t r, cols, cols_index=None): """ - Set row i of self to -(row r of A), but where we only take the + Set row i of ``self`` to -(row r of A), but where we only take the given column positions in that row of A. We do not zero out the - other entries of self's row i either. - + other entries of ``self``'s row i either. .. NOTE:: @@ -2671,15 +2660,13 @@ cdef class Matrix_rational_dense(Matrix_dense): INPUT: + - ``i`` -- integer, index into the rows of self - - ``i`` -- integer, index into the rows of self - - - ``A`` -- a matrix - - - ``r`` -- integer, index into rows of A + - ``A`` -- a matrix - - ``cols`` -- a *sorted* list of integers. + - ``r`` -- integer, index into rows of A + - ``cols`` -- a *sorted* list of integers EXAMPLES:: @@ -2712,8 +2699,8 @@ cdef class Matrix_rational_dense(Matrix_dense): def _add_col_j_of_A_to_col_i_of_self(self, Py_ssize_t i, Matrix_rational_dense A, Py_ssize_t j): """ - Unsafe technical function that very quickly adds the j-th column of - A to the i-th column of self. + Unsafe technical function that very quickly adds the `j`-th column of + A to the `i`-th column of ``self``. Does not check mutability. """ @@ -2779,7 +2766,7 @@ cdef class Matrix_rational_dense(Matrix_dense): def _multiply_pari(self, Matrix_rational_dense right): """ - Return the product of self and right, computed using PARI. + Return the product of ``self`` and ``right``, computed using PARI. EXAMPLES:: @@ -2837,13 +2824,13 @@ cdef class Matrix_rational_dense(Matrix_dense): def row(self, Py_ssize_t i, from_list=False): """ - Return the i-th row of this matrix as a dense vector. + Return the `i`-th row of this matrix as a dense vector. INPUT: - - ``i`` -- integer + - ``i`` -- integer - - ``from_list`` -- ignored + - ``from_list`` -- ignored EXAMPLES:: @@ -2881,13 +2868,13 @@ cdef class Matrix_rational_dense(Matrix_dense): def column(self, Py_ssize_t i, from_list=False): """ - Return the i-th column of this matrix as a dense vector. + Return the `i`-th column of this matrix as a dense vector. INPUT: - - ``i`` -- integer + - ``i`` -- integer - - ``from_list`` -- ignored + - ``from_list`` -- ignored EXAMPLES:: diff --git a/src/sage/matrix/matrix_rational_sparse.pyx b/src/sage/matrix/matrix_rational_sparse.pyx index 6cf8d4fa0d0..8e9898642c3 100644 --- a/src/sage/matrix/matrix_rational_sparse.pyx +++ b/src/sage/matrix/matrix_rational_sparse.pyx @@ -76,14 +76,14 @@ cdef class Matrix_rational_sparse(Matrix_sparse): INPUT: - - ``parent`` -- a matrix space over ``QQ`` + - ``parent`` -- a matrix space over `\QQ` - ``entries`` -- see :func:`matrix` - ``copy`` -- ignored (for backwards compatibility) - - ``coerce`` -- if False, assume without checking that the - entries are of type :class:`Rational`. + - ``coerce`` -- if ``False``, assume without checking that the + entries are of type :class:`Rational` """ ma = MatrixArgs_init(parent, entries) cdef Rational z @@ -356,9 +356,7 @@ cdef class Matrix_rational_sparse(Matrix_sparse): multiple of all numerators and denominators of elements of this matrix. - OUTPUT: - - -- Integer + OUTPUT: integer EXAMPLES:: @@ -409,9 +407,7 @@ cdef class Matrix_rational_sparse(Matrix_sparse): """ Return the denominator of this matrix. - OUTPUT: - - - Sage Integer + OUTPUT: Sage Integer EXAMPLES:: @@ -427,13 +423,7 @@ cdef class Matrix_rational_sparse(Matrix_sparse): def _clear_denom(self): """ - INPUT: - - self -- a matrix - - OUTPUT: - - D*self, D + OUTPUT: ``d*self, D`` The product D*self is a matrix over ZZ @@ -483,8 +473,8 @@ cdef class Matrix_rational_sparse(Matrix_sparse): INPUT: - ``height_guess``, ``proof``, ``**kwds`` -- all passed to the multimodular - algorithm; ignored by the p-adic algorithm. + - ``height_guess``, ``proof``, ``**kwds`` -- all passed to the multimodular + algorithm; ignored by the `p`-adic algorithm OUTPUT: @@ -530,12 +520,10 @@ cdef class Matrix_rational_sparse(Matrix_sparse): """ INPUT: - ``height_guess``, ``proof``, ``**kwds`` -- all passed to the multimodular - algorithm; ignored by the p-adic algorithm. - - OUTPUT: + - ``height_guess``, ``proof``, ``**kwds`` -- all passed to the multimodular + algorithm; ignored by the `p`-adic algorithm - self is no in reduced row echelon form. + OUTPUT: ``self`` is no in reduced row echelon form EXAMPLES:: @@ -574,13 +562,13 @@ cdef class Matrix_rational_sparse(Matrix_sparse): def _echelon_form_multimodular(self, height_guess=None, proof=True): """ - Returns reduced row-echelon form using a multi-modular - algorithm. Does not change self. + Return reduced row-echelon form using a multi-modular + algorithm. Does not change ``self``. INPUT: - - height_guess -- integer or None - - proof -- boolean (default: ``True``) + - ``height_guess`` -- integer or ``None`` + - ``proof`` -- boolean (default: ``True``) """ from sage.matrix.misc import matrix_rational_echelon_form_multimodular cdef Matrix E @@ -661,17 +649,17 @@ cdef class Matrix_rational_sparse(Matrix_sparse): Py_ssize_t r, cols, cols_index=None): """ - Set row i of self to -(row r of A), but where we only take the + Set row i of ``self`` to -(row r of A), but where we only take the given column positions in that row of A. Note that we *DO* - zero out the other entries of self's row i. + zero out the other entries of ``self``'s row i. INPUT: - - i -- integer, index into the rows of self - - A -- a sparse matrix - - r -- integer, index into rows of A - - cols -- a *sorted* list of integers. - - cols_index -- (optional). But set it to this to vastly speed up + - ``i`` -- integer, index into the rows of self + - ``A`` -- a sparse matrix + - ``r`` -- integer, index into rows of A + - ``cols`` -- a *sorted* list of integers + - ``cols_index`` -- (optional) set it to this to vastly speed up calls to this function:: dict([(cols[i], i) for i in range(len(cols))]) @@ -728,7 +716,7 @@ cdef class Matrix_rational_sparse(Matrix_sparse): def _right_kernel_matrix(self, **kwds): r""" - Returns a pair that includes a matrix of basis vectors + Return a pair that includes a matrix of basis vectors for the right kernel of ``self``. INPUT: diff --git a/src/sage/matrix/matrix_space.py b/src/sage/matrix/matrix_space.py index 4448c87f3d6..431cf6f5bd9 100644 --- a/src/sage/matrix/matrix_space.py +++ b/src/sage/matrix/matrix_space.py @@ -105,9 +105,9 @@ def get_matrix_class(R, nrows, ncols, sparse, implementation): - ``ncols`` -- number of columns - - ``sparse`` -- (boolean) whether the matrix class should be sparse + - ``sparse`` -- boolean; whether the matrix class should be sparse - - ``implementation`` -- (``None`` or string or a matrix class) a possible + - ``implementation`` -- ``None`` or string or a matrix class; a possible implementation. See the documentation of the constructor of :class:`MatrixSpace`. EXAMPLES:: @@ -192,7 +192,6 @@ def get_matrix_class(R, nrows, ncols, sparse, implementation): sage: type(matrix(GF(125, 'z'), 2, range(4))) # optional - meataxe, needs sage.rings.finite_rings - """ if isinstance(implementation, type): return implementation @@ -298,7 +297,7 @@ def get_matrix_class(R, nrows, ncols, sparse, implementation): except ImportError: pass else: - if polynomial_ring.is_PolynomialRing(R) and R.base_ring() in _Fields: + if isinstance(R, polynomial_ring.PolynomialRing_general) and R.base_ring() in _Fields: try: from . import matrix_polynomial_dense except ImportError: @@ -306,7 +305,7 @@ def get_matrix_class(R, nrows, ncols, sparse, implementation): else: return matrix_polynomial_dense.Matrix_polynomial_dense - elif multi_polynomial_ring_base.is_MPolynomialRing(R) and R.base_ring() in _Fields: + elif isinstance(R, multi_polynomial_ring_base.MPolynomialRing_base) and R.base_ring() in _Fields: try: from . import matrix_mpolynomial_dense except ImportError: @@ -447,17 +446,17 @@ class MatrixSpace(UniqueRepresentation, Parent): - ``base_ring`` -- a ring - - ``nrows`` or ``row_keys`` -- (nonnegative integer) the number of rows, or + - ``nrows`` or ``row_keys`` -- nonnegative integer; the number of rows, or a finite family of arbitrary objects that index the rows of the matrix - - ``ncols`` or ``column_keys`` -- (nonnegative integer, default ``nrows``) + - ``ncols`` or ``column_keys`` -- nonnegative integer (default: ``nrows``); the number of columns, or a finite family of arbitrary objects that index the columns of the matrix - - ``sparse`` -- (boolean, default ``False``) whether or not matrices - are given a sparse representation + - ``sparse`` -- boolean (default: ``False``); whether or not matrices + are given a sparse representation - - ``implementation`` -- (optional, a string or a matrix class) a possible + - ``implementation`` -- (optional) string or matrix class; a possible implementation. Depending on the base ring, the string can be - ``'generic'`` -- on any base rings @@ -697,13 +696,13 @@ def __classcall__(cls, base_ring, :: - sage: M = MatrixSpace(ZZ, 10, implementation="flint") # needs sage.libs.flint + sage: M = MatrixSpace(ZZ, 10, implementation='flint') # needs sage.libs.flint sage: M # needs sage.libs.flint Full MatrixSpace of 10 by 10 dense matrices over Integer Ring sage: loads(M.dumps()) is M # needs sage.libs.flint True - sage: MatrixSpace(ZZ, 10, implementation="foobar") + sage: MatrixSpace(ZZ, 10, implementation='foobar') Traceback (most recent call last): ... ValueError: unknown matrix implementation 'foobar' over Integer Ring @@ -792,15 +791,15 @@ def __init__(self, base_ring, nrows, ncols, sparse, implementation): - ``base_ring`` - - ``nrows`` -- (positive integer) the number of rows + - ``nrows`` -- positive integer; the number of rows - - ``ncols`` -- (positive integer, default nrows) the number of - columns + - ``ncols`` -- positive integer (default: ``nrows``); the number of + columns - - ``sparse`` -- (boolean, default ``False``) whether or not matrices - are given a sparse representation + - ``sparse`` -- boolean (default: ``False``); whether or not matrices + are given a sparse representation - - ``implementation`` -- (optional, a string or a matrix class) a possible + - ``implementation`` -- (optional) string or matrix class; a possible implementation. Depending on the base ring the string can be - ``'generic'`` -- on any base rings @@ -1022,7 +1021,6 @@ def _copy_zero(self): sage: MS = MatrixSpace(QQ,20,20) sage: MS._copy_zero False - """ if self.__is_sparse: return False @@ -1161,9 +1159,7 @@ def change_ring(self, R): INPUT: - - - ``R`` -- ring - + - ``R`` -- ring OUTPUT: a matrix space @@ -1189,7 +1185,7 @@ def base_extend(self, R): INPUT: - - ``R`` -- ring + - ``R`` -- ring OUTPUT: a matrix space @@ -1535,8 +1531,8 @@ def _latex_(self): def __len__(self): """ Return number of elements of this matrix space if it fits in - an int; raise a :class:`TypeError` if there are infinitely many - elements, and raise an :class:`OverflowError` if there are finitely + an int; raise a :exc:`TypeError` if there are infinitely many + elements, and raise an :exc:`OverflowError` if there are finitely many but more than the size of an int. EXAMPLES:: @@ -1563,7 +1559,7 @@ def __len__(self): def __iter__(self): r""" Return a generator object which iterates through the elements of - self. The order in which the elements are generated is based on a + ``self``. The order in which the elements are generated is based on a 'weight' of a matrix which is the number of iterations on the base ring that are required to reach that matrix. @@ -1883,16 +1879,16 @@ def submodule(self, gens, check=True, already_echelonized=False, INPUT: - - ``gens`` -- a list or family of elements of ``self`` + - ``gens`` -- list or family of elements of ``self`` - - ``check`` -- (default: ``True``) whether to verify that the - elements of ``gens`` are in ``self`` + - ``check`` -- boolean (default: ``True``); whether to verify that the + elements of ``gens`` are in ``self`` - - ``already_echelonized`` -- (default: ``False``) whether - the elements of ``gens`` are already in (not necessarily - reduced) echelon form + - ``already_echelonized`` -- boolean (default: ``False``); whether + the elements of ``gens`` are already in (not necessarily + reduced) echelon form - - ``unitriangular`` -- (default: ``False``) whether + - ``unitriangular`` -- boolean (default: ``False``); whether the lift morphism is unitriangular - ``support_order`` -- (optional) either something that can @@ -2009,7 +2005,6 @@ def identity_matrix(self): sage: type(M2.identity_matrix()) - """ if self.__nrows != self.__ncols: raise TypeError("identity matrix must be square") @@ -2023,7 +2018,7 @@ def identity_matrix(self): def diagonal_matrix(self, entries): """ - Create a diagonal matrix in ``self`` using the specified elements + Create a diagonal matrix in ``self`` using the specified elements. INPUT: @@ -2118,7 +2113,7 @@ def is_finite(self): def gen(self, n): """ - Return the n-th generator of this matrix space. + Return the `n`-th generator of this matrix space. This does not compute all basis matrices, so it is reasonably intelligent. @@ -2210,12 +2205,10 @@ def matrix(self, x=None, **kwds): - ``x`` -- data to construct a new matrix from. See :func:`matrix` - - ``coerce`` -- (default: ``True``) if False, assume without - checking that the values in ``x`` lie in the base ring - - OUTPUT: + - ``coerce`` -- boolean (default: ``True``); if ``False``, assume + without checking that the values in ``x`` lie in the base ring - - a matrix in ``self``. + OUTPUT: a matrix in ``self`` EXAMPLES:: @@ -2326,7 +2319,7 @@ def matrix_space(self, nrows=None, ncols=None, sparse=False): """ Return the matrix space with given number of rows, columns and sparsity over the same base ring as self, and defaults the same as - self. + ``self``. EXAMPLES:: @@ -2411,22 +2404,20 @@ def random_element(self, density=None, *args, **kwds): INPUT: - - ``density`` -- ``float`` or ``None`` (default: ``None``); rough - measure of the proportion of nonzero entries in the random matrix; - if set to ``None``, all entries of the matrix are randomized, - allowing for any element of the underlying ring, but if set to - a ``float``, a proportion of entries is selected and randomized to - non-zero elements of the ring + - ``density`` -- ``float`` or ``None`` (default: ``None``); rough + measure of the proportion of nonzero entries in the random matrix; + if set to ``None``, all entries of the matrix are randomized, + allowing for any element of the underlying ring, but if set to + a ``float``, a proportion of entries is selected and randomized to + nonzero elements of the ring - - ``*args, **kwds`` -- remaining parameters, which may be passed to - the random_element function of the base ring. ("may be", since this - function calls the ``randomize`` function on the zero matrix, which - need not call the ``random_element`` function of the base ring at - all in general.) + - ``*args, **kwds`` -- remaining parameters, which may be passed to + the random_element function of the base ring. ("may be", since this + function calls the ``randomize`` function on the zero matrix, which + need not call the ``random_element`` function of the base ring at + all in general.) - OUTPUT: - - - Matrix + OUTPUT: Matrix .. NOTE:: @@ -2434,7 +2425,7 @@ def random_element(self, density=None, *args, **kwds): in a newly allocated zero matrix. By default, if the user sets the value of ``density`` explicitly, this - method will enforce that these entries are set to non-zero values. + method will enforce that these entries are set to nonzero values. However, if the test for equality with zero in the base ring is too expensive, the user can override this behaviour by passing the argument ``nonzero=False`` to this method. @@ -2534,9 +2525,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -2598,19 +2587,17 @@ def _polymake_init_(self): def _random_nonzero_element(self, *args, **kwds): """ - Return a random non-zero matrix. + Return a random nonzero matrix. - This function repeatedly calls ``random_element`` until a non-zero + This function repeatedly calls ``random_element`` until a nonzero matrix is obtained. INPUT: - - ``*args``, ``**kwds`` -- Parameters that can be forwarded to the + - ``*args``, ``**kwds`` -- parameters that can be forwarded to the ``random_element`` method - OUTPUT: - - - Random non-zero matrix + OUTPUT: random nonzero matrix EXAMPLES:: @@ -2702,23 +2689,21 @@ def dict_to_list(entries, nrows, ncols): def _test_trivial_matrices_inverse(ring, sparse=True, implementation=None, checkrank=True): """ - Tests inversion, determinant and is_invertible for trivial matrices. + Test inversion, determinant and is_invertible for trivial matrices. This function is a helper to check that the inversion of trivial matrices (of size 0x0, nx0, 0xn or 1x1) is handled consistently by the various implementation of matrices. The coherency is checked through a bunch of - assertions. If an inconsistency is found, an AssertionError is raised - which should make clear what is the problem. + assertions. If an inconsistency is found, an :exc:`AssertionError` is + raised which should make clear what is the problem. INPUT: - ``ring`` -- a ring - - ``sparse`` -- a boolean - - ``checkrank`` -- a boolean + - ``sparse`` -- boolean + - ``checkrank`` -- boolean - OUTPUT: - - - nothing if everything is correct, otherwise raise an AssertionError + OUTPUT: nothing if everything is correct, otherwise raise an AssertionError The methods determinant, is_invertible, rank and inverse are checked for - the 0x0 empty identity matrix @@ -2759,7 +2744,6 @@ def _test_trivial_matrices_inverse(ring, sparse=True, implementation=None, check sage: tinv(CyclotomicField(7), sparse=False) # needs sage.rings.number_field sage: tinv(QQ['x,y'], sparse=True) sage: tinv(QQ['x,y'], sparse=False) - """ # Check that the empty 0x0 matrix is it's own inverse with det=1. ms00 = MatrixSpace(ring, 0, 0, sparse=sparse) diff --git a/src/sage/matrix/matrix_sparse.pyx b/src/sage/matrix/matrix_sparse.pyx index 9354558d23d..95b8969e0aa 100644 --- a/src/sage/matrix/matrix_sparse.pyx +++ b/src/sage/matrix/matrix_sparse.pyx @@ -228,7 +228,7 @@ cdef class Matrix_sparse(matrix.Matrix): def _multiply_classical_with_cache(Matrix_sparse left, Matrix_sparse right): """ This function computes the locations of the end of the rows/columns - in the non-zero entries list once O(rows+cols) time and space, then + in the nonzero entries list once O(rows+cols) time and space, then uses these values in the inner loops. For large matrices this can be a 2x or more speedup, but the matrices can no longer be arbitrarily large as the runtime and space requirements are no @@ -307,12 +307,10 @@ cdef class Matrix_sparse(matrix.Matrix): INPUT: - - `right` -- a ring element which must already be in the basering - of ``self`` (no coercion done here). + - ``right`` -- a ring element which must already be in the base ring + of ``self`` (no coercion done here) - OUTPUT: - - the matrix ``self * right`` + OUTPUT: the matrix ``self * right`` EXAMPLES:: @@ -659,9 +657,9 @@ cdef class Matrix_sparse(matrix.Matrix): - ``phi`` -- arbitrary Python function or callable object - - ``R`` -- (optional) ring + - ``R`` -- (optional) ring - - ``sparse`` -- (default: ``True``) whether to return + - ``sparse`` -- boolean (default: ``True``); whether to return a sparse or a dense matrix OUTPUT: a matrix over ``R`` @@ -700,7 +698,7 @@ cdef class Matrix_sparse(matrix.Matrix): sage: n[1, 2] 2 - If self is subdivided, the result will be as well:: + If ``self`` is subdivided, the result will be as well:: sage: m = matrix(2, 2, [0, 0, 3, 0]) sage: m.subdivide(None, 1); m @@ -710,7 +708,7 @@ cdef class Matrix_sparse(matrix.Matrix): [0|0] [9|0] - If the map sends zero to a non-zero value, then it may be useful to + If the map sends zero to a nonzero value, then it may be useful to get the result as a dense matrix. :: @@ -744,7 +742,7 @@ cdef class Matrix_sparse(matrix.Matrix): [ 1 1/2] [1/3 1/4] - Test subdivisions when phi maps 0 to non-zero:: + Test subdivisions when phi maps 0 to nonzero:: sage: m = matrix(2, 2, [0, 0, 3, 0]) sage: m.subdivide(None, 1); m @@ -1123,7 +1121,7 @@ cdef class Matrix_sparse(matrix.Matrix): INPUT: - - ``v`` -- a free module element + - ``v`` -- a free module element OUTPUT: the vector times matrix product ``v*A`` diff --git a/src/sage/matrix/matrix_symbolic_dense.pyx b/src/sage/matrix/matrix_symbolic_dense.pyx index 7a0dab316d8..4e64a22cd15 100644 --- a/src/sage/matrix/matrix_symbolic_dense.pyx +++ b/src/sage/matrix/matrix_symbolic_dense.pyx @@ -170,7 +170,6 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): """ Echelonize using the classical algorithm. - TESTS:: sage: m = matrix([[cos(pi/5), sin(pi/5)], [-sin(pi/5), cos(pi/5)]]) @@ -179,7 +178,7 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): [0 1] """ - return super().echelonize(algorithm="classical", **kwds) + return super().echelonize(algorithm='classical', **kwds) def eigenvalues(self, extend=True): """ @@ -479,7 +478,7 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): INPUT: - - ``var`` -- (default: 'x') name of variable of charpoly + - ``var`` -- (default: ``'x'``) name of variable of charpoly EXAMPLES:: @@ -569,7 +568,6 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): sage: m = matrix([[x]]) sage: m.minimal_polynomial('y') y - x - """ mp = self.fetch('minpoly') if mp is None: @@ -586,7 +584,7 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): INPUT: - - ``var`` -- (default: 'x') name of variable of charpoly + - ``var`` -- (default: ``'x'``) name of variable of charpoly EXAMPLES:: @@ -605,7 +603,6 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): (x^2 - 65*x - 250) * x^3 sage: list(a.fcp()) [(x^2 - 65*x - 250, 1), (x, 3)] - """ from sage.symbolic.ring import SR sub_dict = {var: SR.var(var)} @@ -779,11 +776,9 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): INPUT: - - ``self`` -- the matrix whose entries we should simplify. + - ``self`` -- the matrix whose entries we should simplify - OUTPUT: - - A copy of ``self`` with all of its entries simplified. + OUTPUT: a copy of ``self`` with all of its entries simplified EXAMPLES: @@ -798,7 +793,6 @@ cdef class Matrix_symbolic_dense(Matrix_generic_dense): sage: A.simplify_full() [ 1 sin(1/(x + 1))] [ factorial(n) x^(-a + 1)*sin(2)] - """ M = self.parent() return M([expr.simplify_full() for expr in self]) diff --git a/src/sage/matrix/matrix_symbolic_sparse.pyx b/src/sage/matrix/matrix_symbolic_sparse.pyx index 680e36c5c6c..a1acdc401b4 100644 --- a/src/sage/matrix/matrix_symbolic_sparse.pyx +++ b/src/sage/matrix/matrix_symbolic_sparse.pyx @@ -177,7 +177,6 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): """ Echelonize using the classical algorithm. - TESTS:: sage: m = matrix([[cos(pi/5), sin(pi/5)], [-sin(pi/5), cos(pi/5)]], sparse=True) @@ -185,7 +184,7 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): [1 0] [0 1] """ - return super().echelonize(algorithm="classical", **kwds) + return super().echelonize(algorithm='classical', **kwds) def eigenvalues(self, extend=True): """ @@ -486,7 +485,7 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): INPUT: - - ``var`` -- (default: 'x') name of variable of charpoly + - ``var`` -- (default: ``'x'``) name of variable of charpoly EXAMPLES:: @@ -576,7 +575,6 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): sage: m = matrix([[x]], sparse=True) sage: m.minimal_polynomial('y') y - x - """ mp = self.fetch('minpoly') if mp is None: @@ -593,7 +591,7 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): INPUT: - - ``var`` -- (default: 'x') name of variable of charpoly + - ``var`` -- (default: ``'x'``) name of variable of charpoly EXAMPLES:: @@ -612,7 +610,6 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): (x^2 - 65*x - 250) * x^3 sage: list(a.fcp()) [(x^2 - 65*x - 250, 1), (x, 3)] - """ from sage.symbolic.ring import SR sub_dict = {var: SR.var(var)} @@ -786,11 +783,9 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): INPUT: - - ``self`` -- the matrix whose entries we should simplify. + - ``self`` -- the matrix whose entries we should simplify - OUTPUT: - - A copy of ``self`` with all of its entries simplified. + OUTPUT: a copy of ``self`` with all of its entries simplified EXAMPLES: @@ -805,7 +800,6 @@ cdef class Matrix_symbolic_sparse(Matrix_generic_sparse): sage: A.simplify_full() [ 1 sin(1/(x + 1))] [ factorial(n) x^(-a + 1)*sin(2)] - """ M = self.parent() return M([expr.simplify_full() for expr in self]) diff --git a/src/sage/matrix/matrix_window.pyx b/src/sage/matrix/matrix_window.pyx index 4a1f057ef1e..8c79540f6ef 100644 --- a/src/sage/matrix/matrix_window.pyx +++ b/src/sage/matrix/matrix_window.pyx @@ -55,7 +55,7 @@ cdef class MatrixWindow: cpdef MatrixWindow matrix_window(MatrixWindow self, Py_ssize_t row, Py_ssize_t col, Py_ssize_t n_rows, Py_ssize_t n_cols): """ - Returns a matrix window relative to this window of the + Return a matrix window relative to this window of the underlying matrix. """ if row == 0 and col == 0 and n_rows == self._nrows and n_cols == self._ncols: @@ -121,13 +121,13 @@ cdef class MatrixWindow: cpdef matrix(MatrixWindow self): """ - Returns the underlying matrix that this window is a view of. + Return the underlying matrix that this window is a view of. """ return self._matrix cpdef to_matrix(MatrixWindow self): """ - Returns an actual matrix object representing this view. + Return an actual matrix object representing this view. """ cdef MatrixWindow w a = self._matrix.new_matrix(self._nrows, self._ncols) # zero matrix diff --git a/src/sage/matrix/misc.pyx b/src/sage/matrix/misc.pyx index 5ff93f4accb..17277336e3c 100644 --- a/src/sage/matrix/misc.pyx +++ b/src/sage/matrix/misc.pyx @@ -124,16 +124,17 @@ def matrix_integer_sparse_rational_reconstruction(Matrix_integer_sparse A, Integ def matrix_rational_echelon_form_multimodular(Matrix self, height_guess=None, proof=None): """ - Returns reduced row-echelon form using a multi-modular - algorithm. Does not change self. + Return reduced row-echelon form using a multi-modular + algorithm. Does not change ``self``. REFERENCE: Chapter 7 of Stein's "Explicitly Computing Modular Forms". INPUT: - - height_guess -- integer or None - - proof -- boolean or None (default: None, see proof.linear_algebra or - sage.structure.proof). Note that the global Sage default is proof=True + - ``height_guess`` -- integer or ``None`` + - ``proof`` -- boolean or ``None`` (default: ``None``, see + ``proof.linear_algebra`` or ``sage.structure.proof``). Note that the + global Sage default is proof=True OUTPUT: a pair consisting of a matrix in echelon form and a tuple of pivot positions. diff --git a/src/sage/matrix/misc_flint.pyx b/src/sage/matrix/misc_flint.pyx index 3e829df4d22..2d054c9e718 100644 --- a/src/sage/matrix/misc_flint.pyx +++ b/src/sage/matrix/misc_flint.pyx @@ -27,7 +27,7 @@ def matrix_integer_dense_rational_reconstruction(Matrix_integer_dense A, Integer INPUT: - ``A`` -- matrix - - ``N`` -- an integer + - ``N`` -- integer EXAMPLES:: diff --git a/src/sage/matrix/operation_table.py b/src/sage/matrix/operation_table.py index edd2c781047..421ba420347 100644 --- a/src/sage/matrix/operation_table.py +++ b/src/sage/matrix/operation_table.py @@ -61,13 +61,14 @@ class OperationTable(SageObject): - ``elements`` -- (default: ``None``) A list of elements of ``S``, in forms that can be coerced into the structure, eg. their string representations. This may be used to impose an alternate - ordering on the elements of `S``, perhaps when this is used in + ordering on the elements of ``S``, perhaps when this is used in the context of a particular structure. The default is to use - whatever ordering the ``S.list()`` method returns. `elements`` + whatever ordering the ``S.list()`` method returns. ``elements`` can also be a subset which is closed under the operation, useful perhaps when the set is infinite. OUTPUT: + An object with methods that abstracts multiplication tables, addition tables, Cayley tables, etc. It should be general enough to be useful for any finite algebraic structure @@ -493,17 +494,18 @@ def _name_maker(self, names): Helper function to create names of elements of algebraic structures. INPUT: + Identical to the input for :class:`OperationTable` and :meth:`change_names`, so look there for details. OUTPUT: - - ``width`` -- an integer giving the maximum width of the strings + - ``width`` -- integer giving the maximum width of the strings describing the elements. This is used for formatting the ASCII version of the table. - - ``name_list`` -- a list of strings naming the elements, in the - same order as given by the :meth:`list` method. - - ``name_dict`` -- a dictionary giving the correspondence between the + - ``name_list`` -- list of strings naming the elements, in the + same order as given by the :meth:`list` method + - ``name_dict`` -- dictionary giving the correspondence between the strings and the actual elements. So the keys are the strings and the values are the elements of the structure. @@ -599,12 +601,14 @@ def _name_maker(self, names): def __getitem__(self, pair): r""" - Returns the element of the table, given the elements indexing its position. + Return the element of the table, given the elements indexing its position. INPUT: - - pair -- two elements of the structure + + - ``pair`` -- two elements of the structure OUTPUT: + The element of the structure computed by the operation for the two input elements (in the order provided). @@ -659,13 +663,14 @@ def __getitem__(self, pair): def __eq__(self, other): r""" - Returns the comparison between two tables. + Return the comparison between two tables. INPUT: - - ``other`` -- a second table to compare to ``self``. + - ``other`` -- a second table to compare to ``self`` OUTPUT: + Tables are equal if they have the same operation and elements. EXAMPLES:: @@ -704,7 +709,7 @@ def __ne__(self, other): def _repr_(self): r""" - Returns a printable version of the operation table. + Return a printable version of the operation table. EXAMPLES:: @@ -729,8 +734,8 @@ def set_print_symbols(self, ascii, latex): INPUT: - ``ascii`` -- a single character for text table - - ``latex`` -- a string to represent an operation in LaTeX math mode. - Note the need for double-backslashes to escape properly. + - ``latex`` -- string to represent an operation in LaTeX math mode; + note the need for double-backslashes to escape properly EXAMPLES:: @@ -778,9 +783,9 @@ def set_print_symbols(self, ascii, latex): def column_keys(self): r""" - Returns a tuple of the elements used to build the table. + Return a tuple of the elements used to build the table. - .. note:: ``column_keys`` and ``row_keys`` are identical. + .. NOTE:: ``column_keys`` and ``row_keys`` are identical. Both list the elements in the order used to label the table. OUTPUT: @@ -809,9 +814,10 @@ def column_keys(self): def translation(self): r""" - Returns a dictionary associating names with elements. + Return a dictionary associating names with elements. OUTPUT: + A dictionary whose keys are strings used as names for entries of the table and values that are the actual elements of the algebraic structure. @@ -828,10 +834,11 @@ def translation(self): def table(self): r""" - Returns the table as a list of lists, + Return the table as a list of lists, using integers to reference the elements. OUTPUT: + The rows of the table, as a list of rows, each row being a list of integer entries. The integers correspond to the order of the elements in the headings of the table @@ -968,7 +975,8 @@ def color_table(self, element_names=True, cmap=None, **options): INPUT: - - ``element_names`` -- (default : ``True``) Whether to display text with element names on the image + - ``element_names`` -- (default: ``True``) whether to display text with + element names on the image - ``cmap`` -- (default: :obj:`matplotlib.cm.gist_rainbow`) color map for plot, see :mod:`matplotlib.cm` @@ -1029,7 +1037,8 @@ def gray_table(self, **options): INPUT: - - ``element_names`` -- (default: ``True``) whether to display text with element names on the image + - ``element_names`` -- boolean (default: ``True``); whether to display + text with element names on the image - ``**options`` -- passed on to :func:`~sage.plot.matrix_plot.matrix_plot` @@ -1051,7 +1060,7 @@ def gray_table(self, **options): def _ascii_table(self): r""" - Returns a string that is an ASCII version of the table. + Return a string that is an ASCII version of the table. EXAMPLES:: @@ -1142,7 +1151,7 @@ def _ascii_table(self): def _latex_(self): r""" - Returns a `LaTeX` version of the operation table as a string, + Return a `LaTeX` version of the operation table as a string, using a `LaTeX` ``array`` environment. EXAMPLES:: diff --git a/src/sage/matrix/special.py b/src/sage/matrix/special.py index 1f4f95be263..b81703b6fe7 100644 --- a/src/sage/matrix/special.py +++ b/src/sage/matrix/special.py @@ -79,13 +79,13 @@ def matrix_method(func=None, name=None): """ - Allows a function to be tab-completed on the global matrix + Allow a function to be tab-completed on the global matrix constructor object. INPUT: - - ``*function`` -- a single argument. The function that is being - decorated. + - ``*function`` -- a single argument; the function that is being + decorated - ``**kwds`` -- a single optional keyword argument ``name=``. The name of the corresponding method in the @@ -128,7 +128,7 @@ def column_matrix(*args, **kwds): r""" Construct a matrix, and then swap rows for columns and columns for rows. - .. note:: + .. NOTE:: Linear algebra in Sage favors rows over columns. So, generally, when creating a matrix, input vectors and lists are @@ -155,7 +155,7 @@ def column_matrix(*args, **kwds): The most compelling use of this function is when you have a collection of lists or vectors that you would like to become the columns of a matrix. In almost any other situation, the - :func:`matrix`` constructor can probably do the + :func:`matrix` constructor can probably do the job just as easily, or easier. :: sage: col_1 = [1,2,3] @@ -217,40 +217,39 @@ def random_matrix(ring, nrows, ncols=None, algorithm='randomize', implementation INPUT: - - ``ring`` -- base ring for entries of the matrix + - ``ring`` -- base ring for entries of the matrix - - ``nrows`` -- Integer; number of rows + - ``nrows`` -- integer; number of rows - - ``ncols`` -- (default: ``None``); number of columns; if ``None`` - defaults to ``nrows`` + - ``ncols`` -- (default: ``None``) number of columns. If ``None`` + defaults to ``nrows``. - - ``algorithm`` -- (default: ``randomize``); determines what properties - the matrix will have. See examples below for possible additional - arguments. + - ``algorithm`` -- (default: ``'randomize'``) determines what properties + the matrix will have. See examples below for possible additional + arguments. - - ``randomize`` -- create a matrix of random elements from the - base ring, possibly controlling the density of non-zero entries. + - ``'randomize'`` -- create a matrix of random elements from the + base ring, possibly controlling the density of nonzero entries - - ``echelon_form`` -- creates a matrix in echelon form + - ``'echelon_form'`` -- creates a matrix in echelon form - - ``echelonizable`` -- creates a matrix that has a predictable - echelon form + - ``'echelonizable'`` -- creates a matrix that has a predictable + echelon form - - ``subspaces`` -- creates a matrix whose four subspaces, when - explored, have reasonably sized, integral valued, entries. + - ``'subspaces'`` -- creates a matrix whose four subspaces, when + explored, have reasonably sized, integral valued, entries - - ``unimodular`` -- creates a matrix of determinant 1. + - ``'unimodular'`` -- creates a matrix of determinant 1 - - ``diagonalizable`` -- creates a diagonalizable matrix whose - eigenvectors, if computed by hand, will have only integer - entries. + - ``'diagonalizable'`` -- creates a diagonalizable matrix whose + eigenvectors, if computed by hand, will have only integer entries - ``implementation`` -- (``None`` or string or a matrix class) a possible implementation. See the documentation of the constructor of :class:`~sage.matrix.matrix_space.MatrixSpace`. - - ``*args, **kwds`` -- arguments and keywords to describe additional - properties. See more detailed documentation below. + - ``*args, **kwds`` -- arguments and keywords to describe additional + properties. See more detailed documentation below .. warning:: @@ -265,11 +264,11 @@ def random_matrix(ring, nrows, ncols=None, algorithm='randomize', implementation An upper bound on the absolute value of the entries may be set when the ``algorithm`` is ``echelonizable`` or ``unimodular``. In these cases it is possible for this constructor to fail with - a :class:`ValueError`. If you *must* have this routine return + a :exc:`ValueError`. If you *must* have this routine return successfully, do not set ``upper_bound``. This behavior can be partially controlled by a ``max_tries`` keyword. - .. note:: + .. NOTE:: When constructing matrices with random entries and no additional properties (i.e. when ``algorithm='randomize'``), @@ -404,7 +403,7 @@ def random_matrix(ring, nrows, ncols=None, algorithm='randomize', implementation sage: K. = FiniteField(2^8) # needs sage.rings.finite_rings sage: type(random_matrix(K, 2, 5)) # needs sage.libs.m4ri sage.rings.finite_rings - sage: type(random_matrix(K, 2, 5, implementation="generic")) # needs sage.rings.finite_rings + sage: type(random_matrix(K, 2, 5, implementation='generic')) # needs sage.rings.finite_rings Random rational matrices. Now ``num_bound`` and ``den_bound`` control the @@ -488,7 +487,7 @@ def random_matrix(ring, nrows, ncols=None, algorithm='randomize', implementation sage: TestSuite(A).run() Random matrices in echelon form. The ``algorithm='echelon_form'`` keyword, - along with a requested number of non-zero rows (``num_pivots``) will return + along with a requested number of nonzero rows (``num_pivots``) will return a random matrix in echelon form. When the base ring is ``QQ`` the result has integer entries. Other exact rings may be also specified. :: @@ -696,8 +695,8 @@ def diagonal_matrix(arg0=None, arg1=None, arg2=None, sparse=True): diagonal entries. This may not be specified in combination with a NumPy array. - - ``sparse`` -- (default: ``True``); whether or not - the result has a sparse implementation. + - ``sparse`` -- boolean (default: ``True``); whether or not + the result has a sparse implementation OUTPUT: @@ -1035,11 +1034,11 @@ def ones_matrix(ring, nrows=None, ncols=None, sparse=False): INPUT: - - ``ring`` -- (default: ``ZZ``); base ring for the matrix. - - ``nrows`` -- number of rows in the matrix. - - ``ncols`` -- number of columns in the matrix. - If omitted, defaults to the number of rows, producing a square matrix. - - ``sparse`` -- (default: ``False``); if ``True`` creates a sparse representation. + - ``ring`` -- (default: ``ZZ``) base ring for the matrix + - ``nrows`` -- number of rows in the matrix + - ``ncols`` -- number of columns in the matrix; + if omitted, defaults to the number of rows, producing a square matrix + - ``sparse`` -- (default: ``False``) if ``True`` creates a sparse representation OUTPUT: @@ -1115,7 +1114,7 @@ def ones_matrix(ring, nrows=None, ncols=None, sparse=False): @matrix_method def elementary_matrix(arg0, arg1=None, **kwds): r""" - Creates a square matrix that corresponds to a row operation or a column operation. + Create a square matrix that corresponds to a row operation or a column operation. FORMATS: @@ -1281,7 +1280,7 @@ def elementary_matrix(arg0, arg1=None, **kwds): sage: E3 = elementary_matrix(QQ, 4, row1=3, scale=0) Traceback (most recent call last): ... - ValueError: scale parameter of row of elementary matrix must be non-zero + ValueError: scale parameter of row of elementary matrix must be nonzero sage: E4 = elementary_matrix(QQ, 4, row1=3, row2=3, scale=12) Traceback (most recent call last): @@ -1417,7 +1416,7 @@ def elementary_matrix(arg0, arg1=None, **kwds): sage: E = elementary_matrix(ZZ, 5, col1=3, scale=0) Traceback (most recent call last): ... - ValueError: scale parameter of column of elementary matrix must be non-zero + ValueError: scale parameter of column of elementary matrix must be nonzero AUTHOR: @@ -1501,7 +1500,7 @@ def elementary_matrix(arg0, arg1=None, **kwds): elem[row2, row1] = 1 elif row2 is None and scale is not None: if scale == 0: - raise ValueError('scale parameter of {0} of elementary matrix must be non-zero'.format(opstring)) + raise ValueError('scale parameter of {0} of elementary matrix must be nonzero'.format(opstring)) elem[row1, row1] = scale if rowop: return elem @@ -1512,14 +1511,14 @@ def elementary_matrix(arg0, arg1=None, **kwds): @matrix_method def circulant(v, sparse=None): r""" - Return the circulant matrix specified by its 1st row `v` + Return the circulant matrix specified by its 1st row `v`. A circulant `n \times n` matrix specified by the 1st row `v=(v_0...v_{n-1})` is the matrix `(c_{ij})_{0 \leq i,j\leq n-1}`, where `c_{ij}=v_{j-i \mod b}`. INPUT: - - ``v`` -- a list or a vector of values + - ``v`` -- list or a vector of values - ``sparse`` -- ``None`` by default; if ``sparse`` is set to ``True``, the output will be sparse. Respectively, setting it to ``False`` produces dense output. @@ -1574,7 +1573,7 @@ def _determine_block_matrix_grid(sub_matrices): Non-zero scalars are considered to be square matrices of any size, and zeroes are considered to be zero matrices of any size. - A :class:`ValueError` is raised if there is insufficient or + A :exc:`ValueError` is raised if there is insufficient or conflicting information. TESTS:: @@ -1612,7 +1611,7 @@ def _determine_block_matrix_grid(sub_matrices): if isinstance(M, Matrix): sub_width = M.ncols() sub_height = M.nrows() - elif M: # non-zero scalar is interpreted as a square matrix + elif M: # nonzero scalar is interpreted as a square matrix if row_heights[i] is None: sub_width = col_widths[j] else: @@ -1653,7 +1652,7 @@ def _determine_block_matrix_rows(sub_matrices): Non-zero scalars are considered to be square matrices of any size, and zeroes are considered to be zero matrices of any size. - A ``ValueError`` is raised if there is insufficient or + A :exc:`ValueError` is raised if there is insufficient or conflicting information. TESTS:: @@ -1691,14 +1690,14 @@ def _determine_block_matrix_rows(sub_matrices): height = 0 # If we have a height, then we know the dimensions of any - # non-zero scalars, and can maybe compute the width + # nonzero scalars, and can maybe compute the width if height is not None and not found_zeroes: width = 0 for M in R: if isinstance(M, Matrix): width += M.ncols() else: - # non-zero scalar + # nonzero scalar width += height if total_width is None: total_width = width @@ -1723,7 +1722,7 @@ def _determine_block_matrix_rows(sub_matrices): zero_state = 0 # 0: no zeroes found # 1: consecutive zeroes found - # 2: consecutive zeroes followed by non-zero found + # 2: consecutive zeroes followed by nonzero found # 3: non-consecutive zeroes found scalars = 0 width = 0 @@ -1745,7 +1744,7 @@ def _determine_block_matrix_rows(sub_matrices): remaining_width = total_width - width # This remaining width has to be split over the - # zeroes and (non-zero) scalars + # zeroes and (nonzero) scalars if height is not None: remaining_width -= scalars * height @@ -1795,19 +1794,18 @@ def block_matrix(*args, **kwds): ``nrows`` and ``ncols`` to determine their layout), or a list of lists of matrices, where each list forms a row. - - ``ring`` -- the base ring - - - ``nrows`` -- the number of block rows + - ``ring`` -- the base ring - - ``ncols`` -- the number of block cols + - ``nrows`` -- the number of block rows - - ``sub_matrices`` -- matrices (see below for syntax) + - ``ncols`` -- the number of block cols - - ``subdivide`` -- boolean, whether or not to add - subdivision information to the matrix + - ``sub_matrices`` -- matrices (see below for syntax) - - ``sparse`` -- boolean, whether to make the resulting matrix sparse + - ``subdivide`` -- boolean, whether or not to add + subdivision information to the matrix + - ``sparse`` -- boolean, whether to make the resulting matrix sparse EXAMPLES:: @@ -2177,9 +2175,9 @@ def jordan_block(eigenvalue, size, sparse=False): INPUT: - - ``eigenvalue`` -- eigenvalue for the diagonal entries of the block - - ``size`` -- size of the square matrix - - ``sparse`` -- (default: ``False``); if ``True``, return a sparse matrix + - ``eigenvalue`` -- eigenvalue for the diagonal entries of the block + - ``size`` -- size of the square matrix + - ``sparse`` -- (default: ``False``) if ``True``, return a sparse matrix EXAMPLES:: @@ -2197,7 +2195,7 @@ def jordan_block(eigenvalue, size, sparse=False): sage: jordan_block(6.2, -1) Traceback (most recent call last): ... - ValueError: size of Jordan block must be non-negative, not -1 + ValueError: size of Jordan block must be nonnegative, not -1 """ try: size = ZZ(size) @@ -2205,7 +2203,7 @@ def jordan_block(eigenvalue, size, sparse=False): msg = "size of Jordan block needs to be an integer, not {0}" raise TypeError(msg.format(size)) if size < 0: - msg = "size of Jordan block must be non-negative, not {0}" + msg = "size of Jordan block must be nonnegative, not {0}" raise ValueError(msg.format(size)) block = diagonal_matrix([eigenvalue] * size, sparse=sparse) for i in range(size - 1): @@ -2227,10 +2225,10 @@ def companion_matrix(poly, format='right'): A symbolic expression that might also be a polynomial is not proper input, see examples below. - - ``format`` -- (default: 'right'); specifies one of four + - ``format`` -- (default: ``'right'``) specifies one of four variations of a companion matrix. Allowable values are - 'right', 'left', 'top' and 'bottom', which indicates which - border of the matrix contains the negatives of the coefficients. + ``'right'``, ``'left'``, ``'top'`` and ``'bottom'``, which indicates + which border of the matrix contains the negatives of the coefficients. OUTPUT: @@ -2394,7 +2392,7 @@ def companion_matrix(poly, format='right'): M = sage.matrix.constructor.matrix(poly.universe(), n, n) except TypeError: raise TypeError("unable to find common ring for coefficients from polynomial") - # 1's below diagonal, or above diagonal + # 1s below diagonal, or above diagonal if format in ['right', 'top']: for i in range(n - 1): M[i+1, i] = 1 @@ -2420,21 +2418,21 @@ def companion_matrix(poly, format='right'): @matrix_method def random_rref_matrix(parent, num_pivots): r""" - Generate a matrix in reduced row-echelon form with a specified number of non-zero rows. + Generate a matrix in reduced row-echelon form with a specified number of nonzero rows. INPUT: - - ``parent`` -- A matrix space specifying the base ring, dimensions and + - ``parent`` -- a matrix space specifying the base ring, dimensions and representation (dense/sparse) for the result. The base ring must be exact. - - ``num_pivots`` -- The number of non-zero rows in the result, i.e. the rank. + - ``num_pivots`` -- the number of nonzero rows in the result, i.e. the rank OUTPUT: - A matrix in reduced row echelon form with ``num_pivots`` non-zero rows. If the + A matrix in reduced row echelon form with ``num_pivots`` nonzero rows. If the base ring is `ZZ` or `QQ` then the entries are all integers. - .. note:: + .. NOTE:: It is easiest to use this function via a call to the :func:`~sage.matrix.constructor.random_matrix` @@ -2595,32 +2593,31 @@ def random_echelonizable_matrix(parent, rank, upper_bound=None, max_tries=100): INPUT: - - ``parent`` -- A matrix space specifying the base ring, dimensions and + - ``parent`` -- a matrix space specifying the base ring, dimensions and representation (dense/sparse) for the result. The base ring must be exact. - - ``rank`` -- Rank of result, i.e the number of non-zero rows in the - reduced row echelon form. + - ``rank`` -- rank of result, i.e the number of nonzero rows in the + reduced row echelon form - - ``upper_bound`` -- If designated, size control of the matrix entries is desired. + - ``upper_bound`` -- if designated, size control of the matrix entries is desired Set ``upper_bound`` to 1 more than the maximum value entries can achieve. - If None, no size control occurs. But see the warning below. (default: None) + If ``None``, no size control occurs. But see the warning below. (default: ``None``) - - ``max_tries`` -- If designated, number of tries used to generate each new random row; + - ``max_tries`` -- if designated, number of tries used to generate each new random row;s only matters when upper_bound!=None. Used to prevent endless looping. (default: 100) - OUTPUT: - - A matrix not in reduced row-echelon form with the desired dimensions and properties. + OUTPUT: a matrix not in reduced row-echelon form with the desired + dimensions and properties .. warning:: When ``upper_bound`` is set, it is possible for this constructor to - fail with a ``ValueError``. This may happen when the ``upper_bound``, + fail with a :exc:`ValueError`. This may happen when the ``upper_bound``, ``rank`` and/or matrix dimensions are all so small that it becomes infeasible or unlikely to create the requested matrix. If you *must* have this routine return successfully, do not set ``upper_bound``. - .. note:: + .. NOTE:: It is easiest to use this function via a call to the :func:`~sage.matrix.constructor.random_matrix` @@ -2810,17 +2807,17 @@ def random_subspaces_matrix(parent, rank=None): INPUT: - - ``parent`` -- A matrix space specifying the base ring, dimensions, and + - ``parent`` -- a matrix space specifying the base ring, dimensions, and representation (dense/sparse) for the result. The base ring must be exact. - - ``rank`` -- The desired rank of the return matrix (default: None). + - ``rank`` -- the desired rank of the return matrix (default: ``None``) OUTPUT: A matrix whose natural basis vectors for its four subspaces, when computed, have reasonably sized, integral valued, entries. - .. note:: + .. NOTE:: It is easiest to use this function via a call to the :func:`~sage.matrix.constructor.random_matrix` @@ -2957,32 +2954,30 @@ def random_unimodular_matrix(parent, upper_bound=None, max_tries=100): INPUT: - - ``parent`` -- A matrix space specifying the base ring, dimensions + - ``parent`` -- a matrix space specifying the base ring, dimensions and representation (dense/sparse) for the result. The base ring must be exact. - - ``upper_bound`` -- For large matrices over QQ or ZZ, + - ``upper_bound`` -- for large matrices over QQ or ZZ, ``upper_bound`` is the largest value matrix entries can achieve. But see the warning below. - - ``max_tries`` -- If designated, number of tries used to generate each new random row; + - ``max_tries`` -- if designated, number of tries used to generate each new random row; only matters when upper_bound!=None. Used to prevent endless looping. (default: 100) A matrix not in reduced row-echelon form with the desired dimensions and properties. - OUTPUT: - - An invertible matrix with the desired properties and determinant 1. + OUTPUT: an invertible matrix with the desired properties and determinant 1 .. warning:: When ``upper_bound`` is set, it is possible for this constructor to - fail with a ``ValueError``. This may happen when the ``upper_bound``, + fail with a :exc:`ValueError`. This may happen when the ``upper_bound``, ``rank`` and/or matrix dimensions are all so small that it becomes infeasible or unlikely to create the requested matrix. If you *must* have this routine return successfully, do not set ``upper_bound``. - .. note:: + .. NOTE:: It is easiest to use this function via a call to the :func:`~sage.matrix.constructor.random_matrix` @@ -3067,12 +3062,12 @@ def random_diagonalizable_matrix(parent,eigenvalues=None,dimensions=None): If eigenvalues and dimensions are not specified in a list, they will be assigned randomly. - - ``parent`` -- the desired size of the square matrix. + - ``parent`` -- the desired size of the square matrix - - ``eigenvalues`` -- the list of desired eigenvalues (default=None). + - ``eigenvalues`` -- the list of desired eigenvalues (default=None) - ``dimensions`` -- the list of dimensions corresponding to each - eigenspace (default=None). + eigenspace (default=None) OUTPUT: @@ -3080,7 +3075,7 @@ def random_diagonalizable_matrix(parent,eigenvalues=None,dimensions=None): eigenspaces of this matrix, if computed by hand, give basis vectors with only integer entries. - .. note:: + .. NOTE:: It is easiest to use this function via a call to the :func:`~sage.matrix.constructor.random_matrix` @@ -3283,7 +3278,7 @@ def random_diagonalizable_matrix(parent,eigenvalues=None,dimensions=None): def vector_on_axis_rotation_matrix(v, i, ring=None): r""" Return a rotation matrix `M` such that `det(M)=1` sending the vector - `v` on the i-th axis so that all other coordinates of `Mv` are zero. + `v` on the `i`-th axis so that all other coordinates of `Mv` are zero. .. NOTE:: @@ -3296,9 +3291,7 @@ def vector_on_axis_rotation_matrix(v, i, ring=None): - ``i`` -- integer - ``ring`` -- ring (default: ``None``) of the resulting matrix - OUTPUT: - - A matrix + OUTPUT: a matrix EXAMPLES:: @@ -3358,8 +3351,8 @@ def vector_on_axis_rotation_matrix(v, i, ring=None): @matrix_method def ith_to_zero_rotation_matrix(v, i, ring=None): r""" - Return a rotation matrix that sends the i-th coordinates of the - vector v to zero by doing a rotation with the (i-1)-th coordinate. + Return a rotation matrix that sends the `i`-th coordinates of the + vector v to zero by doing a rotation with the `(i-1)`-th coordinate. INPUT: @@ -3367,9 +3360,7 @@ def ith_to_zero_rotation_matrix(v, i, ring=None): - ``i`` -- integer - ``ring`` -- ring (default: ``None``) of the resulting matrix - OUTPUT: - - A matrix + OUTPUT: a matrix EXAMPLES:: @@ -3483,9 +3474,9 @@ def hilbert(dim, ring=QQ): INPUT: - - ``dim`` -- integer, the dimension of the Hilbert matrix + - ``dim`` -- integer; the dimension of the Hilbert matrix - - ``ring`` -- base ring (default: \\QQ) of the resulting matrix + - ``ring`` -- base ring (default: `\QQ`) of the resulting matrix EXAMPLES:: @@ -3519,7 +3510,7 @@ def vandermonde(v, ring=None): - ``v`` -- vector, the second column of the Vandermonde matrix - - ``ring`` -- base ring (default: None) of the resulting matrix + - ``ring`` -- base ring (default: ``None``) of the resulting matrix EXAMPLES: @@ -3554,7 +3545,7 @@ def toeplitz(c, r, ring=None): - ``r`` -- vector, first row of the Toeplitz matrix, counting from the second column - - ``ring`` -- base ring (default: None) of the resulting matrix + - ``ring`` -- base ring (default: ``None``) of the resulting matrix EXAMPLES: @@ -3603,10 +3594,10 @@ def hankel(c, r=None, ring=None): - ``c`` -- vector, first column of the Hankel matrix - - ``r`` -- vector (default: None), last row of the Hankel matrix, from + - ``r`` -- vector (default: ``None``); last row of the Hankel matrix, from the second to the last column - - ``ring`` -- base ring (default: None) of the resulting matrix + - ``ring`` -- base ring (default: ``None``) of the resulting matrix EXAMPLES: diff --git a/src/sage/matrix/strassen.pyx b/src/sage/matrix/strassen.pyx index 9d5e7ddadf6..56c4bf183ad 100644 --- a/src/sage/matrix/strassen.pyx +++ b/src/sage/matrix/strassen.pyx @@ -22,7 +22,7 @@ from cysignals.signals cimport sig_on, sig_off def strassen_window_multiply(C, A,B, cutoff): """ - Multiplies the submatrices specified by A and B, places result in + Multiply the submatrices specified by A and B, places result in C. Assumes that A and B have compatible dimensions to be multiplied, and that C is the correct size to receive the product, and that they are all defined over the same ring. @@ -248,17 +248,17 @@ cdef subtract_strassen_product(MatrixWindow result, MatrixWindow A, MatrixWindow def strassen_echelon(MatrixWindow A, cutoff): """ Compute echelon form, in place. Internal function, call with - M.echelonize(algorithm="strassen") Based on work of Robert Bradshaw + M.echelonize(algorithm='strassen') Based on work of Robert Bradshaw and David Harvey at MSRI workshop in 2006. INPUT: - - ``A`` -- matrix window + - ``A`` -- matrix window - - ``cutoff`` -- size at which algorithm reverts to - naive Gaussian elimination and multiplication must be at least 1. + - ``cutoff`` -- size at which algorithm reverts to + naive Gaussian elimination and multiplication must be at least 1 - OUTPUT: The list of pivot columns + OUTPUT: the list of pivot columns EXAMPLES:: @@ -414,7 +414,7 @@ cdef strassen_echelon_c(MatrixWindow A, Py_ssize_t cutoff, Py_ssize_t mul_cutoff # let [ 0 I F ] = [ 0 I F ] top_cut = max(max(bottom_pivots) + 1, bottom_cut) - # Note: left with respect to leftmost non-zero column of bottom + # Note: left with respect to leftmost nonzero column of bottom top_left = top.matrix_window(0, bottom_start, top_h, top_cut - bottom_start) if bottom_h + top_h < ncols: @@ -492,8 +492,8 @@ class int_range: It can be one of the following: - - ``indices`` -- integer, start of the unique interval - - ``range`` -- integer, length of the unique interval + - ``indices`` -- integer; start of the unique interval + - ``range`` -- integer; length of the unique interval OR @@ -501,7 +501,7 @@ class int_range: OR - - ``indices`` -- None (default), shortcut for an empty list + - ``indices`` -- ``None`` (default), shortcut for an empty list OUTPUT: @@ -591,9 +591,7 @@ class int_range: r""" Return the list of intervals. - OUTPUT: - - A list of pairs of integers. + OUTPUT: list of pairs of integers EXAMPLES:: @@ -610,9 +608,7 @@ class int_range: r""" Return the (sorted) list of integers represented by this object. - OUTPUT: - - A list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -643,9 +639,7 @@ class int_range: r""" Return an iterator over the intervals. - OUTPUT: - - iterator + OUTPUT: iterator EXAMPLES:: @@ -667,9 +661,7 @@ class int_range: r""" Return the number of integers represented by this object. - OUTPUT: - - Python integer + OUTPUT: Python integer EXAMPLES:: @@ -697,9 +689,7 @@ class int_range: - ``right`` -- an instance of ``int_range`` - OUTPUT: - - An instance of ``int_range`` + OUTPUT: an instance of ``int_range`` .. NOTE:: @@ -725,11 +715,9 @@ class int_range: INPUT: - - ``right`` -- an instance of ``int_range``. - - OUTPUT: + - ``right`` -- an instance of ``int_range`` - An instance of ``int_range``. + OUTPUT: an instance of ``int_range`` .. NOTE:: @@ -757,11 +745,9 @@ class int_range: INPUT: - - ``right`` -- an instance of ``int_range``. - - OUTPUT: + - ``right`` -- an instance of ``int_range`` - An instance of ``int_range``. + OUTPUT: an instance of ``int_range`` EXAMPLES:: @@ -787,7 +773,7 @@ def test(n, m, R, c=2): - ``n`` -- integer - ``m`` -- integer - ``R`` -- ring - - ``c`` -- integer (default:2) + - ``c`` -- integer (default: 2) EXAMPLES:: diff --git a/src/sage/matrix/symplectic_basis.py b/src/sage/matrix/symplectic_basis.py index bc2e9de7687..47dc053a9ce 100644 --- a/src/sage/matrix/symplectic_basis.py +++ b/src/sage/matrix/symplectic_basis.py @@ -16,7 +16,7 @@ * `f_i M {f_j}^t = 0` for all `i, j`; * `e_i M {f_j}^t = 0` for all `i` not equal `j`; -and such that the non-zero terms +and such that the nonzero terms * `e_i M {f_i}^t` are "as nice as possible": 1 over fields, or integers satisfying divisibility properties otherwise. @@ -292,7 +292,7 @@ def symplectic_basis_over_field(M): fs = [] pivot = 0 while pivot < n: - # find non-zero element in row + # find nonzero element in row found_i = None for i in range(pivot, n): if E[pivot, i] != 0: @@ -312,7 +312,7 @@ def symplectic_basis_over_field(M): E.rescale_col(pivot, v) B.rescale_row(pivot, v) - # use non-zero element to clean row pivot + # use nonzero element to clean row pivot for i in range(pivot+2, n): v = - E[i, pivot] / E[pivot+1, pivot] if v != 0: @@ -320,7 +320,7 @@ def symplectic_basis_over_field(M): E.add_multiple_of_column(i, pivot+1, v) B.add_multiple_of_row(i, pivot+1, v) - # use non-zero element to clean row pivot+1 + # use nonzero element to clean row pivot+1 for i in range(pivot+2, n): v = - E[i, pivot+1] / E[pivot, pivot+1] if v != 0: @@ -506,7 +506,7 @@ def symplectic_basis_over_ZZ(M): continue _inplace_move_to_positive_pivot(E, found[0], found[1], B, pivot) - # use non-zero element to clean row pivot + # use nonzero element to clean row pivot all_zero = True u = E[pivot+1, pivot] for i in range(pivot+2, n): @@ -517,7 +517,7 @@ def symplectic_basis_over_ZZ(M): E.add_multiple_of_column(i, pivot+1, v) B.add_multiple_of_row(i, pivot+1, v) - # use non-zero element to clean row pivot+1 + # use nonzero element to clean row pivot+1 u = E[pivot, pivot+1] for i in range(pivot+2, n): v, r = (-E[i, pivot+1]).quo_rem(u) diff --git a/src/sage/matroids/basis_exchange_matroid.pyx b/src/sage/matroids/basis_exchange_matroid.pyx index 2e57bb00fdc..a3c4c897d16 100644 --- a/src/sage/matroids/basis_exchange_matroid.pyx +++ b/src/sage/matroids/basis_exchange_matroid.pyx @@ -146,7 +146,7 @@ cdef class BasisExchangeMatroid(Matroid): sage: from sage.matroids.advanced import * sage: M = BasisExchangeMatroid(groundset=[1, 2, 3], rank=2) - sage: TestSuite(M).run(skip="_test_pickling") + sage: TestSuite(M).run(skip='_test_pickling') .. NOTE:: @@ -199,7 +199,7 @@ cdef class BasisExchangeMatroid(Matroid): - ``mapping`` -- a Python object such that ``mapping[e]`` is the new label of `e` - OUTPUT: ``None`` + OUTPUT: none .. NOTE:: @@ -805,7 +805,7 @@ cdef class BasisExchangeMatroid(Matroid): - ``F`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - OUTPUT: integer; the corank of ``F`` + OUTPUT: integer; the corank of `F` EXAMPLES:: @@ -1503,6 +1503,8 @@ cdef class BasisExchangeMatroid(Matroid): - ``k`` -- integer (optional); if specified, return the size-`k` independent sets of the matroid + OUTPUT: :class:`SetSystem` + EXAMPLES:: sage: M = matroids.catalog.Fano() @@ -2001,7 +2003,7 @@ cdef class BasisExchangeMatroid(Matroid): INPUT: - ``other`` -- matroid - - ``morphism`` -- a dictionary mapping the groundset of ``self`` to + - ``morphism`` -- dictionary mapping the groundset of ``self`` to the groundset of ``other`` OUTPUT: boolean diff --git a/src/sage/matroids/basis_matroid.pyx b/src/sage/matroids/basis_matroid.pyx index 5ae38178df6..f9710eaac7c 100644 --- a/src/sage/matroids/basis_matroid.pyx +++ b/src/sage/matroids/basis_matroid.pyx @@ -133,7 +133,6 @@ cdef class BasisMatroid(BasisExchangeMatroid): 2 sage: M1.is_valid() False - """ def __init__(self, M=None, groundset=None, bases=None, nonbases=None, rank=None): """ @@ -845,7 +844,7 @@ cdef class BasisMatroid(BasisExchangeMatroid): INPUT: - - ``other`` -- BasisMatroid + - ``other`` -- basisMatroid - ``morphism`` -- dictionary with sends each element of the groundset of this matroid to a distinct element of the groundset of ``other`` diff --git a/src/sage/matroids/circuit_closures_matroid.pyx b/src/sage/matroids/circuit_closures_matroid.pyx index 4d45022484b..7dd29ee8143 100644 --- a/src/sage/matroids/circuit_closures_matroid.pyx +++ b/src/sage/matroids/circuit_closures_matroid.pyx @@ -90,7 +90,7 @@ cdef class CircuitClosuresMatroid(Matroid): - ``M`` -- matroid (default: ``None``) - ``groundset`` -- groundset of a matroid (default: ``None``) - - ``circuit_closures`` -- dict (default: ``None``); the collection of + - ``circuit_closures`` -- dictionary (default: ``None``); the collection of circuit closures of a matroid presented as a dictionary whose keys are ranks, and whose values are sets of circuit closures of the specified rank diff --git a/src/sage/matroids/constructor.py b/src/sage/matroids/constructor.py index 38541523caa..a71674e2987 100644 --- a/src/sage/matroids/constructor.py +++ b/src/sage/matroids/constructor.py @@ -166,44 +166,43 @@ def Matroid(groundset=None, data=None, **kwds): INPUT: - - ``groundset`` -- (optional) If provided, the groundset of the - matroid. Otherwise, the function attempts to determine a groundset - from the data. + - ``groundset`` -- (optional) the groundset of the matroid; if not + provided, the function attempts to determine a groundset from the data Exactly one of the following inputs must be given (where ``data`` must be a positional argument and anything else must be a keyword argument): - ``data`` -- a graph or a matrix or a RevLex-Index string or a list - of independent sets containing all bases or a matroid. - - ``bases`` -- The list of bases (maximal independent sets) of the - matroid. - - ``independent_sets`` -- The list of independent sets of the matroid. - - ``circuits`` -- The list of circuits of the matroid. - - ``nonspanning_circuits`` -- The list of nonspanning circuits of the - matroid. - - ``flats`` -- The dictionary, list, or lattice of flats of the matroid. - - ``graph`` -- A graph, whose edges form the elements of the matroid. - - ``matrix`` -- A matrix representation of the matroid. - - ``reduced_matrix`` -- A reduced representation of the matroid: if + of independent sets containing all bases or a matroid + - ``bases`` -- the list of bases (maximal independent sets) of the + matroid + - ``independent_sets`` -- the list of independent sets of the matroid + - ``circuits`` -- the list of circuits of the matroid + - ``nonspanning_circuits`` -- the list of nonspanning circuits of the + matroid + - ``flats`` -- the dictionary, list, or lattice of flats of the matroid + - ``graph`` -- a graph, whose edges form the elements of the matroid + - ``matrix`` -- a matrix representation of the matroid + - ``reduced_matrix`` -- a reduced representation of the matroid: if ``reduced_matrix = A`` then the matroid is represented by `[I\ \ A]` where `I` is an - appropriately sized identity matrix. - - ``morphism`` -- A morphism representation of the matroid. - - ``reduced_morphism`` -- A reduced morphism representation of the matroid. - - ``rank_function`` -- A function that computes the rank of each subset. - Can only be provided together with a groundset. - - ``circuit_closures`` -- Either a list of tuples ``(k, C)`` with ``C`` + appropriately sized identity matrix + - ``morphism`` -- a morphism representation of the matroid + - ``reduced_morphism`` -- a reduced morphism representation of the matroid + - ``rank_function`` -- a function that computes the rank of each subset; + can only be provided together with a groundset + - ``circuit_closures`` -- either a list of tuples ``(k, C)`` with ``C`` the closure of a circuit, and ``k`` the rank of ``C``, or a dictionary - ``D`` with ``D[k]`` the set of closures of rank-``k`` circuits. - - ``revlex`` -- the encoding as a string of ``0`` and ``*`` symbols. - Used by [Mat2012]_ and explained in [MMIB2012]_. - - ``matroid`` -- An object that is already a matroid. Useful only with the - ``regular`` option. + ``D`` with ``D[k]`` the set of closures of rank-``k`` circuits + - ``revlex`` -- the encoding as a string of ``0`` and ``*`` symbols; + used by [Mat2012]_ and explained in [MMIB2012]_ + - ``matroid`` -- an object that is already a matroid; useful only with the + ``regular`` option Further options: - - ``regular`` -- (default: ``False``) boolean. If ``True``, + - ``regular`` -- boolean (default: ``False``); if ``True``, output a :class:`RegularMatroid ` instance such that, *if* the input defines a valid regular matroid, then @@ -212,10 +211,10 @@ def Matroid(groundset=None, data=None, **kwds): - ``ring`` -- any ring. If provided, and the input is a ``matrix`` or ``reduced_matrix``, output will be a linear matroid over the ring or field ``ring``. - - ``field`` -- any field. Same as ``ring``, but only fields are allowed. - - ``check`` -- (default: ``True``) boolean. If ``True`` and - ``regular`` is true, the output is checked to make sure it is a valid - regular matroid. + - ``field`` -- any field. Same as ``ring``, but only fields are allowed + - ``check`` -- boolean (default: ``True``); if ``True`` and + ``regular`` is ``True``, the output is checked to make sure it is a valid + regular matroid .. WARNING:: @@ -658,7 +657,7 @@ def Matroid(groundset=None, data=None, **kwds): Only the ``0`` symbols really matter, any symbol can be used instead of ``*``: - sage: Matroid("abcdefg", revlex="0++++++++0++++0+++++0+--++----+--++", rank=4) + sage: Matroid("abcdefg", revlex='0++++++++0++++0+++++0+--++----+--++', rank=4) Matroid of rank 4 on 7 elements with 31 bases It is checked that the input makes sense (but not that it @@ -742,7 +741,7 @@ def Matroid(groundset=None, data=None, **kwds): Traceback (most recent call last): ... TypeError: no input data given for Matroid() - sage: Matroid("abc", bases=["abc"], foo="bar") + sage: Matroid("abc", bases=["abc"], foo='bar') Traceback (most recent call last): ... TypeError: ...Matroid() got an unexpected keyword argument 'foo' @@ -762,7 +761,7 @@ def Matroid(groundset=None, data=None, **kwds): Traceback (most recent call last): ... TypeError: for rank functions, the groundset needs to be specified - sage: Matroid(matroid="rubbish") + sage: Matroid(matroid='rubbish') Traceback (most recent call last): ... TypeError: input 'rubbish' is not a matroid diff --git a/src/sage/matroids/database_collections.py b/src/sage/matroids/database_collections.py index 81b99a24d87..b5175e0b3d7 100644 --- a/src/sage/matroids/database_collections.py +++ b/src/sage/matroids/database_collections.py @@ -22,27 +22,25 @@ # **************************************************************************** -def AllMatroids(n, r=None, type="all"): +def AllMatroids(n, r=None, type='all'): r""" - Return an iterator over all matroids of certain number of elements (and, - optionally, of specific rank and type). + Iterate over all matroids of certain number of elements (and, optionally, + of specific rank and type). INPUT: - ``n`` -- integer; the number of elements of the matroids - - ``r`` -- integer (optional); the rank of the matroids; `0 \le r \le n` - - ``type`` -- string (default: ``'all'``); the type of the matroids; must + - ``r`` -- integer (optional); the rank of the matroids (`0 \le r \le n`) + - ``type`` -- string (default: ``'all'``); the type of the matroids. Must be one of the following: * ``'all'`` -- all matroids; available: (n=0-9), (n=0-12, r=0-2), (n=0-11, r=3) - * ``'unorientable'`` -- all unorientable matroids; the rank ``r`` must be + * ``'unorientable'`` -- all unorientable matroids; the rank `r` must be specified; available: (n=7-11, r=3), (n=7-9, r=4) * any other type for which there exists an ``is_type`` method; availability same as for ``'all'`` - OUTPUT: an iterator over matroids - EXAMPLES:: sage: for M in matroids.AllMatroids(2): # optional - matroid_database @@ -54,7 +52,7 @@ def AllMatroids(n, r=None, type="all"): :: - sage: for M in matroids.AllMatroids(5, 3, "simple"): # optional - matroid_database + sage: for M in matroids.AllMatroids(5, 3, 'simple'): # optional - matroid_database ....: M simple_n05_r03_#0: Matroid of rank 3 on 5 elements with 10 bases simple_n05_r03_#1: Matroid of rank 3 on 5 elements with 9 bases @@ -64,7 +62,7 @@ def AllMatroids(n, r=None, type="all"): :: sage: # optional - matroid_database - sage: for M in matroids.AllMatroids(4, type="paving"): + sage: for M in matroids.AllMatroids(4, type='paving'): ....: M paving_n04_r00_#0: Matroid of rank 0 on 4 elements with 1 bases paving_n04_r01_#0: Matroid of rank 1 on 4 elements with 4 bases @@ -86,18 +84,18 @@ def AllMatroids(n, r=None, type="all"): ....: M Traceback (most recent call last): ... - ValueError: (n=10, r=4, type="all") is not available in the database + ValueError: (n=10, r=4, type='all') is not available in the database sage: for M in matroids.AllMatroids(12, 3, "unorientable"): ....: M Traceback (most recent call last): ... - ValueError: (n=12, r=3, type="unorientable") is not available in the database - sage: for M in matroids.AllMatroids(8, type="unorientable"): + ValueError: (n=12, r=3, type='unorientable') is not available in the database + sage: for M in matroids.AllMatroids(8, type='unorientable'): ....: M Traceback (most recent call last): ... ValueError: The rank needs to be specified for type "unorientable" - sage: for M in matroids.AllMatroids(6, type="nice"): + sage: for M in matroids.AllMatroids(6, type='nice'): ....: M Traceback (most recent call last): ... @@ -227,7 +225,7 @@ def AllMatroids(n, r=None, type="all"): def OxleyMatroids(): """ - Return an iterator over Oxley's matroid collection. + Iterate over Oxley's matroid collection. EXAMPLES:: @@ -277,7 +275,7 @@ def OxleyMatroids(): def BrettellMatroids(): """ - Return an iterator over Brettell's matroid collection. + Iterate over Brettell's matroid collection. EXAMPLES:: @@ -326,7 +324,7 @@ def BrettellMatroids(): def VariousMatroids(): """ - Return an iterator over various other named matroids. + Iterate over various other named matroids. EXAMPLES:: diff --git a/src/sage/matroids/database_matroids.py b/src/sage/matroids/database_matroids.py index e964ee4836c..b2c6ca5e055 100644 --- a/src/sage/matroids/database_matroids.py +++ b/src/sage/matroids/database_matroids.py @@ -1776,12 +1776,12 @@ def Wheel(r, field=None, ring=None, groundset=None): INPUT: - - ``r`` -- a positive integer; the rank of the desired matroid + - ``r`` -- positive integer; the rank of the matroid - ``ring`` -- any ring; if provided, output will be a linear matroid over the ring or field ``ring``. If the ring is `\ZZ`, then output will be a regular matroid. - ``field`` -- any field; same as ``ring``, but only fields are allowed - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: the rank-`r` wheel matroid, represented as a regular matroid @@ -1853,8 +1853,8 @@ def Whirl(r, groundset=None): INPUT: - - ``r`` -- a positive integer; the rank of the desired matroid. - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``r`` -- positive integer; the rank of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: the rank-`r` whirl matroid, represented as a ternary matroid @@ -1924,10 +1924,10 @@ def Uniform(r, n, groundset=None): INPUT: - - ``r`` -- a nonnegative integer; the rank of the uniform matroid - - ``n`` -- a nonnegative integer; the number of elements of the uniform + - ``r`` -- nonnegative integer; the rank of the uniform matroid + - ``n`` -- nonnegative integer; the number of elements of the uniform matroid - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: the uniform matroid `U_{r,n}` @@ -1968,19 +1968,19 @@ def Uniform(r, n, groundset=None): def PG(n, q, x=None, groundset=None): """ - Return the projective geometry of dimension ``n`` over the finite field - of order ``q``. + Return the projective geometry of dimension `n` over the finite field + of order `q`. INPUT: - - ``n`` -- a positive integer; the dimension of the projective space. This + - ``n`` -- positive integer; the dimension of the projective space. This is one less than the rank of the resulting matroid. - - ``q`` -- a positive integer that is a prime power; the order of the + - ``q`` -- positive integer that is a prime power; the order of the finite field - - ``x`` -- a string (default: ``None``); the name of the generator of a + - ``x`` -- string (default: ``None``); the name of the generator of a non-prime field, used for non-prime fields. If not supplied, ``'x'`` is used. - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: a linear matroid whose elements are the points of `PG(n, q)` @@ -2019,14 +2019,14 @@ def AG(n, q, x=None, groundset=None): INPUT: - - ``n`` -- a positive integer; the dimension of the projective space. This + - ``n`` -- positive integer; the dimension of the projective space. This is one less than the rank of the resulting matroid. - - ``q`` -- a positive integer that is a prime power; the order of the + - ``q`` -- positive integer that is a prime power; the order of the finite field - - ``x`` -- a string (default: ``None``); the name of the generator of a + - ``x`` -- string (default: ``None``); the name of the generator of a non-prime field, used for non-prime fields. If not supplied, ``'x'`` is used. - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: a linear matroid whose elements are the points of `AG(n, q)` @@ -2064,9 +2064,9 @@ def Z(r, t=True, groundset=None): INPUT: - - ``r`` -- an integer (`r \ge 3`); the rank of the spike + - ``r`` -- integer (`r \ge 3`); the rank of the spike - ``t`` -- boolean (default: ``True``); whether the spike is tipped - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: matroid; the unique rank-`r` binary spike (tipped or tipless) @@ -2168,11 +2168,11 @@ def Spike(r, t=True, C3=[], groundset=None): INPUT: - - ``r`` -- an integer (`r \ge 3`); the rank of the spike + - ``r`` -- integer (`r \ge 3`); the rank of the spike - ``t`` -- boolean (default: ``True``); whether the spike is tipped - - ``C3`` -- a list (default: ``[]``); a list of extra nonspanning circuits. - The default (i.e. the empty list) results in a free `r`-spike - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``C3`` -- list (default: ``[]``); a list of extra nonspanning circuits. + The default (i.e. the empty list) results in a free `r`-spike. + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: matroid; a rank-`r` spike (tipped or tipless) @@ -2289,8 +2289,8 @@ def Theta(n, groundset=None): INPUT: - - ``n`` -- an integer (`n \ge 2`); the rank of the matroid - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``n`` -- integer (`n \ge 2`); the rank of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: matroid (`\Theta_n`) @@ -2362,8 +2362,8 @@ def Psi(r, groundset=None): INPUT: - - ``r`` -- an integer (`r \ge 3`); the rank of the matroid - - ``groundset`` -- a string (optional); the groundset of the matroid + - ``r`` -- integer (`r \ge 3`); the rank of the matroid + - ``groundset`` -- string (optional); the groundset of the matroid OUTPUT: matroid (`\Psi_r`) @@ -3022,7 +3022,7 @@ def KR9(groundset=None): Return the matroid `KR9`. An excluded minor for `G`-representable matroids (and - `GF(5)`-representable matroids.) In a `DY`-equivalence class of `4` + `GF(5)`-representable matroids). In a `DY`-equivalence class of `4` matroids. Has a :func:`KP8 `-minor (delete `8`). UPF is `GF(4)`. @@ -3057,7 +3057,7 @@ def KQ9(groundset=None): Return the matroid `KQ9`. An excluded minor for `G`-representable matroids (and - `GF(5)`-representable matroids.) Has a + `GF(5)`-representable matroids). Has a :func:`TQ8 `-minor` (delete `6`) and a :func:`KP8 `-minor (delete `8`). UPF is `GF(4)`. @@ -4511,7 +4511,7 @@ def VP14(groundset=None): def FV14(groundset=None): """ - Return the matroid `FV14` + Return the matroid `FV14`. An excluded minor for `P_4`-representable matroids. Not self-dual. UPF is `PT`. @@ -5187,10 +5187,10 @@ def CompleteGraphic(n, groundset=None): INPUT: - - ``n`` -- an integer, the number of vertices of the underlying complete - graph. + - ``n`` -- integer; the number of vertices of the underlying complete + graph - OUTPUT: The graphic matroid associated with the `n`-vertex complete graph. + OUTPUT: the graphic matroid associated with the `n`-vertex complete graph. This matroid has rank `n - 1`. EXAMPLES:: @@ -5231,16 +5231,16 @@ def _rename_and_relabel(M, name=None, groundset=None): INPUT: - - ``M`` -- a matroid - - ``name`` -- a string (optional) - - ``groundset`` -- a string (optional) + - ``M`` -- matroid + - ``name`` -- string (optional) + - ``groundset`` -- string (optional) OUTPUT: matroid """ if groundset is not None: if len(groundset) != len(M.groundset()): raise ValueError( - "The groundset should be of size %s (%s given)." % + "the groundset should be of size %s (%s given)" % (len(M.groundset()), len(groundset)) ) M = M.relabel(dict(zip(M.groundset(), groundset))) diff --git a/src/sage/matroids/extension.pyx b/src/sage/matroids/extension.pyx index d73b4581674..778e6d6ef70 100644 --- a/src/sage/matroids/extension.pyx +++ b/src/sage/matroids/extension.pyx @@ -51,11 +51,10 @@ cdef class CutNode: hyperplanes and closing the set to become a linear subclass again, and for adding a hyperplane to the set of *forbidden* hyperplanes, and similarly closing that set. - """ def __cinit__(self, MC, N=None): """ - Internal data structure init + Internal data structure init. EXAMPLES:: @@ -187,7 +186,7 @@ cdef class LinearSubclassesIter: INPUT: - - ``MC`` -- a member of class LinearSubclasses. + - ``MC`` -- a member of class LinearSubclasses EXAMPLES:: @@ -258,17 +257,15 @@ cdef class LinearSubclasses: INPUT: - - ``M`` -- a matroid. - - ``line_length`` -- (default: ``None``) an integer. + - ``M`` -- matroid + - ``line_length`` -- integer (default: ``None``) - ``subsets`` -- (default: ``None``) a set of subsets of the groundset of - ``M``. + ``M`` - ``splice`` -- (default: ``None``) a matroid `N` such that for some `e \in E(N)` and some `f \in E(M)`, we have - `N\setminus e= M\setminus f`. + `N\setminus e= M\setminus f` - OUTPUT: - - An enumerator for the linear subclasses of M. + OUTPUT: an enumerator for the linear subclasses of M If ``line_length`` is not ``None``, the enumeration is restricted to linear subclasses ``mc`` so containing at least one of each set of @@ -416,13 +413,13 @@ cdef class MatroidExtensions(LinearSubclasses): INPUT: - - ``M`` -- a matroid + - ``M`` -- matroid - ``e`` -- an element - - ``line_length`` (default: ``None``) -- an integer - - ``subsets`` (default: ``None``) -- a set of subsets of the groundset of + - ``line_length`` -- integer (default: ``None``) + - ``subsets`` -- (default: ``None``) a set of subsets of the groundset of ``M`` - ``splice`` -- a matroid `N` such that for some `f \in E(M)`, we have - `N\setminus e= M\setminus f`. + `N\setminus e= M\setminus f` OUTPUT: diff --git a/src/sage/matroids/flats_matroid.pyx b/src/sage/matroids/flats_matroid.pyx index dce9d8756fa..9c6a3c76aeb 100644 --- a/src/sage/matroids/flats_matroid.pyx +++ b/src/sage/matroids/flats_matroid.pyx @@ -42,7 +42,7 @@ cdef class FlatsMatroid(Matroid): - ``M`` -- matroid (default: ``None``) - ``groundset`` -- list (default: ``None``); the groundset of the matroid - - ``flats`` -- (default: ``None``); the dictionary of the lists of flats + - ``flats`` -- (default: ``None``) the dictionary of the lists of flats (indexed by their rank), or the list of all flats, or the lattice of flats of the matroid @@ -226,7 +226,6 @@ cdef class FlatsMatroid(Matroid): - ``other`` -- matroid - ``certificate`` -- boolean (default: ``False``) - OUTPUT: boolean, and, if ``certificate=True``, a dictionary giving the isomorphism or ``None`` diff --git a/src/sage/matroids/graphic_matroid.pyx b/src/sage/matroids/graphic_matroid.pyx index 2f6287fba8d..a01cef13fe3 100644 --- a/src/sage/matroids/graphic_matroid.pyx +++ b/src/sage/matroids/graphic_matroid.pyx @@ -186,7 +186,7 @@ cdef class GraphicMatroid(Matroid): groundset_set = frozenset(groundset) # if the provided groundset is incomplete, it gets overwritten - # invalidate `None` as label + # invalidate ``None`` as label if None in groundset_set or len(groundset_set) != G.num_edges(): groundset = range(G.num_edges()) groundset_set = frozenset(groundset) @@ -501,8 +501,8 @@ cdef class GraphicMatroid(Matroid): INPUT: - ``N`` -- matroid - - ``certificate`` -- (default: ``False``) if ``True``, returns the - certificate isomorphism from the minor of ``self`` to ``N`` + - ``certificate`` -- boolean (default: ``False``); if ``True``, returns + the certificate isomorphism from the minor of ``self`` to ``N`` OUTPUT: @@ -812,7 +812,7 @@ cdef class GraphicMatroid(Matroid): - ``X`` -- an iterable container of groundset elements OUTPUT: ``frozenset`` instance containing a subset of ``X``; - a :class:`ValueError` is raised if the set contains no circuit + a :exc:`ValueError` is raised if the set contains no circuit EXAMPLES:: @@ -1364,8 +1364,8 @@ cdef class GraphicMatroid(Matroid): each extension - ``vertices`` -- (optional) a set of vertices over which the extension may be taken - - ``simple`` -- (default: ``False``) if true, extensions by loops and - parallel elements are not taken + - ``simple`` -- boolean (default: ``False``); if ``True``, extensions + by loops and parallel elements are not taken OUTPUT: @@ -1440,7 +1440,7 @@ cdef class GraphicMatroid(Matroid): - ``v`` -- (optional) the name of the new vertex after splitting - ``X`` -- (optional) a list of the matroid elements corresponding to edges incident to ``u`` that move to the new vertex after splitting - - ``element`` -- (optional) The name of the newly added element + - ``element`` -- (optional) the name of the newly added element OUTPUT: @@ -1573,7 +1573,7 @@ cdef class GraphicMatroid(Matroid): - ``vertices`` -- (optional) the vertices to be split - ``v`` -- (optional) the name of the new vertex - ``element`` -- (optional) the name of the new element - - ``cosimple`` -- (default: ``False``) if true, coextensions + - ``cosimple`` -- boolean (default: ``False``); if ``True``, coextensions by a coloop or series elements will not be taken OUTPUT: diff --git a/src/sage/matroids/lean_matrix.pyx b/src/sage/matroids/lean_matrix.pyx index 5863a58d4eb..f7051f45c92 100644 --- a/src/sage/matroids/lean_matrix.pyx +++ b/src/sage/matroids/lean_matrix.pyx @@ -494,13 +494,13 @@ cdef class LeanMatrix: cdef shifting_all(self, P_rows, P_cols, Q_rows, Q_cols, int m): r""" Given a partial matrix `M`. If the submatrix `M` using rows - `P_rows` columns `P_cols` and submatrix using rows `Q_rows` columns - `Q_cols` can be extended to a ``m``-separator, then it returns - `True, E`, where `E` is a ``m``-separator. Otherwise it returns - `False, None` + ``P_rows`` columns ``P_cols`` and submatrix using rows ``Q_rows`` + columns ``Q_cols`` can be extended to an ``m``-separator, then it + returns ``True, E``, where `E` is an ``m``-separator. Otherwise it + returns ``False, None``. - `P_rows` and `Q_rows` must be disjoint subsets of row indices. - `P_cols` and `Q_cols` must be disjoint subsets of column indices. + ``P_rows`` and ``Q_rows`` must be disjoint subsets of row indices. + ``P_cols`` and ``Q_cols`` must be disjoint subsets of column indices. Internal version does not verify the above properties hold. @@ -514,8 +514,9 @@ cdef class LeanMatrix: OUTPUT: - - `False, None` -- if the input submatrices does not induce a `m``-separator. - - `True, E` -- if there exist a ``m``-separator ``E``. + - ``False, None`` -- if the input submatrices does not induce an + ``m``-separator + - ``True, E`` -- if there exists an ``m``-separator ``E`` """ for z in range(self.ncols()): if z in P_cols+Q_cols: @@ -540,9 +541,9 @@ cdef class LeanMatrix: optional column `z2` attached. Let `E_2` be the submatrix using rows `U_2` and columns `V_1` with optional column `z1` attached. - If `E_1` and `E_2` can be extended to a ``m``-separator, then it - returns `True, E`, where `E` is a ``m``-separator. Otherwise it - returns `False, None` + If `E_1` and `E_2` can be extended to an ``m``-separator, then it + returns ``True, E``, where `E` is an ``m``-separator. Otherwise it + returns ``False, None``. `U_1` and `U_2` must be disjoint subsets of row indices. `V_1` and `V_2` must be disjoint subsets of column indices. @@ -555,14 +556,16 @@ cdef class LeanMatrix: - ``V_2`` -- list of column indices of the first submatrix - ``U_2`` -- list of row indices of the second submatrix - ``V_1`` -- list of column indices of the second submatrix - - ``z2`` -- start by add an additional column with index `z2` to `V_2` - - ``z1`` -- start by add an additional column with index `z1` to `V_1` + - ``z2`` -- start by add an additional column with index `z2` to `V_2` + - ``z1`` -- start by add an additional column with index `z1` to `V_1` - ``m`` -- separation size OUTPUT: - - `False, None` -- if the input submatrices does not induce a `m``-separator. - - `True, (X,Y)` -- row indices `X` and column indices `Y` defines a ``m``-separator. + - ``False, None`` -- if the input submatrices does not induce an + ``m``-separator + - ``True, (X,Y)`` -- row indices `X` and column indices `Y` defines an + ``m``-separator """ # make copy because of destructive updates cdef list X_1 = list(U_1) @@ -644,8 +647,8 @@ cdef class GenericMatrix(LeanMatrix): - ``nrows`` -- number of rows - ``ncols`` -- number of columns - ``M`` -- (default: ``None``) a ``Matrix`` or ``GenericMatrix`` of - dimensions at most ``m*n``. - - ``ring`` -- (default: ``None``) a Sage ring. + dimensions at most ``m*n`` + - ``ring`` -- (default: ``None``) a Sage ring .. NOTE:: @@ -935,11 +938,11 @@ cdef class BinaryMatrix(LeanMatrix): INPUT: - - ``m`` -- Number of rows. - - ``n`` -- Number of columns. - - ``M`` -- (default: ``None``) Matrix or BinaryMatrix instance. + - ``m`` -- number of rows + - ``n`` -- number of columns + - ``M`` -- (default: ``None``) ``Matrix`` or ``BinaryMatrix`` instance. Assumption: dimensions of ``M`` are at most ``m`` by ``n``. - - ``ring`` -- (default: ``None``) ignored. + - ``ring`` -- (default: ``None``) ignored EXAMPLES:: @@ -1018,7 +1021,7 @@ cdef class BinaryMatrix(LeanMatrix): def __repr__(self): r""" - Return representation string + Return representation string. EXAMPLES:: @@ -1544,11 +1547,11 @@ cdef class TernaryMatrix(LeanMatrix): INPUT: - - ``m`` -- Number of rows. - - ``n`` -- Number of columns. + - ``m`` -- number of rows + - ``n`` -- number of columns - ``M`` -- (default: ``None``) ``Matrix`` or ``TernaryMatrix`` instance. Assumption: dimensions of ``M`` are at most ``m`` by ``n``. - - ``ring`` -- (default: ``None``) ignored. + - ``ring`` -- (default: ``None``) ignored EXAMPLES:: @@ -1646,7 +1649,7 @@ cdef class TernaryMatrix(LeanMatrix): def __repr__(self): r""" - Return representation string + Return representation string. EXAMPLES:: @@ -2101,13 +2104,13 @@ cdef class QuaternaryMatrix(LeanMatrix): INPUT: - - ``m`` -- Number of rows - - ``n`` -- Number of columns - - ``M`` -- (default: ``None``) A QuaternaryMatrix or LeanMatrix or (Sage) - Matrix instance. If not given, new matrix will be filled with zeroes. - Assumption: ``M`` has dimensions at most ``m`` times ``n``. - - ``ring`` -- (default: ``None``) A copy of GF(4). Useful for specifying - generator name. + - ``m`` -- number of rows + - ``n`` -- number of columns + - ``M`` -- (default: ``None``) ``QuaternaryMatrix`` or ``LeanMatrix`` or + (Sage) ``Matrix`` instance. If not given, new matrix will be filled with + zeroes. Assumption: ``M`` has dimensions at most ``m`` times ``n``. + - ``ring`` -- (default: ``None``) a copy of GF(4); useful for specifying + generator name EXAMPLES:: @@ -2222,7 +2225,7 @@ cdef class QuaternaryMatrix(LeanMatrix): def __repr__(self): r""" - Return representation string + Return representation string. EXAMPLES:: diff --git a/src/sage/matroids/linear_matroid.pyx b/src/sage/matroids/linear_matroid.pyx index ebb1bf2a711..0310b8c2cd3 100644 --- a/src/sage/matroids/linear_matroid.pyx +++ b/src/sage/matroids/linear_matroid.pyx @@ -204,7 +204,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - ``matrix`` -- (default: ``None``) a matrix whose column vectors - represent the matroid. + represent the matroid - ``reduced_matrix`` -- (default: ``None``) a matrix `B` such that `[I\ \ B]` represents the matroid, where `I` is an identity matrix with the same number of rows as `B`. Only one of ``matrix`` and @@ -216,16 +216,14 @@ cdef class LinearMatroid(BasisExchangeMatroid): - ``ring`` -- (default: ``None``) the desired base ring of the matrix. If the base ring is different, an attempt will be made to create a new matrix with the correct base ring. - - ``keep_initial_representation`` -- (default: ``True``) decides whether + - ``keep_initial_representation`` -- boolean (default: ``True``); whether or not an internal copy of the input matrix should be preserved. This can help to see the structure of the matroid (e.g. in the case of graphic matroids), and makes it easier to look at extensions. However, the input matrix may have redundant rows, and sometimes it is desirable to store only a row-reduced copy. - OUTPUT: - - A ``LinearMatroid`` instance based on the data above. + OUTPUT: a ``LinearMatroid`` instance based on the data above .. NOTE:: @@ -496,9 +494,9 @@ cdef class LinearMatroid(BasisExchangeMatroid): the representation is such that a basis `B'` that maximally intersects `B` is an identity matrix. - - ``reduced`` -- (default: ``False``) when ``True``, return a reduced - matrix `D` (so `[I\ \ D]` is a representation of the matroid). - Otherwise return a full representation matrix. + - ``reduced`` -- boolean (default: ``False``); when ``True``, return a + reduced matrix `D` (so `[I\ \ D]` is a representation of the + matroid). Otherwise return a full representation matrix. - ``labels`` -- (default: ``None``) when ``True``, return additionally a list of column labels (if ``reduced=False``) or a list of row @@ -506,7 +504,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): The default setting, ``None``, will not return the labels for a full matrix, but will return the labels for a reduced matrix. - - ``order`` -- sequence or ``None`` or ``True`` (default: ``None``); + - ``order`` -- sequence or ``None`` or ``True`` (default: ``None``) - when a sequence, it should be an ordering of the groundset elements, and the columns (and, in case of a reduced @@ -526,7 +524,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): - ``(A, E)`` -- a full representation matrix ``A`` and a list ``E`` of column labels; or - ``(A, R, C)`` -- a reduced representation matrix and a list ``R`` of - row labels and a list ``C`` of column labels. + row labels and a list ``C`` of column labels If ``B == None`` and ``reduced == False`` and ``order == None`` then this method will always output the same matrix (except when @@ -697,14 +695,14 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``B`` -- (default: ``None``) If provided, first find a basis having - maximal intersection with ``B``. + - ``B`` -- (default: ``None``) if provided, first find a basis having + maximal intersection with ``B`` OUTPUT: - - ``R`` -- A list of row indices; corresponds to the currently used + - ``R`` -- list of row indices; corresponds to the currently used internal basis - - ``C`` -- A list of column indices; corresponds to the complement of + - ``C`` -- list of column indices; corresponds to the complement of the current internal basis EXAMPLES:: @@ -735,7 +733,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -804,7 +802,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -844,7 +842,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - ``other`` -- matroid; assumed to have the same base ring as ``self`` - - ``morphism`` -- a dictionary mapping the groundset of ``self`` to + - ``morphism`` -- dictionary mapping the groundset of ``self`` to the groundset of ``other`` OUTPUT: boolean @@ -1016,7 +1014,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - ``other`` -- matroid - - ``morphism`` -- A map from the groundset of ``self`` to the + - ``morphism`` -- a map from the groundset of ``self`` to the groundset of ``other``. See documentation of the :meth:`M.is_isomorphism() ` method for more on what is accepted as input. @@ -1091,14 +1089,14 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``other`` -- A ``LinearMatroid`` instance, of the same subclass as - ``self``. + - ``other`` -- a ``LinearMatroid`` instance, of the same subclass as + ``self`` OUTPUT: - ``None`` -- if the test is inconclusive; - ``True`` -- if the matroids were found to be field-isomorphic - - ``False`` -- if the matroids were found to be non-field-isomorphic. + - ``False`` -- if the matroids were found to be non-field-isomorphic .. NOTE:: @@ -1153,7 +1151,6 @@ cdef class LinearMatroid(BasisExchangeMatroid): :meth:`M.is_field_isomorphism() `, :meth:`M.is_field_equivalent() ` - EXAMPLES:: sage: M1 = matroids.Wheel(3) @@ -1328,9 +1325,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): - ``deletions`` is coindependent - ``contractions`` and ``deletions`` are disjoint. - OUTPUT: - - A matroid. + OUTPUT: matroid EXAMPLES:: @@ -1364,9 +1359,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): represented by `[-A^T\ \ I_2]` for appropriately sized identity matrices `I_1, I_2`. - OUTPUT: - - The dual matroid. + OUTPUT: the dual matroid EXAMPLES:: @@ -1400,13 +1393,11 @@ cdef class LinearMatroid(BasisExchangeMatroid): - ``k`` -- the length of the line minor - ``hyperlines`` -- (default: ``None``) a set of flats of codimension 2. Defaults to the set of all flats of codimension 2. - - ``certificate`` (default: ``False``); If ``True`` returns ``True, F``, - where ``F`` is a flat and ``self.minor(contractions=F)`` has a - `U_{2,k}` restriction or ``False, None``. + - ``certificate`` -- (default: ``False``) if ``True`` returns + ``True, F``, where ``F`` is a flat and ``self.minor(contractions=F)`` + has a `U_{2,k}` restriction or ``False, None`` - OUTPUT: - - Boolean or tuple. + OUTPUT: boolean or tuple EXAMPLES:: @@ -1499,8 +1490,8 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``e`` -- an element of the groundset. - - ``f`` -- an element of the groundset. + - ``e`` -- an element of the groundset + - ``f`` -- an element of the groundset ``e`` should be in the currently active basis, and ``f`` in the currently active cobasis. @@ -1772,7 +1763,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``F`` -- A flat of codimension 2 + - ``F`` -- a flat of codimension 2 - ``a``, ``b``, ``c``, ``d`` -- elements of the groundset OUTPUT: @@ -1817,7 +1808,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): - ``F`` -- a flat of codimension 2 - ``x`` -- an element outside ``F`` - - ``fundamentals`` -- a set of fundamental elements. + - ``fundamentals`` -- set of fundamental elements OUTPUT: @@ -1877,7 +1868,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): - ``x`` -- an element of the groundset - ``fundamentals`` -- a subset of the base ring - - ``hyperlines`` (optional) -- a set of flats of rank=full_rank-2 + - ``hyperlines`` -- (optional) a set of flats of ``rank=full_rank-2`` OUTPUT: boolean ``True`` if each cross ratio using ``x`` is an element of ``fundamentals``. If ``hyperlines`` is specified, then the method @@ -1924,11 +1915,11 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``element`` -- the name of the new element. + - ``element`` -- the name of the new element - ``col`` -- (default: ``None``) a column to be appended to - ``self.representation()``. Can be any iterable. + ``self.representation()``; can be any iterable - ``chain`` -- (default: ``None``) a dictionary that maps elements of - the groundset to elements of the base ring. + the groundset to elements of the base ring OUTPUT: @@ -2004,11 +1995,11 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``element`` -- the name of the new element. + - ``element`` -- the name of the new element - ``row`` -- (default: ``None``) a row to be appended to - ``self.representation()``. Can be any iterable. + ``self.representation()``; can be any iterable - ``cochain`` -- (default: ``None``) a dictionary that maps elements - of the groundset to elements of the base ring. + of the groundset to elements of the base ring OUTPUT: @@ -2092,9 +2083,9 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``element`` -- the name of the new element. - - ``chains`` -- a list of dictionaries, each of which maps elements of - the groundset to elements of the base ring. + - ``element`` -- the name of the new element + - ``chains`` -- list of dictionaries, each of which maps elements of + the groundset to elements of the base ring OUTPUT: @@ -2140,9 +2131,9 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``element`` -- the name of the new element. - - ``cochains`` -- a list of dictionaries, each of which maps elements - of the groundset to elements of the base ring. + - ``element`` -- the name of the new element + - ``cochains`` -- list of dictionaries, each of which maps elements + of the groundset to elements of the base ring OUTPUT: @@ -2252,9 +2243,9 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``F`` -- an independent set of elements. + - ``F`` -- an independent set of elements - ``fundamentals`` -- (default: ``None``) a set elements of the base - ring. + ring OUTPUT: @@ -2329,10 +2320,12 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``F`` -- (default: ``self.groundset()``) a subset of the groundset. - - ``simple`` -- (default: ``False``) boolean + - ``F`` -- (default: ``self.groundset()``) a subset of the groundset + + - ``simple`` -- boolean (default: ``False``) + - ``fundamentals`` -- (default: ``None``) a set elements of the base - ring. + ring OUTPUT: @@ -2429,10 +2422,12 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``F`` -- (default: ``self.groundset()``) a subset of the groundset. - - ``cosimple`` -- (default: ``False``) boolean + - ``F`` -- (default: ``self.groundset()``) a subset of the groundset + + - ``cosimple`` -- boolean (default: ``False``) + - ``fundamentals`` -- (default: ``None``) a set elements of the base - ring. + ring OUTPUT: @@ -2482,11 +2477,14 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - ``element`` -- (default: ``None``) the name of the new element of - the groundset. - - ``F`` -- (default: ``None``) a subset of the groundset. - - ``simple`` -- (default: ``False``) boolean + the groundset + + - ``F`` -- (default: ``None``) a subset of the groundset + + - ``simple`` -- boolean (default: ``False``) + - ``fundamentals`` -- (default: ``None``) a set elements of the base - ring. + ring OUTPUT: @@ -2550,11 +2548,14 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - ``element`` -- (default: ``None``) the name of the new element of - the groundset. - - ``F`` -- (default: ``None``) a subset of the groundset. - - ``cosimple`` -- (default: ``False``) boolean + the groundset + + - ``F`` -- (default: ``None``) a subset of the groundset + + - ``cosimple`` -- boolean (default: ``False``) + - ``fundamentals`` -- (default: ``None``) a set elements of the base - ring. + ring OUTPUT: @@ -2671,7 +2672,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``certificate`` -- (default: ``False``) boolean; if ``True``, + - ``certificate`` -- boolean (default: ``False``); if ``True``, then return ``True, None`` if the matroid is 3-connected, and ``False,`` `X` otherwise, where `X` is a `<3`-separation @@ -2750,7 +2751,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): INPUT: - - ``certificate`` -- (default: ``False``) boolean; if ``True``, + - ``certificate`` -- boolean (default: ``False``); if ``True``, then return ``True, None`` if the matroid is 4-connected, and ``False,`` `X` otherwise, where `X` is a `<4`-separation @@ -2938,7 +2939,7 @@ cdef class LinearMatroid(BasisExchangeMatroid): ....: [0, 0, 1, 1, 3]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U35") + sage: M.rename('U35') sage: loads(dumps(M)) U35 sage: M = Matroid(Matrix(GF(7), [[1, 0, 1], [1, 0, 1]])) @@ -3026,21 +3027,19 @@ cdef class BinaryMatroid(LinearMatroid): labels. When provided, must have the correct number of elements: the number of columns of ``matrix`` or the number of rows plus the number of columns of ``reduced_matrix``. - - ``ring`` -- (default: ``None``) ignored. - - ``keep_initial_representation`` -- (default: ``True``) decides whether + - ``ring`` -- (default: ``None``) ignored + - ``keep_initial_representation`` -- boolean (default: ``True``); whether or not an internal copy of the input matrix should be preserved. This can help to see the structure of the matroid (e.g. in the case of graphic matroids), and makes it easier to look at extensions. However, the input matrix may have redundant rows, and sometimes it is desirable to store only a row-reduced copy. - - ``basis`` -- (default: ``None``) When provided, this is an ordered + - ``basis`` -- (default: ``None``) when provided, this is an ordered subset of ``groundset``, such that the submatrix of ``matrix`` indexed by ``basis`` is an identity matrix. In this case, no row reduction takes place in the initialization phase. - OUTPUT: - - A :class:`BinaryMatroid` instance based on the data above. + OUTPUT: a :class:`BinaryMatroid` instance based on the data above .. NOTE:: @@ -3244,14 +3243,14 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) If provided, first find a basis having - maximal intersection with ``B``. + - ``B`` -- (default: ``None``) if provided, first find a basis having + maximal intersection with ``B`` OUTPUT: - - ``R`` -- A list of row indices; corresponds to the currently used + - ``R`` -- list of row indices; corresponds to the currently used internal basis - - ``C`` -- A list of column indices; corresponds to the complement of + - ``C`` -- list of column indices; corresponds to the complement of the current internal basis EXAMPLES:: @@ -3285,7 +3284,7 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -3325,7 +3324,7 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -3416,7 +3415,7 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - ``other`` -- matroid - - ``morphism`` -- a dictionary mapping the groundset of ``self`` to + - ``morphism`` -- dictionary mapping the groundset of ``self`` to the groundset of ``other`` OUTPUT: boolean @@ -3536,8 +3535,8 @@ cdef class BinaryMatroid(LinearMatroid): A tuple ``(d, b, Lm, L0, Lp, p0, p1, p2)``, with the following interpretation: - - ``d`` is the :meth:`bicycle dimension `. - - ``b`` is the :meth:`Brown invariant `. + - ``d`` -- the :meth:`bicycle dimension ` + - ``b`` -- the :meth:`Brown invariant ` - ``(Lm, L0, Lp)`` is the triple of lengths of the principal tripartition. - ``(p0, p1, p2)`` are the counts of edges in a characteristic graph of the matroid, whose vertices are the union of ``F_-`` and ``F_0`` @@ -3700,9 +3699,7 @@ cdef class BinaryMatroid(LinearMatroid): - Nothing - OUTPUT: - - An ordered partition. + OUTPUT: an ordered partition sage: from sage.matroids.advanced import * sage: M = matroids.catalog.R12() @@ -3730,7 +3727,7 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - - ``other`` -- a binary matroid. + - ``other`` -- a binary matroid OUTPUT: @@ -3775,9 +3772,7 @@ cdef class BinaryMatroid(LinearMatroid): - ``deletions`` is coindependent - ``contractions`` and ``deletions`` are disjoint. - OUTPUT: - - A matroid. + OUTPUT: matroid EXAMPLES:: @@ -3874,9 +3869,7 @@ cdef class BinaryMatroid(LinearMatroid): Since this is a linear matroid over the field `\GF{2}`, this is always the case. - OUTPUT: - - ``True``. + OUTPUT: ``True`` EXAMPLES:: @@ -3894,12 +3887,10 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. - - ``verify`` -- Ignored - - OUTPUT: + - ``randomized_tests`` -- ignored + - ``verify`` -- ignored - A binary matroid. + OUTPUT: a binary matroid ALGORITHM: @@ -3924,7 +3915,7 @@ cdef class BinaryMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. + - ``randomized_tests`` -- ignored OUTPUT: boolean @@ -3968,7 +3959,7 @@ cdef class BinaryMatroid(LinearMatroid): ....: [0, 0, 1, 1]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U34") + sage: M.rename('U34') sage: loads(dumps(M)) U34 sage: M = Matroid(Matrix(GF(2), [[1, 0, 1], [1, 0, 1]])) @@ -4065,8 +4056,8 @@ cdef class TernaryMatroid(LinearMatroid): labels. When provided, must have the correct number of elements: the number of columns of ``matrix`` or the number of rows plus the number of columns of ``reduced_matrix``. - - ``ring`` -- (default: ``None``) ignored. - - ``keep_initial_representation`` -- (default: ``True``) boolean. Decides + - ``ring`` -- (default: ``None``) ignored + - ``keep_initial_representation`` -- boolean (default: ``True``); decides whether or not an internal copy of the input matrix should be preserved. This can help to see the structure of the matroid (e.g. in the case of graphic matroids), and makes it easier to look at extensions. However, @@ -4077,9 +4068,7 @@ cdef class TernaryMatroid(LinearMatroid): by ``basis`` is an identity matrix. In this case, no row reduction takes place in the initialization phase. - OUTPUT: - - A ``TernaryMatroid`` instance based on the data above. + OUTPUT: a ``TernaryMatroid`` instance based on the data above .. NOTE:: @@ -4291,14 +4280,14 @@ cdef class TernaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) If provided, first find a basis having - maximal intersection with ``B``. + - ``B`` -- (default: ``None``) if provided, first find a basis having + maximal intersection with ``B`` OUTPUT: - - ``R`` -- A list of row indices; corresponds to the currently used + - ``R`` -- list of row indices; corresponds to the currently used internal basis - - ``C`` -- A list of column indices; corresponds to the complement of + - ``C`` -- list of column indices; corresponds to the complement of the current internal basis EXAMPLES:: @@ -4332,7 +4321,7 @@ cdef class TernaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -4372,7 +4361,7 @@ cdef class TernaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -4527,13 +4516,13 @@ cdef class TernaryMatroid(LinearMatroid): A tuple ``(d, c, L, La, Lb, Lc, p0, p1, p2, p3, p4, p5)``, with the following interpretation: - - ``d`` is the bicycle dimension. - - ``c`` is the character. + - ``d`` is the bicycle dimension + - ``c`` is the character - ``(L, La, Lb, Lc)`` is the triple of lengths of the principal - quadripartition. + quadripartition - ``(p0, ..., p5)`` counts of edges in a characteristic graph of the matroid whose vertex set is the groundset of the matroid, - restricted to the sets in the principal quadripartition. + restricted to the sets in the principal quadripartition EXAMPLES:: @@ -4674,12 +4663,12 @@ cdef class TernaryMatroid(LinearMatroid): INPUT: - - ``other`` -- a ternary matroid. + - ``other`` -- a ternary matroid OUTPUT: - ``True``, if ``self`` is isomorphic to ``other``; - - ``False``, if ``self`` is not isomorphic to ``other``; + - ``False``, if ``self`` is not isomorphic to ``other``; - ``None``, if the test is inconclusive EXAMPLES:: @@ -4715,9 +4704,7 @@ cdef class TernaryMatroid(LinearMatroid): - ``deletions`` is coindependent - ``contractions`` and ``deletions`` are disjoint. - OUTPUT: - - A matroid. + OUTPUT: matroid EXAMPLES:: @@ -4744,9 +4731,7 @@ cdef class TernaryMatroid(LinearMatroid): Since this is a linear matroid over the field `\GF{3}`, this is always the case. - OUTPUT: - - ``True``. + OUTPUT: ``True`` EXAMPLES:: @@ -4764,12 +4749,10 @@ cdef class TernaryMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. - - ``verify`` -- Ignored - - OUTPUT: + - ``randomized_tests`` -- ignored + - ``verify`` -- ignored - A binary matroid. + OUTPUT: a binary matroid ALGORITHM: @@ -4839,7 +4822,7 @@ cdef class TernaryMatroid(LinearMatroid): ....: [0, 1, 0, 1], [0, 0, 1, 1]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U34") + sage: M.rename('U34') sage: loads(dumps(M)) U34 sage: M = TernaryMatroid(Matrix(GF(3), [[1, 0, 1], [1, 0, 1]])) @@ -4941,21 +4924,19 @@ cdef class QuaternaryMatroid(LinearMatroid): labels. When provided, must have the correct number of elements: the number of columns of ``matrix`` or the number of rows plus the number of columns of ``reduced_matrix``. - - ``ring`` -- (default: ``None``) must be a copy of `\GF{4}`. - - ``keep_initial_representation`` -- (default: ``True``) boolean. Decides + - ``ring`` -- (default: ``None``) must be a copy of `\GF{4}` + - ``keep_initial_representation`` -- boolean (default: ``True``); decides whether or not an internal copy of the input matrix should be preserved. This can help to see the structure of the matroid (e.g. in the case of graphic matroids), and makes it easier to look at extensions. However, the input matrix may have redundant rows, and sometimes it is desirable to store only a row-reduced copy. - - ``basis`` -- (default: ``None``) When provided, this is an ordered + - ``basis`` -- (default: ``None``) when provided, this is an ordered subset of ``groundset``, such that the submatrix of ``matrix`` indexed by ``basis`` is an identity matrix. In this case, no row reduction takes place in the initialization phase. - OUTPUT: - - A ``QuaternaryMatroid`` instance based on the data above. + OUTPUT: a ``QuaternaryMatroid`` instance based on the data above .. NOTE:: @@ -5156,14 +5137,14 @@ cdef class QuaternaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) If provided, first find a basis having - maximal intersection with ``B``. + - ``B`` -- (default: ``None``) if provided, first find a basis having + maximal intersection with ``B`` OUTPUT: - - ``R`` -- A list of row indices; corresponds to the currently used + - ``R`` -- list of row indices; corresponds to the currently used internal basis - - ``C`` -- A list of column indices; corresponds to the complement of + - ``C`` -- list of column indices; corresponds to the complement of the current internal basis EXAMPLES:: @@ -5198,7 +5179,7 @@ cdef class QuaternaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -5242,7 +5223,7 @@ cdef class QuaternaryMatroid(LinearMatroid): INPUT: - - ``B`` -- (default: ``None``) a set of elements of the groundset. + - ``B`` -- (default: ``None``) a set of elements of the groundset OUTPUT: @@ -5357,12 +5338,12 @@ cdef class QuaternaryMatroid(LinearMatroid): A tuple ``(d, Lm, L0, Lp, p0, p1, p2)``, with the following interpretation: - - ``d`` is the bicycle dimension. + - ``d`` is the bicycle dimension - ``(Lm, L0, Lp)`` is the triple of lengths of the principal - tripartition. + tripartition - ``(p0, p1, p2)`` counts of edges in a characteristic graph of the matroid, whose vertices are the union of ``F_-`` and ``F_0`` from - the principal tripartition. + the principal tripartition EXAMPLES:: @@ -5447,7 +5428,7 @@ cdef class QuaternaryMatroid(LinearMatroid): INPUT: - - ``other`` -- a quaternary matroid. + - ``other`` -- a quaternary matroid OUTPUT: @@ -5487,9 +5468,7 @@ cdef class QuaternaryMatroid(LinearMatroid): - ``deletions`` is coindependent - ``contractions`` and ``deletions`` are disjoint. - OUTPUT: - - A matroid. + OUTPUT: matroid EXAMPLES:: @@ -5516,9 +5495,7 @@ cdef class QuaternaryMatroid(LinearMatroid): Since this is a linear matroid over the field `\GF{4}`, this is always the case. - OUTPUT: - - ``True``. + OUTPUT: ``True`` EXAMPLES:: @@ -5553,7 +5530,7 @@ cdef class QuaternaryMatroid(LinearMatroid): ....: [0, 0, 1, 1]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U34") + sage: M.rename('U34') sage: loads(dumps(M)) U34 @@ -5649,8 +5626,8 @@ cdef class RegularMatroid(LinearMatroid): labels. When provided, must have the correct number of elements: the number of columns of ``matrix`` or the number of rows plus the number of columns of ``reduced_matrix``. - - ``ring`` -- (default: ``None``) ignored. - - ``keep_initial_representation`` -- (default: ``True``) boolean. Decides + - ``ring`` -- (default: ``None``) ignored + - ``keep_initial_representation`` -- boolean (default: ``True``); decides whether or not an internal copy of the input matrix should be preserved. This can help to see the structure of the matroid (e.g. in the case of graphic matroids), and makes it easier to look at extensions. However, @@ -5661,9 +5638,7 @@ cdef class RegularMatroid(LinearMatroid): by ``basis`` is an identity matrix. In this case, no row reduction takes place in the initialization phase. - OUTPUT: - - A ``RegularMatroid`` instance based on the data above. + OUTPUT: a ``RegularMatroid`` instance based on the data above .. NOTE:: @@ -5964,10 +5939,10 @@ cdef class RegularMatroid(LinearMatroid): OUTPUT: - - ``PV`` -- A partition of the vertices of ``G``. - - ``tups`` -- A list of pairs ``(x, y)``, where ``x`` denotes the - color class of a part and ``y`` the number of elements in that part. - - ``G`` -- a graph. + - ``PV`` -- a partition of the vertices of ``G`` + - ``tups`` -- list of pairs ``(x, y)``, where ``x`` denotes the + color class of a part and ``y`` the number of elements in that part + - ``G`` -- a graph All are derived from the entries of the projection matrix `P`. The partition ``PV`` groups vertices of the form `i` by the value of @@ -6119,7 +6094,7 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``other`` -- a regular matroid. + - ``other`` -- a regular matroid OUTPUT: @@ -6152,11 +6127,9 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``other`` -- A ``RegularMatroid`` instance. - - OUTPUT: + - ``other`` -- a ``RegularMatroid`` instance - - a dictionary, if the hypergraphs are isomorphic; ``None`` otherwise. + OUTPUT: dictionary, if the hypergraphs are isomorphic; ``None`` otherwise TESTS: @@ -6195,13 +6168,11 @@ cdef class RegularMatroid(LinearMatroid): - ``k`` -- the length of the line minor - ``hyperlines`` -- (default: ``None``) a set of flats of codimension 2. Defaults to the set of all flats of codimension 2. - - ``certificate`` (default: ``False``); If ``True`` returns ``True, F``, - where ``F`` is a flat and ``self.minor(contractions=F)`` has a - `U_{2,k}` restriction or ``False, None``. - - OUTPUT: + - ``certificate`` -- (default: ``False``) if ``True`` returns + ``True, F``, where ``F`` is a flat and ``self.minor(contractions=F)`` + has a `U_{2,k}` restriction or ``False, None`` - Boolean or tuple. + OUTPUT: boolean or tuple .. SEEALSO:: @@ -6242,9 +6213,9 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``F`` -- an independent set of elements. + - ``F`` -- an independent set of elements - ``fundamentals`` -- (default: ``None``) a set elements of the base - ring. + ring OUTPUT: @@ -6348,12 +6319,10 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. - - ``verify`` -- Ignored - - OUTPUT: + - ``randomized_tests`` -- ignored + - ``verify`` -- ignored - A binary matroid. + OUTPUT: a binary matroid ALGORITHM: @@ -6379,7 +6348,7 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. + - ``randomized_tests`` -- ignored OUTPUT: boolean @@ -6405,12 +6374,10 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. - - ``verify`` -- Ignored - - OUTPUT: + - ``randomized_tests`` -- ignored + - ``verify`` -- ignored - A ternary matroid. + OUTPUT: a ternary matroid ALGORITHM: @@ -6436,7 +6403,7 @@ cdef class RegularMatroid(LinearMatroid): INPUT: - - ``randomized_tests`` -- Ignored. + - ``randomized_tests`` -- ignored OUTPUT: boolean @@ -6483,7 +6450,7 @@ cdef class RegularMatroid(LinearMatroid): sage: M = matroids.catalog.R12() sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("R_{12}") + sage: M.rename('R_{12}') sage: loads(dumps(M)) R_{12} sage: M = RegularMatroid(Matrix(QQ, [[1, 0, 1], [1, 0, 1]])) diff --git a/src/sage/matroids/matroid.pyx b/src/sage/matroids/matroid.pyx index 5591e14c038..bfcf7d361a2 100644 --- a/src/sage/matroids/matroid.pyx +++ b/src/sage/matroids/matroid.pyx @@ -299,7 +299,7 @@ Minors:: Testing. Note that the abstract base class does not support pickling:: sage: M = sage.matroids.matroid.Matroid() - sage: TestSuite(M).run(skip="_test_pickling") + sage: TestSuite(M).run(skip='_test_pickling') REFERENCES ========== @@ -659,7 +659,7 @@ cdef class Matroid(SageObject): OUTPUT: ``frozenset`` instance containing a subset of the groundset. - A :class:`ValueError` is raised if the set contains no circuit. + A :exc:`ValueError` is raised if the set contains no circuit. EXAMPLES:: @@ -693,8 +693,8 @@ cdef class Matroid(SageObject): INPUT: - - ``B`` -- a basis of the matroid. - - ``e`` -- an element not in ``B``. + - ``B`` -- a basis of the matroid + - ``e`` -- an element not in ``B`` OUTPUT: a set of elements @@ -793,7 +793,7 @@ cdef class Matroid(SageObject): OUTPUT: ``frozenset`` instance containing a subset of the groundset. - A :class:`ValueError` is raised if the set contains no cocircuit. + A :exc:`ValueError` is raised if the set contains no cocircuit. EXAMPLES:: @@ -827,8 +827,8 @@ cdef class Matroid(SageObject): INPUT: - - ``B`` -- a basis of the matroid. - - ``e`` -- an element of ``B``. + - ``B`` -- a basis of the matroid + - ``e`` -- an element of ``B`` OUTPUT: a set of elements @@ -878,7 +878,7 @@ cdef class Matroid(SageObject): - ``X`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - ``Y`` -- an object with Python's ``frozenset`` interface containing - a subset of ``self.groundset()``, and disjoint from ``X``. + a subset of ``self.groundset()``, and disjoint from ``X`` OUTPUT: a subset of the groundset as a :class:`frozenset` @@ -1231,7 +1231,7 @@ cdef class Matroid(SageObject): INPUT: - ``F`` -- a subset of the groundset, assumed to be a closed set of - rank `r(M) - 2`. + rank `r(M) - 2` OUTPUT: integer @@ -1256,9 +1256,9 @@ cdef class Matroid(SageObject): INPUT: - - ``element`` -- a hashable object not in ``self.groundset()``. + - ``element`` -- a hashable object not in ``self.groundset()`` - ``hyperplanes`` -- the set of hyperplanes of a linear subclass of - ``self``. + ``self`` OUTPUT: matroid @@ -1540,8 +1540,8 @@ cdef class Matroid(SageObject): INPUT: - - ``B`` -- a basis of the matroid. - - ``e`` -- an element not in ``B``. + - ``B`` -- a basis of the matroid + - ``e`` -- an element not in ``B`` OUTPUT: a set of elements @@ -1601,7 +1601,7 @@ cdef class Matroid(SageObject): INPUT: - ``X`` -- a subset (or any iterable) of the groundset - - ``k`` -- a positive integer + - ``k`` -- positive integer EXAMPLES:: @@ -1890,8 +1890,8 @@ cdef class Matroid(SageObject): INPUT: - - ``B`` -- a basis of the matroid. - - ``e`` -- an element of ``B``. + - ``B`` -- a basis of the matroid + - ``e`` -- an element of ``B`` OUTPUT: a set of elements @@ -2049,7 +2049,7 @@ cdef class Matroid(SageObject): INPUT: - ``X`` -- a subset (or any iterable) of the groundset - - ``k`` -- a positive integer + - ``k`` -- positive integer OUTPUT: boolean @@ -3606,7 +3606,8 @@ cdef class Matroid(SageObject): Two matroids `M` and `N` are *isomorphic* if there is a bijection `f` from the groundset of `M` to the groundset of `N` such that a subset `X` is independent in `M` if and only if `f(X)` is independent in `N`. - This method returns one isomorphism `f` from self to other, if such an isomorphism exists. + This method returns one isomorphism `f` from ``self`` to ``other``, if + such an isomorphism exists. INPUT: @@ -3899,8 +3900,8 @@ cdef class Matroid(SageObject): INPUT: - ``other`` -- matroid - - ``morphism`` -- a dictionary mapping the groundset of ``self`` to - the groundset of ``other``. + - ``morphism`` -- dictionary mapping the groundset of ``self`` to + the groundset of ``other`` OUTPUT: boolean @@ -4139,7 +4140,7 @@ cdef class Matroid(SageObject): INPUT: - - ``X`` -- Either a single element of the groundset, or a collection + - ``X`` -- either a single element of the groundset, or a collection of elements OUTPUT: the matroid obtained by contracting the element(s) in ``X`` @@ -4216,7 +4217,7 @@ cdef class Matroid(SageObject): INPUT: - - ``X`` -- Either a single element of the groundset, or a collection + - ``X`` -- either a single element of the groundset, or a collection of elements OUTPUT: the matroid obtained by deleting the element(s) in ``X`` @@ -4395,9 +4396,10 @@ cdef class Matroid(SageObject): - ``k`` -- the length of the line minor - ``hyperlines`` -- (default: ``None``) a set of flats of codimension 2. Defaults to the set of all flats of codimension 2. - - ``certificate`` -- (default: ``False``) if ``True`` returns ``(True, F)``, - where ``F`` is a flat and ``self.minor(contractions=F)`` has a - `U_{2,k}` restriction or ``(False, None)``. + - ``certificate`` -- boolean (default: ``False``); if ``True`` returns + ``(True, F)``, where ``F`` is a flat and + ``self.minor(contractions=F)`` has a `U_{2,k}` restriction or + ``(False, None)``. OUTPUT: boolean or tuple @@ -4459,8 +4461,8 @@ cdef class Matroid(SageObject): INPUT: - ``k`` -- the length of the line minor - - ``hyperlines`` -- (default: None) a set of flats of codimension 2. - The flats are assumed to be ``frozenset`` compatible. + - ``hyperlines`` -- (default: ``None``) a set of flats of codimension 2; + the flats are assumed to be ``frozenset`` compatible OUTPUT: boolean or tuple @@ -5054,7 +5056,7 @@ cdef class Matroid(SageObject): deleting the complement of that subset is :meth:`connected `. - OUTPUT: a list of subsets + OUTPUT: list of subsets .. SEEALSO:: @@ -5333,11 +5335,11 @@ cdef class Matroid(SageObject): INPUT: - ``k`` -- integer greater or equal to 1 - - ``certificate`` -- (default: ``False``) boolean; if ``True``, + - ``certificate`` -- boolean (default: ``False``); if ``True``, then return ``True, None`` if the matroid is k-connected, and ``False, X`` otherwise, where ``X`` is a ``. + OUTPUT: a :class:`TernaryMatroid ` ALGORITHM: @@ -6499,7 +6500,7 @@ cdef class Matroid(SageObject): ``False``, any output will represent ``self`` if and only if the matroid is ternary - OUTPUT: Either a + OUTPUT: either a :class:`TernaryMatroid `, or ``None`` @@ -6687,7 +6688,7 @@ cdef class Matroid(SageObject): INPUT: - ``C`` -- a circuit - - ``certificate`` -- boolean (default: ``False``), if ``True`` + - ``certificate`` -- boolean (default: ``False``); if ``True`` return ``True, (x, Ax, Bx)``, where ``x`` is a chord and ``Ax`` and ``Bx`` are circuits whose union is the elements of ``C`` together with ``x``, if ``False`` return ``False, None`` @@ -6736,7 +6737,7 @@ cdef class Matroid(SageObject): INPUT: - ``C`` -- a circuit - - ``certificate`` -- boolean (default: ``False``), if ``True`` + - ``certificate`` -- boolean (default: ``False``); if ``True`` return ``True, (x, Ax, Bx)``, where ``x`` is a chord and ``Ax`` and ``Bx`` are circuits whose union is the elements of ``C`` together with ``x``, if ``False`` return ``False, None`` @@ -6780,7 +6781,7 @@ cdef class Matroid(SageObject): - ``k1`` -- (optional) the integer `k_1` - ``k2`` -- (optional) the integer `k_2`; if not specified, then this method returns if ``self`` is `k_1`-chordal - - ``certificate`` -- (default: ``False``) boolean; if + - ``certificate`` -- boolean (default: ``False``); if ``True`` return ``True, C``, where ``C`` is a non ``k1`` ``k2`` circuit @@ -6860,7 +6861,7 @@ cdef class Matroid(SageObject): - ``X`` -- (default: the groundset) a subset (or any iterable) of the groundset - - ``weights`` -- a dictionary or function mapping the elements of + - ``weights`` -- dictionary or function mapping the elements of ``X`` to nonnegative weights OUTPUT: a subset of ``X`` @@ -6945,7 +6946,7 @@ cdef class Matroid(SageObject): - ``X`` -- (default: the groundset) a subset (or any iterable) of the groundset - - ``weights`` -- a dictionary or function mapping the elements of + - ``weights`` -- dictionary or function mapping the elements of ``X`` to nonnegative weights OUTPUT: a subset of ``X`` @@ -7036,7 +7037,7 @@ cdef class Matroid(SageObject): - ``X`` -- (default: the groundset) a subset (or any iterable) of the groundset - - ``weights`` -- a dictionary or function mapping the elements of + - ``weights`` -- dictionary or function mapping the elements of ``X`` to nonnegative weights OUTPUT: boolean @@ -7183,7 +7184,7 @@ cdef class Matroid(SageObject): - ``X`` -- (default: the groundset) a subset (or any iterable) of the groundset - - ``weights`` -- a dictionary or function mapping the elements of + - ``weights`` -- dictionary or function mapping the elements of ``X`` to nonnegative weights OUTPUT: boolean @@ -7197,7 +7198,6 @@ cdef class Matroid(SageObject): previously selected elements, then we check if it is coindependent with the previously selected elements with higher weight. - EXAMPLES:: sage: from sage.matroids.advanced import setprint @@ -7391,7 +7391,7 @@ cdef class Matroid(SageObject): - ``other`` -- a second matroid with the same groundset as this matroid - - ``weights`` -- a dictionary which must specify a weight for each + - ``weights`` -- dictionary which must specify a weight for each element of the common groundset OUTPUT: a subset of the groundset @@ -7721,7 +7721,7 @@ cdef class Matroid(SageObject): Return a minimum number of disjoint independent sets that covers the groundset. - OUTPUT: a list of disjoint independent sets that covers the groundset + OUTPUT: list of disjoint independent sets that covers the groundset EXAMPLES:: @@ -7980,13 +7980,13 @@ cdef class Matroid(SageObject): INPUT: - - ``solver`` -- (default: ``None``) Specify a Linear Program (LP) solver + - ``solver`` -- (default: ``None``) specify a Linear Program (LP) solver to be used. If set to ``None``, the default one is used. For more information on LP solvers and which default solver is used, see the method :meth:`~sage.numerical.mip.MixedIntegerLinearProgram.solve` of the class :class:`~sage.numerical.mip.MixedIntegerLinearProgram`. - - ``verbose`` -- integer (default: ``0``). Sets the level of verbosity + - ``verbose`` -- integer (default: 0); sets the level of verbosity of the LP solver. Set to 0 by default, which means quiet. .. SEEALSO:: @@ -8137,19 +8137,23 @@ cdef class Matroid(SageObject): INPUT: - - ``B`` -- (optional) a list containing a basis. - If internal point placement is used, these elements will be placed as vertices of a triangle. - - ``lineorders`` -- (optional) A list of lists where each of the inner lists - specify groundset elements in a certain order which will be used to draw the - corresponding line in geometric representation (if it exists). - - ``pos_method`` -- An integer specifying positioning method. + - ``B`` -- (optional) list containing a basis; if internal point + placement is used, these elements will be placed as vertices of a + triangle + - ``lineorders`` -- (optional) list of lists where each of the inner + lists specify groundset elements in a certain order which will be + used to draw the corresponding line in geometric representation (if + it exists) + - ``pos_method`` -- integer specifying positioning method - ``0``: default positioning - ``1``: use pos_dict if it is not ``None`` - - ``2``: Force directed (Not yet implemented). + - ``2``: force directed (Not yet implemented) - - ``pos_dict``: A dictionary mapping groundset elements to their (x,y) positions. - - ``save_pos``: boolean indicating that point placements (either internal or user provided) and - line orders (if provided) will be cached in the matroid (``M._cached_info``) and can be used for + - ``pos_dict`` -- dictionary mapping groundset elements to their (x,y) + positions + - ``save_pos`` -- boolean indicating that point placements (either + internal or user provided) and line orders (if provided) will be + cached in the matroid (``M._cached_info``) and can be used for reproducing the geometric representation during the same session OUTPUT: @@ -8203,19 +8207,19 @@ cdef class Matroid(SageObject): - ``lineorders`` -- (optional) a list of lists where each of the inner lists specify groundset elements in a certain order which will be used to draw the corresponding line in geometric representation (if - it exists). + it exists) - ``pos_method`` -- integer specifying the positioning method - ``0``: default positioning - ``1``: use pos_dict if it is not ``None`` - ``2``: Force directed (Not yet implemented). - - ``pos_dict`` -- a dictionary mapping groundset elements to their + - ``pos_dict`` -- dictionary mapping groundset elements to their (x, y) positions - ``save_pos`` -- boolean indicating that point placements (either internal or user provided) and line orders (if provided) will be cached in the matroid (``M._cached_info``) and can be used for reproducing the geometric representation during the same session - - ``lims`` -- a list of 4 elements ``[xmin,xmax,ymin,ymax]`` + - ``lims`` -- list of 4 elements ``[xmin,xmax,ymin,ymax]`` EXAMPLES:: @@ -8246,16 +8250,16 @@ cdef class Matroid(SageObject): cpdef _fix_positions(self, pos_dict=None, lineorders=None): """ - Cache point positions and line orders without actually plotting + Cache point positions and line orders without actually plotting. INPUT: - - ``pos_dict`` -- (optional) A dictionary mapping groundset elements to + - ``pos_dict`` -- (optional) dictionary mapping groundset elements to their (x, y) positions - - ``lineorders`` -- (optional) a list of lists where each of the inner + - ``lineorders`` -- (optional) list of lists where each of the inner lists specify groundset elements in a certain order which will be used to draw the corresponding line in geometric representation (if - it exists). + it exists) EXAMPLES:: @@ -8506,7 +8510,7 @@ cdef class Matroid(SageObject): INPUT: - - ``matroids`` -- a matroid or a list of matroids + - ``matroids`` -- matroid or a list of matroids OUTPUT: an instance of :class:`MatroidUnion ` @@ -8546,7 +8550,7 @@ cdef class Matroid(SageObject): INPUT: - - ``matroids`` -- a matroid or list of matroids + - ``matroids`` -- matroid or list of matroids OUTPUT: an instance of :class:`MatroidSum ` diff --git a/src/sage/matroids/matroids_plot_helpers.py b/src/sage/matroids/matroids_plot_helpers.py index 450c56ac049..843385370af 100644 --- a/src/sage/matroids/matroids_plot_helpers.py +++ b/src/sage/matroids/matroids_plot_helpers.py @@ -88,24 +88,21 @@ def it(M, B1, nB1, lps): INPUT: - - ``M`` -- A matroid. - - ``B1`` -- A list of groundset elements of ``M`` that corresponds to a - basis of matroid ``M``. - - ``nB1`` -- A list of elements in the ground set of M that corresponds to - ``M.simplify.groundset() \ B1``. - - ``lps`` -- A list of elements in the ground set of matroid M that are - loops. + - ``M`` -- matroid + - ``B1`` -- list of groundset elements of ``M`` that corresponds to a + basis of matroid ``M`` + - ``nB1`` -- list of elements in the ground set of M that corresponds to + ``M.simplify.groundset() \ B1`` + - ``lps`` -- list of elements in the ground set of matroid M that are loops - OUTPUT: - - A tuple containing 4 elements in this order: + OUTPUT: a tuple containing 4 elements in this order: 1. A dictionary containing 2-tuple (x,y) coordinates with ``M.simplify.groundset()`` elements that can be placed on the sides of the triangle as keys. 2. A list of 3 lists of elements of ``M.simplify.groundset()`` that can be placed on the 3 sides of the triangle. - 3. A list of elements of `M.simplify.groundset()`` that cane be placed + 3. A list of elements of ``M.simplify.groundset()`` that cane be placed inside the triangle in the geometric representation. 4. A list of lists of elements of ``M.simplify.groundset()`` that correspond to lines in the geometric representation other than the sides @@ -185,12 +182,10 @@ def trigrid(tripts): INPUT: - - ``tripts`` -- A list of 3 lists of the form [x,y] where x and y are the - Cartesian coordinates of a point. - - OUTPUT: + - ``tripts`` -- list of 3 lists of the form [x,y] where x and y are the + Cartesian coordinates of a point - A list of lists containing 4 points in following order: + OUTPUT: list of lists containing 4 points in following order: - 1. Barycenter of 3 input points. - 2,3,4. Barycenters of 1. with 3 different 2-subsets of input points @@ -228,12 +223,12 @@ def addnontripts(tripts_labels, nontripts_labels, ptsdict): INPUT: - - ``tripts`` -- A list of 3 ground set elements that are to be placed on - vertices of the triangle. - - ``ptsdict`` -- A dictionary (at least) containing ground set elements in - ``tripts`` as keys and their (x,y) position as values. - - ``nontripts`` -- A list of ground set elements whose corresponding points - are to be placed inside the triangle. + - ``tripts`` -- list of 3 ground set elements that are to be placed on + vertices of the triangle + - ``ptsdict`` -- dictionary (at least) containing ground set elements in + ``tripts`` as keys and their (x,y) position as values + - ``nontripts`` -- list of ground set elements whose corresponding points + are to be placed inside the triangle OUTPUT: @@ -295,18 +290,16 @@ def createline(ptsdict, ll, lineorders2=None): INPUT: - - ``ptsdict`` -- A dictionary containing keys and their (x,y) position as - values. - - ``ll`` -- A list of keys in ``ptsdict`` through which a line is to be - drawn. - - ``lineorders2`` -- (optional) A list of ordered lists of keys in + - ``ptsdict`` -- dictionary containing keys and their (x,y) position as + values + - ``ll`` -- list of keys in ``ptsdict`` through which a line is to be + drawn + - ``lineorders2`` -- (optional) list of ordered lists of keys in ``ptsdict`` such that if ll is setwise same as any of these then points corresponding to values of the keys will be traversed in that order thus - overriding internal order deciding heuristic. + overriding internal order deciding heuristic - OUTPUT: - - A tuple containing 4 elements in this order: + OUTPUT: a tuple containing 4 elements in this order: 1. Ordered list of x-coordinates of values of keys in ``ll`` specified in ptsdict. @@ -378,17 +371,15 @@ def slp(M1, pos_dict=None, B=None): INPUT: - - ``M1`` -- A matroid. - - ``pos_dict`` -- (optional) A dictionary containing non loopy elements of - ``M`` as keys and their (x,y) positions. - as keys. While simplifying the matroid, all except one element in a - parallel class that is also specified in ``pos_dict`` will be retained. - - ``B`` -- (optional) A basis of M1 that has been chosen for placement on - vertices of triangle. - - OUTPUT: + - ``M1`` -- matroid + - ``pos_dict`` -- (optional) dictionary containing non loopy elements of + ``M`` as keys and their (x,y) positions as keys. While simplifying the + matroid, all except one element in a parallel class that is also + specified in ``pos_dict`` will be retained. + - ``B`` -- (optional) a basis of M1 that has been chosen for placement on + vertices of triangle - A tuple containing 3 elements in this order: + OUTPUT: a tuple containing 3 elements in this order: 1. Simple matroid corresponding to ``M1``. 2. Loops of matroid ``M1``. @@ -459,21 +450,19 @@ def addlp(M, M1, L, P, ptsdict, G=None, limits=None): INPUT: - - ``M`` -- A matroid. - - ``M1`` -- A simple matroid corresponding to ``M``. - - ``L`` -- List of elements in ``M.groundset()`` that are loops of matroid - ``M``. - - ``P`` -- List of elements in ``M.groundset()`` not in - ``M.simplify.groundset()`` or ``L``. - - ``ptsdict`` -- A dictionary containing elements in ``M.groundset()`` not - necessarily containing elements of ``L``. - - ``G`` -- (optional) A sage graphics object to which loops and parallel - elements of matroid `M` added . - - ``limits`` -- (optional) Current axes limits [xmin,xmax,ymin,ymax]. - - OUTPUT: + - ``M`` -- matroid + - ``M1`` -- a simple matroid corresponding to ``M`` + - ``L`` -- list of elements in ``M.groundset()`` that are loops of matroid + ``M`` + - ``P`` -- list of elements in ``M.groundset()`` not in + ``M.simplify.groundset()`` or ``L`` + - ``ptsdict`` -- dictionary containing elements in ``M.groundset()`` not + necessarily containing elements of ``L`` + - ``G`` -- (optional) a sage graphics object to which loops and parallel + elements of matroid `M` added + - ``limits`` -- (optional) current axes limits [xmin,xmax,ymin,ymax] - A 2-tuple containing: + OUTPUT: a 2-tuple containing: 1. A sage graphics object containing loops and parallel elements of matroid ``M`` @@ -562,18 +551,16 @@ def addlp(M, M1, L, P, ptsdict, G=None, limits=None): def line_hasorder(l, lodrs=None): """ - Determine if an order is specified for a line + Determine if an order is specified for a line. INPUT: - - ``l`` -- A line specified as a list of ground set elements. - - ``lordrs`` -- (optional) A list of lists each specifying an order on + - ``l`` -- a line specified as a list of ground set elements + - ``lordrs`` -- (optional) list of lists each specifying an order on a subset of ground set elements that may or may not correspond to a - line in geometric representation. + line in geometric representation - OUTPUT: - - A tuple containing 2 elements in this order: + OUTPUT: a tuple containing 2 elements in this order: 1. A boolean indicating whether there is any list in ``lordrs`` that is setwise equal to ``l``. @@ -610,10 +597,10 @@ def lineorders_union(lineorders1, lineorders2): INPUT: - - ``lineorders1`` -- A list of ordered lists specifying orders on subsets - of ground set. - - ``lineorders2`` -- A list of ordered lists specifying orders subsets of - ground set. + - ``lineorders1`` -- list of ordered lists specifying orders on subsets + of ground set + - ``lineorders2`` -- list of ordered lists specifying orders subsets of + ground set OUTPUT: @@ -650,9 +637,9 @@ def posdict_is_sane(M1, pos_dict): INPUT: - - ``M1`` -- A matroid. - - ``posdict`` -- A dictionary mapping ground set elements to (x,y) - positions. + - ``M1`` -- matroid + - ``posdict`` -- dictionary mapping ground set elements to (x,y) + positions OUTPUT: @@ -700,13 +687,11 @@ def tracklims(lims, x_i=[], y_i=[]): INPUT: - - ``lims`` -- A list with 4 elements ``[xmin,xmax,ymin,ymax]`` - - ``x_i`` -- New x values to track - - ``y_i`` -- New y values to track - - OUTPUT: + - ``lims`` -- list with 4 elements ``[xmin,xmax,ymin,ymax]`` + - ``x_i`` -- new x values to track + - ``y_i`` -- new y values to track - A list with 4 elements ``[xmin,xmax,ymin,ymax]`` + OUTPUT: list with 4 elements ``[xmin,xmax,ymin,ymax]`` EXAMPLES:: @@ -735,18 +720,18 @@ def geomrep(M1, B1=None, lineorders1=None, pd=None, sp=False): INPUT: - - ``M1`` -- A matroid. - - ``B1`` -- (optional) A list of elements in ``M1.groundset()`` that + - ``M1`` -- matroid + - ``B1`` -- (optional) list of elements in ``M1.groundset()`` that correspond to a basis of ``M1`` and will be placed as vertices of the - triangle in the geometric representation of ``M1``. - - ``lineorders1`` -- (optional) A list of ordered lists of elements of + triangle in the geometric representation of ``M1`` + - ``lineorders1`` -- (optional) list of ordered lists of elements of ``M1.groundset()`` such that if a line in geometric representation is setwise same as any of these then points contained will be traversed in - that order thus overriding internal order deciding heuristic. - - ``pd`` -- (optional) A dictionary mapping ground set elements to their - (x,y) positions. - - ``sp`` -- (optional) If True, a positioning dictionary and line orders - will be placed in ``M._cached_info``. + that order thus overriding internal order deciding heuristic + - ``pd`` -- (optional) dictionary mapping ground set elements to their + (x,y) positions + - ``sp`` -- (optional) if ``True``, a positioning dictionary and line orders + will be placed in ``M._cached_info`` OUTPUT: diff --git a/src/sage/matroids/minor_matroid.py b/src/sage/matroids/minor_matroid.py index 1b9860b401b..68cce818f8d 100644 --- a/src/sage/matroids/minor_matroid.py +++ b/src/sage/matroids/minor_matroid.py @@ -92,10 +92,10 @@ class wraps around any matroid to provide an abstract minor. It INPUT: - ``matroid`` -- matroid - - ``contractions`` -- An object with Python's ``frozenset`` interface - containing a subset of ``self.groundset()``. - - ``deletions`` -- An object with Python's ``frozenset`` interface + - ``contractions`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()``. + - ``deletions`` -- an object with Python's ``frozenset`` interface + containing a subset of ``self.groundset()`` OUTPUT: @@ -169,9 +169,7 @@ def _rank(self, X): - ``X`` -- an object with Python's ``frozenset`` interface - OUTPUT: - - The rank of ``X`` in the matroid. + OUTPUT: the rank of ``X`` in the matroid EXAMPLES:: @@ -192,9 +190,7 @@ def _corank(self, X): - ``X`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - OUTPUT: - - The corank of ``X``. + OUTPUT: the corank of ``X`` EXAMPLES:: @@ -215,9 +211,7 @@ def _max_independent(self, X): - ``X`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - OUTPUT: - - A maximal independent subset of ``X``. + OUTPUT: a maximal independent subset of ``X`` EXAMPLES:: @@ -243,9 +237,7 @@ def _closure(self, X): - ``X`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - OUTPUT: - - The smallest closed set containing ``X``. + OUTPUT: the smallest closed set containing ``X`` EXAMPLES:: @@ -254,7 +246,6 @@ def _closure(self, X): ....: contractions=set('c'), deletions={'b', 'f'}) sage: sorted(M._closure(frozenset(['a', 'e', 'd']))) ['a', 'd', 'e', 'g', 'h'] - """ return self._matroid._closure(self._contractions.union(X)).difference(self._contractions.union(self._deletions)) @@ -267,9 +258,7 @@ def _max_coindependent(self, X): - ``X`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - OUTPUT: - - A maximal coindependent subset of ``X``. + OUTPUT: a maximal coindependent subset of ``X`` EXAMPLES:: @@ -295,9 +284,7 @@ def _coclosure(self, X): - ``X`` -- an object with Python's ``frozenset`` interface containing a subset of ``self.groundset()`` - OUTPUT: - - The smallest coclosed set containing ``X``. + OUTPUT: the smallest coclosed set containing ``X`` EXAMPLES:: @@ -306,7 +293,6 @@ def _coclosure(self, X): ....: contractions=set('c'), deletions={'b', 'f'}) sage: sorted(M._coclosure(frozenset(['a', 'b', 'c']))) ['a', 'd', 'e', 'g', 'h'] - """ return self._matroid._coclosure(self._deletions.union(X)).difference(self._contractions.union(self._deletions)) diff --git a/src/sage/matroids/rank_matroid.py b/src/sage/matroids/rank_matroid.py index 88e72748c62..7fa20b131ba 100644 --- a/src/sage/matroids/rank_matroid.py +++ b/src/sage/matroids/rank_matroid.py @@ -66,13 +66,11 @@ class RankMatroid(Matroid): INPUT: - - ``groundset`` -- the groundset of a matroid. + - ``groundset`` -- the groundset of a matroid - ``rank_function`` -- a function mapping subsets of ``groundset`` to - nonnegative integers. + nonnegative integers - OUTPUT: - - A matroid on ``groundset`` whose rank function equals ``rank_function`` + OUTPUT: a matroid on ``groundset`` whose rank function equals ``rank_function`` EXAMPLES:: @@ -84,7 +82,6 @@ class RankMatroid(Matroid): True sage: M.is_isomorphic(matroids.Uniform(3, 6)) True - """ def __init__(self, groundset, rank_function): """ @@ -171,7 +168,7 @@ def __eq__(self, other): INPUT: - - ``other`` -- A matroid. + - ``other`` -- matroid OUTPUT: @@ -212,7 +209,7 @@ def __ne__(self, other): INPUT: - - ``other`` -- A matroid. + - ``other`` -- matroid OUTPUT: diff --git a/src/sage/matroids/set_system.pyx b/src/sage/matroids/set_system.pyx index e702edc6a69..d9a2f631fbf 100644 --- a/src/sage/matroids/set_system.pyx +++ b/src/sage/matroids/set_system.pyx @@ -165,9 +165,7 @@ cdef class SetSystem: - ``k`` -- integer; the index of the subset in the system - OUTPUT: - - The subset at index `k`. + OUTPUT: the subset at index `k` EXAMPLES:: @@ -215,7 +213,7 @@ cdef class SetSystem: - ``mapping`` -- a Python object such that ``mapping[e]`` is the new label of `e` - OUTPUT: ``None`` + OUTPUT: none """ cdef long i E = [] @@ -290,13 +288,13 @@ cdef class SetSystem: cdef inline _subset(self, long k): """ - Return the k-th subset, in index format. + Return the `k`-th subset, in index format. """ return bitset_list(self._subsets[k]) cdef subset(self, k): """ - Return the k-th subset. + Return the `k`-th subset. """ cdef long i F = set() @@ -525,11 +523,11 @@ cdef class SetSystem: OUTPUT: - - ``P``, an equitable ordered partition of the groundset, stored as a - SetSystem. - - ``EP``, the corresponding equitable partition of the edges, stored - as a list of lists of indices of subsets of this SetSystem. - - ``h``, an integer invariant of the SetSystem. + - ``P`` -- an equitable ordered partition of the groundset, stored as a + SetSystem + - ``EP`` -- the corresponding equitable partition of the edges, stored + as a list of lists of indices of subsets of this SetSystem + - ``h`` -- integer invariant of the SetSystem EXAMPLES:: @@ -635,15 +633,15 @@ cdef class SetSystem: INPUT: - - ``other`` -- a SetSystem - - ``SP`` (optional) -- a SetSystem storing an ordered partition of the + - ``other`` -- SetSystem + - ``SP`` -- (optional) SetSystem storing an ordered partition of the groundset of ``self`` - - ``OP`` (optional) -- a SetSystem storing an ordered partition of the + - ``OP`` -- (optional) SetSystem storing an ordered partition of the groundset of ``other`` OUTPUT: - ``morphism`` -- a dictionary containing an isomorphism respecting the + ``morphism`` -- dictionary containing an isomorphism respecting the given ordered partitions, or ``None`` if no such isomorphism exists. EXAMPLES:: @@ -698,10 +696,10 @@ cdef class SetSystem: - ``is_equiv`` -- a function that determines if a given groundset isomorphism is a valid equivalence - - ``other`` -- a SetSystem - - ``SP`` (optional) -- a SetSystem storing an ordered partition of the + - ``other`` -- SetSystem + - ``SP`` -- (optional) SetSystem storing an ordered partition of the groundset of ``self`` - - ``OP`` (optional) -- a SetSystem storing an ordered partition of the + - ``OP`` -- (optional) SetSystem storing an ordered partition of the groundset of ``other`` OUTPUT: diff --git a/src/sage/matroids/union_matroid.pyx b/src/sage/matroids/union_matroid.pyx index 14097ad819b..ef40d0fc1b2 100644 --- a/src/sage/matroids/union_matroid.pyx +++ b/src/sage/matroids/union_matroid.pyx @@ -55,9 +55,7 @@ cdef class MatroidUnion(Matroid): The groundset is the set of elements that comprise the matroid. - OUTPUT: - - A set. + OUTPUT: set EXAMPLES:: @@ -134,7 +132,7 @@ cdef class MatroidSum(Matroid): INPUT: - - ``matroids`` -- a iterator of matroids. + - ``matroids`` -- iterator of matroids OUTPUT: @@ -186,9 +184,7 @@ cdef class MatroidSum(Matroid): The groundset is the set of elements that comprise the matroid. - OUTPUT: - - A set. + OUTPUT: set EXAMPLES:: @@ -242,7 +238,7 @@ cdef class PartitionMatroid(Matroid): INPUT: - - ``partition`` -- an iterator of disjoint sets. + - ``partition`` -- iterator of disjoint sets OUTPUT: @@ -283,9 +279,7 @@ cdef class PartitionMatroid(Matroid): The groundset is the set of elements that comprise the matroid. - OUTPUT: - - A set. + OUTPUT: set EXAMPLES:: diff --git a/src/sage/matroids/unpickling.pyx b/src/sage/matroids/unpickling.pyx index 9e41c28a477..33fa9fe7dc1 100644 --- a/src/sage/matroids/unpickling.pyx +++ b/src/sage/matroids/unpickling.pyx @@ -56,14 +56,12 @@ def unpickle_basis_matroid(version, data): INPUT: - - ``version`` -- an integer, expected to be 0 - - ``data`` -- a tuple ``(E, R, name, BB)`` in which ``E`` is the groundset + - ``version`` -- integer; expected to be 0 + - ``data`` -- tuple ``(E, R, name, BB)`` in which ``E`` is the groundset of the matroid, ``R`` is the rank, ``name`` is a custom name, and ``BB`` is the bitpacked list of bases, as pickled by Sage's ``bitset_pickle``. - OUTPUT: - - A matroid. + OUTPUT: matroid .. WARNING:: @@ -104,14 +102,12 @@ def unpickle_circuits_matroid(version, data): INPUT: - - ``version`` -- an integer, expected to be 0 - - ``data`` -- a tuple ``(E, C, name)`` in which ``E`` is the groundset + - ``version`` -- integer; expected to be 0 + - ``data`` -- tuple ``(E, C, name)`` in which ``E`` is the groundset of the matroid, ``C`` is the list of circuits , and ``name`` is a custom name. - OUTPUT: - - A matroid. + OUTPUT: matroid .. WARNING:: @@ -147,14 +143,12 @@ def unpickle_circuit_closures_matroid(version, data): INPUT: - - ``version`` -- an integer, expected to be 0 - - ``data`` -- a tuple ``(E, CC, name)`` in which ``E`` is the groundset + - ``version`` -- integer; expected to be 0 + - ``data`` -- tuple ``(E, CC, name)`` in which ``E`` is the groundset of the matroid, ``CC`` is the dictionary of circuit closures, and ``name`` is a custom name. - OUTPUT: - - A matroid. + OUTPUT: matroid .. WARNING:: @@ -190,14 +184,12 @@ def unpickle_flats_matroid(version, data): INPUT: - - ``version`` -- an integer, expected to be 0 - - ``data`` -- a tuple ``(E, F, name)`` in which ``E`` is the groundset of + - ``version`` -- integer; expected to be 0 + - ``data`` -- tuple ``(E, F, name)`` in which ``E`` is the groundset of the matroid, ``F`` is the dictionary of flats, and ``name`` is a custom name. - OUTPUT: - - A matroid. + OUTPUT: matroid .. WARNING:: @@ -234,13 +226,11 @@ def unpickle_dual_matroid(version, data): INPUT: - - ``version`` -- an integer, expected to be 0 - - ``data`` -- a tuple ``(M, name)`` in which ``M`` is - the internal matroid, and ``name`` is a custom name. - - OUTPUT: + - ``version`` -- integer; expected to be 0 + - ``data`` -- tuple ``(M, name)`` in which ``M`` is + the internal matroid, and ``name`` is a custom name - A matroid. + OUTPUT: matroid .. WARNING:: @@ -462,15 +452,13 @@ def unpickle_linear_matroid(version, data): INPUT: - - ``version`` -- an integer (currently 0). - - ``data`` -- a tuple ``(A, E, reduced, name)`` where ``A`` is the + - ``version`` -- integer (currently 0) + - ``data`` -- tuple ``(A, E, reduced, name)`` where ``A`` is the representation matrix, ``E`` is the groundset of the matroid, ``reduced`` is a boolean indicating whether ``A`` is a reduced matrix, and ``name`` is a custom name. - OUTPUT: - - A :class:`LinearMatroid` instance. + OUTPUT: :class:`LinearMatroid` .. WARNING:: @@ -482,7 +470,7 @@ def unpickle_linear_matroid(version, data): ....: [0, 1, 1, 1, 3]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U35") + sage: M.rename('U35') sage: loads(dumps(M)) U35 """ @@ -509,14 +497,12 @@ def unpickle_binary_matroid(version, data): INPUT: - - ``version`` -- an integer (currently 0). - - ``data`` -- a tuple ``(A, E, B, name)`` where ``A`` is the + - ``version`` -- integer (currently 0) + - ``data`` -- tuple ``(A, E, B, name)`` where ``A`` is the representation matrix, ``E`` is the groundset of the matroid, ``B`` is the currently displayed basis, and ``name`` is a custom name. - OUTPUT: - - A :class:`BinaryMatroid` instance. + OUTPUT: :class:`BinaryMatroid` .. WARNING:: @@ -528,7 +514,7 @@ def unpickle_binary_matroid(version, data): ....: [0, 0, 1, 1]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U34") + sage: M.rename('U34') sage: loads(dumps(M)) U34 """ @@ -555,14 +541,12 @@ def unpickle_ternary_matroid(version, data): INPUT: - - ``version`` -- an integer (currently 0). - - ``data`` -- a tuple ``(A, E, B, name)`` where ``A`` is the + - ``version`` -- integer (currently 0) + - ``data`` -- tuple ``(A, E, B, name)`` where ``A`` is the representation matrix, ``E`` is the groundset of the matroid, ``B`` is the currently displayed basis, and ``name`` is a custom name. - OUTPUT: - - A :class:`TernaryMatroid` instance. + OUTPUT: :class:`TernaryMatroid` .. WARNING:: @@ -575,7 +559,7 @@ def unpickle_ternary_matroid(version, data): ....: [0, 0, 1, 1]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U34") + sage: M.rename('U34') sage: loads(dumps(M)) U34 """ @@ -602,14 +586,12 @@ def unpickle_quaternary_matroid(version, data): INPUT: - - ``version`` -- an integer (currently 0). - - ``data`` -- a tuple ``(A, E, B, name)`` where ``A`` is the + - ``version`` -- integer (currently 0) + - ``data`` -- tuple ``(A, E, B, name)`` where ``A`` is the representation matrix, ``E`` is the groundset of the matroid, ``B`` is the currently displayed basis, and ``name`` is a custom name. - OUTPUT: - - A :class:`TernaryMatroid` instance. + OUTPUT: :class:`TernaryMatroid` .. WARNING:: @@ -622,7 +604,7 @@ def unpickle_quaternary_matroid(version, data): ....: [0, 0, 1, 1]])) sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("U34") + sage: M.rename('U34') sage: loads(dumps(M)) U34 sage: M = QuaternaryMatroid(Matrix(GF(4, 'x'), [[1, 0, 1], # needs sage.rings.finite_rings @@ -654,15 +636,13 @@ def unpickle_regular_matroid(version, data): INPUT: - - ``version`` -- an integer (currently 0). - - ``data`` -- a tuple ``(A, E, reduced, name)`` where ``A`` is the + - ``version`` -- integer (currently 0) + - ``data`` -- tuple ``(A, E, reduced, name)`` where ``A`` is the representation matrix, ``E`` is the groundset of the matroid, ``reduced`` is a boolean indicating whether ``A`` is a reduced matrix, and ``name`` is a custom name. - OUTPUT: - - A :class:`RegularMatroid` instance. + OUTPUT: :class:`RegularMatroid` .. WARNING:: @@ -673,7 +653,7 @@ def unpickle_regular_matroid(version, data): sage: M = matroids.catalog.R10() sage: M == loads(dumps(M)) # indirect doctest True - sage: M.rename("R_{10}") + sage: M.rename('R_{10}') sage: loads(dumps(M)) R_{10} """ @@ -704,15 +684,13 @@ def unpickle_minor_matroid(version, data): INPUT: - - ``version`` -- an integer, currently `0`. - - ``data`` -- a tuple ``(M, C, D, name)``, where ``M`` is the original + - ``version`` -- integer; currently `0` + - ``data`` -- tuple ``(M, C, D, name)``, where ``M`` is the original matroid of which the output is a minor, ``C`` is the set of contractions, ``D`` is the set of deletions, and ``name`` is a custom name. - OUTPUT: - - A :class:`MinorMatroid` instance. + OUTPUT: :class:`MinorMatroid` .. WARNING:: @@ -747,12 +725,10 @@ def unpickle_graphic_matroid(version, data): INPUT: - - ``version`` -- an integer (currently 0). - - ``data`` -- a tuple consisting of a SageMath graph and a name. - - OUTPUT: + - ``version`` -- integer (currently 0) + - ``data`` -- tuple consisting of a SageMath graph and a name - A :class:`GraphicMatroid` instance. + OUTPUT: :class:`GraphicMatroid` .. WARNING:: diff --git a/src/sage/matroids/utilities.py b/src/sage/matroids/utilities.py index 0ab95bb02ec..c9b903594c5 100644 --- a/src/sage/matroids/utilities.py +++ b/src/sage/matroids/utilities.py @@ -48,11 +48,9 @@ def setprint(X): INPUT: - - ``X`` -- Any Python object - - OUTPUT: + - ``X`` -- any Python object - ``None``. However, the function prints a nice representation of ``X``. + OUTPUT: none; however, the function prints a nice representation of ``X`` EXAMPLES: @@ -93,8 +91,8 @@ def setprint_s(X, toplevel=False): INPUT: - ``X`` -- any Python object - - ``toplevel`` -- (default: ``False``) indicates whether this is a - recursion or not. + - ``toplevel`` -- boolean (default: ``False``); indicates whether this is a + recursion or not OUTPUT: @@ -139,11 +137,9 @@ def newlabel(groundset): INPUT: - - ``groundset`` -- A set of objects. + - ``groundset`` -- set of objects - OUTPUT: - - A string not in the set ``groundset``. + OUTPUT: string not in the set ``groundset`` For direct access to ``newlabel``, run:: @@ -188,13 +184,11 @@ def sanitize_contractions_deletions(matroid, contractions, deletions): INPUT: - ``matroid`` -- a :class:`Matroid ` - instance. - - ``contractions`` -- a subset of the groundset. - - ``deletions`` -- a subset of the groundset. + instance + - ``contractions`` -- a subset of the groundset + - ``deletions`` -- a subset of the groundset - OUTPUT: - - An independent set ``C`` and a coindependent set ``D`` such that + OUTPUT: an independent set ``C`` and a coindependent set ``D`` such that ``matroid / contractions \ deletions == matroid / C \ D`` @@ -251,7 +245,7 @@ def make_regular_matroid_from_matroid(matroid): INPUT: - - ``matroid`` -- a matroid. + - ``matroid`` -- matroid OUTPUT: @@ -328,7 +322,7 @@ def get_nonisomorphic_matroids(MSet): INPUT: - - ``MSet`` -- an iterable whose members are matroids. + - ``MSet`` -- an iterable whose members are matroids OUTPUT: @@ -364,12 +358,13 @@ def spanning_forest(M): INPUT: - ``M`` -- a matrix defining a bipartite graph G. The vertices are the - rows and columns, if `M[i,j]` is non-zero, then there is an edge + rows and columns, if `M[i,j]` is nonzero, then there is an edge between row `i` and column `j`. OUTPUT: - A list of tuples `(r_i,c_i)` representing edges between row `r_i` and column `c_i`. + A list of tuples `(r_i,c_i)` representing edges between row `r_i` and + column `c_i`. EXAMPLES:: @@ -408,12 +403,13 @@ def spanning_stars(M): INPUT: - ``M`` -- a matrix defining a bipartite graph G. The vertices are the - rows and columns, if `M[i,j]` is non-zero, then there is an edge + rows and columns, if `M[i,j]` is nonzero, then there is an edge between row i and column 0. OUTPUT: - A list of tuples `(row,column)` in a spanning forest of the bipartite graph defined by ``M`` + A list of tuples `(row,column)` in a spanning forest of the bipartite graph + defined by ``M``. EXAMPLES:: @@ -492,13 +488,12 @@ def lift_cross_ratios(A, lift_map=None): INPUT: - - ``A`` -- a matrix over a ring ``source_ring``. - - ``lift_map`` -- a Python dictionary, mapping each cross ratio of ``A`` to some element - of a target ring, and such that ``lift_map[source_ring(1)] = target_ring(1)``. - - OUTPUT: + - ``A`` -- a matrix over a ring ``source_ring`` + - ``lift_map`` -- a Python dictionary, mapping each cross ratio of ``A`` to + some element of a target ring, and such that + ``lift_map[source_ring(1)] = target_ring(1)`` - - ``Z`` -- a matrix over the ring ``target_ring``. + OUTPUT: ``Z`` -- a matrix over the ring ``target_ring`` The intended use of this method is to create a (reduced) matrix representation of a matroid ``M`` over a ring ``target_ring``, given a (reduced) matrix representation of @@ -670,11 +665,9 @@ def lift_map(target): INPUT: - - ``target`` -- a string describing the target (partial) field. - - OUTPUT: + - ``target`` -- string describing the target (partial) field - - a dictionary + OUTPUT: dictionary Depending on the value of ``target``, the following lift maps will be created: @@ -750,11 +743,11 @@ def split_vertex(G, u, v=None, edges=None): INPUT: - - ``G`` -- A SageMath :class:`Graph`. - - ``u`` -- A vertex in ``G``. - - ``v`` -- (optional) The name of the new vertex after the splitting. If + - ``G`` -- a SageMath :class:`Graph` + - ``u`` -- a vertex in ``G`` + - ``v`` -- (optional) the name of the new vertex after the splitting. If ``v`` is specified and already in the graph, it must be an isolated vertex. - - ``edges`` -- (optional) An iterable container of edges on ``u`` that + - ``edges`` -- (optional) iterable container of edges on ``u`` that move to ``v`` after the splitting. If ``None``, ``v`` will be an isolated vertex. The edge labels must be specified. diff --git a/src/sage/misc/abstract_method.py b/src/sage/misc/abstract_method.py index a169c455ef1..fad6f3097f2 100644 --- a/src/sage/misc/abstract_method.py +++ b/src/sage/misc/abstract_method.py @@ -14,12 +14,12 @@ def abstract_method(f=None, optional=False): r""" - Abstract methods + Abstract methods. INPUT: - - ``f`` -- a function - - ``optional`` -- a boolean; defaults to ``False`` + - ``f`` -- a function + - ``optional`` -- boolean (default: ``False``) The decorator :obj:`abstract_method` can be used to declare methods that should be implemented by all concrete derived @@ -49,7 +49,7 @@ def abstract_method(f=None, optional=False): sage: A.my_method - The current policy is that a :class:`NotImplementedError` is raised + The current policy is that a :exc:`NotImplementedError` is raised when accessing the method through an instance, even before the method is called:: @@ -142,7 +142,7 @@ def abstract_method(f=None, optional=False): class AbstractMethod: def __init__(self, f, optional=False): """ - Constructor for abstract methods + Constructor for abstract methods. EXAMPLES:: @@ -184,7 +184,7 @@ def __repr__(self): def _sage_src_lines_(self): r""" - Returns the source code location for the wrapped function. + Return the source code location for the wrapped function. EXAMPLES:: @@ -201,7 +201,7 @@ def _sage_src_lines_(self): def __get__(self, instance, cls): """ - Implements the attribute access protocol. + Implement the attribute access protocol. EXAMPLES:: @@ -222,7 +222,7 @@ def __get__(self, instance, cls): def is_optional(self): """ - Returns whether an abstract method is optional or not. + Return whether an abstract method is optional or not. EXAMPLES:: @@ -242,7 +242,7 @@ def is_optional(self): def abstract_methods_of_class(cls): """ - Returns the required and optional abstract methods of the class + Return the required and optional abstract methods of the class. EXAMPLES:: diff --git a/src/sage/misc/banner.py b/src/sage/misc/banner.py index 790a4fcccb9..af46d711721 100644 --- a/src/sage/misc/banner.py +++ b/src/sage/misc/banner.py @@ -20,9 +20,7 @@ def version(): """ Return the version of Sage. - OUTPUT: - - str + OUTPUT: string EXAMPLES:: @@ -90,7 +88,7 @@ def banner(): """ Print the Sage banner. - OUTPUT: None + OUTPUT: none If the environment variable ``SAGE_BANNER`` is set to ``no``, no banner is displayed. If ``SAGE_BANNER`` is set to ``bare``, a @@ -125,13 +123,7 @@ def version_dict(): """ A dictionary describing the version of Sage. - INPUT: - - nothing - - OUTPUT: - - dictionary with keys 'major', 'minor', 'tiny', 'prerelease' + OUTPUT: dictionary with keys 'major', 'minor', 'tiny', 'prerelease' This process the Sage version string and produces a dictionary. It expects the Sage version to be in one of these forms:: @@ -188,19 +180,18 @@ def version_dict(): def require_version(major, minor=0, tiny=0, prerelease=False, print_message=False): """ - True if Sage version is at least major.minor.tiny. + Return ``True`` if Sage version is at least ``major.minor.tiny``. INPUT: - - major -- integer - - minor -- integer (default: 0) - - tiny -- float (default: 0) - - prerelease -- boolean (default: ``False``) - - print_message -- boolean (default: ``False``) - - OUTPUT: + - ``major`` -- integer + - ``minor`` -- integer (default: 0) + - ``tiny`` -- float (default: 0) + - ``prerelease`` -- boolean (default: ``False``) + - ``print_message`` -- boolean (default: ``False``) - True if major.minor.tiny is <= version of Sage, False otherwise + OUTPUT: ``True`` if ``major.minor.tiny`` is <= version of Sage, ``False`` + otherwise For example, if the Sage version number is 3.1.2, then require_version(3, 1, 3) will return False, while @@ -212,7 +203,7 @@ def require_version(major, minor=0, tiny=0, prerelease=False, if the optional argument prerelease is True, then a prerelease version of Sage counts as if it were the released version. - If optional argument print_message is True and this function + If optional argument print_message is ``True`` and this function is returning False, print a warning message. EXAMPLES:: diff --git a/src/sage/misc/benchmark.py b/src/sage/misc/benchmark.py index 66b673a6fa0..4b9aa1e8b70 100644 --- a/src/sage/misc/benchmark.py +++ b/src/sage/misc/benchmark.py @@ -12,8 +12,8 @@ def benchmark(n=-1): INPUT: - n -- int (default: -1) the benchmark number; the default - of -1 runs all the benchmarks. + - ``n`` -- integer (default: -1); the benchmark number; the default + of -1 runs all the benchmarks OUTPUT: @@ -50,7 +50,6 @@ def benchmark(n=-1): Compute the Mordell-Weil group of y^2 = x^3 + 37*x - 997. Time: ... seconds Running benchmark 8 - """ if isinstance(n, list): @@ -90,7 +89,6 @@ def bench0(): sage: print(bench0()[0]) Benchmark 0: Factor the following polynomial over the rational numbers: (x^97+19*x+1)*(x^103-19*x^97+14)*(x^100-1) - """ desc = """Benchmark 0: Factor the following polynomial over the rational numbers: (x^97+19*x+1)*(x^103-19*x^97+14)*(x^100-1)""" @@ -110,7 +108,6 @@ def bench1(): sage: from sage.misc.benchmark import * sage: print(bench1()[0]) Find the Mordell-Weil group of the elliptic curve 5077A using mwrank - """ desc = """Find the Mordell-Weil group of the elliptic curve 5077A using mwrank""" E = mwrank_EllipticCurve([0, 0, 1, -7, 6]) @@ -128,7 +125,6 @@ def bench2(): sage: from sage.misc.benchmark import * sage: print(bench2()[0]) Some basic arithmetic with very large Integer numbers: '3^1000001 * 19^100001 - """ desc = """Some basic arithmetic with very large Integer numbers: '3^1000001 * 19^100001""" t = cputime() @@ -145,7 +141,6 @@ def bench3(): sage: from sage.misc.benchmark import * sage: print(bench3()[0]) Some basic arithmetic with very large Rational numbers: '(2/3)^100001 * (17/19)^100001 - """ desc = """Some basic arithmetic with very large Rational numbers: '(2/3)^100001 * (17/19)^100001""" t = cputime() @@ -162,7 +157,6 @@ def bench4(): sage: from sage.misc.benchmark import * sage: print(bench4()[0]) Rational polynomial arithmetic using Sage. Compute (x^29+17*x-5)^200. - """ desc = """Rational polynomial arithmetic using Sage. Compute (x^29+17*x-5)^200.""" x = PolynomialRing(QQ, 'x').gen() @@ -181,7 +175,6 @@ def bench5(): sage: from sage.misc.benchmark import * sage: print(bench5()[0]) Rational polynomial arithmetic using Sage. Compute (x^19 - 18*x + 1)^50 one hundred times. - """ desc = """Rational polynomial arithmetic using Sage. Compute (x^19 - 18*x + 1)^50 one hundred times.""" x = PolynomialRing(QQ, 'x').gen() @@ -200,7 +193,6 @@ def bench6(): sage: from sage.misc.benchmark import * sage: print(bench6()[0]) Compute the p-division polynomials of y^2 = x^3 + 37*x - 997 for primes p < 40. - """ desc = """Compute the p-division polynomials of y^2 = x^3 + 37*x - 997 for primes p < 40.""" E = EllipticCurve([0, 0, 0, 37, -997]) @@ -219,7 +211,6 @@ def bench7(): sage: from sage.misc.benchmark import * sage: print(bench7()[0]) Compute the Mordell-Weil group of y^2 = x^3 + 37*x - 997. - """ desc = """Compute the Mordell-Weil group of y^2 = x^3 + 37*x - 997.""" E = EllipticCurve([0, 0, 0, 37, -997]) diff --git a/src/sage/misc/binary_tree.pyx b/src/sage/misc/binary_tree.pyx index 511e7622faa..583e397a845 100644 --- a/src/sage/misc/binary_tree.pyx +++ b/src/sage/misc/binary_tree.pyx @@ -438,7 +438,7 @@ cdef class BinaryTree: """ return self.head == NULL - def keys(BinaryTree self, order="inorder"): + def keys(BinaryTree self, order='inorder'): """ Return the keys sorted according to "order" parameter. @@ -457,7 +457,7 @@ cdef class BinaryTree: return binary_tree_list(self.head, LIST_KEYS + o) - def values(BinaryTree self, order="inorder"): + def values(BinaryTree self, order='inorder'): """ Return the keys sorted according to "order" parameter. diff --git a/src/sage/misc/bindable_class.py b/src/sage/misc/bindable_class.py index d9cfa536dc9..743b5a19da6 100644 --- a/src/sage/misc/bindable_class.py +++ b/src/sage/misc/bindable_class.py @@ -18,7 +18,7 @@ class BindableClass(metaclass=ClasscallMetaclass): """ - Bindable classes + Bindable classes. This class implements a binding behavior for nested classes that derive from it. Namely, if a nested class ``Outer.Inner`` derives @@ -100,7 +100,7 @@ class BindableClass(metaclass=ClasscallMetaclass): sage: outer.Inner > - .. note:: + .. NOTE:: This is not actually a class, but an instance of :class:`functools.partial`:: @@ -125,7 +125,7 @@ class BindableClass(metaclass=ClasscallMetaclass): @staticmethod def __classget__(cls, instance, owner): """ - Binds ``cls`` to ``instance``, returning a ``BoundClass`` + Bind ``cls`` to ``instance``, returning a ``BoundClass``. INPUT: diff --git a/src/sage/misc/c3.pyx b/src/sage/misc/c3.pyx index a3f37380faf..bd8057b361f 100644 --- a/src/sage/misc/c3.pyx +++ b/src/sage/misc/c3.pyx @@ -45,10 +45,10 @@ cpdef list C3_algorithm(object start, str bases, str attribute, bint proper): INPUT: - ``start`` -- an object; the returned list is built upon data - provided by certain attributes of ``start``. - - ``bases`` -- a string; the name of an attribute of ``start`` - providing a list of objects. - - ``attribute`` -- a string; the name of an attribute of the + provided by certain attributes of ``start`` + - ``bases`` -- string; the name of an attribute of ``start`` + providing a list of objects + - ``attribute`` -- string; the name of an attribute of the objects provided in ``getattr(start,bases)``. That attribute is supposed to provide a list. diff --git a/src/sage/misc/c3_controlled.pyx b/src/sage/misc/c3_controlled.pyx index 518e321c197..76445ff4dfb 100644 --- a/src/sage/misc/c3_controlled.pyx +++ b/src/sage/misc/c3_controlled.pyx @@ -496,7 +496,7 @@ cdef class CmpKey: def __init__(self): """ - Sets the internal category counter to zero. + Set the internal category counter to zero. EXAMPLES:: @@ -507,7 +507,7 @@ cdef class CmpKey: def __get__(self, object inst, object cls): """ - Bind the comparison key to the given instance + Bind the comparison key to the given instance. EXAMPLES:: @@ -555,7 +555,6 @@ cdef class CmpKeyNamed: True sage: Algebras(ZZ)._cmp_key != Algebras(GF(5))._cmp_key True - """ def __get__(self, object inst, object cls): """ @@ -565,7 +564,6 @@ cdef class CmpKeyNamed: True sage: Algebras(ZZ)._cmp_key != Algebras(GF(5))._cmp_key True - """ cdef dict D = cls._make_named_class_cache cdef str name = "_cmp_key" @@ -1208,7 +1206,7 @@ class HierarchyElement(object, metaclass=ClasscallMetaclass): @lazy_attribute def _bases_controlled(self): """ - A list of bases controlled by :meth:`C3_sorted_merge` + A list of bases controlled by :meth:`C3_sorted_merge`. This triggers the calculation of the MRO using :meth:`C3_sorted_merge`, which sets this attribute as a side @@ -1231,7 +1229,7 @@ class HierarchyElement(object, metaclass=ClasscallMetaclass): @lazy_attribute def mro_standard(self): """ - The MRO for this object, calculated with :meth:`C3_merge` + The MRO for this object, calculated with :meth:`C3_merge`. EXAMPLES:: diff --git a/src/sage/misc/cachefunc.pyx b/src/sage/misc/cachefunc.pyx index 597dfc5d049..c7590c6e9ad 100644 --- a/src/sage/misc/cachefunc.pyx +++ b/src/sage/misc/cachefunc.pyx @@ -468,9 +468,9 @@ def _cached_function_unpickle(module, name, cache=None): INPUT: - - ``module`` -- the name of the module to import the function from. - - ``name`` -- the name of the cached function. - - ``cache`` -- a list of cached key value pairs. + - ``module`` -- the name of the module to import the function from + - ``name`` -- the name of the cached function + - ``cache`` -- list of cached key value pairs TESTS:: @@ -499,7 +499,6 @@ def _cached_function_unpickle(module, name, cache=None): True sage: f(0) 0 - """ ret = getattr(__import__(module, fromlist=['']),name) if cache is not None: @@ -518,7 +517,6 @@ cdef class NonpicklingDict(dict): sage: d[0] = 0 sage: loads(dumps(d)) {} - """ def __reduce__(self): r""" @@ -531,7 +529,6 @@ cdef class NonpicklingDict(dict): sage: d[0] = 0 sage: d.__reduce__() (, ()) - """ return NonpicklingDict, () @@ -679,9 +676,9 @@ cdef class CachedFunction(): caching. In this example we ignore the parameter ``algorithm``:: sage: @cached_function(key=lambda x,y,algorithm: (x,y)) - ....: def mul(x, y, algorithm="default"): + ....: def mul(x, y, algorithm='default'): ....: return x*y - sage: mul(1,1,algorithm="default") is mul(1,1,algorithm="algorithm") is mul(1,1) is mul(1,1,'default') + sage: mul(1,1,algorithm='default') is mul(1,1,algorithm='algorithm') is mul(1,1) is mul(1,1,'default') True """ def __init__(self, f, *, classmethod=False, name=None, key=None, do_pickle=None): @@ -752,7 +749,6 @@ cdef class CachedFunction(): sage: f = loads(s) sage: len(f.cache) 100 - """ self.is_classmethod = classmethod self._common_init(f, None, name=name, key=key, do_pickle=do_pickle) @@ -824,7 +820,7 @@ cdef class CachedFunction(): TESTS:: sage: @cached_function(key=lambda x,y,algorithm: (x,y)) - ....: def mul(x, y, algorithm="default"): + ....: def mul(x, y, algorithm='default'): ....: return x*y sage: mul.get_key(1,1,"default") # indirect doctest (1, 1) @@ -913,7 +909,7 @@ cdef class CachedFunction(): def _sage_src_(self): """ - Returns the source code for the wrapped function. + Return the source code for the wrapped function. TESTS:: @@ -921,14 +917,13 @@ cdef class CachedFunction(): sage: g = CachedFunction(number_of_partitions) # needs sage.combinat sage: 'flint' in sage_getsource(g) # indirect doctest # needs sage.combinat True - """ from sage.misc.sageinspect import sage_getsource return sage_getsource(self.f) def _sage_src_lines_(self): r""" - Returns the list of source lines and the first line number + Return the list of source lines and the first line number of the wrapped function. TESTS:: @@ -939,7 +934,6 @@ cdef class CachedFunction(): sage: l = ' elif algorithm.startswith("macaulay2:"):\n' sage: l in sage_getsourcelines(I.groebner_basis)[0] # indirect doctest True - """ from sage.misc.sageinspect import sage_getsourcelines return sage_getsourcelines(self.f) @@ -959,7 +953,6 @@ cdef class CachedFunction(): FullArgSpec(args=['self', 'algorithm', 'deg_bound', 'mult_bound', 'prot'], varargs='args', varkw='kwds', defaults=('', None, None, False), kwonlyargs=[], kwonlydefaults=None, annotations={}) - """ return sage_getargspec(self.f) @@ -1001,7 +994,6 @@ cdef class CachedFunction(): True sage: f(y) is not f(x) True - """ k = self.get_key_args_kwds(args, kwds) @@ -1019,7 +1011,7 @@ cdef class CachedFunction(): def cached(self, *args, **kwds): """ Return the result from the cache if available. If the value is - not cached, raise ``KeyError``. + not cached, raise :exc:`KeyError`. EXAMPLES:: @@ -1045,7 +1037,7 @@ cdef class CachedFunction(): def is_in_cache(self, *args, **kwds): """ - Checks if the argument list is in the cache. + Check if the argument list is in the cache. EXAMPLES:: @@ -1081,7 +1073,6 @@ cdef class CachedFunction(): 1 + O(2) sage: f.is_in_cache(x) True - """ k = self.get_key_args_kwds(args, kwds) try: @@ -1236,7 +1227,7 @@ cdef class CachedFunction(): INPUT: - ``arglist`` -- list (or iterables) of arguments for which - the method shall be precomputed. + the method shall be precomputed - ``num_processes`` -- number of processes used by :func:`~sage.parallel.decorate.parallel` @@ -1331,9 +1322,9 @@ cdef class WeakCachedFunction(CachedFunction): caching. In this example we ignore the parameter ``algorithm``:: sage: @weak_cached_function(key=lambda x,algorithm: x) - ....: def mod_ring(x, algorithm="default"): + ....: def mod_ring(x, algorithm='default'): ....: return IntegerModRing(x) - sage: mod_ring(1,algorithm="default") is mod_ring(1,algorithm="algorithm") is mod_ring(1) is mod_ring(1,'default') + sage: mod_ring(1,algorithm='default') is mod_ring(1,algorithm='algorithm') is mod_ring(1) is mod_ring(1,'default') True TESTS: @@ -1557,9 +1548,9 @@ class CachedMethodPickle(): """ INPUT: - - ``inst`` -- some instance. - - ``name`` (string) -- usually the name of an attribute - of ``inst`` to which ``self`` is assigned. + - ``inst`` -- some instance + - ``name`` -- string; usually the name of an attribute + of ``inst`` to which ``self`` is assigned TESTS:: @@ -1567,7 +1558,6 @@ class CachedMethodPickle(): sage: P = CachedMethodPickle(1, 'foo') sage: P Pickle of the cached method "foo" - """ self._instance = inst self._name = name @@ -1637,7 +1627,6 @@ class CachedMethodPickle(): [a, b] sage: J.gens Cached version of - """ self._instance.__dict__.__delitem__(self._name) CM = getattr(self._instance,self._name) @@ -1741,7 +1730,6 @@ cdef class CachedMethodCaller(CachedFunction): sage: b = loads(dumps(a)) sage: len(b.bar.cache) 1 - """ def __init__(self, CachedMethod cachedmethod, inst, *, cache=None, name=None, key=None, do_pickle=None): """ @@ -1856,7 +1844,7 @@ cdef class CachedMethodCaller(CachedFunction): ....: @cached_method(key=_f_normalize) ....: def f(self, x, algorithm='default'): return x sage: a = A() - sage: a.f(1, algorithm="default") is a.f(1) is a.f(1, algorithm="algorithm") + sage: a.f(1, algorithm='default') is a.f(1) is a.f(1, algorithm='algorithm') True """ if self._argument_fixer is None: @@ -1950,7 +1938,6 @@ cdef class CachedMethodCaller(CachedFunction): True sage: a.f(y) is not a.f(x) True - """ if self._instance is None: # cached method bound to a class @@ -1975,7 +1962,7 @@ cdef class CachedMethodCaller(CachedFunction): def cached(self, *args, **kwds): """ Return the result from the cache if available. If the value is - not cached, raise ``KeyError``. + not cached, raise :exc:`KeyError`. EXAMPLES:: @@ -2057,7 +2044,7 @@ cdef class CachedMethodCaller(CachedFunction): True Any instance of ``Bar`` gets its own instance of - :class:`CachedMethodCaller``:: + :class:`CachedMethodCaller`:: sage: b1.f is b2.f False @@ -2090,7 +2077,6 @@ cdef class CachedMethodCaller(CachedFunction): -1 sage: b.f.cache {1: -1} - """ # This is for Parents or Elements that do not allow attribute assignment try: @@ -2126,7 +2112,7 @@ cdef class CachedMethodCaller(CachedFunction): INPUT: - ``arglist`` -- list (or iterables) of arguments for which - the method shall be precomputed. + the method shall be precomputed - ``num_processes`` -- number of processes used by :func:`~sage.parallel.decorate.parallel` @@ -2239,7 +2225,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): 4 sage: a.f.cache 4 - """ # initialize CachedFunction if isinstance(f,str): @@ -2310,7 +2295,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): False sage: I.gens._instance_call() == I.gens() True - """ return self.f(self._instance) @@ -2326,7 +2310,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): [a, b] sage: I.gens() is I.gens() True - """ if self.cache is None: f = self.f @@ -2364,7 +2347,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): sage: I.gens.set_cache(None) sage: I.gens() [a, b] - """ self.cache = value @@ -2388,7 +2370,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): sage: I.gens.clear_cache() sage: I.gens() [a, b] - """ self.cache = None @@ -2411,7 +2392,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): [x, y] sage: I.gens.is_in_cache() True - """ return self.cache is not None @@ -2463,7 +2443,7 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): Any instance of ``Bar`` gets its own instance of - :class:`CachedMethodCaller``:: + :class:`CachedMethodCaller`:: sage: b1.f is b2.f False @@ -2477,7 +2457,6 @@ cdef class CachedMethodCallerNoArgs(CachedFunction): True sage: b2.f._instance is b2 True - """ # This is for Parents or Elements that do not allow attribute assignment try: @@ -2589,7 +2568,7 @@ cdef class CachedMethod(): ....: @cached_method(key=_f_normalize) ....: def f(self, x, algorithm='default'): return x sage: a = A() - sage: a.f(1, algorithm="default") is a.f(1) is a.f(1, algorithm="algorithm") + sage: a.f(1, algorithm='default') is a.f(1) is a.f(1, algorithm='algorithm') True The parameter ``do_pickle`` can be used to enable pickling of the cache. @@ -2641,7 +2620,6 @@ cdef class CachedMethod(): 1 sage: b.f() 1 - """ def __init__(self, f, name=None, key=None, do_pickle=None): """ @@ -2715,12 +2693,12 @@ cdef class CachedMethod(): def __call__(self, inst, *args, **kwds): """ - Call the cached method as a function on an instance + Call the cached method as a function on an instance. INPUT: - ``inst`` -- an instance on which the method is to be called - - Further positional or named arguments. + - further positional or named arguments EXAMPLES:: @@ -2781,7 +2759,6 @@ cdef class CachedMethod(): {((2,), ()): 4} sage: a._cache__f {((2,), ()): 4} - """ default = {} if self._cachedfunc.do_pickle else NonpicklingDict() try: @@ -2832,7 +2809,6 @@ cdef class CachedMethod(): 0 sage: a.f.cache {1: 0} - """ # This is for Parents or Elements that do not allow attribute assignment: cdef str name @@ -2928,7 +2904,6 @@ cdef class CachedSpecialMethod(CachedMethod): 5 sage: hash(c) 5 - """ def __get__(self, object inst, cls): """ @@ -2962,7 +2937,6 @@ cdef class CachedSpecialMethod(CachedMethod): 0 sage: a.__hash__.cache {1: 0} - """ # This is for Parents or Elements that do not allow attribute assignment: cdef str name @@ -3112,7 +3086,6 @@ def cached_method(f, name=None, key=None, do_pickle=None): sage: d = loads(dumps(c)) sage: hash(d) == hash(c) False - """ cdef str fname = name or f.__name__ if fname in special_method_names: @@ -3147,12 +3120,11 @@ cdef class CachedInParentMethod(CachedMethod): is assigned to must be hashable. Examples can be found at :mod:`~sage.misc.cachefunc`. - """ def __init__(self, f, name=None, key=None, do_pickle=None): """ - Constructs a new method with cache stored in the parent of the instance. + Construct a new method with cache stored in the parent of the instance. See also ``cached_method`` and ``cached_function``. @@ -3197,7 +3169,7 @@ cdef class CachedInParentMethod(CachedMethod): ....: @cached_in_parent_method(key=_f_normalize) ....: def f(self, x, algorithm='default'): return x sage: a = A() - sage: a.f(1, algorithm="default") is a.f(1) is a.f(1, algorithm="algorithm") + sage: a.f(1, algorithm='default') is a.f(1) is a.f(1, algorithm='algorithm') True Test that ``do_pickle`` works. Usually the contents of the cache are not @@ -3238,7 +3210,6 @@ cdef class CachedInParentMethod(CachedMethod): sage: b = loads(dumps(a)) sage: len(b.f.cache) 1 - """ self._cache_name = '_cache__' + 'element_' + (name or f.__name__) self._cachedfunc = CachedFunction(f, classmethod=True, name=name, key=key, do_pickle=do_pickle) @@ -3300,7 +3271,6 @@ cdef class CachedInParentMethod(CachedMethod): sage: a.f.cache is b.f.cache is c.f._cachedmethod._get_instance_cache(c) True - """ default = {} if self._cachedfunc.do_pickle else NonpicklingDict() if inst is None: @@ -3339,10 +3309,10 @@ class FileCache(): :class:`FileCache` is a dictionary-like class which stores keys and values on disk. The keys take the form of a tuple ``(A,K)`` - - ``A`` is a tuple of objects ``t`` where each ``t`` is an - exact object which is uniquely identified by a short string. + - ``A`` -- tuple of objects ``t`` where each ``t`` is an + exact object which is uniquely identified by a short string - - ``K`` is a tuple of tuples ``(s,v)`` where ``s`` is a valid + - ``K`` -- tuple of tuples ``(s,v)`` where ``s`` is a valid variable name and ``v`` is an exact object which is uniquely identified by a short string with letters [a-zA-Z0-9-._] @@ -3496,7 +3466,7 @@ class FileCache(): def clear(self): """ - Clear all key, value pairs from self and unlink the associated files + Clear all key, value pairs from ``self`` and unlink the associated files from the file cache. EXAMPLES:: @@ -3586,7 +3556,6 @@ class FileCache(): Traceback (most recent call last): ... KeyError: ((1, 2), (('a', 4), ('b', 2))) - """ from sage.misc.persist import load @@ -3609,7 +3578,7 @@ class FileCache(): def __setitem__(self, key, value): """ - Sets ``self[key] = value`` and stores both key and value on + Set ``self[key] = value`` and stores both key and value on disk. EXAMPLES:: @@ -3638,7 +3607,7 @@ class FileCache(): def __delitem__(self, key): """ - Delete the key,value pair from self and unlink the associated + Delete the ``key, value`` pair from ``self`` and unlink the associated files from the file cache. EXAMPLES:: diff --git a/src/sage/misc/call.py b/src/sage/misc/call.py index bc428a95115..6c52c331c3b 100644 --- a/src/sage/misc/call.py +++ b/src/sage/misc/call.py @@ -35,7 +35,7 @@ def __init__(self, name, args, kwds): def __call__(self, x, *args): """ - Gets the ``self.name`` method from ``x``, calls it with + Get the ``self.name`` method from ``x``, calls it with ``self.args`` and ``args`` as positional parameters and ``self.kwds`` as keyword parameters, and returns the result. @@ -76,7 +76,7 @@ def __repr__(self): def __eq__(self, other): """ - Equality testing + Equality testing. EXAMPLES:: @@ -91,7 +91,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Equality testing + Equality testing. EXAMPLES:: @@ -106,7 +106,7 @@ def __ne__(self, other): def __hash__(self): """ - Hash value + Hash value. This method tries to ensure that, when two ``attrcall`` objects are equal, they have the same hash value. @@ -151,11 +151,11 @@ def attrcall(name, *args, **kwds): INPUT: - - ``name`` -- a string of the name of the method you - want to call + - ``name`` -- string of the name of the method you + want to call - - ``args, kwds`` -- arguments and keywords to be passed - to the method + - ``args, kwds`` -- arguments and keywords to be passed + to the method EXAMPLES:: diff --git a/src/sage/misc/callable_dict.pyx b/src/sage/misc/callable_dict.pyx index f46998a35a4..6a133afa918 100644 --- a/src/sage/misc/callable_dict.pyx +++ b/src/sage/misc/callable_dict.pyx @@ -36,7 +36,7 @@ cdef class CallableDict(dict): sage: d('zwei') 2 - In case the input is not in the dictionary, a :class:`ValueError` + In case the input is not in the dictionary, a :exc:`ValueError` is raised, for consistency with the function call syntax:: sage: d[1] @@ -56,7 +56,7 @@ cdef class CallableDict(dict): - ``x`` -- any hashable object - A :class:`ValueError` is raised if ``x`` is not in ``self``. + A :exc:`ValueError` is raised if ``x`` is not in ``self``. TESTS:: diff --git a/src/sage/misc/citation.pyx b/src/sage/misc/citation.pyx index aca83edf22c..fbe932ba49a 100644 --- a/src/sage/misc/citation.pyx +++ b/src/sage/misc/citation.pyx @@ -57,7 +57,7 @@ def get_systems(cmd): INPUT: - - ``cmd`` -- a string to run + - ``cmd`` -- string to run .. WARNING:: diff --git a/src/sage/misc/classcall_metaclass.pyx b/src/sage/misc/classcall_metaclass.pyx index 691f7fec01e..150eace4b9a 100644 --- a/src/sage/misc/classcall_metaclass.pyx +++ b/src/sage/misc/classcall_metaclass.pyx @@ -119,7 +119,7 @@ cdef class ClasscallMetaclass(NestedClassMetaclass): def _set_classcall(cls, function): r""" - Change dynamically the classcall function for this class + Change dynamically the classcall function for this class. EXAMPLES:: @@ -400,7 +400,7 @@ cdef class ClasscallMetaclass(NestedClassMetaclass): def __contains__(cls, x): r""" - This method implements membership testing for a class + This method implements membership testing for a class. Let ``cls`` be a class in :class:`ClasscallMetaclass`, and consider a call of the form:: @@ -449,14 +449,14 @@ cdef class ClasscallMetaclass(NestedClassMetaclass): def typecall(pytype cls, *args, **kwds): r""" - Object construction + Object construction. This is a faster equivalent to ``type.__call__(cls, )``. INPUT: - - ``cls`` -- the class used for constructing the instance. It must be - a builtin type or a new style class (inheriting from :class:`object`). + - ``cls`` -- the class used for constructing the instance; it must be + a builtin type or a new style class (inheriting from :class:`object`) EXAMPLES:: diff --git a/src/sage/misc/classgraph.py b/src/sage/misc/classgraph.py index acddb183909..aa4aafe18fa 100644 --- a/src/sage/misc/classgraph.py +++ b/src/sage/misc/classgraph.py @@ -14,20 +14,22 @@ def class_graph(top, depth=5, name_filter=None, classes=None, as_graph=True): """ - Return the class inheritance graph of a module, class, or object + Return the class inheritance graph of a module, class, or object. INPUT: - - ``top`` -- the module, class, or object to start with (e.g. ``sage``, ``Integer``, ``3``) - - ``depth`` -- maximal recursion depth within submodules (default: 5) - - ``name_filter`` -- e.g. 'sage.rings' to only consider classes in :mod:`sage.rings` - - ``classes`` -- optional dictionary to be filled in (it is also returned) - - ``as_graph`` -- a boolean (default: ``True``) + - ``top`` -- the module, class, or object to start with (e.g. ``sage``, + ``Integer``, ``3``) + - ``depth`` -- maximal recursion depth within submodules (default: 5) + - ``name_filter`` -- e.g. 'sage.rings' to only consider classes in + :mod:`sage.rings` + - ``classes`` -- (optional) dictionary to be filled in (it is also returned) + - ``as_graph`` -- boolean (default: ``True``) OUTPUT: - - An oriented graph, with class names as vertices, and an edge - from each class to each of its bases. + An oriented graph, with class names as vertices, and an edge + from each class to each of its bases. EXAMPLES: @@ -70,10 +72,10 @@ def class_graph(top, depth=5, name_filter=None, classes=None, as_graph=True): 'Polynomial_padic'], 'Polynomial_padic_flat': ['Polynomial_generic_dense', 'Polynomial_padic']} - .. note:: the ``classes`` and ``as_graph`` options are mostly + .. NOTE:: the ``classes`` and ``as_graph`` options are mostly intended for internal recursive use. - .. note:: ``class_graph`` does not yet handle nested classes + .. NOTE:: ``class_graph`` does not yet handle nested classes TESTS:: diff --git a/src/sage/misc/compat.py b/src/sage/misc/compat.py index 32a4f240a41..5f27aea06a0 100644 --- a/src/sage/misc/compat.py +++ b/src/sage/misc/compat.py @@ -56,7 +56,7 @@ def _find_library(name): def find_library(name): """ - Returns the shared library filename for a given library. + Return the shared library filename for a given library. The library name is given without any prefixes or suffixes--(e.g. just "Singular", not "libSingular", as shared library naming is @@ -70,7 +70,6 @@ def find_library(name): sage: from sage.misc.compat import find_library sage: find_library('giac') # needs sage.libs.giac '...giac...' - """ result = _find_library(name) diff --git a/src/sage/misc/constant_function.pyx b/src/sage/misc/constant_function.pyx index 4eb58d7599a..59cb785883d 100644 --- a/src/sage/misc/constant_function.pyx +++ b/src/sage/misc/constant_function.pyx @@ -84,7 +84,6 @@ cdef class ConstantFunction(SageObject): sage: loads(dumps(ConstantFunction(5))) == ConstantFunction(5) # indirect doctest True - """ return ConstantFunction, (self._value,) diff --git a/src/sage/misc/converting_dict.py b/src/sage/misc/converting_dict.py index 659bf223c50..684b729ea8c 100644 --- a/src/sage/misc/converting_dict.py +++ b/src/sage/misc/converting_dict.py @@ -61,9 +61,9 @@ class KeyConvertingDict(dict): INPUT: - ``key_conversion_function`` -- a function which will be - applied to all method arguments which represent keys. - - ``data`` -- optional dictionary or sequence of key-value pairs - to initialize this mapping. + applied to all method arguments which represent keys + - ``data`` -- (optional) dictionary or sequence of key-value pairs + to initialize this mapping EXAMPLES:: @@ -104,7 +104,7 @@ def __getitem__(self, key): INPUT: - - ``key`` -- A value identifying the element, will be converted. + - ``key`` -- a value identifying the element, will be converted EXAMPLES:: @@ -123,8 +123,8 @@ def __setitem__(self, key, value): INPUT: - - ``key`` -- A value identifying the element, will be converted. - - ``value`` -- The associated value, will be left unmodified. + - ``key`` -- a value identifying the element, will be converted + - ``value`` -- the associated value, will be left unmodified EXAMPLES:: @@ -143,7 +143,7 @@ def __delitem__(self, key): INPUT: - - ``key`` -- A value identifying the element, will be converted. + - ``key`` -- a value identifying the element, will be converted EXAMPLES:: @@ -163,7 +163,7 @@ def __contains__(self, key): INPUT: - - ``key`` -- A value identifying the element, will be converted. + - ``key`` -- a value identifying the element, will be converted EXAMPLES:: @@ -184,8 +184,8 @@ def pop(self, key, *args): INPUT: - - ``key`` -- A value identifying the element, will be converted. - - ``default`` -- The value to return if the element is not mapped, optional. + - ``key`` -- a value identifying the element, will be converted + - ``default`` -- the value to return if the element is not mapped, optional EXAMPLES:: @@ -211,8 +211,8 @@ def setdefault(self, key, default=None): INPUT: - - ``key`` -- A value identifying the element, will be converted. - - ``default`` -- The value to associate with the key. + - ``key`` -- a value identifying the element, will be converted + - ``default`` -- the value to associate with the key EXAMPLES:: @@ -232,10 +232,10 @@ def update(self, *args, **kwds): INPUT: - - ``key`` -- A value identifying the element, will be converted. - - ``args`` -- A single dict or sequence of pairs. - - ``kwds`` -- Named elements require that the conversion - function accept strings. + - ``key`` -- a value identifying the element, will be converted + - ``args`` -- a single dict or sequence of pairs + - ``kwds`` -- named elements require that the conversion + function accept strings EXAMPLES:: diff --git a/src/sage/misc/cython.py b/src/sage/misc/cython.py index 545e1227b0c..95491a5c623 100644 --- a/src/sage/misc/cython.py +++ b/src/sage/misc/cython.py @@ -88,33 +88,33 @@ def cython(filename, verbose=0, compile_message=False, INPUT: - - ``filename`` -- the name of the file to be compiled. Should end with - 'pyx'. + - ``filename`` -- the name of the file to be compiled; should end with + 'pyx' - - ``verbose`` (integer, default 0) -- level of verbosity. A negative + - ``verbose`` -- integer (default: 0); level of verbosity. A negative value ensures complete silence. - - ``compile_message`` (bool, default: ``False``) -- if True, print - ``'Compiling ...'`` to the standard error. + - ``compile_message`` -- boolean (default: ``False``); if ``True``, print + ``'Compiling ...'`` to the standard error - - ``use_cache`` (bool, default: ``False``) -- if True, check the + - ``use_cache`` -- boolean (default: ``False``); if ``True``, check the temporary build directory to see if there is already a corresponding .so file. If so, and if the .so file is newer than the Cython file, don't recompile, just reuse the .so file. - - ``create_local_c_file`` (bool, default: ``False``) -- if True, save a - copy of the ``.c`` or ``.cpp`` file in the current directory. + - ``create_local_c_file`` -- boolean (default: ``False``); if ``True``, save a + copy of the ``.c`` or ``.cpp`` file in the current directory - - ``annotate`` (bool, default: ``True``) -- if True, create an html file which + - ``annotate`` -- boolean (default: ``True``); if ``True``, create an html file which annotates the conversion from .pyx to .c. By default this is only created in the temporary directory, but if ``create_local_c_file`` is also True, then save a copy of the .html file in the current directory. - - ``sage_namespace`` (bool, default: ``True``) -- if True, import - ``sage.all``. + - ``sage_namespace`` -- boolean (default: ``True``); if ``True``, import + ``sage.all`` - - ``create_local_so_file`` (bool, default: ``False``) -- if True, save a - copy of the compiled .so file in the current directory. + - ``create_local_so_file`` -- boolean (default: ``False``); if ``True``, save a + copy of the compiled .so file in the current directory OUTPUT: a tuple ``(name, dir)`` where ``name`` is the name of the compiled module and ``dir`` is the directory containing @@ -523,7 +523,7 @@ def f(%s): """ % (v, expr) if verbose > 0: print(s) - tmpfile = tmp_filename(ext=".pyx") + tmpfile = tmp_filename(ext='.pyx') with open(tmpfile, 'w') as f: f.write(s) @@ -538,19 +538,17 @@ def f(%s): def cython_import(filename, **kwds): """ Compile a file containing Cython code, then import and return the - module. Raises an ``ImportError`` if anything goes wrong. + module. Raises an :exc:`ImportError` if anything goes wrong. INPUT: - - ``filename`` -- a string; name of a file that contains Cython + - ``filename`` -- string; name of a file that contains Cython code See the function :func:`sage.misc.cython.cython` for documentation for the other inputs. - OUTPUT: - - - the module that contains the compiled Cython code. + OUTPUT: the module that contains the compiled Cython code """ name, build_dir = cython(filename, **kwds) @@ -574,11 +572,11 @@ def cython_import_all(filename, globals, **kwds): from module import * - Raises an ``ImportError`` exception if anything goes wrong. + Raises an :exc:`ImportError` exception if anything goes wrong. INPUT: - - ``filename`` -- a string; name of a file that contains Cython + - ``filename`` -- string; name of a file that contains Cython code """ m = cython_import(filename, **kwds) @@ -621,7 +619,7 @@ def compile_and_load(code, **kwds): INPUT: - ``code`` -- string containing code that could be in a .pyx file - that is attached or put in a %cython block in the notebook. + that is attached or put in a %cython block in the notebook OUTPUT: a module, which results from compiling the given code and importing it @@ -656,7 +654,7 @@ def compile_and_load(code, **kwds): sage: module.evaluate_at_power_of_gen(x^3 + x - 7, 5) # long time x^15 + x^5 - 7 """ - tmpfile = tmp_filename(ext=".pyx") + tmpfile = tmp_filename(ext='.pyx') with open(tmpfile, 'w') as f: f.write(code) return cython_import(tmpfile, **kwds) @@ -689,7 +687,7 @@ def cython_compile(code, **kwds): Need to create a clever caching system so code only gets compiled once. """ - tmpfile = tmp_filename(ext=".pyx") + tmpfile = tmp_filename(ext='.pyx') with open(tmpfile, 'w') as f: f.write(code) return cython_import_all(tmpfile, get_globals(), **kwds) diff --git a/src/sage/misc/decorators.py b/src/sage/misc/decorators.py index d0ea445207c..e91acf5b5a9 100644 --- a/src/sage/misc/decorators.py +++ b/src/sage/misc/decorators.py @@ -153,7 +153,6 @@ def sage_wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES): sage: g = square(f) sage: g(3) # this line used to fail for some people if these command were manually entered on the sage prompt 81 - """ # TRAC 9919: Workaround for bug in @update_wrapper when used with # non-function callables. @@ -230,7 +229,7 @@ def __init__(self, precedence): INPUT: - ``precedence`` -- one of ``'add'``, ``'multiply'``, or ``'or'`` - indicating the new operator's precedence in the order of operations. + indicating the new operator's precedence in the order of operations """ self.precedence = precedence @@ -373,7 +372,7 @@ def __init__(self, name, **options): def __call__(self, func): """ - Returns a wrapper around func + Return a wrapper around ``func``. EXAMPLES:: @@ -486,7 +485,6 @@ def __call__(self, func): sage: f2 = o(f) sage: f2(alpha=1) () [('__original_opts', {'alpha': 1}), ('alpha', 1), ('rgbcolor', (0, 0, 1))] - """ @sage_wraps(func) def wrapper(*args, **kwds): @@ -581,8 +579,8 @@ def __init__(self, deprecated=None, deprecation=None, **renames): INPUT: - - ``deprecation`` -- integer. The github issue number where the - deprecation was introduced. + - ``deprecation`` -- integer; the github issue number where the + deprecation was introduced - the rest of the arguments is a list of keyword arguments in the form ``renamed_option='existing_option'``. This will have the @@ -669,12 +667,10 @@ class specialize: INPUT: - - ``*args``, ``**kwargs`` -- arguments to specialize the function for. - - OUTPUT: + - ``*args``, ``**kwargs`` -- arguments to specialize the function for - - a decorator that accepts a function ``f`` and specializes it - with ``*args`` and ``**kwargs`` + OUTPUT: a decorator that accepts a function ``f`` and specializes it + with ``*args`` and ``**kwargs`` EXAMPLES:: diff --git a/src/sage/misc/defaults.py b/src/sage/misc/defaults.py index 3d75021d198..ea2719a2bf6 100644 --- a/src/sage/misc/defaults.py +++ b/src/sage/misc/defaults.py @@ -29,10 +29,10 @@ def variable_names(n, name=None): INPUT: - - ``n`` a non-negative Integer; the number of variable names to - output + - ``n`` -- a nonnegative Integer; the number of variable names to + output - ``names`` a string (default: ``None``); the root of the variable - name. + name EXAMPLES:: @@ -61,10 +61,10 @@ def latex_variable_names(n, name=None): INPUT: - - ``n`` a non-negative Integer; the number of variable names to + - ``n`` -- a nonnegative Integer; the number of variable names to output - ``names`` a string (default: ``None``); the root of the variable - name. + name EXAMPLES:: diff --git a/src/sage/misc/derivative.pyx b/src/sage/misc/derivative.pyx index 8c0bcbf3c3d..24ceb09a1db 100644 --- a/src/sage/misc/derivative.pyx +++ b/src/sage/misc/derivative.pyx @@ -68,10 +68,10 @@ def derivative_parse(args): INPUT: - args -- any iterable, interpreted as a sequence of 'variables' and - iteration counts. An iteration count is any integer type (python int - or Sage Integer). Iteration counts must be non-negative. Any object - which is not an integer is assumed to be a variable. + - ``args`` -- any iterable, interpreted as a sequence of 'variables' and + iteration counts. An iteration count is any integer type (python int + or Sage Integer). Iteration counts must be nonnegative. Any object + which is not an integer is assumed to be a variable. OUTPUT: @@ -114,7 +114,7 @@ def derivative_parse(args): sage: derivative_parse([-1]) Traceback (most recent call last): ... - ValueError: derivative counts must be non-negative + ValueError: derivative counts must be nonnegative Special case with single list argument provided:: @@ -145,7 +145,6 @@ def derivative_parse(args): [] sage: derivative_parse([x, y, x, 2, 2, y]) [x, y, x, x, None, None, y] - """ if not args: return [None] @@ -161,7 +160,7 @@ def derivative_parse(args): # process iteration count count = int(arg) if count < 0: - raise ValueError("derivative counts must be non-negative") + raise ValueError("derivative counts must be nonnegative") if not got_var: var = None for i from 0 <= i < count: @@ -182,12 +181,12 @@ def derivative_parse(args): def multi_derivative(F, args): r""" - Calls F._derivative(var) for a sequence of variables specified by args. + Call F._derivative(var) for a sequence of variables specified by args. INPUT: - - ``F`` -- any object with a ``_derivative(var)`` method. - - ``args`` -- any tuple that can be processed by :func:`derivative_parse`. + - ``F`` -- any object with a ``_derivative(var)`` method + - ``args`` -- any tuple that can be processed by :func:`derivative_parse` EXAMPLES:: diff --git a/src/sage/misc/dev_tools.py b/src/sage/misc/dev_tools.py index da0a996424b..3f90fde6031 100644 --- a/src/sage/misc/dev_tools.py +++ b/src/sage/misc/dev_tools.py @@ -23,11 +23,11 @@ def runsnake(command): """ - Graphical profiling with ``runsnake`` + Graphical profiling with ``runsnake``. INPUT: - - ``command`` -- the command to be run as a string. + - ``command`` -- the command to be run as a string EXAMPLES:: @@ -60,7 +60,6 @@ def runsnake(command): - `The runsnake website `_ - ``%prun`` - :class:`Profiler` - """ import cProfile from sage.misc.temporary_file import tmp_filename @@ -80,10 +79,10 @@ def import_statement_string(module, names, lazy): - ``module`` -- the name of a module - - ``names`` -- a list of 2-tuples containing names and alias to + - ``names`` -- list of 2-tuples containing names and alias to import - - ``lazy`` -- a boolean: whether to return a lazy import statement + - ``lazy`` -- boolean; whether to return a lazy import statement EXAMPLES:: @@ -143,7 +142,7 @@ def load_submodules(module=None, exclude_pattern=None): - ``module`` -- an optional module - ``exclude_pattern`` -- an optional regular expression pattern of module - names that have to be excluded. + names that have to be excluded EXAMPLES:: @@ -368,16 +367,16 @@ def import_statements(*objects, **kwds): INPUT: - - ``*objects`` -- a sequence of objects or comma-separated strings of names. + - ``*objects`` -- a sequence of objects or comma-separated strings of names - - ``lazy`` -- a boolean (default: ``False``) - Whether to print a lazy import statement. + - ``lazy`` -- boolean (default: ``False``); whether to print a lazy import + statement - - ``verbose`` -- a boolean (default: ``True``) - Whether to print information in case of ambiguity. + - ``verbose`` -- boolean (default: ``True``); whether to print information + in case of ambiguity - - ``answer_as_str`` -- a boolean (default: ``False``) - If ``True`` return a string instead of printing the statement. + - ``answer_as_str`` -- boolean (default: ``False``); if ``True`` return a + string instead of printing the statement EXAMPLES:: diff --git a/src/sage/misc/edit_module.py b/src/sage/misc/edit_module.py index cf39a6d2675..88132947a2e 100644 --- a/src/sage/misc/edit_module.py +++ b/src/sage/misc/edit_module.py @@ -214,7 +214,7 @@ def edit(obj, editor=None, bg=None): INPUT: - - editor -- str (default: None); If given, use specified editor. + - editor -- string (default: ``None``); if given, use specified editor. Choice is stored for next time. AUTHOR: diff --git a/src/sage/misc/explain_pickle.py b/src/sage/misc/explain_pickle.py index 0f5537a87d0..664a86cd5bc 100644 --- a/src/sage/misc/explain_pickle.py +++ b/src/sage/misc/explain_pickle.py @@ -184,25 +184,25 @@ def explain_pickle(pickle=None, file=None, compress=True, **kwargs): INPUT: - - ``pickle`` -- the pickle to explain, as a string (default: ``None``) - - ``file`` -- a filename of a pickle (default: ``None``) - - ``compress`` -- if ``False``, don't attempt to decompress the pickle - (default: ``True``) - - ``in_current_sage`` -- if ``True``, produce potentially simpler code that is - tied to the current version of Sage. (default: ``False``) - - ``default_assumptions`` -- if ``True``, produce potentially simpler code that - assumes that generic unpickling code will be - used. This code may not actually work. - (default: ``False``) - - ``eval`` -- if ``True``, then evaluate the resulting code and return the - evaluated result. (default: ``False``) - - ``preparse`` -- if ``True``, then produce code to be evaluated with - Sage's preparser; if ``False``, then produce standard - Python code; if ``None``, then produce code that will work - either with or without the preparser. (default: ``True``) - - ``pedantic`` -- if ``True``, then carefully ensures that the result has - at least as much sharing as the result of cPickle - (it may have more, for immutable objects). (default: ``False``) + - ``pickle`` -- string (default: ``None``); the pickle to explain + - ``file`` -- a filename of a pickle (default: ``None``) + - ``compress`` -- boolean (default: ``True``); if ``False``, don't attempt + to decompress the pickle + - ``in_current_sage`` -- boolean (default: ``False``); if ``True``, + produce potentially simpler code that is tied to the current version of + Sage + - ``default_assumptions`` -- boolean (default: ``False``); if ``True``, + produce potentially simpler code that assumes that generic unpickling + code will be used. This code may not actually work. + - ``eval`` -- boolean (default: ``False``); if ``True``, then evaluate the + resulting code and return the evaluated result + - ``preparse`` -- if ``True``, then produce code to be evaluated with + Sage's preparser; if ``False``, then produce standard + Python code; if ``None``, then produce code that will work + either with or without the preparser. (default: ``True``) + - ``pedantic`` -- boolean (default: ``False``); if ``True``, then carefully + ensures that the result has at least as much sharing as the result of + cPickle (it may have more, for immutable objects) Exactly one of ``pickle`` (a string containing a pickle) or ``file`` (the filename of a pickle) must be provided. @@ -2482,7 +2482,7 @@ def unpickle_instantiate(fn, args): def unpickle_persistent(s): r""" - Takes an integer index and returns the persistent object with that + Take an integer index and return the persistent object with that index; works by calling whatever callable is stored in ``unpickle_persistent_loader``. Used by :func:`explain_pickle`. @@ -2498,7 +2498,7 @@ def unpickle_persistent(s): def unpickle_extension(code): r""" - Takes an integer index and returns the extension object with that + Take an integer index and return the extension object with that index. Used by :func:`explain_pickle`. EXAMPLES:: diff --git a/src/sage/misc/fast_methods.pyx b/src/sage/misc/fast_methods.pyx index 3c7e77c617a..b5e6cc41516 100644 --- a/src/sage/misc/fast_methods.pyx +++ b/src/sage/misc/fast_methods.pyx @@ -101,7 +101,6 @@ cdef class WithEqualityById: True sage: a is d False - """ def __hash__(self): """ @@ -226,7 +225,6 @@ cdef class FastHashable_class: sage: H = FastHashable_class(123) sage: hash(H) # indirect doctest 123 - """ return self._hash diff --git a/src/sage/misc/flatten.py b/src/sage/misc/flatten.py index 8d46445a687..df553c5aba6 100644 --- a/src/sage/misc/flatten.py +++ b/src/sage/misc/flatten.py @@ -10,13 +10,11 @@ def flatten(in_list, ltypes=(list, tuple), max_level=sys.maxsize): INPUT: - - ``in_list`` -- a list or tuple - - ``ltypes`` -- optional list of particular types to flatten + - ``in_list`` -- list or tuple + - ``ltypes`` -- (optional) list of particular types to flatten - ``max_level`` -- the maximum level to flatten - OUTPUT: - - a flat list of the entries of ``in_list`` + OUTPUT: a flat list of the entries of ``in_list`` EXAMPLES:: diff --git a/src/sage/misc/fpickle.pyx b/src/sage/misc/fpickle.pyx index 752a2a0093a..fd192f1bf02 100644 --- a/src/sage/misc/fpickle.pyx +++ b/src/sage/misc/fpickle.pyx @@ -74,11 +74,9 @@ def pickle_function(func): INPUT: - func -- a Python function + - ``func`` -- a Python function - OUTPUT: - - a string + OUTPUT: string EXAMPLES:: diff --git a/src/sage/misc/function_mangling.pyx b/src/sage/misc/function_mangling.pyx index d84f6c9bc62..8cf4d6e2efa 100644 --- a/src/sage/misc/function_mangling.pyx +++ b/src/sage/misc/function_mangling.pyx @@ -80,11 +80,10 @@ cdef class ArgumentFixer: INPUT: - - f -- a function - - classmethod -- boolean (default: ``False``) -- True if the function - is a classmethod and therefore the first - argument is expected to be the class instance. - In that case, we ignore the first argument. + - ``f`` -- a function + - ``classmethod`` -- boolean (default: ``False``); ``True`` if the function + is a classmethod and therefore the first argument is expected to be the + class instance. In that case, we ignore the first argument. EXAMPLES:: @@ -111,7 +110,6 @@ cdef class ArgumentFixer: sage: af = ArgumentFixer(one.__init__, classmethod=True) sage: af.fix_to_pos(1,2,3,a=31,b=2,n=3) ((1, 2, 3), (('a', 31), ('b', 2), ('n', 3))) - """ def __init__(self, f, classmethod = False): try: @@ -169,9 +167,7 @@ cdef class ArgumentFixer: - any positional and named arguments. - OUTPUT: - - We return a tuple + OUTPUT: we return a tuple `(e_1, e_2, ..., e_k), ((n_1, v_1), ... , (n_m, v_m))` @@ -208,7 +204,6 @@ cdef class ArgumentFixer: ((4, 5, 6), (('a', 1), ('b', 2), ('c', 3), ('e', 16), ('f', 14))) sage: AF.fix_to_named(1,2,f=14) ((), (('a', 1), ('b', 2), ('c', 3), ('f', 14))) - """ cdef list ARGS = [] cdef tuple arg_names = self._arg_names @@ -238,11 +233,9 @@ cdef class ArgumentFixer: INPUT: - Any positional or named arguments - - OUTPUT: + - ``*args``, ``**kwds`` -- any positional or named arguments - We return a tuple + OUTPUT: we return a tuple `(e_1, e_2, ..., e_k), ((n_1, v_1), ... , (n_m, v_m))` diff --git a/src/sage/misc/functional.py b/src/sage/misc/functional.py index 99ddcd3c772..7286501c0f1 100644 --- a/src/sage/misc/functional.py +++ b/src/sage/misc/functional.py @@ -193,7 +193,7 @@ def coerce(P, x): def cyclotomic_polynomial(n, var='x'): """ - Return the `n^{th}` cyclotomic polynomial. + Return the `n`-th cyclotomic polynomial. EXAMPLES:: @@ -570,7 +570,7 @@ def symbolic_sum(expression, *args, **kwds): sage: sum(x, x, 1r, 5r) # needs sage.symbolic 15 - .. note:: + .. NOTE:: #. Sage can currently only understand a subset of the output of Maxima, Maple and Mathematica, so even if the chosen backend can perform the summation the @@ -584,7 +584,6 @@ def symbolic_sum(expression, *args, **kwds): 4 sage: sum([[1], [2]], start=[]) [1, 2] - """ if hasattr(expression, 'sum'): return expression.sum(*args, **kwds) @@ -617,7 +616,7 @@ def symbolic_prod(expression, *args, **kwds): - ``'sympy'`` -- use SymPy - - ``hold`` -- (default: ``False``) if ``True`` don't evaluate + - ``hold`` -- boolean (default: ``False``); if ``True`` don't evaluate EXAMPLES:: @@ -639,7 +638,6 @@ def symbolic_prod(expression, *args, **kwds): 1/factorial(n + 1) sage: product(f(i), i, 1, n).log().log_expand() sum(log(f(i)), i, 1, n) - """ from .misc_c import prod as c_prod if hasattr(expression, 'prod'): @@ -782,7 +780,6 @@ def integral(x, *args, **kwds): ... sage: result # needs sage.symbolic -1/4 - """ if hasattr(x, 'integral'): return x.integral(*args, **kwds) @@ -1092,8 +1089,8 @@ def log(*args, **kwds): sage: log(F(9), 3) 2 - The log function also works for p-adics (see documentation for - p-adics for more information):: + The log function also works for `p`-adics (see documentation for + `p`-adics for more information):: sage: R = Zp(5); R # needs sage.rings.padics 5-adic Ring with capped relative precision 20 @@ -1191,7 +1188,7 @@ def minimal_polynomial(x, var='x'): def multiplicative_order(x): r""" Return the multiplicative order of ``x``, if ``x`` is a unit, or - raise :class:`ArithmeticError` otherwise. + raise :exc:`ArithmeticError` otherwise. EXAMPLES:: @@ -1824,22 +1821,21 @@ def _do_sqrt(x, prec=None, extend=True, all=False): INPUT: - - ``x`` -- a number - - - ``prec`` -- a positive integer (default: ``None``); when specified, - compute the square root with ``prec`` bits of precision + - ``x`` -- a number - - ``extend`` -- bool (default: ``True``); this is a placeholder, and is - always ignored since in the symbolic ring everything - has a square root. + - ``prec`` -- positive integer (default: ``None``); when specified, + compute the square root with ``prec`` bits of precision - - ``extend`` -- bool (default: ``True``); whether to extend - the base ring to find roots. The extend parameter is ignored if - ``prec`` is a positive integer. + - ``extend`` -- boolean (default: ``True``); this is a placeholder, and is + always ignored since in the symbolic ring everything + has a square root - - ``all`` -- bool (default: ``False``); whether to return - a list of all the square roots of ``x``. + - ``extend`` -- boolean (default: ``True``); whether to extend + the base ring to find roots. The extend parameter is ignored if + ``prec`` is a positive integer. + - ``all`` -- boolean (default: ``False``); whether to return + a list of all the square roots of ``x`` EXAMPLES:: @@ -1883,18 +1879,18 @@ def sqrt(x, *args, **kwds): r""" INPUT: - - ``x`` -- a number + - ``x`` -- a number - - ``prec`` -- integer (default: ``None``): if ``None``, returns - an exact square root; otherwise returns a numerical square root if - necessary, to the given bits of precision. + - ``prec`` -- integer (default: ``None``); if ``None``, returns + an exact square root. Otherwise returns a numerical square root if + necessary, to the given bits of precision. - - ``extend`` -- bool (default: ``True``); this is a placeholder, and - is always ignored or passed to the ``sqrt`` method of ``x``, - since in the symbolic ring everything has a square root. + - ``extend`` -- boolean (default: ``True``); this is a placeholder, and + is always ignored or passed to the ``sqrt`` method of ``x``, + since in the symbolic ring everything has a square root - - ``all`` -- bool (default: ``False``); if ``True``, return all - square roots of ``self``, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of ``self``, instead of just one EXAMPLES:: diff --git a/src/sage/misc/gperftools.py b/src/sage/misc/gperftools.py index d3a55a7e9d6..8e89dadef6d 100644 --- a/src/sage/misc/gperftools.py +++ b/src/sage/misc/gperftools.py @@ -52,7 +52,7 @@ class Profiler(SageObject): def __init__(self, filename=None): """ - Interface to the gperftools profiler + Interface to the gperftools profiler. INPUT: @@ -73,11 +73,9 @@ def __init__(self, filename=None): def filename(self): """ - Return the file name + Return the file name. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -90,11 +88,9 @@ def filename(self): def _repr_(self): """ - Return string representation - - OUTPUT: + Return string representation. - String. + OUTPUT: string EXAMPLES:: @@ -106,11 +102,9 @@ def _repr_(self): def _libc(self): """ - Return libc - - OUTPUT: + Return libc. - A ctypes shared library handle. + OUTPUT: a ctypes shared library handle EXAMPLES:: @@ -130,11 +124,9 @@ def _libc(self): def _libprofiler(self): """ - Return libprofiler + Return libprofiler. - OUTPUT: - - A ctypes shared library handle. + OUTPUT: a ctypes shared library handle EXAMPLES:: @@ -155,7 +147,7 @@ def _libprofiler(self): def start(self): """ - Start profiling + Start profiling. EXAMPLES:: @@ -176,7 +168,7 @@ def start(self): def stop(self): """ - Stop the CPU profiler + Stop the CPU profiler. EXAMPLES:: @@ -203,7 +195,7 @@ def _pprof(self): OUTPUT: String. The name of the gperftools ``pprof`` utility. A - ``OSError`` is raised if it cannot be found. + :exc:`OSError` is raised if it cannot be found. EXAMPLES:: @@ -235,9 +227,7 @@ def _executable(self): """ Return the name of the Sage Python interpreter. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -250,14 +240,13 @@ def _executable(self): def _call_pprof(self, *args, **kwds): """ - Run the pprof binary + Run the pprof binary. INPUT: - - ``args`` -- list of strings. The arguments to ``pprof``. + - ``args`` -- list of strings; the arguments to ``pprof`` - - ``kwds`` -- keyword arguments passed to - ``subprocess.check_call``. + - ``kwds`` -- keyword arguments passed to ``subprocess.check_call`` EXAMPLES:: @@ -273,11 +262,9 @@ def _call_pprof(self, *args, **kwds): def top(self, cumulative=True): """ - Print text report - - OUTPUT: + Print text report. - Nothing. A textual report is printed to stdout. + OUTPUT: nothing; a textual report is printed to stdout EXAMPLES:: @@ -303,15 +290,15 @@ def save(self, filename, cumulative=True, verbose=True): INPUT: - - ``filename`` -- string. The filename to save at. Must end + - ``filename`` -- string; the filename to save at. Must end with one of ``.dot``, ``.ps``, ``.pdf``, ``.svg``, ``.gif``, or ``.txt`` to specify the output file format. - - ``cumulative`` -- boolean (default: - ``True``). Whether to return cumulative timings. + - ``cumulative`` -- boolean (default: ``True``); whether to return + cumulative timings - - ``verbose`` -- boolean (default: - ``True``). Whether to print informational messages. + - ``verbose`` -- boolean (default: ``True``); whether to print + informational messages EXAMPLES:: @@ -351,9 +338,9 @@ def crun(s, evaluator): """ Profile single statement. - - ``s`` -- string. Sage code to profile. + - ``s`` -- string; Sage code to profile - - ``evaluator`` -- callable to evaluate. + - ``evaluator`` -- callable to evaluate EXAMPLES:: diff --git a/src/sage/misc/html.py b/src/sage/misc/html.py index 1fe74334d53..8732acdede0 100644 --- a/src/sage/misc/html.py +++ b/src/sage/misc/html.py @@ -47,7 +47,7 @@ class HtmlFragment(str, SageObject): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -73,11 +73,9 @@ def math_parse(s): INPUT: - - ``s`` -- a string + - ``s`` -- string - OUTPUT: - - A :class:`HtmlFragment` instance. + OUTPUT: :class:`HtmlFragment` Specifically this method does the following: @@ -96,7 +94,6 @@ def math_parse(s): This is \[2+2\]. sage: print(sage.misc.html.math_parse(r'\$2+2\$ is rendered to $2+2$.')) $2+2$ is rendered to \(2+2\). - """ # Below t always has the "parsed so far" version of s, and s is # just the part of the original input s that hasn't been parsed. @@ -166,7 +163,7 @@ def __init__(self, y): INPUT: - - ``y`` -- a string + - ``y`` -- string Note that no error checking is done on the type of ``y``. @@ -175,7 +172,7 @@ def __init__(self, y): sage: from sage.misc.html import MathJaxExpr sage: jax = MathJaxExpr(3); jax # indirect doctest 3 - sage: TestSuite(jax).run(skip ="_test_pickling") + sage: TestSuite(jax).run(skip ='_test_pickling') """ self.__y = y @@ -244,14 +241,12 @@ def __call__(self, x, combine_all=False): - ``x`` -- a Sage object - - ``combine_all`` -- boolean (Default: ``False``): If ``combine_all`` is - ``True`` and the input is a tuple, then it does not return a tuple + - ``combine_all`` -- boolean (default: ``False``); if ``combine_all`` + is ``True`` and the input is a tuple, then it does not return a tuple and instead returns a string with all the elements separated by - a single space. + a single space - OUTPUT: - - A :class:`MathJaxExpr` + OUTPUT: :class:`MathJaxExpr` EXAMPLES:: @@ -271,24 +266,22 @@ def eval(self, x, globals=None, locals=None, mode='display', combine_all=False): - ``x`` -- a Sage object - - ``globals`` -- a globals dictionary + - ``globals`` -- a globals dictionary - - ``locals`` -- extra local variables used when - evaluating Sage code in ``x``. + - ``locals`` -- extra local variables used when + evaluating Sage code in ``x`` - - ``mode`` -- string (default: ``'display'``): - ``'display'`` for displaymath, ``'inline'`` for inline - math, or ``'plain'`` for just the LaTeX code without the - surrounding html and script tags. + - ``mode`` -- string (default: ``'display'``); + ``'display'`` for displaymath, ``'inline'`` for inline + math, or ``'plain'`` for just the LaTeX code without the + surrounding html and script tags - - ``combine_all`` -- boolean (Default: ``False``): If ``combine_all`` is - ``True`` and the input is a tuple, then it does not return a tuple + - ``combine_all`` -- boolean (default: ``False``); if ``combine_all`` + is ``True`` and the input is a tuple, then it does not return a tuple and instead returns a string with all the elements separated by - a single space. - - OUTPUT: + a single space - A :class:`MathJaxExpr` + OUTPUT: :class:`MathJaxExpr` EXAMPLES:: @@ -390,11 +383,9 @@ class HTMLFragmentFactory(SageObject): def _repr_(self): """ - Return string representation + Return string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -405,12 +396,12 @@ def _repr_(self): def __call__(self, obj, concatenate=True, strict=False): r""" - Construct a HTML fragment + Construct a HTML fragment. INPUT: - ``obj`` -- anything. An object for which you want an HTML - representation. + representation - ``concatenate`` -- if ``True``, combine HTML representations of elements of the container ``obj`` @@ -418,9 +409,7 @@ def __call__(self, obj, concatenate=True, strict=False): - ``strict`` -- if ``True``, construct an HTML representation of ``obj`` even if ``obj`` is a string - OUTPUT: - - A :class:`HtmlFragment` instance. + OUTPUT: :class:`HtmlFragment` EXAMPLES:: @@ -483,18 +472,16 @@ def __call__(self, obj, concatenate=True, strict=False): def eval(self, s, locals=None): r""" - Evaluate embedded tags + Evaluate embedded tags. INPUT: - - ``s`` -- string. + - ``s`` -- string - - ``globals`` -- dictionary. The global variables when + - ``globals`` -- dictionary; the global variables when evaluating ``s``. Default: the current global variables. - OUTPUT: - - A :class:`HtmlFragment` instance. + OUTPUT: :class:`HtmlFragment` EXAMPLES:: @@ -525,22 +512,20 @@ def eval(self, s, locals=None): def iframe(self, url, height=400, width=800): r""" - Generate an iframe HTML fragment + Generate an iframe HTML fragment. INPUT: - - ``url`` -- string. A url, either with or without URI scheme - (defaults to "http"), or an absolute file path. - - - ``height`` -- the number of pixels for the page height. - Defaults to 400. + - ``url`` -- string; a url, either with or without URI scheme + (defaults to "http"), or an absolute file path - - ``width`` -- the number of pixels for the page width. - Defaults to 800. + - ``height`` -- the number of pixels for the page height + Defaults to 400 - OUTPUT: + - ``width`` -- the number of pixels for the page width + Defaults to 800 - A :class:`HtmlFragment` instance. + OUTPUT: :class:`HtmlFragment` EXAMPLES:: @@ -586,8 +571,8 @@ def pretty_print_default(enable=True): INPUT: - - ``enable`` -- bool (default: ``True``). If ``True``, turn on - pretty printing; if ``False``, turn it off. + - ``enable`` -- boolean (default: ``True``); if ``True``, turn on + pretty printing. If ``False``, turn it off. EXAMPLES:: diff --git a/src/sage/misc/inline_fortran.py b/src/sage/misc/inline_fortran.py index 82da6982bec..ccd4b1da87c 100644 --- a/src/sage/misc/inline_fortran.py +++ b/src/sage/misc/inline_fortran.py @@ -77,14 +77,13 @@ def __call__(self, *args, **kwds): def eval(self, x, globals=None, locals=None): """ - Compile fortran code ``x`` and adds the functions in it to - ``globals``. + Compile fortran code ``x`` and adds the functions in it to ``globals``. INPUT: - - ``x`` -- Fortran code + - ``x`` -- fortran code - - ``globals`` -- a dict to which to add the functions from the + - ``globals`` -- dictionary to which to add the functions from the fortran module - ``locals`` -- ignored diff --git a/src/sage/misc/instancedoc.pyx b/src/sage/misc/instancedoc.pyx index 852cde57220..4641b53b13d 100644 --- a/src/sage/misc/instancedoc.pyx +++ b/src/sage/misc/instancedoc.pyx @@ -137,12 +137,12 @@ cdef class InstanceDocDescriptor: INPUT: - - ``classdoc`` -- (string) class documentation + - ``classdoc`` -- string; class documentation - ``instancedoc`` -- (method) documentation for an instance - - ``attr`` -- (string, default ``__doc__``) attribute name to use - for custom docstring on the instance. + - ``attr`` -- string (default: ``__doc__``); attribute name to use + for custom docstring on the instance EXAMPLES:: @@ -171,7 +171,7 @@ cdef class InstanceDocDescriptor: cdef instancedoc cdef attr - def __init__(self, classdoc, instancedoc, attr="__doc__"): + def __init__(self, classdoc, instancedoc, attr='__doc__'): """ TESTS:: diff --git a/src/sage/misc/latex.py b/src/sage/misc/latex.py index 32aa0c94c66..2d5c6ae7475 100644 --- a/src/sage/misc/latex.py +++ b/src/sage/misc/latex.py @@ -66,11 +66,11 @@ def list_function(x): r""" - Returns the LaTeX code for a list ``x``. + Return the LaTeX code for a list ``x``. INPUT: - - ``x`` -- a list + - ``x`` -- list EXAMPLES:: @@ -96,13 +96,13 @@ def list_function(x): def tuple_function(x, combine_all=False): r""" - Returns the LaTeX code for a tuple ``x``. + Return the LaTeX code for a tuple ``x``. INPUT: - - ``x`` -- a tuple + - ``x`` -- tuple - - ``combine_all`` -- boolean (default: ``False``) If ``combine_all`` is + - ``combine_all`` -- boolean (default: ``False``); if ``combine_all`` is ``True``, then it does not return a tuple and instead returns a string with all the elements separated by a single space. It does not collapse tuples which are inside tuples. @@ -127,7 +127,7 @@ def tuple_function(x, combine_all=False): def bool_function(x): r""" - Returns the LaTeX code for a boolean ``x``. + Return the LaTeX code for a boolean ``x``. INPUT: @@ -146,7 +146,7 @@ def bool_function(x): def builtin_constant_function(x): r""" - Returns the LaTeX code for a builtin constant ``x``. + Return the LaTeX code for a builtin constant ``x``. INPUT: @@ -165,14 +165,13 @@ def builtin_constant_function(x): '\\mbox{\\rm NotImplemented}' sage: builtin_constant_function(Ellipsis) '\\mbox{\\rm Ellipsis}' - """ return "\\mbox{\\rm %s}" % x def None_function(x): r""" - Returns the LaTeX code for ``None``. + Return the LaTeX code for ``None``. INPUT: @@ -210,9 +209,9 @@ def str_function(x): INPUT: - - ``x`` -- a string + - ``x`` -- string - OUTPUT: A string + OUTPUT: string EXAMPLES:: @@ -256,7 +255,7 @@ def dict_function(x): INPUT: - - ``x`` -- a dictionary + - ``x`` -- dictionary EXAMPLES:: @@ -281,7 +280,7 @@ def dict_function(x): def float_function(x): r""" - Returns the LaTeX code for a python float ``x``. + Return the LaTeX code for a python float ``x``. INPUT: @@ -336,12 +335,10 @@ class LatexExpr(str): INPUT: - - ``str`` -- a string with valid math mode LaTeX code (or something - which can be converted to such a string). - - OUTPUT: + - ``str`` -- string with valid math mode LaTeX code (or something + which can be converted to such a string) - - :class:`LatexExpr` wrapping the string representation of the input. + OUTPUT: :class:`LatexExpr` wrapping the string representation of the input EXAMPLES:: @@ -505,7 +502,7 @@ class _Latex_prefs_object(SageObject): An object that holds LaTeX global preferences. """ def __init__(self, bb=False, delimiters=["(", ")"], - matrix_column_alignment="r"): + matrix_column_alignment='r'): """ Define an object that holds LaTeX global preferences. @@ -513,7 +510,7 @@ def __init__(self, bb=False, delimiters=["(", ")"], sage: from sage.misc.latex import _Latex_prefs_object sage: latex_prefs = _Latex_prefs_object() - sage: TestSuite(latex_prefs).run(skip ="_test_pickling") + sage: TestSuite(latex_prefs).run(skip ='_test_pickling') """ self.__option = {} self.__option["blackboard_bold"] = bb @@ -596,7 +593,7 @@ def latex_extra_preamble(): def _run_latex_(filename, debug=False, density=150, engine=None, png=False, do_in_background=False): """ This runs LaTeX on the TeX file "filename.tex". It produces files - ``filename.dvi`` (or ``filename.pdf``` if ``engine`` is either ``'pdflatex'``, + ``filename.dvi`` (or ``filename.pdf`` if ``engine`` is either ``'pdflatex'``, ``'xelatex'``, or ``'lualatex'``) and if ``png`` is ``True``, ``filename.png``. If ``png`` is ``True`` and ``dvipng`` cannot convert the dvi file to png (because of postscript specials or other issues), then ``dvips`` is called, and @@ -604,21 +601,21 @@ def _run_latex_(filename, debug=False, density=150, engine=None, png=False, do_i INPUT: - - ``filename`` -- string; file to process, including full path + - ``filename`` -- string; file to process, including full path - - ``debug`` -- bool (default: ``False``); whether to print - verbose debugging output + - ``debug`` -- boolean (default: ``False``); whether to print + verbose debugging output - - ``density`` -- integer (default: 150); how big output - image is. + - ``density`` -- integer (default: 150); how big output + image is - - ``engine`` -- string: latex engine to use. + - ``engine`` -- string; latex engine to use - - ``png`` -- bool (default: ``False``); whether to produce a - png file. + - ``png`` -- boolean (default: ``False``); whether to produce a + png file - - ``do_in_background`` -- bool (default: ``False``). Unused, - kept for backwards compatibility. + - ``do_in_background`` -- boolean (default: ``False``); unused, + kept for backwards compatibility OUTPUT: @@ -644,7 +641,7 @@ def _run_latex_(filename, debug=False, density=150, engine=None, png=False, do_i sage: from sage.misc.latex import _run_latex_, _latex_file_ sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(mode="w+t", suffix=".tex") as f: # random, optional - latex + sage: with NamedTemporaryFile(mode='w+t', suffix='.tex') as f: # random, optional - latex ....: _ = f.write(_latex_file_([ZZ['x'], RR])) ....: f.flush() ....: _run_latex_(f.name) @@ -849,14 +846,12 @@ def __call__(self, x, combine_all=False): - ``x`` -- a Sage object - - ``combine_all`` -- boolean (Default: ``False``) If ``combine_all`` + - ``combine_all`` -- boolean (default: ``False``); if ``combine_all`` is ``True`` and the input is a tuple, then it does not return a tuple and instead returns a string with all the elements separated by - a single space. - - OUTPUT: + a single space - A :class:`LatexExpr` built from ``x`` + OUTPUT: a :class:`LatexExpr` built from ``x`` EXAMPLES:: @@ -931,7 +926,7 @@ def __init__(self, debug=False, slide=False, density=150, engine=None): sage: from sage.misc.latex import Latex sage: l = Latex() - sage: TestSuite(l).run(skip ="_test_pickling") + sage: TestSuite(l).run(skip ='_test_pickling') """ self.__debug = debug self.__slide = slide @@ -940,7 +935,7 @@ def __init__(self, debug=False, slide=False, density=150, engine=None): def _relation_symbols(self): """ - Returns a dictionary whose keys are attributes of the + Return a dictionary whose keys are attributes of the :mod:`operator` module and whose values are the corresponding LaTeX expressions. @@ -1252,8 +1247,8 @@ def matrix_column_alignment(self, align=None): INPUT: - - ``align`` -- a string (``'r'`` for right, ``'c'`` for center, - ``'l'`` for left) or ``None``. + - ``align`` -- string (``'r'`` for right, ``'c'`` for center, + ``'l'`` for left) or ``None`` OUTPUT: @@ -1297,7 +1292,7 @@ def has_file(self, file_name) -> bool: """ INPUT: - - ``file_name`` -- a string + - ``file_name`` -- string Tests whether the local LaTeX installation includes ``file_name``. @@ -1321,9 +1316,9 @@ def check_file(self, file_name, more_info=""): """ INPUT: - - ``file_name`` -- a string + - ``file_name`` -- string - - ``more_info`` -- a string (default: ``""``) + - ``more_info`` -- string (default: ``''``) Emit a warning if the local LaTeX installation does not include ``file_name``. The string ``more_info`` is appended @@ -1480,13 +1475,13 @@ def add_to_preamble(self, s): def add_package_to_preamble_if_available(self, package_name): r""" - Adds a ``\usepackage{package_name}`` instruction to the latex + Add a ``\usepackage{package_name}`` instruction to the latex preamble if not yet present there, and if ``package_name.sty`` is available in the LaTeX installation. INPUT: - - ``package_name`` -- a string + - ``package_name`` -- string .. SEEALSO:: @@ -1579,20 +1574,20 @@ def _latex_file_(objects, title='SAGE', debug=False, - ``objects`` -- list (or object) - - ``title`` -- string (default: 'Sage'); title for the document + - ``title`` -- string (default: ``'Sage'``); title for the document - - ``math_left`` -- string (default: '\\['), left delimiter for math mode + - ``math_left`` -- string (default: ``'\\['``); left delimiter for math mode - - ``math_right`` -- string (default: '\\]'), right delimiter for math mode + - ``math_right`` -- string (default: ``'\\]'``); right delimiter for math mode - - ``debug`` -- bool (default: ``False``); print verbose output + - ``debug`` -- boolean (default: ``False``); print verbose output - ``sep`` -- string (default: ``''``); separator between math objects - - ``tiny`` -- bool (default: ``False``); use 'tiny' font. + - ``tiny`` -- boolean (default: ``False``); use 'tiny' font - - ``extra_preamble`` -- string (default: ``''``); extra LaTeX commands, - inserted before ``"\\begin{document}"`` + - ``extra_preamble`` -- string (default: ``''``); extra LaTeX commands; + inserted before ``'\\begin{document}'`` This creates a string intended to be a LaTeX file containing the LaTeX representations of objects. It contains the following: @@ -1706,21 +1701,21 @@ def view(objects, title='Sage', debug=False, sep='', tiny=False, - ``objects`` -- list (or object) - ``title`` -- string (default: ``'Sage'``); title for the - document + document - - ``debug`` -- bool (default: ``False``); print verbose - output + - ``debug`` -- boolean (default: ``False``); print verbose + output - ``sep`` -- string (default: ``''``); separator between - math objects + math objects - - ``tiny`` -- bool (default: ``False``); use tiny font. + - ``tiny`` -- boolean (default: ``False``); use tiny font - ``engine`` -- string or ``None`` (default: ``None``); can take the - following values: + following values: - ``None`` -- the value defined in the LaTeX global preferences - ``latex.engine()`` is used. + ``latex.engine()`` is used - ``'pdflatex'`` -- compilation does ``tex`` -> ``pdf`` @@ -1733,26 +1728,23 @@ def view(objects, title='Sage', debug=False, sep='', tiny=False, ``'pdflatex'`` and known to be broken when overfull hboxes are detected. - ``viewer`` -- string or ``None`` (default: ``None``); specify a viewer - to use; currently the only options are ``None`` and ``'pdf'``. + to use; currently the only options are ``None`` and ``'pdf'`` - - ``tightpage`` -- bool (default: ``True``); use the LaTeX package - ``preview`` with the 'tightpage' option. + - ``tightpage`` -- boolean (default: ``True``); use the LaTeX package + ``preview`` with the 'tightpage' option - ``margin`` -- float or ``None`` (default: ``None``); adds a margin - of ``margin`` mm; has no affect if the option ``tightpage`` is - ``False``. + of ``margin`` mm. Has no affect if the option ``tightpage`` is ``False``. - ``mode`` -- string (default: ``'inline'``); ``'display'`` for displaymath or ``'inline'`` for inline math - - ``combine_all`` -- bool (default: ``False``); if ``combine_all`` is + - ``combine_all`` -- boolean (default: ``False``); if ``combine_all`` is ``True`` and the input is a tuple, then it does not return a tuple and instead returns a string with all the elements separated by a single - space. + space - OUTPUT: - - Display typeset objects. + OUTPUT: display typeset objects The output is displayed in a separate viewer displaying a dvi (or pdf) file, with the following: the title string is printed, centered, at the @@ -1802,10 +1794,10 @@ def view(objects, title='Sage', debug=False, sep='', tiny=False, sage: from tempfile import NamedTemporaryFile sage: g = sage.misc.latex.latex_examples.graph() sage: latex.add_to_preamble(r"\usepackage{tkz-graph}") # optional - latex_package_tkz_graph - sage: with NamedTemporaryFile(mode="w+t", suffix=".tex") as f: # optional - latex latex_package_tkz_graph + sage: with NamedTemporaryFile(mode='w+t', suffix='.tex') as f: # optional - latex latex_package_tkz_graph ....: _ = f.write(_latex_file_(g)) ....: f.flush() - ....: _run_latex_(f.name, engine="pdflatex") + ....: _run_latex_(f.name, engine='pdflatex') 'pdf' sage: view(4, margin=5, debug=True) # not tested @@ -1830,11 +1822,10 @@ def view(objects, title='Sage', debug=False, sep='', tiny=False, sage: latex.extra_preamble('') # reset the preamble - sage: view(4, engine="garbage") + sage: view(4, engine='garbage') Traceback (most recent call last): ... ValueError: Unsupported LaTeX engine. - """ if tightpage: @@ -1916,12 +1907,12 @@ def png(x, filename, density=150, debug=False, - ``density`` -- integer (default: 150) - - ``debug`` -- bool (default: ``False``); print verbose output + - ``debug`` -- boolean (default: ``False``); print verbose output - - ``do_in_background`` -- bool (default: ``False``); Unused, kept for + - ``do_in_background`` -- boolean (default: ``False``); unused, kept for backwards compatibility - - ``tiny`` -- bool (default: ``False``); use tiny font + - ``tiny`` -- boolean (default: ``False``); use tiny font - ``engine`` -- (default: ``None``) ``'latex'``, ``'pdflatex'``, ``'xelatex'`` or ``'lualatex'`` @@ -1931,7 +1922,7 @@ def png(x, filename, density=150, debug=False, sage: # optional - imagemagick latex, needs sage.plot sage: from sage.misc.latex import png sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # random + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # random ....: png(ZZ[x], f.name) """ import sage.plot.all @@ -1975,9 +1966,7 @@ def coeff_repr(c): - ``c`` -- a coefficient (i.e., an element of a ring) - OUTPUT: - - A string + OUTPUT: string EXAMPLES:: @@ -2010,7 +1999,7 @@ def repr_lincomb(symbols, coeffs): - ``coeffs`` -- list of coefficients of the symbols - OUTPUT: A string + OUTPUT: string EXAMPLES:: @@ -2141,7 +2130,7 @@ def latex_varify(a, is_fname=False): - ``a`` -- string - OUTPUT: A string + OUTPUT: string EXAMPLES:: @@ -2310,7 +2299,7 @@ class graph(SageObject): def _repr_(self): """ - String representation + String representation. EXAMPLES:: @@ -2334,7 +2323,7 @@ def _repr_(self): def _latex_(self): """ - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2379,7 +2368,7 @@ class pstricks(SageObject): def _repr_(self): """ - String representation + String representation. EXAMPLES:: @@ -2399,7 +2388,7 @@ def _repr_(self): def _latex_(self): """ - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2436,7 +2425,7 @@ class knot(SageObject): def _repr_(self): """ - String representation + String representation. EXAMPLES:: @@ -2455,7 +2444,7 @@ def _repr_(self): def _latex_(self): """ - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2485,7 +2474,7 @@ class diagram(SageObject): def _repr_(self): """ - String representation + String representation. EXAMPLES:: @@ -2503,7 +2492,7 @@ def _repr_(self): def _latex_(self): """ - LaTeX representation + LaTeX representation. EXAMPLES:: diff --git a/src/sage/misc/latex_macros.py b/src/sage/misc/latex_macros.py index 3ac23ff9c6e..fc389b32a72 100644 --- a/src/sage/misc/latex_macros.py +++ b/src/sage/misc/latex_macros.py @@ -50,9 +50,9 @@ def produce_latex_macro(name, *sample_args): INPUT: - - ``name`` -- name of macro to be defined, also name of corresponding Sage object + - ``name`` -- name of macro to be defined, also name of corresponding Sage object - - ``sample_args`` -- (optional) sample arguments for this Sage object + - ``sample_args`` -- (optional) sample arguments for this Sage object EXAMPLES:: @@ -110,7 +110,7 @@ def convert_latex_macro_to_mathjax(macro): INPUT: - - ``macro`` -- LaTeX macro definition + - ``macro`` -- LaTeX macro definition See the web page https://docs.mathjax.org/en/latest/input/tex/macros.html for a diff --git a/src/sage/misc/latex_standalone.py b/src/sage/misc/latex_standalone.py index f17083fdaf4..de53979662e 100644 --- a/src/sage/misc/latex_standalone.py +++ b/src/sage/misc/latex_standalone.py @@ -247,21 +247,21 @@ class Standalone(SageObject): INPUT: - - ``content`` -- string, the content to be added in the document + - ``content`` -- string; the content to be added in the document between lines ``r'\begin{document}'`` and ``r'\end{document}'`` - - ``document_class_options`` -- list of strings (default: ``[]``), + - ``document_class_options`` -- list of strings (default: ``[]``); latex document class standalone options. Such options appear on the line ``\documentclass[...]{standalone}`` between the brackets. - - ``standalone_config`` -- list of strings (default: ``[]``), + - ``standalone_config`` -- list of strings (default: ``[]``); standalone configuration options. Such options are defined with - ``\standaloneconfig{...}`` - - ``usepackage`` -- list of strings (default: ``[]``), latex packages. - - ``macros`` -- list of strings (default: ``[]``), stuff you need for the picture. - - ``use_sage_preamble`` -- bool (default: ``False``), whether to include sage + ``\standaloneconfig{...}``. + - ``usepackage`` -- list of strings (default: ``[]``); latex packages + - ``macros`` -- list of strings (default: ``[]``); stuff you need for the picture + - ``use_sage_preamble`` -- boolean (default: ``False``); whether to include sage latex preamble and sage latex macros, that is, the content of :func:`sage.misc.latex.extra_preamble()`, :func:`sage.misc.latex.extra_macros()` and - :func:`sage.misc.latex_macros.sage_latex_macros()`. + :func:`sage.misc.latex_macros.sage_latex_macros()` EXAMPLES:: @@ -287,7 +287,6 @@ class Standalone(SageObject): \section{Intro} Test \end{document} - """ def __init__(self, content, document_class_options=None, standalone_config=None, usepackage=None, macros=None, @@ -401,7 +400,6 @@ def _repr_(self): \draw(19,-.5) -- (19,.5); \end{tikzpicture} \end{document} - """ lines = self._latex_file_header_lines() lines.append(r"\begin{document}") @@ -421,7 +419,7 @@ def _repr_(self): def _rich_repr_(self, display_manager, **kwds): r""" - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -484,7 +482,7 @@ def _rich_repr_(self, display_manager, **kwds): def __str__(self): r""" - Return the complete string of the standalone document class file + Return the complete string of the standalone document class file. EXAMPLES:: @@ -513,7 +511,7 @@ def __str__(self): def content(self): r""" - Return the content of the standalone document class file + Return the content of the standalone document class file. EXAMPLES:: @@ -536,7 +534,7 @@ def content(self): def add_document_class_option(self, option): r""" - Add a document class option + Add a document class option. INPUT: @@ -557,7 +555,7 @@ def add_document_class_option(self, option): def add_standalone_config(self, config): r""" - Add a standalone config + Add a standalone config. INPUT: @@ -574,13 +572,12 @@ def add_standalone_config(self, config): \begin{document} Hello World \end{document} - """ self._standalone_config.append(config) def add_usepackage(self, package): r""" - Add a ``usepackage`` line + Add a ``usepackage`` line. INPUT: @@ -597,13 +594,12 @@ def add_usepackage(self, package): \begin{document} Hello World \end{document} - """ self._usepackage.append(package) def add_macro(self, macro): r""" - Add a macro + Add a macro. INPUT: @@ -620,7 +616,6 @@ def add_macro(self, macro): \begin{document} Hello World \end{document} - """ self._macros.append(macro) @@ -630,20 +625,18 @@ def pdf(self, filename=None, view=True, program=None): INPUT: - - ``filename`` -- string (default: ``None``), the output filename. + - ``filename`` -- string (default: ``None``); the output filename. If ``None``, it saves the file in a temporary directory. - - ``view`` -- bool (default:``True``), whether to open the file in a + - ``view`` -- boolean (default: ``True``); whether to open the file in a pdf viewer. This option is ignored and automatically set to ``False`` if ``filename`` is not ``None``. - - ``program`` -- string (default:``None``) ``'pdflatex'`` or + - ``program`` -- string (default: ``None``); ``'pdflatex'`` or ``'lualatex'``. If ``None``, it uses ``'lualatex'`` if it is available, otherwise ``'pdflatex'``. - OUTPUT: - - string, path to pdf file + OUTPUT: string, path to pdf file EXAMPLES:: @@ -683,8 +676,7 @@ def pdf(self, filename=None, view=True, program=None): Traceback (most recent call last): ... CalledProcessError: Command '['...latex', '-interaction=nonstopmode', - 'tikz_...tex']' returned non-zero exit status 1. - + 'tikz_...tex']' returned nonzero exit status 1. """ from sage.features.latex import lualatex, pdflatex @@ -719,7 +711,7 @@ def pdf(self, filename=None, view=True, program=None): if result.returncode != 0: print("Command \n" " '{}'\n" - "returned non-zero exit status {}.\n" + "returned nonzero exit status {}.\n" "Here is the content of the stderr:{}\n" "Here is the content of the stdout:" "{}\n".format(' '.join(result.args), @@ -756,18 +748,16 @@ def dvi(self, filename=None, view=True, program='latex'): INPUT: - - ``filename`` -- string (default: ``None``), the output filename. - If ``None``, it saves the file in a temporary directory. + - ``filename`` -- string (default: ``None``); the output filename. + If ``None``, it saves the file in a temporary directory - - ``view`` -- bool (default:``True``), whether to open the file in a + - ``view`` -- boolean (default: ``True``); whether to open the file in a dvi viewer. This option is ignored and automatically set to ``False`` if ``filename`` is not ``None``. - - ``program`` -- string (default:``'latex'``), ``'latex'`` - - OUTPUT: + - ``program`` -- string (default: ``'latex'``); ``'latex'`` - string, path to dvi file + OUTPUT: string, path to dvi file EXAMPLES:: @@ -807,7 +797,7 @@ def dvi(self, filename=None, view=True, program='latex'): Traceback (most recent call last): ... CalledProcessError: Command '['latex', '-interaction=nonstopmode', - 'tikz_...tex']' returned non-zero exit status 1. + 'tikz_...tex']' returned nonzero exit status 1. We test the behavior when a wrong value is provided:: @@ -816,7 +806,6 @@ def dvi(self, filename=None, view=True, program='latex'): Traceback (most recent call last): ... ValueError: program(=lates) should be latex - """ from sage.features.latex import latex @@ -846,7 +835,7 @@ def dvi(self, filename=None, view=True, program='latex'): if result.returncode != 0: print("Command \n" " '{}'\n" - "returned non-zero exit status {}.\n" + "returned nonzero exit status {}.\n" "Here is the content of the stderr:{}\n" "Here is the content of the stdout:" "{}\n".format(' '.join(result.args), @@ -883,19 +872,17 @@ def png(self, filename=None, density=150, view=True): INPUT: - - ``filename`` -- string (default:``None``), the output filename. + - ``filename`` -- string (default: ``None``); the output filename. If ``None``, it saves the file in a temporary directory. - - ``density`` -- integer, (default: ``150``), horizontal and vertical + - ``density`` -- integer (default: ``150``); horizontal and vertical density of the image - - ``view`` -- bool (default:``True``), whether to open the file in a + - ``view`` -- boolean (default: ``True``); whether to open the file in a png viewer. This option is ignored and automatically set to ``False`` if ``filename`` is not ``None``. - OUTPUT: - - string, path to png file + OUTPUT: string, path to png file EXAMPLES:: @@ -917,7 +904,6 @@ def png(self, filename=None, density=150, view=True): sage: path_to_file = t.png(filename) # long time (1s) # optional - latex imagemagick sage: path_to_file[-4:] # long time (fast) # optional - latex imagemagick '.png' - """ from sage.features.imagemagick import ImageMagick ImageMagick().require() @@ -936,7 +922,7 @@ def png(self, filename=None, density=150, view=True): if result.returncode != 0: print("Command \n" " '{}'\n" - "returned non-zero exit status {}.\n" + "returned nonzero exit status {}.\n" "Here is the content of the stderr:{}\n" "Here is the content of the stdout:" "{}\n".format(' '.join(result.args), @@ -972,19 +958,17 @@ def svg(self, filename=None, view=True, program='pdftocairo'): INPUT: - - ``filename`` -- string (default:``None``), the output filename. + - ``filename`` -- string (default: ``None``); the output filename. If ``None``, it saves the file in a temporary directory. - - ``view`` -- bool (default:``True``), whether to open the file in + - ``view`` -- boolean (default: ``True``); whether to open the file in a browser. This option is ignored and automatically set to ``False`` if ``filename`` is not ``None``. - - ``program`` -- string (default:``'pdftocairo'``) ``'pdftocairo'`` or - ``'pdf2svg'``. + - ``program`` -- string (default: ``'pdftocairo'``); ``'pdftocairo'`` or + ``'pdf2svg'`` - OUTPUT: - - string, path to svg file + OUTPUT: string, path to svg file EXAMPLES:: @@ -1011,7 +995,6 @@ def svg(self, filename=None, view=True, program='pdftocairo'): ....: program='pdftocairo') sage: path_to_file[-4:] # long time (fast) # optional - latex pdftocairo '.svg' - """ # set the temporary filenames temp_filename_pdf = self.pdf(filename=None, view=False) @@ -1038,7 +1021,7 @@ def svg(self, filename=None, view=True, program='pdftocairo'): if result.returncode != 0: print("Command \n" " '{}'\n" - "returned non-zero exit status {}.\n" + "returned nonzero exit status {}.\n" "Here is the content of the stderr:{}\n" "Here is the content of the stdout:" "{}\n".format(' '.join(result.args), @@ -1074,19 +1057,17 @@ def eps(self, filename=None, view=True, program='dvips'): INPUT: - - ``filename`` -- string (default:``None``), the output filename. - If ``None``, it saves the file in a temporary directory. + - ``filename`` -- string (default: ``None``); the output filename. + If ``None``, it saves the file in a temporary directory - - ``view`` -- bool (default:``True``), whether to open the file in + - ``view`` -- boolean (default: ``True``); whether to open the file in a browser. This option is ignored and automatically set to ``False`` if ``filename`` is not ``None``. - - ``program`` -- string (default:``'dvips'``), + - ``program`` -- string (default: ``'dvips'``); ``'pdftocairo'`` or ``'dvips'`` - OUTPUT: - - string, path to eps file + OUTPUT: string, path to eps file EXAMPLES:: @@ -1123,7 +1104,6 @@ def eps(self, filename=None, view=True, program='dvips'): Traceback (most recent call last): ... ValueError: program(=convert) should be 'pdftocairo' or 'dvips' - """ if program == 'pdftocairo': @@ -1155,7 +1135,7 @@ def eps(self, filename=None, view=True, program='dvips'): if result.returncode != 0: print("Command \n" " '{}'\n" - "returned non-zero exit status {}.\n" + "returned nonzero exit status {}.\n" "Here is the content of the stderr:{}\n" "Here is the content of the stdout:" "{}\n".format(' '.join(result.args), @@ -1191,15 +1171,13 @@ def tex(self, filename=None, content_only=False, include_header=None): INPUT: - - ``filename`` -- string (default:``None``), the output filename. + - ``filename`` -- string (default: ``None``); the output filename. If ``None``, it saves the file in a temporary directory. - - ``content_only`` -- bool (default:``False``) whether to include + - ``content_only`` -- boolean (default: ``False``); whether to include the header latex part. If ``True``, it prints only the content to the file. - OUTPUT: - - string, path to tex file + OUTPUT: string, path to tex file EXAMPLES:: @@ -1223,7 +1201,6 @@ def tex(self, filename=None, content_only=False, include_header=None): sage: path_to_file = t.tex(filename) sage: path_to_file[-4:] '.tex' - """ if filename is None: from sage.misc.temporary_file import tmp_filename @@ -1268,9 +1245,7 @@ def save(self, filename, **kwds): All other keyword arguments will be passed to the plotter. - OUTPUT: - - - ``None`` + OUTPUT: none .. NOTE:: @@ -1289,7 +1264,6 @@ def save(self, filename, **kwds): sage: t.save(filename) # long time (1s) # optional - latex sage: filename = tmp_filename('temp','.eps') sage: t.save(filename) # long time (1s) # optional - latex dvips - """ ext = os.path.splitext(filename)[1].lower() if ext == '' or ext == '.sobj': @@ -1317,18 +1291,18 @@ class TikzPicture(Standalone): - ``content`` -- string, tikzpicture code starting with ``r'\begin{tikzpicture}'`` and ending with ``r'\end{tikzpicture}'`` - - ``standalone_config`` -- list of strings (default: ``[]``), - latex document class standalone configuration options. - - ``usepackage`` -- list of strings (default: ``[]``), latex - packages. - - ``usetikzlibrary`` -- list of strings (default: ``[]``), tikz libraries - to use. - - ``macros`` -- list of strings (default: ``[]``), stuff you need for the picture. - - ``use_sage_preamble`` -- bool (default: ``False``), whether to include sage + - ``standalone_config`` -- list of strings (default: ``[]``); + latex document class standalone configuration options + - ``usepackage`` -- list of strings (default: ``[]``); latex + packages + - ``usetikzlibrary`` -- list of strings (default: ``[]``); tikz libraries + to use + - ``macros`` -- list of strings (default: ``[]``); stuff you need for the picture + - ``use_sage_preamble`` -- boolean (default: ``False``); whether to include sage latex preamble and sage latex macros, that is, the content of :func:`sage.misc.latex.extra_preamble()`, :func:`sage.misc.latex.extra_macros()` and - :func:`sage.misc.latex_macros.sage_latex_macros()`. + :func:`sage.misc.latex_macros.sage_latex_macros()` EXAMPLES: @@ -1422,7 +1396,7 @@ def _latex_file_header_lines(self): def add_usetikzlibrary(self, library): r""" - Add a ``usetikzlibrary`` line + Add a ``usetikzlibrary`` line. INPUT: @@ -1442,7 +1416,6 @@ def add_usetikzlibrary(self, library): \draw (0,0) -- (1,1); \end{tikzpicture} \end{document} - """ self._usetikzlibrary.append(library) @@ -1459,9 +1432,9 @@ def from_dot_string(cls, dotdata, prog='dot'): INPUT: - ``dotdata`` -- dot format string - - ``prog`` -- string (default: ``'dot'``) the program used for the + - ``prog`` -- string (default: ``'dot'``); the program used for the layout corresponding to one of the software of the graphviz - suite: 'dot', 'neato', 'twopi', 'circo' or 'fdp'. + suite: ``'dot'``, ``'neato'``, ``'twopi'``, ``'circo'`` or ``'fdp'`` EXAMPLES:: @@ -1494,7 +1467,6 @@ def from_dot_string(cls, dotdata, prog='dot'): sage: dotdata = G.graphviz_string(labels='latex') sage: tikz = TikzPicture.from_dot_string(dotdata) # long time (3s), optional - dot2tex graphviz sage: _ = tikz.pdf() # not tested - """ from sage.features import PythonModule PythonModule("dot2tex").require() @@ -1531,21 +1503,21 @@ def from_graph(cls, graph, merge_multiedges=True, INPUT: - ``graph`` -- graph - - ``merge_multiedges`` -- bool (default: ``True``), if the graph + - ``merge_multiedges`` -- boolean (default: ``True``); if the graph has multiple edges, whether to merge the multiedges into one single edge - - ``merge_label_function`` -- function (default:``tuple``), a + - ``merge_label_function`` -- function (default: ``tuple``); a function to apply to each list of labels to be merged. It is ignored if ``merge_multiedges`` is not ``True`` or if the graph has no multiple edges. Other inputs are used for latex drawing with dot2tex and graphviz: - - ``prog`` -- string (default: ``'dot'``) the program used for the + - ``prog`` -- string (default: ``'dot'``); the program used for the layout corresponding to one of the software of the graphviz - suite: 'dot', 'neato', 'twopi', 'circo' or 'fdp'. - - ``edge_labels`` -- bool (default: ``True``) - - ``color_by_label`` -- bool (default: ``False``) + suite: ``'dot'``, ``'neato'``, ``'twopi'``, ``'circo'`` or ``'fdp'`` + - ``edge_labels`` -- boolean (default: ``True``) + - ``color_by_label`` -- boolean (default: ``False``) - ``rankdir`` -- string (default: ``'down'``) - ``subgraph_clusters`` -- (default: ``[]``) a list of lists of vertices, if supported by the layout engine, nodes belonging to @@ -1633,7 +1605,6 @@ def from_graph(cls, graph, merge_multiedges=True, ....: return options sage: tikz = TikzPicture.from_graph(G, edge_options=edge_options) # optional - dot2tex graphviz sage: _ = tikz.pdf() # not tested - """ from sage.features.latex import pdflatex pdflatex().require() @@ -1679,11 +1650,11 @@ def from_graph_with_pos(cls, graph, scale=1, merge_multiedges=True, INPUT: - ``graph`` -- graph (with predefined positions) - - ``scale`` -- number (default:``1``), tikzpicture scale - - ``merge_multiedges`` -- bool (default: ``True``), if the graph + - ``scale`` -- number (default: ``1``); tikzpicture scale + - ``merge_multiedges`` -- boolean (default: ``True``); if the graph has multiple edges, whether to merge the multiedges into one single edge - - ``merge_label_function`` -- function (default:``tuple``), a + - ``merge_label_function`` -- function (default: ``tuple``); a function to apply to each list of labels to be merged. It is ignored if ``merge_multiedges`` is not ``True`` or if the graph has no multiple edges. @@ -1813,11 +1784,11 @@ def from_poset(cls, poset, **kwds): INPUT: - ``poset`` -- poset - - ``prog`` -- string (default: ``'dot'``) the program used for the + - ``prog`` -- string (default: ``'dot'``); the program used for the layout corresponding to one of the software of the graphviz - suite: 'dot', 'neato', 'twopi', 'circo' or 'fdp'. - - ``edge_labels`` -- bool (default: ``True``) - - ``color_by_label`` -- bool (default: ``False``) + suite: ``'dot'``, ``'neato'``, ``'twopi'``, ``'circo'`` or ``'fdp'`` + - ``edge_labels`` -- boolean (default: ``True``) + - ``color_by_label`` -- boolean (default: ``False``) - ``rankdir`` -- string (default: ``'down'``) EXAMPLES:: diff --git a/src/sage/misc/lazy_attribute.pyx b/src/sage/misc/lazy_attribute.pyx index 4210fb7e081..663856d03e3 100644 --- a/src/sage/misc/lazy_attribute.pyx +++ b/src/sage/misc/lazy_attribute.pyx @@ -36,7 +36,6 @@ cdef class _lazy_attribute(): Traceback (most recent call last): ... NotImplementedError: Only instantiate wrapper python class - """ cdef public f @@ -68,7 +67,7 @@ cdef class _lazy_attribute(): sage: Parent.element_class sage: Parent.element_class.__doc__[91:147] - 'The (default) class for the elements of this parent\n\n ' + 'The (default) class for the elements of this parent.\n\n ' sage: Parent.element_class.__name__ 'element_class' sage: Parent.element_class.__module__ @@ -88,7 +87,7 @@ cdef class _lazy_attribute(): sage: src[0] 'def banner():\n' sage: lines - 89 + 87 """ from sage.misc.sageinspect import sage_getsourcelines return sage_getsourcelines(self.f) @@ -590,7 +589,7 @@ class lazy_class_attribute(lazy_attribute): """ def __get__(self, _, cls): """ - Implements the attribute access protocol. + Implement the attribute access protocol. EXAMPLES:: diff --git a/src/sage/misc/lazy_format.py b/src/sage/misc/lazy_format.py index 3d80bca7230..d2b549c9e11 100644 --- a/src/sage/misc/lazy_format.py +++ b/src/sage/misc/lazy_format.py @@ -6,7 +6,7 @@ class LazyFormat(str): """ - Lazy format strings + Lazy format strings. .. NOTE:: @@ -84,7 +84,7 @@ class LazyFormat(str): def __mod__(self, args): """ - Binds the lazy format string with its parameters + Bind the lazy format string with its parameters. EXAMPLES:: diff --git a/src/sage/misc/lazy_import.pyx b/src/sage/misc/lazy_import.pyx index 6d845188adc..cde9be93d7e 100644 --- a/src/sage/misc/lazy_import.pyx +++ b/src/sage/misc/lazy_import.pyx @@ -134,9 +134,7 @@ cpdef bint is_during_startup() noexcept: """ Return whether Sage is currently starting up. - OUTPUT: - - Boolean + OUTPUT: boolean TESTS:: @@ -229,9 +227,7 @@ cdef class LazyImport(): """ Return the wrapped object, importing it if necessary. - OUTPUT: - - - the wrapped object + OUTPUT: the wrapped object EXAMPLES:: @@ -365,7 +361,7 @@ cdef class LazyImport(): def __getattr__(self, attr): """ - Attribute lookup on self defers to attribute lookup on the + Attribute lookup on ``self`` defers to attribute lookup on the wrapped object. EXAMPLES:: @@ -382,7 +378,7 @@ cdef class LazyImport(): def __dir__(self): """ - Tab completion on self defers to completion on the wrapped + Tab completion on ``self`` defers to completion on the wrapped object. EXAMPLES:: @@ -396,7 +392,7 @@ cdef class LazyImport(): def __call__(self, *args, **kwds): """ - Calling self calls the wrapped object. + Calling ``self`` calls the wrapped object. EXAMPLES:: @@ -910,7 +906,7 @@ cdef class LazyImport(): def __copy__(self): """ - Support copy() + Support ``copy()``. TESTS:: @@ -931,7 +927,7 @@ cdef class LazyImport(): def __deepcopy__(self, memo=None): """ - Support copy() + Support ``copy()``. TESTS:: @@ -1003,16 +999,16 @@ def lazy_import(module, names, as_=None, *, INPUT: - - ``module`` -- a string representing the module to import + - ``module`` -- string representing the module to import - - ``names`` -- a string or list of strings representing the names to + - ``names`` -- string or list of strings representing the names to import from module - ``as_`` -- (optional) a string or list of strings representing the names of the objects in the importing module. This is analogous to ``from ... import ... as ...``. - - ``at_startup`` -- a boolean (default: ``False``); + - ``at_startup`` -- boolean (default: ``False``); whether the lazy import is supposed to be resolved at startup time - ``namespace`` -- the namespace where importing the names; by default, diff --git a/src/sage/misc/lazy_list.pyx b/src/sage/misc/lazy_list.pyx index cd750933860..0bbf217c472 100644 --- a/src/sage/misc/lazy_list.pyx +++ b/src/sage/misc/lazy_list.pyx @@ -131,11 +131,11 @@ def lazy_list(data=None, initial_values=None, start=None, stop=None, step=None, #. or a standard Python container ``list`` or ``tuple``. - ``initial_values`` -- the beginning of the sequence that will not be computed from - the ``data`` provided. + the ``data`` provided - ``update_function`` -- you can also construct a lazy list from a function that takes as input a list of precomputed values and updates it with some - more values. + more values .. NOTE:: @@ -252,7 +252,7 @@ def lazy_list(data=None, initial_values=None, start=None, stop=None, step=None, def slice_unpickle(master, start, stop, step): r""" - Unpickle helper + Unpickle helper. TESTS:: @@ -293,9 +293,7 @@ def lazy_list_formatter(L, name='lazy list', - ``preview`` -- (default: ``3``) an integer specifying the number of elements shown in the representation string - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -351,7 +349,7 @@ def lazy_list_formatter(L, name='lazy list', cdef class lazy_list_generic(): r""" - A lazy list + A lazy list. EXAMPLES:: @@ -374,7 +372,7 @@ cdef class lazy_list_generic(): INPUT: - ``cache`` -- an optional list to be used as the cache. Be careful that - there is no copy. + there is no copy - ``start``, ``stop``, ``step`` -- for slices @@ -532,7 +530,7 @@ cdef class lazy_list_generic(): def __reduce__(self): r""" - Pickling support + Pickling support. EXAMPLES:: @@ -614,10 +612,10 @@ cdef class lazy_list_generic(): r""" Return the element at position ``i``. - If the index is not an integer, then raise a ``TypeError``. If the - argument is negative then raise a ``ValueError``. Finally, if the + If the index is not an integer, then raise a :exc:`TypeError`. If the + argument is negative then raise a :exc:`ValueError`. Finally, if the argument is beyond the size of that lazy list it raises a - ``IndexError``. + :exc:`IndexError`. EXAMPLES:: @@ -646,7 +644,7 @@ cdef class lazy_list_generic(): TypeError: unable to convert rational 1/2 to an integer """ if i < 0: - raise ValueError("indices must be non-negative") + raise ValueError("indices must be nonnegative") i = self.start + i * self.step if self._fit(i): @@ -655,7 +653,7 @@ cdef class lazy_list_generic(): def __call__(self, i): r""" - An alias for :meth:`get` + An alias for :meth:`get`. TESTS:: @@ -817,7 +815,7 @@ cdef class lazy_list_generic(): if step == 0: raise TypeError("step may not be 0") if step < 0 or start < 0 or stop < 0: - raise ValueError("slice indices must be non negative") + raise ValueError("slice indices must be nonnegative") step = step * self.step start = self.start + start * self.step @@ -928,8 +926,8 @@ cdef class lazy_list_from_iterator(lazy_list_generic): - ``iterator`` -- an iterator - - ``cache`` -- an optional list to be used as the cache. Be careful that - there is no copy. + - ``cache`` -- an optional list to be used as the cache; be careful that + there is no copy - ``stop`` -- an optional stop point @@ -1004,15 +1002,14 @@ cdef class lazy_list_from_function(lazy_list_generic): INPUT: - ``function`` -- a function that maps ``n`` to the element - at position ``n``. (This - function only needs to be defined for length larger than the length of - the cache.) + at position ``n`` (this function only needs to be defined for length + larger than the length of the cache) - ``cache`` -- an optional list to be used as the cache. Be careful that - there is no copy. + there is no copy - - ``stop`` -- an optional integer to specify the length of this lazy list. - (Otherwise it is considered infinite). + - ``stop`` -- an optional integer to specify the length of this lazy list + (Otherwise it is considered infinite) EXAMPLES:: @@ -1086,15 +1083,15 @@ cdef class lazy_list_from_update_function(lazy_list_generic): r""" INPUT: - - ``function`` -- a function that updates a list of precomputed values. + - ``function`` -- a function that updates a list of precomputed values The update function should take as input a list and make it longer (using either the methods ``append`` or ``extend``). If after a call to the update function the list of values is shorter a - ``RuntimeError`` will occurr. If no value is added then the lazy list + :exc:`RuntimeError` will occurr. If no value is added then the lazy list is considered finite. - ``cache`` -- an optional list to be used as the cache. Be careful that - there is no copy. + there is no copy - ``stop`` -- an optional integer to specify the length of this lazy list (otherwise it is considered infinite) diff --git a/src/sage/misc/lazy_string.pyx b/src/sage/misc/lazy_string.pyx index a37b712c3cc..48a26c9b609 100644 --- a/src/sage/misc/lazy_string.pyx +++ b/src/sage/misc/lazy_string.pyx @@ -64,7 +64,7 @@ import types def is_lazy_string(obj): """ - Checks if the given object is a lazy string. + Check if the given object is a lazy string. EXAMPLES:: @@ -79,14 +79,14 @@ def is_lazy_string(obj): def lazy_string(f, *args, **kwargs): """ - Creates a lazy string. + Create a lazy string. INPUT: - - ``f``, either a callable or a (format) string + - ``f`` -- either a callable or a (format) string - positional arguments that are given to ``f``, either by calling or by applying it as a format string - - named arguments, that are forwarded to ``f`` if it is not a string + - named arguments that are forwarded to ``f`` if it is not a string EXAMPLES:: @@ -139,11 +139,11 @@ cdef class _LazyString(): INPUT: - - ``f``, either a callable or a (format) string - - ``args``, a tuple of arguments that are given to ``f``, either by calling + - ``f`` -- either a callable or a (format) string + - ``args`` -- tuple of arguments that are given to ``f``, either by calling or by applying it as a format string - - ``kwargs``, a dictionary of optional arguments, that are forwarded to ``f`` - if it is a callable. + - ``kwargs`` -- dictionary of optional arguments, that are forwarded to ``f`` + if it is a callable .. NOTE:: @@ -186,11 +186,11 @@ cdef class _LazyString(): """ INPUT: - - ``f``, either a callable or a (format) string - - ``args``, a tuple of arguments that are given to ``f``, either by calling + - ``f`` -- either a callable or a (format) string + - ``args`` -- tuple of arguments that are given to ``f``, either by calling or by applying it as a format string - - ``kwargs``, a dictionary of optional arguments, that are forwarded to ``f`` - if it is a callable. + - ``kwargs`` -- dictionary of optional arguments, that are forwarded to ``f`` + if it is a callable EXAMPLES:: @@ -326,7 +326,6 @@ cdef class _LazyString(): sage: s = lazy_string(f) sage: os.fspath(s) '/dev/null' - """ return str(self) @@ -511,8 +510,8 @@ cdef class _LazyString(): INPUT: - - ``args``, a tuple - - ``kwds``, a dict + - ``args`` -- tuple + - ``kwds`` -- dictionary .. NOTE:: diff --git a/src/sage/misc/messaging.py b/src/sage/misc/messaging.py index d7f6703b4a9..98183875387 100644 --- a/src/sage/misc/messaging.py +++ b/src/sage/misc/messaging.py @@ -68,7 +68,7 @@ def pushover(message, **kwds): sage: sage.misc.messaging.pushover_defaults["user"] = "USER_TOKEN" sage: sage.misc.messaging.pushover("Hi, how are you?") # not tested - .. note:: + .. NOTE:: You may want to populate ``sage.misc.messaging.pushover_defaults`` with default values such as the default user in ``$HOME/.sage/init.sage``. diff --git a/src/sage/misc/misc.py b/src/sage/misc/misc.py index 3a11e1fc440..e5b3aed1ace 100644 --- a/src/sage/misc/misc.py +++ b/src/sage/misc/misc.py @@ -87,10 +87,10 @@ def try_read(obj, splitlines=False): INPUT: - ``obj`` -- typically a `file` or `io.BaseIO` object, but any other - object with a ``read()`` method is accepted. + object with a ``read()`` method is accepted - - ``splitlines`` -- `bool`, optional; if True, return a list of lines - instead of a string. + - ``splitlines`` -- boolean (default: ``False``); if ``True``, return a + list of lines instead of a string EXAMPLES:: @@ -187,9 +187,7 @@ def exactly_one_is_true(iterable): - ``iterable`` -- an iterable object - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -247,9 +245,7 @@ def newton_method_sizes(N): INPUT: - - - ``N`` -- positive integer - + - ``N`` -- positive integer EXAMPLES:: @@ -286,16 +282,16 @@ def newton_method_sizes(N): def compose(f, g): r""" - Return the composition of one-variable functions: `f \circ g` + Return the composition of one-variable functions: `f \circ g`. See also :func:`nest()` INPUT: - - `f` -- a function of one variable - - `g` -- another function of one variable - OUTPUT: - A function, such that compose(f,g)(x) = f(g(x)) + - ``f`` -- a function of one variable + - ``g`` -- another function of one variable + + OUTPUT: a function, such that compose(f,g)(x) = f(g(x)) EXAMPLES:: @@ -315,7 +311,6 @@ def compose(f, g): sage: _ = var('x') # needs sage.symbolic sage: compose(f, g)(x) # needs sage.symbolic f(g(x)) - """ return lambda x: f(g(x)) @@ -327,12 +322,12 @@ def nest(f, n, x): See also :func:`compose()` and :func:`self_compose()` INPUT: - - `f` -- a function of one variable - - `n` -- a nonnegative integer - - `x` -- any input for `f` - OUTPUT: - `f(f(...f(x)...))`, where the composition occurs n times + - ``f`` -- a function of one variable + - ``n`` -- nonnegative integer + - ``x`` -- any input for `f` + + OUTPUT: `f(f(...f(x)...))`, where the composition occurs n times EXAMPLES:: @@ -354,7 +349,6 @@ def nest(f, n, x): sage: _ = var('x') # needs sage.symbolic sage: nest(f, 0, x) # needs sage.symbolic x - """ from sage.rings.integer import Integer n = Integer(n) @@ -373,7 +367,7 @@ def nest(f, n, x): class BackslashOperator: r""" - Implements Matlab-style backslash operator for solving systems:: + Implement Matlab-style backslash operator for solving systems:: A \ b @@ -458,7 +452,7 @@ def __mul__(self, right): ################################################################# def is_iterator(it) -> bool: """ - Tests if it is an iterator. + Test if it is an iterator. The mantra ``if hasattr(it, 'next')`` was used to tests if ``it`` is an iterator. This is not quite correct since ``it`` could have a ``next`` @@ -517,11 +511,9 @@ def random_sublist(X, s): INPUT: + - ``X`` -- list - - ``X`` -- list - - - ``s`` -- floating point number between 0 and 1 - + - ``s`` -- floating point number between 0 and 1 OUTPUT: list @@ -576,12 +568,12 @@ def some_tuples(elements, repeat, bound, max_samples=None): INPUT: - ``elements`` -- an iterable - - ``repeat`` -- integer (default ``None``), the length of the tuples to be returned. + - ``repeat`` -- integer (default: ``None``); the length of the tuples to be returned. If ``None``, just returns entries from ``elements``. - ``bound`` -- the maximum number of tuples returned (ignored if ``max_samples`` given) - - ``max_samples`` -- non-negative integer (default ``None``). If given, + - ``max_samples`` -- nonnegative integer (default: ``None``); if given, then a sample of the possible tuples will be returned, - instead of the first few in the standard order. + instead of the first few in the standard order OUTPUT: @@ -661,8 +653,8 @@ def _some_tuples_sampling(elements, repeat, max_samples, n): def exists(S, P): """ - If S contains an element x such that P(x) is True, this function - returns True and the element x. Otherwise it returns False and + If S contains an element x such that P(x) is ``True``, this function + returns ``True`` and the element x. Otherwise it returns ``False`` and None. Note that this function is NOT suitable to be used in an @@ -673,20 +665,16 @@ def exists(S, P): INPUT: + - ``S`` -- object (that supports enumeration) - - ``S`` -- object (that supports enumeration) - - - ``P`` -- function that returns True or False - + - ``P`` -- function that returns ``True`` or ``False`` OUTPUT: + - ``bool`` -- whether or not P is ``True`` for some element + x of S - - ``bool`` -- whether or not P is True for some element - x of S - - - ``object`` -- x - + - ``object`` -- x EXAMPLES: lambda functions are very useful when using the exists function:: @@ -713,8 +701,8 @@ def exists(S, P): def forall(S, P): """ - If P(x) is true every x in S, return True and None. If there is - some element x in S such that P is not True, return False and x. + If `P(x)` is true every x in S, return ``True`` and ``None``. If there is + some element x in S such that P is not ``True``, return ``False`` and `x`. Note that this function is NOT suitable to be used in an if-statement or in any place where a boolean expression is @@ -724,18 +712,16 @@ def forall(S, P): INPUT: - - ``S`` -- object (that supports enumeration) + - ``S`` -- object (that supports enumeration) - - ``P`` -- function that returns True or False + - ``P`` -- function that returns ``True`` or ``False`` OUTPUT: + - ``bool`` -- whether or not P is ``True`` for all elements + of S - - ``bool`` -- whether or not P is True for all elements - of S - - - ``object`` -- x - + - ``object`` -- x EXAMPLES: lambda functions are very useful when using the forall function. As a toy example we test whether certain integers are @@ -928,9 +914,9 @@ def inject_variable(name, value, warn=True): INPUT: - - ``name`` -- a string + - ``name`` -- string - ``value`` -- anything - - ``warn`` -- a boolean (default: :obj:`False`) + - ``warn`` -- boolean (default: ``False``) EXAMPLES:: @@ -978,7 +964,7 @@ def inject_variable(name, value, warn=True): def inject_variable_test(name, value, depth): """ - A function for testing deep calls to inject_variable + A function for testing deep calls to ``inject_variable``. EXAMPLES:: @@ -1006,7 +992,7 @@ def inject_variable_test(name, value, depth): # from https://stackoverflow.com/questions/4103773/efficient-way-of-having-a-function-only-execute-once-in-a-loop def run_once(func): """ - Runs a function (successfully) only once. + Run a function (successfully) only once. The running can be reset by setting the ``has_run`` attribute to False @@ -1044,7 +1030,7 @@ def increase_recursion_limit(increment): INPUT: - - `increment`: increment to add to the current limit + - ``increment`` -- increment to add to the current limit EXAMPLES:: diff --git a/src/sage/misc/misc_c.pyx b/src/sage/misc/misc_c.pyx index 695806cdf69..2b7136ce584 100644 --- a/src/sage/misc/misc_c.pyx +++ b/src/sage/misc/misc_c.pyx @@ -37,7 +37,8 @@ cdef extern from *: def running_total(L, start=None): """ - Return a list where the i-th entry is the sum of all entries up to (and including) i. + Return a list where the `i`-th entry is the sum of all entries up to (and + including) `i`. INPUT: @@ -440,7 +441,8 @@ cpdef list normalize_index(object key, int size): INPUT: - - ``key`` -- the index key, which can be either an integer, a tuple/list of integers, or a slice. + - ``key`` -- the index key, which can be either an integer, a tuple/list of + integers, or a slice - ``size`` -- the size of the collection OUTPUT: @@ -622,10 +624,10 @@ cdef class sized_iter: - ``iterable`` -- object to be iterated over - - ``length`` -- (optional) the required length. If this is not - given, then ``len(iterable)`` will be used. + - ``length`` -- (optional) the required length; if this is not + given, then ``len(iterable)`` will be used - If the iterable does not have the given length, a ``ValueError`` is + If the iterable does not have the given length, a :exc:`ValueError` is raised during iteration. EXAMPLES:: diff --git a/src/sage/misc/mrange.py b/src/sage/misc/mrange.py index e0c2951329d..5f01348fe81 100644 --- a/src/sage/misc/mrange.py +++ b/src/sage/misc/mrange.py @@ -69,7 +69,6 @@ def _is_finite(L, fallback=True): sage: from itertools import product sage: _is_finite(product([1],[1])) # does not provide is_finite() or __len__() True - """ try: return L.is_finite() @@ -182,16 +181,16 @@ def mrange_iter(iter_list, typ=list): More precisely, return the iterator over all objects of type ``typ`` of n-tuples of Python ints with entries between 0 and the integers in the sizes list. The iterator is empty if sizes is empty or contains - any non-positive integer. + any nonpositive integer. INPUT: - - ``iter_list`` -- a finite iterable of finite iterables + - ``iter_list`` -- a finite iterable of finite iterables - - ``typ`` -- (default: list) a type or class; more - generally, something that can be called with a list as input. + - ``typ`` -- (default: list) a type or class; more + generally, something that can be called with a list as input - OUTPUT: a list + OUTPUT: list EXAMPLES:: @@ -228,24 +227,24 @@ class xmrange_iter: Return the multirange iterate derived from the given iterators and type. - .. note:: + .. NOTE:: This basically gives you the Cartesian product of sets. More precisely, return the iterator over all objects of type typ of n-tuples of Python ints with entries between 0 and the integers in the sizes list. The iterator is empty if sizes is empty or contains - any non-positive integer. + any nonpositive integer. Use :func:`mrange_iter` for the non-iterator form. INPUT: - - ``iter_list`` -- a list of objects usable as iterators (possibly - lists) + - ``iter_list`` -- list of objects usable as iterators (possibly + lists) - ``typ`` -- (default: list) a type or class; more generally, - something that can be called with a list as input. + something that can be called with a list as input OUTPUT: a generator @@ -336,7 +335,7 @@ def __len__(self): """ Return the cardinality of this iterator as an int. - This raises a :class:`TypeError` if the cardinality does not fit + This raises a :exc:`TypeError` if the cardinality does not fit into a Python int. EXAMPLES:: @@ -433,16 +432,16 @@ def mrange(sizes, typ=list): More precisely, return the iterator over all objects of type typ of n-tuples of Python ints with entries between 0 and the integers in the sizes list. The iterator is empty if sizes is empty or contains - any non-positive integer. + any nonpositive integer. INPUT: - - ``sizes`` -- a list of nonnegative integers + - ``sizes`` -- list of nonnegative integers - - ``typ`` -- (default: list) a type or class; more - generally, something that can be called with a list as input. + - ``typ`` -- (default: list) a type or class; more + generally, something that can be called with a list as input - OUTPUT: a list + OUTPUT: list EXAMPLES:: @@ -483,18 +482,16 @@ class xmrange: More precisely, return the iterator over all objects of type typ of n-tuples of Python ints with entries between 0 and the integers in the sizes list. The iterator is empty if sizes is empty or contains - any non-positive integer. + any nonpositive integer. Use mrange for the non-iterator form. INPUT: + - ``sizes`` -- list of nonnegative integers - - ``sizes`` -- a list of nonnegative integers - - - ``typ`` -- (default: list) a type or class; more - generally, something that can be called with a list as input. - + - ``typ`` -- (default: list) a type or class; more + generally, something that can be called with a list as input OUTPUT: a generator @@ -604,7 +601,7 @@ def cartesian_product_iterator(X): INPUT: - - ``X`` -- list or tuple of lists + - ``X`` -- list or tuple of lists OUTPUT: iterator over the Cartesian product of the elements of X @@ -639,7 +636,7 @@ def cantor_product(*args, **kwds): - a certain number of iterables - ``repeat`` -- an optional integer. If it is provided, the input is - repeated ``repeat`` times. + repeated ``repeat`` times Other keyword arguments are passed to :class:`sage.combinat.integer_lists.invlex.IntegerListsLex`. diff --git a/src/sage/misc/nested_class.pyx b/src/sage/misc/nested_class.pyx index 7e5d00c15d8..a3a42dfe5d4 100644 --- a/src/sage/misc/nested_class.pyx +++ b/src/sage/misc/nested_class.pyx @@ -11,15 +11,15 @@ incompatible with the pickling of such classes (pickling by name):: sage: A.B.__name__ 'B' -instead of more natural ``"A.B"``. Furthermore upon pickling *and* unpickling a -class with name ``"A.B"`` in a module ``mod``, the standard cPickle module -searches for ``"A.B"`` in ``mod.__dict__`` instead of looking up ``"A"`` and -then ``"B"`` in the result. See: https://groups.google.com/forum/#!topic/sage-devel/bHBV9KWAt64 +instead of more natural ``'A.B'``. Furthermore upon pickling *and* unpickling a +class with name ``'A.B'`` in a module ``mod``, the standard cPickle module +searches for ``'A.B'`` in ``mod.__dict__`` instead of looking up ``'A'`` and +then ``'B'`` in the result. See: https://groups.google.com/forum/#!topic/sage-devel/bHBV9KWAt64 This module provides two utilities to workaround this issue: - :func:`nested_pickle` "fixes" recursively the name of the subclasses of a - class and inserts their fullname ``"A.B"`` in ``mod.__dict__`` + class and inserts their fullname ``'A.B'`` in ``mod.__dict__`` - :class:`NestedClassMetaclass` is a metaclass ensuring that :func:`nested_pickle` is called on a class upon creation. @@ -30,8 +30,8 @@ See also :mod:`sage.misc.test_nested_class`. In Python 3, nested classes, like any class for that matter, have ``__qualname__`` and the standard pickle module uses it for pickling and - unpickling. Thus the pickle module searches for ``"A.B"`` first by looking - up ``"A"`` in ``mod``, and then ``"B"`` in the result. So there is no + unpickling. Thus the pickle module searches for ``'A.B'`` first by looking + up ``'A'`` in ``mod``, and then ``'B'`` in the result. So there is no pickling problem for nested classes in Python 3, and the two utilities are not really necessary. However, :class:`NestedClassMetaclass` is used widely in Sage and affects behaviors of Sage objects in other respects than in @@ -81,7 +81,7 @@ All of this is not perfect. In the following scenario:: sage: B1.A2 -The name for ``"A1.A2"`` could potentially be set to ``"B1.A2"``. But that will work anyway. +The name for ``'A1.A2'`` could potentially be set to ``'B1.A2'``. But that will work anyway. """ import sys @@ -108,7 +108,7 @@ cpdef modify_for_nested_pickle(cls, str name_prefix, module, first_run=True): - ``module`` -- the module object to modify with the mangled name - - ``first_run`` -- optional bool (default ``True``): whether or not + - ``first_run`` -- boolean (default: ``True``); whether or not this function is run for the first time on ``cls`` NOTE: @@ -177,7 +177,6 @@ cpdef modify_for_nested_pickle(cls, str name_prefix, module, first_run=True): 'A1.B1.C1' sage: getattr(A_module, 'A1.B2.C2', 'Not found').__name__ 'A1.B2.C2' - """ cdef str name, dotted_name cdef str mod_name = module.__name__ @@ -228,8 +227,8 @@ def nested_pickle(cls): sage: nested_pickle(A) - then the name of class ``"B"`` will be modified to ``"A.B"``, and the ``"A.B"`` - attribute of the module will be set to class ``"B"``:: + then the name of class ``'B'`` will be modified to ``'A.B'``, and the ``'A.B'`` + attribute of the module will be set to class ``'B'``:: sage: A.B.__name__ 'A.B' @@ -341,7 +340,6 @@ class MainClass(object, metaclass=NestedClassMetaclass): A dummy method to demonstrate the embedding of method signature for nested classes. ... - """ pass diff --git a/src/sage/misc/package.py b/src/sage/misc/package.py index c144cfca6f9..ca7a9ffd67c 100644 --- a/src/sage/misc/package.py +++ b/src/sage/misc/package.py @@ -78,10 +78,10 @@ def pip_remote_version(pkg, pypi_url=DEFAULT_PYPI, ignore_URLError=False): - ``pkg`` -- the package - - ``pypi_url`` -- (string, default: standard PyPI url) an optional Python + - ``pypi_url`` -- string (default: standard PyPI url) an optional Python package repository to use - - ``ignore_URLError`` -- (default: ``False``) if set to ``True`` then no + - ``ignore_URLError`` -- boolean (default: ``False``); if set to ``True`` then no error is raised if the connection fails and the function returns ``None`` EXAMPLES: @@ -237,11 +237,11 @@ def list_packages(*pkg_types: str, pkg_sources: List[str] = ['normal', 'pip', 's The keys are package names and values are named tuples with the following keys: - - ``'type'``: either ``'base``, ``'standard'``, ``'optional'``, or ``'experimental'`` - - ``'source'``: either ``'normal', ``'pip'``, or ``'script'`` - - ``'installed'``: boolean - - ``'installed_version'``: ``None`` or a string - - ``'remote_version'``: string + - ``'type'`` -- either ``'base``, ``'standard'``, ``'optional'``, or ``'experimental'`` + - ``'source'`` -- either ``'normal', ``'pip'``, or ``'script'`` + - ``'installed'`` -- boolean + - ``'installed_version'`` -- ``None`` or a string + - ``'remote_version'`` -- string INPUT: @@ -253,15 +253,15 @@ def list_packages(*pkg_types: str, pkg_sources: List[str] = ['normal', 'pip', 's If provided, list only the packages with the given source(s), otherwise list all packages. - - ``local`` -- (default: ``False``) if set to ``True``, then do not + - ``local`` -- boolean (default: ``False``); if set to ``True``, then do not consult remote (PyPI) repositories for package versions (only applicable for ``'pip'`` type) - - ``exclude_pip`` -- (default: ``False``) if set to ``True``, then + - ``exclude_pip`` -- boolean (default: ``False``); if set to ``True``, then pip packages are not considered. This is the same as removing ``'pip'`` - from ``pkg_sources``. + from ``pkg_sources`` - - ``ignore_URLError`` -- (default: ``False``) if set to ``True``, then + - ``ignore_URLError`` -- boolean (default: ``False``); if set to ``True``, then connection errors will be ignored EXAMPLES:: @@ -371,7 +371,6 @@ def _spkg_inst_dirs(): sage: from sage.misc.package import _spkg_inst_dirs sage: list(_spkg_inst_dirs()) [...] - """ last_inst_dir = None for inst_dir in (sage.env.SAGE_LOCAL_SPKG_INST, sage.env.SAGE_VENV_SPKG_INST): @@ -388,7 +387,7 @@ def installed_packages(exclude_pip=True): INPUT: - - ``exclude_pip`` -- (default: ``True``) whether "pip" packages + - ``exclude_pip`` -- boolean (default: ``True``); whether "pip" packages are excluded from the list EXAMPLES: @@ -434,10 +433,9 @@ def is_package_installed(package, exclude_pip=True): - ``package`` -- the name of the package - - ``exclude_pip`` -- (default: ``True``) whether to consider pip + - ``exclude_pip`` -- boolean (default: ``True``); whether to consider pip type packages - EXAMPLES:: sage: from sage.misc.package import is_package_installed @@ -470,7 +468,7 @@ def is_package_installed_and_updated(package: str) -> bool: INPUT: - - ``package`` -- the name of the package. + - ``package`` -- the name of the package EXAMPLES:: @@ -493,10 +491,10 @@ def package_versions(package_type, local=False): INPUT: - - ``package_type`` -- (string) one of ``"standard"``, ``"optional"`` or - ``"experimental"`` + - ``package_type`` -- string; one of ``'standard'``, ``'optional'`` or + ``'experimental'`` - - ``local`` -- (boolean, default: ``False``) only query local data (no internet needed) + - ``local`` -- boolean (default: ``False``); only query local data (no internet needed) For packages of the given type, return a dictionary whose entries are of the form ``'package': (installed, latest)``, where diff --git a/src/sage/misc/package_dir.py b/src/sage/misc/package_dir.py index a16f144f400..b15374e3bbc 100644 --- a/src/sage/misc/package_dir.py +++ b/src/sage/misc/package_dir.py @@ -106,8 +106,8 @@ def read_distribution(src_file): OUTPUT: - - a string, the name of the distribution package (``PKG``); or the empty - string if no directive was found. + A string, the name of the distribution package (``PKG``), or the empty + string if no directive was found. EXAMPLES:: @@ -251,7 +251,7 @@ def is_package_or_sage_namespace_package_dir(path, *, distribution_filter=None): INPUT: - - ``path`` -- a directory name. + - ``path`` -- a directory name - ``distribution_filter`` -- (default: ``None``) only consider ``all*.py`` files whose distribution (from a @@ -307,7 +307,7 @@ def is_package_or_sage_namespace_package_dir(path, *, distribution_filter=None): @contextmanager def cython_namespace_package_support(): r""" - Activate namespace package support in Cython 0.x + Activate namespace package support in Cython 0.x. See https://github.com/cython/cython/issues/2918#issuecomment-991799049 """ @@ -333,16 +333,16 @@ def walk_packages(path=None, prefix='', onerror=None): INPUT: - - ``path`` -- a list of paths to look for modules in or - ``None`` (all accessible modules). + - ``path`` -- list of paths to look for modules in or + ``None`` (all accessible modules) - - ``prefix`` -- a string to output on the front of every module name - on output. + - ``prefix`` -- string to output on the front of every module name + on output - ``onerror`` -- a function which gets called with one argument (the name of the package which was being imported) if any exception occurs while trying to import a package. If ``None``, ignore - :class:`ImportError` but propagate all other exceptions. + :exc:`ImportError` but propagate all other exceptions. EXAMPLES:: @@ -469,7 +469,7 @@ def _distribution_from_all_filename(filename): "do not change files that already have a nonempty directive")) parser.add_argument('--set', metavar='DISTRIBUTION', type=str, default=None, help="add or update the 'sage_setup: DISTRIBUTION' directive in FILES") - parser.add_argument('--from-egg-info', action="store_true", default=False, + parser.add_argument('--from-egg-info', action='store_true', default=False, help="take FILES from pkgs/DISTRIBUTION/DISTRIBUTION.egg-info/SOURCES.txt") parser.add_argument("filename", metavar='FILES', nargs='*', type=str, help=("source files or directories (default: all files from SAGE_SRC, " diff --git a/src/sage/misc/parser.pyx b/src/sage/misc/parser.pyx index e9015d1cbcc..7a2c2cc99a4 100644 --- a/src/sage/misc/parser.pyx +++ b/src/sage/misc/parser.pyx @@ -330,7 +330,7 @@ cdef class Tokenizer: cpdef int next(self) noexcept: """ - Returns the next token in the string. + Return the next token in the string. EXAMPLES:: @@ -353,7 +353,7 @@ cdef class Tokenizer: cpdef int last(self) noexcept: """ - Returns the last token seen. + Return the last token seen. EXAMPLES:: @@ -372,8 +372,8 @@ cdef class Tokenizer: cpdef int peek(self) noexcept: """ - Returns the next token that will be encountered, without changing - the state of self. + Return the next token that will be encountered, without changing + the state of ``self``. EXAMPLES:: @@ -397,8 +397,8 @@ cdef class Tokenizer: cpdef bint backtrack(self) except -2: """ - Put self in such a state that the subsequent call to next() will - return the same as if next() had not been called. + Put ``self`` in such a state that the subsequent call to ``next()`` + will return the same as if ``next()`` had not been called. Currently, one can only backtrack once. @@ -457,18 +457,18 @@ cdef class Parser: INPUT: - - make_int -- callable object to construct integers from strings (default int) - - make_float -- callable object to construct real numbers from strings (default float) - - make_var -- callable object to construct variables from strings (default str) + - ``make_int`` -- callable object to construct integers from strings (default: int) + - ``make_float`` -- callable object to construct real numbers from strings (default: float) + - ``make_var`` -- callable object to construct variables from strings (default: str) this may also be a dictionary of variable names - - make_function -- callable object to construct callable functions from strings + - ``make_function`` -- callable object to construct callable functions from strings this may also be a dictionary - - implicit_multiplication -- whether or not to accept implicit multiplication + - ``implicit_multiplication`` -- whether or not to accept implicit multiplication OUTPUT: - The evaluated expression tree given by the string, where the above - functions are used to create the leaves of this tree. + The evaluated expression tree given by the string, where the above + functions are used to create the leaves of this tree. EXAMPLES:: @@ -596,7 +596,7 @@ cdef class Parser: cpdef p_matrix(self, Tokenizer tokens): """ - Parse a matrix + Parse a matrix. EXAMPLES:: @@ -897,7 +897,6 @@ cdef class Parser: factorial(x^2) sage: p.p_factor(Tokenizer('x!^2')) factorial(x)^2 - """ operand1 = self.p_atom(tokens) cdef int token = tokens.next() @@ -976,7 +975,7 @@ cdef class Parser: # args = arg (',' arg)* | EMPTY cpdef p_args(self, Tokenizer tokens): """ - Returns a list, dict pair. + Return a ``list, dict`` pair. EXAMPLES:: @@ -1006,8 +1005,8 @@ cdef class Parser: # arg = expr | name '=' expr cpdef p_arg(self, Tokenizer tokens): """ - Returns an expr, or a (name, expr) tuple corresponding to a single - function call argument. + Return an ``expr``, or a ``(name, expr)`` tuple corresponding to a + single function call argument. EXAMPLES: @@ -1031,7 +1030,6 @@ cdef class Parser: sage: p = Parser(make_var=var) # needs sage.symbolic sage: p.p_arg(Tokenizer("[x]")) # needs sage.symbolic [x] - """ cdef int token = tokens.next() if token == NAME and tokens.peek() == c'=': diff --git a/src/sage/misc/persist.pyx b/src/sage/misc/persist.pyx index d299ec304cb..55540dc27b7 100644 --- a/src/sage/misc/persist.pyx +++ b/src/sage/misc/persist.pyx @@ -10,7 +10,7 @@ Object persistence You can load and save most Sage object to disk using the load and save member functions and commands. -.. note:: +.. NOTE:: It is impossible to save certain Sage objects to disk. For example, if `x` is a MAGMA object, i.e., a wrapper around an object @@ -142,7 +142,7 @@ def load(*filename, compress=True, verbose=True, **kwargs): Files with a ``.sage`` extension are preparsed. Also note that we can access global variables:: - sage: t = tmp_filename(ext=".sage") + sage: t = tmp_filename(ext='.sage') sage: with open(t, 'w') as f: ....: _ = f.write("a += Mod(2/3, 11)") # This evaluates to Mod(8, 11) sage: a = -1 @@ -153,7 +153,7 @@ def load(*filename, compress=True, verbose=True, **kwargs): We can load Fortran files:: sage: code = ' subroutine hello\n print *, "Hello World!"\n end subroutine hello\n' - sage: t = tmp_filename(ext=".F") + sage: t = tmp_filename(ext='.F') sage: with open(t, 'w') as f: ....: _ = f.write(code) sage: load(t) # needs numpy @@ -273,7 +273,7 @@ def save(obj, filename, compress=True, **kwargs): Check that :issue:`11577` is fixed:: sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".bar") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.bar') as f: ....: save((1,1), f.name) ....: load(f.name) (1, 1) @@ -525,7 +525,6 @@ def register_unpickle_override(module, name, callable, call_name=None): # tuple as input. All kinds of problems happen # if we don't do this. return sage.rings.integer.make_integer, (self.str(32),) - """ unpickle_override[(module, name)] = (callable, call_name) @@ -714,7 +713,7 @@ class SagePickler(_BasePickler): INPUT: - ``file_obj`` -- a readable file-like object returning ``bytes`` from - which the pickle data will be loaded. + which the pickle data will be loaded - ``persistent_id`` -- callable or None; if given this callable takes a single object to be pickled, and returns an "ID" (a key with which to @@ -788,7 +787,6 @@ class SagePickler(_BasePickler): Traceback (most recent call last): ... UnicodeDecodeError: 'ascii' codec can...t decode byte 0x80 in position 0: ordinal not in range(128) - """ def __init__(self, file_obj, persistent_id=None, py2compat=True): @@ -808,14 +806,12 @@ class SagePickler(_BasePickler): INPUT: - - ``obj`` -- the object to pickle. + - ``obj`` -- the object to pickle - ``kwargs`` -- keyword arguments passed to the - :class:`sage.misc.persist.SagePickler` constructor. - - OUTPUT: + :class:`sage.misc.persist.SagePickler` constructor - - ``pickle`` -- the pickled object as ``bytes``. + OUTPUT: ``pickle`` -- the pickled object as ``bytes`` EXAMPLES:: @@ -847,7 +843,7 @@ class SageUnpickler(_BaseUnpickler): INPUT: - ``file_obj`` -- a readable file-like object returning ``bytes`` from - which the pickle data will be loaded. + which the pickle data will be loaded - ``persistent_load`` -- callable or None; if given this callable implements loading of persistent external objects. The function @@ -856,7 +852,7 @@ class SageUnpickler(_BaseUnpickler): for more details. - ``kwargs`` -- additional keyword arguments passed to the - ``pickle.Unpickler`` constructor. + ``pickle.Unpickler`` constructor .. _pickling and unpickling external objects: https://docs.python.org/2.7/library/pickle.html#pickling-and-unpickling-external-objects @@ -894,15 +890,12 @@ class SageUnpickler(_BaseUnpickler): INPUT: - - ``data`` -- the pickle data as ``bytes``. + - ``data`` -- the pickle data as ``bytes`` - ``kwargs`` -- keyword arguments passed to the - :class:`sage.misc.persist.SageUnpickler` constructor. - - OUTPUT: - - - ``obj`` -- the object that was serialized to the given pickle data. + :class:`sage.misc.persist.SageUnpickler` constructor + OUTPUT: ``obj`` -- the object that was serialized to the given pickle data EXAMPLES:: @@ -931,9 +924,9 @@ def loads(s, compress=True, **kwargs): [ 1 2] [ 3 -4/3] - If compress is True (the default), it will try to decompress + If compress is ``True`` (the default), it will try to decompress the data with zlib and with bz2 (in turn); if neither succeeds, - it will assume the data is actually uncompressed. If compress=False + it will assume the data is actually uncompressed. If ``compress==False`` is explicitly specified, then no decompression is attempted. Further arguments are passed to python's :func:`pickle.load`. @@ -1020,7 +1013,7 @@ def picklejar(obj, dir=None): - ``obj`` -- a pickleable object - - ``dir`` -- a string or None; if None then ``dir`` defaults to + - ``dir`` -- string or ``None``; if ``None`` then ``dir`` defaults to ``DOT_SAGE/pickle_jar`` EXAMPLES:: @@ -1098,14 +1091,14 @@ def unpickle_all(target, debug=False, run_test_suite=False): INPUT: - - ``target`` -- a string; the name of a directory or of a (possibly + - ``target`` -- string; the name of a directory or of a (possibly compressed) tar archive that contains a single directory of ``.sobj`` files. The tar archive can be in any format that python's ``tarfile`` module understands; for example, ``.tar.gz`` or ``.tar.bz2``. - - ``debug`` -- a boolean (default: ``False``) + - ``debug`` -- boolean (default: ``False``) whether to report a stacktrace in case of failure - - ``run_test_suite`` -- a boolean (default: ``False``) + - ``run_test_suite`` -- boolean (default: ``False``) whether to run ``TestSuite(x).run()`` on the unpickled objects OUTPUT: @@ -1114,7 +1107,7 @@ def unpickle_all(target, debug=False, run_test_suite=False): of successfully unpickled files, and the second reporting the number (zero) of failures. If there are failures, however, then a list of failed files will be printed before either of those lines, - and the failure count will of course be non-zero. + and the failure count will of course be nonzero. .. WARNING:: @@ -1147,7 +1140,7 @@ def unpickle_all(target, debug=False, run_test_suite=False): # 706 for background. with tarfile.open(target) as tf: if hasattr(tarfile, "data_filter"): - tf.extractall(T, filter="data") + tf.extractall(T, filter='data') else: tf.extractall(T) diff --git a/src/sage/misc/prandom.py b/src/sage/misc/prandom.py index c8b41a5e95d..dbfa9ff7085 100644 --- a/src/sage/misc/prandom.py +++ b/src/sage/misc/prandom.py @@ -297,7 +297,7 @@ def expovariate(lambd): def gammavariate(alpha, beta): r""" - Gamma distribution. Not the gamma function! + Gamma distribution. (Not the gamma function.) Conditions on the parameters are alpha > 0 and beta > 0. diff --git a/src/sage/misc/profiler.py b/src/sage/misc/profiler.py index 82746c8f023..37d1e76e99c 100644 --- a/src/sage/misc/profiler.py +++ b/src/sage/misc/profiler.py @@ -82,9 +82,10 @@ class Profiler: def __init__(self, systems=[], verbose=False): """ INPUT: - systems -- a list of interfaces to other system which implements a cputime - method. The cputimes of all provided systems will be added - to the cputime of Sage itself. + + - ``systems`` -- list of interfaces to other system which implements a + cputime method. The cputimes of all provided systems will be added + to the cputime of Sage itself. """ systems = [e.cputime for e in systems] self._cputime_functions = [cputime] + list(systems) @@ -152,7 +153,7 @@ def __repr__(self): def print_last(self): """ - Prints the last profiler step + Print the last profiler step. """ if not self._checkpoints: return "" diff --git a/src/sage/misc/python.py b/src/sage/misc/python.py index d446dfe604d..fcbf8e4dafd 100644 --- a/src/sage/misc/python.py +++ b/src/sage/misc/python.py @@ -3,7 +3,7 @@ class Python: """ - Allows for evaluating a chunk of code without any preparsing. + Allow for evaluating a chunk of code without any preparsing. """ def eval(self, x, globals, locals=None): @@ -15,8 +15,8 @@ def eval(self, x, globals, locals=None): INPUT: - - ``x`` -- a string - - ``globals`` -- a dictionary + - ``x`` -- string + - ``globals`` -- dictionary - ``locals`` -- completely IGNORED EXAMPLES:: diff --git a/src/sage/misc/random_testing.py b/src/sage/misc/random_testing.py index 2625e6ec1e1..bda8cee6ba6 100644 --- a/src/sage/misc/random_testing.py +++ b/src/sage/misc/random_testing.py @@ -21,10 +21,10 @@ def random_testing(fn): INPUT: - - ``fn`` -- The function that we are wrapping for random testing. + - ``fn`` -- the function that we are wrapping for random testing The resulting function will take two additional arguments, *seed* - (default ``None``) and *print_seed* (default ``False``). The + (default: ``None``) and *print_seed* (default: ``False``). The result will set the random number seed to the given seed value (or to a truly random value, if *seed* is not specified), then call the original function. If *print_seed* is true, then the seed will diff --git a/src/sage/misc/randstate.pyx b/src/sage/misc/randstate.pyx index f1aefafd68a..79435da9ce7 100644 --- a/src/sage/misc/randstate.pyx +++ b/src/sage/misc/randstate.pyx @@ -283,7 +283,7 @@ this module correctly. Otherwise, it depends on what random number generator you want to use. -- ``gmp_randstate_t`` -- If you want to use some random number +- ``gmp_randstate_t`` -- if you want to use some random number generator that takes a ``gmp_randstate_t`` (like ``mpz_urandomm`` or ``mpfr_urandomb``), then use code like the following:: @@ -298,7 +298,7 @@ Otherwise, it depends on what random number generator you want to use. every function that wants to use it; don't cache it globally or in a class. (Such caching would break ``set_random_seed``). -- ``Python`` -- If you want to use the random number generators from +- ``Python`` -- if you want to use the random number generators from the :mod:`random` module, you have two choices. The slightly easier choice is to import functions from :mod:`sage.misc.prandom`; for instance, you can simply replace @@ -319,7 +319,7 @@ Otherwise, it depends on what random number generator you want to use. :class:`Random` object globally or in a class. (Such caching would break ``set_random_seed``). -- ``GAP`` -- If you are calling code in GAP that uses random numbers, +- ``GAP`` -- if you are calling code in GAP that uses random numbers, call ``set_seed_gap`` at the beginning of your function, like this:: from sage.misc.randstate import current_randstate @@ -332,7 +332,7 @@ Otherwise, it depends on what random number generator you want to use. don't cache it globally or in a class. (Such caching would break ``set_random_seed``). -- ``Pari`` -- If you are calling code in the Pari library that uses +- ``Pari`` -- if you are calling code in the Pari library that uses random numbers, call ``set_seed_pari`` at the beginning of your function, like this:: @@ -346,7 +346,7 @@ Otherwise, it depends on what random number generator you want to use. don't cache it globally or in a class. (Such caching would break ``set_random_seed``). -- ``Pari/gp`` -- If you are calling code in a Pari/gp subprocess that +- ``Pari/gp`` -- if you are calling code in a Pari/gp subprocess that uses random numbers, call ``set_seed_gp`` at the beginning of your function, like this:: @@ -363,7 +363,7 @@ Otherwise, it depends on what random number generator you want to use. every function that wants to use it; don't cache it globally or in a class. (Such caching would break ``set_random_seed``). -- ``NTL`` -- If you are calling code in the NTL library that uses +- ``NTL`` -- if you are calling code in the NTL library that uses random numbers, call ``set_seed_ntl`` at the beginning of your function, like this:: @@ -376,7 +376,7 @@ Otherwise, it depends on what random number generator you want to use. don't cache it globally or in a class. (Such caching would break ``set_random_seed``). -- ``libc`` -- If you are writing code that calls the libc function +- ``libc`` -- if you are writing code that calls the libc function :func:`random()`: don't! The :func:`random()` function does not give reproducible results across different operating systems, so we can't make portable doctests for the results. Instead, do:: @@ -642,7 +642,7 @@ cdef class randstate: cpdef set_seed_libc(self, bint force): r""" - Checks to see if ``self`` was the most recent :class:`randstate` + Check to see if ``self`` was the most recent :class:`randstate` to seed the libc random number generator. If not, seeds the libc random number generator. (Do not use the libc random number generator if you have a choice; its randomness is poor, @@ -667,7 +667,7 @@ cdef class randstate: cpdef set_seed_ntl(self, bint force): r""" - Checks to see if ``self`` was the most recent :class:`randstate` + Check to see if ``self`` was the most recent :class:`randstate` to seed the NTL random number generator. If not, seeds the generator. If the argument ``force`` is ``True``, seeds the generator unconditionally. @@ -693,7 +693,7 @@ cdef class randstate: def set_seed_gap(self): r""" - Checks to see if ``self`` was the most recent :class:`randstate` + Check to see if ``self`` was the most recent :class:`randstate` to seed the GAP random number generator. If not, seeds the generator. @@ -730,7 +730,7 @@ cdef class randstate: def set_seed_gp(self, gp=None): r""" - Checks to see if ``self`` was the most recent :class:`randstate` + Check to see if ``self`` was the most recent :class:`randstate` to seed the random number generator in the given instance of gp. (If no instance is given, uses the one in :class:`gp `.) If not, seeds the generator. @@ -771,7 +771,7 @@ cdef class randstate: def set_seed_pari(self): r""" - Checks to see if ``self`` was the most recent :class:`randstate` to + Check to see if ``self`` was the most recent :class:`randstate` to seed the Pari random number generator. If not, seeds the generator. @@ -807,7 +807,7 @@ cdef class randstate: cpdef int c_random(self) noexcept: r""" - Returns a 31-bit random number. Intended for internal + Return a 31-bit random number. Intended for internal use only; instead of calling ``current_randstate().c_random()``, it is equivalent (but probably faster) to call the :meth:`random ` method of this @@ -830,7 +830,7 @@ cdef class randstate: cpdef double c_rand_double(self) noexcept: r""" - Returns a random floating-point number between 0 and 1. + Return a random floating-point number between 0 and 1. EXAMPLES:: @@ -956,7 +956,7 @@ seed = randstate cpdef int random() noexcept: r""" - Returns a 31-bit random number. Intended as a drop-in replacement for + Return a 31-bit random number. Intended as a drop-in replacement for the libc :func:`random()` function. EXAMPLES:: @@ -971,7 +971,7 @@ cpdef int random() noexcept: def initial_seed(): r""" - Returns the initial seed used to create the current :class:`randstate`. + Return the initial seed used to create the current :class:`randstate`. EXAMPLES:: @@ -1031,7 +1031,7 @@ def benchmark_mt(): cpdef int _doctest_libc_random() noexcept: r""" - Returns the result of :func:`random()` from libc. + Return the result of :func:`random()` from libc. Only for use in doctests; this should not actually be used in Sage, since the resulting random number stream is not portable across diff --git a/src/sage/misc/remote_file.py b/src/sage/misc/remote_file.py index d6ffd09c5ea..7e1cfef2ea7 100644 --- a/src/sage/misc/remote_file.py +++ b/src/sage/misc/remote_file.py @@ -10,7 +10,7 @@ def get_remote_file(filename, verbose=True) -> Path: INPUT: - ``filename`` -- the URL of a file on the web, e.g., - ``"http://modular.math.washington.edu/myfile.txt"`` + ``'http://modular.math.washington.edu/myfile.txt'`` - ``verbose`` -- whether to display download status @@ -27,7 +27,6 @@ def get_remote_file(filename, verbose=True) -> Path: print("hi from the net") print(2 + 3) - """ if verbose: print("Attempting to load remote file: " + filename) diff --git a/src/sage/misc/replace_dot_all.py b/src/sage/misc/replace_dot_all.py index 2911f72b626..16ac2124377 100644 --- a/src/sage/misc/replace_dot_all.py +++ b/src/sage/misc/replace_dot_all.py @@ -283,11 +283,10 @@ def process_line(location, line, replacements, row_index, verbose=False): - ``line`` -- a source code line - ``replacements`` -- the array output from :func:`find_replacements` - ``row_index`` -- the line number where ``import`` appears - - ``verbose`` -- if True, issue print statements when interesting examples are found + - ``verbose`` -- if ``True``, issue print statements when interesting + examples are found - OUTPUT: - - an array ``[new_line, replacements]`` with entries + OUTPUT: an array ``[new_line, replacements]`` with entries - ``new_line`` -- the modified import statement (possibly now on several lines) - ``replacements`` -- just returns the original replacements with its index 0 element removed if ``replacements`` is nonempty @@ -348,7 +347,7 @@ def make_replacements_in_file(location, package_regex=None, verbose=False, outpu - ``location`` -- a file path - ``package_regex`` -- (default: :obj:`default_package_regex`) a regular expression matching the ``sage.PAC.KAGE.all`` package names from which we do not want to import. - - ``verbose`` -- if True, issue print statements when interesting examples are found + - ``verbose`` -- if ``True``, issue print statements when interesting examples are found - ``output`` -- a file path; if ``None``, overwrite the file given by ``location`` EXAMPLES:: @@ -398,7 +397,7 @@ def walkdir_replace_dot_all(dir, file_regex=r'.*[.](py|pyx|pxi)$', package_regex - ``file_regex`` -- a regular expression matching the file names to process - ``package_regex`` -- (default: :obj:`default_package_regex`) a regular expression matching the ``sage.PAC.KAGE.all`` package names from which we do not want to import. - - ``verbose`` -- if True, print statements when interesting examples are found + - ``verbose`` -- if ``True``, print statements when interesting examples are found - ``excluded_file_regex`` -- a regular expression matching the file names to exclude EXAMPLES:: diff --git a/src/sage/misc/repr.py b/src/sage/misc/repr.py index ae765ff154a..d0bd0396f1f 100644 --- a/src/sage/misc/repr.py +++ b/src/sage/misc/repr.py @@ -12,9 +12,7 @@ def coeff_repr(c, is_latex=False): - ``c`` -- a coefficient (i.e., an element of a ring) - OUTPUT: - - A string + OUTPUT: string EXAMPLES:: @@ -47,7 +45,7 @@ def coeff_repr(c, is_latex=False): return s -def repr_lincomb(terms, is_latex=False, scalar_mult="*", strip_one=False, +def repr_lincomb(terms, is_latex=False, scalar_mult='*', strip_one=False, repr_monomial=None, latex_scalar_mult=None): """ Compute a string representation of a linear combination of some @@ -57,15 +55,11 @@ def repr_lincomb(terms, is_latex=False, scalar_mult="*", strip_one=False, - ``terms`` -- list of terms, as pairs (support, coefficient) - ``is_latex`` -- whether to produce latex (default: ``False``) - - ``scalar_mult`` -- string representing the multiplication (default:``'*'``) + - ``scalar_mult`` -- string representing the multiplication (default: ``'*'``) - ``latex_scalar_mult`` -- latex string representing the multiplication (default: a space if ``scalar_mult`` is ``'*'``; otherwise ``scalar_mult``) - ``coeffs`` -- for backward compatibility - OUTPUT: - - - ``str`` -- a string - EXAMPLES:: sage: repr_lincomb([('a',1), ('b',-2), ('c',3)]) diff --git a/src/sage/misc/reset.pyx b/src/sage/misc/reset.pyx index e8247bb8f89..50e6a15b4c7 100644 --- a/src/sage/misc/reset.pyx +++ b/src/sage/misc/reset.pyx @@ -24,10 +24,10 @@ def reset(vars=None, attached=False): INPUT: - - ``vars`` -- a list, or space or comma separated string (default: - ``None``), variables to restore + - ``vars`` -- list or space or comma separated string (default: + ``None``); variables to restore - - ``attached`` -- boolean (default: ``False``), if ``vars`` is not ``None``, + - ``attached`` -- boolean (default: ``False``); if ``vars`` is not ``None``, whether to detach all attached files EXAMPLES:: @@ -96,8 +96,8 @@ def restore(vars=None): INPUT: - - ``vars`` -- string or list (default: ``None``), if not ``None``, restores - just the given variables to the default value. + - ``vars`` -- string or list (default: ``None``); if not ``None``, restores + just the given variables to the default value EXAMPLES:: diff --git a/src/sage/misc/rest_index_of_methods.py b/src/sage/misc/rest_index_of_methods.py index db32565e3ab..0d1d46f63b7 100644 --- a/src/sage/misc/rest_index_of_methods.py +++ b/src/sage/misc/rest_index_of_methods.py @@ -24,18 +24,18 @@ def gen_rest_table_index(obj, names=None, sort=True, only_local_functions=True, INPUT: - - ``obj`` -- a list of functions, a module or a class. If given a list of + - ``obj`` -- list of functions, a module or a class. If given a list of functions, the generated table will consist of these. If given a module or a class, all functions/methods it defines will be listed, except deprecated or those starting with an underscore. In the case of a class, note that inherited methods are not displayed. - - ``names`` -- a dictionary associating a name to a function. Takes + - ``names`` -- dictionary associating a name to a function. Takes precedence over the automatically computed name for the functions. Only used when ``list_of_entries`` is a list. - ``sort`` -- boolean (default: ``True``); whether to sort the list of - methods lexicographically. + methods lexicographically - ``only_local_functions`` -- boolean (default: ``True``); if ``list_of_entries`` is a module, ``only_local_functions = True`` means @@ -230,7 +230,7 @@ def list_of_subfunctions(root, only_local_functions=True): INPUT: - - ``root`` -- the module, or class, whose elements are to be listed. + - ``root`` -- the module, or class, whose elements are to be listed - ``only_local_functions`` -- boolean (default: ``True``); if ``root`` is a module, ``only_local_functions = True`` means that imported functions will @@ -259,7 +259,6 @@ def list_of_subfunctions(root, only_local_functions=True): sage: list_of_subfunctions(A) # needs sage.graphs ([], {: 'x'}) - """ if inspect.ismodule(root): ismodule = True @@ -305,7 +304,7 @@ def gen_thematic_rest_table_index(root, additional_categories=None, only_local_f INPUT: - - ``root`` -- the module, or class, whose elements are to be listed. + - ``root`` -- the module, or class, whose elements are to be listed - ``additional_categories`` -- dictionary (default: ``None``); a dictionary associating a category (given as a string) to a function's name. Can be @@ -355,8 +354,8 @@ def doc_index(name): INPUT: - - ``name`` -- a string, which will become the title of the index in which - this function/method will appear. + - ``name`` -- string, which will become the title of the index in which + this function/method will appear EXAMPLES:: diff --git a/src/sage/misc/sage_eval.py b/src/sage/misc/sage_eval.py index e69ee6ebda6..eba54910477 100644 --- a/src/sage/misc/sage_eval.py +++ b/src/sage/misc/sage_eval.py @@ -22,32 +22,26 @@ def sage_eval(source, locals=None, cmds='', preparse=True): INPUT: + - ``source`` -- string or object with a ``_sage_`` + method - - ``source`` -- a string or object with a ``_sage_`` - method + - ``locals`` -- evaluate in namespace of :mod:`sage.all` plus + the locals dictionary - - ``locals`` -- evaluate in namespace of :mod:`sage.all` plus - the locals dictionary + - ``cmds`` -- string; sequence of commands to be run + before source is evaluated - - ``cmds`` -- string; sequence of commands to be run - before source is evaluated. + - ``preparse`` -- boolean (default: ``True``); if ``True``, preparse the + string expression - - ``preparse`` -- (default: ``True``) if True, preparse the - string expression. - - - EXAMPLES: This example illustrates that preparsing is applied. - - :: + EXAMPLES: This example illustrates that preparsing is applied:: sage: eval('2^3') 1 sage: sage_eval('2^3') 8 - However, preparsing can be turned off. - - :: + However, preparsing can be turned off:: sage: sage_eval('2^3', preparse=False) 1 @@ -63,9 +57,7 @@ def sage_eval(source, locals=None, cmds='', preparse=True): ``from sage.all import *``. Even though ``bernoulli`` has been redefined in the local scope, when calling :func:`sage_eval` the default value meaning of :func:`bernoulli` - is used. Likewise for ``QQ`` below. - - :: + is used. Likewise for ``QQ`` below:: sage: bernoulli = lambda x : x^2 sage: bernoulli(6) @@ -85,9 +77,7 @@ def sage_eval(source, locals=None, cmds='', preparse=True): sage: parent(sage_eval('QQ(2)')) Rational Field - This example illustrates setting a variable for use in evaluation. - - :: + This example illustrates setting a variable for use in evaluation:: sage: x = 5 sage: eval('4//3 + x', {'x': 25}) @@ -128,9 +118,7 @@ def sage_eval(source, locals=None, cmds='', preparse=True): This example illustrates how :mod:`sage_eval` can be useful when evaluating the output of other computer algebra - systems. - - :: + systems:: sage: # needs sage.libs.gap sage: R. = PolynomialRing(RationalField()) diff --git a/src/sage/misc/sage_input.py b/src/sage/misc/sage_input.py index 025b7b96f5e..08bfde6e715 100644 --- a/src/sage/misc/sage_input.py +++ b/src/sage/misc/sage_input.py @@ -187,20 +187,20 @@ def sage_input(x, preparse=True, verify=False, allow_locals=False): - ``x`` -- the value we want to find an input form for - - ``preparse`` -- (default ``True``) Whether to generate code that requires + - ``preparse`` -- (default: ``True``) whether to generate code that requires the preparser. With ``True``, generated code requires the preparser. With ``False``, generated code requires that the preparser not be used. With ``None``, generated code will work whether or not the preparser is used. - - ``verify`` -- (default ``False``) If ``True``, then the answer will be + - ``verify`` -- (default: ``False``) if ``True``, then the answer will be evaluated with :func:`sage_eval`, and an exception will be raised if the result is not equal to the original value. (In fact, for ``verify=True``, :func:`sage_input` is effectively run three times, with ``preparse`` set to ``True``, ``False``, and ``None``, and all three results are checked.) This is particularly useful for doctests. - - ``allow_locals`` -- (default ``False``) If ``True``, then values that + - ``allow_locals`` -- (default: ``False``) if ``True``, then values that :func:`sage_input` cannot handle are returned in a dictionary, and the returned code assumes that this dictionary is passed as the ``locals`` parameter of :func:`sage_eval`. (Otherwise, if :func:`sage_input` cannot @@ -315,16 +315,16 @@ def __init__(self, allow_locals=False, preparse=True): INPUT: - - ``allow_locals`` -- (default ``False``) If true, then values - that cannot be converted to input form will be stored in - a dictionary, which must be passed as the ``locals`` - when evaluating the result. + - ``allow_locals`` -- (default: ``False``) if true, then values + that cannot be converted to input form will be stored in + a dictionary, which must be passed as the ``locals`` + when evaluating the result. - - ``preparse`` -- (default ``True``) If true, then the result - will assume that the preparser is enabled. If false, then - the result will assume that the preparser is disabled. - If ``None``, then the result will work whether or - not the preparser is enabled. + - ``preparse`` -- (default: ``True``) if true, then the result + will assume that the preparser is enabled. If false, then + the result will assume that the preparser is disabled. + If ``None``, then the result will work whether or + not the preparser is enabled. EXAMPLES:: @@ -345,7 +345,7 @@ def __init__(self, allow_locals=False, preparse=True): def __call__(self, x, coerced=False): r""" - Tries to convert an arbitrary value ``x`` into a + Try to convert an arbitrary value ``x`` into a :class:`SageInputExpression` (an SIE). We first check to see if an SIE has been cached for ``x``; @@ -529,7 +529,7 @@ def __call__(self, x, coerced=False): def preparse(self): r""" - Checks the preparse status. + Check the preparse status. It returns ``True`` if the preparser will be enabled, ``False`` if it will be disabled, and ``None`` if the result must work whether or not @@ -551,7 +551,7 @@ def preparse(self): def int(self, n): r""" - Return a raw SIE from the integer ``n`` + Return a raw SIE from the integer ``n``. As it is raw, it may read back as a Sage Integer or a Python int, depending on its size and whether the preparser is enabled. @@ -750,7 +750,7 @@ def import_name(self, module, name, alt_name=None): def assign(self, e, val): r""" - Constructs a command that performs the assignment ``e=val``. + Construct a command that performs the assignment ``e=val``. Can only be used as an argument to the ``command`` method. @@ -1008,7 +1008,7 @@ def parent_with_gens(self, parent, sie, gen_names, name, gens_syntax=None): def gen(self, parent, n=0): r""" Given a parent, returns a :class:`SageInputExpression` for - the `n`-th (default 0) generator of the parent. + the `n`-th (default: 0) generator of the parent. EXAMPLES:: @@ -1259,7 +1259,7 @@ def __init__(self, sib): def _sie_is_simple(self): r""" - Returns ``True`` if this :class:`SageInputExpression` is simple + Return ``True`` if this :class:`SageInputExpression` is simple enough that duplicate uses are not worth caching. Normally this will be true if the expression represents a single token. @@ -1276,7 +1276,7 @@ def _sie_is_simple(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SageInputExpression`. EXAMPLES:: @@ -1772,7 +1772,7 @@ def __init__(self, sib, n): - ``sib`` -- a :class:`SageInputBuilder` - - ``n`` -- a string; the value to be printed for this expression + - ``n`` -- string; the value to be printed for this expression EXAMPLES:: @@ -1790,7 +1790,7 @@ def __init__(self, sib, n): def __repr__(self): r""" - Returns a string representing this :class:`SIE_literal_stringrep` + Return a string representing this :class:`SIE_literal_stringrep` value. EXAMPLES:: @@ -1849,10 +1849,10 @@ def __init__(self, sib, func, args, kwargs): - ``func`` -- a :class:`SageInputExpression` representing a function - - ``args`` -- a list of instances of :class:`SageInputExpression` + - ``args`` -- list of instances of :class:`SageInputExpression` representing the positional arguments - - ``kwargs`` -- a dictionary mapping strings to instances of + - ``kwargs`` -- dictionary mapping strings to instances of :class:`SageInputExpression` representing the keyword arguments EXAMPLES:: @@ -1869,7 +1869,7 @@ def __init__(self, sib, func, args, kwargs): def __repr__(self): r""" - Returns a string representing this :class:`SIE_call` value. + Return a string representing this :class:`SIE_call` value. EXAMPLES:: @@ -1887,7 +1887,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this :class:`SIE_call`. + Return a list of the immediate subexpressions of this :class:`SIE_call`. EXAMPLES:: @@ -1976,7 +1976,7 @@ def __init__(self, sib, coll, key): def __repr__(self): r""" - Returns a string representing this :class:`SIE_subscript` value. + Return a string representing this :class:`SIE_subscript` value. EXAMPLES:: @@ -1995,7 +1995,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_subscript`. EXAMPLES:: @@ -2060,7 +2060,7 @@ def __init__(self, sib, obj, attr): - ``obj`` -- a :class:`SageInputExpression` representing an object - - ``attr`` -- a string; the attribute name + - ``attr`` -- string; the attribute name EXAMPLES:: @@ -2076,7 +2076,7 @@ def __init__(self, sib, obj, attr): def __repr__(self): r""" - Returns a string representing this :class:`SIE_getattr` value. + Return a string representing this :class:`SIE_getattr` value. EXAMPLES:: @@ -2091,7 +2091,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_subscript`. EXAMPLES:: @@ -2149,10 +2149,10 @@ def __init__(self, sib, values, is_list): - ``sib`` -- a :class:`SageInputBuilder` - - ``values`` -- a list of instances of :class:`SageInputExpression` + - ``values`` -- list of instances of :class:`SageInputExpression` representing the elements of this tuple - - ``is_list`` -- is True if this class represents a list, False for a + - ``is_list`` -- is ``True`` if this class represents a list, False for a tuple EXAMPLES:: @@ -2171,7 +2171,7 @@ def __init__(self, sib, values, is_list): def __repr__(self): r""" - Returns a string representing this :class:`SIE_tuple` value. + Return a string representing this :class:`SIE_tuple` value. EXAMPLES:: @@ -2189,7 +2189,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_tuple`. EXAMPLES:: @@ -2261,7 +2261,7 @@ def __init__(self, sib, entries): - ``sib`` -- a :class:`SageInputBuilder` - - ``entries`` -- a list of pairs of :class:`SageInputExpression` + - ``entries`` -- list of pairs of :class:`SageInputExpression` representing the entries of this dict EXAMPLES:: @@ -2279,7 +2279,7 @@ def __init__(self, sib, entries): def __repr__(self): r""" - Returns a string representing this :class:`SIE_dict` value. + Return a string representing this :class:`SIE_dict` value. EXAMPLES:: @@ -2295,7 +2295,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_dict`. EXAMPLES:: @@ -2351,7 +2351,7 @@ def __init__(self, sib, op, lhs, rhs): - ``sib`` -- a :class:`SageInputBuilder` - - ``op`` -- a string representing a binary operator, such as '*' or '%' + - ``op`` -- string representing a binary operator, such as '*' or '%' - ``lhs`` -- a :class:`SageInputExpression` @@ -2371,7 +2371,7 @@ def __init__(self, sib, op, lhs, rhs): def __repr__(self): r""" - Returns a string representing this :class:`SIE_binary` value. + Return a string representing this :class:`SIE_binary` value. EXAMPLES:: @@ -2385,7 +2385,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a tuple of the immediate subexpressions of this + Return a tuple of the immediate subexpressions of this :class:`SIE_binary`. EXAMPLES:: @@ -2501,7 +2501,7 @@ def __init__(self, sib, op, operand): - ``sib`` -- a :class:`SageInputBuilder` - - ``op`` -- a string representing a unary operator, such as '-' + - ``op`` -- string representing a unary operator, such as '-' - ``operand`` -- a :class:`SageInputExpression` @@ -2519,7 +2519,7 @@ def __init__(self, sib, op, operand): def __repr__(self): r""" - Returns a string representing this :class:`SIE_unary` value. + Return a string representing this :class:`SIE_unary` value. EXAMPLES:: @@ -2533,7 +2533,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_unary`. EXAMPLES:: @@ -2691,7 +2691,7 @@ def __init__(self, sib, constr, gen_names, gens_syntax=None): - ``constr`` -- a :class:`SageInputExpression` for constructing this parent ``normally`` - - ``gen_names`` -- a tuple of generator names + - ``gen_names`` -- tuple of generator names - ``gens_syntax`` -- an optional :class:`SageInputExpression` for constructing this parent using the \sage preparser generators syntax @@ -2717,7 +2717,7 @@ def __init__(self, sib, constr, gen_names, gens_syntax=None): def __repr__(self): r""" - Returns a string representing this :class:`SIE_gens_constructor` value. + Return a string representing this :class:`SIE_gens_constructor` value. EXAMPLES:: @@ -2734,7 +2734,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_gens_constructor`. EXAMPLES:: @@ -2908,7 +2908,7 @@ class SIE_gen(SageInputExpression): def __init__(self, sib, parent, name): r""" - Initializes an instance of :class:`SIE_gen`. + Initialize an instance of :class:`SIE_gen`. INPUT: @@ -2916,7 +2916,7 @@ def __init__(self, sib, parent, name): - ``parent`` -- a :class:`SIE_gens_constructor` - - ``name`` -- a string with the name of this generator + - ``name`` -- string with the name of this generator EXAMPLES:: @@ -2932,7 +2932,7 @@ def __init__(self, sib, parent, name): def __repr__(self): r""" - Returns a string representing this :class:`SIE_gen` value. + Return a string representing this :class:`SIE_gen` value. EXAMPLES:: @@ -3060,7 +3060,7 @@ class SIE_import_name(SageInputExpression): def __init__(self, sib, module, name, alt_name=None): r""" - Initializes an instance of :class:`SIE_import_name`. + Initialize an instance of :class:`SIE_import_name`. INPUT: @@ -3094,7 +3094,7 @@ def __init__(self, sib, module, name, alt_name=None): def __repr__(self): r""" - Returns a string representing this :class:`SIE_import_name` value. + Return a string representing this :class:`SIE_import_name` value. EXAMPLES:: @@ -3194,7 +3194,7 @@ class SIE_assign(SageInputExpression): def __init__(self, sib, lhs, rhs): r""" - Initializes an instance of :class:`SIE_assign`. + Initialize an instance of :class:`SIE_assign`. INPUT: @@ -3218,7 +3218,7 @@ def __init__(self, sib, lhs, rhs): def __repr__(self): r""" - Returns a string representing this :class:`SIE_assign` command. + Return a string representing this :class:`SIE_assign` command. EXAMPLES:: @@ -3232,7 +3232,7 @@ def __repr__(self): def _sie_referenced(self): r""" - Returns a list of the immediate subexpressions of this + Return a list of the immediate subexpressions of this :class:`SIE_assign`. EXAMPLES:: @@ -3313,7 +3313,7 @@ def format(self, e, prec): - ``e`` -- a :class:`SageInputExpression` - - ``prec`` -- an integer representing a precedence level + - ``prec`` -- integer representing a precedence level First, we check to see if ``e`` should be replaced by a variable. If so, we generate the command to assign the variable, and return @@ -3521,11 +3521,10 @@ def verify_si_answer(x, answer, preparse): - ``x`` -- an arbitrary Sage value - - ``answer`` -- a string, or a :class:`SageInputAnswer` + - ``answer`` -- string, or a :class:`SageInputAnswer` - ``preparse`` -- ``True``, ``False``, or ``None`` - EXAMPLES:: sage: from sage.misc.sage_input import verify_si_answer diff --git a/src/sage/misc/sage_ostools.pyx b/src/sage/misc/sage_ostools.pyx index 31118107f20..b679af7c26f 100644 --- a/src/sage/misc/sage_ostools.pyx +++ b/src/sage/misc/sage_ostools.pyx @@ -16,13 +16,13 @@ def have_program(program, path=None): INPUT: - - ``program`` -- a string, the name of the program to check. + - ``program`` -- string, the name of the program to check - - ``path`` -- string or None. Paths to search for ``program``, + - ``path`` -- string or ``None``. Paths to search for ``program``, separated by ``os.pathsep``. If ``None``, use the :envvar:`PATH` environment variable. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -85,7 +85,7 @@ cdef file_and_fd(x, int* fd): If ``x`` is a file, return ``x`` and set ``*fd`` to its file descriptor. If ``x`` is an integer, return ``None`` and set ``*fd`` to ``x``. Otherwise, set ``*fd = -1`` and raise a - ``TypeError``. + :exc:`TypeError`. """ fd[0] = -1 try: @@ -116,7 +116,7 @@ cdef class redirection: - ``dest`` -- where the source file should be redirected to - - ``close`` -- (boolean, default: ``True``) whether to close the + - ``close`` -- boolean (default: ``True``); whether to close the destination file upon exiting the context. This is only supported if ``dest`` is a Python file. diff --git a/src/sage/misc/sage_timeit.py b/src/sage/misc/sage_timeit.py index e90eb1adb23..75828816c24 100644 --- a/src/sage/misc/sage_timeit.py +++ b/src/sage/misc/sage_timeit.py @@ -52,11 +52,10 @@ class SageTimeitResult: sage: SageTimeitResult(stats) # needs sage.symbolic 7 loops, best of 13: 3.1416 ns per loop - If the third argument is not a Python integer, a ``TypeError`` is raised:: + If the third argument is not a Python integer, a :exc:`TypeError` is raised:: sage: SageTimeitResult( (1, 2, 3, 4, 's') ) ) failed: TypeError: * wants int> - """ def __init__(self, stats, series=None): r""" @@ -104,25 +103,23 @@ def sage_timeit(stmt, globals_dict=None, preparse=None, number=0, repeat=3, prec INPUT: - - ``stmt`` -- a text string. + - ``stmt`` -- a text string - - ``globals_dict`` -- a dictionary or ``None`` (default). Evaluate + - ``globals_dict`` -- dictionary or ``None`` (default). Evaluate ``stmt`` in the context of the globals dictionary. If not set, the current ``globals()`` dictionary is used. - ``preparse`` -- (default: use globals preparser default) if - ``True`` preparse ``stmt`` using the Sage preparser. + ``True`` preparse ``stmt`` using the Sage preparser - - ``number`` -- integer, (default: 0), number of loops. + - ``number`` -- integer; (default: 0); number of loops - - ``repeat`` -- integer, (default: 3), number of - repetition. + - ``repeat`` -- integer; (default: 3); number of repetition - - ``precision`` -- integer, (default: 3), precision of - output time. + - ``precision`` -- integer; (default: 3); precision of output time - - ``seconds`` -- boolean (default: ``False``). Whether to just - return time in seconds. + - ``seconds`` -- boolean (default: ``False``); whether to just + return time in seconds OUTPUT: @@ -226,8 +223,8 @@ def sage_timeit(stmt, globals_dict=None, preparse=None, number=0, repeat=3, prec # to the shell namespace? src = timeit_.template.format(stmt=timeit_.reindent(stmt, 8), - setup="pass", init='') - code = compile(src, "", "exec") + setup='pass', init='') + code = compile(src, '', 'exec') ns = {} if not globals_dict: globals_dict = globals() diff --git a/src/sage/misc/sage_timeit_class.pyx b/src/sage/misc/sage_timeit_class.pyx index f568886574f..2438484cd10 100644 --- a/src/sage/misc/sage_timeit_class.pyx +++ b/src/sage/misc/sage_timeit_class.pyx @@ -51,18 +51,18 @@ class SageTimeit: INPUT: - - ``code`` -- string of code to evaluate; may contain newlines. + - ``code`` -- string of code to evaluate; may contain newlines - - ``globs`` -- global variables; if not given, uses module scope - globals. + - ``globs`` -- global variables; if not given, uses module scope + globals - - ``locals`` -- ignored completely. + - ``locals`` -- ignored completely - ``kwds`` -- passed onto sage_timeit. Common options are ``preparse``, ``number``, ``repeat``, ``precision``. See :func:`~sage.misc.sage_timeit.sage_timeit` for details. - OUTPUT: string -- timing information as a string + OUTPUT: string; timing information EXAMPLES:: @@ -84,15 +84,15 @@ class SageTimeit: """ INPUT: - - ``code`` -- a string. A line or block of code, which may - contain newlines. + - ``code`` -- string; a line or block of code, which may + contain newlines - - ``globals`` -- optional global variables; if not given the + - ``globals`` -- (optional) global variables; if not given the globals of the calling module are used (e.g., if using this from the command line, the globals of the command line are used). - - ``preparse`` -- Boolean or ``None`` (default). Whether or + - ``preparse`` -- boolean or ``None`` (default). Whether or not to preparse the input code using the Sage preparser. If not specified, do the same thing as whatever was set by the preparser command. diff --git a/src/sage/misc/sage_unittest.py b/src/sage/misc/sage_unittest.py index f0e281f9b68..47fe452d904 100644 --- a/src/sage/misc/sage_unittest.py +++ b/src/sage/misc/sage_unittest.py @@ -110,40 +110,40 @@ class TestSuite: running ._test_new() . . . pass running ._test_pickling() . . . pass - TODO: - - - Allow for customized behavior in case of failing assertion - (warning, error, statistic accounting). - This involves reimplementing the methods fail / failIf / ... - of unittest.TestCase in InstanceTester - - - Don't catch the exceptions if ``TestSuite(..).run()`` is called - under the debugger, or with ``%pdb`` on (how to detect this? see - ``get_ipython()``, ``IPython.Magic.shell.call_pdb``, ...) - In the mean time, see the ``catch=False`` option. - - - Run the tests according to the inheritance order, from most - generic to most specific, rather than alphabetically. Then, the - first failure will be the most relevant, the others being - usually consequences. - - - Improve integration with doctests (statistics on failing/passing tests) - - - Add proper support for nested testsuites. - - - Integration with unittest: - Make TestSuite inherit from unittest.TestSuite? - Make ``.run(...)`` accept a result object - - - Add some standard option ``proof = True``, asking for the - test method to choose appropriately the elements so as to - prove the desired property. The test method may assume that - a parent implements properly all the super categories. For - example, the ``_test_commutative`` method of the category - ``CommutativeSemigroups()`` may just check that the - provided generators commute, implicitly assuming that - generators indeed generate the semigroup (as required by - ``Semigroups()``). + .. TODO:: + + - Allow for customized behavior in case of failing assertion + (warning, error, statistic accounting). + This involves reimplementing the methods fail / failIf / ... + of unittest.TestCase in InstanceTester + + - Don't catch the exceptions if ``TestSuite(..).run()`` is called + under the debugger, or with ``%pdb`` on (how to detect this? see + ``get_ipython()``, ``IPython.Magic.shell.call_pdb``, ...) + In the mean time, see the ``catch=False`` option. + + - Run the tests according to the inheritance order, from most + generic to most specific, rather than alphabetically. Then, the + first failure will be the most relevant, the others being + usually consequences. + + - Improve integration with doctests (statistics on failing/passing tests) + + - Add proper support for nested testsuites. + + - Integration with unittest: + Make TestSuite inherit from unittest.TestSuite? + Make ``.run(...)`` accept a result object + + - Add some standard option ``proof = True``, asking for the + test method to choose appropriately the elements so as to + prove the desired property. The test method may assume that + a parent implements properly all the super categories. For + example, the ``_test_commutative`` method of the category + ``CommutativeSemigroups()`` may just check that the + provided generators commute, implicitly assuming that + generators indeed generate the semigroup (as required by + ``Semigroups()``). """ def __init__(self, instance): @@ -174,10 +174,10 @@ def run(self, category=None, skip=[], catch=True, raise_on_failure=False, INPUT: - - ``category`` -- a category; reserved for future use - - ``skip`` -- a string or list (or iterable) of strings - - ``raise_on_failure`` -- a boolean (default: ``False``) - - ``catch`` -- a boolean (default: ``True``) + - ``category`` -- a category; reserved for future use + - ``skip`` -- string or list (or iterable) of strings + - ``raise_on_failure`` -- boolean (default: ``False``) + - ``catch`` -- boolean (default: ``True``) All other options are passed down to the individual tests. @@ -197,7 +197,7 @@ def run(self, category=None, skip=[], catch=True, raise_on_failure=False, Some tests may be skipped using the ``skip`` option:: - sage: TestSuite(1).run(verbose = True, skip ="_test_pickling") + sage: TestSuite(1).run(verbose = True, skip ='_test_pickling') running ._test_category() . . . pass running ._test_eq() . . . pass running ._test_new() . . . pass @@ -388,7 +388,7 @@ class InstanceTester(unittest.TestCase): # all that much anyways) longMessage = False - def __init__(self, instance, elements=None, verbose=False, prefix="", + def __init__(self, instance, elements=None, verbose=False, prefix='', max_runs=4096, max_samples=None, **options): """ A gadget attached to an instance providing it with testing utilities. @@ -428,7 +428,7 @@ def runTest(self): def info(self, message, newline=True): """ - Display user information + Display user information. EXAMPLES:: @@ -460,7 +460,6 @@ def __repr__(self): sage: from sage.misc.sage_unittest import InstanceTester sage: InstanceTester(ZZ, verbose = True) Testing utilities for Integer Ring - """ return "Testing utilities for %s" % self._instance @@ -473,13 +472,13 @@ def some_elements(self, S=None, repeat=None): INPUT: - - ``S`` -- a set of elements to select from. By default this + - ``S`` -- set of elements to select from; by default this will use the elements passed to this tester at creation time, or the result of :meth:`.some_elements` if no elements - were specified. + were specified - - ``repeat`` -- integer (default: None). If given, instead returns - a list of tuples of length ``repeat`` from ``S``. + - ``repeat`` -- integer (default: ``None``); if given, instead returns + a list of tuples of length ``repeat`` from ``S`` OUTPUT: @@ -599,7 +598,7 @@ def __init__(self, instance): def _test_pickling(self, **options): """ - Checks that the instance in self can be pickled and unpickled properly. + Check that the instance in ``self`` can be pickled and unpickled properly. EXAMPLES:: diff --git a/src/sage/misc/sagedoc.py b/src/sage/misc/sagedoc.py index 595cb8faf9f..827fd77e811 100644 --- a/src/sage/misc/sagedoc.py +++ b/src/sage/misc/sagedoc.py @@ -127,13 +127,13 @@ def _rmcmd(s, cmd, left='', right=''): INPUT: - - ``s`` -- (string) string from which to remove the command + - ``s`` -- string; string from which to remove the command - - ``cmd`` -- (string) command to be removed. This should be a + - ``cmd`` -- string; command to be removed. This should be a command which takes a single argument, like 'emph' or 'url'; the command is removed, but its argument is not. - - ``left``, ``right`` -- (string, default: '') add these + - ``left``, ``right`` -- string (default: ``''``); add these strings at the left and right ends of the command. See the examples. @@ -200,13 +200,11 @@ def detex(s, embedded=False): - ``s`` -- string - ``embedded`` -- boolean (default: ``False``) - If ``embedded`` is False, then do the replacements in both - ``math_substitutes`` and ``nonmath_substitutes``. If True, then + If ``embedded`` is ``False``, then do the replacements in both + ``math_substitutes`` and ``nonmath_substitutes``. If ``True``, then only do ``nonmath_substitutes``. - OUTPUT: - - string + OUTPUT: string EXAMPLES:: @@ -264,7 +262,7 @@ def skip_TESTS_block(docstring): INPUT: - - ``docstring``, a string + - ``docstring`` -- string A "TESTS" block is a block starting "TESTS:" (or the same with two colons), on a line on its own, and ending either @@ -699,7 +697,7 @@ def format(s, embedded=False): We check that the todo Sphinx extension is correctly activated:: sage: sage.misc.sagedoc.format(sage.combinat.ranker.on_fly.__doc__) # needs sphinx - " Returns ... Todo: add tests as in combinat::rankers\n" + " Return ... Todo: add tests as in combinat::rankers\n" In the following use case, the ``nodetex`` directive would have been ignored prior to :issue:`11815`:: @@ -886,10 +884,10 @@ def _search_src_or_doc(what, string, extra1='', extra2='', extra3='', INPUT: - - ``what``: either ``'src'`` or ``'doc'``, according to whether you - are searching the documentation or source code. + - ``what`` -- either ``'src'`` or ``'doc'``, according to whether you + are searching the documentation or source code - the rest of the input is the same as :func:`search_src`, - :func:`search_doc`, and :func:`search_def`. + :func:`search_doc`, and :func:`search_def` OUTPUT: @@ -1053,45 +1051,47 @@ def search_src(string, extra1='', extra2='', extra3='', extra4='', INPUT: - - ``string`` -- a string to find in the Sage source code. + - ``string`` -- string to find in the Sage source code - ``extra1``, ..., ``extra5`` -- additional strings to require when - searching. Lines must match all of these, as well as ``string``. + searching. Lines must match all of these, as well as ``string`` - - ``whole_word`` (default: ``False``) -- if True, search for + - ``whole_word`` -- (default: ``False``) if ``True``, search for ``string`` and ``extra1`` (etc.) as whole words only. This assumes that each of these arguments is a single word, not a regular expression, and it might have unexpected results if used with regular expressions. - - ``ignore_case`` (default: ``True``) -- if False, perform a + - ``ignore_case`` -- boolean (default: ``True``); if ``False``, perform a case-sensitive search - - ``multiline`` (default: ``False``) -- if True, search more + - ``multiline`` -- (default: ``False``) if ``True``, search more than one line at a time. In this case, print any matching file names, but don't print line numbers. - - ``interact`` (default: ``True``) -- if ``False``, return + - ``interact`` -- boolean (default: ``True``); if ``False``, return a string with all the matches. Otherwise, this function returns ``None``, and the results are displayed appropriately, according to whether you are using the notebook or the command-line interface. You should not ordinarily need to use this. - - ``path_re`` (default: '') -- regular expression which - the filename (including the path) must match. + - ``path_re`` -- (default: ``''``) regular expression which + the filename (including the path) must match - - ``module`` (default: 'sage') -- the module in which to + - ``module`` -- (default: ``'sage'``) the module in which to search. The default is 'sage', the entire Sage library. If ``module`` doesn't start with "sage", then the links in the notebook output may not function. - OUTPUT: If ``interact`` is False, then return a string with all of + OUTPUT: + + If ``interact`` is ``False``, then return a string with all of the matches, separated by newlines. On the other hand, if - ``interact`` is True (the default), there is no output. Instead: + ``interact`` is ``True`` (the default), there is no output. Instead: at the command line, the search results are printed on the screen in the form ``filename:line_number:line of text``, showing the filename in which each match occurs, the line number where it - occurs, and the actual matching line. (If ``multiline`` is True, + occurs, and the actual matching line. (If ``multiline`` is ``True``, then only the filename is printed for each match.) The file paths in the output are relative to ``$SAGE_SRC``. In the notebook, each match produces a link to the actual file in which @@ -1100,9 +1100,9 @@ def search_src(string, extra1='', extra2='', extra3='', extra4='', The ``string`` and ``extraN`` arguments are treated as regular expressions, as is ``path_re``, and errors will be raised if they are invalid. The matches will be case-insensitive unless - ``ignore_case`` is False. + ``ignore_case`` is ``False``. - .. note:: + .. NOTE:: The ``extraN`` parameters are present only because ``search_src(string, *extras, interact=False)`` @@ -1218,7 +1218,6 @@ def search_src(string, extra1='', extra2='', extra3='', extra4='', matrix/matrix0.pyx:607: Get the 2 x 3 submatrix of M starting at row index and column index matrix/matrix0.pyx:924: Set the 2 x 2 submatrix of M, starting at row index and column matrix/matrix0.pyx:933: Set the 2 x 3 submatrix of M starting at row index and column - """ return _search_src_or_doc('src', string, extra1=extra1, extra2=extra2, extra3=extra3, extra4=extra4, extra5=extra5, @@ -1235,7 +1234,7 @@ def search_doc(string, extra1='', extra2='', extra3='', extra4='', INPUT: same as for :func:`search_src`. - OUTPUT: same as for :func:`search_src`. + OUTPUT: same as for :func:`search_src` EXAMPLES: @@ -1276,9 +1275,9 @@ def search_def(name, extra1='', extra2='', extra3='', extra4='', INPUT: same as for :func:`search_src`. - OUTPUT: same as for :func:`search_src`. + OUTPUT: same as for :func:`search_src` - .. note:: + .. NOTE:: The regular expression used by this function only finds function definitions that are preceded by spaces, so if you use tabs on a @@ -1325,11 +1324,11 @@ def format_search_as_html(what, results, search): INPUT: - - ``what`` -- (string) what was searched (source code or + - ``what`` -- string; what was searched (source code or documentation) - - ``results`` -- (string or list) the results of the search as a string or list of + - ``results`` -- string or list; the results of the search as a string or list of search results - - ``search`` -- (string or list) what was being searched for, either as a + - ``search`` -- string or list; what was being searched for, either as a string which is taken verbatim, or a list of multiple search terms if there were more than one @@ -1410,8 +1409,8 @@ def my_getsource(obj, oname=''): - ``obj`` -- a Sage object, function, etc. - - ``oname`` -- str (optional). A name under which the object is - known. Currently ignored by Sage. + - ``oname`` -- string (optional); a name under which the object is + known. Currently ignored by Sage OUTPUT: @@ -1451,7 +1450,7 @@ class _sage_doc: "browse_sage_doc(identity_matrix, 'html'). ``output`` can be either 'html' or 'rst': the form of the output. ``view`` is only relevant if ``output`` is ``html``; in this case, if - ``view`` is True (its default value), then open up the + ``view`` is ``True`` (its default value), then open up the documentation in a web browser. Otherwise, just output the documentation as a string. @@ -1621,11 +1620,11 @@ def _open(self, name, testing=False): INPUT: - - ``name`` -- string, name of the documentation + - ``name`` -- string; name of the documentation - - ``testing`` -- boolean (default: ``False``): if True, - then just return the URL and path-name for this document; - don't open the web browser. + - ``testing`` -- boolean (default: ``False``); if ``True``, + then just return the URL and path-name for this document + (don't open the web browser) EXAMPLES:: diff --git a/src/sage/misc/sageinspect.py b/src/sage/misc/sageinspect.py index 4582d0bfb6d..87702cd481a 100644 --- a/src/sage/misc/sageinspect.py +++ b/src/sage/misc/sageinspect.py @@ -170,7 +170,7 @@ def is_function_or_cython_function(obj): def isclassinstance(obj): r""" - Check if argument is instance of non built-in class + Check if argument is instance of non built-in class. INPUT: @@ -223,7 +223,9 @@ def _extract_embedded_position(docstring): If docstring has a Cython embedded position, return a tuple (original_docstring, filename, line). If not, return None. - INPUT: ``docstring`` (string) + INPUT: + + - ``docstring`` -- string EXAMPLES:: @@ -255,7 +257,6 @@ def _extract_embedded_position(docstring): sage: with open(_extract_embedded_position(func_doc)[1]) as f: # needs sage.misc.cython ....: print(f.read()) cpdef test_funct(x,y): return - """ try: res = __embedded_position_re.search(docstring) @@ -301,7 +302,9 @@ def _extract_embedded_signature(docstring, name): See :issue:`17814`. - INPUT: ``docstring`` (string) + INPUT: + + - ``docstring`` -- string EXAMPLES:: @@ -460,7 +463,6 @@ class SageArgSpecVisitor(ast.NodeVisitor): 'jc' sage: visitor.visit(v.value) ['veni', 'vidi', 'vici'] - """ def visit_Name(self, node): """ @@ -481,7 +483,6 @@ def visit_Name(self, node): ['foo', 'bar'] sage: [type(vis(n)) for n in ['foo', 'bar']] [, ] - """ return node.id @@ -507,7 +508,6 @@ def visit_NameConstant(self, node): [True, False, None] sage: [type(vis(n)) for n in ['True', 'False', 'None']] [, , ] - """ return node.value @@ -535,7 +535,6 @@ def visit_arg(self, node): sage: args = ast.parse(s).body[0].args.args sage: [visitor.visit_arg(n) for n in args] ['a', 'b', 'c', 'd'] - """ return node.arg @@ -581,7 +580,6 @@ def visit_Str(self, node): sage: vis = lambda x: visitor.visit_Str(ast.parse(x).body[0].value) sage: [vis(s) for s in ['"abstract"', "'syntax'", r'''r"tr\ee"''']] ['abstract', 'syntax', 'tr\\ee'] - """ return node.value @@ -602,7 +600,6 @@ def visit_List(self, node): sage: vis = lambda x: visitor.visit_List(ast.parse(x).body[0].value) sage: [vis(l) for l in ['[]', "['s', 't', 'u']", '[[e], [], [pi]]']] [[], ['s', 't', 'u'], [['e'], [], ['pi']]] - """ return [self.visit(n) for n in node.elts] @@ -623,7 +620,6 @@ def visit_Tuple(self, node): sage: vis = lambda x: visitor.visit_Tuple(ast.parse(x).body[0].value) sage: [vis(t) for t in ['()', '(x,y)', '("Au", "Al", "Cu")']] [(), ('x', 'y'), ('Au', 'Al', 'Cu')] - """ return tuple(self.visit(n) for n in node.elts) @@ -645,7 +641,6 @@ def visit_Dict(self, node): sage: v = [vis(d) for d in ['{}', "{1:one, 'two':2, other:bother}"]] sage: [sorted(d.items(), key=lambda x: str(x[0])) for d in v] [[], [(1, 'one'), ('other', 'bother'), ('two', 2)]] - """ d = {} for k, v in zip(node.keys, node.values): @@ -669,7 +664,6 @@ def visit_BoolOp(self, node): sage: vis = lambda x: visitor.visit(ast.parse(x).body[0].value) sage: [vis(d) for d in ['True and 1', 'False or 3 or None', '3 and 4']] #indirect doctest [1, 3, 4] - """ op = node.op.__class__.__name__ L = list(node.values) @@ -702,7 +696,6 @@ def visit_Compare(self, node): sage: vis = lambda x: visitor.visit_Compare(ast.parse(x).body[0].value) sage: [vis(d) for d in ['1<2==2!=3', '1==1>2', '1<2>1', '1<3<2<4']] [True, False, True, False] - """ left = self.visit(node.left) ops = list(node.ops) @@ -748,7 +741,6 @@ def visit_BinOp(self, node): sage: vis = lambda x: visitor.visit(ast.parse(x).body[0].value) sage: [vis(d) for d in ['(3+(2*4))', '7|8', '5^3', '7/3', '7//3', '3<<4']] #indirect doctest [11, 15, 6, 2.3333333333333335, 2, 48] - """ op = node.op.__class__.__name__ if op == 'Add': @@ -813,7 +805,6 @@ def visit_UnaryOp(self, node): sage: vis = lambda x: visitor.visit_UnaryOp(ast.parse(x).body[0].value) sage: [vis(d) for d in ['+(3*2)', '-(3*2)']] [6, -6] - """ op = node.op.__class__.__name__ if op == 'Not': @@ -830,7 +821,7 @@ def _grep_first_pair_of_parentheses(s): INPUT: - - ``s`` -- a string + - ``s`` -- string OUTPUT: @@ -840,7 +831,7 @@ def _grep_first_pair_of_parentheses(s): Parentheses between single or double quotation marks do not count. If no matching pair of parentheses can be found, a - ``SyntaxError`` is raised. + :exc:`SyntaxError` is raised. EXAMPLES:: @@ -853,7 +844,6 @@ def _grep_first_pair_of_parentheses(s): Traceback (most recent call last): ... SyntaxError: The given string does not contain balanced parentheses - """ out = [] single_quote = False @@ -886,7 +876,7 @@ def _split_syntactical_unit(s): INPUT: - - ``s`` -- a string + - ``s`` -- string OUTPUT: @@ -937,7 +927,6 @@ def _split_syntactical_unit(s): sage: _split_syntactical_unit('()): pass') ('()', '): pass') - """ s = s.strip() if not s: @@ -1031,8 +1020,8 @@ def _sage_getargspec_from_ast(source): INPUT: - - ``source`` -- a string; the function's (or method's) source code - definition. The function's body is ignored. + - ``source`` -- string; the function's (or method's) source code + definition. The function's body is ignored. OUTPUT: an instance of :obj:`inspect.ArgSpec`, i.e., a named tuple @@ -1051,7 +1040,6 @@ def _sage_getargspec_from_ast(source): True sage: set(from_ast(sms.sage_getsource(x)) == inspect.getfullargspec(x) for x in [factor, identity_matrix, Graph.__init__]) # needs sage.graphs sage.modules {True} - """ ast_args = ast.parse(source.lstrip()).body[0].args @@ -1075,7 +1063,7 @@ def _sage_getargspec_cython(source): INPUT: - - ``source`` -- a string; the function's (or method's) source code + - ``source`` -- string; the function's (or method's) source code definition. The function's body is ignored. The definition may contain type definitions for the function arguments. @@ -1148,7 +1136,6 @@ def _sage_getargspec_cython(source): FullArgSpec(args=['x', 'z'], varargs=None, varkw=None, defaults=('a string', {(1, 2, 3): True}), kwonlyargs=[], kwonlydefaults=None, annotations={}) - """ defpos = source.find('def ') assert defpos > -1, "The given source does not contain 'def'" @@ -1316,7 +1303,6 @@ def sage_getfile(obj): sage: sage_getfile(range) '' - """ # We try to extract from docstrings, but not using Python's inspect # because _sage_getdoc_unformatted is more robust. @@ -1367,7 +1353,6 @@ def sage_getfile_relative(obj): 'sage/symbolic/expression.pyx' sage: sage_getfile_relative(range) '' - """ filename = sage_getfile(obj) if not filename: @@ -1593,7 +1578,6 @@ def foo(x, a='\')"', b={not (2+1==3):'bar'}): return sage: shell.run_cell('f = Foo()') sage: shell.run_cell('f??') ...the source code string... - """ from sage.misc.lazy_attribute import lazy_attribute from sage.misc.abstract_method import AbstractMethod @@ -1815,9 +1799,7 @@ def sage_getdef(obj, obj_name=''): INPUT: - ``obj`` -- function - - ``obj_name`` -- string (default: '') - - ``obj_name`` is prepended to the output. + - ``obj_name`` -- string (default: ``''``); prepended to the output EXAMPLES:: @@ -1861,7 +1843,7 @@ def _sage_getdoc_unformatted(obj): INPUT: - - ``obj`` -- a function, module, etc.: something with a docstring. + - ``obj`` -- a function, module, etc.: something with a docstring EXAMPLES:: @@ -1898,7 +1880,6 @@ def _sage_getdoc_unformatted(obj): Exception: no doc here sage: _sage_getdoc_unformatted(obj) '' - """ if obj is None: return '' @@ -1931,7 +1912,7 @@ def sage_getdoc_original(obj): INPUT: - - ``obj`` -- a function, module, etc.: something with a docstring. + - ``obj`` -- a function, module, etc.: something with a docstring EXAMPLES:: @@ -1982,7 +1963,6 @@ def sage_getdoc_original(obj): sage: sage_getdoc_original(sage.plot.colors.aliceblue) == sage_getdoc_original(sage.plot.colors.Color) # needs sage.plot True - """ # typ is the type corresponding to obj, which is obj itself if # that was a type or old-style class @@ -2018,7 +1998,7 @@ def sage_getdoc(obj, obj_name='', embedded=False): INPUT: - - ``obj`` -- a function, module, etc.: something with a docstring. + - ``obj`` -- a function, module, etc.: something with a docstring EXAMPLES:: @@ -2035,7 +2015,6 @@ def sage_getdoc(obj, obj_name='', embedded=False): 'original documentation\n' sage: sage_getdoc(f1) 'specialised documentation\n' - """ import sage.misc.sagedoc if obj is None: @@ -2258,7 +2237,7 @@ def sage_getsourcelines(obj): sage: # needs sage.combinat sage: cachedfib = cached_function(fibonacci) sage: sage_getsourcelines(cachedfib)[0][0] - 'def fibonacci(n, algorithm="pari") -> Integer:\n' + "def fibonacci(n, algorithm='pari') -> Integer:\n" sage: sage_getsourcelines(type(cachedfib))[0][0] 'cdef class CachedFunction():\n' @@ -2343,7 +2322,6 @@ class Element: ' Ideal_generic):\n', ' def __init__(self, ring, gens, coerce=True):\n', ...) - """ # First try the method _sage_src_lines_(), which is meant to give # the source lines of an object (not of its type!). @@ -2456,16 +2434,16 @@ def sage_getvariablename(self, omit_underscore_names=True): INPUT: - - ``self`` -- any object. + - ``self`` -- any object - - ``omit_underscore_names`` -- boolean, default ``True``. + - ``omit_underscore_names`` -- boolean (default: ``True``) OUTPUT: If the user has assigned an object ``obj`` to a variable name, then return that variable name. If several variables point to ``obj``, return a sorted list of those names. If - ``omit_underscore_names`` is True (the default) then omit names + ``omit_underscore_names`` is ``True`` (the default) then omit names starting with an underscore "_". EXAMPLES:: diff --git a/src/sage/misc/search.pyx b/src/sage/misc/search.pyx index a9e7149113e..838e77268f5 100644 --- a/src/sage/misc/search.pyx +++ b/src/sage/misc/search.pyx @@ -33,13 +33,11 @@ cpdef search(object v, object x): INPUT: - - v -- a list, which is assumed sorted + - ``v`` -- list; which is assumed sorted - - x -- Python object + - ``x`` -- Python object - OUTPUT: - - bool, int + OUTPUT: boolean, integer This is implemented using the built-in ``bisect`` module. diff --git a/src/sage/misc/session.pyx b/src/sage/misc/session.pyx index 53b732309da..5012c5689d4 100644 --- a/src/sage/misc/session.pyx +++ b/src/sage/misc/session.pyx @@ -89,8 +89,8 @@ def init(state=None): INPUT: - - ``state`` -- a dictionary or ``None``; if ``None`` the :func:`locals()` - of the caller is used. + - ``state`` -- dictionary or ``None``; if ``None`` the :func:`locals()` + of the caller is used EXAMPLES:: @@ -124,12 +124,10 @@ def _is_new_var(x, v, hidden): - ``v`` -- object - - ``hidden`` -- bool; if ``True``, always return ``False`` on variables - that start with ``_``) + - ``hidden`` -- boolean; if ``True``, always return ``False`` on variables + that start with ``_`` - OUTPUT: - - A bool + OUTPUT: boolean EXAMPLES: @@ -173,18 +171,16 @@ def _is_new_var(x, v, hidden): def show_identifiers(hidden=False): r""" - Returns a list of all variable names that have been defined during + Return a list of all variable names that have been defined during this session. By default, this returns only those identifiers that don't start with an underscore. INPUT: - - ``hidden`` -- bool (Default: ``False``); If ``True``, also return - identifiers that start with an underscore. - - OUTPUT: + - ``hidden`` -- boolean (default: ``False``); if ``True``, also return + identifiers that start with an underscore - A list of variable names + OUTPUT: list of variable names EXAMPLES: @@ -260,15 +256,13 @@ def save_session(name='sage_session', verbose=False): INPUT: - - ``name`` -- string (default: 'sage_session') name of ``sobj`` - to save the session to. - - - ``verbose`` -- bool (default: ``False``) if ``True``, print - info about why certain variables can't be saved. + - ``name`` -- string (default: ``'sage_session'``); name of ``sobj`` + to save the session to - OUTPUT: + - ``verbose`` -- boolean (default: ``False``); if ``True``, print + info about why certain variables can't be saved - - Creates a file and returns silently. + OUTPUT: creates a file and returns silently EXAMPLES: diff --git a/src/sage/misc/sphinxify.py b/src/sage/misc/sphinxify.py index 66a42476669..3bd0b12b367 100644 --- a/src/sage/misc/sphinxify.py +++ b/src/sage/misc/sphinxify.py @@ -32,19 +32,18 @@ def sphinxify(docstring, format='html'): r""" - Runs Sphinx on a ``docstring``, and outputs the processed - documentation. + Run Sphinx on a ``docstring``, and output the processed documentation. INPUT: - ``docstring`` -- string; a ReST-formatted docstring - - ``format`` -- string (default: 'html'); either 'html' or - 'text' + - ``format`` -- string (default: ``'html'``); either ``'html'`` or + ``'text'`` OUTPUT: - - string -- Sphinx-processed documentation, in either HTML or + - ``string`` -- Sphinx-processed documentation, in either HTML or plain text format, depending on the value of ``format`` EXAMPLES:: diff --git a/src/sage/misc/stopgap.pyx b/src/sage/misc/stopgap.pyx index 0b3b6cb6c1e..e6f626ae9b4 100644 --- a/src/sage/misc/stopgap.pyx +++ b/src/sage/misc/stopgap.pyx @@ -25,7 +25,7 @@ def set_state(bint mode): INPUT: - - ``mode`` -- (bool); if True, enable stopgaps; otherwise, disable. + - ``mode`` -- boolean; if ``True``, enable stopgaps. Otherwise, disable. EXAMPLES:: @@ -63,9 +63,10 @@ def stopgap(message, int issue_no): INPUT: - - ``message`` -- an explanation of how an incorrect answer might be produced. + - ``message`` -- an explanation of how an incorrect answer might be produced - - ``issue_no`` -- an integer, giving the number of the Github issue tracking the underlying issue. + - ``issue_no`` -- integer; giving the number of the Github issue tracking + the underlying issue EXAMPLES:: diff --git a/src/sage/misc/superseded.py b/src/sage/misc/superseded.py index 442817e830b..a78e7eb37e7 100644 --- a/src/sage/misc/superseded.py +++ b/src/sage/misc/superseded.py @@ -35,11 +35,11 @@ def _check_issue_number(issue_number): INPUT: - - ``issue_number`` -- anything. + - ``issue_number`` -- anything OUTPUT: - This function returns nothing. A :class:`ValueError` or :class:`TypeError` + This function returns nothing. A :exc:`ValueError` or :exc:`TypeError` is raised if the argument cannot be a valid issue number. EXAMPLES:: @@ -74,14 +74,14 @@ def deprecation(issue_number, message, stacklevel=4): INPUT: - - ``issue_number`` -- integer. The github issue number where the - deprecation is introduced. + - ``issue_number`` -- integer; the github issue number where the + deprecation is introduced - - ``message`` -- string. An explanation why things are deprecated - and by what it should be replaced. + - ``message`` -- string; an explanation why things are deprecated + and by what it should be replaced - - ``stack_level`` -- (default: ``4``) an integer. This is passed on to - :func:`warnings.warn`. + - ``stack_level`` -- integer (default: `4`); this is passed on to + :func:`warnings.warn` EXAMPLES:: @@ -101,7 +101,7 @@ def deprecation(issue_number, message, stacklevel=4): def deprecation_cython(issue_number, message, stacklevel=3): r""" - Issue a deprecation warning -- for use in cython functions + Issue a deprecation warning -- for use in cython functions. TESTS: @@ -144,16 +144,16 @@ def warning(issue_number, message, warning_class=Warning, stacklevel=3): INPUT: - - ``issue_number`` -- integer. The github issue number where the - deprecation is introduced. + - ``issue_number`` -- integer; the github issue number where the + deprecation is introduced - - ``message`` -- string. An explanation what is going on. + - ``message`` -- string; an explanation what is going on - ``warning_class`` -- (default: ``Warning``) a class inherited - from a Python :class:`~exceptions.Warning`. + from a Python :class:`~exceptions.Warning` - - ``stack_level`` -- (default: ``3``) an integer. This is passed on to - :func:`warnings.warn`. + - ``stack_level`` -- integer (default: `3`); this is passed on to + :func:`warnings.warn` EXAMPLES:: @@ -187,13 +187,13 @@ def experimental_warning(issue_number, message, stacklevel=4): INPUT: - - ``issue_number`` -- an integer. The github issue number where the - experimental functionality was introduced. + - ``issue_number`` -- integer; the github issue number where the + experimental functionality was introduced - - ``message`` -- a string. An explanation what is going on. + - ``message`` -- string; an explanation what is going on - - ``stack_level`` -- (default: ``4``) an integer. This is passed on to - :func:`warnings.warn`. + - ``stack_level`` -- integer (default: `4`); this is passed on to + :func:`warnings.warn` EXAMPLES:: @@ -223,11 +223,11 @@ def __init__(self, issue_number, stacklevel=4): INPUT: - - ``issue_number`` -- an integer. The github issue number where this - code was introduced. + - ``issue_number`` -- integer; the github issue number where this + code was introduced - - ``stack_level`` -- (default: ``4``) an integer. This is passed on to - :func:`warnings.warn`. + - ``stack_level`` -- integer (default: `4`); this is passed on to + :func:`warnings.warn` EXAMPLES:: @@ -284,11 +284,9 @@ def __call__(self, func): INPUT: - - ``func`` -- the function to decorate. + - ``func`` -- the function to decorate - OUTPUT: - - The wrapper to this function. + OUTPUT: the wrapper to this function TESTS:: @@ -489,7 +487,6 @@ def __get__(self, inst, cls=None): 3 sage: a1.f(a2.f(0)) 3 - """ if inst is None: return self # Unbound method lookup on class @@ -511,8 +508,8 @@ def deprecated_function_alias(issue_number, func): INPUT: - - ``issue_number`` -- integer. The github issue number where the - deprecation is introduced. + - ``issue_number`` -- integer; the github issue number where the + deprecation is introduced - ``func`` -- the function or method to be aliased diff --git a/src/sage/misc/table.py b/src/sage/misc/table.py index b6065772361..086e8fd49ed 100644 --- a/src/sage/misc/table.py +++ b/src/sage/misc/table.py @@ -23,19 +23,19 @@ class table(SageObject): INPUT: - - ``rows`` (default ``None``) -- a list of lists (or list of tuples, - etc.), containing the data to be displayed. - - ``columns`` (default ``None``) -- a list of lists (etc.), containing + - ``rows`` -- (default: ``None``) list of lists (or list of tuples, + etc.), containing the data to be displayed + - ``columns`` -- (default: ``None``) list of lists (etc.), containing the data to be displayed, but stored as columns. Set either ``rows`` or ``columns``, but not both. - - ``header_row`` (default ``False``) -- if ``True``, first row is - highlighted. - - ``header_column`` (default ``False``) -- if ``True``, first column is - highlighted. - - ``frame`` (default ``False``) -- if ``True``, put a box around each - cell. - - ``align`` (default 'left') -- the alignment of each entry: either - 'left', 'center', or 'right' + - ``header_row`` -- (default: ``False``) if ``True``, first row is + highlighted + - ``header_column`` -- (default: ``False``) if ``True``, first column is + highlighted + - ``frame`` -- (default: ``False``) if ``True``, put a box around each + cell + - ``align`` -- (default: ``'left'``) the alignment of each entry: either + ``'left'``, ``'center'``, or ``'right'`` EXAMPLES:: @@ -314,11 +314,11 @@ def options(self, **kwds): INPUT: - - ``header_row`` -- if True, first row is highlighted. - - ``header_column`` -- if True, first column is highlighted. - - ``frame`` -- if True, put a box around each cell. - - ``align`` -- the alignment of each entry: either 'left', - 'center', or 'right' + - ``header_row`` -- if ``True``, first row is highlighted + - ``header_column`` -- if ``True``, first column is highlighted + - ``frame`` -- if ``True``, put a box around each cell + - ``align`` -- the alignment of each entry: either ``'left'``, + ``'center'``, or ``'right'`` EXAMPLES:: @@ -476,7 +476,7 @@ def _repr_(self) -> str: def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -575,9 +575,7 @@ def _latex_(self): dollar signs are not automatically added, so tables can include both plain text and mathematics. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -656,9 +654,7 @@ def _html_(self): visible effect in the Sage notebook, depending on the version of the notebook. - OUTPUT: - - A :class:`~sage.misc.html.HtmlFragment` instance. + OUTPUT: :class:`~sage.misc.html.HtmlFragment` EXAMPLES:: @@ -770,24 +766,22 @@ def _html_(self): def _html_table_row(self, file, row, header=False): r""" - Write table row + Write table row. Helper method used by the :meth:`_html_` method. INPUT: - - ``file`` -- file-like object. The table row data will be - written to it. - - - ``row`` -- a list with the same number of entries as each row - of the table. + - ``file`` -- file-like object; the table row data will be + written to it - - ``header`` -- bool (default: ``False``). If True, treat this as a - header row, using ```` instead of ````. + - ``row`` -- list with the same number of entries as each row + of the table - OUTPUT: + - ``header`` -- boolean (default: ``False``); if ``True``, treat this + as a header row, using ```` instead of ```` - This method returns nothing. All output is written to ``file``. + OUTPUT: this method returns nothing; all output is written to ``file`` Strings are written verbatim unless they seem to be LaTeX code, in which case they are enclosed in a ``script`` tag diff --git a/src/sage/misc/temporary_file.py b/src/sage/misc/temporary_file.py index e9fb7d121e9..ff8c7a751ac 100644 --- a/src/sage/misc/temporary_file.py +++ b/src/sage/misc/temporary_file.py @@ -41,7 +41,7 @@ # temporary directory ################################################################# -def tmp_dir(name="dir_", ext=""): +def tmp_dir(name='dir_', ext=''): r""" Create and return a temporary directory in ``$HOME/.sage/temp/hostname/pid/`` @@ -50,9 +50,9 @@ def tmp_dir(name="dir_", ext=""): INPUT: - - ``name`` -- (default: ``"dir_"``) A prefix for the directory name. + - ``name`` -- (default: ``'dir_'``) a prefix for the directory name - - ``ext`` -- (default: ``""``) A suffix for the directory name. + - ``ext`` -- (default: ``''``) a suffix for the directory name OUTPUT: @@ -84,7 +84,7 @@ def tmp_dir(name="dir_", ext=""): # temporary filename ################################################################# -def tmp_filename(name="tmp_", ext=""): +def tmp_filename(name='tmp_', ext=''): r""" Create and return a temporary file in ``$HOME/.sage/temp/hostname/pid/`` @@ -94,22 +94,20 @@ def tmp_filename(name="tmp_", ext=""): .. warning:: If you need a particular file extension always use - ``tmp_filename(ext=".foo")``, this will ensure that the file + ``tmp_filename(ext='.foo')``, this will ensure that the file does not yet exist. If you were to use ``tmp_filename()+".foo"``, then you might overwrite an existing file! INPUT: - - ``name`` -- (default: ``"tmp_"``) A prefix for the file name. + - ``name`` -- (default: ``'tmp_'``) a prefix for the file name - - ``ext`` -- (default: ``""``) A suffix for the file name. If you + - ``ext`` -- (default: ``''``) a suffix for the file name. If you want a filename extension in the usual sense, this should start with a dot. - OUTPUT: - - The absolute path of the temporary file created. + OUTPUT: the absolute path of the temporary file created EXAMPLES:: @@ -150,10 +148,10 @@ class atomic_write: INPUT: - - ``target_filename`` -- the name of the file to be written. - Normally, the contents of this file will be overwritten. + - ``target_filename`` -- the name of the file to be written + Normally, the contents of this file will be overwritten - - ``append`` -- (boolean, default: ``False``) if True and + - ``append`` -- boolean (default: ``False``); if ``True`` and ``target_filename`` is an existing file, then copy the current contents of ``target_filename`` to the temporary file when entering the ``with`` statement. Otherwise, the temporary file is @@ -165,12 +163,13 @@ class atomic_write: mode bits of the file were changed manually). (Not to be confused with the file opening mode.) - - ``binary`` -- (boolean, default: ``True`` on Python 2, False on Python 3) the - underlying file is opened in binary mode. If False then it is opened in - text mode and an encoding with which to write the file may be supplied. + - ``binary`` -- boolean (default: ``True`` on Python 2, ``False`` on Python + 3); the underlying file is opened in binary mode. If ``False`` then it is + opened in text mode and an encoding with which to write the file may be + supplied. - ``**kwargs`` -- additional keyword arguments passed to the underlying - `io.open` call. + `io.open` call EXAMPLES:: @@ -335,7 +334,7 @@ def __enter__(self): If ``self.append``, then copy the current contents of ``self.target`` to the temporary file. - OUTPUT: a file returned by :func:`tempfile.NamedTemporaryFile`. + OUTPUT: a file returned by :func:`tempfile.NamedTemporaryFile` TESTS:: @@ -429,8 +428,8 @@ class atomic_dir: INPUT: - - ``target_directory`` -- the name of the directory to be written. - If it exists then the previous contents will be kept. + - ``target_directory`` -- the name of the directory to be written; + if it exists then the previous contents will be kept EXAMPLES:: @@ -479,7 +478,7 @@ def __enter__(self): Create and return a temporary directory in ``self.tmpdir`` (normally the same directory as the target file). - OUTPUT: a directory returned by :func:`tempfile.TemporaryDirectory`. + OUTPUT: a directory returned by :func:`tempfile.TemporaryDirectory` TESTS:: diff --git a/src/sage/misc/test_class_pickling.py b/src/sage/misc/test_class_pickling.py index bcc58d3a396..ed2eb62a540 100644 --- a/src/sage/misc/test_class_pickling.py +++ b/src/sage/misc/test_class_pickling.py @@ -8,12 +8,12 @@ class bar: def metaclass(name, bases): """ - Creates a new class in this metaclass + Create a new class in this metaclass. INPUT: - - name -- a string - - bases -- a tuple of classes + - ``name`` -- string + - ``bases`` -- tuple of classes EXAMPLES:: @@ -26,7 +26,6 @@ def metaclass(name, bases): sage: c.__bases__ (<...sage.misc.test_class_pickling.bar...>, <... 'object'>) - """ print("constructing class") result = Metaclass(name, bases, {}) diff --git a/src/sage/misc/timing.py b/src/sage/misc/timing.py index fafe2a44f2b..75d73ef2db6 100644 --- a/src/sage/misc/timing.py +++ b/src/sage/misc/timing.py @@ -41,8 +41,7 @@ def cputime(t=0, subprocesses=False): from an earlier call with ``subprocesses=True``, then ``subprocesses=True`` is assumed. - - subprocesses -- (optional), include subprocesses (default: - ``False``) + - ``subprocesses`` -- boolean (default: ``False``); include subprocesses OUTPUT: @@ -229,13 +228,9 @@ def walltime(t=0): INPUT: + - ``t`` -- (optional) float, time in CPU seconds - - ``t`` -- (optional) float, time in CPU seconds - - OUTPUT: - - - ``float`` -- time in seconds - + OUTPUT: ``float`` -- time in seconds EXAMPLES:: diff --git a/src/sage/misc/trace.py b/src/sage/misc/trace.py index 1d5f383bfc5..927915a4ba5 100644 --- a/src/sage/misc/trace.py +++ b/src/sage/misc/trace.py @@ -13,12 +13,10 @@ def trace(code, preparse=True): INPUT: + - ``code`` -- string - - ``code`` -- str - - - ``preparse`` -- bool (default: ``True``); if True, run - expression through the Sage preparser. - + - ``preparse`` -- boolean (default: ``True``); if ``True``, run + expression through the Sage preparser REMARKS: This function is extremely powerful! For example, if you want to step through each line of execution of, e.g., diff --git a/src/sage/misc/unknown.py b/src/sage/misc/unknown.py index 8387f1e2a45..fddbfccb8a1 100644 --- a/src/sage/misc/unknown.py +++ b/src/sage/misc/unknown.py @@ -5,12 +5,12 @@ The ``Unknown`` object is used in Sage in several places as return value in addition to ``True`` and ``False``, in order to signal uncertainty about or inability to compute the result. ``Unknown`` can be identified -using ``is``, or by catching :class:`UnknownError` from a boolean operation. +using ``is``, or by catching :exc:`UnknownError` from a boolean operation. .. WARNING:: Calling ``bool()`` with ``Unknown`` as argument will throw an - ``UnknownError``. This also means that in the following cases, + :exc:`UnknownError`. This also means that in the following cases, ``and``, ``not``, and ``or`` fail or return a somewhat wrong value:: sage: not Unknown # should return Unknown @@ -50,7 +50,7 @@ n=0 is neither positive nor negative n=12 is positive -Using ``UnknownError``:: +Using :exc:`UnknownError`:: sage: for n in [-3, 0, 12]: ....: try: @@ -102,18 +102,18 @@ class UnknownError(TypeError): @richcmp_method class UnknownClass(UniqueRepresentation): """ - The Unknown truth value + The Unknown truth value. The ``Unknown`` object is used in Sage in several places as return value in addition to ``True`` and ``False``, in order to signal uncertainty about or inability to compute the result. ``Unknown`` can be identified - using ``is``, or by catching :class:`UnknownError` from a boolean + using ``is``, or by catching :exc:`UnknownError` from a boolean operation. .. WARNING:: Calling ``bool()`` with ``Unknown`` as argument will throw an - ``UnknownError``. This also means that applying ``and``, ``not``, + :exc:`UnknownError`. This also means that applying ``and``, ``not``, and ``or`` to ``Unknown`` might fail. TESTS:: @@ -131,7 +131,7 @@ def __repr__(self): def __bool__(self): """ - When evaluated in a boolean context ``Unknown`` raises a ``UnknownError``. + When evaluated in a boolean context ``Unknown`` raises a :exc:`UnknownError`. EXAMPLES:: diff --git a/src/sage/misc/verbose.py b/src/sage/misc/verbose.py index eeb24b08b41..189c15f883c 100644 --- a/src/sage/misc/verbose.py +++ b/src/sage/misc/verbose.py @@ -113,29 +113,26 @@ verbose_files = [] -def verbose(mesg="", t=0, level=1, caller_name=None): +def verbose(mesg='', t=0, level=1, caller_name=None): """ Print a message if the current verbosity is at least level. INPUT: + - ``mesg`` -- string; a message to print - - ``mesg`` -- str, a message to print + - ``t`` -- integer (optional); if included, will also print ``cputime(t)``, + which is the time since time ``t``. Thus ``t`` should have been obtained + with ``t=cputime()`` - - ``t`` -- int, optional, if included, will also print - cputime(t), - which is the time since time t. Thus t should have - been obtained with t=cputime() + - ``level`` -- integer (default: 1); the verbosity level of + what we are printing - - ``level`` -- int, (default: 1) the verbosity level of - what we are printing + - ``caller_name`` -- string (default: ``None``); the name + of the calling function. In most cases Python can deduce this, so + it need not be provided. - - ``caller_name`` -- string (default: None), the name - of the calling function; in most cases Python can deduce this, so - it need not be provided. - - - OUTPUT: possibly prints a message to stdout; also returns - cputime() + OUTPUT: possibly prints a message to stdout; also returns ``cputime()`` EXAMPLES:: @@ -191,13 +188,13 @@ def set_verbose(level, files='all'): INPUT: - - ``level`` -- an integer between 0 and 2, inclusive. + - ``level`` -- integer between 0 and 2, inclusive - - ``files`` (default: 'all'): list of files to make verbose, or - 'all' to make ALL files verbose (the default). + - ``files`` -- (default: ``'all'``) list of files to make verbose, or + 'all' to make ALL files verbose (the default) OUTPUT: changes the state of the verbosity flag and possibly - appends to the list of files that are verbose. + appends to the list of files that are verbose EXAMPLES:: @@ -222,9 +219,6 @@ def set_verbose(level, files='all'): def set_verbose_files(file_name): - """ - - """ if not isinstance(file_name, list): file_name = [file_name] global verbose_files @@ -232,16 +226,10 @@ def set_verbose_files(file_name): def get_verbose_files(): - """ - - """ return verbose_files def unset_verbose_files(file_name): - """ - - """ if not isinstance(file_name, list): file_name = [file_name] for X in file_name: @@ -252,10 +240,6 @@ def get_verbose(): """ Return the global Sage verbosity level. - INPUT: int level: an integer between 0 and 2, inclusive. - - OUTPUT: changes the state of the verbosity flag. - EXAMPLES:: sage: get_verbose() diff --git a/src/sage/misc/viewer.py b/src/sage/misc/viewer.py index caca6647acf..4f62b1c5022 100644 --- a/src/sage/misc/viewer.py +++ b/src/sage/misc/viewer.py @@ -38,9 +38,9 @@ def default_viewer(viewer=None): INPUT: - - ``viewer``: ``None`` or a string: one of 'browser', 'pdf', 'png', - 'dvi' -- return the name of the corresponding program. ``None`` - is treated the same as 'browser'. + - ``viewer`` -- ``None`` or a string; one of ``'browser'``, ``'pdf'``, + ``'png'``, ``'dvi'``. Return the name of the corresponding program. + ``None`` is treated the same as ``'browser'``. EXAMPLES:: @@ -149,9 +149,9 @@ def _set(self, app=None, TYPE='browser'): INPUT: - - ``app`` -- ``None`` or a string, the program to use - - ``TYPE`` -- a string, must be in the list ``VIEWERS`` defined in - :mod:`sage.misc.viewer`. Default 'browser'. + - ``app`` -- ``None`` or a string; the program to use + - ``TYPE`` -- string (default: ``'browser'``); must be in the list + ``VIEWERS`` defined in :mod:`sage.misc.viewer` EXAMPLES:: diff --git a/src/sage/misc/weak_dict.pyx b/src/sage/misc/weak_dict.pyx index f4b20c0fcd1..eefd042bf25 100644 --- a/src/sage/misc/weak_dict.pyx +++ b/src/sage/misc/weak_dict.pyx @@ -168,7 +168,7 @@ cdef class WeakValueDictEraser: """ INPUT: - A :class:`sage.misc.weak_dict.WeakValueDictionary`. + - ``D`` -- a :class:`sage.misc.weak_dict.WeakValueDictionary` EXAMPLES:: @@ -186,7 +186,7 @@ cdef class WeakValueDictEraser: """ INPUT: - A weak reference with key. + - ``r`` -- a weak reference with key When this is called with a weak reference ``r``, then an entry from the dictionary pointed to by ``self.D`` is removed that has ``r`` as a value @@ -335,7 +335,7 @@ cdef class WeakValueDictionary(dict): INPUT: - - ``data`` -- Optional iterable of key-value pairs + - ``data`` -- (optional) iterable of key-value pairs EXAMPLES:: @@ -370,7 +370,6 @@ cdef class WeakValueDictionary(dict): sage: E = copy(D) # indirect doctest sage: set(E.items()) == set(D.items()) True - """ return WeakValueDictionary(self.items()) @@ -403,7 +402,6 @@ cdef class WeakValueDictionary(dict): sage: set(E.values()) == set(D.values()) == set(V) True - """ out = WeakValueDictionary() for k,v in self.items(): @@ -461,7 +459,7 @@ cdef class WeakValueDictionary(dict): TESTS: - Check that :issue:`15956` has been fixed, i.e., a ``TypeError`` is + Check that :issue:`15956` has been fixed, i.e., a :exc:`TypeError` is raised for unhashable objects:: sage: D = sage.misc.weak_dict.WeakValueDictionary() @@ -469,7 +467,6 @@ cdef class WeakValueDictionary(dict): Traceback (most recent call last): ... TypeError: mutable matrices are unhashable - """ cdef PyObject* wr = PyDict_GetItemWithError(self, k) if wr != NULL: @@ -536,7 +533,7 @@ cdef class WeakValueDictionary(dict): sage: list(D.items()) [(2, Integer Ring)] - Check that :issue:`15956` has been fixed, i.e., a ``TypeError`` is + Check that :issue:`15956` has been fixed, i.e., a :exc:`TypeError` is raised for unhashable objects:: sage: D = sage.misc.weak_dict.WeakValueDictionary() @@ -582,7 +579,7 @@ cdef class WeakValueDictionary(dict): TESTS: - Check that :issue:`15956` has been fixed, i.e., a ``TypeError`` is + Check that :issue:`15956` has been fixed, i.e., a :exc:`TypeError` is raised for unhashable objects:: sage: D = sage.misc.weak_dict.WeakValueDictionary() @@ -590,7 +587,6 @@ cdef class WeakValueDictionary(dict): Traceback (most recent call last): ... TypeError: mutable matrices are unhashable - """ cdef PyObject* wr = PyDict_GetItemWithError(self, k) if wr == NULL: @@ -621,13 +617,12 @@ cdef class WeakValueDictionary(dict): (1, Integer Ring) Now, the dictionary is empty, and hence the next attempt to pop an - item will fail with a ``KeyError``:: + item will fail with a :exc:`KeyError`:: sage: D.popitem() Traceback (most recent call last): ... KeyError: 'popitem(): weak value dictionary is empty' - """ for k,v in self.items(): del self[k] @@ -660,7 +655,7 @@ cdef class WeakValueDictionary(dict): TESTS: - Check that :issue:`15956` has been fixed, i.e., a ``TypeError`` is + Check that :issue:`15956` has been fixed, i.e., a :exc:`TypeError` is raised for unhashable objects:: sage: # needs sage.libs.pari @@ -669,7 +664,6 @@ cdef class WeakValueDictionary(dict): Traceback (most recent call last): ... TypeError: mutable matrices are unhashable - """ cdef PyObject * wr = PyDict_GetItemWithError(self, k) if wr == NULL: @@ -701,7 +695,7 @@ cdef class WeakValueDictionary(dict): sage: D[int(10)] Integer Ring - Check that :issue:`15956` has been fixed, i.e., a ``TypeError`` is + Check that :issue:`15956` has been fixed, i.e., a :exc:`TypeError` is raised for unhashable objects:: sage: D = sage.misc.weak_dict.WeakValueDictionary() @@ -709,7 +703,6 @@ cdef class WeakValueDictionary(dict): Traceback (most recent call last): ... TypeError: mutable matrices are unhashable - """ cdef PyObject* wr = PyDict_GetItemWithError(self, k) if wr == NULL: @@ -745,7 +738,7 @@ cdef class WeakValueDictionary(dict): sage: 3 in D False - Check that :issue:`15956` has been fixed, i.e., a ``TypeError`` is + Check that :issue:`15956` has been fixed, i.e., a :exc:`TypeError` is raised for unhashable objects:: sage: D = sage.misc.weak_dict.WeakValueDictionary() @@ -753,7 +746,6 @@ cdef class WeakValueDictionary(dict): Traceback (most recent call last): ... TypeError: mutable matrices are unhashable - """ cdef PyObject* wr = PyDict_GetItemWithError(self, k) return (wr != NULL) and (PyWeakref_GetObject(wr) != Py_None) @@ -818,7 +810,6 @@ cdef class WeakValueDictionary(dict): sage: sorted(D.keys()) [0, 1, 2, 3, 5, 6, 7, 8, 9] - """ return list(iter(self)) @@ -882,7 +873,6 @@ cdef class WeakValueDictionary(dict): <7> <8> <9> - """ cdef PyObject *key cdef PyObject *wr @@ -1001,7 +991,6 @@ cdef class WeakValueDictionary(dict): [7] <7> [8] <8> [9] <9> - """ cdef PyObject *key cdef PyObject *wr @@ -1196,9 +1185,9 @@ cdef class CachedWeakValueDictionary(WeakValueDictionary): INPUT: - - ``data`` -- Optional iterable of key-value pairs + - ``data`` -- (optional) iterable of key-value pairs - - ``cache`` -- (default: 16) Number of values with strong + - ``cache`` -- (default: 16) number of values with strong references EXAMPLES:: diff --git a/src/sage/modular/abvar/abvar.py b/src/sage/modular/abvar/abvar.py index 2c87874503b..b3d8f3492b0 100644 --- a/src/sage/modular/abvar/abvar.py +++ b/src/sage/modular/abvar/abvar.py @@ -81,11 +81,11 @@ def is_ModularAbelianVariety(x) -> bool: """ - Return True if x is a modular abelian variety. + Return ``True`` if x is a modular abelian variety. INPUT: - - ``x`` -- object + - ``x`` -- object EXAMPLES:: @@ -98,7 +98,7 @@ def is_ModularAbelianVariety(x) -> bool: sage: is_ModularAbelianVariety(J0(37)) True - Returning True is a statement about the data type not whether or + Returning ``True`` is a statement about the data type not whether or not some abelian variety is modular:: sage: is_ModularAbelianVariety(EllipticCurve('37a')) @@ -118,27 +118,23 @@ def __init__(self, groups, base_field, is_simple=None, newform_level=None, INPUT: + - ``groups`` -- tuple of congruence subgroups - - ``groups`` -- a tuple of congruence subgroups + - ``base_field`` -- a field - - ``base_field`` -- a field + - ``is_simple`` -- boolean; whether or not ``self`` is simple - - ``is_simple`` -- bool; whether or not self is - simple + - ``newform_level`` -- if ``self`` is isogenous to a + newform abelian variety, returns the level of that abelian variety - - ``newform_level`` -- if self is isogenous to a - newform abelian variety, returns the level of that abelian variety + - ``isogeny_number`` -- which isogeny class the corresponding newform + is in; this corresponds to the Cremona letter code - - ``isogeny_number`` -- which isogeny class the - corresponding newform is in; this corresponds to the Cremona letter - code - - - ``number`` -- the t number of the degeneracy map that - this abelian variety is the image under - - - ``check`` -- whether to do some type checking on the - defining data + - ``number`` -- the t number of the degeneracy map that + this abelian variety is the image under + - ``check`` -- whether to do some type checking on the + defining data EXAMPLES: One should not create an instance of this class, but we do so anyways here as an example:: @@ -203,9 +199,9 @@ def groups(self): def is_J0(self) -> bool: """ - Return whether of not self is of the form J0(N). + Return whether or not ``self`` is of the form J0(N). - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -225,9 +221,9 @@ def is_J0(self) -> bool: def is_J1(self) -> bool: """ - Return whether of not self is of the form J1(N). + Return whether or not ``self`` is of the form J1(N). - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -332,7 +328,7 @@ def base_extend(self, K): def __contains__(self, x) -> bool: """ - Determine whether or not self contains x. + Determine whether or not ``self`` contains x. EXAMPLES:: @@ -368,11 +364,11 @@ def __richcmp__(self, other, op): """ Compare two modular abelian varieties. - If other is not a modular abelian variety, compares the types of - self and other. If other is a modular abelian variety, compares the - groups, then if those are the same, compares the newform level and - isogeny class number and degeneracy map numbers. If those are not - defined or matched up, compare the underlying lattices. + If ``other`` is not a modular abelian variety, compares the types of + ``self`` and ``other``. If ``other`` is a modular abelian variety, + compares the groups, then if those are the same, compares the newform + level and isogeny class number and degeneracy map numbers. If those are + not defined or matched up, compare the underlying lattices. EXAMPLES:: @@ -426,7 +422,8 @@ def __richcmp__(self, other, op): def __radd__(self, other): """ - Return other + self when other is 0. Otherwise raise a TypeError. + Return ``other`` + ``self`` when ``other`` is 0. Otherwise raise a + :exc:`TypeError`. EXAMPLES:: @@ -510,7 +507,7 @@ def label(self) -> str: ... ValueError: self must be simple - We illustrate that self need not equal `\delta_t(A_f)`:: + We illustrate that ``self`` need not equal `\delta_t(A_f)`:: sage: J = J0(11); phi = J.degeneracy_map(33, 1) + J.degeneracy_map(33,3) sage: B = phi.image(); B @@ -533,14 +530,14 @@ def newform(self, names=None): the newform abelian variety `A_f`. If this abelian variety is not - simple, this raises a :class:`ValueError`. + simple, this raises a :exc:`ValueError`. INPUT: - - ``names`` -- (default: ``None``) If the newform has coefficients - in a number field, then a generator name must be specified. + - ``names`` -- (default: ``None``) if the newform has coefficients + in a number field, then a generator name must be specified - OUTPUT: A newform `f` so that ``self`` is isogenous to `A_f`. + OUTPUT: a newform `f` so that ``self`` is isogenous to `A_f` EXAMPLES:: @@ -569,11 +566,9 @@ def newform(self, names=None): def newform_decomposition(self, names=None): """ Return the newforms of the simple subvarieties in the decomposition of - self as a product of simple subvarieties, up to isogeny. - - OUTPUT: + ``self`` as a product of simple subvarieties, up to isogeny. - - an array of newforms + OUTPUT: an array of newforms EXAMPLES:: @@ -591,7 +586,7 @@ def newform_label(self): abelian variety `A_f`. If this abelian variety is not simple, this raises - a :class:`ValueError`. + a :exc:`ValueError`. OUTPUT: string @@ -623,16 +618,16 @@ def elliptic_curve(self): Return an elliptic curve isogenous to ``self``. If ``self`` is not dimension 1 - with rational base ring, this raises a :class:`ValueError`. + with rational base ring, this raises a :exc:`ValueError`. The elliptic curve is found by looking it up in the CremonaDatabase. The CremonaDatabase contains all curves up to some large conductor. If a curve is not found in the - CremonaDatabase, a :class:`RuntimeError` will be raised. In + CremonaDatabase, a :exc:`RuntimeError` will be raised. In practice, only the most committed users will see this - :class:`RuntimeError`. + :exc:`RuntimeError`. - OUTPUT: an elliptic curve isogenous to ``self``. + OUTPUT: an elliptic curve isogenous to ``self`` EXAMPLES:: @@ -695,11 +690,11 @@ def elliptic_curve(self): def _isogeny_to_newform_abelian_variety(self): r""" - Return an isogeny from self to an abelian variety `A_f` + Return an isogeny from ``self`` to an abelian variety `A_f` attached to a newform. - If self is not simple (so that no such - isogeny exists), this raises a :class:`ValueError`. + If ``self`` is not simple (so that no such + isogeny exists), this raises a :exc:`ValueError`. EXAMPLES:: @@ -742,10 +737,10 @@ def _isogeny_to_newform_abelian_variety(self): def _simple_isogeny(self, other): """ - Given self and other, if both are simple, and correspond to the + Given ``self`` and ``other``, if both are simple, and correspond to the same newform with the same congruence subgroup, return an isogeny. - Otherwise, this raises a :class:`ValueError`. + Otherwise, this raises a :exc:`ValueError`. INPUT: @@ -795,11 +790,9 @@ def _Hom_(self, B, cat=None): """ INPUT: + - ``B`` -- modular abelian varieties - - ``B`` -- modular abelian varieties - - - ``cat`` -- category - + - ``cat`` -- category EXAMPLES:: @@ -826,8 +819,8 @@ def _Hom_(self, B, cat=None): def in_same_ambient_variety(self, other): """ - Return True if self and other are abelian subvarieties of the same - ambient product Jacobian. + Return ``True`` if ``self`` and ``other`` are abelian subvarieties of + the same ambient product Jacobian. EXAMPLES:: @@ -848,7 +841,7 @@ def in_same_ambient_variety(self, other): def modular_kernel(self): """ Return the modular kernel of this abelian variety, which is the - kernel of the canonical polarization of self. + kernel of the canonical polarization of ``self``. EXAMPLES:: @@ -881,8 +874,8 @@ def modular_degree(self): def intersection(self, other): """ - Return the intersection of self and other inside a common ambient - Jacobian product. + Return the intersection of ``self`` and ``other`` inside a common + ambient Jacobian product. When ``other`` is a modular abelian variety, the output will be a tuple ``(G, A)``, where ``G`` is a finite subgroup that surjects onto the @@ -893,23 +886,20 @@ def intersection(self, other): INPUT: + - ``other`` -- a modular abelian variety or a finite + group - - ``other`` -- a modular abelian variety or a finite - group + OUTPUT: if other is a modular abelian variety: - OUTPUT: If other is a modular abelian variety: + - ``G`` -- finite subgroup of self - - - ``G`` -- finite subgroup of self - - - ``A`` -- abelian variety (identity component of - intersection) + - ``A`` -- abelian variety (identity component of + intersection) If other is a finite group: - - ``G`` -- a finite group - + - ``G`` -- a finite group EXAMPLES: We intersect some abelian varieties with finite intersection. @@ -918,16 +908,24 @@ def intersection(self, other): sage: J = J0(37) sage: J[0].intersection(J[1]) - (Finite subgroup with invariants [2, 2] over QQ of Simple abelian subvariety 37a(1,37) of dimension 1 of J0(37), Simple abelian subvariety of dimension 0 of J0(37)) + (Finite subgroup with invariants [2, 2] over QQ of Simple abelian + subvariety 37a(1,37) of dimension 1 of J0(37), Simple abelian + subvariety of dimension 0 of J0(37)) :: sage: D = list(J0(65)); D - [Simple abelian subvariety 65a(1,65) of dimension 1 of J0(65), Simple abelian subvariety 65b(1,65) of dimension 2 of J0(65), Simple abelian subvariety 65c(1,65) of dimension 2 of J0(65)] + [Simple abelian subvariety 65a(1,65) of dimension 1 of J0(65), + Simple abelian subvariety 65b(1,65) of dimension 2 of J0(65), + Simple abelian subvariety 65c(1,65) of dimension 2 of J0(65)] sage: D[0].intersection(D[1]) - (Finite subgroup with invariants [2] over QQ of Simple abelian subvariety 65a(1,65) of dimension 1 of J0(65), Simple abelian subvariety of dimension 0 of J0(65)) + (Finite subgroup with invariants [2] over QQ of Simple abelian + subvariety 65a(1,65) of dimension 1 of J0(65), Simple abelian + subvariety of dimension 0 of J0(65)) sage: (D[0]+D[1]).intersection(D[1]+D[2]) - (Finite subgroup with invariants [2] over QQbar of Abelian subvariety of dimension 3 of J0(65), Abelian subvariety of dimension 2 of J0(65)) + (Finite subgroup with invariants [2] over QQbar of Abelian + subvariety of dimension 3 of J0(65), Abelian subvariety of + dimension 2 of J0(65)) :: @@ -1021,17 +1019,17 @@ def intersection(self, other): def __add__(self, other): r""" - Return the sum of the *images* of self and other inside the + Return the sum of the *images* of ``self`` and ``other`` inside the ambient Jacobian product. - Here self and other must be abelian + Here ``self`` and ``other`` must be abelian subvarieties of the ambient Jacobian product. .. WARNING:: The sum of course only makes sense in some ambient variety, and by definition this function takes the sum of the images - of both self and other in the ambient product Jacobian. + of both ``self`` and ``other`` in the ambient product Jacobian. EXAMPLES: @@ -1100,13 +1098,11 @@ def __add__(self, other): def direct_product(self, other): """ - Compute the direct product of self and other. + Compute the direct product of ``self`` and ``other``. INPUT: - - - ``self, other`` -- modular abelian varieties - + - ``self``, ``other`` -- modular abelian varieties OUTPUT: abelian variety @@ -1128,13 +1124,11 @@ def direct_product(self, other): def __pow__(self, n): """ - Return `n^{th}` power of self. + Return `n`-th power of ``self``. INPUT: - - - ``n`` -- a nonnegative integer - + - ``n`` -- nonnegative integer OUTPUT: an abelian variety @@ -1162,7 +1156,7 @@ def __pow__(self, n): def __mul__(self, other): """ - Compute the direct product of self and other. + Compute the direct product of ``self`` and ``other``. EXAMPLES: Some modular Jacobians:: @@ -1188,17 +1182,15 @@ def __mul__(self, other): def quotient(self, other, **kwds): """ - Compute the quotient of self and other, where other is either an - abelian subvariety of self or a finite subgroup of self. + Compute the quotient of ``self`` and ``other``, where other is either an + abelian subvariety of ``self`` or a finite subgroup of ``self``. INPUT: + - ``other`` -- a finite subgroup or subvariety + - further named arguments, that are currently ignored - - ``other`` -- a finite subgroup or subvariety - - further named arguments, that are currently ignored. - - - OUTPUT: a pair (A, phi) with phi the quotient map from self to A + OUTPUT: a pair (A, phi) with phi the quotient map from ``self`` to A EXAMPLES: We quotient `J_0(33)` out by an abelian subvariety:: @@ -1228,14 +1220,12 @@ def quotient(self, other, **kwds): def __truediv__(self, other): """ - Compute the quotient of self and other, where other is either an - abelian subvariety of self or a finite subgroup of self. + Compute the quotient of ``self`` and ``other``, where other is either + an abelian subvariety of ``self`` or a finite subgroup of ``self``. INPUT: - - - ``other`` -- a finite subgroup or subvariety - + - ``other`` -- a finite subgroup or subvariety EXAMPLES: Quotient out by a finite group:: @@ -1288,21 +1278,19 @@ def __truediv__(self, other): def degeneracy_map(self, M_ls, t_ls): """ - Return the degeneracy map with domain self and given - level/parameter. If self.ambient_variety() is a product of + Return the degeneracy map with domain ``self`` and given + level/parameter. If ``self.ambient_variety()`` is a product of Jacobians (as opposed to a single Jacobian), then one can provide a list of new levels and parameters, corresponding to the ambient Jacobians in order. (See the examples below.) INPUT: + - ``M``, ``t`` -- integers level and `t`, or - - ``M, t`` -- integers level and `t`, or - - - ``Mlist, tlist`` -- if self is in a nontrivial - product ambient Jacobian, input consists of a list of levels and - corresponding list of `t`'s. - + - ``Mlist, tlist`` -- if ``self`` is in a nontrivial + product ambient Jacobian, input consists of a list of levels and + corresponding list of `t`'s. OUTPUT: a degeneracy map @@ -1375,21 +1363,18 @@ def degeneracy_map(self, M_ls, t_ls): def _quotient_by_finite_subgroup(self, G): """ - Return the quotient of self by the finite subgroup `G`. + Return the quotient of ``self`` by the finite subgroup `G`. This is used internally by the quotient and __div__ commands. INPUT: + - ``G`` -- a finite subgroup of self - - ``G`` -- a finite subgroup of self - - - OUTPUT: abelian variety - the quotient `Q` of self by `G` - + OUTPUT: - - ``morphism`` -- from self to the quotient - `Q` + - abelian variety; the quotient `Q` of ``self`` by `G` + - ``morphism`` -- from ``self`` to the quotient `Q` EXAMPLES: We quotient the elliptic curve `J_0(11)` out by its cuspidal subgroup. @@ -1424,7 +1409,6 @@ def _quotient_by_finite_subgroup(self, G): Abelian variety J0(22) of dimension 2 sage: f Abelian variety endomorphism of Abelian variety J0(22) of dimension 2 - """ if G.order() == 1: return self, self.endomorphism_ring().identity() @@ -1436,24 +1420,18 @@ def _quotient_by_finite_subgroup(self, G): def _quotient_by_abelian_subvariety(self, B): """ - Return the quotient of self by the abelian variety `B`. - This is used internally by the quotient and __div__ commands. + Return the quotient of ``self`` by the abelian variety `B`. + This is used internally by the quotient and ``__div__`` commands. INPUT: - - - ``B`` -- an abelian subvariety of self - + - ``B`` -- an abelian subvariety of ``self`` OUTPUT: + - ``abelian variety`` -- quotient `Q` of ``self`` by B - - ``abelian variety`` -- quotient `Q` of self - by B - - - ``morphism`` -- from self to the quotient - `Q` - + - ``morphism`` -- from ``self`` to the quotient `Q` EXAMPLES: We compute the new quotient of `J_0(33)`. @@ -1524,13 +1502,11 @@ def _quotient_by_abelian_subvariety(self, B): def projection(self, A, check=True): """ Given an abelian subvariety A of self, return a projection morphism - from self to A. Note that this morphism need not be unique. + from ``self`` to A. Note that this morphism need not be unique. INPUT: - - - ``A`` -- an abelian variety - + - ``A`` -- an abelian variety OUTPUT: a morphism @@ -1593,8 +1569,8 @@ def projection(self, A, check=True): def project_to_factor(self, n): """ - If self is an ambient product of Jacobians, return a projection - from self to the nth such Jacobian. + If ``self`` is an ambient product of Jacobians, return a projection + from ``self`` to the `n`-th such Jacobian. EXAMPLES:: @@ -1641,7 +1617,7 @@ def project_to_factor(self, n): def is_subvariety_of_ambient_jacobian(self): """ - Return True if self is (presented as) a subvariety of the ambient + Return ``True`` if ``self`` is (presented as) a subvariety of the ambient product Jacobian. Every abelian variety in Sage is a quotient of a subvariety of an @@ -1695,8 +1671,8 @@ def ambient_variety(self): def ambient_morphism(self): """ - Return the morphism from self to the ambient variety. This is - injective if self is natural a subvariety of the ambient product + Return the morphism from ``self`` to the ambient variety. This is + injective if ``self`` is natural a subvariety of the ambient product Jacobian. OUTPUT: morphism @@ -1716,9 +1692,7 @@ def ambient_morphism(self): [ 1 1 -2 0 2 -1] [ 0 3 -2 -1 2 0] - phi is of course injective - - :: + ``phi`` is of course injective:: sage: phi.kernel() (Finite subgroup with invariants [] over QQ of Simple abelian subvariety 11a(1,33) of dimension 1 of J0(33), @@ -1743,7 +1717,8 @@ def ambient_morphism(self): [ 0 0 5 10 -5 15] [ 0 0 0 15 -15 30] sage: phi.kernel()[0] - Finite subgroup with invariants [5, 15, 15] over QQ of Abelian variety factor of dimension 2 of J0(33) + Finite subgroup with invariants [5, 15, 15] over QQ of Abelian + variety factor of dimension 2 of J0(33) """ try: return self.__ambient_morphism @@ -1755,9 +1730,9 @@ def ambient_morphism(self): def is_ambient(self) -> bool: """ - Return True if self equals the ambient product Jacobian. + Return ``True`` if ``self`` equals the ambient product Jacobian. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -1831,7 +1806,7 @@ def conductor(self): def rank(self): """ - Return the rank of the underlying lattice of self. + Return the rank of the underlying lattice of ``self``. EXAMPLES:: @@ -1860,7 +1835,7 @@ def degree(self): def endomorphism_ring(self, category=None): """ - Return the endomorphism ring of self. + Return the endomorphism ring of ``self``. OUTPUT: b = self.sturm_bound() @@ -1917,10 +1892,10 @@ def sturm_bound(self): def is_hecke_stable(self) -> bool: """ - Return True if self is stable under the Hecke operators of its + Return ``True`` if ``self`` is stable under the Hecke operators of its ambient Jacobian. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -1957,9 +1932,9 @@ def is_hecke_stable(self) -> bool: def is_subvariety(self, other) -> bool: """ - Return True if self is a subvariety of other as they sit in a + Return ``True`` if ``self`` is a subvariety of other as they sit in a common ambient modular Jacobian. In particular, this function will - only return True if self and other have exactly the same ambient + only return ``True`` if ``self`` and ``other`` have exactly the same ambient Jacobians. EXAMPLES:: @@ -2008,9 +1983,9 @@ def change_ring(self, R): def level(self): """ Return the level of this modular abelian variety, which is an - integer N (usually minimal) such that this modular abelian variety + integer `N` (usually minimal) such that this modular abelian variety is a quotient of `J_1(N)`. In the case that the ambient - variety of self is a product of Jacobians, return the LCM of their + variety of ``self`` is a product of Jacobians, return the LCM of their levels. EXAMPLES:: @@ -2030,7 +2005,7 @@ def level(self): def newform_level(self, none_if_not_known=False): """ - Write self as a product (up to isogeny) of newform abelian + Write ``self`` as a product (up to isogeny) of newform abelian varieties `A_f`. Then this function return the least common multiple of the levels of the newforms `f`, along with the corresponding group or list of groups (the groups do not @@ -2038,11 +2013,9 @@ def newform_level(self, none_if_not_known=False): INPUT: - - - ``none_if_not_known`` -- (default: ``False``) if True, - return None instead of attempting to compute the newform level, if - it isn't already known. This None result is not cached. - + - ``none_if_not_known`` -- boolean (default: ``False``); if ``True``, + return ``None`` instead of attempting to compute the newform level, + if it isn't already known. This None result is not cached. OUTPUT: integer group or list of distinct groups @@ -2074,7 +2047,7 @@ def newform_level(self, none_if_not_known=False): def zero_subvariety(self): """ - Return the zero subvariety of self. + Return the zero subvariety of ``self``. EXAMPLES:: @@ -2140,7 +2113,7 @@ def _ambient_latex_repr(self): def _ambient_lattice(self): """ - Return free lattice of rank twice the degree of self. This is the + Return free lattice of rank twice the degree of ``self``. This is the lattice corresponding to the ambient product Jacobian. OUTPUT: lattice @@ -2168,7 +2141,7 @@ def _ambient_lattice(self): def _ambient_modular_symbols_spaces(self): """ Return a tuple of the ambient cuspidal modular symbols spaces that - make up the Jacobian product that contains self. + make up the Jacobian product that contains ``self``. OUTPUT: tuple of cuspidal modular symbols spaces @@ -2193,7 +2166,7 @@ def _ambient_modular_symbols_spaces(self): def _ambient_modular_symbols_abvars(self): """ Return a tuple of the ambient modular symbols abelian varieties - that make up the Jacobian product that contains self. + that make up the Jacobian product that contains ``self``. OUTPUT: tuple of modular symbols abelian varieties @@ -2249,9 +2222,7 @@ def _ambient_hecke_matrix_on_modular_symbols(self, n): INPUT: - - - ``n`` -- an integer `\geq 1`. - + - ``n`` -- integer `\geq 1` OUTPUT: a matrix @@ -2294,14 +2265,13 @@ def rational_torsion_order(self, proof=True): INPUT: - - ``proof`` -- a boolean (default: ``True``) + - ``proof`` -- boolean (default: ``True``) OUTPUT: The order of the rational torsion subgroup of this modular abelian variety. - EXAMPLES:: sage: J0(11).rational_torsion_subgroup().order() @@ -2354,15 +2324,13 @@ def number_of_rational_points(self): def frobenius_polynomial(self, p, var='x'): """ - Computes the frobenius polynomial at `p`. + Compute the frobenius polynomial at `p`. INPUT: - ``p`` -- prime number - OUTPUT: - - a monic integral polynomial + OUTPUT: a monic integral polynomial EXAMPLES:: @@ -2621,9 +2589,9 @@ def padic_lseries(self, p): ############################################################################### def hecke_operator(self, n): """ - Return the `n^{th}` Hecke operator on the modular abelian + Return the `n`-th Hecke operator on the modular abelian variety, if this makes sense [[elaborate]]. Otherwise raise a - ValueError. + :exc:`ValueError`. EXAMPLES: We compute `T_2` on `J_0(37)`. @@ -2660,18 +2628,15 @@ def hecke_operator(self, n): def hecke_polynomial(self, n, var='x'): r""" - Return the characteristic polynomial of the `n^{th}` Hecke - operator `T_n` acting on self. Raises an ArithmeticError - if self is not Hecke equivariant. + Return the characteristic polynomial of the `n`-th Hecke + operator `T_n` acting on ``self``. Raises an :exc:`ArithmeticError` + if ``self`` is not Hecke equivariant. INPUT: + - ``n`` -- integer `\geq 1` - - ``n`` -- integer `\geq 1` - - - ``var`` -- string (default: 'x'); valid variable - name - + - ``var`` -- string (default: ``'x'``); valid variable name EXAMPLES:: @@ -2713,11 +2678,9 @@ def _compute_hecke_polynomial(self, n, var='x'): INPUT: + - ``n`` -- positive integer - - ``n`` -- positive integer - - - ``var`` -- string (default: 'x') - + - ``var`` -- string (default: ``'x'``) EXAMPLES:: @@ -2732,7 +2695,7 @@ def _integral_hecke_matrix(self, n): Return the matrix of the Hecke operator `T_n` acting on the integral homology of this modular abelian variety, if the modular abelian variety is stable under `T_n`. Otherwise, - raise an ArithmeticError. + raise an :exc:`ArithmeticError`. EXAMPLES:: @@ -2753,7 +2716,7 @@ def _rational_hecke_matrix(self, n): Return the matrix of the Hecke operator `T_n` acting on the rational homology `H_1(A,\QQ)` of this modular abelian variety, if this action is defined. Otherwise, raise an - ArithmeticError. + :exc:`ArithmeticError`. EXAMPLES:: @@ -2804,8 +2767,8 @@ def qbar_torsion_subgroup(self): return G def rational_torsion_subgroup(self): - """ - Return the maximal torsion subgroup of self defined over QQ. + r""" + Return the maximal torsion subgroup of ``self`` defined over `\QQ`. EXAMPLES:: @@ -3081,17 +3044,15 @@ def finite_subgroup(self, X, field_of_definition=None, check=True): INPUT: + - ``X`` -- list of elements of other finite subgroups + of this modular abelian variety or elements that coerce into the + rational homology (viewed as a rational vector space); also X could + be a finite subgroup itself that is contained in this abelian + variety. - - ``X`` -- list of elements of other finite subgroups - of this modular abelian variety or elements that coerce into the - rational homology (viewed as a rational vector space); also X could - be a finite subgroup itself that is contained in this abelian - variety. - - - ``field_of_definition`` -- (default: None) field - over which this group is defined. If None try to figure out the - best base field. - + - ``field_of_definition`` -- (default: ``None``) field + over which this group is defined. If ``None`` try to figure out the + best base field. OUTPUT: a finite subgroup of a modular abelian variety @@ -3120,7 +3081,6 @@ def finite_subgroup(self, X, field_of_definition=None, check=True): Finite subgroup with invariants [2, 2] over QQ of Simple abelian subvariety 43a(1,43) of dimension 1 of J0(43) sage: B.finite_subgroup(G) Finite subgroup with invariants [2, 2] over QQ of Simple abelian subvariety 43b(1,43) of dimension 2 of J0(43) - """ if isinstance(X, (list, tuple)): X = self._ambient_lattice().span(X) @@ -3148,10 +3108,9 @@ def finite_subgroup(self, X, field_of_definition=None, check=True): def torsion_subgroup(self, n): """ - If n is an integer, return the subgroup of points of order n. - Return the `n`-torsion subgroup of elements of order - dividing `n` of this modular abelian variety `A`, - i.e., the group `A[n]`. + If `n` is an integer, return the subgroup of points of order `n`. + Return the `n`-torsion subgroup of elements of order dividing `n` of + this modular abelian variety `A`, i.e., the group `A[n]`. EXAMPLES:: @@ -3189,26 +3148,22 @@ def degen_t(self, none_if_not_known=False): """ If this abelian variety is obtained via decomposition then it gets labeled with the newform label along with some information about - degeneracy maps. In particular, the label ends in a pair - `(t,N)`, where `N` is the ambient level and - `t` is an integer that divides the quotient of `N` - by the newform level. This function returns the tuple - `(t,N)`, or raises a :class:`ValueError` if self is not simple. + degeneracy maps. In particular, the label ends in a pair `(t,N)`, where + `N` is the ambient level and `t` is an integer that divides the + quotient of `N` by the newform level. This function returns the tuple + `(t,N)`, or raises a :exc:`ValueError` if ``self`` is not simple. - .. note:: + .. NOTE:: - It need not be the case that self is literally equal to the - image of the newform abelian variety under the `t^{th}` - degeneracy map. See the documentation for the label method - for more details. + It need not be the case that ``self`` is literally equal to the + image of the newform abelian variety under the `t`-th degeneracy + map. See the documentation for the label method for more details. INPUT: - - - ``none_if_not_known`` -- (default: ``False``); if - True, return None instead of attempting to compute the degen map's - `t`, if it isn't known. This None result is not cached. - + - ``none_if_not_known`` -- (default: ``False``) if ``True``, return + ``None`` instead of attempting to compute the degen map's `t`, if it + isn't known. This ``None`` result is not cached. OUTPUT: a pair (integer, integer) @@ -3247,14 +3202,13 @@ def isogeny_number(self, none_if_not_known=False): simple abelian varieties that ``self`` is in. If ``self`` is not simple, - this raises a :class:`ValueError` exception. + this raises a :exc:`ValueError` exception. INPUT: - - ``none_if_not_known`` -- bool (default: ``False``); if - ``True`` then this function may return ``None`` instead of ``True`` - or ``False`` if - we do not already know the isogeny number of ``self``. + - ``none_if_not_known`` -- boolean (default: ``False``); if + ``True`` then this function may return ``None`` instead of ``True`` + or ``False`` if we do not already know the isogeny number of ``self``. EXAMPLES: We test the ``none_if_not_known`` flag first:: @@ -3262,7 +3216,7 @@ def isogeny_number(self, none_if_not_known=False): True Of course, `J_0(33)` is not simple, so this function - raises a :class:`ValueError`:: + raises a :exc:`ValueError`:: sage: J0(33).isogeny_number() Traceback (most recent call last): @@ -3303,11 +3257,9 @@ def is_simple(self, none_if_not_known=False): INPUT: - - - ``none_if_not_known`` -- bool (default: ``False``); if - True then this function may return None instead of True of False if - we don't already know whether or not self is simple. - + - ``none_if_not_known`` -- boolean (default: ``False``); if ``True`` + then this function may return ``None`` instead of ``True`` of + ``False`` if we don't already know whether or not ``self`` is simple. EXAMPLES:: @@ -3332,18 +3284,19 @@ def is_simple(self, none_if_not_known=False): def decomposition(self, simple=True, bound=None): """ - Return a sequence of abelian subvarieties of self that are all - simple, have finite intersection and sum to self. + Return a sequence of abelian subvarieties of ``self`` that are all + simple, have finite intersection and sum to ``self``. - INPUT: simple- bool (default: ``True``) if True, all factors are - simple. If False, each factor returned is isogenous to a power of a - simple and the simples in each factor are distinct. + INPUT: + - ``simple`` -- boolean (default: ``True``); if ``True``, all factors + are simple. If ``False``, each factor returned is isogenous to a + power of a simple and the simples in each factor are distinct. - - ``bound`` -- int (default: None) if given, only use - Hecke operators up to this bound when decomposing. This can give - wrong answers, so use with caution! + - ``bound`` -- integer (default: ``None``); if given, only use + Hecke operators up to this bound when decomposing. This can give + wrong answers, so use with caution! EXAMPLES:: @@ -3523,8 +3476,7 @@ def decomposition(self, simple=True, bound=None): def _classify_ambient_factors(self, simple=True, bound=None): r""" This function implements the following algorithm, which produces - data useful in finding a decomposition or complement of self. - + data useful in finding a decomposition or complement of ``self``. #. Suppose `A_1 + \cdots + A_n` is a simple decomposition of the ambient space. @@ -3533,26 +3485,23 @@ def _classify_ambient_factors(self, simple=True, bound=None): `B_i = A_1 + \cdots + A_i`. #. For each `i`, compute the intersection `C_i` of - `B_i` and self. + `B_i` and ``self``. #. For each `i`, if the dimension of `C_i` is bigger than `C_{i-1}` put `i` in the "in" list; otherwise put `i` in the "out" list. - - Then one can show that self is isogenous to the sum of the + Then one can show that ``self`` is isogenous to the sum of the `A_i` with `i` in the "in" list. Moreover, the sum of the `A_j` with `i` in the "out" list is a - complement of self in the ambient space. + complement of ``self`` in the ambient space. INPUT: + - ``simple`` -- boolean (default: ``True``) - - ``simple`` -- bool (default: ``True``) - - - ``bound`` -- integer (default: None); if given, - passed onto decomposition function - + - ``bound`` -- integer (default: ``None``); if given, + passed onto decomposition function OUTPUT: IN list OUT list simple (or power of simple) factors @@ -3699,11 +3648,10 @@ def complement(self, A=None): INPUT: - - ``A`` -- (default: None); if given, A must be an - abelian variety that contains self, in which case the complement of - self is taken inside A. Otherwise the complement is taken in the - ambient product Jacobian. - + - ``A`` -- (default: ``None``) if given, ``A`` must be an + abelian variety that contains ``self``, in which case the complement of + ``self`` is taken inside ``A``. Otherwise the complement is taken in the + ambient product Jacobian. OUTPUT: abelian variety @@ -3749,14 +3697,14 @@ def dual(self): OUTPUT: - dual abelian variety - - morphism from self to dual + - morphism from ``self`` to dual - covering morphism from J to dual .. warning:: - This is currently only implemented when self is an abelian + This is currently only implemented when ``self`` is an abelian subvariety of the ambient Jacobian product, and the - complement of self in the ambient product Jacobian share no + complement of ``self`` in the ambient product Jacobian share no common factors. A more general implementation will require implementing computation of the intersection pairing on integral homology and the resulting Weil pairing on @@ -3822,16 +3770,14 @@ def dual(self): def _factors_with_same_label(self, other): """ - Given two modular abelian varieties self and other, this function + Given two modular abelian varieties ``self`` and ``other``, this function returns a list of simple abelian subvarieties appearing in the - decomposition of self that have the same newform labels. Each + decomposition of ``self`` that have the same newform labels. Each simple factor with a given newform label appears at most one. INPUT: - - - ``other`` -- abelian variety - + - ``other`` -- abelian variety OUTPUT: list of simple abelian varieties @@ -3887,8 +3833,8 @@ def _factors_with_same_label(self, other): def _complement_shares_no_factors_with_same_label(self): """ - Return True if no simple factor of self has the same newform_label - as any factor in a Poincaré complement of self in the ambient + Return ``True`` if no simple factor of ``self`` has the same newform_label + as any factor in a Poincaré complement of ``self`` in the ambient product Jacobian. EXAMPLES: `J_0(37)` is made up of two non-isogenous @@ -3950,8 +3896,8 @@ def _complement_shares_no_factors_with_same_label(self): def __getitem__(self, i): """ - Return the `i^{th}` decomposition factor of self - or return the slice `i` of decompositions of self. + Return the `i`-th decomposition factor of self + or return the slice `i` of decompositions of ``self``. EXAMPLES:: @@ -3991,17 +3937,13 @@ def __init__(self, groups, lattice=None, base_field=QQ, is_simple=None, newform_ INPUT: + - ``groups`` -- tuple of congruence subgroups - - ``groups`` -- a tuple of congruence subgroups - - - ``lattice`` -- (default: `\ZZ^n`) a - full lattice in `\ZZ^n`, where `n` is the - sum of the dimensions of the spaces of cuspidal modular symbols - corresponding to each `\Gamma \in` groups - - - ``base_field`` -- a field (default: - `\QQ`) + - ``lattice`` -- (default: `\ZZ^n`) a full lattice in `\ZZ^n`, where + `n` is the sum of the dimensions of the spaces of cuspidal modular + symbols corresponding to each `\Gamma \in` groups + - ``base_field`` -- a field (default: `\QQ`) EXAMPLES:: @@ -4030,10 +3972,8 @@ def lattice(self): OUTPUT: - - - ``lattice`` -- a lattice embedded in the rational - homology of the ambient product Jacobian - + - ``lattice`` -- a lattice embedded in the rational + homology of the ambient product Jacobian EXAMPLES:: @@ -4179,9 +4119,7 @@ def _set_lattice(self, lattice): INPUT: - - - ``lattice`` -- a lattice - + - ``lattice`` -- a lattice EXAMPLES: We do something evil - there's no type checking since this function is for internal use only:: @@ -4197,7 +4135,7 @@ def modular_symbols(self, sign=0): """ Return space of modular symbols (with given sign) associated to this modular abelian variety, if it can be found by cutting down - using Hecke operators. Otherwise raise a :class:`RuntimeError` + using Hecke operators. Otherwise raise a :exc:`RuntimeError` exception. EXAMPLES:: @@ -4247,15 +4185,15 @@ def modular_symbols(self, sign=0): def _compute_hecke_polynomial(self, n, var='x'): r""" - Return the characteristic polynomial of the `n^{th}` Hecke + Return the characteristic polynomial of the `n`-th Hecke operator on ``self``. - .. note:: + .. NOTE:: - If self has dimension d, then this is a polynomial of - degree d. It is not of degree 2\*d, so it is the square + If ``self`` has dimension `d`, then this is a polynomial of + degree `d`. It is not of degree `2d`, so it is the square root of the characteristic polynomial of the Hecke operator - on integral or rational homology (which has degree 2\*d). + on integral or rational homology (which has degree `2d`). EXAMPLES:: @@ -4280,16 +4218,14 @@ def _compute_hecke_polynomial(self, n, var='x'): def _integral_hecke_matrix(self, n, sign=0): """ Return the action of the Hecke operator `T_n` on the - integral homology of self. + integral homology of ``self``. INPUT: + - ``n`` -- positive integer - - ``n`` -- a positive integer - - - ``sign`` -- 0, +1, or -1; if 1 or -1 act on the +1 or - -1 quotient of the integral homology. - + - ``sign`` -- 0, +1, or -1; if 1 or -1 act on the +1 or + -1 quotient of the integral homology EXAMPLES:: @@ -4310,16 +4246,14 @@ def _integral_hecke_matrix(self, n, sign=0): def _rational_hecke_matrix(self, n, sign=0): """ Return the action of the Hecke operator `T_n` on the - rational homology of self. + rational homology of ``self``. INPUT: + - ``n`` -- positive integer - - ``n`` -- a positive integer - - - ``sign`` -- 0, +1, or -1; if 1 or -1 act on the +1 or - -1 quotient of the rational homology. - + - ``sign`` -- 0, +1, or -1; if 1 or -1 act on the +1 or + -1 quotient of the rational homology EXAMPLES:: @@ -4355,7 +4289,7 @@ def group(self): def is_subvariety(self, other): """ - Return True if self is a subvariety of other. + Return ``True`` if ``self`` is a subvariety of ``other``. EXAMPLES:: @@ -4410,11 +4344,11 @@ def is_subvariety(self, other): def is_ambient(self): """ - Return True if this abelian variety attached to a modular symbols + Return ``True`` if this abelian variety attached to a modular symbols space is attached to the cuspidal subspace of the ambient modular symbols space. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -4457,17 +4391,15 @@ def dimension(self): def new_subvariety(self, p=None): """ - Return the new or `p`-new subvariety of self. + Return the new or `p`-new subvariety of ``self``. INPUT: + - ``self`` -- a modular abelian variety - - ``self`` -- a modular abelian variety - - - ``p`` -- prime number or None (default); if p is a - prime, return the p-new subvariety. Otherwise return the full new - subvariety. - + - ``p`` -- prime number or None (default); if `p` is a + prime, return the `p`-new subvariety. Otherwise return the full new + subvariety. EXAMPLES:: @@ -4492,17 +4424,15 @@ def new_subvariety(self, p=None): def old_subvariety(self, p=None): """ - Return the old or `p`-old abelian variety of self. + Return the old or `p`-old abelian variety of ``self``. INPUT: + - ``self`` -- a modular abelian variety - - ``self`` -- a modular abelian variety - - - ``p`` -- prime number or None (default); if p is a - prime, return the p-old subvariety. Otherwise return the full old - subvariety. - + - ``p`` -- prime number or ``None`` (default); if `p` is a + prime, return the `p`-old subvariety. Otherwise return the full old + subvariety. EXAMPLES:: @@ -4530,15 +4460,16 @@ def decomposition(self, simple=True, bound=None): Decompose this modular abelian variety as a product of abelian subvarieties, up to isogeny. - INPUT: simple- bool (default: ``True``) if True, all factors are - simple. If False, each factor returned is isogenous to a power of a - simple and the simples in each factor are distinct. + INPUT: + - ``simple`` -- boolean (default: ``True``); if ``True``, all factors + are simple. If ``False``, each factor returned is isogenous to a + power of a simple and the simples in each factor are distinct. - - ``bound`` -- int (default: None) if given, only use - Hecke operators up to this bound when decomposing. This can give - wrong answers, so use with caution! + - ``bound`` -- integer (default: ``None``); if given, only use + Hecke operators up to this bound when decomposing. This can give + wrong answers, so use with caution! EXAMPLES:: @@ -4647,14 +4578,18 @@ def _modular_symbols(self): return self.__modsym def component_group_order(self, p): - """ + r""" Return the order of the component group of the special fiber - at p of the Neron model of self. + at `p` of the Neron model of ``self``. - NOTE: For bad primes, this is only implemented when the group - if Gamma0 and p exactly divides the level. + .. NOTE:: - NOTE: the input abelian variety must be simple + For bad primes, this is only implemented when the group + is `\Gamma_0` and `p` exactly divides the level. + + .. NOTE:: + + The input abelian variety must be simple. ALGORITHM: See "Component Groups of Quotients of J0(N)" by Kohel and Stein. That paper is about optimal quotients; however, section 4.1 of Conrad-Stein "Component @@ -4663,11 +4598,9 @@ def component_group_order(self, p): INPUT: - - p -- a prime number - - OUTPUT: + - ``p`` -- a prime number - - Integer + OUTPUT: integer EXAMPLES:: @@ -4766,11 +4699,9 @@ def _invariants_of_image_of_component_group_of_J0(self, p): INPUT: - - p -- integer + - ``p`` -- integer - OUTPUT: - - - list -- of elementary invariants + OUTPUT: list of elementary invariants EXAMPLES:: @@ -4801,11 +4732,9 @@ def tamagawa_number(self, p): INPUT: - - p -- a prime number - - OUTPUT: + - ``p`` -- a prime number - - Integer + OUTPUT: integer EXAMPLES:: @@ -4843,19 +4772,19 @@ def tamagawa_number(self, p): def tamagawa_number_bounds(self, p): """ - Return a divisor and multiple of the Tamagawa number of self at `p`. + Return a divisor and multiple of the Tamagawa number of ``self`` at `p`. NOTE: the input abelian variety must be simple. INPUT: - - `p` -- a prime number + - ``p`` -- a prime number OUTPUT: - - div -- integer; divisor of Tamagawa number at `p` - - mul -- integer; multiple of Tamagawa number at `p` - - mul_primes -- tuple; in case mul==0, a list of all + - ``div`` -- integer; divisor of Tamagawa number at `p` + - ``mul`` -- integer; multiple of Tamagawa number at `p` + - ``mul_primes`` -- tuple; in case ``mul==0``, a list of all primes that can possibly divide the Tamagawa number at `p` EXAMPLES:: @@ -4913,18 +4842,16 @@ def tamagawa_number_bounds(self, p): def brandt_module(self, p): """ - Return the Brandt module at p that corresponds to self. This + Return the Brandt module at p that corresponds to ``self``. This is the factor of the vector space on the ideal class set in an - order of level N in the quaternion algebra ramified at p and + order of level `N` in the quaternion algebra ramified at `p` and infinity. INPUT: - - p -- prime that exactly divides the level - - OUTPUT: + - ``p`` -- prime that exactly divides the level - - Brandt module space that corresponds to self. + OUTPUT: Brandt module space that corresponds to self EXAMPLES:: @@ -4985,7 +4912,7 @@ def sqrt_poly(f): """ Return the square root of the polynomial `f`. - .. note:: + .. NOTE:: At some point something like this should be a member of the polynomial class. For now this is just used internally by some @@ -5027,13 +4954,11 @@ def random_hecke_operator(M, t=None, p=2): INPUT: + - ``M`` -- modular symbols space - - ``M`` -- modular symbols space - - - ``t`` -- None or a Hecke operator - - - ``p`` -- a prime + - ``t`` -- ``None`` or a Hecke operator + - ``p`` -- a prime OUTPUT: Hecke operator prime @@ -5062,9 +4987,7 @@ def factor_new_space(M): INPUT: - - - ``M`` -- modular symbols space - + - ``M`` -- modular symbols space OUTPUT: list of factors @@ -5101,7 +5024,7 @@ def factor_modsym_space_new_factors(M): - ``M`` -- ambient modular symbols space - OUTPUT: list of decompositions corresponding to each new space. + OUTPUT: list of decompositions corresponding to each new space EXAMPLES:: @@ -5202,12 +5125,9 @@ def modsym_lattices(M, factors): INPUT: + - ``M`` -- modular symbols spaces - - ``M`` -- modular symbols spaces - - - ``factors`` -- Sequence - (simple_factorization_of_modsym_space) - + - ``factors`` -- sequence (simple_factorization_of_modsym_space) OUTPUT: sequence with more information for each factor (the lattice) diff --git a/src/sage/modular/abvar/abvar_ambient_jacobian.py b/src/sage/modular/abvar/abvar_ambient_jacobian.py index 115408441fd..a25d82d5b8c 100644 --- a/src/sage/modular/abvar/abvar_ambient_jacobian.py +++ b/src/sage/modular/abvar/abvar_ambient_jacobian.py @@ -36,9 +36,7 @@ def ModAbVar_ambient_jacobian(group): INPUT: - - - ``group`` -- a congruence subgroup. - + - ``group`` -- a congruence subgroup OUTPUT: a modular abelian variety attached @@ -123,7 +121,7 @@ def _repr_(self): Abelian variety J0(11) of dimension 1 sage: A._repr_() 'Abelian variety J0(11) of dimension 1' - sage: A.rename("J_0(11)") + sage: A.rename('J_0(11)') sage: A J_0(11) @@ -156,9 +154,9 @@ def _latex_(self): def ambient_variety(self): """ - Return the ambient modular abelian variety that contains self. - Since self is a Jacobian modular abelian variety, this is just - self. + Return the ambient modular abelian variety that contains ``self``. + Since ``self`` is a Jacobian modular abelian variety, this is just + ``self``. OUTPUT: abelian variety @@ -206,7 +204,7 @@ def groups(self): def _calculate_endomorphism_generators(self): """ - Calculate generators for the endomorphism ring of self. + Calculate generators for the endomorphism ring of ``self``. EXAMPLES:: @@ -250,21 +248,20 @@ def _calculate_endomorphism_generators(self): def degeneracy_map(self, level, t=1, check=True): """ - Return the t-th degeneracy map from self to J(level). Here t must - be a divisor of either level/self.level() or self.level()/level. + Return the `t`-th degeneracy map from ``self`` to ``J(level)``. Here + `t` must be a divisor of either ``level/self.level()`` or + ``self.level()/level``. INPUT: + - ``level`` -- integer (multiple or divisor of level of + ``self``) - - ``level`` -- integer (multiple or divisor of level of - self) - - - ``t`` -- divisor of quotient of level of self and - level - - - ``check`` -- bool (default: ``True``); if True do some - checks on the input + - ``t`` -- divisor of quotient of level of ``self`` and + level + - ``check`` -- boolean (default: ``True``); if ``True`` do some + checks on the input OUTPUT: a morphism @@ -396,11 +393,9 @@ def decomposition(self, simple=True, bound=None): def newform_decomposition(self, names=None): """ Return the newforms of the simple subvarieties in the decomposition of - self as a product of simple subvarieties, up to isogeny. - - OUTPUT: + ``self`` as a product of simple subvarieties, up to isogeny. - - an array of newforms + OUTPUT: an array of newforms EXAMPLES:: diff --git a/src/sage/modular/abvar/abvar_newform.py b/src/sage/modular/abvar/abvar_newform.py index 8997ab01fdf..1159de73894 100644 --- a/src/sage/modular/abvar/abvar_newform.py +++ b/src/sage/modular/abvar/abvar_newform.py @@ -36,7 +36,8 @@ def __init__(self, f, internal_name=False): newform `f`. INPUT: - f -- a newform + + - ``f`` -- a newform EXAMPLES:: @@ -123,9 +124,7 @@ def label(self) -> str: Return canonical label that defines this newform modular abelian variety. - OUTPUT: - - string + OUTPUT: string EXAMPLES:: @@ -146,9 +145,7 @@ def factor_number(self): """ Return factor number. - OUTPUT: - - int + OUTPUT: int EXAMPLES:: diff --git a/src/sage/modular/abvar/constructor.py b/src/sage/modular/abvar/constructor.py index e4ba65049e4..a39f7819393 100644 --- a/src/sage/modular/abvar/constructor.py +++ b/src/sage/modular/abvar/constructor.py @@ -25,14 +25,12 @@ def _get(key): """ - Returns the cached abelian variety with given key. This is used + Return the cached abelian variety with given key. This is used internally by the abelian varieties constructor. INPUT: - - - ``key`` -- hashable - + - ``key`` -- hashable EXAMPLES:: @@ -53,23 +51,17 @@ def _get(key): def _saved(key, J): """ - Returns the cached abelian variety with given key. This is used + Return the cached abelian variety with given key. This is used internally by the abelian varieties constructor. INPUT: + - ``key`` -- hashable - - ``key`` -- hashable - - - ``J`` -- modular abelian variety - - - OUTPUT: - - - - ``J`` -- returns the modabvar, to make code that uses - this simpler + - ``J`` -- modular abelian variety + OUTPUT: ``J`` -- returns the modabvar, to make code that uses + this simpler EXAMPLES:: @@ -144,10 +136,8 @@ def AbelianVariety(X): INPUT: - - - ``X`` -- an integer, string, newform, modsym space, - congruence subgroup or tuple of congruence subgroups - + - ``X`` -- integer, string, newform, modsym space, + congruence subgroup or tuple of congruence subgroups OUTPUT: a modular abelian variety diff --git a/src/sage/modular/abvar/cuspidal_subgroup.py b/src/sage/modular/abvar/cuspidal_subgroup.py index 1cff9c4704e..c50a2b109f8 100644 --- a/src/sage/modular/abvar/cuspidal_subgroup.py +++ b/src/sage/modular/abvar/cuspidal_subgroup.py @@ -87,16 +87,10 @@ def _compute_lattice(self, rational_only=False, rational_subgroup=False): INPUT: + - ``rational_only`` -- boolean (default: ``False``); if + ``True``, only use rational cusps - - ``rational_only`` -- bool (default: ``False``); if - ``True``, only use rational cusps. - - - OUTPUT: - - - - ``list`` -- list of vectors - + OUTPUT: list of vectors EXAMPLES:: @@ -216,9 +210,7 @@ def lattice(self): Returned cached tuple of vectors that define elements of the rational homology that generate this finite subgroup. - OUTPUT: - - - ``tuple`` -- cached + OUTPUT: tuple (cached) EXAMPLES:: @@ -347,21 +339,18 @@ def lattice(self): def is_rational_cusp_gamma0(c, N, data): """ - Return True if the rational number c is a rational cusp of level N. + Return ``True`` if the rational number c is a rational cusp of level N. This uses remarks in Glenn Steven's Ph.D. thesis. INPUT: + - ``c`` -- a cusp - - ``c`` -- a cusp - - - ``N`` -- a positive integer - - - ``data`` -- the list [n for n in range(2,N) if - gcd(n,N) == 1], which is passed in as a parameter purely for - efficiency reasons. + - ``N`` -- positive integer + - ``data`` -- the list [n for n in range(2,N) if gcd(n,N) == 1], which is + passed in as a parameter purely for efficiency reasons. EXAMPLES:: diff --git a/src/sage/modular/abvar/finite_subgroup.py b/src/sage/modular/abvar/finite_subgroup.py index 0adc5ce3134..347e45fa418 100644 --- a/src/sage/modular/abvar/finite_subgroup.py +++ b/src/sage/modular/abvar/finite_subgroup.py @@ -328,7 +328,7 @@ def exponent(self): """ Return the exponent of this finite abelian group. - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -352,9 +352,7 @@ def intersection(self, other): INPUT: - - - ``other`` -- a finite group - + - ``other`` -- a finite group OUTPUT: a finite group @@ -440,17 +438,15 @@ def intersection(self, other): def __mul__(self, right): """ - Multiply this subgroup by the rational number right. + Multiply this subgroup by the rational number ``right``. - If right is an integer the result is a subgroup of self. If right - is a rational number `n/m`, then this group is first + If ``right`` is an integer the result is a subgroup of ``self``. If + ``right`` is a rational number `n/m`, then this group is first divided by `m` then multiplied by `n`. INPUT: - - - ``right`` -- a rational number - + - ``right`` -- a rational number OUTPUT: a subgroup @@ -611,7 +607,7 @@ def gens(self): def gen(self, n): r""" - Return `n^{th}` generator of self. + Return `n`-th generator of ``self``. EXAMPLES:: @@ -687,7 +683,6 @@ def _element_constructor_(self, x, check=True): Traceback (most recent call last): ... ValueError: ambient abelian varieties are different - """ if isinstance(x, TorsionPoint): if x.parent().abelian_variety() != self.abelian_variety(): @@ -847,18 +842,15 @@ def __init__(self, abvar, lattice, field_of_definition=None, check=True): INPUT: + - ``abvar`` -- a modular abelian variety - - ``abvar`` -- a modular abelian variety - - - ``lattice`` -- a lattice that contains the lattice of - abvar - - - ``field_of_definition`` -- the field of definition - of this finite group scheme + - ``lattice`` -- a lattice that contains the lattice of abvar - - ``check`` -- bool (default: ``True``) whether or not to - check that lattice contains the abvar lattice. + - ``field_of_definition`` -- the field of definition + of this finite group scheme + - ``check`` -- boolean (default: ``True``); whether or not to + check that lattice contains the abvar lattice EXAMPLES:: diff --git a/src/sage/modular/abvar/homology.py b/src/sage/modular/abvar/homology.py index 6a2b906fd1e..21a129072fa 100644 --- a/src/sage/modular/abvar/homology.py +++ b/src/sage/modular/abvar/homology.py @@ -69,16 +69,16 @@ class Homology(HeckeModule_free_module): action. """ def hecke_polynomial(self, n, var='x'): - """ - Return the n-th Hecke polynomial in the given variable. + r""" + Return the `n`-th Hecke polynomial in the given variable. INPUT: - - ``n`` -- positive integer + - ``n`` -- positive integer - - ``var`` -- string (default: 'x') the variable name + - ``var`` -- string (default: ``'x'``); the variable name - OUTPUT: a polynomial over ZZ in the given variable + OUTPUT: a polynomial over `\ZZ` in the given variable EXAMPLES:: @@ -142,7 +142,7 @@ def __richcmp__(self, other, op): def _repr_(self): """ - Return string representation of self. This must be defined in the + Return string representation of ``self``. This must be defined in the derived class. EXAMPLES:: @@ -158,7 +158,7 @@ def _repr_(self): def gens(self): """ - Return generators of self. + Return generators of ``self``. This is not yet implemented! @@ -174,7 +174,7 @@ def gens(self): def gen(self, n): """ - Return `n^{th}` generator of self. + Return `n`-th generator of ``self``. This is not yet implemented! @@ -248,14 +248,12 @@ def hecke_bound(self): def hecke_matrix(self, n): """ - Return the matrix of the n-th Hecke operator acting on this + Return the matrix of the `n`-th Hecke operator acting on this homology group. INPUT: - - - ``n`` -- a positive integer - + - ``n`` -- positive integer OUTPUT: a matrix over the coefficient ring of this homology group @@ -299,14 +297,13 @@ def submodule(self, U, check=True): INPUT: + - ``U`` -- submodule of ambient free module (or + something that defines one) - - ``U`` -- submodule of ambient free module (or - something that defines one) + - ``check`` -- currently ignored - - ``check`` -- currently ignored. - - .. note:: + .. NOTE:: We do *not* check that U is invariant under all Hecke operators. @@ -347,9 +344,7 @@ def __init__(self, abvar): INPUT: - - - ``abvar`` -- a modular abelian variety - + - ``abvar`` -- a modular abelian variety EXAMPLES:: @@ -378,7 +373,7 @@ def _repr_(self): def hecke_matrix(self, n): """ - Return the matrix of the n-th Hecke operator acting on this + Return the matrix of the `n`-th Hecke operator acting on this homology group. EXAMPLES:: @@ -398,7 +393,7 @@ def hecke_matrix(self, n): def hecke_polynomial(self, n, var='x'): """ - Return the n-th Hecke polynomial on this integral homology group. + Return the `n`-th Hecke polynomial on this integral homology group. EXAMPLES:: @@ -425,9 +420,7 @@ def __init__(self, abvar): INPUT: - - - ``abvar`` -- a modular abelian variety - + - ``abvar`` -- a modular abelian variety EXAMPLES:: @@ -454,7 +447,7 @@ def _repr_(self): def hecke_matrix(self, n): """ - Return the matrix of the n-th Hecke operator acting on this + Return the matrix of the `n`-th Hecke operator acting on this homology group. EXAMPLES:: @@ -479,7 +472,7 @@ def hecke_matrix(self, n): def hecke_polynomial(self, n, var='x'): """ - Return the n-th Hecke polynomial on this rational homology group. + Return the `n`-th Hecke polynomial on this rational homology group. EXAMPLES:: @@ -506,11 +499,9 @@ def __init__(self, abvar, base_ring): INPUT: + - ``abvar`` -- a modular abelian variety - - ``abvar`` -- a modular abelian variety - - - ``base_ring`` -- a commutative ring - + - ``base_ring`` -- a commutative ring EXAMPLES:: @@ -528,7 +519,7 @@ def __init__(self, abvar, base_ring): def _repr_(self): """ - Return string representation of self. + Return string representation of ``self``. EXAMPLES:: @@ -540,7 +531,7 @@ def _repr_(self): def hecke_matrix(self, n): """ - Return the matrix of the n-th Hecke operator acting on this + Return the matrix of the `n`-th Hecke operator acting on this homology group. EXAMPLES:: @@ -567,13 +558,11 @@ def __init__(self, ambient, submodule): INPUT: + - ``ambient`` -- the homology of some modular abelian + variety with ring coefficients - - ``ambient`` -- the homology of some modular abelian - variety with ring coefficients - - - ``submodule`` -- a submodule of the free module - underlying ambient - + - ``submodule`` -- a submodule of the free module + underlying ambient EXAMPLES:: diff --git a/src/sage/modular/abvar/homspace.py b/src/sage/modular/abvar/homspace.py index 8b97e675be5..2333bbacd00 100644 --- a/src/sage/modular/abvar/homspace.py +++ b/src/sage/modular/abvar/homspace.py @@ -210,11 +210,9 @@ def __init__(self, domain, codomain, cat): INPUT: + - ``domain, codomain`` -- modular abelian varieties - - ``domain, codomain`` -- modular abelian varieties - - - ``cat`` -- category - + - ``cat`` -- category EXAMPLES:: @@ -409,10 +407,7 @@ def _get_matrix(self, g): INPUT: - - - ``g`` -- a matrix or morphism or object with a list - method - + - ``g`` -- a matrix or morphism or object with a list method OUTPUT: a matrix @@ -482,11 +477,11 @@ def free_module(self): def gen(self, i=0): """ - Return i-th generator of ``self``. + Return `i`-th generator of ``self``. INPUT: - - ``i`` -- an integer + - ``i`` -- integer OUTPUT: a morphism @@ -588,8 +583,8 @@ def _calculate_product_gens(self): """ For internal use. - Calculate generators for self, assuming that self is a product of - simple factors. + Calculate generators for ``self``, assuming that ``self`` is a product + of simple factors. EXAMPLES:: @@ -759,10 +754,10 @@ def __init__(self, A, gens=None, category=None): INPUT: - - ``A`` -- an abelian variety + - ``A`` -- an abelian variety - - ``gens`` -- (default: ``None``); optional; if given - should be a tuple of the generators as matrices + - ``gens`` -- (default: ``None``) if given + should be a tuple of the generators as matrices EXAMPLES:: @@ -854,11 +849,11 @@ def index_in(self, other, check=True): INPUT: - - ``other`` -- another endomorphism subring of the - same abelian variety + - ``other`` -- another endomorphism subring of the + same abelian variety - - ``check`` -- bool (default: ``True``); whether to do some - type and other consistency checks + - ``check`` -- boolean (default: ``True``); whether to do some + type and other consistency checks EXAMPLES:: @@ -907,7 +902,7 @@ def discriminant(self): Return the discriminant of this ring, which is the discriminant of the trace pairing. - .. note:: + .. NOTE:: One knows that for modular abelian varieties, the endomorphism ring should be isomorphic to an order in a @@ -947,14 +942,12 @@ def image_of_hecke_algebra(self, check_every=1): INPUT: - - ``check_every`` -- integer (default: 1) If this integer is positive, + - ``check_every`` -- integer (default: 1); if this integer is positive, this integer determines how many Hecke operators we add in before checking to see if the submodule spanned so far is maximal and - saturated. - - OUTPUT: + saturated - - The image of the Hecke algebra as a subring of ``self``. + OUTPUT: the image of the Hecke algebra as a subring of ``self`` EXAMPLES:: diff --git a/src/sage/modular/abvar/lseries.py b/src/sage/modular/abvar/lseries.py index 4d67f7b2dfd..e71e58bbcde 100644 --- a/src/sage/modular/abvar/lseries.py +++ b/src/sage/modular/abvar/lseries.py @@ -41,7 +41,7 @@ class Lseries(SageObject): """ def __init__(self, abvar): """ - Called when creating an L-series. + Called when creating an `L`-series. INPUT: @@ -60,9 +60,7 @@ def abelian_variety(self): """ Return the abelian variety that this `L`-series is attached to. - OUTPUT: - - a modular abelian variety + OUTPUT: a modular abelian variety EXAMPLES:: @@ -90,12 +88,10 @@ def __call__(self, s, prec=53): - ``s`` -- complex number - - ``prec`` -- integer (default: 53) the number of bits of precision - used in computing the lseries of the newforms. - - OUTPUT: + - ``prec`` -- integer (default: 53); the number of bits of precision + used in computing the lseries of the newforms - a complex number L(A, s). + OUTPUT: a complex number L(A, s) EXAMPLES:: @@ -124,7 +120,6 @@ def __call__(self, s, prec=53): sage: L = JH(17,[2]).lseries() sage: L(1) # needs sage.symbolic 0.386769938387780 - """ abelian_variety = self.abelian_variety() # Check for easy dimension zero case @@ -155,9 +150,7 @@ def __eq__(self, other): - ``other`` -- object - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -180,9 +173,7 @@ def __ne__(self, other): - ``other`` -- object - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -199,9 +190,7 @@ def _repr_(self): """ String representation of `L`-series. - OUTPUT: - - a string + OUTPUT: string EXAMPLES:: @@ -213,11 +202,9 @@ def _repr_(self): def vanishes_at_1(self): """ - Return True if `L(1)=0` and return False otherwise. + Return ``True`` if `L(1)=0` and return ``False`` otherwise. - OUTPUT: - - a boolean + OUTPUT: boolean EXAMPLES: @@ -272,9 +259,7 @@ def rational_part(self): Return the rational part of this `L`-function at the central critical value 1. - OUTPUT: - - a rational number + OUTPUT: a rational number EXAMPLES:: @@ -335,11 +320,9 @@ def __eq__(self, other): INPUT: - other -- object - - OUTPUT: + - ``other`` -- object - boolean + OUTPUT: boolean EXAMPLES:: @@ -364,11 +347,9 @@ def __ne__(self, other): INPUT: - other -- object - - OUTPUT: + - ``other`` -- object - boolean + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/modular/abvar/morphism.py b/src/sage/modular/abvar/morphism.py index 3b3db9e30c8..ccf87e302e7 100644 --- a/src/sage/modular/abvar/morphism.py +++ b/src/sage/modular/abvar/morphism.py @@ -90,7 +90,7 @@ def _repr_type(self): def complementary_isogeny(self): """ - Returns the complementary isogeny of self. + Return the complementary isogeny of ``self``. EXAMPLES:: @@ -119,7 +119,7 @@ def complementary_isogeny(self): def is_isogeny(self): """ - Return True if this morphism is an isogeny of abelian varieties. + Return ``True`` if this morphism is an isogeny of abelian varieties. EXAMPLES:: @@ -135,16 +135,14 @@ def is_isogeny(self): def cokernel(self): """ - Return the cokernel of self. + Return the cokernel of ``self``. OUTPUT: + - ``A`` -- an abelian variety (the cokernel) - - ``A`` -- an abelian variety (the cokernel) - - - ``phi`` -- a quotient map from self.codomain() to the - cokernel of self - + - ``phi`` -- a quotient map from ``self.codomain()`` to the + cokernel of self EXAMPLES:: @@ -192,12 +190,9 @@ def kernel(self): OUTPUT: + - ``G`` -- a finite group - - ``G`` -- a finite group - - - ``A`` -- an abelian variety (identity component of - the kernel) - + - ``A`` -- an abelian variety (identity component of the kernel) EXAMPLES: We compute the kernel of a projection map. Notice that the kernel has a nontrivial abelian variety part. @@ -249,7 +244,7 @@ def kernel(self): def factor_out_component_group(self): r""" - View self as a morphism `f:A \to B`. Then `\ker(f)` + View ``self`` as a morphism `f:A \to B`. Then `\ker(f)` is an extension of an abelian variety `C` by a finite component group `G`. This function constructs a morphism `g` with domain `A` and codomain Q isogenous to @@ -368,10 +363,7 @@ def __call__(self, X): """ INPUT: - - - ``X`` -- abelian variety, finite group, or torsion - element - + - ``X`` -- abelian variety, finite group, or torsion element OUTPUT: abelian variety, finite group, torsion element @@ -467,9 +459,7 @@ def _image_of_element(self, x): INPUT: - - - ``x`` -- a torsion point on an abelian variety - + - ``x`` -- a torsion point on an abelian variety OUTPUT: a torsion point @@ -518,9 +508,7 @@ def _image_of_finite_subgroup(self, G): - ``G`` -- a finite subgroup of the domain of ``self`` - OUTPUT: - - A finite subgroup of the codomain. + OUTPUT: a finite subgroup of the codomain EXAMPLES:: @@ -555,9 +543,7 @@ def _image_of_abvar(self, A): INPUT: - - - ``A`` -- an abelian variety - + - ``A`` -- an abelian variety OUTPUT an abelian variety @@ -615,7 +601,7 @@ class Morphism(Morphism_abstract, sage.modules.matrix_morphism.MatrixMorphism): def restrict_domain(self, sub): """ - Restrict self to the subvariety sub of self.domain(). + Restrict ``self`` to the subvariety sub of ``self.domain()``. EXAMPLES:: @@ -661,22 +647,18 @@ def restrict_domain(self, sub): class DegeneracyMap(Morphism): - def __init__(self, parent, A, t, side="left"): + def __init__(self, parent, A, t, side='left'): """ Create the degeneracy map of index t in parent defined by the matrix A. INPUT: + - ``parent`` -- a space of homomorphisms of abelian varieties - - ``parent`` -- a space of homomorphisms of abelian - varieties - - - ``A`` -- a matrix defining self - - - ``t`` -- a list of indices defining the degeneracy - map + - ``A`` -- a matrix defining self + - ``t`` -- list of indices defining the degeneracy map EXAMPLES:: @@ -692,7 +674,7 @@ def __init__(self, parent, A, t, side="left"): def t(self): """ - Return the list of indices defining self. + Return the list of indices defining ``self``. EXAMPLES:: @@ -708,7 +690,7 @@ def t(self): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -722,18 +704,16 @@ class HeckeOperator(Morphism): """ A Hecke operator acting on a modular abelian variety. """ - def __init__(self, abvar, n, side="left"): + def __init__(self, abvar, n, side='left'): """ Create the Hecke operator of index `n` acting on the abelian variety abvar. INPUT: + - ``abvar`` -- a modular abelian variety - - ``abvar`` -- a modular abelian variety - - - ``n`` -- a positive integer - + - ``n`` -- positive integer EXAMPLES:: @@ -768,14 +748,11 @@ def _repr_(self): def index(self): """ Return the index of this Hecke operator. (For example, if this is - the operator `T_n`, then the index is the integer - `n`.) + the operator `T_n`, then the index is the integer `n`.) OUTPUT: - - - ``n`` -- a (Sage) Integer - + - ``n`` -- a (Sage) Integer EXAMPLES:: @@ -822,11 +799,9 @@ def characteristic_polynomial(self, var='x'): INPUT: + - ``var`` -- string (default: ``'x'``) - - ``var`` -- a string (default: 'x') - - - OUTPUT: a polynomial in var over the rational numbers. + OUTPUT: a polynomial in var over the rational numbers EXAMPLES:: @@ -851,9 +826,7 @@ def charpoly(self, var='x'): INPUT: - - - ``var`` -- string (default: 'x') - + - ``var`` -- string (default: ``'x'``) EXAMPLES:: @@ -917,9 +890,8 @@ def action_on_homology(self, R=ZZ): def matrix(self): r""" - Return the matrix of self acting on the homology - `H_1(A, ZZ)` of this abelian variety with coefficients in - `\ZZ`. + Return the matrix of ``self`` acting on the homology + `H_1(A, ZZ)` of this abelian variety with coefficients in `\ZZ`. EXAMPLES:: diff --git a/src/sage/modular/abvar/torsion_point.py b/src/sage/modular/abvar/torsion_point.py index 23e66c2197c..51c889f1bb5 100644 --- a/src/sage/modular/abvar/torsion_point.py +++ b/src/sage/modular/abvar/torsion_point.py @@ -33,7 +33,7 @@ class TorsionPoint(ModuleElement): - ``element`` -- a `\QQ`-vector space element that represents this element in terms of the ambient rational homology - - ``check`` -- bool (default: ``True``): whether to check that + - ``check`` -- boolean (default: ``True``); whether to check that element is in the appropriate vector space EXAMPLES: @@ -97,7 +97,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - .. note:: + .. NOTE:: Since they are represented as equivalences classes of rational homology modulo integral homology, we represent @@ -196,7 +196,7 @@ def _richcmp_(self, right, op): INPUT: - ``self``, ``right`` -- elements of the same finite abelian - variety subgroup. + variety subgroup - ``op`` -- comparison operator (see :mod:`sage.structure.richcmp`) diff --git a/src/sage/modular/abvar/torsion_subgroup.py b/src/sage/modular/abvar/torsion_subgroup.py index 4b434c54c7e..516acf5f7fd 100644 --- a/src/sage/modular/abvar/torsion_subgroup.py +++ b/src/sage/modular/abvar/torsion_subgroup.py @@ -115,9 +115,7 @@ def __init__(self, abvar): INPUT: - - - ``abvar`` -- a modular abelian variety - + - ``abvar`` -- a modular abelian variety EXAMPLES:: @@ -147,7 +145,7 @@ def __richcmp__(self, other, op): INPUT: - - ``other`` -- an object + - ``other`` -- an object If other is a torsion subgroup, the abelian varieties are compared. Otherwise, the generic behavior for finite abelian variety @@ -181,11 +179,9 @@ def order(self, proof=True): INPUT: - - ``proof`` -- a boolean (default: ``True``) - - OUTPUT: + - ``proof`` -- boolean (default: ``True``) - The order of this torsion subgroup. + OUTPUT: the order of this torsion subgroup EXAMPLES:: @@ -214,7 +210,6 @@ def order(self, proof=True): sage: J.rational_torsion_subgroup().order(proof=False) 408991 - """ O = self.possible_orders(proof=proof) if len(O) == 1: @@ -281,11 +276,9 @@ def possible_orders(self, proof=True): INPUT: - - ``proof`` -- a boolean (default: ``True``) - - OUTPUT: + - ``proof`` -- boolean (default: ``True``) - - an array of positive integers + OUTPUT: an array of positive integers The computation of the rational torsion order of J1(p) is conjectural and will only be used if ``proof=False``. See Section 6.2.3 of [CES2003]_. @@ -347,9 +340,7 @@ def divisor_of_order(self): Return a divisor of the order of this torsion subgroup of a modular abelian variety. - OUTPUT: - - A divisor of this torsion subgroup. + OUTPUT: a divisor of this torsion subgroup EXAMPLES:: @@ -414,7 +405,7 @@ def multiple_of_order(self, maxp=None, proof=True): INPUT: - - ``proof`` -- a boolean (default: ``True``) + - ``proof`` -- boolean (default: ``True``) The computation of the rational torsion order of J1(p) is conjectural and will only be used if proof=False. See Section 6.2.3 of [CES2003]_. @@ -496,13 +487,11 @@ def multiple_of_order_using_frobp(self, maxp=None): INPUT: - - - ``maxp`` -- (default: None) If maxp is None (the - default), return gcd of best bound computed so far with bound - obtained by computing GCD's of orders modulo p until this gcd - stabilizes for 3 successive primes. If maxp is given, just use all - primes up to and including maxp. - + - ``maxp`` -- (default: ``None``) if ``maxp`` is ``None``, return gcd + of best bound computed so far with bound obtained by computing GCD's + of orders modulo `p` until this gcd stabilizes for 3 successive + primes. If ``maxp`` is given, just use all primes up to and including + ``maxp``. EXAMPLES:: @@ -676,9 +665,7 @@ def __init__(self, abvar): INPUT: - - - ``abvar`` -- an abelian variety - + - ``abvar`` -- an abelian variety EXAMPLES:: diff --git a/src/sage/modular/arithgroup/arithgroup_element.pyx b/src/sage/modular/arithgroup/arithgroup_element.pyx index db914af629b..c47f4e453c3 100644 --- a/src/sage/modular/arithgroup/arithgroup_element.pyx +++ b/src/sage/modular/arithgroup/arithgroup_element.pyx @@ -43,7 +43,7 @@ cdef class ArithmeticSubgroupElement(MultiplicativeGroupElement): which lives in ``parent`` - ``check`` -- if ``True``, check that parent is an arithmetic - subgroup, and that `x` defines a matrix of determinant `1`. + subgroup, and that `x` defines a matrix of determinant `1` We tend not to create elements of arithmetic subgroups that are not SL2Z, in order to avoid coercion issues (that is, the other arithmetic @@ -159,8 +159,8 @@ cdef class ArithmeticSubgroupElement(MultiplicativeGroupElement): cpdef _richcmp_(self, right_r, int op): """ - Compare self to right, where right is guaranteed to have the same - parent as self. + Compare ``self`` to ``right``, where ``right`` is guaranteed to have + the same parent as ``self``. EXAMPLES:: @@ -205,7 +205,7 @@ cdef class ArithmeticSubgroupElement(MultiplicativeGroupElement): cpdef _mul_(self, right): """ - Return self * right. + Return ``self * right``. EXAMPLES:: diff --git a/src/sage/modular/arithgroup/arithgroup_generic.py b/src/sage/modular/arithgroup/arithgroup_generic.py index 8c7a32e2b5f..09d65934165 100644 --- a/src/sage/modular/arithgroup/arithgroup_generic.py +++ b/src/sage/modular/arithgroup/arithgroup_generic.py @@ -74,7 +74,7 @@ def __init__(self): def _repr_(self) -> str: r""" - Return the string representation of self. + Return the string representation of ``self``. NOTE: This function should be overridden by all subclasses. @@ -102,7 +102,7 @@ def _repr_option(self, key): def __reduce__(self): r""" - Used for pickling self. + Used for pickling ``self``. NOTE: This function should be overridden by all subclasses. @@ -119,8 +119,8 @@ def _element_constructor_(self, x, check=True): r""" Create an element of this congruence subgroup from x. - If the optional flag check is True (default), check whether - x actually gives an element of self. + If the optional flag check is ``True`` (default), check whether + x actually gives an element of ``self``. EXAMPLES:: @@ -183,7 +183,7 @@ def __contains__(self, x): def _contains_sl2(self, a,b,c,d): r""" Test whether the matrix [a,b;c,d], which may be assumed to have - determinant 1, is an element of self. This must be overridden by all + determinant 1, is an element of ``self``. This must be overridden by all subclasses. EXAMPLES:: @@ -198,7 +198,7 @@ def _contains_sl2(self, a,b,c,d): def __hash__(self): r""" - Return a hash of self. + Return a hash of ``self``. EXAMPLES:: @@ -254,12 +254,12 @@ def is_parent_of(self, x): def coset_reps(self, G=None): r""" - Return right coset representatives for self \\ G, where G is another - arithmetic subgroup that contains self. If G = None, default to G = - SL2Z. + Return right coset representatives for ``self \\ G``, where `G` is + another arithmetic subgroup that contains ``self``. If ``G == None``, + default to ``G = SL2Z``. - For generic arithmetic subgroups G this is carried out by Todd-Coxeter - enumeration; here G is treated as a black box, implementing nothing but + For generic arithmetic subgroups `G` this is carried out by Todd-Coxeter + enumeration; here `G` is treated as a black box, implementing nothing but membership testing. EXAMPLES:: @@ -279,7 +279,7 @@ def coset_reps(self, G=None): @cached_method def todd_coxeter(self, G=None, on_right=True): r""" - Compute coset representatives for self \\ G and action of standard + Compute coset representatives for ``self \\ G`` and action of standard generators on them via Todd-Coxeter enumeration. If ``G`` is ``None``, default to ``SL2Z``. The method also computes @@ -290,23 +290,21 @@ def todd_coxeter(self, G=None, on_right=True): - ``G`` -- intermediate subgroup (currently not implemented if different from SL(2,Z)) - - ``on_right`` -- boolean (default: ``True``); if True return right coset - enumeration, if False return left one. + - ``on_right`` -- boolean (default: ``True``); if ``True`` return right + coset enumeration, if ``False`` return left one This is *extremely* slow in general. - OUTPUT: - - - a list of coset representatives + OUTPUT: list of coset representatives - a list of generators for the group - ``l`` -- list of integers that correspond to the action of the standard parabolic element [[1,1],[0,1]] of `SL(2,\ZZ)` on the cosets - of self. + of ``self``. - ``s`` -- list of integers that correspond to the action of the standard - element of order `2` [[0,-1],[1,0]] on the cosets of self. + element of order `2` [[0,-1],[1,0]] on the cosets of ``self`` EXAMPLES:: @@ -518,10 +516,10 @@ def nu3(self): def is_abelian(self): r""" - Return True if this arithmetic subgroup is abelian. + Return ``True`` if this arithmetic subgroup is abelian. Since arithmetic subgroups are always nonabelian, this always - returns False. + returns ``False``. EXAMPLES:: @@ -538,10 +536,10 @@ def is_abelian(self): def is_finite(self): r""" - Return True if this arithmetic subgroup is finite. + Return ``True`` if this arithmetic subgroup is finite. Since arithmetic subgroups are always infinite, this always - returns False. + returns ``False``. EXAMPLES:: @@ -558,10 +556,10 @@ def is_finite(self): def is_subgroup(self, right): r""" - Return True if self is a subgroup of right, and False otherwise. For + Return ``True`` if ``self`` is a subgroup of right, and ``False`` otherwise. For generic arithmetic subgroups this is done by the absurdly slow - algorithm of checking all of the generators of self to see if they are - in right. + algorithm of checking all of the generators of ``self`` to see if they are + in ``right``. EXAMPLES:: @@ -582,7 +580,8 @@ def is_subgroup(self, right): def is_normal(self): r""" - Return True precisely if this subgroup is a normal subgroup of SL2Z. + Return ``True`` precisely if this subgroup is a normal subgroup of + ``SL2Z``. EXAMPLES:: @@ -599,7 +598,7 @@ def is_normal(self): def is_odd(self): r""" - Return True precisely if this subgroup does not contain the + Return ``True`` precisely if this subgroup does not contain the matrix -1. EXAMPLES:: @@ -617,7 +616,7 @@ def is_odd(self): def is_even(self): r""" - Return True precisely if this subgroup contains the matrix -1. + Return ``True`` precisely if this subgroup contains the matrix -1. EXAMPLES:: @@ -634,7 +633,7 @@ def is_even(self): def to_even_subgroup(self): r""" - Return the smallest even subgroup of `SL(2, \ZZ)` containing self. + Return the smallest even subgroup of `SL(2, \ZZ)` containing ``self``. EXAMPLES:: @@ -673,7 +672,7 @@ def reduce_cusp(self, c): r""" Given a cusp `c \in \mathbb{P}^1(\QQ)`, return the unique reduced cusp equivalent to c under the action of self, where a reduced cusp is an - element `\tfrac{r}{s}` with r,s coprime non-negative integers, s as + element `\tfrac{r}{s}` with r,s coprime nonnegative integers, s as small as possible, and r as small as possible for that s. NOTE: This function should be overridden by all subclasses. @@ -690,7 +689,7 @@ def reduce_cusp(self, c): def cusps(self, algorithm='default'): r""" Return a sorted list of inequivalent cusps for ``self``, i.e. a set of - representatives for the orbits of self on `\mathbb{P}^1(\QQ)`. + representatives for the orbits of ``self`` on `\mathbb{P}^1(\QQ)`. These should be returned in a reduced form where this makes sense. @@ -745,7 +744,7 @@ def _find_cusps(self): NotImplementedError NOTE: There is a generic algorithm implemented at the top level that - uses the coset representatives of self. This is *very slow* and for all + uses the coset representatives of ``self``. This is *very slow* and for all the standard congruence subgroups there is a quicker way of doing it, so this should usually be overridden in subclasses; but it doesn't have to be. @@ -765,13 +764,14 @@ def _find_cusps(self): def are_equivalent(self, x, y, trans=False): r""" - Test whether or not cusps x and y are equivalent modulo self. + Test whether or not cusps `x` and `y` are equivalent modulo ``self``. - If self has a reduce_cusp() method, use that; otherwise do a + If ``self`` has a ``reduce_cusp()`` method, use that; otherwise do a slow explicit test. - If trans = False, returns True or False. If trans = True, then return - either False or an element of self mapping x onto y. + If ``trans == False``, returns ``True`` or ``False``. If + ``trans == True``, then return either ``False`` or an element of + ``self`` mapping `x` onto `y`. EXAMPLES:: @@ -817,9 +817,9 @@ def are_equivalent(self, x, y, trans=False): def cusp_data(self, c): r""" - Return a triple (g, w, t) where g is an element of self generating the - stabiliser of the given cusp, w is the width of the cusp, and t is 1 if - the cusp is regular and -1 if not. + Return a triple `(g, w, t)` where `g` is an element of ``self`` + generating the stabiliser of the given cusp, `w` is the width of the + cusp, and `t` is 1 if the cusp is regular and -1 if not. EXAMPLES:: @@ -844,8 +844,9 @@ def cusp_data(self, c): def is_regular_cusp(self, c): r""" - Return True if the orbit of the given cusp is a regular cusp for self, - otherwise False. This is automatically true if -1 is in self. + Return ``True`` if the orbit of the given cusp is a regular cusp for + ``self``, otherwise ``False``. This is automatically true if -1 is in + ``self``. EXAMPLES:: @@ -875,7 +876,7 @@ def cusp_width(self, c): def index(self): r""" - Return the index of self in the full modular group. + Return the index of ``self`` in the full modular group. EXAMPLES:: @@ -923,11 +924,11 @@ def generalised_level(self): def projective_index(self): r""" - Return the index of the image of self in `\PSL_2(\ZZ)`. This is equal - to the index of self if self contains -1, and half of this otherwise. + Return the index of the image of ``self`` in `\PSL_2(\ZZ)`. This is equal + to the index of ``self`` if ``self`` contains -1, and half of this otherwise. This is equal to the degree of the natural map from the modular curve - of self to the `j`-line. + of ``self`` to the `j`-line. EXAMPLES:: @@ -944,7 +945,7 @@ def projective_index(self): def is_congruence(self): r""" - Return True if self is a congruence subgroup. + Return ``True`` if ``self`` is a congruence subgroup. EXAMPLES:: @@ -995,20 +996,20 @@ def farey_symbol(self): return Farey(self) @cached_method - def generators(self, algorithm="farey"): + def generators(self, algorithm='farey'): r""" Return a list of generators for this congruence subgroup. The result is cached. INPUT: - - ``algorithm`` (string): either ``farey`` or ``todd-coxeter``. + - ``algorithm`` -- string; either ``farey`` or ``todd-coxeter`` - If ``algorithm`` is set to ``"farey"``, then the generators will be + If ``algorithm`` is set to ``'farey'``, then the generators will be calculated using Farey symbols, which will always return a *minimal* generating set. See :mod:`~sage.modular.arithgroup.farey_symbol` for more information. - If ``algorithm`` is set to ``"todd-coxeter"``, a simpler algorithm + If ``algorithm`` is set to ``'todd-coxeter'``, a simpler algorithm based on Todd-Coxeter enumeration will be used. This is *exceedingly* slow for general subgroups, and the list of generators will be far from minimal (indeed it may contain repetitions). @@ -1020,7 +1021,7 @@ def generators(self, algorithm="farey"): [1 2] [ 3 -2] [-1 0] [0 1], [ 2 -1], [ 0 -1] ] - sage: Gamma(2).generators(algorithm="todd-coxeter") + sage: Gamma(2).generators(algorithm='todd-coxeter') [ [1 2] [-1 0] [ 1 0] [-1 0] [-1 2] [-1 0] [1 0] [0 1], [ 0 -1], [-2 1], [ 0 -1], [-2 3], [ 2 -1], [2 1] @@ -1051,8 +1052,8 @@ def gens(self, *args, **kwds) -> tuple: def gen(self, i): r""" - Return the i-th generator of self, i.e. the i-th element of the - tuple self.gens(). + Return the `i`-th generator of self, i.e. the `i`-th element of the + tuple ``self.gens()``. EXAMPLES:: @@ -1064,7 +1065,7 @@ def gen(self, i): def ngens(self): r""" - Return the size of the minimal generating set of self returned by + Return the size of the minimal generating set of ``self`` returned by :meth:`generators`. EXAMPLES:: @@ -1097,7 +1098,7 @@ def ncusps(self): def nregcusps(self): r""" - Return the number of cusps of self that are "regular", i.e. their + Return the number of cusps of ``self`` that are "regular", i.e. their stabiliser has a generator with both eigenvalues +1 rather than -1. If the group contains -1, every cusp is clearly regular. @@ -1110,7 +1111,7 @@ def nregcusps(self): def nirregcusps(self): r""" - Return the number of cusps of self that are "irregular", i.e. their + Return the number of cusps of ``self`` that are "irregular", i.e. their stabiliser can only be generated by elements with both eigenvalues -1 rather than +1. If the group contains -1, every cusp is clearly regular. @@ -1141,7 +1142,7 @@ def dimension_modular_forms(self, k=2): cases where one can prove solely via Riemann-Roch theory that there aren't any cusp forms (i.e. when the number of regular cusps is strictly greater than the degree of the canonical divisor). Otherwise a - NotImplementedError is raised. + :exc:`NotImplementedError` is raised. EXAMPLES:: @@ -1174,7 +1175,7 @@ def dimension_cusp_forms(self, k=2): where one can prove solely via Riemann-Roch theory that there aren't any cusp forms (i.e. when the number of regular cusps is strictly greater than the degree of the canonical divisor). Otherwise a - NotImplementedError is raised. + :exc:`NotImplementedError` is raised. EXAMPLES:: @@ -1228,7 +1229,7 @@ def dimension_eis(self, k=2): INPUT: - - ``k`` -- an integer (default 2). + - ``k`` -- integer (default: 2) EXAMPLES:: @@ -1305,12 +1306,12 @@ def as_permutation_group(self): def sturm_bound(self, weight=2): r""" - Returns the Sturm bound for modular forms of the given weight and level + Return the Sturm bound for modular forms of the given weight and level this subgroup. INPUT: - - ``weight`` -- an integer `\geq 2` (default: 2) + - ``weight`` -- integer `\geq 2` (default: 2) EXAMPLES:: diff --git a/src/sage/modular/arithgroup/arithgroup_perm.py b/src/sage/modular/arithgroup/arithgroup_perm.py index a084d46a33d..3431dfcac5c 100644 --- a/src/sage/modular/arithgroup/arithgroup_perm.py +++ b/src/sage/modular/arithgroup/arithgroup_perm.py @@ -32,7 +32,7 @@ interest: - `(l,r)` as they are also semigroup generators for the semigroup of matrices - in `\SL_2(\ZZ)` with non-negative entries, + in `\SL_2(\ZZ)` with nonnegative entries, - `(l,s_2)` as they are closely related to the continued fraction algorithm, - `(s_2,s_3)` as the group `\PSL_2(\ZZ)` is the free product of the finite cyclic groups generated by these two elements. @@ -312,10 +312,10 @@ def ArithmeticSubgroup_Permutation( - ``S2``, ``S3``, ``L``, ``R`` -- permutations; action of matrices on the right cosets (each coset is identified to an element of `\{1,\dots,n\}` - where `1` is reserved for the identity coset). + where `1` is reserved for the identity coset) - - ``relabel`` -- boolean (default: ``False``); if True, renumber the cosets in a - canonical way. + - ``relabel`` -- boolean (default: ``False``); if ``True``, renumber the cosets in a + canonical way - ``check`` -- boolean (default: ``True``); check that the input is valid (it may be time efficient but less safe to set it to False) @@ -575,7 +575,7 @@ def __hash__(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -683,7 +683,7 @@ def perm_group(self): def index(self): r""" - Returns the index of this modular subgroup in the full modular group. + Return the index of this modular subgroup in the full modular group. EXAMPLES:: @@ -853,7 +853,7 @@ def relabel(self, inplace=True): def _canonical_unrooted_labels(self): r""" - Returns the smallest label among rooted label + Return the smallest label among rooted label. OUTPUT: @@ -923,7 +923,7 @@ def _canonical_unrooted_labels(self): def _canonical_rooted_labels(self, j0=0): r""" - Return the permutation which correspond to the renumbering of self in + Return the permutation which correspond to the renumbering of ``self`` in order to get canonical labels. If ``j0`` is 0 then the renumbering corresponds to the same group. If @@ -1053,7 +1053,7 @@ def _contains_sl2(self, a,b,c,d): def random_element(self, initial_steps=30): r""" - Returns a random element in this subgroup. + Return a random element in this subgroup. The algorithm uses a random walk on the Cayley graph of `\SL_2(\ZZ)` stopped at the first time it reaches the subgroup after at least @@ -1096,7 +1096,7 @@ def random_element(self, initial_steps=30): def permutation_action(self, x): r""" Given an element ``x`` of `\SL_2(\ZZ)`, compute the permutation of the - cosets of self given by right multiplication by ``x``. + cosets of ``self`` given by right multiplication by ``x``. EXAMPLES:: @@ -1112,7 +1112,7 @@ def permutation_action(self, x): def is_normal(self): r""" - Test whether the group is normal + Test whether the group is normal. EXAMPLES:: @@ -1141,7 +1141,7 @@ def is_normal(self): def _conjugate(self,j0): r""" - Return the conjugate of self rooted at j0. + Return the conjugate of ``self`` rooted at j0. EXAMPLES:: @@ -1188,15 +1188,15 @@ def coset_graph(self, INPUT: - - ``right_cosets`` -- bool (default: ``False``); right or left coset graph + - ``right_cosets`` -- boolean (default: ``False``); right or left coset graph - - ``s2_edges`` -- bool (default: ``True``); put edges associated to s2 + - ``s2_edges`` -- boolean (default: ``True``); put edges associated to s2 - - ``s3_edges`` -- bool (default: ``True``); put edges associated to s3 + - ``s3_edges`` -- boolean (default: ``True``); put edges associated to s3 - - ``l_edges`` -- bool (default: ``False``); put edges associated to l + - ``l_edges`` -- boolean (default: ``False``); put edges associated to l - - ``r_edges`` -- bool (default: ``False``); put edges associated to r + - ``r_edges`` -- boolean (default: ``False``); put edges associated to r - ``s2_label``, ``s3_label``, ``l_label``, ``r_label`` -- the labels to put on the edges corresponding to the generators action. Use ``None`` @@ -1291,18 +1291,18 @@ def generalised_level(self): def congruence_closure(self): r""" - Returns the smallest congruence subgroup containing self. If self is + Return the smallest congruence subgroup containing ``self``. If ``self`` is congruence, this is just self, but represented as a congruence subgroup - data type. If self is not congruence, then it may be larger. + data type. If ``self`` is not congruence, then it may be larger. In practice, we use the following criterion: let `m` be the generalised - level of self. If this subgroup is even, let `n = m`, else let `n = - 2m`. Then any congruence subgroup containing self contains `\Gamma(n)` + level of ``self``. If this subgroup is even, let `n = m`, else let `n = + 2m`. Then any congruence subgroup containing ``self`` contains `\Gamma(n)` (a generalisation of Wohlfahrt's theorem due to Kiming, Verrill and - Schuett). So we compute the image of self modulo `n` and return the + Schuett). So we compute the image of ``self`` modulo `n` and return the preimage of that. - .. note:: + .. NOTE:: If you just want to know if the subgroup is congruence or not, it is *much* faster to use :meth:`~is_congruence`. @@ -1603,7 +1603,7 @@ def __init__(self, S2, S3, L, R, canonical_labels=False): def __reduce__(self): r""" - Return the data used to construct self. Used in pickling. + Return the data used to construct ``self``. Used in pickling. TESTS:: @@ -1650,7 +1650,7 @@ def is_even(self): def to_even_subgroup(self,relabel=True): r""" - Returns the group with `-Id` added in it. + Return the group with `-Id` added in it. EXAMPLES:: @@ -1784,9 +1784,9 @@ def cusp_widths(self,exp=False): INPUT: - - ``exp`` -- boolean (default: ``False``) - if True, return a dictionary with - keys the possible widths and with values the number of cusp with that - width. + - ``exp`` -- boolean (default: ``False``); if ``True``, return a + dictionary with keys the possible widths and with values the number + of cusp with that width EXAMPLES:: @@ -1831,7 +1831,7 @@ def cusp_widths(self,exp=False): def ncusps(self): r""" - Returns the number of cusps. + Return the number of cusps. EXAMPLES:: @@ -1942,7 +1942,7 @@ def __reduce__(self): def is_odd(self): r""" - Returns True if this subgroup does not contain the matrix `-Id`. + Return ``True`` if this subgroup does not contain the matrix `-Id`. EXAMPLES:: @@ -1954,7 +1954,7 @@ def is_odd(self): def is_even(self): r""" - Returns True if this subgroup contains the matrix `-Id`. + Return ``True`` if this subgroup contains the matrix `-Id`. EXAMPLES:: @@ -1966,7 +1966,7 @@ def is_even(self): def nu2(self): r""" - Returns the number of orbits of elliptic points of order 2 for this + Return the number of orbits of elliptic points of order 2 for this arithmetic subgroup. EXAMPLES:: @@ -1979,7 +1979,7 @@ def nu2(self): def nu3(self): r""" - Returns the number of orbits of elliptic points of order 3 for this + Return the number of orbits of elliptic points of order 3 for this arithmetic subgroup. EXAMPLES:: @@ -2016,7 +2016,7 @@ def _spanning_tree_kulkarni(self, root=0, on_right=True): INPUT: - ``on_right`` -- boolean (default: ``True``); if ``False``, - return spanning tree for the left cosets. + return spanning tree for the left cosets OUTPUT: @@ -2027,10 +2027,10 @@ def _spanning_tree_kulkarni(self, root=0, on_right=True): of the cosets with respect to the spanning tree - ``word_reps`` -- list of lists with ``s2`` and ``s3``; word - representatives of the cosets with respect to the spanning tree. + representatives of the cosets with respect to the spanning tree - ``gens`` -- list of 3-tuples ``(in,out,label)``; the list of edges in - the graph which are not in the spanning tree. + the graph which are not in the spanning tree EXAMPLES:: @@ -2156,10 +2156,10 @@ def _spanning_tree_verrill(self, root=0, on_right=True): cosets with respect to the spanning tree - ``word_reps`` -- list of string with ``s`` and ``l`` -- word - representatives of the cosets with respect to the spanning tree. + representatives of the cosets with respect to the spanning tree - ``gens`` -- list of 3-tuples ``(in,out,label)``; the list of edges in - the graph which are not in the spanning tree. + the graph which are not in the spanning tree EXAMPLES:: @@ -2274,7 +2274,7 @@ def _spanning_tree_verrill(self, root=0, on_right=True): def todd_coxeter_s2_s3(self): r""" - Returns a 4-tuple ``(coset_reps, gens, s2, s3)`` where ``coset_reps`` + Return a 4-tuple ``(coset_reps, gens, s2, s3)`` where ``coset_reps`` are coset representatives of the subgroup, ``gens`` is a list of generators, ``s2`` and ``s3`` are the action of the matrices `S2` and `S3` on the list of cosets. @@ -2319,7 +2319,7 @@ def todd_coxeter_s2_s3(self): def todd_coxeter_l_s2(self): r""" - Returns a 4-tuple ``(coset_reps, gens, l, s2)`` where ``coset_reps`` is + Return a 4-tuple ``(coset_reps, gens, l, s2)`` where ``coset_reps`` is a list of coset representatives of the subgroup, ``gens`` a list of generators, ``l`` and ``s2`` are list that corresponds to the action of the matrix `S2` and `L` on the cosets. @@ -2440,8 +2440,8 @@ def cusp_widths(self,exp=False): def to_even_subgroup(self, relabel=True): r""" - Return the subgroup generated by self and ``-Id``. Since self is even, - this is just self. Provided for compatibility. + Return the subgroup generated by ``self`` and ``-Id``. Since ``self`` is even, + this is just ``self``. Provided for compatibility. EXAMPLES:: diff --git a/src/sage/modular/arithgroup/congroup.pyx b/src/sage/modular/arithgroup/congroup.pyx index 002e3bb02da..ee988672a4f 100644 --- a/src/sage/modular/arithgroup/congroup.pyx +++ b/src/sage/modular/arithgroup/congroup.pyx @@ -52,9 +52,9 @@ def degeneracy_coset_representatives_gamma0(int N, int M, int t): INPUT: - - ``N`` -- int - - ``M`` -- int (divisor of `N`) - - ``t`` -- int (divisor of `N/M`) + - ``N`` -- integer + - ``M`` -- integer (divisor of `N`) + - ``t`` -- integer (divisor of `N/M`) OUTPUT: @@ -165,9 +165,9 @@ def degeneracy_coset_representatives_gamma1(int N, int M, int t): INPUT: - - ``N`` -- int - - ``M`` -- int (divisor of `N`) - - ``t`` -- int (divisor of `N/M`) + - ``N`` -- integer + - ``M`` -- integer (divisor of `N`) + - ``t`` -- integer (divisor of `N/M`) OUTPUT: @@ -288,7 +288,7 @@ def generators_helper(coset_reps, level): EXAMPLES:: - sage: Gamma0(7).generators(algorithm="todd-coxeter") # indirect doctest + sage: Gamma0(7).generators(algorithm='todd-coxeter') # indirect doctest [ [1 1] [-1 0] [ 1 -1] [1 0] [1 1] [-3 -1] [-2 -1] [-5 -1] [0 1], [ 0 -1], [ 0 1], [7 1], [0 1], [ 7 2], [ 7 3], [21 4], diff --git a/src/sage/modular/arithgroup/congroup_gamma.py b/src/sage/modular/arithgroup/congroup_gamma.py index 9a3a72589bf..2eec9b267ac 100644 --- a/src/sage/modular/arithgroup/congroup_gamma.py +++ b/src/sage/modular/arithgroup/congroup_gamma.py @@ -66,7 +66,7 @@ class Gamma_class(CongruenceSubgroup): """ def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -77,7 +77,7 @@ def _repr_(self): def _latex_(self): r""" - Return the \LaTeX representation of self. + Return the \LaTeX representation of ``self``. EXAMPLES:: @@ -90,7 +90,7 @@ def _latex_(self): def __reduce__(self): """ - Used for pickling self. + Used for pickling ``self``. EXAMPLES:: @@ -101,7 +101,7 @@ def __reduce__(self): def __richcmp__(self, other, op): r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -123,7 +123,7 @@ def __richcmp__(self, other, op): def index(self): r""" - Return the index of self in the full modular group. This is given by + Return the index of ``self`` in the full modular group. This is given by .. MATH:: @@ -178,7 +178,8 @@ def ncusps(self): def nirregcusps(self): r""" - Return the number of irregular cusps of self. For principal congruence subgroups this is always 0. + Return the number of irregular cusps of ``self``. For principal + congruence subgroups this is always 0. EXAMPLES:: @@ -245,7 +246,6 @@ def reduce_cusp(self, c): sage: Gamma(7).reduce_cusp(Cusp(6,7)) Infinity - """ N = self.level() c = Cusp(c) @@ -309,7 +309,7 @@ def image_mod_n(self): def is_Gamma(x): r""" - Return True if x is a congruence subgroup of type Gamma. + Return ``True`` if x is a congruence subgroup of type Gamma. EXAMPLES:: diff --git a/src/sage/modular/arithgroup/congroup_gamma0.py b/src/sage/modular/arithgroup/congroup_gamma0.py index cfa31675ffe..a01c1dd1683 100644 --- a/src/sage/modular/arithgroup/congroup_gamma0.py +++ b/src/sage/modular/arithgroup/congroup_gamma0.py @@ -26,7 +26,7 @@ def is_Gamma0(x): """ - Return True if x is a congruence subgroup of type Gamma0. + Return ``True`` if x is a congruence subgroup of type Gamma0. EXAMPLES:: @@ -110,7 +110,6 @@ class Gamma0_class(GammaH_class): Modular Symbols subspace of dimension 5 of Modular Symbols space of dimension 18 for Gamma_0(100) of weight 2 with sign 1 over Rational Field - """ def __init__(self, level): @@ -148,7 +147,7 @@ def __init__(self, level): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -159,7 +158,7 @@ def _repr_(self): def __reduce__(self): """ - Used for pickling self. + Used for pickling ``self``. EXAMPLES:: @@ -170,7 +169,7 @@ def __reduce__(self): def _latex_(self): r""" - Return the \LaTeX representation of self. + Return the \LaTeX representation of ``self``. EXAMPLES:: @@ -184,8 +183,8 @@ def _latex_(self): @cached_method def _generators_for_H(self): """ - Return generators for the subgroup H of the units mod - self.level() that defines self. + Return generators for the subgroup `H` of the units mod + ``self.level()`` that defines ``self``. EXAMPLES:: @@ -199,7 +198,7 @@ def _generators_for_H(self): @cached_method def _list_of_elements_in_H(self): """ - Returns a sorted list of Python ints that are representatives + Return a sorted list of Python ints that are representatives between 0 and N-1 of the elements of H. EXAMPLES:: @@ -245,10 +244,10 @@ def divisor_subgroups(self): def is_even(self): r""" - Return True precisely if this subgroup contains the matrix -1. + Return ``True`` precisely if this subgroup contains the matrix -1. Since `\Gamma0(N)` always contains the matrix -1, this always - returns True. + returns ``True``. EXAMPLES:: @@ -261,7 +260,7 @@ def is_even(self): def is_subgroup(self, right): """ - Return True if self is a subgroup of right. + Return ``True`` if ``self`` is a subgroup of ``right``. EXAMPLES:: @@ -331,21 +330,21 @@ def coset_reps(self): yield SL2Z(lift_to_sl2z(z[0], z[1], N)) @cached_method - def generators(self, algorithm="farey"): + def generators(self, algorithm='farey'): r""" Return generators for this congruence subgroup. INPUT: - - ``algorithm`` (string): either ``"farey"`` (default) or - ``"todd-coxeter"``. + - ``algorithm`` -- string; either ``'farey'`` (default) or + ``'todd-coxeter'`` - If ``algorithm`` is set to ``"farey"``, then the generators will be + If ``algorithm`` is set to ``'farey'``, then the generators will be calculated using Farey symbols, which will always return a *minimal* generating set. See :mod:`~sage.modular.arithgroup.farey_symbol` for more information. - If ``algorithm`` is set to ``"todd-coxeter"``, a simpler algorithm + If ``algorithm`` is set to ``'todd-coxeter'``, a simpler algorithm based on Todd-Coxeter enumeration will be used. This tends to return far larger sets of generators. @@ -356,7 +355,7 @@ def generators(self, algorithm="farey"): [1 1] [-1 1] [0 1], [-3 2] ] - sage: Gamma0(3).generators(algorithm="todd-coxeter") + sage: Gamma0(3).generators(algorithm='todd-coxeter') [ [1 1] [-1 0] [ 1 -1] [1 0] [1 1] [-1 0] [ 1 0] [0 1], [ 0 -1], [ 0 1], [3 1], [0 1], [ 3 -1], [-3 1] @@ -390,7 +389,7 @@ def generators(self, algorithm="farey"): def gamma_h_subgroups(self): r""" Return the subgroups of the form `\Gamma_H(N)` contained - in self, where `N` is the level of self. + in ``self``, where `N` is the level of ``self``. EXAMPLES:: @@ -446,9 +445,9 @@ def _contains_sl2(self, a,b,c,d): def _find_cusps(self): r""" Return an ordered list of inequivalent cusps for self, i.e. a - set of representatives for the orbits of self on + set of representatives for the orbits of ``self`` on `\mathbb{P}^1(\QQ)`. These are returned in a reduced - form; see self.reduce_cusp for the definition of reduced. + form; see ``self.reduce_cusp`` for the definition of reduced. ALGORITHM: Uses explicit formulae specific to `\Gamma_0(N)`: a reduced cusp on @@ -555,7 +554,7 @@ def nu3(self): def index(self): r""" - Return the index of self in the full modular group. + Return the index of ``self`` in the full modular group. This is given by @@ -579,12 +578,12 @@ def dimension_new_cusp_forms(self, k=2, p=0): INPUT: - - `k` -- an integer (default: 2), the weight. Not fully + - ``k`` -- integer (default: 2); the weight. Not fully implemented for `k = 1`. - - `p` -- integer (default: 0); if nonzero, compute the - `p`-new subspace. + - ``p`` -- integer (default: 0); if nonzero, compute the + `p`-new subspace - OUTPUT: Integer + OUTPUT: integer ALGORITHM: diff --git a/src/sage/modular/arithgroup/congroup_gamma1.py b/src/sage/modular/arithgroup/congroup_gamma1.py index 4f95a3a702d..18a1c8c0950 100644 --- a/src/sage/modular/arithgroup/congroup_gamma1.py +++ b/src/sage/modular/arithgroup/congroup_gamma1.py @@ -23,7 +23,7 @@ def is_Gamma1(x): """ - Return True if x is a congruence subgroup of type Gamma1. + Return ``True`` if x is a congruence subgroup of type Gamma1. EXAMPLES:: @@ -115,7 +115,7 @@ def __init__(self, level): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -126,7 +126,7 @@ def _repr_(self): def __reduce__(self): """ - Used for pickling self. + Used for pickling ``self``. EXAMPLES:: @@ -137,7 +137,7 @@ def __reduce__(self): def _latex_(self): r""" - Return the \LaTeX representation of self. + Return the \LaTeX representation of ``self``. EXAMPLES:: @@ -150,7 +150,7 @@ def _latex_(self): def is_even(self): """ - Return True precisely if this subgroup contains the matrix -1. + Return ``True`` precisely if this subgroup contains the matrix -1. EXAMPLES:: @@ -165,7 +165,7 @@ def is_even(self): def is_subgroup(self, right): """ - Return True if self is a subgroup of right. + Return ``True`` if ``self`` is a subgroup of ``right``. EXAMPLES:: @@ -192,21 +192,21 @@ def is_subgroup(self, right): raise NotImplementedError @cached_method - def generators(self, algorithm="farey"): + def generators(self, algorithm='farey'): r""" Return generators for this congruence subgroup. The result is cached. INPUT: - - ``algorithm`` (string): either ``farey`` (default) or - ``todd-coxeter``. + - ``algorithm`` -- string; either ``'farey'`` (default) or + ``'todd-coxeter'`` - If ``algorithm`` is set to ``"farey"``, then the generators will be + If ``algorithm`` is set to ``'farey'``, then the generators will be calculated using Farey symbols, which will always return a *minimal* generating set. See :mod:`~sage.modular.arithgroup.farey_symbol` for more information. - If ``algorithm`` is set to ``"todd-coxeter"``, a simpler algorithm + If ``algorithm`` is set to ``'todd-coxeter'``, a simpler algorithm based on Todd-Coxeter enumeration will be used. This tends to return far larger sets of generators. @@ -217,7 +217,7 @@ def generators(self, algorithm="farey"): [1 1] [ 1 -1] [0 1], [ 3 -2] ] - sage: Gamma1(3).generators(algorithm="todd-coxeter") + sage: Gamma1(3).generators(algorithm='todd-coxeter') [ [1 1] [-2 1] [1 1] [ 1 -1] [1 0] [1 1] [-5 2] [ 1 0] [0 1], [-3 1], [0 1], [ 0 1], [3 1], [0 1], [12 -5], [-3 1], @@ -320,7 +320,7 @@ def ncusps(self): def index(self): r""" - Return the index of self in the full modular group. This is given by the formula + Return the index of ``self`` in the full modular group. This is given by the formula .. MATH:: @@ -339,26 +339,26 @@ def index(self): # Dimension formulas for Gamma1, accepting a Dirichlet character as an argument. # ################################################################################## - def dimension_modular_forms(self, k=2, eps=None, algorithm="CohenOesterle"): + def dimension_modular_forms(self, k=2, eps=None, algorithm='CohenOesterle'): r""" - Return the dimension of the space of modular forms for self, or the + Return the dimension of the space of modular forms for ``self``, or the dimension of the subspace corresponding to the given character if one is supplied. INPUT: - - ``k`` -- an integer (default: 2), the weight. + - ``k`` -- integer (default: 2); the weight - - ``eps`` -- either None or a Dirichlet character modulo N, where N is - the level of this group. If this is None, then the dimension of the + - ``eps`` -- either ``None`` or a Dirichlet character modulo N, where N is + the level of this group. If this is ``None``, then the dimension of the whole space is returned; otherwise, the dimension of the subspace of forms of character eps. - - ``algorithm`` -- either "CohenOesterle" (the default) or "Quer". This - specifies the method to use in the case of nontrivial character: - either the Cohen--Oesterle formula as described in Stein's book, or - by Möbius inversion using the subgroups GammaH (a method due to - Jordi Quer). + - ``algorithm`` -- either ``'CohenOesterle'`` (the default) or + ``'Quer'``. This specifies the method to use in the case of + nontrivial character: either the Cohen--Oesterle formula as described + in Stein's book, or by Möbius inversion using the subgroups GammaH (a + method due to Jordi Quer). EXAMPLES:: @@ -368,7 +368,7 @@ def dimension_modular_forms(self, k=2, eps=None, algorithm="CohenOesterle"): sage: G = Gamma1(7*43) sage: G.dimension_modular_forms(2, eps) 32 - sage: G.dimension_modular_forms(2, eps, algorithm="Quer") + sage: G.dimension_modular_forms(2, eps, algorithm='Quer') 32 TESTS: @@ -381,16 +381,16 @@ def dimension_modular_forms(self, k=2, eps=None, algorithm="CohenOesterle"): sage: G = DirichletGroup(13, base_ring=K) sage: Gamma1(13).dimension_modular_forms(2, G[1]) 3 - sage: Gamma1(13).dimension_modular_forms(2, G[1], algorithm="Quer") + sage: Gamma1(13).dimension_modular_forms(2, G[1], algorithm='Quer') 3 sage: Gamma1(39).dimension_modular_forms(2, G[1]) 7 - sage: Gamma1(39).dimension_modular_forms(2, G[1], algorithm="Quer") + sage: Gamma1(39).dimension_modular_forms(2, G[1], algorithm='Quer') 7 """ return self.dimension_cusp_forms(k, eps, algorithm) + self.dimension_eis(k, eps, algorithm) - def dimension_cusp_forms(self, k=2, eps=None, algorithm="CohenOesterle"): + def dimension_cusp_forms(self, k=2, eps=None, algorithm='CohenOesterle'): r""" Return the dimension of the space of cusp forms for ``self``, or the dimension of the subspace corresponding to the given character if one @@ -398,18 +398,18 @@ def dimension_cusp_forms(self, k=2, eps=None, algorithm="CohenOesterle"): INPUT: - - ``k`` -- an integer (default: 2), the weight. + - ``k`` -- integer (default: 2); the weight - - ``eps`` -- either None or a Dirichlet character modulo N, where N is - the level of this group. If this is None, then the dimension of the + - ``eps`` -- either ``None`` or a Dirichlet character modulo N, where N is + the level of this group. If this is ``None``, then the dimension of the whole space is returned; otherwise, the dimension of the subspace of forms of character eps. - - ``algorithm`` -- either "CohenOesterle" (the default) or "Quer". This - specifies the method to use in the case of nontrivial character: - either the Cohen--Oesterle formula as described in Stein's book, or - by Möbius inversion using the subgroups GammaH (a method due to Jordi - Quer). Ignored for weight 1. + - ``algorithm`` -- either ``'CohenOesterle'`` (the default) or + ``'Quer'``. This specifies the method to use in the case of nontrivial + character: either the Cohen--Oesterle formula as described in Stein's + book, or by Möbius inversion using the subgroups GammaH (a method due + to Jordi Quer). Ignored for weight 1. EXAMPLES: @@ -427,7 +427,7 @@ def dimension_cusp_forms(self, k=2, eps=None, algorithm="CohenOesterle"): Via Quer's method:: - sage: Gamma1(7*43).dimension_cusp_forms(2, eps, algorithm="Quer") # needs sage.rings.number_field + sage: Gamma1(7*43).dimension_cusp_forms(2, eps, algorithm='Quer') # needs sage.rings.number_field 28 Some more examples:: @@ -490,7 +490,7 @@ def dimension_cusp_forms(self, k=2, eps=None, algorithm="CohenOesterle"): else: #algorithm not in ["CohenOesterle", "Quer"]: raise ValueError("Unrecognised algorithm in dimension_cusp_forms") - def dimension_eis(self, k=2, eps=None, algorithm="CohenOesterle"): + def dimension_eis(self, k=2, eps=None, algorithm='CohenOesterle'): r""" Return the dimension of the space of Eisenstein series forms for self, or the dimension of the subspace corresponding to the given character @@ -498,18 +498,18 @@ def dimension_eis(self, k=2, eps=None, algorithm="CohenOesterle"): INPUT: - - ``k`` -- an integer (default: 2), the weight. + - ``k`` -- integer (default: 2); the weight - - ``eps`` -- either None or a Dirichlet character modulo N, where N is - the level of this group. If this is None, then the dimension of the + - ``eps`` -- either ``None`` or a Dirichlet character modulo N, where N is + the level of this group. If this is ``None``, then the dimension of the whole space is returned; otherwise, the dimension of the subspace of Eisenstein series of character eps. - - ``algorithm`` -- either "CohenOesterle" (the default) or "Quer". This - specifies the method to use in the case of nontrivial character: - either the Cohen--Oesterle formula as described in Stein's book, or - by Möbius inversion using the subgroups GammaH (a method due to - Jordi Quer). + - ``algorithm`` -- either ``'CohenOesterle'`` (the default) or + ``'Quer'``. This specifies the method to use in the case of nontrivial + character: either the Cohen--Oesterle formula as described in Stein's + book, or by Möbius inversion using the subgroups GammaH (a method due + to Jordi Quer). AUTHORS: @@ -525,14 +525,14 @@ def dimension_eis(self, k=2, eps=None, algorithm="CohenOesterle"): sage: [Gamma1(36).dimension_eis(1,eps) for eps in DirichletGroup(36)] [0, 4, 3, 0, 0, 2, 6, 0, 0, 2, 3, 0] - sage: [Gamma1(36).dimension_eis(1,eps,algorithm="Quer") for eps in DirichletGroup(36)] + sage: [Gamma1(36).dimension_eis(1,eps,algorithm='Quer') for eps in DirichletGroup(36)] [0, 4, 3, 0, 0, 2, 6, 0, 0, 2, 3, 0] So do these:: sage: [Gamma1(48).dimension_eis(3,eps) for eps in DirichletGroup(48)] [0, 12, 0, 4, 0, 8, 0, 4, 12, 0, 4, 0, 8, 0, 4, 0] - sage: [Gamma1(48).dimension_eis(3,eps,algorithm="Quer") for eps in DirichletGroup(48)] + sage: [Gamma1(48).dimension_eis(3,eps,algorithm='Quer') for eps in DirichletGroup(48)] [0, 12, 0, 4, 0, 8, 0, 4, 12, 0, 4, 0, 8, 0, 4, 0] """ from .all import Gamma0 @@ -576,24 +576,24 @@ def dimension_eis(self, k=2, eps=None, algorithm="CohenOesterle"): else: #algorithm not in ["CohenOesterle", "Quer"]: raise ValueError("Unrecognised algorithm in dimension_eis") - def dimension_new_cusp_forms(self, k=2, eps=None, p=0, algorithm="CohenOesterle"): + def dimension_new_cusp_forms(self, k=2, eps=None, p=0, algorithm='CohenOesterle'): r""" Dimension of the new subspace (or `p`-new subspace) of cusp forms of weight `k` and character `\varepsilon`. INPUT: - - ``k`` -- an integer (default: 2) + - ``k`` -- integer (default: 2) - ``eps`` -- a Dirichlet character - - ``p`` -- a prime (default: 0); just the `p`-new subspace if given + - ``p`` -- a prime (default: 0); just the `p`-new subspace if given - - ``algorithm`` -- either "CohenOesterle" (the default) or "Quer". This - specifies the method to use in the case of nontrivial character: - either the Cohen--Oesterle formula as described in Stein's book, or - by Möbius inversion using the subgroups GammaH (a method due to - Jordi Quer). + - ``algorithm`` -- either ``'CohenOesterle'`` (the default) or + ``'Quer'``. This specifies the method to use in the case of nontrivial + character: either the Cohen--Oesterle formula as described in Stein's + book, or by Möbius inversion using the subgroups GammaH (a method due + to Jordi Quer). EXAMPLES:: @@ -623,13 +623,12 @@ def dimension_new_cusp_forms(self, k=2, eps=None, p=0, algorithm="CohenOesterle" 11 sage: [Gamma1(33).dimension_new_cusp_forms(k, G.1) for k in [2..4]] [0, 4, 0] - sage: [Gamma1(33).dimension_new_cusp_forms(k, G.1, algorithm="Quer") for k in [2..4]] + sage: [Gamma1(33).dimension_new_cusp_forms(k, G.1, algorithm='Quer') for k in [2..4]] [0, 4, 0] sage: [Gamma1(33).dimension_new_cusp_forms(k, G.1^2) for k in [2..4]] [2, 0, 6] sage: [Gamma1(33).dimension_new_cusp_forms(k, G.1^2, p=3) for k in [2..4]] [2, 0, 6] - """ if eps is None: diff --git a/src/sage/modular/arithgroup/congroup_gammaH.py b/src/sage/modular/arithgroup/congroup_gammaH.py index 1ad2042ec4b..e0cf97c74bc 100644 --- a/src/sage/modular/arithgroup/congroup_gammaH.py +++ b/src/sage/modular/arithgroup/congroup_gammaH.py @@ -45,8 +45,8 @@ def GammaH_constructor(level, H): INPUT: - - level -- an integer - - H -- either 0, 1, or a list + - ``level`` -- integer + - ``H`` -- either 0, 1, or a list * If H is a list, return `\Gamma_H(N)`, where `H` is the subgroup of `(\ZZ/N\ZZ)^*` **generated** by the elements of the list. @@ -94,7 +94,7 @@ def GammaH_constructor(level, H): def is_GammaH(x): """ - Return True if x is a congruence subgroup of type GammaH. + Return ``True`` if x is a congruence subgroup of type GammaH. EXAMPLES:: @@ -272,7 +272,7 @@ def extend(self, M): def __reduce__(self): """ - Used for pickling self. + Used for pickling ``self``. EXAMPLES:: @@ -308,7 +308,7 @@ def divisor_subgroups(self): def to_even_subgroup(self): r""" - Return the smallest even subgroup of `SL(2, \ZZ)` containing self. + Return the smallest even subgroup of `SL(2, \ZZ)` containing ``self``. EXAMPLES:: @@ -316,7 +316,6 @@ def to_even_subgroup(self): Congruence Subgroup Gamma0(11) sage: Gamma1(11).to_even_subgroup() Congruence Subgroup Gamma_H(11) with H generated by [10] - """ if self.is_even(): return self @@ -325,7 +324,7 @@ def to_even_subgroup(self): def __richcmp__(self, other, op): """ - Compare self to other. + Compare ``self`` to ``other``. The ordering on congruence subgroups of the form GammaH(N) for some H is first by level, then by the order of H, then lexicographically by H. @@ -385,8 +384,8 @@ def __richcmp__(self, other, op): def _generators_for_H(self): """ - Return generators for the subgroup H of the units mod - self.level() that defines self. + Return generators for the subgroup `H` of the units mod + ``self.level()`` that defines ``self``. EXAMPLES:: @@ -399,7 +398,7 @@ def _generators_for_H(self): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -410,7 +409,7 @@ def _repr_(self): def _latex_(self): r""" - Return the \LaTeX representation of self. + Return the \LaTeX representation of ``self``. EXAMPLES:: @@ -421,7 +420,7 @@ def _latex_(self): def _list_of_elements_in_H(self): """ - Returns a sorted list of Python ints that are representatives + Return a sorted list of Python ints that are representatives between 1 and N-1 of the elements of H. WARNING: Do not change this returned list. @@ -437,7 +436,7 @@ def _list_of_elements_in_H(self): def is_even(self): """ - Return True precisely if this subgroup contains the matrix -1. + Return ``True`` precisely if this subgroup contains the matrix -1. EXAMPLES:: @@ -452,21 +451,21 @@ def is_even(self): return int(self.level() - 1) in v @cached_method - def generators(self, algorithm="farey"): + def generators(self, algorithm='farey'): r""" Return generators for this congruence subgroup. The result is cached. INPUT: - - ``algorithm`` (string): either ``farey`` (default) or - ``todd-coxeter``. + - ``algorithm`` -- string; either ``'farey'`` (default) or + ``todd-coxeter`` - If ``algorithm`` is set to ``"farey"``, then the generators will be + If ``algorithm`` is set to ``'farey'``, then the generators will be calculated using Farey symbols, which will always return a *minimal* generating set. See :mod:`~sage.modular.arithgroup.farey_symbol` for more information. - If ``algorithm`` is set to ``"todd-coxeter"``, a simpler algorithm + If ``algorithm`` is set to ``'todd-coxeter'``, a simpler algorithm based on Todd-Coxeter enumeration will be used. This tends to return far larger sets of generators. @@ -477,7 +476,7 @@ def generators(self, algorithm="farey"): [1 1] [ 2 -1] [ 4 -3] [0 1], [ 7 -3], [ 7 -5] ] - sage: GammaH(7, [2]).generators(algorithm="todd-coxeter") + sage: GammaH(7, [2]).generators(algorithm='todd-coxeter') [ [1 1] [-13 4] [ 15 4] [-3 -1] [ 1 -1] [1 0] [1 1] [-3 -1] [0 1], [ 42 -13], [-49 -13], [ 7 2], [ 0 1], [7 1], [0 1], [ 7 2], @@ -512,9 +511,7 @@ def _coset_reduction_data_first_coord(self): - ``self`` -- a congruence subgroup Gamma_0(N), Gamma_1(N), or Gamma_H(N) - OUTPUT: - - A list v such that + OUTPUT: list v such that v[u] = (min(u*h: h in H), gcd(u,N) , @@ -587,13 +584,9 @@ def _coset_reduction_data_second_coord(self): This function specifically returns data needed for the second part of the reduction step (the second coordinate). - INPUT: - - ``self`` - OUTPUT: - a dictionary v with keys the divisors of N such that v[d] + A dictionary v with keys the divisors of N such that v[d] is the subgroup {h in H : h = 1 (mod N/d)}. EXAMPLES:: @@ -659,12 +652,10 @@ def _reduce_coset(self, uu, vv): Two integers (uu,vv) that define an element of `(Z/NZ)^2`. - - uu -- an integer - - vv -- an integer + - ``uu`` -- integer + - ``vv`` -- integer - OUTPUT: - - pair of integers that are equivalent to (uu,vv). + OUTPUT: pair of integers that are equivalent to (uu,vv) .. NOTE:: @@ -892,8 +883,8 @@ def _reduce_cusp(self, c): def _find_cusps(self): r""" - Return an ordered list of inequivalent cusps for self, i.e. a - set of representatives for the orbits of self on + Return an ordered list of inequivalent cusps for ``self``, i.e. a + set of representatives for the orbits of ``self`` on `\mathbf{P}^1(\QQ)`. These are returned in a reduced form; see self.reduce_cusp for the definition of reduced. @@ -968,8 +959,8 @@ def _contains_sl2(self, a, b, c, d): def gamma0_coset_reps(self): r""" - Return a set of coset representatives for self \\ Gamma0(N), where N is - the level of self. + Return a set of coset representatives for ``self \\ Gamma0(N)``, where + N is the level of ``self``. EXAMPLES:: @@ -991,7 +982,7 @@ def gamma0_coset_reps(self): def coset_reps(self): r""" - Return a set of coset representatives for self \\ SL2Z. + Return a set of coset representatives for ``self \\ SL2Z``. EXAMPLES:: @@ -1012,7 +1003,7 @@ def coset_reps(self): def is_subgroup(self, other): r""" - Return True if self is a subgroup of right, and False + Return ``True`` if ``self`` is a subgroup of ``right``, and ``False`` otherwise. EXAMPLES:: @@ -1110,7 +1101,6 @@ def nu3(self): AUTHORS: - Jordi Quer - """ N = self.level() H = self._list_of_elements_in_H() @@ -1138,7 +1128,6 @@ def ncusps(self): AUTHORS: - Jordi Quer - """ N = self.level() H = self._list_of_elements_in_H() @@ -1247,10 +1236,12 @@ def dimension_new_cusp_forms(self, k=2, p=0): INPUT: - - ``k`` -- an integer (default: 2), the weight. Not fully implemented for k = 1. - - ``p`` -- integer (default: 0); if nonzero, compute the `p`-new subspace. + - ``k`` -- integer (default: 2); the weight. Not fully implemented for + `k = 1`. + - ``p`` -- integer (default: 0); if nonzero, compute the `p`-new + subspace - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -1302,7 +1293,7 @@ def atkin_lehner_matrix(self, Q): an exact divisor `Q` of `N`, where `N` is the level of this group; that is, `gcd(Q, N/Q) = 1`. - .. note:: + .. NOTE:: We follow the conventions of [AL1978]_ here, so `W_Q` is given by the action of any matrix of the form `\begin{pmatrix} Qx & y \\ Nz @@ -1312,7 +1303,7 @@ def atkin_lehner_matrix(self, Q): INPUT: - - ``Q`` (integer): an integer dividing `N`, where `N` is the level of + - ``Q`` -- an integer dividing `N`, where `N` is the level of this group. If this divisor does not satisfy `gcd(Q, N/Q) = 1`, it will be replaced by the unique integer with this property having the same prime factors as `Q`. @@ -1349,11 +1340,11 @@ def characters_mod_H(self, sign=None, galois_orbits=False): INPUT: - - ``sign`` (default: None): if not None, return only characters of the - given sign + - ``sign`` -- (default: ``None``) if not ``None``, return only + characters of the given sign - - ``galois_orbits`` (default: ``False``): if True, return only one - character from each Galois orbit. + - ``galois_orbits`` -- (default: ``False``) if ``True``, return only + one character from each Galois orbit EXAMPLES:: @@ -1450,9 +1441,9 @@ def mumu(N): INPUT: - - ``N`` -- an integer at least 1 + - ``N`` -- integer at least 1 - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/modular/arithgroup/congroup_generic.py b/src/sage/modular/arithgroup/congroup_generic.py index cbd368fba31..507418bd239 100644 --- a/src/sage/modular/arithgroup/congroup_generic.py +++ b/src/sage/modular/arithgroup/congroup_generic.py @@ -117,7 +117,7 @@ def CongruenceSubgroup_constructor(*args): def is_CongruenceSubgroup(x): r""" - Return True if x is of type CongruenceSubgroup. + Return ``True`` if x is of type CongruenceSubgroup. Note that this may be False even if `x` really is a congruence subgroup -- it tests whether `x` is "obviously" congruence, i.e.~whether it has a @@ -169,7 +169,7 @@ def __init__(self, level): def _an_element_(self): r""" - Return an element of self (mainly for use by the test suite). + Return an element of ``self`` (mainly for use by the test suite). EXAMPLES:: @@ -318,7 +318,7 @@ def __init__(self, G): def __reduce__(self): r""" - Data defining self (for pickling). + Data defining ``self`` (for pickling). EXAMPLES:: @@ -334,7 +334,7 @@ def __reduce__(self): def _contains_sl2(self, a,b,c,d): r""" - Test whether ``[a,b;c,d]`` is an element of self. + Test whether ``[a,b;c,d]`` is an element of ``self``. EXAMPLES:: @@ -369,7 +369,7 @@ def _contains_sl2(self, a,b,c,d): def to_even_subgroup(self): r""" - Return the smallest even subgroup of `SL(2, \ZZ)` containing self. + Return the smallest even subgroup of `SL(2, \ZZ)` containing ``self``. EXAMPLES:: @@ -392,7 +392,7 @@ def to_even_subgroup(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -403,7 +403,7 @@ def _repr_(self): def index(self): r""" - Return the index of self in the full modular group. This is equal to + Return the index of ``self`` in the full modular group. This is equal to the index in `SL(2, \ZZ / N\ZZ)` of the image of this group modulo `\Gamma(N)`. @@ -416,7 +416,8 @@ def index(self): def image_mod_n(self): r""" - Return the subgroup of `SL(2, \ZZ / N\ZZ)` of which this is the preimage, where `N` is the level of self. + Return the subgroup of `SL(2, \ZZ / N\ZZ)` of which this is the + preimage, where `N` is the level of ``self``. EXAMPLES:: @@ -466,7 +467,7 @@ def __init__(self,*args, **kwds): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. NOTE: This function should be overridden by all subclasses. @@ -480,7 +481,7 @@ def _repr_(self): def modular_symbols(self, sign=0, weight=2, base_ring=QQ): """ Return the space of modular symbols of the specified weight and sign - on the congruence subgroup self. + on the congruence subgroup ``self``. EXAMPLES:: @@ -500,7 +501,7 @@ def modular_symbols(self, sign=0, weight=2, base_ring=QQ): def modular_abelian_variety(self): """ Return the modular abelian variety corresponding to the congruence - subgroup self. + subgroup ``self``. EXAMPLES:: @@ -517,7 +518,7 @@ def modular_abelian_variety(self): def _new_group_from_level(self, level): r""" Return a new group of the same type (Gamma0, Gamma1, or - GammaH) as self of the given level. In the case that self is of type + GammaH) as ``self`` of the given level. In the case that ``self`` is of type GammaH, we take the largest H inside `(\ZZ/ \text{level}\ZZ)^\times` which maps to H, namely its inverse image under the natural reduction map. diff --git a/src/sage/modular/arithgroup/congroup_sl2z.py b/src/sage/modular/arithgroup/congroup_sl2z.py index f67ada831d3..7e15eaca383 100644 --- a/src/sage/modular/arithgroup/congroup_sl2z.py +++ b/src/sage/modular/arithgroup/congroup_sl2z.py @@ -29,7 +29,7 @@ def is_SL2Z(x): r""" - Return True if x is the modular group `\SL_2(\ZZ)`. + Return ``True`` if x is the modular group `\SL_2(\ZZ)`. EXAMPLES:: @@ -87,7 +87,7 @@ def __init__(self): def __reduce__(self): """ - Used for pickling self. + Used for pickling ``self``. EXAMPLES:: @@ -98,8 +98,8 @@ def __reduce__(self): def _element_constructor_(self, x, check=True): r""" - Create an element of self from x, which must be something that can be - coerced into a 2x2 integer matrix. If check=True (the default), check + Create an element of ``self`` from x, which must be something that can be + coerced into a 2x2 integer matrix. If ``check=True`` (the default), check that x really has determinant 1. EXAMPLES:: @@ -130,7 +130,7 @@ def _contains_sl2(self,a,b,c,d): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -141,7 +141,7 @@ def _repr_(self): def _latex_(self): r""" - Return the \LaTeX representation of self. + Return the \LaTeX representation of ``self``. EXAMPLES:: @@ -154,7 +154,7 @@ def _latex_(self): def is_subgroup(self, right): """ - Return True if self is a subgroup of right. + Return ``True`` if ``self`` is a subgroup of ``right``. EXAMPLES:: @@ -170,7 +170,7 @@ def is_subgroup(self, right): def reduce_cusp(self, c): r""" Return the unique reduced cusp equivalent to c under the - action of self. Always returns Infinity, since there is only + action of ``self``. Always returns Infinity, since there is only one equivalence class of cusps for `SL_2(Z)`. EXAMPLES:: @@ -183,7 +183,7 @@ def reduce_cusp(self, c): def random_element(self, bound=100, *args, **kwds): r""" Return a random element of `\SL_2(\ZZ)` with entries whose - absolute value is strictly less than bound (default 100). + absolute value is strictly less than bound (default: 100). Additional arguments and keywords are passed to the random_element method of ZZ. @@ -252,7 +252,7 @@ def random_element(self, bound=100, *args, **kwds): def _SL2Z_ref(): """ - Return SL2Z. (Used for pickling SL2Z.) + Return SL2Z. (Used for pickling SL2Z.). EXAMPLES:: diff --git a/src/sage/modular/arithgroup/farey_symbol.pyx b/src/sage/modular/arithgroup/farey_symbol.pyx index 68ab335a514..bb48288eec2 100644 --- a/src/sage/modular/arithgroup/farey_symbol.pyx +++ b/src/sage/modular/arithgroup/farey_symbol.pyx @@ -110,7 +110,7 @@ cdef class Farey: INPUT: - - `G` -- an arithmetic subgroup of `\PSL_2(\ZZ)` + - ``G`` -- an arithmetic subgroup of `\PSL_2(\ZZ)` EXAMPLES: @@ -305,12 +305,8 @@ cdef class Farey: @cached_method def _get_minus_one(self): r""" - If -I belongs to self, return a Tietze word representing it. - - OUTPUT: - - A Tietze word representing the element -I if it belongs to self. - Otherwise return [] + If -I belongs to ``self``, return a Tietze word representing it. + Otherwise return ``[]``. EXAMPLES:: @@ -352,10 +348,11 @@ cdef class Farey: INPUT: - - ``M`` -- An element `M` of `\SL_2(\ZZ)`. - - ``output`` -- (default: ``'standard'``) Should be one of ``'standard'``, + - ``M`` -- an element `M` of `\SL_2(\ZZ)` + - ``output`` -- (default: ``'standard'``) should be one of ``'standard'``, ``'syllables'``, ``'gens'``. - - ``check`` -- (default: ``True``) Whether to check for correct input and output. + - ``check`` -- boolean (default: ``True``); whether to check for + correct input and output OUTPUT: @@ -364,7 +361,7 @@ cdef class Farey: - ``standard`` returns the so called the Tietze representation, consists of a tuple of nonzero integers `i`, where if `i` > 0 - then it indicates the `i`th generator (that is, ``self.generators()[0]`` + then it indicates the `i`-th generator (that is, ``self.generators()[0]`` would correspond to `i` = 1), and if `i` < 0 then it indicates the inverse of the `i`-th generator. - ``syllables`` returns a tuple of tuples of the form `(i,n)`, where @@ -514,7 +511,7 @@ cdef class Farey: def __contains__(self, M): r""" - Tests if element is in the arithmetic group of the Farey symbol + Test if element is in the arithmetic group of the Farey symbol via LLT algorithm. EXAMPLES:: @@ -536,7 +533,7 @@ cdef class Farey: def __richcmp__(self, other, op): r""" - Compare self to others. + Compare ``self`` to ``other``. EXAMPLES:: @@ -567,7 +564,6 @@ cdef class Farey: sage: FareySymbol(Gamma0(4)).__reduce__() (, ...)) - """ return Farey, (self.group, self.this_ptr.dumps()) @@ -593,8 +589,8 @@ cdef class Farey: INPUT: - - ``forced_format`` -- A format string ('plain' or 'xymatrix') - or ``None``. + - ``forced_format`` -- a format string ('plain' or 'xymatrix') + or ``None`` EXAMPLES:: @@ -908,23 +904,23 @@ cdef class Farey: OPTIONS: - - ``fill`` -- boolean (default ``True``) fill the fundamental domain + - ``fill`` -- boolean (default: ``True``); fill the fundamental domain - - ``linestyle`` -- string (default: 'solid') The style of the line, + - ``linestyle`` -- string (default: ``'solid'``); the style of the line, which is one of 'dashed', 'dotted', 'solid', 'dashdot', or '--', ':', '-', '-.', respectively - - ``color`` -- (default: 'lightgray') fill color; fill - color for odd part of Dedekind tesselation. + - ``color`` -- (default: ``'lightgray'``) fill color for odd part of + Dedekind tesselation - - ``show_pairing`` -- boolean (default: ``True``) flag for pairing + - ``show_pairing`` -- boolean (default: ``True``); flag for pairing - - ``tesselation`` -- (default: 'Dedekind') The type of + - ``tesselation`` -- (default: ``'Dedekind'``) the type of hyperbolic tesselation which is one of - 'coset', 'Dedekind' or ``None`` respectively + ``'coset'``, ``'Dedekind'`` or ``None`` respectively - ``color_even`` -- fill color for even parts of Dedekind - tesselation (default 'white'); ignored for other tesselations + tesselation (default: ``'white'``); ignored for other tesselations - ``thickness`` -- float (default: `1`) the thickness of the line diff --git a/src/sage/modular/btquotients/btquotient.py b/src/sage/modular/btquotients/btquotient.py index eb0a6f0e1b3..d4bdb13e6b1 100644 --- a/src/sage/modular/btquotients/btquotient.py +++ b/src/sage/modular/btquotients/btquotient.py @@ -113,12 +113,12 @@ class computes and stores the data corresponding to the INPUT: - - ``Y`` -- BruhatTitsQuotient object in which to work - - ``x`` -- Something coercible into a matrix in `GL_2(\ZZ)`. In - principle we should allow elements in `GL_2(\QQ_p)`, but it is - enough to work with integral entries + - ``Y`` -- BruhatTitsQuotient object in which to work + - ``x`` -- Something coercible into a matrix in `GL_2(\ZZ)`. In + principle we should allow elements in `GL_2(\QQ_p)`, but it is + enough to work with integral entries - ``extrapow`` -- gets added to the power attribute, and it is - used for the Hecke action. + used for the Hecke action EXAMPLES:: @@ -181,7 +181,7 @@ def __init__(self, Y, x, extrapow=0): def _repr_(self): r""" - Return the representation of self as a string. + Return the representation of ``self`` as a string. EXAMPLES:: @@ -196,7 +196,7 @@ def _repr_(self): def __eq__(self, other): """ - Return self == other + Return ``self == other``. TESTS:: @@ -229,7 +229,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Return self != other + Return ``self != other``. TESTS:: @@ -290,7 +290,7 @@ def igamma(self, embedding=None, scale=1): INPUT: - - ``embedding`` -- an integer, or a function (default: + - ``embedding`` -- integer; or a function (default: none). If ``embedding`` is None, then the image of ``self.gamma`` under the local splitting associated to ``self.Y`` is used. If ``embedding`` is an integer, then @@ -421,7 +421,7 @@ class BruhatTitsTree(SageObject, UniqueRepresentation): """ def __init__(self, p): """ - Initialize a BruhatTitsTree object for a given prime `p` + Initialize a BruhatTitsTree object for a given prime `p`. EXAMPLES:: @@ -444,8 +444,8 @@ def target(self, e, normalized=False): - ``e`` -- a 2x2 matrix with integer entries - - ``normalized`` -- boolean (default: false). If True - then the input matrix is assumed to be normalized. + - ``normalized`` -- boolean (default: ``False``); if True + then the input matrix is assumed to be normalized OUTPUT: @@ -477,12 +477,10 @@ def origin(self, e, normalized=False): - ``e`` -- a 2x2 matrix with integer entries - - ``normalized`` -- boolean (default: false). If True + - ``normalized`` -- boolean (default: ``False``); if True then the input matrix M is assumed to be normalized - OUTPUT: - - - ``e`` -- A 2x2 integer matrix + OUTPUT: ``e`` -- 2x2 integer matrix EXAMPLES:: @@ -508,11 +506,9 @@ def edge(self, M): INPUT: - - ``M`` -- a 2x2 integer matrix - - OUTPUT: + - ``M`` -- 2x2 integer matrix - - ``newM`` -- a 2x2 integer matrix + OUTPUT: ``newM`` -- 2x2 integer matrix EXAMPLES:: @@ -527,15 +523,13 @@ def edge(self, M): def lift(a): """ - Naively approximate a p-adic integer by a positive integer. + Naively approximate a `p`-adic integer by a positive integer. INPUT: - - ``a`` -- a p-adic integer. - - OUTPUT: + - ``a`` -- `p`-adic integer - An integer. + OUTPUT: integer EXAMPLES:: @@ -594,9 +588,7 @@ def vertex(self, M): - ``M`` -- 2x2 integer matrix - OUTPUT: - - - a 2x2 integer matrix + OUTPUT: a 2x2 integer matrix EXAMPLES:: @@ -655,9 +647,7 @@ def edges_leaving_origin(self): leaving the origin vertex corresponding to the homothety class of `\ZZ_p^2`. These are cached. - OUTPUT: - - - A list of size `p+1` of 2x2 integer matrices + OUTPUT: list of size `p+1` of 2x2 integer matrices EXAMPLES:: @@ -688,14 +678,14 @@ def edge_between_vertices(self, v1, v2, normalized=False): - ``v2`` -- 2x2 integer matrix - - ``normalized`` -- boolean (default: ``False``), whether the - vertices are normalized. + - ``normalized`` -- boolean (default: ``False``); whether the + vertices are normalized OUTPUT: - 2x2 integer matrix, representing the edge from ``v1`` to ``v2``. If ``v1`` and ``v2`` are not at distance `1`, raise - a :class:`ValueError`. + a :exc:`ValueError`. EXAMPLES:: @@ -731,15 +721,13 @@ def edge_between_vertices(self, v1, v2, normalized=False): def leaving_edges(self, M): r""" - Return edges leaving a vertex + Return edges leaving a vertex. INPUT: - ``M`` -- 2x2 integer matrix - OUTPUT: - - List of size `p+1` of 2x2 integer matrices + OUTPUT: list of size `p+1` of 2x2 integer matrices EXAMPLES:: @@ -763,9 +751,7 @@ def opposite(self, e): - ``e`` -- 2x2 integer matrix - OUTPUT: - - 2x2 integer matrix + OUTPUT: 2x2 integer matrix EXAMPLES:: @@ -792,9 +778,7 @@ def entering_edges(self, v): - ``v`` -- 2x2 integer matrix - OUTPUT: - - A list of size `p+1` of 2x2 integer matrices + OUTPUT: list of size `p+1` of 2x2 integer matrices EXAMPLES:: @@ -811,7 +795,7 @@ def entering_edges(self, v): def subdivide(self, edgelist, level): r""" - (Ordered) edges of self may be regarded as open balls in + (Ordered) edges of ``self`` may be regarded as open balls in `P^1(\QQ_p)`. Given a list of edges, this function return a list of edges corresponding to the level-th subdivision of the corresponding opens. That is, each open ball of the input is @@ -819,13 +803,11 @@ def subdivide(self, edgelist, level): INPUT: - - ``edgelist`` -- a list of edges - - - ``level`` -- an integer + - ``edgelist`` -- list of edges - OUTPUT: + - ``level`` -- integer - A list of 2x2 integer matrices + OUTPUT: list of 2x2 integer matrices EXAMPLES:: @@ -889,8 +871,8 @@ def find_path(self, v, boundary=None): - ``v`` -- a 2x2 matrix representing a vertex ``boundary`` - - a list of matrices (default: None). If omitted, finds the - geodesic from ``v`` to the central vertex. + - a list of matrices (default: ``None``); if omitted, finds the + geodesic from ``v`` to the central vertex OUTPUT: @@ -954,11 +936,9 @@ def find_containing_affinoid(self, z): INPUT: - ``z`` -- an element of an unramified extension of `\QQ_p` - that is not contained in `\QQ_p`. + that is not contained in `\QQ_p` - OUTPUT: - - A 2x2 integer matrix representing a vertex of ``self``. + OUTPUT: a 2x2 integer matrix representing a vertex of ``self`` EXAMPLES:: @@ -1004,7 +984,7 @@ def find_containing_affinoid(self, z): def find_geodesic(self, v1, v2, normalized=True): r""" - This function computes the geodesic between two vertices + This function computes the geodesic between two vertices. INPUT: @@ -1046,7 +1026,7 @@ def find_geodesic(self, v1, v2, normalized=True): def find_covering(self, z1, z2, level=0): r""" Compute a covering of `P^1(\QQ_p)` adapted to a certain - geodesic in self. + geodesic in ``self``. More precisely, the `p`-adic upper half plane points ``z1`` and ``z2`` reduce to vertices `v_1`, `v_2`. @@ -1057,9 +1037,7 @@ def find_covering(self, z1, z2, level=0): - ``z1``, ``z2`` -- unramified algebraic points of h_p - OUTPUT: - - a list of 2x2 integer matrices representing edges of self + OUTPUT: list of 2x2 integer matrices representing edges of self EXAMPLES:: @@ -1110,24 +1088,24 @@ class Vertex(SageObject): INPUT: - - ``p`` -- a prime integer. + - ``p`` -- prime integer - - ``label`` -- An integer which uniquely identifies this vertex. + - ``label`` -- integer which uniquely identifies this vertex - - ``rep`` -- A 2x2 matrix in reduced form representing this - vertex. + - ``rep`` -- a 2x2 matrix in reduced form representing this + vertex - - ``leaving_edges`` -- (default: empty list) A list of edges - leaving this vertex. + - ``leaving_edges`` -- (default: empty list) list of edges + leaving this vertex - - ``entering_edges`` -- (default: empty list) A list of edges - entering this vertex. + - ``entering_edges`` -- (default: empty list) list of edges + entering this vertex - - ``determinant`` -- (default: None) The determinant of ``rep``, - if known. + - ``determinant`` -- (default: ``None``) the determinant of ``rep``, + if known - - ``valuation`` -- (default: None) The valuation of the - determinant of ``rep``, if known. + - ``valuation`` -- (default: ``None``) the valuation of the + determinant of ``rep``, if known EXAMPLES:: @@ -1177,7 +1155,7 @@ def __init__(self, p, label, rep, leaving_edges=None, def _repr_(self): r""" - Return the representation of self as a string. + Return the representation of ``self`` as a string. EXAMPLES:: @@ -1189,7 +1167,7 @@ def _repr_(self): def __eq__(self, other): """ - Return self == other + Return ``self == other``. TESTS:: @@ -1214,7 +1192,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Return self != other + Return ``self != other``. TESTS:: @@ -1234,27 +1212,27 @@ class Edge(SageObject): INPUT: - - ``p`` -- a prime integer. + - ``p`` -- prime integer - - ``label`` -- An integer which uniquely identifies this edge. + - ``label`` -- integer which uniquely identifies this edge - - ``rep`` -- A 2x2 matrix in reduced form representing this edge. + - ``rep`` -- a 2x2 matrix in reduced form representing this edge - - ``origin`` -- The origin vertex of ``self``. + - ``origin`` -- the origin vertex of ``self`` - - ``target`` -- The target vertex of ``self``. + - ``target`` -- the target vertex of ``self`` - - ``links`` -- (Default: empty list) A list of elements of + - ``links`` -- (default: empty list) list of elements of `\Gamma` which identify different edges in the Bruhat-Tits tree - which are equivalent to ``self``. + which are equivalent to ``self`` - - ``opposite`` -- (Default: None) The edge opposite to ``self`` + - ``opposite`` -- (default: ``None``) the edge opposite to ``self`` - - ``determinant`` -- (Default: None) The determinant of ``rep``, - if known. + - ``determinant`` -- (default: ``None``) the determinant of ``rep``, + if known - - ``valuation`` -- (Default: None) The valuation of the - determinant of ``rep``, if known. + - ``valuation`` -- (default: ``None``) the valuation of the + determinant of ``rep``, if known EXAMPLES:: @@ -1306,7 +1284,7 @@ def __init__(self, p, label, rep, origin, target, links=None, def _repr_(self): r""" - Return the representation of self as a string. + Return the representation of ``self`` as a string. EXAMPLES:: @@ -1318,7 +1296,7 @@ def _repr_(self): def __eq__(self, other): """ - Return self == other + Return ``self == other``. TESTS:: @@ -1353,7 +1331,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Return self != other + Return ``self != other``. TESTS:: @@ -1385,20 +1363,20 @@ class BruhatTitsQuotient(SageObject, UniqueRepresentation): discriminant of the definite quaternion algebra that one is quotienting by. - - ``Nplus`` -- an integer coprime to pNminus (Default: 1). This is + - ``Nplus`` -- integer coprime to pNminus (default: 1). This is the tame level. It need not be squarefree! If Nplus is not 1 then the user currently needs magma installed due to sage's inability to compute well with nonmaximal Eichler orders in rational (definite) quaternion algebras. - - ``character`` -- a Dirichlet character (Default: None) of modulus - `pN^-N^+`. + - ``character`` -- a Dirichlet character (default: ``None``) of modulus + `pN^-N^+` - - ``use_magma`` -- boolean (default: ``False``). If True, uses Magma - for quaternion arithmetic. + - ``use_magma`` -- boolean (default: ``False``); if True, uses Magma + for quaternion arithmetic - - ``magma_session`` -- (default: None). If specified, the Magma session - to use. + - ``magma_session`` -- (default: ``None``) if specified, the Magma session + to use EXAMPLES: @@ -1551,7 +1529,7 @@ def _cache_key(self): def _repr_(self): r""" - Return the representation of self as a string. + Return the representation of ``self`` as a string. EXAMPLES:: @@ -1562,7 +1540,7 @@ def _repr_(self): def __eq__(self, other): r""" - Compare self with other. + Compare ``self`` with ``other``. EXAMPLES:: @@ -1583,7 +1561,7 @@ def __eq__(self, other): def __ne__(self, other): r""" - Compare self with other. + Compare ``self`` with ``other``. EXAMPLES:: @@ -1610,9 +1588,7 @@ def get_vertex_dict(self): This function returns the vertices of the quotient viewed as a dict. - OUTPUT: - - A python dict with the vertices of the quotient. + OUTPUT: a Python dict with the vertices of the quotient EXAMPLES:: @@ -1632,10 +1608,6 @@ def get_vertex_list(self): r""" Return a list of the vertices of the quotient. - OUTPUT: - - - A list with the vertices of the quotient. - EXAMPLES:: sage: X = BruhatTitsQuotient(37,3) @@ -1653,16 +1625,11 @@ def get_edge_list(self): Return a list of ``Edge`` which represent a fundamental domain inside the Bruhat-Tits tree for the quotient. - OUTPUT: - - A list of ``Edge``. - EXAMPLES:: sage: X = BruhatTitsQuotient(37,3) sage: len(X.get_edge_list()) 8 - """ try: return self._edge_list @@ -1677,10 +1644,6 @@ def get_list(self): together with a list of the opposite edges. This is used to work with automorphic forms. - OUTPUT: - - A list of ``Edge``. - EXAMPLES:: sage: X = BruhatTitsQuotient(37,3) @@ -1793,9 +1756,7 @@ def e3(self): e_k =\prod_{\ell\mid pN^-}\left(1-\left(\frac{-3}{\ell}\right)\right)\prod_{\ell \| N^+}\left(1+\left(\frac{-3}{\ell}\right)\right)\prod_{\ell^2\mid N^+} \nu_\ell(3) - OUTPUT: - - an integer + OUTPUT: integer EXAMPLES:: @@ -1815,9 +1776,7 @@ def e4(self): e_k =\prod_{\ell\mid pN^-}\left(1-\left(\frac{-k}{\ell}\right)\right)\prod_{\ell \| N^+}\left(1+\left(\frac{-k}{\ell}\right)\right)\prod_{\ell^2\mid N^+} \nu_\ell(k) - OUTPUT: - - an integer + OUTPUT: integer EXAMPLES:: @@ -1831,11 +1790,9 @@ def e4(self): @lazy_attribute def mu(self): """ - Compute the mu invariant of self. - - OUTPUT: + Compute the mu invariant of ``self``. - An integer. + OUTPUT: integer EXAMPLES:: @@ -1871,9 +1828,7 @@ def get_num_ordered_edges(self): the formula relating the genus `g` with the number of vertices `V` and that of unordered edges `E/2`: `E = 2(g + V - 1)`. - OUTPUT: - - - An integer + OUTPUT: integer EXAMPLES:: @@ -1888,9 +1843,7 @@ def genus_no_formula(self): Compute the genus of the quotient from the data of the quotient graph. This should agree with self.genus(). - OUTPUT: - - An integer + OUTPUT: integer EXAMPLES:: @@ -1914,15 +1867,13 @@ def genus(self): INPUT: - - level: Integer (default: None) a level. By default, use that + - ``level`` -- integer (default: ``None``); a level. By default, use that of ``self``. - - Nplus: Integer (default: None) a conductor. By default, use + - ``Nplus`` -- integer (default: ``None``); a conductor. By default, use that of ``self``. - OUTPUT: - - An integer equal to the genus + OUTPUT: integer equal to the genus EXAMPLES:: @@ -1941,9 +1892,7 @@ def dimension_harmonic_cocycles(self, k, lev=None, Nplus=None, Compute the dimension of the space of harmonic cocycles of weight `k` on ``self``. - OUTPUT: - - An integer equal to the dimension + OUTPUT: integer equal to the dimension EXAMPLES:: @@ -2014,9 +1963,7 @@ def Nplus(self): r""" Return the tame level `N^+`. - OUTPUT: - - An integer equal to `N^+`. + OUTPUT: integer equal to `N^+` EXAMPLES:: @@ -2066,9 +2013,7 @@ def prime(self): r""" Return the prime one is working with. - OUTPUT: - - An integer equal to the fixed prime `p` + OUTPUT: integer equal to the fixed prime `p` EXAMPLES:: @@ -2082,9 +2027,7 @@ def get_graph(self): r""" Return the quotient graph (and compute it if needed). - OUTPUT: - - A graph representing the quotient of the Bruhat-Tits tree. + OUTPUT: a graph representing the quotient of the Bruhat-Tits tree EXAMPLES:: @@ -2102,9 +2045,7 @@ def get_fundom_graph(self): r""" Return the fundamental domain (and computes it if needed). - OUTPUT: - - A fundamental domain for the action of `\Gamma`. + OUTPUT: a fundamental domain for the action of `\Gamma` EXAMPLES:: @@ -2122,9 +2063,7 @@ def plot(self, *args, **kwargs): r""" Plot the quotient graph. - OUTPUT: - - A plot of the quotient graph + OUTPUT: a plot of the quotient graph EXAMPLES:: @@ -2155,9 +2094,7 @@ def plot_fundom(self, *args, **kwargs): r""" Plot a fundamental domain. - OUTPUT: - - A plot of the fundamental domain. + OUTPUT: a plot of the fundamental domain EXAMPLES:: @@ -2191,12 +2128,10 @@ def is_admissible(self, D): INPUT: - - ``D`` -- an integer whose squarefree part will define the + - ``D`` -- integer whose squarefree part will define the quadratic field - OUTPUT: - - A boolean describing whether the quadratic field is admissible + OUTPUT: boolean describing whether the quadratic field is admissible EXAMPLES:: @@ -2220,11 +2155,9 @@ def _local_splitting_map(self, prec): INPUT: - - ``prec`` -- Integer. The precision of the splitting. + - ``prec`` -- integer; the precision of the splitting - OUTPUT: - - A function giving the splitting. + OUTPUT: a function giving the splitting EXAMPLES:: @@ -2249,11 +2182,9 @@ def _local_splitting(self, prec): INPUT: - - ``prec`` -- Integer. The precision of the splitting. + - ``prec`` -- integer; the precision of the splitting - OUTPUT: - - - Matrices `I`, `J`, `K` giving the splitting. + OUTPUT: matrices `I`, `J`, `K` giving the splitting EXAMPLES:: @@ -2304,7 +2235,7 @@ def _compute_embedding_matrix(self, prec, force_computation=False): INPUT: - - ``prec`` -- Integer. The precision of the embedding matrix. + - ``prec`` -- integer; the precision of the embedding matrix EXAMPLES: @@ -2454,18 +2385,16 @@ def get_embedding_matrix(self, prec=None, exact=False): INPUT: - - ``exact`` boolean (Default: ``False``). If ``True``, return an + - ``exact`` -- boolean (default: ``False``); if ``True``, return an embedding into a matrix algebra with coefficients in a number field. Otherwise, embed into matrices over `p`-adic numbers. - - ``prec`` Integer (Default: ``None``). If specified, return the + - ``prec`` -- integer (default: ``None``); if specified, return the matrix with precision ``prec``. Otherwise, return the cached matrix (with the current working precision). - OUTPUT: - - - A 4x4 matrix representing the embedding. + OUTPUT: a 4x4 matrix representing the embedding EXAMPLES:: @@ -2525,11 +2454,11 @@ def embed_quaternion(self, g, exact=False, prec=None): INPUT: - - ``g`` a row vector of size `4` whose entries represent a - quaternion in our basis. + - ``g`` -- a row vector of size `4` whose entries represent a + quaternion in our basis - - ``exact`` boolean (default: ``False``) If True, tries to embed - ``g`` into a matrix algebra over a number field. If False, + - ``exact`` -- boolean (default: ``False``); if True, tries to embed + ``g`` into a matrix algebra over a number field. If ``False``, the target is the matrix algebra over `\QQ_p`. OUTPUT: @@ -2682,9 +2611,7 @@ def get_quaternion_algebra(self): r""" Return the underlying quaternion algebra. - OUTPUT: - - The underlying definite quaternion algebra + OUTPUT: the underlying definite quaternion algebra EXAMPLES:: @@ -2703,9 +2630,7 @@ def get_eichler_order(self, magma=False, force_computation=False): r""" Return the underlying Eichler order of level `N^+`. - OUTPUT: - - An Eichler order. + OUTPUT: an Eichler order EXAMPLES:: @@ -2734,9 +2659,7 @@ def get_maximal_order(self, magma=False, force_computation=False): Return the underlying maximal order containing the Eichler order. - OUTPUT: - - A maximal order. + OUTPUT: a maximal order EXAMPLES:: @@ -2792,9 +2715,7 @@ def get_eichler_order_basis(self): r""" Return a basis for the global Eichler order. - OUTPUT: - - Basis for the underlying Eichler order of level Nplus. + OUTPUT: basis for the underlying Eichler order of level Nplus EXAMPLES:: @@ -2815,9 +2736,7 @@ def get_eichler_order_quadform(self): Eichler order of level ``Nplus``. Required for finding elements in the arithmetic subgroup Gamma. - OUTPUT: - - The norm form of the underlying Eichler order + OUTPUT: the norm form of the underlying Eichler order EXAMPLES:: @@ -2841,9 +2760,7 @@ def get_eichler_order_quadmatrix(self): This function returns the matrix of the quadratic form of the underlying Eichler order in the fixed basis. - OUTPUT: - - A 4x4 integral matrix describing the norm form. + OUTPUT: a 4x4 integral matrix describing the norm form EXAMPLES:: @@ -2975,7 +2892,7 @@ def _get_hecke_data(self, l): INPUT: - - ``l`` -- a prime l. + - ``l`` -- a prime l EXAMPLES:: @@ -3069,15 +2986,15 @@ def _find_equivalent_vertex(self, v0, V=None, valuation=None): INPUT: - ``v0`` -- a 2x2 matrix in `\ZZ_p` representing a - vertex in the Bruhat-Tits tree. + vertex in the Bruhat-Tits tree - - ``V`` -- list (Default: None) If a list of Vertex is given, + - ``V`` -- list (default: ``None``); if a list of Vertex is given, restrict the search to the vertices in ``V``. Otherwise use all the vertices in a fundamental domain. - - ``valuation`` -- an integer (Default: None): The valuation + - ``valuation`` -- integer (default: ``None``); the valuation of the determinant of ``v0``, if known (otherwise it is - calculated). + calculated) OUTPUT: @@ -3117,13 +3034,13 @@ def _find_equivalent_edge(self, e0, E=None, valuation=None): INPUT: - ``e0`` -- a 2x2 matrix in `\ZZ_p` representing an - edge in the Bruhat-Tits tree. + edge in the Bruhat-Tits tree - - ``E`` -- list (Default: None) If a list of Edge is given, + - ``E`` -- list (default: ``None``); if a list of Edge is given, restrict the search to the vertices in ``E``. Otherwise use all the edges in a fundamental domain. - - ``valuation`` -- an integer (Default: None): The valuation + - ``valuation`` -- integer (default: ``None``); the valuation of the determinant of ``e0``, if known (otherwise it is calculated). @@ -3167,11 +3084,9 @@ def fundom_rep(self, v1): INPUT: - - ``v1`` -- a 2x2 matrix representing a normalized vertex. + - ``v1`` -- a 2x2 matrix representing a normalized vertex - OUTPUT: - - A ``Vertex`` equivalent to ``v1``, in the fundamental domain. + OUTPUT: a ``Vertex`` equivalent to ``v1``, in the fundamental domain EXAMPLES:: @@ -3206,18 +3121,16 @@ def _find_lattice(self, v1, v2, as_edges, m): INPUT: - - ``v1``, ``v2`` -- 2x2 matrices. They represent either a pair - of normalized vertices or a pair of normalized edges. + - ``v1``, ``v2`` -- 2x2 matrices; they represent either a pair + of normalized vertices or a pair of normalized edges - - ``as_edges`` -- boolean. If True, the inputs will be - considered as edges instead of vertices. + - ``as_edges`` -- boolean; if ``True``, the inputs will be + considered as edges instead of vertices - - ``m`` -- integer -- The valuation of the determinant of - ``v1``*``v2``. + - ``m`` -- integer; the valuation of the determinant of + ``v1``*``v2`` - OUTPUT: - - A 4x4 integer matrix whose columns encode a lattice and a 4x4 integer matrix encoding a quadratic form. + OUTPUT: a 4x4 integer matrix whose columns encode a lattice and a 4x4 integer matrix encoding a quadratic form EXAMPLES:: @@ -3252,9 +3165,9 @@ def _stabilizer(self, e, as_edge=True): INPUT: - - ``e`` -- A 2x2 matrix representing an edge or vertex + - ``e`` -- a 2x2 matrix representing an edge or vertex - - ``as_edge`` -- Boolean (Default = True). Determines whether + - ``as_edge`` -- boolean (default: ``True``); determines whether ``e`` is treated as an edge or vertex OUTPUT: @@ -3301,18 +3214,19 @@ def _nebentype_check(self, vec, twom, E, A, flag=2): INPUT: - - ``vec`` -- 4x1 integer matrix. It encodes the quaternion to - test in the basis defined by the columns of E. + - ``vec`` -- 4x1 integer matrix; it encodes the quaternion to + test in the basis defined by the columns of E - - ``twom`` -- An integer. + - ``twom`` -- integer - - ``E`` -- 4x4 integer matrix. Its columns should form a - basis for an order in the quaternion algebra. + - ``E`` -- 4x4 integer matrix; its columns should form a + basis for an order in the quaternion algebra - - ``A`` -- 4x4 integer matrix. It encodes the quadratic form on the order defined by the columns of E. + - ``A`` -- 4x4 integer matrix; it encodes the quadratic form on the + order defined by the columns of E - - ``flag`` -- integer (Default = 0). Passed to Pari for finding - minimal elements in a positive definite lattice. + - ``flag`` -- integer (default: 0); Passed to Pari for finding + minimal elements in a positive definite lattice OUTPUT: @@ -3370,19 +3284,19 @@ def _are_equivalent(self, v1, v2, as_edges=False, twom=None, - ``v1``, ``v2`` -- two 2x2 integral matrices representing either vertices or edges - - ``as_edges`` -- boolean (Default: False). Tells whether the - matrices should be interpreted as edges (if true), or as - vertices (if false) + - ``as_edges`` -- boolean (default: ``False``); whether the + matrices should be interpreted as edges (if ``True``), or as + vertices (if ``False``) - - ``twom`` -- integer (Default: None) If specified, + - ``twom`` -- integer (default: ``None``); if specified, indicates the valuation of the determinant of ``v1`` `\times` ``v2``. OUTPUT: - If the objects are equivalent, returns an element of - the arithmetic group Gamma that takes ``v1`` to ``v2``. - Otherwise returns False. + If the objects are equivalent, returns an element of + the arithmetic group `\Gamma` that takes ``v1`` to ``v2``. + Otherwise returns ``False``. EXAMPLES:: @@ -3514,9 +3428,7 @@ def _conv(self, v): Return a quaternion having coordinates in the fixed basis for the order given by ``v``. - OUTPUT: - - A quaternion. + OUTPUT: a quaternion EXAMPLES:: @@ -3541,13 +3453,13 @@ def _find_elements_in_order(self, norm, trace=None, primitive=False): INPUT: - - ``norm`` -- integer. The required reduced norm. + - ``norm`` -- integer; the required reduced norm - - ``trace`` -- integer (Default: None). If specified, returns - elements only reduced trace ``trace``. + - ``trace`` -- integer (default: ``None``); if specified, returns + elements only reduced trace ``trace`` - - ``primitive`` boolean (Default: False). If True, return only - elements that cannot be divided by `p`. + - ``primitive`` -- boolean (default: ``False``); if ``True``, return only + elements that cannot be divided by `p` EXAMPLES:: @@ -3572,7 +3484,7 @@ def _compute_quotient(self, check=True): INPUT: - - ``check`` -- Boolean (Default = True). + - ``check`` -- boolean (default: ``True``) EXAMPLES:: @@ -3728,12 +3640,10 @@ def harmonic_cocycle_from_elliptic_curve(self, E, prec=None): - ``E`` -- an elliptic curve over the rational numbers - - ``prec`` -- (default: None) If specified, the harmonic cocycle will take values + - ``prec`` -- (default: ``None``) if specified, the harmonic cocycle will take values in `\QQ_p` with precision ``prec``. Otherwise it will take values in `\ZZ`. - OUTPUT: - - A harmonic cocycle attached via modularity to the given elliptic curve. + OUTPUT: a harmonic cocycle attached via modularity to the given elliptic curve EXAMPLES:: @@ -3783,16 +3693,16 @@ def harmonic_cocycles(self, k, prec=None, basis_matrix=None, base_field=None): INPUT: - - ``k`` -- integer -- The weight. It must be even. + - ``k`` -- integer; the weight. It must be even. - - ``prec`` -- integer (default: None). If specified, the + - ``prec`` -- integer (default: ``None``); if specified, the precision for the coefficient module - - ``basis_matrix`` -- a matrix (default: None). + - ``basis_matrix`` -- a matrix (default: ``None``) - - ``base_field`` -- a ring (default: None) + - ``base_field`` -- a ring (default: ``None``) - OUTPUT: A space of harmonic cocycles + OUTPUT: a space of harmonic cocycles EXAMPLES:: @@ -3812,23 +3722,23 @@ def padic_automorphic_forms(self, U, prec=None, t=None, R=None, overconvergent=F INPUT: - - ``U`` -- A distributions module or an integer. If ``U`` is a + - ``U`` -- a distributions module or an integer. If ``U`` is a distributions module then this creates the relevant space of automorphic forms. If ``U`` is an integer then the coefficients are the (`U-2`)nd power of the symmetric representation of `GL_2(\QQ_p)`. - - ``prec`` -- A precision (default : None). If not None should - be a positive integer. + - ``prec`` -- a precision (default: ``None``). if not ``None`` should + be a positive integer - - ``t`` -- (default : None). The number of additional moments to store. If None, determine - it automatically from ``prec``, ``U`` and the ``overconvergent`` flag. + - ``t`` -- (default: ``None``) the number of additional moments to store. If ``None``, determine + it automatically from ``prec``, ``U`` and the ``overconvergent`` flag - - ``R`` -- (default : None). If specified, coefficient field of the automorphic forms. + - ``R`` -- (default: ``None``) if specified, coefficient field of the automorphic forms. If not specified it defaults to the base ring of the distributions ``U``, or to `\QQ_p` with the working precision ``prec``. - - ``overconvergent`` -- Boolean (default = False). If True, will construct overconvergent + - ``overconvergent`` -- boolean (default: ``False``); if ``True``, will construct overconvergent `p`-adic automorphic forms. Otherwise it constructs the finite dimensional space of `p`-adic automorphic forms which is isomorphic to the space of harmonic cocycles. diff --git a/src/sage/modular/btquotients/pautomorphicform.py b/src/sage/modular/btquotients/pautomorphicform.py index 992d5990b2b..54acfeeeaa9 100644 --- a/src/sage/modular/btquotients/pautomorphicform.py +++ b/src/sage/modular/btquotients/pautomorphicform.py @@ -94,9 +94,7 @@ def __call__(self, g): - ``g`` -- a 2x2 matrix - OUTPUT: - - A 4-tuple encoding the entries of ``g``. + OUTPUT: a 4-tuple encoding the entries of ``g`` EXAMPLES:: @@ -218,9 +216,7 @@ def _add_(self, g): - ``g`` -- a harmonic cocycle - OUTPUT: - - A harmonic cocycle + OUTPUT: a harmonic cocycle EXAMPLES:: @@ -241,9 +237,7 @@ def _sub_(self, g): - ``g`` -- a harmonic cocycle - OUTPUT: - - A harmonic cocycle + OUTPUT: a harmonic cocycle EXAMPLES:: @@ -266,9 +260,7 @@ def _lmul_(self, a): - ``a`` -- a ring element - OUTPUT: - - A harmonic cocycle + OUTPUT: a harmonic cocycle EXAMPLES:: @@ -284,11 +276,11 @@ def _lmul_(self, a): def _richcmp_(self, other, op): r""" - General comparison method for ``HarmonicCocycles`` + General comparison method for ``HarmonicCocycles``. INPUT: - - ``other`` -- Another harmonic cocycle + - ``other`` -- another harmonic cocycle EXAMPLES:: @@ -366,9 +358,7 @@ def valuation(self): Return the valuation of the cocycle, defined as the minimum of the values it takes on a set of representatives. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -478,20 +468,18 @@ def riemann_sum(self, f, center=1, level=0, E=None): INPUT: - - ``f`` -- a function on `\mathbf{P}^1(\QQ_p)`. + - ``f`` -- a function on `\mathbf{P}^1(\QQ_p)` - - ``center`` -- An integer (default = 1). Center of integration. + - ``center`` -- integer (default: 1); Center of integration - - ``level`` -- An integer (default = 0). Determines the size of + - ``level`` -- integer (default: 0); Determines the size of the covering when computing the Riemann sum. Runtime is exponential in the level. - - ``E`` -- A list of edges (default = None). They should describe - a covering of `\mathbf{P}^1(\QQ_p)`. + - ``E`` -- list of edges (default: ``None``); They should describe + a covering of `\mathbf{P}^1(\QQ_p)` - OUTPUT: - - A `p`-adic number. + OUTPUT: a `p`-adic number EXAMPLES:: @@ -536,14 +524,12 @@ def modular_form(self, z=None, level=0): INPUT: - ``z`` -- an element in the quadratic unramified extension of - `\QQ_p` that is not contained in `\QQ_p` (default = None). - - - ``level`` -- an integer. How fine of a mesh should the Riemann - sum use. + `\QQ_p` that is not contained in `\QQ_p` (default: ``None``) - OUTPUT: + - ``level`` -- integer; how fine of a mesh should the Riemann + sum use - An element of the quadratic unramified extension of `\QQ_p`. + OUTPUT: an element of the quadratic unramified extension of `\QQ_p` EXAMPLES:: @@ -578,7 +564,6 @@ def modular_form(self, z=None, level=0): sage: g = A.lift(g0).modular_form(method='moments') sage: (c*x + d)^4 * f(x) == f((a*x + b)/(c*x + d)) True - """ return self.derivative(z, level, order=0) @@ -602,13 +587,13 @@ def derivative(self, z=None, level=0, order=1): INPUT: - ``z`` -- an element in the quadratic unramified extension of - `\QQ_p` that is not contained in `\QQ_p` (default = None). If ``z - = None`` then a function encoding the derivative is returned. + `\QQ_p` that is not contained in `\QQ_p` (default: ``None``); if + ``z = None`` then a function encoding the derivative is returned. - - ``level`` -- an integer. How fine of a mesh should the Riemann - sum use. + - ``level`` -- integer; how fine of a mesh should the Riemann + sum use - - ``order`` -- an integer. How many derivatives to take. + - ``order`` -- integer; how many derivatives to take OUTPUT: @@ -627,7 +612,6 @@ def derivative(self, z=None, level=0, order=1): (2*a + 2)*3 + (a + 2)*3^2 + 2*a*3^3 + 2*3^4 + O(3^5) sage: b.derivative(a,level=2,order=1) (2*a + 2)*3 + 2*a*3^2 + 3^3 + a*3^4 + O(3^5) - """ def F(z): R = PolynomialRing(z.parent(), 'x,y').fraction_field() @@ -653,7 +637,7 @@ def F(z): class BruhatTitsHarmonicCocycles(AmbientHeckeModule, UniqueRepresentation): r""" - Ensure unique representation + Ensure unique representation. EXAMPLES:: @@ -673,16 +657,16 @@ def __classcall__(cls, X, k, prec=None, basis_matrix=None, base_field=None): INPUT: - - ``X`` -- A BruhatTitsQuotient object + - ``X`` -- a BruhatTitsQuotient object - - ``k`` -- integer -- The weight. It must be even. + - ``k`` -- integer; the weight. It must be even. - - ``prec`` -- integer (default: None). If specified, the + - ``prec`` -- integer (default: ``None``); if specified, the precision for the coefficient module - - ``basis_matrix`` -- a matrix (default: None). + - ``basis_matrix`` -- a matrix (default: ``None``) - - ``base_field`` -- a ring (default: None) + - ``base_field`` -- a ring (default: ``None``) EXAMPLES:: @@ -785,9 +769,7 @@ def base_extend(self, base_ring): - ``base_ring`` -- a ring that has a coerce map from the current base ring - OUTPUT: - - A new space of HarmonicCocycles with the base extended. + OUTPUT: a new space of HarmonicCocycles with the base extended EXAMPLES:: @@ -813,9 +795,7 @@ def change_ring(self, new_base_ring): - ``new_base_ring`` -- a ring that has a coerce map from the current base ring - OUTPUT: - - New space of HarmonicCocycles with different base ring + OUTPUT: new space of HarmonicCocycles with different base ring EXAMPLES:: @@ -826,7 +806,6 @@ def change_ring(self, new_base_ring): sage: H1 = H.base_extend(Qp(5,prec=15)) # indirect doctest sage: H1.base_ring() 5-adic Field with capped relative precision 15 - """ if not new_base_ring.has_coerce_map_from(self.base_ring()): raise ValueError("No coercion defined") @@ -841,9 +820,7 @@ def rank(self): r""" Return the rank (dimension) of ``self``. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -863,13 +840,11 @@ def submodule(self, v, check=False): INPUT: - - ``v`` -- Submodule of self.free_module(). - - - ``check`` -- Boolean (default = False). + - ``v`` -- submodule of ``self.free_module()`` - OUTPUT: + - ``check`` -- boolean (default: ``False``) - Subspace of harmonic cocycles. + OUTPUT: subspace of harmonic cocycles EXAMPLES:: @@ -891,9 +866,7 @@ def is_simple(self): r""" Whether ``self`` is irreducible. - OUTPUT: - - Boolean. True if and only if ``self`` is irreducible. + OUTPUT: boolean; ``True`` if and only if ``self`` is irreducible EXAMPLES:: @@ -914,7 +887,7 @@ def is_simple(self): def _repr_(self): r""" - This returns the representation of self as a string. + This returns the representation of ``self`` as a string. EXAMPLES:: @@ -944,11 +917,9 @@ def _latex_(self): def _an_element_(self): r""" - Return an element of the ambient space + Return an element of the ambient space. - OUTPUT: - - A harmonic cocycle in self. + OUTPUT: a harmonic cocycle in self EXAMPLES:: @@ -962,12 +933,10 @@ def _an_element_(self): def _coerce_map_from_(self, S): r""" Can coerce from other BruhatTitsHarmonicCocycles or from - pAdicAutomorphicForms, also from 0 + pAdicAutomorphicForms, also from 0. - OUTPUT: - - Boolean. True if and only if ``self`` is a space of - BruhatTitsHarmonicCocycles or pAdicAutomorphicForms. + OUTPUT: boolean; ``True`` if and only if ``self`` is a space of + BruhatTitsHarmonicCocycles or pAdicAutomorphicForms EXAMPLES:: @@ -991,11 +960,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- a BruhatTitsHarmonicCocycles class. + - ``other`` -- a BruhatTitsHarmonicCocycles class - OUTPUT: - - A boolean value + OUTPUT: boolean EXAMPLES:: @@ -1018,11 +985,9 @@ def __ne__(self, other): INPUT: - - ``other`` -- a BruhatTitsHarmonicCocycles class. - - OUTPUT: + - ``other`` -- a BruhatTitsHarmonicCocycles class - A boolean value + OUTPUT: boolean EXAMPLES:: @@ -1054,11 +1019,9 @@ def _element_constructor_(self, x): INPUT: - - ``x`` -- an object coercible into a harmonic cocycle. - - OUTPUT: + - ``x`` -- an object coercible into a harmonic cocycle - A harmonic cocycle. + OUTPUT: a harmonic cocycle EXAMPLES:: @@ -1094,11 +1057,9 @@ def _element_constructor_(self, x): def free_module(self): r""" - Return the underlying free module + Return the underlying free module. - OUTPUT: - - A free module. + OUTPUT: a free module EXAMPLES:: @@ -1120,9 +1081,7 @@ def character(self): r""" The trivial character. - OUTPUT: - - The identity map. + OUTPUT: the identity map EXAMPLES:: @@ -1142,11 +1101,9 @@ def embed_quaternion(self, g, scale=1, exact=None): INPUT: - - ``g`` -- A quaternion, expressed as a 4x1 matrix. + - ``g`` -- a quaternion, expressed as a 4x1 matrix - OUTPUT: - - A 2x2 matrix with `p`-adic entries. + OUTPUT: a 2x2 matrix with `p`-adic entries EXAMPLES:: @@ -1255,18 +1212,18 @@ def basis_matrix(self): def __apply_atkin_lehner(self, q, f): r""" - Apply an Atkin-Lehner involution to a harmonic cocycle + Apply an Atkin-Lehner involution to a harmonic cocycle. INPUT: - - ``q`` -- an integer dividing the full level p*Nminus*Nplus + - ``q`` -- integer dividing the full level ``p*Nminus*Nplus`` - ``f`` -- a harmonic cocycle OUTPUT: - - The harmonic cocycle obtained by hitting ``f`` with the - Atkin-Lehner at ``q`` + The harmonic cocycle obtained by hitting ``f`` with the + Atkin-Lehner at ``q``. EXAMPLES:: @@ -1297,14 +1254,14 @@ def __apply_hecke_operator(self, l, f): INPUT: - - ``l`` -- an integer + - ``l`` -- integer - ``f`` -- a harmonic cocycle OUTPUT: - - A harmonic cocycle which is the result of applying the lth - Hecke operator to ``f`` + A harmonic cocycle which is the result of applying the `l`-th + Hecke operator to ``f``. EXAMPLES:: @@ -1341,13 +1298,13 @@ def _compute_atkin_lehner_matrix(self, d): INPUT: - - ``d`` -- an integer dividing p*Nminus*Nplus, where these - quantities are associated to the BruhatTitsQuotient self._X + - ``d`` -- integer dividing ``p*Nminus*Nplus``, where these + quantities are associated to the BruhatTitsQuotient ``self._X`` OUTPUT: - - The matrix of the Atkin-Lehner involution at ``d`` in the basis given by - self.basis_matrix + The matrix of the Atkin-Lehner involution at ``d`` in the basis given by + ``self.basis_matrix``. EXAMPLES:: @@ -1367,12 +1324,12 @@ def _compute_hecke_matrix_prime(self, l): INPUT: - - ``l`` -- a prime integer + - ``l`` -- prime integer OUTPUT: - - The matrix of `T_l` acting on the cocycles in the basis given by - self.basis_matrix + The matrix of `T_l` acting on the cocycles in the basis given by + ``self.basis_matrix``. EXAMPLES:: @@ -1393,11 +1350,9 @@ def __compute_operator_matrix(self, T): INPUT: - - ``T`` -- A linear function on the space of harmonic cocycles. - - OUTPUT: + - ``T`` -- a linear function on the space of harmonic cocycles - The matrix of ``T`` acting on the space of harmonic cocycles. + OUTPUT: the matrix of ``T`` acting on the space of harmonic cocycles EXAMPLES:: @@ -1440,11 +1395,9 @@ def __compute_operator_matrix(self, T): # # INPUT: # -# - ``x`` -- integer (default: 1) the description of the -# argument x goes here. If it contains multiple lines, all -# the lines after the first need to be indented. +# - ``x`` -- integer (default: 1) # -# - ``y`` -- integer (default: 2) the ... +# - ``y`` -- integer (default: 2) # # EXAMPLES:: # @@ -1467,9 +1420,9 @@ def __compute_operator_matrix(self, T): # # - ``ambient_module`` -- BruhatTitsHarmonicCocycles # -# - ``submodule`` -- submodule of the ambient space. +# - ``submodule`` -- submodule of the ambient space # -# - ``check`` -- (default: ``False``) whether to check that the +# - ``check`` -- boolean (default: ``False``); whether to check that the # submodule is Hecke equivariant # # EXAMPLES:: @@ -1536,7 +1489,7 @@ class pAdicAutomorphicFormElement(ModuleElement): INPUT: - - ``vec`` -- A preformatted list of data + - ``vec`` -- a preformatted list of data EXAMPLES:: @@ -1555,7 +1508,7 @@ class pAdicAutomorphicFormElement(ModuleElement): """ def __init__(self, parent, vec): """ - Create a pAdicAutomorphicFormElement + Create a pAdicAutomorphicFormElement. EXAMPLES:: @@ -1577,9 +1530,7 @@ def _add_(self, g): - ``g`` -- a `p`-adic automorphic form - OUTPUT: - - - the result of adding ``g`` to self + OUTPUT: the result of adding ``g`` to ``self`` EXAMPLES:: @@ -1602,9 +1553,7 @@ def _sub_(self, g): - ``g`` -- a `p`-adic automorphic form - OUTPUT: - - - the result of subtracting ``g`` from self + OUTPUT: the result of subtracting ``g`` from ``self`` EXAMPLES:: @@ -1623,11 +1572,11 @@ def _sub_(self, g): def _richcmp_(self, other, op): r""" - Test for equality of pAdicAutomorphicForm elements + Test for equality of pAdicAutomorphicForm elements. INPUT: - - ``other`` -- Another `p`-automorphic form + - ``other`` -- another `p`-automorphic form EXAMPLES:: @@ -1652,9 +1601,7 @@ def __bool__(self): """ Tell whether the form is zero or not. - OUTPUT: - - Boolean. ``True`` if self is zero, ``False`` otherwise. + OUTPUT: boolean; whether ``self`` is zero EXAMPLES:: @@ -1678,9 +1625,7 @@ def __getitem__(self, e1): - ``e1`` -- a matrix in `GL_2(\QQ_p)` - OUTPUT: - - - the value of self evaluated on ``e1`` + OUTPUT: the value of ``self`` evaluated on ``e1`` EXAMPLES:: @@ -1701,9 +1646,7 @@ def evaluate(self, e1): - ``e1`` -- a matrix in `GL_2(\QQ_p)` - OUTPUT: - - - the value of self evaluated on ``e1`` + OUTPUT: the value of ``self`` evaluated on ``e1`` EXAMPLES:: @@ -1730,7 +1673,7 @@ def _lmul_(self, a): INPUT: - - a scalar + - ``a`` -- a scalar EXAMPLES:: @@ -1750,15 +1693,11 @@ def _lmul_(self, a): def _repr_(self): r""" - This returns the representation of self as a string. + This returns the representation of ``self`` as a string. - If self corresponds to a modular form of weight `k`, then the + If ``self`` corresponds to a modular form of weight `k`, then the cohomological weight is `k-2`. - OUTPUT: - - A string. - EXAMPLES:: sage: X = BruhatTitsQuotient(17,3) @@ -1775,9 +1714,7 @@ def valuation(self): valuations of the values that it takes on a set of edge representatives. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -1821,7 +1758,6 @@ def _improve(self, hc): - Cameron Franc (2012-02-20) - Marc Masdeu - """ MMM = self.parent() U = MMM._U @@ -1857,14 +1793,14 @@ def integrate(self, f, center=1, level=0, method='moments'): INPUT: - - ``f`` -- An analytic function. + - ``f`` -- an analytic function - ``center`` -- 2x2 matrix over `\QQ_p` (default: 1) - ``level`` -- integer (default: 0) - - ``method`` -- string (default: 'moments'). Which method of - integration to use. Either 'moments' or 'riemann_sum'. + - ``method`` -- string (default: ``'moments'``); which method of + integration to use. Either ``'moments'`` or ``'riemann_sum'``. EXAMPLES: @@ -1940,22 +1876,22 @@ def modular_form(self, z=None, level=0, method='moments'): INPUT: - - ``z`` -- (default: None). If specified, returns the value of + - ``z`` -- (default: ``None``) if specified, returns the value of the form at the point ``z`` in the `p`-adic upper half - plane. + plane - - ``level`` -- integer (default: 0). If ``method`` is + - ``level`` -- integer (default: 0); if ``method`` is 'riemann_sum', will use a covering of `P^1(\QQ_p)` with - balls of size `p^-\mbox{level}`. + balls of size `p^-\mbox{level}` - - ``method`` -- string (default: ``moments``). It must be - either ``moments`` or ``riemann_sum``. + - ``method`` -- string (default: ``'moments'``); it must be + either ``'moments'`` or ``'riemann_sum'`` OUTPUT: - - A function from the `p`-adic upper half plane to `\CC_p`. If - an argument ``z`` was passed, returns instead the value at - that point. + A function from the `p`-adic upper half plane to `\CC_p`. If + an argument ``z`` was passed, returns instead the value at + that point. EXAMPLES: @@ -1999,24 +1935,24 @@ def derivative(self, z=None, level=0, method='moments', order=1): INPUT: - - ``z`` -- (default: None). If specified, evaluates the derivative - at the point ``z`` in the `p`-adic upper half plane. + - ``z`` -- (default: ``None``) if specified, evaluates the derivative + at the point ``z`` in the `p`-adic upper half plane - - ``level`` -- integer (default: 0). If ``method`` is + - ``level`` -- integer (default: 0); if ``method`` is 'riemann_sum', will use a covering of `P^1(\QQ_p)` with balls of size `p^-\mbox{level}`. - - ``method`` -- string (default: ``moments``). It must be - either ``moments`` or ``riemann_sum``. + - ``method`` -- string (default: ``'moments'``); it must be + either ``'moments'`` or ``'riemann_sum'`` - - ``order`` -- integer (default: 1). The order of the - derivative to be computed. + - ``order`` -- integer (default: 1); the order of the + derivative to be computed OUTPUT: - - A function from the `p`-adic upper half plane to `\CC_p`. If - an argument ``z`` was passed, returns instead the value of - the derivative at that point. + A function from the `p`-adic upper half plane to `\CC_p`. If + an argument ``z`` was passed, returns instead the value of + the derivative at that point. EXAMPLES: @@ -2059,7 +1995,6 @@ def derivative(self, z=None, level=0, method='moments', order=1): sage: f = f0.derivative() sage: (c*x + d)^4*f(x)-f((a*x + b)/(c*x + d)) O(7^5) - """ def F(z, level=level, method=method): R = PolynomialRing(z.parent(), 'x,y').fraction_field() @@ -2097,22 +2032,20 @@ def coleman(self, t1, t2, E=None, method='moments', mult=False): - ``t1``, ``t2`` -- elements of `P^1(\QQ_p)` (the endpoints of integration) - - ``E`` -- (default: None). If specified, will not compute the + - ``E`` -- (default: ``None``) if specified, will not compute the covering adapted to ``t1`` and ``t2`` and instead use the given one. In that case, ``E`` should be a list of matrices corresponding to edges describing the open balls to be considered. - - ``method`` -- string (default: 'moments'). Tells which - algorithm to use (alternative is 'riemann_sum', which is + - ``method`` -- string (default: ``'moments'``); tells which + algorithm to use (alternative is ``'riemann_sum'``, which is unsuitable for computations requiring high precision) - - ``mult`` -- boolean (default: ``False``). Whether to compute the - multiplicative version. + - ``mult`` -- boolean (default: ``False``); whether to compute the + multiplicative version - OUTPUT: - - The result of the Coleman integral + OUTPUT: the result of the Coleman integral EXAMPLES:: @@ -2201,25 +2134,26 @@ def __classcall__(cls, domain, U, prec=None, t=None, R=None, INPUT: - - ``domain`` -- A BruhatTitsQuotient. + - ``domain`` -- a BruhatTitsQuotient - - ``U`` -- A distributions module or an integer. If ``U`` is a + - ``U`` -- a distributions module or an integer. If ``U`` is a distributions module then this creates the relevant space of automorphic forms. If ``U`` is an integer then the coefficients are the (`U-2`)nd power of the symmetric representation of `GL_2(\QQ_p)`. - - ``prec`` -- A precision (default : None). If not None should - be a positive integer. + - ``prec`` -- a precision (default: ``None``); if not ``None`` should + be a positive integer - - ``t`` -- (default : None). The number of additional moments to store. If None, determine - it automatically from ``prec``, ``U`` and the ``overconvergent`` flag. + - ``t`` -- (default: ``None``) the number of additional moments to + store. If ``None``, determine it automatically from ``prec``, ``U`` + and the ``overconvergent`` flag. - - ``R`` -- (default : None). If specified, coefficient field of the automorphic forms. + - ``R`` -- (default: ``None``) if specified, coefficient field of the automorphic forms. If not specified it defaults to the base ring of the distributions ``U``, or to `Q_p` with the working precision ``prec``. - - ``overconvergent`` -- Boolean (default = False). If True, will construct overconvergent + - ``overconvergent`` -- boolean (default: ``False``); if ``True``, will construct overconvergent `p`-adic automorphic forms. Otherwise it constructs the finite dimensional space of `p`-adic automorphic forms which is isomorphic to the space of harmonic cocycles. @@ -2246,7 +2180,7 @@ def __classcall__(cls, domain, U, prec=None, t=None, R=None, def __init__(self, domain, U, prec=None, t=None, R=None, overconvergent=False): """ - Create a space of `p`-automorphic forms + Create a space of `p`-automorphic forms. EXAMPLES:: @@ -2300,9 +2234,7 @@ def prime(self): """ Return the underlying prime. - OUTPUT: - - - ``p`` -- a prime integer + OUTPUT: ``p`` -- prime integer EXAMPLES:: @@ -2333,11 +2265,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- another space of `p`-automorphic forms. - - OUTPUT: + - ``other`` -- another space of `p`-automorphic forms - A boolean value + OUTPUT: boolean EXAMPLES:: @@ -2360,11 +2290,9 @@ def __ne__(self, other): INPUT: - - ``other`` -- another space of `p`-automorphic forms. - - OUTPUT: + - ``other`` -- another space of `p`-automorphic forms - A boolean value + OUTPUT: boolean EXAMPLES:: @@ -2392,7 +2320,7 @@ def __hash__(self): def _repr_(self): r""" - Return the representation of self as a string. + Return the representation of ``self`` as a string. EXAMPLES:: @@ -2408,15 +2336,13 @@ def _repr_(self): def _coerce_map_from_(self, S): r""" - Can coerce from other BruhatTitsHarmonicCocycles or from pAdicAutomorphicForms + Can coerce from other BruhatTitsHarmonicCocycles or from pAdicAutomorphicForms. INPUT: - ``S`` -- a BruhatTitsHarmonicCocycle or pAdicAutomorphicForm - OUTPUT: - - A boolean value. True if and only if ``S`` is coercible into self. + OUTPUT: boolean; ``True`` if and only if `S` is coercible into ``self`` EXAMPLES:: @@ -2447,11 +2373,9 @@ def _element_constructor_(self, data): INPUT: - ``data`` -- defining data. Can be either a harmonic cocycle, or a `p`-adic automorphic form, - or a list of elements coercible into the module of coefficients of ``self``. + or a list of elements coercible into the module of coefficients of ``self`` - OUTPUT: - - A `p`-adic automorphic form. + OUTPUT: a `p`-adic automorphic form EXAMPLES:: @@ -2492,9 +2416,7 @@ def _an_element_(self): r""" Return an element of the module. - OUTPUT: - - A harmonic cocycle. + OUTPUT: a harmonic cocycle EXAMPLES:: @@ -2507,11 +2429,9 @@ def _an_element_(self): def precision_cap(self): """ - Return the precision of self. - - OUTPUT: + Return the precision of ``self``. - An integer. + OUTPUT: integer EXAMPLES:: @@ -2533,9 +2453,7 @@ def lift(self, f): - ``f`` -- a harmonic cocycle - OUTPUT: - - A `p`-adic automorphic form + OUTPUT: a `p`-adic automorphic form EXAMPLES: @@ -2569,11 +2487,9 @@ def _make_invariant(self, F): INPUT: - ``F`` -- a classical (nonoverconvergent) pAdicAutomorphicForm or - BruhatTitsHarmonicCocycle. - - OUTPUT: + BruhatTitsHarmonicCocycle - An overconvergent pAdicAutomorphicForm + OUTPUT: an overconvergent pAdicAutomorphicForm EXAMPLES:: @@ -2611,9 +2527,9 @@ def _apply_Up_operator(self, f, scale=False, original_moments=None): INPUT: - - f -- a `p`-adic automorphic form. - - scale -- (default: ``True``) whether to scale by the appropriate power of `p` - at each iteration. + - ``f`` -- a `p`-adic automorphic form + - ``scale`` -- boolean (default: ``True``); whether to scale by the appropriate power of `p` + at each iteration EXAMPLES:: diff --git a/src/sage/modular/buzzard.py b/src/sage/modular/buzzard.py index 72e72e745cc..6c88bfcf172 100644 --- a/src/sage/modular/buzzard.py +++ b/src/sage/modular/buzzard.py @@ -18,30 +18,12 @@ # # https://www.gnu.org/licenses/ ############################################################################# +from pathlib import Path -from sage.interfaces.gp import Gp -from sage.misc.sage_eval import sage_eval +from sage.env import SAGE_EXTCODE +from sage.libs.pari import pari -_gp = None - - -def gp(): - r""" - Return a copy of the GP interpreter with the appropriate files loaded. - - EXAMPLES:: - - sage: import sage.modular.buzzard - sage: sage.modular.buzzard.gp() - PARI/GP interpreter - """ - global _gp - if _gp is None: - _gp = Gp(script_subdirectory='buzzard') - _gp.read("DimensionSk.g") - _gp.read("genusn.g") - _gp.read("Tpprog.g") - return _gp +buzzard_dir = Path(SAGE_EXTCODE) / "pari" / "buzzard" # def buzzard_dimension_cusp_forms(eps, k): # r""" @@ -73,7 +55,7 @@ def gp(): def buzzard_tpslopes(p, N, kmax): r""" - Return a vector of length kmax, whose `k`'th entry + Return a vector of length kmax, whose `k`-th entry (`0 \leq k \leq k_{max}`) is the conjectural sequence of valuations of eigenvalues of `T_p` on forms of level `N`, weight `k`, and trivial character. @@ -86,6 +68,7 @@ def buzzard_tpslopes(p, N, kmax): sage: from sage.modular.buzzard import buzzard_tpslopes sage: c = buzzard_tpslopes(2,1,50) + ... sage: c[50] [4, 8, 13] @@ -107,7 +90,10 @@ def buzzard_tpslopes(p, N, kmax): - William Stein (2006-03-17): small Sage wrapper of Buzzard's scripts """ - v = gp().eval('tpslopes(%s, %s, %s)' % (p, N, kmax)) - v = sage_eval(v) - v.insert(0, []) # so v[k] = info about weight k (since python is 0-based) + pari.read(buzzard_dir / "DimensionSk.g") + pari.read(buzzard_dir / "genusn.g") + pari.read(buzzard_dir / "Tpprog.g") + # v = pari.tpslopes(p, N, kmax).sage() + v = pari('tpslopes(%s, %s, %s)' % (p, N, kmax)).sage() + v.insert(0, []) # so that v[k] = info about weight k return v diff --git a/src/sage/modular/cusps.py b/src/sage/modular/cusps.py index 27b13298e18..7a4a2628096 100644 --- a/src/sage/modular/cusps.py +++ b/src/sage/modular/cusps.py @@ -317,7 +317,7 @@ def _richcmp_(self, right, op): def is_infinity(self): """ - Returns True if this is the cusp infinity. + Return ``True`` if this is the cusp infinity. EXAMPLES:: @@ -470,28 +470,28 @@ def __neg__(self): def is_gamma0_equiv(self, other, N, transformation=None): r""" - Return whether self and other are equivalent modulo the action of + Return whether ``self`` and ``other`` are equivalent modulo the action of `\Gamma_0(N)` via linear fractional transformations. INPUT: + - ``other`` -- cusp - - ``other`` -- Cusp - - - ``N`` -- an integer (specifies the group - Gamma_0(N)) - - - ``transformation`` -- None (default) or either the string 'matrix' or 'corner'. If 'matrix', - it also returns a matrix in Gamma_0(N) that sends self to other. The matrix is chosen such that the lower left entry is as small as possible in absolute value. If 'corner' (or True for backwards compatibility), it returns only the upper left entry of such a matrix. + - ``N`` -- integer (specifies the group `\Gamma_0(N)`) + - ``transformation`` -- ``None`` (default) or either the string 'matrix' or + ``'corner'``. If ``'matrix'``, it also returns a matrix in `\Gamma_0(N)` that + sends ``self`` to ``other``. The matrix is chosen such that the lower + left entry is as small as possible in absolute value. If ``'corner'`` (or + ``True`` for backwards compatibility), it returns only the upper left + entry of such a matrix. OUTPUT: + - a boolean -- ``True`` if ``self`` and ``other`` are equivalent - - a boolean -- True if self and other are equivalent - - - a matrix or an integer- returned only if transformation is 'matrix' or 'corner', respectively. - + - a matrix or an integer -- returned only if transformation is 'matrix' + or 'corner', respectively EXAMPLES:: @@ -650,31 +650,26 @@ def is_gamma0_equiv(self, other, N, transformation=None): return (True, A) def is_gamma1_equiv(self, other, N): - """ - Return whether self and other are equivalent modulo the action of - Gamma_1(N) via linear fractional transformations. + r""" + Return whether ``self`` and ``other`` are equivalent modulo the action of + `\Gamma_1(N)` via linear fractional transformations. INPUT: + - ``other`` -- cusp - - ``other`` -- Cusp - - - ``N`` -- an integer (specifies the group - Gamma_1(N)) - + - ``N`` -- integer (specifies the group `\Gamma_1(N)`) OUTPUT: + - ``bool`` -- ``True`` if ``self`` and ``other`` are equivalent - - ``bool`` -- True if self and other are equivalent - - - ``int`` -- 0, 1 or -1, gives further information - about the equivalence: If the two cusps are u1/v1 and u2/v2, then - they are equivalent if and only if v1 = v2 (mod N) and u1 = u2 (mod - gcd(v1,N)) or v1 = -v2 (mod N) and u1 = -u2 (mod gcd(v1,N)) The - sign is +1 for the first and -1 for the second. If the two cusps - are not equivalent then 0 is returned. - + - ``int`` -- 0, 1 or -1, gives further information + about the equivalence: If the two cusps are u1/v1 and u2/v2, then + they are equivalent if and only if v1 = v2 (mod N) and u1 = u2 (mod + gcd(v1,N)) or v1 = -v2 (mod N) and u1 = -u2 (mod gcd(v1,N)) The + sign is +1 for the first and -1 for the second. If the two cusps + are not equivalent then 0 is returned. EXAMPLES:: @@ -711,9 +706,9 @@ def is_gamma1_equiv(self, other, N): def is_gamma_h_equiv(self, other, G): r""" - Return a pair (b, t), where b is True or False as self and other - are equivalent under the action of G, and t is 1 or -1, as - described below. + Return a pair ``(b, t)``, where ``b`` is ``True`` or ``False`` as + ``self`` and ``other`` are equivalent under the action of `G`, and `t` + is 1 or -1, as described below. Two cusps `u1/v1` and `u2/v2` are equivalent modulo Gamma_H(N) if and only if `v1 = h*v2 (\mathrm{mod} N)` and @@ -725,19 +720,15 @@ def is_gamma_h_equiv(self, other, G): INPUT: + - ``other`` -- cusp - - ``other`` -- Cusp - - - ``G`` -- a congruence subgroup Gamma_H(N) - + - ``G`` -- a congruence subgroup Gamma_H(N) OUTPUT: + - ``bool`` -- ``True`` if ``self`` and ``other`` are equivalent - - ``bool`` -- True if self and other are equivalent - - - ``int`` -- -1, 0, 1; extra info - + - ``int`` -- -1, 0, 1; extra info EXAMPLES:: @@ -807,7 +798,7 @@ def is_gamma_h_equiv(self, other, G): def _acted_upon_(self, g, self_on_left): r""" - Implement the left action of `SL_2(\ZZ)` on self. + Implement the left action of `SL_2(\ZZ)` on ``self``. EXAMPLES:: @@ -873,13 +864,11 @@ def galois_action(self, t, N): INPUT: - - `t` -- integer that is coprime to N - - - `N` -- positive integer (level) + - ``t`` -- integer that is coprime to N - OUTPUT: + - ``N`` -- positive integer (level) - - a cusp + OUTPUT: a cusp .. WARNING:: @@ -964,7 +953,6 @@ def galois_action(self, t, N): AUTHORS: - William Stein, 2009-04-18 - """ if self.is_infinity(): return self @@ -1066,7 +1054,7 @@ def _repr_(self): def _latex_(self): r""" - Return latex representation of self. + Return latex representation of ``self``. EXAMPLES:: diff --git a/src/sage/modular/cusps_nf.py b/src/sage/modular/cusps_nf.py index 9cf9bc3e7b8..4d120c075da 100644 --- a/src/sage/modular/cusps_nf.py +++ b/src/sage/modular/cusps_nf.py @@ -94,7 +94,7 @@ def list_of_representatives(N): INPUT: - - ``N`` -- an ideal of a number field. + - ``N`` -- an ideal of a number field OUTPUT: @@ -124,9 +124,7 @@ def NFCusps(number_field): - ``number_field`` -- a number field - OUTPUT: - - The set of cusps over the given number field. + OUTPUT: the set of cusps over the given number field EXAMPLES:: @@ -238,13 +236,12 @@ def _repr_(self): Number Field Cusps sage: kCusps.rename(); kCusps Set of all cusps of Number Field in a with defining polynomial x^2 + 2 - """ return "Set of all cusps of %s" % self.number_field() def _latex_(self): r""" - Return latex representation of self. + Return latex representation of ``self``. EXAMPLES:: @@ -332,13 +329,13 @@ class NFCusp(Element): INPUT: - - ``number_field`` -- the number field over which the cusp is defined. + - ``number_field`` -- the number field over which the cusp is defined - ``a`` -- it can be a number field element (integral or not), or - a number field cusp. + a number field cusp - ``b`` -- (optional) when present, it must be either Infinity or - coercible to an element of the number field. + coercible to an element of the number field - ``lreps`` -- (optional) a list of chosen representatives for all the ideal classes of the field. When given, the representative of the cusp @@ -786,8 +783,8 @@ def apply(self, g): INPUT: - - ``g`` -- a list of integral elements [a, b, c, d] that are the - entries of a 2x2 matrix. + - ``g`` -- list of integral elements [a, b, c, d] that are the + entries of a 2x2 matrix OUTPUT: @@ -911,13 +908,11 @@ def is_Gamma0_equivalent(self, other, N, Transformation=False): INPUT: - ``other`` -- a number field cusp or a list of two number field - elements which define a cusp. + elements which define a cusp - ``N`` -- an ideal of the number field (level) - OUTPUT: - - - bool -- ``True`` if the cusps are equivalent. + OUTPUT: boolean; ``True`` if the cusps are equivalent - a transformation matrix -- (if ``Transformation=True``) a list of integral elements [a, b, c, d] which are the entries of a 2x2 matrix @@ -1029,11 +1024,9 @@ def Gamma0_NFCusps(N): INPUT: - - ``N`` -- an integral ideal of the number field k (the level). + - ``N`` -- an integral ideal of the number field k (the level) - OUTPUT: - - A list of inequivalent number field cusps. + OUTPUT: list of inequivalent number field cusps EXAMPLES:: @@ -1122,11 +1115,9 @@ def number_of_Gamma0_NFCusps(N): INPUT: - - ``N`` -- a number field ideal. - - OUTPUT: + - ``N`` -- a number field ideal - integer -- the number of orbits of cusps under Gamma0(N)-action. + OUTPUT: integer; the number of orbits of cusps under Gamma0(N)-action EXAMPLES:: @@ -1164,10 +1155,10 @@ def NFCusps_ideal_reps_for_levelN(N, nlists=1): INPUT: - - ``N`` -- number field ideal. + - ``N`` -- number field ideal - - ``nlists`` -- optional (default 1). The number of lists of prime ideals - we want. + - ``nlists`` -- (default: 1) the number of lists of prime ideals + we want OUTPUT: @@ -1223,7 +1214,7 @@ def units_mod_ideal(I): INPUT: - - ``I`` -- number field ideal. + - ``I`` -- number field ideal OUTPUT: diff --git a/src/sage/modular/dims.py b/src/sage/modular/dims.py index 3f246ad93ad..7eef7392e76 100644 --- a/src/sage/modular/dims.py +++ b/src/sage/modular/dims.py @@ -69,7 +69,7 @@ def eisen(p): - ``p`` -- a prime - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -96,13 +96,13 @@ def CO_delta(r, p, N, eps): INPUT: - - ``r`` -- positive integer + - ``r`` -- positive integer - - ``p`` -- a prime + - ``p`` -- a prime - - ``N`` -- positive integer + - ``N`` -- positive integer - - ``eps`` -- character + - ``eps`` -- character OUTPUT: element of the base ring of the character @@ -140,13 +140,13 @@ def CO_nu(r, p, N, eps): INPUT: - - ``r`` -- positive integer + - ``r`` -- positive integer - - ``p`` -- a prime + - ``p`` -- a prime - - ``N`` -- positive integer + - ``N`` -- positive integer - - ``eps`` -- character + - ``eps`` -- character OUTPUT: element of the base ring of the character @@ -185,11 +185,11 @@ def CohenOesterle(eps, k): INPUT: - - ``eps`` -- Dirichlet character + - ``eps`` -- Dirichlet character - - ``k`` -- integer + - ``k`` -- integer - OUTPUT: element of the base ring of eps. + OUTPUT: element of the base ring of eps EXAMPLES:: @@ -219,9 +219,9 @@ def _lambda(r, s, p): INPUT: - - ``r, s, p`` -- integers + - ``r``, ``s``, ``p`` -- integers - OUTPUT: Integer + OUTPUT: integer EXAMPLES: (indirect doctest) @@ -258,12 +258,12 @@ def dimension_new_cusp_forms(X, k=2, p=0): INPUT: - - ``X`` -- integer, congruence subgroup or Dirichlet - character + - ``X`` -- integer, congruence subgroup or Dirichlet + character - - ``k`` -- weight (integer) + - ``k`` -- weight (integer) - - ``p`` -- 0 or a prime + - ``p`` -- 0 or a prime EXAMPLES:: @@ -320,10 +320,10 @@ def dimension_cusp_forms(X, k=2): INPUT: - - ``X`` -- congruence subgroup or Dirichlet character - or integer + - ``X`` -- congruence subgroup or Dirichlet character + or integer - - ``k`` -- weight (integer) + - ``k`` -- weight (integer) EXAMPLES:: @@ -416,10 +416,10 @@ def dimension_eis(X, k=2): INPUT: - - ``X`` -- congruence subgroup or Dirichlet character - or integer + - ``X`` -- congruence subgroup or Dirichlet character + or integer - - ``k`` -- weight (integer) + - ``k`` -- integer; weight EXAMPLES:: @@ -488,9 +488,9 @@ def dimension_modular_forms(X, k=2): INPUT: - - ``X`` -- congruence subgroup or Dirichlet character + - ``X`` -- congruence subgroup or Dirichlet character - - ``k`` -- weight (integer) + - ``k`` -- integer; weight EXAMPLES:: @@ -539,10 +539,10 @@ def sturm_bound(level, weight=2): INPUT: - - ``level`` -- an integer (interpreted as a level for Gamma0) or a - congruence subgroup + - ``level`` -- integer (interpreted as a level for `\Gamma0`) or a + congruence subgroup - - ``weight`` -- an integer `\geq 2` (default: 2) + - ``weight`` -- integer `\geq 2` (default: 2) EXAMPLES:: diff --git a/src/sage/modular/dirichlet.py b/src/sage/modular/dirichlet.py index e579c5090e3..117f1223d9e 100644 --- a/src/sage/modular/dirichlet.py +++ b/src/sage/modular/dirichlet.py @@ -199,7 +199,7 @@ def __init__(self, parent, x, check=True): INPUT: - ``parent`` -- :class:`DirichletGroup`, a group of Dirichlet - characters + characters - ``x`` -- one of the following: @@ -395,7 +395,6 @@ def change_ring(self, R): sage: psi = chi.change_ring(f) sage: psi(2) -1.83697019872103e-16 - 1.00000000000000*I - """ if self.base_ring() is R: return self @@ -537,7 +536,6 @@ def _repr_short_(self): sage: chi = DirichletGroup(24).0 sage: chi._repr_short_() '[-1, 1, 1]' - """ return str(list(self.values_on_gens())) @@ -637,12 +635,12 @@ def bernoulli(self, k, algorithm='recurrence', cache=True, **opts): INPUT: - - ``k`` -- a non-negative integer + - ``k`` -- nonnegative integer - ``algorithm`` -- either ``'recurrence'`` (default) or ``'definition'`` - - ``cache`` -- if True, cache answers + - ``cache`` -- if ``True``, cache answers - ``**opts`` -- optional arguments; not used directly, but passed to the :func:`bernoulli` function if this is called @@ -686,7 +684,7 @@ def bernoulli(self, k, algorithm='recurrence', cache=True, **opts): sage: eps = DirichletGroup(9).0 sage: eps.bernoulli(3) 10*zeta6 + 4 - sage: eps.bernoulli(3, algorithm="definition") + sage: eps.bernoulli(3, algorithm='definition') 10*zeta6 + 4 TESTS: @@ -695,7 +693,6 @@ def bernoulli(self, k, algorithm='recurrence', cache=True, **opts): sage: DirichletGroup(1)[0].bernoulli(1) 1/2 - """ if cache: try: @@ -749,14 +746,14 @@ def S(n): def lfunction(self, prec=53, algorithm='pari'): """ - Return the L-function of ``self``. + Return the `L`-function of ``self``. - The result is a wrapper around a PARI L-function or around + The result is a wrapper around a PARI `L`-function or around the ``lcalc`` program. INPUT: - - ``prec`` -- precision (default 53) + - ``prec`` -- precision (default: 53) - ``algorithm`` -- 'pari' (default) or 'lcalc' @@ -830,7 +827,7 @@ def conductor(self): return Integer(cond) @cached_method - def fixed_field_polynomial(self, algorithm="pari"): + def fixed_field_polynomial(self, algorithm='pari'): r""" Given a Dirichlet character, this will return a polynomial generating the abelian extension fixed by the kernel @@ -841,9 +838,7 @@ def fixed_field_polynomial(self, algorithm="pari"): A formula by Gauss for the products of periods; see Disquisitiones §343. See the source code for more. - OUTPUT: - - - a polynomial with integer coefficients + OUTPUT: a polynomial with integer coefficients EXAMPLES:: @@ -878,7 +873,7 @@ def fixed_field_polynomial(self, algorithm="pari"): sage: psi = chi^3 sage: psi.order() 2 - sage: psi.fixed_field_polynomial(algorithm="pari") + sage: psi.fixed_field_polynomial(algorithm='pari') x^2 + x + 2 With the Sage implementation:: @@ -886,14 +881,14 @@ def fixed_field_polynomial(self, algorithm="pari"): sage: G = DirichletGroup(37) sage: chi = G.0 sage: psi = chi^18 - sage: psi.fixed_field_polynomial(algorithm="sage") + sage: psi.fixed_field_polynomial(algorithm='sage') x^2 + x - 9 sage: G = DirichletGroup(7) sage: chi = G.0^2 sage: chi Dirichlet character modulo 7 of conductor 7 mapping 3 |--> zeta6 - 1 - sage: chi.fixed_field_polynomial(algorithm="sage") + sage: chi.fixed_field_polynomial(algorithm='sage') x^3 + x^2 - 2*x - 1 sage: G = DirichletGroup(31) @@ -901,12 +896,12 @@ def fixed_field_polynomial(self, algorithm="pari"): sage: chi^6 Dirichlet character modulo 31 of conductor 31 mapping 3 |--> zeta30^6 sage: psi = chi^6 - sage: psi.fixed_field_polynomial(algorithm="sage") + sage: psi.fixed_field_polynomial(algorithm='sage') x^5 + x^4 - 12*x^3 - 21*x^2 + x + 5 sage: G = DirichletGroup(7) sage: chi = G.0 - sage: chi.fixed_field_polynomial(algorithm="sage") + sage: chi.fixed_field_polynomial(algorithm='sage') x^6 + x^5 + x^4 + x^3 + x^2 + x + 1 sage: G = DirichletGroup(1001) @@ -914,7 +909,7 @@ def fixed_field_polynomial(self, algorithm="pari"): sage: psi = chi^3 sage: psi.order() 2 - sage: psi.fixed_field_polynomial(algorithm="sage") + sage: psi.fixed_field_polynomial(algorithm='sage') x^2 + x + 2 The algorithm must be one of `sage` or `pari`:: @@ -924,11 +919,10 @@ def fixed_field_polynomial(self, algorithm="pari"): sage: psi = chi^3 sage: psi.order() 2 - sage: psi.fixed_field_polynomial(algorithm="banana") + sage: psi.fixed_field_polynomial(algorithm='banana') Traceback (most recent call last): ... NotImplementedError: algorithm must be one of 'pari' or 'sage' - """ # this algorithm was written by Francis Clarke see issue #9407 @@ -1027,9 +1021,7 @@ def fixed_field(self): Given a Dirichlet character, this will return the abelian extension fixed by the kernel of the corresponding Galois character. - OUTPUT: - - - a number field + OUTPUT: a number field EXAMPLES:: @@ -1324,7 +1316,7 @@ def gauss_sum(self, a=1): g_a(\chi) = \sum_{r \in \ZZ/m\ZZ} \chi(r)\,\zeta^{ar}, where `m` is the modulus of `\chi` and `\zeta` is a primitive - `m^{th}` root of unity. + `m`-th root of unity. FACTS: If the modulus is a prime `p` and the character is nontrivial, then the Gauss sum has absolute value `\sqrt{p}`. @@ -1416,9 +1408,9 @@ def gauss_sum_numerical(self, prec=53, a=1): INPUT: - - ``prec`` -- integer (default: 53), *bits* of precision + - ``prec`` -- integer (default: 53); *bits* of precision - - ``a`` -- integer, as for :meth:`gauss_sum`. + - ``a`` -- integer; as for :meth:`gauss_sum` The Gauss sum associated to `\chi` is @@ -1427,7 +1419,7 @@ def gauss_sum_numerical(self, prec=53, a=1): g_a(\chi) = \sum_{r \in \ZZ/m\ZZ} \chi(r)\,\zeta^{ar}, where `m` is the modulus of `\chi` and `\zeta` is a primitive - `m^{th}` root of unity. + `m`-th root of unity. EXAMPLES:: @@ -1673,9 +1665,9 @@ def kloosterman_sum_numerical(self, prec=53, a=1, b=0): INPUT: - - ``prec`` -- integer (default: 53), *bits* of precision - - ``a`` -- integer, as for :meth:`.kloosterman_sum` - - ``b`` -- integer, as for :meth:`.kloosterman_sum`. + - ``prec`` -- integer (default: 53); *bits* of precision + - ``a`` -- integer; as for :meth:`.kloosterman_sum` + - ``b`` -- integer; as for :meth:`.kloosterman_sum` EXAMPLES:: @@ -1841,8 +1833,8 @@ def kernel(self): r""" Return the kernel of this character. - OUTPUT: Currently the kernel is returned as a list. This may - change. + OUTPUT: currently the kernel is returned as a list; this may + change EXAMPLES:: @@ -1899,7 +1891,7 @@ def minimize_base_ring(self): Return a Dirichlet character that equals this one, but over as small a subfield (or subring) of the base ring as possible. - .. note:: + .. NOTE:: This function is currently only implemented when the base ring is a number field. It is the identity function in @@ -2465,7 +2457,6 @@ class DirichletGroupFactory(UniqueFactory): sage: DirichletGroup(60) is DirichletGroup(60) True - """ def create_key(self, N, base_ring=None, zeta=None, zeta_order=None, names=None, integral=False): @@ -2565,7 +2556,6 @@ def create_object(self, version, key, **extra_args): sage: DirichletGroup.create_object(None, (K, 60, K.gen(), 4)) Group of Dirichlet characters modulo 60 with values in the group of order 4 generated by zeta4 in Cyclotomic Field of order 4 and degree 2 - """ base_ring, modulus, zeta, zeta_order = key return DirichletGroup_class(base_ring, modulus, zeta, zeta_order) @@ -2626,7 +2616,6 @@ def __init__(self, base_ring, modulus, zeta, zeta_order): True sage: DirichletGroup(13) == DirichletGroup(13, QQ) False - """ from sage.categories.groups import Groups category = Groups().Commutative() @@ -2743,7 +2732,6 @@ def change_ring(self, R, zeta=None, zeta_order=None): sage: D.change_ring(f) Group of Dirichlet characters modulo 5 with values in Complex Field with 53 bits of precision - """ if zeta is None and self._zeta is not None: # A root of unity was explicitly given; we use it over the @@ -2822,7 +2810,6 @@ def base_extend(self, R): 14 sage: g.parent().zeta() 14 - """ if not (isinstance(R, Map) or R.has_coerce_map_from(self.base_ring())): @@ -3039,17 +3026,17 @@ def galois_orbits(self, v=None, reps_only=False, sort=True, check=True): INPUT: - - ``v`` -- (optional) list of elements of ``self`` + - ``v`` -- (optional) list of elements of ``self`` - - ``reps_only`` -- (optional: default ``False``) if ``True`` - only returns representatives for the orbits. + - ``reps_only`` -- (optional: default ``False``) if ``True`` + only returns representatives for the orbits - - ``sort`` -- (optional: default ``True``) whether to sort - the list of orbits and the orbits themselves (slightly faster if - ``False``). + - ``sort`` -- (optional: default ``True``) whether to sort + the list of orbits and the orbits themselves (slightly faster if + ``False``). - - ``check`` -- (default: ``True``) whether or not - to explicitly coerce each element of ``v`` into ``self``. + - ``check`` -- boolean (default: ``True``); whether or not + to explicitly coerce each element of ``v`` into ``self`` The Galois group is the absolute Galois group of the prime subfield of Frac(R). If R is not a domain, an error will be raised. @@ -3098,7 +3085,7 @@ def galois_orbits(self, v=None, reps_only=False, sort=True, check=True): def gen(self, n=0): """ - Return the n-th generator of ``self``. + Return the `n`-th generator of ``self``. EXAMPLES:: diff --git a/src/sage/modular/drinfeld_modform/element.py b/src/sage/modular/drinfeld_modform/element.py index 8af86f25118..dd6d48ad99e 100644 --- a/src/sage/modular/drinfeld_modform/element.py +++ b/src/sage/modular/drinfeld_modform/element.py @@ -84,7 +84,7 @@ class DrinfeldModularFormsElement(ModuleElement): sage: M(T*f1 + f2^3 + T^2 + 1) g2^3 + T*g1 + (T^2 + 1) - .. note:: + .. NOTE:: This class should not be directly instanciated, instead create an instance of the parent @@ -341,9 +341,7 @@ def polynomial(self): Return this graded Drinfeld forms as a multivariate polynomial over the generators of the ring. - OUTPUT: - - A multivariate polynomial over the base ring. + OUTPUT: a multivariate polynomial over the base ring EXAMPLES:: diff --git a/src/sage/modular/drinfeld_modform/ring.py b/src/sage/modular/drinfeld_modform/ring.py index bb638e339ab..c113523fc48 100644 --- a/src/sage/modular/drinfeld_modform/ring.py +++ b/src/sage/modular/drinfeld_modform/ring.py @@ -76,20 +76,20 @@ class DrinfeldModularForms(Parent, UniqueRepresentation): INPUT: - ``base_ring`` -- the fraction field of a univariate polynomial - ring over `\mathbb{F}_q`. + ring over `\mathbb{F}_q` - - ``rank`` integer (default: ``None``) -- the rank of the ring. If + - ``rank`` integer (default: ``None``); the rank of the ring. If the rank is ``None``, then the names of the generators must be specified. - - ``group`` (not implemented, default: ``None``) -- the group of the + - ``group`` -- (not implemented, default: ``None``) the group of the ring. The current implementation only supports the full modular group `\mathrm{GL}_r(A)`. - - ``has_type`` boolean (default: ``False``) -- if set to ``True``, - returns the graded ring of arbitrary type. + - ``has_type`` -- boolean (default: ``False``); if set to ``True``, + returns the graded ring of arbitrary type - - ``names`` string, tuple or list (default: ``None``) -- a single + - ``names`` -- string, tuple or list (default: ``None``); a single character, a tuple or list of character, or comma separated string of character representing the names of the generators. If this parameter is set to ``None`` and the rank is specified, then the @@ -341,7 +341,7 @@ def __init__(self, base_ring, rank, group, has_type, names): def _an_element_(self): r""" - Return an element of self. + Return an element of ``self``. TESTS:: @@ -356,7 +356,7 @@ def _an_element_(self): def _repr_(self): r""" - Return the string representation of self. + Return the string representation of ``self``. TESTS:: @@ -371,7 +371,7 @@ def _repr_(self): def _generator_coefficient_form(self, i): r""" - Return the i-th coefficient form at `T`. + Return the `i`-th coefficient form at `T`. For internal use only, the user should use :meth:`coefficient_form` instead. @@ -415,9 +415,9 @@ def _coefficient_forms(self, a): INPUT: - - ``a`` -- an element in the ring of regular functions. + - ``a`` -- an element in the ring of regular functions - OUTPUT: a list of Drinfeld modular forms. The `i`-th element of + OUTPUT: list of Drinfeld modular forms. The `i`-th element of that list corresponds to the `(i+1)`-th coefficient form at `a`. TESTS:: @@ -460,7 +460,7 @@ def coefficient_form(self, i, a=None): INPUT: - - ``i`` -- an integer between 1 and `r d_a`; + - ``i`` -- integer between 1 and `r d_a` - ``a`` -- (default: ``None``) an element in the ring of regular functions. If `a` is ``None``, then the method returns the @@ -546,7 +546,7 @@ def coefficient_forms(self, a=None): functions. If `a` is ``None``, then the method returns the coefficients forms at `a = T`. - OUTPUT: a list of Drinfeld modular forms. The `i`-th element of + OUTPUT: list of Drinfeld modular forms. The `i`-th element of that list corresponds to the `(i+1)`-th coefficient form at `a`. EXAMPLES:: @@ -728,7 +728,7 @@ def basis_of_weight(self, k): INPUT: - - ``k`` -- an integer. + - ``k`` -- integer EXAMPLES:: diff --git a/src/sage/modular/drinfeld_modform/tutorial.py b/src/sage/modular/drinfeld_modform/tutorial.py index 01e0f80db5c..e4f64f10daf 100644 --- a/src/sage/modular/drinfeld_modform/tutorial.py +++ b/src/sage/modular/drinfeld_modform/tutorial.py @@ -21,7 +21,7 @@ completion of an algebraic closure of `K_{\infty}`. Lastly, we denote by `\tau : x\mapsto x^q` the `q`-Frobenius. -.. note:: +.. NOTE:: The above construction of `\mathbb{C}_{\infty}` is the same as the construction of `\mathbb{C}_p` in the case of `p`-adic numbers diff --git a/src/sage/modular/etaproducts.py b/src/sage/modular/etaproducts.py index b794d0cf2d6..a063255c6a6 100644 --- a/src/sage/modular/etaproducts.py +++ b/src/sage/modular/etaproducts.py @@ -276,13 +276,12 @@ def q_expansion(self, n): INPUT: - - ``n`` (integer): number of terms to calculate + - ``n`` -- integer; number of terms to calculate OUTPUT: - - a power series over `\ZZ` in - the variable `q`, with a *relative* precision of - `1 + O(q^n)`. + A power series over `\ZZ` in the variable `q`, with a *relative* + precision of `1 + O(q^n)`. ALGORITHM: Calculates eta to (n/m) terms, where m is the smallest integer dividing self.level() such that self.r(m) != 0. Then @@ -329,11 +328,9 @@ def order_at_cusp(self, cusp: CuspFamily) -> Integer: INPUT: - - ``cusp`` -- a :class:`CuspFamily` object + - ``cusp`` -- a :class:`CuspFamily` object - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: @@ -470,7 +467,7 @@ def _element_constructor_(self, dic): INPUT: - - ``dic`` -- a dictionary + - ``dic`` -- dictionary See the docstring of :func:`EtaProduct` for how ``dic`` is used. @@ -500,8 +497,8 @@ def basis(self, reduce=True) -> list: INPUT: - - ``reduce`` -- a boolean (default: ``True``) indicating - whether or not to apply LLL-reduction to the calculated basis + - ``reduce`` -- boolean (default: ``True``); whether or not to apply + LLL-reduction to the calculated basis EXAMPLES:: @@ -576,7 +573,7 @@ def reduce_basis(self, long_etas) -> list: INPUT: - - ``long_etas`` -- a list of EtaGroupElement objects (which + - ``long_etas`` -- a list of EtaGroupElement objects (which should all be of the same level) OUTPUT: @@ -627,19 +624,18 @@ def EtaProduct(level, dic) -> EtaGroupElement: INPUT: - - ``level`` -- (integer): the N such that this eta - product is a function on X_0(N). + - ``level`` -- integer; the N such that this eta + product is a function on `X_0(N)` - - ``dic`` -- (dictionary): a dictionary indexed by - divisors of N such that the coefficient of `\eta(q^d)` is - r[d]. Only nonzero coefficients need be specified. If Ligozat's - criteria are not satisfied, a :class:`ValueError` will be raised. + - ``dic`` -- a dictionary indexed by divisors of N such that the + coefficient of `\eta(q^d)` is r[d]. Only nonzero coefficients need be + specified. If Ligozat's criteria are not satisfied, a :exc:`ValueError` + will be raised. OUTPUT: - - an EtaGroupElement object, whose parent is - the EtaGroup of level N and whose coefficients are the given - dictionary. + An EtaGroupElement object, whose parent is the EtaGroup of level N and + whose coefficients are the given dictionary. .. NOTE:: @@ -671,9 +667,9 @@ def num_cusps_of_width(N, d) -> Integer: INPUT: - - ``N`` -- (integer): the level + - ``N`` -- integer; the level - - ``d`` -- (integer): an integer dividing N, the cusp width + - ``d`` -- integer; an integer dividing `N`, the cusp width EXAMPLES:: @@ -700,7 +696,7 @@ def AllCusps(N) -> list: INPUT: - - ``N`` -- (integer): the level + - ``N`` -- integer; the level EXAMPLES:: @@ -859,7 +855,7 @@ def _repr_(self) -> str: def qexp_eta(ps_ring, prec): r""" - Return the q-expansion of `\eta(q) / q^{1/24}`. + Return the `q`-expansion of `\eta(q) / q^{1/24}`. Here `\eta(q)` is Dedekind's function @@ -871,11 +867,11 @@ def qexp_eta(ps_ring, prec): INPUT: - - ``ps_ring`` -- (PowerSeriesRing): a power series ring + - ``ps_ring`` -- PowerSeriesRing; a power series ring - - ``prec`` -- (integer): the number of terms to compute + - ``prec`` -- integer; the number of terms to compute - OUTPUT: An element of ps_ring which is the q-expansion of + OUTPUT: an element of ``ps_ring`` which is the `q`-expansion of `\eta(q)/q^{1/24}` truncated to prec terms. ALGORITHM: We use the Euler identity @@ -917,17 +913,17 @@ def eta_poly_relations(eta_elements, degree, labels=['x1', 'x2'], INPUT: - - ``eta_elements`` -- (list): a list of EtaGroupElement objects. + - ``eta_elements`` -- list; a list of EtaGroupElement objects. Not implemented unless this list has precisely two elements. degree - - ``degree`` -- (integer): the maximal degree of polynomial to look for. + - ``degree`` -- integer; the maximal degree of polynomial to look for - - ``labels`` -- (list of strings): labels to use for the polynomial returned. + - ``labels`` -- list of strings; labels to use for the polynomial returned - - ``verbose`` -- (boolean, default ``False``): if ``True``, prints information as - it goes. + - ``verbose`` -- boolean (default: ``False``); if ``True``, prints information as + it goes - OUTPUT: a list of polynomials which is a Groebner basis for the + OUTPUT: list of polynomials which is a Groebner basis for the part of the ideal of relations between eta_elements which is generated by elements up to the given degree; or None, if no relations were found. diff --git a/src/sage/modular/hecke/algebra.py b/src/sage/modular/hecke/algebra.py index 81611bd2780..4cd632db1aa 100644 --- a/src/sage/modular/hecke/algebra.py +++ b/src/sage/modular/hecke/algebra.py @@ -73,9 +73,7 @@ def _heckebasis(M): - ``M`` -- a Hecke module - OUTPUT: - - a list of Hecke algebra elements represented as matrices + OUTPUT: list of Hecke algebra elements represented as matrices EXAMPLES:: @@ -119,13 +117,12 @@ class HeckeAlgebra_base(CachedRepresentation, CommutativeRing): INPUT: - - ``M`` -- a Hecke module + - ``M`` -- a Hecke module EXAMPLES:: sage: CuspForms(1, 12).hecke_algebra() # indirect doctest Full Hecke algebra acting on Cuspidal subspace of dimension 1 of Modular Forms space of dimension 2 for Modular Group SL(2,Z) of weight 12 over Rational Field - """ @staticmethod def __classcall__(cls, M): @@ -224,7 +221,7 @@ def _element_constructor_(self, x, check=True): In the last case, the parameter ``check`` controls whether or not to check that this element really does lie in the appropriate algebra. At present, setting ``check=True`` raises - a :class:`NotImplementedError` unless x is a scalar (or a diagonal + a :exc:`NotImplementedError` unless x is a scalar (or a diagonal matrix). EXAMPLES:: @@ -250,7 +247,6 @@ def _element_constructor_(self, x, check=True): Traceback (most recent call last): ... TypeError: Don't know how to construct an element of Anemic Hecke algebra acting on Modular Symbols space of dimension 3 for Gamma_0(11) of weight 2 with sign 0 over Rational Field from Hecke operator T_11 on Modular Symbols space of dimension 3 for Gamma_0(11) of weight 2 with sign 0 over Rational Field - """ from .hecke_operator import HeckeAlgebraElement_matrix, HeckeOperator, HeckeAlgebraElement @@ -383,7 +379,7 @@ def matrix_space(self): def _latex_(self) -> str: r""" - LaTeX representation of self. + LaTeX representation of ``self``. EXAMPLES:: @@ -560,7 +556,7 @@ def hecke_operator(self, n): def hecke_matrix(self, n, *args, **kwds): """ - Return the matrix of the n-th Hecke operator `T_n`. + Return the matrix of the `n`-th Hecke operator `T_n`. EXAMPLES:: @@ -607,7 +603,7 @@ class HeckeAlgebra_full(HeckeAlgebra_base): """ def _repr_(self) -> str: r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -618,7 +614,7 @@ def _repr_(self) -> str: def __richcmp__(self, other, op) -> bool: r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -648,7 +644,7 @@ def is_anemic(self): def anemic_subalgebra(self): r""" - The subalgebra of self generated by the Hecke operators of + The subalgebra of ``self`` generated by the Hecke operators of index coprime to the level. EXAMPLES:: @@ -677,7 +673,7 @@ def _repr_(self) -> str: def __richcmp__(self, other, op) -> bool: r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: diff --git a/src/sage/modular/hecke/ambient_module.py b/src/sage/modular/hecke/ambient_module.py index b6044f35889..3ce44fa63ce 100644 --- a/src/sage/modular/hecke/ambient_module.py +++ b/src/sage/modular/hecke/ambient_module.py @@ -87,9 +87,7 @@ def rank(self): """ Return the rank of this ambient Hecke module. - OUTPUT: - - Integer + OUTPUT: integer EXAMPLES:: @@ -167,7 +165,7 @@ def _degeneracy_lowering_matrix(self, codomain, t): def _hecke_image_of_ith_basis_element(self, n, i): """ - Return the image under the Hecke operator T_n of the i-th basis + Return the image under the Hecke operator `T_n` of the `i`-th basis element. EXAMPLES:: @@ -286,14 +284,14 @@ def degeneracy_map(self, codomain, t=1): INPUT: - - ``codomain`` -- a Hecke module, which should be of the same type as - self, or a positive integer (in which case Sage will use - :meth:`~hecke_module_of_level` to find the "natural" module of the - corresponding level). - - ``t`` -- int, the parameter of the degeneracy map, i.e., the map is - related to `f(q)` - `f(q^t)`. + - ``codomain`` -- a Hecke module, which should be of the same type as + self, or a positive integer (in which case Sage will use + :meth:`~hecke_module_of_level` to find the "natural" module of the + corresponding level). + - ``t`` -- integer; the parameter of the degeneracy map, i.e., the map + is related to `f(q)` - `f(q^t)` - OUTPUT: A morphism from ``self`` to ``codomain``. + OUTPUT: a morphism from ``self`` to ``codomain`` EXAMPLES:: @@ -464,18 +462,18 @@ def fcp(self, n, var='x'): INPUT: - - ``self`` -- Hecke module invariant under the Hecke operator of index - `n`. + - ``self`` -- Hecke module invariant under the Hecke operator of index + `n` - - ``n`` --- a positive integer. + - ``n`` --- a positive integer. - - ``var`` --- variable of polynomial (default ``'x'``) + - ``var`` --- variable of polynomial (default: ``'x'``) OUTPUT: - - ``list`` -- list of the pairs `(g,e)`, where `g` is an - irreducible factor of the characteristic polynomial of `T_n`, and `e` - is its multiplicity. + - ``list`` -- list of the pairs `(g,e)`, where `g` is an + irreducible factor of the characteristic polynomial of `T_n`, and `e` + is its multiplicity. EXAMPLES:: @@ -543,7 +541,7 @@ def hecke_module_of_level(self, level): Return the Hecke module corresponding to ``self`` at the given level, which should be either a divisor or a multiple of the level of ``self``. - This raises :class:`NotImplementedError`, and should be overridden in + This raises :exc:`NotImplementedError`, and should be overridden in derived classes. EXAMPLES:: @@ -562,13 +560,11 @@ def hecke_images(self, i, v): INPUT: - - ``i`` -- nonnegative integer - - - ``v`` -- a list of positive integer + - ``i`` -- nonnegative integer - OUTPUT: + - ``v`` -- list of positive integer - - ``matrix`` -- whose rows are the Hecke images + OUTPUT: ``matrix`` -- whose rows are the Hecke images EXAMPLES:: @@ -713,13 +709,12 @@ def linear_combination_of_basis(self, v): r""" Given a list or vector of length equal to the dimension of ``self``, construct the appropriate linear combination of the basis vectors of - self. + ``self``. EXAMPLES:: sage: ModularForms(3, 12).linear_combination_of_basis([1,0,0,0,1]) 2*q + 2049*q^2 + 177147*q^3 + 4196177*q^4 + 48830556*q^5 + O(q^6) - """ return self(v) @@ -729,8 +724,8 @@ def new_submodule(self, p=None): INPUT: - - ``p`` -- (default: ``None``); if not ``None``, return only - the `p`-new submodule. + - ``p`` -- (default: ``None``) if not ``None``, return only + the `p`-new submodule OUTPUT: the new or `p`-new submodule of ``self``, i.e. the intersection of the kernel of the degeneracy lowering maps to level `N/p` (for the @@ -833,8 +828,8 @@ def old_submodule(self, p=None): INPUT: - - ``p`` -- (default: ``None``); if not ``None``, return only the `p`-old - submodule. + - ``p`` -- (default: ``None``) if not ``None``, return only the `p`-old + submodule OUTPUT: the old or `p`-old submodule of ``self`` @@ -866,7 +861,6 @@ def old_submodule(self, p=None): Modular Symbols subspace of dimension 0 of Modular Symbols space of dimension 40 and level 42, weight 6, character [-1, -1], sign 1, over Rational Field - """ try: if self.__is_old[p]: @@ -979,12 +973,12 @@ def submodule_from_nonembedded_module(self, V, Vdual=None, check=True): INPUT: - - ``V`` -- submodule of ambient free module of the same rank as the - rank of self. + - ``V`` -- submodule of ambient free module of the same rank as the + rank of ``self`` - - ``Vdual`` -- used to pass in dual submodule (may be ``None``) + - ``Vdual`` -- used to pass in dual submodule (may be ``None``) - - ``check`` -- whether to check that submodule is Hecke-equivariant + - ``check`` -- whether to check that submodule is Hecke-equivariant OUTPUT: Hecke submodule of ``self`` diff --git a/src/sage/modular/hecke/element.py b/src/sage/modular/hecke/element.py index df828ebca66..4a82899325a 100644 --- a/src/sage/modular/hecke/element.py +++ b/src/sage/modular/hecke/element.py @@ -282,9 +282,9 @@ def is_eisenstein(self) -> bool: def is_new(self, p=None) -> bool: r""" - Return ``True`` if this element is p-new. + Return ``True`` if this element is `p`-new. - If p is ``None``, return ``True`` if the element is new. + If `p` is ``None``, return ``True`` if the element is new. EXAMPLES:: @@ -299,9 +299,9 @@ def is_new(self, p=None) -> bool: def is_old(self, p=None) -> bool: r""" - Return ``True`` if this element is p-old. + Return ``True`` if this element is `p`-old. - If p is ``None``, return ``True`` if the element is old. + If `p` is ``None``, return ``True`` if the element is old. EXAMPLES:: diff --git a/src/sage/modular/hecke/hecke_operator.py b/src/sage/modular/hecke/hecke_operator.py index eb0edef0e74..c7d39270f63 100644 --- a/src/sage/modular/hecke/hecke_operator.py +++ b/src/sage/modular/hecke/hecke_operator.py @@ -163,7 +163,7 @@ def hecke_module_morphism(self): def _add_(self, other): """ - Add self to other. + Add ``self`` to ``other``. EXAMPLES:: @@ -230,8 +230,8 @@ def __rmul__(self, left): def _sub_(self, other): """ - Compute the difference of self and other, where other has already been - coerced into the parent of self. + Compute the difference of ``self`` and ``other``, where ``other`` has + already been coerced into the parent of ``self``. EXAMPLES:: @@ -273,11 +273,9 @@ def charpoly(self, var='x'): INPUT: + - ``var`` -- string (default: ``'x'``) - - ``var`` -- string (default: 'x') - - - OUTPUT: a monic polynomial in the given variable. + OUTPUT: a monic polynomial in the given variable EXAMPLES:: @@ -424,7 +422,7 @@ class HeckeAlgebraElement_matrix(HeckeAlgebraElement): def __init__(self, parent, A): r""" Initialise an element from a matrix. This *must* be over the base ring - of self and have the right size. + of ``self`` and have the right size. This is a bit overkill as similar checks will be performed by the call and coerce methods of the parent of self, but it can't hurt to be @@ -462,8 +460,8 @@ def __init__(self, parent, A): def _richcmp_(self, other, op): r""" - Compare self to other, where the coercion model has already ensured - that other has the same parent as self. + Compare ``self`` to ``other``, where the coercion model has already ensured + that ``other`` has the same parent as ``self``. EXAMPLES:: @@ -486,7 +484,7 @@ def _richcmp_(self, other, op): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -500,7 +498,7 @@ def _repr_(self): def _latex_(self): r""" - Latex representation of self (just prints the matrix) + Latex representation of ``self`` (just prints the matrix). EXAMPLES:: @@ -527,8 +525,8 @@ def matrix(self): def _mul_(self, other): r""" - Multiply self by other (which has already been coerced into an element - of the parent of self). + Multiply ``self`` by ``other`` (which has already been coerced into an element + of the parent of ``self``). EXAMPLES:: @@ -625,8 +623,8 @@ def __init__(self, parent, n): def _richcmp_(self, other, op): r""" - Compare self and other (where the coercion model has already ensured - that self and other have the same parent). Hecke operators on the same + Compare ``self`` and ``other`` (where the coercion model has already ensured + that ``self`` and ``other`` have the same parent). Hecke operators on the same space compare as equal if and only if their matrices are equal, so we check if the indices are the same and if not we compute the matrices (which is potentially expensive). @@ -661,7 +659,7 @@ def _richcmp_(self, other, op): def _repr_(self): r""" - String representation of self + String representation of ``self``. EXAMPLES:: @@ -672,7 +670,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation of self + LaTeX representation of ``self``. EXAMPLES:: diff --git a/src/sage/modular/hecke/module.py b/src/sage/modular/hecke/module.py index cd8a1c70373..e22ed609da6 100644 --- a/src/sage/modular/hecke/module.py +++ b/src/sage/modular/hecke/module.py @@ -233,7 +233,7 @@ def _compute_hecke_matrix(self, n, **kwds): def _compute_hecke_matrix_prime(self, p, **kwds): """ - Compute and return the matrix of the p-th Hecke operator for p prime. + Compute and return the matrix of the `p`-th Hecke operator for `p` prime. Derived classes should overload this function, and they will inherit the machinery for calculating general Hecke operators. @@ -444,11 +444,9 @@ def level(self): INPUT: - - ``ModularSymbols self`` -- an arbitrary space of modular symbols + - ``ModularSymbols self`` -- an arbitrary space of modular symbols - OUTPUT: - - - ``int`` -- the level + OUTPUT: integer; the level EXAMPLES:: @@ -462,7 +460,7 @@ def rank(self): r""" Return the rank of this module over its base ring. - This raises a :class:`NotImplementedError`, since this is an + This raises a :exc:`NotImplementedError`, since this is an abstract base class. EXAMPLES:: @@ -479,7 +477,7 @@ def submodule(self, X): Return the submodule of ``self`` corresponding to ``X``. As this is an abstract base class, this raises a - :class:`NotImplementedError`. + :exc:`NotImplementedError`. EXAMPLES:: @@ -535,7 +533,7 @@ def _repr_(self): def __getitem__(self, n): r""" - Return the nth term in the decomposition of ``self``. + Return the `n`-th term in the decomposition of ``self``. See the docstring for :meth:`decomposition` for further information. @@ -559,7 +557,6 @@ def __hash__(self): sage: MS = ModularSymbols(22) sage: hash(MS) == hash((MS.weight(), MS.level(), MS.base_ring())) True - """ return hash((self.__weight, self.level(), self.base_ring())) @@ -618,7 +615,7 @@ def _eigen_nonzero_element(self, n=1): Return `T_n(x)` where `x` is a sparse modular symbol such that the image of `x` is nonzero under the dual projection map associated to this space, and `T_n` is the - `n^{th}` Hecke operator. + `n`-th Hecke operator. Used in the :meth:`dual_eigenvector` and :meth:`eigenvalue` methods. @@ -745,7 +742,7 @@ def ambient_hecke_module(self): r""" Return the ambient module associated to this module. - As this is an abstract base class, raise :class:`NotImplementedError`. + As this is an abstract base class, raise :exc:`NotImplementedError`. EXAMPLES:: @@ -930,21 +927,19 @@ def decomposition(self, bound=None, anemic=True, height_guess=1, INPUT: - - ``anemic`` -- bool (default: ``True``), if True, use only - Hecke operators of index coprime to the level. + - ``anemic`` -- boolean (default: ``True``); if ``True``, use only + Hecke operators of index coprime to the level - - ``bound`` -- int or None, (default: None). If None, - use all Hecke operators up to the Sturm bound, and hence obtain the - same result as one would obtain by using every element of the Hecke - ring. If a fixed integer, decompose using only Hecke operators - `T_p`, with `p` prime, up to bound. - - ``sort_by_basis`` -- bool (default: ``False``); If True the resulting - decomposition will be sorted as if it was free modules, ignoring the - Hecke module structure. This will save a lot of time. + - ``bound`` -- integer or ``None`` (default: ``None``); if ``None``, + use all Hecke operators up to the Sturm bound, and hence obtain the + same result as one would obtain by using every element of the Hecke + ring. If a fixed integer, decompose using only Hecke operators + `T_p`, with `p` prime, up to bound. + - ``sort_by_basis`` -- boolean (default: ``False``); if ``True`` the + resulting decomposition will be sorted as if it was free modules, + ignoring the Hecke module structure. This will save a lot of time. - OUTPUT: - - - ``list`` -- a list of subspaces of ``self``. + OUTPUT: list of subspaces of ``self`` EXAMPLES:: @@ -1086,15 +1081,17 @@ def dual_eigenvector(self, names='alpha', lift=True, nz=None): INPUT: - - ``name`` -- print name of generator for eigenvalue - field. + - ``name`` -- print name of generator for eigenvalue + field - - ``lift`` -- bool (default: ``True``) + - ``lift`` -- boolean (default: ``True``) - - ``nz`` -- if not ``None``, then normalize vector so dot - product with this basis vector of ambient space is 1. + - ``nz`` -- if not ``None``, then normalize vector so dot + product with this basis vector of ambient space is 1 - OUTPUT: A vector with entries possibly in an extension of the base + OUTPUT: + + A vector with entries possibly in an extension of the base ring. This vector is an eigenvector for all Hecke operators acting via their transpose. @@ -1206,7 +1203,7 @@ def dual_eigenvector(self, names='alpha', lift=True, nz=None): def dual_hecke_matrix(self, n): """ - Return the matrix of the `n^{th}` Hecke operator acting on the dual + Return the matrix of the `n`-th Hecke operator acting on the dual embedded representation of ``self``. EXAMPLES:: @@ -1228,14 +1225,14 @@ def dual_hecke_matrix(self, n): def eigenvalue(self, n, name='alpha'): r""" Assuming that ``self`` is a simple space, return the eigenvalue of the - `n^{th}` Hecke operator on ``self``. + `n`-th Hecke operator on ``self``. INPUT: - - ``n`` -- index of Hecke operator + - ``n`` -- index of Hecke operator - - ``name`` -- print representation of generator of - eigenvalue field + - ``name`` -- print representation of generator of + eigenvalue field EXAMPLES:: @@ -1263,11 +1260,11 @@ def eigenvalue(self, n, name='alpha'): #. In fact there are `d` systems of eigenvalues associated to self, where `d` is the rank of - self. Each of the systems of eigenvalues is conjugate + ``self``. Each of the systems of eigenvalues is conjugate over the base field. This function chooses one of the systems and consistently returns eigenvalues from that system. Thus these are the coefficients `a_n` for - `n\geq 1` of a modular eigenform attached to self. + `n\geq 1` of a modular eigenform attached to ``self``. #. This function works even for Eisenstein subspaces, though it will not give the constant coefficient of one @@ -1370,7 +1367,7 @@ def gens(self): def gen(self, n): r""" - Return the nth basis vector of the space. + Return the `n`-th basis vector of the space. EXAMPLES:: @@ -1381,8 +1378,7 @@ def gen(self, n): def hecke_matrix(self, n): """ - Return the matrix of the `n^{th}` Hecke operator acting on given - basis. + Return the matrix of the `n`-th Hecke operator acting on given basis. EXAMPLES:: @@ -1405,10 +1401,7 @@ def hecke_operator(self, n): INPUT: - - ``ModularSymbols self`` -- Hecke equivariant space of - modular symbols - - - ``int n`` -- an integer at least 1. + - ``n`` -- integer at least 1 EXAMPLES:: @@ -1460,7 +1453,7 @@ def diamond_bracket_matrix(self, d): def diamond_bracket_operator(self, d): r""" - Return the diamond bracket operator `\langle d \rangle` on self. + Return the diamond bracket operator `\langle d \rangle` on ``self``. EXAMPLES:: @@ -1472,7 +1465,7 @@ def diamond_bracket_operator(self, d): def T(self, n): r""" - Return the `n^{th}` Hecke operator `T_n`. + Return the `n`-th Hecke operator `T_n`. This function is a synonym for :meth:`hecke_operator`. @@ -1486,12 +1479,12 @@ def T(self, n): def hecke_polynomial(self, n, var='x'): """ - Return the characteristic polynomial of the `n^{th}` Hecke operator + Return the characteristic polynomial of the `n`-th Hecke operator acting on this space. INPUT: - - ``n`` -- integer + - ``n`` -- integer OUTPUT: a polynomial @@ -1507,7 +1500,7 @@ def is_simple(self): Return ``True`` if this space is simple as a module for the corresponding Hecke algebra. - This raises :class:`NotImplementedError`, as this is an abstract base + This raises :exc:`NotImplementedError`, as this is an abstract base class. EXAMPLES:: @@ -1599,14 +1592,14 @@ def projection(self): ALGORITHM: Let `B` be the matrix whose columns are obtained by concatenating together a basis for the factors of the ambient - space. Then the projection matrix onto self is the submatrix of + space. Then the projection matrix onto ``self`` is the submatrix of `B^{-1}` obtained from the rows corresponding to self, - i.e., if the basis vectors for self appear as columns `n` + i.e., if the basis vectors for ``self`` appear as columns `n` through `m` of `B`, then the projection matrix is got from rows `n` through `m` of `B^{-1}`. This is because projection with respect to the B basis is just given by an `m-n+1` row slice `P` of a diagonal - matrix D with 1's in the `n` through `m` positions, + matrix D with 1s in the `n` through `m` positions, so projection with respect to the standard basis is given by `P\cdot B^{-1}`, which is just rows `n` through `m` of `B^{-1}`. @@ -1673,14 +1666,14 @@ def system_of_eigenvalues(self, n, name='alpha'): r""" Assuming that ``self`` is a simple space of modular symbols, return the eigenvalues `[a_1, \ldots, a_nmax]` of the Hecke - operators on self. See ``self.eigenvalue(n)`` for more + operators on ``self``. See ``self.eigenvalue(n)`` for more details. INPUT: - - ``n`` -- number of eigenvalues + - ``n`` -- number of eigenvalues - - ``alpha`` -- name of generate for eigenvalue field + - ``alpha`` -- name of generate for eigenvalue field EXAMPLES: @@ -1741,11 +1734,9 @@ def weight(self): INPUT: - - ``self`` -- an arbitrary Hecke module - - OUTPUT: + - ``self`` -- an arbitrary Hecke module - - ``int`` -- the weight + OUTPUT: integer; the weight EXAMPLES:: diff --git a/src/sage/modular/hecke/morphism.py b/src/sage/modular/hecke/morphism.py index 03da3dd77a9..d9dff926fbe 100644 --- a/src/sage/modular/hecke/morphism.py +++ b/src/sage/modular/hecke/morphism.py @@ -103,21 +103,23 @@ class HeckeModuleMorphism_matrix(MatrixMorphism, HeckeModuleMorphism): ... TypeError: Incompatible composition of morphisms: domain of left morphism must be codomain of right. """ - def __init__(self, parent, A, name='', side="left"): + def __init__(self, parent, A, name='', side='left'): """ INPUT: - ``parent`` -- ModularSymbolsHomspace - - ``A`` -- Matrix + - ``A`` -- matrix - - ``name`` -- str (defaults to '') name of the morphism + - ``name`` -- string (default: ``''``); name of the morphism (used for printing) + - ``side`` -- string (default: ``'left'``) + EXAMPLES:: sage: M = ModularSymbols(6) - sage: t = M.Hom(M)(matrix(QQ,3,3,srange(9)), name="spam"); t + sage: t = M.Hom(M)(matrix(QQ,3,3,srange(9)), name='spam'); t Hecke module morphism spam defined by the matrix [0 1 2] [3 4 5] @@ -139,7 +141,7 @@ def name(self, new=None): EXAMPLES:: sage: M = ModularSymbols(6) - sage: t = M.Hom(M)(matrix(QQ,3,3,srange(9)), name="spam"); t + sage: t = M.Hom(M)(matrix(QQ,3,3,srange(9)), name='spam'); t Hecke module morphism spam defined by ... sage: t.name() 'spam' @@ -152,7 +154,7 @@ def name(self, new=None): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: diff --git a/src/sage/modular/hecke/submodule.py b/src/sage/modular/hecke/submodule.py index 8fc412013c6..c542d095339 100644 --- a/src/sage/modular/hecke/submodule.py +++ b/src/sage/modular/hecke/submodule.py @@ -66,10 +66,10 @@ def __init__(self, ambient, submodule, dual_free_module=None, check=True): be invariant under all Hecke operators. - ``dual_free_module`` -- the submodule of the dual of the ambient - module corresponding to this submodule (or None). + module corresponding to this submodule (or ``None``) - ``check`` -- whether or not to explicitly check that the submodule is - Hecke equivariant. + Hecke equivariant EXAMPLES:: @@ -110,7 +110,7 @@ def __init__(self, ambient, submodule, dual_free_module=None, check=True): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -124,7 +124,7 @@ def _repr_(self): def __add__(self, other): r""" - Sum of self and other (as submodules of a common ambient + Sum of ``self`` and ``other`` (as submodules of a common ambient module). EXAMPLES:: @@ -170,7 +170,7 @@ def _element_constructor_(self, x, check=True): def __richcmp__(self, other, op): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -201,8 +201,8 @@ def __richcmp__(self, other, op): ################################ def _compute_dual_hecke_matrix(self, n): """ - Compute the matrix for the nth Hecke operator acting on - the dual of self. + Compute the matrix for the `n`-th Hecke operator acting on + the dual of ``self``. EXAMPLES:: @@ -223,9 +223,9 @@ def _compute_dual_hecke_matrix(self, n): def _compute_hecke_matrix(self, n): r""" - Compute the matrix of the nth Hecke operator acting on this space, by + Compute the matrix of the `n`-th Hecke operator acting on this space, by calling the corresponding function for the ambient space and - restricting. If n is not coprime to the level, we check that the + restricting. If `n` is not coprime to the level, we check that the restriction is well-defined. EXAMPLES:: @@ -262,7 +262,7 @@ def _compute_diamond_matrix(self, d): def _compute_atkin_lehner_matrix(self, d): """ Compute the Atkin-Lehner matrix corresponding to the - divisor d of the level of self. + divisor d of the level of ``self``. EXAMPLES:: @@ -283,9 +283,9 @@ def _compute_atkin_lehner_matrix(self, d): def _set_dual_free_module(self, V): """ - Set the dual free module of self to V. Here V must be a vector - space of the same dimension as self, embedded in a space of - the same dimension as the ambient space of self. + Set the dual free module of ``self`` to V. Here V must be a vector + space of the same dimension as ``self``, embedded in a space of + the same dimension as the ambient space of ``self``. EXAMPLES:: @@ -405,23 +405,22 @@ def complement(self, bound=None): def degeneracy_map(self, level, t=1): """ - The t-th degeneracy map from self to the space of ambient modular - symbols of the given level. The level of self must be a divisor or - multiple of level, and t must be a divisor of the quotient. + The `t`-th degeneracy map from ``self`` to the space of ambient modular + symbols of the given level. The level of ``self`` must be a divisor or + multiple of level, and `t` must be a divisor of the quotient. INPUT: + - ``level`` -- positive integer; the level of the codomain of the + map - - ``level`` -- int, the level of the codomain of the - map (positive int). + - ``t`` -- integer; the parameter of the degeneracy map, + i.e., the map is related to `f(q)` - `f(q^t)` - - ``t`` -- int, the parameter of the degeneracy map, - i.e., the map is related to `f(q)` - `f(q^t)`. + OUTPUT: - - OUTPUT: A linear function from self to the space of modular symbols - of given level with the same weight, character, sign, etc., as this - space. + A linear function from ``self`` to the space of modular symbols of given + level with the same weight, character, sign, etc., as this space. EXAMPLES:: @@ -459,12 +458,12 @@ def dual_free_module(self, bound=None, anemic=True, use_star=True): In general this will not be possible, e.g., if this space is not Hecke equivariant, possibly if it is not cuspidal, or if the characteristic is not 0. In all these cases we raise a - :class:`RuntimeError` exception. + :exc:`RuntimeError` exception. - If use_star is True (which is the default), we also use the +/- - eigenspaces for the star operator to find the dual free module of self. - If self does not have a star involution, use_star will automatically be - set to False. + If ``use_star`` is ``True`` (which is the default), we also use the +/- + eigenspaces for the star operator to find the dual free module of ``self``. + If ``self`` does not have a star involution, ``use_star`` will automatically be + set to ``False``. EXAMPLES:: @@ -516,7 +515,6 @@ def dual_free_module(self, bound=None, anemic=True, use_star=True): sage: EllipticCurve('128a').congruence_number() 32 - """ # if we know the complement we can read off the dual module @@ -601,7 +599,7 @@ def dual_free_module(self, bound=None, anemic=True, use_star=True): def free_module(self): """ - Return the free module corresponding to self. + Return the free module corresponding to ``self``. EXAMPLES:: @@ -633,7 +631,7 @@ def module(self): def intersection(self, other): """ - Returns the intersection of self and other, which must both lie in + Return the intersection of ``self`` and ``other``, which must both lie in a common ambient space of modular symbols. EXAMPLES:: @@ -678,8 +676,7 @@ def intersection(self, other): def is_ambient(self): r""" - Return ``True`` if self is an ambient space of modular - symbols. + Return ``True`` if ``self`` is an ambient space of modular symbols. EXAMPLES:: @@ -695,8 +692,8 @@ def is_ambient(self): def is_new(self, p=None): """ - Returns True if this Hecke module is p-new. If p is None, - returns True if it is new. + Return ``True`` if this Hecke module is `p`-new. If `p` is None, + returns ``True`` if it is new. EXAMPLES:: @@ -717,8 +714,8 @@ def is_new(self, p=None): def is_old(self, p=None): """ - Returns True if this Hecke module is p-old. If p is None, - returns True if it is old. + Return ``True`` if this Hecke module is `p`-old. If `p` is ``None``, + returns ``True`` if it is old. EXAMPLES:: @@ -742,7 +739,7 @@ def is_old(self, p=None): def is_submodule(self, V): """ - Returns True if and only if self is a submodule of V. + Return ``True`` if and only if ``self`` is a submodule of V. EXAMPLES:: @@ -785,14 +782,13 @@ def linear_combination_of_basis(self, v): ] sage: S.linear_combination_of_basis([3, 10]) 3*q + 10*q^2 + 756*q^3 - 6384*q^4 + 14490*q^5 + O(q^6) - """ x = self.free_module().linear_combination_of_basis(v) return self(x) def new_submodule(self, p=None): """ - Return the new or p-new submodule of this space of modular + Return the new or `p`-new submodule of this space of modular symbols. EXAMPLES:: @@ -834,7 +830,7 @@ def new_submodule(self, p=None): def nonembedded_free_module(self): """ - Return the free module corresponding to self as an abstract + Return the free module corresponding to ``self`` as an abstract free module, i.e. not as an embedded vector space. EXAMPLES:: @@ -850,7 +846,7 @@ def nonembedded_free_module(self): def old_submodule(self, p=None): r""" - Return the old or p-old submodule of this space of modular + Return the old or `p`-old submodule of this space of modular symbols. EXAMPLES: We compute the old and new submodules of @@ -893,7 +889,7 @@ def old_submodule(self, p=None): def rank(self): r""" - Return the rank of self as a free module over the base ring. + Return the rank of ``self`` as a free module over the base ring. EXAMPLES:: @@ -906,8 +902,8 @@ def rank(self): def submodule(self, M, Mdual=None, check=True): """ - Construct a submodule of self from the free module M, which - must be a subspace of self. + Construct a submodule of ``self`` from the free module M, which + must be a subspace of ``self``. EXAMPLES:: @@ -933,19 +929,17 @@ def submodule(self, M, Mdual=None, check=True): def submodule_from_nonembedded_module(self, V, Vdual=None, check=True): """ - Construct a submodule of self from V. Here V should be a + Construct a submodule of ``self`` from V. Here V should be a subspace of a vector space whose dimension is the same as that - of self. + of ``self``. INPUT: + - ``V`` -- submodule of ambient free module of the same + rank as the rank of ``self`` - - ``V`` -- submodule of ambient free module of the same - rank as the rank of self. - - - ``check`` -- whether to check that V is Hecke - equivariant. - + - ``check`` -- whether to check that V is Hecke + equivariant OUTPUT: Hecke submodule of self diff --git a/src/sage/modular/hypergeometric_motive.py b/src/sage/modular/hypergeometric_motive.py index d21d34da445..32c7c88c0cf 100644 --- a/src/sage/modular/hypergeometric_motive.py +++ b/src/sage/modular/hypergeometric_motive.py @@ -104,23 +104,21 @@ def characteristic_polynomial_from_traces(traces, d, q, i, sign, deg=None, use_f INPUT: - - ``traces`` -- a list of integers `t_1, \dots, t_k` + - ``traces`` -- list of integers `t_1, \dots, t_k` - ``d`` -- the degree of the characteristic polynomial - ``q`` -- power of a prime number - - ``i`` -- integer, the weight in the motivic sense + - ``i`` -- integer; the weight in the motivic sense - - ``sign`` -- integer, the sign + - ``sign`` -- integer; the sign - - ``deg`` -- an integer or ``None`` + - ``deg`` -- integer or ``None`` - - ``use_fe`` -- a boolean (default: ``True``) + - ``use_fe`` -- boolean (default: ``True``) - OUTPUT: - - a polynomial + OUTPUT: a polynomial If ``deg`` is specified, only the coefficients up to this degree (inclusive) are computed. @@ -197,7 +195,7 @@ def enumerate_hypergeometric_data(d, weight=None): - ``d`` -- the degree - - ``weight`` -- optional integer, to specify the motivic weight + - ``weight`` -- (optional) integer; specifies the motivic weight EXAMPLES:: @@ -231,7 +229,7 @@ def possible_hypergeometric_data(d, weight=None) -> list: - ``d`` -- the degree - - ``weight`` -- optional integer, to specify the motivic weight + - ``weight`` -- (optional) integer; specifies the motivic weight EXAMPLES:: @@ -281,7 +279,7 @@ def alpha_to_cyclotomic(alpha) -> list: The output represent a product of cyclotomic polynomials with exactly the given roots. Note that the multiplicity of `r/s` in the list - must be independent of `r`; otherwise, a :class:`ValueError` will be raised. + must be independent of `r`; otherwise, a :exc:`ValueError` will be raised. This is the inverse of :func:`cyclotomic_to_alpha`. @@ -321,11 +319,9 @@ def capital_M(n): INPUT: - - ``n`` -- an integer - - OUTPUT: + - ``n`` -- integer - a rational + OUTPUT: a rational EXAMPLES:: @@ -379,7 +375,7 @@ def gamma_list_to_cyclotomic(galist): INPUT: - - ``galist`` -- a list of integers, where an integer `n` represents + - ``galist`` -- list of integers, where an integer `n` represents the power `(x^{|n|} - 1)^{\operatorname{sgn}(n)}` OUTPUT: @@ -421,7 +417,7 @@ def __init__(self, cyclotomic=None, alpha_beta=None, gamma_list=None): INPUT: - three possibilities are offered, each describing a quotient + Three possibilities are offered, each describing a quotient of products of cyclotomic polynomials. - ``cyclotomic`` -- a pair of lists of nonnegative integers, @@ -704,7 +700,6 @@ def zigzag(self, x, flip_beta=False): sage: H = Hyp(cyclotomic=([5], [1,1,1,1])) sage: [H.zigzag(x) for x in [0,1/6,1/4,1/2,3/4,5/6]] [-4, -4, -3, -2, -1, 0] - """ alpha = self._alpha beta = self._beta @@ -931,7 +926,7 @@ def E_polynomial(self, vars=None): INPUT: - - ``vars`` -- optional pair of variables (default: `u,v`) + - ``vars`` -- (optional) pair of variables (default: `u,v`) REFERENCES: @@ -999,9 +994,7 @@ def M_value(self): """ Return the `M` coefficient that appears in the trace formula. - OUTPUT: - - a rational + OUTPUT: a rational .. SEEALSO:: :meth:`canonical_scheme` @@ -1331,17 +1324,15 @@ def padic_H_value(self, p, f, t, prec=None, cache_p=False): - ``p`` -- a prime number - - ``f`` -- an integer such that `q = p^f` + - ``f`` -- integer such that `q = p^f` - ``t`` -- a rational parameter - ``prec`` -- precision (optional) - - ``cache_p`` -- a boolean + - ``cache_p`` -- boolean - OUTPUT: - - an integer + OUTPUT: integer EXAMPLES: @@ -1476,17 +1467,15 @@ def H_value(self, p, f, t, ring=None): - ``p`` -- a prime number - - ``f`` -- an integer such that `q = p^f` + - ``f`` -- integer such that `q = p^f` - ``t`` -- a rational parameter - - ``ring`` -- optional (default: :class:`UniversalCyclotomicfield`) + - ``ring`` -- (default: :class:`UniversalCyclotomicfield`) The ring could be also ``ComplexField(n)`` or ``QQbar``. - OUTPUT: - - an integer + OUTPUT: integer .. WARNING:: @@ -1632,7 +1621,6 @@ def sign(self, t, p): sage: H = Hyp(cyclotomic=([1,1,1], [6,2])) sage: [H.sign(4,p) for p in [5,7,11,13,17,19]] [1, 1, -1, -1, 1, 1] - """ t = QQ(t) if 0 in self._alpha: @@ -1665,9 +1653,7 @@ def euler_factor_tame_contribution(self, t, p, mo, deg=None): - ``deg`` -- integer (optional) - OUTPUT: - - a polynomial + OUTPUT: a polynomial If ``deg`` is specified, the output is truncated to that degree (inclusive). @@ -1758,9 +1744,7 @@ def euler_factor(self, t, p, deg=None, cache_p=False): - ``deg`` -- integer or ``None`` - OUTPUT: - - a polynomial + OUTPUT: a polynomial See [Benasque2009]_ for explicit examples of Euler factors. diff --git a/src/sage/modular/local_comp/liftings.py b/src/sage/modular/local_comp/liftings.py index dcb901cc3a1..3cef125420d 100644 --- a/src/sage/modular/local_comp/liftings.py +++ b/src/sage/modular/local_comp/liftings.py @@ -87,7 +87,7 @@ def lift_matrix_to_sl2z(A, N): - ``A`` -- list of 4 integers defining a `2 \times 2` matrix - - `N` -- positive integer + - ``N`` -- positive integer EXAMPLES:: diff --git a/src/sage/modular/local_comp/local_comp.py b/src/sage/modular/local_comp/local_comp.py index 5432d111049..029dcc822b0 100644 --- a/src/sage/modular/local_comp/local_comp.py +++ b/src/sage/modular/local_comp/local_comp.py @@ -44,11 +44,11 @@ def LocalComponent(f, p, twist_factor=None): INPUT: - - ``f`` (:class:`~sage.modular.modform.element.Newform`) a newform of weight `k \ge 2` - - ``p`` (integer) a prime - - ``twist_factor`` (integer) an integer congruent to `k` modulo 2 (default: `k - 2`) + - ``f`` -- (:class:`~sage.modular.modform.element.Newform`) a newform of weight `k \ge 2` + - ``p`` -- integer; prime + - ``twist_factor`` -- integer congruent to `k` modulo 2 (default: `k - 2`) - .. note:: + .. NOTE:: The argument ``twist_factor`` determines the choice of normalisation: if it is set to `j \in \ZZ`, then the central character of `\pi_{f, \ell}` maps `\ell` @@ -169,7 +169,7 @@ def check_tempered(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -298,7 +298,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Return True if ``self != other``. + Return ``True`` if ``self != other``. EXAMPLES:: @@ -323,7 +323,7 @@ class PrimitiveLocalComponent(LocalComponentBase): def is_primitive(self): r""" - Return True if this local component is primitive (has minimal level + Return ``True`` if this local component is primitive (has minimal level among its character twists). EXAMPLES:: @@ -445,7 +445,7 @@ def characters(self): `\pi_{f, p}` is equal to the principal series `\pi(\chi_1, \chi_2)`. These are the unramified characters mapping `p` to the roots of the Satake polynomial, so in most cases (but not always) they will be defined over an - extension of the coefficient field of self. + extension of the coefficient field of ``self``. EXAMPLES:: @@ -991,7 +991,7 @@ def __init__(self,newform, prime, twist_factor, min_twist, chi): def is_primitive(self): r""" - Return True if this local component is primitive (has minimal level + Return ``True`` if this local component is primitive (has minimal level among its character twists). EXAMPLES:: diff --git a/src/sage/modular/local_comp/smoothchar.py b/src/sage/modular/local_comp/smoothchar.py index cfce7550fda..1a05d448d9b 100644 --- a/src/sage/modular/local_comp/smoothchar.py +++ b/src/sage/modular/local_comp/smoothchar.py @@ -98,7 +98,7 @@ def __init__(self, parent, c, values_on_gens): def _check_level(self): r""" - Checks that this character has the level it claims to have, and if not, + Check that this character has the level it claims to have, and if not, decrement the level appropriately. This is called by :meth:`__init__`. EXAMPLES:: @@ -266,7 +266,7 @@ def _repr_(self): def _mul_(self, other): r""" - Product of self and other. + Product of ``self`` and ``other``. EXAMPLES:: @@ -287,7 +287,7 @@ def _mul_(self, other): def __invert__(self): r""" - Multiplicative inverse of self. + Multiplicative inverse of ``self``. EXAMPLES:: @@ -379,7 +379,7 @@ def _element_constructor_(self, x): r""" Construct an element of this group from ``x`` (possibly noncanonically). This only works if ``x`` is a character of a field containing the field of - self, whose values lie in a field that can be converted into self. + ``self``, whose values lie in a field that can be converted into ``self``. EXAMPLES:: @@ -495,7 +495,6 @@ def _coerce_map_from_(self, other): sage: G = SmoothCharacterGroupUnramifiedQuadratic(3, QQ) sage: G.character(0, [1]).base_extend(K) Character of unramified extension Q_3(s)* (s^2 + 2*s + 2 = 0), of level 0, mapping 3 |--> 1 - """ return (isinstance(other, SmoothCharacterGroupGeneric) and other.number_field() == self.number_field() @@ -547,7 +546,6 @@ def base_extend(self, ring): Traceback (most recent call last): ... TypeError: no canonical coercion from Rational Field to Ring of integers modulo 3 - """ if not ring.has_coerce_map_from(self.base_ring()): ring.coerce(self.base_ring().an_element()) @@ -558,7 +556,7 @@ def base_extend(self, ring): @abstract_method def _field_name(self): r""" - A string representing the name of the p-adic field of which this is the + A string representing the name of the `p`-adic field of which this is the character group. To be overridden by derived subclasses. EXAMPLES:: @@ -573,7 +571,7 @@ def _field_name(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -587,7 +585,7 @@ def _repr_(self): def ideal(self, level): r""" Return the ``level``-th power of the maximal ideal of the ring of - integers of the p-adic field. Since we approximate by using number + integers of the `p`-adic field. Since we approximate by using number field arithmetic, what is actually returned is an ideal in a number field. @@ -684,14 +682,14 @@ def character(self, level, values_on_gens): INPUT: - - ``level`` (integer) an integer `\ge 0` - - ``values_on_gens`` (sequence) a sequence of elements of length equal + - ``level`` -- integer an integer `\ge 0` + - ``values_on_gens`` -- sequence a sequence of elements of length equal to the length of ``self.unit_gens(level)``. The values should be convertible (that is, possibly noncanonically) into the base ring of self; they should all be units, and all but the last must be roots of unity (of the orders given by ``self.exponents(level)``. - .. note:: + .. NOTE:: The character returned may have level less than ``level`` in general. @@ -943,7 +941,7 @@ def change_ring(self, ring): Return the group of characters of the same field but with values in a different ring. This need not have anything to do with the original base ring, and in particular there won't generally be a coercion map - from self to the new group -- use + from ``self`` to the new group -- use :meth:`~SmoothCharacterGroupGeneric.base_extend` if you want this. EXAMPLES:: @@ -1024,7 +1022,7 @@ def subgroup_gens(self, level): INPUT: - - ``c`` (integer) an integer `\ge 1` + - ``c`` -- integer `\ge 1` EXAMPLES:: @@ -1305,16 +1303,16 @@ def extend_character(self, level, chi, vals, check=True): INPUT: - - ``chi``: a smooth character of `\QQ_p`, where `p` is the residue - characteristic of `F`, with values in the base ring of self (or some + - ``chi`` -- a smooth character of `\QQ_p`, where `p` is the residue + characteristic of `F`, with values in the base ring of ``self`` (or some other ring coercible to it) - - ``level``: the level of the new character (which should be at least + - ``level`` -- the level of the new character (which should be at least the level of ``chi``) - - ``vals``: a list of elements of the base ring of self (or some other + - ``vals`` -- a list of elements of the base ring of ``self`` (or some other ring coercible to it), specifying values on the quotients returned by - :meth:`quotient_gens`. + :meth:`quotient_gens` - A :class:`ValueError` will be raised if `x^t \ne \chi(\alpha^t)`, where `t` + A :exc:`ValueError` will be raised if `x^t \ne \chi(\alpha^t)`, where `t` is the smallest integer such that `\alpha^t` is congruent modulo `p^{\rm level}` to an element of `\QQ_p`. @@ -1432,7 +1430,7 @@ def change_ring(self, ring): Return the character group of the same field, but with values in a different coefficient ring. This need not have anything to do with the original base ring, and in particular there won't generally be a - coercion map from self to the new group -- use + coercion map from ``self`` to the new group -- use :meth:`~SmoothCharacterGroupGeneric.base_extend` if you want this. EXAMPLES:: @@ -1621,10 +1619,10 @@ def __init__(self, prime, flag, base_ring, names='s'): INPUT: - - ``prime`` -- a prime integer + - ``prime`` -- prime integer - ``flag`` -- either 0 or 1 - ``base_ring`` -- a ring - - ``names`` -- a variable name (default ``s``) + - ``names`` -- a variable name (default: ``'s'``) If ``flag`` is 0, return the group of characters of the multiplicative group of the field `\QQ_p(\sqrt{p})`. If ``flag`` is 1, use the @@ -1676,7 +1674,7 @@ def change_ring(self, ring): Return the character group of the same field, but with values in a different coefficient ring. This need not have anything to do with the original base ring, and in particular there won't generally be a - coercion map from self to the new group -- use + coercion map from ``self`` to the new group -- use :meth:`~SmoothCharacterGroupGeneric.base_extend` if you want this. EXAMPLES:: diff --git a/src/sage/modular/local_comp/type_space.py b/src/sage/modular/local_comp/type_space.py index 87c93d53477..9e20c121108 100644 --- a/src/sage/modular/local_comp/type_space.py +++ b/src/sage/modular/local_comp/type_space.py @@ -183,7 +183,7 @@ def __init__(self, f, p, base_extend=True): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -272,7 +272,7 @@ def free_module(self): def eigensymbol_subspace(self): r""" - Return the subspace of self corresponding to the plus eigensymbols of + Return the subspace of ``self`` corresponding to the plus eigensymbols of `f` and its Galois conjugates (as a subspace of the vector space returned by :meth:`~free_module`). @@ -331,7 +331,7 @@ def group(self): @cached_method def is_minimal(self): r""" - Return True if there exists a newform `g` of level strictly smaller + Return ``True`` if there exists a newform `g` of level strictly smaller than `N`, and a Dirichlet character `\chi` of `p`-power conductor, such that `f = g \otimes \chi` where `f` is the form of which this is the type space. To find such a form, use :meth:`~minimal_twist`. @@ -735,7 +735,6 @@ def _unif_ramified(self): sage: T._unif_ramified() [-1 0] [ 0 -1] - """ p = self.prime() k = self.form().weight() diff --git a/src/sage/modular/modform/ambient.py b/src/sage/modular/modform/ambient.py index b218e5e649f..bf67263db8c 100644 --- a/src/sage/modular/modform/ambient.py +++ b/src/sage/modular/modform/ambient.py @@ -119,7 +119,7 @@ def __init__(self, group, weight, base_ring, character=None, eis_only=False): def _repr_(self): """ - Return string representation of self. + Return string representation of ``self``. EXAMPLES:: @@ -159,9 +159,7 @@ def change_ring(self, base_ring): INPUT: - - - ``R`` -- ring - + - ``R`` -- ring EXAMPLES:: @@ -208,8 +206,8 @@ def dimension(self): def hecke_module_of_level(self, N): r""" Return the Hecke module of level N corresponding to self, which is the - domain or codomain of a degeneracy map from self. Here N must be either - a divisor or a multiple of the level of self. + domain or codomain of a degeneracy map from ``self``. Here N must be either + a divisor or a multiple of the level of ``self``. EXAMPLES:: @@ -229,7 +227,7 @@ def hecke_module_of_level(self, N): def _degeneracy_raising_matrix(self, M, t): r""" - Calculate the matrix of the degeneracy map from self to M corresponding + Calculate the matrix of the degeneracy map from ``self`` to M corresponding to `f(q) \mapsto f(q^t)`. Here the level of M should be a multiple of the level of self, and t should divide the quotient. @@ -288,9 +286,9 @@ def ambient_space(self): def is_ambient(self): """ - Return True if this an ambient space of modular forms. + Return ``True`` if this an ambient space of modular forms. - This is an ambient space, so this function always returns True. + This is an ambient space, so this function always returns ``True``. EXAMPLES:: @@ -365,11 +363,9 @@ def prec(self, new_prec=None): INPUT: + - ``new_prec`` -- positive integer (default: ``None``) - - ``new_prec`` -- positive integer (default: None) - - - OUTPUT: if new_prec is None, returns the current precision. + OUTPUT: if ``new_prec`` is ``None``, returns the current precision EXAMPLES:: @@ -468,10 +464,8 @@ def new_submodule(self, p=None): INPUT: - - - ``p`` -- (default: None), if specified return only - the `p`-new submodule. - + - ``p`` -- (default: ``None``), if specified return only + the `p`-new submodule EXAMPLES:: @@ -518,7 +512,7 @@ def new_submodule(self, p=None): def _q_expansion(self, element, prec): r""" - Return the q-expansion of a particular element of this space of + Return the `q`-expansion of a particular element of this space of modular forms, where the element should be a vector, list, or tuple (not a ModularFormElement). Here element should have length = self.dimension(). If element = [ a_i ] and self.basis() = [ v_i @@ -526,11 +520,9 @@ def _q_expansion(self, element, prec): INPUT: + - ``element`` -- vector, list or tuple - - ``element`` -- vector, list or tuple - - - ``prec`` -- desired precision of q-expansion - + - ``prec`` -- desired precision of `q`-expansion EXAMPLES:: @@ -679,7 +671,7 @@ def _dim_new_eisenstein(self): @cached_method def eisenstein_params(self): """ - Return parameters that define all Eisenstein series in self. + Return parameters that define all Eisenstein series in ``self``. OUTPUT: an immutable Sequence @@ -752,12 +744,12 @@ def _compute_q_expansion_basis(self, prec): def _compute_hecke_matrix(self, n): """ - Compute the matrix of the Hecke operator T_n acting on self. + Compute the matrix of the Hecke operator `T_n` acting on ``self``. - NOTE: + .. NOTE:: - If self is a level 1 space, the much faster Victor Miller basis - is used for this computation. + If ``self`` is a level 1 space, the much faster Victor Miller basis + is used for this computation. EXAMPLES:: @@ -830,7 +822,7 @@ def _compute_hecke_matrix_prime_power(self, p, r): def hecke_polynomial(self, n, var='x'): r""" - Compute the characteristic polynomial of the Hecke operator T_n acting + Compute the characteristic polynomial of the Hecke operator `T_n` acting on this space. Except in level 1, this is computed via modular symbols, and in particular is faster to compute than the matrix itself. diff --git a/src/sage/modular/modform/ambient_R.py b/src/sage/modular/modform/ambient_R.py index 0d19eb36cd3..fcf8a598721 100644 --- a/src/sage/modular/modform/ambient_R.py +++ b/src/sage/modular/modform/ambient_R.py @@ -82,7 +82,7 @@ def _repr_(self): def _compute_q_expansion_basis(self, prec=None): """ - Compute q-expansions for a basis of self to precision prec. + Compute `q`-expansions for a basis of ``self`` to precision ``prec``. EXAMPLES:: diff --git a/src/sage/modular/modform/ambient_eps.py b/src/sage/modular/modform/ambient_eps.py index 81527a72aa8..cf2ab2b9db5 100644 --- a/src/sage/modular/modform/ambient_eps.py +++ b/src/sage/modular/modform/ambient_eps.py @@ -102,7 +102,7 @@ def __init__(self, character, weight=2, base_ring=None, eis_only=False): """ Create an ambient modular forms space with character. - .. note:: + .. NOTE:: The base ring must be of characteristic 0. The ambient_R Python module is used for computing in characteristic p, @@ -110,7 +110,7 @@ def __init__(self, character, weight=2, base_ring=None, eis_only=False): INPUT: - - ``weight`` -- int + - ``weight`` -- integer - ``character`` -- dirichlet.DirichletCharacter @@ -260,10 +260,10 @@ def eisenstein_submodule(self): def hecke_module_of_level(self, N): r""" - Return the Hecke module of level N corresponding to self, which is the - domain or codomain of a degeneracy map from self. Here N must be either - a divisor or a multiple of the level of self, and a multiple of the - conductor of the character of self. + Return the Hecke module of level N corresponding to ``self``, which is the + domain or codomain of a degeneracy map from ``self``. Here N must be either + a divisor or a multiple of the level of ``self``, and a multiple of the + conductor of the character of ``self``. EXAMPLES:: diff --git a/src/sage/modular/modform/ambient_g1.py b/src/sage/modular/modform/ambient_g1.py index 2771a9a1623..31db01bd081 100644 --- a/src/sage/modular/modform/ambient_g1.py +++ b/src/sage/modular/modform/ambient_g1.py @@ -135,7 +135,7 @@ def _compute_diamond_matrix(self, d): def _compute_hecke_matrix(self, n): r""" - Compute the matrix of the Hecke operator T_n acting on this space. + Compute the matrix of the Hecke operator `T_n` acting on this space. EXAMPLES:: diff --git a/src/sage/modular/modform/constructor.py b/src/sage/modular/modform/constructor.py index 746b10472bc..30a264905bc 100644 --- a/src/sage/modular/modform/constructor.py +++ b/src/sage/modular/modform/constructor.py @@ -56,28 +56,23 @@ def canonical_parameters(group, level, weight, base_ring): INPUT: + - ``group`` -- integer, group, or Dirichlet character - - ``group`` -- int, long, Sage integer, group, - Dirichlet character, or + - ``level`` -- integer or group - - ``level`` -- int, long, Sage integer, or group - - - ``weight`` -- coercible to Sage integer - - - ``base_ring`` -- commutative Sage ring + - ``weight`` -- coercible to integer + - ``base_ring`` -- commutative ring OUTPUT: + - ``level`` -- integer - - ``level`` -- Sage integer - - - ``group`` -- congruence subgroup + - ``group`` -- congruence subgroup - - ``weight`` -- Sage integer - - - ``ring`` -- commutative Sage ring + - ``weight`` -- integer + - ``ring`` -- commutative ring EXAMPLES:: @@ -168,13 +163,13 @@ def ModularForms(group=1, INPUT: - - ``group`` -- A congruence subgroup or a Dirichlet character eps. + - ``group`` -- a congruence subgroup or a Dirichlet character eps - - ``weight`` -- int, the weight, which must be an integer >= 1. + - ``weight`` -- integer; the weight (`\geq 1`) - ``base_ring`` -- the base ring (ignored if group is a Dirichlet character) - - ``eis_only`` -- if True, compute only the Eisenstein part of the space. + - ``eis_only`` -- if ``True``, compute only the Eisenstein part of the space. Only permitted (and only useful) in weight 1, where computing dimensions of cusp form spaces is expensive. @@ -307,7 +302,6 @@ def ModularForms(group=1, Congruence Subgroup Gamma1(59) of weight 1 over Rational Field sage: (E.0 + E.2).q_expansion(40) 1 + q^2 + 196*q^29 - 197*q^30 - q^31 + q^33 + q^34 + q^37 + q^38 - q^39 + O(q^40) - """ if isinstance(group, dirichlet.DirichletCharacter): if base_ring is None: @@ -423,25 +417,23 @@ def EisensteinForms(group=1, def Newforms(group, weight=2, base_ring=None, names=None): r""" - Returns a list of the newforms of the given weight and level (or weight, + Return a list of the newforms of the given weight and level (or weight, level and character). These are calculated as `\operatorname{Gal}(\overline{F} / F)`-orbits, where `F` is the given base field. INPUT: + - ``group`` -- the congruence subgroup of the newform, or a Nebentypus + character - - ``group`` -- the congruence subgroup of the newform, or a Nebentypus - character + - ``weight`` -- the weight of the newform (default: 2) - - ``weight`` -- the weight of the newform (default 2) - - - ``base_ring`` -- the base ring (defaults to `\QQ` for spaces without - character, or the base ring of the character otherwise) - - - ``names`` -- if the newform has coefficients in a - number field, a generator name must be specified + - ``base_ring`` -- the base ring (defaults to `\QQ` for spaces without + character, or the base ring of the character otherwise) + - ``names`` -- if the newform has coefficients in a number field, a + generator name must be specified EXAMPLES:: @@ -478,7 +470,6 @@ def Newforms(group, weight=2, base_ring=None, names=None): sage: N = Newforms(719, names='a'); len(N) # long time (3 s) 3 - """ return CuspForms(group, weight, base_ring).newforms(names) @@ -487,19 +478,17 @@ def Newform(identifier, group=None, weight=2, base_ring=QQ, names=None): """ INPUT: + - ``identifier`` -- a canonical label, or the index of + the specific newform desired - - ``identifier`` -- a canonical label, or the index of - the specific newform desired - - - ``group`` -- the congruence subgroup of the newform - - - ``weight`` -- the weight of the newform (default 2) + - ``group`` -- the congruence subgroup of the newform - - ``base_ring`` -- the base ring + - ``weight`` -- the weight of the newform (default: 2) - - ``names`` -- if the newform has coefficients in a - number field, a generator name must be specified + - ``base_ring`` -- the base ring + - ``names`` -- if the newform has coefficients in a + number field, a generator name must be specified EXAMPLES:: diff --git a/src/sage/modular/modform/cuspidal_submodule.py b/src/sage/modular/modform/cuspidal_submodule.py index 80356227f93..2f5a94cbf58 100644 --- a/src/sage/modular/modform/cuspidal_submodule.py +++ b/src/sage/modular/modform/cuspidal_submodule.py @@ -100,7 +100,7 @@ def __init__(self, ambient_space): def _compute_q_expansion_basis(self, prec): r""" - Compute a basis of q-expansions of self to the given precision. Not + Compute a basis of `q`-expansions of ``self`` to the given precision. Not implemented in this abstract base class. EXAMPLES:: @@ -115,7 +115,7 @@ def _compute_q_expansion_basis(self, prec): def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -126,7 +126,7 @@ def _repr_(self): def is_cuspidal(self): """ - Return True since spaces of cusp forms are cuspidal. + Return ``True`` since spaces of cusp forms are cuspidal. EXAMPLES:: @@ -231,11 +231,11 @@ def _compute_q_expansion_basis(self, prec): class CuspidalSubmodule_modsym_qexp(CuspidalSubmodule): """ - Cuspidal submodule with q-expansions calculated via modular symbols. + Cuspidal submodule with `q`-expansions calculated via modular symbols. """ def _compute_q_expansion_basis(self, prec=None): """ - Compute q-expansions of a basis for self (via modular symbols). + Compute `q`-expansions of a basis for ``self`` (via modular symbols). EXAMPLES:: @@ -272,7 +272,7 @@ def _compute_hecke_matrix_prime(self, p): def hecke_polynomial(self, n, var='x'): r""" - Return the characteristic polynomial of the Hecke operator T_n on this + Return the characteristic polynomial of the Hecke operator `T_n` on this space. This is computed via modular symbols, and in particular is faster to compute than the matrix itself. @@ -320,7 +320,7 @@ class CuspidalSubmodule_level1_Q(CuspidalSubmodule): """ def _compute_q_expansion_basis(self, prec=None): """ - Compute q-expansions of a basis for self. + Compute `q`-expansions of a basis for ``self``. EXAMPLES:: @@ -358,7 +358,7 @@ class CuspidalSubmodule_wt1_eps(CuspidalSubmodule): def _compute_q_expansion_basis(self, prec=None): r""" - Compute q-expansion basis using Schaeffer's algorithm. + Compute `q`-expansion basis using Schaeffer's algorithm. EXAMPLES:: @@ -383,7 +383,7 @@ class CuspidalSubmodule_wt1_gH(CuspidalSubmodule): def _compute_q_expansion_basis(self, prec=None): r""" - Compute q-expansion basis using Schaeffer's algorithm. + Compute `q`-expansion basis using Schaeffer's algorithm. EXAMPLES:: @@ -540,7 +540,6 @@ def _compute_hecke_matrix(self, n): [ 0 1 0 0 1 0 0] sage: C.hecke_matrix(23) == 0 True - """ chars = self.group().characters_mod_H(sign=-1, galois_orbits=True) A = Matrix(QQ, 0, 0) @@ -590,9 +589,9 @@ class CuspidalSubmodule_gH_Q(CuspidalSubmodule_modsym_qexp): def _compute_hecke_matrix(self, n): r""" - Compute the matrix of the Hecke operator T_n acting on this space. + Compute the matrix of the Hecke operator `T_n` acting on this space. This is done directly using modular symbols, rather than using - q-expansions as for spaces with fixed character. + `q`-expansions as for spaces with fixed character. EXAMPLES:: @@ -671,8 +670,9 @@ def _convert_matrix_from_modsyms(symbs, T): the Atkin-Lehner operators, for instance, when there are oldforms present. OUTPUT: - A pair `(T_e, ps)` with `T_e` the converted matrix and `ps` a list - of pivot elements of the echelon basis. + + A pair `(T_e, ps)` with `T_e` the converted matrix and `ps` a list + of pivot elements of the echelon basis. EXAMPLES:: diff --git a/src/sage/modular/modform/eis_series.py b/src/sage/modular/modform/eis_series.py index f01c28fd0f2..dbdf09d6512 100644 --- a/src/sage/modular/modform/eis_series.py +++ b/src/sage/modular/modform/eis_series.py @@ -30,7 +30,7 @@ def eisenstein_series_qexp(k, prec=10, K=QQ, var='q', normalization='linear'): r""" Return the `q`-expansion of the normalized weight `k` Eisenstein series on - `\SL_2(\ZZ)` to precision prec in the ring `K`. Three normalizations + `\SL_2(\ZZ)` to precision ``prec`` in the ring `K`. Three normalizations are available, depending on the parameter ``normalization``; the default normalization is the one for which the linear coefficient is 1. @@ -42,7 +42,7 @@ def eisenstein_series_qexp(k, prec=10, K=QQ, var='q', normalization='linear'): - ``K`` -- (default: `\QQ`) a ring - - ``var`` -- (default: ``'q'``) variable name to use for q-expansion + - ``var`` -- (default: ``'q'``) variable name to use for `q`-expansion - ``normalization`` -- (default: ``'linear'``) normalization to use. If this is ``'linear'``, then the series will be normalized so that the linear @@ -78,7 +78,7 @@ def eisenstein_series_qexp(k, prec=10, K=QQ, var='q', normalization='linear'): 1 + 65520/691*q + 134250480/691*q^2 + 11606736960/691*q^3 + 274945048560/691*q^4 + O(q^5) sage: eisenstein_series_qexp(12, 5, normalization='linear') 691/65520 + q + 2049*q^2 + 177148*q^3 + 4196353*q^4 + O(q^5) - sage: eisenstein_series_qexp(12, 50, K=GF(13), normalization="constant") + sage: eisenstein_series_qexp(12, 50, K=GF(13), normalization='constant') 1 + O(q^50) TESTS: @@ -95,20 +95,20 @@ def eisenstein_series_qexp(k, prec=10, K=QQ, var='q', normalization='linear'): We check that the function behaves properly over finite-characteristic base rings:: - sage: eisenstein_series_qexp(12, 5, K = Zmod(691), normalization="integral") + sage: eisenstein_series_qexp(12, 5, K = Zmod(691), normalization='integral') 566*q + 236*q^2 + 286*q^3 + 194*q^4 + O(q^5) - sage: eisenstein_series_qexp(12, 5, K = Zmod(691), normalization="constant") + sage: eisenstein_series_qexp(12, 5, K = Zmod(691), normalization='constant') Traceback (most recent call last): ... ValueError: The numerator of -B_k/(2*k) (=691) must be invertible in the ring Ring of integers modulo 691 - sage: eisenstein_series_qexp(12, 5, K = Zmod(691), normalization="linear") + sage: eisenstein_series_qexp(12, 5, K = Zmod(691), normalization='linear') q + 667*q^2 + 252*q^3 + 601*q^4 + O(q^5) - sage: eisenstein_series_qexp(12, 5, K = Zmod(2), normalization="integral") + sage: eisenstein_series_qexp(12, 5, K = Zmod(2), normalization='integral') 1 + O(q^5) - sage: eisenstein_series_qexp(12, 5, K = Zmod(2), normalization="constant") + sage: eisenstein_series_qexp(12, 5, K = Zmod(2), normalization='constant') 1 + O(q^5) - sage: eisenstein_series_qexp(12, 5, K = Zmod(2), normalization="linear") + sage: eisenstein_series_qexp(12, 5, K = Zmod(2), normalization='linear') Traceback (most recent call last): ... ValueError: The denominator of -B_k/(2*k) (=65520) must be invertible in the ring Ring of integers modulo 2 @@ -385,11 +385,11 @@ def eisenstein_series_lseries(weight, prec=53, max_imaginary_part=0, max_asymp_coeffs=40): r""" - Return the L-series of the weight `2k` Eisenstein series + Return the `L`-series of the weight `2k` Eisenstein series on `\SL_2(\ZZ)`. This actually returns an interface to Tim Dokchitser's program - for computing with the L-series of the Eisenstein series + for computing with the `L`-series of the Eisenstein series INPUT: @@ -401,18 +401,16 @@ def eisenstein_series_lseries(weight, prec=53, - ``max_asymp_coeffs`` -- integer - OUTPUT: - - The L-series of the Eisenstein series. + OUTPUT: the `L`-series of the Eisenstein series EXAMPLES: - We compute with the L-series of `E_{16}` and then `E_{20}`:: + We compute with the `L`-series of `E_{16}` and then `E_{20}`:: sage: L = eisenstein_series_lseries(16) sage: L(1) -0.291657724743874 - sage: L = eisenstein_series_lseries(20) + sage: L = eisenstein_series_lseries(20) sage: L(2) -5.02355351645998 diff --git a/src/sage/modular/modform/eis_series_cython.pyx b/src/sage/modular/modform/eis_series_cython.pyx index 70271d3f80b..8126d1f8135 100644 --- a/src/sage/modular/modform/eis_series_cython.pyx +++ b/src/sage/modular/modform/eis_series_cython.pyx @@ -23,12 +23,10 @@ cpdef Ek_ZZ(int k, int prec=10): INPUT: - - `k` -- int - - ``prec`` -- int + - ``k`` -- integer + - ``prec`` -- integer - OUTPUT: - - - list of Sage Integers. + OUTPUT: list of integers EXAMPLES:: @@ -142,7 +140,7 @@ cpdef Ek_ZZ(int k, int prec=10): cpdef eisenstein_series_poly(int k, int prec=10): r""" - Return the q-expansion up to precision ``prec`` of the weight `k` + Return the `q`-expansion up to precision ``prec`` of the weight `k` Eisenstein series, as a FLINT :class:`~sage.libs.flint.fmpz_poly.Fmpz_poly` object, normalised so the coefficients are integers with no common factor. diff --git a/src/sage/modular/modform/eisenstein_submodule.py b/src/sage/modular/modform/eisenstein_submodule.py index 034d94479d5..2110ccf695f 100644 --- a/src/sage/modular/modform/eisenstein_submodule.py +++ b/src/sage/modular/modform/eisenstein_submodule.py @@ -60,7 +60,7 @@ def _repr_(self): def eisenstein_submodule(self): """ - Return the Eisenstein submodule of self. + Return the Eisenstein submodule of ``self``. (Yes, this is just self.) EXAMPLES:: @@ -125,7 +125,7 @@ class EisensteinSubmodule_params(EisensteinSubmodule): def parameters(self): r""" Return a list of parameters for each Eisenstein series - spanning self. That is, for each such series, return a triple + spanning ``self``. That is, for each such series, return a triple of the form (`\psi`, `\chi`, level), where `\psi` and `\chi` are the characters defining the Eisenstein series, and level is the smallest level at which this series occurs. @@ -169,7 +169,7 @@ def parameters(self): def new_submodule(self, p=None): r""" - Return the new submodule of self. + Return the new submodule of ``self``. EXAMPLES:: @@ -190,7 +190,7 @@ def new_submodule(self, p=None): def _parameters_character(self): """ - Return the character defining self. + Return the character defining ``self``. EXAMPLES:: @@ -201,7 +201,7 @@ def _parameters_character(self): def change_ring(self, base_ring): """ - Return self as a module over base_ring. + Return ``self`` as a module over ``base_ring``. EXAMPLES:: @@ -332,7 +332,7 @@ def new_eisenstein_series(self): def _compute_q_expansion_basis(self, prec=None, new=False): """ - Compute a q-expansion basis for self to precision prec. + Compute a `q`-expansion basis for ``self`` to precision ``prec``. EXAMPLES:: @@ -382,9 +382,9 @@ def _compute_q_expansion_basis(self, prec=None, new=False): def _q_expansion(self, element, prec): """ - Compute a q-expansion for a given element of self, expressed + Compute a `q`-expansion for a given element of self, expressed as a vector of coefficients for the basis vectors of self, - viewing self as a subspace of the corresponding space of + viewing ``self`` as a subspace of the corresponding space of modular forms. EXAMPLES:: @@ -429,7 +429,7 @@ class EisensteinSubmodule_gH_Q(EisensteinSubmodule_params): """ def _parameters_character(self): """ - Return the character defining self. Since self is + Return the character defining ``self``. Since ``self`` is a space of Eisenstein forms on GammaH(N) rather than a space with fixed character, we return the group GammaH(N) itself. @@ -475,24 +475,22 @@ def _compute_hecke_matrix(self, n, bound=None): INPUT: - - n: a positive integer + - ``n`` -- positive integer - - bound: an integer such that any element of this space with + - ``bound`` -- integer such that any element of this space with coefficients a_1, ..., a_b all zero must be the zero element. If this turns out not to be true, the code will increase the bound and try again. Setting bound = None is equivalent to setting bound = self.dimension(). - OUTPUT: - - - a matrix (over `\QQ`) + OUTPUT: matrix (over `\QQ`) ALGORITHM: This uses the usual pairing between modular symbols and modular forms, but in a slightly non-standard way. As for cusp forms, we can find a basis for this space made up of - forms with q-expansions `c_m(f) = a_{i,j}(T_m)`, where + forms with `q`-expansions `c_m(f) = a_{i,j}(T_m)`, where `T_m` denotes the matrix of the Hecke operator on the corresponding modular symbols space. Then `c_m(T_n f) = a_{i,j}(T_n* T_m)`. But we can't find the constant terms @@ -537,9 +535,9 @@ class EisensteinSubmodule_g1_Q(EisensteinSubmodule_gH_Q): """ def _parameters_character(self): r""" - Return the character defining self. + Return the character defining ``self``. - Since self is a space of Eisenstein + Since ``self`` is a space of Eisenstein forms on `\Gamma_1(N)`, all characters modulo the level are possible, so we return the level. @@ -586,7 +584,6 @@ class EisensteinSubmodule_eps(EisensteinSubmodule_params): q^4 - 2*zeta3*q^7 + O(q^10), q^5 + (zeta3 + 1)*q^8 + O(q^10) ] - """ # TODO #def _compute_q_expansion_basis(self, prec): @@ -594,21 +591,17 @@ class EisensteinSubmodule_eps(EisensteinSubmodule_params): #raise NotImplementedError, "must restrict scalars down correctly." -def cyclotomic_restriction(L,K): +def cyclotomic_restriction(L, K): r""" - Given two cyclotomic fields L and K, compute the compositum - M of K and L, and return a function and the index [M:K]. The - function is a map that acts as follows (here `M = Q(\zeta_m)`): - - INPUT: + Given two cyclotomic fields `L` and `K`, compute the compositum + `M` of `K` and `L`, and return a function `f` and the index `[M:K]`. - element alpha in L + The function `f` is a map that acts as follows (here `M =\QQ(\zeta_m)`): - OUTPUT: - - a polynomial `f(x)` in `K[x]` such that `f(\zeta_m) = \alpha`, - where we view alpha as living in `M`. (Note that `\zeta_m` - generates `M`, not `L`.) + INPUT: element alpha in `L` + OUTPUT: a polynomial `f(x)` in `K[x]` such that `f(\zeta_m) = \alpha`, + where we view alpha as living in `M`. (Note that `\zeta_m` generates + `M`, not `L`.) EXAMPLES:: @@ -637,16 +630,6 @@ def g(x): r""" Function returned by cyclotomic restriction. - INPUT: - - element alpha in L - - OUTPUT: - - a polynomial `f(x)` in `K[x]` such that `f(\zeta_m) = \alpha`, - where we view alpha as living in `M`. (Note that `\zeta_m` - generates `M`, not `L`.) - EXAMPLES:: sage: L = CyclotomicField(12) @@ -662,19 +645,13 @@ def g(x): euler_phi(L.zeta_order())//euler_phi(K.zeta_order()) -def cyclotomic_restriction_tower(L,K): - """ - Suppose L/K is an extension of cyclotomic fields and L=Q(zeta_m). +def cyclotomic_restriction_tower(L, K): + r""" + Suppose `L/K` is an extension of cyclotomic fields and `L=Q(\zeta_m)`. This function computes a map with the following property: - - INPUT: - - an element alpha in L - - OUTPUT: - - a polynomial `f(x)` in `K[x]` such that `f(zeta_m) = alpha`. + INPUT: element alpha in `L` + OUTPUT: a polynomial `f(x)` in `K[x]` such that `f(\zeta_m) = alpha` EXAMPLES:: @@ -699,14 +676,6 @@ def z(a): """ Function returned by cyclotomic_restriction_tower. - INPUT: - - an element alpha in L - - OUTPUT: - - a polynomial `f(x)` in `K[x]` such that `f(zeta_m) = alpha`. - EXAMPLES:: sage: L = CyclotomicField(121); K = CyclotomicField(11) diff --git a/src/sage/modular/modform/element.py b/src/sage/modular/modform/element.py index 72880952610..6ce83f0372e 100644 --- a/src/sage/modular/modform/element.py +++ b/src/sage/modular/modform/element.py @@ -90,14 +90,14 @@ def is_ModularFormElement(x): def delta_lseries(prec=53, max_imaginary_part=0, max_asymp_coeffs=40, algorithm=None): r""" - Return the L-series of the modular form `\Delta`. + Return the `L`-series of the modular form `\Delta`. - If algorithm is "gp", this returns an interface to Tim - Dokchitser's program for computing with the L-series of the + If algorithm is ``'gp'``, this returns an interface to Tim + Dokchitser's program for computing with the `L`-series of the modular form `\Delta`. - If algorithm is "pari", this returns instead an interface to Pari's - own general implementation of L-functions. + If algorithm is ``'pari'``, this returns instead an interface to Pari's + own general implementation of `L`-functions. INPUT: @@ -107,11 +107,11 @@ def delta_lseries(prec=53, max_imaginary_part=0, - ``max_asymp_coeffs`` -- integer - - ``algorithm`` -- optional string: 'gp' (default), 'pari' + - ``algorithm`` -- string; ``'gp'`` (default), ``'pari'`` OUTPUT: - The L-series of `\Delta`. + The `L`-series of `\Delta`. EXAMPLES:: @@ -175,7 +175,7 @@ def weight(self): def level(self): """ - Return the level of self. + Return the level of ``self``. EXAMPLES:: @@ -221,7 +221,7 @@ def _repr_(self): def __call__(self, x, prec=None): """ - Evaluate the q-expansion of this modular form at x. + Evaluate the `q`-expansion of this modular form at x. EXAMPLES:: @@ -239,7 +239,7 @@ def __call__(self, x, prec=None): @cached_method def valuation(self): """ - Return the valuation of self (i.e. as an element of the power + Return the valuation of ``self`` (i.e. as an element of the power series ring in q). EXAMPLES:: @@ -273,7 +273,7 @@ def qexp(self, prec=None): def __eq__(self, other): """ - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -294,7 +294,7 @@ def __eq__(self, other): def __ne__(self, other): """ - Return True if ``self != other``. + Return ``True`` if ``self != other``. EXAMPLES:: @@ -382,7 +382,7 @@ def coefficients(self, X): def __getitem__(self, n): """ - Returns the `q^n` coefficient of the `q`-expansion of self or + Return the `q^n` coefficient of the `q`-expansion of ``self`` or returns a list containing the `q^i` coefficients of self where `i` is in slice `n`. @@ -410,11 +410,11 @@ def __getitem__(self, n): def coefficient(self, n): r""" - Return the `n`-th coefficient of the `q`-expansion of self. + Return the `n`-th coefficient of the `q`-expansion of ``self``. INPUT: - - ``n`` -- non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -437,7 +437,7 @@ def coefficient(self, n): def padded_list(self, n): """ Return a list of length n whose entries are the first n - coefficients of the q-expansion of self. + coefficients of the `q`-expansion of ``self``. EXAMPLES:: @@ -450,7 +450,7 @@ def padded_list(self, n): def _latex_(self): """ - Return the LaTeX expression of self. + Return the LaTeX expression of ``self``. EXAMPLES:: @@ -464,7 +464,7 @@ def _latex_(self): def character(self, compute=True): """ - Return the character of self. If ``compute=False``, then this will + Return the character of ``self``. If ``compute=False``, then this will return None unless the form was explicitly created as an element of a space of forms with character, skipping the (potentially expensive) computation of the matrices of the diamond operators. @@ -562,7 +562,7 @@ def q_expansion(self, prec=None): sage: f.q_expansion(-1) Traceback (most recent call last): ... - ValueError: prec (= -1) must be non-negative + ValueError: prec (= -1) must be nonnegative """ if prec is None: prec = self.parent().prec() @@ -652,7 +652,7 @@ def atkin_lehner_eigenvalue(self, d=None, embedding=None): INPUT: - - ``d`` -- a positive integer exactly dividing the level `N` + - ``d`` -- positive integer exactly dividing the level `N` of ``self``, i.e. `d` divides `N` and is coprime to `N/d` (default: `d = N`) @@ -666,7 +666,7 @@ def atkin_lehner_eigenvalue(self, d=None, embedding=None): specified, and in (a suitable extension of) the base field of ``self`` otherwise. - If ``self`` is not an eigenform for `W_d`, a :class:`ValueError` is + If ``self`` is not an eigenform for `W_d`, a :exc:`ValueError` is raised. .. SEEALSO:: @@ -751,7 +751,7 @@ def period(self, M, prec=53): linear combinations of the real and the imaginary period of `E`:: sage: s = E.modular_symbol(sign=+1) - sage: t = E.modular_symbol(sign=-1, implementation="sage") + sage: t = E.modular_symbol(sign=-1, implementation='sage') sage: s(3/11), t(3/11) (1/10, 1/2) sage: s(3/11)*omega1 + t(3/11)*2*omega2.imag()*I @@ -804,7 +804,6 @@ def period(self, M, prec=53): sage: M = Gamma0(19)([10, 1, 19, 2]) sage: E.newform().period(M) # abs tol 1e-14 -1.35975973348831 + 1.09365931898146e-16*I - """ R = RealField(prec) @@ -853,29 +852,29 @@ def period(self, M, prec=53): def lseries(self, embedding=0, prec=53, max_imaginary_part=0, max_asymp_coeffs=40): r""" - Return the L-series of the weight k cusp form + Return the `L`-series of the weight k cusp form `f` on `\Gamma_0(N)`. This actually returns an interface to Tim Dokchitser's program for - computing with the L-series of the cusp form. + computing with the `L`-series of the cusp form. INPUT: - ``embedding`` -- either an embedding of the coefficient field of self into `\CC`, or an integer `i` between 0 and D-1 where D is the degree of the coefficient field (meaning to pick the `i`-th embedding). - (Default: 0) + (default: 0) - - ``prec`` -- integer (bits precision). Default: 53. + - ``prec`` -- integer (default: 53); bits precision - - ``max_imaginary_part`` -- real number. Default: 0. + - ``max_imaginary_part`` -- real number (default: 0) - - ``max_asymp_coeffs`` -- integer. Default: 40. + - ``max_asymp_coeffs`` -- integer (default: 40) For more information on the significance of the last three arguments, see :mod:`~sage.lfunctions.dokchitser`. - .. note:: + .. NOTE:: If an explicit embedding is given, but this embedding is specified to smaller precision than ``prec``, it will be automatically @@ -883,7 +882,7 @@ def lseries(self, embedding=0, prec=53, max_imaginary_part=0, OUTPUT: - The L-series of the cusp form, as a + The `L`-series of the cusp form, as a :class:`sage.lfunctions.dokchitser.Dokchitser` object. EXAMPLES:: @@ -925,7 +924,7 @@ def lseries(self, embedding=0, prec=53, max_imaginary_part=0, sage: f.lseries(embedding=1)(1) 0.298115272465799 + 0.0402203326076732*I - We compute with the L-series of the Eisenstein series `E_4`:: + We compute with the `L`-series of the Eisenstein series `E_4`:: sage: f = ModularForms(1,4).0 sage: L = f.lseries() @@ -1037,18 +1036,18 @@ def lseries(self, embedding=0, prec=53, max_imaginary_part=0, def symsquare_lseries(self, chi=None, embedding=0, prec=53): r""" - Compute the symmetric square L-series of this modular form, twisted by + Compute the symmetric square `L`-series of this modular form, twisted by the character `\chi`. INPUT: - - ``chi`` -- Dirichlet character to twist by, or None (default None, - interpreted as the trivial character). + - ``chi`` -- Dirichlet character to twist by, or ``None`` (default: + ``None``), interpreted as the trivial character) - ``embedding`` -- embedding of the coefficient field into `\RR` or `\CC`, or an integer `i` (in which case take the `i`-th embedding) - - ``prec`` -- The desired precision in bits (default 53). + - ``prec`` -- the desired precision in bits (default: 53) - OUTPUT: The symmetric square L-series of the cusp form, as a + OUTPUT: the symmetric square `L`-series of the cusp form, as a :class:`sage.lfunctions.dokchitser.Dokchitser` object. EXAMPLES:: @@ -1170,7 +1169,7 @@ def petersson_norm(self, embedding=0, prec=53): Only implemented for N = 1 at present. It is assumed that `f` has real coefficients. The norm is computed as a special value of the symmetric - square L-function, using the identity + square `L`-function, using the identity .. MATH:: @@ -1178,10 +1177,10 @@ def petersson_norm(self, embedding=0, prec=53): INPUT: - - ``embedding``: embedding of the coefficient field into `\RR` or + - ``embedding`` -- embedding of the coefficient field into `\RR` or `\CC`, or an integer `i` (interpreted as the `i`-th embedding) (default: 0) - - ``prec`` (integer, default 53): precision in bits + - ``prec`` -- integer (default: 53); precision in bits EXAMPLES:: @@ -1217,7 +1216,7 @@ def _q_expansion_bound(self, eps): This function takes as input a modular form, ``self`` and a Dirichlet character ``eps`` and returns an integer bound such that if ``self`` and its twist by ``eps`` have the same - q-expansion up to this bound, then they are equal. + `q`-expansion up to this bound, then they are equal. The bound is taken from [Mu1997]_. See also [Shi1971]_, Proposition 3.64. @@ -1226,9 +1225,7 @@ def _q_expansion_bound(self, eps): - ``eps`` -- a Dirichlet character - OUTPUT: - - A positive integer. + OUTPUT: a positive integer EXAMPLES: @@ -1268,9 +1265,7 @@ def has_cm(self): r""" Return whether the modular form ``self`` has complex multiplication. - OUTPUT: - - Boolean + OUTPUT: boolean .. SEEALSO:: @@ -1386,13 +1381,13 @@ def __init__(self, parent, component, names, check=True): INPUT: - - ``parent`` -- An ambient cuspidal space of modular forms for - which self is a newform. + - ``parent`` -- an ambient cuspidal space of modular forms for + which ``self`` is a newform - - ``component`` -- A simple component of a cuspidal modular - symbols space of any sign corresponding to this newform. + - ``component`` -- a simple component of a cuspidal modular + symbols space of any sign corresponding to this newform - - ``check`` -- If check is ``True``, check that parent and + - ``check`` -- if check is ``True``, check that parent and component have the same weight, level, and character, that component has sign 1 and is simple, and that the types are correct on all inputs. @@ -1429,9 +1424,9 @@ def __init__(self, parent, component, names, check=True): self.__hecke_eigenvalue_field = extension_field def _name(self): - """ + r""" Return the name of the generator of the Hecke eigenvalue field - of self. Note that a name exists even when this field is QQ. + of ``self``. Note that a name exists even when this field is `\QQ`. EXAMPLES:: @@ -1442,7 +1437,7 @@ def _name(self): def _compute_q_expansion(self, prec): """ - Return the q-expansion of self to precision prec. + Return the `q`-expansion of ``self`` to precision ``prec``. EXAMPLES:: @@ -1456,7 +1451,7 @@ def _compute_q_expansion(self, prec): def __eq__(self, other): """ - Return True if self equals other, and False otherwise. + Return ``True`` if ``self`` equals ``other``, and ``False`` otherwise. EXAMPLES:: @@ -1482,7 +1477,6 @@ def __eq__(self, other): q - 4*q^2 + 16*q^4 - 14*q^5 + O(q^6) sage: f == g True - """ if (not isinstance(other, ModularForm_abstract) or self.weight() != other.weight()): return False @@ -1504,7 +1498,7 @@ def __eq__(self, other): @cached_method def abelian_variety(self): """ - Return the abelian variety associated to self. + Return the abelian variety associated to ``self``. EXAMPLES:: @@ -1516,7 +1510,6 @@ def abelian_variety(self): Traceback (most recent call last): ... TypeError: f must have weight 2 - """ from sage.modular.abvar.abvar_newform import ModularAbelianVariety_newform return ModularAbelianVariety_newform(self) @@ -1540,15 +1533,13 @@ def hecke_eigenvalue_field(self): def coefficient(self, n): """ - Return the coefficient of `q^n` in the power series of self. + Return the coefficient of `q^n` in the power series of ``self``. INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - - the coefficient of `q^n` in the power series of self. + OUTPUT: the coefficient of `q^n` in the power series of ``self`` EXAMPLES:: @@ -1598,7 +1589,7 @@ def element(self): Find an element of the ambient space of modular forms which represents this newform. - .. note:: + .. NOTE:: This can be quite expensive. Also, the polynomial defining the field of Hecke eigenvalues should be considered random, @@ -1710,7 +1701,7 @@ def modsym_eigenspace(self, sign=0): def _defining_modular_symbols(self): """ - Return the modular symbols space corresponding to self. + Return the modular symbols space corresponding to ``self``. EXAMPLES:: @@ -1780,12 +1771,12 @@ def _atkin_lehner_eigenvalue_from_qexp(self, Q): - ``self`` -- a newform `f` - - ``Q`` -- an integer exactly dividing the level of ``self`` + - ``Q`` -- integer exactly dividing the level of ``self`` .. NOTE:: This method assumes that the `Q`-th coefficient in the - `q`-expansion of ``self`` is non-zero. + `q`-expansion of ``self`` is nonzero. TESTS:: @@ -1829,7 +1820,7 @@ def _atkin_lehner_eigenvalue_from_modsym(self, Q): - ``self`` -- a newform `f` - - ``Q`` -- a positive integer exactly dividing the level of ``self`` + - ``Q`` -- positive integer exactly dividing the level of ``self`` .. NOTE:: @@ -1986,8 +1977,8 @@ def atkin_lehner_eigenvalue(self, d=None, normalization='analytic', embedding=No INPUT: - - ``d`` -- a positive integer exactly dividing the level `N` of `f`, - i.e. `d` divides `N` and is coprime to `N/d`. The default is `d = N`. + - ``d`` -- positive integer exactly dividing the level `N` of `f`, + i.e., `d` divides `N` and is coprime to `N/d`; the default is `d = N` If `d` does not divide `N` exactly, then it will be replaced with a multiple `D` of `d` such that `D` exactly divides `N` and `D` has the @@ -1995,10 +1986,10 @@ def atkin_lehner_eigenvalue(self, d=None, normalization='analytic', embedding=No divide `N`. - ``normalization`` -- either ``'analytic'`` (the default) or - ``'arithmetic'``; see below. + ``'arithmetic'``; see below - ``embedding`` -- (optional) embedding of the coefficient field of `f` - into another ring. Ignored if `'normalization='arithmetic'``. + into another ring; ignored if ``'normalization='arithmetic'`` OUTPUT: @@ -2257,7 +2248,6 @@ def twist(self, chi, level=None, check=True): AUTHORS: - Peter Bruin (April 2015) - """ from sage.modular.all import CuspForms R = coercion_model.common_parent(self.base_ring(), chi.base_ring()) @@ -2432,16 +2422,15 @@ def __init__(self, parent, x, check=True): INPUT: - - ``parent`` -- ModularForms (an ambient space of modular forms) + - ``parent`` -- :class:`ModularFormsSpace` (an ambient space of modular + forms) - ``x`` -- a vector on the basis for parent - ``check`` -- if check is ``True``, check the types of the - inputs. - - OUTPUT: + inputs - - ``ModularFormElement`` -- a modular form + OUTPUT: ``ModularFormElement`` -- a modular form EXAMPLES:: @@ -2457,7 +2446,7 @@ def __init__(self, parent, x, check=True): def _compute_q_expansion(self, prec): """ - Computes the q-expansion of self to precision prec. + Compute the `q`-expansion of ``self`` to precision ``prec``. EXAMPLES:: @@ -2472,7 +2461,7 @@ def _compute_q_expansion(self, prec): def _add_(self, other): """ - Add self to other. + Add ``self`` to ``other``. EXAMPLES:: @@ -2491,10 +2480,10 @@ def _add_(self, other): def __mul__(self, other): r""" - Calculate the product self * other. + Calculate the product ``self * other``. This tries to determine the - characters of self and other, in order to avoid having to compute a + characters of ``self`` and ``other``, in order to avoid having to compute a (potentially very large) Gamma1 space. Note that this might lead to a modular form that is defined with respect to a larger subgroup than the factors are. @@ -2586,8 +2575,8 @@ def atkin_lehner_eigenvalue(self, d=None, embedding=None): INPUT: - - ``d`` -- a positive integer exactly dividing the level `N` of - ``self``, i.e. `d` divides `N` and is coprime to `N/d`. (Default: `d + - ``d`` -- positive integer exactly dividing the level `N` of + ``self``, i.e. `d` divides `N` and is coprime to `N/d`. (default: `d = N`) - ``embedding`` -- ignored (but accepted for compatibility with @@ -2596,7 +2585,7 @@ def atkin_lehner_eigenvalue(self, d=None, embedding=None): OUTPUT: The Atkin-Lehner eigenvalue of `W_d` on ``self``. If ``self`` is not an - eigenform for `W_d`, a :class:`ValueError` is raised. + eigenform for `W_d`, a :exc:`ValueError` is raised. .. SEEALSO:: @@ -2707,7 +2696,6 @@ def twist(self, chi, level=None): - \L. J. P. Kilford (2009-08-28) - Peter Bruin (2015-03-30) - """ from sage.modular.all import CuspForms, ModularForms R = coercion_model.common_parent(self.base_ring(), chi.base_ring()) @@ -2767,7 +2755,7 @@ def __init__(self, parent, E): def elliptic_curve(self): """ - Return elliptic curve associated to self. + Return elliptic curve associated to ``self``. EXAMPLES:: @@ -2824,7 +2812,7 @@ def atkin_lehner_eigenvalue(self, d=None, embedding=None): INPUT: - - ``d`` -- a positive integer exactly dividing the level `N` of + - ``d`` -- positive integer exactly dividing the level `N` of ``self``, i.e. `d` divides `N` and is coprime to `N/d`. (Defaults to `d = N` if not given.) @@ -2924,7 +2912,7 @@ def __init__(self, parent, vector, t, chi, psi): def _compute_q_expansion(self, prec=None): """ - Compute the q-expansion of self to precision prec. + Compute the `q`-expansion of ``self`` to precision ``prec``. EXAMPLES:: @@ -2951,7 +2939,6 @@ def _compute(self, X): [-9*zeta10^3 + 1, 16*zeta10^2 + 4*zeta10 + 1, 25*zeta10^3 - 25*zeta10^2 + 25*zeta10 - 24] - """ if self.weight() == 2 and (self.__chi.is_trivial() and self.__psi.is_trivial()): return self.__compute_weight2_trivial_character(X) @@ -2960,7 +2947,7 @@ def _compute(self, X): def __compute_weight2_trivial_character(self, X): r""" - Compute coefficients for self an Eisenstein series of the form + Compute coefficients for ``self`` an Eisenstein series of the form `E_2 - t*E_2(q^t)`. Computes `a_n` for each `n \in X`. EXAMPLES:: @@ -3057,7 +3044,7 @@ def __defining_parameters(self): def chi(self): """ - Return the parameter chi associated to self. + Return the parameter chi associated to ``self``. EXAMPLES:: @@ -3068,7 +3055,7 @@ def chi(self): def psi(self): """ - Return the parameter psi associated to self. + Return the parameter psi associated to ``self``. EXAMPLES:: @@ -3079,7 +3066,7 @@ def psi(self): def t(self): """ - Return the parameter t associated to self. + Return the parameter t associated to ``self``. EXAMPLES:: @@ -3090,7 +3077,7 @@ def t(self): def parameters(self): """ - Return chi, psi, and t, which are the defining parameters of self. + Return chi, psi, and t, which are the defining parameters of ``self``. EXAMPLES:: @@ -3124,7 +3111,7 @@ def M(self): @cached_method def character(self): """ - Return the character associated to self. + Return the character associated to ``self``. EXAMPLES:: @@ -3154,7 +3141,7 @@ def character(self): def new_level(self): """ - Return level at which self is new. + Return level at which ``self`` is new. EXAMPLES:: @@ -3217,13 +3204,11 @@ def __init__(self, parent, forms_datum): INPUT: - ``parent`` -- an object of the class ``ModularFormsRing`` - - ``forms_datum`` -- a dictionary ``{k_1:f_1, k_2:f_2, ..., k_n:f_n}`` + - ``forms_datum`` -- dictionary ``{k_1:f_1, k_2:f_2, ..., k_n:f_n}`` or a list ``[f_1, f_2,..., f_n]`` where `f_i` is a modular form of weight `k_i` - OUTPUT: - - A ``GradedModularFormElement`` corresponding to `f_1 + f_2 + ... + f_n` + OUTPUT: a ``GradedModularFormElement`` corresponding to `f_1 + f_2 + ... + f_n` TESTS:: @@ -3306,7 +3291,7 @@ def __init__(self, parent, forms_datum): def __bool__(self): r""" - Return "True" if ``self`` is non-zero and "False" otherwise. + Return "True" if ``self`` is nonzero and "False" otherwise. EXAMPLES:: @@ -3317,13 +3302,12 @@ def __bool__(self): True sage: bool(M(ModularForms(1,6).0)) True - """ return bool(self._forms_dictionary) def is_zero(self): r""" - Return "True" if the graded form is 0 and "False" otherwise + Return "True" if the graded form is 0 and "False" otherwise. EXAMPLES:: @@ -3340,7 +3324,7 @@ def is_zero(self): def is_one(self): r""" - Return "True" if the graded form is 1 and "False" otherwise + Return "True" if the graded form is 1 and "False" otherwise. EXAMPLES:: @@ -3405,7 +3389,7 @@ def q_expansion(self, prec=None): def _repr_(self): r""" - The string representation of self. + The string representation of ``self``. EXAMPLES:: @@ -3436,8 +3420,8 @@ def __getitem__(self, weight): INPUT: - - ``weight`` -- An integer corresponding to the weight of the - homogeneous component of the given graded modular form. + - ``weight`` -- integer corresponding to the weight of the + homogeneous component of the given graded modular form EXAMPLES:: @@ -3466,18 +3450,18 @@ def __getitem__(self, weight): sage: f[-1] Traceback (most recent call last): ... - ValueError: the weight must be non-negative + ValueError: the weight must be nonnegative """ if not isinstance(weight, (int, Integer)): raise KeyError("the weight must be an integer") if weight < 0: - raise ValueError("the weight must be non-negative") + raise ValueError("the weight must be nonnegative") return self._forms_dictionary.get(weight, self.parent().zero()) homogeneous_component = __getitem__ # alias def __call__(self, x, prec=None): r""" - Evaluate the q-expansion of this graded modular form at x. + Evaluate the `q`-expansion of this graded modular form at x. EXAMPLES:: @@ -3525,7 +3509,7 @@ def _add_(self, other): def __neg__(self): r""" - The negation of self. + The negation of ``self``. TESTS:: @@ -3579,13 +3563,13 @@ def _mul_(self, other): def _lmul_(self, c): r""" - The left action of the base ring on self. + The left action of the base ring on ``self``. INPUT: - ``c`` -- an element of the base ring of self - OUTPUT: A ``GradedModularFormElement``. + OUTPUT: a ``GradedModularFormElement`` TESTS:: @@ -3608,7 +3592,7 @@ def _lmul_(self, c): def _richcmp_(self, other, op): r""" - Compare self with other. + Compare ``self`` with ``other``. TESTS:: @@ -3688,7 +3672,8 @@ def weights_list(self): def is_homogeneous(self): r""" - Return True if the graded modular form is homogeneous, i.e. if it is a modular forms of a certain weight. + Return ``True`` if the graded modular form is homogeneous, i.e. if it + is a modular forms of a certain weight. An alias of this method is ``is_modular_form`` @@ -3714,10 +3699,11 @@ def _homogeneous_to_polynomial(self, names, gens): INPUT: - - ``names`` -- a list or tuple of names (strings), or a comma separated string; - - ``gens`` -- (list) a list of generator of ``self``. + - ``names`` -- list or tuple of names (strings), or a comma separated + string + - ``gens`` -- (list) a list of generator of ``self`` - OUTPUT: A polynomial in the variables ``names`` + OUTPUT: a polynomial in the variables ``names`` TESTS:: @@ -3794,13 +3780,14 @@ def to_polynomial(self, names='x', gens=None): INPUT: - - ``names`` -- a list or tuple of names (strings), or a comma separated string. Correspond - to the names of the variables; - - ``gens`` -- (default: None) a list of generator of the parent of ``self``. If set to ``None``, - the list returned by :meth:`~sage.modular.modform.find_generator.ModularFormsRing.gen_forms` + - ``names`` -- list or tuple of names (strings), or a comma separated + string; corresponds to the names of the variables + - ``gens`` -- (default: ``None``) a list of generator of the parent of + ``self``. If set to ``None``, the list returned by + :meth:`~sage.modular.modform.find_generator.ModularFormsRing.gen_forms` is used instead - OUTPUT: A polynomial in the variables ``names`` + OUTPUT: a polynomial in the variables ``names`` EXAMPLES:: @@ -3867,9 +3854,9 @@ def derivative(self, name='E2'): INPUT: - - ``name`` (str, default: 'E2') -- the name of the weight 2 Eisenstein - series generating the graded algebra of quasimodular forms over the - ring of modular forms. + - ``name``-- string (default: ``'E2'``); the name of the weight 2 + Eisenstein series generating the graded algebra of quasimodular forms + over the ring of modular forms OUTPUT: a :class:`sage.modular.quasimodform.element.QuasiModularFormsElement` diff --git a/src/sage/modular/modform/half_integral.py b/src/sage/modular/modform/half_integral.py index bf6c33e73a1..801e3715e21 100644 --- a/src/sage/modular/modform/half_integral.py +++ b/src/sage/modular/modform/half_integral.py @@ -28,9 +28,9 @@ def half_integral_weight_modform_basis(chi, k, prec): - ``k`` -- an odd integer > 1 - - ``prec`` -- a positive integer + - ``prec`` -- positive integer - OUTPUT: a list of power series + OUTPUT: list of power series .. warning:: diff --git a/src/sage/modular/modform/hecke_operator_on_qexp.py b/src/sage/modular/modform/hecke_operator_on_qexp.py index daf4c3bfbec..7191b52abfd 100644 --- a/src/sage/modular/modform/hecke_operator_on_qexp.py +++ b/src/sage/modular/modform/hecke_operator_on_qexp.py @@ -19,7 +19,7 @@ from sage.rings.infinity import Infinity from sage.rings.integer import Integer from sage.rings.integer_ring import ZZ -from sage.rings.power_series_ring_element import is_PowerSeries +from sage.rings.power_series_ring_element import PowerSeries lazy_import('sage.rings.number_field.number_field', 'CyclotomicField') @@ -87,7 +87,7 @@ def hecke_operator_on_qexp(f, n, k, eps=None, # ZZ can coerce to GF(p), but QQ can't. eps = DirichletGroup(1, base_ring=ZZ)[0] if check: - if not (is_PowerSeries(f) or isinstance(f, ModularFormElement)): + if not (isinstance(f, PowerSeries) or isinstance(f, ModularFormElement)): raise TypeError("f (=%s) must be a power series or modular form" % f) if not isinstance(eps, DirichletCharacter): raise TypeError("eps (=%s) must be a Dirichlet character" % eps) @@ -132,7 +132,7 @@ def hecke_operator_on_qexp(f, n, k, eps=None, def _hecke_operator_on_basis(B, V, n, k, eps): """ - Does the work for hecke_operator_on_basis once the input + Do the work for hecke_operator_on_basis once the input is normalized. EXAMPLES:: @@ -163,7 +163,7 @@ def hecke_operator_on_basis(B, n, k, eps=None, already_echelonized=False): with character `\varepsilon` to precision at least `\#B\cdot n+1`, this function computes the matrix of `T_n` relative to `B`. - .. note:: + .. NOTE:: If the elements of B are not known to sufficient precision, this function will report that the vectors are linearly @@ -171,16 +171,16 @@ def hecke_operator_on_basis(B, n, k, eps=None, already_echelonized=False): INPUT: - - ``B`` -- list of q-expansions + - ``B`` -- list of `q`-expansions - - ``n`` -- an integer >= 1 + - ``n`` -- integer >= 1 - - ``k`` -- an integer + - ``k`` -- integer - ``eps`` -- Dirichlet character - - ``already_echelonized`` -- bool (default: ``False``); if True, use that the - basis is already in Echelon form, which saves a lot of time. + - ``already_echelonized`` -- boolean (default: ``False``); if ``True``, use + that the basis is already in Echelon form, which saves a lot of time EXAMPLES:: @@ -235,7 +235,7 @@ def hecke_operator_on_basis(B, n, k, eps=None, already_echelonized=False): eps = DirichletGroup(1, R)[0] all_powerseries = True for x in B: - if not is_PowerSeries(x): + if not isinstance(x, PowerSeries): all_powerseries = False if not all_powerseries: raise TypeError("each element of B must be a power series") diff --git a/src/sage/modular/modform/l_series_gross_zagier.py b/src/sage/modular/modform/l_series_gross_zagier.py index 28acdeeb978..7959c346a2e 100644 --- a/src/sage/modular/modform/l_series_gross_zagier.py +++ b/src/sage/modular/modform/l_series_gross_zagier.py @@ -9,7 +9,7 @@ class GrossZagierLseries(SageObject): def __init__(self, E, A, prec=53): r""" - Class for the Gross-Zagier L-series. + Class for the Gross-Zagier `L`-series. This is attached to a pair `(E,A)` where `E` is an elliptic curve over `\QQ` and `A` is an ideal class in an imaginary quadratic number field. @@ -23,7 +23,7 @@ def __init__(self, E, A, prec=53): - ``A`` -- an ideal class in an imaginary quadratic number field - - ``prec`` -- an integer (default 53) giving the required precision + - ``prec`` -- integer (default: 53); giving the required precision EXAMPLES:: @@ -71,9 +71,9 @@ def __call__(self, s, der=0): INPUT: - - `s` -- complex number + - ``s`` -- complex number - - ``der`` -- ? (default 0) + - ``der`` -- (default: 0) EXAMPLES:: @@ -93,9 +93,9 @@ def taylor_series(self, s=1, series_prec=6, var='z'): INPUT: - - `s` -- complex number (default 1) - - ``series_prec`` -- number of terms (default 6) in the Taylor series - - ``var`` -- variable (default 'z') + - ``s`` -- complex number (default: 1) + - ``series_prec`` -- number of terms (default: 6) in the Taylor series + - ``var`` -- variable (default: ``'z'``) EXAMPLES:: diff --git a/src/sage/modular/modform/l_series_gross_zagier_coeffs.pyx b/src/sage/modular/modform/l_series_gross_zagier_coeffs.pyx index f91a3e256f0..b3dc41e1750 100644 --- a/src/sage/modular/modform/l_series_gross_zagier_coeffs.pyx +++ b/src/sage/modular/modform/l_series_gross_zagier_coeffs.pyx @@ -52,9 +52,7 @@ def bqf_theta_series(Q, long bound, var=None): - ``bound`` -- how many terms to compute - ``var`` -- (optional) the variable in which to express this power series - OUTPUT: - - A power series in ``var``, or list of ints if ``var`` is unspecified. + OUTPUT: a power series in ``var``, or list of ints if ``var`` is unspecified EXAMPLES:: @@ -99,19 +97,17 @@ cdef long* bqf_theta_series_c(long* terms, long bound, long a, long b, long c) e def gross_zagier_L_series(an_list, Q, long N, long u, var=None): """ - Compute the coefficients of the Gross-Zagier L-series. + Compute the coefficients of the Gross-Zagier `L`-series. INPUT: - - ``an_list`` -- list of coefficients of the L-series of an elliptic curve + - ``an_list`` -- list of coefficients of the `L`-series of an elliptic curve - ``Q`` -- a positive definite quadratic form - ``N`` -- conductor of the elliptic curve - ``u`` -- number of roots of unity in the field associated with ``Q`` - ``var`` -- (optional) the variable in which to express this power series - OUTPUT: - - A power series in ``var``, or list of ints if ``var`` is unspecified. + OUTPUT: a power series in ``var``, or list of ints if ``var`` is unspecified The number of terms is the length of the input ``an_list``. diff --git a/src/sage/modular/modform/numerical.py b/src/sage/modular/modform/numerical.py index 775cf222099..253047b2eab 100644 --- a/src/sage/modular/modform/numerical.py +++ b/src/sage/modular/modform/numerical.py @@ -34,27 +34,25 @@ @richcmp_method class NumericalEigenforms(SageObject): """ - numerical_eigenforms(group, weight=2, eps=1e-20, delta=1e-2, tp=[2,3,5]) + numerical_eigenforms(group, weight=2, eps=1e-20, delta=1e-2, tp=[2,3,5]). INPUT: - ``group`` -- a congruence subgroup of a Dirichlet character of order 1 or 2 - - ``weight`` -- an integer >= 2 + - ``weight`` -- integer >= 2 - ``eps`` -- a small float; abs( ) < eps is what "equal to zero" is - interpreted as for floating point numbers. + interpreted as for floating point numbers - ``delta`` -- a small-ish float; eigenvalues are considered distinct if their difference has absolute value at least delta - ``tp`` -- use the Hecke operators T_p for p in tp when searching - for a random Hecke operator with distinct Hecke eigenvalues. + for a random Hecke operator with distinct Hecke eigenvalues - OUTPUT: - - A numerical eigenforms object, with the following useful methods: + OUTPUT: a numerical eigenforms object, with the following useful methods: - :meth:`ap` -- return all eigenvalues of `T_p` @@ -65,7 +63,7 @@ class NumericalEigenforms(SageObject): [eigenvalues of T_3], [eigenvalues of T_5], ...] - - :meth:`systems_of_eigenvalues` -- a list of the systems of + - :meth:`systems_of_eigenvalues` -- list of the systems of eigenvalues of eigenforms such that the chosen random linear combination of Hecke operators has multiplicity 1 eigenvalues. @@ -154,7 +152,7 @@ def weight(self): def _repr_(self): """ - Print string representation of self. + Print string representation of ``self``. EXAMPLES:: @@ -367,11 +365,9 @@ def ap(self, p): INPUT: - - ``p`` -- integer, a prime number - - OUTPUT: + - ``p`` -- integer; a prime number - - ``list`` -- a list of double precision complex numbers + OUTPUT: list of double precision complex numbers EXAMPLES:: @@ -400,11 +396,9 @@ def eigenvalues(self, primes): INPUT: - - ``primes`` -- a list of primes + - ``primes`` -- list of primes - OUTPUT: - - list of lists of eigenvalues. + OUTPUT: list of lists of eigenvalues EXAMPLES:: @@ -442,7 +436,7 @@ def phi(y): def systems_of_eigenvalues(self, bound): """ - Return all systems of eigenvalues for self for primes + Return all systems of eigenvalues for ``self`` for primes up to bound. EXAMPLES:: @@ -470,7 +464,7 @@ def systems_of_eigenvalues(self, bound): def systems_of_abs(self, bound): """ Return the absolute values of all systems of eigenvalues for - self for primes up to bound. + ``self`` for primes up to bound. EXAMPLES:: @@ -506,6 +500,5 @@ def support(v, eps): sage: sage.modular.modform.numerical.support( numerical_eigenforms(61)._easy_vector(), 0.5 ) [0, 4] - """ return [i for i in range(v.degree()) if abs(v[i]) > eps] diff --git a/src/sage/modular/modform/ring.py b/src/sage/modular/modform/ring.py index bf7b10dc025..21d28730de6 100644 --- a/src/sage/modular/modform/ring.py +++ b/src/sage/modular/modform/ring.py @@ -54,15 +54,15 @@ def _span_of_forms_in_weight(forms, weight, prec, stop_dim=None, use_random=Fals - ``forms`` -- list of pairs `(k, f)` with k an integer and f a power series (all over the same base ring) - - ``weight`` -- an integer - - ``prec`` -- an integer (less than or equal to the precision of all the - forms in ``forms``) -- precision to use in power series computations. - - ``stop_dim`` -- an integer: stop as soon as we have enough forms to span + - ``weight`` -- integer + - ``prec`` -- integer (less than or equal to the precision of all the + forms in ``forms``); precision to use in power series computations + - ``stop_dim`` -- integer; stop as soon as we have enough forms to span a submodule of this rank (a saturated one if the base ring is `\ZZ`). - Ignored if ``use_random`` is False. - - ``use_random`` -- which algorithm to use. If True, tries random products + Ignored if ``use_random`` is ``False``. + - ``use_random`` -- which algorithm to use. If ``True``, tries random products of the generators of the appropriate weight until a large enough - submodule is found (determined by ``stop_dim``). If False, just tries + submodule is found (determined by ``stop_dim``). If ``False``, just tries everything. Note that if the given forms do generate the whole space, then @@ -189,7 +189,6 @@ class ModularFormsRing(Parent): 1 - 504*q - 16632*q^2 - 122976*q^3 - 532728*q^4 - 1575504*q^5 + O(q^6) sage: M((E4^3 - E6^2)/1728) q - 24*q^2 + 252*q^3 - 1472*q^4 + 4830*q^5 + O(q^6) - """ Element = GradedModularFormElement @@ -201,7 +200,7 @@ def __init__(self, group, base_ring=QQ): - ``group`` -- a congruence subgroup of `\SL_2(\ZZ)`, or a positive integer `N` (interpreted as `\Gamma_0(N)`) - - ``base_ring`` (ring, default: `\QQ`) -- a base ring, which should be + - ``base_ring``-- ring (default: `\QQ`); a base ring, which should be `\QQ`, `\ZZ`, or the integers mod `p` for some prime `p` TESTS: @@ -252,7 +251,7 @@ def change_ring(self, base_ring): INPUT: - ``base_ring`` -- a base ring, which should be `\QQ`, `\ZZ`, or the - integers mod `p` for some prime `p`. + integers mod `p` for some prime `p` EXAMPLES:: @@ -295,10 +294,10 @@ def gen(self, i): INPUT: - - ``i`` (Integer) -- correspond to the `i`-th modular form generating - the ring of modular forms. + - ``i`` -- integer; correspond to the `i`-th modular form generating + the ring of modular forms - OUTPUT: A ``GradedModularFormElement`` + OUTPUT: a ``GradedModularFormElement`` EXAMPLES:: @@ -314,7 +313,7 @@ def gen(self, i): def ngens(self): r""" - Return the number of generators of ``self`` + Return the number of generators of ``self``. EXAMPLES:: @@ -338,12 +337,14 @@ def polynomial_ring(self, names, gens=None): INPUT: - - ``names`` -- a list or tuple of names (strings), or a comma separated string - - ``gens`` (default: None) -- (list) a list of generator of ``self``. If ``gens`` is - ``None`` then the generators returned by :meth:`~sage.modular.modform.find_generator.ModularFormsRing.gen_forms` - is used instead. + - ``names`` -- list or tuple of names (strings), or a comma separated + string + - ``gens`` -- (default: ``None``) list of generator of + ``self``. If ``gens`` is ``None`` then the generators returned by + :meth:`~sage.modular.modform.find_generator.ModularFormsRing.gen_forms` + is used instead - OUTPUT: A multivariate polynomial ring in the variable ``names``. Each variable of the + OUTPUT: a multivariate polynomial ring in the variable ``names``. Each variable of the polynomial ring correspond to a generator given in gens (following the ordering of the list). EXAMPLES:: @@ -380,7 +381,7 @@ def _generators_variables_dictionnary(self, poly_parent, gens): INPUT: - - ``poly_parent`` -- A polynomial ring + - ``poly_parent`` -- a polynomial ring - ``gen`` -- list of generators of the modular forms ring TESTS:: @@ -409,14 +410,14 @@ def from_polynomial(self, polynomial, gens=None): INPUT: - - ``polynomial`` -- A multivariate polynomial. The variables names of + - ``polynomial`` -- a multivariate polynomial. The variables names of the polynomial should be different from ``'q'``. The number of variable of this polynomial should equal the number of generators - - ``gens`` -- list (default: ``None``) of generators of the modular + - ``gens`` -- list (default: ``None``); of generators of the modular forms ring - OUTPUT: A ``GradedModularFormElement`` given by the polynomial - relation ``polynomial``. + OUTPUT: a ``GradedModularFormElement`` given by the polynomial + relation ``polynomial`` EXAMPLES:: @@ -469,13 +470,13 @@ def from_polynomial(self, polynomial, gens=None): def _element_constructor_(self, forms_datum): r""" - The call method of self. + The call method of ``self``. INPUT: - - ``forms_datum`` (dict, list, ModularFormElement, - GradedModularFormElement, RingElement, Multivariate polynomial) -- Try - to coerce ``forms_datum`` into self. + - ``forms_datum`` -- dictionary, list, ModularFormElement, + GradedModularFormElement, RingElement, or Multivariate polynomial; try + to coerce ``forms_datum`` into ``self`` TESTS:: @@ -601,7 +602,7 @@ def _coerce_map_from_(self, M): def __richcmp__(self, other, op): r""" - Compare self to other. + Compare ``self`` to ``other``. Rings are equal if and only if their groups and base rings are. @@ -622,7 +623,7 @@ def __richcmp__(self, other, op): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -655,13 +656,13 @@ def generators(self, maxweight=8, prec=10, start_gens=[], start_weight=2): INPUT: - - ``maxweight`` (integer, default: 8) -- check up to this weight for + - ``maxweight``-- integer (default: 8); check up to this weight for generators - - ``prec`` (integer, default: 10) -- return `q`-expansions to this + - ``prec``-- integer (default: 10); return `q`-expansions to this precision - - ``start_gens`` (list, default: ``[]``) -- list of pairs `(k, f)`, or + - ``start_gens``-- list (default: ``[]``); list of pairs `(k, f)`, or triples `(k, f, F)`, where: - `k` is an integer, @@ -674,12 +675,12 @@ def generators(self, maxweight=8, prec=10, start_gens=[], start_weight=2): the case); otherwise, more terms will be calculated from the modular form object `F`. - - ``start_weight`` (integer, default: 2) -- calculate the graded - subalgebra of forms of weight at least ``start_weight``. + - ``start_weight`` -- integer (default: 2); calculate the graded + subalgebra of forms of weight at least ``start_weight`` OUTPUT: - a list of pairs (k, f), where f is the q-expansion to precision + a list of pairs (k, f), where f is the `q`-expansion to precision ``prec`` of a modular form of weight k. .. SEEALSO:: @@ -814,14 +815,14 @@ def gen_forms(self, maxweight=8, start_gens=[], start_weight=2): INPUT: - - ``maxweight`` (integer, default: 8) -- calculate forms generating all + - ``maxweight``-- integer (default: 8); calculate forms generating all forms up to this weight - - ``start_gens`` (list, default: ``[]``) -- a list of modular forms. If + - ``start_gens``-- list (default: ``[]``); list of modular forms. If this list is nonempty, we find a minimal generating set containing these forms - - ``start_weight`` (integer, default: 2) -- calculate the graded + - ``start_weight``-- integer (default: 2); calculate the graded subalgebra of forms of weight at least ``start_weight`` .. NOTE:: @@ -840,7 +841,6 @@ def gen_forms(self, maxweight=8, start_gens=[], start_weight=2): q - 9*q^4 - 10*q^5 + O(q^6)] sage: A[0].parent() Modular Forms space of dimension 2 for Congruence Subgroup Gamma0(11) of weight 2 over Rational Field - """ sgs = tuple( (F.weight(), None, F) for F in start_gens ) G = self._find_generators(maxweight, sgs, start_weight) @@ -853,7 +853,7 @@ def _find_generators(self, maxweight, start_gens, start_weight): For internal use. This function is called by :meth:`generators` and :meth:`gen_forms`: it returns a list of triples `(k, f, F)` where `F` is a modular form of weight `k` and `f` is its `q`-expansion coerced - into the base ring of self. + into the base ring of ``self``. INPUT: @@ -861,12 +861,10 @@ def _find_generators(self, maxweight, start_gens, start_weight): - ``start_weight`` -- minimum weight to try - ``start_gens`` -- a sequence of tuples of the form `(k, f, F)`, where `F` is a modular form of weight `k` and `f` is its `q`-expansion - coerced into ``self.base_ring()`. Either (but not both) of `f` and `F` + coerced into ``self.base_ring()``. Either (but not both) of `f` and `F` may be ``None``. - OUTPUT: - - a list of tuples, formatted as with ``start_gens``. + OUTPUT: list of tuples, formatted as with ``start_gens`` EXAMPLES:: @@ -975,19 +973,19 @@ def _find_generators(self, maxweight, start_gens, start_weight): @cached_method def q_expansion_basis(self, weight, prec=None, use_random=True): r""" - Calculate a basis of q-expansions for the space of modular forms of the + Calculate a basis of `q`-expansions for the space of modular forms of the given weight for this group, calculated using the ring generators given by ``find_generators``. INPUT: - - ``weight`` (integer) -- the weight - - ``prec`` (integer or ``None``, default: ``None``) -- power series + - ``weight`` -- integer; the weight + - ``prec`` -- integer or ``None`` (default: ``None``); power series precision. If ``None``, the precision defaults to the Sturm bound for the requested level and weight. - - ``use_random`` (boolean, default: ``True``) -- whether or not to use a + - ``use_random`` -- boolean (default: ``True``); whether or not to use a randomized algorithm when building up the space of forms at the given - weight from known generators of small weight. + weight from known generators of small weight EXAMPLES:: @@ -1130,8 +1128,8 @@ def cuspidal_submodule_q_expansion_basis(self, weight, prec=None): INPUT: - - ``weight`` (integer) -- the weight - - ``prec`` (integer or None) -- precision of `q`-expansions to return + - ``weight`` -- integer; the weight + - ``prec`` -- integer or ``None`` precision of `q`-expansions to return ALGORITHM: Uses the method :meth:`cuspidal_ideal_generators` to calculate generators of the ideal of cusp forms inside this ring. Then diff --git a/src/sage/modular/modform/space.py b/src/sage/modular/modform/space.py index 7dba1ae3a0f..9d4e9caa7f1 100644 --- a/src/sage/modular/modform/space.py +++ b/src/sage/modular/modform/space.py @@ -70,7 +70,7 @@ from sage.rings.integer import Integer from sage.rings.integer_ring import ZZ from sage.rings.power_series_ring import PowerSeriesRing -from sage.rings.power_series_ring_element import is_PowerSeries +from sage.rings.power_series_ring_element import PowerSeries from sage.rings.rational_field import QQ from sage.categories.rings import Rings @@ -87,7 +87,7 @@ def is_ModularFormsSpace(x): r""" - Return True if x is a ```ModularFormsSpace```. + Return ``True`` if x is a ``ModularFormsSpace``. EXAMPLES:: @@ -163,11 +163,9 @@ def prec(self, new_prec=None): INPUT: + - ``new_prec`` -- positive integer (default: ``None``) - - ``new_prec`` -- positive integer (default: None) - - - OUTPUT: if new_prec is None, returns the current precision. + OUTPUT: if new_prec is None, returns the current precision EXAMPLES:: @@ -195,9 +193,7 @@ def set_precision(self, new_prec): INPUT: - - - ``new_prec`` -- positive integer - + - ``new_prec`` -- positive integer EXAMPLES:: @@ -346,11 +342,11 @@ def character(self): def has_character(self): r""" - Return True if this space of modular forms has a specific + Return ``True`` if this space of modular forms has a specific character. - This is True exactly when the character() function does not return - None. + This is ``True`` exactly when the ``character()`` function does not + return ``None``. EXAMPLES: A space for `\Gamma_0(N)` has trivial character, hence has a character. @@ -374,7 +370,7 @@ def has_character(self): def is_ambient(self): """ - Return True if this an ambient space of modular forms. + Return ``True`` if this an ambient space of modular forms. EXAMPLES:: @@ -417,7 +413,7 @@ def __normalize_prec(self, prec): @cached_method def echelon_form(self): r""" - Return a space of modular forms isomorphic to self but with basis + Return a space of modular forms isomorphic to ``self`` but with basis of `q`-expansions in reduced echelon form. This is useful, e.g., the default basis for spaces of modular forms @@ -490,7 +486,7 @@ def echelon_form(self): @cached_method def echelon_basis(self): """ - Return a basis for self in reduced echelon form. This means that if + Return a basis for ``self`` in reduced echelon form. This means that if we view the `q`-expansions of the basis as defining rows of a matrix (with infinitely many columns), then this matrix is in reduced echelon form. @@ -619,7 +615,7 @@ def integral_basis(self): @cached_method def _q_expansion_module(self): """ - Return module spanned by coefficients of q-expansions to sufficient + Return module spanned by coefficients of `q`-expansions to sufficient precision to determine elements of this space. EXAMPLES:: @@ -642,7 +638,7 @@ def _q_expansion_module(self): def q_expansion_basis(self, prec=None): """ - Return a sequence of q-expansions for the basis of this space + Return a sequence of `q`-expansions for the basis of this space computed to the given input precision. INPUT: @@ -650,12 +646,12 @@ def q_expansion_basis(self, prec=None): - ``prec`` -- integer (>=0) or None If prec is None, the prec is computed to be *at least* large - enough so that each q-expansion determines the form as an element + enough so that each `q`-expansion determines the form as an element of this space. - .. note:: + .. NOTE:: - In fact, the q-expansion basis is always computed to + In fact, the `q`-expansion basis is always computed to *at least* ``self.prec()``. EXAMPLES:: @@ -749,7 +745,7 @@ def _compute_q_expansion_basis(self, prec): def q_echelon_basis(self, prec=None): r""" Return the echelon form of the basis of `q`-expansions of - self up to precision prec. + ``self`` up to precision ``prec``. The `q`-expansions are power series (not actual modular forms). The number of `q`-expansions returned equals the @@ -802,12 +798,12 @@ def q_echelon_basis(self, prec=None): def q_integral_basis(self, prec=None): r""" Return a `\ZZ`-reduced echelon basis of - `q`-expansions for self. + `q`-expansions for ``self``. The `q`-expansions are power series with coefficients in `\ZZ`; they are *not* actual modular forms. - The base ring of self must be `\QQ`. The number of + The base ring of ``self`` must be `\QQ`. The number of `q`-expansions returned equals the dimension. EXAMPLES:: @@ -852,7 +848,7 @@ def q_integral_basis(self, prec=None): @cached_method def _q_expansion_ring(self): """ - Returns the parent for q-expansions of modular forms in self. + Return the parent for `q`-expansions of modular forms in ``self``. EXAMPLES:: @@ -865,7 +861,7 @@ def _q_expansion_ring(self): @cached_method def _q_expansion_zero(self): """ - Returns the q-expansion of the modular form 0. + Return the `q`-expansion of the modular form 0. EXAMPLES:: @@ -879,8 +875,8 @@ def _q_expansion_zero(self): def _q_expansion(self, element, prec): """ - Take an element of self (specified as a list, tuple, or vector), - and return the corresponding q-expansion. + Take an element of ``self`` (specified as a list, tuple, or vector), + and return the corresponding `q`-expansion. EXAMPLES:: @@ -899,7 +895,7 @@ def _q_expansion(self, element, prec): def __add__(self, right): """ - If self and right live inside the same ambient module, return the + If ``self`` and ``right`` live inside the same ambient module, return the sum of the two spaces (as modules). EXAMPLES:: @@ -929,15 +925,13 @@ def __add__(self, right): def _has_natural_inclusion_map_to(self, right): """ Return true if there is a natural inclusion map from modular forms - in self to modular forms in right. + in ``self`` to modular forms in right. INPUT: + - ``self``, ``right`` -- spaces of modular forms - - ``self, right`` -- spaces of modular forms - - - OUTPUT: True if self embeds in right, and False otherwise. + OUTPUT: ``True`` if ``self`` embeds in ``right``, ``False`` otherwise TODO: Barring a few trivial cases, this only works in the case that right.is_ambient() returns True. @@ -997,11 +991,11 @@ def _coerce_map_from_(self, from_par): def _element_constructor_(self, x, check=True): """ - Try to coerce x into self. If x is a vector of length - self.dimension(), interpret it as a list of coefficients for - self.basis() and return that linear combination. If x is a power - series, it tries to determine whether or not x lives in self. If - so, it returns x as an element of M, and throws an error if not. + Try to coerce ``x`` into ``self``. If ``x`` is a vector of length + ``self.dimension()``, interpret it as a list of coefficients for + ``self.basis()`` and return that linear combination. If ``x`` is a power + series, it tries to determine whether or not ``x`` lives in ``self``. If + so, it returns ``x`` as an element of M, and throws an error if not. EXAMPLES:: @@ -1066,7 +1060,7 @@ def _element_constructor_(self, x, check=True): sage: ModularForms(1, 12)(R(1)) Traceback (most recent call last): ... - TypeError: unable to create modular form from exact non-zero polynomial + TypeError: unable to create modular form from exact nonzero polynomial sage: E = ModularForms(3,12).cuspidal_subspace() sage: f = E.gens()[0] @@ -1121,12 +1115,12 @@ def _element_constructor_(self, x, check=True): return self(x.q_expansion(self._q_expansion_module().degree())) - elif is_PowerSeries(x): + elif isinstance(x, PowerSeries): if x.prec() == PlusInfinity(): if x == 0: return self.element_class(self, self.free_module().zero()) else: - raise TypeError("unable to create modular form from exact non-zero polynomial") + raise TypeError("unable to create modular form from exact nonzero polynomial") W = self._q_expansion_module() if W.degree() <= x.prec(): try: @@ -1152,7 +1146,7 @@ def _pushout_(self, other): - ``other`` -- ``ModularFormSpace`` or a ``ModularFormRing`` - OUTPUT: If ``self`` and ``other`` have the same groups and base rings, then this method returns + OUTPUT: if ``self`` and ``other`` have the same groups and base rings, then this method returns ``self`` if the weights of the two spaces are equal, otherwise it returns a ``ModularFormsRing``. @@ -1184,7 +1178,7 @@ def _pushout_(self, other): def __richcmp__(self, x, op): """ - Compare self and x. + Compare ``self`` and ``x``. For spaces of modular forms, we order first by signature, then by dimension, and then by the ordering on the underlying free @@ -1227,7 +1221,7 @@ def __richcmp__(self, x, op): def span_of_basis(self, B): """ - Take a set B of forms, and return the subspace of self with B as a + Take a set B of forms, and return the subspace of ``self`` with B as a basis. EXAMPLES:: @@ -1262,7 +1256,7 @@ def span_of_basis(self, B): def __submodule_from_subset_of_basis(self, x): """ - Return the submodule of self generated by the elements of x. + Return the submodule of ``self`` generated by the elements of x. EXAMPLES:: @@ -1278,7 +1272,7 @@ def __submodule_from_subset_of_basis(self, x): def _compute_hecke_matrix_prime(self, p, prec=None): """ - Compute the matrix of the Hecke operator T_p acting on self. + Compute the matrix of the Hecke operator `T_p` acting on ``self``. EXAMPLES:: @@ -1321,7 +1315,7 @@ def _compute_hecke_matrix_prime(self, p, prec=None): def _compute_hecke_matrix(self, n): """ - Compute the matrix of the Hecke operator T_n acting on self. + Compute the matrix of the Hecke operator `T_n` acting on ``self``. EXAMPLES:: @@ -1378,7 +1372,7 @@ def _compute_hecke_matrix(self, n): @cached_method def basis(self): """ - Return a basis for self. + Return a basis for ``self``. EXAMPLES:: @@ -1395,7 +1389,7 @@ def basis(self): def gen(self, n): """ - Return the nth generator of self. + Return the `n`-th generator of ``self``. EXAMPLES:: @@ -1433,7 +1427,7 @@ def gen(self, n): def gens(self): """ - Return a complete set of generators for self. + Return a complete set of generators for ``self``. EXAMPLES:: @@ -1452,10 +1446,10 @@ def gens(self): def sturm_bound(self, M=None): r""" For a space M of modular forms, this function returns an integer B - such that two modular forms in either self or M are equal if and - only if their q-expansions are equal to precision B (note that this + such that two modular forms in either ``self`` or M are equal if and + only if their `q`-expansions are equal to precision B (note that this is 1+ the usual Sturm bound, since `O(q^\mathrm{prec})` has - precision prec). If M is none, then M is set equal to self. + precision ``prec``). If M is none, then M is set equal to ``self``. EXAMPLES:: @@ -1518,7 +1512,7 @@ def sturm_bound(self, M=None): def cuspidal_submodule(self): """ - Return the cuspidal submodule of self. + Return the cuspidal submodule of ``self``. EXAMPLES:: @@ -1587,7 +1581,7 @@ def cuspidal_subspace(self): def is_cuspidal(self): r""" - Return True if this space is cuspidal. + Return ``True`` if this space is cuspidal. EXAMPLES:: @@ -1601,7 +1595,7 @@ def is_cuspidal(self): def is_eisenstein(self): r""" - Return True if this space is Eisenstein. + Return ``True`` if this space is Eisenstein. EXAMPLES:: @@ -1615,11 +1609,11 @@ def is_eisenstein(self): def new_submodule(self, p=None): """ - Return the new submodule of self. + Return the new submodule of ``self``. - If p is specified, return the p-new submodule of self. + If `p` is specified, return the `p`-new submodule of ``self``. - .. note:: + .. NOTE:: This function should be overridden by all derived classes. @@ -1651,7 +1645,7 @@ def eisenstein_series(self): """ Compute the Eisenstein series associated to this space. - .. note:: + .. NOTE:: This function should be overridden by all derived classes. @@ -1673,7 +1667,7 @@ def decomposition(self): self, if possible. The space `V(f_i,t)` is the image under `g(q)` maps to `g(q^t)` of the intersection with `R[[q]]` of the space spanned by the conjugates of - `f_i`, where `R` is the base ring of self. + `f_i`, where `R` is the base ring of ``self``. TODO: Implement this function. @@ -1688,7 +1682,7 @@ def decomposition(self): def newforms(self, names=None): """ - Return all newforms in the cuspidal subspace of self. + Return all newforms in the cuspidal subspace of ``self``. EXAMPLES:: @@ -1766,7 +1760,7 @@ def eisenstein_subspace(self): def embedded_submodule(self): """ - Return the underlying module of self. + Return the underlying module of ``self``. EXAMPLES:: @@ -1823,7 +1817,7 @@ def embedded_submodule(self): def level(self): """ - Return the level of self. + Return the level of ``self``. EXAMPLES:: @@ -1835,7 +1829,7 @@ def level(self): def modular_symbols(self, sign=0): """ - Return the space of modular symbols corresponding to self with the + Return the space of modular symbols corresponding to ``self`` with the given sign. .. NOTE:: @@ -1856,27 +1850,25 @@ def find_in_space(self, f, forms=None, prec=None, indep=True): """ INPUT: + - ``f`` -- a modular form or power series - - ``f`` -- a modular form or power series + - ``forms`` -- (default: ``None``) a specific list of + modular forms or `q`-expansions - - ``forms`` -- (default: None) a specific list of - modular forms or q-expansions. + - ``prec`` -- if forms are given, compute with them to + the given precision - - ``prec`` -- if forms are given, compute with them to - the given precision + - ``indep`` -- boolean (default: ``True``); whether the given list + of forms are assumed to form a basis - - ``indep`` -- (default: ``True``) whether the given list - of forms are assumed to form a basis. - - - OUTPUT: A list of numbers that give f as a linear combination of + OUTPUT: list of numbers that give f as a linear combination of the basis for this space or of the given forms if independent=True. - .. note:: + .. NOTE:: If the list of forms is given, they do *not* have to be in - self. + ``self``. EXAMPLES:: @@ -1914,7 +1906,7 @@ def find_in_space(self, f, forms=None, prec=None, indep=True): B = V.span_of_basis(w) else: B = V.span(w) - if is_PowerSeries(f) and f.prec() < n: + if isinstance(f, PowerSeries) and f.prec() < n: raise ValueError("you need at least %s terms of precision" % n) x = V(f.padded_list(n)) return B.coordinates(x) diff --git a/src/sage/modular/modform/submodule.py b/src/sage/modular/modform/submodule.py index 15a45b80069..992b7ed6231 100644 --- a/src/sage/modular/modform/submodule.py +++ b/src/sage/modular/modform/submodule.py @@ -39,11 +39,11 @@ def __init__(self, ambient_module, submodule, dual=None, check=False): """ INPUT: - - ambient_module -- ModularFormsSpace - - submodule -- a submodule of the ambient space. - - dual_module -- (default: None) ignored - - check -- (default: ``False``) whether to check that the - submodule is Hecke equivariant + - ``ambient_module`` -- ModularFormsSpace + - ``submodule`` -- a submodule of the ambient space + - ``dual_module`` -- (default: ``None``) ignored + - ``check`` -- boolean (default: ``False``); whether to check that the + submodule is Hecke equivariant EXAMPLES:: @@ -51,7 +51,6 @@ def __init__(self, ambient_module, submodule, dual=None, check=False): Modular Forms space of dimension 13 for Congruence Subgroup Gamma1(13) of weight 2 over Rational Field sage: M.eisenstein_subspace() Eisenstein subspace of dimension 11 of Modular Forms space of dimension 13 for Congruence Subgroup Gamma1(13) of weight 2 over Rational Field - """ A = ambient_module sage.modular.hecke.submodule.HeckeSubmodule.__init__(self, A, submodule, check=check) @@ -69,7 +68,7 @@ def _repr_(self): def _compute_coefficients(self, element, X): """ - Compute all coefficients of the modular form element in self for + Compute all coefficients of the modular form element in ``self`` for indices in X. TODO: Implement this function. @@ -86,7 +85,8 @@ def _compute_coefficients(self, element, X): def _compute_q_expansion_basis(self, prec): """ - Compute q_expansions to precision prec for each element in self.basis(). + Compute ``q_expansions`` to precision ``prec`` for each element in + ``self.basis()``. EXAMPLES:: diff --git a/src/sage/modular/modform/theta.py b/src/sage/modular/modform/theta.py index ea0a88c81ba..92c5f945a1c 100644 --- a/src/sage/modular/modform/theta.py +++ b/src/sage/modular/modform/theta.py @@ -17,13 +17,11 @@ def theta2_qexp(prec=10, var='q', K=ZZ, sparse=False): INPUT: - - prec -- integer; the absolute precision of the output - - var -- (default: 'q') variable name - - K -- (default: ZZ) base ring of answer + - ``prec`` -- integer; the absolute precision of the output + - ``var`` -- (default: ``'q'``) variable name + - ``K`` -- (default: ZZ) base ring of answer - OUTPUT: - - a power series over K + OUTPUT: a power series over K EXAMPLES:: @@ -67,13 +65,11 @@ def theta_qexp(prec=10, var='q', K=ZZ, sparse=False): INPUT: - - prec -- integer; the absolute precision of the output - - var -- (default: 'q') variable name - - K -- (default: ZZ) base ring of answer - - OUTPUT: + - ``prec`` -- integer; the absolute precision of the output + - ``var`` -- (default: ``'q'``) variable name + - ``K`` -- (default: ZZ) base ring of answer - a power series over K + OUTPUT: a power series over K EXAMPLES:: @@ -91,7 +87,6 @@ def theta_qexp(prec=10, var='q', K=ZZ, sparse=False): 1 + 2*q + 2*q^4 + 2*q^9 + 2*q^16 + O(q^20) sage: parent(f) Sparse Power Series Ring in q over Integer Ring - """ prec = Integer(prec) if prec <= 0: diff --git a/src/sage/modular/modform/vm_basis.py b/src/sage/modular/modform/vm_basis.py index 6e04ad12156..bbbbd9b4513 100644 --- a/src/sage/modular/modform/vm_basis.py +++ b/src/sage/modular/modform/vm_basis.py @@ -53,17 +53,15 @@ def victor_miller_basis(k, prec=10, cusp_only=False, var='q'): INPUT: - - ``k`` -- an integer + - ``k`` -- integer - ``prec`` -- (default: 10) a positive integer - - ``cusp_only`` -- bool (default: ``False``) + - ``cusp_only`` -- boolean (default: ``False``) - - ``var`` -- string (default: 'q') + - ``var`` -- string (default: ``'q'``) - OUTPUT: - - A sequence whose entries are power series in ``ZZ[[var]]``. + OUTPUT: a sequence whose entries are power series in ``ZZ[[var]]`` EXAMPLES:: @@ -132,7 +130,7 @@ def victor_miller_basis(k, prec=10, cusp_only=False, var='q'): if k % 2 == 1 or k == 2: return Sequence([]) elif k < 0: - raise ValueError("k must be non-negative") + raise ValueError("k must be nonnegative") elif k == 0: return Sequence([PowerSeriesRing(ZZ,var)(1).add_bigoh(prec)], cr=True) e = k.mod(12) @@ -218,7 +216,7 @@ def victor_miller_basis(k, prec=10, cusp_only=False, var='q'): def _delta_poly(prec=10): """ - Return the q-expansion of Delta as a FLINT polynomial. Used internally by + Return the `q`-expansion of Delta as a FLINT polynomial. Used internally by the :func:`~delta_qexp` function. See the docstring of :func:`~delta_qexp` for more information. @@ -228,7 +226,7 @@ def _delta_poly(prec=10): OUTPUT: - the q-expansion of Delta to precision ``prec``, as a FLINT + the `q`-expansion of Delta to precision ``prec``, as a FLINT :class:`~sage.libs.flint.fmpz_poly.Fmpz_poly` object. EXAMPLES:: @@ -274,13 +272,13 @@ def _delta_poly(prec=10): def _delta_poly_modulo(N, prec=10): r""" - Return the q-expansion of `\Delta` modulo `N`. Used internally by + Return the `q`-expansion of `\Delta` modulo `N`. Used internally by the :func:`~delta_qexp` function. See the docstring of :func:`~delta_qexp` for more information. INPUT: - - `N` -- positive integer modulo which we want to compute `\Delta` + - ``N`` -- positive integer modulo which we want to compute `\Delta` - ``prec`` -- integer; the absolute precision of the output @@ -333,16 +331,14 @@ def delta_qexp(prec=10, var='q', K=ZZ) : INPUT: - - ``prec`` -- integer (default 10), the absolute precision of the output + - ``prec`` -- integer (default: 10); the absolute precision of the output (must be positive) - - ``var`` -- string (default: 'q'), variable name + - ``var`` -- string (default: ``'q'``); variable name - - ``K`` -- ring (default: `\ZZ`), base ring of answer - - OUTPUT: + - ``K`` -- ring (default: `\ZZ`); base ring of answer - a power series over K in the variable ``var`` + OUTPUT: a power series over K in the variable ``var`` ALGORITHM: diff --git a/src/sage/modular/modform/weight1.py b/src/sage/modular/modform/weight1.py index c2ce006decb..a2f5aa10108 100644 --- a/src/sage/modular/modform/weight1.py +++ b/src/sage/modular/modform/weight1.py @@ -27,7 +27,7 @@ def modular_ratio_space(chi): level N and character chi such that f * E is a holomorphic cusp form for every Eisenstein series E of weight 1 and character 1/chi. - Elements are returned as q-expansions up to precision R, where R is one + Elements are returned as `q`-expansions up to precision R, where R is one greater than the weight 3 Sturm bound. EXAMPLES:: @@ -80,7 +80,7 @@ def modular_ratio_space(chi): def modular_ratio_to_prec(chi, qexp, prec): r""" - Given a q-expansion of a modular ratio up to sufficient precision to + Given a `q`-expansion of a modular ratio up to sufficient precision to determine it uniquely, compute it to greater precision. EXAMPLES:: @@ -103,9 +103,9 @@ def modular_ratio_to_prec(chi, qexp, prec): @cached_function def hecke_stable_subspace(chi, aux_prime=ZZ(2)): r""" - Compute a q-expansion basis for S_1(chi). + Compute a `q`-expansion basis for `S_1(\chi)`. - Results are returned as q-expansions to a certain fixed (and fairly high) + Results are returned as `q`-expansions to a certain fixed (and fairly high) precision. If more precision is required this can be obtained with :func:`modular_ratio_to_prec`. diff --git a/src/sage/modular/modform_hecketriangle/abstract_ring.py b/src/sage/modular/modform_hecketriangle/abstract_ring.py index b0bf6a850a3..e62cdcb47af 100644 --- a/src/sage/modular/modform_hecketriangle/abstract_ring.py +++ b/src/sage/modular/modform_hecketriangle/abstract_ring.py @@ -50,17 +50,15 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: `\Z`). + - ``base_ring`` -- the base_ring (default: `\Z`) - - ``red_hom`` -- If ``True`` then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the (Hecke) forms. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the (Hecke) forms. - OUTPUT: - - The corresponding abstract (Hecke) forms ring. + OUTPUT: the corresponding abstract (Hecke) forms ring EXAMPLES:: @@ -260,16 +258,17 @@ def _an_element_(self): def default_prec(self, prec=None): r""" Set the default precision ``prec`` for the Fourier expansion. - If ``prec=None`` (default) then the current default precision is returned instead. + If ``prec=None`` (default) then the current default precision is + returned instead. INPUT: - - ``prec`` -- An integer. + - ``prec`` -- integer - NOTE: + .. NOTE:: - This is also used as the default precision for the Fourier - expansion when evaluating forms. + This is also used as the default precision for the Fourier + expansion when evaluating forms. EXAMPLES:: @@ -408,14 +407,12 @@ def extend_type(self, analytic_type=None, ring=False): INPUT: - - ``analytic_type`` -- An ``AnalyticType`` or something which - coerces into it (default: ``None``). + - ``analytic_type`` -- an ``AnalyticType`` or something which + coerces into it (default: ``None``) - - ``ring`` -- Whether to extend to a graded ring (default: ``False``). - - OUTPUT: + - ``ring`` -- whether to extend to a graded ring (default: ``False``) - The new extended space. + OUTPUT: the new extended space EXAMPLES:: @@ -454,14 +451,13 @@ def reduce_type(self, analytic_type=None, degree=None): INPUT: - - ``analytic_type`` -- An ``AnalyticType`` or something which coerces into it (default: ``None``). + - ``analytic_type`` -- an ``AnalyticType`` or something which coerces + into it (default: ``None``) - - ``degree`` -- ``None`` (default) or the degree of the homogeneous component to which - ``self`` should be reduced. + - ``degree`` -- ``None`` (default) or the degree of the homogeneous + component to which ``self`` should be reduced - OUTPUT: - - The new reduced space. + OUTPUT: the new reduced space EXAMPLES:: @@ -645,7 +641,7 @@ def rat_field(self): def get_d(self, fix_d=False, d_num_prec=None): r""" - Return the parameter ``d`` of self either as a formal + Return the parameter ``d`` of ``self`` either as a formal parameter or as a numerical approximation with the specified precision (resp. an exact value in the arithmetic cases). @@ -654,18 +650,14 @@ def get_d(self, fix_d=False, d_num_prec=None): INPUT: - - ``fix_d`` -- If ``False`` (default) a formal parameter is - used for ``d``. - - If ``True`` then the numerical value of - ``d`` is used (or an exact value if the - group is arithmetic). Otherwise, the given - value is used for ``d``. + - ``fix_d`` -- if ``False`` (default) a formal parameter is + used for ``d``. If ``True`` then the numerical value of ``d`` is used + (or an exact value if the group is arithmetic). Otherwise, the given + value is used for ``d``. - - ``d_num_prec`` -- An integer. The numerical precision of - ``d``. Default: ``None``, in which case - the default numerical precision of - ``self.parent()`` is used. + - ``d_num_prec`` -- integer (default: ``None``); the numerical + precision of ``d``. By default, the default numerical precision of + ``self.parent()`` is used. OUTPUT: @@ -717,18 +709,18 @@ def get_q(self, prec=None, fix_d=False, d_num_prec=None): INPUT: - - ``prec`` -- An integer or ``None`` (default), namely the desired default - precision of the space of power series. If nothing is specified - the default precision of ``self`` is used. + - ``prec`` -- an integer or ``None`` (default), namely the desired + default precision of the space of power series. If nothing is + specified the default precision of ``self`` is used. - - ``fix_d`` -- If ``False`` (default) a formal parameter is used for ``d``. - If ``True`` then the numerical value of ``d`` is used - (resp. an exact value if the group is arithmetic). - Otherwise the given value is used for ``d``. + - ``fix_d`` -- if ``False`` (default) a formal parameter is used for + ``d``. If ``True`` then the numerical value of ``d`` is used (resp. + an exact value if the group is arithmetic). Otherwise the given value + is used for ``d``. - - ``d_num_prec`` -- The precision to be used if a numerical value for ``d`` is substituted. - Default: ``None`` in which case the default - numerical precision of ``self.parent()`` is used. + - ``d_num_prec`` -- the precision to be used if a numerical value for + ``d`` is substituted (default: ``None``), otherwise the default + numerical precision of ``self.parent()`` is used OUTPUT: @@ -1019,9 +1011,9 @@ def homogeneous_part(self, k, ep): INPUT: - - ``k`` -- An integer. + - ``k`` -- integer - - ``ep`` -- `+1` or `-1`. + - ``ep`` -- `+1` or `-1` EXAMPLES:: @@ -1726,7 +1718,6 @@ def E2(self): It is in particular also a generator of the graded ring of ``self`` and the polynomial variable ``z`` exactly corresponds to ``E2``. - EXAMPLES:: sage: from sage.modular.modform_hecketriangle.graded_ring import QuasiMeromorphicModularFormsRing, QuasiModularFormsRing, CuspFormsRing @@ -1790,11 +1781,10 @@ def EisensteinSeries(self, k=None): INPUT: - - ``k`` -- A non-negative even integer, namely the weight. - - If ``k=None`` (default) then the weight of ``self`` - is chosen if ``self`` is homogeneous and the - weight is possible, otherwise ``k=0`` is set. + - ``k`` -- a nonnegative even integer, namely the weight. + If ``k`` is ``None`` (default) then the weight of ``self`` is chosen if + ``self`` is homogeneous and the weight is possible, otherwise ``k`` + is set to `0`. OUTPUT: @@ -1893,7 +1883,7 @@ def EisensteinSeries(self, k=None): raise TypeError(None) k = 2*ZZ(k/2) except TypeError: - raise TypeError("k={} must be a non-negative even integer!".format(k)) + raise TypeError("k={} must be a nonnegative even integer!".format(k)) # The case n=infinity is special (there are 2 cusps) # Until we/I get confirmation what is what sort of Eisenstein series diff --git a/src/sage/modular/modform_hecketriangle/abstract_space.py b/src/sage/modular/modform_hecketriangle/abstract_space.py index c60e2b0c4f7..79a3fb10a04 100644 --- a/src/sage/modular/modform_hecketriangle/abstract_space.py +++ b/src/sage/modular/modform_hecketriangle/abstract_space.py @@ -23,7 +23,7 @@ from sage.rings.integer import Integer from sage.rings.integer_ring import ZZ from sage.rings.laurent_series_ring import is_LaurentSeriesRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.power_series_ring import is_PowerSeriesRing from sage.rings.rational_field import QQ from sage.structure.element import parent @@ -51,19 +51,16 @@ def __init__(self, group, base_ring, k, ep, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``k`` -- The weight (default: `0`) + - ``k`` -- the weight (default: `0`) - - ``ep`` -- The epsilon (default: ``None``). - If ``None``, then k*(n-2) has to be divisible by `2` and - ``ep=(-1)^(k*(n-2)/2)`` is used. + - ``ep`` -- the epsilon (default: ``None``); if ``None``, then `k(n-2)` + has to be divisible by `2` and ``ep=(-1)^(k*(n-2)/2)`` is used - - ``base_ring`` -- The base_ring (default: `\Z`). + - ``base_ring`` -- the base_ring (default: `\Z`) - OUTPUT: - - The corresponding abstract (Hecke) forms space. + OUTPUT: the corresponding abstract (Hecke) forms space EXAMPLES:: @@ -380,7 +377,7 @@ def is_ambient(self): def ambient_space(self): r""" - Return the ambient space of self. + Return the ambient space of ``self``. EXAMPLES:: @@ -401,7 +398,7 @@ def ambient_space(self): def module(self): r""" - Return the module associated to self. + Return the module associated to ``self``. EXAMPLES:: @@ -420,7 +417,7 @@ def module(self): def ambient_module(self): r""" - Return the module associated to the ambient space of self. + Return the module associated to the ambient space of ``self``. EXAMPLES:: @@ -544,11 +541,9 @@ def element_from_coordinates(self, vec): INPUT: - - ``vec`` -- A coordinate vector with respect to ``self.gens()``. - - OUTPUT: + - ``vec`` -- a coordinate vector with respect to ``self.gens()`` - An element of ``self`` corresponding to the coordinate vector ``vec``. + OUTPUT: an element of ``self`` corresponding to the coordinate vector ``vec`` EXAMPLES:: @@ -588,11 +583,9 @@ def element_from_ambient_coordinates(self, vec): INPUT: - - ``vec`` -- An element of ``self.module()`` or ``self.ambient_module()``. - - OUTPUT: + - ``vec`` -- an element of ``self.module()`` or ``self.ambient_module()`` - An element of ``self`` corresponding to ``vec``. + OUTPUT: an element of ``self`` corresponding to ``vec`` EXAMPLES:: @@ -619,7 +612,7 @@ def element_from_ambient_coordinates(self, vec): def homogeneous_part(self, k, ep): r""" Since ``self`` already is a homogeneous component return ``self`` - unless the degree differs in which case a :class:`ValueError` is raised. + unless the degree differs in which case a :exc:`ValueError` is raised. EXAMPLES:: @@ -714,9 +707,9 @@ def aut_factor(self, gamma, t): INPUT: - - ``gamma`` -- An element of the group of ``self``. + - ``gamma`` -- an element of the group of ``self`` - - ``t`` -- An element of the upper half plane. + - ``t`` -- an element of the upper half plane EXAMPLES:: @@ -781,9 +774,9 @@ def F_simple(self, order_1=ZZ.zero()): INPUT: - - ``order_1`` -- An integer (default: 0) denoting the desired order at - ``-1`` in the case ``n = infinity``. - If ``n != infinity`` the parameter is ignored. + - ``order_1`` -- an integer (default: 0) denoting the desired order at + ``-1`` in the case ``n = infinity``. If ``n != infinity`` the + parameter is ignored. EXAMPLES:: @@ -838,7 +831,7 @@ def F_simple(self, order_1=ZZ.zero()): def Faber_pol(self, m, order_1=ZZ.zero(), fix_d=False, d_num_prec=None): r""" - Return the ``m``'th Faber polynomial of ``self``. + Return the ``m``-th Faber polynomial of ``self``. Namely a polynomial ``P(q)`` such that ``P(J_inv)*F_simple(order_1)`` has a Fourier expansion of the form ``q^m + O(q^(order_inf + 1))``. @@ -853,23 +846,21 @@ def Faber_pol(self, m, order_1=ZZ.zero(), fix_d=False, d_num_prec=None): INPUT: - - ``m`` -- An integer ``m <= order_inf = self._l1 - order_1``. + - ``m`` -- an integer ``m <= order_inf = self._l1 - order_1`` - - ``order_1`` -- The order at ``-1`` of F_simple (default: 0). - This parameter is ignored if ``n != infinity``. + - ``order_1`` -- the order at ``-1`` of F_simple (default: 0); + this parameter is ignored if ``n != infinity`` - - ``fix_d`` -- If ``False`` (default) a formal parameter is used for ``d``. - If ``True`` then the numerical value of ``d`` is used - (resp. an exact value if the group is arithmetic). - Otherwise the given value is used for ``d``. + - ``fix_d`` -- if ``False`` (default) a formal parameter is used for + ``d``. If ``True`` then the numerical value of ``d`` is used (resp. + an exact value if the group is arithmetic). Otherwise the given + value is used for ``d``. - - ``d_num_prec`` -- The precision to be used if a numerical value for ``d`` is substituted. - Default: ``None`` in which case the default - numerical precision of ``self.parent()`` is used. + - ``d_num_prec`` -- the precision to be used if a numerical value for + ``d`` is substituted (default: ``None``), otherwise the default + numerical precision of ``self.parent()`` is used - OUTPUT: - - The corresponding Faber polynomial ``P(q)``. + OUTPUT: the corresponding Faber polynomial ``P(q)`` EXAMPLES:: @@ -990,7 +981,7 @@ def faber_pol(self, m, order_1=ZZ.zero(), fix_d=False, d_num_prec=None): r""" If ``n=infinity`` a non-trivial order of ``-1`` can be specified through the parameter ``order_1`` (default: 0). Otherwise it is ignored. - Return the `m`'th Faber polynomial of ``self`` + Return the `m`-th Faber polynomial of ``self`` with a different normalization based on ``j_inv`` instead of ``J_inv``. @@ -1006,23 +997,21 @@ def faber_pol(self, m, order_1=ZZ.zero(), fix_d=False, d_num_prec=None): INPUT: - - ``m`` -- An integer ``m <= self._l1 - order_1``. - - - ``order_1`` -- The order at ``-1`` of ``F_simple`` (default: 0). - This parameter is ignored if ``n != infinity``. + - ``m`` -- integer; ``m <= self._l1 - order_1`` - - ``fix_d`` -- If ``False`` (default) a formal parameter is used for ``d``. - If ``True`` then the numerical value of ``d`` is used - (resp. an exact value if the group is arithmetic). - Otherwise the given value is used for ``d``. + - ``order_1`` -- the order at ``-1`` of ``F_simple`` (default: 0); + this parameter is ignored if ``n != infinity`` - - ``d_num_prec`` -- The precision to be used if a numerical value for ``d`` is substituted. - Default: ``None`` in which case the default - numerical precision of ``self.parent()`` is used. + - ``fix_d`` -- if ``False`` (default) a formal parameter is used for + ``d``. If ``True`` then the numerical value of ``d`` is used (resp. + an exact value if the group is arithmetic). Otherwise the given value + is used for ``d``. - OUTPUT: + - ``d_num_prec`` -- the precision to be used if a numerical value for + ``d`` is substituted (default: ``None``), otherwise the default + numerical precision of ``self.parent()`` is used - The corresponding Faber polynomial ``p(q)``. + OUTPUT: the corresponding Faber polynomial ``p(q)`` EXAMPLES:: @@ -1129,7 +1118,7 @@ def faber_pol(self, m, order_1=ZZ.zero(), fix_d=False, d_num_prec=None): def F_basis_pol(self, m, order_1=ZZ.zero()): r""" - Returns a polynomial corresponding to the basis element of + Return a polynomial corresponding to the basis element of the corresponding space of weakly holomorphic forms of the same degree as ``self``. The basis element is determined by the property that the Fourier expansion is of the form @@ -1140,10 +1129,10 @@ def F_basis_pol(self, m, order_1=ZZ.zero()): INPUT: - - ``m`` -- An integer ``m <= self._l1``. + - ``m`` -- integer; ``m <= self._l1`` - - ``order_1`` -- The order at ``-1`` of ``F_simple`` (default: 0). - This parameter is ignored if ``n != infinity``. + - ``order_1`` -- the order at ``-1`` of ``F_simple`` (default: 0); + this parameter is ignored if ``n != infinity`` OUTPUT: @@ -1231,7 +1220,7 @@ def F_basis_pol(self, m, order_1=ZZ.zero()): def F_basis(self, m, order_1=ZZ.zero()): r""" - Returns a weakly holomorphic element of ``self`` + Return a weakly holomorphic element of ``self`` (extended if necessarily) determined by the property that the Fourier expansion is of the form is of the form ``q^m + O(q^(order_inf + 1))``, where ``order_inf = self._l1 - order_1``. @@ -1245,10 +1234,10 @@ def F_basis(self, m, order_1=ZZ.zero()): INPUT: - - ``m`` -- An integer ``m <= self._l1``. + - ``m`` -- integer; ``m <= self._l1`` - - ``order_1`` -- The order at ``-1`` of ``F_simple`` (default: 0). - This parameter is ignored if ``n != infinity``. + - ``order_1`` -- the order at ``-1`` of ``F_simple`` (default: 0); + this parameter is ignored if ``n != infinity`` OUTPUT: @@ -1369,25 +1358,20 @@ def quasi_part_gens(self, r=None, min_exp=0, max_exp=infinity, order_1=ZZ.zero() INPUT: - - ``r`` -- An integer or ``None`` (default), indicating - the desired power of ``E2`` If ``r=None`` - then all possible powers (``r``) are - chosen. + - ``r`` -- an integer or ``None`` (default), indicating the desired + power of ``E2``; if ``r`` is ``None`` then all possible powers + (``r``) are chosen - - ``min_exp`` -- An integer giving a lower bound for the - first non-trivial Fourier coefficient of the - generators (default: 0). + - ``min_exp`` -- integer (default: 0); a lower bound for the first + non-trivial Fourier coefficient of the generators - - ``max_exp`` -- An integer or ``infinity`` (default) giving - an upper bound for the first non-trivial - Fourier coefficient of the generators. If - ``max_exp==infinity`` then no upper bound is - assumed. + - ``max_exp`` -- integer or ``infinity`` (default) giving an upper + bound for the first non-trivial Fourier coefficient of the + generators. If ``max_exp==infinity`` then no upper bound is assumed. - - ``order_1`` -- A lower bound for the order at ``-1`` of all - quasi parts of the basis elements (default: - 0). If ``n!=infinity`` this parameter is - ignored. + - ``order_1`` -- a lower bound for the order at ``-1`` of all quasi + parts of the basis elements (default: 0). If ``n!=infinity`` this + parameter is ignored. OUTPUT: @@ -1633,7 +1617,7 @@ def quasi_part_dimension(self, r=None, min_exp=0, max_exp=infinity, order_1=ZZ.z def construct_form(self, laurent_series, order_1=ZZ.zero(), check=True, rationalize=False): r""" - Tries to construct an element of self with the given Fourier + Try to construct an element of ``self`` with the given Fourier expansion. The assumption is made that the specified Fourier expansion corresponds to a weakly holomorphic modular form. @@ -1642,21 +1626,21 @@ def construct_form(self, laurent_series, order_1=ZZ.zero(), check=True, rational INPUT: - - ``laurent_series`` -- A Laurent or Power series. + - ``laurent_series`` -- a Laurent or Power series - - ``order_1`` -- A lower bound for the order at ``-1`` of the form (default: 0). - If ``n!=infinity`` this parameter is ignored. + - ``order_1`` -- a lower bound for the order at ``-1`` of the form + (default: 0). If ``n!=infinity`` this parameter is ignored. - - ``check`` -- If ``True`` (default) then the series expansion of the constructed - form is compared against the given series. + - ``check`` -- if ``True`` (default) then the series expansion of the + constructed form is compared against the given series - - ``rationalize`` -- If ``True`` (default: ``False``) then the series is - `rationalized` beforehand. Note that in non-exact or non-arithmetic - cases this is experimental and extremely unreliable! + - ``rationalize`` -- if ``True`` (default: ``False``) then the series + is "rationalized" beforehand. Note that in non-exact or + non-arithmetic cases this is experimental and extremely unreliable! OUTPUT: - If possible: An element of self with the same initial + If possible: An element of ``self`` with the same initial Fourier expansion as ``laurent_series``. Note: For modular spaces it is also possible to call @@ -1721,7 +1705,7 @@ def construct_form(self, laurent_series, order_1=ZZ.zero(), check=True, rational """ base_ring = laurent_series.base_ring() - if is_PolynomialRing(base_ring.base()): + if isinstance(base_ring.base(), PolynomialRing_general): if not (self.coeff_ring().has_coerce_map_from(base_ring)): raise ValueError("The Laurent coefficients don't coerce into the coefficient ring of self!") elif rationalize: @@ -1767,19 +1751,18 @@ def _quasi_form_matrix(self, min_exp=0, order_1=ZZ.zero(), incr_prec_by=0): INPUT: - - ``min_exp`` -- An integer (default: 0), namely the lower bound for the - order at infinity resp. the exponent of the Laurent series. - - - ``order_1`` -- A lower bound for the order at ``-1`` of all quasi parts of the - subspace (default: 0). If ``n!=infinity`` this parameter is ignored. + - ``min_exp`` -- integer (default: 0), namely the lower bound for the + order at infinity resp. the exponent of the Laurent series - - ``incr_prec_by`` -- An integer (default: 0) which specifies how - much the precision should be increased compared to - the size of the corresponding basis. + - ``order_1`` -- a lower bound for the order at ``-1`` of all quasi + parts of the subspace (default: 0). If ``n!=infinity`` this parameter + is ignored. - OUTPUT: + - ``incr_prec_by`` -- integer (default: 0) which specifies how much the + precision should be increased compared to the size of the + corresponding basis - The corresponding base change matrix. + OUTPUT: the corresponding base change matrix EXAMPLES:: @@ -1875,15 +1858,15 @@ def required_laurent_prec(self, min_exp=0, order_1=ZZ.zero()): .. NOTE:: For ``n=infinity`` only the holomorphic case (``min_exp >= 0``) - is supported (in particular a non-negative order at ``-1`` is assumed). + is supported (in particular a nonnegative order at ``-1`` is assumed). INPUT: - - ``min_exp`` -- An integer (default: 0), namely the lower bound for the - order at infinity resp. the exponent of the Laurent series. + - ``min_exp`` -- integer (default: 0); namely the lower bound for the + order at infinity resp. the exponent of the Laurent series - - ``order_1`` -- A lower bound for the order at ``-1`` for all quasi parts - (default: 0). If ``n!=infinity`` this parameter is ignored. + - ``order_1`` -- a lower bound for the order at ``-1`` for all quasi + parts (default: 0). If ``n!=infinity`` this parameter is ignored. OUTPUT: @@ -1915,7 +1898,7 @@ def required_laurent_prec(self, min_exp=0, order_1=ZZ.zero()): def construct_quasi_form(self, laurent_series, order_1=ZZ.zero(), check=True, rationalize=False): r""" - Try to construct an element of self with the given Fourier + Try to construct an element of ``self`` with the given Fourier expansion. The assumption is made that the specified Fourier expansion corresponds to a weakly holomorphic quasi modular form. @@ -1924,21 +1907,22 @@ def construct_quasi_form(self, laurent_series, order_1=ZZ.zero(), check=True, ra INPUT: - - ``laurent_series`` -- A Laurent or Power series. + - ``laurent_series`` -- a Laurent or Power series - - ``order_1`` -- A lower bound for the order at ``-1`` for all quasi parts of the - form (default: 0). If ``n!=infinity`` this parameter is ignored. + - ``order_1`` -- a lower bound for the order at ``-1`` for all quasi + parts of the form (default: 0). If ``n!=infinity`` this parameter is + ignored. - - ``check`` -- If ``True`` (default) then the series expansion of the constructed - form is compared against the given (rationalized) series. + - ``check`` -- if ``True`` (default) then the series expansion of the + constructed form is compared against the given (rationalized) series. - - ``rationalize`` -- If ``True`` (default: ``False``) then the series is - `rationalized` beforehand. Note that in non-exact or non-arithmetic - cases this is experimental and extremely unreliable! + - ``rationalize`` -- if ``True`` (default: ``False``) then the series + is "rationalized" beforehand. Note that in non-exact or + non-arithmetic cases this is experimental and extremely unreliable! OUTPUT: - If possible: An element of self with the same initial + If possible: An element of ``self`` with the same initial Fourier expansion as ``laurent_series``. Note: For non modular spaces it is also possible to call @@ -2015,7 +1999,7 @@ def construct_quasi_form(self, laurent_series, order_1=ZZ.zero(), check=True, ra """ base_ring = laurent_series.base_ring() - if is_PolynomialRing(base_ring.base()): + if isinstance(base_ring.base(), PolynomialRing_general): if not (self.coeff_ring().has_coerce_map_from(base_ring)): raise ValueError("The Laurent coefficients don't coerce into the coefficient ring of self!") elif rationalize: @@ -2081,14 +2065,17 @@ def q_basis(self, m=None, min_exp=0, order_1=ZZ.zero()): INPUT: - - ``m`` -- An integer, indicating the desired initial Laurent exponent of the element. - If ``m==None`` (default) then the whole basis is returned. + - ``m`` -- integer, indicating the desired initial Laurent exponent + of the element. If ``m==None`` (default) then the whole basis is + returned. - - ``min_exp`` -- An integer, indicating the minimal Laurent exponent (for each quasi part) - of the subspace of ``self`` which should be considered (default: 0). + - ``min_exp`` -- integer (default: 0); the minimal Laurent exponent + (for each quasi part) of the subspace of ``self`` which should be + considered - - ``order_1`` -- A lower bound for the order at ``-1`` of all quasi parts of the subspace - (default: 0). If ``n!=infinity`` this parameter is ignored. + - ``order_1`` -- a lower bound for the order at ``-1`` of all quasi + parts of the subspace (default: 0). If ``n!=infinity`` this parameter + is ignored. OUTPUT: @@ -2190,35 +2177,33 @@ def rationalize_series(self, laurent_series, coeff_bound=1e-10, denom_factor=ZZ( INPUT: - - ``laurent_series`` -- A Laurent series. If the Laurent coefficients already - coerce into ``self.coeff_ring()`` with a formal parameter - then the Laurent series is returned as is. + - ``laurent_series`` -- a Laurent series. If the Laurent coefficients + already coerce into ``self.coeff_ring()`` with a formal parameter + then the Laurent series is returned as is. - Otherwise it is assumed that the series is normalized - in the sense that the first non-trivial coefficient - is a power of ``d`` (e.g. ``1``). + Otherwise it is assumed that the series is normalized in the sense + that the first non-trivial coefficient is a power of ``d`` (e.g. + ``1``). - - ``coeff_bound`` -- Either ``None`` resp. ``0`` or a positive real number - (default: ``1e-10``). If specified ``coeff_bound`` - gives a lower bound for the size of the initial Laurent - coefficients. If a coefficient is smaller it is - assumed to be zero. + - ``coeff_bound`` -- either ``None`` resp. ``0`` or a positive real + number (default: ``1e-10``). If specified ``coeff_bound`` gives a + lower bound for the size of the initial Laurent coefficients. If a + coefficient is smaller it is assumed to be zero. - For calculations with very small coefficients (less than - ``1e-10``) ``coeff_bound`` should be set to something - even smaller or just ``0``. + For calculations with very small coefficients (less than ``1e-10``) + ``coeff_bound`` should be set to something even smaller or just ``0``. - Non-exact calculations often produce non-zero - coefficients which are supposed to be zero. In those - cases this parameter helps a lot. + Non-exact calculations often produce nonzero coefficients which are + supposed to be zero. In those cases this parameter helps a lot. - - ``denom_factor`` -- An integer (default: 1) whose factor might occur in - the denominator of the given Laurent coefficients - (in addition to naturally occurring factors). + - ``denom_factor`` -- integer (default: 1) whose factor might occur in + the denominator of the given Laurent coefficients (in addition to + naturally occurring factors). OUTPUT: - A Laurent series over ``self.coeff_ring()`` corresponding to the given Laurent series. + A Laurent series over ``self.coeff_ring()`` corresponding to the given + Laurent series. EXAMPLES:: @@ -2282,7 +2267,7 @@ def rationalize_series(self, laurent_series, coeff_bound=1e-10, denom_factor=ZZ( # If the coefficients already coerce to our coefficient ring # and are in polynomial form we simply return the Laurent series - if (is_PolynomialRing(base_ring.base())): + if (isinstance(base_ring.base(), PolynomialRing_general)): if (self.coeff_ring().has_coerce_map_from(base_ring)): return laurent_series else: @@ -2448,7 +2433,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` EXAMPLES:: @@ -2481,7 +2466,7 @@ def ambient_coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` EXAMPLES:: @@ -2524,7 +2509,7 @@ def gens(self): def gen(self, k=0): r""" - Return the ``k``'th basis element of ``self`` + Return the ``k``-th basis element of ``self`` if possible (default: ``k=0``). EXAMPLES:: diff --git a/src/sage/modular/modform_hecketriangle/analytic_type.py b/src/sage/modular/modform_hecketriangle/analytic_type.py index d04d42c91f1..32a2123d974 100644 --- a/src/sage/modular/modform_hecketriangle/analytic_type.py +++ b/src/sage/modular/modform_hecketriangle/analytic_type.py @@ -205,12 +205,10 @@ def reduce_to(self, reduce_type): INPUT: - - ``reduce_type`` -- an analytic type or something which is + - ``reduce_type`` -- an analytic type or something which is convertible to an analytic type - OUTPUT: - - The new reduced analytic type. + OUTPUT: the new reduced analytic type EXAMPLES:: @@ -235,12 +233,10 @@ def extend_by(self, extend_type): INPUT: - - ``extend_type`` -- an analytic type or something which is + - ``extend_type`` -- an analytic type or something which is convertible to an analytic type - OUTPUT: - - The new extended analytic type. + OUTPUT: the new extended analytic type EXAMPLES:: @@ -293,16 +289,16 @@ class AnalyticType(FiniteLatticePoset): The basic ``analytic properties`` are: - - ``quasi`` -- Whether the element is quasi modular (and not modular) - or modular. - - ``mero`` -- ``meromorphic``: If the element is meromorphic - and meromorphic at infinity. - - ``weak`` -- ``weakly holomorphic``: If the element is holomorphic - and meromorphic at infinity. - - ``holo`` -- ``holomorphic``: If the element is holomorphic and - holomorphic at infinity. - - ``cusp`` -- ``cuspidal``: If the element additionally has a positive - order at infinity. + - ``quasi`` -- whether the element is quasi modular (and not modular) + or modular. + - ``mero`` -- ``meromorphic`` -- if the element is meromorphic + and meromorphic at infinity + - ``weak`` -- ``weakly holomorphic`` -- if the element is holomorphic + and meromorphic at infinity + - ``holo`` -- ``holomorphic`` -- if the element is holomorphic and + holomorphic at infinity + - ``cusp`` -- ``cuspidal`` -- if the element additionally has a positive + order at infinity The ``zero`` elements/property have no analytic properties (or only ``quasi``). @@ -494,12 +490,9 @@ def _element_constructor_(self, element): INPUT: - - ``element`` -- Either something which coerces in the - ``FiniteLatticePoset`` of ``self`` or - a string or a list of strings of basic - properties that should be contained in - the new element. - + - ``element`` -- either something which coerces in the + ``FiniteLatticePoset`` of ``self`` or a string or a list of strings + of basic properties that should be contained in the new element OUTPUT: diff --git a/src/sage/modular/modform_hecketriangle/constructor.py b/src/sage/modular/modform_hecketriangle/constructor.py index 0f40b4e4a35..e245e1d2394 100644 --- a/src/sage/modular/modform_hecketriangle/constructor.py +++ b/src/sage/modular/modform_hecketriangle/constructor.py @@ -42,30 +42,30 @@ def rational_type(f, n=ZZ(3), base_ring=ZZ): INPUT: - - ``f`` -- A rational function in ``x,y,z,d`` over ``base_ring``. + - ``f`` -- a rational function in ``x,y,z,d`` over ``base_ring`` - - ``n`` -- An integer greater or equal to `3` corresponding - to the ``HeckeTriangleGroup`` with that parameter (default: `3`). + - ``n`` -- integer greater or equal to `3` corresponding + to the ``HeckeTriangleGroup`` with that parameter (default: `3`) - - ``base_ring`` -- The base ring of the corresponding forms ring, resp. - polynomial ring (default: ``ZZ``). + - ``base_ring`` -- the base ring of the corresponding forms ring, resp. + polynomial ring (default: ``ZZ``) OUTPUT: A tuple ``(elem, homo, k, ep, analytic_type)`` describing the basic analytic properties of `f` (with the interpretation indicated above). - - ``elem`` -- ``True`` if `f` has a homogeneous denominator. + - ``elem`` -- ``True`` if `f` has a homogeneous denominator - - ``homo`` -- ``True`` if `f` also has a homogeneous numerator. + - ``homo`` -- ``True`` if `f` also has a homogeneous numerator - ``k`` -- ``None`` if `f` is not homogeneous, otherwise - the weight of `f` (which is the first component of its degree). + the weight of `f` (which is the first component of its degree) - ``ep`` -- ``None`` if `f` is not homogeneous, otherwise the multiplier of `f` (which is the second component of its degree) - - ``analytic_type`` -- The :class:`AnalyticType` of `f`. + - ``analytic_type`` -- the :class:`AnalyticType` of `f` For the zero function the degree `(0, 1)` is chosen. @@ -208,16 +208,16 @@ def FormsSpace(analytic_type, group=3, base_ring=ZZ, k=QQ(0), ep=None): INPUT: - - ``analytic_type`` -- An element of ``AnalyticType()`` describing - the analytic type of the space. + - ``analytic_type`` -- an element of ``AnalyticType()`` describing + the analytic type of the space - - ``group`` -- The index of the (Hecke triangle) group of the space (default: `3`). + - ``group`` -- the index of the (Hecke triangle) group of the space (default: `3`) - - ``base_ring`` -- The base ring of the space (default: ``ZZ``). + - ``base_ring`` -- the base ring of the space (default: ``ZZ``) - - ``k`` -- The weight of the space, a rational number (default: ``0``). + - ``k`` -- the weight of the space, a rational number (default: ``0``) - - ``ep`` -- The multiplier of the space, `1`, `-1` or ``None`` + - ``ep`` -- the multiplier of the space, `1`, `-1` or ``None`` (in which case ``ep`` should be determined from ``k``). Default: ``None``. For the variables ``group``, ``base_ring``, ``k``, ``ep`` @@ -226,9 +226,7 @@ def FormsSpace(analytic_type, group=3, base_ring=ZZ, k=QQ(0), ep=None): In particular the multiplier ``ep`` is calculated as usual from ``k`` if ``ep == None``. - OUTPUT: - - The FormsSpace with the given properties. + OUTPUT: the FormsSpace with the given properties EXAMPLES:: @@ -322,24 +320,22 @@ def FormsRing(analytic_type, group=3, base_ring=ZZ, red_hom=False): INPUT: - - ``analytic_type`` -- An element of ``AnalyticType()`` describing - the analytic type of the space. + - ``analytic_type`` -- an element of ``AnalyticType()`` describing + the analytic type of the space - - ``group`` -- The index of the (Hecke triangle) group of the space - (default: 3`). + - ``group`` -- the index of the (Hecke triangle) group of the space + (default: 3`) - - ``base_ring`` -- The base ring of the space (default: ``ZZ``). + - ``base_ring`` -- the base ring of the space (default: ``ZZ``) - - ``red_hom`` -- The (boolean) variable ``red_hom`` of the space - (default: ``False``). + - ``red_hom`` -- the (boolean) variable ``red_hom`` of the space + (default: ``False``) For the variables ``group``, ``base_ring``, ``red_hom`` the same arguments as for the class :class:`FormsRing_abstract` can be used. The variables will then be put in canonical form. - OUTPUT: - - The FormsRing with the given properties. + OUTPUT: the FormsRing with the given properties EXAMPLES:: diff --git a/src/sage/modular/modform_hecketriangle/element.py b/src/sage/modular/modform_hecketriangle/element.py index 308d3c6a7c0..8d8575537e3 100644 --- a/src/sage/modular/modform_hecketriangle/element.py +++ b/src/sage/modular/modform_hecketriangle/element.py @@ -182,24 +182,24 @@ def ambient_coordinate_vector(self): def lseries(self, num_prec=None, max_imaginary_part=0, max_asymp_coeffs=40): r""" - Return the L-series of ``self`` if ``self`` is modular and holomorphic. + Return the `L`-series of ``self`` if ``self`` is modular and holomorphic. This relies on the (pari) based function ``Dokchitser``. INPUT: - - ``num_prec`` -- An integer denoting the to-be-used numerical precision. + - ``num_prec`` -- integer denoting the to-be-used numerical precision. If integer ``num_prec=None`` (default) the default numerical precision of the parent of ``self`` is used. - - ``max_imaginary_part`` -- A real number (default: 0), indicating up to which - imaginary part the L-series is going to be studied. + - ``max_imaginary_part`` -- a real number (default: 0), indicating up + to which imaginary part the `L`-series is going to be studied - - ``max_asymp_coeffs`` -- An integer (default: 40). + - ``max_asymp_coeffs`` -- integer (default: 40) OUTPUT: - An interface to Tim Dokchitser's program for computing L-series, namely + An interface to Tim Dokchitser's program for computing `L`-series, namely the series given by the Fourier coefficients of ``self``. EXAMPLES:: diff --git a/src/sage/modular/modform_hecketriangle/functors.py b/src/sage/modular/modform_hecketriangle/functors.py index b0fdfcf5ac7..b50d618c3c4 100644 --- a/src/sage/modular/modform_hecketriangle/functors.py +++ b/src/sage/modular/modform_hecketriangle/functors.py @@ -33,7 +33,7 @@ from .subspace import SubSpaceForms -def _get_base_ring(ring, var_name="d"): +def _get_base_ring(ring, var_name='d'): r""" Return the base ring of the given ``ring``: @@ -56,7 +56,7 @@ def _get_base_ring(ring, var_name="d"): whose construction should be based on the returned base ring (and not on ``ring``!). - If ``var_name`` (default: "d") is specified then this variable + If ``var_name`` (default: ``'d'``) is specified then this variable name is used for the polynomial ring. EXAMPLES:: @@ -79,7 +79,7 @@ def _get_base_ring(ring, var_name="d"): """ # from sage.rings.fraction_field import FractionField_generic - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.categories.pushout import FractionField as FractionFieldFunctor base_ring = ring @@ -87,7 +87,7 @@ def _get_base_ring(ring, var_name="d"): # base_ring = base_ring.base() if (base_ring.construction() and base_ring.construction()[0] == FractionFieldFunctor()): base_ring = base_ring.construction()[1] - if (is_PolynomialRing(base_ring) and base_ring.ngens() == 1 and base_ring.variable_name() == var_name): + if (isinstance(base_ring, PolynomialRing_general) and base_ring.ngens() == 1 and base_ring.variable_name() == var_name): base_ring = base_ring.base() if (base_ring.construction() and base_ring.construction()[0] == FractionFieldFunctor()): base_ring = base_ring.construction()[1] @@ -164,14 +164,12 @@ def __init__(self, ambient_space_functor, generators): INPUT: - - ``ambient_space_functor`` -- A FormsSpaceFunctor + - ``ambient_space_functor`` -- a FormsSpaceFunctor - - ``generators`` -- A list of elements of some ambient space - over some base ring. + - ``generators`` -- a list of elements of some ambient space + over some base ring - OUTPUT: - - The construction functor for the corresponding forms sub space. + OUTPUT: the construction functor for the corresponding forms sub space EXAMPLES:: @@ -268,7 +266,6 @@ def merge(self, other): If ``other`` is not a ``FormsSubSpaceFunctor`` then ``self`` is merged as if it was its ambient space functor. - EXAMPLES:: sage: from sage.modular.modform_hecketriangle.functors import (FormsSpaceFunctor, FormsSubSpaceFunctor) @@ -359,17 +356,15 @@ def __init__(self, analytic_type, group, k, ep): INPUT: - - ``analytic_type`` -- An element of ``AnalyticType()``. - - - ``group`` -- The index of a Hecke Triangle group. + - ``analytic_type`` -- an element of ``AnalyticType()`` - - ``k`` -- A rational number, the weight of the space. + - ``group`` -- the index of a Hecke Triangle group - - ``ep`` -- `1` or `-1`, the multiplier of the space. + - ``k`` -- a rational number, the weight of the space - OUTPUT: + - ``ep`` -- `1` or `-1`, the multiplier of the space - The construction functor for the corresponding forms space/ring. + OUTPUT: the construction functor for the corresponding forms space/ring EXAMPLES:: @@ -454,7 +449,6 @@ def merge(self, other): Two ``FormsRingFunctors`` are merged to the corresponding (extended) ``FormsRingFunctor``. - EXAMPLES:: sage: from sage.modular.modform_hecketriangle.functors import (FormsSpaceFunctor, FormsRingFunctor) @@ -545,16 +539,14 @@ def __init__(self, analytic_type, group, red_hom): INPUT: - - ``analytic_type`` -- An element of ``AnalyticType()``. - - - ``group`` -- The index of a Hecke Triangle group. + - ``analytic_type`` -- an element of ``AnalyticType()`` - - ``red_hom`` -- A boolean variable for the parameter ``red_hom`` - (also see ``FormsRing_abstract``). + - ``group`` -- the index of a Hecke Triangle group - OUTPUT: + - ``red_hom`` -- a boolean variable for the parameter ``red_hom`` + (also see ``FormsRing_abstract``) - The construction functor for the corresponding forms ring. + OUTPUT: the construction functor for the corresponding forms ring EXAMPLES:: @@ -644,7 +636,6 @@ def merge(self, other): Two ``FormsRingFunctors`` are merged to the corresponding (extended) ``FormsRingFunctor``. - EXAMPLES:: sage: from sage.modular.modform_hecketriangle.functors import (FormsSpaceFunctor, FormsRingFunctor) diff --git a/src/sage/modular/modform_hecketriangle/graded_ring.py b/src/sage/modular/modform_hecketriangle/graded_ring.py index 87251973e18..1cb832bbef3 100644 --- a/src/sage/modular/modform_hecketriangle/graded_ring.py +++ b/src/sage/modular/modform_hecketriangle/graded_ring.py @@ -83,13 +83,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -146,13 +146,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -206,13 +206,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -266,13 +266,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -326,13 +326,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -386,13 +386,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -445,13 +445,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: @@ -505,13 +505,13 @@ def __init__(self, group, base_ring, red_hom, n): INPUT: - - ``group`` -- The Hecke triangle group (default: ``HeckeTriangleGroup(3)``) + - ``group`` -- the Hecke triangle group (default: ``HeckeTriangleGroup(3)``) - - ``base_ring`` -- The base_ring (default: ``ZZ``). + - ``base_ring`` -- the base_ring (default: ``ZZ``) - - ``red_hom`` -- If True then results of binary operations are considered - homogeneous whenever it makes sense (default: ``False``). - This is mainly used by the spaces of homogeneous elements. + - ``red_hom`` -- if ``True`` then results of binary operations are + considered homogeneous whenever it makes sense (default: ``False``). + This is mainly used by the spaces of homogeneous elements. OUTPUT: diff --git a/src/sage/modular/modform_hecketriangle/graded_ring_element.py b/src/sage/modular/modform_hecketriangle/graded_ring_element.py index f097db5e44e..b1510c662a6 100644 --- a/src/sage/modular/modform_hecketriangle/graded_ring_element.py +++ b/src/sage/modular/modform_hecketriangle/graded_ring_element.py @@ -88,11 +88,11 @@ def __init__(self, parent, rat): INPUT: - - ``parent`` -- An (non abstract) instance of ``FormsRing_abstract``. + - ``parent`` -- (non abstract) instance of ``FormsRing_abstract`` - - ``rat`` -- A rational function in ``parent.rat_field()``, the - fraction field of the polynomial ring in ``x,y,z,d`` - over the base ring of ``parent``. + - ``rat`` -- a rational function in ``parent.rat_field()``, the + fraction field of the polynomial ring in ``x,y,z,d`` over the base + ring of ``parent`` OUTPUT: @@ -1014,7 +1014,7 @@ def diff_op(self, op, new_parent=None): INPUT: - - ``op`` -- An element of ``self.parent().diff_alg()``. + - ``op`` -- an element of ``self.parent().diff_alg()``. I.e. an element of the algebra over ``QQ`` of differential operators generated by ``X, Y, Z, dX, dY, DZ``, where e.g. ``X`` @@ -1026,13 +1026,11 @@ def diff_op(self, op, new_parent=None): should be homogeneous operator (with respect to the usual, special grading). - - ``new_parent`` -- Try to convert the result to the specified + - ``new_parent`` -- try to convert the result to the specified ``new_parent``. If ``new_parent == None`` (default) then the parent is extended to a "quasi meromorphic" ring. - OUTPUT: - - The new element. + OUTPUT: the new element EXAMPLES:: @@ -1522,7 +1520,7 @@ def full_reduce(self): @cached_method def _q_expansion_cached(self, prec, fix_d, subs_d, d_num_prec, fix_prec=False): """ - Returns the Fourier expansion of self (cached). + Return the Fourier expansion of ``self`` (cached). Don't call this function, instead use :meth:`q_expansion`. Also see :meth:`q_expansion` for a description of the arguments. @@ -1593,27 +1591,25 @@ def q_expansion(self, prec=None, fix_d=False, d_num_prec=None, fix_prec=False): INPUT: - - ``prec`` -- An integer, the desired output precision O(q^prec). + - ``prec`` -- integer, the desired output precision O(q^prec). Default: ``None`` in which case the default precision of ``self.parent()`` is used. - - ``fix_d`` -- If ``False`` (default) a formal parameter is used for ``d``. - If ``True`` then the numerical value of ``d`` is used + - ``fix_d`` -- if ``False`` (default) a formal parameter is used for + ``d``. If ``True`` then the numerical value of ``d`` is used (resp. an exact value if the group is arithmetic). Otherwise the given value is used for ``d``. - - ``d_num_prec`` -- The precision to be used if a numerical value for ``d`` is substituted. - Default: ``None`` in which case the default - numerical precision of ``self.parent()`` is used. + - ``d_num_prec`` -- the precision to be used if a numerical value for + ``d`` is substituted (default: ``None``), otherwise the default + numerical precision of ``self.parent()`` is used - - ``fix_prec`` -- If ``fix_prec`` is not ``False`` (default) + - ``fix_prec`` -- if ``fix_prec`` is not ``False`` (default) then the precision of the ``MFSeriesConstructor`` is increased such that the output has exactly the specified precision O(q^prec). - OUTPUT: - - The Fourier expansion of ``self`` as a ``FormalPowerSeries`` or ``FormalLaurentSeries``. + OUTPUT: the Fourier expansion of ``self`` as a ``FormalPowerSeries`` or ``FormalLaurentSeries`` EXAMPLES:: @@ -1700,21 +1696,21 @@ def q_expansion_fixed_d(self, prec=None, d_num_prec=None, fix_prec=False): INPUT: - - ``prec`` -- An integer, the desired output precision O(q^prec). - Default: ``None`` in which case the default precision of ``self.parent()`` is used. + - ``prec`` -- integer; the desired output precision O(q^prec). + Default: ``None``, in which case the default precision of + ``self.parent()`` is used. - - ``d_num_prec`` -- The precision to be used if a numerical value for ``d`` is substituted. - Default: ``None`` in which case the default - numerical precision of ``self.parent()`` is used. + - ``d_num_prec`` -- the precision to be used if a numerical value for + ``d`` is substituted (default: ``None``), otherwise the default + numerical precision of ``self.parent()`` is used - - ``fix_prec`` -- If ``fix_prec`` is not ``False`` (default) + - ``fix_prec`` -- if ``fix_prec`` is not ``False`` (default) then the precision of the ``MFSeriesConstructor`` is increased such that the output has exactly the specified precision O(q^prec). - OUTPUT: - - The Fourier expansion of self as a ``FormalPowerSeries`` or ``FormalLaurentSeries``. + OUTPUT: the Fourier expansion of ``self`` as a ``FormalPowerSeries`` or + ``FormalLaurentSeries`` EXAMPLES:: @@ -1759,16 +1755,17 @@ def q_expansion_vector(self, min_exp=None, max_exp=None, prec=None, **kwargs): INPUT: - - ``min_exp`` -- An integer, specifying the first coefficient to be + - ``min_exp`` -- integer specifying the first coefficient to be used for the vector. Default: ``None``, meaning that the first non-trivial coefficient is used. - - ``max_exp`` -- An integer, specifying the last coefficient to be + - ``max_exp`` -- integer specifying the last coefficient to be used for the vector. Default: ``None``, meaning that the default precision + 1 is used. - - ``prec`` -- An integer, specifying the precision of the underlying - Laurent series. Default: ``None``, meaning that ``max_exp + 1`` is used. + - ``prec`` -- integer specifying the precision of the underlying + Laurent series. Default: ``None``, meaning that ``max_exp + 1`` is + used. OUTPUT: @@ -1845,16 +1842,16 @@ def evaluate(self, tau, prec=None, num_prec=None, check=False): - ``tau`` -- ``infinity`` or an element of the upper half plane. E.g. with parent ``AA`` or ``CC``. - - ``prec`` -- An integer, namely the precision used for the + - ``prec`` -- integer, namely the precision used for the Fourier expansion. If ``prec == None`` (default) - then the default precision of ``self.parent()`` is used. + then the default precision of ``self.parent()`` is used - - ``num_prec`` -- An integer, namely the minimal numerical precision + - ``num_prec`` -- integer, namely the minimal numerical precision used for ``tau`` and ``d``. If ``num_prec == None`` (default) then the default numerical precision of ``self.parent()`` is used. - - ``check`` -- If ``True`` then the order of ``tau`` is checked. + - ``check`` -- if ``True`` then the order of ``tau`` is checked. Otherwise the order is only considered for ``tau = infinity, i, rho, -1/rho``. Default: ``False``. @@ -1879,7 +1876,7 @@ def evaluate(self, tau, prec=None, num_prec=None, check=False): #. The evaluation at ``w`` is calculated by evaluating the truncated Fourier expansion of - self at ``q(w)``. + ``self`` at ``q(w)``. Note that this is much faster and more precise than a direct evaluation at ``tau``. diff --git a/src/sage/modular/modform_hecketriangle/hecke_triangle_group_element.py b/src/sage/modular/modform_hecketriangle/hecke_triangle_group_element.py index cc88da2542e..df9568bb2ab 100644 --- a/src/sage/modular/modform_hecketriangle/hecke_triangle_group_element.py +++ b/src/sage/modular/modform_hecketriangle/hecke_triangle_group_element.py @@ -63,7 +63,7 @@ def cyclic_representative(L): INPUT: - - ``L`` -- A list or tuple. + - ``L`` -- list or tuple OUTPUT: @@ -103,13 +103,13 @@ def __init__(self, parent, M, check=True, **kwargs): INPUT: - - ``parent`` -- A ``HeckeTriangleGroup``. + - ``parent`` -- a ``HeckeTriangleGroup`` - - ``M`` -- A matrix which coerces into the matrix space + - ``M`` -- a matrix which coerces into the matrix space of ``parent``. For example with entries in a polynomial ring over ``ZZ`` with parameter ``lam``. - - ``check`` -- ``True`` (default) or ``False``. If ``True`` + - ``check`` -- boolean (default: ``True``); if ``True`` then a (possibly long) check is performed to see whether ``M`` really corresponds to a group element of ``parent``. @@ -182,7 +182,7 @@ def _word_S_T_data(self): of ``self`` as a product of the generators ``S`` and ``T`` together with a sign correction ``sgn``. - If this decomposition is not possible a :class:`TypeError` + If this decomposition is not possible a :exc:`TypeError` is raised. In particular this function can be used to check the membership in ``parent`` of an arbitrary matrix over the base ring. @@ -256,7 +256,7 @@ def word_S_T(self): of ``L`` are either the generator ``S`` or a non-trivial integer power of the generator ``T``. ``sgn`` is +- the identity. - If this decomposition is not possible a :class:`TypeError` is raised. + If this decomposition is not possible a :exc:`TypeError` is raised. EXAMPLES:: @@ -337,7 +337,7 @@ def _repr_(self): """ return self.string_repr(self.parent().element_repr_method()) - def string_repr(self, method="default"): + def string_repr(self, method='default'): r""" Return a string representation of ``self`` using the specified ``method``. This method is used to represent ``self``. @@ -346,21 +346,23 @@ def string_repr(self, method="default"): INPUT: - - ``method`` -- one of + - ``method`` -- one of - - ``default``: Use the usual representation method for matrix group elements. + - ``'default'`` -- use the usual representation method for matrix + group elements - - ``basic``: The representation is given as a word in ``S`` and powers of ``T``. - Note: If ``S, T`` are defined accordingly the output can - be used/evaluated directly to recover ``self``. + - ``'basic'`` -- the representation is given as a word in ``S`` and + powers of ``T``. Note: If ``S, T`` are defined accordingly the + output can be used/evaluated directly to recover ``self``. - - ``conj``: The conjugacy representative of the element is represented - as a word in powers of the basic blocks, together with - an unspecified conjugation matrix. + - ``'conj'`` -- the conjugacy representative of the element is + represented as a word in powers of the basic blocks, together with + an unspecified conjugation matrix - - ``block``: Same as ``conj`` but the conjugation matrix is specified as well. - Note: Assuming ``S, T, U, V`` are defined accordingly the output - can directly be used/evaluated to recover ``self``. + - ``'block'`` -- same as ``conj`` but the conjugation matrix is + specified as well. Note: Assuming ``S, T, U, V`` are defined + accordingly the output can directly be used/evaluated to recover + ``self``. Warning: For ``n=infinity`` the methods ``conj`` and ``block`` are not verified at all and are probably wrong! @@ -375,10 +377,10 @@ def string_repr(self, method="default"): sage: el4 = G.U()^4 sage: el5 = (G.V(2)*G.T()).acton(-G.S()) - sage: el4.string_repr(method="basic") + sage: el4.string_repr(method='basic') 'S*T^(-1)' - sage: G.element_repr_method("default") + sage: G.element_repr_method('default') sage: el1 [-1 0] [ 0 -1] @@ -395,7 +397,7 @@ def string_repr(self, method="default"): [-7*lam - 4 9*lam + 6] [-4*lam - 5 7*lam + 4] - sage: G.element_repr_method("basic") + sage: G.element_repr_method('basic') sage: el1 -1 sage: el2 @@ -407,7 +409,7 @@ def string_repr(self, method="default"): sage: el5 T*S*T^2*S*T^(-2)*S*T^(-1) - sage: G.element_repr_method("conj") + sage: G.element_repr_method('conj') sage: el1 [-1] sage: el2 @@ -419,7 +421,7 @@ def string_repr(self, method="default"): sage: el5 [-S] - sage: G.element_repr_method("block") + sage: G.element_repr_method('block') sage: el1 -1 sage: el2 @@ -431,14 +433,14 @@ def string_repr(self, method="default"): sage: el5 -(T*S*T^2) * (S) * (T*S*T^2)^(-1) - sage: G.element_repr_method("default") + sage: G.element_repr_method('default') sage: G = HeckeTriangleGroup(n=infinity) sage: el = G.S()*G.T(3)*G.S()*G.T(-2) sage: print(el.string_repr()) [ -1 4] [ 6 -25] - sage: print(el.string_repr(method="basic")) + sage: print(el.string_repr(method='basic')) S*T^3*S*T^(-2) """ if method == "default": @@ -472,7 +474,7 @@ def string_repr(self, method="default"): (L, R, sgn) = self._block_decomposition_data() - repr_str = self.string_repr(method="conj") + repr_str = self.string_repr(method='conj') repr_str = repr_str[1:-1] if sgn < 0: repr_str = repr_str[1:] @@ -481,7 +483,7 @@ def string_repr(self, method="default"): if R.is_identity(): repr_str = "{}{}".format("-" if sgn < 0 else "", repr_str) else: - R_str = "({})".format(R.string_repr(method="basic")) + R_str = "({})".format(R.string_repr(method='basic')) repr_str = "{}{} * ({}) * {}^(-1)".format("-" if sgn < 0 else "", R_str, repr_str, R_str) return repr_str @@ -660,7 +662,7 @@ def _primitive_block_decomposition_data(self): decomposition is further described by the tuple ``L``, and the corresponding conjugation matrix ``R``. - Together they describe the primitive part of self. + Together they describe the primitive part of ``self``. I.e. an element which is equal to ``self`` up to a sign after taking the appropriate power and which itself cannot be written as a non-trivial @@ -680,7 +682,7 @@ def _primitive_block_decomposition_data(self): The number of such factors is called ``block length`` (see :meth:`block_length`). Each block (and also their product) has a positive sign and - non-negative entries. + nonnegative entries. In the elliptic case the primitive representative is either ``S`` or ``U``. @@ -878,7 +880,7 @@ def _primitive_block_decomposition_data(self): return (L, R) - def primitive_representative(self, method="block"): + def primitive_representative(self, method='block'): r""" Return a tuple ``(P, R)`` which gives the decomposition of the primitive part of ``self``, @@ -887,7 +889,7 @@ def primitive_representative(self, method="block"): conjugation matrix ``R`` (the result depends on the method used). - Together they describe the primitive part of self. + Together they describe the primitive part of ``self``. I.e. an element which is equal to ``self`` up to a sign after taking the appropriate power. @@ -901,20 +903,17 @@ def primitive_representative(self, method="block"): INPUT: - - ``method`` -- ``block`` (default) or ``cf``. The method - used to determine ``P`` and ``R``. If - ``self`` is elliptic, this parameter is - ignored, and if ``self`` is +- the identity - then the ``block`` method is used. + - ``method`` -- ``'block'`` (default) or ``'cf'``. The method used to + determine ``P`` and ``R``. If ``self`` is elliptic, this parameter is + ignored, and if ``self`` is +- the identity then the ``block`` method + is used. - With ``block`` the decomposition described - in :meth:`_primitive_block_decomposition_data` is used. + With ``'block'`` the decomposition described in + :meth:`_primitive_block_decomposition_data` is used. - With ``cf`` a reduced representative from - the lambda-CF of ``self`` is used (see - :meth:`continued_fraction`). In that case - ``P`` corresponds to the period and ``R`` - to the preperiod. + With ``'cf'`` a reduced representative from the lambda-CF of ``self`` + is used (see :meth:`continued_fraction`). In that case ``P`` + corresponds to the period and ``R`` to the preperiod. OUTPUT: @@ -926,37 +925,37 @@ def primitive_representative(self, method="block"): sage: from sage.modular.modform_hecketriangle.hecke_triangle_groups import HeckeTriangleGroup sage: G = HeckeTriangleGroup(n=7) sage: G.element_repr_method("basic") - sage: el = G.T().primitive_representative(method="cf") + sage: el = G.T().primitive_representative(method='cf') sage: el (S*T^(-1)*S*T^(-1)*S*T*S, S*T*S) sage: (el[0]).is_primitive() True - sage: el = G.V(2).acton(G.T(-3)).primitive_representative(method="cf") + sage: el = G.V(2).acton(G.T(-3)).primitive_representative(method='cf') sage: el (-T*S*T^(-1)*S*T^(-1), 1) sage: (el[0]).is_primitive() True - sage: el = (-G.V(2)).primitive_representative(method="cf") + sage: el = (-G.V(2)).primitive_representative(method='cf') sage: el (T^2*S, T*S) sage: (el[0]).is_primitive() True - sage: el = (-G.V(2)^3*G.V(6)^2*G.V(3)).primitive_representative(method="cf") + sage: el = (-G.V(2)^3*G.V(6)^2*G.V(3)).primitive_representative(method='cf') sage: el (-T^2*S*T^2*S*T*S*T^(-2)*S*T*S*T*S*T^2*S, T*S) sage: (el[0]).is_primitive() True - sage: el = (G.U()^4*G.S()*G.V(2)).acton(-G.V(2)^3*G.V(6)^2*G.V(3)).primitive_representative(method="cf") + sage: el = (G.U()^4*G.S()*G.V(2)).acton(-G.V(2)^3*G.V(6)^2*G.V(3)).primitive_representative(method='cf') sage: el (-T^2*S*T^2*S*T^2*S*T*S*T^(-2)*S*T*S*T*S, T*S*T*S*T*S*T^2*S) sage: (el[0]).is_primitive() True - sage: el = (G.V(1)^5*G.V(2)*G.V(3)^3).primitive_representative(method="cf") + sage: el = (G.V(1)^5*G.V(2)*G.V(3)^3).primitive_representative(method='cf') sage: el (T^2*S*T*S*T^2*S*T*S*T^2*S*T*S*T^7*S, T^6*S) sage: (el[0]).is_primitive() True - sage: el = (G.V(2)*G.V(3)).acton(G.U()^6).primitive_representative(method="cf") + sage: el = (G.V(2)*G.V(3)).acton(G.U()^6).primitive_representative(method='cf') sage: el (T*S, -T*S*T^2*S*T*S*T) sage: (el[0]).is_primitive() @@ -1066,10 +1065,10 @@ def primitive_representative(self, method="block"): raise ValueError("if the element is not elliptic, then method must " "be either be 'cf' or 'block'") - def primitive_part(self, method="cf"): + def primitive_part(self, method='cf'): r""" Return the primitive part of ``self``. I.e. a group element - ``A`` with non-negative trace such that + ``A`` with nonnegative trace such that ``self = sign * A^power``, where ``sign = self.sign()`` is +- the identity (to correct the sign) and ``power = self.primitive_power()``. @@ -1087,16 +1086,14 @@ def primitive_part(self, method="cf"): INPUT: - - ``method`` -- The method used to determine the primitive + - ``method`` -- the method used to determine the primitive part (see :meth:`primitive_representative`), - default: "cf". The parameter is ignored + default: ``'cf'``. The parameter is ignored for elliptic elements or +- the identity. The result should not depend on the method. - OUTPUT: - - The primitive part as a group element of ``self``. + OUTPUT: the primitive part as a group element of ``self`` EXAMPLES:: @@ -1128,25 +1125,25 @@ def primitive_part(self, method="cf"): sage: el = (G.V(2)*G.V(3)).acton(G.U()^6) sage: el.primitive_part() (-T*S*T^2*S*T*S*T) * (U) * (-T*S*T^2*S*T*S*T)^(-1) - sage: el.primitive_part() == el.primitive_part(method="block") + sage: el.primitive_part() == el.primitive_part(method='block') True sage: G.T().primitive_part() (T^(-1)*S) * (V(6)) * (T^(-1)*S)^(-1) - sage: G.T().primitive_part(method="block") + sage: G.T().primitive_part(method='block') (T^(-1)) * (V(1)) * (T^(-1))^(-1) - sage: G.V(2).acton(G.T(-3)).primitive_part() == G.V(2).acton(G.T(-3)).primitive_part(method="block") + sage: G.V(2).acton(G.T(-3)).primitive_part() == G.V(2).acton(G.T(-3)).primitive_part(method='block') True - sage: (-G.V(2)).primitive_part() == (-G.V(2)).primitive_part(method="block") + sage: (-G.V(2)).primitive_part() == (-G.V(2)).primitive_part(method='block') True sage: el = -G.V(2)^3*G.V(6)^2*G.V(3) - sage: el.primitive_part() == el.primitive_part(method="block") + sage: el.primitive_part() == el.primitive_part(method='block') True sage: el = (G.U()^4*G.S()*G.V(2)).acton(-G.V(2)^3*G.V(6)^2*G.V(3)) - sage: el.primitive_part() == el.primitive_part(method="block") + sage: el.primitive_part() == el.primitive_part(method='block') True sage: el=G.V(1)^5*G.V(2)*G.V(3)^3 - sage: el.primitive_part() == el.primitive_part(method="block") + sage: el.primitive_part() == el.primitive_part(method='block') True sage: G.element_repr_method("default") @@ -1174,8 +1171,8 @@ def reduce(self, primitive=True): INPUT: - - ``primitive`` -- If ``True`` (default) then a primitive - representative for ``self`` is returned. + - ``primitive`` -- if ``True`` (default) then a primitive + representative for ``self`` is returned EXAMPLES:: @@ -1213,7 +1210,7 @@ def reduce(self, primitive=True): from warnings import warn warn("The case n=infinity here is not verified at all and probably wrong!") - (P, R) = self.primitive_representative(method="cf") + (P, R) = self.primitive_representative(method='cf') if primitive: return P @@ -1270,7 +1267,7 @@ def sign(self): raise AssertionError("This shouldn't happen!") @cached_method - def primitive_power(self, method="cf"): + def primitive_power(self, method='cf'): r""" Return the primitive power of ``self``. I.e. an integer ``power`` such that ``self = sign * primitive_part^power``, @@ -1286,16 +1283,16 @@ def primitive_power(self, method="cf"): INPUT: - - ``method`` -- The method used to determine the primitive + - ``method`` -- the method used to determine the primitive power (see :meth:`primitive_representative`), - default: "cf". The parameter is ignored + default: ``'cf'``. The parameter is ignored for elliptic elements or +- the identity. OUTPUT: An integer. For +- the identity element ``0`` is returned, for parabolic and hyperbolic elements a positive integer. - And for elliptic elements a (non-zero) integer with minimal + And for elliptic elements a (nonzero) integer with minimal absolute value such that ``primitive_part^power`` still has a positive sign. @@ -1316,7 +1313,7 @@ def primitive_power(self, method="cf"): 2 sage: (G.V(2)*G.V(3)).acton(G.U()^6).primitive_power() -1 - sage: G.V(2).acton(G.T(-3)).primitive_power() == G.V(2).acton(G.T(-3)).primitive_power(method="block") + sage: G.V(2).acton(G.T(-3)).primitive_power() == G.V(2).acton(G.T(-3)).primitive_power(method='block') True sage: (-G.I()).primitive_power() @@ -1425,13 +1422,12 @@ def block_length(self, primitive=False): INPUT: - - ``primitive`` -- If ``True`` then the conjugacy - representative of the primitive part is - used instead, default: ``False``. + - ``primitive`` -- boolean (default: ``False``); if ``True`` then the + conjugacy representative of the primitive part is used instead OUTPUT: - An integer. For hyperbolic elements a non-negative integer. + An integer. For hyperbolic elements a nonnegative integer. For parabolic elements a negative sign corresponds to taking the inverse. For elliptic elements a (non-trivial) integer with minimal absolute value is chosen. For +- the identity @@ -1787,12 +1783,12 @@ def conjugacy_type(self, ignore_sign=True, primitive=False): INPUT: - - ``ignore_sign`` -- If ``True`` (default) then the conjugacy - classes are only considered up to a sign. + - ``ignore_sign`` -- if ``True`` (default) then the conjugacy + classes are only considered up to a sign - - ``primitive`` -- If ``True`` then the conjugacy class of - the primitive part is considered instead - and the sign is ignored, default: ``False``. + - ``primitive`` -- boolean (default: ``False``); if ``True`` then the + conjugacy class of the primitive part is considered instead and the + sign is ignored OUTPUT: @@ -2013,7 +2009,7 @@ def simple_fixed_point_set(self, extended=True): This is a so called `irreducible system of poles` for rational period functions for the parent group. I.e. the fixed points occur as a irreducible part - of the non-zero pole set of some rational period + of the nonzero pole set of some rational period function and all pole sets are given as a union of such irreducible systems of poles. @@ -2308,7 +2304,7 @@ def is_elliptic(self): def is_primitive(self): r""" - Returns whether ``self`` is primitive. We call an element + Return whether ``self`` is primitive. We call an element primitive if (up to a sign and taking inverses) it generates the full stabilizer subgroup of the corresponding fixed point. In the non-elliptic case this means that primitive elements @@ -2367,7 +2363,7 @@ def is_primitive(self): def is_reduced(self, require_primitive=True, require_hyperbolic=True): r""" - Returns whether ``self`` is reduced. We call an element + Return whether ``self`` is reduced. We call an element reduced if the associated lambda-CF is purely periodic. I.e. (in the hyperbolic case) if the associated hyperbolic @@ -2387,11 +2383,11 @@ def is_reduced(self, require_primitive=True, require_hyperbolic=True): INPUT: - - ``require_primitive`` -- If ``True`` (default) then non-primitive elements - are not considered reduced. + - ``require_primitive`` -- if ``True`` (default) then non-primitive + elements are not considered reduced - - ``require_hyperbolic`` -- If ``True`` (default) then non-hyperbolic elements - are not considered reduced. + - ``require_hyperbolic`` -- if ``True`` (default) then non-hyperbolic + elements are not considered reduced EXAMPLES:: @@ -2886,7 +2882,7 @@ def root_extension_embedding(self, K=None): INPUT: - - ``K`` -- A field to which we want the (correct) embedding. + - ``K`` -- a field to which we want the (correct) embedding. If ``K=None`` (default), then ``AlgebraicField()`` is used for elliptic elements and ``AlgebraicRealField()`` otherwise. @@ -2947,28 +2943,29 @@ def root_extension_embedding(self, K=None): """ return self.parent().root_extension_embedding(self.discriminant(), K) - def fixed_points(self, embedded=False, order="default"): + def fixed_points(self, embedded=False, order='default'): r""" Return a pair of (mutually conjugate) fixed points of ``self`` in a possible quadratic extension of the base field. INPUT: - - ``embedded`` -- If ``True``, the fixed points are embedded into - ``AlgebraicRealField`` resp. ``AlgebraicField``. Default: ``False``. + - ``embedded`` -- boolean (default: ``False``); if ``True``, the fixed + points are embedded into ``AlgebraicRealField`` resp. + ``AlgebraicField`` - - ``order`` -- If ``order="none"`` the fixed points are chosen - and ordered according to a fixed formula. + - ``order`` -- if ``order='none'`` the fixed points are chosen + and ordered according to a fixed formula - If ``order="sign"`` the fixed points are always ordered + If ``order='sign'`` the fixed points are always ordered according to the sign in front of the square root. - If ``order="default"`` (default) then in case the fixed + If ``order='default'`` (default) then in case the fixed points are hyperbolic they are ordered according to the sign of the trace of ``self`` instead, such that the attracting fixed point comes first. - If ``order="trace"`` the fixed points are always ordered + If ``order='trace'`` the fixed points are always ordered according to the sign of the trace of ``self``. If the trace is zero they are ordered by the sign in front of the square root. In particular the fixed_points @@ -3017,16 +3014,16 @@ def fixed_points(self, embedded=False, order="default"): True sage: (G.U()^4).fixed_points() ((1/2*lam^2 - 1/2*lam - 1/2)*e + 1/2*lam, (-1/2*lam^2 + 1/2*lam + 1/2)*e + 1/2*lam) - sage: pts = (G.U()^4).fixed_points(order="trace") + sage: pts = (G.U()^4).fixed_points(order='trace') sage: (G.U()^4).fixed_points() == [pts[1], pts[0]] False - sage: (G.U()^4).fixed_points(order="trace") == (-G.U()^4).fixed_points(order="trace") + sage: (G.U()^4).fixed_points(order='trace') == (-G.U()^4).fixed_points(order='trace') True - sage: (G.U()^4).fixed_points() == (G.U()^4).fixed_points(order="none") + sage: (G.U()^4).fixed_points() == (G.U()^4).fixed_points(order='none') True sage: (-G.U()^4).fixed_points() == (G.U()^4).fixed_points() True - sage: (-G.U()^4).fixed_points(order="none") == pts + sage: (-G.U()^4).fixed_points(order='none') == pts True sage: p = (G.U()^4).fixed_points(embedded=True)[1] sage: p @@ -3106,7 +3103,7 @@ def acton(self, tau): INPUT: - - ``tau`` -- Either an element of ``self`` or any + - ``tau`` -- either an element of ``self`` or any element to which a linear fractional transformation can be applied in the usual way. @@ -3238,10 +3235,10 @@ def slash(self, f, tau=None, k=None): INPUT: - - ``f`` -- A function in ``tau`` (or an object for which - evaluation at ``self.acton(tau)`` makes sense. + - ``f`` -- a function in ``tau`` (or an object for which + evaluation at ``self.acton(tau)`` makes sense - - ``tau`` -- Where to evaluate the result. + - ``tau`` -- where to evaluate the result. This should be a valid argument for :meth:`acton`. If ``tau`` is a point of ``HyperbolicPlane()`` then @@ -3252,7 +3249,7 @@ def slash(self, f, tau=None, k=None): the generator of the polynomial ring is used for ``tau``. That way ``slash`` acts on rational functions / polynomials. - - ``k`` -- An even integer. + - ``k`` -- even integer Default: ``None`` in which case ``f`` either has to be a rational function / polynomial in one @@ -3320,9 +3317,10 @@ def slash(self, f, tau=None, k=None): return (self.c()*tau + self.d())**(-k) * f(self.acton(tau)) - def as_hyperbolic_plane_isometry(self, model="UHP"): + def as_hyperbolic_plane_isometry(self, model='UHP'): r""" - Return ``self`` as an isometry of ``HyperbolicPlane()`` (in the upper half plane model). + Return ``self`` as an isometry of ``HyperbolicPlane()`` (in the upper + half plane model). EXAMPLES:: diff --git a/src/sage/modular/modform_hecketriangle/hecke_triangle_groups.py b/src/sage/modular/modform_hecketriangle/hecke_triangle_groups.py index aea71efb49e..6aedcba881c 100644 --- a/src/sage/modular/modform_hecketriangle/hecke_triangle_groups.py +++ b/src/sage/modular/modform_hecketriangle/hecke_triangle_groups.py @@ -77,11 +77,9 @@ def __init__(self, n): INPUT: - - ``n`` -- ``infinity`` or an integer greater or equal to ``3``. + - ``n`` -- ``infinity`` or an integer greater or equal to `3` - OUTPUT: - - The Hecke triangle group for the given parameter ``n``. + OUTPUT: the Hecke triangle group for the given parameter `n` EXAMPLES:: @@ -143,19 +141,23 @@ def element_repr_method(self, method=None): INPUT: - - ``method`` -- If ``method=None`` (default) the current default representation - method is returned. Otherwise the default method is set to ``method``. - If ``method`` is not available a :class:`ValueError` is raised. Possible methods are: + - ``method`` -- if ``method=None`` (default) the current default + representation method is returned. Otherwise the default method is + set to ``method``. If ``method`` is not available a + :exc:`ValueError` is raised. Possible methods are: - ``default``: Use the usual representation method for matrix group elements. + - ``default``: use the usual representation method for matrix group + elements - ``basic``: The representation is given as a word in ``S`` and powers of ``T``. + - ``basic``: the representation is given as a word in ``S`` and + powers of ``T`` - ``conj``: The conjugacy representative of the element is represented - as a word in powers of the basic blocks, together with - an unspecified conjugation matrix. + - ``conj``: the conjugacy representative of the element is + represented as a word in powers of the basic blocks, together with + an unspecified conjugation matrix - ``block``: Same as ``conj`` but the conjugation matrix is specified as well. + - ``block``: same as ``conj`` but the conjugation matrix is + specified as well EXAMPLES:: @@ -390,11 +392,13 @@ def I(self): @cached_method def T(self, m=1): r""" - Return the element in ``self`` corresponding to the translation by ``m*self.lam()``. + Return the element in ``self`` corresponding to the translation by + ``m*self.lam()``. INPUT: - - ``m`` -- An integer, default: ``1``, namely the second generator of ``self``. + - ``m`` -- integer (default: 1); namely the second generator of + ``self`` EXAMPLES:: @@ -479,12 +483,10 @@ def V(self, j): INPUT: - - ``j`` -- Any integer. To get the usual representatives - ``j`` should range from ``1`` to ``self.n()-1``. - - OUTPUT: + - ``j`` --integer; to get the usual representatives + ``j`` should range from ``1`` to ``self.n()-1`` - The corresponding matrix/element. + OUTPUT: the corresponding matrix/element The matrix is parabolic if ``j`` is congruent to `\pm 1` modulo ``self.n()``. It is elliptic if ``j`` is congruent to 0 modulo ``self.n()``. @@ -589,19 +591,19 @@ def get_FD(self, z): INPUT: - - ``z`` -- a complex number or an element of AlgebraicField(). + - ``z`` -- a complex number or an element of AlgebraicField() OUTPUT: A tuple ``(A, w)``. - ``A`` -- a matrix in ``self`` such that ``A.acton(w)==z`` - (if ``z`` is exact at least). + (if ``z`` is exact at least) - ``w`` -- a complex number or an element of AlgebraicField() (depending on the type ``z``) which lies inside the (strict) fundamental domain of ``self`` (``self.in_FD(w)==True``) and - which is equivalent to ``z`` (by the above property). + which is equivalent to ``z`` (by the above property) EXAMPLES:: @@ -678,13 +680,13 @@ def root_extension_field(self, D): INPUT: - - ``D`` -- An element of the base ring of ``self`` - corresponding to a discriminant. + - ``D`` -- an element of the base ring of ``self`` + corresponding to a discriminant OUTPUT: A relative (at most quadratic) extension to the base field - of self in the variable ``e`` which corresponds to ``sqrt(D)``. + of ``self`` in the variable ``e`` which corresponds to ``sqrt(D)``. If the extension degree is ``1`` then the base field is returned. The correct embedding is the positive resp. positive imaginary one. @@ -745,18 +747,18 @@ def root_extension_embedding(self, D, K=None): INPUT: - - ``D`` -- An element of the base ring of ``self`` - corresponding to a discriminant. + - ``D`` -- an element of the base ring of ``self`` + corresponding to a discriminant - - ``K`` -- A field to which we want the (correct) embedding. - If ``K=None`` (default) then ``AlgebraicField()`` is + - ``K`` -- a field to which we want the (correct) embedding; + if ``K=None`` (default) then ``AlgebraicField()`` is used for positive ``D`` and ``AlgebraicRealField()`` - otherwise. + otherwise OUTPUT: The corresponding embedding if it was found. - Otherwise a :class:`ValueError` is raised. + Otherwise a :exc:`ValueError` is raised. EXAMPLES:: @@ -893,7 +895,7 @@ def _elliptic_conj_reps(self): def _conjugacy_representatives(self, max_block_length=0, D=None): r""" Store conjugacy representatives up to block length - ``max_block_length`` (a non-negative integer, default: 0) + ``max_block_length`` (a nonnegative integer, default: 0) in the internal dictionary. Previously calculated data is reused. This is a helper function for e.g. :meth:`class_number`. @@ -904,18 +906,17 @@ def _conjugacy_representatives(self, max_block_length=0, D=None): The set of all non-primitive representatives (so far) with discriminant ``D`` is stored in ``self._conj_nonprim[D]``. - The case of non-positive discriminants is done manually. + The case of nonpositive discriminants is done manually. INPUT: - - ``max_block_length`` -- A non-negative integer (default: ``0``), - the maximal block length. + - ``max_block_length`` -- nonnegative integer (default: `0`); the + maximal block length - - ``D`` -- An element/discriminant of the base ring or - more generally an upper bound for the - involved discriminants. If ``D != None`` - then an upper bound for ``max_block_length`` - is deduced from ``D`` (default: ``None``). + - ``D`` -- an element/discriminant of the base ring or more generally + an upper bound for the involved discriminants. If ``D != None`` then + an upper bound for ``max_block_length`` is deduced from ``D`` + (default: ``None``). EXAMPLES:: @@ -969,7 +970,7 @@ def _conjugacy_representatives(self, max_block_length=0, D=None): if max_block_length < 0: raise TypeError except TypeError: - raise ValueError("max_block_length must be a non-negative integer!") + raise ValueError("max_block_length must be a nonnegative integer!") if not hasattr(self, "_max_block_length"): self._max_block_length = ZZ.zero() @@ -1068,11 +1069,11 @@ def class_representatives(self, D, primitive=True): INPUT: - - ``D`` -- An element of the base ring corresponding - to a valid discriminant. + - ``D`` -- an element of the base ring corresponding + to a valid discriminant - - ``primitive`` -- If ``True`` (default) then only primitive - representatives are considered. + - ``primitive`` -- if ``True`` (default) then only primitive + representatives are considered EXAMPLES:: @@ -1153,11 +1154,11 @@ def class_number(self, D, primitive=True): INPUT: - - ``D`` -- An element of the base ring corresponding - to a valid discriminant. + - ``D`` -- an element of the base ring corresponding + to a valid discriminant - - ``primitive`` -- If ``True`` (default) then only primitive - elements are considered. + - ``primitive`` -- if ``True`` (default) then only primitive + elements are considered EXAMPLES:: @@ -1203,10 +1204,10 @@ def is_discriminant(self, D, primitive=True) -> bool: INPUT: - - ``D`` -- An element of the base ring. + - ``D`` -- an element of the base ring - - ``primitive`` -- If ``True`` (default) then only primitive - elements are considered. + - ``primitive`` -- if ``True`` (default) then only primitive + elements are considered OUTPUT: @@ -1250,22 +1251,20 @@ def list_discriminants(self, D, primitive=True, hyperbolic=True, incomplete=Fals INPUT: - - ``D`` -- An element/discriminant of the base ring or - more generally an upper bound for the discriminant. + - ``D`` -- an element/discriminant of the base ring or + more generally an upper bound for the discriminant - - ``primitive`` -- If ``True`` (default) then only primitive - discriminants are listed. + - ``primitive`` -- if ``True`` (default) then only primitive + discriminants are listed - - ``hyperbolic`` -- If ``True`` (default) then only positive - discriminants are listed. + - ``hyperbolic`` -- if ``True`` (default) then only positive + discriminants are listed - - ``incomplete`` -- If ``True`` (default: ``False``) then all + - ``incomplete`` -- if ``True`` (default: ``False``) then all (also higher) discriminants which were gathered so far are listed (however there might be missing discriminants in between). - OUTPUT: - - A list of discriminants less than or equal to ``D``. + OUTPUT: list of discriminants less than or equal to ``D`` EXAMPLES:: @@ -1312,8 +1311,8 @@ def reduced_elements(self, D): Also see the element method :meth:`is_reduced` for more information. - - ``D`` -- An element of the base ring corresponding - to a valid discriminant. + - ``D`` -- an element of the base ring corresponding + to a valid discriminant EXAMPLES:: @@ -1349,8 +1348,8 @@ def simple_elements(self, D): Also see the element method ``is_simple()`` for more information. - - ``D`` -- An element of the base ring corresponding - to a valid discriminant. + - ``D`` -- an element of the base ring corresponding to a valid + discriminant EXAMPLES:: @@ -1376,7 +1375,8 @@ def simple_elements(self, D): def rational_period_functions(self, k, D): r""" - Return a list of basic rational period functions of weight ``k`` for discriminant ``D``. + Return a list of basic rational period functions of weight ``k`` for + discriminant ``D``. The list is expected to be a generating set for all rational period functions of the given weight and discriminant (unknown). @@ -1385,11 +1385,11 @@ def rational_period_functions(self, k, D): Also see the element method `rational_period_function` for more information. - - ``k`` -- An even integer, the desired weight - of the rational period functions. + - ``k`` -- even integer, the desired weight of the rational period + functions - - ``D`` -- An element of the base ring corresponding - to a valid discriminant. + - ``D`` -- an element of the base ring corresponding to a valid + discriminant EXAMPLES:: diff --git a/src/sage/modular/modform_hecketriangle/readme.py b/src/sage/modular/modform_hecketriangle/readme.py index 799f68dc814..60747e9578a 100644 --- a/src/sage/modular/modform_hecketriangle/readme.py +++ b/src/sage/modular/modform_hecketriangle/readme.py @@ -464,7 +464,7 @@ For each group element a very specific conjugacy representative can be obtained. For hyperbolic and parabolic elements the representative is a product ``V(j)``-matrices. They all - have non-negative trace and the number of factors is called + have nonnegative trace and the number of factors is called the block length of the element (which is implemented). Note: For this decomposition special care is given to the diff --git a/src/sage/modular/modform_hecketriangle/series_constructor.py b/src/sage/modular/modform_hecketriangle/series_constructor.py index 462cc273459..4705846217b 100644 --- a/src/sage/modular/modform_hecketriangle/series_constructor.py +++ b/src/sage/modular/modform_hecketriangle/series_constructor.py @@ -86,14 +86,12 @@ def __init__(self, group, prec): INPUT: - - ``group`` -- A Hecke triangle group (default: HeckeTriangleGroup(3)). + - ``group`` -- a Hecke triangle group (default: HeckeTriangleGroup(3)) - - ``prec`` -- An integer (default: 10), the default precision used - in calculations in the LaurentSeriesRing or PowerSeriesRing. + - ``prec`` -- integer (default: 10), the default precision used in + calculations in the LaurentSeriesRing or PowerSeriesRing - OUTPUT: - - The constructor for Fourier expansion with the specified settings. + OUTPUT: the constructor for Fourier expansion with the specified settings EXAMPLES:: @@ -503,7 +501,7 @@ def EisensteinSeries_ZZ(self, k): INPUT: - - ``k`` -- A non-negative even integer, namely the weight. + - ``k`` -- a nonnegative even integer, namely the weight EXAMPLES:: @@ -546,7 +544,7 @@ def EisensteinSeries_ZZ(self, k): raise TypeError(None) k = 2*ZZ(k/2) except TypeError: - raise TypeError("k={} has to be a non-negative even integer!".format(k)) + raise TypeError("k={} has to be a nonnegative even integer!".format(k)) if (not self.group().is_arithmetic() or self.group().n() == infinity): # Exceptional cases should be called manually (see in FormsRing_abstract) diff --git a/src/sage/modular/modform_hecketriangle/space.py b/src/sage/modular/modform_hecketriangle/space.py index 9530d5f07fe..3a55142a63d 100644 --- a/src/sage/modular/modform_hecketriangle/space.py +++ b/src/sage/modular/modform_hecketriangle/space.py @@ -266,7 +266,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` OUTPUT: @@ -440,7 +440,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` OUTPUT: @@ -708,7 +708,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` OUTPUT: @@ -853,7 +853,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` OUTPUT: @@ -961,9 +961,9 @@ def _change_degree(self, k, ep): INPUT: - - ``k`` -- A rational number, the weight. + - ``k`` -- a rational number; the weight - - ``ep`` -- ``1`` or ``-1``, the multiplier. + - ``ep`` -- ``1`` or ``-1``; the multiplier EXAMPLES:: @@ -1017,7 +1017,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``, i.e. in this case the zero vector. + - ``v`` -- an element of ``self``, i.e. in this case the zero vector EXAMPLES:: diff --git a/src/sage/modular/modform_hecketriangle/subspace.py b/src/sage/modular/modform_hecketriangle/subspace.py index 692fcbfc9ec..b22840338dd 100644 --- a/src/sage/modular/modform_hecketriangle/subspace.py +++ b/src/sage/modular/modform_hecketriangle/subspace.py @@ -137,22 +137,21 @@ def __classcall__(cls, ambient_space, basis=(), check=True): def __init__(self, ambient_space, basis, check): r""" - Return the Submodule of (Hecke) forms in ``ambient_space`` for the given ``basis``. + Return the Submodule of (Hecke) forms in ``ambient_space`` for the + given ``basis``. INPUT: - - ``ambient_space`` -- An ambient forms space. + - ``ambient_space`` -- an ambient forms space - - ``basis`` -- A tuple of (not necessarily linearly independent) - elements of ``ambient_space``. + - ``basis`` -- a tuple of (not necessarily linearly independent) + elements of ``ambient_space`` - - ``check`` -- If ``True`` (default) then a maximal linearly - independent subset of ``basis`` is chosen. Otherwise - it is assumed that ``basis`` is linearly independent. + - ``check`` -- if ``True`` (default) then a maximal linearly + independent subset of ``basis`` is chosen. Otherwise it is assumed + that ``basis`` is linearly independent. - OUTPUT: - - The corresponding submodule. + OUTPUT: the corresponding submodule EXAMPLES:: @@ -383,7 +382,7 @@ def coordinate_vector(self, v): INPUT: - - ``v`` -- An element of ``self``. + - ``v`` -- an element of ``self`` OUTPUT: diff --git a/src/sage/modular/modsym/ambient.py b/src/sage/modular/modsym/ambient.py index 02e1bc3cb9e..beb8509af0f 100644 --- a/src/sage/modular/modsym/ambient.py +++ b/src/sage/modular/modsym/ambient.py @@ -119,13 +119,13 @@ class ModularSymbolsAmbient(ModularSymbolsSpace, AmbientHeckeModule): INPUT: - - ``weight`` -- an integer - - ``group`` -- a congruence subgroup. - - ``sign`` -- an integer, either -1, 0, or 1 + - ``weight`` -- integer + - ``group`` -- a congruence subgroup + - ``sign`` -- integer; either -1, 0, or 1 - ``base_ring`` -- a commutative ring - - ``custom_init`` -- a function that is called with self as input + - ``custom_init`` -- a function that is called with ``self`` as input before any computations are done using self; this could be used - to set a custom modular symbols presentation. + to set a custom modular symbols presentation TESTS:: @@ -147,19 +147,18 @@ def __init__(self, group, weight, sign, base_ring, INPUT: - - ``weight`` -- an integer + - ``weight`` -- integer - - ``group`` -- a congruence subgroup. + - ``group`` -- a congruence subgroup - - ``sign`` -- an integer, either -1, 0, or 1 + - ``sign`` -- integer, either -1, 0, or 1 - - ``base_ring`` -- a commutative ring + - ``base_ring`` -- a commutative ring EXAMPLES:: sage: ModularSymbols(2,2) Modular Symbols space of dimension 1 for Gamma_0(2) of weight 2 with sign 0 over Rational Field - """ weight = int(weight) if weight <= 1: @@ -201,14 +200,10 @@ def new_submodule(self, p=None): INPUT: + - ``p`` -- (default: ``None``) if not ``None``, return only + the `p`-new submodule - - ``p`` -- (default: None); if not None, return only - the `p`-new submodule. - - - OUTPUT: - - The new or `p`-new submodule of this modular symbols ambient space. + OUTPUT: the new or `p`-new submodule of this modular symbols ambient space EXAMPLES:: @@ -306,7 +301,6 @@ def compute_presentation(self): EXAMPLES:: sage: ModularSymbols(11,2).compute_presentation() # no output - """ B, basis, mod = relation_matrix.compute_presentation( self.manin_symbols(), self.sign(), @@ -348,50 +342,49 @@ def manin_gens_to_basis(self): def _element_constructor_(self, x, computed_with_hecke=False): r""" Coerce `x` into this modular symbols space. The result is - either an element of self or a subspace of self. + either an element of ``self`` or a subspace of ``self``. INPUT: The allowed input types for `x` are as follows: + - ``Vector`` -- a vector of the same degree. This + defines the corresponding linear combination of the basis of ``self`` - - ``Vector`` -- a vector of the same degree. This - defines the corresponding linear combination of the basis of self. + - ``ManinSymbol`` -- a Manin symbol of the same weight + as the space - - ``ManinSymbol`` -- a Manin symbol of the same weight - as the space + - ``ModularSymbolsElement`` -- a modular symbol whose + ambient parent is this space of modular symbols. (TODO: make more + sophisticated) - - ``ModularSymbolsElement`` -- a modular symbol whose - ambient parent is this space of modular symbols. (TODO: make more - sophisticated) + - 0 -- the integer 0; results in the 0 modular symbol - - 0 -- the integer 0; results in the 0 modular symbol. + - 3-tuple -- given a 3-tuple (i,u,v), returns the modular symbol + element defined by the Manin symbol + `[X^{i}\cdot Y^{k-2-i}, (u,v)]`, where k is the weight. + Note that we must have `0\leq i \leq k-2`. - - 3-tuple -- Given a 3-tuple (i,u,v), returns the modular symbol - element defined by the Manin symbol - `[X^{i}\cdot Y^{k-2-i}, (u,v)]`, where k is the weight. - Note that we must have `0\leq i \leq k-2`. + - 2-tuple -- given a 2-tuple (u,v), returns the element defined by + the Manin symbol `[X^0 \cdot Y^{2-k}, (u,v)]` - - 2-tuple -- Given a 2-tuple (u,v), returns the element defined by - the Manin symbol `[X^0 \cdot Y^{2-k}, (u,v)]`. + - 2-elements list -- given a list ``[alpha, beta]``, + where `\alpha` and `\beta` are (coercible to) + cusps, return the modular symbol `\{\alpha, \beta\}`. When + the weight `k > 2` return + `Y^{k-2} \{\alpha, \beta\}`. - - 2-elements list -- Given a list ``[alpha, beta]``, - where `\alpha` and `\beta` are (coercible to) - cusps, return the modular symbol `\{\alpha, \beta\}`. When - the weight `k > 2` return - `Y^{k-2} \{\alpha, \beta\}`. + - 3-element list -- given a list ``[i, alpha, beta]``, + where `i` is an integer, and `\alpha`, + `\beta` are (coercible to) cusps, return the modular symbol + `X^i Y^{k-2-i} \{\alpha, \beta\}`. - - 3-element list -- Given a list ``[i, alpha, beta]``, - where `i` is an integer, and `\alpha`, - `\beta` are (coercible to) cusps, return the modular symbol - `X^i Y^{k-2-i} \{\alpha, \beta\}`. - - If our list is ``[f, alpha, beta]``, where `f` - is a homogeneous polynomial in two variables of degree k-2 with - integer coefficients, and alpha and beta are cusps, return the - corresponding sum of modular symbols as an element of self. So if - `f = \sum_{i=0}^{k-2} a_i X^i Y^{k-2-i}`, return - `\sum_{i=0}^{k-2} a_i * [ i, alpha, beta ]`. + If our list is ``[f, alpha, beta]``, where `f` + is a homogeneous polynomial in two variables of degree k-2 with + integer coefficients, and alpha and beta are cusps, return the + corresponding sum of modular symbols as an element of ``self``. So if + `f = \sum_{i=0}^{k-2} a_i X^i Y^{k-2-i}`, return + `\sum_{i=0}^{k-2} a_i * [ i, alpha, beta ]`. EXAMPLES:: @@ -509,8 +502,8 @@ def _action_on_modular_symbols(self, g): INPUT: - `g` (list) -- `g=[a,b,c,d]` where `a,b,c,d` are integers - defining a `2\times2` integer matrix. + - ``g`` -- list; `g=[a,b,c,d]` where `a,b,c,d` are integers + defining a `2\times2` integer matrix OUTPUT: @@ -543,10 +536,10 @@ def manin_symbol(self, x, check=True): INPUT: - - ``x`` (list) -- either `[u,v]` or `[i,u,v]`, where `0\le + - ``x`` -- list; either `[u,v]` or `[i,u,v]`, where `0\le i\le k-2` where `k` is the weight, and `u`,`v` are integers defining a valid element of `\mathbb{P}^1(N)`, where `N` is - the level. + the level OUTPUT: @@ -592,9 +585,9 @@ def _modular_symbol_0_to_alpha(self, alpha, i=0): INPUT: - - ``alpha`` (rational or Infinity) -- a cusp + - ``alpha`` -- rational or Infinity a cusp - - ``i`` (int, default 0) -- the degree of the symbol + - ``i`` -- integer (default: 0); the degree of the symbol OUTPUT: @@ -687,7 +680,7 @@ def modular_symbol(self, x, check=True): INPUT: - - ``x`` (list) -- a list of either 2 or 3 entries: + - ``x`` -- list of either 2 or 3 entries: - 2 entries: `[\alpha, \beta]` where `\alpha` and `\beta` are cusps; @@ -695,7 +688,7 @@ def modular_symbol(self, x, check=True): - 3 entries: `[i, \alpha, \beta]` where `0\le i\le k-2` and `\alpha` and `\beta` are cusps; - - ``check`` (bool, default: ``True``) -- flag that determines + - ``check`` -- boolean (default: ``True``); flag that determines whether the input ``x`` needs processing: use check=False for efficiency if the input ``x`` is a list of length 3 whose first entry is an Integer, and whose second and third @@ -772,13 +765,13 @@ def modular_symbol_sum(self, x, check=True): INPUT: - - ``x`` (list) -- `[f, \alpha, \beta]` where `f = + - ``x`` -- list; `[f, \alpha, \beta]` where `f = \sum_{i=0}^{k-2} a_i X^i Y^{k-2-i}` is a homogeneous polynomial over `\ZZ` of degree `k` and `\alpha` and `\beta` are cusps. - - ``check`` (bool, default: ``True``) -- if True check the validity - of the input tuple ``x`` + - ``check`` -- boolean (default: ``True``); if ``True`` check the + validity of the input tuple ``x`` OUTPUT: @@ -830,7 +823,7 @@ def _compute_dual_hecke_matrix(self, n): INPUT: - - ``n`` (int) -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -853,15 +846,15 @@ def _compute_hecke_matrix_prime(self, p, rows=None): INPUT: - - ``p`` (int) -- a prime number. + - ``p`` -- integer; a prime number - - ``rows`` (list or None (default)) -- if not None, a list of - the rows which should be computed; otherwise the complete - matrix will be computed, + - ``rows`` -- list or ``None`` (default); if not ``None``, a list of + the rows which should be computed, otherwise the complete + matrix will be computed - .. note:: + .. NOTE:: - `p` does not have to be, prime despite the function name. + `p` does not have to be prime despite the function name. OUTPUT: @@ -1013,21 +1006,18 @@ def __heilbronn_operator(self, M, H, t=1): r""" Return the matrix function to the space `M` defined by `H`, `t`. - .. note:: + .. NOTE:: Users will instead use the simpler interface defined, for example, by ``hecke_matrix()`` (see examples). INPUT: + - ``M`` -- ModularSymbols; codomain (a space of modular symbols) - - ``M`` (ModularSymbols) -- codomain (a space of modular - symbols); - - - ``H`` (list) -- a list of matrices in `M_2(\ZZ)`; - - - ``t`` (int, default 1) -- an integer. + - ``H`` -- list of matrices in `M_2(\ZZ)` + - ``t`` -- integer (default: 1) OUTPUT: @@ -1054,8 +1044,6 @@ def __heilbronn_operator(self, M, H, t=1): [ 0 2 -1 2 0] [ 0 0 0 -3 2] [ 0 0 0 0 1] - - """ MS = MatrixSpace(self.base_ring(), self.dimension(), M.dimension()) @@ -1143,7 +1131,7 @@ def _matrix_of_operator_on_modular_symbols(self, codomain, R): r""" Return the matrix of a modular symbols operator. - .. note:: + .. NOTE:: Users will usually instead use the simpler interface defined, for example, by ``hecke_matrix()`` (see examples), @@ -1152,19 +1140,18 @@ def _matrix_of_operator_on_modular_symbols(self, codomain, R): INPUT: - - ``codomain`` -- space of modular symbols - - - ``R`` (list) -- a list of lists `[a,b,c,d]` of length 4, - which we view as elements of `GL_2(`QQ)`. + - ``codomain`` -- space of modular symbols + - ``R`` -- list of lists `[a,b,c,d]` of length 4, + which we view as elements of `GL_2(`QQ)` OUTPUT: - -- (matrix) The matrix of the operator + The matrix of the operator .. MATH:: - x \mapsto \sum_{g in R} g.x, + x \mapsto \sum_{g in R} g.x, where `g.x` is the formal linear fractional transformation on modular @@ -1179,7 +1166,6 @@ def _matrix_of_operator_on_modular_symbols(self, codomain, R): [ 0 3 0 5 -2] [ 0 -3 1 -5 3] [ 0 0 2 3 -3] - """ rows = [] for b in self.basis(): @@ -1199,12 +1185,10 @@ def _compute_atkin_lehner_matrix(self, d): INPUT: - - ``d`` (int) -- an integer that divides the level. + - ``d`` -- integer that divides the level - OUTPUT: - - (matrix) The matrix of the operator `W_d` with respect to - the standard basis. + OUTPUT: the matrix of the operator `W_d` with respect to the standard + basis EXAMPLES: An example at level 29:: @@ -1409,17 +1393,16 @@ def cuspidal_submodule(self): def _degeneracy_raising_matrix(self, M, t): r""" - Return the matrix of the level-raising degeneracy map from self to M, + Return the matrix of the level-raising degeneracy map from ``self`` to M, of index t. This is calculated by composing the level-raising matrix for `t = 1` with a Hecke operator. INPUT: - - ``M`` (int) -- a space of modular symbols whose level is an integer - multiple of the level of self + - ``M`` -- integer; a space of modular symbols whose level is an + integer multiple of the level of ``self`` - - ``t`` (int) -- a positive integer dividing the quotient of the two - levels. + - ``t`` -- positive integer dividing the quotient of the two levels OUTPUT: @@ -1465,7 +1448,7 @@ def _degeneracy_raising_matrix_1(self, M): Return the matrix of the degeneracy map to the given level (which must be a multiple of the level of self). - .. note:: + .. NOTE:: Not implemented in the base class, only in the derived classes. @@ -1479,21 +1462,21 @@ def _degeneracy_raising_matrix_1(self, M): def _degeneracy_lowering_matrix(self, M, t): r""" - Return the matrix of the level-lowering degeneracy map from self to M. + Return the matrix of the level-lowering degeneracy map from ``self`` to M. INPUT: - ``M`` -- a modular symbols space whose level divides the level of - self + ``self`` - - ``t`` (int) -- a positive integer dividing the quotient of the - levels. + - ``t`` -- integer; a positive integer dividing the quotient of the + levels OUTPUT: - (matrix) The matrix of the degeneracy map from this space to the space + The matrix of the degeneracy map from this space to the space `M` of index `t`, where `t` is a divisor of the quotient of the levels - of self and `M`. + of ``self`` and `M`. EXAMPLES:: @@ -1516,9 +1499,7 @@ def rank(self): """ Return the rank of this modular symbols ambient space. - OUTPUT: - - (int) The rank of this space of modular symbols. + OUTPUT: integer; the rank of this space of modular symbols EXAMPLES:: @@ -1564,19 +1545,15 @@ def eisenstein_submodule(self): def element(self, x): """ - Creates and returns an element of self from a modular symbol, if + Create and return an element of ``self`` from a modular symbol, if possible. INPUT: + - ``x`` -- an object of one of the following types: + ModularSymbol, ManinSymbol - - ``x`` -- an object of one of the following types: - ModularSymbol, ManinSymbol. - - - OUTPUT: - - ModularSymbol - a modular symbol with parent self. + OUTPUT: ModularSymbol - a modular symbol with parent self EXAMPLES:: @@ -1637,7 +1614,7 @@ def dual_star_involution_matrix(self): def factorization(self): r""" Return a list of pairs `(S,e)` where `S` is spaces - of modular symbols and self is isomorphic to the direct sum of the + of modular symbols and ``self`` is isomorphic to the direct sum of the `S^e` as a module over the *anemic* Hecke algebra adjoin the star involution. The cuspidal `S` are all simple, but the Eisenstein factors need not be simple. @@ -1800,7 +1777,7 @@ def factorization(self): def is_cuspidal(self): r""" - Return True if this space is cuspidal, else False. + Return ``True`` if this space is cuspidal, else ``False``. EXAMPLES:: @@ -1823,7 +1800,7 @@ def is_cuspidal(self): def is_eisenstein(self): r""" - Return True if this space is Eisenstein, else False. + Return ``True`` if this space is Eisenstein, else ``False``. EXAMPLES:: @@ -1849,11 +1826,8 @@ def manin_symbols_basis(self): A list of Manin symbols that form a basis for the ambient space ``self``. - OUTPUT: - - - ``list`` -- a list of 2-tuples (if the weight is 2) - or 3-tuples, which represent the Manin symbols basis for self. - + OUTPUT: list of 2-tuples (if the weight is 2) or 3-tuples, which + represent the Manin symbols basis for ``self`` EXAMPLES:: @@ -1927,7 +1901,7 @@ def modular_symbols_of_sign(self, sign): INPUT: - - ``sign`` (int) -- A sign (`+1`, `-1` or `0`). + - ``sign`` -- integer; a sign (`+1`, `-1` or `0`) OUTPUT: @@ -1958,7 +1932,7 @@ def modular_symbols_of_weight(self, k): INPUT: - - ``k`` (int) -- A positive integer. + - ``k`` -- positive integer OUTPUT: @@ -1978,21 +1952,17 @@ def modular_symbols_of_weight(self, k): def _compute_sign_submodule(self, sign, compute_dual=True): r""" - Return the subspace of self that is fixed under the star + Return the subspace of ``self`` that is fixed under the star involution. INPUT: + - ``sign`` -- integer (either -1 or +1) - - ``sign`` -- int (either -1 or +1) - - - ``compute_dual`` -- bool (default: ``True``) also - compute dual subspace. This are useful for many algorithms. - + - ``compute_dual`` -- boolean (default: ``True``); also + compute dual subspace. This is useful for many algorithms. - OUTPUT: - - A subspace of modular symbols + OUTPUT: a subspace of modular symbols EXAMPLES:: @@ -2048,12 +2018,9 @@ def _compute_diamond_matrix(self, d): INPUT: - - `d` -- integer + - ``d`` -- integer - OUTPUT: - - - ``matrix`` -- the matrix of the diamond bracket operator - on this space. + OUTPUT: the matrix of the diamond bracket operator on this space EXAMPLES:: @@ -2093,20 +2060,17 @@ def submodule(self, M, dual_free_module=None, check=True): INPUT: + - ``M`` -- either a submodule of this ambient free module, or + generators for a submodule - - ``M`` -- either a submodule of this ambient free module, or - generators for a submodule; - - - ``dual_free_module`` (bool, default None) -- this may be - useful to speed up certain calculations; it is the - corresponding submodule of the ambient dual module; + - ``dual_free_module`` -- boolean (default: ``None``); this may be + useful to speed up certain calculations; it is the corresponding + submodule of the ambient dual module; - - ``check`` (bool, default: ``True``) -- if True, check that `M` is - a submodule, i.e. is invariant under all Hecke operators. + - ``check`` -- boolean (default: ``True``); if ``True``, check that `M` + is a submodule, i.e. is invariant under all Hecke operators - OUTPUT: - - A subspace of this modular symbol space. + OUTPUT: a subspace of this modular symbol space EXAMPLES:: @@ -2122,7 +2086,7 @@ def submodule(self, M, dual_free_module=None, check=True): sage: M.submodule([M.0 - 1/5*M.2]) Modular Symbols subspace of dimension 1 of Modular Symbols space of dimension 3 for Gamma_0(11) of weight 2 with sign 0 over Rational Field - .. note:: + .. NOTE:: It would make more sense to only check that `M` is invariant under the Hecke operators with index coprime to the level. @@ -2146,9 +2110,9 @@ def twisted_winding_element(self, i, eps): INPUT: - - ``i`` (int) -- an integer, `0\le i\le k-2` where `k` is the weight. + - ``i`` -- integer; `0\le i\le k-2` where `k` is the weight - - ``eps`` (character) -- a Dirichlet character + - ``eps`` -- character; a Dirichlet character OUTPUT: @@ -2158,7 +2122,7 @@ def twisted_winding_element(self, i, eps): \sum_{a \in (\ZZ/m\ZZ)^\times} \varepsilon(a) * [ i, 0, a/m ]. - .. note:: + .. NOTE:: This will only work if the base ring of the modular symbol space contains the character values. @@ -2190,13 +2154,12 @@ def integral_structure(self, algorithm='default'): INPUT: + - ``algorithm`` -- string (default: ``'default'``, choose + heuristically) - - ``algorithm`` -- string (default: 'default', choose - heuristically) - - - ``'pari'`` -- use pari for the HNF computation + - ``'pari'`` -- use pari for the HNF computation - - ``'padic'`` -- use p-adic algorithm (only good for + - ``'padic'`` -- use `p`-adic algorithm (only good for dense case) @@ -2306,17 +2269,12 @@ class of cuspidal newforms in this ambient space. INPUT: - - - ``v`` -- list of positive integers - + - ``v`` -- list of positive integers OUTPUT: - - - ``list`` -- of pairs (E, x), where E\*x is a vector - with entries the eigenvalues `a_n` for - `n \in v`. - + List of pairs (E, x), where ``E*x`` is a vector with entries the + eigenvalues `a_n` for `n \in v`. EXAMPLES:: @@ -2430,7 +2388,7 @@ def _pari_pairing(self): E\colon M \times P \to K. - OUTPUT: The matrix of the bilinear map `E`. + OUTPUT: the matrix of the bilinear map `E` This is currently only implemented for spaces of modular symbols of trivial character. @@ -2489,7 +2447,7 @@ def _pari_tensor(self): T \in P \otimes_K M. - OUTPUT: The matrix of the element `T \in P \otimes_K M`. + OUTPUT: the matrix of the element `T \in P \otimes_K M`. This is the inverse of the matrix returned by :meth:`_pari_pairing`. @@ -2534,15 +2492,13 @@ class ModularSymbolsAmbient_wtk_g0(ModularSymbolsAmbient): INPUT: + - ``N`` -- integer; the level - - ``N`` -- int, the level - - - ``k`` -- integer weight = 2. - - - ``sign`` -- int, either -1, 0, or 1 + - ``k`` -- integer; weight = 2 - - ``F`` -- field + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- field EXAMPLES:: @@ -2567,15 +2523,13 @@ def __init__(self, N, k, sign, F, custom_init=None, category=None): INPUT: + - ``N`` -- integer; the level - - ``N`` -- int, the level + - ``k`` -- integer; weight = 2 - - ``k`` -- integer weight = 2. - - - ``sign`` -- int, either -1, 0, or 1 - - - ``F`` -- field + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- field EXAMPLES:: @@ -2668,12 +2622,10 @@ def _degeneracy_raising_matrix_1(self, M): INPUT: - - ``M`` -- A space of Gamma0 modular symbols of the same weight as - self, with level an integer multiple of the level of self. + - ``M`` -- a space of Gamma0 modular symbols of the same weight as + ``self``, with level an integer multiple of the level of ``self`` - OUTPUT: - - (matrix) The matrix of the degeneracy raising map to `M`. + OUTPUT: the matrix of the degeneracy raising map to `M` EXAMPLES:: @@ -2789,15 +2741,11 @@ def _hecke_images(self, i, v): INPUT: + - ``i`` -- nonnegative integer - - ``i`` -- nonnegative integer - - - ``v`` -- a list of positive integer - + - ``v`` -- list of positive integer - OUTPUT: - - - ``matrix`` -- whose rows are the Hecke images + OUTPUT: ``matrix`` -- whose rows are the Hecke images EXAMPLES:: @@ -2865,10 +2813,9 @@ class ModularSymbolsAmbient_wt2_g0(ModularSymbolsAmbient_wtk_g0): INPUT: - - ``N`` -- int, the level - - - ``sign`` -- int, either -1, 0, or 1 + - ``N`` -- integer; the level + - ``sign`` -- integer; either -1, 0, or 1 OUTPUT: @@ -2882,14 +2829,13 @@ class ModularSymbolsAmbient_wt2_g0(ModularSymbolsAmbient_wtk_g0): """ def __init__(self, N, sign, F, custom_init=None, category=None): """ - Initialize a space of modular symbols. INPUT: + Initialize a space of modular symbols. INPUT: - - ``N`` -- int, the level - - - ``sign`` -- int, either -1, 0, or 1 + - ``N`` -- integer; the level + - ``sign`` -- integer; either -1, 0, or 1 OUTPUT: @@ -3060,11 +3006,9 @@ def _hecke_image_of_ith_basis_vector(self, n, i): INPUT: - - ``n`` -- an integer which should be prime. + - ``n`` -- integer which should be prime - OUTPUT: - - - ``modular symbol`` -- element of this ambient space + OUTPUT: ``modular symbol`` -- element of this ambient space EXAMPLES:: @@ -3091,17 +3035,11 @@ def _hecke_images(self, i, v): INPUT: + - ``i`` -- nonnegative integer - - ``i`` -- nonnegative integer - - - ``v`` -- a list of positive integer - - - OUTPUT: - - - - ``matrix`` -- whose rows are the Hecke images + - ``v`` -- list of positive integer + OUTPUT: matrix whose rows are the Hecke images EXAMPLES:: @@ -3129,15 +3067,13 @@ class ModularSymbolsAmbient_wtk_g1(ModularSymbolsAmbient): r""" INPUT: + - ``level`` -- integer; the level - - ``level`` -- int, the level - - - ``weight`` -- int, the weight = 2 - - - ``sign`` -- int, either -1, 0, or 1 + - ``weight`` -- integer; the weight = 2 - - ``F`` -- field + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- field EXAMPLES:: @@ -3158,15 +3094,13 @@ def __init__(self, level, weight, sign, F, custom_init=None, category=None): INPUT: + - ``level`` -- integer; the level - - ``level`` -- int, the level - - - ``weight`` -- int, the weight = 2 - - - ``sign`` -- int, either -1, 0, or 1 + - ``weight`` -- integer; the weight = 2 - - ``F`` -- field + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- field EXAMPLES:: @@ -3375,16 +3309,13 @@ def __init__(self, group, weight, sign, F, custom_init=None, category=None): INPUT: + - ``group`` -- a congruence subgroup `\Gamma_H(N)` - - ``group`` -- a congruence subgroup - `\Gamma_H(N)`. + - ``weight`` -- integer; the weight = 2 - - ``weight`` -- int, the weight = 2 - - - ``sign`` -- int, either -1, 0, or 1 - - - ``F`` -- field + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- field EXAMPLES:: @@ -3431,7 +3362,6 @@ def _cuspidal_submodule_dimension_formula(self): sage: ModularSymbols(GammaH(15,[4]),2)._cuspidal_submodule_dimension_formula() is None True - """ return None @@ -3527,17 +3457,15 @@ def __init__(self, eps, weight, sign, base_ring, custom_init=None, category=None INPUT: + - ``eps`` -- dirichlet.DirichletCharacter, the + "Nebentypus" character - - ``eps`` -- dirichlet.DirichletCharacter, the - "Nebentypus" character. - - - ``weight`` -- int, the weight = 2 - - - ``sign`` -- int, either -1, 0, or 1 + - ``weight`` -- integer; the weight = 2 - - ``base_ring`` -- the base ring. It must be possible to change the ring - of the character to this base ring (not always canonically). + - ``sign`` -- integer; either -1, 0, or 1 + - ``base_ring`` -- the base ring; it must be possible to change the ring + of the character to this base ring (not always canonically) EXAMPLES:: @@ -3640,20 +3568,18 @@ def _matrix_of_operator_on_modular_symbols(self, codomain, R, character_twist=Fa r""" INPUT: + - ``self`` -- this space of modular symbols - - ``self`` -- this space of modular symbols - - - ``codomain`` -- space of modular symbols - - - ``R`` -- list of lists [a,b,c,d] of length 4, which - we view as elements of GL_2(Q). + - ``codomain`` -- space of modular symbols + - ``R`` -- list of lists [a,b,c,d] of length 4, which + we view as elements of GL_2(Q) OUTPUT: a matrix, which represents the operator .. MATH:: - x \mapsto \sum_{g in R} g.x + x \mapsto \sum_{g in R} g.x, where g.x is the formal linear fractional transformation on modular @@ -3689,14 +3615,14 @@ def _degeneracy_raising_matrix_1(self, M): r""" Return the matrix of the degeneracy raising map to ``M``, which should be a space of modular symbols with level a multiple of the level of - self and with compatible character. + ``self`` and with compatible character. INPUT: - ``M`` -- a space of modular symbols with character, whose level - should be an integer multiple of the level of self, and whose + should be an integer multiple of the level of ``self``, and whose character should be the Dirichlet character at that level obtained by - extending the character of self. + extending the character of ``self``. The input is *not* sanity-checked in any way -- use with care! @@ -3805,7 +3731,7 @@ def modular_symbols_of_level(self, N): INPUT: - - ``N`` (int) -- a positive integer. + - ``N`` -- positive integer OUTPUT: @@ -3837,7 +3763,7 @@ def modular_symbols_of_sign(self, sign): INPUT: - - ``sign`` (int) -- A sign (`+1`, `-1` or `0`). + - ``sign`` -- integer; a sign (`+1`, `-1` or `0`) OUTPUT: @@ -3856,7 +3782,6 @@ def modular_symbols_of_sign(self, sign): Modular Symbols space of dimension 0 and level 5, weight 2, character [zeta4], sign 1, over Cyclotomic Field of order 4 and degree 2 sage: M.modular_symbols_of_sign(-1) Modular Symbols space of dimension 0 and level 5, weight 2, character [zeta4], sign -1, over Cyclotomic Field of order 4 and degree 2 - """ return modsym.ModularSymbols(self.character(), self.weight(), sign, self.base_ring()) @@ -3868,7 +3793,7 @@ def modular_symbols_of_weight(self, k): INPUT: - - ``k`` (int) -- A positive integer. + - ``k`` -- positive integer OUTPUT: @@ -3897,11 +3822,9 @@ def _hecke_images(self, i, v): - ``i`` -- nonnegative integer - - ``v`` -- a list of positive integer - - OUTPUT: + - ``v`` -- list of positive integer - - ``matrix`` -- whose rows are the Hecke images + OUTPUT: ``matrix`` -- whose rows are the Hecke images EXAMPLES:: diff --git a/src/sage/modular/modsym/boundary.py b/src/sage/modular/modsym/boundary.py index 093ba6a594f..16241c843aa 100644 --- a/src/sage/modular/modsym/boundary.py +++ b/src/sage/modular/modsym/boundary.py @@ -49,7 +49,7 @@ which means this class must vanish. Notice that this cannot be used to show that `[(1,0)]` or `[(0,1)]` is 0. -.. note:: +.. NOTE:: Special care must be taken when working with the images of the cusps 0 and `\infty` in `B_k(G)`. For all cusps *except* 0 and `\infty`, multiplying the @@ -64,7 +64,7 @@ - `[(1,0)] = \sigma \cdot [(-1,0)]` and `[(1,0)] = (-1)^k [(-1,0)]`, so `[(1,0)] = 0` whenever `\sigma \ne (-1)^k`. -.. note:: +.. NOTE:: For all the spaces of boundary symbols below, no work is done to determine the cusps for G at creation time. Instead, cusps are added as they are @@ -114,13 +114,11 @@ def __init__(self, parent, x): INPUT: + - ``parent`` -- BoundarySpace; a space of boundary + modular symbols - - ``parent`` -- BoundarySpace; a space of boundary - modular symbols - - - ``x`` -- a dict with integer keys and values in the - base field of parent. - + - ``x`` -- dictionary with integer keys and values in the + base field of parent EXAMPLES:: @@ -138,8 +136,8 @@ def __init__(self, parent, x): def coordinate_vector(self): r""" - Return self as a vector on the QQ-vector space with basis - self.parent()._known_cusps(). + Return ``self`` as a vector on the `\QQ`-vector space with basis + ``self.parent()._known_cusps()``. EXAMPLES:: @@ -180,7 +178,7 @@ def _repr_(self): def _add_(self, other): """ - Return self + other. Assumes that other is a BoundarySpaceElement. + Return ``self + other``. Assumes that other is a BoundarySpaceElement. EXAMPLES:: @@ -201,7 +199,7 @@ def _add_(self, other): def _sub_(self, other): """ - Return self - other. Assumes that other is a BoundarySpaceElement. + Return ``self - other``. Assumes that other is a BoundarySpaceElement. EXAMPLES:: @@ -222,10 +220,10 @@ def _sub_(self, other): def _rmul_(self, other): r""" - Return self \* other. + Return ``self * other``. Assumes that other can be coerced into - self.parent().base_ring(). + ``self.parent().base_ring()``. EXAMPLES:: @@ -243,10 +241,10 @@ def _rmul_(self, other): def _lmul_(self, other): r""" - Return other \* self. + Return ``other * self``. Assumes that other can be coerced into - self.parent().base_ring(). + ``self.parent().base_ring()``. EXAMPLES:: @@ -294,17 +292,14 @@ def __init__(self, INPUT: + - ``weight`` -- integer; the weight - - ``weight`` -- int, the weight - - - ``group`` -- arithgroup.congroup_generic.CongruenceSubgroup, a congruence - subgroup. + - ``group`` -- arithgroup.congroup_generic.CongruenceSubgroup, a + congruence subgroup - - ``sign`` -- int, either -1, 0, or 1 - - - ``base_ring`` -- rings.Ring (defaults to the - rational numbers) + - ``sign`` -- integer; either -1, 0, or 1 + - ``base_ring`` -- rings.Ring (defaults to the rational numbers) EXAMPLES:: @@ -596,7 +591,6 @@ def _cusp_index(self, cusp): - ``-2`` if ``cusp`` is equivalent to a cusp that's known to vanish from the relations in this space. - EXAMPLES:: sage: B = ModularSymbols(Gamma0(21), 4).boundary_space() @@ -624,15 +618,13 @@ def __init__(self, level, weight, sign, F): INPUT: + - ``level`` -- integer; the level - - ``level`` -- int, the level - - - ``weight`` -- integer weight = 2. + - ``weight`` -- integer; weight = 2 - - ``sign`` -- int, either -1, 0, or 1 - - - ``F`` -- field + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- field EXAMPLES:: @@ -768,14 +760,13 @@ def __init__(self, level, weight, sign, F): INPUT: + - ``level`` -- integer; the level - - ``level`` -- int, the level - - - ``weight`` -- int, the weight = 2 + - ``weight`` -- integer; the weight = 2 - - ``sign`` -- int, either -1, 0, or 1 + - ``sign`` -- integer; either -1, 0, or 1 - - ``F`` -- base ring + - ``F`` -- base ring EXAMPLES:: @@ -969,15 +960,13 @@ def __init__(self, group, weight, sign, F): INPUT: + - ``group`` -- congruence subgroup Gamma_H(N) - - ``group`` -- congruence subgroup Gamma_H(N). - - - ``weight`` -- int, the weight = 2 + - ``weight`` -- integer; the weight = 2 - - ``sign`` -- int, either -1, 0, or 1 - - - ``F`` -- base ring + - ``sign`` -- integer; either -1, 0, or 1 + - ``F`` -- base ring EXAMPLES:: @@ -1022,8 +1011,8 @@ def _repr_(self): def _is_equiv(self, c1, c2): """ - Return a pair of the form (b, t), where b is True if c1 and c2 are - equivalent cusps for self, and False otherwise, and t gives extra + Return a pair of the form (b, t), where b is ``True`` if c1 and c2 are + equivalent cusps for ``self``, and ``False`` otherwise, and t gives extra information about the equivalence between c1 and c2. EXAMPLES:: @@ -1223,14 +1212,12 @@ def __init__(self, eps, weight, sign=0): INPUT: + - ``eps`` -- dirichlet.DirichletCharacter, the + "Nebentypus" character - - ``eps`` -- dirichlet.DirichletCharacter, the - "Nebentypus" character. - - - ``weight`` -- int, the weight = 2 - - - ``sign`` -- int, either -1, 0, or 1 + - ``weight`` -- integer; the weight = 2 + - ``sign`` -- integer; either -1, 0, or 1 EXAMPLES:: @@ -1272,9 +1259,9 @@ def _repr_(self): def _is_equiv(self, c1, c2): """ - Return a pair (b, t), where b is True if c1 and c2 are equivalent - cusps for self, and False otherwise, and t gives extra information - about the equivalence of c1 and c2. + Return a pair (b, t), where b is ``True`` if c1 and c2 are equivalent + cusps for ``self``, and ``False`` otherwise, and t gives extra + information about the equivalence of c1 and c2. EXAMPLES:: diff --git a/src/sage/modular/modsym/element.py b/src/sage/modular/modsym/element.py index 21b1ecb181b..9386ebd0d11 100644 --- a/src/sage/modular/modsym/element.py +++ b/src/sage/modular/modsym/element.py @@ -31,7 +31,7 @@ def is_ModularSymbolsElement(x) -> bool: r""" - Return True if x is an element of a modular symbols space. + Return ``True`` if x is an element of a modular symbols space. EXAMPLES:: @@ -51,23 +51,22 @@ def is_ModularSymbolsElement(x) -> bool: return isinstance(x, ModularSymbolsElement) -def set_modsym_print_mode(mode="manin"): +def set_modsym_print_mode(mode='manin'): r""" Set the mode for printing of elements of modular symbols spaces. INPUT: - - ``mode`` -- a string. The possibilities are as - follows: + - ``mode`` -- string; the possibilities are as follows: - - ``'manin'`` -- (the default) formal sums of Manin - symbols [P(X,Y),(u,v)] + - ``'manin'`` -- (the default) formal sums of Manin + symbols [P(X,Y),(u,v)] - - ``'modular'`` -- formal sums of Modular symbols - P(X,Y)\*alpha,beta, where alpha and beta are cusps + - ``'modular'`` -- formal sums of Modular symbols + P(X,Y)\*alpha,beta, where alpha and beta are cusps - - ``'vector'`` -- as vectors on the basis for the - ambient space + - ``'vector'`` -- as vectors on the basis for the + ambient space OUTPUT: none @@ -107,8 +106,8 @@ def __init__(self, parent, x, check=True): - ``parent`` -- a space of modular symbols - ``x`` -- a free module element that represents the modular - symbol in terms of a basis for the ambient space (not in - terms of a basis for parent!) + symbol in terms of a basis for the ambient space (not in + terms of a basis for parent!) EXAMPLES:: @@ -132,7 +131,7 @@ def __init__(self, parent, x, check=True): def _repr_(self): r""" - String representation of self. The output will depend on the global + String representation of ``self``. The output will depend on the global modular symbols print mode setting controlled by the function ``set_modsym_print_mode``. @@ -157,7 +156,8 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation of self. The output will be determined by the print mode setting set using ``set_modsym_print_mode``. + LaTeX representation of ``self``. The output will be determined by the + print mode setting set using ``set_modsym_print_mode``. EXAMPLES:: @@ -186,7 +186,7 @@ def _latex_(self): def _add_(self, right): r""" - Sum of self and other. + Sum of ``self`` and ``other``. EXAMPLES:: @@ -200,7 +200,7 @@ def _add_(self, right): def _rmul_(self, other): r""" - Right-multiply self by other. + Right-multiply ``self`` by ``other``. EXAMPLES:: @@ -219,7 +219,7 @@ def _rmul_(self, other): def _lmul_(self, left): r""" - Left-multiply self by other. + Left-multiply ``self`` by ``other``. EXAMPLES:: @@ -252,7 +252,7 @@ def _neg_(self): def _sub_(self, other): r""" - Subtract other from self. + Subtract ``other`` from ``self``. EXAMPLES:: @@ -272,7 +272,8 @@ def _sub_(self, other): def list(self): r""" - Return a list of the coordinates of self in terms of a basis for the ambient space. + Return a list of the coordinates of ``self`` in terms of a basis for + the ambient space. EXAMPLES:: @@ -283,7 +284,7 @@ def list(self): def manin_symbol_rep(self): """ - Return a representation of self as a formal sum of Manin symbols. + Return a representation of ``self`` as a formal sum of Manin symbols. EXAMPLES:: diff --git a/src/sage/modular/modsym/g1list.py b/src/sage/modular/modsym/g1list.py index 4485a52814a..23ad499f3ad 100644 --- a/src/sage/modular/modsym/g1list.py +++ b/src/sage/modular/modsym/g1list.py @@ -51,7 +51,7 @@ def __init__(self, N): def __richcmp__(self, other, op): r""" - Compare self to other. + Compare ``self`` to ``other``. EXAMPLES:: @@ -120,7 +120,7 @@ def normalize(self, u, v): `\Gamma_0` (where the problem is rather harder). This will only make sense if `{\rm gcd}(u, v, N) = 1`; otherwise the - output will not be an element of self. + output will not be an element of ``self``. EXAMPLES:: diff --git a/src/sage/modular/modsym/ghlist.py b/src/sage/modular/modsym/ghlist.py index 62989e22105..916374a97b2 100644 --- a/src/sage/modular/modsym/ghlist.py +++ b/src/sage/modular/modsym/ghlist.py @@ -93,7 +93,7 @@ def __len__(self): def __repr__(self): """ - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -122,7 +122,7 @@ def normalize(self, u, v): is equivalent to `(u', v')`. This will only make sense if `{\rm gcd}(u, v, N) = 1`; otherwise the - output will not be an element of self. + output will not be an element of ``self``. EXAMPLES:: diff --git a/src/sage/modular/modsym/hecke_operator.py b/src/sage/modular/modsym/hecke_operator.py index 818de55e97e..b12c5020df7 100644 --- a/src/sage/modular/modsym/hecke_operator.py +++ b/src/sage/modular/modsym/hecke_operator.py @@ -23,7 +23,7 @@ def apply_sparse(self, x): """ Return the image of ``x`` under ``self``. - If ``x`` is not in ``self.domain()``, raise a :class:`TypeError`. + If ``x`` is not in ``self.domain()``, raise a :exc:`TypeError`. EXAMPLES:: diff --git a/src/sage/modular/modsym/heilbronn.pyx b/src/sage/modular/modsym/heilbronn.pyx index c9c7a93b8a0..a14f2e6ccac 100644 --- a/src/sage/modular/modsym/heilbronn.pyx +++ b/src/sage/modular/modsym/heilbronn.pyx @@ -104,7 +104,7 @@ cdef class Heilbronn: (This function is automatically called during initialization.) - .. note:: + .. NOTE:: This function must be overridden by all derived classes! @@ -173,9 +173,9 @@ cdef class Heilbronn: r""" INPUT: - - ``u``, ``v``, ``N`` -- integers + - ``u``, ``v``, ``N`` -- integers - - ``a``, ``b`` -- preallocated int arrays of the length of ``self`` + - ``a``, ``b`` -- preallocated integer arrays of the length of ``self`` OUTPUT: sets the entries of `a`, `b` @@ -210,10 +210,10 @@ cdef class Heilbronn: r""" INPUT: - - ``ans`` -- ``fmpz_poly_t*``; pre-allocated an - initialized array of ``self.length`` ``fmpz_poly_t``s - - ``i`` -- integer - - ``k`` -- integer + - ``ans`` -- ``fmpz_poly_t*``; pre-allocated an + initialized array of ``self.length`` ``fmpz_poly_t``s + - ``i`` -- integer + - ``k`` -- integer OUTPUT: sets entries of ``ans`` """ @@ -230,7 +230,7 @@ cdef class Heilbronn: Return a list of pairs `((c,d),m)`, which is obtained as follows: 1) Compute the images `(a,b)` of the vector `(u,v) \pmod N` acted on by - each of the HeilbronnCremona matrices in self. + each of the HeilbronnCremona matrices in ``self``. 2) Reduce each `(a,b)` to canonical form `(c,d)` using ``p1normalize``. @@ -522,11 +522,10 @@ def hecke_images_gamma0_weight2(int u, int v, int N, indices, R): INPUT: - ``u``, ``v``, ``N`` -- integers so that `\gcd(u,v,N) = 1` - - ``indices`` -- a list of positive integers + - ``indices`` -- list of positive integers - ``R`` -- matrix over `\QQ` that writes each elements of `\textnormal{P1} = \textnormal{P1List}(N)` in terms of a - subset of `\textnormal{P1}`. - + subset of `\textnormal{P1}` OUTPUT: a dense matrix whose columns are the images `T_n(x)` for `n` in indices and `x` the Manin symbol `(u,v)`, expressed @@ -549,7 +548,6 @@ def hecke_images_gamma0_weight2(int u, int v, int N, indices, R): sage: D = N.decomposition() sage: D[1].q_eigenform(10, 'a') # indirect doctest q + 4*q^2 + 2*q^3 + 6*q^5 + q^6 + 5*q^7 + 6*q^8 + q^9 + O(q^10) - """ cdef p1list.P1List P1 = p1list.P1List(N) @@ -648,13 +646,12 @@ def hecke_images_nonquad_character_weight2(int u, int v, int N, indices, chi, R) INPUT: - ``u``, ``v``, ``N`` -- integers so that `\gcd(u,v,N) = 1` - - ``indices`` -- a list of positive integers + - ``indices`` -- list of positive integers - ``chi`` -- a Dirichlet character that takes values - in a nontrivial extension of `\QQ`. + in a nontrivial extension of `\QQ` - ``R`` -- matrix over `\QQ` that writes each elements of `\textnormal{P1} = \textnormal{P1List}(N)` in terms of a - subset of `\textnormal{P1}`. - + subset of `\textnormal{P1}` OUTPUT: a dense matrix with entries in the field `\QQ(\chi)` (the values of `\chi`) whose columns are the images `T_n(x)` for `n` in @@ -754,12 +751,11 @@ def hecke_images_quad_character_weight2(int u, int v, int N, indices, chi, R): INPUT: - ``u``, ``v``, ``N`` -- integers so that `\gcd(u,v,N) = 1` - - ``indices`` -- a list of positive integers + - ``indices`` -- list of positive integers - ``chi`` -- a Dirichlet character that takes values in `\QQ` - ``R`` -- matrix over `\QQ(\chi)` that writes each elements of `\textnormal{P1} = \textnormal{P1List}(N)` in terms of a subset - of `\textnormal{P1}`. - + of `\textnormal{P1}` OUTPUT: a dense matrix with entries in the rational field `\QQ` (the values of `\chi`) whose columns are the images `T_n(x)` for `n` in @@ -852,13 +848,13 @@ def hecke_images_gamma0_weight_k(int u, int v, int i, int N, int k, indices, R): r""" INPUT: - - ``u``, ``v``, ``N`` -- integers so that `\gcd(u,v,N) = 1` - - ``i`` -- integer with `0 \le i \le k-2` - - ``k`` -- weight - - ``indices`` -- a list of positive integers - - ``R`` -- matrix over `\QQ` that writes each elements of - `\textnormal{P1} = \textnormal{P1List}(N)` in terms of a - subset of `\textnormal{P1}`. + - ``u``, ``v``, ``N`` -- integers so that `\gcd(u,v,N) = 1` + - ``i`` -- integer with `0 \le i \le k-2` + - ``k`` -- weight + - ``indices`` -- list of positive integers + - ``R`` -- matrix over `\QQ` that writes each elements of + `\textnormal{P1} = \textnormal{P1List}(N)` in terms of a + subset of `\textnormal{P1}` OUTPUT: a dense matrix with rational entries whose columns are the images `T_n(x)` for `n` in indices and `x` the Manin symbol diff --git a/src/sage/modular/modsym/manin_symbol.pyx b/src/sage/modular/modsym/manin_symbol.pyx index 434aa370e18..7a98b5d1a40 100644 --- a/src/sage/modular/modsym/manin_symbol.pyx +++ b/src/sage/modular/modsym/manin_symbol.pyx @@ -92,7 +92,6 @@ cdef class ManinSymbol(Element): sage: s = ManinSymbol(m,(2,2,3)) sage: s.parent() Manin Symbol List of weight 8 for Gamma0(5) - """ def __init__(self, parent, t): r""" @@ -118,7 +117,6 @@ cdef class ManinSymbol(Element): sage: m = ManinSymbolList_gamma0(5,8) sage: s = ManinSymbol(m,(2,2,3)); s [X^2*Y^4,(2,3)] - """ Element.__init__(self, parent) (i, u, v) = t @@ -138,7 +136,6 @@ cdef class ManinSymbol(Element): sage: s = ManinSymbol(m, (2, 2, 3)) sage: loads(dumps(s)) (2,3) - """ return ManinSymbol, (self.parent(), self.tuple()) @@ -154,7 +151,6 @@ cdef class ManinSymbol(Element): sage: s = ManinSymbol(m,(2,2,3)) sage: loads(dumps(s)) (2,3) - """ self._parent = state['_ManinSymbol__parent'] (self.i, self.u, self.v) = state['_ManinSymbol__t'] @@ -293,7 +289,7 @@ cdef class ManinSymbol(Element): def apply(self, a,b,c,d): """ - Return the image of self under the matrix `[a,b;c,d]`. + Return the image of ``self`` under the matrix `[a,b;c,d]`. Not implemented for raw ManinSymbol objects, only for members of ManinSymbolLists. @@ -342,7 +338,6 @@ cdef class ManinSymbol(Element): [X^2*Y^4,(2,3)] sage: s.lift_to_sl2z() [1, 1, 2, 3] - """ if N is None: N = self.level() @@ -421,7 +416,6 @@ cdef class ManinSymbol(Element): sage: s = ManinSymbol(m,(2,2,3)) sage: s.weight() 8 - """ return self.parent().weight() @@ -437,7 +431,6 @@ cdef class ManinSymbol(Element): sage: s = ManinSymbol(m,(2,2,3)) sage: s.level() 5 - """ return self.parent().level() @@ -456,8 +449,6 @@ cdef class ManinSymbol(Element): sage: s = ManinSymbol(m,(2,2,3)) sage: s.modular_symbol_rep() 144*X^6*{1/3, 1/2} - 384*X^5*Y*{1/3, 1/2} + 424*X^4*Y^2*{1/3, 1/2} - 248*X^3*Y^3*{1/3, 1/2} + 81*X^2*Y^4*{1/3, 1/2} - 14*X*Y^5*{1/3, 1/2} + Y^6*{1/3, 1/2} - - """ # TODO: It would likely be much better to do this slightly more directly from sage.modular.modsym.modular_symbols import ModularSymbol diff --git a/src/sage/modular/modsym/manin_symbol_list.py b/src/sage/modular/modsym/manin_symbol_list.py index f2a26c68303..ebc40022031 100644 --- a/src/sage/modular/modsym/manin_symbol_list.py +++ b/src/sage/modular/modsym/manin_symbol_list.py @@ -165,7 +165,7 @@ def apply(self, j, X): def _apply_S_only_0pm1(self) -> bool: """ - Return True if the coefficient when applying the S relation is + Return ``True`` if the coefficient when applying the S relation is always 0, 1, or -1. This is useful for optimizing code in relation_matrix.py. @@ -311,7 +311,6 @@ def manin_symbol_list(self): ... [X^2,(3,1)], [X^2,(3,2)]] - """ import copy try: @@ -329,11 +328,11 @@ def manin_symbol(self, i): INPUT: - - ``i`` -- integer, a valid index of a symbol in this list + - ``i`` -- integer; a valid index of a symbol in this list OUTPUT: - :class:`ManinSymbol` -- the `i`'th Manin symbol in the list. + :class:`ManinSymbol` -- the `i`-th Manin symbol in the list. EXAMPLES:: @@ -363,7 +362,6 @@ def normalize(self, x): sage: from sage.modular.modsym.manin_symbol_list import ManinSymbolList sage: m = ManinSymbolList(6,P1List(11)) sage: m.normalize((0,6,7)) # not implemented in base class - """ raise NotImplementedError("Only implemented in derived classes") @@ -371,9 +369,7 @@ def weight(self): """ Return the weight of the Manin symbols in this :class:`ManinSymbolList`. - OUTPUT: - - integer -- the weight of the Manin symbols in the list. + OUTPUT: integer; the weight of the Manin symbols in the list EXAMPLES:: @@ -396,7 +392,7 @@ class ManinSymbolList_group(ManinSymbolList): - ``weight`` -- integer weight - ``syms`` -- something with ``normalize`` and ``list`` methods, - e.g. :class:`~sage.modular.modsym.p1list.P1List`. + e.g. :class:`~sage.modular.modsym.p1list.P1List` EXAMPLES:: @@ -415,7 +411,7 @@ def __init__(self, level, weight, syms): - ``weight`` -- integer weight - ``syms`` -- something with ``normalize`` and ``list`` - methods, e.g. :class:`~sage.modular.modsym.p1list.P1List`. + methods, e.g. :class:`~sage.modular.modsym.p1list.P1List` EXAMPLES:: @@ -463,12 +459,12 @@ def apply_S(self, j): INPUT: - - ``j`` -- (int) a symbol index + - ``j`` -- integer; a symbol index OUTPUT: ``(k, s)`` where k is the index of the symbol obtained by acting on the - `j`'th symbol with `S`, and `s` is the parity of the `j`'th symbol + `j`-th symbol with `S`, and `s` is the parity of the `j`-th symbol (a Python ``int``, either 1 or -1). EXAMPLES:: @@ -500,7 +496,7 @@ def apply_S(self, j): def _apply_S_only_0pm1(self): """ - Return True if the coefficient when applying the S relation is + Return ``True`` if the coefficient when applying the S relation is always 0, 1, or -1. This is useful for optimizing code in relation_matrix.py. @@ -518,12 +514,12 @@ def apply_I(self, j): INPUT: - - ``j`` -- (int) a symbol index + - ``j`` -- integer; a symbol index OUTPUT: ``(k, s)`` where k is the index of the symbol obtained by acting on the - `j`'th symbol with `I`, and `s` is the parity of the `j`'th symbol + `j`-th symbol with `I`, and `s` is the parity of the `j`-th symbol (a Python ``int``, either 1 or -1) EXAMPLES:: @@ -557,7 +553,7 @@ def apply_T(self, j): INPUT: - - ``j`` -- (int) a symbol index + - ``j`` -- integer; a symbol index OUTPUT: see documentation for apply() @@ -600,7 +596,7 @@ def apply_TT(self, j): INPUT: - - ``j`` -- (int) a symbol index + - ``j`` -- integer; a symbol index OUTPUT: see documentation for apply() @@ -643,7 +639,7 @@ def apply(self, j, m): INPUT: - - ``j`` -- (int) a symbol index + - ``j`` -- integer; a symbol index - ``m = [a, b, c, d]`` a list of 4 integers, which defines a 2x2 matrix @@ -651,7 +647,7 @@ def apply(self, j, m): a list of pairs `(j_i, \alpha_i)`, where each `\alpha_i` is a nonzero integer, `j_i` is an integer (index of the `j_i`-th Manin symbol), and - `\sum_i \alpha_i\*x_{j_i}` is the image of the j-th Manin symbol under + `\sum_i \alpha_i\*x_{j_i}` is the image of the `j`-th Manin symbol under the right action of the matrix [a,b;c,d]. Here the right action of `g = [a, b; c, d]` on a Manin symbol `[P(X,Y),(u,v)]` is `[P(aX+bY,cX+dY),(u,v)\*g]`. @@ -714,9 +710,9 @@ class ManinSymbolList_gamma0(ManinSymbolList_group): INPUT: - - ``level`` -- (integer): the level. + - ``level`` -- integer; the level - - ``weight`` -- (integer): the weight. + - ``weight`` -- integer; the weight EXAMPLES:: @@ -732,7 +728,7 @@ class ManinSymbolList_gamma0(ManinSymbolList_group): """ def __init__(self, level, weight): """ - Constructor for a ModularSymbolList for Gamma_0(N) + Constructor for a ModularSymbolList for Gamma_0(N). EXAMPLES:: @@ -766,9 +762,9 @@ class ManinSymbolList_gamma1(ManinSymbolList_group): INPUT: - - ``level`` -- (integer): the level. + - ``level`` -- integer; the level - - ``weight`` -- (integer): the weight. + - ``weight`` -- integer; the weight EXAMPLES:: @@ -823,9 +819,9 @@ class ManinSymbolList_gamma_h(ManinSymbolList_group): INPUT: - - ``group`` -- (integer): the congruence subgroup. + - ``group`` -- integer; the congruence subgroup - - ``weight`` -- (integer): the weight. + - ``weight`` -- integer; the weight EXAMPLES:: @@ -865,7 +861,7 @@ def __init__(self, group, weight): def group(self): """ - Return the group associated to self. + Return the group associated to ``self``. EXAMPLES:: @@ -876,7 +872,7 @@ def group(self): def __repr__(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -895,7 +891,7 @@ class ManinSymbolList_character(ManinSymbolList): - ``character`` -- (DirichletCharacter) the Dirichlet character - - ``weight`` -- (integer) the weight + - ``weight`` -- integer; the weight EXAMPLES:: @@ -915,9 +911,9 @@ def __init__(self, character, weight): INPUT: - - ``character`` -- (DirichletCharacter) the Dirichlet character + - ``character`` -- (DirichletCharacter) the Dirichlet character - - ``weight`` -- (integer) the weight + - ``weight`` -- integer; the weight EXAMPLES:: @@ -970,9 +966,7 @@ def level(self): """ Return the level of this :class:`ManinSymbolList`. - OUTPUT: - - ``integer`` -- the level of the symbols in this list. + OUTPUT: integer; the level of the symbols in this list EXAMPLES:: @@ -990,17 +984,16 @@ def apply(self, j, m): INPUT: + - ``j`` -- integer; the index of the symbol to act on - - ``j`` (integer): the index of the symbol to act on. - - - ``m`` (list of ints): `[a,b,c,d]` where `m = [a, b; c, d]` is the matrix to be applied. - + - ``m`` -- list of integers `[a,b,c,d]` where `m = [a, b; c, d]` is the + matrix to be applied OUTPUT: A list of pairs `(j, c_i)`, where each `c_i` is an integer, `j` is an integer (the `j`-th Manin symbol), and the - sum `c_i*x_i` is the image of self under the right action + sum `c_i*x_i` is the image of ``self`` under the right action of the matrix `[a,b;c,d]`. Here the right action of `g = [a,b;c,d]` on a Manin symbol `[P(X,Y),(u,v)]` is by definition `[P(aX+bY,cX+dY),(u,v)*g]`. @@ -1034,13 +1027,13 @@ def apply_S(self, j): INPUT: - - ``j`` -- (integer) a symbol index. + - ``j`` -- integer; a symbol index OUTPUT: ``(k, s)`` where `k` is the index of the symbol obtained by acting - on the `j`'th symbol with `S`, and `s` is the parity of the - `j`'th symbol. + on the `j`-th symbol with `S`, and `s` is the parity of the + `j`-th symbol. EXAMPLES:: @@ -1063,7 +1056,7 @@ def apply_S(self, j): def _apply_S_only_0pm1(self): """ - Return True if the coefficient when applying the S relation is + Return ``True`` if the coefficient when applying the S relation is always 0, 1, or -1. This is useful for optimizing code in relation_matrix.py. @@ -1085,13 +1078,13 @@ def apply_I(self, j): INPUT: - - ``j`` -- (integer) a symbol index + - ``j`` -- integer; a symbol index OUTPUT: ``(k, s)`` where `k` is the index of the symbol obtained by acting - on the `j`'th symbol with `I`, and `s` is the parity of the - `j`'th symbol. + on the `j`-th symbol with `I`, and `s` is the parity of the + `j`-th symbol. EXAMPLES:: @@ -1114,17 +1107,17 @@ def apply_I(self, j): def apply_T(self, j): """ - Apply the matrix `T=[0,1,-1,-1]` to the j-th Manin symbol. + Apply the matrix `T=[0,1,-1,-1]` to the `j`-th Manin symbol. INPUT: - - ``j`` -- (integer) a symbol index. + - ``j`` -- integer; a symbol index OUTPUT: A list of pairs `(j, c_i)`, where each `c_i` is an integer, `j` is an integer (the `j`-th Manin symbol), and the - sum `c_i*x_i` is the image of self under the right action + sum `c_i*x_i` is the image of ``self`` under the right action of the matrix `T`. EXAMPLES:: @@ -1161,13 +1154,13 @@ def apply_TT(self, j): INPUT: - - ``j`` -- (integer) a symbol index + - ``j`` -- integer; a symbol index OUTPUT: A list of pairs `(j, c_i)`, where each `c_i` is an integer, `j` is an integer (the `j`-th Manin symbol), and the - sum `c_i*x_i` is the image of self under the right action + sum `c_i*x_i` is the image of ``self`` under the right action of the matrix `T^2`. EXAMPLES:: @@ -1202,9 +1195,7 @@ def character(self): """ Return the character of this :class:`ManinSymbolList_character` object. - OUTPUT: - - The Dirichlet character of this Manin symbol list. + OUTPUT: the Dirichlet character of this Manin symbol list EXAMPLES:: @@ -1215,7 +1206,6 @@ def character(self): Manin Symbol List of weight 2 for Gamma1(4) with character [-1] sage: m.character() Dirichlet character modulo 4 of conductor 4 mapping 3 |--> -1 - """ return self.__character @@ -1268,7 +1258,7 @@ def normalize(self, x): INPUT: - ``x`` -- 3-tuple of integers ``(i,u,v)``, defining an element of this - list of Manin symbols, which need not be normalized. + list of Manin symbols, which need not be normalized OUTPUT: diff --git a/src/sage/modular/modsym/modsym.py b/src/sage/modular/modsym/modsym.py index 6cb40dae8c0..fb46d0edafa 100644 --- a/src/sage/modular/modsym/modsym.py +++ b/src/sage/modular/modsym/modsym.py @@ -212,17 +212,17 @@ def ModularSymbols(group=1, INPUT: - - ``group`` -- A congruence subgroup or a Dirichlet character eps. - - ``weight`` -- int, the weight, which must be >= 2. - - ``sign`` -- int, The sign of the involution on modular symbols + - ``group`` -- a congruence subgroup or a Dirichlet character eps + - ``weight`` -- integer; the weight, which must be >= 2 + - ``sign`` -- integer; the sign of the involution on modular symbols induced by complex conjugation. The default is 0, which means "no sign", i.e., take the whole space. - ``base_ring`` -- the base ring. Defaults to `\QQ` if no character is given, or to the minimal extension of `\QQ` containing the values of the character. - - ``custom_init`` -- a function that is called with self as input + - ``custom_init`` -- a function that is called with ``self`` as input before any computations are done using self; this could be used - to set a custom modular symbols presentation. If self is + to set a custom modular symbols presentation. If ``self`` is already in the cache and use_cache=True, then this function is not called. diff --git a/src/sage/modular/modsym/modular_symbols.py b/src/sage/modular/modsym/modular_symbols.py index 57dc8f23a2b..3e8a8be156c 100644 --- a/src/sage/modular/modsym/modular_symbols.py +++ b/src/sage/modular/modsym/modular_symbols.py @@ -269,8 +269,8 @@ def apply(self, g): INPUT: - - ``g`` -- a list ``[a,b,c,d]``, corresponding to the 2x2 matrix - `\begin{pmatrix} a & b \\ c & d \end{pmatrix} \in {\rm GL}_2(\QQ)`. + - ``g`` -- list ``[a,b,c,d]``, corresponding to the 2x2 matrix + `\begin{pmatrix} a & b \\ c & d \end{pmatrix} \in {\rm GL}_2(\QQ)` OUTPUT: diff --git a/src/sage/modular/modsym/p1list.pyx b/src/sage/modular/modsym/p1list.pyx index 188e79e6c01..5e48d6b1369 100644 --- a/src/sage/modular/modsym/p1list.pyx +++ b/src/sage/modular/modsym/p1list.pyx @@ -31,28 +31,29 @@ cdef int c_p1_normalize_int(int N, int u, int v, int* uu, int* vv, int* ss, int compute_s) except -1: r""" - Computes the canonical representative of + Compute the canonical representative of `\mathbb{P}^1(\ZZ/N\ZZ)` equivalent to `(u,v)` along with a transforming scalar. INPUT: - - ``N`` -- an integer + - ``N`` -- integer + + - ``u`` -- integer - - ``u`` -- an integer + - ``v`` -- integer - - ``v`` -- an integer + OUTPUT: - OUTPUT: If gcd(u,v,N) = 1, then returns + If `\gcd(u,v,N) = 1`, then returns - - ``uu`` -- an integer + - ``uu`` -- integer - - ``vv`` -- an integer + - ``vv`` -- integer - - ``ss`` -- an integer such that `(ss*uu, ss*vv)` is congruent to - `(u,v)` (mod `N`); + - ``ss`` -- integer such that `(ss*uu, ss*vv)` is congruent to `(u,v)` (mod `N`); - if `\gcd(u,v,N) \not= 1`, returns 0, 0, 0. + If `\gcd(u,v,N) \not= 1`, returns ``0, 0, 0``. If ``compute_s`` is 0, ``s`` is not computed. """ @@ -128,30 +129,29 @@ cdef int c_p1_normalize_int(int N, int u, int v, def p1_normalize_int(N, u, v): r""" - Computes the canonical representative of + Compute the canonical representative of `\mathbb{P}^1(\ZZ/N\ZZ)` equivalent to `(u,v)` along with a transforming scalar. INPUT: + - ``N`` -- integer - - ``N`` -- an integer - - - ``u`` -- an integer - - - ``v`` -- an integer + - ``u`` -- integer + - ``v`` -- integer - OUTPUT: If gcd(u,v,N) = 1, then returns + OUTPUT: + If `\gcd(u,v,N) = 1`, then returns - - ``uu`` -- an integer + - ``uu`` -- integer - - ``vv`` -- an integer + - ``vv`` -- integer - - ``ss`` -- an integer such that `(ss*uu, ss*vv)` is congruent to `(u,v)` (mod `N`); + - ``ss`` -- integer such that `(ss*uu, ss*vv)` is congruent to `(u,v)` (mod `N`); - if `\gcd(u,v,N) \not= 1`, returns 0, 0, 0. + If `\gcd(u,v,N) \not= 1`, returns ``0, 0, 0``. EXAMPLES:: @@ -177,8 +177,7 @@ def p1list_int(int N): INPUT: - - - ``N`` -- integer (the level or modulus). + - ``N`` -- integer (the level or modulus) EXAMPLES:: @@ -270,26 +269,25 @@ cdef int c_p1_normalize_llong(int N, int u, int v, INPUT: + - ``N`` -- integer (the modulus or level) - - ``N`` -- an integer (the modulus or level) - - - ``u`` -- an integer (the first coordinate of (u:v)) + - ``u`` -- integer (the first coordinate of (u:v)) - - ``v`` -- an integer (the second coordinate of (u:v)) + - ``v`` -- integer (the second coordinate of (u:v)) - - ``compute_s`` -- a boolean (int) + - ``compute_s`` -- boolean (int) + OUTPUT: - OUTPUT: If gcd(u,v,N) = 1, then returns - + If `\gcd(u,v,N) = 1`, then returns - - ``uu`` -- an integer + - ``uu`` -- integer - - ``vv`` -- an integer + - ``vv`` -- integer - - ``ss`` -- an integer such that `(ss*uu, ss*vv)` is equivalent to `(u,v)` mod `N`; + - ``ss`` -- integer such that `(ss*uu, ss*vv)` is equivalent to `(u,v)` mod `N` - if `\gcd(u,v,N) \not= 1`, returns 0, 0, 0. + If `\gcd(u,v,N) \not= 1`, returns ``0, 0, 0``. EXAMPLES:: @@ -393,30 +391,29 @@ cdef int c_p1_normalize_llong(int N, int u, int v, def p1_normalize_llong(N, u, v): r""" - Computes the canonical representative of + Compute the canonical representative of `\mathbb{P}^1(\ZZ/N\ZZ)` equivalent to `(u,v)` along with a transforming scalar. INPUT: + - ``N`` -- integer - - ``N`` -- an integer - - - ``u`` -- an integer - - - ``v`` -- an integer + - ``u`` -- integer + - ``v`` -- integer - OUTPUT: If gcd(u,v,N) = 1, then returns + OUTPUT: + If `\gcd(u,v,N) = 1`, then returns - - ``uu`` -- an integer + - ``uu`` -- integer - - ``vv`` -- an integer + - ``vv`` -- integer - - ``ss`` -- an integer such that `(ss*uu, ss*vv)` is equivalent to `(u,v)` mod `N`; + - ``ss`` -- integer such that `(ss*uu, ss*vv)` is equivalent to `(u,v)` mod `N` - if `\gcd(u,v,N) \not= 1`, returns 0, 0, 0. + If `\gcd(u,v,N) \not= 1`, returns ``0, 0, 0``. EXAMPLES:: @@ -443,8 +440,7 @@ def p1list_llong(int N): INPUT: - - - ``N`` -- integer (the level or modulus). + - ``N`` -- integer (the level or modulus) EXAMPLES:: @@ -505,7 +501,7 @@ def p1list(N): INPUT: - - N (integer) -- a positive integer (less than 2^31). + - ``N`` -- integer; a positive integer (less than 2^31) OUTPUT: @@ -532,30 +528,29 @@ def p1list(N): def p1_normalize(int N, int u, int v): r""" - Computes the canonical representative of + Compute the canonical representative of `\mathbb{P}^1(\ZZ/N\ZZ)` equivalent to `(u,v)` along with a transforming scalar. INPUT: + - ``N`` -- integer - - ``N`` -- an integer + - ``u`` -- integer - - ``u`` -- an integer + - ``v`` -- integer - - ``v`` -- an integer - - - OUTPUT: If gcd(u,v,N) = 1, then returns + OUTPUT: + If `\gcd(u,v,N) = 1`, then returns - - ``uu`` -- an integer + - ``uu`` -- integer - - ``vv`` -- an integer + - ``vv`` -- integer - - ``ss`` -- an integer such that `(ss*uu, ss*vv)` is equivalent to `(u,v)` mod `N`; + - ``ss`` -- integer such that `(ss*uu, ss*vv)` is equivalent to `(u,v)` mod `N` - if `\gcd(u,v,N) \not= 1`, returns 0, 0, 0. + If `\gcd(u,v,N) \not= 1`, returns ``0, 0, 0``. EXAMPLES:: @@ -596,17 +591,14 @@ cdef int p1_normalize_xgcdtable(int N, int u, int v, """ INPUT: + - ``N``, ``u``, ``v`` -- integers - - ``N, u, v`` -- integers - - - ``compute_s`` -- do not compute s if compute_s == 0. - - - ``t_g, t_a, t_b`` -- int arrays of + - ``compute_s`` -- do not compute s if ``compute_s == 0`` + - ``t_g``, ``t_a``, ``t_b`` -- integer arrays - OUTPUT: - - - ``uu, vv, ss`` -- reduced representative and normalizing scalar. + OUTPUT: ``uu, vv, ss`` -- reduced representative and normalizing + scalar """ cdef int d, k, g, s, t, min_v, min_t, Ng, vNg if N == 1: @@ -706,11 +698,9 @@ cdef class P1List(): INPUT: - - ``N`` -- positive integer (the modulus or level). - - OUTPUT: + - ``N`` -- positive integer (the modulus or level) - A P1List object representing `\mathbb{P}^1(\ZZ/N\ZZ)`. + OUTPUT: a P1List object representing `\mathbb{P}^1(\ZZ/N\ZZ)` EXAMPLES:: @@ -754,7 +744,7 @@ cdef class P1List(): def __dealloc__(self): """ - Deallocates memory for an object of the class P1List. + Deallocate memory for an object of the class P1List. """ sig_free(self.g) sig_free(self.s) @@ -847,23 +837,22 @@ cdef class P1List(): sage: L = P1List(8) sage: str(L) # indirect doctest 'The projective line over the integers modulo 8' - """ return "The projective line over the integers modulo %s" % self.__N def lift_to_sl2z(self, int i): r""" - Lift the `i`'th element of this P1list to an element of + Lift the `i`-th element of this P1list to an element of `SL(2,\ZZ)`. - If the `i`'th element is `(c,d)`, this function computes and + If the `i`-th element is `(c,d)`, this function computes and returns a list `[a,b, c',d']` that defines a 2x2 matrix with determinant 1 and integer entries, such that `c=c'` (mod `N`) and `d=d'` (mod `N`). INPUT: - - ``i`` -- integer (the index of the element to lift). + - ``i`` -- integer (the index of the element to lift) EXAMPLES:: @@ -896,11 +885,11 @@ cdef class P1List(): def apply_I(self, int i): r""" Return the index of the result of applying the matrix - `I=[-1,0;0,1]` to the `i`'th element of this P1List. + `I=[-1,0;0,1]` to the `i`-th element of this P1List. INPUT: - - ``i`` -- integer (the index of the element to act on). + - ``i`` -- integer (the index of the element to act on) EXAMPLES:: @@ -928,12 +917,11 @@ cdef class P1List(): def apply_S(self, int i): r""" Return the index of the result of applying the matrix - `S=[0,-1;1,0]` to the `i`'th element of this P1List. + `S=[0,-1;1,0]` to the `i`-th element of this P1List. INPUT: - - - ``i`` -- integer (the index of the element to act on). + - ``i`` -- integer (the index of the element to act on) EXAMPLES:: @@ -961,12 +949,11 @@ cdef class P1List(): def apply_T(self, int i): r""" Return the index of the result of applying the matrix - `T=[0,1;-1,-1]` to the `i`'th element of this P1List. + `T=[0,1;-1,-1]` to the `i`-th element of this P1List. INPUT: - - - ``i`` -- integer (the index of the element to act on). + - ``i`` -- integer (the index of the element to act on) EXAMPLES:: @@ -999,14 +986,11 @@ cdef class P1List(): INPUT: - - - ``u, v`` -- integers, with `\gcd(u,v,N)=1`. - + - ``u``, ``v`` -- integers with `\gcd(u,v,N)=1` OUTPUT: - - - ``i`` -- the index of `u`, `v`, in the P1list. + - ``i`` -- the index of `u`, `v`, in the P1list EXAMPLES:: @@ -1043,16 +1027,13 @@ cdef class P1List(): INPUT: - - - ``u, v`` -- integers, with `\gcd(u,v,N)=1`. - + - ``u``, ``v`` -- integers with `\gcd(u,v,N)=1` OUTPUT: + - ``i`` -- the index of `u`, `v`, in the P1list - - ``i`` -- the index of `u`, `v`, in the P1list. - - - ``s`` -- normalizing scalar. + - ``s`` -- normalizing scalar. """ if self.__N == 1: # there is exactly 1 class [(0,0)]. @@ -1086,14 +1067,12 @@ cdef class P1List(): INPUT: - - - ``u``, ``v`` -- integers, with `\gcd(u,v,N)=1`, normalized so they lie in the list. - + - ``u``, ``v`` -- integers with `\gcd(u,v,N)=1`, normalized so they lie + in the list OUTPUT: - - - ``i`` -- the index of `(u:v)`, in the P1list. + - ``i`` -- the index of `(u:v)`, in the P1list EXAMPLES:: @@ -1130,14 +1109,10 @@ cdef class P1List(): INPUT: + - ``u``, ``v`` -- integers with `\gcd(u,v,N)=1` - - ``u, v`` -- integers, with `\gcd(u,v,N)=1`. - - - OUTPUT: - - - a 2-tuple ``(uu,vv)`` where `(uu:vv)` is a *normalized* - representative of `(u:v)`. + OUTPUT: a 2-tuple ``(uu,vv)`` where `(uu:vv)` is a *normalized* + representative of `(u:v)` NOTE: See also normalize_with_scalar() which also returns the normalizing scalar. @@ -1163,9 +1138,7 @@ cdef class P1List(): INPUT: - - - ``u, v`` -- integers, with `\gcd(u,v,N)=1`. - + - ``u``, ``v`` -- integers with `\gcd(u,v,N)=1` OUTPUT: @@ -1226,7 +1199,7 @@ def lift_to_sl2z_int(int c, int d, int N): INPUT: - - ``c,d,N`` -- integers such that `\gcd(c,d,N)=1`. + - ``c``, ``d``, ``N`` -- integers such that `\gcd(c,d,N)=1` EXAMPLES:: @@ -1296,7 +1269,7 @@ def lift_to_sl2z_llong(llong c, llong d, int N): INPUT: - - ``c,d,N`` -- integers such that `\gcd(c,d,N)=1`. + - ``c``, ``d``, ``N`` -- integers such that `\gcd(c,d,N)=1` EXAMPLES:: @@ -1362,7 +1335,7 @@ def lift_to_sl2z(c, d, N): INPUT: - - ``c,d,N`` -- Python ints or longs such that `\gcd(c,d,N)=1`. + - ``c``, ``d``, ``N`` -- python ints or longs such that `\gcd(c,d,N)=1` EXAMPLES:: @@ -1371,7 +1344,7 @@ def lift_to_sl2z(c, d, N): sage: lift_to_sl2z(2,3,6000000) [1, 1, 2, 3] - You will get a :class:`ValueError` exception if the input is invalid. + You will get a :exc:`ValueError` exception if the input is invalid. Note that here gcd(15,6,24)=3:: sage: lift_to_sl2z(15,6,24) diff --git a/src/sage/modular/modsym/p1list_nf.py b/src/sage/modular/modsym/p1list_nf.py index 2c9ed6516ad..86d33071974 100644 --- a/src/sage/modular/modsym/p1list_nf.py +++ b/src/sage/modular/modsym/p1list_nf.py @@ -122,16 +122,18 @@ class MSymbol(SageObject): INPUT: - - ``N`` -- integral ideal (the modulus or level). + - ``N`` -- integral ideal (the modulus or level) - ``c`` -- integral element of the underlying number field or an MSymbol of - level N. + level N - ``d`` -- (optional) when present, it must be an integral element such - that `\langle c\rangle + \langle d\rangle + N = R`, where `R` is the corresponding ring of integers. + that `\langle c\rangle + \langle d\rangle + N = R`, where `R` is the + corresponding ring of integers - - ``check`` -- bool (default ``True``). If ``check=False`` the constructor does - not check the condition `\langle c\rangle + \langle d\rangle + N = R`. + - ``check`` -- boolean (default: ``True``); if ``check=False`` the + constructor does not check the condition + `\langle c\rangle + \langle d\rangle + N = R` OUTPUT: @@ -232,7 +234,7 @@ def __repr__(self): def _latex_(self): r""" - Return latex representation of self. + Return latex representation of ``self``. EXAMPLES:: @@ -384,7 +386,7 @@ def normalize(self, with_scalar=False): INPUT: - - ``with_scalar`` -- bool (default ``False``) + - ``with_scalar`` -- boolean (default: ``False``) OUTPUT: @@ -484,7 +486,7 @@ class P1NFList(SageObject): INPUT: - - ``N`` -- integral ideal (the modulus or level). + - ``N`` -- integral ideal (the modulus or level) OUTPUT: @@ -618,12 +620,12 @@ def normalize(self, c, d=None, with_scalar=False): INPUT: - ``c`` -- integral element of the underlying number field, or an - MSymbol. + MSymbol - ``d`` -- (optional) when present, it must be an integral element of - the number field such that `(c, d)` defines an M-symbol of level `N`. + the number field such that `(c, d)` defines an M-symbol of level `N` - - ``with_scalar`` -- bool (default ``False``) + - ``with_scalar`` -- boolean (default: ``False``) OUTPUT: @@ -690,18 +692,18 @@ def index(self, c, d=None, with_scalar=False): INPUT: - ``c`` -- integral element of the corresponding number field, or an - :class:`MSymbol`. + :class:`MSymbol` - ``d`` -- (optional) when present, it must be an integral element of - the number field such that `(c, d)` defines an M-symbol of level `N`. + the number field such that `(c, d)` defines an M-symbol of level `N` - - ``with_scalar`` -- bool (default ``False``) + - ``with_scalar`` -- boolean (default: ``False``) OUTPUT: - ``u`` -- the normalizing scalar (only if ``with_scalar=True``) - - ``i`` -- the index of `(c, d)` in the list. + - ``i`` -- the index of `(c, d)` in the list EXAMPLES:: @@ -774,15 +776,13 @@ def index_of_normalized_pair(self, c, d=None): INPUT: - ``c`` -- integral element of the corresponding number field, or a - normalized :class:`MSymbol`. + normalized :class:`MSymbol` - ``d`` -- (optional) when present, it must be an integral element of the number field such that `(c, d)` defines a normalized M-symbol of - level `N`. + level `N` - OUTPUT: - - - ``i`` -- the index of `(c, d)` in the list. + OUTPUT: ``i`` -- the index of `(c, d)` in the list EXAMPLES:: @@ -916,19 +916,19 @@ def apply_TS(self, i): def apply_T_alpha(self, i, alpha=1): r""" - Applies the matrix `T_{alpha}` = [1, `alpha`, 0, 1] to the `i`-th M-Symbol of - the list. + Applies the matrix `T_{alpha}` = [1, `alpha`, 0, 1] to the `i`-th + M-Symbol of the list. INPUT: - ``i`` -- integer - - ``alpha`` -- (default 1) element of the corresponding ring of integers + - ``alpha`` -- (default: 1) element of the corresponding ring of integers OUTPUT: integer -- the index of the M-Symbol obtained by the right action of - the matrix `T_{alpha}` = [1, `alpha`, 0, 1] on the i-th M-Symbol. + the matrix `T_{alpha}` = [1, `alpha`, 0, 1] on the `i`-th M-Symbol. EXAMPLES:: @@ -963,7 +963,7 @@ def apply_J_epsilon(self, i, e1, e2=1): - ``e1`` -- unit - - ``e2`` -- unit (default 1) + - ``e2`` -- unit (default: 1) OUTPUT: @@ -1013,7 +1013,7 @@ def p1NFlist(N): INPUT: - - ``N`` -- integral ideal (the level or modulus). + - ``N`` -- integral ideal (the level or modulus) EXAMPLES:: @@ -1073,7 +1073,6 @@ def lift_to_sl2_Ok(N, c, d): a `2\times 2` matrix with determinant 1. The lower two entries are congruent to `c`, `d` modulo the ideal `N`. - EXAMPLES:: sage: from sage.modular.modsym.p1list_nf import lift_to_sl2_Ok diff --git a/src/sage/modular/modsym/relation_matrix.py b/src/sage/modular/modsym/relation_matrix.py index 7d58bb62a48..0562cfdf899 100644 --- a/src/sage/modular/modsym/relation_matrix.py +++ b/src/sage/modular/modsym/relation_matrix.py @@ -69,10 +69,8 @@ def modS_relations(syms): OUTPUT: - - - ``rels`` -- set of pairs of pairs (j, s), where if - mod[i] = (j,s), then x_i = s\*x_j (mod S relations) - + - ``rels`` -- set of pairs of pairs (j, s), where if + mod[i] = (j,s), then x_i = s\*x_j (mod S relations) EXAMPLES:: @@ -138,12 +136,12 @@ def modI_relations(syms, sign): - ``syms`` -- :class:`ManinSymbolList` - - ``sign`` -- int (either -1, 0, or 1) + - ``sign`` -- integer (either -1, 0, or 1) OUTPUT: - - ``rels`` -- set of pairs of pairs (j, s), where if - mod[i] = (j,s), then x_i = s\*x_j (mod S relations) + - ``rels`` -- set of pairs of pairs (j, s), where if + mod[i] = (j,s), then x_i = s\*x_j (mod S relations) EXAMPLES:: @@ -204,16 +202,16 @@ def T_relation_matrix_wtk_g0(syms, mod, field, sparse): - ``syms`` -- :class:`ManinSymbolList` - - ``mod`` -- list that gives quotient modulo some two-term relations, i.e., - the S relations, and if sign is nonzero, the I relations. + - ``mod`` -- list that gives quotient modulo some two-term relations, i.e., + the S relations, and if sign is nonzero, the I relations - - ``field`` -- base_ring + - ``field`` -- ``base_ring`` - - ``sparse`` -- (True or False) whether to use sparse rather than dense - linear algebra + - ``sparse`` -- boolean; whether to use sparse rather than dense + linear algebra - OUTPUT: A sparse matrix whose rows correspond to the reduction of - the T relations modulo the S and I relations. + OUTPUT: a sparse matrix whose rows correspond to the reduction of + the `T` relations modulo the `S` and `I` relations. EXAMPLES:: @@ -266,25 +264,23 @@ def gens_to_basis_matrix(syms, relation_matrix, mod, field, sparse): - ``syms`` -- :class:`ManinSymbolList` - - ``relation_matrix`` -- as output by - ``__compute_T_relation_matrix(self, mod)`` + - ``relation_matrix`` -- as output by + ``__compute_T_relation_matrix(self, mod)`` - - ``mod`` -- quotient of modular symbols modulo the - 2-term S (and possibly I) relations + - ``mod`` -- quotient of modular symbols modulo the + 2-term S (and possibly I) relations - - ``field`` -- base field + - ``field`` -- base field - - ``sparse`` -- (bool): whether or not matrix should be - sparse + - ``sparse`` -- boolean; whether or not matrix should be sparse OUTPUT: - - ``matrix`` -- a matrix whose ith row expresses the - Manin symbol generators in terms of a basis of Manin symbols - (modulo the S, (possibly I,) and T rels) Note that the entries of - the matrix need not be integers. + ``matrix`` -- a matrix whose `i`-th row expresses the Manin symbol + generators in terms of a basis of Manin symbols (modulo the S, (possibly + I,) and T rels). Note that the entries of the matrix need not be integers. - - ``list`` -- integers i, such that the Manin symbols `x_i` are a basis. + - ``list`` -- integers `i`, such that the Manin symbols `x_i` are a basis EXAMPLES:: @@ -370,21 +366,20 @@ def compute_presentation(syms, sign, field, sparse=None): - ``syms`` -- :class:`ManinSymbolList` - - ``sign`` -- integer (-1, 0, 1) - - - ``field`` -- a field + - ``sign`` -- integer (-1, 0, 1) + - ``field`` -- a field OUTPUT: - - sparse matrix whose rows give each generator - in terms of a basis for the quotient + - sparse matrix whose rows give each generator + in terms of a basis for the quotient - - list of integers that give the basis for the - quotient + - list of integers that give the basis for the + quotient - - mod: list where mod[i]=(j,s) means that x_i - = s\*x_j modulo the 2-term S (and possibly I) relations. + - mod: list where mod[i]=(j,s) means that x_i + = s\*x_j modulo the 2-term S (and possibly I) relations. ALGORITHM: @@ -422,7 +417,6 @@ def compute_presentation(syms, sign, field, sparse=None): of Manin symbols, modulo the relations. This subset of Manin symbols is a basis for the quotient by the relations. - EXAMPLES:: sage: L = sage.modular.modsym.manin_symbol_list.ManinSymbolList_gamma0(8,2) @@ -462,11 +456,11 @@ def relation_matrix_wtk_g0(syms, sign, field, sparse): - ``syms`` -- :class:`ManinSymbolList` - - ``sign``: integer (0, 1 or -1) + - ``sign`` -- integer (0, 1 or -1) - - ``field``: the base field (non-field base rings not supported at present) + - ``field`` -- the base field (non-field base rings not supported at present) - - ``sparse``: (True or False) whether to use sparse arithmetic. + - ``sparse`` -- boolean; whether to use sparse arithmetic Note that ManinSymbolList objects already have a specific weight, so there is no need for an extra ``weight`` parameter. @@ -519,30 +513,26 @@ def sparse_2term_quotient(rels, n, F): INPUT: - - ``rels`` -- iterable made of pairs ((i,s), (j,t)). The pair - represents the relation s\*x_i + t\*x_j = 0, where the i, j must - be Python int's. + - ``rels`` -- iterable made of pairs ((i,s), (j,t)). The pair + represents the relation `s x_i + t x_j = 0`, where the `i, j` must + be Python int's. - - ``n`` -- int, the x_i are x_0, ..., x_n-1. + - ``n`` -- integer, the `x_i` are `x_0, \ldots, x_{n-1}` - - ``F`` -- base field + - ``F`` -- base field OUTPUT: - - ``mod`` -- list such that mod[i] = (j,s), which means - that x_i is equivalent to s\*x_j, where the x_j are a basis for - the quotient. + ``mod`` -- list such that ``mod[i] = (j,s)``, which means that `x_i` is + equivalent to `s x_j`, where the `x_j` are a basis for the quotient. EXAMPLES: We quotient out by the relations .. MATH:: - 3*x0 - x1 = 0,\qquad x1 + x3 = 0,\qquad x2 + x3 = 0,\qquad x4 - x5 = 0 + 3*x0 - x1 = 0,\qquad x1 + x3 = 0,\qquad x2 + x3 = 0,\qquad x4 - x5 = 0 - - to get - - :: + to get:: sage: rels = [((int(0),3), (int(1),-1)), ((int(1),1), (int(3),1)), ((int(2),1),(int(3),1)), ((int(4),1),(int(5),-1))] sage: n = 6 diff --git a/src/sage/modular/modsym/relation_matrix_pyx.pyx b/src/sage/modular/modsym/relation_matrix_pyx.pyx index 46d8d716e62..0079133b610 100644 --- a/src/sage/modular/modsym/relation_matrix_pyx.pyx +++ b/src/sage/modular/modsym/relation_matrix_pyx.pyx @@ -31,10 +31,10 @@ def sparse_2term_quotient_only_pm1(rels, n): INPUT: - ``rels`` -- iterable made of pairs ((i,s), (j,t)). The pair - represents the relation s*x_i + t*x_j = 0, where the i, j must - be Python int's, and the s,t must all be 1 or -1. + represents the relation `s x_i + t x_j = 0`, where the `i, j` must + be Python int's, and the `s, t` must all be 1 or -1. - - ``n`` -- int, the x_i are x_0, ..., x_n-1. + - ``n`` -- integer; the `x_i` are `x_0, \ldots, x_{n-1}` OUTPUT: diff --git a/src/sage/modular/modsym/space.py b/src/sage/modular/modsym/space.py index 8dba0412a60..590a73c109d 100644 --- a/src/sage/modular/modsym/space.py +++ b/src/sage/modular/modsym/space.py @@ -196,14 +196,14 @@ def compact_system_of_eigenvalues(self, v, names='alpha', nz=None): INPUT: - - ``v`` -- a list of positive integers - - ``nz`` -- (default: ``None``); if given specifies a column index - such that the dual module has that column nonzero. + - ``v`` -- list of positive integers + - ``nz`` -- (default: ``None``) if given specifies a column index + such that the dual module has that column nonzero OUTPUT: - ``E`` -- matrix such that E\*v is a vector with components - the eigenvalues `a_n` for `n \in v`. + the eigenvalues `a_n` for `n \in v` - ``v`` -- a vector over a number field EXAMPLES:: @@ -388,13 +388,13 @@ def group(self): INPUT: - - ``ModularSymbols self`` -- an arbitrary space of - modular symbols + - ``ModularSymbols self`` -- an arbitrary space of + modular symbols OUTPUT: - - ``CongruenceSubgroup`` -- the congruence subgroup - that this is a space of modular symbols for. + - ``CongruenceSubgroup`` -- the congruence subgroup + that this is a space of modular symbols for ALGORITHM: The group is recorded when this space is created. @@ -473,9 +473,9 @@ def is_simple(self): def multiplicity(self, S, check_simple=True): """ Return the multiplicity of the simple modular symbols space S in - self. S must be a simple anemic Hecke module. + ``self``. S must be a simple anemic Hecke module. - ASSUMPTION: self is an anemic Hecke module with the same weight and + ASSUMPTION: ``self`` is an anemic Hecke module with the same weight and group as S, and S is simple. EXAMPLES:: @@ -507,12 +507,12 @@ def ngens(self): INPUT: - - ``ModularSymbols self`` -- arbitrary space of modular symbols. + - ``ModularSymbols self`` -- arbitrary space of modular symbols OUTPUT: - ``int`` -- the number of generators, which is the same as the - dimension of self. + dimension of ``self`` ALGORITHM: Call the dimension function. @@ -612,31 +612,31 @@ def set_precision(self, prec): def q_expansion_basis(self, prec=None, algorithm='default'): r""" - Return a basis of q-expansions (as power series) to precision prec + Return a basis of `q`-expansions (as power series) to precision ``prec`` of the space of modular forms associated to ``self``. - The q-expansions are defined over the same base ring as ``self``, + The `q`-expansions are defined over the same base ring as ``self``, and a put in echelon form. INPUT: - - ``self`` -- a space of CUSPIDAL modular symbols + - ``self`` -- a space of CUSPIDAL modular symbols - - ``prec`` -- an integer + - ``prec`` -- integer - - ``algorithm`` -- string: + - ``algorithm`` -- string; one of - - ``'default' (default)`` -- decide which algorithm to - use based on heuristics + - ``'default'`` -- (default) decide which algorithm to + use based on heuristics - - ``'hecke'`` -- compute basis by computing - homomorphisms T - K, where T is the Hecke algebra + - ``'hecke'`` -- compute basis by computing + homomorphisms T - K, where T is the Hecke algebra - - ``'eigen'`` -- compute basis using eigenvectors for - the Hecke action and Atkin-Lehner-Li theory to patch them together + - ``'eigen'`` -- compute basis using eigenvectors for + the Hecke action and Atkin-Lehner-Li theory to patch them together - - ``'all'`` -- compute using hecke_dual and eigen - algorithms and verify that the results are the same. + - ``'all'`` -- compute using hecke_dual and eigen + algorithms and verify that the results are the same The computed basis is *not* cached, though of course Hecke @@ -753,20 +753,19 @@ def q_expansion_module(self, prec=None, R=None): vectors of the `q`-expansions corresponding to ``self``. If R is not the base ring of ``self``, this returns the - restriction of scalars down to R (for this, self must have + restriction of scalars down to R (for this, ``self`` must have base ring `\QQ` or a number field). INPUT: - - ``self`` -- must be cuspidal + - ``self`` -- must be cuspidal - - ``prec`` -- an integer (default: - self.default_prec()) + - ``prec`` -- integer (default: ``self.default_prec()``) - - ``R`` -- either ZZ, QQ, or the base_ring of self + - ``R`` -- either `\ZZ`, `\QQ`, or the ``base_ring`` of ``self`` (which is the default) - OUTPUT: A free module over R. + OUTPUT: a free module over `R` .. TODO:: @@ -940,12 +939,12 @@ def _q_eigenform_images(self, A, prec, names): INPUT: - - ``self`` -- space of modular symbols + - ``self`` -- space of modular symbols - - ``A`` -- cuspidal simple space of level dividing the - level of self and the same weight + - ``A`` -- cuspidal simple space of level dividing the + level of ``self`` and the same weight - - ``prec`` -- a positive integer + - ``prec`` -- positive integer EXAMPLES:: @@ -972,11 +971,11 @@ def _q_expansion_module(self, prec, algorithm='hecke'): EXAMPLES:: - sage: ModularSymbols(11, 2, base_ring=GF(4,'a')).cuspidal_submodule()._q_expansion_module(prec=4, algorithm="hecke") + sage: ModularSymbols(11, 2, base_ring=GF(4,'a')).cuspidal_submodule()._q_expansion_module(prec=4, algorithm='hecke') Vector space of degree 4 and dimension 1 over Finite Field in a of size 2^2 Basis matrix: [0 1 0 1] - sage: ModularSymbols(11, 2, base_ring=QuadraticField(-7,'b'), sign=1).cuspidal_submodule()._q_expansion_module(prec=4, algorithm="eigen") + sage: ModularSymbols(11, 2, base_ring=QuadraticField(-7,'b'), sign=1).cuspidal_submodule()._q_expansion_module(prec=4, algorithm='eigen') Vector space of degree 4 and dimension 1 over Number Field in b with defining polynomial x^2 + 7 with b = 2.645751311064591?*I Basis matrix: [ 0 1 -2 -1] @@ -1002,7 +1001,7 @@ def q_eigen_gens(d, f): EXAMPLES:: - sage: ModularSymbols(11, 4, base_ring=QuadraticField(-7,'b'),sign=1).cuspidal_submodule()._q_expansion_module(prec=5, algorithm="eigen") # indirect doctest + sage: ModularSymbols(11, 4, base_ring=QuadraticField(-7,'b'),sign=1).cuspidal_submodule()._q_expansion_module(prec=5, algorithm='eigen') # indirect doctest Vector space of degree 5 and dimension 2 over Number Field in b with defining polynomial x^2 + 7 with b = 2.645751311064591?*I Basis matrix: [ 0 1 0 3 -6] @@ -1039,7 +1038,7 @@ def _q_expansion_module_rational(self, prec): INPUT: - - ``prec`` (integer) -- number of q-expansion terms to calculate. + - ``prec`` -- integer; number of `q`-expansion terms to calculate EXAMPLES:: @@ -1102,7 +1101,7 @@ def _q_expansion_module_integral(self, prec): the `q`-expansions corresponding to ``self``. The base ring of ``self`` must be `\QQ` or a number field, and - self must be cuspidal. The returned space is a `\ZZ`-module, + ``self`` must be cuspidal. The returned space is a `\ZZ`-module, where the coordinates are the coefficients of `q`-expansions. EXAMPLES:: @@ -1127,9 +1126,9 @@ def congruence_number(self, other, prec=None): congruence number, using ``prec`` terms of the `q`-expansions. The congruence number is defined as follows. If `V` is the - submodule of integral cusp forms corresponding to self (saturated in + submodule of integral cusp forms corresponding to ``self`` (saturated in `\ZZ[[q]]`, by definition) and `W` is the - submodule corresponding to other, each computed to precision prec, + submodule corresponding to other, each computed to precision ``prec``, the congruence number is the index of `V+W` in its saturation in `\ZZ[[q]]`. @@ -1170,7 +1169,7 @@ def q_eigenform_character(self, names=None): INPUT: - - ``names`` -- string, name of the variable. + - ``names`` -- string; name of the variable OUTPUT: @@ -1236,7 +1235,7 @@ def q_eigenform_character(self, names=None): def q_eigenform(self, prec, names=None): """ - Return the q-expansion to precision ``prec`` of a new eigenform + Return the `q`-expansion to precision ``prec`` of a new eigenform associated to ``self``. Here ``self`` must be new, cuspidal, and simple. @@ -1309,7 +1308,7 @@ def _q_expansion_basis_eigen(self, prec, names): def q_expansion_cuspforms(self, prec=None): r""" Return a function f(i,j) such that each value f(i,j) is the - q-expansion, to the given precision, of an element of the + `q`-expansion, to the given precision, of an element of the corresponding space `S` of cusp forms. Together these functions span `S`. Here `i,j` are integers @@ -1367,7 +1366,7 @@ def q_expansion_cuspforms(self, prec=None): def _q_expansion_basis_hecke_dual(self, prec): r""" - Compute a basis of q-expansions for the associated space of cusp forms + Compute a basis of `q`-expansions for the associated space of cusp forms to the given precision, by using linear functionals on the Hecke algebra as described in William Stein's book (Algorithm 3.26, page 56) @@ -1452,21 +1451,15 @@ def sign(self): INPUT: - - ``ModularSymbols self`` -- arbitrary space of modular - symbols. + - ``ModularSymbols self`` -- arbitrary space of modular symbols OUTPUT: - - ``int`` -- the sign of ``self``, either -1, 0, or 1. + - ``-1`` -- if this is factor of quotient where \* acts as -1, - - ``-1`` -- if this is factor of quotient where \* acts - as -1, + - ``+1`` -- if this is factor of quotient where \* acts as +1, - - ``+1`` -- if this is factor of quotient where \* acts - as +1, - - - ``0`` -- if this is full space of modular symbols (no - quotient). + - ``0`` -- if this is full space of modular symbols (no quotient) EXAMPLES:: @@ -1696,7 +1689,7 @@ def integral_basis(self): def integral_hecke_matrix(self, n): r""" - Return the matrix of the `n`th Hecke operator acting on the integral + Return the matrix of the `n`-th Hecke operator acting on the integral structure on ``self`` (as returned by ``self.integral_structure()``). This is often (but not always) different from the matrix @@ -1771,8 +1764,8 @@ def plus_submodule(self, compute_dual=True): INPUT: - - ``compute_dual`` -- bool (default: ``True``) also - compute dual subspace. This are useful for many algorithms. + - ``compute_dual`` -- boolean (default: ``True``); also + compute dual subspace. This is useful for many algorithms. OUTPUT: subspace of modular symbols @@ -1791,8 +1784,8 @@ def minus_submodule(self, compute_dual=True): INPUT: - - ``compute_dual`` -- bool (default: ``True``) also - compute dual subspace. This are useful for many algorithms. + - ``compute_dual`` -- boolean (default: ``True``); also + compute dual subspace. This is useful for many algorithms. OUTPUT: subspace of modular symbols @@ -1811,10 +1804,10 @@ def _compute_sign_submodule(self, sign, compute_dual=True): INPUT: - - sign (integer): 1 or -1 + - ``sign`` -- integer; 1 or -1 - - compute_dual (boolean, default ``True``): also compute the dual - submodule (useful for some algorithms) + - ``compute_dual`` -- boolean (default: ``True``); also compute the + dual submodule (useful for some algorithms) OUTPUT: a submodule of ``self`` @@ -1870,10 +1863,10 @@ def sign_submodule(self, sign, compute_dual=True): INPUT: - - ``sign`` -- int (either -1, 0 or +1) + - ``sign`` -- integer (either -1, 0 or +1) - - ``compute_dual`` -- bool (default: ``True``) also - compute dual subspace. This are useful for many algorithms. + - ``compute_dual`` -- boolean (default: ``True``); also + compute dual subspace. This is useful for many algorithms. OUTPUT: subspace of modular symbols @@ -1931,8 +1924,8 @@ def abelian_variety(self): INPUT: - - ``self`` -- modular symbols space of weight 2 for a - congruence subgroup such as Gamma0, Gamma1 or GammaH. + - ``self`` -- modular symbols space of weight 2 for a + congruence subgroup such as Gamma0, Gamma1 or GammaH EXAMPLES:: @@ -1972,7 +1965,7 @@ def rational_period_mapping(self): This is a homomorphism to a vector space whose kernel is the same as the kernel of the period mapping associated to - ``self``. For this to exist, self must be Hecke equivariant. + ``self``. For this to exist, ``self`` must be Hecke equivariant. Use :meth:`integral_period_mapping` to obtain a homomorphism to a `\ZZ`-module, normalized so the image of integral modular symbols is @@ -2092,12 +2085,12 @@ def modular_symbols_of_sign(self, sign, bound=None): INPUT: - - ``self`` -- a cuspidal space of modular symbols + - ``self`` -- a cuspidal space of modular symbols - - ``sign`` -- an integer, one of -1, 0, or 1 + - ``sign`` -- integer, one of -1, 0, or 1 - - ``bound`` -- integer (default: None); if specified - only use Hecke operators up to the given bound. + - ``bound`` -- integer (default: ``None``); if specified + only use Hecke operators up to the given bound EXAMPLES:: @@ -2354,9 +2347,9 @@ def _matrix_of_galois_action(self, t, P): INPUT: - - `t` -- integer + - ``t`` -- integer - - `P` -- list of cusps + - ``P`` -- list of cusps EXAMPLES: diff --git a/src/sage/modular/modsym/subspace.py b/src/sage/modular/modsym/subspace.py index a4892a71a80..e814602226a 100644 --- a/src/sage/modular/modsym/subspace.py +++ b/src/sage/modular/modsym/subspace.py @@ -36,19 +36,17 @@ def __init__(self, ambient_hecke_module, submodule, """ INPUT: + - ``ambient_hecke_module`` -- the ambient space of + modular symbols in which we're constructing a submodule - - ``ambient_hecke_module`` -- the ambient space of - modular symbols in which we're constructing a submodule + - ``submodule`` -- the underlying free module of the + submodule - - ``submodule`` -- the underlying free module of the - submodule - - - ``dual_free_module`` -- underlying free module of - the dual of the submodule (optional) - - - ``check`` -- (default: ``False``) whether to check that - the submodule is invariant under all Hecke operators T_p. + - ``dual_free_module`` -- underlying free module of + the dual of the submodule (optional) + - ``check`` -- boolean (default: ``False``); whether to check that + the submodule is invariant under all Hecke operators `T_p` EXAMPLES:: @@ -77,7 +75,7 @@ def __init__(self, ambient_hecke_module, submodule, def _repr_(self): """ - Return the string representation of self. + Return the string representation of ``self``. EXAMPLES:: @@ -228,7 +226,7 @@ def eisenstein_subspace(self): def factorization(self): """ Return a list of pairs `(S,e)` where `S` is simple - spaces of modular symbols and self is isomorphic to the direct sum + spaces of modular symbols and ``self`` is isomorphic to the direct sum of the `S^e` as a module over the *anemic* Hecke algebra adjoin the star involution. @@ -238,7 +236,7 @@ def factorization(self): The factors are sorted by dimension - don't depend on much more for now. - ASSUMPTION: self is a module over the anemic Hecke algebra. + ASSUMPTION: ``self`` is a module over the anemic Hecke algebra. EXAMPLES: Note that if the sign is 1 then the cuspidal factors occur twice, one with each star eigenvalue. @@ -325,7 +323,7 @@ def factorization(self): def is_cuspidal(self) -> bool: """ - Return True if self is cuspidal. + Return ``True`` if ``self`` is cuspidal. EXAMPLES:: @@ -357,7 +355,7 @@ def _set_is_cuspidal(self, t): def is_eisenstein(self): """ - Return True if self is an Eisenstein subspace. + Return ``True`` if ``self`` is an Eisenstein subspace. EXAMPLES:: @@ -380,10 +378,10 @@ def _compute_sign_subspace(self, sign, compute_dual=True): INPUT: - - ``sign`` -- int (either -1 or +1) + - ``sign`` -- integer (either -1 or +1) - - ``compute_dual`` -- bool (default: ``True``) also - compute dual subspace. This are useful for many algorithms. + - ``compute_dual`` -- boolean (default: ``True``); also + compute dual subspace. This is useful for many algorithms. OUTPUT: subspace of modular symbols diff --git a/src/sage/modular/modsym/tests.py b/src/sage/modular/modsym/tests.py index 3af2ffb1d87..8157b4e9e6b 100644 --- a/src/sage/modular/modsym/tests.py +++ b/src/sage/modular/modsym/tests.py @@ -45,11 +45,11 @@ def __init__(self, levels=20, weights=4, onlyg0=False, onlyg1=False, INPUT: - - levels -- list or int - - weights -- list or int - - onlyg0 -- bool, if True only select Gamma0 spaces for testing - - onlyg1 -- bool, if True only select Gamma1 spaces for testing - - onlychar -- bool, if True only selects spaces with character for testing + - ``levels`` -- list or integer + - ``weights`` -- list or integer + - ``onlyg0`` -- boolean; if ``True`` only select Gamma0 spaces for testing + - ``onlyg1`` -- boolean; if ``True`` only select Gamma1 spaces for testing + - ``onlychar`` -- boolean; if ``True`` only selects spaces with character for testing EXAMPLES:: @@ -92,7 +92,7 @@ def __repr__(self): def _modular_symbols_space(self): """ Generate a random space of modular symbols subject to - the conditions of self. + the conditions of ``self``. EXAMPLES:: diff --git a/src/sage/modular/multiple_zeta.py b/src/sage/modular/multiple_zeta.py index d184eaa9af1..a8ca0884127 100644 --- a/src/sage/modular/multiple_zeta.py +++ b/src/sage/modular/multiple_zeta.py @@ -223,9 +223,7 @@ def coproduct_iterator(paire) -> Iterator[list]: - ``paire`` -- a pair (list of indices, end of word) - OUTPUT: - - iterator for terms in the motivic coproduct + OUTPUT: iterator for terms in the motivic coproduct Each term is seen as a list of positions. @@ -329,9 +327,7 @@ def dual_composition(c) -> tuple[int, ...]: - ``c`` -- a composition - OUTPUT: - - a composition + OUTPUT: a composition EXAMPLES:: @@ -560,11 +556,9 @@ def extend_multiplicative_basis(B, n) -> Iterator: - ``B`` -- function mapping integer to list of tuples of compositions - - ``n`` -- an integer - - OUTPUT: + - ``n`` -- integer - Each term is a tuple of tuples of compositions. + OUTPUT: each term is a tuple of tuples of compositions EXAMPLES:: @@ -665,7 +659,7 @@ def __init__(self, R): if R in Domains(): cat = cat & Domains() W = Words(PositiveIntegers(), infinite=False) - CombinatorialFreeModule.__init__(self, R, W, prefix="Z", category=cat) + CombinatorialFreeModule.__init__(self, R, W, prefix='Z', category=cat) def _repr_(self) -> str: r""" @@ -951,7 +945,7 @@ def algebra_generators(self, n) -> list: INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -972,7 +966,7 @@ def basis_data(self, basering, n) -> Iterator: INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -996,7 +990,7 @@ def basis_brown(self, n) -> list: INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -1022,9 +1016,9 @@ def basis_filtration(self, d, reverse=False): INPUT: - - ``d`` -- (non-negative integer) the weight + - ``d`` -- nonnegative integer; the weight - - ``reverse`` -- (boolean, default ``False``) change the ordering of compositions + - ``reverse`` -- boolean (default: ``False``); change the ordering of compositions EXAMPLES:: @@ -1045,7 +1039,7 @@ def basis_filtration(self, d, reverse=False): [] """ if d < 0: - raise ValueError('d must be a non-negative integer') + raise ValueError('d must be a nonnegative integer') if d == 0: return [self([])] if d == 1: @@ -1148,7 +1142,7 @@ def simplify_full(self, basis=None): INPUT: - - ``basis`` (optional) -- either ``None`` or a function such that + - ``basis`` -- either ``None`` (default) or a function such that ``basis(d)`` is a basis of the weight ``d`` multiple zeta values. If ``None``, the Hoffman basis is used. @@ -1422,7 +1416,7 @@ def __init__(self, R): cat = GradedAlgebrasWithBasis(R).Commutative() if R in Domains(): cat = cat & Domains() - CombinatorialFreeModule.__init__(self, R, Words10, prefix="I", + CombinatorialFreeModule.__init__(self, R, Words10, prefix='I', category=cat) def _repr_(self) -> str: @@ -1624,7 +1618,7 @@ def composition_on_basis(self, w, basering=None): INPUT: - - ``basering`` -- optional choice of the coefficient ring + - ``basering`` -- (optional) choice of the coefficient ring EXAMPLES:: @@ -1754,9 +1748,7 @@ def phi_extended(self, w): - ``w`` -- a word in 0 and 1 - OUTPUT: - - an element in the auxiliary F-algebra + OUTPUT: an element in the auxiliary F-algebra The coefficients are in the base ring. @@ -2081,7 +2073,7 @@ def __init__(self, R): """ if R not in Rings(): raise TypeError("argument R must be a ring") - CombinatorialFreeModule.__init__(self, R, Words10, prefix="I") + CombinatorialFreeModule.__init__(self, R, Words10, prefix='I') def _repr_(self) -> str: """ @@ -2379,9 +2371,7 @@ def coeff_phi(w): - ``w`` -- a word in 0 and 1 with `k` letters (where `k` is odd) - OUTPUT: - - a rational number + OUTPUT: a rational number EXAMPLES:: @@ -2414,9 +2404,7 @@ def phi_on_multiplicative_basis(compo): - ``compo`` -- a composition (in the hardcoded multiplicative base) - OUTPUT: - - an element in :func:`F_ring` with rational coefficients + OUTPUT: an element in :func:`F_ring` with rational coefficients EXAMPLES:: @@ -2444,13 +2432,11 @@ def phi_on_basis(L): INPUT: - a list of compositions, each composition in the hardcoded basis + - ``L`` -- list of compositions; each composition in the hardcoded basis This encodes a product of multiple zeta values. - OUTPUT: - - an element in :func:`F_ring` + OUTPUT: an element in :func:`F_ring` EXAMPLES:: @@ -2518,9 +2504,7 @@ def compute_u_on_compo(compo): - ``compo`` -- a composition - OUTPUT: - - an element of :func:`F_ring` over `\QQ` + OUTPUT: an element of :func:`F_ring` over `\QQ` EXAMPLES:: @@ -2544,9 +2528,7 @@ def compute_u_on_basis(w): - ``w`` -- a word in 0,1 - OUTPUT: - - an element of :func:`F_ring` over `\QQ` + OUTPUT: an element of :func:`F_ring` over `\QQ` EXAMPLES:: @@ -2587,7 +2569,7 @@ def rho_matrix_inverse(n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -2617,9 +2599,7 @@ def rho_inverse(elt): - ``elt`` -- an homogeneous element of the F ring - OUTPUT: - - a linear combination of multiple zeta values + OUTPUT: a linear combination of multiple zeta values EXAMPLES:: diff --git a/src/sage/modular/multiple_zeta_F_algebra.py b/src/sage/modular/multiple_zeta_F_algebra.py index 1d7c8a79ddf..41aeb62b8c4 100644 --- a/src/sage/modular/multiple_zeta_F_algebra.py +++ b/src/sage/modular/multiple_zeta_F_algebra.py @@ -69,10 +69,10 @@ def str_to_index(x: str) -> tuple: r""" Convert a string to an index. - Every letter ``"2"`` contributes to the power of `f_2`. Other letters + Every letter ``'2'`` contributes to the power of `f_2`. Other letters are odd and define a word in `f_1, f_3, f_5, \ldots` - Usually the letters ``"2"`` form a prefix of the input. + Usually the letters ``'2'`` form a prefix of the input. EXAMPLES:: @@ -90,7 +90,7 @@ def str_to_index(x: str) -> tuple: def basis_f_odd_iterator(n, start=3) -> Iterator[tuple]: r""" - Return an iterator over compositions of ``n`` with odd parts. + Return an iterator over compositions of `n` with odd parts. Let `s` be the chosen odd start index. The allowed parts are the odd integers at least equal to `s`, in the set `s,s+2,s+4,s+6,\ldots`. @@ -99,9 +99,9 @@ def basis_f_odd_iterator(n, start=3) -> Iterator[tuple]: INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``start`` -- (default: ``3``) odd integer, start index for odd generators + - ``start`` -- odd integer (default: `3`); start index for odd generators EXAMPLES:: @@ -131,7 +131,7 @@ def basis_f_odd_iterator(n, start=3) -> Iterator[tuple]: def basis_f_iterator(n, start=3) -> Iterator[tuple]: r""" - Return an iterator for decompositions of ``n`` using ``2`` and odd integers. + Return an iterator for decompositions of `n` using `2` and odd integers. Let `s` be the chosen odd start index. The allowed odd parts are the odd integers at least equal to `s`, in the set `s,s+2,s+4,s+6,\ldots`. @@ -143,9 +143,9 @@ def basis_f_iterator(n, start=3) -> Iterator[tuple]: INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``start`` -- (default: ``3``) odd start index for odd generators + - ``start`` -- (default: `3`) odd start index for odd generators Each term is returned as a pair (integer, word) where the integer is the exponent of 2. @@ -193,14 +193,12 @@ def morphism_constructor(data: dict, start=3): INPUT: - - ``data`` -- a dictionary with integer keys containing the images of + - ``data`` -- dictionary with integer keys containing the images of `f_2, f_s, f_{s+2}, f_{s+4}, \ldots` - ``start`` -- (default: 3) start index for odd generators - OUTPUT: - - the unique morphism defined by the dictionary ``data`` + OUTPUT: the unique morphism defined by the dictionary ``data`` The codomain must be a zinbiel algebra, namely have both a commutative associative product ``*`` and a zinbiel product @@ -299,7 +297,7 @@ def __init__(self, R, start=3): Indices = NonNegativeIntegers().cartesian_product(W_Odds(start)) cat = BialgebrasWithBasis(R).Commutative().Graded() CombinatorialFreeModule.__init__(self, R, Indices, - latex_prefix="", prefix='f', + latex_prefix='', prefix='f', category=cat) def _repr_term(self, pw) -> str: @@ -388,7 +386,7 @@ def half_product_on_basis(self, pw1, pw2): INPUT: - - ``pw1``, ``pw2`` -- Basis elements + - ``pw1``, ``pw2`` -- basis elements EXAMPLES:: @@ -436,7 +434,7 @@ def gen(self, i): INPUT: - - ``i`` -- a nonnegative integer (at least 2) + - ``i`` -- nonnegative integer (at least 2) If ``i`` is odd, this returns a single generator `f_i` of the free shuffle algebra. @@ -558,11 +556,9 @@ def homogeneous_from_vector(self, vec, N): - ``vec`` -- a vector with coefficients in some base ring - - ``N`` -- integer, the homogeneous weight + - ``N`` -- integer; the homogeneous weight - OUTPUT: - - a homogeneous element of :func:`F_ring` over this base ring + OUTPUT: a homogeneous element of :func:`F_ring` over this base ring .. SEEALSO:: :meth:`F_algebra.homogeneous_to_vector` @@ -723,9 +719,7 @@ def homogeneous_to_vector(self): This is using a fixed enumeration of the basis. - OUTPUT: - - a vector with coefficients in the base ring + OUTPUT: a vector with coefficients in the base ring .. SEEALSO:: :meth:`F_algebra.homogeneous_from_vector` diff --git a/src/sage/modular/overconvergent/genus0.py b/src/sage/modular/overconvergent/genus0.py index 4cfdb603bd2..2576c9ddc18 100644 --- a/src/sage/modular/overconvergent/genus0.py +++ b/src/sage/modular/overconvergent/genus0.py @@ -243,23 +243,23 @@ def OverconvergentModularForms(prime, weight, radius, base_ring=QQ, prec=20, cha INPUT: - ``prime`` -- a prime number `p`, which must be one of the primes `\{2, 3, - 5, 7, 13\}`, or the congruence subgroup `\Gamma_0(p)` where `p` is one of these - primes. + 5, 7, 13\}`, or the congruence subgroup `\Gamma_0(p)` where `p` is one of + these primes - - ``weight`` -- an integer (which at present must be 0 or `\ge 2`), the - weight. + - ``weight`` -- integer (which at present must be 0 or `\ge 2`), the + weight - ``radius`` -- a rational number in the interval `\left( 0, \frac{p}{p+1} - \right)`, the radius of overconvergence. + \right)`, the radius of overconvergence - - ``base_ring`` -- (default: `\QQ`), a ring over which to compute. This - need not be a `p`-adic ring. + - ``base_ring`` -- (default: `\QQ`), a ring over which to compute; this + need not be a `p`-adic ring - - ``prec`` -- an integer (default: 20), the number of `q`-expansion terms to - compute. + - ``prec`` -- integer (default: 20); the number of `q`-expansion terms to + compute - - ``char`` -- a Dirichlet character modulo `p` or ``None`` (the default). - Here ``None`` is interpreted as the trivial character modulo `p`. + - ``char`` -- a Dirichlet character modulo `p` or ``None`` (the default); + here ``None`` is interpreted as the trivial character modulo `p` The character `\chi` and weight `k` must satisfy `(-1)^k = \chi(-1)`, and the base ring must contain an element `v` such that @@ -461,13 +461,13 @@ def base_extend(self, ring): Return the base extension of ``self`` to the given base ring. There must be a canonical map to this ring from the current - base ring, otherwise a :class:`TypeError` will be raised. + base ring, otherwise a :exc:`TypeError` will be raised. EXAMPLES:: sage: M = OverconvergentModularForms(2, 0, 1/2, base_ring=Qp(2)) sage: x = polygen(ZZ, 'x') - sage: M.base_extend(Qp(2).extension(x^2 - 2, names="w")) + sage: M.base_extend(Qp(2).extension(x^2 - 2, names='w')) Space of 2-adic 1/2-overconvergent modular forms of weight-character 0 over 2-adic Eisenstein Extension ... sage: M.base_extend(QQ) @@ -616,7 +616,6 @@ def _params(self): 7-adic Eisenstein Extension Field in w defined by x^2 - 7, 20, Dirichlet character modulo 7 of conductor 1 mapping 3 |--> 1) - """ return (self.prime(), self.weight().k(), self.radius(), self.base_ring(), self.prec(), self.weight().chi()) @@ -636,7 +635,6 @@ def __reduce__(self): 7-adic Eisenstein Extension Field in w defined by x^2 - 7, 20, Dirichlet character modulo 7 of conductor 1 mapping 3 |--> 1)) - """ return (OverconvergentModularForms, self._params()) @@ -1133,13 +1131,13 @@ def eigenfunctions(self, n, F=None, exact_arith=True): INPUT: - - ``n`` -- integer. The size of the matrix to use. + - ``n`` -- integer; the size of the matrix to use - ``F`` -- either ``None`` or a field over which to calculate eigenvalues. If the field is ``None``, the current base ring is used. If the base ring is not a `p`-adic ring, an error will be raised. - - ``exact_arith`` -- ``True`` or ``False`` (default ``True``). If ``True``, use exact + - ``exact_arith`` -- boolean (default: ``True``); if ``True``, use exact rational arithmetic to calculate the matrix of the `U` operator and its characteristic power series, even when the base ring is an inexact `p`-adic ring. This is typically slower, but more numerically stable. @@ -1313,7 +1311,8 @@ def recurrence_matrix(self, use_smithline=True): def _discover_recurrence_matrix(self, use_smithline=True): r""" - Does hard work of calculating recurrence matrix, which is cached to avoid doing this every time. + Do the hard work of calculating the recurrence matrix, which is cached + to avoid doing this every time. EXAMPLES:: @@ -1388,7 +1387,7 @@ def cps_u(self, n, use_recurrence=False): Uses the Hessenberg form of the Hecke matrix to compute the characteristic polynomial. Because of the use of relative precision here this tends to give better - precision in the p-adic coefficients. + precision in the `p`-adic coefficients. """ m = self.hecke_matrix(self.prime(), n, use_recurrence) A = PowerSeriesRing(self.base_ring(), 'T') @@ -1472,7 +1471,6 @@ def _lmul_(self, x): sage: f = M.0 sage: 2*f # indirect doctest 2-adic overconvergent modular form of weight-character 12 with q-expansion 2 - 131040/1414477*q ... - """ return OverconvergentModularFormElement(self.parent(), gexp=x * self.gexp()) @@ -1486,7 +1484,6 @@ def _rmul_(self, x): sage: f = M.0 sage: f * 3 # indirect doctest 2-adic overconvergent modular form of weight-character 12 with q-expansion 3 - 196560/1414477*q ... - """ return OverconvergentModularFormElement(self.parent(), gexp=x * self.gexp()) diff --git a/src/sage/modular/overconvergent/hecke_series.py b/src/sage/modular/overconvergent/hecke_series.py index 924ebaf5a60..fedf6160c50 100644 --- a/src/sage/modular/overconvergent/hecke_series.py +++ b/src/sage/modular/overconvergent/hecke_series.py @@ -110,7 +110,7 @@ def compute_G(p, F): EXAMPLES:: - sage: E = sage.modular.overconvergent.hecke_series.eisenstein_series_qexp(2, 12, Zmod(9),normalization="constant") + sage: E = sage.modular.overconvergent.hecke_series.eisenstein_series_qexp(2, 12, Zmod(9),normalization='constant') sage: sage.modular.overconvergent.hecke_series.compute_G(3, E) 1 + 3*q + 3*q^4 + 6*q^7 + O(q^12) """ @@ -129,14 +129,12 @@ def low_weight_bases(N, p, m, NN, weightbound): INPUT: - - ``N`` -- positive integer (level). - - ``p`` -- prime. - - ``m``, ``NN`` -- positive integers. - - ``weightbound`` -- (even) positive integer. + - ``N`` -- positive integer (level) + - ``p`` -- prime + - ``m``, ``NN`` -- positive integers + - ``weightbound`` -- (even) positive integer - OUTPUT: - - - list of lists of `q`-expansions modulo `(p^m,q^{NN})`. + OUTPUT: list of lists of `q`-expansions modulo `(p^m,q^{NN})` EXAMPLES:: @@ -145,7 +143,6 @@ def low_weight_bases(N, p, m, NN, weightbound): [[1 + 24*q + 24*q^2 + 96*q^3 + 24*q^4 + O(q^5)], [1 + 115*q^2 + 35*q^4 + O(q^5), q + 8*q^2 + 28*q^3 + 64*q^4 + O(q^5)], [1 + 121*q^2 + 118*q^4 + O(q^5), q + 32*q^2 + 119*q^3 + 24*q^4 + O(q^5)]] - """ generators = [] @@ -156,20 +153,18 @@ def low_weight_bases(N, p, m, NN, weightbound): def random_low_weight_bases(N,p,m,NN,weightbound): r""" - Returns list of random integral bases of modular forms of level `N` and + Return list of random integral bases of modular forms of level `N` and (even) weight at most weightbound with coefficients reduced modulo `(p^m,q^{NN})`. INPUT: - - ``N`` -- positive integer (level). - - ``p`` -- prime. - - ``m``, ``NN`` -- positive integers. - - ``weightbound`` -- (even) positive integer. + - ``N`` -- positive integer (level) + - ``p`` -- prime + - ``m``, ``NN`` -- positive integers + - ``weightbound`` -- (even) positive integer - OUTPUT: - - - list of lists of `q`-expansions modulo `(p^m,q^{NN})`. + OUTPUT: list of lists of `q`-expansions modulo `(p^m,q^{NN})` EXAMPLES:: @@ -185,7 +180,6 @@ def random_low_weight_bases(N,p,m,NN,weightbound): Power Series Ring in q over Ring of integers modulo 49 sage: S[0][0].prec() 5 - """ LWB = low_weight_bases(N,p,m,NN,weightbound) # this is "approximately" row reduced (it's the mod p^n reduction of a @@ -202,7 +196,7 @@ def random_low_weight_bases(N,p,m,NN,weightbound): def low_weight_generators(N,p,m,NN): r""" - Returns a list of lists of modular forms, and an even natural number. + Return a list of lists of modular forms, and an even natural number. The first output is a list of lists of modular forms reduced modulo `(p^m,q^{NN})` which generate the `(\ZZ / p^m \ZZ)`-algebra of mod `p^m` @@ -217,13 +211,11 @@ def low_weight_generators(N,p,m,NN): INPUT: - - ``N`` -- positive integer (level). - - ``p`` -- prime. - - ``m``, ``NN`` -- positive integers. + - ``N`` -- positive integer (level) + - ``p`` -- prime + - ``m``, ``NN`` -- positive integers - OUTPUT: - - a tuple consisting of: + OUTPUT: a tuple consisting of: - a list of lists of `q`-expansions modulo `(p^m,q^{NN})`, - an even natural number (twice the length of the list). @@ -254,7 +246,7 @@ def low_weight_generators(N,p,m,NN): def random_solution(B,K): r""" - Returns a random solution in non-negative integers to the equation `a_1 + 2 + Return a random solution in nonnegative integers to the equation `a_1 + 2 a_2 + 3 a_3 + ... + B a_B = K`, using a greedy algorithm. Note that this is *much* faster than using @@ -262,11 +254,9 @@ def random_solution(B,K): INPUT: - - ``B``, ``K`` -- non-negative integers. - - OUTPUT: + - ``B``, ``K`` -- nonnegative integers - - list. + OUTPUT: list EXAMPLES:: @@ -344,27 +334,23 @@ def ech_form(A, p): def random_new_basis_modp(N, p, k, LWBModp, TotalBasisModp, elldash, bound): r""" - Returns a list of lists of lists ``[j, a]`` encoding a choice of basis for - the ith complementary space `W_i`, as explained in the documentation for the + Return a list of lists of lists ``[j, a]`` encoding a choice of basis for + the `i`-th complementary space `W_i`, as explained in the documentation for the function :func:`complementary_spaces_modp`. INPUT: - - ``N`` -- positive integer at least 2 and not divisible by `p` (level). - - ``p`` -- prime at least 5. - - ``k`` -- non-negative integer. - - ``LWBModp`` -- list of list of `q`-expansions modulo - `(p,q^\text{elldash})`. - - ``TotalBasisModp`` -- matrix over `\mathrm{GF}(p)`. - - ``elldash`` -- positive integer. - - ``bound`` -- positive even integer (twice the length of the list - ``LWBModp``). - - OUTPUT: + - ``N`` -- positive integer at least 2 and not divisible by `p` (level) + - ``p`` -- prime at least 5 + - ``k`` -- nonnegative integer + - ``LWBModp`` -- list of list of `q`-expansions modulo `(p,q^\text{elldash})` + - ``TotalBasisModp`` -- matrix over `\mathrm{GF}(p)` + - ``elldash`` -- positive integer + - ``bound`` -- positive even integer (twice the length of the list ``LWBModp``) - - A list of lists of lists ``[j, a]``. + OUTPUT: list of lists of lists ``[j, a]`` - .. note:: + .. NOTE:: As well as having a non-trivial return value, this function also modifies the input matrix ``TotalBasisModp``. @@ -376,7 +362,6 @@ def random_new_basis_modp(N, p, k, LWBModp, TotalBasisModp, elldash, bound): sage: LWBModp = [ [f.change_ring(GF(5)) for f in x] for x in LWB] sage: complementary_spaces_modp(2, 5, 2, 3, 4, LWBModp, 4) # random, indirect doctest [[[[0, 0]]], [[[0, 0], [1, 1]]], [[[0, 0], [1, 0], [1, 1]]], [[[0, 0], [1, 0], [1, 1], [1, 1]]]] - """ R = LWBModp[0][0].parent() @@ -415,15 +400,15 @@ def random_new_basis_modp(N, p, k, LWBModp, TotalBasisModp, elldash, bound): def complementary_spaces_modp(N, p, k0, n, elldash, LWBModp, bound): r""" - Returns a list of lists of lists of lists ``[j, a]``. The pairs ``[j, a]`` + Return a list of lists of lists of lists ``[j, a]``. The pairs ``[j, a]`` encode the choice of the `a`-th element in the `j`-th list of the input ``LWBModp``, i.e., the `a`-th element in a particular basis modulo `(p,q^\text{elldash})` for the space of modular forms of level `\Gamma_0(N)` and weight `2(j+1)`. The list ``[[j_1, a_1], ...,[j_r, a_r]]`` then encodes the product of the r modular forms associated to each ``[j_i, a_i]``; this has weight `k + (p-1)i` for some `0 \le i \le n`; here - the `i` is such that this *list of lists* occurs in the ith list of the - output. The ith list of the output thus encodes a choice of basis for the + the `i` is such that this *list of lists* occurs in the `i`-th list of the + output. The `i`-th list of the output thus encodes a choice of basis for the complementary space `W_i` which occurs in Step 2 of Algorithm 2 in [Lau2011]_. The idea is that one searches for this space `W_i` first modulo `(p,q^\text{elldash})` and then, having found the correct products of @@ -433,16 +418,14 @@ def complementary_spaces_modp(N, p, k0, n, elldash, LWBModp, bound): INPUT: - - ``N`` -- positive integer at least 2 and not divisible by `p` (level). - - ``p`` -- prime at least 5. - - ``k0`` -- integer in range 0 to `p-1`. - - ``n``, ``elldash`` -- positive integers. - - ``LWBModp`` -- list of lists of `q`-expansions over `GF(p)`. - - ``bound`` -- positive even integer (twice the length of the list ``LWBModp``). - - OUTPUT: + - ``N`` -- positive integer at least 2 and not divisible by `p` (level) + - ``p`` -- prime at least 5 + - ``k0`` -- integer in range 0 to `p-1` + - ``n``, ``elldash`` -- positive integers + - ``LWBModp`` -- list of lists of `q`-expansions over `GF(p)` + - ``bound`` -- positive even integer (twice the length of the list ``LWBModp``) - - list of list of list of lists. + OUTPUT: list of list of list of lists EXAMPLES:: @@ -465,8 +448,8 @@ def complementary_spaces_modp(N, p, k0, n, elldash, LWBModp, bound): def complementary_spaces(N, p, k0, n, mdash, elldashp, elldash, modformsring, bound): r""" - Returns a list ``Ws``, each element in which is a list ``Wi`` of - q-expansions modulo `(p^\text{mdash},q^\text{elldashp})`. The list ``Wi`` is + Return a list ``Ws``, each element in which is a list ``Wi`` of + `q`-expansions modulo `(p^\text{mdash},q^\text{elldashp})`. The list ``Wi`` is a basis for a choice of complementary space in level `\Gamma_0(N)` and weight `k` to the image of weight `k - (p-1)` forms under multiplication by the Eisenstein series `E_{p-1}`. @@ -486,16 +469,16 @@ def complementary_spaces(N, p, k0, n, mdash, elldashp, elldash, modformsring, bo INPUT: - - ``N`` -- positive integer at least 2 and not divisible by p (level). - - ``p`` -- prime at least 5. - - ``k0`` -- integer in range 0 to `p - 1`. - - ``n``, ``mdash``, ``elldashp``, ``elldash`` -- positive integers. - - ``modformsring`` -- ``True`` or ``False``. - - ``bound`` -- positive (even) integer (ignored if ``modformsring`` is True). + - ``N`` -- positive integer at least 2 and not divisible by p (level) + - ``p`` -- prime at least 5 + - ``k0`` -- integer in range 0 to `p - 1` + - ``n``, ``mdash``, ``elldashp``, ``elldash`` -- positive integers + - ``modformsring`` -- boolean + - ``bound`` -- positive (even) integer (ignored if ``modformsring`` is True) OUTPUT: - - list of lists of q-expansions modulo + - list of lists of `q`-expansions modulo `(p^\text{mdash},q^\text{elldashp})`. EXAMPLES:: @@ -522,7 +505,7 @@ def complementary_spaces(N, p, k0, n, mdash, elldashp, elldash, modformsring, bo CompSpacesCode = complementary_spaces_modp(N, p, k0, n, elldash, LWBModp, bound) Ws = [] - Epm1 = eisenstein_series_qexp(p - 1, prec=elldashp, K=Zmod(p**mdash), normalization="constant") + Epm1 = eisenstein_series_qexp(p - 1, prec=elldashp, K=Zmod(p**mdash), normalization='constant') for i in range(n + 1): CompSpacesCodemi = CompSpacesCode[i] Wi = [] @@ -542,7 +525,7 @@ def complementary_spaces(N, p, k0, n, mdash, elldashp, elldash, modformsring, bo def higher_level_katz_exp(p, N, k0, m, mdash, elldash, elldashp, modformsring, bound): r""" - Returns a matrix `e` of size ``ell x elldashp`` over the integers modulo + Return a matrix `e` of size ``ell x elldashp`` over the integers modulo `p^\text{mdash}`, and the Eisenstein series `E_{p-1} = 1 + .\dots \bmod (p^\text{mdash},q^\text{elldashp})`. The matrix `e` contains the coefficients of the elements `e_{i,s}` in the Katz expansions basis in Step 3 of @@ -552,16 +535,14 @@ def higher_level_katz_exp(p, N, k0, m, mdash, elldash, elldashp, modformsring, b INPUT: - - ``p`` -- prime at least 5. - - ``N`` -- positive integer at least 2 and not divisible by `p` (level). - - ``k0`` -- integer in range 0 to `p-1`. - - ``m``, ``mdash, ``elldash``, ``elldashp`` -- positive integers. - - ``modformsring`` -- ``True`` or ``False``. - - ``bound`` -- positive (even) integer. + - ``p`` -- prime at least 5 + - ``N`` -- positive integer at least 2 and not divisible by `p` (level) + - ``k0`` -- integer in range 0 to `p-1` + - ``m``, ``mdash, ``elldash``, ``elldashp`` -- positive integers + - ``modformsring`` -- boolean + - ``bound`` -- positive (even) integer - OUTPUT: - - - matrix and `q`-expansion. + OUTPUT: matrix and `q`-expansion EXAMPLES:: @@ -579,7 +560,7 @@ def higher_level_katz_exp(p, N, k0, m, mdash, elldash, elldashp, modformsring, b """ ordr = 1 / (p + 1) S = Zmod(p ** mdash) - Ep1 = eisenstein_series_qexp(p - 1, prec=elldashp, K=S, normalization="constant") + Ep1 = eisenstein_series_qexp(p - 1, prec=elldashp, K=S, normalization='constant') n = floor(((p + 1) / (p - 1)) * (m + 1)) Wjs = complementary_spaces(N, p, k0, n, mdash, elldashp, elldash, modformsring, bound) @@ -608,7 +589,7 @@ def higher_level_katz_exp(p, N, k0, m, mdash, elldash, elldashp, modformsring, b def compute_elldash(p, N, k0, n): r""" - Returns the "Sturm bound" for the space of modular forms of level + Return the "Sturm bound" for the space of modular forms of level `\Gamma_0(N)` and weight `k_0 + n(p-1)`. .. SEEALSO:: @@ -617,13 +598,11 @@ def compute_elldash(p, N, k0, n): INPUT: - - ``p`` -- prime. - - ``N`` -- positive integer (level). - - ``k0``, ``n`` -- non-negative integers not both zero. - - OUTPUT: + - ``p`` -- prime + - ``N`` -- positive integer (level) + - ``k0``, ``n`` -- nonnegative integers not both zero - - positive integer. + OUTPUT: positive integer EXAMPLES:: @@ -638,8 +617,8 @@ def compute_elldash(p, N, k0, n): def hecke_series_degree_bound(p, N, k, m): r""" - Returns the ``Wan bound`` on the degree of the characteristic series of the - Atkin operator on p-adic overconvergent modular forms of level + Return the ``Wan bound`` on the degree of the characteristic series of the + Atkin operator on `p`-adic overconvergent modular forms of level `\Gamma_0(N)` and weight `k` when reduced modulo `p^m`. This bound depends only upon `p, k \pmod{p-1}`, and `N`. It uses Lemma 3.1 in @@ -647,14 +626,12 @@ def hecke_series_degree_bound(p, N, k, m): INPUT: - - ``p`` -- prime at least 5. - - ``N`` -- positive integer not divisible by `p`. - - ``k`` -- even integer. - - ``m`` -- positive integer. - - OUTPUT: + - ``p`` -- prime at least 5 + - ``N`` -- positive integer not divisible by `p` + - ``k`` -- even integer + - ``m`` -- positive integer - A non-negative integer. + OUTPUT: nonnegative integer EXAMPLES:: @@ -696,13 +673,13 @@ def higher_level_UpGj(p, N, klist, m, modformsring, bound, extra_data=False): INPUT: - - ``p`` -- prime at least 5. - - ``N`` -- integer at least 2 and not divisible by `p` (level). - - ``klist`` -- list of integers all congruent modulo `(p-1)` (the weights). - - ``m`` -- positive integer. - - ``modformsring`` -- ``True`` or ``False``. - - ``bound`` -- (even) positive integer. - - ``extra_data`` -- (default: ``False``) boolean. + - ``p`` -- prime at least 5 + - ``N`` -- integer at least 2 and not divisible by `p` (level) + - ``klist`` -- list of integers all congruent modulo `(p-1)` (the weights) + - ``m`` -- positive integer + - ``modformsring`` -- boolean + - ``bound`` -- (even) positive integer + - ``extra_data`` -- boolean (default: ``False``) OUTPUT: @@ -809,12 +786,12 @@ def higher_level_UpGj(p, N, klist, m, modformsring, bound, extra_data=False): def compute_Wi(k, p, h, hj, E4, E6): r""" - This function computes a list `W_i` of q-expansions, together with an + This function computes a list `W_i` of `q`-expansions, together with an auxiliary quantity `h^j` (see below) which is to be used on the next - call of this function. (The precision is that of input q-expansions.) + call of this function. (The precision is that of input `q`-expansions.) The list `W_i` is a certain subset of a basis of the modular forms of - weight `k` and level 1. Suppose `(a, b)` is the pair of non-negative + weight `k` and level 1. Suppose `(a, b)` is the pair of nonnegative integers with `4a + 6b = k` and `a` minimal among such pairs. Then this space has a basis given by @@ -836,16 +813,16 @@ def compute_Wi(k, p, h, hj, E4, E6): INPUT: - - ``k`` -- non-negative integer. - - ``p`` -- prime at least 5. - - ``h`` -- q-expansion of `h` (to some finite precision). - - ``hj`` -- q-expansion of `h^j` where `j` is the dimension of the space of + - ``k`` -- nonnegative integer + - ``p`` -- prime at least 5 + - ``h`` -- `q`-expansion of `h` (to some finite precision) + - ``hj`` -- `q`-expansion of `h^j` where `j` is the dimension of the space of modular forms of level 1 and weight `k - (p-1)` (to same finite - precision). - - ``E4`` -- `q`-expansion of `E_4` (to same finite precision). - - ``E6`` -- `q`-expansion of `E_6` (to same finite precision). + precision) + - ``E4`` -- `q`-expansion of `E_4` (to same finite precision) + - ``E6`` -- `q`-expansion of `E_6` (to same finite precision) - The Eisenstein series q-expansions should be normalized to have constant + The Eisenstein series `q`-expansions should be normalized to have constant term 1. OUTPUT: @@ -859,8 +836,8 @@ def compute_Wi(k, p, h, hj, E4, E6): sage: prec = 10 sage: k = 24 sage: S = Zmod(17^3) - sage: E4 = eisenstein_series_qexp(4, prec, K=S, normalization="constant") - sage: E6 = eisenstein_series_qexp(6, prec, K=S, normalization="constant") + sage: E4 = eisenstein_series_qexp(4, prec, K=S, normalization='constant') + sage: E6 = eisenstein_series_qexp(6, prec, K=S, normalization='constant') sage: h = delta_qexp(prec, K=S) / E6^2 sage: from sage.modular.dims import dimension_modular_forms sage: j = dimension_modular_forms(1, k - (p - 1)) @@ -899,7 +876,7 @@ def compute_Wi(k, p, h, hj, E4, E6): def katz_expansions(k0, p, ellp, mdash, n): r""" - Returns a list `e` of `q`-expansions, and the Eisenstein series `E_{p-1} = 1 + + Return a list `e` of `q`-expansions, and the Eisenstein series `E_{p-1} = 1 + \dots`, all modulo `(p^\text{mdash},q^\text{ellp})`. The list `e` contains the elements `e_{i,s}` in the Katz expansions basis in Step 3 of Algorithm 1 in [Lau2011]_ when one takes as input to that algorithm `p,m` and `k` and define @@ -907,9 +884,9 @@ def katz_expansions(k0, p, ellp, mdash, n): INPUT: - - ``k0`` -- integer in range 0 to `p - 1`. - - ``p`` -- prime at least 5. - - ``ellp``, ``mdash``, ``n`` -- positive integers. + - ``k0`` -- integer in range 0 to `p - 1` + - ``p`` -- prime at least 5 + - ``ellp``, ``mdash``, ``n`` -- positive integers OUTPUT: @@ -925,9 +902,9 @@ def katz_expansions(k0, p, ellp, mdash, n): """ S = Zmod(p ** mdash) - Ep1 = eisenstein_series_qexp(p - 1, ellp, K=S, normalization="constant") - E4 = eisenstein_series_qexp(4, ellp, K=S, normalization="constant") - E6 = eisenstein_series_qexp(6, ellp, K=S, normalization="constant") + Ep1 = eisenstein_series_qexp(p - 1, ellp, K=S, normalization='constant') + E4 = eisenstein_series_qexp(4, ellp, K=S, normalization='constant') + E6 = eisenstein_series_qexp(6, ellp, K=S, normalization='constant') delta = delta_qexp(ellp, K=S) h = delta / E6 ** 2 @@ -963,10 +940,10 @@ def level1_UpGj(p, klist, m, extra_data=False): INPUT: - - ``p`` -- prime at least 5. - - ``klist`` -- list of integers congruent modulo `(p-1)` (the weights). - - ``m`` -- positive integer. - - ``extra_data`` -- (default: ``False``) boolean + - ``p`` -- prime at least 5 + - ``klist`` -- list of integers congruent modulo `(p-1)` (the weights) + - ``m`` -- positive integer + - ``extra_data`` -- boolean (default: ``False``) OUTPUT: @@ -987,7 +964,6 @@ def level1_UpGj(p, klist, m, extra_data=False): ] sage: len(level1_UpGj(7, [100], 5, extra_data=True)) 4 - """ # Step 1 t = cputime() @@ -1065,12 +1041,13 @@ def level1_UpGj(p, klist, m, extra_data=False): def is_valid_weight_list(klist, p): r""" This function checks that ``klist`` is a nonempty list of integers all of - which are congruent modulo `(p-1)`. Otherwise, it will raise a ValueError. + which are congruent modulo `(p-1)`. Otherwise, it will raise a + :exc:`ValueError`. INPUT: - - ``klist`` -- list of integers. - - ``p`` -- prime. + - ``klist`` -- list of integers + - ``p`` -- prime EXAMPLES:: @@ -1095,8 +1072,8 @@ def is_valid_weight_list(klist, p): def hecke_series(p, N, klist, m, modformsring=False, weightbound=6): r""" - Returns the characteristic series modulo `p^m` of the Atkin operator `U_p` - acting upon the space of p-adic overconvergent modular forms of level + Return the characteristic series modulo `p^m` of the Atkin operator `U_p` + acting upon the space of `p`-adic overconvergent modular forms of level `\Gamma_0(N)` and weight ``klist``. The input ``klist`` may also be a list of weights congruent modulo `(p-1)`, @@ -1108,7 +1085,7 @@ def hecke_series(p, N, klist, m, modformsring=False, weightbound=6): If ``modformsring`` is ``True``, then for `N > 1` the algorithm computes at one step ``ModularFormsRing(N).generators()``. This will often be faster but the algorithm will default to ``modformsring=False`` if the generators - found are not p-adically integral. Note that ``modformsring`` is ignored + found are not `p`-adically integral. Note that ``modformsring`` is ignored for `N = 1` and the ring structure of modular forms is *always* used in this case. @@ -1122,18 +1099,15 @@ def hecke_series(p, N, klist, m, modformsring=False, weightbound=6): INPUT: - - ``p`` -- a prime greater than or equal to 5. - - ``N`` -- a positive integer not divisible by `p`. - - ``klist`` -- either a list of integers congruent modulo `(p-1)`, or a single integer. - - ``m`` -- a positive integer. - - ``modformsring`` -- ``True`` or ``False`` (default: ``False``). - Ignored if `N = 1`. + - ``p`` -- a prime greater than or equal to 5 + - ``N`` -- positive integer not divisible by `p` + - ``klist`` -- either a list of integers congruent modulo `(p-1)`, or a single integer + - ``m`` -- positive integer + - ``modformsring`` -- boolean (default: ``False``); ignored if `N = 1` - ``weightbound`` -- a positive even integer (default: 6). Ignored - if `N = 1` or ``modformsring`` is ``True``. - - OUTPUT: + if `N = 1` or ``modformsring`` is ``True`` - Either a list of polynomials or a single polynomial over the integers modulo `p^m`. + OUTPUT: either a list of polynomials or a single polynomial over the integers modulo `p^m` EXAMPLES:: diff --git a/src/sage/modular/overconvergent/weightspace.py b/src/sage/modular/overconvergent/weightspace.py index e9478c40a90..c159ac5eee3 100644 --- a/src/sage/modular/overconvergent/weightspace.py +++ b/src/sage/modular/overconvergent/weightspace.py @@ -87,7 +87,7 @@ _wscache = {} def WeightSpace_constructor(p, base_ring=None): r""" - Construct the p-adic weight space for the given prime p. + Construct the `p`-adic weight space for the given prime p. A `p`-adic weight is a continuous character `\ZZ_p^\times \to \CC_p^\times`. @@ -281,8 +281,8 @@ def _coerce_map_from_(self, other): def _coerce_in_wtchar(self, x): r""" - Convert in a weight-character whose parent is different from self (with - has the prime, but possibly different base ring). + Convert in a weight-character whose parent is different from ``self`` + (with has the prime, but possibly different base ring). EXAMPLES:: @@ -300,7 +300,7 @@ def _coerce_in_wtchar(self, x): class WeightCharacter(Element): r""" - Abstract base class representing an element of the p-adic weight space + Abstract base class representing an element of the `p`-adic weight space `Hom(\ZZ_p^\times, \CC_p^\times)`. """ @@ -336,7 +336,7 @@ def base_extend(self, R): def is_even(self) -> bool: r""" - Return True if this weight-character sends -1 to +1. + Return ``True`` if this weight-character sends -1 to +1. EXAMPLES:: @@ -353,7 +353,7 @@ def is_even(self) -> bool: def pAdicEisensteinSeries(self, ring, prec=20): r""" - Calculate the q-expansion of the p-adic Eisenstein series of given + Calculate the `q`-expansion of the `p`-adic Eisenstein series of given weight-character, normalised so the constant term is 1. EXAMPLES:: @@ -393,7 +393,7 @@ def values_on_gens(self): def is_trivial(self) -> bool: r""" - Return True if and only if this is the trivial character. + Return ``True`` if and only if this is the trivial character. EXAMPLES:: @@ -424,7 +424,7 @@ def _richcmp_(self, other, op) -> bool: def Lvalue(self): r""" - Return the value of the p-adic L-function of `\QQ`, which can be + Return the value of the `p`-adic `L`-function of `\QQ`, which can be regarded as a rigid-analytic function on weight space, evaluated at this character. @@ -440,10 +440,10 @@ def Lvalue(self): def one_over_Lvalue(self): r""" - Return the reciprocal of the p-adic L-function evaluated at this + Return the reciprocal of the `p`-adic `L`-function evaluated at this weight-character. - If the weight-character is odd, then the L-function + If the weight-character is odd, then the `L`-function is zero, so an error will be raised. EXAMPLES:: @@ -526,7 +526,7 @@ def __call__(self, x): sage: kappa(13 + 4*29 + 11*29^2 + O(29^3)) 9 + 21*29 + 27*29^2 + O(29^3) - When the character chi is defined over a p-adic field, the results returned are inexact:: + When the character chi is defined over a `p`-adic field, the results returned are inexact:: sage: kappa = pAdicWeightSpace(29)(13, DirichletGroup(29, Qp(29)).0^14) sage: kappa(1) @@ -648,13 +648,13 @@ def teichmuller_type(self): def Lvalue(self): r""" - Return the value of the p-adic L-function of `\QQ` evaluated at + Return the value of the `p`-adic `L`-function of `\QQ` evaluated at this weight-character. If the character is `x \mapsto x^k \chi(x)` where `k > 0` and `\chi` has conductor a power of `p`, this is an element of the number field generated by the values of `\chi`, equal to - the value of the complex L-function `L(1-k, \chi)`. If `\chi` is + the value of the complex `L`-function `L(1-k, \chi)`. If `\chi` is trivial, it is equal to `(1 - p^{k-1})\zeta(1-k)`. At present this is not implemented in any other cases, except the @@ -689,10 +689,10 @@ class ArbitraryWeight(WeightCharacter): def __init__(self, parent, w, t): r""" - Create the element of p-adic weight space in the given component + Create the element of `p`-adic weight space in the given component mapping 1 + p to w. - Here w must be an element of a p-adic field, with finite + Here w must be an element of a `p`-adic field, with finite precision. EXAMPLES:: diff --git a/src/sage/modular/pollack_stevens/dist.pyx b/src/sage/modular/pollack_stevens/dist.pyx index 9a05c4ad758..85cccd3bb11 100644 --- a/src/sage/modular/pollack_stevens/dist.pyx +++ b/src/sage/modular/pollack_stevens/dist.pyx @@ -3,7 +3,7 @@ """ `p`-adic distributions spaces -This module implements p-adic distributions, a `p`-adic Banach +This module implements `p`-adic distributions, a `p`-adic Banach space dual to locally analytic functions on a disc. EXAMPLES:: @@ -56,17 +56,17 @@ def get_dist_classes(p, prec_cap, base, symk, implementation): INPUT: - - ``p`` -- prime + - ``p`` -- prime - - ``prec_cap`` -- The `p`-adic precision cap + - ``prec_cap`` -- the `p`-adic precision cap - - ``base`` -- The base ring + - ``base`` -- the base ring - - ``symk`` -- An element of Symk + - ``symk`` -- an element of Symk - - ``implementation`` -- string; If not None, override the + - ``implementation`` -- string; if not ``None``, override the automatic choice of implementation. May be 'long' or 'vector', - otherwise raise a :class:`NotImplementedError` + otherwise raise a :exc:`NotImplementedError`. OUTPUT: @@ -99,7 +99,7 @@ cdef class Dist(ModuleElement): INPUT: - - ``n`` -- an integer or slice, to be passed on to moments. + - ``n`` -- integer or slice, to be passed on to moments OUTPUT: @@ -121,9 +121,7 @@ cdef class Dist(ModuleElement): r""" Return the vector of moments. - OUTPUT: - - - the vector of moments + OUTPUT: the vector of moments EXAMPLES:: @@ -142,9 +140,7 @@ cdef class Dist(ModuleElement): Normalize so that the precision of the `i`-th moment is `n-i`, where `n` is the number of moments. - OUTPUT: - - - Normalized entries of the distribution + OUTPUT: normalized entries of the distribution EXAMPLES:: @@ -184,15 +180,13 @@ cdef class Dist(ModuleElement): def scale(self, left): r""" - Scale the moments of the distribution by ``left`` + Scale the moments of the distribution by ``left``. INPUT: - ``left`` -- scalar - OUTPUT: - - - Scales the moments by ``left`` + OUTPUT: scales the moments by ``left`` EXAMPLES:: @@ -219,8 +213,9 @@ cdef class Dist(ModuleElement): def is_zero(self, p=None, M=None): r""" - Return True if the `i`-th moment is zero for all `i` (case ``M`` is None) - or zero modulo `p^{M-i}` for all `i` (when ``M`` is not None). + Return ``True`` if the `i`-th moment is zero for all `i` (case ``M`` is + ``None``) or zero modulo `p^{M-i}` for all `i` (when ``M`` is not + ``None``). Note that some moments are not known to precision ``M``, in which case they are only checked to be equal to zero modulo the @@ -232,9 +227,7 @@ cdef class Dist(ModuleElement): - ``M`` -- precision - OUTPUT: - - - True/False + OUTPUT: boolean EXAMPLES:: @@ -292,9 +285,9 @@ cdef class Dist(ModuleElement): def find_scalar(self, _other, p, M=None, check=True): r""" Return an ``alpha`` with ``other = self * alpha``, or raises - a :class:`ValueError`. + a :exc:`ValueError`. - It will also raise a :class:`ValueError` if this distribution is zero. + It will also raise a :exc:`ValueError` if this distribution is zero. INPUT: @@ -302,15 +295,13 @@ cdef class Dist(ModuleElement): - ``p`` -- an integral prime (only used if the parent is not a Symk) - - ``M`` -- (default: None) an integer, the relative precision + - ``M`` -- (default: ``None``) an integer, the relative precision to which the scalar must be determined - - ``check`` -- (default: ``True``) boolean, whether to validate - that ``other`` is actually a multiple of this element. - - OUTPUT: + - ``check`` -- boolean (default: ``True``); whether to validate + that ``other`` is actually a multiple of this element - - A scalar ``alpha`` with ``other = self * alpha``. + OUTPUT: a scalar ``alpha`` with ``other = self * alpha`` EXAMPLES:: @@ -416,9 +407,9 @@ cdef class Dist(ModuleElement): def find_scalar_from_zeroth_moment(self, _other, p, M=None, check=True): r""" Return an ``alpha`` with ``other = self * alpha`` using only - the zeroth moment, or raises a :class:`ValueError`. + the zeroth moment, or raises a :exc:`ValueError`. - It will also raise a :class:`ValueError` if the zeroth moment of the + It will also raise a :exc:`ValueError` if the zeroth moment of the distribution is zero. INPUT: @@ -427,15 +418,13 @@ cdef class Dist(ModuleElement): - ``p`` -- an integral prime (only used if the parent is not a Symk) - - ``M`` -- (default: None) an integer, the relative precision + - ``M`` -- (default: ``None``) an integer, the relative precision to which the scalar must be determined - - ``check`` -- (default: ``True``) boolean, whether to validate - that ``other`` is actually a multiple of this element. - - OUTPUT: + - ``check`` -- boolean (default: ``True``); whether to validate + that ``other`` is actually a multiple of this element - - A scalar ``alpha`` with ``other = self * alpha``. + OUTPUT: a scalar ``alpha`` with ``other = self * alpha`` EXAMPLES:: @@ -538,12 +527,12 @@ cdef class Dist(ModuleElement): INPUT: - - ``p`` -- (default: None) a positive integral prime + - ``p`` -- (default: ``None``) a positive integral prime OUTPUT: - - the largest integer `m` so that `p^m` divides the `0`-th - moment, `p^{m-1}` divides the first moment, etc. + The largest integer `m` so that `p^m` divides the `0`-th + moment, `p^{m-1}` divides the first moment, etc. EXAMPLES:: @@ -565,11 +554,9 @@ cdef class Dist(ModuleElement): INPUT: - - ``p`` -- (default: None) a positive integral prime + - ``p`` -- (default: ``None``) a positive integral prime - OUTPUT: - - - an integer + OUTPUT: integer .. WARNING:: @@ -603,12 +590,12 @@ cdef class Dist(ModuleElement): INPUT: - - ``new_base_ring`` -- (default: None) a ring giving the - desired base ring of the result. + - ``new_base_ring`` -- (default: ``None``) a ring giving the + desired base ring of the result OUTPUT: - - An element of `Sym^k(K)`, where `K` is the specified base ring. + An element of `Sym^k(K)`, where `K` is the specified base ring. EXAMPLES:: @@ -635,15 +622,15 @@ cdef class Dist(ModuleElement): INPUT: - - ``p`` -- (default: None) a positive integral prime. If None - then ``p`` must be available in the parent. + - ``p`` -- (default: ``None``) a positive integral prime. If ``None`` + then ``p`` must be available in the parent - - ``M`` -- (default: None) a positive integer giving the - desired number of moments. If None, returns a distribution having one + - ``M`` -- (default: ``None``) a positive integer giving the + desired number of moments. If ``None``, returns a distribution having one more moment than this one. - - ``new_base_ring`` -- (default: None) a ring giving the desired base - ring of the result. If None, a base ring is chosen automatically. + - ``new_base_ring`` -- (default: ``None``) a ring giving the desired base + ring of the result. If ``None``, a base ring is chosen automatically. OUTPUT: @@ -738,10 +725,10 @@ cdef class Dist_vector(Dist): - ``parent`` -- a :class:`distributions.OverconvergentDistributions_class` or :class:`distributions.Symk_class` instance - - ``ordp`` -- an integer. This MUST be zero in the case of Symk - of an exact ring. + - ``ordp`` -- integer; this *must* be zero in the case of Symk + of an exact ring - - ``check`` -- (default: ``True``) boolean, whether to validate input + - ``check`` -- boolean (default: ``True``); whether to validate input EXAMPLES:: @@ -756,7 +743,6 @@ cdef class Dist_vector(Dist): sage: Symk(4)(0) (0, 0, 0, 0, 0) - """ # if not hasattr(parent,'Element'): # parent, moments = moments, parent @@ -801,7 +787,7 @@ cdef class Dist_vector(Dist): cdef Dist_vector _new_c(self): r""" - Creates an empty distribution. + Create an empty distribution. Note that you MUST fill in the ordp attribute on the resulting distribution. @@ -852,7 +838,7 @@ cdef class Dist_vector(Dist): sage: QQ(d) 4/3 - We get a :class:`TypeError` if there is more than 1 moment:: + We get a :exc:`TypeError` if there is more than 1 moment:: sage: D = Symk(1); d = D([1,2]); d (1, 2) @@ -875,7 +861,6 @@ cdef class Dist_vector(Dist): sage: d = D([1,2,3,4,5]); e = D([2,3,4,5,6]) sage: d == e # indirect doctest False - """ return len(self._moments) @@ -895,7 +880,7 @@ cdef class Dist_vector(Dist): cdef Dist_vector _addsub(self, Dist_vector right, bint negate): r""" - Common code for the sum and the difference of two distributions + Common code for the sum and the difference of two distributions. EXAMPLES:: @@ -905,7 +890,6 @@ cdef class Dist_vector(Dist): (5, 7, 9) sage: u - v # indirect doctest (-3, -3, -3) - """ cdef Dist_vector ans = self._new_c() cdef long aprec = min(self.ordp + len(self._moments), right.ordp + len(right._moments)) @@ -1002,9 +986,7 @@ cdef class Dist_vector(Dist): distributions, the precision is the integer `m` so that the sequence of moments is known modulo `Fil^m`. - OUTPUT: - - - An integer giving the number of moments. + OUTPUT: integer giving the number of moments EXAMPLES:: @@ -1051,9 +1033,7 @@ cdef class Dist_vector(Dist): parent is a space of distributions, then normalize reduces the `i`-th moment modulo `p^{N-i}`. - OUTPUT: - - - this distribution, after normalizing. + OUTPUT: this distribution, after normalizing .. WARNING:: @@ -1099,8 +1079,8 @@ cdef class Dist_vector(Dist): INPUT: - - ``M`` -- a positive integer less than the precision of this - distribution. + - ``M`` -- positive integer less than the precision of this + distribution OUTPUT: @@ -1209,10 +1189,10 @@ cdef class WeightKAction(Action): See the documentation of :class:`sage.modular.pollack_stevens.distributions.OverconvergentDistributions_factory` for more details. - - ``adjuster`` -- a callable object that turns matrices into 4-tuples. - - ``on_left`` -- whether this action should be on the left. + - ``adjuster`` -- a callable object that turns matrices into 4-tuples + - ``on_left`` -- whether this action should be on the left - ``dettwist`` -- a power of the determinant to twist by - - ``padic`` -- if True, define an action of `p`-adic matrices (not just integer ones) + - ``padic`` -- if ``True``, define an action of `p`-adic matrices (not just integer ones) EXAMPLES:: @@ -1278,8 +1258,8 @@ cdef class WeightKAction(Action): - ``g`` -- an instance of :class:`sage.matrix.matrix_generic_dense.Matrix_generic_dense` - - ``M`` -- a positive integer giving the precision at which - ``g`` should act. + - ``M`` -- positive integer giving the precision at which + ``g`` should act OUTPUT: @@ -1336,8 +1316,8 @@ cdef class WeightKAction(Action): - ``g`` -- a `2 \times 2` instance of :class:`sage.matrices.matrix_integer_dense.Matrix_integer_dense` - - ``M`` -- a positive integer giving the precision at which - ``g`` should act. + - ``M`` -- positive integer giving the precision at which + ``g`` should act OUTPUT: @@ -1365,8 +1345,8 @@ cdef class WeightKAction_vector(WeightKAction): - ``g`` -- a `2 \times 2` instance of :class:`sage.matrix.matrix_generic_dense.Matrix_generic_dense` - - ``M`` -- a positive integer giving the precision at which - ``g`` should act. + - ``M`` -- positive integer giving the precision at which + ``g`` should act OUTPUT: @@ -1425,14 +1405,12 @@ cdef class WeightKAction_vector(WeightKAction): INPUT: - ``_v`` -- a :class:`Dist_vector` instance, the distribution - on which to act. + on which to act - ``g`` -- a `2 \times 2` instance of - :class:`sage.matrix.matrix_integer_dense.Matrix_integer_dense`. + :class:`sage.matrix.matrix_integer_dense.Matrix_integer_dense` - OUTPUT: - - - the distribution ``_v * g``. + OUTPUT: the distribution ``_v * g`` EXAMPLES:: @@ -1441,7 +1419,6 @@ cdef class WeightKAction_vector(WeightKAction): sage: g = Matrix(ZZ,2,2,[3,-1,1,0]) sage: v * D._act.actor()(g) # indirect doctest (40, -9, 2) - """ # if g is a matrix it needs to be immutable # hashing on arithmetic_subgroup_elements is by str diff --git a/src/sage/modular/pollack_stevens/distributions.py b/src/sage/modular/pollack_stevens/distributions.py index a11240613fb..80bc25b22d9 100644 --- a/src/sage/modular/pollack_stevens/distributions.py +++ b/src/sage/modular/pollack_stevens/distributions.py @@ -63,16 +63,16 @@ class OverconvergentDistributions_factory(UniqueFactory): INPUT: - ``k`` -- nonnegative integer - - ``p`` -- prime number or None - - ``prec_cap`` -- positive integer or None - - ``base`` -- ring or None - - ``character`` -- a Dirichlet character or None - - ``adjuster`` -- None or callable that turns 2 x 2 matrices into a 4-tuple - - ``act_on_left`` -- bool (default: ``False``) - - ``dettwist`` -- integer or None (interpreted as 0) + - ``p`` -- prime number or ``None`` + - ``prec_cap`` -- positive integer or ``None`` + - ``base`` -- ring or ``None`` + - ``character`` -- a Dirichlet character or ``None`` + - ``adjuster`` -- ``None`` or callable that turns 2 x 2 matrices into a 4-tuple + - ``act_on_left`` -- boolean (default: ``False``) + - ``dettwist`` -- integer or ``None`` (interpreted as 0) - ``act_padic`` -- whether monoid should allow `p`-adic coefficients - - ``implementation`` -- string (default: None). - Either None (for automatic), 'long', or 'vector' + - ``implementation`` -- string (default: ``None``); either ``None`` (for + automatic), ``'long'``, or ``'vector'`` EXAMPLES:: @@ -152,14 +152,16 @@ class Symk_factory(UniqueFactory): INPUT: - - ``k`` -- (integer): the degree (degree `k` corresponds to weight `k + 2` modular forms) - - ``base`` -- (ring, default None): the base ring (None is interpreted as `\QQ`) - - ``character`` -- (Dirichlet character or None, default None) the character - - ``adjuster`` -- (None or a callable that turns - `2 \times 2` matrices into a 4-tuple, default None) - - ``act_on_left`` -- (boolean, default: ``False``) whether to have the group acting - on the left rather than the right. - - ``dettwist`` (integer or None) -- power of determinant to twist by + - ``k`` -- integer; the degree (degree `k` corresponds to weight `k + 2` + modular forms) + - ``base`` -- ring (default: ``None``); the base ring (``None`` is + interpreted as `\QQ`) + - ``character`` -- Dirichlet character or ``None`` (default: ``None``) + - ``adjuster`` -- ``None`` or a callable that turns `2 \times 2` matrices + into a 4-tuple (default: ``None``) + - ``act_on_left`` -- boolean (default: ``False``); whether to have the + group acting on the left rather than the right + - ``dettwist`` -- integer or ``None``; power of determinant to twist by EXAMPLES:: @@ -234,18 +236,18 @@ class OverconvergentDistributions_abstract(Module): INPUT: - - ``k`` -- integer; `k` is the usual modular forms weight minus 2 - - ``p`` -- None or prime - - ``prec_cap`` -- None or positive integer - - ``base`` -- None or the base ring over which to construct the distributions - - ``character`` -- None or Dirichlet character - - ``adjuster`` -- None or a way to specify the action among different conventions - - ``act_on_left`` -- bool (default: ``False``) - - ``dettwist`` -- None or integer (twist by determinant). Ignored for Symk spaces - - ``act_padic`` -- bool (default: ``False``) If true, will allow - action by `p`-adic matrices. - - ``implementation`` -- string (default: None) Either automatic (if None), - 'vector' or 'long'. + - ``k`` -- integer; `k` is the usual modular forms weight minus 2 + - ``p`` -- ``None`` or prime + - ``prec_cap`` -- ``None`` or positive integer + - ``base`` -- ``None`` or the base ring over which to construct the distributions + - ``character`` -- ``None`` or Dirichlet character + - ``adjuster`` -- ``None`` or a way to specify the action among different conventions + - ``act_on_left`` -- boolean (default: ``False``) + - ``dettwist`` -- ``None`` or integer (twist by determinant); ignored for Symk spaces + - ``act_padic`` -- boolean (default: ``False``); if ``True``, will allow + action by `p`-adic matrices + - ``implementation`` -- string (default: ``None``); either automatic (if ``None``), + ``'vector'`` or ``'long'`` EXAMPLES:: @@ -307,7 +309,7 @@ def __init__(self, k, p=None, prec_cap=None, base=None, character=None, def _element_constructor_(self, val, **kwargs): """ - Construct a distribution from data in ``val`` + Construct a distribution from data in ``val``. EXAMPLES:: @@ -378,9 +380,7 @@ def prime(self): In case this space is Symk of a non-padic field, we return 0. - OUTPUT: - - - a prime or 0 + OUTPUT: a prime or 0 EXAMPLES:: @@ -412,9 +412,7 @@ def weight(self): The standard caveat applies, namely that the weight of `Sym^k` is defined to be `k`, not `k+2`. - OUTPUT: - - nonnegative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -453,9 +451,9 @@ def lift(self, p=None, M=None, new_base_ring=None): INPUT: - - ``p`` -- prime or None - - ``M`` -- nonnegative integer or None - - ``new_base_ring`` -- ring or None + - ``p`` -- prime or ``None`` + - ``M`` -- nonnegative integer or ``None`` + - ``new_base_ring`` -- ring or ``None`` EXAMPLES:: @@ -502,7 +500,8 @@ def approx_module(self, M=None): INPUT: - - ``M`` -- None or nonnegative integer that is at most the precision cap + - ``M`` -- ``None`` or nonnegative integer that is at most the + precision cap EXAMPLES:: @@ -540,11 +539,11 @@ def approx_module(self, M=None): def random_element(self, M=None, **args): """ Return a random element of the `M`-th approximation module with - non-negative valuation. + nonnegative valuation. INPUT: - - ``M`` -- None or a nonnegative integer + - ``M`` -- ``None`` or a nonnegative integer EXAMPLES:: @@ -591,8 +590,8 @@ def basis(self, M=None): INPUT: - - ``M`` -- (Default: None) If not None, specifies the ``M``-th approximation module, - in case that this makes sense. + - ``M`` -- (default: ``None``) if not ``None``, specifies the ``M``-th + approximation module, in case that this makes sense EXAMPLES:: @@ -620,7 +619,7 @@ def basis(self, M=None): def _an_element_(self): """ - Return a typical element of self. + Return a typical element of ``self``. EXAMPLES:: @@ -681,7 +680,6 @@ def _repr_(self): Sym^6 Q^2 twisted by Dirichlet character modulo 7 of conductor 7 mapping 3 |--> -1 sage: Symk(6,character=DirichletGroup(7,QQ).0,dettwist=3) Sym^6 Q^2 * det^3 twisted by Dirichlet character modulo 7 of conductor 7 mapping 3 |--> -1 - """ if self.base_ring() is QQ: V = 'Q^2' @@ -757,7 +755,7 @@ def base_extend(self, new_base_ring): class OverconvergentDistributions_class(OverconvergentDistributions_abstract): r""" - The class of overconvergent distributions + The class of overconvergent distributions. This class represents the module of finite approximation modules, which are finite-dimensional spaces with a `\Sigma_0(N)` action which approximate the module of overconvergent distributions. @@ -827,7 +825,9 @@ def change_ring(self, new_base_ring): """ Return space of distributions like this one, but with the base ring changed. - INPUT: a ring over which the distribution can be coerced. + INPUT: + + - ``new_base_ring`` -- a ring over which the distribution can be coerced EXAMPLES:: diff --git a/src/sage/modular/pollack_stevens/fund_domain.py b/src/sage/modular/pollack_stevens/fund_domain.py index 40ebcc84fc1..c9b61b36546 100644 --- a/src/sage/modular/pollack_stevens/fund_domain.py +++ b/src/sage/modular/pollack_stevens/fund_domain.py @@ -38,7 +38,9 @@ def M2Z(x): r""" Create an immutable `2 \times 2` integer matrix from ``x``. - INPUT: anything that can be converted into a `2 \times 2` matrix. + INPUT: + + - ``x`` -- anything that can be converted into a `2 \times 2` matrix EXAMPLES:: @@ -73,21 +75,21 @@ class PollackStevensModularDomain(SageObject): INPUT: - - ``N`` -- a positive integer, the level of the congruence subgroup + - ``N`` -- positive integer, the level of the congruence subgroup `\Gamma_0(N)` - - ``reps`` -- a list of `2 \times 2` matrices, the coset + - ``reps`` -- list of `2 \times 2` matrices, the coset representatives of `Div^0(P^1(\QQ))` - - ``indices`` -- a list of integers; indices of elements in + - ``indices`` -- list of integers; indices of elements in ``reps`` which are generators - - ``rels`` -- a list of list of triples ``(d, A, i)``, one for each + - ``rels`` -- list of list of triples ``(d, A, i)``, one for each coset representative of ``reps`` which describes how to express the elements of ``reps`` in terms of generators specified by ``indices``. See :meth:`relations` for a detailed explanations of these triples. - - ``equiv_ind`` -- a dictionary which maps normalized coordinates on + - ``equiv_ind`` -- dictionary which maps normalized coordinates on `P^1(\ZZ/N\ZZ)` to an integer such that a matrix whose bottom row is equivalent to `[a:b]` in `P^1(\ZZ/N\ZZ)` is in the coset of ``reps[equiv_ind[(a,b)]]`` @@ -110,13 +112,12 @@ class PollackStevensModularDomain(SageObject): Traceback (most recent call last): ... TypeError: unable to coerce to an integer - """ def __init__(self, N, reps, indices, rels, equiv_ind): r""" INPUT: - See :class:`PollackStevensModularDomain`. + See :class:`PollackStevensModularDomain`. EXAMPLES:: @@ -220,11 +221,11 @@ def gens(self): def gen(self, n=0): r""" - Return the ``n``-th generator. + Return the `n`-th generator. INPUT: - - ``n`` -- integer (default: 0), which generator is desired + - ``n`` -- integer (default: 0); which generator is desired EXAMPLES:: @@ -283,7 +284,7 @@ def indices(self, n=None): INPUT: - - ``n`` -- integer (default: None) + - ``n`` -- integer (default: ``None``) OUTPUT: @@ -320,7 +321,7 @@ def reps(self, n=None): INPUT: - - ``n`` -- integer (default: None) + - ``n`` -- integer (default: ``None``) OUTPUT: @@ -368,7 +369,7 @@ def relations(self, A=None): A `\ZZ[\Gamma_0(N)]`-relation expressing the divisor attached to ``A`` in terms of the generating set. The relation is given as a list of - triples ``(d, B, i)`` such that the divisor attached to `A`` is the sum + triples ``(d, B, i)`` such that the divisor attached to ``A`` is the sum of ``d`` times the divisor attached to ``B^{-1} * self.reps(i)``. If ``A`` is an integer, then return this data for the ``A``-th @@ -535,7 +536,6 @@ def P1(self): sage: A = ManinRelations(11) sage: A.P1() The projective line over the integers modulo 11 - """ return self._P @@ -547,7 +547,7 @@ class ManinRelations(PollackStevensModularDomain): INPUT: - - ``N`` -- a positive integer, the level of `\Gamma_0(N)` to work with + - ``N`` -- positive integer, the level of `\Gamma_0(N)` to work with EXAMPLES:: @@ -576,7 +576,6 @@ class ManinRelations(PollackStevensModularDomain): Traceback (most recent call last): ... ValueError: N must be a positive integer - """ def __init__(self, N): r""" @@ -584,7 +583,7 @@ def __init__(self, N): INPUT: - - ``N`` -- a positive integer, the level of `\Gamma_0(N)` to work with + - ``N`` -- positive integer; the level of `\Gamma_0(N)` to work with EXAMPLES:: @@ -895,9 +894,7 @@ def indices_with_two_torsion(self): contains a point fixed by a `\Gamma_0(N)` element of order 2 (where the order is computed in `PSL_2(\ZZ)`). - OUTPUT: - - A list of integers. + OUTPUT: list of integers EXAMPLES:: @@ -940,9 +937,7 @@ def reps_with_two_torsion(self): point fixed by a `\Gamma_0(N)` element of order 2 (where the order is computed in `PSL_2(\ZZ)`). - OUTPUT: - - A list of matrices. + OUTPUT: list of matrices EXAMPLES:: @@ -1310,9 +1305,7 @@ def unimod_to_matrices(self, r1, r2): - ``r1``, ``r2`` -- rational numbers (that are assumed to be connected by a unimodular path) - OUTPUT: - - A pair of `2 \times 2` matrices of determinant 1 + OUTPUT: a pair of `2 \times 2` matrices of determinant 1 EXAMPLES:: @@ -1346,7 +1339,7 @@ def fd_boundary(self, C): INPUT: - - ``C`` -- a list of rational numbers coming from + - ``C`` -- list of rational numbers coming from ``self.form_list_of_cusps()`` OUTPUT: @@ -1549,12 +1542,10 @@ def basic_hecke_matrix(a, l): INPUT: - - `a` -- an integer or Infinity + - ``a`` -- integer or Infinity - ``l`` -- a prime - OUTPUT: - - A `2 \times 2` matrix of determinant l + OUTPUT: a `2 \times 2` matrix of determinant l EXAMPLES:: diff --git a/src/sage/modular/pollack_stevens/manin_map.py b/src/sage/modular/pollack_stevens/manin_map.py index b90d95c27f7..94ba0843131 100644 --- a/src/sage/modular/pollack_stevens/manin_map.py +++ b/src/sage/modular/pollack_stevens/manin_map.py @@ -85,7 +85,6 @@ def unimod_matrices_to_infty(r, s): This is Manin's continued fraction trick, which gives an expression `\{0,r/s\} = \{0,\infty\} + ... + \{a,b\} + ... + \{*,r/s\}`, where each `\{a,b\}` is the image of `\{0,\infty\}` under a matrix in `SL_2(\ZZ)`. - """ if s == 0: return [] @@ -140,7 +139,6 @@ def unimod_matrices_from_infty(r, s): This is Manin's continued fraction trick, which gives an expression `\{\infty,r/s\} = \{\infty,0\} + ... + \{a,b\} + ... + \{*,r/s\}`, where each `\{a,b\}` is the image of `\{0,\infty\}` under a matrix in `SL_2(\ZZ)`. - """ if s != 0: L = convergents(r / s) @@ -170,12 +168,13 @@ class ManinMap(): INPUT: - ``codomain`` -- coefficient module - - ``manin_relations`` -- a :class:`sage.modular.pollack_stevens.fund_domain.ManinRelations` object - - ``defining_data`` -- a dictionary whose keys are a superset of + - ``manin_relations`` -- a :class:`sage.modular.pollack_stevens.fund_domain.ManinRelations` + object + - ``defining_data`` -- dictionary whose keys are a superset of ``manin_relations.gens()`` and a subset of ``manin_relations.reps()``, - and whose values are in the codomain. + and whose values are in the codomain - ``check`` -- do numerous (slow) checks and transformations to - ensure that the input data is perfect. + ensure that the input data is perfect EXAMPLES:: @@ -194,11 +193,11 @@ def __init__(self, codomain, manin_relations, defining_data, check=True): - ``codomain`` -- coefficient module - ``manin_relations`` -- a :class:`ManinRelations` object - - ``defining_data`` -- a dictionary whose keys are a superset of + - ``defining_data`` -- dictionary whose keys are a superset of :meth:`manin_relations.gens()` and a subset of manin_relations.reps(), - and whose values are in the codomain. + and whose values are in the codomain - ``check`` -- do numerous (slow) checks and transformations to - ensure that the input data is perfect. + ensure that the input data is perfect TESTS: @@ -243,7 +242,9 @@ def __init__(self, codomain, manin_relations, defining_data, check=True): def extend_codomain(self, new_codomain, check=True): r""" - Extend the codomain of self to new_codomain. There must be a valid conversion operation from the old to the new codomain. This is most often used for extension of scalars from `\QQ` to `\QQ_p`. + Extend the codomain of ``self`` to ``new_codomain``. There must be a + valid conversion operation from the old to the new codomain. This is + most often used for extension of scalars from `\QQ` to `\QQ_p`. EXAMPLES:: @@ -268,11 +269,12 @@ def _compute_image_from_gens(self, B): INPUT: - - ``B`` -- generator of Manin relations. + - ``B`` -- generator of Manin relations OUTPUT: - - an element in the codomain of self (e.g. a distribution), the image of ``B`` under ``self``. + An element in the codomain of ``self`` (e.g. a distribution), the image + of ``B`` under ``self``. EXAMPLES:: @@ -300,11 +302,12 @@ def __getitem__(self, B): INPUT: - - ``B`` -- coset representative of Manin relations. + - ``B`` -- coset representative of Manin relations OUTPUT: - - an element in the codomain of self (e.g. a distribution), the image of ``B`` under ``self``. + An element in the codomain of ``self`` (e.g. a distribution), the image + of ``B`` under ``self``. EXAMPLES:: @@ -342,7 +345,8 @@ def __getitem__(self, B): def compute_full_data(self): r""" - Compute the values of self on all coset reps from its values on our generating set. + Compute the values of ``self`` on all coset reps from its values on our + generating set. EXAMPLES:: @@ -372,16 +376,15 @@ def compute_full_data(self): def __add__(self, right): r""" - Return sum self + right, where self and right are + Return sum ``self + right``, where ``self`` and ``right`` are assumed to have identical codomains and Manin relations. INPUT: - - ``self`` and ``right`` -- two Manin maps with the same codomain and Manin relations. - - OUTPUT: + - ``self``, ``right`` -- two Manin maps with the same codomain and + Manin relations - - the sum of ``self`` and ``right`` -- a Manin map + OUTPUT: the sum of ``self`` and ``right`` -- a Manin map EXAMPLES:: @@ -409,16 +412,15 @@ def __add__(self, right): def __sub__(self, right): """ - Return difference self - right, where self and right are + Return difference ``self`` - right, where ``self`` and ``right`` are assumed to have identical codomains and Manin relations. INPUT: - - ``self`` and ``right`` -- two Manin maps with the same codomain and Manin relations. + - ``self``, ``right`` -- two Manin maps with the same codomain and + Manin relations - OUTPUT: - - - the difference of ``self`` and ``right`` -- a Manin map + OUTPUT: the difference of ``self`` and ``right`` -- a Manin map EXAMPLES:: @@ -446,17 +448,15 @@ def __sub__(self, right): def __mul__(self, right): """ - Return scalar multiplication self * right, where right is in the - base ring of the codomain. + Return scalar multiplication ``self * right``, where ``right`` is in + the base ring of the codomain. INPUT: - - ``self`` -- a Manin map. - - ``right`` -- an element of the base ring of the codomain of self. - - OUTPUT: + - ``self`` -- a Manin map + - ``right`` -- an element of the base ring of the codomain of self - - the sum ``self`` and ``right`` -- a Manin map + OUTPUT: the sum ``self`` and ``right`` -- a Manin map EXAMPLES:: @@ -483,7 +483,7 @@ def __mul__(self, right): def __repr__(self): """ - Return string representation of self. + Return string representation of ``self``. EXAMPLES:: @@ -499,7 +499,7 @@ def __repr__(self): def _eval_sl2(self, A): r""" - Return the value of self on the unimodular divisor corresponding to `A`. + Return the value of ``self`` on the unimodular divisor corresponding to `A`. Note that `A` must be in `SL_2(Z)` for this to work. @@ -509,7 +509,8 @@ def _eval_sl2(self, A): OUTPUT: - The value of self on the divisor corresponding to `A` -- i.e. on the divisor `\{A(0)\} - \{A(\infty)\}`. + The value of ``self`` on the divisor corresponding to `A` -- i.e. on + the divisor `\{A(0)\} - \{A(\infty)\}`. EXAMPLES:: @@ -531,15 +532,14 @@ def _eval_sl2(self, A): def __call__(self, A): """ - Evaluate self at A. + Evaluate ``self`` at A. INPUT: - ``A`` -- a `2 \times 2` matrix - OUTPUT: - - The value of self on the divisor corresponding to ``A`` -- an element of the codomain of self. + OUTPUT: the value of ``self`` on the divisor corresponding to ``A`` -- + an element of the codomain of self EXAMPLES:: @@ -592,9 +592,11 @@ def apply(self, f, codomain=None, to_moments=False): INPUT: - - ``f`` -- anything that can be called with elements of the coefficient module - - ``codomain`` -- (default: None) the codomain of the return map - - ``to_moments`` -- (default: ``False``) if True, will apply ``f`` to each of the moments instead + - ``f`` -- anything that can be called with elements of the coefficient + module + - ``codomain`` -- (default: ``None``) the codomain of the return map + - ``to_moments`` -- boolean (default: ``False``); if ``True``, will + apply ``f`` to each of the moments instead EXAMPLES:: @@ -657,9 +659,7 @@ def _right_action(self, gamma): - ``gamma`` -- `2 \times 2` integer matrix of nonzero determinant, with a well-defined action on the coefficient module - OUTPUT: - - - the image of self under the action of `\gamma` -- a Manin map. + OUTPUT: the image of ``self`` under the action of `\gamma` -- a Manin map EXAMPLES:: @@ -692,8 +692,8 @@ def _right_action(self, gamma): def normalize(self): r""" - Normalize every value of self -- e.g., reduces each value's - `j`-th moment modulo `p^{N-j}` + Normalize every value of ``self`` -- e.g., reduce each value's + `j`-th moment modulo `p^{N-j}`. EXAMPLES:: @@ -719,7 +719,7 @@ def reduce_precision(self, M): INPUT: - - ``M`` -- an integer, the new precision. + - ``M`` -- integer; the new precision EXAMPLES:: @@ -770,13 +770,9 @@ def hecke(self, ell, algorithm='prep'): - ``ell`` -- a prime - - ``algorithm`` -- a string, either 'prep' (default) or - 'naive' + - ``algorithm`` -- string; either ``'prep'`` (default) or ``'naive'`` - OUTPUT: - - - The image of this ManinMap under the Hecke operator - `T_{\ell}` + OUTPUT: the image of this ManinMap under the Hecke operator `T_{\ell}` EXAMPLES:: @@ -817,20 +813,18 @@ def hecke(self, ell, algorithm='prep'): def p_stabilize(self, p, alpha, V): r""" - Return the `p`-stabilization of self to level `N*p` on which + Return the `p`-stabilization of ``self`` to level `N*p` on which `U_p` acts by `\alpha`. INPUT: - - ``p`` -- a prime. + - ``p`` -- a prime - - ``alpha`` -- a `U_p`-eigenvalue. + - ``alpha`` -- a `U_p`-eigenvalue - - ``V`` -- a space of modular symbols. - - OUTPUT: + - ``V`` -- a space of modular symbols - - The image of this ManinMap under the Hecke operator `T_{\ell}` + OUTPUT: the image of this ManinMap under the Hecke operator `T_{\ell}` EXAMPLES:: diff --git a/src/sage/modular/pollack_stevens/modsym.py b/src/sage/modular/pollack_stevens/modsym.py index 9217c186156..c892748174d 100644 --- a/src/sage/modular/pollack_stevens/modsym.py +++ b/src/sage/modular/pollack_stevens/modsym.py @@ -62,8 +62,8 @@ def _iterate_Up(Phi, p, M, ap, q, aq, check): r""" - Return an overconvergent Hecke-eigensymbol lifting self -- self must be a - `p`-ordinary eigensymbol + Return an overconvergent Hecke-eigensymbol lifting ``self`` -- ``self`` + must be a `p`-ordinary eigensymbol. INPUT: @@ -77,9 +77,7 @@ def _iterate_Up(Phi, p, M, ap, q, aq, check): - ``aq`` -- Hecke eigenvalue at `q` - OUTPUT: - - - Hecke-eigenvalue overconvergent modular symbol lifting self. + OUTPUT: Hecke-eigenvalue overconvergent modular symbol lifting ``self`` EXAMPLES:: @@ -119,7 +117,7 @@ def _iterate_Up(Phi, p, M, ap, q, aq, check): class PSModSymAction(Action): def __init__(self, actor, MSspace): r""" - Create the action + Create the action. EXAMPLES:: @@ -134,7 +132,7 @@ def __init__(self, actor, MSspace): def _act_(self, g, sym): r""" - Return the result of sym * g + Return the result of ``sym * g``. EXAMPLES:: @@ -151,7 +149,7 @@ def _act_(self, g, sym): class PSModularSymbolElement(ModuleElement): def __init__(self, map_data, parent, construct=False): r""" - Initialize a modular symbol + Initialize a modular symbol. EXAMPLES:: @@ -179,7 +177,9 @@ def _repr_(self): def dict(self): r""" - Return dictionary on the modular symbol self, where keys are generators and values are the corresponding values of self on generators + Return dictionary on the modular symbol ``self``, where keys are + generators and values are the corresponding values of ``self`` on + generators. EXAMPLES:: @@ -250,9 +250,9 @@ def _normalize(self, **kwds): def _richcmp_(self, other, op): """ - Check if self == other. + Check if ``self == other``. - Here self and other have the same parent. + Here ``self`` and ``other`` have the same parent. EXAMPLES:: @@ -276,7 +276,7 @@ def _richcmp_(self, other, op): def _add_(self, right): """ - Return self + right + Return ``self + right``. EXAMPLES:: @@ -293,7 +293,7 @@ def _add_(self, right): def _lmul_(self, right): """ - Return self * right + Return ``self * right``. EXAMPLES:: @@ -310,7 +310,7 @@ def _lmul_(self, right): def _rmul_(self, right): """ - Return self * right + Return ``self * right``. EXAMPLES:: @@ -327,7 +327,7 @@ def _rmul_(self, right): def _sub_(self, right): """ - Return self - right + Return ``self - right``. EXAMPLES:: @@ -348,19 +348,19 @@ def _get_prime(self, p=None, alpha=None, allow_none=False): INPUT: - - ``p`` -- an integer or None (default None); if specified - needs to match the prime of the parent. + - ``p`` -- integer or ``None`` (default: ``None``); if specified + needs to match the prime of the parent - - ``alpha`` -- an element or None (default None); if p-adic - can contribute a prime. + - ``alpha`` -- an element or None (default: ``None``); if `p`-adic + can contribute a prime - ``allow_none`` -- boolean (default: ``False``); whether to allow - no prime to be specified. + no prime to be specified OUTPUT: - a prime or ``None``. If ``allow_none`` is ``False`` then a - :class:`ValueError` will be raised rather than returning ``None`` + :exc:`ValueError` will be raised rather than returning ``None`` if no prime can be determined. EXAMPLES:: @@ -404,14 +404,11 @@ def _get_prime(self, p=None, alpha=None, allow_none=False): def plus_part(self): r""" - Return the plus part of self -- i.e. ``self + self | [1,0,0,-1]``. + Return the plus part of ``self`` -- i.e. + ``self + self | [1,0,0,-1]``. Note that we haven't divided by 2. Is this a problem? - OUTPUT: - - - self + self | [1,0,0,-1] - EXAMPLES:: sage: E = EllipticCurve('11a') @@ -446,16 +443,16 @@ def minus_part(self): S0N = Sigma0(self.parent().level()) return self - self * S0N(minusproj) - def hecke(self, ell, algorithm="prep"): + def hecke(self, ell, algorithm='prep'): r""" - Return self | `T_{\ell}` by making use of the precomputations in - self.prep_hecke() + Return ``self`` | `T_{\ell}` by making use of the precomputations in + ``self.prep_hecke()``. INPUT: - ``ell`` -- a prime - - ``algorithm`` -- a string, either 'prep' (default) or + - ``algorithm`` -- string, either 'prep' (default) or 'naive' OUTPUT: @@ -506,9 +503,7 @@ def valuation(self, p=None): - ``p`` -- prime - OUTPUT: - - - The valuation of ``self`` at `p` + OUTPUT: the valuation of ``self`` at `p` EXAMPLES:: @@ -544,7 +539,7 @@ def valuation(self, p=None): def diagonal_valuation(self, p): """ - Return the minimum of the diagonal valuation on the values of self + Return the minimum of the diagonal valuation on the values of ``self``. INPUT: @@ -570,7 +565,7 @@ def diagonal_valuation(self, p): @cached_method def is_Tq_eigensymbol(self, q, p=None, M=None): r""" - Determine if self is an eigenvector for `T_q` modulo `p^M` + Determine if ``self`` is an eigenvector for `T_q` modulo `p^M`. INPUT: @@ -580,9 +575,7 @@ def is_Tq_eigensymbol(self, q, p=None, M=None): - ``M`` -- degree of accuracy of approximation - OUTPUT: - - - True/False + OUTPUT: boolean EXAMPLES:: @@ -613,15 +606,15 @@ def is_Tq_eigensymbol(self, q, p=None, M=None): @cached_method def Tq_eigenvalue(self, q, p=None, M=None, check=True): r""" - Eigenvalue of `T_q` modulo `p^M` + Eigenvalue of `T_q` modulo `p^M`. INPUT: - ``q`` -- prime of the Hecke operator - - ``p`` -- prime we are working modulo (default: None) + - ``p`` -- prime we are working modulo (default: ``None``) - - ``M`` -- degree of accuracy of approximation (default: None) + - ``M`` -- degree of accuracy of approximation (default: ``None``) - ``check`` -- check that ``self`` is an eigensymbol @@ -691,13 +684,11 @@ def is_ordinary(self, p=None, P=None): INPUT: - - ``p`` -- a positive integral prime, or None (default None) + - ``p`` -- a positive integral prime, or None (default: ``None``) - ``P`` -- a prime of the base ring above `p`, or None. This is ignored - unless the base ring is a number field. + unless the base ring is a number field - OUTPUT: - - - True/False + OUTPUT: boolean EXAMPLES:: @@ -753,7 +744,7 @@ def evaluate_twisted(self, a, chi): INPUT: - ``a`` -- integer in the range range(p) - - ``chi`` -- the modulus of a quadratic character. + - ``chi`` -- the modulus of a quadratic character OUTPUT: @@ -762,13 +753,13 @@ def evaluate_twisted(self, a, chi): EXAMPLES:: sage: E = EllipticCurve('17a1') - sage: L = E.padic_lseries(5, implementation="pollackstevens", precision=4) #long time + sage: L = E.padic_lseries(5, implementation='pollackstevens', precision=4) #long time sage: D = L.quadratic_twist() # long time sage: L.symbol().evaluate_twisted(1,D) # long time (1 + 5 + 3*5^2 + 5^3 + O(5^4), 5^2 + O(5^3), 1 + O(5^2), 2 + O(5)) sage: E = EllipticCurve('40a4') - sage: L = E.padic_lseries(7, implementation="pollackstevens", precision=4) #long time + sage: L = E.padic_lseries(7, implementation='pollackstevens', precision=4) #long time sage: D = L.quadratic_twist() # long time sage: L.symbol().evaluate_twisted(1,D) # long time (4 + 6*7 + 3*7^2 + O(7^4), 6*7 + 6*7^2 + O(7^3), 6 + O(7^2), 1 + O(7)) @@ -778,7 +769,7 @@ def evaluate_twisted(self, a, chi): Check for :issue:`32878`:: sage: E = EllipticCurve('11a1') - sage: L = E.padic_lseries(3, implementation="pollackstevens", precision=4) + sage: L = E.padic_lseries(3, implementation='pollackstevens', precision=4) sage: D = 5 sage: L.symbol().evaluate_twisted(1, D) (2 + 3 + 2*3^2 + O(3^4), 2 + 3 + O(3^3), 2 + 3 + O(3^2), 2 + O(3)) @@ -860,24 +851,25 @@ def _find_alpha(self, p, k, M=None, ap=None, new_base_ring=None, ordinary=True, - ``k`` -- Pollack-Stevens weight - - ``M`` -- precision (default: None) of `\QQ_p` + - ``M`` -- precision (default: ``None``); of `\QQ_p` - - ``ap`` -- Hecke eigenvalue at `p` (default: None) + - ``ap`` -- Hecke eigenvalue at `p` (default: ``None``) - - ``new_base_ring`` -- field of definition of `\alpha` (default: None) + - ``new_base_ring`` -- field of definition of `\alpha` (default: ``None``) - - ``ordinary`` -- True if the prime is ordinary (default: ``True``) + - ``ordinary`` -- ``True`` if the prime is ordinary (default: ``True``) - ``check`` -- check to see if the prime is ordinary (default: ``True``) - - ``find_extraprec`` -- setting this to True finds extra precision (default: ``True``) + - ``find_extraprec`` -- setting this to ``True`` finds extra precision + (default: ``True``) OUTPUT: - The output is a tuple (``alpha``, ``new_base_ring``, - ``newM``, ``eisenloss``,``q``,``aq``), with + The output is a tuple (``alpha``, ``new_base_ring``, ``newM``, + ``eisenloss``, ``q``,``aq``), with - - ``alpha`` -- `U_p` eigenvalue + - ``alpha`` -- `U_p` eigenvalue - ``new_base_ring`` -- field of definition of `\alpha` with precision at least ``newM`` @@ -962,7 +954,8 @@ def _find_alpha(self, p, k, M=None, ap=None, new_base_ring=None, ordinary=True, def p_stabilize(self, p=None, M=20, alpha=None, ap=None, new_base_ring=None, ordinary=True, check=True): r""" - Return the `p`-stabilization of self to level `N p` on which `U_p` acts by `\alpha`. + Return the `p`-stabilization of ``self`` to level `N p` on which `U_p` + acts by `\alpha`. Note that since `\alpha` is `p`-adic, the resulting symbol is just an approximation to the true `p`-stabilization @@ -980,22 +973,23 @@ def p_stabilize(self, p=None, M=20, alpha=None, ap=None, new_base_ring=None, ord - ``new_base_ring`` -- change of base ring - - ``ordinary`` -- (default: ``True``) whether to return the ordinary - (at ``p``) eigensymbol. + - ``ordinary`` -- boolean (default: ``True``); whether to return the + ordinary (at ``p``) eigensymbol - - ``check`` -- (default: ``True``) whether to perform extra sanity checks + - ``check`` -- boolean (default: ``True``); whether to perform extra + sanity checks OUTPUT: A modular symbol with the same Hecke eigenvalues as - self away from `p` and eigenvalue `\alpha` at `p`. + ``self`` away from `p` and eigenvalue `\alpha` at `p`. The eigenvalue `\alpha` depends on the parameter ``ordinary``. If ``ordinary`` == True: the unique modular symbol of level - `N p` with the same Hecke eigenvalues as self away from + `N p` with the same Hecke eigenvalues as ``self`` away from `p` and unit eigenvalue at `p`; else the unique modular symbol of level `N p` with the same Hecke eigenvalues as - self away from `p` and non-unit eigenvalue at `p`. + ``self`` away from `p` and non-unit eigenvalue at `p`. EXAMPLES:: @@ -1058,7 +1052,7 @@ def p_stabilize(self, p=None, M=20, alpha=None, ap=None, new_base_ring=None, ord def completions(self, p, M): r""" If `K` is the base_ring of self, this function takes all maps - `K\to \QQ_p` and applies them to self return a list of + `K\to \QQ_p` and applies them to ``self`` return a list of (modular symbol,map: `K\to \QQ_p`) as map varies over all such maps. .. NOTE:: @@ -1122,7 +1116,7 @@ def lift(self, p=None, M=None, alpha=None, new_base_ring=None, algorithm=None, eigensymbol=False, check=True): r""" Return a (`p`-adic) overconvergent modular symbol with - `M` moments which lifts self up to an Eisenstein error + `M` moments which lifts ``self`` up to an Eisenstein error. Here the Eisenstein error is a symbol whose system of Hecke eigenvalues equals `\ell+1` for `T_\ell` when `\ell` @@ -1138,13 +1132,14 @@ def lift(self, p=None, M=None, alpha=None, new_base_ring=None, - ``new_base_ring`` -- change of base ring - - ``algorithm`` -- 'stevens' or 'greenberg' (default 'stevens') + - ``algorithm`` -- ``'stevens'`` or ``'greenberg'`` (default: + ``'stevens'``) - - ``eigensymbol`` -- if True, lifts to Hecke eigensymbol (self must + - ``eigensymbol`` -- if ``True``, lifts to Hecke eigensymbol (self must be a `p`-ordinary eigensymbol) (Note: ``eigensymbol = True`` does *not* just indicate to the code that - self is an eigensymbol; it solves a wholly different problem, lifting + ``self`` is an eigensymbol; it solves a wholly different problem, lifting an eigensymbol to an eigensymbol.) OUTPUT: @@ -1263,7 +1258,7 @@ def lift(self, p=None, M=None, alpha=None, new_base_ring=None, def _lift_to_OMS(self, p, M, new_base_ring, algorithm='greenberg'): r""" Return a (`p`-adic) overconvergent modular symbol with - `M` moments which lifts self up to an Eisenstein error + `M` moments which lifts ``self`` up to an Eisenstein error. Here the Eisenstein error is a symbol whose system of Hecke eigenvalues equals `\ell+1` for `T_\ell` when `\ell` @@ -1277,16 +1272,16 @@ def _lift_to_OMS(self, p, M, new_base_ring, algorithm='greenberg'): - ``new_base_ring`` -- new base ring - - ``algorithm`` -- (default: 'greenberg') a string, either 'greenberg' - or 'stevens', specifying whether to use + - ``algorithm`` -- string (default: ``'greenberg'``); either + ``'greenberg'`` or ``'stevens'``, specifying whether to use the lifting algorithm of M.Greenberg or that of Pollack--Stevens. The latter one solves the difference equation, which is not needed. The option to use Pollack--Stevens' algorithm here is just for historical reasons. OUTPUT: - - An overconvergent modular symbol whose specialization - equals self up to some Eisenstein error. + An overconvergent modular symbol whose specialization + equals ``self`` up to some Eisenstein error. EXAMPLES:: @@ -1444,7 +1439,7 @@ def p_stabilize_and_lift(self, p, M, alpha=None, ap=None, ordinary=True, algorithm='greenberg', eigensymbol=False, check=True): """ - `p`-stabilize and lift self + `p`-stabilize and lift ``self``. INPUT: @@ -1452,28 +1447,31 @@ def p_stabilize_and_lift(self, p, M, alpha=None, ap=None, - ``M`` -- precision - - ``alpha`` -- (default: None) the `U_p` eigenvalue, if known + - ``alpha`` -- (default: ``None``) the `U_p` eigenvalue, if known - - ``ap`` -- (default: None) the Hecke eigenvalue at p (before stabilizing), if known + - ``ap`` -- (default: ``None``) the Hecke eigenvalue at p (before + stabilizing), if known - - ``new_base_ring`` -- (default: None) if specified, force the resulting eigensymbol to take values in the given ring + - ``new_base_ring`` -- (default: ``None``) if specified, force the + resulting eigensymbol to take values in the given ring - - ``ordinary`` -- (default: ``True``) whether to return the ordinary - (at ``p``) eigensymbol. + - ``ordinary`` -- boolean (default: ``True``); whether to return the + ordinary (at ``p``) eigensymbol - - ``algorithm`` -- (default: 'greenberg') a string, either 'greenberg' - or 'stevens', specifying whether to use + - ``algorithm`` -- string (default: ``'greenberg'``); either + ``'greenberg'`` or ``'stevens'``, specifying whether to use the lifting algorithm of M.Greenberg or that of Pollack--Stevens. - The latter one solves the difference equation, which is not needed. The - option to use Pollack--Stevens' algorithm here is just for historical reasons. - - - ``eigensymbol`` -- (default: ``False``) if True, return an overconvergent eigensymbol. Otherwise just perform a naive lift + The latter one solves the difference equation, which is not needed. + The option to use Pollack--Stevens' algorithm here is just for + historical reasons. - - ``check`` -- (default: ``True``) whether to perform extra sanity checks + - ``eigensymbol`` -- boolean (default: ``False``); if ``True``, return + an overconvergent eigensymbol. Otherwise just perform a naive lift - OUTPUT: + - ``check`` -- boolean (default: ``True``); whether to perform extra + sanity checks - `p`-stabilized and lifted version of self. + OUTPUT: `p`-stabilized and lifted version of ``self`` EXAMPLES:: @@ -1515,7 +1513,7 @@ class PSModularSymbolElement_dist(PSModularSymbolElement): def reduce_precision(self, M): r""" - Only hold on to `M` moments of each value of self + Only hold on to `M` moments of each value of ``self``. EXAMPLES:: @@ -1577,7 +1575,7 @@ def specialize(self, new_base_ring=None): def padic_lseries(self,*args, **kwds): """ - Return the `p`-adic L-series of this modular symbol. + Return the `p`-adic `L`-series of this modular symbol. EXAMPLES:: diff --git a/src/sage/modular/pollack_stevens/padic_lseries.py b/src/sage/modular/pollack_stevens/padic_lseries.py index 1869e8ed047..613ceef65b8 100644 --- a/src/sage/modular/pollack_stevens/padic_lseries.py +++ b/src/sage/modular/pollack_stevens/padic_lseries.py @@ -49,7 +49,7 @@ class pAdicLseries(SageObject): sage: E = EllipticCurve('37a') sage: p = 5 sage: prec = 4 - sage: L = E.padic_lseries(p, implementation="pollackstevens", precision=prec) # long time + sage: L = E.padic_lseries(p, implementation='pollackstevens', precision=prec) # long time sage: L[1] # long time 1 + 4*5 + 2*5^2 + O(5^3) sage: L.series(3) # long time @@ -88,7 +88,7 @@ class pAdicLseries(SageObject): def __init__(self, symb, gamma=None, quadratic_twist=1, precision=None): r""" - Initialize the class + Initialize the class. EXAMPLES:: @@ -125,12 +125,12 @@ def __init__(self, symb, gamma=None, quadratic_twist=1, precision=None): def __getitem__(self, n): r""" - Return the `n`-th coefficient of the `p`-adic `L`-series + Return the `n`-th coefficient of the `p`-adic `L`-series. EXAMPLES:: sage: E = EllipticCurve('14a5') - sage: L = E.padic_lseries(7,implementation="pollackstevens",precision=5) # long time + sage: L = E.padic_lseries(7,implementation='pollackstevens',precision=5) # long time sage: L[0] # long time O(7^5) sage: L[1] # long time @@ -173,7 +173,7 @@ def __eq__(self, other): EXAMPLES:: sage: E = EllipticCurve('11a') - sage: L = E.padic_lseries(11,implementation="pollackstevens",precision=6) # long time + sage: L = E.padic_lseries(11,implementation='pollackstevens',precision=6) # long time sage: L == loads(dumps(L)) # indirect doctest, long time True """ @@ -192,7 +192,7 @@ def __ne__(self, other): EXAMPLES:: sage: E = EllipticCurve('11a') - sage: L = E.padic_lseries(11,implementation="pollackstevens",precision=6) # long time + sage: L = E.padic_lseries(11,implementation='pollackstevens',precision=6) # long time sage: L != L # long time False """ @@ -224,7 +224,7 @@ def prime(self): EXAMPLES:: sage: E = EllipticCurve('19a') - sage: L = E.padic_lseries(19, implementation="pollackstevens",precision=6) # long time + sage: L = E.padic_lseries(19, implementation='pollackstevens',precision=6) # long time sage: L.prime() # long time 19 """ @@ -253,7 +253,7 @@ def _repr_(self): EXAMPLES:: sage: E = EllipticCurve('14a2') - sage: L = E.padic_lseries(3, implementation="pollackstevens", precision=4) # long time + sage: L = E.padic_lseries(3, implementation='pollackstevens', precision=4) # long time sage: L._repr_() # long time '3-adic L-series of Modular symbol of level 42 with values in Space of 3-adic distributions with k=0 action and precision cap 8' @@ -268,24 +268,24 @@ def series(self, prec=5): INPUT: - - ``prec`` -- (default 5) is the precision of the power series + - ``prec`` -- (default: 5) the precision of the power series EXAMPLES:: sage: E = EllipticCurve('14a2') sage: p = 3 sage: prec = 6 - sage: L = E.padic_lseries(p,implementation="pollackstevens",precision=prec) # long time + sage: L = E.padic_lseries(p,implementation='pollackstevens',precision=prec) # long time sage: L.series(4) # long time 2*3 + 3^4 + 3^5 + O(3^6) + (2*3 + 3^2 + O(3^4))*T + (2*3 + O(3^2))*T^2 + (3 + O(3^2))*T^3 + O(T^4) sage: E = EllipticCurve("15a3") - sage: L = E.padic_lseries(5,implementation="pollackstevens",precision=15) # long time + sage: L = E.padic_lseries(5,implementation='pollackstevens',precision=15) # long time sage: L.series(3) # long time O(5^15) + (2 + 4*5^2 + 3*5^3 + 5^5 + 2*5^6 + 3*5^7 + 3*5^8 + 2*5^9 + 2*5^10 + 3*5^11 + 5^12 + O(5^13))*T + (4*5 + 4*5^3 + 3*5^4 + 4*5^5 + 3*5^6 + 2*5^7 + 5^8 + 4*5^9 + 3*5^10 + O(5^11))*T^2 + O(T^3) sage: E = EllipticCurve("79a1") - sage: L = E.padic_lseries(2,implementation="pollackstevens",precision=10) # not tested + sage: L = E.padic_lseries(2,implementation='pollackstevens',precision=10) # not tested sage: L.series(4) # not tested O(2^9) + (2^3 + O(2^4))*T + O(2^0)*T^2 + (O(2^-3))*T^3 + O(T^4) """ @@ -297,7 +297,7 @@ def series(self, prec=5): def interpolation_factor(self, ap, chip=1, psi=None): r""" - Return the interpolation factor associated to self. + Return the interpolation factor associated to ``self``. This is the `p`-adic multiplier that which appears in the interpolation formula of the `p`-adic `L`-function. It has the form `(1-\alpha_p^{-1})^2`, where `\alpha_p` is the @@ -307,16 +307,16 @@ def interpolation_factor(self, ap, chip=1, psi=None): - ``ap`` -- the eigenvalue of the Up operator - - ``chip`` -- the value of the nebentype at p (default: 1) + - ``chip`` -- the value of the nebentype at `p` (default: 1) - - ``psi`` -- a twisting character (default: None) + - ``psi`` -- a twisting character (default: ``None``) OUTPUT: a `p`-adic number EXAMPLES:: sage: E = EllipticCurve('19a2') - sage: L = E.padic_lseries(3,implementation="pollackstevens",precision=6) # long time + sage: L = E.padic_lseries(3,implementation='pollackstevens',precision=6) # long time sage: ap = E.ap(3) # long time sage: L.interpolation_factor(ap) # long time 3^2 + 3^3 + 2*3^5 + 2*3^6 + O(3^7) @@ -359,7 +359,7 @@ def _basic_integral(self, a, j): sage: from sage.modular.pollack_stevens.padic_lseries import pAdicLseries sage: E = EllipticCurve('11a3') - sage: L = E.padic_lseries(5, implementation="pollackstevens", precision=4) #long time + sage: L = E.padic_lseries(5, implementation='pollackstevens', precision=4) #long time sage: L._basic_integral(1,2) # long time 2*5^2 + 5^3 + O(5^4) """ diff --git a/src/sage/modular/pollack_stevens/sigma0.py b/src/sage/modular/pollack_stevens/sigma0.py index 501ef54c8ad..c5ae3741f2f 100644 --- a/src/sage/modular/pollack_stevens/sigma0.py +++ b/src/sage/modular/pollack_stevens/sigma0.py @@ -2,7 +2,7 @@ The matrix monoid `\Sigma_0(N)`. This stands for a monoid of matrices over `\ZZ`, `\QQ`, `\ZZ_p`, or `\QQ_p`, -depending on an integer `N \ge 1`. This class exists in order to act on p-adic +depending on an integer `N \ge 1`. This class exists in order to act on `p`-adic distribution spaces. Over `\QQ` or `\ZZ`, it is the monoid of matrices `2\times2` matrices @@ -88,9 +88,7 @@ class _default_adjuster(Sigma0ActionAdjuster): - ``g`` -- a `2 \times 2` matrix - OUTPUT: - - - a 4-tuple consisting of the entries of the matrix + OUTPUT: a 4-tuple consisting of the entries of the matrix EXAMPLES:: @@ -114,12 +112,13 @@ class Sigma0_factory(UniqueFactory): INPUT: - - ``N`` (integer) -- the level (should be strictly positive) + - ``N`` -- integer; the level (should be strictly positive) - ``base_ring`` (commutative ring, default `\ZZ`) -- the base ring (normally `\ZZ` or a `p`-adic ring) - - ``adjuster`` -- None, or a callable which takes a `2 \times 2` matrix and returns - a 4-tuple of integers. This is supplied in order to support differing - conventions for the action of `2 \times 2` matrices on distributions. + - ``adjuster`` -- ``None``, or a callable which takes a `2 \times 2` matrix + and returns a 4-tuple of integers. This is supplied in order to support + differing conventions for the action of `2 \times 2` matrices on + distributions. EXAMPLES:: @@ -213,7 +212,7 @@ def __hash__(self): def det(self): r""" - Return the determinant of this matrix, which is (by assumption) non-zero. + Return the determinant of this matrix, which is (by assumption) nonzero. EXAMPLES:: @@ -266,7 +265,7 @@ def _richcmp_(self, other, op): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -279,7 +278,8 @@ def _repr_(self): def matrix(self): r""" - Return self as a matrix (forgetting the additional data that it is in Sigma0(N)). + Return ``self`` as a matrix (forgetting the additional data that it is + in ``Sigma0(N)``). EXAMPLES:: @@ -412,7 +412,7 @@ def __init__(self, N, base_ring, adjuster): def _an_element_(self): r""" - Return an element of self. This is implemented in a rather dumb way. + Return an element of ``self``. This is implemented in a rather dumb way. EXAMPLES:: @@ -478,14 +478,14 @@ def _coerce_map_from_(self, other): def _element_constructor_(self, x, check=True): r""" - Construct an element of self from x. + Construct an element of ``self`` from x. INPUT: - ``x`` -- something that one can make into a matrix over the appropriate base ring - - ``check`` (boolean, default: ``True``) -- if True, then check that this - matrix actually satisfies the conditions. + - ``check`` -- boolean (default: ``True``); if ``True``, then check + that this matrix actually satisfies the conditions EXAMPLES:: diff --git a/src/sage/modular/pollack_stevens/space.py b/src/sage/modular/pollack_stevens/space.py index 4bb25a086c7..862418412ca 100644 --- a/src/sage/modular/pollack_stevens/space.py +++ b/src/sage/modular/pollack_stevens/space.py @@ -93,7 +93,7 @@ class PollackStevensModularSymbols_factory(UniqueFactory): - ``sign`` -- integer; -1, 0, 1 - - ``base_ring`` -- ring or ``None`` + - ``base_ring`` -- ring or ``None`` - ``p`` -- prime or ``None`` @@ -107,7 +107,7 @@ class PollackStevensModularSymbols_factory(UniqueFactory): They are only relevant if ``coefficients`` is ``None``, in which case the coefficient module is inferred from the other data. - .. note:: + .. NOTE:: We emphasize that in the Pollack-Stevens notation, the ``weight`` is the usual weight minus 2, so a classical weight @@ -177,7 +177,7 @@ def create_object(self, version, key): - ``version`` -- the version of the object to create - - ``key`` -- a tuple of parameters, as created by :meth:`create_key` + - ``key`` -- tuple of parameters, as created by :meth:`create_key` EXAMPLES:: @@ -205,7 +205,7 @@ class PollackStevensModularSymbolspace(Module): - ``coefficients`` -- a coefficient module - - ``sign`` -- (default: 0); 0, -1, or 1 + - ``sign`` -- (default: 0) 0, -1, or 1 EXAMPLES:: @@ -256,7 +256,7 @@ def __init__(self, group, coefficients, sign=0): def _element_constructor_(self, data): r""" - Construct an element of self from data. + Construct an element of ``self`` from data. EXAMPLES:: @@ -270,7 +270,7 @@ def _element_constructor_(self, data): elif isinstance(data, ManinMap): pass else: - # a dict, or a single distribution specifying a constant symbol, etc + # a dict, or a single distribution specifying a constant symbol, etc. data = ManinMap(self._coefficients, self._source, data) if data._codomain != self._coefficients: @@ -328,9 +328,7 @@ def source(self): r""" Return the domain of the modular symbols in this space. - OUTPUT: - - A :class:`sage.modular.pollack_stevens.fund_domain.PollackStevensModularDomain` + OUTPUT: a :class:`sage.modular.pollack_stevens.fund_domain.PollackStevensModularDomain` EXAMPLES:: @@ -394,7 +392,7 @@ def sign(self): def ngens(self): r""" - Returns the number of generators defining this space. + Return the number of generators defining this space. EXAMPLES:: @@ -577,9 +575,7 @@ def _specialize_parent_space(self, new_base_ring): - ``new_base_ring`` -- a ring - OUTPUT: - - A space of modular symbols to which our space specializes. + OUTPUT: a space of modular symbols to which our space specializes EXAMPLES:: @@ -592,7 +588,6 @@ def _specialize_parent_space(self, new_base_ring): 5-adic Ring with capped absolute precision 20 sage: M._specialize_parent_space(QQ).base_ring() Rational Field - """ return PollackStevensModularSymbols(self.group(), coefficients=self.coefficient_module().specialize(new_base_ring), sign=self.sign()) @@ -607,9 +602,7 @@ def _lift_parent_space(self, p, M, new_base_ring): - ``M`` -- precision cap - ``new_base_ring`` -- ring - OUTPUT: - - A space of distribution valued modular symbols. + OUTPUT: a space of distribution valued modular symbols EXAMPLES:: @@ -622,7 +615,6 @@ def _lift_parent_space(self, p, M, new_base_ring): TypeError: Coefficient module must be a Symk sage: PollackStevensModularSymbols(Gamma1(3), weight=1)._lift_parent_space(17,10,Qp(17)) Space of overconvergent modular symbols for Congruence Subgroup Gamma1(3) with sign 0 and values in Space of 17-adic distributions with k=1 action and precision cap 10 - """ if self.coefficient_module().is_symk(): return PollackStevensModularSymbols(self.group(), coefficients=self.coefficient_module().lift(p, M, new_base_ring), sign=self.sign()) @@ -637,9 +629,7 @@ def change_ring(self, new_base_ring): - ``new_base_ring`` -- a ring - OUTPUT: - - A space of modular symbols over the specified base. + OUTPUT: a space of modular symbols over the specified base EXAMPLES:: @@ -649,7 +639,6 @@ def change_ring(self, new_base_ring): Space of modular symbols for Congruence Subgroup Gamma(6) with sign 0 and values in Sym^4 Q^2 sage: M.change_ring(Qp(5,8)) Space of modular symbols for Congruence Subgroup Gamma(6) with sign 0 and values in Sym^4 Q_5^2 - """ return PollackStevensModularSymbols(self.group(), coefficients=self.coefficient_module().change_ring(new_base_ring), sign=self.sign()) @@ -657,9 +646,7 @@ def _an_element_(self): r""" Return the cusps associated to an element of a congruence subgroup. - OUTPUT: - - an element of the modular symbol space + OUTPUT: an element of the modular symbol space This returns a "typical" element of this space; in this case the constant map sending every element to an element of the @@ -688,15 +675,13 @@ def _an_element_(self): def random_element(self, M=None): r""" - Return a random overconvergent modular symbol in this space with `M` moments + Return a random overconvergent modular symbol in this space with `M` moments. INPUT: - ``M`` -- positive integer - OUTPUT: - - An element of the modular symbol space with `M` moments + OUTPUT: an element of the modular symbol space with `M` moments Returns a random element in this space by randomly choosing values of distributions on all but one divisor, and solves the @@ -811,9 +796,7 @@ def cusps_from_mat(g): - ``g`` -- an element of a congruence subgroup or a matrix - OUTPUT: - - A tuple of cusps associated to ``g``. + OUTPUT: a tuple of cusps associated to ``g`` EXAMPLES:: @@ -865,13 +848,11 @@ def ps_modsym_from_elliptic_curve(E, sign=0, implementation='eclib'): the plus (if ``sign`` == 1) or the minus (if ``sign`` == -1) modular symbol. The default of 0 returns the sum of the plus and minus symbols. - - ``implementation`` -- either 'eclib' (default) or 'sage'. This + - ``implementation`` -- either ``'eclib'`` (default) or ``'sage'``. This determines which implementation of the underlying classical modular symbols is used. - OUTPUT: - - The overconvergent modular symbol associated to ``E`` + OUTPUT: the overconvergent modular symbol associated to ``E`` EXAMPLES:: @@ -914,14 +895,15 @@ def ps_modsym_from_elliptic_curve(E, sign=0, implementation='eclib'): return V(val) -def ps_modsym_from_simple_modsym_space(A, name="alpha"): +def ps_modsym_from_simple_modsym_space(A, name='alpha'): r""" - Returns some choice -- only well defined up a nonzero scalar (!) -- of an overconvergent modular symbol that corresponds to ``A``. + Return some choice -- only well defined up a nonzero scalar (!) -- of an + overconvergent modular symbol that corresponds to ``A``. INPUT: - ``A`` -- nonzero simple Hecke equivariant new space of modular symbols, - which need not be cuspidal. + which need not be cuspidal OUTPUT: diff --git a/src/sage/modular/quasimodform/element.py b/src/sage/modular/quasimodform/element.py index 12d441809c4..23b11fef749 100644 --- a/src/sage/modular/quasimodform/element.py +++ b/src/sage/modular/quasimodform/element.py @@ -103,9 +103,7 @@ def __init__(self, parent, polynomial): each `f_i` are modular forms ring elements and `E_2` correspond to the weight 2 Eisenstein series - OUTPUT: - - ``QuasiModularFormsElement`` + OUTPUT: ``QuasiModularFormsElement`` TESTS:: @@ -152,7 +150,7 @@ def q_expansion(self, prec=6): def _repr_(self): r""" - String representation of self. + String representation of ``self``. TESTS:: @@ -180,7 +178,7 @@ def _latex_(self): def _richcmp_(self, other, op): r""" - Compare self with other. + Compare ``self`` with ``other``. TESTS:: @@ -227,7 +225,7 @@ def _add_(self, other): def __neg__(self): r""" - The negation of ``self``` + The negation of ``self``. TESTS:: @@ -242,7 +240,7 @@ def __neg__(self): def _mul_(self, other): r""" - The multiplication of two ``QuasiModularFormElement`` + The multiplication of two ``QuasiModularFormElement``. INPUT: @@ -265,7 +263,7 @@ def _mul_(self, other): def _lmul_(self, c): r""" - The left action of the base ring on self. + The left action of the base ring on ``self``. INPUT: @@ -287,7 +285,7 @@ def _lmul_(self, c): def __bool__(self): r""" - Return whether ``self`` is non-zero. + Return whether ``self`` is nonzero. EXAMPLES:: @@ -454,13 +452,13 @@ def polynomial(self, names=None): INPUT: - - ``names`` (str, default: ``None``) -- a list or tuple of names + - ``names``-- string (default: ``None``); list or tuple of names (strings), or a comma separated string. Defines the names for the generators of the multivariate polynomial ring. The default names are of the form ``ABCk`` where ``k`` is a number corresponding to the weight of the form ``ABC``. - OUTPUT: A multivariate polynomial in the variables ``names`` + OUTPUT: a multivariate polynomial in the variables ``names`` EXAMPLES:: @@ -477,7 +475,6 @@ def polynomial(self, names=None): 5 sage: (QM.0 + QM.1 + QM.2*QM.1 + QM.3*QM.4).polynomial() E3_1*E4_0 + E2_0*E3_0 + E2 + E2_0 - """ P = self.parent().polynomial_ring(names) poly_gens = P.gens() @@ -777,7 +774,7 @@ def derivative(self): def _compute(self, X): r""" - Compute the coefficients of `q^n` of the q-expansion of this, + Compute the coefficients of `q^n` of the `q`-expansion of this, graded quasimodular form for `n` in the list `X`. The results are not cached. (Use coefficients for cached results). @@ -800,7 +797,7 @@ def _compute(self, X): def coefficients(self, X): r""" - Return the coefficients of `q^n` of the q-expansion of this, + Return the coefficients of `q^n` of the `q`-expansion of this, graded quasimodular form for `n` in the list `X`. If X is an integer, return coefficients for indices from 1 diff --git a/src/sage/modular/quasimodform/ring.py b/src/sage/modular/quasimodform/ring.py index 14f099be987..29df3bfcde0 100644 --- a/src/sage/modular/quasimodform/ring.py +++ b/src/sage/modular/quasimodform/ring.py @@ -222,15 +222,15 @@ def __init__(self, group=1, base_ring=QQ, name='E2'): r""" INPUT: - - ``group`` (default: `\SL_2(\ZZ)`) -- a congruence subgroup of + - ``group`` -- (default: `\SL_2(\ZZ)`) a congruence subgroup of `\SL_2(\ZZ)`, or a positive integer `N` (interpreted as - `\Gamma_0(N)`). + `\Gamma_0(N)`) - - ``base_ring`` (ring, default: `\QQ`) -- a base ring, which should be - `\QQ`, `\ZZ`, or the integers mod `p` for some prime `p`. + - ``base_ring`` -- a base ring (default: `\QQ`); should be + `\QQ`, `\ZZ`, or the integers mod `p` for some prime `p` - - ``name`` (str, default: ``'E2'``) -- a variable name corresponding to - the weight 2 Eisenstein series. + - ``name`` -- string (default: ``'E2'``); a variable name corresponding to + the weight 2 Eisenstein series TESTS: @@ -321,9 +321,9 @@ def quasimodular_forms_of_weight(self, weight): INPUT: - - ``weight`` (int, Integer) + - ``weight`` -- integer - OUTPUT: A quasimodular forms space of the given weight. + OUTPUT: a quasimodular forms space of the given weight EXAMPLES:: @@ -331,13 +331,12 @@ def quasimodular_forms_of_weight(self, weight): Traceback (most recent call last): ... NotImplementedError: spaces of quasimodular forms of fixed weight not yet implemented - """ raise NotImplementedError("spaces of quasimodular forms of fixed weight not yet implemented") def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -377,11 +376,11 @@ def _coerce_map_from_(self, M): def _element_constructor_(self, datum): r""" - The call method of self. + The call method of ``self``. INPUT: - - ``datum`` -- list, GradedModularFormElement, ModularFormElement, + - ``datum`` -- list; GradedModularFormElement, ModularFormElement, Polynomial, base ring element OUTPUT: QuasiModularFormElement @@ -605,7 +604,7 @@ def polynomial_ring(self, names=None): INPUT: - - ``names`` (str, default: ``None``) -- a list or tuple of names + - ``names``-- string (default: ``None``); list or tuple of names (strings), or a comma separated string. Defines the names for the generators of the multivariate polynomial ring. The default names are of the following form: @@ -621,7 +620,7 @@ def polynomial_ring(self, names=None): - In any other cases, we use the letters ``Fk``, ``Gk``, ``Hk``, ..., ``FFk``, ``FGk``, ... to denote any generator of weight `k`. - OUTPUT: A multivariate polynomial ring in the variables ``names`` + OUTPUT: a multivariate polynomial ring in the variables ``names`` EXAMPLES:: @@ -728,7 +727,7 @@ def from_polynomial(self, polynomial): INPUT: - - ``polynomial`` -- A multivariate polynomial + - ``polynomial`` -- a multivariate polynomial OUTPUT: the graded quasimodular forms `P(g_0, \ldots, g_n)` @@ -789,11 +788,9 @@ def basis_of_weight(self, weight): INPUT: - - ``weight`` (integer) -- the weight of the subspace - - OUTPUT: + - ``weight`` -- integer; the weight of the subspace - A list of quasimodular forms of the given weight. + OUTPUT: list of quasimodular forms of the given weight EXAMPLES:: diff --git a/src/sage/modular/quatalg/brandt.py b/src/sage/modular/quatalg/brandt.py index 5a6714fbdde..c846411a421 100644 --- a/src/sage/modular/quatalg/brandt.py +++ b/src/sage/modular/quatalg/brandt.py @@ -96,7 +96,7 @@ ``is_right_equivalent(I,J)`` returns true if `I` and `J` are equivalent. This method first compares the theta series of `I` and `J`. If they are the same, it computes the theta series of the lattice `I\overline(J)`. It -returns true if the `n^{th}` coefficient of this series is nonzero +returns true if the `n`-th coefficient of this series is nonzero where `n=N(J)N(I)`. The theta series of a lattice `L` over the quaternion algebra `A` is @@ -117,19 +117,19 @@ Brandt matrices which can be computed using the definition of the Hecke operators given earlier. -``hecke_matrix_from_defn(self,n)`` returns the matrix of the n-th Hecke +``hecke_matrix_from_defn(self,n)`` returns the matrix of the `n`-th Hecke operator `B_{0}(n)` acting on self, computed directly from the definition. However, one can efficiently compute Brandt matrices using theta series. In fact, let `\{I_{1},.....,I_{h}\}` be a set of right `\mathcal{O}`-ideal class representatives. The (i,j) entry in the -Brandt matrix `B_{0}(n)` is the product of the `n^{th}` coefficient in +Brandt matrix `B_{0}(n)` is the product of the `n`-th coefficient in the theta series of the lattice `I_{i}\overline{I_{j}}` and the first coefficient in the theta series of the lattice `I_{i}\overline{I_{i}}`. -``compute_hecke_matrix_brandt(self,n)`` returns the n-th Hecke matrix, +``compute_hecke_matrix_brandt(self,n)`` returns the `n`-th Hecke matrix, computed using theta series. EXAMPLES:: @@ -235,15 +235,13 @@ def BrandtModule(N, M=1, weight=2, base_ring=QQ, use_cache=True): INPUT: - - `N` -- a product of primes with odd exponents - - `M` -- an integer coprime to `q` (default: 1) - - ``weight`` -- an integer that is at least 2 (default: 2) + - ``N`` -- a product of primes with odd exponents + - ``M`` -- integer coprime to `q` (default: 1) + - ``weight`` -- integer that is at least 2 (default: 2) - ``base_ring`` -- the base ring (default: ``QQ``) - ``use_cache`` -- whether to use the cache (default: ``True``) - OUTPUT: - - a Brandt module + OUTPUT: a Brandt module EXAMPLES:: @@ -322,13 +320,11 @@ def class_number(p, r, M): INPUT: - - `p` -- a prime - - `r` -- an odd positive integer (default: 1) - - `M` -- an integer coprime to `q` (default: 1) + - ``p`` -- a prime + - ``r`` -- an odd positive integer (default: 1) + - ``M`` -- integer coprime to `q` (default: 1) - OUTPUT: - - Integer + OUTPUT: integer EXAMPLES:: @@ -360,11 +356,9 @@ def maximal_order(A): INPUT: - - `A` -- quaternion algebra ramified precisely at `p` and infinity - - OUTPUT: + - ``A`` -- quaternion algebra ramified precisely at `p` and infinity - a maximal order in `A` + OUTPUT: a maximal order in `A` EXAMPLES:: @@ -390,12 +384,10 @@ def basis_for_left_ideal(R, gens): INPUT: - - `R` -- quaternion order + - ``R`` -- quaternion order - ``gens`` -- list of elements of `R` - OUTPUT: - - list of four elements of `R` + OUTPUT: list of four elements of `R` EXAMPLES:: @@ -419,12 +411,10 @@ def right_order(R, basis): INPUT: - - `R` -- order in quaternion algebra + - ``R`` -- order in quaternion algebra - ``basis`` -- basis for an ideal `I` - OUTPUT: - - order in quaternion algebra + OUTPUT: order in quaternion algebra EXAMPLES: @@ -456,7 +446,7 @@ def quaternion_order_with_given_level(A, level): INPUT: - - ``level`` -- The level of the order to be returned. Currently this + - ``level`` -- the level of the order to be returned. Currently this is only implemented when the level is divisible by at most one power of a prime that ramifies in this quaternion algebra. @@ -624,10 +614,10 @@ def __init__(self, N, M, weight, base_ring): """ INPUT: - - N -- ramification number (coprime to M) - - M -- auxiliary level - - weight -- integer 2 - - base_ring -- the base ring + - ``N`` -- ramification number (coprime to M) + - ``M`` -- auxiliary level + - ``weight`` -- integer 2 + - ``base_ring`` -- the base ring EXAMPLES:: @@ -800,8 +790,8 @@ def cyclic_submodules(self, I, p): INPUT: - - `I` -- ideal I in R = self.order_of_level_N() - - `p` -- prime `p` coprime to self.level() + - ``I`` -- ideal `I` in ``R = self.order_of_level_N()`` + - ``p`` -- prime `p` coprime to ``self.level()`` OUTPUT: @@ -946,25 +936,25 @@ def hecke_matrix(self, n, algorithm='default', sparse=False, B=None): INPUT: - - `n` -- integer + - ``n`` -- integer - - ``algorithm`` -- string (default: 'default') + - ``algorithm`` -- string (default: ``'default'``) - - 'default' -- let Sage guess which algorithm is best + - ``'default'`` -- let Sage guess which algorithm is best - - 'direct' -- use cyclic subideals (generally much + - ``'direct'`` -- use cyclic subideals (generally much better when you want few Hecke operators and the dimension is very large); uses 'theta' if n divides the level. - - 'brandt' -- use Brandt matrices (generally much + - ``'brandt'`` -- use Brandt matrices (generally much better when you want many Hecke operators and the dimension is very small; bad when the dimension is large) - - ``sparse`` -- bool (default: ``False``) + - ``sparse`` -- boolean (default: ``False``) - - `B` -- integer or ``None`` (default: ``None``); in direct + - ``B`` -- integer or ``None`` (default: ``None``); in direct algorithm, use theta series to this precision as an initial check for equality of ideal classes. @@ -1015,18 +1005,18 @@ def hecke_matrix(self, n, algorithm='default', sparse=False, B=None): def _compute_hecke_matrix_prime(self, p, sparse=False, B=None): """ - Return matrix of the `p`-th Hecke operator on self. The matrix + Return matrix of the `p`-th Hecke operator on ``self``. The matrix is always computed using the direct algorithm. INPUT: - - `p` -- prime number + - ``p`` -- prime number - - `B` -- integer or None (default: None); in direct algorithm, + - ``B`` -- integer or ``None`` (default: ``None``); in direct algorithm, use theta series to this precision as an initial check for equality of ideal classes. - - ``sparse`` -- bool (default: ``False``); whether matrix should be sparse + - ``sparse`` -- boolean (default: ``False``); whether matrix should be sparse EXAMPLES:: @@ -1045,15 +1035,15 @@ def _compute_hecke_matrix_prime(self, p, sparse=False, B=None): def _compute_hecke_matrix_directly(self, n, B=None, sparse=False): """ Given an integer `n` coprime to the level, return the matrix of - the n-th Hecke operator on self, computed on our fixed basis + the `n`-th Hecke operator on ``self``, computed on our fixed basis by directly using the definition of the Hecke action in terms of fractional ideals. INPUT: - - `n` -- integer, coprime to level + - ``n`` -- integer, coprime to level - - ``sparse`` -- bool (default: ``False``); whether matrix should be sparse + - ``sparse`` -- boolean (default: ``False``); whether matrix should be sparse EXAMPLES:: @@ -1153,16 +1143,14 @@ def _theta_dict(self, B): """ Return a dictionary from theta series vectors of degree `B` to list of integers `i`, where the key is the vector of - coefficients of the normalized theta series of the `i`th right + coefficients of the normalized theta series of the `i`-th right ideal, as indexed by ``self.right_ideals()``. INPUT: - - `B` -- positive integer, precision of theta series vectors + - ``B`` -- positive integer, precision of theta series vectors - OUTPUT: - - dictionary + OUTPUT: dictionary EXAMPLES: @@ -1193,18 +1181,18 @@ def _theta_dict(self, B): def _compute_hecke_matrix_brandt(self, n, sparse=False): """ - Return the n-th Hecke matrix, computed using Brandt matrices + Return the `n`-th Hecke matrix, computed using Brandt matrices (theta series). - When the n-th Hecke operator is requested, we computed theta + When the `n`-th Hecke operator is requested, we computed theta series to precision `2n+20`, since it only takes slightly longer, and this means that any Hecke operator `T_m` can quickly be computed, for `m<2n+20`. INPUT: - - n -- integer, coprime to level - - sparse -- bool (default: ``False``); whether matrix should be sparse + - ``n`` -- integer, coprime to level + - ``sparse`` -- boolean (default: ``False``); whether matrix should be sparse EXAMPLES:: @@ -1221,7 +1209,6 @@ def _compute_hecke_matrix_brandt(self, n, sparse=False): [0 2 2 2] sage: B._compute_hecke_matrix_brandt(5).fcp() (x - 6) * (x - 3) * (x^2 - 3*x - 2) - """ # we go out to 2*n+20 for efficiency, since it takes only a # little longer, but saves a lot of time if one computes @@ -1258,9 +1245,7 @@ def right_ideals(self, B=None): Return sorted tuple of representatives for the equivalence classes of right ideals in ``self``. - OUTPUT: - - sorted tuple of fractional ideals + OUTPUT: sorted tuple of fractional ideals EXAMPLES:: @@ -1338,12 +1323,10 @@ def _ideal_products(self, diagonal_only=False): INPUT: - - ``diagonal_only`` -- bool (default: ``False``) if ``True`` returns + - ``diagonal_only`` -- boolean (default: ``False``); if ``True`` returns only the diagonal ideal products - OUTPUT: - - list of ideals + OUTPUT: list of ideals EXAMPLES:: @@ -1449,9 +1432,7 @@ def brandt_series(self, prec, var='q'): - ``prec`` -- positive integer - ``var`` -- string (default: `q`) - OUTPUT: - - matrix of power series with coefficients in `\QQ` + OUTPUT: matrix of power series with coefficients in `\QQ` EXAMPLES:: @@ -1585,7 +1566,7 @@ def benchmark_magma(levels, silent=False): - ``levels`` -- list of pairs `(p,M)` where `p` is a prime not dividing `M` - - ``silent`` -- bool, default ``False``; if ``True`` suppress + - ``silent`` -- boolean (default: ``False``); if ``True`` suppress printing during computation OUTPUT: @@ -1625,7 +1606,7 @@ def benchmark_sage(levels, silent=False): - ``levels`` -- list of pairs `(p,M)` where `p` is a prime not dividing `M` - - ``silent`` -- bool, default ``False``; if ``True`` suppress + - ``silent`` -- boolean (default: ``False``); if ``True`` suppress printing during computation OUTPUT: diff --git a/src/sage/modular/ssmod/ssmod.py b/src/sage/modular/ssmod/ssmod.py index 49eb6fe1a08..9913e554a02 100644 --- a/src/sage/modular/ssmod/ssmod.py +++ b/src/sage/modular/ssmod/ssmod.py @@ -100,9 +100,7 @@ def Phi2_quad(J3, ssJ1, ssJ2): - ``ssJ2``, ``ssJ2`` -- supersingular j-invariants over the finite field - OUTPUT: - - - polynomial -- defined over the finite field + OUTPUT: polynomial; defined over the finite field EXAMPLES: @@ -119,7 +117,7 @@ def Phi2_quad(J3, ssJ1, ssJ2): sage: sage.modular.ssmod.ssmod.Phi2_quad(X, F(8), j_in) x^2 + 31*x + 31 - .. note:: + .. NOTE:: Given a root (j1,j2) to the polynomial `Phi_2(J1,J2)`, the pairs (j2,j3) not equal to (j2,j1) which solve `Phi_2(j2,j3)` are roots of @@ -164,9 +162,7 @@ def Phi_polys(L, x, j): - ``j`` -- supersingular j-invariant over the finite field - OUTPUT: - - - polynomial -- defined over the finite field + OUTPUT: polynomial; defined over the finite field EXAMPLES: @@ -204,13 +200,11 @@ def dimension_supersingular_module(prime, level=1): INPUT: - - ``prime`` -- integer, prime - - - ``level`` -- integer, positive + - ``prime`` -- integer; prime - OUTPUT: + - ``level`` -- integer; positive - - dimension -- integer, nonnegative + OUTPUT: dimension; integer, nonnegative EXAMPLES: @@ -259,11 +253,9 @@ def supersingular_D(prime): INPUT: - - prime -- integer, prime - - OUTPUT: + - ``prime`` -- integer, prime - - D -- integer, negative + OUTPUT: d; integer, negative EXAMPLES: @@ -304,7 +296,7 @@ def supersingular_j(FF): INPUT: - - ``FF`` -- finite field with p^2 elements, where p is a prime number + - ``FF`` -- finite field with p^2 elements, where p is a prime number OUTPUT: @@ -419,7 +411,7 @@ def __init__(self, prime=2, level=1, base_ring=ZZ): def _repr_(self) -> str: """ - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -504,9 +496,7 @@ def dimension(self): - ``self`` -- SupersingularModule object - OUTPUT: - - - integer -- dimension, nonnegative + OUTPUT: integer; dimension, nonnegative EXAMPLES:: @@ -553,9 +543,7 @@ def level(self): - ``self`` -- SupersingularModule object - OUTPUT: - - - integer -- the level, positive + OUTPUT: integer; the level, positive EXAMPLES:: @@ -579,9 +567,7 @@ def prime(self): - ``self`` -- SupersingularModule object - OUTPUT: - - - integer -- characteristic, positive + OUTPUT: integer; characteristic, positive EXAMPLES:: @@ -605,9 +591,7 @@ def weight(self): - ``self`` -- SupersingularModule object - OUTPUT: - - - integer -- weight, positive + OUTPUT: integer; weight, positive EXAMPLES:: @@ -630,7 +614,7 @@ def supersingular_points(self): INPUT: - - ``self`` -- SupersingularModule object + - ``self`` -- SupersingularModule object OUTPUT: @@ -783,11 +767,9 @@ def hecke_matrix(self, L): - ``self`` -- SupersingularModule object - - ``L`` -- integer, positive + - ``L`` -- integer; positive - OUTPUT: - - - matrix -- sparse integer matrix + OUTPUT: matrix; sparse integer matrix EXAMPLES: @@ -814,7 +796,7 @@ def hecke_matrix(self, L): [1 1 0 1 0 1] [1 1 1 0 1 0] - .. note:: + .. NOTE:: The first list --- list_j --- returned by the supersingular_points function are the rows *and* column indexes of the above hecke diff --git a/src/sage/modules/diamond_cutting.py b/src/sage/modules/diamond_cutting.py index 14adddd4b54..f470c7f72eb 100644 --- a/src/sage/modules/diamond_cutting.py +++ b/src/sage/modules/diamond_cutting.py @@ -137,11 +137,9 @@ def diamond_cut(V, GM, C, verbose=False): - ``C`` -- radius to use in cutting algorithm - - ``verbose`` -- (default: ``False``) whether to print debug information + - ``verbose`` -- boolean (default: ``False``); whether to print debug information - OUTPUT: - - A :class:`Polyhedron` instance. + OUTPUT: a :class:`Polyhedron` instance EXAMPLES:: @@ -234,7 +232,7 @@ def diamond_cut(V, GM, C, verbose=False): def calculate_voronoi_cell(basis, radius=None, verbose=False): """ - Calculate the Voronoi cell of the lattice defined by basis + Calculate the Voronoi cell of the lattice defined by basis. INPUT: @@ -244,9 +242,7 @@ def calculate_voronoi_cell(basis, radius=None, verbose=False): - ``verbose`` -- whether to print debug information - OUTPUT: - - A :class:`Polyhedron` instance. + OUTPUT: a :class:`Polyhedron` instance EXAMPLES:: diff --git a/src/sage/modules/fg_pid/fgp_element.py b/src/sage/modules/fg_pid/fgp_element.py index 5139506637e..ed63c1d2053 100644 --- a/src/sage/modules/fg_pid/fgp_element.py +++ b/src/sage/modules/fg_pid/fgp_element.py @@ -59,11 +59,12 @@ def __init__(self, parent, x, check=DEBUG): """ INPUT: - - ``parent`` -- parent module M + - ``parent`` -- parent module ``M`` - - ``x`` -- element of M.V() + - ``x`` -- element of ``M.V()`` - - ``check`` -- (default: ``True``) if True, verify that x in M.V() + - ``check`` -- boolean (default: ``True``); if ``True``, verify that x + in ``M.V()`` EXAMPLES:: @@ -83,7 +84,8 @@ def __init__(self, parent, x, check=DEBUG): def lift(self): """ - Lift self to an element of V, where the parent of self is the quotient module V/W. + Lift ``self`` to an element of V, where the parent of ``self`` is the + quotient module V/W. EXAMPLES:: @@ -193,7 +195,7 @@ def _rmul_(self, c): INPUT: - - ``c`` -- an element of ``self.parent().base_ring()``. + - ``c`` -- an element of ``self.parent().base_ring()`` OUTPUT: @@ -238,7 +240,7 @@ def _lmul_(self, s): INPUT: - - ``c`` -- an element of ``self.parent().base_ring()``. + - ``c`` -- an element of ``self.parent().base_ring()`` OUTPUT: @@ -355,11 +357,9 @@ def _vector_(self, base_ring=None): INPUT: - - ``base_ring`` -- the desired base ring of the vector. + - ``base_ring`` -- the desired base ring of the vector - OUTPUT: - - A vector over the base ring. + OUTPUT: a vector over the base ring EXAMPLES:: @@ -391,7 +391,7 @@ def _vector_(self, base_ring=None): def _richcmp_(self, right, op): """ - Compare self and right. + Compare ``self`` and ``right``. EXAMPLES:: diff --git a/src/sage/modules/fg_pid/fgp_module.py b/src/sage/modules/fg_pid/fgp_module.py index 64a6e085eb7..435796d83e5 100644 --- a/src/sage/modules/fg_pid/fgp_module.py +++ b/src/sage/modules/fg_pid/fgp_module.py @@ -238,14 +238,12 @@ def FGP_Module(V, W, check=True): - ``W`` -- a free `R`-submodule of `V` - - ``check`` -- bool (default: ``True``); if ``True``, more checks - on correctness are performed; in particular, we check the data + - ``check`` -- boolean (default: ``True``); if ``True``, more checks + on correctness are performed. In particular, we check the data types of ``V`` and ``W``, and that `W` is a submodule of `V` with the same base ring. - OUTPUT: - - - the quotient `V/W` as a finitely generated `R`-module + OUTPUT: the quotient `V/W` as a finitely generated `R`-module EXAMPLES:: @@ -302,7 +300,7 @@ class FGP_Module_class(Module): - ``W`` -- an `R`-submodule of `V` - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) EXAMPLES:: @@ -346,8 +344,8 @@ def __init__(self, V, W, check=True): - ``W`` -- an `R`-submodule of `V` - - ``check`` -- bool (default: ``True``); if ``True``, more checks on - correctness are performed; in particular, we check the data types of + - ``check`` -- boolean (default: ``True``); if ``True``, more checks on + correctness are performed. In particular, we check the data types of ``V`` and ``W``, and that `W` is a submodule of `V` with the same base ring `R`. @@ -391,11 +389,9 @@ def _module_constructor(self, V, W, check=True): - ``W`` -- an `R`-submodule of `V` - - ``check`` -- bool (default: ``True``) - - OUTPUT: + - ``check`` -- boolean (default: ``True``) - The quotient `V/W`. + OUTPUT: the quotient `V/W` EXAMPLES:: @@ -416,9 +412,7 @@ def _coerce_map_from_(self, S): - ``S`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -457,7 +451,8 @@ def _mul_(self, other, switch_sides=False): INPUT: - ``other`` -- an element of the base ring - - ``switch_sides`` -- (default: ``False``) left or right multiplication + - ``switch_sides`` -- boolean (default: ``False``); left or right + multiplication EXAMPLES:: @@ -536,7 +531,7 @@ def __eq__(self, other): def __ne__(self, other): """ - True iff ``self`` is not equal to ``other``. + Return ``True`` iff ``self`` is not equal to ``other``. This may not be needed for modules created using the function :func:`FGP_Module`, since those have uniqueness built into @@ -576,7 +571,7 @@ def __ne__(self, other): def __lt__(self, other): """ - True iff ``self`` is a proper submodule of ``other``. + Return ``True`` iff ``self`` is a proper submodule of ``other``. EXAMPLES:: @@ -594,7 +589,7 @@ def __lt__(self, other): def __gt__(self, other): """ - True iff ``other`` is a proper submodule of ``self``. + Return ``True`` iff ``other`` is a proper submodule of ``self``. EXAMPLES:: @@ -612,7 +607,7 @@ def __gt__(self, other): def __ge__(self, other): """ - True iff ``other`` is a submodule of ``self``. + Return ``True`` iff ``other`` is a submodule of ``self``. EXAMPLES:: @@ -641,7 +636,7 @@ def _element_constructor_(self, x, check=True): space and try to put into `V`. If ``x`` is in ``self`` already, just return ``x``. - - `check` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) .. SEEALSO:: :meth:`linear_combination_of_smith_form_gens` @@ -673,7 +668,6 @@ def linear_combination_of_smith_form_gens(self, x): sage: X = ZZ**2 / span([[3,0], [0,2]], ZZ) sage: X.linear_combination_of_smith_form_gens([1]) (1) - """ try: x = self.optimized()[0].V().linear_combination_of_basis(x) @@ -794,7 +788,6 @@ def has_canonical_map_to(self, A): True sage: Q.has_canonical_map_to(A) False - """ if not isinstance(A, FGP_Module_class): return False @@ -856,7 +849,6 @@ def V(self): [1/2 0 0] [ 0 1 0] [ 0 0 1] - """ return self._V @@ -949,7 +941,7 @@ def _smith_form(self): """ Return matrices `S`, `U`, and `V` such that `S = U*R*V`, and `S` is in Smith normal form, and `R` is the relative matrix that defines - self. + ``self``. See :meth:`_relative_matrix`. @@ -986,14 +978,14 @@ def invariants(self, include_ones=False): r""" Return the diagonal entries of the Smith form of the relative matrix that defines ``self`` (see :meth:`._relative_matrix`) - padded with zeros, excluding 1's by default. Thus if ``v`` is the - list of integers returned, then self is abstractly isomorphic to + padded with zeros, excluding 1s by default. Thus if ``v`` is the + list of integers returned, then ``self`` is abstractly isomorphic to the product of cyclic groups `\ZZ/n\ZZ` where `n` is in ``v``. INPUT: - - ``include_ones`` -- bool (default: ``False``); if ``True``, also - include 1's in the output list. + - ``include_ones`` -- boolean (default: ``False``); if ``True``, also + include 1s in the output list EXAMPLES:: @@ -1011,7 +1003,6 @@ def invariants(self, include_ones=False): (0,) sage: Q.invariants(include_ones=True) (1, 1, 0) - """ D, _, _ = self._smith_form() @@ -1083,9 +1074,7 @@ def gens_to_smith(self): To go in the other direction, use :meth:`smith_to_gens`. - OUTPUT: - - - a matrix over the base ring + OUTPUT: a matrix over the base ring EXAMPLES:: @@ -1134,9 +1123,7 @@ def smith_to_gens(self): To go in the other direction, use :meth:`gens_to_smith`. - OUTPUT: - - - a matrix over the base ring + OUTPUT: a matrix over the base ring EXAMPLES:: @@ -1203,7 +1190,7 @@ def gens_vector(self, x, reduce=False): - ``x`` -- element of ``self`` - - ``reduce`` -- (default: ``False``); if ``True``, + - ``reduce`` -- (default: ``False``) if ``True``, reduce coefficients modulo invariants; this is ignored if the base ring is not `\ZZ` @@ -1266,9 +1253,9 @@ def coordinate_vector(self, x, reduce=False): - ``x`` -- element of ``self`` - - ``reduce`` -- (default: ``False``); if ``True``, reduce + - ``reduce`` -- (default: ``False``) if ``True``, reduce coefficients modulo invariants; this is - ignored if the base ring is not ``ZZ``. + ignored if the base ring is not ``ZZ`` OUTPUT: @@ -1503,10 +1490,9 @@ def hom(self, im_gens, codomain=None, check=True): INPUT: - - ``im_gens`` -- a list of the images of ``self.gens()`` in some + - ``im_gens`` -- list of the images of ``self.gens()`` in some `R`-module - EXAMPLES:: sage: V = span([[1/2,1,1], [3/2,2,1], [0,0,1]], ZZ) @@ -1650,7 +1636,6 @@ def _hom_general(self, im_gens, check=True): Morphism from module over Integer Ring with invariants (3,) to module with invariants (3,) that sends the generators to [(1), (1)] - """ m = self.ngens() A = ZZ**m @@ -1740,7 +1725,6 @@ def _Hom_(self, N, category=None): in Category of commutative additive groups sage: type(H) - """ if isinstance(N, FGP_Module_class): return FGP_Homset(self, N) @@ -2000,7 +1984,8 @@ def random_fgp_module(n, R=ZZ, finite=False): - ``R`` -- base ring (default: ``ZZ``) - - ``finite`` -- bool (default: ``True``); if True, make the random module finite + - ``finite`` -- boolean (default: ``True``); if ``True``, make the random + module finite EXAMPLES:: diff --git a/src/sage/modules/fg_pid/fgp_morphism.py b/src/sage/modules/fg_pid/fgp_morphism.py index 4be28f43be1..df08f7ceb0f 100644 --- a/src/sage/modules/fg_pid/fgp_morphism.py +++ b/src/sage/modules/fg_pid/fgp_morphism.py @@ -391,7 +391,7 @@ def lift(self, x): INPUT: - - ``x`` -- element of the codomain of self. + - ``x`` -- element of the codomain of self EXAMPLES:: @@ -410,7 +410,6 @@ def lift(self, x): sage: V = span([[5, -1/2]],ZZ); W = span([[20,-2]],ZZ); Q = V/W; phi=Q.hom([2*Q.0]) sage: x = phi.image().0; phi(phi.lift(x)) == x True - """ x = self.codomain()(x) @@ -485,7 +484,7 @@ def FGP_Homset(X, Y): class FGP_Homset_class(Homset): """ - Homsets of :class:`~sage.modules.fg_pid.fgp_module.FGP_Module` + Homsets of :class:`~sage.modules.fg_pid.fgp_module.FGP_Module`. TESTS:: diff --git a/src/sage/modules/filtered_vector_space.py b/src/sage/modules/filtered_vector_space.py index 1b0bb892b7f..ecea38e8365 100644 --- a/src/sage/modules/filtered_vector_space.py +++ b/src/sage/modules/filtered_vector_space.py @@ -133,11 +133,9 @@ def is_FilteredVectorSpace(X): INPUT: - - ``X`` -- anything. + - ``X`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -220,14 +218,11 @@ def FilteredVectorSpace(arg1, arg2=None, base_ring=QQ, check=True): def normalize_degree(deg): """ - Normalized the degree - - - ``deg`` -- something that defines the degree (either integer or - infinity). + Normalize the degree. - OUTPUT: + - ``deg`` -- something that defines the degree (either integer or infinity) - Plus/minus infinity or a Sage integer. + OUTPUT: plus/minus infinity or a Sage integer EXAMPLES:: @@ -255,10 +250,10 @@ def construct_from_dim_degree(dim, max_degree, base_ring, check): INPUT: - - ``dim`` -- integer. The dimension. + - ``dim`` -- integer; the dimension - - ``max_degree`` -- integer or infinity. The maximal degree where - the vector subspace of the filtration is still the entire space. + - ``max_degree`` -- integer or infinity; the maximal degree where + the vector subspace of the filtration is still the entire space EXAMPLES:: @@ -303,7 +298,7 @@ def construct_from_generators(filtration, base_ring, check): INPUT: - - ``filtration`` -- a dictionary of filtration steps. Each + - ``filtration`` -- dictionary of filtration steps. Each filtration step is a pair consisting of an integer degree and a list/tuple/iterable of vector space generators. The integer ``degree`` stipulates that all filtration steps of degree higher @@ -342,11 +337,11 @@ def construct_from_generators_indices(generators, filtration, base_ring, check): INPUT: - - ``generators`` -- a list/tuple/iterable of vectors, or something + - ``generators`` -- list/tuple/iterable of vectors, or something convertible to them. The generators spanning various subspaces. - - ``filtration`` -- a list or iterable of filtration steps. Each + - ``filtration`` -- list or iterable of filtration steps. Each filtration step is a pair ``(degree, ray_indices)``. The ``ray_indices`` are a list or iterable of ray indices, which span a subspace of the vector space. The integer ``degree`` @@ -408,24 +403,24 @@ class FilteredVectorSpace_class(FreeModule_ambient_field): def __init__(self, base_ring, dim, generators, filtration, check=True): r""" - A descending filtration of a vector space + A descending filtration of a vector space. INPUT: - - ``base_ring`` -- a field. The base field of the ambient vector space. + - ``base_ring`` -- a field; the base field of the ambient vector space - - ``dim`` -- integer. The dimension of the ambient vector space. + - ``dim`` -- integer; the dimension of the ambient vector space - ``generators`` -- tuple of generators for the ambient vector space. These will be used to span the subspaces of the filtration. - - ``filtration`` -- a dictionary of filtration steps in ray + - ``filtration`` -- dictionary of filtration steps in ray index notation. See :func:`construct_from_generators_indices` for details. - - ``check`` -- boolean (optional; default: ``True``). Whether - to perform consistency checks. + - ``check`` -- boolean (default: ``True``); whether + to perform consistency checks TESTS:: @@ -489,7 +484,7 @@ def change_ring(self, base_ring): INPUT: - - ``base_ring`` -- a ring. The new base ring. + - ``base_ring`` -- the new base ring OUTPUT: @@ -511,9 +506,7 @@ def ambient_vector_space(self): """ Return the ambient (unfiltered) vector space. - OUTPUT: - - A vector space. + OUTPUT: a vector space EXAMPLES:: @@ -528,10 +521,8 @@ def is_constant(self): """ Return whether the filtration is constant. - OUTPUT: - - Boolean. Whether the filtered vector spaces are identical in - all degrees. + OUTPUT: boolean; whether the filtered vector spaces are identical in + all degrees EXAMPLES:: @@ -560,9 +551,7 @@ def is_exhaustive(self): A filtration `\{F_d\}` in an ambient vector space `V` is exhaustive if `\cup F_d = V`. See also :meth:`is_separating`. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -585,9 +574,7 @@ def is_separating(self): A filtration `\{F_d\}` in an ambient vector space `V` is exhaustive if `\cap F_d = 0`. See also :meth:`is_exhaustive`. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -690,7 +677,7 @@ def get_degree(self, d): INPUT: - - ``d`` -- Integer. The desired degree of the filtration. + - ``d`` -- integer; the desired degree of the filtration OUTPUT: @@ -727,11 +714,9 @@ def graded(self, d): INPUT: - - ``d`` -- integer. The degree. - - OUTPUT: + - ``d`` -- integer; the degree - The quotient `G_d = F_d / F_{d+1}`. + OUTPUT: the quotient `G_d = F_d / F_{d+1}` EXAMPLES:: @@ -787,7 +772,7 @@ def _repr_field_name(self): RAISES: - :class:`NotImplementedError`: The field does not have an + :exc:`NotImplementedError`: The field does not have an abbreviated name defined. EXAMPLES:: @@ -818,15 +803,13 @@ def _repr_field_name(self): def _repr_vector_space(self, dim): """ - Return a string representation of the vector space of given dimension + Return a string representation of the vector space of given dimension. INPUT: - - ``dim`` -- integer. - - OUTPUT: + - ``dim`` -- integer - String representation of the vector space of dimension ``dim``. + OUTPUT: string representation of the vector space of dimension ``dim`` EXAMPLES:: @@ -849,14 +832,14 @@ def _repr_vector_space(self, dim): def _repr_degrees(self, min_deg, max_deg): """ - Return a string representation + Return a string representation. This method is like :meth:`_repr_` except that the user can select the range of degrees to be shown in the output. INPUT: - - ``min_deg``, ``max_deg`` -- two integers. + - ``min_deg``, ``max_deg`` -- two integers EXAMPLES:: @@ -876,9 +859,7 @@ def _repr_(self): r""" Return as string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -982,11 +963,9 @@ def direct_sum(self, other): INPUT: - - ``other`` -- a filtered vector space. - - OUTPUT: + - ``other`` -- a filtered vector space - The direct sum as a filtered vector space. + OUTPUT: the direct sum as a filtered vector space EXAMPLES:: @@ -1044,7 +1023,7 @@ def tensor_product(self, other): INPUT: - - ``other`` -- a filtered vector space. + - ``other`` -- a filtered vector space OUTPUT: @@ -1107,7 +1086,7 @@ def _power_operation(self, n, operation): INPUT: - - ``n`` -- integer. the number of factors of ``self``. + - ``n`` -- integer; the number of factors of ``self`` - ``operation`` -- string. See :class:`~sage.modules.tensor_operations.TensorOperation` for @@ -1145,8 +1124,7 @@ def exterior_power(self, n): INPUT: - - ``n`` -- integer. Exterior product of how many copies of - ``self``. + - ``n`` -- integer; exterior product of how many copies of ``self`` OUTPUT: @@ -1178,8 +1156,8 @@ def symmetric_power(self, n): INPUT: - - ``n`` -- integer. Symmetric product of how many copies of - ``self``. + - ``n`` -- integer; symmetric product of how many copies of + ``self`` OUTPUT: @@ -1248,11 +1226,11 @@ def shift(self, deg): def random_deformation(self, epsilon=None): """ - Return a random deformation + Return a random deformation. INPUT: - - ``epsilon`` -- a number in the base ring. + - ``epsilon`` -- a number in the base ring OUTPUT: diff --git a/src/sage/modules/finite_submodule_iter.pyx b/src/sage/modules/finite_submodule_iter.pyx index 188ff9d879a..6b4992c8f33 100644 --- a/src/sage/modules/finite_submodule_iter.pyx +++ b/src/sage/modules/finite_submodule_iter.pyx @@ -83,11 +83,11 @@ cdef class FiniteZZsubmodule_iterator: INPUT: - - ``basis`` -- the elements `(g_0, \ldots, g_n)` - - ``order`` (optional) -- the additive_orders `m_i` of `g_i`. - - ``coset_rep`` (optional) -- an element of g, - if one aims to compute a coset of the `\ZZ`-submodule `M`. - - ``immutable`` (optional; default: ``False``) -- set it to + - ``basis`` -- the elements `(g_0, \ldots, g_n)` + - ``order`` -- (optional) the additive_orders `m_i` of `g_i` + - ``coset_rep`` -- (optional) an element of `g`, + if one aims to compute a coset of the `\ZZ`-submodule `M` + - ``immutable`` -- boolean (default: ``False``); set it to ``True`` to return immutable elements. Setting this to ``True`` makes sense if the elements are vectors. See :class:`FiniteFieldsubspace_iterator` for examples. @@ -106,7 +106,7 @@ cdef class FiniteZZsubmodule_iterator: def __init__(self, basis, order=None, coset_rep=None, immutable=False): """ - see :class:`FiniteZZsubmodule_iterator` + See :class:`FiniteZZsubmodule_iterator`. EXAMPLES:: @@ -227,17 +227,17 @@ cdef class FiniteFieldsubspace_iterator(FiniteZZsubmodule_iterator): INPUT: - - ``basis`` -- a list of vectors or a matrix with elements over + - ``basis`` -- list of vectors or a matrix with elements over a finite field. If a matrix is provided then it is not checked whether the matrix is full ranked. Similarly, if a list of vectors is provided, then the linear independence of the vectors is not checked. - - ``coset_rep`` (optional) -- a vector in the same ambient space, - if one aims to compute a coset of the vector space given by ``basis``. + - ``coset_rep`` -- (optional) a vector in the same ambient space, + if one aims to compute a coset of the vector space given by ``basis`` - - ``immutable`` (optional; default: ``False``) -- set it to - ``True`` to return immutable vectors. + - ``immutable`` -- boolean (default: ``False``); set it to + ``True`` to return immutable vectors EXAMPLES:: @@ -260,12 +260,11 @@ cdef class FiniteFieldsubspace_iterator(FiniteZZsubmodule_iterator): sage: c = next(iter) sage: c.is_immutable() True - """ def __init__(self, basis, coset_rep=None, immutable=False): """ - see :class:`FiniteFieldsubspace_iterator` + See :class:`FiniteFieldsubspace_iterator`. EXAMPLES:: @@ -311,18 +310,18 @@ cdef class FiniteFieldsubspace_projPoint_iterator: INPUT: - - ``basis`` -- a list of vectors or a matrix with elements over + - ``basis`` -- list of vectors or a matrix with elements over a finite field. If a matrix is provided then it is not checked whether the matrix is full ranked. Similarly, if a list of vectors is provided, then the linear independence of the vectors is not checked. - - ``normalize`` (optional; default: ``False``) -- boolean which - indicates if the returned vectors should be normalized, i.e. the - first nonzero coordinate is equal to 1. + - ``normalize`` -- boolean (default: ``False``); whether the returned + vectors should be normalized, i.e. the first nonzero coordinate is + equal to 1 - - ``immutable`` (optional; default: ``False``) -- set it to - ``True`` to return immutable vectors. + - ``immutable`` -- boolean (default: ``False``); set it to + ``True`` to return immutable vectors EXAMPLES:: @@ -355,7 +354,7 @@ cdef class FiniteFieldsubspace_projPoint_iterator: def __init__(self, basis, normalize=False, immutable=False): """ - see :class:`FiniteFieldsubspace_projPoint_iterator` + See :class:`FiniteFieldsubspace_projPoint_iterator`. EXAMPLES:: diff --git a/src/sage/modules/fp_graded/element.py b/src/sage/modules/fp_graded/element.py index 5e348276c33..273dea1f60b 100755 --- a/src/sage/modules/fp_graded/element.py +++ b/src/sage/modules/fp_graded/element.py @@ -65,9 +65,7 @@ def degree(self): r""" The degree of ``self``. - OUTPUT: - - The integer degree of ``self`` or raise an error if the zero element. + OUTPUT: the integer degree of ``self`` or raise an error if the zero element EXAMPLES:: @@ -147,9 +145,7 @@ def _lmul_(self, a): - ``a`` -- an element of the algebra the parent module is defined over - OUTPUT: - - The module element `a \cdot x` where `x` is ``self``. + OUTPUT: the module element `a \cdot x` where `x` is ``self`` EXAMPLES:: @@ -180,7 +176,7 @@ def _lmul_(self, a): def vector_presentation(self): r""" - A coordinate vector representing ``self`` when it is non-zero. + A coordinate vector representing ``self`` when it is nonzero. These are coordinates with respect to the basis chosen by :meth:`~sage.modules.fp_graded.module.FPModule.basis_elements`. @@ -190,7 +186,7 @@ def vector_presentation(self): OUTPUT: A vector of elements in the ground ring of the algebra for - this module when this element is non-zero. Otherwise, the + this module when this element is nonzero. Otherwise, the value ``None``. .. SEEALSO:: @@ -250,11 +246,11 @@ def vector_presentation(self): def __bool__(self): r""" - Determine if this element is non-zero. + Determine if this element is nonzero. OUTPUT: - The boolean value ``True`` if this element is non-zero + The boolean value ``True`` if this element is nonzero and ``False`` otherwise. EXAMPLES:: @@ -281,7 +277,7 @@ def __bool__(self): def __eq__(self, other): r""" - True iff ``self`` and ``other`` are equal. + ``True`` iff ``self`` and ``other`` are equal. EXAMPLES:: diff --git a/src/sage/modules/fp_graded/free_element.py b/src/sage/modules/fp_graded/free_element.py index 8dc11e7764a..c37eed11566 100755 --- a/src/sage/modules/fp_graded/free_element.py +++ b/src/sage/modules/fp_graded/free_element.py @@ -164,9 +164,7 @@ def _lmul_(self, a): - ``a`` -- an element of the algebra the parent module is defined over - OUTPUT: - - The module element `a \cdot x` where `x` is this module element. + OUTPUT: the module element `a \cdot x` where `x` is this module element EXAMPLES:: @@ -198,7 +196,7 @@ def _lmul_(self, a): @cached_method def vector_presentation(self): r""" - A coordinate vector representing ``self`` when it is a non-zero + A coordinate vector representing ``self`` when it is a nonzero homogeneous element. These are coordinates with respect to the basis chosen by @@ -209,7 +207,7 @@ def vector_presentation(self): OUTPUT: A vector of elements in the ground ring of the algebra for - this module when this element is non-zero. Otherwise, the value + this module when this element is nonzero. Otherwise, the value ``None``. .. SEEALSO:: diff --git a/src/sage/modules/fp_graded/free_module.py b/src/sage/modules/fp_graded/free_module.py index ea736cc54ea..3f5ec2a9284 100755 --- a/src/sage/modules/fp_graded/free_module.py +++ b/src/sage/modules/fp_graded/free_module.py @@ -79,7 +79,7 @@ sage: Sq(2) * x (Sq(4,1)+Sq(7))*g[0] + Sq(3,1)*g[1] -Each non-zero element has a well-defined degree:: +Each nonzero element has a well-defined degree:: sage: x.degree() 5 @@ -306,7 +306,7 @@ class FreeGradedModule(CombinatorialFreeModule): - ``generator_degrees`` -- tuple of integers defining the number of generators of the module, and their degrees - - ``names`` -- optional, the names of the generators. If ``names`` + - ``names`` -- (optional) the names of the generators. If ``names`` is a comma-separated string like ``'a, b, c'``, then those will be the names. Otherwise, for example if ``names`` is ``abc``, then the names will be ``abc(d,i)``. @@ -549,7 +549,7 @@ def _element_constructor_(self, coefficients): INPUT: - - ``coefficients`` -- a tuple of coefficient (i.e. elements of the + - ``coefficients`` -- tuple of coefficient (i.e. elements of the algebra for this module), an element of FreeGradedModule, or the zero integer constant @@ -646,7 +646,7 @@ def basis_elements(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: @@ -733,11 +733,9 @@ def element_from_coordinates(self, coordinates, n): INPUT: - ``coordinates`` -- a sequence of elements of the ground ring - - ``n`` -- an integer + - ``n`` -- integer - OUTPUT: - - A module element of degree ``n``. + OUTPUT: a module element of degree ``n`` .. SEEALSO:: @@ -811,7 +809,7 @@ def vector_presentation(self, n): INPUT: - - ``n`` -- an integer degree + - ``n`` -- integer degree OUTPUT: @@ -921,7 +919,7 @@ def suspension(self, t): INPUT: - - ``t`` -- an integer + - ``t`` -- integer OUTPUT: @@ -985,12 +983,12 @@ def resolution(self, k, top_dim=None, verbose=False): INPUT: - - ``k`` -- a non-negative integer + - ``k`` -- nonnegative integer - ``top_dim`` -- stop the computation at this degree. Ignored, for compatibility with :meth:`sage.modules.fp_graded.module.FPModule.resolution`. - - ``verbose`` -- (default: ``False``) a boolean to control if - log messages should be emitted + - ``verbose`` -- boolean (default: ``False``); controls whether log + messages should be emitted OUTPUT: @@ -1026,7 +1024,7 @@ def resolution(self, k, top_dim=None, verbose=False): Module endomorphism of Free graded left module on 0 generators over The exterior algebra of rank 3 over Rational Field] """ if k < 0: - raise ValueError('the length of the resolution must be non-negative') + raise ValueError('the length of the resolution must be nonnegative') # The first map \epsilon is the identity map ret_complex = [Hom(self, self).identity()] @@ -1047,9 +1045,7 @@ def minimal_presentation(self, top_dim=None, verbose=False): r""" Return a minimal presentation of ``self``. - OUTPUT: - - The identity morphism as ``self`` is free. + OUTPUT: the identity morphism as ``self`` is free EXAMPLES:: diff --git a/src/sage/modules/fp_graded/free_morphism.py b/src/sage/modules/fp_graded/free_morphism.py index 8044fb3883b..68560eaf9e3 100755 --- a/src/sage/modules/fp_graded/free_morphism.py +++ b/src/sage/modules/fp_graded/free_morphism.py @@ -34,7 +34,7 @@ class FreeGradedModuleMorphism(FPModuleMorphism): - ``parent`` -- a homspace in the category of finitely generated free modules - - ``values`` -- a list of elements in the codomain; each element + - ``values`` -- list of elements in the codomain; each element corresponds (by their ordering) to a module generator in the domain EXAMPLES:: @@ -178,9 +178,7 @@ def fp_module(self): r""" Create a finitely presented module from ``self``. - OUTPUT: - - The finitely presented module with presentation equal to ``self``. + OUTPUT: the finitely presented module with presentation equal to ``self`` EXAMPLES:: diff --git a/src/sage/modules/fp_graded/homspace.py b/src/sage/modules/fp_graded/homspace.py index 6edb4bb7dd6..0e3fe9be73e 100755 --- a/src/sage/modules/fp_graded/homspace.py +++ b/src/sage/modules/fp_graded/homspace.py @@ -143,9 +143,7 @@ def an_element(self, n=0): - ``n`` -- (default: 0) an integer degree - OUTPUT: - - A module homomorphism of degree ``n``. + OUTPUT: a module homomorphism of degree ``n`` EXAMPLES:: @@ -192,11 +190,9 @@ def basis_elements(self, n): INPUT: - - ``n`` -- an integer degree + - ``n`` -- integer degree - OUTPUT: - - A basis for the set of all module homomorphisms of degree ``n``. + OUTPUT: a basis for the set of all module homomorphisms of degree ``n`` EXAMPLES:: @@ -241,7 +237,6 @@ def zero(self): To: Free graded left module on 2 generators over sub-Hopf algebra of mod 2 Steenrod algebra, milnor basis, profile function [3, 2, 1] Defn: g[1] |--> 0 g[3] |--> 0 - """ ngens = len(self.domain().generator_degrees()) return self.element_class(self, [self.codomain().zero()] * ngens) @@ -310,7 +305,7 @@ def _basis_elements(self, n, basis): INPUT: - - ``n`` -- an integer degree + - ``n`` -- integer degree - ``basis`` -- boolean; decide if a basis should be returned or just a single homomorphism diff --git a/src/sage/modules/fp_graded/module.py b/src/sage/modules/fp_graded/module.py index 62536fabc20..992fe25b8ae 100755 --- a/src/sage/modules/fp_graded/module.py +++ b/src/sage/modules/fp_graded/module.py @@ -319,7 +319,7 @@ def _from_dict(self, d, coerce=False, remove_zeros=True): INPUT: - - ``d`` -- a dictionary + - ``d`` -- dictionary This code is taken from the method of the same name for ``sage.combinat.free_module.FreeModule``. @@ -402,7 +402,7 @@ def _element_constructor_(self, x): INPUT: - - ``x`` -- a tuple of coefficients, an element of FPModule, or the + - ``x`` -- tuple of coefficients, an element of FPModule, or the zero integer constant OUTPUT: @@ -644,11 +644,9 @@ def an_element(self, n=None): INPUT: - - ``n`` -- (optional) the degree of the element to construct + - ``n`` -- (optional) the degree of the element to construct - OUTPUT: - - A module element of the given degree. + OUTPUT: a module element of the given degree EXAMPLES:: @@ -683,8 +681,8 @@ def basis_elements(self, n, verbose=False): INPUT: - - ``n`` -- an integer - - ``verbose`` -- (default: ``False``) a boolean to control if log + - ``n`` -- integer + - ``verbose`` -- boolean (default: ``False``); controls whether log messages should be emitted OUTPUT: @@ -798,9 +796,7 @@ def vector_presentation(self, n, verbose=False): - ``n`` -- the degree of the presentation - OUTPUT: - - A vector space. + OUTPUT: a vector space .. SEEALSO:: @@ -1068,7 +1064,7 @@ def suspension(self, t): INPUT: - - ``t`` -- an integer degree by which the module is suspended + - ``t`` -- integer degree by which the module is suspended OUTPUT: @@ -1113,11 +1109,9 @@ def submodule_inclusion(self, spanning_elements): INPUT: - - ``spanning_elements`` -- an iterable of elements + - ``spanning_elements`` -- an iterable of elements - OUTPUT: - - The inclusion of the submodule into this module. + OUTPUT: the inclusion of the submodule into this module Because a submodule of a finitely presented module need not be finitely presented, this method will only work if the @@ -1155,16 +1149,14 @@ def resolution(self, k, top_dim=None, verbose=False): INPUT: - - ``k`` -- a non-negative integer + - ``k`` -- nonnegative integer - ``top_dim`` -- stop the computation at this degree (default: ``None``, but required if the algebra is not finite-dimensional) - - ``verbose`` -- (default: ``False``) a boolean to control if + - ``verbose`` -- boolean (default: ``False``); control if log messages should be emitted - OUTPUT: - - A list of homomorphisms `[\epsilon, f_1, \ldots, f_k]` such that + OUTPUT: list of homomorphisms `[\epsilon, f_1, \ldots, f_k]` such that .. MATH:: @@ -1315,7 +1307,7 @@ def _print_progress(i, k): print('Computing f_%d (%d/%d)' % (i, i, k)) if k < 0: - raise ValueError('the length of the resolution must be non-negative') + raise ValueError('the length of the resolution must be nonnegative') ret_complex = [] diff --git a/src/sage/modules/fp_graded/morphism.py b/src/sage/modules/fp_graded/morphism.py index 219058b4af8..890178110a6 100755 --- a/src/sage/modules/fp_graded/morphism.py +++ b/src/sage/modules/fp_graded/morphism.py @@ -45,11 +45,11 @@ def _create_relations_matrix(module, relations, source_degs, target_degs): INPUT: - ``module`` -- the module where the relations acts - - ``relations`` -- a list of lists of algebra coefficients defining the + - ``relations`` -- list of lists of algebra coefficients defining the matrix `R` - - ``source_degs`` -- a list of integer degrees; its length should be + - ``source_degs`` -- list of integer degrees; its length should be equal to the number of columns of `R` - - ``target_degs`` -- a list of integer degrees; its length should be + - ``target_degs`` -- list of integer degrees; its length should be equal to the number of rows of `R` Furthermore must the degrees given by the input satisfy the following:: @@ -60,12 +60,12 @@ def _create_relations_matrix(module, relations, source_degs, target_degs): OUTPUT: - - ``block_matrix`` -- A list of lists representing a matrix of linear + - ``block_matrix`` -- list of lists representing a matrix of linear transformations `(T_{ij})`. Each transformtion `T_{ij}` is the linear map representing multiplication by the coefficient `r_{ij}` restricted to the module elements of degree ``source_degs[j]``. - - ``R`` -- A matrix representing ``block_matrix`` as a single linear - transformation. + - ``R`` -- a matrix representing ``block_matrix`` as a single linear + transformation TESTS:: @@ -151,7 +151,7 @@ class FPModuleMorphism(Morphism): INPUT: - ``parent`` -- a homspace of finitely presented graded modules - - ``values`` -- a list of elements in the codomain; each element + - ``values`` -- list of elements in the codomain; each element corresponds to a module generator in the domain - ``check`` -- boolean (default: ``True``); if ``True``, check that the morphism is well-defined @@ -301,9 +301,7 @@ def degree(self): r""" The degree of ``self``. - OUTPUT: - - The integer degree of ``self``. + OUTPUT: the integer degree of ``self`` EXAMPLES:: @@ -346,9 +344,7 @@ def values(self): r""" The values under ``self`` of the module generators of the domain module. - OUTPUT: - - A sequence of module elements of the codomain. + OUTPUT: a sequence of module elements of the codomain EXAMPLES:: @@ -619,9 +615,7 @@ def is_zero(self): r""" Decide if ``self`` is the zero homomorphism. - OUTPUT: - - The boolean value ``True`` if ``self`` is trivial and ``False`` otherwise. + OUTPUT: the boolean value ``True`` if ``self`` is trivial and ``False`` otherwise EXAMPLES:: @@ -700,7 +694,7 @@ def __call__(self, x): INPUT: - - ``x`` -- an element of the domain of the homomorphism + - ``x`` -- an element of the domain of the homomorphism OUTPUT: @@ -775,7 +769,7 @@ def vector_presentation(self, n): Return the restriction of ``self`` to the domain module elements of degree ``n``. - The restriction of a non-zero module homomorphism to the free module + The restriction of a nonzero module homomorphism to the free module of module elements of degree `n` is a linear function into the free module of elements of degree `n+d` belonging to the codomain. Here `d` is the degree of this homomorphism. @@ -786,7 +780,7 @@ def vector_presentation(self, n): INPUT: - - ``n`` -- an integer degree + - ``n`` -- integer degree OUTPUT: @@ -1250,7 +1244,7 @@ def split(self, verbose=False): INPUT: - - ``verbose`` -- boolean (default: ``False``); enable progress messages + - ``verbose`` -- boolean (default: ``False``); enable progress messages OUTPUT: @@ -1350,11 +1344,9 @@ def suspension(self, t): INPUT: - - ``t`` -- an integer by which the morphism is suspended - - OUTPUT: + - ``t`` -- integer by which the morphism is suspended - The morphism which is the suspension of ``self`` by the degree ``t``. + OUTPUT: the morphism which is the suspension of ``self`` by the degree ``t`` EXAMPLES:: @@ -1967,7 +1959,7 @@ def fp_module(self): @cached_function def _top_dim(algebra): r""" - The top dimension of ``algebra`` + The top dimension of ``algebra``. This returns infinity if the algebra is infinite-dimensional. If the algebra has a ``top_class`` method, then it is used in the diff --git a/src/sage/modules/fp_graded/steenrod/module.py b/src/sage/modules/fp_graded/steenrod/module.py index 90160d18a19..e799fadf389 100755 --- a/src/sage/modules/fp_graded/steenrod/module.py +++ b/src/sage/modules/fp_graded/steenrod/module.py @@ -249,7 +249,7 @@ def export_module_definition(self, powers_of_two_only=True): # A private function which transforms a vector in a given dimension # to a vector of global indices for the basis elements corresponding - # to the non-zero entries in the vector. E.g. + # to the nonzero entries in the vector. E.g. # _GetIndices(dim=2, vec=(1,0,1)) will return a vector of length two, # (a, b), where a is the index of the first vector in the basis for # the 2-dimensional part of the module, and b is the index of the @@ -357,13 +357,12 @@ def resolution(self, k, top_dim=None, verbose=False): INPUT: - - ``k`` -- non-negative integer + - ``k`` -- nonnegative integer - ``top_dim`` -- (optional) stop the computation at this degree - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed - OUTPUT: - - A list of homomorphisms `[\epsilon, f_1, \ldots, f_k]` such that + OUTPUT: list of homomorphisms `[\epsilon, f_1, \ldots, f_k]` such that .. MATH:: diff --git a/src/sage/modules/fp_graded/steenrod/morphism.py b/src/sage/modules/fp_graded/steenrod/morphism.py index 595db1a33aa..2a57af86866 100755 --- a/src/sage/modules/fp_graded/steenrod/morphism.py +++ b/src/sage/modules/fp_graded/steenrod/morphism.py @@ -98,7 +98,8 @@ def is_injective(self, top_dim=None, verbose=False): - ``top_dim`` -- (optional) stop the computation at this degree; if not specified, this is determined using :meth:`profile` - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed EXAMPLES:: @@ -131,9 +132,10 @@ def kernel_inclusion(self, top_dim=None, verbose=False): - ``top_dim`` -- (optional) stop the computation at this degree; if not specified, this is determined using :meth:`profile` - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed - OUTPUT: An injective homomorphism into the domain ``self`` which is + OUTPUT: an injective homomorphism into the domain ``self`` which is onto the kernel of this homomorphism. EXAMPLES:: @@ -176,7 +178,8 @@ def cokernel_projection(self, verbose=False): INPUT: - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed OUTPUT: @@ -221,7 +224,8 @@ def image(self, top_dim=None, verbose=False): - ``top_dim`` -- integer (optional); used by this function to stop the computation at the given degree - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed OUTPUT: @@ -263,7 +267,6 @@ def image(self, top_dim=None, verbose=False): sage: g.is_zero() True - """ return self._action(FPModuleMorphism.image, top_dim=top_dim, verbose=verbose) @@ -275,9 +278,10 @@ def _resolve_kernel(self, top_dim=None, verbose=False): - ``top_dim`` -- (optional) stop the computation at this degree; if not specified, this is determined using :meth:`profile` - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed - OUTPUT: A homomorphism `j: F \rightarrow D` where `D` is the domain of + OUTPUT: a homomorphism `j: F \rightarrow D` where `D` is the domain of this homomorphism, `F` is free and such that `\ker(self) = \operatorname{im}(j)`. TESTS:: @@ -322,9 +326,10 @@ def _resolve_image(self, top_dim=None, verbose=False): - ``top_dim`` -- (optional) stop the computation at this degree; if not specified, this is determined using :meth:`profile` - - ``verbose`` -- (default: ``False``) whether log messages are printed + - ``verbose`` -- boolean (default: ``False``); whether log messages are + printed - OUTPUT: A homomorphism `j: F \rightarrow C` where `C` is the codomain + OUTPUT: a homomorphism `j: F \rightarrow C` where `C` is the codomain of this homomorphism, `F` is free, and `\operatorname{im}(self) = \operatorname{im}(j)`. diff --git a/src/sage/modules/fp_graded/steenrod/profile.py b/src/sage/modules/fp_graded/steenrod/profile.py index 13c5171b7b1..7326eb37eaf 100755 --- a/src/sage/modules/fp_graded/steenrod/profile.py +++ b/src/sage/modules/fp_graded/steenrod/profile.py @@ -41,15 +41,15 @@ def profile_elt(elt, char=2): - ``elt`` -- element of the Steenrod algebra (or a sub-Hopf algebra of it) or list(s) representing it - - ``char`` (default: 2) -- the characteristic + - ``char`` -- (default: 2) the characteristic ``elt`` could also be a list (when ``char=2``) or a pair of lists (otherwise), in which case it is treated as corresponding to an element of the Steenrod algebra: ``(a, b, c) <-> Sq(a, b, c)`` or ``((a, b, c), (x, y, z)) <-> Q_a Q_b Q_c P(x, y, z)``. - OUTPUT: The profile function corresponding to the smallest - sub-Hopf algebra containing the element passed. + OUTPUT: the profile function corresponding to the smallest + sub-Hopf algebra containing the element passed EXAMPLES:: @@ -102,13 +102,13 @@ def enveloping_profile_elements(alist, char=2): INPUT: - ``alist`` -- list of Steenrod algebra elements - - ``char`` (default: 2) -- the characteristic + - ``char`` -- (default: 2) the characteristic As with :func:`profile_elt`, the entries of ``alist`` could also be iterables or pairs of iterables. - OUTPUT: The profile function for the minimum sub-algebra - containing all the elements of ``alist``. + OUTPUT: the profile function for the minimum sub-algebra + containing all the elements of ``alist`` EXAMPLES:: @@ -155,16 +155,14 @@ def enveloping_profile_elements(alist, char=2): def find_min_profile(prof, char=2): r""" Return the smallest valid profile function containing a tuple of - non-negative integers, + nonnegative integers. INPUT: - - ``prof`` -- a list or tuple of nonnegative integers - - ``char`` (default: 2) -- the characteristic + - ``prof`` -- list or tuple of nonnegative integers + - ``char`` -- (default: 2) the characteristic - OUTPUT: - - - a valid profile containing ``prof`` + OUTPUT: a valid profile containing ``prof`` A profile function `e` must satisfy `e(r) \geq \min( e(r-i) - i, e(i))` for all `0 < i < r`, and at odd primes, if `k(i+j) = 1`, diff --git a/src/sage/modules/free_module.py b/src/sage/modules/free_module.py index 6bf1b79bd7d..6b407414030 100644 --- a/src/sage/modules/free_module.py +++ b/src/sage/modules/free_module.py @@ -308,7 +308,7 @@ def create_object(self, version, key): def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_matrix=None, *, with_basis='standard', rank=None, basis_keys=None, **args): r""" - Create a free module over the given commutative ``base_ring`` + Create a free module over the given commutative ``base_ring``. ``FreeModule`` can be called with the following positional arguments: @@ -318,22 +318,22 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m INPUT: - - ``base_ring`` -- a commutative ring + - ``base_ring`` -- a commutative ring - - ``rank`` -- a nonnegative integer + - ``rank`` -- nonnegative integer - - ``basis_keys`` -- a finite or enumerated family of arbitrary objects + - ``basis_keys`` -- a finite or enumerated family of arbitrary objects - - ``sparse`` -- boolean (default ``False``) + - ``sparse`` -- boolean (default: ``False``) - - ``inner_product_matrix`` -- the inner product matrix (default ``None``) + - ``inner_product_matrix`` -- the inner product matrix (default: ``None``) - - ``with_basis`` -- either ``"standard"`` (the default), in which case - a free module with the standard basis as the distinguished basis is created; - or ``None``, in which case a free module without distinguished basis is - created. + - ``with_basis`` -- either ``'standard'`` (the default), in which case + a free module with the standard basis as the distinguished basis is created; + or ``None``, in which case a free module without distinguished basis is + created. - - further options may be accepted by various implementation classes + - further options may be accepted by various implementation classes OUTPUT: a free module @@ -341,9 +341,9 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m depending on the input. Not all combinations of options are implemented. - - If the parameter ``basis_keys`` is provided, it must be a finite - or enumerated family of objects, and an instance of - :class:`CombinatorialFreeModule` is created. + - If the parameter ``basis_keys`` is provided, it must be a finite + or enumerated family of objects, and an instance of + :class:`CombinatorialFreeModule` is created. EXAMPLES:: @@ -355,9 +355,9 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m for more examples and details, including its :class:`UniqueRepresentation` semantics. - - If the parameter ``with_basis`` is set to ``None``, then a free module - of the given ``rank`` without distinguished basis is created. It is - represented by an instance of :class:`FiniteRankFreeModule`. + - If the parameter ``with_basis`` is set to ``None``, then a free module + of the given ``rank`` without distinguished basis is created. It is + represented by an instance of :class:`FiniteRankFreeModule`. EXAMPLES:: @@ -367,20 +367,19 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m See the documentation of :class:`FiniteRankFreeModule` for more options, examples, and details. - - If ``rank`` is provided and the option ``with_basis`` is left at its - default value, ``"standard"``, then a free ambient module with - distinguished standard basis indexed by ``range(rank)`` is created. - There is only one dense and one sparse free ambient module of - given ``rank`` over ``base_ring``. - - EXAMPLES:: + - If ``rank`` is provided and the option ``with_basis`` is left at its + default value, ``'standard'``, then a free ambient module with + distinguished standard basis indexed by ``range(rank)`` is created. + There is only one dense and one sparse free ambient module of + given ``rank`` over ``base_ring``. - sage: FreeModule(Integers(8), 10) - Ambient free module of rank 10 over Ring of integers modulo 8 + EXAMPLES:: - The remainder of this documentation discusses this case of - free ambient modules. + sage: FreeModule(Integers(8), 10) + Ambient free module of rank 10 over Ring of integers modulo 8 + The remainder of this documentation discusses this case of + free ambient modules. EXAMPLES: @@ -485,7 +484,6 @@ def FreeModule(base_ring, rank_or_basis_keys=None, sparse=False, inner_product_m Refactor modules such that it only counts what category the base ring belongs to, but not what is its Python class. - EXAMPLES:: sage: FreeModule(QQ, ['a', 'b', 'c']) @@ -598,7 +596,7 @@ def VectorSpace(K, dimension_or_basis_keys=None, sparse=False, inner_product_mat (0, 0, 1) ] - The base must be a field or a :class:`TypeError` is raised. + The base must be a field or a :exc:`TypeError` is raised. :: @@ -622,16 +620,16 @@ def span(gens, base_ring=None, check=True, already_echelonized=False): INPUT: - - ``gens`` -- a list of either vectors or lists of ring elements + - ``gens`` -- list of either vectors or lists of ring elements used to generate the span - - ``base_ring`` -- (default: ``None``); a principal ideal domain + - ``base_ring`` -- (default: ``None``) a principal ideal domain for the ring of scalars - - ``check`` -- (default: ``True``); passed to the ``span()`` method + - ``check`` -- (default: ``True``) passed to the ``span()`` method of the ambient module - - ``already_echelonized`` -- (default: ``False``); set to ``True`` + - ``already_echelonized`` -- (default: ``False``) set to ``True`` if the vectors form the rows of a matrix in echelon form, in order to skip the computation of an echelonized basis for the span. @@ -845,7 +843,7 @@ def basis_seq(V, vecs): def is_FreeModule(M): """ - Return True if M inherits from FreeModule_generic. + Return ``True`` if M inherits from ``FreeModule_generic``. EXAMPLES:: @@ -882,7 +880,7 @@ class Module_free_ambient(Module): - ``base_ring`` -- a commutative ring - - ``degree`` -- a non-negative integer; degree of the ambient free module + - ``degree`` -- nonnegative integer; degree of the ambient free module - ``sparse`` -- boolean (default: ``False``) @@ -1038,9 +1036,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -1610,11 +1606,11 @@ def span(self, gens, base_ring=None, check=True, already_echelonized=False): INPUT: - - ``gens`` -- a list of vectors + - ``gens`` -- list of vectors - ``base_ring`` -- (optional) a ring - - ``check`` -- boolean (default: ``True``): whether or not to + - ``check`` -- boolean (default: ``True``); whether or not to coerce entries of gens into base field - ``already_echelonized`` -- boolean (default: ``False``); @@ -1738,9 +1734,9 @@ def submodule(self, gens, check=True, already_echelonized=False): INPUT: - - ``gens`` -- a list of free module elements or a free module + - ``gens`` -- list of free module elements or a free module - - ``check`` -- (default: ``True``) whether or not to verify + - ``check`` -- boolean (default: ``True``); whether or not to verify that the gens are in ``self`` OUTPUT: @@ -1769,7 +1765,7 @@ def submodule(self, gens, check=True, already_echelonized=False): [3 3 0] We try to create a submodule that is not really a submodule, - which results in an :class:`ArithmeticError` exception:: + which results in an :exc:`ArithmeticError` exception:: sage: W.submodule([B[0] - B[1]]) Traceback (most recent call last): @@ -1821,7 +1817,7 @@ def quotient_module(self, sub, check=True): - ``sub`` -- a submodule of ``self`` or something that can be turned into one via ``self.submodule(sub)`` - - ``check`` -- (default: ``True``) whether or not to check that + - ``check`` -- boolean (default: ``True``); whether or not to check that ``sub`` is a submodule EXAMPLES:: @@ -1942,9 +1938,9 @@ class FreeModule_generic(Module_free_ambient): - ``base_ring`` -- a commutative ring - - ``rank`` -- a non-negative integer + - ``rank`` -- nonnegative integer - - ``degree`` -- a non-negative integer + - ``degree`` -- nonnegative integer - ``sparse`` -- boolean (default: ``False``) @@ -2014,7 +2010,6 @@ def __init__(self, base_ring, rank, degree, sparse=False, sage: N.element_class - """ if base_ring not in CommutativeRings(): warn("You are constructing a free module\n" @@ -2041,7 +2036,7 @@ def __init__(self, base_ring, rank, degree, sparse=False, def construction(self): """ - The construction functor and base ring for self. + The construction functor and base ring for ``self``. EXAMPLES:: @@ -2104,9 +2099,9 @@ def dense_module(self): def _dense_module(self): """ - Creates a dense module with the same defining data as self. + Create a dense module with the same defining data as ``self``. - N.B. This function is for internal use only! See dense_module for + N.B. This function is for internal use only! See ``dense_module`` for use. EXAMPLES:: @@ -2161,9 +2156,9 @@ def sparse_module(self): def _sparse_module(self): """ - Creates a sparse module with the same defining data as self. + Create a sparse module with the same defining data as ``self``. - N.B. This function is for internal use only! See sparse_module for + N.B. This function is for internal use only! See ``sparse_module`` for use. EXAMPLES:: @@ -2183,9 +2178,9 @@ def _element_constructor_(self, x, coerce=True, copy=True, check=True): The ``coerce`` and ``copy`` arguments are passed on to the underlying element constructor. If ``check`` is ``True``, confirm that the - element specified by x does in fact lie in self. + element specified by x does in fact lie in ``self``. - .. note:: + .. NOTE:: In the case of an inexact base ring (i.e. RDF), we don't verify that the element is in the subspace, even when @@ -2482,7 +2477,7 @@ def __iter__(self): if R in InfiniteEnumeratedSets(): # This makes iter(ZZ^n) produce vectors in a "natural" order, - # rather than only vectors with the first component non-zero. + # rather than only vectors with the first component nonzero. # Algorithm: Initial version which ordered by max-norm due to # Aleksei Udovenko, adapted by Lorenz Panny to order by 1-norm # primarily and by max-norm secondarily. @@ -2532,9 +2527,7 @@ def cardinality(self): r""" Return the cardinality of the free module. - OUTPUT: - - Either an integer or ``+Infinity``. + OUTPUT: either an integer or ``+Infinity`` EXAMPLES:: @@ -2758,25 +2751,24 @@ def direct_sum(self, other): def coordinates(self, v, check=True): """ - Write `v` in terms of the basis for self. + Write `v` in terms of the basis for ``self``. INPUT: - ``v`` -- vector - - ``check`` -- boolean (default: ``True``); if ``True``, also verify that - `v` is really in ``self``. + - ``check`` -- boolean (default: ``True``); if ``True``, also verify + that `v` is really in ``self`` OUTPUT: list - Returns a list `c` such that if `B` is the basis - for self, then + Returns a list `c` such that if `B` is the basis for ``self``, then .. MATH:: \\sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -2790,14 +2782,14 @@ def coordinates(self, v, check=True): def coordinate_vector(self, v, check=True): """ Return the vector whose coefficients give `v` as a linear - combination of the basis for self. + combination of the basis for ``self``. INPUT: - ``v`` -- vector - ``check`` -- boolean (default: ``True``); if ``True``, also verify that - `v` is really in ``self``. + `v` is really in ``self`` OUTPUT: list @@ -3012,9 +3004,9 @@ def gen(self, i=0): INPUT: - - `i` -- an integer (default 0) + - ``i`` -- integer (default: 0) - OUTPUT: `i`-th basis vector for ``self``. + OUTPUT: `i`-th basis vector for ``self`` EXAMPLES:: @@ -3097,12 +3089,12 @@ def hom(self, im_gens, codomain=None, **kwds): EXAMPLES:: - sage: W = ZZ^2; W.hom(matrix(1, [1, 2]), side="right") + sage: W = ZZ^2; W.hom(matrix(1, [1, 2]), side='right') Free module morphism defined as left-multiplication by the matrix [1 2] Domain: Ambient free module of rank 2 over the principal ideal domain Integer Ring Codomain: Ambient free module of rank 1 over the principal ideal domain Integer Ring - sage: V = QQ^2; V.hom(identity_matrix(2), side="right") + sage: V = QQ^2; V.hom(identity_matrix(2), side='right') Vector space morphism represented as left-multiplication by the matrix: [1 0] [0 1] @@ -3167,7 +3159,7 @@ def _inner_product_is_dot_product(self): def is_ambient(self): """ - Returns False since this is not an ambient free module. + Return ``False`` since this is not an ambient free module. EXAMPLES:: @@ -3193,7 +3185,7 @@ def is_ambient(self): def is_dense(self): """ Return ``True`` if the underlying representation of - this module uses dense vectors, and False otherwise. + this module uses dense vectors, and ``False`` otherwise. EXAMPLES:: @@ -3221,7 +3213,7 @@ def is_full(self): def is_finite(self): """ - Returns True if the underlying set of this free module is finite. + Return ``True`` if the underlying set of this free module is finite. EXAMPLES:: @@ -3236,7 +3228,7 @@ def is_finite(self): def ngens(self): """ - Returns the number of basis elements of this free module. + Return the number of basis elements of this free module. EXAMPLES:: @@ -3255,7 +3247,7 @@ def ngens(self): def nonembedded_free_module(self): """ - Returns an ambient free module that is isomorphic to this free + Return an ambient free module that is isomorphic to this free module. Thus if this free module is of rank `n` over a ring @@ -3271,16 +3263,16 @@ def nonembedded_free_module(self): def random_element(self, prob=1.0, *args, **kwds): """ - Returns a random element of self. + Return a random element of ``self``. INPUT: - ``prob`` -- float. Each coefficient will be set to zero with - probability `1-prob`. Otherwise coefficients will be chosen - randomly from base ring (and may be zero). + probability `1-prob`. Otherwise coefficients will be chosen + randomly from base ring (and may be zero). - ``*args``, ``**kwds`` -- passed on to the :func:`random_element` - function of the base ring. + function of the base ring EXAMPLES:: @@ -3329,7 +3321,7 @@ def rank(self): def __bool__(self): """ Return ``True`` if and only if the rank of this module is - non-zero. In other words, this returns ``False`` for the zero + nonzero. In other words, this returns ``False`` for the zero module and ``True`` otherwise (apart from the exceptional case where the base ring is the zero ring). @@ -3621,7 +3613,6 @@ def _mul_(self, other, switch_sides=False): over Finite Field of size 2 Basis matrix: [1 1] - """ B = self.basis_matrix() B = other * B if switch_sides else B * other @@ -3669,8 +3660,8 @@ def __init__(self, base_ring, rank, degree, sparse=False, coordinate_ring=None, def __add__(self, other): r""" - Return the sum of ``self`` and other, where both ``self`` and ``other`` must be - submodules of the ambient vector space. + Return the sum of ``self`` and ``other``, where both ``self`` and + ``other`` must be submodules of the ambient vector space. EXAMPLES: @@ -4038,7 +4029,7 @@ def index_in_saturation(self): def saturation(self): r""" Return the saturated submodule of `R^n` that spans the same - vector space as self. + vector space as ``self``. EXAMPLES: @@ -4181,19 +4172,17 @@ def span_of_basis(self, basis, base_ring=None, check=True, already_echelonized=F def submodule_with_basis(self, basis, check=True, already_echelonized=False): r""" - Create the R-submodule of the ambient vector space with given - basis, where R is the base ring of self. + Create the `R`-submodule of the ambient vector space with given + basis, where `R` is the base ring of ``self``. INPUT: - - ``basis`` -- a list of linearly independent vectors + - ``basis`` -- list of linearly independent vectors - ``check`` -- whether or not to verify that each gen is in - the ambient vector space + the ambient vector space - OUTPUT: - - - ``FreeModule`` -- the `R`-submodule with given basis + OUTPUT: ``FreeModule``; the `R`-submodule with given basis EXAMPLES: @@ -4260,12 +4249,10 @@ def vector_space_span(self, gens, check=True): INPUT: + - ``gens`` -- list of vector in ``self`` - - ``gens`` -- a list of vector in self - - - ``check`` -- whether or not to verify that each gen - is in the ambient vector space - + - ``check`` -- whether or not to verify that each gen + is in the ambient vector space OUTPUT: a vector subspace @@ -4322,10 +4309,10 @@ def vector_space_span_of_basis(self, basis, check=True): INPUT: - - ``basis`` -- a list of linearly independent vectors + - ``basis`` -- list of linearly independent vectors - ``check`` -- whether or not to verify that each gen is in - the ambient vector space + the ambient vector space OUTPUT: a vector subspace with user-specified basis @@ -4351,7 +4338,7 @@ def quotient_module(self, sub, check=True, **kwds): - ``sub`` -- a submodule of ``self``, or something that can be turned into one via ``self.submodule(sub)`` - - ``check`` -- (default: ``True``) whether or not to check + - ``check`` -- boolean (default: ``True``); whether or not to check that ``sub`` is a submodule - further named arguments, that are passed to the constructor @@ -4383,7 +4370,7 @@ class FreeModule_generic_field(FreeModule_generic_pid): """ def __init__(self, base_field, dimension, degree, sparse=False, category=None): """ - Creates a vector space over a field. + Create a vector space over a field. EXAMPLES:: @@ -4406,7 +4393,7 @@ def __init__(self, base_field, dimension, degree, sparse=False, category=None): def _Hom_(self, Y, category): r""" - Returns a homspace whose morphisms have this vector space as domain. + Return a homspace whose morphisms have this vector space as domain. This is called by the general methods such as :meth:`sage.structure.parent.Parent.Hom`. @@ -4501,7 +4488,7 @@ def scale(self, other): def __add__(self, other): """ - Return the sum of ``self`` and other. + Return the sum of ``self`` and ``other``. EXAMPLES:: @@ -4543,8 +4530,8 @@ def echelonized_basis_matrix(self): def intersection(self, other): """ - Return the intersection of ``self`` and other, which must be - R-submodules of a common ambient vector space. + Return the intersection of ``self`` and ``other``, which must be + `R`-submodules of a common ambient vector space. EXAMPLES:: @@ -4641,7 +4628,7 @@ def intersection(self, other): def is_subspace(self, other): """ - True if this vector space is a subspace of other. + ``True`` if this vector space is a subspace of ``other``. EXAMPLES:: @@ -4665,19 +4652,17 @@ def span_of_basis(self, basis, base_ring=None, check=True, already_echelonized=F field of ``self`` or user specified base_ring. Note that this span is a subspace of the ambient vector space, but - need not be a subspace of self. + need not be a subspace of ``self``. INPUT: + - ``basis`` -- list of vectors - - ``basis`` -- list of vectors - - - ``check`` -- boolean (default: ``True``): whether or not to - coerce entries of gens into base field - - - ``already_echelonized`` -- boolean (default: ``False``): - set this if you know the gens are already in echelon form + - ``check`` -- boolean (default: ``True``); whether or not to + coerce entries of gens into base field + - ``already_echelonized`` -- boolean (default: ``False``); + set this if you know the gens are already in echelon form EXAMPLES:: @@ -4693,7 +4678,7 @@ def span_of_basis(self, basis, base_ring=None, check=True, already_echelonized=F [3 3 0] The basis vectors must be linearly independent or a - :class:`ValueError` exception is raised:: + :exc:`ValueError` exception is raised:: sage: W.span_of_basis([[2,2,2], [3,3,3]]) Traceback (most recent call last): @@ -4722,13 +4707,13 @@ def subspace(self, gens, check=True, already_echelonized=False): INPUT: - - ``gens`` -- list of vectors + - ``gens`` -- list of vectors - - ``check`` -- boolean (default: ``True``) verify that gens - are all in ``self``. + - ``check`` -- boolean (default: ``True``); verify that gens + are all in ``self`` - - ``already_echelonized`` -- boolean (default: ``False``) set - to True if you know the gens are in Echelon form. + - ``already_echelonized`` -- boolean (default: ``False``); set + to ``True`` if you know the gens are in Echelon form EXAMPLES: @@ -4752,7 +4737,7 @@ def subspace(self, gens, check=True, already_echelonized=False): [1 1 0] With ``check=True`` (the default) the mistake is correctly - detected and reported with an :class:`ArithmeticError` exception:: + detected and reported with an :exc:`ArithmeticError` exception:: sage: W.subspace([[1,1,0]], check=True) Traceback (most recent call last): @@ -4767,7 +4752,7 @@ def subspaces(self, dim): INPUT: - - ``dim`` -- int, dimension of subspaces to be generated + - ``dim`` -- integer; dimension of subspaces to be generated EXAMPLES:: @@ -4924,8 +4909,8 @@ def complement(self): def vector_space(self, base_field=None): """ - Return the vector space associated to self. Since ``self`` is a vector - space this function simply returns self, unless the base field is + Return the vector space associated to ``self``. Since ``self`` is a vector + space this function simply returns ``self``, unless the base field is different. EXAMPLES:: @@ -4945,7 +4930,7 @@ def vector_space(self, base_field=None): def zero_submodule(self): """ - Return the zero submodule of self. + Return the zero submodule of ``self``. EXAMPLES:: @@ -4958,7 +4943,7 @@ def zero_submodule(self): def zero_subspace(self): """ - Return the zero subspace of self. + Return the zero subspace of ``self``. EXAMPLES:: @@ -4971,19 +4956,21 @@ def zero_subspace(self): def linear_dependence(self, vectors, zeros='left', check=True): r""" - Returns a list of vectors giving relations of linear dependence for the input list of vectors. + Return a list of vectors giving relations of linear dependence for the + input list of vectors. + Can be used to check linear independence of a set of vectors. INPUT: - - ``vectors`` -- A list of vectors, all from the same vector - space. + - ``vectors`` -- list of vectors; all from the same vector + space - - ``zeros`` -- (default: ``'left'``); ``'left'`` or ``'right'`` + - ``zeros`` -- (default: ``'left'``) ``'left'`` or ``'right'`` as a general preference for where zeros are located in the returned coefficients - - ``check`` -- (default: ``True``); if ``True`` each item in + - ``check`` -- (default: ``True``) if ``True`` each item in the list ``vectors`` is checked for membership in ``self``. Set to ``False`` if you can be certain the vectors come from the vector space. @@ -5000,7 +4987,7 @@ def linear_dependence(self, vectors, zeros='left', check=True): list being empty, so this provides a test - see the examples below. The returned vectors are always independent, and with ``zeros`` set to - ``'left'`` they have 1's in their first non-zero entries and a qualitative + ``'left'`` they have 1s in their first nonzero entries and a qualitative disposition to having zeros in the low-index entries. With ``zeros`` set to ``'right'`` the situation is reversed with a qualitative disposition for zeros in the high-index entries. @@ -5167,7 +5154,7 @@ def quotient_module(self, sub, check=True): - ``sub`` -- a submodule of ``self``, or something that can be turned into one via ``self.submodule(sub)`` - - ``check`` -- (default: ``True``) whether or not to check + - ``check`` -- boolean (default: ``True``); whether or not to check that ``sub`` is a submodule EXAMPLES:: @@ -5305,22 +5292,21 @@ def quotient_abstract(self, sub, check=True, **kwds): INPUT: - - ``sub`` -- a submodule of ``self`` or something that can - be turned into one via ``self.submodule(sub)`` + - ``sub`` -- a submodule of ``self`` or something that can + be turned into one via ``self.submodule(sub)`` - - ``check`` -- (default: ``True``) whether or not to check - that sub is a submodule + - ``check`` -- boolean (default: ``True``); whether or not to check + that sub is a submodule - further named arguments, that are currently ignored. OUTPUT: - - ``U`` -- the quotient as an abstract *ambient* free module - - - ``pi`` -- projection map to the quotient + - ``U``; the quotient as an abstract *ambient* free module - - ``lift`` -- lifting map back from quotient + - ``pi``; projection map to the quotient + - ``lift``; lifting map back from quotient EXAMPLES:: @@ -5377,11 +5363,11 @@ def __init__(self, base_ring, rank, sparse=False, coordinate_ring=None, category INPUT: - - ``base_ring`` -- a commutative ring + - ``base_ring`` -- a commutative ring - - ``rank`` -- a non-negative integer + - ``rank`` -- nonnegative integer - - ``sparse`` -- boolean (default: ``False``) + - ``sparse`` -- boolean (default: ``False``) - ``coordinate_ring`` -- a ring containing ``base_ring`` (default: equal to ``base_ring``) @@ -5468,7 +5454,7 @@ def _coerce_map_from_(self, M): def _dense_module(self): """ - Creates a dense module with the same defining data as self. + Create a dense module with the same defining data as ``self``. N.B. This function is for internal use only! See dense_module for use. @@ -5484,7 +5470,7 @@ def _dense_module(self): def _sparse_module(self): """ - Creates a sparse module with the same defining data as self. + Create a sparse module with the same defining data as ``self``. N.B. This function is for internal use only! See sparse_module for use. @@ -5500,7 +5486,7 @@ def _sparse_module(self): def echelonized_basis_matrix(self): """ - The echelonized basis matrix of self. + The echelonized basis matrix of ``self``. EXAMPLES:: @@ -5635,7 +5621,7 @@ def _echelon_matrix_richcmp(self, other, op): def _repr_(self): """ - The printing representation of self. + The printing representation of ``self``. EXAMPLES:: @@ -5737,10 +5723,8 @@ def basis(self): OUTPUT: - - - ``Sequence`` -- an immutable sequence with universe - this ambient free module - + - ``Sequence`` -- an immutable sequence with universe + this ambient free module EXAMPLES:: @@ -5858,7 +5842,7 @@ def coordinate_vector(self, v, check=True): \\sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -5877,10 +5861,10 @@ def echelon_coordinate_vector(self, v, check=True): INPUT: - - ``v`` -- vector + - ``v`` -- vector - - ``check`` -- boolean (default: ``True``); if True, also - verify that `v` is really in ``self``. + - ``check`` -- boolean (default: ``True``); if ``True``, also + verify that `v` is really in ``self`` OUTPUT: list @@ -5904,8 +5888,8 @@ def echelon_coordinate_vector(self, v, check=True): def echelon_coordinates(self, v, check=True): """ - Returns the coordinate vector of v in terms of the echelon basis - for self. + Return the coordinate vector of v in terms of the echelon basis + for ``self``. EXAMPLES:: @@ -5939,18 +5923,16 @@ def echelon_coordinates(self, v, check=True): def random_element(self, prob=1.0, *args, **kwds): """ - Returns a random element of self. + Return a random element of ``self``. INPUT: - - ``prob`` -- float. Each coefficient will be set to zero with - probability `1-prob`. Otherwise coefficients will be chosen - randomly from base ring (and may be zero). + probability `1-prob`. Otherwise coefficients will be chosen + randomly from base ring (and may be zero). - ``*args``, ``**kwds`` -- passed on to random_element function of base - ring. - + ring EXAMPLES:: @@ -6013,9 +5995,9 @@ def gen(self, i=0): INPUT: - - `i` -- an integer (default 0) + - ``i`` -- integer (default: 0) - OUTPUT: `i`-th basis vector for ``self``. + OUTPUT: `i`-th basis vector for ``self`` EXAMPLES:: @@ -6197,8 +6179,8 @@ def coordinate_vector(self, v, check=True): - ``v`` -- vector - - ``check`` -- boolean (default: ``True``); if ``True``, also verify that - `v` is really in ``self``. + - ``check`` -- boolean (default: ``True``); if ``True``, also verify + that `v` is really in ``self`` OUTPUT: list @@ -6209,7 +6191,7 @@ def coordinate_vector(self, v, check=True): \\sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -6232,7 +6214,7 @@ def coordinate_vector(self, v, check=True): def vector_space(self, base_field=None): """ - Returns the vector space obtained from ``self`` by tensoring with the + Return the vector space obtained from ``self`` by tensoring with the fraction field of the base ring and extending to the field. EXAMPLES:: @@ -6266,7 +6248,7 @@ def __init__(self, base_ring, rank, sparse=False, coordinate_ring=None, category - ``base_ring`` -- a principal ideal domain - - ``rank`` -- a non-negative integer + - ``rank`` -- nonnegative integer - ``sparse`` -- boolean (default: ``False``) @@ -6296,7 +6278,7 @@ def __init__(self, base_ring, rank, sparse=False, coordinate_ring=None, category def _repr_(self) -> str: """ - The printing representation of self. + The printing representation of ``self``. EXAMPLES:: @@ -6348,9 +6330,6 @@ def _repr_(self) -> str: ############################################################################### class FreeModule_ambient_field(FreeModule_generic_field, FreeModule_ambient_pid): - """ - - """ def __init__(self, base_field, dimension, sparse=False, category=None): """ Create the ambient vector space of given dimension over the given @@ -6358,11 +6337,11 @@ def __init__(self, base_field, dimension, sparse=False, category=None): INPUT: - - ``base_field`` -- a field + - ``base_field`` -- a field - - ``dimension`` -- a non-negative integer + - ``dimension`` -- nonnegative integer - - ``sparse`` -- boolean (default: ``False``) + - ``sparse`` -- boolean (default: ``False``) EXAMPLES:: @@ -6373,7 +6352,7 @@ def __init__(self, base_field, dimension, sparse=False, category=None): def _repr_(self): """ - The printing representation of self. + The printing representation of ``self``. EXAMPLES:: @@ -6417,7 +6396,7 @@ def _repr_(self): def ambient_vector_space(self): """ - Returns ``self`` as the ambient vector space. + Return ``self`` as the ambient vector space. EXAMPLES:: @@ -6429,7 +6408,7 @@ def ambient_vector_space(self): def base_field(self): """ - Returns the base field of this vector space. + Return the base field of this vector space. EXAMPLES:: @@ -6488,28 +6467,27 @@ class FreeModule_submodule_with_basis_pid(FreeModule_generic_pid): INPUT: - ``ambient`` -- ambient free module over a principal ideal domain `R`, - i.e. `R^n`; + i.e. `R^n` - ``basis`` -- list of elements of `K^n`, where `K` is the fraction field - of `R`. These elements must be linearly independent and will be used as - the default basis of the constructed submodule; + of `R`; these elements must be linearly independent and will be used as + the default basis of the constructed submodule - - ``check`` -- (default: ``True``) if ``False``, correctness of the input - will not be checked and type conversion may be omitted, use with care; + - ``check`` -- boolean (default: ``True``); if ``False``, correctness of + the input will not be checked and type conversion may be omitted, use + with care - - ``echelonize`` -- (default:``False``) if ``True``, ``basis`` will be + - ``echelonize`` -- (default: ``False``) if ``True``, ``basis`` will be echelonized and the result will be used as the default basis of the constructed submodule; - - `` echelonized_basis`` -- (default: ``None``) if not ``None``, must be - the echelonized basis spanning the same submodule as ``basis``; - - - ``already_echelonized`` -- (default: ``False``) if ``True``, ``basis`` - must be already given in the echelonized form. + - ``echelonized_basis`` -- (default: ``None``) if not ``None``, must be + the echelonized basis spanning the same submodule as ``basis`` - OUTPUT: + - ``already_echelonized`` -- boolean (default: ``False``); if ``True``, + ``basis`` must be already given in the echelonized form - - `R`-submodule of `K^n` with the user-specified ``basis``. + OUTPUT: `R`-submodule of `K^n` with the user-specified ``basis`` EXAMPLES:: @@ -6649,7 +6627,7 @@ def __hash__(self): def _echelon_matrix_richcmp(self, other, op): r""" - Compare the free module ``self`` with other. + Compare the free module ``self`` with ``other``. Modules are ordered by their ambient spaces, then by dimension, then in order by their echelon matrices. @@ -6724,7 +6702,7 @@ def _echelon_matrix_richcmp(self, other, op): def construction(self): """ - Returns the functorial construction of self, namely, the subspace + Return the functorial construction of ``self``, namely, the subspace of the ambient module spanned by the given basis. EXAMPLES:: @@ -6818,7 +6796,6 @@ def _denominator(self, B): [ 0 23/6 46/3] sage: L._denominator(L.echelonized_basis_matrix().list()) 30 - """ if not B: return 1 @@ -6830,7 +6807,7 @@ def _denominator(self, B): def _repr_(self): """ - The printing representation of self. + The printing representation of ``self``. EXAMPLES:: @@ -6949,7 +6926,6 @@ def ambient(self): [5 7 9] sage: U.ambient() Ambient free module of rank 3 over the principal ideal domain Integer Ring - """ if self.base_ring() == self.coordinate_ring(): return self.ambient_module() @@ -7049,10 +7025,10 @@ def echelon_coordinates(self, v, check=True): INPUT: - - ``v`` -- vector + - ``v`` -- vector - - ``check`` -- boolean (default: ``True``); if ``True``, also - verify that `v` is really in ``self``. + - ``check`` -- boolean (default: ``True``); if ``True``, also + verify that `v` is really in ``self`` OUTPUT: list @@ -7063,7 +7039,7 @@ def echelon_coordinates(self, v, check=True): \sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -7164,10 +7140,10 @@ def user_to_echelon_matrix(self): def echelon_to_user_matrix(self): """ Return matrix that transforms the echelon basis to the user basis - of self. This is a matrix `A` such that if `v` is a + of ``self``. This is a matrix `A` such that if `v` is a vector written with respect to the echelon basis for ``self`` then `vA` is that vector written with respect to the user basis - of self. + of ``self``. EXAMPLES:: @@ -7183,7 +7159,7 @@ def echelon_to_user_matrix(self): [ 4/3 -1/3] The vector `(1,1,1)` has coordinates `v=(1,1)` with - respect to the echelonized basis for self. Multiplying `vA` + respect to the echelonized basis for ``self``. Multiplying `vA` we find the coordinates of this vector with respect to the user basis. @@ -7205,10 +7181,10 @@ def echelon_to_user_matrix(self): def _user_to_rref_matrix(self): """ - Returns a transformation matrix from the user specified basis to row + Return a transformation matrix from the user specified basis to row reduced echelon form, for this module over a PID. - Note: For internal use only! See user_to_echelon_matrix. + Note: For internal use only! See ``user_to_echelon_matrix``. EXAMPLES:: @@ -7237,10 +7213,10 @@ def _user_to_rref_matrix(self): def _rref_to_user_matrix(self): """ - Returns a transformation matrix from row reduced echelon form to + Return a transformation matrix from row reduced echelon form to the user specified basis, for this module over a PID. - Note: For internal use only! See user_to_echelon_matrix. + Note: For internal use only! See ``user_to_echelon_matrix``. EXAMPLES:: @@ -7266,7 +7242,7 @@ def _rref_to_user_matrix(self): def _echelon_to_rref_matrix(self): """ - Returns a transformation matrix from the some matrix to the row + Return a transformation matrix from the some matrix to the row reduced echelon form for this module over a PID. Note: For internal use only! and not used! @@ -7301,7 +7277,7 @@ def _echelon_to_rref_matrix(self): def _rref_to_echelon_matrix(self): """ - Returns a transformation matrix from row reduced echelon form to + Return a transformation matrix from row reduced echelon form to some matrix for this module over a PID. Note: For internal use only! @@ -7434,7 +7410,7 @@ def change_ring(self, R): INPUT: - - ``R`` -- a principal ideal domain + - ``R`` -- a principal ideal domain EXAMPLES:: @@ -7495,7 +7471,7 @@ def coordinate_vector(self, v, check=True): - ``v`` -- vector - ``check`` -- boolean (default: ``True``); if ``True``, also verify that - `v` is really in ``self``. + `v` is really in ``self`` OUTPUT: list @@ -7506,7 +7482,7 @@ def coordinate_vector(self, v, check=True): \\sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -7551,19 +7527,19 @@ def echelon_coordinate_vector(self, v, check=True): INPUT: - - ``v`` -- vector + - ``v`` -- vector - - ``check`` -- boolean (default: ``True``); if ``True``, also - verify that `v` is really in ``self``. + - ``check`` -- boolean (default: ``True``); if ``True``, also + verify that `v` is really in ``self`` Returns a list `c` such that if `B` is the echelonized basis - for self, then + for ``self``, then .. MATH:: \\sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -7671,7 +7647,7 @@ def __init__(self, ambient, gens, check=True, already_echelonized=False, def _repr_(self): """ - The printing representation of self. + The printing representation of ``self``. EXAMPLES:: @@ -7707,7 +7683,7 @@ def coordinate_vector(self, v, check=True): - ``v`` -- vector - ``check`` -- boolean (default: ``True``); if ``True``, also verify that - `v` is really in ``self``. + `v` is really in ``self`` OUTPUT: list @@ -7718,7 +7694,7 @@ def coordinate_vector(self, v, check=True): \\sum c_i B_i = v. - If `v` is not in self, raise an :class:`ArithmeticError` exception. + If `v` is not in self, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -7829,7 +7805,7 @@ def __init__(self, ambient, basis, check=True, def _repr_(self): """ - The printing representation of self. + The printing representation of ``self``. EXAMPLES:: @@ -8030,7 +8006,7 @@ def __init__(self, ambient, gens, check=True, already_echelonized=False, categor def _repr_(self) -> str: """ - The default printing representation of self. + The default printing representation of ``self``. EXAMPLES:: @@ -8109,10 +8085,10 @@ def echelon_coordinates(self, v, check=True): INPUT: - - ``v`` -- vector + - ``v`` -- vector - - ``check`` -- boolean (default: ``True``); if ``True``, also - verify that `v` is really in ``self`` + - ``check`` -- boolean (default: ``True``); if ``True``, also + verify that `v` is really in ``self`` OUTPUT: list @@ -8123,7 +8099,7 @@ def echelon_coordinates(self, v, check=True): \\sum c_i B_i = v. - If `v` is not in ``self``, raise an :class:`ArithmeticError` exception. + If `v` is not in ``self``, raise an :exc:`ArithmeticError` exception. EXAMPLES:: @@ -8186,7 +8162,7 @@ def coordinate_vector(self, v, check=True): \\sum c_i B_i = v. - If `v` is not in ``self``, raise an :class:`ArithmeticError` exception. + If `v` is not in ``self``, raise an :exc:`ArithmeticError` exception. EXAMPLES:: diff --git a/src/sage/modules/free_module_element.pyx b/src/sage/modules/free_module_element.pyx index b6f297a3510..5f076475e8c 100644 --- a/src/sage/modules/free_module_element.pyx +++ b/src/sage/modules/free_module_element.pyx @@ -178,14 +178,14 @@ def vector(arg0, arg1=None, arg2=None, sparse=None, immutable=False): INPUT: - - ``object`` -- a list, dictionary, or other + - ``object`` -- list, dictionary, or other iterable containing the entries of the vector, including any object that is palatable to the ``Sequence`` constructor - ``ring`` -- a base ring (or field) for the vector space or free module, which contains all of the elements - - ``degree`` -- an integer specifying the number of + - ``degree`` -- integer specifying the number of entries in the vector or free module element - ``sparse`` -- boolean, whether the result should be a sparse vector @@ -610,20 +610,18 @@ free_module_element = vector def prepare(v, R, degree=None): r""" - Converts an object describing elements of a vector into a list of entries in a common ring. + Convert an object describing elements of a vector into a list of entries in a common ring. INPUT: - - ``v`` -- a dictionary with non-negative integers as keys, + - ``v`` -- dictionary with nonnegative integers as keys, or a list or other object that can be converted by the ``Sequence`` constructor - ``R`` -- a ring containing all the entries, possibly given as ``None`` - - ``degree`` -- a requested size for the list when the input is a dictionary, + - ``degree`` -- a requested size for the list when the input is a dictionary, otherwise ignored - OUTPUT: - - A pair. + OUTPUT: a pair The first item is a list of the values specified in the object ``v``. If the object is a dictionary , entries are placed in the list @@ -641,7 +639,6 @@ def prepare(v, R, degree=None): has no elements and ``R`` is ``None``, the ring returned is the integers. - EXAMPLES:: sage: from sage.modules.free_module_element import prepare @@ -706,7 +703,7 @@ def prepare(v, R, degree=None): def zero_vector(arg0, arg1=None): r""" - Returns a vector or free module element with a specified number of zeros. + Return a vector or free module element with a specified number of zeros. CALL FORMATS: @@ -719,7 +716,7 @@ def zero_vector(arg0, arg1=None): - ``degree`` -- the number of zero entries in the vector or free module element - - ``ring`` -- (default: ``ZZ``); the base ring of the vector + - ``ring`` -- (default: ``ZZ``) the base ring of the vector space or module containing the constructed zero vector OUTPUT: @@ -784,14 +781,14 @@ def zero_vector(arg0, arg1=None): def random_vector(ring, degree=None, *args, **kwds): r""" - Returns a vector (or module element) with random entries. + Return a vector (or module element) with random entries. INPUT: - - ring -- (default: ``ZZ``); the base ring for the entries - - degree -- a non-negative integer for the number of entries in the vector - - sparse -- (default: ``False``); whether to use a sparse implementation - - args, kwds -- additional arguments and keywords are passed + - ``ring`` -- (default: ``ZZ``) the base ring for the entries + - ``degree`` -- nonnegative integer for the number of entries in the vector + - ``sparse`` -- (default: ``False``) whether to use a sparse implementation + - ``*args``, ``**kwds`` -- additional arguments and keywords are passed to the ``random_element()`` method of the ring OUTPUT: @@ -890,13 +887,13 @@ def random_vector(ring, degree=None, *args, **kwds): sage: from sage.misc.randstate import current_randstate sage: seed = current_randstate().seed() sage: set_random_seed(seed) - sage: v1 = random_vector(ZZ, 20, distribution="1/n") + sage: v1 = random_vector(ZZ, 20, distribution='1/n') sage: v2 = random_vector(ZZ, 15, x=-1000, y=1000) sage: v3 = random_vector(QQ, 10) sage: v4 = random_vector(FiniteField(17), 10) sage: v5 = random_vector(RR, 10) sage: set_random_seed(seed) - sage: w1 = vector(ZZ.random_element(distribution="1/n") for _ in range(20)) + sage: w1 = vector(ZZ.random_element(distribution='1/n') for _ in range(20)) sage: w2 = vector(ZZ.random_element(x=-1000, y=1000) for _ in range(15)) sage: w3 = vector(QQ.random_element() for _ in range(10)) sage: [v1, v2, v3] == [w1, w2, w3] @@ -923,7 +920,7 @@ def random_vector(ring, degree=None, *args, **kwds): sage: random_vector(ZZ, -9) Traceback (most recent call last): ... - ValueError: degree of a random vector must be non-negative, not -9 + ValueError: degree of a random vector must be nonnegative, not -9 """ if isinstance(ring, (Integer, int)): if degree is not None: @@ -935,7 +932,7 @@ def random_vector(ring, degree=None, *args, **kwds): if not isinstance(degree, (Integer, int)): raise TypeError("degree of a random vector must be an integer, not %s" % degree) if degree < 0: - raise ValueError("degree of a random vector must be non-negative, not %s" % degree) + raise ValueError("degree of a random vector must be nonnegative, not %s" % degree) if ring not in Rings(): raise TypeError("elements of a vector, or module element, must come from a ring, not %s" % ring) if not hasattr(ring, "random_element"): @@ -970,10 +967,10 @@ cdef class FreeModuleElement(Vector): # abstract base class INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally - represented by a dictionary ``d``, then make a copy of ``d``; - if ``False``, then this can cause undesired behavior by - mutating ``d`` + - ``copy`` -- boolean (default: ``True``); if ``self`` is internally + represented by a dictionary ``d``, then make a copy of ``d``. + If ``False``, then this can cause undesired behavior by + mutating ``d``. EXAMPLES:: @@ -1032,9 +1029,7 @@ cdef class FreeModuleElement(Vector): # abstract base class """ Convert ``self`` to a PARI vector. - OUTPUT: - - A PARI ``gen`` of type ``t_VEC``. + OUTPUT: a PARI ``gen`` of type ``t_VEC`` EXAMPLES:: @@ -1058,9 +1053,7 @@ cdef class FreeModuleElement(Vector): # abstract base class Give a string which, when evaluated in GP, gives a PARI representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1071,7 +1064,7 @@ cdef class FreeModuleElement(Vector): # abstract base class Create the multiplication table of `GF(4)` using GP:: sage: # needs sage.libs.pari - sage: k. = GF(4, impl="pari_ffelt") + sage: k. = GF(4, impl='pari_ffelt') sage: v = gp(vector(list(k))) sage: v [0, 1, a, a + 1] @@ -1085,7 +1078,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def _magma_init_(self, magma): r""" - Convert self to Magma. + Convert ``self`` to Magma. EXAMPLES:: @@ -1131,7 +1124,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def numpy(self, dtype=object): """ - Convert self to a numpy array. + Convert ``self`` to a numpy array. INPUT: @@ -1224,7 +1217,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def _vector_(self, R=None): r""" - Return self as a vector. + Return ``self`` as a vector. EXAMPLES:: @@ -1655,7 +1648,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def additive_order(self): """ - Return the additive order of self. + Return the additive order of ``self``. EXAMPLES:: @@ -1732,8 +1725,8 @@ cdef class FreeModuleElement(Vector): # abstract base class INPUT: - - ``p`` -- default: 2 -- ``p`` can be a real number greater than 1, - infinity (``oo`` or ``Infinity``), or a symbolic expression. + - ``p`` -- (default: 2) ``p`` can be a real number greater than 1, + infinity (``oo`` or ``Infinity``), or a symbolic expression: - `p=1`: the taxicab (Manhattan) norm - `p=2`: the usual Euclidean norm (the default) @@ -1874,7 +1867,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def __getitem__(self, i): """ - Return `i`-th entry or slice of self. + Return `i`-th entry or slice of ``self``. EXAMPLES:: @@ -1906,7 +1899,7 @@ cdef class FreeModuleElement(Vector): # abstract base class cdef get_unsafe(self, Py_ssize_t i): """ - Cython function to get the `i`'th entry of this vector. + Cython function to get the `i`-th entry of this vector. Used as building block for a generic ``__getitem__``. """ @@ -1926,7 +1919,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def __setitem__(self, i, value): """ - Set the `i`-th entry or slice of self to ``value``. + Set the `i`-th entry or slice of ``self`` to ``value``. EXAMPLES:: @@ -1967,7 +1960,7 @@ cdef class FreeModuleElement(Vector): # abstract base class cdef int set_unsafe(self, Py_ssize_t i, value) except -1: """ - Cython function to set the `i`'th entry of this vector to + Cython function to set the `i`-th entry of this vector to ``value``. Used as building block for a generic ``__setitem__``. @@ -2038,12 +2031,12 @@ cdef class FreeModuleElement(Vector): # abstract base class def list(self, copy=True): """ - Return list of elements of self. + Return list of elements of ``self``. INPUT: - - copy -- bool, whether returned list is a copy that is - safe to change, is ignored. + - ``copy`` -- boolean (default: ``True``); whether returned list is a + copy that is safe to change (ignored) EXAMPLES:: @@ -2073,8 +2066,7 @@ cdef class FreeModuleElement(Vector): # abstract base class INPUT: - - positions -- iterable of ints - + - ``positions`` -- iterable of integers EXAMPLES:: @@ -2091,7 +2083,7 @@ cdef class FreeModuleElement(Vector): # abstract base class OUTPUT: - Return a lift of self to the covering ring of the base ring `R`, + Return a lift of ``self`` to the covering ring of the base ring `R`, which is by definition the ring returned by calling :meth:`~sage.rings.quotient_ring.QuotientRing_nc.cover_ring` on `R`, or just `R` itself if the @@ -2151,7 +2143,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def __pos__(self): """ - Always returns self, since +self == self. + Always returns ``self``, since ``+self == self``. EXAMPLES:: @@ -2165,7 +2157,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def __pow__(self, n, dummy): """ - Raises a NotImplementedError, since powering doesn't make + Raises a :exc:`NotImplementedError`, since powering doesn't make sense for vectors. EXAMPLES:: @@ -2258,7 +2250,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def denominator(self): """ Return the least common multiple of the denominators of the - entries of self. + entries of ``self``. EXAMPLES:: @@ -2304,14 +2296,12 @@ cdef class FreeModuleElement(Vector): # abstract base class INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally - represented by a dictionary ``d``, then make a copy of ``d``; - if ``False``, then this can cause undesired behavior by - mutating ``d`` - - OUTPUT: + - ``copy`` -- boolean (default: ``True``); if ``self`` is internally + represented by a dictionary ``d``, then make a copy of ``d``. + If ``False``, then this can cause undesired behavior by + mutating ``d``. - - Python dictionary + OUTPUT: Python dictionary EXAMPLES:: @@ -2361,7 +2351,7 @@ cdef class FreeModuleElement(Vector): # abstract base class more than 3 dimensions. - ``start`` -- (default: origin in correct dimension) may be a tuple, - list, or vector. + list, or vector EXAMPLES: @@ -2498,22 +2488,21 @@ cdef class FreeModuleElement(Vector): # abstract base class r""" INPUT: - - ``xmin`` -- (default: 0) start x position to start - plotting - - - ``xmax`` -- (default: 1) stop x position to stop - plotting + - ``xmin`` -- (default: 0) start x position to start + plotting - - ``eps`` -- (default: determined by xmax) we view this - vector as defining a function at the points xmin, xmin + eps, xmin - + 2\*eps, ..., + - ``xmax`` -- (default: 1) stop x position to stop + plotting - - ``res`` -- (default: all points) total number of - points to include in the graph + - ``eps`` -- (default: determined by xmax) we view this + vector as defining a function at the points xmin, xmin + eps, xmin + + 2\*eps, ..., - - ``connect`` -- (default: ``True``) if True draws a line; - otherwise draw a list of points. + - ``res`` -- (default: all points) total number of + points to include in the graph + - ``connect`` -- boolean (default: ``True``); if ``True`` draws a line, + otherwise draw a list of points EXAMPLES:: @@ -2702,13 +2691,13 @@ cdef class FreeModuleElement(Vector): # abstract base class def cross_product(self, right): """ - Return the cross product of self and right, which is only defined + Return the cross product of ``self`` and ``right``, which is only defined for vectors of length 3 or 7. INPUT: - - ``right`` -- A vector of the same size as ``self``, either - degree three or degree seven. + - ``right`` -- a vector of the same size as ``self``, either + degree three or degree seven OUTPUT: @@ -2823,9 +2812,7 @@ cdef class FreeModuleElement(Vector): # abstract base class and also `w \cdot \hat{v} = w \times v` for all vectors `w`. The basis vectors are assumed to be orthonormal. - OUTPUT: - - The cross product matrix of this vector. + OUTPUT: the cross product matrix of this vector EXAMPLES:: @@ -2897,16 +2884,14 @@ cdef class FreeModuleElement(Vector): # abstract base class def pairwise_product(self, right): """ - Return the pairwise product of self and right, which is a vector of + Return the pairwise product of ``self`` and ``right``, which is a vector of the products of the corresponding entries. INPUT: - - - ``right`` -- vector of the same degree as self. It - need not be in the same vector space as self, as long as the - coefficients can be multiplied. - + - ``right`` -- vector of the same degree as ``self``. It + need not be in the same vector space as ``self``, as long as the + coefficients can be multiplied. EXAMPLES:: @@ -3081,7 +3066,6 @@ cdef class FreeModuleElement(Vector): # abstract base class of vector fields on Euclidean spaces (and more generally pseudo-Riemannian manifolds), in particular for computing the divergence in curvilinear coordinates. - """ if variables is None: variables = self._variables() @@ -3135,7 +3119,6 @@ cdef class FreeModuleElement(Vector): # abstract base class of vector fields on Euclidean spaces (and more generally pseudo-Riemannian manifolds), in particular for computing the curl in curvilinear coordinates. - """ if len(self) == 3: if variables is None: @@ -3161,8 +3144,8 @@ cdef class FreeModuleElement(Vector): # abstract base class def element(self): """ - Simply returns self. This is useful, since for many objects, - self.element() returns a vector corresponding to self. + Simply return ``self``. This is useful, since for many objects, + ``self.element()`` returns a vector corresponding to ``self``. EXAMPLES:: @@ -3199,7 +3182,7 @@ cdef class FreeModuleElement(Vector): # abstract base class INPUT: - * "p" - default: 2 - p value for the norm + - ``p`` -- (default: 2) p value for the norm EXAMPLES:: @@ -3221,7 +3204,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def conjugate(self): r""" - Returns a vector where every entry has been replaced by its complex conjugate. + Return a vector where every entry has been replaced by its complex conjugate. OUTPUT: @@ -3310,7 +3293,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def inner_product(self, right): r""" - Returns the inner product of ``self`` and ``right``, + Return the inner product of ``self`` and ``right``, possibly using an inner product matrix from the parent of ``self``. INPUT: @@ -3415,7 +3398,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def outer_product(self, right): r""" - Returns a matrix, the outer product of two vectors ``self`` and ``right``. + Return a matrix, the outer product of two vectors ``self`` and ``right``. INPUT: @@ -3533,7 +3516,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def hermitian_inner_product(self, right): r""" - Returns the dot product, but with the entries of the first vector + Return the dot product, but with the entries of the first vector conjugated beforehand. INPUT: @@ -3840,7 +3823,7 @@ cdef class FreeModuleElement(Vector): # abstract base class OUTPUT: - If self is the free module element (1,2,3,4), + If ``self`` is the free module element (1,2,3,4), then a string with the following latex is returned: "\left(1,\,2,\,3,\,4\right)" (without the quotes). The vector is enclosed in parentheses by default, @@ -3871,8 +3854,8 @@ cdef class FreeModuleElement(Vector): # abstract base class def dense_vector(self): """ - Return dense version of self. If self is dense, just return - self; otherwise, create and return correspond dense vector. + Return dense version of ``self``. If ``self`` is dense, just return + ``self``; otherwise, create and return correspond dense vector. EXAMPLES:: @@ -3890,7 +3873,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def sparse_vector(self): """ - Return sparse version of self. If self is sparse, just return + Return sparse version of ``self``. If ``self`` is sparse, just return self; otherwise, create and return correspond sparse vector. EXAMPLES:: @@ -3914,16 +3897,13 @@ cdef class FreeModuleElement(Vector): # abstract base class automatically determine the base ring of the resulting element. INPUT: - sparse -- True or False will control whether the result - is sparse. By default, the result is sparse iff self - is sparse. - - - ``phi`` -- arbitrary Python function or callable - object + - ``sparse`` -- boolean; will control whether the result is sparse. + By default, the result is sparse iff self is sparse. - - ``R`` -- (optional) ring + - ``phi`` -- arbitrary Python function or callable object + - ``R`` -- (optional) ring OUTPUT: a free module element over R @@ -3953,7 +3933,7 @@ cdef class FreeModuleElement(Vector): # abstract base class sage: n.parent() # needs sage.rings.finite_rings Vector space of dimension 9 over Finite Field in a of size 3^2 - If your map sends 0 to a non-zero value, then your resulting + If your map sends 0 to a nonzero value, then your resulting vector is not mathematically sparse:: sage: v = vector([0] * 6 + [1], sparse=True); v @@ -4033,7 +4013,7 @@ cdef class FreeModuleElement(Vector): # abstract base class # OK, we have some zero entries. zero_res = phi(self.base_ring()(0)) if not zero_res.is_zero(): - # And phi maps 0 to a non-zero value. + # And phi maps 0 to a nonzero value. v = [zero_res] * self._degree for i,z in self.dict(copy=False).items(): v[i] = phi(z) @@ -4134,7 +4114,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def integral(self, *args, **kwds): """ - Returns a symbolic integral of the vector, component-wise. + Return a symbolic integral of the vector, component-wise. :meth:`integrate` is an alias of the function. @@ -4149,7 +4129,6 @@ cdef class FreeModuleElement(Vector): # abstract base class (1/2*t^2, 1/3*t^3, -cos(t)) sage: r.integrate(t, 0, 1) (1/2, 1/3, -cos(1) + 1) - """ from sage.misc.functional import integral return self.apply_map(lambda x: integral(x,*args, **kwds)) @@ -4158,7 +4137,7 @@ cdef class FreeModuleElement(Vector): # abstract base class def nintegral(self, *args, **kwds): """ - Returns a numeric integral of the vector, component-wise, and + Return a numeric integral of the vector, component-wise, and the result of the nintegral command on each component of the input. @@ -4185,7 +4164,6 @@ cdef class FreeModuleElement(Vector): # abstract base class ((0.5, 0.0, 1.0), {0: (0.5, 5.55111512312578...e-15, 21, 0), 2: (1.0, 1.11022302462515...e-14, 21, 0)}) - """ # If Cython supported lambda functions, we would just do # return self.apply_map(lambda x: x.nintegral(*args, **kwds) for x in self) @@ -4373,8 +4351,7 @@ cdef class FreeModuleElement_generic_dense(FreeModuleElement): INPUT: - - ``v`` -- a list which is used as the new entries (without - copying) + - ``v`` -- list which is used as the new entries (without copying) """ cdef type t = type(self) cdef FreeModuleElement_generic_dense x = t.__new__(t) @@ -4659,11 +4636,11 @@ cdef class FreeModuleElement_generic_dense(FreeModuleElement): def list(self, copy=True): """ - Return list of elements of self. + Return list of elements of ``self``. INPUT: - - copy -- bool, return list of underlying entries + - ``copy`` -- boolean; return list of underlying entries EXAMPLES:: @@ -4824,7 +4801,7 @@ cdef class FreeModuleElement_generic_sparse(FreeModuleElement): INPUT: - - ``v`` -- a dict which is used as the new entries (without + - ``v`` -- dictionary which is used as the new entries (without copying) """ cdef type t = type(self) @@ -5309,7 +5286,7 @@ cdef class FreeModuleElement_generic_sparse(FreeModuleElement): def denominator(self): """ Return the least common multiple of the denominators of the - entries of self. + entries of ``self``. EXAMPLES:: @@ -5338,14 +5315,12 @@ cdef class FreeModuleElement_generic_sparse(FreeModuleElement): INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally - represented by a dictionary ``d``, then make a copy of ``d``; - if ``False``, then this can cause undesired behavior by - mutating ``d`` + - ``copy`` -- boolean (default: ``True``); if ``self`` is internally + represented by a dictionary ``d``, then make a copy of ``d``. + If ``False``, then this can cause undesired behavior by + mutating ``d``. - OUTPUT: - - - Python dictionary + OUTPUT: Python dictionary EXAMPLES:: @@ -5391,7 +5366,7 @@ cdef class FreeModuleElement_generic_sparse(FreeModuleElement): def nonzero_positions(self): """ - Returns the list of numbers ``i`` such that ``self[i] != 0``. + Return the list of numbers ``i`` such that ``self[i] != 0``. EXAMPLES:: @@ -5406,7 +5381,7 @@ cdef class FreeModuleElement_generic_sparse(FreeModuleElement): cpdef int hamming_weight(self) noexcept: """ - Returns the number of positions ``i`` such that ``self[i] != 0``. + Return the number of positions ``i`` such that ``self[i] != 0``. EXAMPLES:: diff --git a/src/sage/modules/free_module_homspace.py b/src/sage/modules/free_module_homspace.py index 8fb97a48e5a..fc87d7f83f6 100644 --- a/src/sage/modules/free_module_homspace.py +++ b/src/sage/modules/free_module_homspace.py @@ -134,11 +134,11 @@ def __call__(self, A, **kwds): r""" INPUT: - - A -- either a matrix or a list/tuple of images of generators, - or a function returning elements of the codomain for elements of the domain. - - check -- bool (default: ``True``) - - the keyword ``side`` can be assigned the values ``"left"`` or - ``"right"``. It corresponds to the side of vectors relative to the matrix. + - ``A`` -- either a matrix or a list/tuple of images of generators, + or a function returning elements of the codomain for elements of the domain + - ``check`` -- boolean (default: ``True``) + - the keyword ``side`` can be assigned the values ``'left'`` or + ``'right'``. It corresponds to the side of vectors relative to the matrix. If A is a matrix, then it is the matrix of this linear transformation, with respect to the basis for the domain and @@ -227,11 +227,12 @@ def __call__(self, A, **kwds): return free_module_morphism.FreeModuleMorphism(self, A, side) @cached_method - def zero(self, side="left"): + def zero(self, side='left'): """ INPUT: - - side -- side of the vectors acted on by the matrix (default: ``left``) + - ``side`` -- side of the vectors acted on by the matrix + (default: ``'left'``) EXAMPLES:: @@ -272,18 +273,17 @@ def zero(self, side="left"): return self(lambda x: self.codomain().zero(), side=side) @cached_method - def _matrix_space(self, side="left"): + def _matrix_space(self, side='left'): """ INPUT: - - side -- side of the vectors acted on by the matrix (default: ``left``) + - ``side`` -- side of the vectors acted on by the matrix + (default: ``'left'``) Return underlying matrix space that contains the matrices that define the homomorphisms in this free module homspace. - OUTPUT: - - - matrix space + OUTPUT: matrix space EXAMPLES:: @@ -300,17 +300,16 @@ def _matrix_space(self, side="left"): return MatrixSpace(R, self.codomain().rank(), self.domain().rank()) @cached_method - def basis(self, side="left"): + def basis(self, side='left'): """ Return a basis for this space of free module homomorphisms. INPUT: - - side -- side of the vectors acted on by the matrix (default: ``left``) - - OUTPUT: + - ``side`` -- side of the vectors acted on by the matrix + (default: ``'left'``) - - tuple + OUTPUT: tuple EXAMPLES:: @@ -340,13 +339,14 @@ def basis(self, side="left"): B = M.basis() return tuple([self(x, side=side) for x in B]) - def identity(self, side="left"): + def identity(self, side='left'): r""" Return identity morphism in an endomorphism ring. INPUT: - - side -- side of the vectors acted on by the matrix (default: ``left``) + - ``side`` -- side of the vectors acted on by the matrix + (default: ``'left'``) EXAMPLES:: diff --git a/src/sage/modules/free_module_integer.py b/src/sage/modules/free_module_integer.py index 0fe86437b7c..78884501a91 100644 --- a/src/sage/modules/free_module_integer.py +++ b/src/sage/modules/free_module_integer.py @@ -57,8 +57,8 @@ def IntegerLattice(basis, lll_reduce=True): - an element of an absolute order - - ``lll_reduce`` -- (default: ``True``) run LLL reduction on the basis - on construction. + - ``lll_reduce`` -- boolean (default: ``True``); run LLL reduction on the basis + on construction EXAMPLES: @@ -171,7 +171,6 @@ def IntegerLattice(basis, lll_reduce=True): [ 0 0 0 0 0 1048576 0 0] [ 0 0 0 0 0 0 1048576 0] [ 0 0 0 0 0 0 0 1048576] - """ if isinstance(basis, OrderElement_absolute): @@ -218,7 +217,6 @@ class FreeModule_submodule_with_basis_integer(FreeModule_submodule_with_basis_pi [ 2 -1 1 2 -3 2 2 1 0 1] sage: L.shortest_vector() (-1, 1, 2, -2, 0, 1, 0, -1, 2, 1) - """ def __init__(self, ambient, basis, check=True, echelonize=False, echelonized_basis=None, already_echelonized=False, @@ -233,21 +231,21 @@ def __init__(self, ambient, basis, check=True, echelonize=False, - ``basis`` -- either a list of vectors or a matrix over the integers - - ``check`` -- (default: ``True``) if ``False``, correctness of - the input will not be checked and type conversion may be omitted, + - ``check`` -- boolean (default: ``True``); if ``False``, correctness + of the input will not be checked and type conversion may be omitted, use with care - - ``echelonize`` -- (default:``False``) if ``True``, ``basis`` will be + - ``echelonize`` -- (default: ``False``) if ``True``, ``basis`` will be echelonized and the result will be used as the default basis of the constructed submodule - - `` echelonized_basis`` -- (default: ``None``) if not ``None``, must + - ``echelonized_basis`` -- (default: ``None``) if not ``None``, must be the echelonized basis spanning the same submodule as ``basis`` - - ``already_echelonized`` -- (default: ``False``) if ``True``, + - ``already_echelonized`` -- boolean (default: ``False``); if ``True``, ``basis`` must be already given in the echelonized form - - ``lll_reduce`` -- (default: ``True``) run LLL reduction on the basis + - ``lll_reduce`` -- boolean (default: ``True``); run LLL reduction on the basis on construction EXAMPLES:: @@ -281,7 +279,6 @@ def __init__(self, ambient, basis, check=True, echelonize=False, [ 0 -1 1 -4 1 -1 1 0] [ 2 0 -3 -1 0 -3 0 0] [-1 0 -1 0 -3 -3 0 0] - """ basis = matrix(ZZ, basis) self._basis_is_LLL_reduced = False @@ -357,9 +354,7 @@ def LLL(self, *args, **kwds): - ``**kwds`` -- passed through to :meth:`sage.matrix.matrix_integer_dense.Matrix_integer_dense.LLL` - OUTPUT: - - An integer matrix which is an LLL-reduced basis for this lattice. + OUTPUT: integer matrix which is an LLL-reduced basis for this lattice EXAMPLES:: @@ -403,9 +398,7 @@ def BKZ(self, *args, **kwds): - ``*kwds`` -- passed through to :meth:`sage.matrix.matrix_integer_dense.Matrix_integer_dense.BKZ` - OUTPUT: - - An integer matrix which is a BKZ-reduced basis for this lattice. + OUTPUT: integer matrix which is a BKZ-reduced basis for this lattice EXAMPLES:: @@ -466,9 +459,7 @@ def HKZ(self, *args, **kwds): - ``*kwds`` -- passed through to :meth:`BKZ` - OUTPUT: - - An integer matrix which is a HKZ-reduced basis for this lattice. + OUTPUT: integer matrix which is a HKZ-reduced basis for this lattice EXAMPLES:: @@ -487,9 +478,7 @@ def volume(self): r""" Return `vol(L)` which is `\sqrt{\det(B \cdot B^T)}` for any basis `B`. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -508,9 +497,7 @@ def discriminant(self): Return `|\det(G)|`, i.e. the absolute value of the determinant of the Gram matrix `B \cdot B^T` for any basis `B`. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -525,9 +512,7 @@ def is_unimodular(self): """ Return ``True`` if this lattice is unimodular. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -541,25 +526,23 @@ def is_unimodular(self): return self.volume() == 1 @cached_method - def shortest_vector(self, update_reduced_basis=True, algorithm="fplll", *args, **kwds): + def shortest_vector(self, update_reduced_basis=True, algorithm='fplll', *args, **kwds): r""" Return a shortest vector. INPUT: - - ``update_reduced_basis`` -- (default: ``True``) set this flag if - the found vector should be used to improve the basis + - ``update_reduced_basis`` -- boolean (default: ``True``); set this + flag if the found vector should be used to improve the basis - - ``algorithm`` -- (default: ``"fplll"``) either ``"fplll"`` or - ``"pari"`` + - ``algorithm`` -- (default: ``'fplll'``) either ``'fplll'`` or + ``'pari'`` - ``*args`` -- passed through to underlying implementation - ``**kwds`` -- passed through to underlying implementation - OUTPUT: - - A shortest non-zero vector for this lattice. + OUTPUT: a shortest nonzero vector for this lattice EXAMPLES:: @@ -576,11 +559,11 @@ def shortest_vector(self, update_reduced_basis=True, algorithm="fplll", *args, * sage: min(v.norm().n() for v in L.reduced_basis) # needs sage.symbolic 6.03890756700000e10 - sage: L.shortest_vector(algorithm="pari").norm().n() # needs sage.symbolic + sage: L.shortest_vector(algorithm='pari').norm().n() # needs sage.symbolic 3.74165738677394 sage: L = IntegerLattice(A, lll_reduce=True) - sage: L.shortest_vector(algorithm="pari").norm().n() # needs sage.symbolic + sage: L.shortest_vector(algorithm='pari').norm().n() # needs sage.symbolic 3.74165738677394 """ if algorithm == "pari": @@ -614,9 +597,7 @@ def update_reduced_basis(self, w): - ``w`` -- a vector - OUTPUT: - - Nothing is returned but the internal state is modified. + OUTPUT: nothing is returned but the internal state is modified EXAMPLES:: @@ -644,9 +625,7 @@ def voronoi_cell(self, radius=None): - ``radius`` -- (default: automatic determination) radius of ball containing considered vertices - OUTPUT: - - The Voronoi cell as a Polyhedron instance. + OUTPUT: the Voronoi cell as a Polyhedron instance The result is cached so that subsequent calls to this function return instantly. @@ -705,9 +684,7 @@ def voronoi_relevant_vectors(self): """ Compute the embedded vectors inducing the Voronoi cell. - OUTPUT: - - The list of Voronoi relevant vectors. + OUTPUT: the list of Voronoi relevant vectors EXAMPLES:: @@ -747,9 +724,7 @@ def closest_vector(self, t): - ``t`` -- the target vector to compute the closest vector to - OUTPUT: - - The vector in the lattice closest to ``t``. + OUTPUT: the vector in the lattice closest to ``t`` EXAMPLES:: @@ -834,9 +809,7 @@ def approximate_closest_vector(self, t, delta=None, *args, **kwargs): - ``**kwds`` -- passed through to :meth:`LLL` - OUTPUT: - - The vector `w` described above. + OUTPUT: the vector `w` described above EXAMPLES:: diff --git a/src/sage/modules/free_module_morphism.py b/src/sage/modules/free_module_morphism.py index 7cbfe0f7281..efdbc607c09 100644 --- a/src/sage/modules/free_module_morphism.py +++ b/src/sage/modules/free_module_morphism.py @@ -73,15 +73,15 @@ def is_FreeModuleMorphism(x): class FreeModuleMorphism(matrix_morphism.MatrixMorphism): - def __init__(self, parent, A, side="left"): + def __init__(self, parent, A, side='left'): """ INPUT: - - ``parent`` -- a homspace in a (sub) category of free modules + - ``parent`` -- a homspace in a (sub) category of free modules - - ``A`` -- matrix + - ``A`` -- matrix - - side -- side of the vectors acted on by the matrix (default: ``"left"``) + - ``side`` -- side of the vectors acted on by the matrix (default: ``'left'``) EXAMPLES:: @@ -181,7 +181,7 @@ def _repr_(self): [1 0 0] Domain: Ambient free module of rank 3 over the principal ideal domain Integer Ring Codomain: Ambient free module of rank 3 over the principal ideal domain Integer Ring - sage: h2 = V.hom([V.1, V.2, V.0], side="right"); h2 + sage: h2 = V.hom([V.1, V.2, V.0], side='right'); h2 Free module morphism defined as left-multiplication by the matrix [0 0 1] [1 0 0] @@ -248,7 +248,7 @@ def inverse_image(self, V): """ Given a submodule V of the codomain of self, return the inverse image of V under self, i.e., the biggest submodule of - the domain of self that maps into V. + the domain of ``self`` that maps into V. EXAMPLES: @@ -320,7 +320,7 @@ def inverse_image(self, V): sage: V = ZZ^2 sage: m = matrix(2, [1, 1, 0, 1]) - sage: h = V.hom(m, side="right") + sage: h = V.hom(m, side='right') sage: h Free module morphism defined as left-multiplication by the matrix [1 1] @@ -453,7 +453,7 @@ def lift(self, x): :: sage: V = QQ^2; m = matrix(2, [1, 1, 0, 1]) - sage: V.hom(m, side="right").lift(V.0 + V.1) + sage: V.hom(m, side='right').lift(V.0 + V.1) (0, 1) sage: V.hom(m).lift(V.0 + V.1) (1, 0) @@ -488,12 +488,12 @@ def lift(self, x): def eigenvalues(self, extend=True): r""" - Returns a list with the eigenvalues of the endomorphism of vector spaces. + Return a list with the eigenvalues of the endomorphism of vector spaces. INPUT: - - ``extend`` -- boolean (default: ``True``) decides if base field - extensions should be considered or not. + - ``extend`` -- boolean (default: ``True``); decides if base field + extensions should be considered or not EXAMPLES: @@ -523,12 +523,12 @@ def eigenvalues(self, extend=True): def eigenvectors(self, extend=True): """ - Computes the subspace of eigenvectors of a given eigenvalue. + Compute the subspace of eigenvectors of a given eigenvalue. INPUT: - - ``extend`` -- boolean (default: ``True``) decides if base field - extensions should be considered or not. + - ``extend`` -- boolean (default: ``True``); decides if base field + extensions should be considered or not OUTPUT: @@ -559,7 +559,7 @@ def eigenvectors(self, extend=True): sage: V = QQ^2 sage: m = matrix(2, [1, 1, 0, 1]) - sage: V.hom(m, side="right").eigenvectors() # needs sage.rings.number_field + sage: V.hom(m, side='right').eigenvectors() # needs sage.rings.number_field [(1, [ (1, 0) ], 2)] sage: V.hom(m).eigenvectors() # needs sage.rings.number_field [(1, [ (0, 1) ], 2)] @@ -587,12 +587,10 @@ def eigenspaces(self, extend=True): INPUT: - - ``extend`` -- (default: ``True``) determines if field + - ``extend`` -- boolean (default: ``True``); determines if field extensions should be considered - OUTPUT: - - - a list of pairs ``(eigenvalue, eigenspace)`` + OUTPUT: a list of pairs ``(eigenvalue, eigenspace)`` EXAMPLES:: @@ -634,7 +632,7 @@ def eigenspaces(self, extend=True): :: sage: V = QQ^2; m = matrix(2, [1, 1, 0, 1]) - sage: V.hom(m, side="right").eigenspaces() # needs sage.rings.number_field + sage: V.hom(m, side='right').eigenspaces() # needs sage.rings.number_field [(1, Vector space of degree 2 and dimension 1 over Rational Field Basis matrix: [1 0])] @@ -712,12 +710,12 @@ def _richcmp_(self, other, op): class BaseIsomorphism1D_to_FM(BaseIsomorphism1D): """ - An isomorphism from a ring to its 1-dimensional free module + An isomorphism from a ring to its 1-dimensional free module. INPUT: - ``parent`` -- the homset - - ``basis`` -- (default 1) an invertible element of the ring + - ``basis`` -- (default: 1) an invertible element of the ring EXAMPLES:: @@ -769,12 +767,12 @@ def _call_(self, x): class BaseIsomorphism1D_from_FM(BaseIsomorphism1D): """ - An isomorphism to a ring from its 1-dimensional free module + An isomorphism to a ring from its 1-dimensional free module. INPUT: - ``parent`` -- the homset - - ``basis`` -- (default 1) an invertible element of the ring + - ``basis`` -- (default: 1) an invertible element of the ring EXAMPLES:: diff --git a/src/sage/modules/free_quadratic_module.py b/src/sage/modules/free_quadratic_module.py index da54426e9c9..a209ae79ee4 100644 --- a/src/sage/modules/free_quadratic_module.py +++ b/src/sage/modules/free_quadratic_module.py @@ -91,13 +91,13 @@ def FreeQuadraticModule(base_ring, rank, inner_product_matrix, - ``base_ring`` -- a commutative ring - - ``rank`` -- a nonnegative integer + - ``rank`` -- nonnegative integer - ``inner_product_matrix`` -- the inner product matrix - - ``sparse`` -- bool; (default ``False``) + - ``sparse`` -- boolean (default: ``False``) - - ``inner_product_ring`` -- the inner product codomain ring; (default ``None``) + - ``inner_product_ring`` -- the inner product codomain ring (default: ``None``) OUTPUT: @@ -209,7 +209,7 @@ def QuadraticSpace(K, dimension, inner_product_matrix, sparse=False): (0, 0, 1) ] - The base must be a field or a :class:`TypeError` is raised:: + The base must be a field or a :exc:`TypeError` is raised:: sage: QuadraticSpace(ZZ, 5, identity_matrix(ZZ,2)) Traceback (most recent call last): @@ -318,7 +318,7 @@ def __init__(self, base_ring, rank, degree, inner_product_matrix, sparse=False): - ``base_ring`` -- a commutative ring - - ``rank`` -- a non-negative integer + - ``rank`` -- nonnegative integer EXAMPLES:: @@ -739,10 +739,10 @@ def span(self, gens, check=True, already_echelonized=False): - ``gens`` -- list of vectors - - ``check`` -- bool (default: ``True``): whether or not to coerce + - ``check`` -- boolean (default: ``True``); whether or not to coerce entries of gens into base field - - ``already_echelonized`` -- bool (default: ``False``): set this if + - ``already_echelonized`` -- boolean (default: ``False``); set this if you know the gens are already in echelon form EXAMPLES:: @@ -779,10 +779,10 @@ def span_of_basis(self, basis, check=True, already_echelonized=False): - ``basis`` -- list of vectors - - ``check`` -- bool (default: ``True``): whether or not to coerce + - ``check`` -- boolean (default: ``True``); whether or not to coerce entries of gens into base field - - ``already_echelonized`` -- bool (default: ``False``): set this if + - ``already_echelonized`` -- boolean (default: ``False``); set this if you know the gens are already in echelon form EXAMPLES:: @@ -799,7 +799,7 @@ def span_of_basis(self, basis, check=True, already_echelonized=False): [3 3 0] The basis vectors must be linearly independent or a - :class:`ValueError` exception is raised:: + :exc:`ValueError` exception is raised:: sage: W.span_of_basis([[2,2,2], [3,3,3]]) Traceback (most recent call last): @@ -831,7 +831,7 @@ def __init__(self, base_ring, rank, inner_product_matrix, sparse=False): - ``base_ring`` -- a commutative ring - - ``rank`` -- a non-negative integer + - ``rank`` -- nonnegative integer EXAMPLES:: @@ -1047,11 +1047,11 @@ def __init__(self, base_ring, rank, inner_product_matrix, sparse=False): - ``base_ring`` -- a principal ideal domain - - ``rank`` -- a non-negative integer + - ``rank`` -- nonnegative integer - - ``sparse`` -- bool (default: ``False``) + - ``sparse`` -- boolean (default: ``False``) - - ``inner_product_matrix`` -- bool (default: ``None``) + - ``inner_product_matrix`` -- boolean (default: ``None``) EXAMPLES:: @@ -1131,9 +1131,9 @@ def __init__(self, base_field, dimension, inner_product_matrix, sparse=False): - ``base_field`` -- a field - - ``dimension`` -- a non-negative integer + - ``dimension`` -- nonnegative integer - - ``sparse`` -- bool (default: ``False``) + - ``sparse`` -- boolean (default: ``False``) EXAMPLES:: @@ -1349,7 +1349,7 @@ def change_ring(self, R): element of ``self`` into a vector over the fraction field of `R`, then taking the resulting `R`-module. - This raises a :class:`TypeError` if coercion is not possible. + This raises a :exc:`TypeError` if coercion is not possible. INPUT: diff --git a/src/sage/modules/free_quadratic_module_integer_symmetric.py b/src/sage/modules/free_quadratic_module_integer_symmetric.py index f7343dfc484..ab715bc57d5 100644 --- a/src/sage/modules/free_quadratic_module_integer_symmetric.py +++ b/src/sage/modules/free_quadratic_module_integer_symmetric.py @@ -88,7 +88,7 @@ def IntegralLattice(data, basis=None): :class:`CartanMatrix` (see also :mod:`Cartan types `) -- for a root lattice - * the string ``"U"`` or ``"H"`` -- for hyperbolic lattices + * the string ``'U'`` or ``'H'`` -- for hyperbolic lattices - ``basis`` -- (optional) a matrix whose rows form a basis of the lattice, or a list of module elements forming a basis @@ -140,16 +140,16 @@ def IntegralLattice(data, basis=None): [ 2 -1] [-1 2] - We use ``"U"`` or ``"H"`` for defining a hyperbolic lattice:: + We use ``'U'`` or ``'H'`` for defining a hyperbolic lattice:: - sage: L1 = IntegralLattice("U") + sage: L1 = IntegralLattice('U') sage: L1 Lattice of degree 2 and rank 2 over Integer Ring Standard basis Inner product matrix: [0 1] [1 0] - sage: L1 == IntegralLattice("H") + sage: L1 == IntegralLattice('H') True We can construct root lattices by specifying their type @@ -263,8 +263,8 @@ def IntegralLatticeDirectSum(Lattices, return_embeddings=False): INPUT: - - ``Lattices`` -- a list of lattices ``[L_1,...,L_n]`` - - ``return_embeddings`` -- (default: ``False``) a boolean + - ``Lattices`` -- list of lattices ``[L_1,...,L_n]`` + - ``return_embeddings`` -- boolean (default: ``False``) OUTPUT: @@ -373,12 +373,11 @@ def IntegralLatticeGluing(Lattices, glue, return_embeddings=False): INPUT: - - ``Lattices`` -- a list of lattices `[L_1,...,L_n]` - - ``glue`` -- a list where the elements are lists in the form `[g_1,...,g_n]`; + - ``Lattices`` -- list of lattices `[L_1,...,L_n]` + - ``glue`` -- list where the elements are lists in the form `[g_1,...,g_n]`; here `g_i` is an element of the discriminant group of `L_i`and the overlattice is spanned by the additional ``[sum(g) for g in glue]`` - - ``return_embeddings`` -- (default: ``False``) a boolean - + - ``return_embeddings`` -- boolean (default: ``False``) OUTPUT: @@ -629,7 +628,7 @@ class FreeQuadraticModule_integer_symmetric(FreeQuadraticModule_submodule_with_b INPUT: - ``ambient`` -- an ambient free quadratic module - - ``basis`` -- a list of elements of ambient or a matrix + - ``basis`` -- list of elements of ambient or a matrix - ``inner_product_matrix`` -- a symmetric matrix over the rationals EXAMPLES:: @@ -751,7 +750,7 @@ def is_even(self): @cached_method def dual_lattice(self): r""" - Return the dual lattice as a :class:`FreeQuadraticModule` + Return the dual lattice as a :class:`FreeQuadraticModule`. Let `L` be a lattice. Its dual lattice is @@ -781,7 +780,7 @@ def discriminant_group(self, s=0): INPUT: - - ``s`` -- an integer (default: 0) + - ``s`` -- integer (default: 0) OUTPUT: @@ -974,7 +973,7 @@ def sublattice(self, basis): INPUT: - - ``basis`` -- A list of elements of this lattice. + - ``basis`` -- list of elements of this lattice EXAMPLES:: @@ -1010,7 +1009,7 @@ def overlattice(self, gens): INPUT: - - ``gens`` -- a list of elements or a rational matrix + - ``gens`` -- list of elements or a rational matrix EXAMPLES:: @@ -1032,9 +1031,9 @@ def maximal_overlattice(self, p=None): INPUT: - - ``p`` -- (default:``None``) if given return an overlattice + - ``p`` -- (default: ``None``) if given return an overlattice `M` of this lattice `L` that is maximal at `p` and the - completions `M_q = L_q` are equal for all primes `q \neq p`. + completions `M_q = L_q` are equal for all primes `q \neq p` If `p` is `2` or ``None``, then the lattice must be even. @@ -1055,7 +1054,6 @@ def maximal_overlattice(self, p=None): sage: L = IntegralLattice(matrix.diagonal([2,4,4,8])) sage: L.maximal_overlattice().is_even() True - """ # this code is somewhat slow but it works # it might speed up things to use the algorithms given in @@ -1162,9 +1160,10 @@ def orthogonal_group(self, gens=None, is_finite=None): INPUT: - - ``gens`` -- a list of matrices (default:``None``) - - ``is_finite`` -- bool (default: ``None``) If set to ``True``, - then the group is placed in the category of finite groups. Sage does not check this. + - ``gens`` -- list of matrices (default: ``None``) + - ``is_finite`` -- boolean (default: ``None``); if set to ``True``, + then the group is placed in the category of finite groups. Sage does + not check this. OUTPUT: @@ -1335,8 +1334,8 @@ def tensor_product(self, other, discard_basis=False): INPUT: - ``other`` -- an integral lattice - - ``discard_basis`` -- a boolean (default: ``False``). If ``True``, then the lattice - returned is equipped with the standard basis. + - ``discard_basis`` -- boolean (default: ``False``); if ``True``, then + the lattice returned is equipped with the standard basis EXAMPLES:: @@ -1503,13 +1502,11 @@ def short_vectors(self, n, **kwargs): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - further keyword arguments are passed on to - :meth:`sage.quadratic_forms.short_vector_list_up_to_length`. - - OUTPUT: + :meth:`sage.quadratic_forms.short_vector_list_up_to_length` - - a list `L` where ``L[k]`` is the list of vectors of lengths `k` + OUTPUT: list `L` where ``L[k]`` is the list of vectors of lengths `k` EXAMPLES:: @@ -1536,10 +1533,9 @@ def twist(self, s, discard_basis=False): INPUT: - - ``s`` -- a nonzero integer - - ``discard_basis`` -- a boolean (default: ``False``). - If ``True``, then the lattice returned is equipped - with the standard basis. + - ``s`` -- nonzero integer + - ``discard_basis`` -- boolean (default: ``False``); if ``True``, then + the lattice returned is equipped with the standard basis EXAMPLES:: @@ -1576,7 +1572,7 @@ def twist(self, s, discard_basis=False): except TypeError: raise ValueError("the scaling factor must be an element of the base ring.") if s == 0: - raise ValueError("the scaling factor must be non zero") + raise ValueError("the scaling factor must be nonzero") if discard_basis: return IntegralLattice(s * self.gram_matrix()) else: diff --git a/src/sage/modules/matrix_morphism.py b/src/sage/modules/matrix_morphism.py index fcce12a0788..5736d86932d 100644 --- a/src/sage/modules/matrix_morphism.py +++ b/src/sage/modules/matrix_morphism.py @@ -58,7 +58,7 @@ def is_MatrixMorphism(x): """ - Return True if x is a Matrix morphism of free modules. + Return ``True`` if x is a Matrix morphism of free modules. This function is deprecated. @@ -97,10 +97,9 @@ def __init__(self, parent, side='left'): """ INPUT: - - ``parent`` -- a homspace - - - ``A`` -- matrix + - ``parent`` -- a homspace + - ``A`` -- matrix EXAMPLES:: @@ -244,7 +243,6 @@ def _call_with_args(self, x, args=(), kwds={}): to coefficients in Real Field with 53 bits of precision sage: f((1, 0), coerce=False) (1.00000000000000*I, 0.000000000000000) - """ if self.domain().is_ambient(): x = x.element() @@ -299,7 +297,7 @@ def side(self): sage: m = matrix(2, [1, 1, 0, 1]) sage: V = ZZ^2 - sage: h1 = V.hom(m); h2 = V.hom(m, side="right") + sage: h1 = V.hom(m); h2 = V.hom(m, side='right') sage: h1.side() 'left' sage: h1([1, 0]) @@ -313,7 +311,7 @@ def side(self): def side_switch(self): """ - Return the same morphism, acting on vectors on the opposite side + Return the same morphism, acting on vectors on the opposite side. EXAMPLES:: @@ -342,7 +340,7 @@ def inverse(self): r""" Return the inverse of this matrix morphism, if the inverse exists. - This raises a :class:`ZeroDivisionError` if the inverse does not exist. + This raises a :exc:`ZeroDivisionError` if the inverse does not exist. EXAMPLES: @@ -565,7 +563,7 @@ def __mul__(self, right): Codomain: Vector space of dimension 2 over Rational Field sage: f(a) (1, 1) - sage: V.hom([V.0 - V.1, V.0 + V.1], side="right")*KtoV + sage: V.hom([V.0 - V.1, V.0 + V.1], side='right')*KtoV Composite map: From: Number Field in a with defining polynomial x^2 + 23 To: Vector space of dimension 2 over Rational Field @@ -585,7 +583,7 @@ def __mul__(self, right): sage: V = ZZ^2 sage: m = matrix(2, [1,1,0,1]) sage: hl = V.hom(m) - sage: hr = V.hom(m, side="right") + sage: hr = V.hom(m, side='right') sage: hl * hl Free module morphism defined by the matrix [1 2] @@ -650,7 +648,7 @@ def __mul__(self, right): if right.side() == "right": return H(self.matrix() * right.matrix(), side=self.side()) else: - return H(right.matrix() * self.matrix().transpose(), side="left") + return H(right.matrix() * self.matrix().transpose(), side='left') def __add__(self, right): """ @@ -694,7 +692,7 @@ def __add__(self, right): sage: V = ZZ^2 sage: m = matrix(2, [1,1,0,1]) sage: hl = V.hom(m) - sage: hr = V.hom(m, side="right") + sage: hr = V.hom(m, side='right') sage: hl + hl Free module morphism defined by the matrix [2 2] @@ -727,12 +725,12 @@ def __add__(self, right): if right.side() == "left": return self.parent()(self.matrix() + right.matrix(), side=self.side()) elif right.side() == "right": - return self.parent()(self.matrix() + right.matrix().transpose(), side="left") + return self.parent()(self.matrix() + right.matrix().transpose(), side='left') if self.side() == "right": if right.side() == "right": return self.parent()(self.matrix() + right.matrix(), side=self.side()) elif right.side() == "left": - return self.parent()(self.matrix().transpose() + right.matrix(), side="left") + return self.parent()(self.matrix().transpose() + right.matrix(), side='left') def __neg__(self): """ @@ -765,7 +763,7 @@ def __sub__(self, other): sage: V = ZZ^2 sage: m = matrix(2, [1,1,0,1]) sage: hl = V.hom(m) - sage: hr = V.hom(m, side="right") + sage: hr = V.hom(m, side='right') sage: hl - hr Free module morphism defined by the matrix [ 0 1] @@ -798,17 +796,17 @@ def __sub__(self, other): if other.side() == "left": return self.parent()(self.matrix() - other.matrix(), side=self.side()) elif other.side() == "right": - return self.parent()(self.matrix() - other.matrix().transpose(), side="left") + return self.parent()(self.matrix() - other.matrix().transpose(), side='left') if self.side() == "right": if other.side() == "right": return self.parent()(self.matrix() - other.matrix(), side=self.side()) elif other.side() == "left": - return self.parent()(self.matrix().transpose() - other.matrix(), side="left") + return self.parent()(self.matrix().transpose() - other.matrix(), side='left') def base_ring(self): """ - Return the base ring of self, that is, the ring over which self is - given by a matrix. + Return the base ring of ``self``, that is, the ring over which ``self`` + is given by a matrix. EXAMPLES:: @@ -820,9 +818,9 @@ def base_ring(self): def decomposition(self, *args, **kwds): """ Return decomposition of this endomorphism, i.e., sequence of - subspaces obtained by finding invariant subspaces of self. + subspaces obtained by finding invariant subspaces of ``self``. - See the documentation for self.matrix().decomposition for more + See the documentation for ``self.matrix().decomposition`` for more details. All inputs to this function are passed onto the matrix one. @@ -838,7 +836,7 @@ def decomposition(self, *args, **kwds): Echelon basis matrix: [ 1 -1] ] - sage: phi2 = V.hom(phi.matrix(), side="right") + sage: phi2 = V.hom(phi.matrix(), side='right') sage: phi2.decomposition() # needs sage.libs.pari [ Free module of degree 2 and rank 1 over Integer Ring @@ -893,7 +891,7 @@ def kernel(self): [1 0 0] [0 0 1] sage: f1 = V.hom(m) - sage: f2 = V.hom(m, side="right") + sage: f2 = V.hom(m, side='right') sage: f1.kernel() Vector space of degree 3 and dimension 1 over Rational Field Basis matrix: @@ -938,7 +936,7 @@ def image(self): [1 0 0] [0 0 1] sage: f1 = V.hom(m) - sage: f2 = V.hom(m, side="right") + sage: f2 = V.hom(m, side='right') sage: f1.image() Vector space of degree 3 and dimension 2 over Rational Field Basis matrix: @@ -1030,7 +1028,7 @@ def _matrix_(self): def rank(self): r""" - Returns the rank of the matrix representing this morphism. + Return the rank of the matrix representing this morphism. EXAMPLES:: @@ -1045,7 +1043,7 @@ def rank(self): def nullity(self): r""" - Returns the nullity of the matrix representing this morphism, which is the + Return the nullity of the matrix representing this morphism, which is the dimension of its kernel. EXAMPLES:: @@ -1065,7 +1063,7 @@ def nullity(self): sage: h1.nullity() 1 sage: W = ZZ^1 - sage: h2 = W.hom(m, side="right") + sage: h2 = W.hom(m, side='right') sage: h2.nullity() 0 """ @@ -1207,7 +1205,7 @@ def is_zero(self): sage: phi.is_zero() True - An image list that just barely makes a non-zero morphism. :: + An image list that just barely makes a nonzero morphism. :: sage: V = ZZ^4 sage: W = ZZ^6 @@ -1347,7 +1345,7 @@ def restrict_domain(self, sub): Free module morphism defined by the matrix [0 2]... sage: m = matrix(2, range(1,5)) - sage: f1 = V.hom(m); f2 = V.hom(m, side="right") + sage: f1 = V.hom(m); f2 = V.hom(m, side='right') sage: SV = V.span([V.0]) sage: f1.restrict_domain(SV) Free module morphism defined by the matrix @@ -1451,7 +1449,7 @@ def restrict_codomain(self, sub): V = sub.free_module() try: if self.side() == "right": - return H(self.matrix().transpose().restrict_codomain(V).transpose(), side="right") + return H(self.matrix().transpose().restrict_codomain(V).transpose(), side='right') else: return H(self.matrix().restrict_codomain(V)) except Exception: @@ -1555,13 +1553,13 @@ class MatrixMorphism(MatrixMorphism_abstract): INPUT: - - ``parent`` -- a homspace + - ``parent`` -- a homspace - - ``A`` -- matrix or a :class:`MatrixMorphism_abstract` instance + - ``A`` -- matrix or a :class:`MatrixMorphism_abstract` instance - - ``copy_matrix`` -- (default: ``True``) make an immutable copy of - the matrix ``A`` if it is mutable; if ``False``, then this makes - ``A`` immutable + - ``copy_matrix`` -- boolean (default: ``True``); make an immutable copy of + the matrix ``A`` if it is mutable. If ``False``, then this makes + ``A`` immutable. """ def __init__(self, parent, A, copy_matrix=True, side='left'): """ diff --git a/src/sage/modules/module.pyx b/src/sage/modules/module.pyx index 845c4b239d8..1ca79818c26 100644 --- a/src/sage/modules/module.pyx +++ b/src/sage/modules/module.pyx @@ -71,7 +71,7 @@ cdef class Module(Parent): INPUT: - - ``base`` -- a ring. The base ring of the module. + - ``base`` -- a ring; the base ring of the module - ``category`` -- a category (default: ``None``), the category for this module. If ``None``, then this is set to the category of modules/vector @@ -112,7 +112,6 @@ cdef class Module(Parent): sage: M.rename('toto') sage: h == M.__hash__() True - """ def __init__(self, base, category=None, names=None): """ @@ -124,7 +123,6 @@ cdef class Module(Parent): sage: M = Module(ZZ) sage: type(M) - """ from sage.categories.modules import Modules if category is None: @@ -170,7 +168,6 @@ cdef class Module(Parent): - Simon King (2010-12) - Peter Bruin (June 2014) - """ try: if (isinstance(M, Module) @@ -193,7 +190,6 @@ cdef class Module(Parent): Traceback (most recent call last): ... NotImplementedError: the method change_ring() has not yet been implemented - """ if R is self.base_ring(): return self @@ -204,7 +200,7 @@ cdef class Module(Parent): Return the base extension of ``self`` to `R`. This is the same as ``self.change_ring(R)`` except that a - :class:`TypeError` is raised if there is no canonical coerce map + :exc:`TypeError` is raised if there is no canonical coerce map from the base ring of ``self`` to `R`. INPUT: @@ -245,7 +241,6 @@ cdef class Module(Parent): ... TypeError: Base extension of self (over 'Cyclotomic Field of order 9 and degree 6') to ring 'Cyclotomic Field of order 3 and degree 2' not defined. - """ if R.has_coerce_map_from(self.base_ring()): return self.change_ring(R) @@ -276,7 +271,7 @@ def is_Module(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything EXAMPLES:: @@ -302,7 +297,7 @@ def is_VectorSpace(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything EXAMPLES:: @@ -324,7 +319,6 @@ def is_VectorSpace(x): True sage: is_VectorSpace(M) False - """ from sage.misc.superseded import deprecation_cython deprecation_cython(37924, "the function is_VectorSpace is deprecated; use 'isinstance(..., Module)' and check the base ring instead") diff --git a/src/sage/modules/multi_filtered_vector_space.py b/src/sage/modules/multi_filtered_vector_space.py index 36bf483ee60..ece6d2af6c7 100644 --- a/src/sage/modules/multi_filtered_vector_space.py +++ b/src/sage/modules/multi_filtered_vector_space.py @@ -63,8 +63,8 @@ def MultiFilteredVectorSpace(arg, base_ring=None, check=True): base field of the vector space. Must be a field. If not specified, the base field is derived from the filtrations. - - ``check`` -- boolean (optional; default: ``True``). Whether - to perform consistency checks. + - ``check`` -- boolean (default: ``True``); whether + to perform consistency checks EXAMPLES:: @@ -110,15 +110,14 @@ def __init__(self, base_ring, dim, filtrations, check=True): INPUT: - - ``base_ring`` -- a ring. the base ring. + - ``base_ring`` -- the base ring - - ``dim`` -- integer. The dimension of the ambient vector space. + - ``dim`` -- integer; the dimension of the ambient vector space - - ``filtrations`` -- a dictionary whose values are - filtrations. + - ``filtrations`` -- dictionary whose values are filtrations - - ``check`` -- boolean (optional). Whether to perform - additional consistency checks. + - ``check`` -- boolean (default: ``True``); whether to perform + additional consistency checks EXAMPLES:: @@ -142,9 +141,7 @@ def index_set(self): """ Return the allowed indices for the different filtrations. - OUTPUT: - - Set. + OUTPUT: set EXAMPLES:: @@ -163,7 +160,7 @@ def change_ring(self, base_ring): INPUT: - - ``base_ring`` -- a ring. The new base ring. + - ``base_ring`` -- the new base ring OUTPUT: @@ -199,9 +196,7 @@ def ambient_vector_space(self): """ Return the ambient (unfiltered) vector space. - OUTPUT: - - A vector space. + OUTPUT: a vector space EXAMPLES:: @@ -218,10 +213,8 @@ def is_constant(self): """ Return whether the multi-filtration is constant. - OUTPUT: - - Boolean. Whether the each filtration is constant, see - :meth:`~sage.modules.filtered_vector_space.FilteredVectorSpace_class.is_constant`. + OUTPUT: boolean; whether the each filtration is constant, see + :meth:`~sage.modules.filtered_vector_space.FilteredVectorSpace_class.is_constant` EXAMPLES:: @@ -243,10 +236,8 @@ def is_exhaustive(self): A filtration `\{F_d\}` in an ambient vector space `V` is exhaustive if `\cup F_d = V`. See also :meth:`is_separating`. - OUTPUT: - - Boolean. Whether each filtration is constant, see - :meth:`~sage.modules.filtered_vector_space.FilteredVectorSpace_class.is_exhaustive`. + OUTPUT: boolean; whether each filtration is constant, see + :meth:`~sage.modules.filtered_vector_space.FilteredVectorSpace_class.is_exhaustive` EXAMPLES:: @@ -265,10 +256,8 @@ def is_separating(self): A filtration `\{F_d\}` in an ambient vector space `V` is exhaustive if `\cap F_d = 0`. See also :meth:`is_exhaustive`. - OUTPUT: - - Boolean. Whether each filtration is separating, see - :meth:`~sage.modules.filtered_vector_space.FilteredVectorSpace_class.is_separating`. + OUTPUT: boolean; whether each filtration is separating, see + :meth:`~sage.modules.filtered_vector_space.FilteredVectorSpace_class.is_separating` EXAMPLES:: @@ -355,9 +344,7 @@ def get_filtration(self, key): """ Return the filtration indexed by ``key``. - OUTPUT: - - A filtered vector space. + OUTPUT: a filtered vector space EXAMPLES:: @@ -375,10 +362,10 @@ def get_degree(self, key, deg): INPUT: - - ``key`` -- an element of the :meth:`index_set`. Specifies - which filtration. + - ``key`` -- an element of the :meth:`index_set`; specifies + which filtration - - ``d`` -- Integer. The desired degree of the filtration. + - ``d`` -- integer; the desired degree of the filtration OUTPUT: @@ -404,10 +391,10 @@ def graded(self, key, deg): INPUT: - - ``key`` -- an element of the :meth:`index_set`. Specifies - which filtration. + - ``key`` -- an element of the :meth:`index_set`; specifies + which filtration - - ``d`` -- Integer. The desired degree of the filtration. + - ``d`` -- integer; the desired degree of the filtration OUTPUT: @@ -434,9 +421,7 @@ def _repr_(self): r""" Return as string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -517,7 +502,7 @@ def direct_sum(self, other): INPUT: - ``other`` -- a multi-filtered vector space with the same - :meth:`index_set`. + :meth:`index_set` OUTPUT: @@ -558,7 +543,7 @@ def tensor_product(self, other): INPUT: - ``other`` -- a multi-filtered vector space with the same - :meth:`index_set`. + :meth:`index_set` OUTPUT: @@ -599,8 +584,7 @@ def exterior_power(self, n): INPUT: - - ``n`` -- integer. Exterior product of how many copies of - ``self``. + - ``n`` -- integer; exterior product of how many copies of ``self`` OUTPUT: @@ -629,8 +613,7 @@ def symmetric_power(self, n): INPUT: - - ``n`` -- integer. Symmetric product of how many copies of - ``self``. + - ``n`` -- integer; symmetric product of how many copies of ``self`` OUTPUT: @@ -699,11 +682,11 @@ def shift(self, deg): def random_deformation(self, epsilon=None): """ - Return a random deformation + Return a random deformation. INPUT: - - ``epsilon`` -- a number in the base ring. + - ``epsilon`` -- a number in the base ring OUTPUT: diff --git a/src/sage/modules/quotient_module.py b/src/sage/modules/quotient_module.py index a59273cc407..26c9c7629c0 100644 --- a/src/sage/modules/quotient_module.py +++ b/src/sage/modules/quotient_module.py @@ -219,7 +219,7 @@ def cover(self): def relations(self): r""" - Given this quotient space `Q = V/W`, return `W` + Given this quotient space `Q = V/W`, return `W`. EXAMPLES:: @@ -489,9 +489,9 @@ def _element_constructor_(self, x): Convert an element into this quotient space `V/W` if there is a way to make sense of it. - An element converts into self if it can be converted into `V`, + An element converts into ``self`` if it can be converted into `V`, or if not at least if it can be made sense of as a list of - length the dimension of self. + length the dimension of ``self``. EXAMPLES: @@ -534,7 +534,6 @@ def _element_constructor_(self, x): sage: Q((ZZ^3)([1,2,3])) (2, 3) - """ if isinstance(x, self.element_class) and x.parent() is self: return x @@ -576,7 +575,6 @@ def _coerce_map_from_(self, M): sage: V = QQ^3 / [[1,2,3]] sage: V.coerce_map_from(QQ^2) - """ from sage.modules.free_module import FreeModule_ambient if (isinstance(M, FreeModule_ambient) diff --git a/src/sage/modules/tensor_operations.py b/src/sage/modules/tensor_operations.py index 8ca968133a2..2f17640d89e 100644 --- a/src/sage/modules/tensor_operations.py +++ b/src/sage/modules/tensor_operations.py @@ -71,13 +71,13 @@ def symmetrized_coordinate_sums(dim, n): """ - Return formal symmetrized sum of multi-indices + Return formal symmetrized sum of multi-indices. INPUT: - - ``dim`` -- integer. The dimension (range of each index). + - ``dim`` -- integer; the dimension (range of each index) - - ``n`` -- integer. The total number of indices. + - ``n`` -- integer; the total number of indices OUTPUT: @@ -103,13 +103,13 @@ def symmetrized_coordinate_sums(dim, n): def antisymmetrized_coordinate_sums(dim, n): """ - Return formal anti-symmetrized sum of multi-indices + Return formal anti-symmetrized sum of multi-indices. INPUT: - - ``dim`` -- integer. The dimension (range of each index). + - ``dim`` -- integer; the dimension (range of each index) - - ``n`` -- integer. The total number of indices. + - ``n`` -- integer; the total number of indices OUTPUT: @@ -143,9 +143,9 @@ class VectorCollection(FreeModule_ambient_field): INPUT: - - ``dim`` -- integer. The dimension of the ambient vector space. + - ``dim`` -- integer; the dimension of the ambient vector space - - ``base_ring`` -- a field. The base field of the ambient vector space. + - ``base_ring`` -- a field; the base field of the ambient vector space - ``rays`` -- any list/iterable of things than can be converted into vectors of the ambient vector space. These will be used to @@ -189,7 +189,7 @@ def __init__(self, vector_collection, base_ring, dim): def vectors(self): """ - Return the collection of vectors + Return the collection of vectors. OUTPUT: @@ -207,11 +207,9 @@ def vectors(self): def n_vectors(self): """ - Return the number of vectors + Return the number of vectors. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -236,10 +234,10 @@ class TensorOperation(VectorCollection): INPUT: - ``vector_collections`` -- a nonempty list/tuple/iterable of - :class:`VectorCollection` objects. + :class:`VectorCollection` objects - - ``operation`` -- string. The tensor operation. Currently allowed - values are ``product``, ``symmetric``, and ``antisymmetric``. + - ``operation`` -- string; the tensor operation. Currently allowed + values are ``'product'``, ``'symmetric'``, and ``'antisymmetric'``. .. TODO:: @@ -300,7 +298,7 @@ def _init_product_vectors(self, i): INPUT: - - `i` -- list/tuple of integers. Multi-index of length equal + - ``i`` -- list/tuple of integers. Multi-index of length equal to the number of constituent vector collections. The `j`-th entry `i[j]` indexes a ray in the `j`-th vector collection. Hence, `i` specifies one element in each vector @@ -353,12 +351,12 @@ def _init_power_operation_vectors(self, i, linear_combinations): INPUT: - - `i` -- list/tuple of integers. Specifies one element + - ``i`` -- list/tuple of integers. Specifies one element (vector) in each vector collection as in - :meth:`_init_product_vector`. + :meth:`_init_product_vector` - ``linear_combination`` -- formal linear combination of - vector indices in the vectors specified by `i`. + vector indices in the vectors specified by `i` EXAMPLES:: @@ -391,7 +389,7 @@ def _init_power_operation_vectors(self, i, linear_combinations): def _init_product(self): """ - Initialization for the tensor product + Initialization for the tensor product. EXAMPLES:: @@ -433,7 +431,7 @@ def _init_symmetric(self): def _init_antisymmetric(self): """ - Initialization for the antisymmetric product + Initialization for the antisymmetric product. EXAMPLES:: @@ -552,9 +550,7 @@ def codomain(self): """ The codomain of the index map. - OUTPUT: - - A list of integers. The image of :meth:`index_map`. + OUTPUT: list of integers; the image of :meth:`index_map` EXAMPLES:: diff --git a/src/sage/modules/torsion_quadratic_module.py b/src/sage/modules/torsion_quadratic_module.py index 45f1450c3cb..d6d8431ff2f 100644 --- a/src/sage/modules/torsion_quadratic_module.py +++ b/src/sage/modules/torsion_quadratic_module.py @@ -97,7 +97,7 @@ class TorsionQuadraticModuleElement(FGP_Element): - ``x`` -- element of ``parent.V()`` - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) TESTS:: @@ -205,7 +205,7 @@ class TorsionQuadraticModule(FGP_Module_class, CachedRepresentation): - ``W`` -- a submodule of ``V`` of the same rank as ``V`` - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - ``modulus`` -- a rational number dividing `m` (default: `m`); the inner product `b` is defined in `\QQ /` ``modulus`` `\ZZ` @@ -328,14 +328,12 @@ def _module_constructor(self, V, W, check=False): - ``W`` -- a submodule of ``V`` over the same base ring - - ``check`` -- bool (default: ``False``); + - ``check`` -- boolean (default: ``False``) * if ``False``, then the value modulus is inherited from ``self`` * if ``True``, it figures it out on its own. But that is expensive - OUTPUT: - - The quotient ``V / W`` as a :class:`TorsionQuadraticModule`. + OUTPUT: the quotient ``V / W`` as a :class:`TorsionQuadraticModule` EXAMPLES:: @@ -423,9 +421,7 @@ def brown_invariant(self): The Brown invariant is additive with respect to direct sums of torsion quadratic modules. - OUTPUT: - - - an element of `\Zmod{8}` + OUTPUT: an element of `\Zmod{8}` EXAMPLES:: @@ -544,7 +540,7 @@ def genus(self, signature_pair): r""" Return the genus defined by ``self`` and the ``signature_pair``. - If no such genus exists, raise a :class:`ValueError`. + If no such genus exists, raise a :exc:`ValueError`. REFERENCES: @@ -754,8 +750,8 @@ def is_genus(self, signature_pair, even=True): INPUT: - - ``signature_pair`` -- a tuple of non negative integers ``(s_plus, s_minus)`` - - ``even`` -- bool (default: ``True``) + - ``signature_pair`` -- tuple of nonnegative integers ``(s_plus, s_minus)`` + - ``even`` -- boolean (default: ``True``) EXAMPLES:: @@ -776,7 +772,7 @@ def is_genus(self, signature_pair, even=True): s_plus = ZZ(signature_pair[0]) s_minus = ZZ(signature_pair[1]) if s_plus < 0 or s_minus < 0: - raise ValueError("signature invariants must be non negative") + raise ValueError("signature invariants must be nonnegative") rank = s_plus + s_minus signature = s_plus - s_minus D = self.cardinality() @@ -829,7 +825,7 @@ def orthogonal_group(self, gens=None, check=False): INPUT: - - ``gens`` -- a list of generators, for instance square matrices, + - ``gens`` -- a list of generators, for instance square matrices, something that acts on ``self``, or an automorphism of the underlying abelian group - ``check`` -- perform additional checks on the generators @@ -985,12 +981,10 @@ def normal_form(self, partial=False): INPUT: - - ``partial`` -- bool (default: ``False``) return only a partial normal form; - it is not unique but still useful to extract invariants - - OUTPUT: + - ``partial`` -- boolean (default: ``False``); return only a partial + normal form. It is not unique but still useful to extract invariants. - - a torsion quadratic module + OUTPUT: a torsion quadratic module EXAMPLES:: @@ -1125,11 +1119,9 @@ def primary_part(self, m): INPUT: - - ``m`` -- an integer - - OUTPUT: + - ``m`` -- integer - - a submodule + OUTPUT: a submodule EXAMPLES:: @@ -1162,11 +1154,9 @@ def submodule_with_gens(self, gens): INPUT: - - ``gens`` -- a list of generators that convert into ``self`` - - OUTPUT: + - ``gens`` -- list of generators that convert into ``self`` - - a submodule with the specified generators + OUTPUT: a submodule with the specified generators EXAMPLES:: diff --git a/src/sage/modules/tutorial_free_modules.py b/src/sage/modules/tutorial_free_modules.py index 8fe8cd8c7df..3af1ba78f54 100644 --- a/src/sage/modules/tutorial_free_modules.py +++ b/src/sage/modules/tutorial_free_modules.py @@ -137,12 +137,12 @@ Some definitions: * A *monomial* is an element of the basis `B_i`; - * A *term* is an element of the basis multiplied by a non zero + * A *term* is an element of the basis multiplied by a nonzero *coefficient*: `c B_i`; * The support of that term is `i`. * The corresponding *item* is the :class:`tuple` ``(i, c)``. * The *support* of an element `f` is the collection of indices `i` - such that `B_i` appears in `f` with non zero coefficient. + such that `B_i` appears in `f` with nonzero coefficient. * The *monomials*, *terms*, *items*, and *coefficients* of an element `f` are defined accordingly. * *Leading*/*trailing* refers to the *greatest*/*least* index. diff --git a/src/sage/modules/vector_callable_symbolic_dense.py b/src/sage/modules/vector_callable_symbolic_dense.py index eb2cf2eedfd..8f23e78114f 100644 --- a/src/sage/modules/vector_callable_symbolic_dense.py +++ b/src/sage/modules/vector_callable_symbolic_dense.py @@ -55,7 +55,7 @@ class Vector_callable_symbolic_dense(free_module_element.FreeModuleElement_generic_dense): def _repr_(self): """ - Returns the string representation of the vector + Return the string representation of the vector. EXAMPLES:: diff --git a/src/sage/modules/vector_complex_double_dense.pyx b/src/sage/modules/vector_complex_double_dense.pyx index 59b585f912c..c8aaedce365 100644 --- a/src/sage/modules/vector_complex_double_dense.pyx +++ b/src/sage/modules/vector_complex_double_dense.pyx @@ -71,7 +71,7 @@ cdef class Vector_complex_double_dense(Vector_double_dense): def __reduce__(self): """ - Pickling + Pickling. EXAMPLES:: diff --git a/src/sage/modules/vector_double_dense.pyx b/src/sage/modules/vector_double_dense.pyx index 79f42205439..5c184c96967 100644 --- a/src/sage/modules/vector_double_dense.pyx +++ b/src/sage/modules/vector_double_dense.pyx @@ -103,7 +103,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): cpdef _sub_(self, right): """ - Return self - right + Return ``self - right``. EXAMPLES:: @@ -123,7 +123,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): cpdef _dot_product_(self, Vector right): """ - Dot product of self and right. + Dot product of ``self`` and ``right``. EXAMPLES:: @@ -147,7 +147,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): cpdef _pairwise_product_(self, Vector right): """ - Return the component-wise product of self and right. + Return the component-wise product of ``self`` and ``right``. EXAMPLES:: @@ -170,7 +170,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): cpdef _rmul_(self, Element left): """ - Multiply a scalar and vector + Multiply a scalar and vector. EXAMPLES:: @@ -186,7 +186,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): cpdef _lmul_(self, Element right): """ - Multiply a scalar and vector + Multiply a scalar and vector. EXAMPLES:: @@ -200,7 +200,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): return self._new(self._vector_numpy*self._python_dtype(right)) - def inv_fft(self,algorithm="radix2", inplace=False): + def inv_fft(self, algorithm='radix2', inplace=False): """ This performs the inverse fast Fourier transform on the vector. @@ -217,15 +217,15 @@ cdef class Vector_double_dense(Vector_numpy_dense): sage: max(v - w.inv_fft()) < 1e-12 True """ - return self.fft(direction="backward",algorithm=algorithm,inplace=inplace) + return self.fft(direction='backward', algorithm=algorithm, inplace=inplace) - def fft(self, direction = "forward", algorithm = "radix2", inplace=False): + def fft(self, direction='forward', algorithm='radix2', inplace=False): """ This performs a fast Fourier transform on the vector. INPUT: - - direction -- 'forward' (default) or 'backward' + - ``direction`` -- string; ``'forward'`` (default) or ``'backward'`` The algorithm and inplace arguments are ignored. @@ -311,7 +311,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): def zero_at(self, eps): r""" - Returns a copy with small entries replaced by zeros. + Return a copy with small entries replaced by zeros. This is useful for modifying output from algorithms which have large relative errors when producing zero @@ -328,7 +328,6 @@ cdef class Vector_double_dense(Vector_numpy_dense): complex vectors, the real and imaginary parts are considered individually. - EXAMPLES:: sage: v = vector(RDF, [1.0, 2.0, 10^-10, 3.0]) @@ -360,11 +359,11 @@ cdef class Vector_double_dense(Vector_numpy_dense): def norm(self, p=2): r""" - Returns the norm (or related computations) of the vector. + Return the norm (or related computations) of the vector. INPUT: - - ``p`` -- (default: 2); controls which norm is computed, + - ``p`` -- (default: 2) controls which norm is computed, allowable values are any real number and positive and negative infinity. See output discussion for specifics. @@ -376,12 +375,11 @@ cdef class Vector_double_dense(Vector_numpy_dense): - ``p = Infinity`` or ``p = oo``: the maximum of the absolute values of the entries, where the absolute value - of the complex number `a+bi` is `\sqrt{a^2+b^2}`. + of the complex number `a+bi` is `\sqrt{a^2+b^2}` - ``p = -Infinity`` or ``p = -oo``: the minimum of the - absolute values of the entries. - - ``p = 0`` : the number of nonzero entries in the vector. - - ``p`` is any other real number: for a vector `\vec{x}` - this method computes + absolute values of the entries + - ``p = 0``: the number of nonzero entries in the vector + - ``p`` any other real number: for a vector `\vec{x}` this method computes .. MATH:: @@ -470,7 +468,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): except Exception: raise ValueError("vector norm 'p' must be +/- infinity or a real number, not %s" % p) n = numpy.linalg.norm(self._vector_numpy, ord=p) - # p = 0 returns integer *count* of non-zero entries + # p = 0 returns integer *count* of nonzero entries return RDF(n) ############################# @@ -498,7 +496,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): INPUT: - - ``population`` -- If False, calculate the sample variance. + - ``population`` -- if ``False``, calculate the sample variance EXAMPLES:: @@ -523,7 +521,9 @@ cdef class Vector_double_dense(Vector_numpy_dense): Calculate the standard deviation of entries of the vector. INPUT: - population -- If False, calculate the sample standard deviation. + + - ``population`` -- If ``False``, calculate the sample standard + deviation EXAMPLES:: @@ -567,7 +567,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): def prod(self): """ - Return the product of the entries of self. + Return the product of the entries of ``self``. EXAMPLES:: @@ -582,7 +582,7 @@ cdef class Vector_double_dense(Vector_numpy_dense): def sum(self): """ - Return the sum of the entries of self. + Return the sum of the entries of ``self``. EXAMPLES:: diff --git a/src/sage/modules/vector_integer_dense.pyx b/src/sage/modules/vector_integer_dense.pyx index 274f1c0dbff..3605f4cf865 100644 --- a/src/sage/modules/vector_integer_dense.pyx +++ b/src/sage/modules/vector_integer_dense.pyx @@ -196,7 +196,7 @@ cdef class Vector_integer_dense(free_module_element.FreeModuleElement): INPUT: - - ``copy``, ignored optional argument. + - ``copy`` -- ignored optional argument EXAMPLES:: @@ -307,7 +307,7 @@ cdef class Vector_integer_dense(free_module_element.FreeModuleElement): INPUT: - - singular -- \Singular interface instance (default: None) + - ``singular`` -- \Singular interface instance (default: ``None``) EXAMPLES:: diff --git a/src/sage/modules/vector_integer_sparse.pyx b/src/sage/modules/vector_integer_sparse.pyx index b647c22fb23..8484c0a6a93 100644 --- a/src/sage/modules/vector_integer_sparse.pyx +++ b/src/sage/modules/vector_integer_sparse.pyx @@ -87,12 +87,15 @@ cdef Py_ssize_t mpz_binary_search(mpz_t* v, Py_ssize_t n, mpz_t x, Py_ssize_t* i obtain an ordered array. INPUT: - v -- array of mpz_t (integer) - n -- integer (length of array v) - x -- mpz_t (integer) + + - ``v`` -- array of mpz_t (integer) + - ``n`` -- integer (length of array v) + - ``x`` -- mpz_t (integer) + OUTPUT: - position of x (as a Py_ssize_t) - ins -- (call be pointer), the insertion point if x is not found. + + position of x (as a Py_ssize_t) + ins -- (call be pointer), the insertion point if x is not found. """ cdef Py_ssize_t i, j, k, c if n == 0: @@ -127,7 +130,7 @@ cdef Py_ssize_t mpz_binary_search(mpz_t* v, Py_ssize_t n, mpz_t x, Py_ssize_t* i cdef int mpz_vector_get_entry(mpz_t ans, mpz_vector* v, Py_ssize_t n) except -1: """ Returns the n-th entry of the sparse vector v. This - would be v[n] in Python syntax. + would be ``v[n]`` in Python syntax. The return is done using the pointer ans, which is to an mpz_t that *must* have been initialized using mpz_init. @@ -153,7 +156,7 @@ cdef bint mpz_vector_is_entry_zero_unsafe(mpz_vector* v, Py_ssize_t n) noexcept: cdef object mpz_vector_to_list(mpz_vector* v): """ - Returns a Python list of 2-tuples (i,x), where x=v[i] runs + Return a Python list of 2-tuples (i,x), where ``x=v[i]`` runs through the nonzero elements of x, in order. """ cdef object X @@ -170,7 +173,7 @@ cdef object mpz_vector_to_list(mpz_vector* v): cdef int mpz_vector_set_entry(mpz_vector* v, Py_ssize_t n, mpz_t x) except -1: """ Set the n-th component of the sparse vector v equal to x. - This would be v[n] = x in Python syntax. + This would be ``v[n] = x`` in Python syntax. """ if n >= v.degree or n < 0: raise IndexError("Index (=%s) must be between 0 and %s." % (n, v.degree - 1)) diff --git a/src/sage/modules/vector_numpy_dense.pyx b/src/sage/modules/vector_numpy_dense.pyx index 9b16a6c354d..b6e6d37473f 100644 --- a/src/sage/modules/vector_numpy_dense.pyx +++ b/src/sage/modules/vector_numpy_dense.pyx @@ -53,7 +53,7 @@ cdef class Vector_numpy_dense(FreeModuleElement): def __cinit__(self, parent, entries, coerce=True, copy=True): """ - Set up a new vector + Set up a new vector. EXAMPLES:: @@ -70,7 +70,7 @@ cdef class Vector_numpy_dense(FreeModuleElement): cdef Vector_numpy_dense _new(self, numpy.ndarray vector_numpy): """ - Return a new vector with same parent as self. + Return a new vector with same parent as ``self``. """ cdef Vector_numpy_dense v v = self.__class__.__new__(self.__class__,self._parent,None,None,None) @@ -103,19 +103,19 @@ cdef class Vector_numpy_dense(FreeModuleElement): cdef bint is_dense_c(self) noexcept: """ - Return True (i.e., 1) if self is dense. + Return ``True`` (i.e., 1) if ``self`` is dense. """ return 1 cdef bint is_sparse_c(self) noexcept: """ - Return True (i.e., 1) if self is sparse. + Return ``True`` (i.e., 1) if ``self`` is sparse. """ return 0 def __copy__(self, copy=True): """ - Return a copy of the vector + Return a copy of the vector. EXAMPLES:: @@ -266,8 +266,9 @@ cdef class Vector_numpy_dense(FreeModuleElement): INPUT: - - ``dtype`` -- if specified, the `numpy dtype `_ - of the returned array. + - ``dtype`` -- if specified, the `numpy dtype + `_ of + the returned array EXAMPLES:: diff --git a/src/sage/modules/vector_rational_dense.pyx b/src/sage/modules/vector_rational_dense.pyx index 864628f10c7..22e3c67fcc3 100644 --- a/src/sage/modules/vector_rational_dense.pyx +++ b/src/sage/modules/vector_rational_dense.pyx @@ -234,7 +234,7 @@ cdef class Vector_rational_dense(free_module_element.FreeModuleElement): INPUT: - - ``copy``, ignored optional argument. + - ``copy`` -- ignored optional argument EXAMPLES:: diff --git a/src/sage/modules/vector_rational_sparse.pyx b/src/sage/modules/vector_rational_sparse.pyx index 2c661f34bab..fcdaf2b7cf8 100644 --- a/src/sage/modules/vector_rational_sparse.pyx +++ b/src/sage/modules/vector_rational_sparse.pyx @@ -94,12 +94,15 @@ cdef Py_ssize_t mpq_binary_search(mpq_t* v, Py_ssize_t n, mpq_t x, Py_ssize_t* i obtain an ordered array. INPUT: - v -- array of mpq_t (rational) - n -- integer (length of array v) - x -- mpq_t (rational) + + - ``v`` -- array of mpq_t (rational) + - ``n`` -- integer (length of array v) + - ``x`` -- mpq_t (rational) + OUTPUT: - position of x (as an Py_ssize_t) - ins -- (call be pointer), the insertion point if x is not found. + + position of x (as an Py_ssize_t) + ins -- (call be pointer), the insertion point if x is not found. """ cdef Py_ssize_t i, j, k, c if n == 0: @@ -133,11 +136,11 @@ cdef Py_ssize_t mpq_binary_search(mpq_t* v, Py_ssize_t n, mpq_t x, Py_ssize_t* i cdef int mpq_vector_get_entry(mpq_t ans, mpq_vector* v, Py_ssize_t n) except -1: """ - Returns the n-th entry of the sparse vector v. This - would be v[n] in Python syntax. + Return the n-th entry of the sparse vector v. This + would be ``v[n]`` in Python syntax. - The return is done using the pointer ans, which is to an mpq_t - that *must* have been initialized using mpq_init. + The return is done using the pointer ``ans``, which is to an ``mpq_t`` + that *must* have been initialized using ``mpq_init``. """ if n >= v.degree: raise IndexError("Index must be between 0 and %s." % (v.degree - 1)) @@ -160,7 +163,7 @@ cdef bint mpq_vector_is_entry_zero_unsafe(mpq_vector* v, Py_ssize_t n) noexcept: cdef object mpq_vector_to_list(mpq_vector* v): """ - Returns a Python list of 2-tuples (i,x), where x=v[i] runs + Return a Python list of 2-tuples (i,x), where ``x=v[i]`` runs through the nonzero elements of x, in order. """ cdef object X @@ -177,7 +180,7 @@ cdef object mpq_vector_to_list(mpq_vector* v): cdef int mpq_vector_set_entry(mpq_vector* v, Py_ssize_t n, mpq_t x) except -1: """ Set the n-th component of the sparse vector v equal to x. - This would be v[n] = x in Python syntax. + This would be ``v[n] = x`` in Python syntax. """ if n >= v.degree or n < 0: raise IndexError("Index must be between 0 and the degree minus 1.") @@ -250,7 +253,7 @@ mpq_init(mpq_set_tmp) cdef int mpq_vector_set_entry_str(mpq_vector* v, Py_ssize_t n, char *x_str) except -1: """ Set the n-th component of the sparse vector v equal to x. - This would be v[n] = x in Python syntax. + This would be ``v[n] = x`` in Python syntax. """ mpq_set_str(mpq_set_tmp, x_str, 0) mpq_vector_set_entry(v, n, mpq_set_tmp) diff --git a/src/sage/modules/vector_real_double_dense.pyx b/src/sage/modules/vector_real_double_dense.pyx index 0bedec59d58..8ed7210422b 100644 --- a/src/sage/modules/vector_real_double_dense.pyx +++ b/src/sage/modules/vector_real_double_dense.pyx @@ -62,7 +62,7 @@ cdef class Vector_real_double_dense(Vector_double_dense): def stats_skew(self): """ - Computes the skewness of a data set. + Compute the skewness of a data set. For normally distributed data, the skewness should be about 0. A skewness value > 0 means that there is more weight in the @@ -80,7 +80,7 @@ cdef class Vector_real_double_dense(Vector_double_dense): def __reduce__(self): """ - Pickling + Pickling. EXAMPLES:: diff --git a/src/sage/modules/vector_space_homspace.py b/src/sage/modules/vector_space_homspace.py index 1589e66d640..d18bfd769b4 100644 --- a/src/sage/modules/vector_space_homspace.py +++ b/src/sage/modules/vector_space_homspace.py @@ -254,7 +254,7 @@ def __call__(self, A, check=True, **kwds): INPUT: - ``A`` -- one of several possible inputs representing - a morphism from this vector space homspace. + a morphism from this vector space homspace: - a vector space morphism in this homspace - a matrix representation relative to the bases of the vector spaces, @@ -262,13 +262,12 @@ def __call__(self, A, check=True, **kwds): - a list or tuple containing images of the domain's basis vectors - a function from the domain to the codomain - - ``check`` (default: ``True``) -- ``True`` or ``False``, required for - compatibility with calls from - :meth:`sage.structure.parent.Parent.hom`. + - ``check`` -- boolean (default: ``True``); required for compatibility + with calls from :meth:`sage.structure.parent.Parent.hom` - - the keyword ``side`` can be assigned the values ``"left"`` or - ``"right"``. It corresponds to the side of vectors relative to the - matrix. + - the keyword ``side`` can be assigned the values ``'left'`` or + ``'right'``; it corresponds to the side of vectors relative to the + matrix EXAMPLES:: @@ -371,7 +370,7 @@ def __call__(self, A, check=True, **kwds): sage: H.zero().is_zero() True - Previously the above code resulted in a :class:`TypeError` because the + Previously the above code resulted in a :exc:`TypeError` because the dimensions of the matrix were incorrect. """ from .vector_space_morphism import VectorSpaceMorphism diff --git a/src/sage/modules/vector_space_morphism.py b/src/sage/modules/vector_space_morphism.py index 460e8fba728..9eee6152585 100644 --- a/src/sage/modules/vector_space_morphism.py +++ b/src/sage/modules/vector_space_morphism.py @@ -345,7 +345,7 @@ def linear_transformation(arg0, arg1=None, arg2=None, side='left'): the same field that are the domain and codomain (respectively) of the linear transformation. - ``side`` is a keyword that is either 'left' or 'right'. + ``side`` is a keyword that is either ``'left'`` or ``'right'``. When a matrix is used to specify a linear transformation, as in the first two call formats below, you may specify if the function is given by matrix multiplication with @@ -781,7 +781,7 @@ def linear_transformation(arg0, arg1=None, arg2=None, side='left'): def is_VectorSpaceMorphism(x) -> bool: r""" - Returns ``True`` if ``x`` is a vector space morphism (a linear transformation). + Return ``True`` if ``x`` is a vector space morphism (a linear transformation). This function is deprecated. @@ -815,17 +815,17 @@ def is_VectorSpaceMorphism(x) -> bool: class VectorSpaceMorphism(free_module_morphism.FreeModuleMorphism): - def __init__(self, homspace, A, side="left"): + def __init__(self, homspace, A, side='left'): r""" Create a linear transformation, a morphism between vector spaces. INPUT: - - ``homspace`` -- a homspace (of vector spaces) to serve - as a parent for the linear transformation and a home for - the domain and codomain of the morphism - - ``A`` -- a matrix representing the linear transformation, - which will act on vectors placed to the left of the matrix + - ``homspace`` -- a homspace (of vector spaces) to serve + as a parent for the linear transformation and a home for + the domain and codomain of the morphism + - ``A`` -- a matrix representing the linear transformation, + which will act on vectors placed to the left of the matrix EXAMPLES: diff --git a/src/sage/modules/vector_symbolic_dense.py b/src/sage/modules/vector_symbolic_dense.py index b1d47f32966..e3d6524a921 100644 --- a/src/sage/modules/vector_symbolic_dense.py +++ b/src/sage/modules/vector_symbolic_dense.py @@ -59,7 +59,7 @@ def apply_map(phi): """ - Returns a function that applies phi to its argument. + Return a function that applies ``phi`` to its argument. EXAMPLES:: @@ -68,7 +68,6 @@ def apply_map(phi): sage: f = apply_map(lambda x: x+1) sage: f(v) (2, 3, 4) - """ def apply(self, *args, **kwds): """ diff --git a/src/sage/modules/vector_symbolic_sparse.py b/src/sage/modules/vector_symbolic_sparse.py index c0e7fc209b6..290aa282a85 100644 --- a/src/sage/modules/vector_symbolic_sparse.py +++ b/src/sage/modules/vector_symbolic_sparse.py @@ -61,7 +61,7 @@ def apply_map(phi): """ - Returns a function that applies phi to its argument. + Return a function that applies ``phi`` to its argument. EXAMPLES:: @@ -70,7 +70,6 @@ def apply_map(phi): sage: f = apply_map(lambda x: x+1) sage: f(v) (2, 3, 4) - """ def apply(self, *args, **kwds): """ diff --git a/src/sage/modules/with_basis/cell_module.py b/src/sage/modules/with_basis/cell_module.py index 2c5f54de21b..7c61057737c 100644 --- a/src/sage/modules/with_basis/cell_module.py +++ b/src/sage/modules/with_basis/cell_module.py @@ -234,7 +234,7 @@ def bilinear_form_matrix(self, ordering=None): @cached_method def nonzero_bilinear_form(self): """ - Return ``True`` if the bilinear form of ``self`` is non-zero. + Return ``True`` if the bilinear form of ``self`` is nonzero. EXAMPLES:: diff --git a/src/sage/modules/with_basis/indexed_element.pyx b/src/sage/modules/with_basis/indexed_element.pyx index 85428fc1f55..47e2fe1cc6f 100644 --- a/src/sage/modules/with_basis/indexed_element.pyx +++ b/src/sage/modules/with_basis/indexed_element.pyx @@ -31,7 +31,7 @@ from sage.categories.modules import _Fields cdef class IndexedFreeModuleElement(ModuleElement): r""" - Element class for :class:`~sage.combinat.free_module.CombinatorialFreeModule` + Element class for :class:`~sage.combinat.free_module.CombinatorialFreeModule`. TESTS:: @@ -235,10 +235,10 @@ cdef class IndexedFreeModuleElement(ModuleElement): INPUT: - - ``copy`` -- (default: ``True``) if ``self`` is internally - represented by a dictionary ``d``, then make a copy of ``d``; - if ``False``, then this can cause undesired behavior by - mutating ``d`` + - ``copy`` -- boolean (default: ``True``); if ``self`` is internally + represented by a dictionary ``d``, then make a copy of ``d``. + If ``False``, then this can cause undesired behavior by + mutating ``d``. EXAMPLES:: @@ -786,7 +786,7 @@ cdef class IndexedFreeModuleElement(ModuleElement): - ``new_base_ring`` -- a ring (default: ``None``) - ``order`` -- (optional) an ordering of the support of ``self`` - - ``sparse`` -- (default: ``False``) whether to return a sparse + - ``sparse`` -- boolean (default: ``False``); whether to return a sparse vector or a dense vector OUTPUT: a :func:`FreeModule` vector diff --git a/src/sage/modules/with_basis/invariant.py b/src/sage/modules/with_basis/invariant.py index 7e7600f3069..0c96c6a5b9d 100644 --- a/src/sage/modules/with_basis/invariant.py +++ b/src/sage/modules/with_basis/invariant.py @@ -257,7 +257,7 @@ def _invariant_map(g, x): # Give the intersection of kernels of the map `s*x-x` to determine when # `s*x = x` for all generators `s` of `S` - basis = M.annihilator_basis(S.gens(), action=_invariant_map, side="left") + basis = M.annihilator_basis(S.gens(), action=_invariant_map, side='left') super().__init__(Family(basis), support_order=M._compute_support_order(basis), @@ -800,7 +800,7 @@ def __classcall_private__(cls, M, G, chi, sage: type(T) - Check the :class:`ValueError`:: + Check the :exc:`ValueError`:: sage: T = M.twisted_invariant_module(G, "ichigo", action_on_basis=action) Traceback (most recent call last): @@ -905,7 +905,7 @@ def proj_difference(g, x): basis = M.annihilator_basis(M.basis(), action=proj_difference, - side="left") + side='left') super().__init__(Family(basis), support_order=M._compute_support_order(basis), diff --git a/src/sage/modules/with_basis/morphism.py b/src/sage/modules/with_basis/morphism.py index 1e2e169b147..68ad2521493 100644 --- a/src/sage/modules/with_basis/morphism.py +++ b/src/sage/modules/with_basis/morphism.py @@ -133,10 +133,10 @@ class ModuleMorphism(Morphism): INPUT: - ``domain`` -- a parent in ``ModulesWithBasis(...)`` - - ``codomain`` -- a parent in ``Modules(...)``; - - ``category`` -- a category or ``None`` (default: `None``) + - ``codomain`` -- a parent in ``Modules(...)`` + - ``category`` -- a category or ``None`` (default: ``None``) - ``affine`` -- whether we define an affine module morphism - (default: ``False``). + (default: ``False``) Construct a module morphism from ``domain`` to ``codomain`` in the category ``category``. By default, the category is the first of @@ -164,7 +164,7 @@ class of ``self`` upon construction. """ def __init__(self, domain, codomain=None, category=None, affine=False): """ - Initialization of module morphisms + Initialization of module morphisms. TESTS:: @@ -252,7 +252,7 @@ def __init__(self, domain, function, codomain=None, category=None): """ TESTS:: - sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); X.rename('X'); x = X.basis() sage: from sage.modules.with_basis.morphism import ModuleMorphismFromFunction sage: def f(x): return 3*x sage: import __main__; __main__.f = f # Fake f being defined in a python module @@ -277,7 +277,7 @@ class ModuleMorphismByLinearity(ModuleMorphism): ``domain`` as ``position``-th argument - ``codomain`` -- a parent in ``Modules(...)`` (default: ``on_basis.codomain()``) - - ``position`` -- a non-negative integer (default: 0) + - ``position`` -- nonnegative integer (default: 0) - ``zero`` -- the zero of the codomain (defaults: ``codomain.zero()``) .. SEEALSO:: @@ -341,7 +341,6 @@ def _richcmp_(self, other, op): sage: h3 = X.module_morphism(on_basis=Y.monomial * abs, category=Modules(ZZ)) sage: f == g, f == h1, f == h2, f == h3, f == 1, 1 == f (True, False, False, False, False, False) - """ if op == op_EQ: return (self.__class__ is other.__class__ @@ -418,7 +417,7 @@ def __call__(self, *args): class TriangularModuleMorphism(ModuleMorphism): r""" - An abstract class for triangular module morphisms + An abstract class for triangular module morphisms. Let `X` and `Y` be modules over the same base ring, with distinguished bases `F` indexed by `I` and `G` indexed by `J`, @@ -446,10 +445,10 @@ class TriangularModuleMorphism(ModuleMorphism): - ``codomain`` -- a module with basis `Y` (default: `X`) - ``category`` -- a category, as for :class:`ModuleMorphism` - - ``triangular`` -- ``"upper"`` or ``"lower"`` (default: ``"upper"``) + - ``triangular`` -- ``'upper'`` or ``'lower'`` (default: ``'upper'``) - ``unitriangular`` -- boolean (default: ``False``) - As a shorthand, one may use ``unitriangular="lower"`` - for ``triangular="lower", unitriangular=True``. + As a shorthand, one may use ``unitriangular='lower'`` + for ``triangular='lower', unitriangular=True``. - ``key`` -- a comparison key on `J` (default: the usual comparison of elements of `J`) @@ -461,7 +460,7 @@ class TriangularModuleMorphism(ModuleMorphism): domain. This of course requires the domain to be finite dimensional. - - ``invertible`` -- a boolean or ``None`` (default: ``None``); can + - ``invertible`` -- boolean or ``None`` (default: ``None``); can be set to specify that `\phi` is known to be (or not to be) invertible. If the domain and codomain share the same indexing set, this is by default automatically set to ``True`` if @@ -477,9 +476,7 @@ class TriangularModuleMorphism(ModuleMorphism): - :class:`ModuleMorphismFromFunction` and :class:`TriangularModuleMorphism`. - OUTPUT: - - A morphism from `X` to `Y`. + OUTPUT: a morphism from `X` to `Y` .. WARNING:: @@ -496,10 +493,10 @@ class TriangularModuleMorphism(ModuleMorphism): two free `\QQ`-modules:: sage: I = range(1,200) - sage: X = CombinatorialFreeModule(QQ, I); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(QQ, I); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(QQ, I); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(QQ, I); Y.rename('Y'); y = Y.basis() sage: ut = Y.sum_of_monomials * divisors # This * is map composition. - sage: phi = X.module_morphism(ut, unitriangular="upper", codomain=Y) + sage: phi = X.module_morphism(ut, unitriangular='upper', codomain=Y) sage: phi(x[2]) B[1] + B[2] sage: phi(x[6]) @@ -517,9 +514,9 @@ class TriangularModuleMorphism(ModuleMorphism): A lower triangular (but not unitriangular) morphism:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() sage: def lt(i): return sum(j*x[j] for j in range(i,4)) - sage: phi = X.module_morphism(lt, triangular="lower", codomain=X) + sage: phi = X.module_morphism(lt, triangular='lower', codomain=X) sage: phi(x[2]) 2*B[2] + 3*B[3] sage: phi.preimage(x[2]) @@ -530,10 +527,10 @@ class TriangularModuleMorphism(ModuleMorphism): Using the ``key`` keyword, we can use triangularity even if the map becomes triangular only after a permutation of the basis:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() sage: def ut(i): return (x[1] + x[2] if i == 1 else x[2] + (x[3] if i == 3 else 0)) sage: perm = [0, 2, 1, 3] - sage: phi = X.module_morphism(ut, triangular="upper", codomain=X, + sage: phi = X.module_morphism(ut, triangular='upper', codomain=X, ....: key=lambda a: perm[a]) sage: [phi(x[i]) for i in range(1, 4)] [B[1] + B[2], B[2], B[2] + B[3]] @@ -543,7 +540,7 @@ class TriangularModuleMorphism(ModuleMorphism): The same works in the lower-triangular case:: sage: def lt(i): return (x[1] + x[2] + x[3] if i == 2 else x[i]) - sage: phi = X.module_morphism(lt, triangular="lower", codomain=X, + sage: phi = X.module_morphism(lt, triangular='lower', codomain=X, ....: key=lambda a: perm[a]) sage: [phi(x[i]) for i in range(1, 4)] [B[1], B[1] + B[2] + B[3], B[3]] @@ -557,7 +554,7 @@ class TriangularModuleMorphism(ModuleMorphism): sage: X = CombinatorialFreeModule(QQ, [1,2,3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4,5]); y = Y.basis() sage: ult = lambda i: sum( y[j] for j in range(i+1,6) ) - sage: phi = X.module_morphism(ult, unitriangular="lower", codomain=Y, + sage: phi = X.module_morphism(ult, unitriangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi(x[2]) B[3] + B[4] + B[5] @@ -569,13 +566,13 @@ class TriangularModuleMorphism(ModuleMorphism): them has to be permuted in order to render the morphism triangular. For example:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() sage: def ut(i): ....: return (x[3] if i == 1 else x[1] if i == 2 ....: else x[1] + x[2]) sage: def perm(i): ....: return (2 if i == 1 else 3 if i == 2 else 1) - sage: phi = X.module_morphism(ut, triangular="upper", codomain=X, + sage: phi = X.module_morphism(ut, triangular='upper', codomain=X, ....: inverse_on_support=perm) sage: [phi(x[i]) for i in range(1, 4)] [B[3], B[1], B[1] + B[2]] @@ -584,13 +581,13 @@ class TriangularModuleMorphism(ModuleMorphism): The same works if the permutation induces lower triangularity:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() sage: def lt(i): ....: return (x[3] if i == 1 else x[2] if i == 2 ....: else x[1] + x[2]) sage: def perm(i): ....: return 4 - i - sage: phi = X.module_morphism(lt, triangular="lower", codomain=X, + sage: phi = X.module_morphism(lt, triangular='lower', codomain=X, ....: inverse_on_support=perm) sage: [phi(x[i]) for i in range(1, 4)] [B[3], B[2], B[1] + B[2]] @@ -603,8 +600,8 @@ class TriangularModuleMorphism(ModuleMorphism): sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3, 4]); y = Y.basis() sage: ut = lambda i: sum( y[j] for j in range(1,i+2) ) - sage: phi = X.module_morphism(ut, triangular="upper", codomain=Y, - ....: inverse_on_support="compute") + sage: phi = X.module_morphism(ut, triangular='upper', codomain=Y, + ....: inverse_on_support='compute') sage: tx = "{} {} {}" sage: for j in Y.basis().keys(): ....: i = phi._inverse_on_support(j) @@ -616,7 +613,7 @@ class TriangularModuleMorphism(ModuleMorphism): The ``inverse_on_basis`` and ``key`` keywords can be combined:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: x = X.basis() sage: def ut(i): ....: return (2*x[2] + 3*x[3] if i == 1 @@ -625,22 +622,22 @@ class TriangularModuleMorphism(ModuleMorphism): sage: def perm(i): ....: return (2 if i == 1 else 3 if i == 2 else 1) sage: perverse_key = lambda a: (a - 2) % 3 - sage: phi = X.module_morphism(ut, triangular="upper", codomain=X, + sage: phi = X.module_morphism(ut, triangular='upper', codomain=X, ....: inverse_on_support=perm, key=perverse_key) sage: [phi(x[i]) for i in range(1, 4)] [2*B[2] + 3*B[3], B[1] + B[2] + B[3], 4*B[2]] sage: [phi.preimage(x[i]) for i in range(1, 4)] [-1/3*B[1] + B[2] - 1/12*B[3], 1/4*B[3], 1/3*B[1] - 1/6*B[3]] """ - def __init__(self, triangular="upper", unitriangular=False, + def __init__(self, triangular='upper', unitriangular=False, key=None, inverse=None, inverse_on_support=identity, invertible=None): """ TESTS:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() sage: def lt(i): return sum(j*x[j] for j in range(i,4)) sage: import __main__; __main__.lt = lt # Fake lt being defined in a python module - sage: phi = X.module_morphism(lt, triangular="lower", codomain=X) + sage: phi = X.module_morphism(lt, triangular='lower', codomain=X) sage: phi.__class__ sage: phi._invertible @@ -649,14 +646,14 @@ def __init__(self, triangular="upper", unitriangular=False, With the option ``compute``:: - sage: phi = X.module_morphism(lt, triangular="lower", codomain=X, - ....: inverse_on_support="compute") + sage: phi = X.module_morphism(lt, triangular='lower', codomain=X, + ....: inverse_on_support='compute') sage: TestSuite(phi).run(skip=["_test_pickling"]) Pickling works in Python3 (:issue:`17957`):: - sage: phi = X.module_morphism(lt, triangular="lower", codomain=X, - ....: inverse_on_support="compute") + sage: phi = X.module_morphism(lt, triangular='lower', codomain=X, + ....: inverse_on_support='compute') sage: loads(dumps(phi)) Generic endomorphism of X sage: phi._inverse_on_support @@ -701,22 +698,21 @@ def _richcmp_(self, other, op): TESTS:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() sage: def ut(i): return (x[1] + x[2] if i == 1 else x[2] + (x[3] if i == 3 else 0)) sage: perm = [0, 2, 1, 3] sage: our_key = lambda a: perm[a] - sage: phi = X.module_morphism(ut, triangular="upper", codomain=X, key=our_key) + sage: phi = X.module_morphism(ut, triangular='upper', codomain=X, key=our_key) sage: def ut2(i): return (x[1] + 7*x[2] if i == 1 else x[2] + (x[3] if i == 3 else 0)) - sage: phi2 = X.module_morphism(ut2, triangular="upper", codomain=X, key=our_key) + sage: phi2 = X.module_morphism(ut2, triangular='upper', codomain=X, key=our_key) sage: def lt(i): return (x[1] + x[2] + x[3] if i == 2 else x[i]) - sage: psi = X.module_morphism(lt, triangular="lower", codomain=X, key=our_key) + sage: psi = X.module_morphism(lt, triangular='lower', codomain=X, key=our_key) sage: phi == phi True sage: phi == phi2 False sage: phi == psi False - """ if op == op_EQ: return (self.__class__ is other.__class__ @@ -731,7 +727,7 @@ def _richcmp_(self, other, op): def _test_triangular(self, **options): """ - Test that ``self`` is actually triangular + Test that ``self`` is actually triangular. See also: :class:`sage.misc.sage_unittest.TestSuite`. @@ -740,11 +736,11 @@ def _test_triangular(self, **options): sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); y = Y.basis() sage: lt = lambda i: sum( y[j] for j in range(i,4) ) - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y) + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y) sage: phi._test_triangular() sage: lt = lambda i: sum( y[j] for j in range(i+1,4) ) - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y) + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y) sage: phi._test_triangular() Traceback (most recent call last): ... @@ -753,12 +749,12 @@ def _test_triangular(self, **options): sage: X = CombinatorialFreeModule(QQ, [1,2,3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4,5]); y = Y.basis() sage: ult = lambda i: sum( y[j] for j in range(i+1,6) ) - sage: phi = X.module_morphism(ult, unitriangular="lower", codomain=Y, + sage: phi = X.module_morphism(ult, unitriangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi._test_triangular() sage: ult = lambda i: sum( 2*y[j] for j in range(i+1,6) ) - sage: phi = X.module_morphism(ult, unitriangular="lower", codomain=Y, + sage: phi = X.module_morphism(ult, unitriangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi._test_triangular() Traceback (most recent call last): @@ -793,11 +789,11 @@ def __invert__(self): sage: ut = lambda i: sum(j*y[j] for j in range(1,i+1)) # upper sage: lt = lambda i: sum(j*y[j] for j in range(i,4 )) # lower sage: f_uut = X.module_morphism(uut, codomain=Y, - ....: unitriangular="upper") + ....: unitriangular='upper') sage: f_ult = X.module_morphism(ult, codomain=Y, - ....: unitriangular="lower") - sage: f_ut = X.module_morphism(ut, codomain=Y, triangular="upper") - sage: f_lt = X.module_morphism(lt, codomain=Y, triangular="lower") + ....: unitriangular='lower') + sage: f_ut = X.module_morphism(ut, codomain=Y, triangular='upper') + sage: f_lt = X.module_morphism(lt, codomain=Y, triangular='lower') sage: (~f_uut)(y[2]) -B[1] + B[2] sage: (~f_ult)(y[2]) @@ -819,7 +815,7 @@ def section(self): Return the section (partial inverse) of ``self``. This returns a partial triangular morphism which is a section of - ``self``. The section morphism raises a :class:`ValueError` if + ``self``. The section morphism raises a :exc:`ValueError` if asked to apply on an element which is not in the image of ``self``. EXAMPLES:: @@ -828,7 +824,7 @@ def section(self): sage: X.rename('X') sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4,5]); y = Y.basis() sage: ult = lambda i: sum( y[j] for j in range(i+1,6) ) # uni-lower - sage: phi = X.module_morphism(ult, triangular="lower", codomain=Y, + sage: phi = X.module_morphism(ult, triangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: ~phi Traceback (most recent call last): @@ -879,7 +875,7 @@ def _invert_on_basis(self, i): sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); y = Y.basis() sage: ult = lambda i: sum( y[j] for j in range(i,4) ) # uni-lower - sage: phi = X.module_morphism(ult, triangular="lower", codomain=Y) + sage: phi = X.module_morphism(ult, triangular='lower', codomain=Y) sage: phi._invert_on_basis(2) B[2] - B[3] """ @@ -894,7 +890,7 @@ def preimage(self, f): sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); y = Y.basis() sage: ult = lambda i: sum( y[j] for j in range(i,4) ) # uni-lower - sage: phi = X.module_morphism(ult, triangular="lower", codomain=Y) + sage: phi = X.module_morphism(ult, triangular='lower', codomain=Y) sage: phi.preimage(y[1] + y[2]) B[1] - B[3] @@ -904,7 +900,7 @@ def preimage(self, f): sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3, 4]); y = Y.basis() sage: lt = lambda i: sum( y[j] for j in range(i,5) ) - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y) + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y) sage: phi.preimage(y[1] + y[2]) B[1] - B[3] @@ -914,7 +910,7 @@ def preimage(self, f): sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3, 4, 5]); y = Y.basis() sage: lt = lambda i: sum( y[j] for j in range(i+1,6) ) # lower - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y, + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi(x[1]) B[2] + B[3] + B[4] + B[5] @@ -943,7 +939,7 @@ def preimage(self, f): sage: X = CombinatorialFreeModule(ZZ, [1, 2, 3]); x = X.basis() sage: Y = CombinatorialFreeModule(ZZ, [1, 2, 3]); y = Y.basis() sage: lt = lambda i: sum( 2* y[j] for j in range(i,4) ) # lower - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y) + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y) sage: phi.preimage(2*y[1] + 2*y[2]) B[1] - B[3] @@ -1006,7 +1002,7 @@ def coreduced(self, y): sage: X = CombinatorialFreeModule(QQ, [1,2,3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4,5]); y = Y.basis() sage: ult = lambda i: sum( y[j] for j in range(i+1,6) ) - sage: phi = X.module_morphism(ult, unitriangular="lower", codomain=Y, + sage: phi = X.module_morphism(ult, unitriangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: [phi(v) for v in X.basis()] [B[2] + B[3] + B[4] + B[5], @@ -1020,7 +1016,7 @@ def coreduced(self, y): Now with a non unitriangular morphism:: sage: lt = lambda i: sum( j*y[j] for j in range(i+1,6) ) - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y, + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: [phi(v) for v in X.basis()] [2*B[2] + 3*B[3] + 4*B[4] + 5*B[5], @@ -1036,14 +1032,14 @@ def coreduced(self, y): sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); x = X.basis() sage: Y = CombinatorialFreeModule(ZZ, [1,2,3,4,5]); y = Y.basis() - sage: phi = X.module_morphism(ult, unitriangular="lower", codomain=Y, + sage: phi = X.module_morphism(ult, unitriangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: [phi.coreduced(y[1]-2*y[4])] [B[1] + 2*B[5]] sage: [phi.coreduced(v) for v in y] [B[1], 0, 0, -B[5], B[5]] - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y, + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: [phi.coreduced(v) for v in y] Traceback (most recent call last): @@ -1105,12 +1101,12 @@ def cokernel_basis_indices(self): sage: X = CombinatorialFreeModule(ZZ, [1,2,3]); x = X.basis() sage: Y = CombinatorialFreeModule(ZZ, [1,2,3,4,5]); y = Y.basis() sage: uut = lambda i: sum( y[j] for j in range(i+1,6) ) # uni-upper - sage: phi = X.module_morphism(uut, unitriangular="upper", codomain=Y, + sage: phi = X.module_morphism(uut, unitriangular='upper', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi.cokernel_basis_indices() [1, 5] - sage: phi = X.module_morphism(uut, triangular="upper", codomain=Y, + sage: phi = X.module_morphism(uut, triangular='upper', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi.cokernel_basis_indices() Traceback (most recent call last): @@ -1118,7 +1114,7 @@ def cokernel_basis_indices(self): NotImplementedError: cokernel_basis_indices for a triangular but not unitriangular morphism over a ring sage: Y = CombinatorialFreeModule(ZZ, NN); y = Y.basis() - sage: phi = X.module_morphism(uut, unitriangular="upper", codomain=Y, + sage: phi = X.module_morphism(uut, unitriangular='upper', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phi.cokernel_basis_indices() Traceback (most recent call last): @@ -1145,7 +1141,7 @@ def cokernel_projection(self, category=None): sage: X = CombinatorialFreeModule(QQ, [1,2,3]); x = X.basis() sage: Y = CombinatorialFreeModule(QQ, [1,2,3,4,5]); y = Y.basis() sage: lt = lambda i: sum( y[j] for j in range(i+1,6) ) # lower - sage: phi = X.module_morphism(lt, triangular="lower", codomain=Y, + sage: phi = X.module_morphism(lt, triangular='lower', codomain=Y, ....: inverse_on_support=lambda i: i-1 if i in [2,3,4] else None) sage: phipro = phi.cokernel_projection() sage: phipro(y[1] + y[2]) @@ -1265,7 +1261,7 @@ class ModuleMorphismFromMatrix(ModuleMorphismByLinearity): - ``matrix`` -- a matrix with base ring `R` and dimensions matching that of `F` and `G`, respectively - - ``side`` -- "left" or "right" (default: "left") + - ``side`` -- ``'left'`` or ``'right'`` (default: ``'left'``) If ``side`` is "left", this morphism is considered as acting on the left; i.e. each column of the matrix @@ -1276,8 +1272,8 @@ class ModuleMorphismFromMatrix(ModuleMorphismByLinearity): EXAMPLES:: - sage: X = CombinatorialFreeModule(ZZ, [1,2]); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(ZZ, [1,2]); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename('Y'); y = Y.basis() sage: m = matrix([[1,2],[3,5]]) sage: phi = X.module_morphism(matrix=m, codomain=Y) sage: phi.parent() @@ -1290,7 +1286,7 @@ class ModuleMorphismFromMatrix(ModuleMorphismByLinearity): 2*B[3] + 5*B[4] sage: m = matrix([[1,2],[3,5]]) - sage: phi = X.module_morphism(matrix=m, codomain=Y, side="right", + sage: phi = X.module_morphism(matrix=m, codomain=Y, side='right', ....: category=Modules(ZZ).WithBasis()) sage: phi.parent() Set of Morphisms from X to Y @@ -1305,20 +1301,20 @@ class ModuleMorphismFromMatrix(ModuleMorphismByLinearity): Possibly implement rank, addition, multiplication, matrix, etc, from the stored matrix. """ - def __init__(self, domain, matrix, codomain=None, category=None, side="left"): + def __init__(self, domain, matrix, codomain=None, category=None, side='left'): r""" Initialize ``self``. TESTS:: sage: from sage.modules.with_basis.morphism import ModuleMorphismFromMatrix - sage: X = CombinatorialFreeModule(ZZ, [1,2]); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(ZZ, [1,2]); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename('Y'); y = Y.basis() sage: m = matrix([[1,2],[3,5]]) - sage: phi = ModuleMorphismFromMatrix(matrix=m, domain=X, codomain=Y, side="right") + sage: phi = ModuleMorphismFromMatrix(matrix=m, domain=X, codomain=Y, side='right') sage: phi.__class__ - sage: phi.matrix(side="right") == m + sage: phi.matrix(side='right') == m True sage: TestSuite(phi).run(skip=["_test_pickling"]) @@ -1336,7 +1332,7 @@ def __init__(self, domain, matrix, codomain=None, category=None, side="left"): [1 2] [3 5] - sage: phi = ModuleMorphismFromMatrix(matrix=m, side="left", + sage: phi = ModuleMorphismFromMatrix(matrix=m, side='left', ....: domain=X, codomain=Y) sage: phi._matrix [1 3] @@ -1377,17 +1373,17 @@ def _richcmp_(self, other, op): TESTS:: sage: from sage.modules.with_basis.morphism import ModuleMorphismFromMatrix - sage: X = CombinatorialFreeModule(ZZ, [1,2]); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(ZZ, [1,2]); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(ZZ, [3,4]); Y.rename('Y'); y = Y.basis() sage: m = matrix([[1,2],[3,5]]) - sage: phi = ModuleMorphismFromMatrix(matrix=m, domain=X, codomain=Y, side="right") - sage: phi2 = ModuleMorphismFromMatrix(matrix=m, domain=X, codomain=Y, side="right") + sage: phi = ModuleMorphismFromMatrix(matrix=m, domain=X, codomain=Y, side='right') + sage: phi2 = ModuleMorphismFromMatrix(matrix=m, domain=X, codomain=Y, side='right') sage: phi == phi2 True sage: phi is phi2 False sage: m2 = matrix([[1,2],[4,5]]) - sage: phi2 = ModuleMorphismFromMatrix(matrix=m2, domain=X, codomain=Y, side="right") + sage: phi2 = ModuleMorphismFromMatrix(matrix=m2, domain=X, codomain=Y, side='right') sage: phi == phi2 False """ @@ -1435,7 +1431,7 @@ class DiagonalModuleMorphism(ModuleMorphismByLinearity): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: phi = X.module_morphism(diagonal=factorial, codomain=X) sage: x = X.basis() sage: phi(x[1]), phi(x[2]), phi(x[3]) @@ -1447,7 +1443,7 @@ def __init__(self, domain, diagonal, codomain=None, category=None): TESTS:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: phi = X.module_morphism(diagonal=factorial, codomain=X) sage: phi.__class__ @@ -1474,14 +1470,13 @@ def _richcmp_(self, other, op): TESTS:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X") + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X') sage: phi = X.module_morphism(diagonal=factorial, codomain=X) sage: psi = X.module_morphism(diagonal=factorial, codomain=X) sage: phi == psi True sage: phi is psi False - """ if op == op_EQ: return (self.__class__ is other.__class__ @@ -1496,8 +1491,8 @@ def _on_basis(self, i): TESTS:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); Y.rename('Y'); y = Y.basis() sage: phi = X.module_morphism(diagonal=factorial, codomain=X) sage: phi._on_basis(3) 6*B[3] @@ -1510,8 +1505,8 @@ def __invert__(self): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename("X"); x = X.basis() - sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); Y.rename("Y"); y = Y.basis() + sage: X = CombinatorialFreeModule(QQ, [1, 2, 3]); X.rename('X'); x = X.basis() + sage: Y = CombinatorialFreeModule(QQ, [1, 2, 3]); Y.rename('Y'); y = Y.basis() sage: phi = X.module_morphism(diagonal=factorial, codomain=X) sage: phi_inv = ~phi sage: phi_inv diff --git a/src/sage/modules/with_basis/representation.py b/src/sage/modules/with_basis/representation.py index b7d09675a05..aff13bf2473 100644 --- a/src/sage/modules/with_basis/representation.py +++ b/src/sage/modules/with_basis/representation.py @@ -34,8 +34,8 @@ class Representation_abstract: INPUT: - ``semigroup`` -- a semigroup - - ``side`` -- (default: ``"left"``) whether this is a - ``"left"`` or ``"right"`` representation + - ``side`` -- (default: ``'left'``) whether this is a + ``'left'`` or ``'right'`` representation - ``algebra`` -- (default: ``semigroup.algebra(self.base_ring())``) the semigroup algebra @@ -125,9 +125,7 @@ def side(self): """ Return whether ``self`` is a left, right, or two-sided representation. - OUTPUT: - - - the string ``"left"``, ``"right"``, or ``"twosided"`` + OUTPUT: the string ``'left'``, ``'right'``, or ``'twosided'`` EXAMPLES:: @@ -135,7 +133,7 @@ def side(self): sage: R = G.regular_representation() sage: R.side() 'left' - sage: S = G.regular_representation(side="right") + sage: S = G.regular_representation(side='right') sage: S.side() 'right' sage: R = G.sign_representation() @@ -171,9 +169,7 @@ def invariant_module(self, S=None, **kwargs): Two sided actions are considered as left actions for the invariant module. - OUTPUT: - - - :class:`~sage.modules.with_basis.invariant.FiniteDimensionalInvariantModule` + OUTPUT: :class:`~sage.modules.with_basis.invariant.FiniteDimensionalInvariantModule` EXAMPLES:: @@ -214,16 +210,14 @@ def twisted_invariant_module(self, chi, G=None, **kwargs): INPUT: - - ``chi`` -- a list/tuple of character values or an instance + - ``chi`` -- list/tuple of character values or an instance of :class:`~sage.groups.class_function.ClassFunction_gap` - ``G`` -- a finitely-generated semigroup (default: the semigroup this is a representation of) This also accepts the first argument to be the group. - OUTPUT: - - - :class:`~sage.modules.with_basis.invariant.FiniteDimensionalTwistedInvariantModule` + OUTPUT: :class:`~sage.modules.with_basis.invariant.FiniteDimensionalTwistedInvariantModule` EXAMPLES:: @@ -262,8 +256,8 @@ def representation_matrix(self, g, side=None, sparse=False): sage: S3 = SymmetricGroup(3) sage: g = S3.an_element(); g (2,3) - sage: L = S3.regular_representation(side="left") - sage: R = S3.regular_representation(side="right") + sage: L = S3.regular_representation(side='left') + sage: R = S3.regular_representation(side='right') sage: R.representation_matrix(g) [0 0 0 1 0 0] [0 0 0 0 0 1] @@ -431,7 +425,7 @@ def brauer_character(self): sage: T.brauer_character() (0, 0, 0) - sage: W = CoxeterGroup(['D', 4], implementation="permutation") + sage: W = CoxeterGroup(['D', 4], implementation='permutation') sage: R = W.reflection_representation(GF(2)) sage: R.brauer_character() (4, 1) @@ -676,8 +670,8 @@ def subrepresentation(self, gens, check=True, already_echelonized=False, - ``gens`` -- the generators of the submodule - ``check`` -- ignored - ``already_echelonized`` -- (default: ``False``) whether - the elements of ``gens`` are already in (not necessarily - reduced) echelon form + the elements of ``gens`` are already in (not necessarily + reduced) echelon form - ``is_closed`` -- (keyword only; default: ``False``) whether ``gens`` already spans the subspace closed under the semigroup action @@ -841,10 +835,10 @@ def _composition_series_data(self): data = {i: lift(prev._basis[i]) for i in prev._basis.keys()} lift = prev.module_morphism(data.__getitem__, codomain=self, - triangular="lower", + triangular='lower', unitriangular=False, key=W._support_key, - inverse_on_support="compute") + inverse_on_support='compute') retract = lift.section() ret.append(ret[-1].subrepresentation([], is_closed=True)) @@ -960,7 +954,7 @@ def _acted_upon_(self, scalar, self_on_left=False): s2*s1*s2 + 2*s1*s2 + s2 + 3 sage: G = groups.misc.WeylGroup(['B',2], prefix='s') - sage: R = G.regular_representation(side="right") + sage: R = G.regular_representation(side='right') sage: s1,s2 = G.gens() sage: x = R.an_element(); x 2*s2*s1*s2 + s1*s2 + 3*s2 + 1 @@ -1052,8 +1046,8 @@ class Representation(Representation_abstract, CombinatorialFreeModule): ``g`` is an element of the semigroup and ``m`` is an element of the indexing set for the basis, and returns the result of ``g`` acting on ``m`` - - ``side`` -- (default: ``"left"``) whether this is a - ``"left"`` or ``"right"`` representation + - ``side`` -- (default: ``'left'``) whether this is a + ``'left'`` or ``'right'`` representation EXAMPLES: @@ -1098,7 +1092,7 @@ class Representation(Representation_abstract, CombinatorialFreeModule): - :wikipedia:`Group_representation` """ - def __init__(self, semigroup, module, on_basis, side="left", **kwargs): + def __init__(self, semigroup, module, on_basis, side='left', **kwargs): """ Initialize ``self``. @@ -1184,7 +1178,7 @@ def _test_representation(self, **options): sage: M = CombinatorialFreeModule(QQ, ['v']) sage: def on_basis(g, m): ....: return M.term(m, (-1)**g.length()) - sage: R = G.representation(M, on_basis, side="right") + sage: R = G.representation(M, on_basis, side='right') sage: R._test_representation(max_runs=500) """ from sage.misc.functional import sqrt @@ -1527,8 +1521,8 @@ def _semigroup_action(self, g, vec, vec_on_left): EXAMPLES:: sage: S3 = SymmetricGroup(3) - sage: L = S3.regular_representation(side="left") - sage: R = S3.regular_representation(side="right") + sage: L = S3.regular_representation(side='left') + sage: R = S3.regular_representation(side='right') sage: T = tensor([R, L]) sage: g = S3.an_element(); g (2,3) @@ -1564,14 +1558,14 @@ def __init__(self, rep, degree=None, category=None, **options): EXAMPLES:: sage: G = groups.matrix.GL(3, 2) - sage: R = G.regular_representation(side="right") + sage: R = G.regular_representation(side='right') sage: E2 = R.exterior_power(2) sage: E2.category() Category of finite dimensional modules with basis over Integer Ring sage: TestSuite(E2).run() sage: G = groups.matrix.GL(2, 3) - sage: L = G.regular_representation(side="left") + sage: L = G.regular_representation(side='left') sage: E48 = L.exterior_power(48) sage: TestSuite(E48).run() @@ -1732,7 +1726,7 @@ def _from_repr_to_ext(self, elt): EXAMPLES:: sage: G = groups.matrix.GL(2, 2) - sage: L = G.regular_representation(side="left") + sage: L = G.regular_representation(side='left') sage: E = L.exterior_power() sage: E._from_repr_to_ext(sum(i*b for i,b in enumerate(L.basis(), start=1))) e0 + 2*e1 + 3*e2 + 4*e3 + 5*e4 + 6*e5 @@ -1751,7 +1745,7 @@ def _semigroup_action(self, g, vec, vec_on_left): sage: DC3 = groups.permutation.DiCyclic(3) sage: g = DC3.an_element(); g (1,4,2,3)(5,6) - sage: R = DC3.regular_representation(side="right") + sage: R = DC3.regular_representation(side='right') sage: E2 = R.exterior_power(2) sage: vec = E2.an_element(); vec 2*()*(5,6,7) + 2*()*(5,7,6) + 3*()*(1,2)(3,4) @@ -1774,7 +1768,7 @@ def _action_on_basis(self, g, b, vec_on_left): sage: S3 = SymmetricGroup(3) sage: g = S3.an_element(); g (2,3) - sage: L = S3.regular_representation(side="left") + sage: L = S3.regular_representation(side='left') sage: E2 = L.exterior_power(2) sage: vec = E2.an_element(); vec 2*()*(1,3,2) + 2*()*(1,2,3) + 3*()*(2,3) @@ -1810,14 +1804,14 @@ def __init__(self, rep, degree=None, category=None, **options): EXAMPLES:: sage: G = groups.matrix.GL(3, 2) - sage: R = G.regular_representation(side="right") + sage: R = G.regular_representation(side='right') sage: E0 = R.exterior_power(0) sage: E0.category() Category of finite dimensional algebras with basis over Integer Ring sage: TestSuite(E0).run() sage: G = groups.matrix.GL(2, 3) - sage: L = G.regular_representation(side="left") + sage: L = G.regular_representation(side='left') sage: E = L.exterior_power() sage: E.category() Category of finite dimensional algebras with basis over Integer Ring @@ -1836,7 +1830,7 @@ def one_basis(self): EXAMPLES:: sage: S3 = SymmetricGroup(3) - sage: L = S3.regular_representation(side="left") + sage: L = S3.regular_representation(side='left') sage: E = L.exterior_power() sage: E.one_basis() 0 @@ -1853,7 +1847,7 @@ def product_on_basis(self, x, y): EXAMPLES:: sage: S3 = SymmetricGroup(3) - sage: L = S3.regular_representation(side="left") + sage: L = S3.regular_representation(side='left') sage: E = L.exterior_power() sage: B = list(E.basis()) sage: B[:7] @@ -1877,7 +1871,7 @@ def __init__(self, rep, degree, **options): EXAMPLES:: sage: G = groups.matrix.GL(3, 2) - sage: R = G.regular_representation(side="right") + sage: R = G.regular_representation(side='right') sage: S2 = R.symmetric_power(2) sage: TestSuite(S2).run() sage: S0 = R.symmetric_power(0) @@ -2063,7 +2057,7 @@ def _from_repr_to_sym(self, elt): EXAMPLES:: sage: G = groups.matrix.GL(2, 2) - sage: L = G.regular_representation(side="left") + sage: L = G.regular_representation(side='left') sage: S3L = L.symmetric_power(3) sage: S3L._from_repr_to_sym(sum(i*b for i,b in enumerate(L.basis(), start=1))) e0 + 2*e1 + 3*e2 + 4*e3 + 5*e4 + 6*e5 @@ -2081,7 +2075,7 @@ def _semigroup_action(self, g, vec, vec_on_left): sage: DC3 = groups.permutation.DiCyclic(3) sage: g = DC3.an_element(); g (1,4,2,3)(5,6) - sage: R = DC3.regular_representation(side="right") + sage: R = DC3.regular_representation(side='right') sage: S2L = R.symmetric_power(2) sage: vec = S2L.an_element(); vec 3*()*(5,7,6) + 2*()*(5,6,7) + 2*()^2 @@ -2104,7 +2098,7 @@ def _action_on_basis(self, g, b, vec_on_left): sage: S3 = SymmetricGroup(3) sage: g = S3.an_element(); g (2,3) - sage: L = S3.regular_representation(side="left") + sage: L = S3.regular_representation(side='left') sage: S2L = L.symmetric_power(2) sage: vec = S2L.an_element(); vec 3*()*(1,2,3) + 2*()*(1,3,2) + 2*()^2 @@ -2144,14 +2138,14 @@ class RegularRepresentation(Representation): - ``semigroup`` -- a semigroup - ``base_ring`` -- the base ring for the representation - - ``side`` -- (default: ``"left"``) whether this is a - ``"left"`` or ``"right"`` representation + - ``side`` -- (default: ``'left'``) whether this is a + ``'left'`` or ``'right'`` representation REFERENCES: - :wikipedia:`Regular_representation` """ - def __init__(self, semigroup, base_ring, side="left"): + def __init__(self, semigroup, base_ring, side='left'): """ Initialize ``self``. @@ -2178,7 +2172,7 @@ def _repr_(self): sage: G.regular_representation() Left Regular Representation of Dihedral group of order 8 as a permutation group over Integer Ring - sage: G.regular_representation(side="right") + sage: G.regular_representation(side='right') Right Regular Representation of Dihedral group of order 8 as a permutation group over Integer Ring """ @@ -2207,7 +2201,7 @@ def _right_on_basis(self, g, m): EXAMPLES:: sage: G = groups.permutation.Dihedral(4) - sage: R = G.regular_representation(side="right") + sage: R = G.regular_representation(side='right') sage: R._test_representation() # indirect doctest """ return self.monomial(m * g) diff --git a/src/sage/modules/with_basis/subquotient.py b/src/sage/modules/with_basis/subquotient.py index 48a235b4ab9..d914ba88f0c 100644 --- a/src/sage/modules/with_basis/subquotient.py +++ b/src/sage/modules/with_basis/subquotient.py @@ -89,7 +89,7 @@ def __init__(self, submodule, category, *args, **opts): TESTS:: sage: from sage.modules.with_basis.subquotient import QuotientModuleWithBasis - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: I = X.submodule( (x[0]-x[1], x[1]-x[2]) ) sage: Y = QuotientModuleWithBasis(I) sage: Y.print_options(prefix='y') @@ -115,7 +115,7 @@ def ambient(self): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: Y = X.quotient_module((x[0]-x[1], x[1]-x[2])) sage: Y.ambient() is X True @@ -132,7 +132,7 @@ def lift(self, x): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: Y = X.quotient_module((x[0]-x[1], x[1]-x[2])); y = Y.basis() sage: Y.lift(y[2]) x[2] @@ -150,7 +150,7 @@ def retract(self, x): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: Y = X.quotient_module((x[0]-x[1], x[1]-x[2])); y = Y.basis() sage: Y.print_options(prefix='y') sage: Y.retract(x[0]) @@ -231,7 +231,7 @@ def __init__(self, basis, support_order, ambient, unitriangular, category, TESTS:: sage: from sage.modules.with_basis.subquotient import SubmoduleWithBasis - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: ybas = (x[0]-x[1], x[1]-x[2]) sage: Y = SubmoduleWithBasis(ybas, [0, 1, 2], X) sage: Y.print_options(prefix='y') @@ -287,7 +287,7 @@ def lift(self): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: Y = X.submodule((x[0]-x[1], x[1]-x[2]), already_echelonized=True); y = Y.basis() sage: Y.lift Generic morphism: @@ -300,10 +300,10 @@ def lift(self): """ return self.module_morphism(self.lift_on_basis, codomain=self._ambient, - triangular="lower", + triangular='lower', unitriangular=self._unitriangular, key=self._support_key, - inverse_on_support="compute") + inverse_on_support='compute') @lazy_attribute def reduce(self): @@ -315,7 +315,7 @@ def reduce(self): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: Y = X.submodule((x[0]-x[1], x[1]-x[2]), already_echelonized=True) sage: Y.reduce Generic endomorphism of Free module generated by {0, 1, 2} over Rational Field @@ -338,7 +338,7 @@ def retract(self): EXAMPLES:: - sage: X = CombinatorialFreeModule(QQ, range(3), prefix="x"); x = X.basis() + sage: X = CombinatorialFreeModule(QQ, range(3), prefix='x'); x = X.basis() sage: Y = X.submodule((x[0]-x[1], x[1]-x[2]), already_echelonized=True) sage: Y.print_options(prefix='y') sage: Y.retract @@ -661,7 +661,7 @@ def subspace(self, gens, *args, **opts): INPUT: - - ``gens`` -- a list or family of elements of ``self`` + - ``gens`` -- list or family of elements of ``self`` For additional optional arguments, see :meth:`ModulesWithBasis.ParentMethods.submodule`. diff --git a/src/sage/monoids/automatic_semigroup.py b/src/sage/monoids/automatic_semigroup.py index 4f351d372ef..c4926239f8d 100644 --- a/src/sage/monoids/automatic_semigroup.py +++ b/src/sage/monoids/automatic_semigroup.py @@ -117,7 +117,7 @@ class AutomaticSemigroup(UniqueRepresentation, Parent): [1, 3, 5, 9] sage: # needs sage.graphs - sage: G = M.cayley_graph(side="twosided"); G + sage: G = M.cayley_graph(side='twosided'); G Looped multi-digraph on 4 vertices sage: G.edges(sort=True, key=str) [([1, 1], [1, 1], (2, 'left')), @@ -184,8 +184,8 @@ class AutomaticSemigroup(UniqueRepresentation, Parent): Let us construct and play with the 0-Hecke Monoid:: sage: # needs sage.graphs sage.modules - sage: W = WeylGroup(['A',4]); W.rename("W") - sage: ambient_monoid = FiniteSetMaps(W, action="right") + sage: W = WeylGroup(['A',4]); W.rename('W') + sage: ambient_monoid = FiniteSetMaps(W, action='right') sage: pi = W.simple_projections(length_increasing=True).map(ambient_monoid) sage: M = AutomaticSemigroup(pi, one=ambient_monoid.one()); M A submonoid of (Maps from W to itself) with 4 generators @@ -351,7 +351,7 @@ def __classcall_private__(cls, generators, ambient=None, one=None, mul=operator. def __init__(self, generators, ambient, one, mul, category): """ - Initializes this semigroup. + Initialize this semigroup. TESTS:: @@ -409,7 +409,7 @@ def _repr_(self): sage: AutomaticSemigroup(Family({1: R(3), 2: R(5)}), mul=operator.add, one=R.zero()) A semigroup with 2 generators - sage: S5 = SymmetricGroup(5); S5.rename("S5") # needs sage.groups + sage: S5 = SymmetricGroup(5); S5.rename('S5') # needs sage.groups sage: AutomaticSemigroup(Family({1: S5((1,2))}), # needs sage.groups ....: category=Groups().Finite().Subobjects()) A subgroup of (S5) with 1 generators @@ -429,9 +429,9 @@ def _repr_(self): return f"{typ}{of} with {len(self._generators)} generators" - def repr_element_method(self, style="ambient"): + def repr_element_method(self, style='ambient'): """ - Sets the representation of the elements of the monoid. + Set the representation of the elements of the monoid. INPUT: @@ -501,7 +501,7 @@ def retract(self, ambient_element, check=True): sage: # needs sage.groups sage: from sage.monoids.automatic_semigroup import AutomaticSemigroup - sage: S5 = SymmetricGroup(5); S5.rename("S5") + sage: S5 = SymmetricGroup(5); S5.rename('S5') sage: M = AutomaticSemigroup(Family({1:S5((1,2)), 2:S5((1,2,3,4))}), ....: one=S5.one()) sage: m = M.retract(S5((3,1))); m @@ -773,7 +773,7 @@ def from_reduced_word(self, l): INPUT: - - ``l`` -- a list of indices of the generators + - ``l`` -- list of indices of the generators .. NOTE:: @@ -804,9 +804,9 @@ def construct(self, up_to=None, n=None): INPUT: - - ``up_to`` -- an element of ``self`` or of the ambient semigroup. + - ``up_to`` -- an element of ``self`` or of the ambient semigroup - - ``n`` -- an integer or ``None`` (default: ``None``) + - ``n`` -- integer or ``None`` (default: ``None``) This construct all the elements of this semigroup, their reduced words, and the right Cayley graph. If `n` is @@ -818,8 +818,8 @@ def construct(self, up_to=None, n=None): sage: # needs sage.groups sage.modules sage: from sage.monoids.automatic_semigroup import AutomaticSemigroup - sage: W = WeylGroup(['A',3]); W.rename("W") - sage: ambient_monoid = FiniteSetMaps(W, action="right") + sage: W = WeylGroup(['A',3]); W.rename('W') + sage: ambient_monoid = FiniteSetMaps(W, action='right') sage: pi = W.simple_projections(length_increasing=True).map(ambient_monoid) sage: M = AutomaticSemigroup(pi, one=ambient_monoid.one()); M A submonoid of (Maps from W to itself) with 3 generators @@ -876,7 +876,7 @@ def reduced_word(self): r""" Return the length-lexicographic shortest word of ``self``. - OUTPUT: a list of indexes of the generators + OUTPUT: list of indexes of the generators Obtaining the reduced word requires having constructed the Cayley graph of the semigroup up to ``self``. If this is diff --git a/src/sage/monoids/free_abelian_monoid.py b/src/sage/monoids/free_abelian_monoid.py index 37564eb5c5e..907414e4291 100644 --- a/src/sage/monoids/free_abelian_monoid.py +++ b/src/sage/monoids/free_abelian_monoid.py @@ -71,11 +71,9 @@ class FreeAbelianMonoidFactory(UniqueFactory): INPUT: + - ``n`` -- integer - - ``n`` -- integer - - - ``names`` -- names of generators - + - ``names`` -- names of generators OUTPUT: free abelian monoid @@ -126,11 +124,9 @@ def FreeAbelianMonoid(index_set=None, names=None, **kwds): - ``index_set`` -- an indexing set for the generators; if an integer, then this becomes `\{0, 1, \ldots, n-1\}` - - ``names`` -- names of generators - - OUTPUT: + - ``names`` -- names of generators - A free abelian monoid. + OUTPUT: a free abelian monoid EXAMPLES:: @@ -163,7 +159,7 @@ def FreeAbelianMonoid(index_set=None, names=None, **kwds): def is_FreeAbelianMonoid(x): """ - Return True if `x` is a free abelian monoid. + Return ``True`` if `x` is a free abelian monoid. EXAMPLES:: @@ -231,7 +227,7 @@ def __call__(self, x): def __contains__(self, x): """ - Return True if `x` is an element of this abelian monoid. + Return ``True`` if `x` is an element of this abelian monoid. EXAMPLES:: diff --git a/src/sage/monoids/free_abelian_monoid_element.pyx b/src/sage/monoids/free_abelian_monoid_element.pyx index 9f66e83942d..1cd087584cf 100644 --- a/src/sage/monoids/free_abelian_monoid_element.pyx +++ b/src/sage/monoids/free_abelian_monoid_element.pyx @@ -47,7 +47,7 @@ def is_FreeAbelianMonoidElement(x): INPUT: - - ``x`` -- an object. + - ``x`` -- an object OUTPUT: diff --git a/src/sage/monoids/free_monoid.py b/src/sage/monoids/free_monoid.py index 3e8ed837cf8..9e8553184d1 100644 --- a/src/sage/monoids/free_monoid.py +++ b/src/sage/monoids/free_monoid.py @@ -85,12 +85,10 @@ class FreeMonoid(Monoid_class, UniqueRepresentation): - ``names`` -- names of generators - - ``commutative`` -- (default: ``False``) whether the free + - ``commutative`` -- boolean (default: ``False``); whether the free monoid is commutative or not - OUTPUT: - - A free monoid. + OUTPUT: a free monoid EXAMPLES:: diff --git a/src/sage/monoids/free_monoid_element.py b/src/sage/monoids/free_monoid_element.py index 099ce53239c..f378270fcfd 100644 --- a/src/sage/monoids/free_monoid_element.py +++ b/src/sage/monoids/free_monoid_element.py @@ -135,7 +135,7 @@ def _repr_(self): def _latex_(self) -> str: r""" - Return latex representation of self. + Return latex representation of ``self``. EXAMPLES:: diff --git a/src/sage/monoids/hecke_monoid.py b/src/sage/monoids/hecke_monoid.py index b76867d6e0d..bc25f9769a7 100644 --- a/src/sage/monoids/hecke_monoid.py +++ b/src/sage/monoids/hecke_monoid.py @@ -19,7 +19,7 @@ def HeckeMonoid(W): INPUT: - - `W` -- a finite Coxeter group + - ``W`` -- a finite Coxeter group Let `s_1,\ldots,s_n` be the simple reflections of `W`. The 0-Hecke monoid is the monoid generated by projections `\pi_1,\ldots,\pi_n` @@ -57,7 +57,7 @@ def HeckeMonoid(W): sage: H.cardinality() 24 """ - ambient_monoid = FiniteSetMaps(W, action="right") + ambient_monoid = FiniteSetMaps(W, action='right') pi = W.simple_projections(length_increasing=True).map(ambient_monoid) H = ambient_monoid.submonoid(pi) H.rename("0-Hecke monoid of the %s" % W) diff --git a/src/sage/monoids/indexed_free_monoid.py b/src/sage/monoids/indexed_free_monoid.py index a50aa7cdf12..69b67e260f7 100644 --- a/src/sage/monoids/indexed_free_monoid.py +++ b/src/sage/monoids/indexed_free_monoid.py @@ -205,7 +205,7 @@ def __iter__(self): def _richcmp_(self, other, op): r""" - Comparisons + Comparisons. TESTS:: @@ -271,7 +271,7 @@ def _richcmp_(self, other, op): def support(self): """ Return a list of the objects indexing ``self`` with - non-zero exponents. + nonzero exponents. EXAMPLES:: diff --git a/src/sage/monoids/string_monoid.py b/src/sage/monoids/string_monoid.py index 7aa51ad9776..61814c421c5 100644 --- a/src/sage/monoids/string_monoid.py +++ b/src/sage/monoids/string_monoid.py @@ -35,10 +35,10 @@ def __init__(self, n, alphabet=()): INPUT: - - ``n`` -- Integer + - ``n`` -- integer - - ``alphabet`` -- String or tuple whose characters or elements denote - the generators. + - ``alphabet`` -- string or tuple whose characters or elements denote + the generators EXAMPLES:: @@ -168,7 +168,7 @@ def __call__(self, x, check=True): Return ``x`` coerced into this free monoid. One can create a free binary string monoid element from a - Python string of 0's and 1's or list of integers. + Python string of 0s and 1s or list of integers. NOTE: Due to the ambiguity of the second generator '1' with the identity element '' of the monoid, the syntax S(1) is not @@ -288,7 +288,7 @@ def __call__(self, x, check=True): Return ``x`` coerced into this free monoid. One can create a free octal string monoid element from a - Python string of 0's to 7's or list of integers. + Python string of 0s to 7s or list of integers. EXAMPLES:: @@ -596,7 +596,7 @@ def __call__(self, x, check=True): else: raise TypeError("Argument x (= %s) is of the wrong type." % x) - def characteristic_frequency(self, table_name="beker_piper"): + def characteristic_frequency(self, table_name='beker_piper'): r""" Return a table of the characteristic frequency probability distribution of the English alphabet. In written English, various @@ -630,15 +630,15 @@ def characteristic_frequency(self, table_name="beker_piper"): INPUT: - - ``table_name`` -- (default ``"beker_piper"``) the table of + - ``table_name`` -- (default: ``'beker_piper'``) the table of characteristic frequency probability distribution to use. The following tables are supported: - - ``"beker_piper"`` -- the table of characteristic frequency + - ``'beker_piper'`` -- the table of characteristic frequency probability distribution by Beker and Piper [BP1982]_. This is the default table to use. - - ``"lewand"`` -- the table of characteristic frequency + - ``'lewand'`` -- the table of characteristic frequency probability distribution by Lewand as described on page 36 of [Lew2000]_. @@ -654,7 +654,7 @@ def characteristic_frequency(self, table_name="beker_piper"): Beker and Piper [BP1982]_:: sage: A = AlphabeticStrings() - sage: table = A.characteristic_frequency(table_name="beker_piper") + sage: table = A.characteristic_frequency(table_name='beker_piper') sage: sorted(table.items()) [('A', 0.0820000000000000), @@ -687,7 +687,7 @@ def characteristic_frequency(self, table_name="beker_piper"): The characteristic frequency probability distribution table of Lewand [Lew2000]_:: - sage: table = A.characteristic_frequency(table_name="lewand") + sage: table = A.characteristic_frequency(table_name='lewand') sage: sorted(table.items()) [('A', 0.0816700000000000), @@ -767,7 +767,7 @@ def characteristic_frequency(self, table_name="beker_piper"): Traceback (most recent call last): ... ValueError: Table name must be either 'beker_piper' or 'lewand'. - sage: table = A.characteristic_frequency(table_name="none") + sage: table = A.characteristic_frequency(table_name='none') Traceback (most recent call last): ... ValueError: Table name must be either 'beker_piper' or 'lewand'. diff --git a/src/sage/monoids/string_monoid_element.py b/src/sage/monoids/string_monoid_element.py index 02070b6b4a8..d7e06428e0f 100644 --- a/src/sage/monoids/string_monoid_element.py +++ b/src/sage/monoids/string_monoid_element.py @@ -30,8 +30,6 @@ def is_StringMonoidElement(x): - r""" - """ from sage.misc.superseded import deprecation deprecation(38280, "The function is_StringMonoidElement is deprecated; " @@ -40,8 +38,6 @@ def is_StringMonoidElement(x): def is_AlphabeticStringMonoidElement(x): - r""" - """ from sage.misc.superseded import deprecation deprecation(38280, "The function is_AlphabeticStringMonoidElement is deprecated; " @@ -52,8 +48,6 @@ def is_AlphabeticStringMonoidElement(x): def is_BinaryStringMonoidElement(x): - r""" - """ from sage.misc.superseded import deprecation deprecation(38280, "The function is_BinaryStringMonoidElement is deprecated; " @@ -64,8 +58,6 @@ def is_BinaryStringMonoidElement(x): def is_OctalStringMonoidElement(x): - r""" - """ from sage.misc.superseded import deprecation deprecation(38280, "The function is_OctalStringMonoidElement is deprecated; " @@ -76,8 +68,6 @@ def is_OctalStringMonoidElement(x): def is_HexadecimalStringMonoidElement(x): - r""" - """ from sage.misc.superseded import deprecation deprecation(38280, "The function is_HexadecimalStringMonoidElement is deprecated; " @@ -88,8 +78,6 @@ def is_HexadecimalStringMonoidElement(x): def is_Radix64StringMonoidElement(x): - r""" - """ from sage.misc.superseded import deprecation deprecation(38280, "The function is_Radix64StringMonoidElement is deprecated; " @@ -164,7 +152,7 @@ def _repr_(self): def _latex_(self): """ - Return latex representation of self. + Return latex representation of ``self``. EXAMPLES:: @@ -215,12 +203,12 @@ def __pow__(self, n): sage: x**(-1) Traceback (most recent call last): ... - IndexError: Argument n (= -1) must be non-negative. + IndexError: Argument n (= -1) must be nonnegative. """ if not isinstance(n, (int, Integer)): raise TypeError("Argument n (= %s) must be an integer." % n) if n < 0: - raise IndexError("Argument n (= %s) must be non-negative." % n) + raise IndexError("Argument n (= %s) must be nonnegative." % n) elif n == 0: return self.parent()('') elif n == 1: @@ -468,7 +456,7 @@ def frequency_distribution(self, length=1, prec=0): INPUT: - - ``length`` -- (default ``1``) if ``length=1`` then consider the + - ``length`` -- (default: ``1``) if ``length=1`` then consider the probability space of monogram frequency, i.e. probability distribution of single characters. If ``length=2`` then consider the probability space of digram frequency, i.e. probability @@ -476,7 +464,7 @@ def frequency_distribution(self, length=1, prec=0): supports the generation of probability spaces for monogram frequency (``length=1``) and digram frequency (``length=2``). - - ``prec`` -- (default ``0``) a non-negative integer representing + - ``prec`` -- (default: ``0``) a nonnegative integer representing the precision (in number of bits) of a floating-point number. The default value ``prec=0`` means that we use 53 bits to represent the mantissa of a floating-point number. For more information on diff --git a/src/sage/monoids/string_ops.py b/src/sage/monoids/string_ops.py index 500762cb3e5..304e908c16b 100644 --- a/src/sage/monoids/string_ops.py +++ b/src/sage/monoids/string_ops.py @@ -95,8 +95,8 @@ def coincidence_discriminant(S, n=2): """ INPUT: - A tuple of strings, e.g. produced as decimation of transposition - ciphertext, or a sample plaintext. + - ``S`` --tuple of strings; e.g. produced as decimation of transposition + ciphertext, or a sample plaintext OUTPUT: diff --git a/src/sage/monoids/trace_monoid.py b/src/sage/monoids/trace_monoid.py index df5a7d4bce9..6b72feca4b5 100644 --- a/src/sage/monoids/trace_monoid.py +++ b/src/sage/monoids/trace_monoid.py @@ -131,9 +131,7 @@ def lex_normal_form(self): r""" Return the lexicographic normal form of ``self``. - OUTPUT: - - A free monoid element. + OUTPUT: a free monoid element EXAMPLES:: @@ -153,9 +151,7 @@ def foata_normal_form(self): r""" Return the Foata normal form of ``self``. - OUTPUT: - - Tuple of free monoid elements. + OUTPUT: tuple of free monoid elements EXAMPLES:: @@ -186,9 +182,7 @@ def _flat_elements(self): r""" Return flatten list of generator numbers representing the trace. - OUTPUT: - - A list of generator indexes. + OUTPUT: list of generator indexes TESTS:: @@ -210,9 +204,7 @@ def dependence_graph(self): generators are connected by edges which direction depend on the generator position in the trace. - OUTPUT: - - Directed graph of generator indexes. + OUTPUT: directed graph of generator indexes EXAMPLES:: @@ -237,7 +229,7 @@ def dependence_graph(self): return DiGraph(graph) @cached_method - def hasse_diagram(self, algorithm="naive"): + def hasse_diagram(self, algorithm='naive'): r""" Return Hasse diagram of the trace. @@ -249,9 +241,7 @@ def hasse_diagram(self, algorithm="naive"): that will be used to compute Hasse diagram; there are two variants: ``'naive'`` and ``'min'``. - OUTPUT: - - Directed graph of generator indexes. + OUTPUT: directed graph of generator indexes .. SEEALSO:: @@ -290,9 +280,7 @@ def min_hasse_diagram(self): r""" Return Hasse diagram of the trace. - OUTPUT: - - Directed graph of generator indexes. + OUTPUT: directed graph of generator indexes .. SEEALSO:: @@ -348,9 +336,7 @@ def naive_hasse_diagram(self): In loop check for every two pair of edges if they have common vertex, remove their transitive edge. - OUTPUT: - - Directed graph of generator indexes. + OUTPUT: directed graph of generator indexes .. SEEALSO:: @@ -381,9 +367,7 @@ def alphabet(self): r""" Return alphabet of ``self``. - OUTPUT: - - A set of free monoid generators. + OUTPUT: a set of free monoid generators EXAMPLES:: @@ -405,9 +389,7 @@ def projection(self, letters): - ``letters`` -- set of generators; defines set of letters that will be used to filter the trace - OUTPUT: - - A trace + OUTPUT: a trace EXAMPLES:: @@ -611,9 +593,7 @@ def _compute_dependence_stack(self, x): Return generator stacks formed from trace subelements with respect to non-commutativity. - OUTPUT: - - Used generators and list of stacks as tuple. + OUTPUT: used generators and list of stacks as tuple ALGORITHM: @@ -654,9 +634,7 @@ def _compute_lex_normal_form(self, x): Return lexicographic normal form of the free monoid element in free monoid terms. - OUTPUT: - - Trace monoid element. + OUTPUT: trace monoid element ALGORITHM: @@ -770,7 +748,7 @@ def independence(self): r""" Return independence relation over the monoid. - OUTPUT: set of commuting generator pairs. + OUTPUT: set of commuting generator pairs EXAMPLES:: @@ -788,9 +766,7 @@ def dependence(self): r""" Return dependence relation over the monoid. - OUTPUT: - - Set of non-commuting generator pairs. + OUTPUT: set of non-commuting generator pairs EXAMPLES:: @@ -819,7 +795,7 @@ def dependence_graph(self): """ return Graph({frozenset((e1, e2)) if e1 != e2 else (e1, e2) for e1, e2 in self.dependence()}, loops=True, - format="list_of_edges", + format='list_of_edges', immutable=True) @cached_method @@ -827,9 +803,7 @@ def independence_graph(self): r""" Return the digraph of independence relations. - OUTPUT: - - Independence graph with generators as vertices. + OUTPUT: independence graph with generators as vertices TESTS:: @@ -852,9 +826,7 @@ def dependence_polynomial(self, t=None): where `c_i` equals to number of full subgraphs of size `i` in the independence graph. - OUTPUT: - - A rational function in ``t`` with coefficients in the integer ring. + OUTPUT: a rational function in ``t`` with coefficients in the integer ring EXAMPLES:: @@ -948,7 +920,7 @@ def _sorted_independence(self): r""" Return independence relation over the monoid. - OUTPUT: sorted list of sorted commuting generator pairs. + OUTPUT: sorted list of sorted commuting generator pairs EXAMPLES:: diff --git a/src/sage/numerical/backends/cvxopt_backend.pyx b/src/sage/numerical/backends/cvxopt_backend.pyx index 23a3fcb014c..4c51803b5f9 100644 --- a/src/sage/numerical/backends/cvxopt_backend.pyx +++ b/src/sage/numerical/backends/cvxopt_backend.pyx @@ -30,7 +30,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="CVXOPT") + sage: p = MixedIntegerLinearProgram(solver='CVXOPT') TESTS: @@ -57,13 +57,12 @@ cdef class CVXOPTBackend(GenericBackend): def __cinit__(self, maximization = True): """ - Cython constructor + Cython constructor. EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") - + sage: p = get_solver(solver='CVXOPT') """ self.objective_function = [] #c_matrix in the example for cvxopt @@ -96,12 +95,12 @@ cdef class CVXOPTBackend(GenericBackend): # Added a second inequality to this doctest, # because otherwise CVXOPT complains: ValueError: Rank(A) < p or Rank([G; A]) < n """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = MixedIntegerLinearProgram(solver="CVXOPT") + sage: p = MixedIntegerLinearProgram(solver='CVXOPT') sage: b = p.new_variable() sage: p.add_constraint(b[1] + b[2] <= 6) sage: p.add_constraint(b[2] <= 5) @@ -145,22 +144,22 @@ cdef class CVXOPTBackend(GenericBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integer (default: ``False``). + - ``integer`` -- ``True`` if the variable is integer (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.ncols() 0 sage: p.add_variable() @@ -211,7 +210,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="cvxopt") + sage: p = get_solver(solver='cvxopt') sage: p.add_variables(5) 4 sage: p.set_variable_type(3, -1) @@ -229,7 +228,7 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``sense`` (integer): + - ``sense`` -- integer: * `+1` => Maximization * `-1` => Minimization @@ -237,7 +236,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.is_maximization() True sage: p.set_sense(-1) @@ -256,14 +255,14 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient + - ``coeff`` -- double; its coefficient EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variable() 0 sage: p.objective_coefficient(0) @@ -283,15 +282,16 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variables(5) 4 sage: p.set_objective([1, 1, 2, 1, 3]) @@ -304,7 +304,7 @@ cdef class CVXOPTBackend(GenericBackend): cpdef set_verbosity(self, int level): """ - Does not apply for the cvxopt solver + Do not apply for the cvxopt solver. """ pass @@ -314,15 +314,15 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it - appears. Namely, the ith entry of ``coeffs`` corresponds to + appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint - represented by the ith entry in ``indices``. + represented by the i-th entry in ``indices``. .. NOTE:: @@ -332,7 +332,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.ncols() 0 sage: p.nrows() @@ -375,7 +375,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variables(5) 4 sage: p.add_linear_constraint(zip(range(5), range(5)), 2.0, 2.0) @@ -412,7 +412,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="cvxopt", maximization=False) + sage: p = MixedIntegerLinearProgram(solver='cvxopt', maximization=False) sage: x = p.new_variable(nonnegative=True) sage: p.set_objective(-4*x[0] - 5*x[1]) sage: p.add_constraint(2*x[0] + x[1] <= 3) @@ -420,7 +420,7 @@ cdef class CVXOPTBackend(GenericBackend): sage: N(p.solve(), digits=2) -9.0 - sage: p = MixedIntegerLinearProgram(solver="cvxopt", maximization=False) + sage: p = MixedIntegerLinearProgram(solver='cvxopt', maximization=False) sage: x = p.new_variable(nonnegative=True) sage: p.set_objective(x[0] + 2*x[1]) sage: p.add_constraint(-5*x[0] + x[1] <= 7) @@ -431,7 +431,7 @@ cdef class CVXOPTBackend(GenericBackend): sage: N(p.solve(), digits=4) 48.83 - sage: p = MixedIntegerLinearProgram(solver="cvxopt") + sage: p = MixedIntegerLinearProgram(solver='cvxopt') sage: x = p.new_variable(nonnegative=True) sage: p.set_objective(x[0] + x[1] + 3*x[2]) sage: p.solver_parameter("show_progress",True) @@ -450,8 +450,8 @@ cdef class CVXOPTBackend(GenericBackend): gives the center point of the top face, whereas the other tested solvers return a vertex:: - sage: c = MixedIntegerLinearProgram(solver="cvxopt") - sage: p = MixedIntegerLinearProgram(solver="ppl") + sage: c = MixedIntegerLinearProgram(solver='cvxopt') + sage: p = MixedIntegerLinearProgram(solver='ppl') sage: g = MixedIntegerLinearProgram() sage: xc = c.new_variable(nonnegative=True) sage: xp = p.new_variable(nonnegative=True) @@ -571,7 +571,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="cvxopt") + sage: p = get_solver(solver='cvxopt') sage: p.add_variables(2) 1 sage: p.add_linear_constraint([(0,1), (1,2)], None, 3) @@ -603,7 +603,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variables(2) 1 sage: p.add_linear_constraint([(0,1), (1, 2)], None, 3) @@ -626,7 +626,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.ncols() 0 sage: p.add_variables(2) @@ -644,7 +644,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.nrows() 0 sage: p.add_variables(5) @@ -662,7 +662,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.is_maximization() True sage: p.set_sense(-1) @@ -676,17 +676,17 @@ cdef class CVXOPTBackend(GenericBackend): cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.problem_name() '' sage: p.problem_name("There once was a french fry") @@ -699,11 +699,11 @@ cdef class CVXOPTBackend(GenericBackend): cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -715,7 +715,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variables(5) 4 sage: p.add_linear_constraint(list(zip(range(5), range(5))), 2, 2) @@ -740,7 +740,7 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -751,7 +751,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variables(5) 4 sage: p.add_linear_constraint(list(zip(range(5), range(5))), 2, 2) @@ -768,7 +768,7 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -779,7 +779,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variable() 0 sage: p.col_bounds(0) @@ -797,12 +797,12 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.ncols() 0 sage: p.add_variable() @@ -813,7 +813,6 @@ cdef class CVXOPTBackend(GenericBackend): ValueError: ... sage: p.is_variable_binary(0) False - """ return False @@ -824,12 +823,12 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.ncols() 0 sage: p.add_variable() @@ -851,12 +850,12 @@ cdef class CVXOPTBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.ncols() 0 sage: p.add_variable() @@ -869,22 +868,21 @@ cdef class CVXOPTBackend(GenericBackend): ValueError: ... sage: p.is_variable_continuous(0) True - """ return True cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_linear_constraints(1, 2, None, names=["Empty constraint 1"]) sage: p.row_name(0) 'Empty constraint 1' @@ -895,19 +893,19 @@ cdef class CVXOPTBackend(GenericBackend): cpdef col_name(self, int index): """ - Return the ``index`` th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variable(name="I am a variable") 0 sage: p.col_name(0) @@ -919,11 +917,11 @@ cdef class CVXOPTBackend(GenericBackend): cpdef variable_upper_bound(self, int index, value = False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``False`` @@ -932,7 +930,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variable() 0 sage: p.col_bounds(0) @@ -948,11 +946,11 @@ cdef class CVXOPTBackend(GenericBackend): cpdef variable_lower_bound(self, int index, value = False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not lower bound. When set to ``False`` @@ -961,7 +959,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.add_variable() 0 sage: p.col_bounds(0) @@ -977,14 +975,14 @@ cdef class CVXOPTBackend(GenericBackend): cpdef solver_parameter(self, name, value = None): """ - Return or define a solver parameter + Return or define a solver parameter. INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value .. NOTE:: @@ -994,7 +992,7 @@ cdef class CVXOPTBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.solver_parameter("show_progress") False sage: p.solver_parameter("show_progress", True) diff --git a/src/sage/numerical/backends/cvxopt_sdp_backend.pyx b/src/sage/numerical/backends/cvxopt_sdp_backend.pyx index 1aec0b3c502..c6addca8996 100644 --- a/src/sage/numerical/backends/cvxopt_sdp_backend.pyx +++ b/src/sage/numerical/backends/cvxopt_sdp_backend.pyx @@ -31,13 +31,12 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): def __init__(self, maximization=True, base_ring=None): """ - Cython constructor + Cython constructor. EXAMPLES:: sage: from sage.numerical.backends.generic_sdp_backend import get_solver - sage: p = get_solver(solver="CVXOPT") - + sage: p = get_solver(solver='CVXOPT') """ from sage.rings.real_double import RDF @@ -67,7 +66,7 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): EXAMPLES:: - sage: p = SemidefiniteProgram(solver="cvxopt", maximization=False) + sage: p = SemidefiniteProgram(solver='cvxopt', maximization=False) sage: x = p.new_variable() sage: p.set_objective(x[0] - x[1] + x[2]) sage: a1 = matrix([[-7., -11.], [-11., 3.]]) @@ -82,7 +81,7 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): sage: p.add_constraint(b1*x[0] + b2*x[1] + b3*x[2] <= b4) sage: N(p.solve(), digits=4) -3.225 - sage: p = SemidefiniteProgram(solver="cvxopt", maximization=False) + sage: p = SemidefiniteProgram(solver='cvxopt', maximization=False) sage: x = p.new_variable() sage: p.set_objective(x[0] - x[1] + x[2]) sage: a1 = matrix([[-7., -11.], [-11., 3.]]) @@ -97,7 +96,6 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): sage: p.add_constraint(b1*x[0] + b2*x[1] + b3*x[2] <= b4) sage: N(p.solve(), digits=4) -3.154 - """ from cvxopt import matrix as c_matrix, solvers from sage.rings.real_double import RDF @@ -169,7 +167,7 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): EXAMPLES:: - sage: p = SemidefiniteProgram(solver="cvxopt", maximization=False) + sage: p = SemidefiniteProgram(solver='cvxopt', maximization=False) sage: x = p.new_variable() sage: p.set_objective(x[0] - x[1] + x[2]) sage: a1 = matrix([[-7., -11.], [-11., 3.]]) @@ -196,7 +194,7 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): cpdef _get_answer(self): """ - return the complete output dict of the solver + Return the complete output dict of the solver. Mainly for testing purposes @@ -230,7 +228,7 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): EXAMPLES:: - sage: p = SemidefiniteProgram(solver="cvxopt", maximization=False) + sage: p = SemidefiniteProgram(solver='cvxopt', maximization=False) sage: x = p.new_variable() sage: p.set_objective(x[0] - x[1] + x[2]) sage: a1 = matrix([[-7., -11.], [-11., 3.]]) @@ -256,15 +254,14 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): cpdef dual_variable(self, int i, sparse=False): """ - The `i`-th dual variable - - Available after self.solve() is called, otherwise the result is undefined + The `i`-th dual variable. - - ``index`` (integer) -- the constraint's id. + Available after ``self.solve()`` is called, otherwise the result is + undefined. - OUTPUT: + - ``index`` -- integer; the constraint's id - The matrix of the `i`-th dual variable + OUTPUT: the matrix of the `i`-th dual variable EXAMPLES:: @@ -297,7 +294,6 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): IndexError: list index out of range sage: abs(g - B._get_answer()['gap']) # tol 1e-22 0.0 - """ cdef int n n = self.answer['zs'][i].size[0] @@ -306,15 +302,14 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): cpdef slack(self, int i, sparse=False): """ - Slack of the `i`-th constraint - - Available after self.solve() is called, otherwise the result is undefined + Slack of the `i`-th constraint. - - ``index`` (integer) -- the constraint's id. + Available after ``self.solve()`` is called, otherwise the result is + undefined. - OUTPUT: + - ``index`` -- integer; the constraint's id - The matrix of the slack of the `i`-th constraint + OUTPUT: the matrix of the slack of the `i`-th constraint EXAMPLES:: @@ -348,7 +343,6 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): Traceback (most recent call last): ... IndexError: list index out of range - """ cdef int n n = self.answer['ss'][i].size[0] @@ -357,14 +351,14 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): cpdef solver_parameter(self, name, value=None): """ - Return or define a solver parameter + Return or define a solver parameter. INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value .. NOTE:: @@ -374,7 +368,7 @@ cdef class CVXOPTSDPBackend(MatrixSDPBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_sdp_backend import get_solver - sage: p = get_solver(solver="CVXOPT") + sage: p = get_solver(solver='CVXOPT') sage: p.solver_parameter("show_progress") False sage: p.solver_parameter("show_progress", True) diff --git a/src/sage/numerical/backends/cvxpy_backend.pyx b/src/sage/numerical/backends/cvxpy_backend.pyx index 175b727a8a5..6a758e35bfb 100644 --- a/src/sage/numerical/backends/cvxpy_backend.pyx +++ b/src/sage/numerical/backends/cvxpy_backend.pyx @@ -41,46 +41,46 @@ cdef class CVXPYBackend: Using the default solver determined by CVXPY:: - sage: p = MixedIntegerLinearProgram(solver="CVXPY"); p.solve() + sage: p = MixedIntegerLinearProgram(solver='CVXPY'); p.solve() 0.0 Using a specific solver:: - sage: p = MixedIntegerLinearProgram(solver="CVXPY/OSQP"); p.solve() + sage: p = MixedIntegerLinearProgram(solver='CVXPY/OSQP'); p.solve() 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/ECOS"); p.solve() + sage: p = MixedIntegerLinearProgram(solver='CVXPY/ECOS'); p.solve() 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/SCS"); p.solve() + sage: p = MixedIntegerLinearProgram(solver='CVXPY/SCS'); p.solve() 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/SciPy/HiGHS"); p.solve() + sage: p = MixedIntegerLinearProgram(solver='CVXPY/SciPy/HiGHS'); p.solve() 0.0 Open-source solvers provided by optional packages:: - sage: p = MixedIntegerLinearProgram(solver="CVXPY/GLPK"); p.solve() # needs cvxopt + sage: p = MixedIntegerLinearProgram(solver='CVXPY/GLPK'); p.solve() # needs cvxopt 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/GLPK_MI"); p.solve() # needs cvxopt + sage: p = MixedIntegerLinearProgram(solver='CVXPY/GLPK_MI'); p.solve() # needs cvxopt 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/CVXOPT"); p.solve() # needs cvxopt + sage: p = MixedIntegerLinearProgram(solver='CVXPY/CVXOPT'); p.solve() # needs cvxopt 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/GLOP"); p.solve() # optional - ortools + sage: p = MixedIntegerLinearProgram(solver='CVXPY/GLOP'); p.solve() # optional - ortools 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/PDLP"); p.solve() # optional - ortools + sage: p = MixedIntegerLinearProgram(solver='CVXPY/PDLP'); p.solve() # optional - ortools 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/CBC"); p.solve() # optional - cylp + sage: p = MixedIntegerLinearProgram(solver='CVXPY/CBC'); p.solve() # optional - cylp 0.0 Non-free solvers:: - sage: p = MixedIntegerLinearProgram(solver="CVXPY/Gurobi"); p.solve() # optional - gurobi + sage: p = MixedIntegerLinearProgram(solver='CVXPY/Gurobi'); p.solve() # optional - gurobi 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/CPLEX"); p.solve() # optional - cplex + sage: p = MixedIntegerLinearProgram(solver='CVXPY/CPLEX'); p.solve() # optional - cplex 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/MOSEK"); p.solve() # optional - mosek + sage: p = MixedIntegerLinearProgram(solver='CVXPY/MOSEK'); p.solve() # optional - mosek 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/SCIP"); p.solve() # optional - pyscipopt + sage: p = MixedIntegerLinearProgram(solver='CVXPY/SCIP'); p.solve() # optional - pyscipopt 0.0 - sage: p = MixedIntegerLinearProgram(solver="CVXPY/XPRESS"); p.solve() # optional - xpress + sage: p = MixedIntegerLinearProgram(solver='CVXPY/XPRESS'); p.solve() # optional - xpress 0.0 sage: p = MixedIntegerLinearProgram(solver="CVXPY/NAG"); p.solve() # optional - naginterfaces 0.0 @@ -88,25 +88,25 @@ cdef class CVXPYBackend: def __cinit__(self, maximization=True, base_ring=None, cvxpy_solver=None, cvxpy_solver_args=None): """ - Cython constructor + Cython constructor. INPUT: - - ``maximization`` (boolean, default: ``True``) -- Whether this is a - maximization or minimization problem. + - ``maximization``-- boolean (default: ``True``); whether this is a + maximization or minimization problem - - ``base_ring`` (optional): Must be ``RDF`` if provided. + - ``base_ring`` -- (optional) must be ``RDF`` if provided - - ``cvxpy_solver (optional): Passed to :meth:`cvxpy.Problem.solve` as the - parameter ``solver``. + - ``cvxpy_solver`` -- (optional) passed to :meth:`cvxpy.Problem.solve` + as the parameter ``solver`` - - ``cvxpy_solver_args`` (optional dict): Passed to :meth:`cvxpy.Problem.solve` - as additional keyword arguments. + - ``cvxpy_solver_args`` -- dictionary (optional); passed to + :meth:`cvxpy.Problem.solve` as additional keyword arguments EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') """ if base_ring is None: base_ring = RDF @@ -143,12 +143,12 @@ cdef class CVXPYBackend: cpdef __copy__(self): """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = MixedIntegerLinearProgram(solver="CVXPY") + sage: p = MixedIntegerLinearProgram(solver='CVXPY') sage: b = p.new_variable() sage: p.add_constraint(b[1] + b[2] <= 6) sage: p.set_objective(b[1] + b[2]) @@ -196,26 +196,25 @@ cdef class CVXPYBackend: - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integral (default: ``False``). + - ``integer`` -- ``True`` if the variable is integral (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - - ``coefficients`` -- (optional) an iterable of pairs ``(i, v)``. In each - pair, ``i`` is a row index (integer) and ``v`` is a - value (element of :meth:`base_ring`). + - ``coefficients`` -- (optional) an iterable of pairs ``(i, v)``; in each + pair, ``i`` is a row index (integer) and ``v`` is a value (element of :meth:`base_ring`) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.ncols() 0 sage: p.add_variable() @@ -287,18 +286,18 @@ cdef class CVXPYBackend: cpdef set_verbosity(self, int level): """ - Set the log (verbosity) level + Set the log (verbosity) level. This is currently ignored. INPUT: - - ``level`` (integer) -- From 0 (no verbosity) to 3. + - ``level`` -- integer; from 0 (no verbosity) to 3 EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.set_verbosity(2) """ pass @@ -314,17 +313,17 @@ cdef class CVXPYBackend: value (element of :meth:`base_ring`). - ``lower_bound`` -- element of :meth:`base_ring` or - ``None``. The lower bound. + ``None``; the lower bound - ``upper_bound`` -- element of :meth:`base_ring` or - ``None``. The upper bound. + ``None``; the upper bound - - ``name`` -- string or ``None``. Optional name for this row. + - ``name`` -- string or ``None``; optional name for this row EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variables(5) 4 sage: index = p.nrows() @@ -368,11 +367,11 @@ cdef class CVXPYBackend: INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint @@ -386,7 +385,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.ncols() 0 sage: p.nrows() @@ -415,15 +414,16 @@ cdef class CVXPYBackend: INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variables(5) 4 sage: p.set_objective([1, 1, 2, 1, 3]) @@ -447,7 +447,7 @@ cdef class CVXPYBackend: INPUT: - - ``sense`` (integer) : + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -455,7 +455,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.is_maximization() True sage: p.set_sense(-1) @@ -471,19 +471,19 @@ cdef class CVXPYBackend: cpdef objective_coefficient(self, int variable, coeff=None): """ - Set or get the coefficient of a variable in the objective function + Set or get the coefficient of a variable in the objective function. INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient or ``None`` for + - ``coeff`` -- double; its coefficient or ``None`` for reading (default: ``None``) EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variable() 0 sage: p.objective_coefficient(0) @@ -517,7 +517,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_linear_constraints(5, 0, None) sage: p.add_col(list(range(5)), list(range(5))) Traceback (most recent call last): @@ -555,7 +555,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variables(2) 1 sage: p.add_linear_constraint([(0,1), (1,2)], None, 3) @@ -582,7 +582,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variables(2) 1 sage: p.add_linear_constraint([(0,1), (1, 2)], None, 3) @@ -605,7 +605,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.ncols() 0 sage: p.add_variables(2) @@ -622,7 +622,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.nrows() 0 sage: p.add_linear_constraints(2, 0, None) @@ -638,7 +638,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.is_maximization() True sage: p.set_sense(-1) @@ -649,17 +649,17 @@ cdef class CVXPYBackend: cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.problem_name("There_once_was_a_french_fry") sage: print(p.problem_name()) There_once_was_a_french_fry @@ -674,11 +674,11 @@ cdef class CVXPYBackend: cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -690,7 +690,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variables(5) 4 sage: index = p.nrows() @@ -714,7 +714,7 @@ cdef class CVXPYBackend: INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -725,7 +725,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variables(5) 4 sage: index = p.nrows() @@ -743,7 +743,7 @@ cdef class CVXPYBackend: INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -754,7 +754,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variable() 0 sage: p.col_bounds(0) @@ -771,12 +771,12 @@ cdef class CVXPYBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.ncols() 0 sage: p.add_variable() @@ -792,12 +792,12 @@ cdef class CVXPYBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.ncols() 0 sage: p.add_variable() @@ -813,12 +813,12 @@ cdef class CVXPYBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.ncols() 0 sage: p.add_variable() @@ -830,16 +830,16 @@ cdef class CVXPYBackend: cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_linear_constraint([], 2, 2) sage: p.row_name(0) 'constraint_0' @@ -848,19 +848,19 @@ cdef class CVXPYBackend: cpdef col_name(self, int index): """ - Return the ``index`` th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variable() 0 sage: p.col_name(0) @@ -870,11 +870,11 @@ cdef class CVXPYBackend: cpdef variable_upper_bound(self, int index, value=False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``None`` @@ -883,7 +883,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variable() 0 sage: p.col_bounds(0) @@ -902,11 +902,11 @@ cdef class CVXPYBackend: cpdef variable_lower_bound(self, int index, value=False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not lower bound. When set to ``None`` @@ -915,7 +915,7 @@ cdef class CVXPYBackend: EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="CVXPY") + sage: p = get_solver(solver='CVXPY') sage: p.add_variable() 0 sage: p.col_bounds(0) diff --git a/src/sage/numerical/backends/generic_backend.pyx b/src/sage/numerical/backends/generic_backend.pyx index 4ebfa58f839..b7962c3c877 100644 --- a/src/sage/numerical/backends/generic_backend.pyx +++ b/src/sage/numerical/backends/generic_backend.pyx @@ -3,7 +3,7 @@ Generic Backend for LP solvers This class only lists the methods that should be defined by any interface with a LP Solver. All these methods immediately raise -:class:`NotImplementedError` exceptions when called, and are obviously +:exc:`NotImplementedError` exceptions when called, and are obviously meant to be replaced by the solver-specific method. This file can also be used as a template to create a new interface : one would only need to replace the occurrences of ``"Nonexistent_LP_solver"`` by the @@ -54,17 +54,17 @@ cdef class GenericBackend: - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integral (default: ``False``). + - ``integer`` -- ``True`` if the variable is integral (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -109,17 +109,17 @@ cdef class GenericBackend: - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is binary (default: ``True``). + - ``continuous`` -- ``True`` if the variable is binary (default: ``True``) - - ``integer`` -- ``True`` if the variable is binary (default: ``False``). + - ``integer`` -- ``True`` if the variable is binary (default: ``False``) - - ``obj`` -- (optional) coefficient of all variables in the objective function (default: 0.0) + - ``obj`` -- coefficient of all variables in the objective function (default: 0.0) - - ``names`` -- optional list of names (default: ``None``) + - ``names`` -- list of names (default: ``None``) - OUTPUT: The index of the variable created last. + OUTPUT: the index of the variable created last EXAMPLES:: @@ -168,7 +168,7 @@ cdef class GenericBackend: @classmethod def _test_add_variables(cls, tester=None, **options): """ - Run tests on the method :meth:`.add_linear_constraints`. + Run tests on the method :meth:`add_linear_constraints`. TESTS:: @@ -211,13 +211,13 @@ cdef class GenericBackend: cpdef set_variable_type(self, int variable, int vtype): """ - Set the type of a variable + Set the type of a variable. INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``vtype`` (integer): + - ``vtype`` -- integer: * `1` Integer * `0` Binary @@ -244,7 +244,7 @@ cdef class GenericBackend: INPUT: - - ``sense`` (integer) : + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -273,7 +273,6 @@ cdef class GenericBackend: sage: p = GenericBackend() sage: p._test_sense() # optional - Nonexistent_LP_solver Exception NotImplementedError ... - """ p = cls() # fresh instance of the backend if tester is None: @@ -291,9 +290,9 @@ cdef class GenericBackend: INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient + - ``coeff`` -- double; its coefficient EXAMPLES:: @@ -312,11 +311,12 @@ cdef class GenericBackend: cpdef objective_constant_term(self, d=None): """ - Set or get the constant term in the objective function + Set or get the constant term in the objective function. INPUT: - - ``d`` (double) -- its coefficient. If `None` (default), return the current value. + - ``d`` -- double; its coefficient. If ``None`` (default), return the + current value. EXAMPLES:: @@ -340,10 +340,11 @@ cdef class GenericBackend: INPUT: - - ``coeff`` -- a list of real values, whose i-th element is the - coefficient of the i-th variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: @@ -372,11 +373,11 @@ cdef class GenericBackend: cpdef set_verbosity(self, int level): """ - Set the log (verbosity) level + Set the log (verbosity) level. INPUT: - - ``level`` (integer) -- From 0 (no verbosity) to 3. + - ``level`` -- integer; from 0 (no verbosity) to 3 EXAMPLES:: @@ -392,7 +393,7 @@ cdef class GenericBackend: INPUT: - - ``i`` -- index of the constraint to remove. + - ``i`` -- index of the constraint to remove EXAMPLES:: @@ -420,7 +421,7 @@ cdef class GenericBackend: INPUT: - - ``constraints`` -- an iterable containing the indices of the rows to remove. + - ``constraints`` -- an iterable containing the indices of the rows to remove EXAMPLES:: @@ -455,12 +456,12 @@ cdef class GenericBackend: value (element of :meth:`base_ring`). - ``lower_bound`` -- element of :meth:`base_ring` or - ``None``. The lower bound. + ``None``; the lower bound - ``upper_bound`` -- element of :meth:`base_ring` or - ``None``. The upper bound. + ``None``; the upper bound - - ``name`` -- string or ``None``. Optional name for this row. + - ``name`` -- string or ``None``; optional name for this row EXAMPLES:: @@ -493,21 +494,21 @@ cdef class GenericBackend: INPUT: - - ``degree`` -- integer. The vector degree, that is, the - number of new scalar constraints. + - ``degree`` -- integer; the vector degree, that is, the + number of new scalar constraints - ``coefficients`` -- an iterable of pairs ``(i, v)``. In each pair, ``i`` is a variable index (integer) and ``v`` is a vector (real and of length ``degree``). - - ``lower_bound`` -- either a vector or ``None``. The - component-wise lower bound. + - ``lower_bound`` -- either a vector or ``None``; the + component-wise lower bound - - ``upper_bound`` -- either a vector or ``None``. The - component-wise upper bound. + - ``upper_bound`` -- either a vector or ``None``; the + component-wise upper bound - - ``name`` -- string or ``None``. An optional name for all new - rows. + - ``name`` -- string or ``None``; an optional name for all new + rows EXAMPLES:: @@ -532,7 +533,7 @@ cdef class GenericBackend: @classmethod def _test_add_linear_constraint_vector(cls, tester=None, **options): """ - Run tests on the method :meth:`.add_linear_constraint_vector`. + Run tests on the method :meth:`add_linear_constraint_vector`. TESTS:: @@ -566,11 +567,11 @@ cdef class GenericBackend: INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint @@ -600,7 +601,7 @@ cdef class GenericBackend: @classmethod def _test_add_col(cls, tester=None, **options): """ - Run tests on the method :meth:`.add_col` + Run tests on the method :meth:`add_col`. TESTS:: @@ -610,7 +611,6 @@ cdef class GenericBackend: Traceback (most recent call last): ... NotImplementedError: ... - """ p = cls() # fresh instance of the backend if tester is None: @@ -627,7 +627,7 @@ cdef class GenericBackend: INPUT: - - ``number`` (integer) -- the number of constraints to add. + - ``number`` -- integer; the number of constraints to add - ``lower_bound`` -- a lower bound, either a real value or ``None`` @@ -655,7 +655,7 @@ cdef class GenericBackend: @classmethod def _test_add_linear_constraints(cls, tester=None, **options): """ - Run tests on the method :meth:`.add_linear_constraints`. + Run tests on the method :meth:`add_linear_constraints`. TESTS:: @@ -936,11 +936,11 @@ cdef class GenericBackend: cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: @@ -956,11 +956,11 @@ cdef class GenericBackend: cpdef write_lp(self, name): """ - Write the problem to a ``.lp`` file + Write the problem to a ``.lp`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -972,18 +972,18 @@ cdef class GenericBackend: sage: p.add_linear_constraint([(0, 1], (1, 2)], None, 3) sage: p.set_objective([2, 5]) sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(suffix=".lp") as f: + sage: with NamedTemporaryFile(suffix='.lp') as f: ....: p.write_lp(f.name) """ raise NotImplementedError() cpdef write_mps(self, name, int modern): """ - Write the problem to a ``.mps`` file + Write the problem to a ``.mps`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -995,15 +995,14 @@ cdef class GenericBackend: sage: p.add_linear_constraint([(0, 1), (1, 2)], None, 3) sage: p.set_objective([2, 5]) sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(suffix=".lp") as f: + sage: with NamedTemporaryFile(suffix='.lp') as f: ....: p.write_lp(f.name) - """ raise NotImplementedError() cpdef copy(self): """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -1021,7 +1020,7 @@ cdef class GenericBackend: # Override this method in backends. cpdef __copy__(self): """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -1061,11 +1060,11 @@ cdef class GenericBackend: cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -1095,7 +1094,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -1124,7 +1123,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -1153,7 +1152,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1167,7 +1166,6 @@ cdef class GenericBackend: sage: p.set_variable_type(0,0) sage: p.is_variable_binary(0) True - """ raise NotImplementedError() @@ -1177,7 +1175,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1200,7 +1198,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1216,17 +1214,16 @@ cdef class GenericBackend: sage: p.set_variable_type(0,1) sage: p.is_variable_continuous(0) False - """ raise NotImplementedError() cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: @@ -1236,20 +1233,19 @@ cdef class GenericBackend: sage: p.add_linear_constraints(1, 2, None, names=['Empty constraint 1']) sage: p.row_name(0) 'Empty constraint 1' - """ raise NotImplementedError() cpdef col_name(self, int index): """ - Return the ``index``-th column name + Return the ``index``-th column name. INPUT: - - ``index`` (integer) -- the column id + - ``index`` -- integer; the column id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: @@ -1345,11 +1341,11 @@ cdef class GenericBackend: cpdef variable_upper_bound(self, int index, value=False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``False`` @@ -1372,11 +1368,11 @@ cdef class GenericBackend: cpdef variable_lower_bound(self, int index, value=False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not lower bound. When set to ``False`` @@ -1399,14 +1395,14 @@ cdef class GenericBackend: cpdef solver_parameter(self, name, value=None): """ - Return or define a solver parameter + Return or define a solver parameter. INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value .. NOTE:: @@ -1433,7 +1429,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1464,7 +1460,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1495,7 +1491,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1526,7 +1522,7 @@ cdef class GenericBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1561,7 +1557,6 @@ cdef class GenericBackend: Traceback (most recent call last): ... NotImplementedError - """ p = cls() # fresh instance of the backend if tester is None: @@ -1589,7 +1584,7 @@ default_solver = None def default_mip_solver(solver=None): """ - Returns/sets the default MILP solver used by Sage + Return/set the default MILP solver used by Sage. INPUT: @@ -1601,14 +1596,14 @@ def default_mip_solver(solver=None): - a callable (typically a subclass of :class:`sage.numerical.backends.generic_backend.GenericBackend`); - - ``None`` (default), in which case the current default solver - is returned; this is either a string or a callable. + - ``None`` -- (default) in which case the current default solver + is returned; this is either a string or a callable OUTPUT: This function returns the current default solver's name if ``solver = None`` (default). Otherwise, it sets the default solver to the one given. If this - solver does not exist, or is not available, a :class:`ValueError` exception is + solver does not exist, or is not available, a :exc:`ValueError` exception is raised. EXAMPLES:: @@ -1723,7 +1718,7 @@ def default_mip_solver(solver=None): cpdef GenericBackend get_solver(constraint_generation=False, solver=None, base_ring=None): """ - Return a solver according to the given preferences + Return a solver according to the given preferences. INPUT: @@ -1732,13 +1727,13 @@ cpdef GenericBackend get_solver(constraint_generation=False, solver=None, base_r - a string indicating one of the available solvers (see :class:`MixedIntegerLinearProgram`); - - ``None`` (default), in which case the default solver is used + - ``None`` -- (default) in which case the default solver is used (see :func:`default_mip_solver`); - or a callable (such as a class), in which case it is called, and its result is returned. - - ``base_ring`` -- If not ``None``, request a solver that works over this + - ``base_ring`` -- if not ``None``, request a solver that works over this (ordered) field. If ``base_ring`` is not a field, its fraction field is used. @@ -1746,7 +1741,7 @@ cpdef GenericBackend get_solver(constraint_generation=False, solver=None, base_r the rational numbers. This is unrelated to whether variables are constrained to be integers or not. - - ``constraint_generation`` -- Only used when ``solver=None``. + - ``constraint_generation`` -- only used when ``solver=None``: - When set to ``True``, after solving the ``MixedIntegerLinearProgram``, it is possible to add a constraint, and then solve it again. @@ -1757,7 +1752,7 @@ cpdef GenericBackend get_solver(constraint_generation=False, solver=None, base_r .. SEEALSO:: - - :func:`default_mip_solver` -- Returns/Sets the default MIP solver. + - :func:`default_mip_solver` -- returns/sets the default MIP solver EXAMPLES:: @@ -1798,8 +1793,8 @@ cpdef GenericBackend get_solver(constraint_generation=False, solver=None, base_r sage: def glpk_exact_solver(): ....: from sage.numerical.backends.generic_backend import get_solver - ....: b = get_solver(solver="GLPK") - ....: b.solver_parameter("simplex_or_intopt", "exact_simplex_only") + ....: b = get_solver(solver='GLPK') + ....: b.solver_parameter('simplex_or_intopt', 'exact_simplex_only') ....: return b sage: codes.bounds.delsarte_bound_additive_hamming_space(11,3,4,solver=glpk_exact_solver) # long time 8 @@ -1815,7 +1810,6 @@ cpdef GenericBackend get_solver(constraint_generation=False, solver=None, base_r sage: M.get_backend() <...GLPKBackend...> sage: default_mip_solver(old_default) - """ if solver is None: diff --git a/src/sage/numerical/backends/generic_backend_test.py b/src/sage/numerical/backends/generic_backend_test.py index 3c5416eb63c..2b5411fb64e 100644 --- a/src/sage/numerical/backends/generic_backend_test.py +++ b/src/sage/numerical/backends/generic_backend_test.py @@ -19,4 +19,4 @@ def test_ncols_nonnegative(self, backend: GenericBackend): def test_sage_unittest_testsuite(self, sage_object: SageObject): # TODO: Remove this test as soon as all old test methods are migrated from sage.misc.sage_unittest import TestSuite - TestSuite(sage_object).run(verbose=True, raise_on_failure=True, skip="_test_pickling") + TestSuite(sage_object).run(verbose=True, raise_on_failure=True, skip='_test_pickling') diff --git a/src/sage/numerical/backends/generic_sdp_backend.pyx b/src/sage/numerical/backends/generic_sdp_backend.pyx index 7124afd14ab..e1ad583f41c 100644 --- a/src/sage/numerical/backends/generic_sdp_backend.pyx +++ b/src/sage/numerical/backends/generic_sdp_backend.pyx @@ -3,7 +3,7 @@ Generic Backend for SDP solvers This class only lists the methods that should be defined by any interface with a SDP Solver. All these methods immediately raise -``NotImplementedError`` exceptions when called, and are obviously +:exc:`NotImplementedError` exceptions when called, and are obviously meant to be replaced by the solver-specific method. This file can also be used as a template to create a new interface : one would only need to replace the occurrences of ``"Nonexistent_SDP_solver"`` by the @@ -30,7 +30,7 @@ cdef class GenericSDPBackend: cpdef base_ring(self): """ - The base ring + The base ring. TESTS:: @@ -43,7 +43,7 @@ cdef class GenericSDPBackend: cpdef zero(self): """ - Zero of the base ring + Zero of the base ring. TESTS:: @@ -62,11 +62,13 @@ cdef class GenericSDPBackend: INPUT: - - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) + - ``obj`` -- (optional) coefficient of this variable in the objective + function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: + ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -99,11 +101,11 @@ cdef class GenericSDPBackend: - ``n`` -- the number of new variables (must be > 0) - - ``obj`` -- (optional) coefficient of all variables in the objective function (default: 0.0) + - ``obj`` -- coefficient of all variables in the objective function (default: 0.0) - - ``names`` -- optional list of names (default: ``None``) + - ``names`` -- list of names (default: ``None``) - OUTPUT: The index of the variable created last. + OUTPUT: the index of the variable created last EXAMPLES:: @@ -127,7 +129,7 @@ cdef class GenericSDPBackend: INPUT: - - ``sense`` (integer): + - ``sense`` -- integer: * `+1` => Maximization * `-1` => Minimization @@ -152,9 +154,9 @@ cdef class GenericSDPBackend: INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient + - ``coeff`` -- double; its coefficient EXAMPLES:: @@ -177,10 +179,11 @@ cdef class GenericSDPBackend: INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: @@ -237,7 +240,7 @@ cdef class GenericSDPBackend: INPUT: - - ``number`` (integer) -- the number of constraints to add. + - ``number`` -- integer; the number of constraints to add - ``lower_bound`` -- a lower bound, either a real value or ``None`` @@ -399,11 +402,11 @@ cdef class GenericSDPBackend: cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``NULL`` (default), the method returns the problem's name. EXAMPLES:: @@ -420,11 +423,11 @@ cdef class GenericSDPBackend: cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -450,11 +453,11 @@ cdef class GenericSDPBackend: cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: @@ -464,20 +467,19 @@ cdef class GenericSDPBackend: sage: p.add_linear_constraints(1, 2, None, name="Empty constraint 1") sage: p.row_name(0) 'Empty constraint 1' - """ raise NotImplementedError() cpdef col_name(self, int index): """ - Return the ``index`` th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: @@ -493,15 +495,13 @@ cdef class GenericSDPBackend: cpdef dual_variable(self, int i, sparse=False): """ - The `i`-th dual variable - - Available after self.solve() is called, otherwise the result is undefined + The `i`-th dual variable. - - ``index`` (integer) -- the constraint's id. + Available after ``self.solve()`` is called, otherwise the result is undefined - OUTPUT: + - ``index`` -- integer; the constraint's id - The matrix of the `i`-th dual variable + OUTPUT: the matrix of the `i`-th dual variable EXAMPLES:: @@ -540,15 +540,14 @@ cdef class GenericSDPBackend: cpdef slack(self, int i, sparse=False): """ - Slack of the `i`-th constraint + Slack of the `i`-th constraint. - Available after self.solve() is called, otherwise the result is undefined + Available after ``self.solve()`` is called, otherwise the result is + undefined. - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id - OUTPUT: - - The matrix of the slack of the `i`-th constraint + OUTPUT: the matrix of the slack of the `i`-th constraint EXAMPLES:: @@ -589,14 +588,14 @@ cdef class GenericSDPBackend: cpdef solver_parameter(self, name, value=None): """ - Return or define a solver parameter + Return or define a solver parameter. INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value .. NOTE:: @@ -620,28 +619,28 @@ default_solver = None def default_sdp_solver(solver=None): """ - Return/set the default SDP solver used by Sage + Return/set the default SDP solver used by Sage. INPUT: - ``solver`` -- one of the following: - - the string ``"CVXOPT"``, to make the use of the CVXOPT solver + - the string ``'CVXOPT'``, to make the use of the CVXOPT solver (see the `CVXOPT `_ web site) the default; - a subclass of :class:`sage.numerical.backends.generic_sdp_backend.GenericSDPBackend`, to make it the default; or - - ``None`` (default), in which case the current default solver - (a string or a class) is returned. + - ``None`` -- (default) in which case the current default solver + (a string or a class) is returned OUTPUT: This function returns the current default solver (a string or a class) if ``solver = None`` (default). Otherwise, it sets the default solver to the one given. If this solver does not exist, or - is not available, a ``ValueError`` exception is raised. + is not available, a :exc:`ValueError` exception is raised. EXAMPLES:: @@ -659,7 +658,6 @@ def default_sdp_solver(solver=None): sage: default_sdp_solver(my_sdp_solver) sage: default_sdp_solver() is my_sdp_solver True - """ global default_solver @@ -707,18 +705,18 @@ cpdef GenericSDPBackend get_solver(solver=None, base_ring=None): - ``solver`` -- one of the following: - - the string ``"CVXOPT"``, designating the use of the CVXOPT solver + - the string ``'CVXOPT'``, designating the use of the CVXOPT solver (see the `CVXOPT `_ web site); - a subclass of - :class:`sage.numerical.backends.generic_sdp_backend.GenericSDPBackend`; + :class:`sage.numerical.backends.generic_sdp_backend.GenericSDPBackend` - - ``None`` (default), in which case the default solver is used (see - :func:`default_sdp_solver`); + - ``None`` -- (default) in which case the default solver is used (see + :func:`default_sdp_solver`) .. SEEALSO:: - - :func:`default_sdp_solver` -- Returns/Sets the default SDP solver. + - :func:`default_sdp_solver` -- returns/sets the default SDP solver EXAMPLES:: diff --git a/src/sage/numerical/backends/glpk_backend.pyx b/src/sage/numerical/backends/glpk_backend.pyx index f1253f461b6..dddde9a07b6 100644 --- a/src/sage/numerical/backends/glpk_backend.pyx +++ b/src/sage/numerical/backends/glpk_backend.pyx @@ -33,18 +33,17 @@ from sage.libs.glpk.lp cimport * cdef class GLPKBackend(GenericBackend): - """ MIP Backend that uses the GLPK solver. """ def __cinit__(self, maximization = True): """ - Constructor + Constructor. EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') """ self.lp = glp_create_prob() self.simplex_or_intopt = glp_simplex_then_intopt @@ -78,17 +77,17 @@ cdef class GLPKBackend(GenericBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integral (default: ``False``). + - ``integer`` -- ``True`` if the variable is integral (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -158,17 +157,17 @@ cdef class GLPKBackend(GenericBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is binary (default: ``True``). + - ``continuous`` -- ``True`` if the variable is binary (default: ``True``) - - ``integer`` -- ``True`` if the variable is binary (default: ``False``). + - ``integer`` -- ``True`` if the variable is binary (default: ``False``) - - ``obj`` -- (optional) coefficient of all variables in the objective function (default: 0.0) + - ``obj`` -- coefficient of all variables in the objective function (default: 0.0) - - ``names`` -- optional list of names (default: ``None``) + - ``names`` -- list of names (default: ``None``) - OUTPUT: The index of the variable created last. + OUTPUT: the index of the variable created last EXAMPLES:: @@ -230,13 +229,13 @@ cdef class GLPKBackend(GenericBackend): cpdef set_variable_type(self, int variable, int vtype): """ - Set the type of a variable + Set the type of a variable. INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``vtype`` (integer) : + - ``vtype`` -- integer: * 1 Integer * 0 Binary @@ -259,12 +258,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.set_variable_type(2,0) Traceback (most recent call last): ... ValueError: invalid variable index 2 - """ if variable < 0 or variable > (self.ncols() - 1): raise ValueError("invalid variable index %d" % variable) @@ -284,7 +282,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``sense`` (integer) : + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -306,13 +304,13 @@ cdef class GLPKBackend(GenericBackend): cpdef objective_coefficient(self, int variable, coeff=None): """ - Set or get the coefficient of a variable in the objective function + Set or get the coefficient of a variable in the objective function. INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient or ``None`` for + - ``coeff`` -- double; its coefficient or ``None`` for reading (default: ``None``) EXAMPLES:: @@ -332,12 +330,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.objective_coefficient(2) Traceback (most recent call last): ... ValueError: invalid variable index 2 - """ if variable < 0 or variable > (self.ncols() - 1): raise ValueError("invalid variable index %d" % variable) @@ -349,11 +346,11 @@ cdef class GLPKBackend(GenericBackend): cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: @@ -385,10 +382,11 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: @@ -411,15 +409,15 @@ cdef class GLPKBackend(GenericBackend): cpdef set_verbosity(self, int level): """ - Set the verbosity level + Set the verbosity level. INPUT: - - ``level`` (integer) -- From 0 (no verbosity) to 3. + - ``level`` -- integer; from 0 (no verbosity) to 3 EXAMPLES:: - sage: p. = MixedIntegerLinearProgram(solver="GLPK") + sage: p. = MixedIntegerLinearProgram(solver='GLPK') sage: p.add_constraint(10 * x[0] <= 1) sage: p.add_constraint(5 * x[1] <= 1) sage: p.set_objective(x[0] + x[1]) @@ -438,7 +436,7 @@ cdef class GLPKBackend(GenericBackend): :: - sage: p. = MixedIntegerLinearProgram(solver="GLPK/exact") + sage: p. = MixedIntegerLinearProgram(solver='GLPK/exact') sage: p.add_constraint(10 * x[0] <= 1) sage: p.add_constraint(5 * x[1] <= 1) sage: p.set_objective(x[0] + x[1]) @@ -473,7 +471,7 @@ cdef class GLPKBackend(GenericBackend): cpdef remove_constraint(self, int i): r""" - Remove a constraint from self. + Remove a constraint from ``self``. INPUT: @@ -516,7 +514,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``constraints`` -- an iterable containing the indices of the rows to remove. + - ``constraints`` -- an iterable containing the indices of the rows to remove EXAMPLES:: @@ -597,13 +595,12 @@ cdef class GLPKBackend(GenericBackend): This used to crash Sage, but was fixed in :issue:`19525`:: - sage: p = MixedIntegerLinearProgram(solver="glpk") - sage: q = MixedIntegerLinearProgram(solver="glpk") + sage: p = MixedIntegerLinearProgram(solver='glpk') + sage: q = MixedIntegerLinearProgram(solver='glpk') sage: q.add_constraint(p.new_variable()[0] <= 1) Traceback (most recent call last): ... ValueError: invalid variable index 0 - """ if lower_bound is None and upper_bound is None: raise ValueError("At least one of 'upper_bound' or 'lower_bound' must be set.") @@ -655,7 +652,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``number`` (integer) -- the number of constraints to add. + - ``number`` -- integer; the number of constraints to add - ``lower_bound`` -- a lower bound, either a real value or ``None`` @@ -699,11 +696,11 @@ cdef class GLPKBackend(GenericBackend): cpdef row(self, int index): r""" - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -729,12 +726,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.row(2) Traceback (most recent call last): ... ValueError: invalid row index 2 - """ if index < 0 or index > (self.nrows() - 1): raise ValueError("invalid row index %d" % index) @@ -760,7 +756,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -785,12 +781,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.row_bounds(2) Traceback (most recent call last): ... ValueError: invalid row index 2 - """ cdef double ub cdef double lb @@ -812,7 +807,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -837,12 +832,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.col_bounds(2) Traceback (most recent call last): ... ValueError: invalid column index 2 - """ cdef double ub @@ -865,15 +859,15 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it - appears. Namely, the ith entry of ``coeffs`` corresponds to + appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint - represented by the ith entry in ``indices``. + represented by the i-th entry in ``indices``. .. NOTE:: @@ -1098,7 +1092,7 @@ cdef class GLPKBackend(GenericBackend): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("mip_gap_tolerance",100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -1152,7 +1146,7 @@ cdef class GLPKBackend(GenericBackend): cpdef get_objective_value(self): """ - Returns the value of the objective function. + Return the value of the objective function. .. NOTE:: @@ -1200,7 +1194,7 @@ cdef class GLPKBackend(GenericBackend): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("mip_gap_tolerance",100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -1235,7 +1229,7 @@ cdef class GLPKBackend(GenericBackend): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("mip_gap_tolerance",100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -1260,7 +1254,7 @@ cdef class GLPKBackend(GenericBackend): cpdef get_variable_value(self, int variable): """ - Returns the value of a variable given by the solver. + Return the value of a variable given by the solver. .. NOTE:: @@ -1288,12 +1282,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.get_variable_value(2) Traceback (most recent call last): ... ValueError: invalid variable index 2 - """ if variable < 0 or variable > (self.ncols() - 1): raise ValueError("invalid variable index %d" % variable) @@ -1306,7 +1299,7 @@ cdef class GLPKBackend(GenericBackend): cpdef get_row_prim(self, int i): r""" - Returns the value of the auxiliary variable associated with i-th row. + Return the value of the auxiliary variable associated with i-th row. .. NOTE:: @@ -1340,12 +1333,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.get_row_prim(2) Traceback (most recent call last): ... ValueError: invalid row index 2 - """ if i < 0 or i > (self.nrows() - 1): raise ValueError("invalid row index %d" % i) @@ -1388,11 +1380,11 @@ cdef class GLPKBackend(GenericBackend): cpdef col_name(self, int index): """ - Return the ``index`` th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id EXAMPLES:: @@ -1408,12 +1400,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.col_name(2) Traceback (most recent call last): ... ValueError: invalid column index 2 - """ cdef char * s @@ -1430,11 +1421,11 @@ cdef class GLPKBackend(GenericBackend): cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: @@ -1449,12 +1440,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.row_name(2) Traceback (most recent call last): ... ValueError: invalid row index 2 - """ cdef char * s @@ -1475,7 +1465,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1494,10 +1484,9 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.is_variable_binary(2) False - """ if index < 0 or index > (self.ncols() - 1): # This is how the other backends behave, and this method is @@ -1512,7 +1501,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1531,10 +1520,9 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.is_variable_integer(2) False - """ if index < 0 or index > (self.ncols() - 1): # This is how the other backends behave, and this method is @@ -1549,7 +1537,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1570,10 +1558,9 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.is_variable_continuous(2) False - """ if index < 0 or index > (self.ncols() - 1): # This is how the other backends behave, and this method is @@ -1601,11 +1588,11 @@ cdef class GLPKBackend(GenericBackend): cpdef variable_upper_bound(self, int index, value=False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``False`` @@ -1627,7 +1614,7 @@ cdef class GLPKBackend(GenericBackend): :issue:`14581`:: - sage: P = MixedIntegerLinearProgram(solver="GLPK") + sage: P = MixedIntegerLinearProgram(solver='GLPK') sage: x = P["x"] sage: P.set_max(x, 0) sage: P.get_max(x) @@ -1635,7 +1622,7 @@ cdef class GLPKBackend(GenericBackend): Check that :issue:`10232` is fixed:: - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.variable_upper_bound(2) Traceback (most recent call last): ... @@ -1700,11 +1687,11 @@ cdef class GLPKBackend(GenericBackend): cpdef variable_lower_bound(self, int index, value=False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not lower bound. When set to ``False`` @@ -1726,7 +1713,7 @@ cdef class GLPKBackend(GenericBackend): :issue:`14581`:: - sage: P = MixedIntegerLinearProgram(solver="GLPK") + sage: P = MixedIntegerLinearProgram(solver='GLPK') sage: x = P["x"] sage: P.set_min(x, 5) sage: P.set_min(x, 0) @@ -1735,7 +1722,7 @@ cdef class GLPKBackend(GenericBackend): Check that :issue:`10232` is fixed:: - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.variable_lower_bound(2) Traceback (most recent call last): ... @@ -1800,11 +1787,11 @@ cdef class GLPKBackend(GenericBackend): cpdef write_lp(self, filename): """ - Write the problem to a .lp file + Write the problem to a ``.lp`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -1815,7 +1802,7 @@ cdef class GLPKBackend(GenericBackend): sage: p.add_linear_constraint([[0, 1], [1, 2]], None, 3) sage: p.set_objective([2, 5]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".lp") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.lp') as f: ....: _ = p.write_lp(f.name) ....: len(f.readlines()) ... @@ -1827,11 +1814,11 @@ cdef class GLPKBackend(GenericBackend): cpdef write_mps(self, filename, int modern): """ - Write the problem to a .mps file + Write the problem to a ``.mps`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -1842,7 +1829,7 @@ cdef class GLPKBackend(GenericBackend): sage: p.add_linear_constraint([[0, 1], [1, 2]], None, 3) sage: p.set_objective([2, 5]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix="mps") as f: + sage: with tempfile.NamedTemporaryFile(suffix='mps') as f: ....: _ = p.write_mps(f.name, 2) ....: len(f.readlines()) ... @@ -1854,7 +1841,7 @@ cdef class GLPKBackend(GenericBackend): cpdef __copy__(self): """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -1874,14 +1861,14 @@ cdef class GLPKBackend(GenericBackend): cpdef solver_parameter(self, name, value=None): """ - Return or define a solver parameter + Return or define a solver parameter. INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value You can supply the name of a parameter and its value using either a string or a ``glp_`` constant (which are defined as Cython variables of @@ -1898,7 +1885,7 @@ cdef class GLPKBackend(GenericBackend): Parameter **names** are specified in lower case. To use a constant instead of a string, prepend ``glp_`` to the name. - For example, both ``glp_gmi_cuts`` or ``"gmi_cuts"`` control whether + For example, both ``glp_gmi_cuts`` or ``'gmi_cuts'`` control whether to solve using Gomory cuts. Parameter **values** are specified as strings in upper case, @@ -2014,7 +2001,7 @@ cdef class GLPKBackend(GenericBackend): * - ``presolve_intopt`` - - ``GLP_ON`` (default) or ``GLP_OFF``. + - ``GLP_ON`` (default) or ``GLP_OFF`` * - ``binarize`` @@ -2330,12 +2317,12 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="GLPK") + solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -2360,12 +2347,12 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="GLPK") + solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -2391,12 +2378,12 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="GLPK") + solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -2422,12 +2409,12 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="GLPK") + solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -2456,9 +2443,7 @@ cdef class GLPKBackend(GenericBackend): - ``filename`` -- (optional) name of the file - OUTPUT: - - Zero if the operations was successful otherwise nonzero. + OUTPUT: zero if the operations was successful otherwise nonzero .. NOTE:: @@ -2482,7 +2467,7 @@ cdef class GLPKBackend(GenericBackend): sage: p.solve() 0 sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(mode="r+t", suffix=".tmp") as f: + sage: with NamedTemporaryFile(mode='r+t', suffix='.tmp') as f: ....: p.print_ranges(f.name) ....: for ll in f.readlines(): ....: if ll: print(ll) @@ -2529,9 +2514,9 @@ cdef class GLPKBackend(GenericBackend): cpdef double get_row_dual(self, int variable) noexcept: r""" - Returns the dual value of a constraint. + Return the dual value of a constraint. - The dual value of the ith row is also the value of the ith variable + The dual value of the i-th row is also the value of the i-th variable of the dual problem. The dual value of a constraint is the shadow price of the constraint. @@ -2541,7 +2526,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``variable`` -- The number of the constraint + - ``variable`` -- the number of the constraint .. NOTE:: @@ -2567,8 +2552,6 @@ cdef class GLPKBackend(GenericBackend): 0.0 sage: lp.get_row_dual(1) # tolerance 0.00001 10.0 - - """ if self.simplex_or_intopt == simplex_only: @@ -2578,7 +2561,7 @@ cdef class GLPKBackend(GenericBackend): cpdef double get_col_dual(self, int variable) except? -1: """ - Returns the dual value (reduced cost) of a variable + Return the dual value (reduced cost) of a variable The dual value is the reduced cost of a variable. The reduced cost is the amount by which the objective coefficient @@ -2586,7 +2569,7 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``variable`` -- The number of the variable + - ``variable`` -- the number of the variable .. NOTE:: @@ -2594,7 +2577,6 @@ cdef class GLPKBackend(GenericBackend): If the simplex algorithm has not been used for solving just a 0.0 will be returned. - EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver @@ -2617,12 +2599,11 @@ cdef class GLPKBackend(GenericBackend): We sanity check the input that will be passed to GLPK:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="GLPK") + sage: p = get_solver(solver='GLPK') sage: p.get_col_dual(2) Traceback (most recent call last): ... ValueError: invalid column index 2 - """ if variable < 0 or variable > (self.ncols() - 1): raise ValueError("invalid column index %d" % variable) @@ -2638,11 +2619,12 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``i`` -- The index of the constraint + - ``i`` -- the index of the constraint OUTPUT: - - Returns current status assigned to the auxiliary variable associated with i-th row: + Current status assigned to the auxiliary variable associated with i-th + row: * GLP_BS = 1 basic variable * GLP_NL = 2 non-basic variable on lower bound @@ -2683,11 +2665,12 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``j`` -- The index of the variable + - ``j`` -- the index of the variable OUTPUT: - - Returns current status assigned to the structural variable associated with j-th column: + Current status assigned to the structural variable associated + with j-th column: * GLP_BS = 1 basic variable * GLP_NL = 2 non-basic variable on lower bound @@ -2729,9 +2712,9 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``i`` -- The index of the constraint + - ``i`` -- the index of the constraint - - ``stat`` -- The status to set to + - ``stat`` -- the status to set to EXAMPLES:: @@ -2764,9 +2747,9 @@ cdef class GLPKBackend(GenericBackend): INPUT: - - ``j`` -- The index of the constraint + - ``j`` -- the index of the constraint - - ``stat`` -- The status to set to + - ``stat`` -- the status to set to EXAMPLES:: @@ -2797,9 +2780,7 @@ cdef class GLPKBackend(GenericBackend): r""" Warm up the basis using current statuses assigned to rows and cols. - OUTPUT: - - - Returns the warming up status + OUTPUT: the warming up status * 0 The operation has been successfully performed. * GLP_EBADB The basis matrix is invalid. @@ -2831,7 +2812,7 @@ cdef class GLPKBackend(GenericBackend): cpdef eval_tab_row(self, int k): r""" - Computes a row of the current simplex tableau. + Compute a row of the current simplex tableau. A row corresponds to some basic variable specified by the parameter ``k`` as follows: @@ -2848,12 +2829,12 @@ cdef class GLPKBackend(GenericBackend): .. NOTE:: The basis factorization must exist and the variable with - index ``k`` must be basic. Otherwise, a ``ValueError`` is + index ``k`` must be basic. Otherwise, a :exc:`ValueError` is be raised. INPUT: - - ``k`` (integer) -- the id of the basic variable. + - ``k`` -- integer; the id of the basic variable OUTPUT: @@ -2899,7 +2880,6 @@ cdef class GLPKBackend(GenericBackend): Traceback (most recent call last): ... ValueError: ... - """ cdef int m = self.nrows() cdef int n = self.ncols() @@ -2930,7 +2910,7 @@ cdef class GLPKBackend(GenericBackend): cpdef eval_tab_col(self, int k): r""" - Computes a column of the current simplex tableau. + Compute a column of the current simplex tableau. A (column) corresponds to some non-basic variable specified by the parameter ``k`` as follows: @@ -2947,12 +2927,12 @@ cdef class GLPKBackend(GenericBackend): .. NOTE:: The basis factorization must exist and the variable with - index ``k`` must not be basic. Otherwise, a ``ValueError`` is + index ``k`` must not be basic. Otherwise, a :exc:`ValueError` is be raised. INPUT: - - ``k`` (integer) -- the id of the non-basic variable. + - ``k`` -- integer; the id of the non-basic variable OUTPUT: @@ -2998,7 +2978,6 @@ cdef class GLPKBackend(GenericBackend): Traceback (most recent call last): ... ValueError: ... - """ cdef int m = self.nrows() cdef int n = self.ncols() @@ -3050,7 +3029,6 @@ cdef void glp_callback(glp_tree* tree, void* info) noexcept: - ``info`` -- a ``void *`` to let the function know *where* it should store the data we need. The value of ``info`` is equal to the one stored in iocp.cb_info. - """ cdef search_tree_data_t * data = info data.mip_gap = glp_ios_mip_gap(tree) diff --git a/src/sage/numerical/backends/glpk_backend_test.py b/src/sage/numerical/backends/glpk_backend_test.py index b41b1ae80c8..5204b66e73d 100644 --- a/src/sage/numerical/backends/glpk_backend_test.py +++ b/src/sage/numerical/backends/glpk_backend_test.py @@ -9,4 +9,4 @@ class TestGLPKBackend(GenericBackendTests): @pytest.fixture def backend(self) -> GenericBackend: - return MixedIntegerLinearProgram(solver="GLPK").get_backend() + return MixedIntegerLinearProgram(solver='GLPK').get_backend() diff --git a/src/sage/numerical/backends/glpk_exact_backend.pyx b/src/sage/numerical/backends/glpk_exact_backend.pyx index 8030e1710d3..a9289264a42 100644 --- a/src/sage/numerical/backends/glpk_exact_backend.pyx +++ b/src/sage/numerical/backends/glpk_exact_backend.pyx @@ -15,7 +15,6 @@ AUTHORS: ############################################################################## cdef class GLPKExactBackend(GLPKBackend): - """ MIP Backend that runs the GLPK solver in exact rational simplex mode. @@ -31,11 +30,11 @@ cdef class GLPKExactBackend(GLPKBackend): """ def __cinit__(self, maximization = True): """ - Constructor + Constructor. EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="GLPK/exact") + sage: p = MixedIntegerLinearProgram(solver='GLPK/exact') """ # inherited __cinit__ is called automatically import sage.numerical.backends.glpk_backend as glpk_backend @@ -58,17 +57,17 @@ cdef class GLPKExactBackend(GLPKBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integer (default: ``False``). + - ``integer`` -- ``True`` if the variable is integer (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -126,17 +125,17 @@ cdef class GLPKExactBackend(GLPKBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is binary (default: ``True``). + - ``continuous`` -- ``True`` if the variable is binary (default: ``True``) - - ``integer`` -- ``True`` if the variable is binary (default: ``False``). + - ``integer`` -- ``True`` if the variable is binary (default: ``False``) - - ``obj`` -- (optional) coefficient of all variables in the objective function (default: 0.0) + - ``obj`` -- coefficient of all variables in the objective function (default: 0.0) - - ``names`` -- optional list of names (default: ``None``) + - ``names`` -- list of names (default: ``None``) - OUTPUT: The index of the variable created last. + OUTPUT: the index of the variable created last EXAMPLES:: @@ -166,9 +165,9 @@ cdef class GLPKExactBackend(GLPKBackend): INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``vtype`` (integer) : + - ``vtype`` -- integer: * 1 Integer * 0 Binary diff --git a/src/sage/numerical/backends/glpk_exact_backend_test.py b/src/sage/numerical/backends/glpk_exact_backend_test.py index cffc87e3844..125e041f29e 100644 --- a/src/sage/numerical/backends/glpk_exact_backend_test.py +++ b/src/sage/numerical/backends/glpk_exact_backend_test.py @@ -7,4 +7,4 @@ class TestGLPKExactBackend(GenericBackendTests): @pytest.fixture def backend(self) -> GenericBackend: - return MixedIntegerLinearProgram(solver="GLPK/exact").get_backend() + return MixedIntegerLinearProgram(solver='GLPK/exact').get_backend() diff --git a/src/sage/numerical/backends/glpk_graph_backend.pyx b/src/sage/numerical/backends/glpk_graph_backend.pyx index 63bc2a76305..514e1b9676b 100644 --- a/src/sage/numerical/backends/glpk_graph_backend.pyx +++ b/src/sage/numerical/backends/glpk_graph_backend.pyx @@ -16,21 +16,21 @@ Methods index :widths: 30, 70 :delim: | - :meth:`~GLPKGraphBackend.add_vertex` | Adds an isolated vertex to the graph. - :meth:`~GLPKGraphBackend.add_vertices` | Adds vertices from an iterable container of vertices. - :meth:`~GLPKGraphBackend.set_vertex_demand` | Sets the vertex parameters. - :meth:`~GLPKGraphBackend.set_vertices_demand` | Sets the parameters of selected vertices. - :meth:`~GLPKGraphBackend.get_vertex` | Returns a specific vertex as a ``dict`` Object. - :meth:`~GLPKGraphBackend.get_vertices` | Returns a dictionary of the dictionaries associated to each vertex. - :meth:`~GLPKGraphBackend.vertices` | Returns a ``list`` of all vertices. - :meth:`~GLPKGraphBackend.delete_vertex` | Removes a vertex from the graph. - :meth:`~GLPKGraphBackend.delete_vertices` | Removes vertices from the graph. - :meth:`~GLPKGraphBackend.add_edge` | Adds an edge between vertices ``u`` and ``v``. - :meth:`~GLPKGraphBackend.add_edges` | Adds edges to the graph. - :meth:`~GLPKGraphBackend.get_edge` | Returns an edge connecting two vertices. - :meth:`~GLPKGraphBackend.edges` | Returns a ``list`` of all edges in the graph. - :meth:`~GLPKGraphBackend.delete_edge` | Deletes an edge from the graph. - :meth:`~GLPKGraphBackend.delete_edges` | Deletes edges from the graph. + :meth:`~GLPKGraphBackend.add_vertex` | Add an isolated vertex to the graph. + :meth:`~GLPKGraphBackend.add_vertices` | Add vertices from an iterable container of vertices. + :meth:`~GLPKGraphBackend.set_vertex_demand` | Set the vertex parameters. + :meth:`~GLPKGraphBackend.set_vertices_demand` | Set the parameters of selected vertices. + :meth:`~GLPKGraphBackend.get_vertex` | Return a specific vertex as a dictionary Object. + :meth:`~GLPKGraphBackend.get_vertices` | Return a dictionary of the dictionaries associated to each vertex. + :meth:`~GLPKGraphBackend.vertices` | Return a ``list`` of all vertices. + :meth:`~GLPKGraphBackend.delete_vertex` | Remove a vertex from the graph. + :meth:`~GLPKGraphBackend.delete_vertices` | Remove vertices from the graph. + :meth:`~GLPKGraphBackend.add_edge` | Add an edge between vertices ``u`` and ``v``. + :meth:`~GLPKGraphBackend.add_edges` | Add edges to the graph. + :meth:`~GLPKGraphBackend.get_edge` | Return an edge connecting two vertices. + :meth:`~GLPKGraphBackend.edges` | Return a ``list`` of all edges in the graph. + :meth:`~GLPKGraphBackend.delete_edge` | Delete an edge from the graph. + :meth:`~GLPKGraphBackend.delete_edges` | Delete edges from the graph. **Graph writing operations:** @@ -39,10 +39,10 @@ Methods index :widths: 30, 70 :delim: | - :meth:`~GLPKGraphBackend.write_graph` | Writes the graph to a plain text file. - :meth:`~GLPKGraphBackend.write_ccdata` | Writes the graph to a text file in DIMACS format. - :meth:`~GLPKGraphBackend.write_mincost` | Writes the mincost flow problem data to a text file in DIMACS format. - :meth:`~GLPKGraphBackend.write_maxflow` | Writes the maximum flow problem data to a text file in DIMACS format. + :meth:`~GLPKGraphBackend.write_graph` | Write the graph to a plain text file. + :meth:`~GLPKGraphBackend.write_ccdata` | Write the graph to a text file in DIMACS format. + :meth:`~GLPKGraphBackend.write_mincost` | Write the mincost flow problem data to a text file in DIMACS format. + :meth:`~GLPKGraphBackend.write_maxflow` | Write the maximum flow problem data to a text file in DIMACS format. **Network optimization operations:** @@ -51,9 +51,9 @@ Methods index :widths: 30, 70 :delim: | - :meth:`~GLPKGraphBackend.mincost_okalg` | Finds solution to the mincost problem with the out-of-kilter algorithm. - :meth:`~GLPKGraphBackend.maxflow_ffalg` | Finds solution to the maxflow problem with Ford-Fulkerson algorithm. - :meth:`~GLPKGraphBackend.cpp` | Solves the critical path problem of a project network. + :meth:`~GLPKGraphBackend.mincost_okalg` | Find solution to the mincost problem with the out-of-kilter algorithm. + :meth:`~GLPKGraphBackend.maxflow_ffalg` | Find solution to the maxflow problem with Ford-Fulkerson algorithm. + :meth:`~GLPKGraphBackend.cpp` | Solve the critical path problem of a project network. Classes and methods ------------------- @@ -79,14 +79,14 @@ from sage.numerical.mip import MIPSolverException cdef class GLPKGraphBackend(): """ - GLPK Backend for access to GLPK graph functions + GLPK Backend for access to GLPK graph functions. The constructor can either be called without arguments (which results in an empty graph) or with arguments to read graph data from a file. INPUT: - - ``data`` -- a filename or a :class:`Graph` object. + - ``data`` -- a filename or a :class:`Graph` object - ``format`` -- when ``data`` is a filename, specifies the format of the data read from a file. The ``format`` parameter is a string and can take @@ -143,7 +143,7 @@ cdef class GLPKGraphBackend(): * edges -- The edge values used in the algorithms are read from the edges labels (and left undefined if the edge labels are equal to - ``None``). To be defined, the labels must be ``dict`` objects with + ``None``). To be defined, the labels must be dictionary objects with keys "low", "cap" and "cost". See :meth:`get_edge` for details. EXAMPLES: @@ -185,7 +185,7 @@ cdef class GLPKGraphBackend(): def __cinit__(self, data = None, format = "plain"): """ - Constructor + Constructor. The constructor can either be called without arguments creating an empty graph or with arguments to read graph data from a file or a Sage @@ -233,17 +233,17 @@ cdef class GLPKGraphBackend(): cpdef add_vertex(self, name=None): """ - Adds an isolated vertex to the graph. + Add an isolated vertex to the graph. If the vertex already exists, nothing is done. INPUT: - - ``name`` -- ``str`` of max 255 chars length. If no name is - specified, then the vertex will be represented by the string - representation of the ID of the vertex or - if this already exists - - a string representation of the least integer not already representing - a vertex. + - ``name`` -- string of max 255 chars length. If no name is + specified, then the vertex will be represented by the string + representation of the ID of the vertex or - if this already exists - + a string representation of the least integer not already representing + a vertex. OUTPUT: @@ -287,7 +287,7 @@ cdef class GLPKGraphBackend(): cpdef __add_vertices_sage(self, g): """ - Adds vertices to the GLPK Graph. + Add vertices to the GLPK Graph. This function is only used when importing a :class:`~sage.graphs.generic_graph.GenericGraph` object. @@ -329,14 +329,14 @@ cdef class GLPKGraphBackend(): cpdef list add_vertices(self, vertices): """ - Adds vertices from an iterable container of vertices. + Add vertices from an iterable container of vertices. Vertices that already exist in the graph will not be added again. INPUT: - - ``vertices`` -- iterator of vertex labels (``str``). A label can be - ``None``. + - ``vertices`` -- iterator of vertex labels (string); a label can be + ``None`` OUTPUT: @@ -381,11 +381,11 @@ cdef class GLPKGraphBackend(): cpdef set_vertex_demand(self, vertex, demand): """ - Sets the demand of the vertex in a mincost flow algorithm. + Set the demand of the vertex in a mincost flow algorithm. INPUT: - - ``vertex`` -- Name of the vertex + - ``vertex`` -- name of the vertex - ``demand`` -- the numerical value representing demand of the vertex in a mincost flow algorithm (it could be for instance `-1` to represent a @@ -418,11 +418,11 @@ cdef class GLPKGraphBackend(): cpdef set_vertices_demand(self, list pairs): """ - Sets the parameters of selected vertices. + Set the parameters of selected vertices. INPUT: - - ``pairs`` -- A list of pairs ``(vertex, demand)`` associating a demand + - ``pairs`` -- list of pairs ``(vertex, demand)`` associating a demand to each vertex. For more information, see the documentation of :meth:`set_vertex_demand`. @@ -446,16 +446,16 @@ cdef class GLPKGraphBackend(): cpdef dict get_vertex(self, vertex): """ - Returns a specific vertex as a ``dict`` Object. + Return a specific vertex as a dictionary Object. INPUT: - - ``vertex`` -- The vertex label as ``str``. + - ``vertex`` -- the vertex label as string OUTPUT: - The vertex as a ``dict`` object or ``None`` if the vertex does not - exist. The ``dict`` contains the values used or created by the different + The vertex as a dictionary object or ``None`` if the vertex does not + exist. The dictionary contains the values used or created by the different algorithms. The values associated with the keys following keys contain: * "rhs" -- The supply / demand value the vertex (mincost alg) @@ -493,7 +493,7 @@ cdef class GLPKGraphBackend(): cpdef dict get_vertices(self, verts): """ - Returns a dictionary of the dictionaries associated to each vertex. + Return a dictionary of the dictionaries associated to each vertex. INPUT: @@ -522,7 +522,7 @@ cdef class GLPKGraphBackend(): cpdef list vertices(self): """ - Returns the list of all vertices + Return the list of all vertices. .. NOTE:: @@ -554,25 +554,25 @@ cdef class GLPKGraphBackend(): cpdef add_edge(self, u, v, dict params=None): """ - Adds an edge between vertices ``u`` and ``v``. + Add an edge between vertices ``u`` and ``v``. Allows adding an edge and optionally providing parameters used by the algorithms. If a vertex does not exist it is created. INPUT: - - ``u`` -- The name (as ``str``) of the tail vertex + - ``u`` -- the name (as string) of the tail vertex - - ``v`` -- The name (as ``str``) of the head vertex + - ``v`` -- the name (as string) of the head vertex - - ``params`` -- An optional ``dict`` containing the edge parameters used + - ``params`` -- an optional dictionary containing the edge parameters used for the algorithms. The following keys are used: - * ``low`` -- The minimum flow through the edge + * ``low`` -- the minimum flow through the edge - * ``cap`` -- The maximum capacity of the edge + * ``cap`` -- the maximum capacity of the edge - * ``cost`` -- The cost of transporting one unit through the edge + * ``cost`` -- the cost of transporting one unit through the edge EXAMPLES:: @@ -618,14 +618,14 @@ cdef class GLPKGraphBackend(): cpdef list add_edges(self, edges): """ - Adds edges to the graph. + Add edges to the graph. INPUT: - - ``edges`` -- An iterable container of pairs of the form ``(u, v)``, - where ``u`` is name (as ``str``) of the tail vertex and ``v`` is the - name (as ``str``) of the head vertex or an iterable container of - triples of the form ``(u, v, params)`` where params is a ``dict`` as + - ``edges`` -- an iterable container of pairs of the form ``(u, v)``, + where ``u`` is name (as string) of the tail vertex and ``v`` is the + name (as string) of the head vertex or an iterable container of + triples of the form ``(u, v, params)`` where params is a dictionary as described in ``add_edge``. EXAMPLES:: @@ -656,7 +656,7 @@ cdef class GLPKGraphBackend(): cpdef __add_edges_sage(self, g): """ - Adds edges to the Graph. + Add edges to the Graph. This function is only used when importing a ``GenericGraph``. @@ -711,7 +711,7 @@ cdef class GLPKGraphBackend(): cpdef tuple get_edge(self, u, v): """ - Returns an edge connecting two vertices. + Return an edge connecting two vertices. .. NOTE:: @@ -720,19 +720,19 @@ cdef class GLPKGraphBackend(): INPUT: - - ``u`` -- Name (as ``str``) of the tail vertex - - ``v`` -- Name (as ``str``) of the head vertex + - ``u`` -- name (as string) of the tail vertex + - ``v`` -- name (as string) of the head vertex OUTPUT: A ``triple`` describing if edge was found or ``None`` if not. The third - value of the triple is a ``dict`` containing the following edge + value of the triple is a dictionary containing the following edge parameters: - * ``low`` -- The minimum flow through the edge - * ``cap`` -- The maximum capacity of the edge - * ``cost`` -- The cost of transporting one unit through the edge - * ``x`` -- The actual flow through the edge after solving + * ``low`` -- the minimum flow through the edge + * ``cap`` -- the maximum capacity of the edge + * ``cost`` -- the cost of transporting one unit through the edge + * ``x`` -- the actual flow through the edge after solving EXAMPLES:: @@ -767,11 +767,9 @@ cdef class GLPKGraphBackend(): cpdef list edges(self): """ - Returns a ``list`` of all edges in the graph + Return a ``list`` of all edges in the graph. - OUTPUT: - - A ``list`` of ``triples`` representing the edges of the graph. + OUTPUT: a ``list`` of ``triples`` representing the edges of the graph EXAMPLES:: @@ -822,7 +820,7 @@ cdef class GLPKGraphBackend(): INPUT: - - ``vert`` -- The name (as ``str``) of the vertex to delete. + - ``vert`` -- the name (as string) of the vertex to delete EXAMPLES:: @@ -858,7 +856,7 @@ cdef class GLPKGraphBackend(): INPUT: - - ``verts`` -- iterable container containing names (as ``str``) of the + - ``verts`` -- iterable container containing names (as string) of the vertices to delete EXAMPLES:: @@ -896,15 +894,15 @@ cdef class GLPKGraphBackend(): cpdef delete_edge(self, u, v, dict params=None): """ - Deletes an edge from the graph. + Delete an edge from the graph. If an edge does not exist it is ignored. INPUT: - - ``u`` -- The name (as ``str``) of the tail vertex of the edge - - ``v`` -- The name (as ``str``) of the tail vertex of the edge - - ``params`` -- ``params`` -- An optional ``dict`` containing the edge + - ``u`` -- the name (as string) of the tail vertex of the edge + - ``v`` -- the name (as string) of the tail vertex of the edge + - ``params`` -- an optional dictionary containing the edge parameters (see :meth:`add_edge`). If this parameter is not provided, all edges connecting ``u`` and ``v`` are deleted. Otherwise only edges with matching parameters are deleted. @@ -975,13 +973,13 @@ cdef class GLPKGraphBackend(): def delete_edges(self, edges): """ - Deletes edges from the graph. + Delete edges from the graph. Non existing edges are ignored. INPUT: - - ``edges`` -- An iterable container of edges. + - ``edges`` -- an iterable container of edges .. SEEALSO:: @@ -1008,15 +1006,13 @@ cdef class GLPKGraphBackend(): cpdef int _find_vertex(self, name) noexcept: """ - Returns the index of a vertex specified by a name + Return the index of a vertex specified by a name INPUT: - - ``name`` -- Name of the vertex - - OUTPUT: + - ``name`` -- name of the vertex - The index of the vertex or ``-1`` if the vertex is not found + OUTPUT: the index of the vertex or ``-1`` if the vertex is not found EXAMPLES:: @@ -1041,9 +1037,7 @@ cdef class GLPKGraphBackend(): - ``fname`` -- full name of the file - OUTPUT: - - Zero if the operations was successful otherwise nonzero + OUTPUT: zero if the operations was successful otherwise nonzero EXAMPLES:: @@ -1073,9 +1067,7 @@ cdef class GLPKGraphBackend(): - ``fname`` -- full name of the file - OUTPUT: - - Zero if the operations was successful otherwise nonzero + OUTPUT: zero if the operations was successful otherwise nonzero EXAMPLES:: @@ -1099,11 +1091,9 @@ cdef class GLPKGraphBackend(): INPUT: - - ``fname`` -- Full name of file + - ``fname`` -- full name of file - OUTPUT: - - Zero if successful, otherwise nonzero + OUTPUT: zero if successful, otherwise nonzero EXAMPLES:: @@ -1198,11 +1188,11 @@ cdef class GLPKGraphBackend(): INPUT: - - ``fname`` -- Full name of file + - ``fname`` -- full name of file OUTPUT: - ``Zero`` if successful, otherwise ``non-zero`` + ``Zero`` if successful, otherwise ``nonzero`` EXAMPLES:: @@ -1224,7 +1214,6 @@ cdef class GLPKGraphBackend(): Writing maximum flow problem data to ... 6 lines were written 0 - """ if self.graph.nv <= 0: @@ -1240,8 +1229,8 @@ cdef class GLPKGraphBackend(): INPUT: - - ``u`` -- Name (as ``str``) of the tail vertex. Default is ``None``. - - ``v`` -- Name (as ``str``) of the head vertex. Default is ``None``. + - ``u`` -- name (as string) of the tail vertex; default is ``None`` + - ``v`` -- name (as string) of the head vertex; default is ``None`` If ``u`` or ``v`` are ``None``, the currently stored values for the head or tail vertex are used. This behavior is useful when reading @@ -1249,16 +1238,14 @@ cdef class GLPKGraphBackend(): ``u`` and ``v``, the head and tail vertex are stored for later use. - OUTPUT: - - The solution to the maxflow problem, i.e. the maximum flow. + OUTPUT: the solution to the maxflow problem, i.e. the maximum flow .. NOTE:: - * If the source or sink vertex does not exist, an ``IndexError`` is + * If the source or sink vertex does not exist, an :exc:`IndexError` is raised. - * If the source and sink are identical, a ``ValueError`` is raised. + * If the source and sink are identical, a :exc:`ValueError` is raised. * This method raises ``MIPSolverException`` exceptions when the solution cannot be computed for any reason (none exists, or the @@ -1324,11 +1311,9 @@ cdef class GLPKGraphBackend(): cpdef double cpp(self) noexcept: r""" - Solves the critical path problem of a project network. - - OUTPUT: + Solve the critical path problem of a project network. - The length of the critical path of the network + OUTPUT: the length of the critical path of the network EXAMPLES:: diff --git a/src/sage/numerical/backends/interactivelp_backend.pyx b/src/sage/numerical/backends/interactivelp_backend.pyx index a61fac176fb..ea1a53aedce 100644 --- a/src/sage/numerical/backends/interactivelp_backend.pyx +++ b/src/sage/numerical/backends/interactivelp_backend.pyx @@ -43,7 +43,7 @@ cdef class InteractiveLPBackend: def __cinit__(self, maximization = True, base_ring = None): """ - Cython constructor + Cython constructor. EXAMPLES:: @@ -83,7 +83,7 @@ cdef class InteractiveLPBackend: cpdef __copy__(self): """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -108,9 +108,7 @@ cdef class InteractiveLPBackend: """ Return the base ring. - OUTPUT: - - A ring. The coefficients that the chosen solver supports. + OUTPUT: a ring; the coefficients that the chosen solver supports EXAMPLES:: @@ -131,9 +129,7 @@ cdef class InteractiveLPBackend: - ``upper_bound`` -- the upper bound of the variable - OUTPUT: - - - a string, one of "", "<=", ">=" + OUTPUT: string, one of ``''``, ``'<='``, ``'>='`` The function raises an error if this pair of bounds cannot be represented by an `InteractiveLPProblem` variable type. @@ -189,21 +185,21 @@ cdef class InteractiveLPBackend: - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integral (default: ``False``). + - ``integer`` -- ``True`` if the variable is integral (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - ``coefficients`` -- (optional) an iterable of pairs ``(i, v)``. In each pair, ``i`` is a variable index (integer) and ``v`` is a value (element of :meth:`base_ring`). - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -262,9 +258,9 @@ cdef class InteractiveLPBackend: INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``vtype`` (integer) : + - ``vtype`` -- integer: * 1 Integer * 0 Binary @@ -312,7 +308,7 @@ cdef class InteractiveLPBackend: INPUT: - - ``sense`` (integer) : + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -343,9 +339,9 @@ cdef class InteractiveLPBackend: INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient + - ``coeff`` -- double; its coefficient EXAMPLES:: @@ -371,11 +367,12 @@ cdef class InteractiveLPBackend: cpdef objective_constant_term(self, d=None): """ - Set or get the constant term in the objective function + Set or get the constant term in the objective function. INPUT: - - ``d`` (double) -- its coefficient. If `None` (default), return the current value. + - ``d`` -- double; its coefficient. If ``None`` (default), return the + current value. EXAMPLES:: @@ -401,10 +398,11 @@ cdef class InteractiveLPBackend: INPUT: - - ``coeff`` -- a list of real values, whose i-th element is the - coefficient of the i-th variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (real) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- real; the constant term in the linear function (set to `0` + by default) EXAMPLES:: @@ -437,7 +435,6 @@ cdef class InteractiveLPBackend: sage: p.set_objective(-x - y - 7) sage: p.solve() -47/5 - """ A, b, _, x, constraint_types, variable_types, problem_type, ring, _ = self._AbcxCVPRd() c = coeff @@ -447,11 +444,11 @@ cdef class InteractiveLPBackend: cpdef set_verbosity(self, int level): """ - Set the log (verbosity) level + Set the log (verbosity) level. INPUT: - - ``level`` (integer) -- From 0 (no verbosity) to 3. + - ``level`` -- integer; from 0 (no verbosity) to 3 EXAMPLES:: @@ -467,11 +464,11 @@ cdef class InteractiveLPBackend: INPUT: - - ``i`` -- index of the constraint to remove. + - ``i`` -- index of the constraint to remove EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="InteractiveLP") + sage: p = MixedIntegerLinearProgram(solver='InteractiveLP') sage: v = p.new_variable(nonnegative=True) sage: x,y = v[0], v[1] sage: p.add_constraint(2*x + 3*y, max = 6) @@ -506,12 +503,12 @@ cdef class InteractiveLPBackend: value (element of :meth:`base_ring`). - ``lower_bound`` -- element of :meth:`base_ring` or - ``None``. The lower bound. + ``None``; the lower bound - ``upper_bound`` -- element of :meth:`base_ring` or - ``None``. The upper bound. + ``None``; the upper bound - - ``name`` -- string or ``None``. Optional name for this row. + - ``name`` -- string or ``None``; optional name for this row EXAMPLES:: @@ -562,11 +559,11 @@ cdef class InteractiveLPBackend: INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint @@ -574,8 +571,7 @@ cdef class InteractiveLPBackend: .. NOTE:: - ``indices`` and ``coeffs`` are expected to be of the same - length. + ``indices`` and ``coeffs`` are expected to be of the same length. EXAMPLES:: @@ -741,11 +737,11 @@ cdef class InteractiveLPBackend: cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: @@ -766,11 +762,11 @@ cdef class InteractiveLPBackend: cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -804,7 +800,7 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -839,7 +835,7 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -875,7 +871,7 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -887,7 +883,6 @@ cdef class InteractiveLPBackend: 0 sage: p.is_variable_binary(0) False - """ return False @@ -897,7 +892,7 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -918,7 +913,7 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -930,17 +925,16 @@ cdef class InteractiveLPBackend: 0 sage: p.is_variable_continuous(0) True - """ return True cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: @@ -949,26 +943,25 @@ cdef class InteractiveLPBackend: sage: p.add_linear_constraints(1, 2, None, names=['Empty constraint 1']) sage: p.row_name(0) 'Empty constraint 1' - """ return self.row_names[index] cpdef col_name(self, int index): """ - Return the ``index``-th column name + Return the ``index``-th column name. INPUT: - - ``index`` (integer) -- the column id + - ``index`` -- integer; the column id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver sage: p = get_solver(solver = "InteractiveLP") - sage: p.add_variable(name="I_am_a_variable") + sage: p.add_variable(name='I_am_a_variable') 0 sage: p.col_name(0) 'I_am_a_variable' @@ -977,11 +970,11 @@ cdef class InteractiveLPBackend: cpdef variable_upper_bound(self, int index, value=False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``False`` @@ -1021,11 +1014,11 @@ cdef class InteractiveLPBackend: cpdef variable_lower_bound(self, int index, value=False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has no lower bound. When set to ``False`` @@ -1072,12 +1065,12 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="InteractiveLP") + solver='InteractiveLP') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -1102,12 +1095,12 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="InteractiveLP") + solver='InteractiveLP') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -1132,12 +1125,12 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="InteractiveLP") + solver='InteractiveLP') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -1162,12 +1155,12 @@ cdef class InteractiveLPBackend: INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="InteractiveLP") + solver='InteractiveLP') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -1192,7 +1185,7 @@ cdef class InteractiveLPBackend: EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="InteractiveLP") + solver='InteractiveLP') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) @@ -1215,19 +1208,17 @@ cdef class InteractiveLPBackend: sage: lp, basis = p.interactive_lp_problem() sage: lp.dictionary(*basis).basic_solution() (17/8, 0) - """ return self.final_dictionary cpdef interactive_lp_problem(self): - """ Return the :class:`InteractiveLPProblem` object associated with this backend. EXAMPLES:: sage: p = MixedIntegerLinearProgram(maximization=True,\ - solver="InteractiveLP") + solver='InteractiveLP') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(-x[0] + x[1] <= 2) sage: p.add_constraint(8 * x[0] + 2 * x[1] <= 17) diff --git a/src/sage/numerical/backends/interactivelp_backend_test.py b/src/sage/numerical/backends/interactivelp_backend_test.py index 0f0af51250d..5523c40ce1f 100644 --- a/src/sage/numerical/backends/interactivelp_backend_test.py +++ b/src/sage/numerical/backends/interactivelp_backend_test.py @@ -7,4 +7,4 @@ class TestInteractiveLPBackend(GenericBackendTests): @pytest.fixture def backend(self) -> GenericBackend: - return MixedIntegerLinearProgram(solver="InteractiveLP").get_backend() + return MixedIntegerLinearProgram(solver='InteractiveLP').get_backend() diff --git a/src/sage/numerical/backends/logging_backend.py b/src/sage/numerical/backends/logging_backend.py index 2efb77eaf08..d2d7bd98299 100644 --- a/src/sage/numerical/backends/logging_backend.py +++ b/src/sage/numerical/backends/logging_backend.py @@ -91,7 +91,6 @@ def m(self, *args, **kwdargs): return m class LoggingBackend(GenericBackend): - """ See :class:`LoggingBackendFactory` for documentation. @@ -225,7 +224,6 @@ def _test_{name}(cls, tester=None, **options): Traceback (most recent call last): ... NotImplementedError - """ p = cls() # fresh instance of the backend if tester is None: @@ -336,7 +334,6 @@ def LoggingBackendFactory(solver=None, printing=True, doctest_file=None, test_me | Traceback (most recent call last): | ... | NotImplementedError - | | ... | p = cls() # fresh instance of the backend | if tester is None: @@ -351,7 +348,6 @@ def LoggingBackendFactory(solver=None, printing=True, doctest_file=None, test_me If ``test_method_file`` is not provided, a default output file name will be computed from ``test_method``. - """ if test_method is not None: diff --git a/src/sage/numerical/backends/matrix_sdp_backend.pyx b/src/sage/numerical/backends/matrix_sdp_backend.pyx index 7e108018275..aad7fc4be68 100644 --- a/src/sage/numerical/backends/matrix_sdp_backend.pyx +++ b/src/sage/numerical/backends/matrix_sdp_backend.pyx @@ -26,13 +26,12 @@ cdef class MatrixSDPBackend(GenericSDPBackend): def __init__(self, maximization=True, base_ring=None): """ - Cython constructor + Cython constructor. EXAMPLES:: sage: from sage.numerical.backends.generic_sdp_backend import get_solver sage: p = get_solver(solver = "CVXOPT") - """ self.objective_function = [] self.name = "" @@ -56,7 +55,7 @@ cdef class MatrixSDPBackend(GenericSDPBackend): cpdef base_ring(self): """ - The base ring + The base ring. TESTS:: @@ -68,11 +67,11 @@ cdef class MatrixSDPBackend(GenericSDPBackend): def get_matrix(self): """ - Get a block of a matrix coefficient + Get a block of a matrix coefficient. EXAMPLES:: - sage: p = SemidefiniteProgram(solver="cvxopt") + sage: p = SemidefiniteProgram(solver='cvxopt') sage: x = p.new_variable() sage: a1 = matrix([[1, 2.], [2., 3.]]) sage: a2 = matrix([[3, 4.], [4., 5.]]) @@ -83,7 +82,6 @@ cdef class MatrixSDPBackend(GenericSDPBackend): [-1.0 -2.0] -1, [-2.0 -3.0] ) - """ return self.coeffs_matrix @@ -96,11 +94,13 @@ cdef class MatrixSDPBackend(GenericSDPBackend): INPUT: - - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) + - ``obj`` -- (optional) coefficient of this variable in the objective + function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: + ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -143,9 +143,9 @@ cdef class MatrixSDPBackend(GenericSDPBackend): - ``n`` -- the number of new variables (must be > 0) - - ``names`` -- optional list of names (default: ``None``) + - ``names`` -- list of names (default: ``None``) - OUTPUT: The index of the variable created last. + OUTPUT: the index of the variable created last EXAMPLES:: @@ -170,7 +170,7 @@ cdef class MatrixSDPBackend(GenericSDPBackend): INPUT: - - ``sense`` (integer) + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -197,9 +197,9 @@ cdef class MatrixSDPBackend(GenericSDPBackend): INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient + - ``coeff`` -- double; its coefficient EXAMPLES:: @@ -224,10 +224,11 @@ cdef class MatrixSDPBackend(GenericSDPBackend): INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: @@ -272,7 +273,7 @@ cdef class MatrixSDPBackend(GenericSDPBackend): [-7.00000000000000 -11.0000000000000] [-11.0000000000000 3.00000000000000] ]) - sage: p.add_linear_constraint( [(0, matrix([[33., -9.], [-9., 26.]])) , (1, matrix([[-7., -11.] ,[ -11., 3.]]) )],name="fun") + sage: p.add_linear_constraint( [(0, matrix([[33., -9.], [-9., 26.]])) , (1, matrix([[-7., -11.] ,[ -11., 3.]]) )],name='fun') sage: p.row_name(-1) 'fun' """ @@ -296,7 +297,7 @@ cdef class MatrixSDPBackend(GenericSDPBackend): INPUT: - - ``number`` (integer) -- the number of constraints to add. + - ``number`` -- integer; the number of constraints to add - ``names`` -- an optional list of names (default: ``None``) @@ -371,11 +372,11 @@ cdef class MatrixSDPBackend(GenericSDPBackend): cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``NULL`` (default), the method returns the problem's name. EXAMPLES:: @@ -393,11 +394,11 @@ cdef class MatrixSDPBackend(GenericSDPBackend): cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -433,20 +434,19 @@ cdef class MatrixSDPBackend(GenericSDPBackend): cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: sage: from sage.numerical.backends.generic_sdp_backend import get_solver sage: p = get_solver(solver = "CVXOPT") - sage: p.add_linear_constraints(1, names="A") + sage: p.add_linear_constraints(1, names='A') sage: p.row_name(0) 'A' - """ if self.row_name_var[index] is not None: return self.row_name_var[index] @@ -454,14 +454,14 @@ cdef class MatrixSDPBackend(GenericSDPBackend): cpdef col_name(self, int index): """ - Return the ``index`` th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: diff --git a/src/sage/numerical/backends/ppl_backend.pyx b/src/sage/numerical/backends/ppl_backend.pyx index 1e53c947c95..24b0c8e80ac 100644 --- a/src/sage/numerical/backends/ppl_backend.pyx +++ b/src/sage/numerical/backends/ppl_backend.pyx @@ -29,7 +29,6 @@ from copy import copy cdef class PPLBackend(GenericBackend): - """ MIP Backend that uses the exact MIP solver from the Parma Polyhedra Library. """ @@ -52,7 +51,7 @@ cdef class PPLBackend(GenericBackend): def __cinit__(self, maximization = True, base_ring = None): """ - Constructor + Constructor. EXAMPLES:: @@ -62,7 +61,7 @@ cdef class PPLBackend(GenericBackend): Raise an error if a ``base_ring`` is requested that is not supported:: - sage: p = MixedIntegerLinearProgram(solver="PPL", base_ring=AA) # needs sage.rings.number_field + sage: p = MixedIntegerLinearProgram(solver='PPL', base_ring=AA) # needs sage.rings.number_field Traceback (most recent call last): ... TypeError: The PPL backend only supports rational data. @@ -100,7 +99,7 @@ cdef class PPLBackend(GenericBackend): cpdef __copy__(self): """ - Returns a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -138,7 +137,7 @@ cdef class PPLBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="PPL") + sage: p = get_solver(solver='PPL') sage: p.base_ring() Rational Field sage: type(p.zero()) @@ -208,7 +207,7 @@ cdef class PPLBackend(GenericBackend): - ``e`` -- a linear expression (type ``Linear_Expression``) - - ``denom`` -- a positive integer + - ``denom`` -- positive integer - ``lower``, ``upper`` -- a rational number or ``None``, where ``None`` means that there is no constraint @@ -217,7 +216,7 @@ cdef class PPLBackend(GenericBackend): Create a linear system with only equalities as constraints:: - sage: p = MixedIntegerLinearProgram(solver="PPL") + sage: p = MixedIntegerLinearProgram(solver='PPL') sage: x = p.new_variable(nonnegative=False) sage: n = 40 sage: v = random_vector(QQ, n) @@ -228,7 +227,6 @@ cdef class PPLBackend(GenericBackend): ....: p.add_constraint(lhs == rhs) sage: p.solve() # long time 0 - """ if lower == upper: if lower is not None: @@ -257,17 +255,17 @@ cdef class PPLBackend(GenericBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integral (default: ``False``). + - ``integer`` -- ``True`` if the variable is integral (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -328,17 +326,17 @@ cdef class PPLBackend(GenericBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``). + - ``continuous`` -- ``True`` if the variable is continuous (default: ``True``) - - ``integer`` -- ``True`` if the variable is integral (default: ``False``). + - ``integer`` -- ``True`` if the variable is integral (default: ``False``) - - ``obj`` -- (optional) coefficient of all variables in the objective function (default: 0) + - ``obj`` -- coefficient of all variables in the objective function (default: 0) - - ``names`` -- optional list of names (default: ``None``) + - ``names`` -- list of names (default: ``None``) - OUTPUT: The index of the variable created last. + OUTPUT: the index of the variable created last EXAMPLES:: @@ -384,9 +382,9 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``vtype`` (integer) : + - ``vtype`` -- integer: * 1 Integer * 0 Binary @@ -437,7 +435,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``sense`` (integer) : + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -464,9 +462,9 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (integer) -- its coefficient + - ``coeff`` -- integer; its coefficient EXAMPLES:: @@ -491,12 +489,12 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="PPL") + sage: p = MixedIntegerLinearProgram(solver='PPL') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(x[0]*5 + x[1]/11 <= 6) sage: p.set_objective(x[0]) @@ -556,7 +554,7 @@ cdef class PPLBackend(GenericBackend): EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="PPL") + sage: p = MixedIntegerLinearProgram(solver='PPL') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(x[0]/2 + x[1]/3 <= 2/5) sage: p.set_objective(x[1]) @@ -600,15 +598,15 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it - appears. Namely, the ith entry of ``coeffs`` corresponds to + appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint - represented by the ith entry in ``indices``. + represented by the i-th entry in ``indices``. .. NOTE:: @@ -644,7 +642,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``number`` (integer) -- the number of constraints to add. + - ``number`` -- integer; the number of constraints to add - ``lower_bound`` -- a lower bound, either a real value or ``None`` @@ -738,7 +736,7 @@ cdef class PPLBackend(GenericBackend): EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="PPL") + sage: p = MixedIntegerLinearProgram(solver='PPL') sage: x = p.new_variable(nonnegative=True) sage: p.add_constraint(5/13*x[0] + x[1]/2 == 8/7) sage: p.set_objective(5/13*x[0] + x[1]/2) @@ -845,11 +843,11 @@ cdef class PPLBackend(GenericBackend): cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: @@ -866,11 +864,11 @@ cdef class PPLBackend(GenericBackend): cpdef row(self, int i): """ - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -905,7 +903,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -933,7 +931,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -961,7 +959,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -982,7 +980,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1003,7 +1001,7 @@ cdef class PPLBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1020,11 +1018,11 @@ cdef class PPLBackend(GenericBackend): cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: @@ -1040,14 +1038,14 @@ cdef class PPLBackend(GenericBackend): cpdef col_name(self, int index): """ - Return the ``index`` th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id - - ``name`` (``char *``) -- its name. When set to ``NULL`` - (default), the method returns the current name. + - ``name`` -- (``char *``) its name; when set to ``NULL`` + (default), the method returns the current name EXAMPLES:: @@ -1064,11 +1062,11 @@ cdef class PPLBackend(GenericBackend): cpdef variable_upper_bound(self, int index, value=False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``False`` @@ -1096,11 +1094,11 @@ cdef class PPLBackend(GenericBackend): cpdef variable_lower_bound(self, int index, value=False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not lower bound. When set to ``False`` diff --git a/src/sage/numerical/backends/ppl_backend_test.py b/src/sage/numerical/backends/ppl_backend_test.py index 852c3be82c1..13ef46e1a3d 100644 --- a/src/sage/numerical/backends/ppl_backend_test.py +++ b/src/sage/numerical/backends/ppl_backend_test.py @@ -9,4 +9,4 @@ class TestPPLBackend(GenericBackendTests): @pytest.fixture def backend(self) -> GenericBackend: - return MixedIntegerLinearProgram(solver="PPL").get_backend() + return MixedIntegerLinearProgram(solver='PPL').get_backend() diff --git a/src/sage/numerical/backends/scip_backend.pyx b/src/sage/numerical/backends/scip_backend.pyx index 7fdedc6a334..4cac8e171e0 100644 --- a/src/sage/numerical/backends/scip_backend.pyx +++ b/src/sage/numerical/backends/scip_backend.pyx @@ -27,7 +27,6 @@ from pyscipopt import Model cdef class SCIPBackend(GenericBackend): - """ MIP Backend that uses the SCIP solver. @@ -35,17 +34,17 @@ cdef class SCIPBackend(GenericBackend): General backend testsuite:: - sage: p = MixedIntegerLinearProgram(solver="SCIP") - sage: TestSuite(p.get_backend()).run(skip="_test_pickling") + sage: p = MixedIntegerLinearProgram(solver='SCIP') + sage: TestSuite(p.get_backend()).run(skip='_test_pickling') """ def __cinit__(self, maximization=True): """ - Constructor + Constructor. EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="SCIP") + sage: p = MixedIntegerLinearProgram(solver='SCIP') """ self.model = Model('') if maximization: @@ -65,7 +64,7 @@ cdef class SCIPBackend(GenericBackend): EXAMPLES:: sage: from sage.numerical.backends.generic_backend import get_solver - sage: lp = get_solver(solver="SCIP") + sage: lp = get_solver(solver='SCIP') sage: lp.add_variables(3) 2 sage: lp.add_linear_constraint(zip([0, 1, 2], [8, 6, 1]), None, 48) @@ -109,17 +108,17 @@ cdef class SCIPBackend(GenericBackend): - ``upper_bound`` -- the upper bound of the variable (default: ``None``) - - ``binary`` -- ``True`` if the variable is binary (default: ``False``). + - ``binary`` -- ``True`` if the variable is binary (default: ``False``) - - ``continuous`` -- ``True`` if the variable is binary (default: ``True``). + - ``continuous`` -- ``True`` if the variable is binary (default: ``True``) - - ``integer`` -- ``True`` if the variable is binary (default: ``False``). + - ``integer`` -- ``True`` if the variable is binary (default: ``False``) - ``obj`` -- (optional) coefficient of this variable in the objective function (default: 0.0) - - ``name`` -- an optional name for the newly added variable (default: ``None``). + - ``name`` -- an optional name for the newly added variable (default: ``None``) - OUTPUT: The index of the newly created variable + OUTPUT: the index of the newly created variable EXAMPLES:: @@ -178,13 +177,13 @@ cdef class SCIPBackend(GenericBackend): cpdef set_variable_type(self, int variable, int vtype): """ - Set the type of a variable + Set the type of a variable. INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``vtype`` (integer): + - ``vtype`` -- integer: * 1 Integer * 0 Binary @@ -213,7 +212,7 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``sense`` (integer): + - ``sense`` -- integer: * +1 => Maximization * -1 => Minimization @@ -239,13 +238,13 @@ cdef class SCIPBackend(GenericBackend): cpdef objective_coefficient(self, int variable, coeff=None): """ - Set or get the coefficient of a variable in the objective function + Set or get the coefficient of a variable in the objective function. INPUT: - - ``variable`` (integer) -- the variable's id + - ``variable`` -- integer; the variable's id - - ``coeff`` (double) -- its coefficient or ``None`` for + - ``coeff`` -- double; its coefficient or ``None`` for reading (default: ``None``) EXAMPLES:: @@ -272,11 +271,11 @@ cdef class SCIPBackend(GenericBackend): cpdef problem_name(self, name=None): """ - Return or define the problem's name + Return or define the problem's name. INPUT: - - ``name`` (``str``) -- the problem's name. When set to + - ``name`` -- string; the problem's name. When set to ``None`` (default), the method returns the problem's name. EXAMPLES:: @@ -298,10 +297,11 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``coeff`` -- a list of real values, whose ith element is the - coefficient of the ith variable in the objective function. + - ``coeff`` -- list of real values, whose i-th element is the + coefficient of the i-th variable in the objective function - - ``d`` (double) -- the constant term in the linear function (set to `0` by default) + - ``d`` -- double; the constant term in the linear function (set to `0` + by default) EXAMPLES:: @@ -320,11 +320,11 @@ cdef class SCIPBackend(GenericBackend): cpdef set_verbosity(self, int level): """ - Set the verbosity level + Set the verbosity level. INPUT: - - ``level`` (integer) -- From 0 (no verbosity) to 1. + - ``level`` -- integer; from 0 (no verbosity) to 1 EXAMPLES:: @@ -348,7 +348,7 @@ cdef class SCIPBackend(GenericBackend): cpdef remove_constraint(self, int i): r""" - Remove a constraint from self. + Remove a constraint from ``self``. INPUT: @@ -371,7 +371,7 @@ cdef class SCIPBackend(GenericBackend): Removing fancy constraints does not make Sage crash:: - sage: MixedIntegerLinearProgram(solver="SCIP").remove_constraint(-2) + sage: MixedIntegerLinearProgram(solver='SCIP').remove_constraint(-2) Traceback (most recent call last): ... ValueError: The constraint's index i must satisfy 0 <= i < number_of_constraints @@ -470,11 +470,11 @@ cdef class SCIPBackend(GenericBackend): cpdef row(self, int index): r""" - Return a row + Return a row. INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -511,7 +511,7 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the constraint's id. + - ``index`` -- integer; the constraint's id OUTPUT: @@ -544,7 +544,7 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id. + - ``index`` -- integer; the variable's id OUTPUT: @@ -579,15 +579,15 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``indices`` (list of integers) -- this list contains the + - ``indices`` -- list of integers; this list contains the indices of the constraints in which the variable's coefficient is nonzero - - ``coeffs`` (list of real values) -- associates a coefficient + - ``coeffs`` -- list of real values; associates a coefficient to the variable in each of the constraints in which it - appears. Namely, the ith entry of ``coeffs`` corresponds to + appears. Namely, the i-th entry of ``coeffs`` corresponds to the coefficient of the variable in the constraint - represented by the ith entry in ``indices``. + represented by the i-th entry in ``indices``. .. NOTE:: @@ -745,7 +745,7 @@ cdef class SCIPBackend(GenericBackend): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="SCIP") + sage: p = MixedIntegerLinearProgram(solver='SCIP') sage: p.solver_parameter("limits/gap", 100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -780,7 +780,7 @@ cdef class SCIPBackend(GenericBackend): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="SCIP") + sage: p = MixedIntegerLinearProgram(solver='SCIP') sage: p.solver_parameter("limits/gap", 100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -916,11 +916,11 @@ cdef class SCIPBackend(GenericBackend): cpdef col_name(self, int index): """ - Return the ``index``th col name + Return the ``index``-th col name. INPUT: - - ``index`` (integer) -- the col's id + - ``index`` -- integer; the col's id EXAMPLES:: @@ -935,11 +935,11 @@ cdef class SCIPBackend(GenericBackend): cpdef row_name(self, int index): """ - Return the ``index`` th row name + Return the ``index``-th row name. INPUT: - - ``index`` (integer) -- the row's id + - ``index`` -- integer; the row's id EXAMPLES:: @@ -957,7 +957,7 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -979,7 +979,7 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1001,7 +1001,7 @@ cdef class SCIPBackend(GenericBackend): INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id EXAMPLES:: @@ -1037,11 +1037,11 @@ cdef class SCIPBackend(GenericBackend): cpdef variable_upper_bound(self, int index, value=False): """ - Return or define the upper bound on a variable + Return or define the upper bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not upper bound. When set to ``False`` @@ -1063,7 +1063,7 @@ cdef class SCIPBackend(GenericBackend): :issue:`14581`:: - sage: P = MixedIntegerLinearProgram(solver="SCIP") + sage: P = MixedIntegerLinearProgram(solver='SCIP') sage: x = P["x"] sage: P.set_max(x, 0) sage: P.get_max(x) @@ -1071,7 +1071,7 @@ cdef class SCIPBackend(GenericBackend): Check that :issue:`10232` is fixed:: - sage: p = get_solver(solver="SCIP") + sage: p = get_solver(solver='SCIP') sage: p.variable_upper_bound(2) Traceback (most recent call last): ... @@ -1098,11 +1098,11 @@ cdef class SCIPBackend(GenericBackend): cpdef variable_lower_bound(self, int index, value=False): """ - Return or define the lower bound on a variable + Return or define the lower bound on a variable. INPUT: - - ``index`` (integer) -- the variable's id + - ``index`` -- integer; the variable's id - ``value`` -- real value, or ``None`` to mean that the variable has not lower bound. When set to ``False`` @@ -1124,7 +1124,7 @@ cdef class SCIPBackend(GenericBackend): :issue:`14581`:: - sage: P = MixedIntegerLinearProgram(solver="SCIP") + sage: P = MixedIntegerLinearProgram(solver='SCIP') sage: x = P["x"] sage: P.set_min(x, 5) sage: P.set_min(x, 0) @@ -1133,7 +1133,7 @@ cdef class SCIPBackend(GenericBackend): Check that :issue:`10232` is fixed:: - sage: p = get_solver(solver="SCIP") + sage: p = get_solver(solver='SCIP') sage: p.variable_lower_bound(2) Traceback (most recent call last): ... @@ -1160,11 +1160,11 @@ cdef class SCIPBackend(GenericBackend): cpdef write_cip(self, filename): """ - Write the problem to a .cip file + Write the problem to a ``.cip`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -1175,7 +1175,7 @@ cdef class SCIPBackend(GenericBackend): sage: p.add_linear_constraint([[0, 1], [1, 2]], None, 3) sage: p.set_objective([2, 5]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".cip") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.cip') as f: ....: p.write_cip(f.name) wrote problem to file ... """ @@ -1183,11 +1183,11 @@ cdef class SCIPBackend(GenericBackend): cpdef write_lp(self, filename): """ - Write the problem to a .lp file + Write the problem to a ``.lp`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -1198,7 +1198,7 @@ cdef class SCIPBackend(GenericBackend): sage: p.add_linear_constraint([[0, 1], [1, 2]], None, 3) sage: p.set_objective([2, 5]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".lp") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.lp') as f: ....: p.write_lp(f.name) wrote problem to file ... """ @@ -1212,11 +1212,11 @@ cdef class SCIPBackend(GenericBackend): cpdef write_mps(self, filename, int modern): """ - Write the problem to a .mps file + Write the problem to a ``.mps`` file. INPUT: - - ``filename`` (string) + - ``filename`` -- string EXAMPLES:: @@ -1227,7 +1227,7 @@ cdef class SCIPBackend(GenericBackend): sage: p.add_linear_constraint([[0, 1], [1, 2]], None, 3) sage: p.set_objective([2, 5]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".mps") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.mps') as f: ....: p.write_mps(f.name, 2) wrote problem to file ... """ @@ -1241,7 +1241,7 @@ cdef class SCIPBackend(GenericBackend): cpdef __copy__(self): """ - Return a copy of self. + Return a copy of ``self``. EXAMPLES:: @@ -1262,19 +1262,19 @@ cdef class SCIPBackend(GenericBackend): cpdef solver_parameter(self, name, value=None): """ - Return or define a solver parameter + Return or define a solver parameter. INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value EXAMPLES: sage: from sage.numerical.backends.generic_backend import get_solver - sage: p = get_solver(solver="SCIP") + sage: p = get_solver(solver='SCIP') sage: p.solver_parameter("limits/time", 1) sage: p.solver_parameter("limits/time") 1.0 diff --git a/src/sage/numerical/gauss_legendre.pyx b/src/sage/numerical/gauss_legendre.pyx index 57d9050057e..4a422e9c6d6 100644 --- a/src/sage/numerical/gauss_legendre.pyx +++ b/src/sage/numerical/gauss_legendre.pyx @@ -62,14 +62,12 @@ def nodes_uncached(degree, prec): INPUT: - - ``degree`` -- integer. The number of nodes. Must be 3 or even. + - ``degree`` -- integer; the number of nodes (must be 3 or even) - - ``prec`` -- integer (minimal value 53). Binary precision with which the - nodes and weights are computed. + - ``prec`` -- integer (minimal value 53); binary precision with which the + nodes and weights are computed - OUTPUT: - - A list of (node, weight) pairs. + OUTPUT: list of (node, weight) pairs EXAMPLES: @@ -172,14 +170,12 @@ def nodes(degree, prec): INPUT: - - ``degree`` -- integer. The number of nodes. Must be 3 or even. - - - ``prec`` -- integer (minimal value 53). Binary precision with which the - nodes and weights are computed. + - ``degree`` -- integer; the number of nodes (must be 3 or even) - OUTPUT: + - ``prec`` -- integer (minimal value 53); binary precision with which the + nodes and weights are computed - A list of (node, weight) pairs. + OUTPUT: list of (node, weight) pairs. EXAMPLES: @@ -211,7 +207,6 @@ def nodes(degree, prec): [(0.11270166537925831148207346002, 0.27777777777777777777777777778), (0.50000000000000000000000000000, 0.44444444444444444444444444444), (0.88729833462074168851792653998, 0.27777777777777777777777777778)] - """ return nodes_uncached(degree, prec) @@ -230,15 +225,15 @@ def estimate_error(results, prec, epsilon): INPUT: - - ``results`` -- list. List of approximations to estimate the error from. Should be at least length 2. + - ``results`` -- list of approximations to estimate the error from; should + be at least length 2 - - ``prec`` -- integer. Binary precision at which computations are happening. + - ``prec`` -- integer; binary precision at which computations are happening - - ``epsilon`` -- multiprecision float. Default error estimate in case of insufficient data. + - ``epsilon`` -- multiprecision float; default error estimate in case of + insufficient data - OUTPUT: - - An estimate of the error. + OUTPUT: an estimate of the error EXAMPLES:: @@ -283,15 +278,13 @@ def integrate_vector_N(f, prec, N=3): INPUT: - - ``f`` -- callable. Vector-valued integrand. - - - ``prec`` -- integer. Binary precision to be used. + - ``f`` -- callable; vector-valued integrand - - ``N`` -- integer (default: 3). Number of nodes to use. + - ``prec`` -- integer; binary precision to be used - OUTPUT: + - ``N`` -- integer (default: 3); number of nodes to use - Vector approximating value of the integral. + OUTPUT: vector approximating value of the integral EXAMPLES:: @@ -308,7 +301,7 @@ def integrate_vector_N(f, prec, N=3): The nodes and weights are calculated in the real field with ``prec`` bits of precision. If the vector space in which ``f`` takes values is over a field which is incompatible with this field (e.g. a finite - field) then a :class:`TypeError` occurs. + field) then a :exc:`TypeError` occurs. """ # We use nodes_uncached, because caching takes up memory, and numerics in # Bruin-DisneyHogg-Gao suggest that caching provides little benefit in the @@ -329,15 +322,14 @@ def integrate_vector(f, prec, epsilon=None): INPUT: - - ``f`` -- callable. Vector-valued integrand. - - - ``prec`` -- integer. Binary precision to be used. + - ``f`` -- callable; vector-valued integrand - - ``epsilon`` -- multiprecision float (default: `2^{(-\text{prec}+3)}`). Target error bound. + - ``prec`` -- integer; binary precision to be used - OUTPUT: + - ``epsilon`` -- multiprecision float (default: `2^{(-\text{prec}+3)}`); + target error bound - Vector approximating value of the integral. + OUTPUT: vector approximating value of the integral EXAMPLES:: diff --git a/src/sage/numerical/interactive_simplex_method.py b/src/sage/numerical/interactive_simplex_method.py index 9a9e12eb9a0..a89da826c77 100644 --- a/src/sage/numerical/interactive_simplex_method.py +++ b/src/sage/numerical/interactive_simplex_method.py @@ -44,7 +44,7 @@ sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P LP problem (use 'view(...)' or '%display typeset' for details) @@ -219,14 +219,12 @@ def _assemble_arrayl(lines, stretch=None): INPUT: - - ``lines`` -- a list of strings suitable for math mode typesetting + - ``lines`` -- list of strings suitable for math mode typesetting - - ``stretch`` -- (default: None) if given, a command setting + - ``stretch`` -- (default: ``None``) if given, a command setting ``\arraystretch`` to this value will be added before the array - OUTPUT: - - - a :class:`LatexExpr` + OUTPUT: a :class:`LatexExpr` EXAMPLES:: @@ -268,11 +266,11 @@ def _latex_product(coefficients, variables, INPUT: - - ``coefficients`` -- a list of coefficients + - ``coefficients`` -- list of coefficients - - ``variables`` -- a list of variables + - ``variables`` -- list of variables - - ``separator`` -- (default: ``"&"`` with some extra space adjustment) a + - ``separator`` -- (default: ``'&'`` with some extra space adjustment) a string to be inserted between elements of the generated expression - ``head`` -- either ``None`` (default) or a list of entries to be @@ -281,10 +279,10 @@ def _latex_product(coefficients, variables, - ``tail`` -- either ``None`` (default) or a list of entries to be added to the end of the output - - ``drop_plus`` -- (default: ``True``) whether to drop the leading plus + - ``drop_plus`` -- boolean (default: ``True``); whether to drop the leading plus sign or not - - ``allow_empty`` -- (default: ``False``) whether to allow empty output or + - ``allow_empty`` -- boolean (default: ``False``); whether to allow empty output or produce at least "0" OUTPUT: @@ -366,9 +364,7 @@ def variable(R, v): - ``v`` -- a variable of ``R`` or convertible into ``R``, a string with the name of a variable of ``R`` or an index of a variable in ``R`` - OUTPUT: - - - a variable of ``R`` + OUTPUT: a variable of ``R`` EXAMPLES:: @@ -452,11 +448,9 @@ def default_variable_name(variable): INPUT: - - ``variable`` -- a string describing requested name - - OUTPUT: + - ``variable`` -- string describing requested name - - a string with the requested name for current style + OUTPUT: string with the requested name for current style EXAMPLES:: @@ -477,13 +471,13 @@ def style(new_style=None): INPUT: - - ``new_style`` -- a string or ``None`` (default) + - ``new_style`` -- string or ``None`` (default) OUTPUT: - a string with current style (same as ``new_style`` if it was given) - If the input is not recognized as a valid style, a ``ValueError`` exception + If the input is not recognized as a valid style, a :exc:`ValueError` exception is raised. Currently supported styles are: @@ -573,25 +567,25 @@ class InteractiveLPProblem(SageObject): - ``c`` -- a vector of objective coefficients - - ``x`` -- (default: ``"x"``) a vector of decision variables or a + - ``x`` -- (default: ``'x'``) a vector of decision variables or a string giving the base name - - ``constraint_type`` -- (default: ``"<="``) a string specifying constraint - type(s): either ``"<="``, ``">="``, ``"=="``, or a list of them + - ``constraint_type`` -- (default: ``'<='``) a string specifying constraint + type(s): either ``'<='``, ``'>='``, ``'=='``, or a list of them - ``variable_type`` -- (default: ``""``) a string specifying variable - type(s): either ``">="``, ``"<="``, ``""`` (the empty string), or a - list of them, corresponding, respectively, to non-negative, - non-positive, and free variables + type(s): either ``'>='``, ``'<='``, ``""`` (the empty string), or a + list of them, corresponding, respectively, to nonnegative, + nonpositive, and free variables - - ``problem_type`` -- (default: ``"max"``) a string specifying the - problem type: ``"max"``, ``"min"``, ``"-max"``, or ``"-min"`` + - ``problem_type`` -- (default: ``'max'``) a string specifying the + problem type: ``'max'``, ``'min'``, ``'-max'``, or ``'-min'`` - ``base_ring`` -- (default: the fraction field of a common ring for all input coefficients) a field to which all input coefficients will be converted - - ``is_primal`` -- (default: ``True``) whether this problem is primal or + - ``is_primal`` -- boolean (default: ``True``); whether this problem is primal or dual: each problem is of course dual to its own dual, this flag is mostly for internal use and affects default variable names only @@ -618,16 +612,16 @@ class InteractiveLPProblem(SageObject): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') Same problem, but more explicitly:: sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], - ....: constraint_type="<=", variable_type=">=") + ....: constraint_type='<=', variable_type='>=') Even more explicitly:: - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], problem_type="max", + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], problem_type='max', ....: constraint_type=["<=", "<="], variable_type=[">=", ">="]) Using the last form you should be able to represent any LP problem, as long @@ -635,8 +629,8 @@ class InteractiveLPProblem(SageObject): are on different sides. """ - def __init__(self, A, b, c, x="x", - constraint_type="<=", variable_type="", problem_type="max", + def __init__(self, A, b, c, x='x', + constraint_type='<=', variable_type='', problem_type='max', base_ring=None, is_primal=True, objective_constant_term=0): r""" See :class:`InteractiveLPProblem` for documentation. @@ -646,7 +640,7 @@ def __init__(self, A, b, c, x="x", sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: TestSuite(P).run() """ super().__init__() @@ -673,7 +667,7 @@ def __init__(self, A, b, c, x="x", x = [str(_) for _ in x] if len(x) != n: raise ValueError("A and x have incompatible dimensions") - R = PolynomialRing(base_ring, x, order="neglex") + R = PolynomialRing(base_ring, x, order='neglex') x = vector(R, R.gens()) # All variables as a vector self._Abcx = A, b, c, x self._constant_term = objective_constant_term @@ -727,11 +721,11 @@ def __eq__(self, other): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") - sage: P2 = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') + sage: P2 = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P == P2 True - sage: P3 = InteractiveLPProblem(A, c, b, ["C", "B"], variable_type=">=") + sage: P3 = InteractiveLPProblem(A, c, b, ["C", "B"], variable_type='>=') sage: P == P3 False """ @@ -747,16 +741,14 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string TESTS:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: print(P._latex_()) \begin{array}{l} \begin{array}{lcrcrcl} @@ -799,16 +791,14 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string TESTS:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: print(P._repr_()) LP problem (use ...) """ @@ -824,16 +814,14 @@ def _solution(self, x): problem, e.g. a vector or a list of correct length or a single element list with such a vector - OUTPUT: - - - ``x`` as a vector + OUTPUT: ``x`` as a vector EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, variable_type='>=') sage: P._solution([100, 200]) (100, 200) sage: P._solution([[100, 200]]) @@ -875,7 +863,7 @@ def _solve(self): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P._solve() ((250, 750), 6250) """ @@ -910,16 +898,14 @@ def Abcx(self): r""" Return `A`, `b`, `c`, and `x` of ``self`` as a tuple. - OUTPUT: - - - a tuple + OUTPUT: a tuple EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.Abcx() ( [1 1] @@ -928,7 +914,7 @@ def Abcx(self): """ return self._Abcx - def add_constraint(self, coefficients, constant_term, constraint_type="<="): + def add_constraint(self, coefficients, constant_term, constraint_type='<='): r""" Return a new LP problem by adding a constraint to``self``. @@ -938,12 +924,10 @@ def add_constraint(self, coefficients, constant_term, constraint_type="<="): - ``constant_term`` -- a constant term of the new constraint - - ``constraint_type`` -- (default: ``"<="``) a string indicating + - ``constraint_type`` -- (default: ``'<='``) a string indicating the constraint type of the new constraint - OUTPUT: - - - an :class:`LP problem ` + OUTPUT: an :class:`LP problem ` EXAMPLES:: @@ -999,21 +983,19 @@ def base_ring(self): The base ring of LP problems is always a field. - OUTPUT: - - - a ring + OUTPUT: a ring EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.base_ring() Rational Field sage: c = (10, 5.) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.base_ring() Real Field with 53 bits of precision """ @@ -1023,16 +1005,14 @@ def constant_terms(self): r""" Return constant terms of constraints of ``self``, i.e. `b`. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.constant_terms() (1000, 1500) sage: P.b() @@ -1044,16 +1024,14 @@ def constraint_coefficients(self): r""" Return coefficients of constraints of ``self``, i.e. `A`. - OUTPUT: - - - a matrix + OUTPUT: a matrix EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.constraint_coefficients() [1 1] [3 1] @@ -1067,16 +1045,14 @@ def constraint_types(self): r""" Return a tuple listing the constraint types of all rows. - OUTPUT: - - - a tuple of strings + OUTPUT: a tuple of strings EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=", constraint_type=["<=", "=="]) + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=', constraint_type=["<=", "=="]) sage: P.constraint_types() ('<=', '==') """ @@ -1086,16 +1062,14 @@ def decision_variables(self): r""" Return decision variables of ``self``, i.e. `x`. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.decision_variables() (C, B) sage: P.x() @@ -1112,16 +1086,14 @@ def dual(self, y=None): - ``y`` -- (default: depends on :func:`style`) a vector of dual decision variables or a string giving the base name - OUTPUT: - - - an :class:`InteractiveLPProblem` + OUTPUT: an :class:`InteractiveLPProblem` EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: DP = P.dual() sage: DP.b() == P.c() True @@ -1179,16 +1151,14 @@ def feasible_set(self): r""" Return the feasible set of ``self``. - OUTPUT: - - - a :mod:`Polyhedron ` + OUTPUT: a :mod:`Polyhedron ` EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.feasible_set() A 2-dimensional polyhedron in QQ^2 defined as the convex hull of 4 vertices @@ -1219,23 +1189,21 @@ def is_bounded(self): r""" Check if ``self`` is bounded. - OUTPUT: - - - ``True`` is ``self`` is bounded, ``False`` otherwise + OUTPUT: ``True`` if ``self`` is bounded, ``False`` otherwise EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.is_bounded() True Note that infeasible problems are always bounded:: sage: b = (-1000, 1500) - sage: P = InteractiveLPProblem(A, b, c, variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, variable_type='>=') sage: P.is_feasible() False sage: P.is_bounded() @@ -1262,7 +1230,7 @@ def is_feasible(self, *x): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, variable_type='>=') sage: P.is_feasible() True sage: P.is_feasible(100, 200) @@ -1282,17 +1250,17 @@ def is_feasible(self, *x): def is_negative(self): r""" - Return `True` when the problem is of type ``"-max"`` or ``"-min"``. + Return ``True`` when the problem is of type ``'-max'`` or ``'-min'``. EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.is_negative() False - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=", problem_type="-min") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=', problem_type='-min') sage: P.is_negative() True """ @@ -1304,16 +1272,14 @@ def is_primal(self): This distinction affects only some automatically chosen variable names. - OUTPUT: - - - boolean + OUTPUT: boolean EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.is_primal() True sage: P.dual().is_primal() @@ -1330,16 +1296,14 @@ def is_optimal(self, *x): - anything that can be interpreted as a valid solution for this problem, i.e. a sequence of values for all decision variables - OUTPUT: - - - ``True`` is the given solution is optimal, ``False`` otherwise + OUTPUT: ``True`` if the given solution is optimal, ``False`` otherwise EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (15, 5) - sage: P = InteractiveLPProblem(A, b, c, variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, variable_type='>=') sage: P.is_optimal(100, 200) False sage: P.is_optimal(500, 0) @@ -1356,16 +1320,14 @@ def n_constraints(self): r""" Return the number of constraints of ``self``, i.e. `m`. - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.n_constraints() 2 sage: P.m() @@ -1377,16 +1339,14 @@ def n_variables(self): r""" Return the number of decision variables of ``self``, i.e. `n`. - OUTPUT: - - - an integer + OUTPUT: integer EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.n_variables() 2 sage: P.n() @@ -1398,16 +1358,14 @@ def objective_coefficients(self): r""" Return coefficients of the objective of ``self``, i.e. `c`. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.objective_coefficients() (10, 5) sage: P.c() @@ -1419,22 +1377,20 @@ def objective_constant_term(self): r""" Return the constant term of the objective. - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.objective_constant_term() 0 sage: P.optimal_value() 6250 sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], - ....: variable_type=">=", objective_constant_term=-1250) + ....: variable_type='>=', objective_constant_term=-1250) sage: P.objective_constant_term() -1250 sage: P.optimal_value() @@ -1461,7 +1417,7 @@ def objective_value(self, *x): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, variable_type='>=') sage: P.objective_value(100, 200) 2000 """ @@ -1472,16 +1428,14 @@ def optimal_solution(self): r""" Return **an** optimal solution of ``self``. - OUTPUT: - - - a vector or ``None`` if there are no optimal solutions + OUTPUT: a vector or ``None`` if there are no optimal solutions EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.optimal_solution() (250, 750) """ @@ -1501,7 +1455,7 @@ def optimal_value(self): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.optimal_value() 6250 """ @@ -1518,9 +1472,7 @@ def plot(self, *args, **kwds): - ``alpha`` -- (default: 0.2) determines how opaque are shadows - OUTPUT: - - - a plot + OUTPUT: a plot This only works for problems with two decision variables. On the plot the black arrow indicates the direction of growth of the objective. The @@ -1536,7 +1488,7 @@ def plot(self, *args, **kwds): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: p = P.plot() # needs sage.plot sage: p.show() # needs sage.plot @@ -1549,7 +1501,7 @@ def plot(self, *args, **kwds): We check that zero objective can be dealt with:: - sage: InteractiveLPProblem(A, b, (0, 0), ["C", "B"], variable_type=">=").plot() # needs sage.plot + sage: InteractiveLPProblem(A, b, (0, 0), ["C", "B"], variable_type='>=').plot() # needs sage.plot Graphics object consisting of 8 graphics primitives """ FP = self.plot_feasible_set(*args, **kwds) @@ -1566,8 +1518,8 @@ def plot(self, *args, **kwds): else [xmin + (xmax-xmin)/2, ymin + (ymax-ymin)/2]) length = min(xmax - xmin, ymax - ymin) / 5 end = start + (c * length / c.norm()).n().change_ring(QQ) - result = FP + point(start, color="black", size=50, zorder=10) - result += arrow(start, end, color="black", zorder=10) + result = FP + point(start, color='black', size=50, zorder=10) + result += arrow(start, end, color='black', zorder=10) ieqs = [(xmax, -1, 0), (- xmin, 1, 0), (ymax, 0, -1), (- ymin, 0, 1)] box = Polyhedron(ieqs=ieqs) @@ -1577,11 +1529,11 @@ def plot(self, *args, **kwds): level = box.intersection(level) if level.vertices(): if i == 0 and self.is_bounded(): - result += line(level.vertices(), color="black", + result += line(level.vertices(), color='black', thickness=2) else: - result += line(level.vertices(), color="black", - linestyle="--") + result += line(level.vertices(), color='black', + linestyle='--') result.set_axes_range(xmin, xmax, ymin, ymax) result.axes_labels(FP.axes_labels()) #FIXME: should be preserved! return result @@ -1598,9 +1550,7 @@ def plot_feasible_set(self, xmin=None, xmax=None, ymin=None, ymax=None, - ``alpha`` -- (default: 0.2) determines how opaque are shadows - OUTPUT: - - - a plot + OUTPUT: a plot This only works for a problem with two decision variables. The plot shows boundaries of constraints with a shadow on one side for @@ -1613,7 +1563,7 @@ def plot_feasible_set(self, xmin=None, xmax=None, ymin=None, ymax=None, sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: p = P.plot_feasible_set() # needs sage.plot sage: p.show() # needs sage.plot @@ -1679,9 +1629,9 @@ def plot_feasible_set(self, xmin=None, xmax=None, ymin=None, ymax=None, halfplane = box.intersection(Polyhedron(ieqs=ieqs)) result += halfplane.render_solid(alpha=alpha, color=color) if F.vertices(): - result += F.render_solid(alpha=alpha, color="gray") + result += F.render_solid(alpha=alpha, color='gray') result += text("$F$", F.center(), - fontsize=20, color="black", zorder=5) + fontsize=20, color='black', zorder=5) result.set_axes_range(xmin, xmax, ymin, ymax) result.axes_labels(["${}$".format(latex(xi)) for xi in x]) result.legend(True) @@ -1697,19 +1647,17 @@ def problem_type(self): Needs to be used together with ``is_negative``. - OUTPUT: - - - a string, one of ``"max"``, ``"min"``. + OUTPUT: string, one of ``'max'``, ``'min'`` EXAMPLES:: sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=') sage: P.problem_type() 'max' - sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type=">=", problem_type="-min") + sage: P = InteractiveLPProblem(A, b, c, ["C", "B"], variable_type='>=', problem_type='-min') sage: P.problem_type() 'min' """ @@ -1721,7 +1669,7 @@ def standard_form(self, transformation=False, **kwds): INPUT: - - ``transformation`` -- (default: ``False``) if ``True``, a map + - ``transformation`` -- boolean (default: ``False``); if ``True``, a map converting solutions of the problem in standard form to the original one will be returned as well @@ -1739,7 +1687,7 @@ def standard_form(self, transformation=False, **kwds): sage: A = ([1, 1], [3, 1]) sage: b = (1000, 1500) sage: c = (10, 5) - sage: P = InteractiveLPProblem(A, b, c, variable_type=">=") + sage: P = InteractiveLPProblem(A, b, c, variable_type='>=') sage: DP = P.dual() sage: DPSF = DP.standard_form() sage: DPSF.b() @@ -1791,7 +1739,7 @@ def standard_form(self, transformation=False, **kwds): sage: c = (-10, -5) sage: P = InteractiveLPProblem(A, b, c, variable_type=["<=", ""], ....: objective_constant_term=-42, - ....: problem_type="min") + ....: problem_type='min') sage: PSF, f = P.standard_form(True) sage: PSF.optimal_solution() (0, 1000, 0) @@ -1801,7 +1749,6 @@ def standard_form(self, transformation=False, **kwds): -5042 sage: P.optimal_value() -5042 - """ A, b, c, x = self.Abcx() f = identity_matrix(self.n()).columns() @@ -1864,9 +1811,7 @@ def variable_types(self): r""" Return a tuple listing the variable types of all decision variables. - OUTPUT: - - - a tuple of strings + OUTPUT: a tuple of strings EXAMPLES:: @@ -1916,17 +1861,17 @@ class InteractiveLPProblemStandardForm(InteractiveLPProblem): - ``c`` -- a vector of objective coefficients - - ``x`` -- (default: ``"x"``) a vector of decision variables or a string + - ``x`` -- (default: ``'x'``) a vector of decision variables or a string the base name giving - - ``problem_type`` -- (default: ``"max"``) a string specifying the - problem type: either ``"max"`` or ``"-max"`` + - ``problem_type`` -- (default: ``'max'``) a string specifying the + problem type: either ``'max'`` or ``'-max'`` - ``slack_variables`` -- (default: depends on :func:`style`) a vector of slack variables or a string giving the base name - ``auxiliary_variable`` -- (default: same as ``x`` parameter with adjoined - ``"0"`` if it was given as a string, otherwise ``"x0"``) the auxiliary + ``'0'`` if it was given as a string, otherwise ``'x0'``) the auxiliary name, expected to be the same as the first decision variable for auxiliary problems @@ -1934,12 +1879,12 @@ class InteractiveLPProblemStandardForm(InteractiveLPProblem): input coefficients) a field to which all input coefficients will be converted - - ``is_primal`` -- (default: ``True``) whether this problem is primal or + - ``is_primal`` -- boolean (default: ``True``); whether this problem is primal or dual: each problem is of course dual to its own dual, this flag is mostly for internal use and affects default variable names only - - ``objective_name`` -- a string or a symbolic expression for the - objective used in dictionaries, default depends on :func:`style` + - ``objective_name`` -- string or symbolic expression for the + objective used in dictionaries (default: depends on :func:`style`) - ``objective_constant_term`` -- (default: 0) a constant term of the objective @@ -1952,8 +1897,8 @@ class InteractiveLPProblemStandardForm(InteractiveLPProblem): sage: P = InteractiveLPProblemStandardForm(A, b, c) Unlike :class:`InteractiveLPProblem`, this class does not allow you to adjust types of - constraints (they are always ``"<="``) and variables (they are always - ``">="``), and the problem type may only be ``"max"`` or ``"-max"``. + constraints (they are always ``'<='``) and variables (they are always + ``'>='``), and the problem type may only be ``'max'`` or ``'-max'``. You may give custom names to slack and auxiliary variables, but in most cases defaults should work:: @@ -1963,7 +1908,7 @@ class InteractiveLPProblemStandardForm(InteractiveLPProblem): (x3, x4) """ - def __init__(self, A, b, c, x="x", problem_type="max", + def __init__(self, A, b, c, x='x', problem_type='max', slack_variables=None, auxiliary_variable=None, base_ring=None, is_primal=True, objective_name=None, objective_constant_term=0): @@ -1984,8 +1929,8 @@ def __init__(self, A, b, c, x="x", problem_type="max", super().__init__( A, b, c, x, problem_type=problem_type, - constraint_type="<=", - variable_type=">=", + constraint_type='<=', + variable_type='>=', base_ring=base_ring, is_primal=is_primal, objective_constant_term=objective_constant_term) @@ -2011,7 +1956,7 @@ def __init__(self, A, b, c, x="x", problem_type="max", names.extend(slack_variables) if names[0] == names[1]: names.pop(0) - R = PolynomialRing(self.base_ring(), names, order="neglex") + R = PolynomialRing(self.base_ring(), names, order='neglex') self._R = R x = vector(R.gens()[-n-m:-m]) x.set_immutable() @@ -2075,9 +2020,7 @@ def add_constraint(self, coefficients, constant_term, slack_variable=None): - ``slack_variable`` -- (default: depends on :func:`style`) a string giving the name of the slack variable of the new constraint - OUTPUT: - - - an :class:`LP problem in standard form ` + OUTPUT: an :class:`LP problem in standard form ` EXAMPLES:: @@ -2140,12 +2083,10 @@ def auxiliary_problem(self, objective_name=None): INPUT: - - ``objective_name`` -- a string or a symbolic expression for the - objective used in dictionaries, default depends on :func:`style` + - ``objective_name`` -- string or symbolic expression for the + objective used in dictionaries (default: depends on :func:`style`) - OUTPUT: - - - an :class:`LP problem in standard form ` + OUTPUT: an :class:`LP problem in standard form ` The auxiliary problem with the auxiliary variable `x_0` is @@ -2190,9 +2131,7 @@ def auxiliary_variable(self): Note that the auxiliary variable may or may not be among :meth:`~InteractiveLPProblem.decision_variables`. - OUTPUT: - - - a variable of the :meth:`coordinate_ring` of ``self`` + OUTPUT: a variable of the :meth:`coordinate_ring` of ``self`` EXAMPLES:: @@ -2250,9 +2189,7 @@ def dictionary(self, *x_B): - basic variables for the dictionary to be constructed - OUTPUT: - - - a :class:`dictionary ` + OUTPUT: a :class:`dictionary ` .. NOTE:: @@ -2283,9 +2220,7 @@ def feasible_dictionary(self, auxiliary_dictionary): :meth:`auxiliary_problem` of ``self`` with the optimal value `0` and a non-basic auxiliary variable - OUTPUT: - - - a feasible :class:`dictionary ` for ``self`` + OUTPUT: a feasible :class:`dictionary ` for ``self`` EXAMPLES:: @@ -2351,9 +2286,7 @@ def final_dictionary(self): See :meth:`run_simplex_method` for the description of possibilities. - OUTPUT: - - - a :class:`dictionary ` + OUTPUT: a :class:`dictionary ` EXAMPLES:: @@ -2387,9 +2320,7 @@ def final_revised_dictionary(self): See :meth:`run_revised_simplex_method` for the description of possibilities. - OUTPUT: - - - a :class:`revised dictionary ` + OUTPUT: a :class:`revised dictionary ` EXAMPLES:: @@ -2423,9 +2354,7 @@ def initial_dictionary(self): of the :meth:`~InteractiveLPProblem.decision_variables`, i.e. it has slack variables as basic ones. - OUTPUT: - - - a :class:`dictionary ` + OUTPUT: a :class:`dictionary ` EXAMPLES:: @@ -2452,9 +2381,7 @@ def inject_variables(self, scope=None, verbose=True): - ``verbose`` -- if ``True`` (default), names of injected variables will be printed - OUTPUT: - - - none + OUTPUT: none EXAMPLES:: @@ -2478,9 +2405,7 @@ def objective_name(self): r""" Return the objective name used in dictionaries for this problem. - OUTPUT: - - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -2497,7 +2422,7 @@ def objective_name(self): zeta sage: sage.numerical.interactive_simplex_method.style("UAlberta") 'UAlberta' - sage: P = InteractiveLPProblemStandardForm(A, b, c, objective_name="custom") + sage: P = InteractiveLPProblemStandardForm(A, b, c, objective_name='custom') sage: P.objective_name() custom """ @@ -2513,9 +2438,7 @@ def revised_dictionary(self, *x_B): :meth:`slack_variables` will be used, perhaps with the :meth:`auxiliary_variable` to give a feasible dictionary - OUTPUT: - - - a :class:`revised dictionary ` + OUTPUT: a :class:`revised dictionary ` EXAMPLES:: @@ -2568,7 +2491,7 @@ def run_revised_simplex_method(self): one of the following: - an optimal dictionary with the :meth:`auxiliary_variable` among - :meth:`~LPRevisedDictionary.basic_variables` and a non-zero + :meth:`~LPRevisedDictionary.basic_variables` and a nonzero optimal value indicating that ``self`` is infeasible; @@ -2632,7 +2555,7 @@ def run_simplex_method(self): of the following: - an optimal dictionary for the :meth:`auxiliary_problem` with a - non-zero optimal value indicating that ``self`` is infeasible; + nonzero optimal value indicating that ``self`` is infeasible; - a non-optimal dictionary for ``self`` that has marked entering variable for which there is no choice of the leaving variable, @@ -2704,9 +2627,7 @@ def slack_variables(self): If you want to give custom names to slack variables, you have to do so during construction of the problem. - OUTPUT: - - - a tuple + OUTPUT: a tuple EXAMPLES:: @@ -2752,9 +2673,7 @@ def _html_(self): r""" Return an HTML representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string TESTS:: @@ -2778,12 +2697,10 @@ def _preupdate_output(self, direction): INPUT: - - ``direction`` -- a string specifying the type of the simplex method + - ``direction`` -- string specifying the type of the simplex method used, either "primal" or "dual" - OUTPUT: - - - :class:`~sage.misc.html.HtmlFragment`. + OUTPUT: :class:`~sage.misc.html.HtmlFragment` TESTS:: @@ -2812,9 +2729,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string TESTS:: @@ -2838,18 +2753,16 @@ def add_row(self, nonbasic_coefficients, constant, basic_variable=None): INPUT: - - ``nonbasic_coefficients`` -- a list of the coefficients for the + - ``nonbasic_coefficients`` -- list of the coefficients for the new row (with which nonbasic variables are subtracted in the relation for the new basic variable) - - ``constant`` -- the constant term for the new row + - ``constant`` -- the constant term for the new row - ``basic_variable`` -- (default: depends on :func:`style`) a string giving the name of the basic variable of the new row - OUTPUT: - - - a new dictionary of the same class + OUTPUT: a new dictionary of the same class EXAMPLES:: @@ -2867,9 +2780,7 @@ def base_ring(self): r""" Return the base ring of ``self``, i.e. the ring of coefficients. - OUTPUT: - - - a ring + OUTPUT: a ring EXAMPLES:: @@ -2891,9 +2802,7 @@ def basic_variables(self): r""" Return the basic variables of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -2919,12 +2828,10 @@ def basic_solution(self, include_slack_variables=False): INPUT: - - ``include_slack_variables`` -- (default: ``False``) if ``True``, + - ``include_slack_variables`` -- boolean (default: ``False``); if ``True``, values of slack variables will be appended at the end - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -2961,9 +2868,7 @@ def column_coefficients(self, v): - ``v`` -- a nonbasic variable of ``self``, can be given as a string, an actual variable, or an integer interpreted as the index of a variable - OUTPUT: - - - a vector of coefficients of a nonbasic variable + OUTPUT: a vector of coefficients of a nonbasic variable EXAMPLES:: @@ -2981,9 +2886,7 @@ def constant_terms(self): r""" Return the constant terms of relations of ``self``. - OUTPUT: - - - a vector. + OUTPUT: a vector EXAMPLES:: @@ -3113,9 +3016,7 @@ def entering(self): r""" Return the currently chosen entering variable. - OUTPUT: - - - a variable if the entering one was chosen, otherwise ``None`` + OUTPUT: a variable if the entering one was chosen, otherwise ``None`` EXAMPLES:: @@ -3136,9 +3037,7 @@ def entering_coefficients(self): r""" Return coefficients of the entering variable. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -3163,7 +3062,7 @@ def is_dual_feasible(self): OUTPUT: - ``True`` if all :meth:`~LPDictionary.objective_coefficients` are - non-positive, ``False`` otherwise + nonpositive, ``False`` otherwise EXAMPLES:: @@ -3187,7 +3086,7 @@ def is_feasible(self): OUTPUT: - ``True`` if all :meth:`~LPDictionary.constant_terms` are - non-negative, ``False`` otherwise + nonnegative, ``False`` otherwise EXAMPLES:: @@ -3211,8 +3110,8 @@ def is_optimal(self): OUTPUT: - ``True`` if ``self`` :meth:`is_feasible` and :meth:`is_dual_feasible` - (i.e. all :meth:`~LPDictionary.constant_terms` are non-negative and - all :meth:`~LPDictionary.objective_coefficients` are non-positive), + (i.e. all :meth:`~LPDictionary.constant_terms` are nonnegative and + all :meth:`~LPDictionary.objective_coefficients` are nonpositive), ``False`` otherwise. EXAMPLES:: @@ -3283,9 +3182,7 @@ def leaving(self): r""" Return the currently chosen leaving variable. - OUTPUT: - - - a variable if the leaving one was chosen, otherwise ``None`` + OUTPUT: a variable if the leaving one was chosen, otherwise ``None`` EXAMPLES:: @@ -3306,9 +3203,7 @@ def leaving_coefficients(self): r""" Return coefficients of the leaving variable. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -3338,9 +3233,7 @@ def nonbasic_variables(self): r""" Return non-basic variables of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -3358,9 +3251,7 @@ def objective_coefficients(self): r""" Return coefficients of the objective of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -3378,9 +3269,7 @@ def objective_name(self): r""" Return the objective name of ``self``. - OUTPUT: - - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -3399,9 +3288,7 @@ def objective_value(self): Return the value of the objective at the :meth:`~LPAbstractDictionary.basic_solution` of ``self``. - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: @@ -3615,9 +3502,7 @@ def row_coefficients(self, v): - ``v`` -- a basic variable of ``self``, can be given as a string, an actual variable, or an integer interpreted as the index of a variable - OUTPUT: - - - a vector of coefficients of a basic variable + OUTPUT: a vector of coefficients of a basic variable EXAMPLES:: @@ -3845,15 +3730,13 @@ class LPDictionary(LPAbstractDictionary): - ``objective_value`` -- current value of the objective `z^*` - - ``basic_variables`` -- a list of basic variables `x_B` + - ``basic_variables`` -- list of basic variables `x_B` - - ``nonbasic_variables`` -- a list of non-basic variables `x_N` + - ``nonbasic_variables`` -- list of non-basic variables `x_N` - ``objective_name`` -- a "name" for the objective `z` - OUTPUT: - - - a :class:`dictionary for an LP problem ` + OUTPUT: a :class:`dictionary for an LP problem ` .. NOTE:: @@ -3878,7 +3761,7 @@ class LPDictionary(LPAbstractDictionary): sage: A = matrix(QQ, ([1, 1], [3, 1])) sage: b = vector(QQ, (1000, 1500)) sage: c = vector(QQ, (10, 5)) - sage: R = PolynomialRing(QQ, "x1, x2, x3, x4", order="neglex") + sage: R = PolynomialRing(QQ, "x1, x2, x3, x4", order='neglex') sage: from sage.numerical.interactive_simplex_method \ ....: import LPDictionary sage: D2 = LPDictionary(A, b, c, 0, R.gens()[2:], R.gens()[:2], "z") @@ -3897,7 +3780,7 @@ def __init__(self, A, b, c, objective_value, sage: A = matrix(QQ, ([1, 1], [3, 1])) sage: b = vector(QQ, (1000, 1500)) sage: c = vector(QQ, (10, 5)) - sage: R = PolynomialRing(QQ, "x1, x2, x3, x4", order="neglex") + sage: R = PolynomialRing(QQ, "x1, x2, x3, x4", order='neglex') sage: from sage.numerical.interactive_simplex_method \ ....: import LPDictionary sage: D = LPDictionary(A, b, c, 0, R.gens()[2:], R.gens()[:2], "z") @@ -3956,9 +3839,7 @@ def random_element(m, n, bound=5, special_probability=0.2): - ``special_probability`` -- (default: 0.2) probability of constructing a potentially infeasible or potentially optimal dictionary - OUTPUT: - - - an :class:`LP problem dictionary ` + OUTPUT: an :class:`LP problem dictionary ` EXAMPLES:: @@ -3976,7 +3857,7 @@ def random_element(m, n, bound=5, special_probability=0.2): c = random_vector(ZZ, n, x=-bound, y=bound).change_ring(QQ) else: # Make dual feasible dictionary c = random_vector(ZZ, n, x=-bound, y=0).change_ring(QQ) - x_N = list(PolynomialRing(QQ, "x", m + n + 1, order="neglex").gens()) + x_N = list(PolynomialRing(QQ, "x", m + n + 1, order='neglex').gens()) x_N.pop(0) x_B = [x_N.pop(randint(0, n + m - i - 1)) for i in range(m)] return LPDictionary(A, b, c, randint(-bound, bound), x_B, x_N, "z") @@ -4005,7 +3886,7 @@ def __eq__(self, other): sage: A = matrix(QQ, ([1, 1], [3, 1])) sage: b = vector(QQ, (1000, 1500)) sage: c = vector(QQ, (10, 5)) - sage: R = PolynomialRing(QQ, "x1, x2, x3, x4", order="neglex") + sage: R = PolynomialRing(QQ, "x1, x2, x3, x4", order='neglex') sage: from sage.numerical.interactive_simplex_method \ ....: import LPDictionary sage: D2 = LPDictionary(A, b, c, 0, R.gens()[2:], R.gens()[:2], "z") @@ -4023,9 +3904,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string TESTS:: @@ -4099,18 +3978,16 @@ def add_row(self, nonbasic_coefficients, constant, basic_variable=None): INPUT: - - ``nonbasic_coefficients`` -- a list of the coefficients for the + - ``nonbasic_coefficients`` -- list of the coefficients for the new row (with which nonbasic variables are subtracted in the relation for the new basic variable) - - ``constant`` -- the constant term for the new row + - ``constant`` -- the constant term for the new row - ``basic_variable`` -- (default: depends on :func:`style`) a string giving the name of the basic variable of the new row - OUTPUT: - - - a :class:`dictionary ` + OUTPUT: a :class:`dictionary ` EXAMPLES:: @@ -4145,7 +4022,7 @@ def add_row(self, nonbasic_coefficients, constant, basic_variable=None): basic_variable = str(basic_variable) R = PolynomialRing( - BR, list(B.base_ring().variable_names()) + [basic_variable], order="neglex") + BR, list(B.base_ring().variable_names()) + [basic_variable], order='neglex') B = list(B) + [basic_variable] B = map(R, B) N = map(R, N) @@ -4155,9 +4032,7 @@ def basic_variables(self): r""" Return the basic variables of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -4180,9 +4055,7 @@ def column_coefficients(self, v): - ``v`` -- a nonbasic variable of ``self``, can be given as a string, an actual variable, or an integer interpreted as the index of a variable - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -4205,9 +4078,7 @@ def constant_terms(self): r""" Return the constant terms of relations of ``self``. - OUTPUT: - - - a vector. + OUTPUT: a vector EXAMPLES:: @@ -4225,9 +4096,7 @@ def nonbasic_variables(self): r""" Return non-basic variables of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -4245,9 +4114,7 @@ def objective_coefficients(self): r""" Return coefficients of the objective of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -4265,9 +4132,7 @@ def objective_name(self): r""" Return the objective name of ``self``. - OUTPUT: - - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -4286,9 +4151,7 @@ def objective_value(self): Return the value of the objective at the :meth:`~LPAbstractDictionary.basic_solution` of ``self``. - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: @@ -4314,9 +4177,7 @@ def row_coefficients(self, v): - ``v`` -- a basic variable of ``self``, can be given as a string, an actual variable, or an integer interpreted as the index of a variable - OUTPUT: - - - a vector of coefficients of a basic variable + OUTPUT: a vector of coefficients of a basic variable EXAMPLES:: @@ -4413,11 +4274,9 @@ class LPRevisedDictionary(LPAbstractDictionary): - ``problem`` -- an :class:`LP problem in standard form ` - - ``basic_variables`` -- a list of basic variables or their indices + - ``basic_variables`` -- list of basic variables or their indices - OUTPUT: - - - a :class:`revised dictionary for an LP problem ` + OUTPUT: a :class:`revised dictionary for an LP problem ` A revised dictionary encodes the same relations as a :class:`regular dictionary `, but stores only what is @@ -4585,9 +4444,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - a string + OUTPUT: string TESTS:: @@ -4712,12 +4569,10 @@ def _preupdate_output(self, direction): INPUT: - - ``direction`` -- a string specifying the type of the simplex method + - ``direction`` -- string specifying the type of the simplex method used, either "primal" or "dual" - OUTPUT: - - - :class:`~sage.misc.html.HtmlFragment`. + OUTPUT: :class:`~sage.misc.html.HtmlFragment` TESTS:: @@ -4758,9 +4613,7 @@ def A(self, v): - ``v`` -- a variable, its name, or its index - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -4794,9 +4647,7 @@ def A_N(self): Return the `A_N` matrix, constraint coefficients of non-basic variables. - OUTPUT: - - - a matrix + OUTPUT: a matrix EXAMPLES:: @@ -4817,9 +4668,7 @@ def B(self): Return the `B` matrix, i.e. constraint coefficients of basic variables. - OUTPUT: - - - a matrix + OUTPUT: a matrix EXAMPLES:: @@ -4842,9 +4691,7 @@ def B_inverse(self): This inverse matrix is stored and computed during dictionary update in a more efficient way than generic inversion. - OUTPUT: - - - a matrix + OUTPUT: a matrix EXAMPLES:: @@ -4867,9 +4714,7 @@ def E(self): r""" Return the eta matrix between ``self`` and the next dictionary. - OUTPUT: - - - a matrix + OUTPUT: a matrix If `B_{\mathrm{old}}` is the current matrix `B` and `B_{\mathrm{new}}` is the `B` matrix of the next dictionary (after the update step), then @@ -4907,9 +4752,7 @@ def E_inverse(self): This inverse matrix is computed in a more efficient way than generic inversion. - OUTPUT: - - - a matrix + OUTPUT: a matrix EXAMPLES:: @@ -4946,18 +4789,16 @@ def add_row(self, nonbasic_coefficients, constant, basic_variable=None): INPUT: - - ``nonbasic_coefficients`` -- a list of the coefficients for the + - ``nonbasic_coefficients`` -- list of the coefficients for the new row (with which nonbasic variables are subtracted in the relation for the new basic variable) - - ``constant`` -- the constant term for the new row + - ``constant`` -- the constant term for the new row - ``basic_variable`` -- (default: depends on :func:`style`) a string giving the name of the basic variable of the new row - OUTPUT: - - - a :class:`revised dictionary ` + OUTPUT: a :class:`revised dictionary ` EXAMPLES:: @@ -5035,9 +4876,7 @@ def basic_indices(self): indices of variables which are parts of their names. (They will for the default indexed names.) - OUTPUT: - - - a list. + OUTPUT: list EXAMPLES:: @@ -5056,9 +4895,7 @@ def basic_variables(self): r""" Return the basic variables of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -5076,9 +4913,7 @@ def c_B(self): r""" Return the `c_B` vector, objective coefficients of basic variables. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -5106,9 +4941,7 @@ def c_N(self): r""" Return the `c_N` vector, objective coefficients of non-basic variables. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -5139,9 +4972,7 @@ def column_coefficients(self, v): - ``v`` -- a nonbasic variable of ``self``, can be given as a string, an actual variable, or an integer interpreted as the index of a variable - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -5163,9 +4994,7 @@ def constant_terms(self): r""" Return constant terms in the relations of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -5183,9 +5012,7 @@ def dictionary(self): r""" Return a regular LP dictionary matching ``self``. - OUTPUT: - - - an :class:`LP dictionary ` + OUTPUT: an :class:`LP dictionary ` EXAMPLES:: @@ -5221,9 +5048,7 @@ def nonbasic_indices(self): of variables which are parts of their names. (They will for the default indexed names.) - OUTPUT: - - - a list + OUTPUT: list EXAMPLES:: @@ -5242,9 +5067,7 @@ def nonbasic_variables(self): r""" Return non-basic variables of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: @@ -5263,9 +5086,7 @@ def objective_coefficients(self): r""" Return coefficients of the objective of ``self``. - OUTPUT: - - - a vector + OUTPUT: a vector These are coefficients of non-basic variables when basic variables are eliminated. @@ -5286,9 +5107,7 @@ def objective_name(self): r""" Return the objective name of ``self``. - OUTPUT: - - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -5306,9 +5125,7 @@ def objective_value(self): r""" Return the value of the objective at the basic solution of ``self``. - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: @@ -5327,9 +5144,7 @@ def problem(self): r""" Return the original problem. - OUTPUT: - - - an :class:`LP problem in standard form ` + OUTPUT: an :class:`LP problem in standard form ` EXAMPLES:: @@ -5355,9 +5170,7 @@ def row_coefficients(self, v): - ``v`` -- a basic variable of ``self``, can be given as a string, an actual variable, or an integer interpreted as the index of a variable - OUTPUT: - - - a vector of coefficients of a basic variable + OUTPUT: a vector of coefficients of a basic variable EXAMPLES:: @@ -5419,9 +5232,7 @@ def y(self): Return the `y` vector, the product of :meth:`c_B` and :meth:`B_inverse`. - OUTPUT: - - - a vector + OUTPUT: a vector EXAMPLES:: diff --git a/src/sage/numerical/knapsack.py b/src/sage/numerical/knapsack.py index 3f80f517998..9f9d06fcd3b 100644 --- a/src/sage/numerical/knapsack.py +++ b/src/sage/numerical/knapsack.py @@ -103,7 +103,7 @@ class Superincreasing(SageObject): A class for super-increasing sequences. Let `L = (a_1, a_2, a_3, \dots, a_n)` be a non-empty sequence of - non-negative integers. Then `L` is said to be super-increasing if + nonnegative integers. Then `L` is said to be super-increasing if each `a_i` is strictly greater than the sum of all previous values. That is, for each `a_i \in L` the sequence `L` must satisfy the property @@ -120,7 +120,7 @@ class Superincreasing(SageObject): INPUT: - - ``seq`` -- (default: ``None``) a non-empty sequence. + - ``seq`` -- (default: ``None``) a non-empty sequence EXAMPLES:: @@ -148,8 +148,7 @@ def __init__(self, seq=None): INPUT: - - ``seq`` -- (default: ``None``) a non-empty sequence. - + - ``seq`` -- (default: ``None``) a non-empty sequence EXAMPLES:: @@ -204,7 +203,6 @@ def __repr__(self): Return a string representation of this super-increasing sequence object. - EXAMPLES:: sage: from sage.numerical.knapsack import Superincreasing @@ -231,15 +229,13 @@ def largest_less_than(self, N): INPUT: - - ``N`` -- integer; the target value to search for. - + - ``N`` -- integer; the target value to search for OUTPUT: The largest integer in ``self`` that is less than or equal to ``N``. If no solution exists, then return ``None``. - EXAMPLES: When a solution is found, return it:: @@ -339,7 +335,7 @@ def is_superincreasing(self, seq=None): super-increasing. Let `L = (a_1, a_2, a_3, \dots, a_n)` be a non-empty sequence of - non-negative integers. Then `L` is said to be super-increasing if + nonnegative integers. Then `L` is said to be super-increasing if each `a_i` is strictly greater than the sum of all previous values. That is, for each `a_i \in L` the sequence `L` must satisfy the property @@ -352,12 +348,10 @@ def is_superincreasing(self, seq=None): If `L` has exactly one element, then it is also defined to be a super-increasing sequence. - INPUT: - ``seq`` -- (default: ``None``) a sequence to test - OUTPUT: - If ``seq`` is ``None``, then test ``self`` to determine whether or @@ -368,7 +362,6 @@ def is_superincreasing(self, seq=None): or not it is super-increasing. Return ``True`` if ``seq`` is super-increasing; ``False`` otherwise. - EXAMPLES: By definition, an empty sequence is not super-increasing:: @@ -414,12 +407,12 @@ def is_superincreasing(self, seq=None): sage: Superincreasing(L).is_superincreasing() Traceback (most recent call last): ... - TypeError: Element e (= 1.00000000000000) of seq must be a non-negative integer. + TypeError: Element e (= 1.00000000000000) of seq must be a nonnegative integer. sage: L = [1, 2.1, pi, 21, 69, 189, 376, 919] sage: Superincreasing(L).is_superincreasing() Traceback (most recent call last): ... - TypeError: Element e (= 2.10000000000000) of seq must be a non-negative integer. + TypeError: Element e (= 2.10000000000000) of seq must be a nonnegative integer. """ # argument seq is None, so test self for super-increasing if seq is None: @@ -448,15 +441,15 @@ def is_superincreasing(self, seq=None): return False # so now seq is known to represent a non-empty sequence if (not isinstance(seq[0], Integer)) and (not isinstance(seq[0], int)): - raise TypeError("Element e (= %s) of seq must be a non-negative integer." % seq[0]) + raise TypeError("Element e (= %s) of seq must be a nonnegative integer." % seq[0]) if seq[0] < 0: - raise TypeError("Element e (= %s) of seq must be a non-negative integer." % seq[0]) + raise TypeError("Element e (= %s) of seq must be a nonnegative integer." % seq[0]) cumSum = seq[0] # the cumulative sum of the sequence seq for e in seq[1:]: if (not isinstance(e, Integer)) and (not isinstance(e, int)): - raise TypeError("Element e (= %s) of seq must be a non-negative integer." % e) + raise TypeError("Element e (= %s) of seq must be a nonnegative integer." % e) if e < 0: - raise TypeError("Element e (= %s) of seq must be a non-negative integer." % e) + raise TypeError("Element e (= %s) of seq must be a nonnegative integer." % e) if e <= cumSum: return False cumSum += e @@ -467,7 +460,7 @@ def subset_sum(self, N): Solving the subset sum problem for a super-increasing sequence. Let `S = (s_1, s_2, s_3, \dots, s_n)` be a non-empty sequence of - non-negative integers, and let `N \in \ZZ` be non-negative. The + nonnegative integers, and let `N \in \ZZ` be nonnegative. The subset sum problem asks for a subset `A \subseteq S` all of whose elements sum to `N`. This method specializes the subset sum problem to the case of super-increasing sequences. If a solution exists, then @@ -480,11 +473,9 @@ def subset_sum(self, N): problem for an arbitrary sequence is known to be computationally hard. - INPUT: - - ``N`` -- a non-negative integer. - + - ``N`` -- nonnegative integer OUTPUT: @@ -492,12 +483,10 @@ def subset_sum(self, N): subset is also a super-increasing sequence. If no such subset exists, then return the empty list. - - ALGORITHMS: + ALGORITHM: The algorithm used is adapted from page 355 of [HPS2008]_. - EXAMPLES: Solving the subset sum problem for a super-increasing sequence @@ -511,35 +500,35 @@ def subset_sum(self, N): TESTS: - The target ``N`` must be a non-negative integer:: + The target ``N`` must be a nonnegative integer:: sage: from sage.numerical.knapsack import Superincreasing sage: L = [0, 1, 2, 4] sage: Superincreasing(L).subset_sum(-6) Traceback (most recent call last): ... - TypeError: N (= -6) must be a non-negative integer. + TypeError: N (= -6) must be a nonnegative integer. sage: Superincreasing(L).subset_sum(-6.2) Traceback (most recent call last): ... - TypeError: N (= -6.20000000000000) must be a non-negative integer. + TypeError: N (= -6.20000000000000) must be a nonnegative integer. - The sequence that ``self`` represents must only contain non-negative + The sequence that ``self`` represents must only contain nonnegative integers:: sage: L = [-10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1] sage: Superincreasing(L).subset_sum(1) Traceback (most recent call last): ... - TypeError: Element e (= -10) of seq must be a non-negative integer. + TypeError: Element e (= -10) of seq must be a nonnegative integer. """ # input error handling if not self.is_superincreasing(): raise TypeError("self is not super-increasing. Only super-increasing sequences are currently supported.") if (not isinstance(N, Integer)) and (not isinstance(N, int)): - raise TypeError("N (= %s) must be a non-negative integer." % N) + raise TypeError("N (= %s) must be a nonnegative integer." % N) if N < 0: - raise TypeError("N (= %s) must be a non-negative integer." % N) + raise TypeError("N (= %s) must be a nonnegative integer." % N) # solve subset sum problem for super-increasing sequence candidates = [] @@ -559,7 +548,7 @@ def subset_sum(self, N): def knapsack(seq, binary=True, max=1, value_only=False, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Solves the knapsack problem + Solve the knapsack problem. For more information on the knapsack problem, see the documentation of the :mod:`knapsack module ` or the @@ -567,7 +556,7 @@ def knapsack(seq, binary=True, max=1, value_only=False, solver=None, verbose=0, INPUT: - - ``seq`` -- Two different possible types: + - ``seq`` -- two different possible types: - A sequence of tuples ``(weight, value, something1, something2, ...)``. Note that only the first two coordinates (``weight`` and @@ -577,17 +566,17 @@ def knapsack(seq, binary=True, max=1, value_only=False, solver=None, verbose=0, - A sequence of reals (a value of 1 is assumed). - - ``binary`` -- When set to ``True``, an item can be taken 0 or 1 time. + - ``binary`` -- when set to ``True``, an item can be taken 0 or 1 time When set to ``False``, an item can be taken any amount of times (while staying integer and positive). - - ``max`` -- Maximum admissible weight. + - ``max`` -- maximum admissible weight - - ``value_only`` -- When set to ``True``, only the maximum useful value is + - ``value_only`` -- when set to ``True``, only the maximum useful value is returned. When set to ``False``, both the maximum useful value and an assignment are returned. - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -595,11 +584,11 @@ def knapsack(seq, binary=True, max=1, value_only=False, solver=None, verbose=0, of the class :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``). Sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` OUTPUT: diff --git a/src/sage/numerical/linear_functions.pyx b/src/sage/numerical/linear_functions.pyx index d1a038fd54b..3b0061960e1 100644 --- a/src/sage/numerical/linear_functions.pyx +++ b/src/sage/numerical/linear_functions.pyx @@ -116,15 +116,13 @@ from sage.misc.cachefunc import cached_function cpdef is_LinearFunction(x): """ - Test whether ``x`` is a linear function + Test whether ``x`` is a linear function. INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -149,15 +147,13 @@ cpdef is_LinearFunction(x): def is_LinearConstraint(x): """ - Test whether ``x`` is a linear constraint + Test whether ``x`` is a linear constraint. INPUT: - - ``x`` -- anything. - - OUTPUT: + - ``x`` -- anything - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -197,12 +193,10 @@ def LinearFunctionsParent(base_ring): INPUT: - - ``base_ring`` -- a ring. The coefficient ring for the linear - functions. + - ``base_ring`` -- a ring; the coefficient ring for the linear + functions - OUTPUT: - - The parent of the linear functions over ``base_ring``. + OUTPUT: the parent of the linear functions over ``base_ring`` EXAMPLES:: @@ -223,13 +217,11 @@ def LinearConstraintsParent(linear_functions_parent): INPUT: - - ``linear_functions_parent`` -- a - :class:`LinearFunctionsParent_class`. The type of linear - functions that the constraints are made out of. - - OUTPUT: + - ``linear_functions_parent`` -- a + :class:`LinearFunctionsParent_class`; the type of linear + functions that the constraints are made out of - The parent of the linear constraints with the given linear functions. + OUTPUT: the parent of the linear constraints with the given linear functions EXAMPLES:: @@ -539,9 +531,7 @@ cdef class LinearFunctionsParent_class(Parent): You should use :func:`LinearFunctionsParent` to construct instances of this class. - INPUT/OUTPUT: - - See :func:`LinearFunctionsParent` + INPUT/OUTPUT: see :func:`LinearFunctionsParent` EXAMPLES:: @@ -551,7 +541,7 @@ cdef class LinearFunctionsParent_class(Parent): """ def __cinit__(self): """ - Cython initializer + Cython initializer. TESTS:: @@ -566,7 +556,7 @@ cdef class LinearFunctionsParent_class(Parent): def __init__(self, base_ring): """ - The Python constructor + The Python constructor. TESTS:: @@ -583,8 +573,8 @@ cdef class LinearFunctionsParent_class(Parent): INPUT: - - ``symbol`` -- string, default: ``'*'``. The multiplication - symbol to be used. + - ``symbol`` -- string (default: ``'*'``); the multiplication + symbol to be used EXAMPLES:: @@ -609,9 +599,7 @@ cdef class LinearFunctionsParent_class(Parent): """ Return the multiplication symbol. - OUTPUT: - - String. By default, this is ``'*'``. + OUTPUT: string. By default, this is ``'*'`` EXAMPLES:: @@ -628,7 +616,7 @@ cdef class LinearFunctionsParent_class(Parent): INPUT: - ``free_module`` -- vector space or matrix space over the - same base ring. + same base ring OUTPUT: @@ -655,11 +643,9 @@ cdef class LinearFunctionsParent_class(Parent): INPUT: - - ``i`` -- non-negative integer. + - ``i`` -- nonnegative integer - OUTPUT: - - The linear function `x_i`. + OUTPUT: the linear function `x_i` EXAMPLES:: @@ -671,7 +657,7 @@ cdef class LinearFunctionsParent_class(Parent): def _repr_(self): """ - Return as string representation + Return as string representation. EXAMPLES:: @@ -716,11 +702,9 @@ cdef class LinearFunctionsParent_class(Parent): INPUT: - - ``R`` -- a ring. - - OUTPUT: + - ``R`` -- a ring - Boolean. Whether there is a coercion map. + OUTPUT: boolean; whether there is a coercion map EXAMPLES:: @@ -738,11 +722,9 @@ cdef class LinearFunctionsParent_class(Parent): def _an_element_(self): """ - Returns an element + Return an element. - OUTPUT: - - A linear function. + OUTPUT: a linear function EXAMPLES:: @@ -869,8 +851,8 @@ cdef class LinearFunction(LinearFunctionOrConstraint): INPUT: - - ``x`` -- a linear variable or an integer. If an integer `i` - is passed, then `x_i` is used as linear variable. + - ``x`` -- a linear variable or an integer; if an integer `i` + is passed, then `x_i` is used as linear variable OUTPUT: @@ -924,7 +906,7 @@ cdef class LinearFunction(LinearFunctionOrConstraint): cpdef _add_(self, b): r""" - Defining the + operator + Defining the ``+`` operator. EXAMPLES:: @@ -974,7 +956,7 @@ cdef class LinearFunction(LinearFunctionOrConstraint): cpdef _lmul_(self, Element b): r""" - Multiplication by scalars + Multiplication by scalars. EXAMPLES:: @@ -1045,11 +1027,11 @@ cdef class LinearFunction(LinearFunctionOrConstraint): def _coeff_formatter(self, coeff, constant_term=False): """ - Pretty-print multiplicative coefficient ``x`` + Pretty-print multiplicative coefficient ``x``. OUTPUT: - String, including a trailing space if the coefficient is not + string, including a trailing space if the coefficient is not one. Empty string otherwise. EXAMPLES:: @@ -1104,7 +1086,7 @@ cdef class LinearFunction(LinearFunctionOrConstraint): def _repr_(self): r""" - Returns a string version of the linear function. + Return a string version of the linear function. EXAMPLES:: @@ -1151,9 +1133,7 @@ cdef class LinearFunction(LinearFunctionOrConstraint): """ Test whether ``self`` is zero. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1171,9 +1151,7 @@ cdef class LinearFunction(LinearFunctionOrConstraint): """ Logically compare ``left`` and ``right``. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1193,7 +1171,7 @@ cdef class LinearFunction(LinearFunctionOrConstraint): cdef class LinearConstraintsParent_class(Parent): """ - Parent for :class:`LinearConstraint` + Parent for :class:`LinearConstraint`. .. warning:: @@ -1202,9 +1180,7 @@ cdef class LinearConstraintsParent_class(Parent): :class:`MixedIntegerLinearProgram`. Also, use the :func:`LinearConstraintsParent` factory function. - INPUT/OUTPUT: - - See :func:`LinearFunctionsParent` + INPUT/OUTPUT: see :func:`LinearFunctionsParent` EXAMPLES:: @@ -1217,7 +1193,7 @@ cdef class LinearConstraintsParent_class(Parent): """ def __cinit__(self, linear_functions_parent): """ - Cython initializer + Cython initializer. TESTS:: @@ -1237,11 +1213,9 @@ cdef class LinearConstraintsParent_class(Parent): def __init__(self, linear_functions_parent): """ - The Python constructor - - INPUT/OUTPUT: + The Python constructor. - See :func:`LinearFunctionsParent` + INPUT/OUTPUT: see :func:`LinearFunctionsParent` TESTS:: @@ -1259,7 +1233,7 @@ cdef class LinearConstraintsParent_class(Parent): def linear_functions_parent(self): """ - Return the parent for the linear functions + Return the parent for the linear functions. EXAMPLES:: @@ -1271,11 +1245,9 @@ cdef class LinearConstraintsParent_class(Parent): def _repr_(self): """ - Return a string representation + Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1296,14 +1268,12 @@ cdef class LinearConstraintsParent_class(Parent): :class:`LinearConstraint`. - ``right`` -- a :class:`LinearFunction` or ``None`` - (default). - - - ``equality`` -- boolean (default: ``True``). Whether to - construct an equation or an inequality. + (default) - OUTPUT: + - ``equality`` -- boolean (default: ``True``); whether to + construct an equation or an inequality - The :class:`LinearConstraint` constructed from the input data. + OUTPUT: the :class:`LinearConstraint` constructed from the input data EXAMPLES:: @@ -1366,7 +1336,7 @@ cdef class LinearConstraintsParent_class(Parent): def _an_element_(self): """ - Returns an element + Return an element. EXAMPLES:: @@ -1410,15 +1380,15 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): INPUT: - - ``parent`` -- the parent, a :class:`LinearConstraintsParent_class` + - ``parent`` -- the parent; a :class:`LinearConstraintsParent_class` - - ``terms`` -- a list/tuple/iterable of two or more linear + - ``terms`` -- list/tuple/iterable of two or more linear functions (or things that can be converted into linear - functions). + functions) - - ``equality`` -- boolean (default: ``False``). Whether the terms + - ``equality`` -- boolean (default: ``False``); whether the terms are the entries of a chained less-or-equal (``<=``) inequality - or a chained equality. + or a chained equality EXAMPLES:: @@ -1430,7 +1400,7 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def __init__(self, parent, terms, equality=False): r""" - Constructor for ``LinearConstraint`` + Constructor for ``LinearConstraint``. INPUT: @@ -1455,7 +1425,7 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): OUTPUT: - Boolean. Whether all terms of ``left`` and ``right`` are + boolean; whether all terms of ``left`` and ``right`` are equal. Note that this is stronger than mathematical equivalence of the relations. @@ -1482,11 +1452,9 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def is_equation(self): """ - Whether the constraint is a chained equation - - OUTPUT: + Whether the constraint is a chained equation. - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1501,11 +1469,9 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def is_less_or_equal(self): """ - Whether the constraint is a chained less-or_equal inequality + Whether the constraint is a chained less-or_equal inequality. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1540,7 +1506,7 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def __iter__(self): """ - Iterate over the terms of the chained (in)-equality + Iterate over the terms of the chained (in)-equality. OUTPUT: @@ -1568,7 +1534,7 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def equations(self): """ - Iterate over the unchained(!) equations + Iterate over the unchained(!) equations. OUTPUT: @@ -1603,7 +1569,7 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def inequalities(self): """ - Iterate over the unchained(!) inequalities + Iterate over the unchained(!) inequalities. OUTPUT: @@ -1639,11 +1605,9 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def _repr_(self): r""" - Returns a string representation of the constraint. - - OUTPUT: + Return a string representation of the constraint. - String. + OUTPUT: string EXAMPLES:: @@ -1666,7 +1630,7 @@ cdef class LinearConstraint(LinearFunctionOrConstraint): def __bool__(self): """ - Part of the hack to allow chained (in)equalities + Part of the hack to allow chained (in)equalities. EXAMPLES:: diff --git a/src/sage/numerical/linear_tensor.py b/src/sage/numerical/linear_tensor.py index c4c62066db5..e7eaedb2fe5 100644 --- a/src/sage/numerical/linear_tensor.py +++ b/src/sage/numerical/linear_tensor.py @@ -116,11 +116,9 @@ def is_LinearTensor(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -159,11 +157,10 @@ def LinearTensorParent(free_module_parent, linear_functions_parent): INPUT: - - ``free_module_parent`` -- module. A free module, like vector or - matrix space. + - ``free_module_parent`` -- a free module, like vector or matrix space - - ``linear_functions_parent`` -- linear functions. The linear - functions parent. + - ``linear_functions_parent`` -- linear functions; the linear functions + parent OUTPUT: @@ -204,9 +201,7 @@ class LinearTensorParent_class(Parent): You should use :func:`LinearTensorParent` to construct instances of this class. - INPUT/OUTPUT: - - See :func:`LinearTensorParent` + INPUT/OUTPUT: see :func:`LinearTensorParent` EXAMPLES:: @@ -218,11 +213,9 @@ class LinearTensorParent_class(Parent): def __init__(self, free_module, linear_functions): """ - The Python constructor - - INPUT/OUTPUT: + The Python constructor. - See :func:`LinearTensorParent` + INPUT/OUTPUT: see :func:`LinearTensorParent` TESTS:: @@ -263,10 +256,8 @@ def is_vector_space(self): """ Return whether the free module is a vector space. - OUTPUT: - - Boolean. Whether the :meth:`free_module` factor in the tensor - product is a vector space. + OUTPUT: boolean; whether the :meth:`free_module` factor in the tensor + product is a vector space EXAMPLES:: @@ -284,10 +275,8 @@ def is_matrix_space(self): """ Return whether the free module is a matrix space. - OUTPUT: - - Boolean. Whether the :meth:`free_module` factor in the tensor - product is a matrix space. + OUTPUT: boolean; whether the :meth:`free_module` factor in the tensor + product is a matrix space EXAMPLES:: @@ -325,11 +314,9 @@ def linear_functions(self): def _repr_(self): """ - Return a string representation + Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -342,9 +329,7 @@ def _convert_constant(self, m): """ Convert ``m`` to a constant free module element. - OUTPUT: - - A :meth:`free_module` element. + OUTPUT: a :meth:`free_module` element EXAMPLES:: @@ -441,11 +426,9 @@ def _coerce_map_from_(self, R): INPUT: - - ``R`` -- a ring. + - ``R`` -- a ring - OUTPUT: - - Boolean. Whether there is a coercion map. + OUTPUT: boolean; whether there is a coercion map EXAMPLES:: @@ -470,11 +453,9 @@ def _coerce_map_from_(self, R): def _an_element_(self): """ - Returns an element - - OUTPUT: + Return an element. - A linear function tensored with a free module. + OUTPUT: a linear function tensored with a free module EXAMPLES:: diff --git a/src/sage/numerical/linear_tensor_constraints.py b/src/sage/numerical/linear_tensor_constraints.py index 60578c2511d..68aa1178d00 100644 --- a/src/sage/numerical/linear_tensor_constraints.py +++ b/src/sage/numerical/linear_tensor_constraints.py @@ -45,11 +45,9 @@ def is_LinearTensorConstraint(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -92,9 +90,7 @@ def LinearTensorConstraintsParent(linear_functions_parent): :class:`~sage.numerical.linear_functions.LinearFunctionsParent_class`. The type of linear functions that the constraints are made out of. - OUTPUT: - - The parent of the linear constraints with the given linear functions. + OUTPUT: the parent of the linear constraints with the given linear functions EXAMPLES:: @@ -143,7 +139,7 @@ class LinearTensorConstraint(Element): :class:`sage.numerical.linear_tensor_element.LinearTensor`. The left and right hand side of the constraint (in)equality. - - ``equality`` -- boolean (default: ``False``). Whether the + - ``equality`` -- boolean (default: ``False``); whether the constraint is an equality. If ``False``, it is a ``<=`` inequality. @@ -156,7 +152,7 @@ class LinearTensorConstraint(Element): def __init__(self, parent, lhs, rhs, equality): r""" - Constructor for ``LinearTensorConstraint`` + Constructor for ``LinearTensorConstraint``. INPUT: @@ -175,11 +171,9 @@ def __init__(self, parent, lhs, rhs, equality): def is_equation(self): """ - Whether the constraint is a chained equation + Whether the constraint is a chained equation. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -193,11 +187,9 @@ def is_equation(self): def is_less_or_equal(self): """ - Whether the constraint is a chained less-or_equal inequality + Whether the constraint is a chained less-or_equal inequality. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -247,7 +239,7 @@ def rhs(self): def _ascii_art_(self): """ - Return Ascii Art + Return Ascii Art. OUTPUT: @@ -272,11 +264,9 @@ def matrix_art(m): def _repr_(self): r""" - Returns a string representation of the constraint. - - OUTPUT: + Return a string representation of the constraint. - String. + OUTPUT: string EXAMPLES:: @@ -304,7 +294,7 @@ def _repr_(self): class LinearTensorConstraintsParent_class(Parent): """ - Parent for :class:`LinearTensorConstraint` + Parent for :class:`LinearTensorConstraint`. .. warning:: @@ -313,9 +303,7 @@ class LinearTensorConstraintsParent_class(Parent): :class:`MixedIntegerLinearProgram`. Also, use the :func:`LinearTensorConstraintsParent` factory function. - INPUT/OUTPUT: - - See :func:`LinearTensorConstraintsParent` + INPUT/OUTPUT: see :func:`LinearTensorConstraintsParent` EXAMPLES:: @@ -335,12 +323,12 @@ class LinearTensorConstraintsParent_class(Parent): def __init__(self, linear_tensor_parent): """ - The Python constructor + The Python constructor. INPUT: - ``linear_tensor_parent`` -- instance of - :class:`LinearTensorParent_class`. + :class:`LinearTensorParent_class` TESTS:: @@ -360,11 +348,9 @@ def __init__(self, linear_tensor_parent): def linear_tensors(self): """ - Return the parent for the linear functions + Return the parent for the linear functions. - OUTPUT: - - Instance of :class:`sage.numerical.linear_tensor.LinearTensorParent_class`. + OUTPUT: instance of :class:`sage.numerical.linear_tensor.LinearTensorParent_class` EXAMPLES:: @@ -378,11 +364,9 @@ def linear_tensors(self): def linear_functions(self): """ - Return the parent for the linear functions - - OUTPUT: + Return the parent for the linear functions. - Instance of :class:`sage.numerical.linear_functions.LinearFunctionsParent_class`. + OUTPUT: instance of :class:`sage.numerical.linear_functions.LinearFunctionsParent_class` EXAMPLES:: @@ -395,11 +379,9 @@ def linear_functions(self): def _repr_(self): """ - Return a string representation + Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -425,14 +407,12 @@ def _element_constructor_(self, left, right, equality): :class:`LinearTensorConstraint`. - ``right`` -- a :class:`LinearTensor` or ``None`` - (default). + (default) - - ``equality`` -- boolean. Whether to - construct an equation or a less-or-equal inequality. - - OUTPUT: + - ``equality`` -- boolean; whether to + construct an equation or a less-or-equal inequality - The :class:`LinearTensorConstraint` constructed from the input data. + OUTPUT: the :class:`LinearTensorConstraint` constructed from the input data EXAMPLES:: diff --git a/src/sage/numerical/linear_tensor_element.pyx b/src/sage/numerical/linear_tensor_element.pyx index f7dd2b61deb..4c6ba3c20cc 100644 --- a/src/sage/numerical/linear_tensor_element.pyx +++ b/src/sage/numerical/linear_tensor_element.pyx @@ -34,7 +34,7 @@ from sage.numerical.linear_functions cimport LinearFunction, is_LinearFunction cdef class LinearTensor(ModuleElement): r""" - A linear function tensored with a free module + A linear function tensored with a free module. .. warning:: @@ -56,9 +56,9 @@ cdef class LinearTensor(ModuleElement): INPUT: - ``parent`` -- the parent - :class:`~sage.numerical.linear_tensor.LinearTensorParent_class`. + :class:`~sage.numerical.linear_tensor.LinearTensorParent_class` - - ``f`` -- A linear function tensored by a free module is + - ``f`` -- a linear function tensored by a free module is represented as a dictionary. The values are the coefficient (free module elements) of the variable represented by the keys. The key ``-1`` corresponds to the constant term. @@ -188,9 +188,7 @@ cdef class LinearTensor(ModuleElement): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -226,9 +224,7 @@ cdef class LinearTensor(ModuleElement): """ Return a matrix-like string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -267,11 +263,9 @@ cdef class LinearTensor(ModuleElement): INPUT: - - ``b`` -- a :class:`LinearTensor`. - - OUTPUT: + - ``b`` -- a :class:`LinearTensor` - A :class:`LinearTensor`. + OUTPUT: a :class:`LinearTensor` EXAMPLES:: @@ -289,9 +283,7 @@ cdef class LinearTensor(ModuleElement): r""" Return the negative. - OUTPUT: - - A :class:`LinearTensor`. + OUTPUT: a :class:`LinearTensor` EXAMPLES:: @@ -311,11 +303,9 @@ cdef class LinearTensor(ModuleElement): INPUT: - - ``b`` -- a :class:`LinearTensor`. - - OUTPUT: + - ``b`` -- a :class:`LinearTensor` - A :class:`LinearTensor`. + OUTPUT: a :class:`LinearTensor` EXAMPLES:: @@ -337,11 +327,9 @@ cdef class LinearTensor(ModuleElement): INPUT: - - ``b`` -- base ring element. The scalar to multiply by. - - OUTPUT: + - ``b`` -- base ring element; the scalar to multiply by - A :class:`LinearTensor`. + OUTPUT: a :class:`LinearTensor` EXAMPLES:: diff --git a/src/sage/numerical/mip.pyx b/src/sage/numerical/mip.pyx index 7af017ebd17..50d952c2ae0 100644 --- a/src/sage/numerical/mip.pyx +++ b/src/sage/numerical/mip.pyx @@ -49,7 +49,7 @@ A mixed integer linear program can give you an answer: #. You have to create an instance of :class:`MixedIntegerLinearProgram` and -- in our case -- specify that it is a minimization. - #. Create a dictionary ``w`` of non-negative integer variables ``w`` via ``w = + #. Create a dictionary ``w`` of nonnegative integer variables ``w`` via ``w = p.new_variable(integer=True, nonnegative=True)``. #. Add those three equations as equality constraints via :meth:`add_constraint `. @@ -64,7 +64,7 @@ A mixed integer linear program can give you an answer: The following example shows all these steps:: - sage: p = MixedIntegerLinearProgram(maximization=False, solver="GLPK") + sage: p = MixedIntegerLinearProgram(maximization=False, solver='GLPK') sage: w = p.new_variable(integer=True, nonnegative=True) sage: p.add_constraint(w[0] + w[1] + w[2] - 14*w[3] == 0) sage: p.add_constraint(w[1] + 2*w[2] - 8*w[3] == 0) @@ -183,37 +183,37 @@ also implements the :class:`MIPSolverException` exception, as well as the :widths: 30, 70 :delim: | - :meth:`~MixedIntegerLinearProgram.add_constraint` | Adds a constraint to the ``MixedIntegerLinearProgram`` + :meth:`~MixedIntegerLinearProgram.add_constraint` | Add a constraint to the ``MixedIntegerLinearProgram`` :meth:`~MixedIntegerLinearProgram.base_ring` | Return the base ring :meth:`~MixedIntegerLinearProgram.best_known_objective_bound`| Return the value of the currently best known bound - :meth:`~MixedIntegerLinearProgram.constraints` | Returns a list of constraints, as 3-tuples - :meth:`~MixedIntegerLinearProgram.default_variable` | Return the default ``MIPVariable`` of `self`. - :meth:`~MixedIntegerLinearProgram.get_backend` | Returns the backend instance used - :meth:`~MixedIntegerLinearProgram.get_max` | Returns the maximum value of a variable - :meth:`~MixedIntegerLinearProgram.get_min` | Returns the minimum value of a variable + :meth:`~MixedIntegerLinearProgram.constraints` | Return a list of constraints, as 3-tuples + :meth:`~MixedIntegerLinearProgram.default_variable` | Return the default ``MIPVariable`` of ``self``. + :meth:`~MixedIntegerLinearProgram.get_backend` | Return the backend instance used + :meth:`~MixedIntegerLinearProgram.get_max` | Return the maximum value of a variable + :meth:`~MixedIntegerLinearProgram.get_min` | Return the minimum value of a variable :meth:`~MixedIntegerLinearProgram.get_objective_value` | Return the value of the objective function :meth:`~MixedIntegerLinearProgram.get_relative_objective_gap`| Return the relative objective gap of the best known solution :meth:`~MixedIntegerLinearProgram.get_values` | Return values found by the previous call to ``solve()`` - :meth:`~MixedIntegerLinearProgram.is_binary` | Tests whether the variable ``e`` is binary - :meth:`~MixedIntegerLinearProgram.is_integer` | Tests whether the variable is an integer - :meth:`~MixedIntegerLinearProgram.is_real` | Tests whether the variable is real + :meth:`~MixedIntegerLinearProgram.is_binary` | Test whether the variable ``e`` is binary + :meth:`~MixedIntegerLinearProgram.is_integer` | Test whether the variable is an integer + :meth:`~MixedIntegerLinearProgram.is_real` | Test whether the variable is real :meth:`~MixedIntegerLinearProgram.linear_constraints_parent` | Return the parent for all linear constraints :meth:`~MixedIntegerLinearProgram.linear_functions_parent` | Return the parent for all linear functions - :meth:`~MixedIntegerLinearProgram.new_variable` | Returns an instance of ``MIPVariable`` associated - :meth:`~MixedIntegerLinearProgram.number_of_constraints` | Returns the number of constraints assigned so far - :meth:`~MixedIntegerLinearProgram.number_of_variables` | Returns the number of variables used so far - :meth:`~MixedIntegerLinearProgram.polyhedron` | Returns the polyhedron defined by the Linear Program - :meth:`~MixedIntegerLinearProgram.remove_constraint` | Removes a constraint from self + :meth:`~MixedIntegerLinearProgram.new_variable` | Return an instance of ``MIPVariable`` associated + :meth:`~MixedIntegerLinearProgram.number_of_constraints` | Return the number of constraints assigned so far + :meth:`~MixedIntegerLinearProgram.number_of_variables` | Return the number of variables used so far + :meth:`~MixedIntegerLinearProgram.polyhedron` | Return the polyhedron defined by the Linear Program + :meth:`~MixedIntegerLinearProgram.remove_constraint` | Remove a constraint from self :meth:`~MixedIntegerLinearProgram.remove_constraints` | Remove several constraints - :meth:`~MixedIntegerLinearProgram.set_binary` | Sets a variable or a ``MIPVariable`` as binary - :meth:`~MixedIntegerLinearProgram.set_integer` | Sets a variable or a ``MIPVariable`` as integer - :meth:`~MixedIntegerLinearProgram.set_max` | Sets the maximum value of a variable - :meth:`~MixedIntegerLinearProgram.set_min` | Sets the minimum value of a variable - :meth:`~MixedIntegerLinearProgram.set_objective` | Sets the objective of the ``MixedIntegerLinearProgram`` - :meth:`~MixedIntegerLinearProgram.set_problem_name` | Sets the name of the ``MixedIntegerLinearProgram`` - :meth:`~MixedIntegerLinearProgram.set_real` | Sets a variable or a ``MIPVariable`` as real - :meth:`~MixedIntegerLinearProgram.show` | Displays the ``MixedIntegerLinearProgram`` in a human-readable - :meth:`~MixedIntegerLinearProgram.solve` | Solves the ``MixedIntegerLinearProgram`` + :meth:`~MixedIntegerLinearProgram.set_binary` | Set a variable or a ``MIPVariable`` as binary + :meth:`~MixedIntegerLinearProgram.set_integer` | Set a variable or a ``MIPVariable`` as integer + :meth:`~MixedIntegerLinearProgram.set_max` | Set the maximum value of a variable + :meth:`~MixedIntegerLinearProgram.set_min` | Set the minimum value of a variable + :meth:`~MixedIntegerLinearProgram.set_objective` | Set the objective of the ``MixedIntegerLinearProgram`` + :meth:`~MixedIntegerLinearProgram.set_problem_name` | Set the name of the ``MixedIntegerLinearProgram`` + :meth:`~MixedIntegerLinearProgram.set_real` | Set a variable or a ``MIPVariable`` as real + :meth:`~MixedIntegerLinearProgram.show` | Display the ``MixedIntegerLinearProgram`` in a human-readable + :meth:`~MixedIntegerLinearProgram.solve` | Solve the ``MixedIntegerLinearProgram`` :meth:`~MixedIntegerLinearProgram.solver_parameter` | Return or define a solver parameter :meth:`~MixedIntegerLinearProgram.sum` | Efficiently computes the sum of a sequence of LinearFunction elements :meth:`~MixedIntegerLinearProgram.write_lp` | Write the linear program as a LP file @@ -260,26 +260,26 @@ cdef class MixedIntegerLinearProgram(SageObject): for more information and installation instructions for optional solvers. - - ``solver="GLPK"``: The `GNU Linear Programming Kit + - ``solver="GLPK"``: the `GNU Linear Programming Kit `_. - ``solver="GLPK/exact"``: GLPK's implementation of an exact rational simplex method. - - ``solver="Coin"``: The `COIN-OR CBC (COIN Branch and Cut) solver + - ``solver="Coin"``: the `COIN-OR CBC (COIN Branch and Cut) solver `_. - - ``solver="CPLEX"``, provided by the proprietary `IBM ILOG CPLEX + - ``solver="CPLEX"``: provided by the proprietary `IBM ILOG CPLEX Optimization Studio `_. - - ``solver="Gurobi"``: The proprietary `Gurobi solver `_. + - ``solver="Gurobi"``: the proprietary `Gurobi solver `_. - - ``solver="CVXOPT"``: See the `CVXOPT `_ web site. + - ``solver="CVXOPT"``: see the `CVXOPT `_ web site. - - ``solver="PPL"``: An exact rational solver (for small scale instances) + - ``solver="PPL"``: an exact rational solver (for small scale instances) provided by the `Parma Polyhedra Library (PPL) `_. - - ``solver="InteractiveLP"``: A didactical + - ``solver="InteractiveLP"``: a didactical implementation of the revised simplex method in Sage. It works over any exact ordered field, the default is ``QQ``. @@ -298,7 +298,7 @@ cdef class MixedIntegerLinearProgram(SageObject): - When set to ``False``, the ``MixedIntegerLinearProgram`` is defined as a minimization. - - ``constraint_generation`` -- Only used when ``solver=None``. + - ``constraint_generation`` -- only used when ``solver=None`` - When set to ``True``, after solving the ``MixedIntegerLinearProgram``, it is possible to add a constraint, and then solve it again. @@ -309,7 +309,7 @@ cdef class MixedIntegerLinearProgram(SageObject): .. SEEALSO:: - - :func:`default_mip_solver` -- Returns/Sets the default MIP solver. + - :func:`default_mip_solver` -- returns/sets the default MIP solver EXAMPLES: @@ -358,14 +358,14 @@ cdef class MixedIntegerLinearProgram(SageObject): - ``solver`` -- one of the following: - a string indicating one of the available solvers - (see :class:`MixedIntegerLinearProgram`); + (see :class:`MixedIntegerLinearProgram`) - - ``None`` (default), the default solver is used, see - :func:`default_mip_solver`. + - ``None`` -- (default) the default solver is used, see + :func:`default_mip_solver` - or a callable (such as a class), see :func:`sage.numerical.backends.generic_backend.get_solver` - for examples. + for examples - ``maximization`` @@ -374,7 +374,7 @@ cdef class MixedIntegerLinearProgram(SageObject): - When set to ``False``, the ``MixedIntegerLinearProgram`` is defined as a minimization. - - ``constraint_generation`` -- Only used when ``solver=None``. + - ``constraint_generation`` -- only used when ``solver=None``: - When set to ``True``, after solving the ``MixedIntegerLinearProgram``, it is possible to add a constraint, @@ -397,7 +397,7 @@ cdef class MixedIntegerLinearProgram(SageObject): .. SEEALSO:: - - :meth:`default_mip_solver` -- Returns/Sets the default MIP solver. + - :meth:`default_mip_solver` -- returns/sets the default MIP solver EXAMPLES:: @@ -452,7 +452,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def linear_functions_parent(self): """ - Return the parent for all linear functions + Return the parent for all linear functions. EXAMPLES:: @@ -468,7 +468,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def linear_constraints_parent(self): """ - Return the parent for all linear constraints + Return the parent for all linear constraints. See :mod:`~sage.numerical.linear_functions` for more details. @@ -551,7 +551,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def __copy__(self): r""" - Returns a copy of the current ``MixedIntegerLinearProgram`` instance. + Return a copy of the current ``MixedIntegerLinearProgram`` instance. EXAMPLES:: @@ -620,13 +620,12 @@ cdef class MixedIntegerLinearProgram(SageObject): False sage: dcll[0] is dcll[1] True - """ return self.__copy__() def __getitem__(self, v): r""" - Returns the symbolic variable corresponding to the key + Return the symbolic variable corresponding to the key from the default :class:`MIPVariable` instance. It returns the element asked, creating it if necessary. @@ -648,9 +647,7 @@ cdef class MixedIntegerLinearProgram(SageObject): """ Return the base ring. - OUTPUT: - - A ring. The coefficients that the chosen solver supports. + OUTPUT: a ring. The coefficients that the chosen solver supports EXAMPLES:: @@ -675,12 +672,12 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_problem_name(self,name): r""" - Sets the name of the ``MixedIntegerLinearProgram``. + Set the name of the ``MixedIntegerLinearProgram``. INPUT: - - ``name`` -- A string representing the name of the - ``MixedIntegerLinearProgram``. + - ``name`` -- string representing the name of the + ``MixedIntegerLinearProgram`` EXAMPLES:: @@ -691,7 +688,7 @@ cdef class MixedIntegerLinearProgram(SageObject): """ self._backend.problem_name(name) - def new_variable(self, real=False, binary=False, integer=False, nonnegative=False, name="", + def new_variable(self, real=False, binary=False, integer=False, nonnegative=False, name='', indices=None): r""" Return a new :class:`MIPVariable` instance. @@ -708,10 +705,10 @@ cdef class MixedIntegerLinearProgram(SageObject): .. SEEALSO:: - :meth:`set_min`, :meth:`get_min` -- set/get the lower bound of a - variable. + variable - :meth:`set_max`, :meth:`get_max` -- set/get the upper bound of a - variable. + variable INPUT: @@ -719,21 +716,21 @@ cdef class MixedIntegerLinearProgram(SageObject): arguments to ``True`` to ensure that the variable gets the corresponding type. - - ``nonnegative`` -- boolean, default ``False``. Whether the + - ``nonnegative`` -- boolean (default: ``False``); whether the variable should be assumed to be nonnegative. Rather useless - for the binary type. + for the binary type - - ``name`` -- string. Associates a name to the variable. This + - ``name`` -- string; associates a name to the variable. This is only useful when exporting the linear program to a file using ``write_mps`` or ``write_lp``, and has no other effect. - ``indices`` -- (optional) an iterable of keys; components - corresponding to these keys are created in order, - and access to components with other keys will raise an - error; otherwise components of this variable can be - indexed by arbitrary keys and are created dynamically - on access + corresponding to these keys are created in order, + and access to components with other keys will raise an + error; otherwise components of this variable can be + indexed by arbitrary keys and are created dynamically + on access OUTPUT: @@ -829,7 +826,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def default_variable(self): """ - Return the default :class:`MIPVariable` of `self`. + Return the default :class:`MIPVariable` of ``self``. EXAMPLES:: @@ -850,7 +847,7 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - - ``n`` -- integer. The number of variables to construct. + - ``n`` -- integer; the number of variables to construct OUTPUT: @@ -888,7 +885,7 @@ cdef class MixedIntegerLinearProgram(SageObject): cpdef int number_of_variables(self) noexcept: r""" - Returns the number of variables used so far. + Return the number of variables used so far. Note that this is backend-dependent, i.e. we count solver's variables rather than user's variables. An example of the latter @@ -906,11 +903,11 @@ cdef class MixedIntegerLinearProgram(SageObject): sage: p.add_constraint(p[0] - 2*p[1], min=1) sage: p.number_of_variables() 3 - sage: p = MixedIntegerLinearProgram(solver="glpk") + sage: p = MixedIntegerLinearProgram(solver='glpk') sage: p.add_constraint(p[0] - p[2], min=1, max=4) sage: p.number_of_variables() 2 - sage: p = MixedIntegerLinearProgram(solver="gurobi") # optional - Gurobi + sage: p = MixedIntegerLinearProgram(solver='gurobi') # optional - Gurobi sage: p.add_constraint(p[0] - p[2], min=1, max=4) # optional - Gurobi sage: p.number_of_variables() # optional - Gurobi 3 @@ -919,7 +916,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def constraints(self, indices = None): r""" - Returns a list of constraints, as 3-tuples. + Return a list of constraints, as 3-tuples. INPUT: @@ -981,7 +978,7 @@ cdef class MixedIntegerLinearProgram(SageObject): Running the examples from above, reordering applied:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.add_constraint(p[0] - p[2], min=1, max=4) sage: p.add_constraint(p[0] - 2*p[1], min=1) sage: sorted(reorder_constraint(*c) for c in p.constraints()) @@ -1021,7 +1018,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def polyhedron(self, **kwds): r""" - Returns the polyhedron defined by the Linear Program. + Return the polyhedron defined by the Linear Program. INPUT: @@ -1185,10 +1182,10 @@ cdef class MixedIntegerLinearProgram(SageObject): When constraints and variables have names :: - sage: p = MixedIntegerLinearProgram(solver="GLPK") - sage: x = p.new_variable(name="Hey") + sage: p = MixedIntegerLinearProgram(solver='GLPK') + sage: x = p.new_variable(name='Hey') sage: p.set_objective(x[1] + x[2]) - sage: p.add_constraint(-3*x[1] + 2*x[2], max=2, name="Constraint_1") + sage: p.add_constraint(-3*x[1] + 2*x[2], max=2, name='Constraint_1') sage: p.show() Maximization: Hey[1] + Hey[2] @@ -1200,7 +1197,7 @@ cdef class MixedIntegerLinearProgram(SageObject): Without any names :: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.set_objective(x[1] + x[2]) sage: p.add_constraint(-3*x[1] + 2*x[2], max=2) @@ -1321,22 +1318,22 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - - ``filename`` -- The file in which you want the problem - to be written. + - ``filename`` -- the file in which you want the problem + to be written - - ``modern`` -- Lets you choose between Fixed MPS and Free MPS + - ``modern`` -- lets you choose between Fixed MPS and Free MPS: - - ``True`` -- Outputs the problem in Free MPS - - ``False`` -- Outputs the problem in Fixed MPS + - ``True`` -- outputs the problem in Free MPS + - ``False`` -- outputs the problem in Fixed MPS EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.set_objective(x[1] + x[2]) - sage: p.add_constraint(-3*x[1] + 2*x[2], max=2, name="OneConstraint") + sage: p.add_constraint(-3*x[1] + 2*x[2], max=2, name='OneConstraint') sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".mps") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.mps') as f: ....: p.write_mps(f.name) Writing problem data to ... 17 records were written @@ -1354,17 +1351,17 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - - ``filename`` -- The file in which you want the problem - to be written. + - ``filename`` -- the file in which you want the problem + to be written EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: p.set_objective(x[1] + x[2]) sage: p.add_constraint(-3*x[1] + 2*x[2], max=2) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".lp") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.lp') as f: ....: p.write_lp(f.name) Writing problem data to ... 9 lines were written @@ -1404,7 +1401,7 @@ cdef class MixedIntegerLinearProgram(SageObject): Return the value of a variable component in the backend as an integer. The value is rounded to an integer, and if the difference to the - original value is greater than ``tolerance``, raise a ``RuntimeError``. + original value is greater than ``tolerance``, raise a :exc:`RuntimeError`. INPUT: @@ -1412,9 +1409,7 @@ cdef class MixedIntegerLinearProgram(SageObject): - ``tolerance`` -- a nonnegative real number - OUTPUT: - - An element of ``ZZ``. + OUTPUT: an element of ``ZZ`` EXAMPLES:: @@ -1449,10 +1444,10 @@ cdef class MixedIntegerLinearProgram(SageObject): Return the value of a variable component in the backend as a boolean. The value is rounded to an integer, and if the difference to the - original value is greater than ``tolerance``, raise a ``RuntimeError``. + original value is greater than ``tolerance``, raise a :exc:`RuntimeError`. If the rounded value is anything other than 0 or 1, also a - ``RuntimeError`` is raised. + :exc:`RuntimeError` is raised. INPUT: @@ -1460,9 +1455,7 @@ cdef class MixedIntegerLinearProgram(SageObject): - ``tolerance`` -- a nonnegative real number - OUTPUT: - - A ``bool``. + OUTPUT: a ``bool`` EXAMPLES:: @@ -1533,9 +1526,9 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - ``*lists`` -- any instance of ``MIPVariable`` (or one of its - elements), or lists of them. + elements), or lists of them - - ``convert`` -- ``None`` (default), ``ZZ``, ``bool``, or ``True``. + - ``convert`` -- (default: ``None``) ``ZZ``, ``bool``, or ``True``: - if ``convert=None`` (default), return all variable values as the backend provides them, i.e., as an element of :meth:`base_ring` or a @@ -1555,7 +1548,7 @@ cdef class MixedIntegerLinearProgram(SageObject): :meth:`base_ring` is an exact ring). Required if ``convert`` is not ``None`` and any integer conversion is to be done. If the variable value differs from the nearest integer by more than ``tolerance``, - raise a ``RuntimeError``. + raise a :exc:`RuntimeError`. OUTPUT: @@ -1761,7 +1754,7 @@ cdef class MixedIntegerLinearProgram(SageObject): elif convert is True: get_backend_variable_value = self._backend_variable_value_True else: - raise ValueError('convert should be one of None, ZZ, bool, True') + raise ValueError('convert should be one of None, ZZ, boolean, True') val = [] for l in lists: @@ -1791,11 +1784,11 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_objective(self,obj): r""" - Sets the objective of the ``MixedIntegerLinearProgram``. + Set the objective of the ``MixedIntegerLinearProgram``. INPUT: - - ``obj`` -- A linear function to be optimized. + - ``obj`` -- a linear function to be optimized ( can also be set to ``None`` or ``0`` or any number when just looking for a feasible solution ) @@ -1833,7 +1826,6 @@ cdef class MixedIntegerLinearProgram(SageObject): sage: p.set_objective(42) sage: p.solve() # tol 1e-8 42 - """ cdef list values = [] @@ -1862,11 +1854,11 @@ cdef class MixedIntegerLinearProgram(SageObject): def add_constraint(self, linear_function, max=None, min=None, name=None, return_indices=False): r""" - Adds a constraint to the ``MixedIntegerLinearProgram``. + Add a constraint to the ``MixedIntegerLinearProgram``. INPUT: - - ``linear_function`` -- Four different types of arguments are + - ``linear_function`` -- four different types of arguments are admissible: - A linear function. In this case, one of the arguments @@ -1897,10 +1889,10 @@ cdef class MixedIntegerLinearProgram(SageObject): linear functions. Not allowed if the ``linear_function`` argument is a symbolic (in)-equality. - - ``name`` -- A name for the constraint. + - ``name`` -- a name for the constraint - ``return_indices`` -- boolean (default: ``False``), - whether to return the indices of the added constraints. + whether to return the indices of the added constraints OUTPUT: @@ -2007,7 +1999,7 @@ cdef class MixedIntegerLinearProgram(SageObject): Complex constraints:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: b = p.new_variable(nonnegative=True) sage: p.add_constraint(b[8] - b[15] <= 3*b[8] + 9) sage: p.show() @@ -2049,7 +2041,7 @@ cdef class MixedIntegerLinearProgram(SageObject): Do not add redundant elements (notice only one copy of each constraint is added):: - sage: lp = MixedIntegerLinearProgram(solver="GLPK", check_redundant=True) + sage: lp = MixedIntegerLinearProgram(solver='GLPK', check_redundant=True) sage: for each in range(10): ....: lp.add_constraint(lp[0]-lp[1], min=1) sage: lp.show() @@ -2225,15 +2217,13 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - - ``constraint`` -- dictionary of a non-zero linear function - without constant term. + - ``constraint`` -- dictionary of a nonzero linear function + without constant term - ``min_bound``, ``max_bound`` -- base ring elements or - ``None``. The lower and upper bound. - - OUTPUT: + ``None``; the lower and upper bound - Boolean. Whether the (normalized) constraint has already been added. + OUTPUT: boolean; whether the (normalized) constraint has already been added EXAMPLES:: @@ -2266,11 +2256,11 @@ cdef class MixedIntegerLinearProgram(SageObject): def remove_constraint(self, int i): r""" - Removes a constraint from self. + Removes a constraint from ``self``. INPUT: - - ``i`` -- Index of the constraint to remove. + - ``i`` -- index of the constraint to remove EXAMPLES:: @@ -2308,7 +2298,7 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - - ``constraints`` -- an iterable containing the indices of the rows to remove. + - ``constraints`` -- an iterable containing the indices of the rows to remove EXAMPLES:: @@ -2371,7 +2361,6 @@ cdef class MixedIntegerLinearProgram(SageObject): :issue:`34881`:: sage: MixedIntegerLinearProgram().remove_constraints([]) - """ if self._check_redundant: for i in sorted(constraints, reverse=True): @@ -2381,12 +2370,12 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_binary(self, ee): r""" - Sets a variable or a ``MIPVariable`` as binary. + Set a variable or a ``MIPVariable`` as binary. INPUT: - - ``ee`` -- An instance of ``MIPVariable`` or one of - its elements. + - ``ee`` -- an instance of ``MIPVariable`` or one of + its elements EXAMPLES:: @@ -2404,7 +2393,6 @@ cdef class MixedIntegerLinearProgram(SageObject): variables as integer while keeping the others as they are:: sage: p.set_integer(x[3]) - """ cdef MIPVariable e e = ee @@ -2420,16 +2408,14 @@ cdef class MixedIntegerLinearProgram(SageObject): def is_binary(self, e): r""" - Tests whether the variable ``e`` is binary. Variables are real by + Test whether the variable ``e`` is binary. Variables are real by default. INPUT: - - ``e`` -- A variable (not a ``MIPVariable``, but one of its elements.) - - OUTPUT: + - ``e`` -- a variable (not a ``MIPVariable``, but one of its elements) - ``True`` if the variable ``e`` is binary; ``False`` otherwise. + OUTPUT: ``True`` if the variable ``e`` is binary; ``False`` otherwise EXAMPLES:: @@ -2446,12 +2432,12 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_integer(self, ee): r""" - Sets a variable or a ``MIPVariable`` as integer. + Set a variable or a ``MIPVariable`` as integer. INPUT: - - ``ee`` -- An instance of ``MIPVariable`` or one of - its elements. + - ``ee`` -- an instance of ``MIPVariable`` or one of + its elements EXAMPLES:: @@ -2484,16 +2470,14 @@ cdef class MixedIntegerLinearProgram(SageObject): def is_integer(self, e): r""" - Tests whether the variable is an integer. Variables are real by + Test whether the variable is an integer. Variables are real by default. INPUT: - - ``e`` -- A variable (not a ``MIPVariable``, but one of its elements.) + - ``e`` -- a variable (not a ``MIPVariable``, but one of its elements) - OUTPUT: - - ``True`` if the variable ``e`` is an integer; ``False`` otherwise. + OUTPUT: ``True`` if the variable ``e`` is an integer; ``False`` otherwise EXAMPLES:: @@ -2510,12 +2494,12 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_real(self,ee): r""" - Sets a variable or a ``MIPVariable`` as real. + Set a variable or a ``MIPVariable`` as real. INPUT: - - ``ee`` -- An instance of ``MIPVariable`` or one of - its elements. + - ``ee`` -- an instance of ``MIPVariable`` or one of + its elements EXAMPLES:: @@ -2533,7 +2517,6 @@ cdef class MixedIntegerLinearProgram(SageObject): variables as binary while keeping the others as they are:: sage: p.set_binary(x[3]) - """ cdef MIPVariable e e = ee @@ -2551,15 +2534,13 @@ cdef class MixedIntegerLinearProgram(SageObject): def is_real(self, e): r""" - Tests whether the variable is real. + Test whether the variable is real. INPUT: - - ``e`` -- A variable (not a ``MIPVariable``, but one of its elements.) - - OUTPUT: + - ``e`` -- a variable (not a ``MIPVariable``, but one of its elements) - ``True`` if the variable is real; ``False`` otherwise. + OUTPUT: ``True`` if the variable is real; ``False`` otherwise EXAMPLES:: @@ -2579,23 +2560,21 @@ cdef class MixedIntegerLinearProgram(SageObject): def solve(self, log=None, objective_only=False): r""" - Solves the ``MixedIntegerLinearProgram``. + Solve the ``MixedIntegerLinearProgram``. INPUT: - - ``log`` -- integer (default: ``None``) The verbosity level. Indicates + - ``log`` -- integer (default: ``None``); the verbosity level. Indicates whether progress should be printed during computation. The solver is initialized to report no progress. - - ``objective_only`` -- Boolean variable. + - ``objective_only`` -- boolean: - When set to ``True``, only the objective function is returned. - When set to ``False`` (default), the optimal numerical values are stored (takes computational time). - OUTPUT: - - The optimal value taken by the objective function. + OUTPUT: the optimal value taken by the objective function .. WARNING:: @@ -2661,18 +2640,18 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_min(self, v, min): r""" - Sets the minimum value of a variable. + Set the minimum value of a variable. INPUT: - - ``v`` -- a variable. + - ``v`` -- a variable - - ``min`` -- the minimum value the variable can take. When - ``min=None``, the variable has no lower bound. + - ``min`` -- the minimum value the variable can take; when + ``min=None``, the variable has no lower bound .. SEEALSO:: - - :meth:`get_min` -- get the minimum value of a variable. + - :meth:`get_min` -- get the minimum value of a variable EXAMPLES:: @@ -2705,14 +2684,14 @@ cdef class MixedIntegerLinearProgram(SageObject): def set_max(self, v, max): r""" - Sets the maximum value of a variable. + Set the maximum value of a variable. INPUT: - - ``v`` -- a variable. + - ``v`` -- a variable - - ``max`` -- the maximum value the variable can take. When - ``max=None``, the variable has no upper bound. + - ``max`` -- the maximum value the variable can take; when + ``max=None``, the variable has no upper bound EXAMPLES:: @@ -2742,7 +2721,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def get_min(self, v): r""" - Returns the minimum value of a variable. + Return the minimum value of a variable. INPUT: @@ -2773,11 +2752,11 @@ cdef class MixedIntegerLinearProgram(SageObject): def get_max(self, v): r""" - Returns the maximum value of a variable. + Return the maximum value of a variable. INPUT: - - ``v`` -- a variable. + - ``v`` -- a variable OUTPUT: @@ -2801,7 +2780,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def solver_parameter(self, name, value = None): """ - Return or define a solver parameter + Return or define a solver parameter. The solver parameters are by essence solver-specific, which means their meaning heavily depends on the solver used. @@ -2813,22 +2792,22 @@ cdef class MixedIntegerLinearProgram(SageObject): Very common parameters have aliases making them solver-independent. For example, the following:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("timelimit", 60) Sets the solver to stop its computations after 60 seconds, and works with GLPK, CPLEX , SCIP, and Gurobi. - - ``"timelimit"`` -- defines the maximum time spent on a - computation. Measured in seconds. + - ``'timelimit'`` -- defines the maximum time spent on a + computation (measured in seconds) - Another example is the ``"logfile"`` parameter, which is used to specify + Another example is the ``'logfile'`` parameter, which is used to specify the file in which computation logs are recorded. By default, the logs are not recorded, and we can disable this feature providing an empty filename. This is currently working with CPLEX and Gurobi:: sage: # optional - cplex - sage: p = MixedIntegerLinearProgram(solver="CPLEX") + sage: p = MixedIntegerLinearProgram(solver='CPLEX') sage: p.solver_parameter("logfile") '' sage: p.solver_parameter("logfile", "/dev/null") @@ -2852,7 +2831,7 @@ cdef class MixedIntegerLinearProgram(SageObject): The command :: - sage: p = MixedIntegerLinearProgram(solver="CPLEX") # optional - CPLEX + sage: p = MixedIntegerLinearProgram(solver='CPLEX') # optional - CPLEX sage: p.solver_parameter("CPX_PARAM_TILIM", 60) # optional - CPLEX works as intended. @@ -2866,14 +2845,14 @@ cdef class MixedIntegerLinearProgram(SageObject): INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("timelimit", 60) sage: p.solver_parameter("timelimit") 60.0 @@ -2885,15 +2864,15 @@ cdef class MixedIntegerLinearProgram(SageObject): cpdef sum(self, L): r""" - Efficiently computes the sum of a sequence of + Efficiently compute the sum of a sequence of :class:`~sage.numerical.linear_functions.LinearFunction` elements INPUT: - - ``mip`` -- the :class:`MixedIntegerLinearProgram` parent. + - ``mip`` -- the :class:`MixedIntegerLinearProgram` parent - ``L`` -- list of - :class:`~sage.numerical.linear_functions.LinearFunction` instances. + :class:`~sage.numerical.linear_functions.LinearFunction` instances .. NOTE:: @@ -2921,7 +2900,7 @@ cdef class MixedIntegerLinearProgram(SageObject): def get_backend(self): r""" - Returns the backend instance used. + Return the backend instance used. This might be useful when access to additional functions provided by the backend is needed. @@ -2930,7 +2909,7 @@ cdef class MixedIntegerLinearProgram(SageObject): This example uses the simplex algorithm and prints information:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: x, y = p[0], p[1] sage: p.add_constraint(2*x + 3*y, max=6) sage: p.add_constraint(3*x + 2*y, max=6) @@ -2959,7 +2938,7 @@ cdef class MixedIntegerLinearProgram(SageObject): EXAMPLES:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: x, y = p[0], p[1] sage: p.add_constraint(2*x + 3*y, max=6) sage: p.add_constraint(3*x + 2*y, max=6) @@ -2990,7 +2969,7 @@ cdef class MixedIntegerLinearProgram(SageObject): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("mip_gap_tolerance",100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -3025,7 +3004,7 @@ cdef class MixedIntegerLinearProgram(SageObject): sage: # needs sage.graphs sage: g = graphs.CubeGraph(9) - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.solver_parameter("mip_gap_tolerance",100) sage: b = p.new_variable(binary=True) sage: p.set_objective(p.sum(b[v] for v in g)) @@ -3049,12 +3028,12 @@ cdef class MixedIntegerLinearProgram(SageObject): def interactive_lp_problem(self,form='standard'): r""" - Returns an InteractiveLPProblem and, if available, a basis. + Return an InteractiveLPProblem and, if available, a basis. INPUT: - - ``form`` -- (default: ``"standard"``) a string specifying return type: either - ``None``, or ``"std"`` or ``"standard"``, respectively returns an instance of + - ``form`` -- (default: ``'standard'``) a string specifying return type: either + ``None``, or ``'std'`` or ``'standard'``, respectively returns an instance of :class:`InteractiveLPProblem` or of :class:`InteractiveLPProblemStandardForm` OUTPUT: @@ -3068,7 +3047,7 @@ cdef class MixedIntegerLinearProgram(SageObject): EXAMPLES:: - sage: p = MixedIntegerLinearProgram(names=['m'], solver="GLPK") + sage: p = MixedIntegerLinearProgram(names=['m'], solver='GLPK') sage: x = p.new_variable(nonnegative=True) sage: y = p.new_variable(nonnegative=True, name='n') sage: v = p.new_variable(nonnegative=True) @@ -3205,7 +3184,7 @@ class MIPSolverException(RuntimeError): No continuous solution:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: v = p.new_variable(nonnegative=True) sage: p.add_constraint(v[0], max=5.5) sage: p.add_constraint(v[0], min=7.6) @@ -3220,7 +3199,7 @@ class MIPSolverException(RuntimeError): No integer solution:: - sage: p = MixedIntegerLinearProgram(solver="GLPK") + sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: v = p.new_variable(nonnegative=True) sage: p.add_constraint(v[0], max=5.6) sage: p.add_constraint(v[0], min=5.2) @@ -3247,34 +3226,34 @@ cdef class MIPVariable(FiniteFamily): You should not instantiate this class directly. Instead, use :meth:`MixedIntegerLinearProgram.new_variable`. """ - def __init__(self, mip, vtype, name="", lower_bound=0, upper_bound=None, + def __init__(self, mip, vtype, name='', lower_bound=0, upper_bound=None, indices=None): r""" Constructor for ``MIPVariable``. INPUT: - - ``parent`` -- :class:`MIPVariableParent`. The parent of the - MIP variable. + - ``parent`` -- :class:`MIPVariableParent`; the parent of the + MIP variable - - ``mip`` -- :class:`MixedIntegerLinearProgram`. The - underlying linear program. + - ``mip`` -- :class:`MixedIntegerLinearProgram`; the + underlying linear program - - ``vtype`` (integer) -- Defines the type of the variables - (default is ``REAL``, i.e., ``vtype=-1``). + - ``vtype`` -- integer; defines the type of the variables + (default: ``REAL``, i.e., ``vtype=-1``) - - ``name`` -- A name for the ``MIPVariable``. + - ``name`` -- a name for the ``MIPVariable`` - ``lower_bound``, ``upper_bound`` -- lower bound and upper bound on the variable. Set to ``None`` to indicate that the variable is unbounded. - ``indices`` -- (optional) an iterable of keys; components - corresponding to these keys are created in order, - and access to components with other keys will raise an - error; otherwise components of this variable can be - indexed by arbitrary keys and are created dynamically - on access + corresponding to these keys are created in order, + and access to components with other keys will raise an + error; otherwise components of this variable can be + indexed by arbitrary keys and are created dynamically + on access For more information, see the method ``MixedIntegerLinearProgram.new_variable``. @@ -3284,7 +3263,6 @@ cdef class MIPVariable(FiniteFamily): sage: p = MixedIntegerLinearProgram(solver='GLPK') sage: p.new_variable(nonnegative=True) MIPVariable with 0 real components, >= 0 - """ super().__init__({}) self._p = mip @@ -3299,7 +3277,7 @@ cdef class MIPVariable(FiniteFamily): def __copy__(self): r""" - Returns a copy of ``self``. + Return a copy of ``self``. EXAMPLES:: @@ -3321,7 +3299,7 @@ cdef class MIPVariable(FiniteFamily): def __deepcopy__(self, memo={}): r""" - Returns a copy of ``self``. + Return a copy of ``self``. EXAMPLES:: @@ -3343,7 +3321,7 @@ cdef class MIPVariable(FiniteFamily): def __getitem__(self, i): r""" - Returns the variable component corresponding to the key. + Return the variable component corresponding to the key. Returns the component asked. @@ -3394,7 +3372,6 @@ cdef class MIPVariable(FiniteFamily): Traceback (most recent call last): ... IndexError: 0 does not index a component of MIPVariable with 0 real components - """ cdef int j if i in self._dictionary: @@ -3419,7 +3396,7 @@ cdef class MIPVariable(FiniteFamily): def copy_for_mip(self, mip): r""" - Returns a copy of ``self`` suitable for a new :class:`MixedIntegerLinearProgram` + Return a copy of ``self`` suitable for a new :class:`MixedIntegerLinearProgram` instance ``mip``. For this to make sense, ``mip`` should have been obtained as a copy of @@ -3456,7 +3433,6 @@ cdef class MIPVariable(FiniteFamily): Traceback (most recent call last): ... IndexError: 5 does not index a component of MIPVariable with 2 real components - """ cdef MIPVariable cp = type(self)(mip, self._vtype, self._name, self._lower_bound, self._upper_bound) @@ -3466,12 +3442,12 @@ cdef class MIPVariable(FiniteFamily): def set_min(self, min): r""" - Sets a lower bound on the variable. + Set a lower bound on the variable. INPUT: - ``min`` -- a lower bound, or ``None`` to mean that the variable is - unbounded. + unbounded EXAMPLES:: @@ -3497,7 +3473,6 @@ cdef class MIPVariable(FiniteFamily): sage: x.set_min(42) sage: p.get_min(y[0]) is None True - """ self._lower_bound = min for v in self._dictionary.values(): @@ -3505,12 +3480,12 @@ cdef class MIPVariable(FiniteFamily): def set_max(self, max): r""" - Sets an upper bound on the variable. + Set an upper bound on the variable. INPUT: - ``max`` -- an upper bound, or ``None`` to mean that the variable is - unbounded. + unbounded EXAMPLES:: @@ -3541,7 +3516,7 @@ cdef class MIPVariable(FiniteFamily): def _repr_(self): r""" - Returns a representation of self. + Return a representation of ``self``. EXAMPLES:: @@ -3549,7 +3524,7 @@ cdef class MIPVariable(FiniteFamily): sage: v = p.new_variable() sage: v MIPVariable with 0 real components - sage: x = p.new_variable(integer=True, nonnegative=True, name="x") + sage: x = p.new_variable(integer=True, nonnegative=True, name='x') sage: x[0] x_0 sage: x @@ -3558,12 +3533,12 @@ cdef class MIPVariable(FiniteFamily): x_1 sage: x MIPVariable x with 2 integer components, >= 0 - sage: y = p.new_variable(real=True, name="y", indices=range(5)) + sage: y = p.new_variable(real=True, name='y', indices=range(5)) sage: y.set_min(0) sage: y.set_max(17) sage: y MIPVariable y with 5 real components, >= 0, <= 17 - sage: z = p.new_variable(binary=True, name="z", indices=range(7)) + sage: z = p.new_variable(binary=True, name='z', indices=range(7)) sage: z MIPVariable z with 7 binary components """ @@ -3622,7 +3597,7 @@ cdef class MIPVariable(FiniteFamily): def mip(self): r""" - Returns the :class:`MixedIntegerLinearProgram` in which ``self`` is a variable. + Return the :class:`MixedIntegerLinearProgram` in which ``self`` is a variable. EXAMPLES:: diff --git a/src/sage/numerical/optimize.py b/src/sage/numerical/optimize.py index ed16642ed55..b3e42a6a6a2 100644 --- a/src/sage/numerical/optimize.py +++ b/src/sage/numerical/optimize.py @@ -40,9 +40,8 @@ def find_root(f, a, b, xtol=10e-13, rtol=2.0**-50, maxiter=100, full_output=Fals - ``maxiter`` -- integer; if convergence is not achieved in ``maxiter`` iterations, an error is raised. Must be `\geq 0`. - - ``full_output`` -- bool (default: ``False``), if ``True``, also return - object that contains information about convergence. - + - ``full_output`` -- boolean (default: ``False``); if ``True``, also return + object that contains information about convergence EXAMPLES: @@ -100,7 +99,6 @@ def find_root(f, a, b, xtol=10e-13, rtol=2.0**-50, maxiter=100, full_output=Fals Traceback (most recent call last): ... RuntimeError: f appears to have no zero on the interval - """ try: return f.find_root(a=a,b=b,xtol=xtol,rtol=rtol,maxiter=maxiter,full_output=full_output) @@ -219,15 +217,14 @@ def find_local_minimum(f, a, b, tol=1.48e-08, maxfun=500): INPUT: - - ``f`` -- a function of at most one variable. + - ``f`` -- a function of at most one variable - - ``a``, ``b`` -- endpoints of interval on which to minimize `f`. + - ``a``, ``b`` -- endpoints of interval on which to minimize `f` - ``tol`` -- the convergence tolerance - ``maxfun`` -- maximum function evaluations - OUTPUT: - ``minval`` -- (float) the minimum value that `f` takes on in the @@ -235,7 +232,6 @@ def find_local_minimum(f, a, b, tol=1.48e-08, maxfun=500): - ``x`` -- (float) the point at which `f` takes on the minimum value - EXAMPLES:: sage: f = lambda x: x*cos(x) @@ -300,7 +296,7 @@ def find_local_minimum(f, a, b, tol=1.48e-08, maxfun=500): return fval, xmin -def minimize(func, x0, gradient=None, hessian=None, algorithm="default", +def minimize(func, x0, gradient=None, hessian=None, algorithm='default', verbose=False, **args): r""" This function is an interface to a variety of algorithms for computing @@ -308,24 +304,24 @@ def minimize(func, x0, gradient=None, hessian=None, algorithm="default", INPUT: - - ``func`` -- Either a symbolic function or a Python function whose + - ``func`` -- either a symbolic function or a Python function whose argument is a tuple with `n` components - - ``x0`` -- Initial point for finding minimum. + - ``x0`` -- initial point for finding minimum - - ``gradient`` -- Optional gradient function. This will be computed + - ``gradient`` -- (optional) gradient function. This will be computed automatically for symbolic functions. For Python functions, it allows the use of algorithms requiring derivatives. It should accept a tuple of arguments and return a NumPy array containing the partial derivatives at that point. - - ``hessian`` -- Optional hessian function. This will be computed + - ``hessian`` -- (optional) hessian function. This will be computed automatically for symbolic functions. For Python functions, it allows the use of algorithms requiring derivatives. It should accept a tuple of arguments and return a NumPy array containing the second partial derivatives of the function. - - ``algorithm`` -- String specifying algorithm to use. Options are + - ``algorithm`` -- string specifying algorithm to use. Options are ``'default'`` (for Python functions, the simplex method is the default) (for symbolic functions bfgs is the default): @@ -339,7 +335,7 @@ def minimize(func, x0, gradient=None, hessian=None, algorithm="default", - ``'ncg'`` -- (newton-conjugate gradient) requires gradient and hessian - - ``verbose`` -- (default: ``False``) print convergence message + - ``verbose`` -- boolean (default: ``False``); print convergence message .. NOTE:: @@ -360,12 +356,12 @@ def minimize(func, x0, gradient=None, hessian=None, algorithm="default", Try the newton-conjugate gradient method; the gradient and hessian are computed automatically:: - sage: minimize(f, [.1, .3, .4], algorithm="ncg") # abs tol 1e-6 # needs sage.symbolic + sage: minimize(f, [.1, .3, .4], algorithm='ncg') # abs tol 1e-6 # needs sage.symbolic (1.0, 1.0, 1.0) We get additional convergence information with the `verbose` option:: - sage: minimize(f, [.1, .3, .4], algorithm="ncg", verbose=True) # needs sage.symbolic + sage: minimize(f, [.1, .3, .4], algorithm='ncg', verbose=True) # needs sage.symbolic Optimization terminated successfully. ... (0.9999999..., 0.999999..., 0.999999...) @@ -397,7 +393,7 @@ def minimize(func, x0, gradient=None, hessian=None, algorithm="default", ....: der[-1] = 200r*(x[-1r]-x[-2r]**2r) ....: return der sage: minimize(rosen, [.1,.3,.4], gradient=rosen_der, # abs tol 1e-6 - ....: algorithm="bfgs") + ....: algorithm='bfgs') (1.0, 1.0, 1.0) """ from sage.structure.element import Expression @@ -450,10 +446,9 @@ def minimize_constrained(func,cons,x0,gradient=None,algorithm='default', **args) r""" Minimize a function with constraints. - INPUT: - - ``func`` -- Either a symbolic function, or a Python function whose + - ``func`` -- either a symbolic function, or a Python function whose argument is a tuple with `n` components - ``cons`` -- constraints. This should be either a function or list of @@ -465,20 +460,19 @@ def minimize_constrained(func,cons,x0,gradient=None,algorithm='default', **args) of intervals and there are no constraints for a given variable, that component can be (``None``, ``None``). - - ``x0`` -- Initial point for finding minimum + - ``x0`` -- initial point for finding minimum - - ``algorithm`` -- Optional, specify the algorithm to use: + - ``algorithm`` -- (optional) specify the algorithm to use: - - ``'default'`` -- default choices + - ``'default'`` -- default choices - - ``'l-bfgs-b'`` -- only effective if you specify bound constraints. - See [ZBN1997]_. + - ``'l-bfgs-b'`` -- only effective if you specify bound constraints; + see [ZBN1997]_ - - ``gradient`` -- Optional gradient function. This will be computed + - ``gradient`` -- (optional) gradient function. This will be computed automatically for symbolic functions. This is only used when the constraints are specified as a list of intervals. - EXAMPLES: Let us maximize `x + y - 50` subject to the following constraints: @@ -540,7 +534,6 @@ def minimize_constrained(func,cons,x0,gradient=None,algorithm='default', **args) sage: c2(y,x) = 1-y sage: minimize_constrained(f, [c1, c2], (0,0)) (1.0, 0.0) - """ from sage.structure.element import Expression from sage.ext.fast_callable import fast_callable @@ -597,34 +590,33 @@ def find_fit(data, model, initial_guess=None, parameters=None, variables=None, s INPUT: - - ``data`` -- A two dimensional table of floating point numbers of the + - ``data`` -- a two dimensional table of floating point numbers of the form `[[x_{1,1}, x_{1,2}, \ldots, x_{1,k}, f_1], [x_{2,1}, x_{2,2}, \ldots, x_{2,k}, f_2], \ldots, [x_{n,1}, x_{n,2}, \ldots, x_{n,k}, f_n]]` given as either a list of lists, matrix, or numpy array. - - ``model`` -- Either a symbolic expression, symbolic function, or a + - ``model`` -- either a symbolic expression, symbolic function, or a Python function. ``model`` has to be a function of the variables `(x_1, x_2, \ldots, x_k)` and free parameters `(a_1, a_2, \ldots, a_l)`. - - ``initial_guess`` -- (default: ``None``) Initial estimate for the + - ``initial_guess`` -- (default: ``None``) initial estimate for the parameters `(a_1, a_2, \ldots, a_l)`, given as either a list, tuple, vector or numpy array. If ``None``, the default estimate for each parameter is `1`. - - ``parameters`` -- (default: ``None``) A list of the parameters + - ``parameters`` -- (default: ``None``) a list of the parameters `(a_1, a_2, \ldots, a_l)`. If model is a symbolic function it is ignored, and the free parameters of the symbolic function are used. - - ``variables`` -- (default: ``None``) A list of the variables + - ``variables`` -- (default: ``None``) a list of the variables `(x_1, x_2, \ldots, x_k)`. If model is a symbolic function it is ignored, and the variables of the symbolic function are used. - - ``solution_dict`` -- (default: ``False``) if ``True``, return the - solution as a dictionary rather than an equation. - + - ``solution_dict`` -- boolean (default: ``False``); if ``True``, return the + solution as a dictionary rather than an equation EXAMPLES: @@ -776,11 +768,11 @@ def binpacking(items, maximum=1, k=None, solver=None, verbose=0, INPUT: - ``items`` -- list or dict; either a list of real values (the items' - weight), or a dictionary associating to each item its weight. + weight), or a dictionary associating to each item its weight - - ``maximum`` -- (default: 1); the maximal size of a bin + - ``maximum`` -- (default: 1) the maximal size of a bin - - ``k`` -- integer (default: ``None``); Number of bins + - ``k`` -- integer (default: ``None``); number of bins: - When set to an integer value, the function returns a partition of the items into `k` bins if possible, and raises an exception otherwise. @@ -788,7 +780,7 @@ def binpacking(items, maximum=1, k=None, solver=None, verbose=0, - When set to ``None``, the function returns a partition of the items using the least possible number of bins. - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -796,11 +788,11 @@ def binpacking(items, maximum=1, k=None, solver=None, verbose=0, of the class :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``); sets the level of verbosity. Set + - ``verbose`` -- integer (default: 0); sets the level of verbosity. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` OUTPUT: diff --git a/src/sage/numerical/sdp.pyx b/src/sage/numerical/sdp.pyx index 7e214ad5023..069bea9b3a4 100644 --- a/src/sage/numerical/sdp.pyx +++ b/src/sage/numerical/sdp.pyx @@ -196,7 +196,7 @@ also implements the :class:`SDPSolverException` exception, as well as the :widths: 30, 70 :delim: | - :meth:`~SemidefiniteProgram.add_constraint` | Adds a constraint to the ``SemidefiniteProgram`` + :meth:`~SemidefiniteProgram.add_constraint` | Add a constraint to the ``SemidefiniteProgram`` :meth:`~SemidefiniteProgram.base_ring` | Return the base ring :meth:`~SemidefiniteProgram.dual_variable` | Return optimal dual variable block :meth:`~SemidefiniteProgram.get_backend` | Return the backend instance used @@ -272,7 +272,7 @@ cdef class SemidefiniteProgram(SageObject): .. SEEALSO:: - - :func:`default_sdp_solver` -- Returns/Sets the default SDP solver. + - :func:`default_sdp_solver` -- returns/sets the default SDP solver EXAMPLES: @@ -323,12 +323,11 @@ cdef class SemidefiniteProgram(SageObject): .. SEEALSO:: - - :meth:`default_sdp_solver` -- Returns/Sets the default SDP solver. + - :meth:`default_sdp_solver` -- returns/Sets the default SDP solver EXAMPLES:: sage: p = SemidefiniteProgram(maximization=True) - """ self._first_variable_names = list(names) from sage.numerical.backends.generic_sdp_backend import get_solver @@ -423,7 +422,7 @@ cdef class SemidefiniteProgram(SageObject): def __getitem__(self, v): r""" - Returns the symbolic variable corresponding to the key + Return the symbolic variable corresponding to the key from a default dictionary. It returns the element asked, and otherwise creates it. @@ -450,9 +449,7 @@ cdef class SemidefiniteProgram(SageObject): """ Return the base ring. - OUTPUT: - - A ring. The coefficients that the chosen solver supports. + OUTPUT: a ring. The coefficients that the chosen solver supports EXAMPLES:: @@ -464,12 +461,12 @@ cdef class SemidefiniteProgram(SageObject): def set_problem_name(self,name): r""" - Sets the name of the ``SemidefiniteProgram``. + Set the name of the ``SemidefiniteProgram``. INPUT: - - ``name`` -- A string representing the name of the - ``SemidefiniteProgram``. + - ``name`` -- string representing the name of the + ``SemidefiniteProgram`` EXAMPLES:: @@ -482,7 +479,7 @@ cdef class SemidefiniteProgram(SageObject): def new_variable(self, name=""): r""" - Returns an instance of :class:`SDPVariable` associated + Return an instance of :class:`SDPVariable` associated to the current instance of :class:`SemidefiniteProgram`. A new variable ``x`` is defined by:: @@ -496,11 +493,11 @@ cdef class SemidefiniteProgram(SageObject): INPUT: - - ``dim`` -- integer. Defines the dimension of the dictionary. + - ``dim`` -- integer; defines the dimension of the dictionary If ``x`` has dimension `2`, its fields will be of the form ``x[key1][key2]``. Deprecated. - - ``name`` -- string. Associates a name to the variable. + - ``name`` -- string; associates a name to the variable EXAMPLES:: @@ -531,7 +528,7 @@ cdef class SemidefiniteProgram(SageObject): INPUT: - - ``n`` -- integer. The number of variables to construct. + - ``n`` -- integer; the number of variables to construct OUTPUT: @@ -592,7 +589,6 @@ cdef class SemidefiniteProgram(SageObject): r""" Return the number of variables used so far. - EXAMPLES:: sage: p = SemidefiniteProgram() @@ -612,7 +608,7 @@ cdef class SemidefiniteProgram(SageObject): When constraints and variables have names :: sage: p = SemidefiniteProgram() - sage: x = p.new_variable(name="hihi") + sage: x = p.new_variable(name='hihi') sage: a1 = matrix([[1,2],[2,3]]) sage: a2 = matrix([[2,3],[3,4]]) sage: a3 = matrix([[3,4],[4,5]]) @@ -735,7 +731,6 @@ cdef class SemidefiniteProgram(SageObject): sage: x_sol = p.get_values(x) # needs cvxopt sage: sorted(x_sol) # needs cvxopt [3, 5] - """ val = [] for l in lists: @@ -762,11 +757,11 @@ cdef class SemidefiniteProgram(SageObject): def set_objective(self, obj): r""" - Sets the objective of the :class:`SemidefiniteProgram`. + Set the objective of the :class:`SemidefiniteProgram`. INPUT: - - ``obj`` -- A semidefinite function to be optimized. + - ``obj`` -- a semidefinite function to be optimized (can also be set to ``None`` or ``0`` when just looking for a feasible solution) @@ -817,11 +812,11 @@ cdef class SemidefiniteProgram(SageObject): def add_constraint(self, linear_function, name=None): r""" - Adds a constraint to the ``SemidefiniteProgram``. + Add a constraint to the ``SemidefiniteProgram``. INPUT: - - ``linear_function`` -- Two different types of arguments are possible: + - ``linear_function`` -- two different types of arguments are possible: - A linear function. In this case, arguments ``min`` or ``max`` have to be specified. @@ -829,7 +824,7 @@ cdef class SemidefiniteProgram(SageObject): ``A <= B <= C``, ``A >= B >= C`` or ``A == B``. In this case, arguments ``min`` and ``max`` will be ignored. - - ``name`` -- A name for the constraint. + - ``name`` -- a name for the constraint EXAMPLES: @@ -890,7 +885,6 @@ cdef class SemidefiniteProgram(SageObject): sage: p = SemidefiniteProgram() sage: p.add_constraint(sum([])) - """ if linear_function is 0: return @@ -919,15 +913,13 @@ cdef class SemidefiniteProgram(SageObject): INPUT: - - ``objective_only`` -- Boolean variable. - - - When set to ``True``, only the objective function is returned. - - When set to ``False`` (default), the optimal numerical values - are stored (takes computational time). + - ``objective_only`` -- boolean: - OUTPUT: + - when set to ``True``, only the objective function is returned + - when set to ``False`` (default), the optimal numerical values + are stored (takes computational time) - The optimal value taken by the objective function. + OUTPUT: the optimal value taken by the objective function TESTS: @@ -961,15 +953,14 @@ cdef class SemidefiniteProgram(SageObject): """ The `i`-th dual variable. - Available after self.solve() is called, otherwise the result is undefined. + Available after ``self.solve()`` is called, otherwise the result is + undefined. INPUT: - - ``index`` (integer) -- the constraint's id + - ``index`` -- integer; the constraint's id - OUTPUT: - - The matrix of the `i`-th dual variable. + OUTPUT: the matrix of the `i`-th dual variable EXAMPLES: @@ -1011,17 +1002,16 @@ cdef class SemidefiniteProgram(SageObject): cpdef slack(self, int i, sparse=False): """ - Slack of the `i`-th constraint + Slack of the `i`-th constraint. - Available after self.solve() is called, otherwise the result is undefined + Available after ``self.solve()`` is called, otherwise the result is + undefined. INPUT: - - ``index`` (integer) -- the constraint's id. - - OUTPUT: + - ``index`` -- integer; the constraint's id - The matrix of the slack of the `i`-th constraint + OUTPUT: the matrix of the slack of the `i`-th constraint EXAMPLES:: @@ -1071,15 +1061,15 @@ cdef class SemidefiniteProgram(SageObject): INPUT: - - ``name`` (string) -- the parameter + - ``name`` -- string; the parameter - ``value`` -- the parameter's value if it is to be defined, - or ``None`` (default) to obtain its current value. + or ``None`` (default) to obtain its current value EXAMPLES:: sage: # needs cvxopt - sage: p. = SemidefiniteProgram(solver="cvxopt", + sage: p. = SemidefiniteProgram(solver='cvxopt', ....: maximization=False) sage: p.solver_parameter("show_progress", True) sage: p.solver_parameter("show_progress") @@ -1107,13 +1097,13 @@ cdef class SemidefiniteProgram(SageObject): cpdef sum(self, L): r""" - Efficiently computes the sum of a sequence of + Efficiently compute the sum of a sequence of :class:`~sage.numerical.linear_functions.LinearFunction` elements. INPUT: - ``L`` -- list of - :class:`~sage.numerical.linear_functions.LinearFunction` instances. + :class:`~sage.numerical.linear_functions.LinearFunction` instances .. NOTE:: @@ -1150,7 +1140,7 @@ cdef class SemidefiniteProgram(SageObject): This example prints a matrix coefficient:: - sage: p = SemidefiniteProgram(solver="cvxopt") + sage: p = SemidefiniteProgram(solver='cvxopt') sage: x = p.new_variable() sage: a1 = matrix([[1, 2.], [2., 3.]]) sage: a2 = matrix([[3, 4.], [4., 5.]]) @@ -1182,7 +1172,7 @@ class SDPSolverException(RuntimeError): No solution:: sage: # needs cvxopt - sage: p = SemidefiniteProgram(solver="cvxopt") + sage: p = SemidefiniteProgram(solver='cvxopt') sage: x = p.new_variable() sage: p.set_objective(x[0]) sage: a = matrix([[1,2],[2,4]]) @@ -1220,13 +1210,13 @@ cdef class SDPVariable(Element): INPUT: - - ``parent`` -- :class:`SDPVariableParent`. The parent of the - SDP variable. + - ``parent`` -- :class:`SDPVariableParent`; the parent of the + SDP variable - - ``sdp`` -- :class:`SemidefiniteProgram`. The - underlying linear program. + - ``sdp`` -- :class:`SemidefiniteProgram`; the + underlying linear program - - ``name`` -- A name for the ``SDPVariable``. + - ``name`` -- a name for the ``SDPVariable`` - ``lower_bound``, ``upper_bound`` -- lower bound and upper bound on the variable. Set to ``None`` to indicate that the @@ -1259,7 +1249,6 @@ cdef class SDPVariable(Element): sage: p.set_objective(v[0] + v[1]) sage: v[0] x_0 - """ cdef int j if i in self._dict: @@ -1389,11 +1378,9 @@ cdef class SDPVariableParent(Parent): def _repr_(self): r""" - Return representation of self. - - OUTPUT: + Return representation of ``self``. - String. + OUTPUT: string EXAMPLES:: @@ -1410,7 +1397,7 @@ cdef class SDPVariableParent(Parent): OUTPUT: This is required for the coercion framework. We raise a - ``TypeError`` to abort search for any coercion to another + :exc:`TypeError` to abort search for any coercion to another parent for binary operations. The only interesting operations involving :class:`SDPVariable` elements are actions by matrices. @@ -1428,11 +1415,9 @@ cdef class SDPVariableParent(Parent): def _element_constructor_(self, sdp, name=""): """ - The Element constructor - - INPUT/OUTPUT: + The Element constructor. - See :meth:`SDPVariable.__init__`. + INPUT/OUTPUT: see :meth:`SDPVariable.__init__` EXAMPLES:: diff --git a/src/sage/parallel/decorate.py b/src/sage/parallel/decorate.py index b8ea5e75bb3..b23e997b7e2 100644 --- a/src/sage/parallel/decorate.py +++ b/src/sage/parallel/decorate.py @@ -99,9 +99,7 @@ def __call__(self, f): - ``f`` -- Python callable object or function - OUTPUT: - - - Decorated version of ``f`` + OUTPUT: decorated version of ``f`` EXAMPLES:: @@ -129,7 +127,7 @@ class ParallelFunction(): """ def __init__(self, parallel, func): """ - .. note:: + .. NOTE:: This is typically accessed indirectly through :meth:`Parallel.__call__`. @@ -137,10 +135,9 @@ def __init__(self, parallel, func): INPUT: - ``parallel`` -- a :class:`Parallel` object which controls - how the parallel execution will be done. + how the parallel execution will be done - ``func`` -- Python callable object or function - """ self.parallel = parallel self.func = func @@ -170,7 +167,7 @@ def __get__(self, instance, owner): Implement part of the descriptor protocol for :class:`ParallelFunction` objects. - .. note:: + .. NOTE:: This is the key to fixing :issue:`11461`. @@ -228,7 +225,7 @@ def __get__(self, instance, owner): def _sage_argspec_(self): """ - Returns the argument specification for this object, which is + Return the argument specification for this object, which is just the argument specification for the underlying function. See :mod:`sage.misc.sageinspect` for more information on this convention. @@ -249,7 +246,7 @@ def _sage_argspec_(self): def _sage_src_(self): """ - Returns the source code for this object, which is just the + Return the source code for this object, which is just the source code for the underlying function. See :mod:`sage.misc.sageinspect` for more information on this convention. @@ -269,7 +266,7 @@ def _sage_src_(self): def _instancedoc_(self): r""" - Returns the docstring for this object, which is just the + Return the docstring for this object, which is just the docstring for the underlying function. See :mod:`sage.misc.sageinspect` for more information on this convention. @@ -304,13 +301,13 @@ def parallel(p_iter='fork', ncpus=None, **kwds): INPUT: - - ``p_iter`` -- parallel iterator function or string: - - ``'fork'`` -- (default) use a new forked subprocess for each input - - ``'multiprocessing'`` -- use multiprocessing library - - ``'reference'`` -- use a fake serial reference implementation - - ``ncpus`` -- integer, maximal number of subprocesses to use at the same time - - ``timeout`` -- number of seconds until each subprocess is killed (only supported - by 'fork'; zero means not at all) + - ``p_iter`` -- parallel iterator function or string: + - ``'fork'`` -- (default) use a new forked subprocess for each input + - ``'multiprocessing'`` -- use multiprocessing library + - ``'reference'`` -- use a fake serial reference implementation + - ``ncpus`` -- integer; maximal number of subprocesses to use at the same time + - ``timeout`` -- number of seconds until each subprocess is killed (only supported + by ``'fork'``; zero means not at all) .. warning:: @@ -318,7 +315,6 @@ def parallel(p_iter='fork', ncpus=None, **kwds): subprocess is spawned, so none of your local state (variables, certain functions, etc.) is available. - EXAMPLES: We create a simple decoration for a simple function. The number @@ -436,7 +432,7 @@ def __init__(self, timeout=0, verbose=False): - ``timeout`` -- (default: 0) kill the subprocess after it has run this many seconds (wall time), or if ``timeout`` is zero, do not kill it. - - ``verbose`` -- (default: ``False``) whether to print anything about + - ``verbose`` -- boolean (default: ``False``); whether to print anything about what the decorator does (e.g., killing the subprocess) EXAMPLES:: @@ -455,9 +451,7 @@ def __call__(self, f): - ``f`` -- a function - OUTPUT: - - - A decorated function. + OUTPUT: a decorated function EXAMPLES:: @@ -488,7 +482,7 @@ def fork(f=None, timeout=0, verbose=False): - ``f`` -- a function - ``timeout`` -- (default: 0) if positive, kill the subprocess after this many seconds (wall time) - - ``verbose`` -- (default: ``False``) whether to print anything + - ``verbose`` -- boolean (default: ``False``); whether to print anything about what the decorator does (e.g., killing the subprocess) .. warning:: diff --git a/src/sage/parallel/map_reduce.py b/src/sage/parallel/map_reduce.py index 460f91242c8..239afb6df8b 100644 --- a/src/sage/parallel/map_reduce.py +++ b/src/sage/parallel/map_reduce.py @@ -293,7 +293,7 @@ should be a prefix (including a possible directory) for the profile dump:: sage: import tempfile - sage: d = tempfile.TemporaryDirectory(prefix="RESetMR_profile") + sage: d = tempfile.TemporaryDirectory(prefix='RESetMR_profile') sage: res = S.run(profile=d.name) # random [RESetMapReduceWorker-1:58] (20:00:41.444) Profiling in /home/user/.sage/temp/.../32414/RESetMR_profilewRCRAx/profcomp1 @@ -346,7 +346,7 @@ `Logging facility for Python `_ for more detail on logging and log system configuration. -.. note:: +.. NOTE:: Calls to logger which involve printing the node are commented out in the code, because the printing (to a string) of the node can be very time @@ -393,16 +393,16 @@ map-reduce protocol: - ``_results`` -- a :class:`~multiprocessing.queues.SimpleQueue` where - the master gathers the results sent by the workers. + the master gathers the results sent by the workers - ``_active_tasks`` -- a :class:`~multiprocessing.Semaphore` recording - the number of active tasks. The work is complete when it reaches 0. + the number of active tasks; the work is complete when it reaches 0 - ``_done`` -- a :class:`~multiprocessing.Lock` which ensures that - shutdown is done only once. + shutdown is done only once - ``_aborted`` -- a :func:`~multiprocessing.Value` storing a shared :class:`ctypes.c_bool` which is ``True`` if the computation was aborted - before all workers ran out of work. -- ``_workers`` -- a list of :class:`RESetMapReduceWorker` objects. - Each worker is identified by its position in this list. + before all workers ran out of work +- ``_workers`` -- list of :class:`RESetMapReduceWorker` objects + Each worker is identified by its position in this list Each **worker** is a process (:class:`RESetMapReduceWorker` inherits from :class:`~multiprocessing.Process`) which contains: @@ -413,11 +413,11 @@ worker. It is used as a stack by the worker. Thiefs steal from the bottom of this queue. - ``worker._request`` -- a :class:`~multiprocessing.queues.SimpleQueue` storing - steal request submitted to ``worker``. + steal request submitted to ``worker`` - ``worker._read_task``, ``worker._write_task`` -- a - :class:`~multiprocessing.queues.Pipe` used to transfer node during steal. + :class:`~multiprocessing.queues.Pipe` used to transfer node during steal - ``worker._thief`` -- a :class:`~threading.Thread` which is in charge of - stealing from ``worker._todo``. + stealing from ``worker._todo`` Here is a schematic of the architecture: @@ -515,7 +515,7 @@ - :class:`RESetMPExample` -- a simple basic example - :class:`RESetParallelIterator` -- a more advanced example using non standard - communication configuration. + communication configuration Tests ----- @@ -591,8 +591,7 @@ def proc_number(max_proc=None): INPUT: - - ``max_proc`` -- an upper bound on the number of processes or - ``None``. + - ``max_proc`` -- an upper bound on the number of processes or ``None`` EXAMPLES:: @@ -644,7 +643,7 @@ def __init__(self, task_number): sage: from sage.parallel.map_reduce import ActiveTaskCounterDarwin as ATC sage: t = ATC(4) - sage: TestSuite(t).run(skip="_test_pickling", verbose=True) + sage: TestSuite(t).run(skip='_test_pickling', verbose=True) running ._test_new() . . . pass """ self._active_tasks = mp.Value(ctypes.c_int, task_number) @@ -750,7 +749,7 @@ class ActiveTaskCounterPosix(): computation process. This is the standard implementation on POSIX compliant OSes. We essentially wrap a semaphore. - .. note:: + .. NOTE:: A legitimate question is whether there is a need in keeping the two implementations. I ran the following experiment on my machine:: @@ -778,7 +777,7 @@ def __init__(self, task_number): sage: from sage.parallel.map_reduce import ActiveTaskCounter as ATC sage: t = ATC(4) - sage: TestSuite(t).run(skip="_test_pickling", verbose=True) + sage: TestSuite(t).run(skip='_test_pickling', verbose=True) running ._test_new() . . . pass """ self._active_tasks = mp.Semaphore(task_number) @@ -897,7 +896,7 @@ class RESetMapReduce(): - or a triple ``roots, children, post_process`` as follows - - ``roots=r`` -- The root of the enumeration + - ``roots=r`` -- the root of the enumeration - ``children=c`` -- a function iterating through children nodes, given a parent node - ``post_process=p`` -- a post-processing function @@ -908,9 +907,9 @@ class RESetMapReduce(): Description of the map/reduce operation: - - ``map_function=f`` -- (default to ``None``) - - ``reduce_function=red`` -- (default to ``None``) - - ``reduce_init=init`` -- (default to ``None``) + - ``map_function=f`` -- (default: ``None``) + - ``reduce_function=red`` -- (default: ``None``) + - ``reduce_init=init`` -- (default: ``None``) .. SEEALSO:: @@ -985,11 +984,9 @@ def roots(self): r""" Return the roots of ``self``. - OUTPUT: - - An iterable of nodes. + OUTPUT: an iterable of nodes - .. note:: This should be overloaded in applications. + .. NOTE:: This should be overloaded in applications. EXAMPLES:: @@ -1008,11 +1005,9 @@ def map_function(self, o): - ``o`` -- a node - OUTPUT: - - By default ``1``. + OUTPUT: by default ``1`` - .. note:: This should be overloaded in applications. + .. NOTE:: This should be overloaded in applications. EXAMPLES:: @@ -1034,11 +1029,9 @@ def reduce_function(self, a, b): - ``a``, ``b`` -- two values to be reduced - OUTPUT: - - By default the sum of ``a`` and ``b``. + OUTPUT: by default the sum of ``a`` and ``b`` - .. note:: This should be overloaded in applications. + .. NOTE:: This should be overloaded in applications. EXAMPLES:: @@ -1063,7 +1056,7 @@ def post_process(self, a): With the default post-processing function, which is the identity function, this returns ``a`` itself. - .. note:: This should be overloaded in applications. + .. NOTE:: This should be overloaded in applications. EXAMPLES:: @@ -1083,7 +1076,7 @@ def reduce_init(self): r""" Return the initial element for a reduction. - .. note:: This should be overloaded in applications. + .. NOTE:: This should be overloaded in applications. TESTS:: @@ -1103,8 +1096,8 @@ def setup_workers(self, max_proc=None, reduce_locally=True): INPUT: - - ``max_proc`` -- (integer) an upper bound on the number of - worker processes. + - ``max_proc`` -- integer; an upper bound on the number of + worker processes - ``reduce_locally`` -- whether the workers should reduce locally their work or sends results to the master as soon as possible. @@ -1397,9 +1390,7 @@ def random_worker(self): r""" Return a random worker. - OUTPUT: - - A worker for ``self`` chosen at random. + OUTPUT: a worker for ``self`` chosen at random EXAMPLES:: @@ -1433,7 +1424,7 @@ def run(self, maximum number of worker processors to use. The actual number is also bounded by the value of the environment variable ``SAGE_NUM_THREADS`` (the number of cores by default). - - ``reduce_locally`` -- See :class:`RESetMapReduceWorker` (default: ``True``) + - ``reduce_locally`` -- see :class:`RESetMapReduceWorker` (default: ``True``) - ``timeout`` -- a timeout on the computation (default: ``None``) - ``profile`` -- directory/filename prefix for profiling, or ``None`` for no profiling (default: ``None``) @@ -1570,9 +1561,9 @@ class RESetMapReduceWorker(mp.Process): INPUT: - ``mapred`` -- the instance of :class:`RESetMapReduce` for which - this process is working. + this process is working - - ``iproc`` -- the id of this worker. + - ``iproc`` -- the id of this worker - ``reduce_locally`` -- when reducing the results. Three possible values are supported: @@ -1645,9 +1636,7 @@ def steal(self): r""" Steal some node from another worker. - OUTPUT: - - A node stolen from another worker chosen at random. + OUTPUT: a node stolen from another worker chosen at random EXAMPLES:: @@ -1659,7 +1648,7 @@ def steal(self): sage: # known bug (Issue #27537) sage: w0, w1 = EX._workers sage: w0._todo.append(42) - sage: thief0 = Thread(target = w0._thief, name="Thief") + sage: thief0 = Thread(target = w0._thief, name='Thief') sage: thief0.start() sage: w1.steal() 42 @@ -1753,7 +1742,7 @@ def run_myself(self): self._stats[0] = 0 self._stats[3] = 0 logger.debug("Launching thief") - self._thief = Thread(target=self._thief, name="Thief") + self._thief = Thread(target=self._thief, name='Thief') self._thief.start() self._res = reduce_init() @@ -1810,11 +1799,9 @@ def walk_branch_locally(self, node): INPUT: - - ``node`` -- the root of the subtree explored. + - ``node`` -- the root of the subtree explored - OUTPUT: - - Nothing, the result are stored in ``self._res``. + OUTPUT: nothing, the result are stored in ``self._res`` This is where the actual work is performed. @@ -1867,7 +1854,7 @@ class RESetMPExample(RESetMapReduce): INPUT: - - ``maxl`` -- the maximum size of permutations generated (default to `9`). + - ``maxl`` -- the maximum size of permutations generated (default: `9`) This computes the generating series of permutations counted by their size up to size ``maxl``. @@ -1881,7 +1868,6 @@ class RESetMPExample(RESetMapReduce): + 24*x^4 + 6*x^3 + 2*x^2 + x + 1 .. SEEALSO:: This is an example of :class:`RESetMapReduce` - """ def __init__(self, maxl=9): r""" @@ -1915,7 +1901,7 @@ def children(self, l): INPUT: - - ``l`` -- a list containing a permutation + - ``l`` -- list containing a permutation OUTPUT: @@ -1936,7 +1922,7 @@ def map_function(self, l): INPUT: - - ``l`` -- a list containing a permutation + - ``l`` -- list containing a permutation OUTPUT: diff --git a/src/sage/parallel/multiprocessing_sage.py b/src/sage/parallel/multiprocessing_sage.py index 2ccab49ac0f..ab2ee3f95ee 100644 --- a/src/sage/parallel/multiprocessing_sage.py +++ b/src/sage/parallel/multiprocessing_sage.py @@ -25,11 +25,9 @@ def pyprocessing(processes=0): INPUT: - ``processes`` -- integer (default: 0); if 0, set to the number - of processors on the computer. + of processors on the computer - OUTPUT: - - - a (partially evaluated) function + OUTPUT: a (partially evaluated) function EXAMPLES:: @@ -55,9 +53,7 @@ def parallel_iter(processes, f, inputs): - ``f`` -- function - ``inputs`` -- an iterable of pairs (args, kwds) - OUTPUT: - - - iterator over values of ``f`` at ``args,kwds`` in some random order. + OUTPUT: iterator over values of ``f`` at ``args, kwds`` in some random order EXAMPLES:: diff --git a/src/sage/parallel/parallelism.py b/src/sage/parallel/parallelism.py index 010372467d9..6df09f58fad 100644 --- a/src/sage/parallel/parallelism.py +++ b/src/sage/parallel/parallelism.py @@ -82,7 +82,6 @@ class Parallelism(Singleton, SageObject): Switching off all parallelizations:: sage: Parallelism().set(nproc=1) - """ def __init__(self): r""" @@ -104,7 +103,6 @@ def __init__(self): The test suite is passed:: sage: TestSuite(par).run() - """ self._default = ncpus() # default number of proc. used in parallelizations @@ -121,7 +119,6 @@ def _repr_(self): sage: Parallelism()._repr_() 'Number of processes for parallelization:\n - linbox computations: 1\n - tensor computations: 1' - """ resu = "Number of processes for parallelization:\n" for field in sorted(self._nproc): @@ -164,7 +161,6 @@ def reset(self): - tensor computations: 1 sage: Parallelism().get_default() # random (depends on the computer) 8 - """ self._default = ncpus() for field in self._nproc: @@ -233,7 +229,6 @@ def set(self, field=None, nproc=None): Number of processes for parallelization: - linbox computations: 1 - tensor computations: 1 - """ if field is None: for fi in self._nproc: @@ -277,7 +272,6 @@ def get(self, field): sage: Parallelism().set('tensor', nproc=4) sage: Parallelism().get('tensor') 4 - """ if field not in self._nproc: raise KeyError("entry for field {} is not ".format(field) + @@ -305,7 +299,6 @@ def get_all(self): sage: Parallelism().set(nproc=4) sage: Parallelism().get_all() {'linbox': 4, 'tensor': 4} - """ return self._nproc @@ -339,7 +332,6 @@ def set_default(self, nproc=None): sage: Parallelism().set_default() sage: Parallelism().get_default() # random (depends on the computer) 8 - """ if nproc is None: self._default = ncpus() @@ -367,6 +359,5 @@ def get_default(self): sage: Parallelism().set_default(nproc=4) sage: Parallelism().get_default() 4 - """ return self._default diff --git a/src/sage/parallel/reference.py b/src/sage/parallel/reference.py index 36dd7a8bb76..6a855874330 100644 --- a/src/sage/parallel/reference.py +++ b/src/sage/parallel/reference.py @@ -16,15 +16,13 @@ def parallel_iter(f, inputs): INPUT: - ``f`` -- a Python function that can be pickled using - the pickle_function command. + the ``pickle_function`` command - - ``inputs`` -- a list of pickleable pairs (args, kwds), where - args is a tuple and kwds is a dictionary. + - ``inputs`` -- list of pickleable pairs (args, kwds), where + args is a tuple and kwds is a dictionary - OUTPUT: - - - iterator over 2-tuples ``(inputs[i], f(inputs[i]))``, where the - order may be completely random + OUTPUT: iterator over 2-tuples ``(inputs[i], f(inputs[i]))``, where the + order may be completely random EXAMPLES:: diff --git a/src/sage/parallel/use_fork.py b/src/sage/parallel/use_fork.py index 24341dfb2de..bc5293e0248 100644 --- a/src/sage/parallel/use_fork.py +++ b/src/sage/parallel/use_fork.py @@ -27,11 +27,11 @@ class WorkerData(): This just stores three attributes: - - ``input``: the input value used by this worker + - ``input`` -- the input value used by this worker - - ``starttime``: the walltime when this worker started + - ``starttime`` -- the walltime when this worker started - - ``failure``: an optional message indicating the kind of failure + - ``failure`` -- an optional message indicating the kind of failure EXAMPLES:: @@ -61,15 +61,13 @@ class p_iter_fork(): INPUT: - - ``ncpus`` -- the maximal number of simultaneous - subprocesses to spawn - - ``timeout`` -- (float, default: 0) wall time in seconds until - a subprocess is automatically killed - - ``verbose`` -- (default: ``False``) whether to print - anything about what the iterator does (e.g., killing - subprocesses) - - ``reset_interfaces`` -- (default: ``True``) whether to reset - all pexpect interfaces + - ``ncpus`` -- the maximal number of simultaneous subprocesses to spawn + - ``timeout`` -- float (default: 0); wall time in seconds until a + subprocess is automatically killed + - ``verbose`` -- boolean (default: ``False``); whether to print anything + about what the iterator does (e.g., killing subprocesses) + - ``reset_interfaces`` -- boolean (default: ``True``); whether to reset all + pexpect interfaces EXAMPLES:: @@ -114,11 +112,9 @@ def __call__(self, f, inputs): - ``f`` -- a function (or more general, any callable) - - ``inputs`` -- a list of pairs ``(args, kwds)`` to be used as + - ``inputs`` -- list of pairs ``(args, kwds)`` to be used as arguments to ``f``, where ``args`` is a tuple and ``kwds`` is - a dictionary. - - OUTPUT: + a dictionary EXAMPLES:: @@ -263,7 +259,7 @@ def _subprocess(self, f, dir, args, kwds={}): - ``dir`` -- name of a directory - - ``args`` -- a tuple with positional arguments for ``f`` + - ``args`` -- tuple with positional arguments for ``f`` - ``kwds`` -- (optional) a dict with keyword arguments for ``f`` diff --git a/src/sage/plot/animate.py b/src/sage/plot/animate.py index b5aae572283..896249d8cd1 100644 --- a/src/sage/plot/animate.py +++ b/src/sage/plot/animate.py @@ -160,17 +160,16 @@ class Animation(WithEqualityById, SageObject): INPUT: - - ``v`` -- iterable of Sage objects. These should preferably be + - ``v`` -- iterable of Sage objects; these should preferably be graphics objects, but if they aren't, then :meth:`make_image` is called on them. - - ``xmin``, ``xmax``, ``ymin``, ``ymax`` -- the ranges of the x and y axes. + - ``xmin``, ``xmax``, ``ymin``, ``ymax`` -- the ranges of the x and y axes - ``**kwds`` -- all additional inputs are passed onto the rendering command. E.g., use ``figsize`` to adjust the resolution and aspect ratio. - EXAMPLES:: sage: x = SR.var("x") @@ -185,7 +184,7 @@ class Animation(WithEqualityById, SageObject): The :meth:`show` method takes arguments to specify the delay between frames (measured in hundredths of a second, default - value 20) and the number of iterations (default value 0, which + value 20) and the number of iterations (default: 0, which means to iterate forever). To iterate 4 times with half a second between each frame:: @@ -256,7 +255,7 @@ def __init__(self, v=None, **kwds): def _combine_kwds(self, *kwds_tuple): """ - Returns a dictionary which is a combination of the all the + Return a dictionary which is a combination of the all the dictionaries in kwds_tuple. This also does the appropriate thing for taking the mins and maxes of all of the x/y mins/maxes. @@ -406,7 +405,7 @@ def __mul__(self, other): def __len__(self): """ - Length of self + Length of ``self``. EXAMPLES:: @@ -459,7 +458,6 @@ def make_image(self, frame, filename, **kwds): sage: v = os.listdir(d); v.sort(); v ['00000000.png', '00000001.png', '00000002.png', '00000003.png'] sage: B.show() # not tested - """ p = plot.plot(frame, **kwds) p.save_image(filename) @@ -476,13 +474,10 @@ def png(self, dir=None): INPUT: - - ``dir`` -- Directory in which to store frames. Default - ``None``; in this case, a temporary directory will be - created for storing the frames. + - ``dir`` -- (default: ``None``) directory in which to store frames; in + this case, a temporary directory will be created for storing the frames - OUTPUT: - - Absolute path to the directory containing the PNG images + OUTPUT: absolute path to the directory containing the PNG images EXAMPLES:: @@ -518,7 +513,6 @@ def graphics_array(self, ncols=3): The frames must be acceptable inputs for :class:`sage.plot.multigraphics.GraphicsArray`. - EXAMPLES:: sage: # needs sage.schemes @@ -563,8 +557,8 @@ def graphics_array(self, ncols=3): def gif(self, delay=20, savefile=None, iterations=0, show_path=False, use_ffmpeg=False): r""" - Returns an animated gif composed from rendering the graphics - objects in self. + Return an animated gif composed from rendering the graphics + objects in ``self``. This method will only work if either (a) the ImageMagick software suite is installed, i.e., you have the ``magick/convert`` @@ -576,19 +570,19 @@ def gif(self, delay=20, savefile=None, iterations=0, show_path=False, INPUT: - - ``delay`` -- (default: 20) delay in hundredths of a - second between frames + - ``delay`` -- (default: 20) delay in hundredths of a + second between frames - - ``savefile`` -- file that the animated gif gets saved - to + - ``savefile`` -- file that the animated gif gets saved + to - - ``iterations`` -- integer (default: 0); number of - iterations of animation. If 0, loop forever. + - ``iterations`` -- integer (default: 0); number of + iterations of animation. If 0, loop forever. - - ``show_path`` -- boolean (default: ``False``); if True, - print the path to the saved file + - ``show_path`` -- boolean (default: ``False``); if True, + print the path to the saved file - - ``use_ffmpeg`` -- boolean (default: ``False``); if True, use + - ``use_ffmpeg`` -- boolean (default: ``False``); if ``True``, use 'ffmpeg' by default instead of ImageMagick If ``savefile`` is not specified: in notebook mode, display the @@ -656,7 +650,7 @@ def _gif_from_imagemagick(self, savefile=None, show_path=False, INPUT: - - ``savefile`` -- file that the mpeg gets saved to. + - ``savefile`` -- file that the mpeg gets saved to .. warning:: @@ -666,7 +660,7 @@ def _gif_from_imagemagick(self, savefile=None, show_path=False, print the path to the saved file - ``delay`` -- (default: 20) delay in hundredths of a - second between frames + second between frames - ``iterations`` -- integer (default: 0); number of iterations of animation. If 0, loop forever. @@ -693,7 +687,6 @@ def _gif_from_imagemagick(self, savefile=None, show_path=False, Executable 'magick' not found on PATH. Further installation instructions might be available at https://www.imagemagick.org/. - """ from sage.features.imagemagick import ImageMagick, Magick ImageMagick().require() @@ -715,7 +708,7 @@ def _gif_from_imagemagick(self, savefile=None, show_path=False, # If a problem with the command occurs, print the log before # raising an error (more verbose than result.check_returncode()) if result.returncode: - print('Command "{}" returned non-zero exit status "{}" ' + print('Command "{}" returned nonzero exit status "{}" ' '(with stderr "{}" and stdout "{}").'.format(result.args, result.returncode, result.stderr.strip(), @@ -732,7 +725,7 @@ def _gif_from_imagemagick(self, savefile=None, show_path=False, def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -805,11 +798,11 @@ def show(self, delay=None, iterations=None, **kwds): INPUT: - - ``delay`` -- (default: 20) delay in hundredths of a - second between frames. + - ``delay`` -- (default: 20) delay in hundredths of a + second between frames - - ``iterations`` -- integer (default: 0); number of - iterations of animation. If 0, loop forever. + - ``iterations`` -- integer (default: 0); number of + iterations of animation. If 0, loop forever. - ``format`` -- (default: gif) format to use for output. Currently supported formats are: gif, @@ -849,19 +842,19 @@ def show(self, delay=None, iterations=None, **kwds): You can also make use of the HTML5 video element in the Sage Notebook:: sage: # long time, optional -- FFmpeg - sage: a.show(format="ogg") - sage: a.show(format="webm") - sage: a.show(format="mp4") - sage: a.show(format="webm", iterations=1) + sage: a.show(format='ogg') + sage: a.show(format='webm') + sage: a.show(format='mp4') + sage: a.show(format='webm', iterations=1) Other backends may support other file formats as well:: sage: # long time, optional -- FFmpeg - sage: a.show(format="flash") - sage: a.show(format="matroska") - sage: a.show(format="avi") - sage: a.show(format="wmv") - sage: a.show(format="quicktime") + sage: a.show(format='flash') + sage: a.show(format='matroska') + sage: a.show(format='avi') + sage: a.show(format='wmv') + sage: a.show(format='quicktime') TESTS: @@ -903,7 +896,7 @@ def ffmpeg(self, savefile=None, show_path=False, output_format=None, INPUT: - - ``savefile`` -- file that the mpeg gets saved to. + - ``savefile`` -- file that the mpeg gets saved to .. warning:: @@ -922,7 +915,7 @@ def ffmpeg(self, savefile=None, show_path=False, output_format=None, used. - ``ffmpeg_options`` -- string (default: ``''``); this string is - passed directly to ffmpeg. + passed directly to ffmpeg - ``delay`` -- integer (default: ``None``); delay in hundredths of a second between frames. The framerate is 100/delay. @@ -934,7 +927,7 @@ def ffmpeg(self, savefile=None, show_path=False, output_format=None, for animated gif output and requires ``ffmpeg`` version 0.9 or later. For older versions, set ``iterations=None``. - - ``pix_fmt`` -- string (default: 'rgb24'); used only for gif + - ``pix_fmt`` -- string (default: ``'rgb24'``); used only for gif output. Different values such as 'rgb8' or 'pal8' may be necessary depending on how ffmpeg was installed. Set ``pix_fmt=None`` to disable this option. @@ -1043,8 +1036,8 @@ def ffmpeg(self, savefile=None, show_path=False, output_format=None, def apng(self, savefile=None, show_path=False, delay=20, iterations=0): r""" - Creates an animated PNG composed from rendering the graphics - objects in self. Return the absolute path to that file. + Create an animated PNG composed from rendering the graphics + objects in ``self``. Return the absolute path to that file. Notice that not all web browsers are capable of displaying APNG files, though they should still present the first frame of the @@ -1054,17 +1047,17 @@ def apng(self, savefile=None, show_path=False, delay=20, iterations=0): Input: - - ``delay`` -- (default: 20) delay in hundredths of a - second between frames + - ``delay`` -- (default: 20) delay in hundredths of a + second between frames - - ``savefile`` -- file that the animated gif gets saved - to + - ``savefile`` -- file that the animated gif gets saved + to - - ``iterations`` -- integer (default: 0); number of - iterations of animation. If 0, loop forever. + - ``iterations`` -- integer (default: 0); number of + iterations of animation. If 0, loop forever. - - ``show_path`` -- boolean (default: ``False``); if True, - print the path to the saved file + - ``show_path`` -- boolean (default: ``False``); if True, + print the path to the saved file EXAMPLES:: @@ -1094,7 +1087,6 @@ def apng(self, savefile=None, show_path=False, delay=20, iterations=0): sage: a = animate([]) sage: a.apng(show_path=True) Animation saved to file ....png. - """ pngdir = self.png() if savefile is None: @@ -1115,16 +1107,15 @@ def save(self, filename=None, show_path=False, use_ffmpeg=False, **kwds): INPUT: - - ``filename`` -- (default: None) name of save file + - ``filename`` -- (default: ``None``) name of save file - - ``show_path`` -- boolean (default: ``False``); if True, - print the path to the saved file + - ``show_path`` -- boolean (default: ``False``); if True, + print the path to the saved file - - ``use_ffmpeg`` -- boolean (default: ``False``); if True, use - 'ffmpeg' by default instead of ImageMagick when creating GIF - files. + - ``use_ffmpeg`` -- boolean (default: ``False``); if ``True``, use + 'ffmpeg' by default instead of ImageMagick when creating GIF files - If filename is None, then in notebook mode, display the + If filename is ``None``, then in notebook mode, display the animation; otherwise, save the animation to a GIF file. If filename ends in '.html', save an :meth:`interactive` version of the animation to an HTML file that uses the Three.js viewer. If @@ -1218,9 +1209,7 @@ def interactive(self, **kwds): viewer are: ``animate``, ``animation_controls``, ``auto_play``, ``delay``, and ``loop``. - OUTPUT: - - A 3D graphics object which, by default, will use the Three.js viewer. + OUTPUT: a 3D graphics object which, by default, will use the Three.js viewer EXAMPLES:: @@ -1240,7 +1229,6 @@ def interactive(self, **kwds): .. SEEALSO:: :ref:`threejs_viewer` - """ from sage.plot.plot3d.base import Graphics3d, KeyframeAnimationGroup # Attempt to convert frames to Graphics3d objects. @@ -1268,7 +1256,7 @@ def interactive(self, **kwds): class APngAssembler: r""" - Builds an APNG_ (Animated PNG) from a sequence of PNG files. + Build an APNG_ (Animated PNG) from a sequence of PNG files. This is used by the :meth:`sage.plot.animate.Animation.apng` method. This code is quite simple; it does little more than copying chunks @@ -1328,7 +1316,7 @@ def __init__(self, out, num_frames, def add_frame(self, pngfile, delay=None, delay_denominator=None): r""" - Adds a single frame to the APNG file. + Add a single frame to the APNG file. INPUT: @@ -1359,7 +1347,6 @@ def add_frame(self, pngfile, delay=None, delay_denominator=None): Traceback (most recent call last): ... RuntimeError: Already reached the declared number of frames - """ if self._idx == self.num_frames: raise RuntimeError("Already reached the declared number of frames") @@ -1378,7 +1365,7 @@ def add_frame(self, pngfile, delay=None, delay_denominator=None): def set_default(self, pngfile): r""" - Adds a default image for the APNG file. + Add a default image for the APNG file. This image is used as a fallback in case some application does not understand the APNG format. This method must be called @@ -1409,7 +1396,6 @@ def set_default(self, pngfile): Traceback (most recent call last): ... RuntimeError: Already reached the declared number of frames - """ if self._idx != 0: raise RuntimeError("Default image must precede all animation frames") @@ -1649,7 +1635,7 @@ def _fctl(self): def _chunk(self, ctype, cdata): r""" - Write a new (or modified) chunk of data + Write a new (or modified) chunk of data. TESTS:: @@ -1716,10 +1702,10 @@ def _testData(cls, name, asFile): INPUT: - - ``name``: The name of the file content. + - ``name`` -- the name of the file content. - - ``asFile``: Whether to return a binary string of the named data - or the path of a file containing that data. + - ``asFile`` -- whether to return a binary string of the named data + or the path of a file containing that data EXAMPLES:: @@ -1777,7 +1763,7 @@ def _testData(cls, name, asFile): d = cls._hex2bin(data[name]) if asFile: from sage.misc.temporary_file import tmp_filename - fn = tmp_filename(ext=".png") + fn = tmp_filename(ext='.png') with open(fn, 'wb') as f: f.write(d) return fn diff --git a/src/sage/plot/arc.py b/src/sage/plot/arc.py index 79dedb5762e..6f45b65fc90 100644 --- a/src/sage/plot/arc.py +++ b/src/sage/plot/arc.py @@ -39,7 +39,7 @@ class Arc(GraphicPrimitive): - ``sector`` -- sector of angle - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -52,7 +52,7 @@ class Arc(GraphicPrimitive): """ def __init__(self, x, y, r1, r2, angle, s1, s2, options): """ - Initializes base class ``Arc``. + Initialize base class ``Arc``. EXAMPLES:: @@ -297,7 +297,7 @@ def bezier_path(self): Graphics object consisting of 1 graphics primitive sage: from math import pi - sage: a = arc((0,0),2,1,0,(pi/5,pi/2+pi/12), linestyle="--", color="red") + sage: a = arc((0,0),2,1,0,(pi/5,pi/2+pi/12), linestyle='--', color='red') sage: b = a[0].bezier_path() sage: b[0] Bezier path from (1.133..., 0.8237...) to (-0.2655..., 0.9911...) @@ -390,23 +390,23 @@ def plot3d(self): aspect_ratio=1.0) def arc(center, r1, r2=None, angle=0.0, sector=(0.0, 2 * pi), **options): r""" - An arc (that is a portion of a circle or an ellipse) + An arc (that is a portion of a circle or an ellipse). Type ``arc.options`` to see all options. INPUT: - - ``center`` -- 2-tuple of real numbers; position of the center. + - ``center`` -- 2-tuple of real numbers; position of the center - ``r1``, ``r2`` -- positive real numbers; radii of the ellipse. If only ``r1`` is set, then the two radii are supposed to be equal and this function returns an arc of circle. - ``angle`` -- real number; angle between the horizontal and the axis that - corresponds to ``r1``. + corresponds to ``r1`` - - ``sector`` -- 2-tuple (default: (0,2*pi))- angles sector in which the arc will - be drawn. + - ``sector`` -- 2-tuple (default: (0,2*pi)); angles sector in which the arc will + be drawn OPTIONS: @@ -414,12 +414,12 @@ def arc(center, r1, r2=None, angle=0.0, sector=(0.0, 2 * pi), **options): - ``thickness`` -- float (default: 1) -- thickness of the arc - - ``color``, ``rgbcolor``; string or 2-tuple (default: 'blue') -- the color - of the arc + - ``color``, ``rgbcolor`` -- string or 2-tuple (default: ``'blue'``); the + color of the arc - - ``linestyle`` -- string (default: ``'solid'``) -- The style of the line, + - ``linestyle`` -- string (default: ``'solid'``); the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, - or ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively. + or ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively EXAMPLES: @@ -454,14 +454,14 @@ def arc(center, r1, r2=None, angle=0.0, sector=(0.0, 2 * pi), **options): Plot an arc of an ellipse in red with a dashed linestyle:: - sage: arc((0,0), 2, 1, 0, (0,pi/2), linestyle="dashed", color="red") + sage: arc((0,0), 2, 1, 0, (0,pi/2), linestyle='dashed', color='red') Graphics object consisting of 1 graphics primitive - sage: arc((0,0), 2, 1, 0, (0,pi/2), linestyle="--", color="red") + sage: arc((0,0), 2, 1, 0, (0,pi/2), linestyle='--', color='red') Graphics object consisting of 1 graphics primitive .. PLOT:: - sphinx_plot(arc((0,0), 2, 1, 0, (0,pi/2), linestyle="dashed", color="red")) + sphinx_plot(arc((0,0), 2, 1, 0, (0,pi/2), linestyle='dashed', color='red')) The default aspect ratio for arcs is 1.0:: diff --git a/src/sage/plot/arrow.py b/src/sage/plot/arrow.py index 23e2517ca56..02442f90ba4 100644 --- a/src/sage/plot/arrow.py +++ b/src/sage/plot/arrow.py @@ -26,7 +26,7 @@ class CurveArrow(GraphicPrimitive): def __init__(self, path, options): """ - Returns an arrow graphics primitive along the provided path (bezier curve). + Return an arrow graphics primitive along the provided path (bezier curve). EXAMPLES:: @@ -49,7 +49,7 @@ def __init__(self, path, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -166,7 +166,7 @@ def _render_on_subplot(self, subplot): class Arrow(GraphicPrimitive): """ - Primitive class that initializes the (line) arrow graphics type + Primitive class that initializes the (line) arrow graphics type. EXAMPLES: @@ -197,7 +197,7 @@ def __init__(self, xtail, ytail, xhead, yhead, options): def get_minmax_data(self): """ - Returns a bounding box for this arrow. + Return a bounding box for this arrow. EXAMPLES:: @@ -283,7 +283,7 @@ def _plot3d_options(self, options=None): def plot3d(self, ztail=0, zhead=0, **kwds): """ - Takes 2D plot and places it in 3D. + Take 2D plot and places it in 3D. EXAMPLES:: @@ -401,7 +401,7 @@ def _render_on_subplot(self, subplot): class CheckNthSubPath: def __init__(self, patch, n): """ - creates a callable object that returns True if the + Creates a callable object that returns ``True`` if the provided path is the n-th path from the patch. """ self._patch = patch @@ -429,8 +429,8 @@ class ConditionalStroke(pe.RendererBase): def __init__(self, condition_func, pe_list): """ - path effect that is only applied when the condition_func - returns True. + Path effect that is only applied when the ``condition_func`` + returns ``True``. """ super().__init__() self._pe_list = pe_list @@ -452,7 +452,7 @@ def draw_path(self, renderer, gc, tpath, affine, rgbFace): def arrow(tailpoint=None, headpoint=None, **kwds): """ - Returns either a 2-dimensional or 3-dimensional arrow depending + Return either a 2-dimensional or 3-dimensional arrow depending on value of points. For information regarding additional arguments, see either arrow2d? @@ -482,7 +482,6 @@ def arrow(tailpoint=None, headpoint=None, **kwds): sage: arrow((0,0), (0,0), linestyle='dashed') Graphics object consisting of 1 graphics primitive - """ try: return arrow2d(tailpoint, headpoint, **kwds) @@ -514,9 +513,9 @@ def arrow2d(tailpoint=None, headpoint=None, path=None, **options): or both (2) of the path (using 0 will swap headpoint and tailpoint). This is ignored in 3D plotting. - - ``linestyle`` -- (default: ``'solid'``) The style of the line, which is + - ``linestyle`` -- (default: ``'solid'``) the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, - or ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively. + or ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively - ``width`` -- (default: 2) the width of the arrow shaft, in points @@ -535,7 +534,7 @@ def arrow2d(tailpoint=None, headpoint=None, path=None, **options): - ``legend_color`` -- the color for the legend label - ``zorder`` -- the layer level to draw the arrow-- note that this is - ignored in 3D plotting. + ignored in 3D plotting EXAMPLES: @@ -649,7 +648,7 @@ def arrow2d(tailpoint=None, headpoint=None, path=None, **options): Verify that :issue:`36153` is fixed:: - sage: A = arrow2d((-1,-1), (2,3), legend_label="test") + sage: A = arrow2d((-1,-1), (2,3), legend_label='test') """ from sage.plot.all import Graphics g = Graphics() diff --git a/src/sage/plot/bar_chart.py b/src/sage/plot/bar_chart.py index 34ed242af4c..f03ea65ab12 100644 --- a/src/sage/plot/bar_chart.py +++ b/src/sage/plot/bar_chart.py @@ -54,7 +54,7 @@ def __init__(self, ind, datalist, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: diff --git a/src/sage/plot/bezier_path.py b/src/sage/plot/bezier_path.py index abd171bbdb6..1b81c6fe6d5 100644 --- a/src/sage/plot/bezier_path.py +++ b/src/sage/plot/bezier_path.py @@ -38,18 +38,17 @@ class BezierPath(GraphicPrimitive_xydata): We use :func:`bezier_path` to actually plot Bezier curves:: - sage: bezier_path([[(0,0),(.5,.5),(1,0)],[(.5,1),(0,0)]], linestyle="dashed") + sage: bezier_path([[(0,0),(.5,.5),(1,0)],[(.5,1),(0,0)]], linestyle='dashed') Graphics object consisting of 1 graphics primitive .. PLOT:: - P = bezier_path([[(0,0),(.5,.5),(1,0)],[(.5,1),(0,0)]], linestyle="dashed") + P = bezier_path([[(0,0),(.5,.5),(1,0)],[(.5,1),(0,0)]], linestyle='dashed') sphinx_plot(P) - """ def __init__(self, path, options): """ - Returns a graphics primitive of a path of Bezier curves. + Return a graphics primitive of a path of Bezier curves. EXAMPLES:: @@ -97,7 +96,7 @@ def __init__(self, path, options): def _allowed_options(self): """ - Returns a dict of allowed options for ``bezier_path``. + Return a dict of allowed options for ``bezier_path``. EXAMPLES:: @@ -111,7 +110,6 @@ def _allowed_options(self): ('rgbcolor', 'The color as an RGB tuple.'), ('thickness', 'How thick the border of the polygon is.'), ('zorder', 'The layer level in which to draw')] - """ return {'alpha': 'How transparent the line is.', 'fill': 'Whether or not to fill the polygon.', @@ -124,7 +122,7 @@ def _allowed_options(self): def _plot3d_options(self, options=None): """ - Updates ``BezierPath`` options to those allowed by 3D implementation. + Update ``BezierPath`` options to those allowed by 3D implementation. EXAMPLES:: @@ -158,9 +156,9 @@ def _plot3d_options(self, options=None): def plot3d(self, z=0, **kwds): """ - Returns a 3D plot (Jmol) of the Bezier path. Since a ``BezierPath`` + Return a 3D plot (Jmol) of the Bezier path. Since a ``BezierPath`` primitive contains only `x,y` coordinates, the path will be drawn in - some plane (default is `z=0`). To create a Bezier path with nonzero + some plane (default: `z=0`). To create a Bezier path with nonzero (and nonidentical) `z` coordinates in the path and control points, use the function :func:`~sage.plot.plot3d.shapes2.bezier3d` instead of :func:`bezier_path`. @@ -188,7 +186,6 @@ def plot3d(self, z=0, **kwds): .. PLOT:: sphinx_plot(bezier3d([[(0,0,0),(1,0,0),(0,1,0),(0,1,1)]])) - """ from sage.plot.plot3d.shapes2 import bezier3d options = self._plot3d_options() @@ -255,7 +252,7 @@ def _render_on_subplot(self, subplot): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -276,7 +273,7 @@ def get_minmax_data(self): @options(alpha=1, fill=False, thickness=1, rgbcolor=(0,0,0), zorder=2, linestyle='solid') def bezier_path(path, **options): """ - Returns a Graphics object of a Bezier path corresponding to the + Return a Graphics object of a Bezier path corresponding to the path parameter. The path is a list of curves, and each curve is a list of points. Each point is a tuple ``(x,y)``. @@ -312,11 +309,11 @@ def bezier_path(path, **options): p5 = (0,4) path = [[p1, c1, c2, p2], [c3, c4, p3], [c5, p4], [p5]] P = bezier_path(path) - P += line([p1,c1], color="red", linestyle="dashed") - P += line([p2,c2], color="red", linestyle="dashed") - P += line([p2,c3], color="red", linestyle="dashed") - P += line([p3,c4], color="red", linestyle="dashed") - P += line([p3,c5], color="red", linestyle="dashed") + P += line([p1,c1], color='red', linestyle='dashed') + P += line([p2,c2], color='red', linestyle='dashed') + P += line([p2,c3], color='red', linestyle='dashed') + P += line([p3,c4], color='red', linestyle='dashed') + P += line([p3,c5], color='red', linestyle='dashed') P += text("c1", c1, horizontal_alignment='left') P += text("c2", c2, horizontal_alignment='right') P += text("c3", c3, horizontal_alignment='left', vertical_alignment='bottom') @@ -339,14 +336,14 @@ def bezier_path(path, **options): INPUT: - - ``path`` -- a list of lists of tuples (see above) - - ``alpha`` -- default: 1 - - ``fill`` -- default: ``False`` - - ``thickness`` -- default: 1 - - ``linestyle`` -- default: ``'solid'``, The style of the line, which is one - of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, or ``'--'``, - ``':'``, ``'-'``, ``'-.'``, respectively. - - ``rgbcolor`` -- default: (0,0,0) + - ``path`` -- list of lists of tuples (see above) + - ``alpha`` -- (default: 1) + - ``fill`` -- (default: ``False``) + - ``thickness`` -- (default: 1) + - ``linestyle`` -- (default: ``'solid'``) the style of the line, which is one + of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, or ``'--'``, + ``':'``, ``'-'``, ``'-.'``, respectively + - ``rgbcolor`` -- (default: (0,0,0)) - ``zorder`` -- the layer in which to draw EXAMPLES:: diff --git a/src/sage/plot/circle.py b/src/sage/plot/circle.py index 3ee8d9e3e91..f9c864d602a 100644 --- a/src/sage/plot/circle.py +++ b/src/sage/plot/circle.py @@ -36,7 +36,7 @@ class Circle(GraphicPrimitive): - ``r`` -- radius of Circle object - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -59,7 +59,7 @@ class Circle(GraphicPrimitive): """ def __init__(self, x, y, r, options): """ - Initializes base class Circle. + Initialize base class Circle. EXAMPLES:: @@ -172,8 +172,7 @@ def plot3d(self, z=0, **kwds): INPUT: - - - ``z`` -- optional 3D height above `xy`-plane. + - ``z`` -- (optional) 3D height above `xy`-plane EXAMPLES:: @@ -240,23 +239,23 @@ def circle(center, radius, **options): OPTIONS: - - ``alpha`` -- default: 1 + - ``alpha`` -- (default: 1) - - ``fill`` -- default: ``False`` + - ``fill`` -- (default: ``False``) - - ``thickness`` -- default: 1 + - ``thickness`` -- (default: 1) - - ``linestyle`` -- default: ``'solid'`` (2D plotting only) The style of the + - ``linestyle`` -- (default: ``'solid'``) (2D plotting only) the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, - or ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively. + or ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively - - ``edgecolor`` -- default: 'blue' (2D plotting only) + - ``edgecolor`` -- (default: ``'blue'``) 2D plotting only - - ``facecolor`` -- default: 'blue' (2D plotting only, useful only - if ``fill=True``) + - ``facecolor`` -- (default: ``'blue'``) 2D plotting only, useful only + if ``fill=True`` - ``rgbcolor`` -- 2D or 3D plotting. This option overrides - ``edgecolor`` and ``facecolor`` for 2D plotting. + ``edgecolor`` and ``facecolor`` for 2D plotting - ``legend_label`` -- the label for this item in the legend @@ -409,7 +408,7 @@ def circle(center, radius, **options): Verify that :issue:`36153` does not arise:: - sage: C = circle((1,1), 1, legend_label="test") + sage: C = circle((1,1), 1, legend_label='test') """ from sage.plot.all import Graphics diff --git a/src/sage/plot/colors.py b/src/sage/plot/colors.py index 8d95d2725fb..a9792c2e374 100644 --- a/src/sage/plot/colors.py +++ b/src/sage/plot/colors.py @@ -202,9 +202,7 @@ def mod_one(x): - ``x`` -- an instance of Integer, int, RealNumber, etc.; the number to reduce - OUTPUT: - - - a float + OUTPUT: float EXAMPLES:: @@ -232,11 +230,9 @@ def html_to_float(c): INPUT: - - ``c`` -- a string; a valid HTML hex color + - ``c`` -- string; a valid HTML hex color - OUTPUT: - - - a RGB 3-tuple of floats in the interval [0.0, 1.0] + OUTPUT: a RGB 3-tuple of floats in the interval [0.0, 1.0] EXAMPLES:: @@ -271,13 +267,11 @@ def rgbcolor(c, space='rgb'): - ``c`` -- a :class:`Color` instance, string (name or HTML hex), 3-tuple, or 3-list; the color to convert - - ``space`` -- a string (default: 'rgb'); the color space - coordinate system (other choices are 'hsl', 'hls', and 'hsv') in - which to interpret a 3-tuple or 3-list - - OUTPUT: + - ``space`` -- string (default: ``'rgb'``); the color space + coordinate system (other choices are ``'hsl'``, ``'hls'``, and ``'hsv'``) + in which to interpret a 3-tuple or 3-list - - a RGB 3-tuple of floats in the interval [0.0, 1.0] + OUTPUT: a RGB 3-tuple of floats in the interval [0.0, 1.0] EXAMPLES:: @@ -370,17 +364,17 @@ def __init__(self, r='#0000ff', g=None, b=None, space='rgb'): transformations, of this space. Coordinates in all of these spaces are floating point values in the interval [0.0, 1.0]. - .. note:: All instantiations of :class:`Color` are converted + .. NOTE:: All instantiations of :class:`Color` are converted to an internal RGB floating point 3-tuple. This is likely to degrade precision. INPUT: - - ``r,g,b`` -- either a triple of floats between 0 and 1, - OR ``r`` - a color name string or HTML color hex string + - ``r``, ``g``, ``b`` -- either a triple of floats between 0 and 1, + OR ``r`` - a color name string or HTML color hex string - - ``space`` -- a string (default: 'rgb'); the coordinate system - (other choices are 'hsl', 'hls', and 'hsv') in which to + - ``space`` -- string (default: ``'rgb'``); the coordinate system + (other choices are ``'hsl'``, ``'hls'``, and ``'hsv'``) in which to interpret a triple of floats EXAMPLES:: @@ -410,9 +404,7 @@ def __repr__(self): """ Return a string representation of this color. - OUTPUT: - - - a string + OUTPUT: string EXAMPLES:: @@ -433,9 +425,7 @@ def __lt__(self, right): - ``right`` -- an object - OUTPUT: - - - boolean -- False + OUTPUT: boolean; ``False`` EXAMPLES:: @@ -459,9 +449,7 @@ def __le__(self, right): - ``right`` -- an object - OUTPUT: - - - boolean -- False + OUTPUT: boolean; ``False`` EXAMPLES:: @@ -483,9 +471,8 @@ def __eq__(self, right): - ``right`` -- a :class:`Color` instance - OUTPUT: - - - boolean -- True if the two colors are the same, False if different + OUTPUT: boolean; ``True`` if the two colors are the same, ``False`` + if different EXAMPLES:: @@ -513,8 +500,8 @@ def __ne__(self, right): OUTPUT: - - boolean -- True if the two colors are different, - False if they're the same + boolean; ``True`` if the two colors are different, ``False`` if they're + the same. EXAMPLES:: @@ -539,9 +526,7 @@ def __gt__(self, right): - ``right`` -- an object - OUTPUT: - - - boolean -- False + OUTPUT: boolean; ``False`` EXAMPLES:: @@ -565,9 +550,7 @@ def __ge__(self, right): - ``right`` -- an object - OUTPUT: - - - boolean -- False + OUTPUT: boolean; ``False`` EXAMPLES:: @@ -585,9 +568,7 @@ def __hash__(self): Return the hash value of a color. Equal colors return equal hash values. - OUTPUT: - - - a hash value + OUTPUT: a hash value EXAMPLES:: @@ -612,9 +593,7 @@ def blend(self, color, fraction=0.5): - ``fraction`` -- a float-convertible number; the fraction of ``color`` to blend with this color - OUTPUT: - - - a **new** :class:`Color` instance + OUTPUT: a **new** :class:`Color` instance EXAMPLES:: @@ -657,9 +636,7 @@ def __add__(self, right): - ``right`` -- a :class:`Color` instance or float-convertible 3-tuple/list - OUTPUT: - - - a **new** :class:`Color` instance + OUTPUT: a **new** :class:`Color` instance EXAMPLES:: @@ -693,9 +670,7 @@ def __radd__(self, left): - ``left`` -- a :class:`Color` instance or float-convertible 3-tuple/list - OUTPUT: - - - a **new** :class:`Color` instance + OUTPUT: a **new** :class:`Color` instance EXAMPLES:: @@ -723,9 +698,7 @@ def __mul__(self, right): - ``right`` -- a float-convertible number - OUTPUT: - - - a **new** :class:`Color` instance + OUTPUT: a **new** :class:`Color` instance EXAMPLES:: @@ -751,9 +724,7 @@ def __rmul__(self, left): - ``left`` -- a float-convertible number - OUTPUT: - - - a **new** :class:`Color` instance + OUTPUT: a **new** :class:`Color` instance EXAMPLES:: @@ -772,11 +743,9 @@ def __truediv__(self, right): INPUT: - - ``right`` -- a float-convertible, non-zero number - - OUTPUT: + - ``right`` -- a float-convertible, nonzero number - - a **new** instance of :class:`Color` + OUTPUT: a **new** instance of :class:`Color` EXAMPLES:: @@ -812,9 +781,9 @@ def __int__(self): OUTPUT: - - the integer `256^2 r_int + 256 g_int + b_int`, where `r_int`, `g_int`, and `b_int` - are obtained from `r`, `g`, and `b` by converting from the real interval [0.0, 1.0] - to the integer range 0, 1, ..., 255. + The integer 256^2 r_int + 256 g_int + b_int, where r_int, g_int, + and b_int are obtained from r, g, and b by converting from the + real interval [0.0, 1.0] to the integer range 0, 1, ..., 255. EXAMPLES:: @@ -828,9 +797,7 @@ def __iter__(self): """ Return an iterator over the RGB coordinates of this color. - OUTPUT: - - - a tupleiterator + OUTPUT: a tupleiterator EXAMPLES:: @@ -854,11 +821,9 @@ def __getitem__(self, i): INPUT: - - ``i`` -- an integer; the 0-based coordinate to retrieve + - ``i`` -- integer; the 0-based coordinate to retrieve - OUTPUT: - - - a float + OUTPUT: float EXAMPLES:: @@ -881,9 +846,7 @@ def rgb(self): Return the underlying Red-Green-Blue (RGB) coordinates of this color. - OUTPUT: - - - a 3-tuple of floats + OUTPUT: a 3-tuple of floats EXAMPLES:: @@ -906,9 +869,7 @@ def hls(self): Return the Hue-Lightness-Saturation (HLS) coordinates of this color. - OUTPUT: - - - a 3-tuple of floats + OUTPUT: a 3-tuple of floats EXAMPLES:: @@ -929,9 +890,7 @@ def hsl(self): Return the Hue-Saturation-Lightness (HSL) coordinates of this color. - OUTPUT: - - - a 3-tuple of floats + OUTPUT: a 3-tuple of floats EXAMPLES:: @@ -951,9 +910,7 @@ def hsv(self): Return the Hue-Saturation-Value (HSV) coordinates of this color. - OUTPUT: - - - a 3-tuple of floats + OUTPUT: a 3-tuple of floats EXAMPLES:: @@ -971,9 +928,7 @@ def html_color(self): """ Return a HTML hex representation for this color. - OUTPUT: - - - a string of length 7. + OUTPUT: string of length 7 EXAMPLES:: @@ -1000,9 +955,7 @@ def lighter(self, fraction=1/3): - ``fraction`` -- a float (default: 1/3); blending fraction to apply - OUTPUT: - - - a **new** instance of :class:`Color` + OUTPUT: a **new** instance of :class:`Color` EXAMPLES:: @@ -1028,9 +981,7 @@ def darker(self, fraction=1/3): - ``fraction`` -- a float (default: 1/3); blending fraction to apply - OUTPUT: - - - a new instance of :class:`Color` + OUTPUT: a new instance of :class:`Color` EXAMPLES:: @@ -1055,7 +1006,7 @@ class ColorsDict(dict): """ def __init__(self): """ - Constructs a dict-like collection of colors. The keys are the + Construct a dict-like collection of colors. The keys are the color names (i.e., strings) and the values are RGB 3-tuples of floats. @@ -1076,15 +1027,13 @@ def __init__(self): def __getattr__(self, name): """ - Gets a color via attribute access. + Get a color via attribute access. INPUT: - - ``name`` -- a string; the name of the color to return + - ``name`` -- string; the name of the color to return - OUTPUT: - - - a RGB 3-tuple of floats + OUTPUT: a RGB 3-tuple of floats EXAMPLES:: @@ -1108,12 +1057,10 @@ def __getattr__(self, name): def __dir__(self): """ - Returns an approximate list of attribute names, including the + Return an approximate list of attribute names, including the color names. - OUTPUT: - - - a list of strings + OUTPUT: list of strings EXAMPLES:: @@ -1161,9 +1108,7 @@ def hue(h, s=1, v=1): - ``v`` -- a number (default: 1); the color's value - OUTPUT: - - - a RGB 3-tuple of floats in the interval [0.0, 1.0] + OUTPUT: a RGB 3-tuple of floats in the interval [0.0, 1.0] EXAMPLES:: @@ -1204,9 +1149,7 @@ def float_to_html(r, g, b): - ``b`` -- a real number; the RGB color's "blue" intensity - OUTPUT: - - - a string of length 7, starting with '#' + OUTPUT: string of length 7, starting with ``'#'`` EXAMPLES:: @@ -1245,9 +1188,9 @@ def float_to_integer(r, g, b): OUTPUT: - - the integer `256^2 r_int + 256 g_int + b_int`, where `r_int`, `g_int`, and `b_int` - are obtained from `r`, `g`, and `b` by converting from the real interval [0.0, 1.0] - to the integer range 0, 1, ..., 255. + The integer 256^2 r_int + 256 g_int + b_int, where r_int, g_int, and + b_int are obtained from r, g, and b by converting from the real + interval [0.0, 1.0] to the integer range 0, 1, ..., 255. EXAMPLES:: @@ -1272,7 +1215,7 @@ def float_to_integer(r, g, b): def rainbow(n, format='hex'): """ - Returns a list of colors sampled at equal intervals over the + Return a list of colors sampled at equal intervals over the spectrum, from Hue-Saturation-Value (HSV) coordinates (0, 1, 1) to (1, 1, 1). This range is red at the extremes, but it covers orange, yellow, green, cyan, blue, violet, and many other hues in @@ -1283,13 +1226,11 @@ def rainbow(n, format='hex'): - ``n`` -- a number; the length of the list - - ``format`` -- a string (default: 'hex'); the output format for - each color in the list; the other choice is 'rgbtuple' - - OUTPUT: + - ``format`` -- string (default: ``'hex'``); the output format for + each color in the list. The other choice is ``'rgbtuple'``. - - a list of strings or RGB 3-tuples of floats in the interval - [0.0, 1.0] + OUTPUT: a list of strings or RGB 3-tuples of floats in the interval + [0.0, 1.0] EXAMPLES:: @@ -1321,7 +1262,7 @@ def rainbow(n, format='hex'): # about cmap where it is used and to test these classes. def get_cmap(cmap): r""" - Returns a color map (actually, a matplotlib :class:`Colormap` + Return a color map (actually, a matplotlib :class:`Colormap` object), given its name or a [mixed] list/tuple of RGB list/tuples and color names. For a list of map names, evaluate:: @@ -1332,13 +1273,10 @@ def get_cmap(cmap): INPUT: - - ``cmap`` -- a string, list, tuple, or - :class:`matplotlib.colors.Colormap`; a string must be a valid - color map name - - OUTPUT: + - ``cmap`` -- string, list, tuple, or :class:`matplotlib.colors.Colormap`; + a string must be a valid color map name - - a :class:`matplotlib.colors.Colormap` instance + OUTPUT: a :class:`matplotlib.colors.Colormap` instance EXAMPLES:: @@ -1428,7 +1366,7 @@ class Colormaps(MutableMapping): """ def __init__(self): """ - Constructs an empty mutable collection of color maps. + Construct an empty mutable collection of color maps. EXAMPLES:: @@ -1462,12 +1400,10 @@ def load_maps(self): def __dir__(self): """ - Returns an approximate list of attribute names, including the + Return an approximate list of attribute names, including the color map names. - OUTPUT: - - - a list of strings + OUTPUT: list of strings EXAMPLES:: @@ -1484,11 +1420,9 @@ def __dir__(self): def __len__(self): """ - Returns the number of color maps. + Return the number of color maps. - OUTPUT: - - - an int + OUTPUT: integer EXAMPLES:: @@ -1502,11 +1436,9 @@ def __len__(self): def __iter__(self): """ - Returns an iterator over the color map collection. + Return an iterator over the color map collection. - OUTPUT: - - - a dictionary key iterator instance + OUTPUT: a dictionary key iterator instance EXAMPLES:: @@ -1522,15 +1454,13 @@ def __iter__(self): def __contains__(self, name): """ - Returns whether a map is in the color maps collection. + Return whether a map is in the color maps collection. INPUT: - - ``name`` -- a string; the name of the map to query - - OUTPUT: + - ``name`` -- string; the name of the map to query - - a boolean + OUTPUT: boolean EXAMPLES:: @@ -1546,15 +1476,13 @@ def __contains__(self, name): def __getitem__(self, name): """ - Gets a color map from the collection via key access. + Get a color map from the collection via key access. INPUT: - - ``name`` -- a string; the name of the map return - - OUTPUT: + - ``name`` -- string; the name of the map return - - an instance of :class:`matplotlib.colors.Colormap` + OUTPUT: an instance of :class:`matplotlib.colors.Colormap` EXAMPLES:: @@ -1578,15 +1506,13 @@ def __getitem__(self, name): def __getattr__(self, name): """ - Gets a color map from the collection via attribute access. + Get a color map from the collection via attribute access. INPUT: - - ``name`` -- a string; the name of the map to return + - ``name`` -- string; the name of the map to return - OUTPUT: - - - an instance of :class:`matplotlib.colors.Colormap` + OUTPUT: an instance of :class:`matplotlib.colors.Colormap` EXAMPLES:: @@ -1612,11 +1538,9 @@ def __getattr__(self, name): def __repr__(self): """ - Returns a string representation of the color map collection. - - OUTPUT: + Return a string representation of the color map collection. - - a string + OUTPUT: string EXAMPLES:: @@ -1632,11 +1556,11 @@ def __repr__(self): def __setitem__(self, name, colormap): """ - Adds a color map to the collection. + Add a color map to the collection. INPUT: - - ``name`` -- a string; the name of the map to add + - ``name`` -- string; the name of the map to add - ``colormap`` -- an instance of :class:`matplotlib.colors.Colormap`; the color map to add @@ -1662,7 +1586,7 @@ def __delitem__(self, name): INPUT: - - ``name`` -- a string; the name of the map to remove + - ``name`` -- string; the name of the map to remove EXAMPLES:: diff --git a/src/sage/plot/complex_plot.pyx b/src/sage/plot/complex_plot.pyx index 4d71414e1c2..124209f257e 100644 --- a/src/sage/plot/complex_plot.pyx +++ b/src/sage/plot/complex_plot.pyx @@ -64,7 +64,7 @@ cdef inline double mag_to_lightness(double r, double rate=0.5) noexcept: INPUT: - - ``r`` -- a non-negative real number; the magnitude + - ``r`` -- a nonnegative real number; the magnitude - ``rate`` -- a positive real number; how quickly changes in magnitude affect changes in output lightness @@ -110,7 +110,7 @@ cdef inline double cyclic_logarithmic_mag_to_lightness(double r, double base=2) INPUT: - - ``r`` -- a non-negative real number; the magnitude + - ``r`` -- a nonnegative real number; the magnitude - ``base`` -- a real number (default: `2`); contours will appear at integer powers of ``base``. This should be greater than `1`. @@ -131,7 +131,7 @@ cdef inline double cyclic_logarithmic_mag_to_lightness(double r, double base=2) sage: from sage.plot.complex_plot import complex_to_rgb sage: complex_to_rgb([[0, 1, 10]], contoured=True, # abs tol 1e-4 - ....: contour_type="logarithmic") + ....: contour_type='logarithmic') array([[[1. , 0. , 0. ], [1. , 0.15 , 0.15 ], [0.98903595, 0. , 0. ]]]) @@ -139,7 +139,7 @@ cdef inline double cyclic_logarithmic_mag_to_lightness(double r, double base=2) We set contours to be multiples of `5` apart:: sage: complex_to_rgb([[0, 1, 10]], contoured=True, # abs tol 1e-4 - ....: contour_type="logarithmic", contour_base=5) + ....: contour_type='logarithmic', contour_base=5) array([[[1. , 0. , 0. ], [1. , 0.15 , 0.15 ], [0.93466172, 0. , 0. ]]]) @@ -161,7 +161,7 @@ cdef inline double cyclic_linear_mag_to_lightness(double r, double base=10) noex INPUT: - - ``r`` -- a non-negative real number; the magnitude + - ``r`` -- a nonnegative real number; the magnitude - ``base`` -- a positive real number (default: `10`); contours will appear at integer multiples of ``base`` @@ -182,7 +182,7 @@ cdef inline double cyclic_linear_mag_to_lightness(double r, double base=10) noex sage: from sage.plot.complex_plot import complex_to_rgb sage: complex_to_rgb([[1, 5, 11]], contoured=True, # abs tol 1e-4 - ....: contour_type="linear") + ....: contour_type='linear') array([[[1. , 0.1, 0.1], [0.9, 0. , 0. ], [1. , 0.1, 0.1]]]) @@ -193,7 +193,7 @@ cdef inline double cyclic_linear_mag_to_lightness(double r, double base=10) noex same, but the values for `5` and `11` should be:: sage: complex_to_rgb([[1, 5, 11]], contoured=True, # abs tol 1e-4 - ....: contour_type="linear", contour_base=3) + ....: contour_type='linear', contour_base=3) array([[[0.98333333, 0. , 0. ], [0.81666667, 0. , 0. ], [0.81666667, 0. , 0. ]]]) @@ -217,15 +217,15 @@ cdef inline double mag_and_arg_to_lightness(double r, double arg, INPUT: - - ``r`` -- a non-negative real number + - ``r`` -- a nonnegative real number - ``arg`` -- a real number - ``base`` -- a positive real number (default: ``2``); contours will appear at integer powers of ``base``. This should be greater than `1`. - - ``nphases`` -- a positive integer (default: ``10``); how many phase - contours to represent a change of argument by `2 \pi`. + - ``nphases`` -- positive integer (default: `10`); how many phase + contours to represent a change of argument by `2 \pi` OUTPUT: @@ -285,28 +285,28 @@ def complex_to_rgb(z_values, contoured=False, tiled=False, INPUT: - - ``z_values`` -- A grid of complex numbers, as a list of lists + - ``z_values`` -- a grid of complex numbers, as a list of lists - ``contoured`` -- boolean (default: ``False``); causes magnitude to be - indicated through contour-like adjustments to lightness. + indicated through contour-like adjustments to lightness - ``tiled`` -- boolean (default: ``False``); causes magnitude and argument to - be indicated through contour-like adjustments to lightness. + be indicated through contour-like adjustments to lightness - - ``nphases`` -- a positive integer (default: `10`); when ``tiled=True``, - this is the number of divisions the phase is divided into. + - ``nphases`` -- positive integer (default: 10); when ``tiled=True``, + this is the number of divisions the phase is divided into - ``contour_type`` -- either ``'logarithmic'``, or ``'linear'`` (default: ``'logarithmic'``); causes added contours to be of given type when ``contoured=True``. - - ``contour_base`` -- a positive integer; when ``contour_type`` is + - ``contour_base`` -- positive integer; when ``contour_type`` is ``'logarithmic'``, this sets logarithmic contours at multiples of ``contour_base`` apart. When ``contour_type`` is ``'linear'``, this sets contours at distances of ``contour_base`` apart. If ``None``, then a default is chosen depending on ``contour_type``. - - ``dark_rate`` -- a positive number (default: `0.5`); affects how quickly + - ``dark_rate`` -- a positive number (default: 0.5); affects how quickly magnitudes affect how light/dark the image is. When there are contours, this affects how visible each contour is. Large values (near `1.0`) have very strong, immediate effects, while small values (near `0.0`) have @@ -346,12 +346,12 @@ def complex_to_rgb(z_values, contoured=False, tiled=False, We can change contour types and the distances between contours:: sage: complex_to_rgb([[0, 1 + 1j, 3 + 4j]], # abs tol 1e-4 - ....: contoured=True, contour_type="logarithmic", contour_base=3) + ....: contoured=True, contour_type='logarithmic', contour_base=3) array([[[1. , 0. , 0. ], [0.99226756, 0.74420067, 0. ], [0.91751324, 0.81245954, 0. ]]]) sage: complex_to_rgb([[0, 1 + 1j, 3 + 4j]], # abs tol 1e-4 - ....: contoured=True, contour_type="linear", contour_base=3) + ....: contoured=True, contour_type='linear', contour_base=3) array([[[1. , 0.15 , 0.15 ], [0.91429774, 0.6857233 , 0. ], [0.81666667, 0.72315973, 0. ]]]) @@ -475,34 +475,34 @@ def complex_to_cmap_rgb(z_values, cmap='turbo', contoured=False, tiled=False, INPUT: - - ``z_values`` -- A grid of complex numbers, as a list of lists + - ``z_values`` -- a grid of complex numbers, as a list of lists - - ``cmap`` -- the string name of a matplotlib colormap, or an instance - of a matplotlib Colormap (default: ``'turbo'``). + - ``cmap`` -- the string name of a matplotlib colormap, or an instance + of a matplotlib Colormap (default: ``'turbo'``) - ``contoured`` -- boolean (default: ``False``); causes magnitude to be - indicated through contour-like adjustments to lightness. + indicated through contour-like adjustments to lightness - ``tiled`` -- boolean (default: ``False``); causes magnitude and argument to - be indicated through contour-like adjustments to lightness. + be indicated through contour-like adjustments to lightness - - ``nphases`` -- a positive integer (default: `10`); when ``tiled=True``, - this is the number of divisions the phase is divided into. + - ``nphases`` -- positive integer (default: 10); when ``tiled=True``, + this is the number of divisions the phase is divided into - ``contour_type`` -- either ``'logarithmic'``, or ``'linear'`` (default: ``'logarithmic'``); causes added contours to be of given type when ``contoured=True``. - - ``contour_base`` -- a positive integer; when ``contour_type`` is + - ``contour_base`` -- positive integer; when ``contour_type`` is ``'logarithmic'``, this sets logarithmic contours at multiples of ``contour_base`` apart. When ``contour_type`` is ``'linear'``, this sets contours at distances of ``contour_base`` apart. If ``None``, then a default is chosen depending on ``contour_type``. - - ``dark_rate`` -- a positive number (default: `0.5`); affects how quickly + - ``dark_rate`` -- a positive number (default: 0.5); affects how quickly magnitudes affect how light/dark the image is. When there are contours, - this affects how visible each contour is. Large values (near `1.0`) have - very strong, immediate effects, while small values (near `0.0`) have + this affects how visible each contour is. Large values (near 1.0) have + very strong, immediate effects, while small values (near 0.0) have gradual effects. OUTPUT: @@ -532,12 +532,12 @@ def complex_to_cmap_rgb(z_values, cmap='turbo', contoured=False, tiled=False, We can change contour types and the distances between contours:: sage: complex_to_cmap_rgb([[0, 1 + 1j, 3 + 4j]], contoured=True, # abs tol 1e-4 - ....: contour_type="logarithmic", contour_base=3) + ....: contour_type='logarithmic', contour_base=3) array([[[0.64362 , 0.98999 , 0.23356 ], [0.93239357, 0.81063338, 0.21955399], [0.95647342, 0.74861225, 0.14963982]]]) sage: complex_to_cmap_rgb([[0, 1 + 1j, 3 + 4j]], cmap='turbo', # abs tol 1e-4 - ....: contoured=True, contour_type="linear", contour_base=3) + ....: contoured=True, contour_type='linear', contour_base=3) array([[[0.71246796, 0.9919238 , 0.3816262 ], [0.92617785, 0.79322304, 0.14779989], [0.95156284, 0.72025117, 0.05370383]]]) @@ -649,7 +649,7 @@ def add_lightness_smoothing_to_rgb(rgb, delta): INPUT: - ``rgb`` -- a grid of length 3 tuples `(r, g, b)`, as an - `N \times M \times 3` numpy array. + `N \times M \times 3` numpy array - ``delta`` -- a grid of values as an `N \times M` numpy array; these represent how much to change the lightness of each `(r, g, b)`. Values @@ -702,14 +702,14 @@ def add_contours_to_rgb(rgb, delta, dark_rate=0.5): INPUT: - ``rgb`` -- a grid of length 3 tuples `(r, g, b)`, as an `N \times M - \times 3` numpy array. + \times 3` numpy array - ``delta`` -- a grid of values as an `N \times M` numpy array; these represent how much to change the lightness of each `(r, g, b)`. Values should be in `[-1, 1]`. - - ``dark_rate`` -- a positive number (default: `0.5`); affects how - strongly visible the contours appear. + - ``dark_rate`` -- a positive number (default: 0.5); affects how + strongly visible the contours appear OUTPUT: @@ -731,7 +731,6 @@ def add_contours_to_rgb(rgb, delta, dark_rate=0.5): Finally map `(h, l', s) \mapsto (r, g, b)` using the standard HLS-to-RGB formula. - EXAMPLES:: sage: # needs numpy @@ -771,11 +770,11 @@ class ComplexPlot(GraphicPrimitive): INPUT: - - ``rgb_data`` -- An array of colored points to be plotted. + - ``rgb_data`` -- an array of colored points to be plotted - - ``x_range`` -- A minimum and maximum x value for the plot. + - ``x_range`` -- a minimum and maximum x value for the plot - - ``y_range`` -- A minimum and maximum y value for the plot. + - ``y_range`` -- a minimum and maximum y value for the plot TESTS:: @@ -868,9 +867,9 @@ def complex_plot(f, x_range, y_range, contoured=False, tiled=False, cmap=None, - ``(ymin, ymax)`` -- 2-tuple, the range of ``y`` values - - ``cmap`` -- ``None``, or the string name of a matplotlib colormap, or an + - ``cmap`` -- ``None``, or the string name of a matplotlib colormap, or an instance of a matplotlib Colormap, or the special string ``'matplotlib'`` - (default: ``None``); If ``None``, then hues are chosen from a standard + (default: ``None``); if ``None``, then hues are chosen from a standard color wheel, cycling from red to yellow to blue. If ``matplotlib``, then hues are chosen from a preset matplotlib colormap. @@ -882,10 +881,10 @@ def complex_plot(f, x_range, y_range, contoured=False, tiled=False, cmap=None, magnitude along one contour is either twice or half the magnitude along adjacent contours. - - ``dark_rate`` -- a positive number (default: `0.5`); affects how quickly + - ``dark_rate`` -- a positive number (default: 0.5); affects how quickly magnitudes affect how light/dark the image is. When there are contours, - this affects how visible each contour is. Large values (near `1.0`) have - very strong, immediate effects, while small values (near `0.0`) have + this affects how visible each contour is. Large values (near 1.0) have + very strong, immediate effects, while small values (near 0.0) have gradual effects. - ``tiled`` -- boolean (default: ``False``); causes the magnitude to @@ -893,14 +892,14 @@ def complex_plot(f, x_range, y_range, contoured=False, tiled=False, cmap=None, ``contoured``, and in addition for there to be `10` evenly spaced phase contours. - - ``nphases`` -- a positive integer (default: `10`); when ``tiled=True``, - this is the number of divisions the phase is divided into. + - ``nphases`` -- positive integer (default: 10); when ``tiled=True``, + this is the number of divisions the phase is divided into - ``contour_type`` -- either ``'logarithmic'``, or ``'linear'`` (default: ``'logarithmic'``); causes added contours to be of given type when ``contoured=True``. - - ``contour_base`` -- a positive integer; when ``contour_type`` is + - ``contour_base`` -- positive integer; when ``contour_type`` is ``'logarithmic'``, this sets logarithmic contours at multiples of ``contour_base`` apart. When ``contour_type`` is ``'linear'``, this sets contours at distances of ``contour_base`` apart. If ``None``, then a @@ -908,7 +907,7 @@ def complex_plot(f, x_range, y_range, contoured=False, tiled=False, cmap=None, The following inputs may also be passed in as named parameters: - - ``plot_points`` -- integer (default: ``100``); number of points to + - ``plot_points`` -- integer (default: 100); number of points to plot in each direction of the grid - ``interpolation`` -- string (default: ``'catrom'``); the interpolation @@ -929,7 +928,6 @@ def complex_plot(f, x_range, y_range, contoured=False, tiled=False, cmap=None, See [NAR2018]_ for more information about colormap choice for scientific visualization. - EXAMPLES: Here we plot a couple of simple functions:: @@ -1237,7 +1235,7 @@ def rgb_to_hls(rgb): INPUT: - - ``rgb`` -- an `N \times 3` array of floats with values + - ``rgb`` -- an `N \times 3` array of floats with values in the range `[0, 1]`; the rgb values at each point. (Note that the input can actually be of any dimension, such as `N \times M \times 3`, as long as the last dimension has length `3`). @@ -1405,13 +1403,13 @@ def _v(m1, m2, hue): INPUT: - - ``m1`` -- An array of floats with values in the range `[0, 1]`. + - ``m1`` -- an array of floats with values in the range `[0, 1]` - - ``m2`` -- An array of floats with values in the range `[0, 1]` with - the same dimensions as ``m1``. + - ``m2`` -- an array of floats with values in the range `[0, 1]` with + the same dimensions as ``m1`` - - ``hue`` -- An array of floats with values in the range `[0, 1]` with - the same dimensions as ``m1``. + - ``hue`` -- an array of floats with values in the range `[0, 1]` with + the same dimensions as ``m1`` OUTPUT: diff --git a/src/sage/plot/contour_plot.py b/src/sage/plot/contour_plot.py index 2d94deaa6ff..6b526b1c7c4 100644 --- a/src/sage/plot/contour_plot.py +++ b/src/sage/plot/contour_plot.py @@ -40,7 +40,7 @@ class ContourPlot(GraphicPrimitive): - ``yrange`` -- tuple of 2 floats indicating range for vertical direction - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -250,11 +250,11 @@ def contour_plot(f, xrange, yrange, **options): The following inputs must all be passed in as named parameters: - - ``plot_points`` -- integer (default: 100); number of points to plot + - ``plot_points`` -- integer (default: 100); number of points to plot in each direction of the grid. For old computers, 25 is fine, but should not be used to verify specific intersection points. - - ``fill`` -- bool (default: ``True``), whether to color in the area + - ``fill`` -- boolean (default: ``True``); whether to color in the area between contour lines - ``cmap`` -- a colormap (default: ``'gray'``), the name of @@ -269,25 +269,25 @@ def contour_plot(f, xrange, yrange, **options): is passed (or the option is not given), then the number of contour lines is determined automatically, and is usually about 5. - - ``linewidths`` -- integer or list of integer (default: None), if + - ``linewidths`` -- integer or list of integer (default: ``None``), if a single integer all levels will be of the width given, otherwise the levels will be plotted with the width in the order given. If the list is shorter than the number of contours, then the widths will be repeated cyclically. - - ``linestyles`` -- string or list of strings (default: None), the - style of the lines to be plotted, one of: ``"solid"``, ``"dashed"``, - ``"dashdot"``, ``"dotted"``, respectively ``"-"``, ``"--"``, - ``"-."``, ``":"``. If the list is shorter than the number of + - ``linestyles`` -- string or list of strings (default: ``None``), the + style of the lines to be plotted, one of: ``'solid'``, ``'dashed'``, + ``'dashdot'``, ``'dotted'``, respectively ``'-'``, ``'--'``, + ``'-.'``, ``':'``. If the list is shorter than the number of contours, then the styles will be repeated cyclically. - - ``labels`` -- boolean (default: ``False``) Show level labels or not. + - ``labels`` -- boolean (default: ``False``); show level labels or not The following options are to adjust the style and placement of labels, they have no effect if no labels are shown. - - ``label_fontsize`` -- integer (default: 9), the font size of - the labels. + - ``label_fontsize`` -- integer (default: 9); the font size of + the labels - ``label_colors`` -- string or sequence of colors (default: None) If a string, gives the name of a single color with which @@ -299,36 +299,36 @@ def contour_plot(f, xrange, yrange, **options): otherwise True), controls whether the underlying contour is removed or not. - - ``label_inline_spacing`` -- integer (default: 3), When inline, + - ``label_inline_spacing`` -- integer (default: 3); when inline, this is the amount of contour that is removed from each side, in pixels. - - ``label_fmt`` -- a format string (default: "%1.2f"), this is + - ``label_fmt`` -- a format string (default: ``"%1.2f"``), this is used to get the label text from the level. This can also be a dictionary with the contour levels as keys and corresponding text string labels as values. It can also be any callable which returns a string when called with a numeric contour level. - - ``colorbar`` -- boolean (default: ``False``) Show a colorbar or not. + - ``colorbar`` -- boolean (default: ``False``); show a colorbar or not The following options are to adjust the style and placement of colorbars. They have no effect if a colorbar is not shown. - - ``colorbar_orientation`` -- string (default: 'vertical'), + - ``colorbar_orientation`` -- string (default: ``'vertical'``), controls placement of the colorbar, can be either 'vertical' or 'horizontal' - ``colorbar_format`` -- a format string, this is used to format - the colorbar labels. + the colorbar labels - - ``colorbar_spacing`` -- string (default: 'proportional'). If + - ``colorbar_spacing`` -- string (default: ``'proportional'``); if 'proportional', make the contour divisions proportional to values. If 'uniform', space the colorbar divisions uniformly, without regard for numeric values. - ``legend_label`` -- the label for this item in the legend - - ``region`` -- (default: None) If region is given, it must be a function + - ``region`` -- (default: ``None``) if region is given, it must be a function of two variables. Only segments of the surface where region(x,y) returns a number >0 will be included in the plot. @@ -880,7 +880,6 @@ def f(x,y): return cos(x) + sin(y) sage: x,y = SR.var('x,y', domain='real') sage: contour_plot(log(x) + log(y), (-1, 5), (-1, 5)) Graphics object consisting of 1 graphics primitive - """ from sage.plot.all import Graphics from sage.plot.misc import setup_for_eval_on_grid @@ -1058,21 +1057,21 @@ def implicit_plot(f, xrange, yrange, **options): in each direction of the grid - ``fill`` -- boolean (default: ``False``); if ``True``, fill the region - `f(x, y) < 0`. + `f(x, y) < 0` - - ``fillcolor`` -- string (default: ``'blue'``), the color of the region + - ``fillcolor`` -- string (default: ``'blue'``); the color of the region where `f(x,y) < 0` if ``fill = True``. Colors are defined in :mod:`sage.plot.colors`; try ``colors?`` to see them all. - - ``linewidth`` -- integer (default: None), if a single integer all levels + - ``linewidth`` -- integer (default: ``None``); if a single integer all levels will be of the width given, otherwise the levels will be plotted with the widths in the order given. - - ``linestyle`` -- string (default: None), the style of the line to be - plotted, one of: ``"solid"``, ``"dashed"``, ``"dashdot"`` or - ``"dotted"``, respectively ``"-"``, ``"--"``, ``"-."``, or ``":"``. + - ``linestyle`` -- string (default: ``None``); the style of the line to be + plotted, one of: ``'solid'``, ``'dashed'``, ``'dashdot'`` or + ``'dotted'``, respectively ``'-'``, ``'--'``, ``'-.'``, or ``':'``. - - ``color`` -- string (default: ``'blue'``), the color of the plot. Colors + - ``color`` -- string (default: ``'blue'``); the color of the plot. Colors are defined in :mod:`sage.plot.colors`; try ``colors?`` to see them all. If ``fill = True``, then this sets only the color of the border of the plot. See ``fillcolor`` for setting the color of the fill region. @@ -1085,17 +1084,17 @@ def implicit_plot(f, xrange, yrange, **options): ``basex`` sets the base of the logarithm along the horizontal axis and ``basey`` sets the base along the vertical axis. - - ``scale`` -- (default: ``"linear"``) string. The scale of the axes. - Possible values are ``"linear"``, ``"loglog"``, ``"semilogx"``, - ``"semilogy"``. + - ``scale`` -- (default: ``'linear'``) string. The scale of the axes. + Possible values are ``'linear'``, ``'loglog'``, ``'semilogx'``, + ``'semilogy'``. The scale can be also be given as single argument that is a list or tuple ``(scale, base)`` or ``(scale, basex, basey)``. - The ``"loglog"`` scale sets both the horizontal and vertical axes to - logarithmic scale. The ``"semilogx"`` scale sets the horizontal axis - to logarithmic scale. The ``"semilogy"`` scale sets the vertical axis - to logarithmic scale. The ``"linear"`` scale is the default value + The ``'loglog'`` scale sets both the horizontal and vertical axes to + logarithmic scale. The ``'semilogx'`` scale sets the horizontal axis + to logarithmic scale. The ``'semilogy'`` scale sets the vertical axis + to logarithmic scale. The ``'linear'`` scale is the default value when :class:`~sage.plot.graphics.Graphics` is initialized. .. WARNING:: @@ -1189,13 +1188,13 @@ def f(x,y): return x**2 + y**2 - 2 You can even change the color of the plot:: - sage: implicit_plot(x^2 + y^2 == 2, (x,-3,3), (y,-3,3), color="red") + sage: implicit_plot(x^2 + y^2 == 2, (x,-3,3), (y,-3,3), color='red') Graphics object consisting of 1 graphics primitive .. PLOT:: x, y =var("x y") - g = implicit_plot(x**2 + y**2 == 2, (x,-3,3), (y,-3,3), color="red") + g = implicit_plot(x**2 + y**2 == 2, (x,-3,3), (y,-3,3), color='red') sphinx_plot(g) The color of the fill region can be changed:: @@ -1206,7 +1205,7 @@ def f(x,y): return x**2 + y**2 - 2 .. PLOT:: x, y =var("x y") - g = implicit_plot(x**2 + y**2 == 2, (x,-3,3), (y,-3,3), fill=True, fillcolor="red") + g = implicit_plot(x**2 + y**2 == 2, (x,-3,3), (y,-3,3), fill=True, fillcolor='red') sphinx_plot(g) Here is a beautiful (and long) example which also tests that all @@ -1397,14 +1396,14 @@ def f(x,y): def region_plot(f, xrange, yrange, **options): r""" ``region_plot`` takes a boolean function of two variables, `f(x, y)` - and plots the region where f is True over the specified + and plots the region where f is ``True`` over the specified ``xrange`` and ``yrange`` as demonstrated below. ``region_plot(f, (xmin,xmax), (ymin,ymax), ...)`` INPUT: - - ``f`` -- a boolean function or a list of boolean functions of + - ``f`` -- boolean function or a list of boolean functions of two variables - ``(xmin, xmax)`` -- 2-tuple, the range of ``x`` values OR 3-tuple @@ -1413,7 +1412,7 @@ def region_plot(f, xrange, yrange, **options): - ``(ymin, ymax)`` -- 2-tuple, the range of ``y`` values OR 3-tuple ``(y,ymin,ymax)`` - - ``plot_points`` -- integer (default: 100); number of points to plot + - ``plot_points`` -- integer (default: 100); number of points to plot in each direction of the grid - ``incol`` -- a color (default: ``'blue'``), the color inside the region @@ -1429,11 +1428,11 @@ def region_plot(f, xrange, yrange, **options): (``'black'`` if ``borderwidth`` or ``borderstyle`` is specified but not ``bordercol``) - - ``borderstyle`` -- string (default: ``'solid'``), one of ``'solid'``, + - ``borderstyle`` -- string (default: ``'solid'``); one of ``'solid'``, ``'dashed'``, ``'dotted'``, ``'dashdot'``, respectively ``'-'``, - ``'--'``, ``':'``, ``'-.'``. + ``'--'``, ``':'``, ``'-.'`` - - ``borderwidth`` -- integer (default: ``None``), the width of the + - ``borderwidth`` -- integer (default: ``None``); the width of the border in pixels - ``alpha`` -- (default: 1) how transparent the fill is; a number @@ -1447,20 +1446,19 @@ def region_plot(f, xrange, yrange, **options): ``basex`` sets the base of the logarithm along the horizontal axis and ``basey`` sets the base along the vertical axis. - - ``scale`` -- (default: ``"linear"``) string. The scale of the axes. - Possible values are ``"linear"``, ``"loglog"``, ``"semilogx"``, - ``"semilogy"``. + - ``scale`` -- string (default: ``'linear'``); the scale of the axes. + Possible values are ``'linear'``, ``'loglog'``, ``'semilogx'``, + ``'semilogy'``. The scale can be also be given as single argument that is a list or tuple ``(scale, base)`` or ``(scale, basex, basey)``. - The ``"loglog"`` scale sets both the horizontal and vertical axes to - logarithmic scale. The ``"semilogx"`` scale sets the horizontal axis - to logarithmic scale. The ``"semilogy"`` scale sets the vertical axis - to logarithmic scale. The ``"linear"`` scale is the default value + The ``'loglog'`` scale sets both the horizontal and vertical axes to + logarithmic scale. The ``'semilogx'`` scale sets the horizontal axis + to logarithmic scale. The ``'semilogy'`` scale sets the vertical axis + to logarithmic scale. The ``'linear'`` scale is the default value when :class:`~sage.plot.graphics.Graphics` is initialized. - EXAMPLES: Here we plot a simple function of two variables:: diff --git a/src/sage/plot/density_plot.py b/src/sage/plot/density_plot.py index a22394ad2c1..84d08518a0b 100644 --- a/src/sage/plot/density_plot.py +++ b/src/sage/plot/density_plot.py @@ -40,7 +40,7 @@ class DensityPlot(GraphicPrimitive): - ``yrange`` -- tuple of 2 floats indicating range for vertical direction - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -65,7 +65,7 @@ class DensityPlot(GraphicPrimitive): """ def __init__(self, xy_data_array, xrange, yrange, options): """ - Initializes base class DensityPlot. + Initialize base class ``DensityPlot``. EXAMPLES:: @@ -85,7 +85,7 @@ def __init__(self, xy_data_array, xrange, yrange, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -179,13 +179,12 @@ def density_plot(f, xrange, yrange, **options): Colormap. Type: ``import matplotlib.cm; matplotlib.cm.datad.keys()`` for available colormap names. - - ``interpolation`` -- string (default: ``'catrom'``), the interpolation + - ``interpolation`` -- string (default: ``'catrom'``); the interpolation method to use: ``'bilinear'``, ``'bicubic'``, ``'spline16'``, ``'spline36'``, ``'quadric'``, ``'gaussian'``, ``'sinc'``, ``'bessel'``, ``'mitchell'``, ``'lanczos'``, ``'catrom'``, ``'hermite'``, ``'hanning'``, ``'hamming'``, ``'kaiser'`` - EXAMPLES: Here we plot a simple function of two variables. Note that @@ -290,7 +289,7 @@ def f(x,y): return x**2 * cos(x*y) sage: density_plot((x*y)^(1/2), (x,0,3), (y,0,500), aspect_ratio=.01) Graphics object consisting of 1 graphics primitive - Default ``aspect_ratio`` is ``"automatic"``, and that should work too:: + Default ``aspect_ratio`` is ``'automatic'``, and that should work too:: sage: density_plot((x*y)^(1/2), (x,0,3), (y,0,500)) Graphics object consisting of 1 graphics primitive diff --git a/src/sage/plot/disk.py b/src/sage/plot/disk.py index e7f3f4475cf..862ba12afc9 100644 --- a/src/sage/plot/disk.py +++ b/src/sage/plot/disk.py @@ -40,7 +40,7 @@ class Disk(GraphicPrimitive): - ``angle`` -- beginning and ending angles of disk (i.e. angle extent of sector/wedge) - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -66,7 +66,7 @@ class Disk(GraphicPrimitive): """ def __init__(self, point, r, angle, options): """ - Initializes base class ``Disk``. + Initialize base class ``Disk``. EXAMPLES:: @@ -94,7 +94,7 @@ def __init__(self, point, r, angle, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -109,7 +109,6 @@ def get_minmax_data(self): 6.0 sage: d['ymax'] 5.0 - """ from sage.plot.plot import minmax_data return minmax_data([self.x - self.r, self.x + self.r], @@ -164,7 +163,6 @@ def _render_on_subplot(self, subplot): sage: f = tmp_filename(ext='.pdf') sage: p = disk((0,0), 5, (0, pi/4), alpha=0.5) sage: p.save(f) - """ import matplotlib.patches as patches options = self.options() @@ -190,8 +188,7 @@ def plot3d(self, z=0, **kwds): INPUT: - - - ``z`` -- optional 3D height above `xy`-plane. + - ``z`` -- (optional) 3D height above `xy`-plane AUTHORS: @@ -349,7 +346,7 @@ def disk(point, radius, angle, **options): Verify that :issue:`36153` is fixed:: - sage: D = disk((0, 0), 5, (0, pi/2), legend_label="test") + sage: D = disk((0, 0), 5, (0, pi/2), legend_label='test') """ from sage.plot.all import Graphics g = Graphics() diff --git a/src/sage/plot/ellipse.py b/src/sage/plot/ellipse.py index 02c598c793f..8722d6fdb83 100644 --- a/src/sage/plot/ellipse.py +++ b/src/sage/plot/ellipse.py @@ -48,7 +48,7 @@ class Ellipse(GraphicPrimitive): """ def __init__(self, x, y, r1, r2, angle, options): """ - Initializes base class ``Ellipse``. + Initialize base class ``Ellipse``. TESTS:: @@ -248,22 +248,22 @@ def ellipse(center, r1, r2, angle=0, **options): OPTIONS: - - ``alpha`` -- (default: 1); transparency + - ``alpha`` -- (default: 1) transparency - - ``fill`` -- (default: ``False``); whether to fill the ellipse or not + - ``fill`` -- (default: ``False``) whether to fill the ellipse or not - - ``thickness`` -- (default: 1); thickness of the line + - ``thickness`` -- (default: 1) thickness of the line - - ``linestyle`` -- (default: ``'solid'``); The style of the line, which is one + - ``linestyle`` -- (default: ``'solid'``) the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, or ``'--'``, - ``':'``, ``'-'``, ``'-.'``, respectively. + ``':'``, ``'-'``, ``'-.'``, respectively - - ``edgecolor`` -- (default: 'black'); color of the contour + - ``edgecolor`` -- (default: ``'black'``) color of the contour - - ``facecolor`` -- (default: 'red'); color of the filling + - ``facecolor`` -- (default: ``'red'``) color of the filling - ``rgbcolor`` -- 2D or 3D plotting. This option overrides - ``edgecolor`` and ``facecolor`` for 2D plotting. + ``edgecolor`` and ``facecolor`` for 2D plotting - ``legend_label`` -- the label for this item in the legend @@ -285,17 +285,17 @@ def ellipse(center, r1, r2, angle=0, **options): More complicated examples with tilted axes and drawing options:: sage: from math import pi - sage: ellipse((0,0), 3, 1, pi/6, fill=True, alpha=0.3, linestyle="dashed") + sage: ellipse((0,0), 3, 1, pi/6, fill=True, alpha=0.3, linestyle='dashed') Graphics object consisting of 1 graphics primitive .. PLOT:: - E = ellipse((0,0),3,1,pi/6,fill=True,alpha=0.3,linestyle="dashed") + E = ellipse((0,0),3,1,pi/6,fill=True,alpha=0.3,linestyle='dashed') sphinx_plot(E) other way to indicate dashed linestyle:: - sage: ellipse((0,0),3,1,pi/6,fill=True,alpha=0.3,linestyle="--") + sage: ellipse((0,0),3,1,pi/6,fill=True,alpha=0.3,linestyle='--') Graphics object consisting of 1 graphics primitive .. PLOT:: @@ -350,7 +350,7 @@ def ellipse(center, r1, r2, angle=0, **options): Verify that :issue:`36153` does not arise:: - sage: E = ellipse((0,0), 2, 1, legend_label="test") + sage: E = ellipse((0,0), 2, 1, legend_label='test') """ from sage.plot.all import Graphics g = Graphics() diff --git a/src/sage/plot/graphics.py b/src/sage/plot/graphics.py index f2f108f4295..1ade8565660 100644 --- a/src/sage/plot/graphics.py +++ b/src/sage/plot/graphics.py @@ -55,7 +55,7 @@ def is_Graphics(x): """ - Return True if `x` is a Graphics object. + Return ``True`` if `x` is a Graphics object. EXAMPLES:: @@ -99,7 +99,6 @@ def _parse_figsize(figsize): sage: _parse_figsize(5) # tol 1.0e-13 (5.0, 3.75) - """ from matplotlib import rcParams if isinstance(figsize, (list, tuple)): @@ -212,9 +211,7 @@ def set_aspect_ratio(self, ratio): INPUT: - - - ``ratio`` -- a positive real number or 'automatic' - + - ``ratio`` -- a positive real number or 'automatic' EXAMPLES: We create a plot of the upper half of a circle, but it doesn't look round because the aspect ratio is off:: @@ -292,7 +289,7 @@ def legend(self, show=None): INPUT: - - ``show`` -- (default: ``None``) a boolean + - ``show`` -- (default: ``None``) a boolean If called with no input, return the current legend setting. @@ -331,15 +328,15 @@ def set_legend_options(self, **kwds): INPUT: - - ``title`` -- (default: None) string, the legend title + - ``title`` -- (default: ``None``) string, the legend title - ``ncol`` -- (default: 1) positive integer, the number of columns - - ``columnspacing`` -- (default: None) the spacing between columns + - ``columnspacing`` -- (default: ``None``) the spacing between columns - - ``borderaxespad`` -- (default: None) float, length between the axes and the legend + - ``borderaxespad`` -- (default: ``None``) float, length between the axes and the legend - - ``back_color`` -- (default: 'white') This parameter can be a string + - ``back_color`` -- (default: ``'white'``) this parameter can be a string denoting a color or an RGB tuple. The string can be a color name as in ('red', 'green', 'yellow', ...) or a floating point number like '0.8' which gets expanded to (0.8, 0.8, 0.8). The @@ -352,7 +349,7 @@ def set_legend_options(self, **kwds): - ``labelspacing`` -- (default: 0.02) float, vertical space between legend entries - - ``loc`` -- (default: 'best') May be a string, an integer or a tuple. String or + - ``loc`` -- (default: ``'best'``) may be a string, an integer or a tuple. String or integer inputs must be one of the following: - 0, 'best' @@ -380,30 +377,36 @@ def set_legend_options(self, **kwds): - Tuple arguments represent an absolute (x, y) position on the plot in axes coordinates (meaning from 0 to 1 in each direction). - - ``markerscale`` -- (default: 0.6) float, how much to scale the markers in the legend. + - ``markerscale`` -- (default: 0.6) float, how much to scale the markers in the legend - ``numpoints`` -- (default: 2) integer, the number of points in the legend for line - ``borderpad`` -- (default: 0.6) float, the fractional whitespace inside the legend border (between 0 and 1) - - ``font_family`` -- (default: 'sans-serif') string, one of 'serif', 'sans-serif', - 'cursive', 'fantasy', 'monospace' + - ``font_family`` -- (default: ``'sans-serif'``) string, one of + ``'serif'``, ``'sans-serif'``, ``'cursive'``, ``'fantasy'``, + ``'monospace'`` - - ``font_style`` -- (default: 'normal') string, one of 'normal', 'italic', 'oblique' + - ``font_style`` -- (default: ``'normal'``) string, one of + ``'normal'``, ``'italic'``, ``'oblique'`` - - ``font_variant`` -- (default: 'normal') string, one of 'normal', 'small-caps' + - ``font_variant`` -- (default: ``'normal'``) string, one of + ``'normal'``, ``'small-caps'`` - - ``font_weight`` -- (default: 'medium') string, one of 'black', 'extra bold', 'bold', - 'semibold', 'medium', 'normal', 'light' + - ``font_weight`` -- (default: ``'medium'``) string, one of + ``'black'``, ``'extra bold'``, ``'bold'``, ``'semibold'``, + ``'medium'``, ``'normal'``, ``'light'`` - - ``font_size`` -- (default: 'medium') string, one of 'xx-small', 'x-small', 'small', - 'medium', 'large', 'x-large', 'xx-large' or an absolute font size (e.g. 12) + - ``font_size`` -- (default: ``'medium'``) string, one of + ``'xx-small'``, ``'x-small'``, ``'small'``, ``'medium'``, + ``'large'``, ``'x-large'``, ``'xx-large'``, or an absolute font size + (e.g. 12) - - ``shadow`` -- (default: ``True``) boolean -- draw a shadow behind the legend + - ``shadow`` -- boolean (default: ``True``); draw a shadow behind the legend - - ``fancybox`` -- (default: ``False``) a boolean. If True, draws a frame with a round - fancybox. + - ``fancybox`` -- boolean (default: ``False``); if + ``True``, draws a frame with a round fancybox These are all keyword arguments. @@ -456,8 +459,8 @@ def set_legend_options(self, **kwds): def get_axes_range(self): """ - Returns a dictionary of the range of the axes for this graphics - object. This is fall back to the ranges in get_minmax_data() for + Return a dictionary of the range of the axes for this graphics + object. This is fall back to the ranges in ``get_minmax_data()`` for any value which the user has not explicitly set. .. warning:: @@ -485,9 +488,7 @@ def set_axes_range(self, xmin=None, xmax=None, ymin=None, ymax=None): INPUT: - - - ``xmin, xmax, ymin, ymax`` -- floats - + - ``xmin``, ``xmax``, ``ymin``, ``ymax`` -- floats EXAMPLES:: @@ -507,7 +508,7 @@ def set_axes_range(self, xmin=None, xmax=None, ymin=None, ymax=None): def _get_axes_range_dict(self): """ - Returns the underlying dictionary used to store the user's + Return the underlying dictionary used to store the user's custom ranges for the axes on this object. EXAMPLES:: @@ -600,8 +601,7 @@ def fontsize(self, s=None): INPUT: - - - ``s`` -- integer, a font size in points. + - ``s`` -- integer, a font size in points If called with no input, return the current fontsize. @@ -635,7 +635,7 @@ def axes_labels_size(self, s=None): INPUT: - ``s`` -- float, relative size of axes labels w.r.t. to the tick marks, - the size of the tick marks being set by :meth:`fontsize`. + the size of the tick marks being set by :meth:`fontsize` If called with no input, return the current relative size. @@ -653,7 +653,6 @@ def axes_labels_size(self, s=None): sage: p # needs sage.symbolic Graphics object consisting of 1 graphics primitive - """ if s is None: try: @@ -670,9 +669,7 @@ def axes(self, show=None): INPUT: - - - ``show`` -- bool - + - ``show`` -- boolean If called with no input, return the current axes setting. @@ -718,10 +715,8 @@ def axes_color(self, c=None): INPUT: - - - ``c`` -- an RGB color 3-tuple, where each tuple entry - is a float between 0 and 1 - + - ``c`` -- an RGB color 3-tuple, where each tuple entry + is a float between 0 and 1 EXAMPLES: We create a line, which has like everything a default axes color of black. @@ -763,15 +758,13 @@ def axes_labels(self, l=None): INPUT: - - - ``l`` -- (default: None) a list of two strings or - None - + - ``l`` -- (default: ``None``) a list of two strings or + ``None`` OUTPUT: a 2-tuple of strings - If l is None, returns the current ``axes_labels``, - which is itself by default None. The default labels are both + If l is ``None``, returns the current ``axes_labels``, + which is itself by default ``None``. The default labels are both empty. EXAMPLES: We create a plot and put x and y axes labels on it. @@ -830,8 +823,7 @@ def axes_label_color(self, c=None): INPUT: - - - ``c`` -- an RGB 3-tuple of numbers between 0 and 1 + - ``c`` -- an RGB 3-tuple of numbers between 0 and 1 If called with no input, return the current axes_label_color @@ -878,8 +870,7 @@ def axes_width(self, w=None): INPUT: - - - ``w`` -- a float + - ``w`` -- a float If called with no input, return the current @@ -919,11 +910,10 @@ def tick_label_color(self, c=None): INPUT: - - - ``c`` -- an RGB 3-tuple of numbers between 0 and 1 + - ``c`` -- an RGB 3-tuple of numbers between 0 and 1 - If called with no input, return the current tick_label_color + If called with no input, return the current ``tick_label_color`` setting. EXAMPLES:: @@ -950,9 +940,7 @@ def _repr_(self): r""" Return a string representation of the graphics objects. - OUTPUT: - - String. + OUTPUT: string EXAMPLES: @@ -986,7 +974,7 @@ def _repr_(self): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -1026,9 +1014,7 @@ def __str__(self): r""" Return string representation of this plot. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1046,7 +1032,7 @@ def __str__(self): def __getitem__(self, i): """ - Returns the ith graphics primitive object: + Return the i-th graphics primitive object: EXAMPLES:: @@ -1073,7 +1059,7 @@ def __len__(self): def __delitem__(self, i): """ - If G is of type Graphics, then del(G[i]) removes the ith distinct + If G is of type Graphics, then del(G[i]) removes the i-th distinct graphic primitive making up that object. EXAMPLES:: @@ -1121,7 +1107,7 @@ def __radd__(self, other): Compute and return other + this graphics object. This only works when other is a Python int equal to 0. In all other - cases a :class:`TypeError` is raised. The main reason for this + cases a :exc:`TypeError` is raised. The main reason for this function is to make summing a list of graphics objects easier. EXAMPLES:: @@ -1242,7 +1228,7 @@ def __add__(self, other): def add_primitive(self, primitive): """ - Adds a primitive to this graphics object. + Add a primitive to this graphics object. EXAMPLES: @@ -1283,7 +1269,7 @@ def plot(self): ... TypeError: ...plot() takes 1 positional argument but 2 were given - sage: S.plot(hey="hou") + sage: S.plot(hey='hou') Traceback (most recent call last): ... TypeError: ...plot() got an unexpected keyword argument 'hey' @@ -1363,14 +1349,15 @@ def _set_scale(self, subplot, scale=None, base=None): INPUT: - - ``subplot`` -- matplotlib Axes instance. + - ``subplot`` -- matplotlib Axes instance - ``scale`` -- the scale of the figure. Values it can take are - ``"linear"``, ``"loglog"``, ``"semilogx"``, ``"semilogy"``. See + ``'linear'``, ``'loglog'``, ``'semilogx'``, ``'semilogy'``. See :meth:`show` for other options it can take. - ``base`` -- the base of the logarithm if a logarithmic scale is - set. See :meth:`show` for the options it can take. + set. See :meth:`show` for the options it can take OUTPUT: + The scale in the form of a tuple: (xscale, yscale, basex, basey) EXAMPLES:: @@ -1505,10 +1492,10 @@ def show(self, **kwds): inches, at the default ``dpi`` of 100 dpi, which is just shy of the maximum allowed value of 32768 dots (pixels). - - ``fig_tight`` -- (default: ``True``) whether to clip the drawing - tightly around drawn objects. If True, then the resulting + - ``fig_tight`` -- boolean (default: ``True``); whether to clip the drawing + tightly around drawn objects. If ``True``, then the resulting image will usually not have dimensions corresponding to - ``figsize``. If False, the resulting image will have + ``figsize``. If ``False``, the resulting image will have dimensions corresponding to ``figsize``. - ``aspect_ratio`` -- the perceived height divided by the @@ -1521,7 +1508,7 @@ def show(self, **kwds): - ``axes`` -- (default: ``True``) - - ``axes_labels`` -- (default: None) list (or tuple) of two + - ``axes_labels`` -- (default: ``None``) list (or tuple) of two strings; the first is used as the label for the horizontal axis, and the second for the vertical axis. @@ -1533,9 +1520,9 @@ def show(self, **kwds): integer; used for axes labels; if you make this very large, you may have to increase figsize to see all labels. - - ``frame`` -- (default: ``False``) draw a frame around the image + - ``frame`` -- boolean (default: ``False``); draw a frame around the image - - ``gridlines`` -- (default: None) can be any of the following: + - ``gridlines`` -- (default: ``None``) can be any of the following: - None, False: do not add grid lines. @@ -1562,33 +1549,34 @@ def show(self, **kwds): - ``gridlinesstyle, hgridlinesstyle, vgridlinesstyle`` - - (default: None) a dictionary of MATPLOTLIB options for the + (default: ``None``); a dictionary of MATPLOTLIB options for the rendering of the grid lines, the horizontal grid lines or the vertical grid lines, respectively. - - ``transparent`` -- (default: ``False``) If True, make the background transparent. + - ``transparent`` -- boolean (default: ``False``); if True, make the + background transparent - - ``axes_pad`` -- (default: 0.02 on ``"linear"`` scale, 1 on - ``"log"`` scale). + - ``axes_pad`` -- (default: 0.02 on ``'linear'`` scale, 1 on + ``'log'`` scale) - - In the ``"linear"`` scale, it determines the percentage of the + - In the ``'linear'`` scale, it determines the percentage of the axis range that is added to each end of each axis. This helps avoid problems like clipping lines because of line-width, etc. To get axes that are exactly the specified limits, set ``axes_pad`` to zero. - - On the ``"log"`` scale, it determines the exponent of the + - On the ``'log'`` scale, it determines the exponent of the fraction of the minimum (resp. maximum) that is subtracted from the minimum (resp. added to the maximum) value of the axis. For instance if the minimum is `m` and the base of the axis is `b` then the new minimum after padding the axis will be `m - m/b^{\mathrm{axes\_pad}}`. - - ``ticks_integer`` -- (default: ``False``) guarantee that the ticks + - ``ticks_integer`` -- boolean (default: ``False``); guarantee that the ticks are integers (the ``ticks`` option, if specified, will override this) - - ``ticks`` -- A matplotlib locator for the major ticks, or + - ``ticks`` -- a matplotlib locator for the major ticks, or a number. There are several options. For more information about locators, type ``from matplotlib import ticker`` and then ``ticker?``. @@ -1613,14 +1601,14 @@ def show(self, **kwds): ticks at the locations specified. This includes the case of of the empty list, which will give no ticks. See examples. - - ``tick_formatter`` -- A matplotlib formatter for the major + - ``tick_formatter`` -- a matplotlib formatter for the major ticks. There are several options. For more information about formatters, type ``from matplotlib import ticker`` and then ``ticker?``. If the value of this keyword is a single item, then this will give the formatting for the horizontal axis *only* (except for - the ``"latex"`` option). If it is a list or tuple, the first + the ``'latex'`` option). If it is a list or tuple, the first is for the horizontal axis, the second for the vertical axis. The options are below: @@ -1638,7 +1626,7 @@ def show(self, **kwds): This should only be used with the ``ticks`` option using nice rational multiples of that constant! - - If one of the entries is the string ``"latex"``, then the + - If one of the entries is the string ``'latex'``, then the formatting will be nice typesetting of the ticks. This is intended to be used when the tick locator for at least one of the axes is a list including some symbolic elements. This uses @@ -1646,9 +1634,9 @@ def show(self, **kwds): use an external LaTeX compiler, then set the keyword option ``typeset``. See examples. - - ``title`` -- (default: None) The title for the plot + - ``title`` -- (default: ``None``) the title for the plot - - ``title_pos`` -- (default: None) The position of the title for the + - ``title_pos`` -- (default: ``None``) the position of the title for the plot. It must be a tuple or a list of two real numbers ``(x_pos, y_pos)`` which indicate the relative position of the title within the plot. The plot itself can be considered to @@ -1666,13 +1654,13 @@ def show(self, **kwds): present in the list. Each entry of the list of strings must be provided with a corresponding number in the first entry of ``ticks`` to indicate its position on the axis. To typeset the - strings with ``"latex"`` enclose them within ``"$"`` symbols. To + strings with ``'latex'`` enclose them within ``'$'`` symbols. To have similar custom formatting of the labels along the vertical axis, the second entry must be a list of strings and the second entry of ``ticks`` must also be a list of numbers which give the positions of the labels. See the examples below. - - ``show_legend`` -- (default: None) If True, show the legend + - ``show_legend`` -- (default: ``None``) if ``True``, show the legend - ``legend_*`` -- all the options valid for :meth:`set_legend_options` prefixed with ``legend_`` @@ -1683,53 +1671,53 @@ def show(self, **kwds): ``basex`` sets the base of the logarithm along the horizontal axis and ``basey`` sets the base along the vertical axis. - - ``scale`` -- (default: ``"linear"``) string. The scale of the axes. + - ``scale`` -- (default: ``'linear'``) string. The scale of the axes. Possible values are - - ``"linear"`` -- linear scaling of both the axes - - ``"loglog"`` -- sets both the horizontal and vertical axes to + - ``'linear'`` -- linear scaling of both the axes + - ``'loglog'`` -- sets both the horizontal and vertical axes to logarithmic scale - - ``"semilogx"`` -- sets only the horizontal axis to logarithmic - scale. - - ``"semilogy"`` -- sets only the vertical axis to logarithmic - scale. + - ``'semilogx'`` -- sets only the horizontal axis to logarithmic + scale + - ``'semilogy'`` -- sets only the vertical axis to logarithmic + scale The scale can be also be given as single argument that is a list or tuple ``(scale, base)`` or ``(scale, basex, basey)``. - .. note:: + .. NOTE:: - - If the ``scale`` is ``"linear"``, then irrespective of what + - If the ``scale`` is ``'linear'``, then irrespective of what ``base`` is set to, it will default to 10 and will remain unused. - - ``xmin`` -- starting x value in the rendered figure. + - ``xmin`` -- starting x value in the rendered figure - - ``xmax`` -- ending x value in the rendered figure. + - ``xmax`` -- ending x value in the rendered figure - - ``ymin`` -- starting y value in the rendered figure. + - ``ymin`` -- starting y value in the rendered figure - - ``ymax`` -- ending y value in the rendered figure. + - ``ymax`` -- ending y value in the rendered figure - - ``flip_x`` -- (default: ``False``) boolean. If True, flip the horizontal - axis. + - ``flip_x`` -- boolean (default: ``False``); if ``True``, flip the horizontal + axis - - ``flip_y`` -- (default: ``False``) boolean. If True, flip the vertical - axis. + - ``flip_y`` -- boolean (default: ``False``); if ``True``, flip the vertical + axis - - ``typeset`` -- (default: ``"default"``) string. The type of + - ``typeset`` -- (default: ``'default'``) string. The type of font rendering that should be used for the text. The possible values are - - ``"default"`` -- Uses matplotlib's internal text rendering + - ``'default'`` -- uses matplotlib's internal text rendering engine called Mathtext ( see https://matplotlib.org/users/mathtext.html ). If you have modified the default matplotlib settings, for instance via a matplotlibrc file, then this option will not change any of those settings. - - ``"latex"`` -- LaTeX is used for rendering the fonts. This - requires LaTeX, dvipng and Ghostscript to be installed. - - ``"type1"`` -- Type 1 fonts are used by matplotlib in the text + - ``'latex'`` -- laTeX is used for rendering the fonts. This + requires LaTeX, dvipng and Ghostscript to be installed + - ``'type1'`` -- type 1 fonts are used by matplotlib in the text in the figure. This requires LaTeX, dvipng and Ghostscript to be installed. @@ -1770,14 +1758,14 @@ def show(self, **kwds): Graphics object consisting of 1 graphics primitive If you want all the text to be rendered by using an external LaTeX - installation then set the ``typeset`` to ``"latex"``. This + installation then set the ``typeset`` to ``'latex'``. This requires that LaTeX, dvipng and Ghostscript be installed:: sage: plot(x, typeset='latex') # optional - latex, needs sage.symbolic Graphics object consisting of 1 graphics primitive If you want all the text in your plot to use Type 1 fonts, then - set the ``typeset`` option to ``"type1"``. This requires that + set the ``typeset`` option to ``'type1'``. This requires that LaTeX, dvipng and Ghostscript be installed:: sage: plot(x, typeset='type1') # optional - latex, needs sage.symbolic @@ -1865,8 +1853,8 @@ def show(self, **kwds): sage: c = circle((0,0), 1) sage: c.show(gridlines=True) - sage: c.show(gridlines="automatic") - sage: c.show(gridlines="major") + sage: c.show(gridlines='automatic') + sage: c.show(gridlines='major') Add grid lines at the major and minor ticks of the axes. @@ -1876,7 +1864,7 @@ def show(self, **kwds): sage: u,v = var('u v') sage: f = exp(-(u^2+v^2)) sage: p = plot_vector_field(f.gradient(), (u,-2,2), (v,-2,2)) - sage: p.show(gridlines="minor") + sage: p.show(gridlines='minor') Add only horizontal or vertical grid lines. @@ -1902,7 +1890,7 @@ def show(self, **kwds): sage: def maple_leaf(t): ....: return (100/(100+(t-pi/2)^8))*(2-sin(7*t)-cos(30*t)/2) sage: p = polar_plot(maple_leaf, -pi/4, 3*pi/2, # long time, needs sage.symbolic - ....: color="red",plot_points=1000) + ....: color='red',plot_points=1000) sage: p.show(gridlines=([-3,-2.75,..,3], range(-1,5,2))) # long time, needs sage.symbolic Add grid lines at specific positions (using functions). @@ -1921,7 +1909,7 @@ def show(self, **kwds): sage: b = bar_chart([-3,5,-6,11], color='red') sage: b.show(gridlines=([-1,-0.5,..,4], True), - ....: gridlinesstyle=dict(color="blue", linestyle=":")) + ....: gridlinesstyle=dict(color='blue', linestyle=':')) Change the style of the horizontal or vertical grid lines separately. @@ -1930,8 +1918,8 @@ def show(self, **kwds): sage: p = polar_plot(2 + 2*cos(x), 0, 2*pi, color=hue(0.3)) # needs sage.symbolic sage: p.show(gridlines=True, # needs sage.symbolic - ....: hgridlinesstyle=dict(color="orange", linewidth=1.0), - ....: vgridlinesstyle=dict(color="blue", linestyle=":")) + ....: hgridlinesstyle=dict(color='orange', linewidth=1.0), + ....: vgridlinesstyle=dict(color='blue', linestyle=':')) Change the style of each grid line individually. @@ -1951,7 +1939,7 @@ def show(self, **kwds): ....: (1,{"color":"red","linestyle":":"}), ....: ] ....: ), - ....: gridlinesstyle=dict(marker='x',color="black")) + ....: gridlinesstyle=dict(marker='x',color='black')) Grid lines can be added to contour plots. @@ -1987,7 +1975,7 @@ def show(self, **kwds): Graphics object consisting of 2 graphics primitives The behavior of the ``axes_pad`` parameter is different if the axis - is in the ``"log"`` scale. If `b` is the base of the axis, the + is in the ``'log'`` scale. If `b` is the base of the axis, the minimum value of the axis, is decreased by the factor `1/b^{\mathrm{axes\_pad}}` of the minimum and the maximum value of the axis is increased by the same factor of the maximum value. Compare the @@ -2049,7 +2037,7 @@ def show(self, **kwds): sage: plot(2*x + 1, (x,0,5), # not tested (broken with matplotlib 3.6), needs sage.symbolic ....: ticks=[[0,1,e,pi,sqrt(20)], 2], - ....: tick_formatter="latex") + ....: tick_formatter='latex') Graphics object consisting of 1 graphics primitive This is particularly useful when setting custom ticks in multiples @@ -2251,7 +2239,7 @@ def ymax(self, ymax=None): def get_minmax_data(self): r""" - Return the x and y coordinate minimum and maximum + Return the x and y coordinate minimum and maximum. .. warning:: @@ -2326,12 +2314,12 @@ def get_minmax_data(self): def _limit_output_aspect_ratio(self, xmin, xmax, ymin, ymax): r""" - Private helper function for :meth:`get_minmax_data` + Private helper function for :meth:`get_minmax_data`. INPUT: - ``xmin``, ``xmax``, ``ymin``, ``ymax`` -- bounding box for - the graphics. + the graphics OUTPUT: @@ -2385,7 +2373,7 @@ def _matplotlib_tick_formatter(self, subplot, base=(10, 10), INPUT: - - ``subplot`` -- the subplot instance. + - ``subplot`` -- the subplot instance EXAMPLES:: @@ -2562,11 +2550,11 @@ def _get_vmin_vmax(self, vmin, vmax, basev, axes_pad): INPUT: - - ``vmin`` -- the current min for this variable (e.g. xmin or ymin) + - ``vmin`` -- the current min for this variable (e.g. xmin or ymin) - - ``vmax`` -- the current max for this variable (e.g. xmax or ymax) + - ``vmax`` -- the current max for this variable (e.g. xmax or ymax) - - ``basev`` -- the base of the logarithmic scale for this variable + - ``basev`` -- the base of the logarithmic scale for this variable - ``axes_pad`` -- the padding for the axis. It determines the exponent of the fraction of the minimum (resp. maximum) that is @@ -2617,7 +2605,6 @@ def _get_vmin_vmax(self, vmin, vmax, basev, axes_pad): Traceback (most recent call last): ... ValueError: vmin must be less than vmax - """ if vmin <= 0: raise ValueError('vmin must be positive') @@ -3242,7 +3229,7 @@ def matplotlib(self, filename=None, def save_image(self, filename=None, *args, **kwds): r""" - Save an image representation of self. + Save an image representation of ``self``. The image type is determined by the extension of the filename. For example, this could be ``.png``, ``.jpg``, ``.gif``, @@ -3259,7 +3246,7 @@ def save_image(self, filename=None, *args, **kwds): sage: import tempfile sage: c = circle((1,1), 1, color='red') - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: ....: c.save_image(f.name, xmin=-1, xmax=3, ....: ymin=-1, ymax=3) """ @@ -3296,15 +3283,13 @@ def save(self, filename, **kwds): All other keyword arguments will be passed to the plotter. - OUTPUT: - - - none. + OUTPUT: none EXAMPLES:: sage: c = circle((1,1), 1, color='red') sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(suffix=".png") as f: + sage: with NamedTemporaryFile(suffix='.png') as f: ....: c.save(f.name, xmin=-1, xmax=3, ymin=-1, ymax=3) To make a figure bigger or smaller, use ``figsize``:: @@ -3340,7 +3325,7 @@ def save(self, filename, **kwds): sage: P.set_legend_options(back_color=(1,0,0)) sage: P.set_legend_options(loc=7) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: ....: P.save(f.name) This plot should save with the frame shown, showing :issue:`7524` @@ -3350,14 +3335,13 @@ def save(self, filename, **kwds): (x, y) sage: a = plot_vector_field((x,-y),(x,-1,1),(y,-1,1)) # needs sage.symbolic sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: # needs sage.symbolic + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: # needs sage.symbolic ....: a.save(f.name) The following plot should show the axes; fixes :issue:`14782` :: sage: plot(x^2, (x, 1, 2), ticks=[[], []]) # needs sage.symbolic Graphics object consisting of 1 graphics primitive - """ options = {} options.update(self.SHOW_OPTIONS) @@ -3442,11 +3426,9 @@ def _latex_(self, **kwds): INPUT: - All keyword arguments will be passed to the plotter. - - OUTPUT: + - ``**kwds`` -- all keyword arguments will be passed to the plotter - A string of PGF commands to plot ``self`` + OUTPUT: string of PGF commands to plot ``self`` EXAMPLES:: @@ -3509,9 +3491,7 @@ def inset(self, graphics, pos=None, fontsize=None): ``fontsize`` has been explicitly set in the construction of ``graphics`` (in this case, it is not overwritten here) - OUTPUT: - - - instance of :class:`~sage.plot.multigraphics.MultiGraphics` + OUTPUT: instance of :class:`~sage.plot.multigraphics.MultiGraphics` EXAMPLES:: @@ -3562,7 +3542,6 @@ def inset(self, graphics, pos=None, fontsize=None): g3 = plot(f(x), (x, -0.05, 0.05), axes_labels=['$x$', '$y$'], \ frame=True) sphinx_plot(g1g2.inset(g3, pos=(0.65, 0.12, 0.25, 0.25))) - """ from .multigraphics import MultiGraphics if pos is None: @@ -3591,7 +3570,6 @@ def GraphicsArray(*args, **kwargs): See https://github.com/sagemath/sage/issues/28675 for details. sage: G Graphics Array of size 1 x 2 - """ from .multigraphics import GraphicsArray as NewGraphicsArray from sage.misc.superseded import deprecation diff --git a/src/sage/plot/histogram.py b/src/sage/plot/histogram.py index a585cacf9cd..d2514b9ef29 100644 --- a/src/sage/plot/histogram.py +++ b/src/sage/plot/histogram.py @@ -210,49 +210,49 @@ def _render_on_subplot(self, subplot): @options(aspect_ratio='automatic', align='mid', weights=None, range=None, bins=10, edgecolor='black') def histogram(datalist, **options): """ - Computes and draws the histogram for list(s) of numerical data. + Compute and draw the histogram for list(s) of numerical data. See examples for the many options; even more customization is available using matplotlib directly. INPUT: - - ``datalist`` -- A list, or a list of lists, of numerical data - - ``align`` -- (default: "mid") How the bars align inside of each bin. - Acceptable values are "left", "right" or "mid" + - ``datalist`` -- list, or a list of lists, of numerical data + - ``align`` -- (default: ``'mid'``) how the bars align inside of each bin. + Acceptable values are ``'left'`` ``'right'`` or ``'mid'`` - ``alpha`` -- (float in [0,1], default: 1) The transparency of the plot - - ``bins`` -- The number of sections in which to divide the range. Also + - ``bins`` -- the number of sections in which to divide the range. Also can be a sequence of points within the range that create the partition - - ``color`` -- The color of the face of the bars or list of colors if + - ``color`` -- the color of the face of the bars or list of colors if multiple data sets are given - - ``cumulative`` -- (default: ``False``) If True, then + - ``cumulative`` -- boolean (default: ``False``); if True, then a histogram is computed in which each bin gives the counts in that bin plus all bins for smaller values. Negative values give a reversed direction of accumulation - - ``edgecolor`` -- The color of the border of each bar - - ``fill`` -- (default: ``True``) Whether to fill the bars - - ``hatch`` -- (default: None) symbol to fill the bars with; one of + - ``edgecolor`` -- the color of the border of each bar + - ``fill`` -- boolean (default: ``True``); whether to fill the bars + - ``hatch`` -- (default: ``None``) symbol to fill the bars with; one of "/", "\\", "|", "-", "+", "x", "o", "O", ".", "*", "" (or None) - - ``hue`` -- The color of the bars given as a hue. See + - ``hue`` -- the color of the bars given as a hue. See :mod:`~sage.plot.colors.hue` for more information on the hue - - ``label`` -- A string label for each data list given + - ``label`` -- string label for each data list given - ``linewidth`` -- (float) width of the lines defining the bars - - ``linestyle`` -- (default: 'solid') Style of the line. One of 'solid' + - ``linestyle`` -- (default: ``'solid'``) style of the line. One of 'solid' or '-', 'dashed' or '--', 'dotted' or ':', 'dashdot' or '-.' - - ``density`` -- (default: ``False``) If True, the result is the + - ``density`` -- boolean (default: ``False``); if True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. - - ``range`` -- A list [min, max] which define the range of the + - ``range`` -- list [min, max] which define the range of the histogram. Values outside of this range are treated as outliers and omitted from counts - ``rwidth`` -- (float in [0,1], default: 1) The relative width of the bars as a fraction of the bin width - - ``stacked`` -- (default: ``False``) If True, multiple data are + - ``stacked`` -- boolean (default: ``False``); if True, multiple data are stacked on top of each other - ``weights`` -- (list) A sequence of weights the same length as the data list. If supplied, then each value contributes its associated weight to the bin count - - ``zorder`` -- (integer) the layer level at which to draw the histogram + - ``zorder`` -- integer; the layer level at which to draw the histogram .. NOTE:: @@ -290,12 +290,12 @@ def histogram(datalist, **options): There are many options one can use with histograms. Some of these control the presentation of the data, even if it is boring:: - sage: histogram(list(range(100)), color=(1,0,0), label='mydata', rwidth=.5, align="right") + sage: histogram(list(range(100)), color=(1,0,0), label='mydata', rwidth=.5, align='right') Graphics object consisting of 1 graphics primitive .. PLOT:: - sphinx_plot(histogram(list(range(100)), color=(1,0,0), label='mydata', rwidth=.5, align="right")) + sphinx_plot(histogram(list(range(100)), color=(1,0,0), label='mydata', rwidth=.5, align='right')) This includes many usual matplotlib styling options:: diff --git a/src/sage/plot/hyperbolic_arc.py b/src/sage/plot/hyperbolic_arc.py index ef75f805348..904576f79b2 100644 --- a/src/sage/plot/hyperbolic_arc.py +++ b/src/sage/plot/hyperbolic_arc.py @@ -200,7 +200,7 @@ def __init__(self, A, B, model, options): sage: from sage.plot.hyperbolic_arc import HyperbolicArc sage: arc = HyperbolicArc(0, 1/2+I*sqrt(3)/2, "UHP", {}) - sage: TestSuite(arc).run(skip="_test_pickling") # no equality implemented + sage: TestSuite(arc).run(skip='_test_pickling') # no equality implemented """ if model == "HM": raise ValueError("the hyperboloid model is not supported") @@ -230,8 +230,8 @@ def _repr_(self): @rename_keyword(color='rgbcolor') -@options(alpha=1, fill=False, thickness=1, rgbcolor="blue", zorder=2, linestyle='solid') -def hyperbolic_arc(a, b, model="UHP", **options): +@options(alpha=1, fill=False, thickness=1, rgbcolor='blue', zorder=2, linestyle='solid') +def hyperbolic_arc(a, b, model='UHP', **options): r""" Plot an arc from ``a`` to ``b`` in hyperbolic plane. @@ -249,11 +249,11 @@ def hyperbolic_arc(a, b, model="UHP", **options): OPTIONS: - - ``alpha`` -- default: 1 + - ``alpha`` -- (default: 1) - - ``thickness`` -- default: 1 + - ``thickness`` -- (default: 1) - - ``rgbcolor`` -- default: ``'blue'`` + - ``rgbcolor`` -- (default: ``'blue'``) - ``linestyle`` -- (default: ``'solid'``) the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, @@ -320,9 +320,9 @@ def hyperbolic_arc(a, b, model="UHP", **options): sage: z4 = CC((0.6*cos(3*pi/4),0.6*sin(3*pi/4))) sage: z5 = CC(-0.5,0.5) sage: z6 = CC(0.5,-0.5) - sage: a1 = hyperbolic_arc(z1, z2, model="PD", color="red") - sage: a2 = hyperbolic_arc(z3, z4, model="PD", color="green") - sage: a3 = hyperbolic_arc(z5, z6, model="PD", linestyle="--") + sage: a1 = hyperbolic_arc(z1, z2, model='PD', color='red') + sage: a2 = hyperbolic_arc(z3, z4, model='PD', color='green') + sage: a3 = hyperbolic_arc(z5, z6, model='PD', linestyle='--') sage: a1 + a2 + a3 Graphics object consisting of 6 graphics primitives @@ -334,9 +334,9 @@ def hyperbolic_arc(a, b, model="UHP", **options): z4 = CC((0.6*cos(3*pi/4),0.6*sin(3*pi/4))) z5 = CC(-0.5,0.5) z6 = CC(0.5,-0.5) - a1 = hyperbolic_arc(z1, z2, model="PD", color="red") - a2 = hyperbolic_arc(z3, z4, model="PD", color="green") - a3 = hyperbolic_arc(z5, z6, model="PD", linestyle="--") + a1 = hyperbolic_arc(z1, z2, model='PD', color='red') + a2 = hyperbolic_arc(z3, z4, model='PD', color='green') + a3 = hyperbolic_arc(z5, z6, model='PD', linestyle='--') P = a1 + a2 + a3 sphinx_plot(P) @@ -344,9 +344,9 @@ def hyperbolic_arc(a, b, model="UHP", **options): model (note that these are *not* the image of those arcs when changing between the models):: - sage: a1 = hyperbolic_arc(z1, z2, model="KM", color="red") - sage: a2 = hyperbolic_arc(z3, z4, model="KM", color="green") - sage: a3 = hyperbolic_arc(z5, z6, model="KM", linestyle="--") + sage: a1 = hyperbolic_arc(z1, z2, model='KM', color='red') + sage: a2 = hyperbolic_arc(z3, z4, model='KM', color='green') + sage: a3 = hyperbolic_arc(z5, z6, model='KM', linestyle='--') sage: a1 + a2 + a3 Graphics object consisting of 6 graphics primitives @@ -358,9 +358,9 @@ def hyperbolic_arc(a, b, model="UHP", **options): z4 = CC((0.6*cos(3*pi/4),0.6*sin(3*pi/4))) z5 = CC(-0.5,0.5) z6 = CC(0.5,-0.5) - a1 = hyperbolic_arc(z1, z2, model="KM", color="red") - a2 = hyperbolic_arc(z3, z4, model="KM", color="green") - a3 = hyperbolic_arc(z5, z6, model="KM", linestyle="--") + a1 = hyperbolic_arc(z1, z2, model='KM', color='red') + a2 = hyperbolic_arc(z3, z4, model='KM', color='green') + a3 = hyperbolic_arc(z5, z6, model='KM', linestyle='--') P = a1 + a2 + a3 sphinx_plot(P) @@ -369,14 +369,14 @@ def hyperbolic_arc(a, b, model="UHP", **options): sage: a = (1,2,sqrt(6)) sage: b = (-2,-3,sqrt(14)) - sage: hyperbolic_arc(a, b, model="HM") + sage: hyperbolic_arc(a, b, model='HM') Graphics3d Object .. PLOT:: a = (1,2,sqrt(6)) b = (-2,-3,sqrt(14)) - sphinx_plot(hyperbolic_arc(a, b, model="HM")) + sphinx_plot(hyperbolic_arc(a, b, model='HM')) """ from sage.plot.graphics import Graphics diff --git a/src/sage/plot/hyperbolic_polygon.py b/src/sage/plot/hyperbolic_polygon.py index 57b2bbe971b..f74c35fef6f 100644 --- a/src/sage/plot/hyperbolic_polygon.py +++ b/src/sage/plot/hyperbolic_polygon.py @@ -43,7 +43,7 @@ class HyperbolicPolygon(HyperbolicArcCore): - ``pts`` -- coordinates of the polygon (as complex numbers) - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -62,7 +62,7 @@ def __init__(self, pts, model, options): sage: from sage.plot.hyperbolic_polygon import HyperbolicPolygon sage: HP = HyperbolicPolygon([0, 1/2, I], "UHP", {}) - sage: TestSuite(HP).run(skip ="_test_pickling") + sage: TestSuite(HP).run(skip ='_test_pickling') """ if model == "HM": raise ValueError("the hyperboloid model is not supported") @@ -152,8 +152,8 @@ def _is_left(point, edge): @rename_keyword(color='rgbcolor') -@options(alpha=1, fill=False, thickness=1, rgbcolor="blue", zorder=2, linestyle='solid') -def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): +@options(alpha=1, fill=False, thickness=1, rgbcolor='blue', zorder=2, linestyle='solid') +def hyperbolic_polygon(pts, model='UHP', resolution=200, **options): r""" Return a hyperbolic polygon in the hyperbolic plane with vertices ``pts``. @@ -161,19 +161,19 @@ def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): INPUT: - - ``pts`` -- a list or tuple of complex numbers + - ``pts`` -- list or tuple of complex numbers OPTIONS: - - ``model`` -- default: ``UHP`` Model used for hyperbolic plane + - ``model`` -- (default: ``UHP``) Model used for hyperbolic plane - - ``alpha`` -- default: 1 + - ``alpha`` -- (default: 1) - - ``fill`` -- default: ``False`` + - ``fill`` -- (default: ``False``) - - ``thickness`` -- default: 1 + - ``thickness`` -- (default: 1) - - ``rgbcolor`` -- default: ``'blue'`` + - ``rgbcolor`` -- (default: ``'blue'``) - ``linestyle`` -- (default: ``'solid'``) the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, or @@ -214,21 +214,21 @@ def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): Show a hyperbolic polygon in the Poincare disc model with coordinates `1`, `i`, `-1`, `-i`:: - sage: hyperbolic_polygon([1,I,-1,-I], model="PD", color='green') + sage: hyperbolic_polygon([1,I,-1,-I], model='PD', color='green') Graphics object consisting of 2 graphics primitives .. PLOT:: - sphinx_plot(hyperbolic_polygon([1,I,-1,-I], model="PD", color='green')) + sphinx_plot(hyperbolic_polygon([1,I,-1,-I], model='PD', color='green')) With more options:: - sage: hyperbolic_polygon([1,I,-1,-I], model="PD", color='green', fill=True, linestyle="-") + sage: hyperbolic_polygon([1,I,-1,-I], model='PD', color='green', fill=True, linestyle='-') Graphics object consisting of 2 graphics primitives .. PLOT:: - P = hyperbolic_polygon([1,I,-1,-I], model="PD", color='green', fill=True, linestyle="-") + P = hyperbolic_polygon([1,I,-1,-I], model='PD', color='green', fill=True, linestyle='-') sphinx_plot(P) Klein model is also supported via the parameter ``model``. @@ -241,7 +241,7 @@ def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): sage: p4 = -1 sage: p5 = (cos(4*pi/3), sin(4*pi/3)) sage: p6 = (cos(5*pi/3), sin(5*pi/3)) - sage: hyperbolic_polygon([p1,p2,p3,p4,p5,p6], model="KM", fill=True, color='purple') + sage: hyperbolic_polygon([p1,p2,p3,p4,p5,p6], model='KM', fill=True, color='purple') Graphics object consisting of 2 graphics primitives .. PLOT:: @@ -252,7 +252,7 @@ def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): p4=-1 p5=(cos(4*pi/3),sin(4*pi/3)) p6=(cos(5*pi/3),sin(5*pi/3)) - P = hyperbolic_polygon([p1,p2,p3,p4,p5,p6], model="KM", fill=True, color='purple') + P = hyperbolic_polygon([p1,p2,p3,p4,p5,p6], model='KM', fill=True, color='purple') sphinx_plot(P) Hyperboloid model is supported partially, via the parameter ``model``. @@ -261,13 +261,13 @@ def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): `(-3,3,\sqrt(19))`:: sage: pts = [(3,3,sqrt(19)),(3,-3,sqrt(19)),(-3,-3,sqrt(19)),(-3,3,sqrt(19))] - sage: hyperbolic_polygon(pts, model="HM") + sage: hyperbolic_polygon(pts, model='HM') Graphics3d Object .. PLOT:: pts = [(3,3,sqrt(19)),(3,-3,sqrt(19)),(-3,-3,sqrt(19)),(-3,3,sqrt(19))] - P = hyperbolic_polygon(pts, model="HM") + P = hyperbolic_polygon(pts, model='HM') sphinx_plot(P) Filling a hyperbolic_polygon in hyperboloid model is possible although @@ -277,16 +277,15 @@ def hyperbolic_polygon(pts, model="UHP", resolution=200, **options): give a faster result.) :: sage: pts = [(1,1,sqrt(3)), (0,2,sqrt(5)), (2,0,sqrt(5))] - sage: hyperbolic_polygon(pts, model="HM", resolution=50, + sage: hyperbolic_polygon(pts, model='HM', resolution=50, ....: color='yellow', fill=True) Graphics3d Object .. PLOT:: pts = [(1,1,sqrt(3)),(0,2,sqrt(5)),(2,0,sqrt(5))] - P = hyperbolic_polygon(pts, model="HM", color='yellow', fill=True) + P = hyperbolic_polygon(pts, model='HM', color='yellow', fill=True) sphinx_plot(P) - """ from sage.plot.all import Graphics g = Graphics() @@ -329,7 +328,7 @@ def region(x, y, z): return g -def hyperbolic_triangle(a, b, c, model="UHP", **options): +def hyperbolic_triangle(a, b, c, model='UHP', **options): r""" Return a hyperbolic triangle in the hyperbolic plane with vertices ``(a,b,c)``. @@ -342,17 +341,17 @@ def hyperbolic_triangle(a, b, c, model="UHP", **options): OPTIONS: - - ``alpha`` -- default: 1 + - ``alpha`` -- (default: 1) - - ``fill`` -- default: ``False`` + - ``fill`` -- (default: ``False``) - - ``thickness`` -- default: 1 + - ``thickness`` -- (default: 1) - - ``rgbcolor`` -- default: ``'blue'`` + - ``rgbcolor`` -- (default: ``'blue'``) - ``linestyle`` -- (default: ``'solid'``) the style of the line, which is one of ``'dashed'``, ``'dotted'``, ``'solid'``, ``'dashdot'``, or - ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively. + ``'--'``, ``':'``, ``'-'``, ``'-.'``, respectively EXAMPLES: @@ -392,7 +391,7 @@ def hyperbolic_triangle(a, b, c, model="UHP", **options): sage: z1 = CC((cos(pi/3),sin(pi/3))) sage: z2 = CC((0.6*cos(3*pi/4),0.6*sin(3*pi/4))) sage: z3 = 1 - sage: hyperbolic_triangle(z1, z2, z3, model="PD", color="red") + sage: hyperbolic_triangle(z1, z2, z3, model='PD', color='red') Graphics object consisting of 2 graphics primitives .. PLOT:: @@ -400,18 +399,17 @@ def hyperbolic_triangle(a, b, c, model="UHP", **options): z1 = CC((cos(pi/3),sin(pi/3))) z2 = CC((0.6*cos(3*pi/4),0.6*sin(3*pi/4))) z3 = 1 - P = hyperbolic_triangle(z1, z2, z3, model="PD", color="red") + P = hyperbolic_triangle(z1, z2, z3, model='PD', color='red') sphinx_plot(P) :: - sage: hyperbolic_triangle(0.3+0.3*I, 0.8*I, -0.5-0.5*I, model="PD", color='magenta') + sage: hyperbolic_triangle(0.3+0.3*I, 0.8*I, -0.5-0.5*I, model='PD', color='magenta') Graphics object consisting of 2 graphics primitives .. PLOT:: - P = hyperbolic_triangle(0.3+0.3*I, 0.8*I, -0.5-0.5*I, model="PD", color='magenta') + P = hyperbolic_triangle(0.3+0.3*I, 0.8*I, -0.5-0.5*I, model='PD', color='magenta') sphinx_plot(P) - """ return hyperbolic_polygon((a, b, c), model, **options) diff --git a/src/sage/plot/hyperbolic_regular_polygon.py b/src/sage/plot/hyperbolic_regular_polygon.py index 96df49b2271..14e8bdcaf68 100644 --- a/src/sage/plot/hyperbolic_regular_polygon.py +++ b/src/sage/plot/hyperbolic_regular_polygon.py @@ -61,7 +61,7 @@ class HyperbolicRegularPolygon(HyperbolicPolygon): A(\mathcal{P}) = \pi(s-2) - s \cdot \alpha > 0, - where `s` is ``sides`` and `\alpha` is ``i_angle`. This raises an error if + where `s` is ``sides`` and `\alpha` is ``i_angle``. This raises an error if the ``i_angle`` is less than the minimum to generate a compact polygon:: sage: from sage.plot.hyperbolic_regular_polygon import HyperbolicRegularPolygon @@ -184,9 +184,7 @@ def _i_rotation(self, z, alpha): - ``alpha`` -- angle of rotation (radians, counterclockwise) - OUTPUT: - - - rotated point in the upper complex halfplane + OUTPUT: rotated point in the upper complex halfplane TESTS:: @@ -203,7 +201,7 @@ def _i_rotation(self, z, alpha): @rename_keyword(color='rgbcolor') -@options(alpha=1, fill=False, thickness=1, rgbcolor="blue", zorder=2, +@options(alpha=1, fill=False, thickness=1, rgbcolor='blue', zorder=2, linestyle='solid') def hyperbolic_regular_polygon(sides, i_angle, center=CC(0,1), **options): r""" @@ -219,18 +217,18 @@ def hyperbolic_regular_polygon(sides, i_angle, center=CC(0,1), **options): - ``i_angle`` -- interior angle of the polygon - - ``center`` -- (default: `i`) hyperbolic center point + - ``center`` -- (default: `i`) hyperbolic center point (complex number) of the polygon OPTIONS: - - ``alpha`` -- default: 1 + - ``alpha`` -- (default: 1) - - ``fill`` -- default: ``False`` + - ``fill`` -- (default: ``False``) - - ``thickness`` -- default: 1 + - ``thickness`` -- (default: 1) - - ``rgbcolor`` -- default: ``'blue'`` + - ``rgbcolor`` -- (default: ``'blue'``) - ``linestyle`` -- (default: ``'solid'``) the style of the line, which can be one of the following: @@ -271,7 +269,7 @@ def hyperbolic_regular_polygon(sides, i_angle, center=CC(0,1), **options): A(\mathcal{P}) = \pi(s-2) - s \cdot \alpha > 0, - where `s` is ``sides`` and `\alpha` is ``i_angle`. This raises an error if + where `s` is ``sides`` and `\alpha` is ``i_angle``. This raises an error if the ``i_angle`` is less than the minimum to generate a compact polygon:: sage: hyperbolic_regular_polygon(4, pi/2) diff --git a/src/sage/plot/line.py b/src/sage/plot/line.py index 92db1abf424..241b2b4c1f1 100644 --- a/src/sage/plot/line.py +++ b/src/sage/plot/line.py @@ -103,7 +103,7 @@ def _plot3d_options(self, options=None): 0.5 sage: m.thickness 10 - sage: L = line([(1,1), (1,2), (2,2), (2,1)], linestyle=":") + sage: L = line([(1,1), (1,2), (2,2), (2,1)], linestyle=':') sage: L.plot3d() Traceback (most recent call last): ... @@ -141,7 +141,6 @@ def plot3d(self, z=0, **kwds): E = EllipticCurve('37a').plot(thickness=5).plot3d() F = EllipticCurve('37a').plot(thickness=5).plot3d(z=2) sphinx_plot(E+F) - """ from sage.plot.plot3d.shapes2 import line3d options = self._plot3d_options() @@ -166,11 +165,9 @@ def __getitem__(self, i): INPUT: - - ``i`` -- an integer between 0 and the number of points minus 1 - - OUTPUT: + - ``i`` -- integer between 0 and the number of points minus 1 - A 2-tuple of floats. + OUTPUT: 2-tuple of floats EXAMPLES:: @@ -193,7 +190,7 @@ def __setitem__(self, i, point): INPUT: - - ``i`` -- an integer between 0 and the number of points on the + - ``i`` -- integer between 0 and the number of points on the line minus 1 - ``point`` -- a 2-tuple of floats @@ -276,13 +273,13 @@ def _render_on_subplot(self, subplot): def line(points, **kwds): """ - Returns either a 2-dimensional or 3-dimensional line depending + Return either a 2-dimensional or 3-dimensional line depending on value of points. INPUT: - - ``points`` -- either a single point (as a tuple), a list of - points, a single complex number, or a list of complex numbers. + - ``points`` -- either a single point (as a tuple), a list of + points, a single complex number, or a list of complex numbers For information regarding additional arguments, see either line2d? or line3d?. @@ -323,8 +320,8 @@ def line2d(points, **options): INPUT: - - ``points`` -- either a single point (as a tuple), a list of - points, a single complex number, or a list of complex numbers. + - ``points`` -- either a single point (as a tuple), a list of + points, a single complex number, or a list of complex numbers Type ``line2d.options`` for a dictionary of the default options for lines. You can change this to change the defaults for all future @@ -332,39 +329,39 @@ def line2d(points, **options): INPUT: - - ``alpha`` -- How transparent the line is + - ``alpha`` -- how transparent the line is - - ``thickness`` -- How thick the line is + - ``thickness`` -- how thick the line is - - ``rgbcolor`` -- The color as an RGB tuple + - ``rgbcolor`` -- the color as an RGB tuple - - ``hue`` -- The color given as a hue + - ``hue`` -- the color given as a hue - - ``legend_color`` -- The color of the text in the legend + - ``legend_color`` -- the color of the text in the legend - ``legend_label`` -- the label for this item in the legend Any MATPLOTLIB line option may also be passed in. E.g., - - ``linestyle`` -- (default: "-") The style of the line, which is one of - - ``"-"`` or ``"solid"`` - - ``"--"`` or ``"dashed"`` - - ``"-."`` or ``"dash dot"`` - - ``":"`` or ``"dotted"`` + - ``linestyle`` -- (default: ``'-'``) the style of the line, which is one of + - ``'-'`` or ``'solid'`` + - ``'--'`` or ``'dashed'`` + - ``'-.'`` or ``'dash dot'`` + - ``':'`` or ``'dotted'`` - ``"None"`` or ``" "`` or ``""`` (nothing) - The linestyle can also be prefixed with a drawing style (e.g., ``"steps--"``) + The linestyle can also be prefixed with a drawing style (e.g., ``'steps--'``) - - ``"default"`` (connect the points with straight lines) - - ``"steps"`` or ``"steps-pre"`` (step function; horizontal + - ``'default'`` (connect the points with straight lines) + - ``'steps'`` or ``'steps-pre'`` (step function; horizontal line is to the left of point) - - ``"steps-mid"`` (step function; points are in the middle of + - ``'steps-mid'`` (step function; points are in the middle of horizontal lines) - - ``"steps-post"`` (step function; horizontal line is to the + - ``'steps-post'`` (step function; horizontal line is to the right of point) - - ``marker`` -- The style of the markers, which is one of + - ``marker`` -- the style of the markers, which is one of - ``"None"`` or ``" "`` or ``""`` (nothing) -- default - ``","`` (pixel), ``"."`` (point) - ``"_"`` (horizontal line), ``"|"`` (vertical line) diff --git a/src/sage/plot/matrix_plot.py b/src/sage/plot/matrix_plot.py index 5e505957e8f..900ac9989e0 100644 --- a/src/sage/plot/matrix_plot.py +++ b/src/sage/plot/matrix_plot.py @@ -41,7 +41,7 @@ class MatrixPlot(GraphicPrimitive): (number of rows in the matrix). If ``None``, the defaults are used as indicated in :func:`matrix_plot`. - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -73,7 +73,7 @@ class MatrixPlot(GraphicPrimitive): """ def __init__(self, xy_data_array, xrange, yrange, options): """ - Initializes base class MatrixPlot. + Initialize base class MatrixPlot. EXAMPLES:: @@ -98,7 +98,7 @@ def __init__(self, xy_data_array, xrange, yrange, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -273,26 +273,26 @@ def matrix_plot(mat, xrange=None, yrange=None, **options): - ``mat`` -- a 2D matrix or array - - ``xrange`` -- (default: None) tuple of the horizontal extent + - ``xrange`` -- (default: ``None``) tuple of the horizontal extent ``(xmin, xmax)`` of the bounding box in which to draw the matrix. The image is stretched individually along x and y to fill the box. - If None, the extent is determined by the following conditions. Matrix + If ``None``, the extent is determined by the following conditions. Matrix entries have unit size in data coordinates. Their centers are on integer coordinates, and their center coordinates range from 0 to columns-1 horizontally and from 0 to rows-1 vertically. If the matrix is sparse, this keyword is ignored. - - ``yrange`` -- (default: None) tuple of the vertical extent + - ``yrange`` -- (default: ``None``) tuple of the vertical extent ``(ymin, ymax)`` of the bounding box in which to draw the matrix. See ``xrange`` for details. The following input must all be passed in as named parameters, if default not used: - - ``cmap`` -- a colormap (default: 'Greys'), the name of a predefined - colormap, a list of colors, or an instance of a matplotlib Colormap. + - ``cmap`` -- a colormap (default: ``'Greys'``); the name of a predefined + colormap, a list of colors, or an instance of a matplotlib Colormap The list of predefined color maps can be visualized in `matplotlib's documentation @@ -300,43 +300,44 @@ def matrix_plot(mat, xrange=None, yrange=None, **options): can also type ``import matplotlib.cm; matplotlib.cm.datad.keys()`` to list their names. - - ``colorbar`` -- boolean (default: ``False``) Show a colorbar or not (dense matrices only). + - ``colorbar`` -- boolean (default: ``False``); show a colorbar or not + (dense matrices only) The following options are used to adjust the style and placement of colorbars. They have no effect if a colorbar is not shown. - - ``colorbar_orientation`` -- string (default: 'vertical'), + - ``colorbar_orientation`` -- string (default: ``'vertical'``); controls placement of the colorbar, can be either 'vertical' or 'horizontal' - ``colorbar_format`` -- a format string, this is used to format - the colorbar labels. + the colorbar labels - - ``colorbar_options`` -- a dictionary of options for the matplotlib + - ``colorbar_options`` -- dictionary of options for the matplotlib colorbar API. Documentation for the :mod:`matplotlib.colorbar` module has details. - - ``norm`` -- If None (default), the value range is scaled to the interval + - ``norm`` -- if ``None`` (default), the value range is scaled to the interval [0,1]. If 'value', then the actual value is used with no scaling. A :class:`matplotlib.colors.Normalize` instance may also passed. - - ``vmin`` -- The minimum value (values below this are set to this value) + - ``vmin`` -- the minimum value (values below this are set to this value) - - ``vmax`` -- The maximum value (values above this are set to this value) + - ``vmax`` -- the maximum value (values above this are set to this value) - - ``flip_y`` -- (default: ``True``) boolean. If False, the first row of the + - ``flip_y`` -- boolean (default: ``True``); if ``False``, the first row of the matrix is on the bottom of the graph. Otherwise, the first row is on the top of the graph. - - ``subdivisions`` -- If True, plot the subdivisions of the matrix as lines. + - ``subdivisions`` -- if ``True``, plot the subdivisions of the matrix as lines - - ``subdivision_boundaries`` -- a list of lists in the form + - ``subdivision_boundaries`` -- list of lists in the form ``[row_subdivisions, column_subdivisions]``, which specifies the row and column subdivisions to use. If not specified, defaults to the matrix subdivisions - - ``subdivision_style`` -- a dictionary of properties passed + - ``subdivision_style`` -- dictionary of properties passed on to the :func:`~sage.plot.line.line2d` command for plotting subdivisions. If this is a two-element list or tuple, then it specifies the styles of row and column divisions, respectively. @@ -511,7 +512,7 @@ def matrix_plot(mat, xrange=None, yrange=None, **options): Graphics object consisting of 1 graphics primitive The title position is adjusted upwards if the ``flip_y`` keyword is set - to True (this is the default).:: + to ``True`` (this is the default).:: sage: matrix_plot(identity_matrix(50), title='identity') Graphics object consisting of 1 graphics primitive diff --git a/src/sage/plot/misc.py b/src/sage/plot/misc.py index 5ebe845fe16..b86b52b05f6 100644 --- a/src/sage/plot/misc.py +++ b/src/sage/plot/misc.py @@ -32,18 +32,18 @@ def setup_for_eval_on_grid(funcs, - ``funcs`` -- a function, or a list, tuple, or vector of functions - - ``ranges`` -- a list of ranges. A range can be a 2-tuple of + - ``ranges`` -- list of ranges. A range can be a 2-tuple of numbers specifying the minimum and maximum, or a 3-tuple giving the variable explicitly. - - ``plot_points`` -- a tuple of integers specifying the number of + - ``plot_points`` -- tuple of integers specifying the number of plot points for each range. If a single number is specified, it will be the value for all ranges. This defaults to 2. - - ``return_vars`` -- (default ``False``) If ``True``, return the variables, - in order. + - ``return_vars`` -- (default: ``False``) if ``True``, return the variables, + in order - - ``imaginary_tolerance`` -- (default: ``1e-8``); if an imaginary + - ``imaginary_tolerance`` -- (default: ``1e-8``) if an imaginary number arises (due, for example, to numerical issues), this tolerance specifies how large it has to be in magnitude before we raise an error. In other words, imaginary parts smaller than @@ -51,12 +51,11 @@ def setup_for_eval_on_grid(funcs, OUTPUT: - - ``fast_funcs`` -- if only one function passed, then a fast callable function. If funcs is a list or tuple, then a tuple of fast callable functions is returned. - - ``range_specs`` -- a list of range_specs: for each range, a + - ``range_specs`` -- list of range_specs: for each range, a tuple is returned of the form (range_min, range_max, range_step) such that ``srange(range_min, range_max, range_step, include_endpoint=True)`` gives the correct points @@ -125,7 +124,6 @@ def setup_for_eval_on_grid(funcs, Graphics3d Object sage: streamline_plot(abs(x+i*y), (x,-1,1),(y,-1,1)) Graphics object consisting of 1 graphics primitive - """ if max(map(len, ranges)) > 3: raise ValueError("At least one variable range has more than 3 entries: each should either have 2 or 3 entries, with one of the forms (xmin, xmax) or (x, xmin, xmax)") @@ -233,8 +231,8 @@ def unify_arguments(funcs): INPUT: - - ``funcs`` -- a list of functions; these can be symbolic - expressions, polynomials, etc + - ``funcs`` -- list of functions; these can be symbolic + expressions, polynomials, etc. OUTPUT: functions, expected arguments @@ -327,32 +325,32 @@ def get_matplotlib_linestyle(linestyle, return_type): 'dotted', 'dashdot' ). If linestyle is none of these allowed options, the function raises - a ValueError. + a :exc:`ValueError`. INPUT: - - ``linestyle`` -- The style of the line, which is one of - - ``"-"`` or ``"solid"`` - - ``"--"`` or ``"dashed"`` - - ``"-."`` or ``"dash dot"`` - - ``":"`` or ``"dotted"`` + - ``linestyle`` -- the style of the line, which is one of + - ``'-'`` or ``'solid'`` + - ``'--'`` or ``'dashed'`` + - ``'-.'`` or ``'dash dot'`` + - ``':'`` or ``'dotted'`` - ``"None"`` or ``" "`` or ``""`` (nothing) - The linestyle can also be prefixed with a drawing style (e.g., ``"steps--"``) + The linestyle can also be prefixed with a drawing style (e.g., ``'steps--'``) - - ``"default"`` (connect the points with straight lines) - - ``"steps"`` or ``"steps-pre"`` (step function; horizontal + - ``'default'`` (connect the points with straight lines) + - ``'steps'`` or ``'steps-pre'`` (step function; horizontal line is to the left of point) - - ``"steps-mid"`` (step function; points are in the middle of + - ``'steps-mid'`` (step function; points are in the middle of horizontal lines) - - ``"steps-post"`` (step function; horizontal line is to the + - ``'steps-post'`` (step function; horizontal line is to the right of point) If ``linestyle`` is ``None`` (of type NoneType), then we return it back unmodified. - - ``return_type`` -- The type of linestyle that should be output. This - argument takes only two values - ``"long"`` or ``"short"``. + - ``return_type`` -- the type of linestyle that should be output. This + argument takes only two values - ``'long'`` or ``'short'`` EXAMPLES: @@ -382,9 +380,9 @@ def get_matplotlib_linestyle(linestyle, return_type): sage: get_matplotlib_linestyle(None, 'short') is None True - Linestyles with ``"default"`` or ``"steps"`` in them should also be + Linestyles with ``'default'`` or ``'steps'`` in them should also be properly handled. For instance, matplotlib understands only the short - version when ``"steps"`` is used:: + version when ``'steps'`` is used:: sage: get_matplotlib_linestyle("default", "short") '' @@ -402,7 +400,6 @@ def get_matplotlib_linestyle(linestyle, return_type): linestyle options are: {'solid', 'dashed', 'dotted', dashdot', 'None'}, respectively {'-', '--', ':', '-.', ''} - """ long_to_short_dict = {'solid' : '-','dashed' : '--', 'dotted' : ':', 'dashdot':'-.'} @@ -496,7 +493,6 @@ def __call__(self, *args): sage: fff = FastCallablePlotWrapper(ff, imag_tol=0.1) sage: type(fff(CDF.random_element())) is float True - """ try: return super().__call__(*args) diff --git a/src/sage/plot/multigraphics.py b/src/sage/plot/multigraphics.py index 6be448f1e04..d2f70b44526 100644 --- a/src/sage/plot/multigraphics.py +++ b/src/sage/plot/multigraphics.py @@ -37,7 +37,7 @@ class MultiGraphics(WithEqualityById, SageObject): INPUT: - - ``graphics_list`` -- a list of graphics along with their positions on the + - ``graphics_list`` -- list of graphics along with their positions on the common canvas; each element of ``graphics_list`` is either - a pair ``(graphics, position)``, where ``graphics`` is a @@ -123,7 +123,6 @@ class MultiGraphics(WithEqualityById, SageObject): Graphics object consisting of 1 graphics primitive] sage: len(G) 3 - """ def __init__(self, graphics_list): r""" @@ -164,7 +163,6 @@ def _repr_(self): 'Graphics Array of size 1 x 3' sage: G Graphics Array of size 1 x 3 - """ return str(self) @@ -186,7 +184,6 @@ def _rich_repr_(self, display_manager, **kwds): sage: G = graphics_array([Graphics(), Graphics()], 1, 2) sage: G._rich_repr_(dm) OutputImagePng container - """ types = display_manager.types prefer_raster = ( @@ -214,7 +211,7 @@ def _rich_repr_(self, display_manager, **kwds): def __getitem__(self, i): r""" - Return the ``i``th element of the list of graphics composing ``self``. + Return the ``i``-th element of the list of graphics composing ``self``. EXAMPLES: @@ -232,13 +229,12 @@ def __getitem__(self, i): sage: G = graphics_array(L, 5, 2) sage: G[3] Graphics object consisting of 2 graphics primitives - """ return self._glist[i] def __setitem__(self, i, g): r""" - Set the ``i``th element of the list of graphics composing ``self``. + Set the ``i``-th element of the list of graphics composing ``self``. EXAMPLES:: @@ -253,7 +249,6 @@ def __setitem__(self, i, g): ....: color='purple') sage: G[1] # a circle and some purple points Graphics object consisting of 2 graphics primitives - """ self._glist[i] = g @@ -267,7 +262,6 @@ def __len__(self): sage: G = graphics_array(L, 2, 3) sage: len(G) 6 - """ return len(self._glist) @@ -355,7 +349,6 @@ def matplotlib(self, figure=None, figsize=None, **kwds):
sage: fig2
- """ from matplotlib.figure import Figure glist = self._glist @@ -394,7 +387,7 @@ def save(self, filename, figsize=None, **kwds): INPUT: - - ``filename`` -- (string) the file name; the image format is given by + - ``filename`` -- string; the file name. The image format is given by the extension, which can be one of the following: * ``.eps``, @@ -429,7 +422,6 @@ def save(self, filename, figsize=None, **kwds): sage: graphics_array([]).save(F) sage: graphics_array([[]]).save(F) - """ from matplotlib import rcParams ext = os.path.splitext(filename)[1].lower() @@ -516,7 +508,6 @@ def save_image(self, filename=None, *args, **kwds): ....: for n in range(3)] for m in range(1,3)] sage: G = graphics_array(plots) sage: G.save_image(tmp_filename(ext='.png')) - """ self.save(filename, *args, **kwds) @@ -526,11 +517,9 @@ def _latex_(self, **kwds): INPUT: - All keyword arguments will be passed to the plotter. - - OUTPUT: + - ``**kwds`` -- all keyword arguments will be passed to the plotter - A string of PGF commands to plot ``self`` + OUTPUT: string of PGF commands to plot ``self`` EXAMPLES:: @@ -539,7 +528,6 @@ def _latex_(self, **kwds): '%% Creator: Matplotlib, PGF backend\n%%\n%' The above doctest fails on macOS due to the following Matplotlib issue: https://github.com/matplotlib/matplotlib/issues/10307 - """ tmpfilename = tmp_filename(ext='.pgf') self.save(filename=tmpfilename, **kwds) @@ -617,7 +605,6 @@ def show(self, **kwds): [plot(tan), plot(sec)]]) sphinx_plot(G, axes=False, frame=True, figsize=4, fontsize=8, \ gridlines='major') - """ from sage.repl.rich_output import get_display_manager dm = get_display_manager() @@ -634,7 +621,6 @@ def plot(self): sage: G = multi_graphics([g1, g2]) sage: G.plot() is G True - """ return self @@ -658,9 +644,7 @@ def inset(self, graphics, pos=None, fontsize=None): ``fontsize`` has been explicitly set in the construction of ``graphics`` (in this case, it is not overwritten here) - OUTPUT: - - - instance of :class:`~sage.plot.multigraphics.MultiGraphics` + OUTPUT: instance of :class:`~sage.plot.multigraphics.MultiGraphics` EXAMPLES: @@ -698,7 +682,6 @@ def inset(self, graphics, pos=None, fontsize=None): G = graphics_array([plot(sin, (0, 2*pi)), plot(cos, (0, 2*pi))]) c = circle((0,0), 1, color='red', thickness=2, frame=True) sphinx_plot(G.inset(c, pos=(0.3, 0.7, 0.2, 0.2), fontsize=8)) - """ if pos is None: pos = (0.7, 0.7, 0.2, 0.2) @@ -718,7 +701,7 @@ def inset(self, graphics, pos=None, fontsize=None): # def __str__(self): r""" - String representation of ``self`` + String representation of ``self``. EXAMPLES:: @@ -735,7 +718,6 @@ def __str__(self): sage: G = MultiGraphics([c, c, c]) sage: str(G) 'Multigraphics with 3 elements' - """ n = len(self._glist) if n <= 1: @@ -756,9 +738,7 @@ def _add_subplot(self, figure, index, **options): - ``index`` -- integer specifiying the element of ``self`` - ``options`` -- extra options to be passed to ``Figure.add_axes`` - OUTPUT: - - - a Matplotlib ``Axes`` object + OUTPUT: a Matplotlib ``Axes`` object EXAMPLES:: @@ -789,7 +769,6 @@ def _add_subplot(self, figure, index, **options): ....: numpy.set_printoptions(legacy="1.25") sage: ax1.get_position().bounds # tol 1.0e-13 (0.2, 0.3, 0.4000000000000001, 0.10000000000000003) - """ # Note: using label=str(index) ensures that a new Axes is generated # for each element of ``self``, even if some elements share the same @@ -821,7 +800,6 @@ def position(self, index): (0.125, 0.11, 0.775, 0.77) sage: G.position(1) # tol 1.0e-13 (0.15, 0.2, 0.1, 0.15) - """ return self._positions[index] @@ -906,7 +884,6 @@ def append(self, graphics, pos=None): .. SEEALSO:: :meth:`inset` - """ from matplotlib import rcParams if not isinstance(graphics, Graphics): @@ -1084,7 +1061,6 @@ class GraphicsArray(MultiGraphics): G = graphics_array([[g1, g2], [g3, g4]]) G[0] = g4 sphinx_plot(G) - """ def __init__(self, array): r""" @@ -1138,7 +1114,6 @@ def __init__(self, array): Traceback (most recent call last): ... TypeError: every element of array must be a Graphics object - """ MultiGraphics.__init__(self, []) if not isinstance(array, (list, tuple)): @@ -1178,7 +1153,6 @@ def __str__(self): 'Graphics Array of size 2 x 3' sage: str(G) 'Graphics Array of size 2 x 3' - """ return f"Graphics Array of size {self._rows} x {self._cols}" @@ -1196,9 +1170,7 @@ def _add_subplot(self, figure, index, **options): - ``index`` -- integer specifiying the element of ``self`` - ``options`` -- extra options to be passed to ``Figure.add_subplot`` - OUTPUT: - - - a Matplotlib ``Axes`` object + OUTPUT: a Matplotlib ``Axes`` object EXAMPLES:: @@ -1212,7 +1184,6 @@ def _add_subplot(self, figure, index, **options): sage: ax2 = G._add_subplot(fig, 1) sage: fig.get_axes() == [ax1, ax2] True - """ if self._rows == 0 or self._cols == 0: rows = 1 @@ -1236,7 +1207,6 @@ def nrows(self): 2 sage: graphics_array(L).nrows() 1 - """ return self._rows @@ -1272,7 +1242,6 @@ def append(self, g): ... NotImplementedError: Appending to a graphics array is not yet implemented - """ # Not clear if there is a way to do this raise NotImplementedError('Appending to a graphics array is not ' @@ -1311,7 +1280,6 @@ def position(self, index): 0.20212705964722733, 0.4489880779745068, 0.5986507706326758) - """ if not self._positions: # self._positions must be generated, by invoking get_position() on diff --git a/src/sage/plot/plot.py b/src/sage/plot/plot.py index 5184374756e..d1e21abe20a 100644 --- a/src/sage/plot/plot.py +++ b/src/sage/plot/plot.py @@ -7,7 +7,7 @@ The following graphics primitives are supported: -- :func:`~sage.plot.arrow.arrow` -- an arrow from a min point to a max point. +- :func:`~sage.plot.arrow.arrow` -- an arrow from a min point to a max point - :func:`~sage.plot.circle.circle` -- a circle with given radius @@ -30,7 +30,7 @@ The following plotting functions are supported: - :func:`plot` -- plot of a function or other Sage object (e.g., elliptic - curve). + curve) - :func:`parametric_plot` @@ -419,14 +419,14 @@ def y(x): return x*sin(x**2) Pi Axis:: sage: g1 = plot(sin(x), 0, 2*pi) - sage: g2 = plot(cos(x), 0, 2*pi, linestyle="--") + sage: g2 = plot(cos(x), 0, 2*pi, linestyle='--') sage: (g1 + g2).show(ticks=pi/6, # show their sum, nicely formatted # long time ....: tick_formatter=pi) .. PLOT:: g1 = plot(sin(x), 0, 2*pi, ticks=pi/6, tick_formatter=pi) - g2 = plot(cos(x), 0, 2*pi, linestyle="--", ticks=pi/6, tick_formatter=pi) + g2 = plot(cos(x), 0, 2*pi, linestyle='--', ticks=pi/6, tick_formatter=pi) sphinx_plot(g1+g2) An illustration of integration:: @@ -477,10 +477,10 @@ def f(x): return (x-3)*(x-5)*(x-7)+40 sage: t = plt.title('About as simple as it gets, folks') sage: plt.grid(True) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f1: + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f1: ....: plt.savefig(f1.name) sage: plt.clf() - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f2: + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f2: ....: plt.savefig(f2.name) sage: plt.close() sage: plt.imshow([[1,2],[0,1]]) @@ -494,7 +494,7 @@ def f(x): return (x-3)*(x-5)*(x-7)+40 sage: plt.imshow([[(0.0,0.0,0.0)]]) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: ....: plt.savefig(f.name) Since the above overwrites many Sage plotting functions, we reset @@ -698,9 +698,8 @@ def SelectiveFormatter(formatter, skip_values): ....: skip_values=[0,1]) sage: ax.xaxis.set_major_formatter(formatter) sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".png") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.png') as f: ....: fig.savefig(f.name) - """ global _SelectiveFormatterClass if _SelectiveFormatterClass is None: @@ -714,9 +713,9 @@ def __init__(self, formatter, skip_values): INPUT: - - formatter -- the formatter object to which we should pass labels + - ``formatter`` -- the formatter object to which we should pass labels - - skip_values -- a list of values that we should skip when + - ``skip_values`` -- list of values that we should skip when formatting the tick labels EXAMPLES:: @@ -734,7 +733,7 @@ def __init__(self, formatter, skip_values): ....: skip_values=[0,1]) sage: ax.xaxis.set_major_formatter(formatter) sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(suffix=".png") as f: + sage: with NamedTemporaryFile(suffix='.png') as f: ....: fig.savefig(f.name) """ self.formatter = formatter @@ -756,7 +755,7 @@ def set_locs(self, locs): def __call__(self, x, *args, **kwds): """ - Return the format for tick val *x* at position *pos* + Return the format for tick val *x* at position *pos*. EXAMPLES:: @@ -847,7 +846,7 @@ def xydata_from_point_list(points): aspect_ratio='automatic', imaginary_tolerance=1e-8) def plot(funcs, *args, **kwds): r""" - Use plot by writing + Use plot by writing. ``plot(X, ...)`` @@ -868,40 +867,40 @@ def plot(funcs, *args, **kwds): PLOT OPTIONS: - - ``plot_points`` -- (default: `200`); the minimal number of plot points. + - ``plot_points`` -- (default: 200) the minimal number of plot points - - ``adaptive_recursion`` -- (default: `5`); how many levels of recursion to go + - ``adaptive_recursion`` -- (default: 5) how many levels of recursion to go before giving up when doing adaptive refinement. Setting this to 0 disables adaptive refinement. - - ``adaptive_tolerance`` -- (default: `0.01`); how large a difference should be + - ``adaptive_tolerance`` -- (default: 0.01) how large a difference should be before the adaptive refinement code considers it significant. See the documentation further below for more information, starting at "the algorithm used to insert". - - ``imaginary_tolerance`` -- (default: ``1e-8``); if an imaginary + - ``imaginary_tolerance`` -- (default: ``1e-8``) if an imaginary number arises (due, for example, to numerical issues), this tolerance specifies how large it has to be in magnitude before we raise an error. In other words, imaginary parts smaller than this are ignored in your plot points. - - ``base`` -- (default: `10`); the base of the logarithm if + - ``base`` -- (default: `10`) the base of the logarithm if a logarithmic scale is set. This must be greater than 1. The base can be also given as a list or tuple ``(basex, basey)``. ``basex`` sets the base of the logarithm along the horizontal axis and ``basey`` sets the base along the vertical axis. - - ``scale`` -- string (default: ``"linear"``); scale of the axes. - Possible values are ``"linear"``, ``"loglog"``, ``"semilogx"``, - ``"semilogy"``. + - ``scale`` -- string (default: ``'linear'``); scale of the axes. + Possible values are ``'linear'``, ``'loglog'``, ``'semilogx'``, + ``'semilogy'``. The scale can be also be given as single argument that is a list or tuple ``(scale, base)`` or ``(scale, basex, basey)``. - The ``"loglog"`` scale sets both the horizontal and vertical axes to - logarithmic scale. The ``"semilogx"`` scale sets the horizontal axis - to logarithmic scale. The ``"semilogy"`` scale sets the vertical axis - to logarithmic scale. The ``"linear"`` scale is the default value + The ``'loglog'`` scale sets both the horizontal and vertical axes to + logarithmic scale. The ``'semilogx'`` scale sets the horizontal axis + to logarithmic scale. The ``'semilogy'`` scale sets the vertical axis + to logarithmic scale. The ``'linear'`` scale is the default value when :class:`~sage.plot.graphics.Graphics` is initialized. - ``xmin`` -- starting x value in the rendered figure. This parameter is @@ -916,7 +915,7 @@ def plot(funcs, *args, **kwds): - ``ymax`` -- ending y value in the rendered figure. This parameter is passed directly to the ``show`` procedure and it could be overwritten. - - ``detect_poles`` -- (default: ``False``) If set to ``True`` poles are detected. + - ``detect_poles`` -- boolean (default: ``False``); if set to ``True`` poles are detected. If set to "show" vertical asymptotes are drawn. - ``legend_label`` -- a (TeX) string serving as the label for `X` in the legend. @@ -925,7 +924,7 @@ def plot(funcs, *args, **kwds): .. NOTE:: - - If the ``scale`` is ``"linear"``, then irrespective of what + - If the ``scale`` is ``'linear'``, then irrespective of what ``base`` is set to, it will default to 10 and will remain unused. - If you want to limit the plot along the horizontal axis in the @@ -951,11 +950,11 @@ def plot(funcs, *args, **kwds): COLOR OPTIONS: - - ``color`` -- (Default: 'blue') One of: + - ``color`` -- (default: ``'blue'``) one of: - an RGB tuple (r,g,b) with each of r,g,b between 0 and 1. - - a color name as a string (e.g., 'purple'). + - a color name as a string (e.g., ``'purple'``). - an HTML color such as '#aaff0b'. @@ -963,14 +962,14 @@ def plot(funcs, *args, **kwds): if a dictionary, keys are taken from ``range(len(X))``; the entries/values of the list/dictionary may be any of the options above. - - 'automatic' -- maps to default ('blue') if `X` is a single Sage object; and - maps to a fixed sequence of regularly spaced colors if `X` is a list. + - ``'automatic'`` -- maps to default ('blue') if `X` is a single Sage object; and + maps to a fixed sequence of regularly spaced colors if `X` is a list - ``legend_color`` -- the color of the text for `X` (or each item in `X`) in the legend. - Default color is 'black'. Options are as in ``color`` above, except that the choice 'automatic' maps to 'black' if `X` is a single Sage object. + Default color is 'black'. Options are as in ``color`` above, except that the choice 'automatic' maps to 'black' if `X` is a single Sage object - - ``fillcolor`` -- The color of the fill for the plot of `X` (or each item in `X`). - Default color is 'gray' if `X` is a single Sage object or if ``color`` is a single color. Otherwise, options are as in ``color`` above. + - ``fillcolor`` -- the color of the fill for the plot of `X` (or each item in `X`). + Default color is 'gray' if `X` is a single Sage object or if ``color`` is a single color. Otherwise, options are as in ``color`` above APPEARANCE OPTIONS: @@ -992,30 +991,30 @@ def plot(funcs, *args, **kwds): Any MATPLOTLIB line option may also be passed in. E.g., - - ``linestyle`` -- (default: "-") The style of the line, which is one of + - ``linestyle`` -- (default: ``'-'``) the style of the line, which is one of - - ``"-"`` or ``"solid"`` - - ``"--"`` or ``"dashed"`` - - ``"-."`` or ``"dash dot"`` - - ``":"`` or ``"dotted"`` + - ``'-'`` or ``'solid'`` + - ``'--'`` or ``'dashed'`` + - ``'-.'`` or ``'dash dot'`` + - ``':'`` or ``'dotted'`` - ``"None"`` or ``" "`` or ``""`` (nothing) - a list or dictionary (see below) - The linestyle can also be prefixed with a drawing style (e.g., ``"steps--"``) + The linestyle can also be prefixed with a drawing style (e.g., ``'steps--'``) - - ``"default"`` (connect the points with straight lines) - - ``"steps"`` or ``"steps-pre"`` (step function; horizontal + - ``'default'`` (connect the points with straight lines) + - ``'steps'`` or ``'steps-pre'`` (step function; horizontal line is to the left of point) - - ``"steps-mid"`` (step function; points are in the middle of + - ``'steps-mid'`` (step function; points are in the middle of horizontal lines) - - ``"steps-post"`` (step function; horizontal line is to the + - ``'steps-post'`` (step function; horizontal line is to the right of point) If `X` is a list, then ``linestyle`` may be a list (with entries taken from the strings above) or a dictionary (with keys in ``range(len(X))`` and values taken from the strings above). - - ``marker`` -- The style of the markers, which is one of + - ``marker`` -- the style of the markers, which is one of - ``"None"`` or ``" "`` or ``""`` (nothing) -- default - ``","`` (pixel), ``"."`` (point) @@ -1042,12 +1041,12 @@ def plot(funcs, *args, **kwds): - ``markeredgewidth`` -- the size of the marker edge in points - - ``exclude`` -- (Default: None) values which are excluded from the plot range. + - ``exclude`` -- (default: ``None``) values which are excluded from the plot range. Either a list of real numbers, or an equation in one variable. FILLING OPTIONS: - - ``fill`` -- (default: ``False``) One of: + - ``fill`` -- boolean (default: ``False``); one of: - "axis" or ``True``: Fill the area between the function and the x-axis. @@ -1066,12 +1065,12 @@ def plot(funcs, *args, **kwds): the j-th function in the list. (But if ``d[i] == j``: Fill the area between the i-th function in the list and the horizontal line y = j.) - - ``fillalpha`` -- (default: `0.5`) How transparent the fill is. - A number between 0 and 1. + - ``fillalpha`` -- (default: 0.5) how transparent the fill is; + a number between 0 and 1 MATPLOTLIB STYLE SHEET OPTION: - - ``stylesheet`` -- (Default: classic) Support for loading a full matplotlib style sheet. + - ``stylesheet`` -- (default: classic) support for loading a full matplotlib style sheet. Any style sheet listed in ``matplotlib.pyplot.style.available`` is acceptable. If a non-existing style is provided the default classic is applied. @@ -1774,12 +1773,12 @@ def b(n): return lambda x: bessel_J(n, x) + 0.5*(n-1) sage: plot(2*x + 1, (x, 0, 5), ....: ticks=[[0, 1, e, pi, sqrt(20)], ....: [1, 3, 2*e + 1, 2*pi + 1, 2*sqrt(20) + 1]], - ....: tick_formatter="latex") + ....: tick_formatter='latex') Graphics object consisting of 1 graphics primitive .. PLOT:: - g = plot(2*x + 1, (x, 0, 5), ticks=[[0, 1, e, pi, sqrt(20)], [1, 3, 2*e + 1, 2*pi + 1, 2*sqrt(20) + 1]], tick_formatter="latex") + g = plot(2*x + 1, (x, 0, 5), ticks=[[0, 1, e, pi, sqrt(20)], [1, 3, 2*e + 1, 2*pi + 1, 2*sqrt(20) + 1]], tick_formatter='latex') sphinx_plot(g) This is particularly useful when setting custom ticks in multiples of `\pi`. @@ -2097,7 +2096,7 @@ def _plot(funcs, xrange, parametric=False, The following option is deprecated in favor of ``legend_label``: - - ``label`` -- (default: '') a string for the label + - ``label`` -- (default: ``''``) a string for the label All other usual plot options are also accepted, and a number are required (see the example below) which are normally passed @@ -2150,7 +2149,7 @@ def _plot(funcs, xrange, parametric=False, Make sure that we don't get multiple legend labels for plot segments (:issue:`11998`):: - sage: p1 = plot(1/(x^2-1),(x,-2,2),legend_label="foo",detect_poles=True) + sage: p1 = plot(1/(x^2-1),(x,-2,2),legend_label='foo',detect_poles=True) sage: len(p1.matplotlib().axes[0].legend().texts) 1 sage: p1.show(ymin=-10,ymax=10) # should be one legend @@ -2165,7 +2164,6 @@ def _plot(funcs, xrange, parametric=False, sage: plot(x, -1, 1, detect_poles=True) Graphics object consisting of 1 graphics primitive - """ from sage.plot.colors import Color from sage.plot.misc import setup_for_eval_on_grid @@ -2569,9 +2567,9 @@ def parametric_plot(funcs, *args, **kwargs): INPUT: - - ``funcs`` -- 2 or 3-tuple of functions, or a vector of dimension 2 or 3. + - ``funcs`` -- 2 or 3-tuple of functions, or a vector of dimension 2 or 3 - - ``other options`` -- passed to :func:`plot` or :func:`~sage.plot.plot3d.parametric_plot3d.parametric_plot3d` + - ``other options`` -- passed to :func:`plot` or :func:`~sage.plot.plot3d.parametric_plot3d.parametric_plot3d` EXAMPLES: We draw some 2d parametric plots. Note that the default aspect ratio is 1, so that circles look like circles. :: @@ -2635,13 +2633,13 @@ def parametric_plot(funcs, *args, **kwargs): :: sage: parametric_plot((5*cos(x), 5*sin(x), x), (x, -12, 12), # long time - ....: plot_points=150, color="red") + ....: plot_points=150, color='red') Graphics3d Object .. PLOT:: #AttributeError: 'Line' object has no attribute 'plot' - #g = parametric_plot( (5*cos(x), 5*sin(x), x), (x,-12, 12), plot_points=150, color="red") # long time + #g = parametric_plot( (5*cos(x), 5*sin(x), x), (x,-12, 12), plot_points=150, color='red') # long time #sphinx_plot(g) :: @@ -2865,7 +2863,6 @@ def polar_plot(funcs, *args, **kwds): g = polar_plot(log(floor(x)), (x, 1, 4*pi), exclude=list(range(1,13))) sphinx_plot(g) - """ kwds['polar'] = True return plot(funcs, *args, **kwds) @@ -3170,12 +3167,12 @@ def plot_loglog(funcs, *args, **kwds): INPUT: - - ``base`` -- (default: `10`); the base of the logarithm. This must be + - ``base`` -- (default: `10`) the base of the logarithm; this must be greater than 1. The base can be also given as a list or tuple ``(basex, basey)``. ``basex`` sets the base of the logarithm along the horizontal axis and ``basey`` sets the base along the vertical axis. - - ``funcs`` -- any Sage object which is acceptable to the :func:`plot`. + - ``funcs`` -- any Sage object which is acceptable to the :func:`plot` For all other inputs, look at the documentation of :func:`plot`. @@ -3208,7 +3205,6 @@ def plot_loglog(funcs, *args, **kwds): g = plot_loglog(exp, (1,10), base=(2,3)) sphinx_plot(g) - """ return plot(funcs, *args, scale='loglog', **kwds) @@ -3221,10 +3217,10 @@ def plot_semilogx(funcs, *args, **kwds): INPUT: - - ``base`` -- (default: `10`); the base of the logarithm. This must be - greater than 1. + - ``base`` -- (default: `10`) the base of the logarithm; this must be + greater than 1 - - ``funcs`` -- any Sage object which is acceptable to the :func:`plot`. + - ``funcs`` -- any Sage object which is acceptable to the :func:`plot` For all other inputs, look at the documentation of :func:`plot`. @@ -3261,7 +3257,6 @@ def plot_semilogx(funcs, *args, **kwds): f = 4000000/(4000000 + 4000*s*i - s*s) g = plot_semilogx(20*log(abs(f), 10), (s, 1, 1e6)) sphinx_plot(g) - """ return plot(funcs, *args, scale='semilogx', **kwds) @@ -3274,10 +3269,10 @@ def plot_semilogy(funcs, *args, **kwds): INPUT: - - ``base`` -- (default: `10`); the base of the logarithm. This must be - greater than 1. + - ``base`` -- (default: `10`) the base of the logarithm; this must be + greater than 1 - - ``funcs`` -- any Sage object which is acceptable to the :func:`plot`. + - ``funcs`` -- any Sage object which is acceptable to the :func:`plot` For all other inputs, look at the documentation of :func:`plot`. @@ -3300,7 +3295,6 @@ def plot_semilogy(funcs, *args, **kwds): g = plot_semilogy(exp, (1,10), base=2) # long time # with base 2 sphinx_plot(g) - """ return plot(funcs, *args, scale='semilogy', **kwds) @@ -3313,7 +3307,7 @@ def list_plot_loglog(data, plotjoined=False, **kwds): INPUT: - - ``base`` -- (default: `10`); the base of the logarithm. This must be + - ``base`` -- (default: `10`) the base of the logarithm; this must be greater than 1. The base can be also given as a list or tuple ``(basex, basey)``. ``basex`` sets the base of the logarithm along the horizontal axis and ``basey`` sets the base along the vertical axis. @@ -3368,7 +3362,6 @@ def list_plot_loglog(data, plotjoined=False, **kwds): sage: list_plot_loglog(list(zip(range(1,len(yl)), yl[1:]))) Graphics object consisting of 1 graphics primitive - """ return list_plot(data, plotjoined=plotjoined, scale='loglog', **kwds) @@ -3381,8 +3374,8 @@ def list_plot_semilogx(data, plotjoined=False, **kwds): INPUT: - - ``base`` -- (default: `10`); the base of the logarithm. This must be - greater than 1. + - ``base`` -- (default: `10`) the base of the logarithm; this must be + greater than 1 For all other inputs, look at the documentation of :func:`list_plot`. @@ -3424,7 +3417,6 @@ def list_plot_semilogx(data, plotjoined=False, **kwds): g = list_plot_semilogx([(1,2),(3,4),(3,-1),(25,3)], base=2) sphinx_plot(g) - """ return list_plot(data, plotjoined=plotjoined, scale='semilogx', **kwds) @@ -3437,8 +3429,8 @@ def list_plot_semilogy(data, plotjoined=False, **kwds): INPUT: - - ``base`` -- (default: `10`); the base of the logarithm. This must be - greater than 1. + - ``base`` -- (default: `10`) the base of the logarithm; this must be + greater than 1 For all other inputs, look at the documentation of :func:`list_plot`. @@ -3483,7 +3475,6 @@ def list_plot_semilogy(data, plotjoined=False, **kwds): g = list_plot_semilogy([2, 4, 6, 8, 16, 31], base=2) sphinx_plot(g) - """ return list_plot(data, plotjoined=plotjoined, scale='semilogy', **kwds) @@ -3512,11 +3503,11 @@ def reshape(v, n, m): INPUT: - - ``v`` -- a list of lists or tuples + - ``v`` -- list of lists or tuples - - ``n, m`` -- integers + - ``n``, ``m`` -- integers - OUTPUT: a list of lists of graphics objects + OUTPUT: list of lists of graphics objects EXAMPLES:: @@ -3709,7 +3700,6 @@ def h(x): return sin(4*x) .. SEEALSO:: :class:`~sage.plot.multigraphics.GraphicsArray` for more examples - """ # TODO: refactor the whole array flattening and reshaping into a class if nrows is None and ncols is None: @@ -3749,7 +3739,7 @@ def multi_graphics(graphics_list): INPUT: - - ``graphics_list`` -- a list of graphics along with their + - ``graphics_list`` -- list of graphics along with their positions on the canvas; each element of ``graphics_list`` is either - a pair ``(graphics, position)``, where ``graphics`` is a @@ -3810,7 +3800,6 @@ def multi_graphics(graphics_list): .. SEEALSO:: :class:`~sage.plot.multigraphics.MultiGraphics` for more examples - """ return MultiGraphics(graphics_list) @@ -3863,17 +3852,17 @@ def adaptive_refinement(f, p1, p2, adaptive_tolerance=0.01, - ``p1``, ``p2`` -- two points to refine between - - ``adaptive_recursion`` -- (default: `5`); how many + - ``adaptive_recursion`` -- (default: `5`) how many levels of recursion to go before giving up when doing adaptive refinement. Setting this to 0 disables adaptive refinement. - - ``adaptive_tolerance`` -- (default: `0.01`); how large + - ``adaptive_tolerance`` -- (default: `0.01`) how large a relative difference should be before the adaptive refinement code considers it significant; see documentation for generate_plot_points for more information. See the documentation for :func:`plot` for more information on how the adaptive refinement algorithm works. - - ``excluded`` -- (default: ``False``); also return locations where it has been + - ``excluded`` -- (default: ``False``) also return locations where it has been discovered that the function is not defined (y-value will be ``'NaN'`` in this case) @@ -3977,26 +3966,26 @@ def generate_plot_points(f, xrange, plot_points=5, adaptive_tolerance=0.01, - ``p1``, ``p2`` -- two points to refine between - - ``plot_points`` -- (default: `5`); the minimal number of plot points. (Note + - ``plot_points`` -- (default: 5) the minimal number of plot points. (Note however that in any actual plot a number is passed to this, with default value 200.) - - ``adaptive_recursion`` -- (default: `5`); how many levels of recursion to go + - ``adaptive_recursion`` -- (default: 5) how many levels of recursion to go before giving up when doing adaptive refinement. Setting this to 0 disables adaptive refinement. - - ``adaptive_tolerance`` -- (default: `0.01`); how large the relative difference + - ``adaptive_tolerance`` -- (default: 0.01) how large the relative difference should be before the adaptive refinement code considers it significant. If the actual difference is greater than adaptive_tolerance*delta, where delta is the initial subinterval size for the given xrange and plot_points, then the algorithm will consider it significant. - - ``initial_points`` -- (default: ``None``); a list of x-values that should be evaluated. + - ``initial_points`` -- (default: ``None``) a list of x-values that should be evaluated - - ``excluded`` -- (default: ``False``); add a list of discovered x-values, for + - ``excluded`` -- (default: ``False``) add a list of discovered x-values, for which ``f`` is not defined - - ``imaginary_tolerance`` -- (default: ``1e-8``); if an imaginary + - ``imaginary_tolerance`` -- (default: ``1e-8``) if an imaginary number arises (due, for example, to numerical issues), this tolerance specifies how large it has to be in magnitude before we raise an error. In other words, imaginary parts smaller than diff --git a/src/sage/plot/plot3d/base.pyx b/src/sage/plot/plot3d/base.pyx index 4c09ea7e7c7..9075d31d571 100644 --- a/src/sage/plot/plot3d/base.pyx +++ b/src/sage/plot/plot3d/base.pyx @@ -84,7 +84,7 @@ cdef class Graphics3d(SageObject): """ def __cinit__(self): """ - The Cython constructor + The Cython constructor. EXAMPLES:: @@ -108,9 +108,7 @@ cdef class Graphics3d(SageObject): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -122,7 +120,7 @@ cdef class Graphics3d(SageObject): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -133,7 +131,6 @@ cdef class Graphics3d(SageObject): sage: g = sphere() sage: g._rich_repr_(dm) # OutputSceneThreejs container outside doctest mode OutputSceneJmol container - """ ### First, figure out the best graphics format types = display_manager.types @@ -191,8 +188,8 @@ cdef class Graphics3d(SageObject): the rendered image (can be png, gif, or jpg). Determines the type of the output. - - ``**kwds`` -- Optional keyword arguments are passed to the - Tachyon raytracer. + - ``**kwds`` -- optional keyword arguments are passed to the + Tachyon raytracer OUTPUT: @@ -245,11 +242,11 @@ cdef class Graphics3d(SageObject): def _rich_repr_jmol(self, **kwds): """ - Rich Representation as JMol scene + Rich Representation as JMol scene. INPUT: - Optional keyword arguments are passed to JMol. + - ``**kwds`` -- optional keyword arguments are passed to JMol OUTPUT: @@ -288,7 +285,7 @@ cdef class Graphics3d(SageObject): script = '''set defaultdirectory "{0}"\nscript SCRIPT\n'''.format(scene_native) jdata.export_image(targetfile=preview_png, datafile=script, - image_type="PNG", + image_type='PNG', figsize=opts['figsize'][0]) from sage.repl.rich_output.output_graphics3d import OutputSceneJmol from sage.repl.rich_output.buffer import OutputBuffer @@ -298,11 +295,11 @@ cdef class Graphics3d(SageObject): def _rich_repr_wavefront(self, **kwds): r""" - Rich Representation as Wavefront (obj + mtl) Scene + Rich Representation as Wavefront (obj + mtl) Scene. INPUT: - Optional keyword arguments are ignored. + - ``**kwds`` -- optional keyword arguments are ignored OUTPUT: @@ -327,11 +324,11 @@ cdef class Graphics3d(SageObject): def _rich_repr_canvas3d(self, **kwds): r""" - Rich Representation as Canvas3D Scene + Rich Representation as Canvas3D Scene. INPUT: - Optional keyword arguments. + - ``**kwds`` -- optional keyword arguments OUTPUT: @@ -360,11 +357,11 @@ cdef class Graphics3d(SageObject): def _rich_repr_threejs(self, **kwds): r""" - Rich Representation as Three.js Scene + Rich Representation as Three.js Scene. INPUT: - Optional keyword arguments. + - ``**kwds`` -- optional keyword arguments OUTPUT: @@ -440,7 +437,6 @@ cdef class Graphics3d(SageObject): sage: str = d._rich_repr_threejs(online=True).html.get_str() sage: '"Page" & <Title>' in str True - """ options = self._process_viewing_options(kwds) options.setdefault('online', False) @@ -927,7 +923,7 @@ cdef class Graphics3d(SageObject): """ params = RenderParams(ds=.075) - fn = tmp_filename(ext=".zip") + fn = tmp_filename(ext='.zip') params.output_archive = zipfile.ZipFile(fn, 'w', zipfile.ZIP_STORED, True) return params @@ -968,7 +964,6 @@ cdef class Graphics3d(SageObject): - """ return """ @@ -1162,7 +1157,7 @@ end_scene""".format( @staticmethod def _tostring(s): r""" - Converts vector information to a space-separated string. + Convert vector information to a space-separated string. EXAMPLES:: @@ -1184,7 +1179,7 @@ end_scene""".format( EXAMPLES:: - sage: out_file = tmp_filename(ext=".jmol") + sage: out_file = tmp_filename(ext='.jmol') sage: G = sphere((1, 2, 3), 5) + cube() + sage.plot.plot3d.shapes.Text("hi") sage: G.export_jmol(out_file) sage: import zipfile @@ -1389,7 +1384,6 @@ end_scene""".format( sage: G = sage.plot.plot3d.base.Graphics3d() sage: G.threejs_repr(G.default_render_params()) [] - """ return [] @@ -1556,11 +1550,11 @@ end_scene""".format( # draw axes from sage.plot.plot3d.shapes import arrow3d A = (arrow3d((min(0,a_min[0]),0, 0), (max(0,a_max[0]), 0,0), - thickness, color="blue"), + thickness, color='blue'), arrow3d((0,min(0,a_min[1]), 0), (0, max(0,a_max[1]), 0), - thickness, color="blue"), + thickness, color='blue'), arrow3d((0, 0, min(0,a_min[2])), (0, 0, max(0,a_max[2])), - thickness, color="blue")) + thickness, color='blue')) X += sum(A).translate([-z for z in T]) return X @@ -1626,7 +1620,7 @@ end_scene""".format( def show(self, **kwds): r""" - Display graphics immediately + Display graphics immediately. This method attempts to display the graphics immediately, without waiting for the currently running code (if any) to @@ -1636,8 +1630,8 @@ end_scene""".format( INPUT: - - ``viewer`` -- string (default: ``'threejs'``), how to view the plot; - admissible values are + - ``viewer`` -- string (default: ``'threejs'``); how to view the plot. + Admissible values are * ``'threejs'``: interactive web-based 3D viewer using JavaScript and a WebGL renderer @@ -1651,52 +1645,52 @@ end_scene""".format( * ``'canvas3d'``: web-based 3D viewer using JavaScript and a canvas renderer (Sage notebook only) - - ``verbosity`` -- display information about rendering - the figure + - ``verbosity`` -- display information about rendering + the figure - - ``figsize`` -- (default: 5); x or pair [x,y] for - numbers, e.g., [5,5]; controls the size of the output figure. - With 'tachyon', the resolution (in number of pixels) is 100 times - ``figsize``. This is ignored for the jmol embedded renderer. + - ``figsize`` -- (default: 5) x or pair [x,y] for + numbers, e.g., [5,5]; controls the size of the output figure. + With 'tachyon', the resolution (in number of pixels) is 100 times + ``figsize``. This is ignored for the jmol embedded renderer. - - ``aspect_ratio`` -- (default: ``'automatic'``) -- aspect - ratio of the coordinate system itself. Give [1,1,1] or 1 to make spheres - look round. + - ``aspect_ratio`` -- (default: ``'automatic'``) aspect + ratio of the coordinate system itself; give [1,1,1] or 1 to make + spheres look round - - ``frame_aspect_ratio`` -- (default: ``'automatic'``) - aspect ratio of frame that contains the 3d scene. + - ``frame_aspect_ratio`` -- (default: ``'automatic'``) + aspect ratio of frame that contains the 3d scene - - ``zoom`` -- (default: 1) how zoomed in + - ``zoom`` -- (default: 1) how zoomed in - - ``frame`` -- (default: ``True``) if True, draw a - bounding frame with labels + - ``frame`` -- boolean (default: ``True``); if ``True``, draw a + bounding frame with labels - - ``axes`` -- (default: ``False``) if True, draw coordinate - axes + - ``axes`` -- boolean (default: ``False``); if ``True``, draw coordinate + axes - - ``camera_position`` (for tachyon) -- (default: (2.3, 2.4, 2.0)) - the viewpoint, with respect to the cube - $[-1,1]\\times[-1,1]\\times[-1,1]$, - into which the bounding box of the scene - is scaled and centered. - The default viewing direction is towards the origin. + - ``camera_position`` -- (for tachyon) (default: (2.3, 2.4, 2.0)) + the viewpoint, with respect to the cube + $[-1,1]\\times[-1,1]\\times[-1,1]$, + into which the bounding box of the scene + is scaled and centered. + The default viewing direction is towards the origin. - - ``viewdir`` (for tachyon) -- (default: None) three coordinates - specifying the viewing direction. + - ``viewdir`` -- (for tachyon) (default: ``None``) three coordinates + specifying the viewing direction - - ``updir`` (for tachyon) -- (default: (0,0,1)) the "upward" - direction of the camera + - ``updir`` -- (for tachyon) (default: (0,0,1)) the "upward" + direction of the camera - - ``light_position`` (for tachyon) -- (default: (4,3,2)) the position - of the single light source in the scene (in addition to ambient light) + - ``light_position`` -- (for tachyon) (default: (4,3,2)) the position + of the single light source in the scene (in addition to ambient light) - - ``antialiasing`` (for tachyon) -- (default: ``False``) + - ``antialiasing`` -- (for tachyon) (default: ``False``) - - ``raydepth`` (for tachyon) -- (default: 8) - see the :class:`sage.plot.plot3d.tachyon.Tachyon` class + - ``raydepth`` -- (for tachyon) (default: 8) + see the :class:`sage.plot.plot3d.tachyon.Tachyon` class - - ``shade`` (for tachyon) -- string (default: ``'full'``); - shading options. Admissible values are + - ``shade`` -- (for tachyon) string (default: ``'full'``); + shading options. Admissible values are * ``'full'``: best quality rendering (and slowest). Sets tachyon command line flag ``-fullshade``. @@ -1710,11 +1704,11 @@ end_scene""".format( * ``'lowest'``: worst quality rendering, preview (and fastest). Sets tachyon command line flag ``-lowestshade``. - - ``extra_opts`` (for tachyon) -- string (default: empty string); - extra options that will be appended to the tachyon command line. + - ``extra_opts`` -- (for tachyon) string (default: empty string); + extra options that will be appended to the tachyon command line - - ``**kwds`` -- other options, which make sense for particular - rendering engines + - ``**kwds`` -- other options, which make sense for particular + rendering engines OUTPUT: @@ -1729,11 +1723,11 @@ end_scene""".format( If this is not desired, one can set ``aspect_ratio=1``:: sage: p = plot3d(lambda u,v:(cos(u)-cos(v)), (-0.2,0.2),(-0.2,0.2)) - sage: p.show(viewer="threejs") - sage: p.show(viewer="jmol") - sage: p.show(viewer="jmol",aspect_ratio=1) - sage: p.show(viewer="tachyon",camera_position=(4,0,0)) - sage: p.show(viewer="tachyon",camera_position=(2,2,0.3),aspect_ratio=1) + sage: p.show(viewer='threejs') + sage: p.show(viewer='jmol') + sage: p.show(viewer='jmol',aspect_ratio=1) + sage: p.show(viewer='tachyon',camera_position=(4,0,0)) + sage: p.show(viewer='tachyon',camera_position=(2,2,0.3),aspect_ratio=1) CHANGING DEFAULTS: Defaults can be uniformly changed by importing a dictionary and changing it. For example, here we change the default @@ -1784,12 +1778,12 @@ end_scene""".format( Sometimes shadows in Tachyon-produced images can lead to confusing plots. To remove them:: - sage: p.show(viewer="tachyon", shade="medium") # needs sage.symbolic + sage: p.show(viewer='tachyon', shade='medium') # needs sage.symbolic One can also pass Tachyon command line flags directly. For example, the following line produces the same result as the previous one:: - sage: p.show(viewer="tachyon", extra_opts="-mediumshade") # needs sage.symbolic + sage: p.show(viewer='tachyon', extra_opts='-mediumshade') # needs sage.symbolic """ from sage.repl.rich_output import get_display_manager dm = get_display_manager() @@ -1840,8 +1834,8 @@ end_scene""".format( INPUT: - - ``filename`` -- string. The file name under which to save - the image. + - ``filename`` -- string; the file name under which to save + the image Any further keyword arguments are passed to the renderer. @@ -1893,9 +1887,9 @@ end_scene""".format( INPUT: - - ``filename`` -- string. Where to save the image or object. + - ``filename`` -- string; where to save the image or object - - ``**kwds`` -- When specifying an image file to be rendered by Tachyon + - ``**kwds`` -- when specifying an image file to be rendered by Tachyon or Jmol, any of the viewing options accepted by :meth:`show` are valid as keyword arguments to this function and they will behave in the same way. Accepted keywords include: ``viewer``, ``verbosity``, @@ -1935,7 +1929,6 @@ end_scene""".format( sage: f = tmp_filename(ext='.html') sage: G.save(f, frame=False, online=True) - """ ext = os.path.splitext(filename)[1].lower() if ext == '' or ext == '.sobj': @@ -1973,9 +1966,7 @@ end_scene""".format( This only works for surfaces, transforms and unions of surfaces, but not for general plot objects! - OUTPUT: - - A binary string that represents the surface in the binary STL format. + OUTPUT: a binary string that represents the surface in the binary STL format See :wikipedia:`STL_(file_format)` @@ -2010,7 +2001,7 @@ end_scene""".format( N_triangles = len(data) return b''.join([header, struct.pack('I', N_triangles)] + data) - def stl_ascii_string(self, name="surface"): + def stl_ascii_string(self, name='surface'): """ Return an STL (STereoLithography) representation of the surface. @@ -2020,11 +2011,9 @@ end_scene""".format( INPUT: - - ``name`` (string, default: "surface") -- name of the surface. - - OUTPUT: + - ``name`` -- string (default: ``'surface'``); name of the surface - A string that represents the surface in the STL format. + OUTPUT: string that represents the surface in the STL format See :wikipedia:`STL_(file_format)` @@ -2113,19 +2102,17 @@ end_scene""".format( string_list += ["endsolid {}".format(name)] return "".join(string_list) - def ply_ascii_string(self, name="surface"): + def ply_ascii_string(self, name='surface'): """ Return a PLY (Polygon File Format) representation of the surface. INPUT: - - ``name`` (string, default: "surface") -- name of the surface. - - OUTPUT: + - ``name`` -- string (default: ``'surface'``); name of the surface - A string that represents the surface in the PLY format. + OUTPUT: string that represents the surface in the PLY format - See :wikipedia:`PLY_(file_format)` + See :wikipedia:`PLY_(file_format)`. EXAMPLES:: @@ -2179,7 +2166,7 @@ end_scene""".format( return "".join(string_list) - def amf_ascii_string(self, name="surface"): + def amf_ascii_string(self, name='surface'): """ Return an AMF (Additive Manufacturing File Format) representation of the surface. @@ -2190,13 +2177,11 @@ end_scene""".format( INPUT: - - ``name`` (string, default: "surface") -- name of the surface. + - ``name`` -- string (default: ``'surface'``); name of the surface - OUTPUT: - - A string that represents the surface in the AMF format. + OUTPUT: string that represents the surface in the AMF format - See :wikipedia:`Additive_Manufacturing_File_Format` + See :wikipedia:`Additive_Manufacturing_File_Format`. .. TODO:: @@ -2249,7 +2234,6 @@ end_scene""".format( sage: S = sphere((0,0,0), 2) sage: S.plot() is S True - """ return self @@ -2476,7 +2460,6 @@ class Graphics3dGroup(Graphics3d): 'linewidth': 1.0, 'opacity': 1.0, 'points': [(1.0, 2.0, 3.0), (4.0, 5.0, 6.0)]})] - """ reprs = [] for g in self.all: @@ -2756,7 +2739,6 @@ class TransformGroup(Graphics3dGroup): 'opacity': 1.0, 'point': (30.0, 30.0, 30.0), 'size': 5.0})] - """ render_params.push_transform(self.get_transformation()) rep = Graphics3dGroup.threejs_repr(self, render_params) @@ -2843,14 +2825,13 @@ class KeyframeAnimationGroup(Graphics3dGroup): sage: type(animate(frames).interactive()) - """ Graphics3dGroup.__init__(self, all) self._extra_kwds.update(kwds) def threejs_repr(self, render_params): r""" - Adds keyframe information to the representations of the group's contents. + Add keyframe information to the representations of the group's contents. EXAMPLES:: @@ -2871,7 +2852,6 @@ class KeyframeAnimationGroup(Graphics3dGroup): [('point', {..., 'keyframe': 0, ..., 'point': (0.0, 0.0, 1.0), ...}), ('point', {..., 'keyframe': 0, ..., 'point': (0.0, 1.0, 0.0), ...}), ('point', {..., 'keyframe': 1, ..., 'point': (1.0, 0.0, 0.0), ...})] - """ reprs = [] for i, g in enumerate(self.all): @@ -3029,7 +3009,6 @@ cdef class PrimitiveObject(Graphics3d): 'vertices': [{'x': 0.0, 'y': 0.0, 'z': 0.0}, {'x': 1.0, 'y': 0.0, 'z': 0.0}, {'x': 0.0, 'y': 1.0, 'z': 0.0}]})] - """ return self.triangulation().threejs_repr(render_params) @@ -3080,7 +3059,6 @@ class BoundingSphere(SageObject): sage: BoundingSphere((1,2,3), 10) + None + 0 Center (1.0, 2.0, 3.0) radius 10 - """ if other == 0 or other is None: return self @@ -3209,17 +3187,16 @@ class RenderParams(SageObject): [ 0.0 1.0 0.0 500.0] [ 0.0 0.0 1.0 0.0] [ 0.0 0.0 0.0 1.0] - """ self.transform = self.transform_list.pop() - def unique_name(self, desc="name"): + def unique_name(self, desc='name'): """ Return a unique identifier starting with ``desc``. INPUT: - - ``desc`` (string) -- the prefix of the names (default 'name') + - ``desc`` -- string (default: ``'name'``); the prefix of the names EXAMPLES:: @@ -3340,11 +3317,11 @@ def optimal_aspect_ratios(ratios): Average the aspect ratios. compute the elementwise maximum of triples. - TESTS:: + TESTS:: - sage: from sage.plot.plot3d.base import optimal_aspect_ratios - sage: optimal_aspect_ratios([(2,4,6), (5,4,4), (1,2,7)]) - [5, 4, 7] + sage: from sage.plot.plot3d.base import optimal_aspect_ratios + sage: optimal_aspect_ratios([(2,4,6), (5,4,4), (1,2,7)]) + [5, 4, 7] """ n = len(ratios) if n > 0: @@ -3357,11 +3334,11 @@ def optimal_extra_kwds(v): Merge a list v of dictionaries such that later dictionaries have precedence. - TESTS:: + TESTS:: - sage: from sage.plot.plot3d.base import optimal_extra_kwds - sage: optimal_extra_kwds([{1:2, 2:3}, {2:4, 3:5}]) - {1: 2, 2: 4, 3: 5} + sage: from sage.plot.plot3d.base import optimal_extra_kwds + sage: optimal_extra_kwds([{1:2, 2:3}, {2:4, 3:5}]) + {1: 2, 2: 4, 3: 5} """ a = {} for b in v: @@ -3371,12 +3348,12 @@ def optimal_extra_kwds(v): def _flip_orientation(v): """ - Switch from LH to RH coords to be consistent with Java rendition + Switch from LH to RH coords to be consistent with Java rendition. - TESTS:: + TESTS:: - sage: from sage.plot.plot3d.base import _flip_orientation - sage: _flip_orientation((1, 2, 3)) - (1, -2, 3) + sage: from sage.plot.plot3d.base import _flip_orientation + sage: _flip_orientation((1, 2, 3)) + (1, -2, 3) """ return (v[0], -v[1], v[2]) diff --git a/src/sage/plot/plot3d/bugs.txt b/src/sage/plot/plot3d/bugs.txt index 7355e3ad63f..60a084c22c0 100644 --- a/src/sage/plot/plot3d/bugs.txt +++ b/src/sage/plot/plot3d/bugs.txt @@ -65,13 +65,13 @@ Jmol bugs: other things break. Probably need to save the javascript and execute it each time we reload. -* Sphere(0.3,color="red").translate([1,1,-1]) has *holes* in it!! +* Sphere(0.3,color='red').translate([1,1,-1]) has *holes* in it!! * (done) Default zoom is useless -- we will have to rescale the whole scene I think. Basically we have to figure out the true range of the 3d plot in each direction, then rescale everything into a 10x10x10 square. We should draw axis and allow for aspect ratios. - * Invalid color doesn't yield an error message, e.g., Icosahedron(texture="yello") + * Invalid color doesn't yield an error message, e.g., Icosahedron(texture='yello') * color --> rgbcolor * Observation: jmol embedded applets *crash* when more than 10 or so appear in diff --git a/src/sage/plot/plot3d/implicit_plot3d.py b/src/sage/plot/plot3d/implicit_plot3d.py index 1d8cf813e95..6fe1d4de6a0 100644 --- a/src/sage/plot/plot3d/implicit_plot3d.py +++ b/src/sage/plot/plot3d/implicit_plot3d.py @@ -11,26 +11,26 @@ def implicit_plot3d(f, xrange, yrange, zrange, **kwds): INPUT: - - ``f`` -- function + - ``f`` -- function - - ``xrange`` -- a 2-tuple (x_min, x_max) or a 3-tuple (x, x_min, x_max) + - ``xrange`` -- a 2-tuple (x_min, x_max) or a 3-tuple (x, x_min, x_max) - - ``yrange`` -- a 2-tuple (y_min, y_max) or a 3-tuple (y, y_min, y_max) + - ``yrange`` -- a 2-tuple (y_min, y_max) or a 3-tuple (y, y_min, y_max) - - ``zrange`` -- a 2-tuple (z_min, z_max) or a 3-tuple (z, z_min, z_max) + - ``zrange`` -- a 2-tuple (z_min, z_max) or a 3-tuple (z, z_min, z_max) - - ``plot_points`` -- (default: "automatic", which is 40) the number of - function evaluations in each direction. (The number of cubes in the - marching cubes algorithm will be one less than this). Can be a triple of - integers, to specify a different resolution in each of x,y,z. + - ``plot_points`` -- (default: "automatic", which is 40) the number of + function evaluations in each direction. (The number of cubes in the + marching cubes algorithm will be one less than this). Can be a triple of + integers, to specify a different resolution in each of x,y,z. - - ``contour`` -- (default: 0) plot the isosurface ``f(x,y,z) == contour``. - Can be a list, in which case multiple contours are plotted. + - ``contour`` -- (default: 0) plot the isosurface ``f(x,y,z) == contour``. + Can be a list, in which case multiple contours are plotted - - ``region`` -- (default: None) If region is given, it must be a Python - callable. Only segments of the surface where ``region(x,y,z)`` returns a - number `>0` will be included in the plot. (Note that returning a Python - boolean is acceptable, since ``True == 1`` and ``False == 0``). + - ``region`` -- (default: ``None``) if region is given, it must be a Python + callable. Only segments of the surface where ``region(x,y,z)`` returns a + number `>0` will be included in the plot. (Note that returning a Python + boolean is acceptable, since ``True == 1`` and ``False == 0``). EXAMPLES:: diff --git a/src/sage/plot/plot3d/implicit_surface.pyx b/src/sage/plot/plot3d/implicit_surface.pyx index f4d5059b620..0a6e03354e6 100644 --- a/src/sage/plot/plot3d/implicit_surface.pyx +++ b/src/sage/plot/plot3d/implicit_surface.pyx @@ -851,18 +851,18 @@ cpdef render_implicit(f, xrange, yrange, zrange, plot_points, cube_marchers): """ INPUT: - - ``f`` -- a (fast!) callable function + - ``f`` -- a (fast!) callable function - - ``xrange`` -- a 2-tuple (x_min, x_max) + - ``xrange`` -- a 2-tuple (x_min, x_max) - - ``yrange`` -- a 2-tuple (y_min, y_may) + - ``yrange`` -- a 2-tuple (y_min, y_may) - - ``zrange`` -- a 2-tuple (z_min, z_maz) + - ``zrange`` -- a 2-tuple (z_min, z_maz) - - ``plot_points`` -- a triple of integers indicating the number of - function evaluations in each direction. + - ``plot_points`` -- a triple of integers indicating the number of + function evaluations in each direction - - ``cube_marchers`` -- a list of cube marchers, one for each contour. + - ``cube_marchers`` -- list of cube marchers, one for each contour OUTPUT: @@ -947,7 +947,7 @@ cdef class ImplicitSurface(IndexFaceSet): cdef readonly tuple plot_points def __init__(self, f, xrange, yrange, zrange, - contour=0, plot_points="automatic", + contour=0, plot_points='automatic', region=None, smooth=True, gradient=None, **kwds): """ @@ -1199,7 +1199,6 @@ cdef class ImplicitSurface(IndexFaceSet): sage: len(G.vertex_list()) > 0, len(G.face_list()) > 0 (True, True) sage: G.show() # This should be fast, since the mesh is already triangulated. - """ if self.fcount != 0 and not force: # The mesh is already triangulated diff --git a/src/sage/plot/plot3d/index_face_set.pyx b/src/sage/plot/plot3d/index_face_set.pyx index 4a98bfba774..04cd6866f8d 100644 --- a/src/sage/plot/plot3d/index_face_set.pyx +++ b/src/sage/plot/plot3d/index_face_set.pyx @@ -205,7 +205,7 @@ def midpoint(pointa, pointb, w): - ``pointa``, ``pointb`` -- two points in 3-dimensional space - - ``w`` -- a real weight between 0 and 1. + - ``w`` -- a real weight between 0 and 1 If the weight is zero, the result is ``pointb``. If the weight is one, the result is ``pointa``. @@ -393,7 +393,7 @@ cdef class IndexFaceSet(PrimitiveObject): cdef int realloc(self, Py_ssize_t vcount, Py_ssize_t fcount, Py_ssize_t icount) except -1: r""" - Allocates memory for vertices, faces, and face indices. Can + Allocate memory for vertices, faces, and face indices. Can only be called from Cython, so the doctests must be indirect. EXAMPLES:: @@ -930,7 +930,7 @@ cdef class IndexFaceSet(PrimitiveObject): INPUT: - - `f` -- a function from `\RR^3` to `\ZZ` + - ``f`` -- a function from `\RR^3` to `\ZZ` EXAMPLES:: @@ -1003,9 +1003,7 @@ cdef class IndexFaceSet(PrimitiveObject): - ``eps`` -- target accuracy in the intersection (default: 1.0e-6) - OUTPUT: - - an ``IndexFaceSet`` + OUTPUT: an ``IndexFaceSet`` This will contain both triangular and quadrilateral faces. @@ -1409,7 +1407,6 @@ cdef class IndexFaceSet(PrimitiveObject): {'x': 0.0, 'y': 1.0, 'z': 1.0}, {'x': 1.0, 'y': 0.0, 'z': 1.0}, {'x': 1.0, 'y': 1.0, 'z': 0.0}]})] - """ surface = {} @@ -1711,9 +1708,7 @@ cdef class IndexFaceSet(PrimitiveObject): the original surface so it shows, typically this value is very small compared to the actual object - OUTPUT: - - Graphics3dGroup of stickers + OUTPUT: Graphics3dGroup of stickers EXAMPLES:: @@ -1757,8 +1752,6 @@ cdef class FaceIter: True """ def __init__(self, face_set): - """ - """ self.set = face_set self.i = 0 diff --git a/src/sage/plot/plot3d/list_plot3d.py b/src/sage/plot/plot3d/list_plot3d.py index ed79ff12c7f..565b8c41387 100644 --- a/src/sage/plot/plot3d/list_plot3d.py +++ b/src/sage/plot/plot3d/list_plot3d.py @@ -22,7 +22,7 @@ def list_plot3d(v, interpolation_type='default', point_list=None, **kwds): - a list of 3-tuples - a list of lists (all of the same length) -- this is treated the same as - a matrix. + a matrix OPTIONAL KEYWORDS: @@ -42,15 +42,15 @@ def list_plot3d(v, interpolation_type='default', point_list=None, **kwds): When v is a matrix the default is to use linear interpolation, when v is a list of points the default is 'clough'. - - ``degree`` -- an integer between 1 and 5, controls the degree of spline + - ``degree`` -- integer between 1 and 5, controls the degree of spline used for spline interpolation. For data that is highly oscillatory use higher values - - ``point_list`` -- If point_list=True is passed, then if the array + - ``point_list`` -- if ``point_list=True`` is passed, then if the array is a list of lists of length three, it will be treated as an array of points rather than a 3xn array. - - ``num_points`` -- Number of points to sample interpolating + - ``num_points`` -- number of points to sample interpolating function in each direction, when ``interpolation_type`` is not ``default``. By default for an `n\times n` array this is `n`. @@ -392,8 +392,8 @@ def list_plot3d_array_of_arrays(v, interpolation_type, **kwds): INPUT: - - ``v`` -- a list of lists, all the same length - - ``interpolation_type`` -- (default: 'linear') + - ``v`` -- list of lists, all the same length + - ``interpolation_type`` -- (default: ``'linear'``) OPTIONAL KEYWORDS: @@ -474,15 +474,15 @@ def list_plot3d_tuples(v, interpolation_type, **kwds): When ``v`` is a matrix the default is to use linear interpolation, when ``v`` is a list of points the default is ``'clough'``. - - ``degree`` -- an integer between 1 and 5, controls the degree of spline + - ``degree`` -- integer between 1 and 5, controls the degree of spline used for spline interpolation. For data that is highly oscillatory use higher values - - ``point_list`` -- If ``point_list=True`` is passed, then if the array + - ``point_list`` -- if ``point_list=True`` is passed, then if the array is a list of lists of length three, it will be treated as an array of points rather than a `3\times n` array. - - ``num_points`` -- Number of points to sample interpolating + - ``num_points`` -- number of points to sample interpolating function in each direction. By default for an `n\times n` array this is `n`. diff --git a/src/sage/plot/plot3d/parametric_plot3d.py b/src/sage/plot/plot3d/parametric_plot3d.py index 201894eac42..fa8a69a805e 100644 --- a/src/sage/plot/plot3d/parametric_plot3d.py +++ b/src/sage/plot/plot3d/parametric_plot3d.py @@ -11,7 +11,7 @@ @rename_keyword(alpha='opacity') -def parametric_plot3d(f, urange, vrange=None, plot_points="automatic", +def parametric_plot3d(f, urange, vrange=None, plot_points='automatic', boundary_style=None, **kwds): r""" Return a parametric three-dimensional space curve or surface. @@ -54,13 +54,13 @@ def parametric_plot3d(f, urange, vrange=None, plot_points="automatic", how to draw the boundaries of regions by giving options that are passed to the line3d command. - - ``mesh`` -- bool (default: ``False``) whether to display + - ``mesh`` -- boolean (default: ``False``); whether to display mesh grid lines - - ``dots`` -- bool (default: ``False``) whether to display + - ``dots`` -- boolean (default: ``False``); whether to display dots at mesh grid points - .. note:: + .. NOTE:: #. By default for a curve any points where `f_x`, `f_y`, or `f_z` do not evaluate to a real number @@ -72,7 +72,6 @@ def parametric_plot3d(f, urange, vrange=None, plot_points="automatic", #. mesh and dots are not supported when using the Tachyon ray tracer renderer. - EXAMPLES: We demonstrate each of the four ways to call this function. @@ -302,8 +301,8 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: u, v = var('u,v') sage: f1 = (4+(3+cos(v))*sin(u), 4+(3+cos(v))*cos(u), 4+sin(v)) sage: f2 = (8+(3+cos(v))*cos(u), 3+sin(v), 4+(3+cos(v))*sin(u)) - sage: p1 = parametric_plot3d(f1, (u,0,2*pi), (v,0,2*pi), texture="red") - sage: p2 = parametric_plot3d(f2, (u,0,2*pi), (v,0,2*pi), texture="blue") + sage: p1 = parametric_plot3d(f1, (u,0,2*pi), (v,0,2*pi), texture='red') + sage: p2 = parametric_plot3d(f2, (u,0,2*pi), (v,0,2*pi), texture='blue') sage: p1 + p2 Graphics3d Object @@ -312,8 +311,8 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 u, v = var('u,v') f1 = (4+(3+cos(v))*sin(u), 4+(3+cos(v))*cos(u), 4+sin(v)) f2 = (8+(3+cos(v))*cos(u), 3+sin(v), 4+(3+cos(v))*sin(u)) - p1 = parametric_plot3d(f1, (u,0,2*pi), (v,0,2*pi), texture="red") - p2 = parametric_plot3d(f2, (u,0,2*pi), (v,0,2*pi), texture="blue") + p1 = parametric_plot3d(f1, (u,0,2*pi), (v,0,2*pi), texture='red') + p2 = parametric_plot3d(f2, (u,0,2*pi), (v,0,2*pi), texture='blue') sphinx_plot(p1 + p2) A cylindrical Star of David:: @@ -363,7 +362,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = cos(u)*(4*sqrt(1-v^2)*sin(abs(u))^abs(u)) sage: f_y = sin(u)*(4*sqrt(1-v^2)*sin(abs(u))^abs(u)) sage: f_z = v - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-1,1), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-1,1), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -372,7 +371,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = cos(u)*(4*sqrt(1-v**2)*sin(abs(u))**abs(u)) f_y = sin(u) *(4*sqrt(1-v**2)*sin(abs(u))**abs(u)) f_z = v - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-1,1), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-1,1), frame=False, color='red')) A Trefoil knot (:wikipedia:`Trefoil_knot`):: @@ -380,7 +379,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (4*(1+0.25*sin(3*v))+cos(u))*cos(2*v) sage: f_y = (4*(1+0.25*sin(3*v))+cos(u))*sin(2*v) sage: f_z = sin(u)+2*cos(3*v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color="blue") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color='blue') Graphics3d Object .. PLOT:: @@ -389,7 +388,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (4*(1+0.25*sin(3*v))+cos(u))*cos(2*v) f_y = (4*(1+0.25*sin(3*v))+cos(u))*sin(2*v) f_z = sin(u)+2*cos(3*v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color="blue")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color='blue')) Green bowtie:: @@ -397,7 +396,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = sin(u) / (sqrt(2) + sin(v)) sage: f_y = sin(u) / (sqrt(2) + cos(v)) sage: f_z = cos(u) / (1 + sqrt(2)) - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color='green') Graphics3d Object .. PLOT:: @@ -406,7 +405,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = sin(u) / (sqrt(2) + sin(v)) f_y = sin(u) / (sqrt(2) + cos(v)) f_z = cos(u) / (1 + sqrt(2)) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), frame=False, color='green')) Boy's surface (:wikipedia:`Boy%27s_surface` and https://mathcurve.com/surfaces/boy/boy.shtml):: @@ -420,7 +419,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 ....: (v,0,pi), ....: plot_points=[90,90], ....: frame=False, - ....: color="orange") + ....: color='orange') Graphics3d Object .. PLOT:: @@ -431,7 +430,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_y = K * (cos(u)*sin(2*v)-sqrt(2)*sin(u)*sin(v)) f_z = 3 * K * cos(u) P = parametric_plot3d([f_x, f_y, f_z], (u,-2*pi,2*pi), (v,0,pi), - plot_points=[90,90], frame=False, color="orange") # long time -- about 30 seconds + plot_points=[90,90], frame=False, color='orange') # long time -- about 30 seconds sphinx_plot(P) Maeder's Owl also known as Bour's minimal surface (:wikipedia:`Bour%27s_minimal_surface`):: @@ -441,7 +440,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_y = -v*sin(u) - 0.5*v^2*sin(2*u) sage: f_z = 4 * v^1.5 * cos(3*u/2) / 3 sage: parametric_plot3d([f_x, f_y, f_z], (u,-2*pi,2*pi), (v,0,1), - ....: plot_points=[90,90], frame=False, color="purple") + ....: plot_points=[90,90], frame=False, color='purple') Graphics3d Object .. PLOT:: @@ -451,7 +450,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_y = -v*sin(u) - 0.5*v**2*sin(2*u) f_z = 4 * v**1.5 * cos(3*u/2) / 3 P = parametric_plot3d([f_x, f_y, f_z], (u,-2*pi,2*pi), (v,0,1), - plot_points=[90,90], frame=False, color="purple") + plot_points=[90,90], frame=False, color='purple') sphinx_plot(P) Bracelet:: @@ -460,7 +459,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (2 + 0.2*sin(2*pi*u))*sin(pi*v) sage: f_y = 0.2 * cos(2*pi*u) * 3 * cos(2*pi*v) sage: f_z = (2 + 0.2*sin(2*pi*u))*cos(pi*v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,pi/2), (v,0,3*pi/4), frame=False, color="gray") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,pi/2), (v,0,3*pi/4), frame=False, color='gray') Graphics3d Object .. PLOT:: @@ -469,7 +468,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (2 + 0.2*sin(2*pi*u))*sin(pi*v) f_y = 0.2 * cos(2*pi*u) * 3* cos(2*pi*v) f_z = (2 + 0.2*sin(2*pi*u))*cos(pi*v) - P = parametric_plot3d([f_x, f_y, f_z], (u,0,pi/2), (v,0,3*pi/4), frame=False, color="gray") + P = parametric_plot3d([f_x, f_y, f_z], (u,0,pi/2), (v,0,3*pi/4), frame=False, color='gray') sphinx_plot(P) @@ -479,7 +478,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = cos(u) * cos(2*v) sage: f_y = sin(u) * cos(2*v) sage: f_z = sin(v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,pi), frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,pi), frame=False, color='green') Graphics3d Object .. PLOT:: @@ -488,7 +487,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = cos(u) * cos(2*v) f_y = sin(u) * cos(2*v) f_z = sin(v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,pi), frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,pi), frame=False, color='green')) Funny folded surface - with square projection:: @@ -497,7 +496,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = cos(u) * sin(2*v) sage: f_y = sin(u) * cos(2*v) sage: f_z = sin(v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='green') Graphics3d Object .. PLOT:: @@ -506,7 +505,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = cos(u) * sin(2*v) f_y = sin(u) * cos(2*v) f_z = sin(v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='green')) Surface of revolution of figure 8:: @@ -514,7 +513,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = cos(u) * sin(2*v) sage: f_y = sin(u) * sin(2*v) sage: f_z = sin(v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='green') Graphics3d Object .. PLOT:: @@ -523,7 +522,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = cos(u) * sin(2*v) f_y = sin(u) * sin(2*v) f_z = sin(v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='green')) Yellow Whitney's umbrella (:wikipedia:`Whitney_umbrella`):: @@ -531,7 +530,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = u*v sage: f_y = u sage: f_z = v^2 - sage: parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-1,1), frame=False, color="yellow") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-1,1), frame=False, color='yellow') Graphics3d Object .. PLOT:: @@ -540,7 +539,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = u*v f_y = u f_z = v**2 - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-1,1), frame=False, color="yellow")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-1,1), frame=False, color='yellow')) Cross cap (:wikipedia:`Cross-cap`):: @@ -548,7 +547,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (1+cos(v)) * cos(u) sage: f_y = (1+cos(v)) * sin(u) sage: f_z = -tanh((2/3)*(u-pi)) * sin(v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -557,7 +556,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (1+cos(v)) * cos(u) f_y = (1+cos(v)) * sin(u) f_z = -tanh((2.0/3.0)*(u-pi)) * sin(v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='red')) Twisted torus:: @@ -565,7 +564,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (3+sin(v)+cos(u)) * cos(2*v) sage: f_y = (3+sin(v)+cos(u)) * sin(2*v) sage: f_z = sin(u) + 2*cos(v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -574,7 +573,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (3+sin(v)+cos(u)) * cos(2*v) f_y = (3+sin(v)+cos(u)) * sin(2*v) f_z = sin(u) + 2*cos(v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='red')) Four intersecting discs:: @@ -582,7 +581,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = v*cos(u) - 0.5*v^2*cos(2*u) sage: f_y = -v*sin(u) - 0.5*v^2*sin(2*u) sage: f_z = 4 * v^1.5 * cos(3*u/2) / 3 - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,4*pi), (v,0,2*pi), frame=False, color="red", opacity=0.7) + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,4*pi), (v,0,2*pi), frame=False, color='red', opacity=0.7) Graphics3d Object .. PLOT:: @@ -591,7 +590,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = v*cos(u) - 0.5*v**2*cos(2*u) f_y = -v*sin(u) - 0.5*v**2*sin(2*u) f_z = 4 * v**1.5 * cos(3.0*u/2.0) /3 - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,4*pi), (v,0,2*pi), frame=False, color="red", opacity=0.7)) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,4*pi), (v,0,2*pi), frame=False, color='red', opacity=0.7)) Steiner surface/Roman's surface (see :wikipedia:`Roman_surface` and @@ -601,7 +600,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (sin(2*u) * cos(v) * cos(v)) sage: f_y = (sin(u) * sin(2*v)) sage: f_z = (cos(u) * sin(2*v)) - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,-pi/2,pi/2), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,-pi/2,pi/2), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -610,7 +609,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (sin(2*u) * cos(v) * cos(v)) f_y = (sin(u) * sin(2*v)) f_z = (cos(u) * sin(2*v)) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,-pi/2,pi/2), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,-pi/2,pi/2), frame=False, color='red')) Klein bottle? (see :wikipedia:`Klein_bottle`):: @@ -618,7 +617,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (3*(1+sin(v)) + 2*(1-cos(v)/2)*cos(u)) * cos(v) sage: f_y = (4+2*(1-cos(v)/2)*cos(u)) * sin(v) sage: f_z = -2 * (1-cos(v)/2) * sin(u) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='green') Graphics3d Object .. PLOT:: @@ -627,7 +626,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (3*(1+sin(v)) + 2*(1-cos(v)/2)*cos(u)) * cos(v) f_y = (4+2*(1-cos(v)/2)*cos(u)) * sin(v) f_z = -2 * (1-cos(v)/2) * sin(u) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='green')) A Figure 8 embedding of the Klein bottle (see :wikipedia:`Klein_bottle`):: @@ -636,7 +635,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (2+cos(v/2)*sin(u)-sin(v/2)*sin(2*u)) * cos(v) sage: f_y = (2+cos(v/2)*sin(u)-sin(v/2)*sin(2*u)) * sin(v) sage: f_z = sin(v/2)*sin(u) + cos(v/2)*sin(2*u) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -645,7 +644,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (2+cos(0.5*v)*sin(u)-sin(0.5*v)*sin(2*u)) * cos(v) f_y = (2+cos(0.5*v)*sin(u)-sin(0.5*v)*sin(2*u)) * sin(v) f_z = sin(v*0.5)*sin(u) + cos(v*0.5)*sin(2*u) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0,2*pi), frame=False, color='red')) Enneper's surface (see :wikipedia:`Enneper_surface`):: @@ -654,7 +653,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = u - u^3/3 + u*v^2 sage: f_y = v - v^3/3 + v*u^2 sage: f_z = u^2 - v^2 - sage: parametric_plot3d([f_x, f_y, f_z], (u,-2,2), (v,-2,2), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-2,2), (v,-2,2), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -663,7 +662,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = u - u**3/3 + u*v**2 f_y = v - v**3/3 + v*u**2 f_z = u**2 - v**2 - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-2,2), (v,-2,2), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-2,2), (v,-2,2), frame=False, color='red')) Henneberg's surface (see http://xahlee.org/surface/gallery_m.html):: @@ -672,7 +671,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = 2*sinh(u)*cos(v) - (2/3)*sinh(3*u)*cos(3*v) sage: f_y = 2*sinh(u)*sin(v) + (2/3)*sinh(3*u)*sin(3*v) sage: f_z = 2 * cosh(2*u) * cos(2*v) - sage: parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-pi/2,pi/2), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-pi/2,pi/2), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -681,7 +680,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = 2.0*sinh(u)*cos(v) - (2.0/3.0)*sinh(3*u)*cos(3*v) f_y = 2.0*sinh(u)*sin(v) + (2.0/3.0)*sinh(3*u)*sin(3*v) f_z = 2.0 * cosh(2*u) * cos(2*v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-pi/2,pi/2), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-1,1), (v,-pi/2,pi/2), frame=False, color='red')) Dini's spiral:: @@ -689,7 +688,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = cos(u) * sin(v) sage: f_y = sin(u) * sin(v) sage: f_z = (cos(v)+log(tan(v/2))) + 0.2*u - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,12.4), (v,0.1,2), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,12.4), (v,0.1,2), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -698,7 +697,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = cos(u) * sin(v) f_y = sin(u) * sin(v) f_z = (cos(v)+log(tan(v*0.5))) + 0.2*u - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,12.4), (v,0.1,2), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,12.4), (v,0.1,2), frame=False, color='red')) Catalan's surface (see http://xahlee.org/surface/catalan/catalan.html):: @@ -707,7 +706,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = u - sin(u)*cosh(v) sage: f_y = 1 - cos(u)*cosh(v) sage: f_z = 4 * sin(1/2*u) * sinh(v/2) - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,3*pi), (v,-2,2), frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,3*pi), (v,-2,2), frame=False, color='red') Graphics3d Object .. PLOT:: @@ -716,7 +715,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = u - sin(u)*cosh(v) f_y = 1.0 - cos(u)*cosh(v) f_z = 4.0 * sin(0.5*u) * sinh(0.5*v) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,3*pi), (v,-2,2), frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,3*pi), (v,-2,2), frame=False, color='red')) A Conchoid:: @@ -845,7 +844,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (sinh(v)*cos(3*u)) / (1+cosh(u)*cosh(v)) sage: f_y = (sinh(v)*sin(3*u)) / (1+cosh(u)*cosh(v)) sage: f_z = (cosh(v)*sinh(u)) / (1+cosh(u)*cosh(v)) - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color='red') Graphics3d Object .. PLOT:: @@ -855,7 +854,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (sinh(v)*cos(3*u)) / (1+cosh(u)*cosh(v)) f_y = (sinh(v)*sin(3*u)) / (1+cosh(u)*cosh(v)) f_z = (cosh(v)*sinh(u)) / (1+cosh(u)*cosh(v)) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color='red')) A Helicoid (lines through a helix, :wikipedia:`Helix`):: @@ -864,7 +863,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = sinh(v) * sin(u) sage: f_y = -sinh(v) * cos(u) sage: f_z = 3 * u - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color="red") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color='red') Graphics3d Object .. PLOT:: @@ -873,7 +872,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = sinh(v) * sin(u) f_y = -sinh(v) * cos(u) f_z = 3 * u - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color="red")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi,pi), (v,-pi,pi), plot_points=[50,50], frame=False, color='red')) Kuen's surface (http://virtualmathmuseum.org/Surface/kuen/kuen.html):: @@ -881,7 +880,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (2*(cos(u) + u*sin(u))*sin(v))/(1+ u^2*sin(v)^2) sage: f_y = (2*(sin(u) - u*cos(u))*sin(v))/(1+ u^2*sin(v)^2) sage: f_z = log(tan(1/2 *v)) + (2*cos(v))/(1+ u^2*sin(v)^2) - sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0.01,pi-0.01), plot_points=[50,50], frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0.01,pi-0.01), plot_points=[50,50], frame=False, color='green') Graphics3d Object .. PLOT:: @@ -890,7 +889,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (2.0*(cos(u)+u*sin(u))*sin(v)) / (1.0+u**2*sin(v)**2) f_y = (2.0*(sin(u)-u*cos(u))*sin(v)) / (1.0+u**2*sin(v)**2) f_z = log(tan(0.5 *v)) + (2*cos(v))/(1.0+u**2*sin(v)**2) - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0.01,pi-0.01), plot_points=[50,50], frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,0,2*pi), (v,0.01,pi-0.01), plot_points=[50,50], frame=False, color='green')) A 5-pointed star:: @@ -899,7 +898,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = cos(u) * cos(v) * G1 * G2 sage: f_y = cos(u) * sin(v) * G1 * G2 sage: f_z = sin(u) * G1 - sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,0,2*pi), plot_points=[50,50], frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,0,2*pi), plot_points=[50,50], frame=False, color='green') Graphics3d Object .. PLOT:: @@ -910,14 +909,14 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = cos(u) * cos(v) * G1 * G2 f_y = cos(u) * sin(v) * G1 * G2 f_z = sin(u) * G1 - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,0,2*pi), plot_points=[50,50], frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-pi/2,pi/2), (v,0,2*pi), plot_points=[50,50], frame=False, color='green')) A cool self-intersecting surface (Eppener surface?):: sage: f_x = u - u^3/3 + u*v^2 sage: f_y = v - v^3/3 + v*u^2 sage: f_z = u^2 - v^2 - sage: parametric_plot3d([f_x, f_y, f_z], (u,-25,25), (v,-25,25), plot_points=[50,50], frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-25,25), (v,-25,25), plot_points=[50,50], frame=False, color='green') Graphics3d Object .. PLOT:: @@ -926,7 +925,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = u - u**3/3 + u*v**2 f_y = v - v**3/3 + v*u**2 f_z = u**2 - v**2 - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-25,25), (v,-25,25), plot_points=[50,50], frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-25,25), (v,-25,25), plot_points=[50,50], frame=False, color='green')) The breather surface (:wikipedia:`Breather_surface`):: @@ -936,7 +935,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: f_x = (2*K*cosh(0.4*u)*(-(K*cos(v)*cos(K*v)) - sin(v)*sin(K*v)))/G sage: f_y = (2*K*cosh(0.4*u)*(-(K*sin(v)*cos(K*v)) + cos(v)*sin(K*v)))/G sage: f_z = -u + (2*0.84*cosh(0.4*u)*sinh(0.4*u))/G - sage: parametric_plot3d([f_x, f_y, f_z], (u,-13.2,13.2), (v,-37.4,37.4), plot_points=[90,90], frame=False, color="green") + sage: parametric_plot3d([f_x, f_y, f_z], (u,-13.2,13.2), (v,-37.4,37.4), plot_points=[90,90], frame=False, color='green') Graphics3d Object .. PLOT:: @@ -947,7 +946,7 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 f_x = (2*K*cosh(0.4*u)*(-(K*cos(v)*cos(K*v)) - sin(v)*sin(K*v)))/G f_y = (2*K*cosh(0.4*u)*(-(K*sin(v)*cos(K*v)) + cos(v)*sin(K*v)))/G f_z = -u + (2*0.84*cosh(0.4*u)*sinh(0.4*u))/G - sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-13.2,13.2), (v,-37.4,37.4), plot_points=[90,90], frame=False, color="green")) + sphinx_plot(parametric_plot3d([f_x, f_y, f_z], (u,-13.2,13.2), (v,-37.4,37.4), plot_points=[90,90], frame=False, color='green')) TESTS:: @@ -970,23 +969,22 @@ def g(x,y): return x, y+sin(y), x**2 + y**2 sage: x, y = var('x,y') sage: plot3d(x*y^2 - sin(x), (x,-1,1), (y,-1,1)) Graphics3d Object - """ # TODO: # * Surface -- behavior of functions not defined everywhere -- see note above # * Iterative refinement - # color_function -- (default: "automatic") how to determine the color of curves and surfaces - # color_function_scaling -- (default: ``True``) whether to scale the input to color_function - # exclusions -- (default: "automatic") u points or (u,v) conditions to exclude. + # color_function -- (default: ``'automatic'``) how to determine the color of curves and surfaces + # color_function_scaling -- boolean (default: ``True``); whether to scale the input to color_function + # exclusions -- (default: ``'automatic'``) u points or (u,v) conditions to exclude. # (E.g., exclusions could be a function e = lambda u, v: False if u < v else True - # exclusions_style -- (default: None) what to draw at excluded points - # max_recursion -- (default: "automatic") maximum number of recursive subdivisions, + # exclusions_style -- (default: ``None``) what to draw at excluded points + # max_recursion -- (default: ``'automatic'``) maximum number of recursive subdivisions, # when ... - # mesh -- (default: "automatic") how many mesh divisions in each direction to draw - # mesh_functions -- (default: "automatic") how to determine the placement of mesh divisions - # mesh_shading -- (default: None) how to shade regions between mesh divisions - # plot_range -- (default: "automatic") range of values to include + # mesh -- (default: ``'automatic'``) how many mesh divisions in each direction to draw + # mesh_functions -- (default: ``'automatic'``) how to determine the placement of mesh divisions + # mesh_shading -- (default: ``None``) how to shade regions between mesh divisions + # plot_range -- (default: ``'automatic'``) range of values to include if isinstance(f, Vector): f = tuple(f) @@ -1035,8 +1033,8 @@ def _parametric_plot3d_curve(f, urange, plot_points, **kwds): - ``urange`` -- a 2-tuple (u_min, u_max) or a 3-tuple (u, u_min, u_max) - - ``plot_points`` -- (default: "automatic", which is 75) initial - number of sample points in each parameter; an integer. + - ``plot_points`` -- integer (default: 75, "automatic"); initial + number of sample points in each parameter EXAMPLES: @@ -1054,7 +1052,6 @@ def _parametric_plot3d_curve(f, urange, plot_points, **kwds): sage: u = var('u') sage: parametric_plot3d((sin(u), cos(u), u/10), (u,0,20)) Graphics3d Object - """ from sage.plot.misc import setup_for_eval_on_grid g, ranges = setup_for_eval_on_grid(f, [urange], plot_points) diff --git a/src/sage/plot/plot3d/parametric_surface.pyx b/src/sage/plot/plot3d/parametric_surface.pyx index 85e01276228..dab78e762a5 100644 --- a/src/sage/plot/plot3d/parametric_surface.pyx +++ b/src/sage/plot/plot3d/parametric_surface.pyx @@ -44,14 +44,14 @@ EXAMPLES:: By default, the surface is colored with one single color. :: sage: P = ParametricSurface(f, (srange(0,10,0.1), srange(-5,5.0,0.1)), - ....: color="red") + ....: color='red') sage: P.show() .. PLOT:: from sage.plot.plot3d.parametric_surface import ParametricSurface def f(x,y): return x+y, sin(x)*sin(y), x*y - sphinx_plot(ParametricSurface(f, (srange(0,10,0.1), srange(-5,5.0,0.1)), color="red")) + sphinx_plot(ParametricSurface(f, (srange(0,10,0.1), srange(-5,5.0,0.1)), color='red')) One can instead provide a coloring function and a colormap:: @@ -145,15 +145,15 @@ cdef class ParametricSurface(IndexFaceSet): INPUT: - - ``f`` -- (default: ``None``) The defining function. Either a tuple of + - ``f`` -- (default: ``None``) the defining function. Either a tuple of three functions, or a single function which returns a tuple, taking two python floats as input. To subclass, pass ``None`` for ``f`` and override ``eval_c`` or ``eval`` instead. - - ``domain`` -- (default: ``None``) A tuple of two lists, defining the + - ``domain`` -- (default: ``None``) a tuple of two lists, defining the grid of `u,v` values. If ``None``, this will be calculated automatically. - - ``color`` -- (default: ``None``) A pair `(h,c)` where `h` is + - ``color`` -- (default: ``None``) a pair `(h,c)` where `h` is a function with values in `[0,1]` and `c` is a colormap. The color of a point `p` is then defined as the composition `c(h(p))` @@ -189,7 +189,7 @@ cdef class ParametricSurface(IndexFaceSet): ....: return (x,y,z) sage: v = srange(float(0),float((3/2)*pi),float(0.1)) sage: S = ParametricSurface(f, (srange(float(0),float(pi),float(0.1)), - ....: srange(float(-1),float(1),float(0.1))), color="blue") + ....: srange(float(-1),float(1),float(0.1))), color='blue') sage: show(S) .. PLOT:: @@ -203,7 +203,7 @@ cdef class ParametricSurface(IndexFaceSet): return (x,y,z) from sage.plot.plot3d.parametric_surface import ParametricSurface v = srange(float(0),float((3/2)*pi),float(0.1)) - sphinx_plot(ParametricSurface(f, (srange(float(0),float(pi),float(0.1)),srange(float(-1),float(1),float(0.1))), color="blue")) + sphinx_plot(ParametricSurface(f, (srange(float(0),float(pi),float(0.1)),srange(float(-1),float(1),float(0.1))), color='blue')) A colored example using the ``color`` keyword:: @@ -383,7 +383,6 @@ cdef class ParametricSurface(IndexFaceSet): 'vertices': [{'x': -2.0, 'y': -2.0, 'z': 0.0}, ... {'x': 2.0, 'y': 2.0, 'z': 0.0}]})] - """ self.triangulate(render_params) return IndexFaceSet.threejs_repr(self, render_params) @@ -658,10 +657,10 @@ cdef class ParametricSurface(IndexFaceSet): We branch outside the loops for efficiency. The options for self.f are: - - ``None`` -- call self.eval_c() or self.eval() - (One of these is presumably overridden.) - - tuple -- split into fx, fy, fz and call each separately - - callable -- call f(u,v) + - ``None`` -- call ``self.eval_c()`` or ``self.eval()`` + (One of these is presumably overridden.) + - ``tuple`` -- split into fx, fy, fz and call each separately + - ``callable`` -- call f(u,v) In addition, branches are taken for efficient calling of fast callables """ @@ -784,7 +783,6 @@ cdef class ParametricSurface(IndexFaceSet): sage: S = parametric_plot3d( (sin, cos, lambda u: u/10), (0, 20)) sage: S.plot() is S True - """ return self @@ -833,7 +831,6 @@ class MoebiusStrip(ParametricSurface): Graphics3d Object sage: O = MoebiusStrip(5,1,plot_points=200,color='red'); O # keywords get passed to plot3d Graphics3d Object - """ ParametricSurface.__init__(self, **kwds) self.r = float(r) @@ -848,9 +845,9 @@ class MoebiusStrip(ParametricSurface): INPUT: - - ``ds`` -- A number, typically coming from a RenderParams object, - which helps determine the increment for the `v` range for the - MoebiusStrip object. + - ``ds`` -- a number, typically coming from a RenderParams object, + which helps determine the increment for the `v` range for the + MoebiusStrip object EXAMPLES:: diff --git a/src/sage/plot/plot3d/platonic.py b/src/sage/plot/plot3d/platonic.py index 491179ede81..3f8587968e2 100644 --- a/src/sage/plot/plot3d/platonic.py +++ b/src/sage/plot/plot3d/platonic.py @@ -86,8 +86,7 @@ def index_face_set(face_list, point_list, enclosed, **kwds): - ``point_list`` -- list of points, given explicitly from the solid invocation - - ``enclosed`` -- boolean (default passed is always ``True`` - for these solids) + - ``enclosed`` -- boolean (default: ``True`` for these solids) TESTS: @@ -127,13 +126,13 @@ def prep(G, center, size, kwds): INPUT: - - ``center`` -- 3-tuple indicating the center (default passed - from :func:`index_face_set` is the origin `(0,0,0)`) + - ``center`` -- 3-tuple indicating the center (default: the origin + `(0,0,0)`, passed from :func:`index_face_set`) - - ``size`` -- number indicating amount to scale by (default - passed from :func:`index_face_set` is 1) + - ``size`` -- number indicating amount to scale by (default: 1, + passed from :func:`index_face_set`) - - ``kwds`` -- a dictionary of keywords, passed from solid + - ``kwds`` -- dictionary of keywords, passed from solid invocation by :func:`index_face_set` TESTS: @@ -164,7 +163,7 @@ def tetrahedron(center=(0, 0, 0), size=1, **kwds): - ``size`` -- (default: 1) - - ``color`` -- a string (``"red"``, ``"green"``, etc) + - ``color`` -- string (``'red'``, ``'green'``, etc) or a tuple (r, g, b) with r, g, b numbers between 0 and 1 - ``opacity`` -- (default: 1) if less than 1 then is @@ -276,21 +275,19 @@ def cube(center=(0, 0, 0), size=1, color=None, frame_thickness=0, - ``center`` -- (default: (0,0,0)) - - ``size`` -- (default: 1) the side lengths of the - cube + - ``size`` -- (default: 1) the side lengths of the cube - - ``color`` -- a string that describes a color; this + - ``color`` -- string that describes a color; this can also be a list of 3-tuples or strings length 6 or 3, in which - case the faces (and oppositive faces) are colored. + case the faces (and oppositive faces) are colored - ``frame_thickness`` -- (default: 0) if positive, then thickness of the frame - - ``frame_color`` -- (default: None) if given, gives + - ``frame_color`` -- (default: ``None``) if given, gives the color of the frame - - ``opacity`` -- (default: 1) if less than 1 then it's - transparent + - ``opacity`` -- (default: 1) if less than 1 then it's transparent EXAMPLES: @@ -305,12 +302,12 @@ def cube(center=(0, 0, 0), size=1, color=None, frame_thickness=0, A red cube:: - sage: cube(color="red") + sage: cube(color='red') Graphics3d Object .. PLOT:: - sphinx_plot(cube(color="red")) + sphinx_plot(cube(color='red')) A transparent grey cube that contains a red cube:: @@ -419,12 +416,11 @@ def octahedron(center=(0, 0, 0), size=1, **kwds): - ``size`` -- (default: 1) - - ``color`` -- a string that describes a color; this + - ``color`` -- string that describes a color; this can also be a list of 3-tuples or strings length 6 or 3, in which - case the faces (and oppositive faces) are colored. + case the faces (and oppositive faces) are colored - - ``opacity`` -- (default: 1) if less than 1 then is - transparent + - ``opacity`` -- (default: 1) if less than 1 then is transparent EXAMPLES:: @@ -438,7 +434,6 @@ def octahedron(center=(0, 0, 0), size=1, **kwds): G = octahedron((1,4,3), color='orange') G += octahedron((0,2,1), size=2, opacity=0.6) sphinx_plot(G) - """ kwds['enclosed'] = True if 'aspect_ratio' not in kwds: @@ -457,9 +452,9 @@ def dodecahedron(center=(0, 0, 0), size=1, **kwds): - ``size`` -- (default: 1) - - ``color`` -- a string that describes a color; this + - ``color`` -- string that describes a color; this can also be a list of 3-tuples or strings length 6 or 3, in which - case the faces (and oppositive faces) are colored. + case the faces (and oppositive faces) are colored - ``opacity`` -- (default: 1) if less than 1 then is transparent @@ -571,9 +566,9 @@ def icosahedron(center=(0, 0, 0), size=1, **kwds): - ``size`` -- (default: 1) - - ``color`` -- a string that describes a color; this + - ``color`` -- string that describes a color; this can also be a list of 3-tuples or strings length 6 or 3, in which - case the faces (and oppositive faces) are colored. + case the faces (and oppositive faces) are colored - ``opacity`` -- (default: 1) if less than 1 then is transparent @@ -598,7 +593,6 @@ def icosahedron(center=(0, 0, 0), size=1, **kwds): p = icosahedron((-1/2,0,1), color='orange') p += icosahedron((2,0,1), size = 0.5, color='red', aspect_ratio=[1,1,1]) sphinx_plot(p) - """ kwds['enclosed'] = True if 'aspect_ratio' not in kwds: diff --git a/src/sage/plot/plot3d/plot3d.py b/src/sage/plot/plot3d/plot3d.py index c34830d35d6..387a5dc04da 100644 --- a/src/sage/plot/plot3d/plot3d.py +++ b/src/sage/plot/plot3d/plot3d.py @@ -169,11 +169,10 @@ class _Coordinates: INPUT: - - ``dep_var`` -- the dependent variable (the function value will be - - - ``indep_vars`` -- a list of independent variables (the parameters will be - substituted for these) + - ``dep_var`` -- the dependent variable (the function value will be + - ``indep_vars`` -- list of independent variables (the parameters will be + substituted for these) """ def __init__(self, dep_var, indep_vars): """ @@ -234,11 +233,11 @@ def to_cartesian(self, func, params=None): INPUT: - - ``func`` -- function in this coordinate space; corresponds - to the independent variable + - ``func`` -- function in this coordinate space; corresponds + to the independent variable - - ``params`` -- the parameters of ``func``; corresponds to - the dependent variables + - ``params`` -- the parameters of ``func``; corresponds to + the dependent variables EXAMPLES:: @@ -316,7 +315,6 @@ def to_cartesian(self, func, params=None): sage: f=scipy.interpolate.RectBivariateSpline(v_phi,v_theta,m_r).ev sage: spherical_plot3d(f,(0,2*pi),(0,pi)) Graphics3d Object - """ from sage.structure.element import Expression from sage.rings.real_mpfr import RealNumber @@ -435,13 +433,13 @@ def __init__(self, custom_trans, dep_var, indep_vars): INPUT: - - ``custom_trans`` -- A 3-tuple of transformation - functions. + - ``custom_trans`` -- a 3-tuple of transformation + functions - - ``dep_var`` -- The dependent (function) variable. + - ``dep_var`` -- the dependent (function) variable - - ``indep_vars`` -- a list of the two other independent - variables. + - ``indep_vars`` -- list of the two other independent + variables EXAMPLES:: @@ -753,9 +751,7 @@ def triangle(self, a, b, c, color=None): - ``color`` -- ignored - OUTPUT: - - - the list ``[a,b,c]`` + OUTPUT: the list ``[a,b,c]`` TESTS:: @@ -782,9 +778,7 @@ def smooth_triangle(self, a, b, c, da, db, dc, color=None): - ``color`` -- ignored - OUTPUT: - - - the list ``[a,b,c]`` + OUTPUT: the list ``[a,b,c]`` TESTS:: @@ -806,30 +800,30 @@ def plot3d(f, urange, vrange, adaptive=False, transformation=None, **kwds): INPUT: - - ``f`` -- a symbolic expression or function of 2 - variables + - ``f`` -- a symbolic expression or function of 2 + variables - - ``urange`` -- a 2-tuple (u_min, u_max) or a 3-tuple - (u, u_min, u_max) + - ``urange`` -- a 2-tuple (u_min, u_max) or a 3-tuple + (u, u_min, u_max) - - ``vrange`` -- a 2-tuple (v_min, v_max) or a 3-tuple - (v, v_min, v_max) + - ``vrange`` -- a 2-tuple (v_min, v_max) or a 3-tuple + (v, v_min, v_max) - - ``adaptive`` -- (default: ``False``) whether to use - adaptive refinement to draw the plot (slower, but may look better). - This option does NOT work in conjunction with a transformation - (see below). + - ``adaptive`` -- boolean (default: ``False``); whether to use + adaptive refinement to draw the plot (slower, but may look better). + This option does NOT work in conjunction with a transformation + (see below). - - ``mesh`` -- bool (default: ``False``) whether to display - mesh grid lines + - ``mesh`` -- boolean (default: ``False``); whether to display + mesh grid lines - - ``dots`` -- bool (default: ``False``) whether to display - dots at mesh grid points + - ``dots`` -- boolean (default: ``False``); whether to display + dots at mesh grid points - - ``plot_points`` -- (default: "automatic") initial number of sample - points in each direction; an integer or a pair of integers + - ``plot_points`` -- (default: ``'automatic'``) initial number of sample + points in each direction; an integer or a pair of integers - - ``transformation`` -- (default: None) a transformation to + - ``transformation`` -- (default: ``None``) a transformation to apply. May be a 3 or 4-tuple (x_func, y_func, z_func, independent_vars) where the first 3 items indicate a transformation to Cartesian coordinates (from your coordinate @@ -956,7 +950,7 @@ def plot3d(f, urange, vrange, adaptive=False, transformation=None, **kwds): We draw two parametric surfaces and a transparent plane:: - sage: L = plot3d(lambda x,y: 0, (-5,5), (-5,5), color="lightblue", opacity=0.8) + sage: L = plot3d(lambda x,y: 0, (-5,5), (-5,5), color='lightblue', opacity=0.8) sage: P = plot3d(lambda x,y: 4 - x^3 - y^2, (-2,2), (-2,2), color='green') sage: Q = plot3d(lambda x,y: x^3 + y^2 - 4, (-2,2), (-2,2), color='orange') sage: L + P + Q @@ -964,7 +958,7 @@ def plot3d(f, urange, vrange, adaptive=False, transformation=None, **kwds): .. PLOT:: - L = plot3d(lambda x,y: 0, (-5,5), (-5,5), color="lightblue", opacity=0.8) + L = plot3d(lambda x,y: 0, (-5,5), (-5,5), color='lightblue', opacity=0.8) P = plot3d(lambda x,y: 4 - x**3 - y**2, (-2,2), (-2,2), color='green') Q = plot3d(lambda x,y: x**3 + y**2 - 4, (-2,2), (-2,2), color='orange') sphinx_plot(L + P + Q) @@ -1125,7 +1119,7 @@ def plot3d(f, urange, vrange, adaptive=False, transformation=None, **kwds): return P -def plot3d_adaptive(f, x_range, y_range, color="automatic", +def plot3d_adaptive(f, x_range, y_range, color='automatic', grad_f=None, max_bend=.5, max_depth=5, initial_depth=4, num_colors=128, **kwds): r""" @@ -1136,21 +1130,20 @@ def plot3d_adaptive(f, x_range, y_range, color="automatic", INPUT: - - ``f`` -- a symbolic function or a Python function of 3 variables - ``x_range`` -- x range of values: 2-tuple (xmin, - xmax) or 3-tuple (x,xmin,xmax) + xmax) or 3-tuple (x,xmin,xmax) - ``y_range`` -- y range of values: 2-tuple (ymin, ymax) or 3-tuple - (y,ymin,ymax) + (y,ymin,ymax) - ``grad_f`` -- gradient of f as a Python function - ``color`` -- "automatic"; a rainbow of num_colors colors - ``num_colors`` -- (default: 128) number of colors to use with default - color + color - ``max_bend`` -- (default: 0.5) @@ -1174,7 +1167,6 @@ def plot3d_adaptive(f, x_range, y_range, color="automatic", from sage.plot.plot3d.plot3d import plot3d_adaptive x, y = var('x,y') sphinx_plot(plot3d_adaptive(sin(x*y), (x,-pi,pi), (y,-pi,pi), initial_depth=5)) - """ if initial_depth >= max_depth: max_depth = initial_depth @@ -1326,7 +1318,6 @@ def spherical_plot3d(f, urange, vrange, **kwds): x, y = var('x,y') sphinx_plot(spherical_plot3d(1 + 2*cos(2*y), (x, 0, 3*pi/2), (y, 0, pi))) - """ return plot3d(f, urange, vrange, transformation=Spherical('radius', ['azimuth', 'inclination']), **kwds) @@ -1408,7 +1399,7 @@ def cylindrical_plot3d(f, urange, vrange, **kwds): def axes(scale=1, radius=None, **kwds): """ - Creates basic axes in three dimensions. Each axis is a three + Create basic axes in three dimensions. Each axis is a three dimensional arrow object. INPUT: diff --git a/src/sage/plot/plot3d/plot_field3d.py b/src/sage/plot/plot3d/plot_field3d.py index a18c49215be..99f9449e2f8 100644 --- a/src/sage/plot/plot3d/plot_field3d.py +++ b/src/sage/plot/plot3d/plot_field3d.py @@ -26,25 +26,25 @@ def plot_vector_field3d(functions, xrange, yrange, zrange, plot_points=5, colors='jet', center_arrows=False, **kwds): r""" - Plot a 3d vector field + Plot a 3d vector field. INPUT: - - ``functions`` -- a list of three functions, representing the x-, + - ``functions`` -- list of three functions, representing the x-, y-, and z-coordinates of a vector - ``xrange``, ``yrange``, and ``zrange`` -- three tuples of the form (var, start, stop), giving the variables and ranges for each axis - - ``plot_points`` -- (default 5) either a number or list of three + - ``plot_points`` -- (default: 5) either a number or list of three numbers, specifying how many points to plot for each axis - - ``colors`` -- (default ``'jet'``) a color, list of colors (which are + - ``colors`` -- (default: ``'jet'``) a color, list of colors (which are interpolated between), or matplotlib colormap name, giving the coloring of the arrows. If a list of colors or a colormap is given, coloring is done as a function of length of the vector - - ``center_arrows`` -- (default ``False``) If ``True``, draw the arrows + - ``center_arrows`` -- (default: ``False``) if ``True``, draw the arrows centered on the points; otherwise, draw the arrows with the tail at the point diff --git a/src/sage/plot/plot3d/revolution_plot3d.py b/src/sage/plot/plot3d/revolution_plot3d.py index 6349fabbdd5..6c16263d971 100644 --- a/src/sage/plot/plot3d/revolution_plot3d.py +++ b/src/sage/plot/plot3d/revolution_plot3d.py @@ -33,34 +33,46 @@ def revolution_plot3d(curve,trange,phirange=None,parallel_axis='z',axis=(0,0),pr There are three ways to call this function: - - ``revolution_plot3d(f,trange)`` where `f` is a function located in the `x z` plane. + - ``revolution_plot3d(f,trange)`` where `f` is a function located in the + `x z` plane. - - ``revolution_plot3d((f_x,f_z),trange)`` where `(f_x,f_z)` is a parametric curve on the `x z` plane. + - ``revolution_plot3d((f_x,f_z),trange)`` where `(f_x,f_z)` is a parametric + curve on the `x z` plane. - - ``revolution_plot3d((f_x,f_y,f_z),trange)`` where `(f_x,f_y,f_z)` can be any parametric curve. + - ``revolution_plot3d((f_x,f_y,f_z),trange)`` where `(f_x,f_y,f_z)` can be + any parametric curve. INPUT: - - ``curve`` -- A curve to be revolved, specified as a function, a 2-tuple or a 3-tuple. + - ``curve`` -- a curve to be revolved, specified as a function, a 2-tuple + or a 3-tuple - - ``trange`` -- A 3-tuple `(t,t_{\min},t_{\max})` where t is the independent variable of the curve. + - ``trange`` -- a 3-tuple `(t,t_{\min},t_{\max})` where t is the + independent variable of the curve - - ``phirange`` -- A 2-tuple of the form `(\phi_{\min},\phi_{\max})`, (default `(0,\pi)`) that specifies the angle in which the curve is to be revolved. + - ``phirange`` -- a 2-tuple of the form `(\phi_{\min},\phi_{\max})` + (default: `(0,\pi)`) that specifies the angle in which the curve is to be + revolved - - ``parallel_axis`` -- A string (one of ``'x'``, ``'y'``, ``'z'``) that specifies the coordinate axis parallel to the revolution axis. + - ``parallel_axis`` -- string (one of ``'x'``, ``'y'``, ``'z'``) that + specifies the coordinate axis parallel to the revolution axis - - ``axis`` -- A 2-tuple that specifies the position of the revolution axis. If ``parallel_axis`` is: + - ``axis`` -- a 2-tuple that specifies the position of the revolution axis. + If ``parallel_axis`` is: - - ``'z'`` -- then ``axis`` is the point in which the revolution axis intersects the `x` `y` plane. + - ``'z'`` -- then ``axis`` is the point in which the revolution axis + intersects the `x` `y` plane - - ``'x'`` -- then ``axis`` is the point in which the revolution axis intersects the `y` `z` plane. + - ``'x'`` -- then ``axis`` is the point in which the revolution axis + intersects the `y` `z` plane - - ``'y'`` -- then ``axis`` is the point in which the revolution axis intersects the `x` `z` plane. + - ``'y'`` -- then ``axis`` is the point in which the revolution axis + intersects the `x` `z` plane - - ``print_vector`` -- If ``True``, the parametrization of the surface of revolution will be printed. - - - ``show_curve`` -- If ``True``, the curve will be displayed. + - ``print_vector`` -- if ``True``, the parametrization of the surface of + revolution will be printed + - ``show_curve`` -- if ``True``, the curve will be displayed EXAMPLES: diff --git a/src/sage/plot/plot3d/shapes.pyx b/src/sage/plot/plot3d/shapes.pyx index 393fa10d7bc..6dcf6564714 100644 --- a/src/sage/plot/plot3d/shapes.pyx +++ b/src/sage/plot/plot3d/shapes.pyx @@ -117,22 +117,22 @@ class Box(IndexFaceSet): A red rectangular box:: - sage: show(Box([2,3,4], color="red")) + sage: show(Box([2,3,4], color='red')) .. PLOT:: from sage.plot.plot3d.shapes import Box - sphinx_plot(Box([2,3,4], color="red")) + sphinx_plot(Box([2,3,4], color='red')) A stack of boxes:: - sage: show(sum(Box([2,3,1], color="red").translate((0,0,6*i)) + sage: show(sum(Box([2,3,1], color='red').translate((0,0,6*i)) ....: for i in [0..3])) .. PLOT:: from sage.plot.plot3d.shapes import Box - P = sum([Box([2,3,1], color="red").translate((0,0,6*i)) for i in range(0,4)]) + P = sum([Box([2,3,1], color='red').translate((0,0,6*i)) for i in range(0,4)]) sphinx_plot(P) A sinusoidal stack of multicolored boxes:: @@ -147,7 +147,6 @@ class Box(IndexFaceSet): from sage.plot.plot3d.shapes import Box B = sum([Box([2,4,1/4], color=(i/4.0,i/5.0,1)).translate((sin(i),0,5-i)) for i in range(0,21)]) sphinx_plot(B) - """ def __init__(self, *size, **kwds): """ @@ -196,13 +195,11 @@ def ColorCube(size, colors, opacity=1, **kwds): INPUT: - ``size`` -- 3-tuple of sizes (same as for box and frame) - - ``colors`` -- a list of either 3 or 6 colors + - ``colors`` -- list of either 3 or 6 colors - ``opacity`` -- (default: 1) opacity of cube sides - ``**kwds`` -- passed to the face constructor - OUTPUT: - - a 3d graphics object + OUTPUT: a 3d graphics object EXAMPLES: @@ -233,7 +230,6 @@ def ColorCube(size, colors, opacity=1, **kwds): from sage.plot.plot3d.shapes import ColorCube c = ColorCube([0.5,0.5,0.5], ['red', 'blue', 'green']) sphinx_plot(c) - """ if not isinstance(size, (tuple, list)): size = (size, size, size) @@ -262,7 +258,7 @@ cdef class Cone(ParametricSurface): - ``height`` -- positive real number - - ``closed`` -- whether or not to include the base (default ``True``) + - ``closed`` -- whether or not to include the base (default: ``True``) - ``**kwds`` -- passed to the ParametricSurface constructor @@ -314,7 +310,6 @@ cdef class Cone(ParametricSurface): T = sum(Cone(exp(-n/5.0), 4/3*exp(-n/5.0), color=(0, .5, 0)).translate(0, 0, -3*exp(-n/5.0)) for n in range(8)) T += Cone(1/8, 1, color='brown').translate(0, 0, -3) sphinx_plot(T) - """ def __init__(self, radius, height, closed=True, **kwds): """ @@ -382,7 +377,7 @@ cdef class Cylinder(ParametricSurface): - ``height`` -- positive real number - - ``closed`` -- whether or not to include the ends (default ``True``) + - ``closed`` -- whether or not to include the ends (default: ``True``) - ``**kwds`` -- passed to the :class:`ParametricSurface` constructor @@ -427,7 +422,6 @@ cdef class Cylinder(ParametricSurface): G += G.translate(2.3, 0, -.5) G += G.translate(3.5, 2, -1) sphinx_plot(G) - """ def __init__(self, radius, height, closed=True, **kwds): """ @@ -684,10 +678,10 @@ def arrow3d(start, end, width=1, radius=None, head_radius=None, head_len=None, * - ``start`` -- (x,y,z) point; the starting point of the arrow - ``end`` -- (x,y,z) point; the end point - - ``width`` -- (default: 1); how wide the arrow is + - ``width`` -- (default: 1) how wide the arrow is - ``radius`` -- (default: ``width/50.0``) the radius of the arrow - - ``head_radius`` -- (default: ``3*radius``); radius of arrow head - - ``head_len`` -- (default: ``3*head_radius``); len of arrow head + - ``head_radius`` -- (default: ``3*radius``) radius of arrow head + - ``head_len`` -- (default: ``3*head_radius``) len of arrow head EXAMPLES: @@ -839,7 +833,6 @@ cdef class Sphere(ParametricSurface): from sage.plot.plot3d.shapes import Sphere S = Sphere(1).scale(1,2,1/2) sphinx_plot(S) - """ def __init__(self, radius, **kwds): """ @@ -987,9 +980,7 @@ cdef class Torus(ParametricSurface): - ``R`` -- (default: ``1``) outer radius - ``r`` -- (default: ``.3``) inner radius - OUTPUT: - - a 3d torus + OUTPUT: a 3d torus EXAMPLES:: @@ -1036,7 +1027,6 @@ cdef class Torus(ParametricSurface): D = Torus(1, .4, color=(.5, .3, .2)) + Torus(1, .3, color='yellow').translate(0, 0, .15) G = sum(D.translate(RDF.random_element(-.2, .2), RDF.random_element(-.2, .2), .8*t) for t in range(10)) sphinx_plot(G) - """ def __init__(self, R=1, r=.3, **kwds): """ @@ -1101,7 +1091,6 @@ class Text(PrimitiveObject): from sage.plot.plot3d.shapes import Text pts = [(RealField(10)**3).random_element() for k in range(20)] sphinx_plot(sum(Text(str(P)).translate(P) for P in pts)) - """ def __init__(self, string, **kwds): """ @@ -1223,7 +1212,6 @@ class Text(PrimitiveObject): 'x': 0.0, 'y': 0.0, 'z': 0.0})] - """ center = (float(0), float(0), float(0)) if render_params.transform is not None: @@ -1251,7 +1239,7 @@ def _validate_threejs_text_style(style): INPUT: - - ``style`` -- a dict optionally containing keys: 'color', 'fontSize', + - ``style`` -- dictionary optionally containing keys: 'color', 'fontSize', 'fontFamily', 'fontStyle', 'fontWeight', and 'opacity' OUTPUT: @@ -1325,7 +1313,6 @@ def _validate_threejs_text_style(style): sage: validate(dict(opacity=0.5)) {...'opacity': 0.5} - """ default_color = '#000000' # black color = style.get('color', default_color) diff --git a/src/sage/plot/plot3d/shapes2.py b/src/sage/plot/plot3d/shapes2.py index d188abad674..1f5f8f4739a 100644 --- a/src/sage/plot/plot3d/shapes2.py +++ b/src/sage/plot/plot3d/shapes2.py @@ -52,15 +52,15 @@ def line3d(points, thickness=1, radius=None, arrow_head=False, **kwds): INPUT: - - ``points`` -- a list of at least 2 points + - ``points`` -- list of at least 2 points - ``thickness`` -- (default: 1) - - ``radius`` -- (default: None) + - ``radius`` -- (default: ``None``) - ``arrow_head`` -- (default: ``False``) - - ``color`` -- a string (``"red"``, ``"green"`` etc) + - ``color`` -- string (``'red'``, ``'green'`` etc) or a tuple (r, g, b) with r, g, b numbers between 0 and 1 - ``opacity`` -- (default: 1) if less than 1 then is @@ -195,7 +195,7 @@ def tetra(col): @rename_keyword(alpha='opacity') -@options(opacity=1, color="blue", aspect_ratio=[1, 1, 1], thickness=2) +@options(opacity=1, color='blue', aspect_ratio=[1, 1, 1], thickness=2) def bezier3d(path, **options): """ Draw a 3-dimensional bezier path. @@ -205,18 +205,18 @@ def bezier3d(path, **options): INPUT: - - ``path`` -- a list of curves, which each is a list of points. See further - detail below. + - ``path`` -- list of curves, which each is a list of points. See further + detail below - - ``thickness`` -- (default: 2) + - ``thickness`` -- (default: 2) - - ``color`` -- a string (``"red"``, ``"green"`` etc) - or a tuple (r, g, b) with r, g, b numbers between 0 and 1 + - ``color`` -- string (``'red'``, ``'green'`` etc) + or a tuple (r, g, b) with r, g, b numbers between 0 and 1 - - ``opacity`` -- (default: 1) if less than 1 then is - transparent + - ``opacity`` -- (default: 1) if less than 1 then is + transparent - - ``aspect_ratio`` -- (default: [1,1,1]) + - ``aspect_ratio`` -- (default: [1,1,1]) The path is a list of curves, and each curve is a list of points. Each point is a tuple (x,y,z). @@ -416,10 +416,10 @@ def frame3d(lower_left, upper_right, **kwds): INPUT: - ``lower_left`` -- the lower left corner of the frame, as a - list, tuple, or vector. + list, tuple, or vector - ``upper_right`` -- the upper right corner of the frame, as a - list, tuple, or vector. + list, tuple, or vector EXAMPLES: @@ -462,10 +462,10 @@ def frame_labels(lower_left, upper_right, INPUT: - ``lower_left`` -- the lower left corner of the frame, as a - list, tuple, or vector. + list, tuple, or vector - ``upper_right`` -- the upper right corner of the frame, as a - list, tuple, or vector. + list, tuple, or vector - ``label_lower_left`` -- the label for the lower left corner of the frame, as a list, tuple, or vector. This label must actually @@ -476,7 +476,7 @@ def frame_labels(lower_left, upper_right, have all coordinates greater than the coordinates of the other label. - ``eps`` -- (default: 1) a parameter for how far away from the frame - to put the labels. + to put the labels EXAMPLES: @@ -553,22 +553,22 @@ def ruler(start, end, ticks=4, sub_ticks=4, absolute=False, snap=False, **kwds): INPUT: - ``start`` -- the beginning of the ruler, as a list, - tuple, or vector. + tuple, or vector - ``end`` -- the end of the ruler, as a list, tuple, - or vector. + or vector - ``ticks`` -- (default: 4) the number of major ticks - shown on the ruler. + shown on the ruler - ``sub_ticks`` -- (default: 4) the number of shown - subdivisions between each major tick. + subdivisions between each major tick - - ``absolute`` -- (default: ``False``) if ``True``, makes a huge ruler - in the direction of an axis. + - ``absolute`` -- boolean (default: ``False``); if ``True``, makes a huge ruler + in the direction of an axis - - ``snap`` -- (default: ``False``) if ``True``, snaps to an implied - grid. + - ``snap`` -- boolean (default: ``False``); if ``True``, snaps to an implied + grid EXAMPLES: @@ -685,16 +685,16 @@ def ruler_frame(lower_left, upper_right, ticks=4, sub_ticks=4, **kwds): INPUT: - ``lower_left`` -- the lower left corner of the frame, as a - list, tuple, or vector. + list, tuple, or vector - ``upper_right`` -- the upper right corner of the frame, as a - list, tuple, or vector. + list, tuple, or vector - ``ticks`` -- (default: 4) the number of major ticks - shown on each ruler. + shown on each ruler - ``sub_ticks`` -- (default: 4) the number of shown - subdivisions between each major tick. + subdivisions between each major tick EXAMPLES: @@ -736,7 +736,7 @@ def sphere(center=(0, 0, 0), size=1, **kwds): - `(x,y,z)` -- center (default: (0,0,0)) - - ``size`` -- the radius (default: 1) + - ``size`` -- the radius (default: 1) EXAMPLES: A simple sphere:: @@ -795,11 +795,11 @@ def text3d(txt, x_y_z, **kwds): INPUT: - - ``txt`` -- some text + - ``txt`` -- some text - - ``(x,y,z)`` -- position tuple `(x,y,z)` + - ``x_y_z`` -- position tuple `(x,y,z)` - - ``**kwds`` -- standard 3d graphics options + - ``**kwds`` -- standard 3d graphics options EXAMPLES: @@ -859,7 +859,6 @@ def text3d(txt, x_y_z, **kwds): sage: def echo(o): ....: return text3d("Echo!", (0, 0, o), opacity=o) sage: show(sum([echo(o) for o in (0.1, 0.2, .., 1)]), viewer='threejs') - """ (x, y, z) = x_y_z if 'color' not in kwds and 'rgbcolor' not in kwds: @@ -877,9 +876,9 @@ class Point(PrimitiveObject): INPUT: - - ``center`` -- point (3-tuple) + - ``center`` -- point (3-tuple) - - ``size`` -- (default: 1) + - ``size`` -- (default: 1) EXAMPLES: @@ -909,7 +908,7 @@ def __init__(self, center, size=1, **kwds): def bounding_box(self): """ - Returns the lower and upper corners of a 3-D bounding box for ``self``. + Return the lower and upper corners of a 3-D bounding box for ``self``. This is used for rendering and ``self`` should fit entirely within this box. In this case, we simply return the center of the point. @@ -999,7 +998,6 @@ def threejs_repr(self, render_params): sage: P.threejs_repr(P.default_render_params()) [('point', {'color': '#6666ff', 'opacity': 1.0, 'point': (0.0, 0.0, 0.0), 'size': 5.0})] - """ transform = render_params.transform center = tuple(float(coord) for coord in self.loc) @@ -1038,9 +1036,9 @@ class Line(PrimitiveObject): - ``thickness`` -- (default: 5) diameter of the line - ``corner_cutoff`` -- (default: 0.5) threshold for - smoothing (see :meth:`corners`). + smoothing (see :meth:`corners`) - - ``arrow_head`` -- (default: ``False``) if ``True`` make + - ``arrow_head`` -- boolean (default: ``False``); if ``True`` make this curve into an arrow The parameter ``corner_cutoff`` is a bound for the cosine of the @@ -1214,13 +1212,13 @@ def corners(self, corner_cutoff=None, max_len=None): INPUT: - - ``corner_cutoff`` -- (default: ``None``) If the + - ``corner_cutoff`` -- (default: ``None``) if the cosine of the angle between adjacent line segments is smaller than this bound, then there will be a sharp corner in the path. Otherwise, the path is smoothed. If ``None``, then the default value 0.5 is used. - - ``max_len`` -- (default: ``None``) Maximum number + - ``max_len`` -- (default: ``None``) maximum number of points allowed in a single path. If this is set, this creates corners at smooth points in order to break the path into smaller pieces. @@ -1373,7 +1371,6 @@ def threejs_repr(self, render_params): sage: A_repr = A.threejs_repr(A.default_render_params()) sage: A_repr == L_repr True - """ reprs = [] points = [tuple(float(coord) for coord in p) for p in self.points] @@ -1414,16 +1411,16 @@ def point3d(v, size=5, **kwds): INPUT: - - ``v`` -- a point or list of points + - ``v`` -- a point or list of points - - ``size`` -- (default: 5) size of the point (or - points) + - ``size`` -- (default: 5) size of the point (or + points) - - ``color`` -- a string (``"red"``, ``"green"`` etc) - or a tuple (r, g, b) with r, g, b numbers between 0 and 1 + - ``color`` -- string (``'red'``, ``'green'`` etc) + or a tuple (r, g, b) with r, g, b numbers between 0 and 1 - - ``opacity`` -- (default: 1) if less than 1 then is - transparent + - ``opacity`` -- (default: 1) if less than 1 then is + transparent EXAMPLES:: diff --git a/src/sage/plot/plot3d/tachyon.py b/src/sage/plot/plot3d/tachyon.py index c4f136ec157..83315e33368 100644 --- a/src/sage/plot/plot3d/tachyon.py +++ b/src/sage/plot/plot3d/tachyon.py @@ -179,26 +179,26 @@ class Tachyon(WithEqualityById, SageObject): INPUT: - - ``xres`` -- (default 350) - - ``yres`` -- (default 350) - - ``zoom`` -- (default 1.0) - - ``antialiasing`` -- (default ``False``) - - ``aspectratio`` -- (default 1.0) - - ``raydepth`` -- (default 8) - - ``camera_position`` -- (default (-3, 0, 0)) - - ``updir`` -- (default (0, 0, 1)) - - ``look_at`` -- (default (0,0,0)) - - ``viewdir`` -- (default ``None``), otherwise list of three numbers - - ``projection`` -- ``'PERSPECTIVE'`` (default), ``'perspective_dof'`` - or ``'fisheye'``. - - ``frustum`` -- (default ``''``), otherwise list of four numbers. Only + - ``xres`` -- (default: 350) + - ``yres`` -- (default: 350) + - ``zoom`` -- (default: 1.0) + - ``antialiasing`` -- (default: ``False``) + - ``aspectratio`` -- (default: 1.0) + - ``raydepth`` -- (default: 8) + - ``camera_position`` -- (default: (-3, 0, 0)) + - ``updir`` -- (default: (0, 0, 1)) + - ``look_at`` -- (default: (0,0,0)) + - ``viewdir`` -- (default: ``None``) otherwise list of three numbers + - ``projection`` -- ``'PERSPECTIVE'`` (default) ``'perspective_dof'`` + or ``'fisheye'`` + - ``frustum`` -- (default: ``''``) otherwise list of four numbers. Only used with ``projection='fisheye'``. - - ``focallength`` -- (default ''), otherwise a number. Only used + - ``focallength`` -- (default: ``''``) otherwise a number. Only used with ``projection='perspective_dof'``. - - ``aperture`` -- (default ''), otherwise a number. Only used + - ``aperture`` -- (default: ``''``) otherwise a number. Only used with ``projection='perspective_dof'``. - OUTPUT: A Tachyon 3d scene. + OUTPUT: a Tachyon 3d scene Note that the coordinates are by default such that `z` is up, positive `y` is to the {left} and `x` is toward @@ -462,36 +462,36 @@ def save_image(self, filename=None, *args, **kwds): def save(self, filename='sage.png', verbose=None, extra_opts=''): r""" - Save rendering of the tachyon scene + Save rendering of the tachyon scene. INPUT: - - ``filename`` -- (default: 'sage.png') output - filename; the extension of the filename determines the type. - Supported types include: + - ``filename`` -- (default: ``'sage.png'``) output + filename; the extension of the filename determines the type. + Supported types include: - - ``tga`` -- 24-bit (uncompressed) + - ``tga`` -- 24-bit (uncompressed) - - ``bmp`` -- 24-bit Windows BMP (uncompressed) + - ``bmp`` -- 24-bit Windows BMP (uncompressed) - - ``ppm`` -- 24-bit PPM (uncompressed) + - ``ppm`` -- 24-bit PPM (uncompressed) - - ``rgb`` -- 24-bit SGI RGB (uncompressed) + - ``rgb`` -- 24-bit SGI RGB (uncompressed) - - ``png`` -- 24-bit PNG (compressed, lossless) + - ``png`` -- 24-bit PNG (compressed, lossless) - - ``verbose`` -- integer (default: ``None``); if no verbosity setting - is supplied, the verbosity level set by - ``sage.misc.verbose.set_verbose`` is used. + - ``verbose`` -- integer (default: ``None``); if no verbosity setting + is supplied, the verbosity level set by + ``sage.misc.verbose.set_verbose`` is used. - - ``0`` -- silent + - ``0`` -- silent - - ``1`` -- some output + - ``1`` -- some output - - ``2`` -- very verbose output + - ``2`` -- very verbose output - - ``extra_opts`` -- passed directly to tachyon command - line. Use tachyon_rt.usage() to see some of the possibilities. + - ``extra_opts`` -- passed directly to tachyon command + line. Use ``tachyon_rt.usage()`` to see some of the possibilities. EXAMPLES:: @@ -508,7 +508,7 @@ def save(self, filename='sage.png', verbose=None, extra_opts=''): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -711,7 +711,7 @@ def texfunc(self, type=0, center=(0, 0, 0), rotate=(0, 0, 0), r""" INPUT: - - ``type`` -- (default: 0) + - ``type`` -- (default: 0) 0. No special texture, plain shading 1. 3D checkerboard function, like a rubik's cube @@ -725,10 +725,9 @@ def texfunc(self, type=0, center=(0, 0, 0), rotate=(0, 0, 0), 8. Spherical Image Map, requires ppm filename (with path) 9. Planar Image Map, requires ppm filename (with path) - - ``center`` -- (default: (0,0,0)) - - ``rotate`` -- (default: (0,0,0)) - - ``scale`` -- (default: (1,1,1)) - + - ``center`` -- (default: (0,0,0)) + - ``rotate`` -- (default: (0,0,0)) + - ``scale`` -- (default: (1,1,1)) EXAMPLES: We draw an infinite checkerboard:: @@ -745,32 +744,32 @@ def texfunc(self, type=0, center=(0, 0, 0), rotate=(0, 0, 0), def texture(self, name, ambient=0.2, diffuse=0.8, specular=0.0, opacity=1.0, color=(1.0, 0.0, 0.5), texfunc=0, phong=0, phongsize=.5, - phongtype="PLASTIC", imagefile=''): + phongtype='PLASTIC', imagefile=''): r""" INPUT: - - ``name`` -- string; the name of the texture (to be - used later) + - ``name`` -- string; the name of the texture (to be + used later) - - ``ambient`` -- (default: 0.2) + - ``ambient`` -- (default: 0.2) - - ``diffuse`` -- (default: 0.8) + - ``diffuse`` -- (default: 0.8) - - ``specular`` -- (default: 0.0) + - ``specular`` -- (default: 0.0) - - ``opacity`` -- (default: 1.0) + - ``opacity`` -- (default: 1.0) - - ``color`` -- (default: (1.0,0.0,0.5)) + - ``color`` -- (default: (1.0,0.0,0.5)) - - ``texfunc`` -- (default: 0); a texture function; this - is either the output of self.texfunc, or a number between 0 and 9, - inclusive. See the docs for self.texfunc. + - ``texfunc`` -- (default: 0) a texture function; this + is either the output of self.texfunc, or a number between 0 and 9, + inclusive. See the docs for self.texfunc. - - ``phong`` -- (default: 0) + - ``phong`` -- (default: 0) - - ``phongsize`` -- (default: 0.5) + - ``phongsize`` -- (default: 0.5) - - ``phongtype`` -- (default: "PLASTIC") + - ``phongtype`` -- (default: ``'PLASTIC'``) EXAMPLES: @@ -925,7 +924,6 @@ def triangle(self, vertex_1, vertex_2, vertex_3, texture): sage: t.triangle([1,2,3],[4,5,6],[7,8,10],'s') sage: t._objects[1].get_vertices() ([1, 2, 3], [4, 5, 6], [7, 8, 10]) - """ self._objects.append(TachyonTriangle(vertex_1, vertex_2, vertex_3, texture)) @@ -968,29 +966,29 @@ def plot(self, f, xmin_xmax, ymin_ymax, texture, grad_f=None, r""" INPUT: - - ``f`` -- Function of two variables, which returns a - float (or coercible to a float) (xmin,xmax) + - ``f`` -- function of two variables, which returns a + float (or coercible to a float) (xmin,xmax) - - ``(ymin,ymax)`` -- defines the rectangle to plot over - texture: Name of texture to be used Optional arguments: + - ``(ymin,ymax)`` -- defines the rectangle to plot over + texture: Name of texture to be used Optional arguments: - - ``grad_f`` -- gradient function. If specified, - smooth triangles will be used. + - ``grad_f`` -- gradient function. If specified, + smooth triangles will be used - - ``max_bend`` -- Cosine of the threshold angle - between triangles used to determine whether or not to recurse after - the minimum depth + - ``max_bend`` -- cosine of the threshold angle + between triangles used to determine whether or not to recurse after + the minimum depth - - ``max_depth`` -- maximum recursion depth. Maximum - triangles plotted = `2^{2*max_depth}` + - ``max_depth`` -- maximum recursion depth. Maximum + triangles plotted = `2^{2*max_depth}` - - ``initial_depth`` -- minimum recursion depth. No - error-tolerance checking is performed below this depth. Minimum - triangles plotted: `2^{2*min_depth}` + - ``initial_depth`` -- minimum recursion depth. No + error-tolerance checking is performed below this depth. Minimum + triangles plotted: `2^{2*min_depth}` - - ``num_colors`` -- Number of rainbow bands to color - the plot with. Texture supplied will be cloned (with different - colors) using the texture_recolor method of the Tachyon object. + - ``num_colors`` -- number of rainbow bands to color + the plot with. Texture supplied will be cloned (with different + colors) using the texture_recolor method of the Tachyon object. Plots a function by constructing a mesh with nonstandard sampling @@ -1117,7 +1115,6 @@ def str(self): light center 1.0 1.0 1.0 rad 1.0 color 1.0 1.0 1.0 - """ return fr""" light center {tostr(self._center)} @@ -1193,7 +1190,7 @@ class Texture: def __init__(self, name, ambient=0.2, diffuse=0.8, specular=0.0, opacity=1.0, color=(1.0, 0.0, 0.5), texfunc=0, - phong=0, phongsize=0, phongtype="PLASTIC", imagefile=''): + phong=0, phongsize=0, phongtype='PLASTIC', imagefile=''): r""" Store texture information. diff --git a/src/sage/plot/plot3d/texture.py b/src/sage/plot/plot3d/texture.py index c34d0bdd207..561b8efbc3a 100644 --- a/src/sage/plot/plot3d/texture.py +++ b/src/sage/plot/plot3d/texture.py @@ -91,9 +91,7 @@ def parse_color(info, base=None): - ``info`` -- color, valid color str or number - ``base`` -- tuple of length 3 (default: ``None``) - OUTPUT: - - A tuple or color. + OUTPUT: a tuple or color EXAMPLES: @@ -183,22 +181,20 @@ def __classcall__(cls, id=None, **kwds): INPUT: - - ``id`` -- a texture (default: None), a dict, a color, a - str, a tuple, None or any other type acting as an ID. If ``id`` is - None and keyword ``texture`` is empty, then it returns a unique texture object. + - ``id`` -- a texture (default: ``None``), a dictionary, a color, a + string, a tuple, ``None`` or any other type acting as an ID. If ``id`` is + ``None`` and keyword ``texture`` is empty, then it returns a unique texture object. - ``texture`` -- a texture - - ``color`` -- tuple or str, (default: (.4, .4, 1)) + - ``color`` -- tuple or string (default: (.4, .4, 1)) - ``opacity`` -- number between 0 and 1 (default: 1) - ``ambient`` -- number (default: 0.5) - ``diffuse`` -- number (default: 1) - ``specular`` -- number (default: 0) - ``shininess`` -- number (default: 1) - - ``name`` -- str (default: None) + - ``name`` -- string (default: ``None``) - ``**kwds`` -- other valid keywords - OUTPUT: - - A texture object. + OUTPUT: a texture object EXAMPLES: diff --git a/src/sage/plot/plot3d/tri_plot.py b/src/sage/plot/plot3d/tri_plot.py index 5eb15299fe5..4453d8c574c 100644 --- a/src/sage/plot/plot3d/tri_plot.py +++ b/src/sage/plot/plot3d/tri_plot.py @@ -51,7 +51,7 @@ def __init__(self,a,b,c,color=0): def str(self): """ - Returns a string representation of an instance of the Triangle + Return a string representation of an instance of the Triangle class of the form a b c color @@ -85,7 +85,7 @@ def set_color(self, color): def get_vertices(self): """ - Returns a tuple of vertex coordinates of the triangle. + Return a tuple of vertex coordinates of the triangle. TESTS:: @@ -123,7 +123,7 @@ def __init__(self,a,b,c,da,db,dc,color=0): def str(self): """ - Returns a string representation of the SmoothTriangle of the form + Return a string representation of the SmoothTriangle of the form. a b c color da db dc @@ -141,7 +141,7 @@ def str(self): def get_normals(self): """ - Returns the normals to vertices a, b, and c. + Return the normals to vertices a, b, and c. TESTS:: @@ -221,7 +221,7 @@ def get_colors(self, list): class TrianglePlot: """ - Recursively plots a function of two variables by building squares of 4 triangles, checking at + Recursively plot a function of two variables by building squares of 4 triangles, checking at every stage whether or not each square should be split into four more squares. This way, more planar areas get fewer triangles, and areas with higher curvature get more triangles. """ @@ -452,7 +452,7 @@ def plot_block(self, min_x, mid_x, max_x, min_y, mid_y, max_y, sw_z, nw_z, se_z, def interface(self, n, p, p_c, q, q_c): """ - Takes a pair of lists of points, and compares the (n)th coordinate, and + Take a pair of lists of points, and compares the (n)th coordinate, and "zips" the lists together into one. The "centers", supplied in p_c and q_c are matched up such that the lists describe triangles whose sides are "perfectly" aligned. This algorithm assumes that p and q start and diff --git a/src/sage/plot/plot_field.py b/src/sage/plot/plot_field.py index b1a9505eb81..4a884cf4662 100644 --- a/src/sage/plot/plot_field.py +++ b/src/sage/plot/plot_field.py @@ -62,7 +62,6 @@ def __init__(self, xpos_array, ypos_array, xvec_array, yvec_array, options): sage: x,y = var('x,y') sage: P = plot_vector_field((sin(x),cos(y)), (x,-3,3), (y,-3,3)) sage: Q = loads(dumps(P)) - """ self.xpos_array = xpos_array self.ypos_array = ypos_array @@ -72,7 +71,7 @@ def __init__(self, xpos_array, ypos_array, xvec_array, yvec_array, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -88,7 +87,7 @@ def get_minmax_data(self): def _allowed_options(self): """ - Returns a dictionary with allowed options for PlotField. + Return a dictionary with allowed options for PlotField. EXAMPLES:: @@ -137,7 +136,6 @@ def _repr_(self): zorder The layer level in which to draw 20 - """ return "PlotField defined by a {} x {} vector grid".format( self._options['plot_points'], self._options['plot_points']) diff --git a/src/sage/plot/point.py b/src/sage/plot/point.py index 2f393fe211c..7c2d6bb1ae3 100644 --- a/src/sage/plot/point.py +++ b/src/sage/plot/point.py @@ -45,7 +45,7 @@ class Point(GraphicPrimitive_xydata): - ``ydata`` -- list of y values for points in Point object - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -69,7 +69,7 @@ class Point(GraphicPrimitive_xydata): """ def __init__(self, xdata, ydata, options): """ - Initializes base class Point. + Initialize base class Point. EXAMPLES:: @@ -141,9 +141,8 @@ def plot3d(self, z=0, **kwds): INPUT: - - - ``z`` -- optional 3D height above `xy`-plane. May be a list - if self is a list of points. + - ``z`` -- (optional) 3D height above `xy`-plane; may be a list + if ``self`` is a list of points EXAMPLES: @@ -266,7 +265,7 @@ def _repr_(self): def __getitem__(self, i): """ - Returns tuple of coordinates of point. + Return tuple of coordinates of point. EXAMPLES:: @@ -322,8 +321,8 @@ def point(points, **kwds): INPUT: - - ``points`` -- either a single point (as a tuple), a list of - points, a single complex number, or a list of complex numbers. + - ``points`` -- either a single point (as a tuple), a list of + points, a single complex number, or a list of complex numbers For information regarding additional arguments, see either point2d? or point3d?. @@ -405,8 +404,8 @@ def point2d(points, **options): INPUT: - - ``points`` -- either a single point (as a tuple), a list of - points, a single complex number, or a list of complex numbers + - ``points`` -- either a single point (as a tuple), a list of + points, a single complex number, or a list of complex numbers - ``alpha`` -- how transparent the point is @@ -581,7 +580,7 @@ def point2d(points, **options): Verify that :issue:`36153` does not arise:: - sage: P = point((0.5, 0.5), legend_label="test") + sage: P = point((0.5, 0.5), legend_label='test') """ from sage.plot.plot import xydata_from_point_list from sage.plot.all import Graphics diff --git a/src/sage/plot/polygon.py b/src/sage/plot/polygon.py index 2914240e761..8f2fa424725 100644 --- a/src/sage/plot/polygon.py +++ b/src/sage/plot/polygon.py @@ -35,7 +35,7 @@ class Polygon(GraphicPrimitive_xydata): - ``ydata`` -- list of `y`-coordinates of points defining Polygon - - ``options`` -- dict of valid plot options to pass to constructor + - ``options`` -- dictionary of valid plot options to pass to constructor EXAMPLES: @@ -64,12 +64,12 @@ class Polygon(GraphicPrimitive_xydata): :: - sage: polygon2d([(1, 1), (0, 1), (1, 0)], fill=False, linestyle="dashed") + sage: polygon2d([(1, 1), (0, 1), (1, 0)], fill=False, linestyle='dashed') Graphics object consisting of 1 graphics primitive """ def __init__(self, xdata, ydata, options): """ - Initializes base class Polygon. + Initialize base class Polygon. EXAMPLES:: @@ -97,7 +97,7 @@ def _repr_(self): def __getitem__(self, i): """ - Return `i`-th vertex of Polygon primitive + Return `i`-th vertex of Polygon primitive. It is starting count from 0th vertex. @@ -112,7 +112,7 @@ def __getitem__(self, i): def __setitem__(self, i, point): """ - Change `i`-th vertex of Polygon primitive + Change `i`-th vertex of Polygon primitive. It is starting count from 0th vertex. @@ -191,8 +191,8 @@ def plot3d(self, z=0, **kwds): INPUT: - - ``z`` -- optional 3D height above `xy`-plane, or a list of - heights corresponding to the list of 2D polygon points. + - ``z`` -- (optional) 3D height above `xy`-plane, or a list of + heights corresponding to the list of 2D polygon points EXAMPLES: @@ -366,13 +366,13 @@ def polygon2d(points, **options): and the interior as follows:: sage: L = [[0,0]]+[[i/100, 1.1+cos(i/20)] for i in range(100)]+[[1,0]] # needs sage.symbolic - sage: polygon2d(L, color="limegreen", edgecolor="black", axes=False) # needs sage.symbolic + sage: polygon2d(L, color='limegreen', edgecolor='black', axes=False) # needs sage.symbolic Graphics object consisting of 1 graphics primitive .. PLOT:: L = [[0,0]]+[[i*0.01, 1.1+cos(i*0.05)] for i in range(100)]+[[1,0]] - P = polygon2d(L, color="limegreen", edgecolor="black", axes=False) + P = polygon2d(L, color='limegreen', edgecolor='black', axes=False) sphinx_plot(P) Some modern art -- a random polygon, with legend:: @@ -528,7 +528,7 @@ def polygon2d(points, **options): Verify that :issue:`36153` does not arise:: - sage: P = polygon2d([[1,2], [5,6], [5,0]], legend_label="test") + sage: P = polygon2d([[1,2], [5,6], [5,0]], legend_label='test') AUTHORS: diff --git a/src/sage/plot/primitive.py b/src/sage/plot/primitive.py index ee9966846b1..ef69f7f4344 100644 --- a/src/sage/plot/primitive.py +++ b/src/sage/plot/primitive.py @@ -61,9 +61,7 @@ def _allowed_options(self): """ Return the allowed options for a graphics primitive. - OUTPUT: - - - a reference to a dictionary. + OUTPUT: a reference to a dictionary EXAMPLES:: @@ -219,7 +217,7 @@ def _repr_(self): class GraphicPrimitive_xydata(GraphicPrimitive): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: diff --git a/src/sage/plot/scatter_plot.py b/src/sage/plot/scatter_plot.py index 781854d372c..3b07349cb9c 100644 --- a/src/sage/plot/scatter_plot.py +++ b/src/sage/plot/scatter_plot.py @@ -56,7 +56,7 @@ def __init__(self, xdata, ydata, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -142,26 +142,26 @@ def _render_on_subplot(self, subplot): @options(alpha=1, markersize=50, marker='o', zorder=5, facecolor='#fec7b8', edgecolor='black', clip=True, aspect_ratio='automatic') def scatter_plot(datalist, **options): """ - Returns a Graphics object of a scatter plot containing all points in + Return a Graphics object of a scatter plot containing all points in the datalist. Type ``scatter_plot.options`` to see all available plotting options. INPUT: - - ``datalist`` -- a list of tuples ``(x,y)`` + - ``datalist`` -- list of tuples ``(x,y)`` - - ``alpha`` -- default: 1 + - ``alpha`` -- (default: 1) - - ``markersize`` -- default: 50 + - ``markersize`` -- (default: 50) - - ``marker`` -- The style of the markers (default ``"o"``). See the - documentation of :func:`plot` for the full list of markers. + - ``marker`` -- the style of the markers (default: ``'o'``); see the + documentation of :func:`plot` for the full list of markers - - ``facecolor`` -- default: ``'#fec7b8'`` + - ``facecolor`` -- (default: ``'#fec7b8'``) - - ``edgecolor`` -- default: ``'black'`` + - ``edgecolor`` -- (default: ``'black'``) - - ``zorder`` -- default: 5 + - ``zorder`` -- (default: 5) EXAMPLES:: diff --git a/src/sage/plot/step.py b/src/sage/plot/step.py index 4023686f9bd..85d4bd83c01 100644 --- a/src/sage/plot/step.py +++ b/src/sage/plot/step.py @@ -31,11 +31,11 @@ def plot_step_function(v, vertical_lines=True, **kwds): - ``v`` -- list of pairs (a,b) - - ``vertical_lines`` -- bool (default: ``True``) if ``True``, draw + - ``vertical_lines`` -- boolean (default: ``True``); if ``True``, draw vertical risers at each step of this step function. Technically these vertical lines are not part of the graph of this function, but they look very nice in the plot, so we - include them by default + include them by default. EXAMPLES: diff --git a/src/sage/plot/streamline_plot.py b/src/sage/plot/streamline_plot.py index d2cb11088c7..b69a05b37bf 100644 --- a/src/sage/plot/streamline_plot.py +++ b/src/sage/plot/streamline_plot.py @@ -56,7 +56,6 @@ def __init__(self, xpos_array, ypos_array, xvec_array, yvec_array, options): sage: x, y = var('x y') sage: P = streamline_plot((sin(x), cos(y)), (x,-3,3), (y,-3,3)) sage: Q = loads(dumps(P)) - """ self.xpos_array = xpos_array self.ypos_array = ypos_array @@ -66,7 +65,7 @@ def __init__(self, xpos_array, ypos_array, xvec_array, yvec_array, options): def get_minmax_data(self): """ - Returns a dictionary with the bounding box data. + Return a dictionary with the bounding box data. EXAMPLES:: @@ -85,7 +84,7 @@ def get_minmax_data(self): def _allowed_options(self): """ - Returns a dictionary with allowed options for StreamlinePlot. + Return a dictionary with allowed options for ``StreamlinePlot``. EXAMPLES:: @@ -127,7 +126,6 @@ def _repr_(self): zorder The layer level in which to draw 20 - """ return "StreamlinePlot defined by a {} x {} vector grid".format( self._options['plot_points'], self._options['plot_points']) @@ -273,7 +271,6 @@ def streamline_plot(f_g, xrange, yrange, **options): Streamlines currently pass close to ``start_points`` but do not necessarily pass directly through them. That is part of the behavior of matplotlib, not an error on your part. - """ # Parse the function input if isinstance(f_g, (list, tuple)): diff --git a/src/sage/plot/text.py b/src/sage/plot/text.py index c641528be87..32b0cc712c4 100644 --- a/src/sage/plot/text.py +++ b/src/sage/plot/text.py @@ -36,7 +36,6 @@ class Text(GraphicPrimitive): .. PLOT:: sphinx_plot(text("I like Fibonacci",(3,5))) - """ def __init__(self, string, point, options): """ @@ -100,7 +99,6 @@ def _allowed_options(self): 'The layer level in which to draw' sage: T[0]._allowed_options()['rotation'] 'How to rotate the text: angle in degrees, vertical, horizontal' - """ return {'fontsize': 'How big the text is. Either the size in points or a relative size, e.g. \'smaller\', \'x-large\', etc', 'fontstyle': 'A string either \'normal\', \'italic\' or \'oblique\'', @@ -133,7 +131,6 @@ def _plot3d_options(self, options=None): sage: s=t.plot3d() sage: s.jmol_repr(s.testing_render_params())[0][1] 'color atom [0,0,255]' - """ if options is None: options = dict(self.options()) @@ -162,7 +159,6 @@ def plot3d(self, **kwds): 'label "ABC"' sage: s._trans (1.0, 1.0, 0) - """ from sage.plot.plot3d.shapes2 import text3d options = self._plot3d_options() @@ -173,11 +169,10 @@ def _render_on_subplot(self, subplot): """ TESTS:: - sage: t1 = text("Hello",(1,1), vertical_alignment="top", fontsize=30, rgbcolor='black') - sage: t2 = text("World", (1,1), horizontal_alignment="left", fontsize=20, zorder=-1) + sage: t1 = text("Hello", (1,1), vertical_alignment='top', fontsize=30, rgbcolor='black') + sage: t2 = text("World", (1,1), horizontal_alignment='left', fontsize=20, zorder=-1) sage: t1 + t2 # render the sum Graphics object consisting of 2 graphics primitives - """ options = self.options() opts = {} @@ -227,39 +222,42 @@ def text(string, xy, **options): 2D OPTIONS: - - ``fontsize`` -- How big the text is. Either an integer that + - ``fontsize`` -- how big the text is. Either an integer that specifies the size in points or a string which specifies a size (one of - 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large') + ``'xx-small'``, ``'x-small'``, ``'small'``, ``'medium'``, ``'large'``, + ``'x-large'``, ``'xx-large'``). - - ``fontstyle`` -- A string either 'normal', 'italic' or 'oblique' + - ``fontstyle`` -- string either ``'normal'``, ``'italic'`` or ``'oblique'`` - - ``fontweight`` -- A numeric value in the range 0-1000 or a string (one of - 'ultralight', 'light', 'normal', 'regular', 'book',' 'medium', 'roman', - 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black') + - ``fontweight`` -- a numeric value in the range 0-1000 or a string (one of + ``'ultralight'``, ``'light'``, ``'normal'``, ``'regular'``, ``'book'``, + ``'medium'``, ``'roman'``, ``'semibold'``, ``'demibold'``, ``'demi'``, + ``'bold'``, ``'heavy'``, ``'extra bold'``, ``'black'``) - - ``rgbcolor`` -- The color as an RGB tuple + - ``rgbcolor`` -- the color as an RGB tuple - - ``hue`` -- The color given as a hue + - ``hue`` -- the color given as a hue - - ``alpha`` -- A float (0.0 transparent through 1.0 opaque) + - ``alpha`` -- a float (0.0 transparent through 1.0 opaque) - - ``background_color`` -- The background color + - ``background_color`` -- the background color - - ``rotation`` -- How to rotate the text: angle in degrees, vertical, horizontal + - ``rotation`` -- how to rotate the text: angle in degrees, vertical, horizontal - - ``vertical_alignment`` -- How to align vertically: top, center, bottom + - ``vertical_alignment`` -- how to align vertically: top, center, bottom - - ``horizontal_alignment`` -- How to align horizontally: left, center, right + - ``horizontal_alignment`` -- how to align horizontally: left, center, right - - ``zorder`` -- The layer level in which to draw + - ``zorder`` -- the layer level in which to draw - - ``clip`` -- (default: ``False``) Whether to clip or not + - ``clip`` -- boolean (default: ``False``); whether to clip or not - - ``axis_coords`` -- (default: ``False``) If True, use axis coordinates, so that - (0,0) is the lower left and (1,1) upper right, regardless of the x and y - range of plotted values. + - ``axis_coords`` -- boolean (default: ``False``); if ``True``, use axis + coordinates, so that (0,0) is the lower left and (1,1) upper right, + regardless of the x and y range of plotted values - - ``bounding_box`` -- A dictionary specifying a bounding box. Currently the text location. + - ``bounding_box`` -- dictionary specifying a bounding box; currently the + text location EXAMPLES:: @@ -305,30 +303,30 @@ def text(string, xy, **options): :: - sage: text("Sage is really neat!!",(0,0), rotation="vertical") + sage: text("Sage is really neat!!", (0,0), rotation='vertical') Graphics object consisting of 1 graphics primitive .. PLOT:: - sphinx_plot(text("Sage is really neat!!",(0,0), rotation="vertical")) + sphinx_plot(text("Sage is really neat!!", (0,0), rotation='vertical')) You can also align text differently:: - sage: t1 = text("Hello", (1,1), vertical_alignment="top") - sage: t2 = text("World", (1,0.5), horizontal_alignment="left") + sage: t1 = text("Hello", (1,1), vertical_alignment='top') + sage: t2 = text("World", (1,0.5), horizontal_alignment='left') sage: t1 + t2 # render the sum Graphics object consisting of 2 graphics primitives .. PLOT:: - t1 = text("Hello",(1,1), vertical_alignment="top") - t2 = text("World", (1,0.5), horizontal_alignment="left") + t1 = text("Hello", (1,1), vertical_alignment='top') + t2 = text("World", (1,0.5), horizontal_alignment='left') sphinx_plot(t1 + t2) You can save text as part of PDF output:: sage: import tempfile - sage: with tempfile.NamedTemporaryFile(suffix=".pdf") as f: + sage: with tempfile.NamedTemporaryFile(suffix='.pdf') as f: ....: text("sage", (0,0), rgbcolor=(0,0,0)).save(f.name) Some examples of bounding box:: diff --git a/src/sage/probability/probability_distribution.pyx b/src/sage/probability/probability_distribution.pyx index 59ba4a95ab6..fab94479291 100644 --- a/src/sage/probability/probability_distribution.pyx +++ b/src/sage/probability/probability_distribution.pyx @@ -101,7 +101,7 @@ cdef class ProbabilityDistribution: the probability distribution - ``bins`` -- (optional) number of bins to divide the samples - into. + into OUTPUT: @@ -155,13 +155,13 @@ cdef class ProbabilityDistribution: INPUT: - - ``name`` -- file to save the histogram plot (as a PNG). + - ``name`` -- file to save the histogram plot (as a PNG) - ``num_samples`` -- (optional) number of times to sample from the probability distribution - ``bins`` -- (optional) number of bins to divide the samples - into. + into EXAMPLES: @@ -569,7 +569,6 @@ cdef class RealDistribution(ProbabilityDistribution): sage: Xs = [RealDistribution('gaussian', 1).get_random_element() for _ in range(1000)] sage: len(set(Xs)) > 2^^32 True - """ cdef gsl_rng_type *T cdef gsl_rng *r @@ -685,7 +684,6 @@ cdef class RealDistribution(ProbabilityDistribution): sage: T = RealDistribution('gaussian', 1, seed=0) sage: T.get_random_element() # rel tol 4e-16 0.13391860811867587 - """ cdef double result if self.distribution_type == uniform: @@ -1038,19 +1036,17 @@ cdef class GeneralDiscreteDistribution(ProbabilityDistribution): INPUT: - - ``P`` -- list of probabilities. The list will automatically be - normalised if ``sum(P)`` is not equal to 1. + - ``P`` -- list of probabilities; the list will automatically be + normalised if ``sum(P)`` is not equal to 1 - - ``rng`` -- (optional) random number generator to use. May be - one of ``'default'``, ``'luxury'``, or ``'taus'``. + - ``rng`` -- (optional) random number generator to use; may be + one of ``'default'``, ``'luxury'``, or ``'taus'`` - ``seed`` -- (optional) seed to use with the random number - generator. - - OUTPUT: + generator - - a probability distribution where the probability of selecting - ``x`` is ``P[x]``. + OUTPUT: a probability distribution where the probability of selecting + ``x`` is ``P[x]``. EXAMPLES: @@ -1093,12 +1089,12 @@ cdef class GeneralDiscreteDistribution(ProbabilityDistribution): sage: len(set(Xs)) > 2^^32 True - The distribution probabilities must be non-negative:: + The distribution probabilities must be nonnegative:: sage: GeneralDiscreteDistribution([0.1, -0.1]) Traceback (most recent call last): ... - ValueError: The distribution probabilities must be non-negative + ValueError: The distribution probabilities must be nonnegative """ cdef gsl_rng_type * T cdef gsl_rng * r @@ -1163,7 +1159,7 @@ cdef class GeneralDiscreteDistribution(ProbabilityDistribution): for i in range(n): if P[i] < 0: raise ValueError("The distribution probabilities must " - "be non-negative") + "be nonnegative") P_vec[i] = P[i] self.dist = gsl_ran_discrete_preproc(n, P_vec) diff --git a/src/sage/probability/random_variable.py b/src/sage/probability/random_variable.py index 1a779aba083..cb5c0426c5a 100644 --- a/src/sage/probability/random_variable.py +++ b/src/sage/probability/random_variable.py @@ -93,8 +93,8 @@ def __init__(self, X, f, codomain=None, check=False): INPUT: - - X -- a probability space - - f -- a dictionary such that X[x] = value for x in X + - ``X`` -- a probability space + - ``f`` -- dictionary such that X[x] = value for x in X is the discrete function on X """ if not isinstance(X, DiscreteProbabilitySpace): @@ -134,7 +134,7 @@ def function(self): def expectation(self): r""" The expectation of the discrete random variable, namely - `\sum_{x \in S} p(x) X[x]`, where `X` = self and + `\sum_{x \in S} p(x) X[x]`, where `X` = ``self`` and `S` is the probability space of `X`. """ E = 0 @@ -197,8 +197,8 @@ def translation_variance(self, map): def covariance(self, other): r""" - The covariance of the discrete random variable X = self with Y = - other. + The covariance of the discrete random variable X = ``self`` with Y = + ``other``. Let `S` be the probability space of `X` = self, with probability function `p`, and `E(X)` be the @@ -220,8 +220,8 @@ def covariance(self, other): def translation_covariance(self, other, map): r""" - The covariance of the probability space X = self with image of Y = - other under the given map of the probability space. + The covariance of the probability space X = ``self`` with image of Y = + ``other`` under the given map of the probability space. Let `S` be the probability space of `X` = self, with probability function `p`, and `E(X)` be the @@ -259,23 +259,23 @@ def standard_deviation(self): def translation_standard_deviation(self, map): r""" The standard deviation of the translated discrete random variable - `X \circ e`, where `X` = self and `e` = + `X \circ e`, where `X` = ``self`` and `e` = map. - Let `S` be the probability space of `X` = self, + Let `S` be the probability space of `X` = ``self``, with probability function `p`, and `E(X)` be the expectation of `X`. Then the standard deviation of `X` is defined to be .. MATH:: - \sigma(X) = \sqrt{ \sum_{x \in S} p(x) (X(x) - E(x))^2} + \sigma(X) = \sqrt{ \sum_{x \in S} p(x) (X(x) - E(x))^2} """ return sqrt(self.translation_variance(map)) def correlation(self, other): """ - The correlation of the probability space X = self with Y = other. + The correlation of the probability space X = ``self`` with Y = ``other``. """ cov = self.covariance(other) sigX = self.standard_deviation() @@ -286,8 +286,8 @@ def correlation(self, other): def translation_correlation(self, other, map): """ - The correlation of the probability space X = self with image of Y = - other under map. + The correlation of the probability space X = ``self`` with image of Y = + ``other`` under map. """ cov = self.translation_covariance(other, map) sigX = self.standard_deviation() diff --git a/src/sage/quadratic_forms/binary_qf.py b/src/sage/quadratic_forms/binary_qf.py index 37b0beabed5..1a75f415b64 100755 --- a/src/sage/quadratic_forms/binary_qf.py +++ b/src/sage/quadratic_forms/binary_qf.py @@ -80,9 +80,7 @@ class BinaryQF(SageObject): - ``a``, ``b``, ``c`` -- three integers - OUTPUT: - - The binary quadratic form `a x^2 + b xy + c y^2`. + OUTPUT: the binary quadratic form `a x^2 + b xy + c y^2` EXAMPLES:: @@ -300,7 +298,7 @@ def __call__(self, *args): INPUT: - - args -- x and y values, as a pair x, y or a list, tuple, or + - ``args`` -- x and y values, as a pair x, y or a list, tuple, or vector EXAMPLES:: @@ -611,9 +609,7 @@ def determinant(self): whom an integral quadratic form has coefficients `(a, 2b, c)` with `a`, `b`, `c` integers. - OUTPUT: - - The determinant of the matrix:: + OUTPUT: the determinant of the matrix:: [ a b/2] [b/2 c] @@ -773,9 +769,9 @@ def _reduce_indef(self, transformation=False): INPUT: - - ``transformation`` -- bool (default: ``False``); if ``True``, - return both the reduced form and a matrix transforming - ``self`` into the reduced form. + - ``transformation`` -- boolean (default: ``False``); if ``True``, + return both the reduced form and a matrix transforming ``self`` into + the reduced form TESTS:: @@ -835,7 +831,7 @@ def _reduce_indef(self, transformation=False): return Q @cached_method - def reduced_form(self, transformation=False, algorithm="default"): + def reduced_form(self, transformation=False, algorithm='default'): """ Return a reduced form equivalent to ``self``. @@ -843,9 +839,9 @@ def reduced_form(self, transformation=False, algorithm="default"): - ``self`` -- binary quadratic form of non-square discriminant - - ``transformation`` -- boolean (default: ``False``): if ``True``, return + - ``transformation`` -- boolean (default: ``False``); if ``True``, return both the reduced form and a matrix whose :meth:`matrix_action_right` - transforms ``self`` into the reduced form. + transforms ``self`` into the reduced form - ``algorithm`` -- string; the algorithm to use. Valid options are: @@ -1283,7 +1279,7 @@ def is_singular(self): def is_nonsingular(self): """ - Return whether this form is nonsingular, i.e., has non-zero discriminant. + Return whether this form is nonsingular, i.e., has nonzero discriminant. EXAMPLES:: @@ -1302,7 +1298,7 @@ def is_equivalent(self, other, proper=True): INPUT: - - ``proper`` -- bool (default: ``True``); if ``True`` use proper + - ``proper`` -- boolean (default: ``True``); if ``True`` use proper equivalence - ``other`` -- a binary quadratic form @@ -1608,17 +1604,17 @@ def small_prime_value(self, Bmax=1000): raise ValueError("Unable to find a prime value of %s" % self) B += 10 - def solve_integer(self, n, *, algorithm="general", _flag=2): + def solve_integer(self, n, *, algorithm='general', _flag=2): r""" Solve `Q(x, y) = n` in integers `x` and `y` where `Q` is this quadratic form. INPUT: - - ``n`` -- a positive integer or a + - ``n`` -- positive integer or a `:sage:`~sage.structure.factorization.Factorization` object - - ``algorithm`` -- ``"general"`` (default) or ``"cornacchia"`` + - ``algorithm`` -- ``'general'`` (default) or ``'cornacchia'`` - ``_flag`` -- ``1``, ``2`` (default) or ``3``; passed onto the pari function``qfbsolve``. For internal use only. @@ -1689,7 +1685,7 @@ def solve_integer(self, n, *, algorithm="general", _flag=2): sage: xy is None or Q(*xy) == n # needs sage.libs.pari True - Also when using the ``"cornacchia"`` algorithm:: + Also when using the ``'cornacchia'`` algorithm:: sage: # needs sage.libs.pari sage: n = random_prime(10^9) @@ -1833,12 +1829,12 @@ def BinaryQF_reduced_representatives(D, primitive_only=False, proper=True): INPUT: - - ``D`` -- (integer) a discriminant + - ``D`` -- integer; a discriminant - - ``primitive_only`` -- (boolean; default: ``True``): if ``True``, only - return primitive forms. + - ``primitive_only`` -- boolean (default: ``True``); if ``True``, only + return primitive forms - - ``proper`` -- (boolean; default: ``True``) + - ``proper`` -- boolean (default: ``True``) OUTPUT: diff --git a/src/sage/quadratic_forms/constructions.py b/src/sage/quadratic_forms/constructions.py index da51beb1c2e..95bd131215e 100644 --- a/src/sage/quadratic_forms/constructions.py +++ b/src/sage/quadratic_forms/constructions.py @@ -40,7 +40,6 @@ def BezoutianQuadraticForm(f, g): AUTHORS: - Fernando Rodriguez-Villegas, Jonathan Hanke -- added on 11/9/2008 - """ # Check that f and g are polynomials with a common base ring if not isinstance(f, Polynomial) or not isinstance(g, Polynomial): @@ -69,13 +68,13 @@ def BezoutianQuadraticForm(f, g): def HyperbolicPlane_quadratic_form(R, r=1): """ - Constructs the direct sum of `r` copies of the quadratic form `xy` + Construct the direct sum of `r` copies of the quadratic form `xy` representing a hyperbolic plane defined over the base ring `R`. INPUT: - - ``R``: a ring - - ``n`` (integer, default 1) number of copies + - ``R`` -- a ring + - ``n`` -- integer (default: 1); number of copies EXAMPLES:: diff --git a/src/sage/quadratic_forms/count_local_2.pyx b/src/sage/quadratic_forms/count_local_2.pyx index 3ce05a3a413..55c64e56be7 100644 --- a/src/sage/quadratic_forms/count_local_2.pyx +++ b/src/sage/quadratic_forms/count_local_2.pyx @@ -18,12 +18,12 @@ def count_modp__by_gauss_sum(n, p, m, Qdet): INPUT: - - ``n`` -- an integer `\geq 1` + - ``n`` -- integer `\geq 1` - ``p`` -- a prime number > 2 - - ``m`` -- an integer - - ``Qdet`` -- a integer which is non-zero mod `p` + - ``m`` -- integer + - ``Qdet`` -- a integer which is nonzero mod `p` - OUTPUT: an integer `\geq 0` + OUTPUT: integer `\geq 0` EXAMPLES:: @@ -55,12 +55,10 @@ def count_modp__by_gauss_sum(n, p, m, Qdet): ....: == count_modp__by_gauss_sum(3, 3, m, 2) ....: for m in range(3)] [True, True, True] - - """ # Check that Qdet is non-degenerate if Qdet % p == 0: - raise RuntimeError("Qdet must be non-zero.") + raise RuntimeError("Qdet must be nonzero.") # Check that p is prime > 2 if not is_prime(p) or p == 2: @@ -157,9 +155,9 @@ def CountAllLocalTypesNaive(Q, p, k, m, zvec, nzvec): - ``Q`` -- quadratic form over `\ZZ` - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) - - ``zvec``, ``nzvec`` -- a list of integers in ``range(Q.dim())``, or ``None`` + - ``k`` -- integer > 0 + - ``m`` -- integer (depending only on mod `p^k`) + - ``zvec``, ``nzvec`` -- list of integers in ``range(Q.dim())``, or ``None`` OUTPUT: @@ -176,7 +174,6 @@ def CountAllLocalTypesNaive(Q, p, k, m, zvec, nzvec): [6, 6, 0, 0, 0, 0] sage: CountAllLocalTypesNaive(Q, 3, 1, 0, None, None) [15, 12, 1, 2, 0, 2] - """ return CountAllLocalTypesNaive_cdef(Q, p, k, m, zvec, nzvec) @@ -189,7 +186,6 @@ cdef local_solution_type_cdef(Q, p, w, zvec, nzvec): NOTE: No internal checking is done to test if `p` is a prime >=2, or that Q has the same size as `w`. - """ cdef long i cdef long n @@ -218,7 +214,7 @@ cdef local_solution_type_cdef(Q, p, w, zvec, nzvec): # print("IsLocalSolutionType: Passed the Zero congruence condition test \n") # Check if the solution satisfies the nzvec "nonzero" congruence conditions - # (nzvec is non-empty and its components index a non-zero vector mod p) + # (nzvec is non-empty and its components index a nonzero vector mod p) if nzvec is None: nonzero_flag = True elif len(nzvec) == 0: @@ -228,7 +224,7 @@ cdef local_solution_type_cdef(Q, p, w, zvec, nzvec): i = 0 while not nonzero_flag and i < len(nzvec): if w[nzvec[i]] % p: - nonzero_flag = True # The non-zero condition is satisfied when we find one non-zero entry + nonzero_flag = True # The nonzero condition is satisfied when we find one nonzero entry i += 1 if not nonzero_flag: diff --git a/src/sage/quadratic_forms/extras.py b/src/sage/quadratic_forms/extras.py index edb738ac561..38ab9c498d9 100644 --- a/src/sage/quadratic_forms/extras.py +++ b/src/sage/quadratic_forms/extras.py @@ -13,7 +13,7 @@ def is_triangular_number(n, return_value=False): Return whether ``n`` is a triangular number. A *triangular number* is a number of the form `k(k+1)/2` for some - non-negative integer `n`. See :wikipedia:`Triangular_number`. The sequence + nonnegative integer `n`. See :wikipedia:`Triangular_number`. The sequence of triangular number is references as A000217 in the Online encyclopedia of integer sequences (OEIS). @@ -22,11 +22,11 @@ def is_triangular_number(n, return_value=False): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``return_value`` -- a boolean set to ``False`` by default. If set to + - ``return_value`` -- boolean (default: ``False``); if set to ``True`` the function returns a pair made of a boolean and the value `v` - such that `v(v+1)/2 = n`. + such that `v(v+1)/2 = n` EXAMPLES:: @@ -85,11 +85,9 @@ def extend_to_primitive(A_input): INPUT: - a matrix, or a list of length n vectors (in the same space) + - ``A_input`` -- a matrix or a list of length n vectors (in the same space) - OUTPUT: - - a square matrix, or a list of n vectors (resp.) + OUTPUT: a square matrix or a list of n vectors (resp.) EXAMPLES:: diff --git a/src/sage/quadratic_forms/genera/genus.py b/src/sage/quadratic_forms/genera/genus.py index d98b2416c3d..8868999c367 100644 --- a/src/sage/quadratic_forms/genera/genus.py +++ b/src/sage/quadratic_forms/genera/genus.py @@ -45,9 +45,9 @@ def genera(sig_pair, determinant, max_scale=None, even=False): INPUT: - - ``sig_pair`` -- a pair of non-negative integers giving the signature + - ``sig_pair`` -- a pair of nonnegative integers giving the signature - - ``determinant`` -- an integer; the sign is ignored + - ``determinant`` -- integer; the sign is ignored - ``max_scale`` -- (default: ``None``) an integer; the maximum scale of a jordan block @@ -85,7 +85,7 @@ def genera(sig_pair, determinant, max_scale=None, even=False): sig_pair = (ZZ(sig_pair[0]), ZZ(sig_pair[1])) even = bool(even) if not all(s >= 0 for s in sig_pair): - raise ValueError("the signature vector must be a pair of non negative integers.") + raise ValueError("the signature vector must be a pair of nonnegative integers.") if max_scale is None: max_scale = determinant else: @@ -139,9 +139,9 @@ def _local_genera(p, rank, det_val, max_scale, even): - ``det_val`` -- valuation of the determinant at `p` - - ``max_scale`` -- an integer the maximal scale of a jordan block + - ``max_scale`` -- integer the maximal scale of a jordan block - - ``even`` -- ``bool``; is ignored if `p` is not `2` + - ``even`` -- boolean; ignored if `p` is not `2` EXAMPLES:: @@ -225,17 +225,17 @@ def _local_genera(p, rank, det_val, max_scale, even): def _blocks(b, even_only=False): r""" - Return all viable `2`-adic jordan blocks with rank and scale given by ``b`` + Return all viable `2`-adic jordan blocks with rank and scale given by ``b``. This is a helper function for :meth:`_local_genera`. It is based on the existence conditions for a modular `2`-adic genus symbol. INPUT: - - ``b`` -- a list of `5` non-negative integers the first two are kept + - ``b`` -- list of `5` nonnegative integers the first two are kept and all possibilities for the remaining `3` are enumerated - - ``even_only`` -- bool (default: ``True``) if set, the blocks are even + - ``even_only`` -- boolean (default: ``True``); if set, the blocks are even EXAMPLES:: @@ -469,7 +469,7 @@ def is_2_adic_genus(genus_symbol_quintuple_list) -> bool: INPUT: - ``genus_symbol_quintuple_list`` -- a quintuple of integers (with certain - restrictions). + restrictions) OUTPUT: boolean @@ -534,7 +534,7 @@ def canonical_2_adic_compartments(genus_symbol_quintuple_list): - ``genus_symbol_quintuple_list`` -- a quintuple of integers (with certain restrictions) - OUTPUT: a list of lists of integers + OUTPUT: list of lists of integers EXAMPLES:: @@ -607,7 +607,7 @@ def canonical_2_adic_trains(genus_symbol_quintuple_list, compartments=None): restrictions). - ``compartments`` -- this argument is deprecated - OUTPUT: a list of lists of distinct integers + OUTPUT: list of lists of distinct integers EXAMPLES:: @@ -705,9 +705,9 @@ def canonical_2_adic_reduction(genus_symbol_quintuple_list): - ``genus_symbol_quintuple_list`` -- a quintuple of integers (with certain restrictions) - - ``compartments`` -- a list of lists of distinct integers (optional) + - ``compartments`` -- list of lists of distinct integers (optional) - OUTPUT: a list of lists of distinct integers. + OUTPUT: list of lists of distinct integers EXAMPLES:: @@ -824,7 +824,7 @@ def basis_complement(B): def signature_pair_of_matrix(A): r""" - Computes the signature pair `(p, n)` of a non-degenerate symmetric + Compute the signature pair `(p, n)` of a non-degenerate symmetric matrix, where - `p` is the number of positive eigenvalues of `A` @@ -886,11 +886,11 @@ def p_adic_symbol(A, p, val): - ``A`` -- symmetric matrix with integer coefficients - ``p`` -- prime number - - ``val`` -- non-negative integer; valuation of the maximal elementary + - ``val`` -- nonnegative integer; valuation of the maximal elementary divisor of `A` needed to obtain enough precision. Calculation is modulo `p` to the ``val+3``. - OUTPUT: a list of lists of integers + OUTPUT: list of lists of integers EXAMPLES:: @@ -902,7 +902,6 @@ def p_adic_symbol(A, p, val): sage: p_adic_symbol(A, 3, 1) [[0, 3, 1], [1, 1, -1]] - """ if p % 2 == 0: return two_adic_symbol(A, val) @@ -982,7 +981,7 @@ def split_odd(A): INPUT: - ``A`` -- an odd symmetric matrix with integer coefficients (which admits a - splitting as above). + splitting as above) OUTPUT: @@ -1073,9 +1072,9 @@ def trace_diag_mod_8(A): INPUT: - ``A`` -- symmetric matrix with coefficients in `\ZZ` which is odd in - `\ZZ/2\ZZ` and has determinant not divisible by `8`. + `\ZZ/2\ZZ` and has determinant not divisible by `8` - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -1120,7 +1119,7 @@ def two_adic_symbol(A, val): INPUT: - ``A`` -- symmetric matrix with integer coefficients, non-degenerate - - ``val`` -- non-negative integer; valuation of maximal `2`-elementary divisor + - ``val`` -- nonnegative integer; valuation of maximal `2`-elementary divisor OUTPUT: @@ -1133,7 +1132,6 @@ def two_adic_symbol(A, val): sage: A = diagonal_matrix(ZZ, [1, 2, 3, 4]) sage: two_adic_symbol(A, 2) [[0, 2, 3, 1, 4], [1, 1, 1, 1, 1], [2, 1, 1, 1, 1]] - """ from sage.rings.finite_rings.finite_field_constructor import FiniteField @@ -1266,7 +1264,6 @@ def __init__(self, prime, symbol, check=True): r""" Create the local genus symbol of given prime and local invariants. - EXAMPLES:: sage: from sage.quadratic_forms.genera.genus import p_adic_symbol @@ -1297,9 +1294,9 @@ def __init__(self, prime, symbol, check=True): def __repr__(self): r""" - String representation for the `p`-adic genus symbol + String representation for the `p`-adic genus symbol. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -1457,7 +1454,6 @@ def __eq__(self, other): True sage: G3 == G3 True - """ p = self._prime if p != other._prime: @@ -1669,13 +1665,11 @@ def automorphous_numbers(self): def canonical_symbol(self): r""" - Return (and cache) the canonical p-adic genus symbol. This is + Return (and cache) the canonical `p`-adic genus symbol. This is only really affects the `2`-adic symbol, since when `p > 2` the symbol is already canonical. - OUTPUT: - - a list of lists of integers + OUTPUT: list of lists of integers EXAMPLES:: @@ -1741,7 +1735,7 @@ def gram_matrix(self, check=True): INPUT: - - ``check`` (default: ``True``) -- double check the result + - ``check`` -- boolean (default: ``True``); double check the result EXAMPLES:: @@ -1907,7 +1901,7 @@ def prime(self): r""" Return the prime number `p` of this `p`-adic local symbol. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -1951,7 +1945,7 @@ def symbol_tuple_list(self): Return a copy of the underlying list of lists of integers defining the genus symbol. - OUTPUT: a list of lists of integers + OUTPUT: list of lists of integers EXAMPLES:: @@ -1982,7 +1976,7 @@ def number_of_blocks(self): r""" Return the number of positive dimensional symbols/Jordan blocks. - OUTPUT: a non-negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -2009,12 +2003,12 @@ def number_of_blocks(self): def determinant(self): r""" - Returns the (`p`-part of the) determinant (square-class) of the + Return the (`p`-part of the) determinant (square-class) of the Hessian matrix of the quadratic form (given by regarding the integral symmetric matrix which generated this genus symbol as the Gram matrix of `Q`) associated to this local genus symbol. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -2044,7 +2038,7 @@ def dimension(self): r""" Return the dimension of a quadratic form associated to this genus symbol. - OUTPUT: a non-negative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -2143,7 +2137,7 @@ def excess(self): [CS1999]_ Conway and Sloane Book, 3rd edition, pp 370-371. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -2185,7 +2179,6 @@ def excess(self): 0 sage: p = 11; Genus_Symbol_p_adic_ring(p, p_adic_symbol(A, p, 2)).excess() 0 - """ p = self._prime if self._prime == 2: @@ -2209,7 +2202,7 @@ def scale(self): The scale of `(L,b)` is defined as the ideal `b(L,L)`. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -2269,7 +2262,7 @@ def trains(self) -> list: symbol if it is associated to the prime `p=2` (and raise an error for all other primes). - OUTPUT: a list of non-negative integers + OUTPUT: list of nonnegative integers EXAMPLES:: @@ -2282,7 +2275,6 @@ def trains(self) -> list: Genus symbol at 2: [2^-2 4^1 8^1]_6 sage: G2.trains() [[0, 1, 2]] - """ # Check that p = 2 if self._prime != 2: @@ -2296,7 +2288,7 @@ def compartments(self) -> list: symbol if it is associated to the prime `p=2` (and raise an error for all other primes). - OUTPUT: a list of non-negative integers + OUTPUT: list of nonnegative integers EXAMPLES:: @@ -2309,7 +2301,6 @@ def compartments(self) -> list: Genus symbol at 2: [2^-2 4^1 8^1]_6 sage: G2.compartments() [[0, 1, 2]] - """ # Check that p = 2 if self._prime != 2: @@ -2326,15 +2317,15 @@ class GenusSymbol_global_ring: INPUT: - - ``signature_pair`` -- a tuple of two non-negative integers + - ``signature_pair`` -- tuple of two nonnegative integers - - ``local_symbols`` -- a list of :class:`Genus_Symbol_p_adic_ring` instances + - ``local_symbols`` -- list of :class:`Genus_Symbol_p_adic_ring` instances sorted by their primes - ``representative`` -- (default: ``None``) integer symmetric matrix; the Gram matrix of a representative of this genus - - ``check`` -- (default: ``True``) a boolean; checks the input + - ``check`` -- boolean (default: ``True``); checks the input EXAMPLES:: @@ -2394,7 +2385,7 @@ def __repr__(self) -> str: r""" Return a string representing the global genus symbol. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -2418,7 +2409,6 @@ def __repr__(self) -> str: Signature: (2, 0) Genus symbol at 2: 1^-2 Genus symbol at 3: 1^-1 3^-1 - """ rep = "Genus" if self.dimension() <= 20: @@ -2460,7 +2450,7 @@ def __eq__(self, other) -> bool: INPUT: - a :class:`GenusSymbol_global_ring` object + - ``other`` -- a :class:`GenusSymbol_global_ring` object OUTPUT: boolean @@ -2510,7 +2500,7 @@ def __ne__(self, other) -> bool: INPUT: - a ``GenusSymbol_global_ring`` object + - ``other`` -- a ``GenusSymbol_global_ring`` object OUTPUT: boolean @@ -2532,7 +2522,6 @@ def __ne__(self, other) -> bool: sage: GS2 != GS2 False - """ return not self == other @@ -2655,7 +2644,7 @@ def spinor_generators(self, proper) -> list: - ``proper`` -- boolean - OUTPUT: a list of primes not dividing the determinant + OUTPUT: list of primes not dividing the determinant EXAMPLES:: @@ -2760,7 +2749,7 @@ def determinant(self): form whose Gram matrix is the Gram matrix giving rise to this global genus symbol. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -2991,14 +2980,14 @@ def representative(self): def representatives(self, backend=None, algorithm=None): r""" - Return a list of representatives for the classes in this genus + Return a list of representatives for the classes in this genus. INPUT: - ``backend`` -- (default: ``None``) - ``algorithm`` -- (default: ``None``) - OUTPUT: a list of Gram matrices + OUTPUT: list of Gram matrices EXAMPLES:: @@ -3024,7 +3013,7 @@ def representatives(self, backend=None, algorithm=None): For positive definite forms the magma backend is available:: sage: G = Genus(matrix.diagonal([1, 1, 7])) - sage: G.representatives(backend="magma") # optional - magma + sage: G.representatives(backend='magma') # optional - magma ( [1 0 0] [ 1 0 0] [0 1 0] [ 0 2 -1] @@ -3163,7 +3152,6 @@ def _standard_mass(self): sage: GS = Genus(A) sage: GS._standard_mass() # needs sage.symbolic 1/48 - """ from sage.symbolic.constants import pi from sage.symbolic.ring import SR @@ -3206,7 +3194,7 @@ def mass(self, backend='sage'): INPUT: - - ``backend`` -- default: ``'sage'``, or ``'magma'`` + - ``backend`` -- ``'sage'`` (default) or ``'magma'`` OUTPUT: a rational number @@ -3293,7 +3281,7 @@ def scale(self): The scale of `(L,b)` is defined as the ideal `b(L,L)`. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -3334,10 +3322,10 @@ def _gram_from_jordan_block(p, block, discr_form=False): - ``p`` -- a prime number - - ``block`` -- a list of 3 integers or 5 integers if `p` is `2` + - ``block`` -- list of 3 integers or 5 integers if `p` is `2` - - ``discr_form`` -- bool (default: ``False``); if ``True`` invert the scales - to obtain a Gram matrix for the discriminant form instead. + - ``discr_form`` -- boolean (default: ``False``); if ``True`` invert the scales + to obtain a Gram matrix for the discriminant form instead EXAMPLES:: diff --git a/src/sage/quadratic_forms/genera/normal_form.py b/src/sage/quadratic_forms/genera/normal_form.py index 1dcf13d18e3..d0081636e61 100644 --- a/src/sage/quadratic_forms/genera/normal_form.py +++ b/src/sage/quadratic_forms/genera/normal_form.py @@ -101,12 +101,10 @@ def collect_small_blocks(G): INPUT: - - ``G`` -- a block_diagonal matrix consisting of + - ``G`` -- a ``block_diagonal`` matrix consisting of `1` by `1` and `2` by `2` blocks - OUTPUT: - - - a list of `1` by `1` and `2` by `2` matrices -- the blocks + OUTPUT: list of `1` by `1` and `2` by `2` matrices; the blocks EXAMPLES:: @@ -132,7 +130,7 @@ def p_adic_normal_form(G, p, precision=None, partial=False, debug=False): r""" Return the transformation to the `p`-adic normal form of a symmetric matrix. - Two ``p-adic`` quadratic forms are integrally equivalent if and only if + Two ```p`-adic`` quadratic forms are integrally equivalent if and only if their Gram matrices have the same normal form. Let `p` be odd and `u` be the smallest non-square modulo `p`. @@ -173,8 +171,8 @@ def p_adic_normal_form(G, p, precision=None, partial=False, debug=False): - ``G`` -- a symmetric `n` by `n` matrix in `\QQ` - ``p`` -- a prime number -- it is not checked whether it is prime - ``precision`` -- if not set, the minimal possible is taken - - ``partial`` -- boolean (default: ``False``) if set, only the - partial normal form is returned. + - ``partial`` -- boolean (default: ``False``); if set, only the + partial normal form is returned OUTPUT: @@ -300,7 +298,7 @@ def _find_min_p(G, cnt, lower_bound=0): - ``G`` -- a symmetric `n` by `n` matrix in `\QQ_p` - ``cnt`` -- start search from this index - - ``lower_bound`` -- an integer (default: ``0``) + - ``lower_bound`` -- integer (default: 0) a lower bound for the valuations used for optimization OUTPUT: @@ -363,7 +361,7 @@ def _get_small_block_indices(G): - ``G`` -- a block_diagonal matrix consisting of `1` by `1` and `2` by `2` blocks - OUTPUT: a list of integers + OUTPUT: list of integers EXAMPLES:: @@ -398,9 +396,9 @@ def _get_homogeneous_block_indices(G): INPUT: - ``G`` -- a block diagonal matrix over the `p`-adics - with blocks of size at most `2`. + with blocks of size at most `2` - OUTPUT: a list of integers + OUTPUT: list of integers EXAMPLES:: @@ -559,7 +557,7 @@ def _jordan_odd_adic(G): INPUT: - - a symmetric matrix over `\ZZ_p` of type ``'fixed-mod'`` + - ``G`` -- a symmetric matrix over `\ZZ_p` of type ``'fixed-mod'`` OUTPUT: @@ -741,10 +739,6 @@ def _min_nonsquare(p): - ``p`` -- a prime number - OUTPUT: - - - ``a`` -- the minimal nonsquare mod `p` - EXAMPLES:: sage: from sage.quadratic_forms.genera.normal_form import _min_nonsquare @@ -771,8 +765,8 @@ def _normalize(G, normal_odd=True): - ``G`` -- a symmetric matrix over `\ZZ_p` in jordan form -- the output of :meth:`p_adic_normal_form` or :meth:`_jordan_2_adic` - - ``normal_odd`` -- bool (default: ``True``) if true and `p` is odd, - compute a normal form. + - ``normal_odd`` -- boolean (default: ``True``); if ``True`` and `p` is odd, + compute a normal form OUTPUT: @@ -988,12 +982,12 @@ def _normalize_odd_2x2(G): INPUT: - ``G`` -- a multiple of the `2` by `2` identity_matrix - over the `p`-adics for `p` odd. + over the `p`-adics for `p` odd OUTPUT: - - A transformation matrix ``B`` such that - ``B * G * B.T`` is the identity matrix + A transformation matrix ``B`` such that ``B * G * B.T`` is the identity + matrix. EXAMPLES:: @@ -1121,15 +1115,15 @@ def _relations(G, n): INPUT: - - ``n`` -- an integer between 1 and 10 -- the number of the relation + - ``n`` -- integer between 1 and 10 -- the number of the relation - ``G`` -- a block diagonal matrix consisting of blocks of types `U, V, W` the left side of the relation. If ``G`` does not match `n` then the results are unpredictable. OUTPUT: - - square matrix ``B`` such that ``B * G * B.T`` is the right side of the - relation which consists of blocks of types `U`, `V`, `W` again + Square matrix ``B`` such that ``B * G * B.T`` is the right side of the + relation which consists of blocks of types `U`, `V`, `W` again. EXAMPLES:: @@ -1385,11 +1379,9 @@ def _two_adic_normal_forms(G, partial=False): INPUT: - ``G`` -- block diagonal matrix with blocks of type `U`, `V`, `W` - - ``partial`` -- bool (default: ``False``) - - OUTPUT: + - ``partial`` -- boolean (default: ``False``) - - ``D``, ``B`` -- such that ``D = B * G * B.T`` + OUTPUT: ``D``, ``B``; such that ``D = B * G * B.T`` EXAMPLES:: diff --git a/src/sage/quadratic_forms/genera/spinor_genus.py b/src/sage/quadratic_forms/genera/spinor_genus.py index ee6453b1fd5..4da6f0a2fbd 100644 --- a/src/sage/quadratic_forms/genera/spinor_genus.py +++ b/src/sage/quadratic_forms/genera/spinor_genus.py @@ -37,7 +37,7 @@ class SpinorOperator(AbelianGroupElement_gap): A spinor operator seen as a tuple of square classes. For `2` the square class is represented as one of `1,3,5,7` and for - `p` odd it is `1` for a p-adic unit square and `-1` for a non-square. + `p` odd it is `1` for a `p`-adic unit square and `-1` for a non-square. EXAMPLES:: @@ -149,7 +149,7 @@ def to_square_class(self, x, p): - ``p`` -- a prime - - ``x``` -- a non zero rational number + - ``x`` -- nonzero rational number EXAMPLES:: @@ -166,7 +166,7 @@ def to_square_class(self, x, p): """ x = QQ(x) if x == 0: - raise ValueError("x must be non zero") + raise ValueError("x must be nonzero") if p not in self._primes: raise ValueError("not a coordinate prime") v, u = x.val_unit(p) @@ -194,11 +194,10 @@ def delta(self, r, prime=None): INPUT: - - ``r`` -- a non zero integer; - if ``prime`` is ``None``, ``r`` must not be divisible - by the defining primes of ``self`` + - ``r`` -- a nonzero integer; if ``prime`` is ``None``, ``r`` must not + be divisible by the defining primes of ``self`` - - ``prime`` -- (default:``None``) a prime or `-1` + - ``prime`` -- (default: ``None``) a prime or `-1` OUTPUT: diff --git a/src/sage/quadratic_forms/qfsolve.py b/src/sage/quadratic_forms/qfsolve.py index 83720128bfc..55fd9a4b3b2 100644 --- a/src/sage/quadratic_forms/qfsolve.py +++ b/src/sage/quadratic_forms/qfsolve.py @@ -129,7 +129,7 @@ def solve(self, c=0): - ``c`` -- (default: 0) a rational number - OUTPUT: A non-zero vector `x` satisfying ``self(x) == c``. + OUTPUT: a nonzero vector `x` satisfying ``self(x) == c`` ALGORITHM: diff --git a/src/sage/quadratic_forms/quadratic_form.py b/src/sage/quadratic_forms/quadratic_form.py index b28bca0fb39..88df6dfcb9c 100644 --- a/src/sage/quadratic_forms/quadratic_form.py +++ b/src/sage/quadratic_forms/quadratic_form.py @@ -76,14 +76,12 @@ def quadratic_form_from_invariants(F, rk, det, P, sminus): - ``F`` -- the base field; currently only ``QQ`` is allowed - ``rk`` -- integer; the rank - ``det`` -- rational; the determinant - - ``P`` -- a list of primes where Cassel's Hasse invariant + - ``P`` -- list of primes where Cassel's Hasse invariant is negative - ``sminus`` -- integer; the number of negative eigenvalues of any Gram matrix - OUTPUT: - - - a quadratic form with the specified invariants + OUTPUT: a quadratic form with the specified invariants Let `(a_1, \ldots, a_n)` be the gram marix of a regular quadratic space. Then Cassel's Hasse invariant is defined as @@ -194,8 +192,8 @@ class QuadraticForm(SageObject): #. ``QuadraticForm(R, n, entries)``, where - ``R`` -- ring for which the quadratic form is defined - - ``n`` -- an integer `\geq 0` - - ``entries`` -- a list of `n(n+1)/2` coefficients of the quadratic form + - ``n`` -- integer `\geq 0` + - ``entries`` -- list of `n(n+1)/2` coefficients of the quadratic form in `R` (given lexicographically, or equivalently, by rows of the matrix) @@ -221,7 +219,6 @@ class QuadraticForm(SageObject): - ``number_of_automorphisms`` - ``determinant`` - OUTPUT: quadratic form EXAMPLES:: @@ -365,9 +362,9 @@ class QuadraticForm(SageObject): count_congruence_solutions__bad_type_II # Routines to be called by the user to compute local densities - lazy_import("sage.quadratic_forms.quadratic_form__local_density_interfaces", [ - "local_density", - "local_primitive_density" + lazy_import('sage.quadratic_forms.quadratic_form__local_density_interfaces', [ + 'local_density', + 'local_primitive_density' ]) # Routines for computing with ternary forms @@ -404,8 +401,8 @@ class QuadraticForm(SageObject): theta_by_cholesky # Routines to compute the product of all local densities - lazy_import("sage.quadratic_forms.quadratic_form__siegel_product", [ - "siegel_product" + lazy_import('sage.quadratic_forms.quadratic_form__siegel_product', [ + 'siegel_product' ]) # Routines to compute p-neighbors @@ -424,50 +421,50 @@ class QuadraticForm(SageObject): minkowski_reduction, \ minkowski_reduction_for_4vars__SP # Wrappers for Conway-Sloane genus routines (in ./genera/) - lazy_import("sage.quadratic_forms.quadratic_form__genus", [ - "global_genus_symbol", - "local_genus_symbol", - "CS_genus_symbol_list" + lazy_import('sage.quadratic_forms.quadratic_form__genus', [ + 'global_genus_symbol', + 'local_genus_symbol', + 'CS_genus_symbol_list' ]) # Routines to compute local masses for ZZ. - lazy_import("sage.quadratic_forms.quadratic_form__mass", [ - "shimura_mass__maximal", - "GHY_mass__maximal" + lazy_import('sage.quadratic_forms.quadratic_form__mass', [ + 'shimura_mass__maximal', + 'GHY_mass__maximal' ]) - lazy_import("sage.quadratic_forms.quadratic_form__mass__Siegel_densities", [ - "mass__by_Siegel_densities", - "Pall_mass_density_at_odd_prime", - "Watson_mass_at_2", - "Kitaoka_mass_at_2", - "mass_at_two_by_counting_mod_power" + lazy_import('sage.quadratic_forms.quadratic_form__mass__Siegel_densities', [ + 'mass__by_Siegel_densities', + 'Pall_mass_density_at_odd_prime', + 'Watson_mass_at_2', + 'Kitaoka_mass_at_2', + 'mass_at_two_by_counting_mod_power' ]) - lazy_import("sage.quadratic_forms.quadratic_form__mass__Conway_Sloane_masses", [ - "parity", - "is_even", - "is_odd", - "conway_species_list_at_odd_prime", - "conway_species_list_at_2", - "conway_octane_of_this_unimodular_Jordan_block_at_2", - "conway_diagonal_factor", - "conway_cross_product_doubled_power", - "conway_type_factor", - "conway_p_mass", - "conway_standard_p_mass", - "conway_standard_mass", - "conway_mass" + lazy_import('sage.quadratic_forms.quadratic_form__mass__Conway_Sloane_masses', [ + 'parity', + 'is_even', + 'is_odd', + 'conway_species_list_at_odd_prime', + 'conway_species_list_at_2', + 'conway_octane_of_this_unimodular_Jordan_block_at_2', + 'conway_diagonal_factor', + 'conway_cross_product_doubled_power', + 'conway_type_factor', + 'conway_p_mass', + 'conway_standard_p_mass', + 'conway_standard_mass', + 'conway_mass' # conway_generic_mass, \ # conway_p_mass_adjustment ]) # Routines to check local representability of numbers - lazy_import("sage.quadratic_forms.quadratic_form__local_representation_conditions", [ - "local_representation_conditions", - "is_locally_universal_at_prime", - "is_locally_universal_at_all_primes", - "is_locally_universal_at_all_places", - "is_locally_represented_number_at_place", - "is_locally_represented_number" + lazy_import('sage.quadratic_forms.quadratic_form__local_representation_conditions', [ + 'local_representation_conditions', + 'is_locally_universal_at_prime', + 'is_locally_universal_at_all_primes', + 'is_locally_universal_at_all_places', + 'is_locally_represented_number_at_place', + 'is_locally_represented_number' ]) # Routines to make a split local covering of the given quadratic form. @@ -478,15 +475,15 @@ class QuadraticForm(SageObject): split_local_cover # Routines to make automorphisms of the given quadratic form. - lazy_import("sage.quadratic_forms.quadratic_form__automorphisms", [ - "basis_of_short_vectors", - "short_vector_list_up_to_length", - "short_primitive_vector_list_up_to_length", - "_compute_automorphisms", - "automorphism_group", - "automorphisms", - "number_of_automorphisms", - "set_number_of_automorphisms" + lazy_import('sage.quadratic_forms.quadratic_form__automorphisms', [ + 'basis_of_short_vectors', + 'short_vector_list_up_to_length', + 'short_primitive_vector_list_up_to_length', + '_compute_automorphisms', + 'automorphism_group', + 'automorphisms', + 'number_of_automorphisms', + 'set_number_of_automorphisms' ]) # Routines to test the local and global equivalence/isometry of two quadratic forms. @@ -497,13 +494,13 @@ class QuadraticForm(SageObject): is_rationally_isometric # Routines for solving equations of the form Q(x) = c. - lazy_import("sage.quadratic_forms.qfsolve", [ - "solve" + lazy_import('sage.quadratic_forms.qfsolve', [ + 'solve' ]) # Genus - lazy_import("sage.quadratic_forms.genera.genus", - "_genera_staticmethod", as_="genera") + lazy_import('sage.quadratic_forms.genera.genus', + '_genera_staticmethod', as_='genera') def __init__(self, R, n=None, entries=None, unsafe_initialization=False, number_of_automorphisms=None, determinant=None): """ @@ -539,7 +536,7 @@ def __init__(self, R, n=None, entries=None, unsafe_initialization=False, number_ sage: QuadraticForm(ZZ, -1) Traceback (most recent call last): ... - ValueError: the size must be a non-negative integer, not -1 + ValueError: the size must be a nonnegative integer, not -1 sage: x = polygen(ZZ, 'x') sage: QuadraticForm(x**2) @@ -618,7 +615,7 @@ def __init__(self, R, n=None, entries=None, unsafe_initialization=False, number_ # Verify the size of the matrix is an integer >= 0 n = ZZ(n) if n < 0: - raise ValueError(f"the size must be a non-negative integer, not {n}") + raise ValueError(f"the size must be a nonnegative integer, not {n}") # Store the relevant variables N = n * (n + 1) // 2 @@ -702,7 +699,6 @@ def __pari__(self): sage: Q = QuadraticForm(ZZ, 2, [1,0,5]) sage: Q.__pari__() # needs sage.libs.pari [2, 0; 0, 10] - """ return self.matrix().__pari__() @@ -780,7 +776,6 @@ def __getitem__(self, ij): [1 2 3] [2 4 5] [3 5 6] - """ # Unpack the list of indices i, j = ij @@ -813,7 +808,6 @@ def __setitem__(self, ij, coeff): [ 1 2 3 ] [ * 4 17 ] [ * * 6 ] - """ # Unpack the list of indices i, j = ij @@ -869,7 +863,6 @@ def __eq__(self, right): False sage: Q1 == Q2 False - """ if not isinstance(right, QuadraticForm): return False @@ -1043,7 +1036,6 @@ def __call__(self, v): sage: Q(M) Quadratic form in 1 variables over Integer Ring with coefficients: [ 14 ] - """ # If we are passed a matrix A, return the quadratic form Q(A(x)) # (In matrix notation: A^t * Q * A) @@ -1081,7 +1073,7 @@ def __call__(self, v): def _is_even_symmetric_matrix_(self, A, R=None): """ - Tests if a matrix is symmetric, defined over `R`, and has even diagonal in `R`. + Test if a matrix is symmetric, defined over `R`, and has even diagonal in `R`. INPUT: @@ -1101,7 +1093,6 @@ def _is_even_symmetric_matrix_(self, A, R=None): sage: A[0,0] = 1 sage: Q._is_even_symmetric_matrix_(A) False - """ if not isinstance(A, Matrix): raise TypeError("A is not a matrix.") @@ -1148,7 +1139,6 @@ def matrix(self): [ 0 1 2] [ 1 6 4] [ 2 4 10] - """ return self.Hessian_matrix() @@ -1167,7 +1157,6 @@ def Hessian_matrix(self): [2 6] sage: Q.matrix().base_ring() Rational Field - """ mat_entries = [] for i in range(self.dim()): @@ -1200,7 +1189,6 @@ def Gram_matrix_rational(self): [0 0 0 7] sage: A.base_ring() Rational Field - """ return (ZZ(1) / ZZ(2)) * self.matrix() @@ -1214,7 +1202,7 @@ def Gram_matrix(self): Q(x) = x^t\cdot A\cdot x, defined over the base ring of `Q`. If this is not possible, - then a :class:`TypeError` is raised. + then a :exc:`TypeError` is raised. EXAMPLES:: @@ -1258,7 +1246,6 @@ def has_integral_Gram_matrix(self): sage: Q = QuadraticForm(ZZ, 2, [4,5,6]) sage: Q.has_integral_Gram_matrix() False - """ # Warning over fields if self.base_ring() in Fields(): @@ -1301,7 +1288,7 @@ def polynomial(self, names='x'): - ``names`` -- specification of the names of the variables; see :func:`PolynomialRing` - OUTPUT: The polynomial form of the quadratic form. + OUTPUT: the polynomial form of the quadratic form EXAMPLES:: @@ -1436,7 +1423,6 @@ def adjoint_primitive(self): Quadratic form in 2 variables over Integer Ring with coefficients: [ 3 -2 ] [ * 1 ] - """ return QuadraticForm(self.Hessian_matrix().adjoint_classical()).primitive() @@ -1489,7 +1475,7 @@ def det(self): Return the determinant of the Gram matrix of `2\cdot Q`, or equivalently the determinant of the Hessian matrix of `Q`. - .. NOTE: + .. NOTE:: This is always defined over the same ring as the quadratic form. @@ -1581,7 +1567,7 @@ def level(self): generator for the smallest ideal `N` of `R` such that `N\cdot (` the matrix of `2*Q` `)^{(-1)}` is in `R` with diagonal in `2R`. - Over `\ZZ` this returns a non-negative number. + Over `\ZZ` this returns a nonnegative number. (Caveat: This always returns the unit ideal when working over a field!) @@ -1680,7 +1666,7 @@ def level_ideal(self): def bilinear_map(self, v, w): r""" - Return the value of the associated bilinear map on two vectors + Return the value of the associated bilinear map on two vectors. Given a quadratic form `Q` over some base ring `R` with characteristic not equal to 2, this gives the image of two @@ -1691,7 +1677,7 @@ def bilinear_map(self, v, w): - ``v``, ``w`` -- two vectors - OUTPUT: an element of the base ring `R`. + OUTPUT: an element of the base ring `R` EXAMPLES: diff --git a/src/sage/quadratic_forms/quadratic_form__automorphisms.py b/src/sage/quadratic_forms/quadratic_form__automorphisms.py index 4b6e3594f83..4fa4d4fe1ff 100644 --- a/src/sage/quadratic_forms/quadratic_form__automorphisms.py +++ b/src/sage/quadratic_forms/quadratic_form__automorphisms.py @@ -22,9 +22,7 @@ def basis_of_short_vectors(self, show_lengths=False): r""" Return a basis for `\ZZ^n` made of vectors with minimal lengths `Q(v)`. - OUTPUT: - - a tuple of vectors, and optionally a tuple of values for each vector. + OUTPUT: a tuple of vectors, and optionally a tuple of values for each vector This uses :pari:`qfminim`. @@ -105,8 +103,8 @@ def short_vector_list_up_to_length(self, len_bound, up_to_sign_flag=False): - ``len_bound`` -- bound for the length of the vectors - - ``up_to_sign_flag`` -- (default: ``False``) if set to True, then - only one of the vectors of the pair `[v, -v]` is listed. + - ``up_to_sign_flag`` -- boolean (default: ``False``); if set to ``True``, + then only one of the vectors of the pair `[v, -v]` is listed OUTPUT: @@ -231,7 +229,7 @@ def short_primitive_vector_list_up_to_length(self, len_bound, up_to_sign_flag=Fa This processes the PARI/GP output to always give elements of type `\ZZ`. - OUTPUT: a list of lists of vectors. + OUTPUT: list of lists of vectors EXAMPLES:: @@ -262,7 +260,7 @@ def _compute_automorphisms(self): This uses :pari:`qfauto`. - OUTPUT: None, this just caches the result. + OUTPUT: none, this just caches the result TESTS:: @@ -338,7 +336,7 @@ def automorphisms(self): """ Return the list of the automorphisms of the quadratic form. - OUTPUT: a list of matrices + OUTPUT: list of matrices EXAMPLES:: @@ -377,7 +375,7 @@ def number_of_automorphisms(self): Return the number of automorphisms (of det `1` and `-1`) of the quadratic form. - OUTPUT: an integer `\geq 2`. + OUTPUT: integer `\geq 2` EXAMPLES:: @@ -409,7 +407,7 @@ def set_number_of_automorphisms(self, num_autos): internal list of external initializations, accessible by the method :meth:`list_external_initializations`. - OUTPUT: None + OUTPUT: none EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__count_local_2.py b/src/sage/quadratic_forms/quadratic_form__count_local_2.py index b125d8d6840..3805945d0f7 100644 --- a/src/sage/quadratic_forms/quadratic_form__count_local_2.py +++ b/src/sage/quadratic_forms/quadratic_form__count_local_2.py @@ -38,8 +38,8 @@ def count_congruence_solutions_as_vector(self, p, k, m, zvec, nzvec): INPUT: - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``k`` -- integer > 0 + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers in ``range(self.dim())``, or ``None`` OUTPUT: @@ -47,7 +47,6 @@ def count_congruence_solutions_as_vector(self, p, k, m, zvec, nzvec): a list of six integers `\geq 0` representing the solution types: [All, Good, Zero, Bad, BadI, BadII] - EXAMPLES:: sage: Q = DiagonalQuadraticForm(ZZ, [1,2,3]) @@ -63,7 +62,6 @@ def count_congruence_solutions_as_vector(self, p, k, m, zvec, nzvec): [6, 6, 0, 0, 0, 0] sage: Q.count_congruence_solutions_as_vector(3, 1, 0, None, None) [15, 12, 1, 2, 0, 2] - """ return CountAllLocalTypesNaive(self, p, k, m, zvec, nzvec) @@ -82,9 +80,9 @@ def count_congruence_solutions(self, p, k, m, zvec, nzvec): - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 + - ``k`` -- integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers in ``range(self.dim())``, or ``None`` @@ -107,9 +105,9 @@ def count_congruence_solutions__good_type(self, p, k, m, zvec, nzvec): - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 + - ``k`` -- integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers up to dim(`Q`) @@ -132,9 +130,9 @@ def count_congruence_solutions__zero_type(self, p, k, m, zvec, nzvec): - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 + - ``k`` -- integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers up to dim(`Q`) @@ -157,9 +155,9 @@ def count_congruence_solutions__bad_type(self, p, k, m, zvec, nzvec): - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 + - ``k`` -- integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers up to dim(`Q`) @@ -182,9 +180,9 @@ def count_congruence_solutions__bad_type_I(self, p, k, m, zvec, nzvec): - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 + - ``k`` -- integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers up to dim(`Q`) @@ -207,9 +205,9 @@ def count_congruence_solutions__bad_type_II(self, p, k, m, zvec, nzvec): - ``p`` -- prime number > 0 - - ``k`` -- an integer > 0 + - ``k`` -- integer > 0 - - ``m`` -- an integer (depending only on mod `p^k`) + - ``m`` -- integer (depending only on mod `p^k`) - ``zvec``, ``nzvec`` -- lists of integers up to dim(`Q`) diff --git a/src/sage/quadratic_forms/quadratic_form__equivalence_testing.py b/src/sage/quadratic_forms/quadratic_form__equivalence_testing.py index 32f8bb62b4e..6e47726f08f 100644 --- a/src/sage/quadratic_forms/quadratic_form__equivalence_testing.py +++ b/src/sage/quadratic_forms/quadratic_form__equivalence_testing.py @@ -32,7 +32,7 @@ def is_globally_equivalent_to(self, other, return_matrix=False): - ``self``, ``other`` -- positive definite integral quadratic forms - - ``return_matrix`` -- (boolean, default ``False``) return + - ``return_matrix`` -- boolean (default: ``False``); return the transformation matrix instead of a boolean OUTPUT: @@ -307,8 +307,9 @@ def is_rationally_isometric(self, other, return_matrix=False): - ``other`` -- a quadratic form over a number field - - ``return_matrix`` -- (boolean, default ``False``) return - the transformation matrix instead of a boolean; this is currently only implemented for forms over ``QQ`` + - ``return_matrix`` -- boolean (default: ``False``); return + the transformation matrix instead of a boolean; this is currently + only implemented for forms over ``QQ`` OUTPUT: @@ -444,7 +445,7 @@ def is_rationally_isometric(self, other, return_matrix=False): ... NotImplementedError: this only tests regular forms - Forms must have the same base ring otherwise a :class:`TypeError` is raised:: + Forms must have the same base ring otherwise a :exc:`TypeError` is raised:: sage: # needs sage.rings.number_field sage: K1. = QuadraticField(5) @@ -659,11 +660,9 @@ def _gram_schmidt(m, fixed_vector_index, inner_product): - ``fixed_vector_index`` -- any vectors preceding the vector (i.e. to its left) at this index are not changed. - ``inner_product`` -- a function that takes two vector arguments and returns a scalar, - representing an inner product. + representing an inner product - OUTPUT: - - - A matrix consisting of orthogonal columns with respect to the given inner product + OUTPUT: a matrix consisting of orthogonal columns with respect to the given inner product EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__evaluate.pyx b/src/sage/quadratic_forms/quadratic_form__evaluate.pyx index 95e82e669dc..b0c374e5381 100644 --- a/src/sage/quadratic_forms/quadratic_form__evaluate.pyx +++ b/src/sage/quadratic_forms/quadratic_form__evaluate.pyx @@ -23,7 +23,7 @@ def QFEvaluateVector(Q, v): INPUT: - ``Q`` -- :class:`QuadraticForm` over a base ring `R` - - ``v`` -- a tuple or list (or column matrix) of ``Q.dim()`` elements of `R` + - ``v`` -- tuple or list (or column matrix) of ``Q.dim()`` elements of `R` OUTPUT: an element of `R` @@ -48,7 +48,6 @@ cdef QFEvaluateVector_cdef(Q, v): r""" Routine to quickly evaluate a quadratic form `Q` on a vector `v`. See the Python wrapper function :meth:`QFEvaluate` above for details. - """ # If we are passed a matrix A, return the quadratic form Q(A(x)) # (In matrix notation: A^t * Q * A) @@ -115,7 +114,6 @@ cdef QFEvaluateMatrix_cdef(Q, M, Q2): r""" Routine to quickly evaluate a quadratic form `Q` on a matrix `M`. See the Python wrapper function :func:`QFEvaluateMatrix` above for details. - """ # Create the new quadratic form n = Q.dim() diff --git a/src/sage/quadratic_forms/quadratic_form__local_density_congruence.py b/src/sage/quadratic_forms/quadratic_form__local_density_congruence.py index a39637df8f0..a959be64455 100644 --- a/src/sage/quadratic_forms/quadratic_form__local_density_congruence.py +++ b/src/sage/quadratic_forms/quadratic_form__local_density_congruence.py @@ -34,9 +34,9 @@ def count_modp_solutions__by_Gauss_sum(self, p, m): - ``p`` -- a prime number > 2 - - ``m`` -- an integer + - ``m`` -- integer - OUTPUT: an integer `\geq 0` + OUTPUT: integer `\geq 0` EXAMPLES:: @@ -75,7 +75,7 @@ def local_good_density_congruence_odd(self, p, m, Zvec, NZvec): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -111,7 +111,7 @@ def local_good_density_congruence_odd(self, p, m, Zvec, NZvec): UnitVec = Set(i for i in range(n) if self[i, i] % p) NonUnitVec = Set(range(n)) - UnitVec - # Take cases on the existence of additional non-zero congruence conditions (mod p) + # Take cases on the existence of additional nonzero congruence conditions (mod p) UnitVec_minus_Zvec = list(UnitVec - Set(Zvec)) NonUnitVec_minus_Zvec = list(NonUnitVec - Set(Zvec)) Q_Unit_minus_Zvec = self.extract_variables(UnitVec_minus_Zvec) @@ -171,7 +171,7 @@ def local_good_density_congruence_even(self, m, Zvec, NZvec): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -237,7 +237,7 @@ def local_good_density_congruence_even(self, m, Zvec, NZvec): if (NZvec is not None) and (len(Set(NZvec) + Sn) > n): raise RuntimeError("NZvec must be a subset of {0, ..., n-1}.") - # Find the indices of x for which the associated Jordan blocks are non-zero mod 8 TODO: Move this to special Jordan block code separately! + # Find the indices of x for which the associated Jordan blocks are nonzero mod 8 TODO: Move this to special Jordan block code separately! # ------------------------------------------------------------------------------- Not8vec = [] for i in range(n): @@ -293,7 +293,7 @@ def local_good_density_congruence_even(self, m, Zvec, NZvec): verbose("Z_Is8 = " + str(Z_Is8)) verbose("Is8_minus_Z = " + str(Is8_minus_Z)) - # Take cases on the existence of additional non-zero congruence conditions (mod 2) + # Take cases on the existence of additional nonzero congruence conditions (mod 2) if NZvec is None: total = (4 ** len(Z_Is8)) * (8 ** len(Is8_minus_Z)) \ * Q_Not8.count_congruence_solutions__good_type(2, 3, m, list(Z_Not8), None) @@ -337,7 +337,7 @@ def local_good_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -358,7 +358,6 @@ def local_good_density_congruence(self, p, m, Zvec=None, NZvec=None): 1 sage: Q.local_good_density_congruence(3, 1, None, None) 8/9 - """ # DIAGNOSTIC verbose(" In local_good_density_congruence with ") @@ -408,7 +407,7 @@ def local_zero_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -481,7 +480,7 @@ def local_badI_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -560,7 +559,7 @@ def local_badI_density_congruence(self, p, m, Zvec=None, NZvec=None): S0 = [] S1_empty_flag = True # This is used to check if we should be computing BI solutions at all! - # (We should really to this earlier, but S1 must be non-zero to proceed.) + # (We should really to this earlier, but S1 must be nonzero to proceed.) # Find the valuation of each variable (which will be the same over 2x2 blocks), # remembering those of valuation 0 and if an entry of valuation 1 exists. @@ -644,7 +643,7 @@ def local_badII_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -790,7 +789,7 @@ def local_bad_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -848,7 +847,7 @@ def local_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` @@ -920,7 +919,7 @@ def local_primitive_density_congruence(self, p, m, Zvec=None, NZvec=None): - ``p`` -- a prime number - - ``m`` -- an integer + - ``m`` -- integer - ``Zvec``, ``NZvec`` -- non-repeating lists of integers in ``range(self.dim())`` or ``None`` diff --git a/src/sage/quadratic_forms/quadratic_form__local_density_interfaces.py b/src/sage/quadratic_forms/quadratic_form__local_density_interfaces.py index 2e5be4f59de..2643620e712 100644 --- a/src/sage/quadratic_forms/quadratic_form__local_density_interfaces.py +++ b/src/sage/quadratic_forms/quadratic_form__local_density_interfaces.py @@ -21,7 +21,7 @@ def local_density(self, p, m): INPUT: - ``p`` -- a prime number > 0 - - ``m`` -- an integer + - ``m`` -- integer OUTPUT: a rational number @@ -67,7 +67,7 @@ def local_density(self, p, m): def local_primitive_density(self, p, m): """ - Return the local primitive density -- should be called by the user. =) + Return the local primitive density -- should be called by the user. NOTE: This screens for imprimitive forms, and puts the quadratic form in local normal form, which is a *requirement* of @@ -76,7 +76,7 @@ def local_primitive_density(self, p, m): INPUT: - ``p`` -- a prime number > 0 - - ``m`` -- an integer + - ``m`` -- integer OUTPUT: a rational number diff --git a/src/sage/quadratic_forms/quadratic_form__local_field_invariants.py b/src/sage/quadratic_forms/quadratic_form__local_field_invariants.py index b9a8758be1d..fb869fc7551 100644 --- a/src/sage/quadratic_forms/quadratic_form__local_field_invariants.py +++ b/src/sage/quadratic_forms/quadratic_form__local_field_invariants.py @@ -1,7 +1,7 @@ """ Local Field Invariants -This contains routines to compute local (p-adic) invariants of +This contains routines to compute local (`p`-adic) invariants of quadratic forms over the rationals. """ @@ -37,16 +37,16 @@ def rational_diagonal_form(self, return_matrix=False): INPUT: - - ``return_matrix`` -- (boolean, default: ``False``) also return the + - ``return_matrix`` -- boolean (default: ``False``); also return the transformation matrix OUTPUT: either the diagonal quadratic form `D` (if ``return_matrix`` is false) or the pair `(D, T)` (if ``return_matrix`` is true) where - - `D` -- the diagonalized form of this quadratic form + - ``D`` -- the diagonalized form of this quadratic form - - `T` -- transformation matrix. This is such that - ``T.transpose() * self.matrix() * T`` gives ``D.matrix()``. + - ``T`` -- transformation matrix. This is such that + ``T.transpose() * self.matrix() * T`` gives ``D.matrix()`` Both `D` and `T` are defined over the fraction field of the base ring of the given form. @@ -189,10 +189,10 @@ def _rational_diagonal_form_and_transformation(self): OUTPUT: a tuple `(D,T)` where - - `D` -- the diagonalized form of this quadratic form + - ``D`` -- the diagonalized form of this quadratic form - - `T` -- transformation matrix. This is such that - ``T.transpose() * self.matrix() * T`` gives ``D.matrix()``. + - ``T`` -- transformation matrix. This is such that + ``T.transpose() * self.matrix() * T`` gives ``D.matrix()`` Both `D` and `T` are defined over the fraction field of the base ring of the given form. @@ -258,7 +258,7 @@ def _rational_diagonal_form_and_transformation(self): # Deal with rows where the diagonal entry is zero. if Q[i, i] == 0: - # Look for a non-zero entry and use it to make the diagonal non-zero (if it exists) + # Look for a nonzero entry and use it to make the diagonal nonzero (if it exists) for j in range(i + 1, n): if Q[i, j] != 0: temp = MS(1) @@ -318,7 +318,6 @@ def signature_vector(self): [ * * * 9 ] sage: Q.signature_vector() (3, 1, 0) - """ diag = self.rational_diagonal_form() p = 0 @@ -343,7 +342,7 @@ def signature(self): of the matrix of the quadratic form. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -677,7 +676,7 @@ def is_anisotropic(self, p): def is_isotropic(self, p): r""" - Checks if `Q` is isotropic over the `p`-adic numbers `\QQ_p` or `\RR`. + Check if `Q` is isotropic over the `p`-adic numbers `\QQ_p` or `\RR`. INPUT: @@ -718,7 +717,6 @@ def is_isotropic(self, p): ....: p, -p*least_quadratic_nonresidue(p)]).is_isotropic(p) ....: for p in prime_range(3, 30)] [False, False, False, False, False, False, False, False, False] - """ return not self.is_anisotropic(p) @@ -763,7 +761,7 @@ def compute_definiteness(self): A degenerate form is considered neither definite nor indefinite. - .. NOTE: + .. NOTE:: The zero-dimensional form is considered both positive definite and negative definite. @@ -807,7 +805,6 @@ def compute_definiteness(self): False sage: Q.is_definite() False - """ # Sanity Check from sage.rings.real_mpfr import RR @@ -928,7 +925,7 @@ def is_positive_definite(self): The zero-dimensional form is considered both positive definite and negative definite. - OUTPUT: boolean -- True or False + OUTPUT: boolean EXAMPLES:: @@ -965,7 +962,7 @@ def is_negative_definite(self): The zero-dimensional form is considered both positive definite and negative definite. - OUTPUT: boolean -- True or False + OUTPUT: boolean EXAMPLES:: @@ -1002,7 +999,7 @@ def is_indefinite(self): The zero-dimensional form is not considered indefinite. - OUTPUT: boolean -- True or False + OUTPUT: boolean EXAMPLES:: @@ -1015,7 +1012,6 @@ def is_indefinite(self): sage: Q = DiagonalQuadraticForm(ZZ, [1,-3,5]) sage: Q.is_indefinite() True - """ # Try to use the cached value try: @@ -1040,7 +1036,7 @@ def is_definite(self): The zero-dimensional form is considered indefinite. - OUTPUT: boolean -- True or False + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__local_normal_form.py b/src/sage/quadratic_forms/quadratic_form__local_normal_form.py index 5770a3c22f0..f70ce4f2bb3 100644 --- a/src/sage/quadratic_forms/quadratic_form__local_normal_form.py +++ b/src/sage/quadratic_forms/quadratic_form__local_normal_form.py @@ -143,7 +143,7 @@ def local_normal_form(self, p): else: min_val = valuation(Q[min_i, min_j], p) - # Error if we still haven't seen non-zero coefficients! + # Error if we still haven't seen nonzero coefficients! if min_val == Infinity: raise RuntimeError("the original matrix is degenerate") @@ -261,7 +261,7 @@ def jordan_blocks_by_scale_and_unimodular(self, p, safe_flag=True): - `s_i` is an integer, - `L_i` is a block-diagonal unimodular quadratic form over `\ZZ_p`. - .. note:: + .. NOTE:: These forms `L_i` are defined over the `p`-adic integers, but by a matrix over `\ZZ` (or `\QQ`?). @@ -368,7 +368,7 @@ def jordan_blocks_in_unimodular_list_by_scale_power(self, p): - ``self`` -- a quadratic form over `\ZZ`, which has integer Gram matrix if `p = 2` - ``p`` -- a prime number > 0 - OUTPUT: a list of `p`-unimodular quadratic forms + OUTPUT: list of `p`-unimodular quadratic forms EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__local_representation_conditions.py b/src/sage/quadratic_forms/quadratic_form__local_representation_conditions.py index c337d2994a0..4cc9f18c152 100644 --- a/src/sage/quadratic_forms/quadratic_form__local_representation_conditions.py +++ b/src/sage/quadratic_forms/quadratic_form__local_representation_conditions.py @@ -96,7 +96,7 @@ class QuadraticFormLocalRepresentationConditions: """ def __init__(self, Q): r""" - Takes a :class:`QuadraticForm` and computes its local conditions (if + Take a :class:`QuadraticForm` and computes its local conditions (if they do not already exist). The ``recompute_flag`` overrides the previously computed conditions if they exist, and stores the new conditions. @@ -105,9 +105,7 @@ def __init__(self, Q): - ``Q`` -- Quadratic form over `\ZZ` - OUTPUT: - - a :class:`QuadraticFormLocalRepresentationConditions` object + OUTPUT: a :class:`QuadraticFormLocalRepresentationConditions` object EXAMPLES:: @@ -124,7 +122,7 @@ def __init__(self, Q): # Basic structure initialization self.local_repn_array = [] # List of all local conditions - self.dim = Q.dim() # We allow this to be any non-negative integer. + self.dim = Q.dim() # We allow this to be any nonnegative integer. self.exceptional_primes = [infinity] # Deal with the special cases of 0 and 1-dimensional forms @@ -293,7 +291,7 @@ def squareclass_vector(self, p) -> list: - ``p`` -- a positive prime number or "infinity" - OUTPUT: a list of integers + OUTPUT: list of integers EXAMPLES:: @@ -318,7 +316,7 @@ def local_conditions_vector_for_prime(self, p) -> list: - ``p`` -- a positive prime number. (Is 'infinity' allowed here?) - OUTPUT: a list of integers + OUTPUT: list of integers EXAMPLES:: @@ -362,7 +360,7 @@ def local_conditions_vector_for_prime(self, p) -> list: return [2, infinity, infinity, infinity, infinity, infinity, infinity, infinity, infinity] return [p, infinity, infinity, infinity, infinity, None, None, None, None] - raise RuntimeError("the stored dimension should be a non-negative integer") + raise RuntimeError("the stored dimension should be a nonnegative integer") def is_universal_at_prime(self, p) -> bool: r""" @@ -487,7 +485,7 @@ def is_locally_represented_at_place(self, m, p) -> bool: INPUT: - - ``m`` -- an integer + - ``m`` -- integer - ``p`` -- a positive prime number or "infinity" @@ -556,7 +554,7 @@ def is_locally_represented(self, m) -> bool: INPUT: - - ``m`` -- an integer + - ``m`` -- integer OUTPUT: boolean @@ -823,7 +821,7 @@ def is_locally_represented_number_at_place(self, m, p) -> bool: INPUT: - - ``m`` -- an integer + - ``m`` -- integer - ``p`` -- a prime number > 0 or 'infinity' @@ -868,7 +866,7 @@ def is_locally_represented_number(self, m) -> bool: INPUT: - - ``m`` -- an integer + - ``m`` -- integer OUTPUT: boolean diff --git a/src/sage/quadratic_forms/quadratic_form__mass.py b/src/sage/quadratic_forms/quadratic_form__mass.py index 67bf06d888a..96aa23610cd 100644 --- a/src/sage/quadratic_forms/quadratic_form__mass.py +++ b/src/sage/quadratic_forms/quadratic_form__mass.py @@ -38,9 +38,7 @@ def shimura_mass__maximal(self): quadratic lattice. This works for any totally real number field, but has a small technical restriction when `n` is odd. - OUTPUT: - - a rational number + OUTPUT: a rational number EXAMPLES:: @@ -59,9 +57,7 @@ def GHY_mass__maximal(self): See [GHY, Prop 7.4 and 7.5, p121] and [GY, Thrm 10.20, p25]. - OUTPUT: - - a rational number + OUTPUT: a rational number EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__mass__Conway_Sloane_masses.py b/src/sage/quadratic_forms/quadratic_form__mass__Conway_Sloane_masses.py index 894ee68cec9..89460d08713 100644 --- a/src/sage/quadratic_forms/quadratic_form__mass__Conway_Sloane_masses.py +++ b/src/sage/quadratic_forms/quadratic_form__mass__Conway_Sloane_masses.py @@ -31,11 +31,9 @@ def parity(self, allow_rescaling_flag=True): INPUT: - ``self`` -- a quadratic form with base ring `\ZZ`, which we may - require to have integer Gram matrix. + require to have integer Gram matrix - OUTPUT: - - One of the strings: "even" or "odd" + OUTPUT: one of the strings: ``'even'`` or ``'odd'`` EXAMPLES:: @@ -143,7 +141,6 @@ def is_odd(self, allow_rescaling_flag=True): sage: Q = QuadraticForm(ZZ, 2, [1, 1, 1]) sage: Q.is_odd() False - """ return self.parity(allow_rescaling_flag) == "odd" @@ -158,7 +155,7 @@ def conway_species_list_at_odd_prime(self, p): number is always positive, otherwise it may be positive or negative (or zero, but that is considered positive by convention). - .. NOTE: + .. NOTE:: The species of a zero dimensional form is always 0+, so we interpret the return value of zero as positive here! =) @@ -167,7 +164,7 @@ def conway_species_list_at_odd_prime(self, p): - ``p`` -- a positive prime number - OUTPUT: a list of integers + OUTPUT: list of integers EXAMPLES:: @@ -182,7 +179,6 @@ def conway_species_list_at_odd_prime(self, p): [5, 2] sage: Q.conway_species_list_at_odd_prime(5) [-6, 1] - """ # Sanity Check: if not (p > 2 and is_prime(p)): @@ -233,7 +229,7 @@ def conway_species_list_at_2(self): The species of a zero dimensional form is always 0+, so we interpret the return value of zero as positive here! =) - OUTPUT: a list of integers + OUTPUT: list of integers EXAMPLES:: @@ -246,7 +242,6 @@ def conway_species_list_at_2(self): sage: Q = DiagonalQuadraticForm(ZZ, range(1,8)) sage: Q.conway_species_list_at_2() [1, 3, 1, 1, 1] - """ # Some useful variables n = self.dim() @@ -312,7 +307,7 @@ def conway_octane_of_this_unimodular_Jordan_block_at_2(self): unimodular blocks of size `\leq 2` and the `1 \times 1` blocks are all in the upper leftmost position. - OUTPUT: an integer `0 \leq x \leq 7` + OUTPUT: integer `0 \leq x \leq 7` EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__mass__Siegel_densities.py b/src/sage/quadratic_forms/quadratic_form__mass__Siegel_densities.py index 9133a84b76f..e1b7c897032 100644 --- a/src/sage/quadratic_forms/quadratic_form__mass__Siegel_densities.py +++ b/src/sage/quadratic_forms/quadratic_form__mass__Siegel_densities.py @@ -23,7 +23,7 @@ from sage.rings.rational_field import QQ -def mass__by_Siegel_densities(self, odd_algorithm="Pall", even_algorithm="Watson"): +def mass__by_Siegel_densities(self, odd_algorithm='Pall', even_algorithm='Watson'): """ Return the mass of transformations (det 1 and -1). @@ -33,9 +33,10 @@ def mass__by_Siegel_densities(self, odd_algorithm="Pall", even_algorithm="Watson INPUT: - - ``odd_algorithm`` -- algorithm to be used when `p>2`; ``"Pall"`` (only one choice for now) - - ``even_algorithm`` -- algorithm to be used when `p=2`; - either ``"Kitaoka"`` or ``"Watson"`` (the default) + - ``odd_algorithm`` -- algorithm to be used when `p>2`; ``'Pall'`` (only + one choice for now) + - ``even_algorithm`` -- algorithm to be used when `p=2`; either + ``'Kitaoka'`` or ``'Watson'`` (the default) REFERENCES: @@ -126,7 +127,7 @@ def Pall_mass_density_at_odd_prime(self, p): - ``p`` -- a prime number > 2 - OUTPUT: a rational number. + OUTPUT: a rational number EXAMPLES:: @@ -267,7 +268,6 @@ def Kitaoka_mass_at_2(self): sage: Q = DiagonalQuadraticForm(ZZ, [1,1,1]) sage: Q.Kitaoka_mass_at_2() # WARNING: WE NEED TO CHECK THIS CAREFULLY! 1/2 - """ # Make a 0-dim'l quadratic form (for initialization purposes) Null_Form = deepcopy(self) @@ -352,7 +352,7 @@ def mass_at_two_by_counting_mod_power(self, k): INPUT: - - ``k`` -- an integer `\geq 1` + - ``k`` -- integer `\geq 1` OUTPUT: a rational number diff --git a/src/sage/quadratic_forms/quadratic_form__neighbors.py b/src/sage/quadratic_forms/quadratic_form__neighbors.py index 25566313812..d4d579409d3 100644 --- a/src/sage/quadratic_forms/quadratic_form__neighbors.py +++ b/src/sage/quadratic_forms/quadratic_form__neighbors.py @@ -18,7 +18,7 @@ def find_primitive_p_divisible_vector__random(self, p): """ Find a random `p`-primitive vector in `L/pL` whose value is `p`-divisible. - .. note:: + .. NOTE:: Since there are about `p^{(n-2)}` of these lines, we have a `1/p` chance of randomly finding an appropriate vector. @@ -59,7 +59,7 @@ def find_primitive_p_divisible_vector__next(self, p, v=None): value is `p`-divisible, where the last vector returned was `v`. For an initial call, no `v` needs to be passed. - Return vectors whose last non-zero entry is normalized to 0 or 1 (so no + Return vectors whose last nonzero entry is normalized to 0 or 1 (so no lines are counted repeatedly). The ordering is by increasing the first non-normalized entry. If we have tested all (lines of) vectors, then return None. @@ -97,12 +97,12 @@ def find_primitive_p_divisible_vector__next(self, p, v=None): if n <= 1: raise NotImplementedError("Sorry -- Not implemented yet!") - # Look for the last non-zero entry (which must be 1) + # Look for the last nonzero entry (which must be 1) nz = n - 1 while w[nz] == 0: nz += -1 - # Test that the last non-zero entry is 1 (to detect tampering). + # Test that the last nonzero entry is 1 (to detect tampering). if w[nz] != 1: print("Warning: The input vector to QuadraticForm.find_primitive_p_divisible_vector__next() is not normalized properly.") @@ -124,7 +124,7 @@ def find_primitive_p_divisible_vector__next(self, p, v=None): w[j] = 0 if nz != 0: - # Move the non-zero normalized index over by one, or + # Move the nonzero normalized index over by one, or # return the zero vector w[nz - 1] = 1 nz += -1 @@ -153,8 +153,8 @@ def find_p_neighbor_from_vec(self, p, y, return_matrix=False): - ``p`` -- a prime number - ``y`` -- a vector with `q(y) \in p \ZZ` - - ``odd`` -- (default: ``False``) if `p=2`, return also odd neighbors - - ``return_matrix`` -- (boolean, default ``False``) return + - ``odd`` -- boolean (default: ``False``); if `p=2`, return also odd neighbors + - ``return_matrix`` -- boolean (default: ``False``); return the transformation matrix instead of the quadratic form EXAMPLES:: @@ -259,7 +259,7 @@ def neighbor_iteration(seeds, p, mass=None, max_classes=None, INPUT: - - ``seeds`` -- a list of quadratic forms in the same genus + - ``seeds`` -- list of quadratic forms in the same genus - ``p`` -- a prime number @@ -272,7 +272,7 @@ def neighbor_iteration(seeds, p, mass=None, max_classes=None, - ``max_random_trys`` -- (default: ``1000``) the maximum number of neighbors computed for a single lattice - OUTPUT: a list of quadratic forms + OUTPUT: list of quadratic forms EXAMPLES:: @@ -386,7 +386,7 @@ def orbits_lines_mod_p(self, p): - ``p`` -- a prime number - OUTPUT: a list of vectors over ``GF(p)`` + OUTPUT: list of vectors over ``GF(p)`` EXAMPLES:: diff --git a/src/sage/quadratic_forms/quadratic_form__split_local_covering.py b/src/sage/quadratic_forms/quadratic_form__split_local_covering.py index 4db788e5e44..14c7bdfb279 100644 --- a/src/sage/quadratic_forms/quadratic_form__split_local_covering.py +++ b/src/sage/quadratic_forms/quadratic_form__split_local_covering.py @@ -36,9 +36,9 @@ def cholesky_decomposition(self, bit_prec=53): INPUT: - - ``bit_prec`` -- a natural number (default 53) + - ``bit_prec`` -- a natural number (default: 53) - OUTPUT: an upper triangular real matrix of precision ``bit_prec``. + OUTPUT: an upper triangular real matrix of precision ``bit_prec`` .. TODO:: @@ -46,7 +46,7 @@ def cholesky_decomposition(self, bit_prec=53): If we only care about working over the real double field (``RDF``), then we can use the method :meth:`cholesky` present for square matrices over that. - .. note:: + .. NOTE:: There is a note in the original code reading @@ -55,7 +55,6 @@ def cholesky_decomposition(self, bit_prec=53): Finds the Cholesky decomposition of a quadratic form -- as an upper-triangular matrix! (It's assumed to be global, hence twice the form it refers to.) <-- Python revision asks: Is this true?!? =| - EXAMPLES:: sage: Q = DiagonalQuadraticForm(ZZ, [1,1,1]) @@ -118,7 +117,7 @@ def vectors_by_length(self, bound): INPUT: - - ``bound`` -- an integer `\geq 0` + - ``bound`` -- integer `\geq 0` OUTPUT: @@ -278,7 +277,7 @@ def complementary_subform_to_vector(self, v): INPUT: - - ``v`` -- a list of ``self.dim()`` integers + - ``v`` -- list of ``self.dim()`` integers OUTPUT: a :class:`QuadraticForm` over `\ZZ` @@ -312,7 +311,7 @@ def complementary_subform_to_vector(self, v): # Copy the quadratic form Q = deepcopy(self) - # Find the first non-zero component of v, and call it nz (Note: 0 <= nz < n) + # Find the first nonzero component of v, and call it nz (Note: 0 <= nz < n) nz = 0 while nz < n and v[nz] == 0: nz += 1 @@ -356,7 +355,7 @@ def complementary_subform_to_vector(self, v): def split_local_cover(self): r""" - Tries to find subform of the given (positive definite quaternary) + Try to find subform of the given (positive definite quaternary) quadratic form `Q` of the form .. MATH:: diff --git a/src/sage/quadratic_forms/quadratic_form__ternary_Tornaria.py b/src/sage/quadratic_forms/quadratic_form__ternary_Tornaria.py index cc7a6549312..0e447f982dd 100644 --- a/src/sage/quadratic_forms/quadratic_form__ternary_Tornaria.py +++ b/src/sage/quadratic_forms/quadratic_form__ternary_Tornaria.py @@ -53,7 +53,6 @@ def disc(self): 4 sage: DiagonalQuadraticForm(ZZ, [1,1,1,1]).disc() 16 - """ if is_odd(self.dim()): # This is not so good for characteristic 2. @@ -129,7 +128,6 @@ def adjoint(self): [ 39 2 8 ] [ * 19 4 ] [ * * 8 ] - """ from sage.quadratic_forms.quadratic_form import QuadraticForm as QuadraticForm diff --git a/src/sage/quadratic_forms/quadratic_form__theta.py b/src/sage/quadratic_forms/quadratic_form__theta.py index c4f0606df4c..2929751bea8 100644 --- a/src/sage/quadratic_forms/quadratic_form__theta.py +++ b/src/sage/quadratic_forms/quadratic_form__theta.py @@ -50,7 +50,6 @@ def theta_series(self, Max=10, var_str='q', safe_flag=True): 1 + 2*q + 2*q^3 + 6*q^4 + 2*q^5 + 4*q^6 + 6*q^7 + 8*q^8 + 14*q^9 + 4*q^10 + 12*q^11 + 18*q^12 + 12*q^13 + 12*q^14 + 8*q^15 + 34*q^16 + 12*q^17 + 8*q^18 + 32*q^19 + 10*q^20 + 28*q^21 + 16*q^23 + 44*q^24 + O(q^25) - """ # Sanity Check: Max is an integer or an allowed string: try: @@ -89,8 +88,8 @@ def theta_by_pari(self, Max, var_str='q', safe_flag=True): INPUT: - - ``Max`` -- an integer `\geq 0` - - ``var_str`` -- a string + - ``Max`` -- integer `\geq 0` + - ``var_str`` -- string OUTPUT: a power series or a vector @@ -103,7 +102,6 @@ def theta_by_pari(self, Max, var_str='q', safe_flag=True): ....: for i in range(1, Prec)] sage: compute == exact # needs sage.libs.pari True - """ # Try to use the cached result if it's enough precision if hasattr(self, '__theta_vec') and len(self.__theta_vec) >= Max: @@ -271,11 +269,9 @@ def theta_series_degree_2(Q, prec): INPUT: - - ``prec`` -- an integer - - OUTPUT: + - ``prec`` -- integer - dictionary, where: + OUTPUT: dictionary, where: - keys are `{\rm GL}_2(\ZZ)`-reduced binary quadratic forms (given as triples of coefficients) diff --git a/src/sage/quadratic_forms/quadratic_form__variable_substitutions.py b/src/sage/quadratic_forms/quadratic_form__variable_substitutions.py index aa72053793b..ba3b26bacaa 100644 --- a/src/sage/quadratic_forms/quadratic_form__variable_substitutions.py +++ b/src/sage/quadratic_forms/quadratic_form__variable_substitutions.py @@ -84,7 +84,7 @@ def multiply_variable(self, c, i, in_place=False): - ``c`` -- an element of ``self.base_ring()`` - - ``i`` -- an integer `\geq 0` + - ``i`` -- integer `\geq 0` OUTPUT: a :class:`QuadraticForm` (by default, otherwise none) @@ -127,7 +127,7 @@ def divide_variable(self, c, i, in_place=False): - ``c`` -- an element of ``self.base_ring()`` - - ``i`` -- an integer `\geq 0` + - ``i`` -- integer `\geq 0` OUTPUT: @@ -218,7 +218,7 @@ def extract_variables(QF, var_indices): INPUT: - - ``var_indices`` -- a list of integers `\geq 0` + - ``var_indices`` -- list of integers `\geq 0` OUTPUT: a :class:`QuadraticForm` diff --git a/src/sage/quadratic_forms/random_quadraticform.py b/src/sage/quadratic_forms/random_quadraticform.py index 0d751e1f584..fb36812bcbd 100644 --- a/src/sage/quadratic_forms/random_quadraticform.py +++ b/src/sage/quadratic_forms/random_quadraticform.py @@ -24,11 +24,11 @@ def random_quadraticform(R, n, rand_arg_list=None): INPUT: - ``R`` -- a ring - - ``n`` -- an integer `\ge 0` - - ``rand_arg_list`` -- a list of at most 3 arguments which can be taken by - ``R.random_element()``. + - ``n`` -- integer `\ge 0` + - ``rand_arg_list`` -- list of at most 3 arguments which can be taken by + ``R.random_element()`` - OUTPUT: A quadratic form over the ring `R`. + OUTPUT: a quadratic form over the ring `R` EXAMPLES:: @@ -134,10 +134,10 @@ def random_ternaryqf(rand_arg_list=None): INPUT: - - ``rand_arg_list`` -- a list of at most 3 arguments which can be taken by - ``R.random_element()``. + - ``rand_arg_list`` -- list of at most 3 arguments which can be taken by + ``R.random_element()`` - OUTPUT: A ternary quadratic form. + OUTPUT: a ternary quadratic form EXAMPLES:: diff --git a/src/sage/quadratic_forms/special_values.py b/src/sage/quadratic_forms/special_values.py index 2ee775e053d..0b865877525 100644 --- a/src/sage/quadratic_forms/special_values.py +++ b/src/sage/quadratic_forms/special_values.py @@ -1,10 +1,10 @@ r""" Routines for computing special values of `L`-functions -- :func:`gamma__exact` -- Exact values of the `\Gamma` function at integers and half-integers -- :func:`zeta__exact` -- Exact values of the Riemann `\zeta` function at critical values -- :func:`quadratic_L_function__exact` -- Exact values of the Dirichlet L-functions of quadratic characters at critical values -- :func:`quadratic_L_function__numerical` -- Numerical values of the Dirichlet L-functions of quadratic characters in the domain of convergence +- :func:`gamma__exact` -- exact values of the `\Gamma` function at integers and half-integers +- :func:`zeta__exact` -- exact values of the Riemann `\zeta` function at critical values +- :func:`quadratic_L_function__exact` -- exact values of the Dirichlet `L`-functions of quadratic characters at critical values +- :func:`quadratic_L_function__numerical` -- numerical values of the Dirichlet `L`-functions of quadratic characters in the domain of convergence """ import sage.rings.abc @@ -96,7 +96,7 @@ def gamma__exact(n): def zeta__exact(n): r""" - Return the exact value of the Riemann Zeta function + Return the exact value of the Riemann Zeta function. The argument must be a critical value, namely either positive even or negative odd. @@ -268,7 +268,7 @@ def quadratic_L_function__exact(n, d): def quadratic_L_function__numerical(n, d, num_terms=1000): """ - Evaluate the Dirichlet L-function (for quadratic character) numerically + Evaluate the Dirichlet `L`-function (for quadratic character) numerically (in a very naive way). EXAMPLES: diff --git a/src/sage/quadratic_forms/ternary.pyx b/src/sage/quadratic_forms/ternary.pyx index 4ed6d76ed3d..345d6b962b3 100644 --- a/src/sage/quadratic_forms/ternary.pyx +++ b/src/sage/quadratic_forms/ternary.pyx @@ -27,7 +27,7 @@ def red_mfact(a, b): - ``a``, ``b`` -- integers - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -594,7 +594,6 @@ def _find_zeros_mod_p_odd(long long a, long long b, long long c, long long r, lo (0, 32, 1) sage: Q((0, 32, 1)) 2018 - """ cdef long long a_i diff --git a/src/sage/quadratic_forms/ternary_qf.py b/src/sage/quadratic_forms/ternary_qf.py index 5debc32e846..79436ff4f77 100644 --- a/src/sage/quadratic_forms/ternary_qf.py +++ b/src/sage/quadratic_forms/ternary_qf.py @@ -52,11 +52,9 @@ class TernaryQF(SageObject): INPUT: - - ``v`` -- a list or tuple of 6 entries: ``[a,b,c,r,s,t]`` + - ``v`` -- list or tuple of 6 entries: ``[a,b,c,r,s,t]`` - OUTPUT: - - - the ternary quadratic form `a\cdot x^2 + b\cdot y^2 + c\cdot z^2 + r\cdot y\cdot z + s\cdot x\cdot z + t\cdot x\cdot y`. + OUTPUT: the ternary quadratic form `a\cdot x^2 + b\cdot y^2 + c\cdot z^2 + r\cdot y\cdot z + s\cdot x\cdot z + t\cdot x\cdot y` EXAMPLES:: @@ -117,7 +115,7 @@ def coefficients(self): def __hash__(self): """ - Returns a hash for self. + Return a hash for ``self``. EXAMPLES:: @@ -135,7 +133,7 @@ def coefficient(self, n): INPUT: - - ``n`` -- integer with `0 \leq n \leq 5`. + - ``n`` -- integer with `0 \leq n \leq 5` EXAMPLES:: @@ -426,7 +424,7 @@ def is_negative_definite(self) -> bool: def __neg__(self): """ - Return the ternary quadratic form with coefficients negatives of self. + Return the ternary quadratic form with coefficients negatives of ``self``. EXAMPLES:: @@ -951,7 +949,6 @@ def find_p_neighbors(self, p, mat=False): 1 sage: neig.count(Q2) 3 - """ z = self.find_zeros_mod_p(p) @@ -1309,8 +1306,6 @@ def _automorphisms_reduced_fast(self): sage: Q = TernaryQF([3, 4, 5, 3, 3, 2]) sage: Q._automorphisms_reduced_fast() [(1, 0, 0, 0, 1, 0, 0, 0, 1)] - - """ if self._border(1): diff --git a/src/sage/quivers/algebra.py b/src/sage/quivers/algebra.py index 90def69304a..9e867cadc7c 100644 --- a/src/sage/quivers/algebra.py +++ b/src/sage/quivers/algebra.py @@ -41,13 +41,11 @@ class PathAlgebra(CombinatorialFreeModule): - ``P`` -- the path semigroup of a quiver `Q` - - ``order`` -- optional string, one of "negdegrevlex" (default), - "degrevlex", "negdeglex" or "deglex", defining the monomial order to be - used. + - ``order`` -- string; one of ``'negdegrevlex'`` (default), + ``'degrevlex'``, ``'negdeglex'`` or ``'deglex'``, defining the monomial + order to be used - OUTPUT: - - - the path algebra `kP` with the given monomial order + OUTPUT: the path algebra `kP` with the given monomial order .. NOTE:: @@ -67,7 +65,7 @@ class PathAlgebra(CombinatorialFreeModule): sage: A is P.algebra(GF(7)) True - sage: A is P.algebra(GF(7), order="degrevlex") + sage: A is P.algebra(GF(7), order='degrevlex') False sage: A is P.algebra(RR) False @@ -132,7 +130,7 @@ class PathAlgebra(CombinatorialFreeModule): # # ########################################################################### - def __init__(self, k, P, order="negdegrevlex"): + def __init__(self, k, P, order='negdegrevlex'): """ Create a :class:`PathAlgebra` object. @@ -179,9 +177,9 @@ def order_string(self) -> str: EXAMPLES:: sage: P1 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t')) - sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") - sage: P3 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="negdeglex") - sage: P4 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="deglex") + sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') + sage: P3 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='negdeglex') + sage: P4 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='deglex') sage: P1.order_string() 'negdegrevlex' sage: P2.order_string() @@ -190,7 +188,6 @@ def order_string(self) -> str: 'negdeglex' sage: P4.order_string() 'deglex' - """ return self._ordstr @@ -277,7 +274,6 @@ def ngens(self): sage: A = P.algebra(GF(5)) sage: A.ngens() 7 - """ return self._semigroup.ngens() @@ -300,7 +296,6 @@ def _element_constructor_(self, x): 2*e_0 + 2*e_1 + 2*e_2 + 2*e_3 sage: B([(0,1,'a'),(1,2,'c')]) # indirect doctest a*c - """ from sage.quivers.paths import QuiverPath # If it's an element of another path algebra, do a linear combination @@ -399,7 +394,6 @@ def _coerce_map_from_(self, other): 2*e_0 + 2*e_1 + 2*e_2 + 2*e_3 sage: B(2)*x*B(3) # indirect doctest e_2 + b + e_3 - """ if isinstance(other, PathAlgebra) and self._base.has_coerce_map_from(other._base): OQ = other._quiver @@ -430,8 +424,8 @@ def _repr_monomial(self, data): INPUT: - A list providing the indices of the path algebra generators occurring - in the monomial. + - ``data`` -- list providing the indices of the path algebra + generators occurring in the monomial EXAMPLES:: @@ -439,7 +433,6 @@ def _repr_monomial(self, data): sage: X = sage_eval('a+2*b+3*c+5*e_0+3*e_2', A.gens_dict()) sage: X # indirect doctest 5*e_0 + a + 2*b + 3*c + 3*e_2 - """ # m is [list, pos, mid], where the list gives the nb of arrows, pos # gives the component in the module, and mid gives the length of the @@ -453,8 +446,8 @@ def _latex_monomial(self, data): INPUT: - A list providing the indices of the path algebra generators occurring - in the monomial. + - ``data`` -- list providing the indices of the path algebra + generators occurring in the monomial EXAMPLES:: @@ -462,7 +455,6 @@ def _latex_monomial(self, data): sage: X = sage_eval('a+2*b+3*c+5*e_0+3*e_2', A.gens_dict()) sage: latex(X) # indirect doctest 5 e_0 + a + 2 b + 3 c + 3 e_2 - """ arrows = self.variable_names() return '\\cdot '.join(arrows[n] for n in data) @@ -496,9 +488,7 @@ def quiver(self): """ Return the quiver from which the algebra ``self`` was formed. - OUTPUT: - - - :class:`DiGraph`, the quiver of the algebra + OUTPUT: :class:`DiGraph`; the quiver of the algebra EXAMPLES:: @@ -563,11 +553,11 @@ def degree_on_basis(self, x): def sum(self, iter_of_elements): """ - Return the sum of all elements in ``iter_of_elements`` + Return the sum of all elements in ``iter_of_elements``. INPUT: - - ``iter_of_elements``: iterator of elements of ``self`` + - ``iter_of_elements`` -- iterator of elements of ``self`` .. NOTE:: @@ -654,7 +644,6 @@ def homogeneous_component(self, n): sage: A = P.algebra(ZZ) sage: A.homogeneous_component(3) Free module spanned by [a*b*c, b*c*a, c*a*b] over Integer Ring - """ basis = [] for v in self._semigroup._quiver: @@ -667,7 +656,7 @@ def homogeneous_component(self, n): def homogeneous_components(self): r""" - Return the non-zero homogeneous components of ``self``. + Return the nonzero homogeneous components of ``self``. EXAMPLES:: diff --git a/src/sage/quivers/algebra_elements.pyx b/src/sage/quivers/algebra_elements.pyx index 63d187b05f6..a8f7778b202 100644 --- a/src/sage/quivers/algebra_elements.pyx +++ b/src/sage/quivers/algebra_elements.pyx @@ -106,7 +106,6 @@ cdef class PathAlgebraElement(RingElement): computations are not available for path algebras, yet. Hence, to implement computations in graded quotients of free algebras, the letterplace implementation currently is the only option. - """ def __cinit__(self): """ @@ -139,11 +138,11 @@ cdef class PathAlgebraElement(RingElement): INPUT: - - ``S``, a path algebra. + - ``S`` -- path algebra - - ``data``, a dictionary. Most of its keys are + - ``data`` -- dictionary; most of its keys are :class:`~sage.quivers.paths.QuiverPath`, the value giving its - coefficient. + coefficient .. NOTE:: @@ -156,17 +155,17 @@ cdef class PathAlgebraElement(RingElement): Defining e_1, x, y, z sage: (x+2*z+1)^2 e_1 + 4*z + 2*x + 4*z*z + 2*x*z + 2*z*x + x*x - sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P2.inject_variables() Defining e_1, x, y, z sage: (x+2*z+1)^2 4*z*z + 2*x*z + 2*z*x + x*x + 4*z + 2*x + e_1 - sage: P3 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="negdeglex") + sage: P3 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='negdeglex') sage: P3.inject_variables() Defining e_1, x, y, z sage: (x+2*z+1)^2 e_1 + 4*z + 2*x + 4*z*z + 2*z*x + 2*x*z + x*x - sage: P4 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="deglex") + sage: P4 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='deglex') sage: P4.inject_variables() Defining e_1, x, y, z sage: (x+2*z+1)^2 @@ -408,7 +407,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -464,7 +463,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -503,7 +502,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -560,7 +559,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -615,7 +614,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -690,7 +689,7 @@ cdef class PathAlgebraElement(RingElement): INPUT: - An element of the underlying partial semigroup. + - ``P`` -- an element of the underlying partial semigroup OUTPUT: @@ -699,7 +698,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -737,7 +736,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -789,7 +788,7 @@ cdef class PathAlgebraElement(RingElement): """ EXAMPLES:: - sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") + sage: P = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') sage: P.inject_variables() Defining e_1, x, y, z sage: p = (x+2*z+1)^3 @@ -921,7 +920,7 @@ cdef class PathAlgebraElement(RingElement): EXAMPLES:: sage: P1 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(3,'t')) - sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(3,'t'), order="deglex") + sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(3,'t'), order='deglex') sage: P1.inject_variables() Defining e_1, x, y, z sage: p = x+y diff --git a/src/sage/quivers/ar_quiver.py b/src/sage/quivers/ar_quiver.py index daa1e755fa5..f13c67dfa32 100644 --- a/src/sage/quivers/ar_quiver.py +++ b/src/sage/quivers/ar_quiver.py @@ -213,7 +213,7 @@ def _repr_(self): # add options to class class options(GlobalOptions): r""" - Sets and displays the global options for Auslander-Reiten quivers. + Set and display the global options for Auslander-Reiten quivers. If no parameters are set, then the function returns a copy of the options dictionary. @@ -240,7 +240,7 @@ class options(GlobalOptions): """ NAME = 'AuslanderReitenQuiver' module = 'sage.quivers.ar_quiver' - latex = dict(default="node", + latex = dict(default='node', description='Specifies how nodes of the AR quiver should be latexed', values=dict(node='latex as the node description', dimension_vector='latex as the dimension vector', @@ -356,7 +356,7 @@ def edge_options(data): edge_opts["label"] = LatexExpr(r"\tau") return edge_opts - G.set_latex_options(format="dot2tex", edge_options=edge_options) + G.set_latex_options(format='dot2tex', edge_options=edge_options) return G def digraph_preprojectives(self, max_depth, with_translations=False): @@ -395,7 +395,7 @@ def digraph_preprojectives(self, max_depth, with_translations=False): prev = cur cur = self._dim_vecs_level(k) - G = DiGraph([verts, edges], format="vertices_and_edges", multiedges=True, immutable=True) + G = DiGraph([verts, edges], format='vertices_and_edges', multiedges=True, immutable=True) return self._digraph_set_latex_options(G) def digraph_postinjectives(self, max_depth, with_translations=False): @@ -434,7 +434,7 @@ def digraph_postinjectives(self, max_depth, with_translations=False): prev = cur cur = self._dim_vecs_level(-k) - G = DiGraph([verts, edges], format="vertices_and_edges", multiedges=True, immutable=True) + G = DiGraph([verts, edges], format='vertices_and_edges', multiedges=True, immutable=True) return self._digraph_set_latex_options(G) @cached_method @@ -444,8 +444,8 @@ def digraph(self, with_translations=False): INPUT: - - ``with_translations`` -- (default: ``False``) if ``True``, then - include the arrows corresponding to the translations. + - ``with_translations`` -- boolean (default: ``False``); if ``True``, then + include the arrows corresponding to the translations EXAMPLES:: @@ -491,7 +491,7 @@ def digraph(self, with_translations=False): cur = self._dim_vecs_level(k) self._injectives = Family(injectives) - G = DiGraph([verts, edges], format="vertices_and_edges", immutable=True) + G = DiGraph([verts, edges], format='vertices_and_edges', immutable=True) return self._digraph_set_latex_options(G) diff --git a/src/sage/quivers/homspace.py b/src/sage/quivers/homspace.py index 6a987c339ec..e500d7fac43 100644 --- a/src/sage/quivers/homspace.py +++ b/src/sage/quivers/homspace.py @@ -45,7 +45,7 @@ class QuiverHomSpace(Homset): .. NOTE:: The quivers of the domain and codomain must be equal or a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. EXAMPLES:: @@ -272,9 +272,7 @@ def __call__(self, *data, **kwds): default call method of :class:`~sage.categories.homset.Homset` is called instead. - OUTPUT: - - - :class:`QuiverRepHom` + OUTPUT: :class:`QuiverRepHom` EXAMPLES:: @@ -383,9 +381,7 @@ def _identity(self): """ Return the identity map. - OUTPUT: - - - :class:`QuiverRepHom` + OUTPUT: :class:`QuiverRepHom` EXAMPLES:: @@ -427,9 +423,7 @@ def quiver(self): """ Return the quiver of the representations. - OUTPUT: - - - :class:`DiGraph`, the quiver of the representations + OUTPUT: :class:`DiGraph`; the quiver of the representations EXAMPLES:: @@ -444,9 +438,7 @@ def domain(self): """ Return the domain of the hom space. - OUTPUT: - - - :class:`QuiverRep`, the domain of the Hom space + OUTPUT: :class:`QuiverRep`; the domain of the Hom space EXAMPLES:: @@ -462,9 +454,7 @@ def codomain(self): """ Return the codomain of the hom space. - OUTPUT: - - - :class:`QuiverRep`, the codomain of the Hom space + OUTPUT: :class:`QuiverRep`; the codomain of the Hom space EXAMPLES:: @@ -487,9 +477,7 @@ def dimension(self): """ Return the dimension of the hom space. - OUTPUT: - - - integer, the dimension + OUTPUT: integer; the dimension EXAMPLES:: @@ -505,9 +493,7 @@ def gens(self) -> tuple: Return a tuple of generators of the hom space (as a `k`-vector space). - OUTPUT: - - - tuple of :class:`QuiverRepHom` objects, the generators + OUTPUT: tuple of :class:`QuiverRepHom` objects; the generators EXAMPLES:: @@ -577,16 +563,14 @@ def left_module(self, basis=False): INPUT: - - ``basis`` -- bool. If ``False``, then only the module is + - ``basis`` -- boolean; if ``False``, then only the module is returned. If ``True``, then a tuple is returned. The first element is the QuiverRep and the second element is a dictionary which associates to each vertex a list. The elements of this list are the homomorphisms which correspond to the basis elements of that vertex in the module. - OUTPUT: - - - :class:`QuiverRep` or tuple + OUTPUT: :class:`QuiverRep` or tuple .. WARNING:: diff --git a/src/sage/quivers/morphism.py b/src/sage/quivers/morphism.py index f6c2ca180a6..b35941eb05d 100644 --- a/src/sage/quivers/morphism.py +++ b/src/sage/quivers/morphism.py @@ -66,9 +66,7 @@ class QuiverRepHom(CallMorphism): and from ``C`` to the codomain of ``self``. The composition of these maps is the result. - OUTPUT: - - - :class:`QuiverRepHom` + OUTPUT: :class:`QuiverRepHom` EXAMPLES:: @@ -446,7 +444,7 @@ def __isub__(self, other): def __neg__(self): """ - This function overrides the unary ``-`` operator + This function overrides the unary ``-`` operator. TESTS:: @@ -469,7 +467,7 @@ def __neg__(self): def __pos__(self): """ - This function overrides the unary ``+`` operator + This function overrides the unary ``+`` operator. TESTS:: @@ -490,7 +488,7 @@ def __pos__(self): def __eq__(self, other): """ - This function overrides the ``==`` operator + This function overrides the ``==`` operator. TESTS:: @@ -536,7 +534,7 @@ def __hash__(self): def __ne__(self, other): """ - This function overrides the ``!=`` operator + This function overrides the ``!=`` operator. TESTS:: @@ -588,7 +586,7 @@ def __bool__(self) -> bool: def __mul__(self, other): """ - This function overrides the ``*`` operator + This function overrides the ``*`` operator. TESTS:: @@ -616,7 +614,7 @@ def __mul__(self, other): def _assert_valid_hom(self): """ - Raise a :class:`ValueError` if the homomorphism is not well defined. + Raise a :exc:`ValueError` if the homomorphism is not well defined. Specifically it checks that the domain and codomains of the maps are correct and that the edge diagrams commute. @@ -659,9 +657,7 @@ def domain(self): """ Return the domain of the homomorphism. - OUTPUT: - - - :class:`QuiverRep`, the domain + OUTPUT: :class:`QuiverRep`; the domain EXAMPLES:: @@ -680,9 +676,7 @@ def codomain(self): """ Return the codomain of the homomorphism. - OUTPUT: - - - :class:`QuiverRep`, the codomain + OUTPUT: :class:`QuiverRep`; the codomain EXAMPLES:: @@ -704,12 +698,10 @@ def get_matrix(self, vertex): INPUT: - - ``vertex`` -- integer, a vertex of the quiver + - ``vertex`` -- integer; a vertex of the quiver - OUTPUT: - - - matrix, the matrix representing the homomorphism associated to - the given vertex + OUTPUT: the matrix representing the homomorphism associated to + the given vertex EXAMPLES:: @@ -741,11 +733,9 @@ def get_map(self, vertex): INPUT: - - ``vertex`` -- integer, a vertex of the quiver + - ``vertex`` -- integer; a vertex of the quiver - OUTPUT: - - - homomorphism, the homomorphism associated to the given vertex + OUTPUT: the homomorphism associated to the given vertex EXAMPLES:: @@ -781,9 +771,7 @@ def base_ring(self): """ Return the base ring of the representation in the codomain. - OUTPUT: - - - ring, the base ring of the codomain + OUTPUT: the base ring of the codomain EXAMPLES:: @@ -806,9 +794,8 @@ def is_injective(self): """ Test whether the homomorphism is injective. - OUTPUT: - - - bool, ``True`` if the homomorphism is injective, ``False`` otherwise + OUTPUT: boolean; ``True`` if the homomorphism is injective, ``False`` + otherwise EXAMPLES:: @@ -829,9 +816,8 @@ def is_surjective(self): """ Test whether the homomorphism is surjective. - OUTPUT: - - - bool, ``True`` if the homomorphism is surjective, ``False`` otherwise + OUTPUT: boolean; ``True`` if the homomorphism is surjective, ``False`` + otherwise EXAMPLES:: @@ -857,10 +843,8 @@ def is_isomorphism(self): """ Test whether the homomorphism is an isomorphism. - OUTPUT: - - - bool, ``True`` if the homomorphism is bijective, ``False`` - otherwise + OUTPUT: boolean; ``True`` if the homomorphism is bijective, ``False`` + otherwise EXAMPLES:: @@ -880,9 +864,8 @@ def is_zero(self): """ Test whether the homomorphism is the zero homomorphism. - OUTPUT: - - - bool, ``True`` if the homomorphism is zero, ``False`` otherwise + OUTPUT: boolean; ``True`` if the homomorphism is zero, ``False`` + otherwise EXAMPLES:: @@ -902,10 +885,8 @@ def is_endomorphism(self): """ Test whether the homomorphism is an endomorphism. - OUTPUT: - - - bool, ``True`` if the domain equals the codomain, ``False`` - otherwise + OUTPUT: boolean; ``True`` if the domain equals the codomain, ``False`` + otherwise EXAMPLES:: @@ -926,9 +907,7 @@ def rank(self): Return the rank of the homomorphism ``self`` (as a `k`-linear map). - OUTPUT: - - - integer, the rank + OUTPUT: integer; the rank EXAMPLES:: @@ -953,9 +932,7 @@ def kernel(self): """ Return the kernel of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the kernel + OUTPUT: :class:`QuiverRep`; the kernel .. NOTE:: @@ -982,9 +959,7 @@ def image(self): """ Return the image of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the image + OUTPUT: :class:`QuiverRep`; the image .. NOTE:: @@ -1011,9 +986,7 @@ def cokernel(self): """ Return the cokernel of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the cokernel + OUTPUT: :class:`QuiverRep`; the cokernel .. NOTE:: @@ -1040,9 +1013,7 @@ def linear_dual(self): Compute the linear dual `Df : DN \to DM` of ``self`` = `f : M \to N` where `D(-) = Hom_k(-, k)`. - OUTPUT: - - - :class:`QuiverRepHom`, the map `Df : DN \to DM` + OUTPUT: :class:`QuiverRepHom`; the map `Df : DN \to DM` .. NOTE:: @@ -1088,9 +1059,7 @@ def algebraic_dual(self): Compute the algebraic dual `f^t : N^t \to M^t` of ``self`` = `f : M \to N` where `(-)^t = Hom_Q(-, kQ)`. - OUTPUT: - - - :class:`QuiverRepHom`, the map `f^t : N^t \to M^t` + OUTPUT: :class:`QuiverRepHom`; the map `f^t : N^t \to M^t` .. NOTE:: @@ -1131,7 +1100,7 @@ def direct_sum(self, maps, return_maps=False, pinch=None): - ``maps`` -- :class:`QuiverRepHom` or list of :class:`QuiverRepHom`'s - - ``return_maps`` -- bool (default: ``False``). If ``False``, then + - ``return_maps`` -- boolean (default: ``False``); if ``False``, then the return value is a :class:`QuiverRepHom` which is the direct sum of ``self`` with the :class:`QuiverRepHoms` in ``maps``. If ``True``, then the return value is a tuple of length either 3 @@ -1147,7 +1116,7 @@ def direct_sum(self, maps, return_maps=False, pinch=None): If ``pinch`` is either ``'domain'`` or ``'codomain'`` then the tuple will have length 3. - - ``pinch`` -- string or ``None`` (default: ``None``). If this is + - ``pinch`` -- string or ``None`` (default: ``None``); if this is equal to ``'domain'``, then the domains of ``self`` and the given maps must be equal. The direct sum of `f: A \to B` and `g: A \to C` returned is then the map `A \to B \oplus C` defined @@ -1161,9 +1130,7 @@ def direct_sum(self, maps, return_maps=False, pinch=None): `A \oplus C \to B \oplus D` defined by sending `(x, y)` to `(f(x), g(y))`. - OUTPUT: - - - :class:`QuiverRepHom` or tuple + OUTPUT: :class:`QuiverRepHom` or tuple EXAMPLES:: @@ -1246,9 +1213,7 @@ def lift(self, x): - ``x`` -- :class:`QuiverRepElement` - OUTPUT: - - - :class:`QuiverRepElement` + OUTPUT: :class:`QuiverRepElement` EXAMPLES:: diff --git a/src/sage/quivers/path_semigroup.py b/src/sage/quivers/path_semigroup.py index 860242334ba..cb141c02751 100644 --- a/src/sage/quivers/path_semigroup.py +++ b/src/sage/quivers/path_semigroup.py @@ -95,7 +95,7 @@ def __classcall__(cls, Q): INPUT: - - a :class:`~sage.graphs.digraph.DiGraph`. + - ``Q`` -- a :class:`~sage.graphs.digraph.DiGraph` TESTS:: @@ -121,7 +121,7 @@ def __init__(self, Q): INPUT: - - a :class:`~sage.graphs.digraph.DiGraph`. + - ``Q`` -- a :class:`~sage.graphs.digraph.DiGraph` EXAMPLES: @@ -268,7 +268,7 @@ def _coerce_map_from_(self, other): def _element_constructor_(self, data, check=True): """ - The accepted data are + The accepted data are: - the integer ``1``, which returns the first idempotent, - a list, whose only item is a tuple ``(v,v)`` for a vertex ``v``, @@ -294,7 +294,7 @@ def _element_constructor_(self, data, check=True): sage: Q(P(['c','d'])) c*d - A :class:`TypeError` or a :class:`ValueError` is raised appropriately + A :exc:`TypeError` or a :exc:`ValueError` is raised appropriately if the input is wrong:: sage: G = DiGraph([(0,0,'a'), (0,1,'b'), (1,0,'c')], loops=True) @@ -599,7 +599,6 @@ def __iter__(self): c*b*d a*d*c*a a*d*c*b - """ d = 0 length_d_available = True @@ -617,8 +616,8 @@ def iter_paths_by_length_and_startpoint(self, d, v): INPUT: - - ``d`` -- an integer, the path length - - ``v`` -- a vertex, start point of the paths + - ``d`` -- integer; the path length + - ``v`` -- a vertex; start point of the paths EXAMPLES:: @@ -659,7 +658,7 @@ def iter_paths_by_length_and_startpoint(self, d, v): """ # iterate over length d paths starting at vertex v if not d >= 0: - raise ValueError("path length must be a non-negative integer") + raise ValueError("path length must be a nonnegative integer") if v not in self._quiver: raise ValueError("the starting point {} is not a vertex of the underlying quiver".format(v)) if not d: @@ -675,8 +674,8 @@ def iter_paths_by_length_and_endpoint(self, d, v): INPUT: - - ``d`` -- an integer, the path length - - ``v`` -- a vertex, end point of the paths + - ``d`` -- integer; the path length + - ``v`` -- a vertex; end point of the paths EXAMPLES:: @@ -693,7 +692,7 @@ def iter_paths_by_length_and_endpoint(self, d, v): """ # iterate over length d paths ending at vertex v if not d >= 0: - raise ValueError("path length must be a non-negative integer") + raise ValueError("path length must be a nonnegative integer") if v not in self._quiver: raise ValueError("the starting point {} is not a vertex of the underlying quiver".format(v)) if not d: @@ -739,7 +738,7 @@ def reverse(self): """ return self._quiver.reverse().path_semigroup() - def algebra(self, k, order="negdegrevlex"): + def algebra(self, k, order='negdegrevlex'): """ Return the path algebra of the underlying quiver. @@ -747,9 +746,9 @@ def algebra(self, k, order="negdegrevlex"): - ``k`` -- a commutative ring - - ``order`` -- optional string, one of "negdegrevlex" (default), - "degrevlex", "negdeglex" or "deglex", defining the monomial order to - be used. + - ``order`` -- (optional) string, one of ``'negdegrevlex'`` (default), + ``'degrevlex'``, ``'negdeglex'`` or ``'deglex'``, defining the + monomial order to be used .. NOTE:: @@ -765,9 +764,9 @@ def algebra(self, k, order="negdegrevlex"): Now some example with different monomial orderings:: sage: P1 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t')) - sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="degrevlex") - sage: P3 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="negdeglex") - sage: P4 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order="deglex") + sage: P2 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='degrevlex') + sage: P3 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='negdeglex') + sage: P4 = DiGraph({1:{1:['x','y','z']}}).path_semigroup().algebra(GF(25,'t'), order='deglex') sage: P1.order_string() 'negdegrevlex' sage: sage_eval('(x+2*z+1)^3', P1.gens_dict()) @@ -778,7 +777,6 @@ def algebra(self, k, order="negdegrevlex"): e_1 + z + 3*x + 2*z*z + z*x + x*z + 3*x*x + 3*z*z*z + 4*z*z*x + 4*z*x*z + 2*z*x*x + 4*x*z*z + 2*x*z*x + 2*x*x*z + x*x*x sage: sage_eval('(x+2*z+1)^3', P4.gens_dict()) 3*z*z*z + 4*z*z*x + 4*z*x*z + 2*z*x*x + 4*x*z*z + 2*x*z*x + 2*x*x*z + x*x*x + 2*z*z + z*x + x*z + 3*x*x + z + 3*x + e_1 - """ from sage.quivers.algebra import PathAlgebra return PathAlgebra(k, self, order) @@ -817,14 +815,12 @@ def S(self, k, vertex): INPUT: - - `k` -- ring, the base ring of the representation + - ``k`` -- the base ring of the representation - - ``vertex`` -- integer, a vertex of the quiver + - ``vertex`` -- integer; a vertex of the quiver - OUTPUT: - - - :class:`~sage.quivers.representation.QuiverRep`, the simple module - at ``vertex`` with base ring `k` + OUTPUT: :class:`~sage.quivers.representation.QuiverRep`; the simple + module at ``vertex`` with base ring `k` EXAMPLES:: @@ -861,14 +857,12 @@ def P(self, k, vertex): INPUT: - - `k` -- ring, the base ring of the representation + - ``k`` -- the base ring of the representation - - ``vertex`` -- integer, a vertex of the quiver + - ``vertex`` -- integer; a vertex of the quiver - OUTPUT: - - - :class:`~sage.quivers.representation.QuiverRep`, the indecomposable - projective module at ``vertex`` with base ring `k` + OUTPUT: :class:`~sage.quivers.representation.QuiverRep`, the + indecomposable projective module at ``vertex`` with base ring `k` EXAMPLES:: @@ -901,9 +895,9 @@ def I(self, k, vertex): INPUT: - - `k` -- ring, the base ring of the representation + - ``k`` -- the base ring of the representation - - ``vertex`` -- integer, a vertex of the quiver + - ``vertex`` -- integer; a vertex of the quiver OUTPUT: @@ -939,7 +933,7 @@ def free_module(self, k): INPUT: - - ``k`` -- ring, the base ring of the representation. + - ``k`` -- ring; the base ring of the representation OUTPUT: @@ -1016,9 +1010,7 @@ def all_paths(self, start=None, end=None): vertex of the paths in the output; if ``None`` is given then the terminal vertex is arbitrary - OUTPUT: - - - list of paths, excluding the invalid path + OUTPUT: list of paths, excluding the invalid path .. TODO:: @@ -1078,7 +1070,7 @@ def all_paths(self, start=None, end=None): ... ValueError: the end vertex 4 is not a vertex of the quiver - If the underlying quiver is cyclic, a :class:`ValueError` + If the underlying quiver is cyclic, a :exc:`ValueError` is raised:: sage: Q = DiGraph({1:{2:['a','b'], 3:['c']}, 3:{1:['d']}}) diff --git a/src/sage/quivers/paths.pyx b/src/sage/quivers/paths.pyx index 2f6dfc061b1..c3552c09294 100644 --- a/src/sage/quivers/paths.pyx +++ b/src/sage/quivers/paths.pyx @@ -105,7 +105,6 @@ cdef class QuiverPath(MonoidElement): sage: Q = DiGraph({1:{2:['a']}, 2:{3:['b']}}).path_semigroup() sage: p = Q([(1, 1)]) * Q([(1, 1)]) sage: del p # indirect doctest - """ biseq_dealloc(self._path) @@ -125,17 +124,17 @@ cdef class QuiverPath(MonoidElement): def __init__(self, parent, start, end, path): """ - Creates a path object. Type ``QuiverPath?`` for more information. + Create a path object. Type ``QuiverPath?`` for more information. INPUT: - - ``parent``, a path semigroup. - - ``start``, integer, the label of the initial vertex. - - ``end``, integer, the label of the terminal vertex. - - ``path``, list of integers, providing the list of arrows + - ``parent`` -- a path semigroup + - ``start`` -- integer; the label of the initial vertex + - ``end`` -- integer; the label of the terminal vertex + - ``path`` -- list of integers, providing the list of arrows occurring in the path, labelled according to the position in the list of all arrows (resp. the list of outgoing arrows at - each vertex). + each vertex) TESTS:: @@ -322,7 +321,6 @@ cdef class QuiverPath(MonoidElement): False sage: a < a False - """ # Since QuiverPath inherits from Element, it is guaranteed that # both arguments are elements of the same path semigroup @@ -404,7 +402,6 @@ cdef class QuiverPath(MonoidElement): e_4 sage: p[20:40].initial_vertex() == p.terminal_vertex() True - """ cdef tuple E cdef Py_ssize_t start, stop, step, slicelength @@ -527,7 +524,6 @@ cdef class QuiverPath(MonoidElement): a*b sage: print(p % e2) None - """ cdef QuiverPath right = other # Handle trivial case @@ -555,7 +551,7 @@ cdef class QuiverPath(MonoidElement): INPUT: - A :class:`QuiverPath` ``P`` + - ``P`` -- a :class:`QuiverPath` OUTPUT: @@ -594,7 +590,6 @@ cdef class QuiverPath(MonoidElement): b*a*c*d*a*c*d*a*b sage: print(p2[2:-1].gcd(p2[1:])) (None, None, None) - """ if self._parent is not P._parent: return (None, None, None) @@ -624,7 +619,6 @@ cdef class QuiverPath(MonoidElement): (b*c, b*a*d*d) sage: (b*c*a*d*b).complement(a*c) (None, None) - """ cdef mp_size_t i = biseq_contains(self._path, subpath._path, 0) if i == -1: @@ -637,8 +631,8 @@ cdef class QuiverPath(MonoidElement): INPUT: - ``subpath``, a path of positive length in the same path semigroup as - this path. + - ``subpath`` -- a path of positive length in the same path semigroup + as this path EXAMPLES:: @@ -676,11 +670,9 @@ cdef class QuiverPath(MonoidElement): INPUT: - ``subpath``, a path in the same path semigroup as this path. - - OUTPUT: + - ``subpath`` -- a path in the same path semigroup as this path - ``0`` or ``1``, which stands for ``False`` resp. ``True``. + OUTPUT: ``0`` or ``1``, which stands for ``False`` resp. ``True`` EXAMPLES:: @@ -695,7 +687,6 @@ cdef class QuiverPath(MonoidElement): 1 sage: (c*b*e*a).has_prefix(e_2) 0 - """ if subpath._parent is not self._parent: raise ValueError("the two paths belong to different quivers") @@ -711,9 +702,7 @@ cdef class QuiverPath(MonoidElement): """ Return the initial vertex of the path. - OUTPUT: - - - integer, the label of the initial vertex + OUTPUT: integer; the label of the initial vertex EXAMPLES:: @@ -728,9 +717,7 @@ cdef class QuiverPath(MonoidElement): """ Return the terminal vertex of the path. - OUTPUT: - - - integer, the label of the terminal vertex + OUTPUT: integer; the label of the terminal vertex EXAMPLES:: @@ -759,7 +746,6 @@ cdef class QuiverPath(MonoidElement): e_1 sage: e.reversal() e_1 - """ Q = self._parent.reverse() # Handle trivial paths @@ -788,16 +774,16 @@ def NewQuiverPath(Q, start, end, biseq_data): INPUT: - - ``Q``, the path semigroup of a quiver - - ``start``, an integer, the label of the startpoint - - ``end``, an integer, the label of the endpoint - - ``biseq_data``, a tuple formed by + - ``Q`` -- the path semigroup of a quiver + - ``start`` -- integer; the label of the startpoint + - ``end`` -- integer; the label of the endpoint + - ``biseq_data`` -- tuple formed by - - A string, encoding a bitmap representing the path as integer - at base `32`, - - the number of bits used to store the path, + - a string, encoding a bitmap representing the path as integer + at base `32` + - the number of bits used to store the path - the number of bits used to store a single item - - the number of items in the path. + - the number of items in the path TESTS:: diff --git a/src/sage/quivers/representation.py b/src/sage/quivers/representation.py index be58c37fd70..57d2e09a8bd 100644 --- a/src/sage/quivers/representation.py +++ b/src/sage/quivers/representation.py @@ -480,16 +480,16 @@ class QuiverRepFactory(UniqueFactory): are ignored; the keywords are only checked in the event that the argument list does not have enough entries after ``P``. - - ``spaces`` -- dict (default: empty); a dictionary associating to each - vertex a free module over the base ring `k`. Not all vertices must be - specified; unspecified vertices are automatically set to `k^0`. Keys - of the dictionary that don't correspond to vertices are ignored. + - ``spaces`` -- dictionary (default: empty) associating to each vertex a + free module over the base ring `k`. Not all vertices must be specified; + unspecified vertices are automatically set to `k^0`. Keys of the + dictionary that don't correspond to vertices are ignored. - - ``maps`` -- dict (default: empty); a dictionary associating to each edge - a map whose domain and codomain are the spaces associated to the initial - and terminal vertex of the edge respectively. Not all edges must be - specified; unspecified edges are automatically set to the zero map. - Keys of the dictionary that don't correspond to edges are ignored. + - ``maps`` -- dictionary (default: empty) associating to each edge a map + whose domain and codomain are the spaces associated to the initial and + terminal vertex of the edge respectively. Not all edges must be + specified; unspecified edges are automatically set to the zero map. Keys + of the dictionary that don't correspond to edges are ignored. The second option is the ``paths`` option which creates a module by generating a right ideal from a list of paths. Thus the basis elements @@ -502,7 +502,7 @@ class QuiverRepFactory(UniqueFactory): - ``basis`` -- list; a nonempty list of paths in the quiver ``Q``. Entries that do not represent valid paths are ignored and duplicate paths are deleted. There must be at least one valid path in the list - or a :class:`ValueError` is raised. The closure of this list under right + or a :exc:`ValueError` is raised. The closure of this list under right multiplication forms the basis of the resulting representation. The third option is the ``dual paths`` option which creates the dual of @@ -516,18 +516,16 @@ class QuiverRepFactory(UniqueFactory): - ``basis`` -- list; a nonempty list of paths in the quiver ``Q``. Entries that do not represent valid paths are ignored and duplicate paths are deleted. There must be at least one valid path in the list - or a :class:`ValueError` is raised. The closure of this list under left + or a :exc:`ValueError` is raised. The closure of this list under left multiplication of edges forms the basis of the resulting representation. Using the second and third options requires that the following keyword be passed to the constructor. This must be passed as a keyword. - - ``option`` -- string (default: ``None``), either ``'values'`` or - ``'paths'`` or ``'dual paths'``. ``None`` is equivalent to ``'values'``. + - ``option`` -- string (default: ``None``); either ``'values'`` or + ``'paths'`` or ``'dual paths'``. ``None`` is equivalent to ``'values'`` - OUTPUT: - - - :class:`QuiverRep` + OUTPUT: :class:`QuiverRep` EXAMPLES:: @@ -573,7 +571,8 @@ class QuiverRepFactory(UniqueFactory): In the following example, the 3rd and 4th paths are actually the same, so the duplicate is removed:: - sage: N = Q1.representation(QQ, [[(1, 1)], [(2, 2)], [(1, 2, 'a')], [(1, 2, 'a')]], option='paths') + sage: N = Q1.representation(QQ, [[(1, 1)], [(2, 2)], [(1, 2, 'a')], + ....: [(1, 2, 'a')]], option='paths') sage: N.dimension() 3 @@ -607,9 +606,7 @@ def create_key(self, k, P, *args, **kwds): See the class documentation. - OUTPUT: - - - tuple + OUTPUT: tuple EXAMPLES:: @@ -763,9 +760,7 @@ def create_object(self, version, key, **extra_args): - ``version`` -- the version of sage, this is currently ignored - ``key`` -- tuple - OUTPUT: - - - :class:`QuiverRep_generic` or :class:`QuiverRep_with_path_basis` + OUTPUT: :class:`QuiverRep_generic` or :class:`QuiverRep_with_path_basis` EXAMPLES:: @@ -825,20 +820,18 @@ class QuiverRepElement(ModuleElement): INPUT: - - ``module`` -- :class:`QuiverRep` (default: ``None``), the module to + - ``module`` -- :class:`QuiverRep` (default: ``None``); the module to which the element belongs - - ``elements`` -- dict (default: empty), a dictionary associating to each - vertex a vector or an object from which sage can create a vector. - Not all vertices must be specified, unspecified vertices will be - assigned the zero vector of the space associated to that vertex in - the given module. Keys that do not correspond to a vertex are ignored. - - - ``name`` -- string (default: ``None``), the name of the element + - ``elements`` -- dictionary (default: empty) associating to each vertex a + vector or an object from which sage can create a vector. Not all vertices + must be specified, unspecified vertices will be assigned the zero vector + of the space associated to that vertex in the given module. Keys that do + not correspond to a vertex are ignored. - OUTPUT: + - ``name`` -- string (default: ``None``); the name of the element - - :class:`QuiverRepElement` + OUTPUT: :class:`QuiverRepElement` .. NOTE:: @@ -986,7 +979,7 @@ def _neg_(self): def __mul__(self, other): """ - Implements ``*`` for right multiplication by quiver algebra elements. + Implement ``*`` for right multiplication by quiver algebra elements. TESTS:: @@ -1126,9 +1119,7 @@ def quiver(self): """ Return the quiver of the representation. - OUTPUT: - - - :class:`DiGraph`, the quiver of the representation + OUTPUT: :class:`DiGraph`, the quiver of the representation EXAMPLES:: @@ -1146,11 +1137,9 @@ def get_element(self, vertex): INPUT: - - ``vertex`` -- integer, a vertex of the quiver - - OUTPUT: + - ``vertex`` -- integer; a vertex of the quiver - - vector, the vector assigned to the given vertex + OUTPUT: the vector assigned to the given vertex EXAMPLES:: @@ -1178,7 +1167,7 @@ def _set_element(self, vector, vertex): - ``vector`` -- a vector or an object from which the space associated to the given vertex in the parent can create a vector - - ``vertex`` -- integer, a vertex of the quiver + - ``vertex`` -- integer; a vertex of the quiver .. WARNING:: @@ -1212,10 +1201,8 @@ def is_zero(self): """ Test whether ``self`` is zero. - OUTPUT: - - - bool, ``True`` if the element is the zero element, ``False`` - otherwise + OUTPUT: boolean, ``True`` if the element is the zero element, ``False`` + otherwise EXAMPLES:: @@ -1249,9 +1236,7 @@ def support(self): The support is the set of vertices to which a nonzero vector is associated. - OUTPUT: - - - list, the support + OUTPUT: list; the support EXAMPLES:: @@ -1319,22 +1304,18 @@ class QuiverRep_generic(WithEqualityById, Module): - ``P`` -- the path semigroup of the quiver `Q` of the representation - - ``spaces`` -- dict (default: empty), a dictionary associating to each - vertex a free module over the base ring `k`. Not all vertices need - to be specified, unspecified vertices are automatically set to - `k^0`. Keys of the dictionary that don't correspond to vertices are - ignored. - - - ``maps`` -- dict (default: empty), a dictionary associating to each - edge a map whose domain and codomain are the spaces associated to - the initial and terminal vertex of the edge respectively. Not all - edges need to be specified, unspecified edges are automatically set - to the zero map. Keys of the dictionary that don't correspond to - edges are ignored. + - ``spaces`` -- dictionary (default: empty) associating to each vertex a + free module over the base ring `k`. Not all vertices need to be + specified, unspecified vertices are automatically set to `k^0`. Keys of + the dictionary that don't correspond to vertices are ignored. - OUTPUT: + - ``maps`` -- dictionary (default: empty) associating to each edge a map + whose domain and codomain are the spaces associated to the initial and + terminal vertex of the edge respectively. Not all edges need to be + specified, unspecified edges are automatically set to the zero map. Keys + of the dictionary that don't correspond to edges are ignored. - - :class:`QuiverRep` + OUTPUT: :class:`QuiverRep` EXAMPLES:: @@ -1576,11 +1557,9 @@ def _coerce_map_from_(self, domain): INPUT: - - ``domain`` -= a Sage object - - OUTPUT: + - ``domain`` -- a Sage object - - :class:`QuiverRepHom` or bool + OUTPUT: :class:`QuiverRepHom` or boolean TESTS:: @@ -1658,7 +1637,7 @@ def get_space(self, vertex): INPUT: - - ``vertex`` -- integer, a vertex of the quiver of the module + - ``vertex`` -- integer; a vertex of the quiver of the module EXAMPLES:: @@ -1694,9 +1673,7 @@ def quiver(self): """ Return the quiver of the representation. - OUTPUT: - - - :class:`DiGraph` + OUTPUT: :class:`DiGraph` EXAMPLES:: @@ -1711,9 +1688,7 @@ def actor(self): r""" Return the quiver path algebra acting on this representation. - OUTPUT: - - - a quiver path algebra + OUTPUT: a quiver path algebra EXAMPLES:: @@ -1778,9 +1753,7 @@ def dimension_vector(self): """ Return the dimension vector of the representation. - OUTPUT: - - - tuple + OUTPUT: tuple .. NOTE:: @@ -1806,9 +1779,7 @@ def is_zero(self): """ Test whether the representation is zero. - OUTPUT: - - - bool + OUTPUT: boolean EXAMPLES:: @@ -1830,9 +1801,7 @@ def is_simple(self): """ Test whether the representation is simple. - OUTPUT: - - - bool + OUTPUT: boolean EXAMPLES:: @@ -1850,9 +1819,7 @@ def is_semisimple(self): """ Test whether the representation is semisimple. - OUTPUT: - - - bool + OUTPUT: boolean EXAMPLES:: @@ -1872,9 +1839,7 @@ def an_element(self): """ Return an element of ``self``. - OUTPUT: - - - :class:`QuiverRepElement` + OUTPUT: :class:`QuiverRepElement` EXAMPLES:: @@ -2030,9 +1995,7 @@ def linear_combination_of_basis(self, coordinates): coefficient of the `i`-th basis vector in the linear combination. - OUTPUT: - - - :class:`QuiverRepElement` + OUTPUT: :class:`QuiverRepElement` EXAMPLES:: @@ -2071,10 +2034,9 @@ def submodule(self, elements=[], spaces=None): - ``elements`` -- a collection of QuiverRepElements (default: empty list), each should be an element of ``self`` - - ``spaces`` -- dictionary (default: empty), this dictionary - should contain entries of the form ``{v: S}`` where `v` is a - vertex of the quiver and `S` is a subspace of the vector space - associated to `v` + - ``spaces`` -- dictionary (default: empty); should contain entries of + the form ``{v: S}`` where `v` is a vertex of the quiver and `S` is a + subspace of the vector space associated to `v` OUTPUT: @@ -2183,13 +2145,11 @@ def quotient(self, sub, check=True): associated to each edge `e` of ``sub`` is the restriction of the map associated to `e` in ``self`` - - ``check`` -- bool; if ``True`` then ``sub`` is checked to verify + - ``check`` -- boolean; if ``True`` then ``sub`` is checked to verify that it is indeed a submodule of ``self`` and an error is raised if it is not - OUTPUT: - - - :class:`QuiverRep`, the quotient module ``self / sub`` + OUTPUT: :class:`QuiverRep`, the quotient module ``self / sub`` .. NOTE:: @@ -2256,9 +2216,7 @@ def socle(self): """ The socle of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the socle + OUTPUT: :class:`QuiverRep`; the socle EXAMPLES:: @@ -2280,9 +2238,7 @@ def radical(self): """ Return the Jacobson radical of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the Jacobson radical + OUTPUT: :class:`QuiverRep`; the Jacobson radical EXAMPLES:: @@ -2304,9 +2260,7 @@ def top(self): """ Return the top of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the quotient of ``self`` by its radical + OUTPUT: :class:`QuiverRep`; the quotient of ``self`` by its radical EXAMPLES:: @@ -2323,9 +2277,7 @@ def zero_submodule(self): """ Return the zero submodule of ``self``. - OUTPUT: - - - :class:`QuiverRep`, the zero submodule of ``self``. + OUTPUT: :class:`QuiverRep`; the zero submodule of ``self`` EXAMPLES:: @@ -2345,9 +2297,7 @@ def linear_dual(self): Compute the linear dual `Hom_k(M, k)` of the module `M =` ``self`` over the base ring `k`. - OUTPUT: - - - :class:`QuiverRep`, the dual representation + OUTPUT: :class:`QuiverRep`; the dual representation .. NOTE:: @@ -2399,16 +2349,14 @@ def algebraic_dual(self, basis=False): INPUT: - - ``basis`` -- bool; if ``False``, then only the module is + - ``basis`` -- boolean; if ``False``, then only the module is returned. If ``True``, then a tuple is returned. The first element is the :class:`QuiverRep` and the second element is a dictionary which associates to each vertex a list. The elements of this list are the homomorphisms which correspond to the basis elements of that vertex in the module. - OUTPUT: - - - :class:`QuiverRep` or tuple + OUTPUT: :class:`QuiverRep` or tuple .. NOTE:: @@ -2452,7 +2400,7 @@ def direct_sum(self, modules, return_maps=False): - ``modules`` -- :class:`QuiverRep` or list of :class:`QuiverRep`'s - - ``return_maps`` -- Boolean (default: ``False``); if ``False``, then + - ``return_maps`` -- boolean (default: ``False``); if ``False``, then the output is a single QuiverRep object which is the direct sum of ``self`` with the given module or modules. If ``True``, then the output is a list ``[sum, iota, pi]``. The first entry @@ -2463,9 +2411,7 @@ def direct_sum(self, modules, return_maps=False): The summands are ordered as given with ``self`` being the zeroth summand. - OUTPUT: - - - :class:`QuiverRep` or tuple + OUTPUT: :class:`QuiverRep` or tuple EXAMPLES:: @@ -2618,9 +2564,7 @@ def transpose(self): If `p^t` is the algebraic dual of `p` then define `\mbox{Tr} M = \mbox{coker} p^t`. - OUTPUT: - - - :class:`QuiverRep` + OUTPUT: :class:`QuiverRep` EXAMPLES:: @@ -2860,7 +2804,7 @@ def _left_edge_action(self, edge, element): - ``element`` -- :class:`QuiverRepElement`; an element of ``self`` - - ``edge`` -- An edge of the quiver (a tuple) or a list of edges in + - ``edge`` -- an edge of the quiver (a tuple) or a list of edges in the quiver. Such a list can be empty (in which case no action is performed) and can contain trivial paths (tuples of the form `(v, v)` where `v` is a vertex of the quiver) diff --git a/src/sage/repl/attach.py b/src/sage/repl/attach.py index 4efc94f5cac..89b6a789fc4 100644 --- a/src/sage/repl/attach.py +++ b/src/sage/repl/attach.py @@ -109,10 +109,10 @@ def load_attach_mode(load_debug=None, attach_debug=None): - ``load_debug`` -- boolean or ``None`` (default); if not ``None``, then set a new value for the debug mode for loading - files. + files - ``attach_debug`` -- boolean or ``None`` (default); same as - ``load_debug``, but for attaching files. + ``load_debug``, but for attaching files OUTPUT: @@ -151,15 +151,13 @@ def load_attach_path(path=None, replace=False): INPUT: - ``path`` -- string or list of strings (default: ``None``); - path(s) to append to or replace the current path. + path(s) to append to or replace the current path - ``replace`` -- boolean (default: ``False``); if ``path`` is not ``None``, whether to *replace* the search path instead of - *appending* to it. + *appending* to it - OUTPUT: - - ``None`` or a *reference* to the current search paths. + OUTPUT: none or a *reference* to the current search paths EXAMPLES: @@ -296,20 +294,20 @@ def attach(*files): INPUT: - - ``files`` -- a list of filenames (strings) to attach. + - ``files`` -- list of filenames (strings) to attach OUTPUT: Each file is read in and added to an internal list of watched files. The meaning of reading in a file depends on the file type: - - ``.py`` files are read in with no preparsing (so, e.g., ``2^3`` is 2 - bit-xor 3); + - ``.py`` files are read in with no preparsing (so, e.g., ``2^3`` is 2 + bit-xor 3); - - ``.sage`` files are preparsed, then the result is read in; + - ``.sage`` files are preparsed, then the result is read in; - ``.pyx`` files are *not* preparsed, but rather are compiled to a - module ``m`` and then ``from m import *`` is executed. + module ``m`` and then ``from m import *`` is executed. The contents of the file are then loaded, which means they are read into the running Sage session. For example, if ``foo.sage`` contains @@ -372,7 +370,7 @@ def attach(*files): def add_attached_file(filename): """ - Add to the list of attached files + Add to the list of attached files. This is a callback to be used from :func:`~sage.repl.load.load` after evaluating the attached @@ -405,9 +403,7 @@ def attached_files() -> list: Return a list of all files attached to the current session with :meth:`attach`. - OUTPUT: - - The filenames in a sorted list of strings. + OUTPUT: the filenames in a sorted list of strings EXAMPLES:: @@ -433,7 +429,7 @@ def detach(filename): INPUT: - - ``filename`` -- a string, a list of strings or a tuple of strings + - ``filename`` -- string, a list of strings or a tuple of strings or a :class:`Path`, a list of :class:`Path` or a tuple of :class:`Path` EXAMPLES:: diff --git a/src/sage/repl/configuration.py b/src/sage/repl/configuration.py index ad0870cca2e..a87ee896307 100644 --- a/src/sage/repl/configuration.py +++ b/src/sage/repl/configuration.py @@ -41,7 +41,7 @@ class SageIpythonConfiguration(): def _doctest_mode(self): """ - Whether we are in doctest mode + Whether we are in doctest mode. This returns ``True`` during doctests. @@ -56,7 +56,7 @@ def _doctest_mode(self): def _allow_ansi(self): """ - Whether to allow ANSI escape sequences + Whether to allow ANSI escape sequences. This returns ``False`` during doctests to avoid ANSI escape sequences. @@ -71,7 +71,7 @@ def _allow_ansi(self): def colors(self): """ - Return the IPython color palette + Return the IPython color palette. This returns ``'NoColor'`` during doctests to avoid ANSI escape sequences. @@ -89,7 +89,7 @@ def colors(self): def simple_prompt(self): """ - Return whether to use the simple prompt + Return whether to use the simple prompt. This returns ``True`` during doctests to avoid ANSI escape sequences. @@ -103,7 +103,7 @@ def simple_prompt(self): def term_title(self): """ - Return whether to set the terminal title + Return whether to set the terminal title. This returns false during doctests to avoid ANSI escape sequences. @@ -117,7 +117,7 @@ def term_title(self): def default(self): """ - Return a new default configuration object + Return a new default configuration object. EXAMPLES:: @@ -166,7 +166,7 @@ def default(self): def copy(self): """ - Return a copy of the current configuration + Return a copy of the current configuration. EXAMPLES:: diff --git a/src/sage/repl/display/fancy_repr.py b/src/sage/repl/display/fancy_repr.py index c2e88af33f0..bb1f41ded56 100644 --- a/src/sage/repl/display/fancy_repr.py +++ b/src/sage/repl/display/fancy_repr.py @@ -35,9 +35,7 @@ def __repr__(self): """ Return string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -53,15 +51,15 @@ def __call__(self, obj, p, cycle): INPUT: - - ``obj`` -- anything. Object to format. + - ``obj`` -- anything; object to format - - ``p`` -- PrettyPrinter instance. + - ``p`` -- PrettyPrinter instance - - ``cycle`` -- boolean. Whether there is a cycle. + - ``cycle`` -- boolean; whether there is a cycle OUTPUT: - Boolean. Whether the representer is applicable to ``obj``. If + boolean; whether the representer is applicable to ``obj``. If ``True``, the string representation is appended to ``p``. EXAMPLES:: @@ -79,11 +77,9 @@ def format_string(self, obj): INPUT: - - ``obj`` -- anything. Object to format. - - OUTPUT: + - ``obj`` -- anything; object to format - String. + OUTPUT: string EXAMPLES:: @@ -106,7 +102,7 @@ class SomeIPythonRepr(ObjectReprABC): def __init__(self): """ - Some selected representers from IPython + Some selected representers from IPython. EXAMPLES:: @@ -129,15 +125,15 @@ def __call__(self, obj, p, cycle): INPUT: - - ``obj`` -- anything. Object to format. + - ``obj`` -- anything; object to format - - ``p`` -- PrettyPrinter instance. + - ``p`` -- PrettyPrinter instance - - ``cycle`` -- boolean. Whether there is a cycle. + - ``cycle`` -- boolean; whether there is a cycle OUTPUT: - Boolean. Whether the representer is applicable to ``obj``. If + boolean; whether the representer is applicable to ``obj``. If ``True``, the string representation is appended to ``p``. EXAMPLES:: @@ -157,7 +153,7 @@ def __call__(self, obj, p, cycle): class LargeMatrixHelpRepr(ObjectReprABC): """ - Representation including help for large Sage matrices + Representation including help for large Sage matrices. .. automethod:: __call__ """ @@ -168,15 +164,15 @@ def __call__(self, obj, p, cycle): INPUT: - - ``obj`` -- anything. Object to format. + - ``obj`` -- anything; object to format - - ``p`` -- PrettyPrinter instance. + - ``p`` -- PrettyPrinter instance - - ``cycle`` -- boolean. Whether there is a cycle. + - ``cycle`` -- boolean; whether there is a cycle OUTPUT: - Boolean. Whether the representer is applicable to ``obj``. If + boolean; whether the representer is applicable to ``obj``. If ``True``, the string representation is appended to ``p``. EXAMPLES:: @@ -215,7 +211,7 @@ def __call__(self, obj, p, cycle): class PlainPythonRepr(ObjectReprABC): """ - The ordinary Python representation + The ordinary Python representation. .. automethod:: __call__ """ @@ -226,15 +222,15 @@ def __call__(self, obj, p, cycle): INPUT: - - ``obj`` -- anything. Object to format. + - ``obj`` -- anything; object to format - - ``p`` -- PrettyPrinter instance. + - ``p`` -- PrettyPrinter instance - - ``cycle`` -- boolean. Whether there is a cycle. + - ``cycle`` -- boolean; whether there is a cycle OUTPUT: - Boolean. Whether the representer is applicable to ``obj``. If + boolean; whether the representer is applicable to ``obj``. If ``True``, the string representation is appended to ``p``. EXAMPLES:: @@ -287,7 +283,7 @@ def __call__(self, obj, p, cycle): class TallListRepr(ObjectReprABC): """ - Special representation for lists with tall entries (e.g. matrices) + Special representation for lists with tall entries (e.g. matrices). .. automethod:: __call__ """ @@ -298,15 +294,15 @@ def __call__(self, obj, p, cycle): INPUT: - - ``obj`` -- anything. Object to format. + - ``obj`` -- anything; object to format - - ``p`` -- PrettyPrinter instance. + - ``p`` -- PrettyPrinter instance - - ``cycle`` -- boolean. Whether there is a cycle. + - ``cycle`` -- boolean; whether there is a cycle OUTPUT: - Boolean. Whether the representer is applicable to ``obj``. If + boolean; whether the representer is applicable to ``obj``. If ``True``, the string representation is appended to ``p``. EXAMPLES:: diff --git a/src/sage/repl/display/formatter.py b/src/sage/repl/display/formatter.py index b76457669cb..bae9705d57c 100644 --- a/src/sage/repl/display/formatter.py +++ b/src/sage/repl/display/formatter.py @@ -84,11 +84,9 @@ class SageDisplayFormatter(DisplayFormatter): def __init__(self, *args, **kwds): """ - This is where the Sage rich objects are translated to IPython + This is where the Sage rich objects are translated to IPython. - INPUT/OUTPUT: - - See the IPython documentation. + INPUT/OUTPUT: see the IPython documentation EXAMPLES: @@ -113,11 +111,9 @@ def __init__(self, *args, **kwds): def format(self, obj, include=None, exclude=None): r""" - Use the Sage rich output instead of IPython - - INPUT/OUTPUT: + Use the Sage rich output instead of IPython. - See the IPython documentation. + INPUT/OUTPUT: see the IPython documentation EXAMPLES:: @@ -272,9 +268,7 @@ def __init__(self, *args, **kwds): rich output system that is more flexible and supports different backends. - INPUT/OUTPUT: - - See the IPython documentation. + INPUT/OUTPUT: see the IPython documentation EXAMPLES:: @@ -294,11 +288,9 @@ def __call__(self, obj): INPUT: - - ``obj`` -- anything. - - OUTPUT: + - ``obj`` -- anything - String. The plain text representation. + OUTPUT: string; the plain text representation EXAMPLES:: diff --git a/src/sage/repl/display/jsmol_iframe.py b/src/sage/repl/display/jsmol_iframe.py index b50822b875b..abe0e052c08 100644 --- a/src/sage/repl/display/jsmol_iframe.py +++ b/src/sage/repl/display/jsmol_iframe.py @@ -136,9 +136,7 @@ def script(self): This method extracts the Jmol script from the Jmol spt file (a zip archive) and inlines meshes. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -200,11 +198,9 @@ def js_script(self): def _repr_(self): """ - Return as string representation - - OUTPUT: + Return as string representation. - String. + OUTPUT: string EXAMPLES:: @@ -217,7 +213,7 @@ def _repr_(self): def inner_html(self): """ - Return a HTML document containing a JSmol applet + Return a HTML document containing a JSmol applet. EXAMPLES:: @@ -243,11 +239,9 @@ def inner_html(self): def iframe(self): """ - Return HTML iframe + Return HTML iframe. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -266,11 +260,9 @@ def iframe(self): def outer_html(self): """ - Return a HTML document containing an iframe with a JSmol applet - - OUTPUT: + Return a HTML document containing an iframe with a JSmol applet. - String + OUTPUT: string EXAMPLES:: diff --git a/src/sage/repl/display/pretty_print.py b/src/sage/repl/display/pretty_print.py index 99bbe5013d0..0e4c1aec150 100644 --- a/src/sage/repl/display/pretty_print.py +++ b/src/sage/repl/display/pretty_print.py @@ -50,7 +50,7 @@ def toplevel(self): OUTPUT: - Boolean. Whether we are currently pretty-printing an object at + boolean; whether we are currently pretty-printing an object at the outermost level (``True``), or whether the object is inside a container (``False``). @@ -67,7 +67,7 @@ def toplevel(self): def __init__(self, output, max_width, newline, max_seq_length=None): """ - Pretty print Sage objects for the commandline + Pretty print Sage objects for the commandline. INPUT: @@ -111,17 +111,15 @@ def __init__(self, output, max_width, newline, max_seq_length=None): def pretty(self, obj): r""" - Pretty print ``obj`` + Pretty print ``obj``. This is the only method that outside code should invoke. INPUT: - - ``obj`` -- anything. + - ``obj`` -- anything - OUTPUT: - - String representation for object. + OUTPUT: string representation for object EXAMPLES:: diff --git a/src/sage/repl/display/util.py b/src/sage/repl/display/util.py index e222351a74e..450d1e0db62 100644 --- a/src/sage/repl/display/util.py +++ b/src/sage/repl/display/util.py @@ -18,7 +18,7 @@ class TallListFormatter(): """ - Special representation for lists with tall entries (e.g. matrices) + Special representation for lists with tall entries (e.g. matrices). .. automethod:: __call__ """ @@ -28,7 +28,7 @@ class TallListFormatter(): def _tall_list_row(self, running_lines, last_row=False): """ - Helper for :meth:`_check_tall_list_and_format` + Helper for :meth:`_check_tall_list_and_format`. This helper function processes and outputs the contents of the running_lines array. @@ -64,7 +64,7 @@ def try_format(self, the_list): INPUT: - - ``the_list`` -- The list (or a tuple). + - ``the_list`` -- the list (or a tuple) OUTPUT: @@ -144,11 +144,9 @@ def __call__(self, the_list): INPUT: - - ``the_list`` -- list or tuple. + - ``the_list`` -- list or tuple - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: diff --git a/src/sage/repl/image.py b/src/sage/repl/image.py index 2170d216caa..4f40e7c0715 100644 --- a/src/sage/repl/image.py +++ b/src/sage/repl/image.py @@ -43,7 +43,7 @@ class Image(SageObject): def __init__(self, mode, size, color='white'): """ - Creates a new image with the given mode and size. + Create a new image with the given mode and size. INPUT: @@ -76,7 +76,7 @@ def __init__(self, mode, size, color='white'): * ``'F'`` (32-bit floating point pixels) - - ``size`` -- 2-tuple, containing (width, height) in pixels. + - ``size`` -- 2-tuple, containing (width, height) in pixels - ``color`` -- string, numeric or tuple of numeric. What colour to use for the image. Default is black. If given, this should be a @@ -85,9 +85,7 @@ def __init__(self, mode, size, color='white'): ImageColor module. If the colour is None, the image is not initialised. - OUTPUT: - - A new :class:`Image` object. + OUTPUT: a new :class:`Image` object EXAMPLES:: @@ -106,11 +104,9 @@ def __init__(self, mode, size, color='white'): @property def pil(self): """ - Access the wrapped PIL(low) Image - - OUTPUT: + Access the wrapped PIL(low) Image. - The underlying ``PIL.Image.Image object``. + OUTPUT: the underlying ``PIL.Image.Image object`` EXAMPLES:: @@ -123,7 +119,7 @@ def pil(self): def pixels(self): """ - Return the pixel map + Return the pixel map. OUTPUT: @@ -143,9 +139,7 @@ def _repr_(self): """ Return string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -175,11 +169,9 @@ def _repr_(self): def mode(self): """ - Return the color mode + Return the color mode. - OUTPUT: - - String. As given when constructing the image. + OUTPUT: string; as given when constructing the image EXAMPLES:: @@ -192,11 +184,9 @@ def mode(self): def width(self): """ - Return the horizontal dimension in pixels - - OUTPUT: + Return the horizontal dimension in pixels. - Integer. + OUTPUT: integer EXAMPLES:: @@ -211,11 +201,9 @@ def width(self): def height(self): """ - Return the vertical dimension in pixels - - OUTPUT: + Return the vertical dimension in pixels. - Integer. + OUTPUT: integer EXAMPLES:: @@ -230,12 +218,12 @@ def height(self): def save(self, filename): r""" - Save the bitmap image + Save the bitmap image. INPUT: - - ``filename`` -- string. The filename to save as. The given - extension automatically determines the image file type. + - ``filename`` -- string; the filename to save as. The given + extension automatically determines the image file type EXAMPLES:: @@ -276,7 +264,7 @@ def show(self): def _rich_repr_(self, display_manager, **kwds): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. diff --git a/src/sage/repl/inputhook.py b/src/sage/repl/inputhook.py index 99fb4a0c871..ad87af73ea1 100644 --- a/src/sage/repl/inputhook.py +++ b/src/sage/repl/inputhook.py @@ -48,7 +48,7 @@ def sage_inputhook(context): def install(): """ - Install the Sage input hook + Install the Sage input hook. EXAMPLES: @@ -75,7 +75,7 @@ def install(): def uninstall(): """ - Uninstall the Sage input hook + Uninstall the Sage input hook. EXAMPLES:: diff --git a/src/sage/repl/interface_magic.py b/src/sage/repl/interface_magic.py index b60355f5cae..a426dfdda07 100644 --- a/src/sage/repl/interface_magic.py +++ b/src/sage/repl/interface_magic.py @@ -85,7 +85,7 @@ class InterfaceMagic(): @classmethod def all_iter(cls): """ - Iterate over the available interfaces + Iterate over the available interfaces. EXAMPLES:: @@ -104,7 +104,7 @@ def all_iter(cls): @classmethod def register_all(cls, shell=None): """ - Register all available interfaces + Register all available interfaces. EXAMPLES:: @@ -144,18 +144,15 @@ def register_all(cls, shell=None): @classmethod def find(cls, name): """ - Find a particular magic by name + Find a particular magic by name. This method is for doctesting purposes only. INPUT: - - ``name`` -- string. The name of the interface magic to - search for. + - ``name`` -- string; the name of the interface magic to search for - OUTPUT: - - The corresponding :class:`InterfaceMagic` instance. + OUTPUT: the corresponding :class:`InterfaceMagic` instance EXAMPLES:: @@ -169,17 +166,17 @@ def find(cls, name): def __init__(self, name, interface): """ - Interface Magic + Interface Magic. This class is a wrapper around interface objects to provide them with magics. INPUT: - - ``name`` -- string. The interface name + - ``name`` -- string; the interface name - - ``interface`` -- :class:`sage.interfaces.expect.Expect`. The - interface to wrap. + - ``interface`` -- :class:`sage.interfaces.expect.Expect`; the + interface to wrap EXAMPLES:: @@ -192,11 +189,9 @@ def __init__(self, name, interface): def line_magic_factory(self): """ - Factory for line magic - - OUTPUT: + Factory for line magic. - A function suitable to be used as line magic. + OUTPUT: a function suitable to be used as line magic EXAMPLES:: @@ -237,11 +232,9 @@ def line_magic(line): def cell_magic_factory(self): r""" - Factory for cell magic + Factory for cell magic. - OUTPUT: - - A function suitable to be used as cell magic. + OUTPUT: a function suitable to be used as cell magic EXAMPLES:: @@ -278,23 +271,21 @@ def cell_magic_factory(self): """ def cell_magic(line, cell): """ - Evaluate cell magic + Evaluate cell magic. - Docstring is overwritten in the instance + Docstring is overwritten in the instance. INPUT: - - ``line`` -- string. The option part of the cell magic. - - - ``cell`` -- string. The lines of the cell magic. + - ``line`` -- string; the option part of the cell magic - OUTPUT: + - ``cell`` -- string; the lines of the cell magic - Prints the interface output. + OUTPUT: prints the interface output RAISES: - ``SyntaxError`` if a line is specified; Interfaces have no + :exc:`SyntaxError` if a line is specified; Interfaces have no options. """ if line: diff --git a/src/sage/repl/interpreter.py b/src/sage/repl/interpreter.py index 84af28f8cf7..73b619e8101 100644 --- a/src/sage/repl/interpreter.py +++ b/src/sage/repl/interpreter.py @@ -177,8 +177,7 @@ def preparser(on=True): """ Turn on or off the Sage preparser. - :keyword on: if True turn on preparsing; if False, turn it off. - :type on: bool + - ``on`` -- boolean; whether to turn on preparsing EXAMPLES:: @@ -247,7 +246,7 @@ def system_raw(self, cmd): class SageNotebookInteractiveShell(SageShellOverride, InteractiveShell): """ - IPython Shell for the Sage IPython Notebook + IPython Shell for the Sage IPython Notebook. The doctests are not tested since they would change the current rich output backend away from the doctest rich output backend. @@ -261,7 +260,7 @@ class SageNotebookInteractiveShell(SageShellOverride, InteractiveShell): def init_display_formatter(self): """ - Switch to the Sage IPython notebook rich output backend + Switch to the Sage IPython notebook rich output backend. EXAMPLES:: @@ -275,7 +274,7 @@ def init_display_formatter(self): class SageTerminalInteractiveShell(SageShellOverride, TerminalInteractiveShell): """ - IPython Shell for the Sage IPython Commandline Interface + IPython Shell for the Sage IPython Commandline Interface. The doctests are not tested since they would change the current rich output backend away from the doctest rich output backend. @@ -289,7 +288,7 @@ class SageTerminalInteractiveShell(SageShellOverride, TerminalInteractiveShell): def init_display_formatter(self): """ - Switch to the Sage IPython commandline rich output backend + Switch to the Sage IPython commandline rich output backend. EXAMPLES:: @@ -315,7 +314,7 @@ def prompt_for_code(self): class SageTestShell(SageShellOverride, TerminalInteractiveShell): """ - Test Shell + Test Shell. Care must be taken in these doctests to quit the test shell in order to switch back the rich output display backend to the @@ -331,7 +330,7 @@ class SageTestShell(SageShellOverride, TerminalInteractiveShell): def init_display_formatter(self): """ - Switch to the Sage IPython commandline rich output backend + Switch to the Sage IPython commandline rich output backend. EXAMPLES:: @@ -395,13 +394,12 @@ def _restart(self): def run_cell(self, *args, **kwds): """ - Run IPython cell + Run IPython cell. Starting with IPython-3.0, this returns an success/failure information. Since it is more convenient for doctests, we ignore it. - EXAMPLES:: sage: from sage.repl.interpreter import get_test_shell @@ -464,7 +462,6 @@ def SagePreparseTransformer(lines): So when debugging the preparser, print outs may be duplicated. If using IPython >= 7.17, try: ``sage.repl.interpreter.SagePreparseTransformer.has_side_effects = True`` - """ if _do_preparse: # IPython ensures the input lines end with a newline, and it expects @@ -556,8 +553,7 @@ def preparse_imports_from_sage(self, line): ``maxima(object)`` if :attr:`shell.interface` is ``maxima``. - :param line: the line to transform - :type line: string + - ``line`` -- string; the line to transform EXAMPLES:: @@ -610,10 +606,9 @@ def transform(self, line, continue_prompt): Evaluates *line* in :attr:`shell.interface` and returns a string representing the result of that evaluation. - :param line: the line to be transformed *and evaluated* - :type line: string - :param continue_prompt: is this line a continuation in a sequence of multiline input? - :type continue_prompt: bool + - ``line`` -- string; the line to be transformed *and evaluated* + - ``continue_prompt`` -- boolean; whether this line is a continuation in a + sequence of multiline input EXAMPLES:: @@ -668,14 +663,14 @@ def transform(self, line, continue_prompt): def interface_shell_embed(interface): """ - Returns an IPython shell which uses a Sage interface on the + Return an IPython shell which uses a Sage interface on the backend to perform the evaluations. It uses :class:`InterfaceShellTransformer` to transform the input into the appropriate ``interface.eval(...)`` input. INPUT: - - ``interface`` -- A Sage ``PExpect`` interface instance. + - ``interface`` -- a Sage ``PExpect`` interface instance EXAMPLES:: @@ -709,9 +704,7 @@ def get_test_shell(): Return a IPython shell that can be used in testing the functions in this module. - OUTPUT: - - An IPython shell + OUTPUT: an IPython shell EXAMPLES:: @@ -794,7 +787,7 @@ def load_config_file(self, *args, **kwds): r""" Merges a config file with the default sage config. - .. note:: + .. NOTE:: This code is based on :meth:`Application.update_config`. @@ -821,7 +814,7 @@ def init_shell(self): r""" Initialize the :class:`SageInteractiveShell` instance. - .. note:: + .. NOTE:: This code is based on :meth:`TerminalIPythonApp.init_shell`. diff --git a/src/sage/repl/ipython_extension.py b/src/sage/repl/ipython_extension.py index a7fccf9aa99..b218330d7af 100644 --- a/src/sage/repl/ipython_extension.py +++ b/src/sage/repl/ipython_extension.py @@ -77,11 +77,11 @@ class SageMagics(Magics): @line_magic def crun(self, s): r""" - Profile C function calls + Profile C function calls. INPUT: - - ``s`` -- string. Sage command to profile. + - ``s`` -- string; Sage command to profile EXAMPLES:: @@ -104,7 +104,7 @@ def runfile(self, s): This is designed to be used from the command line as ``%runfile /path/to/file``. - - ``s`` -- string. The file to be loaded. + - ``s`` -- string; the file to be loaded EXAMPLES:: @@ -137,7 +137,7 @@ def attach(self, s): sage: from sage.repl.interpreter import get_test_shell sage: shell = get_test_shell() sage: from tempfile import NamedTemporaryFile as NTF - sage: with NTF(mode="w+t", suffix=".py", delete=False) as f: + sage: with NTF(mode='w+t', suffix='.py', delete=False) as f: ....: _ = f.write('a = 2\n') sage: shell.run_cell('%attach ' + f.name) sage: shell.run_cell('a') @@ -169,7 +169,7 @@ def iload(self, args): - ``args`` -- string. The file to be interactively loaded - .. note:: + .. NOTE:: Currently, this cannot be completely doctested as it relies on :func:`raw_input`. @@ -334,20 +334,18 @@ def display(self, args): @cell_magic def cython(self, line, cell): """ - Cython cell magic + Cython cell magic. This is syntactic sugar on the :func:`~sage.misc.cython.cython_compile` function. INPUT: - - ``line`` -- ignored. + - ``line`` -- ignored - - ``cell`` -- string. The Cython source code to process. + - ``cell`` -- string; the Cython source code to process - OUTPUT: - - None. The Cython code is compiled and loaded. + OUTPUT: none; the Cython code is compiled and loaded EXAMPLES:: @@ -375,13 +373,11 @@ def fortran(self, line, cell): INPUT: - - ``line`` -- ignored. - - - ``cell`` -- string. The Cython source code to process. + - ``line`` -- ignored - OUTPUT: + - ``cell`` -- string; the Cython source code to process - None. The Fortran code is compiled and loaded. + OUTPUT: none; the Fortran code is compiled and loaded EXAMPLES:: diff --git a/src/sage/repl/ipython_kernel/install.py b/src/sage/repl/ipython_kernel/install.py index e476efe22b9..3a2efb4ab64 100644 --- a/src/sage/repl/ipython_kernel/install.py +++ b/src/sage/repl/ipython_kernel/install.py @@ -30,7 +30,7 @@ class SageKernelSpec(): def __init__(self, prefix=None): """ - Utility to manage SageMath kernels and extensions + Utility to manage SageMath kernels and extensions. INPUT: @@ -57,7 +57,7 @@ def __init__(self, prefix=None): def _mkdirs(self): """ - Create necessary parent directories + Create necessary parent directories. EXAMPLES:: @@ -79,9 +79,9 @@ def mkdir_p(path): @classmethod def identifier(cls): """ - Internal identifier for the SageMath kernel + Internal identifier for the SageMath kernel. - OUTPUT: the string ``"sagemath"``. + OUTPUT: the string ``'sagemath'`` EXAMPLES:: @@ -93,7 +93,7 @@ def identifier(cls): def symlink(self, src, dst): """ - Symlink ``src`` to ``dst`` + Symlink ``src`` to ``dst``. This is not an atomic operation. @@ -141,9 +141,7 @@ def _kernel_cmd(self): """ Helper to construct the SageMath kernel command. - OUTPUT: - - List of strings. The command to start a new SageMath kernel. + OUTPUT: list of strings; the command to start a new SageMath kernel EXAMPLES:: @@ -166,11 +164,9 @@ def _kernel_cmd(self): def kernel_spec(self): """ - Return the kernel spec as Python dictionary - - OUTPUT: + Return the kernel spec as Python dictionary. - A dictionary. See the Jupyter documentation for details. + OUTPUT: a dictionary; see the Jupyter documentation for details EXAMPLES:: @@ -187,14 +183,13 @@ def kernel_spec(self): def _install_spec(self): """ - Install the SageMath Jupyter kernel + Install the SageMath Jupyter kernel. EXAMPLES:: sage: from sage.repl.ipython_kernel.install import SageKernelSpec sage: spec = SageKernelSpec(prefix=tmp_dir()) sage: spec._install_spec() - """ jsonfile = os.path.join(self.kernel_dir, "kernel.json") import json @@ -203,7 +198,7 @@ def _install_spec(self): def _symlink_resources(self): """ - Symlink miscellaneous resources + Symlink miscellaneous resources. This method symlinks additional resources (like the SageMath documentation) into the SageMath kernel directory. This is @@ -215,7 +210,6 @@ def _symlink_resources(self): sage: spec = SageKernelSpec(prefix=tmp_dir()) sage: spec._install_spec() sage: spec._symlink_resources() - """ path = os.path.join(SAGE_EXTCODE, 'notebook-ipython') for filename in os.listdir(path): @@ -231,7 +225,7 @@ def _symlink_resources(self): @classmethod def update(cls, *args, **kwds): """ - Configure the Jupyter notebook for the SageMath kernel + Configure the Jupyter notebook for the SageMath kernel. This method does everything necessary to use the SageMath kernel, you should never need to call any of the other methods @@ -241,7 +235,6 @@ def update(cls, *args, **kwds): sage: from sage.repl.ipython_kernel.install import SageKernelSpec sage: SageKernelSpec.update(prefix=tmp_dir()) - """ instance = cls(*args, **kwds) instance.use_local_threejs() @@ -287,12 +280,10 @@ def have_prerequisites(debug=True): INPUT: - - ``debug`` -- boolean (default: ``True``). Whether to print debug - information in case that prerequisites are missing. - - OUTPUT: + - ``debug`` -- boolean (default: ``True``); whether to print debug + information in case that prerequisites are missing - Boolean. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/repl/ipython_kernel/interact.py b/src/sage/repl/ipython_kernel/interact.py index a8167dcabd8..86e53412bc2 100644 --- a/src/sage/repl/ipython_kernel/interact.py +++ b/src/sage/repl/ipython_kernel/interact.py @@ -57,7 +57,7 @@ class sage_interactive(interactive): EXAMPLES:: sage: from sage.repl.ipython_kernel.interact import sage_interactive - sage: def myfunc(x=10, y="hello", z=None): pass + sage: def myfunc(x=10, y='hello', z=None): pass sage: sage_interactive(myfunc, x=(0,100), z=["one", "two", "three"]) ...Interactive function with 3 widgets x: IntSlider(value=10, description='x') @@ -66,7 +66,7 @@ class sage_interactive(interactive): """ def __init__(self, *args, **kwds): """ - See :class:`ipywidgets.widgets.interaction.interactive` + See :class:`ipywidgets.widgets.interaction.interactive`. TESTS:: diff --git a/src/sage/repl/ipython_kernel/kernel.py b/src/sage/repl/ipython_kernel/kernel.py index a9931f8b9cf..dc414ea2aab 100644 --- a/src/sage/repl/ipython_kernel/kernel.py +++ b/src/sage/repl/ipython_kernel/kernel.py @@ -48,11 +48,11 @@ class SageKernel(IPythonKernel): def __init__(self, **kwds): """ - The Sage Jupyter Kernel + The Sage Jupyter Kernel. INPUT: - See the Jupyter documentation + See the Jupyter documentation. EXAMPLES:: @@ -66,14 +66,12 @@ def __init__(self, **kwds): @property def banner(self): r""" - The Sage Banner + The Sage Banner. The value of this property is displayed in the Jupyter notebook. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -88,11 +86,9 @@ def banner(self): @property def help_links(self): r""" - Help in the Jupyter Notebook + Help in the Jupyter Notebook. - OUTPUT: - - See the Jupyter documentation. + OUTPUT: see the Jupyter documentation EXAMPLES:: diff --git a/src/sage/repl/ipython_kernel/widgets.py b/src/sage/repl/ipython_kernel/widgets.py index f3ac6a35ccb..3fa000f70df 100644 --- a/src/sage/repl/ipython_kernel/widgets.py +++ b/src/sage/repl/ipython_kernel/widgets.py @@ -92,7 +92,7 @@ class TransformWidget(): INPUT: - ``transform`` -- a one-argument function which transforms the - value of the widget for use by an interactive function. + value of the widget for use by an interactive function - other arguments are passed to the base class @@ -133,7 +133,7 @@ def get_value(self): sage: from ipywidgets import ColorPicker sage: from sage.repl.ipython_kernel.widgets import TransformWidget sage: class TransformColorPicker(TransformWidget, ColorPicker): pass - sage: TransformColorPicker(value="red").get_value() + sage: TransformColorPicker(value='red').get_value() 'red' """ return self.value @@ -276,7 +276,7 @@ class TransformText(TransformWidget, Text): EXAMPLES:: sage: from sage.repl.ipython_kernel.widgets import TransformText - sage: w = TransformText(value="hello", transform=lambda x: x + x) + sage: w = TransformText(value='hello', transform=lambda x: x + x) sage: w TransformText(value='hello') sage: w.get_interact_value() @@ -293,7 +293,7 @@ class TransformTextarea(TransformWidget, Textarea): EXAMPLES:: sage: from sage.repl.ipython_kernel.widgets import TransformTextarea - sage: w = TransformTextarea(value="hello", transform=lambda x: x + x) + sage: w = TransformTextarea(value='hello', transform=lambda x: x + x) sage: w TransformTextarea(value='hello') sage: w.get_interact_value() @@ -310,7 +310,7 @@ class EvalText(EvalWidget, Text): EXAMPLES:: sage: from sage.repl.ipython_kernel.widgets import EvalText - sage: w = EvalText(value="pi", transform=lambda x: x^2) + sage: w = EvalText(value='pi', transform=lambda x: x^2) sage: w EvalText(value='pi') sage: w.get_interact_value() # needs sage.symbolic @@ -327,7 +327,7 @@ class EvalTextarea(EvalWidget, Textarea): EXAMPLES:: sage: from sage.repl.ipython_kernel.widgets import EvalTextarea - sage: w = EvalTextarea(value="pi", transform=lambda x: x^2) + sage: w = EvalTextarea(value='pi', transform=lambda x: x^2) sage: w EvalTextarea(value='pi') sage: w.get_interact_value() # needs sage.symbolic @@ -392,11 +392,11 @@ def __init__(self, nrows, ncols, make_widget, description=u"", transform=None): - ``nrows``, ``ncols`` -- number of rows and columns in the grid - ``make_widget`` -- a function of two arguments ``(i,j)`` - returning the widget to be placed at position ``(i,j)``. + returning the widget to be placed at position ``(i,j)`` - - ``description`` -- an optional label. + - ``description`` -- an optional label - - ``transform`` -- an optional transformation, see :class:`TransformWidget`. + - ``transform`` -- an optional transformation, see :class:`TransformWidget` EXAMPLES:: @@ -431,7 +431,7 @@ def __init__(self, nrows, ncols, make_widget, description=u"", transform=None): widgets = [] for i in range(nrows): w = make_widget(i, j) - w.observe(self._update, names="value") + w.observe(self._update, names='value') widgets.append(w) col.children = widgets self.cols.append(col) diff --git a/src/sage/repl/ipython_kernel/widgets_sagenb.py b/src/sage/repl/ipython_kernel/widgets_sagenb.py index 4d3b1dbdedc..aa146aa438a 100644 --- a/src/sage/repl/ipython_kernel/widgets_sagenb.py +++ b/src/sage/repl/ipython_kernel/widgets_sagenb.py @@ -56,7 +56,7 @@ def input_box(default=None, label=None, type=None, width=80, height=1): - ``default`` -- initial value - - ``label`` -- optional label + - ``label`` -- (optional) - ``type`` -- function of one variable or ``None``. if ``type`` is ``str``, the value of this widget for interactive functions is @@ -68,7 +68,7 @@ def input_box(default=None, label=None, type=None, width=80, height=1): - ``width`` -- width of the box - ``height`` -- if ``height > 1``, create a textarea instead of a - single-line textbox. + single-line textbox EXAMPLES:: @@ -171,16 +171,15 @@ def slider(vmin, vmax=None, step_size=None, default=None, label=None, display_va For a selection slider (select a value from a list of values): - - ``vmin`` -- a list of possible values for the slider + - ``vmin`` -- list of possible values for the slider For all sliders: - ``default`` -- initial value - - ``label`` -- optional label + - ``label`` -- (optional) - - ``display_value`` -- (boolean) if ``True``, display the current - value. + - ``display_value`` -- boolean; if ``True``, display the current value EXAMPLES:: @@ -361,10 +360,9 @@ def range_slider(*args, **kwds): - ``default`` -- initial value, given as a 2-tuple - - ``label`` -- optional label + - ``label`` -- (optional) - - ``display_value`` -- (boolean) if ``True``, display the current - value. + - ``display_value`` -- boolean; if ``True``, display the current value EXAMPLES:: @@ -417,9 +415,9 @@ def checkbox(default=True, label=None): INPUT: - - ``default`` -- (boolean) initial value + - ``default`` -- boolean; initial value - - ``label`` -- optional label + - ``label`` -- (optional) EXAMPLES:: @@ -444,14 +442,14 @@ def selector(values, label=None, default=None, nrows=None, ncols=None, width=Non INPUT: - - ``values`` -- a list of values to choose from (see examples below + - ``values`` -- list of values to choose from (see examples below for the accepted formats for this) - - ``label`` -- optional label + - ``label`` -- (optional) - ``default`` -- initial value - - ``buttons`` -- (boolean) if True, display buttons instead of a + - ``buttons`` -- boolean; if ``True``, display buttons instead of a dropdown box EXAMPLES:: @@ -515,7 +513,7 @@ def input_grid(nrows, ncols, default=None, label=None, to_value=None, width=4): - ``default`` -- initial value (given as a list of lists, a single constant value or a flat list) - - ``label`` -- optional label + - ``label`` -- (optional) - ``to_value`` -- function to be called to get the value for interactive functions @@ -525,7 +523,7 @@ def input_grid(nrows, ncols, default=None, label=None, to_value=None, width=4): EXAMPLES:: sage: from sage.repl.ipython_kernel.all_jupyter import input_grid - sage: input_grid(2, 2, default=42, label="answers") + sage: input_grid(2, 2, default=42, label='answers') Grid(value=[[42, 42], [42, 42]], children=(Label(value='answers'), VBox(children=(EvalText(value='42', layout=Layout(max_width='5em')), EvalText(value='42', layout=Layout(max_width='5em')))), VBox(children=(EvalText(value='42', layout=Layout(max_width='5em')), EvalText(value='42', layout=Layout(max_width='5em')))))) sage: w = input_grid(2, 2, default=[[cos(x), sin(x)], [-sin(x), cos(x)]], to_value=matrix); w Grid(value=[[cos(x), sin(x)], [-sin(x), cos(x)]], children=(Label(value=''), VBox(children=(EvalText(value='cos(x)', layout=Layout(max_width='5em')), EvalText(value='-sin(x)', layout=Layout(max_width='5em')))), VBox(children=(EvalText(value='sin(x)', layout=Layout(max_width='5em')), EvalText(value='cos(x)', layout=Layout(max_width='5em')))))) @@ -567,9 +565,9 @@ def color_selector(default=(0, 0, 1), label=None, widget=None, hide_box=False): - ``default`` -- initial value - - ``label`` -- optional label + - ``label`` -- (optional) - - ``hide_box`` -- (boolean) if True, do not show the textbox + - ``hide_box`` -- boolean; if ``True``, do not show the textbox EXAMPLES:: diff --git a/src/sage/repl/ipython_tests.py b/src/sage/repl/ipython_tests.py index 12f03c20d7e..1e26d47717c 100644 --- a/src/sage/repl/ipython_tests.py +++ b/src/sage/repl/ipython_tests.py @@ -11,15 +11,15 @@ sage: shell.run_cell(u'%pinfo dummy') Signature: dummy(argument, optional=None) Docstring: - Dummy Docstring Title + Dummy Docstring Title. Dummy docstring explanation. INPUT: - ... "argument" -- anything. Dummy argument. + ... "argument" -- anything; dummy argument - ... "optional" -- anything (optional). Dummy optional. + ... "optional" -- anything (optional); dummy optional EXAMPLES... @@ -35,7 +35,7 @@ sage: shell.run_cell(u'from sage.tests.stl_vector import stl_int_vector') sage: shell.run_cell(u'%pinfo stl_int_vector') ... - Example class wrapping an STL vector + Example class wrapping an STL vector. EXAMPLES... @@ -73,15 +73,15 @@ Source: def dummy(argument, optional=None): """ - Dummy Docstring Title + Dummy Docstring Title. Dummy docstring explanation. INPUT: - - ``argument`` -- anything. Dummy argument. + - ``argument`` -- anything; dummy argument - - ``optional`` -- anything (optional). Dummy optional. + - ``optional`` -- anything (optional); dummy optional EXAMPLES:: @@ -100,7 +100,7 @@ def dummy(argument, optional=None): ... cdef class stl_int_vector(SageObject): """ - Example class wrapping an STL vector + Example class wrapping an STL vector. EXAMPLES:: @@ -144,15 +144,15 @@ def __cinit__(self): def dummy(argument, optional=None): """ - Dummy Docstring Title + Dummy Docstring Title. Dummy docstring explanation. INPUT: - - ``argument`` -- anything. Dummy argument. + - ``argument`` -- anything; dummy argument - - ``optional`` -- anything (optional). Dummy optional. + - ``optional`` -- anything (optional); dummy optional EXAMPLES:: diff --git a/src/sage/repl/load.py b/src/sage/repl/load.py index c7c014d2f8b..a1a1451f1c2 100644 --- a/src/sage/repl/load.py +++ b/src/sage/repl/load.py @@ -29,11 +29,9 @@ def is_loadable_filename(filename): INPUT: - - ``filename`` -- a string or :class:`Path` object + - ``filename`` -- string or :class:`Path` object - OUTPUT: - - - a boolean + OUTPUT: boolean EXAMPLES:: @@ -91,13 +89,13 @@ def load(filename, globals, attach=False): INPUT: - - ``filename`` -- a string (denoting a filename or URL) or a :class:`Path` object + - ``filename`` -- string (denoting a filename or URL) or a :class:`Path` object - - ``globals`` -- a string:object dictionary; the context in which - to execute the file contents. + - ``globals`` -- string:object dictionary; the context in which + to execute the file contents - - ``attach`` -- a boolean (default: ``False``); whether to add the - file to the list of attached files. + - ``attach`` -- boolean (default: ``False``); whether to add the + file to the list of attached files Loading an executable Sage script from the command prompt will run whatever code is inside an @@ -143,10 +141,10 @@ def load(filename, globals, attach=False): sage: z -7 - If the file is not a Cython, Python, or Sage file, a :class:`ValueError` + If the file is not a Cython, Python, or Sage file, a :exc:`ValueError` is raised:: - sage: sage.repl.load.load(tmp_filename(ext=".foo"), globals()) + sage: sage.repl.load.load(tmp_filename(ext='.foo'), globals()) Traceback (most recent call last): ... ValueError: unknown file extension '.foo' for load or attach (supported extensions: .py, .pyx, .sage, .spyx, .f, .f90, .m) @@ -301,13 +299,13 @@ def load_wrap(filename, attach=False): INPUT: - - ``filename`` -- a string or :class:`Path` object; the argument + - ``filename`` -- string or :class:`Path` object; the argument to the load or attach command - - ``attach`` -- a boolean (default: ``False``); whether to attach + - ``attach`` -- boolean (default: ``False``); whether to attach ``filename``, instead of loading it - OUTPUT: a string + OUTPUT: string EXAMPLES:: diff --git a/src/sage/repl/preparse.py b/src/sage/repl/preparse.py index 9b5dde719ce..02a6a51edf5 100644 --- a/src/sage/repl/preparse.py +++ b/src/sage/repl/preparse.py @@ -254,7 +254,7 @@ def implicit_multiplication(level=None): INPUT: - - ``level`` -- a boolean or integer (default: 5); how aggressive to be in + - ``level`` -- boolean or integer (default: 5); how aggressive to be in placing \*'s - 0 -- Do nothing @@ -263,9 +263,7 @@ def implicit_multiplication(level=None): - 3 -- Spaces between alphanumeric - 10 -- Adjacent parentheses (may mangle call statements) - OUTPUT: - - The current ``level`` if no argument is given. + OUTPUT: the current ``level`` if no argument is given EXAMPLES:: @@ -398,7 +396,7 @@ def pop(self): """ Remove and return the frame that was most recently added to the stack. - Raise an IndexError if the stack is empty. + Raise an :exc:`IndexError` if the stack is empty. EXAMPLES:: @@ -491,11 +489,11 @@ def __init__(self, delim, raw=False, f_string=False, braces=0, parens=0, bracket - ``delim`` -- string; the quote character(s) used: ``'``, ``"``, ``'''``, or ``\"\"\"`` - ``raw`` -- boolean (default: ``False``); whether we are in a raw string - ``f_string`` -- boolean (default: ``False``); whether we are in an F-string - - ``braces`` -- integer (default: ``0``); in an F-string, + - ``braces`` -- integer (default: 0); in an F-string, how many unclosed ``{``'s have we encountered? - - ``parens`` -- integer (default: ``0``); in a replacement section of an F-string + - ``parens`` -- integer (default: 0); in a replacement section of an F-string (``braces > 0``), how many unclosed ``(``'s have we encountered? - - ``brackets`` -- integer (default: ``0``); in a replacement section of an F-string + - ``brackets`` -- integer (default: 0); in a replacement section of an F-string (``braces > 0``), how many unclosed ``[``'s have we encountered? - ``fmt_spec`` -- boolean (default: ``False``); in the format specifier portion of a replacement section? @@ -530,7 +528,7 @@ def strip_string_literals(code, state=None): INPUT: - - ``code`` -- a string; the input + - ``code`` -- string; the input - ``state`` -- a :class:`QuoteStack` (default: ``None``); state with which to continue processing, e.g., across multiple calls to this function @@ -876,17 +874,17 @@ def containing_block(code, idx, delimiters=['()', '[]', '{}'], require_delim=Tru INPUT: - - ``code`` -- a string + - ``code`` -- string - - ``idx`` -- an integer; a starting position + - ``idx`` -- integer; a starting position - - ``delimiters`` -- a list of strings (default: ['()', '[]', + - ``delimiters`` -- list of strings (default: ['()', '[]', '{}']); the delimiters to balance. A delimiter must be a single character and no character can at the same time be opening and closing delimiter. - - ``require_delim`` -- a boolean (default: ``True``); whether to raise - a ``SyntaxError`` if delimiters are present. If the delimiters are + - ``require_delim`` -- boolean (default: ``True``); whether to raise + a :exc:`SyntaxError` if delimiters are present. If the delimiters are unbalanced, an error will be raised in any case. OUTPUT: @@ -894,7 +892,7 @@ def containing_block(code, idx, delimiters=['()', '[]', '{}'], require_delim=Tru - a 2-tuple ``(a,b)`` of integers, such that ``code[a:b]`` is delimited by balanced delimiters, ``a<=idx`` tag + Return the HTML code surrounded by ```` tag. This is just a convenience method. diff --git a/src/sage/repl/rich_output/output_graphics.py b/src/sage/repl/rich_output/output_graphics.py index d8c29c553a7..dfef3a78696 100644 --- a/src/sage/repl/rich_output/output_graphics.py +++ b/src/sage/repl/rich_output/output_graphics.py @@ -26,7 +26,7 @@ class OutputImagePng(OutputBase): def __init__(self, png): """ - PNG Image + PNG Image. .. NOTE:: @@ -53,14 +53,12 @@ def __init__(self, png): @classmethod def example(cls): r""" - Construct a sample PNG output container + Construct a sample PNG output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputImagePng`. + OUTPUT: an instance of :class:`OutputImagePng` EXAMPLES:: @@ -79,7 +77,7 @@ class OutputImageGif(OutputBase): def __init__(self, gif): """ - GIF Image (possibly animated) + GIF Image (possibly animated). INPUT: @@ -101,14 +99,12 @@ def __init__(self, gif): @classmethod def example(cls): r""" - Construct a sample GIF output container + Construct a sample GIF output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputImageGif`. + OUTPUT: an instance of :class:`OutputImageGif` EXAMPLES:: @@ -124,13 +120,11 @@ def example(cls): def html_fragment(self): """ - Return a self-contained HTML fragment displaying the image + Return a self-contained HTML fragment displaying the image. This is a workaround for the Jupyter notebook which doesn't support GIF directly. - OUTPUT: - - String. HTML fragment for displaying the GIF image. + OUTPUT: string. HTML fragment for displaying the GIF image EXAMPLES:: @@ -146,7 +140,7 @@ class OutputImageJpg(OutputBase): def __init__(self, jpg): """ - JPEG Image + JPEG Image. INPUT: @@ -168,14 +162,12 @@ def __init__(self, jpg): @classmethod def example(cls): r""" - Construct a sample JPEG output container + Construct a sample JPEG output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputImageJpg`. + OUTPUT: an instance of :class:`OutputImageJpg` EXAMPLES:: @@ -194,7 +186,7 @@ class OutputImageSvg(OutputBase): def __init__(self, svg): """ - SVG Image + SVG Image. INPUT: @@ -216,14 +208,12 @@ def __init__(self, svg): @classmethod def example(cls): r""" - Construct a sample SVG output container + Construct a sample SVG output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputImageSvg`. + OUTPUT: an instance of :class:`OutputImageSvg` EXAMPLES:: @@ -242,7 +232,7 @@ class OutputImagePdf(OutputBase): def __init__(self, pdf): """ - PDF Image + PDF Image. INPUT: @@ -264,14 +254,12 @@ def __init__(self, pdf): @classmethod def example(cls): r""" - Construct a sample PDF output container + Construct a sample PDF output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputImagePdf`. + OUTPUT: an instance of :class:`OutputImagePdf` EXAMPLES:: @@ -290,7 +278,7 @@ class OutputImageDvi(OutputBase): def __init__(self, dvi): """ - DVI Image + DVI Image. INPUT: @@ -312,14 +300,12 @@ def __init__(self, dvi): @classmethod def example(cls): r""" - Construct a sample DVI output container + Construct a sample DVI output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputImageDvi`. + OUTPUT: an instance of :class:`OutputImageDvi` EXAMPLES:: diff --git a/src/sage/repl/rich_output/output_graphics3d.py b/src/sage/repl/rich_output/output_graphics3d.py index 3cf42fafb4a..5e3da996293 100644 --- a/src/sage/repl/rich_output/output_graphics3d.py +++ b/src/sage/repl/rich_output/output_graphics3d.py @@ -24,16 +24,16 @@ class OutputSceneJmol(OutputBase): def __init__(self, scene_zip, preview_png): """ - JMol Scene + JMol Scene. By our (Sage) convention, the actual scene is called ``SCENE`` inside the zip archive. INPUT: - - ``scene_zip`` -- string/bytes. The jmol scene (a zip archive). + - ``scene_zip`` -- string/bytes; the jmol scene (a zip archive) - - ``preview_png`` -- string/bytes. Preview as png file. + - ``preview_png`` -- string/bytes; preview as png file EXAMPLES:: @@ -53,9 +53,7 @@ def launch_script_filename(self): file. The launch script is often necessary to make jmol render the 3d scene. - OUTPUT: - - String. The file name of a suitable launch script. + OUTPUT: string; the file name of a suitable launch script EXAMPLES:: @@ -82,14 +80,12 @@ def launch_script_filename(self): @classmethod def example(cls): r""" - Construct a sample Jmol output container + Construct a sample Jmol output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputSceneJmol`. + OUTPUT: an instance of :class:`OutputSceneJmol` EXAMPLES:: @@ -116,11 +112,11 @@ class OutputSceneCanvas3d(OutputBase): def __init__(self, canvas3d): """ - Canvas3d Scene + Canvas3d Scene. INPUT: - - ``canvas3d`` -- string/bytes. The canvas3d data. + - ``canvas3d`` -- string/bytes; the canvas3d data EXAMPLES:: @@ -133,14 +129,12 @@ def __init__(self, canvas3d): @classmethod def example(cls): r""" - Construct a sample Canvas3D output container + Construct a sample Canvas3D output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputSceneCanvas3d`. + OUTPUT: an instance of :class:`OutputSceneCanvas3d` EXAMPLES:: @@ -161,11 +155,11 @@ class OutputSceneThreejs(OutputBase): def __init__(self, html): """ - Three.js Scene + Three.js Scene. INPUT: - - ``html`` -- string/bytes. The Three.js HTML data. + - ``html`` -- string/bytes; the Three.js HTML data EXAMPLES:: @@ -180,7 +174,7 @@ class OutputSceneWavefront(OutputBase): def __init__(self, obj, mtl): """ - Wavefront `*.obj` Scene + Wavefront `*.obj` Scene. The Wavefront format consists of two files, an ``.obj`` file defining the geometry data (mesh points, normal vectors, ...) @@ -188,11 +182,11 @@ def __init__(self, obj, mtl): INPUT: - - ``obj`` -- bytes. The Wavefront obj file format describing - the mesh shape. + - ``obj`` -- bytes; the Wavefront obj file format describing + the mesh shape - - ``mtl`` -- bytes. The Wavefront mtl file format describing - textures. + - ``mtl`` -- bytes; the Wavefront mtl file format describing + textures EXAMPLES:: @@ -214,11 +208,11 @@ def _check_no_directory(self, filename): INPUT: - - ``filename`` -- string. A filename. + - ``filename`` -- string; a filename OUTPUT: - This method returns nothing. A ``ValueError`` is raised if + This method returns nothing. A :exc:`ValueError` is raised if ``filename`` is not just a plain filename but contains a directory (relative or absolute). @@ -246,7 +240,7 @@ def _check_no_directory(self, filename): def mtllib(self): """ - Return the ``mtllib`` filename + Return the ``mtllib`` filename. The ``mtllib`` line in the Wavefront file format (``*.obj``) is the name of the separate texture file. @@ -272,7 +266,7 @@ def mtllib(self): def obj_filename(self): """ - Return the file name of the ``.obj`` file + Return the file name of the ``.obj`` file. This method saves the object and texture to separate files in a temporary directory and returns the object file name. This @@ -321,14 +315,12 @@ def obj_filename(self): @classmethod def example(cls): r""" - Construct a sample Canvas3D output container + Construct a sample Canvas3D output container. This static method is meant for doctests, so they can easily construct an example. - OUTPUT: - - An instance of :class:`OutputSceneCanvas3d`. + OUTPUT: an instance of :class:`OutputSceneCanvas3d` EXAMPLES:: diff --git a/src/sage/repl/rich_output/output_video.py b/src/sage/repl/rich_output/output_video.py index 5171ac058ae..e1c25a3fca5 100644 --- a/src/sage/repl/rich_output/output_video.py +++ b/src/sage/repl/rich_output/output_video.py @@ -22,14 +22,13 @@ class OutputVideoBase(OutputBase): def __init__(self, video, loop=True): """ - Abstract base class for rich video output + Abstract base class for rich video output. INPUT: - - ``video`` -- - :class:`~sage.repl.rich_output.buffer.OutputBuffer`. - The video data. - - ``loop`` -- boolean. Whether to repeat the video in an endless loop. + - ``video`` -- :class:`~sage.repl.rich_output.buffer.OutputBuffer`; + the video data + - ``loop`` -- boolean; whether to repeat the video in an endless loop EXAMPLES:: @@ -44,16 +43,14 @@ def __init__(self, video, loop=True): @classmethod def example(cls): r""" - Construct a sample video output container + Construct a sample video output container. This static method is meant for doctests, so they can easily construct an example. The method is implemented in the abstract :class:`OutputVideoBase` class, but should get invoked on a concrete subclass for which an actual example can exist. - OUTPUT: - - An instance of the class on which this method is called. + OUTPUT: an instance of the class on which this method is called EXAMPLES:: @@ -73,14 +70,14 @@ def example(cls): def html_fragment(self, url, link_attrs=''): r""" - Construct a HTML fragment for embedding this video + Construct a HTML fragment for embedding this video. INPUT: - - ``url`` -- string. The URL where the data of this video can be found. + - ``url`` -- string; the URL where the data of this video can be found - - ``link_attrs`` -- string. Can be used to style the fallback link - which is presented to the user if the video is not supported. + - ``link_attrs`` -- string; can be used to style the fallback link + which is presented to the user if the video is not supported EXAMPLES:: @@ -114,7 +111,7 @@ def html_fragment(self, url, link_attrs=''): class OutputVideoOgg(OutputVideoBase): """ - Ogg video, Ogg Theora in particular + Ogg video, Ogg Theora in particular. EXAMPLES:: @@ -129,7 +126,7 @@ class OutputVideoOgg(OutputVideoBase): class OutputVideoWebM(OutputVideoBase): """ - WebM video + WebM video. The video can be encoded using VP8, VP9 or an even more recent codec. @@ -146,7 +143,7 @@ class OutputVideoWebM(OutputVideoBase): class OutputVideoMp4(OutputVideoBase): """ - MPEG 4 video + MPEG 4 video. EXAMPLES:: @@ -161,7 +158,7 @@ class OutputVideoMp4(OutputVideoBase): class OutputVideoFlash(OutputVideoBase): """ - Flash video + Flash video. EXAMPLES:: @@ -176,7 +173,7 @@ class OutputVideoFlash(OutputVideoBase): class OutputVideoMatroska(OutputVideoBase): """ - Matroska Video + Matroska Video. EXAMPLES:: @@ -191,7 +188,7 @@ class OutputVideoMatroska(OutputVideoBase): class OutputVideoAvi(OutputVideoBase): """ - AVI video + AVI video. EXAMPLES:: @@ -206,7 +203,7 @@ class OutputVideoAvi(OutputVideoBase): class OutputVideoWmv(OutputVideoBase): """ - Windows Media Video + Windows Media Video. EXAMPLES:: @@ -221,7 +218,7 @@ class OutputVideoWmv(OutputVideoBase): class OutputVideoQuicktime(OutputVideoBase): """ - Quicktime video + Quicktime video. EXAMPLES:: diff --git a/src/sage/repl/rich_output/preferences.py b/src/sage/repl/rich_output/preferences.py index 00cb5ec2ab6..24b35499a8b 100644 --- a/src/sage/repl/rich_output/preferences.py +++ b/src/sage/repl/rich_output/preferences.py @@ -83,15 +83,15 @@ class Property(property): def __init__(self, name, allowed_values, doc=None): r""" - Preference item + Preference item. INPUT: - - ``name`` -- string. The name of the property. + - ``name`` -- string; the name of the property - - ``allowed_values`` -- list/tuple/iterable of allowed values. + - ``allowed_values`` -- list/tuple/iterable of allowed values - - ``doc`` -- string (optional). The docstring of the property. + - ``doc`` -- string (optional); the docstring of the property EXAMPLES:: @@ -115,12 +115,12 @@ def _make_doc(self, doc): INPUT: - - ``doc`` -- the title line of the documentation. + - ``doc`` -- the title line of the documentation OUTPUT: - String. The docstring with auto-generated documentation about - the allowed values added. + string; the docstring with auto-generated documentation about + the allowed values added EXAMPLES:: @@ -149,11 +149,9 @@ def _make_doc(self, doc): def __repr__(self): """ - Return a string representation + Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -166,16 +164,14 @@ def __repr__(self): def getter(self, prefs): """ - Get the current value of the property + Get the current value of the property. INPUT: - ``prefs`` -- the :class:`PreferencesABC` instance that the - property is bound to. - - OUTPUT: + property is bound to - One of the allowed values or ``None`` if not set. + OUTPUT: one of the allowed values or ``None`` if not set EXAMPLES:: @@ -195,12 +191,12 @@ def getter(self, prefs): def setter(self, prefs, value): """ - Get the current value of the property + Get the current value of the property. INPUT: - ``prefs`` -- the :class:`PreferencesABC` instance that the - property is bound to. + property is bound to - ``value`` -- anything. The new value of the property. Setting a property to ``None`` is equivalent to @@ -208,7 +204,7 @@ def setter(self, prefs, value): OUTPUT: - This method does not return anything. A ``ValueError`` is + This method does not return anything. A :exc:`ValueError` is raised if the given ``value`` is not one of the allowed values. @@ -237,12 +233,12 @@ def setter(self, prefs, value): def deleter(self, prefs): """ - Delete the current value of the property + Delete the current value of the property. INPUT: - ``prefs`` -- the :class:`PreferencesABC` instance that the - property is bound to. + property is bound to EXAMPLES:: @@ -267,7 +263,7 @@ class PreferencesABC(SageObject): def __init__(self, *args, **kwds): """ - Preferences for displaying graphics + Preferences for displaying graphics. These can be preferences expressed by the user or by the display backend. They are specified as keyword arguments. @@ -279,8 +275,8 @@ def __init__(self, *args, **kwds): to right, that is, later parents override values from earlier parents. - - ``**kwds`` -- keyword arguments. Will be used to initialize - properties, and override inherited values if necessary. + - ``**kwds`` -- keyword arguments; will be used to initialize + properties, and override inherited values if necessary EXAMPLES:: @@ -331,11 +327,11 @@ def _add_option(cls, name, values, doc): INPUT: - - ``name`` -- the name of the option. + - ``name`` -- the name of the option - - ``values`` -- the allowed values. + - ``values`` -- the allowed values - - ``doc`` -- docstring. + - ``doc`` -- docstring EXAMPLES:: @@ -354,12 +350,11 @@ def _add_option(cls, name, values, doc): def available_options(self): """ - Return the available options + Return the available options. OUTPUT: - Tuple of the preference items as instances of - :class:`Property`. + tuple of the preference items as instances of :class:`Property` EXAMPLES:: @@ -368,18 +363,16 @@ def available_options(self): (align_latex, graphics, supplemental_plot, text) """ options = [] - for key, value in self.__class__.__dict__.items(): + for value in self.__class__.__dict__.values(): if isinstance(value, Property): options.append(value) return tuple(sorted(options, key=str)) def _repr_(self): r""" - Return a string representation - - OUTPUT: + Return a string representation. - String. + OUTPUT: string EXAMPLES:: diff --git a/src/sage/repl/rich_output/pretty_print.py b/src/sage/repl/rich_output/pretty_print.py index 2cb113b230a..93833e01cd8 100644 --- a/src/sage/repl/rich_output/pretty_print.py +++ b/src/sage/repl/rich_output/pretty_print.py @@ -84,15 +84,15 @@ def __init__(self, *args, **kwds): def is_homogeneous(self, common_type): """ - Return whether the pretty print items are homogeneous + Return whether the pretty print items are homogeneous. INPUT: - - ``common_type`` -- a type. + - ``common_type`` -- a type OUTPUT: - Boolean. Whether all items to be pretty printed are of said + boolean; whether all items to be pretty printed are of said type. EXAMPLES:: @@ -108,11 +108,9 @@ def is_homogeneous(self, common_type): def _concatenate_graphs(self): """ - Plot multiple graphs into a single plot + Plot multiple graphs into a single plot. - OUTPUT: - - A graphics object. + OUTPUT: a graphics object EXAMPLES:: @@ -128,11 +126,9 @@ def _concatenate_graphs(self): def _concatenate_graphics(self): """ - Combine multiple graphics objects into one graphics array - - OUTPUT: + Combine multiple graphics objects into one graphics array. - A graphics array. + OUTPUT: a graphics array EXAMPLES:: @@ -210,8 +206,8 @@ def pretty_print(*args, **kwds): INPUT: - - ``*args`` -- any number of positional arguments. The objects to - pretty print. + - ``*args`` -- any number of positional arguments; the objects to + pretty print - ``**kwds`` -- optional keyword arguments that are passed to the rich representation. Examples include: @@ -224,7 +220,7 @@ def pretty_print(*args, **kwds): - ``fontsize`` -- positive integer - - ``frame`` -- (default: ``False``) draw a MATLAB-like frame around + - ``frame`` -- boolean (default: ``False``); draw a MATLAB-like frame around the image EXAMPLES:: diff --git a/src/sage/repl/rich_output/test_backend.py b/src/sage/repl/rich_output/test_backend.py index a08d75624e1..133fb35ae5d 100644 --- a/src/sage/repl/rich_output/test_backend.py +++ b/src/sage/repl/rich_output/test_backend.py @@ -95,11 +95,9 @@ class TestObject(SageObject): def _repr_(self): """ - Return string representation + Return string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -112,7 +110,7 @@ def _repr_(self): def _rich_repr_(self, display_manager): """ - Rich Output Magic Method + Rich Output Magic Method. See :mod:`sage.repl.rich_output` for details. @@ -135,11 +133,9 @@ class BackendTest(BackendBase): def _repr_(self): """ - Return the string representation - - OUTPUT: + Return the string representation. - String. + OUTPUT: string EXAMPLES:: diff --git a/src/sage/repl/user_globals.py b/src/sage/repl/user_globals.py index dfbdc7f72ef..444c0af1405 100644 --- a/src/sage/repl/user_globals.py +++ b/src/sage/repl/user_globals.py @@ -68,7 +68,7 @@ def _check(): """ - Raise ``RuntimeError`` if ``user_globals`` has not been initialized. + Raise :exc:`RuntimeError` if ``user_globals`` has not been initialized. EXAMPLES:: @@ -108,8 +108,8 @@ def set_globals(g): INPUT: - - ``g`` -- a dictionary. Typically, this will be some dictionary - given by the user interface or just ``globals()``. + - ``g`` -- dictionary; typically, this will be some dictionary + given by the user interface or just ``globals()`` EXAMPLES:: @@ -132,7 +132,7 @@ def initialize_globals(all, g=None): - ``all`` -- a module whose globals will be injected - - ``g`` -- a dictionary, see :func:`set_globals`. If this is + - ``g`` -- dictionary; see :func:`set_globals`. If this is ``None``, keep the current globals dictionary. EXAMPLES:: @@ -166,11 +166,11 @@ def get_global(name): """ Return the value of global variable ``name``. - Raise :class:`NameError` if there is no such global variable. + Raise :exc:`NameError` if there is no such global variable. INPUT: - - ``name`` -- a string representing a variable name + - ``name`` -- string representing a variable name OUTPUT: the value of variable ``name`` @@ -199,7 +199,7 @@ def set_global(name, value): INPUT: - - ``name`` -- a string representing a variable name + - ``name`` -- string representing a variable name - ``value`` -- a value to assign to the variable diff --git a/src/sage/rings/algebraic_closure_finite_field.py b/src/sage/rings/algebraic_closure_finite_field.py index 430037f7b31..b5e76c676d3 100644 --- a/src/sage/rings/algebraic_closure_finite_field.py +++ b/src/sage/rings/algebraic_closure_finite_field.py @@ -74,7 +74,6 @@ class AlgebraicClosureFiniteFieldElement(FieldElement): z2 sage: type(F.gen(2)) - """ def __init__(self, parent, value): """ @@ -88,7 +87,6 @@ def __init__(self, parent, value): The ``_test_pickling`` test has to be skipped because there is no coercion map between the parents of ``x`` and ``loads(dumps(x))``. - """ if isinstance(value, Element) and isinstance(value.parent(), FiniteField): n = value.parent().degree() @@ -162,7 +160,6 @@ def _repr_(self): sage: F = GF(3).algebraic_closure() sage: F._repr_() 'Algebraic closure of Finite Field of size 3' - """ return self._value._repr_() @@ -201,7 +198,6 @@ def _add_(self, right): sage: F = GF(3).algebraic_closure() sage: F.gen(2) + F.gen(3) z6^5 + 2*z6^4 + 2*z6^3 + z6^2 + 2*z6 + 1 - """ F = self.parent() x, y = F._to_common_subfield(self, right) @@ -216,7 +212,6 @@ def _sub_(self, right): sage: F = GF(3).algebraic_closure() sage: F.gen(2) - F.gen(3) z6^4 + 2*z6^3 + z6^2 + 2*z6 - """ F = self.parent() x, y = F._to_common_subfield(self, right) @@ -231,7 +226,6 @@ def _mul_(self, right): sage: F = GF(3).algebraic_closure() sage: F.gen(2) * F.gen(3) z6^5 + 2*z6^4 + z6^2 + 2 - """ F = self.parent() x, y = F._to_common_subfield(self, right) @@ -246,7 +240,6 @@ def _div_(self, right): sage: F = GF(3).algebraic_closure() sage: F.gen(2) / F.gen(3) z6^5 + 2*z6^4 + z6^3 + 1 - """ F = self.parent() x, y = F._to_common_subfield(self, right) @@ -282,7 +275,6 @@ def change_level(self, n): From: Finite Field of size 3 To: Finite Field in z3 of size 3^3 Defn: 1 |--> 1 - """ F = self.parent() l = self._level @@ -304,7 +296,6 @@ def _latex_(self): z6^5 + 2*z6^4 + 2*z6^3 + z6^2 + 2*z6 + 2 sage: latex(s) z_{6}^{5} + 2 z_{6}^{4} + 2 z_{6}^{3} + z_{6}^{2} + 2 z_{6} + 2 - """ return self._value._latex_() @@ -318,7 +309,6 @@ def minpoly(self): sage: F = GF(11).algebraic_closure() sage: F.gen(3).minpoly() x^3 + 2*x + 9 - """ return self._value.minpoly() @@ -335,7 +325,6 @@ def is_square(self): sage: F = GF(3).algebraic_closure() sage: F.gen(2).is_square() True - """ return True @@ -384,7 +373,6 @@ def nth_root(self, n): .. TODO:: This function could probably be made faster. - """ from sage.rings.integer import Integer F = self.parent() @@ -414,7 +402,6 @@ def multiplicative_order(self): 16806 sage: (K.gen(1) + K.gen(2) + K.gen(3)).multiplicative_order() 7353 - """ return self._value.multiplicative_order() @@ -436,7 +423,6 @@ def pth_power(self, k=1): t3^2 + t3 + 1 sage: s.pth_power(3).parent() is K True - """ return self.__class__(self.parent(), self._value.pth_power(k)) @@ -458,7 +444,6 @@ def pth_root(self, k=1): t3^2 + t3 + 1 sage: s.pth_root(2).parent() is K True - """ return self.__class__(self.parent(), self._value.pth_root(k)) @@ -468,8 +453,8 @@ def as_finite_field_element(self, minimal=False): INPUT: - - ``minimal`` -- boolean (default: ``False``). If ``True``, - always return the smallest subfield containing ``self``. + - ``minimal`` -- boolean (default: ``False``); if ``True``, + always return the smallest subfield containing ``self`` OUTPUT: @@ -533,7 +518,6 @@ def as_finite_field_element(self, minimal=False): Defn: z2 |--> z4^3 + z4^2 + z4 + 3 sage: f(b) z4^3 + z4^2 + z4 + 4 - """ Fbar = self.parent() x = self._value @@ -621,7 +605,6 @@ def characteristic(self): sage: F = AlgebraicClosureFiniteField(GF(p), 'z') sage: F.characteristic() == p True - """ return self.base_ring().characteristic() @@ -644,7 +627,6 @@ def _element_constructor_(self, x): Traceback (most recent call last): ... ValueError: no conversion defined between different algebraic closures - """ if isinstance(x, self.element_class): if x.parent() is not self: @@ -663,7 +645,6 @@ def _coerce_map_from_(self, other): sage: F = GF(7).algebraic_closure() sage: F.has_coerce_map_from(Integers()) True - """ if other is self: return True @@ -682,7 +663,6 @@ def _repr_(self): sage: F = AlgebraicClosureFiniteField(GF(5), 'z') sage: F._repr_() 'Algebraic closure of Finite Field of size 5' - """ return 'Algebraic closure of %s' % self.base_ring() @@ -710,7 +690,6 @@ def _to_common_subfield(self, x, y): Finite Field in z6 of size 3^6 sage: y.parent() Finite Field in z6 of size 3^6 - """ if x._level == y._level: return x._value, y._value @@ -753,7 +732,6 @@ def _get_im_gen(self, m, n): Traceback (most recent call last): ... NotImplementedError: - """ def _subfield(self, n): @@ -765,7 +743,6 @@ def _subfield(self, n): sage: F = GF(3).algebraic_closure() sage: F._subfield(4) Finite Field in z4 of size 3^4 - """ if n == 1: return self.base_ring() @@ -797,7 +774,6 @@ def subfield(self, n): From: Finite Field in z4 of size 3^4 To: Algebraic closure of Finite Field of size 3 Defn: z4 |--> z4) - """ Fn = self._subfield(n) return Fn, Fn.hom( (self.gen(n),), check=False) @@ -820,7 +796,6 @@ def inclusion(self, m, n): From: Finite Field in z2 of size 3^2 To: Finite Field in z4 of size 3^4 Defn: z2 |--> 2*z4^3 + 2*z4^2 + 1 - """ if m.divides(n): # check=False is required to avoid "coercion hell": an @@ -840,7 +815,6 @@ def ngens(self): sage: from sage.rings.algebraic_closure_finite_field import AlgebraicClosureFiniteField sage: AlgebraicClosureFiniteField(GF(5), 'z').ngens() +Infinity - """ from sage.rings.infinity import Infinity return Infinity @@ -855,7 +829,6 @@ def gen(self, n): sage: F = AlgebraicClosureFiniteField(GF(5), 'z') sage: F.gen(2) z2 - """ F = self._subfield(n) return self(F.gen()) @@ -892,7 +865,6 @@ def _first_ngens(self, n): sage: F = AlgebraicClosureFiniteField(GF(5), 'z') sage: F._first_ngens(3) (1, z2, z3) - """ return tuple(self.gen(i + 1) for i in range(n)) @@ -908,7 +880,6 @@ def algebraic_closure(self): sage: F = AlgebraicClosureFiniteField(GF(5), 'z') sage: F.algebraic_closure() is F True - """ return self @@ -920,7 +891,6 @@ def _an_element_(self): sage: F = AlgebraicClosureFiniteField(GF(5), 'w') sage: F.an_element() # indirect doctest w2 - """ return self.gen(2) @@ -933,7 +903,6 @@ def some_elements(self): sage: F = GF(7).algebraic_closure() sage: F.some_elements() (1, z2, z3 + 1) - """ return (self(1), self.gen(2), 1+self.gen(3)) @@ -962,7 +931,6 @@ def _roots_univariate_polynomial(self, p, ring=None, multiplicities=None, algori ....: p = R.random_element(degree=randint(2,8)) ....: for r in p.roots(K, multiplicities=False): ....: assert p(r).is_zero(), "r={} is not a root of p={}".format(r,p) - """ from sage.arith.functions import lcm from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing @@ -1013,7 +981,6 @@ def _factor_univariate_polynomial(self, p, **kwds): sage: for d in range(10): ....: p = R.random_element(degree=randint(2,8)) ....: assert p.factor().prod() == p, "error in the factorization of p={}".format(p) - """ from sage.structure.factorization import Factorization R = p.parent() @@ -1045,7 +1012,6 @@ class AlgebraicClosureFiniteField_pseudo_conway(WithEqualityById, AlgebraicClosu sage: F5 = GF(5).algebraic_closure() sage: F3 == F5 False - """ def __init__(self, base_ring, name, category=None, lattice=None, use_database=True): """ @@ -1056,18 +1022,18 @@ def __init__(self, base_ring, name, category=None, lattice=None, use_database=Tr accepted. - ``name`` -- prefix to use for generators of the finite - subfields. + subfields - ``category`` -- if provided, specifies the category in which - this algebraic closure will be placed. + this algebraic closure will be placed - ``lattice`` -- :class:`~sage.rings.finite_rings.conway_polynomials.PseudoConwayPolynomialLattice` - (default: None). If provided, use this pseudo-Conway + (default: ``None``); if provided, use this pseudo-Conway polynomial lattice to construct an algebraic closure. - - ``use_database`` -- boolean. If True (default), use actual + - ``use_database`` -- boolean. If ``True`` (default), use actual Conway polynomials whenever they are available in the - database. If False, always compute pseudo-Conway + database. If ``False``, always compute pseudo-Conway polynomials from scratch. TESTS:: @@ -1098,7 +1064,6 @@ def __init__(self, base_ring, name, category=None, lattice=None, use_database=Tr be made to compare equal, and ``_test_elements`` has to be skipped for the reason described in :meth:`AlgebraicClosureFiniteFieldElement.__init__`. - """ if not (isinstance(base_ring, FiniteField) and base_ring.is_prime_field()): raise NotImplementedError('algebraic closures of finite fields are only implemented for prime fields') @@ -1122,7 +1087,6 @@ def _get_polynomial(self, n): sage: F = AlgebraicClosureFiniteField_pseudo_conway(GF(5), 'z') sage: F._get_polynomial(1) x + 3 - """ return self._pseudo_conway_lattice.polynomial(n) @@ -1137,7 +1101,6 @@ def _get_im_gen(self, m, n): sage: F = AlgebraicClosureFiniteField_pseudo_conway(GF(5), 'z') sage: F._get_im_gen(2, 4) z4^3 + z4^2 + z4 + 3 - """ p = self.characteristic() if m == 1: @@ -1177,7 +1140,6 @@ def AlgebraicClosureFiniteField(base_ring, name, category=None, implementation=N This is to ensure that the result of comparing two instances cannot change with time. - """ if category is None: from sage.categories.fields import Fields diff --git a/src/sage/rings/asymptotic/asymptotic_expansion_generators.py b/src/sage/rings/asymptotic/asymptotic_expansion_generators.py index 2d0569cce1e..45a46e4a703 100644 --- a/src/sage/rings/asymptotic/asymptotic_expansion_generators.py +++ b/src/sage/rings/asymptotic/asymptotic_expansion_generators.py @@ -113,20 +113,18 @@ def Stirling(var, precision=None, skip_constant_factor=False): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``precision`` -- (default: ``None``) an integer `\ge 3`. If ``None``, then + - ``precision`` -- (default: ``None``) integer `\ge 3`. If ``None``, then the default precision of the asymptotic ring is used. - - ``skip_constant_factor`` -- (default: ``False``) a - boolean. If set, then the constant factor `\sqrt{2\pi}` is left out. + - ``skip_constant_factor`` -- boolean (default: ``False``); if set, + then the constant factor `\sqrt{2\pi}` is left out. As a consequence, the coefficient ring of the output changes from ``Symbolic Constants Subring`` (if ``False``) to ``Rational Field`` (if ``True``). - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -205,20 +203,18 @@ def log_Stirling(var, precision=None, skip_constant_summand=False): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - ``skip_constant_summand`` -- (default: ``False``) a - boolean. If set, then the constant summand `\log(2\pi)/2` is left out. + - ``skip_constant_summand`` -- boolean (default: ``False``); if set, + then the constant summand `\log(2\pi)/2` is left out. As a consequence, the coefficient ring of the output changes from ``Symbolic Constants Subring`` (if ``False``) to ``Rational Field`` (if ``True``). - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -329,14 +325,12 @@ def _log_StirlingNegativePowers_(var, precision): INPUT: - - ``var`` -- a string for the variable name. - - - ``precision`` -- an integer specifying the number of exact summands. - If this is negative, then the result is `0`. + - ``var`` -- string for the variable name - OUTPUT: + - ``precision`` -- integer specifying the number of exact summands; + if this is negative, then the result is `0` - An asymptotic expansion. + OUTPUT: an asymptotic expansion TESTS:: @@ -376,20 +370,18 @@ def HarmonicNumber(var, precision=None, skip_constant_summand=False): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - ``skip_constant_summand`` -- (default: ``False``) a - boolean. If set, then the constant summand ``euler_gamma`` is left out. + - ``skip_constant_summand`` -- boolean (default: ``False``); if set, + then the constant summand ``euler_gamma`` is left out. As a consequence, the coefficient ring of the output changes from ``Symbolic Constants Subring`` (if ``False``) to ``Rational Field`` (if ``True``). - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -482,23 +474,20 @@ def Binomial_kn_over_n(var, k, precision=None, skip_constant_factor=False): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``k`` -- a number or symbolic constant. + - ``k`` -- a number or symbolic constant - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - ``skip_constant_factor`` -- (default: ``False``) a - boolean. If set, then the constant factor `\sqrt{k/(2\pi(k-1))}` - is left out. + - ``skip_constant_factor`` -- boolean (default: ``False``); if set, + then the constant factor `\sqrt{k/(2\pi(k-1))}` is left out. As a consequence, the coefficient ring of the output changes from ``Symbolic Constants Subring`` (if ``False``) to ``Rational Field`` (if ``True``). - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -628,25 +617,23 @@ def SingularityAnalysis(var, zeta=1, alpha=0, beta=0, delta=0, INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``zeta`` -- (default: `1`) the location of the singularity. + - ``zeta`` -- (default: `1`) the location of the singularity - - ``alpha`` -- (default: `0`) the pole order of the singularity. + - ``alpha`` -- (default: `0`) the pole order of the singularity - - ``beta`` -- (default: `0`) the order of the logarithmic singularity. + - ``beta`` -- (default: `0`) the order of the logarithmic singularity - - ``delta`` -- (default: `0`) the order of the log-log singularity. - Not yet implemented for ``delta != 0``. + - ``delta`` -- (default: `0`) the order of the log-log singularity; + not yet implemented for ``delta != 0`` - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - ``normalized`` -- (default: ``True``) a boolean, see above. + - ``normalized`` -- boolean (default: ``True``); see above - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1052,22 +1039,19 @@ def ImplicitExpansion(var, phi, tau=None, precision=None): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``phi`` -- the function `\Phi`. See the extended description for - assumptions on `\Phi`. + - ``phi`` -- the function `\Phi`; see the extended description for + assumptions on `\Phi` - ``tau`` -- (default: ``None``) the fundamental constant described in the extended description. If ``None``, then `\tau` is determined automatically if possible. - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -1078,7 +1062,6 @@ def ImplicitExpansion(var, phi, tau=None, precision=None): represents a singular element of the form `(1 - z/\rho)^{-1}`, for the variable `z\to\rho`. - EXAMPLES: We can, for example, determine the singular expansion of the well-known @@ -1151,7 +1134,6 @@ def ImplicitExpansion(var, phi, tau=None, precision=None): Traceback (most recent call last): ... ValueError: Fundamental constant tau could not be determined - """ from sage.symbolic.ring import SR from sage.rings.rational_field import QQ @@ -1222,25 +1204,22 @@ def ImplicitExpansionPeriodicPart(var, phi, period, tau=None, precision=None): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``phi`` -- the function `\Phi`. See the extended description for - assumptions on `\Phi`. + - ``phi`` -- the function `\Phi`; see the extended description for + assumptions on `\Phi` - - ``period`` -- the period of the function `\Phi`. See the - extended description for details. + - ``period`` -- the period of the function `\Phi`; see the + extended description for details - ``tau`` -- (default: ``None``) the fundamental constant described in the extended description. If ``None``, then `\tau` is determined automatically if possible. - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -1276,7 +1255,6 @@ def ImplicitExpansionPeriodicPart(var, phi, period, tau=None, precision=None): sage: A. = AsymptoticRing('Z^QQ', QQ, default_prec=3) sage: g((1 - 1/Z)/4) 2 - 2*Z^(-1/2) + 2*Z^(-1) - 2*Z^(-3/2) + 2*Z^(-2) - 2*Z^(-5/2) + O(Z^(-3)) - """ if tau is None: tau = _fundamental_constant_implicit_function_(phi=phi) @@ -1307,25 +1285,22 @@ def InverseFunctionAnalysis(var, phi, tau=None, period=1, precision=None): INPUT: - - ``var`` -- a string for the variable name. + - ``var`` -- string for the variable name - - ``phi`` -- the function `\Phi`. See the extended description for - assumptions on `\Phi`. + - ``phi`` -- the function `\Phi`; see the extended description for + assumptions on `\Phi` - ``tau`` -- (default: ``None``) the fundamental constant described in the extended description. If ``None``, then `\tau` is determined automatically if possible. - ``period`` -- (default: `1`) the period of the function `\Phi`. See - the extended description for details. + the extended description for details - - ``precision`` -- (default: ``None``) an integer. If ``None``, then + - ``precision`` -- (default: ``None``) integer. If ``None``, then the default precision of the asymptotic ring is used. - - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -1337,7 +1312,6 @@ def InverseFunctionAnalysis(var, phi, tau=None, period=1, precision=None): for `n \equiv 1 \mod p`, where `p` is the period. All other coefficients are `0`. - EXAMPLES: There are `C_n` (the `n`-th Catalan number) different binary trees @@ -1418,7 +1392,7 @@ def _fundamental_constant_implicit_function_(phi): INPUT: - - ``phi`` -- the function `\Phi`. + - ``phi`` -- the function `\Phi` .. SEEALSO:: @@ -1435,7 +1409,6 @@ def _fundamental_constant_implicit_function_(phi): 1 sage: _fundamental_constant_implicit_function_(phi=lambda u: 1 + 2*u + 2*u^2) 1/2*sqrt(2) - """ from sage.symbolic.ring import SR u = SR('u') @@ -1451,14 +1424,11 @@ def _sa_coefficients_lambda_(K, beta=0): INPUT: - - ``K`` -- an integer. - - - ``beta`` -- (default: `0`) the order of the logarithmic - singularity. + - ``K`` -- integer - OUTPUT: + - ``beta`` -- (default: `0`) the order of the logarithmic singularity - A dictionary mapping pairs of indices to rationals. + OUTPUT: a dictionary mapping pairs of indices to rationals .. SEEALSO:: diff --git a/src/sage/rings/asymptotic/asymptotic_ring.py b/src/sage/rings/asymptotic/asymptotic_ring.py index d85f407872f..6af7b1a325d 100644 --- a/src/sage/rings/asymptotic/asymptotic_ring.py +++ b/src/sage/rings/asymptotic/asymptotic_ring.py @@ -438,16 +438,16 @@ class AsymptoticExpansion(CommutativeAlgebraElement): INPUT: - - ``parent`` -- the parent of the asymptotic expansion. + - ``parent`` -- the parent of the asymptotic expansion - ``summands`` -- the summands as a :class:`~sage.data_structures.mutable_poset.MutablePoset`, which - represents the underlying structure. + represents the underlying structure - - ``simplify`` -- a boolean (default: ``True``). It controls - automatic simplification (absorption) of the asymptotic expansion. + - ``simplify`` -- boolean (default: ``True``); it controls + automatic simplification (absorption) of the asymptotic expansion - - ``convert`` -- a boolean (default: ``True``). If set, then the + - ``convert`` -- boolean (default: ``True``); if set, then the ``summands`` are converted to the asymptotic ring (the parent of this expansion). If not, then the summands are taken as they are. In that case, the caller must ensure that the parent of the terms is @@ -739,9 +739,7 @@ def __bool__(self) -> bool: r""" Return whether this asymptotic expansion is not identically zero. - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -761,11 +759,9 @@ def __eq__(self, other) -> bool: INPUT: - - ``other`` -- an object. - - OUTPUT: + - ``other`` -- an object - A boolean. + OUTPUT: boolean .. NOTE:: @@ -803,11 +799,9 @@ def __ne__(self, other) -> bool: INPUT: - - ``other`` -- an object. + - ``other`` -- an object - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -836,11 +830,9 @@ def has_same_summands(self, other) -> bool: INPUT: - - ``other`` -- an asymptotic expansion. - - OUTPUT: + - ``other`` -- an asymptotic expansion - A boolean. + OUTPUT: boolean .. NOTE:: @@ -884,11 +876,9 @@ def _has_same_summands_(self, other) -> bool: INPUT: - - ``other`` -- an :class:`AsymptoticExpansion`. + - ``other`` -- an :class:`AsymptoticExpansion` - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -913,9 +903,7 @@ def _simplify_(self): r""" Simplify this asymptotic expansion. - OUTPUT: - - Nothing, but modifies this asymptotic expansion. + OUTPUT: nothing, but modifies this asymptotic expansion .. NOTE:: @@ -951,12 +939,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -983,9 +969,7 @@ def _latex_(self): r""" A LaTeX-representation string for this asymptotic expansion. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -1031,9 +1015,7 @@ def monomial_coefficient(self, monomial): - ``monomial`` -- a monomial element which can be converted into the asymptotic ring of this element - OUTPUT: - - An element of the coefficient ring. + OUTPUT: an element of the coefficient ring EXAMPLES:: @@ -1091,7 +1073,6 @@ def monomial_coefficient(self, monomial): Traceback (most recent call last): ... ValueError: non-exact monomial O(n) - """ monomial = self.parent()(monomial) if not monomial.is_exact(): @@ -1112,11 +1093,9 @@ def _add_(self, other): INPUT: - - ``other`` -- an :class:`AsymptoticExpansion`. + - ``other`` -- an :class:`AsymptoticExpansion` - OUTPUT: - - The sum as an :class:`AsymptoticExpansion`. + OUTPUT: the sum as an :class:`AsymptoticExpansion` EXAMPLES:: @@ -1149,11 +1128,9 @@ def _sub_(self, other): INPUT: - - ``other`` -- an :class:`AsymptoticExpansion`. - - OUTPUT: + - ``other`` -- an :class:`AsymptoticExpansion` - The difference as an :class:`AsymptoticExpansion`. + OUTPUT: the difference as an :class:`AsymptoticExpansion` .. NOTE:: @@ -1178,12 +1155,9 @@ def _mul_term_(self, term): INPUT: - - ``term`` -- an asymptotic term (see - :doc:`term_monoid`). + - ``term`` -- an asymptotic term (see :doc:`term_monoid`) - OUTPUT: - - The product as an :class:`AsymptoticExpansion`. + OUTPUT: the product as an :class:`AsymptoticExpansion` TESTS:: @@ -1207,11 +1181,9 @@ def _mul_(self, other): INPUT: - - ``other`` -- an :class:`AsymptoticExpansion`. - - OUTPUT: + - ``other`` -- an :class:`AsymptoticExpansion` - The product as an :class:`AsymptoticExpansion`. + OUTPUT: the product as an :class:`AsymptoticExpansion` EXAMPLES:: @@ -1247,11 +1219,9 @@ def _lmul_(self, other): INPUT: - - ``other`` -- an element of the coefficient ring. + - ``other`` -- an element of the coefficient ring - OUTPUT: - - An :class:`AsymptoticExpansion`. + OUTPUT: an :class:`AsymptoticExpansion` TESTS:: @@ -1272,11 +1242,9 @@ def _div_(self, other): INPUT: - - ``other`` -- an asymptotic expansion. + - ``other`` -- an asymptotic expansion - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1310,9 +1278,7 @@ def __invert__(self, precision=None): expansion. If ``None`` (default value) is used, the default precision of the parent is used. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. WARNING:: @@ -1393,13 +1359,11 @@ def truncate(self, precision=None): INPUT: - - ``precision`` -- a positive integer or ``None``. Number of + - ``precision`` -- positive integer or ``None``. Number of summands that are kept. If ``None`` (default value) is given, then ``default_prec`` from the parent is used. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -1444,9 +1408,7 @@ def exact_part(self): Return the expansion consisting of all exact terms of this expansion. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1476,9 +1438,7 @@ def error_part(self): Return the expansion consisting of all error terms of this expansion. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1498,15 +1458,13 @@ def __pow__(self, exponent, precision=None): INPUT: - - ``exponent`` -- an element. + - ``exponent`` -- an element - ``precision`` -- the precision used for truncating the expansion. If ``None`` (default value) is used, the default precision of the parent is used. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1719,17 +1677,15 @@ def __pow_number__(self, exponent, precision=None, check_convergence=False): INPUT: - ``exponent`` -- a numerical value (e.g. integer, rational) - or other constant. + or other constant - - ``precision`` -- a non-negative integer. + - ``precision`` -- nonnegative integer - - ``check_convergence`` -- (default: ``False``) a boolean. If set, + - ``check_convergence`` -- boolean (default: ``False``); if set, then an additional check on the input is performed to ensure - that the calculated sum converges. + that the calculated sum converges - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. SEEALSO:: @@ -1861,9 +1817,7 @@ def sqrt(self, precision=None): expansion. If ``None`` (default value) is used, the default precision of the parent is used. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1892,9 +1846,7 @@ def O(self): r""" Convert all terms in this asymptotic expansion to `O`-terms. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -1942,14 +1894,12 @@ def log(self, base=None, precision=None, locals=None): expansion. If ``None`` (default value) is used, the default precision of the parent is used. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -2066,9 +2016,7 @@ def is_exact(self) -> bool: r""" Return whether all terms of this expansion are exact. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -2091,9 +2039,7 @@ def is_little_o_of_one(self) -> bool: r""" Return whether this expansion is of order `o(1)`. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -2129,20 +2075,18 @@ def rpow(self, base, precision=None, locals=None): INPUT: - - ``base`` -- an element or ``'e'``. + - ``base`` -- an element or ``'e'`` - ``precision`` -- the precision used for truncating the expansion. If ``None`` (default value) is used, the default precision of the parent is used. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -2244,8 +2188,8 @@ def _main_term_relative_error_(self, return_inverse_main_term=False): INPUT: - - ``return_inverse_main_term`` -- (default: ``False``) a boolean. - If set, then the pair `(m^{-1},x)` is returned instead of `(m,x)`. + - ``return_inverse_main_term`` -- boolean (default: ``False``); + if set, then the pair `(m^{-1},x)` is returned instead of `(m,x)` OUTPUT: @@ -2332,20 +2276,18 @@ def _power_series_(coefficients, start, ratio, ratio_start, precision): INPUT: - - ``coefficients`` -- an iterator. + - ``coefficients`` -- an iterator - - ``start`` -- an asymptotic expansion. + - ``start`` -- an asymptotic expansion - - ``ratio`` -- an asymptotic expansion. + - ``ratio`` -- an asymptotic expansion - - ``ratio_start`` -- an asymptotic expansion. + - ``ratio_start`` -- an asymptotic expansion - - ``precision`` -- a non-negative integer. All intermediate - results are truncated to this precision. + - ``precision`` -- nonnegative integer; all intermediate + results are truncated to this precision - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion TESTS:: @@ -2394,9 +2336,7 @@ def exp(self, precision=None): expansion. If ``None`` (default value) is used, the default precision of the parent is used. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -2459,19 +2399,17 @@ def subs(self, rules=None, domain=None, **kwds): INPUT: - - ``rules`` -- a dictionary. + - ``rules`` -- dictionary - ``kwds`` -- keyword arguments will be added to the - substitution ``rules``. + substitution ``rules`` - ``domain`` -- (default: ``None``) a parent. The neutral elements `0` and `1` (rules for the keys ``'_zero_'`` and ``'_one_'``, see note box below) are taken out of this domain. If ``None``, then this is determined automatically. - OUTPUT: - - An object. + OUTPUT: an object .. NOTE:: @@ -2683,13 +2621,10 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. - The neutral element of the asymptotic ring is replaced by the value - to key ``'_zero_'``. - - OUTPUT: + - ``rules`` -- dictionary. The neutral element of the asymptotic ring + is replaced by the value to key ``'_zero_'``. - An object. + OUTPUT: an object TESTS:: @@ -2734,20 +2669,20 @@ def compare_with_values(self, variable, function, values, INPUT: - - ``variable`` -- an asymptotic expansion or a string. + - ``variable`` -- an asymptotic expansion or a string - ``function`` -- a callable or symbolic expression giving the - comparison values. + comparison values - - ``values`` -- a list or iterable of values where the comparison - shall be carried out. + - ``values`` -- list or iterable of values where the comparison + shall be carried out - - ``rescaled`` -- (default: ``True``) determines whether + - ``rescaled`` -- boolean (default: ``True``); determines whether the difference is divided by the error term of the asymptotic - expansion. + expansion - ``ring`` -- (default: ``RIF``) the parent into which the - difference is converted. + difference is converted OUTPUT: @@ -2893,29 +2828,27 @@ def plot_comparison(self, variable, function, values, rescaled=True, INPUT: - - ``variable`` -- an asymptotic expansion or a string. + - ``variable`` -- an asymptotic expansion or a string - ``function`` -- a callable or symbolic expression giving the - comparison values. + comparison values - - ``values`` -- a list or iterable of values where the comparison - shall be carried out. + - ``values`` -- list or iterable of values where the comparison + shall be carried out - - ``rescaled`` -- (default: ``True``) determines whether + - ``rescaled`` -- boolean (default: ``True``); determines whether the difference is divided by the error term of the asymptotic - expansion. + expansion - ``ring`` -- (default: ``RIF``) the parent into which the - difference is converted. + difference is converted - - ``relative_tolerance`` -- (default: ``0.025``). Raise error - when relative error exceeds this tolerance. + - ``relative_tolerance`` -- (default: ``0.025``) raise error + when relative error exceeds this tolerance Other keyword arguments are passed to :func:`list_plot`. - OUTPUT: - - A graphics object. + OUTPUT: a graphics object .. NOTE:: @@ -2991,9 +2924,7 @@ def symbolic_expression(self, R=None): The output will be an element of ``R``. If ``None``, then the symbolic ring is used. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -3044,13 +2975,11 @@ def map_coefficients(self, f, new_coefficient_ring=None): INPUT: - - ``f`` -- a callable. A coefficient `c` will be mapped to `f(c)`. + - ``f`` -- a callable; a coefficient `c` will be mapped to `f(c)` - - ``new_coefficient_ring`` -- (default: ``None``) a ring. + - ``new_coefficient_ring`` -- (default: ``None``) a ring - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -3095,9 +3024,7 @@ def factorial(self): r""" Return the factorial of this asymptotic expansion. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -3196,9 +3123,7 @@ def variable_names(self): r""" Return the names of the variables of this asymptotic expansion. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -3233,17 +3158,15 @@ def _singularity_analysis_(self, var, zeta, precision=None): INPUT: - - ``var`` -- a string, the variable for the growth of the coefficients, - or the generator of an asymptotic ring. + - ``var`` -- string; the variable for the growth of the coefficients, + or the generator of an asymptotic ring - ``zeta`` -- location of the singularity - - ``precision`` -- (default: ``None``) an integer. If ``None``, then - the default precision of the parent of this expansion is used. + - ``precision`` -- (default: ``None``) integer; if ``None``, then + the default precision of the parent of this expansion is used - OUTPUT: - - An asymptotic expansion in ``var``. + OUTPUT: an asymptotic expansion in ``var`` EXAMPLES:: @@ -3316,9 +3239,7 @@ def limit(self): """ Compute the limit of this asymptotic expansion. - OUTPUT: - - An element of the coefficient ring. + OUTPUT: an element of the coefficient ring EXAMPLES:: @@ -3369,9 +3290,7 @@ def B(self, valid_from=0): is passed to ``valid_from``, then the lower bounds for all variables of the asymptotic expansion are set to this number - OUTPUT: - - An asymptotic expansion + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -3417,10 +3336,10 @@ class AsymptoticRing(Parent, UniqueRepresentation, WithLocals): :class:`~sage.rings.asymptotic.growth_group.GrowthGroupFactory`). - ``coefficient_ring`` -- the ring which contains the - coefficients of the expansions. + coefficients of the expansions - - ``default_prec`` -- a positive integer. This is the number of - summands that are kept before truncating an infinite series. + - ``default_prec`` -- positive integer; this is the number of + summands that are kept before truncating an infinite series - ``category`` -- the category of the parent can be specified in order to broaden the base structure. It has to be a @@ -3431,7 +3350,7 @@ class AsymptoticRing(Parent, UniqueRepresentation, WithLocals): If ``None``, then :class:`~sage.rings.asymptotic.term_monoid.DefaultTermMonoidFactory` is used. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not given, then the usual :class:`log ` is taken. @@ -3537,7 +3456,7 @@ def __classcall__(cls, growth_group=None, coefficient_ring=None, term_monoid_factory=None, locals=None): r""" - Normalizes the input in order to ensure a unique + Normalize the input in order to ensure a unique representation of the parent. For more information see :class:`AsymptoticRing`. @@ -3778,7 +3697,7 @@ def term_monoid(self, type): INPUT: - - ``type`` -- 'O' or 'exact', or an instance of an existing + - ``type`` -- ``'O'`` or ``'exact'``, or an instance of an existing term monoid. See :class:`~sage.rings.asymptotic.term_monoid.TermMonoidFactory` for more details. @@ -3807,17 +3726,15 @@ def change_parameter(self, **kwds): INPUT: - - ``growth_group`` -- (default: ``None``) the new growth group. - - - ``coefficient_ring`` -- (default: ``None``) the new coefficient ring. + - ``growth_group`` -- (default: ``None``) the new growth group - - ``category`` -- (default: ``None``) the new category. + - ``coefficient_ring`` -- (default: ``None``) the new coefficient ring - - ``default_prec`` -- (default: ``None``) the new default precision. + - ``category`` -- (default: ``None``) the new category - OUTPUT: + - ``default_prec`` -- (default: ``None``) the new default precision - An asymptotic ring. + OUTPUT: an asymptotic ring EXAMPLES:: @@ -3858,9 +3775,7 @@ def _create_empty_summands_(): Create an empty data structure suitable for storing and working with summands. - OUTPUT: - - A :class:`~sage.data_structures.mutable_poset.MutablePoset`. + OUTPUT: a :class:`~sage.data_structures.mutable_poset.MutablePoset` TESTS:: @@ -3880,15 +3795,13 @@ def _create_element_in_extension_(self, term, old_term_parent=None): INPUT: - - ``term`` -- the element data. + - ``term`` -- the element data - ``old_term_parent`` -- the parent of ``term`` is compared to this parent. If both are the same or ``old_parent`` is ``None``, then the result is an expansion in this (``self``) asymptotic ring. - OUTPUT: - - An element. + OUTPUT: an element EXAMPLES:: @@ -3926,21 +3839,19 @@ def _element_constructor_(self, data, simplify=True, convert=True): INPUT: - ``data`` -- an object representing the element to be - initialized. + initialized - - ``simplify`` -- (default: ``True``) if set, then the constructed - element is simplified (terms are absorbed) automatically. + - ``simplify`` -- boolean (default: ``True``); if set, then the constructed + element is simplified (terms are absorbed) automatically - - ``convert`` -- (default: ``True``) passed on to the element + - ``convert`` -- boolean (default: ``True``); passed on to the element constructor. If set, then the ``summands`` are converted to the asymptotic ring (the parent of this expansion). If not, then the summands are taken as they are. In that case, the caller must ensure that the parent of the terms is set correctly. - OUTPUT: - - An element of this asymptotic ring. + OUTPUT: an element of this asymptotic ring TESTS:: @@ -4078,8 +3989,8 @@ def _element_constructor_(self, data, simplify=True, convert=True): from .misc import combine_exceptions from sage.symbolic.ring import SymbolicRing - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base from sage.rings.power_series_ring import is_PowerSeriesRing if isinstance(P, SymbolicRing): @@ -4097,7 +4008,7 @@ def _element_constructor_(self, data, simplify=True, convert=True): (data, self)), e) return sum(summands, self.zero()) - elif is_PolynomialRing(P): + elif isinstance(P, PolynomialRing_general): p = P.gen() try: return sum(iter(self.create_summand('exact', growth=p**i, @@ -4108,7 +4019,7 @@ def _element_constructor_(self, data, simplify=True, convert=True): raise combine_exceptions( ValueError('Polynomial %s is not in %s' % (data, self)), e) - elif is_MPolynomialRing(P): + elif isinstance(P, MPolynomialRing_base): try: return sum(iter(self.create_summand('exact', growth=g, coefficient=c) for c, g in iter(data)), @@ -4149,11 +4060,9 @@ def _coerce_map_from_(self, R): INPUT: - - ``R`` -- a parent. - - OUTPUT: + - ``R`` -- a parent - A boolean. + OUTPUT: boolean .. NOTE:: @@ -4200,9 +4109,7 @@ def _repr_(self) -> str: r""" A representation string of this asymptotic ring. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -4221,9 +4128,7 @@ def _an_element_(self): r""" Return an element of this asymptotic ring. - OUTPUT: - - An :class:`AsymptoticExpansion`. + OUTPUT: an :class:`AsymptoticExpansion` EXAMPLES:: @@ -4245,9 +4150,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -4277,9 +4180,7 @@ def gens(self) -> tuple: r""" Return a tuple with generators of this asymptotic ring. - OUTPUT: - - A tuple of asymptotic expansions. + OUTPUT: a tuple of asymptotic expansions .. NOTE:: @@ -4309,11 +4210,9 @@ def gen(self, n=0): INPUT: - - ``n`` -- (default: `0`) a non-negative integer. - - OUTPUT: + - ``n`` -- (default: `0`) a nonnegative integer - An asymptotic expansion. + OUTPUT: an asymptotic expansion EXAMPLES:: @@ -4327,9 +4226,7 @@ def ngens(self): r""" Return the number of generators of this asymptotic ring. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -4348,15 +4245,15 @@ def coefficients_of_generating_function(self, function, singularities, precision INPUT: - - ``function`` -- a callable function in one variable. + - ``function`` -- a callable function in one variable - - ``singularities`` -- list of dominant singularities of the function. + - ``singularities`` -- list of dominant singularities of the function - - ``precision`` -- (default: ``None``) an integer. If ``None``, then - the default precision of the asymptotic ring is used. + - ``precision`` -- integer (default: ``None``); if ``None``, then + the default precision of the asymptotic ring is used - - ``return_singular_expansions`` -- (default: ``False``) a boolean. - If set, the singular expansions are also returned. + - ``return_singular_expansions`` -- boolean (default: ``False``); + if set, the singular expansions are also returned - ``error_term`` -- (default: ``None``) an asymptotic expansion. If ``None``, then this is interpreted as zero. @@ -4491,22 +4388,20 @@ def create_summand(self, type, data=None, **kwds): INPUT: - - ``type`` -- 'O' or 'exact'. + - ``type`` -- 'O' or 'exact' - - ``data`` -- the element out of which a summand has to be created. + - ``data`` -- the element out of which a summand has to be created - - ``growth`` -- an element of the :meth:`growth_group`. + - ``growth`` -- an element of the :meth:`growth_group` - - ``coefficient`` -- an element of the :meth:`coefficient_ring`. + - ``coefficient`` -- an element of the :meth:`coefficient_ring` .. NOTE:: Either ``growth`` and ``coefficient`` or ``data`` have to be specified. - OUTPUT: - - An asymptotic expansion. + OUTPUT: an asymptotic expansion .. NOTE:: @@ -4581,9 +4476,7 @@ def variable_names(self): r""" Return the names of the variables. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -4645,9 +4538,7 @@ def B(expression, valid_from=0): is passed to ``valid_from``, then the lower bounds for all variables of the asymptotic expansion are set to this number - OUTPUT: - - A B-term + OUTPUT: a B-term EXAMPLES:: @@ -4669,11 +4560,11 @@ class AsymptoticRingFunctor(ConstructionFunctor): :class:`AsymptoticRing` or :doc:`growth_group` for details). - - ``default_prec`` -- ``None`` (default) or an integer. + - ``default_prec`` -- ``None`` (default) or integer - - ``category`` -- ``None`` (default) or a category. + - ``category`` -- ``None`` (default) or a category - - ``cls`` -- :class:`AsymptoticRing` (default) or a derived class. + - ``cls`` -- :class:`AsymptoticRing` (default) or a derived class EXAMPLES:: @@ -4739,9 +4630,7 @@ def _repr_(self) -> str: r""" Return a representation string of this functor. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -4766,11 +4655,9 @@ def _apply_functor(self, coefficient_ring): INPUT: - - ``base`` -- anything :class:`~sage.rings.asymptotic.growth_group.MonomialGrowthGroup` accepts. - - OUTPUT: + - ``base`` -- anything :class:`~sage.rings.asymptotic.growth_group.MonomialGrowthGroup` accepts - An :class:`AsymptoticRing`. + OUTPUT: an :class:`AsymptoticRing` EXAMPLES:: @@ -4818,11 +4705,9 @@ def merge(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A functor or ``None``. + OUTPUT: a functor or ``None`` EXAMPLES:: @@ -4914,11 +4799,9 @@ def __eq__(self, other) -> bool: INPUT: - - ``other`` -- a functor. + - ``other`` -- a functor - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -4943,11 +4826,9 @@ def __ne__(self, other) -> bool: INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A boolean. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/rings/asymptotic/asymptotics_multivariate_generating_functions.py b/src/sage/rings/asymptotic/asymptotics_multivariate_generating_functions.py index f5163d394a5..2147409845f 100644 --- a/src/sage/rings/asymptotic/asymptotics_multivariate_generating_functions.py +++ b/src/sage/rings/asymptotic/asymptotics_multivariate_generating_functions.py @@ -235,7 +235,7 @@ class FractionWithFactoredDenominator(RingElement): - ``numerator`` -- an element `p`; this can be of any ring from which parent's base has coercion in - - ``denominator_factored`` -- a list of the form + - ``denominator_factored`` -- list of the form `[(q_1, e_1), \ldots, (q_n, e_n)]`, where the `q_1, \ldots, q_n` are distinct irreducible elements of `R` and the `e_i` are positive integers @@ -369,9 +369,7 @@ def numerator(self): r""" Return the numerator of ``self``. - OUTPUT: - - The numerator. + OUTPUT: the numerator EXAMPLES:: @@ -439,9 +437,7 @@ def denominator_ring(self): r""" Return the ring of the denominator. - OUTPUT: - - A ring. + OUTPUT: a ring EXAMPLES:: @@ -467,9 +463,7 @@ def numerator_ring(self): r""" Return the ring of the numerator. - OUTPUT: - - A ring. + OUTPUT: a ring EXAMPLES:: @@ -494,9 +488,7 @@ def dimension(self): r""" Return the number of indeterminates of ``self.denominator_ring``. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -510,10 +502,10 @@ def dimension(self): sage: F.dimension() 2 """ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base R = self.denominator_ring - if is_PolynomialRing(R) or is_MPolynomialRing(R): + if isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base): return R.ngens() raise NotImplementedError('only polynomial rings are supported as base') @@ -521,9 +513,7 @@ def quotient(self): r""" Convert ``self`` into a quotient. - OUTPUT: - - An element. + OUTPUT: an element EXAMPLES:: @@ -546,9 +536,7 @@ def _repr_(self) -> str: r""" Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -575,9 +563,7 @@ def _eq_(self, other): - ``other`` -- an instance of :class:`FractionWithFactoredDenominator` - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean It can be assumed that ``self`` and ``other`` have the same parent. @@ -660,9 +646,7 @@ def _total_order_key_(self): denominators are equal and the numerator of ``A`` is less than that of ``B`` in their ring). - OUTPUT: - - A tuple. + OUTPUT: a tuple EXAMPLES:: @@ -720,9 +704,7 @@ def univariate_decomposition(self): factorization of the denominator. This gives a speed up for non-small instances. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` EXAMPLES:: @@ -910,9 +892,7 @@ def nullstellensatz_decomposition(self): Recursive. Only works for multivariate ``self``. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` EXAMPLES:: @@ -976,9 +956,7 @@ def algebraic_dependence_certificate(self): ``self.denominator_ring.base_ring()`` that has ``m = len(self.denominator_factored())`` indeterminates. - OUTPUT: - - An ideal. + OUTPUT: an ideal EXAMPLES:: @@ -1088,9 +1066,7 @@ def algebraic_dependence_decomposition(self, whole_and_parts=True): The algorithm used comes from [Rai2012]_. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` EXAMPLES:: @@ -1211,9 +1187,7 @@ def leinartas_decomposition(self): The algorithm used comes from [Rai2012]_. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` EXAMPLES:: @@ -1317,9 +1291,7 @@ def cohomology_decomposition(self): The algorithm used here comes from the proof of Theorem 17.4 of [AY1983]_. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` EXAMPLES:: @@ -1444,9 +1416,7 @@ def asymptotic_decomposition(self, alpha, asy_var=None): respect to which to compute asymptotics; if ``None`` is given, we set ``asy_var = var('r')`` - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` The output results from a Leinartas decomposition followed by a cohomology decomposition. @@ -1542,20 +1512,19 @@ def asymptotics(self, p, alpha, N, asy_var=None, numerical=0, INPUT: - - ``p`` -- a dictionary with keys that can be coerced to equal + - ``p`` -- dictionary with keys that can be coerced to equal ``self.denominator_ring.gens()`` - - ``alpha`` -- a tuple of length ``self.dimension()`` of - positive integers or, if `p` is a smooth point, - possibly of symbolic variables - - ``N`` -- a positive integer + - ``alpha`` -- tuple of length ``self.dimension()`` of positive + integers or, if `p` is a smooth point, possibly of symbolic variables + - ``N`` -- positive integer - ``asy_var`` -- (default: ``None``) a symbolic variable for the - asymptotic expansion; if ``none`` is given, then - ``var('r')`` will be assigned - - ``numerical`` -- (default: 0) a natural number; - if ``numerical`` is greater than 0, then return a numerical - approximation of `F_{r \alpha}` with ``numerical`` digits of - precision; otherwise return exact values - - ``verbose`` -- (default: ``False``) print the current state of + asymptotic expansion; if ``none`` is given, then ``var('r')`` will be + assigned + - ``numerical`` -- (default: 0) a natural number; if ``numerical`` is + greater than 0, then return a numerical approximation of + `F_{r \alpha}` with ``numerical`` digits of precision; otherwise + return exact values + - ``verbose`` -- boolean (default: ``False``); print the current state of the algorithm OUTPUT: @@ -1677,29 +1646,26 @@ def asymptotics_smooth(self, p, alpha, N, asy_var, coordinate=None, INPUT: - - ``p`` -- a dictionary with keys that can be coerced to equal + - ``p`` -- dictionary with keys that can be coerced to equal ``self.denominator_ring.gens()`` - - ``alpha`` -- a tuple of length ``d = self.dimension()`` of - positive integers or, if `p` is a smooth point, - possibly of symbolic variables - - ``N`` -- a positive integer - - ``asy_var`` -- (optional; default: ``None``) a symbolic variable; - the variable of the asymptotic expansion, - if none is given, ``var('r')`` will be assigned - - ``coordinate`` -- (optional; default: ``None``) an integer in - `\{0, \ldots, d-1\}` indicating a convenient coordinate to base - the asymptotic calculations on; if ``None`` is assigned, then - choose ``coordinate=d-1`` - - ``numerical`` -- (optional; default: 0) a natural number; - if numerical is greater than 0, then return a numerical approximation - of the Maclaurin ray coefficients of ``self`` with ``numerical`` - digits of precision; otherwise return exact values - - ``verbose`` -- (default: ``False``) print the current state of - the algorithm - - OUTPUT: + - ``alpha`` -- tuple of length ``d = self.dimension()`` of positive + integers or, if `p` is a smooth point, possibly of symbolic variables + - ``N`` -- positive integer + - ``asy_var`` -- (default: ``None``) a symbolic variable; the variable + of the asymptotic expansion, if none is given, ``var('r')`` will be + assigned + - ``coordinate`` -- (default: ``None``) an integer in + `\{0, \ldots, d-1\}` indicating a convenient coordinate to base the + asymptotic calculations on; if ``None`` is assigned, then choose + ``coordinate=d-1`` + - ``numerical`` -- (default: 0) a natural number; if numerical is + greater than 0, then return a numerical approximation of the + Maclaurin ray coefficients of ``self`` with ``numerical`` digits of + precision; otherwise return exact values + - ``verbose`` -- boolean (default: ``False``); print the current state + of the algorithm - The asymptotic expansion. + OUTPUT: the asymptotic expansion EXAMPLES:: @@ -2055,29 +2021,26 @@ def asymptotics_multiple(self, p, alpha, N, asy_var, coordinate=None, INPUT: - - ``p`` -- a dictionary with keys that can be coerced to equal + - ``p`` -- dictionary with keys that can be coerced to equal ``self.denominator_ring.gens()`` - - ``alpha`` -- a tuple of length ``d = self.dimension()`` of - positive integers or, if `p` is a smooth point, - possibly of symbolic variables - - ``N`` -- a positive integer - - ``asy_var`` -- (optional; default: ``None``) a symbolic variable; - the variable of the asymptotic expansion, - if none is given, ``var('r')`` will be assigned - - ``coordinate`` -- (optional; default: ``None``) an integer in - `\{0, \ldots, d-1\}` indicating a convenient coordinate to base - the asymptotic calculations on; if ``None`` is assigned, then - choose ``coordinate=d-1`` - - ``numerical`` -- (optional; default: 0) a natural number; - if numerical is greater than 0, then return a numerical approximation - of the Maclaurin ray coefficients of ``self`` with ``numerical`` - digits of precision; otherwise return exact values - - ``verbose`` -- (default: ``False``) print the current state of + - ``alpha`` -- tuple of length ``d = self.dimension()`` of positive + integers or, if `p` is a smooth point, possibly of symbolic variables + - ``N`` -- positive integer + - ``asy_var`` -- (default: ``None``) a symbolic variable; the variable + of the asymptotic expansion, if none is given, ``var('r')`` will be + assigned + - ``coordinate`` -- (default: ``None``) an integer in + `\{0, \ldots, d-1\}` indicating a convenient coordinate to base the + asymptotic calculations on; if ``None`` is assigned, then choose + ``coordinate=d-1`` + - ``numerical`` -- (default: 0) a natural number; if numerical is + greater than 0, then return a numerical approximation of the + Maclaurin ray coefficients of ``self`` with ``numerical`` digits of + precision. Otherwise return exact values. + - ``verbose`` -- boolean (default: ``False``); print the current state of the algorithm - OUTPUT: - - The asymptotic expansion. + OUTPUT: the asymptotic expansion EXAMPLES:: @@ -2357,9 +2320,9 @@ def _crit_cone_combo(self, p, alpha, coordinate=None): INPUT: - - ``p`` -- a dictionary with keys that can be coerced to equal + - ``p`` -- dictionary with keys that can be coerced to equal ``self.denominator_ring.gens()`` - - ``alpha`` -- a list of rationals + - ``alpha`` -- list of rationals OUTPUT: @@ -2426,12 +2389,10 @@ def grads(self, p): INPUT: - - ``p`` -- (optional; default: ``None``) a dictionary whose keys are + - ``p`` -- (default: ``None``) a dictionary whose keys are the generators of ``self.denominator_ring`` - OUTPUT: - - A list. + OUTPUT: list EXAMPLES:: @@ -2476,12 +2437,10 @@ def log_grads(self, p): INPUT: - - ``p`` -- (optional; default: ``None``) a dictionary whose keys + - ``p`` -- (default: ``None``) a dictionary whose keys are the generators of ``self.denominator_ring`` - OUTPUT: - - A list. + OUTPUT: list EXAMPLES:: @@ -2521,13 +2480,11 @@ def critical_cone(self, p, coordinate=None): INPUT: - - ``p`` -- a dictionary with keys that can be coerced to equal + - ``p`` -- dictionary with keys that can be coerced to equal ``self.denominator_ring.gens()`` and values in a field - - ``coordinate`` -- (optional; default: ``None``) a natural number + - ``coordinate`` -- (default: ``None``) a natural number - OUTPUT: - - A list of vectors. + OUTPUT: list of vectors This list of vectors generate the critical cone of ``p`` and the cone itself, which is ``None`` if the values of ``p`` don't lie in @@ -2578,7 +2535,7 @@ def critical_cone(self, p, coordinate=None): def is_convenient_multiple_point(self, p): r""" - Tests if ``p`` is a convenient multiple point of ``self``. + Test if ``p`` is a convenient multiple point of ``self``. In case ``p`` is a convenient multiple point, ``verdict = True`` and ``comment`` is a string stating which variables it's convenient to use. @@ -2589,7 +2546,7 @@ def is_convenient_multiple_point(self, p): INPUT: - - ``p`` -- a dictionary with keys that can be coerced to equal + - ``p`` -- dictionary with keys that can be coerced to equal ``self.denominator_ring.gens()`` OUTPUT: @@ -2671,9 +2628,7 @@ def singular_ideal(self): then the output is the ideal of the singular locus (which is a variety) of the variety of `H`. - OUTPUT: - - An ideal. + OUTPUT: an ideal EXAMPLES:: @@ -2708,12 +2663,10 @@ def smooth_critical_ideal(self, alpha): INPUT: - - ``alpha`` -- a tuple of positive integers and/or symbolic entries + - ``alpha`` -- tuple of positive integers and/or symbolic entries of length ``self.denominator_ring.ngens()`` - OUTPUT: - - An ideal. + OUTPUT: an ideal EXAMPLES:: @@ -2773,11 +2726,11 @@ def maclaurin_coefficients(self, multi_indices, numerical=0): INPUT: - - ``multi_indices`` -- a list of tuples of positive integers, where + - ``multi_indices`` -- list of tuples of positive integers, where each tuple has length ``self.dimension()`` - - ``numerical`` -- (optional; default: 0) a natural number; if - positive, return numerical approximations of coefficients with - ``numerical`` digits of accuracy + - ``numerical`` -- (default: 0) a natural number; if positive, return + numerical approximations of coefficients with ``numerical`` digits of + accuracy OUTPUT: @@ -2876,14 +2829,12 @@ def relative_error(self, approx, alpha, interval, exp_scale=Integer(1), - ``approx`` -- an individual or list of symbolic expressions in one variable - - ``alpha`` -- a list of positive integers of length + - ``alpha`` -- list of positive integers of length ``self.denominator_ring.ngens()`` - - ``interval`` -- a list of positive integers - - ``exp_scale`` -- (optional; default: 1) a number + - ``interval`` -- list of positive integers + - ``exp_scale`` -- (default: 1) a number - OUTPUT: - - A list of tuples with properties described below. + OUTPUT: list of tuples with properties described below This outputs a list whose entries are a tuple ``(r*alpha, a_r, b_r, err_r)`` for ``r`` in ``interval``. @@ -2953,7 +2904,7 @@ def relative_error(self, approx, alpha, interval, exp_scale=Integer(1), def _add_(left, right): r""" - Returns the sum of ``left`` with ``right``. + Return the sum of ``left`` with ``right``. INPUT: @@ -2961,9 +2912,7 @@ def _add_(left, right): - ``right`` -- the right summand - OUTPUT: - - The sum as a new element. + OUTPUT: the sum as a new element EXAMPLES:: @@ -2980,7 +2929,7 @@ def _add_(left, right): def _mul_(left, right): r""" - Returns the product of ``left`` with ``right``. + Return the product of ``left`` with ``right``. INPUT: @@ -2988,9 +2937,7 @@ def _mul_(left, right): - ``right`` -- the right factor - OUTPUT: - - The product as a new element. + OUTPUT: the product as a new element EXAMPLES:: @@ -3085,9 +3032,7 @@ def _repr_(self) -> str: r""" Return a representation. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -3102,11 +3047,9 @@ def _repr_(self) -> str: def base_ring(self): r""" - Returns the base ring. - - OUTPUT: + Return the base ring. - A ring. + OUTPUT: a ring EXAMPLES:: @@ -3124,7 +3067,7 @@ def base_ring(self): def _element_constructor_(self, *args, **kwargs): r""" - Returns an element of this ring. + Return an element of this ring. See :class:`FractionWithFactoredDenominator` for details. @@ -3222,9 +3165,9 @@ def _element_constructor_(self, *args, **kwargs): p = numerator q = R(denominator) - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing - if is_PolynomialRing(R) or is_MPolynomialRing(R): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base + if isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base): if not R(q).is_unit(): # Factor denominator try: @@ -3247,15 +3190,13 @@ def _element_constructor_(self, *args, **kwargs): def _coerce_map_from_(self, P): r""" - Checks if there is a coercion from the given parent. + Check if there is a coercion from the given parent. INPUT: - ``P`` -- a parent - OUTPUT: - - ``True`` if there is a coercion, otherwise ``False`` or ``None``. + OUTPUT: ``True`` if there is a coercion, otherwise ``False`` or ``None`` TESTS:: @@ -3292,9 +3233,9 @@ def _coerce_map_from_(self, P): from sage.rings.fraction_field import FractionField_generic if isinstance(P, FractionField_generic): B = P.base() - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing - if is_PolynomialRing(B) or is_MPolynomialRing(B): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base + if isinstance(B, PolynomialRing_general) or isinstance(B, MPolynomialRing_base): if self.base().has_coerce_map_from(B): return True @@ -3303,11 +3244,7 @@ def _coerce_map_from_(self, P): def _an_element_(self): r""" - Returns an element. - - OUTPUT: - - An element. + Return an element. TESTS:: @@ -3339,9 +3276,7 @@ def __repr__(self) -> str: r""" Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3359,9 +3294,7 @@ def __eq__(self, other) -> bool: r""" Return ``True`` if ``self`` is equal to ``other``. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -3385,9 +3318,7 @@ def __ne__(self, other) -> bool: r""" Return ``True`` if ``self`` is not equal to ``other``. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -3410,9 +3341,7 @@ def denominator_ring(self): r""" Return the polynomial ring of the denominators of ``self``. - OUTPUT: - - A ring or ``None`` if the list is empty. + OUTPUT: a ring or ``None`` if the list is empty EXAMPLES:: @@ -3437,9 +3366,7 @@ def whole_and_parts(self): Rewrite ``self`` as a sum of a (possibly zero) polynomial followed by reduced rational expressions. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` Only useful for multivariate decompositions. @@ -3494,9 +3421,7 @@ def _combine_like_terms_(self): Combine terms in ``self`` with the same denominator. Only useful for multivariate decompositions. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominatorSum`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominatorSum` EXAMPLES:: @@ -3549,9 +3474,7 @@ def sum(self): r""" Return the sum of the elements in ``self``. - OUTPUT: - - An instance of :class:`FractionWithFactoredDenominator`. + OUTPUT: an instance of :class:`FractionWithFactoredDenominator` EXAMPLES:: @@ -3622,21 +3545,21 @@ def diff_prod(f_derivs, u, g, X, interval, end, uderivs, atc): INPUT: - - ``f_derivs`` -- a dictionary whose keys are all tuples of the form + - ``f_derivs`` -- dictionary whose keys are all tuples of the form ``s + end``, where ``s`` is a sequence of variables from ``X`` whose length lies in ``interval``, and whose values are the derivatives of a function `f` evaluated at `c` - ``u`` -- a callable symbolic function - ``g`` -- an expression or callable symbolic function - - ``X`` -- a list of symbolic variables - - ``interval`` -- a list of positive integers + - ``X`` -- list of symbolic variables + - ``interval`` -- list of positive integers Call the first and last values `n` and `nn`, respectively - ``end`` -- a possibly empty list of repetitions of the variable ``z``, where ``z`` is the last element of ``X`` - - ``uderivs`` -- a dictionary whose keys are the symbolic + - ``uderivs`` -- dictionary whose keys are the symbolic derivatives of order 0 to order `n-1` of ``u`` evaluated at `c` and whose values are the corresponding derivatives evaluated at `c` - - ``atc`` -- a dictionary whose keys are the keys of `c` and all + - ``atc`` -- dictionary whose keys are the keys of `c` and all the symbolic derivatives of order 0 to order `nn` of ``g`` evaluated `c` and whose values are the corresponding derivatives evaluated at `c` @@ -3712,7 +3635,7 @@ def permutation_sign(s, u): INPUT: - ``s`` -- a sublist of ``u`` - - ``u`` -- a list + - ``u`` -- list OUTPUT: @@ -3756,7 +3679,7 @@ def subs_all(f, sub, simplify=False): - ``f`` -- an individual or list of symbolic expressions or dictionaries - ``sub`` -- an individual or list of dictionaries - - ``simplify`` -- (default: ``False``) boolean; set to ``True`` to + - ``simplify`` -- boolean (default: ``False``); set to ``True`` to simplify the result OUTPUT: @@ -3839,17 +3762,15 @@ def diff_all(f, V, n, ending=[], sub=None, sub_final=None, INPUT: - ``f`` -- an individual or list of `\mathcal{C}^{n+1}` functions - - ``V`` -- a list of variables occurring in `f` + - ``V`` -- list of variables occurring in `f` - ``n`` -- a natural number - - ``ending`` -- a list of variables in `V` + - ``ending`` -- list of variables in `V` - ``sub`` -- an individual or list of dictionaries - ``sub_final`` -- an individual or list of dictionaries - ``rekey`` -- a callable symbolic function in `V` or list thereof - ``zero_order`` -- a natural number - OUTPUT: - - The dictionary ``{s_1:deriv_1, ..., sr:deriv_r}``. + OUTPUT: the dictionary ``{s_1:deriv_1, ..., sr:deriv_r}`` Here ``s_1, ..., s_r`` is a listing of all nondecreasing sequences of length 1 up to length `n` over the @@ -3987,8 +3908,8 @@ def diff_op(A, B, AB_derivs, V, M, r, N): - ``A`` -- a single or length ``r`` list of symbolic functions in the variables ``V`` - - ``B`` -- a symbolic function in the variables ``V``. - - ``AB_derivs`` -- a dictionary whose keys are the (symbolic) + - ``B`` -- a symbolic function in the variables ``V`` + - ``AB_derivs`` -- dictionary whose keys are the (symbolic) derivatives of ``A[0], ..., A[r-1]`` up to order ``2 * N-2`` and the (symbolic) derivatives of ``B`` up to order ``2 * N``; the values of the dictionary are complex numbers that are @@ -3998,9 +3919,7 @@ def diff_op(A, B, AB_derivs, V, M, r, N): length of ``V`` - ``r``, ``N`` -- natural numbers - OUTPUT: - - A dictionary. + OUTPUT: a dictionary The output is a dictionary whose keys are natural number tuples of the form @@ -4081,8 +4000,8 @@ def diff_seq(V, s): INPUT: - - ``V`` -- a list - - ``s`` -- a list of tuples of natural numbers in the interval + - ``V`` -- list + - ``s`` -- list of tuples of natural numbers in the interval ``range(len(V))`` OUTPUT: @@ -4124,8 +4043,8 @@ def diff_op_simple(A, B, AB_derivs, x, v, a, N): INPUT: - - ``A``, ``B`` -- Symbolic functions in the variable ``x`` - - ``AB_derivs`` -- a dictionary whose keys are the (symbolic) + - ``A``, ``B`` -- symbolic functions in the variable ``x`` + - ``AB_derivs`` -- dictionary whose keys are the (symbolic) derivatives of ``A`` up to order ``2 * N`` if ``v`` is even or ``N`` if ``v`` is odd and the (symbolic) derivatives of ``B`` up to order ``2 * N + v`` if ``v`` is even or ``N + v`` @@ -4135,9 +4054,7 @@ def diff_op_simple(A, B, AB_derivs, x, v, a, N): - ``a`` -- a complex number - ``v``, ``N`` -- natural numbers - OUTPUT: - - A dictionary. + OUTPUT: a dictionary The output is a dictionary whose keys are natural number pairs of the form `(k, l)`, @@ -4188,7 +4105,7 @@ def direction(v, coordinate=None): INPUT: - ``v`` -- a vector - - ``coordinate`` -- (optional; default: ``None``) an index for ``v`` + - ``coordinate`` -- (default: ``None``) an index for ``v`` EXAMPLES:: diff --git a/src/sage/rings/asymptotic/growth_group.py b/src/sage/rings/asymptotic/growth_group.py index 1d7d3049405..cf9cf74ca70 100644 --- a/src/sage/rings/asymptotic/growth_group.py +++ b/src/sage/rings/asymptotic/growth_group.py @@ -259,10 +259,10 @@ class Variable(CachedRepresentation, SageObject): e.g. ``log(x)^ZZ``: ``var`` is then used to specify the variable `x`. - ``latex_name`` -- (default: ``None``) if specified, then this string - will be used as LaTeX-representation of ``var``. + will be used as LaTeX-representation of ``var`` - ``ignore`` -- (default: ``None``) a tuple (or other iterable) - of strings which are not variables. + of strings which are not variables TESTS:: @@ -404,11 +404,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- another variable. + - ``other`` -- another variable - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -426,11 +424,9 @@ def __ne__(self, other): INPUT: - - ``other`` -- another variable. - - OUTPUT: + - ``other`` -- another variable - A boolean. + OUTPUT: boolean TESTS:: @@ -446,9 +442,7 @@ def _repr_(self): r""" Return a representation string of this variable. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -462,9 +456,7 @@ def _latex_(self): r""" Return a LaTeX-representation string of this variable. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -482,9 +474,7 @@ def variable_names(self): r""" Return the names of the variables. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -500,9 +490,7 @@ def is_monomial(self): r""" Return whether this is a monomial variable. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -521,11 +509,9 @@ def extract_variable_names(s): INPUT: - - ``s`` -- a string. - - OUTPUT: + - ``s`` -- string - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -601,11 +587,9 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. + - ``rules`` -- dictionary - OUTPUT: - - An object. + OUTPUT: an object TESTS:: @@ -653,7 +637,7 @@ class PartialConversionValueError(ValueError): """ def __init__(self, element, *args, **kwds): r""" - See :class:`PartialConversionValueError` for more information. + See :exc:`PartialConversionValueError` for more information. TESTS:: @@ -679,9 +663,9 @@ class PartialConversionElement(SageObject): - ``raw_element`` -- an object A :class:`PartialConversionElement` is an element ``growth_group(raw_element)`` - which usually appears in conjunction with :class:`PartialConversionValueError`. + which usually appears in conjunction with :exc:`PartialConversionValueError`. In this case, it was to possible to create that element, although - the conversion went partially well in the sense that a `raw_element`` + the conversion went partially well in the sense that a ``raw_element`` (e.g. an exponent for :class:`MonomialGrowthElement` or a base for :class:`ExponentialGrowthElement`) could be extracted. @@ -777,13 +761,7 @@ def _is_lt_one_(self): r""" Return whether this element is less than `1`. - INPUT: - - Nothing. - - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -809,9 +787,7 @@ def _log_(self, base=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - OUTPUT: - - A growth element. + OUTPUT: a growth element EXAMPLES:: @@ -926,7 +902,7 @@ def _log_factor_(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. @@ -1000,11 +976,9 @@ def _rpow_(self, base): INPUT: - - ``base`` -- an element. - - OUTPUT: + - ``base`` -- an element - A growth element. + OUTPUT: a growth element EXAMPLES:: @@ -1122,9 +1096,9 @@ class GenericGrowthElement(MultiplicativeGroupElement): INPUT: - - ``parent`` -- a :class:`GenericGrowthGroup`. + - ``parent`` -- a :class:`GenericGrowthGroup` - - ``raw_element`` -- an element from the base of the parent. + - ``raw_element`` -- an element from the base of the parent EXAMPLES:: @@ -1207,13 +1181,7 @@ def _repr_(self): r""" A representation string for this generic element. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1234,13 +1202,7 @@ def __hash__(self): r""" Return the hash of this element. - INPUT: - - Nothing. - - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -1257,7 +1219,7 @@ def _mul_(self, other): INPUT: - - ``other`` -- a :class:`GenericGrowthElement`. + - ``other`` -- a :class:`GenericGrowthElement` OUTPUT: @@ -1284,9 +1246,7 @@ def __invert__(self): r""" Return the inverse of this growth element. - OUTPUT: - - An instance of :class:`GenericGrowthElement`. + OUTPUT: an instance of :class:`GenericGrowthElement` TESTS:: @@ -1319,9 +1279,7 @@ def _eq_(self, other): - ``other`` -- a :class:`GenericGrowthElement` - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -1390,9 +1348,7 @@ def _lt_(self, other): - ``other`` -- a :class:`GenericGrowthElement` - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -1434,7 +1390,7 @@ def _log_factor_(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. @@ -1467,11 +1423,9 @@ def _rpow_element_(self, base): INPUT: - - ``base`` -- an element. - - OUTPUT: + - ``base`` -- an element - Nothing since a ``ValueError`` is raised in this generic method. + OUTPUT: nothing since a :exc:`ValueError` is raised in this generic method TESTS:: @@ -1491,13 +1445,7 @@ def factors(self): Return the atomic factors of this growth element. An atomic factor cannot be split further. - INPUT: - - Nothing. - - OUTPUT: - - A tuple of growth elements. + OUTPUT: a tuple of growth elements EXAMPLES:: @@ -1516,11 +1464,9 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. - - OUTPUT: + - ``rules`` -- dictionary - An object. + OUTPUT: an object TESTS:: @@ -1543,9 +1489,7 @@ def variable_names(self): r""" Return the names of the variables of this growth element. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -1585,11 +1529,11 @@ def _singularity_analysis_(self, var, zeta, precision): INPUT: - - ``var`` -- a string denoting the variable + - ``var`` -- string denoting the variable - ``zeta`` -- a number - - ``precision`` -- an integer + - ``precision`` -- integer OUTPUT: @@ -1617,14 +1561,12 @@ def _find_minimum_(self, valid_from): INPUT: - - ``valid_from`` -- a dictionary describing the range of the minimization: + - ``valid_from`` -- dictionary describing the range of the minimization: the keys are names of variables and the range is the intersection over the ranges where the absolute value of the variable designated by the key is at least the corresponding value - OUTPUT: - - A number + OUTPUT: a number TESTS:: @@ -1646,7 +1588,7 @@ class GenericGrowthGroup(UniqueRepresentation, Parent, WithLocals): INPUT: - ``base`` -- one of SageMath's parents, out of which the elements - get their data (``raw_element``). + get their data (``raw_element``) - ``category`` -- (default: ``None``) the category of the newly created growth group. It has to be a subcategory of ``Join of @@ -1693,7 +1635,7 @@ class GenericGrowthGroup(UniqueRepresentation, Parent, WithLocals): @staticmethod def __classcall__(cls, base, var=None, category=None, ignore_variables=None): r""" - Normalizes the input in order to ensure a unique + Normalize the input in order to ensure a unique representation. For more information see :class:`GenericGrowthGroup`. @@ -1787,9 +1729,7 @@ def _initial_category_(base): - ``base`` -- a SageMath parent - OUTPUT: - - A category or ``None``. + OUTPUT: a category or ``None`` TESTS:: @@ -1805,9 +1745,9 @@ def _initial_category_(base): # The following block can be removed once #19269 is fixed. from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general if base is ZZ or base is QQ or \ - is_PolynomialRing(base) and \ + isinstance(base, PolynomialRing_general) and \ (base.base_ring() is ZZ or base.base_ring() is QQ): return Posets() else: @@ -1882,7 +1822,6 @@ def __init__(self, base, var, category): Traceback (most recent call last): ... TypeError: x is not a valid base. - """ self._var_ = var super().__init__(category=category, base=base) @@ -1891,13 +1830,7 @@ def _repr_short_(self): r""" A short representation string of this abstract growth group. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1921,13 +1854,11 @@ def _repr_(self, condense=False): INPUT: - - ``condense`` -- (default: ``False``) if set, then a shorter - output is returned, e.g. the prefix-string ``Growth Group`` - is not show in this case. + - ``condense`` -- boolean (default: ``False``); if set, then a shorter + output is returned, e.g. the prefix-string ``Growth Group`` is not + shown in this case - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1949,13 +1880,7 @@ def __hash__(self): r""" Return the hash of this group. - INPUT: - - Nothing. - - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -2005,13 +1930,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -2035,11 +1954,9 @@ def _create_element_in_extension_(self, raw_element): INPUT: - - ``raw_element`` -- the element data. - - OUTPUT: + - ``raw_element`` -- the element data - An element. + OUTPUT: an element EXAMPLES:: @@ -2064,13 +1981,11 @@ def le(self, left, right): INPUT: - - ``left`` -- an element. - - - ``right`` -- an element. + - ``left`` -- an element - OUTPUT: + - ``right`` -- an element - A boolean. + OUTPUT: boolean .. NOTE:: @@ -2097,16 +2012,13 @@ def _element_constructor_(self, data, raw_element=None): INPUT: - - ``data`` -- an object representing the element to be - initialized. + - ``data`` -- an object representing the element to be initialized - ``raw_element`` -- (default: ``None``) if given, then this is directly passed to the element constructor (i.e., no conversion is performed). - OUTPUT: - - An element of this growth group. + OUTPUT: an element of this growth group .. NOTE:: @@ -2249,7 +2161,7 @@ def _convert_(self, data): INPUT: - - ``data`` -- an object. + - ``data`` -- an object OUTPUT: @@ -2313,9 +2225,7 @@ def _split_raw_element_(raw_element): - ``raw_element`` -- an object - OUTPUT: - - A pair of objects. + OUTPUT: a pair of objects .. NOTE:: @@ -2339,11 +2249,9 @@ def _coerce_map_from_(self, S): INPUT: - - ``S`` -- a parent. + - ``S`` -- a parent - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -2467,13 +2375,7 @@ def gens_monomial(self): Return a tuple containing monomial generators of this growth group. - INPUT: - - Nothing. - - OUTPUT: - - An empty tuple. + OUTPUT: an empty tuple .. NOTE:: @@ -2503,13 +2405,7 @@ def gens(self): r""" Return a tuple of all generators of this growth group. - INPUT: - - Nothing. - - OUTPUT: - - A tuple whose entries are growth elements. + OUTPUT: a tuple whose entries are growth elements EXAMPLES:: @@ -2528,11 +2424,9 @@ def gen(self, n=0): INPUT: - - ``n`` -- default: `0`. + - ``n`` -- (default: `0`) - OUTPUT: - - A :class:`MonomialGrowthElement`. + OUTPUT: a :class:`MonomialGrowthElement` EXAMPLES:: @@ -2555,13 +2449,7 @@ def ngens(self): r""" Return the number of generators (as a group) of this growth group. - INPUT: - - Nothing. - - OUTPUT: - - A Python integer. + OUTPUT: a Python integer EXAMPLES:: @@ -2584,9 +2472,7 @@ def variable_names(self): r""" Return the names of the variables of this growth group. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -2618,9 +2504,7 @@ def extended_by_non_growth_group(self): Extend to a cartesian product of this growth group and a suitable non growth group. - OUTPUT: - - A group group. + OUTPUT: a group group EXAMPLES:: @@ -2647,9 +2531,7 @@ def non_growth_group(self): r""" Return a non-growth group compatible with this growth group. - OUTPUT: - - A group group. + OUTPUT: a group group EXAMPLES:: @@ -2668,10 +2550,10 @@ class AbstractGrowthGroupFunctor(ConstructionFunctor): INPUT: - - ``var`` -- a string or list of strings (or anything else - :class:`Variable` accepts). + - ``var`` -- string or list of strings (or anything else :class:`Variable` + accepts) - - ``domain`` -- a category. + - ``domain`` -- a category EXAMPLES:: @@ -2716,9 +2598,7 @@ def _repr_(self): r""" Return a representation string of this functor. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -2734,11 +2614,9 @@ def merge(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A functor or ``None``. + OUTPUT: a functor or ``None`` EXAMPLES:: @@ -2759,11 +2637,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- a functor. + - ``other`` -- a functor - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -2783,11 +2659,9 @@ def __ne__(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -2816,7 +2690,7 @@ class DecreasingGrowthElementError(ValueError): """ def __init__(self, element, *args, **kwds): r""" - See :class:`DecreasingGrowthElementError` for more information. + See :exc:`DecreasingGrowthElementError` for more information. TESTS:: @@ -2837,9 +2711,9 @@ class MonomialGrowthElement(GenericGrowthElement): INPUT: - - ``parent`` -- a :class:`MonomialGrowthGroup`. + - ``parent`` -- a :class:`MonomialGrowthGroup` - - ``raw_element`` -- an element from the base ring of the parent. + - ``raw_element`` -- an element from the base ring of the parent This ``raw_element`` is the exponent of the created monomial growth element. @@ -2884,12 +2758,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. + - ``latex`` -- boolean (default: ``False``); if set, then LaTeX-output + is returned - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -2945,9 +2817,7 @@ def _latex_(self): r""" A LaTeX-representation string for this monomial growth element. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -2977,9 +2847,7 @@ def _mul_(self, other): - ``other`` -- a :class:`MonomialGrowthElement` - OUTPUT: - - The product as a :class:`MonomialGrowthElement`. + OUTPUT: the product as a :class:`MonomialGrowthElement` .. NOTE:: @@ -3005,13 +2873,7 @@ def __invert__(self): r""" Return the multiplicative inverse of this monomial growth element. - INPUT: - - Nothing. - - OUTPUT: - - The multiplicative inverse as a :class:`MonomialGrowthElement`. + OUTPUT: the multiplicative inverse as a :class:`MonomialGrowthElement` EXAMPLES:: @@ -3041,9 +2903,7 @@ def __pow__(self, exponent): valid right hand side of ``*`` with elements of the parent's base. - OUTPUT: - - The result of this exponentiation, a :class:`MonomialGrowthElement`. + OUTPUT: the result of this exponentiation, a :class:`MonomialGrowthElement` EXAMPLES:: @@ -3077,10 +2937,10 @@ def _log_factor_(self, base=None, locals=None): INPUT: - - ``base`` -- the base of the logarithm. If ``None`` - (default value) is used, the natural logarithm is taken. + - ``base`` -- the base of the logarithm. If ``None`` (default value) is + used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. @@ -3154,23 +3014,21 @@ def _rpow_element_(self, base, locals=None): INPUT: - - ``base`` -- an element. + - ``base`` -- an element - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - A growth element. + OUTPUT: a growth element .. NOTE:: The parent of the result can be different from the parent of this element. - A ``ValueError`` is raised if the calculation is not possible + A :exc:`ValueError` is raised if the calculation is not possible within this method. (Then the calling method should take care of the calculation.) @@ -3229,9 +3087,7 @@ def _lt_(self, other): - ``other`` -- a :class:`MonomialGrowthElement` - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -3254,13 +3110,10 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. - The neutral element of the group is replaced by the value - to key ``'_one_'``. + - ``rules`` -- dictionary; the neutral element of the group is replaced + by the value to key ``'_one_'`` - OUTPUT: - - An object. + OUTPUT: an object TESTS:: @@ -3296,11 +3149,11 @@ def _singularity_analysis_(self, var, zeta, precision): INPUT: - - ``var`` -- a string denoting the variable + - ``var`` -- string denoting the variable - ``zeta`` -- a number - - ``precision`` -- an integer + - ``precision`` -- integer OUTPUT: @@ -3366,14 +3219,12 @@ def _find_minimum_(self, valid_from): INPUT: - - ``valid_from`` -- a dictionary describing the range of the minimization: + - ``valid_from`` -- dictionary describing the range of the minimization: the keys are names of variables and the range is the intersection over the ranges where the absolute value of the variable designated by the key is at least the corresponding value - OUTPUT: - - A number + OUTPUT: a number TESTS:: @@ -3424,12 +3275,12 @@ class MonomialGrowthGroup(GenericGrowthGroup): INPUT: - ``base`` -- one of SageMath's parents, out of which the elements - get their data (``raw_element``). + get their data (``raw_element``) As monomials are represented by this group, the elements in ``base`` are the exponents of these monomials. - - ``var`` -- an object. + - ``var`` -- an object The string representation of ``var`` acts as a base of the monomials represented by this group. @@ -3483,13 +3334,7 @@ def _repr_short_(self): r""" A short representation string of this monomial growth group. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3517,7 +3362,7 @@ def _convert_(self, data): INPUT: - - ``data`` -- an object. + - ``data`` -- an object OUTPUT: @@ -3657,9 +3502,7 @@ def _split_raw_element_(raw_element): - ``raw_element`` -- an object - OUTPUT: - - A pair of objects. + OUTPUT: a pair of objects .. NOTE:: @@ -3681,13 +3524,7 @@ def gens_monomial(self): Return a tuple containing monomial generators of this growth group. - INPUT: - - Nothing. - - OUTPUT: - - A tuple containing elements of this growth group. + OUTPUT: a tuple containing elements of this growth group .. NOTE:: @@ -3714,13 +3551,7 @@ def gens_logarithmic(self): Return a tuple containing logarithmic generators of this growth group. - INPUT: - - Nothing. - - OUTPUT: - - A tuple containing elements of this growth group. + OUTPUT: a tuple containing elements of this growth group .. NOTE:: @@ -3777,17 +3608,15 @@ def factory(cls, exponential growth group; see :class:`MonomialGrowthGroup` for details. - - ``extend_by_non_growth_group`` -- a boolean (default ``False``). If set, then - the growth group consists of two parts, one part dealing with - the absolute values of the bases and one for their arguments. + - ``extend_by_non_growth_group`` -- boolean (default: ``False``); if + set, then the growth group consists of two parts, one part dealing + with the absolute values of the bases and one for their arguments. - - ``return_factors`` -- a boolean (default: ``False``). If set, + - ``return_factors`` -- boolean (default: ``False``); if set, then a tuple of the (cartesian) factors of this growth group - is returned. - - OUTPUT: + is returned - A growth group or tuple of growth groups. + OUTPUT: a growth group or tuple of growth groups EXAMPLES:: @@ -3830,9 +3659,7 @@ def non_growth_group(self): (with an imaginary group as base) compatible with this monomial growth group. - OUTPUT: - - A group group. + OUTPUT: a group group EXAMPLES:: @@ -3851,8 +3678,8 @@ class MonomialGrowthGroupFunctor(AbstractGrowthGroupFunctor): INPUT: - - ``var`` -- a string or list of strings (or anything else - :class:`Variable` accepts). + - ``var`` -- string or list of strings (or anything else + :class:`Variable` accepts) EXAMPLES:: @@ -3899,11 +3726,9 @@ def _apply_functor(self, base): INPUT: - - ``base`` -- anything :class:`MonomialGrowthGroup` accepts. - - OUTPUT: + - ``base`` -- anything :class:`MonomialGrowthGroup` accepts - A monomial growth group. + OUTPUT: a monomial growth group EXAMPLES:: @@ -3921,9 +3746,9 @@ class ExponentialGrowthElement(GenericGrowthElement): INPUT: - - ``parent`` -- an :class:`ExponentialGrowthGroup`. + - ``parent`` -- an :class:`ExponentialGrowthGroup` - - ``raw_element`` -- an element from the base ring of the parent. + - ``raw_element`` -- an element from the base ring of the parent This ``raw_element`` is the base of the created exponential growth element. @@ -3992,12 +3817,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -4049,9 +3872,7 @@ def _latex_(self): r""" A LaTeX-representation string for this exponential growth element. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -4092,9 +3913,7 @@ def _mul_(self, other): - ``other`` -- a :class:`ExponentialGrowthElement` - OUTPUT: - - The product as a :class:`ExponentialGrowthElement`. + OUTPUT: the product as a :class:`ExponentialGrowthElement` .. NOTE:: @@ -4120,13 +3939,7 @@ def __invert__(self): r""" Return the multiplicative inverse of this exponential growth element. - INPUT: - - Nothing. - - OUTPUT: - - The multiplicative inverse as a :class:`ExponentialGrowthElement`. + OUTPUT: the multiplicative inverse as a :class:`ExponentialGrowthElement` EXAMPLES:: @@ -4165,9 +3978,7 @@ def __pow__(self, exponent): on the right hand side of ``*`` with an elements of the parent's base. - OUTPUT: - - The result of this exponentiation as an :class:`ExponentialGrowthElement`. + OUTPUT: the result of this exponentiation as an :class:`ExponentialGrowthElement` EXAMPLES:: @@ -4209,7 +4020,7 @@ def _log_factor_(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. @@ -4264,9 +4075,7 @@ def _lt_(self, other): - ``other`` -- a :class:`ExponentialGrowthElement` - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -4297,13 +4106,10 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. - The neutral element of the group is replaced by the value - to key ``'_one_'``. + - ``rules`` -- dictionary; the neutral element of the group is replaced + by the value to key ``'_one_'`` - OUTPUT: - - An object. + OUTPUT: an object TESTS:: @@ -4341,12 +4147,12 @@ class ExponentialGrowthGroup(GenericGrowthGroup): INPUT: - ``base`` -- one of SageMath's parents, out of which the elements - get their data (``raw_element``). + get their data (``raw_element``) As exponential expressions are represented by this group, the elements in ``base`` are the bases of these exponentials. - - ``var`` -- an object. + - ``var`` -- an object The string representation of ``var`` acts as an exponent of the elements represented by this group. @@ -4426,13 +4232,7 @@ def _repr_short_(self): r""" A short representation string of this exponential growth group. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -4453,12 +4253,12 @@ def _repr_short_(self): def _convert_(self, data): r""" - Converts given ``data`` to something the constructor of the + Convert given ``data`` to something the constructor of the element class accepts (``raw_element``). INPUT: - - ``data`` -- an object. + - ``data`` -- an object OUTPUT: @@ -4578,9 +4378,7 @@ def _split_raw_element_(base): - ``raw_element`` -- an object - OUTPUT: - - A pair of objects. + OUTPUT: a pair of objects .. NOTE:: @@ -4719,13 +4517,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -4741,13 +4533,7 @@ def gens(self): Return a tuple of all generators of this exponential growth group. - INPUT: - - Nothing. - - OUTPUT: - - An empty tuple. + OUTPUT: an empty tuple EXAMPLES:: @@ -4794,17 +4580,15 @@ def factory(cls, exponential growth group; see :class:`ExponentialGrowthGroup` for details. - - ``extend_by_non_growth_group`` -- a boolean (default ``True``). If set, then - the growth group consists of two parts, one part dealing with - the absolute values of the bases and one for their arguments. + - ``extend_by_non_growth_group`` -- boolean (default: ``True``); if + set, then the growth group consists of two parts, one part dealing + with the absolute values of the bases and one for their arguments. - - ``return_factors`` -- a boolean (default: ``False``). If set, + - ``return_factors`` -- boolean (default: ``False``); if set, then a tuple of the (cartesian) factors of this growth group - is returned. - - OUTPUT: + is returned - A growth group or tuple of growth groups. + OUTPUT: a growth group or tuple of growth groups EXAMPLES:: @@ -4866,9 +4650,7 @@ def non_growth_group(self): (with an argument group, e.g. roots of unity, as base) compatible with this exponential growth group. - OUTPUT: - - A group group. + OUTPUT: a group group EXAMPLES:: @@ -4900,8 +4682,8 @@ class ExponentialGrowthGroupFunctor(AbstractGrowthGroupFunctor): INPUT: - - ``var`` -- a string or list of strings (or anything else - :class:`Variable` accepts). + - ``var`` -- string or list of strings (or anything else + :class:`Variable` accepts) EXAMPLES:: @@ -4948,11 +4730,9 @@ def _apply_functor(self, base): INPUT: - - ``base`` -- anything :class:`ExponentialGrowthGroup` accepts. + - ``base`` -- anything :class:`ExponentialGrowthGroup` accepts - OUTPUT: - - An exponential growth group. + OUTPUT: an exponential growth group EXAMPLES:: @@ -5011,9 +4791,7 @@ def _initial_category_(base): - ``base`` -- a SageMath parent - OUTPUT: - - Always the category of posets. + OUTPUT: always the category of posets TESTS:: @@ -5129,11 +4907,9 @@ def _apply_functor(self, base): INPUT: - - ``base`` -- anything :class:`ExponentialNonGrowthGroup` accepts. + - ``base`` -- anything :class:`ExponentialNonGrowthGroup` accepts - OUTPUT: - - An exponential argument growth group. + OUTPUT: an exponential argument growth group EXAMPLES:: @@ -5211,11 +4987,9 @@ def _apply_functor(self, base): INPUT: - - ``base`` -- anything :class:`MonomialNonGrowthGroup` accepts. - - OUTPUT: + - ``base`` -- anything :class:`MonomialNonGrowthGroup` accepts - An exponential argument growth group. + OUTPUT: an exponential argument growth group EXAMPLES:: @@ -5238,7 +5012,7 @@ class GrowthGroupFactory(UniqueFactory): INPUT: - - ``specification`` -- a string. + - ``specification`` -- string - keyword arguments are passed on to the growth group constructor. @@ -5246,9 +5020,7 @@ class GrowthGroupFactory(UniqueFactory): ``ignore_variables=('e',)`` (to ignore ``e`` as a variable name) is used. - OUTPUT: - - An asymptotic growth group. + OUTPUT: an asymptotic growth group .. NOTE:: diff --git a/src/sage/rings/asymptotic/growth_group_cartesian.py b/src/sage/rings/asymptotic/growth_group_cartesian.py index 27a934e69a5..0bdb3d4a1eb 100644 --- a/src/sage/rings/asymptotic/growth_group_cartesian.py +++ b/src/sage/rings/asymptotic/growth_group_cartesian.py @@ -100,7 +100,7 @@ class CartesianProductFactory(UniqueFactory): INPUT: - - ``growth_groups`` -- a tuple (or other iterable) of growth groups. + - ``growth_groups`` -- tuple (or other iterable) of growth groups - ``order`` -- (default: ``None``) if specified, then this order is taken for comparing two Cartesian product elements. If ``order`` is @@ -325,9 +325,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -357,11 +355,9 @@ def _create_element_in_extension_(self, element): INPUT: - - ``element`` -- a tuple. - - OUTPUT: + - ``element`` -- tuple - An element. + OUTPUT: an element EXAMPLES:: @@ -396,8 +392,7 @@ def _create_element_in_extension_(self, element): def _element_constructor_(self, data): r""" - Converts the given object to an element of this Cartesian - product. + Convert the given object to an element of this Cartesian product. EXAMPLES:: @@ -521,13 +516,7 @@ def _repr_short_(self): A short (shorter than :meth:`._repr_`) representation string for this Cartesian product of growth groups. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -547,11 +536,9 @@ def _convert_factors_(self, factors): INPUT: - - ``factors`` -- a tuple or other iterable. - - OUTPUT: + - ``factors`` -- tuple or other iterable - An element of this Cartesian product. + OUTPUT: an element of this Cartesian product EXAMPLES:: @@ -614,13 +601,11 @@ def cartesian_injection(self, factor, element): INPUT: - - ``factor`` -- a growth group (a factor of this Cartesian product). - - - ``element`` -- an element of ``factor``. + - ``factor`` -- a growth group (a factor of this Cartesian product) - OUTPUT: + - ``element`` -- an element of ``factor`` - An element of this Cartesian product. + OUTPUT: an element of this Cartesian product TESTS:: @@ -638,11 +623,9 @@ def _coerce_map_from_(self, S): INPUT: - - ``S`` -- a parent. + - ``S`` -- a parent - OUTPUT: - - A boolean. + OUTPUT: boolean TESTS:: @@ -855,13 +838,7 @@ def gens_monomial(self): r""" Return a tuple containing monomial generators of this growth group. - INPUT: - - Nothing. - - OUTPUT: - - A tuple containing elements of this growth group. + OUTPUT: a tuple containing elements of this growth group .. NOTE:: @@ -890,9 +867,7 @@ def variable_names(self): r""" Return the names of the variables. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -917,12 +892,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -948,9 +921,7 @@ def _latex_(self): r""" A representation string for this Cartesian product element. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -971,11 +942,9 @@ def __pow__(self, exponent): INPUT: - - ``exponent`` -- a number. - - OUTPUT: + - ``exponent`` -- a number - A growth element. + OUTPUT: a growth element EXAMPLES:: @@ -999,13 +968,7 @@ def factors(self): Return the atomic factors of this growth element. An atomic factor cannot be split further and is not the identity (`1`). - INPUT: - - Nothing. - - OUTPUT: - - A tuple of growth elements. + OUTPUT: a tuple of growth elements EXAMPLES:: @@ -1053,13 +1016,14 @@ def _log_factor_(self, base=None, locals=None): INPUT: - - ``base`` -- the base of the logarithm. If ``None`` - (default value) is used, the natural logarithm is taken. + - ``base`` -- the base of the logarithm; if ``None`` + (default value) is used, the natural logarithm is taken - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and + values: - - ``'log'`` -- value: a function. If not used, then the usual - :class:`log ` is taken. + - ``'log'`` -- value: a function; if not used, then the usual + :class:`log ` is taken OUTPUT: @@ -1103,23 +1067,20 @@ def try_create_growth(g): def _rpow_element_(self, base): r""" - Return an element which is the power of ``base`` to this - element. + Return an element which is the power of ``base`` to this element. INPUT: - - ``base`` -- an element. - - OUTPUT: + - ``base`` -- an element - A growth element. + OUTPUT: a growth element .. NOTE:: The parent of the result can be different from the parent of this element. - A ``ValueError`` is raised if the calculation is not possible + A :exc:`ValueError` is raised if the calculation is not possible within this method. (Then the calling method should take care of the calculation.) @@ -1146,13 +1107,7 @@ def exp(self): r""" The exponential of this element. - INPUT: - - Nothing. - - OUTPUT: - - A growth element. + OUTPUT: a growth element EXAMPLES:: @@ -1190,9 +1145,7 @@ def __invert__(self): r""" Return the multiplicative inverse of this Cartesian product. - OUTPUT: - - A growth element. + OUTPUT: a growth element .. NOTE:: @@ -1216,13 +1169,10 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. - The neutral element of the group is replaced by the value - to key ``'_one_'``. + - ``rules`` -- dictionary; the neutral element of the group is + replaced by the value to key ``'_one_'`` - OUTPUT: - - An object. + OUTPUT: an object TESTS:: @@ -1264,11 +1214,11 @@ def _singularity_analysis_(self, var, zeta, precision): INPUT: - - ``var`` -- a string denoting the variable + - ``var`` -- string denoting the variable - ``zeta`` -- a number - - ``precision`` -- an integer + - ``precision`` -- integer OUTPUT: @@ -1355,9 +1305,7 @@ def variable_names(self): r""" Return the names of the variables of this growth element. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: diff --git a/src/sage/rings/asymptotic/misc.py b/src/sage/rings/asymptotic/misc.py index c33ea3e5a94..827a9ded81c 100644 --- a/src/sage/rings/asymptotic/misc.py +++ b/src/sage/rings/asymptotic/misc.py @@ -38,11 +38,9 @@ def repr_short_to_parent(s): INPUT: - - ``s`` -- a string, short representation of a parent. + - ``s`` -- string; short representation of a parent - OUTPUT: - - A parent. + OUTPUT: a parent The possible short representations are shown in the examples below. @@ -108,11 +106,9 @@ def parent_to_repr_short(P): INPUT: - - ``P`` -- a parent. + - ``P`` -- a parent - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -149,8 +145,8 @@ def parent_to_repr_short(P): from sage.rings.real_mpfi import RIF from sage.rings.real_mpfr import RR from sage.symbolic.ring import SR - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base from sage.rings.power_series_ring import is_PowerSeriesRing def abbreviate(P): @@ -168,7 +164,7 @@ def abbreviate(P): pass raise ValueError('Cannot abbreviate %s.' % (P,)) - poly = is_PolynomialRing(P) or is_MPolynomialRing(P) + poly = isinstance(P, PolynomialRing_general) or isinstance(P, MPolynomialRing_base) from sage.rings import multi_power_series_ring power = is_PowerSeriesRing(P) or \ multi_power_series_ring.is_MPowerSeriesRing(P) @@ -198,18 +194,16 @@ def split_str_by_op(string, op, strip_parentheses=True): INPUT: - - ``string`` -- a string. + - ``string`` -- string - - ``op`` -- a string. This is used by + - ``op`` -- string; this is used by :python:`str.split `. Thus, if this is ``None``, then any whitespace string is a separator and empty strings are removed from the result. - - ``strip_parentheses`` -- (default: ``True``) a boolean. - - OUTPUT: + - ``strip_parentheses`` -- boolean (default: ``True``) - A tuple of strings. + OUTPUT: a tuple of strings TESTS:: @@ -309,18 +303,16 @@ def repr_op(left, op, right=None, latex=False): INPUT: - - ``left`` -- an element. - - - ``op`` -- a string. + - ``left`` -- an element - - ``right`` -- an element. + - ``op`` -- string - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. + - ``right`` -- an element - OUTPUT: + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - A string. + OUTPUT: string EXAMPLES:: @@ -368,13 +360,11 @@ def combine_exceptions(e, *f): INPUT: - - ``e`` -- an exception. + - ``e`` -- an exception - - ``*f`` -- exceptions. - - OUTPUT: + - ``*f`` -- exceptions - An exception. + OUTPUT: an exception EXAMPLES:: @@ -416,14 +406,11 @@ def substitute_raise_exception(element, e): INPUT: - - ``element`` -- an element. + - ``element`` -- an element - - ``e`` -- an exception which is included in the raised error - message. + - ``e`` -- an exception which is included in the raised error message - OUTPUT: - - Raise an exception of the same type as ``e``. + OUTPUT: raise an exception of the same type as ``e`` TESTS:: @@ -445,9 +432,9 @@ def bidirectional_merge_overlapping(A, B, key=None): INPUT: - - ``A`` -- a list or tuple (type has to coincide with type of ``B``). + - ``A`` -- list or tuple (type has to coincide with type of ``B``) - - ``B`` -- a list or tuple (type has to coincide with type of ``A``). + - ``B`` -- list or tuple (type has to coincide with type of ``A``) - ``key`` -- (default: ``None``) a function. If ``None``, then the identity is used. This ``key``-function applied on an element @@ -578,9 +565,9 @@ def bidirectional_merge_sorted(A, B, key=None): INPUT: - - ``A`` -- a list or tuple (type has to coincide with type of ``B``). + - ``A`` -- list or tuple (type has to coincide with type of ``B``) - - ``B`` -- a list or tuple (type has to coincide with type of ``A``). + - ``B`` -- list or tuple (type has to coincide with type of ``A``) - ``key`` -- (default: ``None``) a function. If ``None``, then the identity is used. This ``key``-function applied on an element @@ -715,13 +702,11 @@ def log_string(element, base=None): INPUT: - - ``element`` -- an object. + - ``element`` -- an object - - ``base`` -- an object or ``None``. + - ``base`` -- an object or ``None`` - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -746,9 +731,7 @@ def strip_symbolic(expression): - ``expression`` -- an object - OUTPUT: - - An object. + OUTPUT: an object EXAMPLES:: @@ -790,9 +773,10 @@ def __init__(self, asymptotic_ring=None, var=None, exact_part=0): r""" INPUT: - - ``asymptotic_ring`` -- (default: ``None``) an :class:`AsymptoticRing` or ``None``. + - ``asymptotic_ring`` -- (default: ``None``) an :class:`AsymptoticRing` + or ``None`` - - ``var`` -- (default: ``None``) a string. + - ``var`` -- (default: ``None``) a string Either ``asymptotic_ring`` or ``var`` has to be specified. @@ -853,9 +837,10 @@ def __init__(self, asymptotic_ring=None, var=None, exact_part=0): r""" INPUT: - - ``asymptotic_ring`` -- (default: ``None``) an :class:`AsymptoticRing` or ``None``. + - ``asymptotic_ring`` -- (default: ``None``) an :class:`AsymptoticRing` + or ``None`` - - ``var`` -- (default: ``None``) a string. + - ``var`` -- (default: ``None``) string Either ``asymptotic_ring`` or ``var`` has to be specified. @@ -922,15 +907,15 @@ def transform_category(category, INPUT: - - ``category`` -- a category. + - ``category`` -- a category - - ``subcategory_mapping`` -- a list (or other iterable) of triples + - ``subcategory_mapping`` -- list (or other iterable) of triples ``(from, to, mandatory)``, where - ``from`` and ``to`` are categories and - ``mandatory`` is a boolean. - - ``axiom_mapping`` -- a list (or other iterable) of triples + - ``axiom_mapping`` -- list (or other iterable) of triples ``(from, to, mandatory)``, where - ``from`` and ``to`` are strings describing axioms and @@ -944,9 +929,7 @@ def transform_category(category, :class:`category of objects ` is used. - OUTPUT: - - A category. + OUTPUT: a category .. NOTE:: @@ -1136,9 +1119,7 @@ def default_locals(self): Return the default locals used in the :class:`~sage.rings.asymptotic.asymptotic_ring.AsymptoticRing`. - OUTPUT: - - A dictionary. + OUTPUT: a dictionary EXAMPLES:: @@ -1202,9 +1183,7 @@ def locals(self, locals=None): the default values) :class:`Locals` object is created and returned. - OUTPUT: - - A :class:`Locals` object. + OUTPUT: a :class:`Locals` object TESTS:: diff --git a/src/sage/rings/asymptotic/term_monoid.py b/src/sage/rings/asymptotic/term_monoid.py index e50b1e7409c..c16260d298e 100644 --- a/src/sage/rings/asymptotic/term_monoid.py +++ b/src/sage/rings/asymptotic/term_monoid.py @@ -17,11 +17,11 @@ implements the following types of terms: - :class:`OTerm` -- `O`-terms at infinity, see - :wikipedia:`Big_O_notation`. + :wikipedia:`Big_O_notation` - :class:`TermWithCoefficient` -- abstract base class for - asymptotic terms with coefficients. + asymptotic terms with coefficients - :class:`ExactTerm` -- this class represents a growth element - multiplied with some non-zero coefficient from a coefficient ring. + multiplied with some nonzero coefficient from a coefficient ring A characteristic property of asymptotic terms is that some terms are able to "absorb" other terms (see @@ -252,13 +252,11 @@ def absorption(left, right): INPUT: - - ``left`` -- an asymptotic term. + - ``left`` -- an asymptotic term - - ``right`` -- an asymptotic term. + - ``right`` -- an asymptotic term - OUTPUT: - - An asymptotic term or ``None``. + OUTPUT: an asymptotic term or ``None`` EXAMPLES:: @@ -298,13 +296,11 @@ def can_absorb(left, right): INPUT: - - ``left`` -- an asymptotic term. - - - ``right`` -- an asymptotic term. + - ``left`` -- an asymptotic term - OUTPUT: + - ``right`` -- an asymptotic term - A boolean. + OUTPUT: boolean .. NOTE:: @@ -332,9 +328,9 @@ class GenericTerm(MultiplicativeGroupElement): INPUT: - - ``parent`` -- the parent of the asymptotic term. + - ``parent`` -- the parent of the asymptotic term - - ``growth`` -- an asymptotic growth element. + - ``growth`` -- an asymptotic growth element EXAMPLES:: @@ -395,10 +391,6 @@ def construction(self): r""" Return a construction of this term. - INPUT: - - Nothing. - OUTPUT: A pair ``(cls, kwds)`` such that ``cls(**kwds)`` equals this term. @@ -432,11 +424,9 @@ def _mul_(self, other): INPUT: - - ``other`` -- an asymptotic term. - - OUTPUT: + - ``other`` -- an asymptotic term - A :class:`GenericTerm`. + OUTPUT: a :class:`GenericTerm` .. NOTE:: @@ -464,9 +454,7 @@ def __invert__(self): r""" Invert this term. - OUTPUT: - - A :class:`GenericTerm`. + OUTPUT: a :class:`GenericTerm` TESTS:: @@ -500,7 +488,7 @@ def __pow__(self, exponent): INPUT: - - ``exponent`` -- an element. + - ``exponent`` -- an element OUTPUT: @@ -532,11 +520,9 @@ def _calculate_pow_test_zero_(self, exponent): INPUT: - - ``exponent`` -- an element. - - OUTPUT: + - ``exponent`` -- an element - A term. + OUTPUT: a term TESTS:: @@ -586,14 +572,12 @@ def _calculate_pow_(self, exponent, new_coefficient=None): INPUT: - - ``exponent`` -- an element. + - ``exponent`` -- an element - ``new_coefficient`` -- if not ``None`` this is passed on to the - construction of the element (in particular, not taken to any power). - - OUTPUT: + construction of the element (in particular, not taken to any power) - A term. + OUTPUT: a term TESTS:: @@ -635,11 +619,9 @@ def can_absorb(self, other): INPUT: - - ``other`` -- an asymptotic term. - - OUTPUT: + - ``other`` -- an asymptotic term - A boolean. + OUTPUT: boolean .. NOTE:: @@ -672,10 +654,10 @@ def absorb(self, other, check=True): INPUT: - - ``other`` -- an asymptotic term. + - ``other`` -- an asymptotic term - - ``check`` -- a boolean. If ``check`` is ``True`` (default), - then ``can_absorb`` is called before absorption. + - ``check`` -- boolean; if ``True`` (default), then ``can_absorb`` + is called before absorption OUTPUT: @@ -769,11 +751,9 @@ def _absorb_(self, other): INPUT: - ``other`` -- an asymptotic term from the same parent as - this element. - - OUTPUT: + this element - An asymptotic term or ``None``. + OUTPUT: an asymptotic term or ``None`` .. NOTE:: @@ -823,14 +803,12 @@ def log_term(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - A tuple of terms. + OUTPUT: a tuple of terms .. NOTE:: @@ -879,14 +857,12 @@ def _log_growth_(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - A tuple of terms. + OUTPUT: a tuple of terms EXAMPLES:: @@ -918,9 +894,7 @@ def _lt_(self, other): - ``other`` -- an asymptotic term - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -1022,11 +996,9 @@ def _eq_(self, other): INPUT: - - ``other`` -- an asymptotic term. - - OUTPUT: + - ``other`` -- an asymptotic term - A boolean. + OUTPUT: boolean .. NOTE:: @@ -1077,13 +1049,7 @@ def is_constant(self): r""" Return whether this term is an (exact) constant. - INPUT: - - Nothing. - - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -1115,9 +1081,7 @@ def is_exact(self): r""" Return whether this term is an exact term. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1134,13 +1098,7 @@ def is_little_o_of_one(self): r""" Return whether this generic term is of order `o(1)`. - INPUT: - - Nothing. - - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1173,11 +1131,9 @@ def rpow(self, base): INPUT: - - ``base`` -- an element or ``'e'``. - - OUTPUT: + - ``base`` -- an element or ``'e'`` - A term. + OUTPUT: a term EXAMPLES:: @@ -1200,13 +1156,7 @@ def _repr_(self): r""" A representation string for this generic term. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1227,9 +1177,7 @@ def _latex_(self): r""" A LaTeX-representation string for this generic term. - OUTPUT: - - A NotImplementedError is raised. + OUTPUT: a :exc:`NotImplementedError` is raised TESTS:: @@ -1252,7 +1200,7 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. + - ``rules`` -- dictionary OUTPUT: @@ -1284,9 +1232,7 @@ def variable_names(self): r""" Return the names of the variables of this term. - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -1309,9 +1255,7 @@ def _factorial_(self): r""" Return the factorial of this generic term. - OUTPUT: - - A term. + OUTPUT: a term TESTS:: @@ -1335,11 +1279,11 @@ def _singularity_analysis_(self, var, zeta, precision): INPUT: - - ``var`` -- a string denoting the variable + - ``var`` -- string denoting the variable - ``zeta`` -- a number - - ``precision`` -- an integer + - ``precision`` -- integer OUTPUT: @@ -1372,12 +1316,12 @@ class GenericTermMonoid(UniqueRepresentation, Parent, WithLocals): INPUT: - ``growth_group`` -- a growth group (i.e. an instance of - :class:`~sage.rings.asymptotic.growth_group.GenericGrowthGroup`). + :class:`~sage.rings.asymptotic.growth_group.GenericGrowthGroup`) - ``coefficient_ring`` -- a ring which contains the (maybe implicit) - coefficients of the elements. + coefficients of the elements - - ``category`` -- The category of the parent can be specified + - ``category`` -- the category of the parent can be specified in order to broaden the base structure. It has to be a subcategory of ``Join of Category of Monoids and Category of posets``. This is also the default category if ``None`` is specified. @@ -1542,10 +1486,9 @@ def term_monoid(self, type): INPUT: - - ``type`` -- 'O' or 'exact', or an instance of an existing - term monoid. - See :class:`~sage.rings.asymptotic.term_monoid.TermMonoidFactory` - for more details. + - ``type`` -- 'O' or 'exact', or an instance of an existing term monoid. + See :class:`~sage.rings.asymptotic.term_monoid.TermMonoidFactory` for + more details. OUTPUT: @@ -1609,13 +1552,11 @@ def change_parameter(self, growth_group=None, coefficient_ring=None): INPUT: - - ``growth_group`` -- (default: ``None``) the new growth group. + - ``growth_group`` -- (default: ``None``) the new growth group - - ``coefficient_ring`` -- (default: ``None``) the new coefficient ring. + - ``coefficient_ring`` -- (default: ``None``) the new coefficient ring - OUTPUT: - - A term monoid. + OUTPUT: a term monoid EXAMPLES:: @@ -1651,13 +1592,7 @@ def _repr_(self): r""" A representation string for this generic term monoid. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1679,11 +1614,9 @@ def _coerce_map_from_(self, S): INPUT: - - ``S`` -- a parent. - - OUTPUT: + - ``S`` -- a parent - A boolean. + OUTPUT: boolean .. NOTE:: @@ -1738,16 +1671,14 @@ def _element_constructor_(self, data, *args, **kwds): INPUT: - ``data`` -- a growth element or an object representing the - element to be initialized. + element to be initialized - - ``coefficient`` -- (default: ``None``) - an element of the coefficient ring. + - ``coefficient`` -- (default: ``None``) an element of the coefficient + ring - - ``**kwds`` -- keyword arguments passed on to the term. - - OUTPUT: + - ``**kwds`` -- keyword arguments passed on to the term - An element of this term monoid. + OUTPUT: an element of this term monoid EXAMPLES:: @@ -1913,7 +1844,7 @@ def _validate_growth_or_error_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) @@ -1973,7 +1904,7 @@ def _validate_coefficient_or_error_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) @@ -2035,13 +1966,7 @@ def _default_kwds_construction_(self): r""" Return the default keyword arguments for the construction of a term. - INPUT: - - Nothing. - - OUTPUT: - - A dictionary. + OUTPUT: a dictionary TESTS:: @@ -2065,14 +1990,12 @@ def _convert_construction_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) - OUTPUT: - - Nothing, but ``kwds_construction`` might be changed. + OUTPUT: nothing, but ``kwds_construction`` might be changed TESTS:: @@ -2115,11 +2038,9 @@ def from_construction(self, construction, **kwds_overrides): - ``construction`` -- a pair ``(cls, kwds_construction)`` - - ``kwds_overrides`` -- a dictionary - - OUTPUT: + - ``kwds_overrides`` -- dictionary - A term. + OUTPUT: a term EXAMPLES:: @@ -2193,11 +2114,9 @@ def _create_element_in_extension_(self, growth, coefficient): INPUT: - - ``growth`` and ``coefficient`` -- the element data. - - OUTPUT: + - ``growth`` and ``coefficient`` -- the element data - An element. + OUTPUT: an element EXAMPLES:: @@ -2228,7 +2147,7 @@ def _split_growth_and_coefficient_(self, data): INPUT: - - ``data`` -- an element. + - ``data`` -- an element OUTPUT: @@ -2309,11 +2228,9 @@ def _get_factors_(self, data): INPUT: - - ``data`` -- an object. - - OUTPUT: + - ``data`` -- an object - A tuple. + OUTPUT: a tuple TESTS:: @@ -2345,13 +2262,7 @@ def _an_element_(self): r""" Return an element of this term monoid. - INPUT: - - Nothing. - - OUTPUT: - - An element of this term monoid. + OUTPUT: an element of this term monoid EXAMPLES:: @@ -2372,13 +2283,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -2397,13 +2302,11 @@ def le(self, left, right): INPUT: - - ``left`` -- an element. - - - ``right`` -- an element. + - ``left`` -- an element - OUTPUT: + - ``right`` -- an element - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -2430,9 +2333,9 @@ class OTerm(GenericTerm): INPUT: - - ``parent`` -- the parent of the asymptotic term. + - ``parent`` -- the parent of the asymptotic term - - ``growth`` -- a growth element. + - ``growth`` -- a growth element EXAMPLES:: @@ -2471,12 +2374,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. - - OUTPUT: + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - A string. + OUTPUT: string EXAMPLES:: @@ -2507,9 +2408,7 @@ def _latex_(self): r""" A LaTeX-representation string for this `O`-term. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -2532,7 +2431,7 @@ def __invert__(self): OUTPUT: - A :class:`ZeroDivisionError` since `O`-terms cannot be inverted. + A :exc:`ZeroDivisionError` since `O`-terms cannot be inverted. TESTS:: @@ -2553,11 +2452,9 @@ def __pow__(self, exponent): INPUT: - - ``exponent`` -- an element. - - OUTPUT: + - ``exponent`` -- an element - An :class:`OTerm`. + OUTPUT: an :class:`OTerm` TESTS:: @@ -2585,11 +2482,9 @@ def can_absorb(self, other): INPUT: - - ``other`` -- an asymptotic term. - - OUTPUT: + - ``other`` -- an asymptotic term - A boolean. + OUTPUT: boolean .. NOTE:: @@ -2618,11 +2513,9 @@ def _absorb_(self, other): INPUT: - - ``other`` -- an asymptotic `O`-term. - - OUTPUT: + - ``other`` -- an asymptotic `O`-term - An asymptotic `O`-term. + OUTPUT: an asymptotic `O`-term .. NOTE:: @@ -2664,14 +2557,12 @@ def log_term(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - A tuple of terms. + OUTPUT: a tuple of terms .. NOTE:: @@ -2705,13 +2596,7 @@ def is_little_o_of_one(self): r""" Return whether this O-term is of order `o(1)`. - INPUT: - - Nothing. - - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -2755,11 +2640,9 @@ def rpow(self, base): INPUT: - - ``base`` -- an element or ``'e'``. + - ``base`` -- an element or ``'e'`` - OUTPUT: - - A term. + OUTPUT: a term .. NOTE:: @@ -2812,11 +2695,9 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. - - OUTPUT: + - ``rules`` -- dictionary - An object. + OUTPUT: an object TESTS:: @@ -2886,9 +2767,7 @@ def _factorial_(self): Return the factorial of this O-term if it is constant (i.e., has growth `1`). - OUTPUT: - - A term. + OUTPUT: a term TESTS:: @@ -2915,11 +2794,11 @@ def _singularity_analysis_(self, var, zeta, precision): INPUT: - - ``var`` -- a string denoting the variable + - ``var`` -- string denoting the variable - ``zeta`` -- a number - - ``precision`` -- an integer + - ``precision`` -- integer OUTPUT: @@ -2948,9 +2827,9 @@ class OTermMonoid(GenericTermMonoid): INPUT: - - ``growth_group`` -- a growth group. + - ``growth_group`` -- a growth group - - ``category`` -- The category of the parent can be specified + - ``category`` -- the category of the parent can be specified in order to broaden the base structure. It has to be a subcategory of ``Join of Category of monoids and Category of posets``. This is also the default category if ``None`` is specified. @@ -2988,14 +2867,12 @@ def _convert_construction_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) - OUTPUT: - - Nothing, but ``kwds_construction`` might be changed. + OUTPUT: nothing, but ``kwds_construction`` might be changed TESTS:: @@ -3042,11 +2919,9 @@ def _coerce_map_from_(self, S): INPUT: - - ``S`` -- a parent. - - OUTPUT: + - ``S`` -- a parent - ``True`` or ``None``. + OUTPUT: ``True`` or ``None`` .. NOTE:: @@ -3098,13 +2973,7 @@ def _repr_(self): r""" A representation string for this `O`-term monoid. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3125,12 +2994,11 @@ class TermWithCoefficient(GenericTerm): INPUT: - - ``parent`` -- the parent of the asymptotic term. + - ``parent`` -- the parent of the asymptotic term - - ``growth`` -- an asymptotic growth element of - the parent's growth group. + - ``growth`` -- an asymptotic growth element of the parent's growth group - - ``coefficient`` -- an element of the parent's coefficient ring. + - ``coefficient`` -- an element of the parent's coefficient ring EXAMPLES:: @@ -3208,10 +3076,6 @@ def construction(self): r""" Return a construction of this term. - INPUT: - - Nothing. - OUTPUT: A pair ``(cls, kwds)`` such that ``cls(**kwds)`` equals this term. @@ -3245,13 +3109,7 @@ def _repr_(self): r""" A representation string for this term with coefficient. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3273,12 +3131,10 @@ def _repr_product_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. - - OUTPUT: + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - A string + OUTPUT: string EXAMPLES:: @@ -3326,7 +3182,7 @@ def _mul_(self, other): INPUT: - - ``other`` -- an asymptotic term. + - ``other`` -- an asymptotic term OUTPUT: @@ -3373,11 +3229,9 @@ def _calculate_pow_(self, exponent): INPUT: - - ``exponent`` -- an element. + - ``exponent`` -- an element - OUTPUT: - - A term. + OUTPUT: a term TESTS:: @@ -3427,14 +3281,12 @@ def _log_coefficient_(self, base=None, locals=None): - ``base`` -- the base of the logarithm. If ``None`` (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - A tuple of terms. + OUTPUT: a tuple of terms EXAMPLES:: @@ -3481,9 +3333,7 @@ def _eq_(self, other): - ``other`` -- an :class:`TermWithCoefficient` - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -3519,15 +3369,15 @@ class TermWithCoefficientMonoid(GenericTermMonoid): INPUT: - - ``growth_group`` -- a growth group. + - ``growth_group`` -- a growth group - - ``category`` -- The category of the parent can be specified + - ``category`` -- the category of the parent can be specified in order to broaden the base structure. It has to be a subcategory of ``Join of Category of monoids and Category of posets``. This is also the default category if ``None`` is specified. - ``coefficient_ring`` -- the ring which contains the - coefficients of the elements. + coefficients of the elements EXAMPLES:: @@ -3556,13 +3406,7 @@ def _repr_(self): r""" A representation string for this TermWithCoefficient Monoid. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3585,7 +3429,7 @@ def _validate_coefficient_or_error_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) @@ -3640,13 +3484,7 @@ def _default_kwds_construction_(self): r""" Return the default keyword arguments for the construction of a term. - INPUT: - - Nothing. - - OUTPUT: - - A dictionary. + OUTPUT: a dictionary TESTS:: @@ -3673,14 +3511,12 @@ def _convert_construction_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) - OUTPUT: - - Nothing, but ``kwds_construction`` might be changed. + OUTPUT: nothing, but ``kwds_construction`` might be changed TESTS:: @@ -3710,13 +3546,7 @@ def _an_element_(self): r""" Return an element of this term with coefficient monoid. - INPUT: - - Nothing. - - OUTPUT: - - An element of this term monoid. + OUTPUT: an element of this term monoid EXAMPLES:: @@ -3740,13 +3570,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -3772,12 +3596,11 @@ class ExactTerm(TermWithCoefficient): INPUT: - - ``parent`` -- the parent of the asymptotic term. + - ``parent`` -- the parent of the asymptotic term - - ``growth`` -- an asymptotic growth element from - ``parent.growth_group``. + - ``growth`` -- an asymptotic growth element from ``parent.growth_group`` - - ``coefficient`` -- an element from ``parent.coefficient_ring``. + - ``coefficient`` -- an element from ``parent.coefficient_ring`` EXAMPLES:: @@ -3836,12 +3659,10 @@ def _repr_(self, latex=False): INPUT: - - ``latex`` -- (default: ``False``) a boolean. If set, then - LaTeX-output is returned. - - OUTPUT: + - ``latex`` -- boolean (default: ``False``); if set, then + LaTeX-output is returned - A string. + OUTPUT: string EXAMPLES:: @@ -3877,9 +3698,7 @@ def _latex_(self): r""" A LaTeX-representation string for this exact term. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -3921,9 +3740,7 @@ def __invert__(self): r""" Invert this term. - OUTPUT: - - A term. + OUTPUT: a term TESTS:: @@ -3950,11 +3767,9 @@ def __pow__(self, exponent): INPUT: - - ``exponent`` -- an element. - - OUTPUT: + - ``exponent`` -- an element - An :class:`ExactTerm`. + OUTPUT: an :class:`ExactTerm` TESTS:: @@ -3978,11 +3793,9 @@ def can_absorb(self, other): INPUT: - - ``other`` -- an asymptotic term. - - OUTPUT: + - ``other`` -- an asymptotic term - A boolean. + OUTPUT: boolean .. NOTE:: @@ -4014,11 +3827,9 @@ def _absorb_(self, other): INPUT: - - ``other`` -- an exact term. - - OUTPUT: + - ``other`` -- an exact term - An exact term or ``None``. + OUTPUT: an exact term or ``None`` .. NOTE:: @@ -4068,14 +3879,12 @@ def log_term(self, base=None, locals=None): (default value) is used, the natural logarithm is taken. - - ``locals`` -- a dictionary which may contain the following keys and values: + - ``locals`` -- dictionary which may contain the following keys and values: - ``'log'`` -- value: a function. If not used, then the usual :class:`log ` is taken. - OUTPUT: - - A tuple of terms. + OUTPUT: a tuple of terms .. NOTE:: @@ -4113,13 +3922,7 @@ def is_constant(self): r""" Return whether this term is an (exact) constant. - INPUT: - - Nothing. - - OUTPUT: - - A boolean. + OUTPUT: boolean .. NOTE:: @@ -4146,13 +3949,7 @@ def is_little_o_of_one(self): r""" Return whether this exact term is of order `o(1)`. - INPUT: - - Nothing. - - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -4194,9 +3991,7 @@ def is_exact(self): r""" Return whether this term is an exact term. - OUTPUT: - - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -4222,11 +4017,9 @@ def rpow(self, base): INPUT: - - ``base`` -- an element or ``'e'``. - - OUTPUT: + - ``base`` -- an element or ``'e'`` - A term. + OUTPUT: a term EXAMPLES:: @@ -4280,11 +4073,9 @@ def _substitute_(self, rules): INPUT: - - ``rules`` -- a dictionary. + - ``rules`` -- dictionary - OUTPUT: - - An object. + OUTPUT: an object TESTS:: @@ -4330,9 +4121,7 @@ def _factorial_(self): Return the factorial of this exact term if it is constant (i.e., has growth `1`). - OUTPUT: - - A term. + OUTPUT: a term TESTS:: @@ -4363,11 +4152,11 @@ def _singularity_analysis_(self, var, zeta, precision): INPUT: - - ``var`` -- a string denoting the variable + - ``var`` -- string denoting the variable - ``zeta`` -- a number - - ``precision`` -- an integer + - ``precision`` -- integer OUTPUT: @@ -4402,15 +4191,15 @@ class ExactTermMonoid(TermWithCoefficientMonoid): INPUT: - - ``growth_group`` -- a growth group. + - ``growth_group`` -- a growth group - - ``category`` -- The category of the parent can be specified + - ``category`` -- the category of the parent can be specified in order to broaden the base structure. It has to be a subcategory of ``Join of Category of monoids and Category of posets``. This is also the default category if ``None`` is specified. - ``coefficient_ring`` -- the ring which contains the coefficients of - the elements. + the elements EXAMPLES:: @@ -4450,14 +4239,12 @@ def _convert_construction_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) - OUTPUT: - - Nothing, but ``kwds_construction`` might be changed. + OUTPUT: nothing, but ``kwds_construction`` might be changed TESTS:: @@ -4497,13 +4284,7 @@ def _repr_(self): r""" A representation string for this exact term monoid. - INPUT: - - Nothing. - - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -4571,7 +4352,6 @@ class BTerm(TermWithCoefficient): sage: T(x^3*y^2, coefficient=42, valid_from={'x': 10, 'y': 20}) B(42*x^3*y^2, x >= 10, y >= 20) - """ def __init__(self, parent, growth, valid_from, **kwds): r""" @@ -4644,10 +4424,6 @@ def construction(self): r""" Return a construction of this term. - INPUT: - - Nothing. - OUTPUT: A pair ``(cls, kwds)`` such that ``cls(**kwds)`` equals this term. @@ -4684,13 +4460,7 @@ def _repr_(self, latex=False): r""" A representation string for this B-term. - INPUT: - - Nothing - - OUTPUT: - - A string + OUTPUT: string EXAMPLES:: @@ -4720,9 +4490,7 @@ def _latex_(self): r""" A LaTeX-representation string for this B-term. - OUTPUT: - - A string + OUTPUT: string TESTS:: @@ -4788,9 +4556,7 @@ def can_absorb(self, other): - ``other`` -- an asymptotic term - OUTPUT: - - A boolean + OUTPUT: boolean .. NOTE:: @@ -4900,10 +4666,10 @@ class BTermMonoid(TermWithCoefficientMonoid): - ``coefficient_ring`` -- the ring which contains the coefficients of the elements - - ``category`` -- The category of the parent can be specified + - ``category`` -- the category of the parent can be specified in order to broaden the base structure. It has to be a subcategory of ``Join of Category of monoids and Category of posets``. This - is also the default category if ``None`` is specified + is also the default category if ``None`` is specified. EXAMPLES:: @@ -4927,13 +4693,7 @@ def _repr_(self): r""" A representation string for this B term monoid. - INPUT: - - Nothing - - OUTPUT: - - A string + OUTPUT: string EXAMPLES:: @@ -4950,13 +4710,7 @@ def _default_kwds_construction_(self): r""" Return the default keyword arguments for the construction of a term. - INPUT: - - Nothing. - - OUTPUT: - - A dictionary. + OUTPUT: a dictionary TESTS:: @@ -4991,14 +4745,12 @@ def _convert_construction_(self, kwds_construction): INPUT: - - ``kwds_construction`` -- a dictionary representing + - ``kwds_construction`` -- dictionary representing the keyword arguments of a term in its construction (see also :meth:`GenericTerm.construction` and :meth:`TermWithCoefficient.construction`) - OUTPUT: - - Nothing, but ``kwds_construction`` might be changed. + OUTPUT: nothing, but ``kwds_construction`` might be changed TESTS:: @@ -5058,9 +4810,7 @@ def _coerce_map_from_(self, S): - ``S`` -- a parent - OUTPUT: - - ``True`` or ``None`` + OUTPUT: ``True`` or ``None`` .. NOTE:: @@ -5114,13 +4864,7 @@ def _an_element_(self): r""" Return an element of this B-term monoid. - INPUT: - - Nothing. - - OUTPUT: - - An element of this term monoid. + OUTPUT: an element of this term monoid EXAMPLES:: @@ -5143,13 +4887,7 @@ def some_elements(self): See :class:`TestSuite` for a typical use case. - INPUT: - - Nothing. - - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -5200,22 +4938,19 @@ class TermMonoidFactory(UniqueRepresentation, UniqueFactory): INPUT: - - ``term_monoid`` -- the kind of terms held in the new term monoid. + - ``term_monoid`` -- the kind of terms held in the new term monoid Either a string ``'exact'``, ``'O'`` (capital letter ``O``) or ``'B'`` or an existing instance of a term monoid. - - ``growth_group`` -- a growth group or - a string describing a growth group. + - ``growth_group`` -- a growth group or a string describing a growth group - - ``coefficient_ring`` -- a ring. + - ``coefficient_ring`` -- a ring - ``asymptotic_ring`` -- if specified, then ``growth_group`` and - ``coefficient_ring`` are taken from this asymptotic ring. - - OUTPUT: + ``coefficient_ring`` are taken from this asymptotic ring - An asymptotic term monoid. + OUTPUT: an asymptotic term monoid EXAMPLES:: diff --git a/src/sage/rings/bernmm.pyx b/src/sage/rings/bernmm.pyx index 82b1646a72f..492181f1f22 100644 --- a/src/sage/rings/bernmm.pyx +++ b/src/sage/rings/bernmm.pyx @@ -46,7 +46,7 @@ def bernmm_bern_rat(long k, int num_threads = 1): INPUT: - - ``k`` -- non-negative integer + - ``k`` -- nonnegative integer - ``num_threads`` -- integer `\geq 1`, number of threads to use COMPLEXITY: @@ -85,7 +85,7 @@ def bernmm_bern_rat(long k, int num_threads = 1): cdef Rational x if k < 0: - raise ValueError("k must be non-negative") + raise ValueError("k must be nonnegative") x = Rational() sig_on() @@ -104,7 +104,7 @@ def bernmm_bern_modp(long p, long k): INPUT: - ``p`` -- a prime - - ``k`` -- non-negative integer + - ``k`` -- nonnegative integer COMPLEXITY: @@ -147,7 +147,7 @@ def bernmm_bern_modp(long p, long k): cdef long x if k < 0: - raise ValueError("k must be non-negative") + raise ValueError("k must be nonnegative") sig_on() x = bern_modp(p, k) diff --git a/src/sage/rings/bernoulli_mod_p.pyx b/src/sage/rings/bernoulli_mod_p.pyx index ff2948eec56..1783c712aaf 100644 --- a/src/sage/rings/bernoulli_mod_p.pyx +++ b/src/sage/rings/bernoulli_mod_p.pyx @@ -53,9 +53,9 @@ def verify_bernoulli_mod_p(data): INPUT: - - ``data`` -- list, same format as output of :func:`bernoulli_mod_p` function + - ``data`` -- list; same format as output of :func:`bernoulli_mod_p` function - OUTPUT: bool -- True if checksum passed + OUTPUT: boolean; ``True`` if checksum passed EXAMPLES:: @@ -100,7 +100,7 @@ def bernoulli_mod_p(int p): INPUT: - - ``p`` -- integer, a prime + - ``p`` -- integer; a prime OUTPUT: @@ -228,16 +228,14 @@ def bernoulli_mod_p_single(long p, long k): r""" Return the Bernoulli number `B_k` mod `p`. - If `B_k` is not `p`-integral, an :class:`ArithmeticError` is raised. + If `B_k` is not `p`-integral, an :exc:`ArithmeticError` is raised. INPUT: - - ``p`` -- integer, a prime - - ``k`` -- non-negative integer + - ``p`` -- integer; a prime + - ``k`` -- nonnegative integer - OUTPUT: - - The `k`-th Bernoulli number mod `p`. + OUTPUT: the `k`-th Bernoulli number mod `p` EXAMPLES:: @@ -267,7 +265,7 @@ def bernoulli_mod_p_single(long p, long k): sage: bernoulli_mod_p_single(19, -4) Traceback (most recent call last): ... - ValueError: k must be non-negative + ValueError: k must be nonnegative Check results against :class:`bernoulli_mod_p`:: diff --git a/src/sage/rings/big_oh.py b/src/sage/rings/big_oh.py index 917c81e0a3d..54513722d03 100644 --- a/src/sage/rings/big_oh.py +++ b/src/sage/rings/big_oh.py @@ -1,5 +1,5 @@ """ -Big O for various types (power series, p-adics, etc.) +Big O for various types (power series, `p`-adics, etc.) .. SEEALSO:: diff --git a/src/sage/rings/cfinite_sequence.py b/src/sage/rings/cfinite_sequence.py index f34f4514186..6b04e1ee66f 100644 --- a/src/sage/rings/cfinite_sequence.py +++ b/src/sage/rings/cfinite_sequence.py @@ -120,7 +120,7 @@ def CFiniteSequences(base_ring, names=None, category=None): - ``base_ring`` -- the base ring to construct the fraction field representing the C-Finite sequences - - ``names`` -- (optional) the list of variables. + - ``names`` -- (optional) the list of variables EXAMPLES:: @@ -172,9 +172,7 @@ class CFiniteSequence(FieldElement, (can be an element from the symbolic ring, fraction field or polynomial ring) - OUTPUT: - - A CFiniteSequence object + OUTPUT: a CFiniteSequence object EXAMPLES:: @@ -329,12 +327,12 @@ def __init__(self, parent, ogf): INPUT: - - ``ogf`` -- the ordinary generating function, a fraction of polynomials over the rationals - - ``parent`` -- the parent of the C-Finite sequence, an occurrence of :class:`CFiniteSequences` - - OUTPUT: + - ``ogf`` -- the ordinary generating function, a fraction of + polynomials over the rationals + - ``parent`` -- the parent of the C-Finite sequence, an occurrence of + :class:`CFiniteSequences` - - A CFiniteSequence object + OUTPUT: a CFiniteSequence object TESTS:: @@ -511,9 +509,7 @@ def coefficients(self): Return the coefficients of the recurrence representation of the C-finite sequence. - OUTPUT: - - - A list of values + OUTPUT: list of values EXAMPLES:: @@ -728,9 +724,7 @@ def recurrence_repr(self) -> str: Return a string with the recurrence representation of the C-finite sequence. - OUTPUT: - - A string + OUTPUT: string EXAMPLES:: @@ -784,7 +778,7 @@ def series(self, n): INPUT: - - `n` -- a nonnegative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -891,7 +885,7 @@ def closed_form(self, n='n'): class CFiniteSequences_generic(Parent, UniqueRepresentation): r""" - The class representing the ring of C-Finite Sequences + The class representing the ring of C-Finite Sequences. TESTS:: @@ -960,7 +954,8 @@ def _element_constructor_(self, ogf): INPUT: - - ``ogf`` -- the ordinary generating function, a fraction of polynomials over the rationals + - ``ogf`` -- the ordinary generating function, a fraction of + polynomials over the rationals TESTS:: @@ -1005,7 +1000,7 @@ def gen(self, i=0): INPUT: - - ``i`` -- an integer (default:0) + - ``i`` -- integer (default: 0) EXAMPLES:: @@ -1042,9 +1037,7 @@ def an_element(self): r""" Return an element of C-Finite Sequences. - OUTPUT: - - The Lucas sequence. + OUTPUT: the Lucas sequence EXAMPLES:: @@ -1134,12 +1127,10 @@ def from_recurrence(self, coefficients, values): INPUT: - - ``coefficients`` -- a list of rationals + - ``coefficients`` -- list of rationals - ``values`` -- start values, a list of rationals - OUTPUT: - - - A CFiniteSequence object + OUTPUT: a CFiniteSequence object EXAMPLES:: @@ -1185,14 +1176,12 @@ def guess(self, sequence, algorithm='sage'): INPUT: - ``sequence`` -- list of integers - - ``algorithm`` -- string - - 'sage' -- the default is to use Sage's matrix kernel function - - 'pari' -- use Pari's implementation of LLL - - 'bm' -- use Sage's Berlekamp-Massey algorithm - - OUTPUT: + - ``algorithm`` -- string; one of + - ``'sage'`` -- the default is to use Sage's matrix kernel function + - ``'pari'`` -- use Pari's implementation of LLL + - ``'bm'`` -- use Sage's Berlekamp-Massey algorithm - - a CFiniteSequence, or 0 if none could be found + OUTPUT: a CFiniteSequence, or 0 if none could be found With the default kernel method, trailing zeroes are chopped off before a guessing attempt. This may reduce the data diff --git a/src/sage/rings/complex_arb.pyx b/src/sage/rings/complex_arb.pyx index 095de7b6774..3f34c71df19 100644 --- a/src/sage/rings/complex_arb.pyx +++ b/src/sage/rings/complex_arb.pyx @@ -75,7 +75,7 @@ above warning, inexact balls are not considered equal to themselves):: sage: a == b False -A ball is non-zero in the sense of usual comparison if and only if it does not +A ball is nonzero in the sense of usual comparison if and only if it does not contain zero:: sage: a = CBF(RIF(-0.5, 0.5)) @@ -314,7 +314,7 @@ class ComplexBallField(UniqueRepresentation, sage.rings.abc.ComplexBallField): INPUT: - - ``precision`` -- an integer `\ge 2`. + - ``precision`` -- integer `\ge 2` EXAMPLES:: @@ -365,7 +365,7 @@ class ComplexBallField(UniqueRepresentation, sage.rings.abc.ComplexBallField): INPUT: - - ``precision`` -- an integer `\ge 2`. + - ``precision`` -- integer `\ge 2` EXAMPLES:: @@ -454,7 +454,7 @@ class ComplexBallField(UniqueRepresentation, sage.rings.abc.ComplexBallField): def complex_field(self): """ - Return the complex ball field with the same precision, i.e. ``self`` + Return the complex ball field with the same precision, i.e. ``self``. EXAMPLES:: @@ -587,7 +587,7 @@ class ComplexBallField(UniqueRepresentation, sage.rings.abc.ComplexBallField): INPUT: - - ``x``, ``y`` (optional) -- either a complex number, interval or ball, + - ``x``, ``y`` -- (optional) either a complex number, interval or ball, or two real ones (see examples below for more information on accepted number types). @@ -1029,11 +1029,11 @@ class ComplexBallField(UniqueRepresentation, sage.rings.abc.ComplexBallField): balls, or elements of any parent that coerces into this ball field, e.g. rational or algebraic numbers. - - ``rel_tol`` (default: `2^{-p}` where `p` is the precision of - the ball field) -- relative accuracy goal + - ``rel_tol`` -- relative accuracy goal (default: `2^{-p}` where `p` is + the precision of the ball field) - - ``abs_tol`` (default: `2^{-p}` where `p` is the precision of - the ball field) -- absolute accuracy goal + - ``abs_tol`` -- absolute accuracy goal (default: `2^{-p}` where `p` is + the precision of the ball field) Additionally, the following optional parameters can be used to control the integration algorithm. See the `FLINT documentation `_ @@ -1048,12 +1048,12 @@ class ComplexBallField(UniqueRepresentation, sage.rings.abc.ComplexBallField): - ``depth_limit`` -- maximum search depth for adaptive subdivision - - ``use_heap`` (boolean, default ``False``) -- if ``True``, use a + - ``use_heap`` -- boolean (default: ``False``); if ``True``, use a priority queue instead of a stack to manage subintervals. This sometimes gives better results for integrals with slow convergence but may require more memory and increasing ``depth_limit``. - - ``verbose`` (integer, default 0) -- If set to 1, some information + - ``verbose`` -- integer (default: 0); if set to 1, some information about the overall integration process is printed to standard output. If set to 2, information about each subinterval is printed. @@ -1306,7 +1306,7 @@ cdef inline real_ball_field(ComplexBall ball): cdef class ComplexBall(RingElement): """ - Hold one ``acb_t`` of the `FLINT library `_ + Hold one ``acb_t`` of the `FLINT library `_. EXAMPLES:: @@ -1342,10 +1342,10 @@ cdef class ComplexBall(RingElement): INPUT: - - ``parent`` -- a :class:`ComplexBallField`. + - ``parent`` -- a :class:`ComplexBallField` - - ``x``, ``y`` (optional) -- either a complex number, interval or ball, - or two real ones. + - ``x``, ``y`` -- (optional) either a complex number, interval or ball, + or two real ones .. SEEALSO:: :meth:`ComplexBallField._element_constructor_` @@ -1408,7 +1408,6 @@ cdef class ComplexBall(RingElement): Traceback (most recent call last): ... TypeError: unsupported initializer - """ cdef fmpz_t tmpz cdef fmpq_t tmpq @@ -1485,9 +1484,7 @@ cdef class ComplexBall(RingElement): """ Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1619,7 +1616,7 @@ cdef class ComplexBall(RingElement): INPUT: - ``parent`` -- :class:`~sage.rings.complex_mpfr.ComplexField_class`, - target parent. + target parent EXAMPLES:: @@ -1647,7 +1644,7 @@ cdef class ComplexBall(RingElement): INPUT: - ``parent`` -- :class:`~sage.rings.real_mpfi.RealIntervalField_class`, - target parent. + target parent EXAMPLES:: @@ -1672,7 +1669,7 @@ cdef class ComplexBall(RingElement): INPUT: - ``parent`` -- :class:`~sage.rings.real_mpfr.RealField_class`, - target parent. + target parent EXAMPLES:: @@ -1816,9 +1813,7 @@ cdef class ComplexBall(RingElement): """ Return the real part of this ball. - OUTPUT: - - A :class:`~sage.rings.real_arb.RealBall`. + OUTPUT: a :class:`~sage.rings.real_arb.RealBall` EXAMPLES:: @@ -1837,9 +1832,7 @@ cdef class ComplexBall(RingElement): """ Return the imaginary part of this ball. - OUTPUT: - - A :class:`~sage.rings.real_arb.RealBall`. + OUTPUT: a :class:`~sage.rings.real_arb.RealBall` EXAMPLES:: @@ -1878,13 +1871,11 @@ cdef class ComplexBall(RingElement): INPUT: - - ``test_zero`` (boolean, default ``False``) -- if ``True``, + - ``test_zero`` -- boolean (default: ``False``); if ``True``, make sure that the returned lower bound is positive, raising an error if the ball contains zero. - OUTPUT: - - A ball with zero radius + OUTPUT: a ball with zero radius EXAMPLES:: @@ -1915,9 +1906,7 @@ cdef class ComplexBall(RingElement): """ Return an upper bound for the absolute value of this complex ball. - OUTPUT: - - A ball with zero radius + OUTPUT: a ball with zero radius EXAMPLES:: @@ -1990,9 +1979,7 @@ cdef class ComplexBall(RingElement): """ Return an exact ball with the same midpoint as this ball. - OUTPUT: - - A :class:`ComplexBall`. + OUTPUT: a :class:`ComplexBall` EXAMPLES:: @@ -2205,12 +2192,10 @@ cdef class ComplexBall(RingElement): INPUT: - - ``ampl`` -- A **real** ball (or an object that can be coerced to a - real ball). - - OUTPUT: + - ``ampl`` -- a **real** ball (or an object that can be coerced to a + real ball) - A new complex ball. + OUTPUT: a new complex ball EXAMPLES:: @@ -2451,7 +2436,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``other`` -- a :class:`ComplexBall`. + - ``other`` -- a :class:`ComplexBall` OUTPUT: @@ -2480,7 +2465,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``other`` -- a :class:`ComplexBall`. + - ``other`` -- a :class:`ComplexBall` EXAMPLES:: @@ -2711,7 +2696,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``shift`` -- integer, may be negative. + - ``shift`` -- integer; may be negative EXAMPLES:: @@ -2762,7 +2747,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``shift`` -- integer, may be negative. + - ``shift`` -- integer; may be negative EXAMPLES:: @@ -2857,7 +2842,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the exponent is not an integer and the base ball touches the branch cut of the logarithm @@ -2924,7 +2909,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -2954,7 +2939,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3020,7 +3005,6 @@ cdef class ComplexBall(RingElement): [2.34369112679686134...e+347382171305201285713 +/- ...] sage: CBF(1/2).rising_factorial(CBF(2,3)) # abs tol 1e-15 [-0.123060451458124 +/- 3.06e-16] + [0.0406412631676552 +/- 7.57e-17]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_n = self._parent.coerce(n) @@ -3037,11 +3021,11 @@ cdef class ComplexBall(RingElement): INPUT: - - ``base`` (optional, complex ball or number) -- if ``None``, return + - ``base`` -- (optional) complex ball or number; if ``None``, return the principal branch of the natural logarithm ``ln(self)``, otherwise, return the general logarithm ``ln(self)/ln(base)`` - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut (with respect to ``self``) @@ -3092,7 +3076,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3351,7 +3335,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3380,7 +3364,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3409,7 +3393,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3440,7 +3424,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3469,7 +3453,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3498,7 +3482,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3567,7 +3551,7 @@ cdef class ComplexBall(RingElement): INPUT: - - ``analytic`` (optional, boolean) -- if ``True``, return an + - ``analytic`` -- boolean (default: ``False``); if ``True``, return an indeterminate (not-a-number) value when the input ball touches the branch cut @@ -3626,7 +3610,6 @@ cdef class ComplexBall(RingElement): nan sage: CBF(1,1).psi(10) [56514.8269344249 +/- ...e-11] + [56215.1218005823 +/- ...e-11]*I - """ cdef ComplexBall my_n cdef ComplexBall result = self._new() @@ -3675,7 +3658,7 @@ cdef class ComplexBall(RingElement): def zetaderiv(self, k): r""" - Return the image of this ball by the k-th derivative of the Riemann + Return the image of this ball by the `k`-th derivative of the Riemann zeta function. For a more flexible interface, see the low-level method @@ -3814,18 +3797,16 @@ cdef class ComplexBall(RingElement): INPUT: - - ``a`` -- upper parameters, list of complex numbers that coerce into - this ball's parent; + - ``a`` -- upper parameters; list of complex numbers that coerce into + this ball's parent - - ``b`` -- lower parameters, list of complex numbers that coerce into - this ball's parent. + - ``b`` -- lower parameters; list of complex numbers that coerce into + this ball's parent - - ``regularized`` -- if True, the regularized generalized hypergeometric - function is computed. + - ``regularized`` -- if ``True``, the regularized generalized + hypergeometric function is computed - OUTPUT: - - The generalized hypergeometric function defined by + OUTPUT: the generalized hypergeometric function defined by .. MATH:: @@ -3891,7 +3872,6 @@ cdef class ComplexBall(RingElement): sage: CBF(0, 1).hypergeometric([QQbar(sqrt(2)), RLF(pi)], [1r, 1/2]) # needs sage.symbolic [-8.7029449215408 +/- ...e-14] + [-0.8499070546106 +/- ...e-14]*I - """ cdef ComplexBall tmp, my_a, my_b, my_c cdef ComplexBall res = self._new() @@ -4024,7 +4004,6 @@ cdef class ComplexBall(RingElement): sage: ai, aip, bi, bip = CBF(1,2).airy() sage: (ai * bip - bi * aip) * CBF(pi) # needs sage.symbolic [1.0000000000000 +/- ...e-15] + [+/- ...e-16]*I - """ cdef ComplexBall ai = self._new() cdef ComplexBall aip = self._new() @@ -4126,7 +4105,6 @@ cdef class ComplexBall(RingElement): [+/- ...e-16] + [+/- ...e-16]*I sage: Y - CBF(1, 1).bessel_Y(1) [+/- ...e-14] + [+/- ...e-14]*I - """ cdef ComplexBall result1 = self._new() cdef ComplexBall result2 = self._new() @@ -4425,7 +4403,6 @@ cdef class ComplexBall(RingElement): [0.913579138156117 +/- ...e-16], [1.086434811213308 +/- ...e-16], [0.913579138156117 +/- ...e-16]) - """ cdef ComplexBall res1 = self._new() @@ -4447,7 +4424,6 @@ cdef class ComplexBall(RingElement): sage: CBF(0,1).modular_j() [1728.0000000000 +/- ...e-11] - """ cdef ComplexBall result = self._new() if _do_sig(prec(self)): sig_on() @@ -4465,7 +4441,6 @@ cdef class ComplexBall(RingElement): [0.768225422326057 +/- ...e-16] sage: CBF(12,1).modular_eta() [-0.768225422326057 +/- ...e-16] - """ cdef ComplexBall result = self._new() if _do_sig(prec(self)): sig_on() @@ -4487,7 +4462,6 @@ cdef class ComplexBall(RingElement): [-0.00022005123884157 +/- ...e-18] + [-0.00079787346459944 +/- ...e-18]*I sage: (tau / (1 - 2*tau)).modular_lambda() [-0.00022005123884 +/- ...e-15] + [-0.00079787346460 +/- ...e-15]*I - """ cdef ComplexBall result = self._new() if _do_sig(prec(self)): sig_on() @@ -4509,7 +4483,6 @@ cdef class ComplexBall(RingElement): [0.20921376655 +/- ...e-12] + [1.57611925523 +/- ...e-12]*I sage: (c*tau+d)^12 * tau.modular_delta() [0.20921376654986 +/- ...e-15] + [1.5761192552253 +/- ...e-14]*I - """ cdef ComplexBall result = self._new() if _do_sig(prec(self)): sig_on() @@ -4536,7 +4509,6 @@ cdef class ComplexBall(RingElement): [331011.2004330 +/- ...e-8] + [-711178.1655746 +/- ...e-8]*I sage: (c*tau+d)^8 * tau.eisenstein(3)[2] [331011.20043304 +/- ...e-9] + [-711178.1655746 +/- ...e-8]*I - """ if n < 0: raise ValueError("n must be nonnegative") @@ -4581,7 +4553,6 @@ cdef class ComplexBall(RingElement): [[-3.28920996772709 +/- ...e-15] + [-0.00036737673029 +/- ...e-15]*I, [0.0024730557943 +/- ...e-14] + [0.0038595540403 +/- ...e-14]*I, [-0.01299087562 +/- ...e-12] + [0.00725027522 +/- ...e-12]*I] - """ cdef ComplexBall my_tau = self._parent.coerce(tau) cdef ComplexBall result @@ -4659,7 +4630,6 @@ cdef class ComplexBall(RingElement): sage: CBF(2,3).elliptic_k() [1.04291329192852 +/- ...e-15] + [0.62968247230864 +/- ...e-15]*I - """ cdef ComplexBall result = self._new() if _do_sig(prec(self)): sig_on() @@ -4676,7 +4646,6 @@ cdef class ComplexBall(RingElement): sage: CBF(2,3).elliptic_e() [1.472797144959 +/- ...e-13] + [-1.231604783936 +/- ...e-14]*I - """ cdef ComplexBall result = self._new() if _do_sig(prec(self)): sig_on() @@ -4693,7 +4662,6 @@ cdef class ComplexBall(RingElement): sage: CBF(2,3).elliptic_pi(CBF(1,1)) [0.2702999736198...] + [0.715676058329...]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_m = self._parent.coerce(m) @@ -4731,7 +4699,6 @@ cdef class ComplexBall(RingElement): [1.3393589639094 +/- ...e-14] + [1.1104369690719 +/- ...e-14]*I sage: phi.elliptic_k() [1.33935896390938 +/- ...e-15] + [1.11043696907194 +/- ...e-15]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_m = self._parent.coerce(m) @@ -4769,7 +4736,6 @@ cdef class ComplexBall(RingElement): [0.787564350925 +/- ...e-13] + [-0.686896129145 +/- ...e-13]*I sage: phi.elliptic_e() [0.7875643509254 +/- ...e-14] + [-0.686896129145 +/- ...e-13]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_m = self._parent.coerce(m) @@ -4834,7 +4800,6 @@ cdef class ComplexBall(RingElement): sage: CBF(0,1).elliptic_rf(CBF(-1/2,1), CBF(-1,-1)) [1.469800396738515 +/- ...e-16] + [-0.2358791199824196 +/- ...e-17]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_y = self._parent.coerce(y) @@ -4859,7 +4824,6 @@ cdef class ComplexBall(RingElement): sage: CBF(0,1).elliptic_rg(CBF(-1/2,1), CBF(-1,-1)) [0.1586786770922370 +/- ...e-17] + [0.2239733128130531 +/- ...e-17]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_y = self._parent.coerce(y) @@ -4886,7 +4850,6 @@ cdef class ComplexBall(RingElement): sage: CBF(0,1).elliptic_rj(CBF(-1/2,1), CBF(-1,-1), CBF(2)) [1.00438675628573...] + [-0.24516268343916...]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_y = self._parent.coerce(y) @@ -4899,7 +4862,7 @@ cdef class ComplexBall(RingElement): def elliptic_zeta(self, tau): r""" - Return the value of the Weierstrass zeta function at ``(self, tau)`` + Return the value of the Weierstrass zeta function at ``(self, tau)``. EXAMPLES:: @@ -4919,7 +4882,7 @@ cdef class ComplexBall(RingElement): def elliptic_sigma(self, tau): r""" - Return the value of the Weierstrass sigma function at ``(self, tau)`` + Return the value of the Weierstrass sigma function at ``(self, tau)``. EXAMPLES:: @@ -4929,7 +4892,6 @@ cdef class ComplexBall(RingElement): sage: CBF(1,1).elliptic_sigma(CBF(1,3)) [-0.543073363596 +/- ...e-13] + [3.6357291186244 +/- ...e-14]*I - """ cdef ComplexBall result = self._new() cdef ComplexBall my_tau = self._parent.coerce(tau) @@ -4949,7 +4911,6 @@ cdef class ComplexBall(RingElement): [0.8710045668809 +/- ...e-14] sage: CBF(1/3).chebyshev_T(CBF(5,1)) [1.84296854518763 +/- ...e-15] + [0.20053614301799 +/- ...e-15]*I - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall result = self._new() @@ -4969,7 +4930,6 @@ cdef class ComplexBall(RingElement): [0.6973126541184 +/- ...e-14] sage: CBF(1/3).chebyshev_U(CBF(5,1)) [1.75884964893425 +/- ...e-15] + [0.7497317165104 +/- ...e-14]*I - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall result = self._new() @@ -4987,7 +4947,6 @@ cdef class ComplexBall(RingElement): sage: CBF(5,-6).jacobi_P(8, CBF(1,2), CBF(2,3)) [-920983000.45982 +/- ...e-6] + [6069919969.92857 +/- ...e-6]*I - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall my_a = self._parent.coerce(a) @@ -5008,7 +4967,6 @@ cdef class ComplexBall(RingElement): sage: CBF(-10).gegenbauer_C(7, 1/2) [-263813415.6250000 +/- ...e-8] - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall my_m = self._parent.coerce(m) @@ -5053,7 +5011,6 @@ cdef class ComplexBall(RingElement): 20.00000000000000 sage: CBF(10).hermite_H(30) [8.0574670961707e+37 +/- ...e+23] - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall result = self._new() @@ -5082,7 +5039,6 @@ cdef class ComplexBall(RingElement): [-22104403.487377 +/- ...e-7] + [53364750.687392 +/- ...e-7]*I sage: CBF(-10).legendre_P(5, 325/100, type=3) [-57761589.914581 +/- ...e-7] + [+/- ...e-7]*I - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall my_m = self._parent.coerce(m) @@ -5116,7 +5072,6 @@ cdef class ComplexBall(RingElement): [-83825154.36008 +/- ...e-6] + [-34721515.80396 +/- ...e-6]*I sage: CBF(-10).legendre_Q(5, 325/100, type=3) [-4.797306921692e-6 +/- ...e-19] + [-4.797306921692e-6 +/- ...e-19]*I - """ cdef ComplexBall my_n = self._parent.coerce(n) cdef ComplexBall my_m = self._parent.coerce(m) diff --git a/src/sage/rings/complex_double.pyx b/src/sage/rings/complex_double.pyx index b4dddebb4dc..7f7c16ceb67 100644 --- a/src/sage/rings/complex_double.pyx +++ b/src/sage/rings/complex_double.pyx @@ -164,7 +164,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): cpdef bint is_exact(self) except -2: """ - Returns whether or not this field is exact, which is always ``False``. + Return whether or not this field is exact, which is always ``False``. EXAMPLES:: @@ -260,9 +260,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - a string. + OUTPUT: string TESTS:: @@ -302,7 +300,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): sage: CDF(mpc('2.0+1.0j')) 2.0 + 1.0*I - A ``TypeError`` is raised if the coercion doesn't make sense:: + A :exc:`TypeError` is raised if the coercion doesn't make sense:: sage: CDF(QQ['x'].0) Traceback (most recent call last): @@ -379,7 +377,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): cpdef _coerce_map_from_(self, S): """ Return the canonical coerce of `x` into the complex double field, if - it is defined, otherwise raise a ``TypeError``. + it is defined, otherwise raise a :exc:`TypeError`. The rings that canonically coerce to the complex double field are: @@ -487,7 +485,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): def to_prec(self, prec): """ - Returns the complex field to the specified precision. As doubles + Return the complex field to the specified precision. As doubles have fixed precision, this will only return a complex double field if prec is exactly 53. @@ -534,7 +532,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): def algebraic_closure(self): r""" - Returns the algebraic closure of ``self``, i.e., the complex double + Return the algebraic closure of ``self``, i.e., the complex double field. EXAMPLES:: @@ -558,7 +556,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): def pi(self): r""" - Returns `\pi` as a double precision complex number. + Return `\pi` as a double precision complex number. EXAMPLES:: @@ -569,7 +567,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): def construction(self): """ - Returns the functorial construction of ``self``, namely, algebraic + Return the functorial construction of ``self``, namely, algebraic closure of the real double field. EXAMPLES:: @@ -589,9 +587,9 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): INPUT: - - ``n`` -- a positive integer (default: 2) + - ``n`` -- positive integer (default: 2) - OUTPUT: a complex `n`-th root of unity. + OUTPUT: a complex `n`-th root of unity EXAMPLES:: @@ -677,7 +675,6 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): sage: F = f.factor() sage: [f(t[0][0]).abs() for t in F] # abs tol 1e-9 [1.979365054e-14, 1.97936298566e-14, 1.97936990747e-14, 3.6812407475e-14, 3.65211563729e-14, 3.65220890052e-14] - """ unit = f.leading_coefficient() f *= ~unit @@ -691,7 +688,7 @@ cdef class ComplexDoubleField_class(sage.rings.abc.ComplexDoubleField): cdef ComplexDoubleElement new_ComplexDoubleElement(): """ - Creates a new (empty) :class:`ComplexDoubleElement`. + Create a new (empty) :class:`ComplexDoubleElement`. """ cdef ComplexDoubleElement z z = ComplexDoubleElement.__new__(ComplexDoubleElement) @@ -745,7 +742,7 @@ cdef class ComplexDoubleElement(FieldElement): def __init__(self, real, imag): """ - Constructs an element of a complex double field with specified real + Construct an element of a complex double field with specified real and imaginary values. EXAMPLES:: @@ -779,7 +776,7 @@ cdef class ComplexDoubleElement(FieldElement): def __hash__(self): """ - Returns the hash of ``self``, which coincides with the python ``float`` + Return the hash of ``self``, which coincides with the python ``float`` and ``complex`` (and often ``int``) types for ``self``. EXAMPLES:: @@ -843,13 +840,13 @@ cdef class ComplexDoubleElement(FieldElement): def __getitem__(self, n): """ - Returns the real or imaginary part of ``self``. + Return the real or imaginary part of ``self``. INPUT: - - ``n`` -- integer (either 0 or 1) + - ``n`` -- integer (either 0 or 1) - Raises an ``IndexError`` if ``n`` is not 0 or 1. + Raises an :exc:`IndexError` if ``n`` is not 0 or 1. EXAMPLES:: @@ -889,7 +886,7 @@ cdef class ComplexDoubleElement(FieldElement): def prec(self): """ - Returns the precision of this number (to be more similar to + Return the precision of this number (to be more similar to :class:`ComplexNumber`). Always returns 53. EXAMPLES:: @@ -961,7 +958,7 @@ cdef class ComplexDoubleElement(FieldElement): def _interface_init_(self, I=None): """ - Returns ``self`` formatted as a string, suitable as input to another + Return ``self`` formatted as a string, suitable as input to another computer algebra system. (This is the default function used for exporting to other computer algebra systems.) @@ -1470,8 +1467,8 @@ cdef class ComplexDoubleElement(FieldElement): INPUT: - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots If all is ``False``, the branch cut is the negative real axis. The result always lies in the right half of the complex plane. @@ -1512,8 +1509,8 @@ cdef class ComplexDoubleElement(FieldElement): INPUT: - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all ``n``-th roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all ``n``-th roots EXAMPLES:: @@ -1550,7 +1547,7 @@ cdef class ComplexDoubleElement(FieldElement): def is_integer(self): """ - Return ``True`` if this number is a integer + Return ``True`` if this number is a integer. EXAMPLES:: @@ -1740,7 +1737,7 @@ cdef class ComplexDoubleElement(FieldElement): INPUT: - - ``base`` -- default: `e`, the base of the natural logarithm + - ``base`` -- (default: `e`) the base of the natural logarithm EXAMPLES:: @@ -2155,15 +2152,15 @@ cdef class ComplexDoubleElement(FieldElement): ####################################################################### def eta(self, int omit_frac=0): r""" - Return the value of the Dedekind `\eta` function on self. + Return the value of the Dedekind `\eta` function on ``self``. INPUT: - - ``self`` -- element of the upper half plane (if not, - raises a ValueError). + - ``self`` -- element of the upper half plane (if not, + raises a ValueError) - - ``omit_frac`` -- (bool, default: ``False``), if ``True``, - omit the `e^{\pi i z / 12}` factor. + - ``omit_frac`` -- boolean (default: ``False``); if ``True``, + omit the `e^{\pi i z / 12}` factor OUTPUT: a complex double number @@ -2247,20 +2244,20 @@ cdef class ComplexDoubleElement(FieldElement): cdef int flag = 0 if omit_frac else 1 return complex_double_element_eta(self, flag) - def agm(self, right, algorithm="optimal"): + def agm(self, right, algorithm='optimal'): r""" Return the Arithmetic-Geometric Mean (AGM) of ``self`` and ``right``. INPUT: - - ``right`` (complex) -- another complex number + - ``right`` -- complex; another complex number - - ``algorithm`` (string, default ``"optimal"``) -- the algorithm to use - (see below). + - ``algorithm`` -- string (default: ``'optimal'``); the algorithm to + use (see below) OUTPUT: - (complex) A value of the AGM of self and right. Note that + (complex) A value of the AGM of ``self`` and ``right``. Note that this is a multi-valued function, and the algorithm used affects the value returned, as follows: @@ -2349,7 +2346,7 @@ cdef class ComplexDoubleElement(FieldElement): def dilog(self): r""" - Returns the principal branch of the dilogarithm of `x`, i.e., analytic + Return the principal branch of the dilogarithm of `x`, i.e., analytic continuation of the power series .. MATH:: @@ -2444,7 +2441,7 @@ cdef class ComplexDoubleElement(FieldElement): def algdep(self, long n): """ - Returns a polynomial of degree at most `n` which is + Return a polynomial of degree at most `n` which is approximately satisfied by this complex number. Note that the returned polynomial need not be irreducible, and indeed usually won't be if `z` is a good approximation to an algebraic @@ -2501,7 +2498,6 @@ cdef class FloatToCDF(Morphism): To: Complex Double Field sage: f(3.5) 3.5 - """ def __init__(self, R): """ @@ -2610,7 +2606,7 @@ cdef ComplexDoubleElement I = ComplexDoubleElement(0,1) def ComplexDoubleField(): """ - Returns the field of double precision complex numbers. + Return the field of double precision complex numbers. EXAMPLES:: diff --git a/src/sage/rings/complex_interval.pyx b/src/sage/rings/complex_interval.pyx index aeda223a17f..ff6b4fe4d6c 100644 --- a/src/sage/rings/complex_interval.pyx +++ b/src/sage/rings/complex_interval.pyx @@ -208,7 +208,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): return self.imag() raise IndexError("i must be between 0 and 1.") - def __reduce__( self ): + def __reduce__(self): """ Pickling support. @@ -271,7 +271,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): INPUT: - ``parent`` -- :class:`~sage.rings.real_mpfr.RealField_class`, - target parent. + target parent EXAMPLES:: @@ -532,7 +532,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): def overlaps(self, ComplexIntervalFieldElement other): """ - Return ``True`` if ``self`` and other are intervals with at least + Return ``True`` if ``self`` and ``other`` are intervals with at least one value in common. EXAMPLES:: @@ -854,19 +854,19 @@ cdef class ComplexIntervalFieldElement(FieldElement): Note that ``x^2`` is not the same as ``x*x``:: sage: a = CIF(RIF(-1,1)) - sage: print((a^2).str(style="brackets")) + sage: print((a^2).str(style='brackets')) [0.0000000000000000 .. 1.0000000000000000] - sage: print((a*a).str(style="brackets")) + sage: print((a*a).str(style='brackets')) [-1.0000000000000000 .. 1.0000000000000000] sage: a = CIF(0, RIF(-1,1)) - sage: print((a^2).str(style="brackets")) + sage: print((a^2).str(style='brackets')) [-1.0000000000000000 .. -0.0000000000000000] - sage: print((a*a).str(style="brackets")) + sage: print((a*a).str(style='brackets')) [-1.0000000000000000 .. 1.0000000000000000] sage: a = CIF(RIF(-1,1), RIF(-1,1)) - sage: print((a^2).str(style="brackets")) + sage: print((a^2).str(style='brackets')) [-1.0000000000000000 .. 1.0000000000000000] + [-2.0000000000000000 .. 2.0000000000000000]*I - sage: print((a*a).str(style="brackets")) + sage: print((a*a).str(style='brackets')) [-2.0000000000000000 .. 2.0000000000000000] + [-2.0000000000000000 .. 2.0000000000000000]*I We can take very high powers:: @@ -876,7 +876,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): sage: s = RealField(27, rnd="RNDZ")(1/2)^(1/3) sage: a = CIF(RIF(-s/2,s/2), RIF(-s, s)) sage: r = a^(10^10000) - sage: print(r.str(style="brackets")) + sage: print(r.str(style='brackets')) [-2.107553304e1028 .. 2.107553304e1028] + [-2.107553304e1028 .. 2.107553304e1028]*I TESTS:: @@ -973,13 +973,13 @@ cdef class ComplexIntervalFieldElement(FieldElement): def _interface_init_(self, I=None): """ - Raise a ``TypeError``. + Raise a :exc:`TypeError`. This function would return the string representation of ``self`` that makes sense as a default representation of a complex interval in other computer algebra systems. But, most other computer algebra systems do not support interval arithmetic, - so instead we just raise a ``TypeError``. + so instead we just raise a :exc:`TypeError`. Define the appropriate ``_cas_init_`` function if there is a computer algebra system you would like to support. @@ -992,7 +992,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): ... TypeError - Here a conversion to Maxima happens, which results in a ``TypeError``:: + Here a conversion to Maxima happens, which results in a :exc:`TypeError`:: sage: a = CIF(2.3) sage: maxima(a) # needs sage.symbolic @@ -1571,7 +1571,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): def multiplicative_order(self): """ Return the multiplicative order of this complex number, if known, - or raise a ``NotImplementedError``. + or raise a :exc:`NotImplementedError`. EXAMPLES:: @@ -1614,7 +1614,7 @@ cdef class ComplexIntervalFieldElement(FieldElement): The argument (angle) of the complex number, normalized so that `-\pi < \theta.lower() \leq \pi`. - We raise a ``ValueError`` if the interval strictly contains 0, + We raise a :exc:`ValueError` if the interval strictly contains 0, or if the interval contains only 0. .. WARNING:: @@ -1854,8 +1854,8 @@ cdef class ComplexIntervalFieldElement(FieldElement): INPUT: - - ``all`` -- bool (default: ``False``); if ``True``, return a list - of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a list + of all square roots EXAMPLES:: @@ -2389,6 +2389,7 @@ cdef _circle_invert_standard( if crosses_NE_diagonal: mpfr_clear(min2) + def make_ComplexIntervalFieldElement0( fld, re, im ): """ Construct a :class:`ComplexIntervalFieldElement` for pickling. @@ -2410,16 +2411,16 @@ def create_ComplexIntervalFieldElement(s_real, s_imag=None, int pad=0, min_prec= INPUT: - - ``s_real`` -- a string that defines a real number (or something whose + - ``s_real`` -- string that defines a real number (or something whose string representation defines a number) - - ``s_imag`` -- a string that defines a real number (or something whose + - ``s_imag`` -- string that defines a real number (or something whose string representation defines a number) - - ``pad`` -- an integer at least 0. + - ``pad`` -- integer at least 0 - ``min_prec`` -- number will have at least this many bits of precision, - no matter what. + no matter what EXAMPLES:: @@ -2454,7 +2455,6 @@ def create_ComplexIntervalFieldElement(s_real, s_imag=None, int pad=0, min_prec= ....: assert c_CIFE(0,s).imag()-1 != 0 ....: except TypeError: ....: pass - """ if s_imag is None: s_imag = 0 diff --git a/src/sage/rings/complex_interval_field.py b/src/sage/rings/complex_interval_field.py index 372d84abca8..0b6981cf07b 100644 --- a/src/sage/rings/complex_interval_field.py +++ b/src/sage/rings/complex_interval_field.py @@ -148,7 +148,7 @@ class ComplexIntervalField_class(sage.rings.abc.ComplexIntervalField): sage: CIF.category() Category of infinite fields - sage: TestSuite(CIF).run(skip="_test_gcd_vs_xgcd") + sage: TestSuite(CIF).run(skip='_test_gcd_vs_xgcd') TESTS: @@ -195,7 +195,7 @@ def __init__(self, prec=53): from sage.categories.fields import Fields Field.__init__(self, self.real_field(), ("I",), False, category=Fields().Infinite()) - self._populate_coercion_lists_(convert_method_name="_complex_mpfi_") + self._populate_coercion_lists_(convert_method_name='_complex_mpfi_') def __reduce__(self): """ @@ -210,7 +210,7 @@ def __reduce__(self): def construction(self): """ - Returns the functorial construction of this complex interval field, + Return the functorial construction of this complex interval field, namely as the algebraic closure of the real interval field with the same precision. @@ -254,7 +254,7 @@ def is_exact(self): def prec(self): """ - Returns the precision of ``self`` (in bits). + Return the precision of ``self`` (in bits). EXAMPLES:: @@ -267,7 +267,7 @@ def prec(self): def to_prec(self, prec): """ - Returns a complex interval field with the given precision. + Return a complex interval field with the given precision. EXAMPLES:: @@ -625,7 +625,7 @@ def is_field(self, proof=True): def pi(self): r""" - Returns `\pi` as an element in the complex (interval) field. + Return `\pi` as an element in the complex (interval) field. EXAMPLES:: @@ -659,11 +659,9 @@ def zeta(self, n=2): INPUT: - - ``n`` -- an integer (default: 2) + - ``n`` -- integer (default: 2) - OUTPUT: - - A complex `n`-th root of unity. + OUTPUT: a complex `n`-th root of unity EXAMPLES:: diff --git a/src/sage/rings/complex_mpc.pyx b/src/sage/rings/complex_mpc.pyx index eda06a9fc2c..9b56a36ce9f 100644 --- a/src/sage/rings/complex_mpc.pyx +++ b/src/sage/rings/complex_mpc.pyx @@ -237,7 +237,7 @@ cpdef inline split_complex_string(string, int base=10): cache = {} -def MPComplexField(prec=53, rnd="RNDNN", names=None): +def MPComplexField(prec=53, rnd='RNDNN', names=None): """ Return the complex field with real and imaginary parts having prec *bits* of precision. @@ -273,12 +273,12 @@ cdef class MPComplexField_class(Field): INPUT: - - ``prec`` -- (integer) precision; default = 53 + - ``prec`` -- integer (default: 53); precision prec is the number of bits used to represent the mantissa of both the real and imaginary part of complex floating-point number. - - ``rnd`` -- (string) the rounding mode; default = ``'RNDNN'`` + - ``rnd`` -- string (default: ``'RNDNN'``); the rounding mode Rounding mode is of the form ``'RNDxy'`` where ``x`` and ``y`` are the rounding mode for respectively the real and imaginary parts and @@ -333,7 +333,7 @@ cdef class MPComplexField_class(Field): cdef MPComplexNumber _new(self): """ - Return a new complex number with parent ``self`. + Return a new complex number with parent ``self``. """ cdef MPComplexNumber z z = MPComplexNumber.__new__(MPComplexNumber) @@ -582,7 +582,7 @@ cdef class MPComplexField_class(Field): cpdef bint is_exact(self) except -2: """ - Returns whether or not this field is exact, which is always ``False``. + Return whether or not this field is exact, which is always ``False``. EXAMPLES:: @@ -958,7 +958,7 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): def __hash__(self): """ - Returns the hash of ``self``, which coincides with the python + Return the hash of ``self``, which coincides with the python complex and float (and often int) types. This has the drawback that two very close high precision @@ -974,7 +974,7 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): def __getitem__(self, i): r""" - Returns either the real or imaginary component of ``self`` + Return either the real or imaginary component of ``self`` depending on the choice of ``i``: real (``i``=0), imaginary (``i``=1). INPUT: @@ -1064,7 +1064,7 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): - ``base`` -- (default: 10) base for output - ``**kwds`` -- other arguments to pass to the ``str()`` - method of the real numbers in the real and imaginary parts. + method of the real numbers in the real and imaginary parts EXAMPLES:: @@ -1561,7 +1561,7 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): EXAMPLES: This indeed acts as the square function when the imaginary - component of self is equal to zero:: + component of ``self`` is equal to zero:: sage: MPC = MPComplexField() sage: a = MPC(2,1) @@ -2131,8 +2131,8 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): INPUT: - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all `n`-th roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all `n`-th roots EXAMPLES:: @@ -2227,11 +2227,11 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): INPUT: - - ``self`` -- element of the upper half plane (if not, - raises a ``ValueError``). + - ``self`` -- element of the upper half plane (if not, + raises a :exc:`ValueError`) - - ``omit_frac`` -- (bool, default: ``False``), if ``True``, - omit the `e^{\pi i z / 12}` factor. + - ``omit_frac`` -- -- boolean (default: ``False``); if ``True``, + omit the `e^{\pi i z / 12}` factor OUTPUT: a complex number @@ -2289,7 +2289,6 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): -0.0013781309 + 0.0065198200*I sage: C(2).gamma_inc(1 + i) 0.70709210 - 0.42035364*I - """ return self._parent(self.__pari__().incgam(t, precision=self.prec())) @@ -2306,7 +2305,7 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): """ return self._parent(self.__pari__().zeta()) - def agm(self, right, algorithm="optimal"): + def agm(self, right, algorithm='optimal'): """ Return the algebro-geometric mean of ``self`` and ``right``. @@ -2315,11 +2314,11 @@ cdef class MPComplexNumber(sage.structure.element.FieldElement): sage: MPC = MPComplexField() sage: u = MPC(1, 4) sage: v = MPC(-2,5) - sage: u.agm(v, algorithm="pari") + sage: u.agm(v, algorithm='pari') -0.410522769709397 + 4.60061063922097*I - sage: u.agm(v, algorithm="principal") + sage: u.agm(v, algorithm='principal') 1.24010691168158 - 0.472193567796433*I - sage: u.agm(v, algorithm="optimal") + sage: u.agm(v, algorithm='optimal') -0.410522769709397 + 4.60061063922097*I """ if algorithm == "pari": @@ -2425,7 +2424,6 @@ def __create__MPComplexField_version0 (prec, rnd): sage: sage.rings.complex_mpc.__create__MPComplexField_version0(200, 'RNDDZ') Complex Field with 200 bits of precision and rounding RNDDZ - """ return MPComplexField(prec, rnd) diff --git a/src/sage/rings/complex_mpfr.pyx b/src/sage/rings/complex_mpfr.pyx index 79c06af06d5..415dd00c78f 100644 --- a/src/sage/rings/complex_mpfr.pyx +++ b/src/sage/rings/complex_mpfr.pyx @@ -29,7 +29,7 @@ AUTHORS: # the License, or (at your option) any later version. # https://www.gnu.org/licenses/ # **************************************************************************** - +import re import weakref import sage.misc.misc @@ -41,8 +41,6 @@ from sage.structure.element cimport RingElement, Element from sage.structure.richcmp cimport rich_to_bool from sage.categories.map cimport Map -from sage.misc.sage_eval import sage_eval - import sage.rings.abc from sage.arith.constants cimport LOG_TEN_TWO_PLUS_EPSILON from sage.rings import infinity @@ -70,6 +68,10 @@ AA = None QQbar = None CDF = CLF = RLF = None +# useful for parsing +NUMBERS = re.compile("[0-9]") +BLOCK = re.compile(r'[+-]?(?:I\*|)[0-9\.]*(?:e[+-]?[0-9]*|)\*?I?') + def late_import(): """ @@ -496,10 +498,26 @@ class ComplexField_class(sage.rings.abc.ComplexField): sage: CC('1.2+3.4*j') 1.20000000000000 + 3.40000000000000*I + sage: CC("+4-13.59658451496887*I") + 4.00000000000000 - 13.5965845149689*I + sage: CC('1.2*I+3.4') + 3.40000000000000 + 1.20000000000000*I + sage: CC('1.2*I') + 1.20000000000000*I + sage: CC('9-I*1.2') + 9.00000000000000 - 1.20000000000000*I + sage: CC('3.4') + 3.40000000000000 + sage: CC('3.4e-6+7.8e11*I') + 3.40000000000000e-6 + 7.80000000000000e11*I sage: CC('hello') Traceback (most recent call last): ... ValueError: given string 'hello' is not a complex number + sage: CC('1+2+3*I') + Traceback (most recent call last): + ... + ValueError: given string '1+2+3*I' is not a complex number """ if not isinstance(x, (RealNumber, tuple)): if isinstance(x, ComplexDoubleElement): @@ -512,24 +530,35 @@ class ComplexField_class(sage.rings.abc.ComplexField): allowed = '+-.*0123456789Ie' if len(x) == 0 or not all(letter in allowed for letter in x): raise ValueError(f'given string {x!r} is not a complex number') - # This should rather use a proper parser to validate input. - # TODO: this is probably not the best and most - # efficient way to do this. -- Martin Albrecht - return ComplexNumber(self, - sage_eval(x, locals={"I": self.gen()})) + split = [group for group in BLOCK.findall(x) if group] + N = len(split) + if N == 1: + split = split[0] + real, imag = ('0', split) if 'I' in split else (split, '0') + elif N == 2: + real, imag = split + if 'I' in real: + real, imag = imag, real + else: + raise ValueError(f'given string {x!r} is not a complex number') + if not NUMBERS.search(imag): + imag = imag.replace('I', '1') + else: + imag = imag.replace('*', '').replace('I', '') + return ComplexNumber(self, real, imag) late_import() if isinstance(x, NumberFieldElement_quadratic): if isinstance(x.parent(), sage.rings.abc.NumberField_quadratic) and list(x.parent().polynomial()) == [1, 0, 1]: - (re, im) = list(x) - return ComplexNumber(self, re, im) + real, imag = list(x) + return ComplexNumber(self, real, imag) try: return self(x.sage()) except (AttributeError, TypeError): pass try: - return x._complex_mpfr_field_( self ) + return x._complex_mpfr_field_(self) except AttributeError: pass return ComplexNumber(self, x) @@ -718,9 +747,9 @@ class ComplexField_class(sage.rings.abc.ComplexField): True """ size = self._real_field()(component_max) - re = self._real_field().random_element(-size, size, *args, **kwds) - im = self._real_field().random_element(-size, size, *args, **kwds) - return self(re, im) + real = self._real_field().random_element(-size, size, *args, **kwds) + imag = self._real_field().random_element(-size, size, *args, **kwds) + return self(real, imag) def pi(self): r""" @@ -754,9 +783,9 @@ class ComplexField_class(sage.rings.abc.ComplexField): INPUT: - - ``n`` -- an integer (default: 2) + - ``n`` -- integer (default: 2) - OUTPUT: a complex `n`-th root of unity. + OUTPUT: a complex `n`-th root of unity EXAMPLES:: @@ -855,7 +884,6 @@ class ComplexField_class(sage.rings.abc.ComplexField): (x - I) * (x + I) sage: k._factor_univariate_polynomial(k(I) * (x^2 + 1)) (1.0000000000000000000000000000*I) * (x - I) * (x + I) - """ R = f.parent() @@ -890,7 +918,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): cdef ComplexNumber _new(self): """ - Quickly creates a new initialized complex number with the same + Quickly create a new initialized complex number with the same parent as ``self``. """ cdef ComplexNumber x @@ -953,8 +981,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): elif isinstance(real, pari_gen): real, imag = real.real(), real.imag() elif isinstance(real, (list, tuple)): - re, imag = real - real = re + real, imag = real elif isinstance(real, complex): real, imag = real.real, real.imag elif type(real) is gmpy2.mpc: @@ -1172,8 +1199,8 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): def __getitem__(self, i): r""" - Return either the real or imaginary component of self depending on - the choice of i: real (i=0), imaginary (i=1) + Return either the real or imaginary component of ``self`` depending on + the choice of ``i``: real (``i=0``), imaginary (``i=1``). INPUT: @@ -1205,7 +1232,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): def __reduce__(self): """ - Pickling support + Pickling support. EXAMPLES:: @@ -1230,7 +1257,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): INPUT: - - ``n`` -- an integer which will define the multiplicative order + - ``n`` -- integer which will define the multiplicative order EXAMPLES:: @@ -1253,10 +1280,10 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): - ``base`` -- (default: 10) base for output - - ``istr`` -- (default: ``I``) String representation of the complex unit + - ``istr`` -- (default: ``I``) string representation of the complex unit - ``**kwds`` -- other arguments to pass to the ``str()`` - method of the real numbers in the real and imaginary parts. + method of the real numbers in the real and imaginary parts EXAMPLES:: @@ -1373,7 +1400,6 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): sage: ComplexNumber(0).log()._latex_() '-\\infty' """ - import re s = repr(self).replace('*I', 'i').replace('infinity','\\infty') return re.sub(r"e(-?\d+)", r" \\times 10^{\1}", s) @@ -1460,9 +1486,9 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): if prec is not None: return ComplexField(prec)(self)._mpmath_() from sage.libs.mpmath.all import make_mpc - re = mpfr_to_mpfval(self.__re) - im = mpfr_to_mpfval(self.__im) - return make_mpc((re, im)) + real = mpfr_to_mpfval(self.__re) + imag = mpfr_to_mpfval(self.__im) + return make_mpc((real, imag)) def _sympy_(self): """ @@ -1836,7 +1862,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): def __abs__(self): r""" - Method for computing the absolute value or modulus of ``self`` + Method for computing the absolute value or modulus of ``self``. .. MATH:: @@ -2004,7 +2030,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): def multiplicative_order(self): """ Return the multiplicative order of this complex number, if known, - or raise a :class:`NotImplementedError`. + or raise a :exc:`NotImplementedError`. EXAMPLES:: @@ -2050,7 +2076,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): def plot(self, **kargs): """ - Plots this complex number as a point in the plane + Plots this complex number as a point in the plane. The accepted options are the ones of :meth:`~sage.plot.point.point2d`. Type ``point2d.options`` to see all options. @@ -2328,11 +2354,11 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): INPUT: - - ``self`` -- element of the upper half plane (if not, - raises a :class:`ValueError`). + - ``self`` -- element of the upper half plane (if not, + raises a :exc:`ValueError`) - - ``omit_frac`` -- (bool, default: ``False``), if ``True``, - omit the `e^{\pi i z / 12}` factor. + - ``omit_frac`` -- -- boolean (default: ``False``); if ``True``, + omit the `e^{\pi i z / 12}` factor OUTPUT: a complex number @@ -2512,16 +2538,16 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): return z # Other special functions - def agm(self, right, algorithm="optimal"): + def agm(self, right, algorithm='optimal'): r""" Return the Arithmetic-Geometric Mean (AGM) of ``self`` and ``right``. INPUT: - - ``right`` (complex) -- another complex number + - ``right`` -- complex; another complex number - - ``algorithm`` (string, default ``"optimal"``) -- the algorithm to use - (see below). + - ``algorithm`` -- string (default: ``'optimal'``); the algorithm to use + (see below) OUTPUT: @@ -2529,15 +2555,15 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): this is a multi-valued function, and the algorithm used affects the value returned, as follows: - - ``"pari"``: Call the :pari:`agm` function from the PARI library. + - ``'pari'``: Call the :pari:`agm` function from the PARI library. - - ``"optimal"``: Use the AGM sequence such that at each stage + - ``'optimal'``: Use the AGM sequence such that at each stage `(a,b)` is replaced by `(a_1,b_1)=((a+b)/2,\pm\sqrt{ab})` where the sign is chosen so that `|a_1-b_1|\le|a_1+b_1|`, or equivalently `\Re(b_1/a_1)\ge 0`. The resulting limit is maximal among all possible values. - - ``"principal"``: Use the AGM sequence such that at each stage + - ``'principal'``: Use the AGM sequence such that at each stage `(a,b)` is replaced by `(a_1,b_1)=((a+b)/2,\pm\sqrt{ab})` where the sign is chosen so that `\Re(b_1)\ge 0` (the so-called principal branch of the square root). @@ -2550,11 +2576,11 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): sage: b = CC(2,-1) sage: a.agm(b) 1.62780548487271 + 0.136827548397369*I - sage: a.agm(b, algorithm="optimal") + sage: a.agm(b, algorithm='optimal') 1.62780548487271 + 0.136827548397369*I - sage: a.agm(b, algorithm="principal") + sage: a.agm(b, algorithm='principal') 1.62780548487271 + 0.136827548397369*I - sage: a.agm(b, algorithm="pari") # needs sage.libs.pari + sage: a.agm(b, algorithm='pari') # needs sage.libs.pari 1.62780548487271 + 0.136827548397369*I An example to show that the returned value depends on the algorithm @@ -2562,17 +2588,17 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): sage: a = CC(-0.95,-0.65) sage: b = CC(0.683,0.747) - sage: a.agm(b, algorithm="optimal") + sage: a.agm(b, algorithm='optimal') -0.371591652351761 + 0.319894660206830*I - sage: a.agm(b, algorithm="principal") + sage: a.agm(b, algorithm='principal') 0.338175462986180 - 0.0135326969565405*I - sage: a.agm(b, algorithm="pari") # needs sage.libs.pari + sage: a.agm(b, algorithm='pari') # needs sage.libs.pari -0.371591652351761 + 0.319894660206830*I - sage: a.agm(b, algorithm="optimal").abs() + sage: a.agm(b, algorithm='optimal').abs() 0.490319232466314 - sage: a.agm(b, algorithm="principal").abs() + sage: a.agm(b, algorithm='principal').abs() 0.338446122230459 - sage: a.agm(b, algorithm="pari").abs() # needs sage.libs.pari + sage: a.agm(b, algorithm='pari').abs() # needs sage.libs.pari 0.490319232466314 TESTS: @@ -2882,7 +2908,6 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): sage: C = ComplexField(400) sage: C(2 + I).gamma_inc(C(3 + I)) # abs tol 1e-120 # needs sage.libs.pari 0.121515644664508695525971545977439666159749344176962379708992904126499444842886620664991650378432544392118359044438541515 + 0.101533909079826033296475736021224621546966200987295663190553587086145836461236284668967411665020429964946098113930918850*I - """ return self._parent(self.__pari__().incgam(t, precision=self.prec())) @@ -2967,8 +2992,8 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): INPUT: - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots EXAMPLES:: @@ -3036,8 +3061,8 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): INPUT: - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all `n`-th roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all `n`-th roots EXAMPLES:: @@ -3252,7 +3277,7 @@ cdef class ComplexNumber(sage.structure.element.FieldElement): algdep = algebraic_dependency -def make_ComplexNumber0(fld, mult_order, re, im): +def make_ComplexNumber0(fld, mult_order, real, imag): """ Create a complex number for pickling. @@ -3262,7 +3287,7 @@ def make_ComplexNumber0(fld, mult_order, re, im): sage: loads(dumps(a)) == a # indirect doctest True """ - x = ComplexNumber(fld, re, im) + x = ComplexNumber(fld, real, imag) x._set_multiplicative_order(mult_order) return x @@ -3276,16 +3301,16 @@ def create_ComplexNumber(s_real, s_imag=None, int pad=0, min_prec=53): INPUT: - - ``s_real`` -- a string that defines a real number + - ``s_real`` -- string that defines a real number (or something whose string representation defines a number) - - ``s_imag`` -- a string that defines a real number + - ``s_imag`` -- string that defines a real number (or something whose string representation defines a number) - - ``pad`` -- an integer at least 0. + - ``pad`` -- integer at least 0 - ``min_prec`` -- number will have at least this many bits of precision, - no matter what. + no matter what EXAMPLES:: @@ -3317,7 +3342,6 @@ def create_ComplexNumber(s_real, s_imag=None, int pad=0, min_prec=53): False sage: sage.rings.complex_mpfr.create_ComplexNumber(0,s).imag()-1 == 0 False - """ if s_imag is None: s_imag = 0 @@ -3360,11 +3384,9 @@ cdef class RRtoCC(Map): INPUT: - - ``_slots`` -- a dictionary - - OUTPUT: + - ``_slots`` -- dictionary - The given dictionary, with zero added. + OUTPUT: the given dictionary, with zero added EXAMPLES:: @@ -3386,7 +3408,7 @@ cdef class RRtoCC(Map): INPUT: - - ``_slots`` -- a dictionary providing values for the c(p)def slots of self. + - ``_slots`` -- dictionary providing values for the c(p)def slots of ``self`` EXAMPLES:: @@ -3537,7 +3559,6 @@ def _format_complex_number(real, imag, format_spec): ... ValueError: '=' alignment not allowed in complex format specifier """ - import re match = re.match(r'^(.?[><=^])?' # 1: fill and align r'([ +-]?)' # 2: sign r'[^\d\.]*?0?(\d*)' # 3: width diff --git a/src/sage/rings/continued_fraction.py b/src/sage/rings/continued_fraction.py index c51b64261ab..62534d69f99 100644 --- a/src/sage/rings/continued_fraction.py +++ b/src/sage/rings/continued_fraction.py @@ -265,7 +265,7 @@ def rat_interval_cf_list(r1, r2): Return the common prefix of the rationals ``r1`` and ``r2`` seen as continued fractions. - OUTPUT: a list of Sage integers. + OUTPUT: list of Sage integers EXAMPLES:: @@ -362,9 +362,9 @@ def str(self, nterms=10, unicode=False, join=True): - ``nterms`` -- the maximum number of terms to use - - ``unicode`` -- (default ``False``) whether to use unicode character + - ``unicode`` -- (default: ``False``) whether to use unicode character - - ``join`` -- (default ``True``) if ``False`` instead of returning a + - ``join`` -- (default: ``True``) if ``False`` instead of returning a string return a list of string, each of them representing a line EXAMPLES:: @@ -823,7 +823,7 @@ def denominator(self, n): def convergent(self, n): """ - Return the ``n``-th partial convergent to self. + Return the ``n``-th partial convergent to ``self``. EXAMPLES:: @@ -1174,9 +1174,10 @@ def apply_homography(self, a, b, c, d, forward_value=False): - ``a``, ``b``, ``c``, ``d`` -- integers - - ``forward_value`` -- boolean (default: ``False``) whether the returned continued - fraction is given the symbolic value of `(a x + b)/(cx + d)` and not only the - list of partial quotients obtained from Gosper's algorithm. + - ``forward_value`` -- boolean (default: ``False``); whether the + returned continued fraction is given the symbolic value of + `(a x + b)/(cx + d)` and not only the list of partial quotients + obtained from Gosper's algorithm EXAMPLES:: @@ -1312,9 +1313,9 @@ def __init__(self, x1, x2=None, check=True): r""" INPUT: - - ``x1`` -- a tuple of integers + - ``x1`` -- tuple of integers - - ``x2`` -- a tuple of integers + - ``x2`` -- tuple of integers TESTS:: @@ -1840,7 +1841,7 @@ def __init__(self, x): def length(self): r""" - Return infinity + Return infinity. EXAMPLES:: @@ -2065,8 +2066,7 @@ def __init__(self, w, value=None, check=True): - ``value`` -- an optional known value - - ``check`` -- whether the constructor checks the input (default is - ``True``) + - ``check`` -- whether the constructor checks the input (default: ``True``) TESTS:: @@ -2077,11 +2077,11 @@ def __init__(self, w, value=None, check=True): ValueError: the sequence must consist of integers sage: from itertools import count - sage: w = Word(count(), length="infinite") # needs sage.combinat + sage: w = Word(count(), length='infinite') # needs sage.combinat sage: continued_fraction(w) # needs sage.combinat [0; 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19...] - sage: w = Word(count(), length="unknown") # needs sage.combinat + sage: w = Word(count(), length='unknown') # needs sage.combinat sage: continued_fraction(w) # needs sage.combinat Traceback (most recent call last): ... @@ -2157,7 +2157,7 @@ def quotient(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -2192,7 +2192,7 @@ def _Integer_quotient(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -2333,7 +2333,7 @@ def check_and_reduce_pair(x1, x2=None): return tuple(y1), tuple(y2) -def continued_fraction_list(x, type="std", partial_convergents=False, +def continued_fraction_list(x, type='std', partial_convergents=False, bits=None, nterms=None): r""" Return the (finite) continued fraction of ``x`` as a list. @@ -2358,20 +2358,20 @@ def continued_fraction_list(x, type="std", partial_convergents=False, INPUT: - - ``x`` -- exact rational or floating-point number. The number to - compute the continued fraction of. + - ``x`` -- exact rational or floating-point number; the number to + compute the continued fraction of - - ``type`` -- either "std" (default) for standard continued fractions or - "hj" for Hirzebruch-Jung ones. + - ``type`` -- either ``'std'`` (default) for standard continued fractions or + ``'hj'`` for Hirzebruch-Jung ones - - ``partial_convergents`` -- boolean. Whether to return the - partial convergents. + - ``partial_convergents`` -- boolean; whether to return the + partial convergents - ``bits`` -- an optional integer that specify a precision for the real - interval field that is used internally. + interval field that is used internally - - ``nterms`` -- integer. The upper bound on the number of terms in - the continued fraction expansion to return. + - ``nterms`` -- integer; the upper bound on the number of terms in + the continued fraction expansion to return OUTPUT: @@ -2387,7 +2387,7 @@ def continued_fraction_list(x, type="std", partial_convergents=False, sage: 2 + 1/(2 + 1/(1 + 1/(2 + 1/2))) 45/19 - sage: continued_fraction_list(45/19, type="hj") + sage: continued_fraction_list(45/19, type='hj') [3, 2, 3, 2, 3] sage: 3 - 1/(2 - 1/(3 - 1/(2 - 1/3))) 45/19 diff --git a/src/sage/rings/convert/mpfi.pyx b/src/sage/rings/convert/mpfi.pyx index 0d42927740a..803eed59146 100644 --- a/src/sage/rings/convert/mpfi.pyx +++ b/src/sage/rings/convert/mpfi.pyx @@ -52,16 +52,16 @@ cdef int mpfi_set_sage(mpfi_ptr re, mpfi_ptr im, x, field, int base) except -1: INPUT: - - ``re`` -- a pre-initialized MPFI interval. + - ``re`` -- a pre-initialized MPFI interval - - ``im`` -- a pre-initialized MPFI interval or NULL. + - ``im`` -- a pre-initialized MPFI interval or NULL - - ``x`` -- any Sage or Python object to be converted to an interval. + - ``x`` -- any Sage or Python object to be converted to an interval - ``field`` -- a ``RealIntervalField`` or ``ComplexIntervalField`` - of the right precision (real or complex doesn't matter). + of the right precision (real or complex doesn't matter) - - ``base`` -- base to use for string conversion. + - ``base`` -- base to use for string conversion OUTPUT: diff --git a/src/sage/rings/derivation.py b/src/sage/rings/derivation.py index 2702f497d66..b824e16e0d1 100644 --- a/src/sage/rings/derivation.py +++ b/src/sage/rings/derivation.py @@ -260,7 +260,6 @@ def __init__(self, domain, codomain, twist=None): Traceback (most recent call last): ... TypeError: the domain of the derivation must coerce to the domain of the twisting homomorphism - """ if domain not in Rings().Commutative(): raise TypeError("the domain must be a commutative ring") @@ -457,7 +456,6 @@ def __hash__(self): sage: M = R.derivation_module() sage: hash(M) == hash((M.domain(), M.codomain(), M.twisting_morphism())) True - """ return hash((self._domain, self._codomain, self._twist)) @@ -546,7 +544,6 @@ def domain(self): Module of derivations over Multivariate Polynomial Ring in x, y over Integer Ring sage: M.domain() Multivariate Polynomial Ring in x, y over Integer Ring - """ return self._domain @@ -561,7 +558,6 @@ def codomain(self): Module of derivations over Multivariate Polynomial Ring in x, y over Integer Ring sage: M.codomain() Multivariate Polynomial Ring in x, y over Integer Ring - """ return self._codomain @@ -592,7 +588,6 @@ def defining_morphism(self): From: Univariate Polynomial Ring in x over Rational Field To: Rational Field Defn: x |--> 0 - """ return self._defining_morphism @@ -616,7 +611,6 @@ def twisting_morphism(self): sage: M = R.derivation_module() sage: M.twisting_morphism() - """ return self._twist @@ -650,7 +644,6 @@ def ngens(self): 1 sage: M.gen() [x |--> y, y |--> x] - id - """ if self._gens is None: raise NotImplementedError("generators are not implemented for this derivation module") @@ -679,7 +672,6 @@ def gens(self): Ring in x, y over Integer Ring (twisting morphism: x |--> y, y |--> x) sage: M.gens() ([x |--> y, y |--> x] - id,) - """ if self._gens is None: raise NotImplementedError("generators are not implemented for this derivation module") @@ -687,11 +679,11 @@ def gens(self): def gen(self, n=0): r""" - Return the ``n``-th generator of this module of derivations. + Return the `n`-th generator of this module of derivations. INPUT: - - ``n`` -- an integer (default: ``0``) + - ``n`` -- integer (default: `0`) EXAMPLES:: @@ -720,7 +712,6 @@ def basis(self): sage: M = R.derivation_module() sage: M.basis() Family (d/dx, d/dy) - """ if self._basis is None: raise NotImplementedError("basis is not implemented for this derivation module") @@ -745,7 +736,6 @@ def dual_basis(self): Family (d/dx, d/dy) sage: M.dual_basis() Family (x, y) - """ if self._dual_basis is None: raise NotImplementedError("basis is not implemented for this derivation module") @@ -764,7 +754,6 @@ def ring_of_constants(self): Family (d/dx, d/dy) sage: M.ring_of_constants() Rational Field - """ if not self._constants[1]: raise NotImplementedError("the computation of the ring of constants" @@ -781,7 +770,6 @@ def random_element(self, *args, **kwds): sage: M = R.derivation_module() sage: M.random_element() # random (x^2 + x*y - 3*y^2 + x + 1)*d/dx + (-2*x^2 + 3*x*y + 10*y^2 + 2*x + 8)*d/dy - """ if self._gens is None: raise NotImplementedError("generators are not implemented for this derivation module") @@ -797,7 +785,6 @@ def some_elements(self): sage: M = R.derivation_module() sage: M.some_elements() [d/dx, d/dy, x*d/dx, x*d/dy, y*d/dx, y*d/dy] - """ if self._gens is None: return self.an_element() @@ -821,7 +808,6 @@ class RingDerivation(ModuleElement): d/dx + 2*d/dy sage: f(x*y) 2*x + y - """ def __call__(self, x): """ @@ -850,7 +836,6 @@ def domain(self): Multivariate Polynomial Ring in x, y over Rational Field sage: f.domain() is R True - """ return self.parent().domain() @@ -877,7 +862,6 @@ def codomain(self): Univariate Polynomial Ring in x over Rational Field sage: M.random_element().codomain() is S True - """ return self.parent().codomain() @@ -1008,7 +992,6 @@ def list(self): x*d/dx + y*d/dy sage: f.list() [x, y] - """ parent = self.parent() return [self(x) for x in parent.dual_basis()] @@ -1037,7 +1020,6 @@ def monomial_coefficients(self): x*d/dx + y*d/dy sage: f.monomial_coefficients() {0: x, 1: y} - """ dual_basis = self.parent().dual_basis() dict = { } @@ -1079,7 +1061,6 @@ def _richcmp_(self, other, op): x*d/dx + y*d/dy + z*d/dz sage: D.pth_power() == D True - """ if op == op_EQ: if isinstance(other, RingDerivationWithoutTwist): @@ -1128,7 +1109,6 @@ def _bracket_(self, other): sage: f = R.random_element() sage: X.bracket(f*Y) == X(f)*Y + f*X.bracket(Y) True - """ parent = self.parent() if parent.domain() is not parent.codomain(): @@ -1191,7 +1171,6 @@ def pth_power(self): sage: D.bracket(Dp) # needs sage.rings.finite_rings 0 - """ parent = self.parent() if parent.domain() is not parent.codomain(): @@ -1255,7 +1234,6 @@ def precompose(self, morphism): Traceback (most recent call last): ... TypeError: the given ring does not coerce to the domain of the derivation - """ parent = self.parent() if morphism in Rings().Commutative(): @@ -1313,7 +1291,6 @@ def postcompose(self, morphism): Traceback (most recent call last): ... TypeError: you must give a homomorphism of rings - """ parent = self.parent() if morphism in Rings().Commutative(): @@ -1380,7 +1357,6 @@ def __init__(self, parent, arg=None): True sage: TestSuite(der).run() - """ if isinstance(arg, list) and len(arg) == 1 and isinstance(arg[0], RingDerivation): arg = arg[0] @@ -1422,7 +1398,6 @@ def __hash__(self): sage: f = R.derivation(x) sage: hash(f) # random 3713081631936575706 - """ return hash(tuple(self.list())) @@ -1437,7 +1412,6 @@ def _add_(self, other): sage: Dy = R.derivation(y) sage: Dx + Dy d/dx + d/dy - """ return other @@ -1452,7 +1426,6 @@ def _sub_(self, other): sage: Dy = R.derivation(y) sage: Dx - Dy d/dx - d/dy - """ return -other @@ -1466,7 +1439,6 @@ def _neg_(self): sage: Dx = R.derivation(x) sage: -Dx -d/dx - """ return self @@ -1482,7 +1454,6 @@ def _lmul_(self, factor): 2*d/dx sage: Dx * x^2 x^2*d/dx - """ return self @@ -1498,7 +1469,6 @@ def _rmul_(self, left): 2*d/dx sage: x^2 * Dx x^2*d/dx - """ return self @@ -1512,7 +1482,6 @@ def _call_(self, x): sage: f = x*R.derivation(x) + y*R.derivation(y) sage: f(x^2 + 3*x*y - y^2) 2*x^2 + 6*x*y - 2*y^2 - """ return self.parent().codomain().zero() @@ -1528,7 +1497,6 @@ def _bracket_(self, other): sage: Dy = R.derivation(y) sage: Dx._bracket_(Dy) 0 - """ return self @@ -1541,7 +1509,6 @@ def is_zero(self): sage: M = QQ.derivation_module() sage: M().is_zero() True - """ return True @@ -1555,7 +1522,6 @@ def list(self): sage: M = QQ.derivation_module() sage: M().list() [] - """ return [] @@ -1583,7 +1549,6 @@ def __init__(self, parent, arg=None): sage: isinstance(der, RingDerivationWithoutTwist_wrapper) True sage: TestSuite(der).run() - """ if isinstance(arg, list) and len(arg) == 1 and isinstance(arg[0], RingDerivation): arg = arg[0] @@ -1603,7 +1568,6 @@ def __hash__(self): sage: f = R.derivation(x) sage: hash(f) # random 3713081631936575706 - """ return hash(tuple(self.list())) @@ -1620,7 +1584,6 @@ def _add_(self, other): sage: Dy = S.derivation(y) sage: Dx + Dy d/dx + d/dy - """ return type(self)(self.parent(), self._base_derivation + other._base_derivation) @@ -1637,7 +1600,6 @@ def _sub_(self, other): sage: Dy = S.derivation(y) sage: Dx - Dy d/dx - d/dy - """ return type(self)(self.parent(), self._base_derivation - other._base_derivation) @@ -1653,7 +1615,6 @@ def _neg_(self): sage: Dx = S.derivation(x) sage: -Dx -d/dx - """ return type(self)(self.parent(), -self._base_derivation) @@ -1671,7 +1632,6 @@ def _lmul_(self, factor): 2*d/dx sage: Dx * x^2 x^2*d/dx - """ return type(self)(self.parent(), self._base_derivation * factor) @@ -1689,7 +1649,6 @@ def _rmul_(self, factor): 2*d/dx sage: x^2 * Dx x^2*d/dx - """ return type(self)(self.parent(), factor * self._base_derivation) @@ -1714,7 +1673,6 @@ def list(self): x*d/dx + y*d/dy sage: f.list() [x, y] - """ return self._base_derivation.list() @@ -1739,7 +1697,6 @@ def __init__(self, parent, arg=None): d/dx + 2*d/dy sage: TestSuite(der).run() - """ domain = parent.domain() codomain = parent.codomain() @@ -1781,7 +1738,6 @@ def __hash__(self): sage: f = R.derivation(x) sage: hash(f) # random 3713081631936575706 - """ return hash(tuple(self.list())) @@ -1796,7 +1752,6 @@ def _add_(self, other): sage: Dy = R.derivation(y) sage: Dx + Dy d/dx + d/dy - """ base_derivation = self._base_derivation + other._base_derivation im = [ self._images[i] + other._images[i] for i in range(self.parent().domain().ngens()) ] @@ -1920,7 +1875,6 @@ def list(self): x*d/dx + y*d/dy sage: f.list() [x, y] - """ return self._base_derivation.list() + self._images @@ -1939,7 +1893,6 @@ def __hash__(self): sage: f = R.derivation(x) sage: hash(f) # random 3713081631936575706 - """ return hash(tuple(self.list())) @@ -1955,7 +1908,6 @@ def _call_(self, x): d/dx sage: f(1/x) (-1)/x^2 - """ defining_morphism = self.parent().defining_morphism() num = x.numerator() @@ -1981,7 +1933,6 @@ def __hash__(self): sage: f = R.derivation(x) sage: hash(f) # random 3713081631936575706 - """ return hash(tuple(self.list())) @@ -1998,7 +1949,6 @@ def _call_(self, x): x^3*d/dx sage: f(x^3) 0 - """ return self._base_derivation(x.lift()) @@ -2025,7 +1975,6 @@ def __init__(self, parent, scalar=0): sage: der = R.derivation(x, twist=theta) sage: TestSuite(der).run() - """ codomain = parent.codomain() self._scalar = codomain(scalar) @@ -2042,7 +1991,6 @@ def __hash__(self): sage: f = R.derivation(1, twist=theta) sage: hash(f) # random -6511057926760520014 - """ return hash(self._scalar) @@ -2233,7 +2181,6 @@ def list(self): (x + y)*(twisting_morphism - id) sage: f.list() [x + y] - """ return [ self._scalar ] @@ -2266,7 +2213,6 @@ def precompose(self, morphism): Ring endomorphism of Multivariate Polynomial Ring in x, y over Integer Ring Defn: x |--> y^3 y |--> x^2 - """ parent = self.parent() if morphism in Rings().Commutative(): @@ -2309,7 +2255,6 @@ def postcompose(self, morphism): Ring endomorphism of Multivariate Polynomial Ring in x, y over Integer Ring Defn: x |--> y^2 y |--> x^3 - """ parent = self.parent() if morphism in Rings().Commutative(): diff --git a/src/sage/rings/factorint.pyx b/src/sage/rings/factorint.pyx index 87f8d0c1072..f85d6c5f3da 100644 --- a/src/sage/rings/factorint.pyx +++ b/src/sage/rings/factorint.pyx @@ -41,9 +41,7 @@ cpdef aurifeuillian(n, m, F=None, bint check=True): - ``F`` -- integer (default: ``None``) - ``check`` -- boolean (default: ``True``) - OUTPUT: - - A list of factors. + OUTPUT: list of factors EXAMPLES:: @@ -127,9 +125,7 @@ cpdef factor_aurifeuillian(n, check=True): - ``n`` -- integer - OUTPUT: - - List of factors of `n` found by Aurifeuillian factorization. + OUTPUT: list of factors of `n` found by Aurifeuillian factorization EXAMPLES:: @@ -221,7 +217,7 @@ def factor_cunningham(m, proof=None): INPUT: - - ``proof`` -- bool (default: ``None``); whether or not to + - ``proof`` -- boolean (default: ``None``); whether or not to prove primality of each factor, this is only for factors not in the Cunningham table @@ -232,7 +228,6 @@ def factor_cunningham(m, proof=None): 535006138814359 * 1155685395246619182673033 * 374550598501810936581776630096313181393 sage: factor_cunningham((3^101+1)*(2^60).next_prime(), proof=False) # optional - cunningham_tables 2^2 * 379963 * 1152921504606847009 * 1017291527198723292208309354658785077827527 - """ from sage.databases import cunningham_tables cunningham_prime_factors = cunningham_tables.cunningham_prime_factors() @@ -259,7 +254,7 @@ cpdef factor_trial_division(m, long limit=LONG_MAX): INPUT: - - ``limit`` -- integer (default: ``LONG_MAX``) that fits in a C ``signed long`` + - ``limit`` -- integer (default: ``LONG_MAX``); that fits in a C ``signed long`` EXAMPLES:: @@ -277,7 +272,6 @@ cpdef factor_trial_division(m, long limit=LONG_MAX): sage: from sage.rings.factorint import factor_trial_division sage: list(factor_trial_division(8)) [(2, 3)] - """ cdef Integer n = PY_NEW(Integer), unit = PY_NEW(Integer), p = Integer(2) cdef long e diff --git a/src/sage/rings/factorint_flint.pyx b/src/sage/rings/factorint_flint.pyx index cc50af04a1c..69cd6ae8456 100644 --- a/src/sage/rings/factorint_flint.pyx +++ b/src/sage/rings/factorint_flint.pyx @@ -34,7 +34,7 @@ def factor_using_flint(Integer n): INPUT: - - ``n`` -- a nonzero sage Integer; the number to factor. + - ``n`` -- a nonzero sage Integer; the number to factor OUTPUT: diff --git a/src/sage/rings/factorint_pari.pyx b/src/sage/rings/factorint_pari.pyx index 8dae96b047f..a8d748c5845 100644 --- a/src/sage/rings/factorint_pari.pyx +++ b/src/sage/rings/factorint_pari.pyx @@ -41,9 +41,7 @@ def factor_using_pari(n, int_=False, debug_level=0, proof=None): required to be proven prime; if ``None``, the global default is used - OUTPUT: - - A list of pairs. + OUTPUT: list of pairs EXAMPLES:: diff --git a/src/sage/rings/fast_arith.pyx b/src/sage/rings/fast_arith.pyx index 4796122c1b6..2dafcbd701f 100644 --- a/src/sage/rings/fast_arith.pyx +++ b/src/sage/rings/fast_arith.pyx @@ -53,25 +53,25 @@ cpdef prime_range(start, stop=None, algorithm=None, bint py_ints=False): INPUT: - - ``start`` -- integer, lower bound (default: 1) + - ``start`` -- integer; lower bound (default: 1) - - ``stop`` -- integer, upper bound + - ``stop`` -- integer; upper bound - - ``algorithm`` -- optional string (default: ``None``), one of: + - ``algorithm`` -- string (default: ``None``), one of: - - ``None``: Use algorithm ``"pari_primes"`` if ``stop`` <= 436273009 - (approximately 4.36E8). Otherwise use algorithm ``"pari_isprime"``. + - ``None``: Use algorithm ``'pari_primes'`` if ``stop`` <= 436273009 + (approximately 4.36E8). Otherwise use algorithm ``'pari_isprime'``. - - ``"pari_primes"``: Use PARI's :pari:`primes` function to generate all + - ``'pari_primes'``: Use PARI's :pari:`primes` function to generate all primes from 2 to stop. This is fast but may crash if there is insufficient memory. Raises an error if ``stop`` > 436273009. - - ``"pari_isprime"``: Wrapper for ``list(primes(start, stop))``. Each (odd) + - ``'pari_isprime'``: Wrapper for ``list(primes(start, stop))``. Each (odd) integer in the specified range is tested for primality by applying PARI's :pari:`isprime` function. This is slower but will work for much larger input. - - ``py_ints`` -- optional boolean (default ``False``), return Python ints rather - than Sage Integers (faster). Ignored unless algorithm ``"pari_primes"`` is being + - ``py_ints`` -- boolean (default: ``False``); return Python ints rather + than Sage Integers (faster). Ignored unless algorithm ``'pari_primes'`` is being used. EXAMPLES:: @@ -90,7 +90,7 @@ cpdef prime_range(start, stop=None, algorithm=None, bint py_ints=False): [5, 7] sage: prime_range(-100,10,"pari_isprime") [2, 3, 5, 7] - sage: prime_range(2,2,algorithm="pari_isprime") + sage: prime_range(2,2,algorithm='pari_isprime') [] sage: prime_range(10**16,10**16+100,"pari_isprime") [10000000000000061, 10000000000000069, 10000000000000079, 10000000000000099] @@ -98,7 +98,7 @@ cpdef prime_range(start, stop=None, algorithm=None, bint py_ints=False): [1000000000000000000000000000057, 1000000000000000000000000000099] sage: type(prime_range(8)[0]) - sage: type(prime_range(8,algorithm="pari_isprime")[0]) + sage: type(prime_range(8,algorithm='pari_isprime')[0]) .. NOTE:: @@ -134,7 +134,7 @@ cpdef prime_range(start, stop=None, algorithm=None, bint py_ints=False): sage: prime_range(436273009, 436273010) [436273009] - sage: prime_range(436273009, 436273010, algorithm="pari_primes") + sage: prime_range(436273009, 436273010, algorithm='pari_primes') Traceback (most recent call last): ... ValueError: algorithm "pari_primes" is limited to primes larger than 436273008 diff --git a/src/sage/rings/finite_rings/conway_polynomials.py b/src/sage/rings/finite_rings/conway_polynomials.py index 7d6e558f030..ff5873ee14b 100644 --- a/src/sage/rings/finite_rings/conway_polynomials.py +++ b/src/sage/rings/finite_rings/conway_polynomials.py @@ -24,7 +24,7 @@ def conway_polynomial(p, n): Return the Conway polynomial of degree `n` over ``GF(p)``. If the requested polynomial is not known, this function raises a - ``RuntimeError`` exception. + :exc:`RuntimeError` exception. INPUT: @@ -199,9 +199,7 @@ def polynomial(self, n): - ``n`` -- positive integer - OUTPUT: - - - a pseudo-Conway polynomial of degree `n` for the prime `p`. + OUTPUT: a pseudo-Conway polynomial of degree `n` for the prime `p` ALGORITHM: @@ -305,14 +303,11 @@ def _find_pow_of_frobenius(p, n, x, y): - ``n`` -- positive integer - ``x`` -- an element of a field `K` of `p^n` elements so that - the multiplicative order of `x` is `p^n - 1`. - - - ``y`` -- an element of `K` with the same minimal polynomial as - `x`. + the multiplicative order of `x` is `p^n - 1` - OUTPUT: + - ``y`` -- an element of `K` with the same minimal polynomial as `x` - - an element `i` of the integers modulo `n` such that `x = y^{p^i}`. + OUTPUT: an element `i` of the integers modulo `n` such that `x = y^{p^i}` EXAMPLES:: @@ -323,7 +318,6 @@ def _find_pow_of_frobenius(p, n, x, y): sage: y = x^27 sage: _find_pow_of_frobenius(3, 14, x, y) 11 - """ from .integer_mod import mod for i in range(n): @@ -350,7 +344,6 @@ def _crt_non_coprime(running, a): Traceback (most recent call last): ... AssertionError - """ g = running.modulus().gcd(a.modulus()) if g == 1: @@ -387,12 +380,12 @@ def _frobenius_shift(K, generators, check_only=False): - ``K`` -- a finite field of degree `n` over its prime field - - ``generators`` -- a dictionary, indexed by prime divisors `q` of + - ``generators`` -- dictionary, indexed by prime divisors `q` of `n`, whose entries are elements of `K` satisfying the `n/q` - pseudo-Conway polynomial. + pseudo-Conway polynomial - ``check_only`` -- if ``True``, just check that the given - generators form a compatible system. + generators form a compatible system EXAMPLES:: @@ -414,7 +407,6 @@ def _frobenius_shift(K, generators, check_only=False): 13 sage: _find_pow_of_frobenius(2, 12, x12, generators[5]) 8 - """ if len(generators) == 1: return generators @@ -433,7 +425,7 @@ def _frobenius_shift(K, generators, check_only=False): q, x = compatible[m].popitem() except KeyError: break - for qq, xx in compatible[m].items(): + for xx in compatible[m].values(): assert x == xx return crt = {} diff --git a/src/sage/rings/finite_rings/element_base.pyx b/src/sage/rings/finite_rings/element_base.pyx index 7d98b99b95f..aa0a66b4748 100755 --- a/src/sage/rings/finite_rings/element_base.pyx +++ b/src/sage/rings/finite_rings/element_base.pyx @@ -54,8 +54,8 @@ cdef class FiniteRingElement(CommutativeRingElement): def _nth_root_common(self, n, all, algorithm, cunningham): """ This function exists to reduce code duplication between finite field - nth roots and integer_mod nth roots. It assumes that `self` is a field - element. + `n`-th roots and ``integer_mod`` `n`-th roots. It assumes that ``self`` + is a field element. The inputs are described there. @@ -143,7 +143,7 @@ cdef class FiniteRingElement(CommutativeRingElement): else: raise ValueError("unknown algorithm") - def to_bytes(self, byteorder="big"): + def to_bytes(self, byteorder='big'): r""" Return an array of bytes representing an integer. @@ -152,8 +152,8 @@ cdef class FiniteRingElement(CommutativeRingElement): INPUT: - - ``byteorder`` -- str (default: ``"big"``); determines the byte order of - ``input_bytes``; can only be ``"big"`` or ``"little"`` + - ``byteorder`` -- string (default: ``'big'``); determines the byte order of + ``input_bytes``; can only be ``'big'`` or ``'little'`` EXAMPLES:: @@ -161,7 +161,7 @@ cdef class FiniteRingElement(CommutativeRingElement): sage: a = F(8726) sage: a.to_bytes() b'\x00"\x16' - sage: a.to_bytes(byteorder="little") + sage: a.to_bytes(byteorder='little') b'\x16"\x00' """ length = (self.parent().order().nbits() + 7) // 8 @@ -204,18 +204,18 @@ cdef class FinitePolyExtElement(FiniteRingElement): def minpoly(self,var='x',algorithm='pari'): """ - Returns the minimal polynomial of this element + Return the minimal polynomial of this element (over the corresponding prime subfield). INPUT: - - ``var`` -- string (default: 'x') + - ``var`` -- string (default: ``'x'``) - - ``algorithm`` -- string (default: 'pari') + - ``algorithm`` -- string (default: ``'pari'``): - - 'pari' -- use pari's minpoly + - ``'pari'`` -- use pari's minpoly - - 'matrix' -- return the minpoly computed from the matrix of + - ``'matrix'`` -- return the minpoly computed from the matrix of left multiplication by self EXAMPLES:: @@ -225,8 +225,8 @@ cdef class FinitePolyExtElement(FiniteRingElement): sage: parent(a) Finite Field in a of size 19^2 sage: b=a**20 - sage: p=FinitePolyExtElement.minpoly(b,"x", algorithm="pari") - sage: q=FinitePolyExtElement.minpoly(b,"x", algorithm="matrix") + sage: p=FinitePolyExtElement.minpoly(b,"x", algorithm='pari') + sage: q=FinitePolyExtElement.minpoly(b,"x", algorithm='matrix') sage: q == p True sage: p @@ -250,7 +250,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): # for compatibility with sage.matrix def minimal_polynomial(self, var='x'): """ - Returns the minimal polynomial of this element + Return the minimal polynomial of this element (over the corresponding prime subfield). EXAMPLES:: @@ -269,7 +269,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): def __getitem__(self, n): r""" - Return the `n`\th coefficient of this finite field element when + Return the `n`-th coefficient of this finite field element when written as a polynomial in the generator. EXAMPLES:: @@ -409,7 +409,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): INPUT: - ``reverse`` -- reverse the order of the bits - from little endian to big endian. + from little endian to big endian EXAMPLES:: @@ -456,7 +456,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): INPUT: - - ``reverse`` -- if True, act on vectors in reversed order + - ``reverse`` -- if ``True``, act on vectors in reversed order EXAMPLES:: @@ -489,8 +489,8 @@ cdef class FinitePolyExtElement(FiniteRingElement): def _latex_(self): r""" - Return the latex representation of self, which is just the - latex representation of the polynomial representation of self. + Return the latex representation of ``self``, which is just the + latex representation of the polynomial representation of ``self``. EXAMPLES:: @@ -546,7 +546,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): INPUT: - - ``var`` -- (default: ``None``); a string for a new variable name to use. + - ``var`` -- (default: ``None``) a string for a new variable name to use EXAMPLES:: @@ -591,9 +591,9 @@ cdef class FinitePolyExtElement(FiniteRingElement): INPUT: - - ``var`` -- string (default: 'x') + - ``var`` -- string (default: ``'x'``) - - ``algorithm`` -- string (default: ``'pari'``) + - ``algorithm`` -- string (default: ``'pari'``): - ``'pari'`` -- use pari's charpoly @@ -609,8 +609,8 @@ cdef class FinitePolyExtElement(FiniteRingElement): sage: parent(a) Finite Field in a of size 19^2 sage: b = a**20 - sage: p = FinitePolyExtElement.charpoly(b, "x", algorithm="pari") - sage: q = FinitePolyExtElement.charpoly(b, "x", algorithm="matrix") # needs sage.modules + sage: p = FinitePolyExtElement.charpoly(b, "x", algorithm='pari') + sage: q = FinitePolyExtElement.charpoly(b, "x", algorithm='matrix') # needs sage.modules sage: q == p # needs sage.modules True sage: p @@ -631,9 +631,9 @@ cdef class FinitePolyExtElement(FiniteRingElement): def norm(self): """ - Return the norm of self down to the prime subfield. + Return the norm of ``self`` down to the prime subfield. - This is the product of the Galois conjugates of self. + This is the product of the Galois conjugates of ``self``. EXAMPLES:: @@ -737,7 +737,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): def is_square(self): """ - Returns ``True`` if and only if this element is a perfect square. + Return ``True`` if and only if this element is a perfect square. EXAMPLES:: @@ -773,17 +773,16 @@ cdef class FinitePolyExtElement(FiniteRingElement): INPUT: - - - ``extend`` -- bool (default: ``True``); if ``True``, return a - square root in an extension ring, if necessary. Otherwise, raise a - ValueError if the root is not in the base ring. + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the root is not in the base ring. .. WARNING:: This option is not implemented! - - ``all`` -- bool (default: ``False``); if ``True``, return all - square roots of ``self``, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of ``self``, instead of just one .. WARNING:: @@ -825,31 +824,31 @@ cdef class FinitePolyExtElement(FiniteRingElement): def nth_root(self, n, extend = False, all = False, algorithm=None, cunningham=False): r""" - Returns an `n`\th root of ``self``. + Return an `n`-th root of ``self``. INPUT: - ``n`` -- integer `\geq 1` - - ``extend`` -- bool (default: ``False``); if ``True``, return an `n`\th - root in an extension ring, if necessary. Otherwise, raise a - ValueError if the root is not in the base ring. Warning: + - ``extend`` -- boolean (default: ``False``); if ``True``, return an + `n`-th root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the root is not in the base ring. Warning: this option is not implemented! - - ``all`` -- bool (default: ``False``); if ``True``, return all `n`\th - roots of ``self``, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all `n`-th + roots of ``self``, instead of just one - - ``algorithm`` -- string (default: ``None``); 'Johnston' is the only - currently supported option. For IntegerMod elements, the problem + - ``algorithm`` -- string (default: ``None``); ``'Johnston'`` is the + only currently supported option. For IntegerMod elements, the problem is reduced to the prime modulus case using CRT and `p`-adic logs, and then this algorithm used. OUTPUT: - If self has an `n`\th root, returns one (if ``all`` is ``False``) or a + If ``self`` has an `n`-th root, returns one (if ``all`` is ``False``) or a list of all of them (if ``all`` is ``True``). - Otherwise, raises a ``ValueError`` (if ``extend`` is ``False``) - or a ``NotImplementedError`` (if ``extend`` is ``True``). + Otherwise, raises a :exc:`ValueError` (if ``extend`` is ``False``) + or a :exc:`NotImplementedError` (if ``extend`` is ``True``). .. warning:: @@ -944,7 +943,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): def pth_power(self, int k = 1): """ - Return the `(p^k)^{th}` power of self, where `p` is the + Return the `(p^k)`-th power of self, where `p` is the characteristic of the field. INPUT: @@ -978,7 +977,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): def pth_root(self, int k = 1): """ - Return the `(p^k)^{th}` root of self, where `p` is the characteristic + Return the `(p^k)`-th root of self, where `p` is the characteristic of the field. INPUT: @@ -1107,7 +1106,7 @@ cdef class FinitePolyExtElement(FiniteRingElement): integer_representation = deprecated_function_alias(33941, to_integer) - def to_bytes(self, byteorder="big"): + def to_bytes(self, byteorder='big'): r""" Return an array of bytes representing an integer. @@ -1116,8 +1115,8 @@ cdef class FinitePolyExtElement(FiniteRingElement): INPUT: - - ``byteorder`` -- str (default: ``"big"``); determines the byte order of - the output; can only be ``"big"`` or ``"little"`` + - ``byteorder`` -- string (default: ``'big'``); determines the byte order of + the output; can only be ``'big'`` or ``'little'`` EXAMPLES:: diff --git a/src/sage/rings/finite_rings/element_givaro.pyx b/src/sage/rings/finite_rings/element_givaro.pyx index d6fe400b0e9..bb5a9f6b376 100644 --- a/src/sage/rings/finite_rings/element_givaro.pyx +++ b/src/sage/rings/finite_rings/element_givaro.pyx @@ -106,7 +106,7 @@ cdef void late_import() noexcept: cdef class Cache_givaro(Cache_base): - def __init__(self, parent, unsigned int p, unsigned int k, modulus, repr="poly", cache=False): + def __init__(self, parent, unsigned int p, unsigned int k, modulus, repr='poly', cache=False): """ Finite Field. @@ -120,24 +120,22 @@ cdef class Cache_givaro(Cache_base): - ``name`` -- variable used for poly_repr (default: ``'a'``) - - ``modulus`` -- a polynomial to use as modulus. + - ``modulus`` -- a polynomial to use as modulus - - ``repr`` -- (default: 'poly') controls the way elements are printed + - ``repr`` -- (default: ``'poly'``) controls the way elements are printed to the user: - 'log': repr is :meth:`~FiniteField_givaroElement.log_repr()` - 'int': repr is :meth:`~FiniteField_givaroElement.int_repr()` - 'poly': repr is :meth:`~FiniteField_givaroElement.poly_repr()` - - ``cache`` -- (default: ``False``) if ``True`` a cache of all + - ``cache`` -- boolean (default: ``False``); if ``True`` a cache of all elements of this field is created. Thus, arithmetic does not create new elements which speeds calculations up. Also, if many elements are needed during a calculation this cache reduces the memory requirement as at most :meth:`order()` elements are created. - OUTPUT: - - Givaro finite field with characteristic `p` and cardinality `p^n`. + OUTPUT: Givaro finite field with characteristic `p` and cardinality `p^n` EXAMPLES: @@ -301,7 +299,7 @@ cdef class Cache_givaro(Cache_base): INPUT: - - ``e`` -- data to coerce in. + - ``e`` -- data to coerce in EXAMPLES:: @@ -497,9 +495,7 @@ cdef class Cache_givaro(Cache_base): - ``n`` -- log representation of a finite field element - OUTPUT: - - integer representation of a finite field element. + OUTPUT: integer representation of a finite field element EXAMPLES:: @@ -530,9 +526,7 @@ cdef class Cache_givaro(Cache_base): - ``n`` -- integer representation of a finite field element - OUTPUT: - - log representation of ``n`` + OUTPUT: log representation of ``n`` EXAMPLES:: @@ -847,7 +841,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): def __init__(FiniteField_givaroElement self, parent): """ - Initializes an element in parent. It's much better to use + Initialize an element in parent. It's much better to use parent() or any specialized method of parent like gen() instead. In general do not call this constructor directly. @@ -860,9 +854,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): - ``parent`` -- base field - OUTPUT: - - A finite field element. + OUTPUT: a finite field element EXAMPLES:: @@ -870,7 +862,6 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): sage: from sage.rings.finite_rings.element_givaro import FiniteField_givaroElement sage: FiniteField_givaroElement(k) 0 - """ FinitePolyExtElement.__init__(self, parent) self._cache = parent._cache @@ -944,7 +935,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): def is_unit(FiniteField_givaroElement self): """ - Return ``True`` if self is nonzero, so it is a unit as an element of + Return ``True`` if ``self`` is nonzero, so it is a unit as an element of the finite field. EXAMPLES:: @@ -964,7 +955,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): def is_square(FiniteField_givaroElement self): """ - Return ``True`` if ``self`` is a square in ``self.parent()`` + Return ``True`` if ``self`` is a square in ``self.parent()``. ALGORITHM: @@ -1006,20 +997,20 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): def sqrt(FiniteField_givaroElement self, extend=False, all=False): """ Return a square root of this finite field element in its - parent, if there is one. Otherwise, raise a ``ValueError``. + parent, if there is one. Otherwise, raise a :exc:`ValueError`. INPUT: - - ``extend`` -- bool (default: ``True``); if ``True``, return a + - ``extend`` -- boolean (default: ``True``); if ``True``, return a square root in an extension ring, if necessary. Otherwise, - raise a ``ValueError`` if the root is not in the base ring. + raise a :exc:`ValueError` if the root is not in the base ring. .. WARNING:: this option is not implemented! - - ``all`` -- bool (default: ``False``); if ``True``, return all square - roots of ``self``, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of ``self``, instead of just one .. WARNING:: @@ -1061,7 +1052,6 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): sage: K. = FiniteField(9) sage: a.sqrt(extend = False, all = True) [] - """ if all: if self.is_square(): @@ -1114,7 +1104,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): cpdef _div_(self, right): """ - Divide two elements + Divide two elements. EXAMPLES:: @@ -1191,7 +1181,6 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): Traceback (most recent call last): ... ZeroDivisionError: division by zero in finite field - """ cdef int r = 0 if self.element == 0: @@ -1333,7 +1322,6 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): Traceback (most recent call last): ... TypeError: Cannot coerce element to an integer. - """ cdef int self_int = self._cache.log_to_int(self.element) if self_int % self._cache.characteristic() != self_int: @@ -1350,7 +1338,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): `e = a_0 + a_1 x + a_2 x^2 + \cdots`, the integer representation is `a_0 + a_1 p + a_2 p^2 + \cdots`. - OUTPUT: A Python ``int``. + OUTPUT: a Python ``int`` .. SEEALSO:: @@ -1498,7 +1486,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): def polynomial(FiniteField_givaroElement self, name=None): """ - Return self viewed as a polynomial over + Return ``self`` viewed as a polynomial over ``self.parent().prime_subfield()``. EXAMPLES:: @@ -1529,7 +1517,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): def _magma_init_(self, magma): """ - Return a string representation of self that MAGMA can + Return a string representation of ``self`` that MAGMA can understand. EXAMPLES:: @@ -1638,8 +1626,8 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): Return a string that evaluates to the GAP representation of this element. - A ``NotImplementedError`` is raised if ``self.parent().modulus()`` is - not a Conway polynomial, as the isomorphism of finite fields is + A :exc:`NotImplementedError` is raised if ``self.parent().modulus()`` + is not a Conway polynomial, as the isomorphism of finite fields is not implemented yet. EXAMPLES:: @@ -1694,7 +1682,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement): INPUT: - ``reverse`` -- reverse the order of the bits from little endian to - big endian. + big endian EXAMPLES:: diff --git a/src/sage/rings/finite_rings/element_ntl_gf2e.pyx b/src/sage/rings/finite_rings/element_ntl_gf2e.pyx index 8eb716db1e7..2c1c25254c4 100644 --- a/src/sage/rings/finite_rings/element_ntl_gf2e.pyx +++ b/src/sage/rings/finite_rings/element_ntl_gf2e.pyx @@ -144,7 +144,7 @@ cdef class Cache_ntl_gf2e(Cache_base): TESTS:: - sage: k. = GF(2^8, impl="ntl") + sage: k. = GF(2^8, impl='ntl') """ self._parent = parent self._zero_element = self._new() @@ -262,10 +262,10 @@ cdef class Cache_ntl_gf2e(Cache_base): We can coerce from PARI finite field implementations:: - sage: K. = GF(2^19, impl="ntl") + sage: K. = GF(2^19, impl='ntl') sage: a^20 a^6 + a^3 + a^2 + a - sage: M. = GF(2^19, impl="pari_ffelt") + sage: M. = GF(2^19, impl='pari_ffelt') sage: K(c^20) a^6 + a^3 + a^2 + a """ @@ -386,7 +386,7 @@ cdef class Cache_ntl_gf2e(Cache_base): INPUT: - - ``number`` -- an integer, of size less than the cardinality + - ``number`` -- integer; of size less than the cardinality EXAMPLES:: @@ -436,12 +436,12 @@ cdef class Cache_ntl_gf2e(Cache_base): def polynomial(self): """ - Returns the list of 0's and 1's giving the defining polynomial of the + Return the list of 0s and 1s giving the defining polynomial of the field. EXAMPLES:: - sage: k. = GF(2^20,modulus="minimal_weight") + sage: k. = GF(2^20,modulus='minimal_weight') sage: k._cache.polynomial() [1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1] """ @@ -471,7 +471,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): def __init__(FiniteField_ntl_gf2eElement self, parent=None ): """ - Initializes an element in parent. It's much better to use + Initialize an element in parent. It's much better to use parent() or any specialized method of parent (one,zero,gen) instead. Do not call this constructor directly, it doesn't make much sense. @@ -480,9 +480,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): - ``parent`` -- base field - OUTPUT: - - A finite field element. + OUTPUT: a finite field element EXAMPLES:: @@ -499,11 +497,11 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): def __cinit__(FiniteField_ntl_gf2eElement self, parent=None ): """ - Restores the cache and constructs the underlying NTL element. + Restore the cache and construct the underlying NTL element. EXAMPLES:: - sage: k. = GF(2^8, impl="ntl") # indirect doctest + sage: k. = GF(2^8, impl='ntl') # indirect doctest """ if parent is None: return @@ -588,7 +586,6 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): False sage: k(1).is_one() True - """ (self._parent._cache).F.restore() return self.x == self._cache._one_element.x @@ -647,7 +644,6 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): sage: GF(2^16,'a')(1).sqrt() 1 - """ # this really should be handled special, its gf2 linear after # all @@ -898,7 +894,6 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): Traceback (most recent call last): ... TypeError: Cannot coerce element to an integer. - """ if self == 0: return int(0) @@ -999,13 +994,11 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): - ``var`` -- string (default: ``'x'``) - OUTPUT: - - polynomial + OUTPUT: polynomial EXAMPLES:: - sage: k. = GF(2^8, impl="ntl") + sage: k. = GF(2^8, impl='ntl') sage: b = a^3 + a sage: b.minpoly() x^4 + x^3 + x^2 + x + 1 @@ -1030,9 +1023,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): - ``var`` -- string (default: ``'x'``) - OUTPUT: - - polynomial + OUTPUT: polynomial EXAMPLES:: @@ -1080,7 +1071,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): def weight(self): """ - Returns the number of non-zero coefficients in the polynomial + Return the number of nonzero coefficients in the polynomial representation of ``self``. EXAMPLES:: @@ -1145,7 +1136,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): Return a string that evaluates to the GAP representation of this element. - A ``NotImplementedError`` is raised if + A :exc:`NotImplementedError` is raised if ``self.parent().modulus()`` is not a Conway polynomial, as the isomorphism of finite fields is not implemented yet. @@ -1193,7 +1184,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): INPUT: - ``reverse`` -- reverse the order of the bits from little endian to - big endian. + big endian EXAMPLES:: @@ -1248,7 +1239,7 @@ cdef class FiniteField_ntl_gf2eElement(FinitePolyExtElement): OUTPUT: Integer `x` such that `a^x = b`, if it exists. - Raises a ``ValueError`` exception if no such `x` exists. + Raises a :exc:`ValueError` exception if no such `x` exists. ALGORITHM: :pari:`fflog` diff --git a/src/sage/rings/finite_rings/element_pari_ffelt.pyx b/src/sage/rings/finite_rings/element_pari_ffelt.pyx index c7f286bcbeb..3c92e26d679 100644 --- a/src/sage/rings/finite_rings/element_pari_ffelt.pyx +++ b/src/sage/rings/finite_rings/element_pari_ffelt.pyx @@ -54,7 +54,6 @@ cdef GEN _INT_to_FFELT(GEN g, GEN x) except NULL: sage: F. = GF(p^2) sage: x * 2^63 9223372036854775808*x - """ cdef GEN f, p = gel(g, 4), result cdef long t @@ -381,7 +380,6 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): sage: R = [r[0] for r in pol.roots()] sage: prod(Fq_X.gen() - r for r in R) == pol True - """ cdef GEN f, g, result, x_GEN cdef long i, n, t @@ -756,7 +754,7 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): def is_unit(self): """ - Return ``True`` if ``self`` is non-zero. + Return ``True`` if ``self`` is nonzero. EXAMPLES:: @@ -849,7 +847,6 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): exponent to an integer. This means that ``a^Mod(1, n)`` returns `a` even if `n` is not a multiple of the multiplicative order of `a`. - """ if exp == 0: return self._parent.one() @@ -863,7 +860,7 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): def pth_power(FiniteFieldElement_pari_ffelt self, int k=1): r""" - Return the `(p^k)^{th}` power of ``self``, where `p` is the + Return the `(p^k)`-th power of ``self``, where `p` is the characteristic of the field. INPUT: @@ -960,7 +957,7 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): INPUT: - - ``var`` -- string (default: 'x'): variable name to use. + - ``var`` -- string (default: ``'x'``); variable name to use EXAMPLES:: @@ -979,7 +976,7 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): INPUT: - - ``var`` -- string (default: 'x'): variable name to use. + - ``var`` -- string (default: ``'x'``); variable name to use EXAMPLES:: @@ -1029,13 +1026,13 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): INPUT: - - ``extend`` -- bool (default: ``False``) + - ``extend`` -- boolean (default: ``False``) .. WARNING:: This option is not implemented. - - ``all`` -- bool (default: ``False``) + - ``all`` -- boolean (default: ``False``) OUTPUT: @@ -1045,7 +1042,7 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): If ``extend`` is ``True``, a square root is chosen in an extension field if necessary. If ``extend`` is ``False``, a - :class:`ValueError` is raised if the element is not a square in the + :exc:`ValueError` is raised if the element is not a square in the base field. .. WARNING:: @@ -1107,15 +1104,15 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): INPUT: - - ``base`` -- non-zero field element + - ``base`` -- nonzero field element - ``order`` -- integer (optional), the order of the base - - ``check`` -- boolean (default: ``False``): If set, - test whether the given ``order`` is correct. + - ``check`` -- boolean (default: ``False``); if set, + test whether the given ``order`` is correct OUTPUT: An integer `x` such that ``self`` equals ``base`` raised to - the power `x`. If no such `x` exists, a ``ValueError`` is + the power `x`. If no such `x` exists, a :exc:`ValueError` is raised. EXAMPLES:: @@ -1211,7 +1208,7 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement): def multiplicative_order(self): """ - Returns the order of ``self`` in the multiplicative group. + Return the order of ``self`` in the multiplicative group. EXAMPLES:: diff --git a/src/sage/rings/finite_rings/finite_field_base.pyx b/src/sage/rings/finite_rings/finite_field_base.pyx index d10ac31cf96..f54c1ffb2c4 100644 --- a/src/sage/rings/finite_rings/finite_field_base.pyx +++ b/src/sage/rings/finite_rings/finite_field_base.pyx @@ -91,7 +91,6 @@ cdef class FiniteField(Field): True sage: hash(F) == object.__hash__(F) True - """ # This is the default hash function in Python's object.c: cdef long x @@ -150,7 +149,6 @@ cdef class FiniteField(Field): sage: GF(2).is_perfect() True - """ return True @@ -183,7 +181,7 @@ cdef class FiniteField(Field): def _latex_(self): r""" - Returns a string denoting the name of the field in LaTeX. + Return a string denoting the name of the field in LaTeX. The :func:`~sage.misc.latex.latex` function calls the ``_latex_`` attribute when available. @@ -318,14 +316,14 @@ cdef class FiniteField(Field): EXAMPLES:: - sage: k. = FiniteField(9, impl="pari") + sage: k. = FiniteField(9, impl='pari') sage: list(k) [0, 1, 2, a, a + 1, a + 2, 2*a, 2*a + 1, 2*a + 2] Partial iteration of a very large finite field:: sage: p = next_prime(2^64) - sage: k. = FiniteField(p^2, impl="pari") + sage: k. = FiniteField(p^2, impl='pari') sage: it = iter(k); it <...generator object at ...> sage: [next(it) for i in range(10)] @@ -337,11 +335,11 @@ cdef class FiniteField(Field): sage: L = [] sage: from sage.rings.finite_rings.finite_field_base import FiniteField - sage: print(list(FiniteField.__iter__(GF(8, impl="givaro", names="z")))) # needs sage.libs.linbox + sage: print(list(FiniteField.__iter__(GF(8, impl='givaro', names='z')))) # needs sage.libs.linbox [0, 1, z, z + 1, z^2, z^2 + 1, z^2 + z, z^2 + z + 1] - sage: print(list(FiniteField.__iter__(GF(8, impl="pari", names="z")))) + sage: print(list(FiniteField.__iter__(GF(8, impl='pari', names='z')))) [0, 1, z, z + 1, z^2, z^2 + 1, z^2 + z, z^2 + z + 1] - sage: print(list(FiniteField.__iter__(GF(8, impl="ntl", names="z")))) # needs sage.libs.ntl + sage: print(list(FiniteField.__iter__(GF(8, impl='ntl', names='z')))) # needs sage.libs.ntl [0, 1, z, z + 1, z^2, z^2 + 1, z^2 + z, z^2 + z + 1] """ cdef Py_ssize_t n = self.degree() @@ -419,7 +417,7 @@ cdef class FiniteField(Field): INPUT: - - `n` -- integer between `0` and the cardinality of this field minus `1`. + - ``n`` -- integer between `0` and the cardinality of this field minus `1` EXAMPLES:: @@ -463,7 +461,7 @@ cdef class FiniteField(Field): def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): """ - Return ``True`` if the map from self to codomain sending + Return ``True`` if the map from ``self`` to codomain sending ``self.0`` to the unique element of ``im_gens`` is a valid field homomorphism. Otherwise, return ``False``. @@ -546,7 +544,7 @@ cdef class FiniteField(Field): INPUT: - - ``f`` -- a univariate non-zero polynomial over this field + - ``f`` -- a univariate nonzero polynomial over this field ALGORITHM: [Coh1993]_, Algorithm 3.4.2 which is basically the algorithm in [Yun1976]_ with special treatment for powers divisible by `p`. @@ -586,7 +584,6 @@ cdef class FiniteField(Field): sage: R. = PolynomialRing(GF(65537), sparse=True) sage: (x^65537 + 2).squarefree_decomposition() (x + 2)^65537 - """ from sage.structure.factorization import Factorization if f.degree() == 0: @@ -647,7 +644,7 @@ cdef class FiniteField(Field): def gen(self): r""" Return a generator of this field (over its prime field). As this is an - abstract base class, this just raises a ``NotImplementedError``. + abstract base class, this just raises a :exc:`NotImplementedError`. EXAMPLES:: @@ -677,7 +674,7 @@ cdef class FiniteField(Field): def zeta(self, n=None): """ Return an element of multiplicative order ``n`` in this finite - field. If there is no such element, raise ``ValueError``. + field. If there is no such element, raise :exc:`ValueError`. .. WARNING:: @@ -851,7 +848,7 @@ cdef class FiniteField(Field): def is_field(self, proof = True): """ - Returns whether or not the finite field is a field, i.e., + Return whether or not the finite field is a field, i.e., always returns ``True``. EXAMPLES:: @@ -878,7 +875,7 @@ cdef class FiniteField(Field): @cached_method def factored_order(self): """ - Returns the factored order of this field. For compatibility with + Return the factored order of this field. For compatibility with :mod:`~sage.rings.finite_rings.integer_mod_ring`. EXAMPLES:: @@ -892,7 +889,7 @@ cdef class FiniteField(Field): @cached_method def factored_unit_order(self): """ - Returns the factorization of ``self.order()-1``, as a 1-tuple. + Return the factorization of ``self.order()-1``, as a 1-tuple. The format is for compatibility with :mod:`~sage.rings.finite_rings.integer_mod_ring`. @@ -960,9 +957,7 @@ cdef class FiniteField(Field): coefficients in the base field that has `a` as a root. In finite field extensions, `\GF{p^n}`, the base field is `\GF{p}`. - OUTPUT: - - - a monic polynomial over `\GF{p}` in the variable `x`. + OUTPUT: a monic polynomial over `\GF{p}` in the variable `x` EXAMPLES:: @@ -1011,7 +1006,7 @@ cdef class FiniteField(Field): The given modulus is always made monic:: - sage: k. = GF(7^2, modulus=2*x^2 - 3, impl="pari_ffelt") + sage: k. = GF(7^2, modulus=2*x^2 - 3, impl='pari_ffelt') sage: k.modulus() x^2 + 2 @@ -1019,21 +1014,21 @@ cdef class FiniteField(Field): We test the various finite field implementations:: - sage: GF(2, impl="modn").modulus() + sage: GF(2, impl='modn').modulus() x + 1 - sage: GF(2, impl="givaro").modulus() # needs sage.libs.linbox + sage: GF(2, impl='givaro').modulus() # needs sage.libs.linbox x + 1 - sage: GF(2, impl="ntl").modulus() # needs sage.libs.ntl + sage: GF(2, impl='ntl').modulus() # needs sage.libs.ntl x + 1 - sage: GF(2, impl="modn", modulus=x).modulus() + sage: GF(2, impl='modn', modulus=x).modulus() x - sage: GF(2, impl="givaro", modulus=x).modulus() # needs sage.libs.linbox + sage: GF(2, impl='givaro', modulus=x).modulus() # needs sage.libs.linbox x - sage: GF(2, impl="ntl", modulus=x).modulus() # needs sage.libs.ntl + sage: GF(2, impl='ntl', modulus=x).modulus() # needs sage.libs.ntl x - sage: GF(13^2, 'a', impl="givaro", modulus=x^2 + 2).modulus() # needs sage.libs.linbox + sage: GF(13^2, 'a', impl='givaro', modulus=x^2 + 2).modulus() # needs sage.libs.linbox x^2 + 2 - sage: GF(13^2, 'a', impl="pari_ffelt", modulus=x^2 + 2).modulus() # needs sage.libs.pari + sage: GF(13^2, 'a', impl='pari_ffelt', modulus=x^2 + 2).modulus() # needs sage.libs.pari x^2 + 2 """ # Normally, this is set by the constructor of the implementation @@ -1058,9 +1053,7 @@ cdef class FiniteField(Field): - ``name`` -- a variable name to use for the polynomial. By default, use the name given when constructing this field. - OUTPUT: - - - a monic polynomial over `\GF{p}` in the variable ``name``. + OUTPUT: a monic polynomial over `\GF{p}` in the variable ``name`` .. SEEALSO:: @@ -1128,7 +1121,6 @@ cdef class FiniteField(Field): sage: k.random_element(prob=0) # needs sage.modules 0 - """ if self.degree() == 1: return self(randrange(self.order())) @@ -1137,7 +1129,7 @@ cdef class FiniteField(Field): def some_elements(self): """ - Returns a collection of elements of this finite field for use in unit + Return a collection of elements of this finite field for use in unit testing. EXAMPLES:: @@ -1150,7 +1142,7 @@ cdef class FiniteField(Field): def polynomial_ring(self, variable_name=None): """ - Returns the polynomial ring over the prime subfield in the + Return the polynomial ring over the prime subfield in the same variable as this finite field. EXAMPLES:: @@ -1186,7 +1178,7 @@ cdef class FiniteField(Field): over the subfield. If not given, one is chosen automatically. - ``map`` -- boolean (default: ``True``); if ``True``, isomorphisms - from and to the vector space are also returned. + from and to the vector space are also returned The ``basis`` maps to the standard basis of the vector space by the isomorphisms. @@ -1388,7 +1380,7 @@ cdef class FiniteField(Field): cpdef _convert_map_from_(self, R): """ - Conversion from p-adic fields. + Conversion from `p`-adic fields. EXAMPLES:: @@ -1430,7 +1422,6 @@ cdef class FiniteField(Field): sage: F, R = k.construction() sage: F(R) is k True - """ from sage.categories.pushout import AlgebraicExtensionFunctor try: @@ -1459,22 +1450,22 @@ cdef class FiniteField(Field): INPUT: - ``modulus`` -- a polynomial with coefficients in ``self``, - or an integer. + or an integer - - ``name`` or ``names`` -- string: the name of the generator + - ``name`` or ``names`` -- string; the name of the generator in the new extension - - ``latex_name`` or ``latex_names`` -- string: latex name of + - ``latex_name`` or ``latex_names`` -- string; latex name of the generator in the new extension - - ``map`` -- boolean (default: ``False``): if ``False``, - return just the extension `E`; if ``True``, return a pair + - ``map`` -- boolean (default: ``False``); if ``False``, + return just the extension `E`. If ``True``, return a pair `(E, f)`, where `f` is an embedding of ``self`` into `E`. - ``embedding`` -- currently not used; for compatibility with - other ``AlgebraicExtensionFunctor`` calls. + other ``AlgebraicExtensionFunctor`` calls - - ``**kwds``: further keywords, passed to the finite field + - ``**kwds`` -- further keywords, passed to the finite field constructor. OUTPUT: @@ -1654,7 +1645,7 @@ cdef class FiniteField(Field): - ``name`` -- string; name of the generator of the subfield - - ``map`` -- boolean (default ``False``); whether to also return the inclusion map + - ``map`` -- boolean (default: ``False``); whether to also return the inclusion map EXAMPLES:: @@ -1764,9 +1755,9 @@ cdef class FiniteField(Field): INPUT: - - ``degree`` -- (default: `0`) an integer + - ``degree`` -- integer (default: `0`) - - ``name`` -- a string, a dictionary or ``None``: + - ``name`` -- string; a dictionary or ``None``: - If ``degree`` is nonzero, then ``name`` must be a string (or ``None``, if this is a pseudo-Conway extension), @@ -1841,10 +1832,10 @@ cdef class FiniteField(Field): INPUT: - - ``name`` -- string (default: 'z'): prefix to use for + - ``name`` -- string (default: ``'z'``); prefix to use for variable names of subfields - - ``implementation`` -- string (optional): specifies how to + - ``implementation`` -- string (optional); specifies how to construct the algebraic closure. The only value supported at the moment is ``'pseudo_conway'``. For more details, see :mod:`~sage.rings.algebraic_closure_finite_field`. @@ -1912,7 +1903,7 @@ cdef class FiniteField(Field): @cached_method def is_conway(self): """ - Return ``True`` if self is defined by a Conway polynomial. + Return ``True`` if ``self`` is defined by a Conway polynomial. EXAMPLES:: @@ -1933,7 +1924,7 @@ cdef class FiniteField(Field): """ INPUT: - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) OUTPUT: @@ -2008,14 +1999,14 @@ cdef class FiniteField(Field): INPUT: - - ``basis`` -- (default: ``None``): a basis of the finite field + - ``basis`` -- (default: ``None``); a basis of the finite field ``self``, `\GF{p^n}`, as a vector space over the base field `\GF{p}`. Uses the power basis `\{x^i : 0 \leq i \leq n-1\}` as input if no basis is supplied, where `x` is the generator of ``self``. - - ``check`` -- (default: ``True``): verifies that ``basis`` is - a valid basis of ``self``. + - ``check`` -- (default: ``True``); verifies that ``basis`` is + a valid basis of ``self`` ALGORITHM: @@ -2114,7 +2105,7 @@ cdef class FiniteField(Field): return [sum(x * y for x, y in zip(col, basis)) for col in B.columns()] - def from_bytes(self, input_bytes, byteorder="big"): + def from_bytes(self, input_bytes, byteorder='big'): r""" Return the integer represented by the given array of bytes. @@ -2123,8 +2114,8 @@ cdef class FiniteField(Field): INPUT: - ``input_bytes`` -- a bytes-like object or iterable producing bytes - - ``byteorder`` -- str (default: ``"big"``); determines the byte order of - ``input_bytes``; can only be ``"big"`` or ``"little"`` + - ``byteorder`` -- string (default: ``'big'``); determines the byte order of + ``input_bytes`` (can only be ``'big'`` or ``'little'``) EXAMPLES:: @@ -2132,7 +2123,7 @@ cdef class FiniteField(Field): sage: F = GF(2**127 - 1) sage: F.from_bytes(input_bytes) 545127616933790290830707 - sage: a = F.from_bytes(input_bytes, byteorder="little"); a + sage: a = F.from_bytes(input_bytes, byteorder='little'); a 544943659528996309004147 sage: type(a) @@ -2143,7 +2134,7 @@ cdef class FiniteField(Field): sage: F_ext = GF(65537**5) sage: F_ext.from_bytes(input_bytes) 29549*z5^4 + 40876*z5^3 + 52171*z5^2 + 13604*z5 + 20843 - sage: F_ext.from_bytes(input_bytes, byteorder="little") + sage: F_ext.from_bytes(input_bytes, byteorder='little') 29539*z5^4 + 42728*z5^3 + 47440*z5^2 + 12423*z5 + 27473 TESTS:: diff --git a/src/sage/rings/finite_rings/finite_field_constructor.py b/src/sage/rings/finite_rings/finite_field_constructor.py index 78acc0a8873..bd29fdb1a95 100644 --- a/src/sage/rings/finite_rings/finite_field_constructor.py +++ b/src/sage/rings/finite_rings/finite_field_constructor.py @@ -8,11 +8,11 @@ are -- ``sage.rings.finite_rings.integer_mod.IntegerMod_int``, +- ``sage.rings.finite_rings.integer_mod.IntegerMod_int``, -- ``sage.rings.finite_rings.integer_mod.IntegerMod_int64``, and +- ``sage.rings.finite_rings.integer_mod.IntegerMod_int64``, and -- ``sage.rings.finite_rings.integer_mod.IntegerMod_gmp``. +- ``sage.rings.finite_rings.integer_mod.IntegerMod_gmp``. Small extension fields of cardinality `< 2^{16}` are @@ -229,16 +229,15 @@ class FiniteFieldFactory(UniqueFactory): - ``impl`` -- (optional) a string specifying the implementation of the finite field. Possible values are: - - ``'modn'`` -- ring of integers modulo `p` (only for prime - fields). + - ``'modn'`` -- ring of integers modulo `p` (only for prime fields) - ``'givaro'`` -- Givaro, which uses Zech logs (only for fields - of at most 65521 elements). + of at most 65521 elements) - - ``'ntl'`` -- NTL using GF2X (only in characteristic 2). + - ``'ntl'`` -- NTL using GF2X (only in characteristic 2) - ``'pari'`` or ``'pari_ffelt'`` -- PARI's ``FFELT`` type (only - for extension fields). + for extension fields) - ``elem_cache`` -- (default: order < 500) cache all elements to avoid creation time; ignored unless ``impl='givaro'`` @@ -258,8 +257,8 @@ class FiniteFieldFactory(UniqueFactory): - ``check_irreducible`` -- verify that the polynomial modulus is irreducible - - ``proof`` -- bool (default: ``True``): if ``True``, use provable - primality test; otherwise only use pseudoprimality test. + - ``proof`` -- boolean (default: ``True``); if ``True``, use provable + primality test; otherwise only use pseudoprimality test ALIAS: You can also use ``GF`` instead of ``FiniteField`` -- they are identical. @@ -304,7 +303,7 @@ class FiniteFieldFactory(UniqueFactory): 7105427357601001858711242675781 sage: a.is_square() True - sage: K. = GF(5^45, modulus="primitive") + sage: K. = GF(5^45, modulus='primitive') sage: b.multiplicative_order() 28421709430404007434844970703124 @@ -358,7 +357,7 @@ class FiniteFieldFactory(UniqueFactory): change how Sage computes in this field, but it will change the result of the :meth:`modulus` and :meth:`gen` methods:: - sage: k. = GF(5, modulus="primitive") + sage: k. = GF(5, modulus='primitive') sage: k.modulus() x + 3 sage: a @@ -465,9 +464,9 @@ class FiniteFieldFactory(UniqueFactory): Check that :issue:`16934` has been fixed:: - sage: k1. = GF(17^14, impl="pari") + sage: k1. = GF(17^14, impl='pari') sage: _ = a/2 - sage: k2. = GF(17^14, impl="pari") + sage: k2. = GF(17^14, impl='pari') sage: k1 is k2 True diff --git a/src/sage/rings/finite_rings/finite_field_givaro.py b/src/sage/rings/finite_rings/finite_field_givaro.py index a393535a1fd..ce61efb8edd 100644 --- a/src/sage/rings/finite_rings/finite_field_givaro.py +++ b/src/sage/rings/finite_rings/finite_field_givaro.py @@ -39,7 +39,7 @@ class FiniteField_givaro(FiniteField): - ``name`` -- (default: ``'a'``) variable used for :meth:`~sage.rings.finite_rings.element_givaro.FiniteField_givaroElement.poly_repr()` - - ``modulus`` -- A minimal polynomial to use for reduction. + - ``modulus`` -- a minimal polynomial to use for reduction - ``repr`` -- (default: ``'poly'``) controls the way elements are printed to the user: @@ -51,15 +51,13 @@ class FiniteField_givaro(FiniteField): - 'poly': repr is :meth:`~sage.rings.finite_rings.element_givaro.FiniteField_givaroElement.poly_repr()` - - cache -- (default: ``False``) if ``True`` a cache of all elements of - this field is created. Thus, arithmetic does not create new elements - which speeds calculations up. Also, if many elements are needed during a - calculation this cache reduces the memory requirement as at most + - ``cache`` -- boolean (default: ``False``); if ``True`` a cache of all + elements of this field is created. Thus, arithmetic does not create new + elements which speeds calculations up. Also, if many elements are needed + during a calculation this cache reduces the memory requirement as at most :meth:`order` elements are created. - OUTPUT: - - Givaro finite field with characteristic `p` and cardinality `p^n`. + OUTPUT: Givaro finite field with characteristic `p` and cardinality `p^n` EXAMPLES: @@ -104,7 +102,7 @@ class FiniteField_givaro(FiniteField): sage: GF(1009, impl='givaro', modulus='conway').modulus() x + 998 """ - def __init__(self, q, name="a", modulus=None, repr="poly", cache=False): + def __init__(self, q, name='a', modulus=None, repr='poly', cache=False): """ Initialize ``self``. @@ -161,9 +159,7 @@ def order(self): """ Return the cardinality of this field. - OUTPUT: - - Integer -- the number of elements in ``self``. + OUTPUT: integer; the number of elements in ``self`` EXAMPLES:: @@ -178,9 +174,7 @@ def degree(self): r""" If the cardinality of ``self`` is `p^n`, then this returns `n`. - OUTPUT: - - Integer -- the degree + OUTPUT: integer; the degree EXAMPLES:: @@ -334,10 +328,10 @@ def _element_constructor_(self, e): We can coerce from PARI finite field implementations:: - sage: K. = GF(3^10, impl="givaro") + sage: K. = GF(3^10, impl='givaro') sage: a^20 2*a^9 + 2*a^8 + a^7 + 2*a^5 + 2*a^4 + 2*a^3 + 1 - sage: M. = GF(3^10, impl="pari_ffelt") + sage: M. = GF(3^10, impl='pari_ffelt') sage: K(c^20) 2*a^9 + 2*a^8 + a^7 + 2*a^5 + 2*a^4 + 2*a^3 + 1 @@ -409,7 +403,7 @@ def gen(self, n=0): def prime_subfield(self): r""" - Return the prime subfield `\GF{p}` of self if ``self`` is `\GF{p^n}`. + Return the prime subfield `\GF{p}` of ``self`` if ``self`` is `\GF{p^n}`. EXAMPLES:: @@ -440,9 +434,7 @@ def log_to_int(self, n): - ``n`` -- log representation of a finite field element - OUTPUT: - - integer representation of a finite field element. + OUTPUT: integer representation of a finite field element EXAMPLES:: @@ -464,9 +456,7 @@ def int_to_log(self, n): - ``n`` -- integer representation of a finite field element - OUTPUT: - - log representation of ``n`` + OUTPUT: log representation of ``n`` EXAMPLES:: @@ -577,7 +567,7 @@ def frobenius_endomorphism(self, n=1): """ INPUT: - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) OUTPUT: diff --git a/src/sage/rings/finite_rings/finite_field_ntl_gf2e.py b/src/sage/rings/finite_rings/finite_field_ntl_gf2e.py index 654f7a2b54b..2bfda7690d3 100644 --- a/src/sage/rings/finite_rings/finite_field_ntl_gf2e.py +++ b/src/sage/rings/finite_rings/finite_field_ntl_gf2e.py @@ -53,16 +53,14 @@ class FiniteField_ntl_gf2e(FiniteField): - ``names`` -- variable used for poly_repr (default: ``'a'``) - - ``modulus`` -- A minimal polynomial to use for reduction. + - ``modulus`` -- a minimal polynomial to use for reduction - ``repr`` -- controls the way elements are printed to the user: (default: ``'poly'``) - - ``'poly'``: polynomial representation + - ``'poly'`` -- polynomial representation - OUTPUT: - - Finite field with characteristic 2 and cardinality `2^n`. + OUTPUT: finite field with characteristic 2 and cardinality `2^n` EXAMPLES:: @@ -89,7 +87,7 @@ class FiniteField_ntl_gf2e(FiniteField): True """ - def __init__(self, q, names="a", modulus=None, repr="poly"): + def __init__(self, q, names='a', modulus=None, repr='poly'): """ Initialize ``self``. @@ -107,7 +105,7 @@ def __init__(self, q, names="a", modulus=None, repr="poly"): sage: k2. = GF(2^17) sage: k1 == k2 False - sage: k3. = GF(2^16, impl="pari_ffelt") + sage: k3. = GF(2^16, impl='pari_ffelt') sage: k1 == k3 False @@ -277,7 +275,7 @@ def from_integer(self, number): INPUT: - - ``number`` -- an integer + - ``number`` -- integer EXAMPLES:: diff --git a/src/sage/rings/finite_rings/finite_field_pari_ffelt.py b/src/sage/rings/finite_rings/finite_field_pari_ffelt.py index c60a7a563a7..9549dbc94b4 100644 --- a/src/sage/rings/finite_rings/finite_field_pari_ffelt.py +++ b/src/sage/rings/finite_rings/finite_field_pari_ffelt.py @@ -195,7 +195,7 @@ def characteristic(self): def degree(self): """ - Returns the degree of ``self`` over its prime field. + Return the degree of ``self`` over its prime field. EXAMPLES:: @@ -222,7 +222,7 @@ def _pari_frobenius(self, k=1): """ k = k % self.degree() if k == 0: - raise ValueError("_pari_frobenius requires a non-zero exponent") + raise ValueError("_pari_frobenius requires a nonzero exponent") g = self.gen() i = len(self.__pari_frobenius_powers) if i == 0: diff --git a/src/sage/rings/finite_rings/finite_field_prime_modn.py b/src/sage/rings/finite_rings/finite_field_prime_modn.py index b51cf9fe7d5..d94b0a4335a 100644 --- a/src/sage/rings/finite_rings/finite_field_prime_modn.py +++ b/src/sage/rings/finite_rings/finite_field_prime_modn.py @@ -56,9 +56,9 @@ def __init__(self, p, check=True, modulus=None): INPUT: - - ``p`` -- an integer at least 2 + - ``p`` -- integer at least 2 - - ``check`` -- bool (default: ``True``); if ``False``, do not + - ``check`` -- boolean (default: ``True``); if ``False``, do not check ``p`` for primality EXAMPLES:: @@ -154,7 +154,7 @@ def _coerce_map_from_(self, S): def _convert_map_from_(self, R): """ - Conversion from p-adic fields. + Conversion from `p`-adic fields. EXAMPLES:: @@ -174,7 +174,8 @@ def _convert_map_from_(self, R): def construction(self): """ - Returns the construction of this finite field (for use by sage.categories.pushout) + Return the construction of this finite field (for use by + ``sage.categories.pushout``). EXAMPLES:: @@ -214,7 +215,7 @@ def is_prime_field(self): def polynomial(self, name=None): """ - Returns the polynomial ``name``. + Return the polynomial ``name``. EXAMPLES:: @@ -278,7 +279,7 @@ def gen(self, n=0): 1 sage: # needs sage.rings.finite_rings - sage: k = GF(1009, modulus="primitive") + sage: k = GF(1009, modulus='primitive') sage: k.gen() # this gives a primitive element 11 sage: k.gen(1) diff --git a/src/sage/rings/finite_rings/galois_group.py b/src/sage/rings/finite_rings/galois_group.py index f11b72bc681..32e23a40c44 100644 --- a/src/sage/rings/finite_rings/galois_group.py +++ b/src/sage/rings/finite_rings/galois_group.py @@ -66,11 +66,11 @@ def __init__(self, field): sage: TestSuite(GF(9).galois_group()).run() """ - GaloisGroup_cyc.__init__(self, field, (field.degree(),), gen_names="Frob") + GaloisGroup_cyc.__init__(self, field, (field.degree(),), gen_names='Frob') def _repr_(self): r""" - String representation of this Galois group + String representation of this Galois group. EXAMPLES:: diff --git a/src/sage/rings/finite_rings/hom_finite_field.pyx b/src/sage/rings/finite_rings/hom_finite_field.pyx index 9aa5db8ea86..d55e1a0a178 100644 --- a/src/sage/rings/finite_rings/hom_finite_field.pyx +++ b/src/sage/rings/finite_rings/hom_finite_field.pyx @@ -196,7 +196,6 @@ cdef class FiniteFieldHomomorphism_generic(RingHomomorphism_im_gens): sage: K. = GF(3^21) sage: f = FiniteFieldHomomorphism_generic(Hom(k, K)) sage: TestSuite(f).run() - """ def __init__(self, parent, im_gens=None, base_map=None, check=True, section_class=None): """ @@ -423,7 +422,7 @@ cdef class FiniteFieldHomomorphism_generic(RingHomomorphism_im_gens): def __hash__(self): r""" - Return a hash of this morphism + Return a hash of this morphism. TESTS:: @@ -437,7 +436,7 @@ cdef class FiniteFieldHomomorphism_generic(RingHomomorphism_im_gens): cdef dict _extra_slots(self): r""" - Helper function for copying and pickling + Helper function for copying and pickling. TESTS:: @@ -465,7 +464,7 @@ cdef class FiniteFieldHomomorphism_generic(RingHomomorphism_im_gens): cdef _update_slots(self, dict slots): r""" - Helper function for copying and pickling + Helper function for copying and pickling. TESTS:: @@ -494,15 +493,14 @@ cdef class FrobeniusEndomorphism_finite_field(FrobeniusEndomorphism_generic): sage: k. = GF(7^11) sage: Frob = k.frobenius_endomorphism(5) sage: TestSuite(Frob).run() - """ def __init__(self, domain, n=1): """ INPUT: - - ``domain`` -- a finite field + - ``domain`` -- a finite field - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) .. NOTE:: @@ -713,7 +711,7 @@ cdef class FrobeniusEndomorphism_finite_field(FrobeniusEndomorphism_generic): def _composition(self, right): """ - Return self o right. + Return ``self`` o ``right``. EXAMPLES:: @@ -830,7 +828,7 @@ cdef class FrobeniusEndomorphism_finite_field(FrobeniusEndomorphism_generic): def __hash__(self): r""" - Return a hash of this morphism + Return a hash of this morphism. EXAMPLES:: @@ -843,7 +841,7 @@ cdef class FrobeniusEndomorphism_finite_field(FrobeniusEndomorphism_generic): cdef _update_slots(self, dict slots): r""" - Helper function for copying and pickling + Helper function for copying and pickling. TESTS:: diff --git a/src/sage/rings/finite_rings/hom_prime_finite_field.pyx b/src/sage/rings/finite_rings/hom_prime_finite_field.pyx index e45de1d83f9..c53a87ddca0 100644 --- a/src/sage/rings/finite_rings/hom_prime_finite_field.pyx +++ b/src/sage/rings/finite_rings/hom_prime_finite_field.pyx @@ -117,9 +117,9 @@ cdef class FrobeniusEndomorphism_prime(FrobeniusEndomorphism_finite_field): def _composition(self, right): """ - Return self o right. + Return ``self`` o ``right``. - It is always right, since self is always identity because + It is always ``right``, since ``self`` is always identity because the domain is a prime field. """ return right diff --git a/src/sage/rings/finite_rings/homset.py b/src/sage/rings/finite_rings/homset.py index ef72f35a1a5..6c15d725f43 100644 --- a/src/sage/rings/finite_rings/homset.py +++ b/src/sage/rings/finite_rings/homset.py @@ -159,7 +159,7 @@ def _repr_(self): def is_aut(self): """ - Check if ``self`` is an automorphism + Check if ``self`` is an automorphism. EXAMPLES:: @@ -233,7 +233,7 @@ def list(self): Between isomorphic fields with different moduli:: sage: k1 = GF(1009) - sage: k2 = GF(1009, modulus="primitive") + sage: k2 = GF(1009, modulus='primitive') sage: Hom(k1, k2).list() [ Ring morphism: @@ -249,8 +249,8 @@ def list(self): Defn: 11 |--> 11 ] - sage: k1. = GF(1009^2, modulus="first_lexicographic") - sage: k2. = GF(1009^2, modulus="conway") + sage: k1. = GF(1009^2, modulus='first_lexicographic') + sage: k2. = GF(1009^2, modulus='conway') sage: Hom(k1, k2).list() [ Ring morphism: @@ -348,7 +348,6 @@ def _an_element_(self): .. TODO:: Use a more sophisticated algorithm; see also :issue:`8751`. - """ K = self.domain() L = self.codomain() diff --git a/src/sage/rings/finite_rings/integer_mod.pyx b/src/sage/rings/finite_rings/integer_mod.pyx index abb92d41ff7..0b220e81a1e 100644 --- a/src/sage/rings/finite_rings/integer_mod.pyx +++ b/src/sage/rings/finite_rings/integer_mod.pyx @@ -7,20 +7,20 @@ There are three types of integer_mod classes, depending on the size of the modulus. -- ``IntegerMod_int`` stores its value in a - ``int_fast32_t`` (typically an ``int``); - this is used if the modulus is less than - `\sqrt{2^{31}-1}`. +- ``IntegerMod_int`` stores its value in a + ``int_fast32_t`` (typically an ``int``); + this is used if the modulus is less than + `\sqrt{2^{31}-1}`. -- ``IntegerMod_int64`` stores its value in a - ``int_fast64_t`` (typically a ``long - long``); this is used if the modulus is less than - `2^{31}-1`. In many places, we assume that the values and the modulus - actually fit inside an ``unsigned long``. +- ``IntegerMod_int64`` stores its value in a + ``int_fast64_t`` (typically a ``long + long``); this is used if the modulus is less than + `2^{31}-1`. In many places, we assume that the values and the modulus + actually fit inside an ``unsigned long``. -- ``IntegerMod_gmp`` stores its value in a - ``mpz_t``; this can be used for an arbitrarily large - modulus. +- ``IntegerMod_gmp`` stores its value in a + ``mpz_t``; this can be used for an arbitrarily large + modulus. All extend ``IntegerMod_abstract``. @@ -151,7 +151,7 @@ def Mod(n, m, parent=None): if m == 0: return n - # m is non-zero, so return n mod m + # m is nonzero, so return n mod m if parent is None: from sage.rings.finite_rings.integer_mod_ring import IntegerModRing parent = IntegerModRing(m) @@ -479,7 +479,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): Coerce this element to the ring `Z/(modulus)`. If the new ``modulus`` does not divide the current modulus, - an ``ArithmeticError`` is raised. + an :exc:`ArithmeticError` is raised. EXAMPLES:: @@ -605,7 +605,6 @@ cdef class IntegerMod_abstract(FiniteRingElement): 4 sage: aa.typeOf() # optional - fricas IntegerMod(15) - """ return '%s :: %s'%(self, self.parent()._axiom_init_()) @@ -647,24 +646,22 @@ cdef class IntegerMod_abstract(FiniteRingElement): INPUT: + - ``self`` -- unit modulo `n` - - ``self`` -- unit modulo `n` - - - ``b`` -- a unit modulo `n`. If ``b`` is not given, - ``R.multiplicative_generator()`` is used, where - ``R`` is the parent of ``self``. - - - ``order`` -- integer (unused), the order of ``b``. - This argument is normally unused, only there for - coherence of apis with finite field elements. + - ``b`` -- a unit modulo `n`. If ``b`` is not given, + ``R.multiplicative_generator()`` is used, where + ``R`` is the parent of ``self``. - - ``check`` -- boolean (default: ``False``). If set, - test whether the given ``order`` is correct. + - ``order`` -- integer (unused), the order of ``b``. + This argument is normally unused, only there for + coherence of apis with finite field elements. + - ``check`` -- boolean (default: ``False``); if set, + test whether the given ``order`` is correct OUTPUT: - Integer `x` such that `b^x = a`, if this exists; a :class:`ValueError` + Integer `x` such that `b^x = a`, if this exists; a :exc:`ValueError` otherwise. .. NOTE:: @@ -842,7 +839,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def generalised_log(self): r""" - Return integers `[n_1, \ldots, n_d]` such that + Return integers `[n_1, \ldots, n_d]` such that. .. MATH:: @@ -872,7 +869,6 @@ cdef class IntegerMod_abstract(FiniteRingElement): of the parent (which is the default). Specifying ``algorithm='pari'`` usually yields a different set of generators that is incompatible with this method. - """ if not self.is_unit(): raise ZeroDivisionError @@ -902,7 +898,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def charpoly(self, var='x'): """ - Returns the characteristic polynomial of this element. + Return the characteristic polynomial of this element. EXAMPLES:: @@ -922,7 +918,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def minpoly(self, var='x'): """ - Returns the minimal polynomial of this element. + Return the minimal polynomial of this element. EXAMPLES:: @@ -933,7 +929,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def minimal_polynomial(self, var='x'): """ - Returns the minimal polynomial of this element. + Return the minimal polynomial of this element. EXAMPLES:: @@ -944,7 +940,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def polynomial(self, var='x'): """ - Returns a constant polynomial representing this value. + Return a constant polynomial representing this value. EXAMPLES:: @@ -961,7 +957,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def norm(self): """ - Returns the norm of this element, which is itself. (This is here + Return the norm of this element, which is itself. (This is here for compatibility with higher order finite fields.) EXAMPLES:: @@ -979,7 +975,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def trace(self): """ - Returns the trace of this element, which is itself. (This is here + Return the trace of this element, which is itself. (This is here for compatibility with higher order finite fields.) EXAMPLES:: @@ -1140,14 +1136,12 @@ cdef class IntegerMod_abstract(FiniteRingElement): INPUT: - - ``extend`` -- bool (default: ``True``); - if ``True``, return a square root in an extension ring, - if necessary. Otherwise, raise a ``ValueError`` if the - square root is not in the base ring. + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the square root is not in the base ring. - - ``all`` -- bool (default: ``False``); if - ``True``, return {all} square roots of self, instead of - just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return {all} + square roots of self, instead of just one ALGORITHM: Calculates the square roots mod `p` for each of the primes `p` dividing the order of the ring, then lifts @@ -1358,38 +1352,38 @@ cdef class IntegerMod_abstract(FiniteRingElement): def nth_root(self, n, extend = False, all = False, algorithm = None, cunningham = False): r""" - Returns an `n`\th root of ``self``. + Return an `n`-th root of ``self``. INPUT: - ``n`` -- integer `\geq 1` - - ``extend`` -- bool (default: ``True``); if True, return an nth - root in an extension ring, if necessary. Otherwise, raise a - ValueError if the root is not in the base ring. Warning: + - ``extend`` -- boolean (default: ``True``); if ``True``, return an + `n`-th root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the root is not in the base ring. Warning: this option is not implemented! - - ``all`` -- bool (default: ``False``); if ``True``, return all `n`\th - roots of ``self``, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all + `n`-th roots of ``self``, instead of just one - - ``algorithm`` -- string (default: None); The algorithm for the prime modulus case. - CRT and p-adic log techniques are used to reduce to this case. - 'Johnston' is the only currently supported option. + - ``algorithm`` -- string (default: ``None``); the algorithm for the + prime modulus case. CRT and `p`-adic log techniques are used to reduce + to this case. ``'Johnston'`` is the only currently supported option. - - ``cunningham`` -- bool (default: ``False``); In some cases, - factorization of ``n`` is computed. If cunningham is set to ``True``, - the factorization of ``n`` is computed using trial division for all + - ``cunningham`` -- boolean (default: ``False``); in some cases, + factorization of `n` is computed. If cunningham is set to ``True``, + the factorization of `n` is computed using trial division for all primes in the so called Cunningham table. Refer to - sage.rings.factorint.factor_cunningham for more information. You need - to install an optional package to use this method, this can be done - with the following command line ``sage -i cunningham_tables`` + ``sage.rings.factorint.factor_cunningham`` for more information. You + need to install an optional package to use this method, this can be + done with the following command line: ``sage -i cunningham_tables``. OUTPUT: - If self has an `n`\th root, returns one (if ``all`` is ``False``) or a + If ``self`` has an `n`-th root, returns one (if ``all`` is ``False``) or a list of all of them (if ``all`` is ``True``). Otherwise, raises a - ``ValueError`` (if ``extend`` is ``False``) or a ``NotImplementedError`` (if - ``extend`` is ``True``). + :exc:`ValueError` (if ``extend`` is ``False``) or a + :exc:`NotImplementedError` (if ``extend`` is ``True``). .. warning:: @@ -1411,13 +1405,13 @@ cdef class IntegerMod_abstract(FiniteRingElement): - if ``self=1``: ``self`` is returned - - otherwise; a ``ValueError`` is raised + - otherwise; a :exc:`ValueError` is raised - If `n < 0`: - - if self is invertible, the `(-n)`\th root of the inverse of self is returned + - if ``self`` is invertible, the `(-n)`\th root of the inverse of ``self`` is returned - - otherwise a ``ValueError`` is raised or empty list returned. + - otherwise a :exc:`ValueError` is raised or empty list returned. EXAMPLES:: @@ -1620,7 +1614,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def _nth_root_naive(self, n): """ - Computes all nth roots using brute force, for doc-testing. + Compute all `n`-th roots using brute force, for doc-testing. TESTS:: @@ -1758,7 +1752,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def additive_order(self): r""" - Returns the additive order of self. + Return the additive order of ``self``. This is the same as ``self.order()``. @@ -1867,7 +1861,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def multiplicative_order(self): """ - Returns the multiplicative order of self. + Return the multiplicative order of ``self``. EXAMPLES:: @@ -1932,7 +1926,6 @@ cdef class IntegerMod_abstract(FiniteRingElement): +Infinity sage: ZZ.quo(1024)(16).valuation(4) 2 - """ p=self._modulus.sageInteger.gcd(p) if p==1: @@ -1972,7 +1965,7 @@ cdef class IntegerMod_abstract(FiniteRingElement): def _vector_(self): """ - Return self as a vector of its parent viewed as a one-dimensional + Return ``self`` as a vector of its parent viewed as a one-dimensional vector space. This is to support prime finite fields, which are implemented as @@ -2037,7 +2030,7 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): def __lshift__(IntegerMod_gmp self, k): r""" - Performs a left shift by ``k`` bits. + Perform a left shift by ``k`` bits. For details, see :meth:`shift`. @@ -2051,7 +2044,7 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): def __rshift__(IntegerMod_gmp self, k): r""" - Performs a right shift by ``k`` bits. + Perform a right shift by ``k`` bits. For details, see :meth:`shift`. @@ -2065,7 +2058,7 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): cdef shift(IntegerMod_gmp self, long k): r""" - Performs a bit-shift specified by ``k`` on ``self``. + Perform a bit-shift specified by ``k`` on ``self``. Suppose that ``self`` represents an integer `x` modulo `n`. If `k` is `k = 0`, returns `x`. If `k > 0`, shifts `x` to the left, that is, @@ -2077,11 +2070,9 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): INPUT: - - ``k`` -- Integer of type ``long`` + - ``k`` -- integer of type ``long`` - OUTPUT: - - - Result of type ``IntegerMod_gmp`` + OUTPUT: result of type ``IntegerMod_gmp`` EXAMPLES:: @@ -2122,8 +2113,7 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): cpdef bint is_one(IntegerMod_gmp self) noexcept: """ - Returns ``True`` if this is `1`, otherwise - ``False``. + Return ``True`` if this is `1`, otherwise ``False``. EXAMPLES:: @@ -2136,8 +2126,7 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): def __bool__(IntegerMod_gmp self): """ - Returns ``True`` if this is not `0`, otherwise - ``False``. + Return ``True`` if this is not `0`, otherwise ``False``. EXAMPLES:: @@ -2334,7 +2323,6 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): sage: zero^0 0 - """ cdef IntegerMod_gmp x = self._new_c() sig_on() @@ -2346,7 +2334,7 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): def __invert__(IntegerMod_gmp self): """ - Return the multiplicative inverse of self. + Return the multiplicative inverse of ``self``. EXAMPLES:: @@ -2402,14 +2390,14 @@ cdef class IntegerMod_gmp(IntegerMod_abstract): @coerce_binop def gcd(self, IntegerMod_gmp other): r""" - Greatest common divisor + Greatest common divisor. Returns the "smallest" generator in `\ZZ / N\ZZ` of the ideal generated by ``self`` and ``other``. INPUT: - - ``other`` -- an element of the same ring as this one. + - ``other`` -- an element of the same ring as this one EXAMPLES:: @@ -2505,8 +2493,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): cpdef bint is_one(IntegerMod_int self) noexcept: """ - Returns ``True`` if this is `1`, otherwise - ``False``. + Return ``True`` if this is `1`, otherwise ``False``. EXAMPLES:: @@ -2523,8 +2510,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): def __bool__(IntegerMod_int self): """ - Returns ``True`` if this is not `0`, otherwise - ``False``. + Return ``True`` if this is not `0`, otherwise ``False``. EXAMPLES:: @@ -2553,9 +2539,9 @@ cdef class IntegerMod_int(IntegerMod_abstract): def _crt(IntegerMod_int self, IntegerMod_int other): """ Use the Chinese Remainder Theorem to find an element of the - integers modulo the product of the moduli that reduces to self and - to other. The modulus of other must be coprime to the modulus of - self. + integers modulo the product of the moduli that reduces to ``self`` and + to ``other``. The modulus of ``other`` must be coprime to the modulus + of ``self``. EXAMPLES:: @@ -2699,7 +2685,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): def __lshift__(IntegerMod_int self, k): r""" - Performs a left shift by ``k`` bits. + Perform a left shift by ``k`` bits. For details, see :meth:`shift`. @@ -2715,7 +2701,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): def __rshift__(IntegerMod_int self, k): r""" - Performs a right shift by ``k`` bits. + Perform a right shift by ``k`` bits. For details, see :meth:`shift`. @@ -2731,7 +2717,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): cdef shift(IntegerMod_int self, int k): """ - Performs a bit-shift specified by ``k`` on ``self``. + Perform a bit-shift specified by ``k`` on ``self``. Suppose that ``self`` represents an integer `x` modulo `n`. If `k` is `k = 0`, returns `x`. If `k > 0`, shifts `x` to the left, that is, @@ -2743,11 +2729,9 @@ cdef class IntegerMod_int(IntegerMod_abstract): INPUT: - - ``k`` -- Integer of type ``int`` - - OUTPUT: + - ``k`` -- integer of type ``int`` - - Result of type ``IntegerMod_int`` + OUTPUT: result of type ``IntegerMod_int`` WARNING: @@ -2817,7 +2801,6 @@ cdef class IntegerMod_int(IntegerMod_abstract): sage: R = Integers(1) sage: R(0)^0 0 - """ cdef long long_exp cdef int_fast32_t res @@ -2853,7 +2836,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): def __invert__(IntegerMod_int self): """ - Return the multiplicative inverse of self. + Return the multiplicative inverse of ``self``. EXAMPLES:: @@ -2931,14 +2914,14 @@ cdef class IntegerMod_int(IntegerMod_abstract): INPUT: - - ``extend`` -- bool (default: ``True``); - if ``True``, return a square root in an extension ring, - if necessary. Otherwise, raise a ``ValueError`` if the - square root is not in the base ring. + - ``extend`` -- boolean (default: ``True``); + if ``True``, return a square root in an extension ring, + if necessary. Otherwise, raise a :exc:`ValueError` if the + square root is not in the base ring. - - ``all`` -- bool (default: ``False``); if - ``True``, return {all} square roots of self, instead of - just one. + - ``all`` -- boolean (default: ``False``); if + ``True``, return {all} square roots of self, instead of + just one. ALGORITHM: Calculates the square roots mod `p` for each of the primes `p` dividing the order of the ring, then lifts @@ -3042,7 +3025,7 @@ cdef class IntegerMod_int(IntegerMod_abstract): # easy case of n prime, n = 3 mod 4. if n > 100 and n % 4 == 3 and len(moduli) == 1 and moduli[0][1] == 1: if jacobi_int(self.ivalue, self._modulus.int32) == 1: - # it's a non-zero square, sqrt(a) = a^(p+1)/4 + # it's a nonzero square, sqrt(a) = a^(p+1)/4 i = mod_pow_int(self.ivalue, (self._modulus.int32+1)/4, n) if i > n / 2: i = n - i @@ -3085,14 +3068,14 @@ cdef class IntegerMod_int(IntegerMod_abstract): @coerce_binop def gcd(self, IntegerMod_int other): r""" - Greatest common divisor + Greatest common divisor. Returns the "smallest" generator in `\ZZ / N\ZZ` of the ideal generated by ``self`` and ``other``. INPUT: - - ``other`` -- an element of the same ring as this one. + - ``other`` -- an element of the same ring as this one EXAMPLES:: @@ -3122,9 +3105,9 @@ cdef class IntegerMod_int(IntegerMod_abstract): cdef int_fast32_t gcd_int(int_fast32_t a, int_fast32_t b) noexcept: """ - Returns the gcd of a and b + Return the gcd of ``a`` and ``b``. - For use with IntegerMod_int + For use with ``IntegerMod_int``. AUTHORS: @@ -3144,9 +3127,9 @@ cdef int_fast32_t gcd_int(int_fast32_t a, int_fast32_t b) noexcept: cdef int_fast32_t mod_inverse_int(int_fast32_t x, int_fast32_t n) except 0: """ - Returns y such that xy=1 mod n + Return y such that xy=1 mod n. - For use in IntegerMod_int + For use in ``IntegerMod_int``. AUTHORS: @@ -3178,9 +3161,9 @@ cdef int_fast32_t mod_inverse_int(int_fast32_t x, int_fast32_t n) except 0: cdef int_fast32_t mod_pow_int(int_fast32_t base, int_fast32_t exp, int_fast32_t n) noexcept: """ - Returns base^exp mod n + Return base^exp mod n. - For use in IntegerMod_int + For use in ``IntegerMod_int``. EXAMPLES:: @@ -3220,9 +3203,9 @@ cdef int_fast32_t mod_pow_int(int_fast32_t base, int_fast32_t exp, int_fast32_t cdef int jacobi_int(int_fast32_t a, int_fast32_t m) except -2: """ - Calculates the jacobi symbol (a/n) + Calculate the jacobi symbol (a/n). - For use in IntegerMod_int + For use in ``IntegerMod_int``. AUTHORS: @@ -3336,8 +3319,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): cpdef bint is_one(IntegerMod_int64 self) noexcept: """ - Returns ``True`` if this is `1`, otherwise - ``False``. + Return ``True`` if this is `1`, otherwise ``False``. EXAMPLES:: @@ -3350,8 +3332,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def __bool__(IntegerMod_int64 self): """ - Returns ``True`` if this is not `0`, otherwise - ``False``. + Return ``True`` if this is not `0`, otherwise ``False``. EXAMPLES:: @@ -3378,9 +3359,9 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def _crt(IntegerMod_int64 self, IntegerMod_int64 other): """ Use the Chinese Remainder Theorem to find an element of the - integers modulo the product of the moduli that reduces to self and - to other. The modulus of other must be coprime to the modulus of - self. + integers modulo the product of the moduli that reduces to ``self`` and + to ``other``. The modulus of ``other`` must be coprime to the modulus + of ``self``. EXAMPLES:: @@ -3520,7 +3501,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def __lshift__(IntegerMod_int64 self, k): r""" - Performs a left shift by ``k`` bits. + Perform a left shift by ``k`` bits. For details, see :meth:`shift`. @@ -3536,7 +3517,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def __rshift__(IntegerMod_int64 self, k): r""" - Performs a right shift by ``k`` bits. + Perform a right shift by ``k`` bits. For details, see :meth:`shift`. @@ -3550,7 +3531,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): cdef shift(IntegerMod_int64 self, int k): """ - Performs a bit-shift specified by ``k`` on ``self``. + Perform a bit-shift specified by ``k`` on ``self``. Suppose that ``self`` represents an integer `x` modulo `n`. If `k` is `k = 0`, returns `x`. If `k > 0`, shifts `x` to the left, that is, @@ -3562,11 +3543,9 @@ cdef class IntegerMod_int64(IntegerMod_abstract): INPUT: - - ``k`` -- Integer of type ``int`` - - OUTPUT: + - ``k`` -- integer of type ``int`` - - Result of type ``IntegerMod_int64`` + OUTPUT: result of type ``IntegerMod_int64`` WARNING: @@ -3647,7 +3626,6 @@ cdef class IntegerMod_int64(IntegerMod_abstract): sage: zero^0 0 - """ cdef long long_exp cdef int_fast64_t res @@ -3683,7 +3661,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def __invert__(IntegerMod_int64 self): """ - Return the multiplicative inverse of self. + Return the multiplicative inverse of ``self``. EXAMPLES:: @@ -3716,7 +3694,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def __float__(IntegerMod_int64 self): """ - Coerce self to a float. + Coerce ``self`` to a float. EXAMPLES:: @@ -3728,7 +3706,7 @@ cdef class IntegerMod_int64(IntegerMod_abstract): def __hash__(self): """ - Compute hash of self. + Compute hash of ``self``. EXAMPLES:: @@ -3750,14 +3728,14 @@ cdef class IntegerMod_int64(IntegerMod_abstract): @coerce_binop def gcd(self, IntegerMod_int64 other): r""" - Greatest common divisor + Greatest common divisor. Returns the "smallest" generator in `\ZZ / N\ZZ` of the ideal generated by ``self`` and ``other``. INPUT: - - ``other`` -- an element of the same ring as this one. + - ``other`` -- an element of the same ring as this one EXAMPLES:: @@ -3797,9 +3775,9 @@ cdef int mpz_pow_helper(mpz_t res, mpz_t base, object exp, mpz_t modulus) except cdef int_fast64_t gcd_int64(int_fast64_t a, int_fast64_t b) noexcept: """ - Returns the gcd of a and b + Return the gcd of ``a`` and ``b``. - For use with IntegerMod_int64 + For use with IntegerMod_int64. AUTHORS: @@ -3819,9 +3797,9 @@ cdef int_fast64_t gcd_int64(int_fast64_t a, int_fast64_t b) noexcept: cdef int_fast64_t mod_inverse_int64(int_fast64_t x, int_fast64_t n) except 0: """ - Returns y such that xy=1 mod n + Return y such that xy=1 mod n. - For use in IntegerMod_int64 + For use in ``IntegerMod_int64``. AUTHORS: @@ -3851,9 +3829,9 @@ cdef int_fast64_t mod_inverse_int64(int_fast64_t x, int_fast64_t n) except 0: cdef int_fast64_t mod_pow_int64(int_fast64_t base, int_fast64_t exp, int_fast64_t n) noexcept: """ - Returns base^exp mod n + Return base^exp mod n. - For use in IntegerMod_int64 + For use in ``IntegerMod_int64``. AUTHORS: @@ -3887,9 +3865,9 @@ cdef int_fast64_t mod_pow_int64(int_fast64_t base, int_fast64_t exp, int_fast64_ cdef int jacobi_int64(int_fast64_t a, int_fast64_t m) except -2: """ - Calculates the jacobi symbol (a/n) + Calculate the jacobi symbol (a/n). - For use in IntegerMod_int64 + For use in ``IntegerMod_int64``. AUTHORS: @@ -3931,7 +3909,7 @@ cdef int jacobi_int64(int_fast64_t a, int_fast64_t m) except -2: def square_root_mod_prime_power(IntegerMod_abstract a, p, e): r""" - Calculates the square root of `a`, where `a` is an + Calculate the square root of `a`, where `a` is an integer mod `p^e`. ALGORITHM: Compute `p`-adically by stripping off even powers of `p` @@ -4027,7 +4005,7 @@ def square_root_mod_prime_power(IntegerMod_abstract a, p, e): cpdef square_root_mod_prime(IntegerMod_abstract a, p=None): r""" - Calculates the square root of `a`, where `a` is an + Calculate the square root of `a`, where `a` is an integer mod `p`; if `a` is not a perfect square, this returns an (incorrect) answer without checking. @@ -4035,19 +4013,17 @@ cpdef square_root_mod_prime(IntegerMod_abstract a, p=None): `p \bmod 16`. - - `p \bmod 2 = 0`: `p = 2` so - `\sqrt{a} = a`. + - `p \bmod 2 = 0`: `p = 2` so `\sqrt{a} = a`. - - `p \bmod 4 = 3`: `\sqrt{a} = a^{(p+1)/4}`. + - `p \bmod 4 = 3`: `\sqrt{a} = a^{(p+1)/4}`. - - `p \bmod 8 = 5`: `\sqrt{a} = \zeta i a` where - `\zeta = (2a)^{(p-5)/8}`, `i=\sqrt{-1}`. + - `p \bmod 8 = 5`: `\sqrt{a} = \zeta i a` where `\zeta = (2a)^{(p-5)/8}`, + `i=\sqrt{-1}`. - - `p \bmod 16 = 9`: Similar, work in a bi-quadratic - extension of `\GF{p}` for small `p`, Tonelli - and Shanks for large `p`. + - `p \bmod 16 = 9`: Similar, work in a bi-quadratic extension of `\GF{p}` + for small `p`, Tonelli and Shanks for large `p`. - - `p \bmod 16 = 1`: Tonelli and Shanks. + - `p \bmod 16 = 1`: Tonelli and Shanks. REFERENCES: @@ -4135,7 +4111,7 @@ cpdef square_root_mod_prime(IntegerMod_abstract a, p=None): def lucas_q1(mm, IntegerMod_abstract P): """ Return `V_k(P, 1)` where `V_k` is the Lucas - function defined by the recursive relation + function defined by the recursive relation. `V_k(P, Q) = PV_{k-1}(P, Q) - QV_{k-2}(P, Q)` @@ -4349,7 +4325,6 @@ cdef class IntegerMod_hom(Morphism): To: Ring of integers modulo 5 sage: psi(R15(7)) 2 - """ Morphism._update_slots(self, _slots) self.zero = _slots['zero'] @@ -4413,7 +4388,6 @@ cdef class IntegerMod_to_IntegerMod(IntegerMod_hom): sage: Zmod(4).hom(Zmod(2)).is_surjective() True - """ return True @@ -4425,14 +4399,12 @@ cdef class IntegerMod_to_IntegerMod(IntegerMod_hom): sage: Zmod(4).hom(Zmod(2)).is_injective() False - """ return self.domain().order() == self.codomain().order() cdef class Integer_to_IntegerMod(IntegerMod_hom): r""" - Fast `\ZZ \rightarrow \ZZ/n\ZZ` - morphism. + Fast `\ZZ \rightarrow \ZZ/n\ZZ` morphism. EXAMPLES: @@ -4484,7 +4456,6 @@ cdef class Integer_to_IntegerMod(IntegerMod_hom): sage: ZZ.hom(Zmod(2)).is_surjective() True - """ return True @@ -4496,7 +4467,6 @@ cdef class Integer_to_IntegerMod(IntegerMod_hom): sage: ZZ.hom(Zmod(2)).is_injective() False - """ return False diff --git a/src/sage/rings/finite_rings/integer_mod_ring.py b/src/sage/rings/finite_rings/integer_mod_ring.py index 6876d569e4c..5117119dbf4 100644 --- a/src/sage/rings/finite_rings/integer_mod_ring.py +++ b/src/sage/rings/finite_rings/integer_mod_ring.py @@ -93,10 +93,9 @@ class IntegerModFactory(UniqueFactory): INPUT: - ``order`` -- integer (default: 0); positive or negative - - ``is_field`` -- bool (default: ``False``); assert that - the order is prime and hence the quotient ring belongs to - the category of fields - - ``category`` (optional) -- the category that the quotient ring belongs to. + - ``is_field`` -- boolean (default: ``False``); assert that the order is + prime and hence the quotient ring belongs to the category of fields + - ``category`` -- (optional) the category that the quotient ring belongs to .. NOTE:: @@ -199,7 +198,6 @@ class IntegerModFactory(UniqueFactory): the ring factory:: sage: IntegerModRing._cache.clear() - """ def get_object(self, version, key, extra_args): out = super().get_object(version, key, extra_args) @@ -289,13 +287,11 @@ class IntegerModRing_generic(quotient_ring.QuotientRing_generic, sage.rings.abc. INPUT: - - ``order`` -- an integer + - ``order`` -- integer - ``category`` -- a subcategory of ``CommutativeRings()`` (the default) - OUTPUT: - - The ring of integers modulo `N`. + OUTPUT: the ring of integers modulo `N` EXAMPLES: @@ -500,7 +496,7 @@ def _macaulay2_init_(self, macaulay2=None): def _axiom_init_(self): """ - Returns a string representation of self in (Pan)Axiom. + Return a string representation of ``self`` in (Pan)Axiom. EXAMPLES:: @@ -575,7 +571,7 @@ def is_prime_field(self): def _precompute_table(self): """ - Computes a table of elements so that elements are unique. + Compute a table of elements so that elements are unique. EXAMPLES:: @@ -680,12 +676,12 @@ def is_field(self, proof=None): INPUT: - - ``proof`` (optional bool or None, default None): - If ``False``, then test whether the category of the quotient - is a subcategory of ``Fields()``, or do a probabilistic - primality test. If ``None``, then test the category and then - do a primality test according to the global arithmetic proof - settings. If True, do a deterministic primality test. + - ``proof`` -- boolean or ``None`` (default). If ``False``, then test + whether the category of the quotient is a subcategory of + ``Fields()``, or do a probabilistic primality test. If ``None``, then + test the category and then do a primality test according to the + global arithmetic proof settings. If ``True``, do a deterministic + primality test. If it is found (perhaps probabilistically) that the ring is a field, then the category of the ring is refined to include the category @@ -717,8 +713,8 @@ def is_field(self, proof=None): and Category of quotients of semigroups It is possible to mistakenly put `\ZZ/n\ZZ` into the category of fields. - In this case, :meth:`is_field` will return True without performing a - primality check. However, if the optional argument `proof=True` is + In this case, :meth:`is_field` will return ``True`` without performing a + primality check. However, if the optional argument ``proof=True`` is provided, primality is tested and the mistake is uncovered in a warning message:: @@ -739,7 +735,6 @@ def is_field(self, proof=None): of the ring factory:: sage: IntegerModRing._cache.clear() - """ from sage.categories.fields import Fields if not proof: @@ -764,7 +759,7 @@ def field(self): """ If this ring is a field, return the corresponding field as a finite field, which may have extra functionality and structure. Otherwise, - raise a ``ValueError``. + raise a :exc:`ValueError`. EXAMPLES:: @@ -926,9 +921,7 @@ def square_roots_of_one(self): Return all square roots of 1 in self, i.e., all solutions to `x^2 - 1 = 0`. - OUTPUT: - - The square roots of 1 in ``self`` as a tuple. + OUTPUT: the square roots of 1 in ``self`` as a tuple EXAMPLES:: @@ -1274,7 +1267,7 @@ def _coerce_map_from_(self, S): def _convert_map_from_(self, other): """ - Conversion from p-adic fields. + Conversion from `p`-adic fields. EXAMPLES:: @@ -1316,7 +1309,6 @@ def __richcmp__(self, other, op): True sage: R2 == GF(5) False - """ # We want that GF(p) and IntegerModRing(p) evaluate unequal. # However, we cannot just compare the types, since the @@ -1333,7 +1325,7 @@ def __richcmp__(self, other, op): def unit_gens(self, **kwds): r""" - Returns generators for the unit group `(\ZZ/N\ZZ)^*`. + Return generators for the unit group `(\ZZ/N\ZZ)^*`. We compute the list of generators using a deterministic algorithm, so the generators list will always be the same. For each odd prime divisor @@ -1341,9 +1333,7 @@ def unit_gens(self, **kwds): even there will be 0, 1 or 2 generators according to whether 2 divides `N` to order 1, 2 or `\geq 3`. - OUTPUT: - - A tuple containing the units of ``self``. + OUTPUT: a tuple containing the units of ``self`` EXAMPLES:: @@ -1374,7 +1364,6 @@ def unit_gens(self, **kwds): (3,) sage: IntegerModRing(8).unit_gens() # needs sage.groups (7, 5) - """ return self.unit_group(**kwds).gens_values() @@ -1509,7 +1498,6 @@ def unit_group(self, algorithm='sage'): Traceback (most recent call last): ... ValueError: unknown algorithm 'bogus' for computing the unit group - """ from sage.groups.abelian_gps.values import AbelianGroupWithValues if algorithm == 'sage': @@ -1536,9 +1524,9 @@ def random_element(self, bound=None): INPUT: - - ``bound``, a positive integer or ``None`` (the default). Is given, + - ``bound`` -- positive integer or ``None`` (the default); if given, return the coercion of an integer in the interval - ``[-bound, bound]`` into this ring. + ``[-bound, bound]`` into this ring EXAMPLES:: diff --git a/src/sage/rings/finite_rings/maps_finite_field.py b/src/sage/rings/finite_rings/maps_finite_field.py index 9c8713f1a61..e68bd5c7b94 100644 --- a/src/sage/rings/finite_rings/maps_finite_field.py +++ b/src/sage/rings/finite_rings/maps_finite_field.py @@ -40,7 +40,6 @@ def _repr_(self): Isomorphism: From: Vector space of dimension 1 over Finite Field in z4 of size 2^4 To: Finite Field in z4 of size 2^4 - """ s = "Isomorphism:" s += "\n From: {}".format(self.domain()) diff --git a/src/sage/rings/finite_rings/residue_field.pyx b/src/sage/rings/finite_rings/residue_field.pyx index 7a7fa6dfc23..3146f7fd764 100644 --- a/src/sage/rings/finite_rings/residue_field.pyx +++ b/src/sage/rings/finite_rings/residue_field.pyx @@ -182,14 +182,14 @@ from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ from sage.rings.finite_rings.finite_field_constructor import zech_log_bound, FiniteField as GF from sage.rings.finite_rings.finite_field_prime_modn import FiniteField_prime_modn -from sage.rings.ideal import is_Ideal +from sage.rings.ideal import Ideal_generic from sage.rings.number_field.number_field_element_base import NumberFieldElement_base from sage.rings.number_field.number_field_ideal import NumberFieldIdeal from sage.rings.fraction_field import FractionField_generic from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polynomial_element import Polynomial from sage.structure.element cimport Element, parent, Vector @@ -205,17 +205,15 @@ class ResidueFieldFactory(UniqueFactory): INPUT: - - ``p`` -- a prime ideal of an order in a number field. + - ``p`` -- a prime ideal of an order in a number field - - ``names`` -- the variable name for the finite field created. - Defaults to the name of the number field variable but with - bar placed after it. + - ``names`` -- the variable name for the finite field created; + defaults to the name of the number field variable but with + bar placed after it - - ``check`` -- whether or not to check if `p` is prime. + - ``check`` -- whether or not to check if `p` is prime - OUTPUT: - - The residue field at the prime `p`. + OUTPUT: the residue field at the prime `p` EXAMPLES:: @@ -322,7 +320,7 @@ class ResidueFieldFactory(UniqueFactory): Residue field in abar of Fractional ideal (2*a^2 + 3*a - 10) """ if check: - if not is_Ideal(p): + if not isinstance(p, Ideal_generic): if isinstance(p, (int, Integer, Rational)): p = ZZ.ideal(p) elif isinstance(p, NumberFieldElement_base): @@ -339,7 +337,7 @@ class ResidueFieldFactory(UniqueFactory): raise ValueError("p must be an ideal or element of a number field or function field.") if not p.is_prime(): raise ValueError("p (%s) must be prime" % p) - if is_PolynomialRing(p.ring()): + if isinstance(p.ring(), PolynomialRing_general): if not p.ring().base_ring().is_finite(): raise ValueError("residue fields only supported for polynomial rings over finite fields") if not p.ring().base_ring().is_prime_field(): @@ -375,7 +373,7 @@ class ResidueFieldFactory(UniqueFactory): if pring is ZZ: return ResidueFiniteField_prime_modn(p, names, p.gen(), None, None, None) - if is_PolynomialRing(pring): + if isinstance(pring, PolynomialRing_general): K = pring.fraction_field() Kbase = pring.base_ring() f = p.gen() @@ -588,7 +586,6 @@ class ResidueField_generic(Field): Residue field of Integers modulo 17 sage: F(CyclotomicField(49)) Residue field in zbar of Fractional ideal (17) - """ return AlgebraicExtensionFunctor([self.polynomial()], [self.variable_name()], [None], residue=self.p), self.p.ring() @@ -683,7 +680,7 @@ class ResidueField_generic(Field): def _coerce_map_from_(self, R): """ - Returns ``True`` if there is a coercion map from ``R`` to ``self``. + Return ``True`` if there is a coercion map from ``R`` to ``self``. EXAMPLES:: @@ -716,7 +713,7 @@ class ResidueField_generic(Field): def __repr__(self): """ - Returns a string describing this residue field. + Return a string describing this residue field. EXAMPLES:: @@ -742,7 +739,7 @@ class ResidueField_generic(Field): def lift(self, x): """ - Returns a lift of ``x`` to the Order, returning a "polynomial" in the + Return a lift of ``x`` to the Order, returning a "polynomial" in the generator with coefficients between 0 and `p-1`. EXAMPLES:: @@ -822,7 +819,7 @@ class ResidueField_generic(Field): def lift_map(self): """ - Returns the standard map from this residue field up to the ring of + Return the standard map from this residue field up to the ring of integers lifting the canonical projection. EXAMPLES:: @@ -864,7 +861,7 @@ class ResidueField_generic(Field): def _richcmp_(self, x, op): """ - Compares two residue fields: they are equal iff the primes + Compare two residue fields: they are equal iff the primes defining them are equal and they have the same variable name. EXAMPLES:: @@ -925,7 +922,7 @@ cdef class ReductionMap(Map): A reduction map from a (subset) of a number field or function field to this residue class field. - It will be defined on those elements of the field with non-negative + It will be defined on those elements of the field with nonnegative valuation at the specified prime. EXAMPLES:: @@ -1063,7 +1060,7 @@ cdef class ReductionMap(Map): field. If ``x`` doesn't map because it has negative valuation, then a - ``ZeroDivisionError`` exception is raised. + :exc:`ZeroDivisionError` exception is raised. EXAMPLES:: @@ -1178,7 +1175,7 @@ cdef class ReductionMap(Map): def section(self): """ - Computes a section of the map, namely a map that lifts elements of the + Compute a section of the map, namely a map that lifts elements of the residue field to elements of the field. EXAMPLES:: @@ -1267,11 +1264,11 @@ cdef class ResidueFieldHomomorphism_global(RingHomomorphism): INPUT: - - ``k`` -- The residue field that is the codomain of this morphism + - ``k`` -- the residue field that is the codomain of this morphism - - ``p`` -- The prime ideal defining this residue field + - ``p`` -- the prime ideal defining this residue field - - ``im_gen`` -- The image of the generator of the number field + - ``im_gen`` -- the image of the generator of the number field EXAMPLES: @@ -1403,7 +1400,7 @@ cdef class ResidueFieldHomomorphism_global(RingHomomorphism): # No special code for residue fields of Z, since we just use the normal reduction map to GF(p) if self._K is ZZ: return self._F(x) - if is_PolynomialRing(self._K): + if isinstance(self._K, PolynomialRing_general): p = self._F.p.gen() if p.degree() == 1: return self._F((x % p)[0]) @@ -1414,7 +1411,7 @@ cdef class ResidueFieldHomomorphism_global(RingHomomorphism): def section(self): """ - Computes a section of the map, namely a map that lifts elements of + Compute a section of the map, namely a map that lifts elements of the residue field to elements of the ring of integers. EXAMPLES:: @@ -1461,7 +1458,7 @@ cdef class ResidueFieldHomomorphism_global(RingHomomorphism): def lift(self, x): """ - Returns a lift of ``x`` to the Order, returning a "polynomial" in + Return a lift of ``x`` to the Order, returning a "polynomial" in the generator with coefficients between 0 and `p-1`. EXAMPLES:: @@ -1661,7 +1658,7 @@ cdef class LiftingMap(Section): return self._K(self._K.ring_of_integers()(x)) else: return self._K(self._K.ring_of_integers()(x.polynomial().list())) - elif is_PolynomialRing(self._K): + elif isinstance(self._K, PolynomialRing_general): return self._K(x.polynomial().list()) # Else the lifting map is just x |--> to_order(x * PB) x = self._F(x) @@ -1730,7 +1727,7 @@ class ResidueFiniteField_prime_modn(ResidueField_generic, FiniteField_prime_modn INPUT: - - ``p`` -- A prime ideal of a number field + - ``p`` -- a prime ideal of a number field - ``name`` -- the name of the generator of this extension @@ -1780,7 +1777,7 @@ class ResidueFiniteField_prime_modn(ResidueField_generic, FiniteField_prime_modn INPUT: - - ``x`` -- something to cast in to ``self``. + - ``x`` -- something to cast in to ``self`` EXAMPLES:: diff --git a/src/sage/rings/finite_rings/residue_field_givaro.pyx b/src/sage/rings/finite_rings/residue_field_givaro.pyx index a00bc5138fd..84e78622760 100644 --- a/src/sage/rings/finite_rings/residue_field_givaro.pyx +++ b/src/sage/rings/finite_rings/residue_field_givaro.pyx @@ -71,7 +71,7 @@ class ResidueFiniteField_givaro(ResidueField_generic, FiniteField_givaro): - ``to_order`` -- the map from a lattice in that vector space to the maximal order - - ``PB`` -- a matrix used in defining the reduction and lifting maps. + - ``PB`` -- a matrix used in defining the reduction and lifting maps EXAMPLES:: @@ -104,7 +104,7 @@ class ResidueFiniteField_givaro(ResidueField_generic, FiniteField_givaro): """ INPUT: - - ``x`` -- Something to cast into ``self``. + - ``x`` -- something to cast into ``self`` EXAMPLES:: diff --git a/src/sage/rings/finite_rings/residue_field_ntl_gf2e.pyx b/src/sage/rings/finite_rings/residue_field_ntl_gf2e.pyx index 5071bc87137..eb0620e3ba1 100644 --- a/src/sage/rings/finite_rings/residue_field_ntl_gf2e.pyx +++ b/src/sage/rings/finite_rings/residue_field_ntl_gf2e.pyx @@ -110,7 +110,7 @@ class ResidueFiniteField_ntl_gf2e(ResidueField_generic, FiniteField_ntl_gf2e): """ INPUT: - - ``x`` -- Something to cast into ``self``. + - ``x`` -- something to cast into ``self`` EXAMPLES:: diff --git a/src/sage/rings/fraction_field.py b/src/sage/rings/fraction_field.py index 148aa1f6ee4..4e3e923c263 100644 --- a/src/sage/rings/fraction_field.py +++ b/src/sage/rings/fraction_field.py @@ -101,9 +101,9 @@ def FractionField(R, names=None): INPUT: - - ``R`` -- an integral domain + - ``R`` -- an integral domain - - ``names`` -- ignored + - ``names`` -- ignored EXAMPLES: @@ -178,7 +178,7 @@ def __init__(self, R, INPUT: - - ``R`` -- an integral domain + - ``R`` -- an integral domain EXAMPLES:: @@ -398,11 +398,9 @@ def _number_field_to_frac_of_ring_of_integers(self, x): INPUT: - - ``x`` -- Number field element + - ``x`` -- number field element - OUTPUT: - - - Element of ``self`` + OUTPUT: Element of ``self`` TESTS: @@ -446,7 +444,6 @@ def is_finite(self): sage: Frac(QQ['a','b','c']).is_finite() False - """ return self._R.is_finite() @@ -1049,7 +1046,6 @@ def _factor_univariate_polynomial(self, f): sage: f = x^3 + a sage: f.factor() (x + 2*a + 1)^3 - """ # The default implementation would try to convert this element to singular and factor there. # This fails silently over some base fields, see #23642, so we convert @@ -1070,7 +1066,6 @@ def function_field(self): .. SEEALSO:: :meth:`sage.rings.function_field.RationalFunctionField.field` - """ from sage.rings.function_field.constructor import FunctionField return FunctionField(self.base_ring(), names=self.variable_name()) @@ -1092,7 +1087,6 @@ def _coerce_map_from_(self, R): over Finite Field of size 5 sage: f(~L.gen()) 1/t - """ from sage.rings.function_field.function_field_rational import ( RationalFunctionField, @@ -1133,7 +1127,6 @@ class FractionFieldEmbedding(DefaultConvertMap_unique): True sage: R.is_subring(R.fraction_field()) True - """ def is_surjective(self): r""" @@ -1144,7 +1137,6 @@ def is_surjective(self): sage: R. = QQ[] sage: R.fraction_field().coerce_map_from(R).is_surjective() False - """ return self.domain().is_field() @@ -1160,7 +1152,6 @@ def is_injective(self): sage: R. = QQ[] sage: R.fraction_field().coerce_map_from(R).is_injective() True - """ return True @@ -1175,7 +1166,6 @@ def section(self): Section map: From: Fraction Field of Univariate Polynomial Ring in x over Rational Field To: Univariate Polynomial Ring in x over Rational Field - """ from sage.categories.homset import Hom from sage.categories.sets_with_partial_maps import SetsWithPartialMaps @@ -1197,7 +1187,6 @@ def _richcmp_(self, other, op): False sage: f == f True - """ if type(self) is not type(other): return NotImplemented @@ -1212,7 +1201,6 @@ def __hash__(self): sage: R. = QQ[] sage: hash(R.fraction_field().coerce_map_from(R)) == hash(R.fraction_field().coerce_map_from(R)) True - """ return hash((type(self), self.domain())) @@ -1236,7 +1224,6 @@ class FractionFieldEmbeddingSection(Section): sage: isinstance(f, FractionFieldEmbeddingSection) True sage: TestSuite(f).run() - """ def _call_(self, x, check=True): r""" @@ -1330,7 +1317,6 @@ def _richcmp_(self, other, op): False sage: f == f True - """ if type(self) is not type(other): return NotImplemented @@ -1345,6 +1331,5 @@ def __hash__(self): sage: R. = QQ[] sage: hash(R.fraction_field().coerce_map_from(R).section()) == hash(R.fraction_field().coerce_map_from(R).section()) True - """ return hash((type(self), self.codomain())) diff --git a/src/sage/rings/fraction_field_FpT.pyx b/src/sage/rings/fraction_field_FpT.pyx index b3ae363d9ae..5317c1551fb 100644 --- a/src/sage/rings/fraction_field_FpT.pyx +++ b/src/sage/rings/fraction_field_FpT.pyx @@ -115,9 +115,11 @@ cdef class FpTElement(FieldElement): """ INPUT: - - parent -- the Fraction field containing this element - - numer -- something that can be converted into the polynomial ring, giving the numerator - - denom -- something that can be converted into the polynomial ring, giving the numerator (default 1) + - ``parent`` -- the Fraction field containing this element + - ``numer`` -- something that can be converted into the polynomial + ring, giving the numerator + - ``denom`` -- something that can be converted into the polynomial + ring, giving the numerator (default: 1) EXAMPLES:: @@ -173,7 +175,8 @@ cdef class FpTElement(FieldElement): cdef FpTElement _new_c(self): """ - Creates a new FpTElement in the same field, leaving the value to be initialized. + Create a new FpTElement in the same field, leaving the value to be + initialized. """ cdef FpTElement x = FpTElement.__new__(FpTElement) x._parent = self._parent @@ -185,7 +188,8 @@ cdef class FpTElement(FieldElement): cdef FpTElement _copy_c(self): """ - Creates a new FpTElement in the same field, with the same value as self. + Create a new FpTElement in the same field, with the same value as + ``self``. """ cdef FpTElement x = FpTElement.__new__(FpTElement) x._parent = self._parent @@ -295,7 +299,7 @@ cdef class FpTElement(FieldElement): def valuation(self, v): """ - Return the valuation of self at `v`. + Return the valuation of ``self`` at `v`. EXAMPLES:: @@ -444,7 +448,7 @@ cdef class FpTElement(FieldElement): def __neg__(self): """ - Negates this element. + Negate this element. EXAMPLES:: @@ -768,12 +772,12 @@ cdef class FpTElement(FieldElement): INPUT: - - ``extend`` -- bool (default: ``True``); if True, return a - square root in an extension ring, if necessary. Otherwise, raise a - ValueError if the square is not in the base ring. + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the square is not in the base ring. - - ``all`` -- bool (default: ``False``); if True, return all - square roots of self, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of self, instead of just one EXAMPLES:: @@ -802,7 +806,7 @@ cdef class FpTElement(FieldElement): def __pow__(FpTElement self, Py_ssize_t e, dummy): r""" - Return the ``e``th power of this element. + Return the `e`-th power of this element. EXAMPLES:: @@ -886,11 +890,12 @@ cdef class FpT_iter: """ INPUT: - - parent -- The FpT that we're iterating over. + - ``parent`` -- the FpT that we're iterating over - - degree -- The maximum degree of the numerator and denominator of the elements over which we iterate. + - ``degree`` -- the maximum degree of the numerator and denominator of + the elements over which we iterate - - start -- (default 0) The element on which to start. + - ``start`` -- (default: 0) the element on which to start EXAMPLES:: @@ -1029,7 +1034,7 @@ cdef class FpT_iter: cdef class Polyring_FpT_coerce(RingHomomorphism): """ - This class represents the coercion map from GF(p)[t] to GF(p)(t) + This class represents the coercion map from GF(p)[t] to GF(p)(t). EXAMPLES:: @@ -1045,7 +1050,6 @@ cdef class Polyring_FpT_coerce(RingHomomorphism): TESTS:: TestSuite(f).run() - """ cdef long p @@ -1053,7 +1057,7 @@ cdef class Polyring_FpT_coerce(RingHomomorphism): """ INPUT: - - R -- An FpT + - ``R`` -- an FpT EXAMPLES:: @@ -1218,7 +1222,7 @@ cdef class Polyring_FpT_coerce(RingHomomorphism): cdef class FpT_Polyring_section(Section): """ - This class represents the section from GF(p)(t) back to GF(p)[t] + This class represents the section from GF(p)(t) back to GF(p)[t]. EXAMPLES:: @@ -1246,7 +1250,6 @@ cdef class FpT_Polyring_section(Section): TESTS:: sage: TestSuite(f).run(skip='_test_pickling') - """ cdef long p @@ -1254,7 +1257,7 @@ cdef class FpT_Polyring_section(Section): """ INPUT: - - f -- A Polyring_FpT_coerce homomorphism + - ``f`` -- a Polyring_FpT_coerce homomorphism EXAMPLES:: @@ -1347,7 +1350,7 @@ cdef class FpT_Polyring_section(Section): cdef class Fp_FpT_coerce(RingHomomorphism): """ - This class represents the coercion map from GF(p) to GF(p)(t) + This class represents the coercion map from GF(p) to GF(p)(t). EXAMPLES:: @@ -1363,7 +1366,6 @@ cdef class Fp_FpT_coerce(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ cdef long p @@ -1371,7 +1373,7 @@ cdef class Fp_FpT_coerce(RingHomomorphism): """ INPUT: - - R -- An FpT + - ``R`` -- an FpT EXAMPLES:: @@ -1520,7 +1522,7 @@ cdef class Fp_FpT_coerce(RingHomomorphism): cdef class FpT_Fp_section(Section): """ - This class represents the section from GF(p)(t) back to GF(p)[t] + This class represents the section from GF(p)(t) back to GF(p)[t]. EXAMPLES:: @@ -1548,8 +1550,6 @@ cdef class FpT_Fp_section(Section): TESTS:: sage: TestSuite(f).run(skip='_test_pickling') - - """ cdef long p @@ -1557,7 +1557,7 @@ cdef class FpT_Fp_section(Section): """ INPUT: - - f -- An Fp_FpT_coerce homomorphism + - ``f`` -- an ``Fp_FpT_coerce`` homomorphism EXAMPLES:: @@ -1669,7 +1669,7 @@ cdef class FpT_Fp_section(Section): cdef class ZZ_FpT_coerce(RingHomomorphism): """ - This class represents the coercion map from ZZ to GF(p)(t) + This class represents the coercion map from ZZ to GF(p)(t). EXAMPLES:: @@ -1685,7 +1685,6 @@ cdef class ZZ_FpT_coerce(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ cdef long p @@ -1693,7 +1692,7 @@ cdef class ZZ_FpT_coerce(RingHomomorphism): """ INPUT: - - R -- An FpT + - ``R`` -- an FpT EXAMPLES:: @@ -1909,7 +1908,7 @@ cdef inline void nmod_poly_inc(nmod_poly_t poly, bint monic) noexcept: """ Set poly to the "next" polynomial: this is just counting in base p. - If monic is True then will only iterate through monic polynomials. + If monic is ``True`` then will only iterate through monic polynomials. """ cdef long n cdef long a diff --git a/src/sage/rings/fraction_field_element.pyx b/src/sage/rings/fraction_field_element.pyx index 38abe60b094..3d14ab66134 100644 --- a/src/sage/rings/fraction_field_element.pyx +++ b/src/sage/rings/fraction_field_element.pyx @@ -113,7 +113,6 @@ cdef class FractionFieldElement(FieldElement): (x + 1)/(x^2 + x + 1) sage: K(355/113) 355/113 - """ FieldElement.__init__(self, parent) if coerce: @@ -274,15 +273,15 @@ cdef class FractionFieldElement(FieldElement): INPUT: - - ``root`` -- whether or not to also return a square - root (default: ``False``) + - ``root`` -- whether or not to also return a square + root (default: ``False``) OUTPUT: - - ``bool`` -- whether or not a square + - boolean; whether or not a square - - ``object`` -- (optional) an actual square root if - found, and None otherwise. + - object (optional); an actual square root if found, and ``None`` + otherwise EXAMPLES:: @@ -599,9 +598,7 @@ cdef class FractionFieldElement(FieldElement): - ``right`` -- ``ModuleElement`` to add to ``self`` - OUTPUT: - - - Sum of ``self`` and ``right`` + OUTPUT: sum of ``self`` and ``right`` EXAMPLES:: @@ -678,15 +675,13 @@ cdef class FractionFieldElement(FieldElement): cpdef _mul_(self, right): """ - Computes the product of ``self`` and ``right``. + Compute the product of ``self`` and ``right``. INPUT: - ``right`` -- ``RingElement`` to multiply with ``self`` - OUTPUT: - - - Product of ``self`` and ``right`` + OUTPUT: product of ``self`` and ``right`` EXAMPLES:: @@ -744,15 +739,13 @@ cdef class FractionFieldElement(FieldElement): cpdef _div_(self, right): """ - Computes the quotient of ``self`` and ``right``. + Compute the quotient of ``self`` and ``right``. INPUT: - ``right`` -- ``RingElement`` that is the divisor - OUTPUT: - - Quotient of ``self`` and ``right`` + OUTPUT: quotient of ``self`` and ``right`` EXAMPLES:: @@ -827,7 +820,7 @@ cdef class FractionFieldElement(FieldElement): def _conversion(self, R): r""" - Generic conversion + Generic conversion. TESTS:: @@ -890,7 +883,7 @@ cdef class FractionFieldElement(FieldElement): def __pow__(self, right, dummy): r""" - Returns self raised to the `right^{th}` power. + Return ``self`` raised to the ``right``-th power. Note that we need to check whether or not right is negative so we don't set ``_numerator`` or ``_denominator`` to an element of the @@ -1183,7 +1176,7 @@ cdef class FractionFieldElement(FieldElement): def specialization(self, D=None, phi=None): """ - Returns the specialization of a fraction element of a polynomial ring + Return the specialization of a fraction element of a polynomial ring. """ numerator = self.numerator().specialization(D, phi) denominator = self.denominator().specialization(D, phi) @@ -1224,7 +1217,7 @@ cdef class FractionFieldElement_1poly_field(FractionFieldElement): def is_integral(self): """ - Returns whether this element is actually a polynomial. + Return whether this element is actually a polynomial. EXAMPLES:: @@ -1244,7 +1237,7 @@ cdef class FractionFieldElement_1poly_field(FractionFieldElement): def support(self): """ - Returns a sorted list of primes dividing either the numerator or + Return a sorted list of primes dividing either the numerator or denominator of this element. EXAMPLES:: @@ -1261,7 +1254,7 @@ cdef class FractionFieldElement_1poly_field(FractionFieldElement): cpdef reduce(self): """ - Pick a normalized representation of self. + Pick a normalized representation of ``self``. In particular, for any a == b, after normalization they will have the same numerator and denominator. diff --git a/src/sage/rings/function_field/constructor.py b/src/sage/rings/function_field/constructor.py index 8eb407d1552..a316c384bd1 100644 --- a/src/sage/rings/function_field/constructor.py +++ b/src/sage/rings/function_field/constructor.py @@ -167,7 +167,6 @@ def create_key(self,polynomial,names): sage: N. = K.extension(z - 1) sage: M is N False - """ if names is None: names = polynomial.variable_name() diff --git a/src/sage/rings/function_field/derivations_polymod.py b/src/sage/rings/function_field/derivations_polymod.py index 2e0fe91a968..952d5813dd6 100644 --- a/src/sage/rings/function_field/derivations_polymod.py +++ b/src/sage/rings/function_field/derivations_polymod.py @@ -229,7 +229,6 @@ def _call_(self, x): 1 sage: d(y^2) 0 - """ if x.is_zero(): return self.codomain().zero() diff --git a/src/sage/rings/function_field/differential.py b/src/sage/rings/function_field/differential.py index 4442a63bd22..8f841180532 100644 --- a/src/sage/rings/function_field/differential.py +++ b/src/sage/rings/function_field/differential.py @@ -247,7 +247,7 @@ def _add_(self, other): def _div_(self, other): """ - Return the quotient of ``self`` and ``other`` + Return the quotient of ``self`` and ``other``. INPUT: @@ -427,9 +427,7 @@ def residue(self, place): - ``place`` -- a place of the function field - OUTPUT: - - - an element of the residue field of the place + OUTPUT: an element of the residue field of the place EXAMPLES: @@ -472,7 +470,6 @@ def residue(self, place): sage: d = w.divisor() sage: sum([QQ(w.residue(p)) for p in d.support()]) 0 - """ R,fr_R,to_R = place._residue_field() diff --git a/src/sage/rings/function_field/divisor.py b/src/sage/rings/function_field/divisor.py index 30d99d920d4..13247abe3b0 100644 --- a/src/sage/rings/function_field/divisor.py +++ b/src/sage/rings/function_field/divisor.py @@ -132,7 +132,7 @@ class FunctionFieldDivisor(ModuleElement): - ``parent`` -- divisor group - - ``data`` -- dict of place and multiplicity pairs + - ``data`` -- dictionary of place and multiplicity pairs EXAMPLES:: @@ -467,7 +467,7 @@ def multiplicity(self, place): def is_effective(self): """ - Return ``True`` if this divisor has non-negative multiplicity at all + Return ``True`` if this divisor has nonnegative multiplicity at all places. EXAMPLES:: diff --git a/src/sage/rings/function_field/drinfeld_modules/action.py b/src/sage/rings/function_field/drinfeld_modules/action.py index 6fca6225d60..4962162424e 100644 --- a/src/sage/rings/function_field/drinfeld_modules/action.py +++ b/src/sage/rings/function_field/drinfeld_modules/action.py @@ -85,7 +85,9 @@ def __init__(self, drinfeld_module): """ Initialize ``self``. - INPUT: the Drinfeld module + INPUT: + + - ``drinfeld_module`` -- the Drinfeld module TESTS:: @@ -142,7 +144,7 @@ def _latex_(self): r""" Return a LaTeX representation of the action. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -162,7 +164,7 @@ def _repr_(self): r""" Return a string representation of the action. - OUTPUT: a string + OUTPUT: string EXAMPLES:: diff --git a/src/sage/rings/function_field/drinfeld_modules/charzero_drinfeld_module.py b/src/sage/rings/function_field/drinfeld_modules/charzero_drinfeld_module.py index 34644aef4a4..d183848f296 100644 --- a/src/sage/rings/function_field/drinfeld_modules/charzero_drinfeld_module.py +++ b/src/sage/rings/function_field/drinfeld_modules/charzero_drinfeld_module.py @@ -121,7 +121,7 @@ def _compute_coefficient_exp(self, k): INPUT: - - ``k`` (integer) -- the index of the coefficient + - ``k`` -- integer; the index of the coefficient TESTS:: @@ -157,12 +157,10 @@ def exponential(self, name='z'): INPUT: - - ``name`` (string, default: ``'z'``) -- the name of the - generator of the lazy power series ring. + - ``name`` -- string (default: ``'z'``); the name of the + generator of the lazy power series ring - OUTPUT: - - A lazy power series over the base field. + OUTPUT: a lazy power series over the base field EXAMPLES:: @@ -276,12 +274,10 @@ def logarithm(self, name='z'): INPUT: - - ``name`` (string, default: ``'z'``) -- the name of the - generator of the lazy power series ring. - - OUTPUT: + - ``name`` -- string (default: ``'z'``); the name of the + generator of the lazy power series ring - A lazy power series over the base field. + OUTPUT: a lazy power series over the base field EXAMPLES:: @@ -319,7 +315,6 @@ def logarithm(self, name='z'): True sage: log[2**3] == -1/((T**q - T)*(T**(q**2) - T)*(T**(q**3) - T)) # expected value True - """ L = LazyPowerSeriesRing(self._base, name) zero = self._base.zero() @@ -358,7 +353,6 @@ def _compute_goss_polynomial(self, n, q, poly_ring, X): X^12 sage: phi._compute_goss_polynomial(9, 2^2, poly_ring, X) X^9 + (1/(T^3 + T^2 + T))*X^6 + (1/(T^6 + T^4 + T^2))*X^3 - """ # Trivial cases if n.is_zero(): @@ -386,14 +380,12 @@ def goss_polynomial(self, n, var='X'): INPUT: - - ``n`` (integer) -- the index of the Goss polynomial - - - ``var`` (str, default: ``'X'``) -- the name of polynomial - variable. + - ``n`` -- integer; the index of the Goss polynomial - OUTPUT: + - ``var``-- string (default: ``'X'``); the name of polynomial + variable - - a univariate polynomial in ``var`` over the base `A`-field. + OUTPUT: a univariate polynomial in ``var`` over the base `A`-field EXAMPLES:: diff --git a/src/sage/rings/function_field/drinfeld_modules/drinfeld_module.py b/src/sage/rings/function_field/drinfeld_modules/drinfeld_module.py index eb9eba37391..d225820ab18 100644 --- a/src/sage/rings/function_field/drinfeld_modules/drinfeld_module.py +++ b/src/sage/rings/function_field/drinfeld_modules/drinfeld_module.py @@ -125,7 +125,7 @@ class DrinfeldModule(Parent, UniqueRepresentation): - ``gen`` -- the generator of the Drinfeld module; as a list of coefficients or an Ore polynomial - - ``name`` (default: ``'t'``) -- the name of the Ore polynomial ring + - ``name`` -- (default: ``'t'``) the name of the Ore polynomial ring generator .. RUBRIC:: Construction @@ -533,12 +533,10 @@ def __classcall_private__(cls, function_ring, gen, name='t'): - ``gen`` -- the generator of the Drinfeld module; as a list of coefficients or an Ore polynomial - - ``name`` (default: ``'t'``) -- the name of the Ore polynomial + - ``name`` -- (default: ``'t'``) the name of the Ore polynomial ring gen - OUTPUT: - - A DrinfeldModule or DrinfeldModule_finite. + OUTPUT: a DrinfeldModule or DrinfeldModule_finite TESTS:: @@ -645,7 +643,7 @@ def __init__(self, gen, category): - ``gen`` -- the generator of the Drinfeld module; as a list of coefficients or an Ore polynomial - - ``name`` (default: ``'t'``) -- the name of the Ore polynomial + - ``name`` -- (default: ``'t'``) the name of the Ore polynomial ring gen TESTS:: @@ -893,15 +891,15 @@ def basic_j_invariant_parameters(self, coeff_indices=None, nonzero=False): INPUT: - - ``coeff_indices`` (list or tuple, or NoneType; default: - ``None``) -- indices of the Drinfeld module generator + - ``coeff_indices`` -- list or tuple, or NoneType (default: + ``None``); indices of the Drinfeld module generator coefficients to be considered in the computation. If the parameter is ``None`` (default), all the coefficients are involved. - - ``nonzero`` (boolean, default: ``False``) -- if this flag + - ``nonzero``-- boolean (default: ``False``); if this flag is set to ``True``, then only the parameters for which the - corresponding basic `j`-invariant is nonzero are returned. + corresponding basic `j`-invariant is nonzero are returned .. WARNING:: @@ -1070,9 +1068,9 @@ def basic_j_invariants(self, nonzero=False): INPUT: - - ``nonzero`` (boolean, default: ``False``) -- if this flag + - ``nonzero``-- boolean (default: ``False``); if this flag is set to ``True``, then only the parameters for which the - corresponding basic `j`-invariant is nonzero are returned. + corresponding basic `j`-invariant is nonzero are returned .. WARNING:: @@ -1124,7 +1122,7 @@ def coefficient(self, n): INPUT: - - ``n`` -- a nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: an element in the base codomain @@ -1163,7 +1161,7 @@ def coefficients(self, sparse=True): INPUT: - - ``sparse`` -- a boolean + - ``sparse`` -- boolean EXAMPLES:: @@ -1215,7 +1213,7 @@ def gen(self): def height(self): r""" Return the height of the Drinfeld module if the function field - characteristic is a prime ideal; raise ValueError otherwise. + characteristic is a prime ideal; raise :exc:`ValueError` otherwise. The height of a Drinfeld module is defined when the function field characteristic is a prime ideal. In our case, this ideal @@ -1273,7 +1271,6 @@ def height(self): Traceback (most recent call last): ... NotImplementedError: height not implemented in this case - """ try: if self.characteristic().is_zero(): @@ -1294,7 +1291,7 @@ def is_isomorphic(self, other, absolutely=False): - ``absolutely`` -- a boolean (default: ``False``); if ``False``, check the existence of an isomorphism defined on the base - field; if ``True``, check over an algebraic closure. + field. If ``True``, check over an algebraic closure. EXAMPLES:: @@ -1523,8 +1520,8 @@ def j_invariant(self, parameter=None, check=True): INPUT: - - ``parameter`` (tuple or list, integer or NoneType; default: - ``None``) -- the `j`-invariant parameter: + - ``parameter`` -- tuple or list, integer or NoneType (default: + ``None``); the `j`-invariant parameter: - If ``parameter`` is a list or a tuple, then it must be of the form: @@ -1541,11 +1538,11 @@ def j_invariant(self, parameter=None, check=True): `j`-invariant, that is the `j`-invariant for the parameter `((1,), (q+1, 1))`. - - ``check`` (bool, default: ``True``) -- if this flag is set to + - ``check`` -- boolean (default: ``True``); if this flag is set to ``False`` then the code will not check if the given parameter is valid and satisfy the weight-0 condition. - OUTPUT: the `j`-invariant of ``self`` for the given parameter. + OUTPUT: the `j`-invariant of ``self`` for the given parameter EXAMPLES:: @@ -1734,13 +1731,13 @@ def jk_invariants(self): `1 \leqslant k \leqslant r-1` and the values are the corresponding `j_k`-invariants - Recall that the `j_k`-invariant of self is defined by: + Recall that the `j_k`-invariant of ``self`` is defined by: .. MATH:: j_k := \frac{g_k^{(q^r - 1)/(\mathrm{gcd}(k, r) - 1)}}{g_r^{(q^k - 1)/(\mathrm{gcd}(k, r) - 1)}} - where `g_i` is the `i`-th coefficient of the generator of self. + where `g_i` is the `i`-th coefficient of the generator of ``self``. EXAMPLES:: @@ -1823,7 +1820,7 @@ def rank(self): In our case, the rank is the degree of the generator. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -2020,7 +2017,6 @@ def hom(self, x, codomain=None): Traceback (most recent call last): ... ValueError: Ore polynomial does not define a morphism - """ # When `x` is in the function ring (or something that coerces to it): if self.function_ring().has_coerce_map_from(x.parent()): @@ -2066,7 +2062,6 @@ def scalar_multiplication(self, x): sage: phi.hom(T^2 + 1) Endomorphism of Drinfeld module defined by T |--> z*t^3 + t^2 + z Defn: z^2*t^6 + (3*z^2 + z + 1)*t^5 + t^4 + 2*z^2*t^3 + (3*z^2 + z + 1)*t^2 + z^2 + 1 - """ if not self.function_ring().has_coerce_map_from(x.parent()): raise ValueError("%s is not element of the function ring" % x) diff --git a/src/sage/rings/function_field/drinfeld_modules/finite_drinfeld_module.py b/src/sage/rings/function_field/drinfeld_modules/finite_drinfeld_module.py index 470dfc495d7..15809061112 100644 --- a/src/sage/rings/function_field/drinfeld_modules/finite_drinfeld_module.py +++ b/src/sage/rings/function_field/drinfeld_modules/finite_drinfeld_module.py @@ -125,7 +125,7 @@ class DrinfeldModule_finite(DrinfeldModule): def __init__(self, gen, category): """ - Initialize `self`. + Initialize ``self``. Validity of the input is checked in `__classcall_private__`. The `__init__` just saves attributes. @@ -138,7 +138,7 @@ def __init__(self, gen, category): - ``gen`` -- the generator of the Drinfeld module as a list of coefficients or an Ore polynomial - - ``name`` (default: `'t'`) -- the name of the Ore polynomial + - ``name`` -- (default: ``'t'``) the name of the Ore polynomial ring gen TESTS:: @@ -290,8 +290,8 @@ def frobenius_charpoly(self, var='X', algorithm='crystalline'): INPUT: - - ``var`` (default: ``'X'``) -- the name of the second variable - - ``algorithm`` (default: ``'crystalline'``) -- the algorithm + - ``var`` -- (default: ``'X'``) the name of the second variable + - ``algorithm`` -- (default: ``'crystalline'``) the algorithm used to compute the characteristic polynomial EXAMPLES:: @@ -336,11 +336,11 @@ def frobenius_charpoly(self, var='X', algorithm='crystalline'): The available options for 'algorithm' are: - - ``'crystalline'`` -- Computes the characteristic polynomial of the + - ``'crystalline'`` -- computes the characteristic polynomial of the Frobenius endomorphism on the crystalline cohomology of a Drinfeld module. - - ``'motive'`` -- Based on computing the characteristic polynomial of + - ``'motive'`` -- based on computing the characteristic polynomial of the Frobenius endomorphism on the motive of a Drinfeld module. This instantiates the Frobenius as a morphism object and calls its ``'characteristic_polynomial'`` method. @@ -639,7 +639,6 @@ def invert(self, ore_pol): Traceback (most recent call last): ... TypeError: input must be an Ore polynomial - """ deg = ore_pol.degree() r = self.rank() @@ -763,7 +762,6 @@ def is_supersingular(self): False sage: psi.is_supersingular() False - """ return self.height() == self.rank() @@ -788,6 +786,5 @@ def is_ordinary(self): sage: phi = DrinfeldModule(A, [1, z6, 0, z6]) sage: phi.is_ordinary() True - """ return self.height() == 1 diff --git a/src/sage/rings/function_field/drinfeld_modules/homset.py b/src/sage/rings/function_field/drinfeld_modules/homset.py index d50e943686b..41a79e7fe6a 100644 --- a/src/sage/rings/function_field/drinfeld_modules/homset.py +++ b/src/sage/rings/function_field/drinfeld_modules/homset.py @@ -64,7 +64,6 @@ class DrinfeldModuleMorphismAction(Action): From: Drinfeld module defined by T |--> z*t^2 + t + z To: Drinfeld module defined by T |--> (2*z^2 + 4*z + 4)*t^2 + (z^2 + 4*z + 3)*t + z Defn: t + 2 - """ def __init__(self, A, H, is_left, op): r""" @@ -76,7 +75,7 @@ def __init__(self, A, H, is_left, op): - ``H`` -- a homset between Drinfeld modules - - ``is_left`` -- a boolean + - ``is_left`` -- boolean - ``op`` -- an operator @@ -95,7 +94,6 @@ def __init__(self, A, H, is_left, op): sage: right_action = DrinfeldModuleMorphismAction(A, H, False, operator.mul) sage: TestSuite(right_action).run(skip='_test_pickling') - """ Action.__init__(self, A, H, is_left, op) if is_left: @@ -120,7 +118,6 @@ def _act_(self, a, f): From: Drinfeld module defined by T |--> z*t^3 + t^2 + z To: Drinfeld module defined by T |--> (2*z^2 + 4*z + 4)*t^3 + (3*z^2 + 2*z + 2)*t^2 + (2*z^2 + 3*z + 4)*t + z Defn: (2*z^2 + 4*z + 4)*t^4 + (z + 1)*t^3 + t^2 + (2*z^2 + 4*z + 4)*t + z - """ u = f.ore_polynomial() if self._is_left: @@ -234,7 +231,6 @@ class DrinfeldModuleHomset(Homset): False sage: frobenius_endomorphism in H False - """ Element = DrinfeldModuleMorphism @@ -248,10 +244,11 @@ def __init__(self, X, Y, category=None, check=True): - ``Y`` -- the codomain of the homset - - ``category`` (default: ``None``) -- the Drinfeld modules category of + - ``category`` -- (default: ``None``) the Drinfeld modules category of the domain and codomain - - ``check`` (default: ``True``) -- check the validity of the category + - ``check`` -- boolean (default: ``True``); check the validity of the + category TESTS:: diff --git a/src/sage/rings/function_field/drinfeld_modules/morphism.py b/src/sage/rings/function_field/drinfeld_modules/morphism.py index c7e1f6c3bfe..82c1d7a0da1 100644 --- a/src/sage/rings/function_field/drinfeld_modules/morphism.py +++ b/src/sage/rings/function_field/drinfeld_modules/morphism.py @@ -122,7 +122,6 @@ class DrinfeldModuleMorphism(Morphism, UniqueRepresentation, Defn: t + z^5 + z^3 + z + 1 sage: DrinfeldModuleMorphism(Hom(phi, psi), ore_pol) is morphism True - """ @staticmethod def __classcall_private__(cls, parent, x): @@ -459,7 +458,6 @@ def __add__(self, other): sage: F + T Endomorphism of Drinfeld module defined by T |--> z*t^3 + t^2 + z Defn: (z + 1)*t^3 + t^2 + z - """ return self.parent()(self.ore_polynomial() + other.ore_polynomial()) @@ -480,7 +478,6 @@ def _composition_(self, other, H): sage: f * f # indirect doctest Endomorphism of Drinfeld module defined by T |--> z^2*t^3 + z*t^2 + t + z Defn: t^6 - """ return H(self.ore_polynomial() * other.ore_polynomial()) @@ -525,7 +522,6 @@ def inverse(self): Traceback (most recent call last): ... ZeroDivisionError: this morphism is not invertible - """ return self.__invert__() @@ -547,7 +543,6 @@ def __invert__(self): True sage: (g*f).is_identity() True - """ if not self.is_isomorphism(): raise ZeroDivisionError("this morphism is not invertible") @@ -573,7 +568,6 @@ def _motive_matrix(self): sage: f._motive_matrix() [ T + 3 + z 3 + 3*z + 2*z^2] [(1 + z + z^2)*T + 3 + 2*z - z^2 T + 2 - z + 2*z^2] - """ phi = self.domain() phiT = phi.gen() @@ -614,10 +608,10 @@ def norm(self, ideal=True): INPUT: - - ``ideal`` -- a boolean (default: ``True``); if ``True``, - return the norm as an ideal in the function ring of the Drinfeld - modules; if ``False``, return the norm as an element in this - function ring (only relevant for endomorphisms) + - ``ideal`` -- boolean (default: ``True``); if ``True``, return the + norm as an ideal in the function ring of the Drinfeld modules; if + ``False``, return the norm as an element in this function ring (only + relevant for endomorphisms) EXAMPLES:: @@ -660,7 +654,6 @@ def norm(self, ideal=True): Traceback (most recent call last): ... ValueError: norm is defined as an actual element only for endomorphisms - """ nu = self._motive_matrix().det() # We cast to A @@ -720,7 +713,6 @@ def dual_isogeny(self): Traceback (most recent call last): ... ValueError: the dual isogeny of the zero morphism is not defined - """ if not self.is_isogeny(): raise ValueError("the dual isogeny of the zero morphism is not defined") @@ -736,7 +728,7 @@ def characteristic_polynomial(self, var='X'): INPUT: - - ``var`` -- a string (default: ``X``), the name of the + - ``var`` -- string (default: ``X``), the name of the variable of the characteristic polynomial EXAMPLES:: @@ -772,7 +764,6 @@ def characteristic_polynomial(self, var='X'): Traceback (most recent call last): ... ValueError: characteristic polynomial is only defined for endomorphisms - """ if self.domain() is not self.codomain(): raise ValueError("characteristic polynomial is only defined for endomorphisms") @@ -788,7 +779,7 @@ def charpoly(self, var='X'): INPUT: - - ``var`` -- a string (default: ``X``), the name of the + - ``var`` -- string (default: ``'X'``); the name of the variable of the characteristic polynomial EXAMPLES:: @@ -822,6 +813,5 @@ def charpoly(self, var='X'): sage: f.charpoly(var='Y') Y^3 + (T + 1)*Y^2 + (2*T + 3)*Y + 2*T^3 + T + 1 - """ return self.characteristic_polynomial(var) diff --git a/src/sage/rings/function_field/element.pyx b/src/sage/rings/function_field/element.pyx index 5e8254e8294..093325f249c 100644 --- a/src/sage/rings/function_field/element.pyx +++ b/src/sage/rings/function_field/element.pyx @@ -146,7 +146,6 @@ cdef class FunctionFieldElement(FieldElement): Traceback (most recent call last): ... NotImplementedError: PARI does not support general function field elements. - """ raise NotImplementedError("PARI does not support general function field elements.") @@ -172,8 +171,8 @@ cdef class FunctionFieldElement(FieldElement): INPUT: - - ``base`` -- a function field (default: ``None``), if ``None``, then - the matrix is formed over the base field of this function field. + - ``base`` -- a function field (default: ``None``); if ``None``, then + the matrix is formed over the base field of this function field EXAMPLES: @@ -641,8 +640,8 @@ cdef class FunctionFieldElement(FieldElement): OUTPUT: If the element is in the valuation ring at the place, then an element - in the residue field at the place is returned. Otherwise, ``ValueError`` - is raised. + in the residue field at the place is returned. Otherwise, a + :exc:`ValueError` is raised. EXAMPLES:: @@ -683,7 +682,7 @@ cdef class FunctionFieldElement(FieldElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: @@ -709,7 +708,7 @@ cdef class FunctionFieldElement(FieldElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: diff --git a/src/sage/rings/function_field/element_polymod.pyx b/src/sage/rings/function_field/element_polymod.pyx index 55e887ea491..2d92da20bfe 100644 --- a/src/sage/rings/function_field/element_polymod.pyx +++ b/src/sage/rings/function_field/element_polymod.pyx @@ -114,7 +114,7 @@ cdef class FunctionFieldElement_polymod(FunctionFieldElement): cpdef _richcmp_(self, other, int op): """ - Do rich comparison with the other element with respect to ``op`` + Do rich comparison with the other element with respect to ``op``. EXAMPLES:: @@ -257,7 +257,7 @@ cdef class FunctionFieldElement_polymod(FunctionFieldElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: @@ -293,7 +293,6 @@ cdef class FunctionFieldElement_polymod(FunctionFieldElement): x sage: L(x^9).nth_root(-27)^-27 x^9 - """ if n == 1: return self @@ -323,7 +322,7 @@ cdef class FunctionFieldElement_polymod(FunctionFieldElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer ALGORITHM: @@ -345,7 +344,6 @@ cdef class FunctionFieldElement_polymod(FunctionFieldElement): False sage: L(x).is_nth_power(2) True - """ if n == 0: return self.is_one() diff --git a/src/sage/rings/function_field/element_rational.pyx b/src/sage/rings/function_field/element_rational.pyx index 5ad0d81341d..19a63d9ef90 100644 --- a/src/sage/rings/function_field/element_rational.pyx +++ b/src/sage/rings/function_field/element_rational.pyx @@ -61,7 +61,6 @@ cdef class FunctionFieldElement_rational(FunctionFieldElement): sage: K. = FunctionField(QQ) sage: ((a+1)/(a-1)).__pari__() # needs sage.libs.pari (a + 1)/(a - 1) - """ return self.element().__pari__() @@ -146,7 +145,7 @@ cdef class FunctionFieldElement_rational(FunctionFieldElement): cpdef _richcmp_(self, other, int op): """ - Compare the element with the other element with respect to ``op`` + Compare the element with the other element with respect to ``op``. INPUT: @@ -213,7 +212,7 @@ cdef class FunctionFieldElement_rational(FunctionFieldElement): cpdef _mul_(self, right): """ - Multiply the element with the other element + Multiply the element with the other element. INPUT: @@ -231,7 +230,7 @@ cdef class FunctionFieldElement_rational(FunctionFieldElement): cpdef _div_(self, right): """ - Divide the element with the other element + Divide the element with the other element. INPUT: @@ -367,7 +366,7 @@ cdef class FunctionFieldElement_rational(FunctionFieldElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: @@ -419,7 +418,7 @@ cdef class FunctionFieldElement_rational(FunctionFieldElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: diff --git a/src/sage/rings/function_field/extensions.py b/src/sage/rings/function_field/extensions.py index e65532db39e..94e810a9f87 100644 --- a/src/sage/rings/function_field/extensions.py +++ b/src/sage/rings/function_field/extensions.py @@ -82,7 +82,6 @@ class ConstantFieldExtension(FunctionFieldExtension): - ``F`` -- a function field whose constant field is `k` - ``k_ext`` -- an extension of `k` - """ def __init__(self, F, k_ext): """ diff --git a/src/sage/rings/function_field/function_field.py b/src/sage/rings/function_field/function_field.py index 315f58cdc39..7c633aba808 100644 --- a/src/sage/rings/function_field/function_field.py +++ b/src/sage/rings/function_field/function_field.py @@ -438,9 +438,7 @@ def extension(self, f, names=None): - ``names`` -- string or tuple of length 1 that names the variable `y` - OUTPUT: - - - a function field + OUTPUT: a function field EXAMPLES:: @@ -475,9 +473,7 @@ def order_with_basis(self, basis, check=True): basis is really linearly independent and that the module it spans is closed under multiplication, and contains the identity element. - OUTPUT: - - - an order in the function field + OUTPUT: an order in the function field EXAMPLES:: @@ -800,17 +796,15 @@ def _convert_map_from_(self, R): def _intermediate_fields(self, base): """ - Return the fields which lie in between base and the function field in the - tower of function fields. + Return the fields which lie in between base and the function field in + the tower of function fields. INPUT: - ``base`` -- function field, either this field or a field from which this field has been created as an extension - OUTPUT: - - - a list of fields; the first entry is this field, the last entry is ``base`` + OUTPUT: list of fields; the first entry is this field, the last entry is ``base`` EXAMPLES:: @@ -999,7 +993,6 @@ def valuation(self, prime): sage: v = L.valuation(x); v # needs sage.rings.function_field (x)-adic valuation - """ from sage.rings.function_field.valuation import FunctionFieldValuation return FunctionFieldValuation(self, prime) @@ -1235,7 +1228,7 @@ def hilbert_symbol(self, a, b, P): INPUT: - - ``a`` and ``b`` -- elements of this function field + - ``a``, ``b`` -- elements of this function field - ``P`` -- a place of this function field diff --git a/src/sage/rings/function_field/function_field_polymod.py b/src/sage/rings/function_field/function_field_polymod.py index fd8c975e682..9a34fe97e3e 100644 --- a/src/sage/rings/function_field/function_field_polymod.py +++ b/src/sage/rings/function_field/function_field_polymod.py @@ -247,8 +247,7 @@ def _to_base_field(self, f): INPUT: - - ``f`` -- element of the function field which lies in the base - field. + - ``f`` -- element of the function field which lies in the base field EXAMPLES:: @@ -323,10 +322,10 @@ def monic_integral_model(self, names=None): INPUT: - - ``names`` -- a string or a tuple of up to two strings (default: - ``None``), the name of the generator of the field, and the name of - the generator of the underlying rational function field (if a tuple); - if not given, then the names are chosen automatically. + - ``names`` -- string or tuple of up to two strings (default: + ``None``); the name of the generator of the field, and the name of + the generator of the underlying rational function field (if a tuple). + If not given, then the names are chosen automatically. OUTPUT: @@ -410,7 +409,6 @@ def monic_integral_model(self, names=None): To: Function field in yy defined by yy^2 - xx Defn: y |--> yy x |--> xx) - """ if names: if not isinstance(names, tuple): @@ -528,7 +526,7 @@ def degree(self, base=None): INPUT: - ``base`` -- a function field (default: ``None``), a function field - from which this field has been constructed as a finite extension. + from which this field has been constructed as a finite extension EXAMPLES:: @@ -554,7 +552,6 @@ def degree(self, base=None): Traceback (most recent call last): ... ValueError: base must be the rational function field itself - """ if base is None: base = self.base_field() @@ -659,7 +656,6 @@ def is_separable(self, base=None): sage: L. = K.extension(y^5 - 1) sage: L.is_separable() False - """ if base is None: base = self.base_field() @@ -701,10 +697,10 @@ def free_module(self, base=None, basis=None, map=True): space is over this subfield `R`, which defaults to the base field of this function field. - - ``basis`` -- a basis for this field over the base. + - ``basis`` -- a basis for this field over the base - - ``maps`` -- boolean (default ``True``), whether to return - `R`-linear maps to and from `V`. + - ``maps`` -- boolean (default: ``True``); whether to return + `R`-linear maps to and from `V` OUTPUT: @@ -785,7 +781,6 @@ def free_module(self, base=None, basis=None, map=True): Isomorphism: From: Function field in z defined by z^2 - y To: Vector space of dimension 10 over Rational function field in x over Rational Field) - """ if basis is not None: raise NotImplementedError @@ -891,7 +886,7 @@ def hom(self, im_gens, base_morphism=None): INPUT: - ``im_gens`` -- list of images of the generators of the function field - and of successive base rings. + and of successive base rings - ``base_morphism`` -- homomorphism of the base ring, after the ``im_gens`` are used. Thus if ``im_gens`` has length 2, then @@ -986,7 +981,6 @@ def hom(self, im_gens, base_morphism=None): To: Function field in y defined by y^2 - x^3 - 1 Defn: xx |--> x yy |--> y - """ if not isinstance(im_gens, (list, tuple)): im_gens = [im_gens] @@ -1051,7 +1045,7 @@ def _simple_model(self, name='v'): INPUT: - - ``name`` -- a string, the name of the generator of `N` + - ``name`` -- string; the name of the generator of `N` ALGORITHM: @@ -1127,7 +1121,6 @@ def _simple_model(self, name='v'): To: Function field in v defined by v^6 + x*v^4 + x^2*v^2 + x^3 + 1 Defn: z |--> v^4 + x^2 y |--> v^4 + v + x^2) - """ M = self L = M.base_field() @@ -1188,7 +1181,7 @@ def simple_model(self, name=None): INPUT: - - ``name`` -- a string (default: ``None``), the name of generator of + - ``name`` -- string (default: ``None``); the name of generator of the simple extension. If ``None``, then the name of the generator will be the same as the name of the generator of this function field. @@ -1366,7 +1359,7 @@ def separable_model(self, names=None): INPUT: - - ``names`` -- a tuple of two strings or ``None`` (default: ``None``); + - ``names`` -- tuple of two strings or ``None`` (default: ``None``); the second entry will be used as the variable name of the rational function field, the first entry will be used as the variable name of its separable extension. If ``None``, then the variable names will be @@ -1512,7 +1505,6 @@ def separable_model(self, names=None): Defn: z |--> x_ y |--> x_^3 x |--> x_^6) - """ if names is None: pass @@ -1582,9 +1574,9 @@ def change_variable_name(self, name): INPUT: - - ``name`` -- a string or a tuple consisting of a strings, the names of + - ``name`` -- string or tuple consisting of a strings; the names of the new variables starting with a generator of this field and going - down to the rational function field. + down to the rational function field OUTPUT: @@ -1642,7 +1634,6 @@ def change_variable_name(self, name): Defn: z |--> zz y |--> yy x |--> xx) - """ if not isinstance(name, tuple): name = (name,) @@ -1736,7 +1727,7 @@ def places_above(self, p): INPUT: - - ``p`` -- place of the base rational function field. + - ``p`` -- place of the base rational function field EXAMPLES:: @@ -1898,7 +1889,7 @@ def residue_field(self, place, name=None): ideal. If an element not in the valuation ring is applied to the map, an - exception ``TypeError`` is raised. + exception :exc:`TypeError` is raised. EXAMPLES:: @@ -2096,7 +2087,7 @@ def get_place(self, degree): INPUT: - - ``degree`` -- a positive integer + - ``degree`` -- positive integer OUTPUT: a place of ``degree`` if any exists; otherwise ``None`` @@ -2122,7 +2113,6 @@ def get_place(self, degree): sage: L.get_place(7) Place (x^7 + x + 1, y + x^6 + x^5 + x^4 + x^3 + x) sage: L.get_place(8) - """ for p in self._places_finite(degree): return p diff --git a/src/sage/rings/function_field/function_field_rational.py b/src/sage/rings/function_field/function_field_rational.py index bb2075b1ecf..192b6e0deb6 100644 --- a/src/sage/rings/function_field/function_field_rational.py +++ b/src/sage/rings/function_field/function_field_rational.py @@ -123,7 +123,6 @@ class RationalFunctionField(FunctionField): + Place (x, y - 1) + Place (x, y + 1) - Place (x + i, y) - """ Element = FunctionFieldElement_rational @@ -204,7 +203,6 @@ def __hash__(self): sage: K. = FunctionField(QQ) sage: hash(K) == hash((K.constant_base_field(), K.variable_names())) True - """ return self._hash @@ -253,7 +251,6 @@ def _element_constructor_(self, x): sage: I = S * [x^2 - y^2, y - t] sage: I.groebner_basis() # needs sage.rings.function_field [x^2 - t^2, y - t] - """ if isinstance(x, FunctionFieldElement): return self.element_class(self, self._field(x._x)) @@ -275,7 +272,7 @@ def _to_constant_base_field(self, f): INPUT: - ``f`` -- element of the rational function field which is a - constant of the underlying rational function field. + constant of the underlying rational function field EXAMPLES:: @@ -295,7 +292,6 @@ def _to_constant_base_field(self, f): True sage: x in QQ False - """ K = self.constant_base_field() if f.denominator() in K and f.numerator() in K: @@ -310,7 +306,8 @@ def _to_polynomial(self, f): INPUT: - - ``f`` -- an element of this rational function field whose denominator is a constant. + - ``f`` -- an element of this rational function field whose denominator + is a constant EXAMPLES:: @@ -332,9 +329,7 @@ def _to_bivariate_polynomial(self, f): - ``f`` -- univariate polynomial over the function field - OUTPUT: - - - bivariate polynomial, denominator + OUTPUT: bivariate polynomial, denominator EXAMPLES:: @@ -405,7 +400,6 @@ def _factor_univariate_polynomial(self, f, proof=None): sage: F = t*x sage: F.factor(proof=False) (x) * t - """ old_variable_name = f.variable_name() # the variables of the bivariate polynomial must be distinct @@ -445,9 +439,7 @@ def extension(self, f, names=None): - ``names`` -- string or length-1 tuple - OUTPUT: - - - a function field + OUTPUT: a function field EXAMPLES:: @@ -506,7 +498,8 @@ def free_module(self, base=None, basis=None, map=True): - ``basis`` -- (ignored) a basis for the vector space - - ``map`` -- (default ``True``), whether to return maps to and from the vector space + - ``map`` -- (default: ``True``) whether to return maps to and from the + vector space OUTPUT: @@ -538,7 +531,6 @@ def free_module(self, base=None, basis=None, map=True): Isomorphism: From: Rational function field in x over Rational Field To: Vector space of dimension 1 over Rational function field in x over Rational Field) - """ if basis is not None: raise NotImplementedError @@ -648,11 +640,9 @@ def hom(self, im_gens, base_morphism=None): ``base_morphism``; this is not checked. - ``base_morphism`` -- a homomorphism from the base field into the - other ring. If ``None``, try to use a coercion map. - - OUTPUT: + other ring; if ``None``, try to use a coercion map - - a map between function fields + OUTPUT: a map between function fields EXAMPLES: @@ -706,7 +696,6 @@ def field(self): .. SEEALSO:: :meth:`sage.rings.fraction_field.FractionField_1poly_field.function_field` - """ return self._field @@ -800,7 +789,7 @@ def change_variable_name(self, name): INPUT: - - ``name`` -- a string or a tuple consisting of a single string, the + - ``name`` -- string or tuple consisting of a single string; the name of the new variable OUTPUT: @@ -825,7 +814,6 @@ def change_variable_name(self, name): Defn: x |--> y) sage: L.change_variable_name('x')[0] is K True - """ if isinstance(name, tuple): if len(name) != 1: @@ -974,7 +962,7 @@ def get_place(self, degree): INPUT: - - ``degree`` -- a positive integer + - ``degree`` -- positive integer EXAMPLES:: @@ -990,7 +978,6 @@ def get_place(self, degree): Place (x^4 + x + 1) sage: K.get_place(5) # needs sage.libs.pari Place (x^5 + x^2 + 1) - """ for p in self._places_finite(degree): return p diff --git a/src/sage/rings/function_field/ideal.py b/src/sage/rings/function_field/ideal.py index 00450c60533..2ef9d20d132 100644 --- a/src/sage/rings/function_field/ideal.py +++ b/src/sage/rings/function_field/ideal.py @@ -445,7 +445,6 @@ def factor(self): sage: I = O.ideal(y) sage: I == I.factor().prod() True - """ return Factorization(self._factor(), cr=True) @@ -700,9 +699,7 @@ def module(self): The formation of the module is compatible with the vector space corresponding to the function field. - OUTPUT: - - - a module over the maximal order of the base field of the ideal + OUTPUT: a module over the maximal order of the base field of the ideal EXAMPLES:: @@ -967,7 +964,7 @@ def __contains__(self, x): def __hash__(self): """ - Return the hash of this ideal + Return the hash of this ideal. EXAMPLES:: diff --git a/src/sage/rings/function_field/ideal_polymod.py b/src/sage/rings/function_field/ideal_polymod.py index 83a1370e493..829598231cb 100644 --- a/src/sage/rings/function_field/ideal_polymod.py +++ b/src/sage/rings/function_field/ideal_polymod.py @@ -30,7 +30,7 @@ class FunctionFieldIdeal_polymod(FunctionFieldIdeal): """ - Fractional ideals of algebraic function fields + Fractional ideals of algebraic function fields. INPUT: @@ -468,7 +468,6 @@ def intersect(self, other): sage: J = O.ideal(x) sage: I.intersect(J) == I * J * (I + J)^-1 True - """ from sage.matrix.special import block_matrix from .hermite_form_polynomial import reversed_hermite_form @@ -1025,7 +1024,7 @@ def _factor(self): class FunctionFieldIdeal_global(FunctionFieldIdeal_polymod): """ - Fractional ideals of canonical function fields + Fractional ideals of canonical function fields. INPUT: diff --git a/src/sage/rings/function_field/ideal_rational.py b/src/sage/rings/function_field/ideal_rational.py index 2ef3a6beba4..59c63cc9782 100644 --- a/src/sage/rings/function_field/ideal_rational.py +++ b/src/sage/rings/function_field/ideal_rational.py @@ -29,9 +29,9 @@ class FunctionFieldIdeal_rational(FunctionFieldIdeal): INPUT: - - ``ring`` -- the maximal order of the rational function field. + - ``ring`` -- the maximal order of the rational function field - - ``gen`` -- generator of the ideal, an element of the function field. + - ``gen`` -- generator of the ideal, an element of the function field EXAMPLES:: diff --git a/src/sage/rings/function_field/jacobian_base.py b/src/sage/rings/function_field/jacobian_base.py index 7954a842f13..405d90bfc3f 100644 --- a/src/sage/rings/function_field/jacobian_base.py +++ b/src/sage/rings/function_field/jacobian_base.py @@ -238,7 +238,7 @@ def _apply_functor(self, jacobian): def merge(self, other): """ - Return the functor merging ``self`` and ``other`` + Return the functor merging ``self`` and ``other``. INPUT: @@ -549,7 +549,7 @@ def get_points(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -633,7 +633,7 @@ def _an_element_(self): def __call__(self, x): """ - Return the point of ``self`` constructed from ``x`` + Return the point of ``self`` constructed from ``x``. It is assumed that ``self`` and ``x`` are points of the Jacobians attached to the same function field. @@ -776,7 +776,7 @@ def set_base_place(self, place): INPUT: - - ``place`` -- a rational place of the function field. + - ``place`` -- a rational place of the function field The base place `B` is used to map a rational place `P` of the function field to the point of the Jacobian defined by the divisor `P - B`. diff --git a/src/sage/rings/function_field/jacobian_hess.py b/src/sage/rings/function_field/jacobian_hess.py index 13e930fd620..a85bc10e256 100644 --- a/src/sage/rings/function_field/jacobian_hess.py +++ b/src/sage/rings/function_field/jacobian_hess.py @@ -832,7 +832,7 @@ def zero(self): class JacobianGroup_finite_field(JacobianGroup, JacobianGroup_finite_field_base): """ - Jacobian groups of function fields over finite fields + Jacobian groups of function fields over finite fields. INPUT: diff --git a/src/sage/rings/function_field/jacobian_khuri_makdisi.py b/src/sage/rings/function_field/jacobian_khuri_makdisi.py index 012dc983355..2c9a2e5da97 100644 --- a/src/sage/rings/function_field/jacobian_khuri_makdisi.py +++ b/src/sage/rings/function_field/jacobian_khuri_makdisi.py @@ -66,7 +66,6 @@ allows representing points of Jacobian as matrices once we fix a basis of the Riemann-Roch space. - EXAMPLES:: sage: P2. = ProjectiveSpace(GF(17), 2) @@ -170,7 +169,6 @@ class JacobianPoint(JacobianPoint_base): [0 0 0 1 0 0 0 0 5] [0 0 0 0 0 1 0 0 5] [0 0 0 0 0 0 1 0 4] - """ def __init__(self, parent, w): """ @@ -338,7 +336,7 @@ def _rmul_(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -361,7 +359,7 @@ def multiple(self, n): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: diff --git a/src/sage/rings/function_field/khuri_makdisi.pyx b/src/sage/rings/function_field/khuri_makdisi.pyx index 266a83a5c54..5933abcd1ce 100644 --- a/src/sage/rings/function_field/khuri_makdisi.pyx +++ b/src/sage/rings/function_field/khuri_makdisi.pyx @@ -472,7 +472,7 @@ cdef class KhuriMakdisi_large(KhuriMakdisi_base): cpdef Matrix addflip(self, Matrix wd1, Matrix wd2): """ - Theorem 4.3 (addflip) + Theorem 4.3 (addflip). TESTS:: diff --git a/src/sage/rings/function_field/maps.py b/src/sage/rings/function_field/maps.py index 2863a953f20..6b37456c64c 100644 --- a/src/sage/rings/function_field/maps.py +++ b/src/sage/rings/function_field/maps.py @@ -157,7 +157,6 @@ def _richcmp_(self, other, op): sage: g = K.coerce_map_from(L) sage: f == g False - """ if type(self) is not type(other): return NotImplemented @@ -245,7 +244,6 @@ def _call_(self, v): ....: for i in range(100): ....: a = F.random_element() ....: assert(f(t(a)) == a) - """ fields = self._K._intermediate_fields(self._V.base_field()) fields.pop() @@ -325,7 +323,7 @@ def __init__(self, K, V): sage: K. = FunctionField(QQ); R. = K[] sage: L. = K.extension(y^2 - x*y + 4*x^3) sage: V, f, t = L.vector_space() - sage: TestSuite(t).run(skip="_test_category") + sage: TestSuite(t).run(skip='_test_category') """ self._V = V self._K = K @@ -359,7 +357,6 @@ def _call_(self, x): ....: for i in range(100): ....: a = V.random_element() ....: assert(t(f(a)) == a) - """ ret = [x] fields = self._K._intermediate_fields(self._V.base_field()) @@ -393,7 +390,7 @@ def __init__(self, parent, im_gen, base_morphism): sage: f = K.hom(1/x); f Function Field endomorphism of Rational function field in x over Rational Field Defn: x |--> 1/x - sage: TestSuite(f).run(skip="_test_category") + sage: TestSuite(f).run(skip='_test_category') """ RingHomomorphism.__init__(self, parent) @@ -461,7 +458,7 @@ def __init__(self, parent, im_gen, base_morphism): sage: K. = FunctionField(GF(7)); R. = K[] sage: L. = K.extension(y^3 + 6*x^3 + x) sage: f = L.hom(y*2) - sage: TestSuite(f).run(skip="_test_category") + sage: TestSuite(f).run(skip='_test_category') """ FunctionFieldMorphism.__init__(self, parent, im_gen, base_morphism) # Verify that the morphism is valid: @@ -579,7 +576,8 @@ def __init__(self, parent): def _repr_type(self) -> str: r""" - Return the type of this map (a conversion), for the purposes of printing out self. + Return the type of this map (a conversion), for the purposes of + printing out ``self``. EXAMPLES:: @@ -588,7 +586,6 @@ def _repr_type(self) -> str: Conversion map: From: Rational function field in x over Rational Field To: Rational Field - """ return "Conversion" @@ -599,7 +596,6 @@ def _call_(self, x): sage: K. = FunctionField(QQ) sage: QQ(K(1)) # indirect doctest 1 - """ return x.parent()._to_constant_base_field(x) @@ -628,7 +624,6 @@ class FunctionFieldToFractionField(FunctionFieldVectorSpaceIsomorphism): sage: isinstance(f, FunctionFieldToFractionField) True sage: TestSuite(f).run() - """ def _call_(self, f): r""" @@ -641,7 +636,6 @@ def _call_(self, f): sage: f = K.coerce_map_from(L) sage: f(~L.gen()) 1/x - """ return self.codomain()(f.numerator(), f.denominator()) @@ -832,7 +826,7 @@ def _repr_type(self) -> str: def _call_(self, f): """ - Call the completion for f + Call the completion for f. EXAMPLES:: diff --git a/src/sage/rings/function_field/order_basis.py b/src/sage/rings/function_field/order_basis.py index eebaeab97d1..e4fa3dfe39e 100644 --- a/src/sage/rings/function_field/order_basis.py +++ b/src/sage/rings/function_field/order_basis.py @@ -28,8 +28,8 @@ class FunctionFieldOrder_basis(FunctionFieldOrder): - ``basis`` -- list of elements of the function field - - ``check`` -- (default: ``True``) if ``True``, check whether the module - that ``basis`` generates forms an order + - ``check`` -- boolean (default: ``True``); if ``True``, check whether the + module that ``basis`` generates forms an order EXAMPLES:: diff --git a/src/sage/rings/function_field/order_polymod.py b/src/sage/rings/function_field/order_polymod.py index 099fb4caf82..90fa9fe71ce 100644 --- a/src/sage/rings/function_field/order_polymod.py +++ b/src/sage/rings/function_field/order_polymod.py @@ -249,8 +249,8 @@ def _ideal_from_vectors_and_denominator(self, vecs, d=1, check=True): - ``d`` -- (default: 1) a nonzero element of the polynomial ring - - ``check`` -- boolean (default: ``True``); if ``True``, compute the real - denominator of the vectors, possibly different from ``d``. + - ``check`` -- boolean (default: ``True``); if ``True``, compute the + real denominator of the vectors, possibly different from ``d`` EXAMPLES:: @@ -618,7 +618,6 @@ def decomposition(self, ideal): Use Kummer's theorem to shortcut this code if possible, like as done in :meth:`FunctionFieldMaximalOrder_global.decomposition()` - """ from sage.algebras.finite_dimensional_algebras.finite_dimensional_algebra import FiniteDimensionalAlgebra from sage.matrix.constructor import matrix @@ -684,7 +683,7 @@ def decomposition(self, ideal): # not be in pO. To ensure that beta*P is in pO, multiplying # beta by each of P's generators must produce a vector whose # elements are multiples of p. We can ensure that all this - # occurs by constructing a matrix in k, and finding a non-zero + # occurs by constructing a matrix in k, and finding a nonzero # vector in the kernel of the matrix. m = [] diff --git a/src/sage/rings/function_field/order_rational.py b/src/sage/rings/function_field/order_rational.py index b21712bcf2c..87cbbdb4858 100644 --- a/src/sage/rings/function_field/order_rational.py +++ b/src/sage/rings/function_field/order_rational.py @@ -287,7 +287,6 @@ def _residue_field_global(self, q, name=None): sage: K, fr_K, to_K = O._residue_field_global(_f) # needs sage.modules sage: all(to_K(fr_K(e)) == e for e in K) # needs sage.modules True - """ # polynomial ring over the base field R = self._ring @@ -494,7 +493,8 @@ def basis(self): def gen(self, n=0): """ - Return the ``n``-th generator of self. Since there is only one generator ``n`` must be 0. + Return the `n`-th generator of ``self``. Since there is only one + generator `n` must be `0`. EXAMPLES:: diff --git a/src/sage/rings/function_field/place_polymod.py b/src/sage/rings/function_field/place_polymod.py index ee9e8de5874..7a5f2b90cad 100644 --- a/src/sage/rings/function_field/place_polymod.py +++ b/src/sage/rings/function_field/place_polymod.py @@ -387,7 +387,7 @@ def _residue_field(self, name=None): INPUT: - - ``name`` -- string (default: `None`); name of the generator + - ``name`` -- string (default: ``None``); name of the generator of the residue field EXAMPLES:: diff --git a/src/sage/rings/function_field/valuation.py b/src/sage/rings/function_field/valuation.py index 5bd32b7901e..a192a76beb6 100644 --- a/src/sage/rings/function_field/valuation.py +++ b/src/sage/rings/function_field/valuation.py @@ -180,7 +180,6 @@ class FunctionFieldValuationFactory(UniqueFactory): 1 See :meth:`sage.rings.function_field.function_field.FunctionField.valuation` for further examples. - """ def create_key_and_extra_args(self, domain, prime): r""" @@ -207,7 +206,6 @@ def create_key_and_extra_args(self, domain, prime): sage: w = K.valuation(w) sage: w is K.valuation((w, K.hom([~K.gen()]), K.hom([~K.gen()]))) False - """ from sage.categories.function_fields import FunctionFields if domain not in FunctionFields(): @@ -242,8 +240,8 @@ def create_key_and_extra_args(self, domain, prime): # unique extension to domain base_valuation = domain.base_field().valuation(prime) return self.create_key_and_extra_args_from_valuation(domain, base_valuation) - from sage.rings.ideal import is_Ideal - if is_Ideal(prime): + from sage.rings.ideal import Ideal_generic + if isinstance(prime, Ideal_generic): raise NotImplementedError("a place cannot be given by an ideal yet") raise NotImplementedError("argument must be a place or a pseudo-valuation on a supported subring but %r does not satisfy this for the domain %r" % (prime, domain)) @@ -257,7 +255,6 @@ def create_key_and_extra_args_from_place(self, domain, generator): sage: K. = FunctionField(QQ) sage: v = K.valuation(1/x) # indirect doctest - """ if generator not in domain.base_field(): raise NotImplementedError("a place must be defined over a rational function field") @@ -313,7 +310,6 @@ def create_key_and_extra_args_from_valuation(self, domain, valuation): (in Function field in y defined by y^3 + x*y + 2*x^2 after y |--> 1/x^2*y), [ (x)-adic valuation, v(y) = 1/2 ]-adic valuation (in Function field in y defined by y^3 + x*y + 2*x^2 after y |--> 1/x^2*y)] - """ # this should have been handled by create_key already assert valuation.domain() is not domain @@ -358,7 +354,6 @@ def create_key_and_extra_args_from_valuation_on_isomorphic_field(self, domain, v sage: L. = K.extension(y^2 + y + x^3) # needs sage.rings.function_field sage: v = K.valuation(1/x) # needs sage.rings.function_field sage: w = v.extension(L) # indirect doctest # needs sage.rings.function_field - """ from sage.categories.function_fields import FunctionFields if valuation.domain() not in FunctionFields(): @@ -404,7 +399,6 @@ def create_object(self, version, key, **extra_args): sage: w = valuations.GaussValuation(R, QQ.valuation(2)) sage: v = K.valuation(w); v # indirect doctest 2-adic valuation - """ domain, valuation = key from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace @@ -469,7 +463,6 @@ class FunctionFieldValuation_base(DiscretePseudoValuation): sage: from sage.rings.function_field.valuation import FunctionFieldValuation_base sage: isinstance(v, FunctionFieldValuation_base) True - """ @@ -484,7 +477,6 @@ class DiscreteFunctionFieldValuation_base(DiscreteValuation): sage: from sage.rings.function_field.valuation import DiscreteFunctionFieldValuation_base sage: isinstance(v, DiscreteFunctionFieldValuation_base) True - """ def extensions(self, L): r""" @@ -597,7 +589,6 @@ class RationalFunctionFieldValuation_base(FunctionFieldValuation_base): sage: from sage.rings.function_field.valuation import RationalFunctionFieldValuation_base sage: isinstance(v, RationalFunctionFieldValuation_base) True - """ @cached_method def element_with_valuation(self, s): @@ -618,7 +609,6 @@ def element_with_valuation(self, s): 2/x sage: w.element_with_valuation(1) 2 - """ constant_valuation = self.restriction(self.domain().constant_base_field()) if constant_valuation.is_trivial(): @@ -642,7 +632,6 @@ class ClassicalFunctionFieldValuation_base(DiscreteFunctionFieldValuation_base): sage: from sage.rings.function_field.valuation import ClassicalFunctionFieldValuation_base sage: isinstance(v, ClassicalFunctionFieldValuation_base) True - """ def _test_classical_residue_field(self, **options): r""" @@ -654,7 +643,6 @@ def _test_classical_residue_field(self, **options): sage: K. = FunctionField(QQ) sage: v = K.valuation(x^2 + 1) sage: v._test_classical_residue_field() # needs sage.rings.number_field - """ tester = self._tester(**options) @@ -673,7 +661,6 @@ def _ge_(self, other): False sage: w >= v False - """ if other.is_trivial(): return other.is_discrete_valuation() @@ -691,7 +678,6 @@ class InducedRationalFunctionFieldValuation_base(FunctionFieldValuation_base): sage: K. = FunctionField(QQ) sage: v = K.valuation(x^2 + 1) # indirect doctest - """ def __init__(self, parent, base_valuation): r""" @@ -702,7 +688,6 @@ def __init__(self, parent, base_valuation): sage: from sage.rings.function_field.valuation import InducedRationalFunctionFieldValuation_base sage: isinstance(v, InducedRationalFunctionFieldValuation_base) True - """ FunctionFieldValuation_base.__init__(self, parent) @@ -721,7 +706,6 @@ def uniformizer(self): sage: K. = FunctionField(QQ) sage: K.valuation(x).uniformizer() x - """ return self.domain()(self._base_valuation.uniformizer()) @@ -738,7 +722,6 @@ def lift(self, F): 0 sage: v.lift(1) 1 - """ F = self.residue_ring().coerce(F) if F in self._base_valuation.residue_ring(): @@ -761,7 +744,6 @@ def value_group(self): sage: K. = FunctionField(QQ) sage: K.valuation(x).value_group() Additive Abelian Group generated by 1 - """ return self._base_valuation.value_group() @@ -775,7 +757,6 @@ def reduce(self, f): sage: v = K.valuation(x^2 + 1) sage: v.reduce(x) # needs sage.rings.number_field u1 - """ f = self.domain().coerce(f) @@ -806,7 +787,6 @@ def _repr_(self): sage: K. = FunctionField(QQ) sage: K.valuation(x^2 + 1) # indirect doctest (x^2 + 1)-adic valuation - """ from sage.rings.valuation.augmented_valuation import AugmentedValuation_base from sage.rings.valuation.gauss_valuation import GaussValuation @@ -832,7 +812,6 @@ def extensions(self, L): sage: L. = FunctionField(GaussianIntegers().fraction_field()) sage: v.extensions(L) # indirect doctest [(x - I)-adic valuation, (x + I)-adic valuation] - """ K = self.domain() if L is K: @@ -865,7 +844,6 @@ def _call_(self, f): sage: v = K.valuation(x) # indirect doctest sage: v((x+1)/x^2) -2 - """ return self._base_valuation(f.numerator()) - self._base_valuation(f.denominator()) @@ -878,7 +856,6 @@ def residue_ring(self): sage: K. = FunctionField(QQ) sage: K.valuation(x).residue_ring() Rational Field - """ return self._base_valuation.residue_ring().fraction_field() @@ -891,7 +868,6 @@ def restriction(self, ring): sage: K. = FunctionField(QQ) sage: K.valuation(x).restriction(QQ) Trivial valuation on Rational Field - """ if ring.is_subring(self._base_valuation.domain()): return self._base_valuation.restriction(ring) @@ -923,7 +899,6 @@ def simplify(self, f, error=None, force=False): sage: v.simplify(f, force=True) 3 - """ f = self.domain().coerce(f) @@ -984,7 +959,6 @@ def _relative_size(self, f): sage: v.simplify(f, force=True) -1 - """ return max(self._base_valuation._relative_size(f.numerator()), self._base_valuation._relative_size(f.denominator())) @@ -1015,7 +989,6 @@ class FiniteRationalFunctionFieldValuation(InducedRationalFunctionFieldValuation sage: q = L.valuation(x^6 - t); q (x^6 + 2*t)-adic valuation - """ def __init__(self, parent, base_valuation): r""" @@ -1026,7 +999,6 @@ def __init__(self, parent, base_valuation): sage: from sage.rings.function_field.valuation import FiniteRationalFunctionFieldValuation sage: isinstance(v, FiniteRationalFunctionFieldValuation) True - """ InducedRationalFunctionFieldValuation_base.__init__(self, parent, base_valuation) ClassicalFunctionFieldValuation_base.__init__(self, parent) @@ -1044,7 +1016,6 @@ class NonClassicalRationalFunctionFieldValuation(InducedRationalFunctionFieldVal sage: v = GaussValuation(QQ['x'], QQ.valuation(2)) sage: w = K.valuation(v); w # indirect doctest 2-adic valuation - """ def __init__(self, parent, base_valuation): r""" @@ -1061,7 +1032,6 @@ def __init__(self, parent, base_valuation): sage: from sage.rings.function_field.valuation import NonClassicalRationalFunctionFieldValuation sage: isinstance(w, NonClassicalRationalFunctionFieldValuation) True - """ InducedRationalFunctionFieldValuation_base.__init__(self, parent, base_valuation) RationalFunctionFieldValuation_base.__init__(self, parent) @@ -1100,7 +1070,6 @@ def residue_ring(self): sage: w = K.valuation(vv) sage: w.residue_ring() Finite Field of size 2 - """ if not self.is_discrete_valuation(): # A pseudo valuation attaining negative infinity does typically not have a function field as its residue ring @@ -1121,7 +1090,6 @@ class FunctionFieldFromLimitValuation(FiniteExtensionFromLimitValuation, Discret sage: v = K.valuation(x - 1) # indirect doctest # needs sage.rings.function_field sage: w = v.extension(L); w # needs sage.rings.function_field (x - 1)-adic valuation - """ def __init__(self, parent, approximant, G, approximants): r""" @@ -1136,7 +1104,6 @@ def __init__(self, parent, approximant, G, approximants): sage: from sage.rings.function_field.valuation import FunctionFieldFromLimitValuation sage: isinstance(w, FunctionFieldFromLimitValuation) True - """ FiniteExtensionFromLimitValuation.__init__(self, parent, approximant, G, approximants) DiscreteFunctionFieldValuation_base.__init__(self, parent) @@ -1155,7 +1122,6 @@ def _to_base_domain(self, f): sage: w = v.extension(L) sage: w._to_base_domain(y).parent() Univariate Polynomial Ring in y over Rational function field in x over Rational Field - """ return f.element() @@ -1173,7 +1139,6 @@ def scale(self, scalar): sage: w = v.extension(L) sage: 3*w 3 * (x - 1)-adic valuation - """ if scalar in QQ and scalar > 0 and scalar != 1: return self.domain().valuation(self._base_valuation._initial_approximation.scale(scalar)) @@ -1190,7 +1155,6 @@ class FunctionFieldMappedValuation_base(FunctionFieldValuation_base, MappedValua sage: K. = FunctionField(GF(2)) sage: v = K.valuation(1/x); v Valuation at the infinite place - """ def __init__(self, parent, base_valuation, to_base_valuation_domain, from_base_valuation_domain): r""" @@ -1201,7 +1165,6 @@ def __init__(self, parent, base_valuation, to_base_valuation_domain, from_base_v sage: from sage.rings.function_field.valuation import FunctionFieldMappedValuation_base sage: isinstance(v, FunctionFieldMappedValuation_base) True - """ FunctionFieldValuation_base.__init__(self, parent) MappedValuation_base.__init__(self, parent, base_valuation) @@ -1222,7 +1185,6 @@ def _to_base_domain(self, f): sage: w = v.extension(L) # needs sage.rings.function_field sage: w._to_base_domain(y) # needs sage.rings.function_field x^2*y - """ return self._to_base(f) @@ -1256,7 +1218,6 @@ def scale(self, scalar): sage: w = v.extension(L) # needs sage.rings.function_field sage: 3*w # needs sage.rings.function_field 3 * (x)-adic valuation (in Rational function field in x over Finite Field of size 2 after x |--> 1/x) - """ from sage.rings.rational_field import QQ if scalar in QQ and scalar > 0 and scalar != 1: @@ -1275,7 +1236,6 @@ def _repr_(self): sage: v = K.valuation(1/x) sage: v.extension(L) # indirect doctest # needs sage.rings.function_field Valuation at the infinite place - """ to_base = repr(self._to_base) if hasattr(self._to_base, '_repr_defn'): @@ -1296,7 +1256,6 @@ def is_discrete_valuation(self): sage: w0,w1 = v.extensions(L) sage: w0.is_discrete_valuation() True - """ return self._base_valuation.is_discrete_valuation() @@ -1312,7 +1271,6 @@ class FunctionFieldMappedValuationRelative_base(FunctionFieldMappedValuation_bas sage: K. = FunctionField(GF(2)) sage: v = K.valuation(1/x); v Valuation at the infinite place - """ def __init__(self, parent, base_valuation, to_base_valuation_domain, from_base_valuation_domain): r""" @@ -1323,7 +1281,6 @@ def __init__(self, parent, base_valuation, to_base_valuation_domain, from_base_v sage: from sage.rings.function_field.valuation import FunctionFieldMappedValuationRelative_base sage: isinstance(v, FunctionFieldMappedValuationRelative_base) True - """ FunctionFieldMappedValuation_base.__init__(self, parent, base_valuation, to_base_valuation_domain, from_base_valuation_domain) if self.domain().constant_base_field() is not base_valuation.domain().constant_base_field(): @@ -1338,7 +1295,6 @@ def restriction(self, ring): sage: K. = FunctionField(GF(2)) sage: K.valuation(1/x).restriction(GF(2)) Trivial valuation on Finite Field of size 2 - """ if ring.is_subring(self.domain().constant_base_field()): return self._base_valuation.restriction(ring) @@ -1360,7 +1316,6 @@ class RationalFunctionFieldMappedValuation(FunctionFieldMappedValuationRelative_ Valuation on rational function field induced by [ Gauss valuation induced by 2-adic valuation, v(x) = 1 ] (in Rational function field in x over Rational Field after x |--> 1/x) - """ def __init__(self, parent, base_valuation, to_base_valuation_doain, from_base_valuation_domain): r""" @@ -1374,7 +1329,6 @@ def __init__(self, parent, base_valuation, to_base_valuation_doain, from_base_va sage: from sage.rings.function_field.valuation import RationalFunctionFieldMappedValuation sage: isinstance(v, RationalFunctionFieldMappedValuation) True - """ FunctionFieldMappedValuationRelative_base.__init__(self, parent, base_valuation, to_base_valuation_doain, from_base_valuation_domain) RationalFunctionFieldValuation_base.__init__(self, parent) @@ -1388,7 +1342,6 @@ class InfiniteRationalFunctionFieldValuation(FunctionFieldMappedValuationRelativ sage: K. = FunctionField(QQ) sage: v = K.valuation(1/x) # indirect doctest - """ def __init__(self, parent): r""" @@ -1399,7 +1352,6 @@ def __init__(self, parent): sage: from sage.rings.function_field.valuation import InfiniteRationalFunctionFieldValuation sage: isinstance(v, InfiniteRationalFunctionFieldValuation) True - """ x = parent.domain().gen() FunctionFieldMappedValuationRelative_base.__init__(self, parent, FunctionFieldValuation(parent.domain(), x), parent.domain().hom([1/x]), parent.domain().hom([1/x])) @@ -1415,7 +1367,6 @@ def _repr_(self): sage: K. = FunctionField(QQ) sage: K.valuation(1/x) # indirect doctest Valuation at the infinite place - """ return "Valuation at the infinite place" @@ -1448,7 +1399,6 @@ class FunctionFieldExtensionMappedValuation(FunctionFieldMappedValuationRelative sage: from sage.rings.function_field.valuation import FunctionFieldExtensionMappedValuation sage: isinstance(w, FunctionFieldExtensionMappedValuation) # needs sage.rings.function_field True - """ def _repr_(self): r""" @@ -1472,7 +1422,6 @@ def _repr_(self): sage: w = v.extensions(L); w [[ Valuation at the infinite place, v(y + 1) = 2 ]-adic valuation, [ Valuation at the infinite place, v(y - 1) = 2 ]-adic valuation] - """ assert (self.domain().base() is not self.domain()) if repr(self._base_valuation) == repr(self.restriction(self.domain().base())): diff --git a/src/sage/rings/homset.py b/src/sage/rings/homset.py index 6e3126d7ebd..94781b87396 100644 --- a/src/sage/rings/homset.py +++ b/src/sage/rings/homset.py @@ -53,11 +53,10 @@ def RingHomset(R, S, category=None): sage: Hom(ZZ, QQ) # indirect doctest Set of Homomorphisms from Integer Ring to Rational Field - """ - if quotient_ring.is_QuotientRing(R): - from .polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing - if not is_PolynomialQuotientRing(R): # backwards compatibility + if isinstance(R, quotient_ring.QuotientRing_nc): + from .polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic + if not isinstance(R, PolynomialQuotientRing_generic): # backwards compatibility return RingHomset_quo_ring(R, S, category=category) return RingHomset_generic(R, S, category=category) @@ -204,7 +203,7 @@ def _element_constructor_(self, x, check=True, base_map=None): def natural_map(self): """ - Returns the natural map from the domain to the codomain. + Return the natural map from the domain to the codomain. The natural map is the coercion map from the domain ring to the codomain ring. @@ -240,7 +239,6 @@ def zero(self): Traceback (most recent call last): ... ValueError: homset has no zero element - """ if not self.codomain().is_zero(): raise ValueError("homset has no zero element") @@ -324,7 +322,6 @@ def _element_constructor_(self, x, base_map=None, check=True): Coercion map: From: Multivariate Polynomial Ring in x, y over Rational Field To: Quotient of Multivariate Polynomial Ring in x, y over Rational Field by the ideal (x^2 + y^2) - """ if isinstance(x, morphism.RingHomomorphism_from_quotient): phi = x._phi() diff --git a/src/sage/rings/ideal.py b/src/sage/rings/ideal.py index bf1496fb88c..4208c63c55c 100644 --- a/src/sage/rings/ideal.py +++ b/src/sage/rings/ideal.py @@ -48,22 +48,20 @@ def Ideal(*args, **kwds): There are some shorthand notations for creating an ideal, in addition to using the :func:`Ideal` function: - - ``R.ideal(gens, coerce=True)`` - - ``gens*R`` - - ``R*gens`` + - ``R.ideal(gens, coerce=True)`` + - ``gens*R`` + - ``R*gens`` INPUT: - - ``R`` -- A ring (optional; if not given, will try to infer it from - ``gens``) + - ``R`` -- a ring (optional; if not given, will try to infer it from ``gens``) - - ``gens`` -- list of elements generating the ideal + - ``gens`` -- list of elements generating the ideal - - ``coerce`` -- bool (default: ``True``); - whether ``gens`` need to be coerced into the ring. + - ``coerce`` -- boolean (default: ``True``); whether ``gens`` need to be + coerced into the ring - - OUTPUT: The ideal of ring generated by ``gens``. + OUTPUT: the ideal of ring generated by ``gens`` EXAMPLES:: @@ -222,6 +220,9 @@ def is_Ideal(x): sage: from sage.rings.ideal import is_Ideal sage: R = ZZ sage: is_Ideal(R) + doctest:warning... + DeprecationWarning: The function is_Ideal is deprecated; use 'isinstance(..., Ideal_generic)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. False sage: 1*R; is_Ideal(1*R) Principal ideal (1) of Integer Ring @@ -240,6 +241,10 @@ def is_Ideal(x): sage: is_Ideal((x^2 + 1)*R) True """ + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_Ideal is deprecated; " + "use 'isinstance(..., Ideal_generic)' instead.") return isinstance(x, Ideal_generic) @@ -255,12 +260,12 @@ def __init__(self, ring, gens, coerce=True, **kwds): INPUT: - - ``ring`` -- A ring + - ``ring`` -- a ring - - ``gens`` -- The generators for this ideal + - ``gens`` -- the generators for this ideal - - ``coerce`` -- (default: ``True``) If ``gens`` needs to be coerced - into ``ring``. + - ``coerce`` -- boolean (default: ``True``); if ``gens`` needs to be coerced + into ``ring`` EXAMPLES:: @@ -342,21 +347,18 @@ def random_element(self, *args, **kwds): sage: I = P.ideal([a^2, a*b + c, c^3]) sage: I.random_element() # random 2*a^5*c + a^2*b*c^4 + ... + O(a, b, c)^13 - """ return sum(self.__ring.random_element(*args, **kwds) * g for g in self.__gens) def _richcmp_(self, other, op): """ - Compares the generators of two ideals. + Compare the generators of two ideals. INPUT: - ``other`` -- an ideal - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -449,7 +451,7 @@ def __bool__(self): def base_ring(self): r""" - Returns the base ring of this ideal. + Return the base ring of this ideal. EXAMPLES:: @@ -733,7 +735,7 @@ def is_maximal(self): def is_primary(self, P=None): r""" - Returns ``True`` if this ideal is primary (or `P`-primary, if + Return ``True`` if this ideal is primary (or `P`-primary, if a prime ideal `P` is specified). Recall that an ideal `I` is primary if and only if `I` has a @@ -915,7 +917,7 @@ def embedded_primes(self): def is_principal(self): r""" - Returns ``True`` if the ideal is principal in the ring containing the + Return ``True`` if the ideal is principal in the ring containing the ideal. .. TODO:: @@ -1045,7 +1047,7 @@ def __radd__(self, other): def __mul__(self, other): """ - This method just makes sure that ``self`` and other are ideals in the + This method just makes sure that ``self`` and ``other`` are ideals in the same ring and then calls :meth:`_mul_`. If you want to change the behaviour of ideal multiplication in a subclass of :class:`Ideal_generic` please overwrite :meth:`_mul_` and not @@ -1074,7 +1076,7 @@ def _mul_(self, other): This method assumes that ``self`` and ``other`` are Ideals of the same ring. - The number of generators of ```self * other` will be + The number of generators of ``self * other`` will be ``self.ngens() * other.ngens()``. So if used repeatedly this method will create an ideal with a uselessly large amount of generators. Therefore it is advisable to overwrite this method with a method that @@ -1100,7 +1102,6 @@ def __rmul__(self, other): sage: I = [x*y+y*z,x^2+x*y-y*x-y^2]*P sage: [2]*I # indirect doctest Ideal (2*x*y + 2*y*z, 2*x^2 - 2*y^2) of Multivariate Polynomial Ring in x, y, z over Rational Field - """ if not isinstance(other, Ideal_generic): try: @@ -1113,7 +1114,7 @@ def __rmul__(self, other): def norm(self): """ - Returns the norm of this ideal. + Return the norm of this ideal. In the general case, this is just the ideal itself, since the ring it lies in can't be implicitly assumed to be an extension of anything. @@ -1133,7 +1134,7 @@ def norm(self): def absolute_norm(self): """ - Returns the absolute norm of this ideal. + Return the absolute norm of this ideal. In the general case, this is just the ideal itself, since the ring it lies in can't be implicitly assumed to be an extension of anything. @@ -1210,7 +1211,6 @@ def _macaulay2_init_(self, macaulay2=None): sage: R2 = macaulay2(R.ideal(y^2 - x)).ring() # optional - macaulay2 sage: R1._operator('===', R2) # optional - macaulay2 true - """ if macaulay2 is None: from sage.interfaces.macaulay2 import macaulay2 as m2_default @@ -1285,7 +1285,7 @@ def _repr_(self): def is_principal(self): r""" - Returns ``True`` if the ideal is principal in the ring containing the + Return ``True`` if the ideal is principal in the ring containing the ideal. When the ideal construction is explicitly principal (i.e. when we define an ideal with one element) this is always the case. @@ -1504,7 +1504,7 @@ def reduce(self, f): def gcd(self, other): r""" - Returns the greatest common divisor of the principal ideal with the + Return the greatest common divisor of the principal ideal with the ideal ``other``; that is, the largest principal ideal contained in both the ideal and ``other`` @@ -1607,7 +1607,7 @@ def is_prime(self): def is_maximal(self): """ - Returns whether this ideal is maximal. + Return whether this ideal is maximal. Principal ideal domains have Krull dimension 1 (or 0), so an ideal is maximal if and only if it's prime (and nonzero if the ring is not a @@ -1724,15 +1724,15 @@ def Cyclic(R, n=None, homog=False, singular=None): INPUT: - - ``R`` -- base ring to construct ideal for + - ``R`` -- base ring to construct ideal for - - ``n`` -- number of cyclic roots (default: ``None``). If ``None``, then - ``n`` is set to ``R.ngens()``. + - ``n`` -- number of cyclic roots (default: ``None``); if ``None``, then + ``n`` is set to ``R.ngens()`` - - ``homog`` -- (default: ``False``) if ``True`` a homogeneous ideal is - returned using the last variable in the ideal + - ``homog`` -- boolean (default: ``False``); if ``True`` a homogeneous + ideal is returned using the last variable in the ideal - - ``singular`` -- singular instance to use + - ``singular`` -- Singular instance to use .. NOTE:: @@ -1783,22 +1783,21 @@ def Cyclic(R, n=None, homog=False, singular=None): return R2.ideal(I).change_ring(R) def Katsura(R, n=None, homog=False, singular=None): - """ - ``n``-th katsura ideal of ``R`` if ``R`` is coercible to + r""" + `n`-th katsura ideal of `R` if `R` is coercible to :class:`Singular `. INPUT: - ``R`` -- base ring to construct ideal for - - ``n`` -- (default: ``None``) which katsura ideal of ``R``. If ``None``, - then ``n`` is set to ``R.ngens()``. - - - ``homog`` -- if ``True`` a homogeneous ideal is returned - using the last variable in the ideal (default: ``False``) + - ``n`` -- (default: ``None``) which katsura ideal of `R`. If ``None``, + then ``n`` is set to ``R.ngens()`` - - ``singular`` -- singular instance to use + - ``homog`` -- boolean (default: ``False``); if ``True`` a homogeneous + ideal is returned using the last variable in the ideal + - ``singular`` -- Singular instance to use EXAMPLES:: @@ -1809,7 +1808,7 @@ def Katsura(R, n=None, homog=False, singular=None): :: - sage: Q. = PolynomialRing(QQ, implementation="singular") # needs sage.libs.singular + sage: Q. = PolynomialRing(QQ, implementation='singular') # needs sage.libs.singular sage: J = sage.rings.ideal.Katsura(Q,1); J # needs sage.libs.singular Ideal (x - 1) of Multivariate Polynomial Ring in x over Rational Field """ diff --git a/src/sage/rings/infinity.py b/src/sage/rings/infinity.py index 16826c872ce..986b32cb5d5 100644 --- a/src/sage/rings/infinity.py +++ b/src/sage/rings/infinity.py @@ -666,7 +666,7 @@ def _repr_(self) -> str: def _element_constructor_(self, x): """ - The element constructor + The element constructor. TESTS:: @@ -935,7 +935,7 @@ def _mul_(self, other): def _sympy_(self): """ - Converts ``unsigned_infinity`` to sympy ``zoo``. + Convert ``unsigned_infinity`` to sympy ``zoo``. EXAMPLES:: @@ -1126,7 +1126,7 @@ def _repr_(self) -> str: def _element_constructor_(self, x): """ - The element constructor + The element constructor. TESTS:: @@ -1629,7 +1629,7 @@ def sqrt(self): def _sympy_(self): """ - Converts ``-oo`` to sympy ``-oo``. + Convert ``-oo`` to sympy ``-oo``. Then you don't have to worry which ``oo`` you use, like in these examples: @@ -1644,7 +1644,6 @@ def _sympy_(self): True sage: bool((-oo)._sympy_() == -sympy.oo) True - """ import sympy return -sympy.oo @@ -1731,7 +1730,7 @@ def sqrt(self): def _sympy_(self): """ - Converts ``oo`` to sympy ``oo``. + Convert ``oo`` to sympy ``oo``. Then you don't have to worry which ``oo`` you use, like in these examples: @@ -1769,7 +1768,7 @@ def _gap_init_(self) -> str: def test_comparison(ring): """ - Check comparison with infinity + Check comparison with infinity. INPUT: @@ -1848,7 +1847,7 @@ def test_signed_infinity(pos_inf): INPUT: - - ``pos_inf`` -- a representation of positive infinity. + - ``pos_inf`` -- a representation of positive infinity OUTPUT: diff --git a/src/sage/rings/integer.pyx b/src/sage/rings/integer.pyx index 38c30f7627b..c920363e8af 100644 --- a/src/sage/rings/integer.pyx +++ b/src/sage/rings/integer.pyx @@ -276,7 +276,7 @@ cdef _digits_internal(mpz_t v,l,int offset,int power_index,power_list,digits): - ``power_index`` -- a measure of size to fill and index to power_list we're filling ``1 << (power_index+1)`` digits - - ``power_list`` -- a list of powers of the base, precomputed in + - ``power_list`` -- list of powers of the base, precomputed in method digits digits - a python sequence type with objects to use for digits note that python negative index semantics are relied upon @@ -377,7 +377,7 @@ cdef class IntegerWrapper(Integer): def __init__(self, parent=None, x=None, unsigned int base=0): """ We illustrate how to create integers with parents different - from :class:`IntegerRing``:: + from :class:`IntegerRing`:: sage: from sage.rings.integer import IntegerWrapper @@ -574,7 +574,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): ... TypeError: Unable to coerce PARI x to an Integer - Test coercion of p-adic with negative valuation:: + Test coercion of `p`-adic with negative valuation:: sage: ZZ(pari(Qp(11)(11^-7))) # needs sage.libs.pari sage.rings.padics Traceback (most recent call last): @@ -805,7 +805,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def __richcmp__(left, right, int op): """ - cmp for integers + ``cmp`` for integers. EXAMPLES:: @@ -1051,7 +1051,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def __mpz__(self): """ - Return a gmpy2 integer + Return a gmpy2 integer. EXAMPLES:: @@ -1129,7 +1129,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): sage: "{0:#x}; {0:#b}; {0:+05d}".format(ZZ(17)) '0x11; 0b10001; +0017' - """ return int(self).__format__(*args,**kwargs) @@ -1346,7 +1345,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def trailing_zero_bits(self): """ Return the number of trailing zero bits in ``self``, i.e. - the exponent of the largest power of 2 dividing self. + the exponent of the largest power of 2 dividing ``self``. EXAMPLES:: @@ -1360,7 +1359,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): 5 sage: 0.trailing_zero_bits() 0 - """ if mpz_sgn(self.value) == 0: return int(0) @@ -1376,14 +1374,14 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``base`` -- integer (default: 10) + - ``base`` -- integer (default: 10) - - ``digits`` -- optional indexable object as source for - the digits + - ``digits`` -- (optional) indexable object as source for + the digits - - ``padto`` -- the minimal length of the returned list, - sufficient number of zeros are added to make the list minimum that - length (default: 0) + - ``padto`` -- the minimal length of the returned list, sufficient + number of zeros are added to make the list minimum that length + (default: 0) As a shorthand for ``digits(2)``, you can use :meth:`.bits`. @@ -1708,7 +1706,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``base`` -- integer (default: 10) + - ``base`` -- integer (default: 10) EXAMPLES:: @@ -2044,7 +2042,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): cpdef _div_(self, right): r""" - Computes `\frac{a}{b}` + Compute `\frac{a}{b}`. EXAMPLES:: @@ -2061,7 +2059,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): cpdef _floordiv_(self, right): r""" - Computes the whole part of `\frac{x}{y}`. + Compute the whole part of `\frac{x}{y}`. EXAMPLES:: @@ -2330,22 +2328,22 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``n`` -- integer `\geq 1` (must fit in the C ``int`` type). + - ``n`` -- integer `\geq 1` (must fit in the C ``int`` type) - - ``truncate_mode`` -- boolean, whether to allow truncation if - ``self`` is not an ``n``-th power. + - ``truncate_mode`` -- boolean, whether to allow truncation if + ``self`` is not an ``n``-th power OUTPUT: If ``truncate_mode`` is 0 (default), then returns the exact n'th root - if ``self`` is an n'th power, or raises a :class:`ValueError` + if ``self`` is an n'th power, or raises a :exc:`ValueError` if it is not. If ``truncate_mode`` is 1, then if either ``n`` is odd or ``self`` is positive, returns a pair ``(root, exact_flag)`` where ``root`` is the truncated ``n``-th root (rounded towards zero) and ``exact_flag`` is a boolean indicating whether the root extraction was exact; - otherwise raises a :class:`ValueError`. + otherwise raises a :exc:`ValueError`. AUTHORS: @@ -2419,7 +2417,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): sage: ZZ(2^20).nth_root(21, truncate_mode=1) (1, False) - """ if n < 1: raise ValueError("n (=%s) must be positive" % n) @@ -2621,7 +2618,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``m`` -- integer `\geq 2` + - ``m`` -- integer `\geq 2` AUTHORS: @@ -2773,10 +2770,10 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``m`` -- default: natural log base e + - ``m`` -- (default: natural) log base e - - ``prec`` -- integer (default: ``None``): if ``None``, returns - symbolic, else to given bits of precision as in :class:`RealField` + - ``prec`` -- integer (default: ``None``); if ``None``, returns + symbolic, else to given bits of precision as in :class:`RealField` EXAMPLES:: @@ -2891,10 +2888,8 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - - ``prec`` -- integer (default: None): if None, returns - symbolic, else to given bits of precision as in :class:`RealField` - + - ``prec`` -- integer (default: ``None``); if ``None``, returns + symbolic, else to given bits of precision as in :class:`RealField` EXAMPLES:: @@ -2928,9 +2923,9 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``m`` -- Integer + - ``m`` -- integer - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -3095,7 +3090,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): If one first computes all the divisors and then sorts it, the sorting step can easily dominate the runtime. Note, - however, that (non-negative) multiplication on the left + however, that (nonnegative) multiplication on the left preserves relative order. One can leverage this fact to keep the list in order as one computes it using a process similar to that of the merge sort algorithm. @@ -3266,7 +3261,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def __abs__(self): """ - Computes `|self|` + Compute ``|self|``. EXAMPLES:: @@ -3291,7 +3286,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): sage: ZZ(1).euclidean_degree() 1 - """ from sage.rings.integer_ring import ZZ if self.parent() is ZZ: @@ -3304,7 +3298,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): depending on whether this number is negative, zero, or positive respectively. - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -3405,19 +3399,19 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def quo_rem(Integer self, other): """ - Return the quotient and the remainder of ``self`` divided by other. + Return the quotient and the remainder of ``self`` divided by ``other``. Note that the remainder returned is always either zero or of the - same sign as other. + same sign as ``other``. INPUT: - - ``other`` -- the divisor + - ``other`` -- the divisor OUTPUT: - - ``q`` -- the quotient of self/other + - ``q`` -- the quotient of ``self/other`` - - ``r`` -- the remainder of self/other + - ``r`` -- the remainder of ``self/other`` EXAMPLES:: @@ -3539,13 +3533,11 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``self`` -- Integer + - ``self`` -- integer - - ``m`` -- Integer + - ``m`` -- integer - OUTPUT: - - - a :class:`Rational` + OUTPUT: a :class:`Rational` EXAMPLES:: @@ -3706,10 +3698,10 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``bound`` -- a positive integer that fits in a C ``signed long`` - - ``start`` -- a positive integer that fits in a C ``signed long`` + - ``bound`` -- positive integer that fits in a C ``signed long`` + - ``start`` -- positive integer that fits in a C ``signed long`` - OUTPUT: A positive integer + OUTPUT: a positive integer EXAMPLES:: @@ -3868,37 +3860,34 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``algorithm`` -- string + - ``algorithm`` -- string; one of - - ``'pari'`` -- (default) use the PARI library + - ``'pari'`` -- (default) use the PARI library - - ``'flint'`` -- use the FLINT library + - ``'flint'`` -- use the FLINT library - - ``'kash'`` -- use the KASH computer algebra system (requires - kash) + - ``'kash'`` -- use the KASH computer algebra system (requires + kash) - - ``'magma'`` -- use the MAGMA computer algebra system (requires - an installation of MAGMA) + - ``'magma'`` -- use the MAGMA computer algebra system (requires + an installation of MAGMA) - - ``'qsieve'`` -- use Bill Hart's quadratic sieve code; - WARNING: this may not work as expected, see qsieve? for - more information + - ``'qsieve'`` -- use Bill Hart's quadratic sieve code; + WARNING: this may not work as expected, see qsieve? for + more information - - ``'ecm'`` -- use ECM-GMP, an implementation of Hendrik - Lenstra's elliptic curve method. + - ``'ecm'`` -- use ECM-GMP, an implementation of Hendrik + Lenstra's elliptic curve method - - ``proof`` -- bool (default: ``True``) whether or not to prove - primality of each factor (only applicable for ``'pari'`` - and ``'ecm'``). + - ``proof`` -- boolean (default: ``True``); whether or not to prove + primality of each factor (only applicable for ``'pari'`` and ``'ecm'``) - - ``limit`` -- int or None (default: None) if limit is + - ``limit`` -- integer or ``None`` (default: ``None``); if limit is given it must fit in a ``signed int``, and the factorization is done - using trial division and primes up to limit. - - OUTPUT: + using trial division and primes up to limit - - a Factorization object containing the prime factors and - their multiplicities + OUTPUT: a Factorization object containing the prime factors and + their multiplicities EXAMPLES:: @@ -4067,8 +4056,8 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): """ Return a sorted list of the primes dividing this integer. - OUTPUT: The sorted list of primes appearing in the factorization of - this rational with positive exponent. + OUTPUT: the sorted list of primes appearing in the factorization of + this rational with positive exponent EXAMPLES:: @@ -4077,7 +4066,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): sage: (-999).support() [3, 37] - Trying to find the support of 0 raises an :class:`ArithmeticError`:: + Trying to find the support of 0 raises an :exc:`ArithmeticError`:: sage: 0.support() Traceback (most recent call last): @@ -4092,7 +4081,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def coprime_integers(self, m): """ - Return the non-negative integers `< m` that are coprime to + Return the nonnegative integers `< m` that are coprime to this integer. EXAMPLES:: @@ -4211,7 +4200,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): cpdef RingElement _valuation(Integer self, Integer p): r""" - Return the p-adic valuation of ``self``. + Return the `p`-adic valuation of ``self``. We do not require that p be prime, but it must be at least 2. For more documentation see ``valuation`` @@ -4236,7 +4225,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): cdef object _val_unit(Integer self, Integer p): r""" - Return a pair: the p-adic valuation of ``self``, and the p-adic unit + Return a pair: the `p`-adic valuation of ``self``, and the `p`-adic unit of ``self``. We do not require the p be prime, but it must be at least 2. For @@ -4261,11 +4250,11 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def valuation(self, p): """ - Return the p-adic valuation of ``self``. + Return the `p`-adic valuation of ``self``. INPUT: - - ``p`` -- an integer at least 2. + - ``p`` -- integer at least 2 EXAMPLES:: @@ -4297,9 +4286,9 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``p`` -- a prime integer. + - ``p`` -- prime integer - OUTPUT: Largest power of ``p`` dividing ``self``. + OUTPUT: largest power of ``p`` dividing ``self`` EXAMPLES:: @@ -4322,18 +4311,18 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def val_unit(self, p): r""" - Return a pair: the p-adic valuation of ``self``, and the p-adic unit + Return a pair: the `p`-adic valuation of ``self``, and th`p`-adicic unit of ``self``. INPUT: - - ``p`` -- an integer at least 2. + - ``p`` -- integer at least 2 OUTPUT: - - ``v_p(self)`` -- the p-adic valuation of ``self`` + - ``v_p(self)`` -- the `p`-adic valuation of ``self`` - - ``u_p(self)`` -- ``self`` / `p^{v_p(\mathrm{self})}` + - ``u_p(self)`` -- ``self`` / `p^{v_p(\mathrm{self})}` EXAMPLES:: @@ -4360,7 +4349,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): Currently returns 0 when ``self`` is 0. This behaviour is fairly arbitrary, and in Sage 4.6 this special case was not handled at all, eventually - propagating a TypeError. The caller should not rely on the behaviour + propagating a :exc:`TypeError`. The caller should not rely on the behaviour in case ``self`` is 0. EXAMPLES:: @@ -4529,7 +4518,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): r""" Return the factorial `n! = 1 \cdot 2 \cdot 3 \cdots n`. - If the input does not fit in an ``unsigned long int``, an :class:`OverflowError` + If the input does not fit in an ``unsigned long int``, an :exc:`OverflowError` is raised. EXAMPLES:: @@ -4544,22 +4533,22 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): 5 120 6 720 - Large integers raise an :class:`OverflowError`:: + Large integers raise an :exc:`OverflowError`:: sage: (2**64).factorial() Traceback (most recent call last): ... OverflowError: argument too large for factorial - And negative ones a :class:`ValueError`:: + And negative ones a :exc:`ValueError`:: sage: (-1).factorial() Traceback (most recent call last): ... - ValueError: factorial only defined for non-negative integers + ValueError: factorial only defined for nonnegative integers """ if mpz_sgn(self.value) < 0: - raise ValueError("factorial only defined for non-negative integers") + raise ValueError("factorial only defined for nonnegative integers") if not mpz_fits_ulong_p(self.value): raise OverflowError("argument too large for factorial") @@ -4574,15 +4563,15 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def multifactorial(self, long k): r""" - Compute the k-th factorial `n!^{(k)}` of ``self``. + Compute the `k`-th factorial `n!^{(k)}` of ``self``. - The multifactorial number `n!^{(k)}` is defined for non-negative + The multifactorial number `n!^{(k)}` is defined for nonnegative integers `n` as follows. For `k=1` this is the standard factorial, and for `k` greater than `1` it is the product of every `k`-th terms down from `n` to `1`. The recursive definition is used to extend this function to the negative integers `n`. - This function uses direct call to GMP if `k` and `n` are non-negative + This function uses direct call to GMP if `k` and `n` are nonnegative and uses simple transformation for other cases. EXAMPLES:: @@ -4608,7 +4597,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): ... ValueError: multifactorial undefined - When entries are too large an :class:`OverflowError` is raised:: + When entries are too large an :exc:`OverflowError` is raised:: sage: (2**64).multifactorial(2) Traceback (most recent call last): @@ -4616,7 +4605,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): OverflowError: argument too large for multifactorial """ if k <= 0: - raise ValueError("multifactorial only defined for non-positive k") + raise ValueError("multifactorial only defined for nonpositive k") if not mpz_fits_slong_p(self.value): raise OverflowError("argument too large for multifactorial") @@ -4626,7 +4615,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): cdef Integer z if n >= 0: - # non-negative n: call native GMP functions + # nonnegative n: call native GMP functions z = PY_NEW(Integer) if k == 1: mpz_fac_ui(z.value, n) @@ -4656,7 +4645,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def gamma(self): r""" The gamma function on integers is the factorial function (shifted by - one) on positive integers, and `\pm \infty` on non-positive integers. + one) on positive integers, and `\pm \infty` on nonpositive integers. EXAMPLES:: @@ -4677,7 +4666,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def floor(self): """ - Return the floor of ``self``, which is just self since ``self`` is an + Return the floor of ``self``, which is just ``self`` since ``self`` is an integer. EXAMPLES:: @@ -4714,7 +4703,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): """ return self - def round(Integer self, mode="away"): + def round(Integer self, mode='away'): """ Return the nearest integer to ``self``, which is ``self`` since ``self`` is an integer. @@ -4802,7 +4791,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def is_integer(self): """ - Return ``True`` as they are integers + Return ``True`` as they are integers. EXAMPLES:: @@ -4906,8 +4895,8 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default RealField precision). + - ``prec`` -- integer; desired floating point precision (default: + default RealField precision) OUTPUT: @@ -4938,7 +4927,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): cdef bint _is_power_of(Integer self, Integer n) noexcept: r""" - Return a non-zero int if there is an integer b with + Return a nonzero int if there is an integer b with `\mathtt{self} = n^b`. For more documentation see :meth:`is_power_of`. @@ -5163,12 +5152,12 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``proof`` -- Boolean or ``None`` (default). If ``False``, use a strong + - ``proof`` -- boolean or ``None`` (default). If ``False``, use a strong pseudo-primality test (see :meth:`is_pseudoprime`). If ``True``, use a provable primality test. If unset, use the default arithmetic proof flag. - - ``get_data`` -- (default ``False``), if ``True`` return a pair + - ``get_data`` -- (default: ``False``), if ``True`` return a pair ``(p,k)`` such that this integer equals ``p^k`` with ``p`` a prime and ``k`` a positive integer or the pair ``(self,0)`` otherwise. @@ -5313,7 +5302,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``proof`` -- Boolean or ``None`` (default). If ``False``, use a + - ``proof`` -- boolean or ``None`` (default). If ``False``, use a strong pseudo-primality test (see :meth:`is_pseudoprime`). If ``True``, use a provable primality test. If unset, use the :mod:`default arithmetic proof flag `. @@ -5414,9 +5403,9 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``self`` -- A PARI pseudoprime + - ``self`` -- a PARI pseudoprime - - ``proof`` -- Mandatory proof flag (``True``, ``False`` or ``None``) + - ``proof`` -- mandatory proof flag (``True``, ``False`` or ``None``) OUTPUT: @@ -5486,9 +5475,9 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``get_data`` -- (default ``False``) if ``True`` return a pair `(p,k)` + - ``get_data`` -- (default: ``False``) if ``True`` return a pair `(p,k)` such that this number equals `p^k` with `p` a pseudoprime and `k` a - positive integer or the pair ``(self,0)`` otherwise. + positive integer or the pair ``(self,0)`` otherwise EXAMPLES:: @@ -5689,10 +5678,10 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``self`` -- an integer congruent to `0` or `1` mod `4` which is + - ``self`` -- integer congruent to `0` or `1` mod `4` which is not a square - - ``proof`` (boolean, default ``True``) -- if ``False``, then + - ``proof`` -- boolean (default: ``True``); if ``False``, then for negative discriminants a faster algorithm is used by the PARI library which is known to give incorrect results when the class group has many cyclic factors. However, the @@ -5763,10 +5752,10 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def squarefree_part(self, long bound=-1): r""" - Return the square free part of `x` (=self), i.e., the unique integer + Return the square free part of `x` (=``self``), i.e., the unique integer `z` that `x = z y^2`, with `y^2` a perfect square and `z` square-free. - Use ``self.radical()`` for the product of the primes that divide self. + Use ``self.radical()`` for the product of the primes that divide ``self``. If ``self`` is 0, just returns 0. @@ -5872,9 +5861,9 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``proof`` -- bool or None (default: None, see - ``proof.arithmetic`` or :mod:`sage.structure.proof`) Note that the global Sage - default is ``proof=True`` + - ``proof`` -- boolean or ``None`` (default: ``None``, see + ``proof.arithmetic`` or :mod:`sage.structure.proof`); note that the + global Sage default is ``proof=True`` EXAMPLES:: @@ -6228,7 +6217,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): sage: m = n.__pari__() # crash from trac 875 # needs sage.libs.pari sage: m % 1234567 # needs sage.libs.pari 1041334 - """ global new_gen_from_integer if new_gen_from_integer is None: @@ -6354,7 +6342,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): r""" Return `(s, r)` where `s` is the integer square root of ``self`` and `r` is the remainder such that `\text{self} = s^2 + r`. - Raises :class:`ValueError` if ``self`` is negative. + Raises :exc:`ValueError` if ``self`` is negative. EXAMPLES:: @@ -6371,7 +6359,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): Traceback (most recent call last): ... ValueError: square root of negative integer not defined - """ if mpz_sgn(self.value) < 0: raise ValueError("square root of negative integer not defined") @@ -6383,7 +6370,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def isqrt(self): r""" Return the integer floor of the square root of ``self``, or raises an - :class:`ValueError` if ``self`` is negative. + :exc:`ValueError` if ``self`` is negative. EXAMPLES:: @@ -6415,17 +6402,17 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``prec`` -- integer (default: ``None``): if ``None``, return an exact - square root; otherwise return a numerical square root, to the - given bits of precision. + - ``prec`` -- integer (default: ``None``); if ``None``, return an exact + square root; otherwise return a numerical square root, to the + given bits of precision. - - ``extend`` -- bool (default: ``True``); if ``True``, return a - square root in an extension ring, if necessary. Otherwise, raise a - :class:`ValueError` if the square is not in the base ring. Ignored if ``prec`` - is not ``None``. + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the square is not in the base ring. Ignored if + ``prec`` is not ``None``. - - ``all`` -- bool (default: ``False``); if ``True``, return all - square roots of ``self`` (a list of length 0, 1, or 2). + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of ``self`` (a list of length 0, 1, or 2) EXAMPLES:: @@ -6518,11 +6505,11 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: - A triple ``(g, s, t)`` such that ``g`` is the non-negative gcd of + A triple ``(g, s, t)`` such that ``g`` is the nonnegative gcd of ``self`` and ``n``, and ``s`` and ``t`` are cofactors satisfying the Bezout identity @@ -6541,7 +6528,6 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): sage: 6.xgcd(4) (2, 1, -1) - """ return self._xgcd(n) @@ -6551,15 +6537,15 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``n`` -- an integer - - ``minimal`` -- a boolean (default: ``False``), whether to compute + - ``n`` -- integer + - ``minimal`` -- boolean (default: ``False``); whether to compute minimal cofactors (see below) OUTPUT: - A triple ``(g, s, t)`` such that ``g`` is the non-negative gcd of + A triple ``(g, s, t)`` such that ``g`` is the nonnegative gcd of ``self`` and ``n``, and ``s`` and ``t`` are cofactors satisfying the - Bezout identity + Bezout identity. .. MATH:: @@ -6640,7 +6626,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): # Note: the GMP documentation for mpz_gcdext (or mpn_gcdext for that # matter) makes absolutely no claims about any minimality conditions - # satisfied by the returned cofactors. They guarantee a non-negative + # satisfied by the returned cofactors. They guarantee a nonnegative # gcd, but that's it. So we have to do some work ourselves. if not minimal: @@ -6889,7 +6875,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): def inverse_of_unit(self): """ Return inverse of ``self`` if ``self`` is a unit in the integers, i.e., - ``self`` is `-1` or `1`. Otherwise, raise a :class:`ZeroDivisionError`. + ``self`` is `-1` or `1`. Otherwise, raise a :exc:`ZeroDivisionError`. EXAMPLES:: @@ -6915,18 +6901,18 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): r""" Return the inverse of ``self`` modulo `n`, if this inverse exists. - Otherwise, raise a :class:`ZeroDivisionError` exception. + Otherwise, raise a :exc:`ZeroDivisionError` exception. INPUT: - - ``self`` -- Integer + - ``self`` -- integer - - ``n`` -- Integer, or ideal of integer ring + - ``n`` -- integer or ideal of integer ring OUTPUT: - - ``x`` -- Integer such that x\*self = 1 (mod m), or - raises ZeroDivisionError. + - ``x`` -- integer such that x * ``self`` = 1 (mod m), or + raises :exc:`ZeroDivisionError` IMPLEMENTATION: @@ -7076,7 +7062,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``m`` -- an integer + - ``m`` -- integer - ``algorithm`` -- ``'gmp'`` (default), ``'mpir'`` (an alias for ``gmp``), or ``'pari'``; ``'gmp'`` is faster for small ``m``, @@ -7173,7 +7159,7 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): else: raise ValueError("algorithm must be one of: 'pari' or 'gmp' (alias: 'mpir')") - def to_bytes(self, length=1, byteorder="big", is_signed=False): + def to_bytes(self, length=1, byteorder='big', is_signed=False): r""" Return an array of bytes representing an integer. @@ -7181,10 +7167,10 @@ cdef class Integer(sage.structure.element.EuclideanDomainElement): INPUT: - - ``length`` -- positive integer (default: ``1``); integer is represented in - ``length`` bytes - - ``byteorder`` -- str (default: ``"big"``); determines the byte order of - the output; can only be ``"big"`` or ``"little"`` + - ``length`` -- positive integer (default: 1); integer represented + in ``length`` bytes + - ``byteorder`` -- string (default: ``'big'``); determines the byte + order of the output (can only be ``'big'`` or ``'little'``) - ``is_signed`` -- boolean (default: ``False``); determines whether to use two's compliment to represent the integer @@ -7213,17 +7199,16 @@ cdef int mpz_set_str_python(mpz_ptr z, char* s, int base) except -1: Wrapper around ``mpz_set_str()`` which supports :pep:`3127` literals. - If the string is invalid, a ``TypeError`` will be raised. + If the string is invalid, a :exc:`TypeError` will be raised. INPUT: - - ``z`` -- A pre-allocated ``mpz_t`` where the result will be - stored. + - ``z`` -- a pre-allocated ``mpz_t`` where the result will be stored - - ``s`` -- A string to be converted to an ``mpz_t``. + - ``s`` -- string to be converted to an ``mpz_t`` - - ``base`` -- Either 0 or a base between 2 and 36: a base to use - for the string conversion. 0 means auto-detect using prefixes. + - ``base`` -- either 0 or a base between 2 and 36: a base to use + for the string conversion. 0 means auto-detect using prefixes EXAMPLES:: @@ -7809,7 +7794,7 @@ cdef double mpz_get_d_nearest(mpz_t x) except? -648555075988944.5: pass else: if not remainder_is_zero: - # Remainder is non-zero: round away from zero + # Remainder is nonzero: round away from zero q64 += 1 else: # Halfway case: round to even diff --git a/src/sage/rings/integer_ring.pyx b/src/sage/rings/integer_ring.pyx index a1574d00756..2b2ec33294c 100644 --- a/src/sage/rings/integer_ring.pyx +++ b/src/sage/rings/integer_ring.pyx @@ -614,18 +614,16 @@ cdef class IntegerRing_class(CommutativeRing): INPUT: - - ``x``, ``y`` integers -- bounds for the result. + - ``x``, ``y`` integers -- bounds for the result - - ``distribution`` -- a string: + - ``distribution`` -- string: - ``'uniform'`` - ``'mpz_rrandomb'`` - ``'1/n'`` - ``'gaussian'`` - OUTPUT: - - - With no input, return a random integer. + OUTPUT: with no input, return a random integer If only one integer `x` is given, return an integer between 0 and `x-1`. @@ -687,9 +685,9 @@ cdef class IntegerRing_class(CommutativeRing): ....: return 1/5 sage: dic = defaultdict(Integer) sage: counter = 0.0 - sage: add_samples(distribution="uniform") + sage: add_samples(distribution='uniform') sage: while any(abs(dic[i]/counter - prob(i)) > 0.01 for i in dic): - ....: add_samples(distribution="uniform") + ....: add_samples(distribution='uniform') Here we use the distribution ``'1/n'``:: @@ -699,9 +697,9 @@ cdef class IntegerRing_class(CommutativeRing): ....: return 2/(5*abs(n)*(abs(n) + 1)) sage: dic = defaultdict(Integer) sage: counter = 0.0 - sage: add_samples(distribution="1/n") + sage: add_samples(distribution='1/n') sage: while any(abs(dic[i]/counter - prob(i)) > 0.01 for i in dic): - ....: add_samples(distribution="1/n") + ....: add_samples(distribution='1/n') If a range is given, the default distribution is uniform in that range:: @@ -736,25 +734,25 @@ cdef class IntegerRing_class(CommutativeRing): We return a sample from a discrete Gaussian distribution:: - sage: ZZ.random_element(11.0, distribution="gaussian").parent() is ZZ # needs sage.modules + sage: ZZ.random_element(11.0, distribution='gaussian').parent() is ZZ # needs sage.modules True TESTS: Check that :issue:`32124` is fixed:: - sage: ZZ.random_element(5, -5, distribution="1/n").parent() is ZZ + sage: ZZ.random_element(5, -5, distribution='1/n').parent() is ZZ True - sage: ZZ.random_element(5, -5, distribution="gaussian").parent() is ZZ # needs sage.modules + sage: ZZ.random_element(5, -5, distribution='gaussian').parent() is ZZ # needs sage.modules True - sage: ZZ.random_element(5, -5, distribution="mpz_rrandomb").parent() is ZZ + sage: ZZ.random_element(5, -5, distribution='mpz_rrandomb').parent() is ZZ True - sage: ZZ.random_element(-10, -5, distribution="mpz_rrandomb") + sage: ZZ.random_element(-10, -5, distribution='mpz_rrandomb') Traceback (most recent call last): ... TypeError: x must be > 0 - sage: ZZ.random_element(-10, -5, distribution="gaussian") + sage: ZZ.random_element(-10, -5, distribution='gaussian') Traceback (most recent call last): ... TypeError: x must be > 0 @@ -832,7 +830,7 @@ cdef class IntegerRing_class(CommutativeRing): r = _prev_discrete_gaussian_integer_sampler[1]() else: from sage.stats.distributions.discrete_gaussian_integer import DiscreteGaussianDistributionIntegerSampler - D = DiscreteGaussianDistributionIntegerSampler(sigma=x, algorithm="uniform+logtable") + D = DiscreteGaussianDistributionIntegerSampler(sigma=x, algorithm='uniform+logtable') r = D() _prev_discrete_gaussian_integer_sampler = (x, D) mpz_set(value, r.value) @@ -841,7 +839,7 @@ cdef class IntegerRing_class(CommutativeRing): def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): r""" - Tests whether the map from `\ZZ` to codomain, which takes the + Test whether the map from `\ZZ` to codomain, which takes the generator of `\ZZ` to ``im_gens[0]``, is a ring homomorphism. (This amounts to checking that 1 goes to 1.) @@ -909,13 +907,13 @@ cdef class IntegerRing_class(CommutativeRing): INPUT: - - ``poly`` -- a list of one or more polynomials + - ``poly`` -- list of one or more polynomials - ``names`` -- a parameter which will be passed to - :func:`EquationOrder`. + :func:`EquationOrder` - ``embedding`` -- a parameter which will be passed to - :func:`EquationOrder`. + :func:`EquationOrder` OUTPUT: @@ -958,7 +956,7 @@ cdef class IntegerRing_class(CommutativeRing): """ if isinstance(I, sage.rings.integer.Integer): n = I - elif sage.rings.ideal.is_Ideal(I): + elif isinstance(I, sage.rings.ideal.Ideal_generic): if not (I.ring() is self): raise TypeError("I must be an ideal of ZZ") n = I.gens()[0] @@ -977,12 +975,12 @@ cdef class IntegerRing_class(CommutativeRing): - ``prime`` -- a prime number - - ``check`` -- (boolean, default ``True``) whether or not + - ``check`` -- boolean (default: ``True``); whether or not to check the primality of prime - ``names`` -- ignored (for compatibility with number fields) - OUTPUT: The residue field at this prime. + OUTPUT: the residue field at this prime EXAMPLES:: @@ -1027,7 +1025,7 @@ cdef class IntegerRing_class(CommutativeRing): """ if isinstance(prime, sage.rings.integer.Integer): p = self.ideal(prime) - elif sage.rings.ideal.is_Ideal(prime): + elif isinstance(prime, sage.rings.ideal.Ideal_generic): if not (prime.ring() is self): raise TypeError("%s is not an ideal of ZZ" % prime) p = prime @@ -1059,10 +1057,10 @@ cdef class IntegerRing_class(CommutativeRing): INPUT: - - ``n`` (default: 0) -- In a ring with more than one generator, the + - ``n`` -- (default: 0) in a ring with more than one generator, the optional parameter `n` indicates which generator to return; since there is only one generator in this case, the only valid value for - `n` is 0. + `n` is 0 EXAMPLES:: @@ -1171,11 +1169,9 @@ cdef class IntegerRing_class(CommutativeRing): - ``prec`` -- the desired precision - ``extras`` -- any further parameters to pass to the method used to - create the completion. - - OUTPUT: + create the completion - - The completion of `\ZZ` at `p`. + OUTPUT: the completion of `\ZZ` at `p` EXAMPLES:: @@ -1209,7 +1205,7 @@ cdef class IntegerRing_class(CommutativeRing): INPUT: - - ``n`` -- (default 2) a positive integer + - ``n`` -- (default: 2) a positive integer OUTPUT: @@ -1265,7 +1261,7 @@ cdef class IntegerRing_class(CommutativeRing): - ``multiplicities`` -- boolean (default: ``True``); whether to compute the multiplicities - - ``algorithm`` -- ``"dense"``, ``"sparse"`` or ``None`` (default: + - ``algorithm`` -- ``'dense'``, ``'sparse'`` or ``None`` (default: ``None``); the algorithm to use OUTPUT: @@ -1278,14 +1274,14 @@ cdef class IntegerRing_class(CommutativeRing): ALGORITHM: - If ``algorithm`` is ``"dense"`, the roots are computed using + If ``algorithm`` is ``'dense'``, the roots are computed using :meth:`_roots_from_factorization`. - If ``algorithm`` is ``"sparse"``, the roots are computed using the + If ``algorithm`` is ``'sparse'``, the roots are computed using the algorithm described in [CKS1999]_. - If ``algorithm`` is ``None``, use the ``"dense"`` algorithm for - polynomials of degree at most `100`, and ``"sparse"`` otherwise. + If ``algorithm`` is ``None``, use the ``'dense'`` algorithm for + polynomials of degree at most `100`, and ``'sparse'`` otherwise. .. NOTE:: @@ -1319,19 +1315,19 @@ cdef class IntegerRing_class(CommutativeRing): [(100, 1), (-5445, 5), (1, 23), (-1, 23)] sage: ZZ._roots_univariate_polynomial(p, multiplicities=False) [100, -5445, 1, -1] - sage: ZZ._roots_univariate_polynomial(p, algorithm="sparse") + sage: ZZ._roots_univariate_polynomial(p, algorithm='sparse') [(100, 1), (-5445, 5), (1, 23), (-1, 23)] - sage: ZZ._roots_univariate_polynomial(p, algorithm="dense") + sage: ZZ._roots_univariate_polynomial(p, algorithm='dense') [(100, 1), (-5445, 5), (1, 23), (-1, 23)] - sage: ZZ._roots_univariate_polynomial(p, algorithm="foobar") + sage: ZZ._roots_univariate_polynomial(p, algorithm='foobar') Traceback (most recent call last): ... ValueError: unknown algorithm 'foobar' sage: p = x^20 * p # needs sage.libs.pari - sage: ZZ._roots_univariate_polynomial(p, algorithm="sparse") # needs sage.libs.pari + sage: ZZ._roots_univariate_polynomial(p, algorithm='sparse') # needs sage.libs.pari [(0, 20), (100, 1), (-5445, 5), (1, 23), (-1, 23)] - sage: ZZ._roots_univariate_polynomial(p, algorithm="dense") # needs sage.libs.pari + sage: ZZ._roots_univariate_polynomial(p, algorithm='dense') # needs sage.libs.pari [(100, 1), (-5445, 5), (0, 20), (1, 23), (-1, 23)] """ deg = p.degree() @@ -1529,7 +1525,6 @@ cdef class IntegerRing_class(CommutativeRing): sage: polymake(ZZ) # optional - jupymake # indirect doctest Integer - """ return '"Integer"' @@ -1578,12 +1573,11 @@ cdef class IntegerRing_class(CommutativeRing): :meth:`Order.valuation() `, :meth:`RationalField.valuation() ` - """ from sage.rings.padics.padic_valuation import pAdicValuation return pAdicValuation(self, p) - def from_bytes(self, input_bytes, byteorder="big", is_signed=False): + def from_bytes(self, input_bytes, byteorder='big', is_signed=False): r""" Return the integer represented by the given array of bytes. @@ -1592,8 +1586,8 @@ cdef class IntegerRing_class(CommutativeRing): INPUT: - ``input_bytes`` -- a bytes-like object or iterable producing bytes - - ``byteorder`` -- str (default: ``"big"``); determines the byte order of - ``input_bytes``; can only be ``"big"`` or ``"little"`` + - ``byteorder`` -- string (default: ``'big'``); determines the byte order of + ``input_bytes`` (can only be ``'big'`` or ``'little'``) - ``is_signed`` -- boolean (default: ``False``); determines whether to use two's compliment to represent the integer @@ -1640,14 +1634,14 @@ def crt_basis(X, xgcd=None): INPUT: - - ``X`` -- a list of Integers that are coprime in pairs. + - ``X`` -- list of Integers that are coprime in pairs - - ``xgcd`` -- an optional parameter which is ignored. + - ``xgcd`` -- an optional parameter which is ignored OUTPUT: - - ``E`` -- a list of Integers such that ``E[i] = 1`` (mod ``X[i]``) and - ``E[i] = 0`` (mod ``X[j]``) for all `j \neq i`. + - ``E`` -- list of Integers such that ``E[i] = 1`` (mod ``X[i]``) and + ``E[i] = 0`` (mod ``X[j]``) for all `j \neq i` For this explanation, let ``E[i]`` be denoted by `E_i`. diff --git a/src/sage/rings/invariants/invariant_theory.py b/src/sage/rings/invariants/invariant_theory.py index cda4138d5e4..dc370bdf560 100644 --- a/src/sage/rings/invariants/invariant_theory.py +++ b/src/sage/rings/invariants/invariant_theory.py @@ -125,7 +125,7 @@ def _guess_variables(polynomial, *args): INPUT: - ``polynomial`` -- a polynomial, or a list/tuple of polynomials - in the same polynomial ring. + in the same polynomial ring - ``*args`` -- the variables. If none are specified, all variables in ``polynomial`` are returned. If a list or tuple is passed, @@ -177,10 +177,10 @@ def transvectant(f, g, h=1, scale='default'): INPUT: - - ``f``, ``g`` -- two homogeneous binary forms in the same polynomial ring. + - ``f``, ``g`` -- two homogeneous binary forms in the same polynomial ring - - ``h`` -- the order of the transvectant. If it is not specified, - the first transvectant is returned. + - ``h`` -- the order of the transvectant; if it is not specified, + the first transvectant is returned - ``scale`` -- the scaling factor applied to the result. Possible values are ``'default'`` and ``'none'``. The ``'default'`` scaling factor is @@ -336,9 +336,7 @@ def _jacobian_determinant(self, *args): homogeneous degree. Must be a covariant, that is, polynomial in the given :meth:`variables` - OUTPUT: - - The Jacobian determinant with respect to the variables. + OUTPUT: the Jacobian determinant with respect to the variables EXAMPLES:: @@ -424,10 +422,8 @@ def is_homogeneous(self): """ Return whether the forms were defined by homogeneous polynomials. - OUTPUT: - - Boolean. Whether the user originally defined the form via - homogeneous variables. + OUTPUT: boolean; whether the user originally defined the form via + homogeneous variables EXAMPLES:: @@ -462,14 +458,14 @@ class AlgebraicForm(FormsBase): INPUT: - - ``n`` -- The number of variables. + - ``n`` -- the number of variables - - ``d`` -- The degree of the polynomial. + - ``d`` -- the degree of the polynomial - - ``polynomial`` -- The polynomial. + - ``polynomial`` -- the polynomial - - ``*args`` -- The variables, as a single list/tuple, multiple - arguments, or ``None`` to use all variables of the polynomial. + - ``*args`` -- the variables, as a single list/tuple, multiple + arguments, or ``None`` to use all variables of the polynomial Derived classes must implement the same arguments for the constructor. @@ -578,8 +574,8 @@ def _check_covariant(self, method_name, g=None, invariant=False): INPUT: - - ``method_name`` -- string. The name of the method that - returns the invariant / covariant to test. + - ``method_name`` -- string; the name of the method that + returns the invariant / covariant to test - ``g`` -- an `SL(n,\CC)` matrix or ``None`` (default). The test will be to check that the covariant transforms @@ -587,8 +583,8 @@ def _check_covariant(self, method_name, g=None, invariant=False): the homogeneous variables. If ``None``, a random matrix will be picked. - - ``invariant`` -- boolean. Whether to additionally test that - it is an invariant. + - ``invariant`` -- boolean; whether to additionally test that + it is an invariant EXAMPLES:: @@ -644,9 +640,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -688,9 +682,7 @@ def form(self): """ Return the defining polynomial. - OUTPUT: - - The polynomial used to define the algebraic form. + OUTPUT: the polynomial used to define the algebraic form EXAMPLES:: @@ -712,7 +704,7 @@ def homogenized(self, var='h'): INPUT: - ``var`` -- either a variable name, variable index or a - variable (default: ``'h'``). + variable (default: ``'h'``) OUTPUT: @@ -768,8 +760,8 @@ def _extract_coefficients(self, monomials): - ``polynomial`` -- the input polynomial - - ``monomials`` -- a list of all the monomials in the polynomial - ring. If less monomials are passed, an exception is thrown. + - ``monomials`` -- list of all the monomials in the polynomial + ring; if less monomials are passed, an exception is thrown OUTPUT: @@ -892,9 +884,9 @@ def transformed(self, g): INPUT: - ``g`` -- a `GL(n,\CC)` matrix or a dictionary with the - variables as keys. A matrix is used to define the linear - transformation of homogeneous variables, a dictionary acts - by substitution of the variables. + variables as keys. A matrix is used to define the linear + transformation of homogeneous variables, a dictionary acts + by substitution of the variables. OUTPUT: @@ -994,12 +986,10 @@ def from_invariants(cls, discriminant, x, z, *args, **kwargs): INPUT: - - ``discriminant`` -- Value of the discriminant used to reconstruct - the binary quadratic. - - OUTPUT: + - ``discriminant`` -- value of the discriminant used to reconstruct + the binary quadratic - A QuadraticForm with 2 variables. + OUTPUT: a QuadraticForm with 2 variables EXAMPLES:: @@ -1108,7 +1098,7 @@ def scaled_coeffs(self): @cached_method def matrix(self): r""" - Return the quadratic form as a symmetric matrix + Return the quadratic form as a symmetric matrix. OUTPUT: @@ -1181,12 +1171,10 @@ def invariants(self, type='discriminant'): INPUT: - - ``type`` -- The type of invariants to return. The default choice - is to return the discriminant. + - ``type`` -- the type of invariants to return; the default choice + is to return the discriminant - OUTPUT: - - The invariants of the binary quadratic. + OUTPUT: the invariants of the binary quadratic EXAMPLES:: @@ -1199,7 +1187,6 @@ def invariants(self, type='discriminant'): Traceback (most recent call last): ... ValueError: unknown type of invariants unknown for a binary quadratic - """ if type == 'discriminant': return (self.discriminant(),) @@ -1439,9 +1426,7 @@ def EisensteinD(self): r""" One of the Eisenstein invariants of a binary quartic. - OUTPUT: - - The Eisenstein D-invariant of the quartic. + OUTPUT: the Eisenstein D-invariant of the quartic .. MATH:: @@ -1468,9 +1453,7 @@ def EisensteinE(self): r""" One of the Eisenstein invariants of a binary quartic. - OUTPUT: - - The Eisenstein E-invariant of the quartic. + OUTPUT: the Eisenstein E-invariant of the quartic .. MATH:: @@ -1497,9 +1480,7 @@ def g_covariant(self): r""" The g-covariant of a binary quartic. - OUTPUT: - - The g-covariant of the quartic. + OUTPUT: the g-covariant of the quartic .. MATH:: @@ -1548,9 +1529,7 @@ def h_covariant(self): r""" The h-covariant of a binary quartic. - OUTPUT: - - The h-covariant of the quartic. + OUTPUT: the h-covariant of the quartic .. MATH:: @@ -1680,12 +1659,10 @@ def from_invariants(cls, invariants, x, z, *args, **kwargs): INPUT: - - ``invariants`` -- A list or tuple of invariants that are used to - reconstruct the binary quintic. - - OUTPUT: + - ``invariants`` -- list or tuple of invariants that are used to + reconstruct the binary quintic - A BinaryQuintic. + OUTPUT: a BinaryQuintic EXAMPLES:: @@ -1797,9 +1774,7 @@ def H_covariant(self, as_form=False): as polynomial (default). If it is ``True`` the result is returned as an object of the class :class:`AlgebraicForm`. - OUTPUT: - - The `H`-covariant of the binary quintic as polynomial or as binary form. + OUTPUT: the `H`-covariant of the binary quintic as polynomial or as binary form EXAMPLES:: @@ -1834,9 +1809,7 @@ def i_covariant(self, as_form=False): as polynomial (default). If it is ``True`` the result is returned as an object of the class :class:`AlgebraicForm`. - OUTPUT: - - The `i`-covariant of the binary quintic as polynomial or as binary form. + OUTPUT: the `i`-covariant of the binary quintic as polynomial or as binary form EXAMPLES:: @@ -1868,9 +1841,7 @@ def T_covariant(self, as_form=False): as polynomial (default). If it is ``True`` the result is returned as an object of the class :class:`AlgebraicForm`. - OUTPUT: - - The `T`-covariant of the binary quintic as polynomial or as binary form. + OUTPUT: the `T`-covariant of the binary quintic as polynomial or as binary form EXAMPLES:: @@ -1907,9 +1878,7 @@ def j_covariant(self, as_form=False): as polynomial (default). If it is ``True`` the result is returned as an object of the class :class:`AlgebraicForm`. - OUTPUT: - - The `j`-covariant of the binary quintic as polynomial or as binary form. + OUTPUT: the `j`-covariant of the binary quintic as polynomial or as binary form EXAMPLES:: @@ -2185,9 +2154,7 @@ def A_invariant(self): """ Return the invariant `A` of a binary quintic. - OUTPUT: - - The `A`-invariant of the binary quintic. + OUTPUT: the `A`-invariant of the binary quintic EXAMPLES:: @@ -2213,9 +2180,7 @@ def B_invariant(self): """ Return the invariant `B` of a binary quintic. - OUTPUT: - - The `B`-invariant of the binary quintic. + OUTPUT: the `B`-invariant of the binary quintic EXAMPLES:: @@ -2245,9 +2210,7 @@ def C_invariant(self): """ Return the invariant `C` of a binary quintic. - OUTPUT: - - The `C`-invariant of the binary quintic. + OUTPUT: the `C`-invariant of the binary quintic EXAMPLES:: @@ -2276,9 +2239,7 @@ def R_invariant(self): """ Return the invariant `R` of a binary quintic. - OUTPUT: - - The `R`-invariant of the binary quintic. + OUTPUT: the `R`-invariant of the binary quintic EXAMPLES:: @@ -2310,12 +2271,10 @@ def invariants(self, type='clebsch'): INPUT: - - ``type`` -- The type of invariants to return. The default choice - is to return the Clebsch invariants. - - OUTPUT: + - ``type`` -- the type of invariants to return; the default choice + is to return the Clebsch invariants - The invariants of the binary quintic. + OUTPUT: the invariants of the binary quintic EXAMPLES:: @@ -2331,7 +2290,6 @@ def invariants(self, type='clebsch'): Traceback (most recent call last): ... ValueError: unknown type of invariants unknown for a binary quintic - """ if type == 'clebsch': return self.clebsch_invariants(as_tuple=True) @@ -2348,9 +2306,7 @@ def clebsch_invariants(self, as_tuple=False): The following invariants are returned: `A`, `B`, `C` and `R`. - OUTPUT: - - The Clebsch invariants of the binary quintic. + OUTPUT: the Clebsch invariants of the binary quintic EXAMPLES:: @@ -2368,7 +2324,6 @@ def clebsch_invariants(self, as_tuple=False): 4983526016/390625, -247056495846408/244140625, -148978972828696847376/30517578125) - """ if self._ring.characteristic() in [2, 3, 5]: raise NotImplementedError('no invariants implemented for fields ' @@ -2396,9 +2351,7 @@ def arithmetic_invariants(self): of the Clebsch invariants, such that they still generate the ring of invariants. - OUTPUT: - - The arithmetic invariants of the binary quintic. They are given by + OUTPUT: the arithmetic invariants of the binary quintic. They are given by .. MATH:: @@ -2433,7 +2386,6 @@ def arithmetic_invariants(self): sage: invs = quintic.arithmetic_invariants() sage: [invs[x].content() for x in invs] [1, 1, 1, 1] - """ R = self._ring clebsch = self.clebsch_invariants() @@ -2459,10 +2411,10 @@ def canonical_form(self, reduce_gcd=False): INPUT: - - ``reduce_gcd`` -- If set to ``True``, then a variant of this canonical + - ``reduce_gcd`` -- if set to ``True``, then a variant of this canonical form is computed where the coefficients are coprime integers. The - obtained form is then unique up to multiplication by a unit. - See also :meth:`~sage.rings.invariants.reconstruction.binary_quintic_from_invariants`'. + obtained form is then unique up to multiplication by a unit. See also + :meth:`~sage.rings.invariants.reconstruction.binary_quintic_from_invariants`'. OUTPUT: @@ -2495,14 +2447,14 @@ def canonical_form(self, reduce_gcd=False): def _covariant_conic(A_scaled_coeffs, B_scaled_coeffs, monomials): """ - Helper function for :meth:`TernaryQuadratic.covariant_conic` + Helper function for :meth:`TernaryQuadratic.covariant_conic`. INPUT: - - ``A_scaled_coeffs``, ``B_scaled_coeffs`` -- The scaled - coefficients of the two ternary quadratics. + - ``A_scaled_coeffs``, ``B_scaled_coeffs`` -- the scaled + coefficients of the two ternary quadratics - - ``monomials`` -- The monomials :meth:`~TernaryQuadratic.monomials`. + - ``monomials`` -- the monomials :meth:`~TernaryQuadratic.monomials` OUTPUT: @@ -2656,7 +2608,7 @@ def covariant_conic(self, other): INPUT: - - ``other`` -- Another ternary quadratic. + - ``other`` -- another ternary quadratic OUTPUT: @@ -3102,7 +3054,7 @@ class SeveralAlgebraicForms(FormsBase): INPUT: - - ``forms`` -- a list/tuple/iterable of at least one + - ``forms`` -- list/tuple/iterable of at least one :class:`AlgebraicForm` object, all with the same number of variables. Interpreted as multiple homogeneous polynomials in a common polynomial ring. @@ -3244,7 +3196,7 @@ def homogenized(self, var='h'): INPUT: - ``var`` -- either a variable name, variable index or a - variable (default: ``'h'``). + variable (default: ``'h'``) OUTPUT: @@ -3275,8 +3227,8 @@ def _check_covariant(self, method_name, g=None, invariant=False): INPUT: - - ``method_name`` -- string. The name of the method that - returns the invariant / covariant to test. + - ``method_name`` -- string; the name of the method that + returns the invariant / covariant to test - ``g`` -- a `SL(n,\CC)` matrix or ``None`` (default). The test will be to check that the covariant transforms @@ -3284,8 +3236,8 @@ def _check_covariant(self, method_name, g=None, invariant=False): the homogeneous variables. If ``None``, a random matrix will be picked. - - ``invariant`` -- boolean. Whether to additionally test that - it is an invariant. + - ``invariant`` -- boolean; whether to additionally test that + it is an invariant EXAMPLES:: @@ -3327,9 +3279,7 @@ def first(self): """ Return the first of the two forms. - OUTPUT: - - The first algebraic form used in the definition. + OUTPUT: the first algebraic form used in the definition EXAMPLES:: @@ -3351,9 +3301,7 @@ def second(self): """ Return the second of the two forms. - OUTPUT: - - The second form used in the definition. + OUTPUT: the second form used in the definition EXAMPLES:: @@ -3564,7 +3512,7 @@ def syzygy(self, Delta, Theta, Theta_prime, Delta_prime, S, S_prime, F, J): 0 If the arguments are not the invariants and covariants then - the output is some (generically non-zero) polynomial:: + the output is some (generically nonzero) polynomial:: sage: biquadratic.syzygy(1, 1, 1, 1, 1, 1, 1, x) 1/64*x^2 + 1 @@ -3600,8 +3548,8 @@ class TwoQuaternaryQuadratics(TwoAlgebraicForms): REFERENCES: - - section on "Invariants and Covariants of - Systems of Quadrics" in [Sal1958]_, [Sal1965]_ + - section on "Invariants and Covariants of + Systems of Quadrics" in [Sal1958]_, [Sal1965]_ TESTS:: @@ -3948,7 +3896,7 @@ def syzygy(self, Delta, Theta, Phi, Theta_prime, Delta_prime, U, V, T, T_prime, 0 If the arguments are not the invariants and covariants then - the output is some (generically non-zero) polynomial:: + the output is some (generically nonzero) polynomial:: sage: biquadratic.syzygy(1, 1, 1, 1, 1, 1, 1, 1, 1, x) -x^2 + 1 @@ -4032,9 +3980,7 @@ def __repr__(self): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -4049,7 +3995,7 @@ def quadratic_form(self, polynomial, *args): INPUT: - - ``polynomial`` -- a homogeneous or inhomogeneous quadratic form. + - ``polynomial`` -- a homogeneous or inhomogeneous quadratic form - ``*args`` -- the variables as multiple arguments, or as a single list/tuple. If the last argument is ``None``, the @@ -4094,10 +4040,10 @@ def inhomogeneous_quadratic_form(self, polynomial, *args): INPUT: - - ``polynomial`` -- an inhomogeneous quadratic form. + - ``polynomial`` -- an inhomogeneous quadratic form - ``*args`` -- the variables as multiple arguments, or as a - single list/tuple. + single list/tuple EXAMPLES:: @@ -4123,7 +4069,7 @@ def binary_quadratic(self, quadratic, *args): INPUT: - - ``quadratic`` -- a quadratic form. + - ``quadratic`` -- a quadratic form - ``x``, ``y`` -- the homogeneous variables. If ``y`` is ``None``, the quadratic is assumed to be inhomogeneous. @@ -4150,11 +4096,10 @@ def quaternary_quadratic(self, quadratic, *args): INPUT: - - ``quadratic`` -- a quadratic form. + - ``quadratic`` -- a quadratic form - ``w``, ``x``, ``y``, ``z`` -- the homogeneous variables. If - ``z`` is ``None``, the quadratic is assumed to be - inhomogeneous. + ``z`` is ``None``, the quadratic is assumed to be inhomogeneous. REFERENCES: @@ -4199,7 +4144,7 @@ def binary_quartic(self, quartic, *args, **kwds): INPUT: - - ``quartic`` -- a quartic. + - ``quartic`` -- a quartic - ``x``, ``y`` -- the homogeneous variables. If ``y`` is ``None``, the quartic is assumed to be inhomogeneous. @@ -4286,17 +4231,17 @@ def binary_form_from_invariants(self, degree, invariants, variables=None, as_for INPUT: - - ``degree`` -- The degree of the binary form. + - ``degree`` -- the degree of the binary form - - ``invariants`` -- A list or tuple of values of the invariants of the - binary form. + - ``invariants`` -- list or tuple of values of the invariants of the + binary form - - ``variables`` -- A list or tuple of two variables that are used for + - ``variables`` -- list or tuple of two variables that are used for the resulting form (only if ``as_form`` is ``True``). If no variables are provided, two abstract variables ``x`` and ``z`` will be used. - - ``as_form`` -- boolean. If ``False``, the function will return a tuple - of coefficients of a binary form. + - ``as_form`` -- boolean; if ``False``, the function will return a tuple + of coefficients of a binary form OUTPUT: @@ -4309,7 +4254,7 @@ def binary_form_from_invariants(self, degree, invariants, variables=None, as_for based on the value of the discriminant. See also :meth:`binary_quadratic_coefficients_from_invariants` and :meth:`binary_cubic_coefficients_from_invariants`. These methods will always return the - same result if the discriminant is non-zero:: + same result if the discriminant is nonzero:: sage: discriminant = 1 sage: invariant_theory.binary_form_from_invariants(2, [discriminant]) @@ -4318,7 +4263,7 @@ def binary_form_from_invariants(self, degree, invariants, variables=None, as_for (0, 1, -1, 0) For binary cubics, there is no class implemented yet, so ``as_form=True`` - will yield an ``NotImplementedError``:: + will yield a :exc:`NotImplementedError`:: sage: invariant_theory.binary_form_from_invariants(3, [discriminant]) Traceback (most recent call last): @@ -4457,7 +4402,7 @@ def ternary_quadratic(self, quadratic, *args, **kwds): INPUT: - ``quadratic`` -- a homogeneous quadratic in 3 homogeneous - variables, or an inhomogeneous quadratic in 2 variables. + variables, or an inhomogeneous quadratic in 2 variables - ``x``, ``y``, ``z`` -- the variables. If ``z`` is ``None``, the quadratic is assumed to be inhomogeneous. @@ -4533,7 +4478,7 @@ def ternary_cubic(self, cubic, *args, **kwds): INPUT: - ``cubic`` -- a homogeneous cubic in 3 homogeneous variables, - or an inhomogeneous cubic in 2 variables. + or an inhomogeneous cubic in 2 variables - ``x``, ``y``, ``z`` -- the variables. If ``z`` is ``None``, the cubic is assumed to be inhomogeneous. diff --git a/src/sage/rings/invariants/reconstruction.py b/src/sage/rings/invariants/reconstruction.py index 8e98ad3f20f..907538889ad 100644 --- a/src/sage/rings/invariants/reconstruction.py +++ b/src/sage/rings/invariants/reconstruction.py @@ -26,10 +26,10 @@ def binary_quadratic_coefficients_from_invariants(discriminant, invariant_choice INPUT: - - ``discriminant`` -- The value of the discriminant of the - binary quadratic. + - ``discriminant`` -- the value of the discriminant of the + binary quadratic - - ``invariant_choice`` -- The type of invariants provided. The accepted + - ``invariant_choice`` -- the type of invariants provided. The accepted options are ``'discriminant'`` and ``'default'``, which are the same. No other options are implemented. @@ -67,10 +67,10 @@ def binary_cubic_coefficients_from_invariants(discriminant, invariant_choice='de INPUT: - - ``discriminant`` -- The value of the discriminant of the - binary cubic. + - ``discriminant`` -- the value of the discriminant of the + binary cubic - - ``invariant_choice`` -- The type of invariants provided. The accepted + - ``invariant_choice`` -- the type of invariants provided. The accepted options are ``'discriminant'`` and ``'default'``, which are the same. No other options are implemented. @@ -113,17 +113,17 @@ def binary_quintic_coefficients_from_invariants(invariants, K=None, invariant_ch INPUT: - - ``invariants`` -- A list or tuple of values of the three or four + - ``invariants`` -- list or tuple of values of the three or four invariants. The default option requires the Clebsch invariants `A`, `B`, `C` and `R` of the binary quintic. - - ``K`` -- The field over which the quintic is defined. + - ``K`` -- the field over which the quintic is defined - - ``invariant_choice`` -- The type of invariants provided. The accepted + - ``invariant_choice`` -- the type of invariants provided. The accepted options are ``'clebsch'`` and ``'default'``, which are the same. No other options are implemented. - - ``scaling`` -- How the coefficients should be scaled. The accepted + - ``scaling`` -- how the coefficients should be scaled. The accepted values are ``'none'`` for no scaling, ``'normalized'`` to scale in such a way that the resulting coefficients are independent of the scaling of the input invariants and ``'coprime'`` which scales the input invariants @@ -136,7 +136,7 @@ def binary_quintic_coefficients_from_invariants(invariants, K=None, invariant_ch EXAMPLES: - First we check the general case, where the invariant `M` is non-zero:: + First we check the general case, where the invariant `M` is nonzero:: sage: R. = QQ[] sage: p = 3*x1^5 + 6*x1^4*x0 + 3*x1^3*x0^2 + 4*x1^2*x0^3 - 5*x1*x0^4 + 4*x0^5 @@ -363,9 +363,9 @@ def _reduce_invariants(invariants, weights): INPUT: - - ``invariants`` -- The values of the invariants. + - ``invariants`` -- the values of the invariants - - ``weights`` -- The respective weights of the invariants. + - ``weights`` -- the respective weights of the invariants OUTPUT: diff --git a/src/sage/rings/laurent_series_ring.py b/src/sage/rings/laurent_series_ring.py index e2b03bcca58..ed2e4a9c3cf 100644 --- a/src/sage/rings/laurent_series_ring.py +++ b/src/sage/rings/laurent_series_ring.py @@ -218,7 +218,7 @@ def __classcall__(cls, *args, **kwds): def __init__(self, power_series): """ - Initialization + Initialization. EXAMPLES:: @@ -284,8 +284,8 @@ def __init__(self, power_series): def base_extend(self, R): """ Return the Laurent series ring over R in the same variable as - self, assuming there is a canonical coerce map from the base ring - of self to R. + ``self``, assuming there is a canonical coerce map from the base ring + of ``self`` to R. EXAMPLES:: @@ -304,7 +304,7 @@ def fraction_field(self): If the base ring is a field, then Laurent series are already a field. If the base ring is a domain, then the Laurent series over its fraction - field is returned. Otherwise, raise a ``ValueError``. + field is returned. Otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -405,7 +405,7 @@ def _element_constructor_(self, x, n=0, prec=infinity): - ``n`` -- (default: 0) multiply the result by `t^n` - ``prec`` -- (default: ``infinity``) the precision of the series - as an integer. + as an integer EXAMPLES:: @@ -678,13 +678,13 @@ def _coerce_map_from_(self, P): from sage.rings.polynomial.laurent_polynomial_ring_base import ( LaurentPolynomialRing_generic, ) - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.power_series_ring import is_PowerSeriesRing if ((is_LaurentSeriesRing(P) or isinstance(P, LaurentPolynomialRing_generic) or is_PowerSeriesRing(P) or - is_PolynomialRing(P)) + isinstance(P, PolynomialRing_general)) and P.variable_name() == self.variable_name() and A.has_coerce_map_from(P.base_ring())): return True @@ -712,7 +712,7 @@ def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): False """ # NOTE: There are no ring homomorphisms from the ring of - # all formal power series to most rings, e.g, the p-adic + # all formal power series to most rings, e.g, the `p`-adic # field, since you can always (mathematically!) construct # some power series that does not converge. # NOTE: The above claim is wrong when the base ring is Z. diff --git a/src/sage/rings/laurent_series_ring_element.pyx b/src/sage/rings/laurent_series_ring_element.pyx index f03ad5a3fd5..405752c6191 100644 --- a/src/sage/rings/laurent_series_ring_element.pyx +++ b/src/sage/rings/laurent_series_ring_element.pyx @@ -78,6 +78,10 @@ from sage.misc.derivative import multi_derivative def is_LaurentSeries(x): + from sage.misc.superseded import deprecation_cython + deprecation_cython(38266, + "The function is_LaurentSeries is deprecated; " + "use 'isinstance(..., LaurentSeries)' instead.") return isinstance(x, LaurentSeries) @@ -231,7 +235,7 @@ cdef class LaurentSeries(AlgebraElement): def is_monomial(self): """ - Return ``True`` if this element is a monomial. That is, if self is + Return ``True`` if this element is a monomial. That is, if ``self`` is `x^n` for some integer `n`. EXAMPLES:: @@ -403,7 +407,7 @@ cdef class LaurentSeries(AlgebraElement): 5*x^-1 + 3 + 2*x """ if n == 0: - raise ValueError('n must be non zero') + raise ValueError('n must be nonzero') if n < 0: if not self.prec() is infinity: @@ -626,7 +630,7 @@ cdef class LaurentSeries(AlgebraElement): def exponents(self): """ - Return the exponents appearing in self with nonzero coefficients. + Return the exponents appearing in ``self`` with nonzero coefficients. EXAMPLES:: @@ -662,7 +666,7 @@ cdef class LaurentSeries(AlgebraElement): INPUT: - - ``absprec`` -- an integer or ``None`` (default: ``None``), the + - ``absprec`` -- integer or ``None`` (default: ``None``); the absolute precision of the result. If ``None``, lifts to an exact element. @@ -954,7 +958,6 @@ cdef class LaurentSeries(AlgebraElement): sage: h = x^2 + 2*x^4 + x^6 sage: h^(1/2) x + x^3 - """ cdef LaurentSeries self = _self @@ -986,7 +989,7 @@ cdef class LaurentSeries(AlgebraElement): def shift(self, k): r""" - Returns this Laurent series multiplied by the power `t^n`. + Return this Laurent series multiplied by the power `t^n`. Does not change this series. .. NOTE:: @@ -1026,7 +1029,7 @@ cdef class LaurentSeries(AlgebraElement): def truncate(self, long n): r""" Return the Laurent series of degree ` < n` which is - equivalent to self modulo `x^n`. + equivalent to ``self`` modulo `x^n`. EXAMPLES:: @@ -1069,7 +1072,7 @@ cdef class LaurentSeries(AlgebraElement): This is equivalent to:: - self - self.truncate(n) + ``self - self.truncate(n)`` EXAMPLES:: @@ -1402,7 +1405,7 @@ cdef class LaurentSeries(AlgebraElement): ``precision`` is not given, then the precision of the reverse defaults to the default precision of ``f.parent()``. - Note that this is only possible if the valuation of self is exactly + Note that this is only possible if the valuation of ``self`` is exactly 1. The implementation depends on the underlying power series element diff --git a/src/sage/rings/lazy_series.py b/src/sage/rings/lazy_series.py index 4aab7395464..5573e6a399d 100644 --- a/src/sage/rings/lazy_series.py +++ b/src/sage/rings/lazy_series.py @@ -411,22 +411,22 @@ def __getitem__(self, n): def coefficients(self, n=None): r""" - Return the first `n` non-zero coefficients of ``self``. + Return the first `n` nonzero coefficients of ``self``. INPUT: - - ``n`` -- (optional) the number of non-zero coefficients to return + - ``n`` -- (optional) the number of nonzero coefficients to return - If the series has fewer than `n` non-zero coefficients, only + If the series has fewer than `n` nonzero coefficients, only these are returned. If ``n`` is ``None``, a :class:`~sage.misc.lazy_list.lazy_list_generic` with all - non-zero coefficients is returned instead. + nonzero coefficients is returned instead. .. WARNING:: - If there are fewer than `n` non-zero coefficients, but + If there are fewer than `n` nonzero coefficients, but this cannot be detected, this method will not return. EXAMPLES:: @@ -434,7 +434,7 @@ def coefficients(self, n=None): sage: L. = LazyPowerSeriesRing(QQ) sage: f = L([1,2,3]) sage: f.coefficients(5) - doctest:...: DeprecationWarning: the method coefficients now only returns the non-zero coefficients. Use __getitem__ instead. + doctest:...: DeprecationWarning: the method coefficients now only returns the nonzero coefficients. Use __getitem__ instead. See https://github.com/sagemath/sage/issues/32367 for details. [1, 2, 3] @@ -460,7 +460,7 @@ def coefficients(self, n=None): return [] from itertools import repeat, chain, islice from sage.misc.lazy_list import lazy_list - # prepare a generator of the non-zero coefficients + # prepare a generator of the nonzero coefficients P = self.parent() if isinstance(coeff_stream, Stream_exact): if coeff_stream._constant: @@ -480,7 +480,7 @@ def coefficients(self, n=None): if isinstance(self, LazyPowerSeries) and self.parent()._arity == 1: from sage.misc.superseded import deprecation - deprecation(32367, 'the method coefficients now only returns the non-zero coefficients. Use __getitem__ instead.') + deprecation(32367, 'the method coefficients now only returns the nonzero coefficients. Use __getitem__ instead.') if P._internal_poly_ring.base_ring() is not P._laurent_poly_ring: return list(islice(coeffs, n)) @@ -574,7 +574,6 @@ def map_coefficients(self, f): sage: f = z + z^2 + z^3 sage: f.map_coefficients(lambda c: c + 1) 2*z + 2*z^2 + 2*z^3 - """ P = self.parent() coeff_stream = self._coeff_stream @@ -1025,7 +1024,7 @@ def _richcmp_(self, other, op): def __hash__(self): """ - Return the hash of ``self`` + Return the hash of ``self``. TESTS:: @@ -1179,8 +1178,8 @@ def is_nonzero(self, proof=False): INPUT: - - ``proof`` -- (default: ``False``) if ``True``, this will also return - an index such that ``self`` has a nonzero coefficient + - ``proof`` -- boolean (default: ``False``); if ``True``, this will + also return an index such that ``self`` has a nonzero coefficient .. WARNING:: @@ -2697,7 +2696,6 @@ def arcsinh(self): sage: L. = LazyLaurentSeriesRing(SR); x = var("x") # needs sage.symbolic sage: asinh(z)[0:6] == asinh(x).series(x, 6).coefficients(sparse=False) # needs sage.symbolic True - """ from .lazy_series_ring import LazyLaurentSeriesRing P = LazyLaurentSeriesRing(self.base_ring(), "z", sparse=self.parent()._sparse) @@ -2735,7 +2733,6 @@ def arctanh(self): sage: L. = LazyLaurentSeriesRing(SR); x = var("x") # needs sage.symbolic sage: atanh(z)[0:6] == atanh(x).series(x, 6).coefficients(sparse=False) # needs sage.symbolic True - """ from .lazy_series_ring import LazyLaurentSeriesRing P = LazyLaurentSeriesRing(self.base_ring(), "z", sparse=self.parent()._sparse) @@ -2770,7 +2767,6 @@ def hypergeometric(self, a, b): sage: L. = LazyLaurentSeriesRing(SR); x = var("x") # needs sage.symbolic sage: z.hypergeometric([1,1],[1])[0:6] == hypergeometric([1,1],[1], x).series(x, 6).coefficients(sparse=False) # needs sage.symbolic True - """ from .lazy_series_ring import LazyLaurentSeriesRing from sage.arith.misc import rising_factorial @@ -3834,8 +3830,8 @@ def __call__(self, g): composition `(f \circ g)(z) = f(g(z))` is defined if and only if: - `g = 0` and `\mathrm{val}(f) \geq 0`, - - `g` is non-zero and `f` has only finitely many non-zero coefficients, - - `g` is non-zero and `\mathrm{val}(g) > 0`. + - `g` is nonzero and `f` has only finitely many nonzero coefficients, + - `g` is nonzero and `\mathrm{val}(g) > 0`. INPUT: @@ -4031,7 +4027,7 @@ def __call__(self, g): ZeroDivisionError: the valuation of the series must be nonnegative `g \neq 0` and `\mathrm{val}(g) \leq 0` and `f` has infinitely many - non-zero coefficients:: + nonzero coefficients:: sage: g = z^-1 + z^-2 sage: g.valuation() <= 0 @@ -4122,7 +4118,6 @@ def __call__(self, g): sage: g = L([2]) sage: f(g) 0 - """ # Find a good parent for the result from sage.structure.element import get_coercion_model @@ -4139,7 +4134,7 @@ def __call__(self, g): and isinstance(g._coeff_stream, Stream_zero))): if self._coeff_stream._approximate_order >= 0: return P(self[0]) - # Perhaps we just don't yet know if the valuation is non-negative + # Perhaps we just don't yet know if the valuation is nonnegative if any(self._coeff_stream[i] for i in range(self._coeff_stream._approximate_order, 0)): raise ZeroDivisionError("the valuation of the series must be nonnegative") self._coeff_stream._approximate_order = 0 @@ -4705,7 +4700,7 @@ def approximate_series(self, prec, name=None): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer - ``name`` -- name of the variable; if it is ``None``, the name of the variable of the series is used @@ -4765,7 +4760,7 @@ def polynomial(self, degree=None, name=None): If ``degree`` is not ``None``, the terms of the series of degree greater than ``degree`` are first truncated. If ``degree`` is ``None`` and the series is not a polynomial or - a Laurent polynomial, a ``ValueError`` is raised. + a Laurent polynomial, a :exc:`ValueError` is raised. EXAMPLES:: @@ -4806,7 +4801,6 @@ def polynomial(self, degree=None, name=None): sage: L.zero().polynomial() 0 - """ S = self.parent() @@ -4937,7 +4931,7 @@ def exponential(self): def compute_coefficients(self, i): r""" - Computes all the coefficients of ``self`` up to ``i``. + Compute all the coefficients of ``self`` up to ``i``. This method is deprecated, it has no effect anymore. @@ -4976,7 +4970,6 @@ def _im_gens_(self, codomain, im_gens, base_map=None): sage: f = 1/(1+x*q-t) sage: f._im_gens_(S, [s, x*s], base_map=cc) 1 + 2*x*s + 4*x^2*s^2 + 8*x^3*s^3 + 16*x^4*s^4 + 32*x^5*s^5 + 64*x^6*s^6 + O(s^7) - """ if base_map is None: return codomain(self(*im_gens)) @@ -5628,7 +5621,7 @@ def adams_operator(self, p): INPUT: - - ``p`` -- a positive integer + - ``p`` -- positive integer EXAMPLES: @@ -6012,7 +6005,7 @@ def polynomial(self, degree=None, names=None): If ``degree`` is not ``None``, the terms of the series of degree greater than ``degree`` are first truncated. If ``degree`` is ``None`` and the series is not a polynomial - polynomial, a ``ValueError`` is raised. + polynomial, a :exc:`ValueError` is raised. EXAMPLES:: @@ -6401,16 +6394,16 @@ def __call__(self, *args): - `g_i = 0`, or - setting all alphabets except the `i`-th in `f` to zero yields a symmetric function with only finitely many - non-zero coefficients, or + nonzero coefficients, or - `\mathrm{val}(g) > 0`. If `f` is a univariate 'exact' lazy symmetric function, we - can check whether `f` has only finitely many non-zero + can check whether `f` has only finitely many nonzero coefficients. However, if `f` has larger arity, we have no way to test whether setting all but one alphabets of `f` to zero yields a polynomial, except if `f` itself is 'exact' and therefore a symmetric function with only finitely many - non-zero coefficients. + nonzero coefficients. INPUT: @@ -6669,7 +6662,6 @@ def revert(self): - Andrew Gainer-Dewar - Martin Rubey - """ P = self.parent() if P._arity != 1: @@ -6833,7 +6825,7 @@ def derivative_with_respect_to_p1(self, n=1): def suspension(self): r""" - Return the suspension of `self``. + Return the suspension of ``self``. This is an involution, that maps the homogeneous component `f_n` of degree `n` to `(-1)^{n - 1} \omega(f_n)`, where @@ -6919,7 +6911,7 @@ def functorial_composition(self, *args): sage: P.functorial_composition(P2)[4].coefficient([2,2])[3] # needs sage.libs.pari sage.modules 8 - labellings of their vertices with two 1's and two 2's. + labellings of their vertices with two 1s and two 2s. The symmetric function `h_1 \sum_n h_n` is the neutral element with respect to functorial composition:: @@ -7103,9 +7095,7 @@ def arithmetic_product(self, *args): - ``g`` -- a cycle index series having the same parent as ``self`` - OUTPUT: - - The arithmetic product of ``self`` with ``g``. + OUTPUT: the arithmetic product of ``self`` with ``g`` .. SEEALSO:: @@ -7195,7 +7185,6 @@ def arithmetic_product(self, *args): sage: L = LazySymmetricFunctions(s) # needs sage.modules sage: L(s([2])).arithmetic_product(s([1,1,1])) # needs sage.modules s[2, 2, 1, 1] + s[3, 1, 1, 1] + s[3, 2, 1] + s[3, 3] - """ if len(args) != self.parent()._arity: raise ValueError("arity must be equal to the number of arguments provided") @@ -7281,7 +7270,7 @@ def symmetric_function(self, degree=None): If ``degree`` is not ``None``, the terms of the series of degree greater than ``degree`` are first truncated. If ``degree`` is ``None`` and the series is not a polynomial - polynomial, a ``ValueError`` is raised. + polynomial, a :exc:`ValueError` is raised. EXAMPLES:: @@ -7319,7 +7308,6 @@ def symmetric_function(self, degree=None): 0 sage: f4.symmetric_function(0) # needs lrcalc_python s[] - """ S = self.parent() R = S._laurent_poly_ring @@ -7506,13 +7494,13 @@ def __invert__(self): O(1/(8^z)) Trying to invert a non-invertible 'exact' series raises a - ``ZeroDivisionError``:: + :exc:`ZeroDivisionError`:: sage: f = ~L([0,1], constant=1) sage: f[1] Traceback (most recent call last): ... - ZeroDivisionError: the Dirichlet inverse only exists if the coefficient with index 1 is non-zero + ZeroDivisionError: the Dirichlet inverse only exists if the coefficient with index 1 is nonzero sage: f = ~L(lambda n: n-1) sage: f[1] diff --git a/src/sage/rings/lazy_series_ring.py b/src/sage/rings/lazy_series_ring.py index 6f96ffc839d..2e54ce22cd0 100644 --- a/src/sage/rings/lazy_series_ring.py +++ b/src/sage/rings/lazy_series_ring.py @@ -122,8 +122,8 @@ def _element_constructor_(self, x=None, valuation=None, degree=None, constant=No INPUT: - ``x`` -- data used to the define a series - - ``valuation`` -- integer (optional); integer; a lower bound for - the valuation of the series + - ``valuation`` -- integer (optional); a lower bound for the valuation + of the series - ``degree`` -- (optional) the degree when the series is ``constant`` - ``constant`` -- (optional) the eventual constant of the series - ``coefficients`` -- (optional) a callable that defines the @@ -738,7 +738,6 @@ def one(self): sage: L = LazySymmetricFunctions(m) # needs sage.modules sage: L.one() # needs sage.modules m[] - """ R = self.base_ring() coeff_stream = Stream_exact([R.one()], constant=R.zero(), order=0) @@ -919,9 +918,9 @@ def prod(self, f, a=None, b=infinity, add_one=False): INPUT: - - ``f`` -- a list (or iterable) of elements of ``self`` + - ``f`` -- list (or iterable) of elements of ``self`` - ``a``, ``b`` -- optional arguments - - ``add_one`` -- (default: ``False``); if ``True``, then converts a + - ``add_one`` -- (default: ``False``) if ``True``, then converts a lazy series `p_i` from ``args`` into `1 + p_i` for the product If ``a`` and ``b`` are both integers, then this returns the product @@ -1019,7 +1018,7 @@ def sum(self, f, a=None, b=infinity): INPUT: - - ``f`` -- a list (or iterable or function) of elements of ``self`` + - ``f`` -- list (or iterable or function) of elements of ``self`` - ``a``, ``b`` -- optional arguments If ``a`` and ``b`` are both integers, then this returns the sum @@ -1245,7 +1244,7 @@ class LazyLaurentSeriesRing(LazySeriesRing): - ``base_ring`` -- base ring - ``names`` -- name of the generator - - ``sparse`` -- (default: ``True``) whether the implementation of + - ``sparse`` -- boolean (default: ``True``); whether the implementation of the series is sparse or not EXAMPLES:: @@ -1392,7 +1391,7 @@ class LazyLaurentSeriesRing(LazySeriesRing): False We additionally provide two other methods of performing comparisons. - The first is raising a ``ValueError`` and the second uses a check + The first is raising a :exc:`ValueError` and the second uses a check up to a (user set) finite precision. These behaviors are set using the options ``secure`` and ``halting_precision``. In particular, this applies to series that are not specified by a finite number @@ -1400,7 +1399,7 @@ class LazyLaurentSeriesRing(LazySeriesRing): Equality checking will depend on the coefficients which have already been computed. If this information is not enough to check that two series are different, then if ``L.options.secure`` - is set to ``True``, then we raise a ``ValueError``:: + is set to ``True``, then we raise a :exc:`ValueError`:: sage: L.options.secure = True sage: f = 1 / (z + z^2); f @@ -1963,7 +1962,7 @@ class LazyPowerSeriesRing(LazySeriesRing): - ``base_ring`` -- base ring of this Taylor series ring - ``names`` -- name(s) of the generator of this Taylor series ring - - ``sparse`` -- (default: ``True``) whether this series is sparse or not + - ``sparse`` -- boolean (default: ``True``); whether this series is sparse or not EXAMPLES:: @@ -1987,14 +1986,14 @@ def __init__(self, base_ring, names, sparse=True, category=None): sage: LazyPowerSeriesRing.options.halting_precision(12) sage: L = LazyPowerSeriesRing(ZZ, 't') - sage: TestSuite(L).run(skip="_test_fraction_field") + sage: TestSuite(L).run(skip='_test_fraction_field') sage: L = LazyPowerSeriesRing(ZZ, 's, t') - sage: TestSuite(L).run(skip="_test_fraction_field") + sage: TestSuite(L).run(skip='_test_fraction_field') sage: L = LazyPowerSeriesRing(QQ, 't') - sage: TestSuite(L).run(skip="_test_fraction_field") + sage: TestSuite(L).run(skip='_test_fraction_field') sage: L = LazyPowerSeriesRing(QQ, 's, t') - sage: TestSuite(L).run(skip="_test_fraction_field") + sage: TestSuite(L).run(skip='_test_fraction_field') sage: L = LazyPowerSeriesRing(GF(5), 't') sage: TestSuite(L).run() @@ -2008,14 +2007,14 @@ def __init__(self, base_ring, names, sparse=True, category=None): sage: TestSuite(L).run(skip=['_test_revert']) sage: L = LazyPowerSeriesRing(QQ['q'], 't') - sage: TestSuite(L).run(skip="_test_fraction_field") + sage: TestSuite(L).run(skip='_test_fraction_field') sage: L = LazyPowerSeriesRing(QQ['q'], 's, t') - sage: TestSuite(L).run(skip="_test_fraction_field") # long time + sage: TestSuite(L).run(skip='_test_fraction_field') # long time sage: L = LazyPowerSeriesRing(ZZ['q'], 't') - sage: TestSuite(L).run(skip="_test_fraction_field") + sage: TestSuite(L).run(skip='_test_fraction_field') sage: L = LazyPowerSeriesRing(ZZ['q'], 's, t') - sage: TestSuite(L).run(skip="_test_fraction_field") # long time + sage: TestSuite(L).run(skip='_test_fraction_field') # long time sage: LazyPowerSeriesRing.options._reset() # reset the options @@ -2182,15 +2181,17 @@ def _element_constructor_(self, x=None, valuation=None, constant=None, degree=No INPUT: - ``x`` -- data used to the define a Taylor series - - ``valuation`` -- integer (optional); integer; a lower bound for the valuation of the series + - ``valuation`` -- integer (optional); a lower bound for the valuation + of the series - ``constant`` -- (optional) the eventual constant of the series - ``degree`` -- (optional) the degree when the series is ``constant`` - - ``check`` -- (optional) check that coefficients are homogeneous of the correct degree when they are retrieved + - ``check`` -- (optional) check that coefficients are homogeneous of + the correct degree when they are retrieved .. WARNING:: The behaviour of ``LazyPowerSeries(c)`` for a list ``c`` - with non-zero last element `e` changed with + with nonzero last element `e` changed with :issue:`32367`. To obtain the old behaviour, use ``LazyPowerSeries(c, constant=e)``. @@ -2297,11 +2298,10 @@ def _element_constructor_(self, x=None, valuation=None, constant=None, degree=No Traceback (most recent call last): ... ValueError: coefficients must be homogeneous polynomials of the correct degree - """ if valuation is not None: if valuation < 0: - raise ValueError("the valuation of a Taylor series must be non-negative") + raise ValueError("the valuation of a Taylor series must be nonnegative") # TODO: the following is nonsense, think of an iterator if self._arity > 1: raise ValueError("valuation must not be specified for multivariate Taylor series") @@ -2641,7 +2641,7 @@ class LazyCompletionGradedAlgebra(LazySeriesRing): - ``basis`` -- a graded algebra - ``names`` -- name(s) of the alphabets - - ``sparse`` -- (default: ``True``) whether we use a sparse or + - ``sparse`` -- boolean (default: ``True``); whether we use a sparse or a dense representation EXAMPLES:: @@ -2798,8 +2798,8 @@ def _element_constructor_(self, x=None, valuation=None, degree=None, constant=No INPUT: - ``x`` -- data used to the define a lazy element - - ``valuation`` -- integer (optional); integer; a lower bound for - the valuation of the series + - ``valuation`` -- integer (optional); a lower bound for the valuation + of the series - ``degree`` -- (optional) the degree when the lazy element has finite support - ``check`` -- (optional) check that coefficients are homogeneous of @@ -3012,7 +3012,6 @@ def some_elements(self): sage: L = S.formal_series_ring() sage: L.some_elements()[:4] [0, S[], 2*S[] + 2*S[1] + (3*S[1,1]), 2*S[1] + (3*S[1,1])] - """ elt = self.an_element() elts = [self.zero(), self.one(), elt] @@ -3045,7 +3044,8 @@ class LazySymmetricFunctions(LazyCompletionGradedAlgebra): - ``basis`` -- the ring of symmetric functions - ``names`` -- name(s) of the alphabets - - ``sparse`` -- (default: ``True``) whether we use a sparse or a dense representation + - ``sparse`` -- boolean (default: ``True``); whether we use a sparse or a + dense representation EXAMPLES:: @@ -3072,7 +3072,7 @@ class LazyDirichletSeriesRing(LazySeriesRing): - ``base_ring`` -- base ring of this Dirichlet series ring - ``names`` -- name of the generator of this Dirichlet series ring - - ``sparse`` -- (default: ``True``) whether this series is sparse or not + - ``sparse`` -- boolean (default: ``True``); whether this series is sparse or not Unlike formal univariate Laurent/power series (over a field), the ring of formal Dirichlet series is not a @@ -3164,7 +3164,6 @@ def __init__(self, base_ring, names, sparse=True, category=None): sage: TestSuite(L).run() # needs sage.symbolic sage: LazyDirichletSeriesRing.options._reset() # reset the options - """ if base_ring.characteristic() > 0: raise ValueError("positive characteristic not allowed for Dirichlet series") @@ -3234,8 +3233,8 @@ def _element_constructor_(self, x=None, valuation=None, degree=None, constant=No INPUT: - ``x`` -- data used to the define a Dirichlet series - - ``valuation`` -- integer (optional); integer; a lower bound for - the exp of the valuation of the series + - ``valuation`` -- integer (optional); a lower bound for the exp of the + valuation of the series - ``degree`` -- (optional) the degree when the series is ``constant`` - ``constant`` -- (optional) the eventual constant of the series diff --git a/src/sage/rings/localization.py b/src/sage/rings/localization.py index e19d814b55d..be1fc217a8d 100644 --- a/src/sage/rings/localization.py +++ b/src/sage/rings/localization.py @@ -195,11 +195,10 @@ def normalize_extra_units(base_ring, add_units, warning=True): - ``base_ring`` -- an instance of :class:`IntegralDomain` - ``add_units`` -- list of elements from base ring - - ``warning`` -- (default: ``True``) to suppress a warning which is thrown if no normalization was possible + - ``warning`` -- boolean (default: ``True``); to suppress a warning which + is thrown if no normalization was possible - OUTPUT: - - List of all prime factors of the elements of the given list. + OUTPUT: list of all prime factors of the elements of the given list EXAMPLES:: @@ -251,13 +250,13 @@ def normalize_extra_units(base_ring, add_units, warning=True): class LocalizationElement(IntegralDomainElement): """ - Element class for localizations of integral domains + Element class for localizations of integral domains. INPUT: - ``parent`` -- instance of :class:`Localization` - - ``x`` -- instance of :class:`FractionFieldElement` whose parent is the fraction - field of the parent's base ring + - ``x`` -- instance of :class:`FractionFieldElement` whose parent is the + fraction field of the parent's base ring EXAMPLES:: @@ -527,9 +526,7 @@ def _rational_(self): This is only possible if its base ring is the ring of integers. - OUTPUT: - - A rational. + OUTPUT: a rational TESTS:: @@ -550,9 +547,7 @@ def _integer_(self, Z=None): This is only possible if its base ring is the ring of integers and the denominator of ``self`` is one. - OUTPUT: - - An integer. + OUTPUT: integer TESTS:: @@ -568,32 +563,40 @@ def _integer_(self, Z=None): class Localization(IntegralDomain, UniqueRepresentation): r""" - The localization generalizes the construction of the field of fractions of an integral domain to - an arbitrary ring. Given a (not necessarily commutative) ring `R` and a subset `S` of `R`, - there exists a ring `R[S^{-1}]` together with the ring homomorphism `R \longrightarrow R[S^{-1}]` - that "inverts" `S`; that is, the homomorphism maps elements in `S` to unit elements in `R[S^{-1}]` - and, moreover, any ring homomorphism from `R` that "inverts" `S` uniquely factors through `R[S^{-1}]`. - - The ring `R[S^{-1}]` is called the *localization* of `R` with respect to `S`. For example, if `R` is - a commutative ring and `f` an element in `R`, then the localization consists of elements of the form - `r/f, r\in R, n \geq 0` (to be precise, `R[f^{-1}] = R[t]/(ft-1)`. - - The above text is taken from `Wikipedia`. The construction here used for this class relies on the - construction of the field of fraction and is therefore restricted to integral domains. - - Accordingly, this class is inherited from :class:`IntegralDomain` and can only be used in that context. - Furthermore, the base ring should support :meth:`sage.structure.element.CommutativeRingElement.divides` and - the exact division operator `//` (:meth:`sage.structure.element.Element.__floordiv__`) in order to guarantee - a successful application. + The localization generalizes the construction of the field of fractions of + an integral domain to an arbitrary ring. Given a (not necessarily + commutative) ring `R` and a subset `S` of `R`, there exists a ring + `R[S^{-1}]` together with the ring homomorphism `R \longrightarrow R[S^{-1}]` + that "inverts" `S`; that is, the homomorphism maps elements in `S` to unit + elements in `R[S^{-1}]` and, moreover, any ring homomorphism from `R` that + "inverts" `S` uniquely factors through `R[S^{-1}]`. + + The ring `R[S^{-1}]` is called the *localization* of `R` with respect to + `S`. For example, if `R` is a commutative ring and `f` an element in `R`, + then the localization consists of elements of the form + `r/f, r\in R, n \geq 0` (to be precise, `R[f^{-1}] = R[t]/(ft-1)`). + + The above text is taken from `Wikipedia`. The construction here used for + this class relies on the construction of the field of fraction and is + therefore restricted to integral domains. + + Accordingly, this class is inherited from :class:`IntegralDomain` and can + only be used in that context. Furthermore, the base ring should support + :meth:`sage.structure.element.CommutativeRingElement.divides` and the exact + division operator ``//`` (:meth:`sage.structure.element.Element.__floordiv__`) + in order to guarantee a successful application. INPUT: - - ``base_ring`` -- an instance of :class:`Ring` allowing the construction of :meth:`fraction_field` (that is an integral domain) - - ``extra_units`` -- tuple of elements of ``base_ring`` which should be turned into units + - ``base_ring`` -- an instance of :class:`Ring` allowing the construction + of :meth:`fraction_field` (that is an integral domain) + - ``extra_units`` -- tuple of elements of ``base_ring`` which should be + turned into units - ``names`` -- passed to :class:`IntegralDomain` - - ``normalize`` -- (default: ``True``) passed to :class:`IntegralDomain` - - ``category`` -- (default: None) passed to :class:`IntegralDomain` - - ``warning`` -- (default: ``True``) to suppress a warning which is thrown if self cannot be represented uniquely + - ``normalize`` -- boolean (default: ``True``); passed to :class:`IntegralDomain` + - ``category`` -- (default: ``None``) passed to :class:`IntegralDomain` + - ``warning`` -- boolean (default: ``True``); to suppress a warning which + is thrown if ``self`` cannot be represented uniquely REFERENCES: @@ -899,16 +902,14 @@ def _cut_off_extra_units_from_base_ring_element(self, x): def _fraction_to_element(self, x): """ - Checks if the given element of the fraction field is contained in ``self`` - and construct it as an element of self in case the answer is true. + Check if the given element of the fraction field is contained in ``self`` + and construct it as an element of ``self`` in case the answer is true. INPUT: - ``x`` -- an element of the fraction field of the base ring - OUTPUT: - - An instance of the element class of self representing `x`. + OUTPUT: an instance of the element class of ``self`` representing `x` EXAMPLES:: @@ -1019,15 +1020,15 @@ def is_field(self, proof=True): INPUT: - - ``proof`` -- (default: ``True``) Determines what to do in unknown - cases + - ``proof`` -- boolean (default: ``True``); determines what to do in + unknown cases ALGORITHM: If the parameter ``proof`` is set to ``True``, the returned value is correct but the method might throw an error. Otherwise, if it is set - to ``False``, the method returns True if it can establish that self is - a field and False otherwise. + to ``False``, the method returns ``True`` if it can establish that + ``self`` is a field and ``False`` otherwise. EXAMPLES:: diff --git a/src/sage/rings/morphism.pyx b/src/sage/rings/morphism.pyx index bad89829a70..68ee2d5ee8e 100644 --- a/src/sage/rings/morphism.pyx +++ b/src/sage/rings/morphism.pyx @@ -648,7 +648,6 @@ cdef class RingHomomorphism(RingMap): sage: isinstance(f, sage.rings.morphism.RingHomomorphism) # needs sage.rings.padics True - """ from sage.rings.homset import RingHomset_generic if not isinstance(parent, RingHomset_generic): @@ -663,7 +662,6 @@ cdef class RingHomomorphism(RingMap): sage: ZZ.hom(Zp(3))._repr_type() # needs sage.rings.padics 'Ring' - """ return "Ring" @@ -678,9 +676,7 @@ cdef class RingHomomorphism(RingMap): - ``lift`` -- a ring map - OUTPUT: - - Changes the state of ``self``. + OUTPUT: changes the state of ``self`` EXAMPLES:: @@ -691,7 +687,6 @@ cdef class RingHomomorphism(RingMap): From: Ring of integers modulo 3 To: Integer Ring Defn: Choice of lifting map - """ if lift.domain() != self.codomain(): raise TypeError("lift must have correct domain") @@ -888,7 +883,7 @@ cdef class RingHomomorphism(RingMap): def pushforward(self, I): """ - Returns the pushforward of the ideal `I` under this ring + Return the pushforward of the ideal `I` under this ring homomorphism. EXAMPLES:: @@ -898,7 +893,7 @@ cdef class RingHomomorphism(RingMap): Ideal (xx, xx*yy + 3*xx) of Quotient of Multivariate Polynomial Ring in x, y over Rational Field by the ideal (x^2, y^2) """ - if not ideal.is_Ideal(I): + if not isinstance(I, ideal.Ideal_generic): raise TypeError("I must be an ideal") R = self.codomain() return R.ideal([self(y) for y in I.gens()]) @@ -1038,10 +1033,10 @@ cdef class RingHomomorphism(RingMap): sage: f.kernel() # needs sage.libs.singular Ideal (0) of Multivariate Polynomial Ring in t, u over Rational Field """ - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing - from sage.rings.quotient_ring import is_QuotientRing - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic + from sage.rings.quotient_ring import QuotientRing_nc + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general B = self.codomain() graph, from_B, to_A = self._graph_ideal() Q = graph.ring() @@ -1050,14 +1045,14 @@ cdef class RingHomomorphism(RingMap): # avoid adding the 0-ideal to the graph ideal in order to benefit # from a cached Gröbner basis graph_I = graph - elif (is_MPolynomialRing(B) or is_PolynomialRing(B) - or is_QuotientRing(B) or is_PolynomialQuotientRing(B)): + elif (isinstance(B, MPolynomialRing_base) or isinstance(B, PolynomialRing_general) + or isinstance(B, QuotientRing_nc) or isinstance(B, PolynomialQuotientRing_generic)): graph_I = graph + from_B(I) else: - # non-zero fractional ideals of number fields not yet supported + # nonzero fractional ideals of number fields not yet supported raise NotImplementedError("inverse image not implemented " "for ideals in %s" % B) - if is_QuotientRing(Q): + if isinstance(Q, QuotientRing_nc): # elimination_ideal does not work with quotient rings, so # switch to the cover ring gens_B_lifted = Q.cover_ring().gens()[:B.ngens()] @@ -1287,7 +1282,7 @@ cdef class RingHomomorphism(RingMap): ... NotImplementedError: rings are not commutative """ - from sage.rings.quotient_ring import is_QuotientRing + from sage.rings.quotient_ring import QuotientRing_nc from sage.rings.ideal import Ideal_generic A = self.domain() B = self.codomain() @@ -1306,7 +1301,7 @@ cdef class RingHomomorphism(RingMap): A_to_Q = A.hom(Q.gens()[B.ngens():], Q, check=False) B_to_Q = B.hom(Q.gens()[:B.ngens()], Q, check=False) graph = Q.ideal([B_to_Q(self(x)) - A_to_Q(x) for x in A.gens()]) - R = Q.cover_ring() if is_QuotientRing(Q) else Q + R = Q.cover_ring() if isinstance(Q, QuotientRing_nc) else Q R_to_A = R.hom(tuple([0] * B.ngens()) + A.gens(), A, check=False) Q_to_A = R_to_A if R is Q else R_to_A * Q.lifting_map() @@ -1328,7 +1323,7 @@ cdef class RingHomomorphism(RingMap): """ Return the inverse of this ring homomorphism if it exists. - Raises a ``ZeroDivisionError`` if the inverse does not exist. + Raises a :exc:`ZeroDivisionError` if the inverse does not exist. ALGORITHM: @@ -2495,7 +2490,7 @@ cdef class RingHomomorphism_cover(RingHomomorphism): We verify that calling directly raises the expected error (just coercing into the codomain), but calling with __call__ - (the second call below) gives a :class:`TypeError` since 1/2 cannot be + (the second call below) gives a :exc:`TypeError` since 1/2 cannot be coerced into the domain. :: sage: f._call_(1/2) @@ -2621,10 +2616,10 @@ cdef class RingHomomorphism_from_quotient(RingHomomorphism): INPUT: - - ``parent`` -- a ring homset ``Hom(R,S)`` + - ``parent`` -- a ring homset ``Hom(R,S)`` - - ``phi`` -- a ring homomorphism ``C --> S``, where ``C`` is the - domain of ``R.cover()`` + - ``phi`` -- a ring homomorphism ``C --> S``, where ``C`` is the + domain of ``R.cover()`` OUTPUT: a ring homomorphism @@ -2652,7 +2647,7 @@ cdef class RingHomomorphism_from_quotient(RingHomomorphism): True Validity of the homomorphism is determined, when possible, and a - ``TypeError`` is raised if there is no homomorphism sending the + :exc:`TypeError` is raised if there is no homomorphism sending the generators to the given images:: sage: S.hom([b^2, c^2, a^2]) # needs sage.libs.singular @@ -2712,7 +2707,6 @@ cdef class RingHomomorphism_from_quotient(RingHomomorphism): False sage: psi(a) == phi(a) True - """ self.phi = _slots['phi'] RingHomomorphism._update_slots(self, _slots) @@ -2864,9 +2858,9 @@ cdef class FrobeniusEndomorphism_generic(RingHomomorphism): """ INPUT: - - ``domain`` -- a ring + - ``domain`` -- a ring - - ``n`` -- a nonnegative integer (default: 1) + - ``n`` -- nonnegative integer (default: 1) OUTPUT: @@ -3061,7 +3055,7 @@ cdef class FrobeniusEndomorphism_generic(RingHomomorphism): def _composition(self, right): """ - Return self o right. + Return ``self`` o ``right``. EXAMPLES:: @@ -3139,12 +3133,12 @@ def _tensor_product_ring(B, A): """ from sage.rings.finite_rings.finite_field_base import FiniteField from sage.rings.number_field.number_field_base import NumberField - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.rings.polynomial.term_order import TermOrder - from sage.rings.quotient_ring import is_QuotientRing + from sage.rings.quotient_ring import QuotientRing_nc if set(B.variable_names()).isdisjoint(A.variable_names()): names = B.variable_names() + A.variable_names() @@ -3154,7 +3148,7 @@ def _tensor_product_ring(B, A): def term_order(A): # univariate rings do not have a term order - if (is_PolynomialRing(A) or is_PolynomialQuotientRing(A) + if (isinstance(A, PolynomialRing_general) or isinstance(A, PolynomialQuotientRing_generic) or (isinstance(A, (NumberField, FiniteField)) and not A.is_prime_field())): return TermOrder('lex', 1) @@ -3170,12 +3164,12 @@ def _tensor_product_ring(B, A): order=term_order(B) + term_order(A)) def relations(A, R_gens_A): - if is_MPolynomialRing(A) or is_PolynomialRing(A): + if isinstance(A, MPolynomialRing_base) or isinstance(A, PolynomialRing_general): return [] - elif is_PolynomialQuotientRing(A): + elif isinstance(A, PolynomialQuotientRing_generic): to_R = A.ambient().hom(R_gens_A, R, check=False) return [to_R(A.modulus())] - elif is_QuotientRing(A): + elif isinstance(A, QuotientRing_nc): to_R = A.ambient().hom(R_gens_A, R, check=False) return list(to_R(A.defining_ideal()).gens()) elif (isinstance(A, (NumberField, FiniteField)) diff --git a/src/sage/rings/multi_power_series_ring.py b/src/sage/rings/multi_power_series_ring.py index d399fdb6c0b..b59f3c88972 100644 --- a/src/sage/rings/multi_power_series_ring.py +++ b/src/sage/rings/multi_power_series_ring.py @@ -207,9 +207,9 @@ from sage.rings.infinity import infinity from sage.rings.multi_power_series_ring_element import MPowerSeries -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.polynomial.term_order import TermOrder from sage.rings.power_series_ring import PowerSeriesRing, PowerSeriesRing_generic, is_PowerSeriesRing from sage.rings.ring import CommutativeRing @@ -306,7 +306,6 @@ def __classcall__(cls, base_ring, num_gens, name_list, sage: P2 = PowerSeriesRing(QQ,4,'f', order='degrevlex') sage: P1 is P2 # indirect doctest True - """ order = TermOrder(order, num_gens) return super().__classcall__(cls, base_ring, num_gens, name_list, @@ -315,7 +314,7 @@ def __classcall__(cls, base_ring, num_gens, name_list, def __init__(self, base_ring, num_gens, name_list, order='negdeglex', default_prec=10, sparse=False): """ - Initializes a multivariate power series ring. See PowerSeriesRing + Initialize a multivariate power series ring. See PowerSeriesRing for complete documentation. INPUT: @@ -324,7 +323,7 @@ def __init__(self, base_ring, num_gens, name_list, - ``num_gens`` -- number of generators - - ``name_list`` -- List of indeterminate names or a single name. + - ``name_list`` -- list of indeterminate names or a single name If a single name is given, indeterminates will be this name followed by a number from 0 to num_gens - 1. If a list is given, these will be the indeterminate names and the length @@ -333,11 +332,11 @@ def __init__(self, base_ring, num_gens, name_list, - ``order`` -- ordering of variables; default is negative degree lexicographic - - ``default_prec`` -- The default total-degree precision for - elements. The default value of default_prec is 10. + - ``default_prec`` -- (default: 10) the default total-degree precision + for elements - - ``sparse`` -- whether or not the power series are sparse. - The underlying polynomial ring is always sparse. + - ``sparse`` -- whether or not the power series are sparse; the + underlying polynomial ring is always sparse EXAMPLES:: @@ -364,7 +363,6 @@ def __init__(self, base_ring, num_gens, name_list, sage: P.category() Category of commutative rings sage: TestSuite(P).run() - """ self._term_order = order if not base_ring.is_commutative(): @@ -397,7 +395,7 @@ def __init__(self, base_ring, num_gens, name_list, def _repr_(self): """ - Prints out a multivariate power series ring. + Print out a multivariate power series ring. EXAMPLES:: @@ -420,7 +418,7 @@ def _repr_(self): def _latex_(self): """ - Returns latex representation of power series ring + Return latex representation of power series ring. EXAMPLES:: @@ -465,7 +463,7 @@ def is_noetherian(self, proof=False): def term_order(self): """ - Print term ordering of self. Term orderings are implemented by the + Print term ordering of ``self``. Term orderings are implemented by the TermOrder class. EXAMPLES:: @@ -476,7 +474,7 @@ def term_order(self): sage: m = y*z^12 - y^6*z^8 - x^7*y^5*z^2 + x*y^2*z + M.O(15); m x*y^2*z + y*z^12 - x^7*y^5*z^2 - y^6*z^8 + O(x, y, z)^15 - sage: N = PowerSeriesRing(ZZ,3,'x,y,z', order="deglex") + sage: N = PowerSeriesRing(ZZ,3,'x,y,z', order='deglex') sage: N.term_order() Degree lexicographic term order sage: N(m) @@ -486,7 +484,7 @@ def term_order(self): def characteristic(self): """ - Return characteristic of base ring, which is characteristic of self. + Return characteristic of base ring, which is characteristic of ``self``. EXAMPLES:: @@ -499,8 +497,8 @@ def characteristic(self): return self.base_ring().characteristic() def construction(self): - """ - Returns a functor F and base ring R such that F(R) == self. + r""" + Return a functor `F` and base ring `R` such that ``F(R) == self``. EXAMPLES:: @@ -533,7 +531,6 @@ def construction(self): sage: c,R = M3.construction() sage: c(R)==M3 True - """ from sage.categories.pushout import CompletionFunctor extras = {'order':self.term_order(), 'num_gens':self.ngens()} @@ -545,10 +542,10 @@ def construction(self): def change_ring(self, R): """ - Returns the power series ring over R in the same variable as self. + Return the power series ring over `R` in the same variable as ``self``. This function ignores the question of whether the base ring of self - is or can extend to the base ring of R; for the latter, use - base_extend. + is or can extend to the base ring of `R`; for the latter, use + ``base_extend``. EXAMPLES:: @@ -576,7 +573,7 @@ def change_ring(self, R): def remove_var(self, *var): """ - Remove given variable or sequence of variables from self. + Remove given variable or sequence of variables from ``self``. EXAMPLES:: @@ -598,7 +595,6 @@ def remove_var(self, *var): sage: M.remove_var(*M.gens()) Finite Field of size 5 - """ vars = list(self.variable_names()) for v in var: @@ -617,7 +613,7 @@ def remove_var(self, *var): def _coerce_impl(self, f): """ Return the canonical coercion of ``f`` into this multivariate power - series ring, if one is defined, or raise a TypeError. + series ring, if one is defined, or raise a :exc:`TypeError`. The rings that canonically coerce to this multivariate power series ring are: @@ -663,8 +659,8 @@ def _coerce_impl(self, f): True """ P = f.parent() - if is_MPolynomialRing(P) or is_MPowerSeriesRing(P) \ - or is_PolynomialRing(P) or is_PowerSeriesRing(P): + if isinstance(P, MPolynomialRing_base) or is_MPowerSeriesRing(P) \ + or isinstance(P, PolynomialRing_general) or is_PowerSeriesRing(P): if set(P.variable_names()).issubset(set(self.variable_names())): if self.has_coerce_map_from(P.base_ring()): return self(f) @@ -827,8 +823,8 @@ def _coerce_map_from_(self, P): sage: R.has_coerce_map_from(L) True """ - if is_MPolynomialRing(P) or is_MPowerSeriesRing(P) \ - or is_PolynomialRing(P) or is_PowerSeriesRing(P): + if isinstance(P, MPolynomialRing_base) or is_MPowerSeriesRing(P) \ + or isinstance(P, PolynomialRing_general) or is_PowerSeriesRing(P): if set(P.variable_names()).issubset(set(self.variable_names())): if self.has_coerce_map_from(P.base_ring()): return True @@ -881,7 +877,7 @@ def _element_constructor_(self, f, prec=None): def laurent_series_ring(self): """ - Laurent series not yet implemented for multivariate power series rings + Laurent series not yet implemented for multivariate power series rings. TESTS:: @@ -915,7 +911,7 @@ def _poly_ring(self, x=None): def _mpoly_ring(self, x=None): """ - Same as _poly_ring + Same as ``_poly_ring``. TESTS:: @@ -940,7 +936,6 @@ def _bg_ps_ring(self, x=None): t, u over Rational Field sage: R._bg_ps_ring(4).parent() == R False - """ if x is None: return self._bg_power_series_ring @@ -949,7 +944,7 @@ def _bg_ps_ring(self, x=None): def is_sparse(self): """ - Is self sparse? + Check whether ``self`` is sparse. EXAMPLES:: @@ -966,7 +961,7 @@ def is_sparse(self): def is_dense(self): """ - Is self dense? (opposite of sparse) + Is ``self`` dense? (opposite of sparse) EXAMPLES:: @@ -983,7 +978,7 @@ def is_dense(self): def gen(self, n=0): """ - Return the nth generator of self. + Return the `n`-th generator of ``self``. EXAMPLES:: @@ -998,7 +993,7 @@ def gen(self, n=0): def ngens(self): """ - Return number of generators of self. + Return number of generators of ``self``. EXAMPLES:: diff --git a/src/sage/rings/multi_power_series_ring_element.py b/src/sage/rings/multi_power_series_ring_element.py index 70c882cc51c..6d893db5ebb 100644 --- a/src/sage/rings/multi_power_series_ring_element.py +++ b/src/sage/rings/multi_power_series_ring_element.py @@ -159,7 +159,7 @@ from sage.rings.finite_rings.integer_mod_ring import Zmod from sage.rings.infinity import infinity, InfinityElement from sage.rings.integer import Integer -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.power_series_ring import is_PowerSeriesRing from sage.rings.power_series_ring_element import PowerSeries @@ -174,8 +174,14 @@ def is_MPowerSeries(f): sage: from sage.rings.multi_power_series_ring_element import is_MPowerSeries sage: M = PowerSeriesRing(ZZ,4,'v') sage: is_PowerSeries(M.random_element(10)) + doctest:warning... + DeprecationWarning: The function is_PowerSeries is deprecated; use 'isinstance(..., PowerSeries)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. True sage: is_MPowerSeries(M.random_element(10)) + doctest:warning... + DeprecationWarning: The function is_MPowerSeries is deprecated; use 'isinstance(..., MPowerSeries)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. True sage: T. = PowerSeriesRing(RR) sage: is_MPowerSeries(1 - v + v^2 +O(v^3)) @@ -183,6 +189,10 @@ def is_MPowerSeries(f): sage: is_PowerSeries(1 - v + v^2 +O(v^3)) True """ + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_MPowerSeries is deprecated; " + "use 'isinstance(..., MPowerSeries)' instead.") return isinstance(f, MPowerSeries) @@ -223,20 +233,22 @@ class MPowerSeries(PowerSeries): INPUT: - - ``parent`` -- A multivariate power series. + - ``parent`` -- a multivariate power series - - ``x`` -- The element (default: 0). This can be another + - ``x`` -- the element (default: 0). This can be another :class:`MPowerSeries` object, or an element of one of the following: - the background univariate power series ring - the foreground polynomial ring - a ring that coerces to one of the above two - - ``prec`` -- (default: ``infinity``) The precision + - ``prec`` -- (default: ``infinity``) the precision - - ``is_gen`` -- (default: ``False``) Is this element one of the generators? + - ``is_gen`` -- boolean (default: ``False``); whether this element is one + of the generators - - ``check`` -- (default: ``False``) Needed by univariate power series class + - ``check`` -- boolean (default: ``False``); needed by univariate power + series class EXAMPLES: @@ -346,7 +358,6 @@ def __init__(self, parent, x=0, prec=infinity, is_gen=False, check=False): sage: b = B(d) # test coercion from univariate power series ring sage: b in B True - """ PowerSeries.__init__(self, parent, prec, is_gen=is_gen) self._PowerSeries__is_gen = is_gen @@ -369,7 +380,7 @@ def __init__(self, parent, x=0, prec=infinity, is_gen=False, check=False): # x is either a multivariate or univariate power series # # test whether x coerces directly to designated parent - if is_MPowerSeries(x): + if isinstance(x, MPowerSeries): try: self._bg_value = parent._bg_ps_ring(x._bg_value) except TypeError: @@ -393,7 +404,7 @@ def __init__(self, parent, x=0, prec=infinity, is_gen=False, check=False): self._bg_value = parent._send_to_bg(x).add_bigoh(prec) # test whether x coerces to underlying polynomial ring of parent - elif is_PolynomialRing(xparent): + elif isinstance(xparent, PolynomialRing_general): self._bg_value = parent._send_to_bg(x).add_bigoh(prec) else: @@ -634,7 +645,7 @@ def _latex_(self): def _im_gens_(self, codomain, im_gens, base_map=None): """ - Returns the image of this series under the map that sends the + Return the image of this series under the map that sends the generators to ``im_gens``. This is used internally for computing homomorphisms. @@ -1410,7 +1421,7 @@ def valuation(self): if self._bg_value == 0: return infinity - # at this stage, self is probably a non-zero + # at this stage, self is probably a nonzero # element of the base ring for a in range(len(self._bg_value.list())): if self._bg_value.list()[a] != 0: @@ -1620,7 +1631,7 @@ def integral(self, *args): .. warning:: Coefficient division. If the base ring is not a field (e.g. `ZZ`), or if it has a - non-zero characteristic, (e.g. `ZZ/3ZZ`), integration is not + nonzero characteristic, (e.g. `ZZ/3ZZ`), integration is not always possible while staying with the same base ring. In the first case, Sage will report that it has not been able to coerce some coefficient to the base ring:: @@ -1644,7 +1655,7 @@ def integral(self, *args): sage: f.integral(b) b^2 + O(a, b)^6 - In non-zero characteristic, Sage will report that a zero division + In nonzero characteristic, Sage will report that a zero division occurred :: sage: T. = PowerSeriesRing(Zmod(3), 2) @@ -1719,7 +1730,7 @@ def _integral(self, xx): def ogf(self): """ - Method from univariate power series not yet implemented + Method from univariate power series not yet implemented. TESTS:: @@ -1734,7 +1745,7 @@ def ogf(self): def egf(self): """ - Method from univariate power series not yet implemented + Method from univariate power series not yet implemented. TESTS:: @@ -1749,7 +1760,7 @@ def egf(self): def __pari__(self): """ - Method from univariate power series not yet implemented + Method from univariate power series not yet implemented. TESTS:: @@ -1882,8 +1893,8 @@ def exp(self, prec=infinity): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to OUTPUT: @@ -1977,8 +1988,8 @@ def log(self, prec=infinity): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to OUTPUT: @@ -2033,14 +2044,14 @@ def log(self, prec=infinity): sage: a.log(prec=10) Traceback (most recent call last): ... - ValueError: Can only take formal power series for non-zero constant term. + ValueError: Can only take formal power series for nonzero constant term. """ R = self.parent() Rbg = R._bg_power_series_ring c = self.constant_coefficient() if c.is_zero(): - raise ValueError('Can only take formal power series for non-zero constant term.') + raise ValueError('Can only take formal power series for nonzero constant term.') if c.is_one(): log_c = self.base_ring().zero() else: diff --git a/src/sage/rings/noncommutative_ideals.pyx b/src/sage/rings/noncommutative_ideals.pyx index 62484c9326b..48f19dd4596 100644 --- a/src/sage/rings/noncommutative_ideals.pyx +++ b/src/sage/rings/noncommutative_ideals.pyx @@ -83,7 +83,6 @@ class IdealMonoid_nc(IdealMonoid_c): sage: MS = MatrixSpace(ZZ,2,2) sage: MS.ideal_monoid() Monoid of ideals of Full MatrixSpace of 2 by 2 dense matrices over Integer Ring - """ def __init__(self, R): """ @@ -91,7 +90,7 @@ class IdealMonoid_nc(IdealMonoid_c): INPUT: - - ``R`` -- A ring. + - ``R`` -- a ring TESTS:: @@ -99,7 +98,6 @@ class IdealMonoid_nc(IdealMonoid_c): sage: MS = MatrixSpace(ZZ,2,2) sage: IdealMonoid_nc(MS) Monoid of ideals of Full MatrixSpace of 2 by 2 dense matrices over Integer Ring - """ self._IdealMonoid_c__R = R Parent.__init__(self, base=ZZ, @@ -112,7 +110,7 @@ class IdealMonoid_nc(IdealMonoid_c): INPUT: - - ``x`` -- An ideal, or a list of elements. + - ``x`` -- an ideal or a list of elements TESTS:: @@ -137,7 +135,6 @@ class IdealMonoid_nc(IdealMonoid_c): True sage: IT == loads(dumps(IT)) True - """ side = "twosided" if isinstance(x, Ideal_nc): @@ -191,23 +188,22 @@ class Ideal_nc(Ideal_generic): [1 0] ) of Full MatrixSpace of 2 by 2 dense matrices over Rational Field - """ - def __init__(self, ring, gens, coerce=True, side="twosided"): + def __init__(self, ring, gens, coerce=True, side='twosided'): """ Initialize ``self``. INPUT: - - ``ring`` -- A ring. + - ``ring`` -- a ring - - ``gens`` -- A list or tuple of elements. + - ``gens`` -- list or tuple of elements - - ``coerce`` (optional bool, default ``True``): First coerce the given - list of elements into the given ring. + - ``coerce`` -- boolean (default: ``True``); first coerce the given + list of elements into the given ring - - ``side`` (option string, default ``"twosided"``): Must be ``"left"``, - ``"right"`` or ``"twosided"``. Determines whether the ideal is a + - ``side`` -- string (default ``'twosided'``); must be ``'left'``, + ``'right'`` or ``'twosided'``. Determines whether the ideal is a left, right or twosided ideal. TESTS:: @@ -234,7 +230,6 @@ class Ideal_nc(Ideal_generic): [1 0] ) of Full MatrixSpace of 2 by 2 dense matrices over Integer Ring - """ if side not in ['left', 'right', 'twosided']: raise ValueError("Ideals are left, right or twosided, but not %s" % side) @@ -255,7 +250,6 @@ class Ideal_nc(Ideal_generic): Right Ideal (Sq(2) + Sq(4), Sq(1,1)) of mod 2 Steenrod algebra, milnor basis sage: A*[A.1+A.2,A.1^2]*A Twosided Ideal (Sq(2) + Sq(4), Sq(1,1)) of mod 2 Steenrod algebra, milnor basis - """ return "%s Ideal %s of %s" % (self.__side.capitalize(), self._repr_short(), self.ring()) @@ -341,7 +335,6 @@ class Ideal_nc(Ideal_generic): 'right' sage: IT.side() 'twosided' - """ return self.__side diff --git a/src/sage/rings/number_field/S_unit_solver.py b/src/sage/rings/number_field/S_unit_solver.py index 759d6b8da74..74bdd6e246c 100644 --- a/src/sage/rings/number_field/S_unit_solver.py +++ b/src/sage/rings/number_field/S_unit_solver.py @@ -88,12 +88,10 @@ def column_Log(SUK, iota, U, prec=106): - ``SUK`` -- a group of `S`-units - ``iota`` -- an element of ``K`` - - ``U`` -- a list of places (finite or infinite) of ``K`` + - ``U`` -- list of places (finite or infinite) of ``K`` - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The log vector as a list of real numbers + OUTPUT: the log vector as a list of real numbers EXAMPLES:: @@ -126,9 +124,7 @@ def c3_func(SUK, prec=106): - ``SUK`` -- a group of `S`-units - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The constant `c_3`, as a real number + OUTPUT: the constant `c_3`, as a real number EXAMPLES:: @@ -147,7 +143,6 @@ def c3_func(SUK, prec=106): REFERENCES: - [AKMRVW]_ :arxiv:`1903.00977` - """ R = RealField(prec) @@ -177,9 +172,7 @@ def c4_func(SUK, v, A, prec=106): - ``A`` -- the set of the product of the coefficients of the ``S``-unit equation with each root of unity of ``K`` - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The constant `c_4`, as a real number + OUTPUT: the constant `c_4`, as a real number EXAMPLES:: @@ -210,15 +203,18 @@ def c4_func(SUK, v, A, prec=106): def beta_k(betas_and_ns): r""" - Return a pair `[\beta_k,|beta_k|_v]`, where `\beta_k` has the smallest nonzero valuation in absolute value of the list ``betas_and_ns``. + Return a pair `[\beta_k,|beta_k|_v]`, where `\beta_k` has the smallest + nonzero valuation in absolute value of the list ``betas_and_ns``. INPUT: - - ``betas_and_ns`` -- a list of pairs ``[beta,val_v(beta)]`` outputted from the function where ``beta`` is an element of ``SUK.fundamental_units()`` + - ``betas_and_ns`` -- list of pairs ``[beta,val_v(beta)]`` outputted from + the function where ``beta`` is an element of ``SUK.fundamental_units()`` OUTPUT: - The pair ``[beta_k,v(beta_k)]``, where ``beta_k`` is an element of ``K`` and ``val_v(beta_k)`` is a integer + The pair ``[beta_k,v(beta_k)]``, where ``beta_k`` is an element of ``K`` + and ``val_v(beta_k)`` is a integer. EXAMPLES:: @@ -255,9 +251,7 @@ def mus(SUK, v): - ``SUK`` -- a group of `S`-units - ``v`` -- a finite place of ``K`` - OUTPUT: - - A list ``[mus]`` where each ``mu`` is an element of ``K`` + OUTPUT: list ``[mus]`` where each ``mu`` is an element of ``K`` EXAMPLES:: @@ -273,7 +267,6 @@ def mus(SUK, v): REFERENCES: - [AKMRVW]_ - """ betas = SUK.fundamental_units() beta_and_ns = [[beta,beta.valuation(v)] for beta in betas] @@ -295,9 +288,7 @@ def possible_mu0s(SUK, v): - ``SUK`` -- a group of `S`-units - ``v`` -- a finite place of ``K`` - OUTPUT: - - A list ``[mu0s]`` where each ``mu0`` is an element of ``K`` + OUTPUT: list ``[mu0s]`` where each ``mu0`` is an element of ``K`` EXAMPLES:: @@ -321,7 +312,6 @@ def possible_mu0s(SUK, v): - [AKMRVW]_ - [Sma1995]_ pp. 824-825, but we modify the definition of ``sigma`` (``sigma_tilde``) to make it easier to code - """ beta_and_ns = [[beta,beta.valuation(v)] for beta in SUK.fundamental_units()] betak, nk = beta_k(beta_and_ns) @@ -476,7 +466,7 @@ def Yu_modified_height(mu, n, v, prec=106): INPUT: - ``mu`` -- an element of a field K - - ``n`` -- number of mu_j to be considered in Yu's Theorem. + - ``n`` -- number of mu_j to be considered in Yu's Theorem - ``v`` -- a place of K - ``prec`` -- the precision of the real field @@ -529,12 +519,11 @@ def Omega_prime(dK, v, mu_list, prec=106): - ``dK`` -- the degree of a number field `K` - ``v`` -- a finite place of `K` - - ``mu_list`` -- a list of nonzero elements of `K`. It is assumed that the sublist ``mu_list[1:]`` is multiplicatively independent. + - ``mu_list`` -- list of nonzero elements of `K`. It is assumed that the + sublist ``mu_list[1:]`` is multiplicatively independent - ``prec`` -- the precision of the real field - OUTPUT: - - The constant `\Omega'`. + OUTPUT: the constant `\Omega'` EXAMPLES:: @@ -576,9 +565,7 @@ def Yu_C1_star(n, v, prec=106): - ``v`` -- a finite place of `K` (a fractional ideal) - ``prec`` -- the precision of the real field - OUTPUT: - - The constant `C_1^*` as a real number. + OUTPUT: the constant `C_1^*` as a real number EXAMPLES:: @@ -638,9 +625,7 @@ def Yu_bound(SUK, v, prec=106): - ``v`` -- a finite place of `K` (a fractional ideal) - ``prec`` -- the precision of the real field - OUTPUT: - - The constant `c_8` as a real number. + OUTPUT: the constant `c_8` as a real number EXAMPLES:: @@ -721,9 +706,7 @@ def K0_func(SUK, A, prec=106): - ``A`` -- the set of the products of the coefficients of the `S`-unit equation with each root of unity of `K` - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The constant `K_0`, a real number. + OUTPUT: the constant `K_0`, a real number EXAMPLES:: @@ -772,9 +755,7 @@ def c11_func(SUK, v, A, prec=106): - ``A`` -- the set of the product of the coefficients of the `S`-unit equation with each root of unity of `K` - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The constant `c_{11}`, a real number + OUTPUT: the constant `c_{11}`, a real number EXAMPLES:: @@ -813,9 +794,7 @@ def c13_func(SUK, v, prec=106): - ``v`` -- an infinite place of ``K`` (element of ``SUK.number_field().places(prec)``) - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The constant `c_{13}`, as a real number + OUTPUT: the constant `c_{13}`, as a real number EXAMPLES:: @@ -863,12 +842,11 @@ def K1_func(SUK, v, A, prec=106): - ``SUK`` -- a group of `S`-units - ``v`` -- an infinite place of `K` (element of ``SUK.number_field().places(prec)``) - - ``A`` -- a list of all products of each potential `a`, `b` in the `S`-unit equation `ax + by + 1 = 0` with each root of unity of `K` + - ``A`` -- list of all products of each potential `a`, `b` in the `S`-unit + equation `ax + by + 1 = 0` with each root of unity of `K` - ``prec`` -- the precision of the real field (default: 106) - OUTPUT: - - The constant `K_1`, a real number + OUTPUT: the constant `K_1`, a real number EXAMPLES:: @@ -889,7 +867,6 @@ def K1_func(SUK, v, A, prec=106): REFERENCES: - [Sma1995]_ p. 825 - """ R = RealField(prec) @@ -933,9 +910,7 @@ def minimal_vector(A, y, prec=106): - ``y`` -- a row (1 by `n`) vector with integer coordinates - ``prec`` -- precision of real field (default: 106) - OUTPUT: - - A lower bound for the square of + OUTPUT: a lower bound for the square of .. MATH:: @@ -995,13 +970,11 @@ def reduction_step_complex_case(place, B0, list_of_gens, torsion_gen, c13): - ``place`` -- (ring morphism) an infinite place of a number field `K` - ``B0`` -- the initial bound - - ``list_of_gens`` -- a set of generators of the free part of the group + - ``list_of_gens`` -- set of generators of the free part of the group - ``torsion_gen`` -- an element of the torsion part of the group - ``c13`` -- a positive real number - OUTPUT: - - A tuple consisting of: + OUTPUT: a tuple consisting of: 1. a new upper bound, an integer 2. a boolean value, ``True`` if we have to increase precision, otherwise ``False`` @@ -1068,7 +1041,7 @@ def reduction_step_complex_case(place, B0, list_of_gens, torsion_gen, c13): A = A.transpose() - # Note that l is the lower bound on the square of the magnitude of the shortest non-zero vector in the lattice generated by A + # Note that l is the lower bound on the square of the magnitude of the shortest nonzero vector in the lattice generated by A l = minimal_vector(A, zero_vector(ZZ,n+1)) # Checking hypotheses of Lemma 5.3 in our paper: @@ -1107,7 +1080,7 @@ def reduction_step_complex_case(place, B0, list_of_gens, torsion_gen, c13): # We apply Lemma 5.3 from [AKMRVW] A = A.transpose() l = minimal_vector(A, zero_vector(ZZ,n+1)) - # Note that l is the a lower bound on the square of the magnitude of the shortest non-zero vector in the lattice generated by A + # Note that l is the a lower bound on the square of the magnitude of the shortest nonzero vector in the lattice generated by A # Checking hypothesis of lemma 5.3 in [AKMRVW] if l <= T**2 + S: C *= 2 @@ -1154,7 +1127,7 @@ def reduction_step_complex_case(place, B0, list_of_gens, torsion_gen, c13): # We apply Lemma 5.2 from [AKMRVW] A = A.transpose() l = minimal_vector(A, zero_vector(ZZ,n+1)) - # Note that l is the a lower bound on the square of the magnitude of the shortest non-zero vector in the lattice generated by A + # Note that l is the a lower bound on the square of the magnitude of the shortest nonzero vector in the lattice generated by A # Checking hypothesis of lemma 5.2 in [AKMRVW] if l <= T**2 + S: C *= 2 @@ -1178,12 +1151,11 @@ def cx_LLL_bound(SUK, A, prec=106): INPUT: - ``SUK`` -- a group of `S`-units - - ``A`` -- a list of all products of each potential `a`, `b` in the `S`-unit equation `ax + by + 1 = 0` with each root of unity of `K` + - ``A`` -- list of all products of each potential `a`, `b` in the `S`-unit + equation `ax + by + 1 = 0` with each root of unity of `K` - ``prec`` -- precision of real field (default: 106) - OUTPUT: - - A bound for the exponents at the infinite place, as a real number + OUTPUT: a bound for the exponents at the infinite place, as a real number EXAMPLES:: @@ -1234,15 +1206,18 @@ def log_p(a, prime, prec): - ``a`` -- an element of a number field `K` - ``prime`` -- a prime ideal of the number field `K` - - ``prec`` -- a positive integer + - ``prec`` -- positive integer OUTPUT: - An element of `K` which is congruent to the ``prime``-adic logarithm of `a` with respect to ``prime`` modulo ``p^prec``, where `p` is the rational prime below ``prime`` + An element of `K` which is congruent to the ``prime``-adic logarithm of `a` + with respect to ``prime`` modulo ``p^prec``, where `p` is the rational + prime below ``prime``. .. NOTE:: - Here we take into account the other primes in `K` above `p` in order to get coefficients with small values + Here we take into account the other primes in `K` above `p` in order to + get coefficients with small values. EXAMPLES:: @@ -1299,15 +1274,16 @@ def log_p_series_part(a, prime, prec): - ``a`` -- an element of a number field `K` - ``prime`` -- a prime ideal of the number field `K` - - ``prec`` -- a positive integer + - ``prec`` -- positive integer OUTPUT: - The ``prime``-adic logarithm of `a` and accuracy ``p^prec``, where `p` is the rational prime below ``prime`` + The ``prime``-adic logarithm of `a` and accuracy ``p^prec``, where `p` is + the rational prime below ``prime``. ALGORITHM: - The algorithm is based on the algorithm on page 30 of [Sma1998]_ + The algorithm is based on the algorithm on page 30 of [Sma1998]_. EXAMPLES:: @@ -1394,9 +1370,7 @@ def defining_polynomial_for_Kp(prime, prec=106): - ``prime`` -- a prime ideal of a number field `K` - ``prec`` -- a positive natural number (default: 106) - OUTPUT: - - A polynomial with integer coefficients that is equivalent ``mod p^prec`` to a defining polynomial for the completion of `K` associated to the specified prime. + OUTPUT: a polynomial with integer coefficients that is equivalent ``mod p^prec`` to a defining polynomial for the completion of `K` associated to the specified prime .. NOTE:: @@ -1504,15 +1478,14 @@ def p_adic_LLL_bound_one_prime(prime, B0, M, M_logp, m0, c3, prec=106): - ``prime`` -- a prime ideal of a number field `K` - ``B0`` -- the initial bound - - ``M`` -- a list of elements of `K`, the `\mu_i`'s from Lemma IX.3 of [Sma1998]_ - - ``M_logp`` -- the p-adic logarithm of elements in `M` + - ``M`` -- list of elements of `K`, the `\mu_i`'s from Lemma IX.3 of [Sma1998]_ + - ``M_logp`` -- the `p`-adic logarithm of elements in `M` - ``m0`` -- an element of `K`, this is `\mu_0` from Lemma IX.3 of [Sma1998]_ - ``c3`` -- a positive real constant - - ``prec`` -- the precision of the calculations (default: 106), i.e., values are known to ``O(p^prec)`` - - OUTPUT: + - ``prec`` -- the precision of the calculations (default: 106), i.e., + values are known to ``O(p^prec)`` - A pair consisting of: + OUTPUT: a pair consisting of: 1. a new upper bound, an integer 2. a boolean value, ``True`` if we have to increase precision, otherwise ``False`` @@ -1562,7 +1535,7 @@ def p_adic_LLL_bound_one_prime(prime, B0, M, M_logp, m0, c3, prec=106): False """ if any(g.valuation(prime) != 0 for g in M+[m0]): - raise ValueError('There is an element with non zero valuation') + raise ValueError('There is an element with nonzero valuation') K = prime.ring() w = K.number_of_roots_of_unity() @@ -1651,13 +1624,15 @@ def p_adic_LLL_bound_one_prime(prime, B0, M, M_logp, m0, c3, prec=106): def p_adic_LLL_bound(SUK, A, prec=106): r""" - Return the maximum of all of the `K_0`'s as they are LLL-optimized for each finite place `v`. + Return the maximum of all of the `K_0`'s as they are LLL-optimized for each + finite place `v`. INPUT: - ``SUK`` -- a group of `S`-units - - ``A`` -- a list of all products of each potential `a`, `b` in the `S`-unit equation `ax + by + 1 = 0` with each root of unity of `K` - - ``prec`` -- precision for p-adic LLL calculations (default: 106) + - ``A`` -- list of all products of each potential `a`, `b` in the `S`-unit + equation `ax + by + 1 = 0` with each root of unity of `K` + - ``prec`` -- precision for `p`-adic LLL calculations (default: 106) OUTPUT: @@ -1711,16 +1686,15 @@ def p_adic_LLL_bound(SUK, A, prec=106): def split_primes_large_lcm(SUK, bound): r""" - Return a list `L` of rational primes `q` which split completely in `K` and which have desirable properties (see NOTE). + Return a list `L` of rational primes `q` which split completely in `K` and + which have desirable properties (see NOTE). INPUT: - - ``SUK`` -- the `S`-unit group of an absolute number field `K`. - - ``bound`` -- a positive integer + - ``SUK`` -- the `S`-unit group of an absolute number field `K` + - ``bound`` -- positive integer - OUTPUT: - - A list `L` of rational primes `q`, with the following properties: + OUTPUT: list `L` of rational primes `q`, with the following properties: - each prime `q` in `L` splits completely in `K` - if `Q` is a prime in `S` and `q` is the rational @@ -1757,7 +1731,6 @@ def split_primes_large_lcm(SUK, bound): Traceback (most recent call last): ... ValueError: Not enough split primes found. Increase bound. - """ K = SUK.number_field() @@ -1786,11 +1759,10 @@ def sieve_ordering(SUK, q): INPUT: - ``SUK`` -- the `S`-unit group of a number field `K` - - ``q`` -- a rational prime number which splits completely in `K` + - ``q`` -- a rational prime number which splits completely in `K` - OUTPUT: - - A list of tuples, ``[ideals_over_q, residue_fields, rho_images, product_rho_orders]``, where + OUTPUT: list of tuples; + ``[ideals_over_q, residue_fields, rho_images, product_rho_orders]``, where: 1. ``ideals_over_q`` is a list of the `d = [K:\QQ]` ideals in `K` over `q` 2. ``residue_fields[i]`` is the residue field of ``ideals_over_q[i]`` @@ -1855,11 +1827,10 @@ def clean_rfv_dict(rfv_dictionary): INPUT: - - ``rfv_dictionary`` -- a dictionary whose keys are exponent vectors and whose values are residue field vectors - - OUTPUT: + - ``rfv_dictionary`` -- dictionary whose keys are exponent vectors and + whose values are residue field vectors - ``None``. But it removes some keys from the input dictionary. + OUTPUT: none, but it removes some keys from the input dictionary .. NOTE:: @@ -1891,14 +1862,17 @@ def clean_rfv_dict(rfv_dictionary): def construct_rfv_to_ev(rfv_dictionary, q, d, verbose=False): r""" - Return a reverse lookup dictionary, to find the exponent vectors associated to a given residue field vector. + Return a reverse lookup dictionary, to find the exponent vectors associated + to a given residue field vector. INPUT: - - ``rfv_dictionary`` -- a dictionary whose keys are exponent vectors and whose values are the associated residue field vectors + - ``rfv_dictionary`` -- dictionary whose keys are exponent vectors and + whose values are the associated residue field vectors - ``q`` -- a prime (assumed to split completely in the relevant number field) - ``d`` -- the number of primes in `K` above the rational prime `q` - - ``verbose`` -- a boolean flag to indicate more detailed output is desired (default: ``False``) + - ``verbose`` -- boolean (default: ``False``); flag to indicate more + detailed output is desired OUTPUT: @@ -2026,16 +2000,17 @@ def construct_rfv_to_ev(rfv_dictionary, q, d, verbose=False): def construct_comp_exp_vec(rfv_to_ev_dict, q): r""" - Constructs a dictionary associating complement vectors to residue field vectors. + Construct a dictionary associating complement vectors to residue field vectors. INPUT: - - ``rfv_to_ev_dict`` -- a dictionary whose keys are residue field vectors and whose values are lists of exponent vectors with the associated residue field vector. + - ``rfv_to_ev_dict`` -- dictionary whose keys are residue field vectors and + whose values are lists of exponent vectors with the associated residue + field vector - ``q`` -- the characteristic of the residue field - OUTPUT: - - A dictionary whose typical key is an exponent vector ``a``, and whose associated value is a list of complementary exponent vectors to ``a``. + OUTPUT: a dictionary whose typical key is an exponent vector ``a``, and + whose associated value is a list of complementary exponent vectors to ``a`` EXAMPLES: @@ -2102,13 +2077,12 @@ def drop_vector(ev, p, q, complement_ev_dict): - ``ev`` -- an exponent vector modulo `p-1` - ``p`` -- the prime such that ``ev`` is an exponent vector modulo `p-1` - ``q`` -- a prime, distinct from `p`, that is a key in the ``complement_ev_dict`` - - ``complement_ev_dict`` -- a dictionary of dictionaries, whose keys are primes. + - ``complement_ev_dict`` -- dictionary of dictionaries, whose keys are primes ``complement_ev_dict[q]`` is a dictionary whose keys are exponent vectors modulo `q-1` and whose values are lists of complementary exponent vectors modulo `q-1` - OUTPUT: - - Returns ``True`` if ``ev`` may be dropped from the complement exponent vector dictionary, and ``False`` if not. + OUTPUT: ``True`` if ``ev`` may be dropped from the complement exponent + vector dictionary, and ``False`` if not .. NOTE:: @@ -2165,15 +2139,17 @@ def construct_complement_dictionaries(split_primes_list, SUK, verbose=False): INPUT: - - ``split_primes_list`` -- a list of rational primes which split completely in the number field `K` + - ``split_primes_list`` -- list of rational primes which split completely + in the number field `K` - ``SUK`` -- the `S`-unit group for a number field `K` - - ``verbose`` -- a boolean to provide additional feedback (default: ``False``) + - ``verbose`` -- boolean to provide additional feedback (default: ``False``) OUTPUT: - A dictionary of dictionaries. The keys coincide with the primes in ``split_primes_list`` - For each `q`, ``comp_exp_vec[q]`` is a dictionary whose keys are exponent vectors modulo `q-1`, - and whose values are lists of exponent vectors modulo `q-1` + A dictionary of dictionaries. The keys coincide with the primes in + ``split_primes_list``. For each `q`, ``comp_exp_vec[q]`` is a dictionary + whose keys are exponent vectors modulo `q-1`, and whose values are lists of + exponent vectors modulo `q-1`. If `w` is an exponent vector in ``comp_exp_vec[q][v]``, then the residue field vectors modulo `q` for `v` and `w` sum to ``[1,1,...,1]`` @@ -2385,9 +2361,7 @@ def compatible_vectors_check(a0, a1, g, l): - ``g`` -- the gcd of ``m0`` and ``m1`` - ``l`` -- the length of ``a0`` and of ``a1`` - OUTPUT: - - ``True`` if there is an integer exponent vector a satisfying + OUTPUT: ``True`` if there is an integer exponent vector a satisfying .. MATH:: @@ -2425,18 +2399,17 @@ def compatible_vectors(a, m0, m1, g): INPUT: - - ``a`` -- an exponent vector for the modulus ``m0`` - - ``m0`` -- a positive integer (specifying the modulus for ``a``) - - ``m1`` -- a positive integer (specifying the alternate modulus) + - ``a`` -- an exponent vector for the modulus ``m0`` + - ``m0`` -- positive integer (specifying the modulus for ``a``) + - ``m1`` -- positive integer (specifying the alternate modulus) - ``g`` -- the gcd of ``m0`` and ``m1`` - OUTPUT: - - A list of exponent vectors modulo ``m1`` which are compatible with ``a``. + OUTPUT: list of exponent vectors modulo ``m1`` which are compatible with ``a`` .. NOTE:: - - Exponent vectors must agree exactly in the 0th position in order to be compatible. + Exponent vectors must agree exactly in the 0th position in order to be + compatible. EXAMPLES:: @@ -2466,16 +2439,16 @@ def compatible_vectors(a, m0, m1, g): def compatible_systems(split_prime_list, complement_exp_vec_dict): r""" - Given dictionaries of complement exponent vectors for various primes that split in `K`, compute all possible compatible systems. + Given dictionaries of complement exponent vectors for various primes that + split in `K`, compute all possible compatible systems. INPUT: - - ``split_prime_list`` -- a list of rational primes that split completely in `K` - - ``complement_exp_vec_dict`` -- a dictionary of dictionaries. The keys are primes from ``split_prime_list``. - - OUTPUT: + - ``split_prime_list`` -- list of rational primes that split completely in `K` + - ``complement_exp_vec_dict`` -- dictionary of dictionaries; the keys are + primes from ``split_prime_list`` - A list of compatible systems of exponent vectors. + OUTPUT: list of compatible systems of exponent vectors .. NOTE:: @@ -2532,17 +2505,17 @@ def compatible_systems(split_prime_list, complement_exp_vec_dict): def compatible_system_lift(compatible_system, split_primes_list): r""" - Given a compatible system of exponent vectors and complementary exponent vectors, return a lift to the integers. + Given a compatible system of exponent vectors and complementary exponent + vectors, return a lift to the integers. INPUT: - - ``compatible_system`` -- a list of pairs ``[ [v0, w0], [v1, w1], .., [vk, wk] ]`` - where [vi, wi] is a pair of complementary exponent vectors modulo ``qi - 1``, and all pairs are compatible. - - ``split_primes_list`` -- a list of primes ``[ q0, q1, .., qk ]`` + - ``compatible_system`` -- list of pairs ``[ [v0, w0], [v1, w1], .., [vk, wk] ]`` + where [vi, wi] is a pair of complementary exponent vectors modulo ``qi - 1``, + and all pairs are compatible + - ``split_primes_list`` -- list of primes ``[ q0, q1, .., qk ]`` - OUTPUT: - - A pair of vectors ``[v, w]`` satisfying: + OUTPUT: a pair of vectors ``[v, w]`` satisfying: 1. ``v[0] == vi[0]`` for all ``i`` 2. ``w[0] == wi[0]`` for all ``i`` @@ -2593,15 +2566,17 @@ def compatible_system_lift(compatible_system, split_primes_list): def solutions_from_systems(SUK, bound, cs_list, split_primes_list): r""" - Lift compatible systems to the integers and return the `S`-unit equation solutions that the lifts yield. + Lift compatible systems to the integers and return the `S`-unit equation + solutions that the lifts yield. INPUT: - ``SUK`` -- the group of `S`-units where we search for solutions - ``bound`` -- a bound for the entries of all entries of all lifts - - ``cs_list`` -- a list of compatible systems of exponent vectors modulo `q-1` for - various primes `q` - - ``split_primes_list`` -- a list of primes giving the moduli of the exponent vectors in ``cs_list`` + - ``cs_list`` -- list of compatible systems of exponent vectors modulo + `q-1` for various primes `q` + - ``split_primes_list`` -- list of primes giving the moduli of the exponent + vectors in ``cs_list`` OUTPUT: @@ -2654,11 +2629,9 @@ def clean_sfs(sfs_list): INPUT: - - ``sfs_list`` -- a list of solutions to the `S`-unit equation - - OUTPUT: + - ``sfs_list`` -- list of solutions to the `S`-unit equation - A list of solutions to the `S`-unit equation + OUTPUT: list of solutions to the `S`-unit equation .. NOTE:: @@ -2686,17 +2659,23 @@ def clean_sfs(sfs_list): def sieve_below_bound(K, S, bound=10, bump=10, split_primes_list=[], verbose=False): r""" - Return all solutions to the `S`-unit equation `x + y = 1` over `K` with exponents below the given bound. + Return all solutions to the `S`-unit equation `x + y = 1` over `K` with + exponents below the given bound. INPUT: - ``K`` -- a number field (an absolute extension of the rationals) - - ``S`` -- a list of finite primes of `K` - - ``bound`` -- a positive integer upper bound for exponents, solutions with exponents having absolute value below this bound will be found (default: 10) - - ``bump`` -- a positive integer by which the minimum LCM will be increased if not enough split primes are found in sieving step (default: 10) - - ``split_primes_list`` -- a list of rational primes that split completely in the extension `K/\QQ`, used for sieving. - For complete list of solutions should have lcm of `\{(p_i-1)\} for primes `p_i` greater than bound (default: ``[]``) - - ``verbose`` -- an optional parameter allowing the user to print information during the sieving process (default: ``False``) + - ``S`` -- list of finite primes of `K` + - ``bound`` -- positive integer upper bound for exponents, solutions with + exponents having absolute value below this bound will be found (default: 10) + - ``bump`` -- positive integer by which the minimum LCM will be increased + if not enough split primes are found in sieving step (default: 10) + - ``split_primes_list`` -- list of rational primes that split completely in + the extension `K/\QQ`, used for sieving. For complete list of solutions + should have lcm of `\{(p_i-1)\} for primes `p_i` greater than bound + (default: ``[]``). + - ``verbose`` -- an optional parameter allowing the user to print + information during the sieving process (default: ``False``) OUTPUT: @@ -2753,11 +2732,15 @@ def solve_S_unit_equation(K, S, prec=106, include_exponents=True, include_bound= INPUT: - ``K`` -- a number field (an absolute extension of the rationals) - - ``S`` -- a list of finite primes of `K` - - ``prec`` -- precision used for computations in real, complex, and p-adic fields (default: 106) - - ``include_exponents`` -- whether to include the exponent vectors in the returned value (default: ``True``). - - ``include_bound`` -- whether to return the final computed bound (default: ``False``) - - ``verbose`` -- whether to print information during the sieving step (default: ``False``) + - ``S`` -- list of finite primes of `K` + - ``prec`` -- precision used for computations in real, complex, and `p`-adic + fields (default: 106) + - ``include_exponents`` -- whether to include the exponent vectors in the + returned value (default: ``True``) + - ``include_bound`` -- whether to return the final computed bound + (default: ``False``) + - ``verbose`` -- whether to print information during the sieving step + (default: ``False``) OUTPUT: diff --git a/src/sage/rings/number_field/bdd_height.py b/src/sage/rings/number_field/bdd_height.py index 7419361579f..45f08aa4711 100644 --- a/src/sage/rings/number_field/bdd_height.py +++ b/src/sage/rings/number_field/bdd_height.py @@ -50,13 +50,11 @@ def bdd_norm_pr_gens_iq(K, norm_list): INPUT: - - `K` -- an imaginary quadratic number field + - ``K`` -- an imaginary quadratic number field - - ``norm_list`` -- a list of positive integers + - ``norm_list`` -- list of positive integers - OUTPUT: - - - a dictionary of number field elements, keyed by norm + OUTPUT: dictionary of number field elements, keyed by norm EXAMPLES: @@ -114,13 +112,11 @@ def bdd_height_iq(K, height_bound): INPUT: - - `K` -- an imaginary quadratic number field + - ``K`` -- an imaginary quadratic number field - ``height_bound`` -- a real number - OUTPUT: - - - an iterator of number field elements + OUTPUT: an iterator of number field elements EXAMPLES:: @@ -219,13 +215,11 @@ def bdd_norm_pr_ideal_gens(K, norm_list): INPUT: - - `K` -- a number field - - - ``norm_list`` -- a list of positive integers + - ``K`` -- a number field - OUTPUT: + - ``norm_list`` -- list of positive integers - - a dictionary of number field elements, keyed by norm + OUTPUT: dictionary of number field elements, keyed by norm EXAMPLES: @@ -253,7 +247,6 @@ def bdd_norm_pr_ideal_gens(K, norm_list): sage: key = ZZ(28) sage: b[key] [157*g^4 - 139*g^3 - 369*g^2 + 848*g + 158, g^4 + g^3 - g - 7] - """ negative_norm_units = K.elements_of_norm(-1) gens = {} @@ -285,9 +278,7 @@ def integer_points_in_polytope(matrix, interval_radius): - ``interval_radius`` -- a real number - OUTPUT: - - - a list of tuples of integers + OUTPUT: list of tuples of integers EXAMPLES: @@ -370,9 +361,7 @@ def bdd_height(K, height_bound, tolerance=1e-2, precision=53): - ``precision`` -- (default: 53) positive integer - OUTPUT: - - an iterator of number field elements + OUTPUT: an iterator of number field elements EXAMPLES: diff --git a/src/sage/rings/number_field/class_group.py b/src/sage/rings/number_field/class_group.py index f514bd49b26..34a48931f8e 100644 --- a/src/sage/rings/number_field/class_group.py +++ b/src/sage/rings/number_field/class_group.py @@ -261,7 +261,8 @@ def representative_prime(self, norm_bound=1000): INPUT: - - ``norm_bound`` -- (positive integer) upper bound on the norm of primes tested. + - ``norm_bound`` -- (positive integer) upper bound on the norm of + primes tested EXAMPLES:: @@ -510,9 +511,7 @@ def gens_ideals(self): This is an alias for :meth:`gens_values`. - OUTPUT: - - A tuple of ideals, one for each abstract Abelian group generator. + OUTPUT: a tuple of ideals, one for each abstract Abelian group generator EXAMPLES:: diff --git a/src/sage/rings/number_field/galois_group.py b/src/sage/rings/number_field/galois_group.py index 364abc0f706..6ea1068ab2f 100644 --- a/src/sage/rings/number_field/galois_group.py +++ b/src/sage/rings/number_field/galois_group.py @@ -277,7 +277,7 @@ def __init__(self, number_field, algorithm='pari', names=None, gc_numbering=None You can specify the variable name for the Galois closure:: sage: x = polygen(ZZ, 'x') - sage: G = NumberField(x^3 - 2, 'b').galois_group(names="c"); G + sage: G = NumberField(x^3 - 2, 'b').galois_group(names='c'); G Galois group 3T2 (S3) with order 6 of x^3 - 2 sage: G._galois_closure Number Field in c with defining polynomial x^6 + 108 @@ -324,7 +324,7 @@ def _pol_galgp(self, algorithm=None): sage: G = K.galois_group() sage: G._pol_galgp() PARI group [6, -1, 2, "S3"] of degree 3 - sage: G._pol_galgp(algorithm="gap") # optional - gap_packages + sage: G._pol_galgp(algorithm='gap') # optional - gap_packages Transitive group number 2 of degree 3 """ algorithm = self._get_algorithm(algorithm) @@ -342,7 +342,7 @@ def group(self): sage: R. = ZZ[] sage: x = polygen(ZZ, 'x') sage: K. = NumberField(x^3 + 2*x + 2) - sage: G = K.galois_group(type="pari") + sage: G = K.galois_group(type='pari') ...DeprecationWarning: the different Galois types have been merged into one class See https://github.com/sagemath/sage/issues/28782 for details. sage: G.group() @@ -357,7 +357,7 @@ def group(self): @cached_method(key=_alg_key) def order(self, algorithm=None, recompute=False): """ - Return the order of this Galois group + Return the order of this Galois group. EXAMPLES:: @@ -423,7 +423,7 @@ def transitive_number(self, algorithm=None, recompute=False): 2 sage: x = polygen(ZZ, 'x') sage: L. = NumberField(x^13 + 2*x + 2) - sage: H = L.galois_group(algorithm="gap") + sage: H = L.galois_group(algorithm='gap') sage: H.transitive_number() # optional - gap_packages 9 """ @@ -484,7 +484,7 @@ def signature(self): @lazy_attribute def _gcdata(self): """ - Return the Galois closure, together with the embedding of the top field into it + Return the Galois closure, together with the embedding of the top field into it. EXAMPLES:: @@ -693,7 +693,7 @@ def is_galois(self): def _repr_(self): r""" - String representation of this Galois group + String representation of this Galois group. EXAMPLES:: @@ -1028,24 +1028,27 @@ def artin_symbol(self, P): class GaloisGroup_subgroup(GaloisSubgroup_perm): r""" - A subgroup of a Galois group, as returned by functions such as ``decomposition_group``. + A subgroup of a Galois group, as returned by functions such as + ``decomposition_group``. INPUT: - ``ambient`` -- the ambient Galois group - - ``gens`` -- a list of generators for the group + - ``gens`` -- list of generators for the group - ``gap_group`` -- a gap or libgap permutation group, or a string defining one (default: ``None``) - - ``domain`` -- a set on which this permutation group acts; extracted from ``ambient`` if not specified + - ``domain`` -- set on which this permutation group acts; extracted from + ``ambient`` if not specified - ``category`` -- the category for this object - ``canonicalize`` -- if ``True``, sorts and removes duplicates - - ``check`` -- whether to check that generators actually lie in the ambient group + - ``check`` -- whether to check that generators actually lie in the + ambient group EXAMPLES:: @@ -1106,7 +1109,7 @@ def fixed_field(self, name=None, polred=None, threshold=None): INPUT: - - ``name`` -- a variable name for the new field. + - ``name`` -- a variable name for the new field - ``polred`` -- whether to optimize the generator of the newly created field for a simpler polynomial, using PARI's :pari:`polredbest`. @@ -1254,8 +1257,8 @@ def as_hom(self): def __call__(self, x): r""" - Return the action of self on an element x in the number field of self - (or its Galois closure). + Return the action of ``self`` on an element x in the number field of + ``self`` (or its Galois closure). EXAMPLES:: diff --git a/src/sage/rings/number_field/homset.py b/src/sage/rings/number_field/homset.py index 4e4a12a9c6f..62ca214754d 100644 --- a/src/sage/rings/number_field/homset.py +++ b/src/sage/rings/number_field/homset.py @@ -240,7 +240,7 @@ def list(self): def __getitem__(self, n): r""" - Return the ``n``th element of ``self.list()``. + Return the `n`-th element of ``self.list()``. EXAMPLES:: diff --git a/src/sage/rings/number_field/morphism.py b/src/sage/rings/number_field/morphism.py index a16ccd2bbc6..579c925ed01 100644 --- a/src/sage/rings/number_field/morphism.py +++ b/src/sage/rings/number_field/morphism.py @@ -26,7 +26,7 @@ class NumberFieldHomomorphism_im_gens(RingHomomorphism_im_gens): def __invert__(self): r""" - Return the inverse of an isomorphism of absolute number fields + Return the inverse of an isomorphism of absolute number fields. EXAMPLES:: @@ -88,16 +88,16 @@ def __invert__(self): def preimage(self, y): r""" Compute a preimage of `y` in the domain, provided one exists. - Raises a :class:`ValueError` if `y` has no preimage. + Raises a :exc:`ValueError` if `y` has no preimage. INPUT: - - ``y`` -- an element of the codomain of ``self``. + - ``y`` -- an element of the codomain of ``self`` OUTPUT: Returns the preimage of `y` in the domain, if one exists. - Raises a :class:`ValueError` if `y` has no preimage. + Raises a :exc:`ValueError` if `y` has no preimage. EXAMPLES:: @@ -221,7 +221,7 @@ def im_gens(self): def _richcmp_(self, other, op): """ - Compare + Compare. EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field.py b/src/sage/rings/number_field/number_field.py index c1e9c12a711..99fda51012c 100644 --- a/src/sage/rings/number_field/number_field.py +++ b/src/sage/rings/number_field/number_field.py @@ -234,19 +234,19 @@ def NumberField(polynomial, name=None, check=True, names=None, embedding=None, INPUT: - ``polynomial`` -- a polynomial over `\QQ` or a number field, or a list - of such polynomials. - - ``names`` (or ``name``) -- a string or a list of strings, the names of + of such polynomials + - ``names`` (or ``name``) -- string or list of strings, the names of the generators - - ``check`` -- a boolean (default: ``True``); do type checking and - irreducibility checking. + - ``check`` -- boolean (default: ``True``); do type checking and + irreducibility checking - ``embedding`` -- ``None``, an element, or a list of elements, the images of the generators in an ambient field (default: ``None``) - ``latex_names`` (or ``latex_name``) -- ``None``, a string, or a - list of strings (default: ``None``), how the generators are printed + list of strings (default: ``None``); how the generators are printed for latex output - - ``assume_disc_small`` -- a boolean (default: ``False``); if ``True``, + - ``assume_disc_small`` -- boolean (default: ``False``); if ``True``, assume that no square of a prime greater than PARI's primelimit - (which should be 500000); only applies for absolute fields at + (which should be 500000). Only applies for absolute fields at present. - ``maximize_at_primes`` -- ``None`` or a list of primes (default: ``None``); if not ``None``, then the maximal order is computed by @@ -565,17 +565,17 @@ class NumberFieldFactory(UniqueFactory): INPUT: - - ``polynomial`` -- a polynomial over `\QQ` or a number field. - - ``name`` -- a string (default: ``'a'``), the name of the generator - - ``check`` -- a boolean (default: ``True``); do type checking and - irreducibility checking. + - ``polynomial`` -- a polynomial over `\QQ` or a number field + - ``name`` -- string (default: ``'a'``); the name of the generator + - ``check`` -- boolean (default: ``True``); do type checking and + irreducibility checking - ``embedding`` -- ``None`` or an element, the images of the generator in an ambient field (default: ``None``) - - ``latex_name`` -- ``None`` or a string (default: ``None``), how the + - ``latex_name`` -- ``None`` or string (default: ``None``); how the generator is printed for latex output - - ``assume_disc_small`` -- a boolean (default: ``False``); if ``True``, + - ``assume_disc_small`` -- boolean (default: ``False``); if ``True``, assume that no square of a prime greater than PARI's primelimit - (which should be 500000); only applies for absolute fields at + (which should be 500000). Only applies for absolute fields at present. - ``maximize_at_primes`` -- ``None`` or a list of primes (default: ``None``); if not ``None``, then the maximal order is computed by @@ -608,7 +608,6 @@ class NumberFieldFactory(UniqueFactory): Isomorphism given by variable name change map: From: Number Field in a with defining polynomial x^2 - 2 with a = 1.414213562373095? To: Number Field in b with defining polynomial x^2 - 2) - """ def create_key_and_extra_args(self, polynomial, name, check, embedding, latex_name, assume_disc_small, maximize_at_primes, structure): r""" @@ -623,7 +622,6 @@ def create_key_and_extra_args(self, polynomial, name, check, embedding, latex_na ....: latex_name=None, assume_disc_small=False, maximize_at_primes=None, structure=None) ((Rational Field, x^2 + 1, ('a',), None, 'a', None, False, None), {'check': False}) - """ if name is None: raise TypeError("You must specify the name of the generator.") @@ -678,7 +676,6 @@ def create_object(self, version, key, check): sage: R. = QQ[] sage: nff.create_object(None, (QQ, x^2 + 1, ('a',), None, None, None, False, None), check=False) Number Field in a with defining polynomial x^2 + 1 - """ base, polynomial, name, embedding, latex_name, maximize_at_primes, assume_disc_small, structure = key @@ -704,21 +701,21 @@ def NumberFieldTower(polynomials, names, check=True, embeddings=None, latex_name INPUT: - - ``polynomials`` -- a list of polynomials. Each entry must be polynomial + - ``polynomials`` -- list of polynomials. Each entry must be polynomial which is irreducible over the number field generated by the roots of the following entries. - - ``names`` -- a list of strings or a string, the names of the generators of + - ``names`` -- list of strings or a string, the names of the generators of the relative number fields. If a single string, then names are generated from that string. - - ``check`` -- a boolean (default: ``True``), whether to check that the + - ``check`` -- boolean (default: ``True``); whether to check that the polynomials are irreducible - - ``embeddings`` -- a list of elements or ``None`` (default: ``None``), - embeddings of the relative number fields in an ambient field. - - ``latex_names`` -- a list of strings or ``None`` (default: ``None``), names - used to print the generators for latex output. - - ``assume_disc_small`` -- a boolean (default: ``False``); if ``True``, + - ``embeddings`` -- list of elements or ``None`` (default: ``None``); + embeddings of the relative number fields in an ambient field + - ``latex_names`` -- list of strings or ``None`` (default: ``None``); names + used to print the generators for latex output + - ``assume_disc_small`` -- boolean (default: ``False``); if ``True``, assume that no square of a prime greater than PARI's ``primelimit`` - (which should be 500000); only applies for absolute fields at + (which should be 500000). Only applies for absolute fields at present. - ``maximize_at_primes`` -- ``None`` or a list of primes (default: ``None``); if not ``None``, then the maximal order is computed by @@ -868,15 +865,14 @@ def QuadraticField(D, name='a', check=True, embedding=True, latex_name='sqrt', * - ``name`` -- variable name (default: ``'a'``) - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - - ``embedding`` -- bool or square root of `D` in an - ambient field (default: ``True``) + - ``embedding`` -- boolean or square root of `D` in an ambient field + (default: ``True``) - ``latex_name`` -- latex variable name (default: `\sqrt{D}`) - - OUTPUT: A number field defined by a quadratic polynomial. Unless + OUTPUT: a number field defined by a quadratic polynomial. Unless otherwise specified, it has an embedding into `\RR` or `\CC` by sending the generator to the positive or upper-half-plane root. @@ -1041,23 +1037,24 @@ def is_AbsoluteNumberField(x): class CyclotomicFieldFactory(UniqueFactory): r""" - Return the `n`-th cyclotomic field, where n is a positive integer, - or the universal cyclotomic field if ``n==0``. + Return the `n`-th cyclotomic field, where `n` is a positive integer, + or the universal cyclotomic field if `n=0`. For the documentation of the universal cyclotomic field, see :class:`~sage.rings.universal_cyclotomic_field.UniversalCyclotomicField`. INPUT: - - ``n`` -- a nonnegative integer, default: ``0`` + - ``n`` -- nonnegative integer (default: `0`) - - ``names`` -- name of generator (default: ``zetan``) + - ``names`` -- name of generator (default: ``zetan``) - - ``bracket`` -- Defines the brackets in the case of ``n==0``, and - is ignored otherwise. Can be any even length string, with ``"()"`` being the default. + - ``bracket`` -- defines the brackets in the case of `n=0`, and + is ignored otherwise. Can be any even length string, with ``'()'`` being + the default. - - ``embedding`` -- bool or `n`-th root of unity in an - ambient field (default: ``True``) + - ``embedding`` -- boolean or `n`-th root of unity in an ambient field + (default: ``True``) EXAMPLES: @@ -1078,7 +1075,7 @@ class CyclotomicFieldFactory(UniqueFactory): zeta7 The default embedding sends the generator to the complex primitive - `n^{th}` root of unity of least argument. + `n`-th root of unity of least argument. :: @@ -1318,7 +1315,6 @@ class NumberField_generic(WithEqualityById, number_field_base.NumberField): ....: for f in D: ....: elt = f.q_eigenform(10, 'alpha')[3] ....: assert elt.is_integral() - """ def __init__(self, polynomial, name, latex_name, check=True, embedding=None, category=None, @@ -1442,7 +1438,6 @@ def _convert_map_from_(self, other): 1/6*b^3 + 1/6*b sage: L(b) i - a - """ from sage.categories.map import Map if self._structure is not None: @@ -1576,7 +1571,6 @@ def construction(self): sage: F, R = K.construction() sage: F(R) == K True - """ from sage.categories.pushout import AlgebraicExtensionFunctor from sage.rings.rational_field import QQ @@ -2102,21 +2096,20 @@ def random_element(self, num_bound=None, den_bound=None, INPUT: - - ``num_bound`` -- Bound on numerator of the coefficients of + - ``num_bound`` -- bound on numerator of the coefficients of the resulting element - - ``den_bound`` -- Bound on denominators of the coefficients + - ``den_bound`` -- bound on denominators of the coefficients of the resulting element - - ``integral_coefficients`` -- (default: ``False``) If ``True``, then - the resulting element will have integral - coefficients. This option overrides any - value of ``den_bound``. + - ``integral_coefficients`` -- boolean (default: ``False``); if + ``True``, then the resulting element will have integral coefficients. + This option overrides any value of ``den_bound``. - - ``distribution`` -- Distribution to use for the coefficients + - ``distribution`` -- distribution to use for the coefficients of the resulting element - OUTPUT: Element of this number field + OUTPUT: element of this number field EXAMPLES:: @@ -2182,14 +2175,14 @@ def subfield(self, alpha, name=None, names=None): INPUT: - - ``alpha`` -- an element of ``self``, or something that - coerces to an element of ``self``. + - ``alpha`` -- an element of ``self``, or something that + coerces to an element of ``self`` OUTPUT: - ``K`` -- a number field - ``from_K`` -- a homomorphism from `K` to ``self`` that - sends the generator of `K` to ``alpha``. + sends the generator of `K` to ``alpha`` EXAMPLES:: @@ -2358,17 +2351,17 @@ def subfield_from_elements(self, alpha, name=None, polred=True, threshold=None): - ``name`` -- a name for the generator of the new number field - - ``polred`` -- (boolean, default ``True``); whether to optimize the generator of - the newly created field + - ``polred`` -- boolean (default: ``True``); whether to optimize the + generator of the newly created field - - ``threshold`` -- (positive number, default ``None``) threshold to be passed to - the ``do_polred`` function + - ``threshold`` -- positive number (default: ``None``) threshold to be + passed to the ``do_polred`` function OUTPUT: a triple ``(field, beta, hom)`` where - ``field`` -- a subfield of this number field - - ``beta`` -- a list of elements of ``field`` corresponding to ``alpha`` + - ``beta`` -- list of elements of ``field`` corresponding to ``alpha`` - ``hom`` -- inclusion homomorphism from ``field`` to ``self`` @@ -2551,11 +2544,11 @@ def quadratic_defect(self, a, p, check=True): - ``p`` -- a prime ideal - - ``check`` -- (default: ``True``); check if `p` is prime + - ``check`` -- boolean (default: ``True``); check if `p` is prime ALGORITHM: - This is an implementation of Algorithm 3.1.3 from [Kir2016]_ + This is an implementation of Algorithm 3.1.3 from [Kir2016]_. EXAMPLES:: @@ -2684,7 +2677,6 @@ def is_isomorphic(self, other, isomorphism_maps=False) -> bool: sage: k. = NumberField(x) sage: k.is_isomorphic(k) True - """ if not isinstance(other, NumberField_generic): raise ValueError("other must be a generic number field.") @@ -2870,7 +2862,7 @@ def complex_conjugation(self): This is only well-defined for fields contained in CM fields (i.e. for totally real fields and CM fields). Recall that a CM field is a totally imaginary quadratic extension of a totally - real field. For other fields, a :class:`ValueError` is raised. + real field. For other fields, a :exc:`ValueError` is raised. EXAMPLES:: @@ -3039,7 +3031,6 @@ def maximal_totally_real_subfield(self): polynomial x^4 - 2*x^3 + x^2 + 6*x + 3 To: Number Field in z with defining polynomial x^2 - 1/2*a over its base field] - """ try: @@ -3179,7 +3170,6 @@ def real_embeddings(self, prec=53): 0 sage: len(K.embeddings(AA)) 0 - """ K = sage.rings.real_mpfr.RealField(prec) return self.embeddings(K) @@ -3306,18 +3296,16 @@ def algebraic_closure(self): @cached_method def conductor(self, check_abelian=True): r""" - Computes the conductor of the abelian field `K`. + Compute the conductor of the abelian field `K`. If ``check_abelian`` is set to ``False`` and the field is not an abelian extension of `\QQ`, the output is not meaningful. INPUT: - - ``check_abelian`` -- a boolean (default: ``True``); check to see + - ``check_abelian`` -- boolean (default: ``True``); check to see that this is an abelian extension of `\QQ` - OUTPUT: - - Integer which is the conductor of the field. + OUTPUT: integer which is the conductor of the field EXAMPLES:: @@ -3388,7 +3376,7 @@ def dirichlet_group(self): The output is random if the field is not abelian. - OUTPUT: a list of Dirichlet characters + OUTPUT: list of Dirichlet characters EXAMPLES:: @@ -3448,7 +3436,6 @@ def _repr_(self): sage: k. = NumberField(x^13 - (2/3)*x + 3, embedding=-1) sage: k._repr_() 'Number Field in a with defining polynomial x^13 - 2/3*x + 3 with a = -1.106745229567614?' - """ result = "Number Field in {} with defining polynomial {}".format(self.variable_name(), self.polynomial()) gen = self.gen_embedding() @@ -3553,9 +3540,9 @@ def idealchinese(self, ideals, residues): INPUT: - - ``ideals`` -- a list of ideals of the number field. + - ``ideals`` -- list of ideals of the number field - - ``residues`` -- a list of elements of the number field. + - ``residues`` -- list of elements of the number field OUTPUT: @@ -3615,10 +3602,7 @@ def fractional_ideal(self, *gens, **kwds): INPUT: - - - ``gens`` -- a list of generators, or a number field - ideal. - + - ``gens`` -- list of generators, or a number field ideal EXAMPLES:: @@ -3667,9 +3651,9 @@ def ideals_of_bdd_norm(self, bound): INPUT: - - ``bound`` -- a positive integer + - ``bound`` -- positive integer - OUTPUT: A dict of all integral ideals `I` such that Norm(`I`) `\leq` ``bound``, + OUTPUT: a dict of all integral ideals `I` such that Norm(`I`) `\leq` ``bound``, keyed by norm. EXAMPLES:: @@ -3723,15 +3707,15 @@ def primes_above(self, x, degree=None): INPUT: - - ``x`` -- usually an element or ideal of ``self``. It - should be such that ``self.ideal(x)`` is sensible. This excludes `x=0`. + - ``x`` -- usually an element or ideal of ``self``. It should be such + that ``self.ideal(x)`` is sensible. This excludes `x=0`. - - ``degree`` -- (default: ``None``) ``None`` or an integer. - If ``None``, find all primes above `x` of any degree. If an - integer, find all primes above `x` such that the resulting - residue field has exactly this degree. + - ``degree`` -- (default: ``None``) ``None`` or an integer. + If ``None``, find all primes above `x` of any degree. If an + integer, find all primes above `x` such that the resulting + residue field has exactly this degree. - OUTPUT: A list of prime ideals of ``self`` lying over `x`. If ``degree`` + OUTPUT: list of prime ideals of ``self`` lying over `x`. If ``degree`` is specified and no such ideal exists, returns the empty list. The output is sorted by residue degree first, then by underlying prime (or equivalently, by norm). @@ -3826,16 +3810,16 @@ def prime_above(self, x, degree=None): INPUT: - - ``x`` -- usually an element or ideal of ``self``. It - should be such that ``self.ideal(x)`` is sensible. This excludes `x=0`. + - ``x`` -- usually an element or ideal of ``self``. It should be such + that ``self.ideal(x)`` is sensible. This excludes `x=0`. - - ``degree`` -- (default: ``None``) ``None`` or an integer. - If one, find a prime above `x` of any degree. If an integer, find a - prime above `x` such that the resulting residue field has exactly - this degree. + - ``degree`` -- (default: ``None``) ``None`` or an integer. + If one, find a prime above `x` of any degree. If an integer, find a + prime above `x` such that the resulting residue field has exactly + this degree. - OUTPUT: A prime ideal of ``self`` lying over `x`. If ``degree`` is specified - and no such ideal exists, raises a :class:`ValueError`. + OUTPUT: a prime ideal of ``self`` lying over `x`. If ``degree`` is specified + and no such ideal exists, raises a :exc:`ValueError`. EXAMPLES:: @@ -3904,7 +3888,6 @@ def prime_above(self, x, degree=None): Traceback (most recent call last): ... AttributeError: 'NumberFieldIdeal' object has no attribute 'prime_factors'... - """ ids = self.primes_above(x, degree) if not ids: @@ -3917,8 +3900,8 @@ def primes_of_bounded_norm(self, B): INPUT: - - ``B`` -- a positive integer or real; upper bound on the norms of the - primes generated. + - ``B`` -- positive integer or real; upper bound on the norms of the + primes generated OUTPUT: @@ -3927,7 +3910,7 @@ def primes_of_bounded_norm(self, B): using the comparison function for ideals, which is based on the Hermite Normal Form. - .. note:: + .. NOTE:: See also :meth:`primes_of_bounded_norm_iter` for an iterator version of this, but note that the iterator sorts @@ -3969,9 +3952,9 @@ def primes_of_bounded_norm(self, B): from sage.rings.fast_arith import prime_range if self is QQ: - return prime_range(B + 1, algorithm="pari_isprime") + return prime_range(B + 1, algorithm='pari_isprime') else: - P = (pp for p in prime_range(B + 1, algorithm="pari_isprime") + P = (pp for p in prime_range(B + 1, algorithm='pari_isprime') for pp in self.primes_above(p)) P = [p for p in P if p.norm() <= B] P.sort(key=lambda P: (P.norm(), P)) @@ -3983,15 +3966,15 @@ def primes_of_bounded_norm_iter(self, B): INPUT: - - ``B`` -- a positive integer or real; upper bound on the norms of the - primes generated. + - ``B`` -- positive integer or real; upper bound on the norms of the + primes generated OUTPUT: An iterator over all prime ideals of this number field of norm at most `B`. - .. note:: + .. NOTE:: The output is not sorted by norm, but by size of the underlying rational prime. @@ -4021,10 +4004,10 @@ def primes_of_bounded_norm_iter(self, B): from sage.rings.fast_arith import prime_range if self is QQ: - for p in prime_range(B + 1, algorithm="pari_isprime"): + for p in prime_range(B + 1, algorithm='pari_isprime'): yield p else: - for p in prime_range(B + 1, algorithm="pari_isprime"): + for p in prime_range(B + 1, algorithm='pari_isprime'): for pp in self.primes_above(p): if pp.norm() <= B: yield pp @@ -4088,15 +4071,13 @@ def primes_of_degree_one_list(self, n, num_integer_primes=10000, max_iterations= INPUT: - - ``num_integer_primes`` -- (default: 10000) an - integer. We try to find primes of absolute norm no greater than the - ``num_integer_primes``-th prime number. For example, if - ``num_integer_primes`` is 2, the largest norm found will be 3, since - the second prime is 3. + - ``num_integer_primes`` -- integer (default: 10000). We try to find + primes of absolute norm no greater than the ``num_integer_primes``-th + prime number. For example, if ``num_integer_primes`` is 2, the + largest norm found will be 3, since the second prime is 3. - - ``max_iterations`` -- (default: 100) an integer. We - test ``max_iterations`` integers to find small primes before raising - :class:`StopIteration`. + - ``max_iterations`` -- integer (default: 100). We test ``max_iterations`` + integers to find small primes before raising :class:`StopIteration`. EXAMPLES:: @@ -4120,11 +4101,9 @@ def completely_split_primes(self, B=200): INPUT: - - ``B`` -- a positive integer bound (default: 200) - - OUTPUT: + - ``B`` -- positive integer bound (default: 200) - A list of all primes `p < B` which split completely in ``K``. + OUTPUT: list of all primes `p < B` which split completely in ``K`` EXAMPLES:: @@ -4303,8 +4282,8 @@ def pari_nf(self, important=True): INPUT: - - ``important`` -- boolean (default: ``True``). If ``False``, - raise a :class:`RuntimeError` if we need to do a difficult + - ``important`` -- boolean (default: ``True``); if ``False``, + raise a :exc:`RuntimeError` if we need to do a difficult discriminant factorization. This is useful when an integral basis is not strictly required, such as for factoring polynomials over this number field. @@ -4425,16 +4404,13 @@ def pari_bnf(self, proof=None, units=True): INPUT: - - ``proof`` -- If ``False``, assume GRH. If ``True``, run PARI's - :pari:`bnfcertify` to make sure that the results are correct. - - - ``units`` -- (default: ``True) If ``True``, insist on having - fundamental units. If ``False``, the units may or may not be - computed. + - ``proof`` -- if ``False``, assume GRH; if ``True``, run PARI's + :pari:`bnfcertify` to make sure that the results are correct - OUTPUT: + - ``units`` -- (default: ``True) if ``True``, insist on having + fundamental units; if ``False``, the units may or may not be computed - The PARI ``bnf`` structure of this number field. + OUTPUT: the PARI ``bnf`` structure of this number field .. warning:: @@ -4563,14 +4539,13 @@ def class_group(self, proof=None, names='c'): INPUT: - - ``proof`` -- if ``True`` then compute the class group - provably correctly. Default is ``True``. Call :func:`number_field_proof` to - change this default globally. + - ``proof`` -- if ``True`` (default), then compute the class group + provably correctly; call :func:`number_field_proof` to change this + default globally - - ``names`` -- names of the generators of this class - group. + - ``names`` -- names of the generators of this class group - OUTPUT: The class group of this number field. + OUTPUT: the class group of this number field EXAMPLES:: @@ -4625,9 +4600,8 @@ def class_group(self, proof=None, names='c'): default assume the Generalized Riemann Hypothesis. To do class groups computations not provably correctly you must often pass the flag ``proof=False`` to functions or call the function - ``proof.number_field(False)``. It can easily take 1000's of times + ``proof.number_field(False)``. It can easily take 1000s of times longer to do computations with ``proof=True`` (the default). - """ proof = proof_flag(proof) try: @@ -4652,7 +4626,7 @@ def class_number(self, proof=None): INPUT: - - ``proof`` -- bool (default: ``True`` unless you called + - ``proof`` -- boolean (default: ``True``, unless you called ``number_field_proof``) EXAMPLES:: @@ -4674,15 +4648,15 @@ def S_class_group(self, S, proof=None, names='c'): INPUT: - - ``S`` -- a set of primes of the base field + - ``S`` -- set of primes of the base field - - ``proof`` -- if False, assume the GRH in computing the class group. - Default is ``True``. Call ``number_field_proof`` to change this - default globally. + - ``proof`` -- if ``False``, assume the GRH in computing the class + group. Default is ``True``. Call ``number_field_proof`` to change + this default globally. - - ``names`` -- names of the generators of this class group. + - ``names`` -- names of the generators of this class group - OUTPUT: The S-class group of this number field. + OUTPUT: the S-class group of this number field EXAMPLES: @@ -4731,13 +4705,13 @@ def S_units(self, S, proof=True): INPUT: - - ``S`` -- a set of primes of the base field + - ``S`` -- set of primes of the base field - ``proof`` -- if ``False``, assume the GRH in computing the class group - OUTPUT: A list of generators of the unit group. + OUTPUT: list of generators of the unit group - .. note:: + .. NOTE:: For more functionality see the function :func:`S_unit_group`. @@ -4780,7 +4754,6 @@ def S_units(self, S, proof=True): sage: J = K.ideal(-2) sage: K.S_units([I, J, I]) [2, -1] - """ return self._S_class_group_and_units(tuple(S), proof=proof)[0] @@ -4791,17 +4764,17 @@ def _S_class_group_and_units(self, S, proof=True): INPUT: - - ``S`` -- a tuple of prime ideals of ``self`` + - ``S`` -- tuple of prime ideals of ``self`` - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: - - ``units`` -- A list of generators of the unit group. + - ``units``: a list of generators of the unit group - - ``clgp_gens`` -- A list of generators of the `S`-class group. + - ``clgp_gens`` -- a list of generators of the `S`-class group. Each generator is represented as a pair ``(gen, order)``, - where ``gen`` is a fractional ideal of self and ``order`` is + where ``gen`` is a fractional ideal of ``self`` and ``order`` is its order in the `S`-class group. EXAMPLES:: @@ -4907,14 +4880,14 @@ def selmer_generators(self, S, m, proof=True, orders=False): INPUT: - - ``S`` -- a set of primes of ``self`` + - ``S`` -- set of primes of ``self`` - - ``m`` -- a positive integer + - ``m`` -- positive integer - ``proof`` -- if ``False``, assume the GRH in computing the class group - - ``orders`` -- (default: ``False``) if ``True``, output two lists, the - generators and their orders + - ``orders`` -- boolean (default: ``False``); if ``True``, output two + lists, the generators and their orders OUTPUT: @@ -5033,7 +5006,6 @@ def selmer_generators(self, S, m, proof=True, orders=False): sage: S = K.selmer_generators((), 4) sage: all(4.divides(x.valuation(p)) for x in S) True - """ units, clgp_gens = self._S_class_group_and_units(tuple(S), proof=proof) gens = [] @@ -5085,9 +5057,9 @@ def selmer_group_iterator(self, S, m, proof=True): INPUT: - - ``S`` -- a set of primes of ``self`` + - ``S`` -- set of primes of ``self`` - - ``m`` -- a positive integer + - ``m`` -- positive integer - ``proof`` -- if ``False``, assume the GRH in computing the class group @@ -5131,11 +5103,11 @@ def selmer_space(self, S, p, proof=None): INPUT: - - ``S`` -- a set of primes ideals of ``self`` + - ``S`` -- set of primes ideals of ``self`` - ``p`` -- a prime number - - ``proof`` -- if False, assume the GRH in computing the class group + - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: @@ -5225,7 +5197,6 @@ def selmer_space(self, S, p, proof=None): sage: K.hilbert_class_field('b') Number Field in b with defining polynomial x^2 + 1 over its base field - """ from sage.rings.number_field.selmer_group import pSelmerGroup return pSelmerGroup(self, S, p, proof) @@ -5245,9 +5216,7 @@ def composite_fields(self, other, names=None, both_maps=False, preserve_embeddin - ``preserve_embedding`` -- boolean (default: ``True``) - OUTPUT: - - A list of the composite fields, possibly with maps. + OUTPUT: list of the composite fields, possibly with maps If ``both_maps`` is ``True``, the list consists of quadruples ``(F, self_into_F, other_into_F, k)`` such that @@ -5703,9 +5672,7 @@ def discriminant(self, v=None): - ``v`` -- (optional) list of elements of this number field - OUTPUT: - - Integer if ``v`` is omitted, and Rational otherwise. + OUTPUT: integer if ``v`` is omitted, and Rational otherwise EXAMPLES:: @@ -5968,7 +5935,7 @@ def decomposition_type(self, p): INPUT: - - ``p`` -- a prime element or ideal of the base field. + - ``p`` -- a prime element or ideal of the base field OUTPUT: @@ -6071,10 +6038,7 @@ def gen(self, n=0): INPUT: - - - ``n`` -- must be 0 (the default), or an exception is - raised. - + - ``n`` -- must be 0 (the default), or an exception is raised EXAMPLES:: @@ -6213,15 +6177,15 @@ def galois_group(self, type=None, algorithm='pari', names=None, gc_numbering=Non INPUT: - - ``type`` -- Deprecated; the different versions of Galois groups have been - merged in :issue:`28782`. + - ``type`` -- deprecated; the different versions of Galois groups have been + merged in :issue:`28782` - - ``algorithm`` -- ``'pari'``, ``'gap'``, ``'kash'``, ``'magma'``. (default: ``'pari'``; - for degrees between 12 and 15 default is ``'gap'``, and - when the degree is >= 16 it is ``'kash'``.) + - ``algorithm`` -- ``'pari'``, ``'gap'``, ``'kash'``, or ``'magma'`` + (default: ``'pari'``); for degrees between 12 and 15 default is + ``'gap'``, and when the degree is >= 16 it is ``'kash'``) - - ``names`` -- a string giving a name for the generator of the Galois - closure of ``self``, when this field is not Galois. + - ``names`` -- string giving a name for the generator of the Galois + closure of ``self``, when this field is not Galois - ``gc_numbering`` -- if ``True``, permutations will be written in terms of the action on the roots of a defining polynomial @@ -6310,7 +6274,7 @@ def galois_group(self, type=None, algorithm='pari', names=None, gc_numbering=Non We check that the changes in :issue:`28782` won't break code that used v1 Galois groups:: sage: # needs sage.groups - sage: G = NumberField(x^3 - 2, 'a').galois_group(type="pari") + sage: G = NumberField(x^3 - 2, 'a').galois_group(type='pari') ...DeprecationWarning: the different Galois types have been merged into one class See https://github.com/sagemath/sage/issues/28782 for details. sage: G.group() @@ -6343,7 +6307,6 @@ def _normalize_prime_list(self, v): (3, 5) sage: K._normalize_prime_list([3, 5, -3]) (3, 5) - """ if v is None: v = [] @@ -6395,8 +6358,8 @@ def integral_basis(self, v=None): INPUT: - - ``v`` -- ``None``, a prime, or a list of primes. See the - documentation for :meth:`maximal_order`. + - ``v`` -- ``None``, a prime, or a list of primes; see the + documentation for :meth:`maximal_order` EXAMPLES:: @@ -6426,11 +6389,11 @@ def _pari_integral_basis(self, v=None, important=True): INPUT: - - ``v`` -- ``None``, a prime, or a list of primes. See the - documentation for :meth:``maximal_order``. + - ``v`` -- ``None``, a prime, or a list of primes; see the + documentation for :meth:``maximal_order`` - - ``important`` -- boolean (default: ``True``). If ``False``, - raise a :class:`RuntimeError` if we need to do a difficult + - ``important`` -- boolean (default: ``True``); if ``False``, + raise a :exc:`RuntimeError` if we need to do a difficult discriminant factorization. This is useful when an integral basis is not strictly required. @@ -6499,8 +6462,8 @@ def reduced_basis(self, prec=None): INPUT: - - ``prec`` (default: ``None``) -- the precision with which to - compute the Minkowski embedding. + - ``prec`` -- (default: ``None``) the precision with which to + compute the Minkowski embedding OUTPUT: @@ -6573,17 +6536,17 @@ def reduced_gram_matrix(self, prec=None): INPUT: - - ``prec`` (default: ``None``) -- the precision with which - to calculate the Minkowski embedding. (See NOTE below.) + - ``prec`` -- (default: ``None``) the precision with which + to calculate the Minkowski embedding (see NOTE below) - OUTPUT: The Gram matrix `[\langle x_i,x_j \rangle]` of an LLL reduced + OUTPUT: the Gram matrix `[\langle x_i,x_j \rangle]` of an LLL reduced basis for the maximal order of ``self``, where the integral basis for ``self`` is given by `\{x_0, \dots, x_{n-1}\}`. Here `\langle , \rangle` is the usual inner product on `\RR^n`, and ``self`` is embedded in `\RR^n` by the Minkowski embedding. See the docstring for :meth:`NumberField_absolute.minkowski_embedding` for more information. - .. note:: + .. NOTE:: In the non-totally-real case, the LLL routine we call is currently PARI's :pari:`qflll`, which works with floating point @@ -6671,7 +6634,7 @@ def _positive_integral_elements_with_trace(self, C): Find all totally positive integral elements in ``self`` whose trace is between C[0] and C[1], inclusive. - .. note:: + .. NOTE:: This is currently only implemented in the case that ``self`` is totally real, since it requires exact computation of @@ -6719,8 +6682,8 @@ def narrow_class_group(self, proof=None): INPUT: - - ``proof`` -- default: ``None`` (use the global proof - setting, which defaults to ``True``). + - ``proof`` -- (default: ``None``) use the global proof setting, which + defaults to ``True`` EXAMPLES:: @@ -6742,7 +6705,7 @@ def ngens(self): """ Return the number of generators of this number field (always 1). - OUTPUT: the python integer 1. + OUTPUT: the python integer 1 EXAMPLES:: @@ -6889,7 +6852,7 @@ def regulator(self, proof=None): INPUT: - - ``proof`` -- default: ``True``, unless you set it otherwise. + - ``proof`` -- (default: ``True``) unless you set it otherwise EXAMPLES:: @@ -6919,12 +6882,11 @@ def residue_field(self, prime, names=None, check=True): this number field, or an element of the field which generates a principal prime ideal. - - ``names`` -- the name of the variable in the residue - field + - ``names`` -- the name of the variable in the residue field - - ``check`` -- whether or not to check the primality of ``prime``. + - ``check`` -- whether or not to check the primality of ``prime`` - OUTPUT: The residue field at this prime. + OUTPUT: the residue field at this prime EXAMPLES:: @@ -7012,24 +6974,22 @@ def trace_pairing(self, v): A[j, i] = t return A - def uniformizer(self, P, others="positive"): + def uniformizer(self, P, others='positive'): """ Return an element of ``self`` with valuation 1 at the prime ideal `P`. INPUT: + - ``self`` -- a number field - - ``self`` -- a number field + - ``P`` -- a prime ideal of ``self`` - - ``P`` -- a prime ideal of ``self`` + - ``others`` -- either ``'positive'`` (default), in which case the + element will have nonnegative valuation at all other primes of + ``self``, or ``'negative'``, in which case the element will have + nonpositive valuation at all other primes of ``self`` - - ``others`` -- either ``"positive"`` (default), in which - case the element will have non-negative valuation at all other - primes of ``self``, or ``"negative"``, in which case the element will have - non-positive valuation at all other primes of ``self``. - - - .. note:: + .. NOTE:: When `P` is principal (e.g., always when ``self`` has class number one) the result may or may not be a generator of `P`! @@ -7113,9 +7073,9 @@ def units(self, proof=None): INPUT: - - ``proof`` (bool, default ``True``) flag passed to PARI. + - ``proof`` -- boolean (default: ``True``); flag passed to PARI - .. note:: + .. NOTE:: For more functionality see :meth:`unit_group`. @@ -7195,9 +7155,9 @@ def unit_group(self, proof=None): INPUT: - - ``proof`` (bool, default ``True``) flag passed to PARI. + - ``proof`` -- boolean (default: ``True``); flag passed to PARI - .. note:: + .. NOTE:: The group is cached. @@ -7277,7 +7237,7 @@ def S_unit_group(self, proof=None, S=None): INPUT: - - ``proof`` -- bool (default: ``True``); flag passed to PARI + - ``proof`` -- boolean (default: ``True``); flag passed to PARI - ``S`` -- list or tuple of prime ideals, or an ideal, or a single ideal or element from which an ideal can be constructed, in @@ -7285,7 +7245,7 @@ def S_unit_group(self, proof=None, S=None): group is constructed; otherwise, the `S`-unit group is constructed. - .. note:: + .. NOTE:: The group is cached. @@ -7364,7 +7324,6 @@ def S_unit_group(self, proof=None, S=None): -1 * 2^9 * 3^5 sage: U.log(u) (1, 1, 4, 1, 5) - """ proof = proof_flag(proof) @@ -7415,11 +7374,15 @@ def S_unit_solutions(self, S=[], prec=106, include_exponents=False, include_boun INPUT: - - ``S`` -- a list of finite primes in this number field - - ``prec`` -- precision used for computations in real, complex, and p-adic fields (default: 106) - - ``include_exponents`` -- whether to include the exponent vectors in the returned value (default: ``True``). - - ``include_bound`` -- whether to return the final computed bound (default: ``False``) - - ``proof`` -- if ``False``, assume the GRH in computing the class group. Default is ``True``. + - ``S`` -- list of finite primes in this number field + - ``prec`` -- precision used for computations in real, complex, and + `p`-adic fields (default: 106) + - ``include_exponents`` -- whether to include the exponent vectors in + the returned value (default: ``True``) + - ``include_bound`` -- whether to return the final computed bound + (default: ``False``) + - ``proof`` -- if ``False``, assume the GRH in computing the class group; + default is ``True`` OUTPUT: @@ -7472,11 +7435,10 @@ def zeta(self, n=2, all=False): - ``n`` -- positive integer - - ``all`` -- boolean. If ``False`` (default), return a primitive - `n`-th root of unity in this field, or raise a :class:`ValueError` - exception if there are none. If ``True``, return a list of - all primitive `n`-th roots of unity in this field - (possibly empty). + - ``all`` -- boolean; if ``False`` (default), return a primitive + `n`-th root of unity in this field, or raise a :exc:`ValueError` + exception if there are none. If ``True``, return a list of all + primitive `n`-th roots of unity in this field (possibly empty). .. NOTE:: @@ -7576,7 +7538,7 @@ def zeta_order(self): r""" Return the number of roots of unity in this field. - .. note:: + .. NOTE:: We do not create the full unit group since that can be expensive, but we do use it if it is already known. @@ -7622,7 +7584,7 @@ def primitive_root_of_unity(self): cyclotomic fields. Repeated calls of this function may return a different value. - .. note:: + .. NOTE:: We do not create the full unit group since that can be expensive, but we do use it if it is already known. @@ -7731,17 +7693,17 @@ def solve_CRT(self, reslist, Ilist, check=True): INPUT: - - ``reslist`` -- a list of residues, i.e. integral number field elements + - ``reslist`` -- list of residues, i.e. integral number field elements - - ``Ilist`` -- a list of integral ideals, assumed pairwise coprime + - ``Ilist`` -- list of integral ideals, assumed pairwise coprime - - ``check`` -- (boolean, default ``True``) if ``True``, result is checked + - ``check`` -- boolean (default: ``True``); if ``True``, result is checked OUTPUT: An integral element `x` such that ``x - reslist[i]`` is in ``Ilist[i]`` for all `i`. - .. note:: + .. NOTE:: The current implementation requires the ideals to be pairwise coprime. A more general version would be possible. @@ -7872,7 +7834,6 @@ def valuation(self, prime): :meth:`Order.valuation() `, :meth:`pAdicGeneric.valuation() ` - """ from sage.rings.padics.padic_valuation import pAdicValuation return pAdicValuation(self, prime) @@ -7904,7 +7865,6 @@ def some_elements(self): Number Field in a with defining polynomial t sage: K.some_elements() [0, 1, 2, -1, 1/2, -1/2, 1/4, -2, 4] - """ elements = [] @@ -7961,7 +7921,7 @@ def maximal_order(self, v=None, assume_maximal='non-maximal-non-unique'): - if a list, return an order that is maximal at each prime of these primes - ``assume_maximal`` -- ``True``, ``False``, ``None``, or - ``"non-maximal-non-unique"`` (default: ``"non-maximal-non-unique"``) + ``'non-maximal-non-unique'`` (default: ``'non-maximal-non-unique'``) ignored when ``v`` is ``None``; otherwise, controls whether we assume that the order :meth:`order.is_maximal` outside of ``v``. @@ -7972,7 +7932,7 @@ def maximal_order(self, v=None, assume_maximal='non-maximal-non-unique'): - if ``None``, no assumptions are made about primes not in ``v``. - - if ``"non-maximal-non-unique"`` (deprecated), like ``False``, + - if ``'non-maximal-non-unique'`` (deprecated), like ``False``, however, the order is not a unique parent, so creating the same order later does typically not poison caches with the information that the order is not maximal. @@ -8079,7 +8039,6 @@ def maximal_order(self, v=None, assume_maximal='non-maximal-non-unique'): 400160824478095086350656915693814563600 sage: O3.is_maximal() False - """ v = self._normalize_prime_list(v) @@ -8126,7 +8085,7 @@ def _coerce_from_other_number_field(self, x): in a common field, or there is an embedding of ``x.parent()`` into ``self`` or the other way around. If no compatible embeddings are found and `x` is not in ``QQ``, then raise - ``TypeError``. This guarantees that these conversions respect + :exc:`TypeError`. This guarantees that these conversions respect the field operations and conversions between several fields commute. @@ -8139,9 +8098,7 @@ def _coerce_from_other_number_field(self, x): - ``x`` -- an element of some number field - OUTPUT: - - An element of ``self`` corresponding to ``x``. + OUTPUT: an element of ``self`` corresponding to ``x`` EXAMPLES:: @@ -8253,7 +8210,6 @@ def _coerce_from_other_number_field(self, x): AUTHORS: - Jeroen Demeyer (2011-09-30): :issue:`11869` - """ # Special case for x in QQ. This is common, so should be fast. xpol = x.polynomial() @@ -8445,7 +8401,6 @@ def _coerce_map_from_(self, R): sage: K. = NumberField(polygen(QQ)^2 - 2) sage: type(K.coerce_map_from(QQ)) - """ if R is int: return self._generic_coerce_map(R) @@ -8747,7 +8702,7 @@ def change_names(self, names): INPUT: - - ``names`` -- should be exactly one variable name. + - ``names`` -- should be exactly one variable name Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where ``from_K`` is an isomorphism from `K` to ``self`` and ``to_K`` is an @@ -8881,7 +8836,6 @@ def _subfields_helper(self, degree=0, name=None, both_maps=True, optimize=False) sage: K = F.subfields(3)[0][0] sage: K Number Field in zeta7_0 with defining polynomial x^3 + x^2 - 2*x - 1 with zeta7_0 = 1.246979603717467? - """ if name is None: name = self.variable_names() @@ -8947,7 +8901,6 @@ def _maximal_order(self, v=(), assume_maximal=None): sage: k. = NumberField(x^3 + x^2 - 2*x+8) sage: k.maximal_order() is k.maximal_order() # indirect doctest True - """ B = [self(b, check=False) for b in self._pari_integral_basis(v=v)] @@ -8963,20 +8916,20 @@ def order(self, *args, **kwds): INPUT: - - ``gens`` -- list of elements in this number field; if no generators - are given, just returns the cardinality of this number field - (`\infty`) for consistency. + - ``gens`` -- list of elements in this number field; if no generators + are given, just returns the cardinality of this number field + (`\infty`) for consistency. - - ``check_is_integral`` -- bool (default: ``True``), whether to check - that each generator is integral. + - ``check_is_integral`` -- boolean (default: ``True``); whether to + check that each generator is integral - - ``check_rank`` -- bool (default: ``True``), whether to check that the - ring generated by ``gens`` is of full rank. + - ``check_rank`` -- boolean (default: ``True``); whether to check that + the ring generated by ``gens`` is of full rank - - ``allow_subfield`` -- bool (default: ``False``), if ``True`` and the - generators do not generate an order, i.e., they generate a subring - of smaller rank, instead of raising an error, return an order in a - smaller number field. + - ``allow_subfield`` -- boolean (default: ``False``); if ``True`` and + the generators do not generate an order, i.e., they generate a + subring of smaller rank, instead of raising an error, return an order + in a smaller number field EXAMPLES:: @@ -9057,7 +9010,6 @@ def _order(self, gens, **kwds): sage: K.order(a) is K.order(a,a^2) is K.order(a^2,a) True - """ from sage.rings.number_field.order import absolute_order_from_ring_generators return absolute_order_from_ring_generators(gens, **kwds) @@ -9075,12 +9027,12 @@ def free_module(self, base=None, basis=None, map=True): - ``basis`` -- a basis for this field over the base - - ``maps`` -- boolean (default ``True``), whether to return + - ``maps`` -- boolean (default: ``True``); whether to return `R`-linear maps to and from `V` OUTPUT: - - `V` -- a vector space over the rational numbers + - ``V`` -- a vector space over the rational numbers - ``from_V`` -- an isomorphism from `V` to ``self`` (if requested) @@ -9205,7 +9157,8 @@ def galois_closure(self, names=None, map=False): - ``names`` -- variable name for Galois closure - - ``map`` -- (default: ``False``) also return an embedding of ``self`` into `K` + - ``map`` -- boolean (default: ``False``); also return an embedding of + ``self`` into `K` EXAMPLES:: @@ -9506,17 +9459,17 @@ def logarithmic_embedding(self, prec=53): Return the morphism of ``self`` under the logarithmic embedding in the category Set. - The logarithmic embedding is defined as a map from the number field ``self`` to `\RR^n`. + The logarithmic embedding is defined as a map from the number field + ``self`` to `\RR^n`. It is defined under Definition 4.9.6 in [Coh1993]_. INPUT: - - ``prec`` -- desired floating point precision. + - ``prec`` -- desired floating point precision - OUTPUT: - - the morphism of ``self`` under the logarithmic embedding in the category Set. + OUTPUT: the morphism of ``self`` under the logarithmic embedding in the + category Set EXAMPLES:: @@ -9714,9 +9667,7 @@ def abs_val(self, v, iota, prec=None): - ``iota`` -- an element of ``K`` - ``prec`` -- (default: ``None``) the precision of the real field - OUTPUT: - - The absolute value as a real number + OUTPUT: the absolute value as a real number EXAMPLES:: @@ -9775,9 +9726,7 @@ def relativize(self, alpha, names, structure=None): will return isomorphisms from and to this field. Otherwise, the field will be equipped with ``structure``. - OUTPUT: - - `K` -- relative number field + OUTPUT: `K` -- relative number field Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where ``from_K`` is an isomorphism from `K` to ``self`` and ``to_K`` is an isomorphism @@ -9952,7 +9901,6 @@ def relativize(self, alpha, names, structure=None): sage: K. = L.subfield(z24^3)[0] sage: L.relativize(K.hom(L), L.variable_name()+'0' ) Number Field in z2400 with defining polynomial x^2 + z240^3*x - z240^2 over its base field - """ # step 1: construct the abstract field generated by alpha.w # step 2: make a relative extension of it. @@ -9992,7 +9940,7 @@ def relativize(self, alpha, names, structure=None): basis.append(a**extdeg) # this one makes the basis no longer a basis mat = matrix([b.vector() for b in basis]) soln_space = mat.left_kernel(mat.row_space()(0)) - # the solution space is one dimensional and the last entry is non-zero + # the solution space is one dimensional and the last entry is nonzero # because a satisfies no smaller linear relation assert soln_space.dimension() == 1 (reln, ) = soln_space.basis() @@ -10133,7 +10081,7 @@ def relative_different(self): def hilbert_symbol(self, a, b, P=None): r""" Return the Hilbert symbol `(a,b)_P` for a prime `P` of ``self`` - and non-zero elements `a` and `b` of ``self``. + and nonzero elements `a` and `b` of ``self``. If `P` is omitted, return the global Hilbert symbol `(a,b)` instead. @@ -10141,21 +10089,19 @@ def hilbert_symbol(self, a, b, P=None): - ``a``, ``b`` -- elements of ``self`` - - ``P`` -- (default: ``None``) If ``None``, compute the global + - ``P`` -- (default: ``None``) if ``None``, compute the global symbol. Otherwise, `P` should be either a prime ideal of ``self`` (which may also be given as a generator or set of generators) or a real or complex embedding. - OUTPUT: - - If `a` or `b` is zero, returns 0. + OUTPUT: if `a` or `b` is zero, returns 0 - If `a` and `b` are non-zero and `P` is specified, returns + If `a` and `b` are nonzero and `P` is specified, returns the Hilbert symbol `(a,b)_P`, which is `1` if the equation `a x^2 + b y^2 = 1` has a solution in the completion of ``self`` at `P`, and is `-1` otherwise. - If `a` and `b` are non-zero and `P` is unspecified, returns `1` + If `a` and `b` are nonzero and `P` is unspecified, returns `1` if the equation has a solution in ``self`` and `-1` otherwise. EXAMPLES: @@ -10366,11 +10312,11 @@ def hilbert_symbol_negative_at_S(self, S, b, check=True): INPUT: - - ``S`` -- a list of places (or prime ideals) of even cardinality - - ``b`` -- a non-zero rational number which is a non-square locally - at every place in `S`. - - ``check`` -- bool (default: ``True``) perform additional checks on - the input and confirm the output + - ``S`` -- list of places (or prime ideals) of even cardinality + - ``b`` -- a nonzero rational number which is a non-square locally + at every place in `S` + - ``check`` -- boolean (default: ``True``); perform additional checks + on the input and confirm the output OUTPUT: @@ -10543,9 +10489,7 @@ def hilbert_conductor(self, a, b): - ``a``, ``b`` -- elements of the number field ``self`` - OUTPUT: - - squarefree ideal of the ring of integers of ``self`` + OUTPUT: squarefree ideal of the ring of integers of ``self`` EXAMPLES:: @@ -10589,9 +10533,7 @@ def elements_of_bounded_height(self, **kwds): This is an implementation of the revised algorithm (Algorithm 4) in [DK2013]_. Algorithm 5 is used for imaginary quadratic fields. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- a real number @@ -10599,9 +10541,7 @@ def elements_of_bounded_height(self, **kwds): - ``precision`` -- (default: 53) a positive integer - OUTPUT: - - an iterator of number field elements + OUTPUT: an iterator of number field elements EXAMPLES: @@ -10959,7 +10899,7 @@ def _magma_init_(self, magma): Function returning a string to create this cyclotomic field in Magma. - .. note:: + .. NOTE:: The Magma generator name is also initialized to be the same as for the Sage field. @@ -11401,11 +11341,11 @@ def _coerce_from_other_cyclotomic_field(self, x, only_canonical=False): INPUT: - - ``x`` -- number field element + - ``x`` -- number field element - - ``only_canonical`` -- bool (default: ``False``); Attempt - to work, even in some cases when `x` is not in a subfield of the - cyclotomics (as long as `x` is a root of unity). + - ``only_canonical`` -- boolean (default: ``False``); attempt + to work, even in some cases when `x` is not in a subfield of the + cyclotomics (as long as `x` is a root of unity) EXAMPLES:: @@ -11780,9 +11720,9 @@ def discriminant(self, v=None): INPUT: - - ``v`` -- (optional) list of elements of this number field + - ``v`` -- (optional) list of elements of this number field - OUTPUT: Integer if ``v`` is omitted, and Rational otherwise. + OUTPUT: integer if ``v`` is omitted, and Rational otherwise EXAMPLES:: @@ -11910,15 +11850,15 @@ def zeta(self, n=None, all=False): Return an element of multiplicative order `n` in this cyclotomic field. - If there is no such element, raise a :class:`ValueError`. + If there is no such element, raise a :exc:`ValueError`. INPUT: - ``n`` -- integer (default: ``None``, returns element of maximal order) - - ``all`` -- bool (default: ``False``); whether to return - a list of all primitive `n`-th roots of unity. + - ``all`` -- boolean (default: ``False``); whether to return + a list of all primitive `n`-th roots of unity OUTPUT: root of unity or list @@ -12187,7 +12127,6 @@ def _polymake_init_(self): sage: Z = QuadraticField(7) sage: polymake(Z) # optional - jupymake # indirect doctest QuadraticExtension - """ return '"QuadraticExtension"' @@ -12199,11 +12138,9 @@ def discriminant(self, v=None): INPUT: + - ``v`` -- (optional) list of element of this number field - - ``v`` -- (optional) list of element of this number field - - - OUTPUT: Integer if ``v`` is omitted, and Rational otherwise. + OUTPUT: integer if ``v`` is omitted, and Rational otherwise EXAMPLES:: @@ -12293,7 +12230,6 @@ def class_number(self, proof=None): sage: type(CyclotomicField(10).class_number()) - """ proof = proof_flag(proof) try: @@ -12308,7 +12244,7 @@ def hilbert_class_field_defining_polynomial(self, name='x'): Hilbert class field of this quadratic field as an extension of this quadratic field. - .. note:: + .. NOTE:: Computed using PARI via Schertz's method. This implementation is quite fast. @@ -12343,7 +12279,7 @@ def hilbert_class_field(self, names): Return the Hilbert class field of this quadratic field as a relative extension of this field. - .. note:: + .. NOTE:: For the polynomial that defines this field as a relative extension, see the method :meth:`hilbert_class_field_defining_polynomial`, @@ -12517,13 +12453,11 @@ def put_natural_embedding_first(v): INPUT: - - ``v`` -- a list of embeddings of a number field + - ``v`` -- list of embeddings of a number field - OUTPUT: ``None``. The - list is altered in-place, so that, if possible, the first embedding - has been switched with one of the others, so that if there is an - embedding which preserves the generator names then it appears - first. + OUTPUT: none; the list is altered in-place, so that, if possible, the first + embedding has been switched with one of the others, so that if there is an + embedding which preserves the generator names then it appears first. EXAMPLES:: @@ -12563,12 +12497,12 @@ def refine_embedding(e, prec=None): INPUT: - - ``e`` -- an embedding of a number field into either - `\RR` or `\CC` (with some precision) + - ``e`` -- an embedding of a number field into either `\RR` or `\CC` + (with some precision) - - ``prec`` -- (default ``None``) the desired precision; if ``None``, - current precision is doubled; if ``Infinity``, the equivalent - embedding into either ``QQbar`` or ``AA`` is returned. + - ``prec`` -- (default: ``None``) the desired precision; if ``None``, + current precision is doubled; if ``Infinity``, the equivalent + embedding into either ``QQbar`` or ``AA`` is returned. EXAMPLES:: @@ -12700,7 +12634,7 @@ def refine_embedding(e, prec=None): def is_real_place(v): r""" - Return ``True`` if `v` is real, ``False`` if `v` is complex + Return ``True`` if `v` is real, ``False`` if `v` is complex. INPUT: @@ -12732,7 +12666,6 @@ def is_real_place(v): Traceback (most recent call last): ... AttributeError: 'NumberFieldFractionalIdeal' object has no attribute 'im_gens'... - """ RR = sage.rings.real_mpfr.RealField(53) try: @@ -12776,7 +12709,6 @@ def _splitting_classes_gens_(K, m, d): 11 sage: _splitting_classes_gens_(L,11,5) # needs sage.libs.gap # optional - gap_package_polycyclic [10] - """ from sage.groups.abelian_gps.abelian_group import AbelianGroup diff --git a/src/sage/rings/number_field/number_field_base.pyx b/src/sage/rings/number_field/number_field_base.pyx index 651ff62f7c1..910f6ff7904 100644 --- a/src/sage/rings/number_field/number_field_base.pyx +++ b/src/sage/rings/number_field/number_field_base.pyx @@ -256,9 +256,7 @@ cdef class NumberField(Field): :meth:`~bach_bound` - OUTPUT: - - symbolic expression or Rational + OUTPUT: symbolic expression or Rational EXAMPLES: @@ -336,9 +334,7 @@ cdef class NumberField(Field): :meth:`~minkowski_bound` - OUTPUT: - - symbolic expression or the Integer 1 + OUTPUT: symbolic expression or the Integer 1 EXAMPLES: @@ -416,9 +412,7 @@ cdef class NumberField(Field): r""" Return an interval approximation of the generator of this number field. - OUTPUT: - - A real interval element with precision `53 \times 2^i`. + OUTPUT: a real interval element with precision `53 \times 2^i` EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_element.pyx b/src/sage/rings/number_field/number_field_element.pyx index 7e57bd7fc5f..53055e1e648 100644 --- a/src/sage/rings/number_field/number_field_element.pyx +++ b/src/sage/rings/number_field/number_field_element.pyx @@ -172,8 +172,8 @@ cdef class NumberFieldElement(NumberFieldElement_base): """ cdef _new(self): """ - Quickly creates a new initialized NumberFieldElement with the same - parent as self. + Quickly create a new initialized NumberFieldElement with the same + parent as ``self``. """ cdef type t = type(self) cdef NumberFieldElement x = t.__new__(t) @@ -184,8 +184,8 @@ cdef class NumberFieldElement(NumberFieldElement_base): cdef number_field(self): r""" + Return the number field of ``self``. Only accessible from Cython. - Return the number field of self. Only accessible from Cython. EXAMPLES:: sage: x = polygen(ZZ, 'x') @@ -210,9 +210,9 @@ cdef class NumberFieldElement(NumberFieldElement_base): """ INPUT: - - ``parent`` -- a number field + - ``parent`` -- a number field - - ``f`` -- defines an element of a number field. + - ``f`` -- defines an element of a number field EXAMPLES: @@ -308,7 +308,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def _lift_cyclotomic_element(self, new_parent, bint check=True, int rel=0): """ - Creates an element of the passed field from this field. This is + Create an element of the passed field from this field. This is specific to creating elements in a cyclotomic field from elements in another cyclotomic field, in the case that self.number_field()._n() divides new_parent()._n(). This @@ -449,7 +449,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): b^2 + 1 sage: (a+1)._im_gens_(m, [b^2]) b^2 + 1 - """ # NOTE -- if you ever want to change this so relative number # fields are in terms of a root of a poly. The issue is that @@ -467,7 +466,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def _latex_(self): r""" - Returns the latex representation for this element. + Return the latex representation for this element. EXAMPLES:: @@ -480,7 +479,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def _gap_init_(self): """ - Return gap string representation of self. + Return gap string representation of ``self``. EXAMPLES:: @@ -599,7 +598,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def __pari__(self, name='y'): r""" - Return PARI representation of self. + Return PARI representation of ``self``. The returned element is a PARI ``POLMOD`` in the variable ``name``, which is by default 'y' - not the name of the generator @@ -607,7 +606,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``name`` -- (default: 'y') the PARI variable name used. + - ``name`` -- (default: ``'y'``) the PARI variable name used EXAMPLES:: @@ -698,7 +697,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def _pari_init_(self, name='y'): """ - Return PARI/GP string representation of self. + Return PARI/GP string representation of ``self``. The returned string defines a PARI ``POLMOD`` in the variable ``name``, which is by default 'y' - not the name of the generator @@ -706,7 +705,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``name`` -- (default: 'y') the PARI variable name used. + - ``name`` -- (default: ``'y'``) the PARI variable name used EXAMPLES:: @@ -882,11 +881,11 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``num_bound`` -- Bound for the numerator of coefficients of result + - ``num_bound`` -- bound for the numerator of coefficients of result - - ``den_bound`` -- Bound for the denominator of coefficients of result + - ``den_bound`` -- bound for the denominator of coefficients of result - - ``distribution`` -- Distribution to use for coefficients of result + - ``distribution`` -- distribution to use for coefficients of result EXAMPLES:: @@ -1293,12 +1292,9 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: + - ``prec`` -- integer (default: ``None``); bits of precision - - ``prec`` -- (default: None) integer bits of precision - - - ``i`` -- (default: None) integer, which embedding to - use - + - ``i`` -- integer (default: ``None``); which embedding to use EXAMPLES:: @@ -1357,7 +1353,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): sage: b.abs(prec=53) 1.32471795724475 - """ if (i is None and prec is None and ( self._parent)._embedded_real): @@ -1380,10 +1375,10 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``P`` -- a prime ideal of the parent of ``self`` + - ``P`` -- a prime ideal of the parent of ``self`` - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -1392,7 +1387,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): normalised absolute value, so that the underlying prime number `p` has absolute value `1/p`. - EXAMPLES:: sage: x = polygen(ZZ, 'x') @@ -1489,9 +1483,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - - ``prec`` -- integer (default: 53) bits of precision - + - ``prec`` -- integer (default: 53); bits of precision EXAMPLES:: @@ -1571,11 +1563,11 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``L`` -- a number field containing `K` = ``self.parent()``. - - ``element`` -- ``True`` or ``False``, whether to also output an element - of which ``self`` is a norm. - - ``proof`` -- If ``True``, then the output is correct unconditionally. - If ``False``, then the output is correct under GRH. + - ``L`` -- a number field containing `K` = ``self.parent()`` + - ``element`` -- boolean; whether to also output an element + of which ``self`` is a norm + - ``proof`` -- if ``True``, then the output is correct unconditionally; + if ``False``, then the output is correct under GRH OUTPUT: @@ -1707,7 +1699,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): algorithm looks for a solution `x` that is an `S`-integer, with `S` a list of places of `L` containing at least the ramified primes, the generators of the class group of `L`, as well as those primes - dividing self. + dividing ``self``. If `L/K` is Galois, then this is enough; otherwise, ``extra_primes`` is used to add more primes to `S`: all the places @@ -1720,10 +1712,10 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - `L` -- a relative number field with base field ``self.parent()`` - - ``proof`` -- whether to certify outputs of PARI init functions. - If ``False``, truth of the output depends on GRH. - - ``extra_primes`` -- an integer as explained above. + - ``L`` -- a relative number field with base field ``self.parent()`` + - ``proof`` -- whether to certify outputs of PARI init functions; + if ``False``, truth of the output depends on GRH + - ``extra_primes`` -- integer; as explained above OUTPUT: @@ -1954,7 +1946,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): elements raised to appropriate powers, with an appropriate unit factor. - Raise :class:`ValueError` if the factorization of the + Raise :exc:`ValueError` if the factorization of the ideal (``self``) contains a non-principal prime ideal. EXAMPLES:: @@ -1982,7 +1974,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): Traceback (most recent call last): ... ArithmeticError: factorization of 0 is not defined - """ if self.is_zero(): raise ArithmeticError("factorization of 0 is not defined") @@ -2033,14 +2024,13 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``self``, ``other`` -- elements of a number field or maximal - order. + - ``self``, ``other`` -- elements of a number field or maximal order OUTPUT: - - A generator of the ideal ``(self, other)``. If the parent is - a number field, this always returns 0 or 1. For maximal orders, - this raises :class:`ArithmeticError` if the ideal is not principal. + A generator of the ideal ``(self, other)``. If the parent is + a number field, this always returns 0 or 1. For maximal orders, + this raises :exc:`ArithmeticError` if the ideal is not principal. EXAMPLES:: @@ -2149,10 +2139,8 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - - ``root`` -- if ``True``, also return a square root (or - ``None`` if ``self`` is not a perfect square) - + - ``root`` -- if ``True``, also return a square root (or ``None`` if + ``self`` is not a perfect square) EXAMPLES:: @@ -2204,7 +2192,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - ``P`` -- a prime ideal - - ``check`` -- (default: ``True``); check if `P` is prime + - ``check`` -- boolean (default: ``True``); check if `P` is prime EXAMPLES:: @@ -2222,10 +2210,10 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``all`` -- optional boolean (default ``False``); whether to return + - ``all`` -- boolean (default: ``False``); whether to return both square roots - - ``extend`` -- optional boolean (default ``True``); whether to extend + - ``extend`` -- boolean (default: ``True``); whether to extend the field by adding the square roots if needed EXAMPLES:: @@ -2304,7 +2292,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def nth_root(self, n, all=False): r""" - Return an `n`'th root of ``self`` in its parent `K`. + Return an `n`-th root of ``self`` in its parent `K`. EXAMPLES:: @@ -2330,7 +2318,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def is_nth_power(self, n): r""" - Return ``True`` if ``self`` is an `n`'th power in its parent `K`. + Return ``True`` if ``self`` is an `n`-th power in its parent `K`. EXAMPLES:: @@ -2494,7 +2482,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): cpdef _mul_(self, right): """ - Returns the product of self and other as elements of a number + Return the product of ``self`` and ``other`` as elements of a number field. EXAMPLES:: @@ -2542,7 +2530,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): cpdef _div_(self, other): """ - Returns the quotient of self and other as elements of a number + Return the quotient of ``self`` and ``other`` as elements of a number field. EXAMPLES:: @@ -2753,7 +2741,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def __invert__(self): """ - Return the multiplicative inverse of self in the number field. + Return the multiplicative inverse of ``self`` in the number field. EXAMPLES:: @@ -2792,7 +2780,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def _integer_(self, Z=None): """ - Returns an integer if this element is actually an integer. + Return an integer if this element is actually an integer. EXAMPLES:: @@ -2810,7 +2798,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): def _rational_(self): """ - Returns a rational number if this element is actually a rational + Return a rational number if this element is actually a rational number. EXAMPLES:: @@ -2844,7 +2832,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): sage: AA(alpha) Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real sage: NF. = NumberField(x^5 + 7*x + 3) @@ -2980,7 +2968,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): sage: K. = NumberField(p, embedding=rt) sage: SR(a) # needs sage.symbolic -0.3056815681115094? - """ K = self._parent.fraction_field() @@ -3073,7 +3060,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): This is only well-defined for fields contained in CM fields (i.e. for totally real fields and CM fields). Recall that a CM field is a totally imaginary quadratic extension of a totally - real field. For other fields, a :class:`ValueError` is raised. + real field. For other fields, a :exc:`ValueError` is raised. EXAMPLES:: @@ -3096,7 +3083,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): sage: j.conjugate() -j - Raise a :class:`ValueError` if the field is not contained in a CM field. + Raise a :exc:`ValueError` if the field is not contained in a CM field. :: @@ -3124,7 +3111,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): -1/2*a^3 - a - 1/2 sage: (2*a^2 - 1).conjugate() a^3 - 2*a^2 - 2 - """ nf = self.number_field() @@ -3171,7 +3157,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): 1/2*x^3 + 3*x - 1/2 sage: R(list(b)) y - """ from sage.rings.polynomial.polynomial_ring_constructor import _single_variate as Pol return Pol(QQ, var)(self._coefficients()) @@ -3235,10 +3220,8 @@ cdef class NumberFieldElement(NumberFieldElement_base): Return the coefficients of the underlying polynomial corresponding to this number field element. - OUTPUT: - - - a list whose length corresponding to the degree of this - element written in terms of a generator + OUTPUT: list whose length corresponding to the degree of this element + written in terms of a generator EXAMPLES:: @@ -3740,9 +3723,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - - ``base`` -- field or morphism - + - ``base`` -- field or morphism EXAMPLES: @@ -3863,7 +3844,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``P`` -- a prime ideal of the parent of ``self`` + - ``P`` -- a prime ideal of the parent of ``self`` .. NOTE:: @@ -3930,18 +3911,17 @@ cdef class NumberFieldElement(NumberFieldElement_base): def local_height(self, P, prec=None, weighted=False): r""" - Returns the local height of ``self`` at a given prime ideal `P`. + Return the local height of ``self`` at a given prime ideal `P`. INPUT: - - ``P`` -- a prime ideal of the parent of ``self`` - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer; (default: default :class:`RealField` precision); + desired floating point precision - - ``weighted`` (bool, default ``False``) -- if ``True``, apply local - degree weighting. + - ``weighted`` -- boolean (default: ``False``); if ``True``, apply local + degree weighting OUTPUT: @@ -3987,23 +3967,23 @@ cdef class NumberFieldElement(NumberFieldElement_base): def local_height_arch(self, i, prec=None, weighted=False): r""" - Returns the local height of ``self`` at the `i`'th infinite place. + Return the local height of ``self`` at the `i`-th infinite place. INPUT: - - ``i`` (int) -- an integer in ``range(r+s)`` where `(r,s)` is the - signature of the parent field (so `n=r+2s` is the degree). + - ``i`` -- integer in ``range(r+s)`` where `(r,s)` is the signature of + the parent field (so `n=r+2s` is the degree) - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision - - ``weighted`` (bool, default ``False``) -- if ``True``, apply local - degree weighting, i.e. double the value for complex places. + - ``weighted`` -- boolean (default: ``False``); if ``True``, apply local + degree weighting, i.e. double the value for complex places OUTPUT: (real) The archimedean local height of this number field - element at the `i`'th infinite place. If ``weighted`` is + element at the `i`-th infinite place. If ``weighted`` is ``True``, this is multiplied by the local degree (as required for global heights), i.e. 1 for real places and 2 for complex places. @@ -4051,8 +4031,8 @@ cdef class NumberFieldElement(NumberFieldElement_base): INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default RealField precision). + - ``prec`` -- integer (default: default RealField precision); desired + floating point precision OUTPUT: @@ -4101,12 +4081,12 @@ cdef class NumberFieldElement(NumberFieldElement_base): def global_height_arch(self, prec=None): """ - Returns the total archimedean component of the height of ``self``. + Return the total archimedean component of the height of ``self``. INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -4128,12 +4108,12 @@ cdef class NumberFieldElement(NumberFieldElement_base): def global_height(self, prec=None): """ - Returns the absolute logarithmic height of this number field element. + Return the absolute logarithmic height of this number field element. INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -4175,7 +4155,6 @@ cdef class NumberFieldElement(NumberFieldElement_base): 0.346573590279973 sage: (1/s).global_height() #make sure that 11758 is fixed 0.346573590279973 - """ return (self.global_height_non_arch(prec)+self.global_height_arch(prec))/self.number_field().absolute_degree() @@ -4246,7 +4225,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): """ Return the support of this number field element. - OUTPUT: A sorted list of the prime ideals at which this number + OUTPUT: a sorted list of the prime ideals at which this number field element has nonzero valuation. An error is raised if the element is zero. @@ -4366,14 +4345,14 @@ cdef class NumberFieldElement(NumberFieldElement_base): def inverse_mod(self, I): r""" - Returns the inverse of ``self`` mod the integral ideal `I`. + Return the inverse of ``self`` mod the integral ideal `I`. INPUT: - - ``I`` -- may be an ideal of ``self.parent()``, or an element or list - of elements of ``self.parent()`` generating a nonzero ideal. A :class:`ValueError` - is raised if `I` is non-integral or zero. A :class:`ZeroDivisionError` is - raised if `I + (x) \neq (1)`. + - ``I`` -- may be an ideal of ``self.parent()``, or an element or list + of elements of ``self.parent()`` generating a nonzero ideal. A + :exc:`ValueError` is raised if `I` is non-integral or zero. A + :exc:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. .. NOTE:: @@ -4420,7 +4399,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): .. NOTE:: can also be called for an ideal from sage.rings.number_field_ideal.residue_symbol - .. NOTE:: self is coerced into the number field of the ideal P + .. NOTE:: ``self`` is coerced into the number field of the ideal P .. NOTE:: @@ -4433,9 +4412,7 @@ cdef class NumberFieldElement(NumberFieldElement_base): - ``m`` -- positive integer - OUTPUT: - - - an `m`-th root of unity in the number field + OUTPUT: an `m`-th root of unity in the number field EXAMPLES: @@ -4463,35 +4440,34 @@ cdef class NumberFieldElement(NumberFieldElement_base): sage: (w^2 + 3).residue_symbol(K.ideal(17),3) -w - The field must contain the m-th roots of unity:: + The field must contain the `m`-th roots of unity:: sage: K. = NumberField(x^2 - x + 1) sage: (w^2 + 3).residue_symbol(K.ideal(17),5) Traceback (most recent call last): ... ValueError: The residue symbol to that power is not defined for the number field - """ return P.residue_symbol(self,m,check) def descend_mod_power(self, K=QQ, d=2): r""" Return a list of elements of the subfield `K` equal to - ``self`` modulo `d`'th powers. + ``self`` modulo `d`-th powers. INPUT: - - ``K`` (number field, default `\QQ`) -- a subfield of the + - ``K`` -- number field (default: `\QQ`); a subfield of the parent number field `L` of ``self`` - - ``d`` (positive integer, default 2) -- an integer at least 2 + - ``d`` -- positive integer (default: 2); an integer at least 2 OUTPUT: A list, possibly empty, of elements of `K` equal to ``self`` - modulo `d`'th powers, i.e. the preimages of ``self`` under the + modulo `d`-th powers, i.e. the preimages of ``self`` under the map `K^*/(K^*)^d \rightarrow L^*/(L^*)^d` where `L` is the - parent of ``self``. A :class:`ValueError` is raised if `K` does + parent of ``self``. A :exc:`ValueError` is raised if `K` does not embed into `L`. ALGORITHM: @@ -4650,12 +4626,10 @@ cdef class NumberFieldElement_absolute(NumberFieldElement): INPUT: - - - ``magma`` -- a Magma interpreter - + - ``magma`` -- a Magma interpreter OUTPUT: MagmaElement that has parent the Magma object corresponding - to the parent number field. + to the parent number field EXAMPLES:: @@ -4860,7 +4834,6 @@ cdef class NumberFieldElement_absolute(NumberFieldElement): sage: K. = QuadraticField(-3) sage: a.lift() x - """ R = self.number_field().base_field()[var] return R(self.list()) @@ -4924,7 +4897,7 @@ cdef class NumberFieldElement_relative(NumberFieldElement): The current relative number field element implementation does everything in terms of absolute polynomials. - All conversions from relative polynomials, lists, vectors, etc + All conversions from relative polynomials, lists, vectors, etc. should happen in the parent. """ def __init__(self, parent, f): @@ -5021,7 +4994,6 @@ cdef class NumberFieldElement_relative(NumberFieldElement): sage: u = L(1/2*a + 1/2 + b + (a-9)*b^5) sage: u.lift() (a - 9)*x^5 + x + 1/2*a + 1/2 - """ K = self.number_field() # Compute representation of self in terms of relative vector space. @@ -5191,7 +5163,8 @@ cdef class NumberFieldElement_relative(NumberFieldElement): INPUT: - - ``P`` -- a prime ideal of relative number field which is the parent of ``self`` + - ``P`` -- a prime ideal of relative number field which is the parent + of ``self`` EXAMPLES:: @@ -5247,7 +5220,7 @@ cdef class OrderElement_absolute(NumberFieldElement_absolute): cdef _new(self): """ - Quickly creates a new initialized NumberFieldElement with the same + Quickly create a new initialized NumberFieldElement with the same parent as ``self``. EXAMPLES: @@ -5288,10 +5261,10 @@ cdef class OrderElement_absolute(NumberFieldElement_absolute): INPUT: - - ``I`` -- may be an ideal of ``self.parent()``, or an - element or list of elements of ``self.parent()`` generating a nonzero - ideal. A :class:`ValueError` is raised if `I` is non-integral or is zero. - A :class:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. + - ``I`` -- may be an ideal of ``self.parent()``, or an element or list + of elements of ``self.parent()`` generating a nonzero ideal. A + :exc:`ValueError` is raised if `I` is non-integral or is zero. A + :exc:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. EXAMPLES:: @@ -5366,8 +5339,8 @@ cdef class OrderElement_relative(NumberFieldElement_relative): cdef _new(self): """ - Quickly creates a new initialized NumberFieldElement with the same - parent as self. + Quickly create a new initialized NumberFieldElement with the same + parent as ``self``. EXAMPLES: @@ -5420,12 +5393,10 @@ cdef class OrderElement_relative(NumberFieldElement_relative): INPUT: - - - ``I`` -- may be an ideal of ``self.parent()``, or an - element or list of elements of ``self.parent()`` generating a nonzero - ideal. A :class:`ValueError` is raised if `I` is non-integral or is zero. - A :class:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. - + - ``I`` -- may be an ideal of ``self.parent()``, or an + element or list of elements of ``self.parent()`` generating a nonzero + ideal. A :exc:`ValueError` is raised if `I` is non-integral or is zero. + A :exc:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. EXAMPLES:: @@ -5631,7 +5602,7 @@ class CoordinateFunction(): def __eq__(self, other): """ - Test equality + Test equality. EXAMPLES:: @@ -5657,7 +5628,7 @@ class CoordinateFunction(): def __ne__(self, other): """ - Test inequality + Test inequality. EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_element_base.pyx b/src/sage/rings/number_field/number_field_element_base.pyx index 5fee5817cbc..759209f8bb3 100644 --- a/src/sage/rings/number_field/number_field_element_base.pyx +++ b/src/sage/rings/number_field/number_field_element_base.pyx @@ -13,10 +13,11 @@ Number field elements (abstract base class) cdef class NumberFieldElement_base(FieldElement): r""" - Abstract base class for :class:`~sage.rings.number_field.number_field_element.NumberFieldElement` + Abstract base class for + :class:`~sage.rings.number_field.number_field_element.NumberFieldElement`. - This class is defined for the purpose of :func:`isinstance` tests. It should not be - instantiated. + This class is defined for the purpose of :func:`isinstance` tests. + It should not be instantiated. EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_element_quadratic.pyx b/src/sage/rings/number_field/number_field_element_quadratic.pyx index ef924174a9e..e3062448708 100644 --- a/src/sage/rings/number_field/number_field_element_quadratic.pyx +++ b/src/sage/rings/number_field/number_field_element_quadratic.pyx @@ -227,8 +227,8 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): cdef _new(self): """ - Quickly creates a new initialized NumberFieldElement_quadratic with the - same parent as self. + Quickly create a new initialized NumberFieldElement_quadratic with the + same parent as ``self``. EXAMPLES:: @@ -472,7 +472,7 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): def _lift_cyclotomic_element(self, new_parent, bint check=True, int rel=0): """ - Creates an element of the passed field from this field. This + Create an element of the passed field from this field. This is specific to creating elements in a cyclotomic field from elements in another cyclotomic field, in the case that self.number_field()._n() divides new_parent()._n(). This @@ -943,7 +943,8 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): def sign(self): r""" - Returns the sign of ``self`` (`0` if zero, `+1` if positive, and `-1` if negative). + Return the sign of ``self`` (`0` if zero, `+1` if positive, and `-1` if + negative). EXAMPLES:: @@ -1296,7 +1297,7 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): r""" Reduces into canonical form. - WARNING: this mutates self. + WARNING: this mutates ``self``. """ cdef mpz_t gcd # cancel out common factors @@ -1470,7 +1471,6 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): sage: K. = QuadraticField(5, embedding=AA(5).sqrt()) sage: sqrt5*vector([1,2]) (sqrt5, 2*sqrt5) - """ cdef NumberFieldElement_quadratic other = other_m cdef NumberFieldElement_quadratic res = self._new() @@ -2072,7 +2072,6 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): Traceback (most recent call last): ... ValueError: no way to embed L into parent's base ring K - """ cdef Rational res = Rational.__new__(Rational) @@ -2188,8 +2187,9 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): INPUT: - ``var`` -- the minimal polynomial is defined over a polynomial ring - in a variable with this name. If not specified, this defaults to ``'x'`` - - ``algorithm`` -- for compatibility with general number field elements; ignored + in a variable with this name; if not specified, this defaults to ``'x'`` + - ``algorithm`` -- for compatibility with general number field + elements; ignored EXAMPLES:: @@ -2213,8 +2213,9 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): INPUT: - ``var`` -- the minimal polynomial is defined over a polynomial ring - in a variable with this name. If not specified, this defaults to ``'x'`` - - ``algorithm`` -- for compatibility with general number field elements: and ignored + in a variable with this name; if not specified, this defaults to ``'x'`` + - ``algorithm`` -- for compatibility with general number field + elements; ignored EXAMPLES:: @@ -2262,7 +2263,7 @@ cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute): def floor(self): r""" - Returns the floor of ``self``. + Return the floor of ``self``. EXAMPLES:: @@ -2728,9 +2729,9 @@ cdef class OrderElement_quadratic(NumberFieldElement_quadratic): INPUT: - ``var`` -- the minimal polynomial is defined over a polynomial ring - in a variable with this name. If not specified, this defaults to ``'x'`` - - ``algorithm`` -- for compatibility with general number field elements; ignored - + in a variable with this name; if not specified, this defaults to ``'x'`` + - ``algorithm`` -- for compatibility with general number field + elements; ignored EXAMPLES:: @@ -2755,8 +2756,9 @@ cdef class OrderElement_quadratic(NumberFieldElement_quadratic): INPUT: - ``var`` -- the minimal polynomial is defined over a polynomial ring - in a variable with this name. If not specified, this defaults to ``'x'`` - - ``algorithm`` -- for compatibility with general number field elements; ignored + in a variable with this name; if not specified, this defaults to ``'x'`` + - ``algorithm`` -- for compatibility with general number field + elements; ignored EXAMPLES:: @@ -2849,10 +2851,10 @@ cdef class OrderElement_quadratic(NumberFieldElement_quadratic): INPUT: - - ``I`` -- may be an ideal of ``self.parent()``, or an - element or list of elements of ``self.parent()`` generating a nonzero - ideal. A :class:`ValueError` is raised if `I` is non-integral or is zero. - A :class:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. + - ``I`` -- may be an ideal of ``self.parent()``, or an + element or list of elements of ``self.parent()`` generating a nonzero + ideal. A :exc:`ValueError` is raised if `I` is non-integral or is zero. + A :exc:`ZeroDivisionError` is raised if `I + (x) \neq (1)`. EXAMPLES:: @@ -2956,7 +2958,7 @@ cdef class Z_to_quadratic_field_element(Morphism): def __init__(self, K): """ - ``K`` is the target quadratic field + ``K`` is the target quadratic field. EXAMPLES:: @@ -3058,7 +3060,9 @@ cdef class Q_to_quadratic_field_element(Morphism): def __init__(self, K): """ - ``K`` is the target quadratic field + INPUT: + + - ``K`` -- the target quadratic field EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_ideal.py b/src/sage/rings/number_field/number_field_ideal.py index 979bc0dc869..fb9bea019a4 100644 --- a/src/sage/rings/number_field/number_field_ideal.py +++ b/src/sage/rings/number_field/number_field_ideal.py @@ -100,7 +100,8 @@ def __init__(self, field, gens, coerce=True): - ``field`` -- a number field - - ``gens`` -- a list of :class:`NumberFieldElement` objects belonging to the field + - ``gens`` -- list of :class:`NumberFieldElement` objects belonging to + the field TESTS: @@ -144,12 +145,9 @@ def _magma_init_(self, magma): INPUT: + - ``magma`` -- a Magma interpreter - - ``magma`` -- a Magma interpreter - - - OUTPUT: :class:`MagmaElement` corresponding to this ideal. - + OUTPUT: :class:`MagmaElement` corresponding to this ideal EXAMPLES:: @@ -302,7 +300,8 @@ def coordinates(self, x): INPUT: - - ``x`` -- an element of the number field (or ring of integers) of this ideal. + - ``x`` -- an element of the number field (or ring of integers) of this + ideal OUTPUT: @@ -431,7 +430,7 @@ def _repr_(self): """ Return the string representation of this number field ideal. - .. note:: + .. NOTE:: Only the zero ideal actually has type NumberFieldIdeal; all others have type NumberFieldFractionalIdeal. So this function @@ -556,7 +555,7 @@ def __pari__(self): def _pari_init_(self): """ - Return self in PARI Hermite Normal Form as a string + Return ``self`` in PARI Hermite Normal Form as a string. EXAMPLES:: @@ -726,9 +725,9 @@ def free_module(self): def reduce_equiv(self): """ - Return a small ideal that is equivalent to self in the group + Return a small ideal that is equivalent to ``self`` in the group of fractional ideals modulo principal ideals. Very often (but - not always) if self is principal then this function returns + not always) if ``self`` is principal then this function returns the unit ideal. ALGORITHM: Calls :pari:`idealred` function. @@ -848,7 +847,6 @@ def gens_two(self): [12, [0, 12]~] sage: I.gens_two() (12, 0) - """ try: return self.__two_generators @@ -1065,7 +1063,7 @@ def pari_prime(self): INPUT: - - ``self`` -- a prime ideal. + - ``self`` -- a prime ideal OUTPUT: a PARI "prime ideal", i.e. a five-component vector `[p,a,e,f,b]` representing the prime ideal `p O_K + a O_K`, `e`, `f` as usual, `a` as @@ -1097,10 +1095,10 @@ def _cache_bnfisprincipal(self, proof=None, gens=False): - ``self`` -- an ideal - - ``proof`` -- proof flag. If ``proof=False``, assume GRH. + - ``proof`` -- proof flag. If ``proof=False``, assume GRH - - ``gens`` -- (default: ``False``) if True, also computes the reduced - generators of the ideal. + - ``gens`` -- boolean (default: ``False``); if ``True``, also computes + the reduced generators of the ideal OUTPUT: @@ -1271,7 +1269,7 @@ def S_ideal_class_log(self, S): def is_zero(self): """ - Return ``True`` iff ``self`` is the zero ideal + Return ``True`` iff ``self`` is the zero ideal. Note that `(0)` is a :class:`NumberFieldIdeal`, not a :class:`NumberFieldFractionalIdeal`. @@ -1386,7 +1384,7 @@ def number_field(self): def smallest_integer(self): r""" - Return the smallest non-negative integer in `I \cap \ZZ`, + Return the smallest nonnegative integer in `I \cap \ZZ`, where `I` is this ideal. If `I = 0`, returns 0. EXAMPLES:: @@ -1443,17 +1441,17 @@ def smallest_integer(self): def valuation(self, p): r""" - Return the valuation of self at ``p``. + Return the valuation of ``self`` at ``p``. INPUT: - - ``p`` -- a prime ideal `\mathfrak{p}` of this number field. + - ``p`` -- a prime ideal `\mathfrak{p}` of this number field OUTPUT: (integer) The valuation of this fractional ideal at the prime `\mathfrak{p}`. If `\mathfrak{p}` is not prime, raise a - :class:`ValueError`. + :exc:`ValueError`. EXAMPLES:: @@ -1503,10 +1501,10 @@ def decomposition_group(self): def ramification_group(self, v): r""" - Return the `v`'th ramification group of ``self``, i.e. the set of + Return the `v`-th ramification group of ``self``, i.e. the set of elements `s` of the Galois group of the number field of ``self`` (which we assume is Galois) such that `s` acts trivially - modulo the `(v+1)`'st power of self. See the + modulo the `(v+1)`'st power of ``self``. See the :meth:`GaloisGroup.ramification_group` method for further examples and doctests. @@ -1541,7 +1539,7 @@ def random_element(self, *args, **kwds): INPUT: - - ``*args``, ``*kwds`` -- Parameters passed to the random integer + - ``*args``, ``*kwds`` -- parameters passed to the random integer function. See the documentation of ``ZZ.random_element()`` for details. @@ -1557,7 +1555,7 @@ def random_element(self, *args, **kwds): sage: I = K.ideal(1 - a) sage: I.random_element() # random output -a^2 - a - 19 - sage: I.random_element(distribution="uniform") # random output + sage: I.random_element(distribution='uniform') # random output a^2 - 2*a - 8 sage: I.random_element(-30, 30) # random output -7*a^2 - 17*a - 75 @@ -1607,13 +1605,13 @@ def residue_symbol(self, e, m, check=True): .. MATH:: \left(\frac{\alpha}{\mathbf{P}}\right) \equiv \alpha^{\frac{N(\mathbf{P})-1}{m}} \operatorname{mod} \mathbf{P} - .. note:: accepts `m=1`, in which case returns 1 + .. NOTE:: accepts `m=1`, in which case returns 1 - .. note:: can also be called for an element from sage.rings.number_field_element.residue_symbol + .. NOTE:: can also be called for an element from sage.rings.number_field_element.residue_symbol - .. note:: `e` is coerced into the number field of ``self`` + .. NOTE:: `e` is coerced into the number field of ``self`` - .. note:: + .. NOTE:: if `m=2`, `e` is an integer, and ``self.number_field()`` has absolute degree 1 (i.e. it is a copy of the rationals), then this calls :func:`kronecker_symbol`, which is implemented using GMP. @@ -1624,9 +1622,7 @@ def residue_symbol(self, e, m, check=True): - ``m`` -- positive integer - OUTPUT: - - - an m-th root of unity in the number field + OUTPUT: an `m`-th root of unity in the number field EXAMPLES: @@ -1650,7 +1646,6 @@ def residue_symbol(self, e, m, check=True): Traceback (most recent call last): ... ValueError: The residue symbol to that power is not defined for the number field - """ K = self.ring() if m == 2 and K.absolute_degree() == 1: @@ -1840,8 +1835,9 @@ class NumberFieldFractionalIdeal(MultiplicativeGroupElement, NumberFieldIdeal, I def __init__(self, field, gens, coerce=True): """ INPUT: - field -- a number field - x -- a list of NumberFieldElements of the field, not all zero + + - ``field`` -- a number field + - ``x`` -- list of NumberFieldElements of the field, not all zero EXAMPLES:: @@ -1866,7 +1862,7 @@ def _repr_(self): """ Return the string representation of this number field fractional ideal. - .. note:: + .. NOTE:: Only the zero ideal actually has type NumberFieldIdeal; all others have type NumberFieldFractionalIdeal. @@ -1884,7 +1880,7 @@ def _repr_(self): def divides(self, other): """ - Return ``True`` if this ideal divides other and False otherwise. + Return ``True`` if this ideal divides ``other`` and ``False`` otherwise. EXAMPLES:: @@ -2060,7 +2056,7 @@ def is_trivial(self, proof=None): def ramification_index(self): r""" Return the ramification index of this fractional ideal, - assuming it is prime. Otherwise, raise a :class:`ValueError`. + assuming it is prime. Otherwise, raise a :exc:`ValueError`. The ramification index is the power of this prime appearing in the factorization of the prime in `\ZZ` that this prime lies @@ -2108,7 +2104,7 @@ def reduce(self, f): - `d_i = b_i[i]`, with `\{b_0, b_1, \dots, b_n\}` HNF basis of the ideal ``self``. - .. note:: + .. NOTE:: The reduced element `g` is not necessarily small. To get a small `g` use the method :meth:`small_residue`. @@ -2194,7 +2190,7 @@ def residues(self): OUTPUT: An iterator through a complete list of residues modulo the integral - ideal self. This list is the set of canonical reduced representatives + ideal ``self``. This list is the set of canonical reduced representatives given by all integral elements with coordinates `(r_0, \dots,r_{n-1})`, where: @@ -2258,8 +2254,8 @@ def invertible_residues(self, reduce=True): INPUT: - - ``reduce`` -- bool. If ``True`` (default), use ``small_residue`` to get - small representatives of the residues. + - ``reduce`` -- boolean; if ``True`` (default), use ``small_residue`` to get + small representatives of the residues OUTPUT: @@ -2324,10 +2320,10 @@ def invertible_residues_mod(self, subgp_gens=[], reduce=True): an iterator through a list of representatives for the invertible residues modulo the integral ideal ``self``. - - ``reduce`` -- bool. If ``True`` (default), use ``small_residues`` to - get small representatives of the residues. + - ``reduce`` -- boolean; if ``True`` (default), use ``small_residues`` to + get small representatives of the residues - .. note:: + .. NOTE:: See also :meth:`invertible_residues` for a simpler version without the subgroup. @@ -2474,13 +2470,11 @@ def is_coprime(self, other): INPUT: - ``other`` -- another ideal of the same field, or generators - of an ideal. - - OUTPUT: + of an ideal - ``True`` if ``self`` and ``other`` are coprime, else ``False``. + OUTPUT: ``True`` if ``self`` and ``other`` are coprime, else ``False`` - .. note:: + .. NOTE:: This function works for fractional ideals as well as integral ideals. @@ -2540,11 +2534,10 @@ def idealcoprime(self, J): INPUT: - - ``J`` -- another integral ideal of the same field as ``self``, which must also be integral. - - OUTPUT: + - ``J`` -- another integral ideal of the same field as ``self``, which + must also be integral - an element `l` such that ``l*self`` is coprime to the ideal `J` + OUTPUT: an element `l` such that ``l*self`` is coprime to the ideal `J` .. TODO:: @@ -2593,7 +2586,7 @@ def small_residue(self, f): element `g` such that `f - g` belongs to the ideal ``self`` (which must be integral), and `g` is small. - .. note:: + .. NOTE:: The reduced representative returned is not uniquely determined. @@ -2615,7 +2608,6 @@ def small_residue(self, f): sage: I = K.ideal(5) sage: I.small_residue(a^2 -13) a^2 + 5*a - 3 - """ if not self.is_integral(): raise ValueError("The ideal must be integral") @@ -2632,9 +2624,7 @@ def _pari_bid_(self, flag=1): `(O_K/I)^*`, which takes more time. By default ``flag=1`` (no generators are computed). - OUTPUT: - - - The pari special structure ``bid``. + OUTPUT: the PARI special structure ``bid`` EXAMPLES:: @@ -2668,11 +2658,11 @@ def idealstar(self, flag=1): INPUT: - - ``flag`` (int default 1) -- when ``flag`` =2, it also + - ``flag`` -- integer (default: 1); when ``flag==2``, it also computes the generators of the group `(O_K/I)^*`, which - takes more time. By default ``flag`` =1 (no generators are + takes more time. By default ``flag`` is 1 (no generators are computed). In both cases the special PARI structure ``bid`` - is computed as well. If ``flag`` =0 (deprecated) it computes + is computed as well. If ``flag`` is 0 (deprecated) it computes only the group structure of `(O_K/I)^*` (with generators) and not the special ``bid`` structure. @@ -2680,7 +2670,7 @@ def idealstar(self, flag=1): The finite abelian group `(O_K/I)^*`. - .. note:: + .. NOTE:: Uses the PARI function :pari:`idealstar`. The PARI function outputs a special ``bid`` structure which is stored in the internal @@ -2738,26 +2728,26 @@ def ideallog(self, x, gens=None, check=True): INPUT: - - ``x`` -- a non-zero element of the number field of ``self``, + - ``x`` -- a nonzero element of the number field of ``self``, which must have valuation equal to 0 at all prime ideals in - the support of the ideal ``self``. - - ``gens`` -- a list of elements of the number field which generate `(R + the support of the ideal ``self`` + - ``gens`` -- list of elements of the number field which generate `(R / I)^*`, where `R` is the ring of integers of the field and `I` is this ideal, or ``None``. If ``None``, use the generators calculated by :meth:`~idealstar`. - - ``check`` -- if ``True``, do a consistency check on the results. Ignored - if ``gens`` is ``None``. + - ``check`` -- if ``True``, do a consistency check on the results. + Ignored if ``gens`` is ``None``. OUTPUT: - a list of non-negative integers `(x_i)` such that `x = + a list of nonnegative integers `(x_i)` such that `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where `x_i` are the generators, and the list `(x_i)` is lexicographically minimal with respect to this requirement. If the `x_i` generate independent cyclic factors of order `d_i`, as is the case for the default generators calculated by :meth:`~idealstar`, this just means that `0 \le x_i < d_i`. - A :class:`ValueError` will be raised if the elements specified in ``gens`` + A :exc:`ValueError` will be raised if the elements specified in ``gens`` do not in fact generate the unit group (even if the element `x` is in the subgroup they generate). @@ -2857,7 +2847,7 @@ def ideallog(self, x, gens=None, check=True): def element_1_mod(self, other): r""" - Return an element `r` in this ideal such that `1-r` is in ``other`` + Return an element `r` in this ideal such that `1-r` is in ``other``. An error is raised if either ideal is not integral of if they are not coprime. @@ -2865,11 +2855,10 @@ def element_1_mod(self, other): INPUT: - ``other`` -- another ideal of the same field, or generators - of an ideal. - - OUTPUT: + of an ideal - An element `r` of the ideal self such that `1-r` is in the ideal ``other`` + OUTPUT: an element `r` of the ideal ``self`` such that `1-r` is in the + ideal ``other`` AUTHOR: Maite Aranes (modified to use PARI's :pari:`idealaddtoone` by Francis Clarke) @@ -2975,7 +2964,7 @@ def prime_to_S_part(self, S): INPUT: - - ``S`` -- a list of prime ideals + - ``S`` -- list of prime ideals OUTPUT: @@ -3015,10 +3004,10 @@ def is_S_unit(self, S): INPUT: - - ``S`` -- a list of prime ideals (not checked if they are - indeed prime). + - ``S`` -- list of prime ideals (not checked if they are + indeed prime) - .. note:: + .. NOTE:: This function assumes that `S` is a list of prime ideals, but does not check this. This function will fail if `S` is @@ -3046,10 +3035,9 @@ def is_S_integral(self, S): INPUT: - - `S` -- a list of prime ideals (not checked if they are indeed - prime). + - ``S`` -- list of prime ideals (not checked if they are indeed prime) - .. note:: + .. NOTE:: This function assumes that `S` is a list of prime ideals, but does not check this. This function will fail if `S` is @@ -3058,7 +3046,7 @@ def is_S_integral(self, S): OUTPUT: ``True``, if the ideal is `S`-integral: that is, if the valuations - of the ideal at all primes not in `S` are non-negative. ``False``, + of the ideal at all primes not in `S` are nonnegative. ``False``, otherwise. EXAMPLES:: @@ -3087,9 +3075,7 @@ def prime_to_idealM_part(self, M): - ``M`` -- an integral ideal of the same field, or generators of an ideal - OUTPUT: - - An ideal which is the largest divisor of ``self`` that is coprime to `M`. + OUTPUT: an ideal which is the largest divisor of ``self`` that is coprime to `M` AUTHOR: Maite Aranes @@ -3136,10 +3122,10 @@ def _p_quotient(self, p): OUTPUT: - - `V` -- a vector space of characteristic `p` + - ``V`` -- a vector space of characteristic `p` - ``quo`` -- a partially defined quotient homomorphism from the ambient number field to `V` - - ``lift`` -- a section of ``quo``. + - ``lift`` -- a section of ``quo`` EXAMPLES:: @@ -3219,11 +3205,10 @@ def residue_field(self, names=None): sage: FF(a) w - An example of reduction maps to the residue field: these are - defined on the whole valuation ring, i.e. the subring of the - number field consisting of elements with non-negative - valuation. This shows that the issue raised in :issue:`1951` - has been fixed:: + An example of reduction maps to the residue field: these are defined on + the whole valuation ring, i.e. the subring of the number field + consisting of elements with nonnegative valuation. This shows that the + issue raised in :issue:`1951` has been fixed:: sage: K. = NumberField(x^2 + 1) sage: P1, P2 = [g[0] for g in K.factor(5)]; P1, P2 @@ -3274,7 +3259,7 @@ def residue_field(self, names=None): def residue_class_degree(self): r""" Return the residue class degree of this fractional ideal, - assuming it is prime. Otherwise, raise a :class:`ValueError`. + assuming it is prime. Otherwise, raise a :exc:`ValueError`. The residue class degree of a prime ideal `I` is the degree of the extension `O_K/I` of its prime subfield. @@ -3382,7 +3367,7 @@ def __call__(self, x): INPUT: - x -- an element of the field + - ``x`` -- an element of the field EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_ideal_rel.py b/src/sage/rings/number_field/number_field_ideal_rel.py index 2f04cf27660..0a1557110fe 100644 --- a/src/sage/rings/number_field/number_field_ideal_rel.py +++ b/src/sage/rings/number_field/number_field_ideal_rel.py @@ -139,7 +139,8 @@ def absolute_ideal(self, names='a'): INPUT: - - ``names`` (optional) -- string; name of generator of the absolute field + - ``names`` -- (optional) string; name of generator of the absolute + field EXAMPLES:: @@ -249,7 +250,6 @@ def free_module(self): ... sage: I.free_module().is_submodule(K.maximal_order().free_module()) True - """ return self.absolute_ideal().free_module() @@ -659,7 +659,7 @@ def is_integral(self): def absolute_ramification_index(self): """ Return the absolute ramification index of this fractional ideal, - assuming it is prime. Otherwise, raise a :class:`ValueError`. + assuming it is prime. Otherwise, raise a :exc:`ValueError`. The absolute ramification index is the power of this prime appearing in the factorization of the rational prime that @@ -690,7 +690,7 @@ def absolute_ramification_index(self): def relative_ramification_index(self): """ Return the relative ramification index of this fractional ideal, - assuming it is prime. Otherwise, raise a :class:`ValueError`. + assuming it is prime. Otherwise, raise a :exc:`ValueError`. The relative ramification index is the power of this prime appearing in the factorization of the prime ideal of the @@ -760,7 +760,8 @@ def residue_class_degree(self): def residues(self): """ - Returns a iterator through a complete list of residues modulo this integral ideal. + Return a iterator through a complete list of residues modulo this + integral ideal. An error is raised if this fractional ideal is not integral. @@ -784,19 +785,20 @@ def residues(self): def element_1_mod(self, other): r""" - Returns an element `r` in this ideal such that `1-r` is in ``other``. + Return an element `r` in this ideal such that `1-r` is in ``other``. An error is raised if either ideal is not integral of if they are not coprime. INPUT: - - ``other`` -- another ideal of the same field, or generators of an ideal. + - ``other`` -- another ideal of the same field, or generators of an + ideal OUTPUT: - an element `r` of the ideal self such that `1-r` is in the - ideal ``other``. + an element `r` of the ideal ``self`` such that `1-r` is in the ideal + ``other``. EXAMPLES:: @@ -827,7 +829,7 @@ def element_1_mod(self, other): def smallest_integer(self): r""" - Return the smallest non-negative integer in `I \cap \ZZ`, where `I` is + Return the smallest nonnegative integer in `I \cap \ZZ`, where `I` is this ideal. If `I = 0`, returns `0`. EXAMPLES:: @@ -848,14 +850,13 @@ def valuation(self, p): INPUT: - - ``p`` -- a prime ideal `\mathfrak{p}` of this relative number field. + - ``p`` -- a prime ideal `\mathfrak{p}` of this relative number field OUTPUT: (integer) The valuation of this fractional ideal at the prime `\mathfrak{p}`. If `\mathfrak{p}` is not prime, raise a - :class:`ValueError`. - + :exc:`ValueError`. EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_morphisms.pyx b/src/sage/rings/number_field/number_field_morphisms.pyx index 9ef71586355..e71bad5db7c 100644 --- a/src/sage/rings/number_field/number_field_morphisms.pyx +++ b/src/sage/rings/number_field/number_field_morphisms.pyx @@ -68,11 +68,9 @@ cdef class NumberFieldEmbedding(Morphism): INPUT: - - ``_slots`` -- a dictionary + - ``_slots`` -- dictionary - OUTPUT: - - The given dictionary, with the generator image added. + OUTPUT: the given dictionary, with the generator image added EXAMPLES:: @@ -99,7 +97,7 @@ cdef class NumberFieldEmbedding(Morphism): INPUT: - - ``_slots`` -- a dictionary providing values for the c(p)def slots of self. + - ``_slots`` -- dictionary providing values for the c(p)def slots of ``self`` EXAMPLES:: @@ -191,7 +189,6 @@ cdef class EmbeddedNumberFieldMorphism(NumberFieldEmbedding): From: Number Field in i with defining polynomial x^2 + 1 with i = I To: Number Field in i with defining polynomial x^2 + 1 with i = -I Defn: i -> -i - """ cdef readonly ambient_field @@ -231,7 +228,7 @@ cdef class EmbeddedNumberFieldMorphism(NumberFieldEmbedding): 'Number Field in a with defining polynomial x^3 + 2 with a = -1.259921049894873?' and 'Number Field in a with defining polynomial x^3 + 2 with a = 0.6299605249474365? + 1.091123635971722?*I' - The following was fixed to raise a ``TypeError`` in :issue:`15331`:: + The following was fixed to raise a :exc:`TypeError` in :issue:`15331`:: sage: L. = NumberField(x^2 + 1) sage: K = NumberField(L(i/2+3).minpoly(), names=('i0',), embedding=L(i/2+3)) @@ -239,7 +236,6 @@ cdef class EmbeddedNumberFieldMorphism(NumberFieldEmbedding): Traceback (most recent call last): ... TypeError: No embedding available for Number Field in i with defining polynomial x^2 + 1 - """ if ambient_field is None: if K.coerce_embedding() is None: @@ -488,7 +484,6 @@ def root_from_approx(f, a): Traceback (most recent call last): ... ValueError: sqrt(3) is not a root of x^2 - 2 - """ P = a.parent() if P.is_exact() and not f(a): @@ -634,11 +629,9 @@ cdef class CyclotomicFieldEmbedding(NumberFieldEmbedding): INPUT: - - ``_slots`` -- a dictionary - - OUTPUT: + - ``_slots`` -- dictionary - The given dictionary, with _gen_image and ratio added. + OUTPUT: the given dictionary, with _gen_image and ratio added EXAMPLES:: @@ -665,7 +658,7 @@ cdef class CyclotomicFieldEmbedding(NumberFieldEmbedding): INPUT: - - ``_slots`` -- a dictionary providing values for the c(p)def slots of self. + - ``_slots`` -- dictionary providing values for the c(p)def slots of ``self`` EXAMPLES:: diff --git a/src/sage/rings/number_field/number_field_rel.py b/src/sage/rings/number_field/number_field_rel.py index 5ab20ddce48..9ab6fd4c261 100644 --- a/src/sage/rings/number_field/number_field_rel.py +++ b/src/sage/rings/number_field/number_field_rel.py @@ -149,14 +149,14 @@ class NumberField_relative(NumberField_generic): - ``base`` -- the base field - ``polynomial`` -- a polynomial which must be defined in the ring `K[x]`, - where `K` is the base field. + where `K` is the base field - - ``name`` -- a string, the variable name + - ``name`` -- string; the variable name - - ``latex_name`` -- a string or ``None`` (default: ``None``), variable name + - ``latex_name`` -- string or ``None`` (default: ``None``); variable name for latex printing - - ``check`` -- a boolean (default: ``True``), whether to check + - ``check`` -- boolean (default: ``True``); whether to check irreducibility of ``polynomial`` - ``embedding`` -- currently not supported, must be ``None`` @@ -349,7 +349,7 @@ def change_names(self, names): Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where ``from_K`` is an isomorphism from `K` to ``self`` and ``to_K`` is an - isomorphism from self to `K`. + isomorphism from ``self`` to `K`. EXAMPLES:: @@ -513,7 +513,6 @@ def gens(self): (a0, 0) sage: NumberField([x, x^2 - 3], 'a').gens() (0, a1) - """ return ((self._gen_relative(),) + tuple(map(self, self.base_field().gens()))) @@ -564,7 +563,7 @@ def ngens(self): def gen(self, n=0): """ - Return the `n`'th generator of this relative number field. + Return the `n`-th generator of this relative number field. EXAMPLES:: @@ -612,18 +611,17 @@ def composite_fields(self, other, names=None, both_maps=False, preserve_embeddin - ``names`` -- generator name for composite fields - - ``both_maps`` -- (default: ``False``) if ``True``, return quadruples - (`F`, ``self_into_F, ``other_into_F``, `k`) such that ``self_into_F`` maps ``self`` into - `F`, ``other_into_F`` maps ``other`` into `F`. For relative number fields, `k` is - always ``None``. - - - ``preserve_embedding`` -- (default: ``True``) has no effect, but is kept - for compatibility with the absolute version of this method. In every - case the list of all possible compositums is returned. + - ``both_maps`` -- boolean (default: ``False``); if ``True``, return + quadruples (`F`, ``self_into_F, ``other_into_F``, `k`) such that + ``self_into_F`` maps ``self`` into `F`, ``other_into_F`` maps + ``other`` into `F`. For relative number fields, `k` is always + ``None``. - OUTPUT: + - ``preserve_embedding`` -- boolean (default: ``True``); has no effect, + but is kept for compatibility with the absolute version of this, + method. In every case the list of all possible compositums is returned. - list of the composite fields, possibly with maps. + OUTPUT: list of the composite fields, possibly with maps EXAMPLES:: @@ -700,7 +698,7 @@ def absolute_degree(self): def relative_degree(self): r""" - Returns the relative degree of this relative number field. + Return the relative degree of this relative number field. EXAMPLES:: @@ -732,7 +730,7 @@ def degree(self): @cached_method def _maximal_order(self, v=(), assume_maximal='non-maximal-non-unique'): """ - Implements :meth:`NumberField_generic.maximal_order` for relative + Implement :meth:`NumberField_generic.maximal_order` for relative number fields. EXAMPLES:: @@ -741,7 +739,6 @@ def _maximal_order(self, v=(), assume_maximal='non-maximal-non-unique'): sage: K. = NumberFieldTower([x^2 - 17, x^3 - 2]) sage: K.maximal_order() is K.maximal_order() # indirect doctest True - """ absolute_order = self.absolute_field('z').maximal_order(v=v, assume_maximal=assume_maximal) @@ -847,7 +844,7 @@ def _convert_non_number_field_element(self, x): INPUT: - ``x`` -- a non number field element, e.g., a list, - integer, rational, or polynomial. + integer, rational, or polynomial EXAMPLES:: @@ -1156,8 +1153,8 @@ def _pari_base_bnf(self, proof=False, units=True): INPUT: - - ``proof`` (bool, default: ``True``) -- if True, certify - correctness of calculations (not assuming GRH). + - ``proof`` -- boolean (default: ``True``); if ``True``, certify + correctness of calculations (not assuming GRH) EXAMPLES:: @@ -1247,7 +1244,6 @@ def is_galois_absolute(self): sage: y = polygen(K); L. = K.extension(y^2 - a) sage: L.is_galois_absolute() # needs sage.groups False - """ f = self.absolute_polynomial() return f.galois_group(pari_group=True).order() == self.absolute_degree() @@ -1300,7 +1296,8 @@ def is_isomorphic_relative(self, other, base_isom=None): sage: L2.is_isomorphic_relative(L1cyc, base_isom=phi2) True - Omitting ``base_isom`` raises a :class:`ValueError` when the base fields are not identical:: + Omitting ``base_isom`` raises a :exc:`ValueError` when the base fields + are not identical:: sage: L1.is_isomorphic_relative(L1cyc) Traceback (most recent call last): @@ -1369,7 +1366,6 @@ def is_CM_extension(self): False sage: K.is_CM() True - """ try: @@ -1399,7 +1395,8 @@ def free_module(self, base=None, basis=None, map=True): - ``basis`` -- (optional) a list of elements giving a basis over the subfield - - ``map`` -- (default ``True``) whether to return isomorphisms to and from the vector space + - ``map`` -- (default: ``True``) whether to return isomorphisms to and + from the vector space EXAMPLES:: @@ -1517,7 +1514,6 @@ def vector_space(self, *args, **kwds): ... NotImplementedError: For a relative number field L you must use either L.relative_vector_space() or L.absolute_vector_space() as appropriate - """ raise NotImplementedError("For a relative number field L you must use either L.relative_vector_space() or L.absolute_vector_space() as appropriate") @@ -1611,7 +1607,7 @@ def _pari_relative_structure(self): field, and let `f` be the defining polynomial of `L` over `K`. This method returns a triple ``(g, alpha, beta)``, where - - ``g`` is the defining relative polynomial of the PARI + - ``g`` -- the defining relative polynomial of the PARI ``rnf`` structure (see :meth:`pari_rnf`); - ``alpha`` is the image of `x \bmod f` under some isomorphism @@ -1838,9 +1834,7 @@ def absolute_field(self, names): - ``names`` -- string; name of generator of the absolute field - OUTPUT: - - An absolute number field `K` that is isomorphic to this field. + OUTPUT: an absolute number field `K` that is isomorphic to this field Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where ``from_K`` is an isomorphism from `K` to ``self`` and ``to_K`` @@ -2046,7 +2040,7 @@ def embeddings(self, K): e.g., it could be the complex numbers). This will return an identical result when given `K` as input again. - If possible, the most natural embedding of self into `K` + If possible, the most natural embedding of ``self`` into `K` is put first in the list. INPUT: @@ -2190,11 +2184,9 @@ def logarithmic_embedding(self, prec=53): INPUT: - - ``prec`` -- desired floating point precision. + - ``prec`` -- desired floating point precision - OUTPUT: - - the morphism of ``self`` under the logarithmic embedding in the category Set. + OUTPUT: the morphism of ``self`` under the logarithmic embedding in the category Set EXAMPLES:: @@ -2358,9 +2350,9 @@ def absolute_discriminant(self, v=None): INPUT: - - ``v`` (optional) -- list of element of this relative number field. + - ``v`` -- (optional) list of element of this relative number field - OUTPUT: Integer if ``v`` is omitted, and Rational otherwise. + OUTPUT: integer if ``v`` is omitted, and Rational otherwise EXAMPLES:: @@ -2460,14 +2452,14 @@ def order(self, *gens, **kwds): - ``gens`` -- list of elements of ``self``; if no generators are given, just returns the cardinality of this number field (`\infty`) for consistency. - - ``check_is_integral`` -- bool (default: ``True``), whether to check that each - generator is integral. - - ``check_rank`` -- bool (default: ``True``), whether to check that the ring - generated by ``gens`` is of full rank. - - ``allow_subfield`` -- bool (default: ``False``), if ``True`` and the generators - do not generate an order, i.e., they generate a subring of smaller - rank, instead of raising an error, return an order in a smaller - number field. + - ``check_is_integral`` -- boolean (default: ``True``); whether to + check that each generator is integral + - ``check_rank`` -- boolean (default: ``True``); whether to check that + the ring generated by ``gens`` is of full rank + - ``allow_subfield`` -- boolean (default: ``False``); if ``True`` and + the generators do not generate an order, i.e., they generate a + subring of smaller rank, instead of raising an error, return an order + in a smaller number field. The ``check_is_integral`` and ``check_rank`` inputs must be given as explicit keyword arguments. @@ -2518,7 +2510,7 @@ def is_free(self, proof=None): INPUT: - - ``proof`` -- default: ``True`` + - ``proof`` -- (default: ``True``) EXAMPLES:: @@ -2559,7 +2551,7 @@ def _factor_univariate_polynomial(self, poly, **kwargs): def lift_to_base(self, element): """ Lift an element of this extension into the base field if possible, - or raise a :class:`ValueError` if it is not possible. + or raise a :exc:`ValueError` if it is not possible. EXAMPLES:: @@ -2617,7 +2609,7 @@ def relativize(self, alpha, names): INPUT: - ``alpha`` -- an element of ``self``, or an embedding of a subfield into ``self`` - - ``names`` -- name of generator for output field `K`. + - ``names`` -- name of generator for output field `K` OUTPUT: `K` -- a relative number field @@ -2703,23 +2695,23 @@ def relativize(self, alpha, names): L = K.relativize(beta, names) return K.relativize(beta, names, structure=structure.RelativeFromRelative(L)) - def uniformizer(self, P, others="positive"): + def uniformizer(self, P, others='positive'): """ - Returns an element of ``self`` with valuation 1 at the prime ideal `P`. + Return an element of ``self`` with valuation 1 at the prime ideal `P`. INPUT: - - ``self`` -- a number field + - ``self`` -- a number field - - ``P`` -- a prime ideal of ``self`` + - ``P`` -- a prime ideal of ``self`` - - ``others`` -- either ``"positive"`` (default), in which - case the element will have non-negative valuation at all other - primes of ``self``, or ``"negative"``, in which case the element will have - non-positive valuation at all other primes of ``self``. + - ``others`` -- either ``'positive'`` (default), in which case the + element will have nonnegative valuation at all other primes of + ``self``, or ``'negative'``, in which case the element will have + nonpositive valuation at all other primes of ``self`` - .. note:: + .. NOTE:: When `P` is principal (e.g., always when ``self`` has class number one), the result may or may not be a generator of `P`! diff --git a/src/sage/rings/number_field/order.py b/src/sage/rings/number_field/order.py index 11c4fea118d..c214c385179 100644 --- a/src/sage/rings/number_field/order.py +++ b/src/sage/rings/number_field/order.py @@ -126,7 +126,6 @@ class OrderFactory(UniqueFactory): sage: from sage.rings.number_field.order import AbsoluteOrder, OrderFactory sage: isinstance(AbsoluteOrder, OrderFactory) True - """ def get_object(self, version, key, extra_args): @@ -158,7 +157,6 @@ def get_object(self, version, key, extra_args): True sage: N._is_maximal_at(3) True - """ is_maximal = extra_args.pop("is_maximal", None) is_maximal_at = extra_args.pop("is_maximal_at", {}) @@ -210,7 +208,6 @@ def create_key_and_extra_args(self, K, module_rep, is_maximal=None, check=True, Note how the above is lacking the ``is_maximal`` and ``is_maximal_at`` keywords. These are stripped by :meth:`OrderFactory.get_object` and then put back in by :meth:`reduce_data`. - """ if check: if not K.is_absolute(): @@ -238,7 +235,6 @@ def create_object(self, version, key, is_maximal=None, is_maximal_at=()): sage: OK = K.order(i) sage: loads(dumps(OK)) is OK True - """ K, module_rep = key @@ -272,7 +268,6 @@ def reduce_data(self, order): sage: loads(dumps(N)) is O True - """ reduction = super().reduce_data(order) reduction[1][3]["is_maximal"] = order._is_maximal() @@ -322,7 +317,6 @@ def create_key_and_extra_args(self, K, absolute_order, is_maximal=None, check=Tr keywords. These are stripped by :meth:`OrderFactory.get_object`. Since they are applied to the underlying absolute order, they then get pickled when the underlying order is pickled. - """ return (K, absolute_order), {"is_maximal": is_maximal, "is_maximal_at": {p: True for p in is_maximal_at}} @@ -341,7 +335,6 @@ def create_object(self, version, key, is_maximal=None, is_maximal_at=()): sage: OK = L.order([i, j]) sage: loads(dumps(OK)) is OK True - """ K, absolute_order = key @@ -582,7 +575,7 @@ def _coerce_map_from_(self, R): def __mul__(self, right): """ - Create an ideal in this order using the syntax ``O * gens`` + Create an ideal in this order using the syntax ``O * gens``. EXAMPLES:: @@ -638,7 +631,7 @@ def is_field(self, proof=True): def is_noetherian(self): r""" - Return ``True`` (because orders are always Noetherian) + Return ``True`` (because orders are always Noetherian). EXAMPLES:: @@ -713,7 +706,7 @@ def integral_closure(self): def gen(self, i): r""" - Return `i`'th module generator of this order. + Return `i`-th module generator of this order. EXAMPLES:: @@ -776,7 +769,7 @@ def coordinates(self, x): INPUT: - - ``x`` -- an element of the number field of this order. + - ``x`` -- an element of the number field of this order OUTPUT: @@ -817,7 +810,6 @@ def coordinates(self, x): (23, -14/3) sage: sum([O.basis()[j]*acoords[j] for j in range(2)]) == a True - """ K = self.number_field() V, from_V, to_V = K.absolute_vector_space() @@ -1018,13 +1010,11 @@ def residue_field(self, prime, names=None, check=False): INPUT: - - ``prime`` -- a prime ideal of the maximal order in this number field. - - ``names`` -- the name of the variable in the residue field. - - ``check`` -- whether or not to check the primality of prime. - - OUTPUT: + - ``prime`` -- a prime ideal of the maximal order in this number field + - ``names`` -- the name of the variable in the residue field + - ``check`` -- whether or not to check the primality of prime - The residue field at this prime. + OUTPUT: the residue field at this prime EXAMPLES:: @@ -1337,7 +1327,7 @@ def random_element(self, *args, **kwds): sage: OK = K.ring_of_integers() sage: OK.random_element() # random output -2*a^2 - a - 2 - sage: OK.random_element(distribution="uniform") # random output + sage: OK.random_element(distribution='uniform') # random output -a^2 - 1 sage: OK.random_element(-10,10) # random output -10*a^2 - 9*a - 2 @@ -1459,7 +1449,6 @@ def valuation(self, p): :meth:`NumberField_generic.valuation() `, :meth:`pAdicGeneric.valuation() ` - """ from sage.rings.padics.padic_valuation import pAdicValuation return pAdicValuation(self, p) @@ -1494,7 +1483,6 @@ def some_elements(self): Maximal Order generated by [] in Number Field in a with defining polynomial t sage: Z.some_elements() [1, 0, 2, -1, -2, 4] - """ elements = list(self.basis()) for a in self.fraction_field().some_elements(): @@ -1563,7 +1551,6 @@ def __init__(self, K, module_rep): sage: loads(dumps(O)) is O True sage: TestSuite(O).run() - """ if K.degree() == 2: self._element_type = OrderElement_quadratic @@ -1612,7 +1599,6 @@ def _element_constructor_(self, x): 10/3*a^2 + 7/3*a + 1/3 sage: K([1,2,3]) 3*a^2 + 2*a + 1 - """ if isinstance(x, (tuple, list)): x = sum(xi*gi for xi, gi in zip(x, self.gens())) @@ -1685,7 +1671,6 @@ def __and__(left, right): Maximal Order generated by [7/12*z^3 + 3/4*z^2 + 1/12*z + 1/4, 1/6*z^3 + 1/6*z, z^2] in Number Field in z with defining polynomial x^4 - 2*x^2 + 9 sage: L.maximal_order() & L.absolute_field('z').maximal_order() Maximal Order generated by [7/12*z^3 + 3/4*z^2 + 1/12*z + 1/4, 1/6*z^3 + 1/6*z, z^2] in Number Field in z with defining polynomial x^4 - 2*x^2 + 9 - """ if isinstance(right, Order_relative): return right & left @@ -1713,9 +1698,7 @@ def _magma_init_(self, magma): - ``magma`` -- a magma interpreter - OUTPUT: - - a :class:`MagmaElement`, the magma version of this absolute order + OUTPUT: a :class:`MagmaElement`, the magma version of this absolute order EXAMPLES:: @@ -1775,8 +1758,8 @@ def is_maximal(self, p=None): INPUT: - - ``p`` -- an integer prime or ``None`` (default: ``None``); if - set, return whether this order is maximal at the prime `p`. + - ``p`` -- integer prime or ``None`` (default: ``None``); if + set, return whether this order is maximal at the prime `p` EXAMPLES:: @@ -1809,7 +1792,6 @@ def is_maximal(self, p=None): sage: O = K.order([3*a, 2*b]) sage: O.is_maximal() False - """ if self._is_maximal() is True: return True @@ -1842,7 +1824,6 @@ def _is_maximal(self): False sage: K.order(1337*t)._is_maximal() False - """ return self.__is_maximal @@ -1877,7 +1858,6 @@ def _is_maximal_at(self, p=None): sage: O = K.maximal_order([13], assume_maximal=None) sage: O._is_maximal_at() {13: True} - """ if p is None: return dict(self.__is_maximal_at) @@ -1925,7 +1905,7 @@ def _assume_maximal(self, is_maximal=True, p=None): sage: O = K.order(1+i) sage: O.is_maximal() True - sage: N = O._assume_maximal(is_maximal="non-maximal-non-unique") + sage: N = O._assume_maximal(is_maximal='non-maximal-non-unique') sage: N._assume_maximal(p=2) is N True sage: N is O @@ -1936,7 +1916,6 @@ def _assume_maximal(self, is_maximal=True, p=None): False sage: N.is_maximal(p=2) True - """ if is_maximal is None: # No assumption made, return the object unchanged. @@ -2007,11 +1986,9 @@ def index_in(self, other): INPUT: - - ``other`` -- another absolute order with the same ambient number field. - - OUTPUT: + - ``other`` -- another absolute order with the same ambient number field - a rational number + OUTPUT: a rational number EXAMPLES:: @@ -2214,7 +2191,6 @@ def __init__(self, K, absolute_order): sage: loads(dumps(O)) is O True sage: TestSuite(O).run() - """ self._absolute_order = absolute_order self._module_rep = absolute_order._module_rep @@ -2293,9 +2269,10 @@ def absolute_order(self, names='z'): INPUT: - - ``names`` -- string (default: 'z'); name of generator of absolute extension. + - ``names`` -- string (default: ``'z'``); name of generator of absolute + extension - .. note:: + .. NOTE:: There *is* a default variable name, since this absolute order is frequently used for internal algorithms. @@ -2420,7 +2397,6 @@ def __and__(left, right): sage: (L.maximal_order() & L.maximal_order()).is_maximal() True - """ if isinstance(right, Order_absolute): return left._absolute_order & right @@ -2439,8 +2415,8 @@ def is_maximal(self, p=None): INPUT: - - ``p`` -- an integer prime or ``None`` (default: ``None``); if - set, return whether this order is maximal at the prime `p`. + - ``p`` -- integer prime or ``None`` (default: ``None``); if + set, return whether this order is maximal at the prime `p` EXAMPLES:: @@ -2466,7 +2442,6 @@ def is_maximal(self, p=None): sage: K.order(3*a, b).is_maximal(p=3) False - """ return self._absolute_order.is_maximal(p=p) @@ -2485,7 +2460,6 @@ def _is_maximal(self): False sage: O._is_maximal() False - """ return self._absolute_order._is_maximal() @@ -2510,7 +2484,6 @@ def _is_maximal_at(self, p=None): True sage: O._is_maximal_at() {2: True, 3: True, 5: True, 7: True} - """ return self._absolute_order._is_maximal_at(p=p) @@ -2554,7 +2527,7 @@ def _assume_maximal(self, is_maximal=True, p=None): sage: O = L.maximal_order([2, 3], assume_maximal=None) sage: O.is_maximal() True - sage: N = O._assume_maximal(is_maximal="non-maximal-non-unique") + sage: N = O._assume_maximal(is_maximal='non-maximal-non-unique') sage: N._assume_maximal(p=2) is N True sage: N is O @@ -2565,7 +2538,6 @@ def _assume_maximal(self, is_maximal=True, p=None): False sage: N.is_maximal(p=2) True - """ absolute_order = self._absolute_order._assume_maximal(is_maximal=is_maximal, p=p) if absolute_order is not self._absolute_order: @@ -2578,9 +2550,7 @@ def absolute_discriminant(self): Return the absolute discriminant of ``self``, which is the discriminant of the absolute order associated to ``self``. - OUTPUT: - - an integer + OUTPUT: integer EXAMPLES:: @@ -2628,11 +2598,9 @@ def index_in(self, other): INPUT: - - ``other`` -- another order with the same ambient absolute number field. - - OUTPUT: + - ``other`` -- another order with the same ambient absolute number field - a rational number + OUTPUT: a rational number EXAMPLES:: @@ -2674,16 +2642,17 @@ def absolute_order_from_ring_generators(gens, check_is_integral=True, """ INPUT: - - ``gens`` -- list of integral elements of an absolute order. - - ``check_is_integral`` -- bool (default: ``True``), whether to check that each - generator is integral. - - ``check_rank`` -- bool (default: ``True``), whether to check that the ring - generated by ``gens`` is of full rank. - - ``is_maximal`` -- bool (or ``None``); set if maximality of the generated order is - known - - ``allow_subfield`` -- bool (default: ``False``), if ``True`` and the generators do - not generate an order, i.e., they generate a subring of smaller rank, - instead of raising an error, return an order in a smaller number field. + - ``gens`` -- list of integral elements of an absolute order + - ``check_is_integral`` -- boolean (default: ``True``); whether to check + that each generator is integral + - ``check_rank`` -- boolean (default: ``True``); whether to check that the + ring generated by ``gens`` is of full rank + - ``is_maximal`` -- boolean (or ``None``); set if maximality of the + generated order is known + - ``allow_subfield`` -- boolean (default: ``False``); if ``True`` and the + generators do not generate an order, i.e., they generate a subring of + smaller rank, instead of raising an error, return an order in a smaller + number field EXAMPLES:: @@ -2746,17 +2715,18 @@ def absolute_order_from_module_generators(gens, INPUT: - ``gens`` -- list of elements of an absolute number field that generates an - order in that number field as a `\ZZ`-*module*. + order in that number field as a `\ZZ`-*module* - ``check_integral`` -- check that each generator is integral - - ``check_rank`` -- check that the ``gens`` span a module of the correct rank + - ``check_rank`` -- check that the ``gens`` span a module of the correct + rank - ``check_is_ring`` -- check that the module is closed under multiplication (this is very expensive) - - ``is_maximal`` -- bool (or ``None``); set if maximality of the generated order is known - - ``is_maximal_at`` -- a tuple of primes where this order is known to be maximal - - OUTPUT: + - ``is_maximal`` -- boolean (or ``None``); set if maximality of the + generated order is known + - ``is_maximal_at`` -- tuple of primes where this order is known to be + maximal - an absolute order + OUTPUT: an absolute order EXAMPLES: @@ -2898,13 +2868,13 @@ def relative_order_from_ring_generators(gens, """ INPUT: - - ``gens`` -- list of integral elements of an absolute order. - - ``check_is_integral`` -- bool (default: ``True``), whether to check that each - generator is integral. - - ``check_rank`` -- bool (default: ``True``), whether to check that the ring - generated by ``gens`` is of full rank. - - ``is_maximal`` -- bool (or ``None``); set if maximality of the generated order is - known. + - ``gens`` -- list of integral elements of an absolute order + - ``check_is_integral`` -- boolean (default: ``True``); whether to check + that each generator is integral + - ``check_rank`` -- boolean (default: ``True``); whether to check that the + ring generated by ``gens`` is of full rank + - ``is_maximal`` -- boolean (or ``None``); set if maximality of the + generated order is known EXAMPLES: @@ -2950,7 +2920,7 @@ def relative_order_from_ring_generators(gens, return RelativeOrder(K, abs_order, check=False) -def GaussianIntegers(names="I", latex_name="i"): +def GaussianIntegers(names='I', latex_name='i'): r""" Return the ring of Gaussian integers. @@ -2978,7 +2948,7 @@ def GaussianIntegers(names="I", latex_name="i"): return nf.ring_of_integers() -def EisensteinIntegers(names="omega"): +def EisensteinIntegers(names='omega'): r""" Return the ring of Eisenstein integers. diff --git a/src/sage/rings/number_field/order_ideal.py b/src/sage/rings/number_field/order_ideal.py index e1dc02e94cb..0f0b2f5d524 100644 --- a/src/sage/rings/number_field/order_ideal.py +++ b/src/sage/rings/number_field/order_ideal.py @@ -567,7 +567,7 @@ def is_equivalent(self, other, narrow=False): If ``narrow`` is ``True``, test narrow equivalence instead. (Two ideals are equivalent if they differ by multiplication - by a non-zero element. They are narrowly equivalent if they + by a nonzero element. They are narrowly equivalent if they differ by multiplication by an element of positive norm.) EXAMPLES:: diff --git a/src/sage/rings/number_field/selmer_group.py b/src/sage/rings/number_field/selmer_group.py index 49b4030b2e9..377dbd9e60c 100644 --- a/src/sage/rings/number_field/selmer_group.py +++ b/src/sage/rings/number_field/selmer_group.py @@ -19,8 +19,8 @@ where `O^*_{K,S}` is the group of `S`-units of `K` and `Cl_{K,S}` the `S`-class group. When `m=p` is prime, `K(S,p)` is a finite-dimensional vector space over `GF(p)`. Its generators come -from three sources: units (modulo `p`'th powers); generators of the -`p`'th powers of ideals which are not principal but whose `p`'the +from three sources: units (modulo `p`-th powers); generators of the +`p`-th powers of ideals which are not principal but whose `p`-th powers are principal; and generators coming from the prime ideals in `S`. @@ -57,12 +57,10 @@ def _ideal_generator(I): INPUT: - - ``I`` (fractional ideal or integer) -- either a fractional ideal of a - number field, which must be principal, or a rational integer. + - ``I`` -- either a fractional ideal of a number field, which must be + principal, or a rational integer - OUTPUT: - - A generator of `I` when `I` is a principal ideal, else `I` itself. + OUTPUT: a generator of `I` when `I` is a principal ideal, else `I` itself EXAMPLES:: @@ -73,7 +71,6 @@ def _ideal_generator(I): sage: K. = QuadraticField(-11) sage: [_ideal_generator(K.prime_above(p)) for p in primes(25)] [2, 1/2*a - 1/2, -1/2*a - 3/2, 7, -a, 13, 17, 19, 1/2*a + 9/2] - """ try: return I.gens_reduced()[0] @@ -83,16 +80,16 @@ def _ideal_generator(I): def _coords_in_C_p(I, C, p): r""" Return coordinates of the ideal ``I`` with respect to a basis of - the ``p``-torsion of the ideal class group ``C``. + the `p`-torsion of the ideal class group ``C``. INPUT: - - ``I`` (ideal) -- a fractional ideal of a number field ``K``, - whose ``p``'th power is principal. + - ``I`` -- ideal; a fractional ideal of a number field ``K``, whose + `p`-th power is principal - - ``C`` (class group) -- the ideal class group of ``K``. + - ``C`` -- (class group) the ideal class group of ``K`` - - ``p`` (prime) -- a prime number. + - ``p`` -- prime number OUTPUT: @@ -123,7 +120,6 @@ def _coords_in_C_p(I, C, p): Traceback (most recent call last): ... ValueError: The 3rd power of Fractional ideal (2, a + 1) is not principal - """ cyclic_orders = C.gens_orders() non_p_indices = [i for i,n in enumerate(cyclic_orders) if not p.divides(n)] @@ -137,15 +133,15 @@ def _coords_in_C_p(I, C, p): def _coords_in_C_mod_p(I,C,p): r""" Return coordinates of the ideal ``I`` with respect to a basis of - the ``p``-cotorsion of the ideal class group ``C``. + the `p`-cotorsion of the ideal class group ``C``. INPUT: - - ``I`` (ideal) -- a fractional ideal of a number field ``K``. + - ``I`` -- ideal; a fractional ideal of a number field ``K`` - - ``C`` (class group) -- the ideal class group of ``K``. + - ``C`` -- (class group) the ideal class group of ``K`` - - ``p`` (prime) -- a prime number. + - ``p`` -- prime number OUTPUT: @@ -179,7 +175,6 @@ def _coords_in_C_mod_p(I,C,p): [[1, 0], [1, 1], [1, 1], [0, 1], [1, 0], [0, 1], [0, 0], [0, 1], [0, 0]] sage: [_coords_in_C_mod_p(K.prime_above(p), C, 3) for p in primes(25)] [[2], [0], [1], [0], [0], [1], [0], [2], [0]] - """ cyclic_orders = C.gens_orders() p_indices = [i for i, n in enumerate(cyclic_orders) if p.divides(n)] @@ -188,20 +183,18 @@ def _coords_in_C_mod_p(I,C,p): def _root_ideal(I, C, p): r""" - Return a ``p``'th root of an ideal with respect to the class group. + Return a `p`-th root of an ideal with respect to the class group. INPUT: - - ``I`` (ideal) -- a fractional ideal of a number field ``K``, - whose ideal class is a ``p``'th power. + - ``I`` -- ideal; a fractional ideal of a number field ``K``, + whose ideal class is a `p`-th power - - ``C`` (class group) -- the ideal class group of ``K``. + - ``C`` -- (class group) the ideal class group of ``K`` - - ``p`` (prime) -- a prime number. + - ``p`` -- prime number - OUTPUT: - - An ideal `J` such that `J^p` is in the same ideal class as `I`. + OUTPUT: an ideal `J` such that `J^p` is in the same ideal class as `I` EXAMPLES:: @@ -222,7 +215,6 @@ def _root_ideal(I, C, p): sage: J = _root_ideal(I, C, 3) sage: C(J^3) == C(I) True - """ cyclic_orders = C.gens_orders() cyclic_gens = C.gens_ideals() @@ -241,15 +233,15 @@ def _root_ideal(I, C, p): def coords_in_U_mod_p(u, U, p): r""" Return coordinates of a unit ``u`` with respect to a basis of the - ``p``-cotorsion `U/U^p` of the unit group ``U``. + `p`-cotorsion `U/U^p` of the unit group ``U``. INPUT: - - ``u`` (algebraic unit) -- a unit in a number field ``K``. + - ``u`` -- (algebraic unit) a unit in a number field ``K`` - - ``U`` (unit group) -- the unit group of ``K``. + - ``U`` -- (unit group) the unit group of ``K`` - - ``p`` (prime) -- a prime number. + - ``p`` -- prime number OUTPUT: @@ -280,7 +272,6 @@ def coords_in_U_mod_p(u, U, p): [1, 1, 0, 1] sage: coords_in_U_mod_p(u,U,3) [1, 2, 0] - """ coords = U.log(u) start = 1 - int(p.divides(U.zeta_order())) # 0 or 1 @@ -289,25 +280,25 @@ def coords_in_U_mod_p(u, U, p): def basis_for_p_cokernel(S, C, p): r""" Return a basis for the group of ideals supported on ``S`` (mod - ``p``'th-powers) whose class in the class group ``C`` is a ``p``'th power, + `p`-th-powers) whose class in the class group ``C`` is a `p`-th power, together with a function which takes the ``S``-exponents of such an ideal and returns its coordinates on this basis. INPUT: - - ``S`` (list) -- a list of prime ideals in a number field ``K``. + - ``S`` -- list of prime ideals in a number field ``K`` - - ``C`` (class group) -- the ideal class group of ``K``. + - ``C`` -- (class group) the ideal class group of ``K`` - - ``p`` (prime) -- a prime number. + - ``p`` -- prime number OUTPUT: (tuple) (``b``, ``f``) where - ``b`` is a list of ideals which is a basis for the group of - ideals supported on ``S`` (modulo ``p``'th powers) whose ideal - class is a ``p``'th power; + ideals supported on ``S`` (modulo `p`-th powers) whose ideal + class is a `p`-th power; - ``f`` is a function which takes such an ideal and returns its coordinates with respect to this basis. @@ -341,7 +332,6 @@ class is a ``p``'th power; Fractional ideal (3, a + 1), Fractional ideal (5, a + 1), Fractional ideal (5, a + 3)] - """ from sage.matrix.constructor import Matrix M = Matrix(GF(p), [_coords_in_C_mod_p(P, C, p) for P in S]) @@ -360,18 +350,18 @@ def pSelmerGroup(K, S, p, proof=None, debug=False): INPUT: - - ``K`` -- a number field or `\QQ`. + - ``K`` -- a number field or `\QQ` - - ``S`` -- a list of prime ideals in `K`, or prime - numbers when `K` is `\QQ`. + - ``S`` -- list of prime ideals in `K`, or prime + numbers when `K` is `\QQ` - - ``p`` -- a prime number. + - ``p`` -- a prime number - ``proof`` -- if ``True``, compute the class group provably correctly. Default is ``True``. Call :meth:`proof.number_field` to change this default globally. - - ``debug`` -- (boolean, default ``False``) debug flag. + - ``debug`` -- boolean (default: ``False``); debug flag OUTPUT: @@ -401,14 +391,14 @@ def pSelmerGroup(K, S, p, proof=None, debug=False): of the group of roots of unity if its order is divisible by `p`. These have valuation `0` at all primes. - - ``betalist`` is a list of the generators of the `p`'th powers of + - ``betalist`` is a list of the generators of the `p`-th powers of ideals which generate the `p`-torsion in the class group (so is empty if the class number is prime to `p`). These have valuation divisible by `p` at all primes. - ``alphalist`` is a list of generators for each ideal `A` in a - basis of those ideals supported on `S` (modulo `p`'th powers of - ideals) which are `p`'th powers in the class group. We find `B` + basis of those ideals supported on `S` (modulo `p`-th powers of + ideals) which are `p`-th powers in the class group. We find `B` such that `A/B^p` is principal and take a generator of it, for each `A` in a generating set. As a special case, if all the ideals in `S` are principal then ``alphalist`` is a list of @@ -417,16 +407,16 @@ def pSelmerGroup(K, S, p, proof=None, debug=False): The map from the abstract space to `K^*` is easy: we just take the product of the generators to powers given by the coefficient vector. No attempt is made to reduce the resulting product modulo - `p`'th powers. + `p`-th powers. The reverse map is more complicated. Given `a\in K^*`: - write the principal ideal `(a)` in the form `AB^p` with `A` - supported by `S` and `p`'th power free. If this fails, then `a` + supported by `S` and `p`-th power free. If this fails, then `a` does not represent an element of `K(S,p)` and an error is raised. - - set `I_S` to be the group of ideals spanned by `S` mod `p`'th + - set `I_S` to be the group of ideals spanned by `S` mod `p`-th powers, and `I_{S,p}` the subgroup of `I_S` which maps to `0` in `C/C^p`. @@ -435,7 +425,7 @@ def pSelmerGroup(K, S, p, proof=None, debug=False): ``alphalist``. - after dividing out by `A`, now `(a)=B^p` (with a different `a` - and `B`). Write the ideal class `[B]`, whose `p`'th power is + and `B`). Write the ideal class `[B]`, whose `p`-th power is trivial, in terms of the generators of `C[p]`; then `B=(b)B_1`, where the coefficients of `B_1` with respect to generators of `C[p]` give the coordinates of the result with respect to the diff --git a/src/sage/rings/number_field/small_primes_of_degree_one.py b/src/sage/rings/number_field/small_primes_of_degree_one.py index fe456005fed..e7e66f43d02 100644 --- a/src/sage/rings/number_field/small_primes_of_degree_one.py +++ b/src/sage/rings/number_field/small_primes_of_degree_one.py @@ -102,17 +102,15 @@ class Small_primes_of_degree_one_iter(): INPUT: - - ``field`` -- a :class:`NumberField`. + - ``field`` -- a :class:`NumberField` - - ``num_integer_primes`` -- (default: 10000) an integer. We try to find - primes of absolute norm no greater than the - ``num_integer_primes``-th prime number. For example, if - ``num_integer_primes`` is 2, the largest norm found will be 3, since - the second prime is 3. + - ``num_integer_primes`` -- integer (default: 10000); we try to find + primes of absolute norm no greater than the ``num_integer_primes``-th + prime number. For example, if ``num_integer_primes`` is 2, the largest + norm found will be 3, since the second prime is 3. - - ``max_iterations`` -- (default: 100) an integer. We test - ``max_iterations`` integers to find small primes before raising - :class:`StopIteration`. + - ``max_iterations`` -- integer (default: 100); we test ``max_iterations`` + integers to find small primes before raising :class:`StopIteration` AUTHOR: @@ -145,7 +143,7 @@ def __init__(self, field, num_integer_primes=10000, max_iterations=100): def __iter__(self): r""" - Return self as an iterator. + Return ``self`` as an iterator. EXAMPLES:: diff --git a/src/sage/rings/number_field/splitting_field.py b/src/sage/rings/number_field/splitting_field.py index 7fefcd02ce5..28c5486f171 100644 --- a/src/sage/rings/number_field/splitting_field.py +++ b/src/sage/rings/number_field/splitting_field.py @@ -90,7 +90,7 @@ def key(self): def poldegree(self): """ - Return the degree of ``self.pol`` + Return the degree of ``self.pol``. EXAMPLES:: @@ -132,7 +132,7 @@ def splitting_field(poly, name, map=False, degree_multiple=None, abort_degree=No - ``name`` -- a variable name for the number field - - ``map`` -- (default: ``False``) also return an embedding of + - ``map`` -- boolean (default: ``False``); also return an embedding of ``poly`` into the resulting field. Note that computing this embedding might be expensive. @@ -144,14 +144,14 @@ def splitting_field(poly, name, map=False, degree_multiple=None, abort_degree=No if it can be determined that the absolute degree of the splitting field is strictly larger than ``abort_degree``. - - ``simplify`` -- (default: ``True``) during the algorithm, try + - ``simplify`` -- boolean (default: ``True``); during the algorithm, try to find a simpler defining polynomial for the intermediate number fields using PARI's ``polredbest()``. This usually speeds up the computation but can also considerably slow it down. Try and see what works best in the given situation. - - ``simplify_all`` -- (default: ``False``) If ``True``, simplify - intermediate fields and also the resulting number field. + - ``simplify_all`` -- boolean (default: ``False``); if ``True``, simplify + intermediate fields and also the resulting number field OUTPUT: @@ -170,7 +170,7 @@ def splitting_field(poly, name, map=False, degree_multiple=None, abort_degree=No The ``simplify`` and ``simplify_all`` flags usually yield fields defined by polynomials with smaller coefficients. - By default, ``simplify`` is True and ``simplify_all`` is False. + By default, ``simplify`` is ``True`` and ``simplify_all`` is ``False``. :: diff --git a/src/sage/rings/number_field/structure.py b/src/sage/rings/number_field/structure.py index b2b51997528..03748c933a3 100644 --- a/src/sage/rings/number_field/structure.py +++ b/src/sage/rings/number_field/structure.py @@ -88,7 +88,6 @@ class NumberFieldStructure(UniqueRepresentation): sage: LL. = NumberField(x^2 + 1, structure=NameChange(L)) sage: KK is LL False - """ def __init__(self, other): """ @@ -99,7 +98,6 @@ def __init__(self, other): sage: from sage.rings.number_field.structure import NumberFieldStructure sage: type(NumberFieldStructure(QQ)) - """ self.other = other @@ -135,7 +133,6 @@ def create_structure(self, field): j sage: K(j) i - """ raise NotImplementedError @@ -145,7 +142,7 @@ class NameChange(NumberFieldStructure): INPUT: - - ``other`` -- the number field from which this field has been created. + - ``other`` -- the number field from which this field has been created TESTS:: @@ -163,7 +160,6 @@ class NameChange(NumberFieldStructure): 10 sage: [id(v) for v in gc.get_objects() if id(v) == u] [] - """ def create_structure(self, field): r""" @@ -179,7 +175,6 @@ def create_structure(self, field): Isomorphism given by variable name change map: From: Cyclotomic Field of order 5 and degree 4 To: Number Field in a with defining polynomial x^4 + x^3 + x^2 + x + 1) - """ from . import maps return maps.NameChangeMap(field, self.other), maps.NameChangeMap(self.other, field) @@ -191,7 +186,7 @@ class AbsoluteFromRelative(NumberFieldStructure): INPUT: - - ``other`` -- the number field from which this field has been created. + - ``other`` -- the number field from which this field has been created TESTS:: @@ -201,7 +196,6 @@ class AbsoluteFromRelative(NumberFieldStructure): sage: L. = K.extension(x^2 - 3) sage: AbsoluteFromRelative(L) - """ def create_structure(self, field): r""" @@ -220,7 +214,6 @@ def create_structure(self, field): To: Number Field in b with defining polynomial x^2 - 3 over its base field, Isomorphism map: From: Number Field in b with defining polynomial x^2 - 3 over its base field To: Number Field in c with defining polynomial x^4 - 10*x^2 + 1) - """ from . import maps return maps.MapAbsoluteToRelativeNumberField(field, self.other), maps.MapRelativeToAbsoluteNumberField(self.other, field) @@ -233,7 +226,7 @@ class RelativeFromAbsolute(NumberFieldStructure): INPUT: - ``other`` -- the (absolute) number field from which this field has been - created. + created - ``gen`` -- the generator of the intermediate field @@ -242,7 +235,6 @@ class RelativeFromAbsolute(NumberFieldStructure): sage: from sage.rings.number_field.structure import RelativeFromAbsolute sage: RelativeFromAbsolute(QQ, 1/2) - """ def __init__(self, other, gen): r""" @@ -253,7 +245,6 @@ def __init__(self, other, gen): sage: from sage.rings.number_field.structure import RelativeFromAbsolute sage: type(RelativeFromAbsolute(QQ, 1/2)) - """ NumberFieldStructure.__init__(self, other) self.gen = gen @@ -280,7 +271,6 @@ def create_structure(self, field): From: Number Field in a with defining polynomial x^2 - 2 with a = 1.414213562373095? To: Number Field in b with defining polynomial x + a_ over its base field Defn: a |--> -a_) - """ # other field # \ / @@ -310,7 +300,7 @@ class RelativeFromRelative(NumberFieldStructure): INPUT: - ``other`` -- the relative number field used in the construction, see - :meth:`create_structure`; there this field will be called ``field_``. + :meth:`create_structure`; there this field will be called ``field_`` TESTS:: @@ -320,7 +310,6 @@ class RelativeFromRelative(NumberFieldStructure): sage: L. = K.extension(x^2 - 2) sage: RelativeFromRelative(L) - """ def create_structure(self, field): r""" @@ -352,7 +341,6 @@ def create_structure(self, field): To: Number Field in b with defining polynomial x^2 - 2*a*x + 3 over its base field Defn: a |--> a i |--> -b + a) - """ # other and field_ are relative number fields which are isomorphic via # an absolute number field abs. diff --git a/src/sage/rings/number_field/totallyreal.pyx b/src/sage/rings/number_field/totallyreal.pyx index 11d22c8672f..14e55237dd1 100644 --- a/src/sage/rings/number_field/totallyreal.pyx +++ b/src/sage/rings/number_field/totallyreal.pyx @@ -114,11 +114,9 @@ cpdef double odlyzko_bound_totallyreal(int n) noexcept: INPUT: - - ``n`` -- (integer) the degree + - ``n`` -- integer; the degree - OUTPUT: - - a lower bound on the root discriminant (as a real number) + OUTPUT: a lower bound on the root discriminant (as a real number) EXAMPLES:: @@ -172,28 +170,28 @@ def enumerate_totallyreal_fields_prim(n, B, a = [], verbose=0, return_seqs=False INPUT: - - ``n`` -- (integer) the degree - - ``B`` -- (integer) the discriminant bound - - ``a`` -- (list, default: ``[]``) the coefficient list to begin with + - ``n`` -- integer; the degree + - ``B`` -- integer; the discriminant bound + - ``a`` -- list (default: ``[]``); the coefficient list to begin with - ``verbose`` -- (integer or string, default: 0) if ``verbose == 1`` (or ``2``), then print to the screen (really) verbosely; if verbose is a string, then print verbosely to the file specified by verbose. - - ``return_seqs`` -- (boolean, default ``False``) If ``True``, then return - the polynomials as sequences (for easier exporting to a file). + - ``return_seqs`` -- boolean (default: ``False``); if ``True``, then return + the polynomials as sequences (for easier exporting to a file) - ``phc`` -- boolean or integer (default: ``False``) - - ``keep_fields`` -- (boolean or integer, default: ``False``) If + - ``keep_fields`` -- boolean or integer (default: ``False``); if ``keep_fields`` is ``True``, then keep fields up to ``B*log(B)``; if ``keep_fields`` is an integer, then keep fields up to that integer. - - ``t_2`` -- (boolean or integer, default: ``False``) If ``t_2 = T``, then - keep only polynomials with t_2 norm >= T. - - ``just_print`` -- (boolean, default: ``False``): if ``just_print`` is not + - ``t_2`` -- boolean or integer (default: ``False``); if ``t_2 = T``, then + keep only polynomials with ``t_2 norm >= T`` + - ``just_print`` -- boolean (default: ``False``); if ``just_print`` is not ``False``, instead of creating a sorted list of totally real number fields, we simply write each totally real field we find to the file whose filename is given by ``just_print``. In this case, we don't return anything. - - ``return_pari_objects`` -- (boolean, default: ``True``) if + - ``return_pari_objects`` -- boolean (default: ``True``); if both ``return_seqs`` and ``return_pari_objects`` are ``False`` then - it returns the elements as Sage objects; otherwise it returns PARI + it returns the elements as Sage objects. Otherwise it returns PARI objects. OUTPUT: @@ -236,7 +234,6 @@ def enumerate_totallyreal_fields_prim(n, B, a = [], verbose=0, return_seqs=False Univariate Polynomial Ring in x over Rational Field sage: enumerate_totallyreal_fields_prim(2, 10, return_seqs=True)[1][0][1][0].parent() Rational Field - """ cdef pari_gen B_pari, d, d_poly, keepB, nf, t2val, ngt2, ng diff --git a/src/sage/rings/number_field/totallyreal_data.pyx b/src/sage/rings/number_field/totallyreal_data.pyx index 9c31d5aa8e3..694e96235bc 100644 --- a/src/sage/rings/number_field/totallyreal_data.pyx +++ b/src/sage/rings/number_field/totallyreal_data.pyx @@ -457,10 +457,10 @@ cdef class tr_data: INPUT: - n -- integer, the degree - B -- integer, the discriminant bound - a -- list (default: ``[]``), the coefficient list to begin with, where - a[len(a)]*x^n + ... + a[0]x^(n-len(a)) + - ``n`` -- integer; the degree + - ``B`` -- integer; the discriminant bound + - ``a`` -- list (default: ``[]``); the coefficient list to begin with, + where ``a[len(a)]*x^n + ... + a[0]x^(n-len(a))`` OUTPUT: @@ -593,14 +593,12 @@ cdef class tr_data: INPUT: - ``verbose`` -- boolean to print verbosely computational details - - ``haltk`` -- integer, the level at which to halt the inductive + - ``haltk`` -- integer; the level at which to halt the inductive coefficient bounds - ``phc`` -- boolean, if PHCPACK is available, use it when `k = n-5` to compute an improved Lagrange multiplier bound - OUTPUT: - - The next polynomial, as a sequence of integers + OUTPUT: the next polynomial, as a sequence of integers EXAMPLES:: @@ -648,13 +646,13 @@ cdef class tr_data: INPUT: - - f_out -- an integer sequence, to be written with the coefficients of + - ``f_out`` -- integer sequence, to be written with the coefficients of the next polynomial - - verbose -- boolean to print verbosely computational details - - haltk -- integer, the level at which to halt the inductive + - ``verbose`` -- boolean to print verbosely computational details + - ``haltk`` -- integer; the level at which to halt the inductive coefficient bounds - - phc -- boolean, if PHCPACK is available, use it when k == n-5 to - compute an improved Lagrange multiplier bound + - ``phc`` -- boolean; if PHCPACK is available, use it when ``k == n-5`` + to compute an improved Lagrange multiplier bound OUTPUT: @@ -915,7 +913,6 @@ cdef class tr_data: amax = [0, 0, 0, 1] beta = [...] gnk = [...] - """ print("k =", self.k) print("a =", [self.a[i] for i in range(self.n + 1)]) diff --git a/src/sage/rings/number_field/totallyreal_phc.py b/src/sage/rings/number_field/totallyreal_phc.py index e564d760320..a8b5488cb0f 100644 --- a/src/sage/rings/number_field/totallyreal_phc.py +++ b/src/sage/rings/number_field/totallyreal_phc.py @@ -28,12 +28,10 @@ def coefficients_to_power_sums(n, m, a): INPUT: - - ``n`` -- integer, the degree - - ``a`` -- list of integers, the coefficients + - ``n`` -- integer; the degree + - ``a`` -- list of integers; the coefficients - OUTPUT: - - list of integers. + OUTPUT: list of integers .. NOTE:: @@ -64,12 +62,10 @@ def __lagrange_bounds_phc(n, m, a, tmpfile=None): INPUT: - - k -- integer, the index of the next coefficient - - a -- list of integers, the coefficients - - OUTPUT: + - ``k`` -- integer; the index of the next coefficient + - ``a`` -- list of integers; the coefficients - the lower and upper bounds as real numbers. + OUTPUT: the lower and upper bounds as real numbers .. NOTE:: diff --git a/src/sage/rings/number_field/totallyreal_rel.py b/src/sage/rings/number_field/totallyreal_rel.py index 8ce8efb1c02..6eea9afcd2c 100644 --- a/src/sage/rings/number_field/totallyreal_rel.py +++ b/src/sage/rings/number_field/totallyreal_rel.py @@ -118,7 +118,7 @@ def integral_elements_in_box(K, C): INPUT: - ``K`` -- a totally real number field - - ``C`` -- a list ``[[lower, upper], ...]`` of lower and upper bounds, + - ``C`` -- list ``[[lower, upper], ...]`` of lower and upper bounds, for each embedding EXAMPLES:: @@ -244,11 +244,11 @@ def __init__(self, F, m, B, a=None): INPUT: - - ``F`` -- number field, the base field - - ``m`` -- integer, the relative degree - - ``B`` -- integer, the discriminant bound - - ``a`` -- list (default: ``[]``), the coefficient list to begin with, - corresponding to ``a[len(a)]*x^n + ... + a[0]x^(n-len(a))``. + - ``F`` -- number field; the base field + - ``m`` -- integer; the relative degree + - ``B`` -- integer; the discriminant bound + - ``a`` -- list (default: ``[]``); the coefficient list to begin with, + corresponding to ``a[len(a)]*x^n + ... + a[0]x^(n-len(a))`` OUTPUT: @@ -371,17 +371,15 @@ def incr(self, f_out, verbose=False, haltk=0): INPUT: - - ``f_out`` -- an integer sequence, to be written with the - coefficients of the next polynomial - - ``verbose`` -- boolean or nonnegative integer (default: ``False``) - print verbosely computational details. It prints extra - information if ``verbose`` is set to ``2`` or more - - ``haltk`` -- integer, the level at which to halt the inductive + - ``f_out`` -- integer sequence; to be written with the coefficients of + the next polynomial + - ``verbose`` -- boolean or nonnegative integer (default: ``False``); + print verbosely computational details. It prints extra information if + ``verbose`` is set to ``2`` or more. + - ``haltk`` -- integer; the level at which to halt the inductive coefficient bounds - OUTPUT: - - the successor polynomial as a coefficient list. + OUTPUT: the successor polynomial as a coefficient list """ import numpy @@ -655,30 +653,29 @@ def enumerate_totallyreal_fields_rel(F, m, B, a=[], verbose=0, if ``length(a) = d+1``, so in particular always ``a[d] = 1``. - .. note:: + .. NOTE:: This is guaranteed to give all primitive such fields, and seems in practice to give many imprimitive ones. INPUT: - - ``F`` -- number field, the base field - - ``m`` -- integer, the degree - - ``B`` -- integer, the discriminant bound - - ``a`` -- list (default: ``[]``), the coefficient list to begin with - - ``verbose`` -- boolean or nonnegative integer or string (default: 0) + - ``F`` -- number field; the base field + - ``m`` -- integer; the degree + - ``B`` -- integer; the discriminant bound + - ``a`` -- list (default: ``[]``); the coefficient list to begin with + - ``verbose`` -- boolean or nonnegative integer or string (default: 0); give a verbose description of the computations being performed. If ``verbose`` is set to ``2`` or more then it outputs some extra information. If ``verbose`` is a string then it outputs to a file - specified by ``verbose`` - - ``return_seqs`` -- (boolean, default ``False``) If ``True``, then return + specified by ``verbose``. + - ``return_seqs`` -- boolean (default: ``False``); if ``True``, then return the polynomials as sequences (for easier exporting to a file). This also returns a list of four numbers, as explained in the OUTPUT section below. - - ``return_pari_objects`` -- (boolean, default: ``True``) if - both ``return_seqs`` and ``return_pari_objects`` are ``False`` then - it returns the elements as Sage objects; otherwise it returns PARI - objects. + - ``return_pari_objects`` -- boolean (default: ``True``); if both + ``return_seqs`` and ``return_pari_objects`` are ``False`` then it returns + the elements as Sage objects; otherwise it returns PARI objects. OUTPUT: @@ -910,21 +907,19 @@ def enumerate_totallyreal_fields_all(n, B, verbose=0, return_seqs=False, INPUT: - - ``n`` -- integer, the degree - - ``B`` -- integer, the discriminant bound - - ``verbose`` -- boolean or nonnegative integer or string (default: 0) + - ``n`` -- integer; the degree + - ``B`` -- integer; the discriminant bound + - ``verbose`` -- boolean or nonnegative integer or string (default: 0); give a verbose description of the computations being performed. If - ``verbose`` is set to ``2`` or more, it outputs some extra - information. If ``verbose`` is a string, it outputs to a file - specified by ``verbose`` - - ``return_seqs`` -- (boolean, default ``False``) If ``True``, then return + ``verbose`` is set to ``2`` or more, it outputs some extra information. + If ``verbose`` is a string, it outputs to a file specified by ``verbose``. + - ``return_seqs`` -- boolean (default: ``False``); if ``True``, then return the polynomials as sequences (for easier exporting to a file). This also returns a list of four numbers, as explained in the OUTPUT section below. - - ``return_pari_objects`` -- (boolean, default: ``True``) if both + - ``return_pari_objects`` -- boolean (default: ``True``); if both ``return_seqs`` and ``return_pari_objects`` are ``False`` then it - returns the elements as Sage objects; otherwise it returns PARI - objects. + returns the elements as Sage objects; otherwise it returns PARI objects. EXAMPLES:: diff --git a/src/sage/rings/number_field/unit_group.py b/src/sage/rings/number_field/unit_group.py index a98c1dd0907..eb6b46ed82e 100644 --- a/src/sage/rings/number_field/unit_group.py +++ b/src/sage/rings/number_field/unit_group.py @@ -235,7 +235,7 @@ def __init__(self, number_field, proof=True, S=None): INPUT: - ``number_field`` -- a number field - - ``proof`` -- boolean (default ``True``): proof flag + - ``proof`` -- boolean (default: ``True``); proof flag - ``S`` -- tuple of prime ideals, or an ideal, or a single ideal or element from which an ideal can be constructed, in which case the support is used. If ``None``, the global unit @@ -311,8 +311,6 @@ def __init__(self, number_field, proof=True, S=None): sage: K = QuadraticField(d) sage: K.unit_group(proof=False) Unit group with structure C2 x Z of Number Field in a with defining polynomial x^2 - 12936642 with a = 3596.754370262167? - - """ proof = get_flag(proof, "number_field") K = number_field @@ -369,14 +367,14 @@ def __init__(self, number_field, proof=True, S=None): def _element_constructor_(self, u): """ - Returns the abstract group element corresponding to the unit u. + Return the abstract group element corresponding to the unit u. INPUT: - - ``u`` -- Any object from which an element of the unit group's number + - ``u`` -- any object from which an element of the unit group's number field `K` may be constructed; an error is raised if an element of `K` cannot be constructed from u, or if the element constructed is not a - unit. + unit EXAMPLES:: @@ -515,7 +513,7 @@ def torsion_generator(self): def zeta_order(self): """ - Returns the order of the torsion part of the unit group. + Return the order of the torsion part of the unit group. EXAMPLES:: @@ -564,7 +562,6 @@ def zeta(self, n=2, all=False): ValueError: n (=3) does not divide order of generator sage: U.zeta(3, all=True) [] - """ N = self.__ntu K = self.number_field() @@ -631,13 +628,13 @@ def log(self, u): INPUT: - - ``u`` -- Any object from which an element of the unit group's number + - ``u`` -- any object from which an element of the unit group's number field `K` may be constructed; an error is raised if an element of `K` cannot be constructed from `u`, or if the element constructed is not a - unit. + unit - OUTPUT: a list of integers giving the exponents of `u` with - respect to the unit group's basis. + OUTPUT: list of integers giving the exponents of `u` with + respect to the unit group's basis EXAMPLES:: @@ -678,12 +675,12 @@ def exp(self, exponents): INPUT: - - ``u`` -- Any object from which an element of the unit + - ``u`` -- any object from which an element of the unit group's number field `K` may be constructed; an error is raised if an element of `K` cannot be constructed from `u`, or if the element constructed is not a unit. - OUTPUT: a list of integers giving the exponents of `u` with + OUTPUT: list of integers giving the exponents of `u` with respect to the unit group's basis. EXAMPLES:: diff --git a/src/sage/rings/padics/CA_template.pxi b/src/sage/rings/padics/CA_template.pxi index e8d906b01c8..0e6a10b67d9 100644 --- a/src/sage/rings/padics/CA_template.pxi +++ b/src/sage/rings/padics/CA_template.pxi @@ -48,7 +48,7 @@ from sage.categories.homset import Hom cdef class CAElement(pAdicTemplateElement): cdef int _set(self, x, long val, long xprec, absprec, relprec) except -1: """ - Sets the value of this element from given defining data. + Set the value of this element from given defining data. This function is intended for use in conversion, and should not be called on an element created with :meth:`_new_c`. @@ -134,7 +134,7 @@ cdef class CAElement(pAdicTemplateElement): cdef int _get_unit(self, celement value) except -1: """ - Set ``value`` to the unit of this p-adic element. + Set ``value`` to the unit of this `p`-adic element. """ cremove(value, self.value, self.absprec, self.prime_pow, True) @@ -410,11 +410,9 @@ cdef class CAElement(pAdicTemplateElement): INPUT: - - ``_right`` -- currently integers and `p`-adic exponents are - supported. + - ``_right`` -- currently integers and `p`-adic exponents are supported - - ``dummy`` -- not used (Python's ``__pow__`` signature - includes it) + - ``dummy`` -- not used (Python's ``__pow__`` signature includes it) EXAMPLES:: @@ -536,7 +534,7 @@ cdef class CAElement(pAdicTemplateElement): cdef pAdicTemplateElement _lshift_c(self, long shift): r""" - Multiplies by `\pi^{\mbox{shift}}`. + Multiply by `\pi^{\mbox{shift}}`. Negative shifts may truncate the result. @@ -568,7 +566,7 @@ cdef class CAElement(pAdicTemplateElement): cdef pAdicTemplateElement _rshift_c(self, long shift): r""" - Divides by ``π^{\mbox{shift}}``. + Divide by ``π^{\mbox{shift}}``. Positive shifts may truncate the result. @@ -605,11 +603,10 @@ cdef class CAElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer or infinity + - ``absprec`` -- integer or infinity - OUTPUT: - - ``self`` with precision set to the minimum of ``self's`` precision and ``prec`` + OUTPUT: ``self`` with precision set to the minimum of ``self``'s + precision and ``prec`` EXAMPLES:: @@ -630,7 +627,6 @@ cdef class CAElement(pAdicTemplateElement): sage: k(3).add_bigoh(-1) O(3^-1) - """ cdef long aprec, newprec if absprec is infinity: @@ -698,7 +694,7 @@ cdef class CAElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer, infinity, or ``None`` + - ``absprec`` -- integer, infinity, or ``None`` EXAMPLES:: @@ -758,7 +754,7 @@ cdef class CAElement(pAdicTemplateElement): - ``right`` -- a `p`-adic element with the same parent - - ``absprec`` -- an integer, infinity, or ``None`` + - ``absprec`` -- integer, infinity, or ``None`` EXAMPLES:: @@ -824,8 +820,7 @@ cdef class CAElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer, at most the precision cap of the - parent + - ``absprec`` -- integer; at most the precision cap of the parent EXAMPLES:: @@ -1103,7 +1098,6 @@ cdef class pAdicCoercion_ZZ_CA(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, R): """ @@ -1242,11 +1236,11 @@ cdef class pAdicCoercion_ZZ_CA(RingHomomorphism): cdef class pAdicConvert_CA_ZZ(RingMap): """ The map from a capped absolute ring back to the ring of integers that - returns the smallest non-negative integer approximation to its input + returns the smallest nonnegative integer approximation to its input which is accurate up to the precision. - Raises a ``ValueError`` if the input is not in the closure of the image of - the ring of integers. + Raises a :exc:`ValueError` if the input is not in the closure of the image + of the ring of integers. EXAMPLES:: @@ -1291,7 +1285,7 @@ cdef class pAdicConvert_CA_ZZ(RingMap): cdef class pAdicConvert_QQ_CA(Morphism): """ The inclusion map from the rationals to a capped absolute ring that is - defined on all elements with non-negative `p`-adic valuation. + defined on all elements with nonnegative `p`-adic valuation. EXAMPLES:: @@ -1433,7 +1427,6 @@ cdef class pAdicCoercion_CA_frac_field(RingHomomorphism): TESTS:: sage: TestSuite(f).run() # needs sage.libs.flint - """ def __init__(self, R, K): """ @@ -1533,7 +1526,7 @@ cdef class pAdicCoercion_CA_frac_field(RingHomomorphism): def section(self): """ Return a map back to the ring that converts elements of - non-negative valuation. + nonnegative valuation. EXAMPLES:: @@ -1577,7 +1570,6 @@ cdef class pAdicCoercion_CA_frac_field(RingHomomorphism): a + O(3^20) sage: g(a) == f(a) True - """ _slots = RingHomomorphism._extra_slots(self) _slots['_zero'] = self._zero @@ -1607,7 +1599,6 @@ cdef class pAdicCoercion_CA_frac_field(RingHomomorphism): a + O(3^20) sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] self._section = _slots['_section'] @@ -1625,7 +1616,6 @@ cdef class pAdicCoercion_CA_frac_field(RingHomomorphism): sage: f = K.coerce_map_from(R) sage: f.is_injective() True - """ return True @@ -1641,7 +1631,6 @@ cdef class pAdicCoercion_CA_frac_field(RingHomomorphism): sage: f = K.coerce_map_from(R) sage: f.is_surjective() False - """ return False @@ -1816,7 +1805,6 @@ cdef class pAdicConvert_CA_frac_field(Morphism): a + O(3^20) sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] Morphism._update_slots(self, _slots) diff --git a/src/sage/rings/padics/CR_template.pxi b/src/sage/rings/padics/CR_template.pxi index acdc4803670..853a3c3df79 100644 --- a/src/sage/rings/padics/CR_template.pxi +++ b/src/sage/rings/padics/CR_template.pxi @@ -50,18 +50,18 @@ cdef inline bint exactzero(long ordp) noexcept: cdef inline int check_ordp_mpz(mpz_t ordp) except -1: """ - Checks for overflow after addition or subtraction of valuations. + Check for overflow after addition or subtraction of valuations. There is another variant, :meth:`check_ordp`, for long input. - If overflow is detected, raises an ``OverflowError``. + If overflow is detected, raises an :exc:`OverflowError`. """ if mpz_fits_slong_p(ordp) == 0 or mpz_cmp_si(ordp, maxordp) > 0 or mpz_cmp_si(ordp, minusmaxordp) < 0: raise OverflowError("valuation overflow") cdef inline int assert_nonzero(CRElement x) except -1: """ - Checks that ``x`` is distinguishable from zero. + Check that ``x`` is distinguishable from zero. Used in division and floor division. """ @@ -73,7 +73,7 @@ cdef inline int assert_nonzero(CRElement x) except -1: cdef class CRElement(pAdicTemplateElement): cdef int _set(self, x, long val, long xprec, absprec, relprec) except -1: """ - Sets the value of this element from given defining data. + Set the value of this element from given defining data. This function is intended for use in conversion, and should not be called on an element created with :meth:`_new_c`. @@ -152,7 +152,7 @@ cdef class CRElement(pAdicTemplateElement): cdef int _set_exact_zero(self) except -1: """ - Sets ``self`` as an exact zero. + Set ``self`` as an exact zero. TESTS:: @@ -165,7 +165,7 @@ cdef class CRElement(pAdicTemplateElement): cdef int _set_inexact_zero(self, long absprec) except -1: """ - Sets ``self`` as an inexact zero with precision ``absprec``. + Set ``self`` as an inexact zero with precision ``absprec``. TESTS:: @@ -178,7 +178,7 @@ cdef class CRElement(pAdicTemplateElement): cdef CRElement _new_c(self): """ - Creates a new element with the same basic info. + Create a new element with the same basic info. TESTS:: @@ -206,7 +206,7 @@ cdef class CRElement(pAdicTemplateElement): cdef pAdicTemplateElement _new_with_value(self, celement value, long absprec): """ - Creates a new element with a given value and absolute precision. + Create a new element with a given value and absolute precision. Used by code that doesn't know the precision type. """ @@ -219,13 +219,13 @@ cdef class CRElement(pAdicTemplateElement): cdef int _get_unit(self, celement value) except -1: """ - Sets ``value`` to the unit of this p-adic element. + Set ``value`` to the unit of this `p`-adic element. """ ccopy(value, self.unit, self.prime_pow) cdef int check_preccap(self) except -1: """ - Checks that this element doesn't have precision higher than + Check that this element doesn't have precision higher than allowed by the precision cap. TESTS:: @@ -258,7 +258,7 @@ cdef class CRElement(pAdicTemplateElement): cdef int _normalize(self) except -1: """ - Normalizes this element, so that ``self.ordp`` is correct. + Normalize this element, so that ``self.ordp`` is correct. TESTS:: @@ -619,7 +619,7 @@ cdef class CRElement(pAdicTemplateElement): INPUT: - ``_right`` -- currently integers and `p`-adic exponents are - supported. + supported - ``dummy`` -- not used (Python's ``__pow__`` signature includes it) @@ -736,7 +736,7 @@ cdef class CRElement(pAdicTemplateElement): cdef pAdicTemplateElement _lshift_c(self, long shift): r""" - Multiplies by `\pi^{\mbox{shift}}`. + Multiply by `\pi^{\mbox{shift}}`. Negative shifts may truncate the result if the parent is not a field. @@ -767,7 +767,7 @@ cdef class CRElement(pAdicTemplateElement): cdef pAdicTemplateElement _rshift_c(self, long shift): r""" - Divides by ``\pi^{\mbox{shift}}``. + Divide by ``\pi^{\mbox{shift}}``. Positive shifts may truncate the result if the parent is not a field. @@ -808,7 +808,7 @@ cdef class CRElement(pAdicTemplateElement): """ Quotient with remainder. - We choose the remainder to have the same p-adic expansion + We choose the remainder to have the same `p`-adic expansion as the numerator, but truncated at the valuation of the denominator. EXAMPLES:: @@ -889,7 +889,7 @@ cdef class CRElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer or infinity + - ``absprec`` -- integer or infinity OUTPUT: @@ -1002,7 +1002,7 @@ cdef class CRElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer, infinity, or ``None`` + - ``absprec`` -- integer, infinity, or ``None`` EXAMPLES:: @@ -1064,7 +1064,7 @@ cdef class CRElement(pAdicTemplateElement): INPUT: - ``right`` -- a `p`-adic element - - ``absprec`` -- an integer, infinity, or ``None`` + - ``absprec`` -- integer, infinity, or ``None`` EXAMPLES:: @@ -1261,7 +1261,7 @@ cdef class CRElement(pAdicTemplateElement): def _teichmuller_set_unsafe(self): """ - Sets this element to the Teichmuller representative with the + Set this element to the Teichmuller representative with the same residue. .. WARNING:: @@ -1369,7 +1369,7 @@ cdef class CRElement(pAdicTemplateElement): def precision_absolute(self): """ - Returns the absolute precision of this element. + Return the absolute precision of this element. This is the power of the maximal ideal modulo which this element is defined. @@ -1469,7 +1469,7 @@ cdef class CRElement(pAdicTemplateElement): """ Return the valuation of this element. - If self is an exact zero, returns ``maxordp``, which is defined as + If ``self`` is an exact zero, returns ``maxordp``, which is defined as ``(1L << (sizeof(long) * 8 - 2))-1``. EXAMPLES:: @@ -1490,7 +1490,8 @@ cdef class CRElement(pAdicTemplateElement): INPUT: - - ``p`` -- a prime (default: ``None``). If specified, will make sure that ``p == self.parent().prime()`` + - ``p`` -- a prime (default: ``None``); if specified, will make sure + that ``p == self.parent().prime()`` .. NOTE:: @@ -1559,7 +1560,6 @@ cdef class pAdicCoercion_ZZ_CR(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, R): """ @@ -1620,7 +1620,6 @@ cdef class pAdicCoercion_ZZ_CR(RingHomomorphism): 5 + O(5^21) sage: g(5) == f(5) True - """ self._zero = _slots['_zero'] self._section = _slots['_section'] @@ -1692,7 +1691,7 @@ cdef class pAdicCoercion_ZZ_CR(RingHomomorphism): def section(self): """ - Returns a map back to the ring of integers that approximates an element + Return a map back to the ring of integers that approximates an element by an integer. EXAMPLES:: @@ -1710,10 +1709,10 @@ cdef class pAdicCoercion_ZZ_CR(RingHomomorphism): cdef class pAdicConvert_CR_ZZ(RingMap): """ The map from a capped relative ring back to the ring of integers that - returns the smallest non-negative integer approximation to its input + returns the smallest nonnegative integer approximation to its input which is accurate up to the precision. - Raises a :class:`ValueError`, if the input is not in the closure of the image of + Raises a :exc:`ValueError`, if the input is not in the closure of the image of the integers. EXAMPLES:: @@ -1777,7 +1776,6 @@ cdef class pAdicCoercion_QQ_CR(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, R): """ @@ -1838,7 +1836,6 @@ cdef class pAdicCoercion_QQ_CR(RingHomomorphism): 1 + 5 + O(5^20) sage: g(6) == f(6) True - """ self._zero = _slots['_zero'] self._section = _slots['_section'] @@ -1914,7 +1911,7 @@ cdef class pAdicCoercion_QQ_CR(RingHomomorphism): def section(self): """ - Returns a map back to the rationals that approximates an element by + Return a map back to the rationals that approximates an element by a rational number. EXAMPLES:: @@ -1984,7 +1981,7 @@ cdef class pAdicConvert_CR_QQ(RingMap): cdef class pAdicConvert_QQ_CR(Morphism): """ The inclusion map from the rationals to a capped relative ring that is - defined on all elements with non-negative `p`-adic valuation. + defined on all elements with nonnegative `p`-adic valuation. EXAMPLES:: @@ -2120,7 +2117,7 @@ cdef class pAdicConvert_QQ_CR(Morphism): def section(self): """ Return the map back to the rationals that returns the smallest - non-negative integer approximation to its input which is accurate up to + nonnegative integer approximation to its input which is accurate up to the precision. EXAMPLES:: @@ -2152,7 +2149,6 @@ cdef class pAdicCoercion_CR_frac_field(RingHomomorphism): TESTS:: sage: TestSuite(f).run() # needs sage.libs.flint - """ def __init__(self, R, K): """ @@ -2257,7 +2253,7 @@ cdef class pAdicCoercion_CR_frac_field(RingHomomorphism): def section(self): """ Return a map back to the ring that converts elements of - non-negative valuation. + nonnegative valuation. EXAMPLES:: @@ -2301,7 +2297,6 @@ cdef class pAdicCoercion_CR_frac_field(RingHomomorphism): a + O(3^20) sage: g(a) == f(a) True - """ _slots = RingHomomorphism._extra_slots(self) _slots['_zero'] = self._zero @@ -2331,7 +2326,6 @@ cdef class pAdicCoercion_CR_frac_field(RingHomomorphism): a + O(3^20) sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] self._section = _slots['_section'] @@ -2349,7 +2343,6 @@ cdef class pAdicCoercion_CR_frac_field(RingHomomorphism): sage: f = K.coerce_map_from(R) sage: f.is_injective() True - """ return True @@ -2365,7 +2358,6 @@ cdef class pAdicCoercion_CR_frac_field(RingHomomorphism): sage: f = K.coerce_map_from(R) sage: f.is_surjective() False - """ return False @@ -2538,7 +2530,6 @@ cdef class pAdicConvert_CR_frac_field(Morphism): a + O(3^20) sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] Morphism._update_slots(self, _slots) diff --git a/src/sage/rings/padics/FM_template.pxi b/src/sage/rings/padics/FM_template.pxi index 8ce93d797a8..c05930fb0af 100644 --- a/src/sage/rings/padics/FM_template.pxi +++ b/src/sage/rings/padics/FM_template.pxi @@ -47,7 +47,7 @@ from sage.categories.homset import Hom cdef class FMElement(pAdicTemplateElement): cdef int _set(self, x, long val, long xprec, absprec, relprec) except -1: """ - Sets the value of this element from given defining data. + Set the value of this element from given defining data. This function is intended for use in conversion, and should not be called on an element created with :meth:`_new_c`. @@ -91,7 +91,7 @@ cdef class FMElement(pAdicTemplateElement): cdef FMElement _new_c(self): """ - Creates a new element with the same basic info. + Create a new element with the same basic info. TESTS:: @@ -110,7 +110,7 @@ cdef class FMElement(pAdicTemplateElement): cdef pAdicTemplateElement _new_with_value(self, celement value, long absprec): """ - Creates a new element with a given value and absolute precision. + Create a new element with a given value and absolute precision. Used by code that doesn't know the precision type. """ @@ -120,7 +120,7 @@ cdef class FMElement(pAdicTemplateElement): cdef int _get_unit(self, celement value) except -1: """ - Sets ``value`` to the unit of this p-adic element. + Set ``value`` to the unit of this `p`-adic element. """ cremove(value, self.value, self.prime_pow.ram_prec_cap, self.prime_pow) @@ -236,7 +236,7 @@ cdef class FMElement(pAdicTemplateElement): def __invert__(self): r""" - Returns multiplicative inverse of this element. The valuation + Return multiplicative inverse of this element. The valuation of ``self`` must be zero. EXAMPLES:: @@ -381,7 +381,7 @@ cdef class FMElement(pAdicTemplateElement): cdef pAdicTemplateElement _lshift_c(self, long shift): r""" - Multiplies self by `\pi^{shift}`. + Multiply ``self`` by `\pi^{shift}`. If shift < -self.valuation(), digits will be truncated. See :meth:`__rshift__` for details. @@ -428,7 +428,7 @@ cdef class FMElement(pAdicTemplateElement): cdef pAdicTemplateElement _rshift_c(self, long shift): r""" - Divides by `\pi^{shift}`, and truncates. + Divide by `\pi^{shift}`, and truncate. Note that this operation will insert arbitrary digits (in practice, currently all zero) in the least significant digits. @@ -466,11 +466,9 @@ cdef class FMElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer or infinity + - ``absprec`` -- integer or infinity - OUTPUT: - - a new element truncated modulo `\pi^{\mbox{absprec}}`. + OUTPUT: a new element truncated modulo `\pi^{\mbox{absprec}}` EXAMPLES:: @@ -486,7 +484,6 @@ cdef class FMElement(pAdicTemplateElement): 7 sage: a.add_bigoh(-2^1000) 0 - """ cdef long aprec if absprec is infinity: @@ -512,7 +509,7 @@ cdef class FMElement(pAdicTemplateElement): cpdef bint _is_exact_zero(self) except -1: """ - Tests whether this element is an exact zero, which is always + Test whether this element is an exact zero, which is always False for fixed modulus elements. EXAMPLES:: @@ -524,7 +521,7 @@ cdef class FMElement(pAdicTemplateElement): cpdef bint _is_inexact_zero(self) except -1: """ - Return ``True`` if self is indistinguishable from zero. + Return ``True`` if ``self`` is indistinguishable from zero. EXAMPLES:: @@ -538,11 +535,11 @@ cdef class FMElement(pAdicTemplateElement): def is_zero(self, absprec = None): r""" - Returns whether ``self`` is zero modulo `\pi^{\mbox{absprec}}`. + Return whether ``self`` is zero modulo `\pi^{\mbox{absprec}}`. INPUT: - - ``absprec`` -- an integer + - ``absprec`` -- integer EXAMPLES:: @@ -588,7 +585,7 @@ cdef class FMElement(pAdicTemplateElement): INPUT: - ``right`` -- a `p`-adic element with the same parent - - ``absprec`` -- a positive integer or ``None`` (default: ``None``) + - ``absprec`` -- positive integer or ``None`` (default: ``None``) EXAMPLES:: @@ -666,7 +663,7 @@ cdef class FMElement(pAdicTemplateElement): def _teichmuller_set_unsafe(self): """ - Sets this element to the Teichmuller representative with the + Set this element to the Teichmuller representative with the same residue. .. WARNING:: @@ -882,7 +879,6 @@ cdef class pAdicCoercion_ZZ_FM(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, R): """ @@ -963,7 +959,7 @@ cdef class pAdicCoercion_ZZ_FM(RingHomomorphism): - ``x`` -- an Integer - ``absprec``, or the first positional argument -- the maximum - absolute precision (unused for fixed modulus elements). + absolute precision (unused for fixed modulus elements) - ``relprec``, or the second positional argument -- the maximum relative precision (unused for fixed modulus @@ -995,7 +991,7 @@ cdef class pAdicCoercion_ZZ_FM(RingHomomorphism): def section(self): r""" - Returns a map back to `\ZZ` that approximates an element of this + Return a map back to `\ZZ` that approximates an element of this `p`-adic ring by an integer. EXAMPLES:: @@ -1013,9 +1009,9 @@ cdef class pAdicCoercion_ZZ_FM(RingHomomorphism): cdef class pAdicConvert_FM_ZZ(RingMap): r""" The map from a fixed modulus ring back to `\ZZ` that returns the smallest - non-negative integer approximation to its input which is accurate up to the precision. + nonnegative integer approximation to its input which is accurate up to the precision. - If the input is not in the closure of the image of `\ZZ`, raises a :class:`ValueError`. + If the input is not in the closure of the image of `\ZZ`, raises a :exc:`ValueError`. EXAMPLES:: @@ -1060,7 +1056,7 @@ cdef class pAdicConvert_FM_ZZ(RingMap): cdef class pAdicConvert_QQ_FM(Morphism): r""" The inclusion map from `\QQ` to a fixed modulus ring that is defined - on all elements with non-negative `p`-adic valuation. + on all elements with nonnegative `p`-adic valuation. EXAMPLES:: @@ -1145,7 +1141,7 @@ cdef class pAdicConvert_QQ_FM(Morphism): - ``x`` -- a Rational - ``absprec``, or the first positional argument -- the maximum - absolute precision (unused for fixed modulus elements). + absolute precision (unused for fixed modulus elements) - ``relprec``, or the second positional argument -- the maximum relative precision (unused for fixed modulus @@ -1192,7 +1188,6 @@ cdef class pAdicCoercion_FM_frac_field(RingHomomorphism): TESTS:: sage: TestSuite(f).run() # needs sage.libs.flint - """ def __init__(self, R, K): """ @@ -1288,7 +1283,7 @@ cdef class pAdicCoercion_FM_frac_field(RingHomomorphism): def section(self): """ Return a map back to the ring that converts elements of - non-negative valuation. + nonnegative valuation. EXAMPLES:: @@ -1357,7 +1352,6 @@ cdef class pAdicCoercion_FM_frac_field(RingHomomorphism): a sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] self._section = _slots['_section'] @@ -1375,7 +1369,6 @@ cdef class pAdicCoercion_FM_frac_field(RingHomomorphism): sage: f = K.coerce_map_from(R) sage: f.is_injective() True - """ return True @@ -1391,7 +1384,6 @@ cdef class pAdicCoercion_FM_frac_field(RingHomomorphism): sage: f = K.coerce_map_from(R) sage: f.is_surjective() False - """ return False @@ -1553,7 +1545,6 @@ cdef class pAdicConvert_FM_frac_field(Morphism): a sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] Morphism._update_slots(self, _slots) diff --git a/src/sage/rings/padics/FP_template.pxi b/src/sage/rings/padics/FP_template.pxi index 5c7f94051e7..654c3d6b6a3 100644 --- a/src/sage/rings/padics/FP_template.pxi +++ b/src/sage/rings/padics/FP_template.pxi @@ -87,7 +87,7 @@ cdef inline bint huge_val(long ordp) noexcept: cdef class FPElement(pAdicTemplateElement): cdef int _set(self, x, long val, long xprec, absprec, relprec) except -1: """ - Sets the value of this element from given defining data. + Set the value of this element from given defining data. This function is intended for use in conversion, and should not be called on an element created with :meth:`_new_c`. @@ -100,10 +100,10 @@ cdef class FPElement(pAdicTemplateElement): - ``val`` -- the valuation of the resulting element - ``xprec -- an inherent precision of ``x``, if ``val`` - is larger then the result will be zero. + is larger then the result will be zero - ``absprec`` -- an absolute precision cap for this element, - if ``val`` is larger then the result will be zero. + if ``val`` is larger then the result will be zero - ``relprec`` -- a relative precision cap for this element (unused; for compatibility with other `p`-adic precision @@ -149,7 +149,7 @@ cdef class FPElement(pAdicTemplateElement): cdef int _set_exact_zero(self) except -1: """ - Sets this element to zero. + Set this element to zero. TESTS:: @@ -161,7 +161,7 @@ cdef class FPElement(pAdicTemplateElement): cdef int _set_infinity(self) except -1: """ - Sets this element to zero. + Set this element to zero. TESTS:: @@ -173,7 +173,7 @@ cdef class FPElement(pAdicTemplateElement): cdef FPElement _new_c(self): """ - Creates a new element with the same basic info. + Create a new element with the same basic info. TESTS:: @@ -199,7 +199,7 @@ cdef class FPElement(pAdicTemplateElement): cdef pAdicTemplateElement _new_with_value(self, celement value, long absprec): """ - Creates a new element with a given value and absolute precision. + Create a new element with a given value and absolute precision. Used by code that doesn't know the precision type. """ @@ -211,7 +211,7 @@ cdef class FPElement(pAdicTemplateElement): cdef int _get_unit(self, celement value) except -1: """ - Sets ``value`` to the unit of this p-adic element. + Set ``value`` to the unit of this `p`-adic element. """ ccopy(value, self.unit, self.prime_pow) @@ -246,7 +246,7 @@ cdef class FPElement(pAdicTemplateElement): cdef int _normalize(self) except -1: """ - Normalizes this element, so that ``self.ordp`` is correct. + Normalize this element, so that ``self.ordp`` is correct. TESTS:: @@ -429,7 +429,7 @@ cdef class FPElement(pAdicTemplateElement): def __invert__(self): r""" - Returns multiplicative inverse of this element. + Return multiplicative inverse of this element. EXAMPLES:: @@ -530,7 +530,7 @@ cdef class FPElement(pAdicTemplateElement): """ Quotient with remainder. - We choose the remainder to have the same p-adic expansion + We choose the remainder to have the same `p`-adic expansion as the numerator, but truncated at the valuation of the denominator. EXAMPLES:: @@ -667,7 +667,7 @@ cdef class FPElement(pAdicTemplateElement): cdef pAdicTemplateElement _lshift_c(self, long shift): r""" - Multiplies self by `\pi^{shift}`. + Multiply ``self`` by `\pi^{shift}`. Negative shifts may truncate the result if the parent is not a field. @@ -720,7 +720,7 @@ cdef class FPElement(pAdicTemplateElement): cdef pAdicTemplateElement _rshift_c(self, long shift): r""" - Divides by `\pi^{shift}`. + Divide by `\pi^{shift}`. Positive shifts may truncate the result if the parent is not a field. @@ -778,10 +778,10 @@ cdef class FPElement(pAdicTemplateElement): INPUT: - ``mode`` -- allows one to override the default print mode of - the parent (default: ``None``). + the parent (default: ``None``) - ``do_latex`` -- whether to return a latex representation or - a normal one. + a normal one EXAMPLES:: @@ -800,11 +800,9 @@ cdef class FPElement(pAdicTemplateElement): INPUT: - - ``absprec`` -- an integer or infinity + - ``absprec`` -- integer or infinity - OUTPUT: - - a new element truncated modulo `\pi^{\mbox{absprec}}`. + OUTPUT: a new element truncated modulo `\pi^{\mbox{absprec}}` EXAMPLES:: @@ -839,7 +837,7 @@ cdef class FPElement(pAdicTemplateElement): cpdef bint _is_exact_zero(self) except -1: """ - Tests whether this element is exactly zero. + Test whether this element is exactly zero. EXAMPLES:: @@ -852,7 +850,7 @@ cdef class FPElement(pAdicTemplateElement): cpdef bint _is_inexact_zero(self) except -1: """ - Return ``True`` if self is indistinguishable from zero. + Return ``True`` if ``self`` is indistinguishable from zero. EXAMPLES:: @@ -866,11 +864,11 @@ cdef class FPElement(pAdicTemplateElement): def is_zero(self, absprec = None): r""" - Returns whether ``self`` is zero modulo `\pi^{\mbox{absprec}}`. + Return whether ``self`` is zero modulo `\pi^{\mbox{absprec}}`. INPUT: - - ``absprec`` -- an integer + - ``absprec`` -- integer EXAMPLES:: @@ -919,7 +917,7 @@ cdef class FPElement(pAdicTemplateElement): INPUT: - ``right`` -- a `p`-adic element with the same parent - - ``absprec`` -- a positive integer or ``None`` (default: ``None``) + - ``absprec`` -- positive integer or ``None`` (default: ``None``) EXAMPLES:: @@ -1006,7 +1004,7 @@ cdef class FPElement(pAdicTemplateElement): def _teichmuller_set_unsafe(self): """ - Sets this element to the Teichmuller representative with the + Set this element to the Teichmuller representative with the same residue. .. WARNING:: @@ -1264,7 +1262,6 @@ cdef class pAdicCoercion_ZZ_FP(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, R): """ @@ -1345,7 +1342,7 @@ cdef class pAdicCoercion_ZZ_FP(RingHomomorphism): - ``x`` -- an Integer - ``absprec``, or the first positional argument -- the maximum - absolute precision (unused for floating point elements). + absolute precision (unused for floating point elements) - ``relprec``, or the second positional argument -- the maximum relative precision (unused for floating point @@ -1384,7 +1381,7 @@ cdef class pAdicCoercion_ZZ_FP(RingHomomorphism): def section(self): r""" - Returns a map back to `\ZZ` that approximates an element of this + Return a map back to `\ZZ` that approximates an element of this `p`-adic ring by an integer. EXAMPLES:: @@ -1403,9 +1400,9 @@ cdef class pAdicCoercion_ZZ_FP(RingHomomorphism): cdef class pAdicConvert_FP_ZZ(RingMap): r""" The map from a floating point ring back to `\ZZ` that returns the smallest - non-negative integer approximation to its input which is accurate up to the precision. + nonnegative integer approximation to its input which is accurate up to the precision. - If the input is not in the closure of the image of `\ZZ`, raises a :class:`ValueError`. + If the input is not in the closure of the image of `\ZZ`, raises a :exc:`ValueError`. EXAMPLES:: @@ -1476,7 +1473,6 @@ cdef class pAdicCoercion_QQ_FP(RingHomomorphism): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, R): """ @@ -1760,7 +1756,7 @@ cdef class pAdicConvert_QQ_FP(Morphism): - ``x`` -- a Rational - ``absprec``, or the first positional argument -- the maximum - absolute precision (unused for floating point elements). + absolute precision (unused for floating point elements) - ``relprec``, or the second positional argument -- the maximum relative precision (unused for floating point @@ -1815,7 +1811,6 @@ cdef class pAdicCoercion_FP_frac_field(RingHomomorphism): TESTS:: sage: TestSuite(f).run() # needs sage.libs.flint - """ def __init__(self, R, K): r""" @@ -1916,7 +1911,7 @@ cdef class pAdicCoercion_FP_frac_field(RingHomomorphism): def section(self): r""" Return a map back to the ring that converts elements of - non-negative valuation. + nonnegative valuation. EXAMPLES:: @@ -1981,7 +1976,6 @@ cdef class pAdicCoercion_FP_frac_field(RingHomomorphism): a sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] self._section = _slots['_section'] @@ -2151,7 +2145,6 @@ cdef class pAdicConvert_FP_frac_field(Morphism): a sage: g(a) == f(a) True - """ self._zero = _slots['_zero'] Morphism._update_slots(self, _slots) diff --git a/src/sage/rings/padics/README.txt b/src/sage/rings/padics/README.txt index b1204f9c63a..ed259a23f46 100644 --- a/src/sage/rings/padics/README.txt +++ b/src/sage/rings/padics/README.txt @@ -8,7 +8,7 @@ #***************************************************************************** This document aims at explaining the (somehow complicated) file structure and -class hierarchy for p-adics in Sage. +class hierarchy for `p`-adics in Sage. Below is a representation of the parent hierarchy. diff --git a/src/sage/rings/padics/common_conversion.pyx b/src/sage/rings/padics/common_conversion.pyx index 2a143e6d99e..a352cc74c18 100644 --- a/src/sage/rings/padics/common_conversion.pyx +++ b/src/sage/rings/padics/common_conversion.pyx @@ -1,9 +1,9 @@ r""" -The functions in this file are used in creating new p-adic elements. +The functions in this file are used in creating new `p`-adic elements. -When creating a p-adic element, the user can specify that the absolute +When creating a `p`-adic element, the user can specify that the absolute precision be bounded and/or that the relative precision be bounded. -Moreover, different p-adic parents impose their own bounds on the +Moreover, different `p`-adic parents impose their own bounds on the relative or absolute precision of their elements. The precision determines to what power of `p` the defining data will be reduced, but the valuation of the resulting element needs to be determined before @@ -65,9 +65,9 @@ cdef long get_ordp(x, PowComputer_class prime_pow) except? -10000: INPUT: - - ``x`` -- data defining a new p-adic element: a Python int, an + - ``x`` -- data defining a new `p`-adic element: a Python int, an Integer, Rational, an element of Zp or Qp with the same prime, a - PARI p-adic element, a list, a tuple, or an IntegerMod. + PARI `p`-adic element, a list, a tuple, or an IntegerMod. - a PowComputer associated to a `p`-adic ring, which determines the prime and the ramification degree. @@ -176,9 +176,9 @@ cdef long get_preccap(x, PowComputer_class prime_pow) except? -10000: INPUT: - - ``x`` -- data defining a new p-adic element: an Integer, + - ``x`` -- data defining a new `p`-adic element: an Integer, Rational, an element of Zp or Qp with the same prime, a PARI - p-adic element, a list, a tuple, or an IntegerMod. + `p`-adic element, a list, a tuple, or an IntegerMod. - ``prime_pow`` -- the PowComputer for the ring into which ``x`` is being converted. This is used to determine the prime and the ramification degree. @@ -235,10 +235,10 @@ cdef long comb_prec(iprec, long prec) except? -10000: INPUT: - - ``iprec`` -- either infinity, an Integer, a Python int or - something that can be converted to an Integer. + - ``iprec`` -- infinity, integer or something that can be converted to an + integer - - ``prec`` -- a long. + - ``prec`` -- a long """ if iprec is infinity: return prec cdef Integer intprec @@ -258,21 +258,21 @@ cdef int _process_args_and_kwds(long *aprec, long *rprec, args, kwds, bint absol This function obtains values for absprec and relprec from a combination of positional and keyword arguments. - When creating a p-adic element, the user can pass in two arguments: ``absprec`` and ``relprec``. + When creating a `p`-adic element, the user can pass in two arguments: ``absprec`` and ``relprec``. In implementing morphisms to speed up conversion from Integers and Rationals, we need to determine ``absprec`` and ``relprec`` from the ``args`` and ``kwds`` arguments of ``_call_with_args``. This function collects the code to do so. INPUT: - - ``args`` -- a tuple of positional arguments (at most two) + - ``args`` -- tuple of positional arguments (at most two) - - ``kwds`` -- a dictionary of keyword arguments (only + - ``kwds`` -- dictionary of keyword arguments (only ``'relprec'`` and ``'absprec'`` are used) - - ``absolute`` -- (boolean) True if the precision cap of the ring - is a cap on absolute precision, False if a cap on relative - precision. + - ``absolute`` -- boolean; ``True`` if the precision cap of the ring + is a cap on absolute precision, ``False`` if a cap on relative + precision - ``prime_pow`` -- a :class:`sage.rings.padics.pow_computer.PowComputer_class` @@ -281,10 +281,10 @@ cdef int _process_args_and_kwds(long *aprec, long *rprec, args, kwds, bint absol OUTPUT: - ``aprec`` -- (first argument) the maximum absolute precision of - the resulting element. + the resulting element - ``rprec`` -- (second argument) the maximum relative precision of - the resulting element. + the resulting element - error status """ @@ -321,14 +321,14 @@ cdef inline long cconv_mpq_t_shared(mpz_t out, mpq_t x, long prec, bint absolute INPUT: - - ``out`` -- an ``mpz_t`` to store the output. - - ``x`` -- an ``mpq_t`` giving the integer to be converted. - - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. - - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the output + - ``x`` -- an ``mpq_t`` giving the integer to be converted + - ``prec`` -- a long, giving the precision desired; absolute or + relative depending on the ``absolute`` input + - ``absolute`` -- if ``False`` then extracts the valuation and returns + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -362,10 +362,11 @@ cdef inline long cconv_mpq_t_shared(mpz_t out, mpq_t x, long prec, bint absolute cdef inline int cconv_mpq_t_out_shared(mpq_t out, mpz_t x, long valshift, long prec, PowComputer_class prime_pow) except -1: """ - Converts the underlying `p`-adic element into a rational + Convert the underlying `p`-adic element into a rational. - - ``out`` -- gives a rational approximating the input. Currently uses rational reconstruction but - may change in the future to use a more naive method + - ``out`` -- gives a rational approximating the input. Currently uses + rational reconstruction but may change in the future to use a more naive + method - ``x`` -- an ``mpz_t`` giving the underlying `p`-adic element - ``valshift`` -- a long giving the power of `p` to shift `x` by -` ``prec`` -- a long, the precision of ``x``, used in rational reconstruction @@ -392,18 +393,17 @@ cdef inline int cconv_shared(mpz_t out, x, long prec, long valshift, PowComputer INPUT: - - ``out`` -- an ``mpz_t`` to store the output. + - ``out`` -- an ``mpz_t`` to store the output - - ``x`` -- a Sage element that can be converted to a `p`-adic element. + - ``x`` -- a Sage element that can be converted to a `p`-adic element - - ``prec`` -- a long, giving the precision desired: absolute if - `valshift = 0`, relative if `valshift != 0`. + - ``prec`` -- a long, giving the precision desired; absolute if + `valshift = 0`, relative if `valshift != 0` - ``valshift`` -- the power of the uniformizer to divide by before - storing the result in ``out``. - - - ``prime_pow`` -- a PowComputer for the ring. + storing the result in ``out`` + - ``prime_pow`` -- a PowComputer for the ring """ if PyLong_Check(x): x = Integer(x) @@ -456,14 +456,14 @@ cdef inline long cconv_mpz_t_shared(mpz_t out, mpz_t x, long prec, bint absolute INPUT: - - ``out`` -- an ``mpz_t`` to store the output. - - ``x`` -- an ``mpz_t`` giving the integer to be converted. - - ``prec`` -- a long, giving the precision desired: absolute or - relative depending on the ``absolute`` input. - - ``absolute`` -- if False then extracts the valuation and returns - it, storing the unit in ``out``; if True then - just reduces ``x`` modulo the precision. - - ``prime_pow`` -- a PowComputer for the ring. + - ``out`` -- an ``mpz_t`` to store the output + - ``x`` -- an ``mpz_t`` giving the integer to be converted + - ``prec`` -- a long, giving the precision desired; absolute or + relative depending on the ``absolute`` input + - ``absolute`` -- if ``False`` then extracts the valuation and returns + it, storing the unit in ``out``; if ``True`` then just reduces ``x`` + modulo the precision + - ``prime_pow`` -- a PowComputer for the ring OUTPUT: @@ -483,15 +483,14 @@ cdef inline long cconv_mpz_t_shared(mpz_t out, mpz_t x, long prec, bint absolute cdef inline int cconv_mpz_t_out_shared(mpz_t out, mpz_t x, long valshift, long prec, PowComputer_class prime_pow) except -1: """ - Converts the underlying `p`-adic element into an integer if - possible. + Convert the underlying `p`-adic element into an integer if possible. - ``out`` -- stores the resulting integer as an integer between 0 - and `p^{prec + valshift}`. - - ``x`` -- an ``mpz_t`` giving the underlying `p`-adic element. - - ``valshift`` -- a long giving the power of `p` to shift `x` by. - -` ``prec`` -- a long, the precision of ``x``: currently not used. - - ``prime_pow`` -- a PowComputer for the ring. + and `p^{prec + valshift}` + - ``x`` -- an ``mpz_t`` giving the underlying `p`-adic element + - ``valshift`` -- a long giving the power of `p` to shift `x` by + -` ``prec`` -- a long, the precision of ``x``; currently not used + - ``prime_pow`` -- a PowComputer for the ring """ if valshift == 0: mpz_set(out, x) diff --git a/src/sage/rings/padics/eisenstein_extension_generic.py b/src/sage/rings/padics/eisenstein_extension_generic.py index 10e198abfb9..2e584291193 100644 --- a/src/sage/rings/padics/eisenstein_extension_generic.py +++ b/src/sage/rings/padics/eisenstein_extension_generic.py @@ -26,7 +26,7 @@ class EisensteinExtensionGeneric(pAdicExtensionGeneric): def __init__(self, poly, prec, print_mode, names, element_class): """ - Initializes ``self``. + Initialize ``self``. EXAMPLES:: @@ -59,7 +59,7 @@ def _extension_type(self): def absolute_e(self): """ - Return the absolute ramification index of this ring or field + Return the absolute ramification index of this ring or field. EXAMPLES:: @@ -97,11 +97,9 @@ def residue_class_field(self): INPUT: - - ``self`` -- a p-adic ring + - ``self`` -- a `p`-adic ring - OUTPUT: - - the residue field + OUTPUT: the residue field EXAMPLES:: @@ -147,7 +145,7 @@ def residue_ring(self, n): #def galois_group(self): # r""" - # Returns the Galois group of self's fraction field over Qp. + # Returns the Galois group of ``self``'s fraction field over Qp. # """ # ## # ## If K is a number field, then K.galois_group() can return diff --git a/src/sage/rings/padics/factory.py b/src/sage/rings/padics/factory.py index b3d7a232b7e..d9a86cba9d9 100644 --- a/src/sage/rings/padics/factory.py +++ b/src/sage/rings/padics/factory.py @@ -106,16 +106,15 @@ def _canonicalize_show_prec(type, print_mode, show_prec=None): INPUT: - - ``type`` -- a string: ``'capped-rel'``, ``'capped-abs'``, ``'fixed-mod'`` or ``'floating-point'``, - ``'lattice-cap'`` or ``'lattice-float'`` + - ``type`` -- string; ``'capped-rel'``, ``'capped-abs'``, ``'fixed-mod'``, + ``'floating-point'``, ``'lattice-cap'`` or ``'lattice-float'`` - - ``print_mode`` -- a string: ``'series'``, ``'terse'``, ``'val-unit'``, ``'digits'``, ``'bars'`` + - ``print_mode`` -- string; ``'series'``, ``'terse'``, ``'val-unit'``, + ``'digits'``, ``'bars'`` - - ``show_prec`` -- a boolean, string or ``None`` + - ``show_prec`` -- boolean, string, or ``None`` - OUTPUT: - - A string, either ``'bigoh'``, ``'dots'`` or ``'none'`` + OUTPUT: string; either ``'bigoh'``, ``'dots'`` or ``'none'`` EXAMPLES:: @@ -335,9 +334,9 @@ class Qp_class(UniqueFactory): INPUT: - - ``p`` -- integer: the `p` in `\QQ_p` + - ``p`` -- integer; the `p` in `\QQ_p` - - ``prec`` -- integer (default: ``20``) the precision cap of the field. + - ``prec`` -- integer (default: 20); the precision cap of the field. In the lattice capped case, ``prec`` can either be a pair (``relative_cap``, ``absolute_cap``) or an integer (understood at relative cap). @@ -347,44 +346,43 @@ class Qp_class(UniqueFactory): Except in the floating point case, individual elements keep track of their own precision. See TYPES and PRECISION below. - - ``type`` -- string (default: ``'capped-rel'``) Valid types are - ``'capped-rel'``, ``'floating-point'``, ``'lattice-cap'``, ``'lattice-float'``. - See TYPES and PRECISION below + - ``type`` -- string (default: ``'capped-rel'``); valid types are + ``'capped-rel'``, ``'floating-point'``, ``'lattice-cap'``, + ``'lattice-float'``. See TYPES and PRECISION below. - - ``print_mode`` -- string (default: ``None``). Valid modes are 'series', - 'val-unit', 'terse', 'digits', and 'bars'. See PRINTING below + - ``print_mode`` -- string (default: ``None``); valid modes are + ``'series'``, ``'val-unit'``, ``'terse'``, ``'digits'``, and ``'bars'``. + See PRINTING below. - ``names`` -- string or tuple (defaults to a string representation of - `p`). What to use whenever `p` is printed. + `p`); what to use whenever `p` is printed - - ``ram_name`` -- string. Another way to specify the name; for + - ``ram_name`` -- string; another way to specify the name. For consistency with the ``Qq`` and ``Zq`` and extension functions. - - ``print_pos`` -- bool (default ``None``) Whether to only use positive - integers in the representations of elements. See PRINTING below. + - ``print_pos`` -- boolean (default: ``None``); whether to only use + positive integers in the representations of elements. See PRINTING below. - - ``print_sep`` -- string (default ``None``) The separator character used + - ``print_sep`` -- string (default: ``None``); the separator character used in the ``'bars'`` mode. See PRINTING below. - - ``print_alphabet`` -- tuple (default ``None``) The encoding into digits + - ``print_alphabet`` -- tuple (default: ``None``); the encoding into digits for use in the 'digits' mode. See PRINTING below. - - ``print_max_terms`` -- integer (default ``None``) The maximum number of + - ``print_max_terms`` -- integer (default: ``None``); the maximum number of terms shown. See PRINTING below. - - ``show_prec`` -- a boolean or a string (default ``None``) Specify how + - ``show_prec`` -- boolean or a string (default: ``None``); specify how the precision is printed. See PRINTING below. - - ``check`` -- bool (default ``True``) whether to check if `p` is prime. + - ``check`` -- boolean (default: ``True``); whether to check if `p` is prime. Non-prime input may cause seg-faults (but can also be useful for - base n expansions for example) - - - ``label`` -- string (default ``None``) used for lattice precision to - create parents with different lattices. + base n expansions for example). - OUTPUT: + - ``label`` -- string (default: ``None``); used for lattice precision to + create parents with different lattices - - The corresponding `p`-adic field. + OUTPUT: the corresponding `p`-adic field TYPES AND PRECISION: @@ -606,7 +604,7 @@ class Qp_class(UniqueFactory): sage: d = R(-707/5^2); repr(d) '...444444444444444341.33' - Observe that the significant 0's are printed even if they are + Observe that the significant 0s are printed even if they are located in front of the number. On the contrary, unknown digits located after the comma appears as question marks. The precision can therefore be read in this mode as well. @@ -728,7 +726,7 @@ def create_key(self, p, prec=None, type='capped-rel', print_mode=None, print_sep=None, print_alphabet=None, print_max_terms=None, show_prec=None, check=True, label=None): # specific to Lattice precision r""" - Creates a key from input parameters for ``Qp``. + Create a key from input parameters for ``Qp``. See the documentation for ``Qp`` for more information. @@ -751,7 +749,7 @@ def create_key(self, p, prec=None, type='capped-rel', print_mode=None, def create_object(self, version, key): r""" - Creates an object using a given key. + Create an object using a given key. See the documentation for ``Qp`` for more information. @@ -839,57 +837,54 @@ def Qq(q, prec=None, type='capped-rel', modulus=None, names=None, As a tuple it is the pair ``(p, n)``, and as a list it is a single element list ``[(p, n)]``. - - ``prec`` -- integer (default: ``20``) the precision cap of the field. + - ``prec`` -- integer (default: 20); the precision cap of the field. Individual elements keep track of their own precision. See TYPES and PRECISION below. - - ``type`` -- string (default: ``'capped-rel'``) Valid types are + - ``type`` -- string (default: ``'capped-rel'``); valid types are ``'capped-rel'``, ``'floating-point'``, ``'lattice-cap'`` - and ``'lattice-float'``. See TYPES and PRECISION below + and ``'lattice-float'``. See TYPES and PRECISION below. - - ``modulus`` -- polynomial (default ``None``) A polynomial defining an + - ``modulus`` -- polynomial (default: ``None``); a polynomial defining an unramified extension of `\QQ_p`. See MODULUS below. - - ``names`` -- string or tuple (``None`` is only allowed when `q=p`). The - name of the generator, reducing to a generator of the residue - field. + - ``names`` -- string or tuple (``None`` is only allowed when `q=p`); the + name of the generator, reducing to a generator of the residue field. - - ``print_mode`` -- string (default: ``None``). Valid modes are ``'series'``, + - ``print_mode`` -- string (default: ``None``); valid modes are ``'series'``, ``'val-unit'``, ``'terse'``, and ``'bars'``. See PRINTING below. - ``ram_name`` -- string (defaults to string representation of `p` if - None). ``ram_name`` controls how the prime is printed. See PRINTING + ``None``). ``ram_name`` controls how the prime is printed. See PRINTING below. - ``res_name`` -- string (defaults to ``None``, which corresponds to adding a ``'0'`` to the end of the name). Controls how elements of the residue field print. - - ``print_pos`` -- bool (default ``None``) Whether to only use positive + - ``print_pos`` -- boolean (default: ``None``); whether to only use positive integers in the representations of elements. See PRINTING below. - - ``print_sep`` -- string (default ``None``) The separator character used + - ``print_sep`` -- string (default: ``None``); the separator character used in the ``'bars'`` mode. See PRINTING below. - - ``print_max_ram_terms`` -- integer (default ``None``) The maximum number + - ``print_max_ram_terms`` -- integer (default: ``None``) the maximum number of powers of `p` shown. See PRINTING below. - - ``print_max_unram_terms`` -- integer (default ``None``) The maximum + - ``print_max_unram_terms`` -- integer (default: ``None``); the maximum number of entries shown in a coefficient of `p`. See PRINTING below. - - ``print_max_terse_terms`` -- integer (default ``None``) The maximum + - ``print_max_terse_terms`` -- integer (default: ``None``); the maximum number of terms in the polynomial representation of an element (using ``'terse'``). See PRINTING below. - - ``show_prec`` -- bool (default ``None``) whether to show the precision + - ``show_prec`` -- boolean (default: ``None``); whether to show the precision for elements. See PRINTING below. - - ``check`` -- bool (default ``True``) whether to check inputs. + - ``check`` -- boolean (default: ``True``); whether to check inputs - OUTPUT: - - - The corresponding unramified `p`-adic field. + OUTPUT: the corresponding unramified `p`-adic field TYPES AND PRECISION: @@ -1306,11 +1301,11 @@ def Qq(q, prec=None, type='capped-rel', modulus=None, names=None, Check that :issue:`8162` is resolved:: - sage: R = Qq([(5,3)], names="alpha", check=False); R # needs sage.libs.ntl + sage: R = Qq([(5,3)], names='alpha', check=False); R # needs sage.libs.ntl 5-adic Unramified Extension Field in alpha defined by x^3 + 3*x + 3 - sage: Qq((5, 3), names="alpha") is R # needs sage.libs.ntl + sage: Qq((5, 3), names='alpha') is R # needs sage.libs.ntl True - sage: Qq(125.factor(), names="alpha") is R # needs sage.libs.ntl + sage: Qq(125.factor(), names='alpha') is R # needs sage.libs.ntl True Check that :issue:`18606` is resolved:: @@ -1503,9 +1498,9 @@ class Zp_class(UniqueFactory): INPUT: - - ``p`` -- integer: the `p` in `\ZZ_p` + - ``p`` -- integer; the `p` in `\ZZ_p` - - ``prec`` -- integer (default: ``20``) the precision cap of the + - ``prec`` -- integer (default: 20); the precision cap of the ring. In the lattice capped case, ``prec`` can either be a pair (``relative_cap``, ``absolute_cap``) or an integer (understood as relative cap). @@ -1516,44 +1511,42 @@ class Zp_class(UniqueFactory): keep track of their own precision. See TYPES and PRECISION below. - - ``type`` -- string (default: ``'capped-rel'``) Valid types are - ``'capped-rel'``, ``'capped-abs'``, ``'fixed-mod'``, - ``'floating-point'``, ``'lattice-cap'``, ``'lattice-float'``, ``'relaxed'``. + - ``type`` -- string (default: ``'capped-rel'``); valid types are + ``'capped-rel'``, ``'capped-abs'``, ``'fixed-mod'``, ``'floating-point'``, + ``'lattice-cap'``, ``'lattice-float'``, ``'relaxed'``. See TYPES and PRECISION below. - - ``print_mode`` -- string (default: ``None``). Valid modes are + - ``print_mode`` -- string (default: ``None``); valid modes are ``'series'``, ``'val-unit'``, ``'terse'``, ``'digits'``, and ``'bars'``. See PRINTING below. - ``names`` -- string or tuple (defaults to a string - representation of `p`). What to use whenever `p` is printed. + representation of `p`); what to use whenever `p` is printed - - ``print_pos`` -- bool (default ``None``) Whether to only use + - ``print_pos`` -- boolean (default: ``None``); whether to only use positive integers in the representations of elements. See PRINTING below. - - ``print_sep`` -- string (default ``None``) The separator + - ``print_sep`` -- string (default: ``None``); the separator character used in the ``'bars'`` mode. See PRINTING below. - - ``print_alphabet`` -- tuple (default ``None``) The encoding into + - ``print_alphabet`` -- tuple (default: ``None``); the encoding into digits for use in the ``'digits'`` mode. See PRINTING below. - - ``print_max_terms`` -- integer (default ``None``) The maximum + - ``print_max_terms`` -- integer (default: ``None``); the maximum number of terms shown. See PRINTING below. - - ``show_prec`` -- bool (default ``None``) whether to show the precision + - ``show_prec`` -- boolean (default: ``None``) whether to show the precision for elements. See PRINTING below. - - ``check`` -- bool (default ``True``) whether to check if `p` is + - ``check`` -- boolean (default: ``True``) whether to check if `p` is prime. Non-prime input may cause seg-faults (but can also be useful for base `n` expansions for example) - - ``label`` -- string (default ``None``) used for lattice precision to - create parents with different lattices. - - OUTPUT: + - ``label`` -- string (default: ``None``); used for lattice precision to + create parents with different lattices - - The corresponding `p`-adic ring. + OUTPUT: the corresponding `p`-adic ring TYPES AND PRECISION: @@ -1941,7 +1934,7 @@ def create_key(self, p, prec=None, type='capped-rel', print_mode=None, print_max_terms=None, show_prec=None, check=True, label=None): r""" - Creates a key from input parameters for ``Zp``. + Create a key from input parameters for ``Zp``. See the documentation for :func:`Zp` for more information. @@ -1979,7 +1972,7 @@ def create_key(self, p, prec=None, type='capped-rel', print_mode=None, def create_object(self, version, key): r""" - Creates an object using a given key. + Create an object using a given key. See the documentation for :func:`Zp` for more information. @@ -2055,61 +2048,59 @@ def Zq(q, prec=None, type='capped-rel', modulus=None, names=None, :class:`Factorization` object, single element list ``[(p, n)]`` where ``p`` is a prime and ``n`` a positive integer, or the pair ``(p, n)``. - - ``prec`` -- integer (default: ``20``) the precision cap of the + - ``prec`` -- integer (default: 20); the precision cap of the field. Individual elements keep track of their own precision. See TYPES and PRECISION below. - - ``type`` -- string (default: ``'capped-rel'``) Valid types are + - ``type`` -- string (default: ``'capped-rel'``); valid types are ``'capped-abs'``, ``'capped-rel'``, ``'fixed-mod'``, and ``'floating-point'``. See TYPES and PRECISION below. - - ``modulus`` -- polynomial (default None) A polynomial defining an + - ``modulus`` -- polynomial (default: ``None``); a polynomial defining an unramified extension of `\ZZ_p`. See MODULUS below. - ``names`` -- string or tuple (``None`` is only allowed when - `q=p`). The name of the generator, reducing to a generator of - the residue field. + `q=p`); the name of the generator, reducing to a generator of + the residue field - - ``print_mode`` -- string (default: ``None``). Valid modes are ``'series'``, + - ``print_mode`` -- string (default: ``None``); valid modes are ``'series'``, ``'val-unit'``, ``'terse'``, and ``'bars'``. See PRINTING below. - ``ram_name`` -- string (defaults to string representation of `p` if - ``None``). ``ram_name`` controls how the prime is printed. See PRINTING + ``None``); ``ram_name`` controls how the prime is printed. See PRINTING below. - ``res_name`` -- string (defaults to ``None``, which corresponds - to adding a ``'0'`` to the end of the name). Controls how + to adding a ``'0'`` to the end of the name); controls how elements of the residue field print. - - ``print_pos`` -- bool (default ``None``) Whether to only use + - ``print_pos`` -- boolean (default: ``None``); whether to only use positive integers in the representations of elements. See PRINTING below. - - ``print_sep`` -- string (default ``None``) The separator + - ``print_sep`` -- string (default: ``None``); the separator character used in the ``'bars'`` mode. See PRINTING below. - - ``print_max_ram_terms`` -- integer (default ``None``) The maximum + - ``print_max_ram_terms`` -- integer (default: ``None``); the maximum number of powers of `p` shown. See PRINTING below. - - ``print_max_unram_terms`` -- integer (default ``None``) The + - ``print_max_unram_terms`` -- integer (default: ``None``) the maximum number of entries shown in a coefficient of `p`. See PRINTING below. - - ``print_max_terse_terms`` -- integer (default ``None``) The maximum + - ``print_max_terse_terms`` -- integer (default: ``None``); the maximum number of terms in the polynomial representation of an element (using ``'terse'``). See PRINTING below. - - ``show_prec`` -- bool (default ``None``) Whether to show the precision - for elements. See PRINTING below. + - ``show_prec`` -- boolean (default: ``None``); whether to show the + precision for elements. See PRINTING below. - - ``check`` -- bool (default ``True``) whether to check inputs. + - ``check`` -- boolean (default: ``True``) whether to check inputs - - ``implementation`` -- string (default ``'FLINT'``) which + - ``implementation`` -- string (default: ``'FLINT'``); which implementation to use. ``'NTL'`` is the other option. - OUTPUT: - - The corresponding unramified `p`-adic ring. + OUTPUT: the corresponding unramified `p`-adic ring TYPES AND PRECISION: @@ -2561,13 +2552,12 @@ def Zq(q, prec=None, type='capped-rel', modulus=None, names=None, TESTS:: sage: # needs sage.libs.ntl - sage: R = Zq([(5,3)], names="alpha"); R + sage: R = Zq([(5,3)], names='alpha'); R 5-adic Unramified Extension Ring in alpha defined by x^3 + 3*x + 3 - sage: Zq((5, 3), names="alpha") is R + sage: Zq((5, 3), names='alpha') is R True - sage: Zq(125.factor(), names="alpha") is R + sage: Zq(125.factor(), names='alpha') is R True - """ if check: if isinstance(q, Factorization) or isinstance(q, (list, tuple)): @@ -3031,15 +3021,13 @@ def ZpER(p, prec=None, halt=None, secure=False, *args, **kwds): INPUT: - - ``prec`` -- an integer (default: ``20``), the default - precision + - ``prec`` -- integer (default: 20); the default precision - - ``halt`` -- an integer (default: twice ``prec``), the - halting precision + - ``halt`` -- integer (default: twice ``prec``); the halting precision - - ``secure`` -- a boolean (default: ``False``); if ``False``, + - ``secure`` -- boolean (default: ``False``); if ``False``, consider indistinguishable elements at the working precision - as equal; otherwise, raise an error. + as equal. Otherwise, raise an error. See documentation for :func:`Zp` for a description of the other input parameters. @@ -3053,7 +3041,7 @@ def ZpER(p, prec=None, halt=None, secure=False, *args, **kwds): Relaxed `p`-adic rings are created by the constructor :func:`ZpER`:: - sage: R = ZpER(5, print_mode="digits"); R # needs sage.libs.flint + sage: R = ZpER(5, print_mode='digits'); R # needs sage.libs.flint 5-adic Ring handled with relaxed arithmetics The precision is not capped in `R`:: @@ -3271,7 +3259,7 @@ def create_key_and_extra_args(self, base, modulus, prec=None, print_mode=None, print_max_unram_terms=None, print_max_terse_terms=None, show_prec=None, check=True, unram=False, implementation='FLINT'): r""" - Creates a key from input parameters for :class:`pAdicExtension`. + Create a key from input parameters for :class:`pAdicExtension`. See the documentation for :func:`Qq` for more information. @@ -3418,7 +3406,7 @@ def create_key_and_extra_args(self, base, modulus, prec=None, print_mode=None, def create_object(self, version, key, approx_modulus=None, shift_seed=None): r""" - Creates an object using a given key. + Create an object using a given key. See the documentation for :class:`pAdicExtension` for more information. @@ -3503,7 +3491,6 @@ def split(poly, prec): Traceback (most recent call last): ... NotImplementedError: Extensions by general polynomials not yet supported. Please use an unramified or Eisenstein polynomial. - """ raise NotImplementedError("Extensions by general polynomials not yet supported. Please use an unramified or Eisenstein polynomial.") diff --git a/src/sage/rings/padics/generic_nodes.py b/src/sage/rings/padics/generic_nodes.py index cb045b427fc..5fb70851043 100644 --- a/src/sage/rings/padics/generic_nodes.py +++ b/src/sage/rings/padics/generic_nodes.py @@ -186,7 +186,7 @@ def _test_distributivity(self, **options): Test the distributivity of `*` on `+` on (not necessarily all) elements of this set. - p-adic floating point rings only satisfy distributivity + `p`-adic floating point rings only satisfy distributivity up to a precision that depends on the elements. INPUT: @@ -276,10 +276,10 @@ class pAdicLatticeGeneric(pAdicGeneric): - ``prec`` -- the precision - - ``subtype`` -- either ``"cap"`` or ``"float"``, + - ``subtype`` -- either ``'cap'`` or ``'float'``, specifying the precision model used for tracking precision - - ``label`` -- a string or ``None`` (default: ``None``) + - ``label`` -- string or ``None`` (default: ``None``) TESTS:: @@ -546,9 +546,9 @@ def _element_constructor_(self, x, prec=None): INPUT: - - ``x``: the datum from which the element is created + - ``x`` -- the datum from which the element is created - - ``prec`` -- an integer or ``None`` (the default); the + - ``prec`` -- integer or ``None`` (the default); the absolute precision of the created element NOTE: @@ -721,7 +721,7 @@ def _get_element_class(self, name=None): INPUT: - - ``name`` -- a string or ``None`` (default: ``None``); if ``None``, + - ``name`` -- string or ``None`` (default: ``None``); if ``None``, return the generic class from which all the others derive TESTS:: @@ -813,12 +813,12 @@ def default_prec(self): EXAMPLES:: sage: # needs sage.libs.flint - sage: R = ZpER(5, print_mode="digits") + sage: R = ZpER(5, print_mode='digits') sage: R.default_prec() 20 sage: R(1/17) ...34024323104201213403 - sage: S = ZpER(5, prec=10, print_mode="digits") + sage: S = ZpER(5, prec=10, print_mode='digits') sage: S.default_prec() 10 sage: S(1/17) @@ -837,7 +837,7 @@ def halting_prec(self): EXAMPLES:: - sage: R = ZpER(5, print_mode="digits") # needs sage.libs.flint + sage: R = ZpER(5, print_mode='digits') # needs sage.libs.flint sage: R.halting_prec() # needs sage.libs.flint 40 """ @@ -881,7 +881,7 @@ def _element_constructor_(self, x, prec=None): - ``x`` -- the datum from which the element is created - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); if given, bound the precision of the element to ``prec`` EXAMPLES:: @@ -1012,10 +1012,10 @@ def unknown(self, start_val=0, digits=None): INPUT: - - ``start_val`` -- an integer (default: 0); a lower bound on the + - ``start_val`` -- integer (default: 0); a lower bound on the valuation of the returned element - - ``digits`` -- an element, a list or ``None`` (default: ``None``); + - ``digits`` -- an element, a list, or ``None`` (default: ``None``); the first digit or the list of the digits of the returned element NOTE: @@ -1111,10 +1111,10 @@ def random_element(self, integral=False, prec=None): INPUT: - - ``integral`` -- a boolean (default: ``False``); if ``True``, + - ``integral`` -- boolean (default: ``False``); if ``True``, return a random element in the ring of integers of this ring - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); if given, bound the precision of the output to ``prec`` EXAMPLES:: @@ -1149,7 +1149,7 @@ def teichmuller(self, x): EXAMPLES:: - sage: R = ZpER(5, print_mode="digits") # needs sage.libs.flint + sage: R = ZpER(5, print_mode='digits') # needs sage.libs.flint sage: R.teichmuller(2) # needs sage.libs.flint ...40423140223032431212 """ @@ -1165,7 +1165,7 @@ def teichmuller_system(self): EXAMPLES:: - sage: R = ZpER(7, print_mode="digits") # needs sage.libs.flint + sage: R = ZpER(7, print_mode='digits') # needs sage.libs.flint sage: R.teichmuller_system() # needs sage.libs.flint [...00000000000000000001, ...16412125443426203642, @@ -1192,16 +1192,14 @@ def is_field(self, proof=True): def krull_dimension(self): r""" - Return the Krull dimension of self, i.e. 1 + Return the Krull dimension of self, i.e. 1. INPUT: - - self -- a `p`-adic ring - - OUTPUT: + - ``self`` -- a `p`-adic ring - - the Krull dimension of self. Since self is a `p`-adic ring, - this is 1. + OUTPUT: the Krull dimension of ``self``. Since ``self`` is a `p`-adic + ring, this is 1. EXAMPLES:: @@ -1218,12 +1216,12 @@ def _xgcd_univariate_polynomial(self, f, g): INPUT: - - ``f``, ``g`` -- the polynomials of which to take the xgcd + - ``f``, ``g`` -- the polynomials of which to take the xgcd OUTPUT: - - A tuple (a, b, c) which satisfies ``a = b*f + c*g``. There - is no guarantee that a, b, and c are minimal. + A tuple (a, b, c) which satisfies a = b*f + c*g. There + is no guarantee that a, b, and c are minimal. .. WARNING:: @@ -1291,9 +1289,9 @@ def _gcd_univariate_polynomial(self, f, g): INPUT: - - ``f``, ``g`` -- the polynomials of which to take the gcd + - ``f``, ``g`` -- the polynomials of which to take the gcd - OUTPUT: A polynomial + OUTPUT: a polynomial EXAMPLES:: @@ -1365,7 +1363,7 @@ def construction(self, forbid_frac_field=False): INPUT: - - ``forbid_frac_field`` -- ignored, for compatibility with other p-adic types. + - ``forbid_frac_field`` -- ignored, for compatibility with other `p`-adic types EXAMPLES:: @@ -1457,9 +1455,7 @@ def composite(self, subfield1, subfield2): - ``subfield1`` -- a subfield - ``subfield2`` -- a subfield - OUTPUT: - - the composite of ``subfield1`` and ``subfield2`` + OUTPUT: the composite of ``subfield1`` and ``subfield2`` EXAMPLES:: @@ -1473,12 +1469,12 @@ def composite(self, subfield1, subfield2): def subfields_of_degree(self, n): r""" - Return the number of subfields of ``self`` of degree `n` + Return the number of subfields of ``self`` of degree `n`. INPUT: - ``self`` -- a `p`-adic field - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: @@ -1497,16 +1493,14 @@ def subfields_of_degree(self, n): def subfield(self, list): r""" - Return the subfield generated by the elements in ``list`` + Return the subfield generated by the elements in ``list``. INPUT: - ``self`` -- a `p`-adic field - - ``list`` -- a list of elements of ``self`` - - OUTPUT: + - ``list`` -- list of elements of ``self`` - the subfield of ``self`` generated by the elements of ``list`` + OUTPUT: the subfield of ``self`` generated by the elements of ``list`` EXAMPLES:: diff --git a/src/sage/rings/padics/lattice_precision.py b/src/sage/rings/padics/lattice_precision.py index fda871c3052..705feeaf3fc 100644 --- a/src/sage/rings/padics/lattice_precision.py +++ b/src/sage/rings/padics/lattice_precision.py @@ -70,9 +70,9 @@ class pRational: - ``x`` -- a rational number - - ``exponent`` -- an integer (default: 0) + - ``exponent`` -- integer (default: 0) - - ``valuation`` -- an integer or ``None`` (default: ``None``), + - ``valuation`` -- integer or ``None`` (default: ``None``); the `p`-adic valuation of this element If not ``None``, this method trusts the given value to the @@ -108,7 +108,7 @@ class pRational: """ def __init__(self, p, x, exponent=0, valuation=None): r""" - Construct the element ``x * p^exponent`` + Construct the element ``x * p^exponent``. TESTS:: @@ -147,7 +147,7 @@ def reduce(self, prec): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer TESTS:: @@ -197,7 +197,7 @@ def reduce_relative(self, prec): INPUT: - - ``prec`` -- a nonnegative integer + - ``prec`` -- nonnegative integer TESTS:: @@ -402,7 +402,7 @@ def _quo_rem(self, other): """ Quotient with remainder. - Returns a pair `q`, `r` where `r` has the p-adic expansion of this element, + Returns a pair `q`, `r` where `r` has the `p`-adic expansion of this element, truncated at the valuation of other. EXAMPLES:: @@ -446,7 +446,7 @@ def __lshift__(self, n): INPUT: - - ``n`` -- a relative integer + - ``n`` -- relative integer TESTS:: @@ -468,7 +468,7 @@ def __rshift__(self, n): INPUT: - - ``n`` -- a relative integer + - ``n`` -- relative integer TESTS:: @@ -610,7 +610,7 @@ class DifferentialPrecisionGeneric(SageObject): - ``p`` -- a prime number - - ``label`` -- a string, the label of the parents to which the elements + - ``label`` -- string; the label of the parents to which the elements belong that are tracked by this precision module .. NOTE:: @@ -632,7 +632,6 @@ def __init__(self, p, label): sage: from sage.rings.padics.lattice_precision import DifferentialPrecisionGeneric sage: isinstance(prec, DifferentialPrecisionGeneric) True - """ self._p = p self._label = label @@ -672,7 +671,7 @@ def _repr_(self): If a label has been specified, it is included in the representation:: - sage: R = ZpLC(2, label="mylabel") + sage: R = ZpLC(2, label='mylabel') sage: R.precision() Precision lattice on 0 objects (label: mylabel) """ @@ -699,8 +698,8 @@ def threshold_deletion(self, threshold=None): INPUT: - - ``threshold`` -- a non-negative integer, ``Infinity`` or ``None`` - (default: ``None``): if not ``None`` set the threshold to the given + - ``threshold`` -- nonnegative integer, ``Infinity`` or ``None`` + (default: ``None``); if not ``None`` set the threshold to the given value. .. NOTE:: @@ -740,7 +739,7 @@ def prime(self): EXAMPLES:: - sage: R = ZpLC(2, label="mylabel") + sage: R = ZpLC(2, label='mylabel') sage: R.precision().prime() 2 """ @@ -756,7 +755,7 @@ def _index(self, ref): TESTS:: sage: from sage.rings.padics.lattice_precision import pAdicLatticeElementWeakProxy - sage: R = ZpLC(2, label="index") + sage: R = ZpLC(2, label='index') sage: prec = R.precision() sage: x = R(1, 10) sage: y = R(1, 5) @@ -884,10 +883,10 @@ def del_elements(self, threshold=None): INPUT: - - ``threshold`` -- an integer or ``None`` (default: ``None``): + - ``threshold`` -- integer or ``None`` (default: ``None``); a column whose distance to the right is greater than the - threshold is not erased but marked for deletion; - if ``None``, always erase (never mark for deletion). + threshold is not erased but marked for deletion. + If ``None``, always erase (never mark for deletion). EXAMPLES:: @@ -954,7 +953,7 @@ def precision_lattice(self, elements=None): INPUT: - - ``elements`` -- a list of elements or ``None`` (default: ``None``) + - ``elements`` -- list of elements or ``None`` (default: ``None``) EXAMPLES:: @@ -1058,11 +1057,11 @@ def tracked_elements(self, values=True, dead=True): INPUT: - - ``values`` -- a boolean (default: ``True``); if false, + - ``values`` -- boolean (default: ``True``); if ``False``, the method returns a list of weak references on tracked elements instead - - ``dead`` -- a boolean (default: ``True``); whether dead + - ``dead`` -- boolean (default: ``True``); whether dead elements for which the corresponding column is still not erased should be listed or not @@ -1258,17 +1257,17 @@ def history(self, compact=True, separate_reduce=False, timings=True, output_type INPUT: - - ``compact`` -- a boolean (default: ``True``); if true, all + - ``compact`` -- boolean (default: ``True``); if ``True``, all consecutive operations of the same type appear on a single row - - ``separate_reduce`` -- a boolean (default: ``False``); specify + - ``separate_reduce`` -- boolean (default: ``False``); specify whether partial/full Hermite reduction should be displayed separately - - ``timings`` -- a boolean (default: ``True``); specify whether + - ``timings`` -- boolean (default: ``True``); specify whether timings should be displayed - - ``output_type`` -- only ``asciiart`` is implemented for now. + - ``output_type`` -- only ``asciiart`` is implemented for now IMPORTANT NOTE: @@ -1483,7 +1482,7 @@ def timings(self, action=None): INPUT: - - ``action`` -- ``None`` (the default), ``'add'``, ``'mark'``, ``'del'``, + - ``action`` -- ``None`` (default), ``'add'``, ``'mark'``, ``'del'``, ``'partial reduce'`` or ``'full reduce'``; if not ``None``, return the cumulated timing corresponding to this action; otherwise, return a dictionary @@ -1543,8 +1542,8 @@ class PrecisionLattice(UniqueRepresentation, DifferentialPrecisionGeneric): - ``p`` -- a prime number - - ``label`` -- a string, the label of the parents to which the elements - tracked by this lattice belong. + - ``label`` -- string; the label of the parents to which the elements + tracked by this lattice belong .. NOTE:: @@ -1565,7 +1564,6 @@ def __init__(self, p, label): sage: R = ZpLC(2) sage: isinstance(R.precision(), PrecisionLattice) True - """ DifferentialPrecisionGeneric.__init__(self, p, label) self._repr_type = "Precision lattice" @@ -1593,7 +1591,7 @@ def _index(self, ref): TESTS:: sage: from sage.rings.padics.lattice_precision import pAdicLatticeElementWeakProxy - sage: R = ZpLC(2, label="index") + sage: R = ZpLC(2, label='index') sage: prec = R.precision() sage: x = R(1, 10) sage: y = R(1, 5) @@ -1633,10 +1631,10 @@ def reduce(self, index=0, partial=False): INPUT: - - ``index`` -- an integer, the starting row for which the reduction + - ``index`` -- integer; the starting row for which the reduction is performed - - ``partial`` -- a boolean (default: ``False``) specifying whether a + - ``partial`` -- boolean (default: ``False``); specifying whether a partial or a full Hermite reduction should be performed NOTE: @@ -1715,16 +1713,16 @@ def _new_element(self, x, dx, bigoh, dx_mode='linear_combination', capped=False) - ``x`` -- the newly created element - - ``dx`` -- a dictionary representing the differential of ``x`` + - ``dx`` -- dictionary representing the differential of ``x`` - - ``bigoh`` -- an integer or ``None`` (default: ``None``): the + - ``bigoh`` -- integer or ``None`` (default: ``None``); the bigoh to be added to the precision of ``x``; if ``None``, the default cap is used. - - ``dx_mode`` -- a string, either ``linear_combination`` (the default) + - ``dx_mode`` -- string; either ``linear_combination`` (the default) or ``values`` - - ``capped`` -- a boolean, whether this element has been capped + - ``capped`` -- boolean; whether this element has been capped according to the parent's cap If ``dx_mode`` is ``linear_combination``, the dictionary ``dx`` @@ -1796,7 +1794,7 @@ def del_elements(self, threshold=None): INPUT: - - ``threshold`` -- an integer or ``None`` (default: ``None``): + - ``threshold`` -- integer or ``None`` (default: ``None``); a column whose distance to the right is greater than the threshold is not erased @@ -2064,9 +2062,9 @@ def precision_lattice(self, elements=None): INPUT: - - ``elements`` -- a list of elements or ``None`` (default: ``None``) + - ``elements`` -- list of elements or ``None`` (default: ``None``) - - ``echelon`` -- a boolean (default: ``True``); whether the result + - ``echelon`` -- boolean (default: ``True``); whether the result should be in echelon form EXAMPLES:: @@ -2158,7 +2156,7 @@ def __init__(self, p, label, prec): - ``p`` -- a prime number - - ``label`` -- a string, the label of the parents to which belong + - ``label`` -- string; the label of the parents to which belong the elements tracked by this precision module NOTE: @@ -2301,16 +2299,16 @@ def _new_element(self, x, dx, bigoh, dx_mode='linear_combination'): - ``x`` -- the newly created element - - ``dx`` -- a dictionary representing the differential of ``x`` + - ``dx`` -- dictionary representing the differential of ``x`` - - ``bigoh`` -- an integer or ``None`` (default: ``None``): the - bigoh to be added to the precision of ``x``; if ``None``, the + - ``bigoh`` -- integer or ``None`` (default: ``None``); the + bigoh to be added to the precision of ``x``. If ``None``, the default cap is used. - - ``dx_mode`` -- a string, either ``"linear_combination"`` (the - default) or ``"values"`` + - ``dx_mode`` -- string; either ``'linear_combination'`` (the + default) or ``'values'`` - If ``dx_mode`` is ``"linear_combination"``, the dictionary ``dx`` + If ``dx_mode`` is ``'linear_combination'``, the dictionary ``dx`` encodes the expression of the differential of ``x``. For example, if ``x`` was defined as ``x = y*z`` then: @@ -2322,7 +2320,7 @@ def _new_element(self, x, dx, bigoh, dx_mode='linear_combination'): that the keys are not the elements themselves but weak references to them). - If ``dx_mode`` is ``"values"``, the dictionary ``dx`` directly + If ``dx_mode`` is ``'values'``, the dictionary ``dx`` directly specifies the entries that have to stored in the precision module. This mode is only used for multiple conversion between different parents (see :meth:`multiple_conversion`). @@ -2396,7 +2394,7 @@ def del_elements(self, threshold=None): INPUT: - - ``threshold`` -- an integer or ``None`` (default: ``None``): + - ``threshold`` -- integer or ``None`` (default: ``None``); a non-pivot column whose distance to the right is greater than the threshold is not erased but only marked for future deletion @@ -2669,7 +2667,7 @@ def precision_lattice(self, elements=None): INPUT: - - ``elements`` -- a list of elements or ``None`` (default: ``None``) + - ``elements`` -- list of elements or ``None`` (default: ``None``) EXAMPLES:: @@ -2782,7 +2780,6 @@ def __init__(self, element, callback=None): True sage: pAdicLatticeElementWeakProxy(p) is pAdicLatticeElementWeakProxy(p) False - """ if not hasattr(element, '_proxy_id'): element._proxy_id = pAdicLatticeElementWeakProxy._next_id @@ -2805,7 +2802,6 @@ def __hash__(self): sage: p = R(2) sage: hash(pAdicLatticeElementWeakProxy(p)) == hash(pAdicLatticeElementWeakProxy(p)) True - """ return self._id @@ -2823,7 +2819,6 @@ def __eq__(self, other): True sage: pAdicLatticeElementWeakProxy(q) == pAdicLatticeElementWeakProxy(p) False - """ return isinstance(other, pAdicLatticeElementWeakProxy) and self._id == other._id @@ -2839,7 +2834,6 @@ def __call__(self): sage: p = R(2) sage: pAdicLatticeElementWeakProxy(p)() 2 + O(2^21) - """ return self._weakref() @@ -2854,7 +2848,6 @@ def __repr__(self): sage: p = R(2) sage: R.precision()._elements # indirect doctest [WeakProxy#...] - """ return "WeakProxy#%s" % (self._id,) diff --git a/src/sage/rings/padics/local_generic.py b/src/sage/rings/padics/local_generic.py index 349a8ec17dc..397dab2ed8e 100644 --- a/src/sage/rings/padics/local_generic.py +++ b/src/sage/rings/padics/local_generic.py @@ -41,7 +41,7 @@ def __init__(self, base, prec, names, element_class, category=None): sage: R.precision_cap() 20 - In :issue:`14084`, the category framework has been implemented for p-adic rings:: + In :issue:`14084`, the category framework has been implemented for `p`-adic rings:: sage: TestSuite(R).run() # needs sage.geometry.polyhedron sage: K = Qp(7) @@ -244,14 +244,14 @@ def change(self, **kwds): The following arguments are applied to every ring in the tower: - ``type`` -- string, the precision type - - ``p`` -- the prime of the ground ring. Defining polynomials - will be converted to the new base rings. + - ``p`` -- the prime of the ground ring; defining polynomials + will be converted to the new base rings - ``print_mode`` -- string - - ``print_pos`` -- bool + - ``print_pos`` -- boolean - ``print_sep`` -- string - - ``print_alphabet`` -- dict - - ``show_prec`` -- bool - - ``check`` -- bool + - ``print_alphabet`` -- dictionary + - ``show_prec`` -- boolean + - ``check`` -- boolean - ``label`` -- string (only for lattice precision) The following arguments are only applied to the top ring in the tower: @@ -265,19 +265,19 @@ def change(self, **kwds): The following arguments have special behavior: - - ``prec`` -- integer. If the precision is increased on an extension ring, + - ``prec`` -- integer; if the precision is increased on an extension ring, the precision on the base is increased as necessary (respecting ramification). If the precision is decreased, the precision of the base is unchanged. - - ``field`` -- bool. If ``True``, switch to a tower of fields via the fraction field. - If False, switch to a tower of rings of integers. + - ``field`` -- boolean; if ``True``, switch to a tower of fields via the fraction field + If ``False``, switch to a tower of rings of integers - - ``q`` -- prime power. Replace the initial unramified extension of `\QQ_p` or `\ZZ_p` + - ``q`` -- prime power; replace the initial unramified extension of `\QQ_p` or `\ZZ_p` with an unramified extension of residue cardinality `q`. If the initial extension is ramified, add in an unramified extension. - - ``base`` -- ring or field. Use a specific base ring instead of recursively - calling :meth:`change` down the tower. + - ``base`` -- ring or field; use a specific base ring instead of recursively + calling :meth:`change` down the tower See the :mod:`constructors ` for more details on the meaning of these arguments. @@ -291,7 +291,7 @@ def change(self, **kwds): or the precision type:: - sage: Zp(5).change(type="capped-abs") + sage: Zp(5).change(type='capped-abs') 5-adic Ring with capped absolute precision 20 or even the prime:: @@ -617,11 +617,9 @@ def residue_characteristic(self): INPUT: - - ``self`` -- a p-adic ring. - - OUTPUT: + - ``self`` -- a `p`-adic ring - The characteristic of the residue field. + OUTPUT: the characteristic of the residue field EXAMPLES:: @@ -632,19 +630,17 @@ def residue_characteristic(self): def defining_polynomial(self, var='x', exact=False): r""" - Return the defining polynomial of this local ring + Return the defining polynomial of this local ring. INPUT: - - ``var`` -- string (default: ``'x'``), the name of the variable - - - ``exact`` -- a boolean (default: ``False``), whether to return the - underlying exact defining polynomial rather than the one with coefficients - in the base ring. + - ``var`` -- string (default: ``'x'``); the name of the variable - OUTPUT: + - ``exact`` -- boolean (default: ``False``); whether to return the + underlying exact defining polynomial rather than the one with coefficients + in the base ring - The defining polynomial of this ring as an extension over its ground ring + OUTPUT: the defining polynomial of this ring as an extension over its ground ring EXAMPLES:: @@ -675,9 +671,7 @@ def ground_ring(self): - ``self`` -- a local ring - OUTPUT: - - The ground ring of ``self``, i.e., itself. + OUTPUT: the ground ring of ``self``, i.e., itself EXAMPLES:: @@ -700,9 +694,7 @@ def ground_ring_of_tower(self): - ``self`` -- a `p`-adic ring - OUTPUT: - - The ground ring of the tower for ``self``, i.e., itself. + OUTPUT: the ground ring of the tower for ``self``, i.e., itself EXAMPLES:: @@ -714,7 +706,7 @@ def ground_ring_of_tower(self): def absolute_degree(self): r""" - Return the degree of this extension over the prime p-adic field/ring. + Return the degree of this extension over the prime `p`-adic field/ring. EXAMPLES:: @@ -1004,9 +996,7 @@ def inertia_subring(self): - ``self`` -- a local ring - OUTPUT: - - - the inertia subring of self, i.e., itself + OUTPUT: the inertia subring of ``self``, i.e., itself EXAMPLES:: @@ -1024,9 +1014,7 @@ def maximal_unramified_subextension(self): - ``self`` -- a local ring - OUTPUT: - - - the maximal unramified subextension of ``self`` + OUTPUT: the maximal unramified subextension of ``self`` EXAMPLES:: @@ -1061,7 +1049,8 @@ def uniformiser(self): def uniformiser_pow(self, n): r""" - Return the `n`th power of the uniformiser of ``self`` (as an element of ``self``). + Return the `n`-th power of the uniformiser of ``self`` (as an element + of ``self``). EXAMPLES:: @@ -1093,7 +1082,6 @@ def _test_add_bigoh(self, **options): sage: K = Qp(3) sage: K._test_add_bigoh() - """ tester = self._tester(**options) for x in tester.some_elements(): @@ -1131,7 +1119,6 @@ def _test_residue(self, **options): sage: R = Zp(2) sage: R._test_residue() - """ tester = self._tester(**options) tester.assertEqual(self.residue_field().characteristic(), self.residue_characteristic()) @@ -1222,14 +1209,14 @@ def _matrix_smith_form(self, M, transformation, integral, exact): :meth:`sage.matrix.matrix2.Matrix.smith_form` to compute the Smith normal form over local rings and fields. - The entries of the Smith normal form are normalized such that non-zero + The entries of the Smith normal form are normalized such that nonzero entries of the diagonal are powers of the distinguished uniformizer. INPUT: - ``M`` -- a matrix over this ring - - ``transformation`` -- a boolean; whether the transformation matrices + - ``transformation`` -- boolean; whether the transformation matrices are returned - ``integral`` -- a subring of the base ring or ``True``; the entries @@ -1237,13 +1224,13 @@ def _matrix_smith_form(self, M, transformation, integral, exact): entries are in the ring of integers of the base ring. - ``exact`` -- boolean. If ``True``, the diagonal smith form will - be exact, or raise a ``PrecisionError`` if this is not possible. + be exact, or raise a :exc:`PrecisionError` if this is not possible If ``False``, the diagonal entries will be inexact, but the transformation matrices will be exact. EXAMPLES:: - sage: A = Zp(5, prec=10, print_mode="digits") + sage: A = Zp(5, prec=10, print_mode='digits') sage: M = matrix(A, 2, 2, [2, 7, 1, 6]) sage: S, L, R = M.smith_form() # indirect doctest @@ -1494,7 +1481,6 @@ def _test_matrix_smith(self, **options): EXAMPLES:: sage: ZpCA(5, 15)._test_matrix_smith() # needs sage.geometry.polyhedron - """ tester = self._tester(**options) tester.assertEqual(self.residue_field().characteristic(), self.residue_characteristic()) diff --git a/src/sage/rings/padics/local_generic_element.pyx b/src/sage/rings/padics/local_generic_element.pyx index e0a03ea2450..4fb34b774fe 100644 --- a/src/sage/rings/padics/local_generic_element.pyx +++ b/src/sage/rings/padics/local_generic_element.pyx @@ -34,14 +34,14 @@ cdef class LocalGenericElement(CommutativeRingElement): cpdef _div_(self, right): r""" - Returns the quotient of ``self`` by ``right``. + Return the quotient of ``self`` by ``right``. INPUT: - - ``self`` -- a `p`-adic element. + - ``self`` -- a `p`-adic element - - ``right`` -- a `p`-adic element distinguishable from zero. - In a fixed-modulus ring, this element must be a unit. + - ``right`` -- a `p`-adic element distinguishable from zero; + in a fixed-modulus ring, this element must be a unit EXAMPLES:: @@ -63,11 +63,9 @@ cdef class LocalGenericElement(CommutativeRingElement): def inverse_of_unit(self): r""" - Returns the inverse of ``self`` if ``self`` is a unit. + Return the inverse of ``self`` if ``self`` is a unit. - OUTPUT: - - - an element in the same ring as ``self`` + OUTPUT: an element in the same ring as ``self`` EXAMPLES:: @@ -77,7 +75,7 @@ cdef class LocalGenericElement(CommutativeRingElement): sage: b = a.inverse_of_unit(); b 2 + 3 + 3^2 + 3^3 + 3^4 + O(3^5) - A ``ZeroDivisionError`` is raised if an element has no inverse in the + A :exc:`ZeroDivisionError` is raised if an element has no inverse in the ring:: sage: R(3).inverse_of_unit() @@ -112,7 +110,7 @@ cdef class LocalGenericElement(CommutativeRingElement): TESTS: - Test that this works for all kinds of p-adic base elements:: + Test that this works for all kinds of `p`-adic base elements:: sage: ZpCA(3,5)(2).inverse_of_unit() 2 + 3 + 3^2 + 3^3 + 3^4 + O(3^5) @@ -163,7 +161,6 @@ cdef class LocalGenericElement(CommutativeRingElement): sage: R = QpCR(3,5); S. = R[]; W. = R.extension( t^2 - 3 ) sage: (t - 1).inverse_of_unit() 2 + 2*t + t^2 + t^3 + t^4 + t^5 + t^6 + t^7 + t^8 + t^9 + O(t^10) - """ if not self.is_unit(): raise ZeroDivisionError(f"inverse of {self} does not exist") @@ -172,7 +169,7 @@ cdef class LocalGenericElement(CommutativeRingElement): def __iter__(self): """ Local elements should not be iterable, so this method correspondingly - raises a ``TypeError``. + raises a :exc:`TypeError`. .. NOTE:: @@ -194,13 +191,12 @@ cdef class LocalGenericElement(CommutativeRingElement): Traceback (most recent call last): ... TypeError: this local element is not iterable - """ raise TypeError("this local element is not iterable") def slice(self, i, j, k = 1, lift_mode='simple'): r""" - Returns the sum of the `pi^{i + l \cdot k}` terms of the series + Return the sum of the `pi^{i + l \cdot k}` terms of the series expansion of this element, where pi is the uniformizer, for `i + l \cdot k` between ``i`` and ``j-1`` inclusive, and nonnegative integers `l`. Behaves analogously to the slice @@ -208,11 +204,11 @@ cdef class LocalGenericElement(CommutativeRingElement): INPUT: - - ``i`` -- an integer; if set to ``None``, the sum will start with the - first non-zero term of the series. + - ``i`` -- integer; if set to ``None``, the sum will start with the + first nonzero term of the series - - ``j`` -- an integer; if set to ``None`` or `\infty`, this method - behaves as if it was set to the absolute precision of this element. + - ``j`` -- integer; if set to ``None`` or `\infty`, this method + behaves as if it was set to the absolute precision of this element - ``k`` -- (default: 1) a positive integer @@ -357,7 +353,6 @@ cdef class LocalGenericElement(CommutativeRingElement): sage: a = F(0) sage: a.slice(0,None) 0 - """ if k is None: k = 1 @@ -380,7 +375,7 @@ cdef class LocalGenericElement(CommutativeRingElement): start -= self.valuation() stop -= self.valuation() - # make sure that start and stop are non-negative + # make sure that start and stop are nonnegative if start<0: i += -start # fix the value of ppow below start = 0 @@ -412,7 +407,7 @@ cdef class LocalGenericElement(CommutativeRingElement): def _latex_(self): r""" - Return a latex representation of self. + Return a latex representation of ``self``. EXAMPLES:: @@ -437,7 +432,7 @@ cdef class LocalGenericElement(CommutativeRingElement): cpdef _sub_(self, right): r""" - Returns the difference between ``self`` and ``right``. + Return the difference between ``self`` and ``right``. EXAMPLES:: @@ -456,7 +451,7 @@ cdef class LocalGenericElement(CommutativeRingElement): INPUT: - - ``absprec`` -- an integer or positive infinity + - ``absprec`` -- integer or positive infinity EXAMPLES:: @@ -514,7 +509,6 @@ cdef class LocalGenericElement(CommutativeRingElement): sage: R. = Qp(7).extension(x^3 - 7) # needs sage.libs.ntl sage: (pi^93).add_bigoh(-10) # needs sage.libs.ntl sage.symbolic O(pi^-10) - """ parent = self.parent() if absprec >= self.precision_absolute(): @@ -531,15 +525,13 @@ cdef class LocalGenericElement(CommutativeRingElement): def is_integral(self): """ - Returns whether self is an integral element. + Return whether ``self`` is an integral element. INPUT: - ``self`` -- a local ring element - OUTPUT: - - - boolean -- whether ``self`` is an integral element. + OUTPUT: boolean; whether ``self`` is an integral element EXAMPLES:: @@ -556,15 +548,14 @@ cdef class LocalGenericElement(CommutativeRingElement): def is_padic_unit(self): """ - Returns whether self is a `p`-adic unit. That is, whether it has zero valuation. + Return whether ``self`` is a `p`-adic unit. That is, whether it has + zero valuation. INPUT: - ``self`` -- a local ring element - OUTPUT: - - - boolean -- whether ``self`` is a unit + OUTPUT: boolean; whether ``self`` is a unit EXAMPLES:: @@ -613,15 +604,13 @@ cdef class LocalGenericElement(CommutativeRingElement): def is_unit(self): """ - Returns whether self is a unit + Return whether ``self`` is a unit. INPUT: - ``self`` -- a local ring element - OUTPUT: - - - boolean -- whether ``self`` is a unit + OUTPUT: boolean; whether ``self`` is a unit .. NOTE:: @@ -722,24 +711,22 @@ cdef class LocalGenericElement(CommutativeRingElement): INPUT: - - ``self`` -- a `p`-adic element. + - ``self`` -- a `p`-adic element - - ``extend`` -- a boolean (default: ``True``); if ``True``, return a + - ``extend`` -- boolean (default: ``True``); if ``True``, return a square root in an extension if necessary; if ``False`` and no root - exists in the given ring or field, raise a ValueError. + exists in the given ring or field, raise a :exc:`ValueError`. - - ``all`` -- a boolean (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots - - ``algorithm`` -- ``"pari"``, ``"sage"`` or ``None`` (default: + - ``algorithm`` -- ``'pari'``, ``'sage'`` or ``None`` (default: ``None``); Sage provides an implementation for any extension of `Q_p` whereas only square roots over `Q_p` is implemented in Pari; - the default is ``"pari"`` if the ground field is `Q_p`, ``"sage"`` + the default is ``'pari'`` if the ground field is `Q_p`, ``'sage'`` otherwise. - OUTPUT: - - The square root or the list of all square roots of this element. + OUTPUT: the square root or the list of all square roots of this element .. NOTE:: @@ -839,16 +826,14 @@ cdef class LocalGenericElement(CommutativeRingElement): def normalized_valuation(self): r""" - Returns the normalized valuation of this local ring element, + Return the normalized valuation of this local ring element, i.e., the valuation divided by the absolute ramification index. INPUT: - - ``self`` -- a local ring element. - - OUTPUT: + - ``self`` -- a local ring element - rational -- the normalized valuation of ``self``. + OUTPUT: rational; the normalized valuation of ``self`` EXAMPLES:: @@ -863,17 +848,15 @@ cdef class LocalGenericElement(CommutativeRingElement): def _min_valuation(self): r""" - Returns the valuation of this local ring element. + Return the valuation of this local ring element. This function only differs from valuation for relaxed elements. INPUT: - - ``self`` -- a local ring element. - - OUTPUT: + - ``self`` -- a local ring element - - integer -- the valuation of ``self``. + OUTPUT: integer; the valuation of ``self`` EXAMPLES:: @@ -933,9 +916,9 @@ cdef class LocalGenericElement(CommutativeRingElement): INPUT: - ``other`` -- an element in the same ring - - ``integral`` -- if True, use integral-style remainders even when the parent is a field. - Namely, the remainder will have no terms in its p-adic expansion above - the valuation of ``other``. + - ``integral`` -- if ``True``, use integral-style remainders even when + the parent is a field. Namely, the remainder will have no terms in + its `p`-adic expansion above the valuation of ``other``. EXAMPLES:: @@ -976,7 +959,6 @@ cdef class LocalGenericElement(CommutativeRingElement): sage: x = Zp(3, 5).zero() sage: x._test_trivial_powers() - """ tester = self._tester(**options) @@ -997,7 +979,6 @@ cdef class LocalGenericElement(CommutativeRingElement): sage: x = Zp(3, 5).zero() sage: x._test_expansion() - """ tester = self._tester(**options) diff --git a/src/sage/rings/padics/misc.py b/src/sage/rings/padics/misc.py index dfe0feee162..00720ba8bbb 100644 --- a/src/sage/rings/padics/misc.py +++ b/src/sage/rings/padics/misc.py @@ -68,11 +68,11 @@ def gauss_sum(a, p, f, prec=20, factored=False, algorithm='pari', parent=None): - ``f`` -- positive integer - - ``prec`` -- positive integer (optional, 20 by default) + - ``prec`` -- positive integer (default: 20) - - ``factored`` -- boolean (optional, ``False`` by default) + - ``factored`` -- boolean (default: ``False``) - - ``algorithm`` -- flag passed to p-adic Gamma function (optional, ``"pari"`` by default) + - ``algorithm`` -- flag passed to `p`-adic Gamma function (default: ``'pari'``) OUTPUT: @@ -186,7 +186,7 @@ def max(*L): def precprint(prec_type, prec_cap, p): """ - String describing the precision mode on a p-adic ring or field. + String describing the precision mode on a `p`-adic ring or field. EXAMPLES:: diff --git a/src/sage/rings/padics/morphism.pyx b/src/sage/rings/padics/morphism.pyx index a9f041e1d70..d4684f9649d 100644 --- a/src/sage/rings/padics/morphism.pyx +++ b/src/sage/rings/padics/morphism.pyx @@ -1,6 +1,6 @@ # sage.doctest: needs sage.libs.ntl """ -Frobenius endomorphisms on p-adic fields +Frobenius endomorphisms on `p`-adic fields """ # **************************************************************************** # Copyright (C) 2013 Xavier Caruso @@ -26,15 +26,15 @@ from sage.rings.padics.padic_generic import pAdicGeneric cdef class FrobeniusEndomorphism_padics(RingHomomorphism): """ - A class implementing Frobenius endomorphisms on p-adic fields. + A class implementing Frobenius endomorphisms on `p`-adic fields. """ def __init__ (self,domain,n=1): """ INPUT: - - ``domain`` -- an unramified p-adic field + - ``domain`` -- an unramified `p`-adic field - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) .. NOTE:: @@ -240,7 +240,7 @@ cdef class FrobeniusEndomorphism_padics(RingHomomorphism): def _composition(self, right): """ - Return self o right. + Return ``self`` o ``right``. EXAMPLES:: @@ -267,7 +267,7 @@ cdef class FrobeniusEndomorphism_padics(RingHomomorphism): def is_injective(self): """ Return ``True`` since any power of the Frobenius endomorphism - over an unramified p-adic field is always injective. + over an unramified `p`-adic field is always injective. EXAMPLES:: @@ -281,7 +281,7 @@ cdef class FrobeniusEndomorphism_padics(RingHomomorphism): def is_surjective(self): """ Return ``True`` since any power of the Frobenius endomorphism - over an unramified p-adic field is always surjective. + over an unramified `p`-adic field is always surjective. EXAMPLES:: @@ -328,7 +328,7 @@ cdef class FrobeniusEndomorphism_padics(RingHomomorphism): cpdef _richcmp_(left, right, int op): """ - Compare ``left`` and ``right`` + Compare ``left`` and ``right``. EXAMPLES:: @@ -338,7 +338,6 @@ cdef class FrobeniusEndomorphism_padics(RingHomomorphism): sage: F == G True - """ if left is right: return rich_to_bool(op, 0) diff --git a/src/sage/rings/padics/padic_ZZ_pX_CA_element.pyx b/src/sage/rings/padics/padic_ZZ_pX_CA_element.pyx index 09062475876..7efcfc5a047 100644 --- a/src/sage/rings/padics/padic_ZZ_pX_CA_element.pyx +++ b/src/sage/rings/padics/padic_ZZ_pX_CA_element.pyx @@ -16,12 +16,12 @@ For the parent class see padic_extension_leaves.pyx. The underlying implementation is through NTL's ``ZZ_pX`` class. Each element contains the following data: -- ``absprec`` (long) -- An integer giving the precision to which this +- ``absprec`` -- long; an integer giving the precision to which this element is defined. This is the power of the uniformizer modulo which the element is well defined. -- ``value`` (``ZZ_pX_c``) -- An ntl ``ZZ_pX`` storing the value. The - variable `x` is the uniformizer in the case of Eisenstein extensions. +- ``value`` -- ``ZZ_pX_c``; an ntl ``ZZ_pX`` storing the value. The + variable `x` is the uniformizer in the case of Eisenstein extensions This ZZ_pX is created with global ntl modulus determined by absprec. Let `a` be absprec and `e` be the ramification index over `\QQ_p` or `\ZZ_p`. Then the modulus is given by @@ -29,15 +29,15 @@ element contains the following data: to mix moduli. ``ZZ_pX_conv_modulus`` gives a semi-safe way to convert between different moduli without having to pass through ZZX. -- ``prime_pow`` (some subclass of ``PowComputer_ZZ_pX``) -- a class, +- ``prime_pow`` -- (some subclass of ``PowComputer_ZZ_pX``) a class, identical among all elements with the same parent, holding common data. - + ``prime_pow.deg`` -- The degree of the extension + + ``prime_pow.deg`` -- the degree of the extension - + ``prime_pow.e`` -- The ramification index + + ``prime_pow.e`` -- the ramification index - + ``prime_pow.f`` -- The inertia degree + + ``prime_pow.f`` -- the inertia degree + ``prime_pow.prec_cap`` -- the unramified precision cap. For Eisenstein extensions this is the smallest power of p that is @@ -64,7 +64,7 @@ element contains the following data: ``prime_pow.restore_top_context`` -- restores the given context. + ``prime_pow.get_modulus``, ``get_modulus_capdiv``, - ``get_top_modulus`` -- Returns a ``ZZ_pX_Modulus_c*`` pointing to + ``get_top_modulus`` -- returns a ``ZZ_pX_Modulus_c*`` pointing to a polynomial modulus defined modulo `p^n` (appropriately divided by ``prime_pow.e`` in the capdiv case). @@ -198,14 +198,15 @@ cdef long maxordp = (1L << (sizeof(long) * 8 - 2)) -1 cdef class pAdicZZpXCAElement(pAdicZZpXElement): def __init__(self, parent, x, absprec = infinity, relprec = infinity, empty = False): """ - Creates an element of a capped absolute precision, unramified or Eisenstein extension of Zp or Qp. + Create an element of a capped absolute precision, unramified or + Eisenstein extension of Zp or Qp. INPUT: - ``parent`` -- either an ``EisensteinRingCappedAbsolute`` or ``UnramifiedRingCappedAbsolute`` - - `x` -- an integer, rational, `p`-adic element, polynomial, + - ``x`` -- integer, rational, `p`-adic element, polynomial, list, integer_mod, pari int/frac/poly_t/pol_mod, an ``ntl_ZZ_pX``, an ``ntl_ZZ``, an ``ntl_ZZ_p``, an ``ntl_ZZX``, or something convertible into parent.residue_field() @@ -216,7 +217,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): - ``relprec`` -- an upper bound on the relative precision of the element created - - ``empty`` -- whether to return after initializing to zero. + - ``empty`` -- whether to return after initializing to zero EXAMPLES:: @@ -259,7 +260,6 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): sage: W. = R.extension(a^2 + 1) sage: W(W.residue_field().zero()) O(3) - """ pAdicZZpXElement.__init__(self, parent) cdef long aprec, rprec, ctx_prec @@ -439,7 +439,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_inexact_zero(self, long absprec) except -1: """ - Sets ``self`` to be zero with valuation ``absprec``. + Set ``self`` to be zero with valuation ``absprec``. EXAMPLES:: @@ -463,7 +463,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef bint _is_inexact_zero(self) except -1: """ - Tests if ``self`` is an inexact zero. + Test if ``self`` is an inexact zero. EXAMPLES:: @@ -482,7 +482,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set(self, ZZ_pX_c* value, long absprec) except -1: """ - Sets ``value`` and ``absprec`` directly. + Set ``value`` and ``absprec`` directly. EXAMPLES:: @@ -504,7 +504,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_mpz_abs(self, mpz_t x, long absprec) except -1: """ - Sets ``self`` from an ``mpz_t`` with absolute precision + Set ``self`` from an ``mpz_t`` with absolute precision bounded by ``absprec``. EXAMPLES:: @@ -531,7 +531,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_mpz_both(self, mpz_t x, long absprec, long relprec) except -1: """ - Sets ``self`` from an ``mpz_t`` with relative precision + Set ``self`` from an ``mpz_t`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. @@ -567,7 +567,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_mpq_abs(self, mpq_t x, long absprec) except -1: """ - Sets ``self`` from an ``mpq_t`` with absolute precision bounded by + Set ``self`` from an ``mpq_t`` with absolute precision bounded by ``absprec``. EXAMPLES:: @@ -597,7 +597,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_mpq_both(self, mpq_t x, long absprec, long relprec) except -1: """ - Sets ``self`` from an ``mpq_t`` with relative precision bounded by + Set ``self`` from an ``mpq_t`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. EXAMPLES:: @@ -658,7 +658,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_ZZX_abs(self, ZZX_c poly, long absprec) except -1: """ - Sets ``self`` from a ``ZZX`` with absolute precision bounded by + Set ``self`` from a ``ZZX`` with absolute precision bounded by ``absprec``. EXAMPLES:: @@ -706,7 +706,8 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_ZZ_pX_abs(self, ZZ_pX_c* poly, ntl_ZZ_pContext_class ctx, long absprec) except -1: """ - Sets ``self`` from a ``ZZ_pX`` with absolute precision bounded by ``absprec`` (and by ``ctx``). + Set ``self`` from a ``ZZ_pX`` with absolute precision bounded by + ``absprec`` (and by ``ctx``). EXAMPLES:: @@ -735,7 +736,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef int _set_from_ZZ_pX_both(self, ZZ_pX_c* poly, ntl_ZZ_pContext_class ctx, long absprec, long relprec) except -1: """ - Sets ``self`` from a ``ZZ_pX`` with relative precision bounded by + Set ``self`` from a ``ZZ_pX`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. EXAMPLES:: @@ -770,7 +771,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef bint _set_prec_abs(self, long absprec) except -1: """ - Safely sets the absolute precision of self to ``absprec``. + Safely set the absolute precision of ``self`` to ``absprec``. Returns ``True`` iff ``self.absprec`` was reset. @@ -800,7 +801,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): 4*w^5 + 3*w^7 + w^9 + 2*w^10 + 2*w^11 + O(w^13) """ if absprec < 0: - raise ValueError("absprec must be non-negative") + raise ValueError("absprec must be nonnegative") if self.absprec == absprec: return False if absprec > 0: @@ -814,7 +815,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef bint _set_prec_both_with_ordp(self, long ordp, long absprec, long relprec) except -1: """ - Sets the absolute precision of ``self`` to the minimum of ``absprec`` + Set the absolute precision of ``self`` to the minimum of ``absprec`` and ``ordp + relprec``. Note that this will wipe out anything in ``self.value``. Be @@ -847,7 +848,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef pAdicZZpXCAElement _new_c(self, long absprec): """ - Returns a new element with the same parent as ``self`` and + Return a new element with the same parent as ``self`` and absolute precision ``absprec``. EXAMPLES:: @@ -924,7 +925,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def __invert__(self): """ - Returns the inverse of ``self``. + Return the inverse of ``self``. EXAMPLES:: @@ -945,7 +946,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef pAdicZZpXCRElement to_fraction_field(self): """ - Returns ``self`` cast into the fraction field of ``self.parent()``. + Return ``self`` cast into the fraction field of ``self.parent()``. EXAMPLES:: @@ -972,7 +973,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef pAdicZZpXCAElement _lshift_c(self, long n): """ - Multiplies ``self`` by the uniformizer raised to the power ``n``. If + Multiply ``self`` by the uniformizer raised to the power ``n``. If ``n`` is negative, right shifts by ``-n``. EXAMPLES:: @@ -993,7 +994,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def __lshift__(pAdicZZpXCAElement self, shift): """ - Multiplies ``self`` by the uniformizer raised to the power ``n``. If + Multiply ``self`` by the uniformizer raised to the power ``n``. If ``n`` is negative, right shifts by ``-n``. EXAMPLES:: @@ -1023,8 +1024,8 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef pAdicZZpXCAElement _rshift_c(self, long n): """ - Divides ``self`` by the uniformizer raised to the power ``n``. If - parent is not a field, throws away the non-positive part of + Divide ``self`` by the uniformizer raised to the power ``n``. If + parent is not a field, throws away the nonpositive part of the series expansion. If ``n`` is negative, left shifts by ``-n``. EXAMPLES:: @@ -1090,8 +1091,8 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def __rshift__(pAdicZZpXCAElement self, shift): """ - Divides ``self`` by the uniformizer raised to the power ``n``. If - parent is not a field, throws away the non-positive part of + Divide ``self`` by the uniformizer raised to the power ``n``. If + parent is not a field, throws away the nonpositive part of the series expansion. If ``n`` is negative, left shifts by ``-n``. EXAMPLES:: @@ -1121,7 +1122,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef _neg_(self): """ - Returns ``-self``. + Return ``-self``. EXAMPLES:: @@ -1150,7 +1151,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def __pow__(pAdicZZpXCAElement self, _right, m): # m ignored r""" - Computes ``self^right``. + Compute ``self^right``. Note: when right is divisible by `p` then one can get more precision than expected. @@ -1177,7 +1178,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): So if right is divisible by `p^k` we can multiply the relative precision by `p` until we exceed `e/(p-1)`, then add `e` until we have done a total of `k` things: the precision of the - result can therefore be greater than the precision of self. + result can therefore be greater than the precision of ``self``. There is also the issue of `p`-adic exponents, and determining how the precision of the exponent affects the precision of the @@ -1387,7 +1388,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef _add_(self, _right): """ - Computes the sum of ``self`` and ``right``. + Compute the sum of ``self`` and ``right``. EXAMPLES:: @@ -1425,7 +1426,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef _sub_(self, _right): """ - Returns the difference of ``self`` and ``right``. + Return the difference of ``self`` and ``right``. EXAMPLES:: @@ -1466,7 +1467,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef _mul_(self, _right): """ - Returns the product of ``self`` and ``right``. + Return the product of ``self`` and ``right``. EXAMPLES:: @@ -1519,7 +1520,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef _div_(self, right): """ - Returns the quotient of ``self`` by ``right``. + Return the quotient of ``self`` by ``right``. EXAMPLES:: @@ -1548,7 +1549,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def _integer_(self, Z=None): r""" - Returns an integer congruent to this element modulo + Return an integer congruent to this element modulo `\pi`^``self.absolute_precision()``, if possible. EXAMPLES:: @@ -1581,7 +1582,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def __copy__(self): """ - Returns a copy of ``self``. + Return a copy of ``self``. EXAMPLES:: @@ -1608,7 +1609,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): from zero. If ``self`` is an inexact zero of valuation less than ``absprec``, - raises a ``PrecisionError``. + raises a :exc:`PrecisionError`. EXAMPLES:: @@ -1754,7 +1755,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef ZZ_p_c _const_term(self) noexcept: """ - Returns the constant term of ``self.value``. + Return the constant term of ``self.value``. EXAMPLES:: @@ -1770,7 +1771,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def is_equal_to(self, right, absprec = None): """ - Returns whether ``self`` is equal to ``right`` modulo + Return whether ``self`` is equal to ``right`` modulo ``self.uniformizer()^absprec``. If ``absprec`` is ``None``, returns if ``self`` is equal to ``right`` modulo @@ -1793,12 +1794,12 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef pAdicZZpXCAElement lift_to_precision(self, absprec=None): """ - Returns a ``pAdicZZpXCAElement`` congruent to ``self`` but with + Return a ``pAdicZZpXCAElement`` congruent to ``self`` but with absolute precision at least ``absprec``. INPUT: - - ``absprec`` -- (default ``None``) the absolute precision of + - ``absprec`` -- (default: ``None``) the absolute precision of the result. If ``None``, lifts to the maximum precision allowed. @@ -1876,8 +1877,8 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): INPUT: - - ``n`` -- integer (default ``None``). If given, returns the - corresponding entry in the expansion. + - ``n`` -- integer (default: ``None``); if given, returns the + corresponding entry in the expansion EXAMPLES:: @@ -2009,15 +2010,15 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): # INPUT: -# - base -- field or morphism +# - ``base`` -- field or morphism # """ # raise NotImplementedError # def multiplicative_order(self, prec=None): # """ -# Returns the multiplicative order of self, ie the smallest -# positive n so that there is an exact p-adic element congruent -# to self modulo self's precision that is an nth root of unity. +# Returns the multiplicative order of ``self``, ie the smallest +# positive `n` so that there is an exact `p`-adic element congruent +# to ``self`` modulo ``self``'s precision that is an `n`-th root of unity. # Note: unlike the case for Qp and Zp, it is possible to have # non-teichmuller elements with finite orders. This can happen @@ -2026,18 +2027,16 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): # INPUT: -# - self -- a p-adic element -# - prec -- an integer - -# OUTPUT: +# - self -- a `p`-adic element +# - ``prec`` -- integer -# - integer -- the multiplicative order of self +# OUTPUT: integer; the multiplicative order of self # """ # raise NotImplementedError def teichmuller_expansion(self, n = None): r""" - Returns a list [`a_0`, `a_1`,..., `a_n`] such that + Return a list [`a_0`, `a_1`,..., `a_n`] such that: - `a_i^q = a_i` - ``self.unit_part()`` = `\sum_{i = 0}^n a_i \pi^i`, where `\pi` is a @@ -2047,8 +2046,8 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): INPUT: - - ``n`` -- integer (default ``None``). If given, returns the corresponding - entry in the expansion. + - ``n`` -- integer (default: ``None``); if given, returns the + corresponding entry in the expansion EXAMPLES:: @@ -2123,7 +2122,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def _teichmuller_set_unsafe(self): """ - Sets this element to the Teichmuller representative with the + Set this element to the Teichmuller representative with the same residue. .. WARNING:: @@ -2157,7 +2156,6 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): sage: R. = ZpCA(2).extension(x^2 - 2) sage: R.teichmuller(a) O(a^40) - """ if self.absprec == 0: raise ValueError("not enough precision known") @@ -2176,7 +2174,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def precision_absolute(self): """ - Returns the absolute precision of ``self``, ie the power of the + Return the absolute precision of ``self``, ie the power of the uniformizer modulo which this element is defined. EXAMPLES:: @@ -2202,7 +2200,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): def precision_relative(self): """ - Returns the relative precision of ``self``, ie the power of + Return the relative precision of ``self``, ie the power of the uniformizer modulo which the unit part of ``self`` is defined. @@ -2235,7 +2233,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef long valuation_c(self) noexcept: """ - Returns the valuation of ``self``. + Return the valuation of ``self``. EXAMPLES:: @@ -2272,7 +2270,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cpdef pAdicZZpXCAElement unit_part(self): """ - Returns the unit part of ``self``, ie ``self / uniformizer^(self.valuation())`` + Return the unit part of ``self``, ie ``self / uniformizer^(self.valuation())``. EXAMPLES:: @@ -2295,7 +2293,7 @@ cdef class pAdicZZpXCAElement(pAdicZZpXElement): cdef ext_p_list(self, bint pos): """ - Returns a list of integers (in the Eisenstein case) or a list + Return a list of integers (in the Eisenstein case) or a list of lists of integers (in the unramified case). ``self`` can be reconstructed as a sum of elements of the list times powers of the uniformizer (in the Eisenstein case), or as a sum of diff --git a/src/sage/rings/padics/padic_ZZ_pX_CR_element.pyx b/src/sage/rings/padics/padic_ZZ_pX_CR_element.pyx index 8463d40ce26..82d04980363 100644 --- a/src/sage/rings/padics/padic_ZZ_pX_CR_element.pyx +++ b/src/sage/rings/padics/padic_ZZ_pX_CR_element.pyx @@ -16,12 +16,12 @@ For the parent class see :mod:`sage.rings.padics.padic_extension_leaves`. The underlying implementation is through NTL's ``ZZ_pX`` class. Each element contains the following data: -- ``ordp`` (``long``) -- A power of the uniformizer to scale the unit +- ``ordp`` -- ``long``; a power of the uniformizer to scale the unit by. For unramified extensions this uniformizer is `p`, for Eisenstein extensions it is not. A value equal to the maximum value of a ``long`` indicates that the element is an exact zero. -- ``relprec`` (``long``) -- A signed integer giving the precision to +- ``relprec`` -- ``long``; a signed integer giving the precision to which this element is defined. For nonzero ``relprec``, the absolute value gives the power of the uniformizer modulo which the unit is defined. A positive value indicates that the element is @@ -34,7 +34,7 @@ element contains the following data: ``ordp`` gives the absolute precision of the element. If ``ordp`` is greater than ``maxordp``, then the element is an exact zero. -- ``unit`` (``ZZ_pX_c``) -- An ntl ``ZZ_pX`` storing the unit part. +- ``unit`` -- ``ZZ_pX_c``; an ntl ``ZZ_pX`` storing the unit part The variable `x` is the uniformizer in the case of Eisenstein extensions. If the element is not normalized, the ``unit`` may or may not actually be a unit. This ``ZZ_pX`` is created with global @@ -51,11 +51,11 @@ element contains the following data: identical among all elements with the same parent, holding common data. - + ``prime_pow.deg`` -- The degree of the extension + + ``prime_pow.deg`` -- the degree of the extension - + ``prime_pow.e`` -- The ramification index + + ``prime_pow.e`` -- the ramification index - + ``prime_pow.f`` -- The inertia degree + + ``prime_pow.f`` -- the inertia degree + ``prime_pow.prec_cap`` -- the unramified precision cap. For Eisenstein extensions this is the smallest power of `p` that is @@ -82,7 +82,7 @@ element contains the following data: ``prime_pow.restore_top_context`` -- restores the given context. + ``prime_pow.get_modulus``, ``get_modulus_capdiv``, - ``get_top_modulus`` -- Returns a ``ZZ_pX_Modulus_c*`` pointing to + ``get_top_modulus`` -- returns a ``ZZ_pX_Modulus_c*`` pointing to a polynomial modulus defined modulo `p^n` (appropriately divided by ``prime_pow.e`` in the capdiv case). @@ -225,7 +225,7 @@ cdef inline int check_ordp(long a) except -1: cdef class pAdicZZpXCRElement(pAdicZZpXElement): def __init__(self, parent, x, absprec = infinity, relprec = infinity, empty = False): r""" - Creates an element of a capped relative precision, unramified + Create an element of a capped relative precision, unramified or Eisenstein extension of `\ZZ_p` or `\QQ_p`. INPUT: @@ -233,7 +233,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): - ``parent`` -- either an ``EisensteinRingCappedRelative`` or ``UnramifiedRingCappedRelative`` - - ``x`` -- an integer, rational, `p`-adic element, polynomial, + - ``x`` -- integer; rational, `p`-adic element, polynomial, list, integer_mod, pari int/frac/poly_t/pol_mod, an ``ntl_ZZ_pX``, an ``ntl_ZZ``, an ``ntl_ZZ_p``, an ``ntl_ZZX``, or something convertible into parent.residue_field() @@ -245,7 +245,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): the element created - ``empty`` -- whether to return after initializing to zero - (without setting the valuation). + (without setting the valuation) EXAMPLES:: @@ -286,7 +286,6 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): sage: L. = K.extension(a^2 + 1) sage: L(L.residue_field().zero()) O(3) - """ pAdicZZpXElement.__init__(self, parent) self.relprec = 0 @@ -533,7 +532,6 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): (..., 0) sage: K(0,1)._cache_key() (..., 1, 0) - """ if self._is_exact_zero(): return (self.parent(), 0) @@ -547,7 +545,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_inexact_zero(self, long absprec) except -1: """ - Sets ``self`` to be zero with valuation absprec. + Set ``self`` to be zero with valuation absprec. EXAMPLES:: @@ -583,7 +581,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_exact_zero(self) except -1: """ - Sets ``self`` to be an exact zero. + Set ``self`` to be an exact zero. EXAMPLES:: @@ -619,7 +617,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef bint _is_exact_zero(self) except -1: """ - Tests if ``self`` is an exact zero. + Test if ``self`` is an exact zero. EXAMPLES:: @@ -645,7 +643,6 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): sage: z = W(0,6) sage: z._is_exact_zero() False - """ if self.ordp == maxordp: return 1 @@ -654,7 +651,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef bint _is_inexact_zero(self) except -1: """ - Tests if ``self`` is an inexact zero. + Test if ``self`` is an inexact zero. EXAMPLES:: @@ -689,7 +686,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set(self, ZZ_pX_c* unit, long ordp, long relprec) except -1: """ - Sets ``unit``, ``ordp`` and ``relprec`` directly. + Set ``unit``, ``ordp`` and ``relprec`` directly. EXAMPLES:: @@ -815,7 +812,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_mpq_rel(self, mpq_t x, long relprec) except -1: """ - Sets ``self`` from an ``mpq_t`` with relative precision + Set ``self`` from an ``mpq_t`` with relative precision bounded by ``relprec``. EXAMPLES:: @@ -876,7 +873,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_mpq_both(self, mpq_t x, long absprec, long relprec) except -1: """ - Sets ``self`` from an ``mpq_t`` with relative precision + Set ``self`` from an ``mpq_t`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. @@ -914,7 +911,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_mpq_part1(self, mpz_t num_unit, mpz_t den_unit, mpq_t x) except -1: """ - Sets ``num_unit`` to be the unit of the numerator, ``den_unit`` to be the unit of the denominator and sets ``self.ordp`` correctly. + Set ``num_unit`` to be the unit of the numerator, ``den_unit`` to be + the unit of the denominator and sets ``self.ordp`` correctly. TESTS:: @@ -973,7 +971,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_ZZX_rel(self, ZZX_c poly, long relprec) except -1: """ - Sets ``self`` from a ``ZZX`` with relative precision bounded by + Set ``self`` from a ``ZZX`` with relative precision bounded by ``relprec``. EXAMPLES:: @@ -1011,7 +1009,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_ZZX_both(self, ZZX_c poly, long absprec, long relprec) except -1: """ - Sets ``self`` from a ``ZZX`` with relative precision bounded by + Set ``self`` from a ``ZZX`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. EXAMPLES:: @@ -1045,8 +1043,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_ZZX_part1(self, ZZX_c poly, long absprec, long relprec) except -1: """ - Sets ``self.ordp`` from ``poly`` and restores the context. ``poly`` must - have degree less than ``self.prime_pow.deg`` + Set ``self.ordp`` from ``poly`` and restores the context. ``poly`` must + have degree less than ``self.prime_pow.deg``. TESTS:: @@ -1088,11 +1086,11 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_ZZ_pX_rel(self, ZZ_pX_c* poly, ntl_ZZ_pContext_class ctx, long relprec) except -1: """ - Sets ``self`` from a ``ZZ_pX`` with relative precision bounded by + Set ``self`` from a ``ZZ_pX`` with relative precision bounded by ``relprec``. - If ``ctx`` is ``None`` and ``poly`` is 0 this function will raise an error - (a ``ZZ_pX`` cannot represent something with infinite absolute + If ``ctx`` is ``None`` and ``poly`` is 0 this function will raise an + error (a ``ZZ_pX`` cannot represent something with infinite absolute precision). EXAMPLES:: @@ -1131,7 +1129,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_ZZ_pX_both(self, ZZ_pX_c* poly, ntl_ZZ_pContext_class ctx, long absprec, long relprec) except -1: """ - Sets ``self`` from a ``ZZ_pX`` with relative precision bounded by + Set ``self`` from a ``ZZ_pX`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. EXAMPLES:: @@ -1166,7 +1164,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _set_from_ZZ_pX_part1(self, ZZ_pX_c* poly) except -1: """ - Sets ``self.ordp`` based on ``poly``. ``poly`` must not be 0. + Set ``self.ordp`` based on ``poly``. ``poly`` must not be 0. TESTS:: @@ -1206,7 +1204,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef bint _set_prec_rel(self, long relprec) except -1: """ - Safely sets the relative precision of ``self`` to be the absolute + Safely set the relative precision of ``self`` to be the absolute value of ``relprec``. Returns ``True`` iff ``self.relprec`` was reset. @@ -1296,7 +1294,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _normalize(self) except -1: """ - Normalizes ``self``, adjusting ``self.ordp``, ``self.relprec``, and + Normalize ``self``, adjusting ``self.ordp``, ``self.relprec``, and ``self.unit`` so that ``self.unit`` actually represents a unit. EXAMPLES:: @@ -1353,7 +1351,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _internal_lshift(self, long shift) except -1: """ - Multiplies ``self.unit`` by ``x^shift``. + Multiply ``self.unit`` by ``x^shift``. Note that ``self.relprec`` must be set before calling this function and should not be 0, and self.unit must be defined to @@ -1397,7 +1395,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef int _pshift_self(self, long shift) except -1: """ - Multiplies ``self`` by ``p^shift``. + Multiply ``self`` by ``p^shift``. This function assumes that ``self.relprec``, ``self.ordp`` and ``self.unit`` are already set (in the case ``self.prime_pow.e @@ -1473,7 +1471,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): Return a new element with the same parent as ``self`` and relative precision ``relprec`` - Note that if ``relprec`` is non-positive, the convention is that + Note that if ``relprec`` is nonpositive, the convention is that ``relprec = 0`` indicates an exact or inexact zero, ``relprec < 0`` indicates an unnormalized element. @@ -1557,7 +1555,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): def __invert__(self): """ - Return the inverse of this element + Return the inverse of this element. EXAMPLES:: @@ -1595,7 +1593,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef pAdicZZpXCRElement _lshift_c(self, long n): """ - Multiplies ``self`` by the uniformizer raised to the power ``n``. If + Multiply ``self`` by the uniformizer raised to the power ``n``. If ``n`` is negative, right shifts by ``-n``. EXAMPLES:: @@ -1629,7 +1627,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): def __lshift__(pAdicZZpXCRElement self, shift): """ - Multiplies ``self`` by the uniformizer raised to the power ``n``. If + Multiply ``self`` by the uniformizer raised to the power ``n``. If ``n`` is negative, right shifts by ``-n``. EXAMPLES:: @@ -1662,8 +1660,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cdef pAdicZZpXCRElement _rshift_c(self, long n): """ - Divides self by the uniformizer raised to the power ``n``. If - parent is not a field, throws away the non-positive part of + Divide ``self`` by the uniformizer raised to the power ``n``. If + parent is not a field, throws away the nonpositive part of the series expansion. If ``n`` is negative, left shifts by ``-n``. EXAMPLES:: @@ -1727,8 +1725,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): def __rshift__(pAdicZZpXCRElement self, shift): """ - Divides self by the uniformizer raised to the power ``n``. If - parent is not a field, throws away the non-positive part of + Divide ``self`` by the uniformizer raised to the power ``n``. If + parent is not a field, throws away the nonpositive part of the series expansion. If ``n`` is negative, left shifts by ``-n``. EXAMPLES:: @@ -1765,7 +1763,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef _neg_(self): """ - Negation + Negation. EXAMPLES:: @@ -1797,7 +1795,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): def __pow__(pAdicZZpXCRElement self, _right, m): # m ignored r""" - Computes ``self^right``. + Compute ``self^right``. Note: when ``right`` is divisible by `p` then one can get more precision than expected. @@ -1908,7 +1906,6 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): sage: W. = R.ext(f) sage: type(W(0)^0) == type(W(0)) True - """ self._normalize() cdef Integer right @@ -2161,7 +2158,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef _sub_(self, right): """ - Return the difference of two elements + Return the difference of two elements. EXAMPLES:: @@ -2187,7 +2184,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef _mul_(self, _right): """ - Return the product of two elements + Return the product of two elements. EXAMPLES:: @@ -2240,7 +2237,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef _div_(self, right): """ - Return the quotient of two elements + Return the quotient of two elements. EXAMPLES:: @@ -2270,7 +2267,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): def __copy__(self): """ - Return a copy of this element + Return a copy of this element. EXAMPLES:: @@ -2337,7 +2334,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): is indistinguishable from zero. If this element is an inexact zero of valuation less than ``absprec``, - raises a :class:`PrecisionError`. + raises a :exc:`PrecisionError`. EXAMPLES:: @@ -2384,7 +2381,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef ntl_ZZ_pX _ntl_rep_unnormalized(self): """ - Return an ``ntl_ZZ_pX`` holding the current unit part of this element + Return an ``ntl_ZZ_pX`` holding the current unit part of this element. The element is not normalized before this operation, so the polynomial returned may not actually be a unit. @@ -2413,7 +2410,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef ntl_ZZ_pX _ntl_rep(self): """ - Return an ``ntl_ZZ_pX`` that holds the unit part of this element + Return an ``ntl_ZZ_pX`` that holds the unit part of this element. EXAMPLES:: @@ -2435,7 +2432,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): cpdef _ntl_rep_abs(self): """ Return a pair ``(f, k)`` where ``f`` is an ``ntl_ZZ_pX`` and ``k`` is a - non-positive integer such that ``self = f(self.parent.gen())*p^k`` + nonpositive integer such that ``self = f(self.parent.gen())*p^k``. EXAMPLES:: @@ -2612,7 +2609,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): # def lift(self): # """ -# Return an element of a number field defined by the same polynomial as self's parent that is congruent to self modulo an appropriate ideal. +# Return an element of a number field defined by the same polynomial as +# ``self``'s parent that is congruent to self modulo an appropriate ideal. # Not currently implemented. # """ @@ -2625,14 +2623,14 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): INPUT: - - ``absprec`` -- (default ``None``) the absolute precision of + - ``absprec`` -- (default: ``None``) the absolute precision of the result. If ``None``, lifts to the maximum precision allowed. .. NOTE:: If setting ``absprec`` that high would violate the - precision cap, raises a precision error. If self is an + precision cap, raises a precision error. If ``self`` is an inexact zero and ``absprec`` is greater than the maximum allowed valuation, raises an error. @@ -2734,8 +2732,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): INPUT: - - ``n`` -- integer (default ``None``). If given, returns the corresponding - entry in the expansion. + - ``n`` -- integer (default: ``None``); if given, returns the + corresponding entry in the expansion EXAMPLES:: @@ -2782,7 +2780,6 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): sage: w = u - v^2 sage: w.expansion(4) 0 - """ self._normalize() if lift_mode == 'teichmuller': @@ -2857,7 +2854,6 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): [0 0 0 0 0] [0 0 0 0 0] [0 0 0 0 0] - """ if self.valuation_c() < 0: raise ValueError("self must be integral") @@ -2901,9 +2897,9 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): # def multiplicative_order(self, prec=None): # """ -# Return the multiplicative order of self, ie the smallest -# positive n so that there is an exact p-adic element congruent -# to self modulo self's precision that is an nth root of unity. +# Return the multiplicative order of ``self``, ie the smallest +# positive `n` so that there is an exact `p`-adic element congruent +# to ``self`` modulo ``self``'s precision that is an `n`-th root of unity. # Note: unlike the case for Qp and Zp, it is possible to have # non-teichmuller elements with finite orders. This can happen @@ -2912,18 +2908,16 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): # INPUT: -# - self -- a p-adic element -# - prec -- an integer - -# OUTPUT: +# - self -- a `p`-adic element +# - ``prec`` -- integer -# - integer -- the multiplicative order of self +# OUTPUT: integer; the multiplicative order of ``self`` # """ # raise NotImplementedError def teichmuller_expansion(self, n = None): r""" - Return a list [`a_0`, `a_1`,..., `a_n`] such that + Return a list [`a_0`, `a_1`,..., `a_n`] such that: - `a_i^q = a_i` - ``self.unit_part()`` = `\sum_{i = 0}^n a_i \pi^i`, where `\pi` is a @@ -2933,8 +2927,8 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): INPUT: - - ``n`` -- integer (default ``None``). If given, returns the corresponding - entry in the expansion. + - ``n`` -- integer (default: ``None``); if given, returns the + corresponding entry in the expansion EXAMPLES:: @@ -3020,7 +3014,7 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement): def _teichmuller_set_unsafe(self): """ - Sets this element to the Teichmuller representative with the + Set this element to the Teichmuller representative with the same residue. .. WARNING:: diff --git a/src/sage/rings/padics/padic_ZZ_pX_FM_element.pyx b/src/sage/rings/padics/padic_ZZ_pX_FM_element.pyx index f85c6b7f3b4..a3dcd42b3d6 100644 --- a/src/sage/rings/padics/padic_ZZ_pX_FM_element.pyx +++ b/src/sage/rings/padics/padic_ZZ_pX_FM_element.pyx @@ -16,7 +16,7 @@ For the parent class see ``padic_extension_leaves.pyx``. The underlying implementation is through NTL's ``ZZ_pX`` class. Each element contains the following data: -- ``value`` (``ZZ_pX_c``) -- An ntl ``ZZ_pX`` storing the value. The +- ``value`` (``ZZ_pX_c``) -- an ntl ``ZZ_pX`` storing the value. The variable `x` is the uniformizer in the case of Eisenstein extensions. This ``ZZ_pX`` is created with global ntl modulus determined by the parent's precision cap and shared among all elements. @@ -27,9 +27,9 @@ element contains the following data: * ``prime_pow.deg`` -- the degree of the extension - * ``prime_pow.e`` -- the ramification index + * ``prime_pow.e`` -- the ramification index - * ``prime_pow.f`` -- the inertia degree + * ``prime_pow.f`` -- the inertia degree * ``prime_pow.prec_cap`` -- the unramified precision cap: for Eisenstein extensions this is the smallest power of `p` that is @@ -56,7 +56,7 @@ element contains the following data: ``prime_pow.restore_top_context`` -- restores the given context * ``prime_pow.get_modulus``, ``get_modulus_capdiv``, - ``get_top_modulus`` -- Returns a ``ZZ_pX_Modulus_c*`` pointing to + ``get_top_modulus`` -- returns a ``ZZ_pX_Modulus_c*`` pointing to a polynomial modulus defined modulo `p^n` (appropriately divided by ``prime_pow.e`` in the capdiv case). @@ -152,7 +152,7 @@ from sage.rings.finite_rings.integer_mod_ring import IntegerModRing cdef class pAdicZZpXFMElement(pAdicZZpXElement): def __init__(self, parent, x, absprec=None, relprec=None, empty=False): r""" - Creates an element of a fixed modulus, unramified or + Create an element of a fixed modulus, unramified or eisenstein extension of `\ZZ_p` or `\QQ_p`. INPUT: @@ -160,7 +160,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): - ``parent`` -- either an ``EisensteinRingFixedMod`` or ``UnramifiedRingFixedMod`` - - ``x`` -- an integer, rational, `p`-adic element, polynomial, + - ``x`` -- integer, rational, `p`-adic element, polynomial, list, integer_mod, pari int/frac/poly_t/pol_mod, an ``ntl_ZZ_pX``, an ``ntl_ZZX``, an ``ntl_ZZ``, or an ``ntl_ZZ_p`` @@ -196,7 +196,6 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): sage: W. = R.extension(a^2 + 1) sage: W(W.residue_field().zero()) 0 - """ pAdicZZpXElement.__init__(self, parent) if empty: @@ -283,7 +282,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cdef int _set_from_mpz(self, mpz_t x) except -1: """ - Sets ``self`` from an ``mpz_t``. + Set ``self`` from an ``mpz_t``. EXAMPLES:: @@ -307,7 +306,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cdef int _set_from_mpq(self, mpq_t x) except -1: """ - Sets ``self`` from an ``mpq_t``. + Set ``self`` from an ``mpq_t``. EXAMPLES:: @@ -341,7 +340,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cdef int _set_from_ZZ_pX(self, ZZ_pX_c* poly, ntl_ZZ_pContext_class ctx) except -1: """ - Sets ``self`` from a ``ZZ_pX_c``. + Set ``self`` from a ``ZZ_pX_c``. EXAMPLES:: @@ -361,7 +360,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cdef int _set_from_ZZX(self, ZZX_c poly) except -1: """ - Sets ``self`` from a ``ZZX`` with relative precision bounded + Set ``self`` from a ``ZZX`` with relative precision bounded by ``relprec`` and absolute precision bounded by ``absprec``. EXAMPLES:: @@ -381,7 +380,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cpdef bint _is_inexact_zero(self) except -1: """ - Tests if ``self`` is an inexact zero. + Test if ``self`` is an inexact zero. EXAMPLES:: @@ -477,7 +476,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): """ Return the inverse of ``self``, as long as ``self`` is a unit. - If ``self`` is not a unit, raises a ``ValueError``. + If ``self`` is not a unit, raises a :exc:`ValueError`. EXAMPLES:: @@ -573,7 +572,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): """ Divide ``self`` by the uniformizer raised to the power ``n``. - Throws away the non-positive part of the series expansion. + Throws away the nonpositive part of the series expansion. The top digits will be garbage. If ``n`` is negative, left shifts by ``-n``. @@ -631,7 +630,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): """ Divide ``self`` by the uniformizer raised to the power ``n``. - Throws away the non-positive part of the series expansion. + Throws away the nonpositive part of the series expansion. The top digits will be garbage. If ``n`` is negative, left shifts by ``-n``. @@ -662,7 +661,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cpdef _neg_(self): """ - Returns ``-self``. + Return ``-self``. EXAMPLES:: @@ -687,7 +686,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): def __pow__(pAdicZZpXFMElement self, right, m): # m ignored """ - Computes ``self`` ^ ``right``. + Compute ``self`` ^ ``right``. EXAMPLES:: @@ -725,7 +724,6 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): sage: W. = R.ext(f) sage: type(W(0)^0) == type(W(0)) True - """ if not isinstance(right, Integer): right = Integer(right) @@ -819,9 +817,9 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): cpdef _div_(self, _right): """ - Returns the quotient of ``self`` by ``right``. + Return the quotient of ``self`` by ``right``. - If ``right`` is not a unit, raises a ``ValueError``. + If ``right`` is not a unit, raises a :exc:`ValueError`. EXAMPLES:: @@ -843,7 +841,6 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): sage: R. = Zq(8,2,'fixed-mod') sage: 1/(t+t^2) (t + 1) + t^2*2 - """ cdef pAdicZZpXFMElement right = _right if right.valuation_c() > 0: @@ -930,11 +927,9 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): INPUT: - - ``absprec`` -- an integer + - ``absprec`` -- integer - OUTPUT: - - A new element truncated modulo `\pi^{\mbox{absprec}}`. + OUTPUT: a new element truncated modulo `\pi^{\mbox{absprec}}` EXAMPLES:: @@ -1255,7 +1250,8 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): # def lift(self): # """ -# Returns an element of a number field defined by the same polynomial as self's parent that is congruent to self modulo an appropriate ideal. +# Returns an element of a number field defined by the same polynomial as +# ``self``'s parent that is congruent to self modulo an appropriate ideal. # Not currently implemented. # """ @@ -1308,7 +1304,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): INPUT: - - ``n`` -- integer (default ``None``); if given, returns the + - ``n`` -- integer (default: ``None``); if given, returns the corresponding entry in the expansion EXAMPLES:: @@ -1351,7 +1347,6 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): sage: L. = K.extension(a^2 - 3) sage: a.residue() 0 - """ if lift_mode == 'teichmuller': zero = self.parent()(0) @@ -1387,7 +1382,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): def teichmuller_expansion(self, n = None): r""" - Return a list `[a_0, a_1, \ldots, a_n]` such that + Return a list `[a_0, a_1, \ldots, a_n]` such that. - `a_i^q = a_i` - ``self.unit_part()`` = `\sum_{i = 0}^n a_i \pi^i`, where `\pi` is a @@ -1395,7 +1390,7 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): INPUT: - - ``n`` -- integer (default ``None``); f given, returns the corresponding + - ``n`` -- integer (default: ``None``); if given, returns the corresponding entry in the expansion EXAMPLES:: @@ -1520,8 +1515,8 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): # def multiplicative_order(self): # """ # Returns the multiplicative order of self, ie the smallest -# positive n so that there is an exact p-adic element congruent -# to self modulo self's precision that is an nth root of unity. +# positive `n` so that there is an exact `p`-adic element congruent +# to self modulo ``self``'s precision that is an `n`-th root of unity. # Note: unlike the case for Qp and Zp, it is possible to have # non-teichmuller elements with finite orders. This can happen @@ -1530,12 +1525,10 @@ cdef class pAdicZZpXFMElement(pAdicZZpXElement): # INPUT: -# - self -- a p-adic element -# - prec -- an integer - -# OUTPUT: +# - ``self`` -- a `p`-adic element +# - ``prec`` -- integer -# - integer -- the multiplicative order of self +# OUTPUT: integer; the multiplicative order of self # """ # raise NotImplementedError diff --git a/src/sage/rings/padics/padic_ZZ_pX_element.pyx b/src/sage/rings/padics/padic_ZZ_pX_element.pyx index 9ef966c1764..b2d6267503e 100644 --- a/src/sage/rings/padics/padic_ZZ_pX_element.pyx +++ b/src/sage/rings/padics/padic_ZZ_pX_element.pyx @@ -55,7 +55,7 @@ big = two**128 + one cdef class pAdicZZpXElement(pAdicExtElement): def __init__(self, parent): """ - Initialization + Initialization. EXAMPLES:: @@ -68,14 +68,14 @@ cdef class pAdicZZpXElement(pAdicExtElement): cdef int _set_from_list(self, L) except -1: """ - Sets ``self`` from a list. + Set ``self`` from a list. The list can contain integers, ``IntegerMods``, rationals, or `p`-adic base elements INPUT: - - `L` -- a list. + - ``L`` -- list EXAMPLES:: @@ -97,17 +97,16 @@ cdef class pAdicZZpXElement(pAdicExtElement): cdef int _set_from_list_rel(self, L, long relprec) except -1: """ - Sets ``self`` from a list. + Set ``self`` from a list. The list can contain integers, ``IntegerMods``, rationals, or `p`-adic base elements INPUT: - - ``L`` -- a list. + - ``L`` -- list - - ``relprec`` -- an integer, capping the relative precision of - ``self``. + - ``relprec`` -- integer; capping the relative precision of ``self`` EXAMPLES:: @@ -133,11 +132,11 @@ cdef class pAdicZZpXElement(pAdicExtElement): INPUT: - - ``L`` -- a list of integers, ``IntegerMod``s, rationals, or `p`-adic - base elements. + - ``L`` -- list of integers, ``IntegerMod``s, rationals, or `p`-adic + base elements - - ``absprec`` -- an integer at which the absolute precision of the - result will be capped. + - ``absprec`` -- integer at which the absolute precision of the + result will be capped EXAMPLES:: @@ -148,7 +147,6 @@ cdef class pAdicZZpXElement(pAdicExtElement): 1 + 2*w + 3*w^2 + 4*w^3 + O(w^25) sage: W([5,10,15,20], absprec=16) # indirect doctest w^5 + 4*w^6 + w^7 + w^8 + 2*w^9 + 4*w^10 + 2*w^11 + 3*w^13 + 2*w^15 + O(w^16) - """ cdef ntl_ZZ_pContext_class ctx L, min_val, ctx = preprocess_list(self, L) @@ -167,12 +165,12 @@ cdef class pAdicZZpXElement(pAdicExtElement): INPUT: - - ``L`` -- a list of integers, ``IntegerMod``s, rationals, or `p`-adic - base elements. + - ``L`` -- list of integers, ``IntegerMod``s, rationals, or `p`-adic + base elements - - ``absprec`` -- an integer at which the absolute precision of the result will be capped. + - ``absprec`` -- integer at which the absolute precision of the result will be capped - - ``relprec`` -- an integer at which the relative precision of the result will be capped. + - ``relprec`` -- integer at which the relative precision of the result will be capped EXAMPLES:: @@ -200,16 +198,16 @@ cdef class pAdicZZpXElement(pAdicExtElement): cdef long _check_ZZ_pContext(self, ntl_ZZ_pContext_class ctx) except -1: """ - Checks that the given ``ntl_ZZ_pContext`` is actually a power + Check that the given ``ntl_ZZ_pContext`` is actually a power of the relevant prime. If so, returns the exponent. INPUT: - - ``ctx`` -- An ``ntl_ZZ_pContext_class`` + - ``ctx`` -- an ``ntl_ZZ_pContext_class`` OUTPUT: - - ``val`` -- If ``ctx`` is a context for `p^n`, returns `n`. + - ``val`` -- if ``ctx`` is a context for `p^n`, returns `n`. Otherwise, raises an error. EXAMPLES:: @@ -230,7 +228,7 @@ cdef class pAdicZZpXElement(pAdicExtElement): cdef ext_p_list_precs(self, bint pos, long prec): """ - Returns a list giving a series representation of ``self``. + Return a list giving a series representation of ``self``. - The returned list will consist of: @@ -247,23 +245,23 @@ cdef class pAdicZZpXElement(pAdicExtElement): generator (in the unramified case). Note that zeros are truncated from the returned list, so you - must use the valuation() function to completely recover self. + must use the valuation() function to completely recover ``self``. INPUT: - - ``pos`` -- ``bint``. If ``True``, all integers will be in + - ``pos`` -- bint; if ``True``, all integers will be in the range `[0,p-1]`, otherwise they will be in the range - `[(1-p)/2, p/2]`. + `[(1-p)/2, p/2]` - - ``prec`` -- How many terms to return in the list. This is + - ``prec`` -- how many terms to return in the list. This is important since shifting in the Eisenstein case can introduce random high order bits. Thus the process would not otherwise necessarily terminate at the right point. OUTPUT: - - ``L`` -- A list of integers or list of lists giving the - series expansion of ``self``. + - ``L`` -- list of integers or list of lists giving the + series expansion of ``self`` EXAMPLES:: @@ -494,7 +492,6 @@ cdef class pAdicZZpXElement(pAdicExtElement): sage: L. = F.ext(x^2 - 2) sage: L(0, 20).trace() O(2^10) - """ if base is not None: if base is self.parent(): @@ -531,7 +528,7 @@ cdef class pAdicZZpXElement(pAdicExtElement): def _prime_pow(self): """ - Provides access to ``self's`` ``prime_pow``. + Provides access to ``self``'s ``prime_pow``. EXAMPLES:: @@ -546,7 +543,7 @@ cdef class pAdicZZpXElement(pAdicExtElement): cdef int _pshift_self(self, long shift) except -1: """ - Multiplies this element by ``p^shift``. + Multiply this element by ``p^shift``. TESTS: @@ -578,7 +575,7 @@ def _test_preprocess_list(R, L): - ``R`` -- a `p`-adic extension ring - - ``L`` -- a list of rationals, integers, ints, longs, + - ``L`` -- list of rationals, integers, ints, longs, ``ntl_ZZ_ps``, ``ntl_ZZs``, ``IntegerMods`` or `p`-adic base elements @@ -650,7 +647,7 @@ cdef preprocess_list(pAdicZZpXElement elt, L): ctx = ntl_ZZ_pContext(py_tmp) else: # integers, rationals and things with finite precision - # note that min_val will be non-positive since things with finite precision return non-positive valuation from get_val_prec + # note that min_val will be nonpositive since things with finite precision return nonpositive valuation from get_val_prec py_tmp = ntl_ZZ.__new__(ntl_ZZ) py_tmp.x = elt.prime_pow.pow_ZZ_tmp(mpz_get_ui(((min_aprec - min_val)).value))[0] ctx = ntl_ZZ_pContext(py_tmp) @@ -707,11 +704,9 @@ def _find_val_aprec_test(R, L): INPUT: - ``R`` -- a `p`-adic extension - - ``L`` -- a list of integers, rationals, ``IntegerMods``, etc. - - OUTPUT: + - ``L`` -- list of integers, rationals, ``IntegerMods``, etc. - - ``min_val`` -- the minimum valuation of any element in the list + OUTPUT: ``min_val`` -- the minimum valuation of any element in the list - ``min_aprec`` -- the minimum absolute precision of any element in the list; if infinite, a predefined constant ``big`` is @@ -749,9 +744,9 @@ cdef find_val_aprec(PowComputer_ext pp, L): INPUT: - ``pp`` -- a PowComputer_ext for the element that this list is - being initialized into. + being initialized into - - ``L`` -- a list of integers, rationals, ``IntegerMods``, etc. + - ``L`` -- list of integers, rationals, ``IntegerMods``, etc. See the documentation for :func:`_find_val_aprec_test` for more details. """ @@ -784,7 +779,7 @@ def _test_get_val_prec(R, a): - ``R`` -- a `p`-adic extension ring to provide a ``PowComputer_ext`` - - ``a`` -- a rational, integer, int, long, ``ntl_ZZ_p``, + - ``a`` -- rational, integer, int, long, ``ntl_ZZ_p``, ``ntl_ZZ``, ``IntegerMod`` or `p`-adic base element OUTPUT: @@ -856,7 +851,7 @@ cdef get_val_prec(PowComputer_ext pp, a): - ``pp`` -- a ``PowComputer_ext`` - - ``a`` -- a rational, integer, int, long, ``ntl_ZZ_p``, + - ``a`` -- rational, integer, int, long, ``ntl_ZZ_p``, ``ntl_ZZ``, ``IntegerMod`` or `p`-adic base element See :func:`_test_get_val_prec` for more details. diff --git a/src/sage/rings/padics/padic_base_generic.py b/src/sage/rings/padics/padic_base_generic.py index 792e99996c5..8001d366b23 100644 --- a/src/sage/rings/padics/padic_base_generic.py +++ b/src/sage/rings/padics/padic_base_generic.py @@ -36,7 +36,7 @@ class pAdicBaseGeneric(pAdicGeneric): def __init__(self, p, prec, print_mode, names, element_class): """ - Initialization + Initialization. TESTS:: @@ -88,7 +88,7 @@ def __init__(self, p, prec, print_mode, names, element_class): def _repr_(self, do_latex=False): r""" - Returns a print representation of this p-adic ring or field. + Return a print representation of this `p`-adic ring or field. EXAMPLES:: @@ -143,9 +143,9 @@ def _repr_(self, do_latex=False): def exact_field(self): """ - Returns the rational field. + Return the rational field. - For compatibility with extensions of p-adics. + For compatibility with extensions of `p`-adics. EXAMPLES:: @@ -157,7 +157,7 @@ def exact_field(self): def exact_ring(self): """ - Returns the integer ring. + Return the integer ring. EXAMPLES:: @@ -169,7 +169,8 @@ def exact_ring(self): def is_isomorphic(self, ring): r""" - Returns whether ``self`` and ``ring`` are isomorphic, i.e. whether ``ring`` is an implementation of `\ZZ_p` for the same prime as ``self``. + Return whether ``self`` and ``ring`` are isomorphic, i.e. whether + ``ring`` is an implementation of `\ZZ_p` for the same prime as ``self``. INPUT: @@ -177,9 +178,8 @@ def is_isomorphic(self, ring): - ``ring`` -- a ring - OUTPUT: - - - ``boolean`` -- whether ``ring`` is an implementation of \ZZ_p` for the same prime as ``self``. + OUTPUT: ``boolean`` -- whether ``ring`` is an implementation of \ZZ_p` + for the same prime as ``self`` EXAMPLES:: @@ -190,7 +190,7 @@ def is_isomorphic(self, ring): def gen(self, n=0): """ - Returns the ``nth`` generator of this extension. For base + Return the `n`-th generator of this extension. For base rings/fields, we consider the generator to be the prime. EXAMPLES:: @@ -204,13 +204,14 @@ def gen(self, n=0): def modulus(self, exact=False): r""" - Returns the polynomial defining this extension. + Return the polynomial defining this extension. - For compatibility with extension fields; we define the modulus to be x-1. + For compatibility with extension fields; we define the modulus to be `x-1`. INPUT: - - ``exact`` -- boolean (default ``False``), whether to return a polynomial with integer entries. + - ``exact`` -- boolean (default: ``False``); whether to return a + polynomial with integer entries EXAMPLES:: @@ -221,7 +222,7 @@ def modulus(self, exact=False): def absolute_discriminant(self): """ - Returns the absolute discriminant of this `p`-adic ring + Return the absolute discriminant of this `p`-adic ring. EXAMPLES:: @@ -232,7 +233,7 @@ def absolute_discriminant(self): def discriminant(self, K=None): """ - Returns the discriminant of this `p`-adic ring over ``K`` + Return the discriminant of this `p`-adic ring over ``K``. INPUT: @@ -242,8 +243,8 @@ def discriminant(self, K=None): OUTPUT: - - integer -- the discriminant of this ring over ``K`` (or the - absolute discriminant if ``K`` is ``None``) + integer; the discriminant of this ring over ``K`` (or the absolute + discriminant if ``K`` is ``None``) EXAMPLES:: @@ -257,7 +258,7 @@ def discriminant(self, K=None): def is_abelian(self): """ - Returns whether the Galois group is abelian, i.e. ``True``. + Return whether the Galois group is abelian, i.e. ``True``. #should this be automorphism group? EXAMPLES:: @@ -269,7 +270,7 @@ def is_abelian(self): def is_normal(self): """ - Returns whether or not this is a normal extension, i.e. ``True``. + Return whether or not this is a normal extension, i.e. ``True``. EXAMPLES:: @@ -280,7 +281,7 @@ def is_normal(self): def uniformizer(self): """ - Returns a uniformizer for this ring. + Return a uniformizer for this ring. EXAMPLES:: @@ -292,7 +293,7 @@ def uniformizer(self): def uniformizer_pow(self, n): """ - Returns the ``nth`` power of the uniformizer of ``self`` (as + Return the `n`-th power of the uniformizer of ``self`` (as an element of ``self``). EXAMPLES:: @@ -307,7 +308,7 @@ def uniformizer_pow(self, n): def _uniformizer_print(self): """ - Returns how the uniformizer is supposed to print. + Return how the uniformizer is supposed to print. EXAMPLES:: @@ -318,7 +319,7 @@ def _uniformizer_print(self): def has_pth_root(self): r""" - Returns whether or not `\ZZ_p` has a primitive `p^{th}` + Return whether or not `\ZZ_p` has a primitive `p`-th root of unity. EXAMPLES:: @@ -332,19 +333,18 @@ def has_pth_root(self): def has_root_of_unity(self, n): r""" - Returns whether or not `\ZZ_p` has a primitive `n^{th}` + Return whether or not `\ZZ_p` has a primitive `n`-th root of unity. INPUT: - ``self`` -- a `p`-adic ring - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: - - ``boolean`` -- whether ``self`` has primitive `n^{th}` root - of unity + boolean; whether ``self`` has primitive `n`-th root of unity EXAMPLES:: @@ -361,19 +361,18 @@ def has_root_of_unity(self, n): def zeta(self, n=None): r""" - Returns a generator of the group of roots of unity. + Return a generator of the group of roots of unity. INPUT: - ``self`` -- a `p`-adic ring - - ``n`` -- an integer or ``None`` (default: ``None``) + - ``n`` -- integer or ``None`` (default: ``None``) OUTPUT: - - ``element`` -- a generator of the `n^{th}` roots of unity, - or a generator of the full group of roots of unity if ``n`` - is ``None`` + ``element``; a generator of the `n`-th roots of unity, or a generator + of the full group of roots of unity if ``n`` is ``None`` EXAMPLES:: @@ -394,7 +393,7 @@ def zeta(self, n=None): def zeta_order(self): """ - Returns the order of the group of roots of unity. + Return the order of the group of roots of unity. EXAMPLES:: @@ -420,7 +419,7 @@ def plot(self, max_points=2500, **args): INPUT: - ``max_points`` -- the maximum number or points to plot, - which controls the depth of recursion (default 2500) + which controls the depth of recursion (default: 2500) - ``**args`` -- color, size, etc. that are passed to the underlying point graphics objects diff --git a/src/sage/rings/padics/padic_base_leaves.py b/src/sage/rings/padics/padic_base_leaves.py index c89cb6a87ed..0cc295f4e69 100644 --- a/src/sage/rings/padics/padic_base_leaves.py +++ b/src/sage/rings/padics/padic_base_leaves.py @@ -98,7 +98,7 @@ sage: type((a * b) / 5^3) -The fixed modulus type is the leanest of the p-adic rings: it is +The fixed modulus type is the leanest of the `p`-adic rings: it is basically just a wrapper around `\ZZ / p^n \ZZ` providing a unified interface with the rest of the `p`-adics. This is the type you should use if your primary interest is in speed (though @@ -219,8 +219,8 @@ def __init__(self, p, prec, print_mode, names): - ``p`` -- prime - ``prec`` -- precision cap - - ``print_mode`` -- dictionary with print options. - - ``names`` -- how to print the prime. + - ``print_mode`` -- dictionary with print options + - ``names`` -- how to print the prime EXAMPLES:: @@ -317,8 +317,8 @@ def __init__(self, p, prec, print_mode, names): - ``p`` -- prime - ``prec`` -- precision cap - - ``print_mode`` -- dictionary with print options. - - ``names`` -- how to print the prime. + - ``print_mode`` -- dictionary with print options + - ``names`` -- how to print the prime EXAMPLES:: @@ -417,8 +417,8 @@ def __init__(self, p, prec, print_mode, names): - ``p`` -- prime - ``prec`` -- precision cap - - ``print_mode`` -- dictionary with print options. - - ``names`` -- how to print the prime. + - ``print_mode`` -- dictionary with print options + - ``names`` -- how to print the prime EXAMPLES:: @@ -505,14 +505,14 @@ class pAdicRingFixedMod(pAdicRingBaseGeneric, pAdicFixedModRingGeneric): """ def __init__(self, p, prec, print_mode, names): """ - Initialization + Initialization. INPUT: - ``p`` -- prime - ``prec`` -- precision cap - - ``print_mode`` -- dictionary with print options. - - ``names`` -- how to print the prime. + - ``print_mode`` -- dictionary with print options + - ``names`` -- how to print the prime EXAMPLES:: @@ -613,7 +613,6 @@ class pAdicFieldCappedRelative(pAdicFieldBaseGeneric, pAdicCappedRelativeFieldGe sage: K = Qp(17, 1000000) # indirect doctest sage: K = Qp(101) # indirect doctest - """ def __init__(self, p, prec, print_mode, names): @@ -624,8 +623,8 @@ def __init__(self, p, prec, print_mode, names): - ``p`` -- prime - ``prec`` -- precision cap - - ``print_mode`` -- dictionary with print options. - - ``names`` -- how to print the prime. + - ``print_mode`` -- dictionary with print options + - ``names`` -- how to print the prime EXAMPLES:: @@ -649,7 +648,7 @@ def __init__(self, p, prec, print_mode, names): sage: R = Qp(3, 2) sage: TestSuite(R).run(elements=[R.random_element() for i in range(3^9)], # long time, needs sage.geometry.polyhedron - ....: skip="_test_metric_function") + ....: skip='_test_metric_function') sage: R._test_metric_function(elements=[R.random_element() for i in range(3^3)]) sage: R = Qp(next_prime(10^60)) @@ -685,7 +684,6 @@ def _coerce_map_from_(self, R): True sage: K.has_coerce_map_from(Zp(17,40)) True - """ #if isinstance(R, pAdicRingRelaxed) or isinstance(R, pAdicFieldRelaxed) and R.prime() == self.prime(): # return True @@ -755,8 +753,8 @@ def __init__(self, p, prec, print_mode, names): - ``p`` -- prime - ``prec`` -- precision cap - - ``print_mode`` -- dictionary with print options. - - ``names`` -- how to print the prime. + - ``print_mode`` -- dictionary with print options + - ``names`` -- how to print the prime EXAMPLES:: @@ -941,7 +939,7 @@ def random_element(self, prec=None): INPUT: - - ``prec`` -- an integer or ``None`` (the default): the + - ``prec`` -- integer or ``None`` (default); the absolute precision of the generated random element EXAMPLES:: @@ -1072,10 +1070,10 @@ def random_element(self, prec=None, integral=False): INPUT: - - ``prec`` -- an integer or ``None`` (the default): the + - ``prec`` -- integer or ``None`` (default); the absolute precision of the generated random element - - ``integral`` -- a boolean (default: ``False``); if ``True``, + - ``integral`` -- boolean (default: ``False``); if ``True``, return an element in the ring of integers EXAMPLES:: diff --git a/src/sage/rings/padics/padic_capped_absolute_element.pyx b/src/sage/rings/padics/padic_capped_absolute_element.pyx index d21b2c18acb..84839c95388 100644 --- a/src/sage/rings/padics/padic_capped_absolute_element.pyx +++ b/src/sage/rings/padics/padic_capped_absolute_element.pyx @@ -32,7 +32,7 @@ cdef extern from "transcendantal.c": cdef class PowComputer_(PowComputer_base): """ - A PowComputer for a capped-absolute padic ring. + A PowComputer for a capped-absolute `p`-adic ring. """ def __init__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field): """ @@ -51,7 +51,7 @@ cdef class PowComputer_(PowComputer_base): cdef class pAdicCappedAbsoluteElement(CAElement): """ - Constructs new element with given parent and value. + Construct new element with given parent and value. INPUT: @@ -126,7 +126,7 @@ cdef class pAdicCappedAbsoluteElement(CAElement): cdef pari_gen _to_gen(self): """ - Converts this element to an equivalent pari element. + Convert this element to an equivalent pari element. EXAMPLES:: @@ -156,7 +156,7 @@ cdef class pAdicCappedAbsoluteElement(CAElement): def _integer_(self, Z=None): r""" - Converts this element to an integer. + Convert this element to an integer. TESTS:: @@ -173,12 +173,14 @@ cdef class pAdicCappedAbsoluteElement(CAElement): INPUT: - - ``absprec`` -- a non-negative integer (default: 1) + - ``absprec`` -- nonnegative integer (default: 1) - - ``field`` -- boolean (default ``None``). Whether to return an element of GF(p) or Zmod(p). + - ``field`` -- boolean (default: ``None``); whether to return an + element of GF(p) or Zmod(p) - - ``check_prec`` -- boolean (default ``True``). Whether to raise an error if this - element has insufficient precision to determine the reduction. + - ``check_prec`` -- boolean (default: ``True``); whether to raise an + error if this element has insufficient precision to determine the + reduction OUTPUT: @@ -231,7 +233,6 @@ cdef class pAdicCappedAbsoluteElement(CAElement): .. SEEALSO:: :meth:`_mod_` - """ if not isinstance(absprec, Integer): absprec = Integer(absprec) @@ -260,7 +261,7 @@ cdef class pAdicCappedAbsoluteElement(CAElement): OUTPUT: - The multiplicative order of self. This is the minimum multiplicative + The multiplicative order of ``self``. This is the minimum multiplicative order of all elements of `\ZZ_p` lifting ``self`` to infinite precision. @@ -306,19 +307,19 @@ cdef class pAdicCappedAbsoluteElement(CAElement): def _log_binary_splitting(self, aprec, mina=0): r""" - Return ``\log(self)`` for ``self`` equal to 1 in the residue field + Return ``\log(self)`` for ``self`` equal to 1 in the residue field. This is a helper method for :meth:`log`. It uses a fast binary splitting algorithm. INPUT: - - ``aprec`` -- an integer, the precision to which the result is + - ``aprec`` -- integer; the precision to which the result is correct. ``aprec`` must not exceed the precision cap of the ring over which this element is defined. - - ``mina`` -- an integer (default: 0), the series will check `n` up to + - ``mina`` -- integer (default: 0); the series will check `n` up to this valuation (and beyond) to see if they can contribute to the - series. + series .. NOTE:: @@ -384,13 +385,13 @@ cdef class pAdicCappedAbsoluteElement(CAElement): def _exp_binary_splitting(self, aprec): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential .. NOTE:: @@ -422,9 +423,8 @@ cdef class pAdicCappedAbsoluteElement(CAElement): sage: R = Zp(7,5) sage: x = R(7) - sage: x.exp(algorithm="binary_splitting") # indirect doctest + sage: x.exp(algorithm='binary_splitting') # indirect doctest 1 + 7 + 4*7^2 + 2*7^3 + O(7^5) - """ cdef unsigned long p cdef unsigned long prec = aprec @@ -444,16 +444,16 @@ cdef class pAdicCappedAbsoluteElement(CAElement): def _exp_newton(self, aprec, log_algorithm=None): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential - - ``log_algorithm`` (default: None) -- the algorithm used for + - ``log_algorithm`` -- (default: ``None``) the algorithm used for computing the logarithm. This attribute is passed to the log method. See :meth:`log` for more details about the possible algorithms. @@ -480,7 +480,7 @@ cdef class pAdicCappedAbsoluteElement(CAElement): sage: # needs sage.libs.ntl sage: R. = Zq(7^2,5) sage: x = R(7*w) - sage: x.exp(algorithm="newton") # indirect doctest + sage: x.exp(algorithm='newton') # indirect doctest 1 + w*7 + (4*w + 2)*7^2 + (w + 6)*7^3 + 5*7^4 + O(7^5) """ cdef unsigned long p diff --git a/src/sage/rings/padics/padic_capped_relative_element.pyx b/src/sage/rings/padics/padic_capped_relative_element.pyx index 701c9575417..5c7e0091ffe 100644 --- a/src/sage/rings/padics/padic_capped_relative_element.pyx +++ b/src/sage/rings/padics/padic_capped_relative_element.pyx @@ -37,7 +37,7 @@ cdef extern from "transcendantal.c": cdef class PowComputer_(PowComputer_base): """ - A PowComputer for a capped-relative padic ring or field. + A PowComputer for a capped-relative `p`-adic ring or field. """ def __init__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field): """ @@ -56,7 +56,7 @@ cdef class PowComputer_(PowComputer_base): cdef class pAdicCappedRelativeElement(CRElement): """ - Constructs new element with given parent and value. + Construct new element with given parent and value. INPUT: @@ -140,8 +140,7 @@ cdef class pAdicCappedRelativeElement(CRElement): sage: R(pari(R(0,5))) O(5^5) - .. TODO:: doctests for converting from other types of p-adic rings - + .. TODO:: doctests for converting from other types of `p`-adic rings """ def lift(self): r""" @@ -256,12 +255,12 @@ cdef class pAdicCappedRelativeElement(CRElement): INPUT: - - ``absprec`` -- a non-negative integer (default: ``1``) + - ``absprec`` -- nonnegative integer (default: 1) - - ``field`` -- boolean (default ``None``); whether to return an element + - ``field`` -- boolean (default: ``None``); whether to return an element of `\GF{p}` or `\ZZ / p\ZZ` - - ``check_prec`` -- boolean (default ``True``); whether to raise + - ``check_prec`` -- boolean (default: ``True``); whether to raise an error if this element has insufficient precision to determine the reduction @@ -303,7 +302,7 @@ cdef class pAdicCappedRelativeElement(CRElement): sage: b.residue() Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue TESTS:: @@ -328,7 +327,6 @@ cdef class pAdicCappedRelativeElement(CRElement): .. SEEALSO:: :meth:`_mod_` - """ cdef Integer selfvalue, modulus cdef long aprec @@ -339,7 +337,7 @@ cdef class pAdicCappedRelativeElement(CRElement): elif absprec < 0: raise ValueError("cannot reduce modulo a negative power of p") if self.ordp < 0: - raise ValueError("element must have non-negative valuation in order to compute residue") + raise ValueError("element must have nonnegative valuation in order to compute residue") if field is None: field = (absprec == 1) elif field and absprec != 1: @@ -368,10 +366,10 @@ cdef class pAdicCappedRelativeElement(CRElement): INPUT: - - ``aprec`` -- an integer, the precision to which the result is + - ``aprec`` -- integer; the precision to which the result is correct; ``aprec`` must not exceed the precision cap of the ring over which this element is defined - - ``mina`` -- an integer (default: 0), the series will check `n` up to + - ``mina`` -- integer (default: 0); the series will check `n` up to this valuation (and beyond) to see if they can contribute to the series @@ -440,13 +438,13 @@ cdef class pAdicCappedRelativeElement(CRElement): def _exp_binary_splitting(self, aprec): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential .. NOTE:: @@ -478,9 +476,8 @@ cdef class pAdicCappedRelativeElement(CRElement): sage: R = Zp(7,5) sage: x = R(7) - sage: x.exp(algorithm="binary_splitting") # indirect doctest + sage: x.exp(algorithm='binary_splitting') # indirect doctest 1 + 7 + 4*7^2 + 2*7^3 + O(7^5) - """ cdef unsigned long p cdef unsigned long prec = aprec @@ -508,13 +505,13 @@ cdef class pAdicCappedRelativeElement(CRElement): INPUT: - - ``aprec`` -- an integer; the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential - ``log_algorithm`` -- (default: ``None``) the algorithm used for computing the logarithm; this attribute is passed to the :meth:`log` - method; see :meth:`log` for more details about the possible - algorithms + method. See :meth:`log` for more details about the possible + algorithms. .. NOTE:: @@ -538,7 +535,7 @@ cdef class pAdicCappedRelativeElement(CRElement): sage: # needs sage.libs.ntl sage: R. = Zq(7^2,5) sage: x = R(7*w) - sage: x.exp(algorithm="newton") # indirect doctest + sage: x.exp(algorithm='newton') # indirect doctest 1 + w*7 + (4*w + 2)*7^2 + (w + 6)*7^3 + 5*7^4 + O(7^5) """ cdef unsigned long p @@ -586,8 +583,8 @@ def base_p_list(Integer n, bint pos, PowComputer_class prime_pow): - ``n`` -- a positive :class:`Integer` - - ``pos`` -- a boolean; if ``True``, then returns the standard base `p` - expansion, otherwise the digits lie in the range `-p/2` to `p/2`. + - ``pos`` -- boolean; if ``True``, then returns the standard base `p` + expansion, otherwise the digits lie in the range `-p/2` to `p/2` - ``prime_pow`` -- a :class:`PowComputer` giving the prime diff --git a/src/sage/rings/padics/padic_ext_element.pyx b/src/sage/rings/padics/padic_ext_element.pyx index 2327c8085a0..417ead46ad4 100644 --- a/src/sage/rings/padics/padic_ext_element.pyx +++ b/src/sage/rings/padics/padic_ext_element.pyx @@ -34,7 +34,7 @@ from sage.libs.ntl.ntl_ZZ_p cimport ntl_ZZ_p cdef class pAdicExtElement(pAdicGenericElement): cdef int _set_from_list(self, L) except -1: """ - Sets self from a list. + Set ``self`` from a list. The list should either be uniform in type, or all of the entries should be coercible to integers. If any of the entries in ``L`` @@ -42,7 +42,7 @@ cdef class pAdicExtElement(pAdicGenericElement): INPUT: - - ``L`` -- a list + - ``L`` -- list """ raise NotImplementedError @@ -57,8 +57,8 @@ cdef class pAdicExtElement(pAdicGenericElement): cdef int _set_from_ZZX(self, ZZX_c poly) except -1: """ - Sets from a ZZX_c, choosing how to handle based on the - precision type of self.parent(). + Set from a ZZX_c, choosing how to handle based on the + precision type of ``self.parent()``. Fixed modulus elements should override this function. @@ -109,7 +109,7 @@ cdef class pAdicExtElement(pAdicGenericElement): cdef int _set_from_ZZ_pX(self, ZZ_pX_c* poly, ntl_ZZ_pContext_class ctx) except -1: """ - Sets self from a ZZ_pX defined with context ctx. + Set ``self`` from a ZZ_pX defined with context ctx. This function should be overridden for fixed modulus elements. @@ -194,7 +194,7 @@ cdef class pAdicExtElement(pAdicGenericElement): cdef int _set_from_ZZ_pE_both(self, ZZ_pE_c* poly, ntl_ZZ_pEContext_class ctx, long absprec, long relprec) except -1: """ - Sets from a ZZ_pE_c with both absolute and relative precision bounded. + Set from a ZZ_pE_c with both absolute and relative precision bounded. Capped absolute and capped relative elements should override this function. @@ -208,7 +208,7 @@ cdef class pAdicExtElement(pAdicGenericElement): cdef int _set_from_ZZ_pEX(self, ZZ_pEX_c* poly, ntl_ZZ_pEContext_class ctx) except -1: """ - Sets self from a ZZ_pEX_c. + Set ``self`` from a ZZ_pEX_c. Fixed modulus elements should override this function. @@ -245,7 +245,7 @@ cdef class pAdicExtElement(pAdicGenericElement): cdef int _set_from_ZZ_pEX_both(self, ZZ_pEX_c* poly, ntl_ZZ_pEContext_class ctx, long absprec, long relprec) except -1: """ - Sets from a ZZ_pEX_c with both absolute and relative precision bounded. + Set from a ZZ_pEX_c with both absolute and relative precision bounded. Capped absolute and capped relative elements should override this function. @@ -274,7 +274,7 @@ cdef class pAdicExtElement(pAdicGenericElement): Return the constant term of a polynomial representing ``self``. This function is mainly for troubleshooting, and the meaning - of the return value will depend on whether self is capped + of the return value will depend on whether ``self`` is capped relative or otherwise. EXAMPLES:: @@ -365,7 +365,7 @@ cdef class pAdicExtElement(pAdicGenericElement): sage: c.frobenius().frobenius() (a + 1)*7^-1 + O(7^3) - An error will be raised if the parent of self is a ramified extension:: + An error will be raised if the parent of ``self`` is a ramified extension:: sage: x = polygen(ZZ, 'x') sage: K. = Qp(5).extension(x^2 - 5) @@ -397,14 +397,13 @@ cdef class pAdicExtElement(pAdicGenericElement): INPUT: - - ``p`` -- a prime, which is compared with the parent of this element. + - ``p`` -- a prime, which is compared with the parent of this element EXAMPLES:: sage: K. = Qq(7^3,4) sage: a._is_base_elt(5) False - """ return False @@ -414,18 +413,16 @@ cdef class pAdicExtElement(pAdicGenericElement): INPUT: - - ``absprec`` -- a non-negative integer (default: ``1``) + - ``absprec`` -- nonnegative integer (default: 1) - - ``field`` -- boolean (default ``None``). For precision 1, whether to return + - ``field`` -- boolean (default: ``None``); for precision 1, whether to return an element of the residue field or a residue ring. Currently unused. - - ``check_prec`` -- boolean (default ``True``). Whether to raise an error if this + - ``check_prec`` -- boolean (default: ``True``); whether to raise an error if this element has insufficient precision to determine the reduction. Errors are never raised for fixed-mod or floating-point types. - OUTPUT: - - This element reduced modulo `\pi^\mathrm{absprec}`. + OUTPUT: this element reduced modulo `\pi^\mathrm{absprec}` If ``absprec`` is zero, then as an element of `\ZZ/(1)`. @@ -475,7 +472,7 @@ cdef class pAdicExtElement(pAdicGenericElement): sage: (a/3).residue(0) Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue sage: # needs sage.libs.flint sage: R = ZpFM(3,5) @@ -495,7 +492,7 @@ cdef class pAdicExtElement(pAdicGenericElement): if absprec < 0: raise ValueError("cannot reduce modulo a negative power of the uniformizer") if self.valuation() < 0: - raise ValueError("element must have non-negative valuation in order to compute residue") + raise ValueError("element must have nonnegative valuation in order to compute residue") R = self.parent() if check_prec and (R.is_fixed_mod() or R.is_floating_point()): check_prec = False diff --git a/src/sage/rings/padics/padic_extension_generic.py b/src/sage/rings/padics/padic_extension_generic.py index 42d58e9d229..2c8ff496f87 100644 --- a/src/sage/rings/padics/padic_extension_generic.py +++ b/src/sage/rings/padics/padic_extension_generic.py @@ -44,7 +44,7 @@ class pAdicExtensionGeneric(pAdicGeneric): def __init__(self, poly, prec, print_mode, names, element_class): """ - Initialization + Initialization. EXAMPLES:: @@ -313,14 +313,14 @@ def __hash__(self): def defining_polynomial(self, var=None, exact=False): """ - Returns the polynomial defining this extension. + Return the polynomial defining this extension. INPUT: - - ``var`` -- string (default: ``'x'``), the name of the variable + - ``var`` -- string (default: ``'x'``); the name of the variable - - ``exact`` -- boolean (default ``False``), whether to return the underlying exact - defining polynomial rather than the one with coefficients in the base ring. + - ``exact`` -- boolean (default: ``False``); whether to return the underlying exact + defining polynomial rather than the one with coefficients in the base ring EXAMPLES:: @@ -377,7 +377,7 @@ def exact_ring(self): """ Return the order with the same defining polynomial. - Will raise a :class:`ValueError` if the coefficients of the defining + Will raise a :exc:`ValueError` if the coefficients of the defining polynomial are not integral. EXAMPLES:: @@ -402,12 +402,12 @@ def exact_ring(self): def modulus(self, exact=False): r""" - Returns the polynomial defining this extension. + Return the polynomial defining this extension. INPUT: - - ``exact`` -- boolean (default ``False``), whether to return the underlying exact - defining polynomial rather than the one with coefficients in the base ring. + - ``exact`` -- boolean (default: ``False``); whether to return the underlying exact + defining polynomial rather than the one with coefficients in the base ring EXAMPLES:: @@ -429,7 +429,7 @@ def modulus(self, exact=False): def ground_ring(self): """ - Returns the ring of which this ring is an extension. + Return the ring of which this ring is an extension. EXAMPLES:: @@ -444,10 +444,10 @@ def ground_ring(self): def ground_ring_of_tower(self): """ - Returns the p-adic base ring of which this is ultimately an + Return the `p`-adic base ring of which this is ultimately an extension. - Currently this function is identical to ground_ring(), since + Currently this function is identical to ``ground_ring()``, since relative extensions have not yet been implemented. EXAMPLES:: @@ -465,7 +465,7 @@ def ground_ring_of_tower(self): def polynomial_ring(self): """ - Returns the polynomial ring of which this is a quotient. + Return the polynomial ring of which this is a quotient. EXAMPLES:: @@ -492,7 +492,7 @@ def polynomial_ring(self): def construction(self, forbid_frac_field=False): """ - Returns the functorial construction of this ring, namely, + Return the functorial construction of this ring, namely, the algebraic extension of the base ring defined by the given polynomial. @@ -579,7 +579,7 @@ def free_module(self, base=None, basis=None, map=True): - ``basis`` -- a basis for this ring/field over the base - - ``map`` -- boolean (default ``True``), whether to return + - ``map`` -- boolean (default: ``True``); whether to return `R`-linear maps to and from `V` OUTPUT: @@ -670,7 +670,7 @@ def free_module(self, base=None, basis=None, map=True): # just stick with Map. class pAdicModuleIsomorphism(Map): r""" - A base class for various isomorphisms between p-adic rings/fields and free modules + A base class for various isomorphisms between `p`-adic rings/fields and free modules. EXAMPLES:: @@ -730,7 +730,7 @@ def _richcmp_(self, other, op): class MapFreeModuleToOneStep(pAdicModuleIsomorphism): """ - The isomorphism from the underlying module of a one-step p-adic extension + The isomorphism from the underlying module of a one-step `p`-adic extension to the extension. EXAMPLES:: @@ -765,7 +765,7 @@ def _call_with_args(self, x, args=(), kwds={}): class MapOneStepToFreeModule(pAdicModuleIsomorphism): """ - The isomorphism from a one-step p-adic extension to its underlying free module + The isomorphism from a one-step `p`-adic extension to its underlying free module. EXAMPLES:: @@ -789,7 +789,7 @@ def _call_(self, x): class MapFreeModuleToTwoStep(pAdicModuleIsomorphism): """ - The isomorphism from the underlying module of a two-step p-adic extension + The isomorphism from the underlying module of a two-step `p`-adic extension to the extension. EXAMPLES:: @@ -836,7 +836,7 @@ def _call_with_args(self, x, args=(), kwds={}): class MapTwoStepToFreeModule(pAdicModuleIsomorphism): """ - The isomorphism from a two-step p-adic extension to its underlying free module + The isomorphism from a two-step `p`-adic extension to its underlying free module. EXAMPLES:: @@ -863,12 +863,12 @@ def _call_(self, x): class DefPolyConversion(Morphism): """ - Conversion map between p-adic rings/fields with the same defining polynomial. + Conversion map between `p`-adic rings/fields with the same defining polynomial. INPUT: - - ``R`` -- a p-adic extension ring or field. - - ``S`` -- a p-adic extension ring or field with the same defining polynomial. + - ``R`` -- a `p`-adic extension ring or field + - ``S`` -- a `p`-adic extension ring or field with the same defining polynomial EXAMPLES:: @@ -919,7 +919,6 @@ def _call_(self, x): sage: R(K(0)) 0 - """ S = self.codomain() Sbase = S.base_ring() @@ -962,7 +961,6 @@ def _call_with_args(self, x, args=(), kwds={}): Traceback (most recent call last): ... TypeError: _call_with_args() got multiple values for keyword argument 'absprec' - """ S = self.codomain() Sbase = S.base_ring() diff --git a/src/sage/rings/padics/padic_extension_leaves.py b/src/sage/rings/padics/padic_extension_leaves.py index d6450039a82..c57e633c60d 100644 --- a/src/sage/rings/padics/padic_extension_leaves.py +++ b/src/sage/rings/padics/padic_extension_leaves.py @@ -117,7 +117,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -175,7 +175,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -261,7 +261,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -320,7 +320,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -382,7 +382,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -401,7 +401,6 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp sage: a % R.prime() # needs sage.libs.flint a - """ self._shift_seed = None self._exact_modulus = exact_modulus @@ -439,7 +438,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -508,7 +507,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -563,7 +562,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -619,7 +618,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused @@ -674,7 +673,7 @@ def __init__(self, exact_modulus, poly, prec, print_mode, shift_seed, names, imp - ``prec`` -- the precision cap of this ring - - ``print_mode`` -- a dictionary of print options + - ``print_mode`` -- dictionary of print options - ``shift_seed`` -- unused diff --git a/src/sage/rings/padics/padic_fixed_mod_element.pyx b/src/sage/rings/padics/padic_fixed_mod_element.pyx index bb4b8f3e0db..0dca538cbbd 100644 --- a/src/sage/rings/padics/padic_fixed_mod_element.pyx +++ b/src/sage/rings/padics/padic_fixed_mod_element.pyx @@ -1,7 +1,7 @@ """ `p`-adic Fixed-Mod Element -Elements of p-adic Rings with Fixed Modulus +Elements of `p`-adic Rings with Fixed Modulus AUTHORS: @@ -34,7 +34,7 @@ cdef extern from "transcendantal.c": cdef class PowComputer_(PowComputer_base): """ - A PowComputer for a fixed-modulus padic ring. + A PowComputer for a fixed-modulus `p`-adic ring. """ def __init__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field): """ @@ -55,9 +55,9 @@ cdef class pAdicFixedModElement(FMElement): r""" INPUT: - - ``parent`` -- a ``pAdicRingFixedMod`` object. + - ``parent`` -- a ``pAdicRingFixedMod`` object - - ``x`` -- input data to be converted into the parent. + - ``x`` -- input data to be converted into the parent - ``absprec`` -- ignored; for compatibility with other `p`-adic rings @@ -158,7 +158,7 @@ cdef class pAdicFixedModElement(FMElement): cdef lift_c(self): r""" - Returns an integer congruent to this element modulo the precision. + Return an integer congruent to this element modulo the precision. .. WARNING:: @@ -250,11 +250,13 @@ cdef class pAdicFixedModElement(FMElement): INPUT: - - ``absprec`` -- an integer (default: ``1``) + - ``absprec`` -- integer (default: 1) - - ``field`` -- boolean (default ``None``). Whether to return an element of GF(p) or Zmod(p). + - ``field`` -- boolean (default: ``None``); whether to return an + element of GF(p) or Zmod(p) - - ``check_prec`` -- boolean (default ``False``). No effect (for compatibility with other types). + - ``check_prec`` -- boolean (default: ``False``); no effect (for + compatibility with other types) OUTPUT: @@ -299,7 +301,6 @@ cdef class pAdicFixedModElement(FMElement): .. SEEALSO:: :meth:`_mod_` - """ cdef Integer selfvalue, modulus cdef long aprec @@ -375,19 +376,19 @@ cdef class pAdicFixedModElement(FMElement): def _log_binary_splitting(self, aprec, mina=0): r""" - Return ``\log(self)`` for ``self`` equal to 1 in the residue field + Return ``\log(self)`` for ``self`` equal to 1 in the residue field. This is a helper method for :meth:`log`. It uses a fast binary splitting algorithm. INPUT: - - ``aprec`` -- an integer, the precision to which the result is + - ``aprec`` -- integer; the precision to which the result is correct. ``aprec`` must not exceed the precision cap of the ring over which this element is defined. - - ``mina`` -- an integer (default: 0), the series will check `n` up to + - ``mina`` -- integer (default: 0); the series will check `n` up to this valuation (and beyond) to see if they can contribute to the - series. + series .. NOTE:: @@ -450,13 +451,13 @@ cdef class pAdicFixedModElement(FMElement): def _exp_binary_splitting(self, aprec): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential .. NOTE:: @@ -488,9 +489,8 @@ cdef class pAdicFixedModElement(FMElement): sage: R = Zp(7,5) sage: x = R(7) - sage: x.exp(algorithm="binary_splitting") # indirect doctest + sage: x.exp(algorithm='binary_splitting') # indirect doctest 1 + 7 + 4*7^2 + 2*7^3 + O(7^5) - """ cdef unsigned long p cdef unsigned long prec = aprec @@ -509,16 +509,16 @@ cdef class pAdicFixedModElement(FMElement): def _exp_newton(self, aprec, log_algorithm=None): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential - - ``log_algorithm`` (default: None) -- the algorithm used for + - ``log_algorithm`` -- (default: ``None``) the algorithm used for computing the logarithm. This attribute is passed to the log method. See :meth:`log` for more details about the possible algorithms. @@ -545,7 +545,7 @@ cdef class pAdicFixedModElement(FMElement): sage: # needs sage.libs.ntl sage: R. = Zq(7^2,5) sage: x = R(7*w) - sage: x.exp(algorithm="newton") # indirect doctest + sage: x.exp(algorithm='newton') # indirect doctest 1 + w*7 + (4*w + 2)*7^2 + (w + 6)*7^3 + 5*7^4 + O(7^5) """ cdef unsigned long p diff --git a/src/sage/rings/padics/padic_floating_point_element.pyx b/src/sage/rings/padics/padic_floating_point_element.pyx index ed80e7c853d..ceae683a62c 100644 --- a/src/sage/rings/padics/padic_floating_point_element.pyx +++ b/src/sage/rings/padics/padic_floating_point_element.pyx @@ -32,7 +32,7 @@ cdef extern from "transcendantal.c": cdef class PowComputer_(PowComputer_base): """ - A PowComputer for a floating-point padic ring or field. + A PowComputer for a floating-point `p`-adic ring or field. """ def __init__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field): """ @@ -51,7 +51,7 @@ cdef class PowComputer_(PowComputer_base): cdef class pAdicFloatingPointElement(FPElement): """ - Constructs new element with given parent and value. + Construct new element with given parent and value. INPUT: @@ -136,7 +136,6 @@ cdef class pAdicFloatingPointElement(FPElement): 0 # todo: doctests for converting from other types of p-adic rings - """ def lift(self): r""" @@ -144,7 +143,7 @@ cdef class pAdicFloatingPointElement(FPElement): precision. If a rational is returned, its denominator will equal ``p^ordp(self)``. - This method will raise a :class:`ValueError` when this element + This method will raise a :exc:`ValueError` when this element is infinity. EXAMPLES:: @@ -245,9 +244,9 @@ cdef class pAdicFloatingPointElement(FPElement): INPUT: - - ``absprec`` -- a non-negative integer (default: ``1``) + - ``absprec`` -- nonnegative integer (default: 1) - - ``field`` -- boolean (default ``None``); whether to return an + - ``field`` -- boolean (default: ``None``); whether to return an element of `\GF{p}` or `\ZZ / p\ZZ` - ``check_prec`` -- ignored (for compatibility with other types) @@ -276,7 +275,7 @@ cdef class pAdicFloatingPointElement(FPElement): sage: b.residue() Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue TESTS:: @@ -301,7 +300,7 @@ cdef class pAdicFloatingPointElement(FPElement): if mpz_sgn((absprec).value) < 0: raise ValueError("cannot reduce modulo a negative power of p") if self.ordp < 0: - raise ValueError("element must have non-negative valuation in order to compute residue") + raise ValueError("element must have nonnegative valuation in order to compute residue") if field is None: field = (absprec == 1) elif field and absprec != 1: @@ -325,13 +324,13 @@ cdef class pAdicFloatingPointElement(FPElement): def _exp_binary_splitting(self, aprec): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential .. NOTE:: @@ -363,9 +362,8 @@ cdef class pAdicFloatingPointElement(FPElement): sage: R = Zp(7,5) sage: x = R(7) - sage: x.exp(algorithm="binary_splitting") # indirect doctest + sage: x.exp(algorithm='binary_splitting') # indirect doctest 1 + 7 + 4*7^2 + 2*7^3 + O(7^5) - """ cdef unsigned long p cdef unsigned long prec = aprec @@ -386,13 +384,13 @@ cdef class pAdicFloatingPointElement(FPElement): def _exp_newton(self, aprec, log_algorithm=None): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer; the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential - ``log_algorithm`` -- (default: ``None``) the algorithm used for @@ -422,7 +420,7 @@ cdef class pAdicFloatingPointElement(FPElement): sage: # needs sage.libs.ntl sage: R. = Zq(7^2,5) sage: x = R(7*w) - sage: x.exp(algorithm="newton") # indirect doctest + sage: x.exp(algorithm='newton') # indirect doctest 1 + w*7 + (4*w + 2)*7^2 + (w + 6)*7^3 + 5*7^4 + O(7^5) """ cdef unsigned long p diff --git a/src/sage/rings/padics/padic_generic.py b/src/sage/rings/padics/padic_generic.py index f9e4792fd3e..ffa0eba1b05 100644 --- a/src/sage/rings/padics/padic_generic.py +++ b/src/sage/rings/padics/padic_generic.py @@ -2,7 +2,7 @@ r""" `p`-adic Generic -A generic superclass for all p-adic parents. +A generic superclass for all `p`-adic parents. AUTHORS: @@ -164,7 +164,7 @@ def __richcmp__(self, other, op): r""" Rich comparison of ``self`` with ``other``. - We consider two p-adic rings or fields to be equal if they are + We consider two `p`-adic rings or fields to be equal if they are equal mathematically, and also have the same precision cap and printing parameters. @@ -230,9 +230,7 @@ def prime(self): r""" Return the prime, ie the characteristic of the residue field. - OUTPUT: - - The characteristic of the residue field. + OUTPUT: the characteristic of the residue field EXAMPLES:: @@ -275,9 +273,7 @@ def residue_characteristic(self): r""" Return the prime, i.e., the characteristic of the residue field. - OUTPUT: - - The characteristic of the residue field. + OUTPUT: the characteristic of the residue field EXAMPLES:: @@ -377,9 +373,7 @@ def fraction_field(self, print_mode=None): - ``print_mode`` -- (optional) a dictionary containing print options; defaults to the same options as this ring - OUTPUT: - - - the fraction field of this ring + OUTPUT: the fraction field of this ring EXAMPLES:: @@ -437,9 +431,7 @@ def integer_ring(self, print_mode=None): - ``print_mode`` -- (optional) a dictionary containing print options; defaults to the same options as this ring - OUTPUT: - - - the ring of elements of this field with nonnegative valuation + OUTPUT: the ring of elements of this field with nonnegative valuation EXAMPLES:: @@ -503,9 +495,7 @@ def teichmuller(self, x, prec=None): - ``x`` -- something that can be cast into ``self`` - OUTPUT: - - - the Teichmüller lift of ``x`` + OUTPUT: the Teichmüller lift of ``x`` EXAMPLES:: @@ -619,7 +609,7 @@ def teichmuller_system(self): def extension(self, modulus, prec=None, names=None, print_mode=None, implementation='FLINT', **kwds): r""" - Create an extension of this p-adic ring. + Create an extension of this `p`-adic ring. EXAMPLES:: @@ -1063,7 +1053,7 @@ def _test_convert_residue_field(self, **options): INPUT: - - ``options`` -- any keyword arguments accepted by :meth:`_tester` + - ``options`` -- any keyword arguments accepted by :meth:`_tester` EXAMPLES:: @@ -1120,7 +1110,7 @@ def frobenius_endomorphism(self, n=1): INPUT: - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) EXAMPLES:: @@ -1217,7 +1207,7 @@ def _primitive_qth_root_of_unity(self, exponent): INPUT: - - ``exponent`` -- an integer or ``Infinity`` + - ``exponent`` -- integer or ``Infinity`` OUTPUT: @@ -1292,9 +1282,9 @@ def primitive_root_of_unity(self, n=None, order=False): INPUT: - - ``n`` -- an integer or ``None`` (default: ``None``) + - ``n`` -- integer or ``None`` (default: ``None``) - - ``order`` -- a boolean (default: ``False``) + - ``order`` -- boolean (default: ``False``) OUTPUT: @@ -1372,7 +1362,7 @@ def roots_of_unity(self, n=None): INPUT: - - ``n`` -- an integer or ``None`` (default: ``None``); if + - ``n`` -- integer or ``None`` (default: ``None``); if ``None``, the full group of roots of unity is returned EXAMPLES:: @@ -1436,17 +1426,17 @@ def _roots_univariate_polynomial(self, P, ring, multiplicities, algorithm, secur - ``ring`` -- a ring into which this ring coerces - - ``multiplicities`` -- a boolean (default: ``True``); + - ``multiplicities`` -- boolean (default: ``True``); whether we have to return the multiplicities of each root or not - - ``algorithm`` -- ``"pari"``, ``"sage"`` or ``None`` (default: + - ``algorithm`` -- ``'pari'``, ``'sage'`` or ``None`` (default: ``None``); Sage provides an implementation for any extension of `\QQ_p` whereas only roots of polynomials over `\QQ_p` is implemented - in Pari; the default is ``"pari"`` if ``ring`` is `\ZZ_p` or `\QQ_p`, - ``"sage"`` otherwise. + in Pari; the default is ``'pari'`` if ``ring`` is `\ZZ_p` or `\QQ_p`, + ``'sage'`` otherwise. - - ``secure`` -- a boolean (default: ``False``) + - ``secure`` -- boolean (default: ``False``) .. NOTE:: @@ -1511,12 +1501,12 @@ def _roots_univariate_polynomial(self, P, ring, multiplicities, algorithm, secur 3 + O(3^9), O(3^9)] - This is due to the fact that we are using ``"pari"`` which does not + This is due to the fact that we are using ``'pari'`` which does not track precision (it can only compute `p`-adic roots of exact polynomials). - If we are switching to ``"sage"`` then the precision on the result + If we are switching to ``'sage'`` then the precision on the result becomes correct (but the computation is much slower):: - sage: P.roots(multiplicities=False, algorithm="sage") # needs sage.geometry.polyhedron sage.libs.ntl + sage: P.roots(multiplicities=False, algorithm='sage') # needs sage.geometry.polyhedron sage.libs.ntl [0, 3 + O(3^11), 1 + O(3^9), @@ -1526,9 +1516,9 @@ def _roots_univariate_polynomial(self, P, ring, multiplicities, algorithm, secur We check that the keyword ``secure`` works as explained above:: sage: P = x^2 + O(3^10)*x + O(3^10) # needs sage.libs.ntl - sage: P.roots(algorithm="sage") # needs sage.geometry.polyhedron sage.libs.ntl + sage: P.roots(algorithm='sage') # needs sage.geometry.polyhedron sage.libs.ntl [(O(3^5), 2)] - sage: P.roots(algorithm="sage", secure=True) # needs sage.libs.ntl + sage: P.roots(algorithm='sage', secure=True) # needs sage.libs.ntl Traceback (most recent call last): ... PrecisionError: not enough precision to determine the number of roots @@ -1611,7 +1601,7 @@ def _roots_univariate_polynomial(self, P, ring, multiplicities, algorithm, secur class ResidueReductionMap(Morphism): r""" - Reduction map from a p-adic ring or field to its residue field or ring. + Reduction map from a `p`-adic ring or field to its residue field or ring. These maps must be created using the :meth:`_create_` method in order to support categories correctly. @@ -1633,8 +1623,8 @@ def _create_(R, k): INPUT: - - ``R`` -- a `p`-adic ring or field. - - ``k`` -- the residue field of ``R``, or a residue ring of ``R``. + - ``R`` -- a `p`-adic ring or field + - ``k`` -- the residue field of ``R``, or a residue ring of ``R`` EXAMPLES:: @@ -1704,14 +1694,14 @@ def _call_(self, x): sage: Zmod(121).convert_map_from(Qp(11))(3/11) # needs sage.rings.finite_rings Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue """ return x.residue(self._n, field=self._field, check_prec=self._field) def section(self): r""" Return the section from the residue ring or field - back to the p-adic ring or field. + back to the `p`-adic ring or field. EXAMPLES:: @@ -1755,7 +1745,7 @@ def _richcmp_(self, other, op): class ResidueLiftingMap(Morphism): r""" - Lifting map to a p-adic ring or field from its residue field or ring. + Lifting map to a `p`-adic ring or field from its residue field or ring. These maps must be created using the :meth:`_create_` method in order to support categories correctly. @@ -1777,8 +1767,8 @@ def _create_(k, R): INPUT: - - ``k`` -- the residue field of ``R``, or a residue ring of ``R``. - - ``R`` -- a `p`-adic ring or field. + - ``k`` -- the residue field of ``R``, or a residue ring of ``R`` + - ``R`` -- a `p`-adic ring or field EXAMPLES:: @@ -1888,7 +1878,7 @@ def _richcmp_(self, other, op): def local_print_mode(obj, print_options, pos=None, ram_name=None): r""" Context manager for safely temporarily changing the print_mode - of a p-adic ring/field. + of a `p`-adic ring/field. EXAMPLES:: diff --git a/src/sage/rings/padics/padic_generic_element.pyx b/src/sage/rings/padics/padic_generic_element.pyx index 92fa0606de1..ec3b1848416 100644 --- a/src/sage/rings/padics/padic_generic_element.pyx +++ b/src/sage/rings/padics/padic_generic_element.pyx @@ -170,7 +170,7 @@ cdef class pAdicGenericElement(LocalGenericElement): cpdef bint _is_exact_zero(self) except -1: """ - Return ``True`` if self is exactly zero. Since + Return ``True`` if ``self`` is exactly zero. Since non-capped-relative elements cannot be exact, this function always returns False. @@ -183,7 +183,7 @@ cdef class pAdicGenericElement(LocalGenericElement): cpdef bint _is_inexact_zero(self) except -1: """ - Return ``True`` if self is indistinguishable from zero, but not + Return ``True`` if ``self`` is indistinguishable from zero, but not exactly zero. EXAMPLES:: @@ -195,7 +195,7 @@ cdef class pAdicGenericElement(LocalGenericElement): cpdef bint _is_zero_rep(self) except -1: """ - Return ``True`` is self is indistinguishable from zero. + Return ``True`` if ``self`` is indistinguishable from zero. EXAMPLES:: @@ -217,7 +217,7 @@ cdef class pAdicGenericElement(LocalGenericElement): """ Quotient with remainder. - We choose the remainder to have the same p-adic expansion + We choose the remainder to have the same `p`-adic expansion as the numerator, but truncated at the valuation of the denominator. EXAMPLES:: @@ -278,8 +278,8 @@ cdef class pAdicGenericElement(LocalGenericElement): def __floordiv__(self, right): """ - Divides self by right and throws away the nonintegral part if - self.parent() is not a field. + Divide ``self`` by ``right`` and throws away the nonintegral part if + ``self.parent()`` is not a field. There are a number of reasonable definitions for floor division. Any definition should satisfy the following @@ -292,7 +292,7 @@ cdef class pAdicGenericElement(LocalGenericElement): However, for elements of integer rings, there are many choices of definitions for a // b and a % b that satisfy this - equation. Since p-adic rings in Sage come equipped with a + equation. Since `p`-adic rings in Sage come equipped with a uniformizer pi, we can use the choice of uniformizer in our definitions. Here are some other criteria we might ask for: @@ -355,7 +355,7 @@ cdef class pAdicGenericElement(LocalGenericElement): cpdef _floordiv_(self, right): """ - Implements floor division. + Implement floor division. EXAMPLES:: @@ -367,7 +367,7 @@ cdef class pAdicGenericElement(LocalGenericElement): def __getitem__(self, n): r""" - Returns the coefficient of `p^n` in the series expansion of this + Return the coefficient of `p^n` in the series expansion of this element, as an integer in the range `0` to `p-1`. EXAMPLES:: @@ -449,7 +449,7 @@ cdef class pAdicGenericElement(LocalGenericElement): def __invert__(self): r""" - Returns the multiplicative inverse of self. + Return the multiplicative inverse of ``self``. EXAMPLES:: @@ -466,8 +466,8 @@ cdef class pAdicGenericElement(LocalGenericElement): cpdef _mod_(self, right): """ - If self is in a field, returns 0. If in a ring, returns a - p-adic integer such that + If ``self`` is in a field, returns 0. If in a ring, returns a + `p`-adic integer such that (1) a = (a // b) * b + a % b @@ -483,7 +483,7 @@ cdef class pAdicGenericElement(LocalGenericElement): However, for elements of integer rings, there are many choices of definitions for a // b and a % b that satisfy this - equation. Since p-adic rings in Sage come equipped with a + equation. Since `p`-adic rings in Sage come equipped with a uniformizer pi, we can use the choice of uniformizer in our definitions. Here are some other criteria we might ask for: @@ -548,10 +548,10 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - ``mode`` -- allows one to override the default print mode of - the parent (default: ``None``). + the parent (default: ``None``) - ``do_latex`` -- whether to return a latex representation or - a normal one. + a normal one EXAMPLES:: @@ -575,11 +575,9 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``) + - ``prec`` -- integer or ``None`` (default: ``None``) - OUTPUT: - - The additive order of this element + OUTPUT: the additive order of this element EXAMPLES:: @@ -601,7 +599,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``) + - ``prec`` -- integer or ``None`` (default: ``None``); the desired precision on the result; if ``None``, the precision is derived from the precision on the input @@ -636,9 +634,7 @@ cdef class pAdicGenericElement(LocalGenericElement): computing the logarithm is available. Otherwise we switch to the ``'series'`` algorithm. - OUTPUT: - - The Artin-Hasse exponential of this element. + OUTPUT: the Artin-Hasse exponential of this element See :wikipedia:`Artin-Hasse_exponential` for more information. @@ -714,7 +710,6 @@ cdef class pAdicGenericElement(LocalGenericElement): - Xavier Caruso (2018-08): extend to any p-adic rings and fields and implement several algorithms. - """ if self.valuation() < 1: raise ValueError("Artin-Hasse exponential does not converge on this input") @@ -757,10 +752,10 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``prec`` -- an integer, the precision at which the + - ``prec`` -- integer; the precision at which the result should be computed - - ``exp_algorithm`` -- a string, the algorithm called + - ``exp_algorithm`` -- string; the algorithm called for computing the exponential EXAMPLES:: @@ -853,7 +848,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``prec`` -- an integer, the precision at which the + - ``prec`` -- integer; the precision at which the result should be computed EXAMPLES:: @@ -904,7 +899,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``prec`` -- an integer, the precision at which the + - ``prec`` -- integer; the precision at which the result should be computed EXAMPLES:: @@ -969,13 +964,13 @@ cdef class pAdicGenericElement(LocalGenericElement): def minimal_polynomial(self, name='x', base=None): """ - Returns the minimal polynomial of this element over ``base`` + Return the minimal polynomial of this element over ``base``. INPUT: - - ``name`` -- string (default: ``'x'``): the name of the variable + - ``name`` -- string (default: ``'x'``); the name of the variable - - ``base`` -- a ring (default: the base ring of the parent): + - ``base`` -- a ring (default: the base ring of the parent); the base ring over which the minimal polynomial is computed EXAMPLES:: @@ -1048,9 +1043,7 @@ cdef class pAdicGenericElement(LocalGenericElement): - ``base`` -- a subring of the parent (default: base ring) - OUTPUT: - - The norm of this `p`-adic element over the given base. + OUTPUT: the norm of this `p`-adic element over the given base EXAMPLES:: @@ -1076,7 +1069,6 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: y = L.random_element() # needs sage.libs.ntl sage: (x*y).norm() == x.norm() * y.norm() # not tested, known bug (see :issue:`32085`) True - """ parent = self.parent() if base is None: @@ -1088,15 +1080,13 @@ cdef class pAdicGenericElement(LocalGenericElement): def trace(self, base=None): """ - Returns the trace of this `p`-adic element over the base ring + Return the trace of this `p`-adic element over the base ring. INPUT: - ``base`` -- a subring of the parent (default: base ring) - OUTPUT: - - The trace of this `p`-adic element over the given base. + OUTPUT: the trace of this `p`-adic element over the given base EXAMPLES:: @@ -1118,7 +1108,6 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: y = L.random_element() # needs sage.libs.ntl sage: (x+y).trace() == x.trace() + y.trace() # not tested, known bug (see :issue:`32085`) True - """ parent = self.parent() if base is None: @@ -1130,7 +1119,7 @@ cdef class pAdicGenericElement(LocalGenericElement): def algdep(self, n): """ - Returns a polynomial of degree at most `n` which is approximately + Return a polynomial of degree at most `n` which is approximately satisfied by this number. Note that the returned polynomial need not be irreducible, and indeed usually won't be if this number is a good approximation to an algebraic number of degree less than `n`. @@ -1140,11 +1129,9 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - ``self`` -- a `p`-adic element - - ``n`` -- an integer + - ``n`` -- integer - OUTPUT: - - polynomial -- degree `n` polynomial approximately satisfied by ``self`` + OUTPUT: polynomial; degree `n` polynomial approximately satisfied by ``self`` EXAMPLES:: @@ -1178,7 +1165,7 @@ cdef class pAdicGenericElement(LocalGenericElement): def algebraic_dependency(self, n): """ - Returns a polynomial of degree at most `n` which is approximately + Return a polynomial of degree at most `n` which is approximately satisfied by this number. Note that the returned polynomial need not be irreducible, and indeed usually won't be if this number is a good approximation to an algebraic number of degree less than `n`. @@ -1187,12 +1174,10 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``self`` -- a p-adic element - - ``n`` -- an integer - - OUTPUT: + - ``self`` -- a `p`-adic element + - ``n`` -- integer - polynomial -- degree `n` polynomial approximately satisfied by ``self`` + OUTPUT: polynomial; degree `n` polynomial approximately satisfied by ``self`` EXAMPLES:: @@ -1238,12 +1223,10 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``bd`` -- integer. Precision bound, defaults to 20 - - ``a`` -- integer. Offset parameter, defaults to 0 - - OUTPUT: + - ``bd`` -- integer (default: 20); precision bound + - ``a`` -- integer (default: 0); offset parameter - A `p`-adic integer. + OUTPUT: a `p`-adic integer .. NOTE:: @@ -1309,9 +1292,7 @@ cdef class pAdicGenericElement(LocalGenericElement): implemented in Sage. The default is ``'pari'`` since PARI is about 10 times faster than Sage. - OUTPUT: - - - a `p`-adic integer + OUTPUT: a `p`-adic integer .. NOTE:: @@ -1320,7 +1301,7 @@ cdef class pAdicGenericElement(LocalGenericElement): William Stein sped it up for GP (http://sage.math.washington.edu/home/wstein/www/home/wbhart/pari-2.4.2.alpha/src/basemath/trans2.c). The ``'sage'`` version uses dwork_expansion() to compute the - `p`-adic gamma function of self as in [RV2007]_ section 6.2. + `p`-adic gamma function of ``self`` as in [RV2007]_ section 6.2. EXAMPLES: @@ -1443,7 +1424,7 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: R(3).gcd(9) 3 + O(3^21) - A non-zero result is always lifted to the maximal precision possible in + A nonzero result is always lifted to the maximal precision possible in the ring:: sage: a = R(3,2); a @@ -1538,7 +1519,6 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: R = ZpCA(3) sage: R(3).gcd(9) 3 + O(3^20) - """ if self.is_zero() and other.is_zero(): if self.valuation() < other.valuation(): @@ -1701,7 +1681,6 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: R = ZpCA(3) sage: R(3).xgcd(9) (3 + O(3^20), 1 + O(3^19), O(3^20)) - """ s,t = self.parent().zero(), self.parent().zero() if self.is_zero() and other.is_zero(): @@ -1729,7 +1708,7 @@ cdef class pAdicGenericElement(LocalGenericElement): def is_square(self): """ - Returns whether this element is a square + Return whether this element is a square. INPUT: @@ -1881,7 +1860,6 @@ cdef class pAdicGenericElement(LocalGenericElement): K(0,0).is_squarefree() False - """ if self.parent().is_field(): if self.is_zero(): @@ -1901,17 +1879,15 @@ cdef class pAdicGenericElement(LocalGenericElement): def multiplicative_order(self, prec = None): r""" - Returns the multiplicative order of ``self``, where ``self`` is + Return the multiplicative order of ``self``, where ``self`` is considered to be one if it is one modulo `p^{\mbox{prec}}`. INPUT: - ``self`` -- a `p`-adic element - - ``prec`` -- an integer + - ``prec`` -- integer - OUTPUT: - - - integer -- the multiplicative order of ``self`` + OUTPUT: integer; the multiplicative order of ``self`` EXAMPLES:: @@ -2006,16 +1982,15 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - ``self`` -- a `p`-adic element - - ``p`` -- a prime (default: ``None``). If specified, will make sure that ``p == self.parent().prime()`` + - ``p`` -- a prime (default: ``None``); if specified, will make sure + that ``p == self.parent().prime()`` .. NOTE:: The optional argument `p` is used for consistency with the valuation methods on integers and rationals. - OUTPUT: - - integer -- the valuation of ``self`` + OUTPUT: integer; the valuation of ``self`` EXAMPLES:: @@ -2131,7 +2106,8 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - ``self`` -- a `p`-adic element - - ``p`` -- a prime (default: ``None``). If specified, will make sure that ``p == self.parent().prime()`` + - ``p`` -- a prime (default: ``None``); if specified, will make sure + that ``p == self.parent().prime()`` .. NOTE:: @@ -2198,9 +2174,9 @@ cdef class pAdicGenericElement(LocalGenericElement): def rational_reconstruction(self): r""" - Returns a rational approximation to this `p`-adic number. + Return a rational approximation to this `p`-adic number. - This will raise an :class:`ArithmeticError` if there are no valid + This will raise an :exc:`ArithmeticError` if there are no valid approximations to the unit part with numerator and denominator bounded by ``sqrt(p^absprec / 2)``. @@ -2208,9 +2184,7 @@ cdef class pAdicGenericElement(LocalGenericElement): :meth:`_rational_` - OUTPUT: - - rational -- an approximation to ``self`` + OUTPUT: rational; an approximation to ``self`` EXAMPLES:: @@ -2321,19 +2295,19 @@ cdef class pAdicGenericElement(LocalGenericElement): def _log_generic(self, aprec, mina=0): r""" - Return ``\log(self)`` for ``self`` equal to 1 in the residue field + Return ``\log(self)`` for ``self`` equal to 1 in the residue field. This is a helper method for :meth:`log`. INPUT: - - ``aprec`` -- an integer, the precision to which the result is + - ``aprec`` -- integer; the precision to which the result is correct. ``aprec`` must not exceed the precision cap of the ring over which this element is defined. - - ``mina`` -- an integer (default: 0), the series will check `n` up to + - ``mina`` -- integer (default: 0); the series will check `n` up to this valuation (and beyond) to see if they can contribute to the - series. + series ALGORITHM: @@ -2367,7 +2341,6 @@ cdef class pAdicGenericElement(LocalGenericElement): Traceback (most recent call last): ... ValueError: Input value (=2) must be 1 in the residue field - """ x = 1-self R = self.parent() @@ -2454,20 +2427,20 @@ cdef class pAdicGenericElement(LocalGenericElement): def _log_binary_splitting(self, aprec, mina=0): r""" - Return ``\log(self)`` for ``self`` equal to 1 in the residue field + Return ``\log(self)`` for ``self`` equal to 1 in the residue field. This is a helper method for :meth:`log`. It uses a fast binary splitting algorithm. INPUT: - - ``aprec`` -- an integer, the precision to which the result is + - ``aprec`` -- integer; the precision to which the result is correct. ``aprec`` must not exceed the precision cap of the ring over which this element is defined. - - ``mina`` -- an integer (default: 0), the series will check `n` up to + - ``mina`` -- integer (default: 0); the series will check `n` up to this valuation (and beyond) to see if they can contribute to the - series. + series .. NOTE:: @@ -2544,11 +2517,11 @@ cdef class pAdicGenericElement(LocalGenericElement): may specify at most one of ``p_branch`` and ``pi_branch``, and must specify one of them if this element is not a unit - - ``aprec`` -- an integer or ``None`` (default: ``None``); if not + - ``aprec`` -- integer or ``None`` (default: ``None``); if not ``None``, then the result will only be correct to precision ``aprec`` - - ``change_frac`` -- In general the codomain of the logarithm should be + - ``change_frac`` -- in general the codomain of the logarithm should be in the `p`-adic field, however, for most neighborhoods of 1, it lies in the ring of integers. This flag decides if the codomain should be the same as the input (default) or if it should change to the @@ -2630,7 +2603,7 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: c.log(p_branch=4) 4 + 2*5 + 3*5^2 + 2*5^3 + 4*5^4 + 2*5^6 + 2*5^7 + 4*5^8 + 2*5^9 + O(5^10) - The branch parameters are only relevant for elements of non-zero + The branch parameters are only relevant for elements of nonzero valuation:: sage: a.log(p_branch=0) @@ -2886,7 +2859,6 @@ cdef class pAdicGenericElement(LocalGenericElement): - Xavier Caruso (2017-06): Added binary splitting type algorithms over Qp - """ if self.is_zero(): raise ValueError('logarithm is not defined at zero') @@ -2977,14 +2949,14 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential EXAMPLES:: sage: R. = Zq(7^2,5) # needs sage.libs.ntl sage: x = R(7*w) # needs sage.libs.ntl - sage: x.exp(algorithm="generic") # indirect doctest # needs sage.libs.ntl + sage: x.exp(algorithm='generic') # indirect doctest # needs sage.libs.ntl 1 + w*7 + (4*w + 2)*7^2 + (w + 6)*7^3 + 5*7^4 + O(7^5) AUTHORS: @@ -2997,7 +2969,6 @@ cdef class pAdicGenericElement(LocalGenericElement): - Julian Rueth (2013-02-14): Rewrite to solve some precision problems in the capped-absolute case - """ R=self.parent() p=self.parent().prime() @@ -3052,13 +3023,13 @@ cdef class pAdicGenericElement(LocalGenericElement): def _exp_binary_splitting(self, aprec): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential .. NOTE:: @@ -3090,24 +3061,23 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: R = Zp(7,5) sage: x = R(7) - sage: x.exp(algorithm="binary_splitting") # indirect doctest + sage: x.exp(algorithm='binary_splitting') # indirect doctest 1 + 7 + 4*7^2 + 2*7^3 + O(7^5) - """ raise NotImplementedError("the binary splitting algorithm is not implemented for the parent: %s" % self.parent()) def _exp_newton(self, aprec, log_algorithm=None): r""" - Compute the exponential power series of this element + Compute the exponential power series of this element. This is a helper method for :meth:`exp`. INPUT: - - ``aprec`` -- an integer, the precision to which to compute the + - ``aprec`` -- integer; the precision to which to compute the exponential - - ``log_algorithm`` (default: None) -- the algorithm used for + - ``log_algorithm`` -- (default: ``None``) the algorithm used for computing the logarithm. This attribute is passed to the log method. See :meth:`log` for more details about the possible algorithms. @@ -3133,7 +3103,7 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: R. = Zq(7^2,5) # needs sage.libs.ntl sage: x = R(7*w) # needs sage.libs.ntl - sage: x.exp(algorithm="newton") # indirect doctest # needs sage.libs.ntl + sage: x.exp(algorithm='newton') # indirect doctest # needs sage.libs.ntl 1 + w*7 + (4*w + 2)*7^2 + (w + 6)*7^3 + 5*7^4 + O(7^5) """ R = self.parent() @@ -3163,7 +3133,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``aprec`` -- an integer or ``None`` (default: ``None``); if + - ``aprec`` -- integer or ``None`` (default: ``None``); if specified, computes only up to the indicated precision - ``algorithm`` -- ``'generic'``, ``'binary_splitting'``, ``'newton'`` @@ -3333,9 +3303,9 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: R = Zp(5,50) sage: a = 5 * R.random_element() - sage: bg = a.exp(algorithm="generic") - sage: bbs = a.exp(algorithm="binary_splitting") - sage: bn = a.exp(algorithm="newton") + sage: bg = a.exp(algorithm='generic') + sage: bbs = a.exp(algorithm='binary_splitting') + sage: bn = a.exp(algorithm='newton') sage: bg == bbs True sage: bg == bn @@ -3356,7 +3326,6 @@ cdef class pAdicGenericElement(LocalGenericElement): - Julian Rueth (2013-02-14): Added doctests, fixed some corner cases - Xavier Caruso (2017-06): Added binary splitting and Newton algorithms - """ p = self.parent().prime() @@ -3393,20 +3362,20 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``self`` -- a `p`-adic element. + - ``self`` -- a `p`-adic element - - ``extend`` -- a boolean (default: ``True``); if ``True``, return a + - ``extend`` -- boolean (default: ``True``); if ``True``, return a square root in an extension if necessary; if ``False`` and no root - exists in the given ring or field, raise a :class:`ValueError`. + exists in the given ring or field, raise a :exc:`ValueError`. - - ``all`` -- a boolean (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots - - ``algorithm`` -- ``"pari"``, ``"sage"`` or ``None`` (default: + - ``algorithm`` -- ``'pari'``, ``'sage'`` or ``None`` (default: ``None``); Sage provides an implementation for any extension of - `\QQ_p`, whereas only square roots over `\QQ_p` are implemented in PARI; - the default is ``"pari"`` if the ground field is `\QQ_p`, ``"sage"`` - otherwise. + `\QQ_p`, whereas only square roots over `\QQ_p` are implemented in + PARI. The default is ``'pari'`` if the ground field is `\QQ_p`, + ``'sage'`` otherwise. OUTPUT: @@ -3595,10 +3564,10 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``all`` -- a boolean (default: ``False``): if ``True``, - return all `n`-th roots of this element, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, + return all `n`-th roots of this element, instead of just one EXAMPLES:: @@ -3733,7 +3702,6 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: elt = L.random_element() sage: elt in (elt^108).nth_root(108, all=True) True - """ n = ZZ(n) if n == 0: @@ -3785,7 +3753,7 @@ cdef class pAdicGenericElement(LocalGenericElement): root = root.lift_to_precision(min(minprec,prec,curprec)) root += invm * root * (1 - a*(root**m)) - # We now extract the (p^v)-th root + # We now extract the `(p^v)`-th root zeta, s, nextzeta = K._primitive_qth_root_of_unity(v) if v: nextzeta = (parent(nextzeta[0]), nextzeta[1]) # nextzeta[0] may have a wrong parent (with more precision) @@ -3831,7 +3799,7 @@ cdef class pAdicGenericElement(LocalGenericElement): - ``twist`` -- an element in the same parent or ``None`` (default: ``None``) - - ``hint`` -- a tuple or ``None`` (default: ``None``); if not + - ``hint`` -- tuple or ``None`` (default: ``None``); if not ``None``, it has to be the output of ``twist._inverse_pth_root()`` OUTPUT: @@ -3872,7 +3840,6 @@ cdef class pAdicGenericElement(LocalGenericElement): sage: for n in [5, 10, 15]: # indirect doctest ....: z = y**n ....: assert z.nth_root(n)**n == z - """ ring = self.parent() p = ring.prime() @@ -4022,7 +3989,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``prec`` -- Integer. The precision of the real field in which + - ``prec`` -- integer; the precision of the real field in which the answer is returned. If ``None``, returns a rational for absolutely unramified fields, or a real with 53 bits of precision for ramified fields. @@ -4078,7 +4045,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``p`` -- a prime, which is compared with the parent of this element. + - ``p`` -- a prime, which is compared with the parent of this element EXAMPLES:: @@ -4090,18 +4057,17 @@ cdef class pAdicGenericElement(LocalGenericElement): raise NotImplementedError def _polylog_res_1(self, n, p_branch = 0): - """ - Return `Li_n(`self`)` , the `n`th `p`-adic polylogarithm of ``self``, assuming that self is congruent to 1 mod p. + r""" + Return `Li_n(`self`)`, the `n`-th `p`-adic polylogarithm of ``self``, + assuming that ``self`` is congruent to `1 \pmod p`. This is an internal function, used by :meth:`polylog`. INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - `Li_n(`self`)` + OUTPUT: `Li_n(`self`)` EXAMPLES:: @@ -4181,7 +4147,7 @@ cdef class pAdicGenericElement(LocalGenericElement): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - ``p_branch`` -- an element in the base ring or its fraction field; the implementation will choose the branch of the logarithm which sends `p` to ``p_branch`` @@ -4411,7 +4377,6 @@ def _AHE_coefficients(p, N, prec): sage: R = ZpFM(2, 10) sage: [ R(c) for c in L ] == [ R(c) for c in AH.list() ] # needs sage.rings.padics False - """ from sage.rings.padics.factory import ZpFM from sage.arith.misc import integer_floor as floor @@ -4461,7 +4426,7 @@ def _findprec(c_1, c_2, c_3, p): INPUT: - `c_1`, `c_2`, `c_3` -- positive integers - - `p` -- prime + - ``p`` -- prime OUTPUT: @@ -4520,11 +4485,9 @@ cpdef dwork_mahler_coeffs(R, int bd=20): INPUT: - ``R`` -- `p`-adic ring in which to compute - - ``bd`` -- integer. Number of terms in the expansion to use - - OUTPUT: + - ``bd`` -- integer; number of terms in the expansion to use - A list of `p`-adic integers. + OUTPUT: a list of `p`-adic integers EXAMPLES:: @@ -4606,7 +4569,7 @@ cpdef gauss_table(long long p, int f, int prec, bint use_longs): r""" Compute a table of Gauss sums using the Gross-Koblitz formula. - This is used in the computation of L-functions of hypergeometric motives. + This is used in the computation of `L`-functions of hypergeometric motives. The Gross-Koblitz formula is used as in `sage.rings.padics.misc.gauss_sum`, but further unpacked for efficiency. diff --git a/src/sage/rings/padics/padic_lattice_element.py b/src/sage/rings/padics/padic_lattice_element.py index d1b75efe6d6..46747174f43 100644 --- a/src/sage/rings/padics/padic_lattice_element.py +++ b/src/sage/rings/padics/padic_lattice_element.py @@ -59,7 +59,7 @@ def unpickle_le(parent, value, prec): - ``value`` -- a rational number - - ``prec`` -- an integer + - ``prec`` -- integer EXAMPLES:: @@ -75,7 +75,7 @@ def unpickle_le(parent, value, prec): class pAdicLatticeElement(pAdicGenericElement): r""" - Constructs new element with given parent and value. + Construct new element with given parent and value. INPUT: @@ -83,21 +83,21 @@ class pAdicLatticeElement(pAdicGenericElement): - ``x`` -- the newly created element - - ``prec`` -- an integer; the absolute precision at which this + - ``prec`` -- integer; the absolute precision at which this element has to be capped - - ``dx`` -- a dictionary representing the differential of ``x`` + - ``dx`` -- dictionary representing the differential of ``x`` - - ``dx_mode`` -- a string, either ``linear_combination`` (the default) - or ``values`` + - ``dx_mode`` -- string; either ``'linear_combination'`` (the default) + or ``'values'`` - - ``valuation`` -- an integer or ``None`` (default: ``None``), + - ``valuation`` -- integer or ``None`` (default: ``None``); the valuation of this element - - ``check`` -- a boolean (default: ``True``), whether the function + - ``check`` -- boolean (default: ``True``); whether the function should check that the given values are well formed and coherent - - ``reduce`` -- a boolean (default: ``True``), whether the given + - ``reduce`` -- boolean (default: ``True``); whether the given values need to be reduced TESTS:: @@ -204,7 +204,7 @@ def _is_base_elt(self, p): INPUT: - - ``p`` -- a prime, which is compared with the parent of this element. + - ``p`` -- a prime, which is compared with the parent of this element EXAMPLES:: @@ -264,12 +264,14 @@ def residue(self, absprec=1, field=None, check_prec=True): INPUT: - - ``absprec`` -- a non-negative integer (default: ``1``) + - ``absprec`` -- nonnegative integer (default: 1) - - ``field`` -- boolean (default ``None``). Whether to return an element of GF(p) or Zmod(p). + - ``field`` -- boolean (default: ``None``); whether to return an + element of GF(p) or Zmod(p) - - ``check_prec`` -- boolean (default ``True``). Whether to raise an error if this - element has insufficient precision to determine the reduction. + - ``check_prec`` -- boolean (default: ``True``); whether to raise an + error if this element has insufficient precision to determine the + reduction OUTPUT: @@ -310,7 +312,7 @@ def residue(self, absprec=1, field=None, check_prec=True): elif absprec < 0: raise ValueError("cannot reduce modulo a negative power of p") if self.valuation() < 0: - raise ValueError("element must have non-negative valuation in order to compute residue") + raise ValueError("element must have nonnegative valuation in order to compute residue") if field is None: field = (absprec == 1) elif field and absprec != 1: @@ -409,11 +411,11 @@ def valuation(self, secure=False): INPUT: - - ``secure`` -- a boolean (default: ``False``); when ``True``, + - ``secure`` -- boolean (default: ``False``); when ``True``, an error is raised if the precision on the element is not - enough to determine for sure its valuation; otherwise the + enough to determine for sure its valuation. Otherwise the absolute precision (which is the smallest possible valuation) - is returned + is returned. EXAMPLES:: @@ -449,7 +451,7 @@ def precision_relative(self, secure=False): INPUT: - - ``secure`` -- a boolean (default: ``False``); when ``True``, + - ``secure`` -- boolean (default: ``False``); when ``True``, an error is raised if the precision on the element is not enough to determine for sure its valuation @@ -727,7 +729,7 @@ def add_bigoh(self, prec): INPUT: - - ``prec`` -- an integer or infinity + - ``prec`` -- integer or infinity EXAMPLES:: @@ -768,16 +770,16 @@ def add_bigoh(self, prec): def lift_to_precision(self, prec=None, infer_precision=False): r""" Return another element of the same parent with absolute precision - at least ``prec``, congruent to this p-adic element modulo the + at least ``prec``, congruent to this `p`-adic element modulo the precision of this element. INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``), the + - ``prec`` -- integer or ``None`` (default: ``None``); the absolute precision of the result. If ``None``, lifts to the - maximum precision allowed + maximum precision allowed. - - ``infer_precision`` -- a boolean (default: ``False``) + - ``infer_precision`` -- boolean (default: ``False``) NOTE: @@ -878,7 +880,7 @@ def is_zero(self, prec=None): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``) + - ``prec`` -- integer or ``None`` (default: ``None``) EXAMPLES:: @@ -1162,13 +1164,13 @@ def expansion(self, n=None, lift_mode='simple', start_val=None): INPUT: - - ``n`` -- an integer or ``None`` (default ``None``); if given, - return the corresponding entry in the expansion. + - ``n`` -- integer or ``None`` (default: ``None``); if given, + return the corresponding entry in the expansion - - ``lift_mode`` -- a string (default: ``simple``); currently - only ``simple`` is implemented. + - ``lift_mode`` -- string (default: ``'simple'``); currently + only ``'simple'`` is implemented - - ``start_val`` -- an integer or ``None`` (default: ``None``); + - ``start_val`` -- integer or ``None`` (default: ``None``); start at this valuation rather than the default (`0` or the valuation of this element). diff --git a/src/sage/rings/padics/padic_printing.pyx b/src/sage/rings/padics/padic_printing.pyx index eb5904907ba..2ac90a5d0f2 100644 --- a/src/sage/rings/padics/padic_printing.pyx +++ b/src/sage/rings/padics/padic_printing.pyx @@ -7,7 +7,7 @@ """ `p`-adic Printing -This file contains code for printing p-adic elements. +This file contains code for printing `p`-adic elements. It has been moved here to prevent code duplication and make finding the relevant code easier. @@ -52,9 +52,9 @@ def pAdicPrinter(ring, options={}): INPUT: - - ring -- a p-adic ring or field. + - ``ring`` -- a `p`-adic ring or field - - options -- a dictionary, with keys in ``'mode'``, ``'pos'``, + - ``options`` -- dictionary, with keys in ``'mode'``, ``'pos'``, ``'ram_name'``, ``'unram_name'``, ``'var_name'``, ``'max_ram_terms'``, ``'max_unram_terms'``, ``'max_terse_terms'``, ``'sep'``, ``'alphabet'``; see :class:`pAdicPrinter_class` for the meanings of these keywords. @@ -74,12 +74,12 @@ def pAdicPrinter(ring, options={}): class pAdicPrinterDefaults(SageObject): """ - This class stores global defaults for p-adic printing. + This class stores global defaults for `p`-adic printing. """ def __init__(self, mode = 'series', pos = True, max_ram_terms = -1, max_unram_terms = -1, max_terse_terms = -1, sep = "|", alphabet = None): r""" Instances of this class store global defaults used in - determining printing options during the creation of p-adic + determining printing options during the creation of `p`-adic rings and fields. One instance stored in padic_printing stores the globally relevant default values. @@ -273,7 +273,7 @@ class pAdicPrinterDefaults(SageObject): def alphabet(self, alphabet = None): r""" - Controls the alphabet used to translate p-adic digits into + Controls the alphabet used to translate `p`-adic digits into strings (so that no separator need be used in ``'digits'`` mode). ``alphabet`` should be passed in as a list or tuple. @@ -301,83 +301,72 @@ _printer_defaults = pAdicPrinterDefaults() cdef class pAdicPrinter_class(SageObject): """ - This class stores the printing options for a specific p-adic ring + This class stores the printing options for a specific `p`-adic ring or field, and uses these to compute the representations of elements. """ def __init__(self, ring, mode, pos, ram_name, unram_name, var_name, max_ram_terms, max_unram_terms, max_terse_terms, sep, alphabet, show_prec): """ - Initializes a :class:`pAdicPrinter`. + Initialize a :class:`pAdicPrinter`. INPUT: - - ring -- the ring or field to which this :class:`pAdicPrinter` is - attached. + - ``ring`` -- the ring or field to which this :class:`pAdicPrinter` is + attached - - mode -- The allowed values for mode are: 'val-unit', - 'series', 'terse', 'digits' and 'bars'. + - ``mode`` -- the allowed values for mode are: ``'val-unit'``, + ``'series'``, ``'terse'``, ``'digits'`` and ``'bars'``: - - 'val-unit' -- elements are displayed as a power of - the uniformizer times a unit, which is displayed in - terse mode. + - ``'val-unit'`` -- elements are displayed as a power of the + uniformizer times a unit, which is displayed in terse mode - - 'series' -- elements are displayed as power series - in the uniformizer. + - ``'series'`` -- elements are displayed as power series in the + uniformizer - - 'terse' -- for base rings and fields, elements are - just displayed as an integer lift. For extensions - rings and fields, elements are displayed as a - polynomial in the generator of the extension. + - ``'terse'`` -- for base rings and fields, elements are just + displayed as an integer lift. For extensions rings and fields, + elements are displayed as a polynomial in the generator of the + extension. - - 'digits' -- Used only for small primes and totally - ramified extensions (or trivial extensions), - elements are displayed as just a string of p-adic - digits, encoded using the 'alphabet' parameter. + - ``'digits'`` -- used only for small primes and totally ramified + extensions (or trivial extensions), elements are displayed as just + a string of `p`-adic digits, encoded using the 'alphabet' parameter - - 'bars' -- Like 'digits', but uses a separator in - order to print a more canonical representation for - each digit. This change allows the use of this - printing mode for unramified extensions and - extensions with larger primes. + - ``'bars'`` -- like ``'digits'``, but uses a separator in order to + print a more canonical representation for each digit. This change + allows the use of this printing mode for unramified extensions and + extensions with larger primes. - - pos -- if True then integers in the range [0,... p-1] - will be used; if False integers in the range - [(1-p)/2,..., p/2] will be used. + - ``pos`` -- if ``True`` then integers in the range [0,... p-1] will be + used; if ``False`` integers in the range [(1-p)/2,..., p/2] will be used - - ram_name -- The string used to represent the - uniformizer. + - ``ram_name`` -- the string used to represent the uniformizer - - unram_name -- The string used to represent the trivial - lift of a generator of the residue field over the prime - field. + - ``unram_name`` -- the string used to represent the trivial lift of a + generator of the residue field over the prime field - - var_name -- The string used to represent the - user-specified generator of this extension ring or - field. + - ``var_name`` -- the string used to represent the user-specified + generator of this extension ring or field - - max_ram_terms -- Controls the maximum number of terms - shown when printing in 'series', 'digits' or 'bars' - mode. + - ``max_ram_terms`` -- controls the maximum number of terms shown when + printing in ``'series'``, ``'digits'`` or ``'bars'`` mode - - max_unram_terms -- For rings with non-prime residue - fields, controls how many terms appear in the - coefficient of each pi^n when printing in 'series' or - 'bar' modes. + - ``max_unram_terms`` -- for rings with non-prime residue fields, + controls how many terms appear in the coefficient of each pi^n when + printing in ``'series'`` or ``'bar'`` modes - - max_terse_terms -- Controls the number of terms - appearing when printing polynomial representations in - 'terse' or 'val-unit' modes. + - ``max_terse_terms`` -- controls the number of terms appearing when + printing polynomial representations in ``'terse'`` or ``'val-unit'`` + modes - - sep -- Controls the separator used in 'bars' - mode. + - ``sep`` -- controls the separator used in ``'bars'`` mode - - alphabet -- Controls the alphabet used to translate - p-adic digits into strings (so that no separator need be - used in 'digits' mode). + - ``alphabet`` -- controls the alphabet used to translate `p`-adic digits + into strings (so that no separator need be used in ``'digits'`` mode) - - show_prec -- Specify how the precision is printed; it - can be 'none', 'bigoh' or 'dots' (the latter being not - available for all modes) + - ``show_prec`` -- Specify how the precision is printed; it can be + ``'none'``, ``'bigoh'`` or ``'dots'`` (the latter being not available + for all modes) TESTS:: @@ -522,7 +511,7 @@ cdef class pAdicPrinter_class(SageObject): (``max_unram_terms`` is irrelevant if the ring is totally ramified over the base, for example). This does not check if the rings are equal (to prevent infinite recursion in the comparison - functions of p-adic rings), but it does check if the primes + functions of `p`-adic rings), but it does check if the primes are the same (since the prime affects whether ``pos`` is relevant). @@ -665,7 +654,7 @@ cdef class pAdicPrinter_class(SageObject): def _pos(self): """ - Accesses self.pos. + Access ``self.pos``. EXAMPLES:: @@ -676,7 +665,7 @@ cdef class pAdicPrinter_class(SageObject): def _sep(self): """ - Accesses self.sep. + Access ``self.sep``. EXAMPLES:: @@ -687,7 +676,7 @@ cdef class pAdicPrinter_class(SageObject): def _alphabet(self): """ - Accesses self.pos. + Access ``self.pos``. EXAMPLES:: @@ -698,7 +687,7 @@ cdef class pAdicPrinter_class(SageObject): def _max_ram_terms(self): """ - Accesses self.max_ram_terms. + Access ``self.max_ram_terms``. EXAMPLES:: @@ -709,7 +698,7 @@ cdef class pAdicPrinter_class(SageObject): def _max_unram_terms(self): """ - Accesses self.max_unram_terms. + Access ``self.max_unram_terms``. EXAMPLES:: @@ -720,7 +709,7 @@ cdef class pAdicPrinter_class(SageObject): def _max_terse_terms(self): """ - Accesses self.max_terse_terms. + Access ``self.max_terse_terms``. EXAMPLES:: @@ -731,7 +720,7 @@ cdef class pAdicPrinter_class(SageObject): def _show_prec(self): """ - Accesses self.show_prec. + Access ``self.show_prec``. EXAMPLES:: @@ -742,7 +731,7 @@ cdef class pAdicPrinter_class(SageObject): def _ring(self): """ - Accesses self.ring. + Access ``self.ring``. EXAMPLES:: @@ -753,7 +742,7 @@ cdef class pAdicPrinter_class(SageObject): def _uniformizer_name(self): """ - Accesses self.ram_name. + Access ``self.ram_name``. EXAMPLES:: @@ -764,7 +753,7 @@ cdef class pAdicPrinter_class(SageObject): def _ram_name(self): """ - Accesses self.ram_name. + Access ``self.ram_name``. EXAMPLES:: @@ -775,7 +764,7 @@ cdef class pAdicPrinter_class(SageObject): def _print_mode(self): """ - Accesses self.mode. + Access ``self.mode``. EXAMPLES:: @@ -795,8 +784,7 @@ cdef class pAdicPrinter_class(SageObject): def _base_p_list(self, value, pos): """ - Returns a list of integers forming the base p expansion of - value. + Return a list of integers forming the base p expansion of value. If pos is True, these integers will be in the range [0,..., p-1]; if pos is False, they will be in the range @@ -820,8 +808,7 @@ cdef class pAdicPrinter_class(SageObject): cdef base_p_list(self, value, bint pos): """ - Returns a list of integers forming the base p expansion of - value. + Return a list of integers forming the base p expansion of value. If pos is True, these integers will be in the range [0,... p-1]; if po is False, they will be in the range @@ -851,10 +838,10 @@ cdef class pAdicPrinter_class(SageObject): INPUT: - - ``elt`` -- a p-adic element of the appropriate ring to print. + - ``elt`` -- a `p`-adic element of the appropriate ring to print - ``do_latex`` -- whether to return a latex representation or - a normal one. + a normal one EXAMPLES:: @@ -898,7 +885,8 @@ cdef class pAdicPrinter_class(SageObject): cdef _repr_gen(self, pAdicGenericElement elt, bint do_latex, bint pos, int mode, ram_name): r""" - Prints a string representation of the element. See __init__ for more details on print modes. + Print a string representation of the element. See ``__init__`` for + more details on print modes. EXAMPLES:: @@ -1275,7 +1263,7 @@ cdef class pAdicPrinter_class(SageObject): cdef _var(self, x, exp, do_latex): """ - Returns a representation of 'x^exp', latexed if necessary. + Return a representation of 'x^exp', latexed if necessary. """ if exp == 0: return "1" @@ -1288,7 +1276,7 @@ cdef class pAdicPrinter_class(SageObject): cdef _dot_var(self, x, exp, do_latex): """ - Returns a representation of '*x^exp', latexed if necessary. + Return a representation of '*x^exp', latexed if necessary. """ if exp == 0: return "" @@ -1304,7 +1292,7 @@ cdef class pAdicPrinter_class(SageObject): cdef _co_dot_var(self, co, x, exp, do_latex): """ - Returns a representation of 'co*x^exp', latexed if necessary. + Return a representation of 'co*x^exp', latexed if necessary. co should be greater than 0 """ @@ -1329,7 +1317,7 @@ cdef class pAdicPrinter_class(SageObject): cdef _plus_ellipsis(self, bint do_latex): """ - Returns a representation of '+ ...', latexed if necessary. + Return a representation of '+ ...', latexed if necessary. """ if do_latex: return " + \\cdots" @@ -1338,7 +1326,7 @@ cdef class pAdicPrinter_class(SageObject): cdef _ellipsis(self, bint do_latex): """ - Returns a representation of '...', latexed if necessary. + Return a representation of '...', latexed if necessary. """ if do_latex: return "\\cdots" @@ -1347,21 +1335,21 @@ cdef class pAdicPrinter_class(SageObject): cdef _truncate_list(self, L, max_terms, zero): """ - Takes a list L of coefficients and returns a list with at most max_terms nonzero terms. + Take a list L of coefficients and returns a list with at most max_terms nonzero terms. INPUT: - - L -- a list + - ``L`` -- list - - max_terms -- nonnegative integer (or -1, in which case + - ``max_terms`` -- nonnegative integer (or -1, in which case no truncation occurs) - - zero -- what should be considered zero, usually 0 or []. + - ``zero`` -- what should be considered zero, usually 0 or [] OUTPUT: - - Truncated list -- later terms are removed. - - Boolean -- whether any truncation occurred. + - truncated list; later terms are removed + - boolean; whether any truncation occurred """ if max_terms == -1 or len(L) == 0: return list(L), False @@ -1379,25 +1367,24 @@ cdef class pAdicPrinter_class(SageObject): cdef _print_unram_term(self, L, bint do_latex, polyname, long max_unram_terms, long expshift, bint increasing): """ - Returns a string representation of L when considered as a polynomial, truncating to at most max_unram_terms nonzero terms. + Return a string representation of L when considered as a polynomial, + truncating to at most ``max_unram_terms`` nonzero terms. INPUT: - - L -- A list of coefficients. + - ``L`` -- a list of coefficients - - do_latex -- whether to print latex-style. + - ``do_latex`` -- whether to print latex-style - - polyname -- the name for the variable. + - ``polyname`` -- the name for the variable - - max_unram_terms -- a maximum number of terms before + - ``max_unram_terms`` -- a maximum number of terms before truncation occurs and an ellipsis is added. -1 indicates no truncation should happen. - - expshift -- a shift for all the exponents of the - variable. + - ``expshift`` -- a shift for all the exponents of the variable - - increasing -- Whether to order the exponents in - increasing fashion. + - ``increasing`` -- whether to order the exponents in increasing fashion """ s = "" cdef Py_ssize_t j, newj @@ -1452,7 +1439,7 @@ cdef class pAdicPrinter_class(SageObject): cdef _terse_frac(self, a, v, u, ram_name, bint do_latex): """ - Returns a representation of a=u/ram_name^v, latexed if necessary. + Return a representation of 'a=u/ram_name^v', latexed if necessary. """ if do_latex: if v >= 0: @@ -1472,21 +1459,19 @@ cdef class pAdicPrinter_class(SageObject): cdef _print_list_as_poly(self, L, bint do_latex, polyname, long expshift, bint increasing): """ - Prints a list L as a polynomial. + Print a list ``L`` as a polynomial. INPUT: - - L -- A list of coefficients. + - ``L`` -- a list of coefficients - - do_latex -- whether to print latex-style. + - ``do_latex`` -- whether to print latex-style - - polyname -- the name for the variable. + - ``polyname`` -- the name for the variable - - expshift -- a shift for all the exponents of the - variable. + - ``expshift`` -- a shift for all the exponents of the variable - - increasing -- Whether to order the exponents in - increasing fashion. + - ``increasing`` -- whether to order the exponents in increasing fashion """ s = "" cdef Py_ssize_t j diff --git a/src/sage/rings/padics/padic_relaxed_errors.pyx b/src/sage/rings/padics/padic_relaxed_errors.pyx index 2157234f62b..5a7938db5f3 100644 --- a/src/sage/rings/padics/padic_relaxed_errors.pyx +++ b/src/sage/rings/padics/padic_relaxed_errors.pyx @@ -30,10 +30,10 @@ def raise_error(error, permissive=False): INPUT: - - ``error`` -- an integer; the error code + - ``error`` -- integer; the error code - - ``permissive`` -- a boolean (default: ``False``); if ``True``, - do not raise weak errors (precision, abandon). + - ``permissive`` -- boolean (default: ``False``); if ``True``, + do not raise weak errors (precision, abandon) TESTS:: @@ -50,7 +50,6 @@ def raise_error(error, permissive=False): PrecisionError: computation has been abandoned; try to increase precision sage: raise_error(1, permissive=True) - """ if error & ERROR_UNEXPECTED: raise RuntimeError("error code = %s" % error) diff --git a/src/sage/rings/padics/padic_template_element.pxi b/src/sage/rings/padics/padic_template_element.pxi index a3b203845b5..c842d9934cd 100644 --- a/src/sage/rings/padics/padic_template_element.pxi +++ b/src/sage/rings/padics/padic_template_element.pxi @@ -46,11 +46,11 @@ cdef long minusmaxordp = -maxordp cdef inline int check_ordp(long ordp) except -1: """ - Checks for overflow after addition or subtraction of valuations. + Check for overflow after addition or subtraction of valuations. There is another variant, :meth:`check_ordp_mpz`, for ``mpz_t`` input. - If overflow is detected, raises a OverflowError. + If overflow is detected, raises a :exc:`OverflowError`. """ if ordp >= maxordp or ordp <= minusmaxordp: raise OverflowError("valuation overflow") @@ -64,8 +64,8 @@ cdef class pAdicTemplateElement(pAdicGenericElement): - ``parent`` -- a local ring or field - ``x`` -- data defining this element. Various types are supported, - including ints, Integers, Rationals, PARI p-adics, integers mod `p^k` - and other Sage p-adics. + including ints, Integers, Rationals, PARI `p`-adics, integers mod `p^k` + and other Sage `p`-adics. - ``absprec`` -- a cap on the absolute precision of this element @@ -75,7 +75,6 @@ cdef class pAdicTemplateElement(pAdicGenericElement): sage: Zp(17)(17^3, 8, 4) 17^3 + O(17^7) - """ def __init__(self, parent, x, absprec=infinity, relprec=infinity): """ @@ -117,7 +116,6 @@ cdef class pAdicTemplateElement(pAdicGenericElement): Traceback (most recent call last): ... TypeError: no conversion between padics when prime numbers differ - """ self.prime_pow = parent.prime_pow pAdicGenericElement.__init__(self, parent) @@ -171,26 +169,26 @@ cdef class pAdicTemplateElement(pAdicGenericElement): cdef int _set(self, x, long val, long xprec, absprec, relprec) except -1: """ - Sets this element from given data computed in :meth:`__init__`. + Set this element from given data computed in :meth:`__init__`. INPUT: - - ``x`` -- an int, Integer, Rational, PARI p-adic, integer mod `p^k` or Sage p-adic + - ``x`` -- an int, Integer, Rational, PARI `p`-adic, integer mod `p^k` or + Sage `p`-adic - - ``val`` -- a long, the valuation of ``x`` + - ``val`` -- a long; the valuation of ``x`` - - ``xprec`` -- a long, the cap on the absolute precision imposed by ``x`` + - ``xprec`` -- a long; the cap on the absolute precision imposed by ``x`` - - ``absprec`` -- an integer or infinity, a bound on the absolute precision - - - ``relprec`` -- an integer or infinity, a bound on the relative precision + - ``absprec`` -- integer or infinity; a bound on the absolute precision + - ``relprec`` -- integer or infinity; a bound on the relative precision """ raise NotImplementedError cdef pAdicTemplateElement _new_with_value(self, celement value, long absprec): """ - Creates a new element with a given value and absolute precision. + Create a new element with a given value and absolute precision. Used by code that doesn't know the precision type. """ @@ -198,13 +196,13 @@ cdef class pAdicTemplateElement(pAdicGenericElement): cdef int _get_unit(self, celement value) except -1: """ - Sets ``value`` to the unit of this p-adic element. + Set ``value`` to the unit of this `p`-adic element. """ raise NotImplementedError def __lshift__(pAdicTemplateElement self, shift): """ - Multiplies ``self`` by ``pi^shift``. + Multiply ``self`` by ``pi^shift``. If ``shift`` is negative and this element does not lie in a field, digits may be truncated. See ``__rshift__`` for details. @@ -269,7 +267,7 @@ cdef class pAdicTemplateElement(pAdicGenericElement): def __rshift__(pAdicTemplateElement self, shift): """ - Divides by ``p^shift``, and truncates (if the parent is not a field). + Divide by ``p^shift``, and truncate (if the parent is not a field). EXAMPLES:: @@ -314,13 +312,13 @@ cdef class pAdicTemplateElement(pAdicGenericElement): cdef pAdicTemplateElement _rshift_c(self, long shift): """ - Divides by ``p^shift`` and truncates (if the parent is not a field). + Divide by ``p^shift`` and truncate (if the parent is not a field). """ raise NotImplementedError cdef int check_preccap(self) except -1: """ - Checks that this element doesn't have precision higher than allowed by + Check that this element doesn't have precision higher than allowed by the precision cap. """ raise NotImplementedError @@ -333,9 +331,9 @@ cdef class pAdicTemplateElement(pAdicGenericElement): INPUT: - - ``absprec`` -- an integer or ``None`` (default: ``None``); the + - ``absprec`` -- integer or ``None`` (default: ``None``); the absolute precision of the result. If ``None``, lifts to the maximum - precision allowed + precision allowed. .. NOTE:: @@ -368,7 +366,6 @@ cdef class pAdicTemplateElement(pAdicGenericElement): 5 sage: a.lift_to_precision(10000) 5 - """ if absprec is None: absprec = maxordp @@ -404,7 +401,7 @@ cdef class pAdicTemplateElement(pAdicGenericElement): Different lift modes affect the choice of `a_i`. When ``lift_mode`` is ``'simple'``, the resulting `a_i` will be - non-negative: if the residue field is `\GF{p}` then they + nonnegative: if the residue field is `\GF{p}` then they will be integers with `0 \le a_i < p`; otherwise they will be a list of integers in the same range giving the coefficients of a polynomial in the indeterminant representing the maximal @@ -421,14 +418,15 @@ cdef class pAdicTemplateElement(pAdicGenericElement): INPUT: - - ``n`` -- integer (default ``None``). If given, returns the corresponding - entry in the expansion. Can also accept a slice (see :meth:`slice`) + - ``n`` -- integer (default: ``None``); if given, returns the + corresponding entry in the expansion. Can also accept a slice (see + :meth:`slice`). - ``lift_mode`` -- ``'simple'``, ``'smallest'`` or ``'teichmuller'`` (default: ``'simple'``) - ``start_val`` -- start at this valuation rather than the - default (`0` or the valuation of this element). + default (`0` or the valuation of this element) OUTPUT: @@ -564,7 +562,7 @@ cdef class pAdicTemplateElement(pAdicGenericElement): def teichmuller_expansion(self, n = None): r""" - Returns an iterator over coefficients `a_0, a_1, \dots, a_n` such that + Return an iterator over coefficients `a_0, a_1, \dots, a_n` such that - `a_i^q = a_i`, where `q` is the cardinality of the residue field, @@ -588,8 +586,8 @@ cdef class pAdicTemplateElement(pAdicGenericElement): INPUT: - - ``n`` -- integer (default ``None``). If given, returns the - coefficient of `\pi^n` in the expansion. + - ``n`` -- integer (default: ``None``); if given, returns the + coefficient of `\pi^n` in the expansion EXAMPLES: @@ -611,7 +609,7 @@ cdef class pAdicTemplateElement(pAdicGenericElement): def _ext_p_list(self, pos): """ - Returns the p-adic expansion of the unit part. Used in printing. + Return the `p`-adic expansion of the unit part. Used in printing. EXAMPLES:: @@ -628,7 +626,7 @@ cdef class pAdicTemplateElement(pAdicGenericElement): cpdef pAdicTemplateElement unit_part(self): r""" - Returns the unit part of this element. + Return the unit part of this element. This is the `p`-adic element `u` in the same ring so that this element is `\pi^v u`, where `\pi` is a uniformizer and `v` is @@ -650,7 +648,7 @@ cdef class pAdicTemplateElement(pAdicGenericElement): INPUT: - - ``p`` -- a prime, which is compared with the parent of this element. + - ``p`` -- a prime, which is compared with the parent of this element EXAMPLES:: @@ -658,7 +656,6 @@ cdef class pAdicTemplateElement(pAdicGenericElement): True sage: a._is_base_elt(17) False - """ return self.prime_pow.prime == p and self.prime_pow.deg == 1 @@ -680,12 +677,12 @@ cdef class pAdicTemplateElement(pAdicGenericElement): INPUT: - - ``absprec`` -- ``0`` or ``1``. + - ``absprec`` -- ``0`` or ``1`` - - ``field`` -- boolean (default ``None``). For precision 1, whether to return + - ``field`` -- boolean (default: ``None``); for precision 1, whether to return an element of the residue field or a residue ring. Currently unused. - - ``check_prec`` -- boolean (default ``True``). Whether to raise an error if this + - ``check_prec`` -- boolean (default: ``True``); whether to raise an error if this element has insufficient precision to determine the reduction. Errors are never raised for fixed-mod or floating-point types. @@ -737,12 +734,12 @@ cdef class pAdicTemplateElement(pAdicGenericElement): sage: (a/3).residue() Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue """ if absprec < 0: raise ValueError("cannot reduce modulo a negative power of the uniformizer") if self.valuation() < 0: - raise ValueError("element must have non-negative valuation in order to compute residue") + raise ValueError("element must have nonnegative valuation in order to compute residue") R = self.parent() if check_prec and (R.is_fixed_mod() or R.is_floating_point()): check_prec = False @@ -772,16 +769,13 @@ cdef Integer exact_pow_helper(long *ansrelprec, long relprec, _right, PowCompute - ``ansrelprec`` -- (return value) the relative precision of the answer - - ``relprec`` -- a positive integer: the relative precision of the base + - ``relprec`` -- positive integer: the relative precision of the base - ``_right`` -- the exponent, nonzero - - ``prime_pow`` -- the Powcomputer for the ring. - - OUTPUT: - - an Integer congruent to the given exponent + - ``prime_pow`` -- the Powcomputer for the ring + OUTPUT: an Integer congruent to the given exponent """ cdef Integer right, p = prime_pow.prime cdef long exp_val @@ -806,14 +800,14 @@ cdef long padic_pow_helper(celement result, celement base, long base_val, long b """ INPUT: - - ``result`` -- the result of exponentiation. + - ``result`` -- the result of exponentiation - - ``base`` -- a celement, the base of the exponentiation. + - ``base`` -- a celement; the base of the exponentiation - - ``base_val`` -- a long, used to check that the base is a unit + - ``base_val`` -- a long; used to check that the base is a unit - - ``base_relprec`` -- a positive integer: the relative precision - of the base. + - ``base_relprec`` -- positive integer; the relative precision + of the base - ``right_unit`` -- the unit part of the exponent @@ -821,11 +815,9 @@ cdef long padic_pow_helper(celement result, celement base, long base_val, long b - ``right_relprec`` -- the relative precision of the exponent - - ``prime_pow`` -- the Powcomputer for the ring. - - OUTPUT: + - ``prime_pow`` -- the Powcomputer for the ring - the precision of the result + OUTPUT: the precision of the result EXAMPLES:: @@ -920,7 +912,7 @@ cdef class ExpansionIter(): def __cinit__(self, pAdicTemplateElement elt, long prec, expansion_mode mode): """ - Allocates memory for the iterator. + Allocate memory for the iterator. TESTS:: @@ -946,7 +938,7 @@ cdef class ExpansionIter(): def __dealloc__(self): """ - Deallocates memory for the iterator. + Deallocate memory for the iterator. TESTS:: @@ -1052,7 +1044,7 @@ cdef class ExpansionIterable(): def __cinit__(self, pAdicTemplateElement elt, long prec, long val_shift, expansion_mode mode): """ - Allocates memory for the iteratable. + Allocate memory for the iteratable. TESTS:: diff --git a/src/sage/rings/padics/padic_template_element_header.pxi b/src/sage/rings/padics/padic_template_element_header.pxi index 11e1cc7fab7..8ddcefd672c 100644 --- a/src/sage/rings/padics/padic_template_element_header.pxi +++ b/src/sage/rings/padics/padic_template_element_header.pxi @@ -1,6 +1,6 @@ """ This file provides the declaration for the pAdicTemplateElement class, -which collects common functionality for the different p-adic template +which collects common functionality for the different `p`-adic template classes. It is included in CR_template_header.pxi, CA_template_header.pxi and diff --git a/src/sage/rings/padics/padic_valuation.py b/src/sage/rings/padics/padic_valuation.py index 1cf29093ba6..7ee6124eebe 100644 --- a/src/sage/rings/padics/padic_valuation.py +++ b/src/sage/rings/padics/padic_valuation.py @@ -105,7 +105,6 @@ class PadicValuationFactory(UniqueFactory): :meth:`pAdicGeneric.valuation() `, :meth:`RationalField.valuation() `, :meth:`IntegerRing_class.valuation() `. - """ def create_key_and_extra_args(self, R, prime=None, approximants=None): r""" @@ -116,13 +115,12 @@ def create_key_and_extra_args(self, R, prime=None, approximants=None): sage: QQ.valuation(2) # indirect doctest 2-adic valuation - """ from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ from sage.rings.padics.padic_generic import pAdicGeneric from sage.rings.number_field.number_field_base import NumberField - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic if R.characteristic() != 0: # We do not support equal characteristic yet @@ -132,7 +130,7 @@ def create_key_and_extra_args(self, R, prime=None, approximants=None): return self.create_key_for_integers(R, prime), {} elif isinstance(R, pAdicGeneric): return self.create_key_for_local_ring(R, prime), {} - elif isinstance(R.fraction_field(), NumberField) or is_PolynomialQuotientRing(R): + elif isinstance(R.fraction_field(), NumberField) or isinstance(R, PolynomialQuotientRing_generic): return self.create_key_and_extra_args_for_number_field(R, prime, approximants=approximants) else: raise NotImplementedError("p-adic valuations not implemented for %r" % (R,)) @@ -146,7 +144,6 @@ def create_key_for_integers(self, R, prime): sage: QQ.valuation(2) # indirect doctest 2-adic valuation - """ from sage.rings.integer_ring import ZZ if prime is None: @@ -167,7 +164,6 @@ def create_key_for_local_ring(self, R, prime): sage: Qp(2).valuation() # indirect doctest 2-adic valuation - """ # We do not care much about the value of prime since there is only one # reasonable p-adic valuation here @@ -189,7 +185,6 @@ def create_key_and_extra_args_for_number_field(self, R, prime, approximants): sage: GaussianIntegers().valuation(2) # indirect doctest # needs sage.rings.number_field 2-adic valuation - """ K, L, G = self._normalize_number_field_data(R) @@ -230,7 +225,6 @@ def create_key_and_extra_args_for_number_field_from_valuation(self, R, v, prime, sage: R. = QQ[] sage: S = R.quo(x^2 + 1) sage: v = valuations.pAdicValuation(S, v) # needs sage.geometry.polyhedron - """ K, L, G = self._normalize_number_field_data(R) @@ -306,7 +300,6 @@ def create_key_and_extra_args_for_number_field_from_ideal(self, R, I, prime): sage: K. = NumberField([x^2 - 2, x^2 + x + 1]) sage: K.valuation(2) 2-adic valuation - """ K, L, G = self._normalize_number_field_data(R) @@ -360,15 +353,14 @@ def _normalize_number_field_data(self, R): (Rational Field, Univariate Quotient Polynomial Ring in xbar over Rational Field with modulus x^2 + 1, x^2 + 1) - """ - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic from sage.rings.number_field.number_field_base import NumberField if isinstance(R.fraction_field(), NumberField): L = R.fraction_field() G = L.relative_polynomial() K = L.base_ring() - elif is_PolynomialQuotientRing(R): + elif isinstance(R, PolynomialQuotientRing_generic): from sage.categories.number_fields import NumberFields if R.base_ring().fraction_field() not in NumberFields(): raise NotImplementedError("cannot normalize quotients over %r" % (R.base_ring(),)) @@ -388,13 +380,12 @@ def create_object(self, version, key, **extra_args): sage: ZZ.valuation(5) # indirect doctest 5-adic valuation - """ from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ from sage.rings.padics.padic_generic import pAdicGeneric from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic from sage.rings.number_field.number_field_base import NumberField R = key[0] parent = DiscretePseudoValuationSpace(R) @@ -412,7 +403,7 @@ def create_object(self, version, key, **extra_args): K = R.fraction_field() if isinstance(K, NumberField): G = K.relative_polynomial() - elif is_PolynomialQuotientRing(R): + elif isinstance(R, PolynomialQuotientRing_generic): G = R.modulus() else: raise NotImplementedError @@ -453,7 +444,6 @@ class pAdicValuation_base(DiscreteValuation): sage: TestSuite(ZZ.valuation(3)).run() # long time # needs sage.geometry.polyhedron sage: TestSuite(QQ.valuation(5)).run() # long time # needs sage.geometry.polyhedron sage: TestSuite(Zp(5).valuation()).run() # long time # needs sage.geometry.polyhedron - """ def __init__(self, parent, p): r""" @@ -462,7 +452,6 @@ def __init__(self, parent, p): sage: from sage.rings.padics.padic_valuation import pAdicValuation_base sage: isinstance(ZZ.valuation(3), pAdicValuation_base) True - """ DiscreteValuation.__init__(self, parent) @@ -477,7 +466,6 @@ def p(self): sage: GaussianIntegers().valuation(2).p() # needs sage.rings.number_field 2 - """ return self._p @@ -489,21 +477,18 @@ def reduce(self, x): - ``x`` -- an element in the domain of this valuation - OUTPUT: - - An element of the :meth:`~sage.rings.valuation.valuation_space.DiscretePseudoValuationSpace.ElementMethods.residue_field`. + OUTPUT: an element of the :meth:`~sage.rings.valuation.valuation_space.DiscretePseudoValuationSpace.ElementMethods.residue_field` EXAMPLES:: sage: v = ZZ.valuation(3) sage: v.reduce(4) 1 - """ x = self.domain().coerce(x) if self(x) < 0: - raise ValueError("reduction is only defined for elements of non-negative valuation") + raise ValueError("reduction is only defined for elements of nonnegative valuation") return self.residue_field()(x) @@ -521,7 +506,6 @@ def lift(self, x): sage: xbar = v.reduce(4) sage: v.lift(xbar) 1 - """ x = self.residue_field().coerce(x) @@ -536,11 +520,11 @@ def is_unramified(self, G, include_steps=False, assume_squarefree=False): - ``G`` -- a monic squarefree polynomial over the domain of this valuation - - ``include_steps`` -- a boolean (default: ``False``); whether to + - ``include_steps`` -- boolean (default: ``False``); whether to include the approximate valuations that were used to determine the - result in the return value. + result in the return value - - ``assume_squarefree`` -- a boolean (default: ``False``); whether to + - ``assume_squarefree`` -- boolean (default: ``False``); whether to assume that ``G`` is square-free over the completion of the domain of this valuation. Setting this to ``True`` can significantly improve the performance. @@ -566,12 +550,11 @@ def is_unramified(self, G, include_steps=False, assume_squarefree=False): sage: v.is_unramified(x^2 + 2*x + 4) # needs sage.geometry.polyhedron True - """ R = G.parent() - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if not is_PolynomialRing(R) or R.base_ring() is not self.domain() or not G.is_monic(): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if not isinstance(R, PolynomialRing_general) or R.base_ring() is not self.domain() or not G.is_monic(): raise ValueError("G must be a monic univariate polynomial over the domain of this valuation") if not assume_squarefree and not G.is_squarefree(): raise ValueError("G must be squarefree") @@ -613,11 +596,11 @@ def is_totally_ramified(self, G, include_steps=False, assume_squarefree=False): - ``G`` -- a monic squarefree polynomial over the domain of this valuation - - ``include_steps`` -- a boolean (default: ``False``); where to include + - ``include_steps`` -- boolean (default: ``False``); where to include the valuations produced during the process of checking whether ``G`` is totally ramified in the return value - - ``assume_squarefree`` -- a boolean (default: ``False``); whether to + - ``assume_squarefree`` -- boolean (default: ``False``); whether to assume that ``G`` is square-free over the completion of the domain of this valuation. Setting this to ``True`` can significantly improve the performance. @@ -664,12 +647,11 @@ def is_totally_ramified(self, G, include_steps=False, assume_squarefree=False): sage: f = x^9 + 9*x^2 + 3 sage: R.valuation().is_totally_ramified(f) # needs sage.geometry.polyhedron True - """ R = G.parent() - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if not is_PolynomialRing(R) or R.base_ring() is not self.domain() or not G.is_monic(): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if not isinstance(R, PolynomialRing_general) or R.base_ring() is not self.domain() or not G.is_monic(): raise ValueError("G must be a monic univariate polynomial over the domain of this valuation") if not assume_squarefree and not G.is_squarefree(): raise ValueError("G must be squarefree") @@ -711,7 +693,6 @@ def change_domain(self, ring): sage: v = ZZ.valuation(2) sage: v.change_domain(QQ).domain() Rational Field - """ return pAdicValuation(ring, self.p()) @@ -725,7 +706,6 @@ def _extensions_to_quotient(self, ring, approximants=None): sage: R. = QQ[] sage: QQ.valuation(2)._extensions_to_quotient(R.quo(x^2 + x + 1)) [2-adic valuation] - """ approximants = approximants or self.mac_lane_approximants(ring.modulus().change_ring(self.domain()), assume_squarefree=True, require_incomparability=True) return [pAdicValuation(ring, approximant, approximants) for approximant in approximants] @@ -791,7 +771,6 @@ def extensions(self, ring): sage: v.extensions(L) [[ 2-adic valuation, v(x) = 1/24, v(x^24 + 4*x^18 + 10*x^12 + 12*x^6 + 8*x^3 + 6) = 29/8 ]-adic valuation, [ 2-adic valuation, v(x) = 1/24, v(x^24 + 4*x^18 + 2*x^12 + 12*x^6 + 8*x^3 + 6) = 29/8 ]-adic valuation] - """ if self.domain() is ring: return [self] @@ -800,9 +779,9 @@ def extensions(self, ring): if domain_fraction_field.is_subring(ring): return pAdicValuation(domain_fraction_field, self).extensions(ring) if self.domain().is_subring(ring): - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing - if is_PolynomialQuotientRing(ring): - if is_PolynomialQuotientRing(self.domain()): + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic + if isinstance(ring, PolynomialQuotientRing_generic): + if isinstance(self.domain(), PolynomialQuotientRing_generic): if self.domain().modulus() == ring.modulus(): base_extensions = self._base_valuation.extensions(self._base_valuation.domain().change_ring(self._base_valuation.domain().base_ring().fraction_field())) return [pAdicValuation(ring, base._initial_approximation) for base in base_extensions] @@ -830,7 +809,6 @@ def restriction(self, ring): sage: v = GaussianIntegers().valuation(2) # needs sage.rings.number_field sage: v.restriction(ZZ) # needs sage.rings.number_field 2-adic valuation - """ if ring is self.domain(): return self @@ -850,7 +828,6 @@ def value_semigroup(self): sage: v = GaussianIntegers().valuation(2) # needs sage.rings.number_field sage: v.value_semigroup() # needs sage.rings.number_field Additive Abelian Semigroup generated by 1/2 - """ from sage.categories.fields import Fields v = self(self.uniformizer()) @@ -876,7 +853,6 @@ class pAdicValuation_padic(pAdicValuation_base): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def __init__(self, parent): """ @@ -885,7 +861,6 @@ def __init__(self, parent): sage: from sage.rings.padics.padic_valuation import pAdicValuation_padic sage: isinstance(Qp(2).valuation(), pAdicValuation_padic) True - """ pAdicValuation_base.__init__(self, parent, parent.domain().prime()) @@ -897,16 +872,13 @@ def reduce(self, x): - ``x`` -- an element of the domain of this valuation - OUTPUT: - - An element of the :meth:`~sage.rings.valuation.valuation_space.DiscretePseudoValuationSpace.ElementMethods.residue_field`. + OUTPUT: an element of the :meth:`~sage.rings.valuation.valuation_space.DiscretePseudoValuationSpace.ElementMethods.residue_field` EXAMPLES:: sage: R = Zp(3) sage: Zp(3).valuation().reduce(R(4)) 1 - """ x = self.domain().coerce(x) return self.residue_field()(x.residue()) @@ -927,7 +899,6 @@ def lift(self, x): sage: xbar = v.reduce(R(4)) sage: v.lift(xbar) 1 + O(3^20) - """ x = self.residue_field().coerce(x) return self.domain()(x).lift_to_precision() @@ -941,7 +912,6 @@ def uniformizer(self): sage: v = Zp(3).valuation() sage: v.uniformizer() 3 + O(3^21) - """ return self.domain().uniformizer() @@ -966,7 +936,6 @@ def element_with_valuation(self, v): sage: L. = K.extension(y^2 + 3*y + 3) sage: L.valuation().element_with_valuation(3/2) y^3 + O(y^43) - """ from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ @@ -984,7 +953,6 @@ def _repr_(self): sage: ZZ.valuation(3)._repr_() '3-adic valuation' - """ return "%s-adic valuation" % (self.p()) @@ -999,7 +967,6 @@ def _call_(self, x): sage: L. = K.extension(y^2 - 3) # needs sage.libs.ntl sage: L.valuation()(3) # needs sage.libs.ntl 1 - """ return x.ordp() @@ -1011,7 +978,6 @@ def residue_ring(self): sage: Qq(9, names='a').valuation().residue_ring() # needs sage.libs.ntl Finite Field in a0 of size 3^2 - """ return self.domain().residue_field() @@ -1020,7 +986,7 @@ def shift(self, x, s): Shift ``x`` in its expansion with respect to :meth:`uniformizer` by ``s`` "digits". - For non-negative ``s``, this just returns ``x`` multiplied by a + For nonnegative ``s``, this just returns ``x`` multiplied by a power of the uniformizer `\pi`. For negative ``s``, it does the same but when not over a field, it @@ -1042,7 +1008,6 @@ def shift(self, x, s): sage: v = S.valuation() sage: v.shift(1, 5) y^5 + O(y^60) - """ x = self.domain().coerce(x) s = self.value_group()(s) @@ -1073,7 +1038,6 @@ def simplify(self, x, error=None, force=False): 2 + O(2^21) sage: v.simplify(6, error=0) 0 - """ x = self.domain().coerce(x) @@ -1100,7 +1064,6 @@ class pAdicValuation_int(pAdicValuation_base): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def _repr_(self): """ @@ -1110,7 +1073,6 @@ def _repr_(self): sage: ZZ.valuation(3)._repr_() '3-adic valuation' - """ return "%s-adic valuation" % (self.p()) @@ -1120,13 +1082,12 @@ def _call_(self, x): INPUT: - - ``x`` -- an element in the domain of this valuation + - ``x`` -- an element in the domain of this valuation EXAMPLES:: sage: ZZ.valuation(3)(9) 2 - """ if x.is_zero(): # x.valuation() is a factor 10 slower when computing the valuation @@ -1145,7 +1106,6 @@ def uniformizer(self): sage: v = ZZ.valuation(3) sage: v.uniformizer() 3 - """ return self.domain()(self.p()) @@ -1158,7 +1118,6 @@ def residue_ring(self): sage: v = ZZ.valuation(3) sage: v.residue_ring() Finite Field of size 3 - """ from sage.rings.finite_rings.finite_field_constructor import GF return GF(self.p()) @@ -1174,7 +1133,6 @@ def _ge_(self, other): sage: w = valuations.TrivialValuation(ZZ) sage: v >= w True - """ if other.is_trivial(): return other.is_discrete_valuation() @@ -1201,7 +1159,6 @@ def _relative_size(self, x): 1 sage: v._relative_size(2**20) 11 - """ x = self.domain().coerce(x) return (x.numerator().nbits() + x.denominator().nbits())//self.p().nbits() @@ -1246,7 +1203,6 @@ def simplify(self, x, error=None, force=False, size_heuristic_bound=32): Traceback (most recent call last): ... ArithmeticError: rational reconstruction of 55203 (mod 65536) does not exist - """ if not force and self._relative_size(x) <= size_heuristic_bound: return x @@ -1328,7 +1284,6 @@ def inverse(self, x, precision): sage: v.inverse(2, 0) 1 - """ if not x.is_zero(): y = ~x @@ -1365,7 +1320,6 @@ class pAdicFromLimitValuation(FiniteExtensionFromLimitValuation, pAdicValuation_ sage: v.shift(1, -1).parent() # needs sage.rings.number_field Number Field in I with defining polynomial x^2 + 1 with I = 1*I - """ def __init__(self, parent, approximant, G, approximants): r""" @@ -1375,7 +1329,6 @@ def __init__(self, parent, approximant, G, approximants): sage: from sage.rings.padics.padic_valuation import pAdicFromLimitValuation sage: isinstance(v, pAdicFromLimitValuation) # needs sage.rings.number_field True - """ FiniteExtensionFromLimitValuation.__init__(self, parent, approximant, G, approximants) pAdicValuation_base.__init__(self, parent, approximant.restriction(approximant.domain().base_ring()).p()) @@ -1404,7 +1357,6 @@ def _to_base_domain(self, f): sage: w = v.extension(L).extension(M) sage: w._to_base_domain(b) x - """ polynomial = f.lift() return polynomial(self._base_valuation.domain().gen()) @@ -1419,7 +1371,6 @@ def _from_base_domain(self, f): sage: v = GaussianIntegers().valuation(3) # needs sage.rings.number_field sage: v._from_base_domain(v._base_valuation.domain().gen()) # needs sage.rings.number_field I - """ return self.domain()(f) @@ -1432,7 +1383,6 @@ def extensions(self, ring): sage: v = GaussianIntegers().valuation(3) # needs sage.rings.number_field sage: v.extensions(v.domain().fraction_field()) # needs sage.rings.number_field [3-adic valuation] - """ if ring is self.domain().fraction_field(): if self.domain() is not self.domain().fraction_field(): @@ -1457,14 +1407,13 @@ def _fraction_field(ring): sage: from sage.rings.padics.padic_valuation import _fraction_field sage: _fraction_field(S) Univariate Quotient Polynomial Ring in xbar over Rational Field with modulus x^2 + 1 - """ from sage.categories.fields import Fields if ring in Fields(): return ring - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing - if is_PolynomialQuotientRing(ring): + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic + if isinstance(ring, PolynomialQuotientRing_generic): from sage.categories.integral_domains import IntegralDomains if ring in IntegralDomains(): return ring.base().change_ring(ring.base_ring().fraction_field()).quo(ring.modulus()) diff --git a/src/sage/rings/padics/pow_computer.pyx b/src/sage/rings/padics/pow_computer.pyx index dda423f4a0f..9719dfa1efe 100644 --- a/src/sage/rings/padics/pow_computer.pyx +++ b/src/sage/rings/padics/pow_computer.pyx @@ -9,8 +9,8 @@ PowComputer A class for computing and caching powers of the same integer. -This class is designed to be used as a field of p-adic rings and -fields. Since elements of p-adic rings and fields need to use powers +This class is designed to be used as a field of `p`-adic rings and +fields. Since elements of `p`-adic rings and fields need to use powers of p over and over, this class precomputes and stores powers of p. There is no reason that the base has to be prime however. @@ -69,26 +69,26 @@ cdef class PowComputer_class(SageObject): def __init__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly=None, shift_seed=None): """ - Initializes self. + Initialize ``self``. INPUT: - * prime -- the prime that is the base of the exponentials - stored in this pow_computer. + - ``prime`` -- the prime that is the base of the exponentials + stored in this ``pow_computer`` - * cache_limit -- how high to cache powers of prime. + - ``cache_limit`` -- how high to cache powers of prime - * prec_cap -- data stored for p-adic elements using this - pow_computer (so they have C-level access to fields - common to all elements of the same parent). + - ``prec_cap`` -- data stored for `p`-adic elements using this + ``pow_computer`` (so they have C-level access to fields + common to all elements of the same parent) - * ram_prec_cap -- prec_cap * e + - ``ram_prec_cap`` -- prec_cap * e - * in_field -- same idea as prec_cap + - ``in_field`` -- same idea as prec_cap - * poly -- same idea as prec_cap + - ``poly`` -- same idea as prec_cap - * shift_seed -- same idea as prec_cap + - ``shift_seed`` -- same idea as prec_cap EXAMPLES:: @@ -105,7 +105,7 @@ cdef class PowComputer_class(SageObject): def __richcmp__(self, other, int op): """ - Compares ``self`` to ``other``. + Compare ``self`` to ``other``. EXAMPLES:: @@ -148,7 +148,7 @@ cdef class PowComputer_class(SageObject): cdef Integer pow_Integer(self, long n): """ - Returns self.prime^n + Return ``self.prime^n``. EXAMPLES:: @@ -162,7 +162,7 @@ cdef class PowComputer_class(SageObject): def pow_Integer_Integer(self, n): """ - Tests the pow_Integer function. + Test the ``pow_Integer`` function. EXAMPLES:: @@ -247,14 +247,14 @@ cdef class PowComputer_class(SageObject): m = Integer(m) n = Integer(n) if m < 0 or n < 0: - raise ValueError("m, n must be non-negative") + raise ValueError("m, n must be nonnegative") cdef Integer ans = PY_NEW(Integer) mpz_mul(ans.value, self.pow_mpz_t_tmp(mpz_get_ui((m).value)), self.pow_mpz_t_tmp(mpz_get_ui((n).value))) return ans def _pow_mpz_t_tmp_test(self, n): """ - Tests the pow_mpz_t_tmp function. + Test the ``pow_mpz_t_tmp`` function. EXAMPLES:: @@ -286,7 +286,7 @@ cdef class PowComputer_class(SageObject): cdef mpz_srcptr pow_mpz_t_top(self) noexcept: """ - Returns a pointer to self.prime^self.prec_cap as an ``mpz_srcptr``. + Return a pointer to ``self.prime^self.prec_cap`` as an ``mpz_srcptr``. EXAMPLES:: @@ -298,7 +298,7 @@ cdef class PowComputer_class(SageObject): def _pow_mpz_t_top_test(self): """ - Tests the pow_mpz_t_top function. + Test the ``pow_mpz_t_top`` function. EXAMPLES:: @@ -317,7 +317,7 @@ cdef class PowComputer_class(SageObject): def _repr_(self): """ - Returns a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -328,7 +328,7 @@ cdef class PowComputer_class(SageObject): def _prime(self): """ - Returns the base that the PowComputer is exponentiating. + Return the base that the ``PowComputer`` is exponentiating. EXAMPLES:: @@ -340,7 +340,7 @@ cdef class PowComputer_class(SageObject): def _in_field(self): """ - Returns whether or not self is attached to a field. + Return whether or not ``self`` is attached to a field. EXAMPLES:: @@ -352,7 +352,7 @@ cdef class PowComputer_class(SageObject): def _cache_limit(self): """ - Returns the limit to which powers of prime are computed. + Return the limit to which powers of prime are computed. EXAMPLES:: @@ -367,8 +367,8 @@ cdef class PowComputer_class(SageObject): def _prec_cap(self): """ - Returns prec_cap, a single value that for which - ``self._prime()^prec_cap`` is stored + Return ``prec_cap``, a single value that for which + ``self._prime()^prec_cap`` is stored. EXAMPLES:: @@ -383,7 +383,7 @@ cdef class PowComputer_class(SageObject): def _top_power(self): """ - Returns ``self._prime()^self._prec_cap()`` + Return ``self._prime()^self._prec_cap()``. EXAMPLES:: @@ -398,7 +398,7 @@ cdef class PowComputer_class(SageObject): def __call__(self, n): """ - Returns ``self.prime^n``. + Return ``self.prime^n``. EXAMPLES:: @@ -434,14 +434,13 @@ cdef class PowComputer_class(SageObject): cdef class PowComputer_base(PowComputer_class): def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly=None, shift_seed=None): """ - Allocates a PowComputer_base. + Allocate a ``PowComputer_base``. EXAMPLES:: sage: PC = PowComputer(5, 7, 10) sage: PC(3) 125 - """ cdef Py_ssize_t i @@ -558,7 +557,7 @@ cdef class PowComputer_base(PowComputer_class): cdef mpz_srcptr pow_mpz_t_top(self) noexcept: """ - Returns a pointer to self.prime^self.prec_cap as an ``mpz_srcptr``. + Return a pointer to ``self.prime^self.prec_cap`` as an ``mpz_srcptr``. EXAMPLES:: @@ -570,7 +569,7 @@ cdef class PowComputer_base(PowComputer_class): cdef mpz_srcptr pow_mpz_t_tmp(self, long n) except NULL: """ - Computes self.prime^n. + Compute ``self.prime^n``. EXAMPLES:: @@ -580,11 +579,10 @@ cdef class PowComputer_base(PowComputer_class): sage: PC._pow_mpz_t_tmp_test(-1) Traceback (most recent call last): ... - ValueError: n must be non-negative - + ValueError: n must be nonnegative """ if n < 0: - raise ValueError("n must be non-negative") + raise ValueError("n must be nonnegative") if n <= self.cache_limit: return self.small_powers[n] if n == self.prec_cap: @@ -603,7 +601,7 @@ cdef class PowComputer_base(PowComputer_class): pow_comp_cache = {} cdef PowComputer_base PowComputer_c(Integer m, Integer cache_limit, Integer prec_cap, in_field, prec_type=None): """ - Returns a PowComputer. + Return a ``PowComputer``. EXAMPLES:: @@ -612,9 +610,9 @@ cdef PowComputer_base PowComputer_c(Integer m, Integer cache_limit, Integer prec 81 """ if cache_limit < 0: - raise ValueError("cache_limit must be non-negative") + raise ValueError("cache_limit must be nonnegative") if prec_cap < 0: - raise ValueError("prec_cap must be non-negative") + raise ValueError("prec_cap must be nonnegative") if mpz_cmp_si((prec_cap).value, maxpreccap) >= 0: raise ValueError("cannot create p-adic parents with precision cap larger than (1 << (sizeof(long)*8 - 2))") @@ -642,18 +640,17 @@ cdef PowComputer_base PowComputer_c(Integer m, Integer cache_limit, Integer prec def PowComputer(m, cache_limit, prec_cap, in_field = False, prec_type=None): r""" - Returns a PowComputer that caches the values `1, m, m^2, \ldots, m^{C}`, + Return a ``PowComputer`` that caches the values `1, m, m^2, \ldots, m^{C}`, where `C` is ``cache_limit``. - Once you create a PowComputer, merely call it to get values out. + Once you create a ``PowComputer``, merely call it to get values out. - You can input any integer, even if it's outside of the precomputed - range. + You can input any integer, even if it's outside of the precomputed range. INPUT: - * m -- An integer, the base that you want to exponentiate. - * cache_limit -- A positive integer that you want to cache powers up to. + - ``m`` -- integer; the base that you want to exponentiate + - ``cache_limit`` -- positive integer; that you want to cache powers up to EXAMPLES:: diff --git a/src/sage/rings/padics/pow_computer_ext.pyx b/src/sage/rings/padics/pow_computer_ext.pyx index 6978a9435b5..389bd0bb20d 100644 --- a/src/sage/rings/padics/pow_computer_ext.pyx +++ b/src/sage/rings/padics/pow_computer_ext.pyx @@ -8,7 +8,7 @@ """ PowComputer_ext -The classes in this file are designed to be attached to p-adic parents +The classes in this file are designed to be attached to `p`-adic parents and elements for Cython access to properties of the parent. In addition to storing the defining polynomial (as an NTL polynomial) @@ -86,7 +86,7 @@ cdef int ZZ_pX_Eis_init(PowComputer_ZZ_pX prime_pow, ntl_ZZ_pX shift_seed) excep INPUT: - ``prime_pow`` -- the PowComputer to be initialized - - ``shift_seed`` -- x^e/p as a polynomial of degree at most e-1 in x. + - ``shift_seed`` -- x^e/p as a polynomial of degree at most e-1 in x EXAMPLES:: @@ -269,7 +269,8 @@ cdef int ZZ_pX_Eis_init(PowComputer_ZZ_pX prime_pow, ntl_ZZ_pX shift_seed) excep def ZZ_pX_eis_shift_test(_shifter, _a, _n, _finalprec): """ - Shifts _a right _n x-adic digits, where x is considered modulo the polynomial in _shifter. + Shift ``_a`` right ``_n`` x-adic digits, where x is considered modulo the + polynomial in ``_shifter``. EXAMPLES:: @@ -463,7 +464,7 @@ cdef int ZZ_pX_eis_shift_p(PowComputer_ZZ_pX self, ZZ_pX_c* x, ZZ_pX_c* a, long cdef class PowComputer_ext(PowComputer_class): def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed=None): """ - Constructs the storage for powers of prime as ZZ_c's. + Construct the storage for powers of prime as ZZ_c's. EXAMPLES:: @@ -509,7 +510,7 @@ cdef class PowComputer_ext(PowComputer_class): def __repr__(self): """ - Returns a string representation of self. + Return a string representation of ``self``. EXAMPLES:: @@ -576,7 +577,7 @@ cdef class PowComputer_ext(PowComputer_class): 625 """ if n < 0: - raise ValueError("n must be non-negative") + raise ValueError("n must be nonnegative") if n <= self.cache_limit: ZZ_to_mpz(self.temp_m, &(self.small_powers[n])) elif n == self.prec_cap: @@ -613,7 +614,7 @@ cdef class PowComputer_ext(PowComputer_class): 625 """ if n < 0: - raise ValueError("n must be non-negative") + raise ValueError("n must be nonnegative") if n <= self.cache_limit: return &(self.small_powers[n]) if n == self.prec_cap: @@ -623,7 +624,7 @@ cdef class PowComputer_ext(PowComputer_class): def _pow_ZZ_tmp_test(self, n): """ - Tests the pow_ZZ_tmp function + Test the ``pow_ZZ_tmp`` function. EXAMPLES:: @@ -670,14 +671,14 @@ cdef class PowComputer_ext(PowComputer_class): m = Integer(m) n = Integer(n) if m < 0 or n < 0: - raise ValueError("m, n must be non-negative") + raise ValueError("m, n must be nonnegative") cdef ntl_ZZ ans = ntl_ZZ.__new__(ntl_ZZ) ZZ_mul(ans.x, self.pow_ZZ_tmp(mpz_get_ui((m).value))[0], self.pow_ZZ_tmp(mpz_get_ui((n).value))[0]) return ans cdef mpz_srcptr pow_mpz_t_top(self) noexcept: """ - Returns self.prime^self.prec_cap as an ``mpz_srcptr``. + Return ``self.prime^self.prec_cap`` as an ``mpz_srcptr``. EXAMPLES:: @@ -690,7 +691,7 @@ cdef class PowComputer_ext(PowComputer_class): cdef ZZ_c* pow_ZZ_top(self) noexcept: """ - Returns self.prime^self.prec_cap as a ZZ_c. + Return ``self.prime^self.prec_cap`` as a ZZ_c. EXAMPLES:: @@ -702,7 +703,7 @@ cdef class PowComputer_ext(PowComputer_class): def _pow_ZZ_top_test(self): """ - Tests the pow_ZZ_top function. + Test the ``pow_ZZ_top`` function. EXAMPLES:: @@ -716,7 +717,7 @@ cdef class PowComputer_ext(PowComputer_class): def _ram_prec_cap(self): """ - Returns the precision cap of self, considered as a power of the uniformizer. + Return the precision cap of self, considered as a power of the uniformizer. EXAMPLES:: @@ -744,7 +745,8 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def polynomial(self): """ - Returns the polynomial (with coefficient precision prec_cap) associated to this PowComputer. + Return the polynomial (with coefficient precision prec_cap) associated + to this ``PowComputer``. The polynomial is output as an ntl_ZZ_pX. @@ -762,7 +764,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef ntl_ZZ_pContext_class get_context(self, long n): """ - Returns a ZZ_pContext for self.prime^(abs(n)). + Return a ``ZZ_pContext`` for ``self.prime^(abs(n))``. EXAMPLES:: @@ -782,7 +784,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _get_context_test(self, n): """ - Returns a ZZ_pContext for self.prime^n. + Return a ``ZZ_pContext`` for ``self.prime^n``. EXAMPLES:: @@ -795,7 +797,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef ntl_ZZ_pContext_class get_context_capdiv(self, long n): """ - Returns a ZZ_pContext for self.prime^((n-1) // self.e + 1) + Return a ``ZZ_pContext`` for ``self.prime^((n-1) // self.e + 1)``. For Eisenstein extensions this gives the context used for an element of relative precision n. @@ -810,7 +812,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _get_context_capdiv_test(self, n): """ - Returns a ZZ_pContext for self.prime^((n-1) // self.e + 1) + Return a ``ZZ_pContext`` for ``self.prime^((n-1) // self.e + 1)``. For Eisenstein extensions this gives the context used for an element of relative precision n. @@ -826,12 +828,13 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def speed_test(self, n, runs): """ - Runs a speed test. + Run a speed test. INPUT: - - ``n`` -- input to a function to be tested (the function needs to be set in the source code). - - ``runs`` -- The number of runs of that function + - ``n`` -- input to a function to be tested (the function needs to be + set in the source code) + - ``runs`` -- the number of runs of that function OUTPUT: @@ -855,7 +858,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef ntl_ZZ_pContext_class get_top_context(self): """ - Returns a ZZ_pContext for self.prime^self.prec_cap + Return a ``ZZ_pContext`` for ``self.prime^self.prec_cap``. TESTS:: @@ -867,7 +870,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _get_top_context_test(self): """ - Returns a ZZ_pContext for self.prime^self.prec_cap + Return a ``ZZ_pContext`` for ``self.prime^self.prec_cap``. TESTS:: @@ -879,7 +882,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef restore_context(self, long n): """ - Restores the contest corresponding to self.prime^n + Restore the contest corresponding to ``self.prime^n``. EXAMPLES:: @@ -890,7 +893,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _restore_context_test(self, n): """ - Restores the contest corresponding to self.prime^n + Restore the contest corresponding to ``self.prime^n``. EXAMPLES:: @@ -902,7 +905,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef restore_context_capdiv(self, long n): """ - Restores the context for self.prime^((n-1) // self.e + 1) + Restore the context for ``self.prime^((n-1) // self.e + 1)``. EXAMPLES:: @@ -913,7 +916,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _restore_context_capdiv_test(self, n): """ - Restores the context for self.prime^((n-1) // self.e + 1) + Restore the context for ``self.prime^((n-1) // self.e + 1)``. EXAMPLES:: @@ -925,7 +928,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef void restore_top_context(self) noexcept: """ - Restores the context corresponding to self.prime^self.prec_cap + Restore the context corresponding to ``self.prime^self.prec_cap``. EXAMPLES:: @@ -936,7 +939,7 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _restore_top_context_test(self): """ - Restores the context corresponding to self.prime^self.prec_cap + Restore the context corresponding to ``self.prime^self.prec_cap``. EXAMPLES:: @@ -947,7 +950,8 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef ZZ_pX_Modulus_c* get_modulus(self, long n) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod self.prime^n) + Return the modulus corresponding to ``self.polynomial()`` (mod + ``self.prime^n``). EXAMPLES:: @@ -962,7 +966,8 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _get_modulus_test(self, ntl_ZZ_pX a, ntl_ZZ_pX b, Integer n): """ - Multiplies a and b modulo the modulus corresponding to self.polynomial() (mod self.prime^n). + Multiply ``a`` and ``b`` modulo the modulus corresponding to + ``self.polynomial()`` (mod ``self.prime^n``). EXAMPLES:: @@ -990,15 +995,15 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef ZZ_pX_Modulus_c* get_modulus_capdiv(self, long n) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod - self.prime^((n-1) // self.e + 1) + Return the modulus corresponding to ``self.polynomial()`` (mod + ``self.prime^((n-1) // self.e + 1``). """ return self.get_modulus(self.capdiv(n)) cdef ZZ_pX_Modulus_c* get_top_modulus(self) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod - self.prime^self.prec_cap) + Return the modulus corresponding to ``self.polynomial()`` (mod + ``self.prime^self.prec_cap``). EXAMPLES:: @@ -1013,8 +1018,8 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _get_top_modulus_test(self, ntl_ZZ_pX a, ntl_ZZ_pX b): """ - Multiplies a and b modulo the modulus corresponding to - self.polynomial() (mod self.prime^self.prec_cap) + Multiply ``a`` and ``b`` modulo the modulus corresponding to + ``self.polynomial()`` (mod ``self.prime^self.prec_cap``). EXAMPLES:: @@ -1057,9 +1062,9 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): def _capdiv_test(self, n): """ - If n >= 0 returns ceil(n / self.e) + If n >= 0, return ceil(n / self.e). - If n < 0 returns ceil(-n / self.e) + If n < 0, return ceil(-n / self.e). EXAMPLES:: @@ -1082,30 +1087,30 @@ cdef class PowComputer_ZZ_pX(PowComputer_ext): cdef int teichmuller_set_c (self, ZZ_pX_c* x, ZZ_pX_c* a, long absprec) except -1: r""" - Sets x to the Teichmuller lift congruent to a modulo the + Set `x` to the Teichmuller lift congruent to a modulo the uniformizer, ie such that `x = a \mod \pi` and `x^q = x \mod \pi^{\mbox{absprec}}`. If `a = 0 \mod \pi` this function does nothing and returns 1. Otherwise returns 0. - x should be created with context p^absprec. + `x` should be created with context p^absprec. - Does not affect self. + Does not affect ``self``. INPUT: - - ``x`` -- The ``ZZ_pX_c`` to be set + - ``x`` -- the ``ZZ_pX_c`` to be set - - ``a`` -- A ``ZZ_pX_c`` ``currently holding an approximation to the + - ``a`` -- a ``ZZ_pX_c`` ``currently holding an approximation to the Teichmuller representative (this approximation can be any - integer). It will be set to the actual Teichmuller lift + integer). It will be set to the actual Teichmuller lift. - ``absprec`` -- the desired precision of the Teichmuller lift OUTPUT: - - 1 -- x should be set to zero + - 1 -- `x` should be set to zero - 0 -- normal EXAMPLES:: @@ -1212,13 +1217,13 @@ cdef class PowComputer_ZZ_pX_FM(PowComputer_ZZ_pX): r""" This class only caches a context and modulus for p^prec_cap. - Designed for use with fixed modulus p-adic rings, in Eisenstein + Designed for use with fixed modulus `p`-adic rings, in Eisenstein and unramified extensions of `\ZZ_p`. """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed = None): """ - Caches a context and modulus for prime^prec_cap + Caches a context and modulus for ``prime^prec_cap``. EXAMPLES:: @@ -1250,7 +1255,7 @@ cdef class PowComputer_ZZ_pX_FM(PowComputer_ZZ_pX): cdef ntl_ZZ_pContext_class get_top_context(self): """ - Returns a ZZ_pContext for self.prime^self.prec_cap + Return a ``ZZ_pContext`` for ``self.prime^self.prec_cap``. EXAMPLES:: @@ -1262,7 +1267,7 @@ cdef class PowComputer_ZZ_pX_FM(PowComputer_ZZ_pX): cdef void restore_top_context(self) noexcept: """ - Restores the context corresponding to self.prime^self.prec_cap + Restore the context corresponding to ``self.prime^self.prec_cap``. EXAMPLES:: @@ -1273,7 +1278,8 @@ cdef class PowComputer_ZZ_pX_FM(PowComputer_ZZ_pX): cdef ZZ_pX_Modulus_c* get_top_modulus(self) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod self.prime^self.prec_cap) + Return the modulus corresponding to ``self.polynomial()`` + (mod ``self.prime^self.prec_cap``). EXAMPLES:: @@ -1307,12 +1313,13 @@ cdef class PowComputer_ZZ_pX_FM(PowComputer_ZZ_pX): cdef class PowComputer_ZZ_pX_FM_Eis(PowComputer_ZZ_pX_FM): """ - This class computes and stores low_shifter and high_shifter, which aid in right shifting elements. + This class computes and stores ``low_shifter`` and ``high_shifter``, which aid in right shifting elements. """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed = None): """ - Calls Eis_init, which initializes high_shifter and low_shifter. + Call ``Eis_init``, which initializes ``high_shifter`` and + ``low_shifter``. TESTS:: @@ -1411,7 +1418,7 @@ cdef class PowComputer_ZZ_pX_FM_Eis(PowComputer_ZZ_pX_FM): def __dealloc__(self): """ - Deallocates low_shifter and high_shifter. + Deallocate ``low_shifter`` and ``high_shifter``. TESTS:: @@ -1423,8 +1430,8 @@ cdef class PowComputer_ZZ_pX_FM_Eis(PowComputer_ZZ_pX_FM): cdef void cleanup_ZZ_pX_FM_Eis(self) noexcept: """ - Does the actual work of deallocating low_shifter and - high_shifter. + Do the actual work of deallocating ``low_shifter`` and + ``high_shifter``. TESTS:: @@ -1436,9 +1443,10 @@ cdef class PowComputer_ZZ_pX_FM_Eis(PowComputer_ZZ_pX_FM): cdef int eis_shift(self, ZZ_pX_c* x, ZZ_pX_c* a, long n, long finalprec) except -1: """ - Shifts a right n pi-adic digits, where pi is considered modulo the polynomial in self. + Shift ``a`` right ``n`` pi-adic digits, where pi is considered modulo + the polynomial in ``self``. - Puts the result in x. + Puts the result in ``x``. EXAMPLES:: @@ -1534,7 +1542,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): This class caches contexts and moduli densely between 1 and cache_limit. It requires cache_limit == prec_cap. It is intended for use with capped relative and capped absolute rings and fields, in Eisenstein and unramified - extensions of the base p-adic fields. + extensions of the base `p`-adic fields. """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed = None): @@ -1599,7 +1607,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): def __dealloc__(self): """ - Deallocates cache of contexts, moduli. + Deallocate cache of contexts, moduli. EXAMPLES:: @@ -1611,7 +1619,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): cdef void cleanup_ZZ_pX_small(self) noexcept: """ - Deallocates cache of contexts, moduli. + Deallocate cache of contexts, moduli. EXAMPLES:: @@ -1627,11 +1635,9 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): INPUT: - - ``n`` -- A nonzero long - - OUTPUT: + - ``n`` -- nonzero long - - A context for p^n + OUTPUT: a context for p^n EXAMPLES:: @@ -1653,7 +1659,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): INPUT: - - ``n`` -- A nonzero long + - ``n`` -- nonzero long EXAMPLES:: @@ -1669,7 +1675,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): cdef ntl_ZZ_pContext_class get_top_context(self): """ - Returns a ZZ_pContext for self.prime^self.prec_cap + Return a ``ZZ_pContext`` for ``self.prime^self.prec_cap``. EXAMPLES:: @@ -1681,7 +1687,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): cdef void restore_top_context(self) noexcept: """ - Restores the context corresponding to self.prime^self.prec_cap + Restore the context corresponding to ``self.prime^self.prec_cap``. EXAMPLES:: @@ -1692,11 +1698,12 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): cdef ZZ_pX_Modulus_c* get_modulus(self, long n) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod self.prime^n). + Return the modulus corresponding to ``self.polynomial()`` (mod + ``self.prime^n``). INPUT: - - ``n`` -- A long between 1 and ``self.cache_limit``, inclusive. + - ``n`` -- a long between 1 and ``self.cache_limit``, inclusive. If `n` is larger, this function will return ``self.mod[prec_cap]`` lifted to that precision. @@ -1720,7 +1727,8 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): cdef ZZ_pX_Modulus_c* get_top_modulus(self) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod self.prime^self.prec_cap) + Return the modulus corresponding to ``self.polynomial()`` + (mod ``self.prime^self.prec_cap``). EXAMPLES:: @@ -1734,7 +1742,7 @@ cdef class PowComputer_ZZ_pX_small(PowComputer_ZZ_pX): cdef class PowComputer_ZZ_pX_small_Eis(PowComputer_ZZ_pX_small): """ - This class computes and stores low_shifter and high_shifter, which aid in right shifting elements. + This class computes and stores ``low_shifter`` and ``high_shifter``, which aid in right shifting elements. These are only stored at maximal precision: in order to get lower precision versions just reduce mod p^n. """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed = None): @@ -1842,7 +1850,7 @@ cdef class PowComputer_ZZ_pX_small_Eis(PowComputer_ZZ_pX_small): def __dealloc__(self): """ - Deallocates low_shifter and high_shifter. + Deallocate ``low_shifter`` and ``high_shifter``. TESTS:: @@ -1854,8 +1862,8 @@ cdef class PowComputer_ZZ_pX_small_Eis(PowComputer_ZZ_pX_small): cdef void cleanup_ZZ_pX_small_Eis(self) noexcept: """ - Does the actual work of deallocating low_shifter and - high_shifter. + Do the actual work of deallocating ``low_shifter`` and + ``high_shifter``. TESTS:: @@ -1867,9 +1875,10 @@ cdef class PowComputer_ZZ_pX_small_Eis(PowComputer_ZZ_pX_small): cdef int eis_shift(self, ZZ_pX_c* x, ZZ_pX_c* a, long n, long finalprec) except -1: """ - Shifts a right n pi-adic digits, where pi is considered modulo the polynomial in self. + Shift ``a`` right ``n`` pi-adic digits, where pi is considered modulo + the polynomial in ``self``. - Puts the result in x. + Puts the result in ``x``. EXAMPLES:: @@ -1965,7 +1974,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): def __dealloc__(self): """ - Deallocates the stored moduli and contexts. + Deallocate the stored moduli and contexts. EXAMPLES:: @@ -1977,7 +1986,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef void cleanup_ZZ_pX_big(self) noexcept: """ - Deallocates the stored moduli and contexts. + Deallocate the stored moduli and contexts. EXAMPLES:: @@ -1988,7 +1997,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): def reset_dictionaries(self): """ - Resets the dictionaries. Note that if there are elements + Reset the dictionaries. Note that if there are elements lying around that need access to these dictionaries, calling this function and then doing arithmetic with those elements could cause trouble (if the context object gets garbage @@ -2012,7 +2021,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): def _context_dict(self): """ - Returns the context dictionary. + Return the context dictionary. EXAMPLES:: @@ -2025,7 +2034,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): def _modulus_dict(self): """ - Returns the context dictionary. + Return the context dictionary. EXAMPLES:: @@ -2044,15 +2053,13 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef ntl_ZZ_pContext_class get_context(self, long n): """ - Returns the context for p^n. + Return the context for p^n. INPUT: - - ``n`` -- A nonzero long + - ``n`` -- nonzero long - OUTPUT: - - - A context for p^n + OUTPUT: a context for p^n EXAMPLES:: @@ -2080,7 +2087,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef ntl_ZZ_pContext_class get_top_context(self): """ - Returns a ZZ_pContext for self.prime^self.prec_cap + Return a ``ZZ_pContext`` for ``self.prime^self.prec_cap``. EXAMPLES:: @@ -2092,7 +2099,7 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef void restore_top_context(self) noexcept: """ - Restores the context corresponding to self.prime^self.prec_cap + Restore the context corresponding to ``self.prime^self.prec_cap``. EXAMPLES:: @@ -2103,11 +2110,12 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef ZZ_pX_Modulus_c* get_modulus(self, long n) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod self.prime^n). + Return the modulus corresponding to ``self.polynomial()`` (mod + ``self.prime^n``). INPUT: - - ``n`` -- A nonzero long + - ``n`` -- nonzero long EXAMPLES:: @@ -2150,7 +2158,8 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef ZZ_pX_Modulus_c* get_top_modulus(self) noexcept: """ - Returns the modulus corresponding to self.polynomial() (mod self.prime^self.prec_cap) + Return the modulus corresponding to ``self.polynomial()`` + (mod ``self.prime^self.prec_cap``). EXAMPLES:: @@ -2164,8 +2173,10 @@ cdef class PowComputer_ZZ_pX_big(PowComputer_ZZ_pX): cdef class PowComputer_ZZ_pX_big_Eis(PowComputer_ZZ_pX_big): """ - This class computes and stores low_shifter and high_shifter, which aid in right shifting elements. - These are only stored at maximal precision: in order to get lower precision versions just reduce mod p^n. + This class computes and stores ``low_shifter`` and ``high_shifter``, which + aid in right shifting elements. + These are only stored at maximal precision: in order to get lower precision + versions just reduce mod p^n. """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed = None): """ @@ -2272,7 +2283,7 @@ cdef class PowComputer_ZZ_pX_big_Eis(PowComputer_ZZ_pX_big): def __dealloc__(self): """ - Deallocates low_shifter and high_shifter. + Deallocate ``low_shifter`` and ``high_shifter``. TESTS:: @@ -2284,8 +2295,8 @@ cdef class PowComputer_ZZ_pX_big_Eis(PowComputer_ZZ_pX_big): cdef void cleanup_ZZ_pX_big_Eis(self) noexcept: """ - Does the actual work of deallocating low_shifter and - high_shifter. + Do the actual work of deallocating ``low_shifter`` and + ``high_shifter``. TESTS:: @@ -2297,9 +2308,10 @@ cdef class PowComputer_ZZ_pX_big_Eis(PowComputer_ZZ_pX_big): cdef int eis_shift(self, ZZ_pX_c* x, ZZ_pX_c* a, long n, long finalprec) except -1: """ - Shifts a right n pi-adic digits, where pi is considered modulo the polynomial in self. + Shift ``a`` right ``n`` pi-adic digits, where pi is considered modulo + the polynomial in ``self``. - Puts the result in x. + Puts the result in ``x``. EXAMPLES:: @@ -2325,37 +2337,37 @@ cdef class PowComputer_ZZ_pX_big_Eis(PowComputer_ZZ_pX_big): def PowComputer_ext_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly, prec_type = "small", ext_type = "u", shift_seed = None): r""" - Returns a PowComputer that caches the values `1, p, p^2, \ldots, p^C`, + Return a ``PowComputer`` that caches the values `1, p, p^2, \ldots, p^C`, where `C` is ``cache_limit``. - Once you create a PowComputer, merely call it to get values out. + Once you create a ``PowComputer``, merely call it to get values out. You can input any integer, even if it's outside of the precomputed range. INPUT: - - ``prime`` -- An integer, the base that you want to exponentiate. + - ``prime`` -- integer; the base that you want to exponentiate - - ``cache_limit`` -- A positive integer that you want to cache - powers up to. + - ``cache_limit`` -- positive integer that you want to cache + powers up to - - ``prec_cap`` -- The cap on precisions of elements. For ramified + - ``prec_cap`` -- the cap on precisions of elements. For ramified extensions, p^((prec_cap - 1) // e) will be the largest - power of p distinguishable from zero + power of p distinguishable from zero. - - ``in_field`` -- Boolean indicating whether this PowComputer is - attached to a field or not. + - ``in_field`` -- boolean indicating whether this PowComputer is + attached to a field or not - - ``poly`` -- An ``ntl_ZZ_pX`` or ``ntl_ZZ_pEX`` defining the extension. - It should be defined modulo p^((prec_cap - 1) // e + 1) + - ``poly`` -- an ``ntl_ZZ_pX`` or ``ntl_ZZ_pEX`` defining the extension. + It should be defined modulo ``p^((prec_cap - 1) // e + 1)``. - - ``prec_type`` -- 'FM', 'small', or 'big', defining how caching - is done. + - ``prec_type`` -- ``'FM'``, ``'small'``, or ``'big'``, defining how + caching is done - - ``ext_type`` -- 'u' = unramified, 'e' = Eisenstein, 't' = + - ``ext_type`` -- ``'u'`` = unramified, ``'e'`` = Eisenstein, ``'t'`` = two-step - ``shift_seed`` -- (required only for Eisenstein and two-step) - For Eisenstein and two-step extensions, if f = a_n x^n - p + for Eisenstein and two-step extensions, if f = a_n x^n - p a_{n-1} x^{n-1} - ... - p a_0 with a_n a unit, then shift_seed should be 1/a_n (a_{n-1} x^{n-1} + ... + a_0) diff --git a/src/sage/rings/padics/pow_computer_flint.pyx b/src/sage/rings/padics/pow_computer_flint.pyx index 79f5a971e55..cac2d70d758 100644 --- a/src/sage/rings/padics/pow_computer_flint.pyx +++ b/src/sage/rings/padics/pow_computer_flint.pyx @@ -42,7 +42,6 @@ cdef class PowComputer_flint(PowComputer_class): sage: from sage.rings.padics.pow_computer_flint import PowComputer_flint sage: type(PowComputer_flint(5, 20, 20, 20, False)) - """ # fmpz_init does not allocate memory fmpz_init(self.fprime) @@ -71,7 +70,6 @@ cdef class PowComputer_flint(PowComputer_class): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_maker(5, 20, 20, 20, False, f, 'capped-rel') # indirect doctest sage: TestSuite(A).run() - """ PowComputer_class.__init__(self, prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly, shift_seed) @@ -105,7 +103,6 @@ cdef class PowComputer_flint(PowComputer_class): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_maker(5, 20, 20, 20, False, f, 'capped-rel') # indirect doctest sage: A._test_pickling() # indirect doctest - """ return PowComputer_flint_maker, (self.prime, self.cache_limit, self.prec_cap, self.ram_prec_cap, self.in_field, self.polynomial(), self._prec_type) @@ -123,7 +120,7 @@ cdef class PowComputer_flint(PowComputer_class): cdef fmpz_t* pow_fmpz_t_tmp(self, unsigned long n) except NULL: """ - Returns a pointer to a FLINT ``fmpz_t`` holding `p^n`. + Return a pointer to a FLINT ``fmpz_t`` holding `p^n`. Analogous to :meth:`sage.rings.padics.pow_computer.PowComputer_class.pow_mpz_t_tmp` @@ -140,7 +137,7 @@ cdef class PowComputer_flint(PowComputer_class): cdef mpz_srcptr pow_mpz_t_tmp(self, long n) except NULL: """ - Returns a pointer to an ``mpz_t`` holding `p^n`. + Return a pointer to an ``mpz_t`` holding `p^n`. See :meth:`sage.rings.padics.pow_computer.PowComputer_class.pow_mpz_t_tmp` @@ -151,14 +148,14 @@ cdef class PowComputer_flint(PowComputer_class): cdef mpz_srcptr pow_mpz_t_top(self) noexcept: """ - Returns a pointer to an ``mpz_t`` holding `p^N`, where `N` is + Return a pointer to an ``mpz_t`` holding `p^N`, where `N` is the precision cap. """ return self.top_power cdef unsigned long capdiv(self, unsigned long n) noexcept: """ - Returns ceil(n / e). + Return ceil(n / e). """ if self.e == 1: return n if n == 0: return 0 @@ -166,7 +163,7 @@ cdef class PowComputer_flint(PowComputer_class): def polynomial(self, n=None, var='x'): """ - Returns ``None``. + Return ``None``. For consistency with subclasses. @@ -176,7 +173,6 @@ cdef class PowComputer_flint(PowComputer_class): sage: A = PowComputer_flint(5, 20, 20, 20, False, None) sage: A.polynomial() is None True - """ return None @@ -192,7 +188,6 @@ cdef class PowComputer_flint_1step(PowComputer_flint): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_1step(5, 20, 20, 20, False, f); A FLINT PowComputer for 5 with polynomial x^3 - 8*x - 2 - """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, _poly): """ @@ -205,7 +200,6 @@ cdef class PowComputer_flint_1step(PowComputer_flint): sage: A = PowComputer_flint_1step(5, 20, 20, 20, False, f) sage: type(A) - """ cdef Polynomial_integer_dense_flint poly = _poly cdef long length = fmpz_poly_length(poly._poly) @@ -263,7 +257,6 @@ cdef class PowComputer_flint_1step(PowComputer_flint): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_maker(5, 20, 20, 20, False, f, 'capped-rel') sage: TestSuite(A).run() - """ PowComputer_flint.__init__(self, prime, cache_limit, prec_cap, ram_prec_cap, in_field, _poly, shift_seed) @@ -387,7 +380,7 @@ cdef class PowComputer_flint_1step(PowComputer_flint): cdef fmpz_poly_t* get_modulus_capdiv(self, unsigned long k) noexcept: """ - Returns the defining polynomial reduced modulo `p^a`, where + Return the defining polynomial reduced modulo `p^a`, where `a` is the ceiling of `k/e`. The same warnings apply as for @@ -397,14 +390,15 @@ cdef class PowComputer_flint_1step(PowComputer_flint): def polynomial(self, _n=None, var='x'): """ - Returns the polynomial attached to this ``PowComputer``, possibly reduced modulo a power of `p`. + Return the polynomial attached to this ``PowComputer``, possibly + reduced modulo a power of `p`. INPUT: - - ``_n`` -- (default ``None``) an integer, the power of `p` - modulo which to reduce. + - ``_n`` -- (default: ``None``) an integer, the power of `p` + modulo which to reduce - - ``var`` -- (default ``'x'``) the variable for the returned polynomial + - ``var`` -- (default: ``'x'``) the variable for the returned polynomial .. NOTE:: @@ -434,7 +428,7 @@ cdef class PowComputer_flint_1step(PowComputer_flint): cdef _new_fmpz_poly(self, fmpz_poly_t value, var='x'): """ - Returns a polynomial with the value stored in ``value`` and + Return a polynomial with the value stored in ``value`` and variable name ``var``. """ R = ZZ[var] @@ -455,7 +449,6 @@ cdef class PowComputer_flint_unram(PowComputer_flint_1step): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_unram(5, 20, 20, 20, False, f); A FLINT PowComputer for 5 with polynomial x^3 - 8*x - 2 - """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, _poly, shift_seed=None): """ @@ -468,7 +461,6 @@ cdef class PowComputer_flint_unram(PowComputer_flint_1step): sage: A = PowComputer_flint_unram(5, 20, 20, 20, False, f) sage: type(A) - """ # fmpz_init does not allocate memory fmpz_init(self.fmpz_ccmp) @@ -513,7 +505,6 @@ cdef class PowComputer_flint_unram(PowComputer_flint_1step): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_unram(5, 20, 20, 20, False, f) sage: del A - """ if self._allocated >= 16: fmpz_clear(self.fmpz_ccmp) @@ -548,7 +539,6 @@ cdef class PowComputer_flint_unram(PowComputer_flint_1step): sage: R. = ZZ[]; f = x^3 - 8*x - 2 sage: A = PowComputer_flint_maker(5, 20, 20, 20, False, f, 'capped-rel') sage: TestSuite(A).run() - """ PowComputer_flint_1step.__init__(self, prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly) @@ -580,7 +570,6 @@ cdef class PowComputer_flint_eis(PowComputer_flint_1step): sage: A = PowComputer_flint_eis(5, 20, 20, 60, False, f) sage: type(A) - """ PowComputer_flint_1step.__init__(self, prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly) @@ -597,16 +586,16 @@ def PowComputer_flint_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_field - ``prime`` -- an integral prime - - ``cache_limit`` -- a non-negative integer, controlling the + - ``cache_limit`` -- nonnegative integer, controlling the caching. Powers of ``prime``, reductions of ``poly`` modulo different powers of ``prime`` and inverses of the leading coefficient modulo different powers of ``prime`` are cached. Additional data is cached for ramified extensions. - ``prec_cap`` -- the power of `p` modulo which elements of - largest precision are defined. + largest precision are defined - - ``ram_prec_cap`` -- Approximately ``e*prec_cap``, where ``e`` is + - ``ram_prec_cap`` -- approximately ``e*prec_cap``, where ``e`` is the ramification degree of the extension. For a ramified extension this is what Sage calls the precision cap of the ring. In fact, it's possible to have rings with precision cap not a @@ -615,12 +604,12 @@ def PowComputer_flint_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_field ``prec_cap = ceil(n/e)`` - ``in_field`` -- (boolean) whether the associated ring is - actually a field. + actually a field - - ``poly`` -- the polynomial defining the extension. + - ``poly`` -- the polynomial defining the extension - - `prec_type`` -- one of ``"capped-rel"``, ``"capped-abs"`` or - ``"fixed-mod"``, the precision type of the ring. + - ``prec_type`` -- one of ``'capped-rel'``, ``'capped-abs'`` or + ``'fixed-mod'``; the precision type of the ring .. NOTE:: @@ -639,7 +628,6 @@ def PowComputer_flint_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_field sage: A = PowComputer_flint_maker(3, 20, 20, 20, False, x^3 + 2*x + 1, 'fixed-mod'); type(A) - """ if prec_type == 'capped-rel': from sage.rings.padics.qadic_flint_CR import PowComputer_ diff --git a/src/sage/rings/padics/pow_computer_relative.pyx b/src/sage/rings/padics/pow_computer_relative.pyx index 2de1fa5688b..de2e85e6c85 100644 --- a/src/sage/rings/padics/pow_computer_relative.pyx +++ b/src/sage/rings/padics/pow_computer_relative.pyx @@ -53,7 +53,6 @@ cdef class PowComputer_relative(PowComputer_class): sage: from sage.rings.padics.pow_computer_relative import PowComputer_relative sage: isinstance(PC, PowComputer_relative) # needs sage.libs.flint True - """ def __cinit__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed): r""" @@ -67,7 +66,6 @@ cdef class PowComputer_relative(PowComputer_class): sage: RFP = R.change(field=False, show_prec=False, type='floating-point') sage: shift_seed = (-f[:3] // 5).change_ring(RFP) sage: PC = PowComputer_relative_maker(3, 20, 20, 60, False, f, shift_seed, 'fixed-mod') - """ self._allocated = 4 @@ -83,7 +81,6 @@ cdef class PowComputer_relative(PowComputer_class): sage: shift_seed = (-f[:3] // 5).change_ring(RFP) sage: PC = PowComputer_relative_maker(5, 20, 20, 60, False, f, shift_seed, 'fixed-mod') # indirect doctest sage: TestSuite(PC).run() - """ PowComputer_class.__init__(self, prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly, shift_seed) self.e = poly.degree() * poly.base_ring().absolute_e() @@ -115,7 +112,6 @@ cdef class PowComputer_relative(PowComputer_class): sage: shift_seed = (-f[:3] // 5).change_ring(RFP) sage: PC = PowComputer_relative_maker(5, 20, 20, 60, False, f, shift_seed, 'fixed-mod') sage: del PC - """ def __reduce__(self): @@ -152,7 +148,6 @@ cdef class PowComputer_relative(PowComputer_class): sage: shift_seed = (-f[:3] // 5).change_ring(RFP) sage: PowComputer_relative_maker(5, 20, 20, 60, False, f, shift_seed, 'fixed-mod') # indirect doctest Relative PowComputer for modulus x^3 + 5*x + a*5 - """ return "Relative PowComputer for modulus %s" % (self.modulus,) @@ -182,14 +177,13 @@ cdef class PowComputer_relative(PowComputer_class): sage: PC = PowComputer_relative_maker(5, 20, 20, 60, False, f, shift_seed, 'fixed-mod') # indirect doctest sage: PC.polynomial() is f True - """ return self.modulus cdef class PowComputer_relative_eis(PowComputer_relative): r""" - A ``PowComputer`` for a relative extension defined by an Eisenstein polynomial + A ``PowComputer`` for a relative extension defined by an Eisenstein polynomial. For a description of inputs see :func:`PowComputer_relative_maker`. @@ -207,7 +201,6 @@ cdef class PowComputer_relative_eis(PowComputer_relative): sage: isinstance(PC, PowComputer_relative_eis) # needs sage.libs.flint True - """ def __init__(self, Integer prime, long cache_limit, long prec_cap, long ram_prec_cap, bint in_field, poly, shift_seed): r""" @@ -221,7 +214,6 @@ cdef class PowComputer_relative_eis(PowComputer_relative): sage: shift_seed = (-f[:3] // 5).change_ring(RFP) sage: PC = PowComputer_relative_maker(5, 20, 20, 60, False, f, shift_seed, 'fixed-mod') sage: TestSuite(PC).run() - """ PowComputer_relative.__init__(self, prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly, shift_seed) self._inv_shift_seed = self.invert(shift_seed, self.ram_prec_cap) @@ -235,11 +227,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): - ``a`` -- a `p`-adic element, represented as a reduced Polynomial in ``poly_ring`` - - ```prec`` -- a ``long``, the required precision + - ``prec`` -- a ``long``, the required precision - OUTPUT: - - A polynomial ``b`` such that ``a*b`` is one modulo `π^\mathrm{prec}` + OUTPUT: a polynomial ``b`` such that ``a*b`` is one modulo `π^\mathrm{prec}` EXAMPLES:: @@ -283,11 +273,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): INPUT: - - ``r`` -- an integer with 0 <= r < e - - OUTPUT: + - ``r`` -- integer with 0 <= r < e - A reduced polynomial in π + OUTPUT: a reduced polynomial in π EXAMPLES:: @@ -297,10 +285,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): sage: W. = R.ext(f) sage: elt = W.prime_pow.px_pow(2); elt ((4*a + 4) + (4*a + 1)*5 + (4*a + 2)*5^2)*x^2 + ((2*a + 3) + (2*a + 4)*5 + (2*a + 4)*5^2)*x + (a + 1)*5 + 3*5^2 + 2*5^3 - """ if r < 0: - raise ValueError("r must be non-negative") + raise ValueError("r must be nonnegative") elif r == 0: return self.poly_ring(self.base_ring.uniformizer()) elif r >= self.e: @@ -316,11 +303,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): INPUT: - - ``r`` -- a non-negative integer - - OUTPUT: + - ``r`` -- nonnegative integer - A reduced polynomial in π + OUTPUT: a reduced polynomial in π EXAMPLES:: @@ -330,10 +315,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): sage: W. = R.ext(f) sage: elt = W.prime_pow.pxe_pow(2); elt ((4*a + 2) + (a + 4)*5 + 2*a*5^2)*x^2 + ((a + 2) + (a + 2)*5 + (2*a + 4)*5^2)*x + (a + 1) + (3*a + 2)*5 + (2*a + 2)*5^2 - """ if r < 0: - raise ValueError("r must be non-negative") + raise ValueError("r must be nonnegative") elif r == 0: return self.poly_ring.one() elif r == 1: @@ -350,11 +334,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): INPUT: - - ``r`` -- a non-negative integer - - OUTPUT: + - ``r`` -- nonnegative integer - A reduced polynomial in π + OUTPUT: a reduced polynomial in π EXAMPLES:: @@ -364,10 +346,9 @@ cdef class PowComputer_relative_eis(PowComputer_relative): sage: W. = R.ext(f) sage: W.prime_pow.uniformizer_pow(2) x^2 - """ if r < 0: - raise ValueError("r must be non-negative") + raise ValueError("r must be nonnegative") elif r == 0: return self.poly_ring.one() elif r < self.e: @@ -386,8 +367,8 @@ def PowComputer_relative_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_fi - ``prime`` -- a uniformizer in the base ring - - ``cache_limit`` -- a non-negative integer, controlling the caching. The - ``PowComputer`` caches frequently used things like powers of ``prime``. + - ``cache_limit`` -- nonnegative integer, controlling the caching. The + ``PowComputer`` caches frequently used things like powers of ``prime`` This parameter, e.g., controls up to which power these are cached. - ``prec_cap`` -- the power of ``prime`` modulo which elements of largest @@ -400,13 +381,13 @@ def PowComputer_relative_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_fi `e`, in which case the actual relationship between ``ram_prec_cap`` and ``prec_cap`` is that ``prec_cap = ceil(n/e)`` - - ``in_field`` -- a boolean; whether the associated ring is actually a + - ``in_field`` -- boolean; whether the associated ring is actually a field - ``poly`` -- the polynomial defining the extension - - `prec_type`` -- one of ``"capped-rel"``, ``"capped-abs"`` or - ``"fixed-mod"``, ``"floating-point"``, the precision type of the ring + - ``prec_type`` -- one of ``'capped-rel'``, ``'capped-abs'`` or + ``'fixed-mod'``, ``'floating-point'``; the precision type of the ring .. NOTE:: @@ -426,7 +407,6 @@ def PowComputer_relative_maker(prime, cache_limit, prec_cap, ram_prec_cap, in_fi sage: PC = W.prime_pow # indirect doctest sage: PC Relative PowComputer for modulus x^3 + (4*5 + 4*5^2)*x + 4*a*5 + 4*a*5^2 - """ PC = PowComputer_relative_eis(prime, cache_limit, prec_cap, ram_prec_cap, in_field, poly, shift_seed) # We have to set this here because the signature of __cinit__ in PowComputer_base doesn't allow for prec_type to be passed. diff --git a/src/sage/rings/padics/precision_error.py b/src/sage/rings/padics/precision_error.py index a536fa1a104..e7ef94f949b 100644 --- a/src/sage/rings/padics/precision_error.py +++ b/src/sage/rings/padics/precision_error.py @@ -2,7 +2,7 @@ Precision Error The errors in this file indicate various styles of precision problems -that can go wrong for p-adics and power series. +that can go wrong for `p`-adics and power series. AUTHORS: diff --git a/src/sage/rings/padics/qadic_flint_CA.pyx b/src/sage/rings/padics/qadic_flint_CA.pyx index a2a65359edc..36d3df419d0 100644 --- a/src/sage/rings/padics/qadic_flint_CA.pyx +++ b/src/sage/rings/padics/qadic_flint_CA.pyx @@ -83,13 +83,13 @@ cdef class qAdicCappedAbsoluteElement(CAElement): Return the element with the same reduction mod p that can be expressed with coefficients between 0 and p-1. The absolute precision will be maximal. - This method is used in printing and computing p-adic expansions. + This method is used in printing and computing `p`-adic expansions. INPUT: - - ``use_smallest_mode`` -- if True, use reps between -p/2 and p/2 instead. - - ``return_list`` -- if True, return a list of coefficients (as integers). - For use in printing. + - ``use_smallest_mode`` -- if ``True``, use reps between -p/2 and p/2 instead + - ``return_list`` -- if ``True``, return a list of coefficients (as integers); + for use in printing EXAMPLES:: @@ -110,8 +110,8 @@ cdef class qAdicCappedAbsoluteElement(CAElement): def __hash__(self): r""" - Raise a ``TypeError`` since this element is not hashable - (:issue:`11895`.) + Raise a :exc:`TypeError` since this element is not hashable + (:issue:`11895`). TESTS:: @@ -120,7 +120,6 @@ cdef class qAdicCappedAbsoluteElement(CAElement): Traceback (most recent call last): ... TypeError: unhashable type: 'sage.rings.padics.qadic_flint_CA.qAdicCappedAbsoluteElement' - """ # Eventually, hashing will be disabled for all (non-fixed-mod) p-adic # elements (#11895), until then, we only to this for types which did diff --git a/src/sage/rings/padics/qadic_flint_CR.pyx b/src/sage/rings/padics/qadic_flint_CR.pyx index 8f7f268b60e..a13d135ae18 100644 --- a/src/sage/rings/padics/qadic_flint_CR.pyx +++ b/src/sage/rings/padics/qadic_flint_CR.pyx @@ -118,13 +118,13 @@ cdef class qAdicCappedRelativeElement(CRElement): Return the element with the same reduction mod p that can be expressed with coefficients between 0 and p-1. The absolute precision will be maximal. - This method is used in printing and computing p-adic expansions. + This method is used in printing and computing `p`-adic expansions. INPUT: - - ``use_smallest_mode`` -- if True, use reps between -p/2 and p/2 instead. - - ``return_list`` -- if True, return a list of coefficients (as integers). - For use in printing. + - ``use_smallest_mode`` -- if ``True``, use reps between -p/2 and p/2 instead + - ``return_list`` -- if ``True``, return a list of coefficients (as integers); + for use in printing EXAMPLES:: @@ -152,8 +152,8 @@ cdef class qAdicCappedRelativeElement(CRElement): def __hash__(self): r""" - Raise a ``TypeError`` since this element is not hashable - (:issue:`11895`.) + Raise a :exc:`TypeError` since this element is not hashable + (:issue:`11895`). TESTS:: @@ -162,7 +162,6 @@ cdef class qAdicCappedRelativeElement(CRElement): Traceback (most recent call last): ... TypeError: unhashable type: 'sage.rings.padics.qadic_flint_CR.qAdicCappedRelativeElement' - """ # Eventually, hashing will be disabled for all (non-fixed-mod) p-adic # elements (#11895), until then, we only to this for types which did diff --git a/src/sage/rings/padics/qadic_flint_FM.pyx b/src/sage/rings/padics/qadic_flint_FM.pyx index 0a5e0563101..c0aebfb8bc6 100644 --- a/src/sage/rings/padics/qadic_flint_FM.pyx +++ b/src/sage/rings/padics/qadic_flint_FM.pyx @@ -83,13 +83,13 @@ cdef class qAdicFixedModElement(FMElement): Return the element with the same reduction mod p that can be expressed with coefficients between 0 and p-1. The absolute precision will be maximal. - This method is used in printing and computing p-adic expansions. + This method is used in printing and computing `p`-adic expansions. INPUT: - - ``use_smallest_mode`` -- if True, use reps between -p/2 and p/2 instead. - - ``return_list`` -- if True, return a list of coefficients (as integers). - For use in printing. + - ``use_smallest_mode`` -- if ``True``, use reps between -p/2 and p/2 instead + - ``return_list`` -- if ``True``, return a list of coefficients (as integers); + for use in printing EXAMPLES:: diff --git a/src/sage/rings/padics/qadic_flint_FP.pyx b/src/sage/rings/padics/qadic_flint_FP.pyx index 2d080dba429..0461e562a6b 100644 --- a/src/sage/rings/padics/qadic_flint_FP.pyx +++ b/src/sage/rings/padics/qadic_flint_FP.pyx @@ -113,13 +113,13 @@ cdef class qAdicFloatingPointElement(FPElement): Return the element with the same reduction mod p that can be expressed with coefficients between 0 and p-1. The absolute precision will be maximal. - This method is used in printing and computing p-adic expansions. + This method is used in printing and computing `p`-adic expansions. INPUT: - - ``use_smallest_mode`` -- if True, use reps between -p/2 and p/2 instead. - - ``return_list`` -- if True, return a list of coefficients (as integers). - For use in printing. + - ``use_smallest_mode`` -- if ``True``, use reps between -p/2 and p/2 instead + - ``return_list`` -- if ``True``, return a list of coefficients (as integers); + for use in printing EXAMPLES:: @@ -146,8 +146,8 @@ cdef class qAdicFloatingPointElement(FPElement): def __hash__(self): r""" - Raise a ``TypeError`` since this element is not hashable - (:issue:`11895`.) + Raise a :exc:`TypeError` since this element is not hashable + (:issue:`11895`). TESTS:: @@ -156,7 +156,6 @@ cdef class qAdicFloatingPointElement(FPElement): Traceback (most recent call last): ... TypeError: unhashable type: 'sage.rings.padics.qadic_flint_FP.qAdicFloatingPointElement' - """ # Eventually, hashing will be disabled for all (non-fixed-mod) p-adic # elements (#11895), until then, we only to this for types which did diff --git a/src/sage/rings/padics/relative_extension_leaves.py b/src/sage/rings/padics/relative_extension_leaves.py index 0310f2b21c3..b377a446081 100644 --- a/src/sage/rings/padics/relative_extension_leaves.py +++ b/src/sage/rings/padics/relative_extension_leaves.py @@ -1,7 +1,7 @@ """ Relative extensions of `p`-adic rings -We represent general extensions of p-adic rings as a two-step extension: +We represent general extensions of `p`-adic rings as a two-step extension: first an unramified extension of Qp, followed by an Eisenstein extension of the result. @@ -35,7 +35,7 @@ class pAdicRelativeBaseringInjection(Morphism): INPUT: - ``R`` -- an unramified `p`-adic ring or field - - ``S`` -- an eisenstein extension of ``R``. + - ``S`` -- an eisenstein extension of ``R`` EXAMPLES:: diff --git a/src/sage/rings/padics/relative_ramified_CA.pyx b/src/sage/rings/padics/relative_ramified_CA.pyx index 42337d04979..361c160cebe 100644 --- a/src/sage/rings/padics/relative_ramified_CA.pyx +++ b/src/sage/rings/padics/relative_ramified_CA.pyx @@ -20,7 +20,7 @@ cdef class RelativeRamifiedCappedAbsoluteElement(CAElement): sage: W(5)._poly_rep() 5 - The coefficients of P are floating point p-adics:: + The coefficients of P are floating point `p`-adics:: sage: P = W.random_element()._poly_rep() sage: ring = P.parent().base_ring() diff --git a/src/sage/rings/padics/relative_ramified_CR.pyx b/src/sage/rings/padics/relative_ramified_CR.pyx index 5263c190966..1bf0b815a3d 100644 --- a/src/sage/rings/padics/relative_ramified_CR.pyx +++ b/src/sage/rings/padics/relative_ramified_CR.pyx @@ -20,7 +20,7 @@ cdef class RelativeRamifiedCappedRelativeElement(CRElement): sage: W(5)._poly_rep() 5 - The coefficients of P are floating point p-adics:: + The coefficients of P are floating point `p`-adics:: sage: P = W.random_element()._poly_rep() sage: ring = P.parent().base_ring() diff --git a/src/sage/rings/padics/relative_ramified_FM.pyx b/src/sage/rings/padics/relative_ramified_FM.pyx index 27d18035ccb..7ec08b1af4e 100644 --- a/src/sage/rings/padics/relative_ramified_FM.pyx +++ b/src/sage/rings/padics/relative_ramified_FM.pyx @@ -20,7 +20,7 @@ cdef class RelativeRamifiedFixedModElement(FMElement): sage: W(5)._poly_rep() 5 - The coefficients of P are fixed-mod p-adics:: + The coefficients of P are fixed-mod `p`-adics:: sage: P = W.random_element()._poly_rep() sage: ring = P.parent().base_ring() diff --git a/src/sage/rings/padics/relative_ramified_FP.pyx b/src/sage/rings/padics/relative_ramified_FP.pyx index 3cbae5e55d3..2ac6656f753 100644 --- a/src/sage/rings/padics/relative_ramified_FP.pyx +++ b/src/sage/rings/padics/relative_ramified_FP.pyx @@ -20,7 +20,7 @@ cdef class RelativeRamifiedFloatingPointElement(FPElement): sage: W(5)._poly_rep() 5 - The coefficients of P are floating point p-adics:: + The coefficients of P are floating point `p`-adics:: sage: P = W.random_element()._poly_rep() sage: ring = P.parent().base_ring() diff --git a/src/sage/rings/padics/relaxed_template.pxi b/src/sage/rings/padics/relaxed_template.pxi index 7068a1425a2..1b6b4fb0833 100644 --- a/src/sage/rings/padics/relaxed_template.pxi +++ b/src/sage/rings/padics/relaxed_template.pxi @@ -112,7 +112,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``p`` -- a prime, which is compared with the parent of this element. + - ``p`` -- a prime, which is compared with the parent of this element EXAMPLES:: @@ -128,15 +128,14 @@ cdef class RelaxedElement(pAdicGenericElement): r""" Return a pointer on the `i`-th significant digit of this number. - .. NOTE: + .. NOTE:: This function does not check that the requested digit has been already computed. INPUT: - - ``i`` -- a positive integer - + - ``i`` -- positive integer """ pass @@ -145,15 +144,14 @@ cdef class RelaxedElement(pAdicGenericElement): Return a pointer on the digit in position `i` of this number. - .. NOTE: + .. NOTE:: This function do not check that the requested digit has been already computed. INPUT: - - ``i`` -- an integer - + - ``i`` -- integer """ pass @@ -165,10 +163,10 @@ cdef class RelaxedElement(pAdicGenericElement): - ``slice`` -- a ``celement`` to store the slice - - ``start`` -- a positive integer, the starting position of the slice + - ``start`` -- positive integer; the starting position of the slice in relative precision - - ``length`` -- a positive integer, the length of the slice + - ``length`` -- positive integer; the length of the slice .. NOTE:: @@ -182,9 +180,7 @@ cdef class RelaxedElement(pAdicGenericElement): r""" Compute the next digit of this number. - OUTPUT: - - An error code which is a superposition of the following: + OUTPUT: an error code which is a superposition of the following: - ``0`` -- no error - ``ERROR_ABANDON = 1`` -- computation has been abandoned @@ -204,7 +200,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -227,16 +223,15 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer - - ``halt`` -- an integer; the absolute precision after which the + - ``halt`` -- integer; the absolute precision after which the computation is abandoned if the first significant digit has not been found yet OUTPUT: An error code (see :meth:`_next_c` for details). - """ if self._valuation >= maxordp: return 0 @@ -276,7 +271,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -332,14 +327,14 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``n`` -- an integer or ``None`` (default ``None``); if - given, return the corresponding entries in the expansion. + - ``n`` -- integer or ``None`` (default: ``None``); if + given, return the corresponding entries in the expansion - ``lift_mode`` -- ``'simple'``, ``'smallest'`` or ``'teichmuller'`` (default: ``'simple'``) - ``start_val`` -- start at this valuation rather than the - default (`0` or the valuation of this element). + default (`0` or the valuation of this element) OUTPUT: @@ -351,7 +346,7 @@ cdef class RelaxedElement(pAdicGenericElement): EXAMPLES:: - sage: R = ZpER(7, print_mode="digits") + sage: R = ZpER(7, print_mode='digits') sage: a = R(1/2021); a ...23615224635636163463 @@ -443,7 +438,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``n`` -- an integer or a slice + - ``n`` -- integer or a slice EXAMPLES:: @@ -490,13 +485,13 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``start`` -- an integer or ``None`` (default: ``None``), + - ``start`` -- integer or ``None`` (default: ``None``); the first position of the slice - - ``stop`` -- an integer or ``None`` (default: ``None``), + - ``stop`` -- integer or ``None`` (default: ``None``); the first position not included in the slice - - ``bound`` -- a boolean (default: ``False``); whether the + - ``bound`` -- boolean (default: ``False``); whether the precision on the output should be bounded or unbounded EXAMPLES:: @@ -594,7 +589,6 @@ cdef class RelaxedElement(pAdicGenericElement): sage: b[:15] # indirect doctest 1 + 5 + 3*5^3 + 3*5^4 + 5^5 + 4*5^6 + 4*5^7 + 2*5^8 + 3*5^9 + 2*5^10 + 5^11 + 5^12 + 5^13 + O(5^15) - """ # This code should be integrated to the p-adic printer if self._valuation <= -maxordp: @@ -634,11 +628,10 @@ cdef class RelaxedElement(pAdicGenericElement): - ``right`` -- the second element involved in the comparison - - ``prec`` -- an integer, the precision at which the equality is checked - - - ``permissive`` -- a boolean; if ``True``, be silent if the precision - on one input is less than ``prec``; otherwise, raise an error + - ``prec`` -- integer; the precision at which the equality is checked + - ``permissive`` -- boolean; if ``True``, be silent if the precision + on one input is less than ``prec``. Otherwise, raise an error. """ cdef int error cdef long i @@ -670,7 +663,7 @@ cdef class RelaxedElement(pAdicGenericElement): - ``right`` -- a relaxed `p`-adic number - - ``prec`` -- an integer + - ``prec`` -- integer EXAMPLES:: @@ -698,11 +691,11 @@ cdef class RelaxedElement(pAdicGenericElement): - ``right`` -- a relaxed `p`-adic number - - ``prec`` -- an integer or ``None`` (default: ``None``); if - given, compare the two elements at this precision; otherwise - use the default halting precision of the parent + - ``prec`` -- integer or ``None`` (default: ``None``); if + given, compare the two elements at this precision. Otherwise + use the default halting precision of the parent. - - ``secure`` -- a boolean (default: ``False`` if ``prec`` is given, + - ``secure`` -- boolean (default: ``False`` if ``prec`` is given, ``True`` otherwise); when the elements cannot be distinguished at the given precision, raise an error if ``secure`` is ``True``, return ``True`` otherwise. @@ -858,7 +851,6 @@ cdef class RelaxedElement(pAdicGenericElement): O(5^20) sage: b._is_exact_zero() False - """ return self._valuation >= maxordp @@ -869,7 +861,7 @@ cdef class RelaxedElement(pAdicGenericElement): EXAMPLES:: - sage: R = ZpER(5, print_mode="digits") + sage: R = ZpER(5, print_mode='digits') sage: a = R(20/21) Computations have not started yet; hence we are not able @@ -1054,10 +1046,10 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); if ``None``, use the default precision of the parent - - ``permissive`` -- a boolean (default: ``False`` if ``prec`` + - ``permissive`` -- boolean (default: ``False`` if ``prec`` is given, ``True`` otherwise); if ``False``, raise an error if the precision of this element is not sufficient @@ -1123,7 +1115,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``absprec`` -- an integer or infinity + - ``absprec`` -- integer or infinity EXAMPLES:: @@ -1156,16 +1148,16 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); if ``None``, use the default precision of the parent - - ``halt`` -- an integer or a boolean (default: ``True``); + - ``halt`` -- integer or boolean (default: ``True``); the absolute precision after which the computation is abandoned - if the first significant digit has not been found yet; - if ``True``, the default halting precision of the parent is used; - if ``False``, the computation is never abandoned + if the first significant digit has not been found yet. + If ``True``, the default halting precision of the parent is used. + If ``False``, the computation is never abandoned. - - ``permissive`` -- a boolean (default: ``False`` if ``prec`` + - ``permissive`` -- boolean (default: ``False`` if ``prec`` is given, ``True`` otherwise); if ``False``, raise an error if the precision of this element is not sufficient @@ -1204,7 +1196,7 @@ cdef class RelaxedElement(pAdicGenericElement): sage: b.at_precision_relative(5, halt=21) # now, we're okay 5^20 + O(5^25) - .. NOTE: + .. NOTE:: It is also possible to pass in ``halt=False`` but it is not recommended because the computation can hang forever if this element is `0`. @@ -1254,7 +1246,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``absprec`` -- an integer or ``None`` (default: ``None``), the + - ``absprec`` -- integer or ``None`` (default: ``None``); the absolute precision of the result. If ``None``, the default precision of the parent is used. @@ -1325,9 +1317,9 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``halt`` -- an integer; if given, allow to increase the + - ``halt`` -- integer; if given, allow to increase the absolute precision on this element up to ``halt`` in order - to get a better lower bound. + to get a better lower bound """ cdef int error = 0 while not error and self._precrel == 0 and self._valuation < halt: @@ -1340,16 +1332,16 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``halt`` -- an integer or a boolean (default: ``True``); + - ``halt`` -- integer or boolean (default: ``True``); the absolute precision after which the computation is abandoned - if the first significant digit has not been found yet; - if ``True``, the default halting precision of the parent is used; - if ``False``, the computation is never abandoned + if the first significant digit has not been found yet. + If ``True``, the default halting precision of the parent is used. + If ``False``, the computation is never abandoned. - - ``secure`` -- a boolean (default: the value given at the creation + - ``secure`` -- boolean (default: the value given at the creation of the parent); when the valuation cannot be determined for sure, raise an error if ``secure`` is ``True``, return the best known - lower bound on the valuation otherwise. + lower bound on the valuation otherwise EXAMPLES:: @@ -1408,7 +1400,7 @@ cdef class RelaxedElement(pAdicGenericElement): sage: z.valuation(halt=21) # now, we're okay 20 - .. NOTE: + .. NOTE:: It is also possible to pass in ``halt=False`` but it is not recommended because the computation can hang forever if this element is `0`. @@ -1444,11 +1436,11 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``halt`` -- an integer or a boolean (default: ``True``); + - ``halt`` -- integer or boolean (default: ``True``); the absolute precision after which the computation is abandoned - if the first significant digit has not been found yet; - if ``True``, the default halting precision of the parent is used; - if ``False``, the computation is never abandoned + if the first significant digit has not been found yet. + If ``True``, the default halting precision of the parent is used. + If ``False``, the computation is never abandoned. EXAMPLES:: @@ -1476,7 +1468,6 @@ cdef class RelaxedElement(pAdicGenericElement): ValueError: unit part of 0 not defined See :meth:`valuation` for more details on the parameter ``halt``. - """ val = self.valuation(halt) if self._valuation >= self._precbound: @@ -1489,11 +1480,11 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``halt`` -- an integer or a boolean (default: ``True``); + - ``halt`` -- integer or boolean (default: ``True``); the absolute precision after which the computation is abandoned - if the first significant digit has not been found yet; - if ``True``, the default halting precision of the parent is used; - if ``False``, the computation is never abandoned + if the first significant digit has not been found yet. + If ``True``, the default halting precision of the parent is used. + If ``False``, the computation is never abandoned. EXAMPLES:: @@ -1522,7 +1513,6 @@ cdef class RelaxedElement(pAdicGenericElement): ValueError: unit part of 0 not defined See :meth:`valuation` for more details on the parameter ``halt``. - """ val = self.valuation(halt) if self._valuation >= self._precbound: @@ -1536,13 +1526,13 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``absprec`` -- a non-negative integer (default: ``1``) + - ``absprec`` -- nonnegative integer (default: 1) - - ``field`` -- boolean (default ``True``); when ``absprec`` is ``1``, - whether to return an element of GF(p) or Zmod(p). + - ``field`` -- boolean (default: ``True``); when ``absprec`` is ``1``, + whether to return an element of GF(p) or Zmod(p) - - ``check_prec`` -- boolean (default ``True``); whether to raise an error - if this element has insufficient precision to determine the reduction. + - ``check_prec`` -- boolean (default: ``True``); whether to raise an error + if this element has insufficient precision to determine the reduction EXAMPLES:: @@ -1561,7 +1551,7 @@ cdef class RelaxedElement(pAdicGenericElement): sage: b.residue() Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue """ if absprec >= maxordp: raise OverflowError @@ -1570,7 +1560,7 @@ cdef class RelaxedElement(pAdicGenericElement): error = self._jump_c(absprec) raise_error(error, not check_prec) if self._valuation < 0: - raise ValueError("element must have non-negative valuation in order to compute residue") + raise ValueError("element must have nonnegative valuation in order to compute residue") cdef celement digits cdef Integer ans if absprec <= self._valuation: @@ -1590,7 +1580,7 @@ cdef class RelaxedElement(pAdicGenericElement): INPUT: - - ``absprec`` -- an integer or ``None`` (default: ``None``); if ``None``, + - ``absprec`` -- integer or ``None`` (default: ``None``); if ``None``, the absolute precision of this element is used EXAMPLES:: @@ -1882,7 +1872,7 @@ cdef class RelaxedElement(pAdicGenericElement): sage: b 2 + 3 + 3^2 + 3^3 + 3^4 + ... - A ``ZeroDivisionError`` is raised if an element has no inverse in the + A :exc:`ZeroDivisionError` is raised if an element has no inverse in the ring:: sage: R(3).inverse_of_unit() @@ -1988,7 +1978,7 @@ cdef class RelaxedElement(pAdicGenericElement): def _test_pickling(self, **options): r""" - Checks that this object can be pickled and unpickled properly. + Check that this object can be pickled and unpickled properly. TESTS:: @@ -2030,7 +2020,7 @@ cdef class RelaxedElement(pAdicGenericElement): cdef class RelaxedElement_abandon(RelaxedElement): r""" - A special class for relaxed p-adic with all digits unknown. + A special class for relaxed `p`-adic with all digits unknown. This class is used for setting temporary definition of some self-referent numbers. @@ -2068,7 +2058,7 @@ cdef relaxedelement_abandon = RelaxedElement_abandon() cdef class RelaxedElementWithDigits(RelaxedElement): r""" - A generic class for relaxed p-adic elements that stores + A generic class for relaxed `p`-adic elements that stores the sequence of its digits. """ def __cinit__(self): @@ -2105,9 +2095,9 @@ cdef class RelaxedElementWithDigits(RelaxedElement): - ``slice`` -- a ``celement`` to store the slice - - ``start`` -- an integer, the start position of the slice + - ``start`` -- integer; the start position of the slice - - ``length`` -- an integer, the length of the slice + - ``length`` -- integer; the length of the slice .. NOTE:: @@ -2125,7 +2115,7 @@ cdef class RelaxedElementWithDigits(RelaxedElement): cdef class RelaxedElement_zero(RelaxedElement): r""" - A class for representation a relaxed p-adic number which is + A class for representation a relaxed `p`-adic number which is exactly zero. TESTS:: @@ -2133,7 +2123,6 @@ cdef class RelaxedElement_zero(RelaxedElement): sage: R = ZpER(7) sage: a = R.zero() sage: TestSuite(a).run() - """ def __init__(self, parent): r""" @@ -2193,9 +2182,9 @@ cdef class RelaxedElement_zero(RelaxedElement): - ``slice`` -- a ``celement`` to store the slice - - ``start`` -- an integer, the start position of the slice + - ``start`` -- integer; the start position of the slice - - ``length`` -- an integer, the length of the slice + - ``length`` -- integer; the length of the slice """ element_init(slice) @@ -2205,7 +2194,7 @@ cdef class RelaxedElement_zero(RelaxedElement): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -2228,7 +2217,7 @@ cdef class RelaxedElement_zero(RelaxedElement): cdef class RelaxedElement_one(RelaxedElementWithDigits): r""" - A class for representation a relaxed p-adic number which is + A class for representation a relaxed `p`-adic number which is exactly one. TESTS:: @@ -2236,7 +2225,6 @@ cdef class RelaxedElement_one(RelaxedElementWithDigits): sage: R = ZpER(7) sage: a = R.one() sage: TestSuite(a).run() - """ def __init__(self, parent): r""" @@ -2281,7 +2269,7 @@ cdef class RelaxedElement_one(RelaxedElementWithDigits): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -2307,8 +2295,8 @@ cdef class RelaxedElement_one(RelaxedElementWithDigits): cdef class RelaxedElement_bound(RelaxedElement): r""" - A class for p-adic relaxed elements which are defined by bounding the - precision of another p-adic relaxed element. + A class for `p`-adic relaxed elements which are defined by bounding the + precision of another `p`-adic relaxed element. TESTS:: @@ -2327,7 +2315,7 @@ cdef class RelaxedElement_bound(RelaxedElement): - ``x`` -- a relaxed `p`-adics, the element to bound - - ``precbound`` -- an integer or ``None`` (default: ``None``), + - ``precbound`` -- integer or ``None`` (default: ``None``); the bound on the precision .. NOTE:: @@ -2389,10 +2377,10 @@ cdef class RelaxedElement_bound(RelaxedElement): - ``slice`` -- a ``celement`` to store the slice - - ``start`` -- a positive integer, the starting position of the slice + - ``start`` -- positive integer; the starting position of the slice in relative precision - - ``length`` -- a positive integer, the length of the slice + - ``length`` -- positive integer; the length of the slice .. NOTE:: @@ -2408,7 +2396,7 @@ cdef class RelaxedElement_bound(RelaxedElement): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -2466,10 +2454,10 @@ cdef class RelaxedElement_value(RelaxedElementWithDigits): - ``value`` -- the value in the exact subring - - ``shift`` -- an integer (default: `0`), the position at which + - ``shift`` -- integer (default: `0`); the position at which the given value is written - - ``precbound`` -- an integer or ``None`` (default: ``None``), + - ``precbound`` -- integer or ``None`` (default: ``None``); the bound on the precision TESTS:: @@ -2514,7 +2502,7 @@ cdef class RelaxedElement_value(RelaxedElementWithDigits): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -2582,15 +2570,15 @@ cdef class RelaxedElement_random(RelaxedElementWithDigits): - ``parent`` -- the parent of this element - - ``valuation`` -- an integer or ``None``, the position from which + - ``valuation`` -- integer or ``None``; the position from which random digits are picked; if ``None``, it is randomly chosen if the parent is a field and set to `0` otherwise - - ``precbound`` -- an integer or ``None`` (default: ``None``), + - ``precbound`` -- integer or ``None`` (default: ``None``); the bound on the precision - - ``seed`` -- an integer or ``None`` (default: ``None``), the + - ``seed`` -- integer or ``None`` (default: ``None``); the seed of the random generator .. NOTE:: @@ -2628,7 +2616,7 @@ cdef class RelaxedElement_random(RelaxedElementWithDigits): TESTS:: - sage: R = ZpER(5, print_mode="digits") + sage: R = ZpER(5, print_mode='digits') sage: a = R.random_element() sage: a # random ...32220241412003314311 @@ -2696,13 +2684,13 @@ cdef class RelaxedElement_slice(RelaxedElement): - ``x`` -- a relaxed `p`-adic element, the element from which the slice is extracted - - ``start`` -- an integer, the position of the first digit of `x` + - ``start`` -- integer; the position of the first digit of `x` in the slice - - ``stop`` -- an integer, the position of the first digit of `x` + - ``stop`` -- integer; the position of the first digit of `x` after the slice - - ``shift`` -- an integer such that ``self[i] = x[i+shift]`` + - ``shift`` -- integer such that ``self[i] = x[i+shift]`` .. NOTE:: @@ -2739,7 +2727,7 @@ cdef class RelaxedElement_slice(RelaxedElement): TESTS:: - sage: R = ZpER(5, print_mode="digits") + sage: R = ZpER(5, print_mode='digits') sage: x = R(20/21) sage: y = x.slice(3, 6) sage: y == loads(dumps(y)) # indirect doctest @@ -2773,9 +2761,9 @@ cdef class RelaxedElement_slice(RelaxedElement): - ``slice`` -- a ``celement`` to store the slice - - ``start`` -- an integer, the start position of the slice + - ``start`` -- integer; the start position of the slice - - ``length`` -- an integer, the length of the slice + - ``length`` -- integer; the length of the slice .. NOTE:: @@ -2795,7 +2783,7 @@ cdef class RelaxedElement_slice(RelaxedElement): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -2902,7 +2890,7 @@ cdef class RelaxedElement_add(RelaxedElementWithDigits): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -3009,7 +2997,7 @@ cdef class RelaxedElement_sub(RelaxedElementWithDigits): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -3252,7 +3240,6 @@ cdef class RelaxedElement_muldigit(RelaxedElementWithDigits): digit is the first factor - ``y`` -- a relaxed `p`-adic element, the second factor - """ RelaxedElement.__init__(self, parent) self._x = x._inverse @@ -3325,9 +3312,9 @@ cdef class RelaxedElement_div(RelaxedElementWithDigits): - ``denom`` -- a relaxed `p`-adic element, the divisor - - ``minval`` -- an integer, the minimal valuation allowed for this element + - ``minval`` -- integer; the minimal valuation allowed for this element - - ``precbound`` -- an integer or ``None`` (default: ``None``), + - ``precbound`` -- integer or ``None`` (default: ``None``); the bound on the precision TESTS:: @@ -3540,7 +3527,6 @@ cdef class RelaxedElement_sqrt(RelaxedElementWithDigits): .. NOTE:: This code does not work for nontrivial extensions of `\QQ_2`. - """ cdef RelaxedElement x = self._x cdef long maxprec @@ -3654,7 +3640,7 @@ cdef class RelaxedElement_teichmuller(RelaxedElementWithDigits): - ``parent`` -- the parent of this element - ``xbar`` -- an element in the exact subring, which is congruent - to this Teichmüller modulo this uniformizer. + to this Teichmüller modulo this uniformizer TESTS:: @@ -3717,7 +3703,7 @@ cdef class RelaxedElement_teichmuller(RelaxedElementWithDigits): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -3781,10 +3767,10 @@ cdef class RelaxedElement_unknown(RelaxedElementWithDigits): - ``parent`` -- the parent of this element - - ``valuation`` -- an integer, a lower bound on the valuation of + - ``valuation`` -- integer; a lower bound on the valuation of this number - - ``digits`` -- a list or ``None`` (default: ``None``), the first + - ``digits`` -- list or ``None`` (default: ``None``); the first significant digits of this number TESTS:: @@ -3987,7 +3973,6 @@ cdef class RelaxedElement_zeroone(RelaxedElementWithDigits): - ``parent`` -- the parent of this element - ``valuation`` -- the valuation of this number - """ RelaxedElement.__init__(self, parent) self._valuation = valuation @@ -4011,7 +3996,7 @@ cdef class RelaxedElement_zeroone(RelaxedElementWithDigits): INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer OUTPUT: @@ -4061,9 +4046,9 @@ cdef class ExpansionIter(): - ``mode`` -- either ``simple_mode``, ``smallest_mode`` or ``teichmuller_mode`` - - ``start`` -- an integer, the position where the expansion starts + - ``start`` -- integer; the position where the expansion starts - - ``stop`` -- an integer, the position where the expansion stops + - ``stop`` -- integer; the position where the expansion stops TESTS:: diff --git a/src/sage/rings/padics/relaxed_template_header.pxi b/src/sage/rings/padics/relaxed_template_header.pxi index 7a57141e922..044283ee7d0 100644 --- a/src/sage/rings/padics/relaxed_template_header.pxi +++ b/src/sage/rings/padics/relaxed_template_header.pxi @@ -1,6 +1,6 @@ """ This file provides the declaration for the RelaxedElement class, -which collects common functionality for the different relaxed p-adic +which collects common functionality for the different relaxed `p`-adic template classes. It is included in padic_relaxed_element.pxd and should be included diff --git a/src/sage/rings/padics/tutorial.py b/src/sage/rings/padics/tutorial.py index 45459711382..da0c80f021c 100644 --- a/src/sage/rings/padics/tutorial.py +++ b/src/sage/rings/padics/tutorial.py @@ -77,7 +77,7 @@ The *absolute precision* of a finite approximation `\bar{x} \in \ZZ/p^n\ZZ` to `x \in \ZZ_p` -is the non-negative integer `n`. +is the nonnegative integer `n`. In the second representation, we can achieve the same thing by truncating a series diff --git a/src/sage/rings/padics/unramified_extension_generic.py b/src/sage/rings/padics/unramified_extension_generic.py index 3ca4d07b2b0..7eb99efe585 100644 --- a/src/sage/rings/padics/unramified_extension_generic.py +++ b/src/sage/rings/padics/unramified_extension_generic.py @@ -31,16 +31,16 @@ class UnramifiedExtensionGeneric(pAdicExtensionGeneric): """ def __init__(self, poly, prec, print_mode, names, element_class): """ - Initializes ``self``. + Initialize ``self``. INPUT: - - ``poly`` -- Polynomial defining this extension. - - ``prec`` -- The precision cap - - ``print_mode`` -- a dictionary with print options + - ``poly`` -- polynomial defining this extension + - ``prec`` -- the precision cap + - ``print_mode`` -- dictionary with print options - ``names`` -- a 4-tuple, (``variable_name``, ``residue_name``, ``unramified_subextension_variable_name``, ``uniformizer_name``) - - ``element_class`` -- the class for elements of this unramified extension. + - ``element_class`` -- the class for elements of this unramified extension EXAMPLES:: @@ -100,7 +100,7 @@ def absolute_f(self): def residue_class_field(self): """ - Returns the residue class field. + Return the residue class field. EXAMPLES:: @@ -141,7 +141,7 @@ def discriminant(self, K=None): INPUT: - - ``K`` -- a subring/subfield (defaults to the base ring). + - ``K`` -- a subring/subfield (defaults to the base ring) EXAMPLES:: @@ -161,7 +161,7 @@ def discriminant(self, K=None): #def galois_group(self): # r""" - # Returns the Galois group of self's fraction field over Qp. + # Returns the Galois group of ``self``'s fraction field over Qp. # """ # ## # ## If K is a number field, then K.galois_group() can return @@ -182,7 +182,7 @@ def is_galois(self, K=None): INPUT: - - ``K`` -- a subring/subfield (defaults to the base ring). + - ``K`` -- a subring/subfield (defaults to the base ring) EXAMPLES:: @@ -213,7 +213,7 @@ def gen(self, n=0): @cached_method def _frob_gen(self, arithmetic=True): """ - Return frobenius of the generator for this unramified extension + Return frobenius of the generator for this unramified extension. EXAMPLES:: @@ -294,9 +294,7 @@ def has_pth_root(self): - ``self`` -- a `p`-adic ring - OUTPUT: - - boolean -- whether ``self`` has primitive `p`-th root of unity. + OUTPUT: boolean; whether ``self`` has primitive `p`-th root of unity EXAMPLES:: @@ -315,11 +313,9 @@ def has_root_of_unity(self, n): INPUT: - ``self`` -- a `p`-adic ring - - ``n`` -- an integer - - OUTPUT: + - ``n`` -- integer - - boolean + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/rings/pari_ring.py b/src/sage/rings/pari_ring.py index f34a45829a0..61459d8d50d 100644 --- a/src/sage/rings/pari_ring.py +++ b/src/sage/rings/pari_ring.py @@ -202,8 +202,8 @@ def random_element(self, x=None, y=None, distribution=None): between 0 and `x-1`, inclusive. If both are provided, then the result is between `x` and `y-1`, inclusive. - - `distribution` -- optional string, so that ``ZZ`` can make sense - of it as a probability distribution. + - ``distribution`` -- (optional) string, so that ``ZZ`` can make sense + of it as a probability distribution EXAMPLES:: @@ -212,9 +212,8 @@ def random_element(self, x=None, y=None, distribution=None): True sage: R(5) <= R.random_element(5,13) < R(13) True - sage: R.random_element(distribution="1/n").parent() is R + sage: R.random_element(distribution='1/n').parent() is R True - """ from sage.rings.integer_ring import ZZ return self(ZZ.random_element(x, y, distribution)) diff --git a/src/sage/rings/polynomial/binary_form_reduce.py b/src/sage/rings/polynomial/binary_form_reduce.py index 8b6134ec59b..8d4c770072d 100644 --- a/src/sage/rings/polynomial/binary_form_reduce.py +++ b/src/sage/rings/polynomial/binary_form_reduce.py @@ -62,8 +62,7 @@ def covariant_z0(F, z0_cov=False, prec=53, emb=None, error_limit=0.000001): - ``emb`` -- embedding into CC - - ``error_limit`` -- sets the error tolerance (default:0.000001) - + - ``error_limit`` -- sets the error tolerance (default: 0.000001) OUTPUT: a complex number, a real number @@ -271,15 +270,15 @@ def epsinv(F, target, prec=53, target_tol=0.001, z=None, emb=None): - ``F`` -- binary form of degree at least 3 with no multiple roots - - ``target`` -- positive real number. The value we want to attain, i.e., + - ``target`` -- positive real number; the value we want to attain, i.e., the value we are taking the inverse of - - ``prec`` -- positive integer. precision to use in CC + - ``prec`` -- positive integer; precision to use in CC - - ``target_tol`` -- positive real number. The tolerance with which we - attain the target value. + - ``target_tol`` -- positive real number; the tolerance with which we + attain the target value - - ``z`` -- complex number. ``z_0`` covariant for F. + - ``z`` -- complex number; ``z_0`` covariant for F - ``emb`` -- embedding into CC @@ -435,7 +434,7 @@ def get_bound_poly(F, prec=53, norm_type='norm', emb=None): def smallest_poly(F, prec=53, norm_type='norm', emb=None): r""" - Determine the poly with smallest coefficients in `SL(2,\Z)` orbit of ``F`` + Determine the poly with smallest coefficients in `SL(2,\Z)` orbit of ``F``. Smallest can be in the sense of `L_2` norm or height. The method is the algorithm in Hutz-Stoll [HS2018]_. @@ -448,8 +447,8 @@ def smallest_poly(F, prec=53, norm_type='norm', emb=None): - ``F`` -- binary form of degree at least 3 with no multiple roots - - ``norm_type`` -- string; ``norm`` or ``height`` controlling what ``smallest`` - means for the coefficients. + - ``norm_type`` -- string; ``'norm'`` or ``'height'`` controlling what + ``smallest`` means for the coefficients OUTPUT: pair [poly, matrix] diff --git a/src/sage/rings/polynomial/commutative_polynomial.pyx b/src/sage/rings/polynomial/commutative_polynomial.pyx index dc9f2cab8b7..7e2e7be4fc8 100644 --- a/src/sage/rings/polynomial/commutative_polynomial.pyx +++ b/src/sage/rings/polynomial/commutative_polynomial.pyx @@ -1,6 +1,6 @@ cdef class CommutativePolynomial(CommutativeAlgebraElement): r""" - Abstract base class for commutative polynomials in any number of variables + Abstract base class for commutative polynomials in any number of variables. It is a common base for :class:`~sage.rings.polynomial.polynomial_element.Polynomial`, :class:`~sage.rings.polynomial.multi_polynomial.MPolynomial`, and diff --git a/src/sage/rings/polynomial/complex_roots.py b/src/sage/rings/polynomial/complex_roots.py index 602ba9ffc27..0c94bac6035 100644 --- a/src/sage/rings/polynomial/complex_roots.py +++ b/src/sage/rings/polynomial/complex_roots.py @@ -54,9 +54,9 @@ def interval_roots(p, rts, prec): and a precision. We attempt to verify that the estimated roots are in fact distinct - roots of the polynomial, using interval arithmetic of precision prec. + roots of the polynomial, using interval arithmetic of precision ``prec``. If we succeed, we return a list of intervals bounding the roots; if we - fail, we return None. + fail, we return ``None``. EXAMPLES:: diff --git a/src/sage/rings/polynomial/convolution.py b/src/sage/rings/polynomial/convolution.py index 653bc37799c..0f7cc5fadfa 100644 --- a/src/sage/rings/polynomial/convolution.py +++ b/src/sage/rings/polynomial/convolution.py @@ -191,7 +191,7 @@ def _fft(L, K, start, depth, root): `S = R[y]/(y^K + 1)`. This function performs an inplace FFT, i.e. evaluates the - polynomial at x = each D-th root of unity in S (namely the powers + polynomial at x = each `D`-th root of unity in S (namely the powers of `y^{2K/D}`), with results in bit-reversed order. """ half = 1 << (depth - 1) diff --git a/src/sage/rings/polynomial/cyclotomic.pyx b/src/sage/rings/polynomial/cyclotomic.pyx index 4d1c44c5ec0..8c9088434fa 100644 --- a/src/sage/rings/polynomial/cyclotomic.pyx +++ b/src/sage/rings/polynomial/cyclotomic.pyx @@ -58,7 +58,7 @@ def cyclotomic_coeffs(nn, sparse=None): form `1-x^n` can be done very quickly in a single pass. If ``sparse`` is ``True``, the result is returned as a dictionary of - the non-zero entries, otherwise the result is returned as a list + the nonzero entries, otherwise the result is returned as a list of python ints. EXAMPLES:: @@ -209,9 +209,7 @@ def cyclotomic_value(n, x): - ``x`` -- an element of a ring - OUTPUT: - - - the value of the cyclotomic polynomial `\Phi_n` at `x` + OUTPUT: the value of the cyclotomic polynomial `\Phi_n` at `x` ALGORITHM: diff --git a/src/sage/rings/polynomial/flatten.py b/src/sage/rings/polynomial/flatten.py index ef71d2b13a6..ac0e594ab3c 100644 --- a/src/sage/rings/polynomial/flatten.py +++ b/src/sage/rings/polynomial/flatten.py @@ -38,8 +38,8 @@ from sage.categories.morphism import Morphism from sage.misc.cachefunc import cached_method from .polynomial_ring_constructor import PolynomialRing -from .polynomial_ring import is_PolynomialRing -from .multi_polynomial_ring_base import is_MPolynomialRing +from .polynomial_ring import PolynomialRing_general +from .multi_polynomial_ring_base import MPolynomialRing_base from sage.rings.fraction_field import FractionField_generic from sage.rings.fraction_field_element import FractionFieldElement from sage.rings.polynomial.polydict import ETuple @@ -79,7 +79,7 @@ class FlatteningMorphism(Morphism): """ def __init__(self, domain): """ - The Python constructor + The Python constructor. EXAMPLES:: @@ -160,14 +160,14 @@ def __init__(self, domain): sage: fl.section()(fl(p)) == p True """ - if not is_PolynomialRing(domain) and not is_MPolynomialRing(domain): + if not isinstance(domain, PolynomialRing_general) and not isinstance(domain, MPolynomialRing_base): raise ValueError("domain should be a polynomial ring") ring = domain variables = [] intermediate_rings = [] - while is_PolynomialRing(ring) or is_MPolynomialRing(ring): + while isinstance(ring, PolynomialRing_general) or isinstance(ring, MPolynomialRing_base): intermediate_rings.append(ring) v = ring.variable_names() variables.extend(reversed(v)) @@ -181,7 +181,7 @@ def __init__(self, domain): if b not in variables: # not just variables[:i]! break variables[i] = b - if is_MPolynomialRing(domain): + if isinstance(domain, MPolynomialRing_base): codomain = PolynomialRing(ring, variables, len(variables)) else: codomain = PolynomialRing(ring, variables) @@ -221,12 +221,12 @@ def _call_(self, p): for ring in self._intermediate_rings: new_p = {} - if is_PolynomialRing(ring): + if isinstance(ring, PolynomialRing_general): for mon, pp in p.items(): assert pp.parent() is ring for i, j in pp.dict().items(): new_p[(i,)+(mon)] = j - elif is_MPolynomialRing(ring): + elif isinstance(ring, MPolynomialRing_base): for mon, pp in p.items(): assert pp.parent() is ring for mmon, q in pp.dict().items(): @@ -285,7 +285,7 @@ def inverse(self): class UnflatteningMorphism(Morphism): r""" - Inverses for :class:`FlatteningMorphism` + Inverses for :class:`FlatteningMorphism`. EXAMPLES:: @@ -313,7 +313,7 @@ class UnflatteningMorphism(Morphism): def __init__(self, domain, codomain): """ - The Python constructor + The Python constructor. EXAMPLES:: @@ -345,17 +345,17 @@ def __init__(self, domain, codomain): ... ValueError: rings must have the same number of variables """ - if not is_MPolynomialRing(domain): + if not isinstance(domain, MPolynomialRing_base): raise ValueError("domain should be a multivariate polynomial ring") - if not is_PolynomialRing(codomain) and not is_MPolynomialRing(codomain): + if not isinstance(codomain, PolynomialRing_general) and not isinstance(codomain, MPolynomialRing_base): raise ValueError("codomain should be a polynomial ring") ring = codomain intermediate_rings = [] while True: - is_polynomial_ring = is_PolynomialRing(ring) - if not (is_polynomial_ring or is_MPolynomialRing(ring)): + is_polynomial_ring = isinstance(ring, PolynomialRing_general) + if not (is_polynomial_ring or isinstance(ring, MPolynomialRing_base)): break intermediate_rings.append((ring, is_polynomial_ring)) ring = ring.base_ring() @@ -416,7 +416,7 @@ def _call_(self, p): class SpecializationMorphism(Morphism): r""" - Morphisms to specialize parameters in (stacked) polynomial rings + Morphisms to specialize parameters in (stacked) polynomial rings. EXAMPLES:: @@ -463,7 +463,7 @@ class SpecializationMorphism(Morphism): def __init__(self, domain, D): """ - The Python constructor + The Python constructor. EXAMPLES:: @@ -499,7 +499,7 @@ def __init__(self, domain, D): Defn: Defined on coordinates by sending (z) to (z^2 + 1.00000000000000) """ - if not is_PolynomialRing(domain) and not is_MPolynomialRing(domain): + if not isinstance(domain, PolynomialRing_general) and not isinstance(domain, MPolynomialRing_base): raise TypeError("domain should be a polynomial ring") # use only the generators that are in the stack somewhere, @@ -538,7 +538,7 @@ def __init__(self, domain, D): # Construct unflattened codomain R new_vars = [] R = domain - while is_PolynomialRing(R) or is_MPolynomialRing(R) or isinstance(R, FractionField_generic): + while isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base) or isinstance(R, FractionField_generic): if isinstance(R, FractionField_generic): # We've hit base_ring, so set _sub_specialization and exit the loop field_over = R.base() @@ -563,7 +563,7 @@ def __init__(self, domain, D): # We're still in the polynomials, so keep track of the tower old = R.gens() new = [t for t in old if t not in D] - force_multivariate = ((len(old) == 1) and is_MPolynomialRing(R)) + force_multivariate = ((len(old) == 1) and isinstance(R, MPolynomialRing_base)) new_vars.append((new, force_multivariate, old)) R = R.base_ring() @@ -664,7 +664,7 @@ class FractionSpecializationMorphism(Morphism): """ def __init__(self, domain, D): """ - Initialize the morphism with a domain and dictionary of specializations + Initialize the morphism with a domain and dictionary of specializations. EXAMPLES:: @@ -687,7 +687,7 @@ def __init__(self, domain, D): def _call_(self, p): """ - Evaluate a fraction specialization morphism + Evaluate a fraction specialization morphism. EXAMPLES:: @@ -700,7 +700,6 @@ def _call_(self, p): (3*x + 2*y)/(-2*z) sage: spec.parent() Fraction Field of Multivariate Polynomial Ring in x, y, z over Rational Field - """ if not isinstance(p, FractionFieldElement): raise TypeError("p must be a fraction field element") diff --git a/src/sage/rings/polynomial/groebner_fan.py b/src/sage/rings/polynomial/groebner_fan.py index 83877f35072..d0a34b3cca8 100644 --- a/src/sage/rings/polynomial/groebner_fan.py +++ b/src/sage/rings/polynomial/groebner_fan.py @@ -58,14 +58,13 @@ """ import string +import re import pexpect from subprocess import PIPE, Popen -from sage.misc.sage_eval import sage_eval - from sage.structure.sage_object import SageObject from sage.interfaces.gfan import gfan -from .multi_polynomial_ideal import is_MPolynomialIdeal +from .multi_polynomial_ideal import MPolynomialIdeal from .polynomial_ring_constructor import PolynomialRing from sage.rings.rational_field import QQ from sage.rings.integer import Integer @@ -104,7 +103,7 @@ def prefix_check(str_list): def max_degree(list_of_polys): """ - Compute the maximum degree of a list of polynomials + Compute the maximum degree of a list of polynomials. EXAMPLES:: @@ -124,8 +123,7 @@ def _cone_parse(fan_dict_cone): INPUT: - - ``fan_dict_cone`` -- the value of a fan_dict with - key 'CONES' + - ``fan_dict_cone`` -- the value of a ``fan_dict`` with key 'CONES' EXAMPLES:: @@ -290,8 +288,7 @@ def __init__(self, gfan_polyhedral_fan, parameter_indices=None): INPUT: - - ``gfan_polyhedral_fan`` -- output from gfan of a - polyhedral fan. + - ``gfan_polyhedral_fan`` -- output from gfan of a polyhedral fan EXAMPLES:: @@ -494,7 +491,7 @@ def is_simplicial(self): def to_RationalPolyhedralFan(self): """ - Converts to the RationalPolyhedralFan class, which is more actively + Convert to the RationalPolyhedralFan class, which is more actively maintained. While the information in each class is essentially the same, the methods and implementation are different. @@ -520,7 +517,6 @@ def to_RationalPolyhedralFan(self): [ 1 0 0 0 0 1 -2] [ 0 1 0 0 1 0 -2] [ 0 0 1 1 0 0 -2] - """ try: return self._fan @@ -656,12 +652,11 @@ def __init__(self, gfan_polyhedral_fan, polynomial_system, poly_ring, INPUT: - - ``gfan_polyhedral_fan`` -- output from ``gfan`` of a - polyhedral fan. - - ``polynomial_system`` -- a list of polynomials + - ``gfan_polyhedral_fan`` -- output from ``gfan`` of a polyhedral fan + - ``polynomial_system`` -- list of polynomials - ``poly_ring`` -- the polynomial ring of the list of polynomials - - ``parameters`` (optional) -- a list of variables to be considered - as parameters + - ``parameters`` -- (optional) list of variables to be considered + as parameters EXAMPLES:: @@ -725,7 +720,7 @@ def initial_form_systems(self): def ring_to_gfan_format(input_ring): """ - Converts a ring to gfan's format. + Convert a ring to gfan's format. EXAMPLES:: @@ -785,17 +780,17 @@ def __init__(self, I, is_groebner_basis=False, symmetry=None, verbose=False): INPUT: - - ``I`` -- ideal in a multivariate polynomial ring + - ``I`` -- ideal in a multivariate polynomial ring - - ``is_groebner_basis`` -- bool (default ``False``). if - ``True``, then I.gens() must be a Groebner basis with respect to the - standard degree lexicographic term order. + - ``is_groebner_basis`` -- boolean (default: ``False``); if + ``True``, then I.gens() must be a Groebner basis with respect to the + standard degree lexicographic term order - - ``symmetry`` -- default: ``None``; if not ``None``, describes - symmetries of the ideal + - ``symmetry`` -- (default: ``None``) if not ``None``, describes + symmetries of the ideal - - ``verbose`` -- default: ``False``; if ``True``, printout - useful info during computations + - ``verbose`` -- (default: ``False``) if ``True``, printout + useful info during computations EXAMPLES:: @@ -817,14 +812,13 @@ class to compute the Stanley-Reisner ideal of the tropical prevariety:: sage: RPF = PF.to_RationalPolyhedralFan() sage: RPF.Stanley_Reisner_ideal(PolynomialRing(QQ,4,'A, B, C, D')) Ideal (A*B, A*C, B*C*D) of Multivariate Polynomial Ring in A, B, C, D over Rational Field - """ self.__is_groebner_basis = is_groebner_basis self.__symmetry = symmetry if symmetry: print("WARNING! Symmetry option not yet implemented!!") self.__verbose = verbose - if not is_MPolynomialIdeal(I): + if not isinstance(I, MPolynomialIdeal): raise TypeError("I must be a multivariate polynomial ideal") if not prefix_check([str(R_gen) for R_gen in I.ring().gens()]): raise RuntimeError("Ring variables cannot contain each other as prefixes") @@ -844,7 +838,7 @@ class to compute the Stanley-Reisner ideal of the tropical prevariety:: def _repr_(self): """ - Describes the Groebner fan and its corresponding ideal. + Describe the Groebner fan and its corresponding ideal. EXAMPLES:: @@ -858,7 +852,7 @@ def _repr_(self): def __eq__(self, right): """ - Tests equality of Groebner fan objects. + Test equality of Groebner fan objects. EXAMPLES:: @@ -885,8 +879,6 @@ def ideal(self): def _gfan_maps(self): """ - INPUT: none - OUTPUT: - map from Sage ring to ``gfan`` ring @@ -983,8 +975,9 @@ def weight_vectors(self): stdin=PIPE, stdout=PIPE, stderr=PIPE) ans, err = gfan_processes.communicate(input=str_to_bytes(self.gfan())) ans = bytes_to_str(ans) - ans = sage_eval(ans.replace('{', '').replace('}', '').replace('\n', '')) - return [vector(QQ, x) for x in ans] + vect = re.compile(r"\([0-9,/\s]*\)") + ans = (tup[1:-1].split(',') for tup in vect.findall(ans)) + return [vector(QQ, [QQ(y) for y in x]) for x in ans] def ring(self): """ @@ -1114,9 +1107,9 @@ def gfan(self, cmd='bases', I=None, format=None): INPUT: - - ``cmd`` -- string (default:``'bases'``), GFan command - - ``I`` -- ideal (default:``None``) - - ``format`` -- bool (default:``None``), deprecated + - ``cmd`` -- string (default: ``'bases'``); GFan command + - ``I`` -- ideal (default: ``None``) + - ``format`` -- boolean (default: ``None``); deprecated EXAMPLES:: @@ -1157,7 +1150,7 @@ def __iter__(self): def __getitem__(self, i): """ - Get a reduced groebner basis + Get a reduced groebner basis. EXAMPLES:: @@ -1242,29 +1235,27 @@ def render(self, file=None, larger=False, shift=0, rgbcolor=(0, 0, 0), INPUT: - - ``file`` -- a filename if you prefer the output - saved to a file. This will be in xfig format. - - - ``shift`` -- shift the positions of the variables in - the drawing. For example, with shift=1, the corners will be b - (right), c (left), and d (top). The shifting is done modulo the - number of variables in the polynomial ring. The default is 0. + - ``file`` -- a filename if you prefer the output + saved to a file; this will be in xfig format - - ``larger`` -- bool (default: ``False``); if ``True``, make - the triangle larger so that the shape of the Groebner region - appears. Affects the xfig file but probably not the sage graphics - (?) + - ``shift`` -- shift the positions of the variables in + the drawing. For example, with shift=1, the corners will be b + (right), c (left), and d (top). The shifting is done modulo the + number of variables in the polynomial ring. The default is 0. - - ``rgbcolor`` -- This will not affect the saved xfig - file, only the sage graphics produced. + - ``larger`` -- boolean (default: ``False``); if ``True``, make + the triangle larger so that the shape of the Groebner region + appears. Affects the xfig file but probably not the sage graphics (?). - - ``polyfill`` -- Whether or not to fill the cones with - a color determined by the highest degree in each reduced Groebner - basis for that cone. + - ``rgbcolor`` -- this will not affect the saved xfig + file, only the sage graphics produced - - ``scale_colors`` -- if True, this will normalize - color values to try to maximize the range + - ``polyfill`` -- whether or not to fill the cones with + a color determined by the highest degree in each reduced Groebner + basis for that cone + - ``scale_colors`` -- if ``True``, this will normalize + color values to try to maximize the range EXAMPLES:: @@ -1281,7 +1272,7 @@ def render(self, file=None, larger=False, shift=0, rgbcolor=(0, 0, 0), TESTS: Testing the case where the number of generators is < 3. Currently, - this should raise a :class:`NotImplementedError`. + this should raise a :exc:`NotImplementedError`. :: @@ -1367,13 +1358,13 @@ def _cone_to_ieq(self, facet_list): def _embed_tetra(self, fpoint): """ - Takes a 4-d vector and projects it onto the plane perpendicular to + Take a 4-d vector and projects it onto the plane perpendicular to (1,1,1,1). Stretches by a factor of 2 as well, since this is only for graphical display purposes. INPUT: - - ``fpoint`` -- a list of four numbers + - ``fpoint`` -- list of four numbers EXAMPLES:: @@ -1402,7 +1393,7 @@ def _4d_to_3d(self, polyhedral_data): OUTPUT: - - ``edges`` -- a list of edges in 3d; each list item is a pair of + - ``edges`` -- list of edges in 3d; each list item is a pair of points EXAMPLES:: @@ -1457,11 +1448,11 @@ def render3d(self, verbose=False): TESTS: Now test the case where the number of generators is not 4. Currently, - this should raise a :class:`NotImplementedError` error. + this should raise a :exc:`NotImplementedError` error. :: - sage: P. = PolynomialRing(QQ, 3, order="lex") + sage: P. = PolynomialRing(QQ, 3, order='lex') sage: sage.rings.ideal.Katsura(P, 3).groebner_fan().render3d() # needs sage.plot Traceback (most recent call last): ... @@ -1608,10 +1599,10 @@ def tropical_basis(self, check=True, verbose=False): INPUT: - - ``check`` -- bool (default: ``True``); if True raises a - ValueError exception if this ideal does not define a tropical curve - (i.e., the condition that R/I has dimension equal to 1 + the - dimension of the homogeneity space is not satisfied). + - ``check`` -- boolean (default: ``True``); if ``True`` raises a + :exc:`ValueError` exception if this ideal does not define a tropical + curve (i.e., the condition that R/I has dimension equal to 1 + the + dimension of the homogeneity space is not satisfied) EXAMPLES:: @@ -1672,9 +1663,9 @@ def tropical_intersection(self, parameters=[], symmetry_generators=[], *args, ** INPUT: - - ``parameters`` (optional) -- a list of variables to be + - ``parameters`` -- (optional) list of variables to be considered as parameters - - ``symmetry_generators`` (optional) -- generators of the symmetry group + - ``symmetry_generators`` -- (optional) generators of the symmetry group OUTPUT: a TropicalPrevariety object @@ -1776,12 +1767,11 @@ def __init__(self, groebner_fan, gens, gfan_gens): INPUT: - - ``groebner_fan`` -- a GroebnerFan object from an - ideal + - ``groebner_fan`` -- a GroebnerFan object from an ideal - - ``gens`` -- the generators of the ideal + - ``gens`` -- the generators of the ideal - - ``gfan_gens`` -- the generators as a gfan string + - ``gfan_gens`` -- the generators as a gfan string EXAMPLES:: @@ -1888,9 +1878,9 @@ def groebner_cone(self, restrict=False): INPUT: - - ``restrict`` -- bool (default: ``False``); if True, add - an inequality for each coordinate, so that the cone is restricted - to the positive orthant. + - ``restrict`` -- boolean (default: ``False``); if ``True``, add + an inequality for each coordinate, so that the cone is restricted + to the positive orthant OUTPUT: tuple of integer vectors diff --git a/src/sage/rings/polynomial/hilbert.pyx b/src/sage/rings/polynomial/hilbert.pyx index 59ba9bc1304..24728bef328 100644 --- a/src/sage/rings/polynomial/hilbert.pyx +++ b/src/sage/rings/polynomial/hilbert.pyx @@ -93,7 +93,7 @@ cdef inline list interred(list L): INPUT: - - ``L`` -- a list of :class:`~sage.rings.polynomial.polydict.ETuple` + - ``L`` -- list of :class:`~sage.rings.polynomial.polydict.ETuple` OUTPUT: @@ -431,7 +431,8 @@ def first_hilbert_series(I, grading=None, return_grading=False): - ``I`` -- a monomial ideal (possibly defined in singular) - ``grading`` -- (optional) a list or tuple of integers used as degree weights - - ``return_grading`` -- (default: ``False``) whether to return the grading + - ``return_grading`` -- boolean (default: ``False``); whether to return the + grading OUTPUT: diff --git a/src/sage/rings/polynomial/infinite_polynomial_element.py b/src/sage/rings/polynomial/infinite_polynomial_element.py index bb263b21a51..db55eff5dd1 100644 --- a/src/sage/rings/polynomial/infinite_polynomial_element.py +++ b/src/sage/rings/polynomial/infinite_polynomial_element.py @@ -54,8 +54,8 @@ Note that ``P(0)==0``, and thus variables of index zero are invariant under the permutation action. More generally, if ``P`` is any -callable object that accepts non-negative integers as input and -returns non-negative integers, then ``c^P`` means to apply ``P`` to +callable object that accepts nonnegative integers as input and +returns nonnegative integers, then ``c^P`` means to apply ``P`` to the variable indices occurring in ``c``. If you want to substitute variables you can use the standard polynomial @@ -121,8 +121,8 @@ class InfinitePolynomial(CommutativePolynomial, metaclass=InheritComparisonClass INPUT: - - ``A`` -- an Infinite Polynomial Ring. - - ``p`` -- a *classical* polynomial that can be interpreted in ``A``. + - ``A`` -- an Infinite Polynomial Ring + - ``p`` -- a *classical* polynomial that can be interpreted in ``A`` ASSUMPTIONS: @@ -175,7 +175,6 @@ class InfinitePolynomial(CommutativePolynomial, metaclass=InheritComparisonClass sage: Y(a) alpha_2^2 + alpha_1^2 - """ @staticmethod @@ -254,7 +253,6 @@ def __init__(self, A, p): sage: a = x[1] + x[2] sage: a == loads(dumps(a)) True - """ # Despite the above comment, it can still happen that p is in @@ -309,7 +307,6 @@ def polynomial(self): over Finite Field of size 7 sage: p.parent() Infinite polynomial ring in x, y over Finite Field of size 7 - """ return self._p @@ -384,7 +381,6 @@ def __getattr__(self, s): 'p.content_ideal'] sage: 'constant_coefficient' in dir(p) # indirect doctest True - """ if s == '__members__': return dir(self._p) @@ -405,9 +401,7 @@ def subs(self, fixed=None, **kwargs): - ``fixed`` -- (optional) ``dict`` with ``{variable: value}`` pairs - ``**kwargs`` -- named parameters - OUTPUT: - - the resulting substitution + OUTPUT: the resulting substitution EXAMPLES:: @@ -492,7 +486,6 @@ def ring(self): sage: p = x[100]*y[1]^3*x[1]^2 + 2*x[10]*y[30] sage: p.ring() Infinite polynomial ring in x, y over Integer Ring - """ return self.parent() @@ -574,7 +567,6 @@ def variables(self): (x_1,) sage: X(1).variables() () - """ if hasattr(self._p, 'variables'): return tuple(self._p.variables()) @@ -605,7 +597,6 @@ def _rmul_(self, left): sage: R. = InfinitePolynomialRing(QQ, implementation='sparse') sage: R.from_base_ring(4) # indirect doctest 4 - """ return type(self)(self.parent(), left * self._p) @@ -616,7 +607,6 @@ def _lmul_(self, right): sage: R. = InfinitePolynomialRing(QQ, implementation='sparse') sage: alpha[3]*4 # indirect doctest 4*alpha_3 - """ return type(self)(self.parent(), self._p * right) @@ -642,7 +632,7 @@ def _div_(self, x): sage: q.parent() Infinite polynomial ring in x over Rational Field - Division by a non-zero element:: + Division by a nonzero element:: sage: R. = InfinitePolynomialRing(QQ, implementation='sparse') sage: 1/x[1] @@ -705,7 +695,6 @@ def lm(self): sage: p = 2*x[10]*y[30] + x[10]*y[1]^3*x[1]^2 sage: p.lm() x_10*x_1^2*y_1^3 - """ if hasattr(self._p, 'lm'): return InfinitePolynomial(self.parent(), self._p.lm()) @@ -727,7 +716,6 @@ def lc(self): sage: p = 2*x[10]*y[30] + 3*x[10]*y[1]^3*x[1]^2 sage: p.lc() 3 - """ if hasattr(self._p, 'lc'): return self._p.lc() @@ -747,7 +735,6 @@ def lt(self): sage: p = 2*x[10]*y[30] + 3*x[10]*y[1]^3*x[1]^2 sage: p.lt() 3*x_10*x_1^2*y_1^3 - """ if hasattr(self._p, 'lt'): return InfinitePolynomial(self.parent(), self._p.lt()) @@ -767,7 +754,6 @@ def tail(self): sage: p = 2*x[10]*y[30] + 3*x[10]*y[1]^3*x[1]^2 sage: p.tail() 2*x_10*y_30 - """ return self-self.lt() @@ -787,7 +773,6 @@ def squeezed(self): sage: p = x[1]*y[100] + x[50]*y[1000] sage: p.squeezed() x_2*y_4 + x_1*y_3 - """ Indices = set([0] + [Integer(str(Y).split('_')[1]) for Y in self.variables()]) @@ -802,9 +787,7 @@ def footprint(self): """ Leading exponents sorted by index and generator. - OUTPUT: - - ``D`` -- a dictionary whose keys are the occurring variable indices. + OUTPUT: ``D``; dictionary whose keys are the occurring variable indices ``D[s]`` is a list ``[i_1,...,i_n]``, where ``i_j`` gives the exponent of ``self.parent().gen(j)[s]`` in the leading @@ -832,7 +815,6 @@ def footprint(self): sage: p = a[12]^3*a[2]^7*a[4] + a[4]*a[2] sage: sorted(p.footprint().items()) [(2, [7]), (4, [1]), (12, [3])] - """ if not self._has_footprint: PARENT = self.parent() @@ -865,11 +847,11 @@ def symmetric_cancellation_order(self, other): INPUT: - ``self``, ``other`` -- two Infinite Polynomials + - ``self``, ``other`` -- two Infinite Polynomials ASSUMPTION: - Both Infinite Polynomials are non-zero. + Both Infinite Polynomials are nonzero. OUTPUT: @@ -903,7 +885,6 @@ def symmetric_cancellation_order(self, other): (None, 1, 1) sage: (x[2]*x[1]*y[1]).symmetric_cancellation_order(x[2]*x[3]*y[2]) (-1, [2, 3, 1], 1) - """ PARENT = self.parent() other = PARENT(other) @@ -987,7 +968,7 @@ def symmetric_cancellation_order(self, other): def coefficient(self, monomial): """ - Returns the coefficient of a monomial in this polynomial. + Return the coefficient of a monomial in this polynomial. INPUT: @@ -1015,7 +996,6 @@ def coefficient(self, monomial): sage: a.coefficient({x[0]:1, x[1]:1}) 2 - """ if self._p == 0: res = 0 @@ -1062,16 +1042,14 @@ def reduce(self, I, tailreduce=False, report=None): INPUT: - ``I`` -- a :class:`~sage.rings.polynomial.symmetric_ideal.SymmetricIdeal` or a list - of Infinite Polynomials. - - ``tailreduce`` -- (bool, default ``False``) *Tail reduction* is performed if this + of Infinite Polynomials + - ``tailreduce`` -- boolean (default: ``False``); *tail reduction* is performed if this parameter is ``True``. - - ``report`` -- (object, default ``None``) If not ``None``, some information on the + - ``report`` -- object (default: ``None``); if not ``None``, some information on the progress of computation is printed, since reduction of huge polynomials may take - a long time. - - OUTPUT: + a long time - Symmetrical reduction of ``self`` with respect to ``I``, possibly with tail reduction. + OUTPUT: symmetrical reduction of ``self`` with respect to ``I``, possibly with tail reduction THEORY: @@ -1125,7 +1103,6 @@ def reduce(self, I, tailreduce=False, report=None): the reduction process is finished (there could only be several non-trivial rounds if `I` was generated by more than one polynomial). - """ from sage.rings.polynomial.symmetric_reduction import SymmetricReductionStrategy if hasattr(I, 'gens'): @@ -1143,11 +1120,10 @@ def stretch(self, k): INPUT: - - ``k`` -- an integer. - - OUTPUT: + - ``k`` -- integer - Replace `v_n` with `v_{n\cdot k}` for all generators `v_\ast` occurring in self. + OUTPUT: replace `v_n` with `v_{n\cdot k}` for all generators `v_\ast` + occurring in ``self`` EXAMPLES:: @@ -1173,7 +1149,6 @@ def stretch(self, k): sage: a = x[2] + x[3] sage: a.stretch(2000) x_6000 + x_4000 - """ def P(n): return k*n @@ -1197,7 +1172,7 @@ def __iter__(self): def gcd(self, x): """ - computes the greatest common divisor + Compute the greatest common divisor. EXAMPLES:: @@ -1221,7 +1196,7 @@ class InfinitePolynomial_sparse(InfinitePolynomial): INPUT: - ``A`` -- an Infinite Polynomial Ring in sparse implementation - - ``p`` -- a *classical* polynomial that can be interpreted in ``A``. + - ``p`` -- a *classical* polynomial that can be interpreted in ``A`` Of course, one should not directly invoke this class, but rather construct elements of ``A`` in the usual way. @@ -1239,7 +1214,6 @@ class InfinitePolynomial_sparse(InfinitePolynomial): sage: p.polynomial().parent() Multivariate Polynomial Ring in b_100, b_0, c_4, c_0 over Univariate Polynomial Ring in a over Rational Field - """ def __call__(self, *args, **kwargs): @@ -1334,7 +1308,6 @@ def _mul_(self, x): sage: X. = InfinitePolynomialRing(ZZ) sage: x[2]*x[1] # indirect doctest x_2*x_1 - """ try: return InfinitePolynomial_sparse(self.parent(), self._p * x._p) @@ -1358,7 +1331,6 @@ def _sub_(self, x): sage: X. = InfinitePolynomialRing(QQ) sage: x[2] - x[1] # indirect doctest x_2 - x_1 - """ try: return InfinitePolynomial_sparse(self.parent(), self._p - x._p) @@ -1377,12 +1349,12 @@ def _sub_(self, x): def __pow__(self, n): """ - Exponentiation by an integer, or action by a callable object + Exponentiation by an integer, or action by a callable object. NOTE: - The callable object must accept non-negative integers as input - and return non-negative integers. Typical use case is a + The callable object must accept nonnegative integers as input + and return nonnegative integers. Typical use case is a permutation, that will result in the corresponding permutation of variables. @@ -1393,7 +1365,6 @@ def __pow__(self, n): sage: P = Permutation(((1,2),(3,4,5))) sage: p^P # indirect doctest x_10*y_1 + 2*x_2*y_4 - """ P = self.parent() if callable(n): @@ -1437,7 +1408,7 @@ def _richcmp_(self, x, op): NOTE: - Let x and y be generators of the parent of self. We only consider + Let x and y be generators of the parent of ``self``. We only consider monomial orderings in which x[m] > y[n] iff x appears earlier in the list of generators than y, or x==y and m>n @@ -1486,7 +1457,6 @@ def _richcmp_(self, x, op): sage: q = Y('x_1*x_0^2 + x_0*y_1*y_0') sage: p < q False - """ # We can assume that self.parent() is x.parent(), # but of course the underlying polynomial rings @@ -1522,11 +1492,10 @@ class InfinitePolynomial_dense(InfinitePolynomial): INPUT: - ``A`` -- an Infinite Polynomial Ring in dense implementation - - ``p`` -- a *classical* polynomial that can be interpreted in ``A``. + - ``p`` -- a *classical* polynomial that can be interpreted in ``A`` Of course, one should not directly invoke this class, but rather construct elements of ``A`` in the usual way. - """ def __call__(self, *args, **kwargs): @@ -1546,7 +1515,6 @@ def __call__(self, *args, **kwargs): sage: a(x_1=x[100]) x_100 + x_0 - """ # Replace any InfinitePolynomials by their underlying polynomials for kw in kwargs: @@ -1589,7 +1557,6 @@ def _richcmp_(self, x, op): sage: q = Y('x_1*x_0^2 + x_0*y_1*y_0') sage: p < q False - """ # We can assume that self and x belong to the same ring. # We can not assume yet that self._p and @@ -1614,7 +1581,6 @@ def _add_(self, x): sage: X. = InfinitePolynomialRing(QQ) sage: x[1] + x[2] # indirect doctest x_2 + x_1 - """ P = self.parent() self._p = P._P(self._p) @@ -1628,7 +1594,6 @@ def _mul_(self, x): sage: X. = InfinitePolynomialRing(QQ) sage: x[2]*x[1] # indirect doctest x_2*x_1 - """ P = self.parent() self._p = P._P(self._p) @@ -1642,7 +1607,6 @@ def _sub_(self, x): sage: X. = InfinitePolynomialRing(QQ) sage: x[2] - x[1] # indirect doctest x_2 - x_1 - """ P = self.parent() self._p = P._P(self._p) @@ -1651,12 +1615,12 @@ def _sub_(self, x): def __pow__(self, n): """ - Exponentiation by an integer, or action by a callable object + Exponentiation by an integer, or action by a callable object. NOTE: - The callable object must accept non-negative integers as input - and return non-negative integers. Typical use case is a + The callable object must accept nonnegative integers as input + and return nonnegative integers. Typical use case is a permutation, that will result in the corresponding permutation of variables. @@ -1669,7 +1633,6 @@ def __pow__(self, n): sage: P = Permutation(((1,2),(3,4,5))) sage: p^P x_10*y_1 + 2*x_2*y_4 - """ P = self.parent() if callable(n): diff --git a/src/sage/rings/polynomial/infinite_polynomial_ring.py b/src/sage/rings/polynomial/infinite_polynomial_ring.py index 75ca69f979a..afa4a4dc416 100644 --- a/src/sage/rings/polynomial/infinite_polynomial_ring.py +++ b/src/sage/rings/polynomial/infinite_polynomial_ring.py @@ -17,10 +17,10 @@ INPUT: -- ``R``, the base ring. It has to be a commutative ring, and in some +- ``R`` -- the base ring; it has to be a commutative ring, and in some applications it must even be a field -- ``names``, a finite list of generator names. Generator names must be alpha-numeric. -- ``order`` (optional string). The default order is ``'lex'`` (lexicographic). +- ``names`` -- a finite list of generator names; generator names must be alpha-numeric +- ``order`` -- (optional) string; the default order is ``'lex'`` (lexicographic). ``'deglex'`` is degree lexicographic, and ``'degrevlex'`` (degree reverse lexicographic) is possible but discouraged. @@ -300,11 +300,10 @@ class InfinitePolynomialRingFactory(UniqueFactory): sage: X is loads(dumps(X)) True - """ def create_key(self, R, names=('x',), order='lex', implementation='dense'): """ - Creates a key which uniquely defines the infinite polynomial ring. + Create a key which uniquely defines the infinite polynomial ring. TESTS:: @@ -331,7 +330,7 @@ def create_key(self, R, names=('x',), order='lex', implementation='dense'): sage: _[0].all [FractionField, InfPoly{[x], "lex", "dense"}] - If it is attempted to use no generator, a :class:`ValueError` is raised:: + If it is attempted to use no generator, a :exc:`ValueError` is raised:: sage: InfinitePolynomialRing.create_key(ZZ, names=[]) Traceback (most recent call last): @@ -410,13 +409,12 @@ class InfiniteGenDict: sage: sage_eval('3*a_3*b_5-1/2*a_7', D._D[0]) -1/2*a_7 + 3*a_3*b_5 - """ def __init__(self, Gens): """ INPUT: - - ``Gens`` -- a list of generators of an infinite polynomial ring. + - ``Gens`` -- list of generators of an infinite polynomial ring EXAMPLES:: @@ -663,7 +661,6 @@ class InfinitePolynomialRing_sparse(CommutativeRing): See :mod:`~sage.rings.polynomial.infinite_polynomial_ring` for more details. - """ def __init__(self, R, names, order): """ @@ -813,7 +810,6 @@ def construction(self): sage: R. = InfinitePolynomialRing(GF(5)) sage: R.construction() [InfPoly{[x,y], "lex", "dense"}, Finite Field of size 5] - """ return [InfinitePolynomialFunctor(self._names, self._order, 'sparse'), self._base] @@ -865,7 +861,7 @@ def _element_constructor_(self, x): INPUT: - - ``x`` -- any object that can be interpreted in ``self``. + - ``x`` -- any object that can be interpreted in ``self`` TESTS:: @@ -1048,7 +1044,7 @@ def tensor_with_ring(self, R): INPUT: - - ``R`` -- a ring. + - ``R`` -- a ring OUTPUT: @@ -1057,7 +1053,7 @@ def tensor_with_ring(self, R): NOTE: - It is required that the underlying ring of self coerces into ``R``. + It is required that the underlying ring of ``self`` coerces into ``R``. Hence, the tensor product is in fact merely an extension of the base ring. @@ -1156,19 +1152,17 @@ def varname_key(self, x): INPUT: - - ``x`` -- a string of the form ``a+'_'+str(n)``, where a is the + - ``x`` -- string of the form ``a+'_'+str(n)``, where a is the name of a generator, and n is an integer - RETURN: - - a key used to sort the variables + OUTPUT: a key used to sort the variables THEORY: The order is defined as follows: x = InfinitePolynomialRing(QQ) sage: X.ngens() 2 - """ return len(self._names) @cached_method def gen(self, i=None): """ - Return the `i^{th}` 'generator' (see the description in :meth:`.ngens`) + Return the `i`-th 'generator' (see the description in :meth:`.ngens`) of this infinite polynomial ring. EXAMPLES:: @@ -1286,7 +1279,6 @@ def _ideal_class_(self, n=0): sage: R. = InfinitePolynomialRing(ZZ) sage: R._ideal_class_() - """ import sage.rings.polynomial.symmetric_ideal return sage.rings.polynomial.symmetric_ideal.SymmetricIdeal @@ -1302,7 +1294,6 @@ def characteristic(self): Infinite polynomial ring in x, y over Finite Field in a of size 5^2 sage: X.characteristic() # needs sage.rings.finite_rings 5 - """ return self._base.characteristic() @@ -1386,7 +1377,6 @@ class InfinitePolynomialGen(SageObject): x1_5 sage: x1 == loads(dumps(x1)) True - """ def __init__(self, parent, name): @@ -1396,7 +1386,6 @@ def __init__(self, parent, name): sage: X. = InfinitePolynomialRing(QQ) sage: loads(dumps(x)) x_* - """ self._name = name self._parent = parent @@ -1456,7 +1445,7 @@ def __getitem__(self, i): """ Return the variable ``x[i]`` where ``x`` is this :class:`sage.rings.polynomial.infinite_polynomial_ring.InfinitePolynomialGen`, - and i is a non-negative integer. + and i is a nonnegative integer. EXAMPLES:: @@ -1468,7 +1457,7 @@ def __getitem__(self, i): raise ValueError("the index (= %s) must be an integer" % i) i = int(i) if i < 0: - raise ValueError("the index (= %s) must be non-negative" % i) + raise ValueError("the index (= %s) must be nonnegative" % i) P = self._parent from sage.rings.polynomial.infinite_polynomial_element import InfinitePolynomial_dense, InfinitePolynomial_sparse from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing @@ -1536,7 +1525,7 @@ def __str__(self): class InfinitePolynomialRing_dense(InfinitePolynomialRing_sparse): """ - Dense implementation of Infinite Polynomial Rings + Dense implementation of Infinite Polynomial Rings. Compared with :class:`~sage.rings.polynomial.infinite_polynomial_ring.InfinitePolynomialRing_sparse`, from which this class inherits, it keeps a polynomial ring that comprises all elements that have @@ -1549,7 +1538,6 @@ def __init__(self, R, names, order): sage: X. = InfinitePolynomialRing(ZZ, implementation='dense') sage: X == loads(dumps(X)) True - """ if not names: names = ['x'] @@ -1585,7 +1573,7 @@ def tensor_with_ring(self, R): INPUT: - - ``R`` -- a ring. + - ``R`` -- a ring OUTPUT: @@ -1594,7 +1582,7 @@ def tensor_with_ring(self, R): NOTE: - It is required that the underlying ring of self coerces into ``R``. + It is required that the underlying ring of ``self`` coerces into ``R``. Hence, the tensor product is in fact merely an extension of the base ring. @@ -1611,7 +1599,6 @@ def tensor_with_ring(self, R): sage: R. = InfinitePolynomialRing(QQ, implementation='sparse') sage: R.tensor_with_ring(QQ) is R True - """ if not R.has_coerce_map_from(self._underlying_ring): raise TypeError("we cannot tensor with " + repr(R)) @@ -1631,7 +1618,7 @@ def polynomial_ring(self): """ Return the underlying *finite* polynomial ring. - .. note:: + .. NOTE:: The ring returned can change over time as more variables are used. @@ -1649,6 +1636,5 @@ def polynomial_ring(self): sage: X.polynomial_ring() Multivariate Polynomial Ring in xx_3, xx_2, xx_1, xx_0, yy_3, yy_2, yy_1, yy_0 over Integer Ring - """ return self._P diff --git a/src/sage/rings/polynomial/integer_valued_polynomials.py b/src/sage/rings/polynomial/integer_valued_polynomials.py index 2197ac7f3d3..233c0cb800b 100644 --- a/src/sage/rings/polynomial/integer_valued_polynomials.py +++ b/src/sage/rings/polynomial/integer_valued_polynomials.py @@ -36,7 +36,7 @@ class IntegerValuedPolynomialRing(UniqueRepresentation, Parent): The integer-valued polynomial ring over a base ring `R`. Integer-valued polynomial rings are commutative and associative - algebras, with a basis indexed by non-negative integers. + algebras, with a basis indexed by nonnegative integers. There are two natural bases, made of the sequence `\binom{x}{n}` for `n \geq 0` (the *binomial basis*) and of @@ -189,7 +189,7 @@ def from_polynomial(self, p): """ Convert a polynomial into the ring of integer-valued polynomials. - This raises a :class:`ValueError` if this is not possible. + This raises a :exc:`ValueError` if this is not possible. INPUT: @@ -331,7 +331,7 @@ def shift(self, j=1): INPUT: - - `j` -- integer (default: 1) + - ``j`` -- integer (default: 1) In the binomial basis, the shift by 1 corresponds to a summation operator from `0` to `x`. @@ -470,7 +470,7 @@ def __init__(self, A): CombinatorialFreeModule.__init__(self, A.base_ring(), NonNegativeIntegers(), category=A.Bases(), - prefix="S", + prefix='S', latex_prefix=r"\mathbb{S}") def _realization_name(self) -> str: @@ -514,7 +514,7 @@ def _from_binomial_basis(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -537,7 +537,7 @@ def from_h_vector(self, h): INPUT: - - ``h`` -- a tuple or vector + - ``h`` -- tuple or vector .. SEEALSO:: :meth:`Element.h_vector` @@ -692,7 +692,7 @@ def _poly(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -757,7 +757,7 @@ def variable_shift(self, k=1): INPUT: - - `k` -- integer (default: 1) + - ``k`` -- integer (default: 1) EXAMPLES:: @@ -981,7 +981,7 @@ def __init__(self, A) -> None: """ CombinatorialFreeModule.__init__(self, A.base_ring(), NonNegativeIntegers(), - latex_prefix="", + latex_prefix='', category=A.Bases()) def _realization_name(self) -> str: @@ -1026,7 +1026,7 @@ def _from_shifted_basis(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1174,7 +1174,7 @@ def _poly(self, i): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -1195,7 +1195,7 @@ def variable_shift(self, k=1): INPUT: - - `k` -- integer (default: 1) + - ``k`` -- integer (default: 1) EXAMPLES:: diff --git a/src/sage/rings/polynomial/laurent_polynomial.pyx b/src/sage/rings/polynomial/laurent_polynomial.pyx index 650388e7f0f..70cec491cae 100644 --- a/src/sage/rings/polynomial/laurent_polynomial.pyx +++ b/src/sage/rings/polynomial/laurent_polynomial.pyx @@ -13,7 +13,7 @@ from sage.structure.element import coerce_binop, parent from sage.structure.factorization import Factorization from sage.misc.derivative import multi_derivative from sage.rings.polynomial.polynomial_element import Polynomial -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.structure.richcmp cimport richcmp, rich_to_bool from sage.rings.infinity import minus_infinity @@ -40,7 +40,7 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): cpdef _add_(self, other): """ - Abstract addition method + Abstract addition method. EXAMPLES:: @@ -55,7 +55,7 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): cpdef _mul_(self, other): """ - Abstract multiplication method + Abstract multiplication method. EXAMPLES:: @@ -70,7 +70,7 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): cpdef _floordiv_(self, other): """ - Abstract floor division method + Abstract floor division method. EXAMPLES:: @@ -89,9 +89,7 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): This is only possible if the Laurent polynomial is constant. - OUTPUT: - - An integer. + OUTPUT: integer TESTS:: @@ -136,9 +134,7 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): This is only possible if the Laurent polynomial is constant. - OUTPUT: - - A rational. + OUTPUT: a rational TESTS:: @@ -210,7 +206,7 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): """ Return the hamming weight of ``self``. - The hamming weight is number of non-zero coefficients and + The hamming weight is number of nonzero coefficients and also known as the weight or sparsity. EXAMPLES:: @@ -248,10 +244,10 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): INPUT: - - ``f`` -- a callable that will be applied to the coefficients of ``self``. + - ``f`` -- a callable that will be applied to the coefficients of ``self`` - - ``new_base_ring`` (optional) -- if given, the resulting polynomial - will be defined over this ring. + - ``new_base_ring`` -- (optional) if given, the resulting polynomial + will be defined over this ring EXAMPLES:: @@ -292,7 +288,6 @@ cdef class LaurentPolynomial(CommutativeAlgebraElement): X - Y sage: g.parent() Multivariate Laurent Polynomial Ring in X, Y over Finite Field of size 3 - """ R = self.parent() if new_base_ring is not None: @@ -311,9 +306,9 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): - ``parent`` -- a Laurent polynomial ring - - ``f`` -- a polynomial (or something can be coerced to one) + - ``f`` -- a polynomial (or something that can be coerced to one) - - ``n`` -- (default: 0) an integer + - ``n`` -- integer (default: 0) AUTHORS: @@ -431,7 +426,7 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): if self.__n < 0: raise ValueError("Laurent polynomial with negative valuation cannot be converted to polynomial") - if is_PolynomialRing(R): + if isinstance(R, PolynomialRing_general): return R(self.__u) << self.__n elif self.__n == 0: return R(self.__u) @@ -486,7 +481,7 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): def __bool__(self): """ - Check if ``self`` is non-zero. + Check if ``self`` is nonzero. EXAMPLES:: @@ -773,7 +768,7 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): cpdef long number_of_terms(self) except -1: """ - Return the number of non-zero coefficients of ``self``. + Return the number of nonzero coefficients of ``self``. Also called weight, hamming weight or sparsity. @@ -1384,7 +1379,7 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): def inverse_mod(a, m): """ - Invert the polynomial ``a`` with respect to ``m``, or raise a :class:`ValueError` + Invert the polynomial ``a`` with respect to ``m``, or raise a :exc:`ValueError` if no such inverse exists. The parameter ``m`` may be either a single polynomial or an ideal @@ -1401,8 +1396,8 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): sage: f * (t^-2 + 1) + (1/2*t^4 + 1/2*t^3) * (t^-3 + 1) 1 """ - from sage.rings.ideal import is_Ideal - if is_Ideal(m): + from sage.rings.ideal import Ideal_generic + if isinstance(m, Ideal_generic): v = m.gens_reduced() if len(v) > 1: raise NotImplementedError("only inversion modulo principal ideals implemented") @@ -2127,7 +2122,6 @@ cdef class LaurentPolynomial_univariate(LaurentPolynomial): -tinv^2 + t sage: _.parent() Multivariate Polynomial Ring in t, tinv over Rational Field - """ dres = {} for (e, c) in self.dict().items(): diff --git a/src/sage/rings/polynomial/laurent_polynomial_ideal.py b/src/sage/rings/polynomial/laurent_polynomial_ideal.py index db09032f7c5..ae21901fee1 100644 --- a/src/sage/rings/polynomial/laurent_polynomial_ideal.py +++ b/src/sage/rings/polynomial/laurent_polynomial_ideal.py @@ -48,7 +48,7 @@ def __init__(self, ring, gens, coerce=True, hint=None): INPUT: - ``ring`` -- the ring the ideal is defined in - - ``gens`` -- a list of generators for the ideal + - ``gens`` -- list of generators for the ideal - ``coerce`` -- whether or not to coerce elements into ``ring`` - ``hint`` -- an ideal in the associated polynomial ring (optional; see above) diff --git a/src/sage/rings/polynomial/laurent_polynomial_mpair.pyx b/src/sage/rings/polynomial/laurent_polynomial_mpair.pyx index 4d40075c619..e6ea53e1756 100644 --- a/src/sage/rings/polynomial/laurent_polynomial_mpair.pyx +++ b/src/sage/rings/polynomial/laurent_polynomial_mpair.pyx @@ -39,7 +39,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): - ``mon`` -- (default: ``None``) a tuple specifying the shift in the exponents - - ``reduce`` -- (default: ``True``) a boolean + - ``reduce`` -- boolean (default: ``True``) EXAMPLES:: @@ -259,7 +259,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -401,7 +401,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): cpdef long number_of_terms(self) except -1: """ - Return the number of non-zero coefficients of ``self``. + Return the number of nonzero coefficients of ``self``. Also called weight, hamming weight or sparsity. @@ -495,7 +495,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): `n` is a tuple of length `k` and `k` is the number of variables. If the number of inputs is not equal to the number of variables, this - raises a ``TypeError``. + raises a :exc:`TypeError`. EXAMPLES:: @@ -572,7 +572,6 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): -t2inv^2 + t1 sage: _.parent() Multivariate Polynomial Ring in t1, t1inv, t2, t2inv over Rational Field - """ dres = {} for (e, c) in self.dict().items(): @@ -700,9 +699,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): - ``mon`` -- a monomial - OUTPUT: - - Element of the parent of ``self``. + OUTPUT: element of the parent of ``self`` .. NOTE:: @@ -1059,9 +1056,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): - ``right`` -- a Laurent polynomial - OUTPUT: - - A pair of Laurent polynomials. + OUTPUT: a pair of Laurent polynomials EXAMPLES:: @@ -1151,7 +1146,6 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): sage: e = a.exponents() sage: e.sort(); e [(0, 0), (2, -1)] - """ return [a.eadd(self._mon) for a in self._poly.exponents()] @@ -1284,7 +1278,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): """ INPUT: - - ``i`` -- The index of a generator of ``self.parent()`` + - ``i`` -- the index of a generator of ``self.parent()`` OUTPUT: @@ -1313,7 +1307,8 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): def has_any_inverse(self): """ - Return ``True`` if ``self`` contains any monomials with a negative exponent, False otherwise. + Return ``True`` if ``self`` contains any monomials with a negative + exponent, ``False`` otherwise. EXAMPLES:: @@ -1405,9 +1400,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): - ``**kwds`` -- keyword arguments - OUTPUT: - - A Laurent polynomial. + OUTPUT: a Laurent polynomial EXAMPLES:: @@ -1605,7 +1598,7 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): - ``R`` -- (default: ``None``) a univariate Laurent polynomial ring If this polynomial is not in at most one variable, then a - :class:`ValueError` exception is raised. The new polynomial is over + :exc:`ValueError` exception is raised. The new polynomial is over the same base ring as the given :class:`LaurentPolynomial` and in the variable ``x`` if no ring ``R`` is provided. @@ -1734,10 +1727,10 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): INPUT: - - ``root`` -- boolean (default ``False``); if set to ``True`` + - ``root`` -- boolean (default: ``False``); if set to ``True`` then return a pair ``(True, sqrt)`` with ``sqrt`` a square root of this Laurent polynomial when it exists or - ``(False, None)``. + ``(False, None)`` EXAMPLES:: @@ -1862,7 +1855,6 @@ cdef class LaurentPolynomial_mpair(LaurentPolynomial): sage: p.toric_coordinate_change(Matrix([[1,-3], [1,1]]), ....: new_ring=L.change_ring(F)) x^-2*y^2 + x^-3*y - """ cdef int n, i, j, x cdef dict d, dr diff --git a/src/sage/rings/polynomial/laurent_polynomial_ring.py b/src/sage/rings/polynomial/laurent_polynomial_ring.py index c10db4a39ca..680c4c0138c 100644 --- a/src/sage/rings/polynomial/laurent_polynomial_ring.py +++ b/src/sage/rings/polynomial/laurent_polynomial_ring.py @@ -95,14 +95,14 @@ def LaurentPolynomialRing(base_ring, *args, **kwds): INPUT: - ``base_ring`` -- a commutative ring - - ``name`` -- a string - - ``names`` -- a list or tuple of names, or a comma separated string - - ``n`` -- a positive integer - - ``sparse`` -- bool (default: ``False``), whether or not elements are sparse + - ``name`` -- string + - ``names`` -- list or tuple of names, or a comma separated string + - ``n`` -- positive integer + - ``sparse`` -- boolean (default: ``False``); whether or not elements are sparse - ``order`` -- string or :class:`~sage.rings.polynomial.term_order.TermOrder`, e.g., - - ``'degrevlex'`` (default) -- degree reverse lexicographic + - ``'degrevlex'`` -- default; degree reverse lexicographic - ``'lex'`` -- lexicographic - ``'deglex'`` -- degree lexicographic - ``TermOrder('deglex',3) + TermOrder('deglex',3)`` -- block ordering @@ -136,7 +136,6 @@ def LaurentPolynomialRing(base_ring, *args, **kwds): ... ValueError: variable names cannot be changed after object creation. - EXAMPLES: 1. ``LaurentPolynomialRing(base_ring, name, sparse=False)`` @@ -235,18 +234,18 @@ def LaurentPolynomialRing(base_ring, *args, **kwds): sage: (w0 + 2*w8 + w13)^2 # needs sage.modules w0^2 + 4*w0*w8 + 4*w8^2 + 2*w0*w13 + 4*w8*w13 + w13^2 """ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base R = PolynomialRing(base_ring, *args, **kwds) if R in _cache: return _cache[R] # put () here to re-enable weakrefs - if is_PolynomialRing(R): + if isinstance(R, PolynomialRing_general): # univariate case P = LaurentPolynomialRing_univariate(R) else: - assert is_MPolynomialRing(R) + assert isinstance(R, MPolynomialRing_base) P = LaurentPolynomialRing_mpair(R) _cache[R] = P @@ -258,16 +257,14 @@ def _split_dict_(D, indices, group_by=None): INPUT: - - ``D`` -- a dictionary. - - - ``indices`` -- a tuple or list of nonnegative integers. + - ``D`` -- dictionary - - ``group_by`` -- a tuple or list of nonnegative integers. - If this is ``None`` (default), then no grouping is done. + - ``indices`` -- tuple or list of nonnegative integers - OUTPUT: + - ``group_by`` -- tuple or list of nonnegative integers; + if this is ``None`` (default), then no grouping is done - A dictionary. + OUTPUT: a dictionary TESTS:: @@ -341,17 +338,15 @@ def _split_laurent_polynomial_dict_(P, M, d): INPUT: - - ``P`` -- the parent to which we want to convert. + - ``P`` -- the parent to which we want to convert - - ``M`` -- the parent from which we want to convert. + - ``M`` -- the parent from which we want to convert - - ``d`` -- a dictionary mapping tuples (representing the exponents) + - ``d`` -- dictionary mapping tuples (representing the exponents) to their coefficients. This is the dictionary corresponding to an element of ``M``. - OUTPUT: - - A dictionary corresponding to an element of ``P``. + OUTPUT: a dictionary corresponding to an element of ``P`` TESTS:: diff --git a/src/sage/rings/polynomial/laurent_polynomial_ring_base.py b/src/sage/rings/polynomial/laurent_polynomial_ring_base.py index 44654e1b076..71eb20cd701 100644 --- a/src/sage/rings/polynomial/laurent_polynomial_ring_base.py +++ b/src/sage/rings/polynomial/laurent_polynomial_ring_base.py @@ -46,7 +46,6 @@ class LaurentPolynomialRing_generic(CommutativeRing, Parent): over (number fields and quotient fields and metric spaces) and Category of infinite sets sage: TestSuite(R).run() - """ def __init__(self, R): """ @@ -85,7 +84,7 @@ def ngens(self): def gen(self, i=0): r""" - Returns the `i^{th}` generator of self. If i is not specified, then + Return the `i`-th generator of ``self``. If `i` is not specified, then the first generator will be returned. EXAMPLES:: @@ -119,11 +118,9 @@ def variable_names_recursive(self, depth=infinity): INPUT: - - ``depth`` -- an integer or :mod:`Infinity `. - - OUTPUT: + - ``depth`` -- integer or :mod:`Infinity ` - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -147,7 +144,7 @@ def variable_names_recursive(self, depth=infinity): def is_integral_domain(self, proof=True): """ - Return ``True`` if self is an integral domain. + Return ``True`` if ``self`` is an integral domain. EXAMPLES:: @@ -165,7 +162,7 @@ def is_integral_domain(self, proof=True): def is_noetherian(self): """ - Return ``True`` if self is Noetherian. + Return ``True`` if ``self`` is Noetherian. EXAMPLES:: @@ -183,7 +180,6 @@ def construction(self): sage: LaurentPolynomialRing(QQ, 2, 'x,y').construction() (LaurentPolynomialFunctor, Univariate Laurent Polynomial Ring in x over Rational Field) - """ from sage.categories.pushout import LaurentPolynomialFunctor from .laurent_polynomial_ring import LaurentPolynomialRing @@ -421,13 +417,12 @@ def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): def term_order(self): """ - Returns the term order of self. + Return the term order of ``self``. EXAMPLES:: sage: LaurentPolynomialRing(QQ, 2, 'x').term_order() Degree reverse lexicographic term order - """ return self._R.term_order() @@ -437,7 +432,6 @@ def is_finite(self): sage: LaurentPolynomialRing(QQ, 2, 'x').is_finite() False - """ return False @@ -452,7 +446,7 @@ def is_field(self, proof=True): def polynomial_ring(self): """ - Returns the polynomial ring associated with self. + Return the polynomial ring associated with ``self``. EXAMPLES:: @@ -465,7 +459,7 @@ def polynomial_ring(self): def characteristic(self): """ - Returns the characteristic of the base ring. + Return the characteristic of the base ring. EXAMPLES:: @@ -473,7 +467,6 @@ def characteristic(self): 0 sage: LaurentPolynomialRing(GF(3), 2, 'x').characteristic() 3 - """ return self.base_ring().characteristic() @@ -498,10 +491,10 @@ def random_element(self, min_valuation=-2, max_degree=2, *args, **kwds): INPUT: - - ``min_valuation`` -- integer (default: ``-2``); the + - ``min_valuation`` -- integer (default: `-2`); the minimal allowed valuation of the polynomial - - ``max_degree`` -- integer (default: ``2``); the + - ``max_degree`` -- integer (default: `2`); the maximal allowed degree of the polynomial - ``*args``, ``**kwds`` -- passed to the random element generator of the @@ -625,7 +618,7 @@ def random_element(self, min_valuation=-2, max_degree=2, *args, **kwds): abs_deg = (max_degree - min_valuation) f_rand = self._R.random_element(degree=abs_deg, *args, **kwds) - # Cast this polynomial back the `self`` + # Cast this polynomial back the ``self`` f = self(f_rand) # For the univariate case we simply shift by x**min_valuation diff --git a/src/sage/rings/polynomial/msolve.py b/src/sage/rings/polynomial/msolve.py index d15d498c040..fb22236fba9 100644 --- a/src/sage/rings/polynomial/msolve.py +++ b/src/sage/rings/polynomial/msolve.py @@ -136,18 +136,18 @@ def variety(ideal, ring, *, proof=True): sage: R. = PolynomialRing(GF(p), 2, order='lex') sage: I = Ideal([ x*y - 1, (x-2)^2 + (y-1)^2 - 1]) - sage: sorted(I.variety(algorithm="msolve", proof=False), key=str) # optional - msolve + sage: sorted(I.variety(algorithm='msolve', proof=False), key=str) # optional - msolve [{x: 1, y: 1}, {x: 267525699, y: 473946006}] sage: K. = GF(p^2) - sage: sorted(I.variety(K, algorithm="msolve", proof=False), key=str) # optional - msolve + sage: sorted(I.variety(K, algorithm='msolve', proof=False), key=str) # optional - msolve [{x: 1, y: 1}, {x: 118750849*a + 194048031, y: 510295713*a + 18174854}, {x: 267525699, y: 473946006}, {x: 418120060*a + 75297182, y: 26575196*a + 44750050}] sage: R. = PolynomialRing(GF(2147483659), 2, order='lex') - sage: ideal([x, y]).variety(algorithm="msolve", proof=False) + sage: ideal([x, y]).variety(algorithm='msolve', proof=False) Traceback (most recent call last): ... NotImplementedError: unsupported base field: Finite Field of size 2147483659 diff --git a/src/sage/rings/polynomial/multi_polynomial.pyx b/src/sage/rings/polynomial/multi_polynomial.pyx index 2f4a33dc358..6863e5a7316 100644 --- a/src/sage/rings/polynomial/multi_polynomial.pyx +++ b/src/sage/rings/polynomial/multi_polynomial.pyx @@ -248,7 +248,7 @@ cdef class MPolynomial(CommutativePolynomial): def truncate(self, var, n): r""" - Returns a new multivariate polynomial obtained from ``self`` by + Return a new multivariate polynomial obtained from ``self`` by deleting all terms that involve the given variable to a power at least ``n``. """ @@ -573,7 +573,6 @@ cdef class MPolynomial(CommutativePolynomial): Traceback (most recent call last): ... TypeError: unhashable type: 'sage.rings.padics.qadic_flint_CR.qAdicCappedRelativeElement' - """ cdef long result = 0 # store it in a c-int and just let the overflowing additions wrap cdef long result_mon @@ -605,7 +604,7 @@ cdef class MPolynomial(CommutativePolynomial): def args(self): r""" - Returns the names of the arguments of ``self``, in the + Return the names of the arguments of ``self``, in the order they are accepted from call. EXAMPLES:: @@ -710,7 +709,6 @@ cdef class MPolynomial(CommutativePolynomial): sage: q2 = p.homogenize() sage: q1.parent() is q2.parent() True - """ P = self.parent() @@ -784,9 +782,7 @@ cdef class MPolynomial(CommutativePolynomial): r""" Return the homogeneous components of this polynomial. - OUTPUT: - - A dictionary mapping degrees to homogeneous polynomials. + OUTPUT: a dictionary mapping degrees to homogeneous polynomials EXAMPLES:: @@ -850,7 +846,7 @@ cdef class MPolynomial(CommutativePolynomial): - ``R`` -- a ring or morphism; if a morphism, the coefficients are mapped to the codomain of ``R`` - OUTPUT: a new polynomial with the base ring changed to ``R``. + OUTPUT: a new polynomial with the base ring changed to ``R`` EXAMPLES:: @@ -925,7 +921,7 @@ cdef class MPolynomial(CommutativePolynomial): INPUT: - - ``group`` (default: symmetric group) -- if set, test whether the + - ``group`` -- (default: symmetric group) if set, test whether the polynomial is invariant with respect to the given permutation group EXAMPLES:: @@ -1008,7 +1004,7 @@ cdef class MPolynomial(CommutativePolynomial): def _gap_(self, gap): r""" - Return a representation of ``self`` in the GAP interface + Return a representation of ``self`` in the GAP interface. INPUT: @@ -1076,7 +1072,7 @@ cdef class MPolynomial(CommutativePolynomial): def _magma_init_(self, magma): r""" - Returns a Magma string representation of ``self`` valid in the + Return a Magma string representation of ``self`` valid in the given magma session. EXAMPLES:: @@ -1150,7 +1146,7 @@ cdef class MPolynomial(CommutativePolynomial): def jacobian_ideal(self): r""" - Return the Jacobian ideal of the polynomial self. + Return the Jacobian ideal of the polynomial ``self``. EXAMPLES:: @@ -1194,7 +1190,7 @@ cdef class MPolynomial(CommutativePolynomial): r""" Facilitates iterating over the monomials of ``self``, returning tuples of the form ``(coeff, mon)`` for each - non-zero monomial. + nonzero monomial. EXAMPLES:: @@ -1215,7 +1211,7 @@ cdef class MPolynomial(CommutativePolynomial): INPUT: - - ``as_ETuples`` -- (default: ``True``) if ``True``, iterate over + - ``as_ETuples`` -- boolean (default: ``True``); if ``True``, iterate over pairs whose first element is an :class:`ETuple`, otherwise as a tuples EXAMPLES:: @@ -1262,7 +1258,6 @@ cdef class MPolynomial(CommutativePolynomial): sage: f.content(); f.content().parent() 2 Rational Field - """ from sage.arith.misc import GCD as gcd return gcd(self.coefficients()) @@ -1291,8 +1286,7 @@ cdef class MPolynomial(CommutativePolynomial): def is_generator(self): r""" - Returns ``True`` if this polynomial is a generator of its - parent. + Return ``True`` if this polynomial is a generator of its parent. EXAMPLES:: @@ -1315,7 +1309,7 @@ cdef class MPolynomial(CommutativePolynomial): def map_coefficients(self, f, new_base_ring=None): r""" - Returns the polynomial obtained by applying ``f`` to the non-zero + Return the polynomial obtained by applying ``f`` to the nonzero coefficients of ``self``. If ``f`` is a :class:`sage.categories.map.Map`, then the resulting @@ -1325,10 +1319,10 @@ cdef class MPolynomial(CommutativePolynomial): INPUT: - - ``f`` -- a callable that will be applied to the coefficients of ``self``. + - ``f`` -- a callable that will be applied to the coefficients of ``self`` - - ``new_base_ring`` (optional) -- if given, the resulting polynomial - will be defined over this ring. + - ``new_base_ring`` -- (optional) if given, the resulting polynomial + will be defined over this ring EXAMPLES:: @@ -1360,7 +1354,6 @@ cdef class MPolynomial(CommutativePolynomial): X - Y sage: g.parent() Multivariate Polynomial Ring in X, Y over Finite Field of size 3 - """ R = self.parent() if new_base_ring is not None: @@ -1375,7 +1368,7 @@ cdef class MPolynomial(CommutativePolynomial): `\GF{p^e}`, compute the norm of the polynomial down to `\GF{p}`. This is the product of the conjugates by the Frobenius action - on coefficients, where Frobenius acts by p-th power. + on coefficients, where Frobenius acts by `p`-th power. This is (currently) an internal function used in factoring over finite fields. @@ -1409,13 +1402,11 @@ cdef class MPolynomial(CommutativePolynomial): INPUT: - ``self``, ``right`` -- multivariate polynomials - - ``variable`` -- optional, compute the Sylvester matrix with respect to this - variable. If ``variable`` is not provided, the first variable of the - polynomial ring is used. - - OUTPUT: + - ``variable`` -- (optional) compute the Sylvester matrix with respect + to this variable. If ``variable`` is not provided, the first variable + of the polynomial ring is used. - - The Sylvester matrix of ``self`` and ``right``. + OUTPUT: the Sylvester matrix of ``self`` and ``right`` EXAMPLES:: @@ -1508,7 +1499,6 @@ cdef class MPolynomial(CommutativePolynomial): [0 3] sage: K(3).sylvester_matrix(K(4)) [] - """ # This code is almost exactly the same as that of @@ -1557,14 +1547,14 @@ cdef class MPolynomial(CommutativePolynomial): def discriminant(self,variable): r""" - Returns the discriminant of ``self`` with respect to the given variable. + Return the discriminant of ``self`` with respect to the given variable. INPUT: - - ``variable`` -- The variable with respect to which we compute + - ``variable`` -- the variable with respect to which we compute the discriminant - OUTPUT: An element of the base ring of the polynomial ring. + OUTPUT: an element of the base ring of the polynomial ring EXAMPLES:: @@ -1622,7 +1612,7 @@ cdef class MPolynomial(CommutativePolynomial): - ``other`` -- a polynomial - OUTPUT: a list of polynomials in the same ring as ``self`` + OUTPUT: list of polynomials in the same ring as ``self`` EXAMPLES:: @@ -1635,7 +1625,6 @@ cdef class MPolynomial(CommutativePolynomial): sage: p.subresultants(q, x) [2*y^6 - 22*y^5 + 102*y^4 - 274*y^3 + 488*y^2 - 552*y + 288, x*y^2 + y^3 - 5*x*y - 6*y^2 + 6*x + 11*y - 6] - """ R = self.parent() if variable is None: @@ -1662,13 +1651,11 @@ cdef class MPolynomial(CommutativePolynomial): INPUT: - - ``args`` -- a list of `n-1` homogeneous polynomials in `n` variables. - works when ``args[0]`` is the list of polynomials, - or ``args`` is itself the list of polynomials - - OUTPUT: + - ``args`` -- list of `n-1` homogeneous polynomials in `n` variables; + works when ``args[0]`` is the list of polynomials, or ``args`` is + itself the list of polynomials - - the Macaulay resultant + OUTPUT: the Macaulay resultant EXAMPLES: @@ -1773,7 +1760,6 @@ cdef class MPolynomial(CommutativePolynomial): sage: RH = fh.parent() sage: f.resultant(g) == fh.macaulay_resultant(gh) # needs sage.modules True - """ if len(args) == 1 and isinstance(args[0],list): return self.parent().macaulay_resultant(self, *args[0]) @@ -1793,7 +1779,7 @@ cdef class MPolynomial(CommutativePolynomial): .. warning:: This is not the denominator of the rational function - defined by self, which would always be 1 since self is a + defined by ``self``, which would always be 1 since ``self`` is a polynomial. EXAMPLES: @@ -1870,7 +1856,7 @@ cdef class MPolynomial(CommutativePolynomial): .. warning:: This is not the numerator of the rational function - defined by ``self``, which would always be self since ``self`` is a + defined by ``self``, which would always be ``self`` since ``self`` is a polynomial. EXAMPLES: @@ -1948,7 +1934,7 @@ cdef class MPolynomial(CommutativePolynomial): def inverse_mod(self, I): r""" - Returns an inverse of ``self`` modulo the polynomial ideal `I`, + Return an inverse of ``self`` modulo the polynomial ideal `I`, namely a multivariate polynomial `f` such that ``self * f - 1`` belongs to `I`. @@ -1956,9 +1942,7 @@ cdef class MPolynomial(CommutativePolynomial): - ``I`` -- an ideal of the polynomial ring in which ``self`` lives - OUTPUT: - - a multivariate polynomial representing the inverse of ``f`` modulo `I` + OUTPUT: a multivariate polynomial representing the inverse of ``f`` modulo `I` EXAMPLES:: @@ -1999,11 +1983,11 @@ cdef class MPolynomial(CommutativePolynomial): INPUT: - - ``weights`` -- Either individual numbers, an iterable or a dictionary, + - ``weights`` -- either individual numbers, an iterable or a dictionary, specifying the weights of each variable. If it is a dictionary, it maps each variable of ``self`` to its weight. If it is a sequence of individual numbers or a tuple, the weights are specified in the order - of the generators as given by ``self.parent().gens()``: + of the generators as given by ``self.parent().gens()``. EXAMPLES:: @@ -2180,7 +2164,7 @@ cdef class MPolynomial(CommutativePolynomial): r""" Return a `n`-th root of this element. - If there is no such root, a ``ValueError`` is raised. + If there is no such root, a :exc:`ValueError` is raised. EXAMPLES:: @@ -2344,20 +2328,19 @@ cdef class MPolynomial(CommutativePolynomial): Implemented by Rebecca Lauren Miller as part of GSOC 2016. Smallest coefficients added by Ben Hutz July 2018. - INPUT: - - keywords: + INPUT: keyword arguments: - - ``prec`` -- integer, sets the precision (default: 300) + - ``prec`` -- integer (default: 300); sets the precision - - ``return_conjugation`` -- boolean. Returns element of `SL(2, \ZZ)` (default: ``True``) + - ``return_conjugation`` -- boolean (default: ``True``); whether to + return element of `SL(2, \ZZ)` - ``error_limit`` -- sets the error tolerance (default: 0.000001) - - ``smallest_coeffs`` -- (default: ``True``), boolean, whether to find the + - ``smallest_coeffs`` -- boolean (default: ``True``); whether to find the model with smallest coefficients - - ``norm_type`` -- either ``'norm'`` or ``'height'``. What type of norm + - ``norm_type`` -- either ``'norm'`` or ``'height'``; what type of norm to use for smallest coefficients - ``emb`` -- (optional) embedding of based field into ``CC`` @@ -2617,7 +2600,6 @@ cdef class MPolynomial(CommutativePolynomial): sage: _. = Zmod(36)[] sage: (7+ 6*x + 12*y - 18*x*y).is_unit() True - """ # EXERCISE (Atiyah-McDonald, Ch 1): Let `A[x]` be a polynomial # ring in one variable. Then `f=\sum a_i x^i \in A[x]` is a unit\ @@ -2949,7 +2931,7 @@ cdef remove_from_tuple(e, int ind): cdef class MPolynomial_libsingular(MPolynomial): r""" - Abstract base class for :class:`~sage.rings.polynomial.multi_polynomial_libsingular.MPolynomial_libsingular` + Abstract base class for :class:`~sage.rings.polynomial.multi_polynomial_libsingular.MPolynomial_libsingular`. This class is defined for the purpose of :func:`isinstance` tests. It should not be instantiated. diff --git a/src/sage/rings/polynomial/multi_polynomial_element.py b/src/sage/rings/polynomial/multi_polynomial_element.py index 91fcd38631b..0e8d831b808 100644 --- a/src/sage/rings/polynomial/multi_polynomial_element.py +++ b/src/sage/rings/polynomial/multi_polynomial_element.py @@ -123,8 +123,7 @@ def __call__(self, *x, **kwds): Evaluate this multi-variate polynomial at `x`, where `x` is either the tuple of values to substitute in, or one can use functional notation `f(a_0,a_1,a_2, \ldots)` to - evaluate `f` with the ith variable replaced by - `a_i`. + evaluate `f` with the `i`-th variable replaced by `a_i`. EXAMPLES:: @@ -246,7 +245,7 @@ def _im_gens_(self, codomain, im_gens, base_map=None): def number_of_terms(self): """ - Return the number of non-zero coefficients of this polynomial. + Return the number of nonzero coefficients of this polynomial. This is also called weight, :meth:`hamming_weight` or sparsity. @@ -330,7 +329,7 @@ def _mul_(self, right): def _lmul_(self, a): """ - Left Scalar Multiplication + Left Scalar Multiplication. EXAMPLES: @@ -351,7 +350,7 @@ def _lmul_(self, a): def _rmul_(self, a): """ - Right Scalar Multiplication + Right Scalar Multiplication. EXAMPLES: @@ -447,7 +446,6 @@ def _new_constant_poly(self, x, P): sage: R. = QQ['t'][] sage: x._new_constant_poly(R.base_ring()(2),R) 2 - """ return MPolynomial_polydict(P, {P._zero_tuple:x}) @@ -537,7 +535,7 @@ def _macaulay2_(self, macaulay2=None): def degrees(self): r""" - Returns a tuple (precisely - an ``ETuple``) with the + Return a tuple (precisely - an ``ETuple``) with the degree of each variable in this polynomial. The list of degrees is, of course, ordered by the order of the generators. @@ -748,8 +746,7 @@ def monomial_coefficient(self, mon): INPUT: - - ``mon`` -- a monomial - + - ``mon`` -- a monomial OUTPUT: coefficient in base ring @@ -855,8 +852,8 @@ def __getitem__(self, x): INPUT: - - ``x`` -- a tuple or, in case of a single-variable - MPolynomial ring x can also be an integer + - ``x`` -- tuple or, in case of a single-variable + MPolynomial ring, ``x`` can also be an integer EXAMPLES:: @@ -897,8 +894,8 @@ def iterator_exp_coeff(self, as_ETuples=True): INPUT: - - ``as_ETuples`` -- (default: ``True``) if ``True`` iterate over - pairs whose first element is an ETuple, otherwise as a tuples + - ``as_ETuples`` -- boolean (default: ``True``); if ``True`` iterate + over pairs whose first element is an ETuple, otherwise as a tuples EXAMPLES:: @@ -934,16 +931,14 @@ def coefficient(self, degrees): INPUT: + - ``degrees`` -- can be any of: - - ``degrees`` -- Can be any of: - - - a dictionary of degree restrictions - - - a list of degree restrictions (with None in - the unrestricted variables) + - a dictionary of degree restrictions - - a monomial (very fast, but not as flexible) + - a list of degree restrictions (with ``None`` in + the unrestricted variables) + - a monomial (very fast, but not as flexible) OUTPUT: element of the parent of ``self`` @@ -1022,9 +1017,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -1099,12 +1094,12 @@ def local_height(self, v, prec=None): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -1149,12 +1144,12 @@ def local_height_arch(self, i, prec=None): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -1214,12 +1209,10 @@ def exponents(self, as_ETuples=True): INPUT: - - ``as_ETuples`` -- (default: ``True``): return the list of + - ``as_ETuples`` -- (default: ``True``) return the list of exponents as a list of ETuples - OUTPUT: - - The list of exponents as a list of ETuples or tuples. + OUTPUT: the list of exponents as a list of ETuples or tuples EXAMPLES:: @@ -1303,10 +1296,8 @@ def _homogenize(self, var): INPUT: - - - ``var`` -- an integer indicating which variable to - use to homogenize (0 <= var < parent(self).ngens()) - + - ``var`` -- integer indicating which variable to + use to homogenize (``0 <= var < parent(self).ngens()``) OUTPUT: a multivariate polynomial @@ -1421,10 +1412,9 @@ def subs(self, fixed=None, **kwds): INPUT: - - ``fixed`` -- (optional) dictionary of inputs - - - ``**kwds`` -- named parameters + - ``fixed`` -- (optional) dictionary of inputs + - ``**kwds`` -- named parameters OUTPUT: new :class:`MPolynomial` @@ -1506,7 +1496,7 @@ def constant_coefficient(self): def is_univariate(self): """ Return ``True`` if this multivariate polynomial is univariate and - False otherwise. + ``False`` otherwise. EXAMPLES:: @@ -1537,17 +1527,16 @@ def is_univariate(self): def univariate_polynomial(self, R=None): """ - Returns a univariate polynomial associated to this multivariate + Return a univariate polynomial associated to this multivariate polynomial. INPUT: - - - ``R`` -- (default: None) :class:`PolynomialRing` + - ``R`` -- (default: ``None``) :class:`PolynomialRing` If this polynomial is not in at most one variable, then a - :class:`ValueError` exception is raised. This is checked using the + :exc:`ValueError` exception is raised. This is checked using the method :meth:`is_univariate`. The new :class:`Polynomial` is over the same base ring as the given :class:`MPolynomial`. @@ -1615,7 +1604,7 @@ def univariate_polynomial(self, R=None): def variables(self): """ - Returns the tuple of variables occurring in this polynomial. + Return the tuple of variables occurring in this polynomial. EXAMPLES:: @@ -1728,7 +1717,6 @@ def lm(self): sage: f = x + y sage: f.lm() x - """ try: return self.__lm @@ -1743,8 +1731,8 @@ def lm(self): def lc(self): """ - Returns the leading coefficient of ``self``, i.e., - ``self.coefficient(self.lm())`` + Return the leading coefficient of ``self``, i.e., + ``self.coefficient(self.lm())``. EXAMPLES:: @@ -1776,7 +1764,7 @@ def lt(self): sage: f = 3*x^2 - y^2 - x*y sage: f.lt() 3*x^2 - sage: R. = PolynomialRing(QQbar, order="invlex") + sage: R. = PolynomialRing(QQbar, order='invlex') sage: f = 3*x^2 - y^2 - x*y sage: f.lt() -y^2 @@ -1821,9 +1809,9 @@ def __ne__(self, right): def __bool__(self): """ - Return ``True`` if self != 0 + Return ``True`` if ``self != 0``. - .. note:: + .. NOTE:: This is much faster than actually writing ``self == 0``. """ @@ -1831,9 +1819,9 @@ def __bool__(self): def _floordiv_(self, right): r""" - Quotient of division of ``self`` by other. This is denoted //. + Quotient of division of ``self`` by ``other``. This is denoted ``//``. - .. note:: + .. NOTE:: It's not clear to me that this is well-defined if ``self`` is not exactly divisible by other. @@ -2025,7 +2013,7 @@ def factor(self, proof=None): INPUT: - ``proof`` -- insist on provably correct results (default: ``True`` - unless explicitly disabled for the ``"polynomial"`` subsystem with + unless explicitly disabled for the ``'polynomial'`` subsystem with :class:`sage.structure.proof.proof.WithProof`.) TESTS: @@ -2128,7 +2116,6 @@ def factor(self, proof=None): sage: f = y^3 + x^3 + (u + 1)*x sage: f.factor() x^3 + y^3 + (u + 1)*x - """ R = self.parent() @@ -2163,7 +2150,7 @@ def factor(self, proof=None): if proof is None: from sage.structure.proof.proof import get_flag - proof = get_flag(subsystem="polynomial") + proof = get_flag(subsystem='polynomial') if proof: raise NotImplementedError("Provably correct factorization not implemented. Disable this error by wrapping your code in a `with proof.WithProof('polynomial', False):` block.") @@ -2226,7 +2213,7 @@ def lift(self,I): @handle_AA_and_QQbar def quo_rem(self, right): """ - Returns quotient and remainder of ``self`` and ``right``. + Return quotient and remainder of ``self`` and ``right``. EXAMPLES:: @@ -2361,7 +2348,7 @@ def subresultants(self, other, variable=None): - ``other`` -- a polynomial - OUTPUT: a list of polynomials in the same ring as ``self`` + OUTPUT: list of polynomials in the same ring as ``self`` EXAMPLES:: @@ -2375,7 +2362,6 @@ def subresultants(self, other, variable=None): sage: p.subresultants(q, x) [2*y^6 + (-22)*y^5 + 102*y^4 + (-274)*y^3 + 488*y^2 + (-552)*y + 288, x*y^2 + y^3 + (-5)*x*y + (-6)*y^2 + 6*x + 11*y - 6] - """ R = self.parent() if variable is None: @@ -2392,7 +2378,7 @@ def reduce(self, I): INPUT: - - ``I`` -- a list of polynomials or an ideal + - ``I`` -- list of polynomials or an ideal EXAMPLES:: @@ -2494,7 +2480,7 @@ def degree_lowest_rational_function(r, x): - ``x`` -- a multivariate polynomial ring generator - OUTPUT: integer -- the difference `val_x(p) - val_x(q)` where `r = p/q` + OUTPUT: integer; the difference `val_x(p) - val_x(q)` where `r = p/q` .. NOTE:: diff --git a/src/sage/rings/polynomial/multi_polynomial_ideal.py b/src/sage/rings/polynomial/multi_polynomial_ideal.py index d5b7dce9866..c3b85864863 100644 --- a/src/sage/rings/polynomial/multi_polynomial_ideal.py +++ b/src/sage/rings/polynomial/multi_polynomial_ideal.py @@ -313,7 +313,7 @@ def is_MPolynomialIdeal(x) -> bool: INPUT: - - ``x`` -- an arbitrary object + - ``x`` -- an arbitrary object EXAMPLES:: @@ -326,6 +326,10 @@ def is_MPolynomialIdeal(x) -> bool: but matches Magma's behavior. :: sage: is_MPolynomialIdeal(I) + doctest:warning... + DeprecationWarning: The function is_MPolynomialIdeal is deprecated; + use 'isinstance(..., MPolynomialIdeal)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. False :: @@ -334,6 +338,10 @@ def is_MPolynomialIdeal(x) -> bool: sage: is_MPolynomialIdeal(I) True """ + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_MPolynomialIdeal is deprecated; " + "use 'isinstance(..., MPolynomialIdeal)' instead.") return isinstance(x, MPolynomialIdeal) @@ -345,7 +353,7 @@ def _magma_init_(self, magma): INPUT: - - ``magma`` -- Magma instance + - ``magma`` -- Magma instance EXAMPLES:: @@ -371,19 +379,17 @@ def _magma_init_(self, magma): @magma_gb_standard_options def _groebner_basis_magma(self, deg_bound=None, prot=False, magma=magma_default): """ - Computes a Groebner Basis for this ideal using Magma if + Compute a Groebner Basis for this ideal using Magma if available. INPUT: - ``deg_bound`` -- only compute to degree ``deg_bound``, that - is, ignore all S-polynomials of higher degree. (default: - ``None``) + is, ignore all S-polynomials of higher degree (default: ``None``) - - ``prot`` -- if ``True`` Magma's protocol is printed to - stdout. + - ``prot`` -- if ``True`` Magma's protocol is printed to stdout - - ``magma`` -- Magma instance or None (default instance) (default: None) + - ``magma`` -- Magma instance or ``None`` (default instance) (default: ``None``) EXAMPLES:: @@ -448,7 +454,7 @@ class MPolynomialIdeal_singular_base_repr: @require_field def syzygy_module(self): r""" - Computes the first syzygy (i.e., the module of relations of the + Compute the first syzygy (i.e., the module of relations of the given generators) of the ideal. EXAMPLES:: @@ -476,7 +482,7 @@ def syzygy_module(self): return matrix(self.ring(), S) @libsingular_gb_standard_options - def _groebner_basis_libsingular(self, algorithm="groebner", *args, **kwds): + def _groebner_basis_libsingular(self, algorithm='groebner', *args, **kwds): """ Return the reduced Groebner basis of this ideal. @@ -487,8 +493,8 @@ def _groebner_basis_libsingular(self, algorithm="groebner", *args, **kwds): INPUT: - ``algorithm`` -- see below for available algorithms - - ``redsb`` -- (default: ``True``) return a reduced Groebner basis - - ``red_tail`` -- (default: ``True``) perform tail reduction + - ``redsb`` -- boolean (default: ``True``); return a reduced Groebner basis + - ``red_tail`` -- boolean (default: ``True``); perform tail reduction ALGORITHMS: @@ -592,12 +598,11 @@ def _groebner_cover(self): [[1], [1], [[[(2*a + 3)], [[1]]]]]] """ from sage.rings.fraction_field import FractionField_generic - from sage.rings.polynomial.multi_polynomial_ring_base import \ - is_MPolynomialRing - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing + from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general F = self.base_ring() if (not isinstance(F, FractionField_generic) or - (not is_MPolynomialRing(F.ring()) and not is_PolynomialRing(F.ring()))): + not isinstance(F.ring(), (MPolynomialRing_base, PolynomialRing_general))): raise TypeError("the base ring must be a field with parameters") from sage.arith.functions import lcm from sage.libs.singular.function import lib, singular_function @@ -682,10 +687,7 @@ def plot(self, singular=None): INPUT: - - - ``self`` -- must be a principal ideal in 2 or 3 vars - over `\QQ`. - + - ``self`` -- must be a principal ideal in 2 or 3 vars over `\QQ` EXAMPLES: @@ -732,7 +734,7 @@ def plot(self, singular=None): @require_field @cached_method @libsingular_gb_standard_options - def complete_primary_decomposition(self, algorithm="sy"): + def complete_primary_decomposition(self, algorithm='sy'): r""" Return a list of primary ideals such that their intersection is ``self``, together with the associated prime ideals. @@ -759,7 +761,7 @@ def complete_primary_decomposition(self, algorithm="sy"): INPUT: - - ``algorithm`` -- string: + - ``algorithm`` -- string; one of - ``'sy'`` -- (default) use the Shimoyama-Yokoyama algorithm @@ -821,7 +823,6 @@ def complete_primary_decomposition(self, algorithm="sy"): [] sage: I.is_prime() False - """ # Avoid a bug in Singular (see #15745). @@ -872,7 +873,7 @@ def primary_decomposition(self, algorithm='sy'): INPUT: - - ``algorithm`` -- string: + - ``algorithm`` -- string; one of - ``'sy'`` -- (default) use the Shimoyama-Yokoyama algorithm @@ -933,28 +934,26 @@ def associated_primes(self, algorithm='sy'): If `I` is a proper ideal of the ring `R` then there exists a decomposition in primary ideals `Q_i` such that - - their intersection is `I` + - their intersection is `I` - - none of the `Q_i` contains the intersection of the - rest, and + - none of the `Q_i` contains the intersection of the + rest, and - - the associated prime ideals of `Q_i` are pairwise - different. + - the associated prime ideals of `Q_i` are pairwise + different. This method returns the associated primes of the `Q_i`. INPUT: - - - ``algorithm`` -- string: + - ``algorithm`` -- string; one of - ``'sy'`` -- (default) use the Shimoyama-Yokoyama algorithm - ``'gtz'`` -- use the Gianni-Trager-Zacharias algorithm - - OUTPUT: a list of associated primes + OUTPUT: list of associated primes EXAMPLES:: @@ -1041,22 +1040,22 @@ def triangular_decomposition(self, algorithm=None, singular=None): INPUT: - - ``algorithm`` -- string or None (default: None) + - ``algorithm`` -- string or ``None`` (default: ``None``) ALGORITHMS: - - ``"singular:triangL"`` -- decomposition of ``self`` into triangular - systems (Lazard). + - ``'singular:triangL'`` -- decomposition of ``self`` into triangular + systems (Lazard) - - ``"singular:triangLfak"`` -- decomposition of ``self`` into triangular systems - plus factorization. + - ``'singular:triangLfak'`` -- decomposition of ``self`` into triangular systems + plus factorization - - ``"singular:triangM"`` -- decomposition of ``self`` into - triangular systems (Moeller). + - ``'singular:triangM'`` -- decomposition of ``self`` into + triangular systems (Moeller) - OUTPUT: a list `T` of lists `t` such that the variety of + OUTPUT: list `T` of lists `t` such that the variety of ``self`` is the union of the varieties of `t` in `L` and each - `t` is in triangular form. + `t` is in triangular form EXAMPLES:: @@ -1222,7 +1221,6 @@ def dimension(self, singular=None): Requires computation of a Groebner basis, which can be a very expensive operation. - """ try: return self.__dimension @@ -1287,7 +1285,7 @@ def dimension(self, singular=None): def vector_space_dimension(self): """ Return the vector space dimension of the ring modulo this ideal. If - the ideal is not zero-dimensional, a :class:`TypeError` is raised. + the ideal is not zero-dimensional, a :exc:`TypeError` is raised. ALGORITHM: @@ -1329,7 +1327,6 @@ def vector_space_dimension(self): 0 sage: I.vector_space_dimension() 3 - """ R = self.ring() gb = R.ideal(self.groebner_basis()) @@ -1345,18 +1342,19 @@ def vector_space_dimension(self): return vd @require_field - def _groebner_basis_ginv(self, algorithm="TQ", criteria='CritPartially', division_interface="Janet"): + def _groebner_basis_ginv(self, algorithm='TQ', criteria='CritPartially', division_interface='Janet'): r""" Compute a Groebner basis using GINV. INPUT: - - ``algorithm`` -- "TQ", "TQBlockHigh", "TQBlockLow" or "TQDegree" - - ``criteria`` -- "Without" (without any criteria) - -- "C1", "CritPartially" (partial involutive criteria) - -- "C1C2C3", "C1C2C3C4" (full involutive criteria) + - ``algorithm`` -- ``'TQ'``, ``'TQBlockHigh'``, ``'TQBlockLow'``, or + ``'TQDegree'`` + - ``criteria`` -- ``'Without'`` (without any criteria), + ``'C1'``, ``'CritPartially'`` (partial involutive criteria), + ``'C1C2C3'``, ``'C1C2C3C4'`` (full involutive criteria) - - ``division_interface`` -- either "Janet" or "JanetLike" + - ``division_interface`` -- either ``'Janet'`` or ``'JanetLike'`` EXAMPLES: @@ -1413,7 +1411,7 @@ def _groebner_basis_ginv(self, algorithm="TQ", criteria='CritPartially', divisio return G @singular_gb_standard_options - def _groebner_basis_singular(self, algorithm="groebner", *args, **kwds): + def _groebner_basis_singular(self, algorithm='groebner', *args, **kwds): """ Return the reduced Groebner basis of this ideal. If the Groebner basis for this ideal has been calculated before, the @@ -1422,8 +1420,7 @@ def _groebner_basis_singular(self, algorithm="groebner", *args, **kwds): INPUT: - - ``algorithm`` -- see below for available algorithms - + - ``algorithm`` -- see below for available algorithms ALGORITHMS: @@ -1480,7 +1477,7 @@ def _groebner_basis_singular(self, algorithm="groebner", *args, **kwds): return S @cached_method - def _groebner_basis_singular_raw(self, algorithm="groebner", singular=None, *args, **kwds): + def _groebner_basis_singular_raw(self, algorithm='groebner', singular=None, *args, **kwds): r""" Return a Groebner basis in Singular format. @@ -1710,9 +1707,7 @@ def intersection(self, *others): @libsingular_gb_standard_options def minimal_associated_primes(self): """ - OUTPUT: - - - ``list`` -- a list of prime ideals + OUTPUT: list of prime ideals EXAMPLES:: @@ -1837,7 +1832,7 @@ def integral_closure(self, p=0, r=True, singular=None): @handle_AA_and_QQbar def syzygy_module(self): r""" - Computes the first syzygy (i.e., the module of relations of the + Compute the first syzygy (i.e., the module of relations of the given generators) of the ideal. EXAMPLES:: @@ -1980,7 +1975,6 @@ def interreduced_basis(self): - `LC(g_i) = 1` for all `i` if the coefficient ring is a field. - EXAMPLES:: sage: R. = PolynomialRing(QQ) @@ -2174,13 +2168,13 @@ def basis_is_groebner(self, singular=None): @handle_AA_and_QQbar @singular_gb_standard_options @libsingular_gb_standard_options - def transformed_basis(self, algorithm="gwalk", other_ring=None, singular=None): + def transformed_basis(self, algorithm='gwalk', other_ring=None, singular=None): """ Return a lex or ``other_ring`` Groebner Basis for this ideal. INPUT: - - ``algorithm`` -- see below for options. + - ``algorithm`` -- see below for options - ``other_ring`` -- only valid for ``algorithm='fglm'``; if provided, conversion will be performed to this @@ -2189,18 +2183,18 @@ def transformed_basis(self, algorithm="gwalk", other_ring=None, singular=None): ALGORITHMS: - - ``"fglm"`` -- FGLM algorithm. The input ideal must be given with a reduced + - ``'fglm'`` -- FGLM algorithm. The input ideal must be given with a reduced Groebner Basis of a zero-dimensional ideal - - ``"gwalk"`` -- Groebner Walk algorithm (*default*) + - ``'gwalk'`` -- Groebner Walk algorithm (*default*) - - ``"awalk1"`` -- 'first alternative' algorithm + - ``'awalk1'`` -- 'first alternative' algorithm - - ``"awalk2"`` -- 'second alternative' algorithm + - ``'awalk2'`` -- 'second alternative' algorithm - - ``"twalk"`` -- Tran algorithm + - ``'twalk'`` -- Tran algorithm - - ``"fwalk"`` -- Fractal Walk algorithm + - ``'fwalk'`` -- Fractal Walk algorithm EXAMPLES:: @@ -2287,10 +2281,10 @@ def elimination_ideal(self, variables, algorithm=None, *args, **kwds): INPUT: - - ``variables`` -- a list or tuple of variables in ``self.ring()`` + - ``variables`` -- list or tuple of variables in ``self.ring()`` - ``algorithm`` -- determines the algorithm to use, see below - for available algorithms. + for available algorithms ALGORITHMS: @@ -2312,7 +2306,7 @@ def elimination_ideal(self, variables, algorithm=None, *args, **kwds): You can use Giac to compute the elimination ideal:: - sage: print("possible output from giac", flush=True); I.elimination_ideal([t, s], algorithm="giac") == J + sage: print("possible output from giac", flush=True); I.elimination_ideal([t, s], algorithm='giac') == J possible output... True @@ -2338,7 +2332,7 @@ def elimination_ideal(self, variables, algorithm=None, *args, **kwds): sage: J = I.elimination_ideal([t, s]); J Ideal (y^2 - x*z, x*y - z, x^2 - y) of Multivariate Polynomial Ring in x, y, t, s, z over Algebraic Field - sage: print("possible output from giac", flush=True); I.elimination_ideal([t, s], algorithm="giac") == J + sage: print("possible output from giac", flush=True); I.elimination_ideal([t, s], algorithm='giac') == J possible output... True @@ -2404,7 +2398,7 @@ def quotient(self, J): INPUT: - - ``J`` -- multivariate polynomial ideal + - ``J`` -- multivariate polynomial ideal EXAMPLES:: @@ -2467,7 +2461,8 @@ def quotient(self, J): @handle_AA_and_QQbar def saturation(self, other): r""" - Return the saturation (and saturation exponent) of the ideal ``self`` with respect to the ideal ``other`` + Return the saturation (and saturation exponent) of the ideal ``self`` + with respect to the ideal ``other``. INPUT: @@ -2506,7 +2501,7 @@ def saturation(self, other): return (R.ideal(ideal), ZZ(expo)) @require_field - def variety(self, ring=None, *, algorithm="triangular_decomposition", proof=True): + def variety(self, ring=None, *, algorithm='triangular_decomposition', proof=True): r""" Return the variety of this ideal. @@ -2690,11 +2685,11 @@ def variety(self, ring=None, *, algorithm="triangular_decomposition", proof=True ALGORITHM: - - With ``algorithm`` = ``"triangular_decomposition"`` (default), + - With ``algorithm`` = ``'triangular_decomposition'`` (default), uses triangular decomposition, via Singular if possible, falling back on a toy implementation otherwise. - - With ``algorithm`` = ``"msolve"``, uses the + - With ``algorithm`` = ``'msolve'``, uses the :ref:`optional package msolve `. Note that msolve uses heuristics and therefore requires setting the ``proof`` flag to ``False``. See @@ -2815,7 +2810,6 @@ def _variety_triangular_decomposition(self, ring): sage: I = Ideal([ x*y - 1, (x-2)^2 + (y-1)^2 - 1]) sage: len(I.variety()) 4 - """ def _variety(T, V, v=None): @@ -2854,7 +2848,7 @@ def _variety(T, V, v=None): return [] if isinstance(self.base_ring(), sage.rings.abc.ComplexField): - verbose("Warning: computations in the complex field are inexact; variety may be computed partially or incorrectly.", level=0, caller_name="variety") + verbose("Warning: computations in the complex field are inexact; variety may be computed partially or incorrectly.", level=0, caller_name='variety') P = self.ring() if ring is not None: P = P.change_ring(ring) @@ -2863,7 +2857,7 @@ def _variety(T, V, v=None): T = [list(each.gens()) for each in TI] except TypeError: # conversion to Singular not supported if self.ring().term_order().is_global(): - verbose("Warning: falling back to very slow toy implementation.", level=0, caller_name="variety") + verbose("Warning: falling back to very slow toy implementation.", level=0, caller_name='variety') T = toy_variety.triangular_factorization(self.groebner_basis()) else: raise TypeError("Local/unknown orderings not supported by 'toy_buchberger' implementation.") @@ -3185,7 +3179,6 @@ def hilbert_numerator(self, grading=None, algorithm='sage'): sage: n2 = I.hilbert_numerator(algorithm='singular') sage: n1 == n2 True - """ if not self.is_homogeneous(): raise TypeError("Ideal must be homogeneous.") @@ -3295,12 +3288,12 @@ def normal_basis(self, degree=None, algorithm='libsingular', - ``degree`` -- integer (default: ``None``) - - ``algorithm`` -- string (default: ``"libsingular"``); if not the + - ``algorithm`` -- string (default: ``'libsingular'``); if not the default, this will use the ``kbase()`` or ``weightKB()`` command from Singular - ``singular`` -- the singular interpreter to use when ``algorithm`` is - not ``"libsingular"`` (default: the default instance) + not ``'libsingular'`` (default: the default instance) OUTPUT: @@ -3413,7 +3406,7 @@ def _groebner_basis_macaulay2(self, strategy=None): INPUT: - ``strategy`` -- (default: ``'gb'``) argument specifying the strategy - to be used by Macaulay2; possibilities: ``'f4'``, ``'gb'``, ``'mgb'``. + to be used by Macaulay2; possibilities: ``'f4'``, ``'gb'``, ``'mgb'`` EXAMPLES:: @@ -3495,19 +3488,18 @@ def _reduce_using_macaulay2(self, f): return R(k) class NCPolynomialIdeal(MPolynomialIdeal_singular_repr, Ideal_nc): - def __init__(self, ring, gens, coerce=True, side="left"): + def __init__(self, ring, gens, coerce=True, side='left'): r""" - Creates a non-commutative polynomial ideal. + Create a non-commutative polynomial ideal. INPUT: - - ``ring`` - the g-algebra to which this ideal belongs - - ``gens`` - the generators of this ideal - - ``coerce`` (optional - default: ``True``) - generators are + - ``ring`` -- the g-algebra to which this ideal belongs + - ``gens`` -- the generators of this ideal + - ``coerce`` -- boolean (default: ``True``); generators are coerced into the ring before creating the ideal - - ``side`` -- optional string, either ``"left"`` (default) - or ``"twosided"``; defines whether this ideal is left - of two-sided. + - ``side`` -- (optional) string; either ``'left'`` (default) + or ``'twosided'``. Defines whether this ideal is left or two-sided. EXAMPLES:: @@ -3524,18 +3516,17 @@ def __init__(self, ring, gens, coerce=True, side="left"): nc-relations: {z*x: x*z + 2*x, z*y: y*z - 2*y, y*x: x*y - z} sage: sorted(I.gens(), key=str) [x^2, y^2, z^2 - 1] - sage: H.ideal([y^2, x^2, z^2 - H.one()], side="twosided") # random + sage: H.ideal([y^2, x^2, z^2 - H.one()], side='twosided') # random Twosided Ideal (y^2, x^2, z^2 - 1) of Noncommutative Multivariate Polynomial Ring in x, y, z over Rational Field, nc-relations: {z*x: x*z + 2*x, z*y: y*z - 2*y, y*x: x*y - z} - sage: sorted(H.ideal([y^2, x^2, z^2 - H.one()], side="twosided").gens(), + sage: sorted(H.ideal([y^2, x^2, z^2 - H.one()], side='twosided').gens(), ....: key=str) [x^2, y^2, z^2 - 1] - sage: H.ideal([y^2, x^2, z^2 - H.one()], side="right") + sage: H.ideal([y^2, x^2, z^2 - H.one()], side='right') Traceback (most recent call last): ... ValueError: Only left and two-sided ideals are allowed. - """ if side == "right": raise ValueError("Only left and two-sided ideals are allowed.") @@ -3548,11 +3539,9 @@ def __call_singular(self, cmd, arg=None): INPUT: - ``cmd`` - string, representing a Singular function - - ``arg`` (Default: None) - arguments for which cmd is called - - OUTPUT: + - ``arg`` -- (default: ``None``) arguments for which cmd is called - - result of the Singular function call + OUTPUT: result of the Singular function call EXAMPLES:: @@ -3761,7 +3750,6 @@ def reduce(self,p): sage: I.reduce(z^2) # needs sage.combinat sage.modules 1 - """ return self._groebner_strategy().normal_form(p) @@ -3793,7 +3781,6 @@ def _contains_(self,p): False sage: x*y^2-y*z in JT # needs sage.combinat sage.modules True - """ return self.reduce(p).is_zero() @@ -3894,7 +3881,7 @@ def __init__(self, ring, gens, coerce=True): - ``ring`` -- the ring the ideal is defined in - - ``gens`` -- a list of generators for the ideal + - ``gens`` -- list of generators for the ideal - ``coerce`` -- whether to coerce elements to the ring ``ring`` @@ -3912,7 +3899,7 @@ def __init__(self, ring, gens, coerce=True): def __hash__(self): r""" - Stupid constant hash function! + Stupid constant hash function. TESTS:: @@ -3951,7 +3938,6 @@ def basis(self): sage: I = Ideal([x, y + 1]) sage: I.basis [x, y + 1] - """ return self.gens() @@ -3963,15 +3949,13 @@ def __richcmp__(self, other, op): - ``other`` -- a polynomial ideal - OUTPUT: - - boolean + OUTPUT: boolean ALGORITHM: Comparison for ``==`` and ``!=`` compares two Groebner bases. - Comparison for ``<=` and ``>=`` tests the inclusion of ideals + Comparison for ``<=`` and ``>=`` tests the inclusion of ideals using the usual ideal membership test, namely all generators of one ideal must reduce to zero in the other ideal's Groebner basis. @@ -4143,7 +4127,7 @@ def __richcmp__(self, other, op): o, r = next(iter(other_new._gb_by_ordering.items())) l = self.change_ring(R.change_ring(order=o)).gens() else: # use easy GB otherwise - newR = R.change_ring(order="degrevlex") + newR = R.change_ring(order='degrevlex') l = self.change_ring(newR).gens() r = other_new.change_ring(newR).groebner_basis() # remember this Groebner basis for future reference @@ -4162,7 +4146,7 @@ def __richcmp__(self, other, op): l = self.groebner_basis() r = other_new.groebner_basis() else: # use easy GB otherwise - newR = R.change_ring(order="degrevlex") + newR = R.change_ring(order='degrevlex') l = self.change_ring(newR).groebner_basis() r = other_new.change_ring(newR).groebner_basis() except AttributeError: # e.g. quotient rings @@ -4194,16 +4178,15 @@ def groebner_fan(self, is_groebner_basis=False, symmetry=None, verbose=False): INPUT: + - ``is_groebner_basis`` -- boolean (default: ``False``); if + ``True``, then ``I.gens()`` must be a Groebner basis with respect to + the standard degree lexicographic term order - - ``is_groebner_basis`` -- bool (default: ``False``). if - True, then I.gens() must be a Groebner basis with respect to the - standard degree lexicographic term order. - - - ``symmetry`` -- default: None; if not None, describes - symmetries of the ideal + - ``symmetry`` -- (default: ``None``) if not ``None``, describes + symmetries of the ideal - - ``verbose`` -- default: ``False``; if True, printout - useful info during computations + - ``verbose`` -- (default: ``False``) if ``True``, printout + useful info during computations """ import sage.rings.polynomial.groebner_fan as groebner_fan return groebner_fan.GroebnerFan(self, is_groebner_basis=is_groebner_basis, @@ -4229,7 +4212,7 @@ def groebner_basis(self, algorithm='', deg_bound=None, mult_bound=None, prot=Fal INPUT: - ``algorithm`` -- determines the algorithm to use, see below - for available algorithms. + for available algorithms - ``deg_bound`` -- only compute to degree ``deg_bound``, that is, ignore all S-polynomials of higher degree. (default: @@ -4832,15 +4815,12 @@ def groebner_cover(self): def change_ring(self, P): r""" - Return the ideal ``I`` in ``P`` spanned by - the generators `g_1, ..., g_n` of self as returned by - ``self.gens()``. + Return the ideal ``I`` in ``P`` spanned by the generators + `g_1, ..., g_n` of ``self`` as returned by ``self.gens()``. INPUT: - - - ``P`` -- a multivariate polynomial ring - + - ``P`` -- a multivariate polynomial ring EXAMPLES:: @@ -4892,7 +4872,7 @@ def subs(self, in_dict=None, **kwds): OUTPUT: A new ideal with modified generators. If possible, in the same - polynomial ring. Raises a :class:`TypeError` if no common + polynomial ring. Raises a :exc:`TypeError` if no common polynomial ring of the substituted generators can be found. EXAMPLES:: @@ -5016,10 +4996,7 @@ def homogenize(self, var='h'): INPUT: - - - ``h`` -- variable name or variable in cover ring - (default: 'h') - + - ``h`` -- variable name or variable in cover ring (default: ``'h'``) EXAMPLES:: @@ -5111,7 +5088,7 @@ def degree_of_semi_regularity(self): The degree of regularity of a semi-regular sequence `f_1, ...,f_m` of respective degrees `d_1,...,d_m` is given by the - index of the first non-positive coefficient of: + index of the first nonpositive coefficient of: `\sum c_k z^k = \frac{\prod (1 - z^{d_i})}{(1-z)^n}` @@ -5199,9 +5176,9 @@ def plot(self, *args, **kwds): - ``self`` -- a principal ideal in 2 variables - ``algorithm`` -- set this to 'surf' if you want 'surf' to - plot the ideal (default: None) + plot the ideal (default: ``None``) - - ``*args`` -- optional tuples ``(variable, minimum, maximum)`` + - ``*args`` -- (optional) tuples ``(variable, minimum, maximum)`` for plotting dimensions - ``**kwds`` -- optional keyword arguments passed on to @@ -5253,7 +5230,6 @@ def plot(self, *args, **kwds): sage: I = R.ideal([-x^2*y + 1]) sage: I.plot() # blow up # needs sage.plot Graphics object consisting of 1 graphics primitive - """ from sage.plot.all import implicit_plot from sage.rings.real_mpfr import RR @@ -5394,7 +5370,6 @@ def random_element(self, degree, compute_gb=False, *args, **kwds): sage: set_random_seed(5) sage: I.random_element(degree=2) -2*x^2 + 2*y^2 - """ if compute_gb: gens = self.groebner_basis() @@ -5684,9 +5659,7 @@ def __richcmp__(self, other, op): - ``other`` -- an ideal in a quotient of a polynomial ring - OUTPUT: - - boolean + OUTPUT: boolean TESTS:: diff --git a/src/sage/rings/polynomial/multi_polynomial_ideal_libsingular.pyx b/src/sage/rings/polynomial/multi_polynomial_ideal_libsingular.pyx index e01f181be1d..c97dbf9cca3 100644 --- a/src/sage/rings/polynomial/multi_polynomial_ideal_libsingular.pyx +++ b/src/sage/rings/polynomial/multi_polynomial_ideal_libsingular.pyx @@ -69,8 +69,8 @@ from sage.rings.polynomial.plural cimport NCPolynomialRing_plural, NCPolynomial_ cdef object singular_ideal_to_sage_sequence(ideal *i, ring *r, object parent): """ - convert a SINGULAR ideal to a Sage Sequence (the format Sage - stores a Groebner basis in) + Convert a SINGULAR ideal to a Sage Sequence (the format Sage + stores a Groebner basis in). INPUT: @@ -102,7 +102,8 @@ cdef ideal *sage_ideal_to_singular_ideal(I) except NULL: INPUT: - ``I`` -- a Sage ideal in a ring of type - :class:`~sage.rings.polynomial.multi_polynomial_libsingular.MPolynomialRing_libsingular` or a list of generators. + :class:`~sage.rings.polynomial.multi_polynomial_libsingular.MPolynomialRing_libsingular` + or a list of generators TESTS: diff --git a/src/sage/rings/polynomial/multi_polynomial_libsingular.pyx b/src/sage/rings/polynomial/multi_polynomial_libsingular.pyx index ce239335523..d108d269082 100644 --- a/src/sage/rings/polynomial/multi_polynomial_libsingular.pyx +++ b/src/sage/rings/polynomial/multi_polynomial_libsingular.pyx @@ -109,7 +109,7 @@ TESTS:: sage: loads(dumps(x)) == x True - sage: Rt. = PolynomialRing(QQ, implementation="singular") + sage: Rt. = PolynomialRing(QQ, implementation='singular') sage: p = 1+t sage: R. = PolynomialRing(QQ, 2) sage: p(u/v) @@ -218,7 +218,7 @@ from sage.rings.polynomial.multi_polynomial_ring_base import BooleanPolynomialRi from sage.rings.polynomial.multi_polynomial_element import MPolynomial_polydict from sage.rings.polynomial.multi_polynomial_ideal import MPolynomialIdeal from sage.rings.polynomial.polydict cimport ETuple -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general # base ring imports import sage.rings.abc @@ -390,7 +390,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): def __dealloc__(self): r""" - Deallocate the ring without changing ``currRing`` + Deallocate the ring without changing ``currRing``. TESTS: @@ -480,7 +480,6 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): Coercion map: From: Univariate Polynomial Ring in x over Integer Ring To: Multivariate Polynomial Ring in x, y over Rational Field - """ base_ring = self.base_ring() if other is base_ring: @@ -509,7 +508,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): return True elif base_ring.has_coerce_map_from(other._mpoly_base_ring(self.variable_names())): return True - elif is_PolynomialRing(other): + elif isinstance(other, PolynomialRing_general): if base_ring.has_coerce_map_from(other._mpoly_base_ring(self.variable_names())): return True @@ -528,7 +527,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): sage: P. = QQ[] - We can coerce elements of self to self:: + We can coerce elements of ``self`` to ``self``:: sage: P.coerce(x*y + 1/2) x*y + 1/2 @@ -1022,7 +1021,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): def ngens(self): """ - Returns the number of variables in this multivariate polynomial ring. + Return the number of variables in this multivariate polynomial ring. EXAMPLES:: @@ -1039,12 +1038,12 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): def gen(self, int n=0): """ - Returns the ``n``-th generator of this multivariate polynomial + Return the ``n``-th generator of this multivariate polynomial ring. INPUT: - - ``n`` -- an integer ``>= 0`` + - ``n`` -- nonnegative integer EXAMPLES:: @@ -1081,7 +1080,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): - ``*gens`` -- list or tuple of generators (or several input arguments) - - ``coerce`` -- bool (default: ``True``); this must be a + - ``coerce`` -- boolean (default: ``True``); this must be a keyword argument. Only set it to ``False`` if you are certain that each generator is already in the ring. @@ -1099,8 +1098,8 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): coerce = kwds.get('coerce', True) if len(gens) == 1: gens = gens[0] - from sage.rings.ideal import is_Ideal - if is_Ideal(gens): + from sage.rings.ideal import Ideal_generic + if isinstance(gens, Ideal_generic): if gens.ring() is self: return gens gens = gens.gens() @@ -1370,7 +1369,6 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): // block 1 : ordering lp // : names x // block 2 : ordering C - """ if singular is None: from sage.interfaces.singular import singular @@ -1461,7 +1459,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): def __reduce__(self): """ - Serializes self. + Serialize ``self``. EXAMPLES:: @@ -1851,9 +1849,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): - ``t`` -- a monomial - OUTPUT: - a list of monomials - + OUTPUT: list of monomials EXAMPLES:: @@ -1880,7 +1876,7 @@ cdef class MPolynomialRing_libsingular(MPolynomialRing_base): def unpickle_MPolynomialRing_libsingular(base_ring, names, term_order): """ - inverse function for ``MPolynomialRing_libsingular.__reduce__`` + Inverse function for ``MPolynomialRing_libsingular.__reduce__``. EXAMPLES:: @@ -1927,9 +1923,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): """ Copy ``self``. - OUTPUT: - - A copy. + OUTPUT: a copy EXAMPLES:: @@ -1955,7 +1949,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def __deepcopy__(self, memo={}): """ - Deep copy ``self`` + Deep copy ``self``. TESTS:: @@ -1998,12 +1992,12 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): Evaluate this multi-variate polynomial at ``x``, where ``x`` is either the tuple of values to substitute in, or one can use functional notation ``f(a_0,a_1,a_2, \ldots)`` to evaluate - ``f`` with the ith variable replaced by ``a_i``. + ``f`` with the ``i``-th variable replaced by ``a_i``. INPUT: - - ``x`` -- a list of elements in ``self.parent()`` - - or ``**kwds`` -- a dictionary of ``variable-name:value`` pairs. + - ``x`` -- list of elements in ``self.parent()`` + - or ``**kwds`` -- dictionary of ``variable-name:value`` pairs EXAMPLES:: @@ -2227,7 +2221,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): cpdef _lmul_(self, Element left): """ - Multiply self with a base ring element. + Multiply ``self`` with a base ring element. EXAMPLES:: @@ -2275,7 +2269,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): cpdef _div_(left, right_ringelement): r""" - Divide left by right + Divide ``left`` by ``right``. EXAMPLES:: @@ -2337,7 +2331,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): Ensure that :issue:`17638` is fixed:: - sage: R. = PolynomialRing(QQ, order="neglex") + sage: R. = PolynomialRing(QQ, order='neglex') sage: f = 1 + y sage: g = 1 + x sage: h = f/g @@ -2679,7 +2673,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): sage: type(f.degree(y)) - """ cdef ring *r = self._parent_ring cdef poly *p = self._poly @@ -2771,7 +2764,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def degrees(self): """ - Returns a tuple with the maximal degree of each variable in + Return a tuple with the maximal degree of each variable in this polynomial. The list of degrees is ordered by the order of the generators. @@ -2821,12 +2814,12 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``degrees`` -- Can be any of: + - ``degrees`` -- can be any of: - a dictionary of degree restrictions - a list of degree restrictions (with ``None`` in the unrestricted variables) - a monomial (very fast, but not as flexible) - OUTPUT: element of the parent of this element. + OUTPUT: element of the parent of this element .. NOTE:: @@ -2937,7 +2930,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def monomial_coefficient(self, MPolynomial_libsingular mon): """ Return the coefficient in the base ring of the monomial mon in - ``self``, where mon must have the same parent as self. + ``self``, where mon must have the same parent as ``self``. This function contrasts with the function ``coefficient`` which returns the coefficient of a monomial viewing this @@ -2948,9 +2941,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): - ``mon`` -- a monomial - OUTPUT: - - coefficient in base ring + OUTPUT: coefficient in base ring .. SEEALSO:: @@ -2994,7 +2985,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def dict(self): """ - Return a dictionary representing self. This dictionary is in + Return a dictionary representing ``self``. This dictionary is in the same format as the generic MPolynomial: The dictionary consists of ``ETuple:coefficient`` pairs. @@ -3031,8 +3022,8 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``as_ETuples`` -- (default: ``True``) if ``True`` iterate over - pairs whose first element is an ETuple, otherwise as a tuples + - ``as_ETuples`` -- boolean (default: ``True``); if ``True`` iterate + over pairs whose first element is an ETuple, otherwise as a tuples EXAMPLES:: @@ -3072,7 +3063,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): cpdef long number_of_terms(self) noexcept: """ - Return the number of non-zero coefficients of this polynomial. + Return the number of nonzero coefficients of this polynomial. This is also called weight, :meth:`hamming_weight` or sparsity. @@ -3140,8 +3131,8 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``x`` -- a tuple or, in case of a single-variable MPolynomial - ring x can also be an integer. + - ``x`` -- tuple or, in case of a single-variable MPolynomial + ring x can also be an integer EXAMPLES:: @@ -3154,7 +3145,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): sage: f[0,1] 0 - sage: R. = PolynomialRing(GF(7), implementation="singular"); R + sage: R. = PolynomialRing(GF(7), implementation='singular'); R Multivariate Polynomial Ring in x over Finite Field of size 7 sage: f = 5*x^2 + 3; f -2*x^2 + 3 @@ -3198,7 +3189,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): """ Facilitates iterating over the monomials of self, returning tuples of the form ``(coeff, mon)`` for each - non-zero monomial. + nonzero monomial. EXAMPLES:: @@ -3237,8 +3228,8 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``as_ETuples`` -- (default: ``True``) if ``True`` returns the - result as a list of ETuples, otherwise returns a list of tuples + - ``as_ETuples`` -- boolean (default: ``True``); if ``True`` returns + the result as a list of ETuples, otherwise returns a list of tuples EXAMPLES:: @@ -3330,11 +3321,10 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``var`` -- an integer indicating which variable to use to + - ``var`` -- integer indicating which variable to use to homogenize (``0 <= var < parent(self).ngens()``) - OUTPUT: - a multivariate polynomial + OUTPUT: a multivariate polynomial EXAMPLES:: @@ -3555,7 +3545,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): (c + d)*z^2 sage: f.subs({z:x+1}) c*x^2*y + d*x^2 + (2*c)*x*y + (2*d)*x + c*y + d - """ cdef int mi, i cdef bint change_ring = False # indicates the need to change the parent ring @@ -3676,9 +3665,8 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def monomials(self): """ - Return the list of monomials in self. The returned list is - decreasingly ordered by the term ordering of - ``self.parent()``. + Return the list of monomials in ``self``. The returned list is + decreasingly ordered by the term ordering of ``self.parent()``. EXAMPLES:: @@ -3765,7 +3753,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def univariate_polynomial(self, R=None): """ - Returns a univariate polynomial associated to this + Return a univariate polynomial associated to this multivariate polynomial. INPUT: @@ -3773,7 +3761,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): - ``R`` -- (default: ``None``) PolynomialRing If this polynomial is not in at most one variable, then a - ``ValueError`` exception is raised. This is checked using the + :exc:`ValueError` exception is raised. This is checked using the :meth:`is_univariate()` method. The new Polynomial is over the same base ring as the given ``MPolynomial`` and in the variable ``x`` if no ring ``R`` is provided. @@ -3874,7 +3862,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): sage: f = x*z^2 + z + 1 sage: f._variable_indices_() [0, 2] - """ cdef poly *p cdef ring *r = self._parent_ring @@ -3970,7 +3957,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def lm(MPolynomial_libsingular self): """ - Returns the lead monomial of ``self`` with respect to the term + Return the lead monomial of ``self`` with respect to the term order of ``self.parent()``. In Sage a monomial is a product of variables in some power without a coefficient. @@ -3999,7 +3986,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): sage: f = x^4*y^7*z^1 + x^4*y^2*z^3 sage: f.lm() x^4*y^7*z - """ cdef poly *_p cdef ring *_ring = self._parent_ring @@ -4202,7 +4188,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``proof`` -- ignored. + - ``proof`` -- ignored EXAMPLES:: @@ -4504,10 +4490,10 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def lift(self, I): """ - given an ideal ``I = (f_1,...,f_r)`` and some ``g (== self)`` in ``I``, + Given an ideal ``I = (f_1,...,f_r)`` and some ``g (== self)`` in ``I``, find ``s_1,...,s_r`` such that ``g = s_1 f_1 + ... + s_r f_r``. - A ``ValueError`` exception is raised if ``g (== self)`` does not belong to ``I``. + A :exc:`ValueError` exception is raised if ``g (== self)`` does not belong to ``I``. EXAMPLES:: @@ -4564,7 +4550,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): sage: foo = I.complete_primary_decomposition() # indirect doctest sage: foo[0][0] Ideal (x1 + 1, x2^2 - 3) of Multivariate Polynomial Ring in x1, x2 over Rational Field - """ global errorreported @@ -4624,11 +4609,9 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``I`` -- an ideal or a list/set/iterable of polynomials. + - ``I`` -- an ideal or a list/set/iterable of polynomials - OUTPUT: - - A polynomial ``r`` such that: + OUTPUT: a polynomial ``r`` such that: - ``self`` -- ``r`` is in the ideal generated by ``I``. @@ -4688,8 +4671,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): 2*y sage: (x+y).reduce([x-y, x+y]) 0 - - """ cdef ideal *_I cdef MPolynomialRing_libsingular parent = self._parent @@ -4780,7 +4761,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): @coerce_binop def gcd(self, right, algorithm=None, **kwds): """ - Return the greatest common divisor of self and right. + Return the greatest common divisor of ``self`` and ``right``. INPUT: @@ -5020,7 +5001,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): Traceback (most recent call last): ... ZeroDivisionError - """ cdef poly *quo cdef poly *rem @@ -5310,7 +5290,6 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): sage: f = x^3*y^2 + y^2 + x + 2 sage: f._derivative(x) # needs sage.rings.finite_rings x^2*y^2 + 1 - """ if var is None: raise ValueError("you must specify which variable with respect to which to differentiate") @@ -5550,9 +5529,9 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -5626,12 +5605,12 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -5674,12 +5653,12 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -5736,22 +5715,22 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def numerator(self): """ - Return a numerator of self computed as self * self.denominator() + Return a numerator of ``self`` computed as ``self * self.denominator()``. - If the base_field of self is the Rational Field then the + If the base_field of ``self`` is the Rational Field then the numerator is a polynomial whose base_ring is the Integer Ring, this is done for compatibility to the univariate case. - .. warning:: + .. WARNING:: - This is not the numerator of the rational function - defined by self, which would always be self since self is a + This is not the numerator of the rational function defined by + ``self``, which would always be ``self`` since ``self`` is a polynomial. EXAMPLES: First we compute the numerator of a polynomial with - integer coefficients, which is of course self. + integer coefficients, which is of course ``self``. :: @@ -5811,7 +5790,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): else: return self * self.denominator() - def in_subalgebra(self, J, algorithm="algebra_containment"): + def in_subalgebra(self, J, algorithm='algebra_containment'): """ Return whether this polynomial is contained in the subalgebra generated by ``J`` @@ -5820,19 +5799,19 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): - ``J`` -- list of elements of the parent polynomial ring - - ``algorithm`` -- can be ``"algebra_containment"`` (the default), - ``"inSubring"``, or ``"groebner"``. + - ``algorithm`` -- can be ``'algebra_containment'`` (the default), + ``'inSubring'``, or ``'groebner'`` - - ``"algebra_containment"``: use Singular's + - ``'algebra_containment'``: use Singular's ``algebra_containment`` function, https://www.singular.uni-kl.de/Manual/4-2-1/sing_1247.htm#SEC1328. The Singular documentation suggests that this is frequently faster than the next option. - - ``"inSubring"``: use Singular's ``inSubring`` function, + - ``'inSubring'``: use Singular's ``inSubring`` function, https://www.singular.uni-kl.de/Manual/4-2-0/sing_1240.htm#SEC1321. - - ``"groebner"``: use the algorithm described in Singular's + - ``'groebner'``: use the algorithm described in Singular's documentation, but within Sage: if the subalgebra generators are `y_1`, ..., `y_m`, then create a new polynomial algebra with the old generators along with new @@ -5891,7 +5870,7 @@ cdef class MPolynomial_libsingular(MPolynomial_libsingular_base): def unpickle_MPolynomial_libsingular(MPolynomialRing_libsingular R, d): """ - Deserialize an ``MPolynomial_libsingular`` object + Deserialize an ``MPolynomial_libsingular`` object. INPUT: @@ -5955,14 +5934,12 @@ cdef inline MPolynomial_libsingular new_MP(MPolynomialRing_libsingular parent, p INPUT: - - ``parent`` -- a :class:`MPolynomialRing_libsingular`` - instance. The parent of the polynomial to create. - - - ``juice`` -- a pointer to a Singular ``poly`` C struct. + - ``parent`` -- a :class:`MPolynomialRing_libsingular` + instance; the parent of the polynomial to create - OUTPUT: + - ``juice`` -- a pointer to a Singular ``poly`` C struct - A Python object :class:`MPolynomial_libsingular`. + OUTPUT: a Python object :class:`MPolynomial_libsingular` The ownership of ``juice`` will be transferred to the Python object. You must not free it yourself. Singular will modify the diff --git a/src/sage/rings/polynomial/multi_polynomial_ring.py b/src/sage/rings/polynomial/multi_polynomial_ring.py index 03343b85b99..588358ab3d9 100644 --- a/src/sage/rings/polynomial/multi_polynomial_ring.py +++ b/src/sage/rings/polynomial/multi_polynomial_ring.py @@ -144,7 +144,7 @@ def __eq__(self, other): sage: loads(R.dumps()) == R True """ - if not is_MPolynomialRing(other): + if not isinstance(other, MPolynomialRing_base): return False return ((self.base_ring(), self.ngens(), self.variable_names(), self.term_order()) == @@ -554,14 +554,13 @@ def monomial_quotient(self, f, g, coeff=False): INPUT: - - ``f`` -- monomial. + - ``f`` -- monomial - - ``g`` -- monomial. + - ``g`` -- monomial - - ``coeff`` -- divide coefficients as well (default: - False). + - ``coeff`` -- divide coefficients as well (default: ``False``) - OUTPUT: monomial. + OUTPUT: monomial EXAMPLES:: @@ -650,11 +649,11 @@ def monomial_lcm(self, f, g): INPUT: - - ``f`` -- monomial. + - ``f`` -- monomial - - ``g`` -- monomial. + - ``g`` -- monomial - OUTPUT: monomial. + OUTPUT: monomial EXAMPLES:: @@ -703,11 +702,9 @@ def monomial_reduce(self, f, G): INPUT: + - ``f`` -- monomial - - ``f`` -- monomial - - - ``G`` -- list/set of mpolynomials - + - ``G`` -- list/set of mpolynomials EXAMPLES:: @@ -765,7 +762,7 @@ def monomial_divides(self, a, b): - ``b`` -- monomial - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -802,11 +799,11 @@ def monomial_pairwise_prime(self, h, g): INPUT: - - ``h`` -- monomial. + - ``h`` -- monomial - - ``g`` -- monomial. + - ``g`` -- monomial - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -853,9 +850,9 @@ def monomial_all_divisors(self, t): INPUT: - - ``t`` -- a monomial. + - ``t`` -- a monomial - OUTPUT: a list of monomials. + OUTPUT: list of monomials EXAMPLES:: @@ -943,8 +940,8 @@ def ideal(self, *gens, **kwds): """ do_coerce = False if len(gens) == 1: - from sage.rings.ideal import is_Ideal - if is_Ideal(gens[0]): + from sage.rings.ideal import Ideal_generic + if isinstance(gens[0], Ideal_generic): if gens[0].ring() is self: return gens[0] gens = gens[0].gens() diff --git a/src/sage/rings/polynomial/multi_polynomial_ring_base.pyx b/src/sage/rings/polynomial/multi_polynomial_ring_base.pyx index 55d2900fa61..90e736dbadf 100644 --- a/src/sage/rings/polynomial/multi_polynomial_ring_base.pyx +++ b/src/sage/rings/polynomial/multi_polynomial_ring_base.pyx @@ -29,6 +29,10 @@ from sage.rings.polynomial.polynomial_ring_constructor import (PolynomialRing, def is_MPolynomialRing(x): + from sage.misc.superseded import deprecation_cython + deprecation_cython(38266, + "The function is_MPolynomialRing is deprecated; " + "use 'isinstance(..., MPolynomialRing_base)' instead.") return isinstance(x, MPolynomialRing_base) @@ -120,7 +124,7 @@ cdef class MPolynomialRing_base(CommutativeRing): @cached_method def flattening_morphism(self): r""" - Return the flattening morphism of this polynomial ring + Return the flattening morphism of this polynomial ring. EXAMPLES:: @@ -135,7 +139,7 @@ cdef class MPolynomialRing_base(CommutativeRing): Multivariate Polynomial Ring in x, y over Rational Field """ base = self.base_ring() - if is_MPolynomialRing(base) or polynomial_ring.is_PolynomialRing(base): + if isinstance(base, MPolynomialRing_base) or isinstance(base, polynomial_ring.PolynomialRing_general): from sage.rings.polynomial.flatten import FlatteningMorphism return FlatteningMorphism(self) else: @@ -143,7 +147,7 @@ cdef class MPolynomialRing_base(CommutativeRing): def construction(self): """ - Returns a functor ``F`` and base ring ``R`` such that ``F(R) == self``. + Return a functor ``F`` and base ring ``R`` such that ``F(R) == self``. EXAMPLES:: @@ -156,7 +160,6 @@ cdef class MPolynomialRing_base(CommutativeRing): True sage: F(R) == ZZ['x']['y'] False - """ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.categories.pushout import MultiPolynomialFunctor @@ -317,7 +320,6 @@ cdef class MPolynomialRing_base(CommutativeRing): order for the subring sage: R.remove_var(x,y,z, order='degrevlex') Multivariate Polynomial Ring in u, v over Integer Ring - """ vars = list(self.variable_names()) for v in var: @@ -341,7 +343,7 @@ cdef class MPolynomialRing_base(CommutativeRing): INPUT: - - ``x`` -- a variable of ``self``. + - ``x`` -- a variable of ``self`` EXAMPLES:: @@ -366,14 +368,14 @@ cdef class MPolynomialRing_base(CommutativeRing): INPUT: - * ``bound`` -- either an integer bounding the total degree or a + - ``bound`` -- either an integer bounding the total degree or a list/tuple of integers bounding the degree of the variables - * ``points`` -- list/tuple containing the evaluation points + - ``points`` -- list/tuple containing the evaluation points - * ``values`` -- list/tuple containing the desired values at ``points`` + - ``values`` -- list/tuple containing the desired values at ``points`` - * ``function`` -- evaluable function in `n` variables, where `n` is the + - ``function`` -- evaluable function in `n` variables, where `n` is the number of variables of the polynomial ring OUTPUT: @@ -558,7 +560,7 @@ cdef class MPolynomialRing_base(CommutativeRing): cdef _coerce_c_impl(self, x): """ Return the canonical coercion of x to this multivariate - polynomial ring, if one is defined, or raise a TypeError. + polynomial ring, if one is defined, or raise a :exc:`TypeError`. The rings that canonically coerce to this polynomial ring are: @@ -590,14 +592,14 @@ cdef class MPolynomialRing_base(CommutativeRing): P = x.parent() # polynomial rings in the same variable over the any base # that coerces in: - if is_MPolynomialRing(P): + if isinstance(P, MPolynomialRing_base): if P.variable_names() == self.variable_names(): if self.has_coerce_map_from(P.base_ring()): return self(x) elif self.base_ring().has_coerce_map_from(P._mpoly_base_ring(self.variable_names())): return self(x) - elif polynomial_ring.is_PolynomialRing(P): + elif isinstance(P, polynomial_ring.PolynomialRing_general): if P.variable_name() in self.variable_names(): if self.has_coerce_map_from(P.base_ring()): return self(x) @@ -634,7 +636,7 @@ cdef class MPolynomialRing_base(CommutativeRing): # One is not a parent -- not equal and not ordered return op == Py_NE - if not is_MPolynomialRing(right): + if not isinstance(right, MPolynomialRing_base): return op == Py_NE lft = left @@ -786,8 +788,8 @@ cdef class MPolynomialRing_base(CommutativeRing): INPUT: - - ``gap`` -- (optional GAP instance) Interface to which the - string is addressed. + - ``gap`` -- (optional GAP instance) interface to which the + string is addressed NOTE: @@ -933,8 +935,6 @@ cdef class MPolynomialRing_base(CommutativeRing): raise NotImplementedError def __reduce__(self): - """ - """ base_ring = self.base_ring() n = self.ngens() names = self.variable_names() @@ -986,12 +986,12 @@ cdef class MPolynomialRing_base(CommutativeRing): def _to_monomial(self, i, n, d): """ - Given an index i, a number of variables n and a degree d return - the i-th monomial of degree d in n variables. + Given an index ``i``, a number of variables ``n`` and a degree ``d`` + return the `i`-th monomial of degree `d` in `n` variables. INPUT: - - ``i`` -- index: 0 <= i < binom(n+d-1,n-1) + - ``i`` -- index; ``0 <= i < binom(n+d-1,n-1)`` - ``n`` -- number of variables - ``d`` -- degree @@ -1136,7 +1136,7 @@ cdef class MPolynomialRing_base(CommutativeRing): silently reduced to the maximum number of available terms. - ``choose_degree`` -- choose degrees of monomials randomly first - rather than monomials uniformly random. + rather than monomials uniformly random - ``**kwargs`` -- passed to the random element generator of the base ring @@ -1410,18 +1410,18 @@ cdef class MPolynomialRing_base(CommutativeRing): def _macaulay_resultant_getS(self, mon_deg_tuple, dlist): r""" - In the Macaulay resultant algorithm the list of all monomials of the total degree is partitioned into sets `S_i`. - This function returns the index `i` for the set `S_i` for the given monomial. + In the Macaulay resultant algorithm the list of all monomials of the + total degree is partitioned into sets `S_i`. + This function returns the index `i` for the set `S_i` for the given + monomial. INPUT: - - ``mon_deg_tuple`` -- a list representing a monomial of a degree `d` - - ``dlist`` -- a list of degrees ``d_i`` of the polynomials in + - ``mon_deg_tuple`` -- list representing a monomial of a degree `d` + - ``dlist`` -- list of degrees `d_i` of the polynomials in question, where ``d = sum(dlist) - len(dlist) + 1`` - OUTPUT: - - - the index `i` such that the input monomial is in `S_i` + OUTPUT: the index `i` such that the input monomial is in `S_i` EXAMPLES:: @@ -1451,12 +1451,10 @@ cdef class MPolynomialRing_base(CommutativeRing): INPUT: - ``mon_degs`` -- a monomial represented by a vector of degrees - - ``dlist`` -- a list of degrees with respect to which we check + - ``dlist`` -- list of degrees with respect to which we check reducedness - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES: @@ -1483,7 +1481,7 @@ cdef class MPolynomialRing_base(CommutativeRing): INPUT: - - ``dlist`` -- a list of degrees. + - ``dlist`` -- list of degrees OUTPUT: @@ -1545,18 +1543,16 @@ cdef class MPolynomialRing_base(CommutativeRing): INPUT: - - ``args`` -- a list of `n` homogeneous polynomials in `n` variables. + - ``args`` -- list of `n` homogeneous polynomials in `n` variables works when ``args[0]`` is the list of polynomials, or ``args`` is itself the list of polynomials kwds: - ``sparse`` -- boolean (default: ``False``); if ``True``, the function - creates sparse matrices. + creates sparse matrices - OUTPUT: - - - the Macaulay resultant, an element of the base ring of ``self`` + OUTPUT: the Macaulay resultant, an element of the base ring of ``self`` .. TODO:: @@ -1671,7 +1667,6 @@ cdef class MPolynomialRing_base(CommutativeRing): sage: RH = fh.parent() sage: f.resultant(g) == RH.macaulay_resultant([fh, gh]) # needs sage.modules True - """ from sage.matrix.constructor import matrix from sage.matrix.constructor import zero_matrix diff --git a/src/sage/rings/polynomial/multi_polynomial_sequence.py b/src/sage/rings/polynomial/multi_polynomial_sequence.py index b559993d39f..c20666b0403 100644 --- a/src/sage/rings/polynomial/multi_polynomial_sequence.py +++ b/src/sage/rings/polynomial/multi_polynomial_sequence.py @@ -168,9 +168,9 @@ from sage.rings.finite_rings.finite_field_constructor import FiniteField as GF from sage.rings.infinity import Infinity from sage.rings.polynomial.multi_polynomial_ideal import MPolynomialIdeal -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing -from sage.rings.quotient_ring import is_QuotientRing +from sage.rings.quotient_ring import QuotientRing_nc from sage.structure.sequence import Sequence_generic try: @@ -197,12 +197,16 @@ def is_PolynomialSequence(F): sage: F = Sequence(I, P); F [x^2 + y^2, x^2 - y^2] - sage: from sage.rings.polynomial.multi_polynomial_sequence import is_PolynomialSequence - sage: is_PolynomialSequence(F) + sage: from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence_generic + sage: isinstance(F, PolynomialSequence_generic) True - """ - return isinstance(F,PolynomialSequence_generic) + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_PolynomialSequence is deprecated; " + "use 'isinstance(..., PolynomialSequence_generic)' instead.") + return isinstance(F, PolynomialSequence_generic) + def PolynomialSequence(arg1, arg2=None, immutable=False, cr=False, cr_str=None): """ @@ -213,7 +217,7 @@ def PolynomialSequence(arg1, arg2=None, immutable=False, cr=False, cr_str=None): - ``arg1`` -- a multivariate polynomial ring, an ideal or a matrix - ``arg2`` -- an iterable object of parts or polynomials - (default:``None``) + (default: ``None``) - ``immutable`` -- if ``True`` the sequence is immutable (default: ``False``) @@ -297,7 +301,7 @@ def PolynomialSequence(arg1, arg2=None, immutable=False, cr=False, cr_str=None): except ImportError: BooleanMonomialMonoid = () - is_ring = lambda r: is_MPolynomialRing(r) or isinstance(r, BooleanMonomialMonoid) or (is_QuotientRing(r) and is_MPolynomialRing(r.cover_ring())) + is_ring = lambda r: isinstance(r, MPolynomialRing_base) or isinstance(r, BooleanMonomialMonoid) or (isinstance(r, QuotientRing_nc) and isinstance(r.cover_ring(), MPolynomialRing_base)) if is_ring(arg1): ring, gens = arg1, arg2 @@ -380,9 +384,9 @@ def __init__(self, parts, ring, immutable=False, cr=False, cr_str=None): INPUT: - - ``part`` -- a list of lists with polynomials + - ``part`` -- list of lists with polynomials - - ``ring`` -- a multivariate polynomial ring + - ``ring`` -- a multivariate polynomial ring - ``immutable`` -- if ``True`` the sequence is immutable (default: ``False``) @@ -619,10 +623,10 @@ def nvariables(self): def algebraic_dependence(self): r""" - Returns the ideal of annihilating polynomials for the + Return the ideal of annihilating polynomials for the polynomials in ``self``, if those polynomials are algebraically dependent. - Otherwise, returns the zero ideal. + Otherwise, return the zero ideal. OUTPUT: @@ -722,7 +726,7 @@ def coefficients_monomials(self, order=None, sparse=True): INPUT: - ``sparse`` -- construct a sparse matrix (default: ``True``) - - ``order`` -- a list or tuple specifying the order of monomials (default: ``None``) + - ``order`` -- list or tuple specifying the order of monomials (default: ``None``) EXAMPLES:: @@ -841,8 +845,8 @@ def subs(self, *args, **kwargs): INPUT: - - ``args`` -- arguments to be passed to :meth:`MPolynomial.subs` - - ``kwargs`` -- keyword arguments to be passed to :meth:`MPolynomial.subs` + - ``args`` -- arguments to be passed to :meth:`MPolynomial.subs` + - ``kwargs`` -- keyword arguments to be passed to :meth:`MPolynomial.subs` EXAMPLES:: @@ -921,7 +925,6 @@ def _repr_(self): sage: sr = mq.SR(allow_zero_inversions=True, gf2=True) # needs sage.rings.polynomial.pbori sage: F,s = sr.polynomial_system(); F # needs sage.rings.polynomial.pbori Polynomial Sequence with 36 Polynomials in 20 Variables - """ if len(self) < 20: return Sequence_generic._repr_(self) @@ -958,7 +961,7 @@ def __add__(self, right): b^2 + 2*a*c + 2*b*d - c, a^127 + a] """ - if is_PolynomialSequence(right) and right.ring() == self.ring(): + if isinstance(right, PolynomialSequence_generic) and right.ring() == self.ring(): return PolynomialSequence(self.ring(), self.parts() + right.parts()) elif isinstance(right,(tuple,list)) and all((x.parent() == self.ring() for x in right)): @@ -1105,7 +1108,6 @@ def maximal_degree(self): sage: F = Sequence([], universe=P) sage: F.maximal_degree() -1 - """ try: return max(f.degree() for f in self) @@ -1126,7 +1128,6 @@ def __reduce__(self): sage: f = P.hom([y,z,x]) sage: hash(f) == hash(loads(dumps(f))) True - """ return PolynomialSequence, (self._ring, self._parts, self._is_immutable, self._Sequence_generic__cr, self._Sequence_generic__cr_str) @@ -1196,11 +1197,10 @@ def reduced(self): Check that :issue:`26952` is fixed:: sage: Qp = pAdicField(2) - sage: R. = PolynomialRing(Qp, implementation="generic") # needs sage.rings.padics + sage: R. = PolynomialRing(Qp, implementation='generic') # needs sage.rings.padics sage: F = Sequence([z*x+y^3,z+y^3,3*z+x*y]) sage: F.reduced() [y^3 + z, x*y + (1 + 2 + O(2^20))*z, x*z - z] - """ from sage.rings.polynomial.multi_polynomial_ideal_libsingular import \ interred_libsingular @@ -1234,7 +1234,7 @@ def reduced(self): @singular_gb_standard_options def is_groebner(self, singular=singular): r""" - Returns ``True`` if the generators of this ideal (``self.gens()``) + Return ``True`` if the generators of this ideal (``self.gens()``) form a Groebner basis. Let `I` be the set of generators of this ideal. The check is @@ -1254,7 +1254,6 @@ def is_groebner(self, singular=singular): sage: I2 = Ideal(I.groebner_basis()) sage: I2.basis.is_groebner() True - """ return self.ideal().basis_is_groebner() @@ -1496,27 +1495,26 @@ def solve(self, algorithm='polybori', n=1, eliminate_linear_variables=True, ver INPUT: - * ``self`` -- a sequence of boolean polynomials + - ``self`` -- a sequence of boolean polynomials - * ``algorithm`` -- the method to use. Possible values are - ``polybori``, ``sat`` and ``exhaustive_search``. (default: - ``polybori``, since it is always available) + - ``algorithm`` -- the method to use. Possible values are + ``'polybori'``, ``'sat'`` and ``'exhaustive_search'``. (default: + ``'polybori'``, since it is always available) - * ``n`` -- number of solutions to return. If ``n == +Infinity`` - then all solutions are returned. If `n < \infty` then `n` - solutions are returned if the equations have at least `n` - solutions. Otherwise, all the solutions are - returned. (default: ``1``) + - ``n`` -- (default: 1) number of solutions to return. If + ``n == +Infinity`` then all solutions are returned. If `n < \infty` + then `n` solutions are returned if the equations have at least `n` + solutions. Otherwise, all the solutions are returned. - * ``eliminate_linear_variables`` -- whether to eliminate + - ``eliminate_linear_variables`` -- whether to eliminate variables that appear linearly. This reduces the number of variables (makes solving faster a priori), but is likely to make the equations denser (may make solving slower depending on the method). - * ``verbose`` -- whether to display progress and (potentially) - useful information while the computation runs. (default: - ``False``) + - ``verbose`` -- boolean (default: ``False``); whether to display + progress and (potentially) useful information while the computation + runs EXAMPLES: @@ -1583,7 +1581,6 @@ def solve(self, algorithm='polybori', n=1, eliminate_linear_variables=True, ver sage: S = Sequence([x*y*z + x*y + z*y + x*z, x + y + z + 1, x + y + z]) # needs sage.rings.polynomial.pbori sage: S.solve() # needs sage.rings.polynomial.pbori [] - """ from sage.modules.free_module import VectorSpace @@ -1709,7 +1706,7 @@ def coefficients_monomials(self, order=None, sparse=True): INPUT: - ``sparse`` -- construct a sparse matrix (default: ``True``) - - ``order`` -- a list or tuple specifying the order of monomials (default: ``None``) + - ``order`` -- list or tuple specifying the order of monomials (default: ``None``) EXAMPLES:: diff --git a/src/sage/rings/polynomial/omega.py b/src/sage/rings/polynomial/omega.py index 5f5dfb441e7..20a61096548 100644 --- a/src/sage/rings/polynomial/omega.py +++ b/src/sage/rings/polynomial/omega.py @@ -350,7 +350,7 @@ def _simplify_(numerator, terms): - ``numerator`` -- a Laurent polynomial - - ``terms`` -- a tuple or other iterable of Laurent polynomials + - ``terms`` -- tuple or other iterable of Laurent polynomials The denominator is the product of factors `1 - t` for each `t` in ``terms``. @@ -394,10 +394,10 @@ def _Omega_(A, decoded_factors): INPUT: - - ``A`` -- a dictionary mapping `a` to `c` representing a summand + - ``A`` -- dictionary mapping `a` to `c` representing a summand `c\mu^a` of the numerator - - ``decoded_factors`` -- a tuple or list of pairs `(z, e)` representing + - ``decoded_factors`` -- tuple or list of pairs `(z, e)` representing a factor `1 - z \mu^e` OUTPUT: @@ -482,9 +482,9 @@ def Omega_ge(a, exponents): INPUT: - - ``a`` -- an integer + - ``a`` -- integer - - ``exponents`` -- a tuple of integers + - ``exponents`` -- tuple of integers OUTPUT: @@ -638,9 +638,9 @@ def _Omega_numerator_(a, x, y, t): INPUT: - - ``a`` -- an integer + - ``a`` -- integer - - ``x`` and ``y`` -- a tuple of tuples of Laurent polynomials + - ``x``, ``y`` -- tuple of tuples of Laurent polynomials The flattened ``x`` contains `x_1,...,x_n`, the flattened ``y`` the @@ -650,9 +650,7 @@ def _Omega_numerator_(a, x, y, t): - ``t`` -- a temporary Laurent polynomial variable used for substituting - OUTPUT: - - A Laurent polynomial + OUTPUT: a Laurent polynomial The output is normalized such that the corresponding denominator (:func:`_Omega_factors_denominator_`) has constant term `1`. @@ -755,9 +753,9 @@ def _Omega_numerator_P_(a, x, y, t): INPUT: - - ``a`` -- an integer + - ``a`` -- integer - - ``x`` and ``y`` -- a tuple of Laurent polynomials + - ``x``, ``y`` -- tuple of Laurent polynomials The tuple ``x`` here is the flattened ``x`` of :func:`_Omega_numerator_` but without its last entry. @@ -767,9 +765,7 @@ def _Omega_numerator_P_(a, x, y, t): In the (final) result, ``t`` has to be substituted by the last entry of the flattened ``x`` of :func:`_Omega_numerator_`. - OUTPUT: - - A Laurent polynomial + OUTPUT: a Laurent polynomial TESTS:: @@ -839,7 +835,7 @@ def _Omega_factors_denominator_(x, y): INPUT: - - ``x`` and ``y`` -- a tuple of tuples of Laurent polynomials + - ``x``, ``y`` -- tuple of tuples of Laurent polynomials The flattened ``x`` contains `x_1,...,x_n`, the flattened ``y`` the @@ -958,9 +954,7 @@ def homogeneous_symmetric_function(j, x): - ``x`` -- an iterable of variables - OUTPUT: - - A polynomial of the common parent of all entries of ``x`` + OUTPUT: a polynomial of the common parent of all entries of ``x`` EXAMPLES:: diff --git a/src/sage/rings/polynomial/ore_function_element.py b/src/sage/rings/polynomial/ore_function_element.py index 0c1a919351f..fd871fa3b76 100644 --- a/src/sage/rings/polynomial/ore_function_element.py +++ b/src/sage/rings/polynomial/ore_function_element.py @@ -170,7 +170,6 @@ def _richcmp_(self, other, op): sage: D = K.random_element() sage: Q == 0 or D == 0 or (P*D) / (Q*D) == P/Q # long time True - """ if self.parent()._simplification: return richcmp((self._numerator, self._denominator), (other._numerator, other._denominator), op) @@ -614,7 +613,7 @@ def hilbert_shift(self, s, var=None): - ``s`` -- an element in the base ring - - ``var`` -- a string; the variable name + - ``var`` -- string; the variable name EXAMPLES:: @@ -838,7 +837,7 @@ def reduced_trace(self, var=None): INPUT: - - ``var`` -- a string or ``None`` (default: ``None``); + - ``var`` -- string or ``None`` (default: ``None``); the name of the central variable EXAMPLES:: @@ -901,7 +900,7 @@ def reduced_norm(self, var=None): INPUT: - - ``var`` -- a string or ``None`` (default: ``None``); + - ``var`` -- string or ``None`` (default: ``None``); the name of the central variable EXAMPLES:: diff --git a/src/sage/rings/polynomial/ore_function_field.py b/src/sage/rings/polynomial/ore_function_field.py index ad7fc4fe3c1..1c78217508b 100644 --- a/src/sage/rings/polynomial/ore_function_field.py +++ b/src/sage/rings/polynomial/ore_function_field.py @@ -329,7 +329,7 @@ def change_var(self, var): INPUT: - - ``var`` -- a string representing the name of the new variable. + - ``var`` -- string representing the name of the new variable EXAMPLES:: @@ -375,7 +375,7 @@ def twisting_morphism(self, n=1): INPUT: - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) EXAMPLES:: @@ -438,8 +438,8 @@ def gen(self, n=0): INPUT: - - ``n`` -- index of generator to return (default: 0). Exists for - compatibility with other polynomial rings. + - ``n`` -- index of generator to return (default: 0); exists for + compatibility with other polynomial rings EXAMPLES:: @@ -579,7 +579,7 @@ def random_element(self, degree=2, monic=False, *args, **kwds): - ``degree`` -- (default: 2) an integer or a list of two integers; the degrees of the denominator and numerator - - ``monic`` -- (default: ``False``) if ``True``, return a monic + - ``monic`` -- boolean (default: ``False``); if ``True``, return a monic Ore function with monic numerator and denominator - ``*args``, ``**kwds`` -- passed in to the :meth:`random_element` @@ -917,10 +917,10 @@ def center(self, name=None, names=None, default=False): INPUT: - - ``name`` -- a string or ``None`` (default: ``None``); + - ``name`` -- string or ``None`` (default: ``None``); the name for the central variable - - ``default`` -- a boolean (default: ``False``); if ``True``, + - ``default`` -- boolean (default: ``False``); if ``True``, set the default variable name for the center to ``name`` EXAMPLES:: diff --git a/src/sage/rings/polynomial/ore_polynomial_element.pyx b/src/sage/rings/polynomial/ore_polynomial_element.pyx index dc6fbab0ab0..8307bf9694a 100644 --- a/src/sage/rings/polynomial/ore_polynomial_element.pyx +++ b/src/sage/rings/polynomial/ore_polynomial_element.pyx @@ -274,7 +274,7 @@ cdef class OrePolynomial(AlgebraElement): cdef OrePolynomial _new_c(self, list coeffs, Parent P, char check=0): r""" - Fast creation of a new Ore polynomial + Fast creation of a new Ore polynomial. .. NOTE:: @@ -285,7 +285,7 @@ cdef class OrePolynomial(AlgebraElement): cpdef OrePolynomial _new_constant_poly(self, RingElement a, Parent P, char check=0): r""" - Fast creation of a new constant Ore polynomial + Fast creation of a new constant Ore polynomial. EXAMPLES:: @@ -307,7 +307,7 @@ cdef class OrePolynomial(AlgebraElement): r""" Set the ``n``-th coefficient of ``self``. - This always raises an ``IndexError``, since polynomials are immutable in + This always raises an :exc:`IndexError`, since polynomials are immutable in Sage. EXAMPLES:: @@ -583,7 +583,7 @@ cdef class OrePolynomial(AlgebraElement): cpdef _mod_(self, other): r""" Return the remainder in the *right* Euclidean division of - ``self`` by ``other```. + ``self`` by ``other``. TESTS:: @@ -660,9 +660,7 @@ cdef class OrePolynomial(AlgebraElement): - ``other`` -- an Ore polynomial in the same ring as ``self`` - OUTPUT: - - Return ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -696,9 +694,7 @@ cdef class OrePolynomial(AlgebraElement): - ``other`` -- an Ore polynomial in the same ring as ``self`` - OUTPUT: - - Return ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -746,9 +742,7 @@ cdef class OrePolynomial(AlgebraElement): - ``other`` -- an Ore polynomial in the same ring as ``self`` - OUTPUT: - - Return ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -782,9 +776,7 @@ cdef class OrePolynomial(AlgebraElement): - ``other`` -- an Ore polynomial in the same ring as ``self`` - OUTPUT: - - Return ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -1440,7 +1432,7 @@ cdef class OrePolynomial(AlgebraElement): - ``other`` -- an Ore polynomial in the same ring as ``self`` - - ``monic`` -- a boolean (default: ``True``); whether the right lcm + - ``monic`` -- boolean (default: ``True``); whether the right lcm should be normalized to be monic EXAMPLES:: @@ -1946,7 +1938,7 @@ cdef class OrePolynomial(AlgebraElement): r""" Return the coefficients of the monomials appearing in ``self``. - If ``sparse=True`` (the default), return only the non-zero coefficients. + If ``sparse=True`` (the default), return only the nonzero coefficients. Otherwise, return the same value as ``self.list()``. .. NOTE:: @@ -1968,7 +1960,7 @@ cdef class OrePolynomial(AlgebraElement): def number_of_terms(self): r""" - Return the number of non-zero coefficients of ``self``. + Return the number of nonzero coefficients of ``self``. This is also known as the weight, hamming weight or sparsity. @@ -2140,7 +2132,7 @@ cdef class OrePolynomial(AlgebraElement): INPUT: - - ``n`` -- (default: ``None``); if given, an integer that + - ``n`` -- (default: ``None``) if given, an integer that is at least `0` EXAMPLES:: @@ -2200,7 +2192,7 @@ cdef void lmul_gen(list A, Morphism m, d) noexcept: INPUT: - - ``A`` -- a list of coefficients + - ``A`` -- list of coefficients - ``m`` -- the twisting morphism of the Ore polynomial ring @@ -2441,11 +2433,9 @@ cdef class OrePolynomial_generic_dense(OrePolynomial): INPUT: - - ``n`` -- an integer - - OUTPUT: + - ``n`` -- integer - - the ``n``-th coefficient of ``self`` + OUTPUT: the ``n``-th coefficient of ``self`` EXAMPLES:: @@ -2634,7 +2624,7 @@ cdef class OrePolynomial_generic_dense(OrePolynomial): def valuation(self): r""" - Return the minimal degree of a non-zero monomial of ``self``. + Return the minimal degree of a nonzero monomial of ``self``. By convention, the zero Ore polynomial has valuation `+\infty`. @@ -2856,7 +2846,7 @@ cdef class OrePolynomial_generic_dense(OrePolynomial): r""" Return the coefficients of the monomials appearing in ``self``. - If ``sparse=True`` (the default), return only the non-zero coefficients. + If ``sparse=True`` (the default), return only the nonzero coefficients. Otherwise, return the same value as ``self.list()``. EXAMPLES:: @@ -2885,7 +2875,7 @@ cdef class OrePolynomial_generic_dense(OrePolynomial): - ``s`` -- an element in the base ring - - ``var`` -- a string; the variable name + - ``var`` -- string; the variable name EXAMPLES:: @@ -3050,10 +3040,10 @@ cdef class OrePolynomialBaseringInjection(Morphism): INPUT: - - ``domain`` -- a ring `R`. This will be the domain of the injection. + - ``domain`` -- a ring `R`; this will be the domain of the injection - - ``codomain`` -- an Ore polynomial ring over ``domain``. This will be - the codomain. + - ``codomain`` -- an Ore polynomial ring over ``domain``; this will be + the codomain TESTS:: @@ -3105,9 +3095,7 @@ cdef class OrePolynomialBaseringInjection(Morphism): - ``e`` -- element belonging to the base ring according to ``self`` - OUTPUT: - - The Ore polynomial corresponding to `e` according to ``self``. + OUTPUT: the Ore polynomial corresponding to `e` according to ``self`` TESTS:: diff --git a/src/sage/rings/polynomial/ore_polynomial_ring.py b/src/sage/rings/polynomial/ore_polynomial_ring.py index b3848f0a10c..f28b90ad198 100644 --- a/src/sage/rings/polynomial/ore_polynomial_ring.py +++ b/src/sage/rings/polynomial/ore_polynomial_ring.py @@ -68,9 +68,9 @@ class OrePolynomialRing(UniqueRepresentation, Parent): - ``twisting_map`` -- either an endomorphism of the base ring, or a (twisted) derivation of it - - ``names`` -- a string or a list of strings + - ``names`` -- string or list of strings - - ``sparse`` -- a boolean (default: ``False``); currently not supported + - ``sparse`` -- boolean (default: ``False``); currently not supported EXAMPLES: @@ -304,7 +304,7 @@ def __classcall_private__(cls, base_ring, twist=None, names=None, sparse=False, If there is no twisting derivation and that the twisting morphism is - `None` ot the identity, a regular `PolynomialRing` is created, unless + ``None`` ot the identity, a regular `PolynomialRing` is created, unless specified otherwise:: sage: # needs sage.rings.finite_rings @@ -348,7 +348,7 @@ def __classcall_private__(cls, base_ring, twist=None, names=None, sparse=False, except IndexError: raise NotImplementedError("multivariate Ore polynomials rings not supported") - # If `polcast` is `True` and there is no twisting morphism and no + # If `polcast` is ``True`` and there is no twisting morphism and no # twisting derivation we return a classical polynomial ring if polcast and derivation is None and morphism is None: return PolynomialRing(base_ring, names, sparse=sparse) @@ -660,7 +660,7 @@ def change_var(self, var): INPUT: - - ``var`` -- a string representing the name of the new variable + - ``var`` -- string representing the name of the new variable EXAMPLES:: @@ -709,7 +709,7 @@ def twisting_morphism(self, n=1): INPUT: - - ``n`` -- an integer (default: 1) + - ``n`` -- integer (default: 1) EXAMPLES:: @@ -972,7 +972,7 @@ def random_element(self, degree=(-1, 2), monic=False, *args, **kwds): - ``degree`` -- (default: ``(-1,2)``) integer with degree or a tuple of integers with minimum and maximum degrees - - ``monic`` -- (default: ``False``) if ``True``, return a monic + - ``monic`` -- boolean (default: ``False``); if ``True``, return a monic Ore polynomial - ``*args``, ``**kwds`` -- passed on to the ``random_element`` method @@ -1014,7 +1014,7 @@ def random_element(self, degree=(-1, 2), monic=False, *args, **kwds): TESTS: If the first tuple element is greater than the second, a - :class:`ValueError` is raised:: + :exc:`ValueError` is raised:: sage: S.random_element(degree=(5,4)) # needs sage.rings.finite_rings Traceback (most recent call last): @@ -1062,14 +1062,14 @@ def random_irreducible(self, degree=2, monic=True, *args, **kwds): INPUT: - - ``degree`` -- Integer with degree (default: 2) - or a tuple of integers with minimum and maximum degrees + - ``degree`` -- integer with degree (default: 2) + or a tuple of integers with minimum and maximum degrees - - ``monic`` -- if ``True``, returns a monic Ore polynomial - (default: ``True``) + - ``monic`` -- if ``True``, returns a monic Ore polynomial + (default: ``True``) - - ``*args, **kwds`` -- passed in to the ``random_element`` method for - the base ring + - ``*args``, ``**kwds`` -- passed in to the ``random_element`` method for + the base ring EXAMPLES:: diff --git a/src/sage/rings/polynomial/padics/polynomial_padic.py b/src/sage/rings/polynomial/padics/polynomial_padic.py index 4103fbf9fe2..30222f0ad59 100644 --- a/src/sage/rings/polynomial/padics/polynomial_padic.py +++ b/src/sage/rings/polynomial/padics/polynomial_padic.py @@ -142,7 +142,6 @@ def content(self): sage: f = 13*t^3 + K(0,1)*t sage: f.content() 13 + O(13^8) - """ if self.is_zero(): return self[0] @@ -270,11 +269,11 @@ def root_field(self, names, check_irreducible=True, **kwds): INPUT: - * ``names`` -- name of the generator of the extension + - ``names`` -- name of the generator of the extension - * ``check_irreducible`` -- check whether the polynomial is irreducible + - ``check_irreducible`` -- check whether the polynomial is irreducible - * ``kwds`` -- see :meth:`sage.rings.padics.padic_generic.pAdicGeneric.extension` + - ``kwds`` -- see :meth:`sage.rings.padics.padic_generic.pAdicGeneric.extension` EXAMPLES:: @@ -298,7 +297,6 @@ def root_field(self, names, check_irreducible=True, **kwds): Traceback (most recent call last): ... ValueError: polynomial must be irreducible - """ if check_irreducible and not self.is_irreducible(): @@ -317,7 +315,7 @@ def _pari_padic_factorization_to_sage(G, R, leading_coeff): INPUT: - - ``G`` -- PARI factorization matrix, returned by ``factorpadic``. + - ``G`` -- PARI factorization matrix, returned by ``factorpadic`` - ``R`` -- polynomial ring to be used as parent ring of the factors @@ -325,10 +323,7 @@ def _pari_padic_factorization_to_sage(G, R, leading_coeff): was factored. This can belong to any ring which can be coerced into ``R.base_ring()``. - OUTPUT: - - - A Sage :class:`Factorization`. - + OUTPUT: a Sage :class:`Factorization` """ B = R.base_ring() p = B.prime() diff --git a/src/sage/rings/polynomial/padics/polynomial_padic_capped_relative_dense.py b/src/sage/rings/polynomial/padics/polynomial_padic_capped_relative_dense.py index 5290ef34ed0..604764eff35 100644 --- a/src/sage/rings/polynomial/padics/polynomial_padic_capped_relative_dense.py +++ b/src/sage/rings/polynomial/padics/polynomial_padic_capped_relative_dense.py @@ -1,6 +1,6 @@ # sage.doctest: needs sage.libs.ntl """ -p-adic Capped Relative Dense Polynomials +`p`-adic Capped Relative Dense Polynomials """ # **************************************************************************** @@ -482,7 +482,7 @@ def _sub_(self, right): def _mul_(self, right): r""" - Multiplies ``self`` and ``right``. + Multiply ``self`` and ``right``. ALGORITHM: We use an algorithm thought up by Joe Wetherell to find the precisions of the product. It works as follows: @@ -490,7 +490,7 @@ def _mul_(self, right): = \max(\deg f, \deg g) + 1` (in the actual implementation we use `N = 2^{\lfloor \log_2\max(\deg f, \deg g)\rfloor + 1}`). The valuations and absolute precisions of each coefficient - contribute to the absolute precision of the kth coefficient of + contribute to the absolute precision of the `k`-th coefficient of the product in the following way: for each `i + j = k`, you take the valuation of `a_i` plus the absolute precision of `b_j`, and then take the valuation of `b_j` plus the absolute @@ -623,7 +623,7 @@ def lshift_coeffs(self, shift, no_list=False): def rshift_coeffs(self, shift, no_list=False): """ - Return a new polynomial whose coefficients are p-adically + Return a new polynomial whose coefficients are `p`-adically shifted to the right by ``shift``. .. NOTE:: @@ -668,7 +668,7 @@ def rshift_coeffs(self, shift, no_list=False): def _unsafe_mutate(self, n, value): """ - It's a really bad idea to use this function for p-adic + It's a really bad idea to use this function for `p`-adic polynomials. There are speed issues, and it may not be bug-free currently. """ @@ -752,7 +752,7 @@ def degree(self, secure=False): INPUT: - - ``secure`` -- a boolean (default: ``False``) + - ``secure`` -- boolean (default: ``False``) If ``secure`` is ``True`` and the degree of this polynomial is not determined (because the leading coefficient is @@ -820,9 +820,9 @@ def precision_absolute(self, n=None): INPUT: - - ``self`` -- a p-adic polynomial + - ``self`` -- a `p`-adic polynomial - - ``n`` -- ``None`` or an integer (default ``None``). + - ``n`` -- ``None`` or integer (default: ``None``) OUTPUT: @@ -849,9 +849,9 @@ def precision_relative(self, n=None): INPUT: - - ``self`` -- a p-adic polynomial + - ``self`` -- a `p`-adic polynomial - - ``n`` -- ``None`` or an integer (default ``None``). + - ``n`` -- ``None`` or integer (default: ``None``) OUTPUT: @@ -885,9 +885,9 @@ def valuation_of_coefficient(self, n=None): INPUT: - - ``self`` -- a p-adic polynomial + - ``self`` -- a `p`-adic polynomial - - ``n`` -- ``None`` or an integer (default ``None``). + - ``n`` -- ``None`` or integer (default: ``None``) OUTPUT: @@ -919,14 +919,14 @@ def valuation(self, val_of_var=None): INPUT: - - ``self`` -- a p-adic polynomial + - ``self`` -- a `p`-adic polynomial - - ``val_of_var`` -- ``None`` or a rational (default ``None``). + - ``val_of_var`` -- ``None`` or a rational (default: ``None``) OUTPUT: If ``val_of_var`` is ``None``, returns the largest power of the - variable dividing self. Otherwise, returns the valuation of + variable dividing ``self``. Otherwise, returns the valuation of ``self`` where the variable is assigned valuation ``val_of_var`` EXAMPLES:: @@ -953,8 +953,8 @@ def reverse(self, degree=None): INPUT: - - ``degree`` (``None`` or an integer) -- if specified, truncate or zero - pad the list of coefficients to this degree before reversing it. + - ``degree`` -- ``None`` or integer; if specified, truncate or zero + pad the list of coefficients to this degree before reversing it EXAMPLES:: @@ -1061,7 +1061,6 @@ def quo_rem(self, right, secure=False): sage: R. = Qp(3)[] sage: x.quo_rem(x) (1 + O(3^20), 0) - """ return self._quo_rem_list(right, secure=secure) @@ -1139,9 +1138,7 @@ def newton_polygon(self): If some coefficients have not enough precision an error is raised. - OUTPUT: - - - a :class:`NewtonPolygon` + OUTPUT: a :class:`NewtonPolygon` EXAMPLES:: @@ -1275,11 +1272,9 @@ def newton_slopes(self, repetition=True): INPUT: - - ``repetition`` -- boolean (default ``True``) - - OUTPUT: + - ``repetition`` -- boolean (default: ``True``) - - a list of rationals + OUTPUT: list of rationals EXAMPLES:: diff --git a/src/sage/rings/polynomial/padics/polynomial_padic_flat.py b/src/sage/rings/polynomial/padics/polynomial_padic_flat.py index 46ef0c0a9b9..4db824cd0cc 100644 --- a/src/sage/rings/polynomial/padics/polynomial_padic_flat.py +++ b/src/sage/rings/polynomial/padics/polynomial_padic_flat.py @@ -1,5 +1,5 @@ """ -p-adic Flat Polynomials +`p`-adic Flat Polynomials """ # **************************************************************************** diff --git a/src/sage/rings/polynomial/pbori/PyPolyBoRi.py b/src/sage/rings/polynomial/pbori/PyPolyBoRi.py index 18ca366fb85..aa341f35c5d 100644 --- a/src/sage/rings/polynomial/pbori/PyPolyBoRi.py +++ b/src/sage/rings/polynomial/pbori/PyPolyBoRi.py @@ -60,7 +60,7 @@ sage: r = r.clone(names=["z17", "z7"]) sage: [r.variable(idx) for idx in range(3)] [z17, z7, x2] - sage: r = r.clone(names="abcde") + sage: r = r.clone(names='abcde') sage: [r.variable(idx) for idx in range(6)] [a, b, c, d, e, y2] """ @@ -104,7 +104,8 @@ def WeakRingRef(ring): def add_up_polynomials(polys, init): r""" - Adds up the polynomials in polys (which should be a BoolePolynomialVector or a sequence of ??? + Add up the polynomials in polys (which should be a + ``BoolePolynomialVector`` or a sequence of ??? """ if not isinstance(polys, BoolePolynomialVector): vec = BoolePolynomialVector diff --git a/src/sage/rings/polynomial/pbori/blocks.py b/src/sage/rings/polynomial/pbori/blocks.py index 8280fd7db81..dac6ed81303 100644 --- a/src/sage/rings/polynomial/pbori/blocks.py +++ b/src/sage/rings/polynomial/pbori/blocks.py @@ -104,8 +104,8 @@ def g(j): class AdderBlock(AlternatingBlock): - def __init__(self, adder_bits, sums="s", carries="c", input1="a", - input2="b", start_index=0): + def __init__(self, adder_bits, sums='s', carries='c', input1='a', + input2='b', start_index=0): AlternatingBlock.__init__(self, (sums, carries, input1, input2), adder_bits, start_index=start_index, reverse=True) @@ -154,11 +154,14 @@ class HigherOrderBlock: For each dimension a separate start_index and size can be specified. - var_name : variables will be called (multiindex), where multiindex is a tuple of the size + var_name : variables will be called (multiindex), where + multiindex is a tuple of the size - size_tuple : specifies the sizes of the ranges of each component of the multi-indices + size_tuple : specifies the sizes of the ranges of each component of the + multi-indices - start_index_tuple : the multi-indices will be of the form start_index_tuple + a, where a is a multi-index with non-negative components + start_index_tuple : the multi-indices will be of the form + start_index_tuple + a, where a is a multi-index with nonnegative components """ def __init__(self, var_name, size_tuple, start_index_tuple=None, reverse=False): @@ -195,7 +198,7 @@ def var_func(*indices): class InOutBlock: - def __init__(self, out_size, in_size, output="out", input="in", + def __init__(self, out_size, in_size, output='out', input='in', in_start_index=0, out_start_index=0, out_reverse=False, in_reverse=False): self.output = Block(var_name=output, start_index=out_start_index, diff --git a/src/sage/rings/polynomial/pbori/gbcore.py b/src/sage/rings/polynomial/pbori/gbcore.py index 836d5f7a2a6..8371577157d 100644 --- a/src/sage/rings/polynomial/pbori/gbcore.py +++ b/src/sage/rings/polynomial/pbori/gbcore.py @@ -356,7 +356,6 @@ def other_ordering_pre(I, option_set, kwds): sage: from sage.rings.polynomial.pbori.gbcore import groebner_basis sage: groebner_basis(id) [1] - """ if not I: return (I, None) @@ -541,7 +540,7 @@ def groebner_basis(I, heuristic=True, unique_ideal_generator=False, fglm_bound=40000, modified_linear_algebra=True, preprocessor=None, deg_bound=False, - implementation="Python", full_prot=False, prot=False, + implementation='Python', full_prot=False, prot=False, draw_matrices=False, preprocess_only=False, **impl_options): """Computes a Groebner basis of a given ideal I, w.r.t options.""" diff --git a/src/sage/rings/polynomial/pbori/gbrefs.py b/src/sage/rings/polynomial/pbori/gbrefs.py index 0f5436c5b5f..4ac92f359c2 100644 --- a/src/sage/rings/polynomial/pbori/gbrefs.py +++ b/src/sage/rings/polynomial/pbori/gbrefs.py @@ -38,7 +38,7 @@ def load_ref_raw(s): return res -def load_ref(s, ordering="lp", blocks=SINGLE): +def load_ref(s, ordering='lp', blocks=SINGLE): return load_ref_gz_uu(s, ordering, blocks) @@ -68,7 +68,7 @@ def load_ref_gz_uu(s, o, b): uu.decode(ref_file, res) res = res.getvalue() res = StringIO(res) - res = gzip.GzipFile(fileobj=res, mode="r").read() + res = gzip.GzipFile(fileobj=res, mode='r').read() res = res.replace(" ", "") return res @@ -77,7 +77,7 @@ def convert_refs(ref_file_orig): with open(ref_file_orig) as file: content = file.read() buf_out = StringIO() - zipped = gzip.GzipFile(filename=ref_file_orig, mode="w", fileobj=buf_out) + zipped = gzip.GzipFile(filename=ref_file_orig, mode='w', fileobj=buf_out) zipped.write(content) zipped.close() val = buf_out.getvalue() @@ -107,7 +107,7 @@ def clean_data(data): delattr(data, a) -def load_data(file_name, base_dir="./"): +def load_data(file_name, base_dir='./'): in_file = file_name if not re.match("^data", in_file): in_file = "data/" + in_file diff --git a/src/sage/rings/polynomial/pbori/nf.py b/src/sage/rings/polynomial/pbori/nf.py index 0148826e033..004abef5243 100644 --- a/src/sage/rings/polynomial/pbori/nf.py +++ b/src/sage/rings/polynomial/pbori/nf.py @@ -591,7 +591,7 @@ def symmGB_F2_C(G, opt_exchange=True, opt_allow_recursion=False, use_noro=False, use_faugere=False, ll=False, opt_linear_algebra_in_last_block=True, max_generators=None, red_tail_deg_growth=True, - modified_linear_algebra=True, matrix_prefix="", + modified_linear_algebra=True, matrix_prefix='', draw_matrices=False): if use_noro: raise NotImplementedError("noro not implemented for symmgb") diff --git a/src/sage/rings/polynomial/pbori/parallel.py b/src/sage/rings/polynomial/pbori/parallel.py index 32eb3894312..134ee6b2adb 100644 --- a/src/sage/rings/polynomial/pbori/parallel.py +++ b/src/sage/rings/polynomial/pbori/parallel.py @@ -19,7 +19,7 @@ def to_fast_pickable(l): INPUT: - - a list of Boolean polynomials + - ``l`` -- a list of Boolean polynomials OUTPUT: @@ -111,11 +111,9 @@ def from_fast_pickable(l, r): INPUT: - See OUTPUT of :func:`to_fast_pickable` + See OUTPUT of :func:`to_fast_pickable`. - OUTPUT: - - a list of Boolean polynomials + OUTPUT: list of Boolean polynomials EXAMPLES:: @@ -266,7 +264,8 @@ def groebner_basis_first_finished(I, *l): INPUT: - ``I`` -- ideal - - ``l`` -- keyword dictionaries, which will be keyword arguments to groebner_basis. + - ``l`` -- keyword dictionaries, which will be keyword arguments to + ``groebner_basis`` OUTPUT: diff --git a/src/sage/rings/polynomial/pbori/pbori.pyx b/src/sage/rings/polynomial/pbori/pbori.pyx index 3c06d1e390e..686edf8892d 100644 --- a/src/sage/rings/polynomial/pbori/pbori.pyx +++ b/src/sage/rings/polynomial/pbori/pbori.pyx @@ -56,7 +56,6 @@ AUTHORS: to improve compatibility with MPolynomial and make the variety() function work on ideals of BooleanPolynomial's. - EXAMPLES: Consider the ideal @@ -258,9 +257,9 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``n`` -- number of variables (an integer > 1) + - ``n`` -- integer > 1; number of variables - - ``names`` -- names of ring variables, may be a string or + - ``names`` -- names of ring variables; may be a string or list/tuple - ``order`` -- term order (default: lex) @@ -473,7 +472,7 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): R = I.ring() return QuotientFunctor(I, names=self.variable_names(), domain=R.category(), codomain=self.category(), - implementation="pbori", + implementation='pbori', order=self.term_order()), R def ngens(self): @@ -496,11 +495,11 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): def gen(self, i=0): """ - Return the i-th generator of this boolean polynomial ring. + Return the `i`-th generator of this boolean polynomial ring. INPUT: - - ``i`` -- an integer or a boolean monomial in one variable + - ``i`` -- integer or a boolean monomial in one variable EXAMPLES:: @@ -569,7 +568,7 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): sage: P. = BooleanPolynomialRing() sage: P.term_order() Lexicographic term order - sage: R = P.change_ring(names=('a', 'b', 'c'), order="deglex") + sage: R = P.change_ring(names=('a', 'b', 'c'), order='deglex') sage: R Boolean PolynomialRing in a, b, c sage: R.term_order() @@ -1093,10 +1092,10 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``gens`` -- list or tuple of generators + - ``gens`` -- list or tuple of generators - - ``coerce`` -- bool (default: ``True``) automatically - coerce the given polynomials to this ring to form the ideal + - ``coerce`` -- boolean (default: ``True``); automatically + coerce the given polynomials to this ring to form the ideal EXAMPLES:: @@ -1126,18 +1125,17 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``degree`` -- maximum degree (default: 2 for len(var_set) > 1, 1 otherwise) - - - ``terms`` -- number of terms requested (default: 5). If more - terms are requested than exist, then this parameter is - silently reduced to the maximum number of available terms. + - ``degree`` -- maximum degree (default: 2 for len(var_set) > 1, 1 otherwise) - - ``choose_degree`` -- choose degree of monomials - randomly first, rather than monomials uniformly random + - ``terms`` -- number of terms requested (default: 5). If more + terms are requested than exist, then this parameter is + silently reduced to the maximum number of available terms. - - ``vars_set`` -- list of integer indices of - generators of self to use in the generated polynomial + - ``choose_degree`` -- choose degree of monomials + randomly first, rather than monomials uniformly random + - ``vars_set`` -- list of integer indices of + generators of ``self`` to use in the generated polynomial EXAMPLES:: @@ -1262,18 +1260,18 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``degree`` -- maximum degree + - ``degree`` -- maximum degree - - ``monom_counts`` -- a list containing total number - of monomials up to given degree + - ``monom_counts`` -- list containing total number + of monomials up to given degree - - ``vars_set`` -- list of variable indices to use in - the generated polynomial + - ``vars_set`` -- list of variable indices to use in + the generated polynomial - - ``dfirst`` -- if ``True`` choose degree - first, otherwise choose the monomial uniformly + - ``dfirst`` -- if ``True`` choose degree + first, otherwise choose the monomial uniformly - - ``l`` -- number of monomials to generate + - ``l`` -- number of monomials to generate EXAMPLES:: @@ -1298,15 +1296,15 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): def _random_monomial_uniform(self, monom_counts, vars_set): r""" Choose a random monomial uniformly from set of monomials in the - variables indexed by ``vars_set`` in self. + variables indexed by ``vars_set`` in ``self``. INPUT: - - ``monom_counts`` -- list of number of monomials up - to given degree + - ``monom_counts`` -- list of number of monomials up + to given degree - - ``vars_set`` -- list of variable indices to use in - the generated monomial + - ``vars_set`` -- list of variable indices to use in + the generated monomial EXAMPLES:: @@ -1346,9 +1344,9 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``degree`` -- maximum degree + - ``degree`` -- maximum degree - - ``vars_set`` -- list of variable indices of self + - ``vars_set`` -- list of variable indices of self EXAMPLES:: @@ -1445,7 +1443,7 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``magma`` -- a magma instance + - ``magma`` -- a magma instance EXAMPLES:: @@ -1474,11 +1472,9 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): INPUT: - - ``zeros`` -- the set of interpolation points mapped - to zero + - ``zeros`` -- the set of interpolation points mapped to zero - - ``ones`` -- the set of interpolation points mapped to - one + - ``ones`` -- the set of interpolation points mapped to one EXAMPLES: @@ -1585,11 +1581,11 @@ cdef class BooleanPolynomialRing(BooleanPolynomialRing_base): def variable(self, i=0): """ - Return the i-th generator of this boolean polynomial ring. + Return the `i`-th generator of this boolean polynomial ring. INPUT: - - ``i`` -- an integer or a boolean monomial in one variable + - ``i`` -- integer or a boolean monomial in one variable EXAMPLES:: @@ -1803,7 +1799,7 @@ def get_var_mapping(ring, other): other. If it is an element, only variables occurring in other are mapped. - Raises ``NameError`` if no such mapping is possible. + Raises :exc:`NameError` if no such mapping is possible. EXAMPLES:: @@ -1879,7 +1875,6 @@ class BooleanMonomialMonoid(UniqueRepresentation, Monoid_class): sage: loads(dumps(M)) is M True sage: TestSuite(M).run() - """ def __init__(self, BooleanPolynomialRing polring): """ @@ -1949,11 +1944,11 @@ class BooleanMonomialMonoid(UniqueRepresentation, Monoid_class): def gen(self, Py_ssize_t i=0): """ - Return the i-th generator of ``self``. + Return the `i`-th generator of ``self``. INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -2027,7 +2022,7 @@ class BooleanMonomialMonoid(UniqueRepresentation, Monoid_class): x Convert elements from :class:`BooleanMonomialMonoid` where the - generators of self include the generators of the other monoid:: + generators of ``self`` include the generators of the other monoid:: sage: from sage.rings.polynomial.pbori.pbori import BooleanMonomialMonoid sage: R. = BooleanPolynomialRing(2) @@ -2133,7 +2128,6 @@ class BooleanMonomialMonoid(UniqueRepresentation, Monoid_class): sage: M((0,2,0)) x*z - """ cdef BooleanMonomial m cdef PBMonom t @@ -2255,7 +2249,7 @@ cdef class BooleanMonomial(MonoidElement): def __reduce__(self): """ - Pickling + Pickling. TESTS:: @@ -2521,7 +2515,7 @@ cdef class BooleanMonomial(MonoidElement): INPUT: - - ``rhs`` -- a boolean monomial + - ``rhs`` -- boolean monomial EXAMPLES:: @@ -2549,7 +2543,7 @@ cdef class BooleanMonomial(MonoidElement): INPUT: - - ``rhs`` -- a boolean monomial + - ``rhs`` -- boolean monomial EXAMPLES:: @@ -2621,7 +2615,7 @@ cdef class BooleanMonomial(MonoidElement): def iterindex(self): """ - Return an iterator over the indices of the variables in self. + Return an iterator over the indices of the variables in ``self``. EXAMPLES:: @@ -2785,7 +2779,7 @@ cdef class BooleanMonomial(MonoidElement): INPUT: - - ``rhs`` -- a boolean monomial + - ``rhs`` -- boolean monomial EXAMPLES:: @@ -2932,7 +2926,7 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``parent`` -- a boolean polynomial ring + - ``parent`` -- boolean polynomial ring TESTS:: @@ -3513,7 +3507,7 @@ cdef class BooleanPolynomial(MPolynomial): def is_one(BooleanPolynomial self): """ - Check if self is 1. + Check if ``self`` is 1. EXAMPLES:: @@ -3697,7 +3691,7 @@ cdef class BooleanPolynomial(MPolynomial): multivariate polynomial. If this polynomial is not in at most one variable, then a - ``ValueError`` exception is raised. This is checked using the + :exc:`ValueError` exception is raised. This is checked using the :meth:`is_univariate()` method. The new Polynomial is over GF(2) and in the variable ``x`` if no ring ``R`` is provided. @@ -3761,7 +3755,7 @@ cdef class BooleanPolynomial(MPolynomial): def variable(self, i=0): """ - Return the i-th variable occurring in self. The index i is the + Return the i-th variable occurring in ``self``. The index i is the index in ``self.variables()`` EXAMPLES:: @@ -3802,7 +3796,7 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``mon`` -- a monomial + - ``mon`` -- a monomial EXAMPLES:: @@ -3962,10 +3956,9 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``in_dict`` -- (optional) dict with variable:value - pairs + - ``in_dict`` -- (optional) dict with variable:value pairs - - ``**kwds`` -- names parameters + - ``**kwds`` -- names parameters EXAMPLES:: @@ -4053,7 +4046,7 @@ cdef class BooleanPolynomial(MPolynomial): def _magma_init_(self, magma): r""" - Return the Magma representation of self. + Return the Magma representation of ``self``. EXAMPLES:: @@ -4314,7 +4307,6 @@ cdef class BooleanPolynomial(MPolynomial): a*b + a + b + z + 1 sage: f(a+1,b+1,z+1) a*b + a + b + z + 1 - """ return new_BP_from_PBPoly(self._parent, pb_map_every_x_to_x_plus_one(self._pbpoly)) @@ -4363,7 +4355,7 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``rhs`` -- a boolean polynomial + - ``rhs`` -- boolean polynomial EXAMPLES:: @@ -4426,7 +4418,7 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``deg`` -- a degree + - ``deg`` -- a degree EXAMPLES:: @@ -4480,7 +4472,7 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``s`` -- candidate points for evaluation to zero + - ``s`` -- candidate points for evaluation to zero EXAMPLES:: @@ -4589,8 +4581,8 @@ cdef class BooleanPolynomial(MPolynomial): INPUT: - - ``I`` -- a list/set of polynomials in self.parent(). - If I is an ideal, the generators are used. + - ``I`` -- list/set of polynomials in ``self.parent()``; if I is an + ideal, the generators are used EXAMPLES:: @@ -4643,7 +4635,7 @@ cdef class BooleanPolynomial(MPolynomial): cdef class PolynomialConstruct: """ - Implements PolyBoRi's ``Polynomial()`` constructor. + Implement PolyBoRi's ``Polynomial()`` constructor. """ def lead(self, x): """ @@ -4694,7 +4686,7 @@ cdef class PolynomialConstruct: cdef class MonomialConstruct: """ - Implements PolyBoRi's ``Monomial()`` constructor. + Implement PolyBoRi's ``Monomial()`` constructor. """ def __call__(self, x): """ @@ -4732,7 +4724,7 @@ cdef class MonomialConstruct: cdef class VariableConstruct: """ - Implements PolyBoRi's ``Variable()`` constructor. + Implement PolyBoRi's ``Variable()`` constructor. """ def __call__(self, arg, ring=None): """ @@ -4813,9 +4805,9 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): INPUT: - - ``ring`` -- the ring this ideal is defined in + - ``ring`` -- the ring this ideal is defined in - - ``gens`` -- a list of generators + - ``gens`` -- list of generators - ``coerce`` -- coerce all elements to the ring ``ring`` (default: ``True``) @@ -4827,7 +4819,6 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): Ideal (x0*x1*x2*x3 + x0*x1*x3 + x0*x1 + x0*x2 + x0) of Boolean PolynomialRing in x0, x1, x2, x3 sage: loads(dumps(I)) == I True - """ MPolynomialIdeal.__init__(self, ring, gens, coerce) @@ -4853,16 +4844,15 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): INPUT: - - ``algorithm`` -- either ``"polybori"`` (built-in default) - or ``"magma"`` (requires Magma). + - ``algorithm`` -- either ``'polybori'`` (built-in default) + or ``'magma'`` (requires Magma) - ``red_tail`` -- tail reductions in intermediate polynomials, this options affects mainly heuristics. The reducedness of the output polynomials can only be guaranteed by the option - redsb (default: ``True``) + redsb (default: ``True``). - - ``minsb`` -- return a minimal Groebner basis (default: - ``True``) + - ``minsb`` -- return a minimal Groebner basis (default: ``True``) - ``redsb`` -- return a minimal Groebner basis and all tails are reduced (default: ``True``) @@ -4870,8 +4860,7 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): - ``deg_bound`` -- only compute Groebner basis up to a given degree bound (default: ``False``) - - ``faugere`` -- turn off or on the linear algebra (default: - ``False``) + - ``faugere`` -- turn off or on the linear algebra (default: ``False``) - ``linear_algebra_in_last_block`` -- this affects the last block of block orderings and degree orderings. If it is set @@ -4879,12 +4868,12 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): block. (default: ``True``) - ``gauss_on_linear`` -- perform Gaussian elimination on linear - polynomials (default: ``True``) + polynomials (default: ``True``) - ``selection_size`` -- maximum number of polynomials for parallel reductions (default: ``1000``) - - ``heuristic`` -- Turn off heuristic by setting + - ``heuristic`` -- turn off heuristic by setting ``heuristic=False`` (default: ``True``) - ``lazy`` -- (default: ``True``) @@ -4981,7 +4970,6 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): ....: s0s0 + s2s0 + s3s0*s3s1 + s3s0 + 1, s0s0 + s1s1] sage: ideal(problem).groebner_basis() [1] - """ try: return Sequence(sorted(self.__gb, reverse=True), self.ring(), check=False, immutable=True) @@ -5007,7 +4995,7 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): def _groebner_basis(self, **kwds): r""" - Calls PolyBoRi's groebner_basis function. It takes care of the import + Call PolyBoRi's groebner_basis function. It takes care of the import and suitable wrapping (if necessary) EXAMPLES:: @@ -5088,7 +5076,6 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): sage: sols[0]["y"] 1 - """ from sage.misc.converting_dict import KeyConvertingDict R_bool = self.ring() @@ -5134,8 +5121,8 @@ class BooleanPolynomialIdeal(MPolynomialIdeal): If this ideal is spanned by ``(f_1, ..., f_n)`` this method returns ``(g_1, ..., g_s)`` such that: - - `` = `` - - ``LT(g_i) != LT(g_j)`` for all ``i != j``` + - `` = `` + - ``LT(g_i) != LT(g_j)`` for all ``i != j`` - ``LT(g_i)`` does not divide ``m`` for all monomials ``m`` of ``{g_1,...,g_{i-1},g_{i+1},...,g_s}`` @@ -5266,8 +5253,9 @@ cdef class BooleSet: INPUT: - - ``param`` -- either a :class:`CCuddNavigator`, a :class:`BooleSet` or ``None``. - - ``ring`` -- a boolean polynomial ring. + - ``param`` -- either a :class:`CCuddNavigator`, a :class:`BooleSet` or + ``None`` + - ``ring`` -- boolean polynomial ring EXAMPLES:: @@ -5461,7 +5449,6 @@ cdef class BooleSet: X \ Y = \{x | x\in X\;\mathrm{and}\;x\not\in Y\}. - EXAMPLES:: sage: B = BooleanPolynomialRing(5,'x') @@ -5495,7 +5482,6 @@ cdef class BooleSet: X \cup Y = \{x | x\in X\;\mathrm{or}\;x\in Y\}. - EXAMPLES:: sage: B = BooleanPolynomialRing(5,'x') @@ -5572,7 +5558,7 @@ cdef class BooleSet: def __iter__(self): """ - Create an iterator over elements of self. + Create an iterator over elements of ``self``. EXAMPLES:: @@ -5618,7 +5604,7 @@ cdef class BooleSet: INPUT: - - ``vs`` -- a boolean set + - ``vs`` -- boolean set EXAMPLES:: @@ -5797,7 +5783,6 @@ cdef class BooleSet: X \cap Y = \{x | x\in X\;\mathrm{and}\;x\in Y\}. - EXAMPLES:: sage: B = BooleanPolynomialRing(5,'x') @@ -5819,7 +5804,7 @@ cdef class BooleSet: INPUT: - - ``m`` -- a boolean monomial + - ``m`` -- boolean monomial EXAMPLES:: @@ -5838,7 +5823,7 @@ cdef class BooleSet: INPUT: - - ``m`` -- a boolean monomial + - ``m`` -- boolean monomial EXAMPLES:: @@ -5997,7 +5982,7 @@ cdef class BooleanPolynomialVector: INPUT: - - ``I`` -- a list of boolean polynomials. + - ``I`` -- list of boolean polynomials EXAMPLES:: @@ -6191,7 +6176,7 @@ cdef class ReductionStrategy: INPUT: - - ``p`` -- a boolean polynomial. + - ``p`` -- boolean polynomial EXAMPLES:: @@ -6316,7 +6301,7 @@ cdef class ReductionStrategy: INPUT: - - ``p`` -- a boolean polynomial + - ``p`` -- boolean polynomial EXAMPLES:: @@ -6529,11 +6514,9 @@ cdef class GroebnerStrategy: """ def __init__(self, param): """ - INPUT: - - ``param`` -- either ``None`` or a :class:`GroebnerStrategy` - object. + - ``param`` -- either ``None`` or a :class:`GroebnerStrategy` object EXAMPLES:: @@ -6708,7 +6691,7 @@ cdef class GroebnerStrategy: INPUT: - - ``v`` -- a boolean polynomial vector + - ``v`` -- boolean polynomial vector EXAMPLES:: @@ -6811,7 +6794,7 @@ cdef class GroebnerStrategy: def variable_has_value(self, int v): """ - Computes, whether there exists some polynomial of the form + Compute whether there exists some polynomial of the form `v+c` in the Strategy -- where ``c`` is a constant -- in the list of generators. @@ -6852,7 +6835,7 @@ cdef class GroebnerStrategy: INPUT: - - ``p`` -- a boolean polynomial + - ``p`` -- boolean polynomial EXAMPLES:: @@ -6879,7 +6862,6 @@ cdef class GroebnerStrategy: The result is only canonical if the generating set is a Groebner basis. - """ return new_BP_from_PBPoly(self._parent, deref(self._strat).nf(p._pbpoly)) @@ -7126,9 +7108,9 @@ def zeros(pol, BooleSet s): INPUT: - - ``pol`` -- a boolean polynomial + - ``pol`` -- boolean polynomial - - ``s`` -- a set of points encoded as a ``BooleSet`` + - ``s`` -- set of points encoded as a ``BooleSet`` EXAMPLES:: @@ -7324,10 +7306,10 @@ def ll_red_nf_redsb(p, BooleSet reductors): INPUT: - - ``p`` -- a boolean polynomial + - ``p`` -- boolean polynomial - - ``reductors`` -- a boolean set encoding a reduced Groebner basis - with linear leading terms. + - ``reductors`` -- boolean set encoding a reduced Groebner basis + with linear leading terms EXAMPLES:: @@ -7366,10 +7348,10 @@ def ll_red_nf_noredsb(BooleanPolynomial p, BooleSet reductors): INPUT: - - ``p`` -- a boolean polynomial + - ``p`` -- boolean polynomial - - ``reductors`` -- a boolean set encoding a Groebner basis with - linear leading terms. + - ``reductors`` -- boolean set encoding a Groebner basis with + linear leading terms EXAMPLES:: @@ -7399,10 +7381,10 @@ def ll_red_nf_noredsb_single_recursive_call(BooleanPolynomial p, BooleSet reduct INPUT: - - ``p`` -- a boolean polynomial + - ``p`` -- boolean polynomial - - ``reductors`` -- a boolean set encoding a Groebner basis with - linear leading terms. + - ``reductors`` -- boolean set encoding a Groebner basis with + linear leading terms EXAMPLES:: @@ -7439,7 +7421,7 @@ def if_then_else(root, a, b): INPUT: - - ``root`` -- a variable + - ``root`` -- a variable - ``a`` -- the if branch, a ``BooleSet`` or a ``BoolePolynomial`` @@ -7741,7 +7723,7 @@ def easy_linear_factors(BooleanPolynomial p): # todo: merge with pickling from sage.rings.polynomial.pbori.parallel def unpickle_BooleanPolynomial(ring, string): """ - Unpickle boolean polynomials + Unpickle boolean polynomials. EXAMPLES:: @@ -7792,7 +7774,7 @@ cdef class BooleConstant: INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -7809,7 +7791,6 @@ cdef class BooleConstant: sage: from sage.rings.polynomial.pbori.pbori import BooleConstant sage: repr((BooleConstant(0),BooleConstant(1))) # indirect doctest '(0, 1)' - """ if self.is_one(): return '1' @@ -7942,7 +7923,6 @@ cdef class VariableFactory: sage: B. = BooleanPolynomialRing() sage: fac = VariableFactory() sage: fac = VariableFactory(B) - """ if ring is not None: self._factory = PBVariableFactory(ring._pbring) @@ -7978,17 +7958,15 @@ cdef class VariableFactory: cdef class MonomialFactory: """ - Implements PolyBoRi's ``Monomial()`` constructor. If a ring is given is + Implement PolyBoRi's ``Monomial()`` constructor. If a ring is given is can be used as a Monomial factory for the given ring. - EXAMPLES:: sage: from sage.rings.polynomial.pbori.pbori import * sage: B. = BooleanPolynomialRing() sage: fac = MonomialFactory() sage: fac = MonomialFactory(B) - """ def __init__(self, BooleanPolynomialRing ring=None): """ @@ -8053,12 +8031,12 @@ cdef class MonomialFactory: cdef class PolynomialFactory: """ - Implements PolyBoRi's ``Polynomial()`` constructor and + Implement PolyBoRi's ``Polynomial()`` constructor and a polynomial factory for given rings. """ def __init__(self, BooleanPolynomialRing ring=None): """ - Constructs a polynomial factory if ring is given, + Construct a polynomial factory if ring is given, or plain constructor otherwise. EXAMPLES:: @@ -8066,7 +8044,6 @@ cdef class PolynomialFactory: sage: from sage.rings.polynomial.pbori.pbori import * sage: B. = BooleanPolynomialRing() sage: fac = PolynomialFactory() - """ if ring is not None: self._factory = PBPolynomialFactory(ring._pbring) @@ -8101,7 +8078,6 @@ cdef class PolynomialFactory: a sage: PolynomialFactory(B)(1) 1 - """ if self._ring is None: if isinstance(arg, BooleanPolynomial): diff --git a/src/sage/rings/polynomial/plural.pyx b/src/sage/rings/polynomial/plural.pyx index cdcb01eb2d2..eb6b091c683 100644 --- a/src/sage/rings/polynomial/plural.pyx +++ b/src/sage/rings/polynomial/plural.pyx @@ -157,7 +157,7 @@ class G_AlgFactory(UniqueFactory): - ``key`` -- a 6-tuple, formed by a base ring, a tuple of names, two matrices over a polynomial ring over the base ring with the given variable names, a term order, and a category - - ``extra_args`` -- a dictionary, whose only relevant key is 'check' + - ``extra_args`` -- dictionary, whose only relevant key is 'check' TESTS:: @@ -182,11 +182,11 @@ class G_AlgFactory(UniqueFactory): - ``base_ring`` -- a ring - ``c``, ``d`` -- two matrices - - ``names`` -- a tuple or list of names + - ``names`` -- tuple or list of names - ``order`` -- (optional) term order - ``category`` -- (optional) category - - ``check`` -- optional bool - - ``commutative`` -- optional bool + - ``check`` -- (optional) boolean + - ``commutative`` -- (optional) boolean TESTS:: @@ -261,7 +261,7 @@ cdef class NCPolynomialRing_plural(Ring): INPUT: - ``base_ring`` -- base ring (must be either `\GF{q}`, `\ZZ`, `\ZZ/n\ZZ`, `\QQ` or absolute number field) - - ``names`` -- a tuple of names of ring variables + - ``names`` -- tuple of names of ring variables - ``c``, ``d`` -- upper triangular matrices of coefficients, resp. commutative polynomials, satisfying the nondegeneracy conditions, which are to be tested if ``check`` is ``True``. These @@ -767,7 +767,7 @@ cdef class NCPolynomialRing_plural(Ring): INPUT: - ``add_commutative`` (optional bool, default ``False``) + - ``add_commutative`` -- boolean (default: ``False``) OUTPUT: @@ -838,7 +838,7 @@ cdef class NCPolynomialRing_plural(Ring): INPUT: - - ``n`` -- an integer ``>= 0`` + - ``n`` -- nonnegative integer EXAMPLES:: @@ -851,7 +851,6 @@ cdef class NCPolynomialRing_plural(Ring): sage: P.gen(1) is P.gen(1) False - """ cdef poly *_p cdef ring *_ring = self._ring @@ -887,7 +886,7 @@ cdef class NCPolynomialRing_plural(Ring): INPUT: - ``*gens`` -- list or tuple of generators (or several input arguments) - - ``coerce`` -- bool (default: ``True``); this must be a + - ``coerce`` -- boolean (default: ``True``); this must be a keyword argument. Only set it to ``False`` if you are certain that each generator is already in the ring. - ``side`` -- string (either "left", which is the default, or "twosided") @@ -901,7 +900,7 @@ cdef class NCPolynomialRing_plural(Ring): sage: P.ideal([x + 2*y + 2*z-1, 2*x*y + 2*y*z-y, x^2 + 2*y^2 + 2*z^2-x]) Left Ideal (x + 2*y + 2*z - 1, 2*x*y + 2*y*z - y, x^2 - x + 2*y^2 + 2*z^2) of Noncommutative Multivariate Polynomial Ring in x, y, z over Rational Field, nc-relations: {y*x: -x*y} - sage: P.ideal([x + 2*y + 2*z-1, 2*x*y + 2*y*z-y, x^2 + 2*y^2 + 2*z^2-x], side="twosided") + sage: P.ideal([x + 2*y + 2*z-1, 2*x*y + 2*y*z-y, x^2 + 2*y^2 + 2*z^2-x], side='twosided') Twosided Ideal (x + 2*y + 2*z - 1, 2*x*y + 2*y*z - y, x^2 - x + 2*y^2 + 2*z^2) of Noncommutative Multivariate Polynomial Ring in x, y, z over Rational Field, nc-relations: {y*x: -x*y} """ coerce = kwds.get('coerce', True) @@ -1357,9 +1356,7 @@ cdef class NCPolynomialRing_plural(Ring): - ``t`` -- a monomial - OUTPUT: - - a list of monomials + OUTPUT: list of monomials EXAMPLES:: @@ -1399,7 +1396,6 @@ def unpickle_NCPolynomial_plural(NCPolynomialRing_plural R, d): sage: p = x*y+2*z+4*x*y*z*x sage: loads(dumps(p)) == p # indirect doctest True - """ cdef ring *r = R._ring cdef poly *m @@ -1461,7 +1457,6 @@ cdef class NCPolynomial_plural(RingElement): sage: H. = A.g_algebra({y*x:x*y-z, z*x:x*z+2*x, z*y:y*z-2*y}) sage: loads(dumps(x*y+2*z+4*x*y*z*x)) 4*x^2*y*z + 8*x^2*y - 4*x*z^2 + x*y - 8*x*z + 2*z - """ return unpickle_NCPolynomial_plural, (self._parent, self.dict()) @@ -1541,7 +1536,7 @@ cdef class NCPolynomial_plural(RingElement): cpdef _add_(left, right): """ - Adds left and right. + Add ``left`` and ``right``. EXAMPLES:: @@ -1570,7 +1565,6 @@ cdef class NCPolynomial_plural(RingElement): Defining x, z, y sage: 3/2*x - 1/2*y - 1 # indirect doctest 3/2*x - 1/2*y - 1 - """ cdef ring *_ring = (left._parent)._ring @@ -1643,7 +1637,7 @@ cdef class NCPolynomial_plural(RingElement): cpdef _div_(left, right): """ - Divide left by right + Divide ``left`` by ``right``. EXAMPLES:: @@ -1769,8 +1763,6 @@ cdef class NCPolynomial_plural(RingElement): Field, nc-relations: {z*x: x*z + 2*x, z*y: y*z - 2*y, y*x: x*y - z} sage: sorted(I.std().gens(),key=str) [2*x*y - z - 1, x*z + x, x^2, y*z - y, y^2, z^2 - 1] - - """ cdef ideal *_I cdef NCPolynomialRing_plural parent = self._parent @@ -1896,9 +1888,7 @@ cdef class NCPolynomial_plural(RingElement): self) If x is not specified (or is ``None``), return the total degree, which is the maximum degree of any monomial. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -1926,7 +1916,6 @@ cdef class NCPolynomial_plural(RingElement): -1 sage: P(1).degree(x) 0 - """ cdef ring *r = (self._parent)._ring cdef poly *p = self._poly @@ -2031,14 +2020,12 @@ cdef class NCPolynomial_plural(RingElement): INPUT: - - ``degrees`` -- Can be any of: - - a dictionary of degree restrictions - - a list of degree restrictions (with None in the unrestricted variables) - - a monomial (very fast, but not as flexible) - - OUTPUT: + - ``degrees`` -- can be any of: + - a dictionary of degree restrictions + - a list of degree restrictions (with ``None`` in the unrestricted variables) + - a monomial (very fast, but not as flexible) - element of the parent of this element. + OUTPUT: element of the parent of this element .. NOTE:: @@ -2156,9 +2143,7 @@ cdef class NCPolynomial_plural(RingElement): - ``mon`` -- a monomial - OUTPUT: - - coefficient in base ring + OUTPUT: coefficient in base ring .. SEEALSO:: @@ -2249,7 +2234,7 @@ cdef class NCPolynomial_plural(RingElement): INPUT: - * "copy" -- ignored + - ``copy`` -- ignored EXAMPLES:: @@ -2274,9 +2259,9 @@ cdef class NCPolynomial_plural(RingElement): INPUT: - - ``codomain`` -- The parent where the images live + - ``codomain`` -- the parent where the images live - - ``im_gens`` -- A list or tuple with the images of the generators of this ring. + - ``im_gens`` -- list or tuple with the images of the generators of this ring EXAMPLES:: @@ -2356,8 +2341,8 @@ cdef class NCPolynomial_plural(RingElement): INPUT: - - ``x`` -- a tuple or, in case of a single-variable MPolynomial - ring ``x`` can also be an integer. + - ``x`` -- tuple or, in case of a single-variable MPolynomial + ring ``x`` can also be an integer EXAMPLES:: @@ -2374,7 +2359,7 @@ cdef class NCPolynomial_plural(RingElement): sage: f[0,0,0] 0 - sage: R. = PolynomialRing(GF(7), implementation="singular"); R + sage: R. = PolynomialRing(GF(7), implementation='singular'); R Multivariate Polynomial Ring in x over Finite Field of size 7 sage: f = 5*x^2 + 3; f -2*x^2 + 3 @@ -2420,9 +2405,8 @@ cdef class NCPolynomial_plural(RingElement): INPUT: - - ``as_ETuples`` -- (default: ``True``) if ``True`` returns the result as an list of ETuples - otherwise returns a list of tuples - + - ``as_ETuples`` -- boolean (default: ``True``); if ``True`` returns + the result as an list of ETuples, otherwise returns a list of tuples EXAMPLES:: @@ -2529,7 +2513,7 @@ cdef class NCPolynomial_plural(RingElement): def monomials(self): """ - Return the list of monomials in ``self`` + Return the list of monomials in ``self``. The returned list is decreasingly ordered by the term ordering of ``self.parent()``. @@ -2867,7 +2851,8 @@ cdef inline NCPolynomial_plural new_NCP(NCPolynomialRing_plural parent, cpdef MPolynomialRing_libsingular new_CRing(RingWrap rw, base_ring): """ - Construct MPolynomialRing_libsingular from ringWrap, assuming the ground field to be base_ring + Construct ``MPolynomialRing_libsingular`` from ``RingWrap``, assuming the + ground field to be ``base_ring``. EXAMPLES:: @@ -2937,7 +2922,8 @@ cpdef MPolynomialRing_libsingular new_CRing(RingWrap rw, base_ring): cpdef NCPolynomialRing_plural new_NRing(RingWrap rw, base_ring): """ - Construct NCPolynomialRing_plural from ringWrap, assuming the ground field to be base_ring + Construct ``NCPolynomialRing_plural`` from ``RingWrap``, assuming the + ground field to be ``base_ring``. EXAMPLES:: @@ -3005,9 +2991,11 @@ cpdef NCPolynomialRing_plural new_NRing(RingWrap rw, base_ring): def new_Ring(RingWrap rw, base_ring): """ - Constructs a Sage ring out of low level RingWrap, which wraps a pointer to a Singular ring. + Construct a Sage ring out of low level ``RingWrap``, which wraps a pointer + to a Singular ring. - The constructed ring is either commutative or noncommutative depending on the Singular ring. + The constructed ring is either commutative or noncommutative depending on + the Singular ring. EXAMPLES:: @@ -3049,7 +3037,6 @@ def new_Ring(RingWrap rw, base_ring): sage: from sage.rings.polynomial.plural import new_Ring sage: R = new_Ring(W, H.base_ring()); R Noncommutative Multivariate Polynomial Ring in x, y, z over Rational Field, nc-relations: {y*x: x*y - 1} - """ # import warnings # warnings.warn("This is a hack. Please, use it on your own risk...") @@ -3060,15 +3047,15 @@ def new_Ring(RingWrap rw, base_ring): def SCA(base_ring, names, alt_vars, order='degrevlex'): """ - Return a free graded-commutative algebra + Return a free graded-commutative algebra. This is also known as a free super-commutative algebra. INPUT: - ``base_ring`` -- the ground field - - ``names`` -- a list of variable names - - ``alt_vars`` -- a list of indices of to be anti-commutative variables (odd variables) + - ``names`` -- list of variable names + - ``alt_vars`` -- list of indices of to be anti-commutative variables (odd variables) - ``order`` -- ordering to be used for the constructed algebra EXAMPLES:: @@ -3124,7 +3111,7 @@ def ExteriorAlgebra(base_ring, names,order='degrevlex'): INPUT: - ``base_ring`` -- the ground ring - - ``names`` -- a list of variable names + - ``names`` -- list of variable names EXAMPLES:: diff --git a/src/sage/rings/polynomial/polydict.pyx b/src/sage/rings/polynomial/polydict.pyx index e579052df95..0fbc3fb3860 100644 --- a/src/sage/rings/polynomial/polydict.pyx +++ b/src/sage/rings/polynomial/polydict.pyx @@ -71,7 +71,8 @@ cpdef int gen_index(PolyDict x) noexcept: cpdef ETuple monomial_exponent(PolyDict p): r""" - Return the unique exponent of ``p`` if it is a monomial or raise a ``ValueError``. + Return the unique exponent of ``p`` if it is a monomial or raise a + :exc:`ValueError`. EXAMPLES:: @@ -110,10 +111,10 @@ cdef class PolyDict: """ INPUT: - - ``pdict`` -- dict or list, which represents a multi-variable + - ``pdict`` -- dictionary or list, which represents a multi-variable polynomial with the distribute representation (a copy is made) - - ``zero`` -- deprecated + - ``zero`` -- deprecated - ``remove_zero`` -- deprecated @@ -122,7 +123,7 @@ cdef class PolyDict: - ``force_etuples`` -- deprecated - ``check`` -- if set to ``False`` then assumes that the exponents are - all valid ``ETuple``; in that case the construction is a bit faster. + all valid ``ETuple``; in that case the construction is a bit faster EXAMPLES:: @@ -200,7 +201,7 @@ cdef class PolyDict: INPUT: - - ``zero_test`` -- optional function that performs test to zero of a coefficient + - ``zero_test`` -- (optional) function that performs test to zero of a coefficient EXAMPLES:: @@ -275,7 +276,7 @@ cdef class PolyDict: def coerce_coefficients(self, A): r""" - Coerce the coefficients in the parent ``A`` + Coerce the coefficients in the parent ``A``. EXAMPLES:: @@ -612,7 +613,7 @@ cdef class PolyDict: INPUT: - - ``degrees`` -- a list of degree restrictions; list elements are None + - ``degrees`` -- list of degree restrictions; list elements are ``None`` if the variable in that position should be unrestricted EXAMPLES:: @@ -758,8 +759,8 @@ cdef class PolyDict: INPUT: - ``vars`` -- list - - ``atomic_exponents`` -- bool (default: ``True``) - - ``atomic_coefficients`` -- bool (default: ``True``) + - ``atomic_exponents`` -- boolean (default: ``True``) + - ``atomic_coefficients`` -- boolean (default: ``True``) EXAMPLES:: @@ -851,8 +852,8 @@ cdef class PolyDict: INPUT: - ``vars`` -- list - - ``atomic_exponents`` -- bool (default: ``True``) - - ``atomic_coefficients`` -- bool (default: ``True``) + - ``atomic_exponents`` -- boolean (default: ``True``) + - ``atomic_coefficients`` -- boolean (default: ``True``) EXAMPLES:: @@ -952,7 +953,7 @@ cdef class PolyDict: def __iadd__(PolyDict self, PolyDict other): r""" - Inplace addition + Inplace addition. EXAMPLES:: @@ -1026,7 +1027,7 @@ cdef class PolyDict: The algorithm do not test whether a product of coefficients is zero or whether a final coefficient is zero because there is no reliable way - to do so in general (eg power series ring or p-adic rings). + to do so in general (eg power series ring or `p`-adic rings). EXAMPLES: @@ -1137,7 +1138,6 @@ cdef class PolyDict: sage: f = PolyDict({(2,3): 2, (1,2): 3, (2,1): 4}) sage: f.term_lmult(ETuple((1, 2)), -2) PolyDict with representation {(2, 4): -6, (3, 3): -8, (3, 5): -4} - """ cdef dict v = {} for e, c in self.__repn.items(): @@ -1167,7 +1167,6 @@ cdef class PolyDict: sage: f = PolyDict({(2, 3): 2, (1, 2): 3, (2, 1): 4}) sage: f.term_rmult(ETuple((1, 2)), -2) PolyDict with representation {(2, 4): -6, (3, 3): -8, (3, 5): -4} - """ cdef dict v = {} for e, c in self.__repn.items(): @@ -1216,7 +1215,7 @@ cdef class PolyDict: def derivative(self, PolyDict x): r""" - Return the derivative of ``self`` with respect to ``x`` + Return the derivative of ``self`` with respect to ``x``. EXAMPLES:: @@ -1263,7 +1262,7 @@ cdef class PolyDict: def integral(self, PolyDict x): r""" - Return the integral of ``self`` with respect to ``x`` + Return the integral of ``self`` with respect to ``x``. EXAMPLES:: @@ -1318,7 +1317,7 @@ cdef class PolyDict: def min_exp(self): """ - Returns an ETuple containing the minimum exponents appearing. If + Return an ETuple containing the minimum exponents appearing. If there are no terms at all in the PolyDict, it returns None. The nvars parameter is necessary because a PolyDict doesn't know it @@ -1344,7 +1343,7 @@ cdef class PolyDict: def max_exp(self): """ - Returns an ETuple containing the maximum exponents appearing. If + Return an ETuple containing the maximum exponents appearing. If there are no terms at all in the PolyDict, it returns None. The nvars parameter is necessary because a PolyDict doesn't know it @@ -1432,8 +1431,8 @@ cdef class ETuple: """ cdef ETuple _new(self): """ - Quickly creates a new initialized ETuple with the - same length as self. + Quickly create a new initialized ETuple with the + same length as ``self``. """ cdef type t = type(self) cdef ETuple x = t.__new__(t) @@ -1511,7 +1510,7 @@ cdef class ETuple: def __bool__(self): r""" - Return whether self is nonzero. + Return whether ``self`` is nonzero. TESTS:: @@ -1529,9 +1528,9 @@ cdef class ETuple: def __add__(ETuple self, ETuple other): """ - x.__add__(n) <==> x+n + ``x.__add__(n) <==> x+n``. - concatenates two ETuples + Concatenate two ETuples. EXAMPLES:: @@ -1554,7 +1553,7 @@ cdef class ETuple: def __mul__(ETuple self, factor): """ - x.__mul__(n) <==> x*n + ``x.__mul__(n) <==> x*n``. EXAMPLES:: @@ -1665,7 +1664,7 @@ cdef class ETuple: def __len__(self): """ - x.__len__() <==> len(x) + ``x.__len__() <==> len(x)``. EXAMPLES:: @@ -1678,7 +1677,7 @@ cdef class ETuple: def __contains__(self, elem): """ - x.__contains__(n) <==> n in x + ``x.__contains__(n) <==> n in x``. EXAMPLES:: @@ -1780,7 +1779,7 @@ cdef class ETuple: def __iter__(self): """ - x.__iter__() <==> iter(x) + ``x.__iter__() <==> iter(x)``. TESTS:: @@ -1885,7 +1884,7 @@ cdef class ETuple: INPUT: - - ``w`` -- tuple of non-negative integers + - ``w`` -- tuple of nonnegative integers EXAMPLES:: @@ -1917,7 +1916,7 @@ cdef class ETuple: """ Return the degree of ``self`` divided by its gcd with ``other``. - It amounts to counting the non-negative entries of + It amounts to counting the nonnegative entries of ``self.esub(other)``. """ cdef size_t ind1 = 0 # both ind1 and ind2 will be increased in double steps. @@ -1956,7 +1955,7 @@ cdef class ETuple: INPUT: - ``other`` -- an :class:`~sage.rings.polynomial.polydict.ETuple` - - ``w`` -- tuple of non-negative integers. + - ``w`` -- tuple of nonnegative integers """ if len(w) != self._length: raise ValueError('w must be of the same length as the ETuple') @@ -2218,7 +2217,7 @@ cdef class ETuple: cdef size_t ind cdef ETuple result = self._new() if factor == 0: - result._nonzero = 0 # all zero, no non-zero entries! + result._nonzero = 0 # all zero, no nonzero entries! result._data = sig_malloc(sizeof(int) * result._nonzero * 2) else: result._nonzero = self._nonzero @@ -2433,7 +2432,7 @@ cdef class ETuple: """ Return division of ``self`` by the variable with index ``pos``. - If ``self[pos] == 0`` then a ``ArithmeticError`` is raised. Otherwise, + If ``self[pos] == 0`` then a :exc:`ArithmeticError` is raised. Otherwise, an :class:`~sage.rings.polynomial.polydict.ETuple` is returned that is zero in position ``pos`` and coincides with ``self`` in the other positions. @@ -2558,11 +2557,11 @@ cdef class ETuple: cpdef list nonzero_positions(self, bint sort=False): """ - Return the positions of non-zero exponents in the tuple. + Return the positions of nonzero exponents in the tuple. INPUT: - - ``sort`` -- (default: ``False``) if ``True`` a sorted list is + - ``sort`` -- boolean (default: ``False``); if ``True`` a sorted list is returned; if ``False`` an unsorted list is returned EXAMPLES:: @@ -2577,8 +2576,8 @@ cdef class ETuple: cpdef common_nonzero_positions(self, ETuple other, bint sort=False): """ - Returns an optionally sorted list of non zero positions either - in self or other, i.e. the only positions that need to be + Return an optionally sorted list of nonzero positions either + in ``self`` or other, i.e. the only positions that need to be considered for any vector operation. EXAMPLES:: @@ -2600,12 +2599,12 @@ cdef class ETuple: cpdef list nonzero_values(self, bint sort=True): """ - Return the non-zero values of the tuple. + Return the nonzero values of the tuple. INPUT: - - ``sort`` -- (default: ``True``) if ``True`` the values are sorted - by their indices; otherwise the values are returned unsorted + - ``sort`` -- boolean (default: ``True``); if ``True`` the values are + sorted by their indices. Otherwise the values are returned unsorted. EXAMPLES:: diff --git a/src/sage/rings/polynomial/polynomial_compiled.pyx b/src/sage/rings/polynomial/polynomial_compiled.pyx index f17122814de..dbdd9d55b82 100644 --- a/src/sage/rings/polynomial/polynomial_compiled.pyx +++ b/src/sage/rings/polynomial/polynomial_compiled.pyx @@ -20,8 +20,8 @@ from sage.misc.binary_tree cimport BinaryTree cdef class CompiledPolynomialFunction: """ - Builds a reasonably optimized directed acyclic graph representation - for a given polynomial. A CompiledPolynomialFunction is callable from + Build a reasonably optimized directed acyclic graph representation + for a given polynomial. A ``CompiledPolynomialFunction`` is callable from python, though it is a little faster to call the eval function from pyrex. @@ -95,7 +95,6 @@ cdef class CompiledPolynomialFunction: forthcoming) requires the gaps to considered in order, and adds additional dummies as it goes. Hence, the gaps are put into a binary tree. - """ cdef generic_pd max_gap, dag cdef BinaryTree gaps diff --git a/src/sage/rings/polynomial/polynomial_complex_arb.pyx b/src/sage/rings/polynomial/polynomial_complex_arb.pyx index 8c96385c1e2..7f4fc81a4e5 100644 --- a/src/sage/rings/polynomial/polynomial_complex_arb.pyx +++ b/src/sage/rings/polynomial/polynomial_complex_arb.pyx @@ -383,7 +383,7 @@ cdef class Polynomial_complex_arb(Polynomial): r""" Compute the Euclidean division of this ball polynomial by ``divisor``. - Raises a ``ZeroDivisionError`` when the divisor is zero or its leading + Raises a :exc:`ZeroDivisionError` when the divisor is zero or its leading coefficient contains zero. Returns a pair (quotient, remainder) otherwise. @@ -594,7 +594,7 @@ cdef class Polynomial_complex_arb(Polynomial): INPUT: - - ``expo`` -- non-negative integer exponent + - ``expo`` -- nonnegative integer exponent - ``n`` -- truncation order EXAMPLES:: diff --git a/src/sage/rings/polynomial/polynomial_element.pyx b/src/sage/rings/polynomial/polynomial_element.pyx index 09ad79cb199..f349f5eacfd 100644 --- a/src/sage/rings/polynomial/polynomial_element.pyx +++ b/src/sage/rings/polynomial/polynomial_element.pyx @@ -118,9 +118,9 @@ from sage.arith.functions import lcm from sage.rings.polynomial import polynomial_fateman -from sage.rings.ideal import is_Ideal -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing +from sage.rings.ideal import Ideal_generic +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.polynomial.multi_polynomial cimport MPolynomial from sage.rings.polynomial.polynomial_quotient_ring_element import PolynomialQuotientRingElement from sage.misc.cachefunc import cached_function @@ -139,7 +139,7 @@ cpdef is_Polynomial(f): INPUT: - - ``f`` -- an object + - ``f`` -- an object EXAMPLES:: @@ -331,15 +331,13 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``xmin`` -- float + - ``xmin`` -- float - - ``xmax`` -- float + - ``xmax`` -- float - - ``*args, **kwds`` -- passed to either plot or - point + - ``*args, **kwds`` -- passed to either plot or point - - OUTPUT: returns a graphic object. + OUTPUT: a graphic object EXAMPLES:: @@ -369,7 +367,7 @@ cdef class Polynomial(CommutativePolynomial): cpdef _lmul_(self, Element left): """ - Multiply self on the left by a scalar. + Multiply ``self`` on the left by a scalar. EXAMPLES:: @@ -389,7 +387,7 @@ cdef class Polynomial(CommutativePolynomial): cpdef _rmul_(self, Element right): """ - Multiply self on the right by a scalar. + Multiply ``self`` on the right by a scalar. EXAMPLES:: @@ -453,11 +451,9 @@ cdef class Polynomial(CommutativePolynomial): the polynomial. The **first** positional argument is substituted for the polynomial's indeterminate. Remaining arguments, if any, are used **from left to right** to evaluate the coefficients. - - ``**kwds`` -- variable name-value pairs. - - OUTPUT: + - ``**kwds`` -- variable name-value pairs - The value of the polynomial at the point specified by the arguments. + OUTPUT: the value of the polynomial at the point specified by the arguments ALGORITHM: @@ -1010,7 +1006,7 @@ cdef class Polynomial(CommutativePolynomial): cpdef _richcmp_(self, other, int op): r""" - Compare the two polynomials self and other. + Compare the two polynomials ``self`` and ``other``. We order polynomials first by degree (but treating 0 as having degree 0), then in dictionary order starting with the @@ -1268,7 +1264,6 @@ cdef class Polynomial(CommutativePolynomial): Traceback (most recent call last): ... TypeError: unhashable type: 'sage.rings.padics.qadic_flint_CR.qAdicCappedRelativeElement' - """ cdef long result = 0 # store it in a c-int and just let the overflowing additions wrap cdef long result_mon @@ -1553,8 +1548,8 @@ cdef class Polynomial(CommutativePolynomial): def inverse_mod(a, m): """ - Invert the polynomial ``a`` with respect to ``m``, or raise a :class:`ValueError` - if no such inverse exists. + Invert the polynomial ``a`` with respect to ``m``, or raise a + :exc:`ValueError` if no such inverse exists. The parameter ``m`` may be either a single polynomial or an ideal (for consistency with :meth:`inverse_mod` in other rings). @@ -1616,8 +1611,8 @@ cdef class Polynomial(CommutativePolynomial): - Robert Bradshaw (2007-05-31) """ - from sage.rings.ideal import is_Ideal - if is_Ideal(m): + from sage.rings.ideal import Ideal_generic + if isinstance(m, Ideal_generic): v = m.gens_reduced() if len(v) > 1: raise NotImplementedError("Don't know how to invert modulo non-principal ideal %s" % m) @@ -1883,7 +1878,7 @@ cdef class Polynomial(CommutativePolynomial): def multiplication_trunc(self, other, n): r""" - Truncated multiplication + Truncated multiplication. EXAMPLES:: @@ -1955,7 +1950,6 @@ cdef class Polynomial(CommutativePolynomial): sage: f = QQbar['x'](1) # needs sage.rings.number_field sage: f.squarefree_decomposition() # needs sage.rings.number_field 1 - """ if self.degree() < 0: raise ValueError("square-free decomposition not defined for zero polynomial") @@ -1973,15 +1967,14 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``root`` -- whether or not to also return a square - root (default: ``False``) + - ``root`` -- whether or not to also return a square + root (default: ``False``) OUTPUT: - - ``bool`` -- whether or not a square + - boolean; whether or not a square - - ``root`` -- (optional) an actual square root if - found, and ``None`` otherwise. + - (optional) an actual square root if found, and ``None`` otherwise EXAMPLES:: @@ -2048,7 +2041,7 @@ cdef class Polynomial(CommutativePolynomial): def _distinct_degree_factorisation_squarefree(self): """ Helper function for any_irreducible_factor which computes - the distinct degree factorisation of `self`. + the distinct degree factorisation of ``self``. Creates an iterator for all valid degrees `d`, and returns tuples of the form `(a_d, d)` for a polynomial `a_d` the @@ -2211,11 +2204,11 @@ cdef class Polynomial(CommutativePolynomial): def _any_irreducible_factor_squarefree(self, degree=None, ext_degree=None): """ Helper function for :meth:`any_irreducible_factor` which computes - an irreducible factor from self, assuming the input is + an irreducible factor from ``self``, assuming the input is squarefree. Does this by first computing the distinct degree factorisations - of self and then finds a factor with Cantor-Zassenhaus + of ``self`` and then finds a factor with Cantor-Zassenhaus splitting. If ``degree`` is not ``None``, then only irreducible factors of degree @@ -2287,17 +2280,17 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``degree`` (None or positive integer) -- (default: ``None``). + - ``degree`` -- ``None`` or positive integer (default: ``None``). Used for polynomials over finite fields. If ``None``, returns the the first factor found (usually the smallest). Otherwise, attempts to return an irreducible factor of ``self`` of chosen degree ``degree``. - - ``assume_squarefree`` (boolean) -- (default: ``False``). + - ``assume_squarefree`` -- boolean (default: ``False``); Used for polynomials over finite fields. If ``True``, this polynomial is assumed to be squarefree. - - ``assume_equal_deg`` (boolean) -- (default: ``False``). + - ``assume_equal_deg`` -- boolean (default: ``False``); Used for polynomials over finite fields. If ``True``, this polynomial is assumed to be the product of irreducible polynomials of degree equal to ``degree``. @@ -2330,7 +2323,7 @@ cdef class Polynomial(CommutativePolynomial): x^3 + 7*x + 161 If we ask for an irreducible factor which does not exist, the function - will throw a ``ValueError``:: + will throw a :exc:`ValueError`:: sage: # needs sage.rings.finite_rings sage: F = GF(163) @@ -2400,7 +2393,7 @@ cdef class Polynomial(CommutativePolynomial): # For finite fields, we find irreducible factors in the following three steps: # - # 1. Compute the squarefree decomposition of the polynomial `self` + # 1. Compute the squarefree decomposition of the polynomial ``self`` # 2. For each squarefree polynomial find the distinct degree `d` # factorisation, F, which is the product of degree `d` polynomials # dividing the squarefree polynomial @@ -2446,21 +2439,21 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``ring`` -- The ring in which a root is sought. By default - this is the coefficient ring. + - ``ring`` -- the ring in which a root is sought; by default + this is the coefficient ring - - ``degree`` (None or nonzero integer) -- Used for polynomials + - ``degree`` -- ``None`` or nonzero integer; used for polynomials over finite fields. Return a root of degree ``abs(degree)`` over the ground field. If negative, also assumes that all factors of this polynomial are of degree - ``abs(degree)``. If None, returns a root of minimal degree + ``abs(degree)``. If ``None``, returns a root of minimal degree contained within the given ring. - - ``assume_squarefree`` (bool) -- Used for polynomials over + - ``assume_squarefree`` -- boolean; used for polynomials over finite fields. If ``True``, this polynomial is assumed to be squarefree. - - ``assume_equal_deg`` (bool) -- Used for polynomials over + - ``assume_equal_deg`` -- boolean; used for polynomials over finite fields. If ``True``, all factors of this polynomial are assumed to have degree ``degree``. Note that ``degree`` must be set. @@ -2622,7 +2615,7 @@ cdef class Polynomial(CommutativePolynomial): raise ValueError(f"no root of polynomial {self} can be computed over the ring {ring}") # When d != 1 we then find the smallest extension # TODO: What we should do here is compute some minimal - # extension F_ext = self.base_ring().extension(d, names="a") and find a + # extension F_ext = self.base_ring().extension(d, names='a') and find a # root here and then coerce this root into the parent ring. This means we # would work with the smallest possible extension. # However, if we have some element of GF(p^k) and we try and coerce this to @@ -2685,12 +2678,12 @@ cdef class Polynomial(CommutativePolynomial): # new ring? if ring is None: # TODO: a faster option would be to create an extension with `f` - # as F_ext = self.base_ring().extension(f, names="a") + # as F_ext = self.base_ring().extension(f, names='a') # however this returns a quotient ring rather than a # FiniteField type if the base field is a non-prime field, # so this slower option is chosen to ensure the root is # over explicitly a FiniteField type. - ring = self.base_ring().extension(degree, names="a") + ring = self.base_ring().extension(degree, names='a') # TODO: The proper thing to do here would be to call # return f.change_ring(ring).any_root() @@ -2959,13 +2952,13 @@ cdef class Polynomial(CommutativePolynomial): def power_trunc(self, n, prec): r""" - Truncated ``n``-th power of this polynomial up to precision ``prec`` + Truncated ``n``-th power of this polynomial up to precision ``prec``. INPUT: - - ``n`` -- (non-negative integer) power to be taken + - ``n`` -- nonnegative integer; power to be taken - - ``prec`` -- (integer) the precision + - ``prec`` -- integer; the precision EXAMPLES:: @@ -3006,7 +2999,7 @@ cdef class Polynomial(CommutativePolynomial): sage: x.power_trunc(-1, 10) Traceback (most recent call last): ... - ValueError: n must be a non-negative integer + ValueError: n must be a nonnegative integer sage: R. = QQ['x'] sage: y.power_trunc(2**32 - 1, 2) 0 @@ -3020,16 +3013,16 @@ cdef class Polynomial(CommutativePolynomial): cpdef Polynomial _power_trunc(self, unsigned long n, long prec): r""" - Truncated ``n``-th power of this polynomial up to precision ``prec`` + Truncated ``n``-th power of this polynomial up to precision ``prec``. This method is overridden for certain subclasses when a library function is available. INPUT: - - ``n`` -- (non-negative integer) power to be taken + - ``n`` -- nonnegative integer; power to be taken - - ``prec`` -- (integer) the precision + - ``prec`` -- integer; the precision TESTS:: @@ -3061,7 +3054,7 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``name`` -- None or a string; used for printing the variable. + - ``name`` -- ``None`` or a string; used for printing the variable EXAMPLES:: @@ -3284,16 +3277,16 @@ cdef class Polynomial(CommutativePolynomial): def __setitem__(self, n, value): """ - Set the n-th coefficient of this polynomial. This always raises an - IndexError, since in Sage polynomials are immutable. + Set the `n`-th coefficient of this polynomial. This always raises an + :exc:`IndexError`, since in Sage polynomials are immutable. INPUT: - - ``n`` -- an integer + - ``n`` -- integer - - ``value`` -- value to set the n-th coefficient to + - ``value`` -- value to set the `n`-th coefficient to - OUTPUT: an :class:`IndexError` is always raised. + OUTPUT: an :exc:`IndexError` is always raised EXAMPLES:: @@ -3484,13 +3477,11 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``self`` -- Polynomial + - ``self`` -- polynomial - - ``right`` -- Polynomial (over same base ring as - self) + - ``right`` -- polynomial (over same base ring as ``self``) - - OUTPUT: Polynomial - The product self\*right. + OUTPUT: polynomial; the product ``self * right`` ALGORITHM: Based on a paper by R. Fateman @@ -3515,7 +3506,6 @@ cdef class Polynomial(CommutativePolynomial): Advantages: - - Faster than Karatsuba over `\QQ` and `\ZZ` (but much slower still than calling NTL's optimized C++ implementation, which is the default over @@ -3523,17 +3513,14 @@ cdef class Polynomial(CommutativePolynomial): - Potentially less complicated. - Drawbacks: + - Slower over R when the degree of both of polynomials is less + than 250 (roughly). - - Slower over R when the degree of both of polynomials is less - than 250 (roughly). - - - Over R, results may not be as accurate as the Karatsuba case. - This is because we represent coefficients of polynomials over R as - fractions, then convert them back to floating-point numbers. - + - Over R, results may not be as accurate as the Karatsuba case. + This is because we represent coefficients of polynomials over R as + fractions, then convert them back to floating-point numbers. AUTHORS: @@ -3553,16 +3540,14 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``self`` -- Polynomial - - ``right`` -- Polynomial (over same base ring as ``self``) - - ``K_threshold`` -- (optional) Integer. A threshold to fall back to - schoolbook algorithm. In the recursion, if one of the polynomials - is of degree less that K_threshold then the classic quadratic - polynomial is used. + - ``self`` -- polynomial + - ``right`` -- polynomial (over same base ring as ``self``) + - ``K_threshold`` -- (optional) Integer. A threshold to fall back to + schoolbook algorithm. In the recursion, if one of the polynomials + is of degree less that K_threshold then the classic quadratic + polynomial is used. - OUTPUT: - - The product ``self * right``. + OUTPUT: the product ``self * right`` ALGORITHM: @@ -3591,7 +3576,7 @@ cdef class Polynomial(CommutativePolynomial): to recursively compute `fg`. - If `self` is a polynomial of degree n and `right` is a polynomial of + If ``self`` is a polynomial of degree n and `right` is a polynomial of degree m with n < m, then we interpret `right` as .. MATH:: @@ -3599,7 +3584,7 @@ cdef class Polynomial(CommutativePolynomial): g0 + g1 * x^n + g2 * x^{2n} + ... + gq * x^{nq} where `gi` are polynomials of degree <= n. We then compute each product - `gi*right` with Karatsuba multiplication and reconstruct `self*right` + ``gi*right`` with Karatsuba multiplication and reconstruct ``self*right`` from the partial products. The theoretical complexity for multiplying two polynomials of the same @@ -3800,7 +3785,7 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``R`` -- a ring or morphism. + - ``R`` -- a ring or morphism EXAMPLES:: @@ -3977,7 +3962,6 @@ cdef class Polynomial(CommutativePolynomial): Traceback (most recent call last): ... NotImplementedError - """ from sage.categories.fields import Fields if self.base_ring() in Fields(): @@ -4075,7 +4059,7 @@ cdef class Polynomial(CommutativePolynomial): def numerator(self): """ - Return a numerator of ``self``, computed as ``self * self.denominator()`` + Return a numerator of ``self``, computed as ``self * self.denominator()``. Note that some subclasses may implement its own numerator function. For example, see @@ -5157,10 +5141,10 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``names`` -- (default: ``None``) a variable name for the splitting field. + - ``names`` -- (default: ``None``) a variable name for the splitting field - - ``map`` -- (default: ``False``) also return an embedding of - ``self`` into the resulting field. + - ``map`` -- boolean (default: ``False``); also return an embedding of + ``self`` into the resulting field - ``kwds`` -- additional keywords depending on the type. Currently, only number fields are implemented. See @@ -5303,7 +5287,6 @@ cdef class Polynomial(CommutativePolynomial): Traceback (most recent call last): ... TypeError: You must specify the name of the generator. - """ if names is None: raise TypeError("You must specify the name of the generator.") @@ -5546,13 +5529,12 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``n`` (default: ``None``) -- if provided, should equal + - ``n`` -- (default: ``None``) if provided, should equal `q-1` where ``self.parent()`` is the field with `q` - elements; otherwise it will be computed. + elements; otherwise it will be computed - - ``n_prime_divs`` (default: ``None``) -- if provided, should - be a list of the prime divisors of `n`; otherwise it - will be computed. + - ``n_prime_divs`` -- (default: ``None``) if provided, should be a list + of the prime divisors of `n`; otherwise it will be computed .. NOTE:: @@ -5673,7 +5655,7 @@ cdef class Polynomial(CommutativePolynomial): n = q ** self.degree() - 1 y = self._parent.quo(self).gen() from sage.groups.generic import order_from_multiple - return n == order_from_multiple(y, n, n_prime_divs, operation="*") + return n == order_from_multiple(y, n, n_prime_divs, operation='*') elif isinstance(R, sage.rings.abc.Order): K = R.number_field() return K.fractional_ideal(self.coefficients()) == K.fractional_ideal(1) @@ -5684,12 +5666,7 @@ cdef class Polynomial(CommutativePolynomial): """ Return ``True`` if this is a constant polynomial. - OUTPUT: - - - - ``bool`` -- ``True`` if and only if this polynomial is - constant - + OUTPUT: boolean; ``True`` if and only if this polynomial is constant EXAMPLES:: @@ -5859,9 +5836,9 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``right`` -- a polynomial in the same ring as ``self``. - - ``variable`` -- optional, included for compatibility with the multivariate - case only. The variable of the polynomials. + - ``right`` -- a polynomial in the same ring as ``self`` + - ``variable`` -- (optional) included for compatibility with the + multivariate case only; the variable of the polynomials EXAMPLES:: @@ -6051,7 +6028,7 @@ cdef class Polynomial(CommutativePolynomial): def is_monic(self): """ - Returns ``True`` if this polynomial is monic. The zero polynomial is by + Return ``True`` if this polynomial is monic. The zero polynomial is by definition not monic. EXAMPLES:: @@ -6318,7 +6295,7 @@ cdef class Polynomial(CommutativePolynomial): r""" Return the coefficients of the monomials appearing in ``self``. - If ``sparse=True`` (the default), it returns only the non-zero coefficients. + If ``sparse=True`` (the default), it returns only the nonzero coefficients. Otherwise, it returns the same value as ``self.list()``. (In this case, it may be slightly faster to invoke ``self.list()`` directly.) In either case, the coefficients are ordered by increasing degree. @@ -6348,9 +6325,9 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -6430,12 +6407,12 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -6480,12 +6457,12 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default :class:`RealField` precision). + default :class:`RealField` precision) - OUTPUT: a real number. + OUTPUT: a real number EXAMPLES:: @@ -6598,18 +6575,13 @@ cdef class Polynomial(CommutativePolynomial): def padded_list(self, n=None): """ - Return list of coefficients of ``self`` up to (but not including) - `q^n`. + Return list of coefficients of ``self`` up to (but not including) `q^n`. - Includes 0's in the list on the right so that the list has length - `n`. + Includes 0s in the list on the right so that the list has length `n`. INPUT: - - - ``n`` -- (default: None); if given, an integer that - is at least 0 - + - ``n`` -- (default: ``None``) if given, an integer that is at least 0 EXAMPLES:: @@ -6658,7 +6630,7 @@ cdef class Polynomial(CommutativePolynomial): - ``m`` -- a monomial - OUTPUT: Coefficient in base ring. + OUTPUT: coefficient in base ring EXAMPLES:: @@ -6740,17 +6712,14 @@ cdef class Polynomial(CommutativePolynomial): INPUT: + - ``n`` -- integer; the number of iterations - - ``n`` -- an integer (the number of iterations), + - ``x0`` -- an initial guess `x_0` - - ``x0`` -- an initial guess `x_0`. - - - OUTPUT: A list of numbers hopefully approximating a root of - `f(x)=0`. + OUTPUT: list of numbers hopefully approximating a root of `f(x)=0` If one of the iterates is a critical point of `f`, a - :class:`ZeroDivisionError` exception is raised. + :exc:`ZeroDivisionError` exception is raised. EXAMPLES:: @@ -7039,7 +7008,7 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``name`` -- (default: None) Variable name. If not given, use + - ``name`` -- (default: ``None``) variable name. If not given, use ``self.parent().variable_name()``. This argument is irrelevant for constant polynomials. @@ -7347,7 +7316,7 @@ cdef class Polynomial(CommutativePolynomial): - ``other`` -- a polynomial - OUTPUT: a list of polynomials in the same ring as ``self`` + OUTPUT: list of polynomials in the same ring as ``self`` EXAMPLES:: @@ -7369,7 +7338,6 @@ cdef class Polynomial(CommutativePolynomial): REFERENCES: :wikipedia:`Polynomial_greatest_common_divisor#Subresultants` - """ P, Q = self, other if P.degree() < Q.degree(): @@ -7441,9 +7409,9 @@ cdef class Polynomial(CommutativePolynomial): as this polynomial - ``op`` -- ``operator.OP`` where ``OP=add`` or ``sub`` or ``mul`` or - ``truediv``. + ``truediv`` - - ``algorithm`` -- can be ``"resultant"`` or ``"BFSS"``; + - ``algorithm`` -- can be ``'resultant'`` or ``'BFSS'``; by default the former is used when the polynomials have few nonzero coefficients and small degrees or if the base ring is not `\ZZ` or `\QQ`. Otherwise the latter is used. @@ -7463,15 +7431,15 @@ cdef class Polynomial(CommutativePolynomial): .. TODO:: - - The [BFSS2006]_ algorithm has been implemented here only in the case of - polynomials over rationals. For other rings of zero characteristic - (or if the characteristic is larger than the product of the degrees), - one needs to implement a generic method ``_exp_series``. In the - general case of non-zero characteristic there is an alternative - algorithm in the same paper. + - The [BFSS2006]_ algorithm has been implemented here only in the case of + polynomials over rationals. For other rings of zero characteristic + (or if the characteristic is larger than the product of the degrees), + one needs to implement a generic method ``_exp_series``. In the + general case of nonzero characteristic there is an alternative + algorithm in the same paper. - - The Newton series computation can be done much more efficiently! - See [BFSS2006]_. + - The Newton series computation can be done much more efficiently! + See [BFSS2006]_. EXAMPLES:: @@ -7550,7 +7518,7 @@ cdef class Polynomial(CommutativePolynomial): raise TypeError("p2 must be a polynomial") p1, p2 = coercion_model.canonical_coercion(p1, p2) K = p1.parent() - assert is_PolynomialRing(p1.parent()) + assert isinstance(p1.parent(), PolynomialRing_general) S = K.base_ring() Sf = S.fraction_field() @@ -7654,13 +7622,12 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - `k` -- a non-negative integer + - ``k`` -- nonnegative integer - - ``algorithm`` -- ``None`` (default), ``"resultant"`` or ``"BFSS"``. - See :meth:`.composed_op` + - ``algorithm`` -- ``None`` (default), ``'resultant'``, or ``'BFSS'``; + see :meth:`.composed_op` - - ``monic`` -- ``False`` (default) or ``True``. - See :meth:`.composed_op` + - ``monic`` -- boolean (default: ``False``); see :meth:`.composed_op` OUTPUT: @@ -7722,9 +7689,9 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - `n` -- an integer + - ``n`` -- integer - - ``monic`` -- boolean (default ``False``) + - ``monic`` -- boolean (default: ``False``) if set to ``True``, force the output to be monic EXAMPLES:: @@ -7758,7 +7725,6 @@ cdef class Polynomial(CommutativePolynomial): (-1) * (x - c^3) * (x - b^3) * (x - a^3) sage: f.adams_operator_on_roots(3, monic=True).factor() # needs sage.libs.singular (x - c^3) * (x - b^3) * (x - a^3) - """ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing @@ -7874,7 +7840,7 @@ cdef class Polynomial(CommutativePolynomial): leading coefficient of ``self``, and the roots of ``self`` are `r_1, \ldots, r_n`. - OUTPUT: An element of the base ring of the polynomial ring. + OUTPUT: an element of the base ring of the polynomial ring ALGORITHM: @@ -7984,7 +7950,7 @@ cdef class Polynomial(CommutativePolynomial): return self # return 0 n = self.degree() base_ring = self._parent.base_ring() - if (is_MPolynomialRing(base_ring) or + if (isinstance(base_ring, MPolynomialRing_base) or is_PowerSeriesRing(base_ring)): # It is often cheaper to compute discriminant of simple # multivariate polynomial and substitute the real @@ -8036,7 +8002,7 @@ cdef class Polynomial(CommutativePolynomial): sage: f.reverse(degree=1.5r) Traceback (most recent call last): ... - ValueError: degree argument must be a non-negative integer, got 1.5 + ValueError: degree argument must be a nonnegative integer, got 1.5 sage: f.reverse(0) -3*x @@ -8048,10 +8014,10 @@ cdef class Polynomial(CommutativePolynomial): cdef unsigned long d if degree is not None: if degree < 0: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) d = degree if d != degree: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) if len(v) < degree+1: v.reverse() v = [self.base_ring().zero()]*(degree+1-len(v)) + v @@ -8072,17 +8038,16 @@ cdef class Polynomial(CommutativePolynomial): INPUT: + - ``ring`` -- the ring to find roots in - - ``ring`` -- the ring to find roots in + - ``multiplicities`` -- boolean (default: ``True``); if ``True`` + return list of pairs `(r, n)`, where `r` is the root and `n` is the + multiplicity. If ``False``, just return the unique roots, with no + information about multiplicities. - - ``multiplicities`` -- bool (default: ``True``) if ``True`` - return list of pairs `(r, n)`, where `r` is the root and `n` is the - multiplicity. If ``False``, just return the unique roots, with no - information about multiplicities. - - - ``algorithm`` -- the root-finding algorithm to use. - We attempt to select a reasonable algorithm by default, but this - lets the caller override our choice. + - ``algorithm`` -- the root-finding algorithm to use. + We attempt to select a reasonable algorithm by default, but this + lets the caller override our choice. By default, this finds all the roots that lie in the base ring of @@ -8752,7 +8717,7 @@ cdef class Polynomial(CommutativePolynomial): sage: eq.roots(multiplicities=False) # needs sage.libs.pari [3109038, 17207405] - Test that roots in fixed modulus p-adic fields work (:issue:`17598`):: + Test that roots in fixed modulus `p`-adic fields work (:issue:`17598`):: sage: len(cyclotomic_polynomial(3).roots(ZpFM(739, 566))) # needs sage.rings.padics 2 @@ -9269,7 +9234,6 @@ cdef class Polynomial(CommutativePolynomial): 5 sage: pol.number_of_roots_in_interval(0, 2) 3 - """ pol = self // self.gcd(self.derivative()) # squarefree part if a is None: @@ -9503,9 +9467,9 @@ cdef class Polynomial(CommutativePolynomial): - ``self`` -- polynomial with rational or integer coefficients - - ``return_q`` -- (default ``False``) if ``True``, return a second value `q` - which is the prime power with respect to which this is `q`-Weil, - or 0 if there is no such value. + - ``return_q`` -- (default: ``False``) if ``True``, return a second + value `q` which is the prime power with respect to which this is + `q`-Weil, or 0 if there is no such value EXAMPLES:: @@ -9691,7 +9655,6 @@ cdef class Polynomial(CommutativePolynomial): sage: h1.xgcd(h2) (x*y, 1, 0) sage: del R._xgcd_univariate_polynomial - """ if hasattr(self.base_ring(), '_xgcd_univariate_polynomial'): return self.base_ring()._xgcd_univariate_polynomial(self, other) @@ -9930,7 +9893,7 @@ cdef class Polynomial(CommutativePolynomial): def args(self): """ Return the generator of this polynomial ring, which is the (only) - argument used when calling self. + argument used when calling ``self``. EXAMPLES:: @@ -9988,7 +9951,7 @@ cdef class Polynomial(CommutativePolynomial): _p = self._parent.coerce(p) elif p is infinity.infinity: return -self.degree() - elif is_Ideal(p) and p.ring() is self._parent: # eventually need to handle fractional ideals in the fraction field + elif isinstance(p, Ideal_generic) and p.ring() is self._parent: # eventually need to handle fractional ideals in the fraction field if self._parent.base_ring().is_field(): # common case _p = p.gen() else: @@ -10106,8 +10069,6 @@ cdef class Polynomial(CommutativePolynomial): True sage: x.is_irreducible.cache # needs sage.libs.pari True - - """ if self.is_zero(): return False @@ -10205,7 +10166,7 @@ cdef class Polynomial(CommutativePolynomial): cpdef Polynomial truncate(self, long n): r""" Return the polynomial of degree `< n` which is equivalent - to self modulo `x^n`. + to ``self`` modulo `x^n`. EXAMPLES:: @@ -10342,7 +10303,6 @@ cdef class Polynomial(CommutativePolynomial): sage: (x^2).is_squarefree() True sage: del(QQbar._is_squarefree_univariate_polynomial) - """ B = self._parent.base_ring() if B not in sage.categories.integral_domains.IntegralDomains(): @@ -10366,7 +10326,6 @@ cdef class Polynomial(CommutativePolynomial): False sage: (x*(x+1)).is_squarefree() # indirect doctest # needs sage.rings.number_field True - """ B = self.parent().base_ring() @@ -10413,7 +10372,8 @@ cdef class Polynomial(CommutativePolynomial): sage: radical(12 * x^5) 6*x - If self has a factor of multiplicity divisible by the characteristic (see :issue:`8736`):: + If ``self`` has a factor of multiplicity divisible by the + characteristic (see :issue:`8736`):: sage: P. = GF(2)[] sage: (x^3 + x^2).radical() # needs sage.rings.finite_rings @@ -10468,10 +10428,7 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - - ``p`` -- (positive integer or +infinity) the degree - of the norm - + - ``p`` -- positive integer or +infinity; the degree of the norm EXAMPLES:: @@ -10534,7 +10491,7 @@ cdef class Polynomial(CommutativePolynomial): cpdef long number_of_terms(self) noexcept: """ - Return the number of non-zero coefficients of ``self``. + Return the number of nonzero coefficients of ``self``. Also called weight, Hamming weight or sparsity. @@ -10571,7 +10528,7 @@ cdef class Polynomial(CommutativePolynomial): def map_coefficients(self, f, new_base_ring=None): """ - Return the polynomial obtained by applying ``f`` to the non-zero + Return the polynomial obtained by applying ``f`` to the nonzero coefficients of ``self``. If ``f`` is a :class:`sage.categories.map.Map`, then the resulting @@ -10581,10 +10538,10 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``f`` -- a callable that will be applied to the coefficients of ``self``. + - ``f`` -- a callable that will be applied to the coefficients of ``self`` - - ``new_base_ring`` (optional) -- if given, the resulting polynomial - will be defined over this ring. + - ``new_base_ring`` -- (optional) if given, the resulting polynomial + will be defined over this ring EXAMPLES:: @@ -10634,7 +10591,7 @@ cdef class Polynomial(CommutativePolynomial): R = R.change_ring(f.codomain()) return R({k: f(v) for k, v in self.dict().items()}) - def is_cyclotomic(self, certificate=False, algorithm="pari"): + def is_cyclotomic(self, certificate=False, algorithm='pari'): r""" Test if this polynomial is a cyclotomic polynomial. @@ -10642,7 +10599,7 @@ cdef class Polynomial(CommutativePolynomial): all roots are roots of unity. By default the answer is a boolean. But if ``certificate`` is ``True``, - the result is a non-negative integer: it is ``0`` if ``self`` is not + the result is a nonnegative integer: it is ``0`` if ``self`` is not cyclotomic, and a positive integer ``n`` if ``self`` is the `n`-th cyclotomic polynomial. @@ -10654,10 +10611,10 @@ cdef class Polynomial(CommutativePolynomial): INPUT: - - ``certificate`` -- boolean, default to ``False``. Only works with - ``algorithm`` set to ``"pari"``. + - ``certificate`` -- boolean (default: ``False``); only works with + ``algorithm`` set to ``'pari'`` - - ``algorithm`` -- either ``"pari"`` or ``"sage"`` (default is ``"pari"``) + - ``algorithm`` -- either ``'pari'`` (default) or ``'sage'`` ALGORITHM: @@ -10693,14 +10650,14 @@ cdef class Polynomial(CommutativePolynomial): sage: # needs sage.libs.pari sage: f = x^16 + x^14 - x^10 + x^8 - x^6 + x^2 + 1 - sage: f.is_cyclotomic(algorithm="pari") + sage: f.is_cyclotomic(algorithm='pari') False - sage: f.is_cyclotomic(algorithm="sage") + sage: f.is_cyclotomic(algorithm='sage') False sage: g = x^16 + x^14 - x^10 - x^8 - x^6 + x^2 + 1 - sage: g.is_cyclotomic(algorithm="pari") + sage: g.is_cyclotomic(algorithm='pari') True - sage: g.is_cyclotomic(algorithm="sage") + sage: g.is_cyclotomic(algorithm='sage') True sage: y = polygen(QQ) @@ -10711,7 +10668,7 @@ cdef class Polynomial(CommutativePolynomial): Invalid arguments:: - sage: (x - 3).is_cyclotomic(algorithm="sage", certificate=True) # needs sage.libs.pari + sage: (x - 3).is_cyclotomic(algorithm='sage', certificate=True) # needs sage.libs.pari Traceback (most recent call last): ... ValueError: no implementation of the certificate within Sage @@ -10722,20 +10679,20 @@ cdef class Polynomial(CommutativePolynomial): sage: (z - 1).is_cyclotomic() Traceback (most recent call last): ... - NotImplementedError: not implemented in non-zero characteristic + NotImplementedError: not implemented in nonzero characteristic TESTS:: sage: R = ZZ['x'] sage: for _ in range(20): # needs sage.libs.pari ....: p = R.random_element(degree=randint(10,20)) - ....: ans_pari = p.is_cyclotomic(algorithm="pari") - ....: ans_sage = p.is_cyclotomic(algorithm="sage") + ....: ans_pari = p.is_cyclotomic(algorithm='pari') + ....: ans_sage = p.is_cyclotomic(algorithm='sage') ....: assert ans_pari == ans_sage, "problem with p={}".format(p) sage: for d in range(2, 20): # needs sage.libs.pari ....: p = cyclotomic_polynomial(d) - ....: assert p.is_cyclotomic(algorithm="pari"), "pari problem with p={}".format(p) - ....: assert p.is_cyclotomic(algorithm="sage"), "sage problem with p={}".format(p) + ....: assert p.is_cyclotomic(algorithm='pari'), "pari problem with p={}".format(p) + ....: assert p.is_cyclotomic(algorithm='sage'), "sage problem with p={}".format(p) Test the output type when ``certificate=True``:: @@ -10753,7 +10710,7 @@ cdef class Polynomial(CommutativePolynomial): """ S = self.base_ring() if S.characteristic() != 0: - raise NotImplementedError("not implemented in non-zero characteristic") + raise NotImplementedError("not implemented in nonzero characteristic") if S != ZZ: try: f = self.change_ring(ZZ) @@ -10800,14 +10757,14 @@ cdef class Polynomial(CommutativePolynomial): # second case selfminus = self(-gen) if f1 == selfminus: - if selfminus.leading_coefficient() < 0 and (-selfminus).is_cyclotomic(algorithm="sage"): + if selfminus.leading_coefficient() < 0 and (-selfminus).is_cyclotomic(algorithm='sage'): return True - elif selfminus.is_cyclotomic(algorithm="sage"): + elif selfminus.is_cyclotomic(algorithm='sage'): return True # third case, we need to take a square root ans, ff1 = f1.is_square(True) - return ans and ff1.is_cyclotomic(algorithm="sage") + return ans and ff1.is_cyclotomic(algorithm='sage') def is_cyclotomic_product(self): r""" @@ -10841,10 +10798,10 @@ cdef class Polynomial(CommutativePolynomial): sage: (x - 1).is_cyclotomic_product() Traceback (most recent call last): ... - NotImplementedError: not implemented in non-zero characteristic + NotImplementedError: not implemented in nonzero characteristic """ if self.base_ring().characteristic() != 0: - raise NotImplementedError("not implemented in non-zero characteristic") + raise NotImplementedError("not implemented in nonzero characteristic") if self.base_ring() != ZZ: try: f = self.change_ring(ZZ) @@ -10902,11 +10859,11 @@ cdef class Polynomial(CommutativePolynomial): sage: (x-1).cyclotomic_part() Traceback (most recent call last): ... - NotImplementedError: not implemented in non-zero characteristic + NotImplementedError: not implemented in nonzero characteristic """ S = self.base_ring() if S.characteristic(): - raise NotImplementedError("not implemented in non-zero characteristic") + raise NotImplementedError("not implemented in nonzero characteristic") if not S.is_exact(): raise NotImplementedError("not implemented for inexact base rings") R = self._parent @@ -11063,7 +11020,6 @@ cdef class Polynomial(CommutativePolynomial): sage: f = x^2 + x + 1 sage: f.homogenize(0) 3*x^2 - """ if self.is_homogeneous(): return self @@ -11285,7 +11241,7 @@ cdef class Polynomial(CommutativePolynomial): The method might fail if the exponent ``n`` or the coefficient of lowest degree is not invertible in the base ring. In both cases an - ``ArithmeticError`` is raised. + :exc:`ArithmeticError` is raised. INPUT: @@ -11293,7 +11249,7 @@ cdef class Polynomial(CommutativePolynomial): - ``prec`` -- positive integer; the precision of the result - - ``start`` -- optional; the first term of the result. This + - ``start`` -- (optional) the first term of the result. This is only considered when the valuation is zero, i.e. when the polynomial has a nonzero constant term. @@ -11778,11 +11734,11 @@ cdef list do_karatsuba_different_size(list left, list right, Py_ssize_t K_thresh INPUT: - - `left`: a list representing a polynomial - - `right`: a list representing a polynomial - - `K_threshold`: an Integer, a threshold to pass to the classical - quadratic algorithm. During Karatsuba recursion, if one of the lists - has length <= K_threshold the classical product is used instead. + - ``left`` -- list representing a polynomial + - ``right`` -- list representing a polynomial + - ``K_threshold`` -- an Integer, a threshold to pass to the classical + quadratic algorithm. During Karatsuba recursion, if one of the lists + has length <= K_threshold the classical product is used instead. TESTS: @@ -11858,25 +11814,23 @@ cdef list do_karatsuba(list left, list right, Py_ssize_t K_threshold,Py_ssize_t Core routine for Karatsuba multiplication. This function works for two polynomials of the same degree. - Input: + INPUT: - - left: a list containing a slice representing a polynomial - - right: a list containing the slice representing a polynomial with the - same length as left - - K_threshold: an integer. For lists of length <= K_threshold, the - quadratic polynomial multiplication is used. - - start_l: the index of left where the actual polynomial starts - - start_r: the index of right where the actual polynomial starts - - num_elts: the length of the polynomials. + - ``left`` -- list containing a slice representing a polynomial + - ``right`` -- list containing the slice representing a polynomial with the + same length as ``left`` + - ``K_threshold`` -- integer; for lists of ``length <= K_threshold``, the + quadratic polynomial multiplication is used + - ``start_l`` -- the index of ``left`` where the actual polynomial starts + - ``start_r`` -- the index of ``right`` where the actual polynomial starts + - ``num_elts`` -- the length of the polynomials Thus, the actual polynomials we want to multiply are represented by the - slices: left[ start_l: start_l+num_elts ], right[ right_l: right_l+num_elts ]. + slices: ``left[ start_l: start_l+num_elts ]``, ``right[ right_l: right_l+num_elts ]``. We use this representation in order to avoid creating slices of lists and create smaller lists. - Output: - - - a list representing the product of the polynomials + OUTPUT: list representing the product of the polynomials Doctested indirectly in _mul_karatsuba @@ -12142,7 +12096,7 @@ cdef class Polynomial_generic_dense(Polynomial): sage: class BrokenRational(Rational): ....: def __bool__(self): - ....: raise NotImplementedError("cannot check whether number is non-zero") + ....: raise NotImplementedError("cannot check whether number is nonzero") ....: sage: z = BrokenRational() sage: R. = QQ[] @@ -12150,7 +12104,7 @@ cdef class Polynomial_generic_dense(Polynomial): sage: Polynomial_generic_dense(R, [z]) Traceback (most recent call last): ... - NotImplementedError: cannot check whether number is non-zero + NotImplementedError: cannot check whether number is nonzero """ cdef list x = self._coeffs cdef Py_ssize_t n = len(x) - 1 @@ -12387,7 +12341,6 @@ cdef class Polynomial_generic_dense(Polynomial): sage: type(f.degree()) - """ return smallInteger(len(self._coeffs) - 1) @@ -12441,8 +12394,8 @@ cdef class Polynomial_generic_dense(Polynomial): Return the quotient and remainder of the Euclidean division of ``self`` and ``other``. - Raises a :class:`ZeroDivisionError` if ``other`` is zero. Raises an - :class:`ArithmeticError` if the division is not exact. + Raises a :exc:`ZeroDivisionError` if ``other`` is zero. Raises an + :exc:`ArithmeticError` if the division is not exact. EXAMPLES:: @@ -12545,7 +12498,7 @@ cdef class Polynomial_generic_dense(Polynomial): cpdef Polynomial truncate(self, long n): r""" Return the polynomial of degree `< n` which is equivalent - to self modulo `x^n`. + to ``self`` modulo `x^n`. EXAMPLES:: @@ -12630,13 +12583,13 @@ def universal_discriminant(n): cpdef Polynomial generic_power_trunc(Polynomial p, Integer n, long prec): r""" - Generic truncated power algorithm + Generic truncated power algorithm. INPUT: - ``p`` -- a polynomial - - ``n`` -- an integer (of type :class:`sage.rings.integer.Integer`) + - ``n`` -- integer (of type :class:`sage.rings.integer.Integer`) - ``prec`` -- a precision (should fit into a C ``long``) @@ -12655,7 +12608,7 @@ cpdef Polynomial generic_power_trunc(Polynomial p, Integer n, long prec): ....: assert p.power_trunc(n, prec) == generic_power_trunc(p, n, prec), "p = {} n = {} prec = {}".format(p, n, prec) """ if mpz_sgn(n.value) < 0: - raise ValueError("n must be a non-negative integer") + raise ValueError("n must be a nonnegative integer") elif prec <= 0: return p._parent.zero() @@ -12766,9 +12719,9 @@ cdef class Polynomial_generic_dense_inexact(Polynomial_generic_dense): r""" INPUT: - - ``secure`` -- a boolean (default: ``False``) + - ``secure`` -- boolean (default: ``False``) - OUTPUT: The degree of ``self``. + OUTPUT: the degree of ``self`` If ``secure`` is ``True`` and the degree of this polynomial is not determined (because the leading coefficient is @@ -13105,7 +13058,6 @@ cdef class PolynomialBaseringInjection(Morphism): sage: R.is_subring(S) # indirect doctest True - """ return True @@ -13118,7 +13070,6 @@ cdef class PolynomialBaseringInjection(Morphism): sage: R. = ZZ[] sage: R.coerce_map_from(ZZ).is_surjective() False - """ return False diff --git a/src/sage/rings/polynomial/polynomial_element_generic.py b/src/sage/rings/polynomial/polynomial_element_generic.py index 370d8f22fc6..3e8a6b45ee1 100644 --- a/src/sage/rings/polynomial/polynomial_element_generic.py +++ b/src/sage/rings/polynomial/polynomial_element_generic.py @@ -80,7 +80,6 @@ class Polynomial_generic_sparse(Polynomial): s + Tbar sage: (s + T)**2 s^2 + 2*Tbar*s + 4 - """ def __init__(self, parent, x=None, check=True, is_gen=False, construct=False): """ @@ -569,7 +568,6 @@ def __floordiv__(self, right): -3/2 sage: f.quo_rem(1+2*x) (4*x^2 + 4*x + 5/2, -3/2) - """ P = self.parent() if P is parent(right): @@ -801,10 +799,10 @@ def quo_rem(self, other): Return the quotient and remainder of the Euclidean division of ``self`` and ``other``. - Raises :class:`ZeroDivisionError` if ``other`` is zero. + Raises :exc:`ZeroDivisionError` if ``other`` is zero. - Raises :class:`ArithmeticError` if ``other`` has a nonunit leading coefficient - and this causes the Euclidean division to fail. + Raises :exc:`ArithmeticError` if ``other`` has a nonunit leading + coefficient and this causes the Euclidean division to fail. EXAMPLES:: @@ -906,26 +904,26 @@ def quo_rem(self, other): return (quo,rem) @coerce_binop - def gcd(self,other,algorithm=None): + def gcd(self, other, algorithm=None): r""" - Return the gcd of this polynomial and ``other`` + Return the gcd of this polynomial and ``other``. INPUT: - ``other`` -- a polynomial defined over the same ring as this - polynomial. + polynomial ALGORITHM: Two algorithms are provided: - - ``generic`` -- Uses the generic implementation, which depends on the - base ring being a UFD or a field. - - ``dense`` -- The polynomials are converted to the dense representation, - their gcd is computed and is converted back to the sparse - representation. + - ``'generic'`` -- uses the generic implementation, which depends on the + base ring being a UFD or a field + - ``'dense'`` -- the polynomials are converted to the dense + representation, their gcd is computed and is converted back to the + sparse representation - Default is ``dense`` for polynomials over `\ZZ` and ``generic`` in the + Default is ``'dense'`` for polynomials over `\ZZ` and ``'generic'`` in the other cases. EXAMPLES:: @@ -935,11 +933,11 @@ def gcd(self,other,algorithm=None): sage: q = 2*x^4 - x^3 - 2*x^2 - 4*x - 1 sage: gcd(p, q) x^2 + x + 1 - sage: gcd(p, q, algorithm="dense") + sage: gcd(p, q, algorithm='dense') x^2 + x + 1 - sage: gcd(p, q, algorithm="generic") + sage: gcd(p, q, algorithm='generic') x^2 + x + 1 - sage: gcd(p, q, algorithm="foobar") + sage: gcd(p, q, algorithm='foobar') Traceback (most recent call last): ... ValueError: Unknown algorithm 'foobar' @@ -1352,8 +1350,8 @@ def factor_of_slope(self, slope=None): """ INPUT: - - ``slope`` -- a rational number (default: the first slope - in the Newton polygon of ``self``) + - ``slope`` -- a rational number (default: the first slope + in the Newton polygon of ``self``) OUTPUT: @@ -1494,17 +1492,15 @@ def _roots(self, secure, minval, hint): INPUT: - - ``secure`` -- a boolean; whether we raise an error or + - ``secure`` -- boolean; whether we raise an error or not in case of multiple roots - - ``minval`` -- an integer + - ``minval`` -- integer - - ``hint`` -- a list or ``None``; if given, it must be the + - ``hint`` -- list or ``None``; if given, it must be the list of roots of the residual polynomial of slope ``minval`` - OUTPUT: - - A list of pairs ``(root, multiplicity)`` + OUTPUT: list of pairs ``(root, multiplicity)`` TESTS:: @@ -1513,13 +1509,12 @@ def _roots(self, secure, minval, hint): sage: S. = R[] sage: P = (x-1) * (x-2) * (x-4) * (x-8) * (x-16) sage: Q = P^2 - sage: Q.roots(algorithm="sage") # indirect doctest + sage: Q.roots(algorithm='sage') # indirect doctest [(2^4 + O(2^14), 2), (2^3 + O(2^13), 2), (2^2 + O(2^12), 2), (2 + O(2^11), 2), (1 + O(2^10), 2)] - """ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing K = self.base_ring() diff --git a/src/sage/rings/polynomial/polynomial_fateman.py b/src/sage/rings/polynomial/polynomial_fateman.py index 8ccf13eba09..ab13dd72708 100644 --- a/src/sage/rings/polynomial/polynomial_fateman.py +++ b/src/sage/rings/polynomial/polynomial_fateman.py @@ -16,9 +16,11 @@ def _mul_fateman_to_int2(f_list, g_list): """ - Convert a polynomial to an integer by evaluating it + Convert a polynomial to an integer by evaluating it. - INPUT: p, a list of integers + INPUT: + + - ``f_list``, ``g_list`` -- lists of integers OUTPUT: padding """ @@ -30,11 +32,10 @@ def _mul_fateman_to_int2(f_list, g_list): def _mul_fateman_to_poly(number, padding): """ - Converts a number to a polynomial, according to a padding. - - OUTPUT: + Convert a number to a polynomial, according to a padding. - a list containing the coefficient of a polynomial of degree len(list) + OUTPUT: list containing the coefficient of a polynomial of degree + ``len(list)`` """ coeffs = [] flag = 0 diff --git a/src/sage/rings/polynomial/polynomial_gf2x.pyx b/src/sage/rings/polynomial/polynomial_gf2x.pyx index fceadf66d6b..9ba3727e3c0 100644 --- a/src/sage/rings/polynomial/polynomial_gf2x.pyx +++ b/src/sage/rings/polynomial/polynomial_gf2x.pyx @@ -277,7 +277,6 @@ cdef class Polynomial_GF2X(Polynomial_template): False sage: f.is_irreducible.cache False - """ return 0 != GF2X_IterIrredTest(self.x) diff --git a/src/sage/rings/polynomial/polynomial_integer_dense_flint.pyx b/src/sage/rings/polynomial/polynomial_integer_dense_flint.pyx index 3f38f23ffdc..5879909eb1d 100644 --- a/src/sage/rings/polynomial/polynomial_integer_dense_flint.pyx +++ b/src/sage/rings/polynomial/polynomial_integer_dense_flint.pyx @@ -105,14 +105,14 @@ cdef class Polynomial_integer_dense_flint(Polynomial): def __dealloc__(self): r""" - calls the underlying FLINT fmpz_poly destructor + Call the underlying FLINT fmpz_poly destructor """ fmpz_poly_clear(self._poly) cdef Polynomial_integer_dense_flint _new(self): r""" - Quickly creates a new initialized Polynomial_integer_dense_flint - with the correct parent and _is_gen == 0. + Quickly create a new initialized ``Polynomial_integer_dense_flint`` + with the correct parent and ``_is_gen == 0``. """ cdef Polynomial_integer_dense_flint x = Polynomial_integer_dense_flint.__new__(Polynomial_integer_dense_flint) x._parent = self._parent @@ -121,19 +121,18 @@ cdef class Polynomial_integer_dense_flint(Polynomial): cpdef Polynomial _new_constant_poly(self, a, Parent P): r""" - Quickly creates a new constant polynomial with value a in parent P + Quickly create a new constant polynomial with value ``a`` in parent ``P``. ASSUMPTION: - The given value has to be in the base ring of P. This assumption is not - verified. + The given value has to be in the base ring of ``P``. This assumption is + not verified. EXAMPLES:: sage: R. = ZZ[] sage: x._new_constant_poly(2,R) 2 - """ cdef Polynomial_integer_dense_flint x = Polynomial_integer_dense_flint.__new__(Polynomial_integer_dense_flint) x._parent = P @@ -212,7 +211,6 @@ cdef class Polynomial_integer_dense_flint(Polynomial): sage: ZZ['x']({2^3: 1}) x^8 - """ Polynomial.__init__(self, parent, is_gen=is_gen) @@ -364,7 +362,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): def __call__(self, *x, **kwds): """ - Calls this polynomial with the given parameters, which can be + Call this polynomial with the given parameters, which can be interpreted as polynomial composition or evaluation by this method. @@ -504,7 +502,6 @@ cdef class Polynomial_integer_dense_flint(Polynomial): sage: R(-1).content() -1 - """ if self.is_zero(): return ZZ.zero() @@ -978,7 +975,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): cpdef Polynomial _mul_trunc_(self, Polynomial right, long n): r""" - Truncated multiplication + Truncated multiplication. .. SEEALSO:: @@ -1167,7 +1164,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): cpdef Polynomial _power_trunc(self, unsigned long n, long prec): r""" - Truncated power + Truncated power. TESTS:: @@ -1310,10 +1307,10 @@ cdef class Polynomial_integer_dense_flint(Polynomial): cpdef _unsafe_mutate(self, long n, value): r""" - Sets coefficient of `x^n` to value. + Set coefficient of `x^n` to value. This is very unsafe, because Sage polynomials are supposed to be - immutable. (Shhhh don't tell anyone!) + immutable. EXAMPLES:: @@ -1515,7 +1512,6 @@ cdef class Polynomial_integer_dense_flint(Polynomial): sage: f=-x^2 sage: f.squarefree_decomposition() (-1) * x^2 - """ cdef ZZX_c** v cdef long* e @@ -1658,7 +1654,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): - ``p`` -- prime - OUTPUT: factorization of ``self`` reduced modulo `p`. + OUTPUT: factorization of ``self`` reduced modulo `p` EXAMPLES:: @@ -1698,7 +1694,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): - ``prec`` -- integer; the precision - OUTPUT: factorization of ``self`` over the completion at `p`. + OUTPUT: factorization of ``self`` over the completion at `p` EXAMPLES:: @@ -1714,7 +1710,6 @@ cdef class Polynomial_integer_dense_flint(Polynomial): sage: f.factor_padic(5, 10) (4 + O(5^10)) * (5 + O(5^11))^2 * ((1 + O(5^10))*x + 5 + O(5^10))^2 * ((5 + O(5^10))*x + 1 + O(5^10))^2 - """ from sage.rings.padics.factory import Zp @@ -1815,7 +1810,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): sage: p.reverse(degree=1.5r) Traceback (most recent call last): ... - ValueError: degree argument must be a non-negative integer, got 1.5 + ValueError: degree argument must be a nonnegative integer, got 1.5 Check that this implementation is compatible with the generic one:: @@ -1828,10 +1823,10 @@ cdef class Polynomial_integer_dense_flint(Polynomial): cdef unsigned long d if degree is not None: if degree < 0: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) d = degree if d != degree: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) # FLINT expects length fmpz_poly_reverse(res._poly, self._poly, d+1) else: @@ -1853,7 +1848,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): sage: f.revert_series(-1) Traceback (most recent call last): ... - ValueError: argument n must be a non-negative integer, got -1 + ValueError: argument n must be a nonnegative integer, got -1 sage: g = - t^3 + t^5 sage: g.revert_series(6) @@ -1864,7 +1859,7 @@ cdef class Polynomial_integer_dense_flint(Polynomial): cdef Polynomial_integer_dense_flint res = self._new() cdef unsigned long m if n < 0: - raise ValueError("argument n must be a non-negative integer, got {}".format(n)) + raise ValueError("argument n must be a nonnegative integer, got {}".format(n)) m = n if not self[0].is_zero() or not self[1].is_unit(): raise ValueError("self must have constant coefficient 0 and a unit for coefficient {}^1".format(self.parent().gen())) diff --git a/src/sage/rings/polynomial/polynomial_integer_dense_ntl.pyx b/src/sage/rings/polynomial/polynomial_integer_dense_ntl.pyx index c4f175040bb..3f94f66f90b 100644 --- a/src/sage/rings/polynomial/polynomial_integer_dense_ntl.pyx +++ b/src/sage/rings/polynomial/polynomial_integer_dense_ntl.pyx @@ -75,8 +75,8 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): """ cdef Polynomial_integer_dense_ntl _new(self): r""" - Quickly creates a new initialized Polynomial_integer_dense_ntl - with the correct parent and _is_gen == 0. + Quickly create a new initialized ``Polynomial_integer_dense_ntl`` + with the correct parent and ``_is_gen == 0``. """ cdef Polynomial_integer_dense_ntl x = Polynomial_integer_dense_ntl.__new__(Polynomial_integer_dense_ntl) x._parent = self._parent @@ -430,7 +430,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): cpdef _add_(self, right): r""" - Returns self plus right. + Return ``self`` plus ``right``. EXAMPLES:: @@ -448,7 +448,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): cpdef _sub_(self, right): r""" - Return self minus right. + Return ``self`` minus ``right``. EXAMPLES:: @@ -466,7 +466,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): cpdef _neg_(self): r""" - Returns negative of ``self``. + Return negative of ``self``. EXAMPLES:: @@ -529,7 +529,6 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): (0, 0) sage: z.quo_rem(2*x) (0, 0) - """ cdef Polynomial_integer_dense_ntl _right = right @@ -681,7 +680,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): cpdef _mul_(self, right): r""" - Returns self multiplied by right. + Return ``self`` multiplied by ``right``. EXAMPLES:: @@ -696,7 +695,8 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): cpdef _lmul_(self, Element right): r""" - Returns self multiplied by right, where right is a scalar (integer). + Return ``self`` multiplied by ``right``, where ``right`` is a scalar + (integer). EXAMPLES:: @@ -715,7 +715,8 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): cpdef _rmul_(self, Element right): r""" - Returns self multiplied by right, where right is a scalar (integer). + Return ``self`` multiplied by ``right``, where ``right`` is a scalar + (integer). EXAMPLES:: @@ -763,10 +764,10 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): def _unsafe_mutate(self, long n, value): r""" - Sets coefficient of `x^n` to value. + Set coefficient of `x^n` to ``value``. This is very unsafe, because Sage polynomials are supposed - to be immutable. (Shhhh don't tell anyone!) + to be immutable. EXAMPLES:: @@ -787,7 +788,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): def real_root_intervals(self): """ - Returns isolating intervals for the real roots of this polynomial. + Return isolating intervals for the real roots of this polynomial. EXAMPLES: We compute the roots of the characteristic polynomial of some Salem numbers:: @@ -892,7 +893,6 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): sage: f = -x^2 sage: f.squarefree_decomposition() (-1) * x^2 - """ cdef Polynomial_integer_dense_ntl p = self c = p.content() @@ -916,7 +916,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): def _factor_pari(self): """ - Use pari to factor self. + Use pari to factor ``self``. EXAMPLES:: @@ -932,7 +932,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): def _factor_ntl(self): """ - Use NTL to factor self. + Use NTL to factor ``self``. AUTHOR: @@ -1012,7 +1012,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): - ``p`` -- prime - OUTPUT: factorization of ``self`` reduced modulo `p`. + OUTPUT: factorization of ``self`` reduced modulo `p` EXAMPLES:: @@ -1052,9 +1052,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): - ``prec`` -- integer; the precision - OUTPUT: - - - factorization of ``self`` over the completion at `p`. + OUTPUT: factorization of ``self`` over the completion at `p` EXAMPLES:: @@ -1070,7 +1068,6 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): sage: f.factor_padic(5, 10) (4 + O(5^10)) * (5 + O(5^11))^2 * ((1 + O(5^10))*x + 5 + O(5^10))^2 * ((5 + O(5^10))*x + 1 + O(5^10))^2 - """ from sage.rings.padics.factory import Zp @@ -1108,7 +1105,7 @@ cdef class Polynomial_integer_dense_ntl(Polynomial): @coerce_binop def resultant(self, other, proof=True): """ - Returns the resultant of ``self`` and ``other``, which must lie in the same + Return the resultant of ``self`` and ``other``, which must lie in the same polynomial ring. If ``proof=False`` (the default is ``proof=True``), then this function may use a diff --git a/src/sage/rings/polynomial/polynomial_modn_dense_ntl.pyx b/src/sage/rings/polynomial/polynomial_modn_dense_ntl.pyx index 29c75a19d30..d315cc1059e 100644 --- a/src/sage/rings/polynomial/polynomial_modn_dense_ntl.pyx +++ b/src/sage/rings/polynomial/polynomial_modn_dense_ntl.pyx @@ -96,7 +96,6 @@ cdef class Polynomial_dense_mod_n(Polynomial): sage: from sage.rings.polynomial.polynomial_modn_dense_ntl import Polynomial_dense_mod_n sage: isinstance(f, Polynomial_dense_mod_n) True - """ def __init__(self, parent, x=None, check=True, is_gen=False, construct=False): @@ -446,9 +445,9 @@ def small_roots(self, X=None, beta=1.0, epsilon=None, **kwds): - ``X`` -- an absolute bound for the root (default: see above) - ``beta`` -- compute a root mod `b` where `b` is a factor of `N` and `b - \ge N^\beta`. (Default: 1.0, so `b = N`.) - - ``epsilon`` -- the parameter `\epsilon` described above. (Default: `\beta/8`) - - ``**kwds`` -- passed through to method :meth:`Matrix_integer_dense.LLL() `. + \ge N^\beta` (default: 1.0, so `b = N`.) + - ``epsilon`` -- the parameter `\epsilon` described above. (default: `\beta/8`) + - ``**kwds`` -- passed through to method :meth:`Matrix_integer_dense.LLL() ` EXAMPLES: @@ -990,7 +989,7 @@ cdef class Polynomial_dense_modn_ntl_zz(Polynomial_dense_mod_n): def shift(self, n): """ - Shift self to left by `n`, which is multiplication by `x^n`, + Shift ``self`` to left by `n`, which is multiplication by `x^n`, truncating if `n` is negative. EXAMPLES:: @@ -1011,7 +1010,6 @@ cdef class Polynomial_dense_modn_ntl_zz(Polynomial_dense_mod_n): True sage: p.shift(-3).is_zero() True - """ return self << n @@ -1089,8 +1087,8 @@ cdef class Polynomial_dense_modn_ntl_zz(Polynomial_dense_mod_n): INPUT: - - ``degree`` (``None`` or an integer) -- if specified, truncate or zero - pad the list of coefficients to this degree before reversing it. + - ``degree`` -- ``None`` or integer; if specified, truncate or zero + pad the list of coefficients to this degree before reversing it EXAMPLES:: @@ -1141,7 +1139,7 @@ cdef class Polynomial_dense_modn_ntl_zz(Polynomial_dense_mod_n): def valuation(self): """ Return the valuation of ``self``, that is, the power of the - lowest non-zero monomial of ``self``. + lowest nonzero monomial of ``self``. EXAMPLES:: @@ -1193,7 +1191,7 @@ cdef class Polynomial_dense_modn_ntl_zz(Polynomial_dense_mod_n): def __call__(self, *args, **kwds): """ - Evaluate self at ``x``. If ``x`` is a single argument coercible into + Evaluate ``self`` at ``x``. If ``x`` is a single argument coercible into the base ring of ``self``, this is done directly in NTL, otherwise the generic Polynomial call code is used. @@ -1434,7 +1432,6 @@ cdef class Polynomial_dense_modn_ntl_ZZ(Polynomial_dense_mod_n): sage: R. = PolynomialRing(Integers(10^30), implementation='NTL') sage: type(R(0)^0) == type(R(0)) True - """ cdef bint recip = 0, do_sig cdef long e = ee @@ -1545,7 +1542,7 @@ cdef class Polynomial_dense_modn_ntl_ZZ(Polynomial_dense_mod_n): def shift(self, n): """ - Shift self to left by `n`, which is multiplication by `x^n`, + Shift ``self`` to left by `n`, which is multiplication by `x^n`, truncating if `n` is negative. EXAMPLES:: @@ -1566,7 +1563,6 @@ cdef class Polynomial_dense_modn_ntl_ZZ(Polynomial_dense_mod_n): True sage: p.shift(-3).is_zero() True - """ return self << n @@ -1644,8 +1640,8 @@ cdef class Polynomial_dense_modn_ntl_ZZ(Polynomial_dense_mod_n): INPUT: - - ``degree`` (``None`` or an integer) -- if specified, truncate or zero - pad the list of coefficients to this degree before reversing it. + - ``degree`` -- ``None`` or integer; if specified, truncate or zero + pad the list of coefficients to this degree before reversing it EXAMPLES:: @@ -1683,7 +1679,7 @@ cdef class Polynomial_dense_modn_ntl_ZZ(Polynomial_dense_mod_n): def valuation(self): """ Return the valuation of ``self``, that is, the power of the - lowest non-zero monomial of ``self``. + lowest nonzero monomial of ``self``. EXAMPLES:: @@ -1892,7 +1888,6 @@ cdef class Polynomial_dense_mod_p(Polynomial_dense_mod_n): sage: f, g = x + 2, x^2 - 1 sage: f.gcd(g) x + 2 - """ g = self.ntl_ZZ_pX().gcd(right.ntl_ZZ_pX()) return self.parent()(g, construct=True) @@ -1924,7 +1919,6 @@ cdef class Polynomial_dense_mod_p(Polynomial_dense_mod_n): (x^2 + x + 1, 0, 1) sage: ((x - 1)*(x + 1)).xgcd(x*(x - 1)) (x + 2, 1, 2) - """ r, s, t = self.ntl_ZZ_pX().xgcd(other.ntl_ZZ_pX()) return self.parent()(r, construct=True), self.parent()(s, construct=True), self.parent()(t, construct=True) diff --git a/src/sage/rings/polynomial/polynomial_number_field.pyx b/src/sage/rings/polynomial/polynomial_number_field.pyx index 54bddc4e203..7cef7645964 100644 --- a/src/sage/rings/polynomial/polynomial_number_field.pyx +++ b/src/sage/rings/polynomial/polynomial_number_field.pyx @@ -89,20 +89,20 @@ class Polynomial_absolute_number_field_dense(Polynomial_generic_dense_field): INPUT: - ``parent`` -- the polynomial ring in which to construct the - element. + element - - ``x`` -- (default: None) an object representing the + - ``x`` -- (default: ``None``) an object representing the polynomial, e.g. a list of coefficients. See :meth:`sage.rings.polynomial.polynomial_element_generic.Polynomial_generic_dense_field.__init__` for more details. - - ``check`` -- boolean (default: ``True``) if True, make sure that - the coefficients of the polynomial are in the base ring. + - ``check`` -- boolean (default: ``True``); if ``True``, make sure that + the coefficients of the polynomial are in the base ring - - ``is_gen`` -- boolean (default: ``False``) if True, `x` is the - distinguished generator of the polynomial ring. + - ``is_gen`` -- boolean (default: ``False``); if ``True``, `x` is the + distinguished generator of the polynomial ring - - ``construct`` -- (default: ``False``) boolean, unused. + - ``construct`` -- boolean (default: ``False``); unused EXAMPLES:: @@ -124,9 +124,9 @@ class Polynomial_absolute_number_field_dense(Polynomial_generic_dense_field): INPUT: - - ``other`` -- a polynomial with the same parent as ``self``. + - ``other`` -- a polynomial with the same parent as ``self`` - OUTPUT: The monic gcd of ``self`` and ``other``. + OUTPUT: the monic gcd of ``self`` and ``other`` EXAMPLES:: @@ -223,20 +223,20 @@ class Polynomial_relative_number_field_dense(Polynomial_generic_dense_field): INPUT: - ``parent`` -- polynomial ring in which to construct the - element. + element - ``x`` -- (default: ``None``) an object representing the polynomial, e.g. a list of coefficients. See :meth:`sage.rings.polynomial.polynomial_element_generic.Polynomial_generic_dense_field.__init__` for more details. - - ``check`` -- boolean (default: ``True``) if ``True``, make sure that - the coefficients of the polynomial are in the base ring. + - ``check`` -- boolean (default: ``True``); if ``True``, make sure that + the coefficients of the polynomial are in the base ring - - ``is_gen`` -- boolean (default: ``False``) if ``True``, ``x`` is the - distinguished generator of the polynomial ring. + - ``is_gen`` -- boolean (default: ``False``); if ``True``, ``x`` is the + distinguished generator of the polynomial ring - - ``construct`` -- (default: ``False``) boolean, unused. + - ``construct`` -- boolean (default: ``False``); unused EXAMPLES:: @@ -259,11 +259,9 @@ class Polynomial_relative_number_field_dense(Polynomial_generic_dense_field): INPUT: - - ``other`` -- a polynomial with the same parent as ``self``. - - OUTPUT: + - ``other`` -- a polynomial with the same parent as ``self`` - The monic gcd of ``self`` and ``other``. + OUTPUT: the monic gcd of ``self`` and ``other`` See :meth:`Polynomial_absolute_number_field_dense.gcd` for more details. diff --git a/src/sage/rings/polynomial/polynomial_quotient_ring.py b/src/sage/rings/polynomial/polynomial_quotient_ring.py index 0ce0673ad67..e12977e8464 100644 --- a/src/sage/rings/polynomial/polynomial_quotient_ring.py +++ b/src/sage/rings/polynomial/polynomial_quotient_ring.py @@ -68,13 +68,13 @@ class PolynomialQuotientRingFactory(UniqueFactory): INPUT: - - ``ring`` -- a univariate polynomial ring + - ``ring`` -- a univariate polynomial ring - - ``polynomial`` -- an element of ``ring`` with a unit leading coefficient + - ``polynomial`` -- an element of ``ring`` with a unit leading coefficient - - ``names`` -- (optional) name for the variable + - ``names`` -- (optional) name for the variable - OUTPUT: Creates the quotient ring `R/I`, where `R` is the ring and `I` is + OUTPUT: creates the quotient ring `R/I`, where `R` is the ring and `I` is the principal ideal generated by ``polynomial``. EXAMPLES: @@ -175,7 +175,6 @@ class PolynomialQuotientRingFactory(UniqueFactory): sage: f = x^2 - 1 sage: R.quotient_by_principal_ideal(f) Univariate Quotient Polynomial Ring in xbar over Rational Field with modulus x^2 - 1 - """ def create_key(self, ring, polynomial, names=None): r""" @@ -212,7 +211,6 @@ def create_key(self, ring, polynomial, names=None): sage: R.quo(x + 1) is R.quo(2*x + 2) True - """ if not isinstance(ring, PolynomialRing_commutative): raise TypeError("ring must be a polynomial ring") @@ -242,7 +240,6 @@ def create_object(self, version, key): sage: PolynomialQuotientRing.create_object((8, 0, 0), ....: (R, x^2 - 1, ('xbar'))) Univariate Quotient Polynomial Ring in xbar over Rational Field with modulus x^2 - 1 - """ ring, polynomial, names = key @@ -266,6 +263,10 @@ def create_object(self, version, key): PolynomialQuotientRing = PolynomialQuotientRingFactory("PolynomialQuotientRing") def is_PolynomialQuotientRing(x): + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_PolynomialQuotientRing is deprecated; " + "use 'isinstance(..., PolynomialQuotientRing_generic)' instead.") return isinstance(x, PolynomialQuotientRing_generic) @@ -415,7 +416,6 @@ def __init__(self, ring, polynomial, name=None, category=None): ... , ... - """ if not isinstance(ring, PolynomialRing_commutative): raise TypeError("R must be a univariate polynomial ring.") @@ -447,11 +447,9 @@ def _element_constructor_(self, x): INPUT: + - ``x`` -- object to be converted - - ``x`` -- object to be converted - - - OUTPUT: an element obtained by converting x into this ring. + OUTPUT: an element obtained by converting x into this ring EXAMPLES:: @@ -525,7 +523,6 @@ def _element_constructor_(self, x): sage: Q3('x*ybar^2') -x - """ if not isinstance(x, str): try: @@ -585,7 +582,6 @@ def _coerce_map_from_(self, R): sage: Q2 = R.quo([(y^2 + 1)]) sage: Q2.has_coerce_map_from(Q1) False - """ if self.__ring.has_coerce_map_from(R): return True @@ -670,7 +666,6 @@ def lift(self, x): -2*xbar sage: Q.0^3 -2*xbar - """ return x.lift() @@ -762,7 +757,6 @@ def _singular_init_(self, S=None): _[1]=xbar^2+1 sage: singular(Q.gen()) # needs sage.libs.singular xbar - """ if S is None: from sage.interfaces.singular import singular as S @@ -780,7 +774,7 @@ def _repr_(self): def construction(self): """ - Functorial construction of ``self`` + Functorial construction of ``self``. EXAMPLES:: @@ -1067,7 +1061,6 @@ def is_field(self, proof=True): (1 + O(2^20))*x^2 + (1 + O(2^20))*x + 1 + O(2^20) as an isomorphic ring sage: F2.is_field(proof = False) False - """ ret = self.base_ring().is_field(proof) try: @@ -1266,19 +1259,17 @@ def random_element(self, degree=None, *args, **kwds): INPUT: - - ``degree`` -- Optional argument: either an integer for fixing the + - ``degree`` -- (optional) argument; either an integer for fixing the degree, or a tuple of the minimum and maximum degree. By default the degree is n - 1 with n the degree of the polynomial ring. Note that the degree of the polynomial is fixed before the modulo calculation. So when `degree` is bigger than the degree of the polynomial ring, the degree of the returned polynomial would be lower than `degree`. - - ``*args``, ``**kwds`` -- Arguments for randomization that are passed + - ``*args``, ``**kwds`` -- arguments for randomization that are passed on to the ``random_element`` method of the polynomial ring, and from there to the base ring - OUTPUT: - - Element of this quotient ring + OUTPUT: element of this quotient ring EXAMPLES:: @@ -1298,7 +1289,7 @@ def random_element(self, degree=None, *args, **kwds): @cached_method def _S_decomposition(self, S): """ - Compute the decomposition of self into a product of number fields. + Compute the decomposition of ``self`` into a product of number fields. This is an internal function used by :meth:`S_class_group`, :meth:`S_units` and :meth:`selmer_generators`. @@ -1342,10 +1333,10 @@ def _S_decomposition(self, S): if not isinstance(K, NumberField) or not self.__polynomial.is_squarefree(): raise NotImplementedError - from sage.rings.ideal import is_Ideal + from sage.rings.ideal import Ideal_generic for p in S: # second check due to inconsistency over QQ - see # 7596 - if not (is_Ideal(p) + if not (isinstance(p, Ideal_generic) and (p.ring() is K or p.ring() is K.ring_of_integers()) and p.is_prime()): raise TypeError("S must be a list of prime ideals of the base field.") @@ -1398,9 +1389,9 @@ def S_class_group(self, S, proof=True): INPUT: - - ``S`` -- a set of primes of the coefficient ring + - ``S`` -- set of primes of the coefficient ring - - ``proof`` -- if False, assume the GRH in computing the class group + - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: @@ -1572,7 +1563,7 @@ def class_group(self, proof=True): INPUT: - - ``proof`` -- if False, assume the GRH in computing the class group + - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: @@ -1668,22 +1659,21 @@ def class_group(self, proof=True): sage: type(CG[0][1]) - """ return self.S_class_group((), proof=proof) def S_units(self, S, proof=True): """ - If self is an étale algebra `D` over a number field `K` (i.e. + If ``self`` is an étale algebra `D` over a number field `K` (i.e. a quotient of `K[x]` by a squarefree polynomial) and `S` is a finite set of places of `K`, return a list of generators of the group of `S`-units of `D`. INPUT: - - ``S`` -- a set of primes of the base field + - ``S`` -- set of primes of the base field - - ``proof`` -- if False, assume the GRH in computing the class group + - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: @@ -1745,7 +1735,6 @@ def S_units(self, S, proof=True): sage: type(U[1][1]) - """ fields, isos, iso_classes = self._S_decomposition(tuple(S)) n = len(fields) @@ -1778,7 +1767,7 @@ def units(self, proof=True): INPUT: - - ``proof`` -- if False, assume the GRH in computing the class group + - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: @@ -1842,13 +1831,12 @@ def units(self, proof=True): sage: type(U[1][1]) - """ return self.S_units((), proof=proof) def selmer_generators(self, S, m, proof=True): r""" - If self is an étale algebra `D` over a number field `K` (i.e. + If ``self`` is an étale algebra `D` over a number field `K` (i.e. a quotient of `K[x]` by a squarefree polynomial) and `S` is a finite set of places of `K`, compute the Selmer group `D(S,m)`. This is the subgroup of `D^*/(D^*)^m` consisting of @@ -1857,11 +1845,11 @@ def selmer_generators(self, S, m, proof=True): INPUT: - - ``S`` -- A set of primes of the coefficient ring (which is a number field). + - ``S`` -- set of primes of the coefficient ring (which is a number field) - - ``m`` -- a positive integer + - ``m`` -- positive integer - - ``proof`` -- if False, assume the GRH in computing the class group + - ``proof`` -- if ``False``, assume the GRH in computing the class group OUTPUT: @@ -1889,7 +1877,6 @@ def selmer_generators(self, S, m, proof=True): ....: K.ideal(3, a + 1), ....: K.ideal(a)], 3) [2, a + 1, -a] - """ fields, isos, iso_classes = self._S_decomposition(tuple(S)) n = len(fields) @@ -1931,7 +1918,6 @@ def _factor_multivariate_polynomial(self, f, proof=True): sage: F = t * x sage: F.factor(proof=False) # needs sage.modules (x) * t - """ from sage.structure.factorization import Factorization @@ -1963,7 +1949,6 @@ def _factor_univariate_polynomial(self, f): (T + y) * (T + y + 1) sage: (y*T^2 + y*T + y*x).factor() # indirect doctest # needs sage.modules (y) * (T + y) * (T + y + 1) - """ from sage.structure.factorization import Factorization @@ -2033,7 +2018,6 @@ def _isomorphic_ring(self): sage: R. = K[] # needs sage.rings.finite_rings sage: from_L, to_L, L = R.quo(b)._isomorphic_ring(); L # needs sage.rings.finite_rings Finite Field in a of size 2^2 - """ from sage.categories.homset import Hom from sage.categories.morphism import SetMorphism @@ -2156,7 +2140,6 @@ def _test_isomorphic_ring(self, **options): sage: R. = L[] sage: M. = L.extension(c^2 + b*c + b) sage: M._test_isomorphic_ring() - """ tester = self._tester(**options) @@ -2215,7 +2198,6 @@ class PolynomialQuotientRing_coercion(DefaultConvertMap_unique): To: Univariate Quotient Polynomial Ring in xbar over Rational Field with modulus x^2 + 1 sage: f == g True - """ def is_injective(self): r""" @@ -2232,7 +2214,6 @@ def is_injective(self): sage: f = S.quo(x^2 + 1).coerce_map_from(R.quo(x^2 + 1)) sage: f.is_injective() True - """ if (self.domain().modulus().change_ring(self.codomain().base_ring()) == self.codomain().modulus() and self.domain().modulus().leading_coefficient().is_unit()): @@ -2267,7 +2248,6 @@ def is_surjective(self): sage: f = S.quo(x^2 + 2).coerce_map_from(R.quo(x^2 + 2)) sage: f.is_surjective() False - """ constant_map_is_surjective = self.codomain().base_ring().coerce_map_from(self.domain().base_ring()).is_surjective() if constant_map_is_surjective: @@ -2290,7 +2270,6 @@ def _richcmp_(self, other, op): False sage: f == f True - """ if type(self) is not type(other): return NotImplemented @@ -2353,7 +2332,6 @@ def field_extension(self, names): - homomorphism from field to ``self`` - EXAMPLES:: sage: # needs sage.rings.number_field diff --git a/src/sage/rings/polynomial/polynomial_quotient_ring_element.py b/src/sage/rings/polynomial/polynomial_quotient_ring_element.py index 97534f3aa22..919b4b856d4 100644 --- a/src/sage/rings/polynomial/polynomial_quotient_ring_element.py +++ b/src/sage/rings/polynomial/polynomial_quotient_ring_element.py @@ -104,7 +104,6 @@ class PolynomialQuotientRingElement(polynomial_singular_interface.Polynomial_sin xi sage: (singular(xi)*singular(xi)).NF('std(0)') # needs sage.libs.singular -1 - """ def __init__(self, parent, polynomial, check=True): """ @@ -112,14 +111,13 @@ def __init__(self, parent, polynomial, check=True): INPUT: + - ``parent`` -- a quotient of a polynomial ring - - ``parent`` -- a quotient of a polynomial ring - - - ``polynomial`` -- a polynomial + - ``polynomial`` -- a polynomial - - ``check`` -- bool (optional): whether or not to - verify that x is a valid element of the polynomial ring and reduced - (mod the modulus). + - ``check`` -- boolean (default: ``True``); whether or not to + verify that x is a valid element of the polynomial ring and reduced + (mod the modulus). """ from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic from sage.rings.polynomial.polynomial_element import Polynomial @@ -399,7 +397,7 @@ def __invert__(self): sage: (2*y)^(-1) -1/2*y - 1 - Raises a ``ZeroDivisionError`` if this element is not a unit:: + Raises a :exc:`ZeroDivisionError` if this element is not a unit:: sage: (y+1)^(-1) Traceback (most recent call last): @@ -457,7 +455,6 @@ def field_extension(self, names): - ``names`` -- name of generator of output field - OUTPUT: - field @@ -466,7 +463,6 @@ def field_extension(self, names): - homomorphism from field to ``self`` - EXAMPLES:: sage: # needs sage.rings.number_field @@ -584,9 +580,7 @@ def charpoly(self, var): INPUT: - - - ``var`` -- string; the variable name - + - ``var`` -- string; the variable name EXAMPLES:: diff --git a/src/sage/rings/polynomial/polynomial_rational_flint.pyx b/src/sage/rings/polynomial/polynomial_rational_flint.pyx index 84d6ed56596..df25358ff3b 100644 --- a/src/sage/rings/polynomial/polynomial_rational_flint.pyx +++ b/src/sage/rings/polynomial/polynomial_rational_flint.pyx @@ -108,11 +108,9 @@ cdef class Polynomial_rational_flint(Polynomial): cdef Polynomial_rational_flint _new(self): """ - Quickly creates a new polynomial object in this class. + Quickly create a new polynomial object in this class. - OUTPUT: - - - Polynomial of type Polynomial_rational_flint + OUTPUT: polynomial of type ``Polynomial_rational_flint`` TESTS:: @@ -129,7 +127,7 @@ cdef class Polynomial_rational_flint(Polynomial): cpdef Polynomial _new_constant_poly(self, x, Parent P): r""" - Quickly creates a new constant polynomial with value x in parent P + Quickly create a new constant polynomial with value x in parent P. ASSUMPTION: @@ -178,7 +176,7 @@ cdef class Polynomial_rational_flint(Polynomial): def __dealloc__(self): """ - Deallocates the underlying data structure. + Deallocate the underlying data structure. TESTS:: @@ -194,15 +192,15 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``parent`` -- Polynomial ring, the parent of ``self`` - - ``x`` -- Data for the new polynomial self, e.g. a polynomial, an + - ``parent`` -- polynomial ring, the parent of ``self`` + - ``x`` -- data for the new polynomial ``self``, e.g. a polynomial, an integer, a rational, a list of rationals, a dictionary with keys the degrees and the rational coefficients, etc (default: ``None``) - - `check`` -- Whether the integrity of the data needs to be verified, + - ``check`` -- whether the integrity of the data needs to be verified, largely ignored by this method (default: ``True``) - - ``is_gen`` -- Whether self shall be initialised as the generator of + - ``is_gen`` -- whether ``self`` shall be initialised as the generator of the parent polynomial ring - - ``construct`` -- Whether the element shall always be constructed + - ``construct`` -- whether the element shall always be constructed as an independent copy of any input data (default: ``False``) TESTS:: @@ -396,8 +394,8 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``n`` -- Degree of the monomial whose coefficient is to be - returned. + - ``n`` -- degree of the monomial whose coefficient is to be + returned EXAMPLES:: @@ -414,7 +412,7 @@ cdef class Polynomial_rational_flint(Polynomial): cpdef _unsafe_mutate(self, unsigned long n, value): """ - Sets the `n`-th coefficient of ``self`` to value. + Set the `n`-th coefficient of ``self`` to ``value``. TESTS:: @@ -455,7 +453,7 @@ cdef class Polynomial_rational_flint(Polynomial): def __call__(self, *x, **kwds): """ - Calls this polynomial with the given parameters, which can be + Call this polynomial with the given parameters, which can be interpreted as polynomial composition or evaluation by this method. @@ -561,11 +559,11 @@ cdef class Polynomial_rational_flint(Polynomial): cpdef Polynomial truncate(self, long n): """ - Return self truncated modulo `t^n`. + Return ``self`` truncated modulo `t^n`. INPUT: - - ``n`` -- The power of `t` modulo which ``self`` is truncated + - ``n`` -- the power of `t` modulo which ``self`` is truncated EXAMPLES:: @@ -597,9 +595,9 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``degree`` (``None`` or integral value that fits in an ``unsigned - long``, default: degree of ``self``) - if specified, truncate or zero - pad the list of coefficients to this degree before reversing it. + - ``degree`` -- ``None`` or integral value that fits in an ``unsigned + long`` (default: degree of ``self``); if specified, truncate or zero + pad the list of coefficients to this degree before reversing it EXAMPLES: @@ -641,7 +639,7 @@ cdef class Polynomial_rational_flint(Polynomial): We illustrate two ways in which the interpretation of ``degree`` as an unsigned long int may fail. Firstly, an integral value which is - too large, yielding an ``OverflowError``:: + too large, yielding an :exc:`OverflowError`:: sage: R. = QQ[] sage: f = 1 + t/2 @@ -700,7 +698,7 @@ cdef class Polynomial_rational_flint(Polynomial): sage: f.revert_series(-1) Traceback (most recent call last): - ValueError: argument n must be a non-negative integer, got -1 + ValueError: argument n must be a nonnegative integer, got -1 sage: g = - t^3/3 + t^5/5 sage: g.revert_series(6) @@ -712,7 +710,7 @@ cdef class Polynomial_rational_flint(Polynomial): cdef Polynomial_rational_flint res = self._new() cdef unsigned long m if n < 0: - raise ValueError("argument n must be a non-negative integer, got {}".format(n)) + raise ValueError("argument n must be a nonnegative integer, got {}".format(n)) m = n if not self[0].is_zero() or not self[1].is_unit(): raise ValueError("self must have constant coefficient 0 and a unit for coefficient {}^1".format(self.parent().gen())) @@ -764,7 +762,7 @@ cdef class Polynomial_rational_flint(Polynomial): def __bool__(self): """ - Return whether or not ``self`` is non-zero. + Return whether or not ``self`` is nonzero. EXAMPLES:: @@ -783,7 +781,7 @@ cdef class Polynomial_rational_flint(Polynomial): def __lshift__(self, n): """ - Notationally multiplies self by `t^n`. + Notationally multiply ``self`` by `t^n`. EXAMPLES:: @@ -816,7 +814,7 @@ cdef class Polynomial_rational_flint(Polynomial): def __rshift__(self, n): """ - Notationally returns the quotient of Euclidean division of ``self`` + Notationally return the quotient of Euclidean division of ``self`` by `t^n`. EXAMPLES:: @@ -934,7 +932,7 @@ cdef class Polynomial_rational_flint(Polynomial): Return the quotient and remainder of the Euclidean division of ``self`` and ``right``. - Raises a :class:`ZeroDivisionError` if ``right`` is zero. + Raises a :exc:`ZeroDivisionError` if ``right`` is zero. EXAMPLES:: @@ -1164,21 +1162,19 @@ cdef class Polynomial_rational_flint(Polynomial): def __pow__(Polynomial_rational_flint self, exp, ignored): """ - Return self raised to the power of exp. + Return ``self`` raised to the power of ``exp``. The corner case of ``exp == 0`` is handled by returning the constant polynomial 1. Note that this includes the case ``0^0 == 1``. - This method only supports integral values for exp that fit into + This method only supports integral values for ``exp`` that fit into a signed long int (except when this is a constant polynomial). INPUT: - - ``exp`` -- Exponent - - OUTPUT: + - ``exp`` -- exponent - Polynomial; this polynomial raised to the power of ``exp`` + OUTPUT: polynomial; this polynomial raised to the power of ``exp`` EXAMPLES:: @@ -1447,7 +1443,7 @@ cdef class Polynomial_rational_flint(Polynomial): """ Return the numerator of ``self``. - Representing self as the quotient of an integer polynomial and + Representing ``self`` as the quotient of an integer polynomial and a positive integer denominator (coprime to the content of the polynomial), returns the integer polynomial. @@ -1492,13 +1488,11 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``var`` -- Must be either (equal to) the generator of the polynomial - ring to which this polynomial belongs, or ``None``; either way the - behaviour is the same. + - ``var`` -- must be either (equal to) the generator of the polynomial + ring to which this polynomial belongs, or ``None``; either way the + behaviour is the same - OUTPUT: - - - Derivative as a ``Polynomial_rational_flint`` + OUTPUT: derivative as a ``Polynomial_rational_flint`` .. SEEALSO:: :meth:`~Polynomial.derivative` @@ -1602,7 +1596,7 @@ cdef class Polynomial_rational_flint(Polynomial): ring. By definition, over any integral domain, an element `r` is irreducible - if and only if it is non-zero, not a unit and whenever `r = ab` then + if and only if it is nonzero, not a unit and whenever `r = ab` then `a` or `b` is a unit. EXAMPLES:: @@ -1631,7 +1625,6 @@ cdef class Polynomial_rational_flint(Polynomial): True sage: f.is_irreducible.cache True - """ cdef Polynomial_integer_dense_flint primitive cdef unsigned long length = fmpq_poly_length(self._poly) @@ -1929,7 +1922,7 @@ cdef class Polynomial_rational_flint(Polynomial): def _cos_series(self, long prec): r""" - Return the cosine of this polynomial up to precision ``prec`` + Return the cosine of this polynomial up to precision ``prec``. EXAMPLES:: @@ -2072,18 +2065,18 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``self`` -- Irreducible polynomial + - ``self`` -- irreducible polynomial - - ``pari_group`` -- bool (default: ``False``); if ``True`` instead - return the Galois group as a PARI group. This has a useful label - in it, and may be slightly faster since it doesn't require looking - up a group in GAP. To get a permutation group from a PARI - group ``P``, type ``PermutationGroup(P)``. + - ``pari_group`` -- boolean (default: ``False``); if ``True`` instead + return the Galois group as a PARI group. This has a useful label + in it, and may be slightly faster since it doesn't require looking + up a group in GAP. To get a permutation group from a PARI + group ``P``, type ``PermutationGroup(P)``. - - ``algorithm`` -- ``'pari'``, ``'gap'``, ``'kash'``, ``'magma'`` (default: - ``'pari'``, for degrees is at most 11; - ``'gap'``, for degrees from 12 to 15; - ``'kash'``, for degrees from 16 or more). + - ``algorithm`` -- ``'pari'``, ``'gap'``, ``'kash'``, ``'magma'`` (default: + ``'pari'``, for degrees is at most 11; + ``'gap'``, for degrees from 12 to 15; + ``'kash'``, for degrees from 16 or more). OUTPUT: Galois group @@ -2250,13 +2243,13 @@ cdef class Polynomial_rational_flint(Polynomial): Return the factorization of ``self`` modulo the prime `p`. Assumes that the degree of this polynomial is at least one, and raises - a :class:`ValueError` otherwise. + a :exc:`ValueError` otherwise. INPUT: - - ``p`` -- Prime number + - ``p`` -- prime number - OUTPUT: Factorization of this polynomial modulo `p` + OUTPUT: factorization of this polynomial modulo `p` EXAMPLES:: @@ -2272,7 +2265,6 @@ cdef class Polynomial_rational_flint(Polynomial): sage: R. = QQ[] sage: (zeta^2 + zeta + 1).factor_mod(7) (zeta + 3) * (zeta + 5) - """ from sage.rings.finite_rings.finite_field_constructor import FiniteField @@ -2295,9 +2287,9 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``p`` -- Prime number + - ``p`` -- prime number - - ``prec`` -- Integer; the precision + - ``prec`` -- integer; the precision OUTPUT: factorization of ``self`` viewed as a `p`-adic polynomial @@ -2348,7 +2340,7 @@ cdef class Polynomial_rational_flint(Polynomial): sage: f.factor_padic(3, -1) Traceback (most recent call last): ... - ValueError: prec_cap must be non-negative + ValueError: prec_cap must be nonnegative sage: f.factor_padic(6, 10) Traceback (most recent call last): ... @@ -2383,8 +2375,8 @@ cdef class Polynomial_rational_flint(Polynomial): INPUT: - - ``p`` -- Prime number; coerceable to :class:`Integer` - - ``e`` -- Exponent; coerceable to :class:`Integer` + - ``p`` -- prime number; coerceable to :class:`Integer` + - ``e`` -- exponent; coerceable to :class:`Integer` OUTPUT: Hensel lifts; list of polynomials over `\ZZ / p^e \ZZ` @@ -2420,7 +2412,6 @@ cdef class Polynomial_rational_flint(Polynomial): Traceback (most recent call last): ... ValueError: I^2 + 1 is not square-free modulo 2 - """ from sage.rings.finite_rings.integer_mod_ring import IntegerModRing @@ -2465,7 +2456,7 @@ cdef class Polynomial_rational_flint(Polynomial): The discriminant of constant polynomials is defined to be 0. - OUTPUT: Discriminant, an element of the base ring of the polynomial ring + OUTPUT: discriminant, an element of the base ring of the polynomial ring .. NOTE:: @@ -2522,7 +2513,6 @@ cdef class Polynomial_rational_flint(Polynomial): sage: R. = QQ[] sage: (I^2 + 1).discriminant() -4 - """ return QQ(self._pari_with_name().poldisc()) @@ -2552,7 +2542,6 @@ cdef class Polynomial_rational_flint(Polynomial): sage: u = x^7 - 2 sage: u.galois_group_davenport_smith_test() 0 - """ from sage.arith.misc import primes_first_n from sage.rings.finite_rings.integer_mod_ring import IntegerModRing diff --git a/src/sage/rings/polynomial/polynomial_real_mpfr_dense.pyx b/src/sage/rings/polynomial/polynomial_real_mpfr_dense.pyx index bd3e95f8420..cfcdcabdcb5 100644 --- a/src/sage/rings/polynomial/polynomial_real_mpfr_dense.pyx +++ b/src/sage/rings/polynomial/polynomial_real_mpfr_dense.pyx @@ -55,7 +55,6 @@ cdef class PolynomialRealDense(Polynomial): sage: from sage.rings.polynomial.polynomial_real_mpfr_dense import PolynomialRealDense sage: isinstance(f, PolynomialRealDense) True - """ cdef Py_ssize_t _degree @@ -259,7 +258,7 @@ cdef class PolynomialRealDense(Polynomial): cpdef Polynomial truncate(self, long n): r""" - Returns the polynomial of degree `< n` which is equivalent to self + Return the polynomial of degree `< n` which is equivalent to ``self`` modulo `x^n`. EXAMPLES:: @@ -312,7 +311,7 @@ cdef class PolynomialRealDense(Polynomial): cpdef shift(self, Py_ssize_t n): r""" - Returns this polynomial multiplied by the power `x^n`. If `n` + Return this polynomial multiplied by the power `x^n`. If `n` is negative, terms below `x^n` will be discarded. Does not change this polynomial. @@ -567,8 +566,8 @@ cdef class PolynomialRealDense(Polynomial): INPUT: - - ``degree`` (``None`` or an integer) -- if specified, truncate or zero - pad the list of coefficients to this degree before reversing it. + - ``degree`` -- ``None`` or an integer; if specified, truncate or zero + pad the list of coefficients to this degree before reversing it EXAMPLES:: diff --git a/src/sage/rings/polynomial/polynomial_ring.py b/src/sage/rings/polynomial/polynomial_ring.py index d0d2d1241ab..165c7fb72a4 100644 --- a/src/sage/rings/polynomial/polynomial_ring.py +++ b/src/sage/rings/polynomial/polynomial_ring.py @@ -191,6 +191,10 @@ def is_PolynomialRing(x): sage: from sage.rings.polynomial.polynomial_ring import is_PolynomialRing sage: from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing sage: is_PolynomialRing(2) + doctest:warning... + DeprecationWarning: The function is_PolynomialRing is deprecated; + use 'isinstance(..., PolynomialRing_general)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. False This polynomial ring is not univariate. @@ -200,6 +204,10 @@ def is_PolynomialRing(x): sage: is_PolynomialRing(ZZ['x,y,z']) False sage: is_MPolynomialRing(ZZ['x,y,z']) + doctest:warning... + DeprecationWarning: The function is_MPolynomialRing is deprecated; + use 'isinstance(..., MPolynomialRing_base)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. True :: @@ -214,13 +222,17 @@ def is_PolynomialRing(x): :: sage: # needs sage.libs.singular - sage: R. = PolynomialRing(ZZ, implementation="singular"); R + sage: R. = PolynomialRing(ZZ, implementation='singular'); R Multivariate Polynomial Ring in w over Integer Ring sage: is_PolynomialRing(R) False sage: type(R) """ + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_PolynomialRing is deprecated; " + "use 'isinstance(..., PolynomialRing_general)' instead.") return isinstance(x, PolynomialRing_general) @@ -388,7 +400,7 @@ def _element_constructor_(self, x=None, check=True, is_gen=False, sage: S(x) x - Throw a :class:`TypeError` if any of the coefficients cannot be coerced + Throw a :exc:`TypeError` if any of the coefficients cannot be coerced into the base ring (:issue:`6777`):: sage: RealField(300)['x']( [ 1, ComplexField(300).gen(), 0 ]) # needs sage.rings.real_mpfr @@ -490,11 +502,11 @@ def _implementation_names(cls, implementation, base_ring, sparse=False): INPUT: - ``implementation`` -- either a string denoting a specific - implementation or ``None`` for the default. + implementation or ``None`` for the default - - ``base_ring`` -- the base ring for the polynomial ring. + - ``base_ring`` -- the base ring for the polynomial ring - - ``sparse`` -- (boolean) whether the implementation is sparse. + - ``sparse`` -- boolean; whether the implementation is sparse OUTPUT: @@ -506,7 +518,7 @@ def _implementation_names(cls, implementation, base_ring, sparse=False): ``None``. - if the implementation is not supported, raise a - ``ValueError``. + :exc:`ValueError`. EXAMPLES:: @@ -535,7 +547,7 @@ def _implementation_names_impl(implementation, base_ring, sparse): The behaviour is exactly the same, except that an unknown implementation returns ``NotImplemented`` instead of raising - ``ValueError``. + :exc:`ValueError`. EXAMPLES:: @@ -603,7 +615,7 @@ def some_elements(self): @cached_method def flattening_morphism(self): r""" - Return the flattening morphism of this polynomial ring + Return the flattening morphism of this polynomial ring. EXAMPLES:: @@ -616,9 +628,9 @@ def flattening_morphism(self): sage: QQ['x'].flattening_morphism() Identity endomorphism of Univariate Polynomial Ring in x over Rational Field """ - from .multi_polynomial_ring import is_MPolynomialRing + from .multi_polynomial_ring import MPolynomialRing_base base = self.base_ring() - if is_PolynomialRing(base) or is_MPolynomialRing(base): + if isinstance(base, PolynomialRing_general) or isinstance(base, MPolynomialRing_base): from .flatten import FlatteningMorphism return FlatteningMorphism(self) else: @@ -718,9 +730,9 @@ def _coerce_map_from_(self, P): - polynomial rings in the same variable over any base ring that canonically coerces to the base ring of this ring. - - a multivariate polynomial ring P such that self's variable name + - a multivariate polynomial ring P such that ``self``'s variable name is among the variable names of P, and the ring obtained by - removing that variable is different from the base ring of self, + removing that variable is different from the base ring of ``self``, but coerces into it. (see :issue:`813` for a discussion of this) Caveat: There is no coercion from a dense into a sparse @@ -770,9 +782,9 @@ def _coerce_map_from_(self, P): implementation to the default FLINT implementation:: sage: del R, S # clear values from doctests above - sage: R = PolynomialRing(ZZ, 't', implementation="NTL") # needs sage.libs.ntl - sage: S = PolynomialRing(ZZ, 't', implementation="FLINT") # needs sage.libs.flint - sage: T = PolynomialRing(ZZ, 't', implementation="generic") + sage: R = PolynomialRing(ZZ, 't', implementation='NTL') # needs sage.libs.ntl + sage: S = PolynomialRing(ZZ, 't', implementation='FLINT') # needs sage.libs.flint + sage: T = PolynomialRing(ZZ, 't', implementation='generic') sage: R.has_coerce_map_from(S) # needs sage.libs.flint sage.libs.ntl False sage: R.has_coerce_map_from(T) # needs sage.libs.ntl @@ -803,7 +815,7 @@ def _coerce_map_from_(self, P): # polynomial rings in the same variable over a base that canonically # coerces into self.base_ring() - if is_PolynomialRing(P): + if isinstance(P, PolynomialRing_general): if self.construction()[0] != P.construction()[0]: # Construction (including variable names) must be the # same to allow coercion @@ -842,8 +854,8 @@ def _coerce_map_from_(self, P): return PolynomialRingHomomorphism_from_base(RingHomset(P, self), f) # Last, we consider multivariate polynomial rings: - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing - if is_MPolynomialRing(P) and self.variable_name() in P.variable_names(): + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base + if isinstance(P, MPolynomialRing_base) and self.variable_name() in P.variable_names(): P_ = P.remove_var(self.variable_name()) return self.base_ring() != P_ and self.base_ring().has_coerce_map_from(P_) @@ -1116,11 +1128,9 @@ def variable_names_recursive(self, depth=sage.rings.infinity.infinity): INPUT: - - ``depth`` -- an integer or :mod:`Infinity `. + - ``depth`` -- integer or :mod:`Infinity ` - OUTPUT: - - A tuple of strings. + OUTPUT: a tuple of strings EXAMPLES:: @@ -1143,9 +1153,8 @@ def variable_names_recursive(self, depth=sage.rings.infinity.infinity): def _mpoly_base_ring(self, variables=None): r""" - Returns the base ring if this is viewed as a polynomial ring over - ``variables``. See also - Polynomial._mpoly_dict_recursive + Return the base ring if this is viewed as a polynomial ring over + ``variables``. See also ``Polynomial._mpoly_dict_recursive``. """ if variables is None: variables = self.variable_names_recursive() @@ -1180,7 +1189,7 @@ def characteristic(self): def cyclotomic_polynomial(self, n): """ - Return the nth cyclotomic polynomial as a polynomial in this + Return the `n`-th cyclotomic polynomial as a polynomial in this polynomial ring. For details of the implementation, see the documentation for :func:`sage.rings.polynomial.cyclotomic.cyclotomic_coeffs`. @@ -1371,14 +1380,14 @@ def random_element(self, degree=(-1, 2), monic=False, *args, **kwds): INPUT: - - ``degree`` -- (default: ``(-1, 2)``) integer for fixing the degree or - a tuple of minimum and maximum degrees + - ``degree`` -- (default: ``(-1, 2)``) integer for fixing the degree or + a tuple of minimum and maximum degrees - - ``monic`` -- boolean (optional); indicate whether the sampled - polynomial should be monic + - ``monic`` -- boolean (default: ``False``); indicate whether the sampled + polynomial should be monic - - ``*args, **kwds`` -- additional keyword parameters passed on to the - ``random_element`` method for the base ring + - ``*args, **kwds`` -- additional keyword parameters passed on to the + ``random_element`` method for the base ring EXAMPLES:: @@ -1596,7 +1605,7 @@ def _Karatsuba_threshold(self): 0 """ base_ring = self.base_ring() - if is_PolynomialRing(base_ring): + if isinstance(base_ring, PolynomialRing_general): return 0 try: from sage.matrix.matrix_space import MatrixSpace @@ -1654,12 +1663,11 @@ def polynomials( self, of_degree=None, max_degree=None ): INPUT: Pass exactly one of: - - ``max_degree`` -- an int; the iterator will generate - all polynomials which have degree less than or equal to - ``max_degree`` + - ``max_degree`` -- an int; the iterator will generate all polynomials + which have degree less than or equal to ``max_degree`` - - ``of_degree`` -- an int; the iterator will generate - all polynomials which have degree ``of_degree`` + - ``of_degree`` -- an int; the iterator will generate + all polynomials which have degree ``of_degree`` OUTPUT: an iterator @@ -1720,13 +1728,11 @@ def monics( self, of_degree=None, max_degree=None ): INPUT: Pass exactly one of: - - ``max_degree`` -- an int; the iterator will generate - all monic polynomials which have degree less than or equal to - ``max_degree`` - - - ``of_degree`` -- an int; the iterator will generate - all monic polynomials which have degree ``of_degree`` + - ``max_degree`` -- an int; the iterator will generate all monic + polynomials which have degree less than or equal to ``max_degree`` + - ``of_degree`` -- an int; the iterator will generate + all monic polynomials which have degree ``of_degree`` OUTPUT: an iterator @@ -1802,8 +1808,8 @@ def quotient_by_principal_ideal(self, f, names=None, **kwds): INPUT: - ``f`` -- either a polynomial in ``self``, or a principal - ideal of ``self``. - - further named arguments that are passed to the quotient constructor. + ideal of ``self`` + - further named arguments that are passed to the quotient constructor EXAMPLES:: @@ -1861,10 +1867,13 @@ def _roots_univariate_polynomial(self, p, ring=None, multiplicities=True, algori INPUT: - ``p`` -- the polynomial whose roots are computed - - ``ring`` -- the ring to find roots (default is the base ring of ``p``) - - ``multiplicities`` -- bool (default: ``True``): if ``True``, return a list of pairs ``(root, multiplicity)``; if ``False`` return a list of roots + - ``ring`` -- the ring to find roots (default: the base ring of ``p``) + - ``multiplicities`` -- boolean (default: ``True``); if ``True``, + return a list of pairs ``(root, multiplicity)``; if ``False`` return + a list of roots - ``algorithm`` -- ignored (TODO: remove) - - ``degree_bound`` -- if not ``None``, return only roots of degree at most ``degree_bound`` + - ``degree_bound`` -- if not ``None``, return only roots of degree at + most ``degree_bound`` EXAMPLES:: @@ -1904,7 +1913,7 @@ def _roots_univariate_polynomial(self, p, ring=None, multiplicities=True, algori class PolynomialRing_integral_domain(PolynomialRing_commutative, PolynomialRing_singular_repr, IntegralDomain): - def __init__(self, base_ring, name="x", sparse=False, implementation=None, + def __init__(self, base_ring, name='x', sparse=False, implementation=None, element_class=None, category=None): """ TESTS:: @@ -1965,16 +1974,16 @@ def weil_polynomials(self, d, q, sign=1, lead=1): INPUT: - - ``d`` -- integer, the degree of the polynomials + - ``d`` -- integer; the degree of the polynomials - - ``q`` -- integer, the square of the complex absolute value of the + - ``q`` -- integer; the square of the complex absolute value of the roots - - ``sign`` -- integer (default `1`), the sign `s` of the functional + - ``sign`` -- integer (default: `1`); the sign `s` of the functional equation - - ``lead`` -- integer, list of integers or list of pairs of integers - (default `1`), constraints on the leading few coefficients of the + - ``lead`` -- integer; list of integers or list of pairs of integers + (default: `1`), constraints on the leading few coefficients of the generated polynomials. If pairs `(a, b)` of integers are given, they are treated as a constraint of the form `\equiv a \pmod{b}`; the moduli must be in decreasing order by divisibility, and the modulus @@ -2135,7 +2144,7 @@ def construction(self): class PolynomialRing_field(PolynomialRing_integral_domain, PrincipalIdealDomain): - def __init__(self, base_ring, name="x", sparse=False, implementation=None, + def __init__(self, base_ring, name='x', sparse=False, implementation=None, element_class=None, category=None): """ TESTS:: @@ -2202,7 +2211,7 @@ def _element_class(): def _ideal_class_(self, n=0): """ - Returns the class representing ideals in univariate polynomial rings + Return the class representing ideals in univariate polynomial rings over fields. EXAMPLES:: @@ -2221,12 +2230,12 @@ def divided_difference(self, points, full_table=False): INPUT: - - ``points`` -- a list of pairs `(x_0, y_0), (x_1, y_1), + - ``points`` -- list of pairs `(x_0, y_0), (x_1, y_1), \dots, (x_n, y_n)` of elements of the base ring of ``self``, where `x_i - x_j` is invertible for `i \neq j`. This method converts the `x_i` and `y_i` into the base ring of ``self``. - - ``full_table`` -- boolean (default: ``False``): If ``True``, + - ``full_table`` -- boolean (default: ``False``); if ``True``, return the full divided-difference table. If ``False``, only return entries along the main diagonal; these are the Newton divided-difference coefficients `F_{i,i}`. @@ -2303,19 +2312,19 @@ def divided_difference(self, points, full_table=False): else: return [F[i][i] for i in range(n)] - def lagrange_polynomial(self, points, algorithm="divided_difference", previous_row=None): + def lagrange_polynomial(self, points, algorithm='divided_difference', previous_row=None): r""" Return the Lagrange interpolation polynomial through the given points. INPUT: - - ``points`` -- a list of pairs `(x_0, y_0), (x_1, y_1), + - ``points`` -- list of pairs `(x_0, y_0), (x_1, y_1), \dots, (x_n, y_n)` of elements of the base ring of ``self``, where `x_i - x_j` is invertible for `i \neq j`. This method converts the `x_i` and `y_i` into the base ring of ``self``. - - ``algorithm`` -- (default: ``'divided_difference'``): one of + - ``algorithm`` -- (default: ``'divided_difference'``) one of the following: - ``'divided_difference'``: use the method of divided @@ -2331,7 +2340,7 @@ def lagrange_polynomial(self, points, algorithm="divided_difference", previous_r table, instead of the full table itself. Generating the full table can be memory inefficient. - - ``previous_row`` -- (default: ``None``): This option is only + - ``previous_row`` -- (default: ``None``) this option is only relevant if used with ``algorithm='neville'``. If provided, this should be the last row of the table resulting from a previous use of Neville's method. If such a row is passed, @@ -2379,7 +2388,7 @@ def lagrange_polynomial(self, points, algorithm="divided_difference", previous_r sage: R = PolynomialRing(QQ, 'x') sage: R.lagrange_polynomial([(0,1), (2,2), (3,-2), (-4,9)], - ....: algorithm="neville") + ....: algorithm='neville') [9, -11/7*x + 19/7, -17/42*x^2 - 83/42*x + 53/7, @@ -2389,24 +2398,24 @@ def lagrange_polynomial(self, points, algorithm="divided_difference", previous_r sage: R = PolynomialRing(GF(2**3, 'a'), 'x') sage: a = R.base_ring().gen() sage: R.lagrange_polynomial([(a^2+a, a), (a, 1), (a^2, a^2+a+1)], - ....: algorithm="neville") + ....: algorithm='neville') [a^2 + a + 1, x + a + 1, a^2*x^2 + a^2*x + a^2] Repeated use of Neville's method to get better Lagrange interpolation polynomials:: sage: R = PolynomialRing(QQ, 'x') - sage: p = R.lagrange_polynomial([(0,1), (2,2)], algorithm="neville") + sage: p = R.lagrange_polynomial([(0,1), (2,2)], algorithm='neville') sage: R.lagrange_polynomial([(0,1), (2,2), (3,-2), (-4,9)], - ....: algorithm="neville", previous_row=p)[-1] + ....: algorithm='neville', previous_row=p)[-1] -23/84*x^3 - 11/84*x^2 + 13/7*x + 1 sage: # needs sage.rings.finite_rings sage: R = PolynomialRing(GF(2**3, 'a'), 'x') sage: a = R.base_ring().gen() - sage: p = R.lagrange_polynomial([(a^2+a, a), (a, 1)], algorithm="neville") + sage: p = R.lagrange_polynomial([(a^2+a, a), (a, 1)], algorithm='neville') sage: R.lagrange_polynomial([(a^2+a, a), (a, 1), (a^2, a^2+a+1)], - ....: algorithm="neville", previous_row=p)[-1] + ....: algorithm='neville', previous_row=p)[-1] a^2*x^2 + a^2*x + a^2 TESTS: @@ -2414,16 +2423,16 @@ def lagrange_polynomial(self, points, algorithm="divided_difference", previous_r The value for ``algorithm`` must be either ``'divided_difference'`` (default), or ``'neville'``:: - sage: R = PolynomialRing(QQ, "x") - sage: R.lagrange_polynomial([(0,1),(2,2),(3,-2),(-4,9)], algorithm="abc") + sage: R = PolynomialRing(QQ, 'x') + sage: R.lagrange_polynomial([(0,1),(2,2),(3,-2),(-4,9)], algorithm='abc') Traceback (most recent call last): ... ValueError: algorithm must be one of 'divided_difference' or 'neville' - sage: R.lagrange_polynomial([(0,1),(2,2),(3,-2),(-4,9)], algorithm="divided difference") + sage: R.lagrange_polynomial([(0,1),(2,2),(3,-2),(-4,9)], algorithm='divided difference') Traceback (most recent call last): ... ValueError: algorithm must be one of 'divided_difference' or 'neville' - sage: R.lagrange_polynomial([(0,1),(2,2),(3,-2),(-4,9)], algorithm="") + sage: R.lagrange_polynomial([(0,1),(2,2),(3,-2),(-4,9)], algorithm='') Traceback (most recent call last): ... ValueError: algorithm must be one of 'divided_difference' or 'neville' @@ -2433,7 +2442,7 @@ def lagrange_polynomial(self, points, algorithm="divided_difference", previous_r ``divided_difference``, or a list of elements of ``self`` in the case of ``neville``:: - sage: R = PolynomialRing(QQ, "x") + sage: R = PolynomialRing(QQ, 'x') sage: R.lagrange_polynomial([]).parent() == R True sage: R.lagrange_polynomial([(2, 3)]).parent() == R @@ -2581,7 +2590,7 @@ class PolynomialRing_dense_finite_field(PolynomialRing_field): sage: type(R) # needs sage.rings.finite_rings """ - def __init__(self, base_ring, name="x", element_class=None, implementation=None): + def __init__(self, base_ring, name='x', element_class=None, implementation=None): """ TESTS:: @@ -2651,20 +2660,17 @@ def irreducible_element(self, n, algorithm=None): INPUT: - - ``n`` -- integer: degree of the polynomial to construct + - ``n`` -- integer; degree of the polynomial to construct - - ``algorithm`` -- string: algorithm to use, or ``None`` + - ``algorithm`` -- string (algorithm to use) or ``None``: - ``'random'`` or ``None``: - try random polynomials until an irreducible - one is found. + try random polynomials until an irreducible one is found - ``'first_lexicographic'``: try polynomials in - lexicographic order until an irreducible one is found. - - OUTPUT: + lexicographic order until an irreducible one is found - A monic irreducible polynomial of degree `n` in ``self``. + OUTPUT: a monic irreducible polynomial of degree `n` in ``self`` EXAMPLES:: @@ -2675,10 +2681,10 @@ def irreducible_element(self, n, algorithm=None): sage: f.is_irreducible() True sage: R = GF(19)['x'] - sage: R.irreducible_element(21, algorithm="first_lexicographic") + sage: R.irreducible_element(21, algorithm='first_lexicographic') x^21 + x + 5 sage: R = GF(5**2, 'a')['x'] - sage: R.irreducible_element(17, algorithm="first_lexicographic") + sage: R.irreducible_element(17, algorithm='first_lexicographic') x^17 + a*x + 4*a + 3 AUTHORS: @@ -2724,9 +2730,7 @@ def _roth_ruckenstein(self, p, degree_bound, precision): - ``precision`` -- if given, roots are computed modulo `x^d` where `d` is ``precision`` (see below) - OUTPUT: - - The list of roots of ``p`` of degree at most ``degree_bound``: + OUTPUT: the list of roots of ``p`` of degree at most ``degree_bound``: - If `precision = None` actual roots are computed, i.e. all `f \in F[x]` such that `p(f) = 0`. @@ -2819,9 +2823,7 @@ def _alekhnovich(self, p, degree_bound, precision=None, dc_threshold=None): - ``dc_threshold`` -- if given, the algorithm calls :meth:`_roth_ruckenetein` to compute roots of degree at most ``dc_threshold`` - OUTPUT: - - The list of roots of ``p`` of degree at most ``degree_bound``: + OUTPUT: the list of roots of ``p`` of degree at most ``degree_bound``: - If `precision = None` actual roots are computed, i.e. all `f \in F[x]` such that `p(f) = 0`. @@ -2873,7 +2875,7 @@ def _alekhnovich(self, p, degree_bound, precision=None, dc_threshold=None): """ def alekh_rec(p, k, degree_bound, lvl): r""" - Recursive core method for Alekhnovich algorithm." + Recursive core method for Alekhnovich algorithm. INPUT: @@ -2943,11 +2945,11 @@ def _roots_univariate_polynomial(self, p, ring=None, multiplicities=False, algor INPUT: - ``p`` -- the polynomial whose roots are computed - - ``ring`` -- the ring to find roots (default is the base ring of ``p``) - - ``multiplicities`` -- bool (default: ``True``): currently, roots are only - computed without their multiplicities. - - ``algorithm`` -- the algorithm to use: either ``"Alekhnovich"`` (default) - or ``"Roth-Ruckenstein"`` + - ``ring`` -- the ring to find roots (default: the base ring of ``p``) + - ``multiplicities`` -- boolean (default: ``True``); currently, roots are only + computed without their multiplicities + - ``algorithm`` -- the algorithm to use: either ``'Alekhnovich'`` (default) + or ``'Roth-Ruckenstein'`` - ``degree_bound`` -- if not ``None``, return only roots of degree at most ``degree_bound`` @@ -2961,7 +2963,7 @@ def _roots_univariate_polynomial(self, p, ring=None, multiplicities=False, algor [x^2 + 11*x + 1, x + 1] sage: p.roots(multiplicities=False, degree_bound=1) [x + 1] - sage: p.roots(multiplicities=False, algorithm="Roth-Ruckenstein") + sage: p.roots(multiplicities=False, algorithm='Roth-Ruckenstein') [x^2 + 11*x + 1, x + 1] TESTS: @@ -3066,7 +3068,7 @@ def __init__(self, base_ring, name=None, sparse=False, implementation=None, class PolynomialRing_dense_padic_ring_generic(PolynomialRing_cdvr): r""" - A class for dense polynomial ring over p-adic rings + A class for dense polynomial ring over `p`-adic rings """ def __init__(self, base_ring, name=None, implementation=None, element_class=None, category=None): PolynomialRing_cdvr.__init__(self, base_ring, sparse=False, name=name, @@ -3095,7 +3097,7 @@ def _implementation_names_impl(implementation, base_ring, sparse): class PolynomialRing_dense_padic_field_generic(PolynomialRing_cdvf): r""" - A class for dense polynomial ring over p-adic fields + A class for dense polynomial ring over `p`-adic fields """ def __init__(self, base_ring, name=None, implementation=None, element_class=None, category=None): PolynomialRing_cdvf.__init__(self, base_ring, sparse=False, name=name, @@ -3384,7 +3386,7 @@ def residue_field(self, ideal, names=None): class PolynomialRing_dense_mod_p(PolynomialRing_dense_finite_field, PolynomialRing_dense_mod_n, PolynomialRing_singular_repr): - def __init__(self, base_ring, name="x", implementation=None, element_class=None, category=None): + def __init__(self, base_ring, name='x', implementation=None, element_class=None, category=None): """ TESTS:: @@ -3464,13 +3466,13 @@ def _implementation_names_impl(implementation, base_ring, sparse): TESTS:: sage: # needs sage.libs.ntl - sage: PolynomialRing(GF(2), 'x', implementation="GF2X") + sage: PolynomialRing(GF(2), 'x', implementation='GF2X') Univariate Polynomial Ring in x over Finite Field of size 2 (using GF2X) - sage: PolynomialRing(GF(2), 'x', implementation="NTL") + sage: PolynomialRing(GF(2), 'x', implementation='NTL') Univariate Polynomial Ring in x over Finite Field of size 2 (using GF2X) sage: PolynomialRing(GF(2), 'x', implementation=None) Univariate Polynomial Ring in x over Finite Field of size 2 (using GF2X) - sage: PolynomialRing(GF(3), 'x', implementation="GF2X") + sage: PolynomialRing(GF(3), 'x', implementation='GF2X') Traceback (most recent call last): ... ValueError: GF2X only supports modulus 2 @@ -3507,17 +3509,17 @@ def irreducible_element(self, n, algorithm=None): INPUT: - - ``n`` -- integer: the degree of the polynomial to construct + - ``n`` -- integer; the degree of the polynomial to construct - - ``algorithm`` -- string: algorithm to use, or ``None``. - Currently available options are: + - ``algorithm`` -- string (algorithm to use) or ``None``; + currently available options are: - ``'adleman-lenstra'``: a variant of the Adleman--Lenstra algorithm as implemented in PARI. - ``'conway'``: look up the Conway polynomial of degree `n` over the field of `p` elements in the database; raise a - ``RuntimeError`` if it is not found. + :exc:`RuntimeError` if it is not found. - ``'ffprimroot'``: use the :pari:`ffprimroot` function from PARI. @@ -3543,42 +3545,40 @@ def irreducible_element(self, n, algorithm=None): is used if `p = 2`, and the algorithm ``'adleman-lenstra'`` if `p > 2`. - OUTPUT: - - A monic irreducible polynomial of degree `n` in ``self``. + OUTPUT: a monic irreducible polynomial of degree `n` in ``self`` EXAMPLES:: sage: # needs sage.rings.finite_rings sage: GF(5)['x'].irreducible_element(2) x^2 + 4*x + 2 - sage: GF(5)['x'].irreducible_element(2, algorithm="adleman-lenstra") + sage: GF(5)['x'].irreducible_element(2, algorithm='adleman-lenstra') x^2 + x + 1 - sage: GF(5)['x'].irreducible_element(2, algorithm="primitive") + sage: GF(5)['x'].irreducible_element(2, algorithm='primitive') x^2 + 4*x + 2 - sage: GF(5)['x'].irreducible_element(32, algorithm="first_lexicographic") + sage: GF(5)['x'].irreducible_element(32, algorithm='first_lexicographic') x^32 + 2 - sage: GF(5)['x'].irreducible_element(32, algorithm="conway") + sage: GF(5)['x'].irreducible_element(32, algorithm='conway') Traceback (most recent call last): ... RuntimeError: requested Conway polynomial not in database. - sage: GF(5)['x'].irreducible_element(32, algorithm="primitive") + sage: GF(5)['x'].irreducible_element(32, algorithm='primitive') x^32 + ... In characteristic 2:: sage: GF(2)['x'].irreducible_element(33) # needs sage.rings.finite_rings x^33 + x^13 + x^12 + x^11 + x^10 + x^8 + x^6 + x^3 + 1 - sage: GF(2)['x'].irreducible_element(33, algorithm="minimal_weight") # needs sage.rings.finite_rings + sage: GF(2)['x'].irreducible_element(33, algorithm='minimal_weight') # needs sage.rings.finite_rings x^33 + x^10 + 1 In degree 1:: sage: GF(97)['x'].irreducible_element(1) # needs sage.rings.finite_rings x + 96 - sage: GF(97)['x'].irreducible_element(1, algorithm="conway") # needs sage.rings.finite_rings + sage: GF(97)['x'].irreducible_element(1, algorithm='conway') # needs sage.rings.finite_rings x + 92 - sage: GF(97)['x'].irreducible_element(1, algorithm="adleman-lenstra") # needs sage.rings.finite_rings + sage: GF(97)['x'].irreducible_element(1, algorithm='adleman-lenstra') # needs sage.rings.finite_rings x AUTHORS: @@ -3679,15 +3679,15 @@ def fraction_field(self): return super().fraction_field() -def polygen(ring_or_element, name="x"): +def polygen(ring_or_element, name='x'): """ Return a polynomial indeterminate. INPUT: - - ``polygen(base_ring, name="x")`` + - ``polygen(base_ring, name='x')`` - - ``polygen(ring_element, name="x")`` + - ``polygen(ring_element, name='x')`` If the first input is a ring, return a polynomial generator over that ring. If it is a ring element, return a polynomial generator @@ -3701,7 +3701,7 @@ def polygen(ring_or_element, name="x"): sage: parent(z) Univariate Polynomial Ring in z over Rational Field - .. note:: + .. NOTE:: If you give a list or comma-separated string to :func:`polygen`, you'll get a tuple of indeterminates, exactly as if you called @@ -3721,7 +3721,7 @@ def polygen(ring_or_element, name="x"): return t.gen() -def polygens(base_ring, names="x", *args): +def polygens(base_ring, names='x', *args): """ Return indeterminates over the given base ring with the given names. diff --git a/src/sage/rings/polynomial/polynomial_ring_constructor.py b/src/sage/rings/polynomial/polynomial_ring_constructor.py index e417e8a6779..674a84f0ff7 100644 --- a/src/sage/rings/polynomial/polynomial_ring_constructor.py +++ b/src/sage/rings/polynomial/polynomial_ring_constructor.py @@ -76,15 +76,15 @@ def PolynomialRing(base_ring, *args, **kwds): - ``base_ring`` -- a ring - - ``n`` -- an integer + - ``n`` -- integer - - ``name`` -- a string + - ``name`` -- string - - ``names`` -- a list or tuple of names (strings), or a comma separated string + - ``names`` -- list or tuple of names (strings), or a comma separated string - - ``var_array`` -- a list or tuple of names, or a comma separated string + - ``var_array`` -- list or tuple of names, or a comma separated string - - ``sparse`` -- bool: whether or not elements are sparse. The + - ``sparse`` -- boolean; whether or not elements are sparse. The default is a dense representation (``sparse=False``) for univariate rings and a sparse representation (``sparse=True``) for multivariate rings. @@ -92,15 +92,15 @@ def PolynomialRing(base_ring, *args, **kwds): - ``order`` -- string or :class:`~sage.rings.polynomial.term_order.TermOrder` object, e.g., - - ``'degrevlex'`` (default) -- degree reverse lexicographic - - ``'lex'`` -- lexicographic + - ``'degrevlex'`` -- default; degree reverse lexicographic + - ``'lex'`` -- lexicographic - ``'deglex'`` -- degree lexicographic - ``TermOrder('deglex',3) + TermOrder('deglex',3)`` -- block ordering - ``implementation`` -- string or None; selects an implementation in cases where Sage includes multiple choices (currently `\ZZ[x]` can be implemented with ``'NTL'`` or ``'FLINT'``; default is ``'FLINT'``). - For many base rings, the ``"singular"`` implementation is available. + For many base rings, the ``'singular'`` implementation is available. One can always specify ``implementation="generic"`` for a generic Sage implementation which does not use any specialized library. @@ -269,9 +269,9 @@ def PolynomialRing(base_ring, *args, **kwds): The Singular implementation always returns a multivariate ring, even for 1 variable:: - sage: PolynomialRing(QQ, "x", implementation="singular") # needs sage.libs.singular + sage: PolynomialRing(QQ, "x", implementation='singular') # needs sage.libs.singular Multivariate Polynomial Ring in x over Rational Field - sage: P. = PolynomialRing(QQ, implementation="singular"); P # needs sage.libs.singular + sage: P. = PolynomialRing(QQ, implementation='singular'); P # needs sage.libs.singular Multivariate Polynomial Ring in x over Rational Field **3. PolynomialRing(base_ring, n, names, ...)** (where the arguments @@ -407,43 +407,43 @@ def PolynomialRing(base_ring, *args, **kwds): NotImplementedError: a dense representation of multivariate polynomials is not supported Check uniqueness if the same implementation is used for different - values of the ``"implementation"`` keyword:: + values of the ``'implementation'`` keyword:: - sage: R = PolynomialRing(QQbar, 'j', implementation="generic") # needs sage.rings.number_field + sage: R = PolynomialRing(QQbar, 'j', implementation='generic') # needs sage.rings.number_field sage: S = PolynomialRing(QQbar, 'j', implementation=None) # needs sage.rings.number_field sage: R is S # needs sage.rings.number_field True - sage: R = PolynomialRing(ZZ['t'], 'j', implementation="generic") + sage: R = PolynomialRing(ZZ['t'], 'j', implementation='generic') sage: S = PolynomialRing(ZZ['t'], 'j', implementation=None) sage: R is S True sage: # needs sage.rings.number_field - sage: R = PolynomialRing(QQbar, 'j,k', implementation="generic") + sage: R = PolynomialRing(QQbar, 'j,k', implementation='generic') sage: S = PolynomialRing(QQbar, 'j,k', implementation=None) sage: R is S True sage: # needs sage.libs.singular - sage: R = PolynomialRing(ZZ, 'j,k', implementation="singular") + sage: R = PolynomialRing(ZZ, 'j,k', implementation='singular') sage: S = PolynomialRing(ZZ, 'j,k', implementation=None) sage: R is S True - sage: R = PolynomialRing(ZZ, 'p', sparse=True, implementation="generic") + sage: R = PolynomialRing(ZZ, 'p', sparse=True, implementation='generic') sage: S = PolynomialRing(ZZ, 'p', sparse=True) sage: R is S True The generic implementation is different in some cases:: - sage: R = PolynomialRing(GF(2), 'j', implementation="generic"); TestSuite(R).run(skip=['_test_construction', '_test_pickling']); type(R) + sage: R = PolynomialRing(GF(2), 'j', implementation='generic'); TestSuite(R).run(skip=['_test_construction', '_test_pickling']); type(R) sage: S = PolynomialRing(GF(2), 'j'); TestSuite(S).run(); type(S) - sage: R = PolynomialRing(ZZ, 'x,y', implementation="generic"); TestSuite(R).run(skip=['_test_elements', '_test_elements_eq_transitive']); type(R) + sage: R = PolynomialRing(ZZ, 'x,y', implementation='generic'); TestSuite(R).run(skip=['_test_elements', '_test_elements_eq_transitive']); type(R) sage: S = PolynomialRing(ZZ, 'x,y'); TestSuite(S).run(skip='_test_elements'); type(S) # needs sage.libs.singular @@ -471,19 +471,19 @@ def PolynomialRing(base_ring, *args, **kwds): Traceback (most recent call last): ... ValueError: unknown implementation 'FLINT' for multivariate polynomial rings - sage: R. = PolynomialRing(QQbar, implementation="whatever") # needs sage.rings.number_field + sage: R. = PolynomialRing(QQbar, implementation='whatever') # needs sage.rings.number_field Traceback (most recent call last): ... ValueError: unknown implementation 'whatever' for dense polynomial rings over Algebraic Field - sage: R. = PolynomialRing(ZZ['t'], implementation="whatever") + sage: R. = PolynomialRing(ZZ['t'], implementation='whatever') Traceback (most recent call last): ... ValueError: unknown implementation 'whatever' for dense polynomial rings over Univariate Polynomial Ring in t over Integer Ring - sage: PolynomialRing(RR, "x,y", implementation="whatever") + sage: PolynomialRing(RR, "x,y", implementation='whatever') Traceback (most recent call last): ... ValueError: unknown implementation 'whatever' for multivariate polynomial rings - sage: PolynomialRing(RR, name="x", implementation="singular") # needs sage.libs.singular + sage: PolynomialRing(RR, name='x', implementation='singular') # needs sage.libs.singular Traceback (most recent call last): ... NotImplementedError: polynomials over Real Field with 53 bits of precision are not supported in Singular @@ -541,28 +541,28 @@ def PolynomialRing(base_ring, *args, **kwds): sage: PolynomialRing(QQ, -1) Traceback (most recent call last): ... - ValueError: number of variables must be non-negative + ValueError: number of variables must be nonnegative sage: PolynomialRing(QQ, 1) Traceback (most recent call last): ... TypeError: you must specify the names of the variables - sage: PolynomialRing(QQ, "x", None) + sage: PolynomialRing(QQ, 'x', None) Traceback (most recent call last): ... TypeError: invalid arguments ('x', None) for PolynomialRing - sage: PolynomialRing(QQ, "x", "y") + sage: PolynomialRing(QQ, 'x', 'y') Traceback (most recent call last): ... TypeError: variable names specified twice: 'x' and 'y' - sage: PolynomialRing(QQ, 1, "x", 2) + sage: PolynomialRing(QQ, 1, 'x', 2) Traceback (most recent call last): ... TypeError: number of variables specified twice: 1 and 2 - sage: PolynomialRing(QQ, "x", names="x") + sage: PolynomialRing(QQ, 'x', names='x') Traceback (most recent call last): ... TypeError: variable names specified twice inconsistently: ('x',) and 'x' - sage: PolynomialRing(QQ, name="x", names="x") + sage: PolynomialRing(QQ, name='x', names='x') Traceback (most recent call last): ... TypeError: keyword argument 'name' cannot be combined with 'names' @@ -593,18 +593,18 @@ def PolynomialRing(base_ring, *args, **kwds): Multivariate Polynomial Ring in x, y, z over Rational Field sage: Q0 = PolynomialRing(QQ,[]); TestSuite(Q0).run(skip=['_test_elements', '_test_elements_eq_transitive', '_test_gcd_vs_xgcd', '_test_quo_rem']); Q0 Multivariate Polynomial Ring in no variables over Rational Field - sage: P. = PolynomialRing(QQ, implementation="singular"); TestSuite(P).run(skip=['_test_construction', '_test_elements', # needs sage.libs.singular + sage: P. = PolynomialRing(QQ, implementation='singular'); TestSuite(P).run(skip=['_test_construction', '_test_elements', # needs sage.libs.singular ....: '_test_euclidean_degree', '_test_quo_rem']); P Multivariate Polynomial Ring in x over Rational Field sage: Q1 = PolynomialRing(QQ,"x",1); TestSuite(Q1).run(skip=['_test_construction', '_test_elements', '_test_euclidean_degree', '_test_quo_rem']); Q1 Multivariate Polynomial Ring in x over Rational Field sage: Q0 = PolynomialRing(QQ,"x",0); TestSuite(Q0).run(skip=['_test_elements', '_test_elements_eq_transitive', '_test_gcd_vs_xgcd', '_test_quo_rem']); Q0 Multivariate Polynomial Ring in no variables over Rational Field - sage: R = PolynomialRing(GF(2), 'j', implementation="generic"); TestSuite(R).run(skip=['_test_construction', '_test_pickling']); type(R) + sage: R = PolynomialRing(GF(2), 'j', implementation='generic'); TestSuite(R).run(skip=['_test_construction', '_test_pickling']); type(R) sage: S = PolynomialRing(GF(2), 'j'); TestSuite(S).run(); type(S) - sage: R = PolynomialRing(ZZ, 'x,y', implementation="generic"); TestSuite(R).run(skip=['_test_elements', '_test_elements_eq_transitive']); type(R) + sage: R = PolynomialRing(ZZ, 'x,y', implementation='generic'); TestSuite(R).run(skip=['_test_elements', '_test_elements_eq_transitive']); type(R) sage: S = PolynomialRing(ZZ, 'x,y'); TestSuite(S).run(skip='_test_elements'); type(S) # needs sage.libs.singular @@ -665,7 +665,7 @@ def PolynomialRing(base_ring, *args, **kwds): for arg in args: k = Integer(arg) if k < 0: - raise ValueError("number of variables must be non-negative") + raise ValueError("number of variables must be nonnegative") suffixes = [s + str(i) for s in suffixes for i in range(k)] names = [v + s for s in suffixes for v in names] else: # No "var_array" keyword @@ -689,7 +689,7 @@ def PolynomialRing(base_ring, *args, **kwds): if n >= 0: raise TypeError("number of variables specified twice: %r and %r" % (n, arg)) if k < 0: - raise ValueError("number of variables must be non-negative") + raise ValueError("number of variables must be nonnegative") n = k # If number of variables was explicitly given, always # return a multivariate ring @@ -822,7 +822,7 @@ def _single_variate(base_ring, name, sparse=None, implementation=None, order=Non return R -def _multi_variate(base_ring, names, sparse=None, order="degrevlex", implementation=None): +def _multi_variate(base_ring, names, sparse=None, order='degrevlex', implementation=None): if sparse is None: sparse = True if not sparse: @@ -899,7 +899,7 @@ def polynomial_default_category(base_ring_category, n_variables): INPUT: - - ``base_ring_category`` -- The category of ring over which the polynomial + - ``base_ring_category`` -- the category of ring over which the polynomial ring shall be defined - ``n_variables`` -- number of variables @@ -947,7 +947,7 @@ def polynomial_default_category(base_ring_category, n_variables): return category -def BooleanPolynomialRing_constructor(n=None, names=None, order="lex"): +def BooleanPolynomialRing_constructor(n=None, names=None, order='lex'): """ Construct a boolean polynomial ring with the following parameters: diff --git a/src/sage/rings/polynomial/polynomial_ring_homomorphism.pyx b/src/sage/rings/polynomial/polynomial_ring_homomorphism.pyx index c2f0e900c2a..b3ce1183e5e 100644 --- a/src/sage/rings/polynomial/polynomial_ring_homomorphism.pyx +++ b/src/sage/rings/polynomial/polynomial_ring_homomorphism.pyx @@ -33,7 +33,6 @@ cdef class PolynomialRingHomomorphism_from_base(RingHomomorphism_from_base): Natural morphism: From: Integer Ring To: Rational Field - """ cpdef Element _call_(self, x): """ @@ -55,7 +54,6 @@ cdef class PolynomialRingHomomorphism_from_base(RingHomomorphism_from_base): sage: G = PolynomialRingHomomorphism_from_base(A.Hom(B), g) sage: G(A.gen()^1000000) 1.0...*x^1000000 - """ P = self.codomain() f = self.underlying_map() @@ -86,7 +84,6 @@ cdef class PolynomialRingHomomorphism_from_base(RingHomomorphism_from_base): sage: G = PolynomialRingHomomorphism_from_base(A.Hom(B), g) sage: G(A.gen()^1000000, True, construct=False) x^1000000 - """ P = self.codomain() f = self.underlying_map() @@ -105,7 +102,6 @@ cdef class PolynomialRingHomomorphism_from_base(RingHomomorphism_from_base): sage: S. = QQ[] sage: R.hom(S).is_injective() True - """ return self.underlying_map().is_injective() @@ -119,6 +115,5 @@ cdef class PolynomialRingHomomorphism_from_base(RingHomomorphism_from_base): sage: S. = Zmod(2)[] sage: R.hom(S).is_surjective() True - """ return self.underlying_map().is_surjective() diff --git a/src/sage/rings/polynomial/polynomial_singular_interface.py b/src/sage/rings/polynomial/polynomial_singular_interface.py index ee7c243087f..1bdca3af614 100644 --- a/src/sage/rings/polynomial/polynomial_singular_interface.py +++ b/src/sage/rings/polynomial/polynomial_singular_interface.py @@ -172,7 +172,7 @@ def _do_singular_init_(singular, base_ring, char, _vars, order): class PolynomialRing_singular_repr: """ - Implements methods to convert polynomial rings to Singular. + Implement methods to convert polynomial rings to Singular. This class is a base class for all univariate and multivariate polynomial rings which support conversion from and to Singular @@ -221,7 +221,7 @@ def _singular_(self, singular=None): // : names x // block 2 : ordering C - sage: R = PolynomialRing(GF(127), 'x', implementation="singular") # needs sage.libs.singular + sage: R = PolynomialRing(GF(127), 'x', implementation='singular') # needs sage.libs.singular sage: singular(R) # needs sage.libs.singular polynomial ring, over a field, global ordering // coefficients: ZZ/127 @@ -230,7 +230,7 @@ def _singular_(self, singular=None): // : names x // block 2 : ordering C - sage: R = PolynomialRing(QQ, 'x', implementation="singular") # needs sage.libs.singular + sage: R = PolynomialRing(QQ, 'x', implementation='singular') # needs sage.libs.singular sage: singular(R) # needs sage.libs.singular polynomial ring, over a field, global ordering // coefficients: QQ @@ -451,7 +451,7 @@ def can_convert_to_singular(R): class Polynomial_singular_repr: """ - Implements coercion of polynomials to Singular polynomials. + Implement coercion of polynomials to Singular polynomials. This class is a base class for all (univariate and multivariate) polynomial classes which support conversion from and to @@ -477,7 +477,7 @@ def _singular_func(self, singular=None): INPUT: - - ``singular`` -- Singular instance to use. + - ``singular`` -- Singular instance to use EXAMPLES:: diff --git a/src/sage/rings/polynomial/polynomial_template.pxi b/src/sage/rings/polynomial/polynomial_template.pxi index 31f2903f318..7d161504c54 100644 --- a/src/sage/rings/polynomial/polynomial_template.pxi +++ b/src/sage/rings/polynomial/polynomial_template.pxi @@ -75,7 +75,7 @@ cdef class Polynomial_template(Polynomial): We illustrate the generic glueing using univariate polynomials over `\mathop{\mathrm{GF}}(2)`. - .. note:: + .. NOTE:: Implementations using this template MUST implement coercion from base ring elements and :meth:`get_unsafe`. See @@ -340,7 +340,7 @@ cdef class Polynomial_template(Polynomial): @coerce_binop def gcd(self, Polynomial_template other): """ - Return the greatest common divisor of self and other. + Return the greatest common divisor of ``self`` and ``other``. EXAMPLES:: @@ -392,7 +392,7 @@ cdef class Polynomial_template(Polynomial): @coerce_binop def xgcd(self, Polynomial_template other): """ - Computes extended gcd of self and other. + Compute extended gcd of ``self`` and ``other``. EXAMPLES:: @@ -780,7 +780,7 @@ cdef class Polynomial_template(Polynomial): cpdef Polynomial truncate(self, long n): r""" - Returns this polynomial mod `x^n`. + Return this polynomial mod `x^n`. EXAMPLES:: @@ -816,7 +816,7 @@ cdef class Polynomial_template(Polynomial): def _singular_(self, singular=None): r""" - Return Singular representation of this polynomial + Return Singular representation of this polynomial. INPUT: diff --git a/src/sage/rings/polynomial/polynomial_zmod_flint.pyx b/src/sage/rings/polynomial/polynomial_zmod_flint.pyx index 8c68cabe038..80063d7462c 100644 --- a/src/sage/rings/polynomial/polynomial_zmod_flint.pyx +++ b/src/sage/rings/polynomial/polynomial_zmod_flint.pyx @@ -140,7 +140,7 @@ cdef class Polynomial_zmod_flint(Polynomial_template): cpdef Polynomial _new_constant_poly(self, x, Parent P): r""" - Quickly creates a new constant polynomial with value x in parent P. + Quickly create a new constant polynomial with value x in parent P. ASSUMPTION: @@ -160,7 +160,6 @@ cdef class Polynomial_zmod_flint(Polynomial_template): Traceback (most recent call last): ... ValueError: invalid literal for int() with base 10: '4.1' - """ cdef type t = type(self) cdef Polynomial_template r = t.__new__(t) @@ -176,9 +175,8 @@ cdef class Polynomial_zmod_flint(Polynomial_template): INPUT: - - ``x`` -- a list of coefficients; the coefficients are assumed to be - reduced already and the list contains no trailing zeroes. - + - ``x`` -- list of coefficients; the coefficients are assumed to be + reduced already and the list contains no trailing zeroes EXAMPLES:: @@ -238,7 +236,6 @@ cdef class Polynomial_zmod_flint(Polynomial_template): (99998, 1) sage: p[d], p[v] (2, 1) - """ sig_on() fmpz_poly_get_nmod_poly(&self.x, x) @@ -275,11 +272,11 @@ cdef class Polynomial_zmod_flint(Polynomial_template): INPUT: **either** - - a -- ring element; need not be in the coefficient ring of the - polynomial. - - a dictionary for kwds:value pairs. If the variable name of the - polynomial is a keyword it is substituted in; otherwise this - polynomial is returned unchanged. + - ``a`` -- ring element; need not be in the coefficient ring of the + polynomial + - a dictionary for kwds:value pairs; if the variable name of the + polynomial is a keyword it is substituted in, otherwise this + polynomial is returned unchanged EXAMPLES:: @@ -422,7 +419,6 @@ cdef class Polynomial_zmod_flint(Polynomial_template): multiplication and then truncating. The function is tuned for length `n` about half the length of a full product. - EXAMPLES:: sage: P. = GF(7)[] @@ -724,7 +720,6 @@ cdef class Polynomial_zmod_flint(Polynomial_template): True sage: s.is_irreducible.cache True - """ if not self: return False @@ -808,7 +803,6 @@ cdef class Polynomial_zmod_flint(Polynomial_template): Traceback (most recent call last): ... AlarmInterrupt - """ R = self.base_ring() @@ -830,7 +824,7 @@ cdef class Polynomial_zmod_flint(Polynomial_template): """ Return this polynomial divided by its leading coefficient. - Raises :class:`ValueError` if the leading coefficient is not invertible in the + Raises :exc:`ValueError` if the leading coefficient is not invertible in the base ring. EXAMPLES:: @@ -910,7 +904,7 @@ cdef class Polynomial_zmod_flint(Polynomial_template): sage: p.reverse(degree=1.5r) Traceback (most recent call last): ... - ValueError: degree argument must be a non-negative integer, got 1.5 + ValueError: degree argument must be a nonnegative integer, got 1.5 Check that this implementation is compatible with the generic one:: @@ -923,10 +917,10 @@ cdef class Polynomial_zmod_flint(Polynomial_template): cdef unsigned long d if degree is not None: if degree < 0: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) d = degree if d != degree: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) nmod_poly_reverse(&res.x, &self.x, d+1) # FLINT expects length else: nmod_poly_reverse(&res.x, &self.x, nmod_poly_length(&self.x)) @@ -946,7 +940,7 @@ cdef class Polynomial_zmod_flint(Polynomial_template): sage: f.revert_series(-1) Traceback (most recent call last): ... - ValueError: argument n must be a non-negative integer, got -1 + ValueError: argument n must be a nonnegative integer, got -1 sage: g = - t^3 + t^5 sage: g.revert_series(6) @@ -963,7 +957,7 @@ cdef class Polynomial_zmod_flint(Polynomial_template): cdef Polynomial_zmod_flint res = self._new() cdef unsigned long m if n < 0: - raise ValueError("argument n must be a non-negative integer, got {}".format(n)) + raise ValueError("argument n must be a nonnegative integer, got {}".format(n)) m = n if not self[0].is_zero() or not self[1].is_unit(): raise ValueError("self must have constant coefficient 0 and a unit for coefficient {}^1".format(self.parent().gen())) diff --git a/src/sage/rings/polynomial/polynomial_zz_pex.pyx b/src/sage/rings/polynomial/polynomial_zz_pex.pyx index f38f80ee49b..48544dbbe20 100644 --- a/src/sage/rings/polynomial/polynomial_zz_pex.pyx +++ b/src/sage/rings/polynomial/polynomial_zz_pex.pyx @@ -256,7 +256,6 @@ cdef class Polynomial_ZZ_pEX(Polynomial_template): ....: P = PolynomialRing(F, 'x') ....: f = P.random_element(8) ....: assert f(b) == sum(c * b^i for i, c in enumerate(f)) - """ cdef ntl_ZZ_pE _a cdef ZZ_pE_c c_b @@ -318,17 +317,17 @@ cdef class Polynomial_ZZ_pEX(Polynomial_template): K = self._parent.base_ring() return K(K.polynomial_ring()(ZZ_pE_c_to_list(r))) - def is_irreducible(self, algorithm="fast_when_false", iter=1): + def is_irreducible(self, algorithm='fast_when_false', iter=1): r""" Return ``True`` precisely when ``self`` is irreducible over its base ring. INPUT: - - ``algorithm`` -- a string (default ``"fast_when_false"``), + - ``algorithm`` -- string (default: ``'fast_when_false'``); there are 3 available algorithms: - ``"fast_when_true"``, ``"fast_when_false"``, and ``"probabilistic".`` + ``'fast_when_true'``, ``'fast_when_false'``, and ``'probabilistic'`` - - ``iter`` -- (default: 1) if the algorithm is ``"probabilistic"``, + - ``iter`` -- (default: 1) if the algorithm is ``'probabilistic'``, defines the number of iterations. The error probability is bounded by `q^{\text{-iter}}` for polynomials in `\GF{q}[x]`. @@ -337,18 +336,18 @@ cdef class Polynomial_ZZ_pEX(Polynomial_template): sage: K. = GF(next_prime(2**60)**3) sage: R. = PolynomialRing(K, implementation='NTL') sage: P = x^3 + (2-a)*x + 1 - sage: P.is_irreducible(algorithm="fast_when_false") + sage: P.is_irreducible(algorithm='fast_when_false') True - sage: P.is_irreducible(algorithm="fast_when_true") + sage: P.is_irreducible(algorithm='fast_when_true') True - sage: P.is_irreducible(algorithm="probabilistic") + sage: P.is_irreducible(algorithm='probabilistic') True sage: Q = (x^2+a)*(x+a^3) - sage: Q.is_irreducible(algorithm="fast_when_false") + sage: Q.is_irreducible(algorithm='fast_when_false') False - sage: Q.is_irreducible(algorithm="fast_when_true") + sage: Q.is_irreducible(algorithm='fast_when_true') False - sage: Q.is_irreducible(algorithm="probabilistic") + sage: Q.is_irreducible(algorithm='probabilistic') False """ self._parent._modulus.restore() @@ -519,7 +518,7 @@ cdef class Polynomial_ZZ_pEX(Polynomial_template): sage: f.reverse(degree=-5) Traceback (most recent call last): ... - ValueError: degree argument must be a non-negative integer, got -5 + ValueError: degree argument must be a nonnegative integer, got -5 Check that this implementation is compatible with the generic one:: @@ -541,10 +540,10 @@ cdef class Polynomial_ZZ_pEX(Polynomial_template): cdef unsigned long d if degree is not None: if degree < 0: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) d = degree if d != degree: - raise ValueError("degree argument must be a non-negative integer, got %s" % (degree)) + raise ValueError("degree argument must be a nonnegative integer, got %s" % (degree)) ZZ_pEX_reverse_hi(r.x, ( self).x, d) else: ZZ_pEX_reverse(r.x, ( self).x) @@ -596,7 +595,7 @@ cdef class Polynomial_ZZ_pEX(Polynomial_template): """ self._parent._modulus.restore() - # Ensure precision is non-negative + # Ensure precision is nonnegative if prec <= 0: raise ValueError("the precision must be positive, got {}".format(prec)) diff --git a/src/sage/rings/polynomial/real_roots.pyx b/src/sage/rings/polynomial/real_roots.pyx index 99587194f5f..a91a95a1d55 100644 --- a/src/sage/rings/polynomial/real_roots.pyx +++ b/src/sage/rings/polynomial/real_roots.pyx @@ -322,15 +322,15 @@ cdef class interval_bernstein_polynomial: cdef void update_variations(self, interval_bernstein_polynomial bp1, interval_bernstein_polynomial bp2) noexcept: """ - Update the max_variations of bp1 and bp2 (which are assumed to be - the result of splitting this polynomial). + Update the max_variations of ``bp1`` and ``bp2`` (which are assumed to + be the result of splitting this polynomial). - If we knew the number of variations of self, bp1, and bp2 exactly, - we would have - self.variations == bp1.variations + bp2.variations + 2*n + If we knew the number of variations of ``self``, ``bp1``, and ``bp2`` + exactly, we would have + ``self.variations == bp1.variations + bp2.variations + 2*n`` for some nonnegative integer n. Thus, we can use our information - on min and max variations on self and bp1 (or bp2) to refine the range - on bp2 (or bp1). + on min and max variations on ``self`` and ``bp1`` (or ``bp2``) to + refine the range on ``bp2`` (or ``bp1``). """ if self.max_variations - bp1.min_variations < bp2.max_variations: bp2.max_variations = self.max_variations - bp1.min_variations @@ -697,7 +697,8 @@ cdef class interval_bernstein_polynomial_integer(interval_bernstein_polynomial): OUTPUT: - ``bp1``, ``bp2`` -- the new interval Bernstein polynomials - - ``ok`` -- a boolean; True if the sign of the original polynomial at mid is known + - ``ok`` -- boolean; ``True`` if the sign of the original polynomial at + mid is known EXAMPLES:: @@ -1488,7 +1489,6 @@ cdef class interval_bernstein_polynomial_float(interval_bernstein_polynomial): with intervals, not exactly, we cannot necessarily compute the exact number of sign variations; instead, we compute lower and upper bounds on this number. - """ cdef numpy.ndarray[double, ndim=1] cd = self.coeffs._vector_numpy @@ -1572,7 +1572,8 @@ cdef class interval_bernstein_polynomial_float(interval_bernstein_polynomial): OUTPUT: - ``bp1``, ``bp2`` -- the new interval Bernstein polynomials - - ``ok`` -- a boolean; ``True`` if the sign of the original polynomial at ``mid`` is known + - ``ok`` -- boolean; ``True`` if the sign of the original polynomial at + ``mid`` is known EXAMPLES:: @@ -1970,7 +1971,7 @@ def bitsize_doctest(n): def degree_reduction_next_size(n): """ - Given n (a polynomial degree), returns either a smaller integer or None. + Given n (a polynomial degree), returns either a smaller integer or ``None``. This defines the sequence of degrees followed by our degree reduction implementation. @@ -2575,7 +2576,7 @@ class bernstein_polynomial_factory_intlist(bernstein_polynomial_factory): def __init__(self, coeffs): """ - Initializes a bernstein_polynomial_factory_intlist, + Initialize a ``bernstein_polynomial_factory_intlist``, given a list of integer coefficients. EXAMPLES:: @@ -2601,7 +2602,7 @@ class bernstein_polynomial_factory_intlist(bernstein_polynomial_factory): def coeffs_bitsize(self): """ - Computes the approximate log2 of the maximum of the absolute + Compute the approximate log2 of the maximum of the absolute values of the coefficients. EXAMPLES:: @@ -2654,7 +2655,7 @@ class bernstein_polynomial_factory_ratlist(bernstein_polynomial_factory): def __init__(self, coeffs): """ - Initializes a bernstein_polynomial_factory_intlist, + Initialize a ``bernstein_polynomial_factory_intlist``, given a list of rational coefficients. EXAMPLES:: @@ -2680,7 +2681,7 @@ class bernstein_polynomial_factory_ratlist(bernstein_polynomial_factory): def coeffs_bitsize(self): """ - Computes the approximate log2 of the maximum of the absolute + Compute the approximate log2 of the maximum of the absolute values of the coefficients. EXAMPLES:: @@ -2740,7 +2741,7 @@ class bernstein_polynomial_factory_ar(bernstein_polynomial_factory): def __init__(self, poly, neg): """ - Initializes a bernstein_polynomial_factory_ar, + Initialize a ``bernstein_polynomial_factory_ar``, given a polynomial with algebraic real coefficients. If neg is True, then gives the Bernstein polynomial for the negative half-line; if neg is False, the positive. @@ -2785,7 +2786,7 @@ class bernstein_polynomial_factory_ar(bernstein_polynomial_factory): def coeffs_bitsize(self): """ - Computes the approximate log2 of the maximum of the absolute + Compute the approximate log2 of the maximum of the absolute values of the coefficients. EXAMPLES:: @@ -3567,7 +3568,7 @@ cdef class island: def less_bits(self, ancestors, interval_bernstein_polynomial bp): """ - Heuristically pushes lower-precision polynomials on + Heuristically push lower-precision polynomials on the polynomial stack. See the class documentation for class island for more information. """ @@ -4558,7 +4559,7 @@ def max_bitsize_intvec_doctest(b): def dprod_imatrow_vec(Matrix_integer_dense m, Vector_integer_dense v, int k): """ - Computes the dot product of row k of the matrix m with the vector v + Compute the dot product of row k of the matrix m with the vector v (that is, compute one element of the product m*v). If v has more elements than m has columns, then elements of v are diff --git a/src/sage/rings/polynomial/refine_root.pyx b/src/sage/rings/polynomial/refine_root.pyx index 32a9ce8c8e4..1d6eb6bb146 100644 --- a/src/sage/rings/polynomial/refine_root.pyx +++ b/src/sage/rings/polynomial/refine_root.pyx @@ -75,7 +75,7 @@ def refine_root(ip, ipd, irt, fld): # unless either the real or imaginary component of the root is zero. # If the real or imaginary component is zero, then we could spend # a long time computing closer and closer approximations to that - # component. (This doesn't happen for non-zero components, because + # component. (This doesn't happen for nonzero components, because # of the imprecision of floating-point numbers combined with the # outward interval rounding; but close to zero, MPFI provides # extremely precise numbers.) diff --git a/src/sage/rings/polynomial/skew_polynomial_element.pyx b/src/sage/rings/polynomial/skew_polynomial_element.pyx index cf5fd9bd090..70bc7f5b448 100644 --- a/src/sage/rings/polynomial/skew_polynomial_element.pyx +++ b/src/sage/rings/polynomial/skew_polynomial_element.pyx @@ -134,7 +134,7 @@ cdef class SkewPolynomial_generic_dense(OrePolynomial_generic_dense): INPUT: - - ``exp`` -- an integer + - ``exp`` -- integer - ``modulus`` -- a skew polynomial in the same ring as ``self`` @@ -276,9 +276,7 @@ cdef class SkewPolynomial_generic_dense(OrePolynomial_generic_dense): - ``eval_pt`` -- element of the base ring of ``self`` - OUTPUT: - - The operator evaluation of ``self`` at ``eval_pt``. + OUTPUT: the operator evaluation of ``self`` at ``eval_pt`` .. TODO:: @@ -339,9 +337,7 @@ cdef class SkewPolynomial_generic_dense(OrePolynomial_generic_dense): - ``eval_pt`` -- element of the base ring of ``self`` - OUTPUT: - - The value of the polynomial at the point specified by the argument. + OUTPUT: the value of the polynomial at the point specified by the argument EXAMPLES:: @@ -388,7 +384,7 @@ cdef class SkewPolynomial_generic_dense(OrePolynomial_generic_dense): INPUT: - - `n` -- an integer, the power of conjugation + - ``n`` -- integer; the power of conjugation EXAMPLES:: @@ -434,9 +430,7 @@ cdef class SkewPolynomial_generic_dense(OrePolynomial_generic_dense): - ``eval_pts`` -- list of points at which ``self`` is to be evaluated - OUTPUT: - - List of values of ``self`` at the ``eval_pts``. + OUTPUT: list of values of ``self`` at the ``eval_pts`` .. TODO:: diff --git a/src/sage/rings/polynomial/skew_polynomial_finite_field.pyx b/src/sage/rings/polynomial/skew_polynomial_finite_field.pyx index b9538d07263..a901022b308 100644 --- a/src/sage/rings/polynomial/skew_polynomial_finite_field.pyx +++ b/src/sage/rings/polynomial/skew_polynomial_finite_field.pyx @@ -369,7 +369,7 @@ cdef class SkewPolynomial_finite_field_dense(SkewPolynomial_finite_order_dense): INPUT: - - ``right`` -- a boolean; if ``True``, return right divisors, + - ``right`` -- boolean; if ``True``, return right divisors, otherwise, return left divisors TESTS:: @@ -476,7 +476,7 @@ cdef class SkewPolynomial_finite_field_dense(SkewPolynomial_finite_order_dense): INPUT: - - ``uniform`` -- a boolean (default: ``False``); whether the + - ``uniform`` -- boolean (default: ``False``); whether the output irreducible divisor should be uniformly distributed among all possibilities @@ -551,7 +551,7 @@ cdef class SkewPolynomial_finite_field_dense(SkewPolynomial_finite_order_dense): INPUT: - - ``uniform`` -- a boolean (default: ``False``); whether the + - ``uniform`` -- boolean (default: ``False``); whether the output irreducible divisor should be uniformly distributed among all possibilities @@ -933,7 +933,7 @@ cdef class SkewPolynomial_finite_field_dense(SkewPolynomial_finite_order_dense): INPUT: - - ``uniform`` -- a boolean (default: ``False``); whether the + - ``uniform`` -- boolean (default: ``False``); whether the output irreducible divisor should be uniformly distributed among all possibilities diff --git a/src/sage/rings/polynomial/skew_polynomial_finite_order.pyx b/src/sage/rings/polynomial/skew_polynomial_finite_order.pyx index fcda4420378..0abdfca57bc 100644 --- a/src/sage/rings/polynomial/skew_polynomial_finite_order.pyx +++ b/src/sage/rings/polynomial/skew_polynomial_finite_order.pyx @@ -157,8 +157,8 @@ cdef class SkewPolynomial_finite_order_dense(SkewPolynomial_generic_dense): INPUT: - - ``var`` -- a string or ``False`` or ``None`` (default: ``None``); - the variable name; if ``False``, return the list of coefficients + - ``var`` -- string or ``False`` or ``None`` (default: ``None``); + the variable name. If ``False``, return the list of coefficients. EXAMPLES:: @@ -228,8 +228,8 @@ cdef class SkewPolynomial_finite_order_dense(SkewPolynomial_generic_dense): INPUT: - - ``var`` -- a string or ``False`` or ``None`` (default: ``None``); - the variable name; if ``False``, return the list of coefficients + - ``var`` -- string or ``False`` or ``None`` (default: ``None``); + the variable name. If ``False``, return the list of coefficients. .. NOTE:: @@ -341,7 +341,7 @@ cdef class SkewPolynomial_finite_order_dense(SkewPolynomial_generic_dense): INPUT: - - ``var`` -- a string, a pair of strings or ``None`` + - ``var`` -- string, a pair of strings or ``None`` (default: ``None``); the variable names used for the characteristic polynomial and the center @@ -449,7 +449,7 @@ cdef class SkewPolynomial_finite_order_dense(SkewPolynomial_generic_dense): ALGORITHM: - #. Sage first checks whether ``self`` is itself in the + #. Sage first checks whether self is itself in the center. It if is, it returns ``self`` #. If an optimal bound was previously computed and diff --git a/src/sage/rings/polynomial/skew_polynomial_ring.py b/src/sage/rings/polynomial/skew_polynomial_ring.py index db5285ff66f..6feadce07b1 100644 --- a/src/sage/rings/polynomial/skew_polynomial_ring.py +++ b/src/sage/rings/polynomial/skew_polynomial_ring.py @@ -106,11 +106,9 @@ def _minimal_vanishing_polynomial(R, eval_pts): - ``R`` -- a skew polynomial ring over a field - - ``eval_pts`` -- a list of evaluation points - - OUTPUT: + - ``eval_pts`` -- list of evaluation points - The minimal vanishing polynomial. + OUTPUT: the minimal vanishing polynomial EXAMPLES:: @@ -164,9 +162,7 @@ def _lagrange_polynomial(R, eval_pts, values): - ``values`` -- list of values that the Lagrange polynomial takes at the respective ``eval_pts`` - OUTPUT: - - - the Lagrange polynomial + OUTPUT: the Lagrange polynomial EXAMPLES:: @@ -269,9 +265,7 @@ def minimal_vanishing_polynomial(self, eval_pts): independent over the fixed field of the twisting morphism of the associated skew polynomial ring - OUTPUT: - - The minimal vanishing polynomial. + OUTPUT: the minimal vanishing polynomial EXAMPLES:: @@ -319,13 +313,11 @@ def lagrange_polynomial(self, points): INPUT: - - ``points`` -- a list of pairs `(x_1, y_1), \ldots, (x_n, y_n)` of + - ``points`` -- list of pairs `(x_1, y_1), \ldots, (x_n, y_n)` of elements of the base ring of ``self``; the `x_i` should be linearly independent over the fixed field of ``self.twisting_morphism()`` - OUTPUT: - - The Lagrange polynomial. + OUTPUT: the Lagrange polynomial EXAMPLES:: @@ -366,7 +358,7 @@ def lagrange_polynomial(self, points): raise TypeError("the evaluation points must be distinct") zero_i = [i for i in range(l) if eval_pts[i].is_zero()] if zero_i and not values[zero_i[0]].is_zero(): - raise TypeError("a skew polynomial always evaluates to 0 at 0, but a non-zero value was requested") + raise TypeError("a skew polynomial always evaluates to 0 at 0, but a nonzero value was requested") return _lagrange_polynomial(_base_ring_to_fraction_field(self), eval_pts, values) @@ -640,10 +632,10 @@ def center(self, name=None, names=None, default=False): INPUT: - - ``name`` -- a string or ``None`` (default: ``None``); + - ``name`` -- string or ``None`` (default: ``None``); the name for the central variable (namely `x^r`) - - ``default`` -- a boolean (default: ``False``); if ``True``, + - ``default`` -- boolean (default: ``False``); if ``True``, set the default variable name for the center to ``name`` EXAMPLES:: @@ -877,7 +869,7 @@ def _retraction(self, x, newmap=False, seed=None): INPUT: - - ``newmap`` -- a boolean (default: ``False``); whether we + - ``newmap`` -- boolean (default: ``False``); whether we first create and use a new retraction map - ``seed`` -- an element of the base ring or ``None`` (default: diff --git a/src/sage/rings/polynomial/symmetric_ideal.py b/src/sage/rings/polynomial/symmetric_ideal.py index 660e9f9fe4b..869af07d904 100644 --- a/src/sage/rings/polynomial/symmetric_ideal.py +++ b/src/sage/rings/polynomial/symmetric_ideal.py @@ -67,7 +67,8 @@ class SymmetricIdeal(Ideal_generic): r""" - Ideal in an Infinite Polynomial Ring, invariant under permutation of variable indices + Ideal in an Infinite Polynomial Ring, invariant under permutation of + variable indices. THEORY: @@ -176,7 +177,6 @@ class SymmetricIdeal(Ideal_generic): Infinite polynomial ring in x, y over Rational Field sage: I * I == X * (x[1]^2) # needs sage.combinat False - """ def __init__(self, ring, gens, coerce=True): @@ -185,7 +185,8 @@ def __init__(self, ring, gens, coerce=True): - ``ring`` -- an infinite polynomial ring - ``gens`` -- generators of this ideal - - ``coerce`` -- (bool, default ``True``) coerce the given generators into ``ring`` + - ``coerce`` -- boolean (default ``True``); coerce the given generators + into ``ring`` EXAMPLES:: @@ -197,7 +198,6 @@ def __init__(self, ring, gens, coerce=True): sage: J = SymmetricIdeal(X, [x[1]^2 + y[2]^2, x[1]*x[2]*y[3] + x[1]*y[4]]) sage: I == J True - """ Ideal_generic.__init__(self, ring, gens, coerce=coerce) @@ -209,7 +209,6 @@ def __repr__(self): sage: I = X * (x[1]^2 + y[2]^2, x[1]*x[2]*y[3] + x[1]*y[4]) sage: I # indirect doctest Symmetric Ideal (x_1^2 + y_2^2, x_2*x_1*y_3 + x_1*y_4) of Infinite polynomial ring in x, y over Rational Field - """ return f"Symmetric Ideal {self._repr_short()} of {self.ring()}" @@ -222,7 +221,6 @@ def _latex_(self): sage: I = X * (x[1]*y[2]) sage: latex(I) # indirect doctest \left(x_{1} y_{2}\right)\Bold{Q}[x_{\ast}, y_{\ast}][\mathfrak{S}_{\infty}] - """ from sage.misc.latex import latex return r'\left({}\right){}[\mathfrak{{S}}_{{\infty}}]'.format(", ".join(latex(g) for g in self.gens()), latex(self.ring())) @@ -305,7 +303,6 @@ def __pow__(self, n): sage: I = X * (x[1]) sage: I^2 # indirect doctest # needs sage.combinat Symmetric Ideal (x_1^2, x_2*x_1) of Infinite polynomial ring in x over Rational Field - """ OUT = SymmetricIdeal(self.ring(), [1]) for i in range(n): @@ -324,7 +321,7 @@ def is_maximal(self): It is not checked whether ``self`` is in fact a symmetric Groebner basis. A wrong answer can result if this assumption does not - hold. A :class:`NotImplementedError` is raised if the base ring is not + hold. A :exc:`NotImplementedError` is raised if the base ring is not a field, since symmetric Groebner bases are not implemented in this setting. @@ -347,7 +344,6 @@ def is_maximal(self): Infinite polynomial ring in x, y over Rational Field sage: I.is_maximal() # needs sage.combinat True - """ if not self.base_ring().is_field(): raise NotImplementedError @@ -366,13 +362,11 @@ def reduce(self, I, tailreduce=False): INPUT: - ``I`` -- an Infinite Polynomial, or a Symmetric Ideal or a - list of Infinite Polynomials. - - ``tailreduce`` -- (bool, default ``False``) If ``True``, the - non-leading terms will be reduced as well. - - OUTPUT: + list of Infinite Polynomials + - ``tailreduce`` -- boolean (default ``False``); if ``True``, the + non-leading terms will be reduced as well - Symmetric reduction of ``self`` with respect to ``I``. + OUTPUT: symmetric reduction of ``self`` with respect to ``I`` THEORY: @@ -415,7 +409,6 @@ def reduce(self, I, tailreduce=False): sage: I.reduce(J, tailreduce=True) # needs sage.combinat Symmetric Ideal (x_3^2*y_1) of Infinite polynomial ring in x, y over Rational Field - """ if I in self.ring(): # we want to reduce a polynomial by self return self.ring()(I).reduce(self) @@ -435,11 +428,11 @@ def interreduction(self, tailreduce=True, sorted=False, report=None, RStrat=None INPUT: - - ``tailreduce`` -- (bool, default ``True``) If ``True``, the + - ``tailreduce`` -- boolean (default: ``True``); if ``True``, the interreduction is also performed on the non-leading monomials. - - ``sorted`` -- (bool, default ``False``) If ``True``, it is assumed that the + - ``sorted`` -- boolean (default: ``False``); if ``True``, it is assumed that the generators of ``self`` are already increasingly sorted. - - ``report`` -- (object, default ``None``) If not ``None``, some information on the + - ``report`` -- object (default ``None``); if not ``None``, some information on the progress of computation is printed - ``RStrat`` -- (:class:`~sage.rings.polynomial.symmetric_reduction.SymmetricReductionStrategy`, default ``None``) A reduction strategy to which the polynomials resulting @@ -497,7 +490,6 @@ def interreduction(self, tailreduce=True, sorted=False, report=None, RStrat=None sage: R = SymmetricReductionStrategy(X, [x[1]^2]) sage: I.interreduction(RStrat=R) # needs sage.combinat Symmetric Ideal (x_2 + x_1) of Infinite polynomial ring in x over Rational Field - """ DONE = [] TODO = [] @@ -566,7 +558,8 @@ def interreduction(self, tailreduce=True, sorted=False, report=None, RStrat=None def interreduced_basis(self): """ - A fully symmetrically reduced generating set (type :class:`~sage.structure.sequence.Sequence`) of self. + A fully symmetrically reduced generating set (type + :class:`~sage.structure.sequence.Sequence`) of ``self``. This does essentially the same as :meth:`interreduction` with the option 'tailreduce', but it returns a @@ -579,7 +572,6 @@ def interreduced_basis(self): sage: I = X * (x[1] + x[2], x[1]*x[2]) sage: I.interreduced_basis() # needs sage.combinat [-x_1^2, x_2 + x_1] - """ return Sequence(self.interreduction(tailreduce=True).gens(), self.ring(), check=False) @@ -589,15 +581,15 @@ def symmetrisation(self, N=None, tailreduce=False, report=None, use_full_group=F INPUT: - - ``N`` -- (integer, default ``None``) Apply permutations in + - ``N`` -- integer (default: ``None``); apply permutations in `Sym(N)`. If it is not given then it will be replaced by the maximal variable index occurring in the generators of ``self.interreduction().squeezed()``. - - ``tailreduce`` -- (bool, default ``False``) If ``True``, perform + - ``tailreduce`` -- boolean (default: ``False``); if ``True``, perform tail reductions. - - ``report`` -- (object, default ``None``) If not ``None``, report + - ``report`` -- object (default ``None``); if not ``None``, report on the progress of computations. - - ``use_full_group`` (optional) -- If ``True``, apply *all* elements of + - ``use_full_group`` -- (optional) if ``True``, apply *all* elements of `Sym(N)` to the generators of ``self`` (this is what [AB2008]_ originally suggests). The default is to apply all elementary transpositions to the generators of ``self.squeezed()``, @@ -631,7 +623,6 @@ def symmetrisation(self, N=None, tailreduce=False, report=None, use_full_group=F Symmetric Ideal (-2*x_1) of Infinite polynomial ring in x over Rational Field sage: I.symmetrisation(N=3, use_full_group=True) # needs sage.combinat Symmetric Ideal (-2*x_1) of Infinite polynomial ring in x over Rational Field - """ newOUT = self.interreduction(tailreduce=tailreduce, report=report).squeezed() R = self.ring() @@ -688,7 +679,6 @@ def symmetric_basis(self): sage: I = X * (x[1] + x[2], x[1]*x[2]) sage: I.symmetric_basis() # needs sage.combinat [x_1^2, x_2 + x_1] - """ return Sequence(self.symmetrisation(tailreduce=True).normalisation().gens(), self.ring(), check=False) @@ -705,7 +695,6 @@ def normalisation(self): sage: I.normalisation() Symmetric Ideal (x_2 + 3/4*x_1, x_2*x_1) of Infinite polynomial ring in x over Rational Field - """ return SymmetricIdeal(self.ring(), [X / X.lc() for X in self.gens() if X._p != 0]) @@ -730,7 +719,6 @@ def squeezed(self): sage: I.squeezed() Symmetric Ideal (x_2*y_1, x_1*y_2) of Infinite polynomial ring in x, y over Rational Field - """ return SymmetricIdeal(self.ring(), [X.squeezed() for X in self.gens()]) @@ -741,15 +729,15 @@ def groebner_basis(self, tailreduce=False, reduced=True, algorithm=None, report= INPUT: - - ``tailreduce`` -- (bool, default ``False``) If ``True``, use tail reduction + - ``tailreduce`` -- boolean (default: ``False``); if ``True``, use tail reduction in intermediate computations - - ``reduced`` -- (bool, default ``True``) If ``True``, return the reduced normalised - symmetric Groebner basis. - - ``algorithm`` -- (string, default ``None``) Determine the algorithm (see below for - available algorithms). - - ``report`` -- (object, default ``None``) If not ``None``, print information on the - progress of computation. - - ``use_full_group`` -- (bool, default ``False``) If ``True`` then proceed as + - ``reduced`` -- boolean (default: ``True``); if ``True``, return the reduced normalised + symmetric Groebner basis + - ``algorithm`` -- string (default: ``None``); determine the algorithm (see below for + available algorithms) + - ``report`` -- object (default ``None``); if not ``None``, print information on the + progress of computation + - ``use_full_group`` -- boolean (default: ``False``); if ``True`` then proceed as originally suggested by [AB2008]_. Our default method should be faster; see :meth:`symmetrisation` for more details. @@ -802,7 +790,7 @@ def groebner_basis(self, tailreduce=False, reduced=True, algorithm=None, report= If only a system is given - e.g. 'magma' - the default algorithm is chosen for that system. - .. note:: + .. NOTE:: The Singular and libSingular versions of the respective algorithms are identical, but the former calls an external @@ -900,7 +888,7 @@ def groebner_basis(self, tailreduce=False, reduced=True, algorithm=None, report= [x_1] The Aschenbrenner-Hillar algorithm is only guaranteed to work - if the base ring is a field. So, we raise a :class:`TypeError` if this + if the base ring is a field. So, we raise a :exc:`TypeError` if this is not the case:: sage: R. = InfinitePolynomialRing(ZZ) diff --git a/src/sage/rings/polynomial/symmetric_reduction.pyx b/src/sage/rings/polynomial/symmetric_reduction.pyx index 98305d20769..0794ca8a941 100644 --- a/src/sage/rings/polynomial/symmetric_reduction.pyx +++ b/src/sage/rings/polynomial/symmetric_reduction.pyx @@ -131,12 +131,12 @@ cdef class SymmetricReductionStrategy: INPUT: - ``Parent`` -- an Infinite Polynomial Ring, see - :mod:`~sage.rings.polynomial.infinite_polynomial_element`. - - ``L`` -- (list, default the empty list) List of elements of ``Parent`` - with respect to which will be reduced. - - ``good_input`` -- (bool, default ``None``) If this optional parameter + :mod:`~sage.rings.polynomial.infinite_polynomial_element` + - ``L`` -- list (default: the empty list); list of elements of ``Parent`` + with respect to which will be reduced + - ``good_input`` -- boolean (default: ``None``); if this optional parameter is true, it is assumed that each element of ``L`` is symmetrically - reduced with respect to the previous elements of ``L``. + reduced with respect to the previous elements of ``L`` EXAMPLES:: @@ -147,7 +147,6 @@ cdef class SymmetricReductionStrategy: y_3 + 3*y_2^2*y_1 + 2*y_2*y_1^2 sage: S.tailreduce(y[3] + 2*y[2]*y[1]^2 + 3*y[2]^2*y[1]) # needs sage.combinat y_3 - """ def __init__(self, Parent, L=None, tailreduce=False, good_input=None): """ @@ -158,7 +157,6 @@ cdef class SymmetricReductionStrategy: sage: S = SymmetricReductionStrategy(X, [y[2]^2*y[1],y[1]^2*y[2]], good_input=True) sage: S == loads(dumps(S)) True - """ self._parent = Parent if hasattr(Parent, '_P'): @@ -258,7 +256,7 @@ cdef class SymmetricReductionStrategy: def gens(self): """ - Return the list of Infinite Polynomials modulo which self reduces. + Return the list of Infinite Polynomials modulo which ``self`` reduces. EXAMPLES:: @@ -272,22 +270,21 @@ cdef class SymmetricReductionStrategy: y_2^2*y_1 sage: S.gens() [y_2*y_1^2, y_2^2*y_1] - """ return self._lm def setgens(self, L): """ - Define the list of Infinite Polynomials modulo which self reduces. + Define the list of Infinite Polynomials modulo which ``self`` reduces. INPUT: - - ``L`` -- a list of elements of the underlying infinite polynomial ring. + - ``L`` -- list of elements of the underlying infinite polynomial ring .. NOTE:: It is not tested if ``L`` is a good input. That method simply - assigns a *copy* of ``L`` to the generators of self. + assigns a *copy* of ``L`` to the generators of ``self``. EXAMPLES:: @@ -305,7 +302,6 @@ cdef class SymmetricReductionStrategy: False sage: R.gens() == S.gens() True - """ self._lm = [X for X in L] @@ -326,7 +322,6 @@ cdef class SymmetricReductionStrategy: sage: S.reset() sage: S Symmetric Reduction Strategy in Infinite polynomial ring in y over Rational Field - """ self._lm = [] self._lengths = [] @@ -346,7 +341,6 @@ cdef class SymmetricReductionStrategy: y_2*y_1^2, y_2^2*y_1 with tailreduction - """ s = "Symmetric Reduction Strategy in %s" % self._parent if self._lm: @@ -359,11 +353,10 @@ cdef class SymmetricReductionStrategy: """ INPUT: - A polynomial or an infinite polynomial + A polynomial or an infinite polynomial. - OUTPUT: - - A polynomial whose parent ring allows for coercion of any generator of self + OUTPUT: a polynomial whose parent ring allows for coercion of any + generator of ``self`` EXAMPLES:: @@ -379,7 +372,6 @@ cdef class SymmetricReductionStrategy: True sage: S(p) == S(p._p) True - """ if hasattr(p, '_p'): p = p._p @@ -412,8 +404,8 @@ cdef class SymmetricReductionStrategy: INPUT: - - ``p`` -- An element of the underlying infinite polynomial ring. - - ``good_input`` -- (bool, default ``None``) If ``True``, it is + - ``p`` -- an element of the underlying infinite polynomial ring + - ``good_input`` -- boolean (default: ``None``); if ``True``, it is assumed that ``p`` is reduced with respect to ``self``. Otherwise, this reduction will be done first (which may cost some time). @@ -471,7 +463,6 @@ cdef class SymmetricReductionStrategy: In the previous example, ``x[3] + x[2]`` is added without being reduced to zero. - """ from sage.rings.polynomial.infinite_polynomial_element import InfinitePolynomial p = InfinitePolynomial(self._parent, self(p)) @@ -525,16 +516,14 @@ cdef class SymmetricReductionStrategy: INPUT: - - ``p`` -- an element of the underlying infinite polynomial ring. - - ``notail`` -- (bool, default ``False``) If ``True``, tail reduction + - ``p`` -- an element of the underlying infinite polynomial ring + - ``notail`` -- boolean (default: ``False``); if ``True``, tail reduction is avoided (but there is no guarantee that there will be no tail - reduction at all). - - ``report`` -- (object, default ``None``) If not ``None``, print - information on the progress of the computation. + reduction at all) + - ``report`` -- object (default: ``None``); if not ``None``, print + information on the progress of the computation - OUTPUT: - - Reduction of ``p`` with respect to ``self``. + OUTPUT: reduction of ``p`` with respect to ``self`` .. NOTE:: @@ -568,7 +557,6 @@ cdef class SymmetricReductionStrategy: Each ':' indicates that one reduction of the leading monomial was performed. Eventually, the '>' indicates that the computation is finished. - """ from sage.rings.polynomial.infinite_polynomial_element import InfinitePolynomial cdef list lml = self._lm @@ -623,9 +611,9 @@ cdef class SymmetricReductionStrategy: INPUT: - - ``p`` -- an element of the underlying infinite polynomial ring. - - ``report`` -- (object, default ``None``) If not ``None``, print - information on the progress of the computation. + - ``p`` -- an element of the underlying infinite polynomial ring + - ``report`` -- object (default: ``None``); if not ``None``, print + information on the progress of the computation OUTPUT: diff --git a/src/sage/rings/polynomial/term_order.py b/src/sage/rings/polynomial/term_order.py index 431e3b03fa6..1bed10ba867 100644 --- a/src/sage/rings/polynomial/term_order.py +++ b/src/sage/rings/polynomial/term_order.py @@ -519,7 +519,7 @@ Block term order defined by term orders `<_1, <_2, \dots, <_n`. `x^a < x^b` if and only if `a = b` with respect to the first `n-1` term orders and `a <_n b` -with respect to the `n`th term order `<_n`. +with respect to the `n`-th term order `<_n`. """ description_mapping = { @@ -573,13 +573,13 @@ def __init__(self, name='lex', n=0, force=False): INPUT: - - ``name`` -- name of the term order (default: lex) + - ``name`` -- name of the term order (default: ``'lex'``) - - ``n`` -- number of variables (default is `0`) weights for + - ``n`` -- number of variables (default: `0`) weights for weighted degree orders. The weights are converted to integers and must be positive. - - ``force`` -- ignore unknown term orders. + - ``force`` -- ignore unknown term orders See the ``sage.rings.polynomial.term_order`` module for help which names and orders are available. @@ -623,7 +623,7 @@ def __init__(self, name='lex', n=0, force=False): (Degree reverse lexicographic term order of length 5, Degree lexicographic term order of length 2) - .. note:: + .. NOTE:: The optional `n` parameter is not necessary if only non-block orders like `deglex` are @@ -632,7 +632,7 @@ def __init__(self, name='lex', n=0, force=False): TESTS: - We demonstrate that non-positive weights are refused and non-integral weights + We demonstrate that nonpositive weights are refused and non-integral weights are converted to integers (and potentially rounded):: sage: N. = PolynomialRing(QQ, 3, order=TermOrder('wdeglex',[-1,2,-3])) @@ -864,7 +864,7 @@ def __init__(self, name='lex', n=0, force=False): def __hash__(self): r""" - A hash function + A hash function. EXAMPLES:: @@ -874,7 +874,7 @@ def __hash__(self): def __copy(self, other): """ - Copy other term order to self. + Copy ``other`` term order to ``self``. EXAMPLES:: @@ -993,7 +993,6 @@ def sortkey_deglex(self, f): False sage: x > 1 # needs sage.rings.number_field True - """ return (sum(f.nonzero_values(sort=False)), f) @@ -1013,7 +1012,6 @@ def sortkey_degrevlex(self, f): False sage: x > 1 # needs sage.rings.number_field True - """ return (sum(f.nonzero_values(sort=False)), f.reversed().emul(-1)) @@ -1891,7 +1889,6 @@ def matrix(self): sage: t.matrix() # needs sage.modules [1 2] [0 1] - """ return self._matrix @@ -1978,7 +1975,7 @@ def __ne__(self, other): def __add__(self, other): """ - Construct a block order combining self and other. + Construct a block order combining ``self`` and ``other``. INPUT: @@ -2019,7 +2016,7 @@ def __len__(self): def __getitem__(self, i): r""" - Return the i-th block of this term order. + Return the `i`-th block of this term order. INPUT: @@ -2159,7 +2156,7 @@ def is_weighted_degree_order(self): def termorder_from_singular(S): """ - Return the Sage term order of the basering in the given Singular interface + Return the Sage term order of the basering in the given Singular interface. INPUT: diff --git a/src/sage/rings/polynomial/toy_buchberger.py b/src/sage/rings/polynomial/toy_buchberger.py index 5ee623b4ef0..f00f4bdbabd 100644 --- a/src/sage/rings/polynomial/toy_buchberger.py +++ b/src/sage/rings/polynomial/toy_buchberger.py @@ -157,7 +157,7 @@ def spol(f, g): INPUT: - - ``f, g`` -- polynomials + - ``f``, ``g`` -- polynomials OUTPUT: the S-polynomial of f and g @@ -301,7 +301,7 @@ def update(G, B, h): - ``G`` -- an intermediate Groebner basis - - ``B`` -- a set of critical pairs + - ``B`` -- set of critical pairs - ``h`` -- a polynomial @@ -378,7 +378,7 @@ def select(P): INPUT: - - ``P`` -- a list of critical pairs + - ``P`` -- list of critical pairs OUTPUT: an element of P @@ -401,7 +401,7 @@ def inter_reduction(Q): INPUT: - - ``Q`` -- a set of polynomials + - ``Q`` -- set of polynomials OUTPUT: diff --git a/src/sage/rings/polynomial/toy_d_basis.py b/src/sage/rings/polynomial/toy_d_basis.py index ec783625140..fe8b367cb22 100644 --- a/src/sage/rings/polynomial/toy_d_basis.py +++ b/src/sage/rings/polynomial/toy_d_basis.py @@ -276,11 +276,9 @@ def select(P): INPUT: - - ``P`` -- a list of critical pairs + - ``P`` -- list of critical pairs - OUTPUT: - - an element of P + OUTPUT: an element of P EXAMPLES:: @@ -315,12 +313,10 @@ def update(G, B, h): INPUT: - ``G`` -- an intermediate Groebner basis - - ``B`` -- a list of critical pairs + - ``B`` -- list of critical pairs - ``h`` -- a polynomial - OUTPUT: - - ``G,B`` where ``G`` and ``B`` are updated + OUTPUT: ``G,B`` where ``G`` and ``B`` are updated EXAMPLES:: diff --git a/src/sage/rings/polynomial/toy_variety.py b/src/sage/rings/polynomial/toy_variety.py index 7a393595b61..ba67a1ece2e 100644 --- a/src/sage/rings/polynomial/toy_variety.py +++ b/src/sage/rings/polynomial/toy_variety.py @@ -42,11 +42,9 @@ def is_triangular(B) -> bool: INPUT: - - ``B`` -- a list/tuple of polynomials or a multivariate polynomial ideal + - ``B`` -- list/tuple of polynomials or a multivariate polynomial ideal - OUTPUT: - - ``True`` if the basis is triangular; ``False`` otherwise. + OUTPUT: ``True`` if the basis is triangular; ``False`` otherwise EXAMPLES:: @@ -90,11 +88,9 @@ def coefficient_matrix(polys): INPUT: - - ``polys`` -- a list/tuple of polynomials - - OUTPUT: + - ``polys`` -- list/tuple of polynomials - A matrix ``M`` of the coefficients of ``polys`` + OUTPUT: a matrix ``M`` of the coefficients of ``polys`` EXAMPLES:: @@ -149,7 +145,7 @@ def is_linearly_dependent(polys) -> bool: INPUT: - - ``polys`` -- a list/tuple of polynomials + - ``polys`` -- list/tuple of polynomials OUTPUT: @@ -204,7 +200,7 @@ def linear_representation(p, polys): INPUT: - ``p`` -- a polynomial - - ``polys`` -- a list/tuple of polynomials + - ``polys`` -- list/tuple of polynomials OUTPUT: @@ -242,12 +238,10 @@ def triangular_factorization(B, n=-1): INPUT: - - ``B`` -- a list/tuple of polynomials or a multivariate polynomial ideal + - ``B`` -- list/tuple of polynomials or a multivariate polynomial ideal - ``n`` -- the recursion parameter (default: ``-1``) - OUTPUT: - - A list ``T`` of triangular sets ``T_0``, ``T_1``, etc. + OUTPUT: list ``T`` of triangular sets ``T_0``, ``T_1``, etc. EXAMPLES:: @@ -320,7 +314,7 @@ def elim_pol(B, n=-1): INPUT: - - ``B`` -- a list/tuple of polynomials or a multivariate polynomial ideal + - ``B`` -- list/tuple of polynomials or a multivariate polynomial ideal - ``n`` -- the variable to check (see above) (default: ``-1``) EXAMPLES:: diff --git a/src/sage/rings/polynomial/weil/weil_polynomials.pyx b/src/sage/rings/polynomial/weil/weil_polynomials.pyx index ca5288a963f..516cf641d2e 100755 --- a/src/sage/rings/polynomial/weil/weil_polynomials.pyx +++ b/src/sage/rings/polynomial/weil/weil_polynomials.pyx @@ -143,7 +143,6 @@ cdef class dfs_manager: def __dealloc__(self): """ Deallocate memory. - """ ps_static_clear(self.ps_st_data) self.ps_st_data = NULL @@ -334,7 +333,7 @@ class WeilPolynomials_iter(): def __iter__(self): r""" - Return the iterator (i.e. `self`). + Return the iterator (i.e. ``self``). EXAMPLES:: @@ -410,34 +409,34 @@ class WeilPolynomials(): INPUT: - - ``d`` -- integer, the degree of the polynomials + - ``d`` -- integer; the degree of the polynomials - - ``q`` -- integer, the square of the complex absolute value of the roots + - ``q`` -- integer; the square of the complex absolute value of the roots - - ``sign`` -- integer (default `1`), the sign `s` of the functional equation + - ``sign`` -- integer (default: `1`); the sign `s` of the functional equation - - ``lead`` -- integer, list of integers or pairs of integers (default `1`) + - ``lead`` -- integer (default: `1`); list of integers or pairs of integers These are constraints on the leading coefficients of the generated polynomials. If pairs `(a, b)` of integers are given, they are treated as a constraint of the form `\equiv a \pmod{b}`; the moduli must be in decreasing order by divisibility, and the modulus of the leading coefficient must be 0. - - ``node_limit`` -- integer (default ``None``) + - ``node_limit`` -- integer (default: ``None``) If set, imposes an upper bound on the number of terminal nodes during the search - (will raise a ``RuntimeError`` if exceeded). + (will raise a :exc:`RuntimeError` if exceeded). - - ``parallel`` -- boolean (default ``False``), whether to use multiple processes + - ``parallel`` -- boolean (default: ``False``); whether to use multiple processes If set, will raise an error unless this file was compiled with OpenMP support (see instructions at the top of :mod:`sage.rings.polynomial.weil.weil_polynomials`). - - ``squarefree`` -- boolean (default ``False``), + - ``squarefree`` -- boolean (default: ``False``) If set, only squarefree polynomials will be returned. - - ``polring`` -- optional, a polynomial ring in which to construct the results + - ``polring`` -- (optional) a polynomial ring in which to construct the results EXAMPLES: diff --git a/src/sage/rings/power_series_mpoly.pyx b/src/sage/rings/power_series_mpoly.pyx index f7a298e8410..42cf467912b 100644 --- a/src/sage/rings/power_series_mpoly.pyx +++ b/src/sage/rings/power_series_mpoly.pyx @@ -3,7 +3,7 @@ from sage.rings.power_series_ring_element cimport PowerSeries from sage.structure.element cimport Element from sage.rings.infinity import infinity -from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing +from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base from sage.rings import power_series_poly @@ -56,7 +56,7 @@ cdef class PowerSeries_mpoly(PowerSeries): # avoid having an if statement in the inner loop of a # doubly-nested for loop. d = {} - if is_MPolynomialRing(B): + if isinstance(B, MPolynomialRing_base): for i in range(len(v)): for n, c in v[i].dict().iteritems(): d[tuple(n) + (i,)] = c diff --git a/src/sage/rings/power_series_pari.pyx b/src/sage/rings/power_series_pari.pyx index c9ff9beeee7..0e491cad78a 100644 --- a/src/sage/rings/power_series_pari.pyx +++ b/src/sage/rings/power_series_pari.pyx @@ -128,7 +128,6 @@ cdef class PowerSeries_pari(PowerSeries): - ``check`` -- ignored, but accepted for compatibility with :class:`~sage.rings.power_series_poly.PowerSeries_poly` - """ def __init__(self, parent, f=0, prec=infinity, check=None): """ @@ -141,7 +140,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: TestSuite(q).run() sage: f = q - q^3 + O(q^10) sage: TestSuite(f).run() - """ cdef Parent f_parent cdef pari_gen g @@ -214,7 +212,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: R. = PowerSeriesRing(ZZ, implementation='pari') sage: hash(t^2 + 1) == hash(pari(t^2 + 1)) True - """ return hash(self.g) @@ -230,7 +227,6 @@ cdef class PowerSeries_pari(PowerSeries): True sage: f == loads(dumps(f)) True - """ return PowerSeries_pari, (self._parent, self.g, self._prec, False) @@ -243,7 +239,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: R. = PowerSeriesRing(GF(7), implementation='pari') sage: (3 - t^3 + O(t^5)).__pari__() Mod(3, 7) + Mod(6, 7)*t^3 + O(t^5) - """ return self.g @@ -257,7 +252,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: f = 3 - t^3 + O(t^5) sage: f.polynomial() 6*t^3 + 3 - """ return self._parent._poly_ring()(self.list()) @@ -276,7 +270,6 @@ cdef class PowerSeries_pari(PowerSeries): 7 sage: R(0).valuation() +Infinity - """ if not self.g: return self._prec @@ -295,7 +288,6 @@ cdef class PowerSeries_pari(PowerSeries): False sage: bool(O(t^18)) False - """ return bool(self.g) @@ -394,7 +386,6 @@ cdef class PowerSeries_pari(PowerSeries): 1 + a*x + a^2*x^2 + a^3*x^3 + a^4*x^4 + a^5*x^5 + a^6*x^6 + O(x^7) sage: h(x^2, a=3) 1 + 3*x^2 + 4*x^4 + 2*x^6 + x^8 + 3*x^10 + 4*x^12 + O(x^14) - """ if len(kwds) >= 1: name = self._parent.variable_name() @@ -437,7 +428,7 @@ cdef class PowerSeries_pari(PowerSeries): return Q(self.polynomial()(a)).add_bigoh(t * self._prec) elif isinstance(Q, (PowerSeriesRing_generic, LaurentSeriesRing)): # In Sage, we want an error to be raised when trying to - # substitute a series of non-positive valuation, but PARI + # substitute a series of nonpositive valuation, but PARI # (2.8.0-development) does not do this. For example, # subst(1 + O(x), x, 1/y) yields O(y^-1). if a.valuation() <= 0: @@ -463,7 +454,7 @@ cdef class PowerSeries_pari(PowerSeries): same precision, whose coefficients are the same as ``self`` for those indices in the slice, and 0 otherwise. - Returns 0 for negative coefficients. Raises an ``IndexError`` + Returns 0 for negative coefficients. Raises an :exc:`IndexError` if trying to access beyond known coefficients. EXAMPLES:: @@ -491,7 +482,6 @@ cdef class PowerSeries_pari(PowerSeries): 1 + t^3 - 4*t^4 + O(t^7) sage: f[:4] 1 + t^3 + O(t^7) - """ cdef long t if isinstance(n, slice): @@ -516,7 +506,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: R. = PowerSeriesRing(QQ, default_prec=6, implementation='pari') sage: ~(R(1-t)) 1 + t + t^2 + t^3 + t^4 + t^5 + O(t^6) - """ h = ~self.g if h.valuation(self._parent.variable_name()) < 0: @@ -533,7 +522,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: f = t + 17/5*t^3 + 2*t^4 + O(t^5) sage: -f -t - 17/5*t^3 - 2*t^4 + O(t^5) - """ return construct_from_pari(self._parent, -self.g) @@ -549,7 +537,6 @@ cdef class PowerSeries_pari(PowerSeries): 27 - 27*t^3 + O(t^5) sage: b = f^-3; b 1/27 + 1/27*t^3 + O(t^5) - """ h = self.g ** n if h.valuation(self._parent.variable_name()) < 0: @@ -569,7 +556,6 @@ cdef class PowerSeries_pari(PowerSeries): x^2 + O(x^3) sage: f+g x^2 + O(x^3) - """ return construct_from_pari(self._parent, self.g + (right).g) @@ -583,7 +569,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: R. = PowerSeriesRing(k, implementation='pari') sage: w*t^2 -w*t +13 - (w*t^2 + w*t) 13 - 2*w*t - """ return construct_from_pari(self._parent, self.g - (right).g) @@ -596,7 +581,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: k. = PowerSeriesRing(ZZ, implementation='pari') sage: (1+17*w+15*w^3+O(w^5))*(19*w^10+O(w^12)) 19*w^10 + 323*w^11 + O(w^12) - """ return construct_from_pari(self._parent, self.g * (right).g) @@ -610,7 +594,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: f = t + 3*t^4 + O(t^11) sage: f * GF(7)(3) 3*t + 2*t^4 + O(t^11) - """ return construct_from_pari(self._parent, self.g * c) @@ -624,7 +607,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: f = 1 + 3*t^4 + O(t^120) sage: 2 * f 2 + 6*t^4 + O(t^120) - """ return construct_from_pari(self._parent, c * self.g) @@ -643,7 +625,6 @@ cdef class PowerSeries_pari(PowerSeries): t^-1 + 10 sage: g.parent() Laurent Series Ring in t over Finite Field of size 11 - """ h = self.g / (right).g if h.valuation(self._parent.variable_name()) < 0: @@ -668,7 +649,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: S. = PowerSeriesRing(pAdicRing(5), implementation='pari') sage: (2 + u).list() [2 + O(5^20), 1 + O(5^20)] - """ cdef pari_gen g = self.g cdef long vn = get_var(self._parent.variable_name()) @@ -692,10 +672,10 @@ cdef class PowerSeries_pari(PowerSeries): INPUT: - - ``n`` -- a non-negative integer (optional); if `n` is not - given, it will be taken to be the precision of ``self`, - unless this is ``+Infinity``, in which case we just - return ``self.list()`` + - ``n`` -- nonnegative integer (optional); if `n` is not + given, it will be taken to be the precision of ``self``, + unless this is ``+Infinity``, in which case we just + return ``self.list()`` EXAMPLES:: @@ -718,7 +698,6 @@ cdef class PowerSeries_pari(PowerSeries): [1, -17, 13, 0, 10] sage: g.padded_list(10) [1, -17, 13, 0, 10, 0, 0, 0, 0, 0] - """ if n is None: if self._prec is infinity: @@ -769,7 +748,6 @@ cdef class PowerSeries_pari(PowerSeries): sage: f = 1 + t^10 + O(t^12) sage: f.dict() {0: 1, 10: 1} - """ return self.polynomial().dict() @@ -804,7 +782,6 @@ cdef class PowerSeries_pari(PowerSeries): 4*t^3*x^3 + O(x^4) sage: f._derivative(t) 3*t^2*x^4 + O(x^5) - """ if var is None: var = self._parent.variable_name() @@ -848,7 +825,6 @@ cdef class PowerSeries_pari(PowerSeries): 1/2*a*t^2 + 5/3*t^3 sage: f.integral(a) 1/2*a^2*t + 5*a*t^2 - """ if var is None: var = self._parent.variable_name() @@ -937,7 +913,6 @@ cdef class PowerSeries_pari(PowerSeries): Traceback (most recent call last): ... PariError: domain error in serreverse: valuation != 1 - """ cdef PowerSeries_pari f if self._prec is infinity: diff --git a/src/sage/rings/power_series_poly.pyx b/src/sage/rings/power_series_poly.pyx index cb0b0fcad1e..91f790ffa16 100644 --- a/src/sage/rings/power_series_poly.pyx +++ b/src/sage/rings/power_series_poly.pyx @@ -174,21 +174,21 @@ cdef class PowerSeries_poly(PowerSeries): def __call__(self, *x, **kwds): """ - Evaluate the series at x=a. + Evaluate the series at `x=a`. INPUT: - - ``x``: + - ``x``: - - a tuple of elements the first of which can be meaningfully - substituted in ``self``, with the remainder used for substitution - in the coefficients of ``self``. + - a tuple of elements the first of which can be meaningfully + substituted in ``self``, with the remainder used for substitution + in the coefficients of ``self``. - - a dictionary for kwds:value pairs. If the variable name of - self is a keyword it is substituted for. Other keywords - are used for substitution in the coefficients of self. + - a dictionary for kwds:value pairs. If the variable name of + ``self`` is a keyword it is substituted for. Other keywords + are used for substitution in the coefficients of ``self``. - OUTPUT: the value of ``self`` after substitution. + OUTPUT: the value of ``self`` after substitution EXAMPLES:: @@ -232,7 +232,7 @@ cdef class PowerSeries_poly(PowerSeries): sage: f(2*u + u^3 + O(u^5)) 4*u^2 + u^3 + 4*u^4 + 5*u^5 + O(u^6) - As can a p-adic integer as long as the coefficient ring is compatible:: + As can a `p`-adic integer as long as the coefficient ring is compatible:: sage: f(100 + O(5^7)) # needs sage.rings.padics 5^4 + 3*5^5 + 4*5^6 + 2*5^7 + 2*5^8 + O(5^9) @@ -409,7 +409,7 @@ cdef class PowerSeries_poly(PowerSeries): Return the ``n``-th coefficient of ``self``. This returns 0 for negative coefficients and raises an - ``IndexError`` if trying to access beyond known coefficients. + :exc:`IndexError` if trying to access beyond known coefficients. If ``n`` is a slice object ``[:k]``, this will return a power series of the same precision, whose coefficients are the same @@ -675,7 +675,7 @@ cdef class PowerSeries_poly(PowerSeries): sage: u*v 1 + O(t^12) - If we try a non-zero, non-unit constant term, we end up in + If we try a nonzero, non-unit constant term, we end up in the fraction field, i.e. the Laurent series ring:: sage: R. = PowerSeriesRing(ZZ) @@ -700,7 +700,6 @@ cdef class PowerSeries_poly(PowerSeries): Traceback (most recent call last): ... ValueError: must be an integral domain - """ if self.is_one(): return self @@ -765,7 +764,7 @@ cdef class PowerSeries_poly(PowerSeries): def truncate_powerseries(self, long prec): r""" Given input ``prec`` = `n`, returns the power series of degree - `< n` which is equivalent to self modulo `x^n`. + `< n` which is equivalent to ``self`` modulo `x^n`. EXAMPLES:: @@ -1122,9 +1121,7 @@ cdef class PowerSeries_poly(PowerSeries): - ``m``, ``n`` -- integers, describing the degrees of the polynomials - OUTPUT: - - a ratio of two polynomials + OUTPUT: a ratio of two polynomials ALGORITHM: diff --git a/src/sage/rings/power_series_ring.py b/src/sage/rings/power_series_ring.py index 1052d963bdc..b9dc542b4dd 100644 --- a/src/sage/rings/power_series_ring.py +++ b/src/sage/rings/power_series_ring.py @@ -148,8 +148,8 @@ ) from sage.rings.fraction_field_element import FractionFieldElement from sage.rings.infinity import infinity -from sage.rings.polynomial.multi_polynomial_ring_base import is_MPolynomialRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.multi_polynomial_ring_base import MPolynomialRing_base +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.structure.category_object import normalize_names from sage.structure.element import Expression, parent @@ -185,24 +185,22 @@ def PowerSeriesRing(base_ring, name=None, arg2=None, names=None, INPUT: + - ``base_ring`` -- a commutative ring - - ``base_ring`` -- a commutative ring - - - ``name``, ``names`` -- name(s) of the indeterminate + - ``name``, ``names`` -- name(s) of the indeterminate - ``default_prec`` -- the default precision used if an exact object must - be changed to an approximate object in order to do an arithmetic - operation. If left as ``None``, it will be set to the global - default (20) in the univariate case, and 12 in the multivariate case. + be changed to an approximate object in order to do an arithmetic + operation. If left as ``None``, it will be set to the global + default (20) in the univariate case, and 12 in the multivariate case. - - ``sparse`` -- (default: ``False``) whether power series - are represented as sparse objects. + - ``sparse`` -- boolean (default: ``False``); whether power series + are represented as sparse objects - ``order`` -- (default: ``negdeglex``) term ordering, for multivariate case - ``num_gens`` -- number of generators, for multivariate case - There is a unique power series ring over each base ring with given variable name. Two power series over the same base ring with different variable names are not equal or isomorphic. @@ -490,19 +488,17 @@ class PowerSeriesRing_generic(UniqueRepresentation, ring.CommutativeRing, Nonexa def __init__(self, base_ring, name=None, default_prec=None, sparse=False, implementation=None, category=None): """ - Initializes a power series ring. + Initialize a power series ring. INPUT: + - ``base_ring`` -- a commutative ring - - ``base_ring`` -- a commutative ring + - ``name`` -- name of the indeterminate - - ``name`` -- name of the indeterminate + - ``default_prec`` -- the default precision - - ``default_prec`` -- the default precision - - - ``sparse`` -- whether or not power series are - sparse + - ``sparse`` -- whether or not power series are sparse - ``implementation`` -- either ``'poly'``, ``'mpoly'``, or ``'pari'``. Other values (for example ``'NTL'``) are passed to @@ -540,14 +536,13 @@ def __init__(self, base_ring, name=None, default_prec=None, sparse=False, Category of complete discrete valuation rings sage: TestSuite(R).run() - It is checked that the default precision is non-negative + It is checked that the default precision is nonnegative (see :issue:`19409`):: sage: PowerSeriesRing(ZZ, 'x', default_prec=-5) Traceback (most recent call last): ... - ValueError: default_prec (= -5) must be non-negative - + ValueError: default_prec (= -5) must be nonnegative """ if implementation is None: try: @@ -571,7 +566,7 @@ def __init__(self, base_ring, name=None, default_prec=None, sparse=False, from sage.misc.defaults import series_precision default_prec = series_precision() elif default_prec < 0: - raise ValueError("default_prec (= %s) must be non-negative" + raise ValueError("default_prec (= %s) must be nonnegative" % default_prec) if implementation == 'poly': @@ -580,7 +575,7 @@ def __init__(self, base_ring, name=None, default_prec=None, sparse=False, K = base_ring names = K.variable_names() + (name,) self.__mpoly_ring = PolynomialRing(K.base_ring(), names=names) - assert is_MPolynomialRing(self.__mpoly_ring) + assert isinstance(self.__mpoly_ring, MPolynomialRing_base) self.Element = power_series_mpoly.PowerSeries_mpoly elif implementation == 'pari': from .power_series_pari import PowerSeries_pari @@ -711,7 +706,7 @@ def _coerce_map_from_(self, S): """ if self.base_ring().has_coerce_map_from(S): return True - if (is_PolynomialRing(S) or is_PowerSeriesRing(S)) and self.base_ring().has_coerce_map_from(S.base_ring()) \ + if (isinstance(S, PolynomialRing_general) or is_PowerSeriesRing(S)) and self.base_ring().has_coerce_map_from(S.base_ring()) \ and self.variable_names() == S.variable_names(): return True @@ -724,14 +719,12 @@ def _element_constructor_(self, f, prec=infinity, check=True): INPUT: + - ``f`` -- object, e.g., a power series ring element - - ``f`` -- object, e.g., a power series ring element + - ``prec`` -- (default: infinity) truncation precision for coercion - - ``prec`` -- (default: infinity); truncation precision - for coercion - - - ``check`` -- bool (default: ``True``), whether to verify - that the coefficients, etc., coerce in correctly. + - ``check`` -- boolean (default: ``True``); whether to verify + that the coefficients, etc., coerce in correctly EXAMPLES:: @@ -789,7 +782,7 @@ def _element_constructor_(self, f, prec=infinity, check=True): sage: R(ex) 1 + euler_gamma*y + (1/2*euler_gamma^2 + 1/12*pi^2)*y^2 + O(y^3) - Laurent series with non-negative valuation are accepted (see + Laurent series with nonnegative valuation are accepted (see :issue:`6431`):: sage: L. = LaurentSeriesRing(QQ) @@ -801,13 +794,13 @@ def _element_constructor_(self, f, prec=infinity, check=True): ... TypeError: self is not a power series - It is checked that the precision is non-negative + It is checked that the precision is nonnegative (see :issue:`19409`):: sage: PowerSeriesRing(ZZ, 'x')(1, prec=-5) Traceback (most recent call last): ... - ValueError: prec (= -5) must be non-negative + ValueError: prec (= -5) must be nonnegative From lazy series:: @@ -821,7 +814,7 @@ def _element_constructor_(self, f, prec=infinity, check=True): if prec is not infinity: prec = integer.Integer(prec) if prec < 0: - raise ValueError("prec (= %s) must be non-negative" % prec) + raise ValueError("prec (= %s) must be nonnegative" % prec) if isinstance(f, power_series_ring_element.PowerSeries) and f.parent() is self: if prec >= f.prec(): return f @@ -875,7 +868,6 @@ def construction(self): sage: c, S = R.construction() sage: R == c(S) True - """ from sage.categories.pushout import CompletionFunctor if self.is_sparse(): @@ -886,19 +878,19 @@ def construction(self): def _coerce_impl(self, x): """ - Return canonical coercion of x into self. + Return canonical coercion of x into ``self``. - Rings that canonically coerce to this power series ring R: + Rings that canonically coerce to this power series ring `R`: - - R itself + - `R` itself - Any power series ring in the same variable whose base ring - canonically coerces to the base ring of R. + canonically coerces to the base ring of `R` - Any ring that canonically coerces to the polynomial ring - over the base ring of R. + over the base ring of `R` - - Any ring that canonically coerces to the base ring of R + - Any ring that canonically coerces to the base ring of `R` EXAMPLES:: @@ -972,10 +964,10 @@ def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): sage: g(-1 + 3/5 * t) -1 + 3/5*t^2 - .. note:: + .. NOTE:: There are no ring homomorphisms from the ring of all formal - power series to most rings, e.g, the p-adic field, since + power series to most rings, e.g, the `p`-adic field, since you can always (mathematically!) construct some power series that doesn't converge. Note that 0 is not a *ring* homomorphism. @@ -1138,17 +1130,17 @@ def random_element(self, prec=None, *args, **kwds): INPUT: - - ``prec`` -- Integer specifying precision of output (default: - default precision of ``self``) + - ``prec`` -- integer specifying precision of output (default: + default precision of ``self``) - - ``*args``, ``**kwds`` -- Passed on to the ``random_element`` method for - the base ring + - ``*args``, ``**kwds`` -- passed on to the ``random_element`` method for + the base ring OUTPUT: - - Power series with precision ``prec`` whose coefficients are - random elements from the base ring, randomized subject to the - arguments ``*args`` and ``**kwds`` + Power series with precision ``prec`` whose coefficients are + random elements from the base ring, randomized subject to the + arguments ``*args`` and ``**kwds``. ALGORITHM: @@ -1192,7 +1184,6 @@ def random_element(self, prec=None, *args, **kwds): 1/87 - 3/70*v - 3/44*v^2 + O(v^3) sage: SR.random_element(3, max=10, min=-10) # random 2.85948321262904 - 9.73071330911226*v - 6.60414378519265*v^2 + O(v^3) - """ if prec is None: prec = self.default_prec() diff --git a/src/sage/rings/power_series_ring_element.pyx b/src/sage/rings/power_series_ring_element.pyx index 524fb48df27..6ef9f6ab097 100644 --- a/src/sage/rings/power_series_ring_element.pyx +++ b/src/sage/rings/power_series_ring_element.pyx @@ -125,6 +125,9 @@ def is_PowerSeries(x): sage: R. = PowerSeriesRing(ZZ) sage: from sage.rings.power_series_ring_element import is_PowerSeries sage: is_PowerSeries(1 + x^2) + doctest:warning... + DeprecationWarning: The function is_PowerSeries is deprecated; use 'isinstance(..., PowerSeries)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. True sage: is_PowerSeries(x - x) True @@ -135,6 +138,10 @@ def is_PowerSeries(x): sage: is_PowerSeries(1 + x^2) # needs sage.symbolic False """ + from sage.misc.superseded import deprecation_cython + deprecation_cython(38266, + "The function is_PowerSeries is deprecated; " + "use 'isinstance(..., PowerSeries)' instead.") return isinstance(x, PowerSeries) @@ -164,7 +171,7 @@ cdef class PowerSeries(AlgebraElement): def __hash__(self): """ - Compute a hash of self. + Compute a hash of ``self``. EXAMPLES:: @@ -224,7 +231,7 @@ cdef class PowerSeries(AlgebraElement): sage: (1 + 2*t).is_gen() False - Note that this only returns True on the actual generator, not on + Note that this only returns ``True`` on the actual generator, not on something that happens to be equal to it. :: @@ -269,7 +276,7 @@ cdef class PowerSeries(AlgebraElement): def change_ring(self, R): """ - Change if possible the coefficients of self to lie in R. + Change if possible the coefficients of ``self`` to lie in R. EXAMPLES:: @@ -313,7 +320,7 @@ cdef class PowerSeries(AlgebraElement): cpdef _richcmp_(self, right, int op): r""" - Comparison of self and ``right``. + Comparison of ``self`` and ``right``. We say two approximate power series are equal if they agree for all coefficients up to the *minimum* of the precisions of each. @@ -403,7 +410,7 @@ cdef class PowerSeries(AlgebraElement): def coefficients(self): """ - Return the nonzero coefficients of self. + Return the nonzero coefficients of ``self``. EXAMPLES:: @@ -417,7 +424,7 @@ cdef class PowerSeries(AlgebraElement): def exponents(self): """ - Return the exponents appearing in self with nonzero coefficients. + Return the exponents appearing in ``self`` with nonzero coefficients. EXAMPLES:: @@ -479,7 +486,7 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``absprec`` -- an integer or ``None`` (default: ``None``), the + - ``absprec`` -- integer or ``None`` (default: ``None``); the absolute precision of the result. If ``None``, lifts to an exact element. @@ -491,7 +498,6 @@ cdef class PowerSeries(AlgebraElement): t + t^2 + O(t^10) sage: x.lift_to_precision() t + t^2 - """ if absprec is not None and absprec <= self.precision_absolute(): return self @@ -531,20 +537,17 @@ cdef class PowerSeries(AlgebraElement): def padded_list(self, n=None): """ - Return a list of coefficients of self up to (but not including) + Return a list of coefficients of ``self`` up to (but not including) `q^n`. - Includes 0's in the list on the right so that the list has length - `n`. + Includes 0s in the list on the right so that the list has length `n`. INPUT: - - - ``n`` -- (optional) an integer that is at least 0. If ``n`` is - not given, it will be taken to be the precision of self, - unless this is ``+Infinity``, in which case we just return - ``self.list()``. - + - ``n`` -- (optional) an integer that is at least 0. If ``n`` is + not given, it will be taken to be the precision of ``self``, + unless this is ``+Infinity``, in which case we just return + ``self.list()``. EXAMPLES:: @@ -842,7 +845,7 @@ cdef class PowerSeries(AlgebraElement): `t` is the indeterminate of the power series ring. If `n` is negative return 0. If `n` is beyond the precision, raise an - IndexError. + :exc:`IndexError`. EXAMPLES:: @@ -1007,7 +1010,7 @@ cdef class PowerSeries(AlgebraElement): def valuation_zero_part(self): r""" - Factor self as `q^n \cdot (a_0 + a_1 q + \cdots)` with + Factor ``self`` as `q^n \cdot (a_0 + a_1 q + \cdots)` with `a_0` nonzero. Then this function returns `a_0 + a_1 q + \cdots` . @@ -1075,7 +1078,6 @@ cdef class PowerSeries(AlgebraElement): True sage: (1/(2*x)).parent() Laurent Series Ring in x over Rational Field - """ denom = denom_r if denom.is_zero(): @@ -1133,7 +1135,6 @@ cdef class PowerSeries(AlgebraElement): x + x^3 sage: O(x^4)^(1/2) O(x^2) - """ try: right = QQ.coerce(r) @@ -1231,8 +1232,8 @@ cdef class PowerSeries(AlgebraElement): def is_monomial(self): """ - Return ``True`` if this element is a monomial. That is, if self is - `x^n` for some non-negative integer `n`. + Return ``True`` if this element is a monomial. That is, if ``self`` is + `x^n` for some nonnegative integer `n`. EXAMPLES:: @@ -1253,20 +1254,20 @@ cdef class PowerSeries(AlgebraElement): def map_coefficients(self, f, new_base_ring=None): r""" - Return the series obtained by applying ``f`` to the non-zero + Return the series obtained by applying ``f`` to the nonzero coefficients of ``self``. If ``f`` is a :class:`sage.categories.map.Map`, then the resulting series will be defined over the codomain of ``f``. Otherwise, the - resulting polynomial will be over the same ring as self. Set + resulting polynomial will be over the same ring as ``self``. Set ``new_base_ring`` to override this behaviour. INPUT: - - ``f`` -- a callable that will be applied to the coefficients of self. + - ``f`` -- a callable that will be applied to the coefficients of ``self`` - - ``new_base_ring`` (optional) -- if given, the resulting polynomial - will be defined over this ring. + - ``new_base_ring`` -- (optional) if given, the resulting polynomial + will be defined over this ring EXAMPLES:: @@ -1395,9 +1396,7 @@ cdef class PowerSeries(AlgebraElement): 1 / (1 - A_1 t / (1 - A_2 t / (1 - A_3 t / (1 - \cdots)))) - OUTPUT: - - `A_n` for `n \geq 1` + OUTPUT: `A_n` for `n \geq 1` The expansion is done as long as possible given the precision. Whenever the expansion is not well-defined, because it would @@ -1510,22 +1509,21 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- integer (default: ``None``): if not ``None`` and the series - has infinite precision, truncates series at precision - ``prec``. + - ``prec`` -- integer (default: ``None``); if not ``None`` and the + series has infinite precision, truncates series at precision ``prec`` - - ``extend`` -- bool (default: ``False``); if ``True``, return a square - root in an extension ring, if necessary. Otherwise, raise - a :class:`ValueError` if the square root is not in the base power series + - ``extend`` -- boolean (default: ``False``); if ``True``, return a + square root in an extension ring, if necessary. Otherwise, raise + a :exc:`ValueError` if the square root is not in the base power series ring. For example, if ``extend`` is ``True``, the square root of a power series with odd degree leading coefficient is defined as an element of a formal extension ring. - - ``name`` -- string; if ``extend`` is ``True``, you must also specify the print - name of the formal square root. + - ``name`` -- string; if ``extend`` is ``True``, you must also + specify the print name of the formal square root - - ``all`` -- bool (default: ``False``); if ``True``, return all square - roots of ``self``, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of ``self``, instead of just one ALGORITHM: Newton's method @@ -1837,12 +1835,10 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to - OUTPUT: - - A new power series. + OUTPUT: a new power series EXAMPLES: @@ -1864,7 +1860,7 @@ cdef class PowerSeries(AlgebraElement): sage: f.cos(prec=2) 1 + O(a, b)^2 - If the power series has a non-zero constant coefficient `c`, + If the power series has a nonzero constant coefficient `c`, one raises an error:: sage: g = 2+f @@ -1922,12 +1918,10 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. - - OUTPUT: + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to - A new power series. + OUTPUT: a new power series EXAMPLES: @@ -1949,7 +1943,7 @@ cdef class PowerSeries(AlgebraElement): sage: f.sin(prec=2) a + b + O(a, b)^2 - If the power series has a non-zero constant coefficient `c`, + If the power series has a nonzero constant coefficient `c`, one raises an error:: sage: g = 2+f @@ -2008,12 +2002,10 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. - - OUTPUT: + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to - A new power series. + OUTPUT: a new power series EXAMPLES: @@ -2035,7 +2027,7 @@ cdef class PowerSeries(AlgebraElement): sage: f.tan(prec=2) a + b + O(a, b)^2 - If the power series has a non-zero constant coefficient `c`, + If the power series has a nonzero constant coefficient `c`, one raises an error:: sage: g = 2 + f @@ -2072,12 +2064,10 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to - OUTPUT: - - A new power series. + OUTPUT: a new power series EXAMPLES: @@ -2099,7 +2089,7 @@ cdef class PowerSeries(AlgebraElement): sage: f.sinh(prec=2) a + b + O(a, b)^2 - If the power series has a non-zero constant coefficient `c`, + If the power series has a nonzero constant coefficient `c`, one raises an error:: sage: g = 2 + f @@ -2125,7 +2115,6 @@ cdef class PowerSeries(AlgebraElement): sage: sinh(a^2 + T.O(5)) a^2 + O(a, b)^5 - """ R = self.parent() @@ -2161,12 +2150,10 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to - OUTPUT: - - A new power series. + OUTPUT: a new power series EXAMPLES: @@ -2188,7 +2175,7 @@ cdef class PowerSeries(AlgebraElement): sage: f.cosh(prec=2) 1 + O(a, b)^2 - If the power series has a non-zero constant coefficient `c`, + If the power series has a nonzero constant coefficient `c`, one raises an error:: sage: g = 2 + f @@ -2214,7 +2201,6 @@ cdef class PowerSeries(AlgebraElement): sage: cosh(a^2 + T.O(5)) 1 + 1/2*a^4 + O(a, b)^5 - """ R = self.parent() @@ -2249,12 +2235,10 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- Integer or ``infinity``. The degree to truncate - the result to. + - ``prec`` -- integer or ``infinity``; the degree to truncate + the result to - OUTPUT: - - A new power series. + OUTPUT: a new power series EXAMPLES: @@ -2276,7 +2260,7 @@ cdef class PowerSeries(AlgebraElement): sage: f.tanh(prec=2) a + b + O(a, b)^2 - If the power series has a non-zero constant coefficient `c`, + If the power series has a nonzero constant coefficient `c`, one raises an error:: sage: g = 2 + f @@ -2302,7 +2286,6 @@ cdef class PowerSeries(AlgebraElement): sage: tanh(a^2 + T.O(5)) a^2 + O(a, b)^5 - """ if not self[0].is_zero(): raise ValueError('can only apply tanh to formal power ' @@ -2327,7 +2310,7 @@ cdef class PowerSeries(AlgebraElement): sage: p.O(-5) Traceback (most recent call last): ... - ValueError: prec (= -5) must be non-negative + ValueError: prec (= -5) must be nonnegative """ if prec is infinity or prec >= self.prec(): return self @@ -2345,16 +2328,15 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``self`` -- the power series `a(t)` + - ``self`` -- the power series `a(t)` - - ``b`` -- the power series `b(t)` (default is - zero) + - ``b`` -- the power series `b(t)` (default: zero) - - ``f0`` -- the constant term of `f` ("initial - condition") (default is 1) + - ``f0`` -- the constant term of `f` ("initial condition") + (default: 1) - - ``prec`` -- desired precision of result (this will be - reduced if either a or b have less precision available) + - ``prec`` -- desired precision of result (this will be + reduced if either a or b have less precision available) OUTPUT: the power series `f`, to indicated precision @@ -2372,7 +2354,7 @@ cdef class PowerSeries(AlgebraElement): - For other coefficient rings, things are more complicated. A solution may not exist, and if it does it - may not be unique. Generally, by the time the nth term + may not be unique. Generally, by the time the `n`-th term has been computed, the algorithm will have attempted divisions by `n!` in the coefficient ring. So if your coefficient ring has enough 'precision', and if your @@ -2429,7 +2411,7 @@ cdef class PowerSeries(AlgebraElement): if prec == 0: return self._parent(0, 0) if prec < 0: - raise ValueError("prec (=%s) must be a non-negative integer" % prec) + raise ValueError("prec (=%s) must be a nonnegative integer" % prec) base_ring = self._parent.base_ring() R = PolynomialRing(base_ring, self._parent.variable_name()) @@ -2448,10 +2430,7 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - - ``prec`` -- integer; default is - ``self.parent().default_prec`` - + - ``prec`` -- integer (default: ``self.parent().default_prec``) ALGORITHM: See :meth:`.solve_linear_de`. @@ -2562,7 +2541,7 @@ cdef class PowerSeries(AlgebraElement): INPUT: - - ``prec`` -- integer; default is ``self.parent().default_prec()`` + - ``prec`` -- integer (default: ``self.parent().default_prec()``) ALGORITHM: See :meth:`solve_linear_de()`. @@ -2834,7 +2813,7 @@ cdef class PowerSeries(AlgebraElement): def _solve_linear_de(R, N, L, a, b, f0): r""" - Internal function used by PowerSeries.solve_linear_de(). + Internal function used by ``PowerSeries.solve_linear_de()``. INPUT: @@ -2844,29 +2823,25 @@ def _solve_linear_de(R, N, L, a, b, f0): - ``L`` -- integer >= 1 - - ``a`` -- list of coefficients of `a`, any - length, all coefficients should belong to base ring of R. - - - ``b`` -- list of coefficients of `b`, length - at least `L` (only first `L` coefficients are - used), all coefficients should belong to base ring of R. + - ``a`` -- list of coefficients of `a`, any length, all coefficients should + belong to base ring of `R` - - ``f0`` -- constant term of `f` (only used if - `N == 0`), should belong to base ring of R. + - ``b`` -- list of coefficients of `b`, length at least `L` (only first `L` + coefficients are used), all coefficients should belong to base ring of `R` + - ``f0`` -- constant term of `f` (only used if ``N == 0``), should belong + to base ring of `R` - OUTPUT: List of coefficients of `f` (length exactly - `L`), where `f` is a solution to the linear - inhomogeneous differential equation: + OUTPUT: list of coefficients of `f` (length exactly `L`), where `f` is a + solution to the linear inhomogeneous differential equation: .. MATH:: (t^N f)' = a t^N f + t^{N-1} b + O(t^{N+L-1}). - The constant term of `f` is taken to be f0 if - `N == 0`, and otherwise is determined by - `N f_0 = b_0`. + The constant term of `f` is taken to be f0 if `N == 0`, and otherwise is + determined by `N f_0 = b_0`. ALGORITHM: The algorithm implemented here is inspired by the "fast lazy multiplication algorithm" described in the paper "Lazy diff --git a/src/sage/rings/puiseux_series_ring.py b/src/sage/rings/puiseux_series_ring.py index d63b5bcc665..60843720884 100644 --- a/src/sage/rings/puiseux_series_ring.py +++ b/src/sage/rings/puiseux_series_ring.py @@ -204,7 +204,7 @@ def fraction_field(self): If the base ring is a field, then Puiseux series are already a field. If the base ring is a domain, then the Puiseux series over its fraction - field is returned. Otherwise, raise a :class:`ValueError`. + field is returned. Otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -340,7 +340,7 @@ def _element_constructor_(self, x, e=1, prec=infinity): def _coerce_map_from_(self, P): r""" - Return a coercion map from `P` to `self`, or `True`, or `None`. + Return a coercion map from `P` to ``self``, or ``True``, or ``None``. The following rings admit a coercion map to the Puiseux series ring `A((x-a)^(1/e))`: @@ -351,7 +351,7 @@ def _coerce_map_from_(self, P): variable `(x-a)` over a ring admitting a coercion map to `A` - any Puiseux series ring with the same center `a` and ramification - index equal to a multiple of `self`'s ramification index. For + index equal to a multiple of ``self``'s ramification index. For example, Puiseux series in (x-a)^(1/2) can be interpreted as Puiseux series in (x-a)^(1/4). diff --git a/src/sage/rings/puiseux_series_ring_element.pyx b/src/sage/rings/puiseux_series_ring_element.pyx index 96aa6eaef6e..902ce96bd7c 100644 --- a/src/sage/rings/puiseux_series_ring_element.pyx +++ b/src/sage/rings/puiseux_series_ring_element.pyx @@ -133,12 +133,12 @@ cdef class PuiseuxSeries(AlgebraElement): - ``parent`` -- the parent ring - - ``f`` -- one of the following types of inputs: + - ``f`` -- one of the following types of inputs: * instance of :class:`PuiseuxSeries` * instance that can be coerced into the Laurent series ring of the parent - - ``e`` -- integer (default: 1) the ramification index + - ``e`` -- integer (default: 1); the ramification index EXAMPLES:: diff --git a/src/sage/rings/qqbar.py b/src/sage/rings/qqbar.py index 9b9b5c5e7cf..c52a609e62a 100644 --- a/src/sage/rings/qqbar.py +++ b/src/sage/rings/qqbar.py @@ -124,7 +124,7 @@ sage: AA((-4)^(1/4)) Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary part to algebraic real + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real The coercion, however, goes in the other direction, since not all symbolic expressions are algebraic numbers:: @@ -411,7 +411,7 @@ real (has an imaginary component of exactly zero). Converting from either ``AA`` or ``QQbar`` to ``ZZ`` or ``QQ`` succeeds only if the number actually is an integer or rational. If conversion fails, a -ValueError will be raised. +:exc:`ValueError` will be raised. Here are examples of all of these conversions:: @@ -927,7 +927,6 @@ def _factor_multivariate_polynomial(self, f, proof=True): sage: # needs sage.libs.singular sage: AA['x','y'](1).factor() # indirect doctest 1 - """ from sage.interfaces.singular import singular from sage.structure.factorization import Factorization @@ -1149,7 +1148,7 @@ def _element_constructor_(self, x): if x.imag().is_zero(): return x.real() else: - raise ValueError("Cannot coerce algebraic number with non-zero imaginary part to algebraic real") + raise ValueError("Cannot coerce algebraic number with nonzero imaginary part to algebraic real") elif hasattr(x, '_algebraic_'): return x._algebraic_(AA) return AlgebraicReal(x) @@ -1351,11 +1350,11 @@ def ngens(self): def zeta(self, n=2): r""" Return an `n`-th root of unity in this field. This will raise a - ``ValueError`` if `n \ne \{1, 2\}` since no such root exists. + :exc:`ValueError` if `n \ne \{1, 2\}` since no such root exists. INPUT: - - ``n`` (integer) -- default 2 + - ``n`` -- integer (default: 2) EXAMPLES:: @@ -1447,7 +1446,7 @@ def random_element(self, poly_degree=2, *args, **kwds): INPUT: - - ``poly_degree`` -- default: 2; degree of the random + - ``poly_degree`` -- (default: 2) degree of the random polynomial over the integers of which the returned algebraic real number is a (real part of a) root. This is not necessarily the degree of the minimal polynomial of the @@ -1551,7 +1550,6 @@ def _factor_univariate_polynomial(self, f): (12) * (x^2 + 0.3333333333333334?) sage: AA._factor_univariate_polynomial(EllipticCurve('11a1').change_ring(AA).division_polynomial(5)) # needs sage.schemes (5) * (x - 16.00000000000000?) * (x - 5.000000000000000?) * (x - 1.959674775249769?) * (x + 2.959674775249769?) * (x^2 - 2.854101966249685?*x + 15.47213595499958?) * (x^2 + 1.909830056250526?*x + 1.660606461254312?) * (x^2 + 3.854101966249685?*x + 6.527864045000421?) * (x^2 + 13.09016994374948?*x + 93.33939353874569?) - """ rr = f.roots() cr = [(r, e) for r, e in f.roots(QQbar) if r.imag() > 0] @@ -1681,7 +1679,7 @@ def _element_constructor_(self, x): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -1850,11 +1848,11 @@ def ngens(self): @cached_method def zeta(self, n=4): r""" - Return a primitive `n`'th root of unity, specifically `\exp(2*\pi*i/n)`. + Return a primitive `n`-th root of unity, specifically `\exp(2*\pi*i/n)`. INPUT: - - ``n`` (integer) -- default 4 + - ``n`` -- integer (default: 4) EXAMPLES:: @@ -1933,7 +1931,7 @@ def random_element(self, poly_degree=2, *args, **kwds): INPUT: - - ``poly_degree`` -- default: 2; degree of the random polynomial over + - ``poly_degree`` -- (default: 2) degree of the random polynomial over the integers of which the returned algebraic number is a root. This is not necessarily the degree of the minimal polynomial of the number. Increase this parameter to achieve a greater diversity of @@ -2110,7 +2108,6 @@ def _factor_univariate_polynomial(self, f): -1 sage: QQbar._factor_univariate_polynomial(EllipticCurve('11a1').change_ring(QQbar).division_polynomial(5)) # needs sage.schemes (5) * (x - 16) * (x - 5) * (x - 1.959674775249769?) * (x - 1.427050983124843? - 3.665468789467727?*I) * (x - 1.427050983124843? + 3.665468789467727?*I) * (x + 0.9549150281252629? - 0.8652998037182486?*I) * (x + 0.9549150281252629? + 0.8652998037182486?*I) * (x + 1.927050983124843? - 1.677599044300515?*I) * (x + 1.927050983124843? + 1.677599044300515?*I) * (x + 2.959674775249769?) * (x + 6.545084971874737? - 7.106423590645660?*I) * (x + 6.545084971874737? + 7.106423590645660?*I) - """ from sage.structure.factorization import Factorization return Factorization([(f.parent()([-r, 1]), e) for r, e in f.roots()], @@ -2202,9 +2199,9 @@ def tail_prec_seq(): def rational_exact_root(r, d): r""" - Check whether the rational `r` is an exact `d`'th power. + Check whether the rational `r` is an exact `d`-th power. - If so, this returns the `d`'th root of `r`; otherwise, this returns ``None``. + If so, this returns the `d`-th root of `r`; otherwise, this returns ``None``. EXAMPLES:: @@ -2336,7 +2333,7 @@ def do_polred(poly, threshold=32): INPUT: - ``poly`` -- a monic irreducible polynomial with integer coefficients - - ``threshold`` -- an integer used to decide whether to run ``polredbest`` + - ``threshold`` -- integer used to decide whether to run ``polredbest`` OUTPUT: @@ -2544,17 +2541,17 @@ def number_field_elements_from_algebraics(numbers, minimal=False, - ``numbers`` -- a number or list of numbers - - ``minimal`` -- Boolean (default: ``False``). Whether to minimize the + - ``minimal`` -- boolean (default: ``False``); whether to minimize the degree of the extension - - ``same_field`` -- Boolean (default: ``False``). See below + - ``same_field`` -- boolean (default: ``False``); see below - - ``embedded`` -- Boolean (default: ``False``). Whether to make the + - ``embedded`` -- boolean (default: ``False``); whether to make the NumberField embedded - ``name`` -- string (default: ``'a'``); name of the primitive element - - ``prec`` -- integer (default: ``53``). The number of bit of precision + - ``prec`` -- integer (default: 53); the number of bit of precision to guarantee finding real roots OUTPUT: @@ -2934,14 +2931,14 @@ def cmp_elements_with_same_minpoly(a, b, p): INPUT: - - ``a`` and ``b`` -- elements of the algebraic or the real algebraic field + - ``a``, ``b`` -- elements of the algebraic or the real algebraic field with same minimal polynomial - ``p`` -- the minimal polynomial OUTPUT: - `-1`, `0`, `1`, `None` depending on whether `a < b`, `a = b` or `a > b` or + `-1`, `0`, `1`, ``None`` depending on whether `a < b`, `a = b` or `a > b` or the function did not succeed with the given precision of `a` and `b`. EXAMPLES:: @@ -3101,7 +3098,7 @@ def __reduce__(self): def __hash__(self): r""" - Return a hash value for self. This will depend on the order that + Return a hash value for ``self``. This will depend on the order that commands get executed at load time, so we do not test the value that is returned, just that it does not raise an error. @@ -3158,7 +3155,7 @@ def is_complex(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -3183,7 +3180,7 @@ def _repr_(self): def root_as_algebraic(self): r""" - Return the root attached to self as an algebraic number. + Return the root attached to ``self`` as an algebraic number. EXAMPLES:: @@ -3209,7 +3206,7 @@ def is_trivial(self): def field(self): r""" - Return the number field attached to self. + Return the number field attached to ``self``. EXAMPLES:: @@ -3429,7 +3426,6 @@ def super_poly(self, super, checked=None): -a^3 + 3*a sage: gen3.super_poly(gen2_3) a^2 - 2 - """ if checked is None: checked = {} @@ -3450,7 +3446,7 @@ def super_poly(self, super, checked=None): def __call__(self, elt): """ - Takes an algebraic number which is represented as either a + Take an algebraic number which is represented as either a rational or a number field element, and which is in a subfield of the field generated by this generator. Lifts the number into the field of this generator, and returns either a @@ -3514,7 +3510,7 @@ def is_simple(self): Check whether this descriptor represents a value with the same algebraic degree as the number field associated with the descriptor. - This returns ``True`` if self is an ``ANRational``, or a minimal + This returns ``True`` if ``self`` is an ``ANRational``, or a minimal ``ANExtensionElement``. EXAMPLES:: @@ -3544,7 +3540,7 @@ def is_simple(self): def neg(self, n): r""" - Negation of self. + Negation of ``self``. EXAMPLES:: @@ -3570,7 +3566,7 @@ def invert(self, n): def abs(self, n): r""" - Absolute value of self. + Absolute value of ``self``. EXAMPLES:: @@ -3583,7 +3579,7 @@ def abs(self, n): def real(self, n): r""" - Real part of self. + Real part of ``self``. EXAMPLES:: @@ -3599,7 +3595,7 @@ def real(self, n): def imag(self, n): r""" - Imaginary part of self. + Imaginary part of ``self``. EXAMPLES:: @@ -3615,7 +3611,7 @@ def imag(self, n): def conjugate(self, n): r""" - Complex conjugate of self. + Complex conjugate of ``self``. EXAMPLES:: @@ -3631,8 +3627,8 @@ def conjugate(self, n): def norm(self, n): r""" - Field norm of self from `\overline{\QQ}` to its real subfield - `\mathbf{A}`, i.e.~the square of the usual complex absolute value. + Field norm of ``self`` from `\overline{\QQ}` to its real subfield + `\mathbf{A}`, i.e. the square of the usual complex absolute value. EXAMPLES:: @@ -4018,7 +4014,6 @@ def __hash__(self): sage: h2 = hash(QQbar(1/2^100)) sage: hash(h1) == hash(h2) True - """ # The only way I can think of to hash algebraic numbers without @@ -4195,7 +4190,7 @@ def is_square(self): (boolean) ``True`` in all cases for elements of ``QQbar``; - ``True`` for non-negative elements of ``AA``; + ``True`` for nonnegative elements of ``AA``; otherwise ``False`` EXAMPLES:: @@ -4233,13 +4228,13 @@ def sqrt(self, all=False, extend=True): INPUT: - - ``extend`` -- bool (default: ``True``); ignored if self is in QQbar, or - positive in AA. If self is negative in AA, do the following: if True, - return a square root of self in QQbar, otherwise raise a ValueError. + - ``extend`` -- boolean (default: ``True``); ignored if ``self`` is in QQbar, or + positive in AA. If ``self`` is negative in AA, do the following: if True, + return a square root of ``self`` in QQbar, otherwise raise a :exc:`ValueError`. - - ``all`` -- bool (default: ``False``); if True, return a list of all square - roots. If False, return just one square root, or raise an ValueError - if self is a negative element of AA and extend=False. + - ``all`` -- boolean (default: ``False``); if ``True``, return a list of all square + roots. If ``False``, return just one square root, or raise an :exc:`ValueError` + if ``self`` is a negative element of AA and extend=False. OUTPUT: @@ -4314,12 +4309,12 @@ def nth_root(self, n, all=False): INPUT: - - ``all`` -- bool (default: ``False``). If ``True``, return a list of - all `n`-th roots as complex algebraic numbers. + - ``all`` -- boolean (default: ``False``); if ``True``, return a list of + all `n`-th roots as complex algebraic numbers .. WARNING:: - Note that for odd `n`, all=`False` and negative real numbers, + Note that for odd `n`, all ``False`` and negative real numbers, ``AlgebraicReal`` and ``AlgebraicNumber`` values give different answers: ``AlgebraicReal`` values prefer real results, and ``AlgebraicNumber`` values return the principal root. @@ -4375,14 +4370,14 @@ def as_number_field_element(self, minimal=False, embedded=False, prec=53): INPUT: - - ``minimal`` -- Boolean (default: ``False``). Whether to minimize the - degree of the extension. + - ``minimal`` -- boolean (default: ``False``); whether to minimize the + degree of the extension - - ``embedded`` -- Boolean (default: ``False``). Whether to make the - NumberField embedded. + - ``embedded`` -- boolean (default: ``False``); whether to make the + NumberField embedded - - ``prec`` -- integer (default: ``53``). The number of bit of precision - to guarantee finding real roots. + - ``prec`` -- integer (default: 53); the number of bit of precision + to guarantee finding real roots This may not return the smallest such number field, unless ``minimal=True`` is specified. @@ -4684,7 +4679,7 @@ def interval_fast(self, field): def interval_diameter(self, diam): """ - Compute an interval representation of self with ``diameter()`` at + Compute an interval representation of ``self`` with ``diameter()`` at most ``diam``. The precision of the returned value is unpredictable. EXAMPLES:: @@ -4709,7 +4704,7 @@ def interval_diameter(self, diam): def interval(self, field): r""" Given an interval (or ball) field (real or complex, as appropriate) of - precision `p`, compute an interval representation of self with + precision `p`, compute an interval representation of ``self`` with ``diameter()`` at most `2^{-p}`; then round that representation into the given field. Here ``diameter()`` is relative diameter for intervals not containing 0, and absolute diameter for @@ -5084,9 +5079,9 @@ def _richcmp_(self, other, op): def _mpfr_(self, field): r""" - Given a ``RealField``, compute a good approximation to self in - that field. Works only if the imaginary component of self is - exactly zero; otherwise it raises a ``ValueError``. + Given a ``RealField``, compute a good approximation to ``self`` in + that field. Works only if the imaginary component of ``self`` is + exactly zero; otherwise it raises a :exc:`ValueError`. EXAMPLES:: @@ -5097,15 +5092,15 @@ def _mpfr_(self, field): sage: QQbar.zeta(3)._mpfr_(RR) Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary part to algebraic real + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real """ return AA(self)._mpfr_(field) def __float__(self): r""" - Compute a good float approximation to self. Works only if the - imaginary component of self is exactly zero; otherwise it - raises a ``ValueError``. + Compute a good float approximation to ``self``. Works only if the + imaginary component of ``self`` is exactly zero; otherwise it + raises a :exc:`ValueError`. EXAMPLES:: @@ -5116,13 +5111,13 @@ def __float__(self): sage: float(QQbar.zeta(3)) Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary part to algebraic real + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real """ return AA(self).__float__() def __complex__(self): r""" - Compute a good complex approximation to self. + Compute a good complex approximation to ``self``. EXAMPLES:: @@ -5135,7 +5130,7 @@ def __complex__(self): def _complex_double_(self, cdf): r""" - Compute a good approximation to self in CDF. + Compute a good approximation to ``self`` in CDF. EXAMPLES:: @@ -5159,7 +5154,7 @@ def _interval_fast(self, prec): def _integer_(self, ZZ=None): """ - Return self as an Integer. + Return ``self`` as an Integer. EXAMPLES:: @@ -5170,7 +5165,7 @@ def _integer_(self, ZZ=None): sage: QQbar.zeta(6)._integer_() Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary part to algebraic real + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real sage: # needs sage.symbolic sage: QQbar(sqrt(17))._integer_() @@ -5188,7 +5183,7 @@ def _integer_(self, ZZ=None): def _rational_(self): """ - Return self as a Rational. + Return ``self`` as a Rational. EXAMPLES:: @@ -5199,7 +5194,7 @@ def _rational_(self): sage: (QQbar.zeta(7)^3)._rational_() Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary part to algebraic real + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real sage: # needs sage.symbolic sage: QQbar(sqrt(2))._rational_() @@ -5300,7 +5295,7 @@ def interval_exact(self, field): def _complex_mpfr_field_(self, field): r""" - Compute an approximation to self in the given field, which must + Compute an approximation to ``self`` in the given field, which must be a complex field. EXAMPLES:: @@ -5639,7 +5634,7 @@ def _richcmp_(self, other, op): def _integer_(self, Z=None): """ - Return self as an Integer. + Return ``self`` as an Integer. EXAMPLES:: @@ -5775,7 +5770,7 @@ def trunc(self): def _rational_(self): """ - Return self as a Rational. + Return ``self`` as a Rational. EXAMPLES:: @@ -6026,7 +6021,8 @@ def sign(self): def _interval_fast(self, prec): r""" - Compute an approximation to this ``AlgebraicReal`` object in a real interval field of precision prec. + Compute an approximation to this ``AlgebraicReal`` object in a real + interval field of precision ``prec``. EXAMPLES:: @@ -6074,7 +6070,6 @@ def interval_exact(self, field): sage: from sage.rings.qqbar import QQbar_hash_offset sage: len([(r[0] + QQbar_hash_offset).interval_exact(CIF) for r in roots]) 7 - """ for extra in (0, 40): target = RR(1.0) >> (field.prec() + extra) @@ -6163,7 +6158,7 @@ def real_number(self, field): def __float__(self): r""" - Compute a good float approximation to self. + Compute a good float approximation to ``self``. EXAMPLES:: @@ -6295,14 +6290,14 @@ class AlgebraicNumberPowQQAction(Action): - ``G`` -- must be ``QQ`` - - ``S`` -- the parent on which to act, either ``AA`` or ``QQbar``. + - ``S`` -- the parent on which to act, either ``AA`` or ``QQbar`` .. NOTE:: - To compute ``x ^ (a/b)``, we take the `b`'th root of `x`; then - we take that to the `a`'th power. If `x` is a negative algebraic - real and `b` is odd, take the real `b`'th root; otherwise take - the principal `b`'th root. + To compute ``x ^ (a/b)``, we take the `b`-th root of `x`; then + we take that to the `a`-th power. If `x` is a negative algebraic + real and `b` is odd, take the real `b`-th root; otherwise take + the principal `b`-th root. EXAMPLES: @@ -6460,7 +6455,7 @@ def _act_(self, e, x): if prec is None: # We know that x.real() < 0, since x._value # crosses the negative real line and x._value - # is known to be non-zero. + # is known to be nonzero. isgn = x.imag().sign() val = x._value argument = val.argument() @@ -6549,7 +6544,7 @@ def __reduce__(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -6589,7 +6584,8 @@ def handle_sage_input(self, sib, coerce, is_qqbar): def _interval_fast(self, prec): r""" - Return an approximation to self in a real interval field of precision prec. + Return an approximation to ``self`` in a real interval field of + precision ``prec``. EXAMPLES:: @@ -6612,7 +6608,7 @@ def generator(self): def is_complex(self): r""" - Return ``False``, since rational numbers are real + Return ``False``, since rational numbers are real. EXAMPLES:: @@ -6635,7 +6631,7 @@ def exactify(self): def is_simple(self): """ - Checks whether this descriptor represents a value with the same + Check whether this descriptor represents a value with the same algebraic degree as the number field associated with the descriptor. This is always true for rational numbers. @@ -6701,7 +6697,7 @@ def abs(self, n): def rational_argument(self, n): r""" - Return the argument of self divided by `2 \pi`, or ``None`` if this + Return the argument of ``self`` divided by `2 \pi`, or ``None`` if this element is 0. EXAMPLES:: @@ -6907,7 +6903,7 @@ def _sage_input_(self, sib, coerce): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -7097,7 +7093,7 @@ def __reduce__(self): def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -7177,7 +7173,7 @@ def handle_sage_input(self, sib, coerce, is_qqbar): def is_complex(self): r""" Whether this is a root in `\overline{\QQ}` (rather than `\mathbf{A}`). - Note that this may return True even if the root is actually real, as + Note that this may return ``True`` even if the root is actually real, as the second example shows; it does *not* trigger exact computation to see if the root is real. @@ -7216,7 +7212,7 @@ def conjugate(self, n): def refine_interval(self, interval, prec): r""" - Takes an interval which is assumed to enclose exactly one root + Take an interval which is assumed to enclose exactly one root of the polynomial (or, with multiplicity=`k`, exactly one root of the `k-1`-st derivative); and a precision, in bits. @@ -7247,7 +7243,7 @@ def refine_interval(self, interval, prec): def _real_refine_interval(self, interval, prec): r""" - Does the calculation for ``refine_interval``. + Do the calculation for ``refine_interval``. EXAMPLES:: @@ -7389,7 +7385,7 @@ def _real_refine_interval(self, interval, prec): def _complex_refine_interval(self, interval, prec): r""" - Takes an interval which is assumed to enclose exactly one root + Take an interval which is assumed to enclose exactly one root of the polynomial (or, with multiplicity=`k`, exactly one root of the `k-1`-st derivative); and a precision, in bits. @@ -7981,8 +7977,8 @@ def simplify(self, n): INPUT: - - ``n`` -- The element of ``AA`` or ``QQbar`` corresponding - to this descriptor. + - ``n`` -- the element of ``AA`` or ``QQbar`` corresponding + to this descriptor EXAMPLES:: @@ -8103,7 +8099,6 @@ def conjugate(self, n): sage: (b.conjugate("random").generator() == c.generator() # needs sage.symbolic ....: and b.conjugate("random").field_element_value() == c.field_element_value()) True - """ if self._exactly_real: return self @@ -8115,7 +8110,7 @@ def conjugate(self, n): def norm(self, n): r""" - Norm of ``self`` (square of complex absolute value) + Norm of ``self`` (square of complex absolute value). EXAMPLES:: @@ -8620,7 +8615,8 @@ def is_complex(self): def _interval_fast(self, prec): r""" - Calculate an approximation to self in an interval field of precision prec. + Calculate an approximation to ``self`` in an interval field of + precision ``prec``. EXAMPLES:: diff --git a/src/sage/rings/qqbar_decorators.py b/src/sage/rings/qqbar_decorators.py index 13d6d562824..7343a0b9b08 100644 --- a/src/sage/rings/qqbar_decorators.py +++ b/src/sage/rings/qqbar_decorators.py @@ -86,13 +86,13 @@ def wrapper(*args, **kwds): from sage.misc.flatten import flatten from sage.rings.polynomial.polynomial_element import Polynomial from sage.rings.polynomial.multi_polynomial import MPolynomial - from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence, is_PolynomialSequence + from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence, PolynomialSequence_generic from sage.rings.ideal import Ideal, Ideal_generic from sage.rings.abc import AlgebraicField_common if not any(isinstance(a, (Polynomial, MPolynomial, Ideal_generic)) and isinstance(a.base_ring(), AlgebraicField_common) - or is_PolynomialSequence(a) + or isinstance(a, PolynomialSequence_generic) and isinstance(a.ring().base_ring(), AlgebraicField_common) for a in args): return func(*args, **kwds) @@ -123,7 +123,7 @@ def forward_map(item): return item.map_coefficients(elem_dict.__getitem__, new_base_ring=numfield) elif isinstance(item, MPolynomial): return item.map_coefficients(elem_dict.__getitem__, new_base_ring=numfield) - elif is_PolynomialSequence(item): + elif isinstance(item, PolynomialSequence_generic): return PolynomialSequence(map(forward_map, item), immutable=item.is_immutable()) elif isinstance(item, list): @@ -144,7 +144,7 @@ def reverse_map(item): return item.map_coefficients(morphism) elif isinstance(item, MPolynomial): return item.map_coefficients(morphism) - elif is_PolynomialSequence(item): + elif isinstance(item, PolynomialSequence_generic): return PolynomialSequence(map(reverse_map, item), immutable=item.is_immutable()) elif isinstance(item, list): diff --git a/src/sage/rings/quotient_ring.py b/src/sage/rings/quotient_ring.py index 468f81115b7..b2d3c52bca3 100644 --- a/src/sage/rings/quotient_ring.py +++ b/src/sage/rings/quotient_ring.py @@ -130,7 +130,7 @@ def QuotientRing(R, I, names=None, **kwds): r""" - Creates a quotient ring of the ring `R` by the twosided ideal `I`. + Create a quotient ring of the ring `R` by the twosided ideal `I`. Variables are labeled by ``names`` (if the quotient ring is a quotient of a polynomial ring). If ``names`` isn't given, 'bar' will be appended @@ -138,15 +138,15 @@ def QuotientRing(R, I, names=None, **kwds): INPUT: - - ``R`` -- a ring. + - ``R`` -- a ring - - ``I`` -- a twosided ideal of `R`. + - ``I`` -- a twosided ideal of `R` - ``names`` -- (optional) a list of strings to be used as names for - the variables in the quotient ring `R/I`. + the variables in the quotient ring `R/I` - further named arguments that will be passed to the constructor - of the quotient ring instance. + of the quotient ring instance OUTPUT: `R/I` - the quotient ring `R` mod the ideal `I` @@ -342,7 +342,7 @@ def QuotientRing(R, I, names=None, **kwds): def is_QuotientRing(x): """ - Tests whether or not ``x`` inherits from :class:`QuotientRing_nc`. + Test whether or not ``x`` inherits from :class:`QuotientRing_nc`. EXAMPLES:: @@ -351,6 +351,10 @@ def is_QuotientRing(x): sage: I = R.ideal([4 + 3*x + x^2, 1 + x^2]) sage: S = R.quotient_ring(I) sage: is_QuotientRing(S) + doctest:warning... + DeprecationWarning: The function is_QuotientRing is deprecated; + use 'isinstance(..., QuotientRing_nc)' instead. + See https://github.com/sagemath/sage/issues/38266 for details. True sage: is_QuotientRing(R) False @@ -366,6 +370,10 @@ def is_QuotientRing(x): sage: is_QuotientRing(F) False """ + from sage.misc.superseded import deprecation + deprecation(38266, + "The function is_QuotientRing is deprecated; " + "use 'isinstance(..., QuotientRing_nc)' instead.") return isinstance(x, QuotientRing_nc) @@ -455,11 +463,11 @@ def __init__(self, R, I, names, category=None): INPUT: - - ``R`` -- a ring. + - ``R`` -- a ring - - ``I`` -- a twosided ideal of `R`. + - ``I`` -- a twosided ideal of `R` - - ``names`` -- a list of generator names. + - ``names`` -- list of generator names EXAMPLES:: @@ -474,7 +482,6 @@ def __init__(self, R, I, names, category=None): -b*c sage: a^3 -b*c*a - b*c*b - b*c*c - """ if R not in _Rings: raise TypeError("The first argument must be a ring, but %s is not" % R) @@ -511,7 +518,7 @@ def __init__(self, R, I, names, category=None): def construction(self): """ - Returns the functorial construction of ``self``. + Return the functorial construction of ``self``. EXAMPLES:: @@ -591,7 +598,7 @@ def is_commutative(self): This is certainly the case if the cover ring is commutative. Otherwise, if this ring has a finite number of generators, it is tested whether they commute. If the number of generators is - infinite, a ``NotImplementedError`` is raised. + infinite, a :exc:`NotImplementedError` is raised. AUTHOR: @@ -623,7 +630,6 @@ def is_commutative(self): sage: R = F.quo(J) sage: R.is_commutative() True - """ try: if self.__R.is_commutative(): @@ -747,7 +753,6 @@ def lifting_map(self): To: Full MatrixSpace of 2 by 2 dense matrices over Finite Field of size 5 Defn: Choice of lifting map - """ try: return self.__lift @@ -783,7 +788,6 @@ def lift(self, x=None): Defn: Choice of lifting map sage: S.lift(S.0) == x # needs sage.libs.singular True - """ if x is None: return self.lifting_map() @@ -795,11 +799,9 @@ def retract(self,x): INPUT: - - ``x`` -- An element of the cover ring + - ``x`` -- an element of the cover ring - OUTPUT: - - The image of the given element in ``self``. + OUTPUT: the image of the given element in ``self`` EXAMPLES:: @@ -807,7 +809,6 @@ def retract(self,x): sage: S = R.quotient(x^2 + y^2) sage: S.retract((x+y)^2) # needs sage.libs.singular 2*xbar*ybar - """ return self.cover()(x) @@ -831,7 +832,7 @@ def characteristic(self): def defining_ideal(self): r""" - Returns the ideal generating this quotient ring. + Return the ideal generating this quotient ring. EXAMPLES: @@ -859,7 +860,7 @@ def defining_ideal(self): @cached_method def is_field(self, proof=True): r""" - Returns ``True`` if the quotient ring is a field. Checks to see if the + Return ``True`` if the quotient ring is a field. Checks to see if the defining ideal is maximal. TESTS:: @@ -889,9 +890,9 @@ def is_field(self, proof=True): def is_integral_domain(self, proof=True): r""" With ``proof`` equal to ``True`` (the default), this function may - raise a ``NotImplementedError``. + raise a :exc:`NotImplementedError`. - When ``proof`` is ``False``, if ``True`` is returned, then self is + When ``proof`` is ``False``, if ``True`` is returned, then ``self`` is definitely an integral domain. If the function returns ``False``, then either ``self`` is not an integral domain or it was unable to determine whether or not ``self`` is an integral domain. @@ -960,7 +961,7 @@ def is_noetherian(self): def cover_ring(self): r""" - Returns the cover ring of the quotient ring: that is, the original + Return the cover ring of the quotient ring: that is, the original ring `R` from which we modded out an ideal, `I`. EXAMPLES:: @@ -1177,7 +1178,7 @@ def __richcmp__(self, other, op): def ngens(self): r""" - Returns the number of generators for this quotient ring. + Return the number of generators for this quotient ring. .. TODO:: @@ -1216,7 +1217,7 @@ def ngens(self): def gen(self, i=0): r""" - Returns the `i`-th generator for this quotient ring. + Return the `i`-th generator for this quotient ring. EXAMPLES:: @@ -1247,7 +1248,7 @@ def gen(self, i=0): def _singular_(self, singular=None): """ - Returns the Singular quotient ring of ``self`` if the base ring is + Return the Singular quotient ring of ``self`` if the base ring is coercible to Singular. If a valid Singular representation is found it is used otherwise a @@ -1255,8 +1256,8 @@ def _singular_(self, singular=None): INPUT: - - ``singular`` -- Singular instance (default: the - default Singular instance) + - ``singular`` -- Singular instance (default: the + default Singular instance) .. NOTE:: @@ -1291,7 +1292,7 @@ def _singular_(self, singular=None): def _singular_init_(self, singular=None): """ - Returns a newly created Singular quotient ring matching ``self`` if + Return a newly created Singular quotient ring matching ``self`` if the base ring is coercible to Singular. See ``_singular_`` @@ -1319,7 +1320,7 @@ def _magma_init_(self, magma): INPUT: - - ``magma`` -- a Magma instance + - ``magma`` -- a Magma instance EXAMPLES:: @@ -1380,7 +1381,7 @@ def random_element(self): class QuotientRing_generic(QuotientRing_nc, ring.CommutativeRing): r""" - Creates a quotient ring of a *commutative* ring `R` by the ideal `I`. + Create a quotient ring of a *commutative* ring `R` by the ideal `I`. EXAMPLES:: @@ -1397,11 +1398,11 @@ def __init__(self, R, I, names, category=None): INPUT: - - ``R`` -- a ring that is a :class:`~sage.rings.ring.CommutativeRing`. + - ``R`` -- a ring that is a :class:`~sage.rings.ring.CommutativeRing` - - ``I`` -- an ideal of `R`. + - ``I`` -- an ideal of `R` - - ``names`` -- a list of generator names. + - ``names`` -- list of generator names TESTS:: @@ -1466,7 +1467,6 @@ def _macaulay2_init_(self, macaulay2=None): --------------------- 2 2 (x + 3x + 4, x + 1) - """ if macaulay2 is None: from sage.interfaces.macaulay2 import macaulay2 as m2_default diff --git a/src/sage/rings/quotient_ring_element.py b/src/sage/rings/quotient_ring_element.py index 9572de38f10..6699ae9f74b 100644 --- a/src/sage/rings/quotient_ring_element.py +++ b/src/sage/rings/quotient_ring_element.py @@ -37,7 +37,7 @@ class QuotientRingElement(RingElement): - ``rep`` -- a representative of the element in `R`; this is used as the internal representation of the element - - ``reduce`` -- bool (default: ``True``) -- if True, then the + - ``reduce`` -- boolean (default: ``True``); if ``True``, then the internal representation of the element is ``rep`` reduced modulo the ideal `I` @@ -121,7 +121,7 @@ def _reduce_(self): def lift(self): """ - If self is an element of `R/I`, then return self as an + If ``self`` is an element of `R/I`, then return ``self`` as an element of `R`. EXAMPLES:: @@ -137,7 +137,7 @@ def lift(self): def __bool__(self): """ - Return ``True`` if quotient ring element is non-zero in the + Return ``True`` if quotient ring element is nonzero in the quotient ring `R/I`, by determining whether the element is in `I`. @@ -159,7 +159,7 @@ def __bool__(self): def is_unit(self): """ - Return ``True`` if self is a unit in the quotient ring. + Return ``True`` if ``self`` is a unit in the quotient ring. EXAMPLES:: @@ -209,7 +209,6 @@ def _repr_(self): sage: Q = S.quo(I) sage: Q.0 Sq(1) - """ from sage.structure.parent_gens import localvars P = self.parent() @@ -462,7 +461,7 @@ def _im_gens_(self, codomain, im_gens, base_map=None): - ``codomain`` -- a ring - - ``im_gens`` -- a tuple of elements `f(x)` in ``codomain``, + - ``im_gens`` -- tuple of elements `f(x)` in ``codomain``, one for each `x` in ``self.parent().gens()``, that define a homomorphism `f` from ``self.parent()`` to ``codomain`` @@ -493,7 +492,7 @@ def _im_gens_(self, codomain, im_gens, base_map=None): def __int__(self): """ - Try to convert self (an element of `R/I`) to an integer by + Try to convert ``self`` (an element of `R/I`) to an integer by converting its lift in `R` to an integer. Return a TypeError if no such conversion can be found. @@ -725,7 +724,6 @@ def lm(self): sage: (a+3*a*b+b).lm() # needs sage.libs.singular a*b - """ return self.__class__(self.parent(), self.__rep.lm()) @@ -783,9 +781,7 @@ def monomials(self): """ Return the monomials in ``self``. - OUTPUT: - - A list of monomials. + OUTPUT: list of monomials EXAMPLES:: @@ -803,12 +799,11 @@ def monomials(self): def _singular_(self, singular=None): """ - Return Singular representation of self. + Return Singular representation of ``self``. INPUT: - - ``singular`` -- a non-standard interpreter may be - provided + - ``singular`` -- a non-standard interpreter may be provided EXAMPLES:: @@ -851,7 +846,7 @@ def _singular_(self, singular=None): def _magma_init_(self, magma): """ - Returns the Magma representation of this quotient ring element. + Return the Magma representation of this quotient ring element. EXAMPLES:: @@ -943,7 +938,7 @@ def reduce(self, G): INPUT: - - ``G`` -- a list of quotient ring elements + - ``G`` -- list of quotient ring elements .. WARNING:: diff --git a/src/sage/rings/rational.pyx b/src/sage/rings/rational.pyx index 8a591520d98..272650abeef 100644 --- a/src/sage/rings/rational.pyx +++ b/src/sage/rings/rational.pyx @@ -200,12 +200,10 @@ cpdef Integer integer_rational_power(Integer a, Rational b): INPUT: - - a -- an ``Integer`` - - b -- a nonnegative ``Rational`` + - ``a`` -- an ``Integer`` + - ``b`` -- a nonnegative ``Rational`` - OUTPUT: - - `a^b` as an ``Integer`` or ``None`` + OUTPUT: `a^b` as an ``Integer`` or ``None`` EXAMPLES:: @@ -519,9 +517,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``x`` -- object (default: ``None``) + - ``x`` -- object (default: ``None``) - - ``base`` -- base if ``x`` is a string + - ``base`` -- base if ``x`` is a string EXAMPLES:: @@ -708,9 +706,7 @@ cdef class Rational(sage.structure.element.FieldElement): Return a list with the rational element in it, to be compatible with the method for number fields. - OUTPUT: - - - ``list`` -- the list ``[self]`` + OUTPUT: the list ``[self]`` EXAMPLES:: @@ -720,14 +716,14 @@ cdef class Rational(sage.structure.element.FieldElement): """ return [ self ] - def continued_fraction_list(self, type="std"): + def continued_fraction_list(self, type='std'): r""" Return the list of partial quotients of this rational number. INPUT: - - ``type`` -- either "std" (the default) for the standard continued - fractions or "hj" for the Hirzebruch-Jung ones. + - ``type`` -- either ``'std'`` (the default) for the standard continued + fractions or ``'hj'`` for the Hirzebruch-Jung ones EXAMPLES:: @@ -846,9 +842,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``left, right`` -- objects + - ``left``, ``right`` -- objects - - ``op`` -- integer + - ``op`` -- integer EXAMPLES:: @@ -1118,9 +1114,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``codomain`` -- object (usually a ring) + - ``codomain`` -- object (usually a ring) - - ``im_gens`` -- list of elements of ``codomain`` + - ``im_gens`` -- list of elements of ``codomain`` EXAMPLES:: @@ -1159,12 +1155,11 @@ cdef class Rational(sage.structure.element.FieldElement): def valuation(self, p): r""" - Return the power of ``p`` in the factorization of self. + Return the power of ``p`` in the factorization of ``self``. INPUT: - - - ``p`` -- a prime number + - ``p`` -- a prime number OUTPUT: @@ -1206,10 +1201,10 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``p`` -- a prime number + - ``p`` -- a prime number - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -1245,8 +1240,8 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -1281,8 +1276,8 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -1324,8 +1319,8 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -1356,8 +1351,8 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``prec`` (int) -- desired floating point precision (default: - default :class:`RealField` precision). + - ``prec`` -- integer (default: default :class:`RealField` precision); + desired floating point precision OUTPUT: @@ -1396,7 +1391,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return whether or not this rational number is a square. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -1422,10 +1417,10 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - ``L`` -- a number field - - ``element`` -- (default: ``False``) boolean whether to also output + - ``element`` -- boolean (default: ``False``); whether to also output an element of which ``self`` is a norm - - ``proof`` -- If ``True``, then the output is correct unconditionally. - If ``False``, then the output assumes GRH. + - ``proof`` -- if ``True``, then the output is correct unconditionally; + if ``False``, then the output assumes GRH OUTPUT: @@ -1534,7 +1529,7 @@ cdef class Rational(sage.structure.element.FieldElement): If `K` is known to be Galois, set ``extra_primes = 0`` (in this case, ``self`` is a norm iff `b = 1`). - If ``extra_primes`` is non-zero, the program adds to `S` the following + If ``extra_primes`` is nonzero, the program adds to `S` the following prime ideals, depending on the sign of extra_primes. If ``extra_primes > 0``, the ideals of norm less than ``extra_primes``. And if ``extra_primes < 0``, the ideals dividing ``extra_primes``. @@ -1546,10 +1541,10 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``K`` -- a number field - - ``proof`` -- whether to certify the output of bnfinit. - If ``False``, then correctness of the output depends on GRH. - - ``extra_primes`` -- an integer as explained above + - ``K`` -- a number field + - ``proof`` -- whether to certify the output of bnfinit; + if ``False``, then correctness of the output depends on GRH + - ``extra_primes`` -- integer as explained above OUTPUT: @@ -1587,9 +1582,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``expected_value`` -- (bool) whether or not this rational is expected - be a perfect power. This does not affect the correctness of the - output, only the runtime. + - ``expected_value`` -- boolean; whether or not this rational is + expected to be a perfect power. This does not affect the correctness + of the output, only the runtime. If ``expected_value`` is ``False`` (default) it will check the smallest of the numerator and denominator is a perfect power @@ -1740,9 +1735,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``p`` -- a prime number, or ``infinity`` + - ``p`` -- a prime number, or ``infinity`` - - ``check`` -- (default: ``True``); check if `p` is prime + - ``check`` -- boolean (default: ``True``); check if `p` is prime EXAMPLES:: @@ -1795,13 +1790,13 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``p`` -- a prime + - ``p`` -- a prime OUTPUT: - - ``int`` -- the `p`-adic valuation of this rational + - integer; the `p`-adic valuation of this rational - - ``Rational`` -- `p`-adic unit part of ``self`` + - ``Rational``; `p`-adic unit part of ``self`` EXAMPLES:: @@ -1857,7 +1852,7 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``S`` -- list or tuple of primes. + - ``S`` -- list or tuple of primes OUTPUT: rational @@ -1881,7 +1876,6 @@ cdef class Rational(sage.structure.element.FieldElement): 0 sage: QQ(-700/99).prime_to_S_part([]) -700/99 - """ if self.is_zero(): return self @@ -1896,17 +1890,17 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``prec`` -- integer (default: ``None``): if ``None``, returns - an exact square root; otherwise returns a numerical square root if - necessary, to the given bits of precision. + - ``prec`` -- integer (default: ``None``); if ``None``, returns + an exact square root; otherwise returns a numerical square root if + necessary, to the given bits of precision. - - ``extend`` -- bool (default: ``True``); if ``True``, return a - square root in an extension ring, if necessary. Otherwise, raise a - ``ValueError`` if the square is not in the base ring. Ignored if ``prec`` - is not ``None``. + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in an extension ring, if necessary. Otherwise, raise a + :exc:`ValueError` if the square is not in the base ring. Ignored if + ``prec`` is not ``None``. - - ``all`` -- bool (default: ``False``); if ``True``, return all - square roots of ``self`` (a list of length 0, 1, or 2). + - ``all`` -- boolean (default: ``False``); if ``True``, return all + square roots of ``self`` (a list of length 0, 1, or 2) EXAMPLES:: @@ -2060,12 +2054,12 @@ cdef class Rational(sage.structure.element.FieldElement): def nth_root(self, int n): r""" - Computes the `n`-th root of ``self``, or raises a - ``ValueError`` if ``self`` is not a perfect `n`-th power. + Compute the `n`-th root of ``self``, or raises a + :exc:`ValueError` if ``self`` is not a perfect `n`-th power. INPUT: - - ``n`` -- integer (must fit in C ``int`` type) + - ``n`` -- integer (must fit in C ``int`` type) AUTHORS: @@ -2124,11 +2118,11 @@ cdef class Rational(sage.structure.element.FieldElement): def is_nth_power(self, int n): r""" - Return ``True`` if self is an `n`-th power, else ``False``. + Return ``True`` if ``self`` is an `n`-th power, else ``False``. INPUT: - - ``n`` -- integer (must fit in C ``int`` type) + - ``n`` -- integer (must fit in C ``int`` type) .. NOTE:: @@ -2155,7 +2149,6 @@ cdef class Rational(sage.structure.element.FieldElement): False sage: QQ(-25).is_nth_power(2) False - """ if n == 0: raise ValueError("n cannot be zero") @@ -2172,7 +2165,7 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``base`` -- integer (default: 10); base must be between 2 and 36. + - ``base`` -- integer (default: 10); base must be between 2 and 36 OUTPUT: string @@ -2297,9 +2290,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``n`` -- an integer (error if not 0 or -1) + - ``n`` -- integer (error if not 0 or -1) - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -2321,7 +2314,7 @@ cdef class Rational(sage.structure.element.FieldElement): ################################################################ def __add__(left, right): """ - Return ``left`` plus ``right`` + Return ``left`` plus ``right``. EXAMPLES:: @@ -2362,7 +2355,7 @@ cdef class Rational(sage.structure.element.FieldElement): def __sub__(left, right): """ - Return ``left`` minus ``right`` + Return ``left`` minus ``right``. EXAMPLES:: @@ -2473,7 +2466,7 @@ cdef class Rational(sage.structure.element.FieldElement): def __truediv__(left, right): """ - Return ``left`` divided by ``right`` + Return ``left`` divided by ``right``. EXAMPLES:: @@ -2534,7 +2527,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the multiplicative inverse of ``self``. - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -2712,7 +2705,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return ``self``. - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -2727,7 +2720,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the negative of ``self``. - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -2745,7 +2738,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return ``True`` if this rational number is nonzero. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -2761,7 +2754,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the absolute value of this rational number. - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -2781,7 +2774,7 @@ cdef class Rational(sage.structure.element.FieldElement): depending on whether this number is negative, zero, or positive respectively. - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -2801,7 +2794,7 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``n`` -- an unsigned long integer + - ``n`` -- an unsigned long integer OUTPUT: integer @@ -2832,7 +2825,7 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``other`` -- object that coerces to an integer. + - ``other`` -- object that coerces to an integer OUTPUT: integer @@ -2866,9 +2859,7 @@ cdef class Rational(sage.structure.element.FieldElement): Return the norm from `\QQ` to `\QQ` of `x` (which is just `x`). This was added for compatibility with :class:`NumberField`. - OUTPUT: - - - ``Rational`` -- reference to ``self`` + OUTPUT: ``Rational`` -- reference to ``self`` EXAMPLES:: @@ -2883,7 +2874,8 @@ cdef class Rational(sage.structure.element.FieldElement): def relative_norm(self): """ - Return the norm from Q to Q of x (which is just x). This was added for compatibility with NumberFields + Return the norm from Q to Q of x (which is just x). This was added for + compatibility with NumberFields. EXAMPLES:: @@ -2897,7 +2889,8 @@ cdef class Rational(sage.structure.element.FieldElement): def absolute_norm(self): """ - Return the norm from Q to Q of x (which is just x). This was added for compatibility with NumberFields + Return the norm from Q to Q of x (which is just x). This was added for + compatibility with NumberFields. EXAMPLES:: @@ -2914,9 +2907,7 @@ cdef class Rational(sage.structure.element.FieldElement): Return the trace from `\QQ` to `\QQ` of `x` (which is just `x`). This was added for compatibility with :class:`NumberFields`. - OUTPUT: - - - ``Rational`` -- reference to self + OUTPUT: ``Rational`` -- reference to ``self`` EXAMPLES:: @@ -2938,9 +2929,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``var`` -- a string + - ``var`` -- string - OUTPUT: Polynomial + OUTPUT: polynomial EXAMPLES:: @@ -2968,9 +2959,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``var`` -- a string + - ``var`` -- string - OUTPUT: Polynomial + OUTPUT: polynomial EXAMPLES:: @@ -2991,7 +2982,7 @@ cdef class Rational(sage.structure.element.FieldElement): Return ``self`` coerced to an integer. Of course this rational number must have a denominator of 1. - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -3036,7 +3027,7 @@ cdef class Rational(sage.structure.element.FieldElement): def __int__(self): """ - Convert this rational to a Python ``int`` + Convert this rational to a Python ``int``. This truncates ``self`` if ``self`` has a denominator (which is consistent with Python's ``long(floats)``). @@ -3104,7 +3095,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the factorization of this rational number. - OUTPUT: Factorization + OUTPUT: factorization EXAMPLES:: @@ -3125,9 +3116,9 @@ cdef class Rational(sage.structure.element.FieldElement): def support(self): """ Return a sorted list of the primes where this rational number has - non-zero valuation. + nonzero valuation. - OUTPUT: The set of primes appearing in the factorization of this + OUTPUT: the set of primes appearing in the factorization of this rational with nonzero exponent, as a sorted list. EXAMPLES:: @@ -3317,7 +3308,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the floor of this rational number as an integer. - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -3341,7 +3332,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the ceiling of this rational number. - OUTPUT: Integer + OUTPUT: integer If this rational number is an integer, this returns this number, otherwise it returns the floor of this number +1. @@ -3392,18 +3383,18 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``self`` -- a rational number + - ``self`` -- a rational number - - ``mode`` -- a rounding mode for half integers: + - ``mode`` -- a rounding mode for half integers: - - 'toward' rounds toward zero - - 'away' (default) rounds away from zero - - 'up' rounds up - - 'down' rounds down - - 'even' rounds toward the even integer - - 'odd' rounds toward the odd integer + - ``'toward'`` rounds toward zero + - ``'away'`` (default) rounds away from zero + - ``'up'`` rounds up + - ``'down'`` rounds down + - ``'even'`` rounds toward the even integer + - ``'odd'`` rounds toward the odd integer - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -3485,7 +3476,7 @@ cdef class Rational(sage.structure.element.FieldElement): The max absolute value of the numerator and denominator of ``self``, as an :class:`Integer`. - OUTPUT: Integer + OUTPUT: integer EXAMPLES:: @@ -3506,7 +3497,6 @@ cdef class Rational(sage.structure.element.FieldElement): .. NOTE:: For the logarithmic height, use :meth:`global_height()`. - """ x = abs(self.numer()) if x > self.denom(): @@ -3521,11 +3511,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``other`` -- Rational - - OUTPUT: + - ``other`` -- Rational - - ``Rational`` -- 0 or 1 + OUTPUT: ``Rational`` -- 0 or 1 EXAMPLES:: @@ -3564,7 +3552,7 @@ cdef class Rational(sage.structure.element.FieldElement): """ Return the multiplicative order of ``self``. - OUTPUT: Integer or ``infinity`` + OUTPUT: integer or ``infinity`` EXAMPLES:: @@ -3593,7 +3581,7 @@ cdef class Rational(sage.structure.element.FieldElement): r""" Determine if a rational number is one. - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -3610,7 +3598,7 @@ cdef class Rational(sage.structure.element.FieldElement): Determine if a rational number is integral (i.e., is in `\ZZ`). - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -3645,9 +3633,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``S`` -- list or tuple of primes. + - ``S`` -- list or tuple of primes - OUTPUT: bool + OUTPUT: boolean .. NOTE:: @@ -3676,9 +3664,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``S`` -- list or tuple of primes. + - ``S`` -- list or tuple of primes - OUTPUT: bool + OUTPUT: boolean .. NOTE:: @@ -3720,9 +3708,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``x, y`` -- integer or rational + - ``x``, ``y`` -- integer or rational - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -3768,9 +3756,9 @@ cdef class Rational(sage.structure.element.FieldElement): INPUT: - - ``x, y`` -- integer or rational + - ``x``, ``y`` -- integer or rational - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -4077,7 +4065,7 @@ cdef double mpq_get_d_nearest(mpq_t x) except? -648555075988944.5: pass else: if not remainder_is_zero: - # Remainder is non-zero: round away from zero + # Remainder is nonzero: round away from zero q64 += 1 else: # Halfway case: round to even @@ -4095,13 +4083,13 @@ cdef double mpq_get_d_nearest(mpq_t x) except? -648555075988944.5: @cython.binding(True) def make_rational(s): """ - Make a rational number from ``s`` (a string in base 32) + Make a rational number from ``s`` (a string in base 32). INPUT: - - ``s`` -- string in base 32 + - ``s`` -- string in base 32 - OUTPUT: Rational + OUTPUT: rational EXAMPLES:: @@ -4190,7 +4178,6 @@ cdef class Z_to_Q(Morphism): sage: QQ.coerce_map_from(ZZ).is_surjective() False - """ return False diff --git a/src/sage/rings/rational_field.py b/src/sage/rings/rational_field.py index 62d85cf3380..0e6f2e69609 100644 --- a/src/sage/rings/rational_field.py +++ b/src/sage/rings/rational_field.py @@ -294,7 +294,7 @@ def __len__(self): """ Return the number of elements in ``self``. - Since this does not have a size, this throws a ``TypeError``. + Since this does not have a size, this throws a :exc:`TypeError`. EXAMPLES:: @@ -410,7 +410,7 @@ def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): def __iter__(self): r""" - Creates an iterator that generates the rational numbers without + Create an iterator that generates the rational numbers without repetition, in order of the height. See also :meth:`range_by_height()`. @@ -516,13 +516,11 @@ def primes_of_bounded_norm_iter(self, B): INPUT: - - ``B`` -- a positive integer; upper bound on the primes generated. + - ``B`` -- positive integer; upper bound on the primes generated - OUTPUT: - - An iterator over all integer primes less than or equal to `B`. + OUTPUT: an iterator over all integer primes less than or equal to `B` - .. note:: + .. NOTE:: This function exists for compatibility with the related number field method, though it returns prime integers, not ideals. @@ -730,12 +728,12 @@ def residue_field(self, p, check=True): INPUT: - - ``p`` -- a prime integer. + - ``p`` -- prime integer - - ``check`` (default ``True``) -- if ``True``, check the primality of - `p`, else do not. + - ``check`` -- (default: ``True``) if ``True``, check the primality of + `p`, else do not - OUTPUT: The residue field at this prime. + OUTPUT: the residue field at this prime EXAMPLES:: @@ -758,12 +756,12 @@ def hilbert_symbol_negative_at_S(self, S, b, check=True): INPUT: - - ``S`` -- a list of rational primes, the infinite place as real + - ``S`` -- list of rational primes, the infinite place as real embedding of `\QQ` or as `-1` - - ``b`` -- a non-zero rational number which is a non-square locally - at every prime in ``S``. - - ``check`` -- ``bool`` (default: ``True``) perform additional checks on - input and confirm the output. + - ``b`` -- a nonzero rational number which is a non-square locally + at every prime in ``S`` + - ``check`` -- boolean (default: ``True``); perform additional checks on + input and confirm the output OUTPUT: @@ -834,7 +832,6 @@ def hilbert_symbol_negative_at_S(self, S, b, check=True): AUTHORS: - Simon Brandhorst, Juanita Duque, Anna Haensch, Manami Roy, Sandi Rudzinski (10-24-2017) - """ from sage.arith.misc import hilbert_symbol, is_prime from sage.matrix.constructor import matrix @@ -933,7 +930,7 @@ def gens(self): def gen(self, n=0): r""" - Return the ``n``-th generator of `\QQ`. + Return the n-th generator of `\QQ`. There is only the 0-th generator, which is 1. @@ -1116,7 +1113,6 @@ def polynomial(self): sage: QQ.polynomial() x - """ from sage.rings.polynomial.polynomial_ring import polygen return polygen(self) @@ -1141,7 +1137,7 @@ def some_elements(self): See :func:`TestSuite` for a typical use case. - OUTPUT: An iterator over 100 elements of `\QQ`. + OUTPUT: an iterator over 100 elements of `\QQ` EXAMPLES:: @@ -1187,13 +1183,13 @@ def random_element(self, num_bound=None, den_bound=None, *args, **kwds): INPUT: - - ``num_bound`` -- a positive integer, specifying a bound - on the absolute value of the numerator. - If absent, no bound is enforced. + - ``num_bound`` -- positive integer, specifying a bound + on the absolute value of the numerator. + If absent, no bound is enforced. - - ``den_bound`` -- a positive integer, specifying a bound - on the value of the denominator. - If absent, the bound for the numerator will be reused. + - ``den_bound`` -- positive integer, specifying a bound + on the value of the denominator. + If absent, the bound for the numerator will be reused. Any extra positional or keyword arguments are passed through to :meth:`sage.rings.integer_ring.IntegerRing_class.random_element`. @@ -1255,8 +1251,7 @@ def zeta(self, n=2): INPUT: - - ``n`` -- integer (default: 2) order of the root of - unity + - ``n`` -- integer (default: 2); order of the root of unity EXAMPLES:: @@ -1284,13 +1279,13 @@ def selmer_generators(self, S, m, proof=True, orders=False): INPUT: - - ``S`` -- a set of primes + - ``S`` -- set of primes - - ``m`` -- a positive integer + - ``m`` -- positive integer - ``proof`` -- ignored - - ``orders`` (default ``False``) -- if ``True``, output two lists, the + - ``orders`` -- (default: ``False``) if ``True``, output two lists, the generators and their orders OUTPUT: @@ -1332,7 +1327,6 @@ def selmer_generators(self, S, m, proof=True, orders=False): ([-1, 2, 3, 5, 7], [2, 2, 2, 2, 2]) sage: QQ.selmer_generators((2,3,5,7,), 3, orders=True) ([2, 3, 5, 7], [3, 3, 3, 3]) - """ gens = list(S) ords = [ZZ(m)] * len(S) @@ -1353,9 +1347,9 @@ def selmer_group_iterator(self, S, m, proof=True): INPUT: - - ``S`` -- a set of primes + - ``S`` -- set of primes - - ``m`` -- a positive integer + - ``m`` -- positive integer - ``proof`` -- ignored @@ -1389,7 +1383,7 @@ def selmer_space(self, S, p, proof=None): INPUT: - - ``S`` -- a list of prime numbers + - ``S`` -- list of prime numbers - ``p`` -- a prime number @@ -1445,7 +1439,7 @@ def selmer_space(self, S, p, proof=None): sage: fromQS2((0,1,1)) -7 - The map ``fromQS2`` is only well-defined modulo `p`'th powers + The map ``fromQS2`` is only well-defined modulo `p`-th powers (in this case, modulo squares):: sage: toQS2(-5/7) # needs sage.modules sage.rings.number_field @@ -1463,7 +1457,6 @@ def selmer_space(self, S, p, proof=None): ... ValueError: argument 210 should have valuations divisible by 2 at all primes in [5, 7] - """ from sage.rings.number_field.selmer_group import pSelmerGroup return pSelmerGroup(self, S, p) @@ -1476,7 +1469,7 @@ def quadratic_defect(self, a, p, check=True): - ``a`` -- an element of ``self`` - ``p`` -- a prime ideal or a prime number - - ``check`` -- (default: ``True``); check if `p` is prime + - ``check`` -- (default: ``True``) check if `p` is prime REFERENCE: @@ -1572,7 +1565,6 @@ def _axiom_init_(self): Fraction Integer sage: fricas(QQ) #optional - fricas # indirect doctest Fraction(Integer) - """ return 'Fraction Integer' @@ -1586,7 +1578,6 @@ def _polymake_init_(self): sage: polymake(QQ) #optional - jupymake # indirect doctest Rational - """ return '"Rational"' @@ -1683,7 +1674,6 @@ def valuation(self, p): :meth:`NumberField_generic.valuation() `, :meth:`IntegerRing_class.valuation() ` - """ from sage.rings.padics.padic_valuation import pAdicValuation return pAdicValuation(self, p) diff --git a/src/sage/rings/real_arb.pyx b/src/sage/rings/real_arb.pyx index 4b34af0e8bf..3c063f193a8 100644 --- a/src/sage/rings/real_arb.pyx +++ b/src/sage/rings/real_arb.pyx @@ -94,7 +94,7 @@ above warning, inexact balls are not considered equal to themselves):: sage: a == b False -A ball is non-zero in the sense of comparison if and only if it does not +A ball is nonzero in the sense of comparison if and only if it does not contain zero. :: sage: a = RBF(RIF(-0.5, 0.5)) @@ -241,11 +241,11 @@ cdef void mpfi_to_arb(arb_t target, const mpfi_t source, const long precision) n INPUT: - - ``target`` -- an ``arb_t``. + - ``target`` -- an ``arb_t`` - - ``source`` -- an ``mpfi_t``. + - ``source`` -- an ``mpfi_t`` - - ``precision`` -- an integer `\ge 2`. + - ``precision`` -- integer `\ge 2` TESTS:: @@ -285,18 +285,17 @@ cdef int arb_to_mpfi(mpfi_t target, arb_t source, const long precision) except - INPUT: - - ``target`` -- an ``mpfi_t``. + - ``target`` -- an ``mpfi_t`` - - ``source`` -- an ``arb_t``. + - ``source`` -- an ``arb_t`` - - ``precision`` -- an integer `\ge 2`. + - ``precision`` -- integer `\ge 2` EXAMPLES:: sage: RIF(RBF(2)**(2**100)) [5.8756537891115869e1388255822130839282 .. +infinity] # 64-bit [2.098... .. +infinity] # 32-bit - """ cdef mpfr_t left cdef mpfr_t right @@ -323,7 +322,7 @@ class RealBallField(UniqueRepresentation, sage.rings.abc.RealBallField): INPUT: - - ``precision`` -- an integer `\ge 2`. + - ``precision`` -- integer `\ge 2` EXAMPLES:: @@ -396,7 +395,7 @@ class RealBallField(UniqueRepresentation, sage.rings.abc.RealBallField): INPUT: - - ``precision`` -- an integer `\ge 2`. + - ``precision`` -- integer `\ge 2` EXAMPLES:: @@ -418,7 +417,6 @@ class RealBallField(UniqueRepresentation, sage.rings.abc.RealBallField): Real ball field with 53 bits of precision sage: RBF.base_ring() Real ball field with 53 bits of precision - """ if precision < 2: raise ValueError("precision must be at least 2") @@ -541,7 +539,6 @@ class RealBallField(UniqueRepresentation, sage.rings.abc.RealBallField): [-3.932239737431101 +/- 5.58e-16] sage: v.overlaps(RealBallField(100)(3/2).zetaderiv(1)) # needs sage.symbolic True - """ # Symbolic expressions are handled in a special way, see # Expression._arb_(). A call like RBF(expr, rad) converts expr to a @@ -1118,7 +1115,6 @@ class RealBallField(UniqueRepresentation, sage.rings.abc.RealBallField): Traceback (most recent call last): ... ValueError: expected a nonnegative index - """ cdef RealBall res cdef Integer n_as_Integer = ZZ.coerce(n) @@ -1138,9 +1134,7 @@ class RealBallField(UniqueRepresentation, sage.rings.abc.RealBallField): r""" Return the relative accuracy of exact elements measured in bits. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -1195,7 +1189,7 @@ def create_RealBall(parent, serialized): cdef class RealBall(RingElement): """ - Hold one ``arb_t`` + Hold one ``arb_t``. EXAMPLES:: @@ -1235,12 +1229,12 @@ cdef class RealBall(RingElement): INPUT: - - ``parent`` -- a :class:`RealBallField`. + - ``parent`` -- a :class:`RealBallField` - - ``mid`` (optional) -- ball midpoint, see examples below. If omitted, + - ``mid`` -- (optional) ball midpoint, see examples below. If omitted, initialize the ball to zero, ignoring the ``rad`` argument. - - ``rad`` (optional) -- a :class:`RealNumber` or a Python float, ball + - ``rad`` -- (optional) a :class:`RealNumber` or a Python float, ball radius. If the midpoint is not exactly representable in floating-point, the radius is adjusted to account for the roundoff error. @@ -1524,9 +1518,7 @@ cdef class RealBall(RingElement): """ Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1571,9 +1563,7 @@ cdef class RealBall(RingElement): """ Return a :mod:`real interval ` containing this ball. - OUTPUT: - - A :class:`~sage.rings.real_mpfi.RealIntervalFieldElement`. + OUTPUT: a :class:`~sage.rings.real_mpfi.RealIntervalFieldElement` EXAMPLES:: @@ -1602,7 +1592,6 @@ cdef class RealBall(RingElement): Traceback (most recent call last): ... ValueError: [3.141592653589793 +/- ...e-16] does not contain a unique integer - """ cdef Integer res cdef fmpz_t tmp @@ -1870,13 +1859,11 @@ cdef class RealBall(RingElement): INPUT: - - ``test_zero`` (boolean, default ``False``) -- if ``True``, + - ``test_zero`` -- boolean (default: ``False``); if ``True``, make sure that the returned lower bound is positive, raising an error if the ball contains zero. - OUTPUT: - - A ball with zero radius + OUTPUT: a ball with zero radius EXAMPLES:: @@ -1910,9 +1897,7 @@ cdef class RealBall(RingElement): """ Return an upper bound for the absolute value of this ball. - OUTPUT: - - A ball with zero radius + OUTPUT: a ball with zero radius EXAMPLES:: @@ -1936,13 +1921,11 @@ cdef class RealBall(RingElement): INPUT: - - ``rnd`` (string) -- rounding mode for the parent of the result (does + - ``rnd`` -- string; rounding mode for the parent of the result (does not affect its value!), see :meth:`sage.rings.real_mpfi.RealIntervalFieldElement.upper` - OUTPUT: - - A real number. + OUTPUT: a real number EXAMPLES:: @@ -1964,13 +1947,11 @@ cdef class RealBall(RingElement): INPUT: - - ``rnd`` (string) -- rounding mode for the parent of the result (does + - ``rnd`` -- string; rounding mode for the parent of the result (does not affect its value!), see :meth:`sage.rings.real_mpfi.RealIntervalFieldElement.lower` - OUTPUT: - - A real number. + OUTPUT: a real number EXAMPLES:: @@ -1990,13 +1971,11 @@ cdef class RealBall(RingElement): INPUT: - - ``rnd`` (string) -- rounding mode for the parent of the resulting + - ``rnd`` -- string; rounding mode for the parent of the resulting floating-point numbers (does not affect their values!), see :meth:`sage.rings.real_mpfi.RealIntervalFieldElement.upper` - OUTPUT: - - A pair of real numbers. + OUTPUT: a pair of real numbers EXAMPLES:: @@ -2154,12 +2133,10 @@ cdef class RealBall(RingElement): INPUT: - - ``ampl`` -- A real ball (or an object that can be coerced to a real - ball). - - OUTPUT: + - ``ampl`` -- a real ball (or an object that can be coerced to a real + ball) - A new real ball. + OUTPUT: a new real ball EXAMPLES:: @@ -2621,7 +2598,6 @@ cdef class RealBall(RingElement): sage: b.contains_exact(1r) True - """ cdef fmpz_t tmpz cdef fmpq_t tmpq @@ -2732,7 +2708,7 @@ cdef class RealBall(RingElement): .. WARNING:: - Contrary to the usual convention, a return value of True does + Contrary to the usual convention, a return value of ``True`` does not imply that all points of the ball satisfy the predicate. This is due to the way comparisons with symbolic infinities work in sage. @@ -2799,7 +2775,6 @@ cdef class RealBall(RingElement): nan sage: RBF(RIF(-0.1,0.1)) [+/- 0.101] - """ cdef RealBall res = self._new() if _do_sig(prec(self)): sig_on() @@ -3055,7 +3030,7 @@ cdef class RealBall(RingElement): INPUT: - - ``shift`` -- integer, may be negative. + - ``shift`` -- integer; may be negative EXAMPLES:: @@ -3108,7 +3083,7 @@ cdef class RealBall(RingElement): INPUT: - - ``shift`` -- integer, may be negative. + - ``shift`` -- integer; may be negative EXAMPLES:: @@ -3139,7 +3114,7 @@ cdef class RealBall(RingElement): INPUT: - - ``base`` (optional, positive real ball or number) -- if ``None``, + - ``base`` -- (optional) positive real ball or number; if ``None``, return the natural logarithm ``ln(self)``, otherwise, return the general logarithm ``ln(self)/ln(base)`` @@ -3537,7 +3512,7 @@ cdef class RealBall(RingElement): def erfi(self): """ - Imaginary error function + Imaginary error function. EXAMPLES:: @@ -3552,7 +3527,7 @@ cdef class RealBall(RingElement): def Ei(self): """ - Exponential integral + Exponential integral. EXAMPLES:: @@ -3572,7 +3547,7 @@ cdef class RealBall(RingElement): def Si(self): """ - Sine integral + Sine integral. EXAMPLES:: @@ -3594,7 +3569,7 @@ cdef class RealBall(RingElement): def Ci(self): """ - Cosine integral + Cosine integral. EXAMPLES:: @@ -3616,7 +3591,7 @@ cdef class RealBall(RingElement): def Shi(self): """ - Hyperbolic sine integral + Hyperbolic sine integral. EXAMPLES:: @@ -3638,7 +3613,7 @@ cdef class RealBall(RingElement): def Chi(self): """ - Hyperbolic cosine integral + Hyperbolic cosine integral. EXAMPLES:: @@ -3660,7 +3635,7 @@ cdef class RealBall(RingElement): def li(self): """ - Logarithmic integral + Logarithmic integral. EXAMPLES:: @@ -3684,7 +3659,7 @@ cdef class RealBall(RingElement): def Li(self): """ - Offset logarithmic integral + Offset logarithmic integral. EXAMPLES:: @@ -3701,11 +3676,11 @@ cdef class RealBall(RingElement): def beta(self, a, z=1): """ - (Incomplete) beta function + (Incomplete) beta function. INPUT: - - ``a``, ``z`` (optional) -- real balls + - ``a``, ``z`` -- (optional) real balls OUTPUT: @@ -3740,7 +3715,7 @@ cdef class RealBall(RingElement): def gamma(self, a=None): r""" - Image of this ball by the (upper incomplete) Euler Gamma function + Image of this ball by the (upper incomplete) Euler Gamma function. For `a` real, return the upper incomplete Gamma function `\Gamma(self,a)`. @@ -3782,7 +3757,7 @@ cdef class RealBall(RingElement): def gamma_inc_lower(self, a): r""" - Image of this ball by the lower incomplete Euler Gamma function + Image of this ball by the lower incomplete Euler Gamma function. For `a` real, return the lower incomplete Gamma function of `\Gamma(self,a)`. @@ -3806,7 +3781,7 @@ cdef class RealBall(RingElement): """ Return the image of this ball by the logarithmic Gamma function. - The complex branch structure is assumed, so if ``self`` <= 0, the result + The complex branch structure is assumed, so if ``self <= 0``, the result is an indeterminate interval. EXAMPLES:: @@ -3862,7 +3837,7 @@ cdef class RealBall(RingElement): cpdef RealBall psi(self): """ - Compute the digamma function with argument self. + Compute the digamma function with argument ``self``. EXAMPLES:: @@ -3911,7 +3886,7 @@ cdef class RealBall(RingElement): def zetaderiv(self, k): r""" - Return the image of this ball by the k-th derivative of the Riemann + Return the image of this ball by the `k`-th derivative of the Riemann zeta function. For a more flexible interface, see the low-level method diff --git a/src/sage/rings/real_double.pyx b/src/sage/rings/real_double.pyx index d0ef9a4bb62..129603749d3 100644 --- a/src/sage/rings/real_double.pyx +++ b/src/sage/rings/real_double.pyx @@ -92,7 +92,7 @@ cdef class RealDoubleField_class(sage.rings.abc.RealDoubleField): sage: RDF(2/3) 0.6666666666666666 - A ``TypeError`` is raised if the coercion doesn't make sense:: + A :exc:`TypeError` is raised if the coercion doesn't make sense:: sage: RDF(QQ['x'].0) Traceback (most recent call last): @@ -151,7 +151,7 @@ cdef class RealDoubleField_class(sage.rings.abc.RealDoubleField): cpdef bint is_exact(self) except -2: """ - Returns ``False``, because doubles are not exact. + Return ``False``, because doubles are not exact. EXAMPLES:: @@ -233,7 +233,7 @@ cdef class RealDoubleField_class(sage.rings.abc.RealDoubleField): def construction(self): r""" - Returns the functorial construction of ``self``, namely, completion of + Return the functorial construction of ``self``, namely, completion of the rational numbers with respect to the prime at `\infty`. Also preserves other information that makes this field unique (i.e. @@ -462,7 +462,7 @@ cdef class RealDoubleField_class(sage.rings.abc.RealDoubleField): def characteristic(self): """ - Returns 0, since the field of real numbers has characteristic 0. + Return 0, since the field of real numbers has characteristic 0. EXAMPLES:: @@ -523,7 +523,7 @@ cdef class RealDoubleField_class(sage.rings.abc.RealDoubleField): def pi(self): r""" - Returns `\pi` to double-precision. + Return `\pi` to double-precision. EXAMPLES:: @@ -572,7 +572,7 @@ cdef class RealDoubleField_class(sage.rings.abc.RealDoubleField): def zeta(self, n=2): """ Return an `n`-th root of unity in the real field, if one - exists, or raise a ``ValueError`` otherwise. + exists, or raise a :exc:`ValueError` otherwise. EXAMPLES:: @@ -760,7 +760,7 @@ cdef class RealDoubleElement(FieldElement): def ulp(self): """ - Returns the unit of least precision of ``self``, which is the + Return the unit of least precision of ``self``, which is the weight of the least significant bit of ``self``. This is always a strictly positive number. It is also the gap between this number and the closest number with larger absolute value that @@ -844,7 +844,6 @@ cdef class RealDoubleElement(FieldElement): sage: x = u * 2^52 # smallest normal number sage: x.ulp() == u True - """ # First, check special values if self._value == 0: @@ -1364,7 +1363,7 @@ cdef class RealDoubleElement(FieldElement): def __neg__(self): """ - Negates ``self``. + Negate ``self``. EXAMPLES:: @@ -1377,7 +1376,7 @@ cdef class RealDoubleElement(FieldElement): def conjugate(self): r""" - Returns the complex conjugate of this real number, which is + Return the complex conjugate of this real number, which is the real number itself. EXAMPLES:: @@ -1389,7 +1388,7 @@ cdef class RealDoubleElement(FieldElement): def __abs__(self): """ - Returns the absolute value of ``self``. + Return the absolute value of ``self``. EXAMPLES:: @@ -1410,7 +1409,7 @@ cdef class RealDoubleElement(FieldElement): cpdef RealDoubleElement abs(RealDoubleElement self): """ - Returns the absolute value of ``self``. + Return the absolute value of ``self``. EXAMPLES:: @@ -1454,7 +1453,7 @@ cdef class RealDoubleElement(FieldElement): def multiplicative_order(self): r""" - Returns `n` such that ``self^n == 1``. + Return `n` such that ``self^n == 1``. Only `\pm 1` have finite multiplicative order. @@ -1475,7 +1474,7 @@ cdef class RealDoubleElement(FieldElement): def sign(self): """ - Returns -1,0, or 1 if ``self`` is negative, zero, or positive; + Return -1, 0, or 1 if ``self`` is negative, zero, or positive; respectively. EXAMPLES:: @@ -1600,7 +1599,7 @@ cdef class RealDoubleElement(FieldElement): def _rpy_(self): """ - Returns ``self.__float__()`` for rpy to convert into the + Return ``self.__float__()`` for rpy to convert into the appropriate R object. EXAMPLES:: @@ -1637,7 +1636,7 @@ cdef class RealDoubleElement(FieldElement): 0.333333333333333 If we coerce to a higher-precision field the extra bits appear - random; they are actually 0's in base 2. + random; they are actually 0s in base 2. :: @@ -1802,12 +1801,12 @@ cdef class RealDoubleElement(FieldElement): INPUT: - - ``extend`` -- bool (default: ``True``); if ``True``, return a - square root in a complex field if necessary if ``self`` is negative; - otherwise raise a ``ValueError``. + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in a complex field if necessary if ``self`` is negative. + Otherwise raise a :exc:`ValueError`. - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots EXAMPLES:: @@ -1858,7 +1857,7 @@ cdef class RealDoubleElement(FieldElement): """ Return whether or not this number is a square in this field. For the real numbers, this is ``True`` if and only if ``self`` is - non-negative. + nonnegative. EXAMPLES:: @@ -1873,7 +1872,7 @@ cdef class RealDoubleElement(FieldElement): def is_integer(self): """ - Return ``True`` if this number is a integer + Return ``True`` if this number is a integer. EXAMPLES:: diff --git a/src/sage/rings/real_double_element_gsl.pyx b/src/sage/rings/real_double_element_gsl.pyx index cf2be375b78..001564dee37 100644 --- a/src/sage/rings/real_double_element_gsl.pyx +++ b/src/sage/rings/real_double_element_gsl.pyx @@ -17,11 +17,11 @@ cdef class RealDoubleElement_gsl(RealDoubleElement): def nth_root(self, int n): """ - Return the `n^{th}` root of ``self``. + Return the `n`-th root of ``self``. INPUT: - - ``n`` -- an integer + - ``n`` -- integer OUTPUT: @@ -502,7 +502,7 @@ cdef class RealDoubleElement_gsl(RealDoubleElement): the interval `(-\pi, \pi]`. Specifically, it is the unique `x \in (-\pi, \pi]` such - that ```self`` `= x + 2\pi n` for some `n \in \ZZ`. + that ``self`` `= x + 2\pi n` for some `n \in \ZZ`. EXAMPLES:: @@ -546,7 +546,7 @@ cdef class RealDoubleElement_gsl(RealDoubleElement): def hypot(self, other): r""" - Computes the value `\sqrt{s^2 + o^2}` where `s` is ``self`` and `o` + Compute the value `\sqrt{s^2 + o^2}` where `s` is ``self`` and `o` is ``other`` in such a way as to avoid overflow. EXAMPLES:: diff --git a/src/sage/rings/real_field.py b/src/sage/rings/real_field.py index 7b8e17eb5b9..d0302c47ee5 100644 --- a/src/sage/rings/real_field.py +++ b/src/sage/rings/real_field.py @@ -1,4 +1,4 @@ -def create_RealField(prec=53, type="MPFR", rnd="RNDN", sci_not=0): +def create_RealField(prec=53, type='MPFR', rnd='RNDN', sci_not=0): """ Create a real field with given precision, type, rounding mode and scientific notation. @@ -7,7 +7,7 @@ def create_RealField(prec=53, type="MPFR", rnd="RNDN", sci_not=0): INPUT: - - ``prec`` -- a positive integer + - ``prec`` -- positive integer - ``type`` -- type of real field: @@ -26,9 +26,7 @@ def create_RealField(prec=53, type="MPFR", rnd="RNDN", sci_not=0): - ``sci_not`` -- boolean, whether to use scientific notation for printing - OUTPUT: - - the appropriate real field + OUTPUT: the appropriate real field EXAMPLES:: diff --git a/src/sage/rings/real_interval_absolute.pyx b/src/sage/rings/real_interval_absolute.pyx index e1c60c049c7..50baf63a0e9 100644 --- a/src/sage/rings/real_interval_absolute.pyx +++ b/src/sage/rings/real_interval_absolute.pyx @@ -212,7 +212,7 @@ cdef class RealIntervalAbsoluteField_class(Field): def absprec(self): """ - Returns the absolute precision of self. + Return the absolute precision of ``self``. EXAMPLES:: diff --git a/src/sage/rings/real_lazy.pyx b/src/sage/rings/real_lazy.pyx index 4b241818d84..8fe3a8281d0 100644 --- a/src/sage/rings/real_lazy.pyx +++ b/src/sage/rings/real_lazy.pyx @@ -110,7 +110,6 @@ cdef class LazyField(Field): sage: RLF # indirect doctest Real Lazy Field - """ Field.__init__(self,base or self, names=names, normalize=normalize, category=category) @@ -193,7 +192,7 @@ cdef class LazyField(Field): def algebraic_closure(self): """ - Returns the algebraic closure of ``self``, i.e., the complex lazy + Return the algebraic closure of ``self``, i.e., the complex lazy field. EXAMPLES:: @@ -258,7 +257,7 @@ class RealLazyField_class(LazyField): """ def interval_field(self, prec=None): """ - Returns the interval field that represents the same mathematical + Return the interval field that represents the same mathematical field as ``self``. EXAMPLES:: @@ -276,7 +275,7 @@ class RealLazyField_class(LazyField): def construction(self): """ - Returns the functorial construction of ``self``, namely, the + Return the functorial construction of ``self``, namely, the completion of the rationals at infinity to infinite precision. EXAMPLES:: @@ -409,7 +408,7 @@ class ComplexLazyField_class(LazyField): def interval_field(self, prec=None): """ - Returns the interval field that represents the same mathematical + Return the interval field that represents the same mathematical field as ``self``. EXAMPLES:: @@ -447,7 +446,7 @@ class ComplexLazyField_class(LazyField): def construction(self): """ - Returns the functorial construction of ``self``, namely, + Return the functorial construction of ``self``, namely, algebraic closure of the real lazy field. EXAMPLES:: @@ -513,7 +512,7 @@ CLF = ComplexLazyField_class() def ComplexLazyField(): """ - Returns the lazy complex field. + Return the lazy complex field. EXAMPLES: @@ -745,7 +744,7 @@ cdef class LazyFieldElement(FieldElement): def approx(self): """ - Returns ``self`` as an element of an interval field. + Return ``self`` as an element of an interval field. EXAMPLES:: @@ -859,13 +858,12 @@ cdef class LazyFieldElement(FieldElement): def __dir__(self): """ - Adds the named_unops to ``__dir__`` so that tab completion works. + Add the named_unops to ``__dir__`` so that tab completion works. TESTS:: sage: "log" in RLF(sqrt(8)).__dir__() # needs sage.symbolic True - """ return FieldElement.__dir__(self) + named_unops @@ -890,7 +888,7 @@ cdef class LazyFieldElement(FieldElement): def continued_fraction(self): r""" - Return the continued fraction of self. + Return the continued fraction of ``self``. EXAMPLES:: @@ -923,7 +921,7 @@ cdef class LazyWrapper(LazyFieldElement): cpdef int depth(self) noexcept: """ - Returns the depth of ``self`` as an expression, which is always 0. + Return the depth of ``self`` as an expression, which is always 0. EXAMPLES:: @@ -1049,7 +1047,7 @@ cdef class LazyWrapper(LazyFieldElement): def continued_fraction(self): r""" - Return the continued fraction of self. + Return the continued fraction of ``self``. EXAMPLES:: @@ -1204,7 +1202,7 @@ cdef class LazyUnop(LazyFieldElement): def __init__(self, LazyField parent, arg, op): """ - Represents a unevaluated single function of one variable. + Represent a unevaluated single function of one variable. EXAMPLES:: @@ -1369,7 +1367,7 @@ cdef class LazyNamedUnop(LazyUnop): def approx(self): """ - Does something reasonable with functions that are not defined on the + Do something reasonable with functions that are not defined on the interval fields. TESTS:: diff --git a/src/sage/rings/real_mpfi.pyx b/src/sage/rings/real_mpfi.pyx index 76fbfedab95..11953a50ab5 100644 --- a/src/sage/rings/real_mpfi.pyx +++ b/src/sage/rings/real_mpfi.pyx @@ -175,7 +175,7 @@ EXAMPLES:: Comparison with infinity is defined through coercion to the infinity ring where semi-infinite intervals are sent to their central value -(plus or minus infinity); This implements the above convention for +(plus or minus infinity); this implements the above convention for inequalities:: sage: InfinityRing.has_coerce_map_from(RIF) @@ -313,14 +313,14 @@ cpdef RealIntervalField_class RealIntervalField(prec=53, sci_not=False): INPUT: - - ``prec`` -- (integer) precision; default = 53: - The number of bits used to represent the mantissa of a - floating-point number. The precision can be any integer between - :func:`mpfr_prec_min()` and :func:`mpfr_prec_max()`. In the current - implementation, :func:`mpfr_prec_min()` is equal to 2. + - ``prec`` -- integer (default: 53); precision. + The number of bits used to represent the mantissa of a + floating-point number. The precision can be any integer between + :func:`mpfr_prec_min()` and :func:`mpfr_prec_max()`. In the current + implementation, :func:`mpfr_prec_min()` is equal to 2. - - ``sci_not`` -- (default: ``False``) whether or not to display using - scientific notation + - ``sci_not`` -- boolean (default: ``False``); whether or not to display using + scientific notation EXAMPLES:: @@ -352,16 +352,16 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): INPUT: - - ``prec`` -- (integer) precision; default = 53 ``prec`` is - the number of bits used to represent the mantissa of a - floating-point number. The precision can be any integer between - :func:`~sage.rings.real_mpfr.mpfr_prec_min()` and - :func:`~sage.rings.real_mpfr.mpfr_prec_max()`. In the current - implementation, :func:`~sage.rings.real_mpfr.mpfr_prec_min()` - is equal to 2. + - ``prec`` -- integer (default: 53); precision ``prec`` is + the number of bits used to represent the mantissa of a + floating-point number. The precision can be any integer between + :func:`~sage.rings.real_mpfr.mpfr_prec_min()` and + :func:`~sage.rings.real_mpfr.mpfr_prec_max()`. In the current + implementation, :func:`~sage.rings.real_mpfr.mpfr_prec_min()` + is equal to 2. - - ``sci_not`` -- (default: ``False``) whether or not to display using - scientific notation + - ``sci_not`` -- boolean (default: ``False``); whether or not to display using + scientific notation EXAMPLES:: @@ -545,7 +545,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): self._multiplicative_order = None from sage.categories.fields import Fields Field.__init__(self, self, category=Fields().Infinite()) - self._populate_coercion_lists_(convert_method_name="_real_mpfi_") + self._populate_coercion_lists_(convert_method_name='_real_mpfi_') def lower_field(self): """ @@ -670,7 +670,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): cpdef bint is_exact(self) except -2: """ - Returns whether or not this field is exact, which is always ``False``. + Return whether or not this field is exact, which is always ``False``. EXAMPLES:: @@ -687,12 +687,12 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): - ``x`` -- a number, string, or 2-tuple - - ``y`` -- (default: ``None``); if given ``x`` is set to ``(x,y)``; + - ``y`` -- (default: ``None``) if given ``x`` is set to ``(x,y)``; this is so you can write ``R(2,3)`` to make the interval from 2 to 3 - ``base`` -- integer (default: 10); only used if ``x`` is a string - OUTPUT: an element of this real interval field. + OUTPUT: an element of this real interval field EXAMPLES:: @@ -736,7 +736,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def construction(self): r""" - Returns the functorial construction of ``self``, namely, completion of + Return the functorial construction of ``self``, namely, completion of the rational numbers with respect to the prime at `\infty`, and the note that this is an interval field. @@ -988,7 +988,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def characteristic(self): """ - Returns 0, since the field of real numbers has characteristic 0. + Return 0, since the field of real numbers has characteristic 0. EXAMPLES:: @@ -1040,7 +1040,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def to_prec(self, prec): """ - Returns a real interval field to the given precision. + Return a real interval field to the given precision. EXAMPLES:: @@ -1068,7 +1068,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def pi(self): r""" - Returns `\pi` to the precision of this field. + Return `\pi` to the precision of this field. EXAMPLES:: @@ -1087,7 +1087,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def euler_constant(self): """ - Returns Euler's gamma constant to the precision of this field. + Return Euler's gamma constant to the precision of this field. EXAMPLES:: @@ -1100,7 +1100,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def log2(self): r""" - Returns `\log(2)` to the precision of this field. + Return `\log(2)` to the precision of this field. EXAMPLES:: @@ -1123,7 +1123,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): INPUT: - - ``status`` -- boolean optional flag + - ``status`` -- boolean optional flag EXAMPLES:: @@ -1144,7 +1144,7 @@ cdef class RealIntervalField_class(sage.rings.abc.RealIntervalField): def zeta(self, n=2): """ Return an `n`-th root of unity in the real field, if one - exists, or raise a ``ValueError`` otherwise. + exists, or raise a :exc:`ValueError` otherwise. EXAMPLES:: @@ -1176,7 +1176,7 @@ cdef class RealIntervalFieldElement(RingElement): """ def __cinit__(self, parent, *args, **kwds): """ - Initialize the parent of this element and allocate memory + Initialize the parent of this element and allocate memory. TESTS:: @@ -1344,13 +1344,13 @@ cdef class RealIntervalFieldElement(RingElement): def _interface_init_(self, I=None): """ - Raise a ``TypeError``. + Raise a :exc:`TypeError`. This function would return the string representation of ``self`` that makes sense as a default representation of a real interval in other computer algebra systems. But, most other computer algebra systems do not support interval arithmetic, so instead we just raise a - ``TypeError``. + :exc:`TypeError`. Define the appropriate ``_cas_init_`` function if there is a computer algebra system you would like to support. @@ -1485,19 +1485,19 @@ cdef class RealIntervalFieldElement(RingElement): INPUT: - - ``base`` -- base for output + - ``base`` -- base for output - - ``style`` -- The printing style; either ``'brackets'`` or - ``'question'`` (or ``None``, to use the current default). + - ``style`` -- the printing style; either ``'brackets'`` or + ``'question'`` (or ``None``, to use the current default) - - ``no_sci`` -- if ``True`` do not print using scientific - notation; if ``False`` print with scientific notation; if ``None`` - (the default), print how the parent prints. + - ``no_sci`` -- if ``True`` do not print using scientific + notation; if ``False`` print with scientific notation; if ``None`` + (the default), print how the parent prints. - - ``e`` -- symbol used in scientific notation + - ``e`` -- symbol used in scientific notation - - ``error_digits`` -- The number of digits of error to - print, in ``'question'`` style. + - ``error_digits`` -- the number of digits of error to + print, in ``'question'`` style We support two different styles of printing; ``'question'`` style and ``'brackets'`` style. In question style (the default), we print the @@ -1856,7 +1856,6 @@ cdef class RealIntervalFieldElement(RingElement): sage: v = RIF(1.0 >> -mpfr_get_exp_min()+1); v 2.3825649048879511?e-323228497 # 32-bit 8.5096913117408362?e-1388255822130839284 # 64-bit - """ if not(mpfr_number_p(&self.value.left) and mpfr_number_p(&self.value.right)): raise ValueError("_str_question_style on NaN or infinity") @@ -2207,7 +2206,7 @@ cdef class RealIntervalFieldElement(RingElement): # Interval-specific functions def lower(self, rnd=None): """ - Return the lower bound of this interval + Return the lower bound of this interval. INPUT: @@ -2258,7 +2257,7 @@ cdef class RealIntervalFieldElement(RingElement): def upper(self, rnd=None): """ - Return the upper bound of ``self`` + Return the upper bound of ``self``. INPUT: @@ -2434,7 +2433,7 @@ cdef class RealIntervalFieldElement(RingElement): def fp_rank_diameter(self): r""" - Computes the diameter of this interval in terms of the + Compute the diameter of this interval in terms of the "floating-point rank". The floating-point rank is the number of floating-point numbers (of @@ -2549,7 +2548,7 @@ cdef class RealIntervalFieldElement(RingElement): def bisection(self): """ - Returns the bisection of ``self`` into two intervals of half the size + Return the bisection of ``self`` into two intervals of half the size whose union is ``self`` and intersection is :meth:`center()`. EXAMPLES:: @@ -2917,7 +2916,7 @@ cdef class RealIntervalFieldElement(RingElement): def __lshift__(x, y): """ - Returns `x * 2^y`, for `y` an integer. Much faster + Return `x * 2^y`, for `y` an integer. Much faster than an ordinary multiplication. EXAMPLES:: @@ -2985,7 +2984,7 @@ cdef class RealIntervalFieldElement(RingElement): def precision(self): """ - Returns the precision of ``self``. + Return the precision of ``self``. EXAMPLES:: @@ -2999,12 +2998,12 @@ cdef class RealIntervalFieldElement(RingElement): prec = precision ################### - # Rounding etc + # Rounding etc. ################### def floor(self): """ - Return the floor of this interval as an interval + Return the floor of this interval as an interval. The floor of a real number `x` is the largest integer smaller than or equal to `x`. @@ -3012,7 +3011,7 @@ cdef class RealIntervalFieldElement(RingElement): .. SEEALSO:: - :meth:`unique_floor` -- method which returns the floor as an integer - if it is unique or raises a ``ValueError`` otherwise. + if it is unique or raises a :exc:`ValueError` otherwise - :meth:`ceil` -- truncation towards plus infinity - :meth:`round` -- rounding - :meth:`trunc` -- truncation towards zero @@ -3042,7 +3041,7 @@ cdef class RealIntervalFieldElement(RingElement): def ceil(self): """ - Return the ceiling of this interval as an interval + Return the ceiling of this interval as an interval. The ceiling of a real number `x` is the smallest integer larger than or equal to `x`. @@ -3050,7 +3049,7 @@ cdef class RealIntervalFieldElement(RingElement): .. SEEALSO:: - :meth:`unique_ceil` -- return the ceil as an integer if it is - unique and raises a ``ValueError`` otherwise + unique and raises a :exc:`ValueError` otherwise - :meth:`floor` -- truncation towards minus infinity - :meth:`trunc` -- truncation towards zero - :meth:`round` -- rounding @@ -3079,12 +3078,12 @@ cdef class RealIntervalFieldElement(RingElement): def round(self): r""" - Return the nearest integer of this interval as an interval + Return the nearest integer of this interval as an interval. .. SEEALSO:: - :meth:`unique_round` -- return the round as an integer if it is - unique and raises a ``ValueError`` otherwise + unique and raises a :exc:`ValueError` otherwise - :meth:`floor` -- truncation towards `-\infty` - :meth:`ceil` -- truncation towards `+\infty` - :meth:`trunc` -- truncation towards `0` @@ -3116,15 +3115,15 @@ cdef class RealIntervalFieldElement(RingElement): def trunc(self): r""" - Return the truncation of this interval as an interval + Return the truncation of this interval as an interval. - The truncation of `x` is the floor of `x` if `x` is non-negative or the + The truncation of `x` is the floor of `x` if `x` is nonnegative or the ceil of `x` if `x` is negative. .. SEEALSO:: - :meth:`unique_trunc` -- return the trunc as an integer if it is - unique and raises a ``ValueError`` otherwise + unique and raises a :exc:`ValueError` otherwise - :meth:`floor` -- truncation towards `-\infty` - :meth:`ceil` -- truncation towards `+\infty` - :meth:`round` -- rounding @@ -3302,7 +3301,7 @@ cdef class RealIntervalFieldElement(RingElement): This method returns `+1` if all elements in this interval are positive, `-1` if all of them are negative and `0` if it contains only zero. - Otherwise it raises a :class:`ValueError`. + Otherwise it raises a :exc:`ValueError`. EXAMPLES:: @@ -3337,7 +3336,7 @@ cdef class RealIntervalFieldElement(RingElement): def argument(self): r""" The argument of this interval, if it is well-defined, in the - complex sense. Otherwise raises a :class:`ValueError`. + complex sense. Otherwise raises a :exc:`ValueError`. OUTPUT: @@ -3361,7 +3360,6 @@ cdef class RealIntervalFieldElement(RingElement): Traceback (most recent call last): ... ValueError: Can't take the argument of interval strictly containing zero - """ k=self.parent() if mpfi_is_zero(self.value): @@ -3376,9 +3374,9 @@ cdef class RealIntervalFieldElement(RingElement): def unique_floor(self): """ Return the unique floor of this interval, if it is well defined, - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. - OUTPUT: an integer. + OUTPUT: integer .. SEEALSO:: @@ -3405,9 +3403,9 @@ cdef class RealIntervalFieldElement(RingElement): def unique_ceil(self): """ Return the unique ceiling of this interval, if it is well defined, - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. - OUTPUT: an integer. + OUTPUT: integer .. SEEALSO:: @@ -3434,9 +3432,9 @@ cdef class RealIntervalFieldElement(RingElement): def unique_round(self): """ Return the unique round (nearest integer) of this interval, - if it is well defined, otherwise raise a :class:`ValueError`. + if it is well defined, otherwise raise a :exc:`ValueError`. - OUTPUT: an integer. + OUTPUT: integer .. SEEALSO:: @@ -3496,7 +3494,7 @@ cdef class RealIntervalFieldElement(RingElement): def unique_trunc(self): r""" Return the nearest integer toward zero if it is unique, otherwise raise - a :class:`ValueError`. + a :exc:`ValueError`. .. SEEALSO:: @@ -3528,7 +3526,7 @@ cdef class RealIntervalFieldElement(RingElement): def unique_integer(self): """ Return the unique integer in this interval, if there is exactly one, - otherwise raise a :class:`ValueError`. + otherwise raise a :exc:`ValueError`. EXAMPLES:: @@ -3659,7 +3657,7 @@ cdef class RealIntervalFieldElement(RingElement): cdef Rational _simplest_rational_helper(self): """ - Returns the simplest rational in an interval which is either equal + Return the simplest rational in an interval which is either equal to or slightly larger than ``self``. We assume that both endpoints of ``self`` are nonnegative. """ @@ -4033,7 +4031,7 @@ cdef class RealIntervalFieldElement(RingElement): def overlaps(self, RealIntervalFieldElement other): """ - Return ``True`` if ``self`` and other are intervals with at least one + Return ``True`` if ``self`` and ``other`` are intervals with at least one value in common. For intervals ``a`` and ``b``, we have ``a.overlaps(b)`` iff ``not(a!=b)``. @@ -4058,7 +4056,7 @@ cdef class RealIntervalFieldElement(RingElement): def intersection(self, other): """ Return the intersection of two intervals. If the intervals do not - overlap, raises a ``ValueError``. + overlap, raises a :exc:`ValueError`. EXAMPLES:: @@ -4521,7 +4519,7 @@ cdef class RealIntervalFieldElement(RingElement): def exp(self): r""" - Returns `e^\mathtt{self}` + Return `e^\mathtt{self}`. EXAMPLES:: @@ -4551,7 +4549,7 @@ cdef class RealIntervalFieldElement(RingElement): def exp2(self): r""" - Returns `2^\mathtt{self}` + Return `2^\mathtt{self}`. EXAMPLES:: @@ -4579,7 +4577,7 @@ cdef class RealIntervalFieldElement(RingElement): def is_int(self): r""" - Checks to see whether this interval includes exactly one integer. + Check to see whether this interval includes exactly one integer. OUTPUT: @@ -4982,7 +4980,7 @@ cdef class RealIntervalFieldElement(RingElement): def algdep(self, n): r""" - Returns a polynomial of degree at most `n` which is + Return a polynomial of degree at most `n` which is approximately satisfied by ``self``. .. NOTE:: @@ -5137,13 +5135,7 @@ cdef class RealIntervalFieldElement(RingElement): """ Return the digamma function evaluated on ``self``. - INPUT: - - None. - - OUTPUT: - - A :class:`RealIntervalFieldElement`. + OUTPUT: a :class:`RealIntervalFieldElement` EXAMPLES:: @@ -5194,7 +5186,7 @@ cdef _simplest_rational_exact(Rational low, Rational high, int low_open, int hig """ Return the simplest rational between ``low`` and ``high``. May return ``low`` or ``high`` unless ``low_open`` or ``high_open`` (respectively) are - ``True`` (non-zero). We assume that ``low`` and ``high`` are both + ``True`` (nonzero). We assume that ``low`` and ``high`` are both nonnegative, and that ``high > low``. This is a helper function for @@ -5266,19 +5258,18 @@ def RealInterval(s, upper=None, int base=10, int pad=0, min_prec=53): INPUT: - - ``s`` -- a string that defines a real number (or - something whose string representation defines a number) + - ``s`` -- string that defines a real number (or + something whose string representation defines a number) - - ``upper`` -- (default: ``None``); upper endpoint of - interval if given, in which case ``s`` is the lower endpoint + - ``upper`` -- (default: ``None``) upper endpoint of + interval if given, in which case ``s`` is the lower endpoint - - ``base`` -- an integer between 2 and 36 + - ``base`` -- integer between 2 and 36 - - ``pad`` -- (default: 0) an integer - - - ``min_prec`` -- number will have at least this many - bits of precision, no matter what + - ``pad`` -- integer (default: 0) + - ``min_prec`` -- number will have at least this many + bits of precision, no matter what EXAMPLES:: @@ -5308,7 +5299,6 @@ def RealInterval(s, upper=None, int base=10, int pad=0, min_prec=53): ....: assert len(str(z))-4 >= k ....: except TypeError: ....: pass - """ if not isinstance(s, str): s = str(s) diff --git a/src/sage/rings/real_mpfr.pyx b/src/sage/rings/real_mpfr.pyx index 9e905c9c721..7e1ab748b55 100644 --- a/src/sage/rings/real_mpfr.pyx +++ b/src/sage/rings/real_mpfr.pyx @@ -386,17 +386,17 @@ cpdef RealField(mpfr_prec_t prec=53, int sci_not=0, rnd=MPFR_RNDN): INPUT: - - ``prec`` -- (integer) precision; default = 53 prec is + - ``prec`` -- integer (default: 53); precision ``prec`` is the number of bits used to represent the mantissa of a floating-point number. The precision can be any integer between :func:`mpfr_prec_min()` and :func:`mpfr_prec_max()`. In the current implementation, :func:`mpfr_prec_min()` is equal to 2. - - ``sci_not`` -- (default: ``False``) if ``True``, always display using - scientific notation; if ``False``, display using scientific notation - only for very large or very small numbers + - ``sci_not`` -- boolean (default: ``False``); if ``True``, always display + using scientific notation. If ``False``, display using scientific + notation only for very large or very small numbers. - - ``rnd`` -- (string) the rounding mode: + - ``rnd`` -- string; the rounding mode: - ``'RNDN'`` -- (default) round to nearest (ties go to the even number): Knuth says this is the best choice to prevent "floating @@ -966,7 +966,7 @@ cdef class RealField_class(sage.rings.abc.RealField): def characteristic(self): """ - Returns 0, since the field of real numbers has characteristic 0. + Return 0, since the field of real numbers has characteristic 0. EXAMPLES:: @@ -991,7 +991,7 @@ cdef class RealField_class(sage.rings.abc.RealField): def __hash__(self): """ - Returns a hash function of the field, which takes into account + Return a hash function of the field, which takes into account the precision and rounding convention. EXAMPLES:: @@ -1088,7 +1088,7 @@ cdef class RealField_class(sage.rings.abc.RealField): def euler_constant(self): """ - Returns Euler's gamma constant to the precision of this field. + Return Euler's gamma constant to the precision of this field. EXAMPLES:: @@ -1104,7 +1104,7 @@ cdef class RealField_class(sage.rings.abc.RealField): def catalan_constant(self): """ - Returns Catalan's constant to the precision of this field. + Return Catalan's constant to the precision of this field. EXAMPLES:: @@ -1238,7 +1238,7 @@ cdef class RealField_class(sage.rings.abc.RealField): INPUT: - - ``status`` -- boolean optional flag + - ``status`` -- boolean optional flag EXAMPLES:: @@ -1268,7 +1268,7 @@ cdef class RealField_class(sage.rings.abc.RealField): def zeta(self, n=2): """ Return an `n`-th root of unity in the real field, if one - exists, or raise a ``ValueError`` otherwise. + exists, or raise a :exc:`ValueError` otherwise. EXAMPLES:: @@ -1327,7 +1327,6 @@ cdef class RealField_class(sage.rings.abc.RealField): (x - 1.0000000000000000000000000000)^3 sage: k._factor_univariate_polynomial( x^2 - 3 ) (x - 1.7320508075688772935274463415) * (x + 1.7320508075688772935274463415) - """ R = f.parent() F = list(f._pari_with_name().factor()) @@ -1358,7 +1357,7 @@ cdef class RealNumber(sage.structure.element.RingElement): """ def __cinit__(self, parent, x=None, base=None): """ - Initialize the parent of this element and allocate memory + Initialize the parent of this element and allocate memory. TESTS:: @@ -1800,7 +1799,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def __hash__(self): """ - Returns the hash of self, which coincides with the python float + Return the hash of self, which coincides with the Python float (and often int) type. This has the drawback that two very close high precision numbers @@ -1872,8 +1871,8 @@ cdef class RealNumber(sage.structure.element.RingElement): - ``base`` -- (default: 10) base for output - - ``digits`` -- (default: 0) number of digits to display. When - ``digits`` is zero, choose this automatically. + - ``digits`` -- (default: 0) number of digits to display; when + ``digits`` is zero, choose this automatically - ``no_sci`` -- if 2, never print using scientific notation; if ``True``, use scientific notation only for large or small @@ -1883,12 +1882,12 @@ cdef class RealNumber(sage.structure.element.RingElement): - ``e`` -- symbol used in scientific notation; defaults to 'e' for base=10, and '@' otherwise - - ``truncate`` -- (default: ``False``) if ``True``, round off the + - ``truncate`` -- boolean (default: ``False``); if ``True``, round off the last digits in base-10 printing to lessen confusing base-2 roundoff issues. This flag may not be used in other bases or when ``digits`` is given. - - ``skip_zeroes`` -- (default: ``False``) if ``True``, skip + - ``skip_zeroes`` -- boolean (default: ``False``); if ``True``, skip trailing zeroes in mantissa EXAMPLES:: @@ -2244,7 +2243,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def fp_rank(self): r""" - Returns the floating-point rank of this number. That is, if you + Return the floating-point rank of this number. That is, if you list the floating-point numbers of this precision in order, and number them starting with `0.0 \rightarrow 0` and extending the list to positive and negative infinity, returns the number @@ -2559,7 +2558,7 @@ cdef class RealNumber(sage.structure.element.RingElement): cpdef _div_(self, right): """ - Divide ``self`` by other, where both are real numbers with the same + Divide ``self`` by ``other``, where both are real numbers with the same parent. EXAMPLES:: @@ -2773,7 +2772,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def ulp(self, field=None): """ - Returns the unit of least precision of ``self``, which is the + Return the unit of least precision of ``self``, which is the weight of the least significant bit of ``self``. This is always a strictly positive number. It is also the gap between this number and the closest number with larger absolute value that @@ -2781,8 +2780,8 @@ cdef class RealNumber(sage.structure.element.RingElement): INPUT: - - ``field`` -- :class:`RealField` used as parent of the result. - If not specified, use ``parent(self)``. + - ``field`` -- :class:`RealField` used as parent of the result; + if not specified, use ``parent(self)`` .. NOTE:: @@ -2813,7 +2812,7 @@ cdef class RealNumber(sage.structure.element.RingElement): sage: (a+b)/2 in [a,b] True - The ulp of zero is the smallest non-zero number:: + The ulp of zero is the smallest nonzero number:: sage: a = RR(0).ulp() sage: a @@ -2823,7 +2822,7 @@ cdef class RealNumber(sage.structure.element.RingElement): 1 The ulp of very small numbers results in underflow, so the - smallest non-zero number is returned instead:: + smallest nonzero number is returned instead:: sage: a.ulp() == a True @@ -2885,7 +2884,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def epsilon(self, field=None): """ - Returns ``abs(self)`` divided by `2^b` where `b` is the + Return ``abs(self)`` divided by `2^b` where `b` is the precision in bits of ``self``. Equivalently, return ``abs(self)`` multiplied by the :meth:`ulp` of 1. @@ -2895,8 +2894,8 @@ cdef class RealNumber(sage.structure.element.RingElement): INPUT: - - ``field`` -- :class:`RealField` used as parent of the result. - If not specified, use ``parent(self)``. + - ``field`` -- :class:`RealField` used as parent of the result + If not specified, use ``parent(self)`` OUTPUT: @@ -2959,7 +2958,7 @@ cdef class RealNumber(sage.structure.element.RingElement): return x ################### - # Rounding etc + # Rounding etc. ################### cpdef _mod_(left, right): @@ -3286,7 +3285,6 @@ cdef class RealNumber(sage.structure.element.RingElement): 3.1415926535 8979323846 26433833 sage: fricas(R(pi)) # optional - fricas 3.1415926535_8979323846_26433833 - """ prec = self.parent().prec() @@ -3445,7 +3443,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def exact_rational(self): """ - Returns the exact rational representation of this floating-point + Return the exact rational representation of this floating-point number. EXAMPLES:: @@ -4164,12 +4162,12 @@ cdef class RealNumber(sage.structure.element.RingElement): INPUT: - - ``extend`` -- bool (default: ``True``); if ``True``, return a - square root in a complex field if necessary if ``self`` is negative; - otherwise raise a ``ValueError`` + - ``extend`` -- boolean (default: ``True``); if ``True``, return a + square root in a complex field if necessary if ``self`` is negative. + Otherwise raise a :exc:`ValueError`. - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots EXAMPLES:: @@ -4227,7 +4225,7 @@ cdef class RealNumber(sage.structure.element.RingElement): """ Return whether or not this number is a square in this field. For the real numbers, this is ``True`` if and only if ``self`` is - non-negative. + nonnegative. EXAMPLES:: @@ -4387,7 +4385,6 @@ cdef class RealNumber(sage.structure.element.RingElement): sage: r = R(NaN); r.log() # needs sage.symbolic NaN - """ if mpfr_nan_p(self.value): return self @@ -4658,7 +4655,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def eint(self): """ - Returns the exponential integral of this number. + Return the exponential integral of this number. EXAMPLES:: @@ -4967,7 +4964,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def sec(self): """ - Returns the secant of this number + Return the secant of this number. EXAMPLES:: @@ -5049,9 +5046,7 @@ cdef class RealNumber(sage.structure.element.RingElement): - ``right`` -- another real number - OUTPUT: - - - the AGM of ``self`` and ``other`` + OUTPUT: the AGM of ``self`` and ``other`` EXAMPLES:: @@ -5304,7 +5299,7 @@ cdef class RealNumber(sage.structure.element.RingElement): def zeta(self): r""" - Return the Riemann zeta function evaluated at this real number + Return the Riemann zeta function evaluated at this real number. .. NOTE:: @@ -5381,18 +5376,16 @@ cdef class RealNumber(sage.structure.element.RingElement): def nth_root(self, int n, int algorithm=0): r""" - Return an `n^{th}` root of ``self``. + Return an `n`-th root of ``self``. INPUT: - - ``n`` -- A positive number, rounded down to the - nearest integer. Note that `n` should be less than - ```sys.maxsize```. + - ``n`` -- a positive number, rounded down to the nearest integer; + note that `n` should be less than ``sys.maxsize`` - - ``algorithm`` -- Set this to 1 to call mpfr directly, - set this to 2 to use interval arithmetic and logarithms, or leave - it at the default of 0 to choose the algorithm which is estimated - to be faster. + - ``algorithm`` -- set this to 1 to call mpfr directly, set this to 2 + to use interval arithmetic and logarithms, or leave it at the default + of 0 to choose the algorithm which is estimated to be faster AUTHORS: @@ -5437,7 +5430,7 @@ cdef class RealNumber(sage.structure.element.RingElement): ... ValueError: taking an even root of a negative number - The `n^{th}` root of 0 is defined to be 0, for any `n`:: + The `n`-th root of 0 is defined to be 0, for any `n`:: sage: R(0).nth_root(6) 0.000000000000000 @@ -5712,9 +5705,7 @@ cdef class RealLiteral(RealNumber): If neither ``prec`` nor ``digits`` is given, the default precision is 53 bits (roughly 16 digits). - OUTPUT: - - A ``RealNumber`` with the given precision. + OUTPUT: a ``RealNumber`` with the given precision EXAMPLES:: @@ -5749,7 +5740,7 @@ RR = RealField() RR_min_prec = RealField(MPFR_PREC_MIN) -def create_RealNumber(s, int base=10, int pad=0, rnd="RNDN", int min_prec=53): +def create_RealNumber(s, int base=10, int pad=0, rnd='RNDN', int min_prec=53): r""" Return the real number defined by the string ``s`` as an element of ``RealField(prec=n)``, where ``n`` potentially has slightly @@ -5757,12 +5748,12 @@ def create_RealNumber(s, int base=10, int pad=0, rnd="RNDN", int min_prec=53): INPUT: - - ``s`` -- a string that defines a real number (or + - ``s`` -- string that defines a real number (or something whose string representation defines a number) - - ``base`` -- an integer between 2 and 62 + - ``base`` -- integer between 2 and 62 - - ``pad`` -- an integer >= 0. + - ``pad`` -- nonnegative integer - ``rnd`` -- rounding mode: @@ -5772,7 +5763,7 @@ def create_RealNumber(s, int base=10, int pad=0, rnd="RNDN", int min_prec=53): - ``'RNDU'`` -- round up - ``min_prec`` -- number will have at least this many - bits of precision, no matter what. + bits of precision, no matter what EXAMPLES:: @@ -5803,7 +5794,7 @@ def create_RealNumber(s, int base=10, int pad=0, rnd="RNDN", int min_prec=53): 14070.0000000000 sage: RealNumber("aaa", base=37) 50652.0000000000 - sage: RealNumber("3.4", base="foo") + sage: RealNumber("3.4", base='foo') Traceback (most recent call last): ... TypeError: an integer is required @@ -6011,7 +6002,7 @@ cdef class QQtoRR(Map): cdef class double_toRR(Map): cpdef Element _call_(self, x): """ - Takes anything that can be converted to a double. + Take anything that can be converted to a double. EXAMPLES:: @@ -6031,7 +6022,7 @@ cdef class double_toRR(Map): cdef class int_toRR(Map): cpdef Element _call_(self, x): """ - Takes Python int/long instances. + Take Python int/long instances. EXAMPLES:: diff --git a/src/sage/rings/ring.pyx b/src/sage/rings/ring.pyx index 78be87716ce..b2e11b93678 100644 --- a/src/sage/rings/ring.pyx +++ b/src/sage/rings/ring.pyx @@ -256,7 +256,7 @@ cdef class Ring(ParentWithGens): def __len__(self): r""" Return the cardinality of this ring if it is finite, else raise - a ``NotImplementedError``. + a :exc:`NotImplementedError`. EXAMPLES:: @@ -346,7 +346,7 @@ cdef class Ring(ParentWithGens): - ``*x`` -- list or tuple of generators (or several input arguments) - - ``coerce`` -- bool (default: ``True``); this must be a keyword + - ``coerce`` -- boolean (default: ``True``); this must be a keyword argument. Only set it to ``False`` if you are certain that each generator is already in the ring. @@ -472,7 +472,6 @@ cdef class Ring(ParentWithGens): Right Ideal (Sq(2) + Sq(4), Sq(1,1)) of mod 2 Steenrod algebra, milnor basis sage: A * [A.1 + A.2, A.1^2] * A Twosided Ideal (Sq(2) + Sq(4), Sq(1,1)) of mod 2 Steenrod algebra, milnor basis - """ if isinstance(self, Ring): if self.is_commutative(): @@ -569,7 +568,6 @@ cdef class Ring(ParentWithGens): sage: L. = K.extension(a^2-3) sage: L.ideal(a) Principal ideal (1 + O(a^40)) of 3-adic Eisenstein Extension Field in a defined by a^2 - 3 - """ if self._zero_ideal is None: I = Ring.ideal(self, [self.zero()], coerce=False) @@ -631,15 +629,15 @@ cdef class Ring(ParentWithGens): INPUT: - - ``proof`` -- (default: ``True``) Determines what to do in unknown - cases + - ``proof`` -- boolean (default: ``True``); determines what to do in + unknown cases ALGORITHM: If the parameter ``proof`` is set to ``True``, the returned value is correct but the method might throw an error. Otherwise, if it is set - to ``False``, the method returns True if it can establish that self is - a field and False otherwise. + to ``False``, the method returns ``True`` if it can establish that + ``self`` is a field and ``False`` otherwise. EXAMPLES:: @@ -701,7 +699,7 @@ cdef class Ring(ParentWithGens): Return ``True`` if the canonical map from ``self`` to ``other`` is injective. - Raises a ``NotImplementedError`` if not known. + Raises a :exc:`NotImplementedError` if not known. EXAMPLES:: @@ -784,19 +782,17 @@ cdef class Ring(ParentWithGens): def zeta(self, n=2, all=False): """ Return a primitive ``n``-th root of unity in ``self`` if there - is one, or raise a ``ValueError`` otherwise. + is one, or raise a :exc:`ValueError` otherwise. INPUT: - ``n`` -- positive integer - - ``all`` -- bool (default: ``False``); whether to return - a list of all primitive `n`-th roots of unity. If True, raise a ``ValueError`` - if ``self`` is not an integral domain. - - OUTPUT: + - ``all`` -- boolean (default: ``False``); whether to return + a list of all primitive `n`-th roots of unity. If ``True``, raise a + :exc:`ValueError` if ``self`` is not an integral domain. - Element of ``self`` of finite order + OUTPUT: element of ``self`` of finite order EXAMPLES:: @@ -902,9 +898,9 @@ cdef class Ring(ParentWithGens): TESTS: - The following example returns a ``NotImplementedError`` since the + The following example returns a :exc:`NotImplementedError` since the generic ring class ``__call__`` function returns a - ``NotImplementedError``. Note that + :exc:`NotImplementedError`. Note that ``sage.rings.ring.Ring.random_element`` performs a call in the generic ring class by a random integer:: @@ -1141,11 +1137,12 @@ cdef class CommutativeRing(Ring): def extension(self, poly, name=None, names=None, **kwds): """ - Algebraically extends self by taking the quotient ``self[x] / (f(x))``. + Algebraically extend ``self`` by taking the quotient + ``self[x] / (f(x))``. INPUT: - - ``poly`` -- A polynomial whose coefficients are coercible into + - ``poly`` -- a polynomial whose coefficients are coercible into ``self`` - ``name`` -- (optional) name for the root of `f` @@ -1212,7 +1209,7 @@ cdef class IntegralDomain(CommutativeRing): INPUT: - - ``category`` (default: ``None``) -- a category, or ``None`` + - ``category`` -- (default: ``None``) a category, or ``None`` This method is used by all the abstract subclasses of :class:`IntegralDomain`, like :class:`NoetherianRing`, @@ -1249,7 +1246,7 @@ cdef class IntegralDomain(CommutativeRing): fractions; otherwise return ``False``. When no algorithm is implemented for this, then this - function raises a ``NotImplementedError``. + function raises a :exc:`NotImplementedError`. Note that ``is_integrally_closed`` has a naive implementation in fields. For every field `F`, `F` is its own field of fractions, diff --git a/src/sage/rings/ring_extension.pyx b/src/sage/rings/ring_extension.pyx index 9c214a1ffee..174af6dd415 100644 --- a/src/sage/rings/ring_extension.pyx +++ b/src/sage/rings/ring_extension.pyx @@ -148,7 +148,7 @@ def tower_bases(ring, degree): - ``ring`` -- a commutative ring - - ``degree`` -- a boolean + - ``degree`` -- boolean EXAMPLES:: @@ -207,7 +207,7 @@ def common_base(K, L, degree): - ``L`` -- a commutative ring - - ``degree`` -- a boolean; if true, return the degree of + - ``degree`` -- boolean; if ``True``, return the degree of ``K`` and ``L`` over their common base EXAMPLES:: @@ -234,7 +234,6 @@ def common_base(K, L, degree): Traceback (most recent call last): ... NotImplementedError: unable to find a common base - """ bases_K, degrees_K = tower_bases(K, degree) bases_L, degrees_L = tower_bases(L, degree) @@ -358,13 +357,13 @@ class RingExtensionFactory(UniqueFactory): ring or ``None`` (default: ``None``); the defining morphism of this extension or its base (if it coerces to ``ring``) - - ``gens`` -- a list of generators of this extension (over its base) - or ``None`` (default: ``None``); + - ``gens`` -- list of generators of this extension (over its base) + or ``None`` (default: ``None``) - - ``names`` -- a list or a tuple of variable names or ``None`` + - ``names`` -- list or a tuple of variable names or ``None`` (default: ``None``) - - ``constructors`` -- a list of constructors; each constructor + - ``constructors`` -- list of constructors; each constructor is a pair `(class, arguments)` where `class` is the class implementing the extension and `arguments` is the dictionary of arguments to pass in to init function @@ -424,7 +423,7 @@ class RingExtensionFactory(UniqueFactory): if not isinstance(defining_morphism, RingExtensionHomomorphism): defining_morphism = RingExtensionHomomorphism(defining_morphism.parent(), defining_morphism) if isinstance(ring, RingExtension_generic): - defining_morphism = backend_morphism(defining_morphism, forget="codomain") + defining_morphism = backend_morphism(defining_morphism, forget='codomain') if (ring)._is_backend_exposed: print_as = (ring)._backend else: @@ -512,7 +511,6 @@ cdef class RingExtension_generic(CommutativeRing): sage: TestSuite(Q).run() - """ Element = RingExtensionElement @@ -524,27 +522,25 @@ cdef class RingExtension_generic(CommutativeRing): - ``defining_morphism`` -- a ring homomorphism - - ``print_options`` -- a dictionary + - ``print_options`` -- dictionary - - ``import_methods`` -- a boolean (default: ``True``); whether this + - ``import_methods`` -- boolean (default: ``True``); whether this parent (resp. its elements) import the methods of the backend parent class (resp. element class) - - ``is_backend_exposed`` -- a boolean (default: ``False``); whether + - ``is_backend_exposed`` -- boolean (default: ``False``); whether the backend ring can be exposed to the user - ``category`` -- the category for the resulting parent (default: ``CommutativeRings()``) - .. NOTE: + .. NOTE:: The attribute ``is_backend_exposed`` is only used for printing; when it is ``False``, printing an element like its backend is - disabled (and a :class:`RuntimeError` is raised when it would occur). + disabled (and a :exc:`RuntimeError` is raised when it would occur). - OUTPUT: - - The extension defined by ``defining_morphism`` + OUTPUT: the extension defined by ``defining_morphism`` EXAMPLES:: @@ -567,7 +563,6 @@ cdef class RingExtension_generic(CommutativeRing): Traceback (most recent call last): ... ValueError: exotic defining morphism between two rings in the tower; consider using another variable name - """ cdef CommutativeRing base, ring cdef CommutativeRing b, backend @@ -726,7 +721,6 @@ cdef class RingExtension_generic(CommutativeRing): sage: E = GF(5^3).over() # needs sage.rings.finite_rings sage: E.construction() # needs sage.rings.finite_rings - """ # One could define a construction functor K' -> K' otimes_K L, but we leave this to another issue pass @@ -737,7 +731,7 @@ cdef class RingExtension_generic(CommutativeRing): INPUT: - - ``force`` -- a boolean (default: ``False``); if ``False``, + - ``force`` -- boolean (default: ``False``); if ``False``, raise an error if the backend is not exposed EXAMPLES:: @@ -751,7 +745,6 @@ cdef class RingExtension_generic(CommutativeRing): Finite Field in z3 of size 5^3 sage: E.backend() is K True - """ if force or self._is_backend_exposed: return self._backend @@ -790,7 +783,7 @@ cdef class RingExtension_generic(CommutativeRing): INPUT: - - ``over`` -- an integer or ``Infinity`` (default: ``0``); the maximum + - ``over`` -- integer or ``Infinity`` (default: ``0``); the maximum number of bases included in the printing of this extension - ``base`` -- a base over which this extension is finite free; @@ -850,15 +843,13 @@ cdef class RingExtension_generic(CommutativeRing): def _print_option_over(self, over): """ - Check and normalize the print option ``over`` + Check and normalize the print option ``over``. INPUT: - - ``over`` -- an integer or ``Infinity`` + - ``over`` -- integer or ``Infinity`` - OUTPUT: - - The normalized value of ``over`` + OUTPUT: the normalized value of ``over`` TESTS:: @@ -885,10 +876,9 @@ cdef class RingExtension_generic(CommutativeRing): INPUT: - - ``over`` -- an integer, ``Infinity`` or ``None``; the maximum + - ``over`` -- integer, ``Infinity`` or ``None``; the maximum number of bases included in the print representation of - this extension; - if ``None``, use the print options of this extension. + this extension. If ``None``, use the print options of this extension. EXAMPLES:: @@ -949,10 +939,9 @@ cdef class RingExtension_generic(CommutativeRing): r""" Return a LaTeX representation of this extension. - - ``over`` -- an integer, ``Infinity`` or ``None``; the maximum + - ``over`` -- integer, ``Infinity`` or ``None``; the maximum number of bases included in the LaTeX representation of - this extension; - if ``None``, use the print options of this extension. + this extension. If ``None``, use the print options of this extension. EXAMPLES:: @@ -1016,8 +1005,8 @@ cdef class RingExtension_generic(CommutativeRing): If `L/K` is an extension, a coercion map `K \to (L/K)` (acting through the defining morphism of `L/K`) is set. - If ``L_1/K_1` and `L_2/K_2` are two extensions, a coercion - map `(L_1/K_1) \to (L_2/K_2)`` is set when `L_1` coerces to + If `L_1/K_1` and `L_2/K_2` are two extensions, a coercion + map `(L_1/K_1) \to (L_2/K_2)` is set when `L_1` coerces to `L_2` and `K_1` coerces to `K_2` in such a way that the appropriate diagram commutes. @@ -1069,7 +1058,6 @@ cdef class RingExtension_generic(CommutativeRing): False sage: B.has_coerce_map_from(A) True - """ cdef RingExtension_generic right if isinstance(other, RingExtension_generic): @@ -1254,7 +1242,6 @@ cdef class RingExtension_generic(CommutativeRing): Field in z4 with defining polynomial x^2 + (4*z2 + 3)*x + z2 over its base sage: L._check_base(None) is L.base() # needs sage.rings.finite_rings True - """ cdef CommutativeRing b if base is None: @@ -1323,7 +1310,6 @@ cdef class RingExtension_generic(CommutativeRing): 1/2 sage: x.parent() Rational Field over its base - """ elt = self._backend.an_element() return self.element_class(self, elt) @@ -1527,7 +1513,7 @@ cdef class RingExtension_generic(CommutativeRing): def relative_degree(self): r""" - Return the degree of this extension over its base + Return the degree of this extension over its base. EXAMPLES:: @@ -1543,7 +1529,7 @@ cdef class RingExtension_generic(CommutativeRing): def absolute_degree(self): r""" - Return the degree of this extension over its absolute base + Return the degree of this extension over its absolute base. EXAMPLES:: @@ -1692,7 +1678,7 @@ cdef class RingExtension_generic(CommutativeRing): INPUT: - - ``proof`` -- a boolean (default: ``False``) + - ``proof`` -- boolean (default: ``False``) EXAMPLES:: @@ -1718,7 +1704,7 @@ cdef class RingExtension_generic(CommutativeRing): INPUT: - - ``extend_base`` -- a boolean (default: ``False``); + - ``extend_base`` -- boolean (default: ``False``) If ``extend_base`` is ``False``, the fraction field of the extension `L/K` is defined as `\textrm{Frac}(L)/L/K`, except @@ -1793,7 +1779,7 @@ cdef class RingExtension_generic(CommutativeRing): INPUT: - - ``extend_base`` -- a boolean (default: ``False``); see + - ``extend_base`` -- boolean (default: ``False``); see :meth:`fraction_field` for more informations TESTS:: @@ -1848,7 +1834,6 @@ cdef class RingExtension_generic(CommutativeRing): to Field in z12 with defining polynomial x^6 + (4*z2 + 3)*x^5 + x^4 + (3*z2 + 1)*x^3 + x^2 + (4*z2 + 1)*x + z2 over its base in Category of sets - """ from sage.rings.ring_extension_homset import RingExtensionHomset if category.is_subcategory(CommutativeRings()): @@ -1875,7 +1860,7 @@ cdef class RingExtension_generic(CommutativeRing): - ``category`` -- the category of the resulting morphism - - ``check`` -- a boolean (default: ``True``); whether to verify that the + - ``check`` -- boolean (default: ``True``); whether to verify that the images of generators extend to define a map (using only canonical coercions) EXAMPLES:: @@ -1930,9 +1915,7 @@ cdef class RingExtension_generic(CommutativeRing): r""" Return the characteristic of the extension as a ring. - OUTPUT: - - A prime number or zero. + OUTPUT: a prime number or zero EXAMPLES:: @@ -2001,7 +1984,6 @@ cdef class RingExtensionFractionField(RingExtension_generic): sage: TestSuite(Q).run() - """ Element = RingExtensionFractionFieldElement @@ -2120,12 +2102,12 @@ cdef class RingExtensionWithBasis(RingExtension_generic): - ``defining_morphism`` -- a ring homomorphism - - ``basis`` -- a tuple of elements in this extension + - ``basis`` -- tuple of elements in this extension - - ``names`` -- a tuple of strings or ``None`` (default: ``None``); + - ``names`` -- tuple of strings or ``None`` (default: ``None``); the way the elements of the basis are printed - - ``check`` -- a boolean (default: ``True``); whether to check if + - ``check`` -- boolean (default: ``True``); whether to check if ``basis`` is indeed a basis TESTS:: @@ -2196,7 +2178,6 @@ cdef class RingExtensionWithBasis(RingExtension_generic): ... ValueError: not (explicitly) defined over Field in z4 with defining polynomial x^2 + (3 - z2)*x + z2 over its base - """ if 'print_elements_as' in self._print_options: raise NotImplementedError("printing is handled by an external function or another parent") @@ -2351,7 +2332,7 @@ cdef class RingExtensionWithBasis(RingExtension_generic): - ``base`` -- a commutative ring (which might be itself an extension) or ``None`` (default: ``None``) - - ``map`` -- boolean (default ``True``); whether to return + - ``map`` -- boolean (default: ``True``); whether to return isomorphisms between this ring and V OUTPUT: @@ -2424,7 +2405,6 @@ cdef class RingExtensionWithBasis(RingExtension_generic): Traceback (most recent call last): ... ValueError: not (explicitly) defined over Finite Field in z3 of size 11^3 - """ base = self._check_base(base) return self._free_module(base, map) @@ -2440,7 +2420,7 @@ cdef class RingExtensionWithBasis(RingExtension_generic): - ``base`` -- a commutative ring (which might be itself an extension) or ``None`` (default: ``None``) - - ``map`` -- boolean (default ``True``); whether to return + - ``map`` -- boolean (default: ``True``); whether to return isomorphisms between this ring and V OUTPUT: @@ -2462,7 +2442,6 @@ cdef class RingExtensionWithBasis(RingExtension_generic): ....: V, i, j = L.free_module(base) ....: assert([i(v) for v in V.basis()] == L.basis_over(base)) ....: assert([j(x) for x in L.basis_over(base)] == V.basis()) - """ d = self._degree_over(base) if map: @@ -2477,7 +2456,7 @@ cdef class RingExtensionWithBasis(RingExtension_generic): INPUT: - - ``extend_base`` -- a boolean (default: ``False``); + - ``extend_base`` -- boolean (default: ``False``) If ``extend_base`` is ``False``, the fraction field of the extension `L/K` is defined as `\textrm{Frac}(L)/L/K`, except @@ -2567,7 +2546,6 @@ cdef class RingExtensionWithGen(RingExtensionWithBasis): sage: type(K) sage: TestSuite(K).run() - """ def __init__(self, defining_morphism, gen, names, check=True, **kwargs): r""" @@ -2579,10 +2557,10 @@ cdef class RingExtensionWithGen(RingExtensionWithBasis): - ``gen`` -- a generator of this extension - - ``names`` -- a tuple of strings or ``None`` (default: ``None``); + - ``names`` -- tuple of strings or ``None`` (default: ``None``); the way the elements of the basis are printed - - ``check`` -- a boolean (default: ``True``); whether to check if + - ``check`` -- boolean (default: ``True``); whether to check if ``gen`` is indeed a generator TESTS:: @@ -2722,7 +2700,7 @@ cdef class RingExtensionWithGen(RingExtensionWithBasis): INPUT: - - ``extend_base`` -- a boolean (default: ``False``); + - ``extend_base`` -- boolean (default: ``False``) If ``extend_base`` is ``False``, the fraction field of the extension `L/K` is defined as `\textrm{Frac}(L)/L/K`, except diff --git a/src/sage/rings/ring_extension_conversion.pyx b/src/sage/rings/ring_extension_conversion.pyx index eeb6077cd0a..482b74552c8 100644 --- a/src/sage/rings/ring_extension_conversion.pyx +++ b/src/sage/rings/ring_extension_conversion.pyx @@ -243,7 +243,7 @@ cdef _backend_morphism(f): return ring.coerce_map_from(domain) raise NotImplementedError -cpdef backend_morphism(f, forget="all"): +cpdef backend_morphism(f, forget='all'): r""" Return the backend morphism of ``f``. @@ -251,8 +251,8 @@ cpdef backend_morphism(f, forget="all"): - ``f`` -- a map - - ``forget`` -- a string, either ``all`` or ``domain`` or ``codomain`` - (default: ``all``); whether to switch to the backend for the domain, + - ``forget`` -- string; either ``'all'`` or ``'domain'`` or ``'codomain'`` + (default: ``'all'``). Whether to switch to the backend for the domain, the codomain or both of them. EXAMPLES:: @@ -269,13 +269,13 @@ cpdef backend_morphism(f, forget="all"): Ring endomorphism of Finite Field in z3 of size 7^3 Defn: z3 |--> 3*z3^2 + 5*z3 - sage: backend_morphism(f, forget="domain") + sage: backend_morphism(f, forget='domain') Ring morphism: From: Finite Field in z3 of size 7^3 To: Field in a with defining polynomial x^3 + 6*x^2 + 4 over its base Defn: z3 |--> 5*a + 3*a^2 - sage: backend_morphism(f, forget="codomain") + sage: backend_morphism(f, forget='codomain') Ring morphism: From: Field in a with defining polynomial x^3 + 6*x^2 + 4 over its base To: Finite Field in z3 of size 7^3 diff --git a/src/sage/rings/ring_extension_element.pyx b/src/sage/rings/ring_extension_element.pyx index 729793d3bfa..67b6aa90879 100644 --- a/src/sage/rings/ring_extension_element.pyx +++ b/src/sage/rings/ring_extension_element.pyx @@ -46,7 +46,6 @@ cdef class RingExtensionElement(CommutativeAlgebraElement): sage: K = GF(5^4).over() # needs sage.rings.finite_rings sage: x = K.random_element() # needs sage.rings.finite_rings sage: TestSuite(x).run() # needs sage.rings.finite_rings - """ def __init__(self, RingExtension_generic parent, x, *args, **kwds): r""" @@ -274,7 +273,7 @@ cdef class RingExtensionElement(CommutativeAlgebraElement): INPUT: - - ``force`` -- a boolean (default: ``False``); if ``False``, + - ``force`` -- boolean (default: ``False``); if ``False``, raise an error if the backend is not exposed EXAMPLES:: @@ -290,7 +289,6 @@ cdef class RingExtensionElement(CommutativeAlgebraElement): 4*z4^3 + 2*z4^2 + 4*z4 + 4 sage: y.parent() Finite Field in z4 of size 5^4 - """ if force or ((self._parent))._is_backend_exposed: return self._backend @@ -341,7 +339,6 @@ cdef class RingExtensionElement(CommutativeAlgebraElement): sage: x = 4*v^7 + v^6 + 3*v^4 + v^3 + v^2 + 4 sage: x.in_base() u - """ cdef RingExtension_generic parent = self._parent if isinstance(parent, RingExtensionWithGen): @@ -572,7 +569,7 @@ cdef class RingExtensionElement(CommutativeAlgebraElement): INPUT: - - ``root`` -- a boolean (default: ``False``); if ``True``, + - ``root`` -- boolean (default: ``False``); if ``True``, return also a square root EXAMPLES:: @@ -604,16 +601,16 @@ cdef class RingExtensionElement(CommutativeAlgebraElement): INPUT: - - ``extend`` -- a boolean (default: ``True``); if "True", + - ``extend`` -- boolean (default: ``True``); if ``True``, return a square root in an extension ring, if necessary. - Otherwise, raise a :class:`ValueError` if the root is not in - the ring + Otherwise, raise a :exc:`ValueError` if the root is not in + the ring. - - ``all`` -- a boolean (default: ``False``); if ``True``, - return all square roots of this element, instead of just one. + - ``all`` -- boolean (default: ``False``); if ``True``, + return all square roots of this element, instead of just one - - ``name`` -- Required when ``extend=True`` and ``self`` is not a - square. This will be the name of the generator extension. + - ``name`` -- required when ``extend=True`` and ``self`` is not a + square; this will be the name of the generator extension .. NOTE:: diff --git a/src/sage/rings/ring_extension_morphism.pyx b/src/sage/rings/ring_extension_morphism.pyx index 7a870e80182..2768bdac81c 100644 --- a/src/sage/rings/ring_extension_morphism.pyx +++ b/src/sage/rings/ring_extension_morphism.pyx @@ -108,7 +108,7 @@ cdef class RingExtensionHomomorphism(RingMap): the action of this morphism on one of the bases of the domain; if ``None``, a coercion map is used - - ``check`` -- a boolean (default: ``True``); whether to check if + - ``check`` -- boolean (default: ``True``); whether to check if the given data define a valid homomorphism TESTS:: @@ -293,7 +293,6 @@ cdef class RingExtensionHomomorphism(RingMap): Field in b with defining polynomial x^3 + (2 + 2*a)*x - a over its base Defn: b |--> 2 + 2*a*b + (2 - a)*b^2 sage: phi.base_map() # needs sage.rings.finite_rings - """ domain = self.domain() codomain = self.codomain() @@ -634,7 +633,6 @@ cdef class RingExtensionBackendReverseIsomorphism(RingExtensionHomomorphism): sage: type(f) sage: TestSuite(f).run() - """ def __init__(self, parent): r""" @@ -717,7 +715,6 @@ cdef class MapFreeModuleToRelativeRing(Map): sage: V, i, j = K.free_module() # needs sage.rings.finite_rings sage: type(i) # needs sage.rings.finite_rings - """ def __init__(self, E, K): r""" @@ -740,7 +737,7 @@ cdef class MapFreeModuleToRelativeRing(Map): """ self._degree = E.degree(K) self._basis = [ (x)._backend for x in E.basis_over(K) ] - self._f = backend_morphism(E.defining_morphism(K), forget="codomain") + self._f = backend_morphism(E.defining_morphism(K), forget='codomain') domain = K ** self._degree parent = domain.Hom(E) Map.__init__(self, parent) @@ -804,7 +801,6 @@ cdef class MapRelativeRingToFreeModule(Map): sage: V, i, j = K.free_module() # needs sage.rings.finite_rings sage: type(j) # needs sage.rings.finite_rings - """ def __init__(self, E, K): r""" @@ -829,7 +825,7 @@ cdef class MapRelativeRingToFreeModule(Map): self._degree = (E)._degree_over(K) self._basis = [ (x)._backend for x in E.basis_over(K) ] - f = backend_morphism(E.defining_morphism(K), forget="codomain") + f = backend_morphism(E.defining_morphism(K), forget='codomain') codomain = K ** self._degree Map.__init__(self, E.Hom(codomain)) diff --git a/src/sage/rings/semirings/non_negative_integer_semiring.py b/src/sage/rings/semirings/non_negative_integer_semiring.py index 1c01fc47eb5..cc144253328 100644 --- a/src/sage/rings/semirings/non_negative_integer_semiring.py +++ b/src/sage/rings/semirings/non_negative_integer_semiring.py @@ -15,7 +15,7 @@ class NonNegativeIntegerSemiring(NonNegativeIntegers): r""" - A class for the semiring of the non negative integers + A class for the semiring of the nonnegative integers. This parent inherits from the infinite enumerated set of non negative integers and endows it with its natural semiring @@ -58,7 +58,6 @@ class NonNegativeIntegerSemiring(NonNegativeIntegers): Integer Ring sage: x+3 18 - """ def __init__(self): r""" @@ -83,7 +82,7 @@ def _repr_(self): def additive_semigroup_generators(self): r""" - Returns the additive semigroup generators of ``self``. + Return the additive semigroup generators of ``self``. EXAMPLES:: diff --git a/src/sage/rings/semirings/tropical_semiring.pyx b/src/sage/rings/semirings/tropical_semiring.pyx index aa3ea3da761..205966541ab 100644 --- a/src/sage/rings/semirings/tropical_semiring.pyx +++ b/src/sage/rings/semirings/tropical_semiring.pyx @@ -40,7 +40,7 @@ cdef class TropicalSemiringElement(Element): cdef TropicalSemiringElement _new(self): """ - Return a new tropical semiring element with parent ``self`. + Return a new tropical semiring element with parent ``self``. """ cdef TropicalSemiringElement x x = TropicalSemiringElement.__new__(TropicalSemiringElement) @@ -468,8 +468,8 @@ class TropicalSemiring(Parent, UniqueRepresentation): INPUT: - ``base`` -- the base ordered additive semigroup `R` - - ``use_min`` -- (default: ``True``) if ``True``, then the semiring uses - `a \oplus b = \min(a, b)`; otherwise uses `a \oplus b = \max(a, b)` + - ``use_min`` -- boolean (default: ``True``); if ``True``, then the semiring uses + `a \oplus b = \min(a, b)`. Otherwise uses `a \oplus b = \max(a, b)`. EXAMPLES:: diff --git a/src/sage/rings/sum_of_squares.pyx b/src/sage/rings/sum_of_squares.pyx index a1f06964719..bd403de75e9 100644 --- a/src/sage/rings/sum_of_squares.pyx +++ b/src/sage/rings/sum_of_squares.pyx @@ -133,10 +133,10 @@ cdef int three_squares_c(uint_fast32_t n, uint_fast32_t res[3]) noexcept: def two_squares_pyx(uint32_t n): r""" - Return a pair of non-negative integers ``(i,j)`` such that `i^2 + j^2 = n`. + Return a pair of nonnegative integers ``(i,j)`` such that `i^2 + j^2 = n`. - If ``n`` is not a sum of two squares, a ``ValueError`` is raised. The input - must be lesser than `2^{32}=4294967296`, otherwise an ``OverflowError`` is + If ``n`` is not a sum of two squares, a :exc:`ValueError` is raised. The input + must be less than `2^{32}=4294967296`, otherwise an :exc:`OverflowError` is raised. .. SEEALSO:: @@ -193,7 +193,7 @@ def is_sum_of_two_squares_pyx(uint32_t n): Return ``True`` if ``n`` is a sum of two squares and ``False`` otherwise. The input must be smaller than `2^{32} = 4294967296`, otherwise an - ``OverflowError`` is raised. + :exc:`OverflowError` is raised. EXAMPLES:: @@ -219,11 +219,12 @@ def is_sum_of_two_squares_pyx(uint32_t n): def three_squares_pyx(uint32_t n): r""" - If ``n`` is a sum of three squares return a 3-tuple ``(i,j,k)`` of Sage integers - such that `i^2 + j^2 + k^2 = n` and `i \leq j \leq k`. Otherwise raise a ``ValueError``. + If ``n`` is a sum of three squares return a 3-tuple ``(i,j,k)`` of Sage + integers such that `i^2 + j^2 + k^2 = n` and `i \leq j \leq k`. Otherwise + raise a :exc:`ValueError`. - The input must be lesser than `2^{32}=4294967296`, otherwise an - ``OverflowError`` is raised. + The input must be less than `2^{32}=4294967296`, otherwise an + :exc:`OverflowError` is raised. EXAMPLES:: @@ -274,11 +275,11 @@ def three_squares_pyx(uint32_t n): def four_squares_pyx(uint32_t n): r""" - Return a 4-tuple of non-negative integers ``(i,j,k,l)`` such that `i^2 + j^2 + Return a 4-tuple of nonnegative integers ``(i,j,k,l)`` such that `i^2 + j^2 + k^2 + l^2 = n` and `i \leq j \leq k \leq l`. - The input must be lesser than `2^{32}=4294967296`, otherwise an - ``OverflowError`` is raised. + The input must be less than `2^{32}=4294967296`, otherwise an + :exc:`OverflowError` is raised. .. SEEALSO:: diff --git a/src/sage/rings/tate_algebra.py b/src/sage/rings/tate_algebra.py index 52f264b1761..7118e1d386b 100644 --- a/src/sage/rings/tate_algebra.py +++ b/src/sage/rings/tate_algebra.py @@ -95,7 +95,7 @@ 1 + 2^2 + a*2^4 + O(2^5) sage: u = polygen(ZZ, 'u') - sage: L. = K.change(print_mode="series").extension(u^3 - 2) + sage: L. = K.change(print_mode='series').extension(u^3 - 2) sage: g(pi, 2*pi) pi^7 + pi^8 + pi^19 + pi^20 + O(pi^21) @@ -173,14 +173,14 @@ class TateAlgebraFactory(UniqueFactory): - ``base`` -- a `p`-adic ring or field; if a ring is given, the Tate algebra over its fraction field will be constructed - - ``prec`` -- an integer or ``None`` (default: ``None``), the - precision cap; it is used if an exact object must be truncated + - ``prec`` -- integer or ``None`` (default: ``None``); the + precision cap. It is used if an exact object must be truncated in order to do an arithmetic operation. If left as ``None``, it will be set to the precision cap of the base field. - - ``log_radii`` -- an integer or a list or a tuple of integers - (default: ``0``), the value(s) `v_i`. + - ``log_radii`` -- integer or a list or a tuple of integers + (default: ``0``); the value(s) `v_i`. If an integer is given, this will be the common value for all `v_i`. @@ -251,9 +251,9 @@ def create_key(self, base, prec=None, log_radii=ZZ(0), names=None, order='degrev - ``base`` -- a `p`-adic ring or field - - ``prec`` -- an integer or ``None`` (default: ``None``) + - ``prec`` -- integer or ``None`` (default: ``None``) - - ``log_radii`` -- an integer or a list or a tuple of integers + - ``log_radii`` -- integer or a list or a tuple of integers (default: ``0``) - ``names`` -- names of the indeterminates @@ -291,7 +291,6 @@ def create_key(self, base, prec=None, log_radii=ZZ(0), names=None, order='degrev Traceback (most recent call last): ... ValueError: unknown term order 'myorder' - """ if not isinstance(base, pAdicGeneric): raise TypeError("the base ring must be a p-adic ring or a p-adic field") @@ -328,7 +327,6 @@ def create_object(self, version, key): sage: key = TateAlgebra.create_key(Zp(2), names=('x','y')) sage: TateAlgebra.create_object((8,4,6), key) Tate Algebra in x (val >= 0), y (val >= 0) over 2-adic Field with capped relative precision 20 - """ (base, prec, log_radii, names, order) = key return TateAlgebra_generic(base, prec, log_radii, names, order) @@ -342,20 +340,19 @@ def create_object(self, version, key): class TateTermMonoid(Monoid_class, UniqueRepresentation): r""" - A base class for Tate algebra terms + A base class for Tate algebra terms. A term in a Tate algebra `K\{X_1,\dots,X_n\}` (resp. in its ring of integers) is a monomial in this ring. Those terms form a pre-ordered monoid, with term multiplication and the term order of the parent Tate algebra. - """ Element = TateAlgebraTerm def __init__(self, A): r""" - Initialize the Tate term monoid + Initialize the Tate term monoid. INPUT: @@ -373,7 +370,6 @@ def __init__(self, A): sage: A. = TateAlgebra(Zp(2), log_radii=1) sage: T = A.monoid_of_terms() sage: TestSuite(T).run() - """ # This function is not exposed to the user # so we do not check the inputs @@ -392,15 +388,14 @@ def __init__(self, A): def _repr_(self): r""" - Return a string representation of this Tate term monoid + Return a string representation of this Tate term monoid. EXAMPLES:: sage: R = pAdicRing(2, 10) - sage: A. = TateAlgebra(R, log_radii=[1,1], order="lex") + sage: A. = TateAlgebra(R, log_radii=[1,1], order='lex') sage: A.monoid_of_terms() # indirect doctest Monoid of terms in x (val >= -1), y (val >= -1) over 2-adic Field with capped relative precision 10 - """ if self._ngens == 0: return "Monoid of terms over %s" % self._base @@ -410,16 +405,15 @@ def _repr_(self): def _latex_(self): r""" - Return a LaTeX representation of this Tate term monoid + Return a LaTeX representation of this Tate term monoid. EXAMPLES:: sage: R = pAdicRing(2, 10) - sage: A. = TateAlgebra(R, log_radii=[1,1], order="lex") + sage: A. = TateAlgebra(R, log_radii=[1,1], order='lex') sage: M = A.monoid_of_terms() sage: M._latex_() '\\verb"Terms"(\\Bold{Q}_{2}\\{x,y\\}_{(1,1)})' - """ return '\\verb"Terms"(%s)' % self._parent_algebra._latex_() @@ -479,7 +473,7 @@ def _coerce_map_from_(self, R): Term orders must also match:: - sage: B. = TateAlgebra(R, order="lex") + sage: B. = TateAlgebra(R, order='lex') sage: U = B.monoid_of_terms() sage: T.has_coerce_map_from(U) # indirect doctest False @@ -519,7 +513,6 @@ def algebra_of_series(self): Tate Algebra in x (val >= 0), y (val >= 0) over 2-adic Field with capped relative precision 10 sage: T.algebra_of_series() is A True - """ return self._parent_algebra @@ -552,7 +545,6 @@ def base_ring(self): 2-adic Ring with capped relative precision 10 sage: Ao.base_ring() is R True - """ return self._base @@ -567,7 +559,6 @@ def variable_names(self): sage: T = A.monoid_of_terms() sage: T.variable_names() ('x', 'y') - """ return self._names @@ -586,7 +577,6 @@ def log_radii(self): sage: B. = TateAlgebra(R, log_radii=[1,2]) sage: B.monoid_of_terms().log_radii() (1, 2) - """ return tuple(self._log_radii) @@ -606,13 +596,12 @@ def term_order(self): sage: T = A.monoid_of_terms() sage: T.term_order() Lexicographic term order - """ return self._order def ngens(self): r""" - Return the number of variables in the Tate term monoid + Return the number of variables in the Tate term monoid. EXAMPLES:: @@ -621,7 +610,6 @@ def ngens(self): sage: T = A.monoid_of_terms() sage: T.ngens() 2 - """ return self._ngens @@ -636,17 +624,16 @@ def gens(self): sage: T = A.monoid_of_terms() sage: T.gens() (...0000000001*x, ...0000000001*y) - """ return tuple([self(g) for g in self._parent_algebra.gens()]) def gen(self, n=0): r""" - Return the ``n``-th generator of this monoid of terms. + Return the `n`-th generator of this monoid of terms. INPUT: - - ``n`` -- an integer (default: ``0``), the index of + - ``n`` -- integer (default: `0`); the index of the requested generator EXAMPLES:: @@ -664,7 +651,6 @@ def gen(self, n=0): Traceback (most recent call last): ... ValueError: generator not defined - """ return self(self._parent_algebra.gen(n)) @@ -679,7 +665,6 @@ def some_elements(self): sage: T = A.monoid_of_terms() sage: T.some_elements() [...00000000010, ...0000000001*x, ...0000000001*y, ...00000000010*x*y] - """ elts = [ self(self._field.uniformizer()) ] + list(self.gens()) elts.append(prod(elts)) @@ -692,7 +677,7 @@ def some_elements(self): class TateAlgebra_generic(Parent): def __init__(self, field, prec, log_radii, names, order, integral=False): """ - Initialize the Tate algebra + Initialize the Tate algebra. TESTS:: @@ -702,7 +687,6 @@ def __init__(self, field, prec, log_radii, names, order, integral=False): We check that univariate Tate algebras work correctly:: sage: B. = TateAlgebra(Zp(3)) - """ from sage.misc.latex import latex_variable_name from sage.rings.polynomial.polynomial_ring_constructor import _multi_variate @@ -740,14 +724,13 @@ def __init__(self, field, prec, log_radii, names, order, integral=False): def _an_element_(self): r""" - Return an element of this Tate algebra + Return an element of this Tate algebra. EXAMPLES:: sage: A. = TateAlgebra(Zp(2), log_radii=1) sage: A.an_element() # indirect doctest (1 + O(2^20))*x - """ return self.gen() @@ -797,7 +780,7 @@ def _coerce_map_from_(self, R): If the tame order changes, there is no coercion either:: - sage: B. = TateAlgebra(R, order="lex") + sage: B. = TateAlgebra(R, order='lex') sage: B.has_coerce_map_from(A) # indirect doctest False @@ -815,7 +798,6 @@ def _coerce_map_from_(self, R): sage: C. = TateAlgebra(S, log_radii=[2,-2]) sage: C.has_coerce_map_from(B) # indirect doctest True - """ base = self._base if base.has_coerce_map_from(R): @@ -838,8 +820,8 @@ def _pushout_(self, R): """ Return the pushout of this Tate algebra with ``R``. - This is only implemented when ``R`` is a p-adic ring or - a p-adic field. + This is only implemented when ``R`` is a `p`-adic ring or + a `p`-adic field. EXAMPLES:: @@ -876,7 +858,6 @@ def _pushout_(self, R): (pi + O(pi^41))*v sage: (pi*v).parent() is A2 True - """ if isinstance(R, pAdicGeneric): base = pushout(self._base, R) @@ -926,11 +907,11 @@ def prime(self): def gen(self, n=0): r""" - Return the ``n``-th generator of this Tate algebra. + Return the `n`-th generator of this Tate algebra. INPUT: - - ``n`` -- an integer (default: ``0``), the index of + - ``n`` -- integer (default: `0`); the index of the requested generator EXAMPLES:: @@ -947,7 +928,6 @@ def gen(self, n=0): Traceback (most recent call last): ... ValueError: generator not defined - """ try: return self._gens[n] @@ -964,7 +944,6 @@ def gens(self): sage: A. = TateAlgebra(R) sage: A.gens() (...0000000001*x, ...0000000001*y) - """ return tuple(self._gens) @@ -978,7 +957,6 @@ def ngens(self): sage: A. = TateAlgebra(R) sage: A.ngens() 2 - """ return self._ngens @@ -1006,7 +984,6 @@ def some_elements(self): ...0000000010*y, ...0000000001*y + ...00000000010*x*y, ...00000000100*x*y] - """ terms = [ self.zero() ] + [ self(t) for t in self.monoid_of_terms().some_elements() ] return [ terms[i] + terms[j] for i in range(len(terms)) for j in range(i, len(terms)) ] @@ -1024,7 +1001,6 @@ def _repr_(self): sage: A.integer_ring() Integer ring of the Tate Algebra in x (val >= 0), y (val >= 0) over 2-adic Field with capped relative precision 10 - """ vars = ", ".join("%s (val >= %s)" % (var, -r) for var, r in zip(self._names, self._log_radii)) @@ -1049,7 +1025,6 @@ def _latex_(self): sage: B. = TateAlgebra(R, log_radii=[1,2]) sage: B._latex_() '\\Bold{Q}_{2}\\{u_{1},u_{2}\\}_{(1,2)}' - """ from sage.misc.latex import latex s = r"%s\{%s\}" % (latex(self._field), ",".join(self._latex_names)) @@ -1072,7 +1047,6 @@ def variable_names(self): sage: A. = TateAlgebra(R) sage: A.variable_names() ('x', 'y') - """ return self._names @@ -1095,7 +1069,6 @@ def log_radii(self): sage: C. = TateAlgebra(R, log_radii=(1,-1)) sage: C.log_radii() (1, -1) - """ return self._log_radii @@ -1116,7 +1089,6 @@ def integer_ring(self): True sage: x/2 in Ao False - """ return self._integer_ring @@ -1130,7 +1102,6 @@ def monoid_of_terms(self): sage: A. = TateAlgebra(R) sage: A.monoid_of_terms() Monoid of terms in x (val >= 0), y (val >= 0) over 2-adic Field with capped relative precision 10 - """ return self._parent_terms @@ -1148,7 +1119,6 @@ def term_order(self): sage: A. = TateAlgebra(R, order='lex') sage: A.term_order() Lexicographic term order - """ return self._order @@ -1182,7 +1152,6 @@ def precision_cap(self): sage: A. = TateAlgebra(R, prec=20) sage: A.precision_cap() 20 - """ return self._cap @@ -1211,7 +1180,6 @@ def absolute_e(self): sage: A. = TateAlgebra(S) sage: A.absolute_e() 2 - """ return self._base.absolute_e() @@ -1225,7 +1193,6 @@ def characteristic(self): sage: A. = TateAlgebra(R) sage: A.characteristic() 0 - """ return self.base_ring().characteristic() @@ -1235,20 +1202,20 @@ def random_element(self, degree=2, terms=5, integral=False, prec=None): INPUT: - - ``degree`` -- an integer (default: 2), an upper bound on + - ``degree`` -- integer (default: 2); an upper bound on the total degree of the result - - ``terms`` -- an integer (default: 5), the maximal number + - ``terms`` -- integer (default: 5); the maximal number of terms of the result - - ``integral`` -- a boolean (default: ``False``); if ``True`` + - ``integral`` -- boolean (default: ``False``); if ``True`` the result will be in the ring of integers - ``prec`` -- (optional) an integer, the precision of the result EXAMPLES:: - sage: R = Zp(2, prec=10, print_mode="digits") + sage: R = Zp(2, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: A.random_element() # random (...00101000.01)*y + ...1111011111*x^2 + ...0010010001*x*y @@ -1278,7 +1245,6 @@ def random_element(self, degree=2, terms=5, integral=False, prec=None): sage: B.random_element(integral=True) # random (...1111111.001)*x*y + (...111000101.1)*x + (...11010111.01)*y^2 + ...0010011011*y + ...0010100011000 - """ if integral or self._integral: polring = self._polynomial_ring.change_ring(self._field.integer_ring()) diff --git a/src/sage/rings/tate_algebra_element.pyx b/src/sage/rings/tate_algebra_element.pyx index 6b606881399..1c435a2ccec 100644 --- a/src/sage/rings/tate_algebra_element.pyx +++ b/src/sage/rings/tate_algebra_element.pyx @@ -44,7 +44,7 @@ def _pushout_family(elements, initial=ZZ): INPUT: - - ``elements`` -- a list of elements + - ``elements`` -- list of elements - ``initial`` -- a parent @@ -59,7 +59,6 @@ def _pushout_family(elements, initial=ZZ): sage: _pushout_family([a, x, 3]) Tate Algebra in x (val >= 0), y (val >= 0) over 2-adic Unramified Extension Field in a defined by x^2 + x + 1 - """ from sage.structure.coerce_exceptions import CoercionException from sage.categories.pushout import pushout @@ -88,7 +87,7 @@ cdef class TateAlgebraTerm(MonoidElement): - ``coeff`` -- an element in the base field - - ``exponent`` -- a tuple of length ``n`` + - ``exponent`` -- tuple of length ``n`` EXAMPLES:: @@ -104,17 +103,16 @@ cdef class TateAlgebraTerm(MonoidElement): Traceback (most recent call last): ... TypeError: a term cannot be zero - """ def __init__(self, parent, coeff, exponent=None): """ - Initialize a Tate algebra term + Initialize a Tate algebra term. INPUT: - ``coeff`` -- an element in the base field - - ``exponent`` -- a tuple + - ``exponent`` -- tuple TESTS:: @@ -124,7 +122,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: t = T(x) sage: TestSuite(t).run() - """ MonoidElement.__init__(self, parent) field = parent.base_ring().fraction_field() @@ -163,7 +160,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: hash(t) == hash((t.coefficient(), t.exponent())) True - """ return hash((self._coeff, self._exponent)) @@ -181,7 +177,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...0000000001*x*y sage: 2*t # indirect doctest ...00000000010*x*y - """ cdef TateAlgebraTerm ans = TateAlgebraTerm.__new__(TateAlgebraTerm) ans._parent = self._parent @@ -198,7 +193,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: t = x.leading_term() sage: loads(dumps(t)) == t # indirect doctest True - """ return TateAlgebraTerm, (self.parent(), self._coeff, self._exponent) @@ -226,7 +220,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: T = A.monoid_of_terms() sage: T(2*x*y) # indirect doctest ...00000000010*x*y - """ parent = self._parent if self._coeff._is_atomic() or (-self._coeff)._is_atomic(): @@ -288,7 +281,6 @@ cdef class TateAlgebraTerm(MonoidElement): (2 + O(2^11))*x*y sage: t.coefficient() 2 + O(2^11) - """ return self._coeff @@ -306,7 +298,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: t = T(2,(1,1)) sage: t.exponent() (1, 1) - """ return self._exponent @@ -329,7 +320,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...0000000011*x^2*y sage: s*t # indirect doctest ...00000000110*x^3*y^2 - """ cdef TateAlgebraTerm ans = self._new_c() ans._exponent = self._exponent.eadd((other)._exponent) @@ -376,7 +366,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: t = T(x*y^3) sage: s > t # indirect doctest True - """ cdef long c = other._valuation_c() - self._valuation_c() if not c: @@ -436,7 +425,6 @@ cdef class TateAlgebraTerm(MonoidElement): True sage: s == ss False - """ if op == Py_EQ: return ((self)._coeff == (other)._coeff @@ -460,7 +448,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...0000000011*x^2*y^2 sage: s.monomial() ...0000000001*x^2*y^2 - """ cdef TateAlgebraTerm ans = self._new_c() ans._coeff = self._parent._field(1) @@ -506,7 +493,6 @@ cdef class TateAlgebraTerm(MonoidElement): 0 sage: s.monomial().valuation() -4 - """ cdef TateAlgebraTerm ans = self._new_c() cdef long v = self._exponent.dotprod(self._parent._log_radii) @@ -537,7 +523,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...000000000100*x^2*y^2 sage: t.valuation() -2 - """ return ZZ(self._valuation_c()) @@ -554,7 +539,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...000000000100*x^2*y^2 sage: t.valuation() # indirect doctest 2 - """ return (self._coeff).valuation_c() - self._exponent.dotprod(self._parent._log_radii) @@ -574,7 +558,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: t = M(x*y) sage: t(0, 1) 0 - """ cdef Element ans = self._coeff cdef ETuple exponent = self._exponent @@ -619,7 +602,6 @@ cdef class TateAlgebraTerm(MonoidElement): Traceback (most recent call last): ... TypeError: cannot coerce all the elements to the same parent - """ parent = self._parent if len(args) != parent._ngens: @@ -685,7 +667,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: To = Ao.monoid_of_terms() sage: To(s).is_coprime_with(To(t)) False - """ for i in range(self._parent.ngens()): if self._exponent[i] > 0 and other.exponent()[i] > 0: @@ -722,7 +703,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...000000000100*x*y^3 sage: s.gcd(t) ...000000000100*x*y^2 - """ return self._gcd_c(other) @@ -759,7 +739,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: T = A.monoid_of_terms() sage: T(x^5).gcd(T(y^5)) ...00000.00001 - """ cdef TateAlgebraTerm ans = self._new_c() cdef long val @@ -792,7 +771,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...000000000100*x*y^3 sage: s.lcm(t) ...0000000001000*x^2*y^3 - """ return self._lcm_c(other) @@ -824,7 +802,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: s.gcd(t) * s.lcm(t) == s * t True - """ cdef TateAlgebraTerm ans = self._new_c() cdef long val @@ -842,7 +819,7 @@ cdef class TateAlgebraTerm(MonoidElement): - ``other`` -- a Tate term - - ``integral`` -- (default: ``False``); if ``True``, test + - ``integral`` -- (default: ``False``) if ``True``, test for divisibility in the ring of integers of the Tate algebra EXAMPLES:: @@ -887,7 +864,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: s.is_divisible_by(to) True - """ return (other)._divides_c(self, integral) @@ -900,7 +876,7 @@ cdef class TateAlgebraTerm(MonoidElement): - ``other`` -- a Tate term - - ``integral`` -- (default: ``False``); if ``True``, test for + - ``integral`` -- (default: ``False``) if ``True``, test for divisibility in the ring of integers of the Tate algebra EXAMPLES:: @@ -945,7 +921,6 @@ cdef class TateAlgebraTerm(MonoidElement): sage: to.divides(s) True - """ return self._divides_c(other, integral) @@ -957,7 +932,7 @@ cdef class TateAlgebraTerm(MonoidElement): - ``other`` -- a Tate term - - ``integral`` -- (default: ``False``) if ``True``, test for + - ``integral`` -- boolean (default: ``False``); if ``True``, test for divisibility in the ring of integers of the Tate algebra EXAMPLES:: @@ -971,7 +946,6 @@ cdef class TateAlgebraTerm(MonoidElement): ...000000000100*x*y^3 sage: t.divides(s) # indirect doctest False - """ parent = self._parent if (integral or not parent.base_ring().is_field()) and self.valuation() > other.valuation(): @@ -1007,7 +981,6 @@ cdef class TateAlgebraTerm(MonoidElement): Traceback (most recent call last): ... ValueError: the division is not exact - """ if not self.is_divisible_by(other): raise ValueError("the division is not exact") @@ -1039,7 +1012,6 @@ cdef class TateAlgebraTerm(MonoidElement): Traceback (most recent call last): ... ValueError: the division is not exact - """ cdef TateAlgebraTerm ans = self._new_c() ans._exponent = self.exponent().esub(other.exponent()) @@ -1061,7 +1033,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...00001 + ...00010*x + O(2^5 * ) sage: A(2*x+1, prec=20) ...0000000001 + ...00000000010*x + O(2^20 * ) - """ def __init__(self, parent, x, prec=None, reduce=True): r""" @@ -1072,7 +1043,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: R = Zp(2, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: TestSuite(x).run() - """ cdef TateAlgebraElement xc CommutativeAlgebraElement.__init__(self, parent) @@ -1130,7 +1100,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: A. = TateAlgebra(R) sage: x + y # indirect doctest ...0000000001*x + ...0000000001*y - """ cdef TateAlgebraElement ans = TateAlgebraElement.__new__(TateAlgebraElement) ans._parent = self._parent @@ -1146,7 +1115,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: A. = TateAlgebra(R) sage: A(78612, prec=3) # indirect doctest ...100 + O(2^3 * ) - """ self._is_normalized = True if self._prec is Infinity: @@ -1192,7 +1160,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: A(x + 2*x^2 + x^3, prec=5) ...00001*x^3 + ...00001*x + ...00010*x^2 + O(2^5 * ) - """ base = self._parent.base_ring() nvars = self._parent.ngens() @@ -1306,7 +1273,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): 5 sage: h.precision_absolute() 5 - """ cdef TateAlgebraElement ans = self._new_c() ans._poly = self._poly + (other)._poly @@ -1326,7 +1292,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x^3 + ...0000000001*x + ...00000000010*x^2 sage: -f # indirect doctest ...1111111111*x^3 + ...1111111111*x + ...11111111110*x^2 - """ cdef TateAlgebraElement ans = self._new_c() cdef Element s = self._parent.base_ring()(-1) @@ -1359,7 +1324,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): 5 sage: h.precision_absolute() 5 - """ cdef TateAlgebraElement ans = self._new_c() ans._poly = self._poly - (other)._poly @@ -1392,7 +1356,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): 5 sage: h.precision_absolute() 6 - """ cdef TateAlgebraElement ans = self._new_c() a = self._prec + (other).valuation() @@ -1417,7 +1380,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: 6*f # indirect doctest ...00000000110*x^3 + ...00000000110*x + ...000000001100*x^2 - """ cdef TateAlgebraElement ans = self._new_c() ans._poly = self._poly.scalar_lmult(right) @@ -1430,7 +1392,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); the precision at which the result is computed, if ``None``, the result is truncated according to the cap of the parent @@ -1461,7 +1423,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... ValueError: this series in not invertible - """ cdef TateAlgebraTerm t cdef long v, curprec @@ -1518,7 +1479,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: Ao = A.integer_ring() sage: Ao(f).is_unit() False - """ if self.is_zero(): return False @@ -1543,7 +1503,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): EXAMPLES:: - sage: R = Zp(3, prec=4, print_mode="digits") + sage: R = Zp(3, prec=4, print_mode='digits') sage: A. = TateAlgebra(R) sage: (x + y)^3 ...0001*x^3 + ...0001*y^3 + ...0010*x^2*y + ...0010*x*y^2 @@ -1555,7 +1515,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0001 + ...2210*x^2 + ...1100*x^4 + ...2200*y^2 + ...1000*x^6 + ...1000*x^2*y^2 + O(3^4 * ) - or a square root (or more generally a nth root):: + or a square root (or more generally an n-th root):: sage: g = f^(1/2); g ...0001 + ...0010*x^2 + ...1100*x^4 + ...1200*y^2 + ...2000*x^6 @@ -1590,7 +1550,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): True sage: f^(x*y) == (f^y)^x True - """ cdef TateAlgebraElement temp cdef long p, v, e @@ -1629,13 +1588,13 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); the precision at which the result is computed, if ``None``, the result is truncated according to the cap of the parent EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 6*x^2 + 9*y^2 sage: g = f.sqrt(); g @@ -1659,7 +1618,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... ValueError: not in the domain of convergence - """ return self.nth_root(2, prec) @@ -1669,13 +1627,13 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); the precision at which the result is computed, if ``None``, the result is truncated according to the cap of the parent EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 6*x^2 + 9*y^2 sage: g = f.sqrt(); g @@ -1699,29 +1657,28 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... ValueError: not in the domain of convergence - """ return self.nth_root(2, prec) def nth_root(self, n=2, prec=None): r""" - Return the ``n``-th root of this series. + Return the `n`-th root of this series. INPUT: - - ``n`` -- an integer (default: ``2``) + - ``n`` -- integer (default: `2`) - - ``prec`` -- an integer or ``None`` (default: ``None``); + - ``prec`` -- integer or ``None`` (default: ``None``); the precision at which the result is computed, if ``None``, the result is truncated according to the cap of the parent .. NOTE:: - The ``n``-th root is computed as `\exp(\frac 1 n \log(f))`. + The `n`-th root is computed as `\exp(\frac 1 n \log(f))`. EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 9*x^2 + 9*y^2 sage: g = f.nth_root(3, prec=3); g @@ -1742,7 +1699,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... ValueError: not in the domain of convergence - """ if n not in ZZ or n == 0: raise ValueError("n must be a nonzero integer") @@ -1831,7 +1787,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): False sage: f == g - 2 True - """ diff = self - other c = None @@ -1903,7 +1858,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f(pi, v) (pi^2 + O(pi^42)) + (1 + O(pi^40))*v^2 - """ cdef TateAlgebraTerm t parent = self._parent @@ -1941,7 +1895,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x^4 + ...0000000001 + ...000000000100*x*y sage: t*f # indirect doctest ...0000000011*x^6 + ...0000000011*x^2 + ...000000001100*x^3*y - """ cdef TateAlgebraElement ans = self._new_c() ans._poly = self._poly.term_lmult(term._exponent, term._coeff) @@ -1955,7 +1908,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer EXAMPLES:: @@ -1965,7 +1918,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x^3 + ...0000000001*x + ...00000000010*x^2 sage: f << 2 # indirect doctest ...000000000100*x^3 + ...000000000100*x + ...0000000001000*x^2 - """ cdef dict coeffs = { } cdef ETuple e @@ -1984,7 +1936,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -1999,7 +1951,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...00001*x^3 + ...00001*x + ...00010*x^2 + O(2^5 * ) sage: g << 2 ...0000100*x^3 + ...0000100*x + ...0001000*x^2 + O(2^7 * ) - """ cdef dict coeffs = { } cdef ETuple e @@ -2028,7 +1979,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -2049,7 +2000,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: Ao = A.integer_ring() sage: Ao(f) << -1 ...0000000001*x^2 + ...000000000*x^3 + ...000000000*x - """ return (self)._lshift_c(n) @@ -2060,7 +2010,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -2080,7 +2030,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: Ao = A.integer_ring() sage: Ao(f) << -1 ...0000000001*x^2 + ...000000000*x^3 + ...000000000*x - """ return (self)._lshift_c(-n) @@ -2107,7 +2056,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``), + - ``prec`` -- integer or ``None`` (default: ``None``), the precision at which the series should be compared to zero EXAMPLES:: @@ -2127,7 +2076,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): False sage: g.is_zero(4) True - """ cdef list terms = self._terms_c(include_zero=False) if prec is None: @@ -2142,7 +2090,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``log_radii`` -- an integer or a tuple; the log-radii of + - ``log_radii`` -- integer or a tuple; the log-radii of convergence of the smaller domain (see :class:`TateAlgebra` for more details) @@ -2163,7 +2111,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f.restriction([-1,-2]) ...00000000010*x + ...0000000001*y^2 - """ parent = self._parent from sage.rings.tate_algebra import TateAlgebra @@ -2189,7 +2136,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f = 2*x^2 + x sage: f.terms() [...0000000001*x, ...00000000010*x^2] - """ if not self._is_normalized: self._normalize() @@ -2202,8 +2148,8 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``include_zero`` -- a boolean (default: ``True``); if ``True``, - include terms which are indistinguishable from zero. + - ``include_zero`` -- boolean (default: ``True``); if ``True``, + include terms which are indistinguishable from zero EXAMPLES:: @@ -2212,7 +2158,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f = 2*x^2 + x sage: f.terms() # indirect doctest [...0000000001*x, ...00000000010*x^2] - """ cdef pAdicGenericElement c cdef ETuple e @@ -2244,7 +2189,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f = 2*x^2 + x sage: f.monomials() # indirect doctest [...0000000001*x, ...0000000001*x^2] - """ return [ t.monomial() for t in self.terms() ] @@ -2260,18 +2204,17 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f = 2*x^2 + x sage: f.dict() {(1, 0): ...0000000001, (2, 0): ...00000000010} - """ self._normalize() return dict(self._poly.__repn) def coefficient(self, exponent): r""" - Return the coefficient corresponding to the given exponent + Return the coefficient corresponding to the given exponent. INPUT: - - ``exponent`` -- a tuple of integers + - ``exponent`` -- tuple of integers EXAMPLES:: @@ -2309,11 +2252,11 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): def __getitem__(self, exponent): r""" - Return the coefficient corresponding to the given exponent + Return the coefficient corresponding to the given exponent. INPUT: - - ``exponent`` -- a tuple of integers + - ``exponent`` -- tuple of integers TESTS:: @@ -2344,7 +2287,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f = x + 2*x^2 sage: f.coefficients() [...0000000001, ...00000000010] - """ return [ t.coefficient() for t in self.terms() ] @@ -2354,7 +2296,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``n`` -- an integer + - ``n`` -- integer EXAMPLES:: @@ -2369,7 +2311,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...100000*x + O(2^6 * ) sage: g.precision_absolute() 6 - """ return self._parent(self, prec=n) @@ -2379,7 +2320,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``); if + - ``prec`` -- integer or ``None`` (default: ``None``); if ``None``, the cap of the parent is used if it is higher than the current precision @@ -2409,11 +2350,10 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): In the next example, the precision on the coefficient is only lifted to ``O(2^10)`` because it is limited by the cap of the underlying - p-adic ring:: + `p`-adic ring:: sage: g.lift_to_precision(20) (1 + O(2^10))*x*y + (1 + O(2^10))*x + (1 + O(2^10))*y + O(2^20 * ) - """ cdef TateAlgebraElement ans = self._new_c() # Hmm, shouldn't we add a keyword argument to lift_to_precision() @@ -2455,7 +2395,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x + ...00000000010*x^2 + O(2^20 * ) sage: g.precision_absolute() 20 - """ return self._prec @@ -2495,7 +2434,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f = x^4 + 4*x*y + 1 sage: f.valuation() -4 - """ cdef TateAlgebraTerm t cdef list terms = self._terms_c() @@ -2545,13 +2483,13 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - `prec` -- an integer or ``None`` (default: ``None``); the + - ``prec`` -- integer or ``None`` (default: ``None``); the absolute precision at which the result is computed, if ``None`` the cap of the Tate algebra is used EXAMPLES:: - sage: R = Zp(3, 10, print_mode="digits") + sage: R = Zp(3, 10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 3*x + 9*y^2 sage: f.log() @@ -2602,7 +2540,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: logf.exp() == f True - """ # This code is mostly copied from sage.rings.padics.padic_generic_element # (should we find a way to share it?) @@ -2707,13 +2644,13 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - `prec` -- an integer or ``None`` (default: ``None``); the + - ``prec`` -- integer or ``None`` (default: ``None``); the absolute precision at which the result is computed, if ``None`` the cap of the Tate algebra is used EXAMPLES:: - sage: R = Zp(3, 10, print_mode="digits") + sage: R = Zp(3, 10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 9*y sage: f.exp() @@ -2761,7 +2698,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: expf.log() == f # long time True - """ # This code is mostly copied from sage.rings.padics.padic_generic_element # (should we find a way to share it?) @@ -2810,10 +2746,10 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``secure`` -- a boolean (default: ``False``); if ``True``, + - ``secure`` -- boolean (default: ``False``); if ``True``, raises an error if the leading term cannot be determined due to the existence of terms which are indistinguishable - from zero; if ``False``, discard silently these terms + from zero. If ``False``, discard silently these terms. EXAMPLES:: @@ -2862,7 +2798,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): .. SEEALSO:: :meth:`leading_coefficient`, :meth:`leading_monomial` - """ cdef list terms cdef TateAlgebraTerm term @@ -2890,14 +2825,14 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``secure`` -- a boolean (default: ``False``); if ``True``, + - ``secure`` -- boolean (default: ``False``); if ``True``, raises an error if the leading term cannot be determined due to the existence of terms which are indistinguishable - from zero; if ``False``, discard silently these terms + from zero. If ``False``, discard silently these terms. EXAMPLES:: - sage: R = Zp(2, prec=10, print_mode="terse") + sage: R = Zp(2, prec=10, print_mode='terse') sage: A. = TateAlgebra(R) sage: f = x^4 + 3*x*y + 1; f (1 + O(2^10))*x^4 + (3 + O(2^10))*x*y + (1 + O(2^10)) @@ -2912,7 +2847,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): .. SEEALSO:: :meth:`leading_term`, :meth:`leading_monomial` - """ return self.leading_term(secure=secure).coefficient() @@ -2926,10 +2860,10 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``secure`` -- a boolean (default: ``False``); if ``True``, + - ``secure`` -- boolean (default: ``False``); if ``True``, raises an error if the leading term cannot be determined due to the existence of terms which are indistinguishable - from zero; if ``False``, discard silently these terms + from zero. If ``False``, discard silently these terms. EXAMPLES:: @@ -2948,7 +2882,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): .. SEEALSO:: :meth:`leading_term`, :meth:`leading_coefficient` - """ return self.leading_term(secure=secure).monomial() @@ -2985,7 +2918,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... ZeroDivisionError: rational division by zero - """ cdef TateAlgebraElement ans = self._new_c() cdef TateAlgebraTerm t @@ -3043,7 +2975,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x*y + ...0000000001*y + ...00000000010*x^4 sage: f.weierstrass_degree() 2 - """ v = self.valuation() return self.residue(v+1).degree() @@ -3065,7 +2996,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x*y + ...0000000001*y + ...00000000010*x^4 sage: f.degree() 2 - """ return self.weierstrass_degree() @@ -3086,7 +3016,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x^2 + ...0000000001*y^2 + ...0000000001*y + ...00000000010*x^3 sage: f.weierstrass_degrees() (2, 2) - """ v = self.valuation() return self.residue(v+1).degrees() @@ -3108,7 +3037,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...0000000001*x^2 + ...0000000001*y^2 + ...0000000001*y + ...00000000010*x^3 sage: f.degrees() (2, 2) - """ return self.weierstrass_degrees() @@ -3120,7 +3048,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): INPUT: - - ``n`` -- an integer (default: ``1``) + - ``n`` -- integer (default: `1`) EXAMPLES:: @@ -3137,14 +3065,14 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: f.residue(2).parent() Multivariate Polynomial Ring in x, y over Ring of integers modulo 4 - The residue can only be computed for series with non-negative valuation. + The residue can only be computed for series with nonnegative valuation. sage: g = f >> 2; g ...00000000.01*x^2 + ...00000000.01*y^2 + ...00000000.11*y + ...000000001.1*x^3 sage: g.residue() Traceback (most recent call last): ... - ValueError: element must have non-negative valuation in order to compute residue + ValueError: element must have nonnegative valuation in order to compute residue The residue is not implemented for series with convergence radius different from 1. @@ -3154,7 +3082,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... NotImplementedError: residues are only implemented for radius 1 - """ for r in self._parent.log_radii(): if r != 0: @@ -3165,7 +3092,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): try: Rn = self.base_ring().residue_ring(n) except (AttributeError, NotImplementedError): - Rn = self.base_ring().change(field=False, type="fixed-mod", prec=n) + Rn = self.base_ring().change(field=False, type='fixed-mod', prec=n) poly = self._parent._polynomial_ring(self._poly) return poly.change_ring(Rn) @@ -3177,13 +3104,13 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): - ``divisors`` -- the list of divisors - - ``quo`` -- a boolean, whether we should compute the quotients + - ``quo`` -- boolean; whether we should compute the quotients - - ``rem`` -- a boolean, whether we should compute the remainder + - ``rem`` -- boolean; whether we should compute the remainder TESTS:: - sage: R = Zp(2, 5, print_mode="digits") + sage: R = Zp(2, 5, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 2*x*y + 3*x^2*y + 4*x*y^2 sage: g = x^2 @@ -3192,7 +3119,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...00011*y sage: r ...00001 + ...00010*x*y + ...00100*x*y^2 + O(2^5 * ) - """ cdef dict coeffs = { } cdef TateAlgebraElement f @@ -3250,9 +3176,9 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): - ``divisors`` -- the list of divisors - - ``quo`` -- a boolean, whether we should compute the quotients + - ``quo`` -- boolean; whether we should compute the quotients - - ``rem`` -- a boolean, whether we should compute the remainder + - ``rem`` -- boolean; whether we should compute the remainder TESTS:: @@ -3290,7 +3216,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... TypeError: cannot coerce all the elements to the same parent - """ parent = self.parent() if self.precision_absolute() is Infinity: @@ -3334,7 +3259,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): EXAMPLES:: - sage: R = Zp(2, 5, print_mode="digits") + sage: R = Zp(2, 5, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 2*x*y + 3*x^2*y + 4*x*y^2 sage: g = x^2 @@ -3357,7 +3282,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): ...00001 + ...01100*x + O(2^5 * ) sage: f == g0*q[0] + g1*q[1] + r True - """ return (self)._quo_rem_check(divisors, True, True) @@ -3372,7 +3296,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): EXAMPLES:: - sage: R = Zp(2, 5, print_mode="digits") + sage: R = Zp(2, 5, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 2*x*y + 3*x^2*y + 4*x*y^2 sage: g = x^2 @@ -3385,7 +3309,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: g1 = x*y + 2*x sage: f % [g0, g1] ...00001 + ...01100*x + O(2^5 * ) - """ return (self)._quo_rem_check(divisors, False, True) @@ -3400,7 +3323,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): EXAMPLES:: - sage: R = Zp(2, 5, print_mode="digits") + sage: R = Zp(2, 5, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 1 + 2*x*y + 3*x^2*y + 4*x*y^2 sage: g = x^2 @@ -3413,7 +3336,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: g1 = x*y + 2*x sage: f // [g0, g1] [...00011*y, ...11010 + ...00100*y] - """ return (self)._quo_rem_check(divisors, True, False) @@ -3425,7 +3347,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 @@ -3446,7 +3368,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): sage: h = A.random_element() sage: (h + s).reduce(I) == h.reduce(I) True - """ return self % I.groebner_basis() @@ -3475,7 +3396,7 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): EXAMPLES:: - sage: R = Zp(2, 5, print_mode="digits") + sage: R = Zp(2, 5, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = x^3*y + 2*x*y + 4*x^2 sage: g = 2*x*y^2 + 2*x @@ -3491,7 +3412,6 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): Traceback (most recent call last): ... ValueError: the S-polynomial of zero is not defined - """ try: return self._Spoly_c(other) @@ -3510,13 +3430,12 @@ cdef class TateAlgebraElement(CommutativeAlgebraElement): We check that the S-polynomial of two monomials vanishes:: - sage: R = Zp(3, 5, print_mode="digits") + sage: R = Zp(3, 5, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = x^3*y^2 sage: g = x^2*y^3 sage: f.Spoly(g) 0 - """ cdef TateAlgebraTerm st = self._terms_c()[0] cdef TateAlgebraTerm ot = other._terms_c()[0] diff --git a/src/sage/rings/tate_algebra_ideal.pyx b/src/sage/rings/tate_algebra_ideal.pyx index 5d72155f97c..830b01686c2 100644 --- a/src/sage/rings/tate_algebra_ideal.pyx +++ b/src/sage/rings/tate_algebra_ideal.pyx @@ -38,43 +38,42 @@ from cysignals.signals cimport sig_check class TateAlgebraIdeal(Ideal_generic): r""" - Initialize a class for ideals in a Tate series algebra + Initialize a class for ideals in a Tate series algebra. EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 sage: I = A.ideal([f,g]); I Ideal (...0000000012*x*y^2 + ...00000000010*x^2, ...0000000012*x^2*y + ...00000000010) of Tate Algebra in x (val >= 0), y (val >= 0) over 3-adic Field with capped relative precision 10 - """ #@cached_method def groebner_basis(self, prec=None, algorithm='VaPoTe', **options): r""" - Compute a Groebner basis of the ideal + Compute a Groebner basis of the ideal. INPUT: - - ``prec`` -- an integer or ``None`` (default: ``None``), the precision + - ``prec`` -- integer or ``None`` (default: ``None``); the precision at which the computations are carried. If ``None``, defaults to the - algebra precision cap + algebra precision cap. - - ``algorithm`` -- a string (default: ``VaPoTe``), the algorithm to + - ``algorithm`` -- string (default: ``'VaPoTe'``), the algorithm to use in the calculations; available algorithms are: - - ``buchberger``: classical Buchberger algorithm + - ``'buchberger'``: classical Buchberger algorithm - - ``buchberger-integral``: first computes a Groebner basis of the + - ``'buchberger-integral'``: first computes a Groebner basis of the ideal generated by the same generators over the ring of integers (provides better numerical stability) - - ``PoTe``: a F5-type algorithm where signatures are ordered by + - ``'PoTe'``: a F5-type algorithm where signatures are ordered by position over term - - ``VaPoTe``: a F5-type algorithm where signatures are ordered + - ``'VaPoTe'``: a F5-type algorithm where signatures are ordered by valuation over position over term We refer to [CVV2019]_ and [CVV2020]_ for a detailed description @@ -121,7 +120,7 @@ class TateAlgebraIdeal(Ideal_generic): EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 @@ -140,7 +139,7 @@ class TateAlgebraIdeal(Ideal_generic): sage: g = x^4*y^5 + x^5*y^2 + x^4 + 5*x^2*y + 2*x^5*y^4 + 2*x^6*y + 6*x^3*y^3 sage: h = 2*x^6*y^4 + 2*x^4 + 4*x^5*y^2 + 8*x^8*y^2 + 8*x^7*y^3 + 8*x^6*y sage: I = A.ideal([f,g,h]) - sage: I.groebner_basis(algorithm="buchberger-integral") + sage: I.groebner_basis(algorithm='buchberger-integral') [...0001*x^4 + O(2^4 * ), ...0001*x^2*y + O(2^4 * ), ...0001*y^2 + O(2^4 * )] @@ -151,11 +150,10 @@ class TateAlgebraIdeal(Ideal_generic): TESTS:: - sage: I.groebner_basis(algorithm="F4") + sage: I.groebner_basis(algorithm='F4') Traceback (most recent call last): ... NotImplementedError: available algorithms are 'buchberger', 'buchberger-integral', 'PoTe' and 'VaPoTe' - """ if prec is None: prec = self.ring().precision_cap() @@ -172,7 +170,7 @@ class TateAlgebraIdeal(Ideal_generic): def _contains_(self, x): r""" - Return ``True`` if ``x`` lies in this ideal + Return ``True`` if ``x`` lies in this ideal. INPUT: @@ -196,14 +194,13 @@ class TateAlgebraIdeal(Ideal_generic): sage: I.random_element() in I True - """ rgb = self.groebner_basis() return (x % rgb).is_zero() def _contains_ideal(self, I): r""" - Return ``True`` if ``I`` is contained in this ideal + Return ``True`` if ``I`` is contained in this ideal. INPUT: @@ -211,7 +208,7 @@ class TateAlgebraIdeal(Ideal_generic): EXAMPLES:: - sage: R = Zp(3,prec=10,print_mode="digits") + sage: R = Zp(3,prec=10,print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 @@ -264,7 +261,6 @@ class TateAlgebraIdeal(Ideal_generic): True sage: A.ideal([f]) == I False - """ if op == op_GT: return self._contains_ideal(other) and not other._contains_ideal(self) @@ -296,7 +292,7 @@ class TateAlgebraIdeal(Ideal_generic): Over classical Tate algebras (where `\pi` is invertible), this method always returns ``True``:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 @@ -322,7 +318,6 @@ class TateAlgebraIdeal(Ideal_generic): sage: Ao.ideal([3*f]).is_saturated() False - """ if self.ring().base_ring().is_field(): return True @@ -354,7 +349,7 @@ class TateAlgebraIdeal(Ideal_generic): Over classical Tate algebras (where `\pi` is invertible), this method always returns the same ideal:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 @@ -391,7 +386,6 @@ class TateAlgebraIdeal(Ideal_generic): True sage: 3*Ios < Io True - """ if self.ring().base_ring().is_field(): return self @@ -407,7 +401,7 @@ class TateAlgebraIdeal(Ideal_generic): def groebner_basis_buchberger(I, prec, py_integral): r""" - Compute a Groebner basis of the Tate algebra ideal I using Buchberger's algorithm + Compute a Groebner basis of the Tate algebra ideal I using Buchberger's algorithm. INPUT: @@ -416,7 +410,7 @@ def groebner_basis_buchberger(I, prec, py_integral): - ``prec`` -- the related precision at which the initial generators are truncated - - ``integral`` -- a boolean; if ``True``, first compute a + - ``integral`` -- boolean; if ``True``, first compute a Grobner basis of the ideal generated by the same generators over the ring over the ring of integers @@ -427,7 +421,7 @@ def groebner_basis_buchberger(I, prec, py_integral): EXAMPLES:: - sage: R = Zp(3, prec=10, print_mode="digits"); + sage: R = Zp(3, prec=10, print_mode='digits'); sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 @@ -437,7 +431,6 @@ def groebner_basis_buchberger(I, prec, py_integral): [...000000001*x^3 + ...222222222*y + O(3^9 * ), ...0000000001*x^2*y + ...1210121020 + O(3^10 * ), ...000000001*y^2 + ...210121020*x + O(3^9 * )] - """ cdef list gb, rgb, indices, ts, S = [ ] cdef int i, j, l @@ -569,7 +562,7 @@ def groebner_basis_buchberger(I, prec, py_integral): cdef Jpair(p1, p2): r""" - Return the J-pair of ``p1`` and ``p2`` + Return the J-pair of ``p1`` and ``p2``. INPUT: @@ -602,11 +595,11 @@ cdef Jpair(p1, p2): cdef TateAlgebraElement regular_reduce(sgb, TateAlgebraTerm s, TateAlgebraElement v, stopval): r""" - Return the result of the regular reduction of the pair ``(s,v)`` by ``sgb`` + Return the result of the regular reduction of the pair ``(s,v)`` by ``sgb``. INPUT: - - ``sgb`` -- a list of pairs (signature, series), candidate to be a strong + - ``sgb`` -- list of pairs (signature, series), candidate to be a strong Groebner basis; all leading coefficients are assumed to be a power of the uniformizer @@ -686,11 +679,11 @@ cdef TateAlgebraElement regular_reduce(sgb, TateAlgebraTerm s, TateAlgebraElemen cdef TateAlgebraElement reduce(gb, TateAlgebraElement v, stopval): r""" - Return the result of the reduction of ``v`` by ``gb`` + Return the result of the reduction of ``v`` by ``gb``. INPUT: - - ``gb`` -- a list of reductors + - ``gb`` -- list of reductors - ``v`` -- a series @@ -752,18 +745,18 @@ cdef TateAlgebraElement reduce(gb, TateAlgebraElement v, stopval): def print_pair(p, verbose): r""" - Return a string representation of the pair ``p`` + Return a string representation of the pair ``p``. INPUT: - ``p`` -- a pair (signature, series) - - ``verbose`` -- an integer + - ``verbose`` -- integer TESTS:: sage: from sage.rings.tate_algebra_ideal import print_pair - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: v = 3*x^2 + 5*x*y^2 sage: s = v.leading_term() @@ -798,21 +791,21 @@ def groebner_basis_pote(I, prec, verbose=0): - ``prec`` -- the precision at which the Groebner basis is computed - - ``verbose`` -- an integer (default: ``0``) + - ``verbose`` -- integer (default: 0) TESTS:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 sage: I = A.ideal([f,g]) - sage: I.groebner_basis(algorithm="PoTe") # indirect doctest + sage: I.groebner_basis(algorithm='PoTe') # indirect doctest [...000000001*x^3 + ...222222222*y + O(3^9 * ), ...0000000001*x^2*y + ...1210121020 + O(3^10 * ), ...000000001*y^2 + ...210121020*x + O(3^9 * )] - sage: I.groebner_basis(algorithm="PoTe", verbose=2) # indirect doctest + sage: I.groebner_basis(algorithm='PoTe', verbose=2) # indirect doctest --- new generator: ...0000000001*x*y^2 + ... 0 initial J-pairs @@ -851,7 +844,7 @@ def groebner_basis_pote(I, prec, verbose=0): We check that :issue:`30101` is fixed:: - sage: I.groebner_basis(algorithm="PoTe", prec=100) # indirect doctest + sage: I.groebner_basis(algorithm='PoTe', prec=100) # indirect doctest [...0000000001*x^3 + ...2222222222*y + ...000000000*x^2*y^2 + O(3^99 * ), ...0000000001*x^2*y + ...01210121020 + O(3^100 * ), ...0000000001*y^2 + ...01210121020*x + ...0000000000*x^3*y + O(3^99 * )] @@ -1028,34 +1021,34 @@ def groebner_basis_vapote(I, prec, verbose=0, interrupt_red_with_val=False, inte - ``prec`` -- the precision at which the Groebner basis is computed - - ``verbose`` -- an integer (default: ``0``) + - ``verbose`` -- integer (default: 0) - - ``interrupt_red_with_val`` -- a boolean (default: ``False``); if + - ``interrupt_red_with_val`` -- boolean (default: ``False``); if regular reductions have to be interrupted as soon as the valuation raises - - ``interrupt_interred_with_val`` -- a boolean (default: ``False''); + - ``interrupt_interred_with_val`` -- boolean (default: ``False''); if intermediate interreductions of the Groebner basis have to be interrupted as soon as the valuation raises TESTS:: - sage: R = Zp(3, prec=10, print_mode="digits") + sage: R = Zp(3, prec=10, print_mode='digits') sage: A. = TateAlgebra(R) sage: f = 3*x^2 + 5*x*y^2 sage: g = 5*x^2*y + 3 sage: I = A.ideal([f,g]) - sage: I.groebner_basis(algorithm="VaPoTe") # indirect doctest + sage: I.groebner_basis(algorithm='VaPoTe') # indirect doctest [...000000001*x^3 + ...222222222*y + O(3^9 * ), ...0000000001*x^2*y + ...1210121020 + O(3^10 * ), ...000000001*y^2 + ...210121020*x + O(3^9 * )] - sage: I.groebner_basis(algorithm="VaPoTe", interrupt_red_with_val=True) # indirect doctest + sage: I.groebner_basis(algorithm='VaPoTe', interrupt_red_with_val=True) # indirect doctest [...000000001*x^3 + ...222222222*y + O(3^9 * ), ...0000000001*x^2*y + ...1210121020 + O(3^10 * ), ...000000001*y^2 + ...210121020*x + O(3^9 * )] - sage: I.groebner_basis(algorithm="VaPoTe", verbose=2) # indirect doctest + sage: I.groebner_basis(algorithm='VaPoTe', verbose=2) # indirect doctest grobner basis reduced --- new generator: ...0000000012*x*y^2 + ... @@ -1097,7 +1090,7 @@ def groebner_basis_vapote(I, prec, verbose=0, interrupt_red_with_val=False, inte We check that :issue:`30101` is fixed:: - sage: I.groebner_basis(algorithm="VaPoTe", prec=100) # indirect doctest + sage: I.groebner_basis(algorithm='VaPoTe', prec=100) # indirect doctest [...0000000001*x^3 + ...2222222222*y + ...000000000*x^2*y^2 + O(3^99 * ), ...0000000001*x^2*y + ...01210121020 + O(3^100 * ), ...0000000001*y^2 + ...01210121020*x + ...0000000000*x^3*y + O(3^99 * )] diff --git a/src/sage/rings/tests.py b/src/sage/rings/tests.py index ef8d65da7e1..3796ef7b276 100644 --- a/src/sage/rings/tests.py +++ b/src/sage/rings/tests.py @@ -102,7 +102,7 @@ def integer_mod_ring(): def padic_field(): """ - Return a random p-adic field modulo n with p at most 10000 + Return a random `p`-adic field modulo n with p at most 10000 and precision between 10 and 100. EXAMPLES:: @@ -344,12 +344,10 @@ def test_random_elements(level=MAX_LEVEL, trials=1): INPUT: - - level -- (default: MAX_LEVEL); controls the types of rings to use - - trials -- A positive integer (default 1); the number of trials - to run. - - seed -- the random seed to use; if not specified, uses a truly - random seed. - - print_seed -- If True (default: ``False``), prints the random seed chosen. + - ``level`` -- (default: ``MAX_LEVEL``) controls the types of rings to use + - ``trials`` -- a positive integer (default: 1); the number of trials to run + - ``seed`` -- the random seed to use; if not specified, uses a truly random seed + - ``print_seed`` -- if ``True`` (default: ``False``), prints the random seed chosen EXAMPLES:: @@ -395,12 +393,10 @@ def test_random_arith(level=MAX_LEVEL, trials=1): INPUT: - - ``level`` -- (default: ``MAX_LEVEL``); controls the types of rings to use - - ``trials`` -- A positive integer (default: 1); the number of trials - to run. - - ``seed`` -- the random seed to use; if not specified, uses a truly - random seed. - - ``print_seed`` -- If ``True`` (default: ``False``), prints the random seed chosen. + - ``level`` -- (default: ``MAX_LEVEL``) controls the types of rings to use + - ``trials`` -- positive integer (default: 1); the number of trials to run + - ``seed`` -- the random seed to use; if not specified, uses a truly random seed + - ``print_seed`` -- if ``True`` (default: ``False``), prints the random seed chosen EXAMPLES:: @@ -486,7 +482,6 @@ def test_karatsuba_multiplication(base_ring, maxdeg1, maxdeg2, sage: test_karatsuba_multiplication(ZZ, 10000, 10000, # long time ....: ref_mul=lambda f,g: f*g, ....: base_ring_random_elt_args=[100000]) - """ from sage.misc.prandom import randint from sage.misc.sage_input import sage_input diff --git a/src/sage/rings/universal_cyclotomic_field.py b/src/sage/rings/universal_cyclotomic_field.py index ee3e48a1bd5..35c6b90a76b 100644 --- a/src/sage/rings/universal_cyclotomic_field.py +++ b/src/sage/rings/universal_cyclotomic_field.py @@ -642,7 +642,7 @@ def _algebraic_(self, R): sage: AA(UCF.gen(5)) Traceback (most recent call last): ... - ValueError: Cannot coerce algebraic number with non-zero imaginary + ValueError: Cannot coerce algebraic number with nonzero imaginary part to algebraic real """ return R(QQbar(self)) @@ -1047,13 +1047,13 @@ def sqrt(self, extend=True, all=False): INPUT: - - ``extend`` -- bool (default: ``True``); if ``True``, might return a - square root in the algebraic closure of the rationals. If false, - return a square root in the universal cyclotomic field or raises - an error. + - ``extend`` -- boolean (default: ``True``); if ``True``, might return + a square root in the algebraic closure of the rationals. If + ``False``, return a square root in the universal cyclotomic field or + raises an error. - - ``all`` -- bool (default: ``False``); if ``True``, return a - list of all square roots. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + list of all square roots EXAMPLES:: @@ -1249,7 +1249,7 @@ def minpoly(self, var='x'): INPUT: - - ``var`` -- (default: 'x') the name of the variable to use. + - ``var`` -- (default: ``'x'``) the name of the variable to use EXAMPLES:: @@ -1586,8 +1586,8 @@ def _factor_univariate_polynomial(self, f): OUTPUT: - - A factorization of ``f`` over self into a unit and monic irreducible - factors + A factorization of ``f`` over ``self`` into a unit and monic + irreducible factors. .. NOTE:: @@ -1620,7 +1620,7 @@ def _factor_univariate_polynomial(self, f): (x - 2) * (x - 2*E(3)) * (x - 2*E(3)^2) In most situations, the factorization will fail with a - :class:`NotImplementedError`:: + :exc:`NotImplementedError`:: sage: (x^3 - 2).factor() Traceback (most recent call last): diff --git a/src/sage/rings/valuation/augmented_valuation.py b/src/sage/rings/valuation/augmented_valuation.py index 3d415c6e83c..e751cfabd9c 100644 --- a/src/sage/rings/valuation/augmented_valuation.py +++ b/src/sage/rings/valuation/augmented_valuation.py @@ -182,7 +182,6 @@ class AugmentedValuationFactory(UniqueFactory): sage: ww = w.augmentation(x, 2) sage: ww._base_valuation is v True - """ def create_key(self, base_valuation, phi, mu, check=True): r""" @@ -205,7 +204,6 @@ def create_key(self, base_valuation, phi, mu, check=True): sage: ww = v.augmentation(x, 1) sage: w is ww True - """ if check: is_key, reason = base_valuation.is_key(phi, explain=True) @@ -236,7 +234,6 @@ def create_object(self, version, key): sage: R. = QQ[] sage: v = GaussValuation(R, QQ.valuation(2)) sage: w = v.augmentation(x^2 + x + 1, 1) # indirect doctest - """ base_valuation, phi, mu = key @@ -285,7 +282,6 @@ class AugmentedValuation_base(InductiveValuation): sage: # needs sage.rings.number_field sage: TestSuite(w).run() # long time sage: TestSuite(ww).run() # long time - """ def __init__(self, parent, v, phi, mu): r""" @@ -301,7 +297,6 @@ def __init__(self, parent, v, phi, mu): sage: isinstance(w, AugmentedValuation_base) True sage: TestSuite(w).run() # long time # needs sage.numerical.mip - """ InductiveValuation.__init__(self, parent, phi) @@ -317,7 +312,7 @@ def equivalence_unit(self, s, reciprocal=False): - ``s`` -- a rational number - - ``reciprocal`` -- a boolean (default: ``False``); whether or not to + - ``reciprocal`` -- boolean (default: ``False``); whether or not to return the equivalence unit as the :meth:`~sage.rings.valuation.inductive_valuation.InductiveValuation.equivalence_reciprocal` of the equivalence unit of valuation ``-s``. @@ -356,7 +351,6 @@ def equivalence_unit(self, s, reciprocal=False): sage: ww = w.augmentation(x^4 + 8, 5) # needs sage.libs.ntl sage: ww.equivalence_unit(1/2) # needs sage.libs.ntl (2^-1 + O(2^4))*x^2 - """ if reciprocal: ret = self._base_valuation.element_with_valuation(s) @@ -379,9 +373,7 @@ def element_with_valuation(self, s): - ``s`` -- a rational number in the value group of this valuation - OUTPUT: - - An element in the domain of this valuation + OUTPUT: an element in the domain of this valuation EXAMPLES:: @@ -405,7 +397,6 @@ def element_with_valuation(self, s): ... ValueError: s must be in the value group of the valuation but 1/3 is not in Additive Abelian Group generated by 1/2. - """ if s not in self.value_group(): raise ValueError("s must be in the value group of the valuation but %r is not in %r." % (s, self.value_group())) @@ -432,7 +423,6 @@ def _repr_(self): sage: w # indirect doctest [ Gauss valuation induced by 2-adic valuation, v((1 + O(2^5))*x^2 + (1 + O(2^5))*x + u + O(2^5)) = 1/2 ] - """ vals = self.augmentation_chain() vals.reverse() @@ -461,7 +451,6 @@ def augmentation_chain(self): sage: ww.augmentation_chain() [[ Gauss valuation induced by 2-adic valuation, v(x) = 2 ], Gauss valuation induced by 2-adic valuation] - """ return [self] + self._base_valuation.augmentation_chain() @@ -470,9 +459,7 @@ def psi(self): r""" Return the minimal polynomial of the residue field extension of this valuation. - OUTPUT: - - A polynomial in the residue ring of the base valuation + OUTPUT: a polynomial in the residue ring of the base valuation EXAMPLES:: @@ -486,7 +473,6 @@ def psi(self): sage: ww = w.augmentation((x^2 + x + u)^2 + 2, 5/3) sage: ww.psi() x + 1 - """ R = self._base_valuation.equivalence_unit(-self._base_valuation(self._phi)) F = self._base_valuation.reduce(self._phi * R, check=False).monic() @@ -511,7 +497,6 @@ def E(self): sage: w = v.augmentation(x, 1/2) sage: w.E() 2 - """ if self.augmentation_chain()[-1]._base_valuation.is_trivial(): raise NotImplementedError("ramification index is not defined over a trivial Gauss valuation") @@ -535,7 +520,6 @@ def F(self): sage: w = v.augmentation(x, 1/2) sage: w.F() 1 - """ return self.phi().degree() // self._base_valuation.E() @@ -550,13 +534,12 @@ def extensions(self, ring): sage: w = v.augmentation(x^2 + x + 1, 1) sage: w.extensions(GaussianIntegers().fraction_field()['x']) # needs sage.rings.number_field [[ Gauss valuation induced by 2-adic valuation, v(x^2 + x + 1) = 1 ]] - """ if ring is self.domain(): return [self] - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring): # univariate + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general): # univariate base_valuations = self._base_valuation.extensions(ring) phi = self.phi().change_ring(ring.base_ring()) @@ -595,8 +578,8 @@ def restriction(self, ring): base = self._base_valuation.restriction(ring) if ring.is_subring(self.domain().base_ring()): return base - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring): # univariate + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general): # univariate return base.augmentation(self.phi().change_ring(ring.base_ring()), self._mu) return super().restriction(ring) @@ -612,7 +595,6 @@ def uniformizer(self): sage: w.uniformizer() 2 - """ return self.element_with_valuation(self.value_group()._generator) @@ -628,7 +610,6 @@ def is_gauss_valuation(self): sage: w.is_gauss_valuation() False - """ assert (self._mu > 0) return False @@ -650,7 +631,6 @@ def monic_integral_model(self, G): Ring endomorphism of Univariate Polynomial Ring in x over Rational Field Defn: x |--> 2*x, x^2 + 1/5*x + 1/5) - """ return self._base_valuation.monic_integral_model(G) @@ -674,7 +654,6 @@ def _ge_(self, other): True sage: www >= ww False - """ from .gauss_valuation import GaussValuation_generic if other.is_trivial(): @@ -700,7 +679,6 @@ def is_trivial(self): sage: w = v.augmentation(x^2 + x + 1, 1) sage: w.is_trivial() False - """ # We need to override the default implementation from valuation_space # because that one uses uniformizer() which might not be implemented if @@ -718,7 +696,6 @@ def scale(self, scalar): sage: w = v.augmentation(x^2 + x + 1, 1) sage: 3*w # indirect doctest [ Gauss valuation induced by 3 * 2-adic valuation, v(x^2 + x + 1) = 3 ] - """ if scalar in QQ and scalar > 0 and scalar != 1: return self._base_valuation.scale(scalar).augmentation(self.phi(), scalar * self._mu) @@ -738,7 +715,6 @@ def _residue_ring_generator_name(self): sage: w = v.augmentation(x^2 + x + 1, 1) sage: w._residue_ring_generator_name() 'u1' - """ base = self._base_valuation.residue_ring().base() # we need a name for a generator that is not present already in base @@ -779,7 +755,6 @@ def _relative_size(self, f): 1 sage: w._relative_size(1048576*x^2 + 1048576*x + 1048576) 11 - """ return self._base_valuation._relative_size(f) @@ -797,7 +772,6 @@ def is_negative_pseudo_valuation(self): sage: w = v.augmentation(x, infinity) sage: w.is_negative_pseudo_valuation() False - """ return False @@ -815,10 +789,9 @@ def change_domain(self, ring): sage: v = v.augmentation(x, 1) sage: v.change_domain(QQ['x']) [ Gauss valuation induced by 2-adic valuation, v(x) = 1 ] - """ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring) and ring.variable_name() == self.domain().variable_name(): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general) and ring.variable_name() == self.domain().variable_name(): return self._base_valuation.change_domain(ring).augmentation(self.phi().change_ring(ring.base_ring()), self._mu, check=False) return super().change_domain(ring) @@ -833,7 +806,6 @@ class FinalAugmentedValuation(AugmentedValuation_base, FinalInductiveValuation): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: w = v.augmentation(x, 1) - """ def __init__(self, parent, v, phi, mu): r""" @@ -845,7 +817,6 @@ def __init__(self, parent, v, phi, mu): sage: from sage.rings.valuation.augmented_valuation import FinalAugmentedValuation sage: isinstance(w, FinalAugmentedValuation) True - """ AugmentedValuation_base.__init__(self, parent, v, phi, mu) FinalInductiveValuation.__init__(self, parent, phi) @@ -854,7 +825,7 @@ def __init__(self, parent, v, phi, mu): def residue_ring(self): r""" Return the residue ring of this valuation, i.e., the elements of - non-negative valuation modulo the elements of positive valuation. + nonnegative valuation modulo the elements of positive valuation. EXAMPLES:: @@ -898,7 +869,6 @@ def residue_ring(self): Number Field in uu1 with defining polynomial y^2 - 2 over its base field sage: w.residue_field().base_field() Number Field in u1 with defining polynomial x^2 + 2 - """ # the following is correct, even if the polynomial ring is not over a field @@ -922,7 +892,7 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations - ``f`` -- an element in the domain of this valuation - - ``check`` -- whether or not to check whether ``f`` has non-negative + - ``check`` -- whether or not to check whether ``f`` has nonnegative valuation (default: ``True``) - ``degree_bound`` -- an a-priori known bound on the degree of the @@ -994,14 +964,13 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations x sage: ww.reduce(f + g) x + 1 - """ f = self.domain().coerce(f) if check: v = self(f) if v < 0: - raise ValueError("f must have non-negative valuation") + raise ValueError("f must have nonnegative valuation") elif v > 0: return self.residue_ring().zero() @@ -1039,7 +1008,6 @@ def _residue_field_generator(self): sage: w = v.augmentation(x^2 + x + u, infinity) sage: w._residue_field_generator() # needs sage.rings.number_field u1 - """ if self.psi().degree() == 1: ret = self.residue_ring()(-self.psi()[0]) @@ -1061,9 +1029,7 @@ def lift(self, F): We simply undo the steps performed in :meth:`reduce`. - OUTPUT: - - A polynomial in the domain of the valuation with reduction ``F`` + OUTPUT: a polynomial in the domain of the valuation with reduction ``F`` EXAMPLES:: @@ -1100,7 +1066,6 @@ def lift(self, F): sage: v = v0.augmentation(x^2 + x + 2, 1) sage: v.lift(v.reduce(x)) == x True - """ F = self.residue_ring().coerce(F) @@ -1140,7 +1105,6 @@ class NonFinalAugmentedValuation(AugmentedValuation_base, NonFinalInductiveValua sage: R. = QQ[] sage: v = GaussValuation(R, QQ.valuation(2)) sage: w = v.augmentation(x^2 + x + 1, 1) - """ def __init__(self, parent, v, phi, mu): r""" @@ -1152,7 +1116,6 @@ def __init__(self, parent, v, phi, mu): sage: from sage.rings.valuation.augmented_valuation import NonFinalAugmentedValuation sage: isinstance(w, NonFinalAugmentedValuation) True - """ AugmentedValuation_base.__init__(self, parent, v, phi, mu) NonFinalInductiveValuation.__init__(self, parent, phi) @@ -1161,7 +1124,7 @@ def __init__(self, parent, v, phi, mu): def residue_ring(self): r""" Return the residue ring of this valuation, i.e., the elements of - non-negative valuation modulo the elements of positive valuation. + nonnegative valuation modulo the elements of positive valuation. EXAMPLES:: @@ -1178,7 +1141,6 @@ def residue_ring(self): sage: w = v.augmentation(x, 1) sage: w.residue_ring() Univariate Polynomial Ring in x over Finite Field of size 2 (using ...) - """ from sage.categories.fields import Fields if self.domain().base() not in Fields(): @@ -1205,7 +1167,7 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations - ``f`` -- an element in the domain of this valuation - - ``check`` -- whether or not to check whether ``f`` has non-negative + - ``check`` -- whether or not to check whether ``f`` has nonnegative valuation (default: ``True``) - ``degree_bound`` -- an a-priori known bound on the degree of the @@ -1279,7 +1241,6 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations x sage: ww.reduce(f + g) x + 1 - """ f = self.domain().coerce(f) @@ -1349,7 +1310,6 @@ def _residue_field_generator(self): sage: w = v.augmentation(x^2 + x + u, 1/2) sage: w._residue_field_generator() u1 - """ if self.residue_ring() == self._base_valuation.residue_ring(): assert self.psi().degree() == 1 @@ -1426,7 +1386,6 @@ def lift(self, F, report_coefficients=False): (2^-1 + O(2^9))*x^2 + (2^-1 + O(2^9))*x + u*2^-1 + O(2^9) sage: F == ww.reduce(f) True - """ F = self.residue_ring().coerce(F) @@ -1518,7 +1477,6 @@ def lift_to_key(self, F, check=True): 12 sage: ww.is_key(f) True - """ F = self.residue_ring().coerce(F) @@ -1571,7 +1529,6 @@ def _Q(self, e): sage: w._Q(1) 2 - """ tau = self.value_group().index(self._base_valuation.value_group()) v = self._mu * tau @@ -1591,7 +1548,6 @@ def _Q_reciprocal(self, e=1): sage: w._Q_reciprocal() 1/2 - """ if e == 1: return self.equivalence_reciprocal(self._Q(1), check=False) @@ -1621,7 +1577,6 @@ class FiniteAugmentedValuation(AugmentedValuation_base, FiniteInductiveValuation sage: S. = R[] sage: v = GaussValuation(S) sage: w = v.augmentation(x^2 + x + u, 1/2) - """ def __init__(self, parent, v, phi, mu): r""" @@ -1635,7 +1590,6 @@ def __init__(self, parent, v, phi, mu): sage: from sage.rings.valuation.augmented_valuation import FiniteAugmentedValuation sage: isinstance(w, FiniteAugmentedValuation) True - """ AugmentedValuation_base.__init__(self, parent, v, phi, mu) FiniteInductiveValuation.__init__(self, parent, phi) @@ -1657,7 +1611,6 @@ def value_group(self): sage: ww = w.augmentation((x^2 + x + u)^2 + 2, 5/3) sage: ww.value_group() Additive Abelian Group generated by 1/6 - """ return self._base_valuation.value_group() + self._mu @@ -1677,7 +1630,6 @@ def value_semigroup(self): sage: ww = w.augmentation((x^2 + x + u)^2 + 2, 5/3) sage: ww.value_semigroup() Additive Abelian Semigroup generated by 1/2, 5/3 - """ return self._base_valuation.value_semigroup() + self._mu @@ -1716,7 +1668,6 @@ def valuations(self, f, coefficients=None, call_error=False): sage: ww = w.augmentation((x^2 + x + u)^2 + 2, 5/3) sage: list(ww.valuations( ((x^2 + x + u)^2 + 2)^3 )) [+Infinity, +Infinity, +Infinity, 5] - """ f = self.domain().coerce(f) @@ -1802,7 +1753,6 @@ def simplify(self, f, error=None, force=False, effective_degree=None, size_heuri [ Gauss valuation induced by 2-adic valuation, v(x) = 3/2, v(x^2 + 8) = 13/4, v(x^4 + 16*x^2 + 32*x + 64) = 20/3 ], v(y + 4*x + 8) = 31/8 ]] - """ f = self.domain().coerce(f) @@ -1874,7 +1824,6 @@ def lower_bound(self, f): sage: w = v.augmentation(x^2 + x + u, 1/2) sage: w.lower_bound(x^2 + x + u) 0 - """ f = self.domain().coerce(f) @@ -1917,7 +1866,6 @@ def upper_bound(self, f): sage: w = v.augmentation(x^2 + x + u, 1/2) sage: w.upper_bound(x^2 + x + u) 1/2 - """ f = self.domain().coerce(f) @@ -1936,7 +1884,6 @@ class FinalFiniteAugmentedValuation(FiniteAugmentedValuation, FinalAugmentedValu sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: w = v.augmentation(x, 1) - """ def __init__(self, parent, v, phi, mu): r""" @@ -1948,7 +1895,6 @@ def __init__(self, parent, v, phi, mu): sage: from sage.rings.valuation.augmented_valuation import FinalFiniteAugmentedValuation sage: isinstance(w, FinalFiniteAugmentedValuation) True - """ FiniteAugmentedValuation.__init__(self, parent, v, phi, mu) FinalAugmentedValuation.__init__(self, parent, v, phi, mu) @@ -1975,7 +1921,6 @@ def __init__(self, parent, v, phi, mu): sage: from sage.rings.valuation.augmented_valuation import NonFinalFiniteAugmentedValuation sage: isinstance(w, NonFinalFiniteAugmentedValuation) True - """ FiniteAugmentedValuation.__init__(self, parent, v, phi, mu) NonFinalAugmentedValuation.__init__(self, parent, v, phi, mu) @@ -1992,7 +1937,6 @@ class InfiniteAugmentedValuation(FinalAugmentedValuation, InfiniteInductiveValua sage: R. = QQ[] sage: v = GaussValuation(R, QQ.valuation(2)) sage: w = v.augmentation(x, infinity) - """ def __init__(self, parent, v, phi, mu): r""" @@ -2004,7 +1948,6 @@ def __init__(self, parent, v, phi, mu): sage: from sage.rings.valuation.augmented_valuation import InfiniteAugmentedValuation sage: isinstance(w, InfiniteAugmentedValuation) True - """ FinalAugmentedValuation.__init__(self, parent, v, phi, mu) InfiniteInductiveValuation.__init__(self, parent, phi) @@ -2023,7 +1966,6 @@ def value_group(self): sage: w = v.augmentation(x, infinity) sage: w.value_group() Additive Abelian Group generated by 1 - """ return self._base_valuation.value_group() @@ -2041,7 +1983,6 @@ def value_semigroup(self): sage: w = v.augmentation(x, infinity) sage: w.value_semigroup() Additive Abelian Semigroup generated by 1 - """ return self._base_valuation.value_semigroup() @@ -2077,7 +2018,6 @@ def valuations(self, f, coefficients=None, call_error=False): sage: w = v.augmentation(x, infinity) sage: list(w.valuations(x^2 + 1)) [0, +Infinity, +Infinity] - """ f = self.domain().coerce(f) @@ -2121,7 +2061,6 @@ def simplify(self, f, error=None, force=False, effective_degree=None): sage: w = v.augmentation(x^2 + x + u, infinity) sage: w.simplify(x^10/2 + 1, force=True) (u + 1)*2^-1 + O(2^4) - """ f = self.domain().coerce(f) @@ -2149,7 +2088,6 @@ def lower_bound(self, f): sage: w = v.augmentation(x^2 + x + u, infinity) sage: w.lower_bound(x^2 + x + u) +Infinity - """ return self._base_valuation.lower_bound(next(self.coefficients(f))) @@ -2169,6 +2107,5 @@ def upper_bound(self, f): sage: w = v.augmentation(x^2 + x + u, infinity) sage: w.upper_bound(x^2 + x + u) +Infinity - """ return self._base_valuation.upper_bound(next(self.coefficients(f))) diff --git a/src/sage/rings/valuation/developing_valuation.py b/src/sage/rings/valuation/developing_valuation.py index f99c2b5161c..8b77224f591 100644 --- a/src/sage/rings/valuation/developing_valuation.py +++ b/src/sage/rings/valuation/developing_valuation.py @@ -67,7 +67,6 @@ class DevelopingValuation(DiscretePseudoValuation): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def __init__(self, parent, phi): r""" @@ -78,13 +77,12 @@ def __init__(self, parent, phi): sage: from sage.rings.valuation.developing_valuation import DevelopingValuation sage: isinstance(v, DevelopingValuation) True - """ DiscretePseudoValuation.__init__(self, parent) domain = parent.domain() - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if not is_PolynomialRing(domain) or not domain.ngens() == 1: + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if not isinstance(domain, PolynomialRing_general) or not domain.ngens() == 1: raise TypeError("domain must be a univariate polynomial ring but %r is not" % (domain,)) phi = domain.coerce(phi) @@ -104,7 +102,6 @@ def phi(self): sage: v = GaussValuation(S) # needs sage.libs.ntl sage: v.phi() # needs sage.libs.ntl (1 + O(2^5))*x - """ return self._phi @@ -118,7 +115,7 @@ def effective_degree(self, f, valuations=None): INPUT: - - ``f`` -- a non-zero polynomial in the domain of this valuation + - ``f`` -- a nonzero polynomial in the domain of this valuation EXAMPLES:: @@ -130,12 +127,11 @@ def effective_degree(self, f, valuations=None): 1 sage: v.effective_degree(2*x + 1) 0 - """ f = self.domain().coerce(f) if f.is_zero(): - raise ValueError("the effective degree is only defined for non-zero polynomials") + raise ValueError("the effective degree is only defined for nonzero polynomials") if valuations is None: valuations = list(self.valuations(f)) @@ -161,7 +157,6 @@ def _pow(self, f, e, error, effective_degree): sage: v = GaussValuation(S) sage: v._pow(2*x + 1, 10, effective_degree=0, error=5) 1 + O(2^5) - """ if e == 0: return self.domain().one() @@ -199,7 +194,6 @@ def coefficients(self, f): sage: v = v.augmentation( x^2 + x + 1, 1) sage: list(v.coefficients(f)) [(1 + O(2^5))*x + 2 + O(2^5), 1 + O(2^5)] - """ domain = self.domain() f = domain.coerce(f) @@ -252,7 +246,6 @@ def newton_polygon(self, f, valuations=None): Finite Newton polygon with 2 vertices: (0, 0), (1, 1) sage: v.newton_polygon( f * v.phi()^3 ) # needs sage.geometry.polyhedron Finite Newton polygon with 2 vertices: (3, 3), (4, 4) - """ f = self.domain().coerce(f) @@ -287,7 +280,6 @@ def _call_(self, f): 3 sage: v(S.zero()) +Infinity - """ f = self.domain().coerce(f) @@ -325,7 +317,6 @@ def valuations(self, f): sage: f = x^2 + 2*x + 16 sage: list(v.valuations(f)) [4, 1, 0] - """ def _test_effective_degree(self, **options): diff --git a/src/sage/rings/valuation/gauss_valuation.py b/src/sage/rings/valuation/gauss_valuation.py index 0443ba9c670..ca67b25274e 100644 --- a/src/sage/rings/valuation/gauss_valuation.py +++ b/src/sage/rings/valuation/gauss_valuation.py @@ -87,10 +87,9 @@ def create_key(self, domain, v=None): Traceback (most recent call last): ... ValueError: the domain of v must be the base ring of domain but 2-adic valuation is not defined over Integer Ring but over Rational Field - """ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if not is_PolynomialRing(domain): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if not isinstance(domain, PolynomialRing_general): raise TypeError("GaussValuations can only be created over polynomial rings but %r is not a polynomial ring" % (domain,)) if not domain.ngens() == 1: raise NotImplementedError("domain must be univariate but %r is not univariate" % (domain,)) @@ -115,7 +114,6 @@ def create_object(self, version, key, **extra_args): sage: R. = QQ[] sage: GaussValuation.create_object(0, (R, v)) Gauss valuation induced by 2-adic valuation - """ domain, v = key from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace @@ -151,7 +149,6 @@ class GaussValuation_generic(NonFinalInductiveValuation): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def __init__(self, parent, v): """ @@ -162,7 +159,6 @@ def __init__(self, parent, v): sage: v = GaussValuation(S, QQ.valuation(5)) sage: isinstance(v, GaussValuation_generic) True - """ NonFinalInductiveValuation.__init__(self, parent, parent.domain().gen()) @@ -178,7 +174,6 @@ def value_group(self): sage: v = GaussValuation(S, QQ.valuation(5)) sage: v.value_group() Additive Abelian Group generated by 1 - """ return self._base_valuation.value_group() @@ -192,7 +187,6 @@ def value_semigroup(self): sage: v = GaussValuation(S, QQ.valuation(5)) sage: v.value_semigroup() Additive Abelian Semigroup generated by -1, 1 - """ return self._base_valuation.value_semigroup() @@ -223,7 +217,6 @@ def uniformizer(self): 5 sage: v.uniformizer().parent() is S True - """ return self.domain()(self._base_valuation.uniformizer()) @@ -244,9 +237,8 @@ def valuations(self, f, coefficients=None, call_error=False): assuming that the result is only used to compute the valuation of ``f`` (default: ``False``) - OUTPUT: - - A list, each entry a rational numbers or infinity, the valuations of `f_0, f_1\phi, \dots` + OUTPUT: list, each entry a rational numbers or infinity, the valuations + of `f_0, f_1\phi, \dots` EXAMPLES:: @@ -297,7 +289,6 @@ def residue_ring(self): sage: v = GaussValuation(S) # needs sage.libs.ntl sage: v.residue_ring() # needs sage.libs.ntl Univariate Polynomial Ring in x over Finite Field of size 2 (using ...) - """ return self.domain().change_ring(self._base_valuation.residue_ring()) @@ -309,7 +300,7 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations - ``f`` -- an integral element of the domain of this valuation - - ``check`` -- whether or not to check whether ``f`` has non-negative + - ``check`` -- whether or not to check whether ``f`` has nonnegative valuation (default: ``True``) - ``degree_bound`` -- an a-priori known bound on the degree of the @@ -321,9 +312,7 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations - ``valuations`` -- the valuations of ``coefficients`` or ``None`` (default: ``None``); ignored - OUTPUT: - - A polynomial in the :meth:`residue_ring` of this valuation. + OUTPUT: a polynomial in the :meth:`residue_ring` of this valuation EXAMPLES:: @@ -347,7 +336,6 @@ def reduce(self, f, check=True, degree_bound=None, coefficients=None, valuations .. SEEALSO:: :meth:`lift` - """ f = self.domain().coerce(f) @@ -421,7 +409,6 @@ def lift_to_key(self, F): sage: y = v.residue_ring().gen() sage: f = v.lift_to_key(y^2 + y + 1); f x^2 + x + 1 - """ F = self.residue_ring().coerce(F) @@ -443,7 +430,7 @@ def equivalence_unit(self, s, reciprocal=False): - ``s`` -- an element of the :meth:`value_group` - - ``reciprocal`` -- a boolean (default: ``False``); whether or not to + - ``reciprocal`` -- boolean (default: ``False``); whether or not to return the equivalence unit as the :meth:`~sage.rings.valuation.inductive_valuation.InductiveValuation.equivalence_reciprocal` of the equivalence unit of valuation ``-s`` @@ -456,7 +443,6 @@ def equivalence_unit(self, s, reciprocal=False): 3^2 + O(3^7) sage: v.equivalence_unit(-2) 3^-2 + O(3^3) - """ if reciprocal: return self.equivalence_reciprocal(self.equivalence_unit(-s)) @@ -474,7 +460,6 @@ def element_with_valuation(self, s): sage: v = GaussValuation(R, QQ.valuation(2)) sage: v.element_with_valuation(-2) 1/4 - """ return self.equivalence_unit(s) @@ -491,7 +476,6 @@ def E(self): sage: v = GaussValuation(S) sage: v.E() 1 - """ from sage.rings.integer_ring import ZZ return ZZ.one() @@ -509,7 +493,6 @@ def F(self): sage: v = GaussValuation(S) sage: v.F() 1 - """ from sage.rings.integer_ring import ZZ return ZZ.one() @@ -525,10 +508,9 @@ def change_domain(self, ring): sage: w = GaussValuation(R, v) sage: w.change_domain(QQ['x']) Gauss valuation induced by 2-adic valuation - """ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring) and ring.ngens() == 1: + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general) and ring.ngens() == 1: base_valuation = self._base_valuation.change_domain(ring.base_ring()) return GaussValuation(self.domain().change_ring(ring.base_ring()), base_valuation) return super().change_domain(ring) @@ -544,10 +526,9 @@ def extensions(self, ring): sage: w = GaussValuation(R, v) sage: w.extensions(GaussianIntegers()['x']) # needs sage.rings.number_field [Gauss valuation induced by 2-adic valuation] - """ - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring) and ring.ngens() == 1: + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general) and ring.ngens() == 1: if self.domain().is_subring(ring): return [GaussValuation(ring, w) for w in self._base_valuation.extensions(ring.base_ring())] return super().extensions(ring) @@ -563,12 +544,11 @@ def restriction(self, ring): sage: w = GaussValuation(R, v) sage: w.restriction(ZZ) 2-adic valuation - """ if ring.is_subring(self.domain().base_ring()): return self._base_valuation.restriction(ring) - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring) and ring.ngens() == 1: + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general) and ring.ngens() == 1: if ring.base().is_subring(self.domain().base()): return GaussValuation(ring, self._base_valuation.restriction(ring.base())) return super().restriction(ring) @@ -585,7 +565,6 @@ def is_gauss_valuation(self): sage: v = GaussValuation(S) sage: v.is_gauss_valuation() True - """ return True @@ -602,7 +581,6 @@ def augmentation_chain(self): sage: v = GaussValuation(S) sage: v.augmentation_chain() [Gauss valuation induced by 2-adic valuation] - """ return [self] @@ -617,7 +595,6 @@ def is_trivial(self): sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v.is_trivial() True - """ return self._base_valuation.is_trivial() @@ -637,7 +614,6 @@ def monic_integral_model(self, G): Ring endomorphism of Univariate Polynomial Ring in x over 2-adic Field with capped relative precision 5 Defn: (1 + O(2^5))*x |--> (2 + O(2^6))*x, (1 + O(2^5))*x^2 + (1 + 2^2 + 2^3 + O(2^5))*x + 1 + 2^2 + 2^3 + O(2^5)) - """ if not G.is_monic(): # this might fail if the base ring is not a field @@ -672,7 +648,6 @@ def _ge_(self, other): False sage: w >= v False - """ if isinstance(other, GaussValuation_generic): return self._base_valuation >= other._base_valuation @@ -693,7 +668,6 @@ def scale(self, scalar): sage: v = GaussValuation(R, QQ.valuation(2)) sage: 3*v # indirect doctest Gauss valuation induced by 3 * 2-adic valuation - """ from sage.rings.rational_field import QQ if scalar in QQ and scalar > 0 and scalar != 1: @@ -725,7 +699,6 @@ def _relative_size(self, f): sage: v._relative_size(1024*x + 1) 1 - """ return self._base_valuation._relative_size(f[0]) @@ -767,7 +740,6 @@ def simplify(self, f, error=None, force=False, size_heuristic_bound=32, effectiv sage: f = x^10/2 + 1 sage: v.simplify(f) (2^-1 + O(2^4))*x^10 + 1 + O(2^5) - """ f = self.domain().coerce(f) @@ -801,7 +773,6 @@ def lower_bound(self, f): 1 sage: v(1024*x + 2) 1 - """ from sage.rings.infinity import infinity coefficients = f.coefficients(sparse=True) diff --git a/src/sage/rings/valuation/inductive_valuation.py b/src/sage/rings/valuation/inductive_valuation.py index 40f405e1b21..9646cf5e429 100644 --- a/src/sage/rings/valuation/inductive_valuation.py +++ b/src/sage/rings/valuation/inductive_valuation.py @@ -55,7 +55,6 @@ class InductiveValuation(DevelopingValuation): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def is_equivalence_unit(self, f, valuations=None): r""" @@ -79,7 +78,6 @@ def is_equivalence_unit(self, f, valuations=None): False sage: v.is_equivalence_unit(2*x + 1) True - """ f = self.domain().coerce(f) @@ -167,7 +165,6 @@ def equivalence_reciprocal(self, f, coefficients=None, valuations=None, check=Tr sage: f_ = w.equivalence_reciprocal(f) sage: w.reduce(f*f_) 1 - """ f = self.domain().coerce(f) @@ -200,7 +197,7 @@ def equivalence_reciprocal(self, f, coefficients=None, valuations=None, check=Tr h = self.simplify(h, -vf) - # it might be the case that f*h has non-zero valuation because h has + # it might be the case that f*h has nonzero valuation because h has # insufficient precision, so we must not assert that here but only # until we lifted to higher precision @@ -223,7 +220,6 @@ def mu(self): sage: v = GaussValuation(R, QQ.valuation(2)) sage: v.mu() 0 - """ return self(self.phi()) @@ -236,7 +232,7 @@ def equivalence_unit(self, s, reciprocal=False): - ``s`` -- an element of the :meth:`~sage.rings.valuation.valuation_space.DiscretePseudoValuationSpace.ElementMethods.value_group` - - ``reciprocal`` -- a boolean (default: ``False``); whether or not to + - ``reciprocal`` -- boolean (default: ``False``); whether or not to return the equivalence unit as the :meth:`equivalence_reciprocal` of the equivalence unit of valuation ``-s``. @@ -263,7 +259,6 @@ def equivalence_unit(self, s, reciprocal=False): ... ValueError: s must be in the value semigroup of this valuation but -1 is not in Additive Abelian Semigroup generated by 1 - """ @abstract_method @@ -280,7 +275,6 @@ def augmentation_chain(self): sage: v = GaussValuation(S) sage: v.augmentation_chain() [Gauss valuation induced by 2-adic valuation] - """ @abstract_method @@ -296,7 +290,6 @@ def is_gauss_valuation(self): sage: v = GaussValuation(S) sage: v.is_gauss_valuation() True - """ @abstract_method @@ -313,7 +306,6 @@ def E(self): sage: v = GaussValuation(S) sage: v.E() 1 - """ @abstract_method @@ -329,7 +321,6 @@ def F(self): sage: v = GaussValuation(S) sage: v.F() 1 - """ @abstract_method @@ -349,7 +340,6 @@ def monic_integral_model(self, G): Ring endomorphism of Univariate Polynomial Ring in x over Rational Field Defn: x |--> 2*x, x^2 + 1/5*x + 1/5) - """ @abstract_method @@ -374,7 +364,6 @@ def element_with_valuation(self, s): ... ValueError: s must be in the value semigroup of this valuation but -2 is not in Additive Abelian Semigroup generated by 1 - """ def _test_element_with_valuation_inductive_valuation(self, **options): @@ -386,7 +375,6 @@ def _test_element_with_valuation_inductive_valuation(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, QQ.valuation(2)) sage: v._test_element_with_valuation_inductive_valuation() - """ tester = self._tester(**options) chain = self.augmentation_chain() @@ -419,7 +407,6 @@ def _test_EF(self, **options): sage: S. = R[] sage: v = GaussValuation(S) sage: v._test_EF() - """ tester = self._tester(**options) chain = self.augmentation_chain() @@ -442,7 +429,6 @@ def _test_augmentation_chain(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_augmentation_chain() - """ tester = self._tester(**options) chain = self.augmentation_chain() @@ -460,7 +446,6 @@ def _test_equivalence_unit(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_equivalence_unit() - """ tester = self._tester(**options) @@ -492,7 +477,6 @@ def _test_is_equivalence_unit(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_is_equivalence_unit() - """ tester = self._tester(**options) tester.assertFalse(self.is_equivalence_unit(self.phi())) @@ -506,7 +490,6 @@ def _test_equivalence_reciprocal(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_equivalence_reciprocal() - """ tester = self._tester(**options) S = tester.some_elements(self.domain().some_elements()) @@ -536,7 +519,6 @@ def _test_inductive_valuation_inheritance(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_inductive_valuation_inheritance() - """ tester = self._tester(**options) tester.assertNotEqual(isinstance(self, InfiniteInductiveValuation), @@ -555,7 +537,6 @@ class FiniteInductiveValuation(InductiveValuation, DiscreteValuation): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) - """ def __init__(self, parent, phi): r""" @@ -566,7 +547,6 @@ def __init__(self, parent, phi): sage: from sage.rings.valuation.inductive_valuation import FiniteInductiveValuation sage: isinstance(v, FiniteInductiveValuation) True - """ InductiveValuation.__init__(self, parent, phi) DiscreteValuation.__init__(self, parent) @@ -582,7 +562,6 @@ def extensions(self, other): sage: K. = FunctionField(QQ) sage: v.extensions(K) [Trivial valuation on Rational Field] - """ from sage.categories.function_fields import FunctionFields if other in FunctionFields() and other.ngens() == 1: @@ -605,7 +584,6 @@ class NonFinalInductiveValuation(FiniteInductiveValuation, DiscreteValuation): sage: S. = R[] sage: v = GaussValuation(S) sage: v = v.augmentation(x^2 + x + u, 1) - """ def __init__(self, parent, phi): r""" @@ -619,7 +597,6 @@ def __init__(self, parent, phi): sage: from sage.rings.valuation.inductive_valuation import NonFinalInductiveValuation sage: isinstance(v, NonFinalInductiveValuation) True - """ FiniteInductiveValuation.__init__(self, parent, phi) DiscreteValuation.__init__(self, parent) @@ -638,7 +615,7 @@ def augmentation(self, phi, mu, check=True): - ``mu`` -- a rational number or infinity, the valuation of ``phi`` in the extended valuation - - ``check`` -- a boolean (default: ``True``), whether or not to check + - ``check`` -- boolean (default: ``True``); whether or not to check the correctness of the parameters EXAMPLES:: @@ -677,7 +654,6 @@ def augmentation(self, phi, mu, check=True): .. SEEALSO:: :mod:`~sage.rings.valuation.augmented_valuation` - """ from .augmented_valuation import AugmentedValuation return AugmentedValuation(self, phi, mu, check) @@ -695,7 +671,7 @@ def mac_lane_step(self, G, principal_part_bound=None, assume_squarefree=False, a - ``G`` -- a squarefree monic non-constant integral polynomial ``G`` which is not an :meth:`equivalence unit ` - - ``principal_part_bound`` -- an integer or ``None`` (default: + - ``principal_part_bound`` -- integer or ``None`` (default: ``None``), a bound on the length of the principal part, i.e., the section of negative slope, of the Newton polygon of ``G`` @@ -786,7 +762,6 @@ def mac_lane_step(self, G, principal_part_bound=None, assume_squarefree=False, a sage: f = x^4 - 30*x^2 - 75 sage: v.mac_lane_step(f) # needs sage.geometry.polyhedron [[ Gauss valuation induced by 2-adic valuation, v(x + 1) = 3/4 ]] - """ G = self.domain().coerce(G) @@ -823,7 +798,7 @@ def mac_lane_step(self, G, principal_part_bound=None, assume_squarefree=False, a raise ValueError("G must be squarefree") from sage.rings.infinity import infinity - assert self(G) is not infinity # this is a valuation and G is non-zero + assert self(G) is not infinity # this is a valuation and G is nonzero ret = [] @@ -944,7 +919,7 @@ def is_key(self, phi, explain=False, assume_equivalence_irreducible=False): - ``phi`` -- a polynomial in the domain of this valuation - - ``explain`` -- a boolean (default: ``False``), if ``True``, return a + - ``explain`` -- boolean (default: ``False``); if ``True``, return a string explaining why ``phi`` is not a key polynomial EXAMPLES:: @@ -962,7 +937,6 @@ def is_key(self, phi, explain=False, assume_equivalence_irreducible=False): sage: w = v.augmentation(x, 1) sage: w.is_key(x + 1, explain = True) (False, 'phi must be minimal') - """ phi = self.domain().coerce(phi) @@ -986,7 +960,7 @@ def is_minimal(self, f, assume_equivalence_irreducible=False): valuation. A polynomial `f` is minimal with respect to `v` if it is not a constant - and any non-zero polynomial `h` which is `v`-divisible by `f` has at + and any nonzero polynomial `h` which is `v`-divisible by `f` has at least the degree of `f`. A polynomial `h` is `v`-divisible by `f` if there is a polynomial `c` @@ -1027,7 +1001,6 @@ def is_minimal(self, f, assume_equivalence_irreducible=False): True sage: v2.is_minimal(x^4 + 4) # needs sage.libs.ntl False - """ f = self.domain().coerce(f) @@ -1092,7 +1065,6 @@ def _equivalence_reduction(self, f, coefficients=None, valuations=None, degree_b sage: v = GaussValuation(R, QQ.valuation(2)) sage: v._equivalence_reduction(2*x^6 + 4*x^5 + 2*x^4 + 8) (1, 4, x^2 + 1) - """ f = self.domain().coerce(f) @@ -1159,7 +1131,6 @@ def is_equivalence_irreducible(self, f, coefficients=None, valuations=None): False sage: v.is_equivalence_irreducible(x^2 + 2) False - """ f = self.domain().coerce(f) @@ -1188,7 +1159,7 @@ def equivalence_decomposition(self, f, assume_not_equivalence_unit=False, coeffi INPUT: - - ``f`` -- a non-zero polynomial in the domain of this valuation + - ``f`` -- a nonzero polynomial in the domain of this valuation - ``assume_not_equivalence_unit`` -- whether or not to assume that ``f`` is not an :meth:`equivalence unit ` @@ -1299,7 +1270,6 @@ def equivalence_decomposition(self, f, assume_not_equivalence_unit=False, coeffi x^4 - 343/2*x^2 + 1294139 sage: v2.is_equivalent(F.prod(), f) True - """ f = self.domain().coerce(f) @@ -1369,11 +1339,9 @@ def minimal_representative(self, f): INPUT: - - ``f`` -- a non-zero polynomial which is not an equivalence unit - - OUTPUT: + - ``f`` -- a nonzero polynomial which is not an equivalence unit - A factorization which has `e` as its unit and `a` as its unique factor. + OUTPUT: a factorization which has `e` as its unit and `a` as its unique factor ALGORITHM: @@ -1403,7 +1371,6 @@ def minimal_representative(self, f): True sage: v.is_equivalent(F.prod(), f) True - """ f = self.domain().coerce(f) @@ -1473,7 +1440,6 @@ def lift_to_key(self, F): sage: u0 = v.residue_ring().base_ring().gen() sage: f = v.lift_to_key(y^2 + y + u0); f (1 + O(2^10))*x^2 + (1 + O(2^10))*x + u + O(2^10) - """ def _eliminate_denominators(self, f): @@ -1484,7 +1450,7 @@ def _eliminate_denominators(self, f): INPUT: - ``f`` -- a polynomial with coefficients in the fraction field of the - base ring of the domain of this valuation. + base ring of the domain of this valuation EXAMPLES:: @@ -1509,7 +1475,6 @@ def _eliminate_denominators(self, f): sage: w._eliminate_denominators(x^3/2 + x) x - """ if f in self.domain(): return self.domain()(f) @@ -1550,7 +1515,6 @@ def _test_eliminate_denominators(self, **options): sage: R. = ZZ[] sage: v = GaussValuation(R, ZZ.valuation(2)) sage: v._test_eliminate_denominators() - """ tester = self._tester(**options) @@ -1577,7 +1541,6 @@ def _test_lift_to_key(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_lift_to_key() # needs sage.rings.number_field - """ tester = self._tester(**options) @@ -1625,7 +1588,6 @@ def _test_is_equivalence_irreducible(self, **options): sage: R. = QQ[] sage: v = GaussValuation(R, valuations.TrivialValuation(QQ)) sage: v._test_is_equivalence_irreducible() - """ tester = self._tester(**options) S = tester.some_elements(self.domain().some_elements()) @@ -1668,7 +1630,6 @@ class InfiniteInductiveValuation(FinalInductiveValuation, InfiniteDiscretePseudo sage: R. = QQ[] sage: v = GaussValuation(R, QQ.valuation(2)) sage: w = v.augmentation(x^2 + x + 1, infinity) - """ def __init__(self, parent, base_valuation): r""" @@ -1680,7 +1641,6 @@ def __init__(self, parent, base_valuation): sage: from sage.rings.valuation.inductive_valuation import InfiniteInductiveValuation sage: isinstance(w, InfiniteInductiveValuation) True - """ FinalInductiveValuation.__init__(self, parent, base_valuation) InfiniteDiscretePseudoValuation.__init__(self, parent) @@ -1698,10 +1658,9 @@ def change_domain(self, ring): sage: w = v.augmentation(x^2 + x + 1, infinity) sage: w.change_domain(R.quo(x^2 + x + 1)) 2-adic valuation - """ - from sage.rings.polynomial.polynomial_quotient_ring import is_PolynomialQuotientRing - if is_PolynomialQuotientRing(ring) and ring.base() is self.domain() and ring.modulus() == self.phi(): + from sage.rings.polynomial.polynomial_quotient_ring import PolynomialQuotientRing_generic + if isinstance(ring, PolynomialQuotientRing_generic) and ring.base() is self.domain() and ring.modulus() == self.phi(): return self.restriction(self.domain().base())._extensions_to_quotient(ring, approximants=[self])[0] return super().change_domain(ring) @@ -1722,6 +1681,5 @@ def _lift_to_maximal_precision(c): sage: x = 1 sage: _lift_to_maximal_precision(x) 1 - """ return c if c.parent().is_exact() else c.lift_to_precision() diff --git a/src/sage/rings/valuation/limit_valuation.py b/src/sage/rings/valuation/limit_valuation.py index 11b41cf9fed..86a64d23f99 100644 --- a/src/sage/rings/valuation/limit_valuation.py +++ b/src/sage/rings/valuation/limit_valuation.py @@ -97,7 +97,7 @@ class LimitValuationFactory(UniqueFactory): uniquely augmented (possibly only in the limit) to a pseudo-valuation that sends ``G`` to infinity. - - ``G`` -- a squarefree polynomial in the domain of ``base_valuation``. + - ``G`` -- a squarefree polynomial in the domain of ``base_valuation`` EXAMPLES:: @@ -106,7 +106,6 @@ class LimitValuationFactory(UniqueFactory): sage: w = valuations.LimitValuation(v, x) sage: w(x) +Infinity - """ def create_key(self, base_valuation, G): r""" @@ -128,7 +127,6 @@ def create_key(self, base_valuation, G): The point here is that this is not meant to be invoked from user code. But mostly from other factories which have made sure that the parameters are normalized already. - """ if not base_valuation.restriction(G.parent().base_ring()).is_discrete_valuation(): raise ValueError("base_valuation must be discrete on the coefficient ring.") @@ -143,7 +141,6 @@ def create_object(self, version, key): sage: R. = QQ[] sage: v = GaussValuation(R, QQ.valuation(2)) sage: w = valuations.LimitValuation(v, x^2 + 1) # indirect doctest - """ base_valuation, G = key from .valuation_space import DiscretePseudoValuationSpace @@ -184,7 +181,6 @@ class LimitValuation_generic(DiscretePseudoValuation): sage: isinstance(w._base_valuation, LimitValuation_generic) # needs sage.rings.function_field True sage: TestSuite(w._base_valuation).run() # long time # needs sage.rings.function_field - """ def __init__(self, parent, approximation): r""" @@ -197,7 +193,6 @@ def __init__(self, parent, approximation): sage: from sage.rings.valuation.limit_valuation import LimitValuation_generic sage: isinstance(v._base_valuation, LimitValuation_generic) True - """ DiscretePseudoValuation.__init__(self, parent) @@ -210,10 +205,10 @@ def reduce(self, f, check=True): INPUT: - - ``f`` -- an element in the domain of this valuation of non-negative + - ``f`` -- an element in the domain of this valuation of nonnegative valuation - - ``check`` -- whether or not to check that ``f`` has non-negative + - ``check`` -- whether or not to check that ``f`` has nonnegative valuation (default: ``True``) EXAMPLES:: @@ -226,7 +221,6 @@ def reduce(self, f, check=True): sage: w = v.extension(L) sage: w.reduce(y) # indirect doctest u1 - """ f = self.domain().coerce(f) self._improve_approximation_for_reduce(f) @@ -247,7 +241,6 @@ def _call_(self, f): sage: w = v.extension(L) sage: w(y) # indirect doctest 1/2 - """ self._improve_approximation_for_call(f) return self._approximation(f) @@ -297,7 +290,6 @@ def _improve_approximation_for_reduce(self, f): sage: u._approximation [ Gauss valuation induced by (x - 1341)-adic valuation, v(y + 1/64*x^2 - 1349/32*x + 1819609/64) = 3 ] - """ @abstract_method @@ -337,7 +329,6 @@ def _improve_approximation_for_call(self, f): 1/2 sage: u._approximation [ Gauss valuation induced by (x - 23)-adic valuation, v(y) = 1/2, v(y^2 - x + 23) = +Infinity ] - """ def _repr_(self): @@ -354,7 +345,6 @@ def _repr_(self): sage: w = v.extension(L) sage: w._base_valuation # indirect doctest [ Gauss valuation induced by 2-adic valuation, v(t + 1) = 1/2 , … ] - """ from sage.rings.infinity import infinity from .augmented_valuation import AugmentedValuation_base @@ -384,7 +374,6 @@ class MacLaneLimitValuation(LimitValuation_generic, InfiniteDiscretePseudoValuat sage: v = K.valuation(2) sage: u = v._base_valuation; u [ Gauss valuation induced by 2-adic valuation, v(x + 1) = 1/2 , … ] - """ def __init__(self, parent, approximation, G): r""" @@ -398,7 +387,6 @@ def __init__(self, parent, approximation, G): sage: from sage.rings.valuation.limit_valuation import MacLaneLimitValuation sage: isinstance(u, MacLaneLimitValuation) True - """ LimitValuation_generic.__init__(self, parent, approximation) InfiniteDiscretePseudoValuation.__init__(self, parent) @@ -418,12 +406,11 @@ def extensions(self, ring): sage: u = v._base_valuation sage: u.extensions(QQ['x']) [[ Gauss valuation induced by 2-adic valuation, v(x + 1) = 1/2 , … ]] - """ if self.domain() is ring: return [self] - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ring) and self.domain().base_ring().is_subring(ring.base_ring()): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ring, PolynomialRing_general) and self.domain().base_ring().is_subring(ring.base_ring()): if self.domain().base_ring().fraction_field() is ring.base_ring(): return [LimitValuation(self._initial_approximation.change_domain(ring), self._G.change_ring(ring.base_ring()))] @@ -451,7 +438,6 @@ def lift(self, F): u1 sage: w.lift(s) # indirect doctest y - """ F = self.residue_ring().coerce(F) return self._initial_approximation.lift(F) @@ -470,7 +456,6 @@ def uniformizer(self): sage: w = v.extension(L) sage: w.uniformizer() # indirect doctest y - """ return self._initial_approximation.uniformizer() @@ -495,7 +480,6 @@ def _call_(self, f): sage: w = valuations.LimitValuation(V[2], f) sage: w((x^2 + 7) * (x + 3)) +Infinity - """ self._improve_approximation_for_call(f) if self._G.divides(f): @@ -528,7 +512,6 @@ def _improve_approximation(self): sage: u._improve_approximation() # needs sage.rings.number_field sage: u._approximation # needs sage.rings.number_field [ Gauss valuation induced by 2-adic valuation, v(t + 1) = 1/2, v(t^2 + 1) = +Infinity ] - """ from sage.rings.infinity import infinity if self._approximation(self._G) is infinity: @@ -575,7 +558,7 @@ def _improve_approximation_for_call(self, f): Write `L=K[x]/(G)` and consider `g` a representative of the class of ``f`` in `K[x]` (of minimal degree.) Write `v` for - ``self._approximation` and `\phi` for the last key polynomial of + ``self._approximation`` and `\phi` for the last key polynomial of `v`. With repeated quotient and remainder `g` has a unique expansion as `g=\sum a_i\phi^i`. Suppose that `g` is an equivalence-unit with respect to ``self._approximation``, i.e., @@ -595,7 +578,6 @@ def _improve_approximation_for_call(self, f): finitely many steps. From this we can deduce the valuation of `s` (and in fact replace `G` with the factor with infinite valuation for all future computations.) - """ from sage.rings.infinity import infinity if self._approximation(self._approximation.phi()) is infinity: @@ -653,7 +635,6 @@ def _improve_approximation_for_reduce(self, f): The reduction produced by the approximation is correct for an equivalence-unit, see :meth:`_improve_approximation_for_call`. - """ if self._approximation(f) > 0: return @@ -673,7 +654,6 @@ def residue_ring(self): sage: w = v.extension(L) sage: w.residue_ring() Finite Field of size 2 - """ R = self._initial_approximation.residue_ring() from sage.categories.fields import Fields @@ -681,8 +661,8 @@ def residue_ring(self): # the approximation ends in v(phi)=infty return R else: - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - assert (is_PolynomialRing(R)) + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + assert (isinstance(R, PolynomialRing_general)) return R.base_ring() def _ge_(self, other): @@ -703,7 +683,6 @@ def _ge_(self, other): True sage: valuations.LimitValuation(V[2], F) >= valuations.LimitValuation(V[2], G) True - """ if other.is_trivial(): return other.is_discrete_valuation() @@ -744,7 +723,6 @@ def restriction(self, ring): sage: w = v.extension(L) sage: w._base_valuation.restriction(K) 2-adic valuation - """ if ring.is_subring(self.domain().base()): return self._initial_approximation.restriction(ring) @@ -790,7 +768,6 @@ def _weakly_separating_element(self, other): has a huge impact on the runtime:: sage: u.separating_element([ww,w,v,uu]) # not tested, takes forever - """ from .scaled_valuation import ScaledValuation_generic v = self.restriction(self.domain().base()) @@ -825,7 +802,6 @@ def value_semigroup(self): sage: u,uu = v.extensions(L) sage: u.value_semigroup() Additive Abelian Semigroup generated by -1, 1 - """ return self._initial_approximation.value_semigroup() @@ -843,7 +819,6 @@ def element_with_valuation(self, s): sage: u = v.extension(L) sage: u.element_with_valuation(1/2) t + 1 - """ return self._initial_approximation.element_with_valuation(s) @@ -869,7 +844,6 @@ def _relative_size(self, f): sage: u = v.extension(L) sage: u._relative_size(1024*t + 1024) 6 - """ return self._initial_approximation._relative_size(f) @@ -891,7 +865,6 @@ def simplify(self, f, error=None, force=False): sage: u = v.extension(L) sage: u.simplify(t + 1024, force=True) t - """ f = self.domain().coerce(f) @@ -923,7 +896,6 @@ def lower_bound(self, f): 10 sage: u(1024*t + 1024) 21/2 - """ f = self.domain().coerce(f) return self._approximation.lower_bound(f) @@ -947,7 +919,6 @@ def upper_bound(self, f): 21/2 sage: u(1024*t + 1024) 21/2 - """ f = self.domain().coerce(f) self._improve_approximation_for_call(f) diff --git a/src/sage/rings/valuation/mapped_valuation.py b/src/sage/rings/valuation/mapped_valuation.py index a4ccf3feec0..0c9dde8d423 100644 --- a/src/sage/rings/valuation/mapped_valuation.py +++ b/src/sage/rings/valuation/mapped_valuation.py @@ -52,7 +52,6 @@ class MappedValuation_base(DiscretePseudoValuation): TESTS:: sage: TestSuite(w).run() # long time # needs sage.rings.function_field - """ def __init__(self, parent, base_valuation): r""" @@ -76,7 +75,6 @@ def __init__(self, parent, base_valuation): sage: from sage.rings.valuation.mapped_valuation import MappedValuation_base sage: isinstance(w, MappedValuation_base) True - """ DiscretePseudoValuation.__init__(self, parent) @@ -97,7 +95,6 @@ def _repr_(self): sage: v = valuations.pAdicValuation(QQ, 2) sage: v.extension(L) # indirect doctest # needs sage.rings.number_field 2-adic valuation - """ def residue_ring(self): @@ -112,7 +109,6 @@ def residue_ring(self): sage: v = valuations.pAdicValuation(QQ, 2) sage: v.extension(L).residue_ring() # needs sage.rings.number_field Finite Field of size 2 - """ return self._base_valuation.residue_ring() @@ -128,7 +124,6 @@ def uniformizer(self): sage: v = valuations.pAdicValuation(QQ, 2) sage: v.extension(L).uniformizer() # needs sage.rings.number_field t + 1 - """ return self._from_base_domain(self._base_valuation.uniformizer()) @@ -146,7 +141,6 @@ def _to_base_domain(self, f): sage: w = v.extensions(L)[0] sage: w._to_base_domain(y).parent() Univariate Polynomial Ring in y over Rational function field in x over Rational Field - """ return self._base_valuation.domain().coerce(f) @@ -164,7 +158,6 @@ def _from_base_domain(self, f): sage: w = v.extension(L) sage: w._from_base_domain(w._base_valuation.domain().gen()).parent() Function field in y defined by y^2 - x - """ return self.domain().coerce(f) @@ -182,7 +175,6 @@ def _call_(self, f): sage: w = v.extension(L) sage: w(y) # indirect doctest 1/2 - """ return self._base_valuation(self._to_base_domain(f)) @@ -200,7 +192,6 @@ def reduce(self, f): sage: w = v.extension(L) sage: w.reduce(y) u1 - """ return self._from_base_residue_ring(self._base_valuation.reduce(self._to_base_domain(f))) @@ -219,7 +210,6 @@ def lift(self, F): sage: w = v.extension(L) sage: w.lift(w.residue_field().gen()) y - """ F = self.residue_ring().coerce(F) F = self._to_base_residue_ring(F) @@ -257,7 +247,6 @@ def simplify(self, x, error=None, force=False): sage: w.simplify(y + x^32, force=True) # needs sage.rings.function_field y - """ return self._from_base_domain(self._base_valuation.simplify(self._to_base_domain(x), error=error, force=force)) @@ -287,7 +276,6 @@ def _relative_size(self, x): sage: w._relative_size(y + x^32) # needs sage.rings.function_field 1 - """ return self._base_valuation._relative_size(self._to_base_domain(x)) @@ -306,7 +294,6 @@ def _to_base_residue_ring(self, F): sage: w = v.extensions(L)[0] sage: w._to_base_residue_ring(1) 1 - """ return self._base_valuation.residue_ring().coerce(F) @@ -325,7 +312,6 @@ def _from_base_residue_ring(self, F): sage: w = v.extensions(L)[0] sage: w._from_base_residue_ring(1) 1 - """ return self.residue_ring().coerce(F) @@ -343,7 +329,6 @@ def element_with_valuation(self, s): sage: u,uu = v.extensions(L) sage: u.element_with_valuation(1) 5 - """ return self._from_base_domain(self._base_valuation.element_with_valuation(s)) @@ -361,7 +346,6 @@ def _test_to_from_base_domain(self, **options): sage: v = K.valuation(0) sage: w = v.extensions(L)[0] sage: w._test_to_from_base_domain() - """ tester = self._tester(**options) @@ -383,7 +367,6 @@ def _test_to_from_base_residue_ring(self, **options): sage: v = K.valuation(0) sage: w = v.extensions(L)[0] sage: w._test_to_from_base_residue_ring() - """ tester = self._tester(**options) @@ -416,7 +399,6 @@ class FiniteExtensionFromInfiniteValuation(MappedValuation_base, DiscreteValuati sage: v = K.valuation(0) sage: w = v.extension(L); w (x)-adic valuation - """ def __init__(self, parent, base_valuation): r""" @@ -432,7 +414,6 @@ def __init__(self, parent, base_valuation): sage: isinstance(w, FiniteExtensionFromInfiniteValuation) True sage: TestSuite(w).run() # long time - """ MappedValuation_base.__init__(self, parent, base_valuation) DiscreteValuation.__init__(self, parent) @@ -452,7 +433,6 @@ def _eq_(self, other): sage: ww = v.extension(L) sage: w == ww # indirect doctest True - """ return (isinstance(other, FiniteExtensionFromInfiniteValuation) and self._base_valuation == other._base_valuation) @@ -471,7 +451,6 @@ def restriction(self, ring): sage: w = v.extension(L) sage: w.restriction(K) is v True - """ if ring.is_subring(self._base_valuation.domain().base()): return self._base_valuation.restriction(ring) @@ -496,7 +475,6 @@ def _weakly_separating_element(self, other): sage: u,uu = v.extensions(L) sage: u.separating_element([w,uu]) # indirect doctest 1/20*t + 7/20 - """ if isinstance(other, FiniteExtensionFromInfiniteValuation): return self.domain()(self._base_valuation._weakly_separating_element(other._base_valuation)) @@ -524,7 +502,6 @@ def _relative_size(self, x): sage: w = v.extension(L) sage: w._relative_size(1024*t + 1024) 6 - """ return self._base_valuation._relative_size(self._to_base_domain(x)) @@ -547,7 +524,6 @@ def simplify(self, x, error=None, force=False): sage: f = 125*t + 1 sage: u.simplify(f, error=u(f), force=True) 1 - """ x = self.domain().coerce(x) @@ -575,7 +551,6 @@ def lower_bound(self, x): 0 sage: u(t + 2) 1 - """ x = self.domain().coerce(x) return self._base_valuation.lower_bound(self._to_base_domain(x)) @@ -599,7 +574,6 @@ def upper_bound(self, x): True sage: u(t + 2) 1 - """ x = self.domain().coerce(x) return self._base_valuation.upper_bound(self._to_base_domain(x)) @@ -625,7 +599,6 @@ class FiniteExtensionFromLimitValuation(FiniteExtensionFromInfiniteValuation): sage: TestSuite(w[0]).run() # long time # needs sage.rings.function_field sage: TestSuite(w[1]).run() # long time # needs sage.rings.function_field - """ def __init__(self, parent, approximant, G, approximants): r""" @@ -644,7 +617,6 @@ def __init__(self, parent, approximant, G, approximants): sage: from sage.rings.valuation.mapped_valuation import FiniteExtensionFromLimitValuation sage: isinstance(w, FiniteExtensionFromLimitValuation) True - """ # keep track of all extensions to this field extension so we can print # this valuation nicely, dropping any unnecessary information @@ -662,7 +634,6 @@ def _repr_(self): sage: valuations.pAdicValuation(GaussianIntegers().fraction_field(), 2) # indirect doctest # needs sage.rings.number_field 2-adic valuation - """ from .limit_valuation import MacLaneLimitValuation if isinstance(self._base_valuation, MacLaneLimitValuation): diff --git a/src/sage/rings/valuation/scaled_valuation.py b/src/sage/rings/valuation/scaled_valuation.py index d17edc246c7..458400a7e0f 100644 --- a/src/sage/rings/valuation/scaled_valuation.py +++ b/src/sage/rings/valuation/scaled_valuation.py @@ -71,7 +71,6 @@ def create_object(self, version, key): sage: 3*ZZ.valuation(2) # indirect doctest 3 * 2-adic valuation - """ base, s = key @@ -97,7 +96,6 @@ class ScaledValuation_generic(DiscreteValuation): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def __init__(self, parent, base_valuation, s): r""" @@ -115,7 +113,6 @@ def __init__(self, parent, base_valuation, s): sage: from sage.rings.valuation.scaled_valuation import ScaledValuation_generic sage: isinstance(v, ScaledValuation_generic) True - """ DiscreteValuation.__init__(self, parent) self._base_valuation = base_valuation @@ -141,7 +138,6 @@ def residue_ring(self): sage: v = 3*ZZ.valuation(2) sage: v.residue_ring() Finite Field of size 2 - """ return self._base_valuation.residue_ring() @@ -154,7 +150,6 @@ def uniformizer(self): sage: v = 3*ZZ.valuation(2) sage: v.uniformizer() 2 - """ return self._base_valuation.uniformizer() @@ -167,7 +162,6 @@ def _call_(self, f): sage: v = 3*ZZ.valuation(2) sage: v(2) 3 - """ return self._scale * self._base_valuation(f) @@ -180,7 +174,6 @@ def reduce(self, f): sage: v = 3*ZZ.valuation(2) sage: v.reduce(1) 1 - """ return self._base_valuation.reduce(f) @@ -195,7 +188,6 @@ def lift(self, F): sage: v = 3*ZZ.valuation(2) sage: v.lift(1) 1 - """ return self._base_valuation.lift(F) @@ -209,7 +201,6 @@ def extensions(self, ring): sage: v.extensions(GaussianIntegers().fraction_field()) # needs sage.rings.number_field [3 * [ 5-adic valuation, v(x + 2) = 1 ]-adic valuation, 3 * [ 5-adic valuation, v(x + 3) = 1 ]-adic valuation] - """ return [ScaledValuation(w, self._scale) for w in self._base_valuation.extensions(ring)] @@ -222,7 +213,6 @@ def restriction(self, ring): sage: v = 3*QQ.valuation(5) sage: v.restriction(ZZ) 3 * 5-adic valuation - """ restricted = self._base_valuation.restriction(ring) if restricted.is_trivial(): @@ -242,7 +232,6 @@ def _strictly_separating_element(self, other): sage: v3 = 12 * QQ.valuation(3) sage: v2._strictly_separating_element(v3) 2/3 - """ return self._base_valuation._strictly_separating_element(other) @@ -259,7 +248,6 @@ def _weakly_separating_element(self, other): sage: v3 = 12 * QQ.valuation(3) sage: v2._weakly_separating_element(v3) 2 - """ return self._base_valuation._weakly_separating_element(other) @@ -283,7 +271,6 @@ def _ge_(self, other): sage: v2 > v2/2 True - """ if self == other: return True @@ -318,7 +305,6 @@ def _le_(self, other): sage: v2 < v2/2 False - """ return other / self._scale >= self._base_valuation @@ -331,6 +317,5 @@ def value_semigroup(self): sage: v2 = QQ.valuation(2) sage: (2*v2).value_semigroup() Additive Abelian Semigroup generated by -2, 2 - """ return self._scale * self._base_valuation.value_semigroup() diff --git a/src/sage/rings/valuation/trivial_valuation.py b/src/sage/rings/valuation/trivial_valuation.py index 6ba86ab5888..a8c2ff16618 100644 --- a/src/sage/rings/valuation/trivial_valuation.py +++ b/src/sage/rings/valuation/trivial_valuation.py @@ -248,7 +248,7 @@ def _ge_(self, other): class TrivialDiscreteValuation(TrivialDiscretePseudoValuation_base, DiscreteValuation): r""" - The trivial valuation that is zero on non-zero elements. + The trivial valuation that is zero on nonzero elements. EXAMPLES:: diff --git a/src/sage/rings/valuation/valuation.py b/src/sage/rings/valuation/valuation.py index 863d3b423a4..bbc5bdf1db0 100644 --- a/src/sage/rings/valuation/valuation.py +++ b/src/sage/rings/valuation/valuation.py @@ -77,7 +77,6 @@ class DiscretePseudoValuation(Morphism): TESTS:: sage: TestSuite(v).run() # long time # needs sage.geometry.polyhedron - """ def __init__(self, parent): r""" @@ -86,7 +85,6 @@ def __init__(self, parent): sage: from sage.rings.valuation.valuation import DiscretePseudoValuation sage: isinstance(ZZ.valuation(2), DiscretePseudoValuation) True - """ Morphism.__init__(self, parent=parent) @@ -105,7 +103,6 @@ def is_equivalent(self, f, g): False sage: v.is_equivalent(0, 0) True - """ from sage.rings.infinity import infinity if self(f) is infinity: @@ -127,7 +124,6 @@ def __hash__(self): sage: v = QQ.valuation(2) sage: hash(v) == hash(v) # indirect doctest True - """ return self._hash_() @@ -148,7 +144,6 @@ def _hash_(self): sage: v = QQ.valuation(2) sage: hash(v) == hash(v) # indirect doctest True - """ return id(self) @@ -212,7 +207,6 @@ def _eq_(self, other): sage: v = valuations.TrivialValuation(QQ) sage: v == v True - """ return self is other @@ -295,7 +289,6 @@ class InfiniteDiscretePseudoValuation(DiscretePseudoValuation): sage: isinstance(w, InfiniteDiscretePseudoValuation) True sage: TestSuite(w).run() # long time # needs sage.geometry.polyhedron sage.rings.padics - """ def is_discrete_valuation(self): r""" @@ -311,7 +304,6 @@ def is_discrete_valuation(self): sage: w = v.augmentation(x, infinity) sage: w.is_discrete_valuation() False - """ return False @@ -332,7 +324,6 @@ class NegativeInfiniteDiscretePseudoValuation(InfiniteDiscretePseudoValuation): TESTS:: sage: TestSuite(w).run() # long time - """ def is_negative_pseudo_valuation(self): r""" @@ -349,7 +340,6 @@ def is_negative_pseudo_valuation(self): sage: w = K.valuation(v) sage: w.is_negative_pseudo_valuation() True - """ return True @@ -372,7 +362,6 @@ class DiscreteValuation(DiscretePseudoValuation): sage: isinstance(w, DiscreteValuation) True sage: TestSuite(w).run() # long time # needs sage.geometry.polyhedron sage.rings.padics - """ def is_discrete_valuation(self): r""" @@ -383,11 +372,10 @@ def is_discrete_valuation(self): sage: v = valuations.TrivialValuation(ZZ) sage: v.is_discrete_valuation() True - """ return True - def mac_lane_approximants(self, G, assume_squarefree=False, require_final_EF=True, required_precision=-1, require_incomparability=False, require_maximal_degree=False, algorithm="serial"): + def mac_lane_approximants(self, G, assume_squarefree=False, require_final_EF=True, required_precision=-1, require_incomparability=False, require_maximal_degree=False, algorithm='serial'): r""" Return approximants on `K[x]` for the extensions of this valuation to `L=K[x]/(G)`. @@ -400,12 +388,12 @@ def mac_lane_approximants(self, G, assume_squarefree=False, require_final_EF=Tru - ``G`` -- a monic squarefree integral polynomial in a univariate polynomial ring over the domain of this valuation - - ``assume_squarefree`` -- a boolean (default: ``False``), whether to + - ``assume_squarefree`` -- boolean (default: ``False``); whether to assume that ``G`` is squarefree. If ``True``, the squafreeness of ``G`` is not verified though it is necessary when ``require_final_EF`` is set for the algorithm to terminate. - - ``require_final_EF`` -- a boolean (default: ``True``); whether to + - ``require_final_EF`` -- boolean (default: ``True``); whether to require the returned key polynomials to be in one-to-one correspondance to the extensions of this valuation to ``L`` and require them to have the ramification index and residue degree of the @@ -415,20 +403,20 @@ def mac_lane_approximants(self, G, assume_squarefree=False, require_final_EF=Tru to require the last key polynomial of the returned valuations to have at least that valuation. - - ``require_incomparability`` -- a boolean (default: ``False``); + - ``require_incomparability`` -- boolean (default: ``False``); whether to require the returned valuations to be incomparable (with respect to the partial order on valuations defined by comparing them pointwise.) - - ``require_maximal_degree`` -- a boolean (default: ``False``); whether + - ``require_maximal_degree`` -- boolean (default: ``False``); whether to require the last key polynomial of the returned valuation to have maximal degree. This is most relevant when using this algorithm to compute approximate factorizations of ``G``, when set to ``True``, the last key polynomial has the same degree as the corresponding factor. - - ``algorithm`` -- one of ``"serial"`` or ``"parallel"`` (default: - ``"serial"``); whether or not to parallelize the algorithm + - ``algorithm`` -- one of ``'serial'`` or ``'parallel'`` (default: + ``'serial'``); whether or not to parallelize the algorithm EXAMPLES:: @@ -689,7 +677,6 @@ def mac_lane_approximants(self, G, assume_squarefree=False, require_final_EF=Tru v(x^36 + 60552000*x^33 + 268157412*x^30 + 173881701*x^27 + 266324841*x^24 + 83125683*x^21 + 111803814*x^18 + 31925826*x^15 + 205726716*x^12 + 17990262*x^9 + 351459648*x^6 + 127014399*x^3 + 359254116) = +Infinity ]] - """ R = G.parent() if R.base_ring() is not self.domain(): @@ -821,7 +808,6 @@ def _pow(self, x, e, error): 4 sage: v._pow(2, 1000, error=4) 0 - """ if e == 0: return self.domain().one() @@ -844,8 +830,8 @@ def mac_lane_approximant(self, G, valuation, approximants=None): - ``valuation`` -- a valuation on the parent of ``G`` - - ``approximants`` -- the output of :meth:`mac_lane_approximants`. - If not given, it is computed. + - ``approximants`` -- the output of :meth:`mac_lane_approximants`; + if not given, it is computed EXAMPLES:: @@ -910,7 +896,6 @@ def mac_lane_approximant(self, G, valuation, approximants=None): sage: w = GaussValuation(R, v).augmentation(x + 3, 2) sage: v.mac_lane_approximant(G, w) # needs sage.geometry.polyhedron sage.rings.padics [ Gauss valuation induced by 2-adic valuation, v(x + 1) = 1 ] - """ if valuation.restriction(valuation.domain().base_ring()) is not self: raise ValueError @@ -951,7 +936,7 @@ def montes_factorization(self, G, assume_squarefree=False, required_precision=No - ``G`` -- a monic polynomial over the domain of this valuation - - ``assume_squarefree`` -- a boolean (default: ``False``), whether to + - ``assume_squarefree`` -- boolean (default: ``False``); whether to assume ``G`` to be squarefree - ``required_precision`` -- a number or infinity (default: @@ -1021,7 +1006,6 @@ def montes_factorization(self, G, assume_squarefree=False, required_precision=No The underlying algorithm is described in [Mac1936II]_ and thoroughly analyzed in [GMN2008]_. - """ if required_precision is None: from sage.rings.infinity import infinity @@ -1053,7 +1037,6 @@ def _ge_(self, other): sage: w = QQ.valuation(2) sage: v >= w False - """ if other.is_trivial(): return other.is_discrete_valuation() @@ -1062,7 +1045,7 @@ def _ge_(self, other): class MacLaneApproximantNode(): r""" - A node in the tree computed by :meth:`DiscreteValuation.mac_lane_approximants` + A node in the tree computed by :meth:`DiscreteValuation.mac_lane_approximants`. Leaves in the computation of the tree of approximants :meth:`~DiscreteValuation.mac_lane_approximants`. Each vertex consists of a @@ -1080,7 +1063,6 @@ class MacLaneApproximantNode(): sage: v = ZZ.valuation(3) sage: v.extension(GaussianIntegers()) # indirect doctest # needs sage.rings.number_field sage.rings.padics 3-adic valuation - """ def __init__(self, valuation, parent, ef, principal_part_bound, coefficients, valuations): r""" @@ -1089,7 +1071,6 @@ def __init__(self, valuation, parent, ef, principal_part_bound, coefficients, va sage: from sage.rings.valuation.valuation import MacLaneApproximantNode sage: node = MacLaneApproximantNode(QQ.valuation(2), None, 1, None, None, None) sage: TestSuite(node).run() - """ self.valuation = valuation self.parent = parent @@ -1112,7 +1093,6 @@ def __eq__(self, other): False sage: n == n True - """ if type(self) is not type(other): return False @@ -1131,7 +1111,6 @@ def __ne__(self, other): True sage: n != n False - """ return not (self == other) diff --git a/src/sage/rings/valuation/valuation_space.py b/src/sage/rings/valuation/valuation_space.py index 3eb143a6d4b..24e5f598624 100644 --- a/src/sage/rings/valuation/valuation_space.py +++ b/src/sage/rings/valuation/valuation_space.py @@ -99,7 +99,6 @@ class DiscretePseudoValuationSpace(UniqueRepresentation, Homset): TESTS:: sage: TestSuite(H).run() # long time - """ def __init__(self, domain): r""" @@ -108,7 +107,6 @@ def __init__(self, domain): sage: from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace sage: isinstance(QQ.valuation(2).parent(), DiscretePseudoValuationSpace) True - """ from .value_group import DiscreteValuationCodomain # A valuation is a map from an additive semigroup to an additive semigroup, however, it @@ -140,7 +138,6 @@ def _abstract_element_class(self): sage: from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace sage: isinstance(QQ.valuation(2), DiscretePseudoValuationSpace.ElementMethods) # indirect doctest True - """ class_name = "%s._abstract_element_class" % self.__class__.__name__ from sage.structure.dynamic_class import dynamic_class @@ -156,7 +153,6 @@ def _get_action_(self, S, op, self_on_left): sage: from operator import mul sage: v.parent().get_action(ZZ, mul) # indirect doctest Right action by Integer Ring on Discrete pseudo-valuations on Rational Field - """ from operator import mul from sage.rings.infinity import InfinityRing @@ -175,7 +171,6 @@ def _an_element_(self): sage: from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace sage: DiscretePseudoValuationSpace(QQ).an_element() # indirect doctest Trivial pseudo-valuation on Rational Field - """ from .trivial_valuation import TrivialPseudoValuation return TrivialPseudoValuation(self.domain()) @@ -189,7 +184,6 @@ def _repr_(self): sage: from sage.rings.valuation.valuation_space import DiscretePseudoValuationSpace sage: DiscretePseudoValuationSpace(QQ) # indirect doctest Discrete pseudo-valuations on Rational Field - """ return "Discrete pseudo-valuations on %r" % (self.domain(),) @@ -205,7 +199,6 @@ def __contains__(self, x): True sage: QQ.valuation(2) in H True - """ # override the logic from Homset with the original implementation for Parent # which entirely relies on a proper implementation of @@ -223,7 +216,6 @@ def __call__(self, x): sage: H = DiscretePseudoValuationSpace(QQ) sage: H(QQ.valuation(2)) 2-adic valuation - """ # override the logic from Homset with the original implementation for Parent # which entirely relies on a proper implementation of @@ -233,7 +225,7 @@ def __call__(self, x): def _element_constructor_(self, x): r""" - Create an element in this space from ``x``, + Create an element in this space from ``x``. EXAMPLES: @@ -252,7 +244,6 @@ def _element_constructor_(self, x): False sage: Z(Q(v)) in Z True - """ if isinstance(x.parent(), DiscretePseudoValuationSpace): if x.domain() is not self.domain(): @@ -301,7 +292,6 @@ class ElementMethods: sage: m = H.__make_element_class__(DiscretePseudoValuation)(H) sage: m._test_category() - """ def is_discrete_pseudo_valuation(self): r""" @@ -311,7 +301,6 @@ def is_discrete_pseudo_valuation(self): sage: QQ.valuation(2).is_discrete_pseudo_valuation() True - """ return True @@ -326,7 +315,6 @@ def is_discrete_valuation(self): sage: QQ.valuation(2).is_discrete_valuation() True - """ def is_negative_pseudo_valuation(self): @@ -339,7 +327,6 @@ def is_negative_pseudo_valuation(self): sage: QQ.valuation(2).is_negative_pseudo_valuation() False - """ from sage.categories.fields import Fields if self.is_discrete_valuation(): @@ -362,14 +349,13 @@ def is_trivial(self): sage: QQ.valuation(7).is_trivial() False - """ from sage.rings.infinity import infinity if self(self.domain().one()) is infinity: # the constant infinity return True if self(self.uniformizer()) != 0: - # not constant on the non-zero elements + # not constant on the nonzero elements return False return True @@ -394,7 +380,6 @@ def uniformizer(self): Traceback (most recent call last): ... ValueError: Trivial valuations do not define a uniformizing element - """ @cached_method @@ -418,7 +403,6 @@ def value_group(self): Traceback (most recent call last): ... ValueError: The trivial pseudo-valuation that is infinity everywhere does not have a value group. - """ from .value_group import DiscreteValueGroup return DiscreteValueGroup(self(self.uniformizer())) @@ -454,7 +438,6 @@ def value_semigroup(self): sage: u = w.augmentation(x, 5/3) sage: u.value_semigroup() Additive Abelian Semigroup generated by 1, 5/3 - """ from sage.categories.fields import Fields if self.domain() in Fields(): @@ -473,7 +456,6 @@ def element_with_valuation(self, s): sage: v = ZZ.valuation(2) sage: v.element_with_valuation(10) 1024 - """ from sage.rings.integer_ring import ZZ from sage.rings.rational_field import QQ @@ -492,7 +474,7 @@ def element_with_valuation(self, s): def residue_ring(self): r""" Return the residue ring of this valuation, i.e., the elements of - non-negative valuation modulo the elements of positive valuation. + nonnegative valuation modulo the elements of positive valuation. EXAMPLES:: sage: QQ.valuation(2).residue_ring() @@ -509,13 +491,12 @@ def residue_ring(self): Integer Ring sage: GaussValuation(ZZ['x'], ZZ.valuation(2)).residue_ring() Univariate Polynomial Ring in x over Finite Field of size 2... - """ def residue_field(self): r""" Return the residue field of this valuation, i.e., the field of - fractions of the :meth:`residue_ring`, the elements of non-negative + fractions of the :meth:`residue_ring`, the elements of nonnegative valuation modulo the elements of positive valuation. EXAMPLES:: @@ -529,14 +510,13 @@ def residue_field(self): Rational Field sage: GaussValuation(ZZ['x'], ZZ.valuation(2)).residue_field() Rational function field in x over Finite Field of size 2 - """ ret = self.residue_ring() from sage.categories.fields import Fields if ret in Fields(): return ret - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - if is_PolynomialRing(ret): + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + if isinstance(ret, PolynomialRing_general): from sage.rings.function_field.constructor import FunctionField return FunctionField(ret.base_ring().fraction_field(), names=(ret.variable_name(),)) return ret.fraction_field() @@ -559,8 +539,7 @@ def reduce(self, x): sage: v.reduce(1/2) Traceback (most recent call last): ... - ValueError: reduction is only defined for elements of non-negative valuation - + ValueError: reduction is only defined for elements of nonnegative valuation """ @abstract_method @@ -574,7 +553,6 @@ def lift(self, X): sage: v = QQ.valuation(2) sage: v.lift(v.residue_ring().one()) 1 - """ def extension(self, ring): @@ -603,7 +581,6 @@ def extensions(self, ring): sage: v = ZZ.valuation(2) sage: v.extensions(QQ) [2-adic valuation] - """ if ring is self.domain(): return [self] @@ -619,7 +596,6 @@ def restriction(self, ring): sage: w = v.restriction(ZZ) sage: w.domain() Integer Ring - """ if ring is self.domain(): return self @@ -638,7 +614,6 @@ def change_domain(self, ring): sage: v = QQ.valuation(3) sage: v.change_domain(ZZ) 3-adic valuation - """ if ring is self.domain(): return self @@ -654,7 +629,7 @@ def scale(self, scalar): INPUT: - - ``scalar`` -- a non-negative rational number or infinity + - ``scalar`` -- a nonnegative rational number or infinity EXAMPLES:: @@ -684,7 +659,6 @@ def scale(self, scalar): +Infinity sage: w(0) +Infinity - """ from sage.rings.infinity import infinity if scalar is infinity: @@ -696,7 +670,7 @@ def scale(self, scalar): if scalar == 1: return self if scalar < 0: - raise ValueError("scalar must be non-negative") + raise ValueError("scalar must be nonnegative") if self.is_trivial(): return self @@ -720,7 +694,6 @@ def separating_element(self, others): sage: v5 = QQ.valuation(5) sage: v2.separating_element([v3,v5]) 4/15 - """ try: iter(others) @@ -791,7 +764,6 @@ def _strictly_separating_element(self, other): sage: v3 = QQ.valuation(3) sage: v2._strictly_separating_element(v3) 2/3 - """ from sage.rings.infinity import infinity @@ -814,14 +786,14 @@ def _strictly_separating_element(self, other): # option this generically. return self.domain()(~denominator) - # We need non-negative integers a and b such that + # We need nonnegative integers a and b such that # a*n - b*d > 0 and a*nn - b*dd < 0 if nn == 0: # the above becomes b != 0 and a/b > d/n b = 1 a = (d/n + 1).floor() else: - # Since n,nn,d,dd are all non-negative this is essentially equivalent to + # Since n,nn,d,dd are all nonnegative this is essentially equivalent to # a/b > d/n and b/a > nn/dd # which is # dd/nn > a/b > d/n @@ -874,7 +846,6 @@ def _weakly_separating_element(self, other): sage: v3 = QQ.valuation(3) sage: v2._weakly_separating_element(v3) 2 - """ ret = self.uniformizer() if self(ret) > other(ret): @@ -886,7 +857,7 @@ def shift(self, x, s): Shift ``x`` in its expansion with respect to :meth:`uniformizer` by ``s`` "digits". - For non-negative ``s``, this just returns ``x`` multiplied by a + For nonnegative ``s``, this just returns ``x`` multiplied by a power of the uniformizer `\pi`. For negative ``s``, it does the same but when not over a field, it @@ -914,7 +885,6 @@ def shift(self, x, s): x sage: w.shift(x + 2*x^2, -1) x^2 - """ from sage.rings.integer_ring import ZZ x = self.domain().coerce(x) @@ -953,7 +923,6 @@ def simplify(self, x, error=None, force=False): 2 sage: v.simplify(6, error=0, force=True) 0 - """ x = self.domain().coerce(x) @@ -973,7 +942,6 @@ def lower_bound(self, x): sage: v = ZZ.valuation(2) sage: v.lower_bound(2^10) 10 - """ return self(x) @@ -989,7 +957,6 @@ def upper_bound(self, x): sage: v = ZZ.valuation(2) sage: v.upper_bound(2^10) 10 - """ return self(x) @@ -1027,7 +994,6 @@ def inverse(self, x, precision): sage: v = QQ.valuation(2) sage: v.inverse(2, 2) 1/2 - """ return x.inverse_of_unit() @@ -1055,7 +1021,6 @@ def _relative_size(self, x): sage: v._relative_size(2**20) 1 - """ return 1 @@ -1067,7 +1032,6 @@ def _test_is_negative_pseudo_valuation(self, **options): sage: v = ZZ.valuation(3) sage: v._test_is_negative_pseudo_valuation() - """ tester = self._tester(**options) @@ -1090,7 +1054,6 @@ def _test_bounds(self, **options): sage: v = ZZ.valuation(3) sage: v._test_bounds() - """ tester = self._tester(**options) @@ -1107,7 +1070,6 @@ def _test_simplify(self, **options): sage: v = ZZ.valuation(3) sage: v._test_simplify() - """ tester = self._tester(**options) @@ -1150,7 +1112,6 @@ def _test_shift(self, **options): sage: v = ZZ.valuation(3) sage: v._test_shift() - """ if self.is_trivial() and not self.is_discrete_valuation(): return @@ -1186,7 +1147,6 @@ def _test_scale(self, **options): sage: v = ZZ.valuation(3) sage: v._test_scale() - """ tester = self._tester(**options) @@ -1223,7 +1183,6 @@ def _test_add(self, **options): sage: v = ZZ.valuation(3) sage: v._test_add() - """ tester = self._tester(**options) S = self.domain().some_elements() @@ -1241,7 +1200,6 @@ def _test_infinite_zero(self, **options): sage: v = QQ.valuation(5) sage: v._test_infinite_zero() - """ tester = self._tester(**options) from sage.rings.infinity import infinity @@ -1255,7 +1213,6 @@ def _test_mul(self, **options): sage: v = QQ.valuation(5) sage: v._test_mul() - """ tester = self._tester(**options) S = self.domain().some_elements() @@ -1268,7 +1225,7 @@ def _test_mul(self, **options): def _test_no_infinite_units(self, **options): r""" - Checks that no units are sent to infinity. + Check that no units are sent to infinity. TESTS:: @@ -1284,7 +1241,6 @@ def _test_no_infinite_units(self, **options): +Infinity sage: v.is_trivial() True - """ if not self.is_discrete_valuation() and self.is_trivial(): return @@ -1305,7 +1261,6 @@ def _test_value_group(self, **options): sage: v = QQ.valuation(5) sage: v._test_value_group() - """ from sage.rings.infinity import infinity tester = self._tester(**options) @@ -1334,7 +1289,6 @@ def _test_value_semigroup(self, **options): sage: v = QQ.valuation(5) sage: v._test_value_semigroup() # needs sage.geometry.polyhedron - """ tester = self._tester(**options) @@ -1353,7 +1307,6 @@ def _test_element_with_valuation(self, **options): sage: v = QQ.valuation(5) sage: v._test_element_with_valuation() # needs sage.geometry.polyhedron - """ tester = self._tester(**options) @@ -1372,7 +1325,6 @@ def _test_residue_ring(self, **options): sage: v = QQ.valuation(5) sage: v._test_residue_ring() - """ tester = self._tester(**options) @@ -1404,7 +1356,6 @@ def _test_reduce(self, **options): sage: v = QQ.valuation(5) sage: v._test_reduce() - """ tester = self._tester(**options) @@ -1443,7 +1394,6 @@ def _test_lift(self, **options): sage: v = QQ.valuation(5) sage: v._test_lift() - """ tester = self._tester(**options) @@ -1473,7 +1423,6 @@ def _test_restriction(self, **options): sage: v = QQ.valuation(5) sage: v._test_restriction() - """ tester = self._tester(**options) @@ -1487,7 +1436,6 @@ def _test_extension(self, **options): sage: v = QQ.valuation(5) sage: v._test_extension() - """ tester = self._tester(**options) @@ -1502,7 +1450,6 @@ def _test_change_domain(self, **options): sage: v = QQ.valuation(5) sage: v._test_change_domain() - """ tester = self._tester(**options) @@ -1516,7 +1463,6 @@ def _test_no_infinite_nonzero(self, **options): sage: v = QQ.valuation(5) sage: v._test_no_infinite_nonzero() - """ if not self.is_discrete_valuation(): return @@ -1535,7 +1481,6 @@ def _test_residue_field(self, **options): sage: v = QQ.valuation(5) sage: v._test_residue_field() - """ if not self.is_discrete_valuation(): return @@ -1581,7 +1526,6 @@ def _test_ge(self, **options): sage: v = QQ.valuation(5) sage: v._test_ge() - """ tester = self._tester(**options) @@ -1602,7 +1546,6 @@ def _test_le(self, **options): sage: v = QQ.valuation(5) sage: v._test_le() - """ tester = self._tester(**options) @@ -1623,7 +1566,6 @@ def _test_inverse(self, **options): sage: v = QQ.valuation(5) sage: v._test_inverse() - """ tester = self._tester(**options) diff --git a/src/sage/rings/valuation/value_group.py b/src/sage/rings/valuation/value_group.py index b35d07e70a3..f3afd30c413 100644 --- a/src/sage/rings/valuation/value_group.py +++ b/src/sage/rings/valuation/value_group.py @@ -46,7 +46,6 @@ class DiscreteValuationCodomain(UniqueRepresentation, Parent): TESTS:: sage: TestSuite(C).run() # long time - """ def __init__(self): r""" @@ -55,7 +54,6 @@ def __init__(self): sage: from sage.rings.valuation.value_group import DiscreteValuationCodomain sage: isinstance(QQ.valuation(2).codomain(), DiscreteValuationCodomain) True - """ from sage.sets.finite_enumerated_set import FiniteEnumeratedSet from sage.categories.additive_monoids import AdditiveMonoids @@ -79,7 +77,6 @@ def _element_constructor_(self, x): +Infinity sage: DiscreteValuationCodomain()(-infinity) -Infinity - """ if x is infinity: return x @@ -98,7 +95,6 @@ def _repr_(self): sage: from sage.rings.valuation.value_group import DiscreteValuationCodomain sage: DiscreteValuationCodomain() # indirect doctest Codomain of Discrete Valuations - """ return "Codomain of Discrete Valuations" @@ -137,12 +133,11 @@ class DiscreteValueGroup(UniqueRepresentation, Parent): sage: TestSuite(D1).run() # long time sage: TestSuite(D2).run() # long time sage: TestSuite(D3).run() # long time - """ @staticmethod def __classcall__(cls, generator): r""" - Normalizes ``generator`` to a positive rational so that this is a + Normalize ``generator`` to a positive rational so that this is a unique parent. TESTS:: @@ -150,7 +145,6 @@ def __classcall__(cls, generator): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: DiscreteValueGroup(1) is DiscreteValueGroup(-1) True - """ generator = QQ.coerce(generator).abs() return super().__classcall__(cls, generator) @@ -162,7 +156,6 @@ def __init__(self, generator): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: isinstance(DiscreteValueGroup(0), DiscreteValueGroup) True - """ from sage.categories.modules import Modules self._generator = generator @@ -195,7 +188,6 @@ def _element_constructor_(self, x): Traceback (most recent call last): ... ValueError: `1/2` is not in Additive Abelian Group generated by 1. - """ x = QQ.coerce(x) if x == 0 or (self._generator != 0 and x / self._generator in ZZ): @@ -212,7 +204,6 @@ def _repr_(self): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: DiscreteValueGroup(0) # indirect doctest Trivial Additive Abelian Group - """ if self.is_trivial(): return "Trivial Additive Abelian Group" @@ -238,7 +229,6 @@ def __add__(self, other): Additive Abelian Group generated by 1/2 sage: DiscreteValueGroup(2/7) + DiscreteValueGroup(4/9) Additive Abelian Group generated by 2/63 - """ if isinstance(other, DiscreteValueGroup): return DiscreteValueGroup(self._generator.gcd(other._generator)) @@ -299,7 +289,6 @@ def index(self, other): Traceback (most recent call last): ... ValueError: other must be a subgroup of this group - """ if not isinstance(other, DiscreteValueGroup): raise ValueError("other must be a DiscreteValueGroup") @@ -321,7 +310,6 @@ def numerator(self): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: DiscreteValueGroup(3/8).numerator() 3 - """ return self._generator.numerator() @@ -334,7 +322,6 @@ def denominator(self): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: DiscreteValueGroup(3/8).denominator() 8 - """ return self._generator.denominator() @@ -347,7 +334,6 @@ def gen(self): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: DiscreteValueGroup(-3/8).gen() 3/8 - """ return self._generator @@ -360,7 +346,6 @@ def some_elements(self): sage: from sage.rings.valuation.value_group import DiscreteValueGroup sage: DiscreteValueGroup(-3/8).some_elements() [3/8, -3/8, 0, 42, 3/2, -3/2, 9/8, -9/8] - """ return [self._generator, -self._generator] + [x for x in QQ.some_elements() if x in self] @@ -375,7 +360,6 @@ def is_trivial(self): False sage: DiscreteValueGroup(0).is_trivial() True - """ return self._generator.is_zero() @@ -394,7 +378,6 @@ def _element_with_valuation(self, subgroup, s): (-3, 1) sage: DiscreteValueGroup(3/8)._element_with_valuation(DiscreteValueGroup(3), 33/8) (3, 1) - """ if s not in self: raise ValueError("s must be in the value group but %r is not in %r." % (s, self)) @@ -432,7 +415,6 @@ class DiscreteValueSemigroup(UniqueRepresentation, Parent): sage: TestSuite(D1).run() # long time sage: TestSuite(D2).run() # long time # needs sage.geometry.polyhedron sage: TestSuite(D3).run() # long time # needs sage.numerical.mip - """ @staticmethod def __classcall__(cls, generators): @@ -454,7 +436,6 @@ def __classcall__(cls, generators): sage: DiscreteValueSemigroup([1,-1,1/3]) is DiscreteValueSemigroup([1/3,-1/3]) False - """ if generators in QQ: generators = [generators] @@ -482,7 +463,6 @@ def __init__(self, generators): sage: from sage.rings.valuation.value_group import DiscreteValueSemigroup sage: isinstance(DiscreteValueSemigroup([0]), DiscreteValueSemigroup) True - """ from sage.categories.additive_magmas import AdditiveMagmas self._generators = generators @@ -513,7 +493,6 @@ def _solve_linear_program(self, target): {0: 1, 1: 0, 2: 2} sage: 1*2 + 0*3 + 2*5 12 - """ if len(self._generators) == 0: if target == 0: @@ -536,7 +515,7 @@ def _solve_linear_program(self, target): return {0: exp, 1: 0} from sage.numerical.mip import MixedIntegerLinearProgram, MIPSolverException - P = MixedIntegerLinearProgram(maximization=False, solver="ppl") + P = MixedIntegerLinearProgram(maximization=False, solver='ppl') x = P.new_variable(integer=True, nonnegative=True) constraint = sum([g * x[i] for i, g in enumerate(self._generators)]) == target @@ -587,7 +566,6 @@ def _repr_(self): sage: from sage.rings.valuation.value_group import DiscreteValueSemigroup sage: DiscreteValueSemigroup(0) # indirect doctest Trivial Additive Abelian Semigroup - """ if self.is_trivial(): return "Trivial Additive Abelian Semigroup" @@ -613,7 +591,6 @@ def __add__(self, other): Additive Abelian Semigroup generated by 1/2 sage: DiscreteValueGroup(2/7) + DiscreteValueSemigroup(4/9) Additive Abelian Semigroup generated by -2/7, 2/7, 4/9 - """ if isinstance(other, DiscreteValueSemigroup): return DiscreteValueSemigroup(self._generators + other._generators) @@ -643,7 +620,6 @@ def _mul_(self, other, switch_sides=False): Additive Abelian Semigroup generated by 1/4 sage: D * 0 Trivial Additive Abelian Semigroup - """ other = QQ.coerce(other) return DiscreteValueSemigroup([g*other for g in self._generators]) @@ -657,7 +633,6 @@ def gens(self): sage: from sage.rings.valuation.value_group import DiscreteValueSemigroup sage: DiscreteValueSemigroup(-3/8).gens() (-3/8,) - """ return tuple(self._generators) @@ -691,7 +666,6 @@ def is_trivial(self): False sage: DiscreteValueSemigroup([]).is_trivial() True - """ return len(self._generators) == 0 diff --git a/src/sage/sandpiles/examples.py b/src/sage/sandpiles/examples.py index a7615723e81..279d0cfae0c 100644 --- a/src/sage/sandpiles/examples.py +++ b/src/sage/sandpiles/examples.py @@ -51,15 +51,9 @@ class SandpileExamples: """ def __call__(self): r""" - If sandpiles() is executed, return a helpful message. + If ``sandpiles()`` is executed, return a helpful message. - INPUT: - - None - - OUTPUT: - - None + OUTPUT: none EXAMPLES:: @@ -78,11 +72,9 @@ def Complete(self, n): INPUT: - - ``n`` -- positive integer - - OUTPUT: + - ``n`` -- positive integer - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -100,11 +92,9 @@ def Cycle(self, n): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - OUTPUT: - - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -125,13 +115,7 @@ def Diamond(self): """ Sandpile on the diamond graph. - INPUT: - - None - - OUTPUT: - - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -147,11 +131,9 @@ def Fan(self, n, deg_three_verts=False): INPUT: - - ``n`` -- a non-negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -183,11 +165,9 @@ def Grid(self, m, n): INPUT: - - ``m``, ``n`` -- negative integers + - ``m``, ``n`` -- negative integers - OUTPUT: - - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -211,13 +191,7 @@ def House(self): """ Sandpile on the House graph. - INPUT: - - None - - OUTPUT: - - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -233,11 +207,9 @@ def Wheel(self, n): INPUT: - - ``n`` -- a non-negative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - Sandpile + OUTPUT: Sandpile EXAMPLES:: diff --git a/src/sage/sandpiles/sandpile.py b/src/sage/sandpiles/sandpile.py index b8697213bf0..6fb9720b945 100644 --- a/src/sage/sandpiles/sandpile.py +++ b/src/sage/sandpiles/sandpile.py @@ -363,7 +363,7 @@ def _sandpile_help(cls, usage, verbose=True): """ - Prints help text for classes in this module; see the ``help()`` methods on + Print help text for classes in this module; see the ``help()`` methods on individual classes in this module for example usage. """ @@ -415,10 +415,7 @@ def version(): r""" The version number of Sage Sandpiles. - OUTPUT: - - string - + OUTPUT: string EXAMPLES:: @@ -438,11 +435,9 @@ def help(verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - printed string + OUTPUT: printed string EXAMPLES:: @@ -517,8 +512,8 @@ def __init__(self, g, sink=None): INPUT: - - ``g`` -- dict for directed multigraph with edges weighted by - nonnegative integers (see NOTE), a Graph or DiGraph. + - ``g`` -- dictionary for directed multigraph with edges weighted by + nonnegative integers (see NOTE), a Graph or DiGraph - ``sink`` -- (optional) A sink vertex. Any outgoing edges from the designated sink are ignored for the purposes of stabilization. It is @@ -526,9 +521,7 @@ def __init__(self, g, sink=None): ``sink`` argument is omitted, the first vertex in the list of the Sandpile's vertices is set as the sink. - OUTPUT: - - Sandpile + OUTPUT: Sandpile EXAMPLES: @@ -653,9 +646,7 @@ def __copy__(self): """ Make a copy of this sandpile. - OUTPUT: - - A new :class:`Sandpile` instance. + OUTPUT: a new :class:`Sandpile` instance EXAMPLES:: @@ -757,9 +748,7 @@ def __str__(self) -> str: r""" The name of the sandpile. - OUTPUT: - - string + OUTPUT: string EXAMPLES:: @@ -775,7 +764,7 @@ def __str__(self) -> str: def _repr_(self): r""" - String representation of self. + String representation of ``self``. EXAMPLES:: @@ -831,9 +820,7 @@ def dict(self): r""" A dictionary of dictionaries representing a directed graph. - OUTPUT: - - dict + OUTPUT: dictionary EXAMPLES:: @@ -852,9 +839,7 @@ def sink(self): r""" The sink vertex. - OUTPUT: - - sink vertex + OUTPUT: sink vertex EXAMPLES:: @@ -873,9 +858,7 @@ def laplacian(self): r""" The Laplacian matrix of the graph. Its *rows* encode the vertex firing rules. - OUTPUT: - - matrix + OUTPUT: matrix EXAMPLES:: @@ -897,9 +880,7 @@ def reduced_laplacian(self): r""" The reduced Laplacian matrix of the graph. - OUTPUT: - - matrix + OUTPUT: matrix EXAMPLES:: @@ -925,9 +906,7 @@ def group_order(self): r""" The size of the sandpile group. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -955,10 +934,7 @@ def max_stable(self): r""" The maximal stable configuration. - OUTPUT: - - SandpileConfig (the maximal stable configuration) - + OUTPUT: SandpileConfig (the maximal stable configuration) EXAMPLES:: @@ -1024,9 +1000,7 @@ def out_degree(self, v=None): - ``v`` -- (optional) vertex name - OUTPUT: - - integer or dict + OUTPUT: integer or dict EXAMPLES:: @@ -1063,9 +1037,7 @@ def in_degree(self, v=None): - ``v`` -- (optional) vertex name - OUTPUT: - - integer or dict + OUTPUT: integer or dict EXAMPLES:: @@ -1173,9 +1145,7 @@ def burning_script(self): r""" A script for the minimal burning configuration. - OUTPUT: - - dict + OUTPUT: dictionary EXAMPLES:: @@ -1225,9 +1195,7 @@ def nonsink_vertices(self): r""" The nonsink vertices. - OUTPUT: - - list of vertices + OUTPUT: list of vertices EXAMPLES:: @@ -1245,9 +1213,7 @@ def all_k_config(self, k): - ``k`` -- integer - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -1261,9 +1227,7 @@ def zero_config(self): r""" The all-zero configuration. - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -1287,7 +1251,7 @@ def zero_config(self): def _set_identity(self): r""" - Computes ``_identity``, the variable holding the identity configuration + Compute ``_identity``, the variable holding the identity configuration of the sandpile group, when ``identity()`` is first called by a user. EXAMPLES:: @@ -1303,16 +1267,13 @@ def _set_identity(self): def identity(self, verbose=True): r""" The identity configuration. If ``verbose`` is ``False``, the - configuration are converted to a list of integers. + configuration is converted to a list of integers. INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - SandpileConfig or a list of integers If ``verbose`` is ``False``, the - configuration are converted to a list of integers. + OUTPUT: SandpileConfig or a list of integers EXAMPLES:: @@ -1331,7 +1292,7 @@ def identity(self, verbose=True): def _set_recurrents(self): """ - Computes ``_recurrents``, the variable holding the list of recurrent + Compute ``_recurrents``, the variable holding the list of recurrent configurations, when ``recurrents()`` is first called by a user. EXAMPLES:: @@ -1370,12 +1331,9 @@ def recurrents(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: - - list of recurrent configurations + - ``verbose`` -- boolean (default: ``True``) + OUTPUT: list of recurrent configurations EXAMPLES:: @@ -1409,7 +1367,7 @@ def recurrents(self, verbose=True): def _set_superstables(self): r""" - Computes ``_superstables``, the variable holding the list of superstable + Compute ``_superstables``, the variable holding the list of superstable configurations, when ``superstables()`` is first called by a user. EXAMPLES:: @@ -1429,12 +1387,9 @@ def superstables(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: - - list of SandpileConfig + - ``verbose`` -- boolean (default: ``True``) + OUTPUT: list of SandpileConfig EXAMPLES:: @@ -1489,7 +1444,7 @@ def group_gens(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean + - ``verbose`` -- boolean (default: ``True``) OUTPUT: @@ -1521,9 +1476,7 @@ def genus(self): This is only defined for undirected graphs. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -1541,9 +1494,7 @@ def is_undirected(self): Is the underlying graph undirected? ``True`` if `(u,v)` is and edge if and only if `(v,u)` is an edge, each edge with the same weight. - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -1557,7 +1508,7 @@ def is_undirected(self): def _set_min_recurrents(self): r""" - Computes the minimal recurrent elements. If the underlying graph is + Compute the minimal recurrent elements. If the underlying graph is undirected, these are the recurrent elements of least degree. EXAMPLES:: @@ -1586,11 +1537,9 @@ def min_recurrents(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - list of SandpileConfig + OUTPUT: list of SandpileConfig EXAMPLES:: @@ -1623,11 +1572,9 @@ def max_superstables(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - tuple of SandpileConfig + OUTPUT: tuple of SandpileConfig EXAMPLES:: @@ -1657,9 +1604,7 @@ def tutte_polynomial(self): The Tutte polynomial of the underlying graph. Only defined for undirected sandpile graphs. - OUTPUT: - - polynomial + OUTPUT: polynomial EXAMPLES:: @@ -1706,11 +1651,9 @@ def avalanche_polynomial(self, multivariable=True): INPUT: - - ``multivariable`` -- (default: ``True``) boolean - - OUTPUT: + - ``multivariable`` -- boolean (default: ``True``) - polynomial + OUTPUT: polynomial EXAMPLES:: @@ -1746,11 +1689,9 @@ def nonspecial_divisors(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean + - ``verbose`` -- boolean (default: ``True``) - OUTPUT: - - list (of divisors) + OUTPUT: list (of divisors) EXAMPLES:: @@ -1793,9 +1734,7 @@ def canonical_divisor(self): The canonical divisor. This is the divisor with `\deg(v)-2` grains of sand on each vertex (not counting loops). Only for undirected graphs. - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -1816,7 +1755,7 @@ def canonical_divisor(self): def _set_invariant_factors(self): r""" - Computes the variable holding the elementary divisors of the sandpile + Compute the variable holding the elementary divisors of the sandpile group when ``invariant_factors()`` is first called by the user. EXAMPLES:: @@ -1835,9 +1774,7 @@ def invariant_factors(self): r""" The invariant factors of the sandpile group. - OUTPUT: - - list of integers + OUTPUT: list of integers EXAMPLES:: @@ -1849,7 +1786,7 @@ def invariant_factors(self): def _set_hilbert_function(self): """ - Computes the variables holding the Hilbert function of the homogeneous + Compute the variables holding the Hilbert function of the homogeneous homogeneous toppling ideal, the first differences of the Hilbert function, and the postulation number for the zero-set of the sandpile ideal when any one of these is called by the user. @@ -1875,9 +1812,7 @@ def h_vector(self): this is the list of first differences of the Hilbert function of the (homogeneous) toppling ideal. - OUTPUT: - - list of nonnegative integers + OUTPUT: list of nonnegative integers EXAMPLES:: @@ -1893,9 +1828,7 @@ def hilbert_function(self): r""" The Hilbert function of the homogeneous toppling ideal. - OUTPUT: - - list of nonnegative integers + OUTPUT: list of nonnegative integers EXAMPLES:: @@ -1912,9 +1845,7 @@ def postulation(self): The postulation number of the toppling ideal. This is the largest weight of a superstable configuration of the graph. - OUTPUT: - - nonnegative integer + OUTPUT: nonnegative integer EXAMPLES:: @@ -1944,9 +1875,7 @@ def smith_form(self): Laplacian, `D` is diagonal, and `U` and `V` are invertible over the integers. - OUTPUT: - - list of integer matrices + OUTPUT: list of integer matrices EXAMPLES:: @@ -1969,9 +1898,7 @@ def reorder_vertices(self): After reordering, vertex `u` comes before vertex `v` in the list of vertices if `u` is closer to the sink. - OUTPUT: - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -2047,11 +1974,9 @@ def jacobian_representatives(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - list of SandpileDivisor (or of lists representing divisors) + OUTPUT: list of SandpileDivisor (or of lists representing divisors) EXAMPLES: @@ -2103,11 +2028,9 @@ def picard_representatives(self, d, verbose=True): - ``d`` -- integer - - ``verbose`` -- (default: ``True``) boolean + - ``verbose`` -- boolean (default: ``True``) - OUTPUT: - - list of SandpileDivisors (or lists representing divisors) + OUTPUT: slist of SandpileDivisors (or lists representing divisors) EXAMPLES:: @@ -2138,10 +2061,7 @@ def stable_configs(self, smax=None): - ``smax`` -- (optional) SandpileConfig or list representing a SandpileConfig - - OUTPUT: - - generator for all stable configurations + OUTPUT: generator for all stable configurations EXAMPLES:: @@ -2173,13 +2093,13 @@ def markov_chain(self, state, distrib=None): INPUT: - - ``state`` -- SandpileConfig, SandpileDivisor, or list representing one of these + - ``state`` -- SandpileConfig, SandpileDivisor, or list representing + one of these - - ``distrib`` -- (optional) list of nonnegative numbers summing to 1 (representing a prob. dist.) - - OUTPUT: + - ``distrib`` -- (optional) list of nonnegative numbers summing to 1 + (representing a prob. dist.) - generator for Markov chain (see NOTE) + OUTPUT: generator for Markov chain (see NOTE) EXAMPLES:: @@ -2313,9 +2233,7 @@ def stationary_density(self): r""" The stationary density of the sandpile. - OUTPUT: - - rational number + OUTPUT: rational number EXAMPLES:: @@ -2350,9 +2268,7 @@ def all_k_div(self, k): - ``k`` -- integer - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -2366,9 +2282,7 @@ def zero_div(self): r""" The all-zero divisor. - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -2412,10 +2326,7 @@ def betti_complexes(self): r""" The support-complexes with non-trivial homology. (See NOTE.) - OUTPUT: - - list (of pairs [divisors, corresponding simplicial complex]) - + OUTPUT: list (of pairs [divisors, corresponding simplicial complex]) EXAMPLES:: @@ -2516,9 +2427,7 @@ def unsaturated_ideal(self): r""" The unsaturated, homogeneous toppling ideal. - OUTPUT: - - ideal + OUTPUT: ideal EXAMPLES:: @@ -2538,11 +2447,9 @@ def ideal(self, gens=False): INPUT: - - ``gens`` -- (default: ``False``) boolean + - ``gens`` -- boolean (default: ``False``) - OUTPUT: - - ideal or, optionally, the generators of an ideal + OUTPUT: ideal or, optionally, the generators of an ideal EXAMPLES:: @@ -2567,9 +2474,7 @@ def ring(self): r""" The ring containing the homogeneous toppling ideal. - OUTPUT: - - ring + OUTPUT: ring EXAMPLES:: @@ -2630,11 +2535,9 @@ def resolution(self, verbose=False): INPUT: - - ``verbose`` -- (default: ``False``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``False``) - free resolution of the toppling ideal + OUTPUT: free resolution of the toppling ideal EXAMPLES:: @@ -2670,7 +2573,7 @@ def resolution(self, verbose=False): def _set_groebner(self): r""" - Computes a Groebner basis for the homogeneous toppling ideal with + Compute a Groebner basis for the homogeneous toppling ideal with respect to the standard sandpile ordering (see ``ring``). EXAMPLES:: @@ -2687,9 +2590,7 @@ def groebner(self): A Groebner basis for the homogeneous toppling ideal. It is computed with respect to the standard sandpile ordering (see ``ring``). - OUTPUT: - - Groebner basis + OUTPUT: Groebner basis EXAMPLES:: @@ -2708,12 +2609,9 @@ def betti(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: - - Betti numbers for the sandpile + - ``verbose`` -- boolean (default: ``True``) + OUTPUT: Betti numbers for the sandpile EXAMPLES:: @@ -2740,9 +2638,7 @@ def solve(self): Approximations of the complex affine zeros of the sandpile ideal. - OUTPUT: - - list of complex numbers + OUTPUT: list of complex numbers EXAMPLES:: @@ -2813,9 +2709,7 @@ def points(self): Generators for the multiplicative group of zeros of the sandpile ideal. - OUTPUT: - - list of complex numbers + OUTPUT: list of complex numbers EXAMPLES: @@ -2839,9 +2733,7 @@ def symmetric_recurrents(self, orbits): - ``orbits`` -- list of lists partitioning the vertices - OUTPUT: - - list of recurrent configurations + OUTPUT: list of recurrent configurations EXAMPLES:: @@ -2896,11 +2788,9 @@ def help(verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - printed string + OUTPUT: printed string EXAMPLES:: @@ -2925,10 +2815,10 @@ def help(verbose=True): fire_unstable -- Fire all unstable vertices. fire_vertex -- Fire the given vertex. help -- List of SandpileConfig methods. - is_recurrent -- Is the configuration recurrent? - is_stable -- Is the configuration stable? - is_superstable -- Is the configuration superstable? - is_symmetric -- Is the configuration symmetric? + is_recurrent -- Return whether the configuration is recurrent. + is_stable -- Return whether the configuration is stable. + is_superstable -- Return whether the configuration is superstable. + is_symmetric -- Return whether the configuration is symmetric. order -- The order of the equivalent recurrent element. sandpile -- The configuration's underlying sandpile. show -- Show the configuration. @@ -2957,11 +2847,9 @@ def __init__(self, S, c): - ``S`` -- Sandpile - - ``c`` -- dict or list representing a configuration + - ``c`` -- dictionary or list representing a configuration - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3017,7 +2905,7 @@ def __setitem__(self, key, item): INPUT: - ``key``, ``item`` -- objects + - ``key``, ``item`` -- objects EXAMPLES:: @@ -3082,9 +2970,7 @@ def _set_deg(self): r""" Compute and store the degree of the configuration. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -3100,9 +2986,7 @@ def deg(self): r""" The degree of the configuration. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -3121,9 +3005,7 @@ def __add__(self, other): - ``other`` -- SandpileConfig - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -3145,9 +3027,7 @@ def __sub__(self, other): - ``other`` -- SandpileConfig - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -3170,9 +3050,7 @@ def __rsub__(self, other): - ``other`` -- SandpileConfig - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -3199,9 +3077,7 @@ def __neg__(self): r""" The additive inverse of the configuration. - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3223,9 +3099,7 @@ def __mul__(self, other): - ``other`` -- SandpileConfig or Integer - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3258,11 +3132,9 @@ def __rmul__(self, other): INPUT: - - ``other`` -- Integer - - OUTPUT: + - ``other`` -- integer - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3279,16 +3151,14 @@ def __rmul__(self, other): def __le__(self, other): r""" - ``True`` if every component of ``self`` is at most that of + Return ``True`` if every component of ``self`` is at most that of ``other``. INPUT: - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3311,16 +3181,14 @@ def __le__(self, other): def __lt__(self, other): r""" - ``True`` if every component of ``self`` is at most that + Return ``True`` if every component of ``self`` is at most that of ``other`` and the two configurations are not equal. INPUT: - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3338,16 +3206,14 @@ def __lt__(self, other): def __ge__(self, other): r""" - ``True`` if every component of ``self`` is at least that of + Return ``True`` if every component of ``self`` is at least that of ``other``. INPUT: - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3370,16 +3236,14 @@ def __ge__(self, other): def __gt__(self, other): r""" - ``True`` if every component of ``self`` is at least that + Return ``True`` if every component of ``self`` is at least that of ``other`` and the two configurations are not equal. INPUT: - ``other`` -- SandpileConfig - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3407,9 +3271,7 @@ def __pow__(self, k): - ``k`` -- SandpileConfig - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3448,9 +3310,7 @@ def __and__(self, other): - ``other`` -- SandpileConfig - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3471,9 +3331,7 @@ def sandpile(self): r""" The configuration's underlying sandpile. - OUTPUT: - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -3492,9 +3350,7 @@ def values(self): The list is sorted in the order of the vertices. - OUTPUT: - - list of integers + OUTPUT: list of integers boolean @@ -3515,9 +3371,7 @@ def dualize(self): r""" The difference with the maximal stable configuration. - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3540,9 +3394,7 @@ def fire_vertex(self, v): - ``v`` -- vertex - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3567,9 +3419,7 @@ def fire_script(self, sigma): - ``sigma`` -- SandpileConfig or (list or dict representing a SandpileConfig) - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3598,9 +3448,7 @@ def unstable(self): r""" The unstable vertices. - OUTPUT: - - list of vertices + OUTPUT: list of vertices EXAMPLES:: @@ -3616,9 +3464,7 @@ def fire_unstable(self): r""" Fire all unstable vertices. - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3637,7 +3483,7 @@ def fire_unstable(self): def _set_stabilize(self): r""" - Computes the stabilized configuration and its firing vector. + Compute the stabilized configuration and its firing vector. EXAMPLES:: @@ -3669,11 +3515,9 @@ def stabilize(self, with_firing_vector=False): INPUT: - - ``with_firing_vector`` -- (default: ``False``) boolean + - ``with_firing_vector`` -- boolean (default: ``False``) - OUTPUT: - - ``SandpileConfig`` or ``[SandpileConfig, firing_vector]`` + OUTPUT: ``SandpileConfig`` or ``[SandpileConfig, firing_vector]`` EXAMPLES:: @@ -3700,9 +3544,7 @@ def __invert__(self): r""" The stabilized configuration. - OUTPUT: - - ``SandpileConfig`` + OUTPUT: ``SandpileConfig`` Returns the stabilized configuration. @@ -3719,9 +3561,7 @@ def support(self): r""" The vertices containing sand. - OUTPUT: - - list - support of the configuration + OUTPUT: list - support of the configuration EXAMPLES:: @@ -3744,9 +3584,7 @@ def add_random(self, distrib=None): - ``distrib`` -- (optional) list of nonnegative numbers summing to 1 (representing a prob. dist.) - OUTPUT: - - SandpileConfig + OUTPUT: SandpileConfig EXAMPLES:: @@ -3819,9 +3657,7 @@ def order(self): r""" The order of the equivalent recurrent element. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -3845,11 +3681,9 @@ def order(self): def is_stable(self): r""" - Is the configuration stable? - - OUTPUT: + Return whether the configuration is stable. - boolean + OUTPUT: boolean EXAMPLES:: @@ -3868,7 +3702,7 @@ def is_stable(self): def _set_equivalent_recurrent(self): r""" - Sets the equivalent recurrent configuration and the corresponding + Set the equivalent recurrent configuration and the corresponding firing vector. EXAMPLES:: @@ -3901,12 +3735,9 @@ def equivalent_recurrent(self, with_firing_vector=False): INPUT: - - ``with_firing_vector`` -- (default: ``False``) boolean - - OUTPUT: - - SandpileConfig or [SandpileConfig, firing_vector] + - ``with_firing_vector`` -- boolean (default: ``False``) + OUTPUT: SandpileConfig or [SandpileConfig, firing_vector] EXAMPLES:: @@ -3934,7 +3765,7 @@ def equivalent_recurrent(self, with_firing_vector=False): def _set_is_recurrent(self): r""" - Computes and stores whether the configuration is recurrent. + Compute and store whether the configuration is recurrent. EXAMPLES:: @@ -3956,11 +3787,9 @@ def _set_is_recurrent(self): def is_recurrent(self): r""" - Is the configuration recurrent? + Return whether the configuration is recurrent. - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -3974,13 +3803,10 @@ def is_recurrent(self): def _set_equivalent_superstable(self): r""" - Sets the superstable configuration equivalent to the given + Set the superstable configuration equivalent to the given configuration and its corresponding firing vector. - OUTPUT: - - [configuration, firing_vector] - + OUTPUT: [configuration, firing_vector] EXAMPLES:: @@ -4000,12 +3826,9 @@ def equivalent_superstable(self, with_firing_vector=False): INPUT: - - ``with_firing_vector`` -- (default: ``False``) boolean - - OUTPUT: - - SandpileConfig or [SandpileConfig, firing_vector] + - ``with_firing_vector`` -- boolean (default: ``False``) + OUTPUT: SandpileConfig or [SandpileConfig, firing_vector] EXAMPLES:: @@ -4033,11 +3856,9 @@ def equivalent_superstable(self, with_firing_vector=False): def _set_is_superstable(self): r""" - Computes and stores whether ``config`` is superstable. + Compute and store whether ``config`` is superstable. - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4056,11 +3877,9 @@ def _set_is_superstable(self): def is_superstable(self): r""" - Is the configuration superstable? + Return whether the configuration is superstable. - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4072,17 +3891,15 @@ def is_superstable(self): def is_symmetric(self, orbits) -> bool: r""" - Is the configuration symmetric? Return ``True`` if the values of the + Return whether the configuration is symmetric. Return ``True`` if the values of the configuration are constant over the vertices in each sublist of ``orbits``. INPUT: - - ``orbits`` -- list of lists of vertices + - ``orbits`` -- list of lists of vertices - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4105,9 +3922,7 @@ def burst_size(self, v): - ``v`` -- vertex - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -4142,11 +3957,13 @@ def show(self, sink=True, colors=True, heights=False, directed=None, **kwds): INPUT: - - ``sink`` -- (default: ``True``) whether to show the sink + - ``sink`` -- boolean (default: ``True``); whether to show the sink - - ``colors`` -- (default: ``True``) whether to color-code the amount of sand on each vertex + - ``colors`` -- boolean (default: ``True``); whether to color-code the + amount of sand on each vertex - - ``heights`` -- (default: ``False``) whether to label each vertex with the amount of sand + - ``heights`` -- boolean (default: ``False``); whether to label each + vertex with the amount of sand - ``directed`` -- (optional) whether to draw directed edges @@ -4219,11 +4036,9 @@ def help(verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - printed string + OUTPUT: printed string EXAMPLES:: @@ -4241,11 +4056,11 @@ def help(verbose=True): fire_unstable -- Fire all unstable vertices. fire_vertex -- Fire the given vertex. help -- List of SandpileDivisor methods. - is_alive -- Is the divisor stabilizable? - is_linearly_equivalent -- Is the given divisor linearly equivalent? - is_q_reduced -- Is the divisor q-reduced? - is_symmetric -- Is the divisor symmetric? - is_weierstrass_pt -- Is the given vertex a Weierstrass point? + is_alive -- Return whether the divisor is stabilizable. + is_linearly_equivalent -- Return whether the given divisor is linearly equivalent. + is_q_reduced -- Return whether the divisor is q-reduced. + is_symmetric -- Return whether the divisor is symmetric. + is_weierstrass_pt -- Return whether the given vertex is a Weierstrass point. polytope -- The polytope determining the complete linear system. polytope_integer_pts -- The integer points inside divisor's polytope. q_reduced -- The linearly equivalent q-reduced divisor. @@ -4275,11 +4090,9 @@ def __init__(self, S, D): - ``S`` -- Sandpile - - ``D`` -- dict or list representing a divisor - - OUTPUT: + - ``D`` -- dictionary or list representing a divisor - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4307,7 +4120,7 @@ def __deepcopy__(self, memo): INPUT: - memo -- (optional) dict + - ``memo`` -- (optional) dictionary EXAMPLES:: @@ -4330,7 +4143,7 @@ def __setitem__(self, key, item): INPUT: - ``key``, ``item`` -- objects + - ``key``, ``item`` -- objects EXAMPLES:: @@ -4422,9 +4235,7 @@ def _set_deg(self): r""" Compute and store the degree of the divisor. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -4440,9 +4251,7 @@ def deg(self): r""" The degree of the divisor. - OUTPUT: - - integer + OUTPUT: integer EXAMPLES:: @@ -4461,9 +4270,7 @@ def __add__(self, other): - ``other`` -- SandpileDivisor - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -4485,9 +4292,7 @@ def __mul__(self, other): - ``other`` -- integer - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4508,11 +4313,9 @@ def __rmul__(self, other): INPUT: - - ``other`` -- Integer - - OUTPUT: + - ``other`` -- integer - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4535,9 +4338,7 @@ def __radd__(self, other): - ``other`` -- SandpileDivisor - OUTPUT: - - sum of ``self`` and ``other`` + OUTPUT: sum of ``self`` and ``other`` EXAMPLES:: @@ -4560,9 +4361,7 @@ def __sub__(self, other): - ``other`` -- SandpileDivisor - OUTPUT: - - Difference of ``self`` and ``other`` + OUTPUT: difference of ``self`` and ``other`` EXAMPLES:: @@ -4585,9 +4384,7 @@ def __rsub__(self, other): - ``other`` -- SandpileDivisor - OUTPUT: - - Difference of ``self`` and ``other`` + OUTPUT: difference of ``self`` and ``other`` EXAMPLES:: @@ -4608,9 +4405,7 @@ def __neg__(self): r""" The additive inverse of the divisor. - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4623,16 +4418,14 @@ def __neg__(self): def __le__(self, other): r""" - ``True`` if every component of ``self`` is at most that of + Return ``True`` if every component of ``self`` is at most that of ``other``. INPUT: - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4655,16 +4448,14 @@ def __le__(self, other): def __lt__(self, other): r""" - ``True`` if every component of ``self`` is at most that + Return ``True`` if every component of ``self`` is at most that of ``other`` and the two divisors are not equal. INPUT: - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4682,16 +4473,14 @@ def __lt__(self, other): def __ge__(self, other): r""" - ``True`` if every component of ``self`` is at least that of + Return ``True`` if every component of ``self`` is at least that of ``other``. INPUT: - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4714,16 +4503,14 @@ def __ge__(self, other): def __gt__(self, other): r""" - ``True`` if every component of ``self`` is at least that + Return ``True`` if every component of ``self`` is at least that of ``other`` and the two divisors are not equal. INPUT: - ``other`` -- SandpileDivisor - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4743,9 +4530,7 @@ def sandpile(self): r""" The divisor's underlying sandpile. - OUTPUT: - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -4764,9 +4549,7 @@ def values(self): The list is sorted in the order of the vertices. - OUTPUT: - - list of integers + OUTPUT: list of integers boolean @@ -4787,9 +4570,7 @@ def dualize(self): r""" The difference with the maximal stable divisor. - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4810,9 +4591,7 @@ def fire_vertex(self, v): - ``v`` -- vertex - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4836,9 +4615,7 @@ def fire_script(self, sigma): - ``sigma`` -- SandpileDivisor or (list or dict representing a SandpileDivisor) - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4866,9 +4643,7 @@ def unstable(self): r""" The unstable vertices. - OUTPUT: - - list of vertices + OUTPUT: list of vertices EXAMPLES:: @@ -4884,9 +4659,7 @@ def fire_unstable(self): r""" Fire all unstable vertices. - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -4927,11 +4700,9 @@ def q_reduced(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - SandpileDivisor or list representing SandpileDivisor + OUTPUT: SandpileDivisor or list representing SandpileDivisor EXAMPLES:: @@ -4954,12 +4725,10 @@ def q_reduced(self, verbose=True): def is_q_reduced(self): r""" - Is the divisor `q`-reduced? This would mean that `self = c + kq` where + Return whether the divisor is `q`-reduced. This would mean that `self = c + kq` where `c` is superstable, `k` is an integer, and `q` is the sink vertex. - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -4994,18 +4763,16 @@ def is_q_reduced(self): def is_linearly_equivalent(self, D, with_firing_vector=False): r""" - Is the given divisor linearly equivalent? Optionally, returns the + Return whether the given divisor is linearly equivalent. Optionally, returns the firing vector. (See NOTE.) INPUT: - ``D`` -- SandpileDivisor or list, tuple, etc. representing a divisor - - ``with_firing_vector`` -- (default: ``False``) boolean + - ``with_firing_vector`` -- boolean (default: ``False``) - OUTPUT: - - boolean or integer vector + OUTPUT: boolean or integer vector EXAMPLES:: @@ -5068,9 +4835,7 @@ def simulate_threshold(self, distrib=None): - ``distrib`` -- (optional) list of nonnegative numbers representing a probability distribution on the vertices - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -5105,11 +4870,11 @@ def simulate_threshold(self, distrib=None): def _set_linear_system(self): r""" - Computes and stores the complete linear system of a divisor. + Compute and store the complete linear system of a divisor. OUTPUT: - dict - ``{num_homog: int, homog:list, num_inhomog:int, inhomog:list}`` + dictionary; ``{num_homog: int, homog:list, num_inhomog:int, inhomog:list}`` EXAMPLES:: @@ -5219,9 +4984,7 @@ def polytope(self): r""" The polytope determining the complete linear system. - OUTPUT: - - polytope + OUTPUT: polytope EXAMPLES:: @@ -5270,9 +5033,7 @@ def polytope_integer_pts(self): here is the one determining the divisor's complete linear system (see the documentation for ``polytope``). - OUTPUT: - - tuple of integer vectors + OUTPUT: tuple of integer vectors EXAMPLES:: @@ -5319,13 +5080,11 @@ def effective_div(self, verbose=True, with_firing_vectors=False): INPUT: - - ``verbose`` -- (default: ``True``) boolean + - ``verbose`` -- boolean (default: ``True``) - - ``with_firing_vectors`` -- (default: ``False``) boolean - - OUTPUT: + - ``with_firing_vectors`` -- boolean (default: ``False``) - list (of divisors) + OUTPUT: list (of divisors) EXAMPLES:: @@ -5392,7 +5151,7 @@ def _set_rank(self, set_witness=False): INPUT: - - ``verbose`` -- (default: ``False``) boolean + - ``verbose`` -- boolean (default: ``False``) EXAMPLES:: @@ -5463,11 +5222,9 @@ def rank(self, with_witness=False): INPUT: - - ``with_witness`` -- (default: ``False``) boolean + - ``with_witness`` -- boolean (default: ``False``) - OUTPUT: - - integer or (integer, SandpileDivisor) + OUTPUT: integer or (integer, SandpileDivisor) EXAMPLES:: @@ -5523,12 +5280,12 @@ def rank(self, with_witness=False): def _set_r_of_D(self, verbose=False): r""" - Computes `r(D)` and an effective divisor `F` such that `|D - F|` is + Compute `r(D)` and an effective divisor `F` such that `|D - F|` is empty. INPUT: - - ``verbose`` -- (default: ``False``) boolean + - ``verbose`` -- boolean (default: ``False``) EXAMPLES:: @@ -5579,9 +5336,7 @@ def weierstrass_rank_seq(self, v='sink'): - ``v`` -- (default: ``sink``) vertex - OUTPUT: - - tuple of int + OUTPUT: tuple of int EXAMPLES:: @@ -5619,11 +5374,9 @@ def weierstrass_gap_seq(self, v='sink', weight=True): - ``v`` -- (default: ``sink``) vertex - - ``weight`` -- (default: ``True``) boolean - - OUTPUT: + - ``weight`` -- boolean (default: ``True``) - list or (list of list) of integers + OUTPUT: list or (list of list) of integers EXAMPLES:: @@ -5658,15 +5411,13 @@ def weierstrass_gap_seq(self, v='sink', weight=True): def is_weierstrass_pt(self, v='sink'): r""" - Is the given vertex a Weierstrass point? + Return whether the given vertex is a Weierstrass point. INPUT: - ``v`` -- (default: ``sink``) vertex - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -5707,15 +5458,14 @@ def _set_weierstrass_pts(self): def weierstrass_pts(self, with_rank_seq=False): r""" - The Weierstrass points (vertices). Optionally, return the corresponding rank sequences. + The Weierstrass points (vertices). Optionally, return the corresponding + rank sequences. INPUT: - - ``with_rank_seq`` -- (default: ``False``) boolean + - ``with_rank_seq`` -- boolean (default: ``False``) - OUTPUT: - - tuple of vertices or list of (vertex, rank sequence) + OUTPUT: tuple of vertices or list of (vertex, rank sequence) EXAMPLES:: @@ -5745,11 +5495,9 @@ def weierstrass_div(self, verbose=True): INPUT: - - ``verbose`` -- (default: ``True``) boolean - - OUTPUT: + - ``verbose`` -- boolean (default: ``True``) - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -5779,9 +5527,7 @@ def support(self): r""" List of vertices at which the divisor is nonzero. - OUTPUT: - - list representing the support of the divisor + OUTPUT: list representing the support of the divisor EXAMPLES:: @@ -5796,7 +5542,7 @@ def support(self): def _set_Dcomplex(self): r""" - Computes the simplicial complex determined by the supports of the + Compute the simplicial complex determined by the supports of the linearly equivalent effective divisors. EXAMPLES:: @@ -5834,9 +5580,7 @@ def Dcomplex(self): r""" The support-complex. (See NOTE.) - OUTPUT: - - simplicial complex + OUTPUT: simplicial complex EXAMPLES:: @@ -5861,9 +5605,7 @@ def betti(self): r""" The Betti numbers for the support-complex. (See NOTE.) - OUTPUT: - - dictionary of integers + OUTPUT: dictionary of integers EXAMPLES:: @@ -5887,9 +5629,7 @@ def add_random(self, distrib=None): - ``distrib`` -- (optional) list of nonnegative numbers representing a probability distribution on the vertices - OUTPUT: - - SandpileDivisor + OUTPUT: SandpileDivisor EXAMPLES:: @@ -5917,7 +5657,7 @@ def add_random(self, distrib=None): def is_symmetric(self, orbits): r""" - Is the divisor symmetric? Return ``True`` if the values of the + Return whether the divisor is symmetric. Return ``True`` if the values of the configuration are constant over the vertices in each sublist of ``orbits``. @@ -5925,9 +5665,7 @@ def is_symmetric(self, orbits): - ``orbits`` -- list of lists of vertices - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -5974,17 +5712,15 @@ def _set_life(self): def is_alive(self, cycle=False): r""" - Is the divisor stabilizable? In other words, will the divisor stabilize + Return whether the divisor is stabilizable. In other words, will the divisor stabilize under repeated firings of all unstable vertices? Optionally returns the resulting cycle. INPUT: - - ``cycle`` -- (default: ``False``) boolean + - ``cycle`` -- boolean (default: ``False``) - OUTPUT: - - boolean or optionally, a list of SandpileDivisors + OUTPUT: boolean or optionally, a list of SandpileDivisors EXAMPLES:: @@ -6028,7 +5764,7 @@ def stabilize(self, with_firing_vector=False): INPUT: - - ``with_firing_vector`` -- (default: ``False``) boolean + - ``with_firing_vector`` -- boolean (default: ``False``) EXAMPLES:: @@ -6049,7 +5785,8 @@ def show(self, heights=True, directed=None, **kwds): INPUT: - - ``heights`` -- (default: ``True``) whether to label each vertex with the amount of sand + - ``heights`` -- boolean (default: ``True``); whether to label each + vertex with the amount of sand - ``directed`` -- (optional) whether to draw directed edges @@ -6086,16 +5823,14 @@ def show(self, heights=True, directed=None, **kwds): def sandlib(selector=None): r""" - Returns the sandpile identified by ``selector``. If no argument is + Return the sandpile identified by ``selector``. If no argument is given, a description of the sandpiles in the sandlib is printed. INPUT: - ``selector`` -- (optional) identifier or None - OUTPUT: - - sandpile or description + OUTPUT: Sandpile or description EXAMPLES:: @@ -6172,9 +5907,7 @@ def triangle_sandpile(n): - ``n`` -- integer - OUTPUT: - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -6218,9 +5951,7 @@ def aztec_sandpile(n): - ``n`` -- integer - OUTPUT: - - dictionary for the aztec diamond graph + OUTPUT: dictionary for the aztec diamond graph EXAMPLES:: @@ -6274,14 +6005,11 @@ def glue_graphs(g, h, glue_g, glue_h): INPUT: - - ``g``, ``h`` -- dictionaries for directed multigraphs - - - ``glue_h``, ``glue_g`` -- dictionaries for a vertex - - OUTPUT: + - ``g``, ``h`` -- dictionaries for directed multigraphs - dictionary for a directed multigraph + - ``glue_h``, ``glue_g`` -- dictionaries for a vertex + OUTPUT: dictionary for a directed multigraph EXAMPLES:: @@ -6357,7 +6085,7 @@ def glue_graphs(g, h, glue_g, glue_h): def firing_graph(S, eff): r""" - Creates a digraph with divisors as vertices and edges between two divisors + Create a digraph with divisors as vertices and edges between two divisors `D` and `E` if firing a single vertex in `D` gives `E`. INPUT: @@ -6366,9 +6094,7 @@ def firing_graph(S, eff): - ``eff`` -- list of divisors - OUTPUT: - - DiGraph + OUTPUT: DiGraph EXAMPLES:: @@ -6394,7 +6120,7 @@ def firing_graph(S, eff): def parallel_firing_graph(S, eff): r""" - Creates a digraph with divisors as vertices and edges between two divisors + Create a digraph with divisors as vertices and edges between two divisors `D` and `E` if firing all unstable vertices in `D` gives `E`. INPUT: @@ -6403,9 +6129,7 @@ def parallel_firing_graph(S, eff): - ``eff`` -- list of divisors - OUTPUT: - - DiGraph + OUTPUT: DiGraph EXAMPLES:: @@ -6442,9 +6166,7 @@ def admissible_partitions(S, k): - ``k`` -- integer - OUTPUT: - - partitions + OUTPUT: partitions EXAMPLES:: @@ -6496,9 +6218,7 @@ def partition_sandpile(S, p): - ``p`` -- partition of the vertices of ``S`` - OUTPUT: - - Sandpile + OUTPUT: Sandpile EXAMPLES:: @@ -6542,9 +6262,7 @@ def min_cycles(G, v): - ``v`` -- vertex of ``G`` - OUTPUT: - - list of lists of vertices + OUTPUT: list of lists of vertices EXAMPLES:: @@ -6560,16 +6278,14 @@ def min_cycles(G, v): def wilmes_algorithm(M): r""" - Computes an integer matrix `L` with the same integer row span as `M` and + Compute an integer matrix `L` with the same integer row span as `M` and such that `L` is the reduced Laplacian of a directed multigraph. INPUT: - ``M`` -- square integer matrix of full rank - OUTPUT: - - integer matrix (``L``) + OUTPUT: integer matrix (``L``) EXAMPLES:: diff --git a/src/sage/sat/boolean_polynomials.py b/src/sage/sat/boolean_polynomials.py index d321366d0a0..bad6b33d4d3 100644 --- a/src/sage/sat/boolean_polynomials.py +++ b/src/sage/sat/boolean_polynomials.py @@ -50,7 +50,7 @@ def solve(F, converter=None, solver=None, n=1, target_variables=None, **kwds): ``None`` then :class:`sage.sat.solvers.cryptominisat.CryptoMiniSat` is used to construct a new converter. (default: ``None``) - - ``target_variables`` -- a list of variables. The elements of the list are + - ``target_variables`` -- list of variables. The elements of the list are used to exclude a particular combination of variable assignments of a solution from any further solution. Furthermore ``target_variables`` denotes which variable-value pairs appear in the solutions. If @@ -59,14 +59,14 @@ def solve(F, converter=None, solver=None, n=1, target_variables=None, **kwds): (default: ``None``) - ``**kwds`` -- parameters can be passed to the converter and the - solver by prefixing them with ``c_`` and ``s_`` respectively. For - example, to increase CryptoMiniSat's verbosity level, pass - ``s_verbosity=1``. + solver by prefixing them with ``c_`` and ``s_`` respectively. For + example, to increase CryptoMiniSat's verbosity level, pass + ``s_verbosity=1``. OUTPUT: - A list of dictionaries, each of which contains a variable - assignment solving ``F``. + A list of dictionaries, each of which contains a variable assignment + solving ``F``. EXAMPLES: @@ -335,9 +335,7 @@ def learn(F, converter=None, solver=None, max_learnt_length=3, interreduction=Fa ``s_`` respectively. For example, to increase CryptoMiniSat's verbosity level, pass ``s_verbosity=1``. - OUTPUT: - - A sequence of Boolean polynomials. + OUTPUT: a sequence of Boolean polynomials EXAMPLES:: diff --git a/src/sage/sat/converters/polybori.py b/src/sage/sat/converters/polybori.py index f45e9740475..d57f1c12c02 100644 --- a/src/sage/sat/converters/polybori.py +++ b/src/sage/sat/converters/polybori.py @@ -257,7 +257,6 @@ def clauses_sparse(self, f): - ``f`` -- a :class:`sage.rings.polynomial.pbori.BooleanPolynomial` - EXAMPLES:: sage: B. = BooleanPolynomialRing() @@ -347,13 +346,13 @@ def clauses_dense(self, f): @cached_method def monomial(self, m): """ - Return SAT variable for ``m`` + Return SAT variable for ``m``. INPUT: - - ``m`` -- a monomial. + - ``m`` -- a monomial - OUTPUT: An index for a SAT variable corresponding to ``m``. + OUTPUT: an index for a SAT variable corresponding to ``m`` EXAMPLES:: @@ -383,7 +382,7 @@ def monomial(self, m): sage: e.phi [None, a, b, c, a*b, a*b*c] - .. note:: + .. NOTE:: For correctness, this function is cached. """ @@ -443,7 +442,7 @@ def split_xor(self, monomial_list, equal_zero): INPUT: - - ``monomial_list`` -- a list of monomials + - ``monomial_list`` -- list of monomials - ``equal_zero`` -- is the constant coefficient zero? EXAMPLES:: @@ -543,8 +542,7 @@ def __call__(self, F): - ``F`` -- an iterable of :class:`sage.rings.polynomial.pbori.BooleanPolynomial` - OUTPUT: An inverse map int -> variable - + OUTPUT: an inverse map int -> variable EXAMPLES:: @@ -582,7 +580,7 @@ def __call__(self, F): def to_polynomial(self, c): """ - Convert clause to :class:`sage.rings.polynomial.pbori.BooleanPolynomial` + Convert clause to :class:`sage.rings.polynomial.pbori.BooleanPolynomial`. INPUT: diff --git a/src/sage/sat/solvers/cryptominisat.py b/src/sage/sat/solvers/cryptominisat.py index dfb1295195d..e23c3491ccc 100644 --- a/src/sage/sat/solvers/cryptominisat.py +++ b/src/sage/sat/solvers/cryptominisat.py @@ -33,12 +33,12 @@ class CryptoMiniSat(SatSolver): INPUT: - - ``verbosity`` -- an integer between 0 and 15 (default: 0). Verbosity. + - ``verbosity`` -- integer between 0 and 15 (default: 0) - - ``confl_limit`` -- an integer (default: ``None``). Abort after this many + - ``confl_limit`` -- integer (default: ``None``); abort after this many conflicts. If set to ``None``, never aborts. - - ``threads`` -- an integer (default: None). The number of thread to + - ``threads`` -- integer (default: ``None``); the number of thread to use. If set to ``None``, the number of threads used corresponds to the number of cpus. @@ -74,7 +74,7 @@ def var(self, decision=None): INPUT: - - ``decision`` -- accepted for compatibility with other solvers, ignored. + - ``decision`` -- accepted for compatibility with other solvers; ignored EXAMPLES:: @@ -119,9 +119,9 @@ def add_clause(self, lits): INPUT: - - ``lits`` -- a tuple of nonzero integers. + - ``lits`` -- tuple of nonzero integers - .. note:: + .. NOTE:: If any element ``e`` in ``lits`` has ``abs(e)`` greater than the number of variables generated so far, then new @@ -147,10 +147,10 @@ def add_xor_clause(self, lits, rhs=True): INPUT: - - ``lits`` -- a tuple of positive integers. + - ``lits`` -- tuple of positive integers - - ``rhs`` -- boolean (default: ``True``). Whether this XOR clause should - be evaluated to ``True`` or ``False``. + - ``rhs`` -- boolean (default: ``True``); whether this XOR clause should + be evaluated to ``True`` or ``False`` EXAMPLES:: diff --git a/src/sage/sat/solvers/dimacs.py b/src/sage/sat/solvers/dimacs.py index 1288a69456d..424442930de 100644 --- a/src/sage/sat/solvers/dimacs.py +++ b/src/sage/sat/solvers/dimacs.py @@ -6,7 +6,7 @@ Currently, interfaces to **RSat** and **Glucose** are included by default. -.. note:: +.. NOTE:: Our SAT solver interfaces are 1-based, i.e., literals start at 1. This is consistent with the popular DIMACS format for SAT solving but not with Pythion's 0-based convention. However, this @@ -42,7 +42,7 @@ class DIMACS(SatSolver): """ Generic DIMACS Solver. - .. note:: + .. NOTE:: Usually, users won't have to use this class directly but some class which inherits from this class. @@ -73,8 +73,7 @@ def __init__(self, command=None, filename=None, verbosity=0, **kwds): - ``verbosity`` -- a verbosity level, where zero means silent and anything else means verbose output. (default: ``0``) - - ``**kwds`` -- accepted for compatibility with other solves, - ignored. + - ``**kwds`` -- accepted for compatibility with other solvers; ignored TESTS:: @@ -148,7 +147,7 @@ def var(self, decision=None): INPUT: - - ``decision`` -- accepted for compatibility with other solvers, ignored. + - ``decision`` -- accepted for compatibility with other solvers; ignored EXAMPLES:: @@ -183,9 +182,9 @@ def add_clause(self, lits): INPUT: - - ``lits`` -- a tuple of integers != 0 + - ``lits`` -- tuple of nonzero integers - .. note:: + .. NOTE:: If any element ``e`` in ``lits`` has ``abs(e)`` greater than the number of variables generated so far, then new @@ -326,7 +325,7 @@ def render_dimacs(clauses, filename, nlits): INPUT: - - ``clauses`` -- a list of clauses, either in simple format as a list of + - ``clauses`` -- list of clauses, either in simple format as a list of literals or in extended format for CryptoMiniSat: a tuple of literals, ``is_xor`` and ``rhs``. @@ -520,7 +519,6 @@ def __call__(self, assumptions=None): ....: except ZeroDivisionError: ....: pass sage: solve_sat(F, solver=sage.sat.solvers.RSat) # optional - rsat, needs sage.rings.finite_rings sage.rings.polynomial.pbori - """ if assumptions is not None: raise NotImplementedError("Assumptions are not supported for DIMACS based solvers.") @@ -576,7 +574,6 @@ class RSat(DIMACS): sage: solver.add_clause((-1,-2)) sage: solver() # optional - rsat False - """ command = "rsat {input} -v -s" @@ -642,7 +639,6 @@ class Glucose(DIMACS): c... s SATISFIABLE v -1 -2 ... 100 0 - """ command = "glucose -verb=0 -model {input}" @@ -706,13 +702,12 @@ class GlucoseSyrup(DIMACS): c... s SATISFIABLE v -1 -2 ... 100 0 - """ command = "glucose-syrup -model -verb=0 {input}" class Kissat(DIMACS): """ - An instance of the Kissat SAT solver + An instance of the Kissat SAT solver. For information on Kissat see: http://fmv.jku.at/kissat/ @@ -770,7 +765,6 @@ class Kissat(DIMACS): v ... v ... v ... 100 0 - """ command = "kissat -q {input}" diff --git a/src/sage/sat/solvers/picosat.py b/src/sage/sat/solvers/picosat.py index 89e82170b7f..fb8c10afd80 100644 --- a/src/sage/sat/solvers/picosat.py +++ b/src/sage/sat/solvers/picosat.py @@ -32,9 +32,9 @@ class PicoSAT(SatSolver): INPUT: - - ``verbosity`` -- an integer between 0 and 2 (default: 0); verbosity + - ``verbosity`` -- integer between 0 and 2 (default: 0) - - ``prop_limit`` -- an integer (default: 0); the propagation limit + - ``prop_limit`` -- integer (default: 0); the propagation limit EXAMPLES:: @@ -112,7 +112,7 @@ def add_clause(self, lits): INPUT: - - ``lits`` -- a tuple of nonzero integers + - ``lits`` -- tuple of nonzero integers .. NOTE:: diff --git a/src/sage/sat/solvers/sat_lp.py b/src/sage/sat/solvers/sat_lp.py index de9f8b082c7..76446e1f0f8 100644 --- a/src/sage/sat/solvers/sat_lp.py +++ b/src/sage/sat/solvers/sat_lp.py @@ -13,11 +13,11 @@ class SatLP(SatSolver): def __init__(self, solver=None, verbose=0, *, integrality_tolerance=1e-3): r""" - Initializes the instance + Initialize the instance. INPUT: - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specify a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -25,15 +25,15 @@ def __init__(self, solver=None, verbose=0, *, integrality_tolerance=1e-3): of the class :class:`MixedIntegerLinearProgram `. - - ``verbose`` -- integer (default: ``0``). Sets the level of verbosity + - ``verbose`` -- integer (default: 0); sets the level of verbosity of the LP solver. Set to 0 by default, which means quiet. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` EXAMPLES:: - sage: S=SAT(solver="LP"); S + sage: S=SAT(solver='LP'); S an ILP-based SAT Solver """ SatSolver.__init__(self) @@ -48,7 +48,7 @@ def var(self): EXAMPLES:: - sage: S=SAT(solver="LP"); S + sage: S=SAT(solver='LP'); S an ILP-based SAT Solver sage: S.var() 1 @@ -65,7 +65,7 @@ def nvars(self): EXAMPLES:: - sage: S=SAT(solver="LP"); S + sage: S=SAT(solver='LP'); S an ILP-based SAT Solver sage: S.var() 1 @@ -82,9 +82,9 @@ def add_clause(self, lits): INPUT: - - ``lits`` -- a tuple of integers != 0 + - ``lits`` -- tuple of nonzero integers - .. note:: + .. NOTE:: If any element ``e`` in ``lits`` has ``abs(e)`` greater than the number of variables generated so far, then new @@ -92,7 +92,7 @@ def add_clause(self, lits): EXAMPLES:: - sage: S=SAT(solver="LP"); S + sage: S=SAT(solver='LP'); S an ILP-based SAT Solver sage: for u,v in graphs.CycleGraph(6).edges(sort=False, labels=False): ....: u,v = u+1,v+1 @@ -120,7 +120,7 @@ def __call__(self): EXAMPLES:: sage: def is_bipartite_SAT(G): - ....: S=SAT(solver="LP"); S + ....: S=SAT(solver='LP'); S ....: for u,v in G.edges(sort=False, labels=False): ....: u,v = u+1,v+1 ....: S.add_clause((u,v)) @@ -148,7 +148,7 @@ def __repr__(self): """ TESTS:: - sage: S=SAT(solver="LP"); S + sage: S=SAT(solver='LP'); S an ILP-based SAT Solver """ return "an ILP-based SAT Solver" diff --git a/src/sage/sat/solvers/satsolver.pyx b/src/sage/sat/solvers/satsolver.pyx index 7b63a1ee87d..9de7b4a9ca7 100644 --- a/src/sage/sat/solvers/satsolver.pyx +++ b/src/sage/sat/solvers/satsolver.pyx @@ -67,7 +67,7 @@ cdef class SatSolver: INPUT: - - ``lits`` -- a tuple of integers != 0 + - ``lits`` -- tuple of nonzero integers .. NOTE:: @@ -111,7 +111,7 @@ cdef class SatSolver: INPUT: - - ``filename`` -- The name of a file as a string or a file object + - ``filename`` -- the name of a file as a string or a file object EXAMPLES:: @@ -269,7 +269,6 @@ cdef class SatSolver: If ``filename`` points to a writable file, then the list of original clauses is written to that file in DIMACS format. - EXAMPLES:: sage: from sage.sat.solvers.satsolver import SatSolver @@ -320,58 +319,58 @@ def SAT(solver=None, *args, **kwds): INPUT: - - ``solver`` (string) -- select a solver. Admissible values are: + - ``solver`` -- string; select a solver. Admissible values are: - - ``"cryptominisat"`` -- note that the pycryptosat package must be - installed. + - ``'cryptominisat'`` -- note that the pycryptosat package must be + installed - - ``"picosat"`` -- note that the pycosat package must be installed. + - ``'picosat'`` -- note that the pycosat package must be installed - - ``"glucose"`` -- note that the glucose package must be installed. + - ``'glucose'`` -- note that the glucose package must be installed - - ``"glucose-syrup"`` -- note that the glucose package must be installed. + - ``'glucose-syrup'`` -- note that the glucose package must be installed - - ``"LP"`` -- use :class:`~sage.sat.solvers.sat_lp.SatLP` to solve the - SAT instance. + - ``'LP'`` -- use :class:`~sage.sat.solvers.sat_lp.SatLP` to solve the + SAT instance - - ``None`` (default) -- use CryptoMiniSat if available, else PicoSAT if - available, and a LP solver otherwise. + - ``None`` -- default; use CryptoMiniSat if available, else PicoSAT if + available, and a LP solver otherwise EXAMPLES:: - sage: SAT(solver="LP") # needs sage.numerical.mip + sage: SAT(solver='LP') # needs sage.numerical.mip an ILP-based SAT Solver TESTS:: - sage: SAT(solver="Wouhouuuuuu") + sage: SAT(solver='Wouhouuuuuu') Traceback (most recent call last): ... ValueError: Solver 'Wouhouuuuuu' is not available Forcing CryptoMiniSat:: - sage: SAT(solver="cryptominisat") # optional - pycryptosat + sage: SAT(solver='cryptominisat') # optional - pycryptosat CryptoMiniSat solver: 0 variables, 0 clauses. Forcing PicoSat:: - sage: SAT(solver="picosat") # optional - pycosat + sage: SAT(solver='picosat') # optional - pycosat PicoSAT solver: 0 variables, 0 clauses. Forcing Glucose:: - sage: SAT(solver="glucose") + sage: SAT(solver='glucose') DIMACS Solver: 'glucose -verb=0 -model {input}' Forcing Glucose Syrup:: - sage: SAT(solver="glucose-syrup") + sage: SAT(solver='glucose-syrup') DIMACS Solver: 'glucose-syrup -model -verb=0 {input}' Forcing Kissat:: - sage: SAT(solver="kissat") + sage: SAT(solver='kissat') DIMACS Solver: 'kissat -q {input}' """ if solver is None: diff --git a/src/sage/schemes/affine/affine_homset.py b/src/sage/schemes/affine/affine_homset.py old mode 100644 new mode 100755 index 9fcf0543da5..e2dc72eadd0 --- a/src/sage/schemes/affine/affine_homset.py +++ b/src/sage/schemes/affine/affine_homset.py @@ -10,7 +10,7 @@ the rational points are implemented by such scheme morphisms. This is done by :class:`SchemeHomset_points` and its subclasses. -.. note:: +.. NOTE:: You should not create the Hom-sets manually. Instead, use the :meth:`~sage.structure.parent.Hom` method that is inherited by all @@ -91,7 +91,7 @@ def _repr_(self): """ Return a string representation of a homset. - OUTPUT: A string. + OUTPUT: string EXAMPLES:: @@ -178,9 +178,7 @@ def points(self, **kwds): by lowering the tolerance. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- real number (default: 0). The bound for the height of the coordinates. Only used for subschemes with @@ -190,15 +188,13 @@ def points(self, **kwds): For numerically inexact fields, points are on the subscheme if they satisfy the equations to within tolerance. - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 - for enumeration over number fields. + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm-4 for enumeration over number fields - ``precision`` -- the precision to use for computing the elements of - bounded height of number fields. - - OUTPUT: + bounded height of number fields - - a list of rational points of a affine scheme + OUTPUT: list of rational points of a affine scheme .. WARNING:: @@ -383,7 +379,7 @@ def numerical_points(self, F=None, **kwds): For numerically inexact fields, points are on the subscheme if they satisfy the equations to within tolerance. - OUTPUT: A list of points in the ambient space. + OUTPUT: list of points in the ambient space .. WARNING:: diff --git a/src/sage/schemes/affine/affine_morphism.py b/src/sage/schemes/affine/affine_morphism.py old mode 100644 new mode 100755 index 4d0aebd69c7..a4bd1dd51d5 --- a/src/sage/schemes/affine/affine_morphism.py +++ b/src/sage/schemes/affine/affine_morphism.py @@ -272,15 +272,13 @@ def __call__(self, x, check=True): def __eq__(self, right): """ - Tests the equality of two affine maps. + Test the equality of two affine maps. INPUT: - ``right`` -- a map on affine space - OUTPUT: - - ``True`` if the two affine maps define the same map. + OUTPUT: ``True`` if the two affine maps define the same map EXAMPLES:: @@ -310,15 +308,13 @@ def __eq__(self, right): def __ne__(self, right): """ - Tests the inequality of two affine maps. + Test the inequality of two affine maps. INPUT: - ``right`` -- a map on affine space - OUTPUT: - - ``True`` if the two affine maps define the same map. + OUTPUT: ``True`` if the two affine maps define the same map EXAMPLES:: @@ -442,7 +438,7 @@ def homogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers. If ``n`` is an integer, + - ``n`` -- tuple of nonnegative integers; if ``n`` is an integer, then the two values of the tuple are assumed to be the same OUTPUT: a morphism from the projective embedding of the domain of this map @@ -636,9 +632,7 @@ def as_dynamical_system(self): """ Return this endomorphism as a :class:`DynamicalSystem_affine`. - OUTPUT: - - - :class:`DynamicalSystem_affine` + OUTPUT: :class:`DynamicalSystem_affine` EXAMPLES:: @@ -695,9 +689,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -753,14 +747,12 @@ def local_height(self, v, prec=None): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default RealField precision). - - OUTPUT: + default RealField precision) - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -809,14 +801,12 @@ def local_height_arch(self, i, prec=None): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: - - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -860,9 +850,7 @@ def jacobian(self): The `(i, j)` entry of the Jacobian matrix is the partial derivative ``diff(functions[i], variables[j])``. - OUTPUT: - - - matrix with coordinates in the coordinate ring of the map. + OUTPUT: matrix with coordinates in the coordinate ring of the map EXAMPLES:: @@ -1059,7 +1047,7 @@ def weil_restriction(self): morphism from the Weil restriction of the domain to the Weil restriction of the codomain. - OUTPUT: Scheme morphism on the Weil restrictions of the domain + OUTPUT: scheme morphism on the Weil restrictions of the domain and codomain of the map. EXAMPLES:: @@ -1292,7 +1280,6 @@ def indeterminacy_points(self, F=None): sage: f = A2.hom([x*y, y, x], P2) sage: f.indeterminacy_points() # needs sage.libs.singular [(0, 0)] - """ if F is None: fcn = self @@ -1524,7 +1511,6 @@ def indeterminacy_locus(self): y*z sage: L.dimension() # needs sage.libs.singular 1 - """ # homogenize using 0th affine patch both for domain and codomain h = self.homogenize(0) diff --git a/src/sage/schemes/affine/affine_point.py b/src/sage/schemes/affine/affine_point.py old mode 100644 new mode 100755 index 4824c30d7a2..385e4259926 --- a/src/sage/schemes/affine/affine_point.py +++ b/src/sage/schemes/affine/affine_point.py @@ -42,9 +42,9 @@ class SchemeMorphism_point_affine(SchemeMorphism_point): - ``X`` -- a subscheme of an ambient affine space over a ring `R` - - ``v`` -- a list/tuple/iterable of coordinates in `R` + - ``v`` -- list/tuple/iterable of coordinates in `R` - - ``check`` -- boolean (default:``True``); whether to + - ``check`` -- boolean (default: ``True``); whether to check the input for consistency EXAMPLES:: @@ -91,7 +91,7 @@ def __init__(self, X, v, check=True): def _matrix_times_point_(self, mat, dom): r""" - Multiplies the point on the left by a matrix ``mat``. + Multiply the point on the left by a matrix ``mat``. INPUT: @@ -138,7 +138,7 @@ def _matrix_times_point_(self, mat, dom): def __hash__(self): r""" - Computes the hash value of this affine point. + Compute the hash value of this affine point. EXAMPLES:: @@ -152,22 +152,19 @@ def __hash__(self): sage: pt = A([1, 2, -i]) # needs sage.rings.real_mpfr sage.symbolic sage: hash(pt) == hash(tuple(pt)) # needs sage.rings.real_mpfr sage.symbolic True - """ return hash(tuple(self)) def global_height(self, prec=None): r""" - Returns the logarithmic height of the point. + Return the logarithmic height of the point. INPUT: - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: - - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -214,11 +211,9 @@ def homogenize(self, n): INPUT: - - ``n`` -- integer between 0 and dimension of the map, inclusive. - - OUTPUT: + - ``n`` -- integer between 0 and dimension of the map, inclusive - - A point in the projectivization of the codomain of the map . + OUTPUT: a point in the projectivization of the codomain of the map EXAMPLES:: @@ -278,7 +273,7 @@ def weil_restriction(self): the equivalent point on the Weil restriction of its codomain. - OUTPUT: Scheme point on the Weil restriction of the codomain of this point. + OUTPUT: scheme point on the Weil restriction of the codomain of this point EXAMPLES:: @@ -345,9 +340,9 @@ def intersection_multiplicity(self, X): INPUT: - - ``X`` -- a subscheme in the same ambient space as that of the codomain of this point. + - ``X`` -- a subscheme in the same ambient space as that of the codomain of this point - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: @@ -384,7 +379,7 @@ def multiplicity(self): Uses the subscheme multiplicity implementation. This point must be a point on an affine subscheme. - OUTPUT: an integer. + OUTPUT: integer EXAMPLES:: @@ -430,9 +425,9 @@ class SchemeMorphism_point_affine_finite_field(SchemeMorphism_point_affine_field def __hash__(self): r""" - Returns the integer hash of the point. + Return the integer hash of the point. - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/schemes/affine/affine_rational_point.py b/src/sage/schemes/affine/affine_rational_point.py old mode 100644 new mode 100755 index 0f4a0f0bbe6..034637c8862 --- a/src/sage/schemes/affine/affine_rational_point.py +++ b/src/sage/schemes/affine/affine_rational_point.py @@ -62,8 +62,8 @@ def enum_affine_rational_field(X, B): INPUT: - - ``X`` -- a scheme or set of abstract rational points of a scheme. - - ``B`` -- a positive integer bound. + - ``X`` -- a scheme or set of abstract rational points of a scheme + - ``B`` -- a positive integer bound OUTPUT: @@ -170,15 +170,13 @@ def enum_affine_number_field(X, **kwds): [DK2013]_. Algorithm 5 is used for imaginary quadratic fields. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- a real number - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm algorithm-4 - - ``precision`` -- the precision to use for computing the elements of bounded height of number fields. + - ``precision`` -- the precision to use for computing the elements of bounded height of number fields OUTPUT: @@ -240,8 +238,8 @@ def enum_affine_finite_field(X): INPUT: - - ``X`` -- a scheme defined over a finite field or a set of abstract - rational points of such a scheme. + - ``X`` -- a scheme defined over a finite field or a set of abstract + rational points of such a scheme OUTPUT: diff --git a/src/sage/schemes/affine/affine_space.py b/src/sage/schemes/affine/affine_space.py old mode 100644 new mode 100755 index c50b6caabbb..b21ac4a7de6 --- a/src/sage/schemes/affine/affine_space.py +++ b/src/sage/schemes/affine/affine_space.py @@ -15,8 +15,8 @@ from sage.rings.integer_ring import ZZ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.rings.rational_field import RationalField -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.finite_rings.finite_field_base import FiniteField from sage.categories.map import Map from sage.categories.fields import Fields @@ -109,7 +109,7 @@ def AffineSpace(n, R=None, names=None, ambient_projective_space=None, ... NameError: variable names passed to AffineSpace conflict with names in ring """ - if (is_MPolynomialRing(n) or is_PolynomialRing(n)) and R is None: + if (isinstance(n, MPolynomialRing_base) or isinstance(n, PolynomialRing_general)) and R is None: R = n if names is not None: # Check for the case that the user provided a variable name @@ -233,8 +233,8 @@ def __iter__(self): def ngens(self): """ - Return the number of generators of self, i.e. the number of - variables in the coordinate ring of self. + Return the number of generators of ``self``, i.e. the number of + variables in the coordinate ring of ``self``. EXAMPLES:: @@ -247,8 +247,8 @@ def ngens(self): def rational_points(self, F=None): """ - Return the list of ``F``-rational points on the affine space self, - where ``F`` is a given finite field, or the base ring of self. + Return the list of ``F``-rational points on the affine space ``self``, + where ``F`` is a given finite field, or the base ring of ``self``. EXAMPLES:: @@ -485,7 +485,7 @@ def _latex_generic_point(self, v=None): def _check_satisfies_equations(self, v): """ Return ``True`` if ``v`` defines a point on the scheme ``self``; raise a - :class:`TypeError` otherwise. + :exc:`TypeError` otherwise. EXAMPLES:: @@ -526,11 +526,9 @@ def __pow__(self, m): INPUT: - - ``m`` -- integer. + - ``m`` -- integer - OUTPUT: - - - affine ambient space. + OUTPUT: affine ambient space EXAMPLES:: @@ -559,9 +557,9 @@ def __mul__(self, right): INPUT: - - ``right`` -- an affine space or subscheme. + - ``right`` -- an affine space or subscheme - OUTPUT: an affine space.= or subscheme. + OUTPUT: an affine space.= or subscheme EXAMPLES:: @@ -621,9 +619,9 @@ def change_ring(self, R): INPUT: - - ``R`` -- commutative ring or morphism. + - ``R`` -- commutative ring or morphism - OUTPUT: An affine space over ``R``. + OUTPUT: an affine space over ``R`` .. NOTE:: @@ -675,18 +673,16 @@ def coordinate_ring(self): def _validate(self, polynomials): """ If ``polynomials`` is a tuple of valid polynomial functions on the affine space, - return ``polynomials``, otherwise raise :class:`TypeError`. + return ``polynomials``, otherwise raise :exc:`TypeError`. Since this is an affine space, all polynomials are valid. INPUT: - ``polynomials`` -- tuple of polynomials in the coordinate ring of - this space. + this space - OUTPUT: - - - tuple of polynomials in the coordinate ring of this space. + OUTPUT: tuple of polynomials in the coordinate ring of this space EXAMPLES:: @@ -703,15 +699,12 @@ def projective_embedding(self, i=None, PP=None): INPUT: + - ``i`` -- integer (default: dimension of self = last coordinate) + determines which projective embedding to compute. The embedding is + that which has a 1 in the `i`-th coordinate, numbered from 0. - - ``i`` -- integer (default: dimension of self = last - coordinate) determines which projective embedding to compute. The - embedding is that which has a 1 in the i-th coordinate, numbered - from 0. - - - ``PP`` -- (default: None) ambient projective space, i.e., - codomain of morphism; this is constructed if it is not - given. + - ``PP`` -- (default: ``None``) ambient projective space, i.e., + codomain of morphism; this is constructed if it is not given. EXAMPLES:: @@ -800,7 +793,7 @@ def subscheme(self, X, **kwds): INPUT: - - ``X`` -- a list or tuple of equations. + - ``X`` -- list or tuple of equations EXAMPLES:: @@ -874,13 +867,13 @@ def chebyshev_polynomial(self, n, kind='first', monic=False): INPUT: - - ``n`` -- a non-negative integer. + - ``n`` -- nonnegative integer - - ``kind`` -- ``first`` or ``second`` specifying which kind of chebyshev the user would like - to generate. Defaults to ``first``. + - ``kind`` -- ``'first'`` (default) or ``'second'`` specifying which + kind of Chebyshev the user would like to generate - - ``monic`` -- ``True`` or ``False`` specifying if the polynomial defining the system - should be monic or not. Defaults to ``False``. + - ``monic`` -- boolean (default: ``False``) specifying if the + polynomial defining the system should be monic or not OUTPUT: :class:`DynamicalSystem_affine` @@ -912,7 +905,7 @@ def chebyshev_polynomial(self, n, kind='first', monic=False): sage: A.chebyshev_polynomial(-4, 'second') Traceback (most recent call last): ... - ValueError: first parameter 'n' must be a non-negative integer + ValueError: first parameter 'n' must be a nonnegative integer :: @@ -942,7 +935,7 @@ def chebyshev_polynomial(self, n, kind='first', monic=False): raise TypeError("affine space must be of dimension 1") n = ZZ(n) if n < 0: - raise ValueError("first parameter 'n' must be a non-negative integer") + raise ValueError("first parameter 'n' must be a nonnegative integer") from sage.dynamics.arithmetic_dynamics.affine_ds import DynamicalSystem_affine from sage.functions.orthogonal_polys import chebyshev_T, chebyshev_U @@ -1030,19 +1023,15 @@ def points_of_bounded_height(self, **kwds): slightly larger than the bound may be returned. This can be controlled by lowering the tolerance. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- a real number - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm algorithm-4 - ``precision`` -- the precision to use for computing the elements of bounded height of number fields - OUTPUT: - - - an iterator of points in self + OUTPUT: an iterator of points in self EXAMPLES:: @@ -1108,7 +1097,7 @@ def weil_restriction(self): If the field is a finite field, then this computes the Weil restriction to the prime subfield. - OUTPUT: Affine space of dimension ``d * self.dimension_relative()`` + OUTPUT: affine space of dimension ``d * self.dimension_relative()`` over the base field of ``self.base_ring()``. EXAMPLES:: @@ -1224,7 +1213,6 @@ def translation(self, p, q=None): (x + 3, y + 3, z + 3) sage: psi * phi == A.translation(p, q) True - """ gens = self.gens() diff --git a/src/sage/schemes/affine/affine_subscheme.py b/src/sage/schemes/affine/affine_subscheme.py old mode 100644 new mode 100755 index b3831e54d79..a6b550c6ec8 --- a/src/sage/schemes/affine/affine_subscheme.py +++ b/src/sage/schemes/affine/affine_subscheme.py @@ -85,7 +85,6 @@ def _morphism(self, *args, **kwds): Scheme endomorphism of Affine Space of dimension 3 over Integer Ring Defn: Defined on coordinates by sending (x, y, z) to (x, y, z) - """ return self.ambient_space()._morphism(*args, **kwds) @@ -138,13 +137,12 @@ def projective_embedding(self, i=None, PP=None): INPUT: - - ``i`` -- integer (default: dimension of self = last - coordinate) determines which projective embedding to compute. The - embedding is that which has a 1 in the i-th coordinate, numbered - from 0. + - ``i`` -- integer (default: dimension of self = last coordinate); + determines which projective embedding to compute. The embedding is + that which has a 1 in the `i`-th coordinate, numbered from 0. - - ``PP`` -- (default: None) ambient projective space, i.e., ambient space - of codomain of morphism; this is constructed if it is not given. + - ``PP`` -- (default: ``None``) ambient projective space, i.e., ambient + space of codomain of morphism; this is constructed if it is not given EXAMPLES:: @@ -247,12 +245,13 @@ def projective_closure(self, i=None, PP=None): INPUT: - - ``i`` -- (default: None) determines the embedding to use to compute the projective - closure of this affine subscheme. The embedding used is the one which has a 1 in the - i-th coordinate, numbered from 0. + - ``i`` -- (default: ``None``) determines the embedding to use to + compute the projective closure of this affine subscheme. The + embedding used is the one which has a 1 in the i-th coordinate, + numbered from 0. - - ``PP`` -- (default: None) ambient projective space, i.e., ambient space - of codomain of morphism; this is constructed if it is not given + - ``PP`` -- (default: ``None``) ambient projective space, i.e., ambient + space of codomain of morphism; this is constructed if it is not given OUTPUT: a projective subscheme @@ -287,12 +286,12 @@ def is_smooth(self, point=None): INPUT: - - ``point`` -- A point or ``None`` (default). The point to - test smoothness at. + - ``point`` -- a point or ``None`` (default). The point to + test smoothness at OUTPUT: - Boolean. If no point was specified, returns whether the + boolean; if no point was specified, returns whether the algebraic subscheme is smooth everywhere. Otherwise, smoothness at the specified point is tested. @@ -344,11 +343,11 @@ def intersection_multiplicity(self, X, P): INPUT: - - ``X`` -- subscheme in the same ambient space as this subscheme. + - ``X`` -- subscheme in the same ambient space as this subscheme - - ``P`` -- a point in the intersection of this subscheme with ``X``. + - ``P`` -- a point in the intersection of this subscheme with ``X`` - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -412,7 +411,7 @@ def intersection_multiplicity(self, X, P): J = X.defining_ideal() # move P to the origin and localize chng_coords = [AA.gens()[i] + P[i] for i in range(AA.dimension_relative())] - R = AA.coordinate_ring().change_ring(order="negdegrevlex") + R = AA.coordinate_ring().change_ring(order='negdegrevlex') Iloc = R.ideal([f(chng_coords) for f in I.gens()]) Jloc = R.ideal([f(chng_coords) for f in J.gens()]) # compute the intersection multiplicity with Serre's Tor formula using Singular @@ -436,11 +435,9 @@ def multiplicity(self, P): INPUT: - - ``P`` -- a point on this subscheme. - - OUTPUT: + - ``P`` -- a point on this subscheme - An integer. + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/schemes/berkovich/berkovich_cp_element.py b/src/sage/schemes/berkovich/berkovich_cp_element.py old mode 100644 new mode 100755 index 72111b32ab3..1b25bc801d3 --- a/src/sage/schemes/berkovich/berkovich_cp_element.py +++ b/src/sage/schemes/berkovich/berkovich_cp_element.py @@ -12,10 +12,10 @@ - Type II points are represented by a center and a rational power of `p`. -- Type III points are represented by a center and a non-negative real radius. +- Type III points are represented by a center and a nonnegative real radius. - Type IV points are represented by a finite list of centers and a finite list of - non-negative radii. + nonnegative radii. For an exposition of Berkovich space over `\CC_p`, see Chapter 6 of [Ben2019]_. For a more involved exposition, see Chapter 1 and 2 of [BR2010]_. @@ -417,7 +417,7 @@ def _custom_abs(self, x): Return the absolute value of ``x`` with respect to the norm on ``Cp``. Used to simplify code, as ``x`` may be a point of a number field - or a p-adic field. + or a `p`-adic field. EXAMPLES:: @@ -448,7 +448,7 @@ def center_function(self): Not defined unless this point is a type IV point created by using a univariate function to compute centers. - OUTPUT: A univariate function. + OUTPUT: a univariate function EXAMPLES:: @@ -476,7 +476,7 @@ def radius_function(self): Not defined unless this point is a type IV point created by using a univariate function to compute radii. - OUTPUT: A univariate function. + OUTPUT: a univariate function EXAMPLES:: @@ -504,7 +504,7 @@ def precision(self): This integer is the number of disks used in the approximation of the type IV point. Not defined for type I, II, or III points. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -528,7 +528,7 @@ def ideal(self): r""" The ideal which defines an embedding of the ``base_ring`` into `\CC_p`. - If this Berkovich space is backed by a p-adic field, then an embedding is + If this Berkovich space is backed by a `p`-adic field, then an embedding is already specified, and this returns ``None``. EXAMPLES:: @@ -541,7 +541,6 @@ def ideal(self): sage: B = Berkovich_Cp_Projective(3) sage: B(0).ideal() - """ return self.parent().ideal() @@ -580,8 +579,8 @@ def radius(self): OUTPUT: - - A non-negative real number for type I, II, or III points. - - A list of non-negative real numbers for type IV points. + - A nonnegative real number for type I, II, or III points. + - A list of nonnegative real numbers for type IV points. EXAMPLES:: @@ -613,10 +612,10 @@ def diameter(self, basepoint=Infinity): INPUT: - - ``basepoint`` -- (default = Infinity) A point of the - same Berkovich space as this point. + - ``basepoint`` -- (default: ``Infinity``) a point of the + same Berkovich space as this point - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -659,7 +658,7 @@ def diameter(self, basepoint=Infinity): if self._radius_func is None: return self._radius_lst[-1] from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing - R = PolynomialRing(QQ, names="x") + R = PolynomialRing(QQ, names='x') x = R.gens()[0] if isinstance(self._radius_func, Expression): radius_func_variable = self._radius_func.variables()[0] @@ -668,7 +667,7 @@ def diameter(self, basepoint=Infinity): radius_expr = self._radius_func(x) from sage.symbolic.ring import SymbolicRing as SR radius_expr = SR(RR)(radius_expr) - return radius_expr.limit(x="oo") + return radius_expr.limit(x='oo') return self._radius if not isinstance(basepoint, Berkovich_Element_Cp): raise TypeError('basepoint must be a point of Berkovich space, not %s' % basepoint) @@ -689,9 +688,9 @@ def path_distance_metric(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point - OUTPUT: A finite or infinite real number. + OUTPUT: a finite or infinite real number EXAMPLES:: @@ -739,10 +738,10 @@ def Hsia_kernel(self, other, basepoint): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. - - ``basepoint`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point + - ``basepoint`` -- a point of the same Berkovich space as this point - OUTPUT: A finite or infinite real number. + OUTPUT: a finite or infinite real number EXAMPLES:: @@ -761,7 +760,6 @@ def Hsia_kernel(self, other, basepoint): sage: Q3 = B(1/2) sage: Q1.Hsia_kernel(Q2, Q3) +infinity - """ if not isinstance(other, type(self)): raise TypeError('other must be a point of Berkovich space. other was %s' % other) @@ -786,9 +784,9 @@ def small_metric(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -848,10 +846,10 @@ def potential_kernel(self, other, basepoint): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. - - ``basepoint`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point + - ``basepoint`` -- a point of the same Berkovich space as this point - OUTPUT: A finite or infinite real number. + OUTPUT: a finite or infinite real number EXAMPLES:: @@ -891,9 +889,9 @@ def spherical_kernel(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -929,9 +927,9 @@ def Hsia_kernel_infinity(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -960,7 +958,7 @@ def center(self): Return the center of the corresponding disk (or sequence of disks) in `\CC_p`. - OUTPUT: An element of the ``base`` of the parent Berkovich space. + OUTPUT: an element of the ``base`` of the parent Berkovich space EXAMPLES:: @@ -992,7 +990,7 @@ def type_of_point(self): r""" Return the type of this point of Berkovich space over `\CC_p`. - OUTPUT: An integer between 1 and 4 inclusive. + OUTPUT: integer between 1 and 4 inclusive EXAMPLES:: @@ -1011,7 +1009,7 @@ def prime(self): """ The residue characteristic of the parent. - OUTPUT: A prime integer. + OUTPUT: a prime integer EXAMPLES:: @@ -1112,10 +1110,10 @@ class Berkovich_Element_Cp_Affine(Berkovich_Element_Cp): INPUT: - - ``center`` -- For type I, II, and III points, the center of the + - ``center`` -- for type I, II, and III points, the center of the corresponding disk in `\CC_p`. If the parent Berkovich space was created using a number field `K`, then ``center`` must be an element of `K`. Otherwise, ``center`` must be an element of a - p-adic field. For type IV points, can be a list of centers used to approximate the point or a + `p`-adic field. For type IV points, can be a list of centers used to approximate the point or a univariate function that computes the centers (computation starts at 1). - ``radius`` -- (optional) For type I, II, and III points, the radius of the @@ -1124,11 +1122,11 @@ class Berkovich_Element_Cp_Affine(Berkovich_Element_Cp): computes the radii (computation starts at 1). - ``power`` -- (optional) Rational number. Used for constructing type II points; specifies - the power of ``p`` such that `p^\text{power}` = radius. + the power of ``p`` such that `p^\text{power}` = radius - - ``prec`` -- (default: 20) The number of disks to be used to approximate a type IV point. + - ``prec`` -- (default: 20) the number of disks to be used to approximate a type IV point - - ``error_check`` -- (default: ``True``) If error checking should be run on input. If + - ``error_check`` -- boolean (default: ``True``); if error checking should be run on input. If input is correctly formatted, can be set to ``False`` for better performance. WARNING: with error check set to ``False``, any error in the input will lead to incorrect results. @@ -1269,7 +1267,7 @@ def __init__(self, parent, center, radius=None, power=None, prec=20, error_check raise TypeError('use as_affine_point to convert to affine Berkovich space') Berkovich_Element_Cp.__init__(self, parent=parent, center=center, radius=radius, power=power, - prec=prec, space_type="affine", error_check=error_check) + prec=prec, space_type='affine', error_check=error_check) def as_projective_point(self): r""" @@ -1413,12 +1411,12 @@ def lt(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point OUTPUT: - - ``True`` -- If this point is less than ``other`` in the standard partial order. - - ``False`` -- Otherwise. + - ``True`` -- if this point is less than ``other`` in the standard partial order + - ``False`` -- otherwise EXAMPLES:: @@ -1490,12 +1488,12 @@ def gt(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point OUTPUT: - - ``True`` -- If this point is greater than ``other`` in the standard partial order. - - ``False`` -- Otherwise. + - ``True`` -- if this point is greater than ``other`` in the standard partial order + - ``False`` -- otherwise EXAMPLES:: @@ -1558,11 +1556,11 @@ def join(self, other, basepoint=Infinity): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. - - ``basepoint`` -- (default: Infinity) A point of the same - Berkovich space as this point or Infinity. + - ``other`` -- a point of the same Berkovich space as this point + - ``basepoint`` -- (default: ``Infinity``) a point of the same + Berkovich space as this point or ``Infinity`` - OUTPUT: A point of the same Berkovich space. + OUTPUT: a point of the same Berkovich space EXAMPLES:: @@ -1639,7 +1637,7 @@ def involution_map(self): then the image under the involution map is not defined. To avoid this error, increase precision. - OUTPUT: A point of the same Berkovich space. + OUTPUT: a point of the same Berkovich space EXAMPLES: @@ -1728,8 +1726,8 @@ def contained_in_interval(self, start, end): INPUT: - - ``start`` -- A point of the same Berkovich space as this point. - - ``end`` -- A point of the same Berkovich space as this point. + - ``start`` -- a point of the same Berkovich space as this point + - ``end`` -- a point of the same Berkovich space as this point OUTPUT: @@ -1792,10 +1790,10 @@ class Berkovich_Element_Cp_Projective(Berkovich_Element_Cp): INPUT: - - ``center`` -- For type I, II, and III points, the center of the + - ``center`` -- for type I, II, and III points, the center of the corresponding disk in `P^1(\CC_p)`. If the parent Berkovich space was created using a number field `K`, then ``center`` can be an element of `P^1(K)`. Otherwise, ``center`` - must be an element of a projective space of dimension 1 over a padic field. + must be an element of a projective space of dimension 1 over a `p`-adic field. For type IV points, can be a list of centers used to approximate the point or a univariate function that computes the centers (computation starts at 1). @@ -1807,9 +1805,9 @@ class Berkovich_Element_Cp_Projective(Berkovich_Element_Cp): - ``power`` -- (optional) Rational number. Used for constructing type II points; specifies the power of ``p`` such that `p^\text{power}` = radius - - ``prec`` -- (default: 20) The number of disks to be used to approximate a type IV point + - ``prec`` -- (default: 20) the number of disks to be used to approximate a type IV point - - ``error_check`` -- (default: ``True``) If error checking should be run on input. If + - ``error_check`` -- boolean (default: ``True``); if error checking should be run on input. If input is correctly formatted, can be set to ``False`` for better performance. WARNING: with error check set to ``False``, any error in the input will lead to incorrect results. @@ -1908,13 +1906,13 @@ def __init__(self, parent, center, radius=None, power=None, prec=20, error_check raise TypeError('use as_projective_point to convert to projective Berkovich space') Berkovich_Element_Cp.__init__(self, parent=parent, center=center, radius=radius, power=power, - prec=prec, space_type="projective", error_check=error_check) + prec=prec, space_type='projective', error_check=error_check) def as_affine_point(self): """ Return the corresponding affine point after dehomogenizing at infinity. - OUTPUT: A point of affine Berkovich space. + OUTPUT: a point of affine Berkovich space EXAMPLES:: @@ -2061,12 +2059,12 @@ def lt(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point OUTPUT: - - ``True`` -- If this point is less than ``other`` in the standard partial order. - - ``False`` -- Otherwise. + - ``True`` -- if this point is less than ``other`` in the standard partial order + - ``False`` -- otherwise EXAMPLES:: @@ -2156,12 +2154,12 @@ def gt(self, other): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. + - ``other`` -- a point of the same Berkovich space as this point OUTPUT: - - ``True`` -- If this point is greater than ``other`` in the standard partial order. - - ``False`` -- Otherwise. + - ``True`` -- if this point is greater than ``other`` in the standard partial order + - ``False`` -- otherwise EXAMPLES:: @@ -2241,11 +2239,11 @@ def join(self, other, basepoint=Infinity): INPUT: - - ``other`` -- A point of the same Berkovich space as this point. - - ``basepoint`` -- (default: Infinity) A point of the same - Berkovich space as this point, or infinity. + - ``other`` -- a point of the same Berkovich space as this point + - ``basepoint`` -- (default: ``Infinity``) a point of the same + Berkovich space as this point, or ``Infinity`` - OUTPUT: A point of the same Berkovich space. + OUTPUT: a point of the same Berkovich space EXAMPLES:: @@ -2403,7 +2401,7 @@ def involution_map(self): then the image under the involution map is not defined. To avoid this error, increase precision. - OUTPUT: A point of the same Berkovich space. + OUTPUT: a point of the same Berkovich space EXAMPLES: @@ -2498,8 +2496,8 @@ def contained_in_interval(self, start, end): INPUT: - - ``start`` -- A point of the same Berkovich space as this point. - - ``end`` -- A point of the same Berkovich space as this point. + - ``start`` -- a point of the same Berkovich space as this point + - ``end`` -- a point of the same Berkovich space as this point OUTPUT: diff --git a/src/sage/schemes/berkovich/berkovich_space.py b/src/sage/schemes/berkovich/berkovich_space.py old mode 100644 new mode 100755 index f64b7835f79..f5455937b43 --- a/src/sage/schemes/berkovich/berkovich_space.py +++ b/src/sage/schemes/berkovich/berkovich_space.py @@ -134,11 +134,11 @@ def residue_characteristic(self): def is_padic_base(self): """ - Return ``True`` if this Berkovich space is backed by a p-adic field. + Return ``True`` if this Berkovich space is backed by a `p`-adic field. OUTPUT: - - ``True`` if this Berkovich space was created with a p-adic field. + - ``True`` if this Berkovich space was created with a `p`-adic field. - ``False`` otherwise. EXAMPLES:: @@ -182,7 +182,7 @@ def ideal(self): r""" The ideal which defines an embedding of the ``base_ring`` into `\CC_p`. - If this Berkovich space is backed by a p-adic field, then an embedding is + If this Berkovich space is backed by a `p`-adic field, then an embedding is already specified, and this returns ``None``. OUTPUT: @@ -191,7 +191,7 @@ def ideal(self): - A prime of `\QQ` if ``base_ring`` is `\QQ`. - - ``None`` if ``base_ring`` is a p-adic field. + - ``None`` if ``base_ring`` is a `p`-adic field. EXAMPLES:: @@ -312,14 +312,14 @@ class Berkovich_Cp_Affine(Berkovich_Cp): for all `f \in \CC_p[x]`. We can represent the Berkovich affine line in two separate ways: - either using a p-adic field to represent elements or using + either using a `p`-adic field to represent elements or using a number field to represent elements while storing an ideal of the ring of integers of the number field, which specifies an embedding of the number field into `\CC_p`. See the examples. INPUT: - - ``base`` -- Three cases: + - ``base`` -- three cases: * a prime number `p`. Centers of elements are then represented as points of `\QQ_p`. @@ -367,8 +367,8 @@ class Berkovich_Cp_Affine(Berkovich_Cp): Type I point centered at 2 + O(3) Note that this point has very low precision, as ``B`` was initialized - with a p-adic field of capped-relative precision one. For high precision, - pass in a high precision p-adic field:: + with a `p`-adic field of capped-relative precision one. For high precision, + pass in a high precision `p`-adic field:: sage: B = Berkovich_Cp_Affine(Qp(3, 1000)); B Affine Berkovich line over Cp(3) of precision 1000 @@ -399,7 +399,7 @@ class Berkovich_Cp_Affine(Berkovich_Cp): ring of integers of the number field. Specifying the ideal uniquely specifies an embedding of the number field into `\CC_p`. - Unlike in the case where Berkovich space is backed by a p-adic + Unlike in the case where Berkovich space is backed by a `p`-adic field, any point of a Berkovich space backed by a number field must be centered at a point of that number field:: @@ -521,14 +521,14 @@ class Berkovich_Cp_Projective(Berkovich_Cp): of the Berkovich affine line. We can represent the Berkovich projective line in two separate ways: - either using a p-adic field to represent elements or using + either using a `p`-adic field to represent elements or using a number field to represent elements while storing an ideal of the ring of integers of the number field, which specifies an embedding of the number field into `\CC_p`. See the examples. INPUT: - - ``base`` -- Three cases: + - ``base`` -- three cases: * a prime number `p`. Centers of elements are then represented as points of projective space of dimension 1 over `\QQ_p`. @@ -563,7 +563,7 @@ class Berkovich_Cp_Projective(Berkovich_Cp): For details about element construction, see the documentation of :class:`Berkovich_Element_Cp_Projective`. Initializing a Berkovich projective - line by passing in a p-adic space looks the same:: + line by passing in a `p`-adic space looks the same:: sage: B = Berkovich_Cp_Projective(Qp(3)); B Projective Berkovich line over Cp(3) of precision 20 @@ -600,7 +600,7 @@ class Berkovich_Cp_Projective(Berkovich_Cp): of the number field. Specifying the ideal uniquely specifies an embedding of the number field into `\CC_p`. - Unlike in the case where Berkovich space is backed by a p-adic + Unlike in the case where Berkovich space is backed by a `p`-adic field, any point of a Berkovich space backed by a number field must be centered at a point of that number field:: @@ -683,7 +683,7 @@ def base_ring(self): r""" The base ring of this Berkovich Space. - OUTPUT: A field. + OUTPUT: a field EXAMPLES:: diff --git a/src/sage/schemes/curves/affine_curve.py b/src/sage/schemes/curves/affine_curve.py old mode 100644 new mode 100755 index c8467094001..c539968c294 --- a/src/sage/schemes/curves/affine_curve.py +++ b/src/sage/schemes/curves/affine_curve.py @@ -229,13 +229,13 @@ def projective_closure(self, i=0, PP=None): INPUT: - - ``i`` -- (default: 0) the index of the affine coordinate chart of the projective space that the affine - ambient space of this curve embeds into. + - ``i`` -- (default: 0) the index of the affine coordinate chart of the + projective space that the affine ambient space of this curve embeds into - - ``PP`` -- (default: None) ambient projective space to compute the projective closure in. This is - constructed if it is not given. + - ``PP`` -- (default: ``None``) ambient projective space to compute the + projective closure in; this is constructed if it is not given - OUTPUT: A curve in projective space. + OUTPUT: a curve in projective space EXAMPLES:: @@ -317,15 +317,15 @@ def divisor_of_function(self, r): """ Return the divisor of a function on a curve. - INPUT: r is a rational function on X - - OUTPUT: + INPUT: + - ``r`` -- a rational function on X - - ``list`` -- The divisor of r represented as a list of - coefficients and points. (TODO: This will change to a more - structural output in the future.) + OUTPUT: + - ``list`` -- the divisor of r represented as a list of coefficients + and points. (TODO: This will change to a more structural output in + the future.) EXAMPLES:: @@ -372,12 +372,10 @@ def local_coordinates(self, pt, n): INPUT: + - ``pt`` -- an F-rational point on X which is not a + point of ramification for the projection (x,y) - x - - ``pt`` -- an F-rational point on X which is not a - point of ramification for the projection (x,y) - x. - - - ``n`` -- the number of terms desired - + - ``n`` -- the number of terms desired OUTPUT: x = x0 + t y = y0 + power series in t @@ -442,11 +440,10 @@ def plot(self, *args, **kwds): INPUT: - - ``*args`` -- optional tuples (variable, minimum, maximum) for - plotting dimensions + - ``*args`` -- (optional) tuples (variable, minimum, maximum) for + plotting dimensions - - ``**kwds`` -- optional keyword arguments passed on to - ``implicit_plot`` + - ``**kwds`` -- optional keyword arguments passed on to ``implicit_plot`` EXAMPLES: @@ -487,11 +484,11 @@ def is_transverse(self, C, P): INPUT: - - ``C`` -- a curve in the ambient space of this curve. + - ``C`` -- a curve in the ambient space of this curve - - ``P`` -- a point in the intersection of both curves. + - ``P`` -- a point in the intersection of both curves - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -545,9 +542,9 @@ def multiplicity(self, P): INPUT: - - ``P`` -- a point in the ambient space of this curve. + - ``P`` -- a point in the ambient space of this curve - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -609,12 +606,12 @@ def tangents(self, P, factor=True): - ``P`` -- a point on this curve - - ``factor`` -- (default: ``True``) whether to attempt computing the + - ``factor`` -- boolean (default: ``True``); whether to attempt computing the polynomials of the individual tangent lines over the base field of this curve, or to just return the polynomial corresponding to the union of the tangent lines (which requires fewer computations) - OUTPUT: A list of polynomials in the coordinate ring of the ambient space. + OUTPUT: list of polynomials in the coordinate ring of the ambient space EXAMPLES:: @@ -778,9 +775,8 @@ def rational_parameterization(self): The rational parameterization may have coefficients in a quadratic extension of the rational field. - OUTPUT: - - - a birational map between `\mathbb{A}^{1}` and this curve, given as a scheme morphism. + OUTPUT: a birational map between `\mathbb{A}^{1}` and this curve, given + as a scheme morphism EXAMPLES:: @@ -873,7 +869,7 @@ def projection(self, indices, AS=None): INPUT: - - ``indices`` -- a list or tuple of distinct integers specifying the + - ``indices`` -- list or tuple of distinct integers specifying the indices of the coordinates to use in the projection. Can also be a list or tuple consisting of variables of the coordinate ring of the ambient space of this curve. If integers are used to specify the coordinates, 0 @@ -881,12 +877,12 @@ def projection(self, indices, AS=None): two and one less than the dimension of the ambient space of this curve, inclusive. - - ``AS`` -- (default: None) the affine space the projected curve will + - ``AS`` -- (default: ``None``) the affine space the projected curve will be defined in. This space must be defined over the same base field as this curve, and must have dimension equal to the length of ``indices``. This space is constructed if not specified. - OUTPUT: A tuple of + OUTPUT: a tuple of - a scheme morphism from this curve to affine space of dimension equal to the number of coordinates specified in ``indices`` @@ -1042,12 +1038,12 @@ def plane_projection(self, AP=None): INPUT: - - ``AP`` -- (default: None) the affine plane to project this curve + - ``AP`` -- (default: ``None``) the affine plane to project this curve into. This space must be defined over the same base field as this curve, and must have dimension two. This space will be constructed if not specified. - OUTPUT: A tuple of + OUTPUT: a tuple of - a scheme morphism from this curve into an affine plane @@ -1109,21 +1105,21 @@ def blowup(self, P=None): INPUT: - - ``P`` -- (default: None) a point on this curve at which to blow up; - if ``None``, then ``P`` is taken to be the origin. + - ``P`` -- (default: ``None``) a point on this curve at which to blow up; + if ``None``, then ``P`` is taken to be the origin - OUTPUT: A tuple of + OUTPUT: a tuple of - a tuple of curves in affine space of the same dimension as the ambient space of this curve, which define the blow up in each affine chart. - - a tuple of tuples such that the jth element of the ith tuple is the - transition map from the ith affine patch to the jth affine patch. + - a tuple of tuples such that the j-th element of the i-th tuple is the + transition map from the i-th affine patch to the j-th affine patch. - a tuple consisting of the restrictions of the projection map from the blow up back to the original curve, restricted to each affine patch. - There the ith element will be the projection from the ith affine patch. + There the i-th element will be the projection from the i-th affine patch. EXAMPLES:: @@ -1416,26 +1412,26 @@ def resolution_of_singularities(self, extend=False): INPUT: - - ``extend`` -- (default: ``False``) specifies whether to extend the base - field when necessary to find all singular points when this curve is - defined over a number field. If ``extend`` is ``False``, then only - singularities with coordinates in the base field of this curve will be - resolved. However, setting ``extend`` to ``True`` will slow down - computations. + - ``extend`` -- boolean (default: ``False``); specifies whether to + extend the base field when necessary to find all singular points when + this curve is defined over a number field. If ``extend`` is + ``False``, then only singularities with coordinates in the base field + of this curve will be resolved. However, setting ``extend`` to + ``True`` will slow down computations. - OUTPUT: A tuple of + OUTPUT: a tuple of - a tuple of curves in affine space of the same dimension as the ambient space of this curve, which represent affine patches of the resolution of singularities. - - a tuple of tuples such that the jth element of the ith tuple is the - transition map from the ith patch to the jth patch. + - a tuple of tuples such that the j-th element of the i-th tuple is the + transition map from the i-th patch to the j-th patch. - a tuple consisting of birational maps from the patches back to the original curve that were created by composing the projection maps - generated from the blow up computations. There the ith element will be - a map from the ith patch. + generated from the blow up computations. There the i-th element will + be a map from the i-th patch. EXAMPLES:: @@ -1801,11 +1797,11 @@ def fundamental_group(self, simplified=True, puiseux=True): INPUT: - - ``simplified`` -- (default: ``True``) boolean to simplify the presentation. + - ``simplified`` -- boolean (default: ``True``); to simplify the presentation - - ``puiseux`` -- (default: ``True``) boolean to decide if the + - ``puiseux`` -- boolean (default: ``True``); to decide if the presentation is constructed in the classical way or using Puiseux - shortcut. + shortcut OUTPUT: @@ -1909,7 +1905,6 @@ def braid_monodromy(self): Traceback (most recent call last): ... NotImplementedError: the base field must have an embedding to the algebraic field - """ from sage.schemes.curves.zariski_vankampen import braid_monodromy F = self.base_ring() @@ -1922,9 +1917,9 @@ def braid_monodromy(self): def riemann_surface(self, **kwargs): r""" - Return the complex Riemann surface determined by this curve + Return the complex Riemann surface determined by this curve. - OUTPUT: A :class:`~sage.schemes.riemann_surfaces.riemann_surface.RiemannSurface` object. + OUTPUT: a :class:`~sage.schemes.riemann_surfaces.riemann_surface.RiemannSurface` object EXAMPLES:: @@ -1965,7 +1960,7 @@ def riemann_roch_basis(self, D): divisor `Div = d_1P_1 + \dots + d_nP_n`, where `X(F) = \{P_1, \dots, P_n\}`. The ordering is that dictated by ``places_on_curve``. - OUTPUT: A basis of `L(Div)`. + OUTPUT: a basis of `L(Div)`. EXAMPLES:: @@ -1997,13 +1992,13 @@ def riemann_roch_basis(self, D): return [g[1].sage() / g[2].sage() for g in G.BrillNoether(P)] - def rational_points(self, algorithm="enum"): + def rational_points(self, algorithm='enum'): r""" Return sorted list of all rational points on this curve. INPUT: - - ``algorithm`` -- possible choices: + - ``algorithm`` -- possible choices: + ``'enum'`` -- use *very* naive point enumeration to find all rational points on this curve over a finite field. @@ -2016,7 +2011,7 @@ def rational_points(self, algorithm="enum"): .. NOTE:: The Brill-Noether package does not always work. When it fails, a - RuntimeError exception is raised. + :exc:`RuntimeError` exception is raised. EXAMPLES:: @@ -2084,8 +2079,8 @@ def rational_points(self, algorithm="enum"): return sorted(set(pnts)) elif algorithm == "all": - S_enum = self.rational_points(algorithm="enum") - S_bn = self.rational_points(algorithm="bn") + S_enum = self.rational_points(algorithm='enum') + S_bn = self.rational_points(algorithm='bn') if S_enum != S_bn: raise RuntimeError("Bug in rational_points -- different algorithms give different answers for curve %s!" % self) return S_enum @@ -2197,7 +2192,7 @@ def function(self, f): - ``f`` -- an element of the fraction field of the coordinate ring of the ambient space or the coordinate ring of the curve - OUTPUT: An element of the function field of this curve. + OUTPUT: an element of the function field of this curve EXAMPLES:: @@ -2245,7 +2240,7 @@ def pull_from_function_field(self, f): INPUT: - - ``f`` -- an element of the function field + - ``f`` -- an element of the function field OUTPUT: @@ -2686,7 +2681,7 @@ def places_on(self, point): - ``point`` -- a closed point of the curve - OUTPUT: A list of the places of the function field of the curve. + OUTPUT: list of the places of the function field of the curve EXAMPLES:: @@ -2859,7 +2854,7 @@ def closed_points(self, degree=1): INPUT: - - ``degree`` -- a positive integer + - ``degree`` -- positive integer EXAMPLES:: diff --git a/src/sage/schemes/curves/closed_point.py b/src/sage/schemes/curves/closed_point.py old mode 100644 new mode 100755 index 50cd46605bc..384487a4fd0 --- a/src/sage/schemes/curves/closed_point.py +++ b/src/sage/schemes/curves/closed_point.py @@ -90,7 +90,7 @@ class IntegralCurveClosedPoint(CurveClosedPoint): INPUT: - - ``curve`` -- the curve to which the closed point belongs + - ``curve`` -- the curve to which the closed point belongs - ``prime_ideal`` -- a prime ideal @@ -310,7 +310,7 @@ def projective(self, i=0): INPUT: - - ``i`` -- an integer + - ``i`` -- integer EXAMPLES:: @@ -391,7 +391,7 @@ def affine(self, i=None): INPUT: - - ``i`` -- an integer; if not specified, it is chosen automatically. + - ``i`` -- integer; if not specified, it is chosen automatically EXAMPLES:: diff --git a/src/sage/schemes/curves/constructor.py b/src/sage/schemes/curves/constructor.py old mode 100644 new mode 100755 index 687a238fcfa..beff4dd649d --- a/src/sage/schemes/curves/constructor.py +++ b/src/sage/schemes/curves/constructor.py @@ -39,7 +39,7 @@ from sage.categories.number_fields import NumberFields from sage.rings.polynomial.multi_polynomial import MPolynomial -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.finite_rings.finite_field_base import FiniteField from sage.rings.rational_field import QQ @@ -107,7 +107,7 @@ def Curve(F, A=None): - ``F`` -- a multivariate polynomial, or a list or tuple of polynomials, or an algebraic scheme - - ``A`` -- (default: None) an ambient space in which to create the curve + - ``A`` -- (default: ``None``) an ambient space in which to create the curve EXAMPLES: @@ -240,7 +240,7 @@ def Curve(F, A=None): if isinstance(F, (list, tuple)): P = Sequence(F).universe() - if not is_MPolynomialRing(P): + if not isinstance(P, MPolynomialRing_base): raise TypeError("universe of F must be a multivariate polynomial ring") for f in F: if not f.is_homogeneous(): diff --git a/src/sage/schemes/curves/curve.py b/src/sage/schemes/curves/curve.py old mode 100644 new mode 100755 index 1ae4b4144b3..be072ba3873 --- a/src/sage/schemes/curves/curve.py +++ b/src/sage/schemes/curves/curve.py @@ -153,8 +153,8 @@ def divisor_group(self, base_ring=None): INPUT: - - ``base_ring`` -- the base ring of the divisor group. Usually, this is - `\ZZ` (default) or `\QQ`. + - ``base_ring`` -- the base ring of the divisor group; usually, this is + `\ZZ` (default) or `\QQ` OUTPUT: the divisor group of the curve @@ -275,9 +275,7 @@ def singular_subscheme(self): r""" Return the subscheme of singular points of this curve. - OUTPUT: - - - a subscheme in the ambient space of this curve. + OUTPUT: a subscheme in the ambient space of this curve EXAMPLES:: @@ -315,10 +313,10 @@ def singular_points(self, F=None): INPUT: - - ``F`` -- (default: None) field over which to find the singular + - ``F`` -- (default: ``None``) field over which to find the singular points; if not given, the base ring of this curve is used - OUTPUT: a list of points in the ambient space of this curve + OUTPUT: list of points in the ambient space of this curve EXAMPLES:: @@ -362,13 +360,13 @@ def is_singular(self, P=None): INPUT: - - ``P`` -- (default: None) a point on this curve + - ``P`` -- (default: ``None``) a point on this curve OUTPUT: - A boolean. If a point ``P`` is provided, and if ``P`` lies on this - curve, returns True if ``P`` is a singular point of this curve, and - False otherwise. If no point is provided, returns True or False + boolean; if a point ``P`` is provided, and if ``P`` lies on this + curve, returns ``True`` if ``P`` is a singular point of this curve, and + ``False`` otherwise. If no point is provided, returns ``True`` or False depending on whether this curve is or is not singular, respectively. EXAMPLES:: @@ -395,9 +393,9 @@ def intersects_at(self, C, P): INPUT: - - ``C`` -- a curve in the same ambient space as this curve. + - ``C`` -- a curve in the same ambient space as this curve - - ``P`` -- a point in the ambient space of this curve. + - ``P`` -- a point in the ambient space of this curve EXAMPLES:: @@ -450,11 +448,11 @@ def intersection_points(self, C, F=None): - ``C`` -- a curve in the same ambient space as this curve - - ``F`` -- (default: None); field over which to compute the + - ``F`` -- (default: ``None``) field over which to compute the intersection points; if not specified, the base ring of this curve is used - OUTPUT: a list of points in the ambient space of this curve + OUTPUT: list of points in the ambient space of this curve EXAMPLES:: diff --git a/src/sage/schemes/curves/plane_curve_arrangement.py b/src/sage/schemes/curves/plane_curve_arrangement.py old mode 100644 new mode 100755 index e82ec07328d..b4c36b1329a --- a/src/sage/schemes/curves/plane_curve_arrangement.py +++ b/src/sage/schemes/curves/plane_curve_arrangement.py @@ -79,7 +79,7 @@ def __init__(self, parent, curves, check=True): - ``parent`` -- the parent :class:`PlaneCurveArrangements` - - ``curves`` -- a tuple of curves + - ``curves`` -- tuple of curves EXAMPLES:: @@ -111,10 +111,6 @@ def __getitem__(self, i): - ``i`` -- integer - OUTPUT: - - The `i`-th curve. - EXAMPLES:: sage: H. = AffinePlaneCurveArrangements(QQ) @@ -138,9 +134,7 @@ def ncurves(self): r""" Return the number of curves in the arrangement. - OUTPUT: - - An integer. + OUTPUT: integer EXAMPLES:: @@ -159,9 +153,7 @@ def curves(self): r""" Return the curves in the arrangement as a tuple. - OUTPUT: - - A tuple. + OUTPUT: a tuple EXAMPLES:: @@ -182,9 +174,7 @@ def _repr_(self): r""" String representation for a curve arrangement. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -237,9 +227,7 @@ def union(self, other): - ``other`` -- a curve arrangement or something that can be converted into a curve arrangement - OUTPUT: - - A new curve arrangement. + OUTPUT: a new curve arrangement EXAMPLES:: @@ -334,9 +322,7 @@ def coordinate_ring(self): """ Return the coordinate ring of ``self``. - OUTPUT: - - The coordinate ring of the curve arrangement. + OUTPUT: the coordinate ring of the curve arrangement EXAMPLES:: @@ -450,7 +436,7 @@ def __init__(self, parent, curves, check=True): - ``parent`` -- the parent :class:`AffinePlaneCurveArrangements` - - ``curves`` -- a tuple of curves + - ``curves`` -- tuple of curves EXAMPLES:: @@ -499,9 +485,7 @@ def fundamental_group(self, simplified=True, vertical=True, - ``projective`` -- boolean (default: ``False``); to be used in the method for projective curves - OUTPUT: - - A finitely presented group. + OUTPUT: a finitely presented group .. NOTE:: @@ -799,7 +783,7 @@ def __init__(self, parent, curves, check=True): - ``parent`` -- the parent :class:`ProjectivePlaneCurveArrangements` - - ``curves`` -- a tuple of curves + - ``curves`` -- tuple of curves EXAMPLES:: @@ -832,9 +816,7 @@ def fundamental_group(self, simplified=True): - ``simplified`` -- boolean (default: ``True``); set if the group is simplified - OUTPUT: - - A finitely presented group. + OUTPUT: a finitely presented group .. NOTE:: @@ -1045,9 +1027,7 @@ def coordinate_ring(self): """ Return the coordinate ring. - OUTPUT: - - The coordinate ring of the curve arrangement. + OUTPUT: the coordinate ring of the curve arrangement EXAMPLES:: @@ -1063,7 +1043,7 @@ def change_ring(self, base_ring): INPUT: - - ``base_ring`` -- a ring; the new base ring. + - ``base_ring`` -- a ring; the new base ring OUTPUT: @@ -1106,9 +1086,7 @@ def _repr_(self): """ Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1182,9 +1160,7 @@ def ngens(self): """ Return the number of variables, i.e. 2 or 3, kept for completness. - OUTPUT: - - An integer, 2 or 3, depending if the arrangement is projective or affine. + OUTPUT: integer, 2 or 3, depending if the arrangement is projective or affine EXAMPLES:: @@ -1201,9 +1177,7 @@ def gens(self): """ Return the coordinates. - OUTPUT: - - A tuple of linear expressions, one for each linear variable. + OUTPUT: a tuple of linear expressions, one for each linear variable EXAMPLES:: @@ -1224,9 +1198,7 @@ def gen(self, i): - ``i`` -- integer - OUTPUT: - - A variable. + OUTPUT: a variable EXAMPLES:: diff --git a/src/sage/schemes/curves/point.py b/src/sage/schemes/curves/point.py old mode 100644 new mode 100755 index 5fd9e684876..e74e009b1ce --- a/src/sage/schemes/curves/point.py +++ b/src/sage/schemes/curves/point.py @@ -296,8 +296,8 @@ def tangents(self): r""" Return the tangents at this point of the affine plane curve this point is on. - OUTPUT: a list of polynomials in the coordinate ring of the ambient - space of the curve this point is on. + OUTPUT: list of polynomials in the coordinate ring of the ambient + space of the curve this point is on EXAMPLES:: @@ -343,7 +343,7 @@ def is_transverse(self, D): INPUT: - - ``D`` -- a curve in the same ambient space as the curve this point is on. + - ``D`` -- a curve in the same ambient space as the curve this point is on EXAMPLES:: diff --git a/src/sage/schemes/curves/projective_curve.py b/src/sage/schemes/curves/projective_curve.py old mode 100644 new mode 100755 index 09a86d2ae20..2757f11ca81 --- a/src/sage/schemes/curves/projective_curve.py +++ b/src/sage/schemes/curves/projective_curve.py @@ -238,10 +238,10 @@ def affine_patch(self, i, AA=None): - ``i`` -- affine coordinate chart of the projective ambient space of this curve to compute affine patch with respect to - - ``AA`` -- (default: None) ambient affine space, this is constructed + - ``AA`` -- (default: ``None``) ambient affine space, this is constructed if it is not given - OUTPUT: A curve in affine space. + OUTPUT: a curve in affine space EXAMPLES:: @@ -280,16 +280,16 @@ def projection(self, P=None, PS=None): INPUT: - - ``P`` -- (default: None) a point not on this curve that will be used - to define the projection map; this is constructed if not specified. + - ``P`` -- (default: ``None``) a point not on this curve that will be used + to define the projection map; this is constructed if not specified - - ``PS`` -- (default: None) the projective space the projected curve + - ``PS`` -- (default: ``None``) the projective space the projected curve will be defined in. This space must be defined over the same base ring as this curve, and must have dimension one less than that of the ambient space of this curve. This space will be constructed if not specified. - OUTPUT: A tuple of + OUTPUT: a tuple of - a scheme morphism from this curve into a projective space of dimension one less than that of the ambient space of this curve @@ -499,12 +499,12 @@ def plane_projection(self, PP=None): INPUT: - - ``PP`` -- (default: None) the projective plane the projected curve + - ``PP`` -- (default: ``None``) the projective plane the projected curve will be defined in. This space must be defined over the same base field as this curve, and must have dimension two. This space is constructed if not specified. - OUTPUT: A tuple of + OUTPUT: a tuple of - a scheme morphism from this curve into a projective plane @@ -639,10 +639,12 @@ def divisor_of_function(self, r): """ Return the divisor of a function on a curve. - INPUT: ``r`` is a rational function on X + INPUT: + + - ``r`` is a rational function on X - OUTPUT: A list. The divisor of r represented as a list of coefficients and - points. (TODO: This will change to a more structural output in the + OUTPUT: list; the divisor of r represented as a list of coefficients + and points. (TODO: This will change to a more structural output in the future.) EXAMPLES:: @@ -685,7 +687,7 @@ def local_coordinates(self, pt, n): INPUT: - ``pt`` -- a rational point on X which is not a point of ramification - for the projection `(x,y) \to x`. + for the projection `(x,y) \to x` - ``n`` -- the number of terms desired @@ -754,17 +756,16 @@ def plot(self, *args, **kwds): INPUT: - - ``self`` -- an affine plane curve + - ``self`` -- an affine plane curve - - ``patch`` -- (optional) the affine patch to be plotted; if not - specified, the patch corresponding to the last projective - coordinate being nonzero + - ``patch`` -- (optional) the affine patch to be plotted; if not + specified, the patch corresponding to the last projective + coordinate being nonzero - - ``*args`` -- optional tuples (variable, minimum, maximum) for - plotting dimensions + - ``*args`` -- (optional) tuples (variable, minimum, maximum) for + plotting dimensions - - ``**kwds`` -- optional keyword arguments passed on to - ``implicit_plot`` + - ``**kwds`` -- optional keyword arguments passed on to ``implicit_plot`` EXAMPLES: @@ -902,7 +903,7 @@ def degree(self): For a plane curve, this is just the degree of its defining polynomial. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -922,12 +923,12 @@ def tangents(self, P, factor=True): INPUT: - - ``P`` -- a point on this curve. + - ``P`` -- a point on this curve - - ``factor`` -- (default: ``True``) whether to attempt computing the + - ``factor`` -- boolean (default: ``True``); whether to attempt computing the polynomials of the individual tangent lines over the base field of this curve, or to just return the polynomial corresponding to the union of - the tangent lines (which requires fewer computations). + the tangent lines (which requires fewer computations) OUTPUT: @@ -1000,12 +1001,13 @@ def is_ordinary_singularity(self, P): INPUT: - - ``P`` -- a point on this curve. + - ``P`` -- a point on this curve OUTPUT: - - Boolean. True or False depending on whether ``P`` is or is not an ordinary singularity of this - curve, respectively. An error is raised if ``P`` is not a singular point of this curve. + boolean; ``True`` or ``False`` depending on whether ``P`` is or is not + an ordinary singularity of this curve, respectively. An error is raised + if ``P`` is not a singular point of this curve. EXAMPLES:: @@ -1124,12 +1126,12 @@ def excellent_position(self, Q): INPUT: - - ``Q`` -- a point on this curve. + - ``Q`` -- a point on this curve OUTPUT: - - a scheme morphism from this curve to a curve in excellent position that is a restriction of a change - of coordinates map of the projective plane. + A scheme morphism from this curve to a curve in excellent position that + is a restriction of a change of coordinates map of the projective plane. EXAMPLES:: @@ -1530,11 +1532,11 @@ def is_transverse(self, C, P): INPUT: - - ``C`` -- a curve in the ambient space of this curve. + - ``C`` -- a curve in the ambient space of this curve - - ``P`` -- a point in the intersection of both curves. + - ``P`` -- a point in the intersection of both curves - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1681,7 +1683,6 @@ def tangent_line(self, p): sage: C.tangent_line(p) Projective Curve over Rational Field defined by -2*x + y + w, -3*x + z + 2*w - """ for i in range(len(p)): if p[i]: @@ -1816,9 +1817,7 @@ def rational_parameterization(self): The rational parameterization may have coefficients in a quadratic extension of the rational field. - OUTPUT: - - - a birational map between `\mathbb{P}^{1}` and this curve, given as a scheme morphism. + OUTPUT: a birational map between `\mathbb{P}^{1}` and this curve, given as a scheme morphism EXAMPLES:: @@ -1872,9 +1871,9 @@ def rational_parameterization(self): def riemann_surface(self, **kwargs): r""" - Return the complex Riemann surface determined by this curve + Return the complex Riemann surface determined by this curve. - OUTPUT: A :class:`~sage.schemes.riemann_surfaces.riemann_surface.RiemannSurface` object. + OUTPUT: a :class:`~sage.schemes.riemann_surfaces.riemann_surface.RiemannSurface` object EXAMPLES:: @@ -1883,7 +1882,6 @@ def riemann_surface(self, **kwargs): sage: C.riemann_surface() Riemann surface defined by polynomial f = x^3 + 3*y^3 + 5 = 0, with 53 bits of precision - """ return self.affine_patch(2).riemann_surface(**kwargs) @@ -1902,9 +1900,7 @@ def rational_points_iterator(self): - ``self`` -- a projective curve - OUTPUT: - - A generator of all the rational points on the curve defined over its base field. + OUTPUT: a generator of all the rational points on the curve defined over its base field EXAMPLES:: @@ -1968,7 +1964,6 @@ def rational_points_iterator(self): Traceback (most recent call last): ... StopIteration - """ g = self.defining_polynomial() K = g.parent().base_ring() @@ -2011,11 +2006,9 @@ def _points_via_singular(self, sort=True): INPUT: - - - ``sort`` -- bool (default: ``True``), if ``True`` return the - point list sorted. If ``False``, returns the points in the order - computed by Singular. - + - ``sort`` -- boolean (default: ``True``); if ``True`` return the + point list sorted. If ``False``, returns the points in the order + computed by Singular. EXAMPLES:: @@ -2032,10 +2025,10 @@ def _points_via_singular(self, sort=True): (0 : 0 : 1), (2 : 3 : 1)] - .. note:: + .. NOTE:: The Brill-Noether package does not always work (i.e., the - 'bn' algorithm. When it fails a :class:`RuntimeError` exception is + 'bn' algorithm. When it fails a :exc:`RuntimeError` exception is raised. """ f = self.defining_polynomial()._singular_() @@ -2082,10 +2075,10 @@ def riemann_roch_basis(self, D): INPUT: - - ``D`` -- a divisor + - ``D`` -- a divisor - OUTPUT: A list of function field elements that form a basis of the - Riemann-Roch space. + OUTPUT: list of function field elements that form a basis of the + Riemann-Roch space EXAMPLES:: @@ -2155,28 +2148,28 @@ def riemann_roch_basis(self, D): V = [(sage_eval(a, vars)/sage_eval(b, vars)) for a, b in LG] return V - def rational_points(self, algorithm="enum", sort=True): + def rational_points(self, algorithm='enum', sort=True): r""" Return the rational points on this curve. INPUT: - - ``algorithm`` -- one of + - ``algorithm`` -- one of - - ``'enum'`` -- straightforward enumeration + - ``'enum'`` -- straightforward enumeration - - ``'bn'`` -- via Singular's brnoeth package. + - ``'bn'`` -- via Singular's brnoeth package - - ``sort`` -- boolean (default: ``True``); whether the output - points should be sorted. If False, the order of the output + - ``sort`` -- boolean (default: ``True``); whether the output + points should be sorted. If ``False``, the order of the output is non-deterministic. - OUTPUT: A list of all the rational points on the curve, possibly sorted. + OUTPUT: list of all the rational points on the curve, possibly sorted .. NOTE:: The Brill-Noether package does not always work (i.e., the 'bn' - algorithm. When it fails a :class:`RuntimeError` exception is raised. + algorithm. When it fails a :exc:`RuntimeError` exception is raised. EXAMPLES:: @@ -2231,7 +2224,6 @@ def rational_points(self, algorithm="enum", sort=True): sage: C = Curve(f); pts = C.rational_points() sage: pts [(0 : 0 : 1), (0 : 1 : 0), (1 : 0 : 0)] - """ if algorithm == "enum": points = list(self.rational_points_iterator()) @@ -2247,8 +2239,8 @@ def rational_points(self, algorithm="enum", sort=True): return self._points_via_singular(sort=sort) if algorithm == "all": - S_enum = self.rational_points(algorithm="enum") - S_bn = self.rational_points(algorithm="bn") + S_enum = self.rational_points(algorithm='enum') + S_bn = self.rational_points(algorithm='bn') if S_enum != S_bn: raise RuntimeError("Bug in rational_points -- different\ algorithms give different answers for\ @@ -2358,7 +2350,7 @@ def function(self, f): - ``f`` -- a fraction of homogeneous polynomials of the coordinate ring of the ambient space of the curve - OUTPUT: An element of the function field. + OUTPUT: an element of the function field EXAMPLES:: @@ -2412,7 +2404,7 @@ def pull_from_function_field(self, f): INPUT: - - ``f`` -- an element of the function field + - ``f`` -- an element of the function field OUTPUT: @@ -2533,7 +2525,6 @@ def _singularities(self): sage: D = Curve(x) sage: D._singularities [] - """ S = self.ambient_space().coordinate_ring() to_F = self._map_to_function_field @@ -2840,7 +2831,7 @@ def closed_points(self, degree=1): INPUT: - - ``degree`` -- a positive integer + - ``degree`` -- positive integer EXAMPLES:: @@ -2897,7 +2888,6 @@ def L_polynomial(self, name='t'): sage: Cbar = C.projective_closure() sage: Cbar.L_polynomial() 9*t^4 - 3*t^3 + t^2 - t + 1 - """ F = self.function_field() L = F.L_polynomial() @@ -2935,7 +2925,6 @@ def number_of_rational_points(self, r=1): Finite Field in z3 of size 3^3 sage: len(D.closed_points()) 21 - """ q = self.base_ring().order() L = self.L_polynomial() @@ -2987,12 +2976,12 @@ def Hasse_bounds(q, genus=1): INPUT: - - ``q`` (int) -- a prime power + - ``q`` -- integer; a prime power - - ``genus`` (int, default 1) -- a non-negative integer, + - ``genus`` -- nonnegative integer (default: 1) - OUTPUT: A tuple. The Hasse bounds (lb,ub) for the cardinality of a curve of - genus ``genus`` defined over `\GF{q}`. + OUTPUT: tuple; the Hasse bounds (lb,ub) for the cardinality of a curve of + genus ``genus`` defined over `\GF{q}` EXAMPLES:: diff --git a/src/sage/schemes/curves/zariski_vankampen.py b/src/sage/schemes/curves/zariski_vankampen.py old mode 100644 new mode 100755 index 4afdb48c743..b2b9d7cd5b2 --- a/src/sage/schemes/curves/zariski_vankampen.py +++ b/src/sage/schemes/curves/zariski_vankampen.py @@ -81,13 +81,11 @@ def braid_from_piecewise(strands): INPUT: - - ``strands`` -- a list of lists of tuples ``(t, c1, c2)``, where ``t`` + - ``strands`` -- list of lists of tuples ``(t, c1, c2)``, where ``t`` is a number between 0 and 1, and ``c1`` and ``c2`` are rationals - or algebraic reals. + or algebraic reals - OUTPUT: - - The braid formed by the piecewise linear strands. + OUTPUT: the braid formed by the piecewise linear strands EXAMPLES:: @@ -180,12 +178,10 @@ def discrim(pols) -> tuple: INPUT: - - ``pols`` -- a list or tuple of polynomials in two variables with - coefficients in a number field with a fixed embedding in `\QQbar`. + - ``pols`` -- list or tuple of polynomials in two variables with + coefficients in a number field with a fixed embedding in `\QQbar` - OUTPUT: - - A tuple with the roots of the discriminant in `\QQbar`. + OUTPUT: a tuple with the roots of the discriminant in `\QQbar` EXAMPLES:: @@ -231,7 +227,7 @@ def corrected_voronoi_diagram(points): INPUT: - - ``points`` -- a tuple of complex numbers + - ``points`` -- tuple of complex numbers OUTPUT: @@ -287,13 +283,13 @@ def orient_circuit(circuit, convex=False, precision=53, verbose=False): INPUT: - - ``circuit`` -- a circuit in the graph of a Voronoi Diagram, given + - ``circuit`` -- a circuit in the graph of a Voronoi Diagram, given by a list of edges - ``convex`` -- boolean (default: ``False``); if set to ``True`` a simpler computation is made - - ``precision`` -- bits of precision (default: 53) + - ``precision`` -- bits of precision (default: 53) - ``verbose`` -- boolean (default: ``False``); for testing purposes @@ -391,10 +387,10 @@ def voronoi_cells(V, vertical_lines=frozenset()): - ``G`` -- the graph of the 1-skeleton of ``V`` - ``E`` -- the subgraph of the boundary - ``p`` -- a vertex in ``E`` - - ``EC`` -- a list of vertices (representing a counterclockwise orientation + - ``EC`` -- list of vertices (representing a counterclockwise orientation of ``E``) with identical first and last elements) - ``DG`` -- the dual graph of ``V``, where the vertices are labelled - by the compact regions of ``V`` and the edges by their dual edges. + by the compact regions of ``V`` and the edges by their dual edges - ``vertical_regions`` -- dictionary for the regions associated with vertical lines @@ -493,7 +489,7 @@ def followstrand(f, factors, x0, x1, y0a, prec=53) -> list: INPUT: - ``f`` -- an irreducible polynomial in two variables - - ``factors`` -- a list of irreducible polynomials in two variables + - ``factors`` -- list of irreducible polynomials in two variables - ``x0`` -- a complex value, where the homotopy starts - ``x1`` -- a complex value, where the homotopy ends - ``y0a`` -- an approximate solution of the polynomial `F(y) = f(x_0, y)` @@ -624,11 +620,9 @@ def fieldI(field): INPUT: - - ``field`` -- a number field with an embedding in `\QQbar`. - - OUTPUT: + - ``field`` -- a number field with an embedding in `\QQbar` - The extension ``F`` of ``field`` containing ``I`` with an embedding in `\QQbar`. + OUTPUT: the extension ``F`` of ``field`` containing ``I`` with an embedding in `\QQbar` EXAMPLES:: @@ -791,7 +785,7 @@ def populate_roots_interval_cache(inputs): INPUT: - - ``inputs`` -- a list of tuples ``(f, x0)`` + - ``inputs`` -- list of tuples ``(f, x0)`` EXAMPLES:: @@ -811,7 +805,6 @@ def populate_roots_interval_cache(inputs): 0.4795466549853897? - 1.475892845355996?*I: 1.? - 2.?*I, 0.4795466549853897? + 1.475892845355996?*I: 1.? + 2.?*I, 14421467174121563/9293107134194871: 2.? + 0.?*I} - """ global roots_interval_cache tocompute = [inp for inp in inputs if inp not in roots_interval_cache] @@ -834,15 +827,13 @@ def braid_in_segment(glist, x0, x1, precision={}): INPUT: - - ``glist`` -- a tuple of polynomials in two variables + - ``glist`` -- tuple of polynomials in two variables - ``x0`` -- a Gauss rational - ``x1`` -- a Gauss rational - - ``precision`` -- a dictionary (default: `{}`) which assigns a number + - ``precision`` -- dictionary (default: `{}`) which assigns a number precision bits to each element of ``glist`` - OUTPUT: - - A braid. + OUTPUT: a braid EXAMPLES:: @@ -955,7 +946,7 @@ def geometric_basis(G, E, EC0, p, dual_graph, vertical_regions={}) -> list: - ``E`` -- a subgraph of ``G`` which is a cycle containing the bounded edges touching an unbounded region of a Voronoi Diagram - - ``EC0`` -- A counterclockwise orientation of the vertices of ``E`` + - ``EC0`` -- a counterclockwise orientation of the vertices of ``E`` - ``p`` -- a vertex of ``E`` @@ -969,7 +960,7 @@ def geometric_basis(G, E, EC0, p, dual_graph, vertical_regions={}) -> list: the vertices of ``dual_graph`` to fix regions associated with vertical lines - OUTPUT: A geometric basis and a dictionary. + OUTPUT: a geometric basis and a dictionary The geometric basis is formed by a list of sequences of paths. Each path is a ist of vertices, that form a closed path in ``G``, based at ``p``, that goes @@ -1233,7 +1224,7 @@ def braid_monodromy(f, arrangement=(), vertical=False): - ``arrangement`` -- tuple (default: ``()``); an optional tuple of polynomials whose product equals ``f`` - - ``vertical`` -- boolean (default: ``False`); if set to ``True``, + - ``vertical`` -- boolean (default: ``False``); if set to ``True``, ``arrangements`` contains more than one polynomial, some of them are of degree `1` in `x` and degree `0` in `y`, and none of the other components have vertical asymptotes, then these @@ -1256,7 +1247,7 @@ def braid_monodromy(f, arrangement=(), vertical=False): of a braid corresponding to a vertical line with index ``i`` in ``arrangement``, then ``dv[j] = i``. - - A non-negative integer: the number of strands of the braids, + - A nonnegative integer: the number of strands of the braids, only necessary if the list of braids is empty. .. NOTE:: @@ -1500,8 +1491,8 @@ def braid2rels(L): INPUT: - - ``L`` -- a tuple whose first element is a positive braid and the second - element is a list of permutation braids. + - ``L`` -- tuple whose first element is a positive braid and the second + element is a list of permutation braids OUTPUT: @@ -1570,10 +1561,10 @@ def fundamental_group_from_braid_mon(bm, degree=None, INPUT: - - ``bm`` -- a list of braids + - ``bm`` -- list of braids - ``degree`` -- integer (default: ``None``); only needed if the braid - monodromy is an empty list. + monodromy is an empty list - ``simplified`` -- boolean (default: ``True``); if set to ``True`` the presentation will be simplified (see below) @@ -1591,7 +1582,7 @@ def fundamental_group_from_braid_mon(bm, degree=None, - ``vertical`` -- list of integers (default: ``[]``); the indices in ``[0 .. r - 1]`` of the braids that surround a vertical line - If ``projective``` is ``False`` and ``puiseux`` is + If ``projective`` is ``False`` and ``puiseux`` is ``True``, a Zariski-VanKampen presentation is returned. OUTPUT: @@ -1693,7 +1684,7 @@ def fundamental_group(f, simplified=True, projective=False, puiseux=True): with a wedge of 2-spheres. One relation is added if ``projective`` is set to ``True``. - If ``projective``` is ``False`` and ``puiseux`` is + If ``projective`` is ``False`` and ``puiseux`` is ``True``, a Zariski-VanKampen presentation is returned. OUTPUT: diff --git a/src/sage/schemes/cyclic_covers/charpoly_frobenius.py b/src/sage/schemes/cyclic_covers/charpoly_frobenius.py old mode 100644 new mode 100755 index b7cf928853c..649e565e797 --- a/src/sage/schemes/cyclic_covers/charpoly_frobenius.py +++ b/src/sage/schemes/cyclic_covers/charpoly_frobenius.py @@ -32,9 +32,8 @@ def charpoly_frobenius(frob_matrix, charpoly_prec, p, weight, a=1, known_factor= - ``known_factor`` -- the list of coefficients of the known factor - OUTPUT: - - A list of integers corresponding to the characteristic polynomial of the Frobenius action. + OUTPUT: list of integers corresponding to the characteristic polynomial + of the Frobenius action EXAMPLES:: diff --git a/src/sage/schemes/cyclic_covers/constructor.py b/src/sage/schemes/cyclic_covers/constructor.py old mode 100644 new mode 100755 index 6ff76f69c0a..92366cfbb79 --- a/src/sage/schemes/cyclic_covers/constructor.py +++ b/src/sage/schemes/cyclic_covers/constructor.py @@ -25,13 +25,12 @@ def CyclicCover(r, f, names=None, check_smooth=True): - ``r`` -- the order of the cover - - ``f`` -- univariate polynomial if not given, then it defaults to 0. + - ``f`` -- univariate polynomial if not given, then it defaults to 0 - - ``names`` (default: ``["x","y"]``) -- names for the - coordinate functions + - ``names`` -- (default: ``["x","y"]``) names for the coordinate functions - - ``check_squarefree`` (default: ``True``) -- test if - the input defines a unramified cover of the projective line. + - ``check_squarefree`` -- boolean (default: ``True``); test if + the input defines a unramified cover of the projective line .. WARNING:: @@ -97,14 +96,12 @@ def CyclicCover(r, f, names=None, check_smooth=True): Input with integer coefficients creates objects with the integers as base ring, but only checks smoothness over `\QQ`, not over Spec(`\ZZ`). - In other words, it is checked that the discriminant is non-zero, but it is + In other words, it is checked that the discriminant is nonzero, but it is not checked whether the discriminant is a unit in `\ZZ^*`:: sage: R. = ZZ[] sage: CyclicCover(5, (x^3-x+2)*(x^6-1)) Cyclic Cover of P^1 over Integer Ring defined by y^5 = x^9 - x^7 + 2*x^6 - x^3 + x - 2 - - """ if not isinstance(f, Polynomial): raise TypeError("Arguments f (= %s) must be a polynomial" % (f,)) diff --git a/src/sage/schemes/cyclic_covers/cycliccover_finite_field.py b/src/sage/schemes/cyclic_covers/cycliccover_finite_field.py old mode 100644 new mode 100755 index 8515d7a849b..850d9e975ea --- a/src/sage/schemes/cyclic_covers/cycliccover_finite_field.py +++ b/src/sage/schemes/cyclic_covers/cycliccover_finite_field.py @@ -87,16 +87,16 @@ def _N0_nodenominators(p, g, n): """ - Return the necessary p-adic precision for the Frobenius matrix to deduce + Return the necessary `p`-adic precision for the Frobenius matrix to deduce the characteristic polynomial of Frobenius using the Newton identities, using :meth:`charpoly_frobenius`, which assumes that the Frobenius matrix is integral, i.e., has no denominators. INPUT: - - `p` -- prime - - `g` -- genus - - `n` -- degree of residue field + - ``p`` -- prime + - ``g`` -- genus + - ``n`` -- degree of residue field TESTS:: @@ -123,7 +123,6 @@ def __init__(self, AA, r, f, names=None, verbose=0): 1 + 8*t + 102*t^2 + O(t^3) sage: C.frobenius_polynomial().reverse()(t)/((1-t)*(1-p*t)) + O(t^5) 1 + 8*t + 102*t^2 + 1384*t^3 + 18089*t^4 + O(t^5) - """ cycliccover_generic.CyclicCover_generic.__init__(self, AA, r, f, names=names) self._verbose = verbose @@ -233,22 +232,22 @@ def right_side_log(n): self._Zq = IntegerModRing(self._p**self._N) if self._sqrtp: self._Zq0 = IntegerModRing(self._p**(self._N - 1)) - self._Qq = Qq(self._p, prec=self._N, type="capped-rel") + self._Qq = Qq(self._p, prec=self._N, type='capped-rel') self._w = 1 else: self._Zq = Zq( self._q, - names="w", + names='w', modulus=self._Fq.polynomial(), prec=self._N, - type="capped-abs", + type='capped-abs', ) self._w = self._Zq.gen() self._Qq = self._Zq.fraction_field() else: self._Zq = Qq( self._q, - names="w", + names='w', modulus=self._Fq.polynomial(), prec=self._N + self._extraworkingprec, ) @@ -328,14 +327,14 @@ def _divide_vector(self, D, vect, R): def _frob_sparse(self, i, j, N0): r""" - Compute `Frob(x^i y^(-j) dx ) / dx` for y^r = f(x) with N0 terms + Compute `Frob(x^i y^(-j) dx ) / dx` for y^r = f(x) with N0 terms. INPUT: - - ``i`` -- The power of x in the expression `Frob(x^i dx/y^j) / dx` + - ``i`` -- the power of x in the expression `Frob(x^i dx/y^j) / dx` - - ``j`` -- The (negative) power of y in the expression - `Frob(x^i dx/y^j) / dx` + - ``j`` -- the (negative) power of y in the expression + `Frob(x^i dx/y^j) / dx` OUTPUT: @@ -584,7 +583,6 @@ def _vertical_matrix_reduction(self, s0): [ 74203580341 2817857481 75142866164] [108017870113 0 2817857481] )) - """ d = self._d @@ -825,7 +823,7 @@ def _reduce_vector_horizontal_plain(self, G, e, s, k=1): def _reduce_vector_vertical(self, G, s0, s, k=1): r""" - Reduce the vector `G` representing an element of `W_{-1,rs + s0}` by `r k` steps + Reduce the vector `G` representing an element of `W_{-1,rs + s0}` by `r k` steps. INPUT: @@ -834,7 +832,7 @@ def _reduce_vector_vertical(self, G, s0, s, k=1): OUTPUT: - a vector -- `H \in W_{-1, r*(s - k) + s0}` such that - `G y^{-(r*s + s0)} dx \cong H y^{-(r*(s -k) + s0)} dx` + `G y^{-(r*s + s0)} dx \cong H y^{-(r*(s -k) + s0)} dx` TESTS:: @@ -906,7 +904,6 @@ def _initialize_fat_vertical(self, s0, max_upper_target): """ Initialise reduction matrices for vertical reductions for blocks from `s0` to `s0 + max_upper_target`. - TESTS:: sage: p = 4999 @@ -953,8 +950,8 @@ def _frob(self, i, j, N0): INPUT: - - `i`,`j` -- exponents of the basis differential - - `N0` -- desired p-adic precision for the Frobenius expansion + - ``i``, ``j`` -- exponents of the basis differential + - ``N0`` -- desired `p`-adic precision for the Frobenius expansion TESTS:: @@ -1019,7 +1016,7 @@ def _frob(self, i, j, N0): @cached_method def frobenius_matrix(self, N=None): """ - Compute p-adic Frobenius matrix to precision p^N. + Compute `p`-adic Frobenius matrix to precision `p^N`. If `N` not supplied, a default value is selected, which is the minimum needed to recover the charpoly unambiguously. @@ -1243,8 +1240,6 @@ def frobenius_polynomial(self): ....: else: ....: True True - - """ self._init_frob() F = self.frobenius_matrix(self._N0) diff --git a/src/sage/schemes/cyclic_covers/cycliccover_generic.py b/src/sage/schemes/cyclic_covers/cycliccover_generic.py old mode 100644 new mode 100755 index 2ef6b734300..9b21549a8b1 --- a/src/sage/schemes/cyclic_covers/cycliccover_generic.py +++ b/src/sage/schemes/cyclic_covers/cycliccover_generic.py @@ -44,7 +44,7 @@ class CyclicCover_generic(AffinePlaneCurve): def __init__(self, AA, r, f, names=None): """ - Cyclic covers over a general ring + Cyclic covers over a general ring. INPUT: @@ -52,10 +52,10 @@ def __init__(self, AA, r, f, names=None): - ``r`` -- degree of the cover - - ``f`` -- univariate polynomial + - ``f`` -- univariate polynomial - - ``names`` (default: ``["x","y"]``) -- names for the - coordinate functions + - ``names`` -- (default: ``["x","y"]``); names for the + coordinate functions TESTS:: @@ -244,7 +244,6 @@ def projective_closure(self, **kwds): sage: ZZx. = ZZ[] sage: CyclicCover(5, x^5 + x + 1).projective_closure() Projective Plane Curve over Integer Ring defined by x0^5 + x0^4*x1 + x1^5 - x2^5 - """ # test d = 3 and 4 if self._d == self._r: @@ -252,7 +251,7 @@ def projective_closure(self, **kwds): else: raise NotImplementedError("Weighted Projective Space is not implemented") - def cover_polynomial(self, K=None, var="x"): + def cover_polynomial(self, K=None, var='x'): """ Return the polynomial defining the cyclic cover. @@ -260,7 +259,6 @@ def cover_polynomial(self, K=None, var="x"): sage: ZZx. = ZZ[]; CyclicCover(5, x^5 + x + 1).cover_polynomial() x^5 + x + 1 - """ if K is None: diff --git a/src/sage/schemes/elliptic_curves/BSD.py b/src/sage/schemes/elliptic_curves/BSD.py old mode 100644 new mode 100755 index 7b808d8d461..73f1f57d41c --- a/src/sage/schemes/elliptic_curves/BSD.py +++ b/src/sage/schemes/elliptic_curves/BSD.py @@ -156,7 +156,7 @@ def pari_two_descent_work(E): - ``E`` -- an elliptic curve - OUTPUT: A tuple of 5 elements with the first 4 being integers. + OUTPUT: a tuple of 5 elements with the first 4 being integers - a lower bound on the rank @@ -183,7 +183,6 @@ def pari_two_descent_work(E): sage: E = EllipticCurve('66b3') sage: pari_two_descent_work(E) (0, 0, 2, 2, []) - """ ep = E.pari_curve() lower, rank_upper_bd, s, pts = ep.ellrank() @@ -304,24 +303,24 @@ def prove_BSD(E, verbosity=0, two_desc='mwrank', proof=None, secs_hi=5, - ``E`` -- an elliptic curve - - ``verbosity`` -- int, how much information about the proof to print. + - ``verbosity`` -- integer; how much information about the proof to print - 0: print nothing - 1: print sketch of proof - 2: print information about remaining primes - - ``two_desc`` -- string (default ``'mwrank'``), what to use for the - two-descent. Options are ``'mwrank', 'pari', 'sage'`` + - ``two_desc`` -- string (default: ``'mwrank'``); what to use for the + two-descent. Options are ``'mwrank', 'pari', 'sage'``. - - ``proof`` -- bool or None (default: None, see - proof.elliptic_curve or sage.structure.proof). If False, this + - ``proof`` -- boolean or ``None`` (default: None, see + proof.elliptic_curve or sage.structure.proof). If ``False``, this function just immediately returns the empty list. - ``secs_hi`` -- maximum number of seconds to try to compute the Heegner index before switching over to trying to compute the Heegner index bound. (Rank 0 only!) - - ``return_BSD`` -- bool (default: ``False``) whether to return an object + - ``return_BSD`` -- boolean (default: ``False``); whether to return an object which contains information to reconstruct a proof .. NOTE:: @@ -498,7 +497,6 @@ def prove_BSD(E, verbosity=0, two_desc='mwrank', proof=None, secs_hi=5, p = 2: True by 2-descent True for p not in {2} by Kolyvagin. [] - """ if proof is None: from sage.structure.proof.proof import get_flag diff --git a/src/sage/schemes/elliptic_curves/Qcurves.py b/src/sage/schemes/elliptic_curves/Qcurves.py old mode 100644 new mode 100755 index e0f55597f90..b8e9b7411fb --- a/src/sage/schemes/elliptic_curves/Qcurves.py +++ b/src/sage/schemes/elliptic_curves/Qcurves.py @@ -32,15 +32,15 @@ def is_Q_curve(E, maxp=100, certificate=False, verbose=False): INPUT: - - ``E`` (elliptic curve) -- an elliptic curve over a number field. + - ``E`` -- elliptic curve over a number field - - ``maxp`` (int, default 100): bound on primes used for checking + - ``maxp`` -- integer (default: 100); bound on primes used for checking necessary local conditions. The result will not depend on this, but using a larger value may return ``False`` faster. - - ``certificate`` (bool, default ``False``): if ``True`` then a + - ``certificate`` -- boolean (default: ``False``); if ``True`` then a second value is returned giving a certificate for the - `\QQ`-curve property. + `\QQ`-curve property OUTPUT: @@ -82,7 +82,7 @@ def is_Q_curve(E, maxp=100, certificate=False, verbose=False): the conductor norm. 3. For all primes `p\mid N` check that the valuations of `j` at - all `P\mid p` are either all negative or all non-negative; if not, + all `P\mid p` are either all negative or all nonnegative; if not, return ``False``. 4. For `p\le maxp`, `p\not\mid N`, check that either `E` is @@ -402,13 +402,13 @@ def Step4Test(E, B, oldB=0, verbose=False): INPUT: - - `E` (elliptic curve): an elliptic curve defined over a number field + - ``E`` -- elliptic curve defined over a number field - - `B` (integer): upper bound on primes to test + - ``B`` -- integer; upper bound on primes to test - - ``oldB`` (integer, default 0): lower bound on primes to test + - ``oldB`` -- integer (default: 0); lower bound on primes to test - - ``verbose`` (boolean, default ``False``): verbosity flag + - ``verbose`` -- boolean (default: ``False``); verbosity flag OUTPUT: @@ -496,9 +496,9 @@ def conjugacy_test(jlist, verbose=False): INPUT: - - ``jlist`` (list): a list of algebraic numbers in the same field + - ``jlist`` -- list of algebraic numbers in the same field - - ``verbose`` (boolean, default ``False``): verbosity flag + - ``verbose`` -- boolean (default: ``False``); verbosity flag OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/cm.py b/src/sage/schemes/elliptic_curves/cm.py old mode 100644 new mode 100755 index 9580a90038c..faf4f75f2ce --- a/src/sage/schemes/elliptic_curves/cm.py +++ b/src/sage/schemes/elliptic_curves/cm.py @@ -51,9 +51,9 @@ def hilbert_class_polynomial(D, algorithm=None): INPUT: - - ``D`` (int) -- a negative integer congruent to 0 or 1 modulo 4. + - ``D`` -- negative integer congruent to 0 or 1 modulo 4 - - ``algorithm`` (string, default None). + - ``algorithm`` -- string (default: ``None``) OUTPUT: @@ -89,19 +89,19 @@ def hilbert_class_polynomial(D, algorithm=None): x^3 + 3491750*x^2 - 5151296875*x + 12771880859375 sage: hilbert_class_polynomial(-37*4) x^2 - 39660183801072000*x - 7898242515936467904000000 - sage: hilbert_class_polynomial(-37*4, algorithm="magma") # optional - magma + sage: hilbert_class_polynomial(-37*4, algorithm='magma') # optional - magma x^2 - 39660183801072000*x - 7898242515936467904000000 sage: hilbert_class_polynomial(-163) x + 262537412640768000 - sage: hilbert_class_polynomial(-163, algorithm="sage") + sage: hilbert_class_polynomial(-163, algorithm='sage') x + 262537412640768000 - sage: hilbert_class_polynomial(-163, algorithm="magma") # optional - magma + sage: hilbert_class_polynomial(-163, algorithm='magma') # optional - magma x + 262537412640768000 TESTS:: - sage: all(hilbert_class_polynomial(d, algorithm="arb") == - ....: hilbert_class_polynomial(d, algorithm="sage") + sage: all(hilbert_class_polynomial(d, algorithm='arb') == + ....: hilbert_class_polynomial(d, algorithm='sage') ....: for d in range(-1,-100,-1) if d % 4 in [0, 1]) True """ @@ -182,10 +182,9 @@ def is_HCP(f, check_monic_irreducible=True): INPUT: - - ``f`` -- a polynomial in `\ZZ[X]`. - - ``check_monic_irreducible`` (boolean, default ``True``) -- if - ``True``, check that ``f`` is a monic, irreducible, integer - polynomial. + - ``f`` -- a polynomial in `\ZZ[X]` + - ``check_monic_irreducible`` -- boolean (default: ``True``); if ``True``, + check that ``f`` is a monic, irreducible, integer polynomial OUTPUT: @@ -294,9 +293,9 @@ def OrderClassNumber(D0,h0,f): INPUT: - - ``D0`` (integer) -- a negative fundamental discriminant - - ``h0`` (integer) -- the class number of the (maximal) imaginary quadratic order of discriminant ``D0`` - - ``f`` (integer) -- a positive integer + - ``D0`` -- integer; a negative fundamental discriminant + - ``h0`` -- integer; the class number of the (maximal) imaginary quadratic order of discriminant ``D0`` + - ``f`` -- positive integer OUTPUT: @@ -321,7 +320,6 @@ def OrderClassNumber(D0,h0,f): [1, 1, 2, 2, 2, 4, 4, 4, 6, 4, 6, 8, 6, 8, 8, 8, 8, 12, 10] sage: all([OrderClassNumber(D0,h,f) == (D0*f**2).class_number() for f in srange(1,20)]) True - """ if not D0.is_fundamental_discriminant(): raise ValueError("{} is not a fundamental discriminant".format(D0)) @@ -401,9 +399,8 @@ def cm_j_invariants_and_orders(K, proof=None): OUTPUT: - (list) A list of 3-tuples `(D,f,j)` where `j` is a CM - `j`-invariant in `K` with quadratic fundamental discriminant `D` - and conductor `f`. + A list of 3-tuples `(D,f,j)` where `j` is a CM `j`-invariant in `K` with + quadratic fundamental discriminant `D` and conductor `f`. EXAMPLES:: @@ -478,12 +475,10 @@ def cm_orders(h, proof=None): INPUT: - - `h` -- positive integer + - ``h`` -- positive integer - ``proof`` -- (default: proof.number_field()) - OUTPUT: - - - list of 2-tuples `(D,f)` sorted lexicographically by `(|D|, f)` + OUTPUT: list of 2-tuples `(D,f)` sorted lexicographically by `(|D|, f)` EXAMPLES:: @@ -628,7 +623,7 @@ class number `h`, and the number of fundamental negative discriminants with INPUT: - - `h` -- integer + - ``h`` -- integer EXAMPLES:: @@ -647,7 +642,6 @@ class number `h`, and the number of fundamental negative discriminants with Traceback (most recent call last): ... NotImplementedError: largest fundamental discriminant not available for class number 101 - """ h = Integer(h) if h <= 0: @@ -678,7 +672,7 @@ class number `h`, and the number of fundamental negative INPUT: - - `h` -- integer + - ``h`` -- integer EXAMPLES:: @@ -709,7 +703,6 @@ class number `h` is also the largest discriminant, but this is not (3763, 51) sage: largest_disc_with_class_number(6) (4075, 101) - """ h = Integer(h) if h <= 0: @@ -739,15 +732,13 @@ def discriminants_with_bounded_class_number(hmax, B=None, proof=None): INPUT: - ``hmax`` -- integer - - `B` -- integer or None; if None returns all pairs + - ``B`` -- integer or ``None``; if ``None`` returns all pairs - ``proof`` -- this code calls the PARI function :pari:`qfbclassno`, so it could give wrong answers when ``proof``==``False`` (though only for discriminants greater than `2\cdot10^{10}`). The default is the current value of ``proof.number_field()``. - OUTPUT: - - - dictionary + OUTPUT: dictionary .. NOTE:: @@ -783,7 +774,6 @@ def discriminants_with_bounded_class_number(hmax, B=None, proof=None): sage: sage.schemes.elliptic_curves.cm.discriminants_with_bounded_class_number(hmax=5, B=50) {1: [(-3, 1), (-3, 2), (-3, 3), (-4, 1), (-4, 2), (-7, 1), (-7, 2), (-8, 1), (-11, 1), (-19, 1), (-43, 1)], 2: [(-3, 4), (-4, 3), (-8, 2), (-15, 1), (-20, 1), (-24, 1), (-35, 1), (-40, 1)], 3: [(-11, 2), (-23, 1), (-31, 1)], 4: [(-39, 1)], 5: [(-47, 1)]} - """ hmax = Integer(hmax) global hDf_dict @@ -900,11 +890,11 @@ def is_cm_j_invariant(j, algorithm='CremonaSutherland', method=None): - ``j`` -- an element of a number field `K` - - ``algorithm`` (string, default 'CremonaSutherland') -- the algorithm - used, either 'CremonaSutherland' (the default, very much faster - for all but very small degrees), 'exhaustive' or 'reduction' + - ``algorithm`` -- string (default: ``'CremonaSutherland'``); the algorithm + used, either ``'CremonaSutherland'`` (the default, very much faster + for all but very small degrees), ``'exhaustive'`` or ``'reduction'`` - - ``method`` (string) -- deprecated name for ``algorithm`` + - ``method`` -- string; deprecated name for ``algorithm`` OUTPUT: @@ -965,7 +955,6 @@ def is_cm_j_invariant(j, algorithm='CremonaSutherland', method=None): sage: from sage.schemes.elliptic_curves.cm import is_cm_j_invariant sage: all(is_cm_j_invariant(j) == (True, (d,f)) for d,f,j in cm_j_invariants_and_orders(QQ)) True - """ if method: if not algorithm: diff --git a/src/sage/schemes/elliptic_curves/constructor.py b/src/sage/schemes/elliptic_curves/constructor.py old mode 100644 new mode 100755 index 21470bd890a..ebbc55e6799 --- a/src/sage/schemes/elliptic_curves/constructor.py +++ b/src/sage/schemes/elliptic_curves/constructor.py @@ -28,7 +28,7 @@ from sage.rings.rational_field import RationalField import sage.rings.abc -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.number_field.number_field_base import NumberField from sage.rings.finite_rings.finite_field_base import FiniteField from sage.rings.polynomial.multi_polynomial import MPolynomial @@ -65,7 +65,7 @@ class EllipticCurveFactory(UniqueFactory): - ``EllipticCurve(label)``: Returns the elliptic curve over `\QQ` from the Cremona database with the given label. The label is a - string, such as ``"11a"`` or ``"37b2"``. The letters in the + string, such as ``'11a'`` or ``'37b2'``. The letters in the label *must* be lower case (Cremona's new labeling). - ``EllipticCurve(R, [a1,a2,a3,a4,a6])``: Create the elliptic @@ -197,7 +197,7 @@ class EllipticCurveFactory(UniqueFactory): By default, when a rational value of `j` is given, the constructed curve is a minimal twist (minimal conductor for curves with that `j`-invariant). This can be changed by setting the optional - parameter ``minimal_twist``, which is True by default, to False:: + parameter ``minimal_twist``, which is ``True`` by default, to ``False``:: sage: EllipticCurve(j=100) Elliptic Curve defined by y^2 = x^3 + x^2 + 3392*x + 307888 over Rational Field @@ -504,10 +504,9 @@ def EllipticCurve_from_Weierstrass_polynomial(f): INPUT: - - ``f`` -- a inhomogeneous cubic polynomial in long Weierstrass - form. + - ``f`` -- a inhomogeneous cubic polynomial in long Weierstrass form - OUTPUT: The elliptic curve defined by it. + OUTPUT: the elliptic curve defined by it EXAMPLES:: @@ -613,9 +612,9 @@ def EllipticCurve_from_j(j, minimal_twist=True): INPUT: - - ``j`` -- an element of some field. + - ``j`` -- an element of some field - - ``minimal_twist`` (boolean, default: ``True``) -- If True and ``j`` + - ``minimal_twist``-- boolean (default: ``True``); if ``True`` and ``j`` is in `\QQ`, the curve returned is a minimal twist, i.e. has minimal conductor; when there is more than one curve with minimal conductor, the curve returned is the one whose label @@ -623,9 +622,7 @@ def EllipticCurve_from_j(j, minimal_twist=True): the one whose minimal a-invariants are first lexicographically. If `j` is not in `\QQ` this parameter is ignored. - OUTPUT: - - An elliptic curve with `j`-invariant `j`. + OUTPUT: an elliptic curve with `j`-invariant `j` EXAMPLES:: @@ -644,7 +641,7 @@ def EllipticCurve_from_j(j, minimal_twist=True): 1 The ``minimal_twist`` parameter (ignored except over `\QQ` and - True by default) controls whether or not a minimal twist is + ``True`` by default) controls whether or not a minimal twist is computed:: sage: EllipticCurve_from_j(100) @@ -685,7 +682,7 @@ def coefficients_from_j(j, minimal_twist=True): [1, 0, 0, 36, 3455] The ``minimal_twist`` parameter (ignored except over `\QQ` and - True by default) controls whether or not a minimal twist is + ``True`` by default) controls whether or not a minimal twist is computed:: sage: coefficients_from_j(100) @@ -777,15 +774,15 @@ def EllipticCurve_from_cubic(F, P=None, morphism=True): - ``F`` -- a homogeneous cubic in three variables with rational coefficients, as a polynomial ring element, defining a smooth - plane cubic curve `C`. + plane cubic curve `C` - ``P`` -- a 3-tuple `(x,y,z)` defining a projective point on `C`, or ``None``. If ``None`` then a rational flex will be used as a base point if one exists, otherwise an error will be raised. - - ``morphism`` -- boolean (default: ``True``). If ``True`` + - ``morphism`` -- boolean (default: ``True``); if ``True`` returns a birational isomorphism from `C` to a Weierstrass - elliptic curve `E`, otherwise just returns `E`. + elliptic curve `E`, otherwise just returns `E` OUTPUT: @@ -1098,7 +1095,7 @@ def EllipticCurve_from_cubic(F, P=None, morphism=True): # check the input R = F.parent() K = R.base_ring() - if not is_MPolynomialRing(R): + if not isinstance(R, MPolynomialRing_base): raise TypeError('equation must be a polynomial') if R.ngens() != 3 or F.nvariables() != 3: raise TypeError('equation must be a polynomial in three variables') @@ -1247,13 +1244,11 @@ def tangent_at_smooth_point(C,P): INPUT: - - ``C`` -- a projective plane curve. - - - ``P`` -- a 3-tuple `(x,y,z)` defining a projective point on `C`. + - ``C`` -- a projective plane curve - OUTPUT: + - ``P`` -- a 3-tuple `(x,y,z)` defining a projective point on `C` - The linear form defining the tangent at `P` to `C`. + OUTPUT: the linear form defining the tangent at `P` to `C` EXAMPLES:: @@ -1292,7 +1287,7 @@ def chord_and_tangent(F, P): plane cubic curve. - ``P`` -- a 3-tuple `(x,y,z)` defining a projective point on the - curve `F=0`. + curve `F=0` OUTPUT: @@ -1333,7 +1328,7 @@ def chord_and_tangent(F, P): from sage.schemes.curves.constructor import Curve # check the input R = F.parent() - if not is_MPolynomialRing(R): + if not isinstance(R, MPolynomialRing_base): raise TypeError('equation must be a polynomial') if R.ngens() != 3: raise TypeError('{} is not a polynomial in three variables'.format(F)) @@ -1358,15 +1353,13 @@ def chord_and_tangent(F, P): def projective_point(p): r""" - Return equivalent point with denominators removed + Return equivalent point with denominators removed. INPUT: - - ``P``, ``Q`` -- list/tuple of projective coordinates. - - OUTPUT: + - ``P``, ``Q`` -- list/tuple of projective coordinates - List of projective coordinates. + OUTPUT: list of projective coordinates EXAMPLES:: @@ -1394,11 +1387,11 @@ def are_projectively_equivalent(P, Q, base_ring): INPUT: - - ``P``, ``Q`` -- list/tuple of projective coordinates. + - ``P``, ``Q`` -- list/tuple of projective coordinates - - ``base_ring`` -- the base ring. + - ``base_ring`` -- the base ring - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1421,10 +1414,10 @@ def EllipticCurves_with_good_reduction_outside_S(S=[], proof=None, verbose=False - ``S`` -- list of primes (default: empty list) - - ``proof`` -- boolean (default ``True``): the MW basis for + - ``proof`` -- boolean (default: ``True``); the MW basis for auxiliary curves will be computed with this proof flag - - ``verbose`` -- boolean (default ``False``): if ``True``, some details + - ``verbose`` -- boolean (default: ``False``); if ``True``, some details of the computation will be output .. NOTE:: diff --git a/src/sage/schemes/elliptic_curves/descent_two_isogeny.pyx b/src/sage/schemes/elliptic_curves/descent_two_isogeny.pyx old mode 100644 new mode 100755 index 4bd4cc6cea9..16bad60ba56 --- a/src/sage/schemes/elliptic_curves/descent_two_isogeny.pyx +++ b/src/sage/schemes/elliptic_curves/descent_two_isogeny.pyx @@ -89,7 +89,7 @@ def test_valuation(a, p): cdef int padic_square(mpz_t a, mpz_t p) noexcept: """ - Test if a is a p-adic square. + Test if a is a `p`-adic square. """ cdef unsigned long v cdef mpz_t aa @@ -134,7 +134,7 @@ def test_padic_square(a, p): cdef int lemma6(mpz_t a, mpz_t b, mpz_t c, mpz_t d, mpz_t e, mpz_t x, mpz_t p, unsigned long nu) noexcept: """ - Implements Lemma 6 of BSD's "Notes on elliptic curves, I" for odd p. + Implement Lemma 6 of BSD's "Notes on elliptic curves, I" for odd `p`. Returns -1 for insoluble, 0 for undecided, +1 for soluble. """ @@ -184,7 +184,7 @@ cdef int lemma6(mpz_t a, mpz_t b, mpz_t c, mpz_t d, mpz_t e, cdef int lemma7(mpz_t a, mpz_t b, mpz_t c, mpz_t d, mpz_t e, mpz_t x, mpz_t p, unsigned long nu) noexcept: """ - Implements Lemma 7 of BSD's "Notes on elliptic curves, I" for p=2. + Implement Lemma 7 of BSD's "Notes on elliptic curves, I" for `p=2`. Returns -1 for insoluble, 0 for undecided, +1 for soluble. """ @@ -948,7 +948,7 @@ def test_qpls(a, b, c, d, e, p): cdef int everywhere_locally_soluble(mpz_t a, mpz_t b, mpz_t c, mpz_t d, mpz_t e) except -1: """ - Returns whether the quartic has local solutions at all primes p. + Return whether the quartic has local solutions at all primes `p`. """ cdef Integer A, B, C, D, E, Delta,p cdef mpz_t mpz_2 diff --git a/src/sage/schemes/elliptic_curves/ec_database.py b/src/sage/schemes/elliptic_curves/ec_database.py old mode 100644 new mode 100755 index f3de993ff5e..1cc03fdb8b3 --- a/src/sage/schemes/elliptic_curves/ec_database.py +++ b/src/sage/schemes/elliptic_curves/ec_database.py @@ -80,18 +80,16 @@ def rank(self, rank, tors=0, n=10, labels=False): INPUT: - - ``rank`` (int) -- the desired rank + - ``rank`` -- integer; the desired rank - - ``tors`` (int, default 0) -- the desired torsion order (ignored if 0) + - ``tors`` -- integer (default: 0); the desired torsion order (ignored if 0) - - ``n`` (int, default 10) -- the maximum number of curves returned. + - ``n`` -- integer (default: 10); the maximum number of curves returned - - ``labels`` (bool, default: ``False``) -- if True, return Cremona - labels instead of curves. + - ``labels`` -- boolean (default: ``False``); if ``True``, return Cremona + labels instead of curves - OUTPUT: - - (list) A list at most `n` of elliptic curves of required rank. + OUTPUT: list at most `n` of elliptic curves of required rank EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_curve_isogeny.py b/src/sage/schemes/elliptic_curves/ell_curve_isogeny.py old mode 100644 new mode 100755 index bce46802b9c..c095eb1ee89 --- a/src/sage/schemes/elliptic_curves/ell_curve_isogeny.py +++ b/src/sage/schemes/elliptic_curves/ell_curve_isogeny.py @@ -121,9 +121,7 @@ def _isogeny_determine_algorithm(E, kernel): - ``kernel`` -- either a list of points on ``E``, or a univariate polynomial or list of coefficients of a univariate polynomial - OUTPUT: - - (string) Either ``"velu"`` or ``"kohel"``. + OUTPUT: string; either ``'velu'`` or ``'kohel'``. EXAMPLES: @@ -185,9 +183,7 @@ def isogeny_codomain_from_kernel(E, kernel): or a kernel polynomial (specified as either a univariate polynomial or a coefficient list) - OUTPUT: - - (elliptic curve) The codomain of the separable normalized isogeny + OUTPUT: elliptic curve) The codomain of the separable normalized isogeny defined by this kernel. EXAMPLES:: @@ -278,9 +274,7 @@ def compute_vw_kohel_even_deg1(x0, y0, a1, a2, a4): - ``a1``, ``a2``, ``a4`` -- invariants of `E` - OUTPUT: - - (tuple) Vélu's isogeny parameters `(v,w)`. + OUTPUT: Vélu's isogeny parameters `(v,w)`. EXAMPLES: @@ -316,9 +310,7 @@ def compute_vw_kohel_even_deg3(b2, b4, s1, s2, s3): - ``s1``, ``s2``, ``s3`` -- signed coefficients of the 2-division polynomial of `E` - OUTPUT: - - (tuple) Vélu's isogeny parameters `(v,w)`. + OUTPUT: Vélu's isogeny parameters `(v,w)`. EXAMPLES: @@ -355,11 +347,9 @@ def compute_vw_kohel_odd(b2, b4, b6, s1, s2, s3, n): - ``s1``, ``s2``, ``s3`` -- signed coefficients of lowest powers of `x` in the kernel polynomial - - ``n`` (integer) -- the degree + - ``n`` -- integer; the degree - OUTPUT: - - (tuple) Vélu's isogeny parameters `(v,w)`. + OUTPUT: Vélu's isogeny parameters `(v,w)` EXAMPLES: @@ -392,13 +382,11 @@ def compute_codomain_kohel(E, kernel): - ``E`` -- domain elliptic curve - - ``kernel`` (polynomial or list) -- the kernel polynomial, or a + - ``kernel`` -- polynomial or list; the kernel polynomial, or a list of its coefficients - OUTPUT: - - (elliptic curve) The codomain elliptic curve of the isogeny - defined by ``kernel``. + OUTPUT: elliptic curve; the codomain elliptic curve of the isogeny + defined by ``kernel`` EXAMPLES:: @@ -503,10 +491,7 @@ def two_torsion_part(E, psi): - ``psi`` -- a univariate polynomial over the base field of ``E`` - OUTPUT: - - (polynomial) The `\gcd` of ``psi`` and the 2-torsion polynomial - of ``E``. + OUTPUT: polynomial; the `\gcd` of ``psi`` and the 2-torsion polynomial of ``E`` EXAMPLES: @@ -548,14 +533,13 @@ class EllipticCurveIsogeny(EllipticCurveHom): INPUT: - - ``E`` -- an elliptic curve, the domain of the isogeny to - initialize. + - ``E`` -- an elliptic curve; the domain of the isogeny to initialize - - ``kernel`` -- a kernel: either a point on ``E``, a list of + - ``kernel`` -- a kernel; either a point on ``E``, a list of points on ``E``, a monic kernel polynomial, or ``None``. If initializing from a domain/codomain, this must be ``None``. - - ``codomain`` -- an elliptic curve (default: ``None``). + - ``codomain`` -- an elliptic curve (default: ``None``) - If ``kernel`` is ``None``, then ``degree`` must be given as well and the given ``codomain`` must be the codomain of a cyclic, @@ -566,7 +550,7 @@ class EllipticCurveIsogeny(EllipticCurveHom): this case, the isogeny is post-composed with an isomorphism so that the codomain equals the given curve. - - ``degree`` -- an integer (default: ``None``). + - ``degree`` -- integer (default: ``None``) - If ``kernel`` is ``None``, then this is the degree of the isogeny from ``E`` to ``codomain``. @@ -575,20 +559,20 @@ class EllipticCurveIsogeny(EllipticCurveHom): whether or not to skip a `\gcd` of the given kernel polynomial with the two-torsion polynomial of ``E``. - - ``model`` -- a string (default: ``None``). Supported values + - ``model`` -- string (default: ``None``); supported values (cf. :func:`~sage.schemes.elliptic_curves.ell_field.compute_model`): - - ``"minimal"``: If ``E`` is a curve over the rationals or + - ``'minimal'`` -- if ``E`` is a curve over the rationals or over a number field, then the codomain is a global minimal model where this exists. - - ``"short_weierstrass"``: The codomain is a short Weierstrass curve, + - ``'short_weierstrass'`` -- the codomain is a short Weierstrass curve, assuming one exists. - - ``"montgomery"``: The codomain is an (untwisted) Montgomery + - ``'montgomery'`` -- the codomain is an (untwisted) Montgomery curve, assuming one exists over this field. - - ``check`` (default: ``True``) -- check whether the input is valid. + - ``check`` -- boolean (default: ``True``); check whether the input is valid. Setting this to ``False`` can lead to significant speedups. EXAMPLES: @@ -1104,9 +1088,7 @@ def _eval(self, P): - ``P`` -- a sequence of 3 coordinates defining a point on ``self`` - OUTPUT: - - The result of evaluating ``self`` at the given point. + OUTPUT: the result of evaluating ``self`` at the given point EXAMPLES:: @@ -1255,7 +1237,6 @@ def _call_(self, P): (0 : 1 : 1) sage: Q.order() +Infinity - """ if P.is_zero(): return self._codomain(0) @@ -1466,7 +1447,7 @@ def _latex_(self): Return the rational maps of the isogeny as a LaTeX string. This function returns a latex string representing the isogeny - self as the `x` and `y` coordinate rational functions. + ``self`` as the `x` and `y` coordinate rational functions. EXAMPLES:: @@ -1647,7 +1628,7 @@ def __initialize_rational_maps(self, precomputed_maps=None): INPUT: - - ``precomputed_maps`` (default ``None``) -- tuple `(X,Y)` + - ``precomputed_maps`` -- (default: ``None``) tuple `(X,Y)` of rational functions in `x,y` EXAMPLES: @@ -3482,20 +3463,18 @@ def compute_isogeny_stark(E1, E2, ell): INPUT: - - ``E1`` -- domain elliptic curve in short Weierstrass form + - ``E1`` -- domain elliptic curve in short Weierstrass form - - ``E2`` -- codomain elliptic curve in short Weierstrass form + - ``E2`` -- codomain elliptic curve in short Weierstrass form - ``ell`` -- the degree of an isogeny from ``E1`` to ``E2`` - OUTPUT: - - The kernel polynomial of an isogeny from ``E1`` to ``E2``. + OUTPUT: the kernel polynomial of an isogeny from ``E1`` to ``E2`` .. NOTE:: If there is no degree-``ell``, cyclic, separable, normalized - isogeny from ``E1`` to ``E2``, a :class:`ValueError` will be + isogeny from ``E1`` to ``E2``, a :exc:`ValueError` will be raised. ALGORITHM: @@ -3603,24 +3582,22 @@ def compute_isogeny_kernel_polynomial(E1, E2, ell, algorithm=None): INPUT: - - ``E1`` -- domain elliptic curve in short Weierstrass form + - ``E1`` -- domain elliptic curve in short Weierstrass form - - ``E2`` -- codomain elliptic curve in short Weierstrass form + - ``E2`` -- codomain elliptic curve in short Weierstrass form - - ``ell`` -- the degree of an isogeny from ``E1`` to ``E2`` + - ``ell`` -- the degree of an isogeny from ``E1`` to ``E2`` - ``algorithm`` -- ``None`` (default, choose automatically) or - ``"bmss"`` (:func:`compute_isogeny_bmss`) or - ``"stark"`` (:func:`compute_isogeny_stark`) - - OUTPUT: + ``'bmss'`` (:func:`compute_isogeny_bmss`) or + ``'stark'`` (:func:`compute_isogeny_stark`) - The kernel polynomial of an isogeny from ``E1`` to ``E2``. + OUTPUT: the kernel polynomial of an isogeny from ``E1`` to ``E2`` .. NOTE:: If there is no degree-``ell``, cyclic, separable, normalized - isogeny from ``E1`` to ``E2``, a :class:`ValueError` will be + isogeny from ``E1`` to ``E2``, a :exc:`ValueError` will be raised. EXAMPLES:: @@ -3884,14 +3861,14 @@ def fill_isogeny_matrix(M): INPUT: - ``M`` -- a square symmetric matrix whose off-diagonal `i`, `j` - entry is either a prime `l` if the `i`'th and `j`'th curves + entry is either a prime `l` if the `i`-th and `j`-th curves have an `l`-isogeny between them, otherwise `0` OUTPUT: - (matrix) A square matrix with entries `1` on the diagonal, and in + A square matrix with entries `1` on the diagonal, and in general the `i`, `j` entry is `d>0` if `d` is the minimal degree - of an isogeny from the `i`'th to the `j`'th curve. + of an isogeny from the `i`-th to the `j`-th curve. EXAMPLES:: @@ -3946,7 +3923,7 @@ def unfill_isogeny_matrix(M): OUTPUT: - (matrix) A square symmetric matrix obtained from ``M`` by + A square symmetric matrix obtained from ``M`` by replacing non-prime entries with `0`. EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_egros.py b/src/sage/schemes/elliptic_curves/ell_egros.py old mode 100644 new mode 100755 index 7004995aec6..365070a3809 --- a/src/sage/schemes/elliptic_curves/ell_egros.py +++ b/src/sage/schemes/elliptic_curves/ell_egros.py @@ -95,7 +95,7 @@ def is_possible_j(j, S=[]): r""" - Tests if the rational `j` is a possible `j`-invariant of an + Test if the rational `j` is a possible `j`-invariant of an elliptic curve with good reduction outside `S`. .. NOTE:: @@ -155,7 +155,7 @@ def egros_from_j_1728(S=[]): INPUT: - - S -- list of primes (default: empty list). + - ``S`` -- list of primes (default: empty list) .. NOTE:: @@ -199,7 +199,7 @@ def egros_from_j_0(S=[]): INPUT: - - S -- list of primes (default: empty list). + - ``S`` -- list of primes (default: empty list) .. NOTE:: @@ -247,9 +247,9 @@ def egros_from_j(j, S=[]): INPUT: - - j -- a rational number. + - ``j`` -- a rational number - - S -- list of primes (default: empty list). + - ``S`` -- list of primes (default: empty list) .. NOTE:: @@ -302,9 +302,9 @@ def egros_from_jlist(jlist, S=[]): INPUT: - - j -- list of rational numbers. + - ``j`` -- list of rational numbers - - S -- list of primes (default: empty list). + - ``S`` -- list of primes (default: empty list) .. NOTE:: @@ -341,19 +341,19 @@ def egros_from_jlist(jlist, S=[]): def egros_get_j(S=[], proof=None, verbose=False): r""" - Returns a list of rational `j` such that all elliptic curves + Return a list of rational `j` such that all elliptic curves defined over `\QQ` with good reduction outside `S` have `j`-invariant in the list, sorted by height. INPUT: - - ``S`` -- list of primes (default: empty list). + - ``S`` -- list of primes (default: empty list) - - ``proof`` -- ``True``/``False`` (default ``True``): the MW basis for - auxiliary curves will be computed with this proof flag. + - ``proof`` -- boolean (default: ``True``); the MW basis for + auxiliary curves will be computed with this proof flag - - ``verbose`` -- ``True``/``False`` (default ``False````): if ``True``, some - details of the computation will be output. + - ``verbose`` -- boolean (default: ``False``); if ``True``, some + details of the computation will be output .. NOTE:: diff --git a/src/sage/schemes/elliptic_curves/ell_field.py b/src/sage/schemes/elliptic_curves/ell_field.py old mode 100644 new mode 100755 index 8147fab3cf2..decf0a3d0b5 --- a/src/sage/schemes/elliptic_curves/ell_field.py +++ b/src/sage/schemes/elliptic_curves/ell_field.py @@ -101,14 +101,14 @@ def quadratic_twist(self, D=None): INPUT: - - ``D`` (default None) the twisting parameter (see below). + - ``D`` -- (default: ``None``) the twisting parameter (see below) In characteristics other than 2, `D` must be nonzero, and the - twist is isomorphic to self after adjoining `\sqrt(D)` to the + twist is isomorphic to ``self`` after adjoining `\sqrt(D)` to the base. In characteristic 2, `D` is arbitrary, and the twist is - isomorphic to self after adjoining a root of `x^2+x+D` to the + isomorphic to ``self`` after adjoining a root of `x^2+x+D` to the base. In characteristic 2 when `j=0`, this is not implemented. @@ -267,7 +267,7 @@ def quartic_twist(self, D): INPUT: - - ``D`` (must be nonzero) -- the twisting parameter + - ``D`` -- (must be nonzero) the twisting parameter .. NOTE:: @@ -311,7 +311,7 @@ def sextic_twist(self, D): INPUT: - - ``D`` (must be nonzero) -- the twisting parameter + - ``D`` -- (must be nonzero) the twisting parameter .. NOTE:: @@ -357,7 +357,7 @@ def is_quadratic_twist(self, other): INPUT: - - ``other`` -- an elliptic curve with the same base field as ``self``. + - ``other`` -- an elliptic curve with the same base field as ``self`` OUTPUT: @@ -513,7 +513,7 @@ def is_quartic_twist(self, other): INPUT: - - ``other`` -- an elliptic curves with the same base field as self. + - ``other`` -- an elliptic curves with the same base field as ``self`` OUTPUT: @@ -582,7 +582,7 @@ def is_sextic_twist(self, other): INPUT: - - ``other`` -- an elliptic curves with the same base field as self. + - ``other`` -- an elliptic curves with the same base field as ``self`` OUTPUT: @@ -647,22 +647,21 @@ def is_sextic_twist(self, other): def descend_to(self, K, f=None): r""" - Given an elliptic curve self defined over a field `L` and a + Given an elliptic curve ``self`` defined over a field `L` and a subfield `K` of `L`, return all elliptic curves over `K` which - are isomorphic over `L` to self. + are isomorphic over `L` to ``self``. INPUT: - - `K` -- a field which embeds into the base field `L` of self. + - ``K`` -- a field which embeds into the base field `L` of ``self`` - - `f` (optional) -- an embedding of `K` into `L`. Ignored if - `K` is `\QQ`. + - ``f`` -- (optional) an embedding of `K` into `L`; ignored if + `K` is `\QQ` OUTPUT: A list (possibly empty) of elliptic curves defined over `K` - which are isomorphic to self over `L`, up to isomorphism over - `K`. + which are isomorphic to ``self`` over `L`, up to isomorphism over `K`. .. NOTE:: @@ -824,9 +823,9 @@ def division_field(self, n, names='t', map=False, **kwds): INPUT: - - `n` -- a positive integer + - ``n`` -- positive integer - ``names`` -- (default: ``'t'``) a variable name for the division field - - ``map`` -- (default: ``False``) also return an embedding of the + - ``map`` -- boolean (default: ``False``); also return an embedding of the :meth:`base_field` into the resulting field - ``kwds`` -- additional keyword arguments passed to :func:`~sage.rings.polynomial.polynomial_element.Polynomial.splitting_field` @@ -1077,7 +1076,7 @@ def division_field(self, n, names='t', map=False, **kwds): if n == 2 or f.is_constant(): # For n = 2, the division field is the splitting field of # the division polynomial. - # If f is a non-zero constant, the n-torsion is trivial: + # If f is a nonzero constant, the n-torsion is trivial: # This means the curve must be supersingular and n == p. return f.splitting_field(names, map=map, **kwds) @@ -1197,7 +1196,7 @@ def isogeny(self, kernel, codomain=None, degree=None, model=None, check=True, al INPUT: - - ``kernel`` -- a kernel: either a point on this curve, a list of + - ``kernel`` -- a kernel; either a point on this curve, a list of points on this curve, a monic kernel polynomial, or ``None``. If initializing from a codomain, this must be ``None``. @@ -1212,7 +1211,7 @@ def isogeny(self, kernel, codomain=None, degree=None, model=None, check=True, al this case, the isogeny is post-composed with an isomorphism so that the codomain equals the given curve. - - ``degree`` -- an integer (default: ``None``). + - ``degree`` -- integer (default: ``None``). - If ``kernel`` is ``None``, then this is the degree of the isogeny from this curve to ``codomain``. @@ -1221,58 +1220,58 @@ def isogeny(self, kernel, codomain=None, degree=None, model=None, check=True, al whether or not to skip a `\gcd` of the given kernel polynomial with the two-torsion polynomial of this curve. - - ``model`` -- a string (default: ``None``). Supported values + - ``model`` -- string (default: ``None``); supported values (cf. :func:`~sage.schemes.elliptic_curves.ell_field.compute_model`): - - ``"minimal"``: If ``self`` is a curve over the rationals or + - ``'minimal'``: if ``self`` is a curve over the rationals or over a number field, then the codomain is a global minimal model where this exists. - - ``"short_weierstrass"``: The codomain is a short Weierstrass curve, + - ``'short_weierstrass'``: the codomain is a short Weierstrass curve, assuming one exists. - - ``"montgomery"``: The codomain is an (untwisted) Montgomery + - ``'montgomery'``: the codomain is an (untwisted) Montgomery curve, assuming one exists over this field. - - ``check`` (default: ``True``) -- check whether the input is valid. + - ``check`` -- boolean (default: ``True``); check whether the input is valid. Setting this to ``False`` can lead to significant speedups. - - ``algorithm`` -- string (optional). The possible choices are: + - ``algorithm`` -- string (optional); the possible choices are: - - ``"velusqrt"``: Use + - ``'velusqrt'``: Use :class:`~sage.schemes.elliptic_curves.hom_velusqrt.EllipticCurveHom_velusqrt`. - - ``"factored"``: Use + - ``'factored'``: Use :class:`~sage.schemes.elliptic_curves.hom_composite.EllipticCurveHom_composite` to decompose the isogeny into prime-degree steps. - - ``"traditional"``: Use + - ``'traditional'``: Use :class:`~sage.schemes.elliptic_curves.ell_curve_isogeny.EllipticCurveIsogeny`. When ``algorithm`` is not specified, and ``kernel`` is not ``None``, an algorithm is selected using the following criteria: - - if ``kernel`` is a list of multiple points, ``"factored"`` is selected. + - if ``kernel`` is a list of multiple points, ``'factored'`` is selected. - If ``kernel`` is a single point, or a list containing a single point: - - if the order of the point is unknown, ``"traditional"`` is selected. + - if the order of the point is unknown, ``'traditional'`` is selected. - - If the order is known and composite, ``"factored"`` is selected. + - If the order is known and composite, ``'factored'`` is selected. - - If the order is known and prime, a choice between ``"velusqrt"`` and - ``"traditional"`` is done according to the ``velu_sqrt_bound`` + - If the order is known and prime, a choice between ``'velusqrt'`` and + ``'traditional'`` is done according to the ``velu_sqrt_bound`` parameter (see below). - If none of the previous apply, ``"traditional"`` is selected. + If none of the previous apply, ``'traditional'`` is selected. - - ``velu_sqrt_bound`` -- an integer (default: ``None``). Establish the highest - (prime) degree for which the ``"traditional"`` algorithm should be selected - instead of ``"velusqrt"``. If ``None``, the default value from + - ``velu_sqrt_bound`` -- integer (default: ``None``); establish the highest + (prime) degree for which the ``'traditional'`` algorithm should be selected + instead of ``'velusqrt'``. If ``None``, the default value from :class:`~sage.schemes.elliptic_curves.hom_velusqrt._VeluBoundObj` is used. This value is initially set to 1000, but can be modified by the user. If an integer is supplied and the isogeny computation goes through the - ``"factored"`` algorithm, the same integer is supplied to each factor. + ``'factored'`` algorithm, the same integer is supplied to each factor. The ``degree`` parameter is not supported when an ``algorithm`` is specified. @@ -1321,7 +1320,7 @@ def isogeny(self, kernel, codomain=None, degree=None, model=None, check=True, al sage: E = EllipticCurve(GF(2^32 - 5), [170246996, 2036646110]) # needs sage.rings.finite_rings sage: P = E.lift_x(2) # needs sage.rings.finite_rings - sage: E.isogeny(P, algorithm="factored") # needs sage.rings.finite_rings + sage: E.isogeny(P, algorithm='factored') # needs sage.rings.finite_rings Composite morphism of degree 1073721825 = 3^4*5^2*11*19*43*59: From: Elliptic Curve defined by y^2 = x^3 + 170246996*x + 2036646110 over Finite Field of size 4294967291 @@ -1384,7 +1383,7 @@ def isogeny(self, kernel, codomain=None, degree=None, model=None, check=True, al To: Elliptic Curve defined by y^2 = x^3 + 95*x + 68 over Finite Field of size 97 sage: _velu_sqrt_bound.set(1000) # Reset bound - If the order of the point is unknown, fall back to ``"traditional"``:: + If the order of the point is unknown, fall back to ``'traditional'``:: sage: E = EllipticCurve_from_j(GF(97)(42)) sage: P = E(2, 39) @@ -1427,7 +1426,7 @@ def isogeny(self, kernel, codomain=None, degree=None, model=None, check=True, al sage: phi.codomain()._order 170141183460469231746191640949390434666 - Check that ``"factored"`` recursively apply `velu_sqrt_bound`:: + Check that ``'factored'`` recursively apply `velu_sqrt_bound`:: sage: from sage.schemes.elliptic_curves.hom_velusqrt import _velu_sqrt_bound sage: _velu_sqrt_bound.get() @@ -1496,8 +1495,9 @@ def isogeny_codomain(self, kernel): INPUT: - - ``kernel`` -- Either a list of points in the kernel of the isogeny, - or a kernel polynomial (specified as either a univariate polynomial or a coefficient list.) + - ``kernel`` -- either a list of points in the kernel of the isogeny, + or a kernel polynomial (specified as either a univariate polynomial + or a coefficient list) OUTPUT: @@ -1547,8 +1547,8 @@ def kernel_polynomial_from_point(self, P, *, algorithm=None): sage: E.kernel_polynomial_from_point(K) x^21 + 7*x^20 + 22*x^19 + 4*x^18 + 7*x^17 + 81*x^16 + 41*x^15 + 68*x^14 + 18*x^13 + 58*x^12 + 31*x^11 + 26*x^10 + 62*x^9 + 20*x^8 + 73*x^7 + 23*x^6 + 66*x^5 + 79*x^4 + 12*x^3 + 40*x^2 + 50*x + 93 - The ``"minpoly"`` algorithm is often much faster than the - ``"basic"`` algorithm:: + The ``'minpoly'`` algorithm is often much faster than the + ``'basic'`` algorithm:: sage: from sage.schemes.elliptic_curves.ell_field import EllipticCurve_field, point_of_order sage: p = 2^127 - 1 @@ -1587,13 +1587,13 @@ def kernel_polynomial_from_point(self, P, *, algorithm=None): ALGORITHM: - - The ``"basic"`` algorithm is to multiply together all the linear + - The ``'basic'`` algorithm is to multiply together all the linear factors `(X - x([i]P))` of the kernel polynomial using a product tree, then converting the result to the base field of the curve. Its complexity is `\widetilde O(\ell k)` where `k` is the extension degree. - - The ``"minpoly"`` algorithm is + - The ``'minpoly'`` algorithm is [EPSV2023]_, Algorithm 4 (``KernelPolynomialFromIrrationalX``). Over finite fields, its complexity is `O(\ell k) + \widetilde O(\ell)` where `k` is the extension degree. @@ -1648,7 +1648,7 @@ def kernel_polynomial_from_divisor(self, f, l, *, check=True): defined by `f`. If the given polynomial does not define a rational subgroup, a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. This method is currently only implemented for prime `l`. @@ -1738,14 +1738,14 @@ def isogenies_prime_degree(self, l=None, max_l=31): INPUT: - - ``l`` -- a prime or a list of primes. + - ``l`` -- a prime or a list of primes - ``max_l`` -- (default: 31) a bound on the primes to be tested. - This is only used if ``l`` is None. + This is only used if ``l`` is ``None``. OUTPUT: - (list) All separable `l`-isogenies for the given `l` with domain self. + (list) All separable `l`-isogenies for the given `l` with domain ``self``. ALGORITHM: @@ -2018,24 +2018,22 @@ def isogenies_prime_degree(self, l=None, max_l=31): def is_isogenous(self, other, field=None): """ - Return whether or not self is isogenous to other. + Return whether or not ``self`` is isogenous to ``other``. INPUT: - - ``other`` -- another elliptic curve. + - ``other`` -- another elliptic curve - - ``field`` (default None) -- Currently not implemented. A + - ``field`` -- (default: ``None``) currently not implemented. A field containing the base fields of the two elliptic curves onto which the two curves may be extended to test if they are isogenous over this field. By default ``is_isogenous`` will not try to find this field unless one of the curves can be - be extended into the base field of the other, in which case + be extended into the base field of the ``other``, in which case it will test over the larger base field. - OUTPUT: - - (bool) True if there is an isogeny from curve ``self`` to - curve ``other`` defined over ``field``. + OUTPUT: boolean; ``True`` if there is an isogeny from curve ``self`` to + curve ``other`` defined over ``field`` METHOD: @@ -2083,9 +2081,9 @@ def weierstrass_p(self, prec=20, algorithm=None): - ``prec`` -- precision - - ``algorithm`` -- string or ``None`` (default: ``None``): - a choice of algorithm among ``"pari"``, ``"fast"``, ``"quadratic"``; - or ``None`` to let this function determine the best algorithm to use. + - ``algorithm`` -- string or ``None`` (default: ``None``); + a choice of algorithm among ``'pari'``, ``'fast'``, ``'quadratic'`` + or ``None`` to let this function determine the best algorithm to use OUTPUT: @@ -2129,7 +2127,7 @@ def hasse_invariant(self): characteristic, and is an element of the field which is zero if and only if the curve is supersingular. Over a field of characteristic zero, where the Hasse invariant is undefined, - a :class:`ValueError` is raised. + a :exc:`ValueError` is raised. EXAMPLES:: @@ -2214,7 +2212,7 @@ class of curves. If the j-invariant is not unique in the isogeny class, append ``*`` to it to indicate a twist. Otherwise, if ``False`` label vertices by the equation of a representative curve. - OUTPUT: A :class:`Graph` or :class:`DiGraph`. + OUTPUT: a :class:`Graph` or :class:`DiGraph` EXAMPLES: @@ -2400,8 +2398,8 @@ class of curves. If the j-invariant is not unique in the isogeny else: from sage.graphs.graph import Graph as GraphType - G = GraphType(A, format="adjacency_matrix", - data_structure="static_sparse") + G = GraphType(A, format='adjacency_matrix', + data_structure='static_sparse') # inplace relabelling is necessary for static_sparse graphs GL = G.relabel(labels, inplace=False) return GL @@ -2456,26 +2454,24 @@ def compute_model(E, name): INPUT: - - ``E`` (elliptic curve) + - ``E`` -- elliptic curve - - ``name`` (string) -- current options: + - ``name`` -- string; current options: - - ``"minimal"``: Return a global minimal model of ``E`` if it + - ``'minimal'``: Return a global minimal model of ``E`` if it exists, and a semi-global minimal model otherwise. For this choice, ``E`` must be defined over a number field. See :meth:`~sage.schemes.elliptic_curves.ell_number_field.EllipticCurve_number_field.global_minimal_model`. - - ``"short_weierstrass"``: Return a short Weierstrass model of ``E`` + - ``'short_weierstrass'``: Return a short Weierstrass model of ``E`` assuming one exists. See :meth:`~sage.schemes.elliptic_curves.ell_generic.EllipticCurve_generic.short_weierstrass_model`. - - ``"montgomery"``: Return an (untwisted) Montgomery model of ``E`` + - ``'montgomery'``: Return an (untwisted) Montgomery model of ``E`` assuming one exists over this field. See :meth:`~sage.schemes.elliptic_curves.ell_generic.EllipticCurve_generic.montgomery_model`. - OUTPUT: - - An elliptic curve of the specified type isomorphic to `E`. + OUTPUT: an elliptic curve of the specified type isomorphic to `E` EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_finite_field.py b/src/sage/schemes/elliptic_curves/ell_finite_field.py old mode 100644 new mode 100755 index e285f473cb7..8cf0cdb2cb0 --- a/src/sage/schemes/elliptic_curves/ell_finite_field.py +++ b/src/sage/schemes/elliptic_curves/ell_finite_field.py @@ -96,7 +96,7 @@ def plot(self, *args, **kwds): INPUT: - ``*args``, ``**kwds`` -- all other options are passed - to the circle graphing primitive. + to the circle graphing primitive EXAMPLES:: @@ -240,11 +240,9 @@ def count_points(self, n=1): INPUT: - - ``n`` (int) -- a positive integer + - ``n`` -- positive integer - OUTPUT: - - If `n=1`, returns the cardinality of the curve over its base field. + OUTPUT: if `n=1`, returns the cardinality of the curve over its base field If `n>1`, returns a list `[c_1, c_2, ..., c_n]` where `c_d` is the cardinality of the curve over the extension of degree `d` @@ -296,9 +294,9 @@ def random_element(self): Choose the point at infinity with probability `1/(2q + 1)`. Otherwise, take a random element from the field as x-coordinate - and compute the possible y-coordinates. Return the i'th + and compute the possible y-coordinates. Return the i-th possible y-coordinate, where i is randomly chosen to be 0 or 1. - If the i'th y-coordinate does not exist (either there is no + If the i-th y-coordinate does not exist (either there is no point with the given x-coordinate or we hit a 2-torsion point with i == 1), try again. @@ -431,24 +429,24 @@ def cardinality(self, algorithm=None, extension_degree=1): - ``algorithm`` -- (optional) string: - - ``'pari'`` -- use the PARI C-library function ``ellcard``. + - ``'pari'`` -- use the PARI C-library function ``ellcard`` - ``'bsgs'`` -- use the baby-step giant-step method as implemented in Sage, with the Cremona-Sutherland version - of Mestre's trick. + of Mestre's trick - - ``'exhaustive'`` -- naive point counting. + - ``'exhaustive'`` -- naive point counting - ``'subfield'`` -- reduce to a smaller field, provided that - the j-invariant lies in a subfield. + the j-invariant lies in a subfield - ``'all'`` -- compute cardinality with both ``'pari'`` and ``'bsgs'``; return result if they agree or raise a - :class:`AssertionError` if they do not + :exc:`AssertionError` if they do not - - ``extension_degree`` -- an integer `d` (default: 1): if the + - ``extension_degree`` -- integer `d` (default: 1); if the base field is `\GF{q}`, return the cardinality of ``self`` - over the extension `\GF{q^d}` of degree `d`. + over the extension `\GF{q^d}` of degree `d` OUTPUT: @@ -503,12 +501,12 @@ def cardinality(self, algorithm=None, extension_degree=1): sage: # needs sage.rings.finite_rings sage: k. = GF(11^100) sage: E1 = EllipticCurve(k, [3,3]) - sage: N1 = E1.cardinality(algorithm="subfield"); N1 + sage: N1 = E1.cardinality(algorithm='subfield'); N1 137806123398222701841183371720896367762643312000384671846835266941791510341065565176497846502742959856128 sage: E1.cardinality_pari() == N1 True sage: E2 = E1.quadratic_twist() - sage: N2 = E2.cardinality(algorithm="subfield"); N2 + sage: N2 = E2.cardinality(algorithm='subfield'); N2 137806123398222701841183371720896367762643312000384656816094284101308193849980588362304472492174093035876 sage: E2.cardinality_pari() == N2 True @@ -823,7 +821,7 @@ def gens(self): the same each time, although they should remain fixed within a single run of Sage unless :meth:`abelian_group` is called.) - OUTPUT: a tuple of points on the curve. + OUTPUT: a tuple of points on the curve - if the group is trivial: an empty tuple. @@ -928,7 +926,7 @@ def __iter__(self): def __getitem__(self, n): """ - Return the n'th point in self's __points list. + Return the n-th point in ``self``'s ``__points`` list. This enables users to iterate over the curve's point set. @@ -1163,28 +1161,27 @@ def torsion_basis(self, n): def is_isogenous(self, other, field=None, proof=True): """ - Return whether or not self is isogenous to other. + Return whether or not ``self`` is isogenous to ``other``. INPUT: - - ``other`` -- another elliptic curve. + - ``other`` -- another elliptic curve - - ``field`` (default None) -- a field containing the base + - ``field`` -- (default: ``None``) a field containing the base fields of the two elliptic curves into which the two curves may be extended to test if they are isogenous over this field. By default is_isogenous will not try to find this field unless one of the curves can be extended into the base - field of the other, in which case it will test over the + field of the ``other``, in which case it will test over the larger base field. - - ``proof`` (default: ``True``) -- this parameter is here only to - be consistent with versions for other types of elliptic - curves. + - ``proof`` -- boolean (default: ``True``); this parameter is here only + to be consistent with versions for other types of elliptic curves OUTPUT: - (bool) True if there is an isogeny from curve ``self`` to - curve ``other`` defined over ``field``. + boolean; ``True`` if there is an isogeny from curve ``self`` to + curve ``other`` defined over ``field`` EXAMPLES:: @@ -1286,13 +1283,13 @@ def is_isogenous(self, other, field=None, proof=True): def is_supersingular(self, proof=True): r""" - Return True if this elliptic curve is supersingular, else False. + Return ``True`` if this elliptic curve is supersingular, else ``False``. INPUT: - - ``proof`` (boolean, default: ``True``) -- If True, returns a - proved result. If False, then a return value of False is - certain but a return value of True may be based on a + - ``proof``-- boolean (default: ``True``); if ``True``, returns a + proved result. If ``False``, then a return value of ``False`` is + certain but a return value of ``True`` may be based on a probabilistic test. See the documentation of the function :meth:`is_j_supersingular` for more details. @@ -1320,13 +1317,13 @@ def is_supersingular(self, proof=True): def is_ordinary(self, proof=True): r""" - Return True if this elliptic curve is ordinary, else False. + Return ``True`` if this elliptic curve is ordinary, else ``False``. INPUT: - - ``proof`` (boolean, default: ``True``) -- If True, returns a - proved result. If False, then a return value of True is - certain but a return value of False may be based on a + - ``proof``-- boolean (default: ``True``); if ``True``, returns a + proved result. If ``False``, then a return value of ``True`` is + certain but a return value of ``False`` may be based on a probabilistic test. See the documentation of the function :meth:`is_j_supersingular` for more details. @@ -1353,19 +1350,16 @@ def set_order(self, value, *, check=True, num_checks=8): INPUT: - - ``value`` -- integer in the Hasse-Weil range for this - curve. + - ``value`` -- integer in the Hasse-Weil range for this curve - - ``check`` (boolean, default: ``True``) -- whether or - not to run sanity checks on the input. + - ``check``-- boolean (default: ``True``); whether or + not to run sanity checks on the input - - ``num_checks`` (integer, default: 8) -- if ``check`` is + - ``num_checks``-- integer (default: 8); if ``check`` is ``True``, the number of times to check whether ``value`` - times a random point on this curve equals the identity. - - OUTPUT: + times a random point on this curve equals the identity - None + OUTPUT: none EXAMPLES: @@ -1538,7 +1532,7 @@ def height_above_floor(self, ell, e): INPUT: - ``ell`` -- a prime number - - ``e`` -- a non-negative integer, the ell-adic valuation of + - ``e`` -- nonnegative integer, the `\ell`-adic valuation of the conductor the Frobenius order @@ -1565,7 +1559,6 @@ def height_above_floor(self, ell, e): -1 * 2^10 * 11 * 61 sage: E.height_above_floor(2,8) 5 - """ if self.is_supersingular(): raise ValueError("{} is not ordinary".format(self)) @@ -1606,13 +1599,13 @@ def endomorphism_discriminant_from_class_number(self, h): INPUT: - - ``h`` -- a positive integer + - ``h`` -- positive integer OUTPUT: - (integer) The discriminant of the endomorphism ring `\text{End}(E)`, if + integer; the discriminant of the endomorphism ring `\text{End}(E)`, if this has class number ``h``. If `\text{End}(E)` does not have class - number ``h``, a :class:`ValueError` is raised. + number ``h``, a :exc:`ValueError` is raised. ALGORITHM: @@ -1622,7 +1615,7 @@ def endomorphism_discriminant_from_class_number(self, h): must be a multiple of `h_0`, compute the possible conductors, using :meth:`height_above_floor` for each prime `\ell` dividing the quotient `h/h_0`. If exactly one conductor `f` - remains, return `f^2D_0`, otherwise raise a :class:`ValueError`; + remains, return `f^2D_0`, otherwise raise a :exc:`ValueError`; this can onlyhappen when the input value of `h` was incorrect. .. NOTE:: @@ -1644,7 +1637,6 @@ def endomorphism_discriminant_from_class_number(self, h): sage: H = hilbert_class_polynomial(-671) sage: H(E.j_invariant()) == 0 and H.degree()==30 True - """ F = self.base_field() if not F.is_finite(): @@ -2266,9 +2258,9 @@ def supersingular_j_polynomial(p, use_cache=True): INPUT: - - `p` (integer) -- a prime number. + - ``p`` -- integer; a prime number - - ``use_cache`` (boolean, default ``True``) -- use cached coefficients if they exist + - ``use_cache`` -- boolean (default: ``True``); use cached coefficients if they exist ALGORITHM: @@ -2342,20 +2334,18 @@ def supersingular_j_polynomial(p, use_cache=True): def is_j_supersingular(j, proof=True): r""" - Return True if `j` is a supersingular `j`-invariant. + Return ``True`` if `j` is a supersingular `j`-invariant. INPUT: - - ``j`` (finite field element) -- an element of a finite field + - ``j`` -- finite field element - - ``proof`` (boolean, default: ``True``) -- If True, returns a proved - result. If False, then a return value of False is certain but a - return value of True may be based on a probabilistic test. See + - ``proof``-- boolean (default: ``True``); if ``True``, returns a proved + result. If ``False``, then a return value of ``False`` is certain but a + return value of ``True`` may be based on a probabilistic test. See the ALGORITHM section below for more details. - OUTPUT: - - (boolean) True if `j` is supersingular, else False. + OUTPUT: boolean; ``True`` if `j` is supersingular, else ``False`` ALGORITHM: @@ -2366,9 +2356,9 @@ def is_j_supersingular(j, proof=True): `j=1728`, the curve is supersingular if and only if `p=3` or `p\equiv2\pmod{3}`. Next, if the base field is the prime field `{\rm GF}(p)`, we check that `(p+1)P=0` for several random points - `P`, returning False if any fail: supersingular curves over `{\rm + `P`, returning ``False`` if any fail: supersingular curves over `{\rm GF}(p)` have cardinality `p+1`. If Proof is false we now return - True. Otherwise we compute the cardinality and return True if and + ``True``. Otherwise we compute the cardinality and return ``True`` if and only if it is divisible by `p`. EXAMPLES:: @@ -2498,9 +2488,9 @@ def special_supersingular_curve(F, *, endomorphism=False): - ``F`` -- finite field `\mathbb F_{p^r}`; - - ``endomorphism`` -- boolean (default: ``False``): - When set to ``True``, it is required that `2 \mid r`, and - the function then additionally returns `\vartheta`. + - ``endomorphism`` -- boolean (default: ``False``); when set to ``True``, + it is required that `2 \mid r`, and the function then additionally + returns `\vartheta` EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_generic.py b/src/sage/schemes/elliptic_curves/ell_generic.py old mode 100644 new mode 100755 index 43e67f0329d..6ca3f1fdb46 --- a/src/sage/schemes/elliptic_curves/ell_generic.py +++ b/src/sage/schemes/elliptic_curves/ell_generic.py @@ -10,7 +10,7 @@ Note that the (usual) scheme-theoretic definition of an elliptic curve over `R` would require the discriminant to be a unit in `R`; Sage only imposes that the -discriminant is non-zero. Also note that in Magma, "Weierstrass Model" refers +discriminant is nonzero. Also note that in Magma, "Weierstrass Model" refers to a model with `a_1=a_2=a_3=0`, which is called *Short Weierstrass Model* in Sage; these do not always exist in characteristics 2 and 3. @@ -133,8 +133,8 @@ def __init__(self, K, ainvs, category=None): - ``K`` -- a ring - - ``ainvs`` -- a list or tuple `[a_1, a_2, a_3, a_4, a_6]` of - Weierstrass coefficients. + - ``ainvs`` -- list or tuple `[a_1, a_2, a_3, a_4, a_6]` of + Weierstrass coefficients .. NOTE:: @@ -434,7 +434,7 @@ def _symbolic_(self, SR): def __contains__(self, P): """ - Return True if and only if P is a point on the elliptic curve. + Return ``True`` if and only if P is a point on the elliptic curve. P just has to be something that can be coerced to a point. @@ -492,7 +492,7 @@ def __call__(self, *args, **kwds): sage: E([0,1,0]) (0 : 1 : 0) - Over a field, points are normalized so the 3rd entry (if non-zero) + Over a field, points are normalized so the 3rd entry (if nonzero) is 1:: sage: E(105, -69, 125) @@ -528,7 +528,7 @@ def __call__(self, *args, **kwds): sage: P + P (0 : 1 : 0) - Another example involving p-adics:: + Another example involving `p`-adics:: sage: E = EllipticCurve('37a1') sage: P = E([0,0]); P @@ -602,13 +602,11 @@ def _reduce_point(self, R, p): INPUT: - - R -- a point on an elliptic curve - - p -- a prime + - ``R`` -- a point on an elliptic curve + - ``p`` -- a prime - OUTPUT: - - S -- the corresponding point of the elliptic curve containing - R, but reduced modulo p + OUTPUT: S; the corresponding point of the elliptic curve containing + R, but reduced modulo p EXAMPLES: @@ -645,7 +643,7 @@ def _reduce_point(self, R, p): def is_x_coord(self, x): r""" - Return True if ``x`` is the `x`-coordinate of a point on this curve. + Return ``True`` if ``x`` is the `x`-coordinate of a point on this curve. .. NOTE:: @@ -723,13 +721,13 @@ def lift_x(self, x, all=False, extend=False): INPUT: - - ``x`` -- an element of the base ring of the curve, or of an extension. + - ``x`` -- an element of the base ring of the curve, or of an extension - - ``all`` (bool, default: ``False``) -- if True, return a (possibly - empty) list of all points; if False, return just one point, - or raise a :class:`ValueError` if there are none. + - ``all`` -- boolean (default: ``False``); if ``True``, return a + (possibly empty) list of all points; if ``False``, return just one + point, or raise a :exc:`ValueError` if there are none. - - ``extend`` (bool, default: ``False``) -- + - ``extend`` -- boolean (default: ``False``); - if ``False``, extend the base if necessary and possible to include `x`, and only return point(s) defined over this @@ -1029,11 +1027,11 @@ def __is_over_RationalField(self): def is_on_curve(self, x, y): r""" - Return True if `(x,y)` is an affine point on this curve. + Return ``True`` if `(x,y)` is an affine point on this curve. INPUT: - - ``x``, ``y`` -- elements of the base ring of the curve. + - ``x``, ``y`` -- elements of the base ring of the curve EXAMPLES:: @@ -1498,7 +1496,7 @@ def rst_transform(self, r, s, t): INPUT: - - ``r``, ``s``, ``t`` -- three elements of the base ring. + - ``r``, ``s``, ``t`` -- three elements of the base ring OUTPUT: @@ -1528,7 +1526,7 @@ def scale_curve(self, u): INPUT: - - ``u`` -- an invertible element of the base ring. + - ``u`` -- an invertible element of the base ring OUTPUT: @@ -1683,7 +1681,7 @@ def isomorphism(self, u, r=0, s=0, t=0, *, is_codomain=False): def division_polynomial_0(self, n, x=None): r""" - Return the `n^{th}` torsion (division) polynomial, without + Return the `n`-th torsion (division) polynomial, without the 2-torsion factor if `n` is even, as a polynomial in `x`. These are the polynomials `g_n` defined in [MT1991]_, but with @@ -1705,10 +1703,10 @@ def division_polynomial_0(self, n, x=None): - ``n`` -- positive integer, or the special values ``-1`` and ``-2`` which mean `B_6 = (2y + a_1 x + a_3)^2` and `B_6^2` respectively (in - the notation of [MT1991]_); or a list of integers. + the notation of [MT1991]_), or a list of integers - ``x`` -- a ring element to use as the "x" variable or ``None`` - (default: ``None``). If ``None``, then a new polynomial ring will + (default: ``None``); if ``None``, then a new polynomial ring will be constructed over the base ring of the elliptic curve, and its generator will be used as ``x``. Note that ``x`` does not need to be a generator of a polynomial ring; any ring element is ok. This @@ -1864,7 +1862,7 @@ def two_division_polynomial(self, x=None): INPUT: - - ``x`` -- optional ring element to use as the `x` variable. + - ``x`` -- (optional) ring element to use as the `x` variable. If ``x`` is ``None``, then a new polynomial ring will be constructed over the base ring of the elliptic curve, and its generator will be used as ``x``. Note that ``x`` does @@ -1887,16 +1885,16 @@ def two_division_polynomial(self, x=None): def division_polynomial(self, m, x=None, two_torsion_multiplicity=2, force_evaluate=None): r""" - Return the `m^{th}` division polynomial of this elliptic + Return the `m`-th division polynomial of this elliptic curve evaluated at `x`. The division polynomial is cached if `x` is ``None``. INPUT: - - ``m`` -- positive integer. + - ``m`` -- positive integer - - ``x`` -- optional ring element to use as the `x` variable. + - ``x`` -- (optional) ring element to use as the `x` variable. If `x` is ``None`` (omitted), then a new polynomial ring will be constructed over the base ring of the elliptic curve, and its generator will be used as `x`. Note that `x` does not need to @@ -1925,7 +1923,7 @@ def division_polynomial(self, m, x=None, two_torsion_multiplicity=2, force_evalu When `x` is not ``None``, it should be a tuple of length 2, and the evaluation of such a polynomial at `x` is returned. - - ``force_evaluate`` (optional) -- 0, 1, or 2 + - ``force_evaluate`` -- (optional) 0, 1, or 2 By default, this method makes use of previously cached generic division polynomials to compute the value of the polynomial at @@ -2113,7 +2111,7 @@ def _multiple_x_numerator(self, n, x=None): INPUT: - - ``n``, ``x`` -- as described in :meth:`division_polynomial_0`. + - ``n``, ``x`` -- as described in :meth:`division_polynomial_0` If ``x`` is ``None``, the result is cached. This is so that on calling ``P.division_points(n)`` for the same `n` and different points `P` (on @@ -2237,7 +2235,7 @@ def _multiple_x_denominator(self, n, x=None): INPUT: - - ``n``, ``x`` -- as described in :meth:`division_polynomial_0`. + - ``n``, ``x`` -- as described in :meth:`division_polynomial_0` If ``x`` is ``None``, the result is cached. This is so that on calling ``P.division_points(n)`` for the same `n` and different points `P` (on @@ -2321,7 +2319,7 @@ def _multiple_x_denominator(self, n, x=None): def multiplication_by_m(self, m, x_only=False): r""" - Return the multiplication-by-`m` map from ``self`` to ``self`` + Return the multiplication-by-`m` map from ``self`` to ``self``. The result is a pair of rational functions in two variables `x`, `y` (or a rational function in one variable `x` if @@ -2329,11 +2327,10 @@ def multiplication_by_m(self, m, x_only=False): INPUT: - - ``m`` -- a nonzero integer + - ``m`` -- nonzero integer - - ``x_only`` -- boolean (default: ``False``) if ``True``, return - only the `x`-coordinate of the map (as a rational function - in one variable). + - ``x_only`` -- boolean (default: ``False``); if ``True``, return only + the `x`-coordinate of the map (as a rational function in one variable) OUTPUT: @@ -2457,7 +2454,7 @@ def multiplication_by_m(self, m, x_only=False): p = self.base_ring().characteristic() if m == 0: - raise ValueError("m must be a non-zero integer") + raise ValueError("m must be a nonzero integer") if x_only: x = polygen(self.base_ring(), 'x') @@ -2531,7 +2528,7 @@ def multiplication_by_m_isogeny(self, m): INPUT: - - ``m`` -- a nonzero integer + - ``m`` -- nonzero integer OUTPUT: @@ -2693,7 +2690,7 @@ def isomorphism_to(self, other): INPUT: - - ``other`` -- an elliptic curve isomorphic to ``self``. + - ``other`` -- an elliptic curve isomorphic to ``self`` OUTPUT: @@ -2701,8 +2698,8 @@ def isomorphism_to(self, other): .. NOTE:: - If the curves in question are not isomorphic, - a :class:`ValueError` is raised. + If the curves in question are not isomorphic, a :exc:`ValueError` + is raised. EXAMPLES:: @@ -2745,13 +2742,13 @@ def automorphisms(self, field=None): INPUT: - - ``field`` (default ``None``) -- a field into which the + - ``field`` -- (default: ``None``) a field into which the coefficients of the curve may be coerced (by default, uses - the base field of the curve). + the base field of the curve) OUTPUT: - (list) A list of :class:`~wm.WeierstrassIsomorphism` objects + A list of :class:`~wm.WeierstrassIsomorphism` objects consisting of all the isomorphisms from the curve ``self`` to itself defined over ``field``. @@ -2828,15 +2825,15 @@ def isomorphisms(self, other, field=None): INPUT: - - ``other`` -- another elliptic curve. + - ``other`` -- another elliptic curve - - ``field`` (default ``None``) -- a field into which the + - ``field`` -- (default: ``None``) a field into which the coefficients of the curves may be coerced (by default, uses - the base field of the curves). + the base field of the curves) OUTPUT: - (list) A list of :class:`~wm.WeierstrassIsomorphism` objects consisting of all + A list of :class:`~wm.WeierstrassIsomorphism` objects consisting of all the isomorphisms from the curve ``self`` to the curve ``other`` defined over ``field``. @@ -2885,15 +2882,15 @@ def is_isomorphic(self, other, field=None): INPUT: - - ``other`` -- another elliptic curve. + - ``other`` -- another elliptic curve - - ``field`` (default None) -- a field into which the + - ``field`` -- (default: ``None``) a field into which the coefficients of the curves may be coerced (by default, uses the base field of the curves). OUTPUT: - (bool) True if there is an isomorphism from curve ``self`` to + boolean; ``True`` if there is an isomorphism from curve ``self`` to curve ``other`` defined over ``field``. EXAMPLES:: @@ -2925,7 +2922,8 @@ def is_isomorphic(self, other, field=None): def change_weierstrass_model(self, *urst): r""" - Return a new Weierstrass model of ``self`` under the standard transformation `(u,r,s,t)` + Return a new Weierstrass model of ``self`` under the standard + transformation `(u,r,s,t)`. .. MATH:: @@ -2950,16 +2948,14 @@ def change_weierstrass_model(self, *urst): def short_weierstrass_model(self, complete_cube=True): """ - Return a short Weierstrass model for self. + Return a short Weierstrass model for ``self``. INPUT: - ``complete_cube`` -- boolean (default: ``True``); for - meaning, see below. - - OUTPUT: + meaning, see below - An elliptic curve. + OUTPUT: an elliptic curve If ``complete_cube=True``: Return a model of the form `y^2 = x^3 + a*x + b` for this curve. The characteristic @@ -3272,9 +3268,9 @@ def plot(self, xmin=None, xmax=None, components='both', **args): INPUT: - ``xmin``, ``xmax`` -- (optional) points will be computed at - least within this range, but possibly farther. + least within this range, but possibly farther - - ``components`` -- a string, one of the following: + - ``components`` -- string; one of the following: - ``both`` -- (default), scale so that both bounded and unbounded components appear @@ -3284,7 +3280,7 @@ def plot(self, xmin=None, xmax=None, components='both', **args): component. - ``unbounded`` -- scale the plot to show the unbounded - component, including the two flex points. + component, including the two flex points - ``plot_points`` -- passed to :func:`sage.plot.generate_plot_points` @@ -3491,10 +3487,10 @@ def _p_primary_torsion_basis(self, p, m=None): INPUT: - - ``p`` (integer) -- a prime number. + - ``p`` -- integer; a prime number - - ``m`` (integer or None) -- if not None, the `p`-primary torsion will - be assumed to have order at most `p^m`. + - ``m`` -- integer or ``None``; if not ``None``, the `p`-primary + torsion will be assumed to have order at most `p^m` OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/ell_local_data.py b/src/sage/schemes/elliptic_curves/ell_local_data.py old mode 100644 new mode 100755 index f600259eef7..7434659b5a2 --- a/src/sage/schemes/elliptic_curves/ell_local_data.py +++ b/src/sage/schemes/elliptic_curves/ell_local_data.py @@ -102,7 +102,7 @@ from sage.rings.number_field.number_field_ideal import NumberFieldFractionalIdeal from sage.rings.number_field.number_field_base import NumberField -from sage.rings.ideal import is_Ideal +from sage.rings.ideal import Ideal_generic from .constructor import EllipticCurve from .kodaira_symbol import KodairaSymbol @@ -118,17 +118,17 @@ class EllipticCurveLocalData(SageObject): INPUT: - - ``E`` -- an elliptic curve defined over a number field, or `\QQ`. + - ``E`` -- an elliptic curve defined over a number field, or `\QQ` - - ``P`` -- a prime ideal of the field, or a prime integer if the field is `\QQ`. + - ``P`` -- a prime ideal of the field, or a prime integer if the field is `\QQ` - - ``proof`` (bool) -- if ``True``, only use provably correct - methods (default controlled by global proof module). Note + - ``proof`` -- boolean; if ``True``, only use provably correct + methods (default: controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - - ``algorithm`` (string, default: "pari") -- Ignored unless the + - ``algorithm`` -- string (default: ``'pari'``); ignored unless the base field is `\QQ`. If "pari", use the PARI C-library ``ellglobalred`` implementation of Tate's algorithm over `\QQ`. If "generic", use the general number field @@ -155,29 +155,29 @@ class EllipticCurveLocalData(SageObject): Tamagawa Number: 2 """ - def __init__(self, E, P, proof=None, algorithm="pari", globally=False): + def __init__(self, E, P, proof=None, algorithm='pari', globally=False): r""" Initialize the reduction data for the elliptic curve `E` at the prime `P`. INPUT: - - ``E`` -- an elliptic curve defined over a number field, or `\QQ`. + - ``E`` -- an elliptic curve defined over a number field, or `\QQ` - - ``P`` -- a prime ideal of the field, or a prime integer if the field is `\QQ`. + - ``P`` -- a prime ideal of the field, or a prime integer if the field is `\QQ` - - ``proof`` (bool)-- if True, only use provably correct - methods (default controlled by global proof module). Note + - ``proof`` -- boolean; if ``True``, only use provably correct + methods (default: controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - - ``algorithm`` (string, default: "pari") -- Ignored unless the + - ``algorithm`` -- string (default: ``'pari'``); ignored unless the base field is `\QQ`. If "pari", use the PARI C-library ``ellglobalred`` implementation of Tate's algorithm over `\QQ`. If "generic", use the general number field implementation. - - ``globally`` (bool, default: ``False``) -- If True, the algorithm + - ``globally`` -- boolean (default: ``False``); if ``True``, the algorithm uses the generators of principal ideals rather than an arbitrary uniformizer. @@ -203,7 +203,7 @@ def __init__(self, E, P, proof=None, algorithm="pari", globally=False): :: - sage: EllipticCurveLocalData(E, 2, algorithm="generic") + sage: EllipticCurveLocalData(E, 2, algorithm='generic') Local data at Principal ideal (2) of Integer Ring: Reduction type: bad non-split multiplicative Local minimal model: Elliptic Curve defined by y^2 + x*y + y = x^3 + 4*x - 6 @@ -215,7 +215,7 @@ def __init__(self, E, P, proof=None, algorithm="pari", globally=False): :: - sage: EllipticCurveLocalData(E, 2, algorithm="pari") + sage: EllipticCurveLocalData(E, 2, algorithm='pari') Local data at Principal ideal (2) of Integer Ring: Reduction type: bad non-split multiplicative Local minimal model: Elliptic Curve defined by y^2 + x*y + y = x^3 + 4*x - 6 @@ -227,7 +227,7 @@ def __init__(self, E, P, proof=None, algorithm="pari", globally=False): :: - sage: EllipticCurveLocalData(E, 2, algorithm="unknown") + sage: EllipticCurveLocalData(E, 2, algorithm='unknown') Traceback (most recent call last): ... ValueError: algorithm must be one of 'pari', 'generic' @@ -315,7 +315,7 @@ def minimal_model(self, reduce=True): INPUT: - - ``reduce`` -- (default: ``True``) if set to ``True`` and if + - ``reduce`` -- boolean (default: ``True``); if set to ``True`` and if the initial elliptic curve had globally integral coefficients, then the elliptic curve returned by Tate's algorithm will be "reduced" as specified in _reduce_model() @@ -346,15 +346,15 @@ def minimal_model(self, reduce=True): over Number Field in a with defining polynomial x^3 + x + 1 sage: E = EllipticCurve([2, 1, 0, -2, -1]) - sage: E.local_data(ZZ.ideal(2), algorithm="generic").minimal_model(reduce=False) + sage: E.local_data(ZZ.ideal(2), algorithm='generic').minimal_model(reduce=False) Elliptic Curve defined by y^2 + 2*x*y + 2*y = x^3 + x^2 - 4*x - 2 over Rational Field - sage: E.local_data(ZZ.ideal(2), algorithm="pari").minimal_model(reduce=False) + sage: E.local_data(ZZ.ideal(2), algorithm='pari').minimal_model(reduce=False) Traceback (most recent call last): ... ValueError: the argument reduce must not be False if algorithm=pari is used - sage: E.local_data(ZZ.ideal(2), algorithm="generic").minimal_model() + sage: E.local_data(ZZ.ideal(2), algorithm='generic').minimal_model() Elliptic Curve defined by y^2 = x^3 - x^2 - 3*x + 2 over Rational Field - sage: E.local_data(ZZ.ideal(2), algorithm="pari").minimal_model() + sage: E.local_data(ZZ.ideal(2), algorithm='pari').minimal_model() Elliptic Curve defined by y^2 = x^3 - x^2 - 3*x + 2 over Rational Field :issue:`14476`:: @@ -508,7 +508,7 @@ def bad_reduction_type(self): OUTPUT: - (int or ``None``): + integer or ``None``: - +1 for split multiplicative reduction - -1 for non-split multiplicative reduction @@ -697,12 +697,12 @@ def _tate(self, proof=None, globally=False): (tuple) ``(Emin, p, val_disc, fp, KS, cp)`` where: - - ``Emin`` (EllipticCurve) is a model (integral and) minimal at P - - ``p`` (int) is the residue characteristic - - ``val_disc`` (int) is the valuation of the local minimal discriminant - - ``fp`` (int) is the valuation of the conductor - - ``KS`` (string) is the Kodaira symbol - - ``cp`` (int) is the Tamagawa number + - ``Emin`` -- :class:`EllipticCurve`; a model (integral and) minimal at P + - ``p`` -- integer; the residue characteristic + - ``val_disc`` -- integer; the valuation of the local minimal discriminant + - ``fp`` -- integer; the valuation of the conductor + - ``KS`` -- string; the Kodaira symbol + - ``cp`` -- integer; the Tamagawa number EXAMPLES (this raised a type error in sage prior to 4.4.4, see :issue:`7930`) :: @@ -759,7 +759,7 @@ def _tate(self, proof=None, globally=False): # reduce (mod P) elements of K which are not integral (but are # P-integral). However, if the model is non-minimal and we # end up dividing a_i by pi^i then at that point we use a - # uniformiser pi which has non-positive valuation at all other + # uniformiser pi which has nonpositive valuation at all other # primes, so that we can divide by it without losing # integrality at other primes. @@ -805,7 +805,8 @@ def _tate(self, proof=None, globally=False): def _pquadroots(a, b, c): r""" - Local function returning True iff `ax^2 + bx + c` has roots modulo `P` + Local function returning ``True`` iff `ax^2 + bx + c` has roots + modulo `P`. """ (a, b, c) = (F(a), F(b), F(c)) if a == 0: @@ -1129,19 +1130,17 @@ def check_prime(K, P): INPUT: - - ``K`` -- a number field (including `\QQ`). + - ``K`` -- a number field (including `\QQ`) - - ``P`` -- an element of ``K`` or a (fractional) ideal of ``K``. + - ``P`` -- an element of ``K`` or a (fractional) ideal of ``K`` - OUTPUT: - - - If ``K`` is `\QQ`: the prime integer equal to or which generates `P`. + OUTPUT: if ``K`` is `\QQ`: the prime integer equal to or which generates `P` - If ``K`` is not `\QQ`: the prime ideal equal to or generated by `P`. .. NOTE:: - If `P` is not a prime and does not generate a prime, a :class:`TypeError` + If `P` is not a prime and does not generate a prime, a :exc:`TypeError` is raised. EXAMPLES:: @@ -1185,7 +1184,7 @@ def check_prime(K, P): raise TypeError("The element %s is not prime" % (P,)) elif P in QQ: raise TypeError("The element %s is not prime" % (P,)) - elif is_Ideal(P) and P.base_ring() is ZZ: + elif isinstance(P, Ideal_generic) and P.base_ring() is ZZ: if P.is_prime(): return P.gen() else: diff --git a/src/sage/schemes/elliptic_curves/ell_modular_symbols.py b/src/sage/schemes/elliptic_curves/ell_modular_symbols.py old mode 100644 new mode 100755 index 0b8039aeb36..ba10a3c6e1a --- a/src/sage/schemes/elliptic_curves/ell_modular_symbols.py +++ b/src/sage/schemes/elliptic_curves/ell_modular_symbols.py @@ -39,7 +39,7 @@ 1/3 sage: m(1/17) -2/3 - sage: m2 = E.modular_symbol(-1, implementation="sage") + sage: m2 = E.modular_symbol(-1, implementation='sage') sage: m2(0) 0 sage: m2(1/5) @@ -109,16 +109,16 @@ def modular_symbol_space(E, sign, base_ring, bound=None): r""" - Creates the space of modular symbols of a given sign over a give base_ring, + Create the space of modular symbols of a given sign over a give base_ring, attached to the isogeny class of the elliptic curve ``E``. INPUT: - ``E`` -- an elliptic curve over `\QQ` - - ``sign`` -- integer, -1, 0, or 1 + - ``sign`` -- integer; -1, 0, or 1 - ``base_ring`` -- ring - - ``bound`` -- (default: None) maximum number of Hecke operators to - use to cut out modular symbols factor. If None, use + - ``bound`` -- (default: ``None``) maximum number of Hecke operators to + use to cut out modular symbols factor. If ``None``, use enough to provably get the correct answer. OUTPUT: a space of modular symbols @@ -172,7 +172,7 @@ def sign(self): sage: m = EllipticCurve('11a1').modular_symbol() sage: m.sign() 1 - sage: m = EllipticCurve('11a1').modular_symbol(sign=-1, implementation="sage") + sage: m = EllipticCurve('11a1').modular_symbol(sign=-1, implementation='sage') sage: m.sign() -1 """ @@ -212,7 +212,7 @@ def _repr_(self): sage: m Modular symbol with sign 1 over Rational Field attached to Elliptic Curve defined by y^2 + y = x^3 - x^2 - 10*x - 20 over Rational Field - sage: m = EllipticCurve('43a1').modular_symbol(sign=-1, implementation="sage") + sage: m = EllipticCurve('43a1').modular_symbol(sign=-1, implementation='sage') sage: m Modular symbol with sign -1 over Rational Field attached to Elliptic Curve defined by y^2 + y = x^3 + x^2 over Rational Field @@ -236,10 +236,10 @@ def __init__(self, E, sign, nap=1000): - ``E`` -- an elliptic curve - - ``sign`` -- an integer, -1 or 1 + - ``sign`` -- integer; -1 or 1 - - ``nap`` -- (int, default 1000): the number of ap of E to use - in determining the normalisation of the modular symbols. + - ``nap`` -- integer (default: 1000); the number of ap of E to use + in determining the normalisation of the modular symbols EXAMPLES:: @@ -265,12 +265,12 @@ def __init__(self, E, sign, nap=1000): sage: M(1/7) 1/2 - sage: M = EllipticCurve('121d1').modular_symbol(implementation="eclib") + sage: M = EllipticCurve('121d1').modular_symbol(implementation='eclib') sage: M(0) 2 sage: E = EllipticCurve('15a1') - sage: [C.modular_symbol(implementation="eclib")(0) for C in E.isogeny_class()] + sage: [C.modular_symbol(implementation='eclib')(0) for C in E.isogeny_class()] [1/4, 1/8, 1/4, 1/2, 1/8, 1/16, 1/2, 1] Since :issue:`10256`, the interface for negative modular symbols in eclib is available:: @@ -297,7 +297,7 @@ def __init__(self, E, sign, nap=1000): TESTS (for :issue:`10236`):: sage: E = EllipticCurve('11a1') - sage: m = E.modular_symbol(implementation="eclib") + sage: m = E.modular_symbol(implementation='eclib') sage: m(1/7) 7/10 sage: m(0) @@ -344,7 +344,7 @@ def _call_with_caching(self, r, base_at_infinity=True): EXAMPLES:: - sage: m = EllipticCurve('11a1').modular_symbol(implementation="eclib") + sage: m = EllipticCurve('11a1').modular_symbol(implementation='eclib') sage: m._call_with_caching(0) 1/5 """ @@ -363,7 +363,7 @@ def __call__(self, r, base_at_infinity=True): EXAMPLES:: - sage: m = EllipticCurve('11a1').modular_symbol(implementation="eclib") + sage: m = EllipticCurve('11a1').modular_symbol(implementation='eclib') sage: m(0) 1/5 """ @@ -375,21 +375,21 @@ def __call__(self, r, base_at_infinity=True): class ModularSymbolSage(ModularSymbol): - def __init__(self, E, sign, normalize="L_ratio"): + def __init__(self, E, sign, normalize='L_ratio'): """Modular symbols attached to `E` using ``sage``. INPUT: - ``E`` -- an elliptic curve - - ``sign`` -- an integer, -1 or 1 - - ``normalize`` -- either 'L_ratio' (default), 'period', or - 'none'; For 'L_ratio', the modular symbol is correctly + - ``sign`` -- integer; -1 or 1 + - ``normalize`` -- either ``'L_ratio'`` (default), ``'period'``, or + ``'none'``; For ``'L_ratio'``, the modular symbol is correctly normalized by comparing it to the quotient of `L(E,1)` by the least positive period for the curve and some small - twists. The normalization 'period' uses the + twists. The normalization ``'period'`` uses the integral_period_map for modular symbols and is known to be equal to the above normalization up to the sign and a - possible power of 2. For 'none', the modular symbol is + possible power of 2. For ``'none'``, the modular symbol is almost certainly not correctly normalized, i.e. all values will be a fixed scalar multiple of what they should be. But the initial computation of the modular symbol is much @@ -424,22 +424,22 @@ def __init__(self, E, sign, normalize="L_ratio"): sage: M._scaling 1 - sage: M = EllipticCurve('121d1').modular_symbol(implementation="sage") + sage: M = EllipticCurve('121d1').modular_symbol(implementation='sage') sage: M(0) 2 - sage: M = EllipticCurve('121d1').modular_symbol(implementation="sage", + sage: M = EllipticCurve('121d1').modular_symbol(implementation='sage', ....: normalize='none') sage: M(0) 1 sage: E = EllipticCurve('15a1') - sage: [C.modular_symbol(implementation="sage", normalize='L_ratio')(0) + sage: [C.modular_symbol(implementation='sage', normalize='L_ratio')(0) ....: for C in E.isogeny_class()] [1/4, 1/8, 1/4, 1/2, 1/8, 1/16, 1/2, 1] - sage: [C.modular_symbol(implementation="sage", normalize='period')(0) + sage: [C.modular_symbol(implementation='sage', normalize='period')(0) ....: for C in E.isogeny_class()] [1/8, 1/16, 1/8, 1/4, 1/16, 1/32, 1/4, 1/2] - sage: [C.modular_symbol(implementation="sage", normalize='none')(0) + sage: [C.modular_symbol(implementation='sage', normalize='none')(0) ....: for C in E.isogeny_class()] [1, 1, 1, 1, 1, 1, 1, 1] """ @@ -472,27 +472,27 @@ def _find_scaling_L_ratio(self): r""" This function is use to set ``_scaling``, the factor used to adjust the scalar multiple of the modular symbol. - If `[0]`, the modular symbol evaluated at 0, is non-zero, we can just scale + If `[0]`, the modular symbol evaluated at 0, is nonzero, we can just scale it with respect to the approximation of the L-value. It is known that the quotient is a rational number with small denominator. Otherwise we try to scale using quadratic twists. - ``_scaling`` will be set to a rational non-zero multiple if we succeed and to 1 otherwise. + ``_scaling`` will be set to a rational nonzero multiple if we succeed and to 1 otherwise. Even if we fail we scale at least to make up the difference between the periods of the `X_0`-optimal curve and our given curve `E` in the isogeny class. EXAMPLES:: - sage: m = EllipticCurve('11a1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('11a1').modular_symbol(implementation='sage') sage: m._scaling 1/5 - sage: m = EllipticCurve('11a2').modular_symbol(implementation="sage") + sage: m = EllipticCurve('11a2').modular_symbol(implementation='sage') sage: m._scaling 1 - sage: m = EllipticCurve('11a3').modular_symbol(implementation="sage") + sage: m = EllipticCurve('11a3').modular_symbol(implementation='sage') sage: m._scaling 1/25 - sage: m = EllipticCurve('37a1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('37a1').modular_symbol(implementation='sage') sage: m._scaling -1 sage: m = EllipticCurve('37a1').modular_symbol() @@ -501,16 +501,16 @@ def _find_scaling_L_ratio(self): sage: m = EllipticCurve('389a1').modular_symbol() sage: m._scaling 1 - sage: m = EllipticCurve('389a1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('389a1').modular_symbol(implementation='sage') sage: m._scaling 1 - sage: m = EllipticCurve('196a1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('196a1').modular_symbol(implementation='sage') sage: m._scaling 1 Some harder cases fail:: - sage: m = EllipticCurve('121b1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('121b1').modular_symbol(implementation='sage') Warning : Could not normalize the modular symbols, maybe all further results will be multiplied by -1 and a power of 2 sage: m._scaling 1 @@ -520,8 +520,8 @@ def _find_scaling_L_ratio(self): sage: rk0 = ['11a1', '11a2', '15a1', '27a1', '37b1'] sage: for la in rk0: # long time (3s on sage.math, 2011) ....: E = EllipticCurve(la) - ....: me = E.modular_symbol(implementation="eclib") - ....: ms = E.modular_symbol(implementation="sage") + ....: me = E.modular_symbol(implementation='eclib') + ....: ms = E.modular_symbol(implementation='sage') ....: print("{} {} {}".format(E.lseries().L_ratio()*E.real_components(), me(0), ms(0))) 1/5 1/5 1/5 1 1 1 @@ -558,7 +558,7 @@ def _find_scaling_L_ratio(self): Dlist = [5,8,12,13,17,21,24,28,29, 33, 37, 40, 41, 44, 53, 56, 57, 60, 61, 65, 69, 73, 76, 77, 85, 88, 89, 92, 93, 97] # a list of positive fundamental discriminants j = 0 at0 = 0 - # computes [0]+ for the twist of E by D until one value is non-zero + # computes [0]+ for the twist of E by D until one value is nonzero while j < 30 and at0 == 0 : D = Dlist[j] # the following line checks if the twist of the newform of E by D is a newform @@ -580,7 +580,7 @@ def _find_scaling_L_ratio(self): j = 0 at0 = 0 while j < 30 and at0 == 0 : - # computes [0]+ for the twist of E by D until one value is non-zero + # computes [0]+ for the twist of E by D until one value is nonzero D = Dlist[j] if all( valuation(E.conductor(),ell) <= valuation(D,ell) for ell in prime_divisors(D) ) : at0 = - sum([kronecker_symbol(D,u) * self(ZZ(u)/D) for u in range(1,abs(D))]) @@ -712,7 +712,7 @@ def _call_with_caching(self, r): EXAMPLES:: - sage: m = EllipticCurve('11a1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('11a1').modular_symbol(implementation='sage') sage: m._call_with_caching(0) 1/5 """ @@ -733,7 +733,7 @@ def __call__(self, r, base_at_infinity=True): EXAMPLES:: - sage: m = EllipticCurve('11a1').modular_symbol(implementation="sage") + sage: m = EllipticCurve('11a1').modular_symbol(implementation='sage') sage: m(0) 1/5 """ diff --git a/src/sage/schemes/elliptic_curves/ell_number_field.py b/src/sage/schemes/elliptic_curves/ell_number_field.py old mode 100644 new mode 100755 index 8ea2c766f6d..8ccdbcd452d --- a/src/sage/schemes/elliptic_curves/ell_number_field.py +++ b/src/sage/schemes/elliptic_curves/ell_number_field.py @@ -178,7 +178,7 @@ def simon_two_descent(self, verbose=0, lim1=2, lim3=4, limtriv=2, - ``self`` -- an elliptic curve `E` over a number field `K` - - ``verbose`` -- 0, 1, 2, or 3 (default: 0), the verbosity level + - ``verbose`` -- 0, 1, 2, or 3 (default: 0); the verbosity level - ``lim1`` -- (default: 2) limit on trivial points on quartics @@ -192,14 +192,14 @@ def simon_two_descent(self, verbose=0, lim1=2, lim3=4, limtriv=2, small and large prime numbers. Use probabilistic tests for large primes. If 0, do not use probabilistic tests. - - ``known_points`` -- (default: None) list of known points on + - ``known_points`` -- (default: ``None``) list of known points on the curve OUTPUT: a triple ``(lower, upper, list)`` consisting of - - ``lower`` (integer) -- lower bound on the rank + - ``lower`` -- integer; lower bound on the rank - - ``upper`` (integer) -- upper bound on the rank + - ``upper`` -- integer; upper bound on the rank - ``list`` -- list of points in `E(K)` @@ -318,19 +318,19 @@ def simon_two_descent(self, verbose=0, lim1=2, lim3=4, limtriv=2, return t def height_pairing_matrix(self, points=None, precision=None, normalised=True): - r"""Return the height pairing matrix of the given points. + r""" + Return the height pairing matrix of the given points. INPUT: - - ``points`` (list or ``None`` (default)) -- a list of points - on this curve, or ``None``, in which case self.gens() will - be used. + - ``points`` -- list or ``None`` (default); list of points + on this curve, or ``None``, in which case ``self.gens()`` will + be used - - ``precision`` (int or ``None`` (default)) -- number of bits - of precision of result, or ``None``, for default RealField - precision. + - ``precision`` -- integer or ``None`` (default); number of bits + of precision of result, or ``None``, for default RealField precision - - ``normalised`` (bool, default ``True``) -- if ``True``, use + - ``normalised`` -- boolean (default: ``True``); if ``True``, use normalised heights which are independent of base change. Otherwise use the non-normalised Néron-Tate height, as required for the regulator in the BSD conjecture. @@ -416,12 +416,12 @@ def regulator_of_points(self, points=[], precision=None, normalised=True): INPUT: - - ``points`` -- (default: empty list) a list of points on this curve + - ``points`` -- (default: empty list) a list of points on this curve - - ``precision`` -- int or None (default: None): the precision - in bits of the result (default real precision if None) + - ``precision`` -- integer or ``None`` (default); the + precision in bits of the result (default: real precision if ``None``) - - ``normalised`` (bool, default ``True``) -- if ``True``, use + - ``normalised`` -- boolean (default: ``True``); if ``True``, use normalised heights which are independent of base change. Otherwise use the non-normalised Néron-Tate height, as required for the regulator in the BSD conjecture @@ -522,16 +522,16 @@ def regulator_of_points(self, points=[], precision=None, normalised=True): if points is None: points = [] mat = self.height_pairing_matrix(points=points, precision=precision, normalised=normalised) - return mat.det(algorithm="hessenberg") + return mat.det(algorithm='hessenberg') def is_local_integral_model(self, *P): r""" - Tests if self is integral at the prime ideal `P`, or at all the + Test if ``self`` is integral at the prime ideal `P`, or at all the primes if `P` is a list or tuple. INPUT: - - ``*P`` -- a prime ideal, or a list or tuple of primes. + - ``*P`` -- a prime ideal, or a list or tuple of primes EXAMPLES:: @@ -552,7 +552,7 @@ def is_local_integral_model(self, *P): def local_integral_model(self,*P): r""" - Return a model of self which is integral at the prime ideal `P`. + Return a model of ``self`` which is integral at the prime ideal `P`. .. NOTE:: @@ -561,7 +561,7 @@ def local_integral_model(self,*P): INPUT: - - ``*P`` -- a prime ideal, or a list or tuple of primes. + - ``*P`` -- a prime ideal, or a list or tuple of primes EXAMPLES:: @@ -603,7 +603,7 @@ def is_global_integral_model(self): def global_integral_model(self): r""" - Return a model of self which is integral at all primes. + Return a model of ``self`` which is integral at all primes. EXAMPLES:: @@ -838,28 +838,29 @@ def _scale_by_units(self): u = prod([uj**ej for uj,ej in zip(fu,es)]) return self.scale_curve(u) - def local_data(self, P=None, proof=None, algorithm="pari", globally=False): + def local_data(self, P=None, proof=None, algorithm='pari', globally=False): r""" Local data for this elliptic curve at the prime `P`. INPUT: - - ``P`` -- either None, a prime ideal of the base field of self, or an element of the base field that generates a prime ideal. + - ``P`` -- either ``None``, a prime ideal of the base field of ``self``, + or an element of the base field that generates a prime ideal - ``proof`` -- whether to only use provably correct methods (default controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - - ``algorithm`` (string, default: "pari") -- Ignored unless the - base field is `\QQ`. If "pari", use the PARI C-library + - ``algorithm`` -- string (default: ``'pari'``); ignored unless the + base field is `\QQ`. If ``'pari'``, use the PARI C-library :pari:`ellglobalred` implementation of Tate's algorithm over - `\QQ`. If "generic", use the general number field + `\QQ`. If ``'generic'``, use the general number field implementation. - ``globally`` -- whether the local algorithm uses global generators for the prime ideals. Default is False, which will not require any - information about the class group. If True, a generator for `P` + information about the class group. If ``True``, a generator for `P` will be used if `P` is principal. Otherwise, or if ``globally`` is False, the minimal model returned will preserve integrality at other primes, but not minimality. @@ -942,7 +943,7 @@ def local_data(self, P=None, proof=None, algorithm="pari", globally=False): return self._get_local_data(P,proof,algorithm,globally) - def _get_local_data(self, P, proof, algorithm="pari", globally=False): + def _get_local_data(self, P, proof, algorithm='pari', globally=False): r""" Internal function to create data for this elliptic curve at the prime `P`. @@ -952,22 +953,22 @@ def _get_local_data(self, P, proof, algorithm="pari", globally=False): INPUT: - - ``P`` -- either None or a prime ideal of the base field of self. + - ``P`` -- either ``None`` or a prime ideal of the base field of ``self`` - ``proof`` -- whether to only use provably correct methods (default controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - - ``algorithm`` (string, default: "pari") -- Ignored unless the - base field is `\QQ`. If "pari", use the PARI C-library + - ``algorithm`` -- string (default: ``'pari'``); ignored unless the + base field is `\QQ`. If ``'pari'``, use the PARI C-library :pari:`ellglobalred` implementation of Tate's algorithm over - `\QQ`. If "generic", use the general number field + `\QQ`. If ``'generic'``, use the general number field implementation. - ``globally`` -- whether the local algorithm uses global generators for the prime ideals. Default is False, which will not require any - information about the class group. If True, a generator for `P` + information about the class group. If ``True``, a generator for `P` will be used if `P` is principal. Otherwise, or if ``globally`` is False, the minimal model returned will preserve integrality at other primes, but not minimality. @@ -1006,23 +1007,23 @@ def _get_local_data(self, P, proof, algorithm="pari", globally=False): self._local_data[P, proof, algorithm, globally] = EllipticCurveLocalData(self, P, proof, algorithm, globally) return self._local_data[P, proof, algorithm, globally] - def local_minimal_model(self, P, proof=None, algorithm="pari"): + def local_minimal_model(self, P, proof=None, algorithm='pari'): r""" Return a model which is integral at all primes and minimal at `P`. INPUT: - - ``P`` -- either None or a prime ideal of the base field of self. + - ``P`` -- either ``None`` or a prime ideal of the base field of ``self`` - ``proof`` -- whether to only use provably correct methods (default controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - - ``algorithm`` (string, default: "pari") -- Ignored unless the - base field is `\QQ`. If "pari", use the PARI C-library + - ``algorithm`` -- string (default: ``'pari'``); ignored unless the + base field is `\QQ`. If ``'pari'``, use the PARI C-library :pari:`ellglobalred` implementation of Tate's algorithm over - `\QQ`. If "generic", use the general number field + `\QQ`. If ``'generic'``, use the general number field implementation. OUTPUT: @@ -1056,16 +1057,16 @@ def local_minimal_model(self, P, proof=None, algorithm="pari"): def has_good_reduction(self, P): r""" - Return True if this elliptic curve has good reduction at the prime `P`. + Return ``True`` if this elliptic curve has good reduction at the prime `P`. INPUT: - - ``P`` -- a prime ideal of the base field of self, or a field - element generating such an ideal. + - ``P`` -- a prime ideal of the base field of ``self``, or a field + element generating such an ideal OUTPUT: - (bool) -- True if the curve has good reduction at `P`, else False. + boolean; ``True`` if the curve has good reduction at `P`, else ``False``. .. NOTE:: @@ -1090,16 +1091,16 @@ def has_good_reduction(self, P): def has_bad_reduction(self, P): r""" - Return True if this elliptic curve has bad reduction at the prime `P`. + Return ``True`` if this elliptic curve has bad reduction at the prime `P`. INPUT: - - ``P`` -- a prime ideal of the base field of self, or a field - element generating such an ideal. + - ``P`` -- a prime ideal of the base field of ``self``, or a field + element generating such an ideal OUTPUT: - (bool) True if the curve has bad reduction at `P`, else False. + boolean; ``True`` if the curve has bad reduction at `P`, else ``False``. .. NOTE:: @@ -1124,7 +1125,8 @@ def has_bad_reduction(self, P): def has_multiplicative_reduction(self, P): r""" - Return True if this elliptic curve has (bad) multiplicative reduction at the prime `P`. + Return ``True`` if this elliptic curve has (bad) multiplicative + reduction at the prime `P`. .. NOTE:: @@ -1133,13 +1135,13 @@ def has_multiplicative_reduction(self, P): INPUT: - - ``P`` -- a prime ideal of the base field of self, or a field - element generating such an ideal. + - ``P`` -- a prime ideal of the base field of ``self``, or a field + element generating such an ideal OUTPUT: - (bool) True if the curve has multiplicative reduction at `P`, - else False. + boolean; ``True`` if the curve has multiplicative reduction at `P`, + else ``False``. EXAMPLES:: @@ -1158,17 +1160,17 @@ def has_multiplicative_reduction(self, P): def has_split_multiplicative_reduction(self, P): r""" - Return True if this elliptic curve has (bad) split multiplicative reduction at the prime `P`. + Return ``True`` if this elliptic curve has (bad) split multiplicative reduction at the prime `P`. INPUT: - - ``P`` -- a prime ideal of the base field of self, or a field - element generating such an ideal. + - ``P`` -- a prime ideal of the base field of ``self``, or a field + element generating such an ideal OUTPUT: - (bool) True if the curve has split multiplicative reduction at - `P`, else False. + boolean; ``True`` if the curve has split multiplicative reduction at + `P`, else ``False``. EXAMPLES:: @@ -1187,17 +1189,18 @@ def has_split_multiplicative_reduction(self, P): def has_nonsplit_multiplicative_reduction(self, P): r""" - Return True if this elliptic curve has (bad) non-split multiplicative reduction at the prime `P`. + Return ``True`` if this elliptic curve has (bad) non-split + multiplicative reduction at the prime `P`. INPUT: - - ``P`` -- a prime ideal of the base field of self, or a field - element generating such an ideal. + - ``P`` -- a prime ideal of the base field of ``self``, or a field + element generating such an ideal OUTPUT: - (bool) True if the curve has non-split multiplicative - reduction at `P`, else False. + boolean; ``True`` if the curve has non-split multiplicative + reduction at `P`, else ``False``. EXAMPLES:: @@ -1216,16 +1219,18 @@ def has_nonsplit_multiplicative_reduction(self, P): def has_additive_reduction(self, P): r""" - Return True if this elliptic curve has (bad) additive reduction at the prime `P`. + Return ``True`` if this elliptic curve has (bad) additive reduction at + the prime `P`. INPUT: - - ``P`` -- a prime ideal of the base field of self, or a field - element generating such an ideal. + - ``P`` -- a prime ideal of the base field of ``self``, or a field + element generating such an ideal OUTPUT: - (bool) True if the curve has additive reduction at `P`, else False. + boolean; ``True`` if the curve has additive reduction at `P`, else + ``False``. EXAMPLES:: @@ -1248,16 +1253,14 @@ def tamagawa_number(self, P, proof=None): INPUT: - - ``P`` -- either None or a prime ideal of the base field of self. + - ``P`` -- either ``None`` or a prime ideal of the base field of ``self`` - ``proof`` -- whether to only use provably correct methods (default controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - OUTPUT: - - (positive integer) The Tamagawa number of the curve at `P`. + OUTPUT: positive integer; the Tamagawa number of the curve at `P` EXAMPLES:: @@ -1304,16 +1307,14 @@ def tamagawa_exponent(self, P, proof=None): INPUT: - - ``P`` -- either None or a prime ideal of the base field of self. + - ``P`` -- either ``None`` or a prime ideal of the base field of ``self`` - ``proof`` -- whether to only use provably correct methods (default controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - OUTPUT: - - (positive integer) The Tamagawa index of the curve at P. + OUTPUT: positive integer; the Tamagawa index of the curve at P EXAMPLES:: @@ -1343,9 +1344,7 @@ def tamagawa_product(self): additional factor when the model is not globally minimal, as required by the BSD formula. - OUTPUT: - - A positive integer. + OUTPUT: a positive integer EXAMPLES:: @@ -1398,9 +1397,7 @@ def tamagawa_product_bsd(self): of the Tamagawa numbers, so the two definitions only agree when the model is global minimal. - OUTPUT: - - A rational number + OUTPUT: a rational number EXAMPLES:: @@ -1454,16 +1451,14 @@ def kodaira_symbol(self, P, proof=None): INPUT: - - ``P`` -- either None or a prime ideal of the base field of self. + - ``P`` -- either ``None`` or a prime ideal of the base field of ``self`` - ``proof`` -- whether to only use provably correct methods (default controlled by global proof module). Note that the proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - OUTPUT: - - The Kodaira Symbol of the curve at ``P``, represented as a string. + OUTPUT: the Kodaira Symbol of the curve at ``P``, represented as a string EXAMPLES:: @@ -1491,9 +1486,7 @@ def conductor(self): Return the conductor of this elliptic curve as a fractional ideal of the base field. - OUTPUT: - - (fractional ideal) The conductor of the curve. + OUTPUT: fractional ideal; the conductor of the curve EXAMPLES:: @@ -1628,7 +1621,7 @@ def non_minimal_primes(self): sage: Emin.non_minimal_primes() [] - If the model is not globally integral, a :class:`ValueError` is + If the model is not globally integral, a :exc:`ValueError` is raised:: sage: E = EllipticCurve([0, 0, 0, 1/2, 1/3]) @@ -1757,7 +1750,7 @@ def has_global_minimal_model(self): OUTPUT: - Boolean, True iff a global minimal model exists, i.e. an + boolean; ``True`` iff a global minimal model exists, i.e. an integral model which is minimal at every prime. EXAMPLES:: @@ -1773,7 +1766,7 @@ def has_global_minimal_model(self): def global_minimal_model(self, proof=None, semi_global=False): r""" - Return a model of self that is integral, and minimal. + Return a model of ``self`` that is integral, and minimal. .. NOTE:: @@ -1789,7 +1782,7 @@ def global_minimal_model(self, proof=None, semi_global=False): proof module is number_field, not elliptic_curves, since the functions that actually need the flag are in number fields. - - ``semi_global`` (boolean, default: ``False``) -- if there is no + - ``semi_global``-- boolean (default: ``False``); if there is no global minimal mode, return a semi-global minimal model (minimal at all but one prime) instead, if True; raise an error if False. No effect if a global minimal model exists. @@ -1922,9 +1915,7 @@ def reduction(self,place): - ``place`` -- a prime ideal in the base field of the curve - OUTPUT: - - An elliptic curve over a finite field, the residue field of the place. + OUTPUT: an elliptic curve over a finite field, the residue field of the place EXAMPLES:: @@ -1971,7 +1962,7 @@ def torsion_subgroup(self): r""" Return the torsion subgroup of this elliptic curve. - OUTPUT: The :class:`EllipticCurveTorsionSubgroup` associated to this elliptic + OUTPUT: the :class:`EllipticCurveTorsionSubgroup` associated to this elliptic curve. EXAMPLES:: @@ -2030,9 +2021,7 @@ def torsion_order(self): r""" Return the order of the torsion subgroup of this elliptic curve. - OUTPUT: - - (integer) the order of the torsion subgroup of this elliptic curve. + OUTPUT: integer EXAMPLES:: @@ -2072,9 +2061,7 @@ def torsion_points(self): r""" Return a list of the torsion points of this elliptic curve. - OUTPUT: - - (list) A sorted list of the torsion points. + OUTPUT: sorted list of the torsion points EXAMPLES:: @@ -2162,11 +2149,11 @@ def rank_bounds(self, **kwds): INPUT: - - ``verbose`` -- 0, 1, 2, or 3 (default: 0), the verbosity level + - ``verbose`` -- 0, 1, 2, or 3 (default: 0); the verbosity level - - ``lim1`` -- (default: 2) limit on trivial points on quartics + - ``lim1`` -- (default: 2) limit on trivial points on quartics - - ``lim3`` -- (default: 4) limit on points on ELS quartics + - ``lim3`` -- (default: 4) limit on points on ELS quartics - ``limtriv`` -- (default: 2) limit on trivial points on elliptic curve @@ -2176,12 +2163,10 @@ def rank_bounds(self, **kwds): small and large prime numbers. Use probabilistic tests for large primes. If 0, do not use probabilistic tests. - - ``known_points`` -- (default: None) list of known points on + - ``known_points`` -- (default: ``None``) list of known points on the curve - OUTPUT: - - lower and upper bounds for the rank of the Mordell-Weil group + OUTPUT: lower and upper bounds for the rank of the Mordell-Weil group .. NOTE:: @@ -2239,11 +2224,11 @@ def rank(self, **kwds): INPUT: - - ``verbose`` -- 0, 1, 2, or 3 (default: 0), the verbosity level + - ``verbose`` -- 0, 1, 2, or 3 (default: 0); the verbosity level - - ``lim1`` -- (default: 2) limit on trivial points on quartics + - ``lim1`` -- (default: 2) limit on trivial points on quartics - - ``lim3`` -- (default: 4) limit on points on ELS quartics + - ``lim3`` -- (default: 4) limit on points on ELS quartics - ``limtriv`` -- (default: 2) limit on trivial points on elliptic curve @@ -2253,14 +2238,14 @@ def rank(self, **kwds): small and large prime numbers. Use probabilistic tests for large primes. If 0, do not use probabilistic tests. - - ``known_points`` -- (default: None) list of known points on + - ``known_points`` -- (default: ``None``) list of known points on the curve OUTPUT: If the upper and lower bounds given by Simon two-descent are the same, then the rank has been uniquely identified and we - return this. Otherwise, we raise a :class:`ValueError` with an error + return this. Otherwise, we raise a :exc:`ValueError` with an error message specifying the upper and lower bounds. .. NOTE:: @@ -2321,11 +2306,11 @@ def gens(self, **kwds): INPUT: - - ``verbose`` -- 0, 1, 2, or 3 (default: 0), the verbosity level + - ``verbose`` -- 0, 1, 2, or 3 (default: 0); the verbosity level - - ``lim1`` -- (default: 2) limit on trivial points on quartics + - ``lim1`` -- (default: 2) limit on trivial points on quartics - - ``lim3`` -- (default: 4) limit on points on ELS quartics + - ``lim3`` -- (default: 4) limit on points on ELS quartics - ``limtriv`` -- (default: 2) limit on trivial points on elliptic curve @@ -2335,12 +2320,10 @@ def gens(self, **kwds): small and large prime numbers. Use probabilistic tests for large primes. If 0, do not use probabilistic tests. - - ``known_points`` -- (default: None) list of known points on + - ``known_points`` -- (default: ``None``) list of known points on the curve - OUTPUT: - - A set of points of infinite order given by the Simon two-descent. + OUTPUT: a set of points of infinite order given by the Simon two-descent .. NOTE:: @@ -2416,7 +2399,7 @@ def period_lattice(self, embedding): INPUT: - - ``embedding`` -- an embedding of the base number field into `\RR` or `\CC`. + - ``embedding`` -- an embedding of the base number field into `\RR` or `\CC` .. NOTE:: @@ -2529,7 +2512,7 @@ def real_components(self, embedding): def height_function(self): """ - Return the canonical height function attached to self. + Return the canonical height function attached to ``self``. EXAMPLES:: @@ -2555,17 +2538,17 @@ def isogeny_class(self, reducible_primes=None, algorithm='Billerey', minimal_mod INPUT: - - ``reducible_primes`` (list of ints, or None (default)) -- if - not None then this should be a list of primes; in computing + - ``reducible_primes`` -- list of integers or ``None`` (default)); if + not ``None`` then this should be a list of primes; in computing the isogeny class, only composites isogenies of these degrees will be used. - - ``algorithm`` (string, default ``'Billerey'``) -- the algorithm + - ``algorithm`` -- string (default: ``'Billerey'``); the algorithm to use to compute the reducible primes. Ignored for CM curves or if ``reducible_primes`` is provided. Values are ``'Billerey'`` (default), ``'Larson'``, and ``'heuristic'``. - - ``minimal_models`` (bool, default ``True``) -- if ``True``, + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves in the class will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -2945,27 +2928,25 @@ class number is only `3` is that the class also contains three def isogenies_prime_degree(self, l=None, algorithm='Billerey', minimal_models=True): r""" - Return a list of `\ell`-isogenies from self, where `\ell` is a + Return a list of `\ell`-isogenies from ``self``, where `\ell` is a prime. INPUT: - - ``l`` -- either None or a prime or a list of primes. + - ``l`` -- either ``None`` or a prime or a list of primes - - ``algorithm`` (string, default 'Billerey') -- the algorithm - to use to compute the reducible primes when ``l`` is None. + - ``algorithm`` -- string (default: ``'Billerey'``); the algorithm + to use to compute the reducible primes when ``l`` is ``None``. Ignored for CM curves or if ``l`` is provided. Values are 'Billerey' (default), 'Larson', and 'heuristic'. - - ``minimal_models`` (bool, default ``True``) -- if ``True``, + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. - OUTPUT: - - (list) `\ell`-isogenies for the given `\ell` or if `\ell` is None, all - isogenies of prime degree (see below for the CM case). + OUTPUT: list; `\ell`-isogenies for the given `\ell` or if `\ell` is + ``None``, all isogenies of prime degree (see below for the CM case) .. NOTE:: @@ -3060,26 +3041,26 @@ def isogenies_prime_degree(self, l=None, algorithm='Billerey', minimal_models=Tr def is_isogenous(self, other, proof=True, maxnorm=100): """ - Return whether or not self is isogenous to other. + Return whether or not ``self`` is isogenous to ``other``. INPUT: - - ``other`` -- another elliptic curve. + - ``other`` -- another elliptic curve - - ``proof`` (default: ``True``) -- If ``False``, the function will - return ``True`` whenever the two curves have the same + - ``proof`` -- boolean (default: ``True``); if ``False``, the function + will return ``True`` whenever the two curves have the same conductor and are isogenous modulo `p` for all primes `p` of norm up to ``maxnorm``. If ``True``, the function returns False when the previous condition does not hold, and if it does hold we compute the complete isogeny class to see if the curves are indeed isogenous. - - ``maxnorm`` (integer, default 100) -- The maximum norm of - primes `p` for which isogeny modulo `p` will be checked. + - ``maxnorm`` -- integer (default: 100); the maximum norm of + primes `p` for which isogeny modulo `p` will be checked OUTPUT: - (bool) True if there is an isogeny from curve ``self`` to + boolean; ``True`` if there is an isogeny from curve ``self`` to curve ``other``. EXAMPLES:: @@ -3238,16 +3219,14 @@ def is_isogenous(self, other, proof=True, maxnorm=100): def isogeny_degree(self, other): """ - Return the minimal degree of an isogeny between self and - other, or 0 if no isogeny exists. + Return the minimal degree of an isogeny between ``self`` and + ``other``, or 0 if no isogeny exists. INPUT: - - ``other`` -- another elliptic curve. - - OUTPUT: + - ``other`` -- another elliptic curve - (int) The degree of an isogeny from ``self`` to ``other``, or 0. + OUTPUT: integer; the degree of an isogeny from ``self`` to ``other``, or 0 EXAMPLES:: @@ -3306,17 +3285,17 @@ def reducible_primes(self, algorithm='Billerey', max_l=None, INPUT: - - ``algorithm`` (string) -- only relevant for non-CM curves. + - ``algorithm`` -- string; only relevant for non-CM curves Either 'Billerey", to use the methods of [Bil2011]_, 'Larson' to use Larson's implementation using Galois representations, or 'heuristic' (see below). - - ``max_l`` (int or ``None``) -- only relevant for non-CM + - ``max_l`` -- integer or ``None``; only relevant for non-CM curves and algorithms 'Billerey' and 'heuristic. Controls the maximum prime used in either algorithm. If ``None``, use the default for that algorithm. - - ``num_l`` (int or ``None``) -- only relevant for non-CM + - ``num_l`` -- integer or ``None``; only relevant for non-CM curves and algorithm 'Billerey'. Controls the maximum number of primes used in the algorithm. If ``None``, use the default for that algorithm. @@ -3370,8 +3349,8 @@ def lll_reduce(self, points, height_matrix=None, precision=None): INPUT: - - ``points`` -- a list of points on this elliptic - curve, which should be independent. + - ``points`` -- list of points on this elliptic + curve, which should be independent - ``height_matrix`` -- the height-pairing matrix of the points, or ``None``. If ``None``, it will be computed. @@ -3380,7 +3359,7 @@ def lll_reduce(self, points, height_matrix=None, precision=None): computations (default: ``None``, for default RealField precision; ignored if ``height_matrix`` is supplied) - OUTPUT: A tuple (newpoints, U) where U is a unimodular integer + OUTPUT: a tuple (newpoints, U) where U is a unimodular integer matrix, new_points is the transform of points by U, such that new_points has LLL-reduced height pairing matrix @@ -3711,14 +3690,14 @@ def is_Q_curve(self, maxp=100, certificate=False, verbose=False): INPUT: - - ``maxp`` (int, default 100): bound on primes used for + - ``maxp`` -- integer (default: 100); bound on primes used for checking necessary local conditions. The result will not depend on this, but using a larger value may return ``False`` faster. - - ``certificate`` (bool, default ``False``): if ``True`` then + - ``certificate`` -- boolean (default: ``False``); if ``True`` then a second value is returned giving a certificate for the - `\QQ`-curve property. + `\QQ`-curve property OUTPUT: @@ -3862,42 +3841,42 @@ def saturation(self, points, verbose=False, order are ignored; the remaining points should be independent, or an error is raised. - - ``verbose`` (bool) -- (default: ``False``), if ``True``, give - verbose output. + - ``verbose`` -- boolean (default: ``False``); if ``True``, give + verbose output - - ``max_prime`` (int, default 0) -- saturation is performed + - ``max_prime`` -- integer (default: 0); saturation is performed for all primes up to ``max_prime``. If ``max_prime`` is 0, perform saturation at *all* primes, i.e., compute the true saturation. - - ``odd_primes_only`` (bool, default ``False``) -- only do - saturation at odd primes. + - ``odd_primes_only`` -- boolean (default: ``False``); only do + saturation at odd primes - - ``one_prime`` (int, default 0) -- if nonzero, only do - saturation at this prime. + - ``one_prime`` -- integer (default: 0); if nonzero, only do + saturation at this prime The following two inputs are optional, and may be provided to speed up the computation. - - ``lower_ht_bound`` (real, default ``None``) -- lower bound of - the regulator `E(K)`, if known. + - ``lower_ht_bound`` -- real (default: ``None``); lower bound of + the regulator `E(K)`, if known - - ``reg`` (real, default ``None``) -- regulator of the span of - points, if known. + - ``reg`` -- real (default: ``None``); regulator of the span of + points, if known - - ``debug`` (int, default 0) -- used for debugging and - testing. + - ``debug`` -- integer (default: 0); used for debugging and + testing OUTPUT: - - ``saturation`` (list) -- points that form a basis for the - saturation. + - ``saturation`` -- list; points that form a basis for the + saturation - - ``index`` (int) -- the index of the group generated by the - input points in their saturation. + - ``index`` -- integer; the index of the group generated by the + input points in their saturation - - ``regulator`` (real with default precision, or ``None``) -- - regulator of saturated points. + - ``regulator`` -- real with default precision, or ``None``; + regulator of saturated points EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_padic_field.py b/src/sage/schemes/elliptic_curves/ell_padic_field.py old mode 100644 new mode 100755 index 2867ff51d23..32f4a48a807 --- a/src/sage/schemes/elliptic_curves/ell_padic_field.py +++ b/src/sage/schemes/elliptic_curves/ell_padic_field.py @@ -1,6 +1,6 @@ # sage.doctest: needs sage.rings.padics """ -Elliptic curves over padic fields +Elliptic curves over `p`-adic fields """ # **************************************************************************** # Copyright (C) 2007 Robert Bradshaw @@ -30,7 +30,7 @@ class EllipticCurve_padic_field(EllipticCurve_field, HyperellipticCurve_padic_field): """ - Elliptic curve over a padic field. + Elliptic curve over a `p`-adic field. EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_point.py b/src/sage/schemes/elliptic_curves/ell_point.py old mode 100644 new mode 100755 index 568d76ffc94..0c670a3b9d7 --- a/src/sage/schemes/elliptic_curves/ell_point.py +++ b/src/sage/schemes/elliptic_curves/ell_point.py @@ -75,7 +75,7 @@ Arithmetic over `\ZZ/N\ZZ` with composite `N` is supported. When an operation tries to invert a non-invertible element, a -:class:`ZeroDivisionError` is raised and a factorization of the modulus appears +:exc:`ZeroDivisionError` is raised and a factorization of the modulus appears in the error message:: sage: N = 1715761513 @@ -272,9 +272,9 @@ def __init__(self, curve, v, check=True): INPUT: - - curve -- an elliptic curve - - v -- data determining a point (another point, the integer - 0, or a tuple of coordinates) + - ``curve`` -- an elliptic curve + - ``v`` -- data determining a point (another point, the integer + 0, or a tuple of coordinates) EXAMPLES:: @@ -405,7 +405,7 @@ def _richcmp_(self, other, op): def __pari__(self): r""" - Converts this point to PARI format. + Convert this point to PARI format. EXAMPLES:: @@ -451,7 +451,7 @@ def order(self): Return the order of this point on the elliptic curve. If the point is zero, returns 1, otherwise raise a - :class:`NotImplementedError`. + :exc:`NotImplementedError`. For curves over number fields and finite fields, see below. @@ -507,7 +507,7 @@ def has_order(self, n): INPUT: - - ``n`` -- integer, or its :class:`~sage.structure.factorization.Factorization` + - ``n`` -- integer or its :class:`~sage.structure.factorization.Factorization` ALGORITHM: @@ -631,11 +631,11 @@ def has_finite_order(self): def has_infinite_order(self): """ - Return True if this point has infinite additive order as an element + Return ``True`` if this point has infinite additive order as an element of the group of points on this curve. For fields other than number fields and finite fields, this is - NotImplemented unless self.is_zero(). + NotImplemented unless ``self.is_zero()``. EXAMPLES:: @@ -663,7 +663,7 @@ def plot(self, **args): INPUT: - ``**args`` -- all arguments get passed directly onto the point - plotting function. + plotting function EXAMPLES:: @@ -682,7 +682,7 @@ def plot(self, **args): def _add_(self, right): """ - Add self to right. + Add ``self`` to ``right``. EXAMPLES:: @@ -772,7 +772,7 @@ def _add_(self, right): def _sub_(self, right): """ - Subtract right from self. + Subtract ``right`` from ``self``. EXAMPLES:: @@ -818,7 +818,7 @@ def __neg__(self): def xy(self): """ Return the `x` and `y` coordinates of this point, as a 2-tuple. - If this is the point at infinity, a :class:`ZeroDivisionError` is raised. + If this is the point at infinity, a :exc:`ZeroDivisionError` is raised. EXAMPLES:: @@ -841,7 +841,7 @@ def xy(self): def x(self): """ Return the `x` coordinate of this point, as an element of the base field. - If this is the point at infinity, a :class:`ZeroDivisionError` is raised. + If this is the point at infinity, a :exc:`ZeroDivisionError` is raised. EXAMPLES:: @@ -864,7 +864,7 @@ def x(self): def y(self): """ Return the `y` coordinate of this point, as an element of the base field. - If this is the point at infinity, a :class:`ZeroDivisionError` is raised. + If this is the point at infinity, a :exc:`ZeroDivisionError` is raised. EXAMPLES:: @@ -886,16 +886,16 @@ def y(self): def is_divisible_by(self, m): """ - Return True if there exists a point `Q` defined over the same - field as self such that `mQ` == self. + Return ``True`` if there exists a point `Q` defined over the same + field as ``self`` such that `mQ` == ``self``. INPUT: - - ``m`` -- a positive integer. + - ``m`` -- positive integer OUTPUT: - (bool) -- True if there is a solution, else False. + boolean; ``True`` if there is a solution, else False. .. WARNING:: @@ -1010,21 +1010,19 @@ def division_points(self, m, poly_only=False): r""" Return a list of all points `Q` such that `mQ=P` where `P` = ``self``. - Only points on the elliptic curve containing self and defined + Only points on the elliptic curve containing ``self`` and defined over the base field are included. INPUT: - - ``m`` -- a positive integer + - ``m`` -- positive integer - - ``poly_only`` -- bool (default: ``False``); if True return + - ``poly_only`` -- boolean (default: ``False``); if ``True`` return polynomial whose roots give all possible `x`-coordinates of - `m`-th roots of ``self``. - - OUTPUT: + `m`-th roots of ``self`` - (list) -- a (possibly empty) list of solutions `Q` to `mQ=P`, - where `P` = self. + OUTPUT: a (possibly empty) list of solutions `Q` to `mQ=P`, + where `P` = ``self`` EXAMPLES: @@ -1256,20 +1254,19 @@ def division_points(self, m, poly_only=False): def _divide_out(self, p): r""" - Return `(Q,k)` where `p^kQ` == self and `Q` cannot be divided by `p`. + Return `(Q,k)` where `p^kQ` == ``self`` and `Q` cannot be divided by `p`. .. WARNING:: It is up to the caller to make sure that this does not loop endlessly. It is used in ``EllipticCurve_generic._p_primary_torsion_basis()``, when - self will always have (finite) order which is a power of `p`, + ``self`` will always have (finite) order which is a power of `p`, so that the order of `Q` increases by a factor of `p` at each stage. Since it will clearly be in danger of looping when - self.is_zero(), this case is caught, but otherwise caveat - user. + ``self.is_zero()``, this case is caught, but otherwise caveat user. EXAMPLES:: @@ -1322,7 +1319,7 @@ def set_order(self, value=None, *, multiple=None, check=True): - ``value`` -- positive integer - ``multiple`` -- positive integer; mutually exclusive with ``value`` - OUTPUT: ``None`` + OUTPUT: none EXAMPLES: @@ -1479,17 +1476,17 @@ def set_order(self, value=None, *, multiple=None, check=True): def _line_(self, R, Q): r""" - Computes the value at `Q` of a straight line through points - self and `R`. + Compute the value at `Q` of a straight line through points + ``self`` and `R`. INPUT: - - ``R``, ``Q`` -- points on self.curve() with ``Q`` nonzero. + - ``R``, ``Q`` -- points on ``self.curve()`` with `Q` nonzero OUTPUT: - An element of the base field self.curve().base_field(). - A ValueError is raised if ``Q`` is zero. + An element of the base field ``self.curve().base_field()``. + A :exc:`ValueError` is raised if `Q` is zero. EXAMPLES:: @@ -1560,15 +1557,15 @@ def _miller_(self, Q, n): INPUT: - - ``Q`` -- a nonzero point on self.curve(). + - ``Q`` -- a nonzero point on ``self.curve()`` - - ``n`` -- a nonzero integer. If `n<0` then return `Q` - evaluated at `1/(v_{nP}*f_{n,P})` (used in the ate pairing). + - ``n`` -- nonzero integer; if `n<0` then return `Q` + evaluated at `1/(v_{nP}*f_{n,P})` (used in the ate pairing) OUTPUT: An element in the base field ``self.curve().base_field()``. - A :class:`ValueError` is raised if `Q` is zero. + A :exc:`ValueError` is raised if `Q` is zero. EXAMPLES:: @@ -1741,19 +1738,17 @@ def weil_pairing(self, Q, n, algorithm=None): INPUT: - - ``Q`` -- another point on the same curve as ``self``. + - ``Q`` -- another point on the same curve as ``self`` - - ``n`` -- an integer `n` such that `nP = nQ = (0:1:0)`, where - `P` is ``self``. + - ``n`` -- integer `n` such that `nP = nQ = (0:1:0)`, where + `P` is ``self`` - - ``algorithm`` (default: ``None``) -- choices are ``pari`` - and ``sage``. PARI is usually significantly faster, but it + - ``algorithm`` -- (default: ``None``) choices are ``'pari'`` + and ``'sage'``. PARI is usually significantly faster, but it only works over finite fields. When ``None`` is given, a suitable algorithm is chosen automatically. - OUTPUT: - - An `n`'th root of unity in the base field of the curve. + OUTPUT: an `n`-th root of unity in the base field of the curve EXAMPLES:: @@ -1847,7 +1842,7 @@ def weil_pairing(self, Q, n, algorithm=None): - For ``algorithm='sage'``: Implemented using Proposition 8 in [Mil2004]_. The value 1 is returned for linearly dependent input points. This condition - is caught via a :class:`ZeroDivisionError`, since the use of a + is caught via a :exc:`ZeroDivisionError`, since the use of a discrete logarithm test for linear dependence is much too slow for large `n`. @@ -1933,21 +1928,21 @@ def tate_pairing(self, Q, n, k, q=None): INPUT: - - ``P=self`` -- Elliptic curve point having order n + - ``P=self`` -- elliptic curve point having order `n` - - ``Q`` -- Elliptic curve point on same curve as P (can be any order) + - ``Q`` -- elliptic curve point on same curve as `P` (can be any order) - - ``n`` -- positive integer: order of P + - ``n`` -- positive integer; order of `P` - - ``k`` -- positive integer: embedding degree + - ``k`` -- positive integer; embedding degree - - ``q`` -- positive integer: size of base field (the "big" + - ``q`` -- positive integer; size of base field (the "big" field is `GF(q^k)`. `q` needs to be set only if its value cannot be deduced.) OUTPUT: - An `n`'th root of unity in the base field ``self.curve().base_field()`` + An `n`-th root of unity in the base field ``self.curve().base_field()``. EXAMPLES: @@ -2125,18 +2120,18 @@ def ate_pairing(self, Q, n, k, t, q=None): INPUT: - - `P` (``=self``) -- a point of order `n`, in `ker(\pi-1)`, where - `\pi` is the `q`-Frobenius map (e.g., `P` is `q`-rational). + - ``P`` (``=self``) -- a point of order `n`, in `ker(\pi-1)`, where + `\pi` is the `q`-Frobenius map (e.g., `P` is `q`-rational) - ``Q`` -- a point of order `n` in `ker(\pi-q)` - - ``n`` -- the order of `P` and `Q`. + - ``n`` -- the order of `P` and `Q` - - ``k`` -- the embedding degree. + - ``k`` -- the embedding degree - - ``t`` -- the trace of Frobenius of the curve over `GF(q)`. + - ``t`` -- the trace of Frobenius of the curve over `GF(q)` - - ``q`` -- (default: None) the size of base field (the "big" + - ``q`` -- (default: ``None``) the size of base field (the "big" field is `GF(q^k)`). `q` needs to be set only if its value cannot be deduced. @@ -2533,7 +2528,7 @@ def has_finite_order(self): def has_infinite_order(self): r""" - Return True iff this point has infinite order on the elliptic curve. + Return ``True`` iff this point has infinite order on the elliptic curve. EXAMPLES:: @@ -2556,7 +2551,7 @@ def has_infinite_order(self): def is_on_identity_component(self, embedding=None): r""" - Return True iff this point is on the identity component of + Return ``True`` iff this point is on the identity component of its curve with respect to a given (real or complex) embedding. INPUT: @@ -2570,8 +2565,8 @@ def is_on_identity_component(self, embedding=None): OUTPUT: - (bool) -- ``True`` iff the point is on the identity component of - the curve. (If the point is zero then the result is True.) + boolean; ``True`` iff the point is on the identity component of + the curve. (If the point is zero then the result is ``True``.) EXAMPLES: @@ -2634,7 +2629,7 @@ def is_on_identity_component(self, embedding=None): def has_good_reduction(self, P=None): r""" - Returns True iff this point has good reduction modulo a prime. + Return ``True`` iff this point has good reduction modulo a prime. INPUT: @@ -2643,9 +2638,9 @@ def has_good_reduction(self, P=None): OUTPUT: - (bool) If a prime `P` of the base field is specified, returns - True iff the point has good reduction at `P`; otherwise, - return true if the point has god reduction at all primes in + boolean; if a prime `P` of the base field is specified, returns + ``True`` iff the point has good reduction at `P`; otherwise, + return ``True`` if the point has god reduction at all primes in the support of the discriminant of this model. EXAMPLES:: @@ -2760,13 +2755,11 @@ def reduction(self, p): INPUT: - - ``self`` -- A point on an elliptic curve. + - ``self`` -- a point on an elliptic curve - ``p`` -- a prime number - OUTPUT: - - The point reduced to be a point on the elliptic curve modulo `p`. + OUTPUT: the point reduced to be a point on the elliptic curve modulo `p` EXAMPLES:: @@ -2812,25 +2805,23 @@ def height(self, precision=None, normalised=True, algorithm='pari'): INPUT: - - ``self`` -- a point on an elliptic curve over a number field - `K`. + - ``self`` -- a point on an elliptic curve over a number field `K` - - ``precision`` -- positive integer, or None (default). The - precision in bits of the result. If None, the default real + - ``precision`` -- positive integer, or ``None`` (default). The + precision in bits of the result. If ``None``, the default real precision is used. - - ``normalised`` -- boolean. If True (default), the height is - normalised to be invariant under extension of `K`. If False, - return this normalised height multiplied by the degree of - `K`. + - ``normalised`` -- boolean. If ``True`` (default), the height is + normalised to be invariant under extension of `K`. If ``False``, + return this normalised height multiplied by the degree of `K`. - - ``algorithm`` -- string: either ``'pari'`` (default) or ``'sage'``. + - ``algorithm`` -- string; either ``'pari'`` (default) or ``'sage'``. If ``'pari'`` and the base field is `\QQ`, use the PARI library function; otherwise use the Sage implementation. OUTPUT: - The rational number 0, or a non-negative real number. + The rational number 0, or a nonnegative real number. There are two normalisations used in the literature, one of which is double the other. We use the larger of the two, which @@ -3075,26 +3066,24 @@ def height(self, precision=None, normalised=True, algorithm='pari'): def archimedean_local_height(self, v=None, prec=None, weighted=False): """ - Compute the local height of self at the archimedean place `v`. + Compute the local height of ``self`` at the archimedean place `v`. INPUT: - - ``self`` -- a point on an elliptic curve over a number field - `K`. + - ``self`` -- a point on an elliptic curve over a number field `K` - ``v`` -- a real or complex embedding of K, or None (default). If `v` is a real or complex embedding, return the local - height of self at `v`. If `v` is None, return the total + height of ``self`` at `v`. If `v` is None, return the total archimedean contribution to the global height. - - ``prec`` -- integer, or None (default). The precision of the - computation. If None, the precision is deduced from `v`. + - ``prec`` -- integer or ``None`` (default). The precision of the + computation. If ``None``, the precision is deduced from `v` - - ``weighted`` -- boolean. If False (default), the height is - normalised to be invariant under extension of `K`. If True, + - ``weighted`` -- boolean. If ``False`` (default), the height is + normalised to be invariant under extension of `K`. If ``True``, return this normalised height multiplied by the local degree - if `v` is a single place, or by the degree of `K` if `v` is - None. + if `v` is a single place, or by the degree of `K` if `v` is ``None``. OUTPUT: @@ -3142,7 +3131,7 @@ def archimedean_local_height(self, v=None, prec=None, weighted=False): sage: P.archimedean_local_height() 1.98723816350773 - Local heights of torsion points can be non-zero (unlike the + Local heights of torsion points can be nonzero (unlike the global height):: sage: # needs sage.rings.number_field @@ -3314,22 +3303,20 @@ def non_archimedean_local_height(self, v=None, prec=None, INPUT: - - ``self`` -- a point on an elliptic curve over a number field - `K`. + - ``self`` -- a point on an elliptic curve over a number field `K` - ``v`` -- a non-archimedean place of `K`, or ``None`` (default). If `v` is a non-archimedean place, return the local height - of self at `v`. If `v` is ``None``, return the total + of ``self`` at `v`. If `v` is ``None``, return the total non-archimedean contribution to the global height. - - ``prec`` -- integer, or ``None`` (default). The precision of the - computation. If ``None``, the height is returned symbolically. + - ``prec`` -- integer; or ``None`` (default). The precision of the + computation. If ``None``, the height is returned symbolically - ``weighted`` -- boolean. If ``False`` (default), the height is normalised to be invariant under extension of `K`. If ``True``, return this normalised height multiplied by the local degree - if `v` is a single place, or by the degree of `K` if `v` is - None. + if `v` is a single place, or by the degree of `K` if `v` is ``None``. OUTPUT: @@ -3378,7 +3365,7 @@ def non_archimedean_local_height(self, v=None, prec=None, sage: P.non_archimedean_local_height() -log(3) - Local heights of torsion points can be non-zero (unlike the + Local heights of torsion points can be nonzero (unlike the global height):: sage: # needs sage.rings.number_field @@ -3509,12 +3496,12 @@ def elliptic_logarithm(self, embedding=None, precision=100, INPUT: - - ``embedding``: an embedding of the base field into `\RR` or `\CC` + - ``embedding`` -- an embedding of the base field into `\RR` or `\CC` - - ``precision``: a positive integer (default 100) setting the + - ``precision`` -- a positive integer (default: 100) setting the number of bits of precision for the computation - - ``algorithm``: either ``'pari'`` (default for real embeddings) + - ``algorithm`` -- either ``'pari'`` (default: for real embeddings) to use PARI's :pari:`ellpointtoz`, or ``'sage'`` for a native implementation. Ignored for complex embeddings. @@ -3713,12 +3700,14 @@ def elliptic_logarithm(self, embedding=None, precision=100, def padic_elliptic_logarithm(self, p, absprec=20): r""" - Computes the `p`-adic elliptic logarithm of this point. + Compute the `p`-adic elliptic logarithm of this point. INPUT: - - ``p`` -- integer: a prime ``absprec`` -- integer (default: 20): - the initial `p`-adic absolute precision of the computation + - ``p`` -- integer; a prime + + - ``absprec`` -- integer (default: 20); the initial `p`-adic absolute + precision of the computation OUTPUT: @@ -3854,7 +3843,7 @@ class EllipticCurvePoint_finite_field(EllipticCurvePoint_field): """ def _magma_init_(self, magma): """ - Return a string representation of self that ``MAGMA`` can + Return a string representation of ``self`` that ``MAGMA`` can use for input. EXAMPLES:: @@ -3926,7 +3915,7 @@ def log(self, base): In other words, return an integer `x` such that `xP = Q` where `P` is ``base`` and `Q` is this point. - A :class:`ValueError` is raised if there is no solution. + A :exc:`ValueError` is raised if there is no solution. ALGORITHM: @@ -3952,7 +3941,7 @@ def log(self, base): INPUT: - - ``base`` (point) -- another point on the same curve as ``self``. + - ``base`` -- another point on the same curve as ``self`` OUTPUT: @@ -4049,8 +4038,8 @@ def padic_elliptic_logarithm(self,Q, p): INPUT: - - ``Q`` (point) -- another point on the same curve as ``self``. - - ``p`` (integer) -- a prime equal to the order of the curve. + - ``Q`` -- point; another point on the same curve as ``self`` + - ``p`` -- integer; a prime equal to the order of the curve OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/ell_rational_field.py b/src/sage/schemes/elliptic_curves/ell_rational_field.py old mode 100644 new mode 100755 index 7bf1ac039d6..2d5da94a8bd --- a/src/sage/schemes/elliptic_curves/ell_rational_field.py +++ b/src/sage/schemes/elliptic_curves/ell_rational_field.py @@ -119,7 +119,7 @@ class EllipticCurve_rational_field(EllipticCurve_number_field): INPUT: - - ``ainvs`` -- a list or tuple `[a_1, a_2, a_3, a_4, a_6]` of + - ``ainvs`` -- list or tuple `[a_1, a_2, a_3, a_4, a_6]` of Weierstrass coefficients .. NOTE:: @@ -358,7 +358,7 @@ def is_p_integral(self, p): INPUT: - - ``p`` -- a prime integer + - ``p`` -- prime integer EXAMPLES:: @@ -408,7 +408,7 @@ def mwrank(self, options=''): INPUT: - - ``options`` (string) -- run-time options passed when starting mwrank. + - ``options`` -- string; run-time options passed when starting mwrank. The format is as follows (see below for examples of usage): - ``-v n`` (verbosity level) sets verbosity to n (default=1) @@ -421,9 +421,7 @@ def mwrank(self, options=''): - ``-d`` (skip_2nd_descent flag) if set, skips the second descent for curves with 2-torsion (default: not set) - ``-S n`` (sat_bd) upper bound on saturation primes (default=100, -1 for automatic) - OUTPUT: - - - (string) -- output of mwrank on this curve + OUTPUT: string; output of mwrank on this curve .. NOTE:: @@ -473,43 +471,42 @@ def mwrank(self, options=''): mwrank = Mwrank(options=options) return mwrank(list(self.a_invariants())) - def conductor(self, algorithm="pari"): + def conductor(self, algorithm='pari'): r""" Return the conductor of the elliptic curve. INPUT: - - ``algorithm`` -- str, (default: "pari") + - ``algorithm`` -- string (default: ``'pari'``) - - ``"pari"`` -- use the PARI C-library :pari:`ellglobalred` + - ``'pari'`` -- use the PARI C-library :pari:`ellglobalred` implementation of Tate's algorithm - - ``"mwrank"`` -- use Cremona's mwrank implementation + - ``'mwrank'`` -- use Cremona's mwrank implementation of Tate's algorithm; can be faster if the curve has integer coefficients (TODO: limited to small conductor until mwrank gets integer factorization) - - ``"gp"`` -- use the GP interpreter + - ``'gp'`` -- use the GP interpreter - - ``"generic"`` -- use the general number field - implementation + - ``'generic'`` -- use the general number field implementation - - ``"all"`` -- use all four implementations, verify + - ``'all'`` -- use all four implementations, verify that the results are the same (or raise an error), and output the common value EXAMPLES:: sage: E = EllipticCurve([1, -1, 1, -29372, -1932937]) - sage: E.conductor(algorithm="pari") + sage: E.conductor(algorithm='pari') 3006 - sage: E.conductor(algorithm="mwrank") + sage: E.conductor(algorithm='mwrank') 3006 - sage: E.conductor(algorithm="gp") + sage: E.conductor(algorithm='gp') 3006 - sage: E.conductor(algorithm="generic") + sage: E.conductor(algorithm='generic') 3006 - sage: E.conductor(algorithm="all") + sage: E.conductor(algorithm='all') 3006 .. NOTE:: @@ -521,7 +518,7 @@ def conductor(self, algorithm="pari"): TESTS:: - sage: E.conductor(algorithm="bogus") + sage: E.conductor(algorithm='bogus') Traceback (most recent call last): ... ValueError: algorithm 'bogus' is not known @@ -656,7 +653,7 @@ def database_attributes(self): the elliptic curve database. If there is no elliptic curve isomorphic to ``self`` in the - database, a :class:`LookupError` is raised. + database, a :exc:`LookupError` is raised. EXAMPLES:: @@ -688,9 +685,7 @@ def database_attributes(self): def database_curve(self): r""" Return the curve in the elliptic curve database isomorphic to this - curve, if possible. - - Otherwise this raises a :class:`LookupError` exception. + curve, if possible. Otherwise raise a :exc:`LookupError` exception. Since :issue:`11474`, this returns exactly the same curve as :meth:`minimal_model`; the only difference is the additional @@ -726,13 +721,12 @@ def Np(self, p): INPUT: - - ``p`` (int) -- a prime, not necessarily of good reduction + - ``p`` -- integer; a prime, not necessarily of good reduction OUTPUT: - (int) The number ofpoints on the reduction of `E` modulo `p` - (including the singular point when `p` is a prime of bad - reduction). + integer; the number of points on the reduction of `E` modulo `p` + (including the singular point when `p` is a prime of bad reduction). EXAMPLES:: @@ -761,7 +755,7 @@ def Np(self, p): #################################################################### def mwrank_curve(self, verbose=False): r""" - Construct an mwrank_EllipticCurve from this elliptic curve + Construct an mwrank_EllipticCurve from this elliptic curve. The resulting mwrank_EllipticCurve has available methods from John Cremona's eclib library. @@ -797,11 +791,10 @@ def two_descent(self, verbose=True, INPUT: - - ``verbose`` -- (default: ``True``) print what mwrank is - doing; if ``False``, **no output** is printed + - ``verbose`` -- boolean (default: ``True``); print what mwrank is + doing. If ``False``, **no output** is printed. - - ``selmer_only`` -- (default: ``False``) selmer_only - switch + - ``selmer_only`` -- boolean (default: ``False``); selmer_only switch - ``first_limit`` -- (default: 20) firstlim is bound on x+z second_limit- (default: 8) secondlim is bound on log max @@ -852,7 +845,7 @@ def aplist(self, n, python_ints=False): - ``n`` -- integer - - ``python_ints`` -- bool (default: ``False``); if ``True`` + - ``python_ints`` -- boolean (default: ``False``); if ``True`` return a list of Python ints instead of Sage integers OUTPUT: list of integers @@ -890,7 +883,7 @@ def anlist(self, n, python_ints=False): - ``n`` -- integer - - ``python_ints`` -- bool (default: ``False``); if ``True`` + - ``python_ints`` -- boolean (default: ``False``); if ``True`` return a list of Python ints instead of Sage integers OUTPUT: list of integers @@ -960,16 +953,14 @@ def anlist(self, n, python_ints=False): def q_expansion(self, prec): r""" - Return the `q`-expansion to precision prec of the newform + Return the `q`-expansion to precision ``prec`` of the newform attached to this elliptic curve. INPUT: - - ``prec`` -- an integer + - ``prec`` -- integer - OUTPUT: - - a power series (in the variable 'q') + OUTPUT: a power series (in the variable 'q') .. NOTE:: @@ -1057,11 +1048,9 @@ def modular_symbol_space(self, sign=1, base_ring=Q, bound=None): def abelian_variety(self): r""" - Return self as a modular abelian variety. + Return ``self`` as a modular abelian variety. - OUTPUT: - - - a modular abelian variety + OUTPUT: a modular abelian variety EXAMPLES:: @@ -1106,31 +1095,29 @@ def modular_symbol(self, sign=+1, normalize=None, implementation='eclib', nap=0) INPUT: - - ``sign`` -- +1 (default) or -1. - - - ``normalize`` -- (default: ``None``); either 'L_ratio', 'period', - or 'none'; ignored unless ``implementation`` is 'sage'. - For 'L_ratio', the modular symbol tries to normalize - correctly as explained below by comparing it to ``L_ratio`` - for the curve and some small twists. The normalization - 'period' uses the ``integral_period_map`` for modular - symbols which is known to be equal to the desired - normalization, up to the sign and a possible power of 2. - With normalization 'none', the modular symbol is almost - certainly not correctly normalized, i.e. all values will be + - ``sign`` -- +1 (default) or -1 + + - ``normalize`` -- (default: ``None``) either ``'L_ratio'``, + ``'period'``, or ``'none'``; ignored unless ``implementation`` is + ``'sage'``. For ``'L_ratio'``, the modular symbol tries to normalize + correctly as explained below by comparing it to ``L_ratio`` for the + curve and some small twists. The normalization ``'period'`` uses the + ``integral_period_map`` for modular symbols which is known to be + equal to the desired normalization, up to the sign and a possible + power of 2. With normalization ``'none'``, the modular symbol is + almost certainly not correctly normalized, i.e. all values will be a fixed scalar multiple of what they should be. - - ``implementation`` -- either 'eclib' (default), 'sage' or - 'num'. Here, 'eclib' uses Cremona's ``C++`` implementation - in the ``eclib`` library, 'sage' uses an implementation - within Sage which is often quite a bit slower, and 'num' - uses Wuthrich's implementation of numerical modular - symbols. + - ``implementation`` -- either ``'eclib'`` (default), ``'sage'`` or + ``'num'``. Here, ``'eclib'`` uses Cremona's ``C++`` implementation + in the ``eclib`` library, ``'sage'`` uses an implementation + within Sage which is often quite a bit slower, and ``'num'`` + uses Wuthrich's implementation of numerical modular symbols. - - ``nap`` -- (int, default 0); ignored unless implementation is - 'eclib'. The number of ap of E to use in determining the + - ``nap`` -- integer (default: 0); ignored unless implementation is + ``'eclib'``. The number of ap of E to use in determining the normalisation of the modular symbols. If 0 (the default), - then the value of 100*E.conductor().isqrt() is used. Using + then the value of ``100*E.conductor().isqrt()`` is used. Using too small a value can lead to incorrect normalisation. DEFINITION: @@ -1157,7 +1144,7 @@ def modular_symbol(self, sign=+1, normalize=None, implementation='eclib', nap=0) ALGORITHM: - For the implementations 'sage' and 'eclib', the used + For the implementations ``'sage'`` and ``'eclib'``, the used algorithm starts by finding the space of modular symbols within the full space of all modular symbols of that level. This initial step will take a very long time if the @@ -1165,7 +1152,7 @@ def modular_symbol(self, sign=+1, normalize=None, implementation='eclib', nap=0) conductors). Once the space is determined, each evaluation is very fast (logarithmic in the denominator of `r`). - The implementation 'num' uses a different algorithm. It + The implementation ``'num'`` uses a different algorithm. It uses numerical integration along paths in the upper half plane. The bounds are rigorously proved so that the outcome is known to be correct. The initial step costs no time, @@ -1191,7 +1178,7 @@ def modular_symbol(self, sign=+1, normalize=None, implementation='eclib', nap=0) :: sage: E = EllipticCurve('121b1') - sage: M = E.modular_symbol(implementation="sage") + sage: M = E.modular_symbol(implementation='sage') Warning : Could not normalize the modular symbols, maybe all further results will be multiplied by -1 and a power of 2 sage: M(1/7) @@ -1203,7 +1190,7 @@ def modular_symbol(self, sign=+1, normalize=None, implementation='eclib', nap=0) sage: E = EllipticCurve([999,997]) sage: E.conductor() 16059400956 - sage: m = E.modular_symbol(implementation="num") + sage: m = E.modular_symbol(implementation='num') sage: m(0) # long time 16 @@ -1313,11 +1300,9 @@ def modular_symbol_numerical(self, sign=1, prec=20): - ``sign`` -- either +1 (default) or -1 - - ``prec`` -- an integer (default 20) + - ``prec`` -- integer (default: 20) - OUTPUT: - - - a real number + OUTPUT: a real number ALGORITHM: @@ -1431,27 +1416,27 @@ def q_eigenform(self, prec): """ return self.q_expansion(prec) - def analytic_rank(self, algorithm="pari", leading_coefficient=False): + def analytic_rank(self, algorithm='pari', leading_coefficient=False): r""" Return an integer that is *probably* the analytic rank of this elliptic curve. INPUT: - - ``algorithm`` -- (default: 'pari'), String + - ``algorithm`` -- string (default: ``'pari'``): - - ``'pari'`` -- use the PARI library function. + - ``'pari'`` -- use the PARI library function - ``'sympow'`` -- use Watkins's program sympow - - ``'rubinstein'`` -- use Rubinstein's L-function C++ program lcalc. + - ``'rubinstein'`` -- use Rubinstein's `L`-function C++ program lcalc - ``'magma'`` -- use MAGMA - - ``'zero_sum'`` -- Use the rank bounding zero sum method implemented + - ``'zero_sum'`` -- use the rank bounding zero sum method implemented in :meth:`analytic_rank_upper_bound` - ``'all'`` -- compute with PARI, sympow and lcalc, check that - the answers agree, and return the common answer. + the answers agree, and return the common answer - - ``leading_coefficient`` -- (default: ``False``) Boolean; if set to - True, return a tuple `(rank, lead)` where `lead` is the value of - the first non-zero derivative of the L-function of the elliptic + - ``leading_coefficient`` -- boolean (default: ``False``); if set to + ``True``, return a tuple ``(rank, lead)`` where ``lead`` is the value + of the first nonzero derivative of the `L`-function of the elliptic curve. Only implemented for ``algorithm='pari'``. .. NOTE:: @@ -1494,7 +1479,7 @@ def analytic_rank(self, algorithm="pari", leading_coefficient=False): With the optional parameter leading_coefficient set to ``True``, a tuple of both the analytic rank and the leading term of the - L-series at `s = 1` is returned. This only works for + `L`-series at `s = 1` is returned. This only works for ``algorithm=='pari'``:: sage: EllipticCurve([0,-1,1,-10,-20]).analytic_rank(leading_coefficient=True) @@ -1511,7 +1496,7 @@ def analytic_rank(self, algorithm="pari", leading_coefficient=False): TESTS: When the input is horrendous, some of the algorithms just bomb - out with a :class:`RuntimeError`:: + out with a :exc:`RuntimeError`:: sage: EllipticCurve([1234567,89101112]).analytic_rank(algorithm='rubinstein') Traceback (most recent call last): @@ -1568,11 +1553,11 @@ def analytic_rank_upper_bound(self, max_Delta=None, adaptive=True, N=None, - root_number="compute", + root_number='compute', bad_primes=None, ncpus=None): r""" - Return an upper bound for the analytic rank of self, conditional on + Return an upper bound for the analytic rank of ``self``, conditional on the Generalized Riemann Hypothesis, via computing the zero sum `\sum_{\gamma} f(\Delta\gamma),` where `\gamma` ranges over the imaginary parts of the zeros of `L(E,s)` @@ -1585,18 +1570,18 @@ def analytic_rank_upper_bound(self, INPUT: - - ``max_Delta`` -- (default: ``None``) If not ``None``, a positive real value - specifying the maximum Delta value used in the zero sum; larger + - ``max_Delta`` -- (default: ``None``) if not ``None``, a positive real + value specifying the maximum Delta value used in the zero sum; larger values of Delta yield better bounds - but runtime is exponential in Delta. If left as ``None``, Delta is set to `\min\{\frac{1}{\pi}(\log(N+1000)/2-\log(2\pi)-\eta), 2.5\}`, - where `N` is the conductor of the curve attached to self, and `\eta` + where `N` is the conductor of the curve attached to ``self``, and `\eta` is the Euler-Mascheroni constant `= 0.5772...`; the crossover point is at conductor around `8.3 \cdot 10^8`. For the former value, empirical results show that for about 99.7% of all curves the returned value is the actual analytic rank. - - ``adaptive`` -- (default: ``True``) boolean + - ``adaptive`` -- boolean (default: ``True``): - ``True`` -- the computation is first run with small and then successively larger `\Delta` values up to max_Delta. If at any @@ -1604,30 +1589,30 @@ def analytic_rank_upper_bound(self, or True), the computation halts and that value is returned; otherwise the minimum of the computed bounds is returned. - ``False`` -- the computation is run a single time with `\Delta` - equal to ``max_Delta``, and the resulting bound returned. + equal to ``max_Delta``, and the resulting bound returned - - ``N`` -- (default: ``None``) If not ``None``, a positive integer equal + - ``N`` -- (default: ``None``) if not ``None``, a positive integer equal to the conductor of ``self``. This is passable so that rank estimation can be done for curves whose (large) conductor has been precomputed. - - ``root_number`` -- (default: "compute") string or integer + - ``root_number`` -- (default: ``'compute'``) string or integer: - - ``"compute"`` -- the root number of self is computed and used to + - ``'compute'`` -- the root number of ``self`` is computed and used to (possibly) lower the analytic rank estimate by 1. - - ``"ignore"`` -- the above step is omitted + - ``'ignore'`` -- the above step is omitted - ``1`` -- this value is assumed to be the root number of - self. This is passable so that rank estimation can be done for + ``self``. This is passable so that rank estimation can be done for curves whose root number has been precomputed. - ``-1`` -- this value is assumed to be the root number of - self. This is passable so that rank estimation can be done for + ``self``. This is passable so that rank estimation can be done for curves whose root number has been precomputed. - - ``bad_primes`` -- (default: ``None``) If not ``None``, a list of the primes - of bad reduction for the curve attached to self. This is passable + - ``bad_primes`` -- (default: ``None``) if not ``None``, a list of the primes + of bad reduction for the curve attached to ``self``. This is passable so that rank estimation can be done for curves of large conductor whose bad primes have been precomputed. - - ``ncpus`` -- (default: ``None``) If not ``None``, a positive integer + - ``ncpus`` -- (default: ``None``) if not ``None``, a positive integer defining the maximum number of CPUs to be used for the computation. If left as None, the maximum available number of CPUs will be used. Note: Due to parallelization overhead, multiple processors will @@ -1648,8 +1633,8 @@ def analytic_rank_upper_bound(self, OUTPUT: - A non-negative integer greater than or equal to the analytic rank of - self. + A nonnegative integer greater than or equal to the analytic rank of + ``self``. .. NOTE:: @@ -1689,7 +1674,7 @@ def analytic_rank_upper_bound(self, ....: E = elliptic_curves.rank(r)[0] ....: print((r, E.analytic_rank_upper_bound(max_Delta=1, ....: adaptive=False, - ....: root_number="ignore"))) + ....: root_number='ignore'))) (0, 0) (1, 1) (2, 2) @@ -1708,9 +1693,9 @@ def analytic_rank_upper_bound(self, sage: E = EllipticCurve("974b1") sage: r = E.rank(); r 0 - sage: E.analytic_rank_upper_bound(max_Delta=1, root_number="ignore") + sage: E.analytic_rank_upper_bound(max_Delta=1, root_number='ignore') 1 - sage: E.analytic_rank_upper_bound(max_Delta=1.3, root_number="ignore") + sage: E.analytic_rank_upper_bound(max_Delta=1.3, root_number='ignore') 0 Knowing the root number of `E` allows us to use smaller Delta values @@ -1718,7 +1703,7 @@ def analytic_rank_upper_bound(self, :: - sage: E.analytic_rank_upper_bound(max_Delta=0.6, root_number="compute") + sage: E.analytic_rank_upper_bound(max_Delta=0.6, root_number='compute') 0 There are a small number of curves which have pathologically low-lying @@ -1803,14 +1788,14 @@ def simon_two_descent(self, verbose=0, lim1=5, lim3=50, limtriv=3, and large prime numbers. Use probabilistic tests for large primes. If 0, don't any probabilistic tests. - - ``known_points`` -- (default: None) list of known points on + - ``known_points`` -- (default: ``None``) list of known points on the curve OUTPUT: a triple ``(lower, upper, list)`` consisting of - - ``lower`` (integer) -- lower bound on the rank + - ``lower`` -- integer; lower bound on the rank - - ``upper`` (integer) -- upper bound on the rank + - ``upper`` -- integer; upper bound on the rank - ``list`` -- list of points of infinite order in `E(\QQ)` @@ -2008,7 +1993,7 @@ def rank(self, use_database=True, verbose=False, - ``use_database`` -- boolean (default: ``True``); if ``True``, try to look up the rank in the Cremona database - - ``verbose`` -- (default: ``False``) if specified changes + - ``verbose`` -- boolean (default: ``False``); if specified changes the verbosity of mwrank computations - ``algorithm`` -- (default: ``'mwrank_lib'``) one of: @@ -2019,10 +2004,10 @@ def rank(self, use_database=True, verbose=False, - ``'pari'`` -- call ellrank in pari - - ``only_use_mwrank`` -- (default: ``True``) if ``False`` try + - ``only_use_mwrank`` -- boolean (default: ``True``); if ``False`` try using analytic rank methods first - - ``proof`` -- bool (default: ``None``, see + - ``proof`` -- boolean (default: ``None``, see ``proof.elliptic_curve`` or ``sage.structure.proof``); note that results obtained from databases are considered ``proof=True`` @@ -2034,7 +2019,7 @@ def rank(self, use_database=True, verbose=False, OUTPUT: the rank of the elliptic curve as :class:`Integer` - IMPLEMENTATION: Uses L-functions, mwrank, pari, and databases. + IMPLEMENTATION: uses `L`-functions, mwrank, pari, and databases EXAMPLES:: @@ -2050,7 +2035,7 @@ def rank(self, use_database=True, verbose=False, 4 sage: EllipticCurve([0, 0, 1, -79, 342]).rank(proof=False) 5 - sage: EllipticCurve([0, 0, 1, -79, 342]).rank(algorithm="pari") + sage: EllipticCurve([0, 0, 1, -79, 342]).rank(algorithm='pari') 5 Examples with denominators in defining equations:: @@ -2072,12 +2057,12 @@ def rank(self, use_database=True, verbose=False, Traceback (most recent call last): ... RuntimeError: rank not provably correct (lower bound: 0) - sage: EllipticCurve([1,0,0,0,37455]).rank(algorithm="pari") + sage: EllipticCurve([1,0,0,0,37455]).rank(algorithm='pari') 0 TESTS:: - sage: EllipticCurve([1,10000]).rank(algorithm="garbage") + sage: EllipticCurve([1,10000]).rank(algorithm='garbage') Traceback (most recent call last): ... ValueError: unknown algorithm 'garbage' @@ -2085,7 +2070,7 @@ def rank(self, use_database=True, verbose=False, An example to check if the points are saturated:: sage: E = EllipticCurve([0,0, 1, -7, 6]) - sage: E.gens(use_database=False, algorithm="pari") # random + sage: E.gens(use_database=False, algorithm='pari') # random [(2 : 0 : 1), (-1 : 3 : 1), (11 : 35 : 1)] sage: E.saturation(_)[1] 1 @@ -2109,7 +2094,7 @@ def rank(self, use_database=True, verbose=False, determined using pari only:: sage: E =EllipticCurve([-113^2,0]) - sage: E.rank(use_database=False, verbose=False, algorithm="pari") + sage: E.rank(use_database=False, verbose=False, algorithm='pari') Traceback (most recent call last): ... RuntimeError: rank not provably correct (lower bound: 0, upper bound:2). Hint: increase pari_effort. @@ -2238,15 +2223,14 @@ def rank(self, use_database=True, verbose=False, def gens(self, proof=None, **kwds): r""" - Return generators for the Mordell-Weil group `E(Q)` *modulo* - torsion. + Return generators for the Mordell-Weil group `E(Q)` *modulo* torsion. INPUT: - - ``proof`` -- bool or None (default None), see + - ``proof`` -- boolean or ``None`` (default: ``None``), see ``proof.elliptic_curve`` or ``sage.structure.proof`` - - ``verbose`` -- (default: None), if specified changes the + - ``verbose`` -- (default: ``None``) if specified changes the verbosity of mwrank computations - ``rank1_search`` -- (default: 10), if the curve has analytic @@ -2254,18 +2238,18 @@ def gens(self, proof=None, **kwds): this logarithmic height. If this fails, the usual mwrank procedure is called. - - algorithm -- one of the following: + - ``algorithm`` -- one of the following: - - ``'mwrank_shell'`` (default) -- call mwrank shell command + - ``'mwrank_shell'`` -- default; call mwrank shell command - ``'mwrank_lib'`` -- call mwrank C library - ``'pari'`` -- use ellrank in pari - - ``only_use_mwrank`` -- bool (default: ``True``) if False, first + - ``only_use_mwrank`` -- boolean (default: ``True``); if ``False``, first attempts to use more naive, natively implemented methods - - ``use_database`` -- bool (default: ``True``) if True, attempts to + - ``use_database`` -- boolean (default: ``True``); if ``True``, attempts to find curve and gens in the (optional) database - ``descent_second_limit`` -- (default: 12) used in 2-descent @@ -2299,10 +2283,10 @@ def gens(self, proof=None, **kwds): sage: E = EllipticCurve('389a') sage: E.gens() # random output [(-1 : 1 : 1), (0 : 0 : 1)] - sage: E.gens(algorithm="pari") # random output + sage: E.gens(algorithm='pari') # random output [(5/4 : 5/8 : 1), (0 : 0 : 1)] sage: E = EllipticCurve([0,2429469980725060,0,275130703388172136833647756388,0]) - sage: len(E.gens(algorithm="pari")) # not tested (takes too long) + sage: len(E.gens(algorithm='pari')) # not tested (takes too long) 14 A non-integral example:: @@ -2319,7 +2303,7 @@ def gens(self, proof=None, **kwds): over Rational Field sage: E1.gens() # random (if database not used) [(-400 : 8000 : 1), (0 : -8000 : 1)] - sage: E1.gens(algorithm="pari") #random + sage: E1.gens(algorithm='pari') #random [(-400 : 8000 : 1), (0 : -8000 : 1)] TESTS:: @@ -2329,15 +2313,14 @@ def gens(self, proof=None, **kwds): 2 sage: E.saturation(E.gens())[1] 1 - sage: len(E.gens(algorithm="pari")) + sage: len(E.gens(algorithm='pari')) 2 - sage: E.saturation(E.gens(algorithm="pari"))[1] + sage: E.saturation(E.gens(algorithm='pari'))[1] 1 sage: E = EllipticCurve([-3/8,-2/3]) sage: P = E.lift_x(10/9) sage: set(E.gens()) <= set([P,-P]) True - """ if proof is None: from sage.structure.proof.proof import get_flag @@ -2390,29 +2373,28 @@ def _compute_gens(self, proof, True sage: E = EllipticCurve([-127^2,0]) - sage: E.gens(use_database=False, algorithm="pari",pari_effort=4) # random + sage: E.gens(use_database=False, algorithm='pari',pari_effort=4) # random [(611429153205013185025/9492121848205441 : 15118836457596902442737698070880/924793900700594415341761 : 1)] TESTS:: sage: P = E.lift_x(611429153205013185025/9492121848205441) - sage: set(E.gens(use_database=False, algorithm="pari",pari_effort=4)) <= set([P+T for T + sage: set(E.gens(use_database=False, algorithm='pari',pari_effort=4)) <= set([P+T for T ....: in E.torsion_points()] + [-P+T for T in E.torsion_points()]) True sage: E = EllipticCurve([-157^2,0]) - sage: E.gens(use_database=False, algorithm="pari") + sage: E.gens(use_database=False, algorithm='pari') Traceback (most recent call last): ... RuntimeError: generators could not be determined. So far we found []. Hint: increase pari_effort. - sage: ge = E.gens(use_database=False, algorithm="pari",pari_effort=10) + sage: ge = E.gens(use_database=False, algorithm='pari',pari_effort=10) sage: ge #random [(-166136231668185267540804/2825630694251145858025 : 167661624456834335404812111469782006/150201095200135518108761470235125 : 1)] sage: P = E.lift_x(-166136231668185267540804/2825630694251145858025) - sage: set(E.gens(use_database=False, algorithm="pari",pari_effort=4)) <= set([P+T for T + sage: set(E.gens(use_database=False, algorithm='pari',pari_effort=4)) <= set([P+T for T ....: in E.torsion_points()] + [-P+T for T in E.torsion_points()]) True - """ # If the optional extended database is installed and an # isomorphic curve is in the database then its gens will be @@ -2607,11 +2589,11 @@ def regulator(self, proof=None, precision=53, **kwds): INPUT: - - ``proof`` -- bool or ``None`` (default: ``None``, see + - ``proof`` -- boolean or ``None`` (default: ``None``, see proof.[tab] or sage.structure.proof). Note that results from - databases are considered proof = True + databases are considered ``proof = True``. - - ``precision`` -- (int, default 53): the precision in bits of + - ``precision`` -- integer (default: 53); the precision in bits of the result - ``**kwds`` -- passed to :meth:`gens()` method @@ -2668,19 +2650,19 @@ def saturation(self, points, verbose=False, max_prime=-1, min_prime=2): INPUT: - - ``points (list)`` -- list of points on `E` + - ``points`` -- list of points on `E` - - ``verbose (bool)`` -- (default: ``False``) if ``True``, give + - ``verbose`` -- boolean (default: ``False``); if ``True``, give verbose output - - ``max_prime`` -- int (default: `-1`); if `-1` (the default), an + - ``max_prime`` -- integer (default: `-1`); if `-1`, an upper bound is computed for the primes at which the subgroup may not be saturated, and saturation is performed for all primes up to this bound; otherwise, the bound used is the minimum of ``max_prime`` and the computed bound - - ``min_prime (int)`` -- (default: `2`) only do `p`-saturation - at primes `p` greater than or equal to this + - ``min_prime`` -- integer (default: `2`); only do `p`-saturation + at primes `p` greater than or equal to this .. NOTE:: @@ -2692,14 +2674,14 @@ def saturation(self, points, verbose=False, max_prime=-1, min_prime=2): OUTPUT: - - ``saturation (list)`` -- points that form a basis for + - ``saturation`` -- list; points that form a basis for the saturation - - ``index (int)`` -- the index of the group generated + - ``index`` -- integer; the index of the group generated by points in their saturation - - ``regulator (real with default precision)`` -- - regulator of saturated points. + - ``regulator`` -- real with default precision; regulator of saturated + points ALGORITHM: @@ -2775,7 +2757,6 @@ def saturation(self, points, verbose=False, max_prime=-1, min_prime=2): sage: Q = E([-82,54]) sage: E.saturation([2*Q], max_prime=10) ([(-82 : 54 : 1)], 2, 2.36570863272098) - """ if not isinstance(points, list): raise TypeError("points (=%s) must be a list." % points) @@ -3004,14 +2985,13 @@ def point_search(self, height_limit, verbose=False, rank_bound=None): points = self.saturation(points, verbose=verbose)[0] return points - def selmer_rank(self, algorithm="pari"): + def selmer_rank(self, algorithm='pari'): r""" Return the rank of the 2-Selmer group of the curve. INPUT: - - ``algorithm`` -- (default:``'pari'``) - either ``'pari'`` or ``'mwrank'`` + - ``algorithm`` -- either ``'pari'`` (default) or ``'mwrank'`` EXAMPLES: This example has rank 1, Sha[2] of order 4 and @@ -3020,7 +3000,7 @@ def selmer_rank(self, algorithm="pari"): sage: E = EllipticCurve([1, 1, 1, 508, -2551]) sage: E.selmer_rank() 4 - sage: E.selmer_rank(algorithm="mwrank") + sage: E.selmer_rank(algorithm='mwrank') 4 The following is the curve 960d1, which has rank 0, but @@ -3029,7 +3009,7 @@ def selmer_rank(self, algorithm="pari"): sage: E = EllipticCurve([0, -1, 0, -900, -10098]) sage: E.selmer_rank() 3 - sage: E.selmer_rank(algorithm="mwrank") + sage: E.selmer_rank(algorithm='mwrank') 3 This curve has rank 1, and 4 elements in Sha[2]. @@ -3063,15 +3043,14 @@ def selmer_rank(self, algorithm="pari"): else: raise ValueError(f"unknown {algorithm=}") - def rank_bound(self, algorithm="pari"): + def rank_bound(self, algorithm='pari'): r""" Return the upper bound on the rank of the curve, computed using a 2-descent. INPUT: - - ``algorithm`` -- (default:``'pari'``) - either ``'pari'`` or ``'mwrank'`` + - ``algorithm`` -- either ``'pari'`` (default) or ``'mwrank'`` In many cases, this is the actual rank of the curve. @@ -3090,7 +3069,7 @@ def rank_bound(self, algorithm="pari"): sage: E = EllipticCurve([0, -1, 1, -929, -10595]) sage: E.rank_bound() 0 - sage: E.rank_bound(algorithm="mwrank") + sage: E.rank_bound(algorithm='mwrank') 2 In the following last example, both algorithm only determine a rank bound larger than the actual rank:: @@ -3098,7 +3077,7 @@ def rank_bound(self, algorithm="pari"): sage: E = EllipticCurve([1, 1, 1, -896670, -327184905]) sage: E.rank_bound() 2 - sage: E.rank_bound(algorithm="mwrank") + sage: E.rank_bound(algorithm='mwrank') 2 sage: E.rank(only_use_mwrank=False) # uses L-function 0 @@ -3193,7 +3172,7 @@ def is_minimal(self): def is_p_minimal(self, p): r""" - Tests if curve is ``p``-minimal at a given prime ``p``. + Test if curve is `p`-minimal at a given prime `p`. INPUT: @@ -3201,8 +3180,8 @@ def is_p_minimal(self, p): OUTPUT: - - ``True`` -- if curve is p-minimal - - ``False`` -- if curve is not p-minimal + - ``True`` -- if curve is `p`-minimal + - ``False`` -- if curve is not `p`-minimal EXAMPLES:: @@ -3410,7 +3389,7 @@ def has_good_reduction_outside_S(self, S=None): INPUT: - - ``S`` -- list of primes (default: ``[]``). + - ``S`` -- list of primes (default: ``[]``) .. NOTE:: @@ -3545,10 +3524,10 @@ def elliptic_exponential(self, z, embedding=None): def lseries(self): r""" - Return the L-series of this elliptic curve. + Return the `L`-series of this elliptic curve. Further documentation is available for the functions which apply to - the L-series. + the `L`-series. EXAMPLES:: @@ -3565,16 +3544,16 @@ def lseries(self): def lseries_gross_zagier(self, A): r""" - Return the Gross-Zagier L-series attached to ``self`` + Return the Gross-Zagier `L`-series attached to ``self`` and an ideal class `A`. INPUT: - ``A`` -- an ideal class in an imaginary quadratic number field `K` - This L-series `L(E,A,s)` is defined as the product of a shifted L-function of the + This `L`-series `L(E,A,s)` is defined as the product of a shifted `L`-function of the quadratic character associated to `K` and the Dirichlet series whose `n`-th - coefficient is the product of the `n`-th factor of the L-series of `E` and + coefficient is the product of the `n`-th factor of the `L`-series of `E` and the number of integral ideal in `A` of norm `n`. For any character `\chi` on the class group of `K`, one gets `L_K(E,\chi,s) = \sum_{A} \chi(A) L(E,A,s)` where `A` runs through the class group of `K`. @@ -3646,8 +3625,8 @@ def _F(n, t): def is_local_integral_model(self, *p): r""" - Tests if ``self`` is integral at the prime ``p``, or at all the - primes if ``p`` is a list or tuple of primes. + Test if ``self`` is integral at the prime `p`, or at all the + primes if `p` is a list or tuple of primes. EXAMPLES:: @@ -3669,7 +3648,7 @@ def is_local_integral_model(self, *p): def local_integral_model(self, p): r""" - Return a model of self which is integral at the prime ``p``. + Return a model of ``self`` which is integral at the prime `p`. EXAMPLES:: @@ -3745,7 +3724,7 @@ def integral_short_weierstrass_model(self): B /= Integer(p**(6 * e)) return constructor.EllipticCurve([A, B]) - def _generalized_congmod_numbers(self, M, invariant="both"): + def _generalized_congmod_numbers(self, M, invariant='both'): r""" Internal method to compute the generalized modular degree and congruence number at level `MN`, where `N` is the conductor of `E`. @@ -3759,16 +3738,16 @@ def _generalized_congmod_numbers(self, M, invariant="both"): INPUT: - - ``M`` -- non-negative integer; this function is only ever called on + - ``M`` -- nonnegative integer; this function is only ever called on `M > 1`, although the algorithm works fine for the case `M = 1` - - ``invariant`` -- string (default: ``"both"``); options are: + - ``invariant`` -- string (default: ``'both'``); options are: - - "both" -- both modular degree and congruence number at level `MN` are computed + - ``'both'`` -- both modular degree and congruence number at level `MN` are computed - - "moddeg" -- only modular degree is computed + - ``'moddeg'`` -- only modular degree is computed - - "congnum" -- only congruence number is computed + - ``'congnum'`` -- only congruence number is computed OUTPUT: @@ -3839,7 +3818,7 @@ def modular_degree(self, algorithm='sympow', M=1): INPUT: - - ``algorithm`` -- string: + - ``algorithm`` -- string; one of * ``'sympow'`` -- (default) use Mark Watkin's (newer) C program sympow @@ -3847,7 +3826,7 @@ def modular_degree(self, algorithm='sympow', M=1): * ``'magma'`` -- requires that MAGMA be installed (also implemented by Mark Watkins) - - ``M`` -- non-negative integer; the modular degree at level `MN` + - ``M`` -- nonnegative integer; the modular degree at level `MN` is returned (see above) .. NOTE:: @@ -4020,7 +3999,7 @@ def congruence_number(self, M=1): INPUT: - - ``M`` -- non-negative integer; congruence number is computed + - ``M`` -- nonnegative integer; congruence number is computed at level `MN`, where `N` is the conductor of ``self`` EXAMPLES:: @@ -4096,9 +4075,7 @@ def congruence_number(self, M=1): def cremona_label(self, space=False): r""" Return the Cremona label associated to (the minimal model) of this - curve, if it is known. - - If not, this raises a :class:`LookupError` exception. + curve, if it is known. If not, raise a :exc:`LookupError` exception. EXAMPLES:: @@ -4248,7 +4225,7 @@ def torsion_subgroup(self): r""" Return the torsion subgroup of this elliptic curve. - OUTPUT: The EllipticCurveTorsionSubgroup instance associated to + OUTPUT: the EllipticCurveTorsionSubgroup instance associated to this elliptic curve. .. NOTE:: @@ -4293,10 +4270,9 @@ def torsion_subgroup(self): def torsion_points(self): r""" - Return the torsion points of this elliptic curve as a sorted - list. + Return the torsion points of this elliptic curve as a sorted list. - OUTPUT: A list of all the torsion points on this elliptic curve. + OUTPUT: list of all the torsion points on this elliptic curve EXAMPLES:: @@ -4367,12 +4343,12 @@ def root_number(self, p=None): r""" Return the root number of this elliptic curve. - This is 1 if the order of vanishing of the L-function `L(E,s)` at 1 + This is 1 if the order of vanishing of the `L`-function `L(E,s)` at 1 is even, and -1 if it is odd. INPUT: - - `p` -- (optional) if given, return the local root number at ``p`` + - ``p`` -- (optional) if given, return the local root number at ``p`` EXAMPLES:: @@ -4448,7 +4424,7 @@ def cm_discriminant(self): Return the associated quadratic discriminant if this elliptic curve has Complex Multiplication over the algebraic closure. - A :class:`ValueError` is raised if the curve does not have CM (see the + A :exc:`ValueError` is raised if the curve does not have CM (see the function :meth:`has_cm()`). EXAMPLES:: @@ -4670,29 +4646,29 @@ def minimal_quadratic_twist(self): ########################################################## # Isogeny class ########################################################## - def isogeny_class(self, algorithm="sage", order=None): + def isogeny_class(self, algorithm='sage', order=None): r""" Return the `\QQ`-isogeny class of this elliptic curve. INPUT: - - ``algorithm`` -- string: one of the following: + - ``algorithm`` -- string; one of - - "database" -- use the Cremona database (only works if + - ``'database'`` -- use the Cremona database (only works if curve is isomorphic to a curve in the database) - - "sage" (default) -- use the native Sage implementation. + - ``'sage'`` (default) -- use the native Sage implementation - ``order`` -- ``None``, string, or list of curves (default: - ``None``); If not ``None`` then the curves in the class are + ``None``); if not ``None`` then the curves in the class are reordered after being computed. Note that if the order is ``None`` then the resulting order will depend on the algorithm. - - If ``order`` is "database" or "sage", then the reordering + - If ``order`` is ``'database'`` or ``'sage'``, then the reordering is so that the order of curves matches the order produced by that algorithm. - - If ``order`` is "lmfdb" then the curves are sorted + - If ``order`` is ``'lmfdb'`` then the curves are sorted lexicographically by a-invariants, in the LMFDB database. - If ``order`` is a list of curves, then the curves in the @@ -4715,7 +4691,7 @@ class are reordered to be isomorphic with the specified EXAMPLES:: - sage: isocls = EllipticCurve('37b').isogeny_class(order="lmfdb") + sage: isocls = EllipticCurve('37b').isogeny_class(order='lmfdb') sage: isocls Elliptic curve isogeny class 37b sage: isocls.curves @@ -4729,7 +4705,7 @@ class are reordered to be isomorphic with the specified :: - sage: isocls = EllipticCurve('37b').isogeny_class('database', order="lmfdb"); isocls.curves + sage: isocls = EllipticCurve('37b').isogeny_class('database', order='lmfdb'); isocls.curves (Elliptic Curve defined by y^2 + y = x^3 + x^2 - 1873*x - 31833 over Rational Field, Elliptic Curve defined by y^2 + y = x^3 + x^2 - 23*x - 50 over Rational Field, Elliptic Curve defined by y^2 + y = x^3 + x^2 - 3*x + 1 over Rational Field) @@ -4932,14 +4908,14 @@ def isogenies_prime_degree(self, l=None): def is_isogenous(self, other, proof=True, maxp=200): r""" - Return whether or not self is isogenous to other. + Return whether or not ``self`` is isogenous to other. INPUT: - ``other`` -- another elliptic curve - - ``proof`` -- (default: ``True``) if ``False``, the function will - return ``True`` whenever the two curves have the same + - ``proof`` -- boolean (default: ``True``); if ``False``, the function + will return ``True`` whenever the two curves have the same conductor and are isogenous modulo `p` for `p` up to ``maxp``; otherwise this test is followed by a rigorous test (which may be more time-consuming) @@ -4949,7 +4925,7 @@ def is_isogenous(self, other, proof=True, maxp=200): OUTPUT: - (bool) True if there is an isogeny from curve ``self`` to + boolean; ``True`` if there is an isogeny from curve ``self`` to curve ``other``. ALGORITHM: @@ -5247,7 +5223,7 @@ def manin_constant(self): that in each class there is at least one, more precisely the so-called strong Weil curve or `X_0(N)`-optimal curve, that has Manin constant `1`. - OUTPUT: An integer. + OUTPUT: integer This function only works if the curve is in the installed Cremona database. Sage includes by default a small database; @@ -5318,11 +5294,9 @@ def _shortest_paths(self): r""" Technical internal function that returns the list of isogenies curves and corresponding dictionary of shortest isogeny paths - from self to each other curve in the isogeny class. - - OUTPUT: + from ``self`` to each other curve in the isogeny class. - list, dict + OUTPUT: list, dictionary EXAMPLES:: @@ -5456,7 +5430,7 @@ def is_ordinary(self, p, ell=None): - ``p`` -- a prime - ``ell`` -- a prime (default: ``p``) - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -5481,7 +5455,7 @@ def is_good(self, p, check=True): - ``p`` -- a prime - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -5500,8 +5474,8 @@ def is_good(self, p, check=True): def is_supersingular(self, p, ell=None): r""" - Return ``True`` precisely when p is a prime of good reduction and the - mod-``p`` representation attached to this elliptic curve is + Return ``True`` precisely when `p` is a prime of good reduction and the + mod-`p` representation attached to this elliptic curve is supersingular at ell. INPUT: @@ -5509,7 +5483,7 @@ def is_supersingular(self, p, ell=None): - ``p`` -- a prime - ``ell`` -- a prime (default: ``p``) - OUTPUT: bool + OUTPUT: boolean EXAMPLES:: @@ -5601,13 +5575,13 @@ def eval_modular_form(self, points, order): INPUT: - - ``points`` -- a list of points in the upper half-plane + - ``points`` -- list of points in the upper half-plane - - ``order`` -- a nonnegative integer + - ``order`` -- nonnegative integer The ``order`` parameter is the number of terms used in the summation. - OUTPUT: A list of values for `s` in ``points`` + OUTPUT: list of values for `s` in ``points`` EXAMPLES:: @@ -5743,8 +5717,7 @@ def tate_curve(self, p): INPUT: - - `p` -- a prime where the curve has split multiplicative - reduction + - ``p`` -- a prime where the curve has split multiplicative reduction EXAMPLES:: @@ -5843,17 +5816,13 @@ def faltings_height(self, stable=False, prec=None): INPUT: - - ``stable`` -- boolean (default: ``False``); if ``True``, - return the *stable* Faltings height, otherwise the unstable - height + - ``stable`` -- boolean (default: ``False``); if ``True``, return the + *stable* Faltings height, otherwise the unstable height - - ``prec`` -- integer (default: ``None``); bit - precision of output; if ``None``, use standard - precision (53 bits) - - OUTPUT: + - ``prec`` -- integer (default: ``None``); bit precision of output; if + ``None``, use standard precision (53 bits) - (real) the Faltings height of this elliptic curve. + OUTPUT: real; the Faltings height of this elliptic curve .. NOTE:: @@ -5936,11 +5905,10 @@ def antilogarithm(self, z, max_denominator=None): OUTPUT: - - point on the curve: the rational point which is the - image of `z` under the Weierstrass parametrization, if it - exists and can be determined from `z` and the given value - of max_denominator (if any); otherwise a :class:`ValueError` exception - is raised. + A point on the curve: the rational point which is the image of `z` + under the Weierstrass parametrization, if it exists and can be + determined from `z` and the given value of max_denominator (if any); + otherwise a :exc:`ValueError` exception is raised. EXAMPLES:: @@ -5983,12 +5951,12 @@ def integral_x_coords_in_interval(self,xmin,xmax): INPUT: - - ``xmin``, ``xmax`` (integers) -- two integers + - ``xmin``, ``xmax`` -- two integers OUTPUT: - (set) The set of integers `x` with `xmin\le x\le xmax` which - are `x`-coordinates of rational points on the elliptic curve. + The set of integers `x` with `xmin\le x\le xmax` which are + `x`-coordinates of rational points on the elliptic curve. EXAMPLES:: @@ -6036,7 +6004,7 @@ def integral_points(self, mw_base='auto', both_signs=False, verbose=False): - ``verbose`` -- boolean (default: ``False``); if ``True``, some details of the computation are output - OUTPUT: A sorted list of all the integral points on `E` (up to sign + OUTPUT: a sorted list of all the integral points on `E` (up to sign unless ``both_signs`` is ``True``) .. NOTE:: @@ -6169,7 +6137,7 @@ def integral_points(self, mw_base='auto', both_signs=False, verbose=False): ############################## begin ################################ def point_preprocessing(free,tor): r""" - Transforms the mw_basis ``free`` into a `\ZZ`-basis for + Transform the mw_basis ``free`` into a `\ZZ`-basis for `E(\QQ)\cap E^0(`\RR)`. If there is a torsion point on the "egg" we add it to any of the gens on the egg; otherwise we replace the free generators with generators of a @@ -6436,8 +6404,8 @@ def S_integral_points(self, S, mw_base='auto', both_signs=False, verbose=False, details of the computation are output - ``proof`` -- boolean (default: ``True``); if ``True`` ALL - S-integral points will be returned. If False, the MW basis - will be computed with the proof=False flag, and also the + S-integral points will be returned. If ``False``, the MW basis + will be computed with the ``proof=False`` flag, and also the time-consuming final call to S_integral_x_coords_with_abs_bounded_by(abs_bound) is omitted. Use this only if the computation takes too long, @@ -6447,7 +6415,7 @@ def S_integral_points(self, S, mw_base='auto', both_signs=False, verbose=False, OUTPUT: A sorted list of all the S-integral points on E (up to sign - unless both_signs is True) + unless ``both_signs`` is ``True``). .. NOTE:: @@ -6896,7 +6864,7 @@ def S_integral_x_coords_with_abs_bounded_by(abs_bound): M = U.transpose()*M*U # NB "lambda" is a reserved word in Python! - lamda = min(M.charpoly(algorithm="hessenberg").roots(multiplicities=False)) + lamda = min(M.charpoly(algorithm='hessenberg').roots(multiplicities=False)) max_S = max(S) len_S += 1 #Counting infinity (always "included" in S) if verbose: @@ -7165,15 +7133,14 @@ def integral_points_with_bounded_mw_coeffs(E, mw_base, N, x_bound): INPUT: - ``E`` -- an elliptic curve - - ``mw_base`` -- a list of points on `E` (generators) - - ``N`` -- a positive integer (bound on coefficients) + - ``mw_base`` -- list of points on `E` (generators) + - ``N`` -- positive integer (bound on coefficients) - ``x_bound`` -- a positive real number (upper bound on size of x-coordinates) OUTPUT: - (list) list of integral points on `E` which are linear combinations - of the given points with coefficients bounded by `N` in absolute - value. + list of integral points on `E` which are linear combinations of the given + points with coefficients bounded by `N` in absolute value. TESTS: @@ -7302,13 +7269,13 @@ def elliptic_curve_congruence_graph(curves): INPUT: - - ``curves`` -- a list of elliptic curves + - ``curves`` -- list of elliptic curves OUTPUT: The graph with each curve as a vertex (labelled by its Cremona label) and an edge from `E` to `F` labelled `p` if and only if `E` is - congruent to `F` mod `p` + congruent to `F` mod `p`. EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_tate_curve.py b/src/sage/schemes/elliptic_curves/ell_tate_curve.py old mode 100644 new mode 100755 index 4dac4b08aed..7defaf1d50c --- a/src/sage/schemes/elliptic_curves/ell_tate_curve.py +++ b/src/sage/schemes/elliptic_curves/ell_tate_curve.py @@ -82,7 +82,7 @@ def __init__(self, E, p): - ``E`` -- an elliptic curve over the rational numbers - ``p`` -- a prime where `E` has multiplicative reduction, - i.e., such that `j(E)` has negative valuation. + i.e., such that `j(E)` has negative valuation EXAMPLES:: @@ -167,7 +167,7 @@ def parameter(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -209,7 +209,7 @@ def curve(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -244,7 +244,7 @@ def _Csquare(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -269,7 +269,7 @@ def E2(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -313,10 +313,10 @@ def parametrisation_onto_tate_curve(self, u, prec=None): INPUT: - - ``u`` -- a non-zero `p`-adic number. + - ``u`` -- a nonzero `p`-adic number - - ``prec`` -- the `p`-adic precision, default is the relative precision of ``u`` - otherwise 20. + - ``prec`` -- the `p`-adic precision; default is the relative precision + of ``u``, otherwise 20 EXAMPLES:: @@ -375,7 +375,7 @@ def L_invariant(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -406,7 +406,7 @@ def _isomorphism(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -443,7 +443,7 @@ def _inverse_isomorphism(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -466,9 +466,9 @@ def lift(self, P, prec=20): INPUT: - - ``P`` -- a point on the elliptic curve. + - ``P`` -- a point on the elliptic curve - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: @@ -522,10 +522,10 @@ def parametrisation_onto_original_curve(self, u, prec=None): INPUT: - - ``u`` -- a non-zero `p`-adic number. + - ``u`` -- a nonzero `p`-adic number - - ``prec`` -- the `p`-adic precision, default is the relative precision of ``u`` - otherwise 20. + - ``prec`` -- the `p`-adic precision; default is the relative precision + of ``u``, otherwise 20 EXAMPLES:: @@ -578,11 +578,9 @@ def padic_height(self, prec=20): INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) - OUTPUT: - - - A function that can be evaluated on rational points of `E`. + OUTPUT: a function that can be evaluated on rational points of `E` EXAMPLES:: @@ -635,11 +633,11 @@ def padic_regulator(self, prec=20): The `p`-adic Birch and Swinnerton-Dyer conjecture predicts that this value appears in the formula for the leading term of - the `p`-adic L-function. + the `p`-adic `L`-function. INPUT: - - ``prec`` -- the `p`-adic precision, default is 20. + - ``prec`` -- the `p`-adic precision (default: 20) EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/ell_torsion.py b/src/sage/schemes/elliptic_curves/ell_torsion.py old mode 100644 new mode 100755 index cc543b339a4..ade14590440 --- a/src/sage/schemes/elliptic_curves/ell_torsion.py +++ b/src/sage/schemes/elliptic_curves/ell_torsion.py @@ -137,11 +137,11 @@ class EllipticCurveTorsionSubgroup(groups.AdditiveAbelianGroupWrapper): """ def __init__(self, E): r""" - Initialization function for EllipticCurveTorsionSubgroup class + Initialization function for EllipticCurveTorsionSubgroup class. INPUT: - - ``E`` -- An elliptic curve defined over a number field (including `\QQ`) + - ``E`` -- an elliptic curve defined over a number field (including `\QQ`) EXAMPLES:: @@ -287,7 +287,7 @@ def torsion_bound(E, number_of_places=20): - ``E`` -- an elliptic curve over `\QQ` or a number field - - ``number_of_places`` (positive integer, default = 20) -- the + - ``number_of_places`` -- positive integer (default: 20); the number of places that will be used to find the bound OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/ell_wp.py b/src/sage/schemes/elliptic_curves/ell_wp.py old mode 100644 new mode 100755 index 8532ce08b74..a1a5c8fb5fe --- a/src/sage/schemes/elliptic_curves/ell_wp.py +++ b/src/sage/schemes/elliptic_curves/ell_wp.py @@ -64,9 +64,9 @@ def weierstrass_p(E, prec=20, algorithm=None): - ``prec`` -- precision - - ``algorithm`` -- string or ``None`` (default: ``None``): - a choice of algorithm among ``"pari"``, ``"fast"``, ``"quadratic"``; - or ``None`` to let this function determine the best algorithm to use. + - ``algorithm`` -- string or ``None`` (default: ``None``); + a choice of algorithm among ``'pari'``, ``'fast'``, ``'quadratic'``, + or ``None`` to let this function determine the best algorithm to use OUTPUT: @@ -110,7 +110,7 @@ def weierstrass_p(E, prec=20, algorithm=None): NotImplementedError: currently no algorithms for computing the Weierstrass p-function for that characteristic / precision pair is implemented. Lower the precision below char(k) - 2 - sage: E.weierstrass_p(prec=9, algorithm="quadratic") + sage: E.weierstrass_p(prec=9, algorithm='quadratic') Traceback (most recent call last): ... ValueError: for computing the Weierstrass p-function via the quadratic @@ -167,7 +167,7 @@ def weierstrass_p(E, prec=20, algorithm=None): def compute_wp_pari(E,prec): r""" - Computes the Weierstrass `\wp`-function with the ``ellwp`` function + Compute the Weierstrass `\wp`-function with the ``ellwp`` function from PARI. EXAMPLES:: @@ -206,7 +206,7 @@ def compute_wp_quadratic(k, A, B, prec): - ``k`` -- the field of definition of the curve - ``A`` -- and - ``B`` -- the coefficients of the elliptic curve - - ``prec`` -- the precision to which we compute the series. + - ``prec`` -- the precision to which we compute the series OUTPUT: @@ -253,7 +253,7 @@ def compute_wp_quadratic(k, A, B, prec): def compute_wp_fast(k, A, B, m): r""" - Computes the Weierstrass function of an elliptic curve defined by short Weierstrass model: + Compute the Weierstrass function of an elliptic curve defined by short Weierstrass model: `y^2 = x^3 + Ax + B`. It does this with as fast as polynomial of degree `m` can be multiplied together in the base ring, i.e. `O(M(n))` in the notation of [BMSS2006]_. @@ -264,11 +264,9 @@ def compute_wp_fast(k, A, B, m): - ``k`` -- the base field of the curve - ``A`` -- and - ``B`` -- as the coefficients of the short Weierstrass model `y^2 = x^3 +Ax +B`, and - - ``m`` -- the precision to which the function is computed to. + - ``m`` -- the precision to which the function is computed to - OUTPUT: - - the Weierstrass `\wp` function as a Laurent series to precision `m`. + OUTPUT: the Weierstrass `\wp` function as a Laurent series to precision `m` ALGORITHM: @@ -318,7 +316,7 @@ def compute_wp_fast(k, A, B, m): def solve_linear_differential_system(a, b, c, alpha): r""" - Solves a system of linear differential equations: `af' + bf = c` and `f'(0) = \alpha` + Solve a system of linear differential equations: `af' + bf = c` and `f'(0) = \alpha` where `a`, `b`, and `c` are power series in one variable and `\alpha` is a constant in the coefficient ring. ALGORITHM: diff --git a/src/sage/schemes/elliptic_curves/formal_group.py b/src/sage/schemes/elliptic_curves/formal_group.py old mode 100644 new mode 100755 index ae3dceb8555..3524c492a2f --- a/src/sage/schemes/elliptic_curves/formal_group.py +++ b/src/sage/schemes/elliptic_curves/formal_group.py @@ -118,7 +118,7 @@ def w(self, prec=20): .. WARNING:: - The resulting power series will have precision prec, but + The resulting power series will have precision ``prec``, but its parent PowerSeriesRing will have default precision 20 (or whatever the default default is). @@ -251,7 +251,7 @@ def x(self, prec=20): .. WARNING:: - The resulting series will have precision prec, but its + The resulting series will have precision ``prec``, but its parent PowerSeriesRing will have default precision 20 (or whatever the default default is). @@ -289,7 +289,7 @@ def y(self, prec=20): .. WARNING:: - The resulting series will have precision prec, but its + The resulting series will have precision ``prec``, but its parent PowerSeriesRing will have default precision 20 (or whatever the default default is). @@ -338,7 +338,7 @@ def differential(self, prec=20): .. WARNING:: - The resulting series will have precision prec, but its + The resulting series will have precision ``prec``, but its parent PowerSeriesRing will have default precision 20 (or whatever the default default is). @@ -417,7 +417,7 @@ def inverse(self, prec=20): .. WARNING:: - The resulting power series will have precision prec, but + The resulting power series will have precision ``prec``, but its parent PowerSeriesRing will have default precision 20 (or whatever the default default is). @@ -579,7 +579,7 @@ def mult_by_n(self, n, prec=10): .. WARNING:: - The resulting power series will have precision prec, but + The resulting power series will have precision ``prec``, but its parent PowerSeriesRing will have default precision 20 (or whatever the default default is). diff --git a/src/sage/schemes/elliptic_curves/gal_reps.py b/src/sage/schemes/elliptic_curves/gal_reps.py old mode 100644 new mode 100755 index 14700ad86c7..b9360acdf56 --- a/src/sage/schemes/elliptic_curves/gal_reps.py +++ b/src/sage/schemes/elliptic_curves/gal_reps.py @@ -130,7 +130,7 @@ def _ex_set(p): """ - Gives the set of the only values of trace^2/det + Give the set of the only values of trace^2/det that appear in a exceptional subgroup in PGL_2(F_p). EXAMPLES:: @@ -180,7 +180,7 @@ class GaloisRepresentation(SageObject): def __init__(self, E): r""" - see ``GaloisRepresentation`` for documentation + See ``GaloisRepresentation`` for documentation. EXAMPLES:: @@ -193,7 +193,7 @@ def __init__(self, E): def __repr__(self): r""" - string representation of the class + String representation of the class. EXAMPLES:: @@ -205,7 +205,7 @@ def __repr__(self): def __eq__(self,other): r""" - Compares two Galois representations. + Compare two Galois representations. We define tho compatible families of representations attached to elliptic curves to be isomorphic if the curves are equal. @@ -253,7 +253,7 @@ def elliptic_curve(self): def is_reducible(self, p): r""" - Return True if the mod-p representation is + Return ``True`` if the mod-p representation is reducible. This is equivalent to the existence of an isogeny defined over `\QQ` of degree `p` from the elliptic curve. @@ -262,7 +262,7 @@ def is_reducible(self, p): - ``p`` -- a prime number - OUTPUT: A boolean. + OUTPUT: boolean The answer is cached. @@ -307,13 +307,13 @@ def is_reducible(self, p): def is_irreducible(self, p): r""" - Return True if the mod p representation is irreducible. + Return ``True`` if the mod p representation is irreducible. INPUT: - ``p`` -- a prime number - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -362,22 +362,20 @@ def reducible_primes(self): def is_surjective(self, p, A=1000): r""" - Return True if the mod-p representation is + Return ``True`` if the mod-p representation is surjective onto `Aut(E[p]) = GL_2(\GF{p})`. - False if it is not, or None if we were unable to + ``False`` if it is not, or ``None`` if we were unable to determine whether it is or not. INPUT: - - ``p`` (integer) -- a prime number + - ``p`` -- integer; a prime number - - ``A`` (integer) -- a bound on the number of `a_p` to use + - ``A`` -- integer; a bound on the number of `a_p` to use - OUTPUT: - - - (boolean) -- True if the mod-p representation is surjective - and False if not. + OUTPUT: boolean; ``True`` if the mod-p representation is surjective + and ``False`` if not The answer is cached. @@ -418,13 +416,13 @@ def is_surjective(self, p, A=1000): REMARKS: 1. If `p \geq 5` then the mod-p representation is - surjective if and only if the p-adic representation is + surjective if and only if the `p`-adic representation is surjective. When `p = 2, 3` there are counterexamples. See papers of Dokchitsers and Elkies for more details. 2. For the primes `p=2` and 3, this will always answer either - True or False. For larger primes it might give None. + ``True`` or ``False``. For larger primes it might give ``None``. """ if not arith.is_prime(p): raise TypeError("p (=%s) must be prime." % p) @@ -443,7 +441,7 @@ def is_surjective(self, p, A=1000): def _is_surjective(self, p, A): r""" - helper function for ``is_surjective`` + Helper function for ``is_surjective``. The value of `A` is as before, except that `A=-1` is a special code to stop before @@ -607,12 +605,12 @@ def non_surjective(self, A=1000): INPUT: - - ``A`` -- an integer (default 1000). By increasing this parameter - the resulting set might get smaller. + - ``A`` -- integer (default: 1000); by increasing this parameter + the resulting set might get smaller OUTPUT: - - ``list`` -- if the curve has CM, returns [0]. + - ``list`` -- if the curve has CM, returns ``[0]``. Otherwise, returns a list of primes where mod-p representation is very likely not surjective. At any prime not in this list, the representation is definitely surjective. @@ -708,9 +706,9 @@ def image_type(self, p): INPUT: - - ``p`` a prime number + - ``p`` -- a prime number - OUTPUT: A string. + OUTPUT: string EXAMPLES:: @@ -1105,13 +1103,11 @@ def image_classes(self,p,bound=10000): INPUT: - - a prime ``p`` + - ``p`` -- a prime - - a natural number ``bound`` (default: 10000) - - OUTPUT: + - ``bound`` -- a natural number (default: 10000) - - a list of `p` real numbers in the interval `[0,1]` adding up to 1 + OUTPUT: list of `p` real numbers in the interval `[0,1]` adding up to 1 EXAMPLES:: @@ -1238,15 +1234,15 @@ def is_unramified(self,p,ell): if the inertia group at a place above `\ell` in `\text{Gal}(\bar\QQ/\QQ)` has trivial image in `GL_2(\ZZ_p)`. - For a Galois representation attached to an elliptic curve `E`, this returns True if `\ell\neq p` - and `E` has good reduction at `\ell`. + For a Galois representation attached to an elliptic curve `E`, this + returns ``True`` if `\ell\neq p` and `E` has good reduction at `\ell`. INPUT: - - ``p`` a prime - - ``ell`` another prime + - ``p`` -- a prime + - ``ell`` -- another prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1271,15 +1267,15 @@ def is_unipotent(self,p,ell): Return true if the Galois representation to `GL_2(\ZZ_p)` is unipotent at `\ell\neq p`, i.e. if the inertia group at a place above `\ell` in `\text{Gal}(\bar\QQ/\QQ)` maps into a Borel subgroup. - For a Galois representation attached to an elliptic curve `E`, this returns True if + For a Galois representation attached to an elliptic curve `E`, this returns ``True`` if `E` has semi-stable reduction at `\ell`. INPUT: - - ``p`` a prime - - ``ell`` a different prime + - ``p`` -- a prime + - ``ell`` -- a different prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1313,10 +1309,10 @@ def is_quasi_unipotent(self,p,ell): INPUT: - - ``p`` a prime - - ``ell`` a different prime + - ``p`` -- a prime + - ``ell`` -- a different prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1344,9 +1340,9 @@ def is_ordinary(self,p): INPUT: - - ``p`` a prime + - ``p`` -- a prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1372,9 +1368,9 @@ def is_crystalline(self,p): INPUT: - - ``p`` a prime + - ``p`` -- a prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1397,9 +1393,9 @@ def is_potentially_crystalline(self,p): INPUT: - - ``p`` a prime + - ``p`` -- a prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1421,9 +1417,9 @@ def is_semistable(self,p): INPUT: - - ``p`` a prime + - ``p`` -- a prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1443,13 +1439,13 @@ def is_potentially_semistable(self,p): r""" Return true if the `p`-adic Galois representation to `GL_2(\ZZ_p)` is potentially semistable. - For an elliptic curve `E`, this returns True always + For an elliptic curve `E`, this returns ``True`` always INPUT: - - ``p`` a prime + - ``p`` -- a prime - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/gal_reps_number_field.py b/src/sage/schemes/elliptic_curves/gal_reps_number_field.py old mode 100644 new mode 100755 index 607996a84c9..accde11b636 --- a/src/sage/schemes/elliptic_curves/gal_reps_number_field.py +++ b/src/sage/schemes/elliptic_curves/gal_reps_number_field.py @@ -134,7 +134,7 @@ def __repr__(self): def __eq__(self,other): r""" - Compares two Galois representations. + Compare two Galois representations. We define two compatible families of representations attached to elliptic curves to be equal if the curves are isomorphic. @@ -178,15 +178,14 @@ def non_surjective(self, A=100): INPUT: - - ``A`` -- int (a bound on the number of traces of Frobenius to use - while trying to prove surjectivity). + - ``A`` -- integer; a bound on the number of traces of Frobenius to use + while trying to prove surjectivity OUTPUT: - - ``list`` -- A list of primes where mod-`p` representation is - very likely not surjective. At any prime not in this list, - the representation is definitely surjective. If `E` has CM, - the list [0] is returned. + A list of primes where mod-`p` representation is very likely not + surjective. At any prime not in this list, the representation is + definitely surjective. If `E` has CM, the list ``[0]`` is returned. EXAMPLES:: @@ -234,10 +233,10 @@ def is_surjective(self, p, A=100): INPUT: - * ``p`` -- a prime number. + - ``p`` -- prime number - * ``A`` -- (integer) a bound on the number of traces of Frobenius to use - while trying to prove surjectivity. + - ``A`` -- integer; a bound on the number of traces of Frobenius to use + while trying to prove surjectivity EXAMPLES:: @@ -292,18 +291,17 @@ def isogeny_bound(self, A=100): INPUT: - - ``A`` -- int (a bound on the number of traces of Frobenius to - use while trying to prove the mod-`p` - representation is not contained in a Borel). + - ``A`` -- integer; a bound on the number of traces of Frobenius to + use while trying to prove the mod-`p` representation is not contained + in a Borel OUTPUT: - - ``list`` -- A list of primes which contains (but may not be - equal to) all `p` for which the image of the mod-`p` - representation is contained in a Borel subgroup. At any - prime not in this list, the image is definitely not - contained in a Borel. If E has `CM` defined over `K`, the list - [0] is returned. + A list of primes which contains (but may not be equal to) all `p` for + which the image of the mod-`p` representation is contained in a Borel + subgroup. At any prime not in this list, the image is definitely not + contained in a Borel. If E has `CM` defined over `K`, the list ``[0]`` + is returned. EXAMPLES:: @@ -379,11 +377,10 @@ def reducible_primes(self): OUTPUT: - - ``list`` -- A list of those primes `p` for which the mod-`p` - representation is contained in a Borel subgroup, i.e. is - reducible. If E has CM *defined over K*, the list [0] is - returned (in this case the representation is reducible for - infinitely many primes). + A list of those primes `p` for which the mod-`p` representation is + contained in a Borel subgroup, i.e. is reducible. If E has CM + *defined over K*, the list ``[0]`` is returned (in this case the + representation is reducible for infinitely many primes). EXAMPLES:: @@ -432,16 +429,16 @@ def _non_surjective(E, patience=100): INPUT: - - ``E`` -- EllipticCurve (over a number field). + - ``E`` -- :class:`EllipticCurve` (over a number field) - - ``A`` -- int (a bound on the number of traces of Frobenius to use - while trying to prove surjectivity). + - ``A`` -- integer; a bound on the number of traces of Frobenius to use + while trying to prove surjectivity OUTPUT: - - ``list`` -- A list of primes where mod-`p` representation is very likely - not surjective. At any prime not in this list, the representation is - definitely surjective. If E has CM, a :class:`ValueError` is raised. + A list of primes where mod-`p` representation is very likely not + surjective. At any prime not in this list, the representation is + definitely surjective. If E has CM, a :exc:`ValueError` is raised. EXAMPLES:: @@ -505,19 +502,17 @@ def Frobenius_filter(E, L, patience=100): INPUT: - - ``E`` -- EllipticCurve over a number field. + - ``E`` -- :class:`EllipticCurve` over a number field - - ``L`` -- a list of prime numbers. + - ``L`` -- list of prime numbers - - ``patience`` (int), default 100 -- a positive integer bounding - the number of traces of Frobenius to use while trying to prove - irreducibility. + - ``patience`` -- positive integer (default: 100) bounding the number of + traces of Frobenius to use while trying to prove irreducibility OUTPUT: - - list -- The list of all primes `\ell` in L for which the mod - `\ell` image might be contained in a Borel subgroup of - `GL_2(\mathbf{F}_{\ell})`. + The list of all primes `\ell` in L for which the mod `\ell` image might be + contained in a Borel subgroup of `GL_2(\mathbf{F}_{\ell})`. EXAMPLES:: @@ -606,17 +601,17 @@ def _exceptionals(E, L, patience=1000): INPUT: - - ``E`` -- EllipticCurve over a number field. + - ``E`` -- :class:`EllipticCurve` over a number field - - ``L`` -- a list of prime numbers. + - ``L`` -- list of prime numbers - - ``patience`` (int) -- a bound on the number of traces of Frobenius to - use while trying to prove surjectivity. + - ``patience`` -- integer; a bound on the number of traces of Frobenius to + use while trying to prove surjectivity OUTPUT: - - list -- The list of all primes l in L for which the mod l image - might fail to be surjective. + The list of all primes l in L for which the mod l image might fail to be + surjective. EXAMPLES:: @@ -755,7 +750,7 @@ def _over_numberfield(E): INPUT: - - ``E`` -- EllipticCurve over a number field. + - ``E`` -- :class:`EllipticCurve` over a number field OUTPUT: @@ -770,7 +765,6 @@ def _over_numberfield(E): sage: E = EllipticCurve([1, 2]) sage: sage.schemes.elliptic_curves.gal_reps_number_field._over_numberfield(E) Elliptic Curve defined by y^2 = x^3 + x + 2 over Number Field in a with defining polynomial x - """ K = E.base_field() @@ -788,7 +782,7 @@ def deg_one_primes_iter(K, principal_only=False): INPUT: - ``K`` -- a number field - - ``principal_only`` -- bool; if ``True``, only yield principal primes + - ``principal_only`` -- boolean; if ``True``, only yield principal primes OUTPUT: @@ -835,14 +829,14 @@ def _semistable_reducible_primes(E, verbose=False): INPUT: - - ``E`` -- EllipticCurve over a number field. + - ``E`` -- :class:`EllipticCurve` over a number field OUTPUT: A list of primes, which contains all primes `l` unramified in `K/\mathbb{QQ}`, such that `E` is semistable at all primes lying over `l`, and the Galois image at `l` is reducible. If `E` has CM - defined over its ground field, a :class:`ValueError` is raised. + defined over its ground field, a :exc:`ValueError` is raised. EXAMPLES:: @@ -1011,19 +1005,18 @@ def _possible_normalizers(E, SA): INPUT: - - ``E`` -- EllipticCurve over a number field K. + - ``E`` -- :class:`EllipticCurve` over a number field K - - ``SA`` -- a list of primes of K. + - ``SA`` -- list of primes of K OUTPUT: - - list -- A list of primes, which contains all primes `l` such that the - Galois image at `l` is contained in the normalizer of a Cartan - subgroup, such that the corresponding quadratic character is - ramified only at primes in SA. + - a list of primes, which contains all primes `l` such that the Galois + image at `l` is contained in the normalizer of a Cartan subgroup, such + that the corresponding quadratic character is ramified only at primes in SA. - - If `E` has geometric CM that is not defined over its ground field, a - ValueError is raised. + - if `E` has geometric CM that is not defined over its ground field, a + :exc:`ValueError` is raised. EXAMPLES:: @@ -1165,7 +1158,7 @@ def Billerey_P_l(E, l): INPUT: - ``E`` -- an elliptic curve over a number field `K`, given by a - global integral model. + global integral model - ``l`` -- a rational prime @@ -1200,11 +1193,12 @@ def Billerey_B_l(E,l,B=0): INPUT: - ``E`` -- an elliptic curve over a number field `K`, given by a - global integral model. + global integral model - - ``l`` (int) -- a rational prime + - ``l`` -- integer; a rational prime - - ``B`` (int) -- 0 or LCM of previous `B_l`: the prime-to-B part of this `B_l` is ignored. + - ``B`` -- integer; 0 or LCM of previous `B_l` the prime-to-B part of this + `B_l` is ignored EXAMPLES:: @@ -1242,11 +1236,12 @@ def Billerey_R_q(E, q, B=0): INPUT: - ``E`` -- an elliptic curve over a number field `K`, given by a - global integral model. + global integral model - ``q`` -- a prime ideal of `K` - - ``B`` (int) -- 0 or LCM of previous `R_q`: the prime-to-B part of this `R_q` is ignored. + - ``B`` -- integer; 0 or LCM of previous `R_q` the prime-to-B part of this + `R_q` is ignored EXAMPLES:: @@ -1286,21 +1281,21 @@ def Billerey_B_bound(E, max_l=200, num_l=8, small_prime_bound=0, debug=False): nonzero values are found (at most). Return the list of primes dividing all `B_l` computed, excluding those dividing 6 or ramified or of bad reduction or less than small_prime_bound. If - no non-zero values are found return [0]. + no nonzero values are found return ``[0]``. INPUT: - ``E`` -- an elliptic curve over a number field `K`, given by a - global integral model. + global integral model - - ``max_l`` (int, default 200) -- maximum size of primes l to check. + - ``max_l`` -- integer (default: 200); maximum size of primes l to check - - ``num_l`` (int, default 8) -- maximum number of primes l to check. + - ``num_l`` integer (default: 8); maximum number of primes l to check - - ``small_prime_bound`` (int, default 0) -- remove primes less - than this from the output. + - ``small_prime_bound`` -- integer (default: 0); remove primes less + than this from the output - - ``debug`` (bool, default ``False``) -- if ``True`` prints details. + - ``debug`` -- boolean (default: ``False``); if ``True`` prints details .. NOTE:: @@ -1394,23 +1389,23 @@ def Billerey_R_bound(E, max_l=200, num_l=8, small_prime_bound=None, debug=False) (at most) until ``num_l`` nonzero values are found (at most). Return the list of primes dividing all ``R_q`` computed, excluding those dividing 6 or ramified or of bad reduction or less than - small_prime_bound. If no non-zero values are found return [0]. + small_prime_bound. If no nonzero values are found return ``[0]``. INPUT: - ``E`` -- an elliptic curve over a number field `K`, given by a - global integral model. + global integral model - - ``max_l`` (int, default 200) -- maximum size of rational primes - l for which the primes q above l are checked. + - ``max_l`` -- integer (default: 200); maximum size of rational primes + l for which the primes q above l are checked - - ``num_l`` (int, default 8) -- maximum number of rational primes - l for which the primes q above l are checked. + - ``num_l`` -- integer (default: 8); maximum number of rational primes + l for which the primes q above l are checked - - ``small_prime_bound`` (int, default 0) -- remove primes less - than this from the output. + - ``small_prime_bound`` -- integer (default: 0); remove primes less + than this from the output - - ``debug`` (bool, default ``False``) -- if ``True`` prints details. + - ``debug`` -- boolean (default: ``False``); if ``True`` prints details .. NOTE:: @@ -1503,13 +1498,13 @@ def reducible_primes_Billerey(E, num_l=None, max_l=None, verbose=False): INPUT: - - ``E`` -- an elliptic curve defined over a number field `K`. + - ``E`` -- an elliptic curve defined over a number field `K` - - ``max_l`` (int or ``None`` (default)) -- the maximum prime + - ``max_l`` -- integer or ``None`` (default); the maximum prime `\ell` to use for the B-bound and R-bound. If ``None``, a default value will be used. - - ``num_l`` (int or ``None`` (default)) -- the number of primes + - ``num_l`` -- integer or ``None`` (default); the number of primes `\ell` to use for the B-bound and R-bound. If ``None``, a default value will be used. @@ -1526,7 +1521,7 @@ def reducible_primes_Billerey(E, num_l=None, max_l=None, verbose=False): Provided that one of these methods succeeds in producing a finite list of primes we check these using a local condition, and finally test that the primes returned actually are reducible. Otherwise - we return [0]. + we return ``[0]``. EXAMPLES:: @@ -1632,11 +1627,11 @@ def reducible_primes_naive(E, max_l=None, num_P=None, verbose=False): - ``E`` -- an elliptic curve defined over a number field `K` - - ``max_l`` (int or ``None`` (default)) -- the maximum prime - `\ell` to test. + - ``max_l`` -- integer or ``None`` (default); the maximum prime + `\ell` to test - - ``num_P`` (int or ``None`` (default)) -- the number of primes - `P` of `K` to use in testing each `\ell`. + - ``num_P`` -- integer or ``None`` (default); the number of primes + `P` of `K` to use in testing each `\ell` EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/heegner.py b/src/sage/schemes/elliptic_curves/heegner.py old mode 100644 new mode 100755 index 4079cfced94..fb5306f32b3 --- a/src/sage/schemes/elliptic_curves/heegner.py +++ b/src/sage/schemes/elliptic_curves/heegner.py @@ -146,11 +146,11 @@ def heegner_points(N, D=None, c=None): INPUT: - - `N` -- level (positive integer) + - ``N`` -- level (positive integer) - - `D` -- discriminant (negative integer) + - ``D`` -- discriminant (negative integer) - - `c` -- conductor (positive integer) + - ``c`` -- conductor (positive integer) EXAMPLES:: @@ -179,11 +179,11 @@ def heegner_point(N, D=None, c=1): INPUT: - - `N` -- level (positive integer) + - ``N`` -- level (positive integer) - - `D` -- discriminant (optional: default first valid `D`) + - ``D`` -- discriminant (optional: default first valid `D`) - - `c` -- conductor (positive integer, default: 1) + - ``c`` -- conductor (positive integer, default: 1) EXAMPLES:: @@ -243,11 +243,11 @@ def __init__(self, D, c, check=True): """ INPUT: - - `D` -- discriminant of quadratic imaginary field + - ``D`` -- discriminant of quadratic imaginary field - - `c` -- conductor (positive integer coprime to `D`) + - ``c`` -- conductor (positive integer coprime to `D`) - - ``check`` -- bool (default: ``True``); whether to check + - ``check`` -- boolean (default: ``True``); whether to check validity of input EXAMPLES:: @@ -564,8 +564,7 @@ def galois_group(self, base=QQ): def is_subfield(self, M): """ Return ``True`` if this ring class field is a subfield of the ring class field `M`. - - If `M` is not a ring class field, then a :class:`TypeError` is raised. + If `M` is not a ring class field, then a :exc:`TypeError` is raised. EXAMPLES:: @@ -703,9 +702,9 @@ def __call__(self, x): INPUT: - - `x` -- automorphism or quadratic field element + - ``x`` -- automorphism or quadratic field element - OUTPUT: An automorphism (or :class:`TypeError`) + OUTPUT: an automorphism (or :exc:`TypeError`) EXAMPLES:: @@ -721,7 +720,7 @@ def __call__(self, x): sage: G(alpha) Class field automorphism defined by 14*x^2 - 10*x*y + 25*y^2 - A :class:`TypeError` is raised when the coercion is not possible:: + A :exc:`TypeError` is raised when the coercion is not possible:: sage: G(0) Traceback (most recent call last): @@ -814,9 +813,7 @@ def kolyvagin_generators(self): identity element of `\textrm{Gal}(K_p/K_1)` for all `p \neq p_i` and to a choice of generator of `\textrm{Gal}(K_{p_i}/K_1)`. - OUTPUT: - - - list of elements of ``self`` + OUTPUT: list of elements of ``self`` EXAMPLES:: @@ -854,9 +851,7 @@ def lift_of_hilbert_class_field_galois_group(self): this function returns noncanonical choices of lifts of the elements of the quotient group `\textrm{Gal}(K_1/K)`. - OUTPUT: - - - tuple of elements of self + OUTPUT: tuple of elements of ``self`` EXAMPLES:: @@ -964,11 +959,9 @@ def _quadratic_form_to_alpha(self, f): """ INPUT: - - `f` -- a binary quadratic form with discriminant `c^2 D` - - OUTPUT: + - ``f`` -- a binary quadratic form with discriminant `c^2 D` - - an element of the ring of integers of the quadratic imaginary field + OUTPUT: an element of the ring of integers of the quadratic imaginary field EXAMPLES:: @@ -1002,7 +995,7 @@ def _alpha_to_automorphism(self, alpha): INPUT: - - `\alpha` -- element of quadratic imaginary field coprime to conductor + - ``alpha`` -- element of quadratic imaginary field coprime to conductor EXAMPLES:: @@ -1033,11 +1026,10 @@ def _alpha_to_p1_element(self, alpha): INPUT: - - `\alpha` -- element of the ring of integers of the quadratic imaginary field + - ``alpha`` -- element of the ring of integers of the quadratic + imaginary field - OUTPUT: - - - 2-tuple of integers + OUTPUT: 2-tuple of integers EXAMPLES:: @@ -1080,9 +1072,7 @@ def _p1_element_to_alpha(self, uv): - ``uv`` -- pair of integers - OUTPUT: - - - element of maximal order of quadratic field + OUTPUT: element of maximal order of quadratic field EXAMPLES:: @@ -1454,9 +1444,9 @@ def __init__(self, parent, quadratic_form, alpha=None): - ``parent`` -- a group of automorphisms of a ring class field - ``quadratic_form`` -- a binary quadratic form that - defines an element of the Galois group of `K_c` over `K`. + defines an element of the Galois group of `K_c` over `K` - - ``\alpha`` -- (default: ``None``) optional data that specified + - ``alpha`` -- (default: ``None``) optional data that specified element corresponding element of `(\mathcal{O}_K / c\mathcal{O}_K)^* / (\ZZ/c\ZZ)^*`, via class field theory. @@ -1698,7 +1688,7 @@ def ideal(self): ## ## INPUT: ## -## - `z` -- a Heegner point on `X_0(N)` or an elliptic curve +## - ``z`` -- a Heegner point on `X_0(N)` or an elliptic curve ## ## OUTPUT: ## @@ -1754,11 +1744,11 @@ def __init__(self, N, D, c): """ INPUT: - - `N` -- (positive integer) the level + - ``N`` -- (positive integer) the level - - `D` -- (negative integer) fundamental discriminant + - ``D`` -- (negative integer) fundamental discriminant - - `c` -- (positive integer) conductor + - ``c`` -- (positive integer) conductor Since this is an abstract base class, no type or compatibility checks are done, as those are all assumed to be done in the @@ -1979,7 +1969,7 @@ def __init__(self, N): """ INPUT: - - `N` -- level, a positive integer + - ``N`` -- level, a positive integer EXAMPLES:: @@ -2083,9 +2073,9 @@ def discriminants(self, n=10, weak=False): INPUT: - - `n` -- nonnegative integer + - ``n`` -- nonnegative integer - - ``weak`` -- bool (default: ``False``); if ``True`` only require + - ``weak`` -- boolean (default: ``False``); if ``True`` only require weak Heegner hypothesis, which is the same as usual but without the condition that `\gcd(D,N)=1`. @@ -2149,9 +2139,9 @@ def __init__(self, N, D): """ INPUT: - - `N` -- positive integer + - ``N`` -- positive integer - - `D` -- negative fundamental discriminant + - ``D`` -- negative fundamental discriminant EXAMPLES:: @@ -2248,13 +2238,13 @@ def kolyvagin_conductors(self, r=None, n=10, E=None, m=None): INPUT: - - `r` -- (default: ``None``) nonnegative integer or ``None`` + - ``r`` -- (default: ``None``) nonnegative integer or ``None`` - - `n` -- positive integer + - ``n`` -- positive integer - - `E` -- an elliptic curve + - ``E`` -- an elliptic curve - - `m` -- a positive integer + - ``m`` -- positive integer EXAMPLES:: @@ -2310,17 +2300,17 @@ def is_kolyvagin_conductor(N, E, D, r, n, c): INPUT: - - `N` -- level (positive integer) + - ``N`` -- level (positive integer) - - `E` -- elliptic curve or ``None`` + - ``E`` -- elliptic curve or ``None`` - - `D` -- negative fundamental discriminant + - ``D`` -- negative fundamental discriminant - - `r` -- number of prime factors (nonnegative integer) or ``None`` + - ``r`` -- number of prime factors (nonnegative integer) or ``None`` - - `n` -- torsion order (i.e., do we get class in `(E(K_c)/n E(K_c))^{Gal(K_c/K)}`?) + - ``n`` -- torsion order (i.e., do we get class in `(E(K_c)/n E(K_c))^{Gal(K_c/K)}`?) - - `c` -- conductor (positive integer) + - ``c`` -- conductor (positive integer) EXAMPLES:: @@ -2398,11 +2388,11 @@ def __init__(self, N, D, c=ZZ(1)): INPUT: - - `N` -- positive integer (the level) + - ``N`` -- positive integer (the level) - - `D` -- negative fundamental discriminant + - ``D`` -- negative fundamental discriminant - - `c` -- conductor (default: 1) + - ``c`` -- conductor (default: 1) EXAMPLES:: @@ -2646,7 +2636,7 @@ def points(self, beta=None): def plot(self, *args, **kwds): """ - Returns plot of all the representatives in the upper half + Return plot of all the representatives in the upper half plane of the Heegner points in this set of Heegner points. The inputs to this function get passed onto the point command. @@ -2696,18 +2686,18 @@ def __init__(self, N, D, c=ZZ(1), f=None, check=True): r""" INPUT: - - `N` -- positive integer + - ``N`` -- positive integer - - `D` -- fundamental discriminant, a negative integer + - ``D`` -- fundamental discriminant, a negative integer - - `c` -- conductor, a positive integer coprime to `N` + - ``c`` -- conductor, a positive integer coprime to `N` - - `f` -- binary quadratic form, 3-tuple `(A,B,C)` of coefficients + - ``f`` -- binary quadratic form, 3-tuple `(A,B,C)` of coefficients of `AX^2 + BXY + CY^2`, or element of quadratic imaginary - field `\QQ(\sqrt{D})` in the upper half plan. + field `\QQ(\sqrt{D})` in the upper half plane - - ``check`` -- bool, default: ``True``. should not be used - except internally. + - ``check`` -- boolean (default: ``True``); should not be used + except internally EXAMPLES:: @@ -2817,7 +2807,7 @@ def atkin_lehner_act(self, Q=None): INPUT: - - `Q` -- positive divisor of `N`; if not given, default to `N` + - ``Q`` -- positive divisor of `N`; if not given, default to `N` EXAMPLES:: @@ -3012,12 +3002,12 @@ def __init__(self, E, x, check=True): r""" INPUT: - - `E` -- an elliptic curve over the rational numbers + - ``E`` -- an elliptic curve over the rational numbers - - `x` -- Heegner point on `X_0(N)` + - ``x`` -- Heegner point on `X_0(N)` - - ``check`` -- bool (default: ``True``); if ``True``, ensure that `D`, - `c` are of type Integer and define a Heegner point on `E` + - ``check`` -- boolean (default: ``True``); if ``True``, ensure that `D`, + `c` are of type Integer and define a Heegner point on `E` EXAMPLES:: @@ -3045,7 +3035,7 @@ def satisfies_kolyvagin_hypothesis(self, n=None): INPUT: - - `n` -- positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -3233,9 +3223,7 @@ def _trace_index(self, *args, **kwds): the inputs to this function and more details about what is computed. In particular, the returned index can be off at 2. - OUTPUT: - - - ``Integer`` -- returns an integer + OUTPUT: ``Integer`` -- returns an integer EXAMPLES:: @@ -3391,13 +3379,13 @@ def x_poly_exact(self, prec=53, algorithm='lll'): """ Return irreducible polynomial over the rational numbers satisfied by the `x` coordinate of this Heegner point. A - ValueError is raised if the precision is clearly insignificant + :exc:`ValueError` is raised if the precision is clearly insignificant to define a point on the curve. .. WARNING:: It is in theory possible for this function to not raise a - ValueError, find a polynomial, but via some very unlikely + :exc:`ValueError`, find a polynomial, but via some very unlikely coincidence that point is not actually this Heegner point. INPUT: @@ -3463,7 +3451,6 @@ def x_poly_exact(self, prec=53, algorithm='lll'): (a : -4*a + 3 : 1) sage: all(c.parent().disc() == -7 for c in PE) True - """ L = self.ring_class_field() n = L.absolute_degree() @@ -3487,7 +3474,7 @@ def _check_poly_discriminant(self, f): INPUT: - - `f` -- a polynomial + - ``f`` -- a polynomial EXAMPLES:: @@ -3517,15 +3504,14 @@ def point_exact(self, prec=53, algorithm='lll', var='a', optimize=False): """ Return exact point on the elliptic curve over a number field defined by computing this Heegner point to the given number of - bits of precision. A ValueError is raised if the precision + bits of precision. A :exc:`ValueError` is raised if the precision is clearly insignificant to define a point on the curve. .. WARNING:: It is in theory possible for this function to not raise a - ValueError, find a point on the curve, but via some very - unlikely coincidence that point is not actually this Heegner - point. + :exc:`ValueError`, find a point on the curve, but via some very + unlikely coincidence that point is not actually this Heegner point. .. WARNING:: @@ -3537,11 +3523,11 @@ def point_exact(self, prec=53, algorithm='lll', var='a', optimize=False): - ``prec`` -- integer (default: 53) - ``algorithm`` -- see the description of the algorithm - parameter for the ``x_poly_exact`` method. + parameter for the ``x_poly_exact`` method - - ``var`` -- string (default: 'a') + - ``var`` -- string (default: ``'a'``) - - ``optimize`` -- bool (default; False) if ``True``, try to + - ``optimize`` -- boolean (default: ``False``); if ``True``, try to optimize defining polynomial for the number field that the point is defined over. Off by default, since this can be very expensive. @@ -3685,9 +3671,7 @@ def _numerical_approx_xy_poly(self, prec=53): - ``prec`` -- positive integer (default: 53) - OUTPUT: - - - 2-tuple of polynomials with floating point coefficients + OUTPUT: 2-tuple of polynomials with floating point coefficients EXAMPLES:: @@ -3720,9 +3704,7 @@ def _xy_poly_nearby(self, prec=53, max_error=10**(-10)): - ``max_error`` -- very small floating point number - OUTPUT: - - - 2-tuple of polynomials with rational coefficients + OUTPUT: 2-tuple of polynomials with rational coefficients EXAMPLES:: @@ -3788,7 +3770,7 @@ def _trace_numerical_conductor_1(self, prec=53): INPUT: - - `prec` -- bits precision (default: 53) + - ``prec`` -- bits precision (default: 53) EXAMPLES:: @@ -3902,7 +3884,7 @@ def _qf_to_tau(self, f): INPUT: - - `f` -- binary quadratic form + - ``f`` -- binary quadratic form EXAMPLES:: @@ -3955,13 +3937,11 @@ def _qf_atkin_lehner_act(self, Q, f): INPUT: - - `Q` -- integer that divides the level `N` - - - `f` -- quadratic form + - ``Q`` -- integer that divides the level `N` - OUTPUT: + - ``f`` -- quadratic form - - quadratic form + OUTPUT: quadratic form EXAMPLES:: @@ -4008,7 +3988,7 @@ def kolyvagin_cohomology_class(self, n=None): INPUT: - - `n` -- positive integer that divides the gcd of `a_p` + - ``n`` -- positive integer that divides the gcd of `a_p` and `p+1` for all `p` dividing the conductor. If `n` is ``None``, choose the largest valid `n`. @@ -4340,7 +4320,7 @@ def _trace_exact_conductor_1(self, prec=53): the case of conductor 1, computed using prec bits of precision, then approximated using some algorithm (e.g., continued fractions). If the precision is not enough to - determine a point on the curve, then a :class:`RuntimeError` is raised. + determine a point on the curve, then a :exc:`RuntimeError` is raised. Even if the precision determines a point, there is no guarantee that it is correct. @@ -4368,9 +4348,9 @@ def _recognize_point_over_QQ(self, P, n): INPUT: - - `P` -- numerical approximation for a point on `E` + - ``P`` -- numerical approximation for a point on `E` - - `n` -- upper bound on divisibility index of `P` in group `E(\QQ)` + - ``n`` -- upper bound on divisibility index of `P` in group `E(\QQ)` EXAMPLES:: @@ -4472,7 +4452,7 @@ def mod(self, p, prec=53): ## ## INPUT: ## -## - `n` -- positive integer +## - ``n`` -- positive integer ## ## - ``prec`` -- positive integer (default: 53) ## @@ -4486,7 +4466,7 @@ def kolyvagin_cohomology_class(self, n=None): """ INPUT: - - `n` -- positive integer that divides the gcd of `a_p` + - ``n`` -- positive integer that divides the gcd of `a_p` and `p+1` for all `p` dividing the conductor. If `n` is ``None``, choose the largest valid `n`. @@ -4633,11 +4613,6 @@ def heegner_point(self): return self.__kolyvagin_point.heegner_point() class KolyvaginCohomologyClassEn(KolyvaginCohomologyClass): - """ - - EXAMPLES: - - """ def _repr_(self): """ @@ -4770,11 +4745,11 @@ def satisfies_heegner_hypothesis(self, D, c=ZZ(1)): INPUT: - - `D` -- negative integer + - ``D`` -- negative integer - - `c` -- positive integer (default: 1) + - ``c`` -- positive integer (default: 1) - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -4807,9 +4782,9 @@ def heegner_discriminants(self, n=5): INPUT: - - `n` -- positive integer (default: 5) + - ``n`` -- positive integer (default: 5) - OUTPUT: A list. + OUTPUT: list EXAMPLES:: @@ -4836,11 +4811,11 @@ def heegner_conductors(self, D, n=5): INPUT: - - `D` -- negative integer; a fundamental Heegner discriminant + - ``D`` -- negative integer; a fundamental Heegner discriminant - - `n` -- positive integer (default: 5) + - ``n`` -- positive integer (default: 5) - OUTPUT: A list. + OUTPUT: list EXAMPLES:: @@ -4862,11 +4837,11 @@ def optimal_embeddings(self, D, c, R): """ INPUT: - - `D` -- negative fundamental discriminant + - ``D`` -- negative fundamental discriminant - - `c` -- integer coprime + - ``c`` -- integer coprime - - `R` -- Eichler order + - ``R`` -- Eichler order EXAMPLES:: @@ -4913,7 +4888,7 @@ def brandt_module(self): @cached_method def quaternion_algebra(self): """ - Return the rational quaternion algebra used to implement self. + Return the rational quaternion algebra used to implement ``self``. EXAMPLES:: @@ -4964,11 +4939,11 @@ def heegner_divisor(self, D, c=ZZ(1)): INPUT: - - `D` -- discriminant (negative integer) + - ``D`` -- discriminant (negative integer) - - `c` -- conductor (positive integer) + - ``c`` -- conductor (positive integer) - OUTPUT: A Brandt module element. + OUTPUT: a Brandt module element EXAMPLES:: @@ -5028,9 +5003,9 @@ def modp_splitting_data(self, p): INPUT: - - `p` -- unramified odd prime + - ``p`` -- unramified odd prime - OUTPUT: A 2-tuple of matrices over finite field. + OUTPUT: a 2-tuple of matrices over finite field EXAMPLES:: @@ -5113,7 +5088,7 @@ def modp_splitting_map(self, p): INPUT: - - `p` -- prime number + - ``p`` -- prime number EXAMPLES:: @@ -5146,9 +5121,9 @@ def cyclic_subideal_p1(self, I, c): INPUT: - - `I` -- right ideal of Eichler order or in quaternion algebra + - ``I`` -- right ideal of Eichler order or in quaternion algebra - - `c` -- square free integer (currently must be odd prime + - ``c`` -- square free integer (currently must be odd prime and coprime to level, discriminant, characteristic, etc. OUTPUT: @@ -5202,9 +5177,9 @@ def galois_group_over_hilbert_class_field(self, D, c): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `c` -- conductor (square-free integer) + - ``c`` -- conductor (square-free integer) EXAMPLES:: @@ -5226,9 +5201,9 @@ def galois_group_over_quadratic_field(self, D, c): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `c` -- conductor (square-free integer) + - ``c`` -- conductor (square-free integer) EXAMPLES:: @@ -5250,9 +5225,9 @@ def quadratic_field(self, D): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - OUTPUT: A quadratic number field. + OUTPUT: a quadratic number field EXAMPLES:: @@ -5273,14 +5248,14 @@ def kolyvagin_cyclic_subideals(self, I, p, alpha_quaternion): INPUT: - - `I` -- right ideal of the quaternion algebra + - ``I`` -- right ideal of the quaternion algebra - - `p` -- prime number + - ``p`` -- prime number - ``alpha_quaternion`` -- image in the quaternion algebra - of generator `\alpha` for `(\mathcal{O}_K / c\mathcal{O}_K)^* / (\ZZ/c\ZZ)^*`. + of generator `\alpha` for `(\mathcal{O}_K / c\mathcal{O}_K)^* / (\ZZ/c\ZZ)^*` - OUTPUT: A list of 2-tuples. + OUTPUT: list of 2-tuples EXAMPLES:: @@ -5326,9 +5301,9 @@ def kolyvagin_generator(self, K, p): INPUT: - - `K` -- quadratic imaginary field + - ``K`` -- quadratic imaginary field - - `p` -- inert prime + - ``p`` -- inert prime EXAMPLES:: @@ -5377,9 +5352,9 @@ def kolyvagin_generators(self, K, c): INPUT: - - `K` -- quadratic imaginary field + - ``K`` -- quadratic imaginary field - - `c` -- square free product of inert prime + - ``c`` -- square free product of inert prime EXAMPLES:: @@ -5418,11 +5393,11 @@ def kolyvagin_sigma_operator(self, D, c, r, bound=None): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `c` -- conductor (square-free integer, need not be prime) + - ``c`` -- conductor (square-free integer, need not be prime) - - `r` -- nonnegative integer + - ``r`` -- nonnegative integer - ``bound`` -- (default: ``None``), if given, controls precision of computation of theta series, which could @@ -5543,9 +5518,9 @@ def modp_dual_elliptic_curve_factor(self, E, p, bound=10): INPUT: - - `E` -- elliptic curve of conductor equal to the level of ``self`` + - ``E`` -- elliptic curve of conductor equal to the level of ``self`` - - `p` -- prime number + - ``p`` -- prime number - ``bound`` -- positive integer (default: 10) @@ -5590,11 +5565,11 @@ def rational_kolyvagin_divisor(self, D, c): INPUT: - - `D` -- discriminant (negative integer) + - ``D`` -- discriminant (negative integer) - - `c` -- conductor (positive integer) + - ``c`` -- conductor (positive integer) - OUTPUT: Brandt module element (or tuple of them). + OUTPUT: Brandt module element (or tuple of them) EXAMPLES:: @@ -5633,13 +5608,13 @@ def kolyvagin_point_on_curve(self, D, c, E, p, bound=10): INPUT: - - `D` -- fundamental negative discriminant + - ``D`` -- fundamental negative discriminant - - `c` -- conductor + - ``c`` -- conductor - - `E` -- elliptic curve of conductor the level of self + - ``E`` -- elliptic curve of conductor the level of self - - `p` -- odd prime number such that we consider image in + - ``p`` -- odd prime number such that we consider image in `E(\GF{\ell^2}) / p E(\GF{\ell^2})` - ``bound`` -- integer (default: 10) @@ -5664,28 +5639,26 @@ def kolyvagin_reduction_data(E, q, first_only=True): INPUT: - - `E` -- elliptic curve over `\QQ` of rank 1 or 2 + - ``E`` -- elliptic curve over `\QQ` of rank 1 or 2 - - `q` -- an odd prime that does not divide the order of the - rational torsion subgroup of `E` + - ``q`` -- an odd prime that does not divide the order of the + rational torsion subgroup of `E` - - ``first_only`` -- bool (default: ``True``) whether two only return - the first prime that one can work modulo to get data about - the Euler system + - ``first_only`` -- boolean (default: ``True``); whether two only return + the first prime that one can work modulo to get data about the Euler system OUTPUT in the rank 1 case or when the default flag ``first_only=True``: - - `\ell` -- first good odd prime satisfying the Kolyvagin - condition that `q` divides \gcd(a_{\ell},\ell+1)` and the - reduction map is surjective to `E(\GF{\ell}) / q - E(\GF{\ell})` + - `\ell` -- first good odd prime satisfying the Kolyvagin condition that + `q` divides \gcd(a_{\ell},\ell+1)` and the reduction map is surjective to + `E(\GF{\ell}) / q E(\GF{\ell})` - - `D` -- discriminant of the first quadratic imaginary field + - ``D`` -- discriminant of the first quadratic imaginary field `K` that satisfies the Heegner hypothesis for `E` such that both `\ell` is inert in `K`, and the twist `E^D` has analytic rank `\leq 1` - - `h_D` -- the class number of `K` + - ``h_D`` -- the class number of `K` - the dimension of the Brandt module `B(\ell,N)`, where `N` is the conductor of `E` @@ -5698,12 +5671,12 @@ def kolyvagin_reduction_data(E, q, first_only=True): - `\ell_2` -- second prime (as above) where reduction map is surjective - - `D` -- discriminant of the first quadratic imaginary field + - ``D`` -- discriminant of the first quadratic imaginary field `K` that satisfies the Heegner hypothesis for `E` such that both `\ell_1` and `\ell_2` are simultaneously inert in `K`, and the twist `E^D` has analytic rank `\leq 1` - - `h_D` -- the class number of `K` + - ``h_D`` -- the class number of `K` - the dimension of the Brandt module `B(\ell_1,N)`, where `N` is the conductor of `E` @@ -5883,13 +5856,13 @@ def __init__(self, D, c, R, beta): r""" INPUT: - - `D` -- negative fundamental discriminant + - ``D`` -- negative fundamental discriminant - - `c` -- positive integer coprime to `D` + - ``c`` -- positive integer coprime to `D` - - `R` -- Eichler order in a rational quaternion algebra + - ``R`` -- Eichler order in a rational quaternion algebra - - `\beta` -- element of `R` such that the homomorphism + - ``beta`` -- element of `R` such that the homomorphism sends `c\sqrt{D}` to `\beta` EXAMPLES:: @@ -5945,7 +5918,7 @@ def __call__(self, x): INPUT: - - `x` -- element of the quadratic order + - ``x`` -- element of the quadratic order EXAMPLES:: @@ -6115,11 +6088,11 @@ def quadratic_order(D, c, names='a'): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `c` -- conductor + - ``c`` -- conductor - - ``names`` -- string (default: 'a') + - ``names`` -- string (default: ``'a'``) OUTPUT: @@ -6153,7 +6126,7 @@ def class_number(D): INPUT: - - `D` -- integer + - ``D`` -- integer EXAMPLES:: @@ -6164,7 +6137,7 @@ def class_number(D): sage: sage.schemes.elliptic_curves.heegner.class_number(-163) 1 - A :class:`ValueError` is raised when `D` is not a fundamental + A :exc:`ValueError` is raised when `D` is not a fundamental discriminant:: sage: sage.schemes.elliptic_curves.heegner.class_number(-5) @@ -6182,9 +6155,9 @@ def is_inert(D, p): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `p` -- prime integer + - ``p`` -- prime integer EXAMPLES:: @@ -6205,9 +6178,9 @@ def is_split(D, p): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `p` -- prime integer + - ``p`` -- prime integer EXAMPLES:: @@ -6228,9 +6201,9 @@ def is_ramified(D, p): INPUT: - - `D` -- fundamental discriminant + - ``D`` -- fundamental discriminant - - `p` -- prime integer + - ``p`` -- prime integer EXAMPLES:: @@ -6250,7 +6223,7 @@ def nearby_rational_poly(f, **kwds): INPUT: - - `f` -- polynomial with real floating point entries + - ``f`` -- polynomial with real floating point entries - ``**kwds`` -- passed on to ``nearby_rational`` method @@ -6275,7 +6248,7 @@ def simplest_rational_poly(f, prec): INPUT: - - `f` -- polynomial with real floating point entries + - ``f`` -- polynomial with real floating point entries - ``prec`` -- positive integer @@ -6302,9 +6275,9 @@ def satisfies_weak_heegner_hypothesis(N, D): INPUT: - - `N` -- positive integer + - ``N`` -- positive integer - - `D` -- negative integer + - ``D`` -- negative integer EXAMPLES:: @@ -6345,9 +6318,9 @@ def make_monic(f): INPUT: - - `f` -- polynomial over the rational numbers + - ``f`` -- polynomial over the rational numbers - OUTPUT: A monic integral polynomial and an integer. + OUTPUT: a monic integral polynomial and an integer EXAMPLES:: @@ -6402,7 +6375,7 @@ def make_monic(f): def ell_heegner_point(self, D, c=ZZ(1), f=None, check=True): r""" - Returns the Heegner point on this curve associated to the + Return the Heegner point on this curve associated to the quadratic imaginary field `K=\QQ(\sqrt{D})`. If the optional parameter `c` is given, returns the higher Heegner @@ -6410,16 +6383,16 @@ def ell_heegner_point(self, D, c=ZZ(1), f=None, check=True): INPUT: - - `D` -- a Heegner discriminant + - ``D`` -- a Heegner discriminant - - `c` -- (default: 1) conductor, must be coprime to `DN` + - ``c`` -- (default: 1) conductor, must be coprime to `DN` - - `f` -- binary quadratic form or 3-tuple `(A,B,C)` of coefficients + - ``f`` -- binary quadratic form or 3-tuple `(A,B,C)` of coefficients of `AX^2 + BXY + CY^2` - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - OUTPUT: The Heegner point `y_c`. + OUTPUT: the Heegner point `y_c` EXAMPLES:: @@ -6472,13 +6445,13 @@ def kolyvagin_point(self, D, c=ZZ(1), check=True): INPUT: - - `D` -- a Heegner discriminant + - ``D`` -- a Heegner discriminant - - `c` -- (default: 1) conductor, must be coprime to `DN` + - ``c`` -- (default: 1) conductor, must be coprime to `DN` - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - OUTPUT: The Kolyvagin point `P` of conductor `c`. + OUTPUT: the Kolyvagin point `P` of conductor `c` EXAMPLES:: @@ -6499,15 +6472,15 @@ def kolyvagin_point(self, D, c=ZZ(1), check=True): def ell_heegner_discriminants(self, bound): """ - Return the list of self's Heegner discriminants between -1 and + Return the list of ``self``'s Heegner discriminants between -1 and -bound. INPUT: - - ``bound (int)`` -- upper bound for -discriminant + - ``bound`` -- integer; upper bound for -discriminant - OUTPUT: The list of Heegner discriminants between -1 and -bound for - the given elliptic curve. + OUTPUT: the list of Heegner discriminants between -1 and -bound for + the given elliptic curve EXAMPLES:: @@ -6521,15 +6494,15 @@ def ell_heegner_discriminants(self, bound): def ell_heegner_discriminants_list(self, n): """ - Return the list of self's first `n` Heegner discriminants smaller + Return the list of ``self``'s first `n` Heegner discriminants smaller than -5. INPUT: - - ``n (int)`` -- the number of discriminants to compute + - ``n`` -- integer; the number of discriminants to compute - OUTPUT: The list of the first n Heegner discriminants smaller than - -5 for the given elliptic curve. + OUTPUT: the list of the first `n` Heegner discriminants smaller than + `-5` for the given elliptic curve EXAMPLES:: @@ -6557,16 +6530,16 @@ def heegner_point_height(self, D, prec=2, check_rank=True): INPUT: - - ``D (int)`` -- fundamental discriminant (=/= -3, -4) + - ``D`` -- integer; fundamental discriminant (=/= -3, -4) - - ``prec (int)`` -- (default: 2), use `prec \cdot \sqrt(N) + 20` + - ``prec`` -- integer (default: 2); use `prec \cdot \sqrt(N) + 20` terms of `L`-series in computations, where `N` is the - conductor. + conductor - ``check_rank`` -- whether to check if the rank is at least 2 by - computing the Mordell-Weil rank directly. + computing the Mordell-Weil rank directly - OUTPUT: Interval that contains the height of the Heegner point. + OUTPUT: interval that contains the height of the Heegner point EXAMPLES:: @@ -6653,22 +6626,22 @@ def heegner_index(self, D, min_p=2, prec=5, descent_second_limit=12, INPUT: - - ``D (int)`` -- Heegner discriminant + - ``D`` -- integer; Heegner discriminant - - ``min_p (int)`` -- (default: 2) only rule out primes - = min_p dividing the index. + - ``min_p`` -- integer (default: 2); only rule out primes + = min_p dividing the index - - ``verbose_mwrank (bool)`` -- (default: ``False``); print lots of + - ``verbose_mwrank`` -- boolean (default: ``False``); print lots of mwrank search status information when computing regulator - - ``prec (int)`` -- (default: 5), use prec\*sqrt(N) + - 20 terms of L-series in computations, where N is the conductor. + - ``prec`` -- integer (default: 5);, use prec\*sqrt(N) + + 20 terms of `L`-series in computations, where N is the conductor - ``descent_second_limit`` -- (default: 12)- used in 2-descent when computing regulator of the twist - ``check_rank`` -- whether to check if the rank is at least 2 by - computing the Mordell-Weil rank directly. + computing the Mordell-Weil rank directly OUTPUT: an interval that contains the index, or half the index @@ -6863,14 +6836,14 @@ def heegner_index_bound(self, D=0, prec=5, max_height=None): INPUT: - - ``D (int)`` -- (default: 0) Heegner discriminant; if + - ``D`` -- integer (default: 0); Heegner discriminant; if 0, use the first discriminant -4 that satisfies the Heegner hypothesis - - ``verbose (bool)`` -- (default: ``True``) + - ``verbose`` -- boolean (default: ``True``) - - ``prec (int)`` -- (default: 5), use `prec \cdot \sqrt(N) + 20` - terms of `L`-series in computations, where `N` is the conductor. + - ``prec`` -- integer (default: 5); use `prec \cdot \sqrt(N) + 20` + terms of `L`-series in computations, where `N` is the conductor - ``max_height (float)`` -- should be = 21; bound on logarithmic naive height used in point searches. Make smaller to @@ -6882,7 +6855,7 @@ def heegner_index_bound(self, D=0, prec=5, max_height=None): - ``v`` -- list or int (bad primes or 0 or -1) - ``D`` -- the discriminant that was used (this is - useful if `D` was automatically selected). + useful if `D` was automatically selected) - ``exact`` -- either False, or the exact Heegner index (up to factors of 2) @@ -6984,9 +6957,9 @@ def _heegner_index_in_EK(self, D): INPUT: - - `D` -- negative integer; the Heegner discriminant + - ``D`` -- negative integer; the Heegner discriminant - OUTPUT: A power of 2 -- the given index. + OUTPUT: a power of 2 -- the given index EXAMPLES: @@ -7083,9 +7056,9 @@ def heegner_sha_an(self, D, prec=53): INPUT: - - `D` -- negative integer; the Heegner discriminant + - ``D`` -- negative integer; the Heegner discriminant - - prec -- integer (default: 53); bits of precision to + - ``prec`` -- integer (default: 53); bits of precision to compute analytic order of Sha OUTPUT: @@ -7235,7 +7208,7 @@ def heegner_sha_an(self, D, prec=53): def _heegner_forms_list(self, D, beta=None, expected_count=None): r""" - Returns a list of quadratic forms corresponding to Heegner points + Return a list of quadratic forms corresponding to Heegner points with discriminant `D` and a choice of `\beta` a square root of `D` mod `4N`. Specifically, given a quadratic form `f = Ax^2 + Bxy + Cy^2` we let `\tau_f` be a root of `Ax^2 + Bx + C` @@ -7314,7 +7287,7 @@ def _heegner_best_tau(self, D, prec=None): def satisfies_heegner_hypothesis(self, D): """ - Returns ``True`` precisely when `D` is a fundamental discriminant that + Return ``True`` precisely when `D` is a fundamental discriminant that satisfies the Heegner hypothesis for this elliptic curve. EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/height.py b/src/sage/schemes/elliptic_curves/height.py old mode 100644 new mode 100755 index 9b5b6176b80..88447c3bdbd --- a/src/sage/schemes/elliptic_curves/height.py +++ b/src/sage/schemes/elliptic_curves/height.py @@ -109,7 +109,7 @@ def __init__(self, endpoints): def finite_endpoints(self): r""" - Returns the finite endpoints of this union of intervals. + Return the finite endpoints of this union of intervals. EXAMPLES:: @@ -123,7 +123,7 @@ def finite_endpoints(self): def intervals(self): r""" - Returns the intervals in self, as a list of 2-tuples. + Return the intervals in self, as a list of 2-tuples. EXAMPLES:: @@ -137,7 +137,7 @@ def intervals(self): def is_empty(self): r""" - Returns whether self is empty. + Return whether ``self`` is empty. EXAMPLES:: @@ -232,7 +232,7 @@ def __radd__(self, other): def __invert__(self): r""" - Return the closure of the complement of self. + Return the closure of the complement of ``self``. .. NOTE:: @@ -268,10 +268,10 @@ def join(L, condition): INPUT: - - ``L`` (list) -- a list of UnionOfIntervals instances + - ``L`` -- list of UnionOfIntervals instances - - ``condition`` (function) -- either ``any`` or ``all``, or - some other boolean function of a list of boolean values. + - ``condition`` -- function; either ``any`` or ``all``, or + some other boolean function of a list of boolean values OUTPUT: @@ -319,7 +319,7 @@ def union(cls, L): INPUT: - - ``L`` (list) -- a list of UnionOfIntervals instances + - ``L`` -- list of UnionOfIntervals instances OUTPUT: @@ -349,7 +349,7 @@ def intersection(cls, L): INPUT: - - ``L`` (list) -- a list of UnionOfIntervals instances + - ``L`` -- list of UnionOfIntervals instances OUTPUT: @@ -381,11 +381,9 @@ def __or__(left, right): INPUT: - - ``left``, ``right`` (UnionOfIntervals) -- two UnionOfIntervals instances + - ``left``, ``right`` -- two UnionOfIntervals instances - OUTPUT: - - A new UnionOfIntervals instance representing the union of ``left`` and ``right``. + OUTPUT: a new UnionOfIntervals instance representing the union of ``left`` and ``right`` EXAMPLES:: @@ -405,11 +403,9 @@ def __and__(left, right): INPUT: - - ``left``, ``right`` (UnionOfIntervals) -- two UnionOfIntervals instances + - ``left``, ``right`` -- two UnionOfIntervals instances - OUTPUT: - - A new UnionOfIntervals instance representing the intersection of ``left`` and ``right``. + OUTPUT: a new UnionOfIntervals instance representing the intersection of ``left`` and ``right`` EXAMPLES:: @@ -425,15 +421,13 @@ def __and__(left, right): def __contains__(self, x): r""" - Return True if ``x`` is in the UnionOfIntervals. + Return ``True`` if ``x`` is in the UnionOfIntervals. INPUT: - - ``x`` (real) -- a real number + - ``x`` -- real number - OUTPUT: - - Boolean: True if and only if ``x`` is in the union of intervals. + OUTPUT: boolean; ``True`` if and only if `x` is in the union of intervals EXAMPLES:: @@ -477,11 +471,11 @@ def __repr__(self): def nonneg_region(f): r""" - Returns the UnionOfIntervals representing the region where ``f`` is non-negative. + Return the UnionOfIntervals representing the region where ``f`` is nonnegative. INPUT: - - ``f`` (polynomial) -- a univariate polynomial over `\RR`. + - ``f`` -- a univariate polynomial over `\RR` OUTPUT: @@ -522,13 +516,13 @@ def nonneg_region(f): def inf_max_abs(f, g, D): r""" - Returns `\inf_D(\max(|f|, |g|))`. + Return `\inf_D(\max(|f|, |g|))`. INPUT: - - ``f``, ``g`` (polynomials) -- real univariate polynomials + - ``f``, ``g`` -- real univariate polynomials - - ``D`` (:class:`UnionOfIntervals`) -- a subset of `\RR` + - ``D`` -- :class:`UnionOfIntervals`; a subset of `\RR` OUTPUT: @@ -566,15 +560,15 @@ def inf_max_abs(f, g, D): def min_on_disk(f, tol, max_iter=10000): r""" - Returns the minimum of a real-valued complex function on a square. + Return the minimum of a real-valued complex function on a square. INPUT: - ``f`` -- a function from CIF to RIF - - ``tol`` (real) -- a positive real number + - ``tol`` -- a positive real number - - ``max_iter`` (integer, default 10000) -- a positive integer + - ``max_iter`` -- integer (default: 10000); a positive integer bounding the number of iterations to be used OUTPUT: @@ -659,9 +653,9 @@ def rat_term_CIF(z, try_strict=True): INPUT: - - ``z`` (complex) -- a CIF element + - ``z`` -- complex; a CIF element - - ``try_strict`` (bool) -- flag + - ``try_strict`` -- boolean; flag EXAMPLES:: @@ -725,9 +719,9 @@ def eps(err, is_real): INPUT: - - ``err`` (real) -- a positive real number, the radius of the interval + - ``err`` -- a positive real number; the radius of the interval - - ``is_real`` (boolean) -- if True, returns a real interval in + - ``is_real`` -- boolean; if ``True``, returns a real interval in RIF, else a complex interval in CIF OUTPUT: @@ -776,7 +770,7 @@ def __init__(self, E): INPUT: - - `E` -- an elliptic curve defined over a number field + - ``E`` -- an elliptic curve defined over a number field EXAMPLES:: @@ -864,11 +858,9 @@ def __call__(self, P): INPUT: - - ``P`` -- a point on the elliptic curve. - - OUTPUT: + - ``P`` -- a point on the elliptic curve - The canonical height of ``P``. + OUTPUT: the canonical height of ``P`` EXAMPLES:: @@ -978,7 +970,7 @@ def e_p(self, p): INPUT: - - ``p`` -- a prime ideal of `K` (or a prime number if `K=\QQ`). + - ``p`` -- a prime ideal of `K` (or a prime number if `K=\QQ`) OUTPUT: @@ -1033,7 +1025,7 @@ def DE(self, n): INPUT: - - ``n`` (int) -- a positive integer + - ``n`` -- positive integer OUTPUT: @@ -1097,9 +1089,9 @@ def B(self, n, mu): INPUT: - - ``n`` (int) -- a positive integer + - ``n`` -- positive integer - - ``mu`` (real) -- a positive real number + - ``mu`` -- positive real number OUTPUT: @@ -1137,11 +1129,11 @@ def psi(self, xi, v): INPUT: - - ``xi`` (real) -- the real x-coordinate of a point on the + - ``xi`` -- real; the real x-coordinate of a point on the curve in the connected component with respect to a real - embedding. + embedding - - ``v`` (embedding) -- a real embedding of the number field. + - ``v`` -- a real embedding of the number field OUTPUT: @@ -1204,9 +1196,9 @@ def S(self, xi1, xi2, v): INPUT: - - ``xi1``, ``xi2`` (real) -- real numbers with `\xi_1\le\xi_2`. + - ``xi1``, ``xi2`` -- real numbers with `\xi_1\le\xi_2` - - ``v`` (embedding) -- a real embedding of the field. + - ``v`` -- a real embedding of the field OUTPUT: @@ -1252,11 +1244,11 @@ def Sn(self, xi1, xi2, n, v): INPUT: - - ``xi1``, ``xi2`` (real) -- real numbers with `\xi_1\le\xi_2`. + - ``xi1``, ``xi2`` -- real numbers with `\xi_1\le\xi_2` - - ``n`` (integer) -- a positive integer. + - ``n`` -- positive integer - - ``v`` (embedding) -- a real embedding of the field. + - ``v`` -- a real embedding of the field OUTPUT: @@ -1295,17 +1287,17 @@ def Sn(self, xi1, xi2, n, v): def real_intersection_is_empty(self, Bk, v): r""" - Returns True iff an intersection of `S_n^{(v)}` sets is empty. + Return ``True`` iff an intersection of `S_n^{(v)}` sets is empty. INPUT: - - ``Bk`` (list) -- a list of reals. + - ``Bk`` -- list of reals - - ``v`` (embedding) -- a real embedding of the number field. + - ``v`` -- a real embedding of the number field OUTPUT: - True or False, according as the intersection of the unions of + ``True`` or ``False``, according as the intersection of the unions of intervals `S_n^{(v)}(-b,b)` for `b` in the list ``Bk`` is empty or not. When ``Bk`` is the list of `b=B_n(\mu)` for `n=1,2,3,\dots` for some `\mu>0` this means that all @@ -1363,7 +1355,7 @@ def tau(self, v): INPUT: - - ``v`` (embedding) -- a real or complex embedding of the number field. + - ``v`` -- a real or complex embedding of the number field OUTPUT: @@ -1385,7 +1377,7 @@ def wp_c(self, v): INPUT: - - ``v`` (embedding) -- a real or complex embedding of the number field. + - ``v`` -- a real or complex embedding of the number field OUTPUT: @@ -1424,15 +1416,15 @@ def fk_intervals(self, v=None, N=20, domain=CIF): INPUT: - - ``v`` (embedding) -- an embedding of the number field. If - None (default) use the real embedding if the field is `\QQ` + - ``v`` -- an embedding of the number field. If + ``None`` (default) use the real embedding if the field is `\QQ` and raise an error for other fields. - - ``N`` (int) -- The number of terms to use in the - `q`-expansion of `\wp`. + - ``N`` -- integer; the number of terms to use in the + `q`-expansion of `\wp` - - ``domain`` (complex field) -- the model of `\CC` to use, for - example ``CDF`` of ``CIF`` (default). + - ``domain`` -- (complex field) the model of `\CC` to use, for + example ``CDF`` of ``CIF`` (default) OUTPUT: @@ -1524,16 +1516,16 @@ def wp_intervals(self, v=None, N=20, abs_only=False): INPUT: - - ``v`` (embedding) -- an embedding of the number field. If - None (default) use the real embedding if the field is `\QQ` - and raise an error for other fields. + - ``v`` -- an embedding of the number field; if + ``None`` (default) use the real embedding if the field is `\QQ` + and raise an error for other fields - - ``N`` (int, default 20) -- The number of terms to use in the - `q`-expansion of `\wp`. + - ``N`` -- integer (default: 20); The number of terms to use in the + `q`-expansion of `\wp` - - ``abs_only`` (boolean, default: ``False``) -- flag to determine - whether (if True) the error adjustment should use the - absolute value or (if False) the real and imaginary parts. + - ``abs_only``-- boolean (default: ``False``); flag to determine + whether (if ``True``) the error adjustment should use the + absolute value or (if ``False``) the real and imaginary parts OUTPUT: @@ -1610,13 +1602,13 @@ def wp_on_grid(self, v, N, half=False): INPUT: - - ``v`` (embedding) -- an embedding of the number field. + - ``v`` -- an embedding of the number field - - ``N`` (int) -- The number of terms to use in the - `q`-expansion of `\wp`. + - ``N`` -- integer; the number of terms to use in the + `q`-expansion of `\wp` - - ``half`` (boolean, default: ``False``) -- if True, use an array of - size `N\times N/2` instead of `N\times N`. + - ``half``-- boolean (default: ``False``); if ``True``, use an array of + size `N\times N/2` instead of `N\times N` OUTPUT: @@ -1661,22 +1653,22 @@ def wp_on_grid(self, v, N, half=False): def complex_intersection_is_empty(self, Bk, v, verbose=False, use_half=True): r""" - Returns True iff an intersection of `T_n^{(v)}` sets is empty. + Return ``True`` iff an intersection of `T_n^{(v)}` sets is empty. INPUT: - - ``Bk`` (list) -- a list of reals. + - ``Bk`` -- list of reals - - ``v`` (embedding) -- a complex embedding of the number field. + - ``v`` -- a complex embedding of the number field - - ``verbose`` (boolean, default: ``False``) -- verbosity flag. + - ``verbose``-- boolean (default: ``False``); verbosity flag - - ``use_half`` (boolean, default: ``False``) -- if True, use only half - the fundamental region. + - ``use_half``-- boolean (default: ``False``); if ``True``, use only half + the fundamental region OUTPUT: - True or False, according as the intersection of the unions of + ``True`` or ``False``, according as the intersection of the unions of intervals `T_n^{(v)}(-b,b)` for `b` in the list ``Bk`` (see [Tho2010]_, section 7) is empty or not. When ``Bk`` is the list of `b=\sqrt{B_n(\mu)}` for `n=1,2,3,\dots` for some `\mu>0` this @@ -1786,11 +1778,11 @@ def test_mu(self, mu, N, verbose=True): INPUT: - - ``mu`` (real) -- a positive real number + - ``mu`` -- positive real number - - ``N`` (integer) -- upper bound on the multiples to be used. + - ``N`` -- integer; upper bound on the multiples to be used - - ``verbose`` (boolean, default: ``True``) -- verbosity flag. + - ``verbose``-- boolean (default: ``True``); verbosity flag OUTPUT: @@ -1883,15 +1875,15 @@ def test_mu(self, mu, N, verbose=True): def min_gr(self, tol, n_max, verbose=False): r""" - Returns a lower bound for points of infinite order with good reduction. + Return a lower bound for points of infinite order with good reduction. INPUT: - - ``tol`` -- tolerance in output (see below). + - ``tol`` -- tolerance in output (see below) - - ``n_max`` -- how many multiples to use in iteration. + - ``n_max`` -- how many multiples to use in iteration - - ``verbose`` (boolean, default: ``False``) -- verbosity flag. + - ``verbose``-- boolean (default: ``False``); verbosity flag OUTPUT: @@ -2009,15 +2001,15 @@ def min_gr(self, tol, n_max, verbose=False): def min(self, tol, n_max, verbose=False): r""" - Returns a lower bound for all points of infinite order. + Return a lower bound for all points of infinite order. INPUT: - - ``tol`` -- tolerance in output (see below). + - ``tol`` -- tolerance in output (see below) - - ``n_max`` -- how many multiples to use in iteration. + - ``n_max`` -- how many multiples to use in iteration - - ``verbose`` (boolean, default: ``False``) -- verbosity flag. + - ``verbose``-- boolean (default: ``False``); verbosity flag OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/hom.py b/src/sage/schemes/elliptic_curves/hom.py old mode 100644 new mode 100755 index fe450c89c5c..7bf61914f9a --- a/src/sage/schemes/elliptic_curves/hom.py +++ b/src/sage/schemes/elliptic_curves/hom.py @@ -561,8 +561,8 @@ def formal(self, prec=20): INPUT: - - ``prec`` -- (default: 20), the precision with which the - computations in the formal group are carried out. + - ``prec`` -- (default: 20) the precision with which the + computations in the formal group are carried out EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/hom_composite.py b/src/sage/schemes/elliptic_curves/hom_composite.py old mode 100644 new mode 100755 index d687c07c2bd..6952f2a0e11 --- a/src/sage/schemes/elliptic_curves/hom_composite.py +++ b/src/sage/schemes/elliptic_curves/hom_composite.py @@ -449,9 +449,9 @@ def from_factors(cls, maps, E=None, strict=True): INPUT: - ``maps`` -- sequence of :class:`EllipticCurveHom` objects - - ``E`` (optional) -- the domain elliptic curve - - ``strict`` (default: ``True``) -- if ``True``, - always return an :class:`EllipticCurveHom_composite` object; + - ``E`` -- (optional) the domain elliptic curve + - ``strict`` -- boolean (default: ``True``); if ``True``, + always return an :class:`EllipticCurveHom_composite` object, else may return another :class:`EllipticCurveHom` type OUTPUT: the composite of ``maps`` diff --git a/src/sage/schemes/elliptic_curves/hom_sum.py b/src/sage/schemes/elliptic_curves/hom_sum.py old mode 100644 new mode 100755 index ab10ec0d530..50f03d6d761 --- a/src/sage/schemes/elliptic_curves/hom_sum.py +++ b/src/sage/schemes/elliptic_curves/hom_sum.py @@ -560,7 +560,6 @@ def scaling_factor(self): the standard Weierstrass differentials on `E_i` defined by `\mathrm dx/(2y+a_1x+a_3)`. - EXAMPLES:: sage: E = EllipticCurve(GF(101), [5,5]) diff --git a/src/sage/schemes/elliptic_curves/hom_velusqrt.py b/src/sage/schemes/elliptic_curves/hom_velusqrt.py old mode 100644 new mode 100755 index ad6a8919261..c7c6e434ce5 --- a/src/sage/schemes/elliptic_curves/hom_velusqrt.py +++ b/src/sage/schemes/elliptic_curves/hom_velusqrt.py @@ -699,7 +699,7 @@ def __init__(self, E, P, *, codomain=None, model=None, Q=None): Elliptic-curve isogeny (using square-root Vélu) of degree 105: From: Elliptic Curve defined by y^2 = x^3 + x over Finite Field of size 419 To: Elliptic Curve defined by y^2 = x^3 + 6*x^2 + 385*x + 42 over Finite Field of size 419 - sage: EllipticCurveHom_velusqrt(E, K, model="montgomery") + sage: EllipticCurveHom_velusqrt(E, K, model='montgomery') Elliptic-curve isogeny (using square-root Vélu) of degree 105: From: Elliptic Curve defined by y^2 = x^3 + x over Finite Field of size 419 To: Elliptic Curve defined by y^2 = x^3 + 6*x^2 + x over Finite Field of size 419 diff --git a/src/sage/schemes/elliptic_curves/isogeny_class.py b/src/sage/schemes/elliptic_curves/isogeny_class.py old mode 100644 new mode 100755 index ede5b7bd788..2c710b09f0b --- a/src/sage/schemes/elliptic_curves/isogeny_class.py +++ b/src/sage/schemes/elliptic_curves/isogeny_class.py @@ -57,7 +57,7 @@ def __init__(self, E, label=None, empty=False): INPUT: - ``label`` -- string or ``None``, a Cremona or LMFDB label, used - in printing. Ignored if base field is not `\QQ`. + in printing; ignored if base field is not `\QQ` EXAMPLES:: @@ -102,7 +102,7 @@ def __getitem__(self, i): EXAMPLES:: sage: E = EllipticCurve('990j1') - sage: iso = E.isogeny_class(order="lmfdb") # orders lexicographically on a-invariants + sage: iso = E.isogeny_class(order='lmfdb') # orders lexicographically on a-invariants sage: iso[2] == E # indirect doctest True """ @@ -114,17 +114,17 @@ def index(self, C): INPUT: - - ``C`` -- an elliptic curve in this isogeny class. + - ``C`` -- an elliptic curve in this isogeny class OUTPUT: - - ``i`` -- an integer so that the ``i`` th curve in the class + - ``i`` -- integer so that the ``i`` th curve in the class is isomorphic to ``C`` EXAMPLES:: sage: E = EllipticCurve('990j1') - sage: iso = E.isogeny_class(order="lmfdb") # orders lexicographically on a-invariants + sage: iso = E.isogeny_class(order='lmfdb') # orders lexicographically on a-invariants sage: iso.index(E.short_weierstrass_model()) 2 """ @@ -235,12 +235,10 @@ def __contains__(self, x): """ INPUT: - - ``x`` -- a Python object. + - ``x`` -- a Python object - OUTPUT: - - - boolean -- ``True`` iff ``x`` is an elliptic curve in this - isogeny class. + OUTPUT: boolean; ``True`` iff ``x`` is an elliptic curve in this + isogeny class .. NOTE:: @@ -267,8 +265,8 @@ def matrix(self, fill=True): INPUT: - - ``fill`` -- boolean (default ``True``). If ``False`` then the - matrix will contain only zeros and prime entries; if ``True`` it + - ``fill`` -- boolean (default: ``True``); if ``False`` then the + matrix will contain only zeros and prime entries. If ``True`` it will fill in the other degrees. EXAMPLES:: @@ -341,7 +339,7 @@ def isogenies(self, fill=False): INPUT: - - ``fill`` -- boolean (default ``False``). Whether to only return + - ``fill`` -- boolean (default: ``False``); whether to only return prime degree isogenies. Currently only implemented for ``fill=False``. @@ -501,15 +499,15 @@ def reorder(self, order): INPUT: - - ``order`` -- None, a string or an iterable over all curves - in this class. See + - ``order`` -- ``None``, a string or an iterable over all curves in + this class. See :meth:`sage.schemes.elliptic_curves.ell_rational_field.EllipticCurve_rational_field.isogeny_class` for more details. OUTPUT: - - Another :class:`IsogenyClass_EC` with the curves reordered - (and matrices and maps changed as appropriate) + Another :class:`IsogenyClass_EC` with the curves reordered (and + matrices and maps changed as appropriate). EXAMPLES:: @@ -588,19 +586,18 @@ def __init__(self, E, reducible_primes=None, algorithm='Billerey', minimal_model r""" INPUT: - - ``E`` -- an elliptic curve over a number field. + - ``E`` -- an elliptic curve over a number field - - ``reducible_primes`` (list of ints, or ``None`` (default)) -- if - not ``None`` then this should be a list of primes; in computing - the isogeny class, only composites isogenies of these - degrees will be used. + - ``reducible_primes`` -- list of integers, or ``None`` (default); if + not ``None`` then this should be a list of primes; in computing the + isogeny class, only composites isogenies of these degrees will be used. - - ``algorithm`` (string, default ``'Billerey'``) -- the algorithm + - ``algorithm`` -- string (default: ``'Billerey'``); the algorithm to use to compute the reducible primes. Ignored for CM curves or if ``reducible_primes`` is provided. Values are ``'Billerey'`` (default), ``'Larson'``, and ``'heuristic'``. - - ``minimal_models`` (bool, default ``True``) -- if ``True``, + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves in the class will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -995,23 +992,23 @@ class IsogenyClass_EC_Rational(IsogenyClass_EC_NumberField): r""" Isogeny classes for elliptic curves over `\QQ`. """ - def __init__(self, E, algorithm="sage", label=None, empty=False): + def __init__(self, E, algorithm='sage', label=None, empty=False): r""" INPUT: - - ``E`` -- an elliptic curve over `\QQ`. + - ``E`` -- an elliptic curve over `\QQ` - - ``algorithm`` -- a string (default ``"sage"``). One of the + - ``algorithm`` -- string (default: ``'sage'``); one of the following: - - ``"sage"`` -- Use sage's implementation to compute the curves, + - ``'sage'`` -- use sage's implementation to compute the curves, matrix and isogenies - - ``"database"`` -- Use the Cremona database (only works if the + - ``'database'`` -- use the Cremona database (only works if the curve is in the database) - - ``label`` -- a string, the label of this isogeny class - (e.g. '15a' or '37.b'). Used in printing. + - ``label`` -- string; the label of this isogeny class + (e.g. '15a' or '37.b'), used in printing - ``empty`` -- don't compute the curves right now (used when reordering) @@ -1129,7 +1126,7 @@ def isogeny_degrees_cm(E, verbose=False): INPUT: - - ``E`` -- An elliptic curve defined over a number field. + - ``E`` -- an elliptic curve defined over a number field OUTPUT: @@ -1202,7 +1199,6 @@ def isogeny_degrees_cm(E, verbose=False): sage: from sage.schemes.elliptic_curves.isogeny_class import isogeny_degrees_cm sage: isogeny_degrees_cm(E) [3, 5] - """ if not E.has_cm(): raise ValueError("possible_isogeny_degrees_cm(E) requires E to be an elliptic curve with CM") @@ -1331,24 +1327,24 @@ def possible_isogeny_degrees(E, algorithm='Billerey', max_l=None, INPUT: - - ``E`` -- An elliptic curve defined over a number field. + - ``E`` -- an elliptic curve defined over a number field - - ``algorithm`` (string, default ``'Billerey'``) -- Algorithm to be + - ``algorithm`` -- string (default: ``'Billerey'``); algorithm to be used for non-CM curves: either ``'Billerey'``, ``'Larson'``, or ``'heuristic'``. Only relevant for non-CM curves and base fields other than `\QQ`. - - ``max_l`` (int or ``None``) -- only relevant for non-CM curves + - ``max_l`` -- integer or ``None``; only relevant for non-CM curves and algorithms ``'Billerey'`` and ``'heuristic'``. Controls the maximum prime used in either algorithm. If ``None``, use the default for that algorithm. - - ``num_l`` (int or ``None``) -- only relevant for non-CM curves + - ``num_l`` -- integer or ``None``; only relevant for non-CM curves and algorithm ``'Billerey'``. Controls the maximum number of primes used in the algorithm. If ``None``, use the default for that algorithm. - - ``exact`` (bool, default ``True``) -- if ``True``, perform an + - ``exact`` -- boolean (default: ``True``); if ``True``, perform an additional check that the primes returned are all reducible. If ``False``, skip this step, in which case some of the primes returned may be irreducible. diff --git a/src/sage/schemes/elliptic_curves/isogeny_small_degree.py b/src/sage/schemes/elliptic_curves/isogeny_small_degree.py old mode 100644 new mode 100755 index 9f08f428564..92199fb497e --- a/src/sage/schemes/elliptic_curves/isogeny_small_degree.py +++ b/src/sage/schemes/elliptic_curves/isogeny_small_degree.py @@ -170,10 +170,10 @@ def Psi(l, use_stored=True): INPUT: - - ``l`` -- either 2, 3, 5, 7, or 13. + - ``l`` -- either 2, 3, 5, 7, or 13 - - ``use_stored`` (boolean, default: ``True``) -- If True, use - precomputed values, otherwise compute them on the fly. + - ``use_stored``-- boolean (default: ``True``); if ``True``, use + precomputed values, otherwise compute them on the fly .. NOTE:: @@ -238,11 +238,11 @@ def isogenies_prime_degree_genus_0(E, l=None, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``l`` -- either None or 2, 3, 5, 7, or 13. + - ``l`` -- either ``None`` or 2, 3, 5, 7, or 13 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -373,8 +373,8 @@ def _sporadic_Q_data(j): INPUT: - - ``j`` -- The `j`-invariant of a sporadic curve, i.e. one of the - keys of ``sporadic_j``. + - ``j`` -- the `j`-invariant of a sporadic curve, i.e. one of the + keys of ``sporadic_j`` OUTPUT: @@ -578,9 +578,9 @@ def isogenies_sporadic_Q(E, l=None, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve defined over `\QQ`. + - ``E`` -- an elliptic curve defined over `\QQ` - - ``l`` -- either None or a prime number. + - ``l`` -- either ``None`` or a prime number OUTPUT: @@ -725,9 +725,9 @@ def isogenies_2(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -770,9 +770,9 @@ def isogenies_3(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -820,9 +820,9 @@ def isogenies_5_0(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 0. + - ``E`` -- an elliptic curve with j-invariant 0 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -923,9 +923,9 @@ def isogenies_5_1728(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 1728. + - ``E`` -- an elliptic curve with j-invariant 1728 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -1057,9 +1057,9 @@ def isogenies_7_0(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 0. + - ``E`` -- an elliptic curve with j-invariant 0 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -1197,9 +1197,9 @@ def isogenies_7_1728(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 1728. + - ``E`` -- an elliptic curve with j-invariant 1728 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -1296,9 +1296,9 @@ def isogenies_13_0(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 0. + - ``E`` -- an elliptic curve with j-invariant 0 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -1448,9 +1448,9 @@ def isogenies_13_1728(E, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 1728. + - ``E`` -- an elliptic curve with j-invariant 1728 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -1608,9 +1608,8 @@ def _hyperelliptic_isogeny_data(l): - ``l`` -- a prime in [11, 17, 19, 23, 29, 31, 41, 47, 59, 71] - OUTPUT: - - - A dict holding a collection of precomputed data needed for computing `l`-isogenies. + OUTPUT: a dict holding a collection of precomputed data needed for + computing `l`-isogenies EXAMPLES:: @@ -1750,11 +1749,9 @@ def Psi2(l): INPUT: - - ``l`` -- either 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71. - - OUTPUT: + - ``l`` -- either 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71 - The generic `l`-kernel polynomial. + OUTPUT: the generic `l`-kernel polynomial EXAMPLES:: @@ -1821,11 +1818,11 @@ def isogenies_prime_degree_genus_plus_0(E, l=None, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``l`` -- either None or 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71. + - ``l`` -- either ``None`` or 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -2042,8 +2039,8 @@ def isogenies_prime_degree_genus_plus_0(E, l=None, minimal_models=True): psi = Fxuv(Psi2(l)) for u0, v0 in S: - A4 = Fuv(data['A4'])(u0,v0) #non-zero since j!=0 - A6 = Fuv(data['A6'])(u0,v0) #non-zero since j!=1728 + A4 = Fuv(data['A4'])(u0,v0) # nonzero since j!=0 + A6 = Fuv(data['A6'])(u0,v0) # nonzero since j!=1728 T = (c4*A6)/(2*c6*A4) kernels += [psi((36*X+3*b2)*T,u0,v0).monic()] return [E.isogeny(ker) for ker in kernels] @@ -2055,11 +2052,11 @@ def isogenies_prime_degree_genus_plus_0_j0(E, l, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 0. + - ``E`` -- an elliptic curve with j-invariant 0 - - ``l`` -- 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71. + - ``l`` -- 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -2146,7 +2143,7 @@ def isogenies_prime_degree_genus_plus_0_j0(E, l, minimal_models=True): psi = Fxuv(Psi2(l)) for u0,v0 in S: - A6 = Fuv(data['A6'])(u0,v0) # non-zero since j!=1728 + A6 = Fuv(data['A6'])(u0,v0) # nonzero since j!=1728 kernels += [psi((36*X+3*b2)*T,u0,v0).monic() for T in (X**3-A6/(-54*c6)).roots(multiplicities=False)] return [E.isogeny(ker) for ker in kernels] @@ -2157,11 +2154,11 @@ def isogenies_prime_degree_genus_plus_0_j1728(E, l, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve with j-invariant 1728. + - ``E`` -- an elliptic curve with j-invariant 1728 - - ``l`` -- 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71. + - ``l`` -- 11, 17, 19, 23, 29, 31, 41, 47, 59, or 71 - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -2270,7 +2267,7 @@ def isogenies_prime_degree_genus_plus_0_j1728(E, l, minimal_models=True): psi = Fxuv(Psi2(l)) for u0,v0 in S: - A4 = Fuv(data['A4'])(u0,v0) # non-zero since j!=0 + A4 = Fuv(data['A4'])(u0,v0) # nonzero since j!=0 kernels += [psi((36*X+3*b2)*T,u0,v0).monic() for T in (X**2-A4/(-27*c4)).roots(multiplicities=False)] return [E.isogeny(ker) for ker in kernels] @@ -2282,11 +2279,9 @@ def _least_semi_primitive(p): INPUT: - - ``p`` -- an odd prime power. + - ``p`` -- an odd prime power - OUTPUT: - - the smallest semi-primitive root modulo `p`. + OUTPUT: the smallest semi-primitive root modulo `p` .. NOTE:: @@ -2325,15 +2320,15 @@ def is_kernel_polynomial(E, m, f): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``m`` -- a positive integer. + - ``m`` -- positive integer - - ``f`` -- a polynomial over the base field of ``E``. + - ``f`` -- a polynomial over the base field of ``E`` OUTPUT: - (bool) ``True`` if ``E`` has a cyclic isogeny of degree ``m`` with + boolean; ``True`` if ``E`` has a cyclic isogeny of degree ``m`` with kernel polynomial ``f``, else ``False``. ALGORITHM: @@ -2434,11 +2429,11 @@ def isogenies_prime_degree_general(E, l, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``l`` -- a prime. + - ``l`` -- a prime - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. @@ -2623,19 +2618,17 @@ def isogenies_prime_degree(E, l, minimal_models=True): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``l`` -- a prime. + - ``l`` -- a prime - - ``minimal_models`` (bool, default ``True``) -- if ``True``, all + - ``minimal_models`` -- boolean (default: ``True``); if ``True``, all curves computed will be minimal or semi-minimal models. Over fields of larger degree it can be expensive to compute these so set to ``False``. Ignored except over number fields other than `QQ`. - OUTPUT: - - A list of all separable isogenies of degree `l` with domain ``E``. + OUTPUT: list of all separable isogenies of degree `l` with domain ``E`` EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/jacobian.py b/src/sage/schemes/elliptic_curves/jacobian.py old mode 100644 new mode 100755 index 9099a803afc..8aa868dcc92 --- a/src/sage/schemes/elliptic_curves/jacobian.py +++ b/src/sage/schemes/elliptic_curves/jacobian.py @@ -62,9 +62,9 @@ def Jacobian(X, **kwds): INPUT: - ``X`` -- polynomial, algebraic variety, or anything else that - has a Jacobian elliptic curve. + has a Jacobian elliptic curve - - ``kwds`` -- optional keyword arguments. + - ``kwds`` -- optional keyword arguments The input ``X`` can be one of the following: @@ -118,13 +118,13 @@ def Jacobian(X, **kwds): def Jacobian_of_curve(curve, morphism=False): """ - Return the Jacobian of a genus-one curve + Return the Jacobian of a genus-one curve. INPUT: - - ``curve`` -- a one-dimensional algebraic variety of genus one. + - ``curve`` -- a one-dimensional algebraic variety of genus one - OUTPUT: Its Jacobian elliptic curve. + OUTPUT: its Jacobian elliptic curve EXAMPLES:: @@ -155,7 +155,7 @@ def Jacobian_of_equation(polynomial, variables=None, curve=None): INPUT: - ``F`` -- a polynomial defining a plane curve of genus one. May - be homogeneous or inhomogeneous. + be homogeneous or inhomogeneous - ``variables`` -- list of two or three variables or ``None`` (default). The inhomogeneous or homogeneous coordinates. By diff --git a/src/sage/schemes/elliptic_curves/kodaira_symbol.py b/src/sage/schemes/elliptic_curves/kodaira_symbol.py old mode 100644 new mode 100755 index 8e081e4705a..50f94199a36 --- a/src/sage/schemes/elliptic_curves/kodaira_symbol.py +++ b/src/sage/schemes/elliptic_curves/kodaira_symbol.py @@ -7,7 +7,7 @@ The standard notation for Kodaira Symbols is as a string which is one of `\rm{I}_m`, `\rm{II}`, `\rm{III}`, `\rm{IV}`, `\rm{I}^*_m`, `\rm{II}^*`, `\rm{III}^*`, `\rm{IV}^*`, where `m` denotes a -non-negative integer. These have been encoded by single integers by +nonnegative integer. These have been encoded by single integers by different people. For convenience we give here the conversion table between strings, the eclib coding and the PARI encoding. @@ -80,7 +80,7 @@ def __init__(self, symbol): INPUT: - - ``symbol`` (string or integer) -- The string should be a + - ``symbol`` -- string or integer; the string should be a standard string representation (e.g. III*) of a Kodaira symbol, which will be parsed. Alternatively, use the PARI encoding of Kodaira symbols as integers. @@ -316,7 +316,9 @@ def KodairaSymbol(symbol): INPUT: - - ``symbol`` (string or integer) -- Either a string of the form "I0", "I1", ..., "In", "II", "III", "IV", "I0*", "I1*", ..., "In*", "II*", "III*", or "IV*", or an integer encoding a Kodaira symbol using PARI's conventions. + - ``symbol`` -- string or integer; either a string of the form + "I0", "I1", ..., "In", "II", "III", "IV", "I0*", "I1*", ..., "In*", "II*", "III*", or "IV*", + or an integer encoding a Kodaira symbol using PARI's conventions OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/kraus.py b/src/sage/schemes/elliptic_curves/kraus.py old mode 100644 new mode 100755 index b117e8f7ba7..49dff06b493 --- a/src/sage/schemes/elliptic_curves/kraus.py +++ b/src/sage/schemes/elliptic_curves/kraus.py @@ -108,15 +108,15 @@ def c4c6_model(c4, c6, assume_nonsingular=False): - ``c4``, ``c6`` -- elements of a number field - - ``assume_nonsingular`` (boolean, default ``False``) -- if ``True``, - check for integrality and nosingularity. + - ``assume_nonsingular`` -- boolean (default: ``False``); if ``True``, + check for integrality and nosingularity OUTPUT: The elliptic curve with a-invariants `[0,0,0,-c_4/48,-c_6/864]`, whose c-invariants are the given `c_4`, `c_6`. If the supplied invariants are singular, returns ``None`` when ``assume_nonsingular`` is ``False`` and - raises an :class:`ArithmeticError` otherwise. + raises an :exc:`ArithmeticError` otherwise. EXAMPLES:: @@ -149,7 +149,7 @@ def make_integral(a, P, e): - ``P`` -- a prime ideal of the number field - - ``e`` -- a positive integer + - ``e`` -- positive integer OUTPUT: @@ -364,8 +364,8 @@ def check_Kraus_local_3(c4, c6, P, assume_nonsingular=False, debug=False): - ``P`` -- a prime ideal of the number field which divides 3 - - ``assume_nonsingular`` (boolean, default ``False``) -- if ``True``, - check for integrality and nosingularity. + - ``assume_nonsingular`` -- boolean (default: ``False``); if ``True``, + check for integrality and nosingularity OUTPUT: @@ -591,8 +591,8 @@ def check_Kraus_local_2(c4, c6, P, a1=None, assume_nonsingular=False): - ``a1`` -- an integral elements of a number field, or ``None`` (default) - - ``assume_nonsingular`` (boolean, default ``False``) -- if ``True``, - check for integrality and nonsingularity. + - ``assume_nonsingular`` -- boolean (default: ``False``); if ``True``, + check for integrality and nonsingularity OUTPUT: @@ -681,8 +681,8 @@ def check_Kraus_local(c4, c6, P, assume_nonsingular=False): - ``P`` -- a prime ideal of the number field - - ``assume_nonsingular`` (boolean, default ``False``) -- if ``True``, - check for integrality and nonsingularity. + - ``assume_nonsingular`` -- boolean (default: ``False``); if ``True``, + check for integrality and nonsingularity OUTPUT: @@ -753,8 +753,8 @@ def check_Kraus_global(c4, c6, assume_nonsingular=False, debug=False): - ``c4``, ``c6`` -- elements of a number field - - ``assume_nonsingular`` (boolean, default ``False``) -- if ``True``, - check for integrality and nonsingularity. + - ``assume_nonsingular`` -- boolean (default: ``False``); if ``True``, + check for integrality and nonsingularity OUTPUT: @@ -926,8 +926,8 @@ def semi_global_minimal_model(E, debug=False): - ``E`` -- an elliptic curve over a number field - - ``debug`` (boolean, default ``False``) -- if ``True``, prints some - messages about the progress of the computation. + - ``debug`` -- boolean (default: ``False``); if ``True``, prints some + messages about the progress of the computation OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/lseries_ell.py b/src/sage/schemes/elliptic_curves/lseries_ell.py old mode 100644 new mode 100755 index 30c6456362c..74f5233c0e1 --- a/src/sage/schemes/elliptic_curves/lseries_ell.py +++ b/src/sage/schemes/elliptic_curves/lseries_ell.py @@ -70,9 +70,9 @@ def taylor_series(self, a=1, prec=53, series_prec=6, var='z'): INPUT: - ``a`` -- complex number - - ``prec`` -- integer, precision in bits (default 53) - - ``series_prec`` -- integer (default 6) - - ``var`` -- variable (default 'z') + - ``prec`` -- integer; precision in bits (default: 53) + - ``series_prec`` -- integer (default: 6) + - ``var`` -- variable (default: ``'z'``) EXAMPLES:: @@ -111,25 +111,25 @@ def dokchitser(self, prec=53, INPUT: - - ``prec`` -- optional integer (default 53) bits precision + - ``prec`` -- integer (default: 53); bits precision - - ``max_imaginary_part`` -- optional real number (default 0) + - ``max_imaginary_part`` -- real number (default: 0) - - ``max_asymp_coeffs`` -- optional integer (default 40) + - ``max_asymp_coeffs`` -- integer (default: 40) - - ``algorithm`` -- optional string: 'gp' (default), 'pari' or 'magma' + - ``algorithm`` -- string; ``'gp'`` (default), ``'pari'``, or ``'magma'`` - If algorithm is "gp", this returns an interface to Tim - Dokchitser's program for computing with the L-functions. + If algorithm is ``'gp'``, this returns an interface to Tim + Dokchitser's program for computing with the `L`-functions. If algorithm is "pari", this returns instead an interface to Pari's - own general implementation of L-functions. + own general implementation of `L`-functions. .. NOTE:: If algorithm='magma', then the precision is in digits rather - than bits and the object returned is a Magma L-series, which has - different functionality from the Sage L-series. + than bits and the object returned is a Magma `L`-series, which has + different functionality from the Sage `L`-series. EXAMPLES:: @@ -143,7 +143,7 @@ def dokchitser(self, prec=53, If the curve has too large a conductor, it is not possible to compute with the `L`-series using this command. Instead a - :class:`RuntimeError` is raised:: + :exc:`RuntimeError` is raised:: sage: e = EllipticCurve([1,1,0,-63900,-1964465932632]) sage: L = e.lseries().dokchitser(15, algorithm='gp') @@ -154,7 +154,7 @@ def dokchitser(self, prec=53, Using the "pari" algorithm:: sage: E = EllipticCurve('37a') - sage: L = E.lseries().dokchitser(algorithm="pari") + sage: L = E.lseries().dokchitser(algorithm='pari') sage: L(2) 0.381575408260711 """ @@ -208,9 +208,7 @@ def sympow(self, n, prec): - ``prec`` -- integer - OUTPUT: - - - (string) -- real number to ``prec`` digits of precision as a string. + OUTPUT: string; real number to ``prec`` digits of precision as a string .. NOTE:: @@ -233,20 +231,18 @@ def sympow(self, n, prec): def sympow_derivs(self, n, prec, d): r""" - Return 0-th to `d`-th derivatives of `L( Sym^{(n)}(E, + Return `0`-th to `d`-th derivatives of `L( Sym^{(n)}(E, \text{edge}))` to ``prec`` digits of precision. INPUT: - - n -- integer - - - prec -- integer + - ``n`` -- integer - - d -- integer + - ``prec`` -- integer - OUTPUT: + - ``d`` -- integer - - a string, exactly as output by sympow + OUTPUT: string; exactly as output by sympow .. NOTE:: @@ -379,7 +375,7 @@ def twist_values(self, s, dmin, dmax): .. NOTE:: - The L-series is normalized so that the center of the + The `L`-series is normalized so that the center of the critical strip is 1. INPUT: @@ -432,7 +428,7 @@ def twist_zeros(self, n, dmin, dmax): .. NOTE:: - The L-series is normalized so that the center of the + The `L`-series is normalized so that the center of the critical strip is 1. INPUT: @@ -445,8 +441,8 @@ def twist_zeros(self, n, dmin, dmax): OUTPUT: - - dict -- keys are the discriminants `d`, and - values are list of corresponding zeros. + - ``dict`` -- keys are the discriminants `d`, and + values are list of corresponding zeros EXAMPLES:: @@ -467,11 +463,11 @@ def at1(self, k=None, prec=None): INPUT: - - ``k`` -- number of terms of the series. If zero or ``None``, - use `k = \sqrt{N}`, where `N` is the conductor. + - ``k`` -- number of terms of the series; if zero or ``None``, + use `k = \sqrt{N}`, where `N` is the conductor - - ``prec`` -- numerical precision in bits. If zero or ``None``, - use a reasonable automatic default. + - ``prec`` -- numerical precision in bits; if zero or ``None``, + use a reasonable automatic default OUTPUT: @@ -613,11 +609,11 @@ def deriv_at1(self, k=None, prec=None): INPUT: - - ``k`` -- number of terms of the series. If zero or ``None``, - use `k = \sqrt{N}`, where `N` is the conductor. + - ``k`` -- number of terms of the series; if zero or ``None``, + use `k = \sqrt{N}`, where `N` is the conductor - - ``prec`` -- numerical precision in bits. If zero or ``None``, - use a reasonable automatic default. + - ``prec`` -- numerical precision in bits; if zero or ``None``, + use a reasonable automatic default OUTPUT: @@ -751,7 +747,7 @@ def deriv_at1(self, k=None, prec=None): def __call__(self, s): r""" - Returns the value of the L-series of the elliptic curve E at s, where s + Return the value of the `L`-series of the elliptic curve E at s, where s must be a real number. .. NOTE:: @@ -775,7 +771,7 @@ def __call__(self, s): def L1_vanishes(self): r""" - Returns whether or not `L(E,1) = 0`. The result is provably + Return whether or not `L(E,1) = 0`. The result is provably correct if the Manin constant of the associated optimal quotient is <= 2. This hypothesis on the Manin constant is true for all curves of conductor <= 40000 (by Cremona) and @@ -924,14 +920,12 @@ def zero_sums(self, N=None): INPUT: - - ``N`` -- (default: ``None``) If not ``None``, the conductor of the + - ``N`` -- (default: ``None``) if not ``None``, the conductor of the elliptic curve attached to ``self``. This is passable so that zero sum computations can be done on curves for which the conductor has been precomputed. - OUTPUT: - - A ``LFunctionZeroSum_EllipticCurve`` instance. + OUTPUT: a ``LFunctionZeroSum_EllipticCurve`` instance EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/mod_poly.py b/src/sage/schemes/elliptic_curves/mod_poly.py old mode 100644 new mode 100755 index 58232132421..02ba61efb41 --- a/src/sage/schemes/elliptic_curves/mod_poly.py +++ b/src/sage/schemes/elliptic_curves/mod_poly.py @@ -42,7 +42,7 @@ def classical_modular_polynomial(l, j=None): INPUT: - - ``l`` -- positive integer. + - ``l`` -- positive integer - ``j`` -- either ``None`` or a ring element: * if ``None`` is given, the original modular polynomial diff --git a/src/sage/schemes/elliptic_curves/mod_sym_num.pyx b/src/sage/schemes/elliptic_curves/mod_sym_num.pyx old mode 100644 new mode 100755 index 200651274ea..927df5e5a42 --- a/src/sage/schemes/elliptic_curves/mod_sym_num.pyx +++ b/src/sage/schemes/elliptic_curves/mod_sym_num.pyx @@ -23,8 +23,8 @@ imaginary part of a period on the imaginary axis. The theorem of Manin-Drinfeld shows that the modular symbols are rational numbers with small denominator. They are used for the -computation of special values of the L-function of `E` twisted by -Dirichlet characters and for the computation of `p`-adic L-functions. +computation of special values of the `L`-function of `E` twisted by +Dirichlet characters and for the computation of `p`-adic `L`-functions. ALGORITHM: @@ -61,7 +61,7 @@ The most likely usage for the code is through the functions ``modular_symbol_numerical``:: sage: E = EllipticCurve("5077a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(0) 0 sage: M(1/123) @@ -77,7 +77,7 @@ accessible, too):: sage: E = EllipticCurve([101,103]) sage: E.conductor() 35261176 - sage: M = E.modular_symbol(implementation="num", sign=-1) + sage: M = E.modular_symbol(implementation='num', sign=-1) sage: M Numerical modular symbol attached to Elliptic Curve defined by y^2 = x^3 + 101*x + 103 over Rational Field @@ -127,7 +127,7 @@ very long time to return a value. However it is possible to compute them for smaller conductors:: sage: E = EllipticCurve("664a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(1/2) 0 @@ -136,7 +136,7 @@ can twist to a semistable curve, like in this example:: sage: C = EllipticCurve("11a1") sage: E = C.quadratic_twist(101) - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(1/101) 41 @@ -313,17 +313,19 @@ cdef int proj_normalise(llong N, llong u, llong v, INPUT: - - ``N`` -- an integer (the modulus or level) + - ``N`` -- integer (the modulus or level) - - ``u`` -- an integer (the first coordinate of (u:v)) + - ``u`` -- integer (the first coordinate of (u:v)) - - ``v`` -- an integer (the second coordinate of (u:v)) + - ``v`` -- integer (the second coordinate of (u:v)) - OUTPUT: If gcd(u,v,N) = 1, then returns (in a pointer) + OUTPUT: + + If `\gcd(u,v,N) = 1`, then returns (in a pointer) - - ``uu`` -- an integer + - ``uu`` -- integer - - ``vv`` -- an integer + - ``vv`` -- integer if `\gcd(u,v,N) \not= 1`, returns 0, 0, 0. """ @@ -690,7 +692,7 @@ cdef class ModularSymbolNumerical: INPUT: - - ``E`` -- an elliptic curve over the rational numbers. + - ``E`` -- an elliptic curve over the rational numbers - ``sign`` -- either -1 or +1 (default). This sets the default value of ``sign`` throughout the class. Both are still accessible. @@ -700,14 +702,14 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("5077a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(0) 0 sage: M(77/57) -1 sage: M(33/37, -1) 2 - sage: M = E.modular_symbol(sign=-1, implementation="num") + sage: M = E.modular_symbol(sign=-1, implementation='num') sage: M(2/7) 2 @@ -748,7 +750,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve([1,-1]) - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(12/11) # indirect doctest 1/2 """ @@ -768,7 +770,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("27a1") - sage: M = E. modular_symbol(implementation="num") + sage: M = E. modular_symbol(implementation='num') sage: M(1/9) 1/2 sage: M(1/3) @@ -818,7 +820,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("14a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M Numerical modular symbol attached to Elliptic Curve defined by y^2 + x*y + y = x^3 + 4*x - 6 over Rational Field """ @@ -831,7 +833,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("15a4") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.elliptic_curve() Elliptic Curve defined by y^2 + x*y + y = x^3 + x^2 + 35*x - 28 over Rational Field """ @@ -846,30 +848,30 @@ cdef class ModularSymbolNumerical: - ``r`` -- a rational (or integer) - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken - ``use_twist`` -- boolean (default: ``True``); decides if we - allow to use a quadratic twist. + allow to use a quadratic twist OUTPUT: a rational number EXAMPLES:: sage: E = EllipticCurve("36a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(2/5) -1/3 sage: M(2/5, -1) 1/2 sage: E = EllipticCurve("54a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(5/9) -1/2 sage: E = EllipticCurve("5077a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(234/567) 0 sage: M(112379/43568779) @@ -911,20 +913,20 @@ cdef class ModularSymbolNumerical: - ``r`` -- a rational (or integer) - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken - - ``prec`` -- an integer (default 20) + - ``prec`` -- integer (default: 20) - - ``use_twist`` -- True (default) allows to use a - quadratic twist of the curve to lower the conductor. + - ``use_twist`` -- ``True`` (default) allows to use a + quadratic twist of the curve to lower the conductor OUTPUT: a real number EXAMPLES:: sage: E = EllipticCurve("5077a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.approximative_value(123/567) # abs tol 1e-11 -4.00000000000845 sage: M.approximative_value(123/567,prec=2) # abs tol 1e-9 @@ -933,7 +935,7 @@ cdef class ModularSymbolNumerical: sage: E = EllipticCurve([11,88]) sage: E.conductor() 1715296 - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.approximative_value(0,prec=2) # abs tol 1e-11 -0.0000176374317982166 sage: M.approximative_value(1/7,prec=2) # abs tol 1e-11 @@ -996,7 +998,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("20a2") - sage: M = E.modular_symbol(implementation="num") #indirect doctest + sage: M = E.modular_symbol(implementation='num') #indirect doctest """ self._epsQs = {d: prod(self._E.root_number(p) for p in d.prime_divisors()) @@ -1017,7 +1019,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("240b3") - sage: M = E.modular_symbol(implementation="num") #indirect doctest + sage: M = E.modular_symbol(implementation='num') #indirect doctest """ from sage.databases.cremona import CremonaDatabase @@ -1152,7 +1154,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve("63a2") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(3/4, use_twist=True) # indirect doctest -1 """ @@ -1212,9 +1214,9 @@ cdef class ModularSymbolNumerical: - ``sign`` -- either +1 or -1 - - ``unitary`` -- a boolean (int) + - ``unitary`` -- boolean (int) - OUTPUT: a rational. + OUTPUT: a rational EXAMPLES:: @@ -1268,7 +1270,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve([-11,13]) - sage: M = E.modular_symbol(implementation="num") #indirect doctest + sage: M = E.modular_symbol(implementation='num') #indirect doctest """ cdef int n # verbose(" enter _initialise_an_coeffients", level=5) @@ -1293,7 +1295,7 @@ cdef class ModularSymbolNumerical: INPUT: - - ``T`` -- an integer + - ``T`` -- integer EXAMPLES:: @@ -1346,12 +1348,12 @@ cdef class ModularSymbolNumerical: def clear_cache(self): r""" - Clear the cached values in all methods of this class + Clear the cached values in all methods of this class. EXAMPLES:: sage: E = EllipticCurve("11a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(0) 1/5 sage: M.clear_cache() @@ -1376,15 +1378,13 @@ cdef class ModularSymbolNumerical: - ``tau`` -- a point in the upper half plane - - ``number_of_terms`` -- an integer describing + - ``number_of_terms`` -- integer describing how many terms to sum - - ``prec`` -- an integer, setting the precision + - ``prec`` -- integer; setting the precision to ``prec`` bits in all of the computation - OUTPUT: - - - a complex number + OUTPUT: a complex number EXAMPLES:: @@ -1450,12 +1450,10 @@ cdef class ModularSymbolNumerical: - ``tau`` -- a point in the upper half plane - - ``number_of_terms`` -- an integer describing + - ``number_of_terms`` -- integer describing how many terms to sum - OUTPUT: - - - a complex number + OUTPUT: a complex number EXAMPLES:: @@ -1508,12 +1506,12 @@ cdef class ModularSymbolNumerical: - ``y`` -- a positive real number - - ``m`` -- an integer + - ``m`` -- integer - - ``number_of_terms`` -- an integer describing + - ``number_of_terms`` -- integer describing how many terms to sum - OUTPUT: a list of real numbers (in a pointer) + OUTPUT: list of real numbers (in a pointer) EXAMPLES:: @@ -1578,15 +1576,15 @@ cdef class ModularSymbolNumerical: - ``y`` -- a positive real number - - ``m`` -- an integer + - ``m`` -- integer - - ``number_of_terms`` -- an integer describing + - ``number_of_terms`` -- integer describing how many terms to sum - - ``prec`` -- an integer, setting the precision + - ``prec`` -- integer setting the precision to ``prec`` bits in all of the computation - OUTPUT: a list of real numbers + OUTPUT: list of real numbers EXAMPLES:: @@ -1661,9 +1659,7 @@ cdef class ModularSymbolNumerical: - ``eps`` -- a positive real number, the maximal allowed error - OUTPUT: - - two integers `T` and `b` + OUTPUT: two integers `T` and `b` If `T` would be larger than `2^31`, the value (-1,-1) is returned instead. @@ -1768,22 +1764,22 @@ cdef class ModularSymbolNumerical: INPUT: - - ``m`` -- an integer (long long) + - ``m`` -- integer (long long) - ``z`` -- another integer (long long) - - ``eps`` -- either None (default) or a real number (double), + - ``eps`` -- either ``None`` (default) or a real number (double), describing the precision to which the terms are computed. - Each term is off by less than ``eps``/``m``. If None, the + Each term is off by less than ``eps``/``m``. If ``None``, the ``eps`` is chosen from the precomputed precision related to the periods. - OUTPUT: a list of `m` real numbers + OUTPUT: list of `m` real numbers EXAMPLES:: sage: E = EllipticCurve("43a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M._kappa(3,4) # abs tol 1e-11 [-5.379533671373222e-05, 0.043215661934968536, -0.0018675632930897528] sage: M._kappa(3,17) # abs tol 1e-11 @@ -1880,7 +1876,7 @@ cdef class ModularSymbolNumerical: INPUT: - - ```r`` -- a rational number + - ``r`` -- a rational number - ``eps`` -- a positive real number @@ -2024,11 +2020,11 @@ cdef class ModularSymbolNumerical: - ``r``, ``rr`` -- two Rationals - - ``espQ`` and ``espQ`` -- two Integers + - ``espQ``, ``espQ`` -- two Integers - - `` T `` and ``prec`` -- two ints + - ``T``, ``prec`` -- two ints - - `` use_partials -- int: 0 don't use partials, + - ``use_partials`` -- int: 0 don't use partials, 1 use them, 2 (default) decide if meaningful OUTPUT: a complex number @@ -2166,10 +2162,10 @@ cdef class ModularSymbolNumerical: - ``eps`` -- a positive real number - - ``method`` -- a string or None: either "direct", "indirect", - "both". When method is not given (default), then the better - of the two is chosen. "both" raises an error if the two - methods differ by more than ``eps``. + - ``method`` -- string or ``None``: either ``'direct'``, + ``'indirect'``, or ``'both'``. When method is not given (default), + then the better of the two is chosen. ``'both'`` raises an error if + the two methods differ by more than ``eps``. - ``use_partials`` -- int: 0 don't use partials, 1 use them, 2 (default) decide if meaningful @@ -2477,28 +2473,28 @@ cdef class ModularSymbolNumerical: - ``r`` -- a rational number, which has to be a unitary cusp - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken - - ``use_partials`` -- integer: 0 don't use partial summation to do + - ``use_partials`` -- integer; 0 don't use partial summation to do the computation, 1 do use them, 2 (default) decide if it is - meaningful to do so. + meaningful to do so - OUTPUT: a rational number. + OUTPUT: a rational number EXAMPLES:: sage: from sage.schemes.elliptic_curves.mod_sym_num \ ....: import ModularSymbolNumerical sage: E = EllipticCurve("11a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M._value_ioo_to_r(0/1) 1/5 sage: M._value_ioo_to_r(3/11,-1) 1/2 sage: E = EllipticCurve("5077a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M._value_ioo_to_r(0/1) 0 sage: M._value_ioo_to_r(123/456) @@ -2536,15 +2532,15 @@ cdef class ModularSymbolNumerical: INPUT: - - ``r`` and ``rr`` -- two rational number, both have to be - uniraty cusps. + - ``r``, ``rr`` -- two rational numbers, both have to be + unitary cusps - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken - - ``use_partials`` -- integer: 0 don't use partial summation to do + - ``use_partials`` -- integer; 0 don't use partial summation to do the computation, 1 do use them, 2 (default) decide if it is - meaningful to do so. + meaningful to do so OUTPUT: a rational number @@ -2553,7 +2549,7 @@ cdef class ModularSymbolNumerical: sage: from sage.schemes.elliptic_curves.mod_sym_num \ ....: import ModularSymbolNumerical sage: E = EllipticCurve("57a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M._value_r_to_rr(0/1,8/9) 0 sage: M._value_r_to_rr(0/1,8/9,use_partials=0) @@ -2570,7 +2566,7 @@ cdef class ModularSymbolNumerical: 55196272 sage: E.conductor().factor() 2^4 * 3449767 - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M._value_r_to_rr(0/1,4/5) 1 sage: M._value_r_to_rr(7/11,14/75) # long time @@ -2606,29 +2602,29 @@ cdef class ModularSymbolNumerical: INPUT: - - ``r`` and ``rr`` -- two rational numbers + - ``r``, ``rr`` -- two rational numbers - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken OUTPUT: a rational number EXAMPLES:: sage: E = EllipticCurve("11a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.transportable_symbol(0/1,-2/7) -1/2 sage: E = EllipticCurve("37a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.transportable_symbol(0/1,-1/19) 0 sage: M.transportable_symbol(0/1,-1/19,-1) 0 sage: E = EllipticCurve("5077a1") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.transportable_symbol(0/1,-35/144) -3 sage: M.transportable_symbol(0/1,-35/144,-1) @@ -2671,8 +2667,8 @@ cdef class ModularSymbolNumerical: - ``r`` -- a rational number representing a unitary cusp - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken OUTPUT: a rational number @@ -2860,18 +2856,18 @@ cdef class ModularSymbolNumerical: INPUT: - - ``u`` -- an integer + - ``u`` -- integer - - ``v`` -- an integer such that `(u:v)` is a projective point + - ``v`` -- integer such that `(u:v)` is a projective point modulo `N` - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken EXAMPLES:: sage: E = EllipticCurve('11a1') - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.manin_symbol(1,3) -1/2 sage: M.manin_symbol(1,3, sign=-1) @@ -2882,7 +2878,7 @@ cdef class ModularSymbolNumerical: 1 sage: E = EllipticCurve('14a1') - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.manin_symbol(1,2) -1/2 sage: M.manin_symbol(17,6) @@ -2992,8 +2988,8 @@ cdef class ModularSymbolNumerical: - ``r`` -- a rational number representing a unitary cusp - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken OUTPUT: a rational number @@ -3127,8 +3123,8 @@ cdef class ModularSymbolNumerical: - ``m`` -- a natural number - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken OUTPUT: a dictionary of fractions with denominator `m` giving rational numbers. @@ -3136,7 +3132,7 @@ cdef class ModularSymbolNumerical: EXAMPLES:: sage: E = EllipticCurve('5077a1') - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.all_values_for_one_denominator(7) {1/7: 3, 2/7: 0, 3/7: -3, 4/7: -3, 5/7: 0, 6/7: 3} sage: [M(a/7) for a in [1..6]] @@ -3145,14 +3141,14 @@ cdef class ModularSymbolNumerical: {1/3: 4, 2/3: -4} sage: E = EllipticCurve('11a1') - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.all_values_for_one_denominator(12) {1/12: 1/5, 5/12: -23/10, 7/12: -23/10, 11/12: 1/5} sage: M.all_values_for_one_denominator(12, -1) {1/12: 0, 5/12: 1/2, 7/12: -1/2, 11/12: 0} sage: E = EllipticCurve('20a1') - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.all_values_for_one_denominator(4) {1/4: 0, 3/4: 0} sage: M.all_values_for_one_denominator(8) @@ -3227,15 +3223,15 @@ cdef class ModularSymbolNumerical: - ``ra`` -- a rational number - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken OUTPUT: a rational number EXAMPLES:: sage: E = EllipticCurve("735e4") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M(1/19, sign=-1, use_twist=False) #indirect doctest 4 sage: M(1/19, sign=-1, use_twist=True) @@ -3455,17 +3451,17 @@ cdef class ModularSymbolNumerical: - ``ra`` -- a rational number - - ``sign`` -- optional either +1 or -1, or 0 (default), - in which case the sign passed to the class is taken. + - ``sign`` -- either +1 or -1, or 0 (default), + in which case the sign passed to the class is taken - - ``prec`` -- an integer (default 20) + - ``prec`` -- integer (default: 20) OUTPUT: a real number EXAMPLES:: sage: E = EllipticCurve("735e4") - sage: M = E.modular_symbol(implementation="num") + sage: M = E.modular_symbol(implementation='num') sage: M.approximative_value(1/19, sign=-1, prec=20, use_twist=False) # indirect doctest abs tol 1e-11 4.00000000089736 sage: M.approximative_value(1/19, sign=-1, prec=20, use_twist=True) # abs tol 1e-11 @@ -3622,10 +3618,10 @@ def _test_integration(E, a, b, T): - ``E`` -- an elliptic curve - - ``a`` and ``b`` -- two real numbers representing real and + - ``a``, ``b`` -- two real numbers representing real and imaginary part of a complex number tau - - ``T `` -- an integer for the number of terms to use + - ``T `` -- integer for the number of terms to use OUTPUT: a complex number @@ -3665,11 +3661,11 @@ def _test_integration_via_partials(E, y, m, T): - ``y`` -- a real number - - ``m`` -- an integers + - ``m`` -- integer - - ``T `` -- an integer for the number of terms to use + - ``T `` -- integer for the number of terms to use - OUTPUT: a list of `m` real numbers + OUTPUT: list of `m` real numbers EXAMPLES:: @@ -3697,7 +3693,7 @@ def _test_integration_via_partials(E, y, m, T): return res -def _test_against_table(range_of_conductors, other_implementation="sage", list_of_cusps=None, verb=False): +def _test_against_table(range_of_conductors, other_implementation='sage', list_of_cusps=None, verb=False): r""" This test function checks the modular symbols here against the ones implemented already. Note that for some curves the current @@ -3706,14 +3702,14 @@ def _test_against_table(range_of_conductors, other_implementation="sage", list_o INPUT: - - ``range_of_conductors`` -- a list of integers; all curves with - conductors in that list will be tested. + - ``range_of_conductors`` -- list of integers; all curves with + conductors in that list will be tested - - ``list_of_cusps`` -- a list of rationals to be tested + - ``list_of_cusps`` -- list of rationals to be tested - ``verb`` -- if ``True`` (default) prints the values - OUTPUT: Boolean. If ``False`` the function also prints information. + OUTPUT: boolean; if ``False`` the function also prints information EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/modular_parametrization.py b/src/sage/schemes/elliptic_curves/modular_parametrization.py old mode 100644 new mode 100755 index 6ff558a0db0..2df0d64f5cc --- a/src/sage/schemes/elliptic_curves/modular_parametrization.py +++ b/src/sage/schemes/elliptic_curves/modular_parametrization.py @@ -112,7 +112,7 @@ def __repr__(self): def __eq__(self, other): r""" - Compares two modular parametrizations by simply comparing the elliptic curves. + Compare two modular parametrizations by simply comparing the elliptic curves. EXAMPLES:: @@ -253,7 +253,9 @@ def power_series(self, prec=20): the number of significant terms. This means that X will be given up to O(q^(prec-2)) and Y will be given up to O(q^(prec-3)). - OUTPUT: A list of two Laurent series ``[X(x),Y(x)]`` of degrees -2, -3 + OUTPUT: + + A list of two Laurent series [`X(x)`,`Y(x)`] of degrees `-2`, `-3`, respectively, which satisfy the equation of the elliptic curve. There are modular functions on `\Gamma_0(N)` where `N` is the conductor. diff --git a/src/sage/schemes/elliptic_curves/padic_lseries.py b/src/sage/schemes/elliptic_curves/padic_lseries.py old mode 100644 new mode 100755 index d29be405854..4721ef67951 --- a/src/sage/schemes/elliptic_curves/padic_lseries.py +++ b/src/sage/schemes/elliptic_curves/padic_lseries.py @@ -3,7 +3,7 @@ `p`-adic `L`-functions of elliptic curves To an elliptic curve `E` over the rational numbers and a prime `p`, one -can associate a `p`-adic L-function; at least if `E` does not have additive +can associate a `p`-adic `L`-function; at least if `E` does not have additive reduction at `p`. This function is defined by interpolation of L-values of `E` at twists. Through the main conjecture of Iwasawa theory it should also be equal to a characteristic series of a certain Selmer group. @@ -17,15 +17,15 @@ One can decompose this algebra as the direct product of the subalgebras corresponding to the characters of `\Delta`, which are simply the powers `\tau^\eta` (`0 \le \eta \le p-2`) of the Teichmueller character `\tau: \Delta -\to \ZZ_p^\times`. Projecting the L-function into these components gives `p-1` +\to \ZZ_p^\times`. Projecting the `L`-function into these components gives `p-1` power series in `T`, each with coefficients in `\ZZ_p`. If `E` is supersingular, the series will have coefficients in a quadratic extension of `\QQ_p`, and the coefficients will be unbounded. In this case we have only implemented the series for `\eta = 0`. We have also implemented the -`p`-adic L-series as formulated by Perrin-Riou [BP1993]_, which has coefficients in -the Dieudonné module `D_pE = H^1_{dR}(E/\QQ_p)` of `E`. There is a different -description by Pollack [Pol2003]_ which is not available here. +`p`-adic `L`-series as formulated by Perrin-Riou [BP1993]_, which has +coefficients in the Dieudonné module `D_pE = H^1_{dR}(E/\QQ_p)` of `E`. There +is a different description by Pollack [Pol2003]_ which is not available here. According to the `p`-adic version of the Birch and Swinnerton-Dyer conjecture [MTT1986]_, the order of vanishing of the `L`-function at the trivial character @@ -93,7 +93,7 @@ @richcmp_method class pAdicLseries(SageObject): r""" - The `p`-adic L-series of an elliptic curve. + The `p`-adic `L`-series of an elliptic curve. EXAMPLES: @@ -156,14 +156,13 @@ def __init__(self, E, p, implementation='eclib', normalize='L_ratio'): - ``E`` -- an elliptic curve - ``p`` -- a prime of good reduction - - ``implementation`` -- string (default: 'eclib'); either 'eclib' to use - John Cremona's ``eclib`` for the computation of modular - symbols, 'num' to use numerical modular symbols - or 'sage' to use Sage's own implementation + - ``implementation`` -- string (default: ``'eclib'``); either + ``'eclib'`` to use John Cremona's ``eclib`` for the computation of + modular symbols, 'num' to use numerical modular symbols or ``'sage'`` + to use Sage's own implementation - ``normalize`` -- ``'L_ratio'`` (default), ``'period'`` or ``'none'``; - this is describes the way the modular symbols - are normalized. See ``modular_symbol`` of - an elliptic curve over Q for more details. + this is describes the way the modular symbols are normalized. See + ``modular_symbol`` of an elliptic curve over Q for more details. EXAMPLES:: @@ -207,7 +206,7 @@ def __add_negative_space(self): sage: lp.modular_symbol(1/7,sign=-1) #indirect doctest -1/2 """ - self._negative_modular_symbol = self._E.modular_symbol(sign=-1, implementation="sage", normalize=self._normalize) + self._negative_modular_symbol = self._E.modular_symbol(sign=-1, implementation='sage', normalize=self._normalize) def __richcmp__(self, other, op): r""" @@ -231,7 +230,7 @@ def __richcmp__(self, other, op): def elliptic_curve(self): r""" - Return the elliptic curve to which this `p`-adic L-series is associated. + Return the elliptic curve to which this `p`-adic `L`-series is associated. EXAMPLES:: @@ -243,7 +242,7 @@ def elliptic_curve(self): def prime(self): r""" - Return the prime `p` as in 'p-adic L-function'. + Return the prime `p` as in `p`-adic `L`-function'. EXAMPLES:: @@ -278,7 +277,7 @@ def modular_symbol(self, r, sign=+1, quadratic_twist=+1): r""" Return the modular symbol evaluated at `r`. - This is used to compute this `p`-adic L-series. + This is used to compute this `p`-adic `L`-series. Note that the normalization is not correct at this stage: use ``_quotient_of periods_to_twist`` to correct. @@ -353,7 +352,7 @@ def measure(self, a, n, prec, quadratic_twist=+1, sign=+1): \frac{1}{\alpha^{n+1}} \left[\frac{a}{p^{n-1}}\right]^{+}` where `[\cdot]^{+}` is the modular symbol. This is used to define - this `p`-adic L-function (at least when the reduction is good). + this `p`-adic `L`-function (at least when the reduction is good). The optional argument ``sign`` allows the minus symbol `[\cdot]^{-}` to be substituted for the plus symbol. @@ -375,16 +374,16 @@ def measure(self, a, n, prec, quadratic_twist=+1, sign=+1): INPUT: - - ``a`` -- an integer + - ``a`` -- integer - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer - - ``prec`` -- an integer + - ``prec`` -- integer - - ``quadratic_twist`` (default = 1) -- a fundamental discriminant of a quadratic field, - should be coprime to the conductor of `E` + - ``quadratic_twist`` -- (default: 1) a fundamental discriminant of a + quadratic field, should be coprime to the conductor of `E` - - ``sign`` (default = 1) -- an integer, which should be `\pm 1`. + - ``sign`` -- integer (default: 1) which should be `\pm 1` EXAMPLES:: @@ -456,7 +455,7 @@ def alpha(self, prec=20): INPUT: - - ``prec`` -- positive integer, the `p`-adic precision of the root. + - ``prec`` -- positive integer; the `p`-adic precision of the root EXAMPLES: @@ -513,14 +512,14 @@ def alpha(self, prec=20): raise RuntimeError("bug in p-adic L-function alpha") else: # supersingular case f = f.change_ring(K) - A = K.extension(f, names="alpha") + A = K.extension(f, names='alpha') a = A.gen() self._alpha[prec] = a return a def order_of_vanishing(self): r""" - Return the order of vanishing of this `p`-adic L-series. + Return the order of vanishing of this `p`-adic `L`-series. The output of this function is provably correct, due to a theorem of Kato [Kat2004]_. @@ -588,11 +587,9 @@ def teichmuller(self, prec): INPUT: - - ``prec`` -- a positive integer. + - ``prec`` -- positive integer - OUTPUT: - - - a list of `p`-adic numbers, the cached Teichmuller lifts + OUTPUT: list of `p`-adic numbers; the cached Teichmuller lifts EXAMPLES:: @@ -743,13 +740,13 @@ def _quotient_of_periods_to_twist(self, D): class pAdicLseriesOrdinary(pAdicLseries): def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): r""" - Return the `n`-th approximation to the `p`-adic L-series, in the + Return the `n`-th approximation to the `p`-adic `L`-series, in the component corresponding to the `\eta`-th power of the Teichmueller character, as a power series in `T` (corresponding to `\gamma-1` with `\gamma=1+p` as a generator of `1+p\ZZ_p`). Each coefficient is a `p`-adic number whose precision is provably correct. - Here the normalization of the `p`-adic L-series is chosen + Here the normalization of the `p`-adic `L`-series is chosen such that `L_p(E,1) = (1-1/\alpha)^2 L(E,1)/\Omega_E` where `\alpha` is the unit root of the characteristic polynomial of Frobenius on `T_pE` and `\Omega_E` is the @@ -763,7 +760,7 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): - ``prec`` -- (default: 5) maximal number of terms of the series to compute; to compute as many as possible just give a very large number for ``prec``; the result will still be correct. - - ``eta`` (default: 0) an integer (specifying the power of the + - ``eta`` -- (default: 0) an integer (specifying the power of the Teichmueller character on the group of roots of unity in `\ZZ_p^\times`) @@ -771,7 +768,7 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): EXAMPLES: - We compute some `p`-adic L-functions associated to the elliptic + We compute some `p`-adic `L`-functions associated to the elliptic curve 11a:: sage: E = EllipticCurve('11a') @@ -783,8 +780,8 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): 2 + 3 + 3^2 + 2*3^3 + O(3^5) + (1 + 3 + O(3^2))*T + (1 + 2*3 + O(3^2))*T^2 + O(3)*T^3 + O(3)*T^4 + O(T^5) Another example at a prime of bad reduction, where the - `p`-adic L-function has an extra 0 (compared to the non - `p`-adic L-function):: + `p`-adic `L`-function has an extra 0 (compared to the non + `p`-adic `L`-function):: sage: E = EllipticCurve('11a') sage: p = 11 @@ -794,7 +791,7 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): sage: L.series(2) O(11^4) + (10 + O(11))*T + (6 + O(11))*T^2 + (2 + O(11))*T^3 + (5 + O(11))*T^4 + O(T^5) - We compute a `p`-adic L-function that vanishes to order 2:: + We compute a `p`-adic `L`-function that vanishes to order 2:: sage: E = EllipticCurve('389a') sage: p = 3 @@ -815,7 +812,7 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): sage: L.series(3,prec=6) O(3^5) + O(3^2)*T + (2 + 2*3 + O(3^2))*T^2 + (2 + O(3))*T^3 + (1 + O(3))*T^4 + (1 + O(3))*T^5 + O(T^6) - Rather than computing the `p`-adic L-function for the curve '15523a1', one can + Rather than computing the `p`-adic `L`-function for the curve '15523a1', one can compute it as a quadratic_twist:: sage: E = EllipticCurve('43a1') @@ -829,7 +826,7 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): We calculate the `L`-series in the nontrivial Teichmueller components:: - sage: L = EllipticCurve('110a1').padic_lseries(5, implementation="sage") + sage: L = EllipticCurve('110a1').padic_lseries(5, implementation='sage') sage: for j in [0..3]: print(L.series(4, eta=j)) O(5^6) + (2 + 2*5 + 2*5^2 + O(5^3))*T + (5 + 5^2 + O(5^3))*T^2 + (4 + 4*5 + 2*5^2 + O(5^3))*T^3 + (1 + 5 + 3*5^2 + O(5^3))*T^4 + O(T^5) 4 + 3*5 + 2*5^2 + 3*5^3 + 5^4 + O(5^6) + (1 + 3*5 + 4*5^2 + O(5^3))*T + (3 + 4*5 + 3*5^2 + O(5^3))*T^2 + (3 + 3*5^2 + O(5^3))*T^3 + (1 + 2*5 + 2*5^2 + O(5^3))*T^4 + O(T^5) @@ -851,11 +848,11 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): Check that twists by odd Teichmuller characters are ok (:issue:`32258`):: sage: E = EllipticCurve("443c1") - sage: lp = E.padic_lseries(17, implementation="num") + sage: lp = E.padic_lseries(17, implementation='num') sage: l8 = lp.series(2,eta=8,prec=3) sage: l8.list()[0] - 1/lp.alpha() O(17^4) - sage: lp = E.padic_lseries(2, implementation="num") + sage: lp = E.padic_lseries(2, implementation='num') sage: l1 = lp.series(8,eta=1,prec=3) sage: l1.list()[0] - 4/lp.alpha()^2 O(2^9) @@ -986,7 +983,7 @@ def series(self, n=2, quadratic_twist=+1, prec=5, eta=0): def is_ordinary(self): r""" - Return ``True`` if the elliptic curve that this L-function is attached + Return ``True`` if the elliptic curve that this `L`-function is attached to is ordinary. EXAMPLES:: @@ -1036,11 +1033,11 @@ def _c_bound(self, sign=+1): 0 sage: EllipticCurve('11a3').padic_lseries(5)._c_bound() 2 - sage: EllipticCurve('11a3').padic_lseries(5, implementation="sage")._c_bound() + sage: EllipticCurve('11a3').padic_lseries(5, implementation='sage')._c_bound() 2 sage: EllipticCurve('50b1').padic_lseries(3)._c_bound() 0 - sage: EllipticCurve('50b1').padic_lseries(3, implementation="sage")._c_bound() + sage: EllipticCurve('50b1').padic_lseries(3, implementation='sage')._c_bound() 1 sage: l = EllipticCurve("11a1").padic_lseries(5) sage: ls = l.series(1,eta=1); @@ -1122,7 +1119,7 @@ def _prec_bounds(self, n, prec, sign=+1): A helper function not designed for direct use. It returns the `p`-adic precisions of the approximation - to the `p`-adic L-function. + to the `p`-adic `L`-function. EXAMPLES:: @@ -1152,13 +1149,13 @@ def _prec_bounds(self, n, prec, sign=+1): class pAdicLseriesSupersingular(pAdicLseries): def series(self, n=3, quadratic_twist=+1, prec=5, eta=0): r""" - Return the `n`-th approximation to the `p`-adic L-series as a + Return the `n`-th approximation to the `p`-adic `L`-series as a power series in `T` (corresponding to `\gamma-1` with `\gamma=1+p` as a generator of `1+p\ZZ_p`). Each coefficient is an element of a quadratic extension of the `p`-adic number whose precision is provably correct. - Here the normalization of the `p`-adic L-series is chosen + Here the normalization of the `p`-adic `L`-series is chosen such that `L_p(E,1) = (1-1/\alpha)^2 L(E,1)/\Omega_E` where `\alpha` is a root of the characteristic polynomial of Frobenius on `T_pE` and `\Omega_E` is the @@ -1172,7 +1169,7 @@ def series(self, n=3, quadratic_twist=+1, prec=5, eta=0): - ``prec`` -- (default: 5) maximal number of terms of the series to compute; to compute as many as possible just give a very large number for ``prec``; the result will still be correct. - - ``eta`` (default: 0) an integer (specifying the power of the + - ``eta`` -- (default: 0) an integer (specifying the power of the Teichmueller character on the group of roots of unity in `\ZZ_p^\times`) @@ -1326,7 +1323,7 @@ def series(self, n=3, quadratic_twist=+1, prec=5, eta=0): def is_ordinary(self): r""" - Return ``True`` if the elliptic curve that this L-function is attached + Return ``True`` if the elliptic curve that this `L`-function is attached to is ordinary. EXAMPLES:: @@ -1355,7 +1352,7 @@ def _prec_bounds(self, n, prec): A helper function not designed for direct use. It returns the `\alpha`-adic precisions of the approximation - to the `p`-adic L-function. + to the `p`-adic `L`-function. EXAMPLES:: @@ -1406,7 +1403,7 @@ def _poly(self, a): def Dp_valued_series(self, n=3, quadratic_twist=+1, prec=5): r""" - Return a vector of two components which are p-adic power series. + Return a vector of two components which are `p`-adic power series. The answer v is such that @@ -1456,7 +1453,7 @@ def Dp_valued_series(self, n=3, quadratic_twist=+1, prec=5): resu = lpv * eps.transpose() return resu - def frobenius(self, prec=20, algorithm="mw"): + def frobenius(self, prec=20, algorithm='mw'): r""" Return a geometric Frobenius `\varphi` on the Dieudonné module `D_p(E)` with respect to the basis `\omega`, the invariant differential, and `\eta=x\omega`. @@ -1537,16 +1534,16 @@ def __phi_bpr(self, prec=0): sage: E = EllipticCurve('11a1') sage: lp = E.padic_lseries(19) - sage: lp.frobenius(prec=1,algorithm="approx") #indirect doctest + sage: lp.frobenius(prec=1,algorithm='approx') #indirect doctest [ O(19^0) 4*19^-1 + O(19^0)] [ 14 + O(19) O(19^0)] sage: E = EllipticCurve('17a1') sage: lp = E.padic_lseries(3) - sage: lp.frobenius(prec=3,algorithm="approx") + sage: lp.frobenius(prec=3,algorithm='approx') [ O(3) 2*3^-1 + 2 + O(3)] [ 1 + O(3^2) O(3)] - sage: lp.frobenius(prec=5,algorithm="approx") + sage: lp.frobenius(prec=5,algorithm='approx') [ 3 + O(3^2) 2*3^-1 + 2 + 3 + O(3^2)] [ 1 + 2*3^2 + O(3^3) 2*3 + O(3^2)] """ @@ -1774,9 +1771,9 @@ def Dp_pairing(vec1,vec2): reg_oe = (reg1 * v2 - reg2 * v1 ) / Dp_pairing(v2, v1) if p < 5: - phi = self.frobenius(min(6, prec), algorithm="approx") + phi = self.frobenius(min(6, prec), algorithm='approx') else: - phi = self.frobenius(prec + 2, algorithm="mw") + phi = self.frobenius(prec + 2, algorithm='mw') c = phi[1, 0] # this is the 'period' [omega,phi(omega)] a = phi[0, 0] diff --git a/src/sage/schemes/elliptic_curves/padics.py b/src/sage/schemes/elliptic_curves/padics.py old mode 100644 new mode 100755 index a5e9a4e4a65..624b3a11e7d --- a/src/sage/schemes/elliptic_curves/padics.py +++ b/src/sage/schemes/elliptic_curves/padics.py @@ -63,7 +63,6 @@ def __check_padic_hypotheses(self, p): Traceback (most recent call last): ... ArithmeticError: p must be a good ordinary prime - """ p = Integer(p) if not p.is_prime(): @@ -110,7 +109,7 @@ def _normalize_padic_lseries(self, p, normalize, implementation, precision): def padic_lseries(self, p, normalize=None, implementation='eclib', precision=None): r""" - Return the `p`-adic `L`-series of self at + Return the `p`-adic `L`-series of ``self`` at `p`, which is an object whose approx method computes approximation to the true `p`-adic `L`-series to any desired precision. @@ -190,7 +189,7 @@ def padic_lseries(self, p, normalize=None, implementation='eclib', This may allow for much larger conductor in some instances:: sage: E = EllipticCurve([101,103]) - sage: L = E.padic_lseries(5, implementation="num") + sage: L = E.padic_lseries(5, implementation='num') sage: L.series(2) O(5^4) + (3 + O(5))*T + (1 + O(5))*T^2 + (3 + O(5))*T^3 + O(5)*T^4 + O(T^5) @@ -243,17 +242,16 @@ def padic_regulator(self, p, prec=20, height=None, check_hypotheses=True): - ``p`` -- prime >= 5 - - ``prec`` -- answer will be returned modulo - `p^{\mathrm{prec}}` + - ``prec`` -- answer will be returned modulo `p^{\mathrm{prec}}` - - ``height`` -- precomputed height function. If not - supplied, this function will call padic_height to compute it. + - ``height`` -- precomputed height function; if not supplied, this function + will call ``padic_height`` to compute it - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic height makes sense + - ``check_hypotheses`` -- boolean; whether to check + that this is a curve for which the `p`-adic height makes sense - OUTPUT: The `p`-adic cyclotomic regulator of this curve, to the - requested precision. + OUTPUT: the `p`-adic cyclotomic regulator of this curve, to the + requested precision If the rank is 0, we output 1. @@ -343,7 +341,7 @@ def padic_regulator(self, p, prec=20, height=None, check_hypotheses=True): def padic_height_pairing_matrix(self, p, prec=20, height=None, check_hypotheses=True): r""" - Computes the cyclotomic `p`-adic height pairing matrix of + Compute the cyclotomic `p`-adic height pairing matrix of this curve with respect to the basis ``self.gens()`` for the Mordell-Weil group for a given odd prime `p` of good ordinary reduction. @@ -353,17 +351,16 @@ def padic_height_pairing_matrix(self, p, prec=20, height=None, check_hypotheses= - ``p`` -- prime >= 5 - - ``prec`` -- answer will be returned modulo - `p^{\mathrm{prec}}` + - ``prec`` -- answer will be returned modulo `p^{\mathrm{prec}}` - - ``height`` -- precomputed height function. If not - supplied, this function will call padic_height to compute it. + - ``height`` -- precomputed height function; if not supplied, this function + will call ``padic_height`` to compute it - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic height makes sense + - ``check_hypotheses`` -- boolean; whether to check that this is a curve + for which the `p`-adic height makes sense - OUTPUT: The `p`-adic cyclotomic height pairing matrix of this curve - to the given precision. + OUTPUT: the `p`-adic cyclotomic height pairing matrix of this curve + to the given precision AUTHORS: @@ -425,7 +422,7 @@ def padic_height_pairing_matrix(self, p, prec=20, height=None, check_hypotheses= def _multiply_point(E, R, P, m): r""" - Computes coordinates of a multiple of `P` with entries in a ring. + Compute coordinates of a multiple of `P` with entries in a ring. INPUT: @@ -436,12 +433,13 @@ def _multiply_point(E, R, P, m): non-singular point at all primes - ``R`` -- a ring in which 2 is invertible (typically - `\ZZ/L\ZZ` for some positive odd integer - `L`). + `\ZZ/L\ZZ` for some positive odd integer `L`) + + - ``m`` -- integer (default: 1) - - ``m`` -- an integer, = 1 + OUTPUT: - OUTPUT: A triple `(a', b', d')` such that if the point + A triple `(a', b', d')` such that if the point `mP` has coordinates `(a/d^2, b/d^3)`, then we have `a' \equiv a`, `b' \equiv \pm b`, `d' \equiv \pm d` all in `R` (i.e. modulo @@ -592,9 +590,7 @@ def _multiple_to_make_good_reduction(E): - ``E`` -- an elliptic curve over `\QQ` - OUTPUT: - - - a positive integer ``n2`` + OUTPUT: a positive integer ``n2`` EXAMPLE (:issue:`34790`):: @@ -627,7 +623,6 @@ def _multiple_to_make_good_reduction(E): sage: E = EllipticCurve([0,-3^2,0,0,3^7]) # min eq is non-split mult sage: _multiple_to_make_good_reduction(E) 4 - """ if not E.is_integral(): st = ("This only implemented for integral models. " @@ -666,23 +661,24 @@ def padic_height(self, p, prec=20, sigma=None, check_hypotheses=True): INPUT: - - ``p`` -- prime >= 5 for which the curve has - semi-stable reduction + - ``p`` -- prime >= 5 for which the curve has semi-stable reduction + + - ``prec`` -- integer >= 1 (default: 20); desired precision of result - - ``prec`` -- integer >= 1 (default 20), desired precision of result + - ``sigma`` -- precomputed value of sigma; if not supplied, this function + will call ``padic_sigma`` to compute it - - ``sigma`` -- precomputed value of sigma. If not - supplied, this function will call padic_sigma to compute it. + - ``check_hypotheses`` -- boolean; whether to check that this is a curve + for which the `p`-adic height makes sense - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic height makes sense + OUTPUT: - OUTPUT: A function that accepts two parameters: + A function that accepts two parameters: - a `\QQ`-rational point on the curve whose height should be computed - - optional boolean flag 'check': if False, it skips some input - checking, and returns the p-adic height of that point to the + - optional boolean flag 'check': if ``False``, it skips some input + checking, and returns the `p`-adic height of that point to the desired precision. - The normalization (sign and a factor 1/2 with respect to some other @@ -864,36 +860,37 @@ def height(P, check=True): def padic_height_via_multiply(self, p, prec=20, E2=None, check_hypotheses=True): r""" - Computes the cyclotomic `p`-adic height. + Compute the cyclotomic `p`-adic height. The equation of the curve must be minimal at `p`. INPUT: - - ``p`` -- prime >= 5 for which the curve has good - ordinary reduction + - ``p`` -- prime >= 5 for which the curve has good ordinary reduction - - ``prec`` -- integer >= 2 (default 20), desired precision of result + - ``prec`` -- integer >= 2 (default: 20); desired precision of result - ``E2`` -- precomputed value of E2. If not supplied, this function will call padic_E2 to compute it. The value supplied must be correct mod `p^{prec-2}` (or slightly higher in the anomalous case; see the code for details). - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic height makes sense + - ``check_hypotheses`` -- boolean; whether to check + that this is a curve for which the `p`-adic height makes sense + + OUTPUT: - OUTPUT: A function that accepts two parameters: + A function that accepts two parameters: - a `\QQ`-rational point on the curve whose height should be computed - - optional boolean flag 'check': if False, it skips some input + - optional boolean flag 'check': if ``False``, it skips some input checking, and returns the `p`-adic height of that point to the desired precision. - The normalization (sign and a factor 1/2 with respect to some other normalizations that appear in the literature) is chosen in such a way - as to make the p-adic Birch Swinnerton-Dyer conjecture hold as stated + as to make the `p`-adic Birch Swinnerton-Dyer conjecture hold as stated in [MTT1986]_. AUTHORS: @@ -1008,7 +1005,7 @@ def height(P, check=True): def padic_sigma(self, p, N=20, E2=None, check=False, check_hypotheses=True): r""" - Computes the `p`-adic sigma function with respect to the standard + Compute the `p`-adic sigma function with respect to the standard invariant differential `dx/(2y + a_1 x + a_3)`, as defined by Mazur and Tate in [MT1991]_, as a power series in the usual uniformiser `t` at the origin. @@ -1017,30 +1014,26 @@ def padic_sigma(self, p, N=20, E2=None, check=False, check_hypotheses=True): INPUT: - - ``p`` -- prime >= 5 for which the curve has good - ordinary reduction + - ``p`` -- prime >= 5 for which the curve has good ordinary reduction - - ``N`` -- integer >= 1 (default 20), indicates precision of result; + - ``N`` -- integer >= 1 (default: 20); precision of result, see OUTPUT section for description - ``E2`` -- precomputed value of E2. If not supplied, this function will call padic_E2 to compute it. The value supplied must be correct mod `p^{N-2}`. - - ``check`` -- boolean, whether to perform a + - ``check`` -- boolean; whether to perform a consistency check (i.e. verify that the computed sigma satisfies the defining - - ``differential equation`` -- note that this does NOT - guarantee correctness of all the returned digits, but it comes - pretty close. + - ``differential equation`` -- note that this does NOT guarantee + correctness of all the returned digits, but it comes pretty close - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic sigma function makes - sense + - ``check_hypotheses`` -- boolean; whether to check that this is a curve + for which the `p`-adic sigma function makes sense - OUTPUT: A power series `t + \cdots` with coefficients in - `\ZZ_p`. + OUTPUT: a power series `t + \cdots` with coefficients in `\ZZ_p` The output series will be truncated at `O(t^{N+1})`, and the coefficient of `t^n` for `n \geq 1` will be @@ -1228,7 +1221,7 @@ def padic_sigma(self, p, N=20, E2=None, check=False, check_hypotheses=True): def padic_sigma_truncated(self, p, N=20, lamb=0, E2=None, check_hypotheses=True): r""" - Compute the p-adic sigma function with respect to the standard + Compute the `p`-adic sigma function with respect to the standard invariant differential `dx/(2y + a_1 x + a_3)`, as defined by Mazur and Tate in [MT1991]_, as a power series in the usual uniformiser `t` at the origin. @@ -1240,25 +1233,21 @@ def padic_sigma_truncated(self, p, N=20, lamb=0, E2=None, check_hypotheses=True) INPUT: - - ``p`` -- prime >= 5 for which the curve has good - ordinary reduction + - ``p`` -- prime >= 5 for which the curve has good ordinary reduction - - ``N`` -- integer >= 2 (default 20), indicates precision of result; + - ``N`` -- integer >= 2 (default: 20); precision of result, see OUTPUT section for description - - ``lamb`` -- integer >= 0, see OUTPUT section for - description + - ``lamb`` -- integer >= 0; see OUTPUT section for description - ``E2`` -- precomputed value of E2. If not supplied, this function will call padic_E2 to compute it. The value supplied must be correct mod `p^{N-2}`. - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic sigma function makes - sense + - ``check_hypotheses`` -- boolean; whether to check that this is a curve + for which the `p`-adic sigma function makes sense - OUTPUT: A power series `t + \cdots` with coefficients in - `\ZZ_p`. + OUTPUT: a power series `t + \cdots` with coefficients in `\ZZ_p` The coefficient of `t^j` for `j \geq 1` will be correct to precision `O(p^{N - 2 + (3 - j)(lamb + 1)})`. @@ -1388,50 +1377,46 @@ def padic_sigma_truncated(self, p, N=20, lamb=0, E2=None, check_hypotheses=True) return sigma -def padic_E2(self, p, prec=20, check=False, check_hypotheses=True, algorithm="auto"): +def padic_E2(self, p, prec=20, check=False, check_hypotheses=True, algorithm='auto'): r""" - Returns the value of the `p`-adic modular form `E2` + Return the value of the `p`-adic modular form `E2` for `(E, \omega)` where `\omega` is the usual invariant differential `dx/(2y + a_1 x + a_3)`. INPUT: - - ``p`` -- prime (= 5) for which `E` is good - and ordinary + - ``p`` -- prime (= 5) for which `E` is good and ordinary - - ``prec`` -- (relative) p-adic precision (= 1) for - result + - ``prec`` -- (relative) `p`-adic precision (= 1) for result - - ``check`` -- boolean, whether to perform a - consistency check. This will slow down the computation by a - constant factor 2. (The consistency check is to compute the whole - matrix of frobenius on Monsky-Washnitzer cohomology, and verify - that its trace is correct to the specified precision. Otherwise, - the trace is used to compute one column from the other one - (possibly after a change of basis).) + - ``check`` -- boolean; whether to perform a consistency check. This will + slow down the computation by a constant factor 2. (The consistency check + is to compute the whole matrix of frobenius on Monsky-Washnitzer + cohomology, and verify that its trace is correct to the specified + precision. Otherwise, the trace is used to compute one column from the + other one (possibly after a change of basis).) - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the p-adic sigma function makes - sense + - ``check_hypotheses`` -- boolean; whether to check that this is a curve + for which the `p`-adic sigma function makes sense - - ``algorithm`` -- one of "standard", "sqrtp", or - "auto". This selects which version of Kedlaya's algorithm is used. - The "standard" one is the one described in Kedlaya's paper. The - "sqrtp" one has better performance for large `p`, but only - works when `p > 6N` (`N=` prec). The "auto" option - selects "sqrtp" whenever possible. + - ``algorithm`` -- one of ``'standard'``, ``'sqrtp'``, or + ``'auto'``. This selects which version of Kedlaya's algorithm is used. + The ``'standard'`` one is the one described in Kedlaya's paper. The + ``'sqrtp'`` one has better performance for large `p`, but only + works when `p > 6N` (`N=` ``prec``). The ``'auto'`` option + selects ``'sqrtp'`` whenever possible. - Note that if the "sqrtp" algorithm is used, a consistency check + Note that if the ``'sqrtp'`` algorithm is used, a consistency check will automatically be applied, regardless of the setting of the - "check" flag. + ``check`` flag. - OUTPUT: p-adic number to precision prec + OUTPUT: `p`-adic number to precision ``prec`` .. NOTE:: If the discriminant of the curve has nonzero valuation at p, then the result will not be returned mod `p^\text{prec}`, - but it still *will* have prec *digits* of precision. + but it still *will* have ``prec`` *digits* of precision. .. TODO:: @@ -1468,9 +1453,9 @@ def padic_E2(self, p, prec=20, check=False, check_hypotheses=True, algorithm="au sage: EllipticCurve([-1, 1/4]).padic_E2(5, 3) 2 + 4*5 + O(5^3) - TODO: With the old(-er), i.e., = sage-2.4 p-adics we got + TODO: With the old(-er), i.e., = sage-2.4 `p`-adics we got `5 + O(5^2)` as output, i.e., relative precision 1, but - with the newer p-adics we get relative precision 0 and absolute + with the newer `p`-adics we get relative precision 0 and absolute precision 1. :: @@ -1542,7 +1527,7 @@ def padic_E2(self, p, prec=20, check=False, check_hypotheses=True, algorithm="au Here's one using the `p^{1/2}` algorithm:: - sage: EllipticCurve([-1, 1/4]).padic_E2(3001, 3, algorithm="sqrtp") + sage: EllipticCurve([-1, 1/4]).padic_E2(3001, 3, algorithm='sqrtp') 1907 + 2819*3001 + 1124*3001^2 + O(3001^3) """ if self.conductor() % p == 0: @@ -1574,40 +1559,37 @@ def padic_E2(self, p, prec=20, check=False, check_hypotheses=True, algorithm="au return output_ring(E2_of_X * fudge_factor_inverse) -def matrix_of_frobenius(self, p, prec=20, check=False, check_hypotheses=True, algorithm="auto"): +def matrix_of_frobenius(self, p, prec=20, check=False, check_hypotheses=True, algorithm='auto'): r""" - Returns the matrix of Frobenius on the Monsky Washnitzer cohomology of + Return the matrix of Frobenius on the Monsky Washnitzer cohomology of the short Weierstrass model of the minimal model of the elliptic curve. INPUT: - - ``p`` -- prime (>= 3) for which `E` is good - and ordinary + - ``p`` -- prime (>= 3) for which `E` is good and ordinary - - ``prec`` -- (relative) `p`-adic precision for - result (default 20) + - ``prec`` -- (relative) `p`-adic precision for result (default: 20) - - ``check`` -- boolean (default: ``False``), whether to perform a + - ``check`` -- boolean (default: ``False``); whether to perform a consistency check. This will slow down the computation by a constant factor 2. (The consistency check is to verify that its trace is correct to the specified precision. Otherwise, the trace is used to compute one column from the other one (possibly after a change of basis).) - - ``check_hypotheses`` -- boolean, whether to check - that this is a curve for which the `p`-adic sigma function makes - sense + - ``check_hypotheses`` -- boolean; whether to check that this is a curve + for which the `p`-adic sigma function makes sense - - ``algorithm`` -- one of "standard", "sqrtp", or - "auto". This selects which version of Kedlaya's algorithm is used. - The "standard" one is the one described in Kedlaya's paper. The - "sqrtp" one has better performance for large `p`, but only - works when `p > 6N` (`N=` prec). The "auto" option - selects "sqrtp" whenever possible. + - ``algorithm`` -- one of ``'standard'``, ``'sqrtp'``, or + ``'auto'``. This selects which version of Kedlaya's algorithm is used. + The ``'standard'`` one is the one described in Kedlaya's paper. The + ``'sqrtp'`` one has better performance for large `p`, but only + works when `p > 6N` (`N=` prec). The ``'auto'`` option + selects ``'sqrtp'`` whenever possible. - Note that if the "sqrtp" algorithm is used, a consistency check + Note that if the ``'sqrtp'`` algorithm is used, a consistency check will automatically be applied, regardless of the setting of the - "check" flag. + ``check`` flag. OUTPUT: a matrix of `p`-adic number to precision ``prec`` diff --git a/src/sage/schemes/elliptic_curves/period_lattice.py b/src/sage/schemes/elliptic_curves/period_lattice.py old mode 100644 new mode 100755 index a961aa5f1f2..9db15a6eba7 --- a/src/sage/schemes/elliptic_curves/period_lattice.py +++ b/src/sage/schemes/elliptic_curves/period_lattice.py @@ -149,9 +149,8 @@ def __init__(self, E, embedding=None): - ``E`` -- an elliptic curve - - ``embedding`` (default: ``None``) -- an embedding of the base - field `K` of ``E`` into a real or complex field. If - ``None``: + - ``embedding`` -- (default: ``None``) an embedding of the base + field `K` of ``E`` into a real or complex field. If ``None``: - use the built-in coercion to `\RR` for `K=\QQ`; @@ -281,7 +280,7 @@ def __init__(self, E, embedding=None): def __richcmp__(self, other, op): r""" - Comparison function for period lattices + Comparison function for period lattices. TESTS:: @@ -340,11 +339,11 @@ def __call__(self, P, prec=None): INPUT: - - ``P`` (point) -- a point on the elliptic curve associated - with this period lattice. + - ``P`` -- a point on the elliptic curve associated with this period + lattice - - ``prec`` (default: ``None``) -- precision in bits (default - precision if ``None``). + - ``prec`` -- (default: ``None``) precision in bits (default + precision if ``None``) OUTPUT: @@ -401,13 +400,13 @@ def basis(self, prec=None, algorithm='sage'): INPUT: - - ``prec`` (default: ``None``) -- precision in bits (default - precision if ``None``). + - ``prec`` -- (default: ``None``) precision in bits (default + precision if ``None``) - - ``algorithm`` (string, default ``'sage'``) -- choice of + - ``algorithm`` -- string (default: ``'sage'``); choice of implementation (for real embeddings only) between ``'sage'`` (native Sage implementation) or ``'pari'`` (use the PARI - library: only available for real embeddings). + library: only available for real embeddings) OUTPUT: @@ -486,13 +485,13 @@ def gens(self, prec=None, algorithm='sage'): INPUT: - - ``prec`` (default: ``None``) -- precision in bits (default - precision if ``None``). + - ``prec`` -- (default: ``None``) precision in bits (default + precision if ``None``) - - ``algorithm`` (string, default ``'sage'``) -- choice of + - ``algorithm`` -- string (default: ``'sage'``); choice of implementation (for real embeddings only) between ``'sage'`` (native Sage implementation) or ``'pari'`` (use the PARI - library: only available for real embeddings). + library: only available for real embeddings) OUTPUT: @@ -524,13 +523,13 @@ def normalised_basis(self, prec=None, algorithm='sage'): INPUT: - - ``prec`` (default: ``None``) -- precision in bits (default - precision if ``None``). + - ``prec`` -- (default: ``None``) precision in bits (default + precision if ``None``) - - ``algorithm`` (string, default ``'sage'``) -- choice of + - ``algorithm`` -- string (default: ``'sage'``); choice of implementation (for real embeddings only) between ``'sage'`` (native Sage implementation) or ``'pari'`` (use the PARI - library: only available for real embeddings). + library: only available for real embeddings) OUTPUT: @@ -581,13 +580,13 @@ def tau(self, prec=None, algorithm='sage'): INPUT: - - ``prec`` (default: ``None``) -- precision in bits (default - precision if ``None``). + - ``prec`` -- (default: ``None``) precision in bits (default + precision if ``None``) - - ``algorithm`` (string, default 'sage') -- choice of + - ``algorithm`` -- string (default: ``'sage'``); choice of implementation (for real embeddings only) between 'sage' (native Sage implementation) or 'pari' (use the PARI - library: only available for real embeddings). + library: only available for real embeddings) OUTPUT: @@ -638,13 +637,14 @@ def _compute_periods_real(self, prec=None, algorithm='sage'): INPUT: - - `prec` (int or ``None`` (default)) -- floating point - precision (in bits); if None, use the default precision. + - ``prec`` -- integer or ``None`` (default); floating point + precision (in bits). If ``None``, use the default precision. - - `algorithm` (string, default 'sage') -- choice of implementation between - - `pari`: use the PARI library + - ``algorithm`` string (default: ``'sage'``); choice of implementation between - - `sage`: use a native Sage implementation (with the same underlying algorithm). + - ``'pari'`` -- use the PARI library + + - ``'sage'`` -- use a native Sage implementation (with the same underlying algorithm) OUTPUT: @@ -711,17 +711,17 @@ def _compute_periods_complex(self, prec=None, normalise=True): INPUT: - - ``prec`` (integer or ``None`` (default)) -- floating point precision (in bits); if ``None``, - use the default precision. + - ``prec`` -- integer or ``None`` (default); floating point precision + (in bits); if ``None``, use the default precision - - ``normalise`` (bool, default ``True``) -- whether to normalise the - basis after computation. + - ``normalise`` -- boolean (default: ``True``); whether to normalise the + basis after computation OUTPUT: (tuple of Complex) `(\omega_1,\omega_2)` where the lattice has the form `\ZZ\omega_1 + \ZZ\omega_2`. If `normalise` is - `True`, the basis is normalised so that `(\omega_1/\omega_2)` + ``True``, the basis is normalised so that `(\omega_1/\omega_2)` is in the fundamental region of the upper half plane. EXAMPLES:: @@ -820,7 +820,7 @@ def is_rectangular(self) -> bool: .. NOTE:: - Only defined for real lattices; a :class:`RuntimeError` + Only defined for real lattices; a :exc:`RuntimeError` is raised for non-real lattices. EXAMPLES:: @@ -855,17 +855,17 @@ def real_period(self, prec=None, algorithm='sage'): INPUT: - - ``prec`` (integer or ``None`` (default)) -- real precision in + - ``prec`` -- integer or ``None`` (default); real precision in bits (default real precision if ``None``) - - ``algorithm`` (string, default ``'sage'``) -- choice of + - ``algorithm`` -- string (default: ``'sage'``); choice of implementation (for real embeddings only) between ``'sage'`` (native Sage implementation) or ``'pari'`` (use the PARI - library: only available for real embeddings). + library: only available for real embeddings) .. NOTE:: - Only defined for real lattices; a :class:`RuntimeError` + Only defined for real lattices; a :exc:`RuntimeError` is raised for non-real lattices. EXAMPLES:: @@ -895,11 +895,11 @@ def omega(self, prec=None, bsd_normalise=False): INPUT: - - ``prec`` (int or ``None`` (default)) -- real precision in + - ``prec`` -- integer or ``None`` (default); real precision in bits (default real precision if ``None``) - - ``bsd_normalise`` (bool, default ``False``) -- flag to use - BSD normalisation in the complex case. + - ``bsd_normalise`` -- boolean (default: ``False``); flag to use + BSD normalisation in the complex case OUTPUT: @@ -978,12 +978,12 @@ def basis_matrix(self, prec=None, normalised=False): INPUT: - - ``prec`` (int or ``None`` (default)) -- real precision in - bits (default real precision if ``None``). + - ``prec`` -- integer or ``None`` (default); real precision in + bits (default real precision if ``None``) - - ``normalised`` (bool, default ``False``) -- if ``True`` and the + - ``normalised`` -- boolean (default: ``False``); if ``True`` and the embedding is real, use the normalised basis (see - :meth:`normalised_basis`) instead of the default. + :meth:`normalised_basis`) instead of the default OUTPUT: @@ -1047,8 +1047,8 @@ def complex_area(self, prec=None): INPUT: - - ``prec`` (int or ``None`` (default)) -- real precision in - bits (default real precision if ``None``). + - ``prec`` -- integer or ``None`` (default); real precision in + bits (default real precision if ``None``) EXAMPLES:: @@ -1079,8 +1079,8 @@ def sigma(self, z, prec=None, flag=0): - ``z`` -- a complex number - - ``prec`` (default: ``None``) -- real precision in bits - (default real precision if ``None``). + - ``prec`` -- (default: ``None``) real precision in bits + (default real precision if ``None``) - ``flag`` -- @@ -1180,14 +1180,14 @@ def ei(self): def coordinates(self, z, rounding=None): r""" - Return the coordinates of a complex number w.r.t. the lattice basis + Return the coordinates of a complex number w.r.t. the lattice basis. INPUT: - - ``z`` (complex) -- A complex number. + - ``z`` -- complex number - - ``rounding`` (default ``None``) -- whether and how to round the - output (see below). + - ``rounding`` -- (default: ``None``) whether and how to round the + output (see below) OUTPUT: @@ -1257,11 +1257,11 @@ def coordinates(self, z, rounding=None): def reduce(self, z): r""" - Reduce a complex number modulo the lattice + Reduce a complex number modulo the lattice. INPUT: - - ``z`` (complex) -- A complex number. + - ``z`` -- complex number OUTPUT: @@ -1336,11 +1336,11 @@ def e_log_RC(self, xP, yP, prec=None, reduce=True): the embedded elliptic curve associated with this period lattice. - - ``prec`` (default: ``None``) -- real precision in bits - (default real precision if None). + - ``prec`` -- (default: ``None``) real precision in bits + (default real precision if ``None``) - - ``reduce`` (default: ``True``) -- if ``True``, the result - is reduced with respect to the period lattice basis. + - ``reduce`` -- boolean (default: ``True``); if ``True``, the result + is reduced with respect to the period lattice basis OUTPUT: @@ -1536,14 +1536,14 @@ def elliptic_logarithm(self, P, prec=None, reduce=True): INPUT: - - ``P`` (point) -- A point on the elliptic curve associated - with this period lattice. + - ``P`` -- point on the elliptic curve associated with this period + lattice - - ``prec`` (default: ``None``) -- real precision in bits - (default real precision if ``None``). + - ``prec`` -- (default: ``None``) real precision in bits + (default real precision if ``None``) - - ``reduce`` (default: ``True``) -- if ``True``, the result - is reduced with respect to the period lattice basis. + - ``reduce`` -- boolean (default: ``True``); if ``True``, the result + is reduced with respect to the period lattice basis OUTPUT: @@ -1731,9 +1731,9 @@ def elliptic_exponential(self, z, to_curve=True): INPUT: - - ``z`` (complex) -- A complex number (viewed modulo this period lattice). + - ``z`` -- complex number (viewed modulo this period lattice) - - ``to_curve`` (bool, default ``True``): see below. + - ``to_curve`` -- boolean (default: ``True``); see below OUTPUT: @@ -1943,7 +1943,7 @@ def reduce_tau(tau): INPUT: - - ``tau`` (complex) -- a complex number with positive imaginary part + - ``tau`` -- complex number with positive imaginary part OUTPUT: @@ -2038,7 +2038,7 @@ def extended_agm_iteration(a, b, c): INPUT: - - ``a``, ``b``, ``c`` (real or complex) -- three real or complex numbers. + - ``a``, ``b``, ``c`` -- three real or complex numbers OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/period_lattice_region.pyx b/src/sage/schemes/elliptic_curves/period_lattice_region.pyx old mode 100644 new mode 100755 index 70ce616f92f..40b92ab23eb --- a/src/sage/schemes/elliptic_curves/period_lattice_region.pyx +++ b/src/sage/schemes/elliptic_curves/period_lattice_region.pyx @@ -72,7 +72,7 @@ cdef class PeriodicRegion: def is_empty(self): """ - Returns whether this region is empty. + Return whether this region is empty. EXAMPLES:: @@ -91,10 +91,10 @@ cdef class PeriodicRegion: def _ensure_full(self): """ - Ensure the bitmap in self.data represents the entire fundamental + Ensure the bitmap in ``self.data`` represents the entire fundamental parallelogram, expanding symmetry by duplicating data if necessary. - Mutates and returns self. + Mutates and returns ``self``. EXAMPLES:: @@ -126,7 +126,7 @@ cdef class PeriodicRegion: def ds(self): """ - Returns the sides of each parallelogram tile. + Return the sides of each parallelogram tile. EXAMPLES:: @@ -155,12 +155,12 @@ cdef class PeriodicRegion: INPUT: - - ``condition`` (function) -- a boolean-valued function on `\CC`. + - ``condition`` -- boolean-valued function on `\CC` OUTPUT: - True or False according to whether the condition holds for all - lines on the boundary. + boolean according to whether the condition holds for all lines on the + boundary. EXAMPLES:: @@ -189,15 +189,13 @@ cdef class PeriodicRegion: INPUT: - - ``condition`` (function, default None) -- if not None, only - keep tiles in the refinement which satisfy the condition. + - ``condition`` -- function (default: ``None``); if not ``None``, only + keep tiles in the refinement which satisfy the condition - - ``times`` (int, default 1) -- the number of times to refine; - each refinement step halves the mesh size. + - ``times`` -- integer (default: 1); the number of times to refine. + Each refinement step halves the mesh size. - OUTPUT: - - The refined PeriodicRegion. + OUTPUT: the refined PeriodicRegion EXAMPLES:: @@ -243,7 +241,7 @@ cdef class PeriodicRegion: def expand(self, bint corners=True): """ - Returns a region containing this region by adding all neighbors of + Return a region containing this region by adding all neighbors of internal tiles. EXAMPLES:: @@ -316,7 +314,7 @@ cdef class PeriodicRegion: def __contains__(self, z): """ - Returns whether this region contains the given point. + Return whether this region contains the given point. EXAMPLES:: @@ -367,7 +365,7 @@ cdef class PeriodicRegion: def __truediv__(self, unsigned int n): """ - Returns a new region of the same resolution that is the image + Return a new region of the same resolution that is the image of this region under the map z -> z/n. The resolution is the same, so some detail may be lost. The result is @@ -445,7 +443,7 @@ cdef class PeriodicRegion: def __invert__(self): """ - Returns the complement of this region. + Return the complement of this region. EXAMPLES:: @@ -467,7 +465,7 @@ cdef class PeriodicRegion: def __and__(left, right): """ - Returns the intersection of left and right. + Return the intersection of ``left`` and ``right``. EXAMPLES:: @@ -494,7 +492,8 @@ cdef class PeriodicRegion: def __xor__(left, right): """ - Returns the union of left and right less the intersection of left and right. + Return the union of ``left`` and ``right`` minus the intersection of + ``left`` and ``right``. EXAMPLES:: @@ -562,7 +561,7 @@ cdef class PeriodicRegion: def border(self, raw=True): """ - Returns the boundary of this region as set of tile boundaries. + Return the boundary of this region as set of tile boundaries. If raw is true, returns a list with respect to the internal bitmap, otherwise returns complex intervals covering the border. diff --git a/src/sage/schemes/elliptic_curves/saturation.py b/src/sage/schemes/elliptic_curves/saturation.py old mode 100644 new mode 100755 index 936948a4267..5f14db7ac19 --- a/src/sage/schemes/elliptic_curves/saturation.py +++ b/src/sage/schemes/elliptic_curves/saturation.py @@ -59,16 +59,14 @@ def reduce_mod_q(x, amodq): INPUT: - - ``x`` -- an element of a number field `K`. + - ``x`` -- an element of a number field `K` - ``amodq`` -- an element of `GF(q)` which is a root mod `q` of the defining polynomial of `K`. This defines a degree 1 prime ideal `Q=(q,\alpha-a)` of `K=\QQ(\alpha)`, where `a \bmod q` = ``amodq``. - OUTPUT: - - The image of ``x`` in the residue field of `K` at the prime `Q`. + OUTPUT: the image of ``x`` in the residue field of `K` at the prime `Q` EXAMPLES:: @@ -96,9 +94,9 @@ class EllipticCurveSaturator(SageObject): INPUT: - - ``E`` -- an elliptic curve defined over a number field, or `\QQ`. + - ``E`` -- an elliptic curve defined over a number field, or `\QQ` - - ``verbose`` (boolean, default ``False``) -- verbosity flag. + - ``verbose`` -- boolean (default: ``False``); verbosity flag .. NOTE:: @@ -112,9 +110,9 @@ def __init__(self, E, verbose=False): INPUT: - - ``E`` -- an elliptic curve defined over a number field. + - ``E`` -- an elliptic curve defined over a number field - - ``verbose`` (boolean, default ``False``) -- verbosity flag. + - ``verbose`` -- boolean (default: ``False``); verbosity flag """ self._verbose = verbose self._curve = E @@ -143,7 +141,7 @@ def add_reductions(self, q): INPUT: - ``q`` -- a prime number not dividing the defining polynomial - of ``self.__field``. + of ``self.__field`` OUTPUT: @@ -211,9 +209,9 @@ def full_p_saturation(self, Plist, p): INPUT: - - ``Plist`` (list) -- a list of independent points on one elliptic curve. + - ``Plist`` -- list of independent points on one elliptic curve - - ``p`` (integer) -- a prime number. + - ``p`` -- integer; a prime number OUTPUT: @@ -302,12 +300,12 @@ def p_saturation(self, Plist, p, sieve=True): INPUT: - - ``Plist`` (list) -- a list of independent points on one elliptic curve. + - ``Plist`` -- list of independent points on one elliptic curve - - ``p`` (integer) -- a prime number. + - ``p`` -- integer; a prime number - - ``sieve`` (boolean) -- if True, use a sieve (when there are at - least 2 points); otherwise test all combinations. + - ``sieve`` -- boolean; if ``True``, use a sieve (when there are at + least 2 points), otherwise test all combinations .. NOTE:: @@ -340,7 +338,7 @@ def p_saturation(self, Plist, p, sieve=True): False Here we see an example where 19-saturation is proved, with the - verbose flag set to True so that we can see what is going on:: + verbose flag set to ``True`` so that we can see what is going on:: sage: saturator = EllipticCurveSaturator(EK, verbose=True) sage: saturator.p_saturation([P, Q, R], 19) @@ -573,7 +571,7 @@ def p_saturation(self, Plist, p, sieve=True): # really is p*R. Now to enlarge the # span, we may replce the j'th point # in Plist with R, where v[j] is - # non-zero. + # nonzero. if verbose: print("-- points were not {}-saturated, gaining index {}".format(p,p)) j = next(i for i,x in enumerate(v) if x) @@ -592,11 +590,11 @@ def p_projections(Eq, Plist, p, debug=False): INPUT: - - ``Eq`` -- An elliptic curve over a finite field. + - ``Eq`` -- an elliptic curve over a finite field - - ``Plist`` -- a list of points on `Eq`. + - ``Plist`` -- list of points on `Eq` - - ``p`` -- a prime number. + - ``p`` -- a prime number OUTPUT: diff --git a/src/sage/schemes/elliptic_curves/sha_tate.py b/src/sage/schemes/elliptic_curves/sha_tate.py old mode 100644 new mode 100755 index 90003faf1c7..83922981a63 --- a/src/sage/schemes/elliptic_curves/sha_tate.py +++ b/src/sage/schemes/elliptic_curves/sha_tate.py @@ -14,7 +14,7 @@ But it is not known in general. A theorem of Kolyvagin and Gross-Zagier using Heegner points shows that if the -L-series of an elliptic curve `E/\QQ` does not vanish at 1 or has a simple +`L`-series of an elliptic curve `E/\QQ` does not vanish at 1 or has a simple zero there, then `Sha` is finite. A theorem of Kato, together with theorems from Iwasawa theory, allows for @@ -22,7 +22,7 @@ gives an effective upper bound for it. The (`p`-adic) conjecture of Birch and Swinnerton-Dyer predicts the order of -`Sha` from the leading term of the (`p`-adic) L-series of the elliptic curve. +`Sha` from the leading term of the (`p`-adic) `L`-series of the elliptic curve. Sage can compute a few things about `Sha`. The commands ``an``, ``an_numerical`` and ``an_padic`` compute the conjectural order of `Sha` as a @@ -143,7 +143,7 @@ def __init__(self, E): INPUT: - - E -- an elliptic curve over `\QQ` + - ``E`` -- an elliptic curve over `\QQ` EXAMPLES:: @@ -213,11 +213,11 @@ def an_numerical(self, prec=None, INPUT: - - ``prec`` -- integer (default: 53) bits precision -- used - for the L-series computation, period, regulator, etc. + - ``prec`` -- integer (default: 53); bits precision -- used + for the `L`-series computation, period, regulator, etc. - ``use_database`` -- whether the rank and generators should be looked up in the database if possible. Default is ``True`` - - ``proof`` -- bool or ``None`` (default: ``None``, see proof.[tab] or + - ``proof`` -- boolean or ``None`` (default: ``None``, see proof.[tab] or sage.structure.proof) proof option passed onto regulator and rank computation. @@ -230,7 +230,7 @@ def an_numerical(self, prec=None, If the curve's generators are not known, computing them may be very time-consuming. Also, computation of the - L-series derivative will be time-consuming for large rank and + `L`-series derivative will be time-consuming for large rank and large conductor, and the computation time for this may increase substantially at greater precision. However, use of very low precision less than about 10 can cause the underlying @@ -304,12 +304,12 @@ def an(self, use_database=False, descent_second_limit=12): INPUT: - - ``use_database`` -- bool (default: ``False``); if ``True``, try + - ``use_database`` -- boolean (default: ``False``); if ``True``, try to use any databases installed to lookup the analytic order of `Sha`, if possible. The order of `Sha` is computed if it cannot be looked up. - - ``descent_second_limit`` -- int (default: 12); limit to use on + - ``descent_second_limit`` -- integer (default: 12); limit to use on point searching for the quartic twist in the hard case This result is proved correct if the order of vanishing is 0 @@ -466,16 +466,16 @@ def an_padic(self, p, prec=0, use_twists=True): - ``p`` -- a prime > 3 - - ``prec`` (optional) -- the precision used in the computation of the + - ``prec`` -- (optional) the precision used in the computation of the `p`-adic L-Series - - ``use_twists`` (default: ``True``) -- If ``True`` the algorithm may + - ``use_twists`` -- boolean (default: ``True``); if ``True`` the algorithm may change to a quadratic twist with minimal conductor to do the modular symbol computations rather than using the modular symbols of the curve itself. If ``False`` it forces the computation using the modular symbols of the curve itself. - OUTPUT: `p`-adic number - that conjecturally equals `\# Sha(E/\QQ)`. + OUTPUT: `p`-adic number - that conjecturally equals `\# Sha(E/\QQ)`. If ``prec`` is set to zero (default) then the precision is set so that at least the first `p`-adic digit of conjectural `\# Sha(E/\QQ)` is @@ -724,13 +724,13 @@ def p_primary_order(self, p): INPUT: - - `p` -- an odd prime + - ``p`` -- an odd prime OUTPUT: - - `e` -- a non-negative integer such that `p^e` is the + - ``e`` -- nonnegative integer such that `p^e` is the order of the `p`-primary order if the conditions are satisfied - and raises a :class:`ValueError` otherwise. + and raises a :exc:`ValueError` otherwise. EXAMPLES:: @@ -775,7 +775,7 @@ def p_primary_bound(self, p): OUTPUT: - - ``e`` -- a non-negative integer such that `p^e` is an upper + - ``e`` -- nonnegative integer such that `p^e` is an upper bound for the order of `Sha(E)(p)` In particular, if this algorithm does not fail, then it proves @@ -920,19 +920,19 @@ def bound_kolyvagin(self, D=0, regulator=None, the Heegner hypothesis for `E`; if not given, use the first such `D` - ``regulator`` -- (optional) regulator of `E(K)`; if not given, will be computed (which could take a long time) - - ``ignore_nonsurj_hypothesis`` (optional: default ``False``) -- - If ``True``, then gives the bound coming from Heegner point + - ``ignore_nonsurj_hypothesis`` -- (default: ``False``); + if ``True``, then gives the bound coming from Heegner point index, but without any hypothesis on surjectivity - of the mod-`p` representation. + of the mod-`p` representation OUTPUT: - - list -- a list of primes such that if `p` divides `Sha(E/K)`, then + - ``list`` -- list of primes such that if `p` divides `Sha(E/K)`, then `p` is in this list, unless `E/K` has complex multiplication or - analytic rank greater than 2 (in which case we return 0). + analytic rank greater than 2 (in which case we return 0) - - index -- the odd part of the index of the Heegner point in the full - group of `K`-rational points on E. (If `E` has CM, returns 0.) + - ``index`` -- the odd part of the index of the Heegner point in the full + group of `K`-rational points on `E` (if `E` has CM, returns 0) REMARKS: @@ -1081,7 +1081,7 @@ def bound_kato(self): Then `{ord}_p(\#Sha(E))` is bounded from above by the `p`-adic valuation of `L(E,1)\cdot\#E(\QQ)_{tor}^2 / (\Omega_E \cdot \prod c_v)`. - If the L-series vanishes, the method ``p_primary_bound`` can be used instead. + If the `L`-series vanishes, the method ``p_primary_bound`` can be used instead. EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/weierstrass_morphism.py b/src/sage/schemes/elliptic_curves/weierstrass_morphism.py old mode 100644 new mode 100755 index 4c3313c9a89..1fc2eb751a9 --- a/src/sage/schemes/elliptic_curves/weierstrass_morphism.py +++ b/src/sage/schemes/elliptic_curves/weierstrass_morphism.py @@ -60,7 +60,7 @@ class baseWI: """ def __init__(self, u=1, r=0, s=0, t=0): r""" - Constructor: check for valid parameters (defaults to identity) + Constructor: check for valid parameters (defaults to identity). INPUT: @@ -179,11 +179,9 @@ def __call__(self, EorP): INPUT: - - ``EorP`` -- either an elliptic curve, or a point on an elliptic curve. + - ``EorP`` -- either an elliptic curve, or a point on an elliptic curve - OUTPUT: - - The transformed curve or point. + OUTPUT: the transformed curve or point EXAMPLES:: @@ -227,7 +225,7 @@ def _isomorphisms(E, F): INPUT: - - ``E``, ``F`` (EllipticCurve) -- Two elliptic curves. + - ``E``, ``F`` -- two elliptic curves OUTPUT: @@ -378,12 +376,12 @@ class WeierstrassIsomorphism(EllipticCurveHom, baseWI): INPUT: - - ``E`` -- an ``EllipticCurve``, or ``None`` (see below). + - ``E`` -- an ``EllipticCurve``, or ``None`` (see below) - ``urst`` -- a 4-tuple `(u,r,s,t)`, a :class:`baseWI` object, - or ``None`` (see below). + or ``None`` (see below) - - ``F`` -- an ``EllipticCurve``, or ``None`` (see below). + - ``F`` -- an ``EllipticCurve``, or ``None`` (see below) Given two Elliptic Curves ``E`` and ``F`` (represented by Weierstrass models as usual), and a transformation ``urst`` from ``E`` to ``F``, @@ -617,7 +615,7 @@ def _call_(self, P): INPUT: - - ``P`` (Point) -- a point on the domain curve. + - ``P`` -- Point; a point on the domain curve OUTPUT: @@ -1003,9 +1001,9 @@ def order(self): r""" Compute the order of this Weierstrass isomorphism if it is an automorphism. - A :class:`ValueError` is raised if the domain is not equal to the codomain. + A :exc:`ValueError` is raised if the domain is not equal to the codomain. - A :class:`NotImplementedError` is raised if the order of the automorphism is not 1, 2, 3, 4 or 6. + A :exc:`NotImplementedError` is raised if the order of the automorphism is not 1, 2, 3, 4 or 6. EXAMPLES:: diff --git a/src/sage/schemes/elliptic_curves/weierstrass_transform.py b/src/sage/schemes/elliptic_curves/weierstrass_transform.py old mode 100644 new mode 100755 index 07f897fb315..fcbd4e84023 --- a/src/sage/schemes/elliptic_curves/weierstrass_transform.py +++ b/src/sage/schemes/elliptic_curves/weierstrass_transform.py @@ -62,13 +62,13 @@ def __init__(self, domain, codomain, defining_polynomials, post_multiplication): INPUT: - ``domain``, ``codomain`` -- two schemes, one of which is an - elliptic curve. + elliptic curve - ``defining_polynomials`` -- triplet of polynomials that - define the transformation. + define the transformation - ``post_multiplication`` -- a polynomial to homogeneously - rescale after substituting the defining polynomials. + rescale after substituting the defining polynomials EXAMPLES:: @@ -116,9 +116,7 @@ def post_rescaling(self): Return the homogeneous rescaling to apply after the coordinate substitution. - OUTPUT: - - A polynomial. See the example below. + OUTPUT: a polynomial; see the example below EXAMPLES:: diff --git a/src/sage/schemes/generic/algebraic_scheme.py b/src/sage/schemes/generic/algebraic_scheme.py old mode 100644 new mode 100755 index c94d0ab28b1..ebe79be6471 --- a/src/sage/schemes/generic/algebraic_scheme.py +++ b/src/sage/schemes/generic/algebraic_scheme.py @@ -116,7 +116,7 @@ from sage.categories.number_fields import NumberFields -from sage.rings.ideal import is_Ideal +from sage.rings.ideal import Ideal_generic from sage.rings.integer_ring import ZZ from sage.rings.rational_field import RationalField from sage.rings.finite_rings.finite_field_base import FiniteField @@ -140,11 +140,11 @@ def is_AlgebraicScheme(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: - Boolean. Whether ``x`` is an algebraic scheme, that is, a + boolean; whether ``x`` is an algebraic scheme, that is, a subscheme of an ambient space over a ring defined by polynomial equations. @@ -254,12 +254,10 @@ def _latex_(self): def is_projective(self): """ - Return True if self is presented as a subscheme of an ambient + Return ``True`` if ``self`` is presented as a subscheme of an ambient projective space. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -375,7 +373,7 @@ def embedding_morphism(self): or neighborhood of a point then the embedding is the embedding into the original scheme. - * A :class:`NotImplementedError` is raised if the construction of + * A :exc:`NotImplementedError` is raised if the construction of the embedding morphism is not implemented yet. EXAMPLES:: @@ -469,7 +467,7 @@ def embedding_center(self): OUTPUT: - A point of ``self``. This raises :class:`AttributeError` if there + A point of ``self``. This raises :exc:`AttributeError` if there is no distinguished point, depending on how ``self`` was constructed. EXAMPLES:: @@ -534,15 +532,13 @@ def _repr_(self): def _homset(self, *args, **kwds): """ - Construct the Hom-set + Construct the Hom-set. INPUT: Same as :class:`sage.schemes.generic.homset.SchemeHomset_generic`. - OUTPUT: - - The Hom-set of the ambient space. + OUTPUT: the Hom-set of the ambient space EXAMPLES:: @@ -604,9 +600,7 @@ class AlgebraicScheme_quasi(AlgebraicScheme): preferred method to construct such subschemes is to use :meth:`complement` method of algebraic schemes. - OUTPUT: - - An instance of :class:`AlgebraicScheme_quasi`. + OUTPUT: an instance of :class:`AlgebraicScheme_quasi` EXAMPLES:: @@ -628,7 +622,7 @@ def __init__(self, X, Y): INPUT: - - ``X``, ``Y`` -- two subschemes of the same ambient space. + - ``X``, ``Y`` -- two subschemes of the same ambient space TESTS:: @@ -724,7 +718,7 @@ def _repr_(self): def X(self): """ - Return the scheme `X` such that self is represented as `X - Y`. + Return the scheme `X` such that ``self`` is represented as `X - Y`. EXAMPLES:: @@ -739,7 +733,7 @@ def X(self): def Y(self): """ - Return the scheme `Y` such that self is represented as `X - Y`. + Return the scheme `Y` such that ``self`` is represented as `X - Y`. EXAMPLES:: @@ -755,7 +749,7 @@ def Y(self): def _check_satisfies_equations(self, v): """ Verify that the coordinates of v define a point on this scheme, or - raise a TypeError. + raise a :exc:`TypeError`. EXAMPLES:: @@ -834,16 +828,13 @@ def rational_points(self, **kwds): Return the set of rational points on this algebraic scheme over the field `F`. - INPUT: - - kwds: - - - ``bound`` -- integer (default: 0). The bound for the coordinates for - subschemes with dimension at least 1. + INPUT: keyword arguments: - - ``F`` -- field (default: base ring). The field to compute - the rational points over. + - ``bound`` -- integer (default: 0); the bound for the coordinates for + subschemes with dimension at least 1 + - ``F`` -- field (default: base ring); the field to compute + the rational points over EXAMPLES:: @@ -898,16 +889,14 @@ class AlgebraicScheme_subscheme(AlgebraicScheme): INPUT: - - ``A`` -- ambient space (e.g. affine or projective `n`-space) + - ``A`` -- ambient space (e.g. affine or projective `n`-space) - - ``polynomials`` -- single polynomial, ideal or iterable of defining - polynomials; in any case polynomials must belong to the coordinate - ring of the ambient space and define valid polynomial functions (e.g. - they should be homogeneous in the case of a projective space) + - ``polynomials`` -- single polynomial, ideal or iterable of defining + polynomials; in any case polynomials must belong to the coordinate + ring of the ambient space and define valid polynomial functions (e.g. + they should be homogeneous in the case of a projective space) - OUTPUT: - - - algebraic scheme + OUTPUT: algebraic scheme EXAMPLES:: @@ -936,17 +925,17 @@ def __init__(self, A, polynomials, category=None): Closed subscheme of Projective Space of dimension 2 over Rational Field defined by: x^2 - y*z """ - from sage.rings.polynomial.multi_polynomial_sequence import is_PolynomialSequence + from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence_generic AlgebraicScheme.__init__(self, A, category=category) self._base_ring = A.base_ring() R = A.coordinate_ring() - if is_Ideal(polynomials): + if isinstance(polynomials, Ideal_generic): I = polynomials polynomials = I.gens() if I.ring() is R: # Otherwise we will recompute I later after self.__I = I # converting generators to the correct ring - if isinstance(polynomials, tuple) or is_PolynomialSequence(polynomials) or is_iterator(polynomials): + if isinstance(polynomials, tuple) or isinstance(polynomials, PolynomialSequence_generic) or is_iterator(polynomials): polynomials = list(polynomials) elif not isinstance(polynomials, list): # Looks like we got a single polynomial @@ -963,7 +952,7 @@ def __init__(self, A, polynomials, category=None): def _check_satisfies_equations(self, v): """ Verify that the coordinates of v define a point on this scheme, or - raise a TypeError. + raise a :exc:`TypeError`. EXAMPLES:: @@ -1122,7 +1111,6 @@ def normalize_defining_polynomials(self): sage: S.normalize_defining_polynomials() sage: S.defining_polynomials() (x^2 + 2*x*y, 3*x + 8*y) - """ BR = self.base_ring() if (BR == ZZ @@ -1152,9 +1140,7 @@ def defining_ideal(self): Return the ideal that defines this scheme as a subscheme of its ambient space. - OUTPUT: - - An ideal in the coordinate ring of the ambient space. + OUTPUT: an ideal in the coordinate ring of the ambient space EXAMPLES:: @@ -1176,9 +1162,7 @@ def codimension(self): r""" Return the codimension of the algebraic subscheme. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -1277,7 +1261,7 @@ def is_irreducible(self): r""" Return whether this subscheme is or is not irreducible. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -1312,9 +1296,7 @@ def Jacobian_matrix(self): Return the matrix `\frac{\partial f_i}{\partial x_j}` of (formal) partial derivatives. - OUTPUT: - - A matrix of polynomials. + OUTPUT: a matrix of polynomials EXAMPLES:: @@ -1355,9 +1337,7 @@ def Jacobian(self): Jacobian ideal. An example of a reference that does include the defining equations is [Laz2004]_, p. 181. - OUTPUT: - - An ideal in the coordinate ring of the ambient space. + OUTPUT: an ideal in the coordinate ring of the ambient space EXAMPLES:: @@ -1435,7 +1415,7 @@ def reduce(self): def union(self, other): """ - Return the scheme-theoretic union of self and other in their common + Return the scheme-theoretic union of ``self`` and ``other`` in their common ambient space. EXAMPLES: We construct the union of a line and a tripled-point on @@ -1482,9 +1462,11 @@ def __pow__(self, m): """ Return the Cartesian power of this space. - INPUT: ``m`` -- integer. + INPUT: + + - ``m`` -- integer - OUTPUT: subscheme of product of ambient spaces. + OUTPUT: subscheme of product of ambient spaces EXAMPLES:: @@ -1547,7 +1529,7 @@ def __mul__(self, right): - ``right`` -- a subscheme of similar type - OUTPUT: a subscheme of a the product of the ambient spaces. + OUTPUT: a subscheme of a the product of the ambient spaces EXAMPLES:: @@ -1741,18 +1723,16 @@ def rational_points(self, **kwds): modulo primes is used. See the documentation in homset for the details of the sieving algorithm. - INPUT: - - kwds: + INPUT: keyword arguments: - - ``bound`` -- integer (default: 0). The bound for the coordinates for - subschemes with dimension at least 1. + - ``bound`` -- integer (default: 0); the bound for the coordinates for + subschemes with dimension at least 1 - - ``prec`` -- integer (default: 53). The precision to use to - compute the elements of bounded height for number fields. + - ``prec`` -- integer (default: 53); the precision to use to + compute the elements of bounded height for number fields - ``F`` -- field (default: base ring). The field to compute - the rational points over. + the rational points over - ``point_tolerance`` -- positive real number (default: 10^(-10)). For numerically inexact fields, two points are considered the same @@ -1762,7 +1742,8 @@ def rational_points(self, **kwds): For numerically inexact fields, points are on the subscheme if they satisfy the equations to within tolerance. - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm-4 OUTPUT: list of points in subscheme or ambient space @@ -1856,15 +1837,13 @@ def rational_points(self, **kwds): def change_ring(self, R): r""" - Returns a new algebraic subscheme which is this subscheme coerced to ``R``. + Return a new algebraic subscheme which is this subscheme coerced to ``R``. INPUT: - - ``R`` -- ring or morphism. - - OUTPUT: + - ``R`` -- ring or morphism - - A new algebraic subscheme which is this subscheme coerced to ``R``. + OUTPUT: a new algebraic subscheme which is this subscheme coerced to ``R`` EXAMPLES:: @@ -2007,7 +1986,7 @@ def weil_restriction(self): If the input and the output ideals are radical, this is equivalent to the statement about algebraic varieties above. - OUTPUT: Affine subscheme - the Weil restriction of ``self``. + OUTPUT: affine subscheme; the Weil restriction of ``self`` EXAMPLES:: diff --git a/src/sage/schemes/generic/ambient_space.py b/src/sage/schemes/generic/ambient_space.py old mode 100644 new mode 100755 index 895cd4a338d..0a624197b07 --- a/src/sage/schemes/generic/ambient_space.py +++ b/src/sage/schemes/generic/ambient_space.py @@ -19,7 +19,7 @@ def is_AmbientSpace(x): """ - Return True if `x` is an ambient space. + Return ``True`` if `x` is an ambient space. EXAMPLES:: @@ -46,9 +46,9 @@ class AmbientSpace(Scheme): INPUT: - - ``n`` -- dimension + - ``n`` -- dimension - - ``R`` -- ring + - ``R`` -- ring """ def __init__(self, n, R=ZZ): """ @@ -123,7 +123,7 @@ def _latex_generic_point(self, coords=None): def _check_satisfies_equations(self, v): """ Verify that the coordinates of v define a point on this scheme, or - raise a TypeError. + raise a :exc:`TypeError`. TESTS:: @@ -138,17 +138,15 @@ def _check_satisfies_equations(self, v): def _validate(self, polynomials): """ - If ``polynomials`` is a tuple of valid polynomial functions on self, - return ``polynomials``, otherwise raise TypeError. + If ``polynomials`` is a tuple of valid polynomial functions on + ``self``, return ``polynomials``, otherwise raise :exc:`TypeError`. INPUT: - ``polynomials`` -- tuple of polynomials in the coordinate ring of - self + ``self`` - OUTPUT: - - - tuple of polynomials in the coordinate ring of self + OUTPUT: tuple of polynomials in the coordinate ring of ``self`` TESTS:: @@ -170,9 +168,7 @@ def change_ring(self, R): - ``R`` -- commutative ring - OUTPUT: - - - ambient space over ``R`` + OUTPUT: ambient space over ``R`` .. NOTE:: @@ -217,15 +213,13 @@ def base_extend(self, R): INPUT: - ``R`` -- a commutative ring, such that there is a natural map from - the base ring of self to ``R``. - - OUTPUT: + the base ring of ``self`` to ``R`` - - an ambient space over ``R`` of the same structure as ``self``. + OUTPUT: an ambient space over ``R`` of the same structure as ``self`` .. NOTE:: - A :class:`ValueError` is raised if there is no such natural map. + A :exc:`ValueError` is raised if there is no such natural map. If you need to drop this condition, use ``self.change_ring(R)``. EXAMPLES:: @@ -271,8 +265,8 @@ def ambient_space(self): def defining_polynomials(self): """ - Return the defining polynomials of the scheme self. Since - self is an ambient space, this is an empty list. + Return the defining polynomials of the scheme ``self``. Since + ``self`` is an ambient space, this is an empty list. EXAMPLES:: @@ -311,7 +305,7 @@ def identity_morphism(self): def gen(self, n=0): """ Return the `n`-th generator of the coordinate ring of the - scheme self. + scheme ``self``. EXAMPLES:: @@ -324,7 +318,7 @@ def gen(self, n=0): def gens(self): """ Return the generators of the coordinate ring of the scheme - self. + ``self``. EXAMPLES:: @@ -340,7 +334,7 @@ def gens(self): def ngens(self): """ Return the number of generators of the coordinate ring of the - scheme self. + scheme ``self``. EXAMPLES:: diff --git a/src/sage/schemes/generic/divisor.py b/src/sage/schemes/generic/divisor.py old mode 100644 new mode 100755 index 981290dfe76..2f1990484e9 --- a/src/sage/schemes/generic/divisor.py +++ b/src/sage/schemes/generic/divisor.py @@ -95,15 +95,13 @@ def CurvePointToIdeal(C,P): def is_Divisor(x): r""" - Test whether ``x`` is an instance of :class:`Divisor_generic` + Test whether ``x`` is an instance of :class:`Divisor_generic`. INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -162,16 +160,15 @@ def __init__(self, v, parent, check=True, reduce=True): INPUT: - - ``v`` -- object. Usually a list of pairs - ``(coefficient,divisor)``. + - ``v`` -- object; usually a list of pairs ``(coefficient,divisor)`` - ``parent`` -- FormalSums(R) module (default: FormalSums(ZZ)) - - ``check`` -- bool (default: ``True``). Whether to coerce + - ``check`` -- boolean (default: ``True``); whether to coerce coefficients into base ring. Setting it to ``False`` can speed up construction. - - ``reduce`` -- reduce (default: ``True``). Whether to combine + - ``reduce`` -- reduce (default: ``True``); whether to combine common terms. Setting it to ``False`` can speed up construction. @@ -195,9 +192,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -225,9 +220,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -272,14 +265,12 @@ class Divisor_curve(Divisor_generic): For any curve `C`, use ``C.divisor(v)`` to construct a divisor on `C`. Here `v` can be either + - a rational point on `C` - - a rational point on `C` - - - a list of rational points - - - a list of 2-tuples `(c,P)`, where `c` is an - integer and `P` is a rational point. + - a list of rational points + - a list of 2-tuples `(c,P)`, where `c` is an + integer and `P` is a rational point TODO: Divisors shouldn't be restricted to rational points. The problem is that the divisor group is the formal sum of the group of @@ -310,12 +301,11 @@ def __init__(self, v, parent=None, check=True, reduce=True): INPUT: - - ``v`` -- a list of pairs ``(c, P)``, where ``c`` is an - integer and ``P`` is a point on a curve. The P's must all - lie on the same curve. - + - ``v`` -- list of pairs ``(c, P)``, where ``c`` is an + integer and ``P`` is a point on a curve. The P's must all + lie on the same curve. - - To create the divisor 0 use ``[(0, P)]``, so as to give the curve. + To create the divisor 0 use ``[(0, P)]``, so as to give the curve. EXAMPLES:: @@ -382,9 +372,7 @@ def _repr_(self): r""" Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: diff --git a/src/sage/schemes/generic/divisor_group.py b/src/sage/schemes/generic/divisor_group.py old mode 100644 new mode 100755 index 05c0f06f7d9..0b11b1d0982 --- a/src/sage/schemes/generic/divisor_group.py +++ b/src/sage/schemes/generic/divisor_group.py @@ -31,15 +31,13 @@ def DivisorGroup(scheme, base_ring=None): INPUT: - - ``scheme`` -- a scheme. + - ``scheme`` -- a scheme - ``base_ring`` -- usually either `\ZZ` (default) or `\QQ`. The coefficient ring of the divisors. Not to be confused with the base ring of the scheme! - OUTPUT: - - An instance of ``DivisorGroup_generic``. + OUTPUT: an instance of ``DivisorGroup_generic`` EXAMPLES:: @@ -66,11 +64,9 @@ def is_DivisorGroup(x): INPUT: - - ``x`` -- anything. - - OUTPUT: + - ``x`` -- anything - ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -114,10 +110,9 @@ def __init__(self, scheme, base_ring): INPUT: - - ``scheme`` -- a scheme. + - ``scheme`` -- a scheme - - ``base_ring`` -- the coefficient ring of the divisor - group. + - ``base_ring`` -- the coefficient ring of the divisor group Implementation note: :meth:`__classcall__` sets default value for ``base_ring``. diff --git a/src/sage/schemes/generic/glue.py b/src/sage/schemes/generic/glue.py old mode 100644 new mode 100755 index e70aafa0507..122801561e6 --- a/src/sage/schemes/generic/glue.py +++ b/src/sage/schemes/generic/glue.py @@ -15,15 +15,11 @@ class GluedScheme(scheme.Scheme): r""" INPUT: + - ``f`` -- open immersion from a scheme `U` to a scheme `X` - - ``f`` -- open immersion from a scheme `U` to a scheme - `X` + - ``g`` -- open immersion from `U` to a scheme `Y` - - ``g`` -- open immersion from `U` to a scheme `Y` - - - OUTPUT: The scheme obtained by gluing `X` and `Y` along the open set - `U`. + OUTPUT: the scheme obtained by gluing `X` and `Y` along the open set `U` .. NOTE:: diff --git a/src/sage/schemes/generic/homset.py b/src/sage/schemes/generic/homset.py old mode 100644 new mode 100755 index 7ef792b9b5b..1468090f395 --- a/src/sage/schemes/generic/homset.py +++ b/src/sage/schemes/generic/homset.py @@ -10,7 +10,7 @@ are implemented by such scheme morphisms. This is done by :class:`SchemeHomset_points` and its subclasses. -.. note:: +.. NOTE:: You should not create the Hom-sets manually. Instead, use the :meth:`~sage.structure.parent.Hom` method that is inherited by all @@ -129,18 +129,18 @@ def create_key_and_extra_args(self, X, Y, category=None, base=None, INPUT: - - ``X`` -- a scheme. The domain of the morphisms. + - ``X`` -- a scheme; the domain of the morphisms - - ``Y`` -- a scheme. The codomain of the morphisms. + - ``Y`` -- a scheme; the codomain of the morphisms - ``category`` -- a category for the Hom-sets (default: schemes over - given base). + given base) - - ``base`` -- a scheme or a ring. The base scheme of domain + - ``base`` -- a scheme or a ring; the base scheme of domain and codomain schemes. If a ring is specified, the spectrum of that ring will be used as base scheme. - - ``check`` -- boolean (default: ``True``). + - ``check`` -- boolean (default: ``True``) EXAMPLES:: @@ -190,11 +190,11 @@ def create_object(self, version, key, **extra_args): INPUT: - - ``version`` -- object version. Currently not used. + - ``version`` -- object version; currently not used - - ``key`` -- a key created by :meth:`create_key_and_extra_args`. + - ``key`` -- a key created by :meth:`create_key_and_extra_args` - - ``extra_args`` -- a dictionary of extra keyword arguments. + - ``extra_args`` -- dictionary of extra keyword arguments EXAMPLES:: @@ -235,15 +235,15 @@ class SchemeHomset_generic(HomsetWithBase): INPUT: - - ``X`` -- a scheme. The domain of the Hom-set. + - ``X`` -- a scheme; the domain of the Hom-set - - ``Y`` -- a scheme. The codomain of the Hom-set. + - ``Y`` -- a scheme; the codomain of the Hom-set - - ``category`` -- a category (optional). The category of the - Hom-set. + - ``category`` -- a category (optional); the category of the + Hom-set - - ``check`` -- boolean (default: ``True``). Whether to - check the defining data for consistency. + - ``check`` -- boolean (default: ``True``); whether to + check the defining data for consistency EXAMPLES:: @@ -293,9 +293,7 @@ def _repr_(self): r""" Return a string representation. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -318,8 +316,7 @@ def natural_map(self): OUTPUT: A :class:`SchemeMorphism` if there is a natural map from - domain to codomain. Otherwise, a :class:`NotImplementedError` is - raised. + domain to codomain. Otherwise, a :exc:`NotImplementedError` is raised. EXAMPLES:: @@ -342,12 +339,12 @@ def _element_constructor_(self, x, check=True): INPUT: - - `x` -- a ring morphism, or a list or a tuple that define a - ring morphism. + - ``x`` -- a ring morphism, or a list or a tuple that define a + ring morphism - - ``check`` -- boolean (default: ``True``) passed onto + - ``check`` -- boolean (default: ``True``); passed onto functions called by this one to be more careful about input - argument type checking. + argument type checking EXAMPLES:: @@ -630,11 +627,9 @@ def _element_constructor_(self, *v, **kwds): INPUT: - ``v`` -- anything that determines a scheme morphism in the - Hom-set. - - OUTPUT: + Hom-set - The scheme morphism determined by ``v``. + OUTPUT: the scheme morphism determined by ``v`` EXAMPLES:: @@ -708,9 +703,7 @@ def _repr_(self): """ Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -724,9 +717,7 @@ def value_ring(self): r""" Return `R` for a point Hom-set `X(\mathrm{Spec}(R))`. - OUTPUT: - - A commutative ring. + OUTPUT: a commutative ring EXAMPLES:: @@ -743,9 +734,7 @@ def cardinality(self): """ Return the number of points. - OUTPUT: - - An integer or infinity. + OUTPUT: integer or infinity EXAMPLES:: @@ -767,9 +756,7 @@ def list(self): """ Return a tuple containing all points. - OUTPUT: - - A tuple containing all points of the toric variety. + OUTPUT: a tuple containing all points of the toric variety EXAMPLES:: diff --git a/src/sage/schemes/generic/hypersurface.py b/src/sage/schemes/generic/hypersurface.py old mode 100644 new mode 100755 index 4d39a7bfc27..0560697be25 --- a/src/sage/schemes/generic/hypersurface.py +++ b/src/sage/schemes/generic/hypersurface.py @@ -25,7 +25,7 @@ def is_Hypersurface(self): """ - Return True if ``self`` is a hypersurface, i.e. an object of the type + Return ``True`` if ``self`` is a hypersurface, i.e. an object of the type :class:`ProjectiveHypersurface` or :class:`AffineHypersurface`. EXAMPLES:: diff --git a/src/sage/schemes/generic/morphism.py b/src/sage/schemes/generic/morphism.py old mode 100644 new mode 100755 index 6e491c50c9e..cc5475bf38a --- a/src/sage/schemes/generic/morphism.py +++ b/src/sage/schemes/generic/morphism.py @@ -96,11 +96,11 @@ def is_SchemeMorphism(f): INPUT: - - ``f`` -- anything. + - ``f`` -- anything OUTPUT: - Boolean. Return ``True`` if ``f`` is a scheme morphism or a point + boolean; return ``True`` if ``f`` is a scheme morphism or a point on an elliptic curve. EXAMPLES:: @@ -122,11 +122,11 @@ def is_SchemeMorphism(f): class SchemeMorphism(Element): """ - Base class for scheme morphisms + Base class for scheme morphisms. INPUT: - - ``parent`` -- the parent of the morphism. + - ``parent`` -- the parent of the morphism .. TODO:: @@ -277,9 +277,7 @@ def _repr_defn(self): r""" Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -298,9 +296,7 @@ def _repr_type(self): r""" Return a string representation of the type of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -317,9 +313,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -412,11 +406,9 @@ def __pow__(self, n, dummy=None): INPUT: - - ``n`` -- integer. The exponent. - - OUTPUT: + - ``n`` -- integer; the exponent - A composite map that belongs to the same endomorphism set as ``self``. + OUTPUT: a composite map that belongs to the same endomorphism set as ``self`` EXAMPLES:: @@ -439,9 +431,7 @@ def category(self): """ Return the category of the Hom-set. - OUTPUT: - - A category. + OUTPUT: a category EXAMPLES:: @@ -467,9 +457,7 @@ def is_endomorphism(self) -> bool: """ Return whether the morphism is an endomorphism. - OUTPUT: - - Boolean. Whether the domain and codomain are identical. + OUTPUT: boolean; whether the domain and codomain are identical EXAMPLES:: @@ -486,9 +474,7 @@ def base_ring(self): Return the base ring of ``self``, that is, the ring over which the defining polynomials of ``self`` are defined. - OUTPUT: - - - ring + OUTPUT: ring EXAMPLES:: @@ -608,11 +594,11 @@ def _composition_(self, right, homset): def glue_along_domains(self, other): r""" - Glue two morphism + Glue two morphisms. INPUT: - - ``other`` -- a scheme morphism with the same domain. + - ``other`` -- a scheme morphism with the same domain OUTPUT: @@ -678,7 +664,7 @@ class SchemeMorphism_id(SchemeMorphism): INPUT: - - ``X`` -- the scheme. + - ``X`` -- the scheme EXAMPLES:: @@ -705,9 +691,7 @@ def _repr_defn(self): r""" Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -719,12 +703,12 @@ def _repr_defn(self): class SchemeMorphism_structure_map(SchemeMorphism): r""" - The structure morphism + The structure morphism. INPUT: - ``parent`` -- Hom-set with codomain equal to the base scheme of - the domain. + the domain EXAMPLES:: @@ -755,9 +739,7 @@ def _repr_defn(self): r""" Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -769,16 +751,16 @@ def _repr_defn(self): class SchemeMorphism_spec(SchemeMorphism): """ - Morphism of spectra of rings + Morphism of spectra of rings. INPUT: - - ``parent`` -- Hom-set whose domain and codomain are affine schemes. + - ``parent`` -- Hom-set whose domain and codomain are affine schemes - - ``phi`` -- a ring morphism with matching domain and codomain. + - ``phi`` -- a ring morphism with matching domain and codomain - - ``check`` -- boolean (default:``True``). Whether to - check the input for consistency. + - ``check`` -- boolean (default: ``True``); whether to + check the input for consistency EXAMPLES:: @@ -841,11 +823,9 @@ def _call_(self, x): INPUT: - - ``x`` -- a scheme point. - - OUTPUT: + - ``x`` -- a scheme point - The image scheme point. + OUTPUT: the image scheme point EXAMPLES: @@ -871,9 +851,7 @@ def _repr_type(self): r""" Return a string representation of the type of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -890,9 +868,7 @@ def _repr_defn(self): r""" Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -912,9 +888,7 @@ def ring_homomorphism(self): """ Return the underlying ring homomorphism. - OUTPUT: - - A ring homomorphism. + OUTPUT: a ring homomorphism EXAMPLES:: @@ -945,13 +919,13 @@ class SchemeMorphism_polynomial(SchemeMorphism): INPUT: - ``parent`` -- Hom-set whose domain and codomain are affine or - projective schemes. + projective schemes - - ``polys`` -- a list/tuple/iterable of polynomials defining the - scheme morphism. + - ``polys`` -- list/tuple/iterable of polynomials defining the + scheme morphism - - ``check`` -- boolean (default:``True``). Whether to - check the input for consistency. + - ``check`` -- boolean (default: ``True``); whether to + check the input for consistency EXAMPLES: @@ -981,7 +955,6 @@ class SchemeMorphism_polynomial(SchemeMorphism): ... TypeError: polys (=[e^x, e^y]) must be elements of Multivariate Polynomial Ring in x, y over Rational Field - """ def __init__(self, parent, polys, check=True): """ @@ -1069,11 +1042,9 @@ def _call_(self, x): INPUT: - ``x`` -- a point in the domain or a list or tuple that - defines a point in the domain. + defines a point in the domain - OUTPUT: - - A point in the codomain. + OUTPUT: a point in the codomain EXAMPLES:: @@ -1141,16 +1112,15 @@ def _call_(self, x): def _call_with_args(self, x, args, kwds): """ - Apply this morphism to a point in the domain, with additional arguments + Apply this morphism to a point in the domain, with additional arguments. INPUT: - - ``x`` -- a point in the domain or a list or tuple that defines a point in the domain. - - ``check``, a boolean, either provided by position or name. - - OUTPUT: + - ``x`` -- a point in the domain or a list or tuple that defines a + point in the domain + - ``check`` -- boolean; either provided by position or name - A point in the codomain. + OUTPUT: a point in the codomain EXAMPLES:: @@ -1233,9 +1203,7 @@ def _repr_defn(self): """ Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1252,15 +1220,13 @@ def _repr_defn(self): def __getitem__(self, i): """ - Return the i-th poly with self[i]. + Return the i-th poly with ``self[i]``. INPUT: - ``i`` -- integer - OUTPUT: - - - element of the coordinate ring of the domain + OUTPUT: element of the coordinate ring of the domain EXAMPLES:: @@ -1276,9 +1242,7 @@ def __copy__(self): r""" Return a copy of ``self``. - OUTPUT: - - - :class:`SchemeMorphism_polynomial` + OUTPUT: :class:`SchemeMorphism_polynomial` EXAMPLES:: @@ -1306,7 +1270,7 @@ def coordinate_ring(self): r""" Return the coordinate ring of the ambient projective space. - OUTPUT: A multivariable polynomial ring over the base ring. + OUTPUT: a multivariable polynomial ring over the base ring EXAMPLES:: @@ -1330,19 +1294,19 @@ def coordinate_ring(self): def change_ring(self, R, check=True): r""" - Returns a new :class:`SchemeMorphism_polynomial` which is this map coerced to ``R``. + Return a new :class:`SchemeMorphism_polynomial` which is this map + coerced to ``R``. If ``check`` is ``True``, then the initialization checks are performed. INPUT: - - ``R`` -- ring or morphism. + - ``R`` -- ring or morphism - - ``check`` -- Boolean + - ``check`` -- boolean - OUTPUT: - - - A new :class:`SchemeMorphism_polynomial` which is this map coerced to ``R``. + OUTPUT: a new :class:`SchemeMorphism_polynomial` which is this map + coerced to ``R`` TESTS:: @@ -1373,7 +1337,6 @@ def change_ring(self, R, check=True): ... ValueError: no canonical coercion of base ring of morphism to domain of embedding - EXAMPLES:: sage: P. = ProjectiveSpace(ZZ, 1) @@ -1811,9 +1774,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1828,9 +1789,7 @@ def _latex_(self): r""" Return a latex representation of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1847,9 +1806,7 @@ def __getitem__(self, n): """ Return the ``n``-th coordinate. - OUTPUT: - - The coordinate values as an element of the base ring. + OUTPUT: the coordinate values as an element of the base ring EXAMPLES:: @@ -1866,9 +1823,7 @@ def __iter__(self): """ Iterate over the coordinates of the point. - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -1888,9 +1843,7 @@ def __tuple__(self): """ Return the coordinates as a tuple. - OUTPUT: - - A tuple. + OUTPUT: a tuple EXAMPLES:: @@ -1905,9 +1858,7 @@ def __len__(self): """ Return the number of coordinates. - OUTPUT: - - Integer. The number of coordinates used to describe the point. + OUTPUT: integer. The number of coordinates used to describe the point EXAMPLES:: @@ -1924,12 +1875,10 @@ def _richcmp_(self, other, op): INPUT: - - ``other`` -- anything. To compare against the scheme - morphism ``self``. + - ``other`` -- anything; to compare against the scheme + morphism ``self`` - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -1952,9 +1901,7 @@ def scheme(self): """ Return the scheme whose point is represented. - OUTPUT: - - A scheme. + OUTPUT: a scheme EXAMPLES:: @@ -1967,15 +1914,16 @@ def scheme(self): def change_ring(self, R, check=True): r""" - Returns a new :class:`SchemeMorphism_point` which is this point coerced to ``R``. + Return a new :class:`SchemeMorphism_point` which is this point coerced + to ``R``. If ``check`` is true, then the initialization checks are performed. INPUT: - - ``R`` -- ring or morphism. + - ``R`` -- ring or morphism - - ``check`` -- Boolean + - ``check`` -- boolean OUTPUT: :class:`SchemeMorphism_point` @@ -2051,11 +1999,10 @@ def change_ring(self, R, check=True): def __copy__(self): r""" - Returns a copy of the :class:`SchemeMorphism_point` self coerced to `R`. + Return a copy of the :class:`SchemeMorphism_point` ``self`` coerced to + `R`. - OUTPUT: - - - :class:`SchemeMorphism_point` + OUTPUT: :class:`SchemeMorphism_point` EXAMPLES:: diff --git a/src/sage/schemes/generic/point.py b/src/sage/schemes/generic/point.py old mode 100644 new mode 100755 index 7ef85645f56..43857cc5b3e --- a/src/sage/schemes/generic/point.py +++ b/src/sage/schemes/generic/point.py @@ -41,7 +41,7 @@ def __init__(self, S, parent=None): def scheme(self): """ - Return the scheme on which self is a point. + Return the scheme on which ``self`` is a point. EXAMPLES:: @@ -170,8 +170,8 @@ def __init__(self, S, P, check=False): the Ideal (-x^2 + y*z) of Multivariate Polynomial Ring in x, y, z over Rational Field """ R = S.coordinate_ring() - from sage.rings.ideal import is_Ideal - if not is_Ideal(P): + from sage.rings.ideal import Ideal_generic + if not isinstance(P, Ideal_generic): P = R.ideal(P) elif P.ring() is not R: P = R.ideal(P.gens()) diff --git a/src/sage/schemes/generic/scheme.py b/src/sage/schemes/generic/scheme.py old mode 100644 new mode 100755 index c697a305f26..4d2468893a6 --- a/src/sage/schemes/generic/scheme.py +++ b/src/sage/schemes/generic/scheme.py @@ -24,7 +24,7 @@ from sage.misc.lazy_import import lazy_import from sage.rings.integer_ring import ZZ from sage.categories.commutative_rings import CommutativeRings -from sage.rings.ideal import is_Ideal +from sage.rings.ideal import Ideal_generic from sage.structure.unique_representation import UniqueRepresentation from sage.schemes.generic.point import SchemeTopologicalPoint_prime_ideal @@ -37,11 +37,9 @@ def is_Scheme(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - Boolean. Whether ``x`` derives from :class:`Scheme`. + OUTPUT: boolean; whether ``x`` derives from :class:`Scheme` EXAMPLES:: @@ -71,8 +69,8 @@ class Scheme(Parent): the base scheme. If a commutative ring is passed, the spectrum of the ring will be used as base. - - ``category`` -- the category (optional). Will be automatically - constructed by default. + - ``category`` -- the category (optional); will be automatically + constructed by default EXAMPLES:: @@ -105,7 +103,6 @@ def __init__(self, X=None, category=None): sage: RmodI = R.quotient(I) sage: X = Spec(RmodI) sage: TestSuite(X).run() # needs sage.libs.singular - """ from sage.schemes.generic.morphism import is_SchemeMorphism from sage.categories.map import Map @@ -206,15 +203,13 @@ def __call__(self, *args): """ Call syntax for schemes. - INPUT/OUTPUT: - - The arguments must be one of the following: + INPUT/OUTPUT: the arguments must be one of the following: - a ring or a scheme `S`. Output will be the set `X(S)` of `S`-valued points on `X`. - If `S` is a list or tuple or just the coordinates, return a - point in `X(T)`, where `T` is the base scheme of self. + point in `X(T)`, where `T` is the base scheme of ``self``. EXAMPLES:: @@ -280,11 +275,9 @@ def point_homset(self, S=None): INPUT: - - ``S`` -- a commutative ring. + - ``S`` -- a commutative ring - OUTPUT: - - The set of morphisms `\mathrm{Spec}(S) \to X`. + OUTPUT: the set of morphisms `\mathrm{Spec}(S) \to X` EXAMPLES:: @@ -323,9 +316,7 @@ def point(self, v, check=True): - ``check`` -- boolean (default: ``True``); whether to check the defining data for consistency - OUTPUT: - - A point of the scheme. + OUTPUT: a point of the scheme EXAMPLES:: @@ -383,7 +374,7 @@ def _point_homset(self, *args, **kwds): def __truediv__(self, Y): """ - Return the base extension of self to Y. + Return the base extension of ``self`` to Y. See :meth:`base_extend` for details. @@ -401,11 +392,9 @@ def __truediv__(self, Y): def base_ring(self): """ - Return the base ring of the scheme self. - - OUTPUT: + Return the base ring of the scheme ``self``. - A commutative ring. + OUTPUT: a commutative ring EXAMPLES:: @@ -432,9 +421,7 @@ def base_scheme(self): """ Return the base scheme. - OUTPUT: - - A scheme. + OUTPUT: a scheme EXAMPLES:: @@ -463,9 +450,7 @@ def base_morphism(self): Return the structure morphism from ``self`` to its base scheme. - OUTPUT: - - A scheme morphism. + OUTPUT: a scheme morphism EXAMPLES:: @@ -506,7 +491,7 @@ def coordinate_ring(self): OUTPUT: The global coordinate ring of this scheme, if - defined. Otherwise this raises a :class:`ValueError`. + defined. Otherwise this raises a :exc:`ValueError`. EXAMPLES:: @@ -526,9 +511,7 @@ def dimension_absolute(self): """ Return the absolute dimension of this scheme. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -552,9 +535,7 @@ def dimension_relative(self): """ Return the relative dimension of this scheme over its base. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -572,9 +553,7 @@ def identity_morphism(self): """ Return the identity morphism. - OUTPUT: - - The identity morphism of the scheme ``self``. + OUTPUT: the identity morphism of the scheme ``self`` EXAMPLES:: @@ -601,9 +580,7 @@ def hom(self, x, Y=None, check=True): - ``check`` -- boolean (default: ``True``); whether to check the defining data for consistency - OUTPUT: - - The scheme morphism from ``self`` to ``Y`` defined by ``x``. + OUTPUT: the scheme morphism from ``self`` to ``Y`` defined by ``x`` EXAMPLES:: @@ -633,11 +610,9 @@ def _Hom_(self, Y, category=None, check=True): Hom-set - ``check`` -- boolean (default: ``True``); whether - to check the defining data for consistency. - - OUTPUT: + to check the defining data for consistency - The set of morphisms from ``self`` to ``Y``. + OUTPUT: the set of morphisms from ``self`` to ``Y`` EXAMPLES:: @@ -667,7 +642,7 @@ def count_points(self, n): INPUT: - - ``n`` -- integer. + - ``n`` -- integer OUTPUT: @@ -707,7 +682,7 @@ def zeta_function(self): Derived classes should override this method. - OUTPUT: rational function in one variable. + OUTPUT: rational function in one variable EXAMPLES:: @@ -733,9 +708,7 @@ def zeta_series(self, n, t): - ``t`` -- the variable which the series should be returned - OUTPUT: - - A power series approximating the zeta function of ``self`` + OUTPUT: a power series approximating the zeta function of ``self`` EXAMPLES:: @@ -796,7 +769,7 @@ def zeta_series(self, n, t): def is_AffineScheme(x): """ - Return True if `x` is an affine scheme. + Return ``True`` if `x` is an affine scheme. EXAMPLES:: @@ -839,7 +812,6 @@ class AffineScheme(UniqueRepresentation, Scheme): For affine spaces over a base ring and subschemes thereof, see :class:`sage.schemes.generic.algebraic_scheme.AffineSpace`. - """ def __init__(self, R, S=None, category=None): """ @@ -909,9 +881,7 @@ def _repr_(self): """ Return a string representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -929,9 +899,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -947,9 +915,7 @@ def __call__(self, *args): """ Construct a scheme-valued or topological point of ``self``. - INPUT/OUTPUT: - - The argument ``x`` must be one of the following: + INPUT/OUTPUT: the argument ``x`` must be one of the following: - a prime ideal of the coordinate ring; the output will be the corresponding point of `X` @@ -1019,7 +985,7 @@ def __call__(self, *args): if len(args) == 1: x = args[0] if ((isinstance(x, self.element_class) and (x.parent() is self or x.parent() == self)) - or (is_Ideal(x) and x.ring() is self.coordinate_ring())): + or (isinstance(x, Ideal_generic) and x.ring() is self.coordinate_ring())): # Construct a topological point from x. return self._element_constructor_(x) try: @@ -1049,7 +1015,7 @@ def _element_constructor_(self, x): return x elif x.parent() == self: return self.element_class(self, x.prime_ideal()) - elif is_Ideal(x) and x.ring() is self.coordinate_ring(): + elif isinstance(x, Ideal_generic) and x.ring() is self.coordinate_ring(): return self.element_class(self, x) raise TypeError('cannot convert %s to a topological point of %s' % (x, self)) @@ -1057,9 +1023,7 @@ def _an_element_(self): r""" Return an element of the spectrum of the ring. - OUTPUT: - - A point of the affine scheme ``self``. + OUTPUT: a point of the affine scheme ``self`` EXAMPLES:: @@ -1077,9 +1041,7 @@ def coordinate_ring(self): """ Return the underlying ring of this scheme. - OUTPUT: - - A commutative ring. + OUTPUT: a commutative ring EXAMPLES:: @@ -1105,9 +1067,7 @@ def dimension_absolute(self): """ Return the absolute dimension of this scheme. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -1125,9 +1085,7 @@ def dimension_relative(self): """ Return the relative dimension of this scheme over its base. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -1191,9 +1149,7 @@ def hom(self, x, Y=None): - ``check`` -- boolean (default: ``True``); whether to check the defining data for consistency - OUTPUT: - - The scheme morphism from ``self`` to ``Y`` defined by ``x``. + OUTPUT: the scheme morphism from ``self`` to ``Y`` defined by ``x`` EXAMPLES: diff --git a/src/sage/schemes/generic/spec.py b/src/sage/schemes/generic/spec.py old mode 100644 new mode 100755 index 93fc8b7e43c..5c699c0d004 --- a/src/sage/schemes/generic/spec.py +++ b/src/sage/schemes/generic/spec.py @@ -54,7 +54,7 @@ def Spec(R, S=None): sage: A is B True - A :class:`TypeError` is raised if the input is not a commutative ring:: + A :exc:`TypeError` is raised if the input is not a commutative ring:: sage: Spec(5) Traceback (most recent call last): diff --git a/src/sage/schemes/hyperelliptic_curves/constructor.py b/src/sage/schemes/hyperelliptic_curves/constructor.py old mode 100644 new mode 100755 index adb7d7cb6f5..a39b94b030b --- a/src/sage/schemes/hyperelliptic_curves/constructor.py +++ b/src/sage/schemes/hyperelliptic_curves/constructor.py @@ -31,23 +31,21 @@ def HyperellipticCurve(f, h=0, names=None, PP=None, check_squarefree=True): r""" - Returns the hyperelliptic curve `y^2 + h y = f`, for + Return the hyperelliptic curve `y^2 + h y = f`, for univariate polynomials `h` and `f`. If `h` is not given, then it defaults to 0. INPUT: - - ``f`` -- univariate polynomial + - ``f`` -- univariate polynomial - - ``h`` -- optional univariate polynomial + - ``h`` -- (optional) univariate polynomial - - ``names`` (default: ``["x","y"]``) -- names for the - coordinate functions + - ``names`` -- (default: ``["x","y"]``) names for the coordinate functions - - ``check_squarefree`` (default: ``True``) -- test if - the input defines a hyperelliptic curve when f is - homogenized to degree `2g+2` and h to degree - `g+1` for some g. + - ``check_squarefree`` -- boolean (default: ``True``); test if the input + defines a hyperelliptic curve when f is homogenized to degree `2g+2` and + h to degree `g+1` for some `g` .. WARNING:: @@ -163,7 +161,7 @@ def HyperellipticCurve(f, h=0, names=None, PP=None, check_squarefree=True): Input with integer coefficients creates objects with the integers as base ring, but only checks smoothness over `\QQ`, not over Spec(`\ZZ`). - In other words, it is checked that the discriminant is non-zero, but it is + In other words, it is checked that the discriminant is nonzero, but it is not checked whether the discriminant is a unit in `\ZZ^*`.:: sage: P. = ZZ[] @@ -222,7 +220,7 @@ def HyperellipticCurve(f, h=0, names=None, PP=None, check_squarefree=True): # characteristic 2 if h == 0: raise ValueError( - f"for characteristic 2, argument {h = } must be non-zero" + f"for characteristic 2, argument {h = } must be nonzero" ) if h[g + 1] == 0 and f[2 * g + 1] ** 2 == f[2 * g + 2] * h[g] ** 2: raise ValueError( diff --git a/src/sage/schemes/hyperelliptic_curves/hypellfrob.pyx b/src/sage/schemes/hyperelliptic_curves/hypellfrob.pyx old mode 100644 new mode 100755 index e0b0e77c568..4fa3280f6f9 --- a/src/sage/schemes/hyperelliptic_curves/hypellfrob.pyx +++ b/src/sage/schemes/hyperelliptic_curves/hypellfrob.pyx @@ -78,7 +78,7 @@ def interval_products(M0, M1, target): INPUT: - ``M0``, ``M1`` -- matrices over `\ZZ/N\ZZ`, so that `M(t) = M_0 + M_1t` - - ``target`` -- a list of integers `a_0, b_0, \dots, a_n, b_n` + - ``target`` -- list of integers `a_0, b_0, \dots, a_n, b_n` ALGORITHM: @@ -116,7 +116,6 @@ def interval_products(M0, M1, target): [[20]] sage: [prod(Matrix(Integers(3^18), 1, 1, [t + 1]) for t in range(3,5))] [[20]] - """ # Sage objects that wrap the NTL objects cdef mat_ZZ_p_c mm0, mm1 @@ -163,7 +162,7 @@ def hypellfrob(p, N, Q): - ``p`` -- a prime - ``Q`` -- a monic polynomial in `\ZZ[x]` of odd degree; must have no - multiple roots mod `p`. + multiple roots mod `p` - ``N`` -- precision parameter; the output matrix will be correct modulo `p^N` The prime `p` should satisfy `p > (2g+1)(2N-1)`, where `g = @@ -200,7 +199,6 @@ def hypellfrob(p, N, Q): Remove the restriction on `p`. Probably by merging in Robert's code, which eventually needs a fast C++/NTL implementation. - """ # Sage objects that wrap the NTL objects cdef ntl_ZZ pp @@ -244,7 +242,7 @@ def hypellfrob(p, N, Q): raise ValueError("Could not compute frobenius matrix" ", because the curve is singular at p.") - R = Qp(p, N, print_mode="terse") + R = Qp(p, N, print_mode='terse') prec = big_oh(p**N) data = [[mm[j, i]._integer_() + prec for i in range(2 * g)] for j in range(2 * g)] diff --git a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field.py b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field.py old mode 100644 new mode 100755 index b9106a7082e..469e3eaa2f8 --- a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field.py +++ b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field.py @@ -71,9 +71,9 @@ class HyperellipticCurve_finite_field(hyperelliptic_generic.HyperellipticCurve_g ProjectivePlaneCurve_finite_field): def _frobenius_coefficient_bound_charpoly(self): r""" - Computes bound on number of `p`-adic digits needed to recover + Compute bound on number of `p`-adic digits needed to recover frobenius polynomial computing the characteristic polynomial - of the frobenius matrix, i.e. returns `B` so that knowledge of + of the frobenius matrix, i.e. return `B` so that knowledge of `a_1`, ..., `a_g` modulo `p^B` determine frobenius polynomial uniquely. @@ -125,9 +125,9 @@ def _frobenius_coefficient_bound_charpoly(self): def _frobenius_coefficient_bound_traces(self, n=1): r""" - Computes bound on number of `p`-adic digits needed to recover + Compute bound on number of `p`-adic digits needed to recover the number of rational points on `n` extensions computing - traces of the frobenius matrix powers, i.e. returns `B` so that + traces of the frobenius matrix powers, i.e. return `B` so that knowledge of `\tr(M^1)`, ..., `\tr(M^n)` modulo `p^B` determine `N_1`, ..., `N_n` uniquely. @@ -184,7 +184,7 @@ def frobenius_matrix_hypellfrob(self, N=None): If `N` not supplied, a default value is selected, which is the minimum needed to recover the charpoly unambiguously. - .. note:: + .. NOTE:: Implemented using ``hypellfrob``, which means it only works over the prime field `GF(p)`, and requires `p > (2g+1)(2N-1)`. @@ -259,7 +259,7 @@ def frobenius_matrix(self, N=None, algorithm='hypellfrob'): If `N` not supplied, a default value is selected, which is the minimum needed to recover the charpoly unambiguously. - .. note:: + .. NOTE:: Currently only implemented using ``hypellfrob``, which means it only works over the prime field `GF(p)`, @@ -480,7 +480,7 @@ def frobenius_polynomial_pari(self): sage: H.frobenius_polynomial_pari() x^2 - 15*x + 12167 - Over prime fields of odd characteristic, `h` may be non-zero:: + Over prime fields of odd characteristic, `h` may be nonzero:: sage: K = GF(101) sage: R. = PolynomialRing(K) @@ -543,7 +543,7 @@ def frobenius_polynomial(self): sage: H.frobenius_polynomial() x^4 - 3*x^3 + 10*x^2 - 81*x + 729 - Over prime fields of odd characteristic, `h` may be non-zero:: + Over prime fields of odd characteristic, `h` may be nonzero:: sage: K = GF(101) sage: R. = PolynomialRing(K) @@ -970,7 +970,7 @@ def count_points_frobenius_polynomial(self, n=1, f=None): S = PowerSeriesRing(QQ, default_prec=n+1, names='t') frev = f.reverse() # the coefficients() method of power series only returns - # non-zero coefficients so let us use the list() method but + # nonzero coefficients so let us use the list() method but # this does not work for zero which gives the empty list flog = S(frev).log() return [q**(i+1) + 1 + ZZ((i+1)*flog[i+1]) for i in range(n)] @@ -1127,7 +1127,7 @@ def count_points(self, n=1): INPUT: - - ``n`` -- integer. + - ``n`` -- integer OUTPUT: @@ -1443,12 +1443,12 @@ def _Cartier_matrix_cached(self): r""" INPUT: - - 'E' -- Hyperelliptic Curve of the form `y^2 = f(x)` over a + - ``self`` -- Hyperelliptic Curve of the form `y^2 = f(x)` over a finite field, `\GF{q}` OUTPUT: - - matrix(Fq,M)' The matrix `M = (c_(pi-j)), f(x)^((p-1)/2) = \sum c_i x^i` + - 'matrix(Fq,M)' The matrix `M = (c_(pi-j)), f(x)^((p-1)/2) = \sum c_i x^i` - 'Coeff' List of Coeffs of F, this is needed for Hasse-Witt function. - 'g' genus of the curve self, this is needed by a-number. - 'Fq' is the base field of self, and it is needed for Hasse-Witt @@ -1578,11 +1578,13 @@ def Cartier_matrix(self): r""" INPUT: - - ``E`` : Hyperelliptic Curve of the form `y^2 = f(x)` over a finite field, `\GF{q}` + - ``self`` -- Hyperelliptic Curve of the form `y^2 = f(x)` over a + finite field, `\GF{q}` OUTPUT: - - ``M``: The matrix `M = (c_{pi-j})`, where `c_i` are the coefficients of `f(x)^{(p-1)/2} = \sum c_i x^i` + The matrix `M = (c_{pi-j})`, where `c_i` are the coefficients of + `f(x)^{(p-1)/2} = \sum c_i x^i`. REFERENCES: @@ -1776,11 +1778,13 @@ def Hasse_Witt(self): r""" INPUT: - - ``E`` : Hyperelliptic Curve of the form `y^2 = f(x)` over a finite field, `\GF{q}` + - ``self`` -- Hyperelliptic Curve of the form `y^2 = f(x)` over a + finite field, `\GF{q}` OUTPUT: - - ``N`` : The matrix `N = M M^p \dots M^{p^{g-1}}` where `M = c_{pi-j}`, and `f(x)^{(p-1)/2} = \sum c_i x^i` + The matrix `N = M M^p \dots M^{p^{g-1}}` where `M = c_{pi-j}`, and + `f(x)^{(p-1)/2} = \sum c_i x^i`. Reference-N. Yui. On the Jacobian varieties of hyperelliptic curves over fields of characteristic `p > 2`. @@ -1833,12 +1837,10 @@ def a_number(self): r""" INPUT: - - ``E``: Hyperelliptic Curve of the form `y^2 = f(x)` over a finite field, `\GF{q}` - - OUTPUT: - - - ``a`` : a-number + - ``self`` -- Hyperelliptic Curve of the form `y^2 = f(x)` over a + finite field, `\GF{q}` + OUTPUT: a-number EXAMPLES:: @@ -1875,12 +1877,10 @@ def p_rank(self): r""" INPUT: - - ``E`` : Hyperelliptic Curve of the form `y^2 = f(x)` over a finite field, `\GF{q}` - - OUTPUT: - - - ``pr`` :p-rank + - ``self`` -- Hyperelliptic Curve of the form `y^2 = f(x)` over a + finite field, `\GF{q}` + OUTPUT: p-rank EXAMPLES:: diff --git a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_generic.py b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_generic.py old mode 100644 new mode 100755 index fcd904998dd..6074f66e699 --- a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_generic.py +++ b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_generic.py @@ -130,7 +130,7 @@ def __init__(self, PP, f, h=None, names=None, genus=None): def change_ring(self, R): """ - Returns this HyperellipticCurve over a new base ring ``R``. + Return this HyperellipticCurve over a new base ring ``R``. EXAMPLES:: @@ -201,7 +201,7 @@ def hyperelliptic_polynomials(self, K=None, var='x'): def is_singular(self): r""" - Returns False, because hyperelliptic curves are smooth projective + Return ``False``, because hyperelliptic curves are smooth projective curves, as checked on construction. EXAMPLES:: @@ -229,7 +229,7 @@ def is_singular(self): def is_smooth(self): r""" - Returns True, because hyperelliptic curves are smooth projective + Return ``True``, because hyperelliptic curves are smooth projective curves, as checked on construction. EXAMPLES:: @@ -258,7 +258,7 @@ def is_smooth(self): def is_x_coord(self, x): """ - Return True if ``x`` is the `x`-coordinate of a point on this curve. + Return ``True`` if ``x`` is the `x`-coordinate of a point on this curve. .. SEEALSO:: @@ -271,9 +271,8 @@ def is_x_coord(self, x): - ``x`` -- an element of the base ring of the curve - OUTPUT: - - A bool stating whether or not `x` is a x-coordinate of a point on the curve + OUTPUT: boolean stating whether or not `x` is a x-coordinate of a point + on the curve EXAMPLES: @@ -373,13 +372,11 @@ def lift_x(self, x, all=False): - ``x`` -- an element of the base ring of the curve - - ``all`` (bool, default ``False``) -- if ``True``, return a - (possibly empty) list of all points; if ``False``, return - just one point, or raise a :class:`ValueError` if there are none. - - OUTPUT: + - ``all`` -- boolean (default: ``False``); if ``True``, return a + (possibly empty) list of all points. If ``False``, return + just one point, or raise a :exc:`ValueError` if there are none. - A point or list of up to two points on this curve. + OUTPUT: a point or list of up to two points on this curve .. SEEALSO:: @@ -525,7 +522,8 @@ def jacobian(self): def odd_degree_model(self): r""" - Return an odd degree model of self, or raise ValueError if one does not exist over the field of definition. + Return an odd degree model of ``self``, or raise :exc:`ValueError` if + one does not exist over the field of definition. EXAMPLES:: @@ -606,7 +604,8 @@ def odd_degree_model(self): def has_odd_degree_model(self): r""" - Return True if an odd degree model of self exists over the field of definition; False otherwise. + Return ``True`` if an odd degree model of ``self`` exists over the + field of definition; ``False`` otherwise. Use ``odd_degree_model`` to calculate an odd degree model. @@ -657,8 +656,8 @@ def monsky_washnitzer_gens(self): def invariant_differential(self): """ - Returns `dx/2y`, as an element of the Monsky-Washnitzer cohomology - of self + Return `dx/2y`, as an element of the Monsky-Washnitzer cohomology + of ``self``. EXAMPLES:: @@ -666,7 +665,6 @@ def invariant_differential(self): sage: C = HyperellipticCurve(x^5 - 4*x + 4) sage: C.invariant_differential() 1 dx/2y - """ import sage.schemes.hyperelliptic_curves.monsky_washnitzer as m_w S = m_w.SpecialHyperellipticQuotientRing(self) @@ -681,8 +679,8 @@ def local_coordinates_at_nonweierstrass(self, P, prec=20, name='t'): INPUT: - - ``P = (a, b)`` -- a non-Weierstrass point on self - - ``prec`` -- desired precision of the local coordinates + - ``P = (a, b)`` -- a non-Weierstrass point on ``self`` + - ``prec`` -- desired precision of the local coordinates - ``name`` -- gen of the power series ring (default: ``t``) OUTPUT: @@ -733,7 +731,7 @@ def local_coordinates_at_weierstrass(self, P, prec=20, name='t'): INPUT: - - ``P`` -- a finite Weierstrass point on self + - ``P`` -- a finite Weierstrass point on ``self`` - ``prec`` -- desired precision of the local coordinates - ``name`` -- gen of the power series ring (default: `t`) @@ -835,11 +833,11 @@ def local_coordinates_at_infinity(self, prec=20, name='t'): def local_coord(self, P, prec=20, name='t'): """ - Calls the appropriate local_coordinates function + Call the appropriate local_coordinates function. INPUT: - - ``P`` -- a point on self + - ``P`` -- a point on ``self`` - ``prec`` -- desired precision of the local coordinates - ``name`` -- generator of the power series ring (default: ``t``) diff --git a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_padic_field.py b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_padic_field.py old mode 100644 new mode 100755 index 10c471035a7..654e33c80fc --- a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_padic_field.py +++ b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_padic_field.py @@ -50,7 +50,7 @@ def local_analytic_interpolation(self, P, Q): INPUT: - - P and Q points on self in the same residue disc + - ``P``, ``Q`` -- points on ``self`` in the same residue disc OUTPUT: @@ -149,9 +149,9 @@ def local_analytic_interpolation(self, P, Q): def weierstrass_points(self): """ - Return the Weierstrass points of self defined over self.base_ring(), - that is, the point at infinity and those points in the support - of the divisor of `y` + Return the Weierstrass points of ``self`` defined over + ``self.base_ring()``, that is, the point at infinity and those points + in the support of the divisor of `y`. EXAMPLES:: @@ -168,7 +168,7 @@ def weierstrass_points(self): def is_in_weierstrass_disc(self, P): """ - Checks if `P` is in a Weierstrass disc + Check if `P` is in a Weierstrass disc. EXAMPLES:: @@ -198,7 +198,8 @@ def is_in_weierstrass_disc(self, P): def is_weierstrass(self, P): """ - Checks if `P` is a Weierstrass point (i.e., fixed by the hyperelliptic involution) + Check if `P` is a Weierstrass point (i.e., fixed by the hyperelliptic + involution). EXAMPLES:: @@ -228,8 +229,8 @@ def is_weierstrass(self, P): def find_char_zero_weier_point(self, Q): """ - Given `Q` a point on self in a Weierstrass disc, finds the - center of the Weierstrass disc (if defined over self.base_ring()) + Given `Q` a point on ``self`` in a Weierstrass disc, finds the + center of the Weierstrass disc (if defined over ``self.base_ring()``). EXAMPLES:: @@ -263,7 +264,7 @@ def find_char_zero_weier_point(self, Q): def residue_disc(self, P): """ - Gives the residue disc of `P` + Give the residue disc of `P`. EXAMPLES:: @@ -309,7 +310,7 @@ def residue_disc(self, P): def is_same_disc(self, P, Q): """ - Checks if `P,Q` are in same residue disc + Check if `P,Q` are in same residue disc. EXAMPLES:: @@ -338,13 +339,11 @@ def tiny_integrals(self, F, P, Q): INPUT: - - F a list of functions `f_i` - - P a point on self - - Q a point on self (in the same residue disc as P) + - ``F`` -- list of functions `f_i` + - ``P`` -- point on ``self`` + - ``Q`` -- point on ``self`` (in the same residue disc as `P`) - OUTPUT: - - The integrals `\int_P^Q f_i dx/2y` + OUTPUT: the integrals `\int_P^Q f_i dx/2y` EXAMPLES:: @@ -373,7 +372,6 @@ def tiny_integrals(self, F, P, Q): Traceback (most recent call last): ... ValueError: (11^-2 + O(11^3) : 11^-5 + 8*11^-2 + O(11^0) : 1 + O(11^5)) and (0 : 3 + 8*11 + 2*11^2 + 8*11^3 + 2*11^4 + O(11^5) : 1 + O(11^5)) are not in the same residue disc - """ x, y, z = self.local_analytic_interpolation(P, Q) #homogeneous coordinates x = x/z @@ -402,12 +400,10 @@ def tiny_integrals_on_basis(self, P, Q): INPUT: - - P a point on self - - Q a point on self (in the same residue disc as P) + - ``P`` -- point on ``self`` + - ``Q`` -- point on ``self`` (in the same residue disc as `P`) - OUTPUT: - - The integrals `\{\int_P^Q x^i dx/2y \}_{i=0}^{2g-1}` + OUTPUT: the integrals `\{\int_P^Q x^i dx/2y \}_{i=0}^{2g-1}` EXAMPLES:: @@ -436,7 +432,6 @@ def tiny_integrals_on_basis(self, P, Q): Traceback (most recent call last): ... ValueError: (11^-2 + O(11^3) : 11^-5 + 8*11^-2 + O(11^0) : 1 + O(11^5)) and (0 : 3 + 8*11 + 2*11^2 + 8*11^3 + 2*11^4 + O(11^5) : 1 + O(11^5)) are not in the same residue disc - """ if P == Q: V = VectorSpace(self.base_ring(), 2*self.genus()) @@ -477,17 +472,16 @@ def teichmuller(self, P): def coleman_integrals_on_basis(self, P, Q, algorithm=None): r""" - Computes the Coleman integrals `\{\int_P^Q x^i dx/2y \}_{i=0}^{2g-1}` + Compute the Coleman integrals `\{\int_P^Q x^i dx/2y \}_{i=0}^{2g-1}`. INPUT: - - P point on self - - Q point on self - - algorithm (optional) = None (uses Frobenius) or teichmuller (uses Teichmuller points) - - OUTPUT: + - ``P`` -- point on ``self`` + - ``Q`` -- point on ``self`` + - ``algorithm`` -- ``None`` (default, uses Frobenius) or teichmuller + (uses Teichmuller points) - the Coleman integrals `\{\int_P^Q x^i dx/2y \}_{i=0}^{2g-1}` + OUTPUT: the Coleman integrals `\{\int_P^Q x^i dx/2y \}_{i=0}^{2g-1}` EXAMPLES:: @@ -705,14 +699,13 @@ def coleman_integral(self, w, P, Q, algorithm='None'): INPUT: - - w differential (if one of P,Q is Weierstrass, w must be odd) - - P point on self - - Q point on self - - algorithm (optional) = None (uses Frobenius) or teichmuller (uses Teichmuller points) - - OUTPUT: + - ``w`` -- differential (if one of P,Q is Weierstrass, w must be odd) + - ``P`` -- point on ``self`` + - ``Q`` -- point on ``self`` + - ``algorithm`` -- ``None`` (default, uses Frobenius) or teichmuller + (uses Teichmuller points) - the Coleman integral `\int_P^Q w` + OUTPUT: the Coleman integral `\int_P^Q w` EXAMPLES: @@ -837,7 +830,6 @@ def coleman_integral(self, w, P, Q, algorithm='None'): - Robert Bradshaw (2007-03) - Kiran Kedlaya (2008-05) - Jennifer Balakrishnan (2010-02) - """ # TODO: implement Jacobians and show the relationship directly import sage.schemes.hyperelliptic_curves.monsky_washnitzer as monsky_washnitzer @@ -872,7 +864,7 @@ def coleman_integral(self, w, P, Q, algorithm='None'): def frobenius(self, P=None): """ - Returns the `p`-th power lift of Frobenius of `P` + Return the `p`-th power lift of Frobenius of `P`. EXAMPLES:: @@ -963,7 +955,7 @@ def _frob(P): def newton_sqrt(self, f, x0, prec): r""" - Takes the square root of the power series `f` by Newton's method + Take the square root of the power series `f` by Newton's method. NOTE: @@ -1009,11 +1001,9 @@ def curve_over_ram_extn(self, deg): INPUT: - - deg: the degree of the ramified extension + - ``deg`` -- the degree of the ramified extension - OUTPUT: - - ``self`` over `\QQ_p(p^(1/deg))` + OUTPUT: ``self`` over `\QQ_p(p^(1/deg))` EXAMPLES:: @@ -1028,7 +1018,6 @@ def curve_over_ram_extn(self, deg): AUTHOR: - Jennifer Balakrishnan - """ from sage.schemes.hyperelliptic_curves.constructor import HyperellipticCurve K = self.base_ring() @@ -1045,16 +1034,15 @@ def curve_over_ram_extn(self, deg): def get_boundary_point(self, curve_over_extn, P): """ - Given self over an extension field, find a point in the disc of `P` near the boundary + Given ``self`` over an extension field, find a point in the disc of `P` + near the boundary. INPUT: - - curve_over_extn: self over a totally ramified extension - - P: Weierstrass point + - ``curve_over_extn`` -- ``self`` over a totally ramified extension + - ``P`` -- Weierstrass point - OUTPUT: - - a point in the disc of `P` near the boundary + OUTPUT: a point in the disc of `P` near the boundary EXAMPLES:: @@ -1072,7 +1060,6 @@ def get_boundary_point(self, curve_over_extn, P): AUTHOR: - Jennifer Balakrishnan - """ J = curve_over_extn.base_ring() a = J.gen() @@ -1082,17 +1069,15 @@ def get_boundary_point(self, curve_over_extn, P): def P_to_S(self, P, S): r""" - Given a finite Weierstrass point `P` and a point `S` - in the same disc, computes the Coleman integrals `\{\int_P^S x^i dx/2y \}_{i=0}^{2g-1}` + Given a finite Weierstrass point `P` and a point `S` in the same disc, + compute the Coleman integrals `\{\int_P^S x^i dx/2y \}_{i=0}^{2g-1}`. INPUT: - - P: finite Weierstrass point - - S: point in disc of P + - ``P`` -- finite Weierstrass point + - ``S`` -- point in disc of `P` - OUTPUT: - - Coleman integrals `\{\int_P^S x^i dx/2y \}_{i=0}^{2g-1}` + OUTPUT: Coleman integrals `\{\int_P^S x^i dx/2y \}_{i=0}^{2g-1}` EXAMPLES:: @@ -1109,7 +1094,6 @@ def P_to_S(self, P, S): AUTHOR: - Jennifer Balakrishnan - """ prec = self.base_ring().precision_cap() deg = (S[0]).parent().defining_polynomial().degree() @@ -1123,18 +1107,16 @@ def P_to_S(self, P, S): def coleman_integral_P_to_S(self, w, P, S): r""" Given a finite Weierstrass point `P` and a point `S` - in the same disc, computes the Coleman integral `\int_P^S w` + in the same disc, compute the Coleman integral `\int_P^S w`. INPUT: - - w: differential - - P: Weierstrass point - - S: point in the same disc of P (S is defined over an extension of `\QQ_p`; coordinates - of S are given in terms of uniformizer `a`) + - ``w`` -- differential + - ``P`` -- Weierstrass point + - ``S`` -- point in the same disc of `P` (S is defined over an extension + of `\QQ_p`; coordinates of S are given in terms of uniformizer `a`) - OUTPUT: - - Coleman integral `\int_P^S w` in terms of `a` + OUTPUT: Coleman integral `\int_P^S w` in terms of `a` EXAMPLES:: @@ -1155,7 +1137,6 @@ def coleman_integral_P_to_S(self, w, P, S): AUTHOR: - Jennifer Balakrishnan - """ prec = self.base_ring().precision_cap() deg = S[0].parent().defining_polynomial().degree() @@ -1167,20 +1148,20 @@ def coleman_integral_P_to_S(self, w, P, S): def S_to_Q(self, S, Q): r""" - Given `S` a point on self over an extension field, computes the - Coleman integrals `\{\int_S^Q x^i dx/2y \}_{i=0}^{2g-1}` + Given `S` a point on ``self`` over an extension field, compute the + Coleman integrals `\{\int_S^Q x^i dx/2y \}_{i=0}^{2g-1}`. **one should be able to feed `S,Q` into coleman_integral, but currently that segfaults** INPUT: - - S: a point with coordinates in an extension of `\QQ_p` (with unif. a) - - Q: a non-Weierstrass point defined over `\QQ_p` + - ``S`` -- a point with coordinates in an extension of `\QQ_p` (with unif. a) + - ``Q`` -- a non-Weierstrass point defined over `\QQ_p` OUTPUT: - the Coleman integrals `\{\int_S^Q x^i dx/2y \}_{i=0}^{2g-1}` in terms of `a` + The Coleman integrals `\{\int_S^Q x^i dx/2y \}_{i=0}^{2g-1}` in terms of `a`. EXAMPLES:: @@ -1205,7 +1186,6 @@ def S_to_Q(self, S, Q): AUTHOR: - Jennifer Balakrishnan - """ FS = self.frobenius(S) FS = (FS[0],FS[1]) @@ -1252,20 +1232,18 @@ def S_to_Q(self, S, Q): def coleman_integral_S_to_Q(self, w, S, Q): r""" - Compute the Coleman integral `\int_S^Q w` + Compute the Coleman integral `\int_S^Q w`. **one should be able to feed `S,Q` into coleman_integral, but currently that segfaults** INPUT: - - w: a differential - - S: a point with coordinates in an extension of `\QQ_p` - - Q: a non-Weierstrass point defined over `\QQ_p` - - OUTPUT: + - ``w`` -- a differential + - ``S`` -- a point with coordinates in an extension of `\QQ_p` + - ``Q`` -- a non-Weierstrass point defined over `\QQ_p` - the Coleman integral `\int_S^Q w` + OUTPUT: the Coleman integral `\int_S^Q w` EXAMPLES:: @@ -1308,15 +1286,15 @@ def coleman_integral_S_to_Q(self, w, S, Q): def coleman_integral_from_weierstrass_via_boundary(self, w, P, Q, d): r""" - Computes the Coleman integral `\int_P^Q w` via a boundary point + Compute the Coleman integral `\int_P^Q w` via a boundary point in the disc of `P`, defined over a degree `d` extension INPUT: - - w: a differential - - P: a Weierstrass point - - Q: a non-Weierstrass point - - d: degree of extension where coordinates of boundary point lie + - ``w`` -- a differential + - ``P`` -- a Weierstrass point + - ``Q`` -- a non-Weierstrass point + - ``d`` -- degree of extension where coordinates of boundary point lie OUTPUT: diff --git a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_rational_field.py b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_rational_field.py old mode 100644 new mode 100755 index 70cd588047f..dc9ddc3e3f5 --- a/src/sage/schemes/hyperelliptic_curves/hyperelliptic_rational_field.py +++ b/src/sage/schemes/hyperelliptic_curves/hyperelliptic_rational_field.py @@ -30,12 +30,12 @@ def matrix_of_frobenius(self, p, prec=20): INPUT: - - ``p`` (prime integer or pAdic ring / field) -- if ``p`` is an integer, + - ``p`` -- prime integer or pAdic ring / field; if ``p`` is an integer, constructs a ``pAdicField`` with ``p`` to compute the matrix of - Frobenius, otherwise uses the supplied pAdic ring or field. + Frobenius, otherwise uses the supplied pAdic ring or field - - ``prec`` (optional) -- if ``p`` is an prime integer, the `p`-adic - precision of the coefficient ring constructed. + - ``prec`` -- (optional) if ``p`` is an prime integer, the `p`-adic + precision of the coefficient ring constructed EXAMPLES:: @@ -67,7 +67,7 @@ def matrix_of_frobenius(self, p, prec=20): def lseries(self, prec=53): """ - Return the L-series of this hyperelliptic curve of genus 2. + Return the `L`-series of this hyperelliptic curve of genus 2. EXAMPLES:: diff --git a/src/sage/schemes/hyperelliptic_curves/invariants.py b/src/sage/schemes/hyperelliptic_curves/invariants.py old mode 100644 new mode 100755 index 7e3e659ba00..3910594a5af --- a/src/sage/schemes/hyperelliptic_curves/invariants.py +++ b/src/sage/schemes/hyperelliptic_curves/invariants.py @@ -18,7 +18,7 @@ def diffxy(f, x, xtimes, y, ytimes): r""" Differentiate a polynomial ``f``, ``xtimes`` with respect to ``x``, and - ```ytimes`` with respect to ``y``. + ``ytimes`` with respect to ``y``. EXAMPLES:: diff --git a/src/sage/schemes/hyperelliptic_curves/jacobian_endomorphism_utils.py b/src/sage/schemes/hyperelliptic_curves/jacobian_endomorphism_utils.py old mode 100644 new mode 100755 index 339964d7d08..032bc3105ba --- a/src/sage/schemes/hyperelliptic_curves/jacobian_endomorphism_utils.py +++ b/src/sage/schemes/hyperelliptic_curves/jacobian_endomorphism_utils.py @@ -142,11 +142,11 @@ def get_is_geom_field(f, C, bad_primes, B=200): INPUT: - - ``f`` -- a polynomial defining the hyperelliptic curve. + - ``f`` -- a polynomial defining the hyperelliptic curve - - ``C`` -- the hyperelliptic curve. + - ``C`` -- the hyperelliptic curve - - ``bad_primes`` -- the list of odd primes of bad reduction. + - ``bad_primes`` -- the list of odd primes of bad reduction - ``B`` -- (default: 200) the bound which appears in the statement of the algorithm from [Lom2019]_ @@ -252,9 +252,9 @@ def is_geom_trivial_when_field(C, bad_primes, B=200): INPUT: - - ``C`` -- the hyperelliptic curve. + - ``C`` -- the hyperelliptic curve - - ``bad_primes`` -- the list of odd primes of bad reduction. + - ``bad_primes`` -- the list of odd primes of bad reduction - ``B`` -- (default: 200) the bound which appears in the statement of the algorithm from [Lom2019]_ diff --git a/src/sage/schemes/hyperelliptic_curves/jacobian_generic.py b/src/sage/schemes/hyperelliptic_curves/jacobian_generic.py old mode 100644 new mode 100755 index c4544e7cdfc..efc2a805bc0 --- a/src/sage/schemes/hyperelliptic_curves/jacobian_generic.py +++ b/src/sage/schemes/hyperelliptic_curves/jacobian_generic.py @@ -146,9 +146,7 @@ def dimension(self): """ Return the dimension of this Jacobian. - OUTPUT: - - Integer + OUTPUT: integer EXAMPLES:: @@ -191,11 +189,9 @@ def _have_established_geometrically_trivial(self): INPUT: - - ``self`` -- The Jacobian. - - OUTPUT: + - ``self`` -- the Jacobian - The boolean ``False``; this will be updated by other methods. + OUTPUT: the boolean ``False``; this will be updated by other methods EXAMPLES: @@ -222,11 +218,9 @@ def _have_established_geometrically_field(self): INPUT: - - ``self`` -- The Jacobian. + - ``self`` -- the Jacobian - OUTPUT: - - The boolean ``False``; this will be updated by other methods. + OUTPUT: the boolean ``False``; this will be updated by other methods EXAMPLES: @@ -253,9 +247,9 @@ def geometric_endomorphism_algebra_is_field(self, B=200, proof=False): - ``B`` -- (default: 200) the bound which appears in the statement of the algorithm from [Lom2019]_ - - ``proof`` -- (default: ``False``) whether or not to insist on a provably - correct answer. This is related to the warning in the docstring - of this module: if this function returns ``False``, then + - ``proof`` -- boolean (default: ``False``); whether or not to insist + on a provably correct answer. This is related to the warning in the + docstring of this module: if this function returns ``False``, then strictly speaking this has not been proven to be ``False`` until one has exhibited a non-trivial endomorphism, which these methods are not designed to carry out. If one is convinced that this method should @@ -324,14 +318,14 @@ def geometric_endomorphism_ring_is_ZZ(self, B=200, proof=False): - ``B`` -- (default: 200) the bound which appears in the statement of the algorithm from [Lom2019]_ - - ``proof`` -- (default: ``False``) whether or not to insist on a provably - correct answer. This is related to the warning in the module docstring - of `jacobian_endomorphisms.py`: if this function returns ``False``, then - strictly speaking this has not been proven to be ``False`` until one has - exhibited a non-trivial endomorphism, which the methods in that module - are not designed to carry out. If one is convinced that this method - should return ``True``, but it is returning ``False``, then this can be - exhibited by increasing `B`. + - ``proof`` -- boolean (default: ``False``); whether or not to insist + on a provably correct answer. This is related to the warning in the + module docstring of `jacobian_endomorphisms.py`: if this function + returns ``False``, then strictly speaking this has not been proven to + be ``False`` until one has exhibited a non-trivial endomorphism, + which the methods in that module are not designed to carry out. If + one is convinced that this method should return ``True``, but it is + returning ``False``, then this can be exhibited by increasing `B`. OUTPUT: diff --git a/src/sage/schemes/hyperelliptic_curves/jacobian_morphism.py b/src/sage/schemes/hyperelliptic_curves/jacobian_morphism.py old mode 100644 new mode 100755 index 0a820f5bda6..50ec2c63748 --- a/src/sage/schemes/hyperelliptic_curves/jacobian_morphism.py +++ b/src/sage/schemes/hyperelliptic_curves/jacobian_morphism.py @@ -361,11 +361,10 @@ def __init__(self, parent, polys, check=True): INPUT: - - parent -- the parent Homset - - polys -- Mumford's `u` and `v` polynomials - - check (default: ``True``) -- if ``True``, ensure that - polynomials define a divisor on the appropriate curve and are - reduced + - ``parent`` -- the parent Homset + - ``polys`` -- Mumford's `u` and `v` polynomials + - ``check`` -- boolean (default: ``True``); if ``True``, ensure that + polynomials define a divisor on the appropriate curve and are reduced .. warning:: @@ -589,7 +588,7 @@ def point_of_jacobian_of_curve(self): def __list__(self): r""" Return a list `(a(x), b(x))` of the polynomials giving the - Mumford representation of self. + Mumford representation of ``self``. TESTS:: @@ -613,7 +612,7 @@ def __list__(self): def __tuple__(self): r""" Return a tuple `(a(x), b(x))` of the polynomials giving the - Mumford representation of self. + Mumford representation of ``self``. TESTS:: @@ -637,7 +636,7 @@ def __tuple__(self): def __getitem__(self, n): r""" Return the `n`-th item of the pair `(a(x), b(x))` - of polynomials giving the Mumford representation of self. + of polynomials giving the Mumford representation of ``self``. TESTS:: @@ -667,7 +666,7 @@ def __getitem__(self, n): def _richcmp_(self, other, op): r""" - Compare self and other. + Compare ``self`` and ``other``. TESTS:: @@ -789,7 +788,6 @@ def __neg__(self): (u^2 - t, v + u + 1) sage: Q + (-Q) # indirect doctest (1) - """ if self.is_zero(): return self @@ -810,7 +808,7 @@ def __neg__(self): def _add_(self,other): r""" - Return a Mumford representative of the divisor self + other. + Return a Mumford representative of the divisor ``self + other``. EXAMPLES:: @@ -841,7 +839,7 @@ def _add_(self,other): def _sub_(self, other): r""" - Return a Mumford representative of the divisor self - other. + Return a Mumford representative of the divisor ``self - other``. EXAMPLES:: diff --git a/src/sage/schemes/hyperelliptic_curves/mestre.py b/src/sage/schemes/hyperelliptic_curves/mestre.py old mode 100644 new mode 100755 index be6439d7b3e..83a4b209174 --- a/src/sage/schemes/hyperelliptic_curves/mestre.py +++ b/src/sage/schemes/hyperelliptic_curves/mestre.py @@ -32,32 +32,30 @@ def HyperellipticCurve_from_invariants(i, reduced=True, precision=None, algorithm='default'): r""" - Returns a hyperelliptic curve with the given Igusa-Clebsch invariants up to + Return a hyperelliptic curve with the given Igusa-Clebsch invariants up to scaling. The output is a curve over the field in which the Igusa-Clebsch invariants are given. The output curve is unique up to isomorphism over the algebraic closure. If no such curve exists over the given field, then raise a - ValueError. + :exc:`ValueError`. INPUT: - ``i`` -- list or tuple of length 4 containing the four Igusa-Clebsch - invariants: I2,I4,I6,I10. - - ``reduced`` -- Boolean (default = True) If True, tries to reduce the - polynomial defining the hyperelliptic curve using the function + invariants: I2,I4,I6,I10 + - ``reduced`` -- boolean (default: ``True``); if ``True``, tries to reduce + the polynomial defining the hyperelliptic curve using the function :func:`reduce_polynomial` (see the :func:`reduce_polynomial` documentation for more details). - - ``precision`` -- integer (default = None) Which precision for real and + - ``precision`` -- integer (default: ``None``); which precision for real and complex numbers should the reduction use. This only affects the - reduction, not the correctness. If None, the algorithm uses the default + reduction, not the correctness. If ``None``, the algorithm uses the default 53 bit precision. - ``algorithm`` -- ``'default'`` or ``'magma'``. If set to ``'magma'``, uses - Magma to parameterize Mestre's conic (needs Magma to be installed). + Magma to parameterize Mestre's conic (needs Magma to be installed) - OUTPUT: - - A hyperelliptic curve object. + OUTPUT: a hyperelliptic curve object EXAMPLES: @@ -228,13 +226,11 @@ def Mestre_conic(i, xyz=False, names='u,v,w'): - ``i`` -- list or tuple of length 4 containing the four Igusa-Clebsch invariants: I2, I4, I6, I10 - - ``xyz`` -- Boolean (default: ``False``) if ``True``, the algorithm also + - ``xyz`` -- boolean (default: ``False``); if ``True``, the algorithm also returns three invariants `x`,`y`,`z` used in Mestre's algorithm - - ``names`` (default: ``'u,v,w'``) -- the variable names for the conic - - OUTPUT: + - ``names`` -- (default: ``'u,v,w'``) the variable names for the conic - A Conic object + OUTPUT: a Conic object EXAMPLES: @@ -276,7 +272,6 @@ def Mestre_conic(i, xyz=False, names='u,v,w'): 321 and 332 of [Mes1991]_. See the code or [LY2001]_ for the detailed formulae defining x, y, z and L. - """ from sage.structure.sequence import Sequence k = Sequence(i).universe() diff --git a/src/sage/schemes/hyperelliptic_curves/monsky_washnitzer.py b/src/sage/schemes/hyperelliptic_curves/monsky_washnitzer.py old mode 100644 new mode 100755 index 0876bbcb740..7e9b3bcb7a6 --- a/src/sage/schemes/hyperelliptic_curves/monsky_washnitzer.py +++ b/src/sage/schemes/hyperelliptic_curves/monsky_washnitzer.py @@ -100,7 +100,7 @@ def __init__(self, parent, p0, p1, p2, check=True): - ``p0``, ``p1``, ``p2`` -- coefficients; must be coercible into parent.poly_ring() - - ``check`` -- bool (default: ``True``): whether to carry + - ``check`` -- boolean (default: ``True``); whether to carry out coercion EXAMPLES:: @@ -279,8 +279,8 @@ def scalar_multiply(self, scalar): INPUT: - - ``scalar`` -- either an element of base_ring, or an - element of poly_ring. + - ``scalar`` -- either an element of ``base_ring``, or an + element of ``poly_ring`` EXAMPLES:: @@ -608,7 +608,7 @@ def _element_constructor_(self, *args, check=True): - ``p0``, ``p1``, ``p2`` -- coefficients; must be coercible into poly_ring() - - ``check`` -- bool (default: ``True``): whether to carry + - ``check`` -- boolean (default: ``True``); whether to carry out coercion EXAMPLES:: @@ -664,11 +664,9 @@ def transpose_list(input) -> list[list]: """ INPUT: - - ``input`` -- a list of lists, each list of the same length + - ``input`` -- list of lists, each list of the same length - OUTPUT: - - - ``output`` -- a list of lists such that output[i][j] = input[j][i] + OUTPUT: list of lists such that ``output[i][j] = input[j][i]`` EXAMPLES:: @@ -1026,7 +1024,7 @@ def reduce_all(Q, p, coeffs, offset, compute_exact_form=False): OUTPUT: - ``A``, ``B`` -- pair such that the input differential is - cohomologous to (A + Bx) dx/y. + cohomologous to (A + Bx) dx/y .. NOTE:: @@ -1104,9 +1102,9 @@ def frobenius_expansion_by_newton(Q, p, M): `Q(x) = x^3 + ax + b`, whose coefficient ring is a `Z/(p^M)Z`-algebra - - ``p`` -- residue characteristic of the p-adic field + - ``p`` -- residue characteristic of the `p`-adic field - - ``M`` -- p-adic precision of the coefficient ring + - ``M`` -- `p`-adic precision of the coefficient ring (this will be used to determine the number of Newton iterations) OUTPUT: @@ -1114,7 +1112,7 @@ def frobenius_expansion_by_newton(Q, p, M): - ``F0``, ``F1`` -- elements of ``SpecialCubicQuotientRing(Q)``, as described above - - ``r`` -- non-negative integer, as described above + - ``r`` -- nonnegative integer, as described above EXAMPLES:: @@ -1302,7 +1300,7 @@ def frobenius_expansion_by_series(Q, p, M): - ``F0``, ``F1`` -- elements of ``SpecialCubicQuotientRing(Q)``, as described above - - ``r`` -- non-negative integer, as described above + - ``r`` -- nonnegative integer, as described above EXAMPLES:: @@ -1380,7 +1378,7 @@ def adjusted_prec(p, prec): - ``p`` -- a prime ``p >= 5`` - - ``prec`` -- integer, desired output precision, ``prec >= 1`` + - ``prec`` -- integer; desired output precision, ``prec >= 1`` OUTPUT: adjusted precision (usually slightly more than ``prec``) @@ -1808,7 +1806,6 @@ def matrix_of_frobenius_hyperelliptic(Q, p=None, prec=None, M=None): [ 3*5 + 5^2 + O(5^3) 3*5 + O(5^3) 4*5 + O(5^3) 2 + 5^2 + O(5^3)] [ 4*5 + 4*5^2 + O(5^3) 3*5 + 2*5^2 + O(5^3) 5 + 3*5^2 + O(5^3) 2*5 + 2*5^2 + O(5^3)] [ 5^2 + O(5^3) 5 + 4*5^2 + O(5^3) 4*5 + 3*5^2 + O(5^3) 2*5 + O(5^3)] - """ prof = Profiler() prof("setup") @@ -1937,7 +1934,7 @@ def change_ring(self, R): def __call__(self, *x): """ - Evaluate ``self`` at given arguments + Evaluate ``self`` at given arguments. EXAMPLES:: @@ -1985,7 +1982,7 @@ def __invert__(self): def __bool__(self): """ - Return True iff ``self`` is not zero. + Return ``True`` iff ``self`` is not zero. EXAMPLES:: @@ -2282,7 +2279,7 @@ def coeffs(self, R=None): OUTPUT: - - ``coeffs`` -- a list of coefficients of powers of `x` for each power + - ``coeffs`` -- list of coefficients of powers of `x` for each power of `y` - ``n`` -- an offset indicating the power of `y` of the first list @@ -2546,7 +2543,7 @@ def zero(self): def gens(self): """ - Return the generators of ``self`` + Return the generators of ``self``. EXAMPLES:: @@ -2560,7 +2557,7 @@ def gens(self): def x(self): r""" - Return the generator `x` of ``self`` + Return the generator `x` of ``self``. EXAMPLES:: @@ -2574,7 +2571,7 @@ def x(self): def y(self): r""" - Return the generator `y` of ``self`` + Return the generator `y` of ``self``. EXAMPLES:: @@ -2832,7 +2829,7 @@ def __init__(self, parent, val, offset=0): - ``val`` -- element of the base ring, or list of coefficients - - ``offset`` -- (default: 0) if non-zero, shift val by `y^\text{offset}` + - ``offset`` -- (default: 0) if nonzero, shift val by `y^\text{offset}` EXAMPLES:: @@ -3158,7 +3155,7 @@ def reduce_neg_y_fast(self, even_degree_only=False): sage: (y^-5*x^2+y^-1*x).diff().reduce_neg_y_fast() ((y^-1)*x + (y^-5)*x^2, 0 dx/2y) - It leaves non-negative powers of `y` alone:: + It leaves nonnegative powers of `y` alone:: sage: y.diff() (-3*1 + 5*x^4) dx/2y @@ -3448,11 +3445,9 @@ def coeffs(self, R=None): INPUT: - - R -- An (optional) base ring in which to cast the coefficients + - ``R`` -- an (optional) base ring in which to cast the coefficients - OUTPUT: - - The raw coefficients of `A` where ``self`` is `A dx/2y`. + OUTPUT: the raw coefficients of `A` where ``self`` is `A dx/2y` EXAMPLES:: @@ -3479,9 +3474,7 @@ def coleman_integral(self, P, Q): - `P`, `Q` -- two points on the underlying curve - OUTPUT: - - `\int_P^Q \text{self}` + OUTPUT: `\int_P^Q \text{self}` EXAMPLES:: @@ -3572,16 +3565,14 @@ def base_extend(self, R): def change_ring(self, R): """ - Return a new differential ring which is self with the coefficient + Return a new differential ring which is ``self`` with the coefficient ring changed to `R`. INPUT: - ``R`` -- ring of coefficients - OUTPUT: - - ``self`` with the coefficient ring changed to `R`. + OUTPUT: ``self`` with the coefficient ring changed to `R` EXAMPLES:: @@ -3635,7 +3626,7 @@ def dimension(self): def Q(self): """ Return `Q(x)` where the model of the underlying hyperelliptic curve - of self is given by `y^2 = Q(x)`. + of ``self`` is given by `y^2 = Q(x)`. EXAMPLES:: @@ -3858,7 +3849,7 @@ def _element_constructor_(self, val=0, offset=0): - ``parent`` -- Monsky-Washnitzer differential ring (instance of class :class:`~MonskyWashnitzerDifferentialRing` - ``val`` -- element of the base ring, or list of coefficients - - ``offset`` -- (default: 0) if non-zero, shift val by `y^\text{offset}` + - ``offset`` -- (default: 0) if nonzero, shift val by `y^\text{offset}` EXAMPLES:: diff --git a/src/sage/schemes/jacobians/abstract_jacobian.py b/src/sage/schemes/jacobians/abstract_jacobian.py old mode 100644 new mode 100755 index f5c69ea99c1..6ec2880a627 --- a/src/sage/schemes/jacobians/abstract_jacobian.py +++ b/src/sage/schemes/jacobians/abstract_jacobian.py @@ -28,7 +28,7 @@ def is_Jacobian(J): """ - Return True if `J` is of type Jacobian_generic. + Return ``True`` if `J` is of type ``Jacobian_generic``. EXAMPLES:: @@ -188,7 +188,7 @@ def _point(self): OUTPUT: - This method always raises a :class:`NotImplementedError`; it is + This method always raises a :exc:`NotImplementedError`; it is only abstract. EXAMPLES:: @@ -225,9 +225,9 @@ def change_ring(self, R): INPUT: - - ``R`` -- a field. The new base ring. + - ``R`` -- a field; the new base ring - OUTPUT: The Jacobian over the ring `R`. + OUTPUT: the Jacobian over the ring `R` EXAMPLES:: @@ -248,9 +248,9 @@ def base_extend(self, R): INPUT: - - ``R`` -- a field. The new base field. + - ``R`` -- a field; the new base field - OUTPUT: The Jacobian over the ring `R`. + OUTPUT: the Jacobian over the ring `R` EXAMPLES:: diff --git a/src/sage/schemes/plane_conics/con_field.py b/src/sage/schemes/plane_conics/con_field.py old mode 100644 new mode 100755 index 723bc46e916..8ad15fdf5b4 --- a/src/sage/schemes/plane_conics/con_field.py +++ b/src/sage/schemes/plane_conics/con_field.py @@ -153,7 +153,7 @@ def cache_point(self, p): def coefficients(self): r""" - Gives a the `6` coefficients of the conic ``self`` + Give a the `6` coefficients of the conic ``self`` in lexicographic order. EXAMPLES:: @@ -172,7 +172,7 @@ def coefficients(self): def derivative_matrix(self): r""" - Gives the derivative of the defining polynomial of + Give the derivative of the defining polynomial of the conic ``self``, which is a linear map, as a `3 \times 3` matrix. @@ -399,33 +399,32 @@ def gens(self): sage: C. = Conic(GF(3), [1, 1, 1]); C # needs sage.libs.singular Projective Conic Curve over Finite Field of size 3 defined by a^2 + b^2 + c^2 - """ return self.coordinate_ring().gens() def has_rational_point(self, point=False, algorithm='default', read_cache=True): r""" - Return True if and only if the conic ``self`` + Return ``True`` if and only if the conic ``self`` has a point over its base field `B`. - If ``point`` is True, then returns a second output, which is + If ``point`` is ``True``, then returns a second output, which is a rational point if one exists. Points are cached whenever they are found. Cached information - is used if and only if ``read_cache`` is True. + is used if and only if ``read_cache`` is ``True``. ALGORITHM: The parameter ``algorithm`` specifies the algorithm to be used: - - ``'default'`` -- If the base field is real or complex, - use an elementary native Sage implementation. + - ``'default'`` -- if the base field is real or complex, + use an elementary native Sage implementation - ``'magma'`` (requires Magma to be installed) -- delegates the task to the Magma computer algebra - system. + system EXAMPLES:: @@ -567,10 +566,10 @@ def has_rational_point(self, point=False, def has_singular_point(self, point=False): r""" - Return True if and only if the conic ``self`` has a rational + Return ``True`` if and only if the conic ``self`` has a rational singular point. - If ``point`` is True, then also return a rational singular + If ``point`` is ``True``, then also return a rational singular point (or ``None`` if no such point exists). EXAMPLES: @@ -668,7 +667,7 @@ def hom(self, x, Y=None): To: Projective Conic Curve over Rational Field defined by 4*x^2 + y^2 - z^2 Defn: Defined on coordinates by sending (x : y : z) to (1/2*z : y : x) - :class:`ValueError` is raised if the wrong codomain ``Y`` is specified: + :exc:`ValueError` is raised if the wrong codomain ``Y`` is specified: :: @@ -712,7 +711,6 @@ def hom(self, x, Y=None): Polynomial Ring in t over Rational Field defined by 1/(t^2)*x^2 + t*y^2 - 2/(t^2)*x*z + (t + 1)/(t^2)*z^2 Defn: Defined on coordinates by sending (x : y : z) to (t*x + z : y : z) - """ if isinstance(x, Matrix): from .constructor import Conic @@ -731,7 +729,7 @@ def hom(self, x, Y=None): def is_diagonal(self): r""" - Return True if and only if the conic has the form + Return ``True`` if and only if the conic has the form `a x^2 + b y^2 + c z^2`. EXAMPLES: @@ -750,7 +748,7 @@ def is_diagonal(self): def is_smooth(self): r""" - Return True if and only if ``self`` is smooth. + Return ``True`` if and only if ``self`` is smooth. EXAMPLES: @@ -917,7 +915,7 @@ def parametrization(self, point=None, morphism=True): sage: i[0](p) / i[1](p) x/y - A :class:`ValueError` is raised if ``self`` has no rational point :: + A :exc:`ValueError` is raised if ``self`` has no rational point :: sage: # needs sage.libs.pari sage: C = Conic(x^2 + y^2 + 7*z^2) @@ -927,7 +925,7 @@ def parametrization(self, point=None, morphism=True): ValueError: Conic Projective Conic Curve over Rational Field defined by x^2 + y^2 + 7*z^2 has no rational points over Rational Field! - A :class:`ValueError` is raised if ``self`` is not smooth :: + A :exc:`ValueError` is raised if ``self`` is not smooth :: sage: # needs sage.libs.pari sage: C = Conic(x^2 + y^2) @@ -972,7 +970,7 @@ def parametrization(self, point=None, morphism=True): def point(self, v, check=True): r""" - Constructs a point on ``self`` corresponding to the input ``v``. + Construct a point on ``self`` corresponding to the input ``v``. If ``check`` is True, then checks if ``v`` defines a valid point on ``self``. @@ -1031,7 +1029,6 @@ def random_rational_point(self, *args1, **args2): ... ValueError: Conic Projective Conic Curve over Rational Field defined by x^2 + y^2 + z^2 has no rational points over Rational Field! - """ if not self.is_smooth(): raise NotImplementedError("Sorry, random points not implemented " @@ -1049,7 +1046,7 @@ def rational_point(self, algorithm='default', read_cache=True): r""" Return a point on ``self`` defined over the base field. - This raises a :class:`ValueError` if no rational point exists. + This raises a :exc:`ValueError` if no rational point exists. See ``self.has_rational_point`` for the algorithm used and for the use of the parameters ``algorithm`` and ``read_cache``. @@ -1201,7 +1198,7 @@ def singular_point(self): sage: Conic(GF(2), [1,1,1,1,1,1]).singular_point() (1 : 1 : 1) - :class:`ValueError` is raised if the conic has no rational + :exc:`ValueError` is raised if the conic has no rational singular point :: @@ -1294,6 +1291,5 @@ def variable_names(self): sage: C. = Conic(QQ, [1, 1, 1]); C # needs sage.libs.singular Projective Conic Curve over Rational Field defined by p^2 + q^2 + r^2 - """ return self.defining_polynomial().parent().variable_names() diff --git a/src/sage/schemes/plane_conics/con_finite_field.py b/src/sage/schemes/plane_conics/con_finite_field.py old mode 100644 new mode 100755 index 296cd056d87..3562b2e2765 --- a/src/sage/schemes/plane_conics/con_finite_field.py +++ b/src/sage/schemes/plane_conics/con_finite_field.py @@ -60,7 +60,7 @@ def __init__(self, A, f): def count_points(self, n): r""" - If the base field `B` of `self` is finite of order `q`, + If the base field `B` of ``self`` is finite of order `q`, then returns the number of points over `\GF{q}, ..., \GF{q^n}`. EXAMPLES:: @@ -78,7 +78,7 @@ def count_points(self, n): def has_rational_point(self, point=False, read_cache=True, algorithm='default'): r""" - Always returns ``True`` because self has a point defined over + Always returns ``True`` because ``self`` has a point defined over its finite base field `B`. If ``point`` is True, then returns a second output `S`, which is a diff --git a/src/sage/schemes/plane_conics/con_number_field.py b/src/sage/schemes/plane_conics/con_number_field.py old mode 100644 new mode 100755 index 393b77bc1ff..e09a1f60262 --- a/src/sage/schemes/plane_conics/con_number_field.py +++ b/src/sage/schemes/plane_conics/con_number_field.py @@ -72,40 +72,39 @@ def has_rational_point(self, point=False, obstruction=False, then the output is a boolean ``out`` saying whether ``self`` has a rational point. - If ``point`` or ``obstruction`` is True, then the output is + If ``point`` or ``obstruction`` is ``True``, then the output is a pair ``(out, S)``, where ``out`` is as above and: - - if ``point`` is True and ``self`` has a rational point, + - if ``point`` is ``True`` and ``self`` has a rational point, then ``S`` is a rational point, - - if ``obstruction`` is True, ``self`` has no rational point, + - if ``obstruction`` is ``True``, ``self`` has no rational point, then ``S`` is a prime or infinite place of `B` such that no rational point exists over the completion at ``S``. Points and obstructions are cached whenever they are found. Cached information is used for the output if available, but only - if ``read_cache`` is True. + if ``read_cache`` is ``True``. ALGORITHM: The parameter ``algorithm`` specifies the algorithm to be used: - - ``'rnfisnorm'`` -- Use PARI's ``rnfisnorm`` + - ``'rnfisnorm'`` -- use PARI's ``rnfisnorm`` (cannot be combined with ``obstruction = True``) - - ``'local'`` -- Check if a local solution exists for all primes - and infinite places of `B` and apply the Hasse principle. - (Cannot be combined with ``point = True``.) + - ``'local'`` -- check if a local solution exists for all primes + and infinite places of `B` and apply the Hasse principle + (cannot be combined with ``point = True``) - - ``'default'`` -- Use algorithm ``'rnfisnorm'`` first. + - ``'default'`` -- use algorithm ``'rnfisnorm'`` first. Then, if no point exists and obstructions are requested, use algorithm ``'local'`` to find an obstruction. - ``'magma'`` (requires Magma to be installed) -- delegates the task to the Magma computer algebra - system. - + system EXAMPLES: @@ -123,9 +122,9 @@ def has_rational_point(self, point=False, obstruction=False, sage: C = Conic(K, [1, 3, -5]) sage: C.has_rational_point(point=True, obstruction=True) (False, Fractional ideal (-i - 2)) - sage: C.has_rational_point(algorithm="rnfisnorm") + sage: C.has_rational_point(algorithm='rnfisnorm') False - sage: C.has_rational_point(algorithm="rnfisnorm", obstruction=True, + sage: C.has_rational_point(algorithm='rnfisnorm', obstruction=True, ....: read_cache=False) Traceback (most recent call last): ... @@ -223,7 +222,7 @@ def has_rational_point(self, point=False, obstruction=False, return False, self._local_obstruction else: return False - # `_(in)finite_obstructions` is `None` if the cache is empty, + # `_(in)finite_obstructions` is ``None`` if the cache is empty, # so we explicitly check against a list: if (not point) and self._finite_obstructions == [] and \ self._infinite_obstructions == []: @@ -391,7 +390,7 @@ def local_obstructions(self, finite=True, infinite=True, read_cache=True): If the base field is `\QQ`, then the infinite place is denoted `-1`. - The parameters ``finite`` and ``infinite`` (both True by default) are + The parameters ``finite`` and ``infinite`` (both ``True`` by default) are used to specify whether to look at finite and/or infinite places. Note that ``finite = True`` involves factorization of the determinant of ``self``, hence may be slow. diff --git a/src/sage/schemes/plane_conics/con_rational_field.py b/src/sage/schemes/plane_conics/con_rational_field.py old mode 100644 new mode 100755 index f357a71edb6..329193bb5b5 --- a/src/sage/schemes/plane_conics/con_rational_field.py +++ b/src/sage/schemes/plane_conics/con_rational_field.py @@ -96,16 +96,16 @@ def has_rational_point(self, point=False, obstruction=False, The parameter ``algorithm`` specifies the algorithm to be used: - - ``'qfsolve'`` -- Use PARI/GP function :pari:`qfsolve` + - ``'qfsolve'`` -- use PARI/GP function :pari:`qfsolve` - - ``'rnfisnorm'`` -- Use PARI's function :pari:`rnfisnorm` + - ``'rnfisnorm'`` -- use PARI's function :pari:`rnfisnorm` (cannot be combined with ``obstruction = True``) - - ``'local'`` -- Check if a local solution exists for all primes + - ``'local'`` -- check if a local solution exists for all primes and infinite places of `\QQ` and apply the Hasse principle (cannot be combined with ``point = True``) - - ``'default'`` -- Use ``'qfsolve'`` + - ``'default'`` -- use ``'qfsolve'`` - ``'magma'`` (requires Magma to be installed) -- delegates the task to the Magma computer algebra system. @@ -357,7 +357,7 @@ def parametrization(self, point=None, morphism=True): sage: i[0](p) / i[1](p) x/y - A :class:`ValueError` is raised if ``self`` has no rational point :: + A :exc:`ValueError` is raised if ``self`` has no rational point :: sage: # needs sage.libs.pari sage: C = Conic(x^2 + 2*y^2 + z^2) @@ -367,7 +367,7 @@ def parametrization(self, point=None, morphism=True): ValueError: Conic Projective Conic Curve over Rational Field defined by x^2 + 2*y^2 + z^2 has no rational points over Rational Field! - A :class:`ValueError` is raised if ``self`` is not smooth :: + A :exc:`ValueError` is raised if ``self`` is not smooth :: sage: # needs sage.libs.pari sage: C = Conic(x^2 + y^2) diff --git a/src/sage/schemes/plane_conics/con_rational_function_field.py b/src/sage/schemes/plane_conics/con_rational_function_field.py old mode 100644 new mode 100755 index bc842415d8e..6ac78706107 --- a/src/sage/schemes/plane_conics/con_rational_function_field.py +++ b/src/sage/schemes/plane_conics/con_rational_function_field.py @@ -88,7 +88,7 @@ def __init__(self, A, f): def has_rational_point(self, point=False, algorithm='default', read_cache=True): r""" - Returns True if and only if the conic ``self`` + Return ``True`` if and only if the conic ``self`` has a point over its base field `F(t)`, which is a field of rational functions. @@ -226,7 +226,6 @@ def has_rational_point(self, point=False, algorithm='default', ....: 5*t^2 + 5, 4*t + 3, 4*t^2 + t + 5]) sage: C.has_rational_point() True - """ from .constructor import Conic @@ -338,14 +337,14 @@ def _reduce_conic(self): `K=F(t)` and coefficients `a,b,c` such that `a,b,c \in F[t]`, `\gcd(a,b)=\gcd(b,c)=\gcd(c,a)=1` and `abc` is square-free. - Assumes `self` is in diagonal form. + Assumes ``self`` is in diagonal form. OUTPUT: A tuple (coefficients, multipliers), the coefficients of the conic in reduced form and multipliers `\lambda, \mu, \nu \in F(t)^*` such that `(x,y,z) \in F(t)` is a solution of the reduced conic if and only - if `(\lambda x, \mu y, \nu z)` is a solution of `self`. + if `(\lambda x, \mu y, \nu z)` is a solution of ``self``. ALGORITHM: @@ -429,14 +428,14 @@ def find_point(self, supports, roots, case, solution=0): INPUT: - - ``self`` -- conic in reduced form. + - ``self`` -- conic in reduced form - ``supports`` -- 3-tuple where ``supports[i]`` is a list of all monic - irreducible `p \in F[t]` that divide the `i`'th of the 3 coefficients. + irreducible `p \in F[t]` that divide the `i`-th of the 3 coefficients - ``roots`` -- 3-tuple containing lists of roots of all elements of - ``supports[i]``, in the same order. - - ``case`` -- 1 or 0, as in [HC2006]_. + ``supports[i]``, in the same order + - ``case`` -- 1 or 0, as in [HC2006]_ - ``solution`` -- (default: 0) a solution of (5) in [HC2006]_, if - case = 0, 0 otherwise. + ``case`` = 0, 0 otherwise OUTPUT: diff --git a/src/sage/schemes/plane_conics/constructor.py b/src/sage/schemes/plane_conics/constructor.py old mode 100644 new mode 100755 index 308b56f6db0..38652c9c555 --- a/src/sage/schemes/plane_conics/constructor.py +++ b/src/sage/schemes/plane_conics/constructor.py @@ -32,8 +32,8 @@ from sage.rings.number_field.number_field_base import NumberField from sage.rings.polynomial.multi_polynomial import MPolynomial -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.schemes.affine.affine_point import SchemeMorphism_point_affine from sage.schemes.projective.projective_point import SchemeMorphism_point_projective_field @@ -59,9 +59,9 @@ def Conic(base_field, F=None, names=None, unique=True): INPUT: - - ``base_field`` -- The base field of the conic. + - ``base_field`` -- the base field of the conic - - ``names`` -- a list, tuple, or comma separated string + - ``names`` -- list, tuple, or comma separated string of three variable names specifying the names of the coordinate functions of the ambient space `\Bold{P}^3`. If not specified or read @@ -89,13 +89,11 @@ def Conic(base_field, F=None, names=None, unique=True): If ``F`` is a list of 5 points in the plane, then the output is a conic through those points. - - ``unique`` -- Used only if ``F`` is a list of points in the plane. - If the conic through the points is not unique, then - raise :class:`ValueError` if and only if ``unique`` is ``True`` + - ``unique`` -- used only if ``F`` is a list of points in the plane; + if the conic through the points is not unique, then + raise :exc:`ValueError` if and only if ``unique`` is ``True`` - OUTPUT: - - A plane projective conic curve defined by ``F`` over a field. + OUTPUT: a plane projective conic curve defined by ``F`` over a field EXAMPLES: @@ -242,7 +240,7 @@ def Conic(base_field, F=None, names=None, unique=True): return ProjectiveConic_rational_field(P2, F) if isinstance(base_field, NumberField): return ProjectiveConic_number_field(P2, F) - if isinstance(base_field, FractionField_generic) and (is_PolynomialRing(base_field.ring()) or is_MPolynomialRing(base_field.ring())): + if isinstance(base_field, FractionField_generic) and (isinstance(base_field.ring(), PolynomialRing_general) or isinstance(base_field.ring(), MPolynomialRing_base)): return ProjectiveConic_rational_function_field(P2, F) return ProjectiveConic_field(P2, F) diff --git a/src/sage/schemes/plane_quartics/quartic_constructor.py b/src/sage/schemes/plane_quartics/quartic_constructor.py old mode 100644 new mode 100755 index df2fdfa60bb..c1dd1a3d0b0 --- a/src/sage/schemes/plane_quartics/quartic_constructor.py +++ b/src/sage/schemes/plane_quartics/quartic_constructor.py @@ -21,7 +21,7 @@ def QuarticCurve(F, PP=None, check=False): - ``F`` -- a polynomial in three variables, homogeneous of degree 4 - - ``PP`` -- a projective plane (default: None) + - ``PP`` -- a projective plane (default: ``None``) - ``check`` -- whether to check for smoothness or not (default: ``False``) @@ -48,7 +48,6 @@ def QuarticCurve(F, PP=None, check=False): Traceback (most recent call last): ... ValueError: Argument F (=x^4 + y^4) must be a polynomial in 3 variables - """ if not isinstance(F, MPolynomial): raise ValueError(f"Argument F (={F}) must be a multivariate polynomial") diff --git a/src/sage/schemes/plane_quartics/quartic_generic.py b/src/sage/schemes/plane_quartics/quartic_generic.py old mode 100644 new mode 100755 index 324ec2f9b13..514637e1d96 --- a/src/sage/schemes/plane_quartics/quartic_generic.py +++ b/src/sage/schemes/plane_quartics/quartic_generic.py @@ -35,7 +35,6 @@ def is_QuarticCurve(C): DeprecationWarning: The function is_QuarticCurve is deprecated; use 'isinstance(..., QuarticCurve_generic)' instead. See https://github.com/sagemath/sage/issues/38022 for details. True - """ from sage.misc.superseded import deprecation deprecation(38022, "The function is_QuarticCurve is deprecated; use 'isinstance(..., QuarticCurve_generic)' instead.") diff --git a/src/sage/schemes/product_projective/homset.py b/src/sage/schemes/product_projective/homset.py old mode 100644 new mode 100755 index ef135a2cd6b..d10d2cc0ccb --- a/src/sage/schemes/product_projective/homset.py +++ b/src/sage/schemes/product_projective/homset.py @@ -47,11 +47,9 @@ def _element_constructor_(self, v, **kwds): INPUT: - - ``v`` -- anything that determines a scheme morphism in the Hom-set. + - ``v`` -- anything that determines a scheme morphism in the Hom-set - OUTPUT: - - The scheme morphism determined by ``v``. + OUTPUT: the scheme morphism determined by ``v`` EXAMPLES:: @@ -91,14 +89,17 @@ def points(self, **kwds): - ``bound`` -- a real number - - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm algorithm 4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm 4 - - ``precision`` -- the precision to use for computing the elements of bounded height of number fields. + - ``precision`` -- the precision to use for computing the elements of + bounded height of number fields - - ``algorithm`` -- either ``'sieve'`` or ``'enumerate'`` algorithms can be used over `\QQ`. If - not specified, ``'enumerate'`` is used only for small height bounds. + - ``algorithm`` -- either ``'sieve'`` or ``'enumerate'`` algorithms can + be used over `\QQ`. If not specified, ``'enumerate'`` is used only + for small height bounds - OUTPUT: A list of rational points of the projective scheme. + OUTPUT: list of rational points of the projective scheme EXAMPLES:: diff --git a/src/sage/schemes/product_projective/morphism.py b/src/sage/schemes/product_projective/morphism.py old mode 100644 new mode 100755 index 7fc09c0860d..e2ebb4e1834 --- a/src/sage/schemes/product_projective/morphism.py +++ b/src/sage/schemes/product_projective/morphism.py @@ -52,12 +52,12 @@ def __init__(self, parent, polys, check=True): INPUT: - - ``parent`` -- Hom-set. + - ``parent`` -- Hom-set - - ``polys`` -- anything that defines a point in the class. + - ``polys`` -- anything that defines a point in the class - - ``check`` -- Boolean. Whether or not to perform input checks. - (Default: ``True``) + - ``check`` -- boolean; whether or not to perform input checks + (default: ``True``) EXAMPLES:: @@ -131,7 +131,7 @@ def __getitem__(self, i): INPUT: - - ``i`` -- integer. + - ``i`` -- integer OUTPUT: @@ -151,7 +151,7 @@ def _repr_defn(self): r""" Return a string representation of this morphism. - OUTPUT: String. + OUTPUT: string EXAMPLES:: @@ -174,12 +174,12 @@ def __call__(self, P, check=True): INPUT: - - ``P`` -- a point in the domain. + - ``P`` -- a point in the domain - - ``check`` -- Boolean; whether or not to perform the input checks - on the image point (Default: ``True``). + - ``check`` -- boolean (default: ``True``); whether or not to perform + the input checks on the image point - OUTPUT: The image point in the codomain. + OUTPUT: the image point in the codomain EXAMPLES:: @@ -239,16 +239,16 @@ def __call__(self, P, check=True): def __eq__(self, right): """ - Tests the equality of two product projective morphisms. + Test the equality of two product projective morphisms. INPUT: - - ``right`` -- a map on product of projective space. + - ``right`` -- a map on product of projective space OUTPUT: - - Boolean -- True if ``self`` and ``right`` define the same product projective - map. False otherwise. + boolean; ``True`` if ``self`` and ``right`` define the same product + projective map. ``False`` otherwise. EXAMPLES:: @@ -304,16 +304,16 @@ def __eq__(self, right): def __ne__(self, right): """ - Tests the inequality of two prduct projective morphisms. + Test the inequality of two prduct projective morphisms. INPUT: - - ``right`` -- a map on product of projective space. + - ``right`` -- a map on product of projective space OUTPUT: - - Boolean -- True if ``self`` and ``right`` define different product - projective maps. False otherwise. + boolean; ``True`` if ``self`` and ``right`` define different product + projective maps. ``False`` otherwise. EXAMPLES:: @@ -356,7 +356,7 @@ def is_morphism(self): the domain of this map generated by the corresponding coordinates of the map. This map is a morphism if and only if each of these subschemes has no points. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -406,9 +406,7 @@ def as_dynamical_system(self): """ Return this endomorphism as a :class:`~sage.dynamics.arithmetic_dynamics.product_projective_ds.DynamicalSystem_product_projective`. - OUTPUT: - - - :class:`~sage.dynamics.arithmetic_dynamics.product_projective_ds.DynamicalSystem_product_projective` + OUTPUT: :class:`~sage.dynamics.arithmetic_dynamics.product_projective_ds.DynamicalSystem_product_projective` EXAMPLES:: @@ -431,11 +429,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default RealField precision). - - OUTPUT: + default RealField precision) - - a real number. + OUTPUT: a real number .. TODO:: @@ -482,12 +478,12 @@ def local_height(self, v, prec=None): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: diff --git a/src/sage/schemes/product_projective/point.py b/src/sage/schemes/product_projective/point.py old mode 100644 new mode 100755 index 5e1167b7b58..7cbe0065de5 --- a/src/sage/schemes/product_projective/point.py +++ b/src/sage/schemes/product_projective/point.py @@ -52,12 +52,12 @@ def __init__(self, parent, polys, check=True): INPUT: - - ``parent`` -- Hom-set. + - ``parent`` -- Hom-set - - ``polys`` -- anything that defines a point in the class. + - ``polys`` -- anything that defines a point in the class - - ``check`` -- Boolean. Whether or not to perform input checks. - (Default: ``True``) + - ``check`` -- boolean (default: ``True``); whether or not to perform + input checks EXAMPLES:: @@ -110,11 +110,9 @@ def __getitem__(self, i): INPUT: - - ``i`` -- integer. + - ``i`` -- integer - OUTPUT: - - The projective space point that is the ``i``-th coordinate. + OUTPUT: the projective space point that is the ``i``-th coordinate EXAMPLES:: @@ -133,7 +131,7 @@ def _repr_(self): r""" Return a string representation of this point. - OUTPUT: String. + OUTPUT: string EXAMPLES:: @@ -153,9 +151,7 @@ def _richcmp_(self, right, op): - ``other`` -- another point - OUTPUT: - - boolean + OUTPUT: boolean EXAMPLES:: @@ -207,9 +203,7 @@ def __copy__(self): r""" Return a copy of this point. - OUTPUT: - - - a point in the same space as third point. + OUTPUT: a point in the same space as third point EXAMPLES:: @@ -228,7 +222,7 @@ def __iter__(self): r""" Iterate over the coordinates of the point. - OUTPUT: An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -262,7 +256,7 @@ def __hash__(self): """ Compute the hash value of this point. - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: @@ -304,7 +298,7 @@ def normalize_coordinates(self): r""" Remove common factors (componentwise) from the coordinates of this point (including `-1`). - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -319,18 +313,16 @@ def normalize_coordinates(self): def dehomogenize(self, L): r""" - Dehomogenize `k^{th}` point at `L[k]^{th}` coordinate. + Dehomogenize `k`-th point at `L[k]`-th coordinate. This function computes the appropriate affine patch using ``L`` and then returns the dehomogenized point on of this affine space. INPUT: - - ``L`` -- a list of non-negative integers - - OUTPUT: + - ``L`` -- list of nonnegative integers - - :class:`SchemeMorphism_point_affine`. + OUTPUT: :class:`SchemeMorphism_point_affine` EXAMPLES:: @@ -368,7 +360,7 @@ def scale_by(self, t): r""" Scale the coordinates of the point by ``t``, done componentwise. - A :class:`TypeError` occurs if the point is not in the base ring + A :exc:`TypeError` occurs if the point is not in the base ring of the codomain after scaling. INPUT: @@ -399,15 +391,15 @@ def change_ring(self, R, **kwds): INPUT: - - ``R`` -- ring. + - ``R`` -- ring kwds: - - ``check`` -- Boolean. + - ``check`` -- boolean - - ``embedding`` -- field embedding from the base ring of this point to ``R``. + - ``embedding`` -- field embedding from the base ring of this point to ``R`` - OUTPUT: :class:`ProductProjectiveSpaces_point`. + OUTPUT: :class:`ProductProjectiveSpaces_point` EXAMPLES:: @@ -432,9 +424,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -484,12 +476,12 @@ def local_height(self, v, prec=None): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: A real number. + OUTPUT: a real number EXAMPLES:: @@ -524,9 +516,9 @@ def intersection_multiplicity(self, X): INPUT: - - ``X`` -- a subscheme in the same ambient space as the codomain of this point. + - ``X`` -- a subscheme in the same ambient space as the codomain of this point - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -549,7 +541,7 @@ def multiplicity(self): This uses the subscheme implementation of multiplicity. This point must be a point on a subscheme of a product of projective spaces. - OUTPUT: an integer. + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/schemes/product_projective/rational_point.py b/src/sage/schemes/product_projective/rational_point.py old mode 100644 new mode 100755 index 190ed0e36a9..97909025d19 --- a/src/sage/schemes/product_projective/rational_point.py +++ b/src/sage/schemes/product_projective/rational_point.py @@ -78,12 +78,12 @@ def enum_product_projective_rational_field(X, B): - ``X`` -- a scheme or set of abstract rational points of a scheme - - ``B`` -- a positive integer bound + - ``B`` -- positive integer bound OUTPUT: - - a list containing the product projective points of ``X`` of height up - to ``B``, sorted. + A list containing the product projective points of ``X`` of height up + to ``B``, sorted. EXAMPLES:: @@ -191,20 +191,20 @@ def enum_product_projective_number_field(X, **kwds): This is an implementation of the revised algorithm (Algorithm 4) in [DK2013]_. Algorithm 5 is used for imaginary quadratic fields. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- a real number - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm-4 - - ``precision`` -- the precision to use for computing the elements of bounded height of number fields. + - ``precision`` -- the precision to use for computing the elements of + bounded height of number fields OUTPUT: - - a list containing the product projective points of ``X`` of - absolute height up to ``B``, sorted. + A list containing the product projective points of ``X`` of + absolute height up to ``B``, sorted. EXAMPLES:: @@ -253,13 +253,13 @@ def enum_product_projective_finite_field(X): INPUT: - - ``X`` -- a scheme defined over a finite field or a set of abstract - rational points of such a scheme. + - ``X`` -- a scheme defined over a finite field or a set of abstract + rational points of such a scheme OUTPUT: - - a list containing the projective points of ``X`` over the finite field, - sorted. + A list containing the projective points of ``X`` over the finite field, + sorted. EXAMPLES:: @@ -306,7 +306,7 @@ def enum_product_projective_finite_field(X): def sieve(X, bound): r""" - Returns the list of all rational points on scheme + Return the list of all rational points on scheme ``X`` of height up to ``bound``. ALGORITHM: @@ -326,12 +326,12 @@ def sieve(X, bound): - ``X`` -- a scheme with ambient space defined over a product of projective spaces - - ``bound`` -- a positive integer bound + - ``bound`` -- positive integer bound OUTPUT: - - a list containing the rational points of ``X`` of height - up to ``bound``, sorted + A list containing the rational points of ``X`` of height + up to ``bound``, sorted EXAMPLES:: @@ -368,7 +368,7 @@ def sieve(X, bound): def sufficient_primes(x): r""" - Returns a list of primes whose product is > `x` + Return a list of primes whose product is > `x`. """ small_primes = [2,3] prod_primes = 6 diff --git a/src/sage/schemes/product_projective/space.py b/src/sage/schemes/product_projective/space.py old mode 100644 new mode 100755 index 56df71b3896..b0b672755da --- a/src/sage/schemes/product_projective/space.py +++ b/src/sage/schemes/product_projective/space.py @@ -63,12 +63,12 @@ def is_ProductProjectiveSpaces(x): r""" - Return True if ``x`` is a product of projective spaces. + Return ``True`` if ``x`` is a product of projective spaces. This is an ambient space defined by `\mathbb{P}^n_R \times \cdots \times \mathbb{P}^m_R`, where `R` is a ring and `n,\ldots, m\geq 0` are integers. - OUTPUT: Boolean. + OUTPUT: boolean EXAMPLES:: @@ -95,11 +95,11 @@ def ProductProjectiveSpaces(n, R=None, names='x'): INPUT: - - ``n`` -- a list of integers or a list of projective spaces + - ``n`` -- list of integers or a list of projective spaces - ``R`` -- a ring - - ``names`` -- a string or list of strings + - ``names`` -- string or list of strings EXAMPLES:: @@ -205,11 +205,11 @@ def __init__(self, N, R=QQ, names=None): INPUT: - - ``N`` -- a list or tuple of positive integers + - ``N`` -- list or tuple of positive integers - ``R`` -- a ring - - ``names`` -- a tuple or list of strings; this must either be a single + - ``names`` -- tuple or list of strings; this must either be a single variable name or the complete list of variables EXAMPLES:: @@ -322,7 +322,7 @@ def __getitem__(self, i): INPUT: - - ``i`` -- a positive integer + - ``i`` -- positive integer OUTPUT: a projective space @@ -342,7 +342,7 @@ def __eq__(self, right): - ``right`` -- a product of projective spaces - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -364,7 +364,7 @@ def __ne__(self, other): - ``other`` -- a product of projective spaces - OUTPUT: Boolean + OUTPUT: boolean EXAMPLES:: @@ -395,9 +395,11 @@ def __pow__(self, m): """ Return the Cartesian power of this space. - INPUT: ``m`` -- integer. + INPUT: + + - ``m`` -- integer - OUTPUT: product of projective spaces. + OUTPUT: product of projective spaces EXAMPLES:: @@ -480,7 +482,7 @@ def components(self): r""" Return the components of this product of projective spaces. - OUTPUT: a list of projective spaces + OUTPUT: list of projective spaces EXAMPLES:: @@ -530,7 +532,7 @@ def dimension_relative_components(self): r""" Return the relative dimension of the product of projective spaces. - OUTPUT: a list of positive integers + OUTPUT: list of positive integers EXAMPLES:: @@ -544,7 +546,7 @@ def dimension_absolute_components(self): r""" Return the absolute dimension of the product of projective spaces. - OUTPUT: a list of positive integers + OUTPUT: list of positive integers EXAMPLES:: @@ -563,9 +565,9 @@ def dimension_absolute_components(self): def num_components(self): r""" - Returns the number of components of this space. + Return the number of components of this space. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -582,7 +584,7 @@ def ngens(self): This is the number of variables in the coordinate ring of the projective space. - OUTPUT: an integer + OUTPUT: integer EXAMPLES:: @@ -598,9 +600,9 @@ def _factors(self, v): INPUT: - - ``v`` -- a list or tuple + - ``v`` -- list or tuple - OUTPUT: a list of lists + OUTPUT: list of lists EXAMPLES:: @@ -628,8 +630,8 @@ def _degree(self, polynomial): - ``polynomial`` -- a polynomial in the coordinate_ring - OUTPUT: A tuple of integers, one for each projective space component. A - :class:`ValueError` is raised if the polynomial is not multihomogeneous. + OUTPUT: a tuple of integers, one for each projective space component. A + :exc:`ValueError` is raised if the polynomial is not multihomogeneous. EXAMPLES:: @@ -699,17 +701,16 @@ def _point_homset(self, *args, **kwds): def _validate(self, polynomials): r""" If ``polynomials`` is a tuple of valid polynomial functions on this space, - return ``polynomials``, otherwise raise a :class:`TypeError`. + return ``polynomials``, otherwise raise a :exc:`TypeError`. Since this is a product of projective spaces, the polynomials must be multi-homogeneous. INPUT: - - ``polynomials`` -- tuple of polynomials in the coordinate ring of this projective space. - - OUTPUT: + - ``polynomials`` -- tuple of polynomials in the coordinate ring of + this projective space - - tuple of polynomials in the coordinate ring of this space. + OUTPUT: tuple of polynomials in the coordinate ring of this space EXAMPLES:: @@ -750,7 +751,7 @@ def _validate(self, polynomials): def _check_satisfies_equations(self, v): """ Return ``True`` if ``v`` defines a point on the scheme this space; - raise a :class:`TypeError` otherwise. + raise a :exc:`TypeError` otherwise. EXAMPLES:: @@ -810,13 +811,11 @@ def _check_satisfies_equations(self, v): def _an_element_(self): r""" - Returns a (preferably typical) element of this space. + Return a (preferably typical) element of this space. This is used both for illustration and testing purposes. - OUTPUT: - - A point in the this projective space. + OUTPUT: a point in the this projective space EXAMPLES:: @@ -834,11 +833,9 @@ def subscheme(self, X): INPUT: - - ``X`` -- a list or tuple of equations + - ``X`` -- list or tuple of equations - OUTPUT: - - :class:`AlgebraicScheme_subscheme_projective_cartesian_product`. + OUTPUT: :class:`AlgebraicScheme_subscheme_projective_cartesian_product` EXAMPLES:: @@ -870,15 +867,14 @@ def subscheme(self, X): def change_ring(self, R): r""" - Return a product of projective spaces over a ring ``R`` and otherwise the same as this projective space. + Return a product of projective spaces over a ring ``R`` and otherwise + the same as this projective space. INPUT: - ``R`` -- commutative ring or morphism - OUTPUT: - - - Product of projective spaces over ``R``. + OUTPUT: product of projective spaces over ``R`` .. NOTE:: @@ -897,14 +893,15 @@ def change_ring(self, R): def affine_patch(self, I, return_embedding=False): r""" - Return the `I^{th}` affine patch of this projective space product + Return the `I`-th affine patch of this projective space product where ``I`` is a multi-index. INPUT: - - ``I`` -- a list or tuple of positive integers. + - ``I`` -- list or tuple of positive integers - - ``return_embedding`` -- Boolean, if true the projective embedding is also returned. + - ``return_embedding`` -- boolean; if ``True`` the projective embedding + is also returned OUTPUT: @@ -966,14 +963,14 @@ def segre_embedding(self, PP=None, var='u'): INPUT: - - ``PP`` -- (default: ``None``) ambient image projective space; - this is constructed if it is not given. - - - ``var`` -- string, variable name of the image projective space, default `u` (optional). + - ``PP`` -- (default: ``None``) ambient image projective space; + this is constructed if it is not given - OUTPUT: + - ``var`` -- string (default: ``'u'``); variable name of the image + projective space - Hom -- from this space to the appropriate subscheme of projective space. + OUTPUT: Hom; from this space to the appropriate subscheme of projective + space .. TODO:: @@ -1117,13 +1114,13 @@ def _point_homset(self, *args, **kwds): def points_of_bounded_height(self, **kwds): r""" - Returns an iterator of the points in this product of projective spaces with the absolute heights of the - components of at most the given bound. + Return an iterator of the points in this product of projective spaces + with the absolute heights of the components of at most the given bound. - Bound check is strict for the rational field. Requires the base field of this space to be a number field. - Uses the - Doyle-Krumm algorithm 4 (algorithm 5 for imaginary quadratic) for - computing algebraic numbers up to a given height [DK2013]_. + Bound check is strict for the rational field. Requires the base field + of this space to be a number field. Uses the Doyle-Krumm algorithm 4 + (algorithm 5 for imaginary quadratic) for computing algebraic numbers + up to a given height [DK2013]_. The algorithm requires floating point arithmetic, so the user is allowed to specify the precision for such calculations. @@ -1136,9 +1133,11 @@ def points_of_bounded_height(self, **kwds): - ``bound`` -- a real number - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm-4 - - ``precision`` -- the precision to use for computing the elements of bounded height of number fields. + - ``precision`` -- the precision to use for computing the elements of + bounded height of number fields OUTPUT: an iterator of points in this space @@ -1238,7 +1237,7 @@ def _point(self, *args, **kwds): def __iter__(self): r""" - Returns iterator over the elements of this product of projective spaces. + Return an iterator over the elements of this product of projective spaces. EXAMPLES:: diff --git a/src/sage/schemes/product_projective/subscheme.py b/src/sage/schemes/product_projective/subscheme.py old mode 100644 new mode 100755 index 35433ba565b..8fe4fba1f6b --- a/src/sage/schemes/product_projective/subscheme.py +++ b/src/sage/schemes/product_projective/subscheme.py @@ -38,10 +38,10 @@ class AlgebraicScheme_subscheme_product_projective(AlgebraicScheme_subscheme_pro INPUT: - ``A`` -- ambient :class:`Product of Projective Spaces - `. + ` - ``polynomials`` -- single polynomial, ideal or iterable of - defining multi-homogeneous polynomials. + defining multi-homogeneous polynomials EXAMPLES:: @@ -70,11 +70,9 @@ def segre_embedding(self, PP=None): INPUT: - ``PP`` -- (default: ``None``) ambient image projective space; - this is constructed if it is not given. + this is constructed if it is not given - OUTPUT: - - Hom from this subscheme to the appropriate subscheme of projective space + OUTPUT: hom from this subscheme to the appropriate subscheme of projective space EXAMPLES:: @@ -186,7 +184,7 @@ def dimension(self): r""" Return the dimension of the algebraic subscheme. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -263,14 +261,15 @@ def is_smooth(self, point=None): def affine_patch(self, I, return_embedding=False): r""" - Return the `I^{th}` affine patch of this projective scheme + Return the `I`-th affine patch of this projective scheme where `I` is a multi-index. INPUT: - - ``I`` -- a list or tuple of positive integers + - ``I`` -- list or tuple of positive integers - - ``return_embedding`` -- Boolean, if true the projective embedding is also returned + - ``return_embedding`` -- boolean; if ``True`` the projective embedding + is also returned OUTPUT: @@ -336,18 +335,19 @@ def affine_patch(self, I, return_embedding=False): def intersection_multiplicity(self, X, P): r""" - Return the intersection multiplicity of this subscheme and the subscheme ``X`` at the point ``P``. + Return the intersection multiplicity of this subscheme and the + subscheme ``X`` at the point ``P``. - This uses the intersection_multiplicity function for affine subschemes on affine patches of this subscheme - and ``X`` that contain ``P``. + This uses the intersection_multiplicity function for affine subschemes + on affine patches of this subscheme and ``X`` that contain ``P``. INPUT: - - ``X`` -- subscheme in the same ambient space as this subscheme. + - ``X`` -- subscheme in the same ambient space as this subscheme - - ``P`` -- a point in the intersection of this subscheme with ``X``. + - ``P`` -- a point in the intersection of this subscheme with ``X`` - OUTPUT: An integer. + OUTPUT: integer EXAMPLES: @@ -416,9 +416,9 @@ def multiplicity(self, P): INPUT: - - ``P`` -- a point on this subscheme. + - ``P`` -- a point on this subscheme - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/schemes/projective/proj_bdd_height.py b/src/sage/schemes/projective/proj_bdd_height.py old mode 100644 new mode 100755 index f1191fe78a0..232f51188b4 --- a/src/sage/schemes/projective/proj_bdd_height.py +++ b/src/sage/schemes/projective/proj_bdd_height.py @@ -44,13 +44,11 @@ def ZZ_points_of_bounded_height(PS, dim, bound): - ``PS`` -- a projective space - - ``dim`` -- a positive integer + - ``dim`` -- positive integer - - ``bound`` -- a positive integer + - ``bound`` -- positive integer - OUTPUT: - - - an iterator of points of bounded height + OUTPUT: an iterator of points of bounded height EXAMPLES:: @@ -99,16 +97,14 @@ def QQ_points_of_bounded_height(PS, dim, bound, normalize=False): - ``PS`` -- a projective space - - ``dim`` -- a positive integer + - ``dim`` -- positive integer - ``bound`` -- a real number - ``normalize`` -- boolean (default: ``False``); whether to normalize the coordinates of returned points - OUTPUT: - - - an iterator of points of bounded height + OUTPUT: an iterator of points of bounded height EXAMPLES:: @@ -166,9 +162,7 @@ def IQ_points_of_bounded_height(PS, K, dim, bound): - ``bound`` -- a real number - OUTPUT: - - - an iterator of points of bounded height + OUTPUT: an iterator of points of bounded height EXAMPLES: @@ -242,15 +236,13 @@ def points_of_bounded_height(PS, K, dim, bound, prec=53): - ``K`` -- a number field - - ``dim`` -- a positive integer + - ``dim`` -- positive integer - ``bound`` -- a real number - ``prec`` -- (default: 53) a positive integer - OUTPUT: - - - an iterator of points of bounded height + OUTPUT: an iterator of points of bounded height EXAMPLES:: diff --git a/src/sage/schemes/projective/projective_homset.py b/src/sage/schemes/projective/projective_homset.py old mode 100644 new mode 100755 index b1dca24495f..7f86f7ea0f6 --- a/src/sage/schemes/projective/projective_homset.py +++ b/src/sage/schemes/projective/projective_homset.py @@ -10,7 +10,7 @@ the rational points are implemented by such scheme morphisms. This is done by :class:`SchemeHomset_points` and its subclasses. -.. note:: +.. NOTE:: You should not create the Hom-sets manually. Instead, use the :meth:`~sage.structure.parent.Hom` method that is inherited by all @@ -80,30 +80,26 @@ def points(self, **kwds): basis calculation. For schemes or subschemes with dimension greater than 1 points are determined through enumeration up to the specified bound. - INPUT: - - kwds: + INPUT: keyword arguments: - - ``bound`` -- real number (default: 0). The bound for the coordinates for - subschemes with dimension at least 1. + - ``bound`` -- real number (default: 0); the bound for the coordinates + for subschemes with dimension at least 1 - - ``precision`` -- integer (default: 53). The precision to use to - compute the elements of bounded height for number fields. - - - ``point_tolerance`` -- positive real number (default: `10^{-10}`). - For numerically inexact fields, two points are considered the same - if their coordinates are within tolerance. + - ``precision`` -- integer (default: 53); the precision to use to + compute the elements of bounded height for number fields - - ``zero_tolerance`` -- positive real number (default: `10^{-10}`). - For numerically inexact fields, points are on the subscheme if they - satisfy the equations to within tolerance. + - ``point_tolerance`` -- positive real number (default: `10^{-10}`); + for numerically inexact fields, two points are considered the same + if their coordinates are within tolerance - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 - for enumeration over number fields. + - ``zero_tolerance`` -- positive real number (default: `10^{-10}`); + for numerically inexact fields, points are on the subscheme if they + satisfy the equations to within tolerance - OUTPUT: + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm-4 for enumeration over number fields - - a list of rational points of a projective scheme + OUTPUT: list of rational points of a projective scheme .. WARNING:: @@ -318,7 +314,7 @@ def numerical_points(self, F=None, **kwds): For numerically inexact fields, points are on the subscheme if they satisfy the equations to within tolerance. - OUTPUT: A list of points in the ambient space. + OUTPUT: list of points in the ambient space .. WARNING:: @@ -487,8 +483,7 @@ def points(self, B=0): INPUT: - - ``B`` -- integer (default: 0). The bound for the - coordinates. + - ``B`` -- integer (default: 0); the bound for the coordinates EXAMPLES:: @@ -624,12 +619,9 @@ def _element_constructor_(self, *v, **kwds): INPUT: - - ``v`` -- anything that determines a scheme morphism in the - Hom-set. - - OUTPUT: + - ``v`` -- anything that determines a scheme morphism in the Hom-set - The scheme morphism determined by ``v``. + OUTPUT: the scheme morphism determined by ``v`` EXAMPLES:: @@ -654,9 +646,7 @@ def _repr_(self): """ Return a string representation of this homset. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -677,7 +667,7 @@ def base_extend(self, R): INPUT: - - ``R`` -- a ring. + - ``R`` -- a ring EXAMPLES:: diff --git a/src/sage/schemes/projective/projective_morphism.py b/src/sage/schemes/projective/projective_morphism.py old mode 100644 new mode 100755 index 562df768bae..20031e81a41 --- a/src/sage/schemes/projective/projective_morphism.py +++ b/src/sage/schemes/projective/projective_morphism.py @@ -292,9 +292,9 @@ def __call__(self, x, check=True): INPUT: - - ``x`` -- a point or subscheme in domain of this map. + - ``x`` -- a point or subscheme in domain of this map - - ``check`` -- Boolean; if `False` assume that ``x`` is a point. + - ``check`` -- boolean; if ``False`` assume that ``x`` is a point EXAMPLES:: @@ -508,7 +508,7 @@ def _fast_eval(self, x): def __eq__(self, right): """ - Tests the equality of two projective morphisms. + Test the equality of two projective morphisms. INPUT: @@ -559,7 +559,7 @@ def __eq__(self, right): def __ne__(self, right): """ - Tests the inequality of two projective morphisms. + Test the inequality of two projective morphisms. INPUT: @@ -597,7 +597,7 @@ def __ne__(self, right): def _matrix_times_polymap_(self, mat, h): """ - Multiplies the morphism on the left by a matrix ``mat``. + Multiply the morphism on the left by a matrix ``mat``. INPUT: @@ -642,7 +642,7 @@ def _matrix_times_polymap_(self, mat, h): def _polymap_times_matrix_(self, mat, h): """ - Multiplies the morphism on the right by a matrix ``mat``. + Multiply the morphism on the right by a matrix ``mat``. INPUT: @@ -690,9 +690,7 @@ def as_dynamical_system(self): """ Return this endomorphism as a :class:`DynamicalSystem_projective`. - OUTPUT: - - - :class:`DynamicalSystem_projective` + OUTPUT: :class:`DynamicalSystem_projective` EXAMPLES:: @@ -741,16 +739,14 @@ def scale_by(self, t): """ Scale each coordinate by a factor of ``t``. - A :class:`TypeError` occurs if the point is not in the coordinate ring + A :exc:`TypeError` occurs if the point is not in the coordinate ring of the parent after scaling. INPUT: - - ``t`` -- a ring element. - - OUTPUT: + - ``t`` -- a ring element - - None. + OUTPUT: none EXAMPLES:: @@ -814,19 +810,15 @@ def normalize_coordinates(self, **kwds): absolute value less than or equal to 1. Only supported when the base ring is a number field. - INPUT: - - kwds: + INPUT: keyword arguments: - ``ideal`` -- (optional) a prime ideal of the base ring of this - morphism. + morphism - ``valuation`` -- (optional) a valuation of the base ring of this - morphism. + morphism - OUTPUT: - - - None. + OUTPUT: none EXAMPLES:: @@ -1063,9 +1055,7 @@ def degree(self): The degree is defined as the degree of the homogeneous polynomials that are the coordinates of this map. - OUTPUT: - - - A positive integer + OUTPUT: positive integer EXAMPLES:: @@ -1114,12 +1104,10 @@ def dehomogenize(self, n): INPUT: - - ``n`` -- a tuple of nonnegative integers. If ``n`` is an integer, then the two values of - the tuple are assumed to be the same. - - OUTPUT: + - ``n`` -- tuple of nonnegative integers; if ``n`` is an integer, then + the two values of the tuple are assumed to be the same - - :class:`SchemeMorphism_polynomial_affine_space`. + OUTPUT: :class:`SchemeMorphism_polynomial_affine_space` EXAMPLES:: @@ -1256,9 +1244,7 @@ def is_morphism(self): the defining polynomials is the unit ideal (no common zeros of the defining polynomials). - OUTPUT: - - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -1317,11 +1303,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default RealField precision). - - OUTPUT: + default RealField precision) - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -1419,14 +1403,12 @@ def local_height(self, v, prec=None): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default RealField precision). - - OUTPUT: + default RealField precision) - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -1478,14 +1460,12 @@ def local_height_arch(self, i, prec=None): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: - - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -1529,7 +1509,7 @@ def wronskian_ideal(self): This is the vanishing of the maximal minors of the Jacobian matrix. Not implemented for subvarieties. - OUTPUT: an ideal in the coordinate ring of the domain of this map. + OUTPUT: an ideal in the coordinate ring of the domain of this map EXAMPLES:: @@ -1581,13 +1561,11 @@ def rational_preimages(self, Q, k=1): INPUT: - - ``Q`` -- a rational point or subscheme in the domain of this map. + - ``Q`` -- a rational point or subscheme in the domain of this map - - ``k`` -- positive integer. + - ``k`` -- positive integer - OUTPUT: - - - a list of rational points or a subscheme in the domain of this map. + OUTPUT: a list of rational points or a subscheme in the domain of this map EXAMPLES:: @@ -1944,7 +1922,6 @@ def indeterminacy_locus(self): x*z - y*z, x^2 - y^2, z^2 - """ from sage.misc.superseded import deprecation deprecation(29145, "The meaning of indeterminacy_locus() has changed. Read the docstring.") @@ -2065,7 +2042,7 @@ def reduce_base_field(self): the base ring is a number field, QQbar, a finite field, or algebraic closure of a finite field. - OUTPUT: A scheme morphism. + OUTPUT: a scheme morphism EXAMPLES:: diff --git a/src/sage/schemes/projective/projective_point.py b/src/sage/schemes/projective/projective_point.py old mode 100644 new mode 100755 index 2e9dd6fca9f..c154b8e7d49 --- a/src/sage/schemes/projective/projective_point.py +++ b/src/sage/schemes/projective/projective_point.py @@ -62,18 +62,17 @@ class SchemeMorphism_point_projective_ring(SchemeMorphism_point): INPUT: - - ``X`` -- a homset of a subscheme of an ambient projective space over a ring `K`. + - ``X`` -- a homset of a subscheme of an ambient projective space over a ring `K` - - ``v`` -- a list or tuple of coordinates in `K`. + - ``v`` -- list or tuple of coordinates in `K` - - ``check`` -- boolean (default:``True``). Whether to check the input for consistency. + - ``check`` -- boolean (default: ``True``); whether to check the input for consistency EXAMPLES:: sage: P = ProjectiveSpace(2, ZZ) sage: P(2,3,4) (2 : 3 : 4) - """ def __init__(self, X, v, check=True): @@ -186,7 +185,7 @@ def __init__(self, X, v, check=True): if R in IntegralDomains(): # Over integral domains, any tuple with at least one - # non-zero coordinate is a valid projective point. + # nonzero coordinate is a valid projective point. if not any(v): raise ValueError(f"{v} does not define a valid projective " "point since all entries are zero") @@ -211,9 +210,7 @@ def _richcmp_(self, right, op): - ``right`` -- a point on projective space - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -388,7 +385,7 @@ def __hash__(self): equal hash values. If the base ring is not an integral domain, return the hash of the parent. - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: @@ -430,7 +427,7 @@ def __hash__(self): def _matrix_times_point_(self, mat, dom): r""" - Multiplies the point by a matrix ``mat`` on the left. + Multiply the point by a matrix ``mat`` on the left. INPUT: @@ -489,14 +486,14 @@ def scale_by(self, t): """ Scale the coordinates of the point by ``t``. - A :class:`TypeError` occurs if the point is not in the + A :exc:`TypeError` occurs if the point is not in the base_ring of the codomain after scaling. INPUT: - - ``t`` -- a ring element. + - ``t`` -- a ring element - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -541,7 +538,7 @@ def normalize_coordinates(self): .. WARNING:: The gcd will depend on the base ring. - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -635,11 +632,9 @@ def dehomogenize(self,n): INPUT: - - ``n`` -- non-negative integer. + - ``n`` -- nonnegative integer - OUTPUT: - - - :class:`SchemeMorphism_point_affine`. + OUTPUT: :class:`SchemeMorphism_point_affine` EXAMPLES:: @@ -692,11 +687,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default RealField precision). - - OUTPUT: + default RealField precision) - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -778,18 +771,16 @@ def global_height(self, prec=None): def local_height(self, v, prec=None): r""" - Returns the maximum of the local height of the coordinates of this point. + Return the maximum of the local height of the coordinates of this point. INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default RealField precision). - - OUTPUT: + default RealField precision) - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -812,18 +803,16 @@ def local_height(self, v, prec=None): def local_height_arch(self, i, prec=None): r""" - Returns the maximum of the local heights at the ``i``-th infinite place of this point. + Return the maximum of the local heights at the ``i``-th infinite place of this point. INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default RealField precision). + default RealField precision) - OUTPUT: - - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -850,17 +839,18 @@ def local_height_arch(self, i, prec=None): def multiplier(self, f, n, check=True): r""" - Returns the multiplier of this point of period ``n`` by the function ``f``. + Return the multiplier of this point of period ``n`` by the function ``f``. ``f`` must be an endomorphism of projective space. INPUT: - - ``f`` -- a endomorphism of this point's codomain. + - ``f`` -- a endomorphism of this point's codomain - - ``n`` -- a positive integer, the period of this point. + - ``n`` -- positive integer; the period of this point - - ``check`` -- check if ``P`` is periodic of period ``n``, Default:True. + - ``check`` -- boolean (default: ``True``); check if ``P`` is periodic + of period ``n`` OUTPUT: @@ -908,18 +898,18 @@ def is_preperiodic(self, f, err=0.1, return_period=False): INPUT: - - ``f`` -- an endomorphism of this point's codomain. + - ``f`` -- an endomorphism of this point's codomain kwds: - - ``err`` -- a positive real number (default: 0.1). + - ``err`` -- a positive real number (default: 0.1) - - ``return_period`` -- boolean (default: ``False``). + - ``return_period`` -- boolean (default: ``False``) OUTPUT: - - boolean -- ``True`` if preperiodic. + - boolean; ``True`` if preperiodic. - if ``return_period`` is ``True``, then ``(0,0)`` if wandering, and ``(m,n)`` if preperiod ``m`` and period ``n``. @@ -1060,13 +1050,13 @@ class SchemeMorphism_point_projective_field(SchemeMorphism_point_projective_ring INPUT: - - ``X`` -- a homset of a subscheme of an ambient projective space - over a field `K`. + - ``X`` -- a homset of a subscheme of an ambient projective space + over a field `K` - - ``v`` -- a list or tuple of coordinates in `K`. + - ``v`` -- list or tuple of coordinates in `K` - - ``check`` -- boolean (default:``True``). Whether to - check the input for consistency. + - ``check`` -- boolean (default: ``True``); whether to + check the input for consistency EXAMPLES:: @@ -1082,7 +1072,7 @@ def __init__(self, X, v, check=True): See :class:`SchemeMorphism_point_projective_ring` for details. - This function still normalizes points so that the rightmost non-zero coordinate is 1. + This function still normalizes points so that the rightmost nonzero coordinate is 1. This is to maintain functionality with current implementations of curves in projectives space (plane, conic, elliptic, etc). The :class:`SchemeMorphism_point_projective_ring` is for general use. @@ -1179,9 +1169,9 @@ def __init__(self, X, v, check=True): def __hash__(self): """ - Computes the hash value of this point. + Compute the hash value of this point. - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: @@ -1195,9 +1185,9 @@ def __hash__(self): def normalize_coordinates(self): r""" - Normalizes the point so that the last non-zero coordinate is `1`. + Normalize the point so that the last nonzero coordinate is `1`. - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -1290,9 +1280,9 @@ def _number_field_from_algebraics(self): def clear_denominators(self): r""" - scales by the least common multiple of the denominators. + Scale by the least common multiple of the denominators. - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -1339,9 +1329,9 @@ def intersection_multiplicity(self, X): INPUT: - - ``X`` -- a subscheme in the same ambient space as that of the codomain of this point. + - ``X`` -- a subscheme in the same ambient space as that of the codomain of this point - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: @@ -1380,7 +1370,7 @@ def multiplicity(self): Uses the subscheme multiplicity implementation. This point must be a point on a projective subscheme. - OUTPUT: an integer. + OUTPUT: integer EXAMPLES:: @@ -1431,9 +1421,9 @@ class SchemeMorphism_point_projective_finite_field(SchemeMorphism_point_projecti def __hash__(self): r""" - Returns the integer hash of this point. + Return the integer hash of this point. - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: diff --git a/src/sage/schemes/projective/projective_rational_point.py b/src/sage/schemes/projective/projective_rational_point.py old mode 100644 new mode 100755 index 4e68426fb1f..82653894cca --- a/src/sage/schemes/projective/projective_rational_point.py +++ b/src/sage/schemes/projective/projective_rational_point.py @@ -80,14 +80,14 @@ def enum_projective_rational_field(X, B): INPUT: - - ``X`` -- a scheme or set of abstract rational points of a scheme. + - ``X`` -- a scheme or set of abstract rational points of a scheme - - ``B`` -- a positive integer bound. + - ``B`` -- a positive integer bound OUTPUT: - - a list containing the projective points of ``X`` of height up to ``B``, - sorted. + A list containing the projective points of ``X`` of height up to ``B``, + sorted. EXAMPLES:: @@ -171,20 +171,18 @@ def enum_projective_number_field(X, **kwds): This is an implementation of the revised algorithm (Algorithm 4) in [DK2013]_. Algorithm 5 is used for imaginary quadratic fields. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- a real number - - ``tolerance`` -- a rational number in (0,1] used in doyle-krumm algorithm-4 + - ``tolerance`` -- a rational number in (0,1] used in Doyle-Krumm + algorithm-4 - - ``precision`` -- the precision to use for computing the elements of bounded height of number fields. - - OUTPUT: + - ``precision`` -- the precision to use for computing the elements of + bounded height of number fields - - a list containing the projective points of ``X`` of absolute height up to ``B``, - sorted. + OUTPUT: a sorted list containing the projective points of ``X`` of absolute + height up to ``B`` EXAMPLES:: @@ -238,13 +236,13 @@ def enum_projective_finite_field(X): INPUT: - - ``X`` -- a scheme defined over a finite field or a set of abstract - rational points of such a scheme. + - ``X`` -- a scheme defined over a finite field or a set of abstract + rational points of such a scheme OUTPUT: - - a list containing the projective points of ``X`` over the finite field, - sorted. + A list containing the projective points of ``X`` over the finite field, + sorted. EXAMPLES:: @@ -314,7 +312,7 @@ def enum_projective_finite_field(X): def sieve(X, bound): r""" - Returns the list of all projective, rational points on scheme ``X`` of + Return the list of all projective, rational points on scheme ``X`` of height up to ``bound``. Height of a projective point `X = (x_1, x_2,\dots, x_n)` is given by @@ -337,12 +335,12 @@ def sieve(X, bound): - ``X`` -- a scheme with ambient space defined over projective space - - ``bound`` -- a positive integer bound + - ``bound`` -- positive integer bound OUTPUT: - - a list containing the projective rational points of ``X`` of height - up to ``bound``, sorted + A list containing the projective rational points of ``X`` of height + up to ``bound``, sorted EXAMPLES:: @@ -402,7 +400,7 @@ def sieve(X, bound): def sufficient_primes(x): r""" - Returns a list of primes whose product is > `x` + Return a list of primes whose product is > `x`. """ small_primes = [2,3] prod_primes = 6 diff --git a/src/sage/schemes/projective/projective_space.py b/src/sage/schemes/projective/projective_space.py old mode 100644 new mode 100755 index b91b5ac1080..9f010391eec --- a/src/sage/schemes/projective/projective_space.py +++ b/src/sage/schemes/projective/projective_space.py @@ -99,8 +99,8 @@ from sage.rings.fraction_field import FractionField from sage.rings.integer import Integer from sage.rings.integer_ring import ZZ -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.rings.rational_field import QQ, RationalField from sage.schemes.generic.ambient_space import AmbientSpace @@ -136,7 +136,7 @@ def is_ProjectiveSpace(x): r""" - Return True if ``x`` is a projective space. + Return ``True`` if ``x`` is a projective space. In other words, if ``x`` is an ambient space `\mathbb{P}^n_R`, where `R` is a ring and `n\geq 0` is an integer. @@ -248,7 +248,7 @@ def ProjectiveSpace(n, R=None, names=None): sage: P.gens() == R.gens() True """ - if (is_MPolynomialRing(n) or is_PolynomialRing(n)) and R is None: + if (isinstance(n, MPolynomialRing_base) or isinstance(n, PolynomialRing_general)) and R is None: if names is not None: # Check for the case that the user provided a variable name # That does not match what we wanted to use from R @@ -370,7 +370,7 @@ def ngens(self): def _check_satisfies_equations(self, v): """ Return ``True`` if ``v`` defines a point on the scheme; raise a - :class:`TypeError` otherwise. + :exc:`TypeError` otherwise. EXAMPLES:: @@ -451,19 +451,17 @@ def coordinate_ring(self): def _validate(self, polynomials): """ - If ``polynomials`` is a tuple of valid polynomial functions on self, - return ``polynomials``, otherwise raise TypeError. + If ``polynomials`` is a tuple of valid polynomial functions on + ``self``, return ``polynomials``, otherwise raise :exc:`TypeError`. Since this is a projective space, polynomials must be homogeneous. INPUT: - ``polynomials`` -- tuple of polynomials in the coordinate ring of - this space. + this space - OUTPUT: - - - tuple of polynomials in the coordinate ring of this space. + OUTPUT: tuple of polynomials in the coordinate ring of this space EXAMPLES:: @@ -498,9 +496,11 @@ def __pow__(self, m): """ Return the Cartesian power of this space. - INPUT: ``m`` -- integer. + INPUT: + + - ``m`` -- integer - OUTPUT: product of projective spaces. + OUTPUT: product of projective spaces EXAMPLES:: @@ -524,9 +524,9 @@ def __mul__(self, right): INPUT: - - ``right`` -- a projective space, product of projective spaces, or subscheme. + - ``right`` -- a projective space, product of projective spaces, or subscheme - OUTPUT: a product of projective spaces or subscheme. + OUTPUT: a product of projective spaces or subscheme EXAMPLES:: @@ -607,12 +607,12 @@ def _linear_system_as_kernel(self, d, pt, m): INPUT: - - ``d`` -- a nonnegative integer. + - ``d`` -- nonnegative integer - - ``pt`` -- a point of ``self`` (possibly represented by a list with at \ - least one component equal to 1). + - ``pt`` -- a point of ``self`` (possibly represented by a list with at + least one component equal to 1) - - ``m`` -- a nonnegative integer. + - ``m`` -- nonnegative integer OUTPUT: @@ -686,7 +686,6 @@ def _linear_system_as_kernel(self, d, pt, m): Use this method as starting point to implement a class LinearSystem for linear systems of hypersurfaces. - """ if not isinstance(d, (int, Integer)): raise TypeError('the argument d=%s must be an integer' % d) @@ -785,7 +784,7 @@ def point(self, v, check=True): - ``check`` -- boolean (default: ``True``); whether to check the defining data for consistency - OUTPUT: A point of this projective space. + OUTPUT: a point of this projective space EXAMPLES:: @@ -901,11 +900,9 @@ def change_ring(self, R): INPUT: - - ``R`` -- commutative ring or morphism. + - ``R`` -- commutative ring or morphism - OUTPUT: - - - projective space over ``R``. + OUTPUT: projective space over ``R`` .. NOTE:: @@ -952,7 +949,7 @@ def subscheme(self, X): INPUT: - - ``X`` -- a list or tuple of equations. + - ``X`` -- list or tuple of equations EXAMPLES:: @@ -1004,17 +1001,13 @@ def points_of_bounded_height(self, **kwds): This is an implementation of Algorithm 6 in [Krumm2016]_. - INPUT: - - kwds: + INPUT: keyword arguments: - ``bound`` -- a real number - ``precision`` -- (default: 53) a positive integer - OUTPUT: - - - an iterator of points of bounded height + OUTPUT: an iterator of points of bounded height EXAMPLES:: @@ -1227,22 +1220,20 @@ def points_of_bounded_height(self, **kwds): def affine_patch(self, i, AA=None): r""" - Return the `i^{th}` affine patch of this projective space. + Return the `i`-th affine patch of this projective space. This is an ambient affine space `\mathbb{A}^n_R,` where `R` is the base ring of ``self``, whose "projective embedding" - map is `1` in the `i^{th}` factor. + map is `1` in the `i`-th factor. INPUT: - - ``i`` -- integer between 0 and dimension of ``self``, inclusive. + - ``i`` -- integer between 0 and dimension of ``self``, inclusive - - ``AA`` -- (default: None) ambient affine space, this is constructed - if it is not given. + - ``AA`` -- (default: ``None``) ambient affine space, this is constructed + if it is not given - OUTPUT: - - - An ambient affine space with fixed projective_embedding map. + OUTPUT: an ambient affine space with fixed projective_embedding map EXAMPLES:: @@ -1298,11 +1289,11 @@ def affine_patch(self, i, AA=None): def _an_element_(self): r""" - Returns a (preferably typical) element of this space. + Return a (preferably typical) element of this space. This is used both for illustration and testing purposes. - OUTPUT: a point in this projective space. + OUTPUT: a point in this projective space EXAMPLES:: @@ -1326,11 +1317,11 @@ def Lattes_map(self, E, m): INPUT: - - ``E`` -- an elliptic curve. + - ``E`` -- an elliptic curve - - ``m`` -- an integer. + - ``m`` -- integer - OUTPUT: a dynamical system on this projective space. + OUTPUT: a dynamical system on this projective space EXAMPLES:: @@ -1370,11 +1361,9 @@ def cartesian_product(self, other): INPUT: - - ``other`` -- A projective space with the same base ring as this space. - - OUTPUT: + - ``other`` -- a projective space with the same base ring as this space - - A Cartesian product of projective spaces. + OUTPUT: a Cartesian product of projective spaces EXAMPLES:: @@ -1399,13 +1388,13 @@ def chebyshev_polynomial(self, n, kind='first', monic=False): INPUT: - - ``n`` -- a non-negative integer. + - ``n`` -- nonnegative integer - - ``kind`` -- ``first`` or ``second`` specifying which kind of chebyshev the user would like - to generate. Defaults to ``first``. + - ``kind`` -- ``'first'`` (default) or ``'second'`` specifying which + kind of Chebyshev the user would like to generate - - ``monic`` -- ``True`` or ``False`` specifying if the polynomial defining the system - should be monic or not. Defaults to ``False``. + - ``monic`` -- boolean (default: ``False``) specifying if the + polynomial defining the system should be monic or not OUTPUT: :class:`DynamicalSystem_projective` @@ -1439,7 +1428,7 @@ def chebyshev_polynomial(self, n, kind='first', monic=False): sage: P.chebyshev_polynomial(-4, 'second') Traceback (most recent call last): ... - ValueError: first parameter 'n' must be a non-negative integer + ValueError: first parameter 'n' must be a nonnegative integer :: @@ -1471,7 +1460,7 @@ def chebyshev_polynomial(self, n, kind='first', monic=False): raise TypeError("projective space must be of dimension 1") n = ZZ(n) if (n < 0): - raise ValueError("first parameter 'n' must be a non-negative integer") + raise ValueError("first parameter 'n' must be a nonnegative integer") # use the affine version and then homogenize. A = self.affine_patch(1) f = A.chebyshev_polynomial(n, kind) @@ -1486,18 +1475,18 @@ def veronese_embedding(self, d, CS=None, order='lex'): INPUT: - - ``d`` -- a positive integer. - - - ``CS`` -- a projective ambient space to embed into. If this projective space has dimension `N`, the - dimension of ``CS`` must be `\binom{N + d}{d} - 1`. This is constructed if not specified. Default: - ``None``. + - ``d`` -- positive integer - - ``order`` -- a monomial order to use to arrange the monomials defining the embedding. The monomials - will be arranged from greatest to least with respect to this order. Default: ``'lex'``. + - ``CS`` -- (default: ``None``) a projective ambient space to embed + into. If this projective space has dimension `N`, the dimension of + ``CS`` must be `\binom{N + d}{d} - 1`. This is constructed if not + specified. - OUTPUT: + - ``order`` -- string (default: ``'lex'``); a monomial order to use to + arrange the monomials defining the embedding. The monomials will be + arranged from greatest to least with respect to this order. - - a scheme morphism from this projective space to ``CS``. + OUTPUT: a scheme morphism from this projective space to ``CS`` EXAMPLES:: @@ -1563,16 +1552,17 @@ def point_transformation_matrix(self, points_source, points_target, normalize=Tr INPUT: - - ``points_source`` -- points in source projective space. + - ``points_source`` -- points in source projective space - - ``points_target`` -- points in target projective space. + - ``points_target`` -- points in target projective space - - ``normalize`` -- (default: ``True``) If the returned matrix should be normalized. - Only works over exact rings. If the base ring is a field, the matrix is normalized so - that the last nonzero entry in the last row is 1. If the base ring is a ring, then - the matrix is normalized so that the entries are elements of the base ring. + - ``normalize`` -- boolean (default: ``True``); if the returned matrix + should be normalized. Only works over exact rings. If the base ring + is a field, the matrix is normalized so that the last nonzero entry + in the last row is 1. If the base ring is a ring, then the matrix is + normalized so that the entries are elements of the base ring. - OUTPUT: Transformation matrix - element of PGL. + OUTPUT: transformation matrix - element of PGL ALGORITHM: @@ -1788,7 +1778,7 @@ def hyperplane_transformation_matrix(self, plane_1, plane_2): - ``plane_1``, ``plane_2`` -- hyperplanes of this projective space - OUTPUT: An element of PGL + OUTPUT: an element of PGL EXAMPLES:: @@ -1928,7 +1918,7 @@ def hyperplane_transformation_matrix(self, plane_1, plane_2): source_points.append(self(L)) else: nonzero_places.append(i) - # next we add a point for each variable with non-zero coefficient, except the last + # next we add a point for each variable with nonzero coefficient, except the last # giving us a total of (N+1) - J - 1 = N - J points added in this loop # resulting in exactly J + (N-J) = N points on the plane for i in range(len(nonzero_places)-1): @@ -1967,15 +1957,13 @@ def is_linearly_independent(self, points, n=None): INPUT: - - ``points`` -- a list of points in this projective space. + - ``points`` -- list of points in this projective space - - ``n`` -- (Optional) A positive integer less than or equal to the length + - ``n`` -- (optional) positive integer less than or equal to the length of ``points``. Specifies the size of the subsets to check for linear independence. - OUTPUT: - - - ``True`` if ``points`` is linearly independent, ``False`` otherwise. + OUTPUT: ``True`` if ``points`` is linearly independent, ``False`` otherwise EXAMPLES:: @@ -2029,7 +2017,7 @@ def is_linearly_independent(self, points, n=None): sage: P.is_linearly_independent(points, 5) Traceback (most recent call last): ... - ValueError: n must be a non negative integer not greater than the length of points + ValueError: n must be a nonnegative integer not greater than the length of points """ if not isinstance(points, list): raise TypeError("points must be a list") @@ -2042,7 +2030,7 @@ def is_linearly_independent(self, points, n=None): return M.rank() == len(points) n = Integer(n) if n < 1 or n > len(points): - raise ValueError('n must be a non negative integer not greater than the length of points') + raise ValueError('n must be a nonnegative integer not greater than the length of points') all_subsets = Subsets(range(len(points)), n) linearly_independent = True for subset in all_subsets: @@ -2104,7 +2092,7 @@ def _morphism(self, *args, **kwds): def subscheme_from_Chow_form(self, Ch, dim): r""" - Returns the subscheme defined by the Chow equations associated to the Chow form ``Ch``. + Return the subscheme defined by the Chow equations associated to the Chow form ``Ch``. These equations define the subscheme set-theoretically, but only for smooth subschemes and hypersurfaces do they define the subscheme as a scheme. @@ -2119,11 +2107,11 @@ def subscheme_from_Chow_form(self, Ch, dim): INPUT: - - ``Ch`` -- a homogeneous polynomial. + - ``Ch`` -- a homogeneous polynomial - - ``dim`` -- the dimension of the associated scheme. + - ``dim`` -- the dimension of the associated scheme - OUTPUT: a projective subscheme. + OUTPUT: a projective subscheme EXAMPLES:: @@ -2254,7 +2242,6 @@ def line_through(self, p, q): Traceback (most recent call last): ... ValueError: not distinct points - """ if p == q: raise ValueError("not distinct points") @@ -2378,9 +2365,7 @@ def rational_points_dictionary(self): r""" Return dictionary of points. - OUTPUT: - - - dictionary + OUTPUT: dictionary EXAMPLES:: @@ -2428,7 +2413,7 @@ def rational_points_dictionary(self): class ProjectiveSpace_rational_field(ProjectiveSpace_field): def rational_points(self, bound=0): r""" - Returns the projective points `(x_0:\cdots:x_n)` over + Return the projective points `(x_0:\cdots:x_n)` over `\QQ` with `|x_i| \leq` bound. ALGORITHM: @@ -2444,7 +2429,7 @@ def rational_points(self, bound=0): INPUT: - - ``bound`` -- integer. + - ``bound`` -- integer EXAMPLES:: diff --git a/src/sage/schemes/projective/projective_subscheme.py b/src/sage/schemes/projective/projective_subscheme.py old mode 100644 new mode 100755 index eff64907afc..a0c571de25b --- a/src/sage/schemes/projective/projective_subscheme.py +++ b/src/sage/schemes/projective/projective_subscheme.py @@ -51,10 +51,10 @@ class AlgebraicScheme_subscheme_projective(AlgebraicScheme_subscheme): INPUT: - ``A`` -- ambient :class:`projective space - `. + ` - ``polynomials`` -- single polynomial, ideal or iterable of - defining homogeneous polynomials. + defining homogeneous polynomials EXAMPLES:: @@ -81,7 +81,7 @@ def point(self, v, check=True): - ``check`` -- boolean (default: ``True``); whether to check the defining data for consistency - OUTPUT: A point of the subscheme. + OUTPUT: a point of the subscheme EXAMPLES:: @@ -135,9 +135,7 @@ def _morphism(self, *args, **kwds): - same as for :class:`~sage.schemes.projective.projective_morphism.SchemeMorphism_polynomial_projective_space`. - OUTPUT: - - - :class:`~sage.schemes.projective.projective_morphism.SchemeMorphism_polynomial_projective_space`. + OUTPUT: :class:`~sage.schemes.projective.projective_morphism.SchemeMorphism_polynomial_projective_space` TESTS:: @@ -161,9 +159,7 @@ def dimension(self): """ Return the dimension of the projective algebraic subscheme. - OUTPUT: - - Integer. + OUTPUT: integer EXAMPLES:: @@ -201,17 +197,17 @@ def dimension(self): def affine_patch(self, i, AA=None): r""" - Return the `i^{th}` affine patch of this projective scheme. + Return the `i`-th affine patch of this projective scheme. - This is the intersection with this `i^{th}` affine patch of + This is the intersection with this `i`-th affine patch of its ambient space. INPUT: - - ``i`` -- integer between 0 and dimension of ``self``, inclusive. + - ``i`` -- integer between 0 and dimension of ``self``, inclusive - ``AA`` -- (default: ``None``) ambient affine space, this - is constructed if it is not given. + is constructed if it is not given OUTPUT: @@ -293,11 +289,9 @@ def _best_affine_patch(self, point): INPUT: - - ``point`` -- a point of the algebraic subscheme. + - ``point`` -- a point of the algebraic subscheme - OUTPUT: - - Integer. The index of the patch. See :meth:`affine_patch`. + OUTPUT: integer. The index of the patch. See :meth:`affine_patch` EXAMPLES:: @@ -337,7 +331,7 @@ def neighborhood(self, point): INPUT: - - ``point`` -- a point of the projective subscheme. + - ``point`` -- a point of the projective subscheme OUTPUT: @@ -400,12 +394,12 @@ def is_smooth(self, point=None) -> bool: INPUT: - - ``point`` -- A point or ``None`` (default). The point to - test smoothness at. + - ``point`` -- a point or ``None`` (default); the point to + test smoothness at OUTPUT: - Boolean. If no point was specified, returns whether the + boolean; if no point was specified, returns whether the algebraic subscheme is smooth everywhere. Otherwise, smoothness at the specified point is tested. @@ -461,11 +455,9 @@ def orbit(self, f, N) -> list: - ``f`` -- a :class:`DynamicalSystem_projective` with ``self`` in ``f.domain()`` - - ``N`` -- a non-negative integer or list or tuple of two non-negative integers + - ``N`` -- nonnegative integer or list or tuple of two nonnegative integers - OUTPUT: - - - a list of projective subschemes + OUTPUT: list of projective subschemes EXAMPLES:: @@ -507,7 +499,7 @@ def orbit(self, f, N) -> list: sage: X.orbit(f, [-1,2]) # needs sage.schemes Traceback (most recent call last): ... - TypeError: orbit bounds must be non-negative + TypeError: orbit bounds must be nonnegative """ if not isinstance(f, DynamicalSystem): raise TypeError("map must be a dynamical system for iteration") @@ -516,7 +508,7 @@ def orbit(self, f, N) -> list: N[0] = ZZ(N[0]) N[1] = ZZ(N[1]) if N[0] < 0 or N[1] < 0: - raise TypeError("orbit bounds must be non-negative") + raise TypeError("orbit bounds must be nonnegative") if N[0] > N[1]: return [] @@ -532,13 +524,13 @@ def orbit(self, f, N) -> list: def nth_iterate(self, f, n): r""" - The nth forward image of this scheme by the map ``f``. + The `n`-th forward image of this scheme by the map ``f``. INPUT: - ``f`` -- a :class:`DynamicalSystem_projective` with ``self`` in ``f.domain()`` - - ``n`` -- a positive integer. + - ``n`` -- positive integer OUTPUT: @@ -606,11 +598,9 @@ def _forward_image(self, f, check=True): - ``f`` -- a map whose domain contains ``self`` - - ``check`` -- Boolean, if `False` no input checking is done - - OUTPUT: + - ``check`` -- boolean, if ``False`` no input checking is done - - a subscheme in the codomain of ``f``. + OUTPUT: a subscheme in the codomain of ``f`` EXAMPLES:: @@ -793,13 +783,11 @@ def preimage(self, f, k=1, check=True): - ``f`` -- a map whose codomain contains this scheme - - ``k`` -- a positive integer + - ``k`` -- positive integer - - ``check`` -- Boolean, if ``False`` no input checking is done + - ``check`` -- boolean; if ``False`` no input checking is done - OUTPUT: - - a subscheme in the domain of ``f`` + OUTPUT: a subscheme in the domain of ``f`` EXAMPLES:: @@ -907,13 +895,11 @@ def dual(self): INPUT: - - ``X`` -- A subscheme of projective space. At present, ``X`` is + - ``X`` -- a subscheme of projective space. At present, ``X`` is required to be an irreducible and reduced hypersurface defined over `\QQ` or a finite field. - OUTPUT: - - - The dual of ``X`` as a subscheme of the dual projective space. + OUTPUT: the dual of ``X`` as a subscheme of the dual projective space EXAMPLES: @@ -1023,7 +1009,7 @@ def degree(self): If `P(t) = a_{m}t^m + \ldots + a_{0}` is the Hilbert polynomial of this subscheme, then the degree is `a_{m} m!`. - OUTPUT: Integer. + OUTPUT: integer EXAMPLES:: @@ -1055,11 +1041,11 @@ def intersection_multiplicity(self, X, P): INPUT: - - ``X`` -- subscheme in the same ambient space as this subscheme. + - ``X`` -- subscheme in the same ambient space as this subscheme - - ``P`` -- a point in the intersection of this subscheme with ``X``. + - ``P`` -- a point in the intersection of this subscheme with ``X`` - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -1125,11 +1111,9 @@ def multiplicity(self, P): INPUT: - - ``P`` -- a point on this subscheme. - - OUTPUT: + - ``P`` -- a point on this subscheme - An integer. + OUTPUT: integer EXAMPLES:: @@ -1185,18 +1169,19 @@ def veronese_embedding(self, d, CS=None, order='lex'): INPUT: - - ``d`` -- a positive integer. + - ``d`` -- positive integer - - ``CS`` -- a projective ambient space to embed into. If the projective ambient space of this subscheme - is of dimension `N`, the dimension of ``CS`` must be `\binom{N + d}{d} - 1`. This is constructed if - not specified. Default: ``None``. + - ``CS`` -- (default: ``None``) a projective ambient space to embed + into. If the projective ambient space of this subscheme is of + dimension `N`, the dimension of ``CS`` must be + `\binom{N + d}{d} - 1`. This is constructed if not specified. - - ``order`` -- a monomial order to use to arrange the monomials defining the embedding. The monomials - will be arranged from greatest to least with respect to this order. Default: ``'lex'``. + - ``order`` -- string (default: ``'lex'``); a monomial order to use to + arrange the monomials defining the embedding. The monomials will be + arranged from greatest to least with respect to this order. - OUTPUT: - - - a scheme morphism from this subscheme to its image by the degree ``d`` Veronese embedding. + OUTPUT: a scheme morphism from this subscheme to its image by the + degree ``d`` Veronese embedding EXAMPLES:: @@ -1257,9 +1242,7 @@ def _morphism(self, *args, **kwds): - same as for :class:`~sage.schemes.projective.projective_morphism.SchemeMorphism_polynomial_projective_space`. - OUTPUT: - - - :class:`~sage.schemes.projective.projective_morphism.SchemeMorphism_polynomial_projective_space`. + OUTPUT: :class:`~sage.schemes.projective.projective_morphism.SchemeMorphism_polynomial_projective_space` TESTS:: @@ -1302,7 +1285,7 @@ def Chow_form(self): writing `R` as a polynomial in Plucker coordinates (i.e. bracket polynomials). [DS1994]_. - OUTPUT: a homogeneous polynomial. + OUTPUT: a homogeneous polynomial EXAMPLES:: @@ -1422,11 +1405,9 @@ def global_height(self, prec=None): INPUT: - ``prec`` -- desired floating point precision (default: - default ``RealField`` precision). + default ``RealField`` precision) - OUTPUT: - - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -1453,14 +1434,12 @@ def local_height(self, v, prec=None): INPUT: - - ``v`` -- a prime or prime ideal of the base ring. + - ``v`` -- a prime or prime ideal of the base ring - ``prec`` -- desired floating point precision (default: - default ``RealField`` precision). - - OUTPUT: + default ``RealField`` precision) - - a real number. + OUTPUT: a real number EXAMPLES:: @@ -1488,14 +1467,12 @@ def local_height_arch(self, i, prec=None): INPUT: - - ``i`` -- an integer. + - ``i`` -- integer - ``prec`` -- desired floating point precision (default: - default ``RealField`` precision). - - OUTPUT: + default ``RealField`` precision) - - a real number. + OUTPUT: a real number EXAMPLES:: diff --git a/src/sage/schemes/riemann_surfaces/riemann_surface.py b/src/sage/schemes/riemann_surfaces/riemann_surface.py old mode 100644 new mode 100755 index 28d761803b7..0c3e2724229 --- a/src/sage/schemes/riemann_surfaces/riemann_surface.py +++ b/src/sage/schemes/riemann_surfaces/riemann_surface.py @@ -156,7 +156,7 @@ def voronoi_ghost(cpoints, n=6, CC=CDF): INPUT: - - ``cpoints`` -- a list of complex numbers + - ``cpoints`` -- list of complex numbers OUTPUT: @@ -200,14 +200,12 @@ def bisect(L, t): INPUT: - - ``L`` -- A list of tuples such that the first term of each tuple is a real - number between 0 and 1. These real numbers must be increasing. + - ``L`` -- list of tuples such that the first term of each tuple is a real + number between 0 and 1. These real numbers must be increasing - - ``t`` -- A real number between `t_0` and `t_n`. + - ``t`` -- real number between `t_0` and `t_n` - OUTPUT: - - An integer i, giving the position in L where t would be in + OUTPUT: integer i, giving the position in L where t would be in EXAMPLES: @@ -252,11 +250,11 @@ def bisect(L, t): def numerical_inverse(C): """ - Compute numerical inverse of a matrix via LU decomposition + Compute numerical inverse of a matrix via LU decomposition. INPUT: - - ``C`` -- A real or complex invertible square matrix + - ``C`` -- a real or complex invertible square matrix EXAMPLES:: @@ -304,7 +302,7 @@ class ConvergenceError(ValueError): def differential_basis_baker(f): r""" - Compute a differential basis for a curve that is nonsingular outside (1:0:0),(0:1:0),(0:0:1) + Compute a differential basis for a curve that is nonsingular outside (1:0:0),(0:1:0),(0:0:1). Baker's theorem tells us that if a curve has its singularities at the coordinate vertices and meets some further easily tested genericity criteria, @@ -321,7 +319,7 @@ def differential_basis_baker(f): INPUT: - - `f` -- a bivariate polynomial + - ``f`` -- a bivariate polynomial EXAMPLES:: @@ -343,7 +341,6 @@ def differential_basis_baker(f): sage: f = y^12 - x*(x - 1)^7 sage: differential_basis_baker(f) is None True - """ k = f.base_ring() R = PolynomialRing(k, 3, "x,y,z") @@ -423,9 +420,7 @@ def reparameterize_differential_minpoly(minpoly, z0): - ``z0`` -- complex number or infinity; the point about which to reparameterize - OUTPUT: - - A polynomial in two variables giving the reparameterize minimal polynomial. + OUTPUT: a polynomial in two variables giving the reparameterize minimal polynomial EXAMPLES: @@ -494,11 +489,11 @@ class RiemannSurface: - ``prec`` -- the desired precision of computations on the surface in bits (default: 53) - - ``certification`` -- a boolean (default: ``True``) value indicating + - ``certification`` -- boolean (default: ``True``); value indicating whether homotopy continuation is certified or not. Uncertified homotopy continuation can be faster. - - ``differentials`` -- (default: ``None``). If specified, provides a list + - ``differentials`` -- (default: ``None``) if specified, provides a list of polynomials `h` such that `h/(df/dw) dz` is a regular differential on the Riemann surface. This is taken as a basis of the regular differentials, so the genus is assumed to be equal @@ -775,7 +770,7 @@ def w_values(self, z0): INPUT: - - ``z0`` -- (complex) a point in the complex z-plane. + - ``z0`` -- complex number; a point in the complex z-plane OUTPUT: @@ -863,9 +858,7 @@ def downstairs_graph(self): The result of this routine can be useful to interpret the labelling of the vertices. See also :meth:`upstairs_graph`. - OUTPUT: - - The Voronoi decomposition as a graph, with appropriate planar embedding. + OUTPUT: the Voronoi decomposition as a graph, with appropriate planar embedding EXAMPLES:: @@ -925,17 +918,15 @@ def _compute_delta(self, z1, epsilon, wvalues=None): INPUT: - - ``z1`` -- a complex number in the z-plane + - ``z1`` -- complex number in the z-plane - - ``epsilon`` -- a real number, which is the minimum distance between + - ``epsilon`` -- real number which is the minimum distance between the w-values above ``z1`` - - ``wvalues`` -- a list (default: ``None``). If specified, saves - recomputation. + - ``wvalues`` -- list (default: ``None``); if specified, saves + recomputation - OUTPUT: - - A real number, which is a step size for moving along a path. + OUTPUT: a real number, which is a step size for moving along a path EXAMPLES: @@ -1018,7 +1009,7 @@ def homotopy_continuation(self, edge): INPUT: - - ``edge`` -- a tuple ``(z_start, z_end)`` indicating the straight line + - ``edge`` -- tuple ``(z_start, z_end)`` indicating the straight line over which to perform the homotopy continutation OUTPUT: @@ -1101,10 +1092,10 @@ def _determine_new_w(self, z0, oldw, epsilon): INPUT: - - ``z0`` -- a complex number + - ``z0`` -- complex number - - ``oldw`` -- a list of w-values which are presumed to be guesses of - the w-values above ``z0``. + - ``oldw`` -- list of w-values which are presumed to be guesses of + the w-values above ``z0`` - ``epsilon`` -- the minimum distance between the points of ``oldw`` divided by 3 @@ -1203,12 +1194,12 @@ def _newton_iteration(self, z0, oldw, epsilon): INPUT: - - ``z0`` -- a complex number. + - ``z0`` -- complex number - ``oldw`` -- a w-value which is presumed to be a guess of one of - the w-values above ``z0``. + the w-values above ``z0`` - - ``epsilon`` -- the minimum distance between the w-values divided by 3. + - ``epsilon`` -- the minimum distance between the w-values divided by 3 OUTPUT: @@ -1683,7 +1674,7 @@ def direction(center, neighbour): # Range over the size of the Gram matrix. for j in range(cn): # Forms the acycles and bcycles. If the entry in the - # transformation matrix is non-zero, it adds the coefficient at + # transformation matrix is nonzero, it adds the coefficient at # that entry, and the corresponding cycle. (also, forms it # into a loop) if P[i][j] != 0: @@ -1792,18 +1783,16 @@ def simple_vector_line_integral(self, upstairs_edge, differentials): INPUT: - - ``upstairs_edge`` -- tuple. Either a pair of integer tuples + - ``upstairs_edge`` -- tuple; either a pair of integer tuples corresponding to an edge of the upstairs graph, or a tuple ``((z_start, sb), (z_end, ))`` as in the input of - ``make_zw_interpolator``. + ``make_zw_interpolator`` - - ``differentials`` -- a list of polynomials; a polynomial `g` + - ``differentials`` -- list of polynomials; a polynomial `g` represents the differential `g(z,w)/(df/dw) dz` where `f(z,w)=0` is - the equation defining the Riemann surface. - - OUTPUT: + the equation defining the Riemann surface - A complex number, the value of the line integral. + OUTPUT: a complex number, the value of the line integral EXAMPLES:: @@ -1855,7 +1844,7 @@ def cohomology_basis(self, option=1): INPUT: - - ``option`` -- Presently, this routine uses Singular's ``adjointIdeal`` + - ``option`` -- presently, this routine uses Singular's ``adjointIdeal`` and passes the ``option`` parameter on. Legal values are 1, 2, 3 ,4, where 1 is the default. See the Singular documentation for the meaning. The backend for this function may change, and support for @@ -1885,7 +1874,7 @@ def cohomology_basis(self, option=1): base = self.f.base_ring() # It's important we use a degree ordering; see below. R = self._R - k = PolynomialRing(base, names="Z,W,U", order="degrevlex") + k = PolynomialRing(base, names='Z,W,U', order='degrevlex') dehom = k.Hom(R)([R.gen(0), R.gen(1), R.one()]) fnew = self.f(k.gen(0) / k.gen(2), k.gen(1) / k.gen(2)).numerator() @@ -1942,19 +1931,19 @@ def _bounding_data(self, differentials, exact=False): notation ``RBzg = PolynomialRing(self._R, ['z','g'])`` and ``CCzg = PolynomialRing(self._CC, ['z','g'])``, we have that: - - ``Rzg`` is either ``RBzg`` or ``CCzg`` depending on the value of - ``exact``, - - ``g`` is the full rational function in ``self._R.fraction_field()`` - giving the differential, - - ``dgdz`` is the derivative of ``g`` with respect to ``self._R.gen(0)``, - written in terms of ``self._R.gen(0)`` and ``g``, hence laying in - ``RBzg``, - - ``F`` is the minimal polynomial of ``g`` over ``self._R.gen(0)``, - laying in the polynomial ring ``Rzg``, - - ``a0_info`` is a tuple ``(lc, roots)`` where ``lc`` and ``roots`` are - the leading coefficient and roots of the polynomial in ``CCzg.gen(0)`` - that is the coefficient of the term of ``F`` of highest degree in - ``CCzg.gen(1)``. + - ``Rzg`` is either ``RBzg`` or ``CCzg`` depending on the value of + ``exact``, + - ``g`` is the full rational function in ``self._R.fraction_field()`` + giving the differential, + - ``dgdz`` is the derivative of ``g`` with respect to ``self._R.gen(0)``, + written in terms of ``self._R.gen(0)`` and ``g``, hence laying in + ``RBzg``, + - ``F`` is the minimal polynomial of ``g`` over ``self._R.gen(0)``, + laying in the polynomial ring ``Rzg``, + - ``a0_info`` is a tuple ``(lc, roots)`` where ``lc`` and ``roots`` are + the leading coefficient and roots of the polynomial in ``CCzg.gen(0)`` + that is the coefficient of the term of ``F`` of highest degree in + ``CCzg.gen(1)``. EXAMPLES:: @@ -2056,22 +2045,20 @@ def rigorous_line_integral(self, upstairs_edge, differentials, bounding_data): INPUT: - - ``upstairs_edge`` -- tuple. Either a pair of integer tuples + - ``upstairs_edge`` -- tuple; either a pair of integer tuples corresponding to an edge of the upstairs graph, or a tuple ``((z_start, sb), (z_end, ))`` as in the input of - ``make_zw_interpolator``. + ``make_zw_interpolator`` - - ``differentials`` -- a list of polynomials; a polynomial `g` + - ``differentials`` -- list of polynomials; a polynomial `g` represents the differential `g(z,w)/(df/dw) dz` where `f(z,w)=0` is - the equation defining the Riemann surface. + the equation defining the Riemann surface - ``bounding_data`` -- tuple containing the data required for bounding the integrands. This should be in the form of the output from :meth:`_bounding_data`. - OUTPUT: - - A complex number, the value of the line integral. + OUTPUT: a complex number, the value of the line integral EXAMPLES:: @@ -2273,7 +2260,7 @@ def integrand(t): return output * z1_minus_z0 - def matrix_of_integral_values(self, differentials, integration_method="heuristic"): + def matrix_of_integral_values(self, differentials, integration_method='heuristic'): r""" Compute the path integrals of the given differentials along the homology basis. @@ -2285,9 +2272,9 @@ def matrix_of_integral_values(self, differentials, integration_method="heuristic INPUT: - - ``differentials`` -- a list of polynomials. + - ``differentials`` -- list of polynomials - - ``integration_method`` -- (default: ``'heuristic'``). String specifying + - ``integration_method`` -- (default: ``'heuristic'``) string specifying the integration method to use. The options are ``'heuristic'`` and ``'rigorous'``. @@ -2314,7 +2301,6 @@ def matrix_of_integral_values(self, differentials, integration_method="heuristic of the integrals along the edges are written to ``self._integral_dict``. This is as this data will be required when computing the Abel-Jacobi map, and so it is helpful to have is stored rather than recomputing. - """ cycles = self.homology_basis() @@ -2372,9 +2358,7 @@ def period_matrix(self): r""" Compute the period matrix of the surface. - OUTPUT: - - A matrix of complex values. + OUTPUT: a matrix of complex values EXAMPLES:: @@ -2399,8 +2383,8 @@ def period_matrix(self): sage: from sage.schemes.riemann_surfaces.riemann_surface import RiemannSurface sage: R. = QQ[] sage: f = y^2 - x^3 + 1 - sage: S = RiemannSurface(f, integration_method="rigorous") - sage: T = RiemannSurface(f, integration_method="heuristic") + sage: S = RiemannSurface(f, integration_method='rigorous') + sage: T = RiemannSurface(f, integration_method='heuristic') sage: RM_S = S.riemann_matrix() sage: RM_T = T.riemann_matrix() sage: (RM_S-RM_T).norm() < 1e-10 @@ -2413,9 +2397,7 @@ def riemann_matrix(self): r""" Compute the Riemann matrix. - OUTPUT: - - A matrix of complex values. + OUTPUT: a matrix of complex values EXAMPLES:: @@ -2475,7 +2457,7 @@ def path(t): T = self._L[e] P += [path(t[0]) for t in T] - return point2d(P, size=1) + point2d(self.branch_locus, color="red") + return point2d(P, size=1) + point2d(self.branch_locus, color='red') def plot_paths3d(self, thickness=0.01): r""" @@ -2525,7 +2507,7 @@ def path(t): for w in ws: P += point3d( [z.real_part(), z.imag_part(), w.imag_part()], - color="purple", + color='purple', size=20, ) return P @@ -2544,12 +2526,12 @@ def endomorphism_basis(self, b=None, r=None): INPUT: - - ``b`` -- integer (default provided). The equation coefficients are - scaled by `2^b` before rounding to integers. + - ``b`` -- integer (default provided); the equation coefficients are + scaled by `2^b` before rounding to integers - - ``r`` -- integer (default: ``b/4``). Solutions that have all + - ``r`` -- integer (default: ``b/4``); solutions that have all coefficients smaller than `2^r` in absolute value are reported as - actual solutions. + actual solutions OUTPUT: @@ -2568,7 +2550,6 @@ def endomorphism_basis(self, b=None, r=None): ] sage: sorted([b.minpoly().disc() for b in B]) [-3, 1] - """ M = self.riemann_matrix() return integer_matrix_relations(M, M, b, r) @@ -2589,12 +2570,12 @@ def homomorphism_basis(self, other, b=None, r=None): INPUT: - - ``b`` -- integer (default provided). The equation coefficients are - scaled by `2^b` before rounding to integers. + - ``b`` -- integer (default provided); the equation coefficients are + scaled by `2^b` before rounding to integers - - ``r`` -- integer (default: ``b/4``). Solutions that have all + - ``r`` -- integer (default: ``b/4``); solutions that have all coefficients smaller than `2^r` in absolute value are reported as - actual solutions. + actual solutions OUTPUT: @@ -2628,15 +2609,13 @@ def tangent_representation_numerical(self, Rs, other=None): INPUT: - - ``Rs`` -- a set of matrices on homology to be converted to their - tangent representations. + - ``Rs`` -- set of matrices on homology to be converted to their + tangent representations - - ``other`` (default: ``self``) -- the codomain, another Riemann - surface. + - ``other`` -- (default: ``self``) the codomain; another Riemann + surface - OUTPUT: - - The numerical tangent representations of the matrices in ``Rs``. + OUTPUT: the numerical tangent representations of the matrices in ``Rs`` EXAMPLES:: @@ -2680,19 +2659,17 @@ def tangent_representation_algebraic(self, Rs, other=None, epscomp=None): INPUT: - - ``Rs`` -- a set of matrices on homology to be converted to their - tangent representations. + - ``Rs`` -- set of matrices on homology to be converted to their + tangent representations - - ``other`` (default: ``self``) -- the codomain, another Riemann - surface. + - ``other`` -- (default: ``self``) the codomain; another Riemann + surface - ``epscomp`` -- real number (default: ``2^(-prec + 30)``). Used to determine whether a complex number is close enough to a root of a polynomial. - OUTPUT: - - The algebraic tangent representations of the matrices in ``Rs``. + OUTPUT: the algebraic tangent representations of the matrices in ``Rs`` EXAMPLES:: @@ -2750,11 +2727,9 @@ def rosati_involution(self, R): INPUT: - - ``R`` -- integral matrix. + - ``R`` -- integral matrix - OUTPUT: - - The result of applying the Rosati involution to ``R``. + OUTPUT: the result of applying the Rosati involution to ``R`` EXAMPLES:: @@ -2785,22 +2760,22 @@ def symplectic_isomorphisms(self, other=None, hom_basis=None, b=None, r=None): INPUT: - - ``other`` (default: ``self``) -- the codomain, another Riemann - surface. + - ``other`` -- (default: ``self``) the codomain; another Riemann + surface - - ``hom_basis`` (default: ``None``) -- a `\ZZ`-basis of the + - ``hom_basis`` -- (default: ``None``) a `\ZZ`-basis of the homomorphisms from ``self`` to ``other``, as obtained from :meth:`homomorphism_basis`. If you have already calculated this basis, it saves time to pass it via this keyword argument. Otherwise the method will calculate it. - - ``b`` -- integer (default provided): as for + - ``b`` -- integer (default provided); as for :meth:`homomorphism_basis`, and used in its invocation if - (re)calculating said basis. + (re)calculating said basis - - ``r`` -- integer (default: ``b/4``). as for + - ``r`` -- integer (default: ``b/4``); as for :meth:`homomorphism_basis`, and used in its invocation if - (re)calculating said basis. + (re)calculating said basis OUTPUT: @@ -2864,19 +2839,19 @@ def symplectic_automorphism_group(self, endo_basis=None, b=None, r=None): INPUT: - - ``endo_basis`` (default: ``None``) -- a `\ZZ`-basis of the + - ``endo_basis`` -- (default: ``None``) a `\ZZ`-basis of the endomorphisms of ``self``, as obtained from :meth:`endomorphism_basis`. If you have already calculated this basis, it saves time to pass it via this keyword argument. Otherwise the method will calculate it. - - ``b`` -- integer (default provided): as for + - ``b`` -- integer (default provided); as for :meth:`homomorphism_basis`, and used in its invocation if - (re)calculating said basis. + (re)calculating said basis - - ``r`` -- integer (default: ``b/4``). as for + - ``r`` -- integer (default: ``b/4``); as for :meth:`homomorphism_basis`, and used in its invocation if - (re)calculating said basis. + (re)calculating said basis OUTPUT: @@ -2938,17 +2913,17 @@ def _integrate_differentials_iteratively( along, where ``z_start`` may be infinite, in which case ``w_start`` must be an integer specifying the branch. - - ``cutoff_individually`` -- boolean (default: ``False``). Whether to truncate - the integrand uniformly or not. If ``None``, then no truncation is - applied. + - ``cutoff_individually`` -- boolean (default: ``False``); whether to + truncate the integrand uniformly or not. If ``None``, then no + truncation is applied - - ``raise_errors`` -- boolean (default: ``True``). By default the code uses - convergence errors to ensure any answers returned are accurate. This - can be turned off to return answers faster that are not necessarily - correct. + - ``raise_errors`` -- boolean (default: ``True``); by default the code + uses convergence errors to ensure any answers returned are accurate. + This can be turned off to return answers faster that are not + necessarily correct. - - ``prec`` -- integer (default: ``self._prec``). The precision to try - and achieve, defined as `2^{-\text{prec}+3}`. + - ``prec`` -- integer (default: ``self._prec``); the precision to try + and achieve, defined as `2^{-\text{prec}+3}` OUTPUT: @@ -3285,7 +3260,7 @@ def _aj_based(self, P): we are using the convention that the `w` value over `\infty` is given by the limit as ``z`` tends to `\infty` of ``self.w_values(z)[branch]``. - OUTPUT: A vector of length ``self.genus``. + OUTPUT: a vector of length ``self.genus`` EXAMPLES: @@ -3312,7 +3287,6 @@ def _aj_based(self, P): sage: AJx2 = [2*z for z in AJ] sage: bool(S.reduce_over_period_lattice(AJx2).norm() < 1e-10) True - """ ##### fcd = self._fastcall_cohomology_basis @@ -3511,11 +3485,11 @@ def abel_jacobi(self, divisor, verbose=False): where ``v`` is the valuation of the divisor at point ``P``, ``P`` as per the input to :meth:`_aj_based`. - - ``verbose`` -- logical (default: ``False``). Whether to report the progress + - ``verbose`` -- logical (default: ``False``); whether to report the progress of the computation, in terms of how many elements of the list ``divisor`` - have been completed. + have been completed - OUTPUT: A vector of length ``self.genus``. + OUTPUT: a vector of length ``self.genus`` EXAMPLES: @@ -3548,7 +3522,7 @@ def abel_jacobi(self, divisor, verbose=False): return ans def reduce_over_period_lattice( - self, vector, method="ip", b=None, r=None, normalised=False + self, vector, method='ip', b=None, r=None, normalised=False ): r""" Reduce a vector over the period lattice. @@ -3564,20 +3538,20 @@ def reduce_over_period_lattice( INPUT: - ``vector`` -- vector. A vector of length ``self.genus`` to reduce over - the lattice. + the lattice - - ``method`` -- string (default: ``'ip'``). String specifying the method - to use to reduce the vector. THe options are ``'ip'`` and ``'svp'``. + - ``method`` -- string (default: ``'ip'``) specifying the method + to use to reduce the vector; the options are ``'ip'`` and ``'svp'`` - - ``b`` -- integer (default provided): as for + - ``b`` -- integer (default provided); as for :meth:`homomorphism_basis`, and used in its invocation if - (re)calculating said basis. + (re)calculating said basis - - ``r`` -- integer (default: ``b/4``). as for + - ``r`` -- integer (default: ``b/4``); as for :meth:`homomorphism_basis`, and used in its invocation if - (re)calculating said basis. + (re)calculating said basis - - ``normalised`` -- logical (default: ``False``). Whether to use the + - ``normalised`` -- logical (default: ``False``); whether to use the period matrix with the differentials normalised s.t. the `A`-matrix is the identity. @@ -3607,7 +3581,7 @@ def reduce_over_period_lattice( sage: for vector in S.period_matrix().columns(): ....: n1 = S.reduce_over_period_lattice(vector).norm() - ....: n2 = S.reduce_over_period_lattice(vector, method="svp").norm() + ....: n2 = S.reduce_over_period_lattice(vector, method='svp').norm() ....: print(bool(n2<=n1)) True True @@ -3682,7 +3656,7 @@ def curve(self): For others, the curve is constructed and cached, so that an identical curve is returned upon subsequent calls. - OUTPUT: Curve from which Riemann surface is obtained. + OUTPUT: curve from which Riemann surface is obtained EXAMPLES:: @@ -3947,11 +3921,11 @@ def integer_matrix_relations(M1, M2, b=None, r=None): - ``M2`` -- square complex valued matrix of same size as ``M1`` - - ``b`` -- integer (default provided). The equation coefficients are scaled - by `2^b` before rounding to integers. + - ``b`` -- integer (default provided); the equation coefficients are scaled + by `2^b` before rounding to integers - - ``r`` -- integer (default: ``b/4``). The vectors found by LLL that satisfy - the scaled equations to within `2^r` are reported as solutions. + - ``r`` -- integer (default: ``b/4``); the vectors found by LLL that satisfy + the scaled equations to within `2^r` are reported as solutions OUTPUT: @@ -4027,7 +4001,7 @@ class RiemannSurfaceSum(RiemannSurface): INPUT: - - L -- list of RiemannSurface objects + - ``L`` -- list of RiemannSurface objects EXAMPLES:: diff --git a/src/sage/schemes/toric/chow_group.py b/src/sage/schemes/toric/chow_group.py old mode 100644 new mode 100755 index de2441eef0f..3087ed5b301 --- a/src/sage/schemes/toric/chow_group.py +++ b/src/sage/schemes/toric/chow_group.py @@ -163,12 +163,12 @@ def __init__(self, parent, v, check=True): INPUT: - - ``parent`` -- a :class:`ChowGroup_class`. + - ``parent`` -- a :class:`ChowGroup_class` - ``v`` -- a vector in the covering module, that is, with one - entry for each cone of the toric variety. + entry for each cone of the toric variety - - ``check`` -- boolean (default: ``True``). Verify that ``v`` + - ``check`` -- boolean (default: ``True``); verify that ``v`` is in the covering module. Set to ``False`` if you want to initialize from a coordinate vector. @@ -186,9 +186,7 @@ def _repr_(self) -> str: r""" Return a string representation of the Chow cycle. - OUTPUT: - - See the module-level documentation for details. + OUTPUT: see the module-level documentation for details EXAMPLES:: @@ -237,7 +235,7 @@ def degree(self) -> int: Integer. The complex dimension of the subvariety representing the Chow cycle. - This raises a :class:`ValueError` if the Chow cycle is a + This raises a :exc:`ValueError` if the Chow cycle is a sum of mixed degree cycles. EXAMPLES:: @@ -266,7 +264,7 @@ def project_to_degree(self, degree): INPUT: - - ``degree`` -- integer. The degree to project to. + - ``degree`` -- integer; the degree to project to OUTPUT: @@ -356,7 +354,7 @@ def intersection_with_divisor(self, divisor): OUTPUT: A new :class:`ChowCycle`. If the divisor is not Cartier then - this method potentially raises a :class:`ValueError`, indicating + this method potentially raises a :exc:`ValueError`, indicating that the divisor cannot be made transversal to the Chow cycle. EXAMPLES:: @@ -473,7 +471,7 @@ def cohomology_class(self): If the toric variety is not simplicial, that is, has worse than orbifold singularities, there is no way to associate a cohomology class of the correct degree. In this case, - :meth:`cohomology_class` raises a :class:`ValueError`. + :meth:`cohomology_class` raises a :exc:`ValueError`. EXAMPLES:: @@ -534,12 +532,12 @@ def create_key_and_extra_args(self, toric_variety, base_ring=ZZ, check=True): INPUT: - - ``toric_variety`` -- a toric variety. + - ``toric_variety`` -- a toric variety - - ``base_ring`` -- either `\ZZ` (default) or `\QQ`. The - coefficient ring of the Chow group. + - ``base_ring`` -- either `\ZZ` (default) or `\QQ`; the + coefficient ring of the Chow group - - ``check`` -- boolean (default: ``True``). + - ``check`` -- boolean (default: ``True``) EXAMPLES:: @@ -564,11 +562,11 @@ def create_object(self, version, key, **extra_args): INPUT: - - ``version`` -- object version. Currently not used. + - ``version`` -- object version; currently not used - - ``key`` -- a key created by :meth:`create_key_and_extra_args`. + - ``key`` -- a key created by :meth:`create_key_and_extra_args` - - ``**extra_args`` -- Currently not used. + - ``**extra_args`` -- currently not used EXAMPLES:: @@ -658,7 +656,7 @@ def scheme(self): r""" Return the underlying toric variety. - OUTPUT: A :class:`ToricVariety + OUTPUT: a :class:`ToricVariety `. EXAMPLES:: @@ -680,10 +678,10 @@ def _element_constructor_(self, x, check=True): - ``x`` -- a cone of the fan, a toric divisor, or a valid input for - :class:`sage.modules.fg_pid.fgp_module.FGP_Module_class`. + :class:`sage.modules.fg_pid.fgp_module.FGP_Module_class` - - ``check`` -- bool (default: ``True``). See - :class:`sage.modules.fg_pid.fgp_module.FGP_Module_class`. + - ``check`` -- boolean (default: ``True``); see + :class:`sage.modules.fg_pid.fgp_module.FGP_Module_class` EXAMPLES:: @@ -763,9 +761,7 @@ def __truediv__(self, other): r""" Return the quotient of the Chow group by a subgroup. - OUTPUT: - - Currently not implemented. + OUTPUT: currently not implemented EXAMPLES:: @@ -800,15 +796,13 @@ def _repr_(self) -> str: def _cone_to_V(self, cone): r""" - Convert a cone into the corresponding vector in ``self._V`` + Convert a cone into the corresponding vector in ``self._V``. INPUT: - - ``cone`` -- a :class:`sage.geometry.cone.ConvexRationalPolyhedralCone`. + - ``cone`` -- a :class:`sage.geometry.cone.ConvexRationalPolyhedralCone` - OUTPUT: - - The corresponding element of ``self.V()``. + OUTPUT: the corresponding element of ``self.V()`` EXAMPLES:: @@ -829,8 +823,8 @@ def degree(self, k=None): INPUT: - - ``k`` -- an integer or ``None`` (default). The degree of the - Chow group. + - ``k`` -- integer or ``None`` (default); the degree of the + Chow group OUTPUT: @@ -933,12 +927,12 @@ def coordinate_vector(self, chow_cycle, degree=None, reduce=True): INPUT: - - ``chow_cycle`` -- a :class:`ChowCycle`. + - ``chow_cycle`` -- a :class:`ChowCycle` - - ``degree`` -- None (default) or an integer. + - ``degree`` -- ``None`` (default) or integer - - ``reduce`` -- boolean (default: ``True``). Whether to reduce - modulo the invariants. + - ``reduce`` -- boolean (default: ``True``); whether to reduce + modulo the invariants OUTPUT: @@ -970,8 +964,8 @@ def gens(self, degree=None): INPUT: - - ``degree`` -- integer (optional). The degree of the Chow - group. + - ``degree`` -- integer (optional); the degree of the Chow + group OUTPUT: @@ -1067,9 +1061,9 @@ def __init__(self, A, d): INPUT: - - ``A`` -- A :class:`ChowGroup_class`. + - ``A`` -- a :class:`ChowGroup_class` - - ``d`` -- integer. The degree of the Chow group. + - ``d`` -- integer; the degree of the Chow group EXAMPLES:: @@ -1101,7 +1095,7 @@ def _repr_(self) -> str: """ Return a string representation. - OUTPUT: A string. + OUTPUT: string EXAMPLES:: @@ -1138,7 +1132,7 @@ def module(self): """ Return the submodule of the toric Chow group generated. - OUTPUT: A :class:`sage.modules.fg_pid.fgp_module.FGP_Module_class`. + OUTPUT: a :class:`sage.modules.fg_pid.fgp_module.FGP_Module_class` EXAMPLES:: @@ -1153,7 +1147,7 @@ def ngens(self) -> int: """ Return the number of generators. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -1170,9 +1164,9 @@ def gen(self, i): INPUT: - - ``i`` -- integer. The index of the generator to be returned. + - ``i`` -- integer; the index of the generator to be returned - OUTPUT: A Chow cycle. + OUTPUT: a Chow cycle EXAMPLES:: @@ -1187,7 +1181,7 @@ def gens(self): """ Return the generators of the Chow group of fixed degree. - OUTPUT: A tuple of Chow cycles of fixed degree generating + OUTPUT: a tuple of Chow cycles of fixed degree generating :meth:`module`. EXAMPLES:: @@ -1206,9 +1200,9 @@ def is_ChowGroup(x) -> bool: INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: @@ -1234,9 +1228,9 @@ def is_ChowCycle(x) -> bool: INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: ``True`` or ``False``. + OUTPUT: boolean EXAMPLES:: diff --git a/src/sage/schemes/toric/divisor.py b/src/sage/schemes/toric/divisor.py old mode 100644 new mode 100755 index dc98d7843eb..1da707e0cb6 --- a/src/sage/schemes/toric/divisor.py +++ b/src/sage/schemes/toric/divisor.py @@ -198,7 +198,7 @@ def is_ToricDivisor(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: @@ -235,7 +235,7 @@ def ToricDivisor(toric_variety, arg=None, ring=None, check=True, reduce=True): INPUT: - ``toric_variety`` -- a :class:`toric variety - `; + ` - ``arg`` -- one of the following description of the toric divisor to be constructed: @@ -254,11 +254,11 @@ def ToricDivisor(toric_variety, arg=None, ring=None, check=True, reduce=True): divisor group. If ``ring`` is not specified, a coefficient ring suitable for ``arg`` is derived. - - ``check`` -- bool (default: ``True``). Whether to coerce + - ``check`` -- boolean (default: ``True``); whether to coerce coefficients into base ring. Setting it to ``False`` can speed up construction. - - ``reduce`` -- reduce (default: ``True``). Whether to combine common + - ``reduce`` -- reduce (default: ``True``); whether to combine common terms. Setting it to ``False`` can speed up construction. .. WARNING:: @@ -268,7 +268,7 @@ def ToricDivisor(toric_variety, arg=None, ring=None, check=True, reduce=True): ``reduce=False`` it is your responsibility to pass valid input data ``arg``. - OUTPUT: A :class:`sage.schemes.toric.divisor.ToricDivisor_generic`. + OUTPUT: a :class:`sage.schemes.toric.divisor.ToricDivisor_generic` EXAMPLES:: @@ -388,15 +388,15 @@ class ToricDivisor_generic(Divisor_generic): INPUT: - - ``v`` -- a list of tuples (multiplicity, coordinate). + - ``v`` -- list of tuples (multiplicity, coordinate) - - ``parent`` -- :class:`ToricDivisorGroup`. The parent divisor group. + - ``parent`` -- :class:`ToricDivisorGroup`; the parent divisor group - - ``check`` -- boolean. Type-check the entries of ``v``, see - :class:`~sage.schemes.generic.divisor_group.DivisorGroup_generic`. + - ``check`` -- boolean; type-check the entries of ``v``, see + :class:`~sage.schemes.generic.divisor_group.DivisorGroup_generic` - - ``reduce`` -- boolean. Combine coefficients in ``v``, see - :class:`~sage.schemes.generic.divisor_group.DivisorGroup_generic`. + - ``reduce`` -- boolean; combine coefficients in ``v``, see + :class:`~sage.schemes.generic.divisor_group.DivisorGroup_generic` .. WARNING:: @@ -486,11 +486,9 @@ def coefficient(self, x): INPUT: - ``x`` -- one of the homogeneous coordinates, either given by - the variable or its index. + the variable or its index - OUTPUT: - - The coefficient of ``x``. + OUTPUT: the coefficient of ``x`` EXAMPLES:: @@ -525,9 +523,9 @@ def function_value(self, point): INPUT: - ``point`` -- either an integer, interpreted as the index of a ray of - `\Sigma`, or a point of the lattice `N`. + `\Sigma`, or a point of the lattice `N` - OUTPUT: An integer or a rational number. + OUTPUT: integer or a rational number EXAMPLES:: @@ -567,17 +565,15 @@ def m(self, cone): INPUT: - - ``cone`` -- A cone in the fan of the toric variety. - - OUTPUT: + - ``cone`` -- a cone in the fan of the toric variety - - If possible, a point of lattice `M`. + OUTPUT: if possible, a point of lattice `M` - If the dual vector cannot be chosen integral, a rational vector is returned. - If there is no such vector (i.e. ``self`` is not even a - `\QQ`-Cartier divisor), a :class:`ValueError` is raised. + `\QQ`-Cartier divisor), a :exc:`ValueError` is raised. EXAMPLES:: @@ -783,7 +779,7 @@ def move_away_from(self, cone): .. NOTE:: A divisor that is Weil but not Cartier might be impossible - to move away. In this case, a :class:`ValueError` is raised. + to move away. In this case, a :exc:`ValueError` is raised. EXAMPLES:: @@ -883,12 +879,12 @@ def divisor_class(self): def Chow_cycle(self, ring=ZZ): r""" - Returns the Chow homology class of the divisor. + Return the Chow homology class of the divisor. INPUT: - - ``ring`` -- Either ``ZZ`` (default) or ``QQ``. The base ring - of the Chow group. + - ``ring`` -- either ``ZZ`` (default) or ``QQ``; the base ring + of the Chow group OUTPUT: @@ -916,9 +912,7 @@ def is_ample(self): r""" Return whether a `\QQ`-Cartier divisor is ample. - OUTPUT: - - - ``True`` if the divisor is in the ample cone, ``False`` otherwise. + OUTPUT: ``True`` if the divisor is in the ample cone, ``False`` otherwise .. NOTE:: @@ -1059,9 +1053,7 @@ def polyhedron(self): Return the polyhedron `P_D\subset M` associated to a toric divisor `D`. - OUTPUT: - - `P_D` as an instance of :class:`~sage.geometry.polyhedron.base.Polyhedron_base`. + OUTPUT: `P_D` as an instance of :class:`~sage.geometry.polyhedron.base.Polyhedron_base` EXAMPLES:: @@ -1145,7 +1137,7 @@ def sections(self): the line bundle (or reflexive sheaf) associated to the divisor. - OUTPUT: A :class:`tuple` of points of lattice `M`. + OUTPUT: a :class:`tuple` of points of lattice `M` EXAMPLES:: @@ -1191,9 +1183,7 @@ def sections_monomials(self): The sections are described as monomials in the generalized homogeneous coordinates. - OUTPUT: - - - tuple of monomials in the coordinate ring of ``self``. + OUTPUT: tuple of monomials in the coordinate ring of ``self`` EXAMPLES:: @@ -1230,7 +1220,7 @@ def monomial(self, point): INPUT: - - ``point`` -- a point in ``self.variety().fan().dual_lattice()``. + - ``point`` -- a point in ``self.variety().fan().dual_lattice()`` OUTPUT: @@ -1270,8 +1260,8 @@ def Kodaira_map(self, names='z'): INPUT: - - ``names`` -- string (optional; default ``'z'``). The - variable names for the destination projective space. + - ``names`` -- string (default: ``'z'``); the + variable names for the destination projective space EXAMPLES:: @@ -1321,9 +1311,9 @@ def _sheaf_complex(self, m): INPUT: - - `m` -- a point in ``self.scheme().fan().dual_lattice()``. + - ``m`` -- a point in ``self.scheme().fan().dual_lattice()`` - OUTPUT: A :class:`simplicial complex `. + OUTPUT: a :class:`simplicial complex ` EXAMPLES:: @@ -1350,16 +1340,16 @@ def cone_is_negative(cone): # and non-trivial def _sheaf_cohomology(self, cplx): """ - Returns the sheaf cohomology as the shifted, reduced cohomology + Return the sheaf cohomology as the shifted, reduced cohomology of the complex. Helper for :meth:`cohomology`. INPUT: - - ``cplx`` -- simplicial complex. + - ``cplx`` -- simplicial complex - OUTPUT: An integer vector. + OUTPUT: integer vector EXAMPLES:: @@ -1457,11 +1447,11 @@ def cohomology(self, weight=None, deg=None, dim=False): INPUT: - - ``weight`` -- (optional) a point of the `M`-lattice. + - ``weight`` -- (optional) a point of the `M`-lattice - - ``deg`` -- (optional) the degree of the cohomology group. + - ``deg`` -- (optional) the degree of the cohomology group - - ``dim`` -- boolean. If ``False`` (default), the cohomology + - ``dim`` -- boolean; if ``False`` (default), the cohomology groups are returned as vector spaces. If ``True``, only the dimension of the vector space(s) is returned. @@ -1670,17 +1660,15 @@ def __init__(self, toric_variety, base_ring): - ``toric_variety`` -- a :class:`toric variety - ``; + `` - ``base_ring`` -- the coefficient ring of this divisor group, - usually `\ZZ` (default) or `\QQ`. + usually `\ZZ` (default) or `\QQ` Implementation note: :meth:`__classcall__` sets the default value for ``base_ring``. - OUTPUT: - - Divisor group of the toric variety. + OUTPUT: divisor group of the toric variety EXAMPLES:: @@ -1704,7 +1692,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: A string. + OUTPUT: string TESTS:: @@ -1718,9 +1706,7 @@ def _repr_(self): """ Return a string representation of the toric divisor group. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -1777,7 +1763,7 @@ def gen(self, i): INPUT: - - ``i`` -- integer. + - ``i`` -- integer OUTPUT: @@ -1795,15 +1781,15 @@ def gen(self, i): def _element_constructor_(self, x, check=True, reduce=True): r""" - Construct a :class:`ToricDivisor_generic` + Construct a :class:`ToricDivisor_generic`. INPUT: - ``x`` -- something defining a toric divisor, see - :func:`ToricDivisor`. + :func:`ToricDivisor` - - ``check``, ``reduce`` -- boolean. See - :meth:`ToricDivisor_generic.__init__`. + - ``check``, ``reduce`` -- boolean; See + :meth:`ToricDivisor_generic.__init__` EXAMPLES:: @@ -1840,11 +1826,9 @@ def base_extend(self, R): INPUT: - - ``R`` -- ring. - - OUTPUT: + - ``R`` -- ring - - toric divisor group. + OUTPUT: toric divisor group EXAMPLES:: @@ -1896,11 +1880,9 @@ class ToricRationalDivisorClassGroup(FreeModule_ambient_field, UniqueRepresentat INPUT: - ``toric_variety`` -- :class:`toric variety - `. - - OUTPUT: + ` - - the basis lattice of ``group``. + OUTPUT: the basis lattice of ``group`` EXAMPLES:: @@ -2079,9 +2053,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -2097,9 +2069,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: diff --git a/src/sage/schemes/toric/divisor_class.pyx b/src/sage/schemes/toric/divisor_class.pyx old mode 100644 new mode 100755 index ccf70e51811..98ed1b377b3 --- a/src/sage/schemes/toric/divisor_class.pyx +++ b/src/sage/schemes/toric/divisor_class.pyx @@ -73,11 +73,9 @@ def is_ToricRationalDivisorClass(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything - OUTPUT: - - - ``True`` if ``x`` is a toric rational divisor class, ``False`` otherwise. + OUTPUT: ``True`` if ``x`` is a toric rational divisor class, ``False`` otherwise EXAMPLES:: @@ -106,9 +104,7 @@ cdef class ToricRationalDivisorClass(Vector_rational_dense): - same as for :class:`~sage.modules.vector_rational_dense.Vector_rational_dense`. - OUTPUT: - - - toric rational divisor class. + OUTPUT: toric rational divisor class TESTS:: @@ -204,17 +200,15 @@ cdef class ToricRationalDivisorClass(Vector_rational_dense): cpdef _dot_product_(self, Vector right): r""" - Raise a :class:`TypeError` exception. + Raise a :exc:`TypeError` exception. Dot product is not defined on toric rational divisor classes. INPUT: - - ``right`` -- vector. - - OUTPUT: + - ``right`` -- vector - A :class:`TypeError` exception is raised. + OUTPUT: a :exc:`TypeError` exception is raised TESTS:: @@ -234,9 +228,7 @@ cdef class ToricRationalDivisorClass(Vector_rational_dense): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -251,9 +243,7 @@ cdef class ToricRationalDivisorClass(Vector_rational_dense): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string EXAMPLES:: @@ -266,9 +256,7 @@ cdef class ToricRationalDivisorClass(Vector_rational_dense): r""" Return a divisor representing this divisor class. - OUTPUT: - - An instance of :class:`ToricDivisor` representing ``self``. + OUTPUT: an instance of :class:`ToricDivisor` representing ``self`` EXAMPLES:: @@ -296,17 +284,15 @@ def _ToricRationalDivisorClass_unpickle_v1(parent, entries, INPUT: - - ``parent`` -- rational divisor class group of a toric variety; - - - ``entries`` -- list of rationals specifying the divisor class; + - ``parent`` -- rational divisor class group of a toric variety - - ``degree`` -- integer, dimension of the ``parent``; + - ``entries`` -- list of rationals specifying the divisor class - - ``is_mutable`` -- boolean, whether the divisor class is mutable. + - ``degree`` -- integer; dimension of the ``parent`` - OUTPUT: + - ``is_mutable`` -- boolean, whether the divisor class is mutable - - :class:`toric rational divisor class `. + OUTPUT: :class:`toric rational divisor class ` TESTS:: diff --git a/src/sage/schemes/toric/fano_variety.py b/src/sage/schemes/toric/fano_variety.py old mode 100644 new mode 100755 index c17cf7c37d7..77a14643e4b --- a/src/sage/schemes/toric/fano_variety.py +++ b/src/sage/schemes/toric/fano_variety.py @@ -54,7 +54,7 @@ Its anticanonical "hypersurface" is a one-dimensional Calabi-Yau manifold:: - sage: P2.anticanonical_hypersurface(monomial_points="all") + sage: P2.anticanonical_hypersurface(monomial_points='all') Closed subscheme of 2-d CPR-Fano toric variety covered by 3 affine patches defined by: a0*z0^3 + a9*z0^2*z1 + a7*z0*z1^2 + a1*z1^3 + a8*z0^2*z2 + a6*z0*z1*z2 + a4*z1^2*z2 + a5*z0*z2^2 + a3*z1*z2^2 + a2*z2^3 @@ -62,15 +62,15 @@ In many cases it is sufficient to work with the "simplified polynomial moduli space" of anticanonical hypersurfaces:: - sage: P2.anticanonical_hypersurface(monomial_points="simplified") + sage: P2.anticanonical_hypersurface(monomial_points='simplified') Closed subscheme of 2-d CPR-Fano toric variety covered by 3 affine patches defined by: a0*z0^3 + a1*z1^3 + a6*z0*z1*z2 + a2*z2^3 The mirror family to these hypersurfaces lives inside the Fano toric variety obtained using ``simplex`` as ``Delta`` instead of ``Delta_polar``:: - sage: FTV = CPRFanoToricVariety(Delta=simplex, coordinate_points="all") - sage: FTV.anticanonical_hypersurface(monomial_points="simplified") + sage: FTV = CPRFanoToricVariety(Delta=simplex, coordinate_points='all') + sage: FTV.anticanonical_hypersurface(monomial_points='simplified') Closed subscheme of 2-d CPR-Fano toric variety covered by 9 affine patches defined by: a2*z2^3*z3^2*z4*z5^2*z8 + a1*z1^3*z3*z4^2*z7^2*z9 + a3*z0*z1*z2*z3*z4*z5*z7*z8*z9 + a0*z0^3*z5*z7*z8^2*z9^2 @@ -81,7 +81,7 @@ points which do not lie on a generic anticanonical hypersurface:: sage: FTV = CPRFanoToricVariety(Delta=simplex, coordinate_points="all but facets") - sage: FTV.anticanonical_hypersurface(monomial_points="simplified") + sage: FTV.anticanonical_hypersurface(monomial_points='simplified') Closed subscheme of 2-d CPR-Fano toric variety covered by 3 affine patches defined by: a0*z0^3 + a1*z1^3 + a3*z0*z1*z2 + a2*z2^3 @@ -128,8 +128,8 @@ from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing from sage.rings.rational_field import QQ -from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing -from sage.rings.polynomial.polynomial_ring import is_PolynomialRing +from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base +from sage.rings.polynomial.polynomial_ring import PolynomialRing_general from sage.rings.fraction_field import FractionField_generic from sage.schemes.toric.toric_subscheme import AlgebraicScheme_subscheme_toric @@ -153,7 +153,7 @@ def is_CPRFanoToricVariety(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: @@ -218,7 +218,7 @@ def CPRFanoToricVariety(Delta=None, *normal fan* of ``Delta``. Either ``Delta`` or ``Delta_polar`` must be given, but not both at the same time, since one is completely determined by another via :meth:`polar - ` method; + ` method. - ``Delta_polar`` -- reflexive :class:`lattice polytope `. The fan of the @@ -226,7 +226,7 @@ def CPRFanoToricVariety(Delta=None, *face fan* of ``Delta_polar``. Either ``Delta`` or ``Delta_polar`` must be given, but not both at the same time, since one is completely determined by another via :meth:`polar - ` method; + ` method. - ``coordinate_points`` -- list of integers or string. A list will be interpreted as indices of (boundary) points of ``Delta_polar`` which @@ -243,26 +243,26 @@ def CPRFanoToricVariety(Delta=None, of these lists must define a generating cone of a fan subdividing the normal fan of ``Delta``. Default ``charts`` correspond to the normal fan of ``Delta`` without subdivision. The fan specified by ``charts`` will - be subdivided to include all of the requested ``coordinate_points``; + be subdivided to include all of the requested ``coordinate_points``. - ``coordinate_names`` -- names of variables for the coordinate ring, see :func:`~sage.schemes.toric.variety.normalize_names` for acceptable formats. If not given, indexed variable names will be - created automatically; + created automatically. - ``names`` -- an alias of ``coordinate_names`` for internal use. You may specify either ``names`` or ``coordinate_names``, - but not both; + but not both. - ``coordinate_name_indices`` -- list of integers, indices for indexed variables. If not given, the index of each variable will coincide with - the index of the corresponding point of ``Delta_polar``; + the index of the corresponding point of ``Delta_polar``. - ``make_simplicial`` -- if ``True``, the underlying fan will be made - simplicial (default: ``False``); + simplicial (default: ``False``) - ``base_ring`` -- base field of the CPR-Fano toric variety - (default: `\QQ`); + (default: `\QQ`) - ``base_field`` -- alias for ``base_ring``. Takes precedence if both are specified. @@ -272,7 +272,7 @@ def CPRFanoToricVariety(Delta=None, ``Delta``). If you know for sure that the input is valid, you may significantly decrease construction time using ``check=False`` option. - OUTPUT: :class:`CPR-Fano toric variety `. + OUTPUT: :class:`CPR-Fano toric variety ` EXAMPLES: @@ -330,7 +330,7 @@ def CPRFanoToricVariety(Delta=None, sage: FTV = CPRFanoToricVariety(Delta_polar=square, ....: coordinate_points=[8,0,2,1,3], - ....: coordinate_names="x+") + ....: coordinate_names='x+') sage: FTV.fan().rays() N( 1, 0), N( 1, 1), N(-1, -1), N( 1, -1), N(-1, 1) @@ -339,7 +339,7 @@ def CPRFanoToricVariety(Delta=None, (x8, x0, x2, x1, x3) sage: FTV = CPRFanoToricVariety(Delta_polar=square, - ....: coordinate_points="all", + ....: coordinate_points='all', ....: coordinate_names="x y Z+") sage: FTV.fan().rays() N( 1, 1), N( 1, -1), N(-1, -1), N(-1, 1), @@ -357,7 +357,7 @@ def CPRFanoToricVariety(Delta=None, you want:: sage: FTV = CPRFanoToricVariety(Delta_polar=square, - ....: coordinate_points="all", + ....: coordinate_points='all', ....: coordinate_names="x y Z+", ....: coordinate_name_indices=list(range(8))) sage: FTV.gens() @@ -369,7 +369,7 @@ def CPRFanoToricVariety(Delta=None, much "automatic" ones:: sage: FTV = CPRFanoToricVariety(Delta_polar=square, - ....: coordinate_points="all", + ....: coordinate_points='all', ....: coordinate_names="x Z+", ....: coordinate_name_indices=list(range(8))) sage: FTV.gens() @@ -379,14 +379,14 @@ def CPRFanoToricVariety(Delta=None, accordingly:: sage: FTV = CPRFanoToricVariety(Delta_polar=square, - ....: coordinate_points="all", + ....: coordinate_points='all', ....: coordinate_names="x Z+", ....: coordinate_name_indices=[0] + list(range(7))) sage: FTV.gens() (x, Z0, Z1, Z2, Z3, Z4, Z5, Z6) sage: FTV = CPRFanoToricVariety(Delta_polar=square, - ....: coordinate_points="all", + ....: coordinate_points='all', ....: coordinate_names="x y Z+", ....: coordinate_name_indices=[0]*2 + list(range(6))) sage: FTV.gens() @@ -612,27 +612,27 @@ class CPRFanoToricVariety_field(ToricVariety_field): INPUT: - - ``Delta_polar`` -- reflexive polytope; + - ``Delta_polar`` -- reflexive polytope - ``fan`` -- rational polyhedral fan subdividing the face fan of - ``Delta_polar``; + ``Delta_polar`` - ``coordinate_points`` -- list of indices of points of ``Delta_polar`` - used for rays of ``fan``; + used for rays of ``fan`` - ``point_to_ray`` -- dictionary mapping the index of a coordinate point - to the index of the corresponding ray; + to the index of the corresponding ray - ``coordinate_names`` -- names of the variables of the coordinate ring in the format accepted by - :func:`~sage.schemes.toric.variety.normalize_names`; + :func:`~sage.schemes.toric.variety.normalize_names` - ``coordinate_name_indices`` -- indices for indexed variables, - if ``None``, will be equal to ``coordinate_points``; + if ``None``, will be equal to ``coordinate_points`` - - ``base_field`` -- base field of the CPR-Fano toric variety. + - ``base_field`` -- base field of the CPR-Fano toric variety - OUTPUT: :class:`CPR-Fano toric variety `. + OUTPUT: :class:`CPR-Fano toric variety ` TESTS:: @@ -669,9 +669,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -685,9 +683,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -715,7 +711,7 @@ def anticanonical_hypersurface(self, **kwds): INPUT: - - ``monomial points`` -- a list of integers or a string. A list will be + - ``monomial points`` -- list of integers or a string. A list will be interpreted as indices of points of `\Delta` which should be used for monomials of this hypersurface. A string must be one of the following descriptions of points of `\Delta`: @@ -731,11 +727,11 @@ def anticanonical_hypersurface(self, **kwds): - ``coefficient_names`` -- names for the monomial coefficients, see :func:`~sage.schemes.toric.variety.normalize_names` for acceptable formats. If not given, indexed coefficient names will - be created automatically; + be created automatically. - - ``coefficient_name_indices`` -- a list of integers, indices for + - ``coefficient_name_indices`` -- list of integers, indices for indexed coefficients. If not given, the index of each coefficient - will coincide with the index of the corresponding point of `\Delta`; + will coincide with the index of the corresponding point of `\Delta`. - ``coefficients`` -- as an alternative to specifying coefficient names and/or indices, you can give the coefficients themselves as @@ -758,7 +754,7 @@ def anticanonical_hypersurface(self, **kwds): Its anticanonical "hypersurface" is a one-dimensional Calabi-Yau manifold:: - sage: P2.anticanonical_hypersurface(monomial_points="all") + sage: P2.anticanonical_hypersurface(monomial_points='all') Closed subscheme of 2-d CPR-Fano toric variety covered by 3 affine patches defined by: a0*z0^3 + a9*z0^2*z1 + a7*z0*z1^2 + a1*z1^3 + a8*z0^2*z2 + a6*z0*z1*z2 @@ -767,7 +763,7 @@ def anticanonical_hypersurface(self, **kwds): In many cases it is sufficient to work with the "simplified polynomial moduli space" of anticanonical hypersurfaces:: - sage: P2.anticanonical_hypersurface(monomial_points="simplified") + sage: P2.anticanonical_hypersurface(monomial_points='simplified') Closed subscheme of 2-d CPR-Fano toric variety covered by 3 affine patches defined by: a0*z0^3 + a1*z1^3 + a6*z0*z1*z2 + a2*z2^3 @@ -777,8 +773,8 @@ def anticanonical_hypersurface(self, **kwds): ``Delta_polar``:: sage: FTV = CPRFanoToricVariety(Delta=simplex, - ....: coordinate_points="all") - sage: FTV.anticanonical_hypersurface(monomial_points="simplified") + ....: coordinate_points='all') + sage: FTV.anticanonical_hypersurface(monomial_points='simplified') Closed subscheme of 2-d CPR-Fano toric variety covered by 9 affine patches defined by: a2*z2^3*z3^2*z4*z5^2*z8 + a1*z1^3*z3*z4^2*z7^2*z9 @@ -791,7 +787,7 @@ def anticanonical_hypersurface(self, **kwds): sage: FTV = CPRFanoToricVariety(Delta=simplex, ....: coordinate_points="all but facets") - sage: FTV.anticanonical_hypersurface(monomial_points="simplified") + sage: FTV.anticanonical_hypersurface(monomial_points='simplified') Closed subscheme of 2-d CPR-Fano toric variety covered by 3 affine patches defined by: a0*z0^3 + a1*z1^3 + a3*z0*z1*z2 + a2*z2^3 @@ -840,9 +836,9 @@ def change_ring(self, F): INPUT: - - ``F`` -- field. + - ``F`` -- field - OUTPUT: :class:`CPR-Fano toric variety ` over ``F``. + OUTPUT: :class:`CPR-Fano toric variety ` over ``F`` .. NOTE:: @@ -891,11 +887,9 @@ def coordinate_point_to_coordinate(self, point): INPUT: - - ``point`` -- integer from the list of :meth:`coordinate_points`. - - OUTPUT: + - ``point`` -- integer from the list of :meth:`coordinate_points` - - the corresponding generator of the coordinate ring of ``self``. + OUTPUT: the corresponding generator of the coordinate ring of ``self`` EXAMPLES:: @@ -914,7 +908,7 @@ def coordinate_points(self): r""" Return indices of points of :meth:`Delta_polar` used for coordinates. - OUTPUT: :class:`tuple` of integers. + OUTPUT: :class:`tuple` of integers EXAMPLES:: @@ -928,7 +922,7 @@ def coordinate_points(self): (z0, z1, z2, z3, z8) sage: FTV = CPRFanoToricVariety(Delta_polar=square, - ....: coordinate_points="all") + ....: coordinate_points='all') sage: FTV.coordinate_points() (0, 1, 2, 3, 4, 5, 7, 8) sage: FTV.gens() @@ -1012,7 +1006,7 @@ def nef_complete_intersection(self, nef_partition, **kwds): - ``nef_partition`` -- a `k`-part :class:`nef-partition ` of `\Delta^\circ`, all - other parameters (if given) must be lists of length `k`; + other parameters (if given) must be lists of length `k` - ``monomial_points`` -- the `i`-th element of this list is either a list of integers or a string. A list will be interpreted as indices @@ -1025,18 +1019,18 @@ def nef_complete_intersection(self, nef_partition, **kwds): * "all" (default), when using this description, it is also OK to pass a single string as - ``monomial_points`` instead of repeating it `k` times; + ``monomial_points`` instead of repeating it `k` times. - ``coefficient_names`` -- the `i`-th element of this list specifies names for the monomial coefficients of the `i`-th polynomial, see :func:`~sage.schemes.toric.variety.normalize_names` for acceptable formats. If not given, indexed coefficient names will - be created automatically; + be created automatically. - - ``coefficient_name_indices`` -- the `i`-th element of this list + - ``coefficient_name_indices`` -- the `i`-th element of this list specifies indices for indexed coefficients of the `i`-th polynomial. If not given, the index of each coefficient will coincide with the - index of the corresponding point of `\Delta_i`; + index of the corresponding point of `\Delta_i`. - ``coefficients`` -- as an alternative to specifying coefficient names and/or indices, you can give the coefficients themselves as @@ -1069,7 +1063,7 @@ def nef_complete_intersection(self, nef_partition, **kwds): Now we include only monomials associated to vertices of `\Delta_i`:: - sage: X.nef_complete_intersection(np, monomial_points="vertices") + sage: X.nef_complete_intersection(np, monomial_points='vertices') Closed subscheme of 3-d CPR-Fano toric variety covered by 10 affine patches defined by: a0*z1*z4^2*z5^2*z7^3 + a2*z2*z4*z5*z6*z7^2*z8^2 @@ -1081,7 +1075,7 @@ def nef_complete_intersection(self, nef_partition, **kwds): instead of using default generic names:: sage: X.nef_complete_intersection(np, - ....: monomial_points="vertices", + ....: monomial_points='vertices', ....: coefficients=[("a", "a^2", "a/e", "c_i"), list(range(1,6))]) Closed subscheme of 3-d CPR-Fano toric variety covered by 10 affine patches defined by: @@ -1094,7 +1088,7 @@ def nef_complete_intersection(self, nef_partition, **kwds): intersections in a completely resolved ambient toric variety:: sage: X = CPRFanoToricVariety(Delta_polar=p, - ....: coordinate_points="all") + ....: coordinate_points='all') sage: X.nef_complete_intersection(np) Closed subscheme of 3-d CPR-Fano toric variety covered by 22 affine patches defined by: @@ -1118,11 +1112,11 @@ def cartesian_product(self, other, - ``other`` -- a (possibly :class:`CPR-Fano `) :class:`toric variety - `; + ` - ``coordinate_names`` -- names of variables for the coordinate ring, see :func:`normalize_names` for acceptable formats. If not given, - indexed variable names will be created automatically; + indexed variable names will be created automatically. - ``coordinate_indices`` -- list of integers, indices for indexed variables. If not given, the index of each variable will coincide @@ -1176,12 +1170,12 @@ def resolve(self, **kwds): - ``new_points`` -- list of integers, indices of boundary points of :meth:`Delta_polar`, which should be added as rays to the - subdividing fan; + subdividing fan - all other arguments will be passed to :meth:`~sage.schemes.toric.variety.ToricVariety_field.resolve` - method of (general) toric varieties, see its documentation for - details. + method of (general) toric varieties; see its documentation for + details OUTPUT: @@ -1270,16 +1264,15 @@ class AnticanonicalHypersurface(AlgebraicScheme_subscheme_toric): INPUT: - ``P_Delta`` -- :class:`CPR-Fano toric variety - ` associated to a reflexive polytope - `\Delta`; + ` associated to a reflexive polytope `\Delta` - - see :meth:`CPRFanoToricVariety_field.anticanonical_hypersurface` for - documentation on all other acceptable parameters. + - see :meth:`CPRFanoToricVariety_field.anticanonical_hypersurface` for + documentation on all other acceptable parameters OUTPUT: - - :class:`anticanonical hypersurface ` of - ``P_Delta`` (with the extended base field, if necessary). + :class:`anticanonical hypersurface ` of + ``P_Delta`` (with the extended base field, if necessary). EXAMPLES:: @@ -1312,7 +1305,7 @@ def __init__(self, P_Delta, monomial_points=None, coefficient_names=None, sage: F = GF(5^2, "a") # needs sage.rings.finite_rings sage: X = P1xP1.change_ring(F) # needs sage.rings.finite_rings - sage: X.anticanonical_hypersurface(monomial_points="all", # needs sage.rings.finite_rings + sage: X.anticanonical_hypersurface(monomial_points='all', # needs sage.rings.finite_rings ....: coefficients=[1]*X.Delta().npoints()) Closed subscheme of 2-d CPR-Fano toric variety covered by 4 affine patches defined by: @@ -1384,11 +1377,10 @@ class NefCompleteIntersection(AlgebraicScheme_subscheme_toric): INPUT: - ``P_Delta`` -- a :class:`CPR-Fano toric variety - ` associated to a reflexive polytope - `\Delta`; + ` associated to a reflexive polytope `\Delta` - see :meth:`CPRFanoToricVariety_field.nef_complete_intersection` for - documentation on all other acceptable parameters. + documentation on all other acceptable parameters OUTPUT: @@ -1411,7 +1403,7 @@ class NefCompleteIntersection(AlgebraicScheme_subscheme_toric): more elaborate example. """ def __init__(self, P_Delta, nef_partition, - monomial_points="all", coefficient_names=None, + monomial_points='all', coefficient_names=None, coefficient_name_indices=None, coefficients=None): r""" See :meth:`CPRFanoToricVariety_field.nef_complete_intersection` for @@ -1510,7 +1502,7 @@ def cohomology_class(self): r""" Return the class of ``self`` in the ambient space cohomology ring. - OUTPUT: A :class:`cohomology class `. + OUTPUT: a :class:`cohomology class ` EXAMPLES:: @@ -1536,7 +1528,7 @@ def nef_partition(self): r""" Return the nef-partition associated to ``self``. - OUTPUT: A :class:`nef-partition `. + OUTPUT: a :class:`nef-partition ` EXAMPLES:: @@ -1563,9 +1555,9 @@ def add_variables(field, variables): INPUT: - - ``field`` -- a field; + - ``field`` -- a field - - ``variables`` -- a list of strings. + - ``variables`` -- list of strings OUTPUT: @@ -1593,7 +1585,7 @@ def add_variables(field, variables): if isinstance(field, FractionField_generic): # Q(a) ---> Q(a, b) rather than Q(a)(b) R = field.ring() - if is_PolynomialRing(R) or is_MPolynomialRing(R): + if isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base): new_variables = list(R.variable_names()) for v in variables: if v not in new_variables: diff --git a/src/sage/schemes/toric/homset.py b/src/sage/schemes/toric/homset.py old mode 100644 new mode 100755 index 830eb09de44..87f648e1a9d --- a/src/sage/schemes/toric/homset.py +++ b/src/sage/schemes/toric/homset.py @@ -13,7 +13,7 @@ done by :class:`~sage.schemes.generic.homset.SchemeHomset_points` and its subclasses. -.. note:: +.. NOTE:: You should not create the Hom-sets manually. Instead, use the :meth:`~sage.structure.parent.Hom` method that is inherited by all @@ -176,17 +176,15 @@ def _element_constructor_(self, x, check=True): INPUT: - - `x` -- anything that defines a morphism of toric + - ``x`` -- anything that defines a morphism of toric varieties. A matrix, fan morphism, or a list or tuple of homogeneous polynomials that define a morphism. - - ``check`` -- boolean (default: ``True``) passed onto + - ``check`` -- boolean (default: ``True``); passed onto functions called by this to be more careful about input argument type checking - OUTPUT: - - The morphism of toric varieties determined by ``x``. + OUTPUT: the morphism of toric varieties determined by ``x`` EXAMPLES: @@ -271,9 +269,7 @@ def _an_element_(self): """ Construct a sample morphism. - OUTPUT: - - An element of the homset. + OUTPUT: an element of the homset EXAMPLES:: @@ -298,7 +294,7 @@ class SchemeHomset_points_toric_base(SchemeHomset_points): - same as for :class:`SchemeHomset_points`. - OUTPUT: A scheme morphism of type :class:`SchemeHomset_points_toric_base`. + OUTPUT: a scheme morphism of type :class:`SchemeHomset_points_toric_base` EXAMPLES:: @@ -318,7 +314,7 @@ def is_finite(self): """ Return whether there are finitely many points. - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -432,7 +428,7 @@ class SchemeHomset_points_toric_field(SchemeHomset_points_toric_base): - same as for :class:`~sage.schemes.generic.homset.SchemeHomset_points`. - OUTPUT: A scheme morphism of type :class:`SchemeHomset_points_toric_field`. + OUTPUT: a scheme morphism of type :class:`SchemeHomset_points_toric_field` EXAMPLES:: @@ -493,9 +489,7 @@ def cardinality(self): r""" Return the number of points of the toric variety. - OUTPUT: - - An integer or infinity. The cardinality of the set of points. + OUTPUT: integer or infinity; the cardinality of the set of points EXAMPLES:: @@ -568,7 +562,7 @@ def __iter__(self): """ Iterate over the points of the variety. - OUTPUT: Iterator over points. + OUTPUT: iterator over points EXAMPLES:: @@ -615,9 +609,7 @@ def __iter__(self): """ Iterate over the points of the variety. - OUTPUT: - - Iterator over points. + OUTPUT: iterator over points EXAMPLES:: @@ -636,9 +628,7 @@ def cardinality(self): """ Return the number of points of the toric variety. - OUTPUT: - - An integer or infinity. The cardinality of the set of points. + OUTPUT: integer or infinity; the cardinality of the set of points EXAMPLES:: diff --git a/src/sage/schemes/toric/ideal.py b/src/sage/schemes/toric/ideal.py old mode 100644 new mode 100755 index 8feca9114ad..41b69d05aca --- a/src/sage/schemes/toric/ideal.py +++ b/src/sage/schemes/toric/ideal.py @@ -147,24 +147,24 @@ class ToricIdeal(MPolynomialIdeal): INPUT: - - ``A`` -- integer matrix. The defining matrix of the toric ideal. + - ``A`` -- integer matrix; the defining matrix of the toric ideal - - ``names`` -- string (optional). Names for the variables. By + - ``names`` -- string (optional); names for the variables. By default, this is ``'z'`` and the variables will be named ``z0``, ``z1``, ... - - ``base_ring`` -- a ring (optional). Default: `\QQ`. The base + - ``base_ring`` -- a ring (default: `\QQ`); the base ring of the ideal. A toric ideal uses only coefficients `\pm 1`. - - ``polynomial_ring`` -- a polynomial ring (optional). The - polynomial ring to construct the ideal in. + - ``polynomial_ring`` -- a polynomial ring (optional); the + polynomial ring to construct the ideal in You may specify the ambient polynomial ring via the ``polynomial_ring`` parameter or via the ``names`` and - ``base_ring`` parameter. A :class:`ValueError` is raised if you + ``base_ring`` parameter. A :exc:`ValueError` is raised if you specify both. - - ``algorithm`` -- string (optional). The algorithm to use. For + - ``algorithm`` -- string (optional); the algorithm to use. For now, must be ``'HostenSturmfels'`` which is the algorithm proposed by Hosten and Sturmfels in [SH1995b]_. @@ -250,7 +250,7 @@ def A(self): """ Return the defining matrix. - OUTPUT: An integer matrix. + OUTPUT: integer matrix EXAMPLES:: @@ -266,7 +266,7 @@ def ker(self): """ Return the kernel of the defining matrix. - OUTPUT: The kernel of ``self.A()``. + OUTPUT: the kernel of ``self.A()``. EXAMPLES:: @@ -286,8 +286,7 @@ def nvariables(self): r""" Return the number of variables of the ambient polynomial ring. - OUTPUT: An integer. The number of columns of the defining matrix - :meth:`A`. + OUTPUT: integer; the number of columns of the defining matrix :meth:`A` EXAMPLES:: @@ -304,12 +303,10 @@ def _init_ring(self, term_order): INPUT: - - ``term_order`` -- string. The order of the variables, for - example ``'neglex'`` and ``'degrevlex'``. + - ``term_order`` -- string; the order of the variables, for + example ``'neglex'`` and ``'degrevlex'`` - OUTPUT: - - A polynomial ring with the given term order. + OUTPUT: a polynomial ring with the given term order .. NOTE:: @@ -340,11 +337,9 @@ def _naive_ideal(self, ring): INPUT: - - ``ring`` -- the ambient ring of the ideal. - - OUTPUT: + - ``ring`` -- the ambient ring of the ideal - A subideal of the toric ideal in the polynomial ring ``ring``. + OUTPUT: a subideal of the toric ideal in the polynomial ring ``ring`` EXAMPLES:: @@ -370,15 +365,13 @@ def _ideal_quotient_by_variable(self, ring, ideal, n): INPUT: - - ``ring`` -- the ambient polynomial ring in neglex order. - - - ``ideal`` -- the ideal `J`. + - ``ring`` -- the ambient polynomial ring in neglex order - - ``n`` -- Integer. The index of the next variable to divide by. + - ``ideal`` -- the ideal `J` - OUTPUT: + - ``n`` -- integer; the index of the next variable to divide by - The ideal quotient `(J:x_n^\infty)`. + OUTPUT: the ideal quotient `(J:x_n^\infty)` ALGORITHM: diff --git a/src/sage/schemes/toric/library.py b/src/sage/schemes/toric/library.py old mode 100644 new mode 100755 index c09c404d64a..1e1ff4d38d8 --- a/src/sage/schemes/toric/library.py +++ b/src/sage/schemes/toric/library.py @@ -197,16 +197,16 @@ def _make_ToricVariety(self, name, coordinate_names, base_ring): INPUT: - - ``name`` -- string. One of the pre-defined names in the - ``toric_varieties_rays_cones`` data structure. + - ``name`` -- string; one of the pre-defined names in the + ``toric_varieties_rays_cones`` data structure - - ``coordinate_names`` -- A string describing the names of the - homogeneous coordinates of the toric variety. + - ``coordinate_names`` -- string describing the names of the + homogeneous coordinates of the toric variety - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -236,16 +236,16 @@ def _make_CPRFanoToricVariety(self, name, coordinate_names, base_ring): INPUT: - - ``name`` -- string. One of the pre-defined names in the - ``toric_varieties_rays_cones`` data structure. + - ``name`` -- string; one of the pre-defined names in the + ``toric_varieties_rays_cones`` data structure - - ``coordinate_names`` -- A string describing the names of the - homogeneous coordinates of the toric variety. + - ``coordinate_names`` -- string describing the names of the + homogeneous coordinates of the toric variety - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -281,15 +281,14 @@ def dP6(self, names='x u y v z w', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -312,15 +311,14 @@ def dP7(self, names='x u y v z', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -343,15 +341,14 @@ def dP8(self, names='t x y z', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -374,15 +371,14 @@ def P1xP1(self, names='s t x y', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -405,15 +401,14 @@ def P1xP1_Z2(self, names='s t x y', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -438,15 +433,14 @@ def P1(self, names='s t', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -469,15 +463,14 @@ def P2(self, names='x y z', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -500,17 +493,16 @@ def P(self, n, names='z+', base_ring=QQ): INPUT: - - ``n`` -- positive integer. The dimension of the projective space. + - ``n`` -- positive integer; the dimension of the projective space - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -550,15 +542,14 @@ def A1(self, names='z', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -579,15 +570,14 @@ def A2(self, names='x y', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -609,17 +599,16 @@ def A(self, n, names='z+', base_ring=QQ): INPUT: - - ``n`` -- positive integer. The dimension of the affine space. + - ``n`` -- positive integer; the dimension of the affine space - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -656,15 +645,14 @@ def A2_Z2(self, names='x y', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -687,15 +675,14 @@ def P1xA1(self, names='s t z', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -718,15 +705,14 @@ def Conifold(self, names='u x y v', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -749,15 +735,14 @@ def dP6xdP6(self, names='x0 x1 x2 x3 x4 x5 y0 y1 y2 y3 y4 y5', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -785,15 +770,14 @@ def Cube_face_fan(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -820,15 +804,14 @@ def Cube_sublattice(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -855,15 +838,14 @@ def Cube_nonpolyhedral(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. .. NOTE:: @@ -898,16 +880,15 @@ def Cube_deformation(self,k, names=None, base_ring=QQ): INPUT: - - ``k`` -- integer. The case ``k=0`` is the same as - :meth:`Cube_face_fan`. + - ``k`` -- integer; the case ``k=0`` is the same as + :meth:`Cube_face_fan` - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety OUTPUT: @@ -932,10 +913,10 @@ def Cube_deformation(self,k, names=None, base_ring=QQ): k = ZZ(k) # make sure that we got a "mathematical" integer except TypeError: raise TypeError("cube deformations X_k are defined only for " - "non-negative integer k!\nGot: %s" % k) + "nonnegative integer k!\nGot: %s" % k) if k < 0: raise ValueError("cube deformations X_k are defined only for " - "non-negative k!\nGot: %s" % k) + "nonnegative k!\nGot: %s" % k) def rays(kappa): return matrix([[1, 1, 2 * kappa + 1], [1, -1, 1], @@ -955,15 +936,14 @@ def BCdlOG(self, names='v1 v2 c1 c2 v4 v5 b e1 e2 e3 f g v6', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -991,15 +971,14 @@ def BCdlOG_base(self, names='d4 d3 r2 r1 d2 u d1', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -1022,15 +1001,14 @@ def P2_112(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -1054,15 +1032,14 @@ def P2_123(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -1086,15 +1063,14 @@ def P4_11169(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -1118,15 +1094,14 @@ def P4_11169_resolved(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -1150,15 +1125,14 @@ def P4_11133(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -1181,15 +1155,14 @@ def P4_11133_resolved(self, names='z+', base_ring=QQ): INPUT: - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`CPR-Fano toric variety + OUTPUT: a :class:`CPR-Fano toric variety `. EXAMPLES:: @@ -1221,10 +1194,10 @@ def WP(self, *q, **kw): Two keyword arguments: - - ``base_ring`` -- a field (default: `\QQ`). + - ``base_ring`` -- a field (default: `\QQ`) - - ``names`` -- string or list (tuple) of strings (default 'z+'). See - :func:`~sage.schemes.toric.variety.normalize_names` for + - ``names`` -- string or list (tuple) of strings (default: ``'z+'``); + see :func:`~sage.schemes.toric.variety.normalize_names` for acceptable formats. OUTPUT: @@ -1304,17 +1277,16 @@ def torus(self, n, names='z+', base_ring=QQ): INPUT: - - ``n`` -- non-negative integer. The dimension of the algebraic torus. + - ``n`` -- nonnegative integer. The dimension of the algebraic torus - - ``names`` -- string. Names for the homogeneous - coordinates. See - :func:`~sage.schemes.toric.variety.normalize_names` - for acceptable formats. + - ``names`` -- string; names for the homogeneous coordinates. See + :func:`~sage.schemes.toric.variety.normalize_names` for acceptable + formats. - - ``base_ring`` -- a ring (default: `\QQ`). The base ring for - the toric variety. + - ``base_ring`` -- a ring (default: `\QQ`); the base ring for + the toric variety - OUTPUT: A :class:`toric variety + OUTPUT: a :class:`toric variety `. EXAMPLES:: @@ -1340,7 +1312,7 @@ def torus(self, n, names='z+', base_ring=QQ): except TypeError: raise TypeError('dimension of the torus must be an integer') if n < 0: - raise ValueError('dimension must be non-negative') + raise ValueError('dimension must be nonnegative') N = ToricLattice(n) fan = Fan([], lattice=N) return ToricVariety(fan, coordinate_names=names, base_field=base_ring) diff --git a/src/sage/schemes/toric/morphism.py b/src/sage/schemes/toric/morphism.py old mode 100644 new mode 100755 index c7e601ad3c3..c73282cabe0 --- a/src/sage/schemes/toric/morphism.py +++ b/src/sage/schemes/toric/morphism.py @@ -35,7 +35,7 @@ is a functor from the category of fans and fan morphisms to the category of toric varieties and toric morphisms. -.. note:: +.. NOTE:: Do not create the toric morphisms (or any morphism of schemes) directly from the ``SchemeMorphism...`` classes. Instead, use the @@ -398,14 +398,14 @@ class SchemeMorphism_point_toric_field(SchemeMorphism_point, Morphism): INPUT: - - ``X`` -- toric variety or subscheme of a toric variety. + - ``X`` -- toric variety or subscheme of a toric variety - - ``coordinates`` -- list of coordinates in the base field of ``X``. + - ``coordinates`` -- list of coordinates in the base field of ``X`` - ``check`` -- if ``True`` (default), the input will be checked for - correctness. + correctness - OUTPUT: A :class:`SchemeMorphism_point_toric_field`. + OUTPUT: a :class:`SchemeMorphism_point_toric_field` TESTS:: @@ -466,7 +466,7 @@ class SchemeMorphism_polynomial_toric_variety(SchemeMorphism_polynomial, Morphis Same as for :class:`~sage.schemes.toric.morphism.SchemeMorphism_polynomial`. - OUTPUT: A :class:`~sage.schemes.toric.morphism.SchemeMorphism_polynomial_toric_variety`. + OUTPUT: a :class:`~sage.schemes.toric.morphism.SchemeMorphism_polynomial_toric_variety` TESTS:: @@ -519,9 +519,9 @@ def as_fan_morphism(self): """ Express the morphism as a map defined by a fan morphism. - OUTPUT: A :class:`SchemeMorphism_polynomial_toric_variety`. + OUTPUT: a :class:`SchemeMorphism_polynomial_toric_variety` - This raises a :class:`TypeError` if the morphism cannot be written + This raises a :exc:`TypeError` if the morphism cannot be written in such a way. EXAMPLES:: @@ -547,11 +547,11 @@ class SchemeMorphism_orbit_closure_toric_variety(SchemeMorphism, Morphism): INPUT: - - ``parent`` -- the parent homset. + - ``parent`` -- the parent homset - - ``defining_cone`` -- the defining cone. + - ``defining_cone`` -- the defining cone - - ``ray_map`` -- a dictionary ``{ambient ray generator: orbit ray + - ``ray_map`` -- dictionary ``{ambient ray generator: orbit ray generator}``. Note that the image of the ambient ray generator is not necessarily primitive. @@ -605,7 +605,7 @@ def defining_cone(self): r""" Return the cone corresponding to the torus orbit. - OUTPUT: A cone of the fan of the ambient toric variety. + OUTPUT: a cone of the fan of the ambient toric variety EXAMPLES:: @@ -657,9 +657,7 @@ def _repr_defn(self): """ Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -679,11 +677,9 @@ def as_polynomial_map(self): """ Express the morphism via homogeneous polynomials. - OUTPUT: + OUTPUT: a :class:`SchemeMorphism_polynomial_toric_variety` - A :class:`SchemeMorphism_polynomial_toric_variety`. - - This raises a :class:`TypeError` if the morphism cannot be + This raises a :exc:`TypeError` if the morphism cannot be written in terms of homogeneous polynomials. The defining polynomials are not necessarily unique. There are @@ -737,7 +733,7 @@ def pullback_divisor(self, divisor): INPUT: - ``divisor`` -- a torus-invariant `\QQ`-Cartier divisor on the - codomain of the embedding map. + codomain of the embedding map OUTPUT: @@ -772,7 +768,7 @@ def pullback_divisor(self, divisor): # A morphism of toric varieties determined by a fan morphism class SchemeMorphism_fan_toric_variety(SchemeMorphism, Morphism): """ - Construct a morphism determined by a fan morphism + Construct a morphism determined by a fan morphism. .. WARNING:: @@ -784,14 +780,14 @@ class SchemeMorphism_fan_toric_variety(SchemeMorphism, Morphism): INPUT: - - ``parent`` -- Hom-set whose domain and codomain are toric varieties. + - ``parent`` -- Hom-set whose domain and codomain are toric varieties - - ``fan_morphism`` -- A morphism of fans whose domain and codomain + - ``fan_morphism`` -- a morphism of fans whose domain and codomain fans equal the fans of the domain and codomain in the ``parent`` Hom-set. - - ``check`` -- boolean (default:``True``). Whether to - check the input for consistency. + - ``check`` -- boolean (default: ``True``); whether to + check the input for consistency .. WARNING:: @@ -803,7 +799,7 @@ class SchemeMorphism_fan_toric_variety(SchemeMorphism, Morphism): :class:`SchemeMorphism_fan_toric_variety_dominant` for additional functionality for fibrations. - OUTPUT: A :class:`~sage.schemes.toric.morphism.SchemeMorphism_fan_toric_variety`. + OUTPUT: a :class:`~sage.schemes.toric.morphism.SchemeMorphism_fan_toric_variety` EXAMPLES:: @@ -872,7 +868,7 @@ def _richcmp_(self, right, op): - ``right`` -- another toric morphism - OUTPUT: A boolean. + OUTPUT: boolean Comparison is done first by domain, then by codomain, then by fan morphism. @@ -911,9 +907,9 @@ def _composition_(self, right, homset): INPUT: - - ``right`` -- a toric morphism defined by a fan morphism. + - ``right`` -- a toric morphism defined by a fan morphism - OUTPUT: A toric morphism. + OUTPUT: a toric morphism EXAMPLES:: @@ -938,9 +934,7 @@ def _repr_defn(self): """ Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1050,7 +1044,7 @@ def fan_morphism(self): """ Return the defining fan morphism. - OUTPUT: A :class:`~sage.geometry.fan_morphism.FanMorphism`. + OUTPUT: a :class:`~sage.geometry.fan_morphism.FanMorphism` EXAMPLES:: @@ -1070,9 +1064,9 @@ def as_polynomial_map(self): """ Express the morphism via homogeneous polynomials. - OUTPUT: A :class:`SchemeMorphism_polynomial_toric_variety`. + OUTPUT: a :class:`SchemeMorphism_polynomial_toric_variety` - This raises a :class:`TypeError` if the morphism cannot be written + This raises a :exc:`TypeError` if the morphism cannot be written in terms of homogeneous polynomials. EXAMPLES:: @@ -1117,9 +1111,7 @@ def is_bundle(self): See :meth:`~sage.geometry.fan_morphism.FanMorphism.is_bundle` for fan morphisms for details. - OUTPUT: - - - ``True`` if ``self`` is a bundle, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is a bundle, ``False`` otherwise EXAMPLES:: @@ -1138,9 +1130,7 @@ def is_fibration(self): :meth:`~sage.geometry.fan_morphism.FanMorphism.is_fibration` for fan morphisms for details. - OUTPUT: - - - ``True`` if ``self`` is a fibration, ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is a fibration, ``False`` otherwise EXAMPLES:: @@ -1159,9 +1149,7 @@ def is_injective(self): :meth:`~sage.geometry.fan_morphism.FanMorphism.is_injective` for fan morphisms for a description of the toric algorithm. - OUTPUT: - - Boolean. Whether ``self`` is injective. + OUTPUT: boolean; whether ``self`` is injective EXAMPLES:: @@ -1191,9 +1179,7 @@ def is_surjective(self): :meth:`~sage.geometry.fan_morphism.FanMorphism.is_surjective` for fan morphisms for a description of the toric algorithm. - OUTPUT: - - Boolean. Whether ``self`` is surjective. + OUTPUT: boolean; whether ``self`` is surjective EXAMPLES:: @@ -1223,9 +1209,7 @@ def is_birational(self): :meth:`~sage.geometry.fan_morphism.FanMorphism.is_birational` for fan morphisms for a description of the toric algorithm. - OUTPUT: - - Boolean. Whether ``self`` is birational. + OUTPUT: boolean; whether ``self`` is birational EXAMPLES:: @@ -1251,9 +1235,7 @@ def is_dominant(self): :meth:`~sage.geometry.fan_morphism.FanMorphism.is_dominant` for fan morphisms for a description of the toric algorithm. - OUTPUT: - - Boolean. Whether ``self`` is a dominant scheme morphism. + OUTPUT: boolean; whether ``self`` is a dominant scheme morphism EXAMPLES:: @@ -1279,11 +1261,9 @@ def pullback_divisor(self, divisor): INPUT: - ``divisor`` -- a torus-invariant `\QQ`-Cartier divisor on the - codomain of ``self``. - - OUTPUT: + codomain of ``self`` - The pull-back divisor `f^*(D)`. + OUTPUT: the pull-back divisor `f^*(D)` EXAMPLES:: @@ -1335,7 +1315,7 @@ class SchemeMorphism_fan_toric_variety_dominant(SchemeMorphism_fan_toric_variety morphism :meth:`must be dominant `. - OUTPUT: A :class:`~sage.schemes.toric.morphism.SchemeMorphism_fan_toric_variety_dominant`. + OUTPUT: a :class:`~sage.schemes.toric.morphism.SchemeMorphism_fan_toric_variety_dominant` EXAMPLES:: @@ -1405,7 +1385,6 @@ def fiber_generic(self): (2-d affine toric variety, 1) sage: _[0].fan().generating_cones() (0-d cone of Rational polyhedral fan in Sublattice ,) - """ from sage.schemes.toric.variety import ToricVariety fm = self.fan_morphism() @@ -1422,10 +1401,10 @@ def fiber_component(self, domain_cone, multiplicity=False): INPUT: - - ``domain_cone`` -- a cone of the domain fan of ``self``. + - ``domain_cone`` -- a cone of the domain fan of ``self`` - - ``multiplicity`` (default: ``False``) -- whether to return the number - of fiber components corresponding to ``domain_cone`` as well. + - ``multiplicity`` -- boolean (default: ``False``); whether to return + the number of fiber components corresponding to ``domain_cone`` as well OUTPUT: @@ -1492,7 +1471,7 @@ def fiber_dimension(self, codomain_cone): INPUT: - ``codomain_cone`` -- a cone `\sigma` of the codomain, - specifying a torus orbit `O(\sigma)`. + specifying a torus orbit `O(\sigma)` OUTPUT: @@ -1550,7 +1529,7 @@ def fiber_graph(self, codomain_cone): INPUT: - ``codomain_cone`` -- a cone `\sigma` of the codomain, - specifying a torus orbit `O(\sigma)`. + specifying a torus orbit `O(\sigma)` OUTPUT: @@ -1632,13 +1611,13 @@ class SchemeMorphism_fan_fiber_component_toric_variety(SchemeMorphism): INPUT: - - ``toric_morphism`` -- a toric morphism. The toric morphism whose - fiber component we are describing. + - ``toric_morphism`` -- a toric morphism; the toric morphism whose + fiber component we are describing - ``defining_cone`` -- a cone of the fan of the domain of - ``toric_morphism``. See + ``toric_morphism``; see :meth:`~SchemeMorphism_fan_toric_variety_dominant.fiber_component` for - details. + details EXAMPLES:: @@ -1708,9 +1687,7 @@ def _repr_defn(self): """ Return a string representation of the definition of ``self``. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1726,11 +1703,9 @@ def as_polynomial_map(self): """ Express the embedding morphism via homogeneous polynomials. - OUTPUT: - - A :class:`SchemeMorphism_polynomial_toric_variety`. + OUTPUT: a :class:`SchemeMorphism_polynomial_toric_variety` - This raises a :class:`ValueError` if the morphism cannot be + This raises a :exc:`ValueError` if the morphism cannot be written in terms of homogeneous polynomials. EXAMPLES:: @@ -1778,9 +1753,7 @@ def _make_fiber_component(self): """ Construct the fiber component as a toric variety. - OUTPUT: - - The fiber component as a toric variety. + OUTPUT: the fiber component as a toric variety EXAMPLES:: @@ -1854,9 +1827,7 @@ def defining_cone(self): r""" Return the cone corresponding to the fiber torus orbit. - OUTPUT: - - A cone of the fan of the total space of the toric fibration. + OUTPUT: a cone of the fan of the total space of the toric fibration EXAMPLES:: @@ -1879,9 +1850,7 @@ def base_cone(self): The fiber is constant over the base orbit closure `V(\sigma)`. - OUTPUT: - - A cone of the base of the toric fibration. + OUTPUT: a cone of the base of the toric fibration EXAMPLES:: @@ -1904,11 +1873,9 @@ def _image_ray_multiplicity(self, fiber_ray): INPUT: - A ray of the domain fan (the fiber component). - - OUTPUT: + - ``fiber_ray`` -- a ray of the domain fan (the fiber component) - A pair ``(codomain ray index, multiplicity)`` + OUTPUT: a pair ``(codomain ray index, multiplicity)`` EXAMPLES:: @@ -1955,7 +1922,7 @@ def pullback_divisor(self, divisor): INPUT: - ``divisor`` -- a torus-invariant `\QQ`-Cartier divisor on the - codomain of the embedding map. + codomain of the embedding map OUTPUT: diff --git a/src/sage/schemes/toric/points.py b/src/sage/schemes/toric/points.py old mode 100644 new mode 100755 index 799606a4d1f..ea2f09405a3 --- a/src/sage/schemes/toric/points.py +++ b/src/sage/schemes/toric/points.py @@ -52,10 +52,9 @@ def __init__(self, fan, ring): INPUT: - - ``fan`` -- fan of the toric variety. + - ``fan`` -- fan of the toric variety - - ``ring`` -- infinite base ring over which to enumerate - points. + - ``ring`` -- infinite base ring over which to enumerate points TESTS:: @@ -82,7 +81,7 @@ def __iter__(self): """ Iterate over the points. - OUTPUT: Iterator over points. + OUTPUT: iterator over points EXAMPLES:: @@ -115,9 +114,9 @@ def __init__(self, fan, ring): INPUT: - - ``fan`` -- fan of the toric variety. + - ``fan`` -- fan of the toric variety - - ``ring`` -- finite base ring over which to enumerate points. + - ``ring`` -- finite base ring over which to enumerate points EXAMPLES:: @@ -136,7 +135,7 @@ def rays(self): """ Return all rays (real and virtual). - OUTPUT: Tuple of rays of the fan. + OUTPUT: tuple of rays of the fan EXAMPLES:: @@ -170,15 +169,15 @@ def units(self): @cached_method def roots(self, n): """ - Return the n-th roots in the base field + Return the `n`-th roots in the base field. INPUT: - - ``n`` integer. + - ``n`` -- integer OUTPUT: - Tuple containing all n-th roots (not only the primitive + Tuple containing all `n`-th roots (not only the primitive ones). In particular, 1 is included. EXAMPLES:: @@ -196,7 +195,7 @@ def roots(self, n): def _Chow_group_free(self): r""" - Return the relations coming from the free part of the Chow group + Return the relations coming from the free part of the Chow group. OUTPUT: @@ -297,9 +296,7 @@ def orbit(self, point): """ Return the orbit of homogeneous coordinates under rescalings. - OUTPUT: - - The set of all homogeneous coordinates that are equivalent to ``point``. + OUTPUT: the set of all homogeneous coordinates that are equivalent to ``point`` EXAMPLES:: @@ -322,7 +319,7 @@ def orbit(self, point): def cone_iter(self): """ - Iterate over all cones of the fan + Iterate over all cones of the fan. OUTPUT: @@ -360,7 +357,7 @@ def coordinate_iter(self): This method does NOT identify homogeneous coordinates that are equivalent by a homogeneous rescaling. - OUTPUT: An iterator over the points. + OUTPUT: an iterator over the points EXAMPLES:: @@ -402,7 +399,7 @@ def __iter__(self): rescalings, and returns precisely one representative per orbit. - OUTPUT: An iterator over points. + OUTPUT: an iterator over points EXAMPLES:: @@ -435,7 +432,7 @@ def multiplicative_generator(self): """ Return the multiplicative generator of the finite field. - OUTPUT: A finite field element. + OUTPUT: a finite field element EXAMPLES:: @@ -457,9 +454,9 @@ def root_generator(self, n): INPUT: - - ``n`` integer. + - ``n`` -- integer - OUTPUT: A multiplicative generator for :meth:`roots`. + OUTPUT: a multiplicative generator for :meth:`roots` EXAMPLES:: @@ -490,7 +487,7 @@ def root_generator(self, n): def _Chow_group_free_generators(self): r""" - Return generators for :meth:`_Chow_group_free_generators` + Return generators for :meth:`_Chow_group_free_generators`. OUTPUT: @@ -519,7 +516,7 @@ def _Chow_group_free_generators(self): def _Chow_group_torsion_generators(self): r""" - Return generators for :meth:`Chow_group_torsion` + Return generators for :meth:`Chow_group_torsion`. OUTPUT: @@ -555,12 +552,12 @@ def _Chow_group_torsion_generators(self): def log(self, z): """ - Return the component-wise log of ``z`` + Return the component-wise log of ``z``. INPUT: - - ``z`` -- a list/tuple/iterable of non-zero finite field - elements. + - ``z`` -- list/tuple/iterable of nonzero finite field + elements OUTPUT: @@ -590,11 +587,11 @@ def log(self, z): def exp(self, powers): """ - Return the component-wise exp of ``z`` + Return the component-wise exp of ``z``. INPUT: - - ``powers`` -- a list/tuple/iterable of integers. + - ``powers`` -- list/tuple/iterable of integers OUTPUT: @@ -703,7 +700,7 @@ def __iter__(self): rescalings, and returns precisely one representative per orbit. - OUTPUT: Iterator over points. + OUTPUT: iterator over points EXAMPLES:: @@ -739,7 +736,7 @@ def cardinality(self): """ Return the cardinality of the point set. - OUTPUT: An integer. The number of points. + OUTPUT: integer; the number of points EXAMPLES:: @@ -764,10 +761,10 @@ def __init__(self, polynomials, ambient): INPUT: - - ``polynomials`` -- list/tuple/iterable of polynomials. The - defining polynomials. + - ``polynomials`` -- list/tuple/iterable of polynomials; the + defining polynomials - - ``ambient`` -- enumerator for ambient space points. + - ``ambient`` -- enumerator for ambient space points TESTS:: @@ -812,15 +809,15 @@ class FiniteFieldSubschemePointEnumerator(NaiveSubschemePointEnumerator): def inhomogeneous_equations(self, ring, nonzero_coordinates, cokernel): """ - Inhomogenize the defining polynomials + Inhomogenize the defining polynomials. INPUT: - ``ring`` -- the polynomial ring for inhomogeneous - coordinates. + coordinates - ``nonzero_coordinates`` -- list of integers. The indices of - the non-zero homogeneous coordinates in the patch. + the nonzero homogeneous coordinates in the patch - ``cokernel`` -- the logs of the nonzero coordinates of all distinct points as a cokernel. See @@ -888,7 +885,7 @@ def solutions_serial(self, inhomogeneous_equations, log_range): def solutions(self, inhomogeneous_equations, log_range): """ - Parallel version of :meth:`solutions_serial` + Parallel version of :meth:`solutions_serial`. INPUT/OUTPUT: @@ -925,22 +922,20 @@ def partial_solution(work_range): def homogeneous_coordinates(self, log_t, nonzero_coordinates, cokernel): """ - Convert the log of inhomogeneous coordinates back to homogeneous coordinates + Convert the log of inhomogeneous coordinates back to homogeneous coordinates. INPUT: - - ``log_t`` -- log of inhomogeneous coordinates of a point. + - ``log_t`` -- log of inhomogeneous coordinates of a point - ``nonzero_coordinates`` -- the nonzero homogeneous - coordinates in the patch. + coordinates in the patch - ``cokernel`` -- the logs of the nonzero coordinates of all distinct points as a cokernel. See :meth:`FiniteFieldPointEnumerator.cone_points_iter`. - OUTPUT: - - The same point, but as a tuple of homogeneous coordinates. + OUTPUT: the same point, but as a tuple of homogeneous coordinates EXAMPLES:: @@ -999,7 +994,7 @@ def cardinality(self): """ Return the cardinality of the point set. - OUTPUT: An integer. The number of points. + OUTPUT: integer; the number of points EXAMPLES:: diff --git a/src/sage/schemes/toric/sheaf/constructor.py b/src/sage/schemes/toric/sheaf/constructor.py old mode 100644 new mode 100755 index 3b23c4d9213..925451654ad --- a/src/sage/schemes/toric/sheaf/constructor.py +++ b/src/sage/schemes/toric/sheaf/constructor.py @@ -23,11 +23,9 @@ def TangentBundle(X): INPUT: - - ``X`` -- a toric variety. The base space of the bundle. + - ``X`` -- a toric variety; the base space of the bundle - OUTPUT: - - The tangent bundle as a Klyachko bundle. + OUTPUT: the tangent bundle as a Klyachko bundle EXAMPLES:: @@ -55,11 +53,9 @@ def CotangentBundle(X): INPUT: - - ``X`` -- a toric variety. The base space of the bundle. - - OUTPUT: + - ``X`` -- a toric variety; the base space of the bundle - The cotangent bundle as a Klyachko bundle. + OUTPUT: the cotangent bundle as a Klyachko bundle EXAMPLES:: @@ -77,13 +73,11 @@ def TrivialBundle(X, rank=1): INPUT: - - ``X`` -- a toric variety. The base space of the bundle. + - ``X`` -- a toric variety; the base space of the bundle - - ``rank`` -- the rank of the bundle. + - ``rank`` -- the rank of the bundle - OUTPUT: - - The trivial bundle as a Klyachko bundle. + OUTPUT: the trivial bundle as a Klyachko bundle EXAMPLES:: @@ -110,9 +104,9 @@ def LineBundle(X, D): INPUT: - - ``X`` -- a toric variety. The base space of the bundle. + - ``X`` -- a toric variety; the base space of the bundle - - ``D`` -- a toric divisor. + - ``D`` -- a toric divisor OUTPUT: @@ -162,9 +156,7 @@ def __repr__(self): """ Return a string representation. - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -179,12 +171,9 @@ def trivial_bundle(self, rank=1): INPUT: - - ``rank`` -- integer (optional; default: `1`). The rank of - the bundle. + - ``rank`` -- integer (default: `1`); the rank of the bundle - OUTPUT: - - The trivial bundle as a Klyachko bundle. + OUTPUT: the trivial bundle as a Klyachko bundle EXAMPLES:: @@ -202,7 +191,7 @@ def line_bundle(self, divisor): INPUT: - - ``divisor`` -- a toric divisor. + - ``divisor`` -- a toric divisor OUTPUT: @@ -223,9 +212,7 @@ def tangent_bundle(self): r""" Return the tangent bundle of the toric variety. - OUTPUT: - - The tangent bundle as a Klyachko bundle. + OUTPUT: the tangent bundle as a Klyachko bundle EXAMPLES:: @@ -238,9 +225,7 @@ def cotangent_bundle(self): r""" Return the cotangent bundle of the toric variety. - OUTPUT: - - The cotangent bundle as a Klyachko bundle. + OUTPUT: the cotangent bundle as a Klyachko bundle EXAMPLES:: @@ -301,9 +286,7 @@ def divisor(self, *args, **kwds): By abuse of notation, you can usually use the divisor `D` interchangeably with the line bundle `O(D)`. - OUTPUT: - - A toric divisor. + OUTPUT: a toric divisor EXAMPLES:: diff --git a/src/sage/schemes/toric/sheaf/klyachko.py b/src/sage/schemes/toric/sheaf/klyachko.py old mode 100644 new mode 100755 index b6c7147140c..94f465860b7 --- a/src/sage/schemes/toric/sheaf/klyachko.py +++ b/src/sage/schemes/toric/sheaf/klyachko.py @@ -57,13 +57,13 @@ def is_KlyachkoBundle(X): """ - Test whether ``X`` is a Klyachko bundle + Test whether ``X`` is a Klyachko bundle. INPUT: - - ``X`` -- anything. + - ``X`` -- anything - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -81,11 +81,11 @@ def is_KlyachkoBundle(X): def Bundle(toric_variety, multi_filtration, check=True): r""" - Construct a Klyacho bundle + Construct a Klyacho bundle. INPUT: - - ``toric_variety`` -- a toric variety. The base space of the bundle. + - ``toric_variety`` -- a toric variety; the base space of the bundle - ``multi_filtration`` -- a multi-filtered vectors space with multiple filtrations being indexed by the one-dimensional cones @@ -147,14 +147,14 @@ def __init__(self, toric_variety, multi_filtration, check=True): INPUT: - - ``toric_variety`` -- a toric variety. The base space of the bundle. + - ``toric_variety`` -- a toric variety; the base space of the bundle - ``multi_filtration`` -- a :func:`~sage.modules.multi_filtered_vector_space.MultiFilteredVectorSpace` with index set the rays of the fan. - - ``check`` -- boolean (default: ``True``). Whether to perform - consistency checks. + - ``check`` -- boolean (default: ``True``); whether to perform + consistency checks EXAMPLES:: @@ -187,7 +187,7 @@ def variety(self): r""" Return the base toric variety. - OUTPUT: A toric variety. + OUTPUT: a toric variety EXAMPLES:: @@ -203,7 +203,7 @@ def base_ring(self): r""" Return the base field. - OUTPUT: A field. + OUTPUT: a field EXAMPLES:: @@ -217,7 +217,7 @@ def fiber(self): r""" Return the generic fiber of the vector bundle. - OUTPUT: A vector space over :meth:`base_ring`. + OUTPUT: a vector space over :meth:`base_ring` EXAMPLES:: @@ -232,7 +232,7 @@ def rank(self): r""" Return the rank of the vector bundle. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -246,7 +246,7 @@ def _repr_(self): r""" Return a string representation. - OUTPUT: A string. + OUTPUT: string EXAMPLES:: @@ -262,7 +262,7 @@ def get_filtration(self, ray=None): INPUT: - - ``ray`` -- Integer, a `N`-lattice point, a one-dimensional + - ``ray`` -- integer; a `N`-lattice point, a one-dimensional cone, or ``None`` (default). Specifies a ray of the fan of the toric variety, either via its index or its generator. @@ -309,11 +309,11 @@ def get_degree(self, ray, i): r""" Return the vector subspace ``E^\alpha(i)``. - - ``ray`` -- Integer, a `N`-lattice point, a one-dimensional + - ``ray`` -- integer; a `N`-lattice point, a one-dimensional cone, or ``None`` (default). Specifies a ray of the fan of the toric variety, either via its index or its generator. - - ``i`` -- integer. The filtration degree. + - ``i`` -- integer; the filtration degree OUTPUT: @@ -335,9 +335,9 @@ def filtration_intersection(self, sigma, i): INPUT: - - ``sigma`` -- a cone of the fan of the base toric variety. + - ``sigma`` -- a cone of the fan of the base toric variety - - ``i`` -- integer. The filtration degree. + - ``i`` -- integer; the filtration degree OUTPUT: @@ -424,12 +424,12 @@ def E_intersection(self, sigma, m): INPUT: - - ``sigma`` -- a cone of the fan of the base toric variety. + - ``sigma`` -- a cone of the fan of the base toric variety - ``m`` -- tuple of integers or `M`-lattice point. A point in the dual lattice of the fan. Must be immutable. - OUTPUT: The subspace `E^\sigma(m)`. + OUTPUT: the subspace `E^\sigma(m)`. EXAMPLES:: @@ -463,12 +463,12 @@ def E_quotient(self, sigma, m): INPUT: - - ``sigma`` -- a cone of the fan of the base toric variety. + - ``sigma`` -- a cone of the fan of the base toric variety - ``m`` -- tuple of integers or `M`-lattice point. A point in the dual lattice of the fan. Must be immutable. - OUTPUT: The subspace `E_\sigma(m)`. + OUTPUT: the subspace `E_\sigma(m)`. EXAMPLES:: @@ -507,16 +507,14 @@ def E_quotient_projection(self, sigma, tau, m): INPUT: - - ``sigma`` -- a cone of the fan of the base toric variety. + - ``sigma`` -- a cone of the fan of the base toric variety - - ``tau`` -- a cone of the fan containing ``sigma``. + - ``tau`` -- a cone of the fan containing ``sigma`` - ``m`` -- tuple of integers or `M`-lattice point. A point in the dual lattice of the fan. Must be immutable. - OUTPUT: - - The restriction map + OUTPUT: the restriction map .. MATH:: @@ -567,7 +565,7 @@ def E_quotient_projection(self, sigma, tau, m): def cohomology_complex(self, m): r""" - Return the "cohomology complex" `C^*(m)` + Return the "cohomology complex" `C^*(m)`. See [Kly1990]_, equation 4.2. @@ -636,16 +634,16 @@ def cohomology(self, degree=None, weight=None, dim=False): INPUT: - - ``degree`` -- ``None`` (default) or an integer. The degree of - the cohomology group. + - ``degree`` -- ``None`` (default) or an integer; the degree of + the cohomology group - ``weight`` -- ``None`` (default) or a tuple of integers or a `M`-lattice point. A point in the dual lattice of the fan defining a torus character. The weight of the cohomology group. - - ``dim`` -- Boolean (default: ``False``). Whether to return - vector spaces or only their dimension. + - ``dim`` -- boolean (default: ``False``); whether to return + vector spaces or only their dimension OUTPUT: @@ -712,9 +710,9 @@ def __richcmp__(self, other, op): INPUT: - - ``other`` -- anything. + - ``other`` -- anything - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -747,9 +745,9 @@ def is_isomorphic(self, other): INPUT: - - ``other`` -- anything. + - ``other`` -- anything - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -771,9 +769,9 @@ def direct_sum(self, other): INPUT: - - ``other`` -- a Klyachko bundle over the same base. + - ``other`` -- a Klyachko bundle over the same base - OUTPUT: The direct sum as a new Klyachko bundle. + OUTPUT: the direct sum as a new Klyachko bundle EXAMPLES:: @@ -801,9 +799,9 @@ def tensor_product(self, other): INPUT: - - ``other`` -- a Klyachko bundle over the same base. + - ``other`` -- a Klyachko bundle over the same base - OUTPUT: The tensor product as a new Klyachko bundle. + OUTPUT: the tensor product as a new Klyachko bundle EXAMPLES:: @@ -827,7 +825,7 @@ def exterior_power(self, n): INPUT: - - ``n`` -- integer. + - ``n`` -- integer OUTPUT: @@ -855,9 +853,9 @@ def symmetric_power(self, n): INPUT: - - ``n`` -- integer. + - ``n`` -- integer - OUTPUT: The `n`-th symmetric power as a new Klyachko bundle. + OUTPUT: the `n`-th symmetric power as a new Klyachko bundle EXAMPLES:: @@ -876,7 +874,7 @@ def dual(self): """ Return the dual bundle. - OUTPUT: The dual bundle as a new Klyachko bundle. + OUTPUT: the dual bundle as a new Klyachko bundle EXAMPLES:: @@ -897,8 +895,8 @@ def random_deformation(self, epsilon=None): INPUT: - - ``epsilon`` -- an element of the base ring. Scales the - random deformation. + - ``epsilon`` -- an element of the base ring; scales the + random deformation OUTPUT: diff --git a/src/sage/schemes/toric/toric_subscheme.py b/src/sage/schemes/toric/toric_subscheme.py old mode 100644 new mode 100755 index 93f35acbc2e..33806674d28 --- a/src/sage/schemes/toric/toric_subscheme.py +++ b/src/sage/schemes/toric/toric_subscheme.py @@ -41,12 +41,12 @@ class AlgebraicScheme_subscheme_toric(AlgebraicScheme_subscheme): INPUT: - ``toric_variety`` -- ambient :class:`toric variety - `. + ` - ``polynomials`` -- single polynomial, list, or ideal of defining - polynomials in the coordinate ring of ``toric_variety``. + polynomials in the coordinate ring of ``toric_variety`` - OUTPUT: An :class:`algebraic subscheme of a toric variety + OUTPUT: an :class:`algebraic subscheme of a toric variety `. TESTS:: @@ -106,7 +106,7 @@ def _morphism(self, *args, **kwds): - same as for :class:`~sage.schemes.toric.morphism.SchemeMorphism_polynomial_toric_variety`. - OUTPUT: A :class:`~sage.schemes.toric.morphism.SchemeMorphism_polynomial_toric_variety`. + OUTPUT: a :class:`~sage.schemes.toric.morphism.SchemeMorphism_polynomial_toric_variety` TESTS:: @@ -146,7 +146,7 @@ def _point_homset(self, *args, **kwds): - same as for :class:`~sage.schemes.toric.homset.SchemeHomset_points_toric_field`. - OUTPUT: A :class:`~sage.schemes.toric.homset.SchemeHomset_points_subscheme_toric_field`. + OUTPUT: a :class:`~sage.schemes.toric.homset.SchemeHomset_points_subscheme_toric_field` TESTS:: @@ -166,7 +166,7 @@ def fan(self): """ Return the fan of the ambient space. - OUTPUT: A fan. + OUTPUT: a fan EXAMPLES:: @@ -184,8 +184,8 @@ def affine_patch(self, i): INPUT: - - ``i`` -- integer, index of a generating cone of the fan of the - ambient space of ``self``. + - ``i`` -- integer; index of a generating cone of the fan of the + ambient space of ``self`` OUTPUT: @@ -384,11 +384,9 @@ def _best_affine_patch(self, point): INPUT: - - ``point`` -- a point of the algebraic subscheme. + - ``point`` -- a point of the algebraic subscheme - OUTPUT: - - Integer. The index of the patch. See :meth:`affine_patch`. + OUTPUT: integer. The index of the patch. See :meth:`affine_patch` EXAMPLES:: @@ -416,7 +414,7 @@ def neighborhood(self, point): INPUT: - - ``point`` -- a point of the toric algebraic scheme. + - ``point`` -- a point of the toric algebraic scheme OUTPUT: @@ -496,7 +494,7 @@ def dimension(self): """ Return the dimension of ``self``. - OUTPUT: An integer. If ``self`` is empty, `-1` is returned. + OUTPUT: integer; if ``self`` is empty, `-1` is returned EXAMPLES:: @@ -525,12 +523,12 @@ def is_smooth(self, point=None): INPUT: - - ``point`` -- A point or ``None`` (default). The point to - test smoothness at. + - ``point`` -- a point or ``None`` (default); the point to + test smoothness at OUTPUT: - Boolean. If no point was specified, returns whether the + boolean; if no point was specified, returns whether the algebraic subscheme is smooth everywhere. Otherwise, smoothness at the specified point is tested. @@ -667,7 +665,6 @@ def is_nondegenerate(self): False sage: P2.subscheme([x]).is_nondegenerate() False - """ X = self.ambient_space() fan = X.fan() @@ -718,7 +715,6 @@ def is_schon(self): True sage: X.is_schon() False - """ return self.is_nondegenerate() @@ -737,10 +733,10 @@ class AlgebraicScheme_subscheme_affine_toric(AlgebraicScheme_subscheme_toric): INPUT: - ``toric_variety`` -- ambient :class:`affine toric variety - `; + ` - ``polynomials`` -- single polynomial, list, or ideal of defining - polynomials in the coordinate ring of ``toric_variety``. + polynomials in the coordinate ring of ``toric_variety`` OUTPUT: @@ -796,7 +792,7 @@ def dimension(self): """ Return the dimension of ``self``. - OUTPUT: An integer. + OUTPUT: integer EXAMPLES:: @@ -835,12 +831,12 @@ def is_smooth(self, point=None): INPUT: - - ``point`` -- A point or ``None`` (default). The point to - test smoothness at. + - ``point`` -- a point or ``None`` (default); the point to + test smoothness at OUTPUT: - Boolean. If no point was specified, returns whether the + boolean; if no point was specified, returns whether the algebraic subscheme is smooth everywhere. Otherwise, smoothness at the specified point is tested. diff --git a/src/sage/schemes/toric/variety.py b/src/sage/schemes/toric/variety.py old mode 100644 new mode 100755 index 5ab31a58905..2bc696b4183 --- a/src/sage/schemes/toric/variety.py +++ b/src/sage/schemes/toric/variety.py @@ -342,7 +342,7 @@ def is_ToricVariety(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: @@ -388,27 +388,27 @@ def ToricVariety(fan, INPUT: - ``fan`` -- :class:`rational polyhedral fan - `; + ` - ``coordinate_names`` -- names of variables for the coordinate ring, see :func:`normalize_names` for acceptable formats. If not given, indexed - variable names will be created automatically; + variable names will be created automatically. - ``names`` -- an alias of ``coordinate_names`` for internal use. You may specify either ``names`` or ``coordinate_names``, - but not both; + but not both. - ``coordinate_indices`` -- list of integers, indices for indexed variables. If not given, the index of each variable will coincide with - the index of the corresponding ray of the fan; + the index of the corresponding ray of the fan. - ``base_ring`` -- base ring of the toric variety (default: - `\QQ`). Must be a field. + `\QQ`); must be a field - - ``base_field`` -- alias for ``base_ring``. Takes precedence if - both are specified. + - ``base_field`` -- alias for ``base_ring``; takes precedence if + both are specified - OUTPUT: A :class:`toric variety `. + OUTPUT: a :class:`toric variety ` EXAMPLES: @@ -478,13 +478,13 @@ def AffineToricVariety(cone, *args, **kwds): INPUT: - ``cone`` -- :class:`strictly convex rational polyhedral cone - `. + ` This cone will be used to construct a :class:`rational polyhedral fan `, which will be passed to :func:`ToricVariety` with the rest of positional and keyword arguments. - OUTPUT: A :class:`toric variety `. + OUTPUT: a :class:`toric variety ` .. NOTE:: @@ -529,19 +529,19 @@ class ToricVariety_field(AmbientSpace): INPUT: - ``fan`` -- :class:`rational polyhedral fan - `; + ` - ``coordinate_names`` -- names of variables, see :func:`normalize_names` for acceptable formats. If ``None``, indexed variable names will be - created automatically; + created automatically. - ``coordinate_indices`` -- list of integers, indices for indexed variables. If ``None``, the index of each variable will coincide with - the index of the corresponding ray of the fan; + the index of the corresponding ray of the fan. - - ``base_field`` -- base field of the toric variety. + - ``base_field`` -- base field of the toric variety - OUTPUT: A :class:`toric variety `. + OUTPUT: a :class:`toric variety ` TESTS:: @@ -576,7 +576,7 @@ def __eq__(self, right): - ``right`` -- anything - OUTPUT: A boolean. + OUTPUT: boolean ``True`` if and only if ``right`` is of the same type as ``self``, their fans are the same, names of variables are the same and @@ -612,7 +612,7 @@ def __ne__(self, other): - ``other`` -- anything - OUTPUT: A boolean. + OUTPUT: boolean ``True`` if and only if ``other`` is of the same type as ``self``, their fans are the same, names of variables are the same and @@ -656,9 +656,7 @@ def _an_element_(self): This function is needed (in particular) for the test framework. - OUTPUT: - - - a point of ``self`` with coordinates [1 : 2: ... : n]. + OUTPUT: a point of ``self`` with coordinates [1 : 2: ... : n] TESTS:: @@ -674,12 +672,12 @@ def _check_satisfies_equations(self, coordinates): INPUT: - - ``coordinates`` -- list of elements of the base field of ``self``. + - ``coordinates`` -- list of elements of the base field of ``self`` OUTPUT: - ``True`` if ``coordinates`` do define a valid point of ``self``, - otherwise a :class:`TypeError` or :class:`ValueError` exception + otherwise a :exc:`TypeError` or :exc:`ValueError` exception is raised. TESTS:: @@ -768,9 +766,7 @@ def _latex_(self): r""" Return a LaTeX representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -786,12 +782,10 @@ def _latex_generic_point(self, coordinates=None): INPUT: - - ``coordinates`` -- list of coordinates of a point of ``self``. - If not given, names of coordinates of ``self`` will be used. - - OUTPUT: + - ``coordinates`` -- list of coordinates of a point of ``self``; + if not given, names of coordinates of ``self`` will be used - string. + OUTPUT: string EXAMPLES:: @@ -815,9 +809,7 @@ def _point(self, *args, **kwds): - same as for :class:`~sage.schemes.generic.morphism.SchemeMorphism_point_toric_field`. - OUTPUT: - - :class:`~sage.schemes.generic.morphism.SchemeMorphism_point_toric_field`. + OUTPUT: :class:`~sage.schemes.generic.morphism.SchemeMorphism_point_toric_field` TESTS:: @@ -836,9 +828,7 @@ def _homset(self, *args, **kwds): Same as :class:`sage.schemes.generic.homset.SchemeHomset_generic`. - OUTPUT: - - A :class:`sage.schemes.toric.homset.SchemeHomset_toric_variety`. + OUTPUT: a :class:`sage.schemes.toric.homset.SchemeHomset_toric_variety` EXAMPLES:: @@ -882,9 +872,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - - string. + OUTPUT: string TESTS:: @@ -906,12 +894,10 @@ def _repr_generic_point(self, coordinates=None): INPUT: - - ``coordinates`` -- list of coordinates of a point of ``self``. - If not given, names of coordinates of ``self`` will be used. - - OUTPUT: + - ``coordinates`` -- list of coordinates of a point of ``self``; + if not given, names of coordinates of ``self`` will be used - - string. + OUTPUT: string EXAMPLES:: @@ -935,13 +921,13 @@ def _validate(self, polynomials): INPUT: - ``polynomials`` -- list of polynomials in the coordinate ring of - ``self`` (this function does not perform any conversions). + ``self`` (this function does not perform any conversions) OUTPUT: - - ``polynomials`` (the input parameter without any modifications) if + - ``polynomials`` -- the input parameter without any modifications if ``polynomials`` do define valid polynomial functions on ``self``, - otherwise a :class:`ValueError` exception is raised. + otherwise a :exc:`ValueError` exception is raised. TESTS: @@ -970,7 +956,7 @@ def affine_patch(self, i): INPUT: - - ``i`` -- integer, index of a generating cone of the fan of ``self``. + - ``i`` -- integer; index of a generating cone of the fan of ``self`` OUTPUT: @@ -1035,9 +1021,9 @@ def change_ring(self, F): INPUT: - - ``F`` -- field. + - ``F`` -- field - OUTPUT: :class:`toric variety ` over ``F``. + OUTPUT: :class:`toric variety ` over ``F`` .. NOTE:: @@ -1084,7 +1070,7 @@ def coordinate_ring(self): For toric varieties this is the homogeneous coordinate ring (a.k.a. Cox's ring and total ring). - OUTPUT: A polynomial ring. + OUTPUT: a polynomial ring EXAMPLES:: @@ -1116,7 +1102,7 @@ def embedding_morphism(self): - :class:`scheme morphism ` if the default embedding morphism was defined for ``self``, - otherwise a :class:`ValueError` exception is raised. + otherwise a :exc:`ValueError` exception is raised. EXAMPLES:: @@ -1147,9 +1133,9 @@ def fan(self, dim=None, codim=None): INPUT: - - ``dim`` -- dimension of the requested cones; + - ``dim`` -- dimension of the requested cones - - ``codim`` -- codimension of the requested cones. + - ``codim`` -- codimension of the requested cones OUTPUT: @@ -1181,12 +1167,12 @@ def inject_coefficients(self, scope=None, verbose=True): INPUT: - ``scope`` -- namespace (default: global, not just the scope from - which this function was called); + which this function was called) - ``verbose`` -- if ``True`` (default), names of injected generators - will be printed. + will be printed - OUTPUT: None. + OUTPUT: none EXAMPLES:: @@ -1256,11 +1242,9 @@ def is_homogeneous(self, polynomial): INPUT: - ``polynomial`` -- polynomial in the coordinate ring of ``self`` or - its quotient. + its quotient - OUTPUT: - - - ``True`` if ``polynomial`` is homogeneous and ``False`` otherwise. + OUTPUT: ``True`` if ``polynomial`` is homogeneous and ``False`` otherwise EXAMPLES: @@ -1329,7 +1313,7 @@ def is_isomorphic(self, another): INPUT: - - ``another`` -- :class:`toric variety `. + - ``another`` -- :class:`toric variety ` OUTPUT: @@ -1366,7 +1350,7 @@ def is_affine(self): face lattice of a single cone. See also :func:`AffineToricVariety`. - OUTPUT: A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1381,9 +1365,7 @@ def is_complete(self): r""" Check if ``self`` is complete. - OUTPUT: - - - ``True`` if ``self`` is complete and ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is complete and ``False`` otherwise EXAMPLES:: @@ -1426,9 +1408,7 @@ def is_smooth(self): r""" Check if ``self`` is smooth. - OUTPUT: - - - ``True`` if ``self`` is smooth and ``False`` otherwise. + OUTPUT: ``True`` if ``self`` is smooth and ``False`` otherwise EXAMPLES:: @@ -1448,7 +1428,7 @@ def Kaehler_cone(self): r""" Return the closure of the Kähler cone of ``self``. - OUTPUT: :class:`cone `. + OUTPUT: :class:`cone ` .. NOTE:: @@ -1493,7 +1473,7 @@ def Mori_cone(self): r""" Return the Mori cone of ``self``. - OUTPUT: :class:`cone `. + OUTPUT: :class:`cone ` .. NOTE:: @@ -1540,7 +1520,7 @@ def plot(self, **options): - any options for toric plots (see :func:`toric_plotter.options `), none are mandatory. - OUTPUT: A plot. + OUTPUT: a plot .. NOTE:: @@ -1605,10 +1585,10 @@ def Chow_group(self, base_ring=ZZ): INPUT: - - ``base_ring`` -- either ``ZZ`` (default) or ``QQ``. The - coefficient ring of the Chow group. + - ``base_ring`` -- either ``ZZ`` (default) or ``QQ``; the + coefficient ring of the Chow group - OUTPUT: A :class:`sage.schemes.toric.chow_group.ChowGroup_class`. + OUTPUT: a :class:`sage.schemes.toric.chow_group.ChowGroup_class` EXAMPLES:: @@ -1627,17 +1607,17 @@ def cartesian_product(self, other, INPUT: - - ``other`` -- a :class:`toric variety `; + - ``other`` -- a :class:`toric variety ` - ``coordinate_names`` -- names of variables for the coordinate ring, see :func:`normalize_names` for acceptable formats. If not given, - indexed variable names will be created automatically; + indexed variable names will be created automatically. - ``coordinate_indices`` -- list of integers, indices for indexed variables. If not given, the index of each variable will coincide with the index of the corresponding ray of the fan. - OUTPUT: A :class:`toric variety `. + OUTPUT: a :class:`toric variety ` EXAMPLES:: @@ -1669,10 +1649,10 @@ def resolve(self, **kwds): - ``coordinate_names`` -- names for coordinates of the new variety. If not given, will be constructed from the coordinate names of ``self`` and necessary indexed ones. See :func:`normalize_names` for the - description of acceptable formats; + description of acceptable formats. - ``coordinate_indices`` -- coordinate indices which should be used - for indexed variables of the new variety; + for indexed variables of the new variety - all other arguments will be passed to :meth:`~sage.geometry.fan.RationalPolyhedralFan.subdivide` method of @@ -1680,7 +1660,7 @@ def resolve(self, **kwds): `, see its documentation for the available options. - OUTPUT: A :class:`toric variety `. + OUTPUT: a :class:`toric variety ` EXAMPLES: @@ -1727,7 +1707,7 @@ def resolve(self, **kwds): (z0, z1, z2, z3, z4, z5, z6, z7) sage: TV_res.gens() (z0, z1, z2, z3, z4, z5, z6, z7) - sage: TV_res = TV.resolve(coordinate_names="x+", + sage: TV_res = TV.resolve(coordinate_names='x+', ....: make_simplicial=True) sage: TV_res.gens() (x0, x1, x2, x3, x4, x5, x6, x7) @@ -1782,7 +1762,7 @@ def resolve_to_orbifold(self, **kwds): - this function accepts only keyword arguments. See :meth:`resolve` for documentation. - OUTPUT: A :class:`toric variety `. + OUTPUT: a :class:`toric variety ` EXAMPLES:: @@ -1811,9 +1791,9 @@ def subscheme(self, polynomials): INPUT: - ``polynomials`` -- list of polynomials in the coordinate ring of - ``self``. + ``self`` - OUTPUT: A :class:`subscheme of a toric variety + OUTPUT: a :class:`subscheme of a toric variety `. EXAMPLES: @@ -1876,7 +1856,7 @@ def Stanley_Reisner_ideal(self): def linear_equivalence_ideal(self): r""" - Return the ideal generated by linear relations + Return the ideal generated by linear relations. OUTPUT: @@ -1963,11 +1943,11 @@ def cohomology_basis(self, d=None): INPUT: - - ``d`` (optional) -- integer. + - ``d`` -- (optional) integer OUTPUT: - - Without the optional argument, a list whose d-th entry is a + - Without the optional argument, a list whose `d`-th entry is a basis for `H^{2d}(X,\QQ)` - If the argument is an integer ``d``, returns basis for @@ -2008,14 +1988,14 @@ def volume_class(self): the variety is non-compact this is dual to homology without any support condition. In particular, for non-compact varieties the volume form `\mathrm{dVol}=\wedge_i(dx_i \wedge - dy_i)` does not define a (non-zero) cohomology class. + dy_i)` does not define a (nonzero) cohomology class. OUTPUT: A :class:`CohomologyClass`. If it exists, it is the class of the (properly normalized) volume form, that is, it is the Poincaré dual of a single point. If it does not exist, a - :class:`ValueError` is raised. + :exc:`ValueError` is raised. EXAMPLES:: @@ -2079,7 +2059,7 @@ def integrate(self, cohomology_class): INPUT: - - ``cohomology_class`` -- A cohomology class given as a + - ``cohomology_class`` -- a cohomology class given as a polynomial in ``self.cohomology_ring()`` OUTPUT: @@ -2161,11 +2141,9 @@ def Chern_class(self, deg=None): INPUT: - - ``deg`` -- integer (optional). The degree of the Chern class. - - OUTPUT: + - ``deg`` -- integer (optional); the degree of the Chern class - - If the degree is specified, the ``deg``-th Chern class. + OUTPUT: if the degree is specified, the ``deg``-th Chern class - If no degree is specified, the total Chern class. @@ -2203,8 +2181,8 @@ def Chern_character(self, deg=None): INPUT: - - ``deg`` -- integer (optional). The degree of the Chern - character. + - ``deg`` -- integer (optional); the degree of the Chern + character OUTPUT: @@ -2241,7 +2219,7 @@ def Todd_class(self, deg=None): INPUT: - - ``deg`` -- integer (optional). The desired degree part. + - ``deg`` -- integer (optional); the desired degree part OUTPUT: @@ -2350,9 +2328,7 @@ def divisor(self, arg, base_ring=None, check=True, reduce=True): exception of defining a divisor with a single integer: this method considers it to be the index of a ray of the :meth:`fan` of ``self``. - OUTPUT: - - - A :class:`sage.schemes.toric.divisor.ToricDivisor_generic` + OUTPUT: a :class:`sage.schemes.toric.divisor.ToricDivisor_generic` EXAMPLES:: @@ -2403,7 +2379,7 @@ def divisor_group(self, base_ring=ZZ): INPUT: - ``base_ring`` -- the coefficient ring, usually ``ZZ`` - (default) or ``QQ``. + (default) or ``QQ`` OUTPUT: @@ -2440,7 +2416,7 @@ def toric_divisor_group(self, base_ring=ZZ): INPUT: - ``base_ring`` -- the coefficient ring, usually ``ZZ`` - (default) or ``QQ``. + (default) or ``QQ`` OUTPUT: @@ -2560,9 +2536,7 @@ def Spec(self, cone=None, names=None): formats. If not given, indexed variable names will be created automatically. - OUTPUT: - - The spectrum of the semigroup ring `\CC[\sigma^\vee \cap M]`. + OUTPUT: the spectrum of the semigroup ring `\CC[\sigma^\vee \cap M]` EXAMPLES:: @@ -2627,9 +2601,9 @@ def _orbit_closure_projection(self, cone, x): - ``cone`` -- a :class:`cone ` of the :meth:`fan` - of ``self``; + of ``self`` - - ``x`` -- a lattice point or a cone of the :meth:`fan` of ``self``. + - ``x`` -- a lattice point or a cone of the :meth:`fan` of ``self`` OUTPUT: @@ -2638,7 +2612,7 @@ def _orbit_closure_projection(self, cone, x): This quotient lattice is the ambient lattice for the fan of the orbit closure corresponding to ``cone``. - If ``x`` is a cone not in the star of ``cone``, an :class:`IndexError` + If ``x`` is a cone not in the star of ``cone``, an :exc:`IndexError` is raised. See :meth:`orbit_closure` for more details. @@ -2694,7 +2668,7 @@ def orbit_closure(self, cone): INPUT: - ``cone`` -- a :class:`cone - ` of the fan. + ` of the fan OUTPUT: @@ -2767,9 +2741,7 @@ def Demazure_roots(self): r""" Return the Demazure roots. - OUTPUT: - - The roots as points of the `M`-lattice. + OUTPUT: the roots as points of the `M`-lattice REFERENCES: @@ -2819,7 +2791,7 @@ def Demazure_roots(self): def Aut_dimension(self): r""" - Return the dimension of the automorphism group + Return the dimension of the automorphism group. There are three kinds of symmetries of toric varieties: @@ -2869,24 +2841,22 @@ def normalize_names(names=None, ngens=None, prefix=None, indices=None, names separated by commas or spaces) or a list of strings with each string specifying a name. If the last name ends with the plus sign, "+", this name will be used as ``prefix`` (even if ``prefix`` was - given explicitly); + given explicitly). - - ``ngens`` -- number of names to be returned; + - ``ngens`` -- number of names to be returned - - ``prefix`` -- prefix for the indexed names given as a string; + - ``prefix`` -- prefix for the indexed names given as a string - ``indices`` -- list of integers (default: ``range(ngens)``) used as indices for names with ``prefix``. If given, must be of length - ``ngens``; + ``ngens``. - ``return_prefix`` -- if ``True``, the last element of the returned list will contain the prefix determined from ``names`` or given as the parameter ``prefix``. This is useful if you may need more names in the future. - OUTPUT: - - - list of names given as strings. + OUTPUT: list of names given as strings These names are constructed in the following way: @@ -2941,18 +2911,18 @@ def normalize_names(names=None, ngens=None, prefix=None, indices=None, This is especially useful if you get ``names`` from a user but want to specify all default names:: - sage: normalize_names("x, y", 4, prefix="t") + sage: normalize_names("x, y", 4, prefix='t') ['x', 'y', 't2', 't3'] In this format, the user can easily override your choice for automatic names:: - sage: normalize_names("x y s+", 4, prefix="t") + sage: normalize_names("x y s+", 4, prefix='t') ['x', 'y', 's2', 's3'] Let's now use all parameters at once:: - sage: normalize_names("x, y, s+", 4, prefix="t", + sage: normalize_names("x, y, s+", 4, prefix='t', ....: indices=list(range(1,5)), return_prefix=True) ['x', 'y', 's3', 's4', 's'] @@ -2975,7 +2945,7 @@ def normalize_names(names=None, ngens=None, prefix=None, indices=None, A more subtle one:: - sage: normalize_names("x1", 4, prefix="x") + sage: normalize_names("x1", 4, prefix='x') Traceback (most recent call last): ... ValueError: variable name 'x1' appears more than once @@ -3115,9 +3085,7 @@ def _repr_(self): r""" Return a string representation of the cohomology ring. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3130,9 +3098,7 @@ def _latex_(self): r""" Return a latex representation of the cohomology ring. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3153,9 +3119,7 @@ def _element_constructor_(self, x): be converted into a polynomial in the homogeneous coordinates. - OUTPUT: - - The :class:`CohomologyClass` defined by ``x``. + OUTPUT: the :class:`CohomologyClass` defined by ``x`` EXAMPLES:: @@ -3275,7 +3239,7 @@ def gen(self, i): INPUT: - - ``i`` -- integer. + - ``i`` -- integer OUTPUT: @@ -3300,7 +3264,7 @@ def is_CohomologyClass(x): INPUT: - - ``x`` -- anything. + - ``x`` -- anything OUTPUT: @@ -3361,13 +3325,11 @@ def __init__(self, cohomology_ring, representative): INPUT: - - ``cohomology_ring`` -- :class:`CohomologyRing`. + - ``cohomology_ring`` -- :class:`CohomologyRing` - - ``representative`` -- a polynomial in the generators of the cohomology ring. + - ``representative`` -- a polynomial in the generators of the cohomology ring - OUTPUT: - - An instance of :class:`CohomologyClass`. + OUTPUT: an instance of :class:`CohomologyClass` EXAMPLES:: @@ -3385,9 +3347,7 @@ def _repr_(self): r""" Return a string representation of the cohomology class. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3400,9 +3360,7 @@ def _latex_(self): r""" Return a latex representation of the cohomology class. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -3444,9 +3402,7 @@ def part_of_degree(self, d): - An integer ``d`` - OUTPUT: - - - The degree-``2d`` part of the cohomology class. + OUTPUT: the degree-``2d`` part of the cohomology class EXAMPLES:: @@ -3483,7 +3439,7 @@ def exp(self): OUTPUT: The cohomology class `\exp(` ``self`` `)` if the constant part - vanishes, otherwise a :class:`ValueError` is raised. + vanishes, otherwise a :exc:`ValueError` is raised. EXAMPLES:: diff --git a/src/sage/schemes/toric/weierstrass.py b/src/sage/schemes/toric/weierstrass.py old mode 100644 new mode 100755 index 492f6b41126..8e0feb88c2c --- a/src/sage/schemes/toric/weierstrass.py +++ b/src/sage/schemes/toric/weierstrass.py @@ -160,7 +160,7 @@ def Discriminant(polynomial, variables=None): See :func:`WeierstrassForm` for how to specify the input polynomial(s) and variables. - OUTPUT: The discriminant of the elliptic curve. + OUTPUT: the discriminant of the elliptic curve EXAMPLES:: @@ -199,7 +199,7 @@ def j_invariant(polynomial, variables=None): * A nodal cubic: `j(-y^2 + x^2 + x^3) = \infty` * A cuspidal cubic `y^2=x^3` has undefined `j`-invariant. In this - case, a :class:`ValueError` is raised. + case, a :exc:`ValueError` is raised. EXAMPLES:: @@ -364,16 +364,16 @@ def WeierstrassForm(polynomial, variables=None, transformation=False): If two polynomials are passed, they must both be quadratics in `\mathbb{P}^3`. - - ``variables`` -- a list of variables of the parent polynomial + - ``variables`` -- list of variables of the parent polynomial ring or ``None`` (default). In the latter case, all variables are taken to be polynomial ring variables. If a subset of polynomial ring variables are given, the Weierstrass form is determined over the function field generated by the remaining variables. - - ``transformation`` -- boolean (default: ``False``). Whether to + - ``transformation`` -- boolean (default: ``False``); whether to return the new variables that bring ``polynomial`` into - Weierstrass form. + Weierstrass form OUTPUT: @@ -505,28 +505,28 @@ def WeierstrassForm(polynomial, variables=None, transformation=False): ###################################################################### def _check_homogeneity(polynomial, variables, weights, total_weight=None): """ - Raise :class:`ValueError` if the polynomial is not weighted + Raise :exc:`ValueError` if the polynomial is not weighted homogeneous. INPUT: - - ``polynomial`` -- the input polynomial. See - :func:`WeierstrassForm` for details. + - ``polynomial`` -- the input polynomial; see + :func:`WeierstrassForm` for details - - ``variables`` -- the variables. See :func:`WeierstrassForm` for - details. + - ``variables`` -- the variables; see :func:`WeierstrassForm` for + details - - ``weights`` -- list of integers, one per variable. the weights - of the variables. + - ``weights`` -- list of integers, one per variable; the weights + of the variables - - ``total_weight`` -- an integer or ``None`` (default). If an + - ``total_weight`` -- integer or ``None`` (default); if an integer is passed, it is also checked that the weighted total - degree of polynomial is this value. + degree of polynomial is this value OUTPUT: This function returns nothing. If the polynomial is not weighted - homogeneous, a :class:`ValueError` is raised. + homogeneous, a :exc:`ValueError` is raised. EXAMPLES:: @@ -565,9 +565,9 @@ def _extract_coefficients(polynomial, monomials, variables): - ``polynomial`` -- the input polynomial - - ``monomials`` -- a list of monomials in the polynomial ring + - ``monomials`` -- list of monomials in the polynomial ring - - ``variables`` -- a list of variables in the polynomial ring + - ``variables`` -- list of variables in the polynomial ring OUTPUT: @@ -614,16 +614,16 @@ def _check_polynomial_P2(cubic, variables): INPUT: - - ``cubic`` -- the input polynomial. See - :func:`WeierstrassForm` for details. + - ``cubic`` -- the input polynomial; see + :func:`WeierstrassForm` for details - - ``variables`` -- the variables or ``None``. See - :func:`WeierstrassForm` for details. + - ``variables`` -- the variables or ``None``; see + :func:`WeierstrassForm` for details OUTPUT: This functions returns ``variables``, potentially guessed from the - polynomial ring. A :class:`ValueError` is raised if the polynomial is + polynomial ring. A :exc:`ValueError` is raised if the polynomial is not homogeneous. EXAMPLES:: @@ -771,16 +771,16 @@ def _check_polynomial_P1xP1(biquadric, variables): INPUT: - - ``biquadric`` -- the input polynomial. See - :func:`WeierstrassForm` for details. + - ``biquadric`` -- the input polynomial; see + :func:`WeierstrassForm` for details - - ``variables`` -- the variables or ``None``. See - :func:`WeierstrassForm` for details. + - ``variables`` -- the variables or ``None``; see + :func:`WeierstrassForm` for details OUTPUT: This functions returns ``variables``, potentially guessed from the - polynomial ring. A :class:`ValueError` is raised if the polynomial is + polynomial ring. A :exc:`ValueError` is raised if the polynomial is not homogeneous. EXAMPLES:: @@ -820,14 +820,12 @@ def _partial_discriminant(quadric, y0, y1=None): INPUT: - - ``quadric`` -- a biquadric. + - ``quadric`` -- a biquadric - - ``y_0``, ``y_1`` -- the variables of the quadric. The ``y_1`` - variable can be omitted if the quadric is inhomogeneous. + - ``y_0``, ``y_1`` -- the variables of the quadric; the ``y_1`` + variable can be omitted if the quadric is inhomogeneous - OUTPUT: - - A plane quartic in ``x0``, ``x1``. + OUTPUT: a plane quartic in ``x0``, ``x1`` EXAMPLES:: @@ -862,7 +860,7 @@ def _partial_discriminant(quadric, y0, y1=None): ###################################################################### def WeierstrassForm_P1xP1(biquadric, variables=None): r""" - Bring a biquadric into Weierstrass form + Bring a biquadric into Weierstrass form. Input/output is the same as :func:`WeierstrassForm`, except that the input polynomial must be a standard biquadric in `\mathbb{P}^2`, @@ -955,16 +953,16 @@ def _check_polynomial_P2_112(polynomial, variables): INPUT: - - ``polynomial`` -- the input polynomial. See - :func:`WeierstrassForm` for details. + - ``polynomial`` -- the input polynomial; see + :func:`WeierstrassForm` for details - - ``variables`` -- the variables or ``None``. See - :func:`WeierstrassForm` for details. + - ``variables`` -- the variables or ``None``; see + :func:`WeierstrassForm` for details OUTPUT: This functions returns ``variables``, potentially guessed from the - polynomial ring. A :class:`ValueError` is raised if the polynomial is + polynomial ring. A :exc:`ValueError` is raised if the polynomial is not homogeneous. EXAMPLES:: diff --git a/src/sage/schemes/toric/weierstrass_covering.py b/src/sage/schemes/toric/weierstrass_covering.py old mode 100644 new mode 100755 index 128c30d33a8..87d414d3464 --- a/src/sage/schemes/toric/weierstrass_covering.py +++ b/src/sage/schemes/toric/weierstrass_covering.py @@ -134,7 +134,7 @@ def WeierstrassMap(polynomial, variables=None): hypersurface in `\mathbb{P}^2[1,1,2]`. The equation need not be in any standard form, only its Newton polyhedron is used. - - ``variables`` -- a list of variables of the parent polynomial + - ``variables`` -- list of variables of the parent polynomial ring or ``None`` (default). In the latter case, all variables are taken to be polynomial ring variables. If a subset of polynomial ring variables are given, the Weierstrass form is @@ -258,7 +258,7 @@ def homogenize(inhomog, degree): X_dict = {homogenize(e, 2): v for e, v in X.dict().items()} Y_dict = {homogenize(e, 3): v for e, v in Y.dict().items()} Z_dict = {homogenize(e, 1): v for e, v in Z.dict().items()} - # shift to non-negative exponents if necessary + # shift to nonnegative exponents if necessary min_deg = [0] * R.ngens() for var in variables: i = R.gens().index(var) diff --git a/src/sage/schemes/toric/weierstrass_higher.py b/src/sage/schemes/toric/weierstrass_higher.py old mode 100644 new mode 100755 index 48d683d53a4..1e88b1dd952 --- a/src/sage/schemes/toric/weierstrass_higher.py +++ b/src/sage/schemes/toric/weierstrass_higher.py @@ -38,14 +38,12 @@ ###################################################################### def WeierstrassForm2(polynomial, variables=None, transformation=False): r""" - Helper function for :func:`~sage.schemes.toric.weierstrass.WeierstrassForm` + Helper function for :func:`~sage.schemes.toric.weierstrass.WeierstrassForm`. Currently, only the case of the complete intersection of two quadratic equations in `\mathbb{P}^3` is supported. - INPUT / OUTPUT: - - See :func:`~sage.schemes.toric.weierstrass.WeierstrassForm` + INPUT / OUTPUT: see :func:`~sage.schemes.toric.weierstrass.WeierstrassForm` TESTS:: @@ -74,14 +72,14 @@ def _check_polynomials_P3(quadratic1, quadratic2, variables): INPUT: - ``quadratic1``, ``quadratic2`` -- two quadratic polynomials in 4 - homogeneous or 3 inhomogeneous variables. + homogeneous or 3 inhomogeneous variables - - ``variables`` -- the variables or ``None`` (default). + - ``variables`` -- the variables or ``None`` (default) OUTPUT: This function returns ``variables``, potentially guessed from the - polynomial ring. A :class:`ValueError` is raised if the polynomial is + polynomial ring. A :exc:`ValueError` is raised if the polynomial is not homogeneous. EXAMPLES:: @@ -124,7 +122,7 @@ def _check_polynomials_P3(quadratic1, quadratic2, variables): ###################################################################### def _biquadratic_syzygy_quartic(quadratic1, quadratic2, variables=None): r""" - Helper function for the Weierstrass form of a biquadratic in `\mathbb{P}^3` + Helper function for the Weierstrass form of a biquadratic in `\mathbb{P}^3`. The invariants and covariants of a quaternary biquadratic satisfy the relation @@ -139,11 +137,9 @@ def _biquadratic_syzygy_quartic(quadratic1, quadratic2, variables=None): INPUT: - See :func:`WeierstrassForm_P3` - - OUTPUT: + See :func:`WeierstrassForm_P3`. - A triple consisting of + OUTPUT: a triple consisting of - The quaternary biquadratic as an algebraic form :class:`~sage.rings.invariant_theory.TwoQuaternaryQuadratics` diff --git a/src/sage/sets/cartesian_product.py b/src/sage/sets/cartesian_product.py index 47b94b6d222..e29a4fb1a2f 100644 --- a/src/sage/sets/cartesian_product.py +++ b/src/sage/sets/cartesian_product.py @@ -55,9 +55,9 @@ def __init__(self, sets, category, flatten=False): r""" INPUT: - - ``sets`` -- a tuple of parents - - ``category`` -- a subcategory of ``Sets().CartesianProducts()`` - - ``flatten`` -- a boolean (default: ``False``) + - ``sets`` -- tuple of parents + - ``category`` -- a subcategory of ``Sets().CartesianProducts()`` + - ``flatten`` -- boolean (default: ``False``) ``flatten`` is current ignored, and reserved for future use. @@ -82,11 +82,11 @@ def __init__(self, sets, category, flatten=False): def _element_constructor_(self, x): r""" - Construct an element of a Cartesian product from a list or iterable + Construct an element of a Cartesian product from a list or iterable. INPUT: - - ``x`` -- a list (or iterable) + - ``x`` -- list (or iterable) Each component of `x` is converted to the corresponding Cartesian factor. @@ -211,7 +211,7 @@ def cartesian_projection(self, i): EXAMPLES:: sage: C = Sets().CartesianProducts().example(); C - The Cartesian product of (Set of prime numbers (basic implementation), An example of an infinite enumerated set: the non negative integers, An example of a finite enumerated set: {1,2,3}) + The Cartesian product of (Set of prime numbers (basic implementation), An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) sage: x = C.an_element(); x (47, 42, 1) sage: pi = C.cartesian_projection(1) @@ -316,7 +316,7 @@ def cartesian_projection(self, i): EXAMPLES:: sage: C = Sets().CartesianProducts().example(); C - The Cartesian product of (Set of prime numbers (basic implementation), An example of an infinite enumerated set: the non negative integers, An example of a finite enumerated set: {1,2,3}) + The Cartesian product of (Set of prime numbers (basic implementation), An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) sage: x = C.an_element(); x (47, 42, 1) sage: x.cartesian_projection(1) @@ -335,7 +335,7 @@ def __iter__(self): sage: C = Sets().CartesianProducts().example(); C The Cartesian product of (Set of prime numbers (basic implementation), - An example of an infinite enumerated set: the non negative integers, + An example of an infinite enumerated set: the nonnegative integers, An example of a finite enumerated set: {1,2,3}) sage: c = C.an_element(); c (47, 42, 1) diff --git a/src/sage/sets/condition_set.py b/src/sage/sets/condition_set.py index e29f0124224..a0d618ebdde 100644 --- a/src/sage/sets/condition_set.py +++ b/src/sage/sets/condition_set.py @@ -26,11 +26,11 @@ class ConditionSet(Set_generic, Set_base, Set_boolean_operators, Set_add_sub_operators, UniqueRepresentation): r""" - Set of elements of a universe that satisfy given predicates + Set of elements of a universe that satisfy given predicates. INPUT: - - ``universe`` -- a set + - ``universe`` -- set - ``*predicates`` -- callables @@ -70,7 +70,7 @@ class ConditionSet(Set_generic, Set_base, Set_boolean_operators, Set_add_sub_ope sage: # needs sage.geometry.polyhedron sage: P = polytopes.cube(); P A 3-dimensional polyhedron in ZZ^3 defined as the convex hull of 8 vertices - sage: P.rename("P") + sage: P.rename('P') sage: P_inter_B = ConditionSet(P, lambda x: x.norm() < 1.2); P_inter_B { x ∈ P : at 0x...>(x) } sage: vector([1, 0, 0]) in P_inter_B @@ -217,7 +217,6 @@ def _first_ngens(self, n): sage: preparse("Q3. = ConditionSet(QQ^3)") "Q3 = ConditionSet(QQ**Integer(3), names=('x', 'y', 'z',)); (x, y, z,) = Q3._first_ngens(3)" - """ return self.arguments() @@ -321,7 +320,6 @@ def _element_constructor_(self, *args, **kwds): Traceback (most recent call last): ... ValueError: 3 does not satisfy the condition - """ try: universe_element_constructor = self._universe._element_constructor_ @@ -375,7 +373,7 @@ def _an_element_(self): r""" Return an element of ``self``. - This may raise :class:`NotImplementedError`. + This may raise :exc:`NotImplementedError`. TESTS:: @@ -520,7 +518,6 @@ def __iter__(self): { x ∈ Integer Ring : (x) } sage: list(Odds.iterator_range(stop=6)) [1, -1, 3, -3, 5, -5] - """ for x in self._universe: if x in self: diff --git a/src/sage/sets/disjoint_union_enumerated_sets.py b/src/sage/sets/disjoint_union_enumerated_sets.py index 030834993fa..97243f90d11 100644 --- a/src/sage/sets/disjoint_union_enumerated_sets.py +++ b/src/sage/sets/disjoint_union_enumerated_sets.py @@ -32,9 +32,9 @@ class DisjointUnionEnumeratedSets(UniqueRepresentation, Parent): INPUT: - - ``family`` -- a list (or iterable or family) of enumerated sets - - ``keepkey`` -- a boolean - - ``facade`` -- a boolean + - ``family`` -- list (or iterable or family) of enumerated sets + - ``keepkey`` -- boolean + - ``facade`` -- boolean This models the enumerated set obtained by concatenating together the specified ordered sets. The latter are supposed to be pairwise @@ -227,7 +227,7 @@ class DisjointUnionEnumeratedSets(UniqueRepresentation, Parent): We skip ``_test_an_element`` because the coercion framework does not currently allow a tuple to be returned for facade parents:: - sage: TestSuite(Ukeep).run(skip="_test_an_element") # needs sage.combinat + sage: TestSuite(Ukeep).run(skip='_test_an_element') # needs sage.combinat The following three lines are required for the pickling tests, because the classes ``MyUnion`` and ``UnionOfSpecialSets`` have @@ -239,7 +239,6 @@ class DisjointUnionEnumeratedSets(UniqueRepresentation, Parent): sage: TestSuite(pp).run() sage: TestSuite(psp).run() - """ @staticmethod @@ -437,7 +436,7 @@ def an_element(self): @cached_method def cardinality(self): """ - Returns the cardinality of this disjoint union. + Return the cardinality of this disjoint union. EXAMPLES: @@ -465,7 +464,6 @@ def cardinality(self): ....: Family(NonNegativeIntegers(), lambda x: [])) sage: U.cardinality() # Should be 0! +Infinity - """ if self._family.cardinality() == Infinity: return Infinity diff --git a/src/sage/sets/family.pyx b/src/sage/sets/family.pyx index 0810b07f17a..f87768f3989 100644 --- a/src/sage/sets/family.pyx +++ b/src/sage/sets/family.pyx @@ -421,13 +421,13 @@ def Family(indices, function=None, hidden_keys=[], hidden_function=None, lazy=Fa cdef class AbstractFamily(Parent): """ - The abstract class for family + The abstract class for family. Any family belongs to a class which inherits from :class:`AbstractFamily`. """ def hidden_keys(self): """ - Returns the hidden keys of the family, if any. + Return the hidden keys of the family, if any. EXAMPLES:: @@ -500,9 +500,7 @@ cdef class AbstractFamily(Parent): def map(self, f, name=None): r""" Return the family `( f(\mathtt{self}[i]) )_{i \in I}`, where - `I` is the index set of self. - - .. TODO:: good name? + `I` is the index set of ``self``. EXAMPLES:: @@ -519,9 +517,8 @@ cdef class AbstractFamily(Parent): @cached_method def inverse_family(self): """ - Returns the inverse family, with keys and values - exchanged. This presumes that there are no duplicate values in - ``self``. + Return the inverse family, with keys and values exchanged. This + presumes that there are no duplicate values in ``self``. This default implementation is not lazy and therefore will only work with not too big finite families. It is also cached @@ -575,7 +572,6 @@ cdef class FiniteFamily(AbstractFamily): sage: f = FiniteFamily({"a": "aa", "b": "bb", "c" : "cc" }, keys = ["c", "a", "b"]) sage: list(f) ['cc', 'aa', 'bb'] - """ def __init__(self, dictionary, keys=None): @@ -649,7 +645,7 @@ cdef class FiniteFamily(AbstractFamily): def keys(self): """ - Returns the index set of this family + Return the index set of this family. EXAMPLES:: @@ -662,7 +658,7 @@ cdef class FiniteFamily(AbstractFamily): def values(self): """ - Returns the elements of this family + Return the elements of this family. EXAMPLES:: @@ -677,7 +673,7 @@ cdef class FiniteFamily(AbstractFamily): def has_key(self, k): """ - Returns whether ``k`` is a key of ``self`` + Return whether ``k`` is a key of ``self``. EXAMPLES:: @@ -753,7 +749,7 @@ cdef class FiniteFamily(AbstractFamily): def __len__(self): """ - Returns the number of elements in self. + Return the number of elements in ``self``. EXAMPLES:: @@ -766,7 +762,7 @@ cdef class FiniteFamily(AbstractFamily): def cardinality(self): """ - Returns the number of elements in self. + Return the number of elements in ``self``. EXAMPLES:: @@ -884,7 +880,7 @@ class FiniteFamilyWithHiddenKeys(FiniteFamily): def hidden_keys(self): """ - Returns self's hidden keys. + Return ``self``'s hidden keys. EXAMPLES:: @@ -1090,7 +1086,7 @@ class LazyFamily(AbstractFamily): def keys(self): """ - Returns self's keys. + Return ``self``'s keys. EXAMPLES:: @@ -1103,7 +1099,7 @@ class LazyFamily(AbstractFamily): def cardinality(self): """ - Return the number of elements in self. + Return the number of elements in ``self``. EXAMPLES:: @@ -1306,7 +1302,7 @@ class TrivialFamily(AbstractFamily): def keys(self): """ - Returns self's keys. + Return ``self``'s keys. EXAMPLES:: @@ -1319,7 +1315,7 @@ class TrivialFamily(AbstractFamily): def cardinality(self): """ - Return the number of elements in self. + Return the number of elements in ``self``. EXAMPLES:: @@ -1487,7 +1483,7 @@ class EnumeratedFamily(LazyFamily): def cardinality(self): """ - Return the number of elements in self. + Return the number of elements in ``self``. EXAMPLES:: diff --git a/src/sage/sets/finite_enumerated_set.py b/src/sage/sets/finite_enumerated_set.py index 6f205e5b70e..ce959031800 100644 --- a/src/sage/sets/finite_enumerated_set.py +++ b/src/sage/sets/finite_enumerated_set.py @@ -36,7 +36,6 @@ class FiniteEnumeratedSet(UniqueRepresentation, Parent): ``EnumeratedSets`` and has unique representation. The list of the elements is expanded in memory. - EXAMPLES:: sage: S = FiniteEnumeratedSet([1, 2, 3]) @@ -163,7 +162,7 @@ def __contains__(self, x): def __iter__(self): r""" - Iterator over the element of self. + Iterator over the element of ``self``. EXAMPLES:: @@ -198,8 +197,8 @@ def an_element(self): def first(self): r""" - Return the first element of the enumeration or raise an EmptySetError if - the set is empty. + Return the first element of the enumeration or raise an + :exc:`EmptySetError` if the set is empty. EXAMPLES:: @@ -213,8 +212,8 @@ def first(self): def last(self): r""" - Returns the last element of the iteration or raise an EmptySetError if - the set is empty. + Return the last element of the iteration or raise an + :exc:`EmptySetError` if the set is empty. EXAMPLES:: @@ -259,7 +258,7 @@ def cardinality(self): def rank(self, x): """ - Returns the index of ``x`` in this finite enumerated set. + Return the index of ``x`` in this finite enumerated set. EXAMPLES:: @@ -381,7 +380,7 @@ def _element_constructor_(self, el): - ``el`` -- an element of ``self`` - If ``el`` is not an element of ``self``, a :class:`ValueError` + If ``el`` is not an element of ``self``, a :exc:`ValueError` is raised. TESTS:: diff --git a/src/sage/sets/finite_set_map_cy.pyx b/src/sage/sets/finite_set_map_cy.pyx index a06dc0a2bd9..335e4cfb5e7 100644 --- a/src/sage/sets/finite_set_map_cy.pyx +++ b/src/sage/sets/finite_set_map_cy.pyx @@ -60,11 +60,11 @@ from sage.sets.set import Set_object_enumerated cpdef fibers(f, domain): r""" - Returns the fibers of the function ``f`` on the finite set ``domain`` + Return the fibers of the function ``f`` on the finite set ``domain``. INPUT: - - ``f`` -- a function or callable + - ``f`` -- a function or callable - ``domain`` -- a finite iterable OUTPUT: @@ -98,7 +98,7 @@ cpdef fibers(f, domain): def fibers_args(f, domain, *args, **opts): r""" - Returns the fibers of the function ``f`` on the finite set ``domain`` + Return the fibers of the function ``f`` on the finite set ``domain``. It is the same as :func:`fibers` except that one can pass extra argument for ``f`` (with a small overhead) @@ -118,23 +118,21 @@ cdef class FiniteSetMap_MN(ClonableIntArray): We assume that the parent given as argument is such that: - - ``m`` is stored in ``self.parent()._m`` - - ``n`` is stored in ``self.parent()._n`` + - ``m`` -- stored in ``self.parent()._m`` + - ``n`` -- stored in ``self.parent()._n`` - the domain is in ``self.parent().domain()`` - the codomain is in ``self.parent().codomain()`` """ def __call__(self, int i): """ - Returns the image of ``i`` under the map ``self`` + Return the image of ``i`` under the map ``self``. INPUT: - - ``i`` -- an int + - ``i`` -- integer - OUTPUT: - - an int + OUTPUT: integer EXAMPLES:: @@ -147,7 +145,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): # Needed by generic power which refuses to compute 0^0 def __bool__(self): """ - Returns whether ``self`` is non zero; this is always ``True``. + Return whether ``self`` is nonzero; this is always ``True``. EXAMPLES:: @@ -159,7 +157,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef domain(self): """ - Returns the domain of ``self`` + Return the domain of ``self``. EXAMPLES:: @@ -170,7 +168,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef codomain(self): """ - Returns the codomain of ``self`` + Return the codomain of ``self``. EXAMPLES:: @@ -181,7 +179,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef _setimage(self, int i, int j): """ - Set the image of ``i`` as ``j`` in ``self`` + Set the image of ``i`` as ``j`` in ``self``. This is a fast internal version where ``i`` and ``j`` are both int's. @@ -189,9 +187,9 @@ cdef class FiniteSetMap_MN(ClonableIntArray): INPUT: - - ``i``, ``j`` -- two ``int``'s + - ``i``, ``j`` -- integers - OUTPUT: ``None`` + OUTPUT: none EXAMPLES:: @@ -223,13 +221,13 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef _getimage(self, int i): """ - Returns the image of ``i`` by ``self`` + Return the image of ``i`` by ``self``. - This is a fast internal version where ``i`` is an int. + This is a fast internal version where ``i`` is integer. INPUT: - - ``i`` -- an ``int`` + - ``i`` -- integer EXAMPLES:: @@ -241,7 +239,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef setimage(self, i, j): """ - Set the image of ``i`` as ``j`` in ``self`` + Set the image of ``i`` as ``j`` in ``self``. .. warning:: ``self`` must be mutable; otherwise an exception is raised. @@ -249,7 +247,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): - ``i``, ``j`` -- two ``object``'s - OUTPUT: ``None`` + OUTPUT: none .. NOTE:: if you need speed, please use instead :meth:`_setimage` @@ -270,11 +268,11 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef getimage(self, i): """ - Returns the image of ``i`` by ``self`` + Return the image of ``i`` by ``self``. INPUT: - - ``i`` -- any object. + - ``i`` -- any object .. NOTE:: if you need speed, please use instead :meth:`_getimage` @@ -288,7 +286,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef image_set(self): """ - Returns the image set of ``self`` + Return the image set of ``self``. EXAMPLES:: @@ -301,7 +299,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef fibers(self): """ - Returns the fibers of ``self`` + Return the fibers of ``self``. OUTPUT: @@ -320,7 +318,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef items(self): """ - The items of ``self`` + The items of ``self``. Return the list of the ordered pairs ``(x, self(x))`` @@ -333,7 +331,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef check(self): """ - Performs checks on ``self`` + Perform checks on ``self``. Check that ``self`` is a proper function and then calls ``parent.check_element(self)`` where ``parent`` is the parent @@ -385,7 +383,7 @@ cdef class FiniteSetMap_MN(ClonableIntArray): cpdef FiniteSetMap_Set FiniteSetMap_Set_from_list(t, parent, lst): """ - Creates a ``FiniteSetMap`` from a list + Create a ``FiniteSetMap`` from a list. .. warning:: no check is performed ! @@ -408,7 +406,7 @@ cpdef FiniteSetMap_Set FiniteSetMap_Set_from_list(t, parent, lst): cpdef FiniteSetMap_Set FiniteSetMap_Set_from_dict(t, parent, d): """ - Creates a ``FiniteSetMap`` from a dictionary + Create a ``FiniteSetMap`` from a dictionary. .. warning:: no check is performed ! @@ -432,7 +430,7 @@ cpdef FiniteSetMap_Set FiniteSetMap_Set_from_dict(t, parent, d): cdef class FiniteSetMap_Set(FiniteSetMap_MN): """ - Data structure for maps + Data structure for maps. We assume that the parent given as argument is such that: @@ -471,15 +469,13 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): def __call__(self, i): """ - Returns the image of ``i`` under the map ``self`` + Return the image of ``i`` under the map ``self``. INPUT: - - ``i`` -- an int + - ``i`` -- integer - OUTPUT: - - an int + OUTPUT: integer EXAMPLES:: @@ -493,7 +489,7 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): cpdef image_set(self): """ - Returns the image set of ``self`` + Return the image set of ``self``. EXAMPLES:: @@ -509,7 +505,7 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): cpdef setimage(self, i, j): """ - Set the image of ``i`` as ``j`` in ``self`` + Set the image of ``i`` as ``j`` in ``self``. .. warning:: ``self`` must be mutable otherwise an exception is raised. @@ -517,7 +513,7 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): - ``i``, ``j`` -- two ``object``'s - OUTPUT: ``None`` + OUTPUT: none EXAMPLES:: @@ -552,11 +548,11 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): cpdef getimage(self, i): """ - Returns the image of ``i`` by ``self`` + Return the image of ``i`` by ``self``. INPUT: - - ``i`` -- an ``int`` + - ``i`` -- integer EXAMPLES:: @@ -570,7 +566,7 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): cpdef items(self): """ - The items of ``self`` + The items of ``self``. Return the list of the couple ``(x, self(x))`` @@ -604,7 +600,7 @@ cdef class FiniteSetMap_Set(FiniteSetMap_MN): cdef class FiniteSetEndoMap_N(FiniteSetMap_MN): """ - Maps from ``range(n)`` to itself. + Map from ``range(n)`` to itself. .. SEEALSO:: :class:`FiniteSetMap_MN` for assumptions on the parent @@ -621,7 +617,7 @@ cdef class FiniteSetEndoMap_N(FiniteSetMap_MN): sage: F = FiniteSetMaps(3) sage: F([1, 0, 2]) * F([2, 1, 0]) [2, 0, 1] - sage: F = FiniteSetMaps(3, action="right") + sage: F = FiniteSetMaps(3, action='right') sage: F([1, 0, 2]) * F([2, 1, 0]) [1, 2, 0] """ @@ -637,8 +633,8 @@ cdef class FiniteSetEndoMap_N(FiniteSetMap_MN): INPUT: - - ``n`` -- a positive integer - - ``dummy`` -- not used; must be set to ``None`` (for compatibility only). + - ``n`` -- positive integer + - ``dummy`` -- not used; must be set to ``None`` (for compatibility only) EXAMPLES:: @@ -657,7 +653,7 @@ cdef class FiniteSetEndoMap_N(FiniteSetMap_MN): cdef class FiniteSetEndoMap_Set(FiniteSetMap_Set): """ - Maps from a set to itself + Map from a set to itself. .. SEEALSO:: :class:`FiniteSetMap_Set` for assumptions on the parent @@ -691,12 +687,12 @@ cdef class FiniteSetEndoMap_Set(FiniteSetMap_Set): def __pow__(self, n, dummy): """ - Return the ``n``-th power of self. + Return the ``n``-th power of ``self``. INPUT: - - ``n`` -- a positive integer - - ``dummy`` -- not used; must be set to None (for compatibility only). + - ``n`` -- positive integer + - ``dummy`` -- not used; must be set to None (for compatibility only) EXAMPLES:: diff --git a/src/sage/sets/finite_set_maps.py b/src/sage/sets/finite_set_maps.py index b0faa1ddd95..290e32d5e3c 100644 --- a/src/sage/sets/finite_set_maps.py +++ b/src/sage/sets/finite_set_maps.py @@ -37,7 +37,7 @@ class FiniteSetMaps(UniqueRepresentation, Parent): r""" - Maps between finite sets + Maps between finite sets. Constructs the set of all maps between two sets. The sets can be given using any of the three following ways: @@ -54,12 +54,12 @@ class FiniteSetMaps(UniqueRepresentation, Parent): INPUT: - - ``domain`` -- a set, finite iterable, or integer. + - ``domain`` -- set, finite iterable, or integer - - ``codomain`` -- a set, finite iterable, integer, or ``None`` + - ``codomain`` -- set, finite iterable, integer, or ``None`` (default). In this last case, the maps are endo-maps of the domain. - - ``action`` -- ``"left"`` (default) or ``"right"``. The side + - ``action`` -- ``'left'`` (default) or ``'right'``. The side where the maps act on the domain. This is used in particular to define the meaning of the product (composition) of two maps. @@ -156,7 +156,7 @@ class FiniteSetMaps(UniqueRepresentation, Parent): sage: TestSuite(FiniteSetMaps([], [1, 2])).run() """ @staticmethod - def __classcall_private__(cls, domain, codomain=None, action="left", category=None): + def __classcall_private__(cls, domain, codomain=None, action='left', category=None): """ TESTS:: @@ -195,7 +195,7 @@ def __classcall_private__(cls, domain, codomain=None, action="left", category=No def cardinality(self): """ - The cardinality of ``self`` + The cardinality of ``self``. EXAMPLES:: @@ -239,7 +239,7 @@ def __init__(self, m, n, category=None): def domain(self): """ - The domain of ``self`` + The domain of ``self``. EXAMPLES:: @@ -250,7 +250,7 @@ def domain(self): def codomain(self): """ - The codomain of ``self`` + The codomain of ``self``. EXAMPLES:: @@ -291,7 +291,7 @@ def __contains__(self, x): def an_element(self): """ - Returns a map in ``self`` + Return a map in ``self``. EXAMPLES:: @@ -368,16 +368,16 @@ def _element_constructor_(self, *args, **keywords): class FiniteSetMaps_Set(FiniteSetMaps_MN): """ - The sets of all maps between two sets + The sets of all maps between two sets. Users should use the factory class :class:`FiniteSetMaps` to create instances of this class. INPUT: - - ``domain`` -- an object in the category ``FiniteSets()``. + - ``domain`` -- an object in the category ``FiniteSets()`` - - ``codomain`` -- an object in the category ``FiniteSets()``. + - ``codomain`` -- an object in the category ``FiniteSets()`` - ``category`` -- the category in which the sets of maps is constructed. It must be a sub-category of @@ -428,7 +428,7 @@ def __init__(self, domain, codomain, category=None): def domain(self): """ - The domain of ``self`` + The domain of ``self``. EXAMPLES:: @@ -439,7 +439,7 @@ def domain(self): def codomain(self): """ - The codomain of ``self`` + The codomain of ``self``. EXAMPLES:: @@ -451,7 +451,7 @@ def codomain(self): # TODO: consistency from_dict / from_list def _from_list_(self, v): """ - Create a function from a list + Create a function from a list. The list gives in the order of the element of the domain the rank (index) of its image in the codomain. @@ -466,7 +466,7 @@ def _from_list_(self, v): def from_dict(self, d): """ - Create a map from a dictionary + Create a map from a dictionary. EXAMPLES:: @@ -481,14 +481,14 @@ def from_dict(self, d): class FiniteSetEndoMaps_N(FiniteSetMaps_MN): r""" - The sets of all maps from `\{1, 2, \dots, n\}` to itself + The sets of all maps from `\{1, 2, \dots, n\}` to itself. Users should use the factory class :class:`FiniteSetMaps` to create instances of this class. INPUT: - - ``n`` -- an integer. + - ``n`` -- integer - ``category`` -- the category in which the sets of maps is constructed. It must be a sub-category of ``Monoids().Finite()`` @@ -523,7 +523,7 @@ def one(self): def an_element(self): """ - Returns a map in ``self`` + Return a map in ``self``. EXAMPLES:: @@ -547,14 +547,14 @@ def _repr_(self): class FiniteSetEndoMaps_Set(FiniteSetMaps_Set, FiniteSetEndoMaps_N): """ - The sets of all maps from a set to itself + The sets of all maps from a set to itself. Users should use the factory class :class:`FiniteSetMaps` to create instances of this class. INPUT: - - ``domain`` -- an object in the category ``FiniteSets()``. + - ``domain`` -- an object in the category ``FiniteSets()`` - ``category`` -- the category in which the sets of maps is constructed. It must be a sub-category of ``Monoids().Finite()`` diff --git a/src/sage/sets/image_set.py b/src/sage/sets/image_set.py index e2780d523c8..7c3095664e5 100644 --- a/src/sage/sets/image_set.py +++ b/src/sage/sets/image_set.py @@ -52,7 +52,7 @@ class ImageSubobject(Parent): - ``None`` (default): infer from ``map`` or default to ``False`` - ``False``: do not assume that ``map`` is injective - ``True``: ``map`` is known to be injective - - ``"check"``: raise an error when ``map`` is not injective + - ``'check'``: raise an error when ``map`` is not injective - ``inverse`` -- a function (optional); a map from `f(X)` to `X` diff --git a/src/sage/sets/integer_range.py b/src/sage/sets/integer_range.py index 31602abb5a6..1406ddc9b28 100644 --- a/src/sage/sets/integer_range.py +++ b/src/sage/sets/integer_range.py @@ -27,16 +27,16 @@ class IntegerRange(UniqueRepresentation, Parent): r""" - The class of :class:`Integer ` ranges + The class of :class:`Integer ` ranges. Returns an enumerated set containing an arithmetic progression of integers. INPUT: - - ``begin`` -- an integer, Infinity or -Infinity - - ``end`` -- an integer, Infinity or -Infinity - - ``step`` -- a non zero integer (default to 1) - - ``middle_point`` -- an integer inside the set (default to ``None``) + - ``begin`` -- integer, Infinity or -Infinity + - ``end`` -- integer, Infinity or -Infinity + - ``step`` -- a nonzero integer (default: 1) + - ``middle_point`` -- integer inside the set (default: ``None``) OUTPUT: @@ -156,7 +156,7 @@ class IntegerRange(UniqueRepresentation, Parent): [0, 10, -10, 20, -20, 30, -30, 40, -40, 50, -50, 60, -60, 70, -70, 80, -80, 90, -90, -100] - .. note:: + .. NOTE:: The input is normalized so that:: @@ -290,7 +290,7 @@ def _element_constructor_(self, el): class IntegerRangeEmpty(IntegerRange, FiniteEnumeratedSet): r""" - A singleton class for empty integer ranges + A singleton class for empty integer ranges. See :class:`IntegerRange` for more details. """ @@ -338,7 +338,7 @@ def __init__(self, begin, end, step=Integer(1)): def __contains__(self, elt): r""" - Returns True if ``elt`` is in ``self``. + Return ``True`` if ``elt`` is in ``self``. EXAMPLES:: @@ -373,7 +373,7 @@ def __contains__(self, elt): def cardinality(self): """ - Return the cardinality of ``self`` + Return the cardinality of ``self``. EXAMPLES:: @@ -482,7 +482,7 @@ def __getitem__(self, i): def __iter__(self): r""" - Returns an iterator over the elements of ``self`` + Return an iterator over the elements of ``self``. EXAMPLES:: @@ -507,7 +507,7 @@ def __iter__(self): def _an_element_(self): r""" - Returns an element of ``self``. + Return an element of ``self``. EXAMPLES:: @@ -564,7 +564,7 @@ def _repr_(self): def __contains__(self, elt): r""" - Returns True if ``elt`` is in ``self``. + Return ``True`` if ``elt`` is in ``self``. EXAMPLES:: @@ -608,7 +608,7 @@ def rank(self, x): def __getitem__(self, i): r""" - Returns the ``i``-th element of self. + Return the ``i``-th element of ``self``. EXAMPLES:: @@ -633,7 +633,7 @@ def __getitem__(self, i): def __iter__(self): r""" - Returns an iterator over the elements of ``self``. + Return an iterator over the elements of ``self``. EXAMPLES:: @@ -654,7 +654,7 @@ def __iter__(self): def _an_element_(self): r""" - Returns an element of ``self``. + Return an element of ``self``. EXAMPLES:: @@ -725,7 +725,7 @@ def _repr_(self): def __contains__(self, elt): r""" - Returns True if ``elt`` is in ``self``. + Return ``True`` if ``elt`` is in ``self``. EXAMPLES:: @@ -792,7 +792,7 @@ def next(self, elt): def __iter__(self): r""" - Returns an iterator over the elements of ``self``. + Return an iterator over the elements of ``self``. EXAMPLES:: @@ -813,7 +813,7 @@ def __iter__(self): def _an_element_(self): r""" - Returns an element of ``self``. + Return an element of ``self``. EXAMPLES:: diff --git a/src/sage/sets/non_negative_integers.py b/src/sage/sets/non_negative_integers.py index a7995ff3e1e..ab7960df3d1 100644 --- a/src/sage/sets/non_negative_integers.py +++ b/src/sage/sets/non_negative_integers.py @@ -16,9 +16,9 @@ class NonNegativeIntegers(UniqueRepresentation, Parent): r""" - The enumerated set of non negative integers. + The enumerated set of nonnegative integers. - This class implements the set of non negative integers, as an + This class implements the set of nonnegative integers, as an enumerated set (see :class:`InfiniteEnumeratedSets `). @@ -123,8 +123,8 @@ def __contains__(self, elt): def _element_constructor_(self, i): """ - Constructs an element of self from an integer, testing that - this integer is indeed non negative. + Construct an element of ``self`` from an integer, testing that + this integer is indeed nonnegative. EXAMPLES:: diff --git a/src/sage/sets/positive_integers.py b/src/sage/sets/positive_integers.py index 70625fb53b7..31502df53d8 100644 --- a/src/sage/sets/positive_integers.py +++ b/src/sage/sets/positive_integers.py @@ -68,7 +68,7 @@ def _repr_(self): def an_element(self): r""" - Returns an element of ``self``. + Return an element of ``self``. EXAMPLES:: diff --git a/src/sage/sets/pythonclass.pyx b/src/sage/sets/pythonclass.pyx index 7b75bd7bf26..02f34931b64 100644 --- a/src/sage/sets/pythonclass.pyx +++ b/src/sage/sets/pythonclass.pyx @@ -106,7 +106,7 @@ cdef class Set_PythonType_class(Set_generic): def __reduce__(self): r""" - Pickling support + Pickling support. TESTS:: diff --git a/src/sage/sets/real_set.py b/src/sage/sets/real_set.py index 168521ce6a8..5a23d6d18f5 100644 --- a/src/sage/sets/real_set.py +++ b/src/sage/sets/real_set.py @@ -120,20 +120,17 @@ class InternalRealInterval(UniqueRepresentation, Parent): INPUT: - - ``lower`` -- real or minus infinity; the lower bound of the - interval. + - ``lower`` -- real or minus infinity; the lower bound of the interval - - ``lower_closed`` -- boolean; whether the interval is closed - at the lower bound + - ``lower_closed`` -- boolean; whether the interval is closed at the lower + bound - - ``upper`` -- real or (plus) infinity; the upper bound of the - interval + - ``upper`` -- real or (plus) infinity; the upper bound of the interval - - ``upper_closed`` -- boolean; whether the interval is closed - at the upper bound + - ``upper_closed`` -- boolean; whether the interval is closed at the upper + bound - - ``check`` -- boolean; whether to check the other arguments - for validity + - ``check`` -- boolean; whether to check the other arguments for validity """ def __init__(self, lower, lower_closed, upper, upper_closed, check=True): @@ -170,14 +167,12 @@ def __init__(self, lower, lower_closed, upper, upper_closed, check=True): def is_empty(self): """ - Return whether the interval is empty + Return whether the interval is empty. The normalized form of :class:`RealSet` has all intervals non-empty, so this method usually returns ``False``. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -189,11 +184,9 @@ def is_empty(self): def is_point(self): """ - Return whether the interval consists of a single point + Return whether the interval consists of a single point. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -205,11 +198,9 @@ def is_point(self): def lower(self): """ - Return the lower bound - - OUTPUT: + Return the lower bound. - The lower bound as it was originally specified. + OUTPUT: the lower bound as it was originally specified EXAMPLES:: @@ -226,11 +217,9 @@ def lower(self): def upper(self): """ - Return the upper bound - - OUTPUT: + Return the upper bound. - The upper bound as it was originally specified. + OUTPUT: the upper bound as it was originally specified EXAMPLES:: @@ -247,11 +236,9 @@ def upper(self): def lower_closed(self): """ - Return whether the interval is open at the lower bound - - OUTPUT: + Return whether the interval is open at the lower bound. - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -270,11 +257,9 @@ def lower_closed(self): def upper_closed(self): """ - Return whether the interval is closed at the lower bound + Return whether the interval is closed at the lower bound. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -293,11 +278,9 @@ def upper_closed(self): def lower_open(self): """ - Return whether the interval is closed at the upper bound + Return whether the interval is closed at the upper bound. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -316,11 +299,9 @@ def lower_open(self): def upper_open(self): """ - Return whether the interval is closed at the upper bound - - OUTPUT: + Return whether the interval is closed at the upper bound. - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -339,11 +320,9 @@ def upper_open(self): def __richcmp__(self, other, op): """ - Intervals are sorted by lower bound, then upper bound - - OUTPUT: + Intervals are sorted by lower bound, then upper bound. - `-1`, `0`, or `+1` depending on how the intervals compare. + OUTPUT: `-1`, `0`, or `+1` depending on how the intervals compare EXAMPLES:: @@ -373,11 +352,9 @@ def __richcmp__(self, other, op): def _repr_(self): """ - Return a string representation - - OUTPUT: + Return a string representation. - String. + OUTPUT: string EXAMPLES:: @@ -521,11 +498,9 @@ def _giac_condition_(self, variable): def closure(self): """ - Return the closure + Return the closure. - OUTPUT: - - The closure as a new :class:`InternalRealInterval` + OUTPUT: the closure as a new :class:`InternalRealInterval` EXAMPLES:: @@ -546,11 +521,9 @@ def closure(self): def interior(self): """ - Return the interior + Return the interior. - OUTPUT: - - The interior as a new :class:`InternalRealInterval` + OUTPUT: the interior as a new :class:`InternalRealInterval` EXAMPLES:: @@ -565,7 +538,7 @@ def interior(self): def boundary_points(self): """ - Generate the boundary points of ``self`` + Generate the boundary points of ``self``. EXAMPLES:: @@ -573,7 +546,6 @@ def boundary_points(self): [1] sage: list(RealSet.open(1, 2)[0].boundary_points()) [1, 2] - """ if self._lower != minus_infinity: yield self._lower @@ -582,11 +554,11 @@ def boundary_points(self): def is_connected(self, other): """ - Test whether two intervals are connected + Test whether two intervals are connected. OUTPUT: - Boolean. Whether the set-theoretic union of the two intervals + boolean; whether the set-theoretic union of the two intervals has a single connected component. EXAMPLES:: @@ -631,11 +603,9 @@ def is_connected(self, other): def convex_hull(self, other): """ - Return the convex hull of the two intervals + Return the convex hull of the two intervals. - OUTPUT: - - The convex hull as a new :class:`InternalRealInterval`. + OUTPUT: the convex hull as a new :class:`InternalRealInterval` EXAMPLES:: @@ -680,15 +650,13 @@ def convex_hull(self, other): def intersection(self, other): """ - Return the intersection of the two intervals + Return the intersection of the two intervals. INPUT: - ``other`` -- a :class:`InternalRealInterval` - OUTPUT: - - The intersection as a new :class:`InternalRealInterval` + OUTPUT: the intersection as a new :class:`InternalRealInterval` EXAMPLES:: @@ -739,15 +707,13 @@ def intersection(self, other): def contains(self, x): """ - Return whether `x` is contained in the interval + Return whether `x` is contained in the interval. INPUT: - - ``x`` -- a real number. + - ``x`` -- a real number - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -850,7 +816,7 @@ def __rmul__(self, other): def _scan_lower(self): r""" - Helper function for the scan-line method of :class:`RealSet` + Helper function for the scan-line method of :class:`RealSet`. OUTPUT: @@ -886,7 +852,7 @@ def _scan_lower(self): def _scan_upper(self): r""" - Helper function for the scan-line method of :class:`RealSet` + Helper function for the scan-line method of :class:`RealSet`. OUTPUT: @@ -925,7 +891,7 @@ def _scan_upper(self): class RealSet(UniqueRepresentation, Parent, Set_base, Set_boolean_operators, Set_add_sub_operators): r""" - A subset of the real line, a finite union of intervals + A subset of the real line, a finite union of intervals. INPUT: @@ -941,7 +907,7 @@ class RealSet(UniqueRepresentation, Parent, Set_base, - an :class:`~sage.manifolds.differentiable.examples.real_line.OpenInterval`. - ``structure`` -- (default: ``None``) if ``None``, construct the real set as an - instance of :class:`RealSet`; if ``"differentiable"``, construct it as a subset of + instance of :class:`RealSet`; if ``'differentiable'``, construct it as a subset of an instance of :class:`~sage.manifolds.differentiable.examples.real_line.RealLine`, representing the differentiable manifold `\RR`. - ``ambient`` -- (default: ``None``) an instance of @@ -951,7 +917,7 @@ class RealSet(UniqueRepresentation, Parent, Set_base, :class:`~sage.manifolds.differentiable.examples.real_line.RealLine`. Using these keywords implies ``structure='differentiable'``. - ``name``, ``latex_name``, ``start_index`` -- see - :class:`~sage.manifolds.differentiable.examples.real_line.RealLine`. + :class:`~sage.manifolds.differentiable.examples.real_line.RealLine` - ``normalized`` -- (default: ``None``) if ``True``, the input is already normalized, i.e., ``*args`` are the connected components (type :class:`InternalRealInterval`) of the real set in ascending order; no other keyword is provided. @@ -1087,7 +1053,7 @@ class RealSet(UniqueRepresentation, Parent, Set_base, Set {(0, +oo), (0, 1), ℝ} of open subsets of the Real number line ℝ sage: F = RealSet.point(0).union(RealSet.point(1)).union(RealSet.point(2)); F {0} ∪ {1} ∪ {2} - sage: F_tau = RealSet(F, names="τ"); F_tau + sage: F_tau = RealSet(F, names='τ'); F_tau Subset {0} ∪ {1} ∪ {2} of the Real number line ℝ sage: F_tau.manifold().canonical_chart() Chart (ℝ, (τ,)) @@ -1117,9 +1083,7 @@ def __classcall__(cls, *args, **kwds): See :class:`RealSet`. - OUTPUT: - - A :class:`RealSet`. + OUTPUT: a :class:`RealSet` EXAMPLES:: @@ -1354,11 +1318,9 @@ def __init__(self, *intervals, normalized=True): def __richcmp__(self, other, op): r""" - Intervals are sorted by lower bound, then upper bound - - OUTPUT: + Intervals are sorted by lower bound, then upper bound. - `-1`, `0`, or `+1` depending on how the intervals compare. + OUTPUT: `-1`, `0`, or `+1` depending on how the intervals compare EXAMPLES:: @@ -1381,11 +1343,9 @@ def __richcmp__(self, other, op): def __iter__(self): r""" - Iterate over the component intervals is ascending order + Iterate over the component intervals is ascending order. - OUTPUT: - - An iterator over the intervals. + OUTPUT: an iterator over the intervals EXAMPLES:: @@ -1400,9 +1360,9 @@ def __iter__(self): def n_components(self): r""" - Return the number of connected components + Return the number of connected components. - See also :meth:`get_interval` + See also :meth:`get_interval`. EXAMPLES:: @@ -1418,7 +1378,7 @@ def cardinality(self): OUTPUT: - Integer or infinity. The size of a discrete set is the number + Integer or infinity; the size of a discrete set is the number of points; the size of a real interval is Infinity. EXAMPLES:: @@ -1438,7 +1398,7 @@ def cardinality(self): def is_empty(self): r""" - Return whether the set is empty + Return whether the set is empty. EXAMPLES:: @@ -1473,11 +1433,9 @@ def get_interval(self, i): INPUT: - - ``i`` -- integer. - - OUTPUT: + - ``i`` -- integer - The `i`-th connected component as a :class:`InternalRealInterval`. + OUTPUT: the `i`-th connected component as a :class:`InternalRealInterval` EXAMPLES:: @@ -1561,15 +1519,13 @@ def retract(self, x): def normalize(intervals): r""" - Bring a collection of intervals into canonical form + Bring a collection of intervals into canonical form. INPUT: - - ``intervals`` -- a list/tuple/iterable of intervals. + - ``intervals`` -- list/tuple/iterable of intervals - OUTPUT: - - A tuple of intervals such that + OUTPUT: a tuple of intervals such that * they are sorted in ascending order (by lower bound) @@ -1593,9 +1549,7 @@ def _repr_(self): r""" Return a string representation of ``self``. - OUTPUT: - - A string representation. + OUTPUT: string representation EXAMPLES:: @@ -1698,7 +1652,7 @@ def _giac_condition_(self, variable): @staticmethod def _prep(lower, upper=None): r""" - Helper to prepare the lower and upper bounds + Helper to prepare the lower and upper bounds. EXAMPLES:: @@ -1735,21 +1689,19 @@ def _prep(lower, upper=None): @staticmethod def interval(lower, upper, *, lower_closed=None, upper_closed=None, **kwds): r""" - Construct an interval + Construct an interval. INPUT: - - ``lower``, ``upper`` -- two real numbers or infinity. They - will be sorted if necessary. + - ``lower``, ``upper`` -- two real numbers or infinity; they + will be sorted if necessary - ``lower_closed``, ``upper_closed`` -- boolean; whether the interval - is closed at the lower and upper bound of the interval, respectively. - - - ``**kwds`` -- see :class:`RealSet`. + is closed at the lower and upper bound of the interval, respectively - OUTPUT: + - ``**kwds`` -- see :class:`RealSet` - A new :class:`RealSet`. + OUTPUT: a new :class:`RealSet` EXAMPLES:: @@ -1764,18 +1716,16 @@ def interval(lower, upper, *, lower_closed=None, upper_closed=None, **kwds): @staticmethod def open(lower, upper, **kwds): r""" - Construct an open interval + Construct an open interval. INPUT: - - ``lower``, ``upper`` -- two real numbers or infinity. They - will be sorted if necessary. - - - ``**kwds`` -- see :class:`RealSet`. + - ``lower``, ``upper`` -- two real numbers or infinity; they + will be sorted if necessary - OUTPUT: + - ``**kwds`` -- see :class:`RealSet` - A new :class:`RealSet`. + OUTPUT: a new :class:`RealSet` EXAMPLES:: @@ -1788,18 +1738,16 @@ def open(lower, upper, **kwds): @staticmethod def closed(lower, upper, **kwds): r""" - Construct a closed interval + Construct a closed interval. INPUT: - - ``lower``, ``upper`` -- two real numbers or infinity. They - will be sorted if necessary. + - ``lower``, ``upper`` -- two real numbers or infinity; they + will be sorted if necessary - - ``**kwds`` -- see :class:`RealSet`. - - OUTPUT: + - ``**kwds`` -- see :class:`RealSet` - A new :class:`RealSet`. + OUTPUT: a new :class:`RealSet` EXAMPLES:: @@ -1812,17 +1760,15 @@ def closed(lower, upper, **kwds): @staticmethod def point(p, **kwds): r""" - Construct an interval containing a single point + Construct an interval containing a single point. INPUT: - - ``p`` -- a real number. + - ``p`` -- a real number - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` - OUTPUT: - - A new :class:`RealSet`. + OUTPUT: a new :class:`RealSet` EXAMPLES:: @@ -1835,14 +1781,14 @@ def point(p, **kwds): @staticmethod def open_closed(lower, upper, **kwds): r""" - Construct a half-open interval + Construct a half-open interval. INPUT: - - ``lower``, ``upper`` -- two real numbers or infinity. They - will be sorted if necessary. + - ``lower``, ``upper`` -- two real numbers or infinity; they + will be sorted if necessary - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` OUTPUT: @@ -1860,14 +1806,14 @@ def open_closed(lower, upper, **kwds): @staticmethod def closed_open(lower, upper, **kwds): r""" - Construct a half-open interval + Construct a half-open interval. INPUT: - - ``lower``, ``upper`` -- two real numbers or infinity. They - will be sorted if necessary. + - ``lower``, ``upper`` -- two real numbers or infinity; they + will be sorted if necessary - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` OUTPUT: @@ -1885,17 +1831,17 @@ def closed_open(lower, upper, **kwds): @staticmethod def unbounded_below_closed(bound, **kwds): r""" - Construct a semi-infinite interval + Construct a semi-infinite interval. INPUT: - - ``bound`` -- a real number. + - ``bound`` -- a real number OUTPUT: A new :class:`RealSet` from minus infinity to the bound (including). - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` EXAMPLES:: @@ -1908,17 +1854,17 @@ def unbounded_below_closed(bound, **kwds): @staticmethod def unbounded_below_open(bound, **kwds): r""" - Construct a semi-infinite interval + Construct a semi-infinite interval. INPUT: - - ``bound`` -- a real number. + - ``bound`` -- a real number OUTPUT: A new :class:`RealSet` from minus infinity to the bound (excluding). - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` EXAMPLES:: @@ -1931,13 +1877,13 @@ def unbounded_below_open(bound, **kwds): @staticmethod def unbounded_above_closed(bound, **kwds): r""" - Construct a semi-infinite interval + Construct a semi-infinite interval. INPUT: - - ``bound`` -- a real number. + - ``bound`` -- a real number - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` OUTPUT: @@ -1955,13 +1901,13 @@ def unbounded_above_closed(bound, **kwds): @staticmethod def unbounded_above_open(bound, **kwds): r""" - Construct a semi-infinite interval + Construct a semi-infinite interval. INPUT: - - ``bound`` -- a real number. + - ``bound`` -- a real number - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` OUTPUT: @@ -1979,11 +1925,11 @@ def unbounded_above_open(bound, **kwds): @staticmethod def real_line(**kwds): r""" - Construct the real line + Construct the real line. INPUT: - - ``**kwds`` -- see :class:`RealSet`. + - ``**kwds`` -- see :class:`RealSet` EXAMPLES:: @@ -1994,7 +1940,7 @@ def real_line(**kwds): def _scan(self): r""" - Helper function for the scan-line method of :class:`RealSet` + Helper function for the scan-line method of :class:`RealSet`. OUTPUT: @@ -2040,7 +1986,7 @@ def _scan(self): @staticmethod def _scan_to_intervals(scan, condition): r""" - Helper function for the scan-line method of :class:`RealSet` + Helper function for the scan-line method of :class:`RealSet`. INPUT: @@ -2048,9 +1994,7 @@ def _scan_to_intervals(scan, condition): ``(x, epsilon), delta``, see :meth:`_scan` - ``condition`` -- a function indicating the on or off boundary points - OUTPUT: - - Generate :class:`InternalRealInterval` objects. + OUTPUT: generate :class:`InternalRealInterval` objects EXAMPLES:: @@ -2088,16 +2032,14 @@ def _scan_to_intervals(scan, condition): def union(self, *real_set_collection): """ - Return the union of real sets + Return the union of real sets. INPUT: - - ``*real_set_collection`` -- a list/tuple/iterable of :class:`RealSet` - or data that defines one. - - OUTPUT: + - ``*real_set_collection`` -- list/tuple/iterable of :class:`RealSet` + or data that defines one - The set-theoretic union as a new :class:`RealSet`. + OUTPUT: the set-theoretic union as a new :class:`RealSet` EXAMPLES:: @@ -2142,16 +2084,14 @@ def union(self, *real_set_collection): def intersection(self, *real_set_collection): """ - Return the intersection of real sets + Return the intersection of real sets. INPUT: - - ``*real_set_collection`` -- a list/tuple/iterable of :class:`RealSet` - or data that defines one. - - OUTPUT: + - ``*real_set_collection`` -- list/tuple/iterable of :class:`RealSet` + or data that defines one - The set-theoretic intersection as a new :class:`RealSet`. + OUTPUT: the set-theoretic intersection as a new :class:`RealSet` EXAMPLES:: @@ -2222,11 +2162,9 @@ def intersection(self, *real_set_collection): def inf(self): """ - Return the infimum - - OUTPUT: + Return the infimum. - A real number or infinity. + OUTPUT: a real number or infinity EXAMPLES:: @@ -2246,11 +2184,9 @@ def inf(self): def sup(self): """ - Return the supremum + Return the supremum. - OUTPUT: - - A real number or infinity. + OUTPUT: a real number or infinity EXAMPLES:: @@ -2270,11 +2206,9 @@ def sup(self): def complement(self): """ - Return the complement + Return the complement. - OUTPUT: - - The set-theoretic complement as a new :class:`RealSet`. + OUTPUT: the set-theoretic complement as a new :class:`RealSet` EXAMPLES:: @@ -2304,11 +2238,11 @@ def complement(self): def difference(self, *other): """ - Return ``self`` with ``other`` subtracted + Return ``self`` with ``other`` subtracted. INPUT: - - ``other`` -- a :class:`RealSet` or data that defines one. + - ``other`` -- a :class:`RealSet` or data that defines one OUTPUT: @@ -2342,11 +2276,11 @@ def difference(self, *other): def symmetric_difference(self, *other): r""" - Returns the symmetric difference of ``self`` and ``other``. + Return the symmetric difference of ``self`` and ``other``. INPUT: - - ``other`` -- a :class:`RealSet` or data that defines one. + - ``other`` -- a :class:`RealSet` or data that defines one OUTPUT: @@ -2368,15 +2302,13 @@ def symmetric_difference(self, *other): def contains(self, x): """ - Return whether `x` is contained in the set + Return whether `x` is contained in the set. INPUT: - - ``x`` -- a real number. - - OUTPUT: + - ``x`` -- a real number - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -2409,12 +2341,9 @@ def is_subset(self, *other): INPUT: - - ``*other`` -- a :class:`RealSet` or something that defines - one. - - OUTPUT: + - ``*other`` -- a :class:`RealSet` or something that defines one - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -2432,11 +2361,9 @@ def is_subset(self, *other): def _an_element_(self): """ - Return a point of the set - - OUTPUT: + Return a point of the set. - A real number. + OUTPUT: a real number It raises an :class:`~sage.categories.sets_cat.EmptySetError` if the set is empty. @@ -2564,7 +2491,6 @@ def boundary(self): {1} ∪ {2} ∪ {3} ∪ {4} sage: RealSet((1, 2), (2, 3)).boundary() {1} ∪ {2} ∪ {3} - """ return RealSet(*[RealSet.point(x) for i in self._intervals for x in i.boundary_points()]) @@ -2575,12 +2501,10 @@ def convex_hull(*real_set_collection): INPUT: - - ``*real_set_collection`` -- a list/tuple/iterable of :class:`RealSet` - or data that defines one. - - OUTPUT: + - ``*real_set_collection`` -- list/tuple/iterable of :class:`RealSet` + or data that defines one - The convex hull as a new :class:`RealSet`. + OUTPUT: the convex hull as a new :class:`RealSet` EXAMPLES:: @@ -2629,9 +2553,7 @@ def is_connected(self): """ Return whether ``self`` is a connected set. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -2658,15 +2580,13 @@ def is_connected(self): def is_disjoint(self, *other): """ - Test whether the two sets are disjoint + Test whether the two sets are disjoint. INPUT: - - ``other`` -- a :class:`RealSet` or data defining one. + - ``other`` -- a :class:`RealSet` or data defining one - OUTPUT: - - Boolean. + OUTPUT: boolean .. SEEALSO:: :meth:`are_pairwise_disjoint` @@ -2691,16 +2611,14 @@ def is_disjoint(self, *other): @staticmethod def are_pairwise_disjoint(*real_set_collection): """ - Test whether the real sets are pairwise disjoint + Test whether the real sets are pairwise disjoint. INPUT: - - ``*real_set_collection`` -- a list/tuple/iterable of :class:`RealSet` - or data that defines one. - - OUTPUT: + - ``*real_set_collection`` -- list/tuple/iterable of :class:`RealSet` + or data that defines one - Boolean. + OUTPUT: boolean .. SEEALSO:: :meth:`is_disjoint` diff --git a/src/sage/sets/recursively_enumerated_set.pyx b/src/sage/sets/recursively_enumerated_set.pyx index c125d151867..3d9d4a00f75 100644 --- a/src/sage/sets/recursively_enumerated_set.pyx +++ b/src/sage/sets/recursively_enumerated_set.pyx @@ -29,7 +29,7 @@ structure, such as not containing an oriented cycle, that does not help with the enumeration. In this example, the seed is 0 and the successor function is either ``+2`` -or ``+3``. This is the set of non negative linear combinations of 2 and 3:: +or ``+3``. This is the set of nonnegative linear combinations of 2 and 3:: sage: succ = lambda a:[a+2,a+3] sage: C = RecursivelyEnumeratedSet([0], succ) @@ -310,24 +310,24 @@ def RecursivelyEnumeratedSet(seeds, successors, structure=None, - ``seeds`` -- list (or iterable) of hashable objects - ``successors`` -- function (or callable) returning a list (or iterable) of hashable objects - - ``structure`` -- string (default: ``None``), structure of the + - ``structure`` -- string (default: ``None``); structure of the set, possible values are: - - ``None`` -- nothing is known about the structure of the set. + - ``None`` -- nothing is known about the structure of the set - ``'forest'`` -- if the ``successors`` function generates a *forest*, that - is, each element can be reached uniquely from a seed. + is, each element can be reached uniquely from a seed - ``'graded'`` -- if the ``successors`` function is *graded*, that is, all - paths from a seed to a given element have equal length. + paths from a seed to a given element have equal length - ``'symmetric'`` -- if the relation is *symmetric*, that is, ``y in successors(x)`` if and only if ``x in successors(y)`` - ``enumeration`` -- ``'depth'``, ``'breadth'``, ``'naive'`` or ``None`` - (default: ``None``). The default enumeration for the - ``__iter__`` function. - - ``max_depth`` -- integer (default: ``float("inf")``), limit + (default: ``None``); the default enumeration for the + ``__iter__`` function + - ``max_depth`` -- integer (default: ``float("inf")``); limit the search to a certain depth, currently works only for breadth first search - - ``post_process`` -- (default: ``None``), for forest only + - ``post_process`` -- (default: ``None``) for forest only - ``facade`` -- (default: ``None``) - ``category`` -- (default: ``None``) @@ -705,9 +705,7 @@ cdef class RecursivelyEnumeratedSet_generic(Parent): It is currently implemented only for graded or symmetric structure. - OUTPUT: - - An iterator of sets. + OUTPUT: an iterator of sets EXAMPLES:: @@ -733,9 +731,7 @@ cdef class RecursivelyEnumeratedSet_generic(Parent): - ``depth`` -- integer - OUTPUT: - - A set. + OUTPUT: set EXAMPLES:: @@ -760,9 +756,7 @@ cdef class RecursivelyEnumeratedSet_generic(Parent): - ``depth`` -- integer - OUTPUT: - - An iterator. + OUTPUT: an iterator EXAMPLES:: @@ -913,12 +907,10 @@ cdef class RecursivelyEnumeratedSet_generic(Parent): - ``max_depth`` -- (default: ``self._max_depth``) specifies the maximal depth for which outgoing edges of elements are computed - - ``loops`` -- (default: ``True``) option for the digraph - - ``multiedges`` -- (default: ``True``) option of the digraph + - ``loops`` -- boolean (default: ``True``); option for the digraph + - ``multiedges`` -- boolean (default: ``True``); option of the digraph - OUTPUT: - - A directed graph + OUTPUT: a directed graph .. WARNING:: @@ -1079,9 +1071,7 @@ cdef class RecursivelyEnumeratedSet_symmetric(RecursivelyEnumeratedSet_generic): The enumeration remembers only the last two graded components generated since the structure is symmetric. - OUTPUT: - - An iterator of sets. + OUTPUT: an iterator of sets EXAMPLES:: @@ -1162,9 +1152,7 @@ cdef class RecursivelyEnumeratedSet_symmetric(RecursivelyEnumeratedSet_generic): - ``depth`` -- integer - OUTPUT: - - A set. + OUTPUT: set EXAMPLES:: @@ -1223,9 +1211,7 @@ cdef class RecursivelyEnumeratedSet_symmetric(RecursivelyEnumeratedSet_generic): - ``A`` -- set, the set of elements of depth n-1 - ``B`` -- set, the set of elements of depth n - OUTPUT: - - - ``C`` -- set, the set of elements of depth n+1 + OUTPUT: ``C``; the set of elements of depth n+1 .. TODO:: @@ -1331,9 +1317,7 @@ cdef class RecursivelyEnumeratedSet_graded(RecursivelyEnumeratedSet_generic): The algorithm remembers only the current graded component generated since the structure is graded. - OUTPUT: - - An iterator of sets. + OUTPUT: an iterator of sets EXAMPLES:: @@ -1384,9 +1368,7 @@ cdef class RecursivelyEnumeratedSet_graded(RecursivelyEnumeratedSet_generic): - ``depth`` -- integer - OUTPUT: - - A set. + OUTPUT: set EXAMPLES:: @@ -1440,9 +1422,7 @@ cdef class RecursivelyEnumeratedSet_graded(RecursivelyEnumeratedSet_generic): - ``B`` -- set, the set of elements of depth `n` - OUTPUT: - - - ``C`` -- set, the set of elements of depth `n+1` + OUTPUT: ``C``; the set of elements of depth `n+1` .. TODO:: @@ -1498,7 +1478,7 @@ def search_forest_iterator(roots, children, algorithm='depth'): INPUT: - - ``roots`` -- a list (or iterable) + - ``roots`` -- list (or iterable) - ``children`` -- a function returning a list (or iterable) - ``algorithm`` -- ``'depth'`` or ``'breadth'`` (default: ``'depth'``) @@ -1590,7 +1570,7 @@ class RecursivelyEnumeratedSet_forest(Parent): INPUT: - - ``roots`` -- a list (or iterable) + - ``roots`` -- list (or iterable) - ``children`` -- a function returning a list (or iterable, or iterator) - ``post_process`` -- a function defined over the nodes of the forest (default: no post processing) @@ -1812,7 +1792,7 @@ class RecursivelyEnumeratedSet_forest(Parent): @abstract_method def children(self, x): r""" - Return the children of the element ``x`` + Return the children of the element ``x``. The result can be a list, an iterable, an iterator, or even a generator. @@ -1860,7 +1840,7 @@ class RecursivelyEnumeratedSet_forest(Parent): def depth_first_search_iterator(self): r""" - Return a depth first search iterator over the elements of ``self`` + Return a depth first search iterator over the elements of ``self``. EXAMPLES:: @@ -1875,7 +1855,7 @@ class RecursivelyEnumeratedSet_forest(Parent): def breadth_first_search_iterator(self): r""" - Return a breadth first search iterator over the elements of ``self`` + Return a breadth first search iterator over the elements of ``self``. EXAMPLES:: @@ -2052,7 +2032,7 @@ class RecursivelyEnumeratedSet_forest(Parent): reduce_function = None, reduce_init = None): r""" - Apply a Map/Reduce algorithm on ``self`` + Apply a Map/Reduce algorithm on ``self``. INPUT: @@ -2061,12 +2041,12 @@ class RecursivelyEnumeratedSet_forest(Parent): the constant function ``1``. - ``reduce_function`` -- the reduce function (e.g.: the addition of a - monoid). The default value is ``+``. + monoid); the default value is ``+`` - ``reduce_init`` -- the initialisation of the reduction (e.g.: the - neutral element of the monoid). The default value is ``0``. + neutral element of the monoid); the default value is ``0`` - .. note:: + .. NOTE:: the effect of the default values is to compute the cardinality of ``self``. diff --git a/src/sage/sets/set.py b/src/sage/sets/set.py index 2a5c8c86f23..55d5639e706 100644 --- a/src/sage/sets/set.py +++ b/src/sage/sets/set.py @@ -303,7 +303,7 @@ def difference(self, X): def symmetric_difference(self, X): r""" - Returns the symmetric difference of ``self`` and ``X``. + Return the symmetric difference of ``self`` and ``X``. EXAMPLES:: @@ -342,7 +342,7 @@ def _test_as_set_object(self, tester=None, **options): if set_self is not self: from sage.misc.sage_unittest import TestSuite tester.info("\n Running the test suite of Set(self)") - TestSuite(set_self).run(skip="_test_pickling", # see Issue #32025 + TestSuite(set_self).run(skip='_test_pickling', # see Issue #32025 verbose=tester._verbose, prefix=tester._prefix + " ") tester.info(tester._prefix + " ", newline=False) @@ -371,7 +371,7 @@ def __or__(self, X): def __and__(self, X): """ - Returns the intersection of ``self`` and ``X``. + Return the intersection of ``self`` and ``X``. EXAMPLES:: @@ -384,7 +384,7 @@ def __and__(self, X): def __xor__(self, X): """ - Returns the symmetric difference of ``self`` and ``X``. + Return the symmetric difference of ``self`` and ``X``. EXAMPLES:: @@ -470,7 +470,7 @@ class Set_object(Set_generic, Set_base, Set_boolean_operators, Set_add_sub_opera def __init__(self, X, category=None): """ - Create a Set_object + Create a Set_object. This function is called by the Set function; users shouldn't call this directly. @@ -704,9 +704,7 @@ def is_empty(self): """ Return boolean representing emptiness of the set. - OUTPUT: - - True if the set is empty, False if otherwise. + OUTPUT: ``True`` if the set is empty, ``False`` otherwise EXAMPLES:: @@ -806,7 +804,6 @@ def subsets_lattice(self): sage: Y = Set() sage: Y.subsets_lattice() # needs sage.graphs Finite lattice containing 1 elements - """ if not self.is_finite(): raise NotImplementedError( @@ -1094,7 +1091,7 @@ def issubset(self, other): INPUT: - - ``other`` -- a finite Set + - ``other`` -- a finite Set EXAMPLES:: @@ -1122,7 +1119,7 @@ def issuperset(self, other): INPUT: - - ``other`` -- a finite Set + - ``other`` -- a finite Set EXAMPLES:: @@ -1267,9 +1264,9 @@ class Set_object_binary(Set_object, metaclass=ClasscallMetaclass): - ``X``, ``Y`` -- sets, the operands to ``op`` - - ``op`` -- a string describing the binary operation + - ``op`` -- string describing the binary operation - - ``latex_op`` -- a string used for rendering this object in LaTeX + - ``latex_op`` -- string used for rendering this object in LaTeX EXAMPLES:: @@ -1961,7 +1958,6 @@ def __richcmp__(self, right, op): True sage: Y == X True - """ if not isinstance(right, Set_generic): return rich_to_bool(op, -1) diff --git a/src/sage/sets/set_from_iterator.py b/src/sage/sets/set_from_iterator.py index 81cb4f11bbc..0020ca080a1 100644 --- a/src/sage/sets/set_from_iterator.py +++ b/src/sage/sets/set_from_iterator.py @@ -10,7 +10,7 @@ sage: from sage.sets.set_from_iterator import EnumeratedSetFromIterator sage: E = EnumeratedSetFromIterator( ....: graphs, - ....: name="Graphs", + ....: name='Graphs', ....: category=InfiniteEnumeratedSets(), ....: cache=True) sage: E @@ -78,9 +78,9 @@ class EnumeratedSetFromIterator(Parent): - ``f`` -- a function that returns an iterable from which the set is built from - - ``args`` -- tuple -- arguments to be sent to the function ``f`` + - ``args`` -- tuple; arguments to be sent to the function `f` - - ``kwds`` -- dictionary -- keywords to be sent to the function ``f`` + - ``kwds`` -- dictionary; keywords to be sent to the function `f` - ``name`` -- an optional name for the set @@ -90,11 +90,10 @@ class EnumeratedSetFromIterator(Parent): you know that your iterator will run over and over you should set it as :class:`InfiniteEnumeratedSets`. - - ``cache`` -- boolean (default: ``False``) -- Whether or not use a cache - mechanism for the iterator. If ``True``, then the function ``f`` is called + - ``cache`` -- boolean (default: ``False``); whether or not use a cache + mechanism for the iterator. If ``True``, then the function `f` is called only once. - EXAMPLES:: sage: from sage.sets.set_from_iterator import EnumeratedSetFromIterator @@ -362,7 +361,7 @@ def __ne__(self, other): def __iter__(self): r""" - Returns an iterator over the element of ``self``. + Return an iterator over the element of ``self``. EXAMPLES:: @@ -383,7 +382,7 @@ def __iter__(self): def unrank(self, i): r""" - Returns the element at position ``i``. + Return the element at position ``i``. EXAMPLES:: @@ -488,7 +487,7 @@ def _instancedoc_(self): def _sage_src_(self): r""" - Returns the source code for the wrapped function. + Return the source code for the wrapped function. TESTS:: @@ -506,7 +505,7 @@ def is_square(self): def _sage_src_lines_(self): r""" - Returns the list of source lines and the first line number + Return the list of source lines and the first line number of the wrapped function. TESTS:: @@ -724,8 +723,8 @@ class EnumeratedSetFromIterator_method_caller(Decorator): - ``f`` -- a method of a class of ``inst`` (and not of the instance itself) - - ``name`` -- optional -- either a string (which may contains substitution - rules from argument or a function ``args, kwds -> string``. + - ``name`` -- (optional) either a string (which may contains substitution + rules from argument or a function ``args, kwds -> string`` - ``options`` -- any option accepted by :class:`EnumeratedSetFromIterator` """ @@ -845,11 +844,11 @@ class EnumeratedSetFromIterator_method_decorator(): INPUT: - - ``f`` -- Optional function from which are built the enumerated sets at + - ``f`` -- (optional) function from which are built the enumerated sets at each call - - ``name`` -- Optional string (which may contains substitution rules from - argument) or a function ``(args,kwds) -> string``. + - ``name`` -- (optional) string (which may contains substitution rules from + argument) or a function ``(args,kwds) -> string`` - any option accepted by :class:`EnumeratedSetFromIterator`. @@ -1003,7 +1002,7 @@ class DummyExampleForPicklingTest: @set_from_method def f(self): r""" - Returns the set between ``self.start`` and ``self.stop``. + Return the set between ``self.start`` and ``self.stop``. EXAMPLES:: diff --git a/src/sage/sets/totally_ordered_finite_set.py b/src/sage/sets/totally_ordered_finite_set.py index 9191992c285..757146ed323 100644 --- a/src/sage/sets/totally_ordered_finite_set.py +++ b/src/sage/sets/totally_ordered_finite_set.py @@ -118,13 +118,12 @@ def _repr_(self): sage: A = TotallyOrderedFiniteSet(['gaga',1], facade=False) sage: repr(A('gaga')) #indirect doctest "'gaga'" - """ return repr(self.value) def __str__(self): r""" - String that represents self. + String that represents ``self``. EXAMPLES:: @@ -144,10 +143,10 @@ class TotallyOrderedFiniteSet(FiniteEnumeratedSet): INPUT: - - ``elements`` -- A list of elements in the set + - ``elements`` -- list of elements in the set - - ``facade`` -- (default: ``True``) if ``True``, a facade is used; it - should be set to ``False`` if the elements do not inherit from + - ``facade`` -- boolean (default: ``True``); if ``True``, a facade is used. + It should be set to ``False`` if the elements do not inherit from :class:`~sage.structure.element.Element` or if you want a funny order. See examples for more details. diff --git a/src/sage/stats/basic_stats.py b/src/sage/stats/basic_stats.py index 6937f6cb410..47d890cf0ab 100644 --- a/src/sage/stats/basic_stats.py +++ b/src/sage/stats/basic_stats.py @@ -60,11 +60,9 @@ def mean(v): INPUT: - - ``v`` -- a list of numbers + - ``v`` -- list of numbers - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: @@ -116,11 +114,9 @@ def mode(v): INPUT: - - ``v`` -- a list - - OUTPUT: + - ``v`` -- list - - a list (sorted if possible) + OUTPUT: list (sorted if possible) EXAMPLES:: @@ -186,15 +182,13 @@ def std(v, bias=False): INPUT: - - ``v`` -- a list of numbers + - ``v`` -- list of numbers - - ``bias`` -- bool (default: ``False``); if ``False``, divide by + - ``bias`` -- boolean (default: ``False``); if ``False``, divide by ``len(v) - 1`` instead of ``len(v)`` to give a less biased estimator (sample) for the standard deviation. - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: @@ -276,15 +270,13 @@ def variance(v, bias=False): INPUT: - - ``v`` -- a list of numbers + - ``v`` -- list of numbers - - ``bias`` -- bool (default: ``False``); if ``False``, divide by + - ``bias`` -- boolean (default: ``False``); if ``False``, divide by ``len(v) - 1`` instead of ``len(v)`` to give a less biased estimator (sample) for the standard deviation. - OUTPUT: - - - a number + OUTPUT: a number EXAMPLES:: @@ -376,11 +368,11 @@ def variance(v, bias=False): def median(v): """ - Return the median (middle value) of the elements of `v` + Return the median (middle value) of the elements of `v`. If `v` is empty, we define the median to be NaN, which is consistent with NumPy (note that R returns NULL). - If `v` is comprised of strings, :class:`TypeError` occurs. + If `v` is comprised of strings, :exc:`TypeError` occurs. For elements other than numbers, the median is a result of :func:`sorted`. This function is deprecated. Use :func:`numpy.median` or :func:`numpy.nanmedian` @@ -388,11 +380,9 @@ def median(v): INPUT: - - ``v`` -- a list + - ``v`` -- list - OUTPUT: - - - median element of `v` + OUTPUT: median element of `v` EXAMPLES:: @@ -443,13 +433,11 @@ def moving_average(v, n): INPUT: - - ``v`` -- a list - - - ``n`` -- the number of values used in computing each average. + - ``v`` -- list - OUTPUT: + - ``n`` -- the number of values used in computing each average - - a list of length ``len(v)-n+1``, since we do not fabric any values + OUTPUT: list of length ``len(v)-n+1``, since we do not fabric any values EXAMPLES:: @@ -477,7 +465,6 @@ def moving_average(v, n): [2.0000, 3.0000, 4.0000, 5.0000, 6.0000, 7.0000, 8.0000, 9.0000] sage: stats.moving_average(list(a), 3) # needs numpy [2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0] - """ deprecation(29662, 'sage.stats.basic_stats.moving_average is deprecated; use pandas.Series.rolling instead') diff --git a/src/sage/stats/distributions/dgs_bern.h b/src/sage/stats/distributions/dgs_bern.h index 09406616bff..a120cb292ca 100644 --- a/src/sage/stats/distributions/dgs_bern.h +++ b/src/sage/stats/distributions/dgs_bern.h @@ -51,7 +51,7 @@ /** Number of bits sampled at once in ``dgs_bern_uniform_t`` - .. note:: + .. NOTE:: We want machine independent behaviour at least for the MP functions, so we pick 32. */ @@ -73,7 +73,7 @@ /** Balanced Bernoulli distribution. - .. note:: + .. NOTE:: This implementation is faster than ``dgs_bern_mp_t`` @@ -111,7 +111,7 @@ typedef struct { :param length: number of bits to sample from GMP (or 0 for automatic choice) - .. note:: + .. NOTE:: Clear with ``dgs_bern_uniform_clear()``. @@ -200,7 +200,7 @@ typedef struct { :param p: sampler will return 1 with probability `p` and 0 with probability `1-p`. - .. note:: + .. NOTE:: Clear with ``dgs_bern_mp_clear()``. @@ -245,7 +245,7 @@ typedef struct { :param p: sampler will return 1 with probability `p` and 0 with probability `1-p`. - .. note:: + .. NOTE:: Clear with ``dgs_bern_dp_clear()``. @@ -259,7 +259,7 @@ dgs_bern_dp_t *dgs_bern_dp_init(double p); :param self: Bernoulli state - .. note:: + .. NOTE:: Uses libc ``random()``. @@ -307,7 +307,7 @@ typedef struct { :param f: samplers return 1 with probability `exp(-x/f)` :param l: we support inputs to call `x` up to `2^l-1` - .. note:: + .. NOTE:: Clear ``dgs_bern_exp_mp_clear()``. @@ -367,7 +367,7 @@ typedef struct { :param f: samplers return 1 with probability `exp(-x/f)` :param l: we support inputs to call `x` up to `2^l-1` - .. note:: + .. NOTE:: Clear ``dgs_bern_exp_mp_clear()``. diff --git a/src/sage/stats/distributions/dgs_gauss.h b/src/sage/stats/distributions/dgs_gauss.h index 6353d5f52eb..4e3d310e196 100644 --- a/src/sage/stats/distributions/dgs_gauss.h +++ b/src/sage/stats/distributions/dgs_gauss.h @@ -36,7 +36,7 @@ - ``mp`` -- multi-precision using MPFR, cf. ``dgs_gauss_mp.c`` - - ``dp`` -- double precision using machine doubles, cf. ``dgs_gauss_dp.c``. + - ``dp`` -- double precision using machine doubles, cf. ``dgs_gauss_dp.c`` For readers unfamiliar with the implemented algorithms it makes sense to start with ``dgs_gauss_dp.c`` which implements the same algorithms as @@ -94,7 +94,7 @@ /** We consider a double ``x`` an integer if ``fmod(x,1.0) <= DGS_DISC_GAUSS_INTEGER_CUTOFF`` - .. note:: + .. NOTE:: it is okay put 0.0 here as for typical inputs the above inequality holds exactly @@ -105,7 +105,7 @@ /** We consider two doubles ``x`` and ``y`` equal if ``abs(x-y) <= DGS_DISC_GAUSS_EQUAL_DIFF`` - .. note:: + .. NOTE:: the value picked here is somewhat arbitrary */ @@ -322,7 +322,7 @@ long dgs_disc_gauss_dp_call_uniform_online(dgs_disc_gauss_dp_t *self); :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: `c` must be an integer in this algorithm */ @@ -335,7 +335,7 @@ long dgs_disc_gauss_dp_call_uniform_table(dgs_disc_gauss_dp_t *self); :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: This function makes no assumptions about `c` but requires more resources than ``dgs_disc_gauss_dp_call_uniform_table()``. @@ -351,7 +351,7 @@ long dgs_disc_gauss_dp_call_uniform_table_offset(dgs_disc_gauss_dp_t *self); :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: `c` must be an integer in this algorithm */ @@ -365,7 +365,7 @@ long dgs_disc_gauss_dp_call_uniform_logtable(dgs_disc_gauss_dp_t *self); :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: `c` must be an integer in this algorithm @@ -531,7 +531,7 @@ dgs_disc_gauss_mp_t *dgs_disc_gauss_mp_init(mpfr_t sigma, mpfr_t c, size_t tau, :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: `c` must be an integer in this algorithm @@ -545,7 +545,7 @@ void dgs_disc_gauss_mp_call_uniform_table(mpz_t rop, dgs_disc_gauss_mp_t *self, :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: This function makes no assumptions about `c` but requires more resources than ``dgs_disc_gauss_dp_call_uniform_table()``. @@ -560,7 +560,7 @@ void dgs_disc_gauss_mp_call_uniform_table_offset(mpz_t rop, dgs_disc_gauss_mp_t :param self: discrete Gaussian sampler - .. note:: + .. NOTE:: `c` must be an integer in this algorithm */ @@ -582,7 +582,7 @@ void dgs_disc_gauss_mp_call_uniform_online(mpz_t rop, dgs_disc_gauss_mp_t *self, :param self: Discrete Gaussian sampler - .. note:: + .. NOTE:: `c` must be an integer in this algorithm. */ diff --git a/src/sage/stats/distributions/discrete_gaussian_integer.pyx b/src/sage/stats/distributions/discrete_gaussian_integer.pyx index e74b3e8e741..4fd8d24b1f4 100644 --- a/src/sage/stats/distributions/discrete_gaussian_integer.pyx +++ b/src/sage/stats/distributions/discrete_gaussian_integer.pyx @@ -162,7 +162,7 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): # We use tables for σt ≤ table_cutoff table_cutoff = 10**6 - def __init__(self, sigma, c=0, tau=6, algorithm=None, precision="mp"): + def __init__(self, sigma, c=0, tau=6, algorithm=None, precision='mp'): r""" Construct a new sampler for a discrete Gaussian distribution. @@ -179,34 +179,34 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): considered to have probability zero. This bound applies to algorithms which sample from the uniform distribution (default: ``6``) - - ``algorithm`` -- see list below (default: ``"uniform+table"`` for + - ``algorithm`` -- see list below (default: ``'uniform+table'`` for `σt` bounded by ``DiscreteGaussianDistributionIntegerSampler.table_cutoff`` and - ``"uniform+online"`` for bigger `στ`) + ``'uniform+online'`` for bigger `στ`) - - ``precision`` -- either ``"mp"`` for multi-precision where the actual - precision used is taken from sigma or ``"dp"`` for double precision. In - the latter case results are not reproducible. (default: ``"mp"``) + - ``precision`` -- either ``'mp'`` for multi-precision where the actual + precision used is taken from sigma or ``'dp'`` for double precision. In + the latter case results are not reproducible. (default: ``'mp'``) ALGORITHMS: - - ``"uniform+table"`` -- classical rejection sampling, sampling from the + - ``'uniform+table'`` -- classical rejection sampling, sampling from the uniform distribution and accepted with probability proportional to `\exp(-(x-c)²/(2σ²))` where `\exp(-(x-c)²/(2σ²))` is precomputed and stored in a table. Any real-valued `c` is supported. - - ``"uniform+logtable"`` -- samples are drawn from a uniform distribution and + - ``'uniform+logtable'`` -- samples are drawn from a uniform distribution and accepted with probability proportional to `\exp(-(x-c)²/(2σ²))` where `\exp(-(x-c)²/(2σ²))` is computed using logarithmically many calls to Bernoulli distributions. See [DDLL2013]_ for details. Only integer-valued `c` are supported. - - ``"uniform+online"`` -- samples are drawn from a uniform distribution and + - ``'uniform+online'`` -- samples are drawn from a uniform distribution and accepted with probability proportional to `\exp(-(x-c)²/(2σ²))` where `\exp(-(x-c)²/(2σ²))` is computed in each invocation. Typically this is very slow. See [DDLL2013]_ for details. Any real-valued `c` is accepted. - - ``"sigma2+logtable"`` -- samples are drawn from an easily samplable + - ``'sigma2+logtable'`` -- samples are drawn from an easily samplable distribution with `σ = k·σ_2` with `σ_2 = \sqrt{1/(2\log 2)}` and accepted with probability proportional to `\exp(-(x-c)²/(2σ²))` where `\exp(-(x-c)²/(2σ²))` is computed using logarithmically many calls to Bernoulli @@ -217,16 +217,16 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): EXAMPLES:: sage: from sage.stats.distributions.discrete_gaussian_integer import DiscreteGaussianDistributionIntegerSampler - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+online") + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+online') Discrete Gaussian sampler over the Integers with sigma = 3.000000 and c = 0.000000 - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+table") + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+table') Discrete Gaussian sampler over the Integers with sigma = 3.000000 and c = 0.000000 - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+logtable") + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+logtable') Discrete Gaussian sampler over the Integers with sigma = 3.000000 and c = 0.000000 - Note that ``"sigma2+logtable"`` adjusts `σ`:: + Note that ``'sigma2+logtable'`` adjusts `σ`:: - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="sigma2+logtable") + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='sigma2+logtable') Discrete Gaussian sampler over the Integers with sigma = 3.397287 and c = 0.000000 TESTS: @@ -244,12 +244,12 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): ... ValueError: tau must be >= 1 but got -1 - sage: DiscreteGaussianDistributionIntegerSampler(3.0, tau=2, algorithm="superfastalgorithmyouneverheardof") + sage: DiscreteGaussianDistributionIntegerSampler(3.0, tau=2, algorithm='superfastalgorithmyouneverheardof') Traceback (most recent call last): ... ValueError: Algorithm 'superfastalgorithmyouneverheardof' not supported by class 'DiscreteGaussianDistributionIntegerSampler' - sage: DiscreteGaussianDistributionIntegerSampler(3.0, c=1.5, algorithm="sigma2+logtable") + sage: DiscreteGaussianDistributionIntegerSampler(3.0, c=1.5, algorithm='sigma2+logtable') Traceback (most recent call last): ... ValueError: algorithm 'uniform+logtable' requires c%1 == 0 @@ -296,19 +296,19 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): ....: n += 1 sage: from sage.stats.distributions.discrete_gaussian_integer import DiscreteGaussianDistributionIntegerSampler - sage: D = DiscreteGaussianDistributionIntegerSampler(1.0, c=0, tau=2, precision="dp") + sage: D = DiscreteGaussianDistributionIntegerSampler(1.0, c=0, tau=2, precision='dp') sage: mini = 1000; maxi = -1000; s = 0; n = 0 sage: add_samples(2^16) sage: while mini != 0 - 2*1.0 or maxi != 0 + 2*1.0 or abs(float(s)/n) >= 0.05: ....: add_samples(2^16) - sage: D = DiscreteGaussianDistributionIntegerSampler(1.0, c=2.5, tau=2, precision="dp") + sage: D = DiscreteGaussianDistributionIntegerSampler(1.0, c=2.5, tau=2, precision='dp') sage: mini = 1000; maxi = -1000; s = 0; n = 0 sage: add_samples(2^16) sage: while mini != 2 - 2*1.0 or maxi != 2 + 2*1.0 or abs(float(s)/n - 2.45) >= 0.01: ....: add_samples(2^16) - sage: D = DiscreteGaussianDistributionIntegerSampler(1.0, c=2.5, tau=6, precision="dp") + sage: D = DiscreteGaussianDistributionIntegerSampler(1.0, c=2.5, tau=6, precision='dp') sage: mini = 1000; maxi = -1000; s = 0; n = 0 sage: add_samples(2^16) sage: while mini > -1 or maxi < 6 or abs(float(s)/n - 2.5) >= 0.1: @@ -443,7 +443,7 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): TESTS:: sage: from sage.stats.distributions.discrete_gaussian_integer import DiscreteGaussianDistributionIntegerSampler - sage: D = DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+online") + sage: D = DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+online') sage: del D """ if self._gen_mp: @@ -458,15 +458,15 @@ cdef class DiscreteGaussianDistributionIntegerSampler(SageObject): EXAMPLES:: sage: from sage.stats.distributions.discrete_gaussian_integer import DiscreteGaussianDistributionIntegerSampler - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+online")() # random + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+online')() # random -3 - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+table")() # random + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+table')() # random 3 TESTS:: sage: from sage.stats.distributions.discrete_gaussian_integer import DiscreteGaussianDistributionIntegerSampler - sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm="uniform+logtable", precision="dp")() # random output + sage: DiscreteGaussianDistributionIntegerSampler(3.0, algorithm='uniform+logtable', precision='dp')() # random output 13 """ cdef randstate rstate diff --git a/src/sage/stats/distributions/discrete_gaussian_lattice.py b/src/sage/stats/distributions/discrete_gaussian_lattice.py index 428ca30855b..5f734677609 100644 --- a/src/sage/stats/distributions/discrete_gaussian_lattice.py +++ b/src/sage/stats/distributions/discrete_gaussian_lattice.py @@ -82,17 +82,16 @@ def _iter_vectors(n, lower, upper, step=None): INPUT: - - ``n`` -- length, integer ``>0``, - - ``lower`` -- lower bound (inclusive), integer ``< upper``. - - ``upper`` -- upper bound (exclusive), integer ``> lower``. - - ``step`` -- used for recursion, ignore. + - ``n`` -- integer ``>0``; length + - ``lower`` -- integer ``< upper``; lower bound (inclusive) + - ``upper`` -- integer ``> lower``; upper bound (exclusive) + - ``step`` -- used for recursion, ignore EXAMPLES:: sage: from sage.stats.distributions.discrete_gaussian_lattice import _iter_vectors sage: list(_iter_vectors(2, -1, 2)) [(-1, -1), (0, -1), (1, -1), (-1, 0), (0, 0), (1, 0), (-1, 1), (0, 1), (1, 1)] - """ if step is None: if ZZ(lower) >= ZZ(upper): @@ -160,9 +159,9 @@ def compute_precision(precision, sigma): INPUT: - - ``precision`` -- an integer `>= 53` nor ``None``. + - ``precision`` -- integer `>= 53` nor ``None`` - ``sigma`` -- if ``precision`` is ``None`` then the precision of - ``sigma`` is used. + ``sigma`` is used EXAMPLES:: @@ -179,7 +178,6 @@ def compute_precision(precision, sigma): 200 sage: DGL.compute_precision(None, 3) 53 - """ if precision is None: try: @@ -434,8 +432,8 @@ def __init__(self, B, sigma=1, c=0, r=None, precision=None, sigma_basis=False): [Pei2010]_; ignored for spherical Gaussian parameter; if not provided, set to be the maximal possible such that `\Sigma - rBB^T` is positive definite - - ``precision`` -- bit precision `\geq 53`. - - ``sigma_basis`` -- (default: ``False``) When set, ``sigma`` is treated as + - ``precision`` -- bit precision `\geq 53` + - ``sigma_basis`` -- boolean (default: ``False``); when set, ``sigma`` is treated as a (row) basis, i.e. the covariance matrix is computed by `\Sigma = SS^T` .. TODO:: @@ -856,7 +854,7 @@ def _call(self): c_ = c.dot_product(b_) / b_.dot_product(b_) sigma_ = sigma / b_.norm() assert sigma_ > 0 - z = DiscreteGaussianDistributionIntegerSampler(sigma=sigma_, c=c_, algorithm="uniform+online")() + z = DiscreteGaussianDistributionIntegerSampler(sigma=sigma_, c=c_, algorithm='uniform+online')() c = c - z * B[i] v = v + z * B[i] return v diff --git a/src/sage/stats/hmm/chmm.pyx b/src/sage/stats/hmm/chmm.pyx index c7c2ab25b4e..540f91356d0 100644 --- a/src/sage/stats/hmm/chmm.pyx +++ b/src/sage/stats/hmm/chmm.pyx @@ -76,7 +76,7 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): - ``A`` -- matrix; the `N \times N` transition matrix - ``B`` -- list of pairs ``(mu, sigma)`` that define the distributions - ``pi`` -- initial state probabilities - - ``normalize`` -- bool (default: ``True``) + - ``normalize`` -- boolean (default: ``True``) EXAMPLES: @@ -164,11 +164,11 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``A`` -- a list of lists or a square `N \times N` matrix, whose + - ``A`` -- list of lists or a square `N \times N` matrix, whose `(i,j)` entry gives the probability of transitioning from state `i` to state `j`. - - ``B`` -- a list of `N` pairs ``(mu, std)``, where if ``B[i]=(mu,std)``, + - ``B`` -- list of `N` pairs ``(mu, std)``, where if ``B[i]=(mu,std)``, then the probability distribution associated with state `i` normal with mean ``mu`` and standard deviation ``std``. @@ -176,7 +176,7 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): state, i.e., ``pi[i]`` is the probability of starting in state `i`. - - ``normalize`` -- bool (default: ``True``); if given, input is + - ``normalize`` -- boolean (default: ``True``); if given, input is normalized to define valid probability distributions, e.g., the entries of `A` are made nonnegative and the rows sum to 1. @@ -343,8 +343,8 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): INPUT: - ``length`` -- positive integer - - ``starting_state`` -- int (or ``None``); if specified then generate - a sequence using this model starting with the given state + - ``starting_state`` -- integer (or ``None``); if specified then + generate a sequence using this model starting with the given state instead of the initial probabilities to determine the starting state. @@ -534,9 +534,7 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): - ``obs`` -- sequence of observations - OUTPUT: - - float + OUTPUT: float EXAMPLES:: @@ -561,7 +559,7 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``obs`` -- an integer list of observation states. + - ``obs`` -- integer list of observation states OUTPUT: @@ -624,11 +622,11 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): OUTPUT: - - list -- "the" most probable sequence of hidden states, i.e., - the Viterbi path. + - ``list`` -- "the" most probable sequence of hidden states, i.e., + the Viterbi path - - float -- log of probability that the observed sequence - was produced by the Viterbi sequence of states. + - ``float`` -- log of probability that the observed sequence + was produced by the Viterbi sequence of states EXAMPLES: @@ -772,8 +770,8 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): - TimeSeries alpha with alpha_t(i) = alpha[t*N + i] - TimeSeries scale with scale[t] the scaling at step t - - float -- log_probability of the observation sequence - being produced by the model. + - ``float`` -- log_probability of the observation sequence + being produced by the model """ cdef Py_ssize_t i, j, t, T = len(obs) cdef int N = self.N @@ -861,7 +859,7 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): - ``obs`` -- a time series of emissions - - ``max_iter`` -- integer (default: 500) maximum number + - ``max_iter`` -- integer (default: 500); maximum number of Baum-Welch steps to take - ``log_likelihood_cutoff`` -- positive float (default: 1e-4); @@ -873,7 +871,7 @@ cdef class GaussianHiddenMarkovModel(HiddenMarkovModel): reestimating, the standard deviation of emissions is not allowed to be less than ``min_sd``. - - ``fix_emissions`` -- bool (default: ``False``); if ``True``, do not + - ``fix_emissions`` -- boolean (default: ``False``); if ``True``, do not change emissions when updating OUTPUT: @@ -1049,7 +1047,7 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): INPUT: - - ``A`` -- matrix; the `N \times N` transition matrix + - ``A`` -- matrix; the `N \times N` transition matrix - ``B`` -- list of mixture definitions for each state. Each state may have a varying number of gaussians with selection @@ -1057,7 +1055,7 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): - ``pi`` -- initial state probabilities - - ``normalize`` -- bool (default: ``True``); if given, input is + - ``normalize`` -- boolean (default: ``True``); if given, input is normalized to define valid probability distributions, e.g., the entries of `A` are made nonnegative and the rows sum to 1, and the probabilities in ``pi`` are normalized. @@ -1166,7 +1164,8 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): def __richcmp__(self, other, op): r""" - Compare self and other, which must both be GaussianMixtureHiddenMarkovModel's. + Compare ``self`` and ``other``, which must both be + ``GaussianMixtureHiddenMarkovModel``s. EXAMPLES:: @@ -1195,9 +1194,7 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): - ``i`` -- integer - OUTPUT: - - a Gaussian mixture distribution object + OUTPUT: a Gaussian mixture distribution object EXAMPLES:: @@ -1231,11 +1228,9 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): def emission_parameters(self): r""" - Returns a list of all the emission distributions. - - OUTPUT: + Return a list of all the emission distributions. - list of Gaussian mixtures + OUTPUT: list of Gaussian mixtures EXAMPLES:: @@ -1303,7 +1298,7 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): - ``alpha`` -- TimeSeries - ``beta`` -- TimeSeries - ``obs`` -- TimeSeries - - ``j`` -- int + - ``j`` -- integer OUTPUT: @@ -1351,7 +1346,7 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): INPUT: - ``obs`` -- a time series of emissions - - ``max_iter`` -- integer (default: 1000) maximum number + - ``max_iter`` -- integer (default: 1000); maximum number of Baum-Welch steps to take - ``log_likelihood_cutoff`` -- positive float (default: 1e-12); the minimal improvement in likelihood with respect to @@ -1360,7 +1355,7 @@ cdef class GaussianMixtureHiddenMarkovModel(GaussianHiddenMarkovModel): - ``min_sd`` -- positive float (default: 0.01); when reestimating, the standard deviation of emissions is not allowed to be less than ``min_sd``. - - ``fix_emissions`` -- bool (default: ``False``); if ``True``, do not + - ``fix_emissions`` -- boolean (default: ``False``); if ``True``, do not change emissions when updating OUTPUT: diff --git a/src/sage/stats/hmm/distributions.pyx b/src/sage/stats/hmm/distributions.pyx index 1b04dff21cb..ed79d289ed6 100644 --- a/src/sage/stats/hmm/distributions.pyx +++ b/src/sage/stats/hmm/distributions.pyx @@ -78,9 +78,7 @@ cdef class Distribution: - ``n`` -- ``None`` or a positive integer - OUTPUT: - - - a single sample if `n` is 1; otherwise many samples + OUTPUT: a single sample if `n` is 1; otherwise many samples EXAMPLES: @@ -102,9 +100,7 @@ cdef class Distribution: - ``x`` -- object - OUTPUT: - - - float + OUTPUT: float EXAMPLES: @@ -126,9 +122,7 @@ cdef class Distribution: - ``args`` and ``kwds``, passed to the Sage :func:`plot` function - OUTPUT: - - - a :class:`Graphics` object + OUTPUT: a :class:`Graphics` object EXAMPLES:: @@ -165,12 +159,12 @@ cdef class GaussianMixtureDistribution(Distribution): r""" INPUT: - - ``B`` -- a list of triples ``(c_i, mean_i, std_i)``, where + - ``B`` -- list of triples ``(c_i, mean_i, std_i)``, where the ``c_i`` and ``std_i`` are positive and the sum of the - ``c_i`` is `1`. + ``c_i`` is `1` - ``eps`` -- positive real number; any standard deviation in B - less than eps is replaced by eps. + less than eps is replaced by eps - ``normalize`` -- if ``True``, ensure that the ``c_i`` are nonnegative @@ -209,9 +203,7 @@ cdef class GaussianMixtureDistribution(Distribution): - ``i`` -- integer - OUTPUT: - - - triple of floats + OUTPUT: triple of floats EXAMPLES:: @@ -361,7 +353,6 @@ cdef class GaussianMixtureDistribution(Distribution): True sage: P.unfix(); P.is_fixed() False - """ cdef int j if i is None: @@ -469,9 +460,7 @@ cdef class GaussianMixtureDistribution(Distribution): - ``x`` -- float - OUTPUT: - - - float + OUTPUT: float EXAMPLES:: @@ -503,9 +492,7 @@ cdef class GaussianMixtureDistribution(Distribution): - ``x`` -- float - ``m`` -- integer - OUTPUT: - - - float + OUTPUT: float EXAMPLES:: diff --git a/src/sage/stats/hmm/hmm.pyx b/src/sage/stats/hmm/hmm.pyx index 39fb342710d..e471a42d97f 100644 --- a/src/sage/stats/hmm/hmm.pyx +++ b/src/sage/stats/hmm/hmm.pyx @@ -171,11 +171,11 @@ cdef class HiddenMarkovModel: INPUT: - ``length`` -- positive integer - - ``number`` -- (default: ``None``) if given, compute list of this many sample sequences - - ``starting_state`` -- int (or ``None``); if specified, generate - a sequence using this model starting with the given state - instead of the initial probabilities to determine the - starting state. + - ``number`` -- (default: ``None``) if given, compute list of this many + sample sequences + - ``starting_state`` -- integer (or ``None``); if specified, generate a + sequence using this model starting with the given state instead of + the initial probabilities to determine the starting state OUTPUT: @@ -261,11 +261,11 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``A`` -- a list of lists or a square `N \times N` matrix, whose + - ``A`` -- list of lists or a square `N \times N` matrix, whose `(i,j)` entry gives the probability of transitioning from state `i` to state `j`. - - ``B`` -- a list of `N` lists or a matrix with `N` rows, such that + - ``B`` -- list of `N` lists or a matrix with `N` rows, such that `B[i,k]` gives the probability of emitting symbol `k` while in state `i`. @@ -278,7 +278,7 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): is the number of states. Otherwise, they are the entries of the list ``emissions_symbols``, which must all be hashable. - - ``normalize`` -- bool (default: ``True``); if given, input is + - ``normalize`` -- boolean (default: ``True``); if given, input is normalized to define valid probability distributions, e.g., the entries of `A` are made nonnegative and the rows sum to 1, and the probabilities in ``pi`` are normalized. @@ -347,7 +347,6 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): sage: hmm.DiscreteHiddenMarkovModel([1,2,.1,1.2], [[1],[1]],[.5,.5]).transition_matrix() [ 0.3333333333333333 0.6666666666666666] [0.07692307692307693 0.923076923076923] - """ self.pi = util.initial_probs_to_TimeSeries(pi, normalize) self.N = len(self.pi) @@ -459,7 +458,7 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``obs`` -- a list of objects + - ``obs`` -- list of objects OUTPUT: an IntList @@ -478,7 +477,7 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``obs`` -- a list of objects + - ``obs`` -- list of objects OUTPUT: an IntList @@ -494,7 +493,7 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): def log_likelihood(self, obs, bint scale=True): r""" Return the logarithm of the probability that this model produced the given - observation sequence. Thus the output is a non-positive number. + observation sequence. Thus the output is a nonpositive number. INPUT: @@ -548,15 +547,15 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): def _forward(self, IntList obs): r""" - Memory-efficient implementation of the forward algorithm, without scaling. + Memory-efficient implementation of the forward algorithm, without + scaling. INPUT: - - ``obs`` -- an integer list of observation states. - - OUTPUT: + - ``obs`` -- integer list of observation states - ``float`` -- the log of the probability that the model produced this sequence + OUTPUT: ``float`` -- the log of the probability that the model produced + this sequence EXAMPLES:: @@ -607,11 +606,10 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``obs`` -- an integer list of observation states. + - ``obs`` -- integer list of observation states - OUTPUT: - - ``float`` -- the log of the probability that the model produced this sequence + OUTPUT: ``float`` -- the log of the probability that the model produced + this sequence EXAMPLES:: @@ -697,10 +695,9 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): INPUT: - ``length`` -- positive integer - - ``starting_state`` -- int (or ``None``); if specified, generate - a sequence using this model starting with the given state - instead of the initial probabilities to determine the - starting state. + - ``starting_state`` -- integer (or ``None``); if specified, generate a + sequence using this model starting with the given state instead of + the initial probabilities to determine the starting state OUTPUT: @@ -815,12 +812,10 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): INPUT: - - ``q`` -- a nonnegative integer, which specifies a state + - ``q`` -- nonnegative integer, which specifies a state - ``r`` -- a real number between 0 and 1 - OUTPUT: - - a nonnegative int + OUTPUT: a nonnegative int EXAMPLES:: @@ -855,16 +850,16 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): - ``seq`` -- sequence of emitted ints or symbols - - ``log_scale`` -- bool (default: ``True``) whether to scale the - sequence in order to avoid numerical overflow. + - ``log_scale`` -- boolean (default: ``True``); whether to scale the + sequence in order to avoid numerical overflow OUTPUT: - ``list`` -- "the" most probable sequence of hidden states, i.e., - the Viterbi path. + the Viterbi path - ``float`` -- log of probability that the observed sequence - was produced by the Viterbi sequence of states. + was produced by the Viterbi sequence of states EXAMPLES:: @@ -1118,8 +1113,8 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): - TimeSeries alpha with alpha_t(i) = alpha[t*N + i] - TimeSeries scale with scale[t] the scaling at step t - - float -- log_probability of the observation sequence - being produced by the model. + - ``float`` -- log_probability of the observation sequence + being produced by the model """ cdef Py_ssize_t i, j, t, T = len(obs) cdef int N = self.N @@ -1208,7 +1203,7 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): - ``obs`` -- list of emissions - - ``max_iter`` -- integer (default: 100) maximum number + - ``max_iter`` -- integer (default: 100); maximum number of Baum-Welch steps to take - ``log_likelihood_cutoff`` -- positive float (default: 1e-4); @@ -1216,8 +1211,8 @@ cdef class DiscreteHiddenMarkovModel(HiddenMarkovModel): the last iteration required to continue. Relative value to log likelihood. - - ``fix_emissions`` -- bool (default: ``False``); if ``True``, do not - change emissions when updating + - ``fix_emissions`` -- boolean (default: ``False``); if ``True``, do + not change emissions when updating OUTPUT: diff --git a/src/sage/stats/hmm/util.pyx b/src/sage/stats/hmm/util.pyx index a2d34d55e1d..c43abc73f75 100644 --- a/src/sage/stats/hmm/util.pyx +++ b/src/sage/stats/hmm/util.pyx @@ -38,9 +38,7 @@ cdef class HMM_Util: - ``i`` -- nonnegative integer - ``j`` -- nonnegative integer - OUTPUT: - - - ``T`` is modified + OUTPUT: ``T`` is modified EXAMPLES:: @@ -97,9 +95,7 @@ cdef class HMM_Util: equal to 1. If the sum of the entries in a row is 0, replace them all by `1/N`. - OUTPUT: - - - a :class:`TimeSeries` of length `N` + OUTPUT: a :class:`TimeSeries` of length `N` EXAMPLES:: @@ -137,9 +133,7 @@ cdef class HMM_Util: equal to 1. If the sum of the entries in a row is 0, replace them all by `1/N`. - OUTPUT: - - - a :class:`TimeSeries` + OUTPUT: a :class:`TimeSeries` EXAMPLES:: diff --git a/src/sage/stats/intlist.pyx b/src/sage/stats/intlist.pyx index fccbb56e680..6f337badad5 100644 --- a/src/sage/stats/intlist.pyx +++ b/src/sage/stats/intlist.pyx @@ -52,7 +52,6 @@ cdef class IntList: sage: stats.IntList(5) # indirect test [0, 0, 0, 0, 0] - """ self._values = NULL @@ -62,7 +61,7 @@ cdef class IntList: INPUT: - - values -- int, long, Integer, list of integers, or a TimeSeries + - ``values`` -- int, long, Integer, list of integers, or a TimeSeries If the input is a time series or list of floats, then the integer parts of the entries are taken (not the floor). @@ -121,7 +120,7 @@ cdef class IntList: def __richcmp__(IntList self, other, int op): """ - Compare self and other. This has the same semantics + Compare ``self`` and ``other``. This has the same semantics as list comparison. EXAMPLES:: @@ -188,7 +187,7 @@ cdef class IntList: INPUT: - - i -- integer or slice + - ``i`` -- integer or slice EXAMPLES:: @@ -252,8 +251,8 @@ cdef class IntList: INPUT: - - i -- an integer - - x -- an int + - ``i`` -- integer + - ``x`` -- integer EXAMPLES:: @@ -295,8 +294,8 @@ cdef class IntList: sage: loads(dumps(v)) == v True - Note that dumping and loading with compress False is much faster, though - dumping with compress True can save a lot of space:: + Note that dumping and loading with compress ``False`` is much faster, + though dumping with compress ``True`` can save a lot of space:: sage: v = stats.IntList([1..10^5]) sage: loads(dumps(v, compress=False),compress=False) == v @@ -379,9 +378,7 @@ cdef class IntList: """ Return the number of entries in this time series. - OUTPUT: - - Python integer + OUTPUT: Python integer EXAMPLES:: @@ -396,7 +393,7 @@ cdef class IntList: def __add__(left, right): """ - Concatenate the integer lists self and right. + Concatenate the integer lists ``self`` and ``right``. EXAMPLES:: @@ -417,17 +414,17 @@ cdef class IntList: def min(self, bint index=False): """ Return the smallest value in this integer list. If this - series has length 0 we raise a :class:`ValueError`. + series has length 0 we raise a :exc:`ValueError`. INPUT: - - ``index`` -- bool (default: ``False``); if ``True``, also return - index of minimal entry. + - ``index`` -- boolean (default: ``False``); if ``True``, also return + index of minimal entry OUTPUT: - - float -- smallest value - - integer -- index of smallest value; only returned if + - ``float`` -- smallest value + - ``integer`` -- index of smallest value; only returned if ``index=True`` EXAMPLES:: @@ -455,17 +452,17 @@ cdef class IntList: def max(self, bint index=False): """ Return the largest value in this time series. If this series - has length 0 we raise a :class:`ValueError` + has length 0 we raise a :exc:`ValueError` INPUT: - - ``index`` -- bool (default: ``False``); if ``True``, also return - index of maximum entry. + - ``index`` -- boolean (default: ``False``); if ``True``, also return + index of maximum entry OUTPUT: - - int -- largest value - - int -- index of largest value; only returned if ``index=True`` + - integer -- largest value + - integer -- index of largest value; only returned if ``index=True`` EXAMPLES:: @@ -551,11 +548,9 @@ cdef IntList new_int_list(Py_ssize_t length): INPUT: - - length -- a nonnegative integer - - OUTPUT: + - ``length`` -- nonnegative integer - - an IntList. + OUTPUT: an IntList """ if length < 0: raise ValueError("length must be nonnegative") diff --git a/src/sage/stats/r.py b/src/sage/stats/r.py index 47f492eff61..63398fb1a44 100644 --- a/src/sage/stats/r.py +++ b/src/sage/stats/r.py @@ -24,12 +24,12 @@ def ttest(x, y, conf_level=0.95, **kw): """ - T-Test using R + T-Test using R. INPUT: - ``x``, ``y`` -- vectors of same length - - conf_level -- confidence level of the interval, [0,1) in percent + - ``conf_level`` -- confidence level of the interval, [0,1) in percent OUTPUT: diff --git a/src/sage/stats/time_series.pyx b/src/sage/stats/time_series.pyx index 23adae84fb4..3b36f04ab9b 100644 --- a/src/sage/stats/time_series.pyx +++ b/src/sage/stats/time_series.pyx @@ -86,9 +86,9 @@ cdef class TimeSeries: INPUT: - ``values`` -- integer (number of values) or an iterable of - floats. + floats - - ``initialize`` -- bool (default: ``True``); if ``False``, do not + - ``initialize`` -- boolean (default: ``True``); if ``False``, do not bother to zero out the entries of the new time series. For large series that you are going to just fill in, this can be way faster. @@ -243,9 +243,7 @@ cdef class TimeSeries: time series. This is useful since vectors have standard algebraic structure and play well with matrices. - OUTPUT: - - A real double vector. + OUTPUT: a real double vector EXAMPLES:: @@ -292,9 +290,7 @@ cdef class TimeSeries: ``None``. If ``None`` use the default ``sage.stats.time_series.digits``. - OUTPUT: - - A string. + OUTPUT: string EXAMPLES:: @@ -320,9 +316,7 @@ cdef class TimeSeries: r""" Return the number of entries in this time series. - OUTPUT: - - Python integer. + OUTPUT: Python integer EXAMPLES:: @@ -426,9 +420,9 @@ cdef class TimeSeries: INPUT: - - ``i`` -- a nonnegative integer. + - ``i`` -- nonnegative integer - - ``x`` -- a float. + - ``x`` -- a float EXAMPLES:: @@ -486,11 +480,9 @@ cdef class TimeSeries: INPUT: - - ``right`` -- a time series. - - OUTPUT: + - ``right`` -- a time series - A time series. + OUTPUT: a time series EXAMPLES:: @@ -534,11 +526,9 @@ cdef class TimeSeries: INPUT: - - ``left``, ``right`` -- an integer and a time series. + - ``left``, ``right`` -- integer and a time series - OUTPUT: - - A time series. + OUTPUT: a time series EXAMPLES:: @@ -589,11 +579,9 @@ cdef class TimeSeries: INPUT: - - ``M`` -- an integer. - - OUTPUT: + - ``M`` -- integer - A time series -- the coefficients of the autoregressive process. + OUTPUT: a time series -- the coefficients of the autoregressive process EXAMPLES:: @@ -632,7 +620,7 @@ cdef class TimeSeries: INPUT: - ``filter`` -- a time series outputted by the ``autoregressive_fit`` - command. + command EXAMPLES:: @@ -662,9 +650,7 @@ cdef class TimeSeries: Return new time series obtain from this time series by reversing the order of the entries in this time series. - OUTPUT: - - A time series. + OUTPUT: a time series EXAMPLES:: @@ -686,7 +672,7 @@ cdef class TimeSeries: INPUT: - - ``right`` -- iterable that can be converted to a time series. + - ``right`` -- iterable that can be converted to a time series EXAMPLES:: @@ -728,9 +714,7 @@ cdef class TimeSeries: Return new time series got by taking the logarithms of all the terms in the time series. - OUTPUT: - - A new time series. + OUTPUT: a new time series EXAMPLES: @@ -760,9 +744,7 @@ cdef class TimeSeries: Return new time series got by applying the exponential map to all the terms in the time series. - OUTPUT: - - A new time series. + OUTPUT: a new time series EXAMPLES:: @@ -784,9 +766,7 @@ cdef class TimeSeries: Return new time series got by replacing all entries of ``self`` by their absolute value. - OUTPUT: - - A new time series. + OUTPUT: a new time series EXAMPLES:: @@ -815,9 +795,7 @@ cdef class TimeSeries: - ``k`` -- positive integer (default: 1) - OUTPUT: - - A new time series. + OUTPUT: a new time series EXAMPLES:: @@ -842,11 +820,9 @@ cdef class TimeSeries: INPUT: - - ``k`` -- a positive integer. - - OUTPUT: + - ``k`` -- positive integer - A new time series. + OUTPUT: a new time series EXAMPLES:: @@ -897,7 +873,7 @@ cdef class TimeSeries: INPUT: - - ``s`` -- a float. + - ``s`` -- a float EXAMPLES:: @@ -917,11 +893,9 @@ cdef class TimeSeries: INPUT: - - ``s`` -- a float. - - OUTPUT: + - ``s`` -- a float - A new time series with all values multiplied by ``s``. + OUTPUT: a new time series with all values multiplied by ``s`` EXAMPLES:: @@ -946,11 +920,9 @@ cdef class TimeSeries: INPUT: - - ``s`` -- a float. - - OUTPUT: + - ``s`` -- a float - A new time series with ``s`` added to all values. + OUTPUT: a new time series with ``s`` added to all values EXAMPLES:: @@ -967,7 +939,7 @@ cdef class TimeSeries: def add_entries(self, t): r""" Add corresponding entries of ``self`` and ``t`` together, - extending either ``self`` or ``t`` by 0's if they do + extending either ``self`` or ``t`` by 0s if they do not have the same length. .. NOTE:: @@ -977,7 +949,7 @@ cdef class TimeSeries: INPUT: - - ``t`` -- a time series. + - ``t`` -- a time series OUTPUT: @@ -1050,10 +1022,10 @@ cdef class TimeSeries: plot the given number of equally spaced points in the time series. If 0, plot all points. - - ``points`` -- bool (default: ``False``). If ``True``, return just - the points of the time series. + - ``points`` -- boolean (default: ``False``); if ``True``, return just + the points of the time series - - ``**kwds`` -- passed to the line or point command. + - ``**kwds`` -- passed to the line or point command EXAMPLES:: @@ -1102,11 +1074,9 @@ cdef class TimeSeries: INPUT: - - ``k`` -- positive integer. - - OUTPUT: + - ``k`` -- positive integer - A time series with the same number of steps as ``self``. + OUTPUT: a time series with the same number of steps as ``self`` EXAMPLES:: @@ -1156,11 +1126,9 @@ cdef class TimeSeries: INPUT: - - ``alpha`` -- float; a smoothing factor with ``0 <= alpha <= 1``. - - OUTPUT: + - ``alpha`` -- float; a smoothing factor with ``0 <= alpha <= 1`` - A time series with the same number of steps as ``self``. + OUTPUT: a time series with the same number of steps as ``self`` EXAMPLES:: @@ -1202,11 +1170,9 @@ cdef class TimeSeries: INPUT: - - ``s`` -- starting value for partial sums. - - OUTPUT: + - ``s`` -- starting value for partial sums - A time series. + OUTPUT: a time series EXAMPLES:: @@ -1228,9 +1194,7 @@ cdef class TimeSeries: If ``self`` has length 0, returns 0. - OUTPUT: - - A double. + OUTPUT: double EXAMPLES:: @@ -1251,9 +1215,7 @@ cdef class TimeSeries: If ``self`` has length 0, returns 1. - OUTPUT: - - A double. + OUTPUT: double EXAMPLES:: @@ -1272,9 +1234,7 @@ cdef class TimeSeries: r""" Return the mean (average) of the elements of ``self``. - OUTPUT: - - A double. + OUTPUT: double EXAMPLES:: @@ -1292,11 +1252,9 @@ cdef class TimeSeries: INPUT: - - ``k`` -- a float. - - OUTPUT: + - ``k`` -- a float - A time series. + OUTPUT: a time series EXAMPLES:: @@ -1318,11 +1276,9 @@ cdef class TimeSeries: INPUT: - - ``k`` -- a positive integer. + - ``k`` -- positive integer - OUTPUT: - - A double. + OUTPUT: double EXAMPLES:: @@ -1351,11 +1307,9 @@ cdef class TimeSeries: INPUT: - - ``k`` -- a positive integer. - - OUTPUT: + - ``k`` -- positive integer - A double. + OUTPUT: double EXAMPLES:: @@ -1389,7 +1343,7 @@ cdef class TimeSeries: INPUT: - - ``self``, ``other`` -- time series. + - ``self``, ``other`` -- time series Whichever time series has more terms is truncated. @@ -1430,11 +1384,9 @@ cdef class TimeSeries: INPUT: - - ``k`` -- a nonnegative integer (default: 0) + - ``k`` -- nonnegative integer (default: 0) - OUTPUT: - - A float. + OUTPUT: float EXAMPLES:: @@ -1486,7 +1438,7 @@ cdef class TimeSeries: INPUT: - - ``self``, ``other`` -- time series. + - ``self``, ``other`` -- time series Whichever time series has more terms is truncated. @@ -1514,15 +1466,13 @@ cdef class TimeSeries: {\sum_{t=0}^{n-1} (x_t - \mu)^2}. Note that the variance must be nonzero or you will get a - :class:`ZeroDivisionError`. + :exc:`ZeroDivisionError`. INPUT: - - ``k`` -- a nonnegative integer (default: 1) - - OUTPUT: + - ``k`` -- nonnegative integer (default: 1) - A time series. + OUTPUT: a time series EXAMPLES:: @@ -1550,13 +1500,11 @@ cdef class TimeSeries: INPUT: - - ``bias`` -- bool (default: ``False``); if ``False``, divide by + - ``bias`` -- boolean (default: ``False``); if ``False``, divide by ``self.length() - 1`` instead of ``self.length()`` to give a less biased estimator for the variance. - OUTPUT: - - A double. + OUTPUT: double EXAMPLES:: @@ -1594,13 +1542,11 @@ cdef class TimeSeries: INPUT: - - ``bias`` -- bool (default: ``False``); if ``False``, divide by + - ``bias`` -- boolean (default: ``False``); if ``False``, divide by ``self.length() - 1`` instead of ``self.length()`` to give a less biased estimator for the variance. - OUTPUT: - - A double. + OUTPUT: double EXAMPLES:: @@ -1642,16 +1588,14 @@ cdef class TimeSeries: INPUT: - - ``self`` -- a time series (*not* the series of differences). + - ``self`` -- a time series (*not* the series of differences) - ``b`` -- integer (default: ``None``); if given instead divide the input time series up into ``j = floor(n/b)`` disjoint blocks, compute the `R/S` statistic for each block, and return the average of those `R/S` statistics. - OUTPUT: - - A float. + OUTPUT: float EXAMPLES: @@ -1727,18 +1671,18 @@ cdef class TimeSeries: r""" Return the smallest value in this time series. - If this series has length 0, we raise a :class:`ValueError`. + If this series has length 0, we raise a :exc:`ValueError`. INPUT: - - ``index`` -- bool (default: ``False``); if ``True``, also return - index of minimal entry. + - ``index`` -- boolean (default: ``False``); if ``True``, also return + index of minimal entry OUTPUT: - - float -- smallest value. + - float; smallest value - - integer -- index of smallest value; only returned if ``index=True``. + - integer; index of smallest value (only returned if ``index=True``) EXAMPLES:: @@ -1765,18 +1709,18 @@ cdef class TimeSeries: def max(self, bint index=False): r""" Return the largest value in this time series. If this series - has length 0 we raise a :class:`ValueError`. + has length 0 we raise a :exc:`ValueError`. INPUT: - - ``index`` -- bool (default: ``False``); if ``True``, also return - index of maximum entry. + - ``index`` -- boolean (default: ``False``); if ``True``, also return + index of maximum entry OUTPUT: - - float -- largest value. + - float; largest value - - integer -- index of largest value; only returned if ``index=True``. + - integer; index of largest value (only returned if ``index=True``) EXAMPLES:: @@ -1807,13 +1751,11 @@ cdef class TimeSeries: INPUT: - - ``min`` -- (default: ``None``) ``None`` or double. + - ``min`` -- (default: ``None``) ``None`` or double - - ``max`` -- (default: ``None``) ``None`` or double. - - OUTPUT: + - ``max`` -- (default: ``None``) ``None`` or double - A time series. + OUTPUT: a time series EXAMPLES:: @@ -1885,18 +1827,16 @@ cdef class TimeSeries: INPUT: - - ``bins`` -- a positive integer (default: 50) + - ``bins`` -- positive integer (default: 50) - - ``normalize`` -- (default: ``False``) whether to normalize so the - total area in the bars of the histogram is 1. + - ``normalize`` -- boolean (default: ``False``); whether to normalize so the + total area in the bars of the histogram is 1 OUTPUT: - - counts -- list of counts of numbers of elements in - each bin. + - counts -- list of counts of numbers of elements in each bin - - endpoints -- list of 2-tuples (a,b) that give the - endpoints of the bins. + - endpoints -- list of 2-tuples (a,b) that give the endpoints of the bins EXAMPLES:: @@ -1954,12 +1894,10 @@ cdef class TimeSeries: - ``bins`` -- positive integer (default: 50) - - ``normalize`` -- (default: ``True``) whether to normalize so the - total area in the bars of the histogram is 1. - - OUTPUT: + - ``normalize`` -- boolean (default: ``True``); whether to normalize so the + total area in the bars of the histogram is 1 - A histogram plot. + OUTPUT: a histogram plot EXAMPLES:: @@ -1996,12 +1934,10 @@ cdef class TimeSeries: INPUT: - - ``bins`` -- positive integer (default: 30), the number of bins - or candles. - - OUTPUT: + - ``bins`` -- positive integer (default: 30); the number of bins + or candles - A candlestick plot. + OUTPUT: a candlestick plot EXAMPLES: @@ -2058,11 +1994,9 @@ cdef class TimeSeries: INPUT: - - ``copy`` -- bool (default: ``True``) - - OUTPUT: + - ``copy`` -- boolean (default: ``True``) - A numpy 1-D array. + OUTPUT: a numpy 1-D array EXAMPLES:: @@ -2109,7 +2043,7 @@ cdef class TimeSeries: INPUT: - - ``distribution`` -- (default: ``"uniform"``); supported values are: + - ``distribution`` -- (default: ``'uniform'``) supported values are: - ``'uniform'`` -- from ``loc`` to ``loc + scale`` @@ -2209,9 +2143,9 @@ cdef class TimeSeries: INPUT: - - ``left`` -- left bound on random distribution. + - ``left`` -- left bound on random distribution - - ``right`` -- right bound on random distribution. + - ``right`` -- right bound on random distribution EXAMPLES: @@ -2303,7 +2237,7 @@ cdef class TimeSeries: INPUT: - - ``center`` -- the center of the semicircle distribution. + - ``center`` -- the center of the semicircle distribution EXAMPLES: @@ -2523,9 +2457,7 @@ cdef new_time_series(Py_ssize_t length): - ``length`` -- integer - OUTPUT: - - A time series. + OUTPUT: a time series EXAMPLES: diff --git a/src/sage/structure/category_object.pyx b/src/sage/structure/category_object.pyx index 3a7d6e7204e..a72d3fcd887 100644 --- a/src/sage/structure/category_object.pyx +++ b/src/sage/structure/category_object.pyx @@ -84,11 +84,11 @@ cdef class CategoryObject(SageObject): INPUT: - - ``category`` -- The category this object belongs to. If this object + - ``category`` -- the category this object belongs to; if this object belongs to multiple categories, those can be passed as a tuple - - ``base`` -- If this object has another object that should be + - ``base`` -- if this object has another object that should be considered a base in its primary category, you can include that base - here. + here EXAMPLES:: @@ -238,7 +238,7 @@ cdef class CategoryObject(SageObject): Return the underlying class (class without the attached categories) of the given object. - OUTPUT: A class + OUTPUT: a class EXAMPLES:: @@ -429,7 +429,6 @@ cdef class CategoryObject(SageObject): This can only be done once because objects with generators are immutable, and is typically done during creation of the object. - EXAMPLES: When we create this polynomial ring, self._assign_names is called by the constructor:: @@ -490,7 +489,7 @@ cdef class CategoryObject(SageObject): """ Return the first variable name. - OUTPUT: a string + OUTPUT: string EXAMPLES:: @@ -521,7 +520,6 @@ cdef class CategoryObject(SageObject): sage: a #indirect doctest [1 0] [0 0] - """ # old = self._names, self._latex_names # We cannot assume that self *has* _latex_variable_names. @@ -546,7 +544,7 @@ cdef class CategoryObject(SageObject): Thus, e.g., if the generators of ``self`` are labeled 'a', 'b', and 'c', then after calling this method the variables a, b, and c in the current scope will be set - equal to the generators of self. + equal to the generators of ``self``. NOTE: If Foo is a constructor for a Sage object with generators, and Foo is defined in Cython, then it would typically call @@ -670,7 +668,7 @@ cdef class CategoryObject(SageObject): def latex_variable_names(self): """ - Returns the list of variable names suitable for latex output. + Return the list of variable names suitable for latex output. All ``_SOMETHING`` substrings are replaced by ``_{SOMETHING}`` recursively so that subscripts of subscripts work. @@ -773,7 +771,7 @@ cdef class CategoryObject(SageObject): sage: h1 = hash(bla) sage: h1 # random -5279516879544852222 - sage: bla.rename("toto") + sage: bla.rename('toto') sage: h2 = hash(bla) sage: h2 # random -5279516879544852222 @@ -913,7 +911,6 @@ cdef class CategoryObject(SageObject): sage: F = GF(9,'a') # needs sage.rings.finite_rings sage: dir(F) # needs sage.rings.finite_rings [..., '__class__', ..., '_test_pickling', ..., 'extension', ...] - """ return dir_with_other_class(self, self.category().parent_class) @@ -924,7 +921,7 @@ cpdef normalize_names(Py_ssize_t ngens, names): INPUT: - - ``ngens`` -- integer: number of generators. The value ``ngens=-1`` + - ``ngens`` -- integer; number of generators. The value ``ngens=-1`` means that the number of generators is unknown a priori. - ``names`` -- any of the following: @@ -937,7 +934,7 @@ cpdef normalize_names(Py_ssize_t ngens, names): - a string of single character names, such as 'xyz' - OUTPUT: a tuple of ``ngens`` strings to be used as variable names. + OUTPUT: a tuple of ``ngens`` strings to be used as variable names EXAMPLES:: diff --git a/src/sage/structure/coerce.pyx b/src/sage/structure/coerce.pyx index 955a256e9b4..cc15eff82e9 100644 --- a/src/sage/structure/coerce.pyx +++ b/src/sage/structure/coerce.pyx @@ -31,7 +31,7 @@ If there is a coercion (see below) from one of the parents to the other, the operation is always performed in the codomain of that coercion. Otherwise a reasonable attempt to create a new parent with coercion maps from both original parents is made. The results of these discoveries are cached. -On failure, a :class:`TypeError` is always raised. +On failure, a :exc:`TypeError` is always raised. Some arithmetic operations (such as multiplication) can indicate an action rather than arithmetic in a common parent. For example:: @@ -103,8 +103,8 @@ cdef type FractionType = Fraction cpdef py_scalar_parent(py_type): """ - Returns the Sage equivalent of the given python type, if one exists. - If there is no equivalent, return None. + Return the Sage equivalent of the given python type, if one exists. + If there is no equivalent, return ``None``. EXAMPLES:: @@ -697,7 +697,7 @@ cdef class CoercionModel: cpdef _record_exception(self): r""" - Pushes the last exception that occurred onto the stack for later reference, + Push the last exception that occurred onto the stack for later reference, for internal use. If the stack has not yet been flagged as cleared, we clear it now (rather @@ -752,7 +752,7 @@ cdef class CoercionModel: def exception_stack(self): r""" - Returns the list of exceptions that were caught in the course of + Return the list of exceptions that were caught in the course of executing the last binary operation. Useful for diagnosis when user-defined maps or actions raise exceptions that are caught in the course of coercion detection. @@ -1035,12 +1035,12 @@ cdef class CoercionModel: INPUT: - - ``args`` -- a set of elements and/or parents + - ``args`` -- set of elements and/or parents OUTPUT: A :class:`Parent` into which each input should coerce, or raises a - :class:`TypeError` if no such :class:`Parent` can be found. + :exc:`TypeError` if no such :class:`Parent` can be found. EXAMPLES:: @@ -1141,7 +1141,7 @@ cdef class CoercionModel: corresponding to ``op``, and failing that, it tries to coerce `x` and `y` into a common parent and calls ``op`` on them. - If it cannot make sense of the operation, a :class:`TypeError` is raised. + If it cannot make sense of the operation, a :exc:`TypeError` is raised. INPUT: @@ -1525,7 +1525,6 @@ cdef class CoercionModel: sage: N2 = len(list(o for o in gc.get_objects() if type(o) is T)) sage: N2 - N0 0 - """ try: refs = self._coercion_maps.get(R, S, None) @@ -1831,11 +1830,9 @@ cdef class CoercionModel: - ``S`` -- the right :class:`Parent` (or type) - ``op`` -- the operand, typically an element of the :mod:`operator` module - ``r`` -- (optional) element of `R` - - ``s`` -- (optional) element of `S`. - - OUTPUT: + - ``s`` -- (optional) element of `S` - - An action `A` such that `s` ``op`` `r` is given by `A(s,r)`. + OUTPUT: an action `A` such that `s` ``op`` `r` is given by `A(s,r)` The steps taken are illustrated below. diff --git a/src/sage/structure/coerce_actions.pyx b/src/sage/structure/coerce_actions.pyx index 2a9c56174e7..b25abdf328a 100644 --- a/src/sage/structure/coerce_actions.pyx +++ b/src/sage/structure/coerce_actions.pyx @@ -73,7 +73,6 @@ cdef class GenericAction(Action): sage: GenericAction(QQ, Z6, True, check=False) Left action by Rational Field on Ring of integers modulo 6 - """ Action.__init__(self, G, S, is_left, operator.mul) if check: @@ -84,7 +83,7 @@ cdef class GenericAction(Action): def codomain(self): """ - Returns the "codomain" of this action, i.e. the Parent in which the + Return the "codomain" of this action, i.e. the Parent in which the result elements live. Typically, this should be the same as the acted upon set. @@ -107,7 +106,6 @@ cdef class GenericAction(Action): sage: A = sage.structure.coerce_actions.ActOnAction(S3, QQxyz, False) sage: A.codomain() Multivariate Polynomial Ring in x, y, z over Rational Field - """ if self._codomain is None: self._codomain = parent(self.act(an_element(self.G), @@ -253,12 +251,12 @@ cdef class ModuleAction(Action): INPUT: - - ``G`` -- the actor, an instance of :class:`~sage.structure.parent.Parent`. - - ``S`` -- the object that is acted upon. - - ``g`` -- optional, an element of ``G``. - - ``a`` -- optional, an element of ``S``. - - ``check`` -- if True (default), then there will be no consistency tests - performed on sample elements. + - ``G`` -- the actor, an instance of :class:`~sage.structure.parent.Parent` + - ``S`` -- the object that is acted upon + - ``g`` -- (optional) an element of ``G`` + - ``a`` -- (optional) an element of ``S`` + - ``check`` -- if ``True`` (default), then there will be no consistency tests + performed on sample elements NOTE: @@ -275,7 +273,6 @@ cdef class ModuleAction(Action): assumption that the inputs lie exactly in the base ring and may segfault otherwise. Thus we handle all possible base extensions manually here. - """ def __init__(self, G, S, g=None, a=None, check=True): """ @@ -332,7 +329,6 @@ cdef class ModuleAction(Action): sage: G.gen() * S.gen() [x 0] [0 x]*y - """ Action.__init__(self, G, S, not isinstance(self, RightModuleAction), operator.mul) if not isinstance(G, Parent): @@ -431,7 +427,6 @@ cdef class ModuleAction(Action): sage: RightModuleAction(GF5, GF5t) Right scalar multiplication by Finite Field of size 5 on Power Series Ring in t over Finite Field of size 5 - """ return "scalar multiplication" diff --git a/src/sage/structure/coerce_dict.pyx b/src/sage/structure/coerce_dict.pyx index 768d2488dca..e060bc73a28 100644 --- a/src/sage/structure/coerce_dict.pyx +++ b/src/sage/structure/coerce_dict.pyx @@ -204,7 +204,7 @@ cdef class MonoDictEraser: """ INPUT: - A :class:`MonoDict`. + - ``D`` -- a :class:`MonoDict` EXAMPLES:: @@ -222,7 +222,7 @@ cdef class MonoDictEraser: """ INPUT: - A weak reference with key. + - ``r`` -- a weak reference with key For internal use only. @@ -273,12 +273,12 @@ cdef class MonoDict: INPUT: - - ``data`` -- optional iterable defining initial data, as dict or - iterable of (key, value) pairs. + - ``data`` -- (optional) iterable defining initial data, as dict or + iterable of (key, value) pairs - - ``weak_values`` -- optional bool (default: ``False``). If it is true, - weak references to the values in this dictionary will be used, - when possible. + - ``weak_values`` -- boolean (default: ``False``); if it is + ``True``, weak references to the values in this dictionary will be used, + when possible EXAMPLES:: @@ -520,7 +520,7 @@ cdef class MonoDict: def __cinit__(self): """ - Setup basic data structure + Setup basic data structure. TESTS:: @@ -555,7 +555,6 @@ cdef class MonoDict: sage: L = MonoDict([(a, 1)]) sage: L[a] 1 - """ self.weak_values = weak_values if data: @@ -572,7 +571,7 @@ cdef class MonoDict: def __len__(self): """ - The number of items in self. + The number of items in ``self``. EXAMPLES:: sage: from sage.structure.coerce_dict import MonoDict @@ -924,7 +923,7 @@ cdef class TripleDictEraser: """ INPUT: - A :class:`TripleDict`. For internal use only. + - ``D`` -- a :class:`TripleDict`. For internal use only. EXAMPLES:: @@ -936,7 +935,6 @@ cdef class TripleDictEraser: sage: del k sage: len(D) # indirect doctest 0 - """ self.D = ref(D) @@ -944,7 +942,7 @@ cdef class TripleDictEraser: """ INPUT: - A weak reference with key. + - ``r`` -- a weak reference with key For internal use only. @@ -1003,23 +1001,20 @@ cdef class TripleDict: It is bare-bones in the sense that not all dictionary methods are implemented. - INPUT: - - ``data`` -- optional iterable defining initial data, as dict or - iterable of (key, value) pairs. - - - ``weak_values`` -- optional bool (default: ``False``). If it is true, - weak references to the values in this dictionary will be used, - when possible. + - ``data`` -- (optional) iterable defining initial data, as dict or + iterable of (key, value) pairs + - ``weak_values`` -- boolean (default: ``False``); if it is + ``True``, weak references to the values in this dictionary will be used, + when possible IMPLEMENTATION: It is implemented as a hash table with open addressing, similar to python's dict. - EXAMPLES:: sage: from sage.structure.coerce_dict import TripleDict @@ -1190,7 +1185,7 @@ cdef class TripleDict: def __cinit__(self): """ - Setup basic data structure + Setup basic data structure. TESTS:: @@ -1226,7 +1221,6 @@ cdef class TripleDict: sage: L = TripleDict({key: 42}) sage: L[key] 42 - """ self.weak_values = weak_values if data: @@ -1243,7 +1237,7 @@ cdef class TripleDict: def __len__(self): """ - The number of items in self. + The number of items in ``self``. EXAMPLES:: diff --git a/src/sage/structure/debug_options.pyx b/src/sage/structure/debug_options.pyx index 3afe5ca835a..78e12faa0ce 100644 --- a/src/sage/structure/debug_options.pyx +++ b/src/sage/structure/debug_options.pyx @@ -26,7 +26,7 @@ EXAMPLES:: cdef class DebugOptions_class: def __cinit__(self): """ - Initializer for the debug options + Initializer for the debug options. TESTS:: diff --git a/src/sage/structure/dynamic_class.py b/src/sage/structure/dynamic_class.py index 1beb2a8210f..4136c79cfca 100644 --- a/src/sage/structure/dynamic_class.py +++ b/src/sage/structure/dynamic_class.py @@ -131,13 +131,13 @@ def dynamic_class(name, bases, cls=None, reduction=None, doccls=None, r""" INPUT: - - ``name`` -- a string - - ``bases`` -- a tuple of classes + - ``name`` -- string + - ``bases`` -- tuple of classes - ``cls`` -- a class or ``None`` - - ``reduction`` -- a tuple or ``None`` + - ``reduction`` -- tuple or ``None`` - ``doccls`` -- a class or ``None`` - - ``prepend_cls_bases`` -- a boolean (default: ``True``) - - ``cache`` -- a boolean or ``"ignore_reduction"`` (default: ``True``) + - ``prepend_cls_bases`` -- boolean (default: ``True``) + - ``cache`` -- boolean or ``'ignore_reduction'`` (default: ``True``) Constructs dynamically a new class ``C`` with name ``name``, and bases ``bases``. If ``cls`` is provided, then its methods will be @@ -147,7 +147,7 @@ def dynamic_class(name, bases, cls=None, reduction=None, doccls=None, The module, documentation and source instrospection is taken from ``doccls``, or ``cls`` if ``doccls`` is ``None``, or ``bases[0]`` if both are ``None`` (therefore ``bases`` should be non empty if - ``cls` is ``None``). + ``cls`` is ``None``). The constructed class can safely be pickled (assuming the arguments themselves can). @@ -236,7 +236,7 @@ class also has a zero ``__dictoffset__``. This means that the The following (meaningless) example illustrates how to customize the result of the reduction:: - sage: BarFoo = dynamic_class("BarFoo", (Foo,), Bar, reduction = (str, (3,))) + sage: BarFoo = dynamic_class('BarFoo', (Foo,), Bar, reduction = (str, (3,))) sage: type(BarFoo).__reduce__(BarFoo) (, (3,)) sage: loads(dumps(BarFoo)) @@ -253,9 +253,9 @@ class also has a zero ``__dictoffset__``. This means that the and the result depends on the reduction:: - sage: dynamic_class("BarFoo", (Foo,), Bar, reduction = (str, (3,))) is BarFoo + sage: dynamic_class('BarFoo', (Foo,), Bar, reduction = (str, (3,))) is BarFoo True - sage: dynamic_class("BarFoo", (Foo,), Bar, reduction = (str, (2,))) is BarFoo + sage: dynamic_class('BarFoo', (Foo,), Bar, reduction = (str, (2,))) is BarFoo False With ``cache=False``, a new class is created each time:: @@ -272,14 +272,14 @@ class also has a zero ``__dictoffset__``. This means that the With ``cache="ignore_reduction"``, the class does not depend on the reduction:: - sage: BarFoo = dynamic_class("BarFoo", (Foo,), Bar, reduction = (str, (3,)), cache="ignore_reduction") - sage: dynamic_class("BarFoo", (Foo,), Bar, reduction = (str, (2,)), cache="ignore_reduction") is BarFoo + sage: BarFoo = dynamic_class('BarFoo', (Foo,), Bar, reduction = (str, (3,)), cache='ignore_reduction') + sage: dynamic_class('BarFoo', (Foo,), Bar, reduction = (str, (2,)), cache='ignore_reduction') is BarFoo True In particular, the reduction used is that provided upon creating the first class:: - sage: dynamic_class("BarFoo", (Foo,), Bar, reduction = (str, (2,)), cache="ignore_reduction")._reduction + sage: dynamic_class('BarFoo', (Foo,), Bar, reduction = (str, (2,)), cache='ignore_reduction')._reduction (, (3,)) .. WARNING:: diff --git a/src/sage/structure/element.pyx b/src/sage/structure/element.pyx index 63f55b1f59e..e62726dedf7 100644 --- a/src/sage/structure/element.pyx +++ b/src/sage/structure/element.pyx @@ -573,10 +573,10 @@ cdef class Element(SageObject): def __setstate__(self, state): """ - Initializes the state of the object from data saved in a pickle. + Initialize the state of the object from data saved in a pickle. - During unpickling __init__ methods of classes are not called, the saved - data is passed to the class via this function instead. + During unpickling ``__init__`` methods of classes are not called, the + saved data is passed to the class via this function instead. TESTS:: @@ -595,9 +595,7 @@ cdef class Element(SageObject): """ Return a copy of ``self``. - OUTPUT: - - - a new object which is a copy of ``self``. + OUTPUT: a new object which is a copy of ``self`` This implementation ensures that ``self.__dict__`` is properly copied when it exists (typically for instances of classes deriving from @@ -795,9 +793,7 @@ cdef class Element(SageObject): - ``**kwds`` -- named parameters - OUTPUT: - - - new object if substitution is possible, otherwise self. + OUTPUT: new object if substitution is possible, otherwise ``self`` EXAMPLES:: @@ -1032,7 +1028,6 @@ cdef class Element(SageObject): True sage: bool(v + w) False - """ try: zero = self._parent.zero() @@ -1252,7 +1247,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_add_`` calls the Python method ``self._add_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1364,7 +1359,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_sub_`` calls the Python method ``self._sub_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1418,7 +1413,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_neg_`` calls the Python method ``self._neg_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1532,7 +1527,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_mul_`` calls the Python method ``self._mul_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1645,7 +1640,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_matmul_`` calls the Python method ``self._matmul_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the - parent. If the method is not found, a :class:`TypeError` is raised + parent. If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1748,7 +1743,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_div_`` calls the Python method ``self._div_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1848,7 +1843,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_floordiv_`` calls the Python method ``self._floordiv_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -1948,7 +1943,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_mod_`` calls the Python method ``self._mod_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -2075,7 +2070,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_pow_`` calls the Python method ``self._pow_`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -2105,7 +2100,7 @@ cdef class Element(SageObject): This default Cython implementation of ``_pow_int`` calls the Python method ``self._pow_int`` if it exists. This method may be defined in the ``ElementMethods`` of the category of the parent. - If the method is not found, a :class:`TypeError` is raised + If the method is not found, a :exc:`TypeError` is raised indicating that the operation is not supported. See :ref:`element_arithmetic`. @@ -2309,7 +2304,6 @@ cdef class ElementWithCachedMethod(Element): <-5> sage: epython.element_cache_test() is epython.element_cache_test() # needs sage.misc.cython True - """ cdef getattr_from_category(self, name): """ @@ -2381,7 +2375,7 @@ cdef class ModuleElement(Element): """ cpdef _add_(self, other): """ - Abstract addition method + Abstract addition method. TESTS:: @@ -2449,13 +2443,13 @@ cdef class ModuleElement(Element): ################################################## def order(self): ### DO NOT OVERRIDE THIS!!! Instead, override additive_order. """ - Return the additive order of self. + Return the additive order of ``self``. """ return self.additive_order() def additive_order(self): """ - Return the additive order of self. + Return the additive order of ``self``. """ raise NotImplementedError @@ -2495,7 +2489,7 @@ cdef class ModuleElementWithMutability(ModuleElement): cpdef bint is_mutable(self) noexcept: """ - Return True if this vector is mutable, i.e., the entries can be + Return ``True`` if this vector is mutable, i.e., the entries can be changed. EXAMPLES:: @@ -2510,7 +2504,7 @@ cdef class ModuleElementWithMutability(ModuleElement): cpdef bint is_immutable(self) noexcept: """ - Return True if this vector is immutable, i.e., the entries cannot + Return ``True`` if this vector is immutable, i.e., the entries cannot be changed. EXAMPLES:: @@ -2548,19 +2542,19 @@ cdef class MonoidElement(Element): ############################################################# def order(self): """ - Return the multiplicative order of self. + Return the multiplicative order of ``self``. """ return self.multiplicative_order() def multiplicative_order(self): """ - Return the multiplicative order of self. + Return the multiplicative order of ``self``. """ raise NotImplementedError cpdef _pow_int(self, n): """ - Return the (integral) power of self. + Return the (integral) power of ``self``. """ return arith_generic_power(self, n) @@ -2628,7 +2622,7 @@ cdef class MultiplicativeGroupElement(MonoidElement): """ def order(self): """ - Return the multiplicative order of self. + Return the multiplicative order of ``self``. """ return self.multiplicative_order() @@ -2661,7 +2655,7 @@ def is_RingElement(x): cdef class RingElement(ModuleElement): cpdef _mul_(self, other): """ - Abstract multiplication method + Abstract multiplication method. TESTS:: @@ -2721,7 +2715,7 @@ cdef class RingElement(ModuleElement): sage: 2r^(1/2) # needs sage.symbolic sqrt(2) - Exponent overflow should throw an :class:`OverflowError` (:issue:`2956`):: + Exponent overflow should throw an :exc:`OverflowError` (:issue:`2956`):: sage: K. = AA[] # needs sage.rings.number_field sage: x^(2^64 + 12345) # needs sage.rings.number_field @@ -2849,7 +2843,7 @@ cdef class RingElement(ModuleElement): r""" Return the multiplicative order of ``self``, if ``self`` is a unit. - This raise an :class:`ArithmeticError` otherwise. + This raises an :class:`ArithmeticError` otherwise. """ if not self.is_unit(): raise ArithmeticError("self (=%s) must be a unit to have a multiplicative order.") @@ -2900,9 +2894,9 @@ cdef class RingElement(ModuleElement): def is_prime(self): """ - Is ``self`` a prime element? + Check whether ``self`` is a prime element. - A *prime* element is a non-zero, non-unit element `p` such that, + A *prime* element is a nonzero, non-unit element `p` such that, whenever `p` divides `ab` for some `a` and `b`, then `p` divides `a` or `p` divides `b`. @@ -3087,7 +3081,7 @@ cdef class CommutativeRingElement(RingElement): If ``x`` has different parent than ``self``, they are first coerced to a common parent if possible. If this coercion fails, it returns a - TypeError. This fixes :issue:`5759`. :: + :exc:`TypeError`. This fixes :issue:`5759`. :: sage: Zmod(2)(0).divides(Zmod(2)(0)) True @@ -3166,7 +3160,6 @@ cdef class CommutativeRingElement(RingElement): sage: n.mod([15,6]) 2 - EXAMPLES: Univariate polynomials :: @@ -3209,8 +3202,8 @@ cdef class CommutativeRingElement(RingElement): sage: (x^2 + y^2 + z^2).mod( (x^3, y - z) ) # needs sage.libs.singular x^2 + 2*z^2 """ - from sage.rings.ideal import is_Ideal - if not is_Ideal(I) or not I.ring() is self._parent: + from sage.rings.ideal import Ideal_generic + if not isinstance(I, Ideal_generic) or not I.ring() is self._parent: I = self._parent.ideal(I) #raise TypeError, "I = %s must be an ideal in %s"%(I, self.parent()) return I.reduce(self) @@ -3228,15 +3221,15 @@ cdef class CommutativeRingElement(RingElement): INPUT: - - ``root`` -- whether or not to also return a square - root (default: ``False``) + - ``root`` -- boolean (default: ``False``); whether or not to also + return a square root OUTPUT: - - ``bool`` -- whether or not a square + - boolean; whether or not a square - - ``object`` -- (optional) an actual square root if - found, and ``None`` otherwise. + - object; (optional) an actual square root if found, and ``None`` + otherwise EXAMPLES:: @@ -3254,11 +3247,10 @@ cdef class CommutativeRingElement(RingElement): .. NOTE:: - This is the is_square implementation for general - commutative ring elements. It's implementation is to raise - a NotImplementedError. The function definition is here to - show what functionality is expected and provide a general - framework. + This is the is_square implementation for general commutative ring + elements. It's implementation is to raise a + :exc:`NotImplementedError`. The function definition is here to show + what functionality is expected and provide a general framework. """ raise NotImplementedError("is_square() not implemented for elements of %s" % self.parent()) @@ -3269,13 +3261,13 @@ cdef class CommutativeRingElement(RingElement): INPUT: - ``extend`` -- boolean (default: ``True``); whether to make a ring - extension containing a square root if ``self`` is not a square + extension containing a square root if ``self`` is not a square - ``all`` -- boolean (default: ``False``); whether to return a list of - all square roots or just a square root + all square roots or just a square root - ``name`` -- required when ``extend=True`` and ``self`` is not a - square. This will be the name of the generator of the extension. + square; this will be the name of the generator of the extension OUTPUT: @@ -3298,11 +3290,11 @@ cdef class CommutativeRingElement(RingElement): x sage: f = x^2 - 4*x + 4; f.sqrt(all=True) [x - 2, -x + 2] - sage: sqrtx = x.sqrt(name="y"); sqrtx + sage: sqrtx = x.sqrt(name='y'); sqrtx y sage: sqrtx^2 x - sage: x.sqrt(all=true, name="y") + sage: x.sqrt(all=true, name='y') [y, -y] sage: x.sqrt(extend=False, all=True) [] @@ -3343,11 +3335,11 @@ cdef class CommutativeRingElement(RingElement): sage: R. = QQ[] sage: a = 2*(x+1)^2 / (2*(x-1)^2); a.sqrt() (x + 1)/(x - 1) - sage: sqrtx=(1/x).sqrt(name="y"); sqrtx + sage: sqrtx=(1/x).sqrt(name='y'); sqrtx y sage: sqrtx^2 1/x - sage: (1/x).sqrt(all=true, name="y") + sage: (1/x).sqrt(all=true, name='y') [y, -y] sage: (1/x).sqrt(extend=False, all=True) [] @@ -3431,7 +3423,7 @@ cdef class Vector(ModuleElementWithMutability): def __mul__(left, right): """ - Multiplication of vector by vector, matrix, or scalar + Multiplication of vector by vector, matrix, or scalar. AUTHOR: @@ -3806,7 +3798,7 @@ cdef class Matrix(ModuleElement): def __mul__(left, right): """ - Multiplication of matrix by matrix, vector, or scalar + Multiplication of matrix by matrix, vector, or scalar. AUTHOR: @@ -4331,7 +4323,7 @@ cdef class EuclideanDomainElement(PrincipalIdealDomainElement): cpdef _floordiv_(self, right): """ - Quotient of division of ``self`` by other. This is denoted //. + Quotient of division of ``self`` by ``other``. This is denoted ``//``. This default implementation assumes that ``quo_rem`` has been implemented. @@ -4354,7 +4346,7 @@ cdef class EuclideanDomainElement(PrincipalIdealDomainElement): cpdef _mod_(self, other): """ - Remainder of division of ``self`` by other. + Remainder of division of ``self`` by ``other``. This default implementation assumes that ``quo_rem`` has been implemented. @@ -4396,7 +4388,7 @@ def is_FieldElement(x): cdef class FieldElement(CommutativeRingElement): cpdef _floordiv_(self, right): """ - Return the quotient of self and other. Since these are field + Return the quotient of ``self`` and ``other``. Since these are field elements, the floor division is exactly the same as usual division. EXAMPLES:: @@ -4440,7 +4432,7 @@ cdef class FieldElement(CommutativeRingElement): def _lcm(self, FieldElement other): """ - Return the least common multiple of ``self`` and other. + Return the least common multiple of ``self`` and ``other``. """ if self.is_zero() and other.is_zero(): return self @@ -4471,10 +4463,10 @@ cdef class FieldElement(CommutativeRingElement): def divides(self, FieldElement other): r""" - Check whether ``self`` divides other, for field elements. + Check whether ``self`` divides ``other``, for field elements. Since this is a field, all values divide all other values, - except that zero does not divide any non-zero values. + except that zero does not divide any nonzero values. EXAMPLES:: diff --git a/src/sage/structure/factorization.py b/src/sage/structure/factorization.py index 8d65ccb1197..ab3fa717031 100644 --- a/src/sage/structure/factorization.py +++ b/src/sage/structure/factorization.py @@ -6,7 +6,7 @@ general lists of objects with integer multiplicities. These may hold the results of an arithmetic or algebraic factorization, where the objects may be primes or irreducible polynomials and the -multiplicities are the (non-zero) exponents in the factorization. For +multiplicities are the (nonzero) exponents in the factorization. For other types of examples, see below. :class:`Factorization` class objects contain a ``list``, so can be @@ -227,25 +227,23 @@ def __init__(self, x, unit=None, cr=False, sort=True, simplify=True): INPUT: - - ``x`` -- a list of pairs (p, e) with e an integer; - otherwise a :class:`TypeError` is raised + - ``x`` -- list of pairs (p, e) with e an integer + otherwise a :exc:`TypeError` is raised - - ``unit`` -- (default: 1); the unit part of the factorization. + - ``unit`` -- (default: 1) the unit part of the factorization - - ``cr`` -- (default: ``False``); if ``True``, print the factorization - with carriage returns between factors. + - ``cr`` -- (default: ``False``) if ``True``, print the factorization + with carriage returns between factors - - ``sort`` -- (default: ``True``); if ``True``, sort the factors by + - ``sort`` -- (default: ``True``) if ``True``, sort the factors by calling the sort function ``self.sort()`` after creating the factorization - - ``simplify`` -- (default: ``True``); if ``True``, remove duplicate + - ``simplify`` -- (default: ``True``) if ``True``, remove duplicate factors from the factorization. See the documentation for self.simplify. - OUTPUT: - - a Factorization object + OUTPUT: a Factorization object EXAMPLES: @@ -328,7 +326,7 @@ def __init__(self, x, unit=None, cr=False, sort=True, simplify=True): def __getitem__(self, i): """ - Return `i^{th}` factor of ``self``. + Return `i`-th factor of ``self``. EXAMPLES:: @@ -349,7 +347,7 @@ def __getitem__(self, i): def __setitem__(self, i, v): """ - Set the `i^{th}` factor of ``self``. + Set the `i`-th factor of ``self``. .. warning:: @@ -520,7 +518,7 @@ def universe(self): r""" Return the parent structure of my factors. - .. note:: + .. NOTE:: This used to be called ``base_ring``, but the universe of a factorization need not be a ring. @@ -558,7 +556,7 @@ def base_change(self, U): sage: F.base_change(P).universe() Univariate Polynomial Ring in x over Integer Ring - This method will return a :class:`TypeError` if the coercion is not + This method will return a :exc:`TypeError` if the coercion is not possible:: sage: g = x^2 - 1 @@ -664,11 +662,9 @@ def sort(self, key=None): INPUT: - - ``key`` -- (default: ``None``); comparison key - - OUTPUT: + - ``key`` -- (default: ``None``) comparison key - - changes this factorization to be sorted (inplace) + OUTPUT: changes this factorization to be sorted (inplace) If ``key`` is ``None``, we determine the comparison key as follows: @@ -921,7 +917,6 @@ def __pari__(self): sage: g = factor(x^10 - 1) # needs sage.libs.pari sage: pari(g) # needs sage.libs.pari [x - 1, 1; x + 1, 1; x^4 - x^3 + x^2 - x + 1, 1; x^4 + x^3 + x^2 + x + 1, 1] - """ from sage.libs.pari.all import pari from itertools import chain @@ -1042,7 +1037,7 @@ def __mul__(self, other): If the two factorizations have different universes, this method will attempt to find a common universe for the - product. A :class:`TypeError` is raised if this is impossible. + product. A :exc:`TypeError` is raised if this is impossible. EXAMPLES:: @@ -1102,7 +1097,7 @@ def __mul__(self, other): def __pow__(self, n): """ - Return the `n^{th}` power of a factorization, which is got by + Return the `n`-th power of a factorization, which is got by combining together like factors. EXAMPLES:: @@ -1279,7 +1274,7 @@ def gcd(self, other): If the two factorizations have different universes, this method will attempt to find a common universe for the - gcd. A :class:`TypeError` is raised if this is impossible. + gcd. A :exc:`TypeError` is raised if this is impossible. EXAMPLES:: @@ -1321,7 +1316,7 @@ def lcm(self, other): If the two factorizations have different universes, this method will attempt to find a common universe for the - lcm. A :class:`TypeError` is raised if this is impossible. + lcm. A :exc:`TypeError` is raised if this is impossible. EXAMPLES:: @@ -1359,7 +1354,7 @@ def lcm(self, other): def is_integral(self) -> bool: r""" - Return whether all exponents of this Factorization are non-negative. + Return whether all exponents of this Factorization are nonnegative. EXAMPLES:: @@ -1380,7 +1375,7 @@ def radical(self): Return the factorization of the radical of the value of ``self``. First, check that all exponents in the factorization are - positive, raise :class:`ValueError` otherwise. If all exponents are + positive, raise :exc:`ValueError` otherwise. If all exponents are positive, return ``self`` with all exponents set to 1 and with the unit set to 1. @@ -1405,7 +1400,7 @@ def radical_value(self): Return the product of the prime factors in ``self``. First, check that all exponents in the factorization are - positive, raise :class:`ValueError` otherwise. If all exponents are + positive, raise :exc:`ValueError` otherwise. If all exponents are positive, return the product of the prime factors in ``self``. This should be functionally equivalent to ``self.radical().value()``. diff --git a/src/sage/structure/factory.pyx b/src/sage/structure/factory.pyx index 548e2c40a4e..bde82e5d18f 100644 --- a/src/sage/structure/factory.pyx +++ b/src/sage/structure/factory.pyx @@ -179,7 +179,7 @@ cdef class UniqueFactory(SageObject): ....: Now we can create a factory instance. It is supposed to be found under the - name ``"F"`` in the ``"__main__"`` module. Note that in an interactive + name ``'F'`` in the ``__main__`` module. Note that in an interactive session, ``F`` would automatically be in the ``__main__`` module. Hence, the second and third of the following four lines are only needed in doctests. :: @@ -237,7 +237,7 @@ cdef class UniqueFactory(SageObject): only considered an "extra argument" that does not count for the key. :: - sage: c is F(1, impl='C') is F(1, impl="D") is F(1) # needs sage.misc.cython + sage: c is F(1, impl='C') is F(1, impl='D') is F(1) # needs sage.misc.cython True However, pickling and unpickling does not use the cache. This is because @@ -292,9 +292,9 @@ cdef class UniqueFactory(SageObject): """ INPUT: - - ``name`` -- string. A name in the global namespace referring - to self or a fully qualified path name to self, which is - used to locate the factory on unpickling. + - ``name`` -- string; a name in the global namespace referring to + ``self`` or a fully qualified path name to ``self``, which is used to + locate the factory on unpickling EXAMPLES:: @@ -374,7 +374,7 @@ cdef class UniqueFactory(SageObject): cpdef get_object(self, version, key, extra_args): """ - Returns the object corresponding to ``key``, creating it with + Return the object corresponding to ``key``, creating it with ``extra_args`` if necessary (for example, it isn't in the cache or it is unpickling from an older version of Sage). @@ -403,7 +403,6 @@ cdef class UniqueFactory(SageObject): Making object (1 + O(2^20), 'c') sage: d is test_factory.get_object(3.0, (K(1), 'c'), {}) # needs sage.rings.padics True - """ cache_key = key try: @@ -715,7 +714,6 @@ def generic_factory_unpickle(factory, *args): False sage: loads(dumps(b)) is b True - """ cdef UniqueFactory F if factory is not None: diff --git a/src/sage/structure/formal_sum.py b/src/sage/structure/formal_sum.py index f037f71042e..ab72ff5eb2d 100644 --- a/src/sage/structure/formal_sum.py +++ b/src/sage/structure/formal_sum.py @@ -17,9 +17,9 @@ FUNCTIONS: - ``FormalSums(ring)`` -- create the module of formal finite sums with - coefficients in the given ring. + coefficients in the given ring -- ``FormalSum(list of pairs (coeff, number))`` -- create a formal sum. +- ``FormalSum(list of pairs (coeff, number))`` -- create a formal sum EXAMPLES:: @@ -90,10 +90,9 @@ def __init__(self, x, parent=None, check=True, reduce=True): - ``x`` -- object - ``parent`` -- FormalSums(R) module (default: FormalSums(ZZ)) - - ``check`` -- bool (default: ``True``) if ``False``, might not coerce - coefficients into base ring, which can speed - up constructing a formal sum. - - ``reduce`` -- reduce (default: ``True``) if ``False``, do not + - ``check`` -- boolean (default: ``True``); if ``False``, might not coerce + coefficients into base ring, which can speed up constructing a formal sum + - ``reduce`` -- boolean (default: ``True``); if ``False``, do not combine common terms .. WARNING:: @@ -342,7 +341,6 @@ class FormalSums(UniqueRepresentation, Module): TESTS:: sage: TestSuite(FormalSums(QQ)).run() - """ Element = FormalSum @@ -371,15 +369,15 @@ def _repr_(self): def _element_constructor_(self, x, check=True, reduce=True): """ - Make a formal sum in self from x. + Make a formal sum in ``self`` from x. INPUT: - ``x`` -- formal sum, list or number - - ``check`` -- bool (default: ``True``) + - ``check`` -- boolean (default: ``True``) - - ``reduce`` -- bool (default: ``True``); whether to combine terms + - ``reduce`` -- boolean (default: ``True``); whether to combine terms EXAMPLES:: @@ -402,7 +400,7 @@ def _element_constructor_(self, x, check=True, reduce=True): def _coerce_map_from_(self, X): r""" - Return whether there is a coercion from ``X`` + Return whether there is a coercion from ``X``. EXAMPLES:: diff --git a/src/sage/structure/global_options.py b/src/sage/structure/global_options.py index 437554b4130..854a93e6009 100644 --- a/src/sage/structure/global_options.py +++ b/src/sage/structure/global_options.py @@ -49,13 +49,13 @@ The options constructed by :class:`GlobalOptions` have to be explicitly associated to the class that they control using the following arguments: -- ``NAME`` -- A descriptive name for the options class. This is - optional; the default is the name of the constructed class. +- ``NAME`` -- a descriptive name for the options class; this is + optional. The default is the name of the constructed class. -- ``module`` -- The sage module containing the options class (optional) +- ``module`` -- the sage module containing the options class (optional) -- ``option_class`` -- The name of the options class. This is optional and - defaults to ``NAME`` if not explicitly set. +- ``option_class`` -- the name of the options class; this is optional and + defaults to ``NAME`` if not explicitly set It is only possible to pickle a :class:`GlobalOptions` class if the corresponding module is specified *and* if the options are explicitly @@ -65,31 +65,31 @@ values for the option and its documentation. The possible entries in this dictionary are: -- ``alias`` -- Allows for several option values to do the same thing. +- ``alias`` -- allows for several option values to do the same thing -- ``alt_name`` -- An alternative name for this option. +- ``alt_name`` -- an alternative name for this option -- ``checker`` -- A validation function which returns whether a user +- ``checker`` -- a validation function which returns whether a user supplied value is valid or not. This is typically useful for large lists of legal values such as :class:`~sage.rings.semirings.non_negative_integer_semiring.NN`. -- ``default`` -- Gives the default value for the option. +- ``default`` -- gives the default value for the option -- ``description`` -- A one line description of the option. +- ``description`` -- a one line description of the option -- ``link_to`` -- Links this option to another one in another set of +- ``link_to`` -- links this option to another one in another set of global options. This is used for example to allow :class:`Partitions` and :class:`Tableaux` to share the same ``convention`` option. -- ``setter`` -- A function which is called **after** the value of the - option is changed. +- ``setter`` -- a function which is called **after** the value of the + option is changed -- ``values`` -- A dictionary assigning each valid value for the option - to a short description of what it does. +- ``values`` -- dictionary assigning each valid value for the option + to a short description of what it does -- ``case_sensitive`` -- (Default: ``True``) ``True`` or ``False`` depending on - whether the values of the option are case sensitive. +- ``case_sensitive`` -- boolean (default: ``True``); depending on + whether the values of the option are case sensitive For each option, either a complete list of possible values, via ``values``, or a validation function, via ``checker``, must be given. The values can be quite @@ -429,9 +429,9 @@ class options(GlobalOptions): Check that the ``name`` and ``NAME`` keywords are both supported with this syntax:: - sage: GlobalOptions(name="menu") + sage: GlobalOptions(name='menu') Current options for menu - sage: GlobalOptions(NAME="menu") + sage: GlobalOptions(NAME='menu') Current options for menu sage: GlobalOptions() Traceback (most recent call last): @@ -827,7 +827,7 @@ def __call__(self, name, bases, dict): class GlobalOptionsMeta(type, metaclass=GlobalOptionsMetaMeta): """ - Metaclass for :class:`GlobalOptions` + Metaclass for :class:`GlobalOptions`. This class is itself an instance of :class:`GlobalOptionsMetaMeta`, which implements the subclass magic. @@ -871,12 +871,12 @@ class GlobalOptions(metaclass=GlobalOptionsMeta): option in another :class:`GlobalOptions` - ``setter`` -- a function (class method) which is called whenever this option changes - - ``values`` -- a dictionary of the legal values for this option (this + - ``values`` -- dictionary of the legal values for this option (this automatically defines the corresponding ``checker``); this dictionary gives the possible options, as keys, together with a brief description of them - - ``case_sensitive`` -- (default: ``True``) ``True`` or ``False`` - depending on whether the values of the option are case sensitive + - ``case_sensitive`` -- boolean (default: ``True``); depending on whether + the values of the option are case sensitive Options and their values can be abbreviated provided that this abbreviation is a prefix of a unique option. @@ -1026,12 +1026,12 @@ def __init__(self, NAME=None, module='', option_class='', doc='', end_doc='', ** sage: class alias_test(GlobalOptions): ....: "Test aliases with case sensitivity" - ....: test_opt = dict(default="Upper", + ....: test_opt = dict(default='Upper', ....: description = 'Starts with an uppercase', ....: values = dict(Upper="Starts with uppercase", ....: lower="only lowercase"), ....: case_sensitive = False, - ....: alias = dict(UpperAlias="Upper", lower_alias="lower")) + ....: alias = dict(UpperAlias='Upper', lower_alias='lower')) sage: alias_test['test_opt'] = 'Lower_Alias' sage: alias_test['test_opt'] 'lower' @@ -1129,13 +1129,13 @@ def __call__(self, *get_value, **set_value): - food: apple sage: FoodOptions('food') 'apple' - sage: FoodOptions(food="pair"); FoodOptions() + sage: FoodOptions(food='pair'); FoodOptions() Current options for daily meal - drink: water - food: pair sage: FoodOptions('beverage') 'water' - sage: FoodOptions(food="apple", drink="coffee"); FoodOptions() + sage: FoodOptions(food='apple', drink='coffee'); FoodOptions() Current options for daily meal - drink: coffee - food: apple @@ -1237,7 +1237,7 @@ def _instancedoc_(self): sage: print(Partitions.options.__doc__) # needs sage.combinat - Sets and displays the global options for elements of the partition, + Set and display the global options for elements of the partition, skew partition, and partition tuple classes. If no parameters are set, then the function returns a copy of the options dictionary. @@ -1267,7 +1267,7 @@ def _instancedoc_(self): def __setattr__(self, name, value=None): r""" - Set the attribute ``name`` of the option class self equal to + Set the attribute ``name`` of the option class ``self`` equal to ``value``, if the attribute ``name`` exists. As the attributes of an option class are the actual options we need @@ -1330,7 +1330,7 @@ def __setstate__(self, state): for setting in unpickle.__dict__: self.__dict__[setting] = unpickle.__dict__[setting] - # reset the options in `self` to their defaults + # reset the options in ``self`` to their defaults self._reset() # apply the options stored in state for opt in state: @@ -1402,8 +1402,8 @@ def _add_option(self, option, specifications): INPUT: - - ``option`` -- a string - - ``specifications`` -- a dictionary + - ``option`` -- string + - ``specifications`` -- dictionary .. SEEALSO:: @@ -1519,7 +1519,7 @@ def _match_option(self, option): INPUT: - - ``option`` -- a string + - ``option`` -- string EXAMPLES:: @@ -1562,8 +1562,8 @@ def _match_value(self, option, value): INPUT: - - ``option`` -- a string: the name of an option, or prefix thereof - - ``value`` -- a value or ``'?'`` + - ``option`` -- string: the name of an option, or prefix thereof + - ``value`` -- a value or ``'?'`` EXAMPLES:: @@ -1642,8 +1642,6 @@ def _default_value(self, option): def _dispatch(self, obj, dispatch_to, option, *args, **kargs): r""" - .. TODO:: title - The *dispatchable* options are options which dispatch related methods of the corresponding class - or user defined methods which are passed to :class:`GlobalOptions`. The format for specifying a dispatchable option @@ -1701,7 +1699,7 @@ def _reset(self, option=None): INPUT: - - ``option`` -- (Default: ``None``) The name of an option as a string + - ``option`` -- (default: ``None``) the name of an option as a string or ``None``. If ``option`` is specified only this option is reset to its default value; otherwise all options are reset. diff --git a/src/sage/structure/indexed_generators.py b/src/sage/structure/indexed_generators.py index 16349837cd0..c0b7312d9dc 100644 --- a/src/sage/structure/indexed_generators.py +++ b/src/sage/structure/indexed_generators.py @@ -22,11 +22,11 @@ class IndexedGenerators(): Options controlling the printing of elements: - ``prefix`` -- string, prefix used for printing elements of this - module (default: 'x'). With the default, a monomial + module (default: ``'x'``). With the default, a monomial indexed by 'a' would be printed as ``x['a']``. - ``latex_prefix`` -- string or ``None``, prefix used in the `\LaTeX` - representation of elements (default: ``None``). If this is + representation of elements (default: ``None``); if this is anything except the empty string, it prints the index as a subscript. If this is ``None``, it uses the setting for ``prefix``, so if ``prefix`` is set to "B", then a monomial indexed by 'a' @@ -35,16 +35,16 @@ class IndexedGenerators(): would be printed as ``a``, or as ``[a]`` if ``latex_bracket`` is ``True``. - - ``names`` -- dict with strings as values or list of strings (optional): + - ``names`` -- dictionary with strings as values or list of strings (optional); a mapping from the indices of the generators to strings giving the generators explicit names. This is used instead of the print options ``prefix`` and ``bracket`` when ``names`` is specified. - - ``latex_names`` -- dict with strings as values or list of strings - (optional): same as ``names`` except using the `\LaTeX` representation + - ``latex_names`` -- dictionary with strings as values or list of strings + (optional); same as ``names`` except using the `\LaTeX` representation - - ``bracket`` -- ``None``, bool, string, or list or tuple of - strings (default: ``None``): if ``None``, use the value of the + - ``bracket`` -- ``None``, boolean, string, or list or tuple of + strings (default: ``None``); if ``None``, use the value of the attribute ``self._repr_option_bracket``, which has default value ``True``. (``self._repr_option_bracket`` is available for backwards compatibility. Users should set ``bracket`` instead. If @@ -52,15 +52,15 @@ class IndexedGenerators(): the value of ``self._repr_option_bracket``.) If ``False``, do not include brackets when printing elements: a monomial indexed by 'a' would be printed as ``B'a'``, and a monomial indexed by - (1,2,3) would be printed as ``B(1,2,3)``. If True, use "[" and + (1,2,3) would be printed as ``B(1,2,3)``. If ``True``, use "[" and "]" as brackets. If it is one of "[", "(", or "{", use it and its partner as brackets. If it is any other string, use it as both brackets. If it is a list or tuple of strings, use the first entry as the left bracket and the second entry as the right bracket. - - ``latex_bracket`` -- bool, string, or list or tuple of strings - (default: ``False``): if ``False``, do not include brackets in + - ``latex_bracket`` -- boolean, string, or list or tuple of strings + (default: ``False``); if ``False``, do not include brackets in the LaTeX representation of elements. This option is only relevant if ``latex_prefix`` is the empty string; otherwise, brackets are not used regardless. If ``True``, use "\left[" and @@ -72,28 +72,28 @@ class IndexedGenerators(): right bracket. - ``scalar_mult`` -- string to use for scalar multiplication in - the print representation (default: "*") + the print representation (default: ``'*'``) - - ``latex_scalar_mult`` -- string or ``None`` (default: ``None``), + - ``latex_scalar_mult`` -- string or ``None`` (default: ``None``); string to use for scalar multiplication in the latex - representation. If None, use the empty string if ``scalar_mult`` + representation. If ``None``, use the empty string if ``scalar_mult`` is set to "*", otherwise use the value of ``scalar_mult``. - - ``tensor_symbol`` -- string or ``None`` (default: ``None``), + - ``tensor_symbol`` -- string or ``None`` (default: ``None``); string to use for tensor product in the print representation. If ``None``, use ``sage.categories.tensor.symbol`` and ``sage.categories.tensor.unicode_symbol``. - - ``sorting_key`` -- a key function (default: ``lambda x: x``), + - ``sorting_key`` -- a key function (default: ``lambda x: x``); to use for sorting elements in the output of elements - - ``sorting_reverse`` -- bool (default: ``False``), if ``True`` + - ``sorting_reverse`` -- boolean (default: ``False``); if ``True`` sort elements in reverse order in the output of elements - - ``string_quotes`` -- bool (default: ``True``), if ``True`` then + - ``string_quotes`` -- boolean (default: ``True``); if ``True`` then display string indices with quotes - - ``iterate_key`` -- bool (default: ``False``) iterate through + - ``iterate_key`` -- boolean (default: ``False``); iterate through the elements of the key and print the result as comma separated objects for string output @@ -119,7 +119,7 @@ class IndexedGenerators(): sage: I._latex_generator(2) 'x_{2}' - sage: I = IndexedGenerators(ZZ, prefix="", latex_bracket='(') + sage: I = IndexedGenerators(ZZ, prefix='', latex_bracket='(') sage: I._repr_generator(2) '[2]' sage: I._latex_generator(2) @@ -129,7 +129,7 @@ class IndexedGenerators(): sage: I._repr_generator(2) 'x|2>' """ - def __init__(self, indices, prefix="x", **kwds): + def __init__(self, indices, prefix='x', **kwds): """ Initialize ``self``. @@ -182,7 +182,7 @@ def indices(self): def prefix(self): """ - Return the prefix used when displaying elements of self. + Return the prefix used when displaying elements of ``self``. EXAMPLES:: @@ -202,7 +202,9 @@ def print_options(self, **kwds): """ Return the current print options, or set an option. - INPUT: all of the input is optional; if present, it should be + INPUT: + + All of the input is optional; if present, it should be in the form of keyword pairs, such as ``latex_bracket='('``. The allowable keywords are: @@ -358,7 +360,7 @@ def _repr_generator(self, m): B['a'] + 2*B['b'] sage: # needs sage.modules - sage: F = CombinatorialFreeModule(QQ, ['a', 'b', 'c'], prefix="F") + sage: F = CombinatorialFreeModule(QQ, ['a', 'b', 'c'], prefix='F') sage: e = F.basis() sage: e['a'] + 2*e['b'] # indirect doctest F['a'] + 2*F['b'] @@ -367,7 +369,7 @@ def _repr_generator(self, m): F[a] + 2*F[b] sage: # needs sage.modules - sage: F = CombinatorialFreeModule(QQ, ['aa', 'bb', 'cc'], prefix="F") + sage: F = CombinatorialFreeModule(QQ, ['aa', 'bb', 'cc'], prefix='F') sage: e = F.basis() sage: F.print_options(iterate_key=True) sage: e['aa'] + 2*e['bb'] @@ -472,7 +474,7 @@ def _ascii_art_generator(self, m): ** ** * - sage: Partitions.options(diagram_str="#", convention="french") + sage: Partitions.options(diagram_str='#', convention='french') sage: ascii_art(R[1,2,2,4]) R # @@ -564,14 +566,14 @@ def _latex_generator(self, m): sage: latex(e['a'] + 2*e['b']) # indirect doctest # needs sage.modules B_{a} + 2 B_{b} - sage: F = CombinatorialFreeModule(QQ, ['a', 'b', 'c'], prefix="C") # needs sage.modules + sage: F = CombinatorialFreeModule(QQ, ['a', 'b', 'c'], prefix='C') # needs sage.modules sage: e = F.basis() # needs sage.modules sage: latex(e['a'] + 2*e['b']) # indirect doctest # needs sage.modules C_{a} + 2 C_{b} sage: # needs sage.combinat sage.modules sage: QS3 = CombinatorialFreeModule(QQ, Permutations(3), - ....: prefix="", scalar_mult="*") + ....: prefix='', scalar_mult='*') sage: original_print_options = QS3.print_options() sage: a = 2*QS3([1,2,3])+4*QS3([3,2,1]) sage: latex(a) # indirect doctest diff --git a/src/sage/structure/list_clone.pyx b/src/sage/structure/list_clone.pyx index 7363dee36d9..03c0cd23530 100644 --- a/src/sage/structure/list_clone.pyx +++ b/src/sage/structure/list_clone.pyx @@ -157,7 +157,7 @@ from sage.structure.richcmp cimport richcmp, rich_to_bool ############################################################################ cdef class ClonableElement(Element): r""" - Abstract class for elements with clone protocol + Abstract class for elements with clone protocol. This class is a subclass of :class:`Element` and implements the "prototype" design pattern (see [Prototype_pattern]_, [GHJV1994]_). The role @@ -179,7 +179,7 @@ cdef class ClonableElement(Element): Additionally, one can also implement - - ``obj._hash_()`` -- return the hash value of ``obj``. + - ``obj._hash_()`` -- return the hash value of ``obj`` Then, given an instance ``obj`` of ``C``, the following sequences of instructions ensures that the invariants of ``new_obj`` are properly @@ -295,7 +295,7 @@ cdef class ClonableElement(Element): """ Check that ``self`` is mutable. - This raises a :class:`ValueError` if ``self`` is immutable. + Raise a :exc:`ValueError` if ``self`` is immutable. TESTS:: @@ -422,8 +422,8 @@ cdef class ClonableElement(Element): INPUT: - - ``check`` -- a boolean indicating if ``self.check()`` must be called - after modifications. + - ``check`` -- boolean indicating if ``self.check()`` must be called + after modifications EXAMPLES:: @@ -441,7 +441,7 @@ cdef class ClonableElement(Element): def __enter__(self): """ - Implement the self guarding clone protocol. + Implement the ``self`` guarding clone protocol. TESTS:: @@ -455,7 +455,7 @@ cdef class ClonableElement(Element): def __exit__(self, typ, value, tracback): """ - Implement the self guarding clone protocol. + Implement the ``self`` guarding clone protocol. .. NOTE:: The input argument are required by the ``with`` protocol but are ignored. @@ -489,7 +489,7 @@ cdef class ClonableElement(Element): ############################################################################ cdef class ClonableArray(ClonableElement): """ - Array with clone protocol + Array with clone protocol. The class of objects which are :class:`Element` behave as arrays @@ -499,11 +499,11 @@ cdef class ClonableArray(ClonableElement): INPUT: - ``parent`` -- a :class:`Parent` - - ``lst`` -- a list - - ``check`` -- a boolean specifying if the invariant must be checked - using method :meth:`check`. - - ``immutable`` -- a boolean telling whether the created element is - immutable (defaults to ``True``) + - ``lst`` -- list + - ``check`` -- boolean specifying if the invariant must be checked + using method :meth:`check` + - ``immutable`` -- boolean (default: ``True``); whether the created element + is immutable .. SEEALSO:: :class:`~sage.structure.list_clone_demo.IncreasingArray` for an example of usage. @@ -526,7 +526,7 @@ cdef class ClonableArray(ClonableElement): """ def __init__(self, Parent parent, lst, check=True, immutable=True): """ - Initialize ``self`` + Initialize ``self``. TESTS:: @@ -567,7 +567,7 @@ cdef class ClonableArray(ClonableElement): def __bool__(self): """ - Tests if self is not empty. + Test if ``self`` is not empty. EXAMPLES:: @@ -614,7 +614,7 @@ cdef class ClonableArray(ClonableElement): def __len__(self): """ - Return the len of ``self`` + Return the ``len`` of ``self``. EXAMPLES:: @@ -626,7 +626,7 @@ cdef class ClonableArray(ClonableElement): def __getitem__(self, key): """ - Return the ``key``-th element of ``self`` + Return the ``key``-th element of ``self``. It also works with slice returning a python list in this case. @@ -654,7 +654,7 @@ cdef class ClonableArray(ClonableElement): def __setitem__(self, int key, value): """ - Set the ``i``-th element of ``self`` + Set the ``i``-th element of ``self``. An exception is raised if ``self`` is immutable. @@ -679,7 +679,7 @@ cdef class ClonableArray(ClonableElement): cpdef object _getitem(self, int key): """ - Same as :meth:`__getitem__` + Same as :meth:`__getitem__`. This is much faster when used with Cython and ``key`` is known to be an ``int``. @@ -698,7 +698,7 @@ cdef class ClonableArray(ClonableElement): cpdef _setitem(self, int key, value): """ - Same as :meth:`__setitem__` + Same as :meth:`__setitem__`. This is much faster when used with Cython and ``key`` is known to be an ``int``. @@ -848,7 +848,7 @@ cdef class ClonableArray(ClonableElement): cpdef ClonableArray __copy__(self): """ - Return a copy of ``self`` + Return a copy of ``self``. TESTS:: @@ -892,7 +892,7 @@ cdef class ClonableArray(ClonableElement): cpdef check(self): """ - Check that ``self`` fulfill the invariants + Check that ``self`` fulfill the invariants. This is an abstract method. Subclasses are supposed to overload ``check``. @@ -997,7 +997,7 @@ def _make_array_clone(clas, parent, list, needs_check, is_immutable, dic): ############################################################################ cdef class ClonableList(ClonableArray): """ - List with clone protocol + List with clone protocol. The class of objects which are :class:`Element` behave as lists and @@ -1009,9 +1009,11 @@ cdef class ClonableList(ClonableArray): """ cpdef append(self, el): """ - Appends ``el`` to ``self`` + Appends ``el`` to ``self``. + + INPUT: - INPUT: ``el`` -- any object + - ``el`` -- any object EXAMPLES:: @@ -1038,9 +1040,11 @@ cdef class ClonableList(ClonableArray): cpdef extend(self, it): """ - Extends ``self`` by the content of the iterable ``it`` + Extend ``self`` by the content of the iterable ``it``. - INPUT: ``it`` -- any iterable + INPUT: + + - ``it`` -- any iterable EXAMPLES:: @@ -1073,12 +1077,12 @@ cdef class ClonableList(ClonableArray): cpdef insert(self, int index, el): """ - Inserts ``el`` in ``self`` at position ``index`` + Inserts ``el`` in ``self`` at position ``index``. INPUT: - - ``el`` -- any object - - ``index`` -- any int + - ``el`` -- any object + - ``index`` -- any int EXAMPLES:: @@ -1103,9 +1107,11 @@ cdef class ClonableList(ClonableArray): cpdef pop(self, int index=-1): """ - Remove ``self[index]`` from ``self`` and returns it + Remove ``self[index]`` from ``self`` and returns it. - INPUT: ``index`` -- any int, default to -1 + INPUT: + + - ``index`` -- integer (default: -1) EXAMPLES:: @@ -1131,9 +1137,11 @@ cdef class ClonableList(ClonableArray): cpdef remove(self, el): """ - Remove the first occurrence of ``el`` from ``self`` + Remove the first occurrence of ``el`` from ``self``. + + INPUT: - INPUT: ``el`` -- any object + - ``el`` -- any object EXAMPLES:: @@ -1158,7 +1166,7 @@ cdef class ClonableList(ClonableArray): def __setitem__(self, key, value): """ - Set the ith element of ``self`` + Set the i-th element of ``self``. An exception is raised if ``self`` is immutable. @@ -1186,7 +1194,7 @@ cdef class ClonableList(ClonableArray): def __delitem__(self, key): """ - Remove the ith element of ``self`` + Remove the i-th element of ``self``. An exception is raised if ``self`` is immutable. @@ -1216,7 +1224,7 @@ cdef class ClonableList(ClonableArray): ############################################################################ cdef class ClonableIntArray(ClonableElement): """ - Array of int with clone protocol + Array of integers with clone protocol. The class of objects which are :class:`Element` behave as list of int and @@ -1227,11 +1235,11 @@ cdef class ClonableIntArray(ClonableElement): INPUT: - ``parent`` -- a :class:`Parent` - - ``lst`` -- a list - - ``check`` -- a boolean specifying if the invariant must be checked + - ``lst`` -- list + - ``check`` -- boolean specifying if the invariant must be checked using method :meth:`check` - - ``immutable`` -- a boolean telling whether the created element is - immutable (defaults to ``True``) + - ``immutable`` -- boolean (default: ``True``); whether the created element + is immutable .. SEEALSO:: :class:`~sage.structure.list_clone_demo.IncreasingIntArray` for an example of usage. @@ -1242,7 +1250,7 @@ cdef class ClonableIntArray(ClonableElement): def __init__(self, Parent parent, lst, check=True, immutable=True): """ - Initialize ``self`` + Initialize ``self``. TESTS:: @@ -1288,11 +1296,13 @@ cdef class ClonableIntArray(ClonableElement): cpdef _alloc_(self, int size): """ - Allocate the array part of ``self`` for a given size + Allocate the array part of ``self`` for a given size. This can be used to initialize ``self`` without passing a list - INPUT: ``size`` -- an int + INPUT: + + - ``size`` -- integer EXAMPLES:: @@ -1347,7 +1357,7 @@ cdef class ClonableIntArray(ClonableElement): def __len__(self): """ - Return the len of ``self`` + Return the len of ``self``. EXAMPLES:: @@ -1359,7 +1369,7 @@ cdef class ClonableIntArray(ClonableElement): def __iter__(self): """ - Iterate over the items of self. + Iterate over the items of ``self``. EXAMPLES:: @@ -1374,7 +1384,7 @@ cdef class ClonableIntArray(ClonableElement): cpdef list list(self): """ - Convert self into a Python list. + Convert ``self`` into a Python list. EXAMPLES:: @@ -1399,7 +1409,7 @@ cdef class ClonableIntArray(ClonableElement): def __getitem__(self, key): """ - Return the ith element of ``self`` + Return the i-th element of ``self``. EXAMPLES:: @@ -1448,7 +1458,7 @@ cdef class ClonableIntArray(ClonableElement): def __setitem__(self, int key, value): """ - Set the ith element of ``self`` + Set the i-th element of ``self``. An exception is raised if ``self`` is immutable. @@ -1472,7 +1482,7 @@ cdef class ClonableIntArray(ClonableElement): cpdef object _getitem(self, int key): """ - Same as :meth:`__getitem__` + Same as :meth:`__getitem__`. This is much faster when used with Cython and the index is known to be an int. @@ -1490,7 +1500,7 @@ cdef class ClonableIntArray(ClonableElement): cpdef _setitem(self, int key, value): """ - Same as :meth:`__setitem__` + Same as :meth:`__setitem__`. This is much faster when used with Cython and the index is known to be an int. @@ -1626,7 +1636,7 @@ cdef class ClonableIntArray(ClonableElement): cpdef ClonableIntArray __copy__(self): """ - Return a copy of ``self`` + Return a copy of ``self``. TESTS:: @@ -1673,7 +1683,7 @@ cdef class ClonableIntArray(ClonableElement): cpdef check(self): """ - Check that ``self`` fulfill the invariants + Check that ``self`` fulfill the invariants. This is an abstract method. Subclasses are supposed to overload ``check``. @@ -1777,7 +1787,7 @@ def _make_int_array_clone(clas, parent, lst, needs_check, is_immutable, dic): cdef class NormalizedClonableList(ClonableList): """ - List with clone protocol and normal form + List with clone protocol and normal form. This is a subclass of :class:`ClonableList` which call a method :meth:`normalize` at creation and after any modification of its instance. @@ -1834,7 +1844,7 @@ cdef class NormalizedClonableList(ClonableList): cpdef normalize(self): """ - Normalize ``self`` + Normalize ``self``. This is an abstract method. Subclasses are supposed to overload :meth:`normalize`. The call ``self.normalize()`` is supposed to diff --git a/src/sage/structure/list_clone_demo.pyx b/src/sage/structure/list_clone_demo.pyx index 4899bcf5cc2..dbd199fa317 100644 --- a/src/sage/structure/list_clone_demo.pyx +++ b/src/sage/structure/list_clone_demo.pyx @@ -116,7 +116,7 @@ cdef class IncreasingList(ClonableList): cpdef check(self): """ - Check that ``self`` is increasing + Check that ``self`` is increasing. EXAMPLES:: @@ -195,7 +195,7 @@ cdef class SortedList(NormalizedClonableList): """ cpdef normalize(self): """ - Normalize ``self`` + Normalize ``self``. Sort the list stored in ``self``. @@ -215,7 +215,7 @@ cdef class SortedList(NormalizedClonableList): cpdef check(self): """ - Check that ``self`` is strictly increasing + Check that ``self`` is strictly increasing. EXAMPLES:: diff --git a/src/sage/structure/list_clone_timings.py b/src/sage/structure/list_clone_timings.py index 05320d6bc77..f91eaab558b 100644 --- a/src/sage/structure/list_clone_timings.py +++ b/src/sage/structure/list_clone_timings.py @@ -88,7 +88,7 @@ class IncreasingArraysPy(IncreasingArrays): class Element(ClonableArray): """ - A small class for testing :class:`ClonableArray`: Increasing Lists + A small class for testing :class:`ClonableArray`: Increasing Lists. TESTS:: diff --git a/src/sage/structure/mutability.pyx b/src/sage/structure/mutability.pyx index db6a331fa4c..69d034bd8c3 100644 --- a/src/sage/structure/mutability.pyx +++ b/src/sage/structure/mutability.pyx @@ -45,7 +45,6 @@ cdef class Mutability: ValueError: object is immutable; please change a copy instead sage: hash(a) 6 - """ def __init__(self, is_immutable=False): @@ -62,8 +61,7 @@ cdef class Mutability: ....: self._require_immutable() ....: return hash(self._val) sage: a = A(4) - sage: TestSuite(a).run(skip ="_test_pickling") - + sage: TestSuite(a).run(skip ='_test_pickling') """ self._is_immutable = is_immutable @@ -88,7 +86,6 @@ cdef class Mutability: Traceback (most recent call last): ... ValueError: object is immutable; please change a copy instead - """ if self._is_immutable: raise ValueError("object is immutable; please change a copy instead") @@ -113,7 +110,6 @@ cdef class Mutability: Traceback (most recent call last): ... ValueError: object is mutable; please make it immutable first - """ if not self._is_immutable: raise ValueError("object is mutable; please make it immutable first") @@ -204,7 +200,6 @@ cdef class Mutability: , ), {'_is_immutable': False, '_val': 4}) - """ state = getattr(self, '__dict__', {}) state['_is_immutable'] = self._is_immutable @@ -237,7 +232,6 @@ cdef class Mutability: True sage: a.__getstate__() {'_is_immutable': True, '_val': 4} - """ if hasattr(self, '__dict__'): self.__dict__ = state diff --git a/src/sage/structure/nonexact.py b/src/sage/structure/nonexact.py index cef7a641f26..8bde0763a9e 100644 --- a/src/sage/structure/nonexact.py +++ b/src/sage/structure/nonexact.py @@ -37,12 +37,12 @@ class Nonexact: INPUT: - - ``prec`` -- a non-negative integer representing the default precision of - ``self`` (default: ``20``) + - ``prec`` -- nonnegative integer representing the default precision of + ``self`` (default: 20) """ def __init__(self, prec=20): if prec < 0: - raise ValueError(f"prec (= {prec}) must be non-negative") + raise ValueError(f"prec (= {prec}) must be nonnegative") self._default_prec = Integer(prec) def default_prec(self): diff --git a/src/sage/structure/parent.pyx b/src/sage/structure/parent.pyx index db6e01de40a..44c23ff8fb0 100644 --- a/src/sage/structure/parent.pyx +++ b/src/sage/structure/parent.pyx @@ -222,25 +222,22 @@ cdef class Parent(sage.structure.category_object.CategoryObject): INPUT: - - ``base`` -- An algebraic structure considered to be the - "base" of this parent (e.g. the base field for a vector - space). - - - ``category`` -- a category or list/tuple of categories. The - category in which this parent lies (or list or tuple - thereof). Since categories support more general - super-categories, this should be the most specific category - possible. If category is a list or tuple, a JoinCategory is - created out of them. If category is not specified, the - category will be guessed (see - :class:`~sage.structure.category_object.CategoryObject`), - but will not be used to inherit parent's or element's code from - this category. - - - ``names`` -- Names of generators. - - - ``normalize`` -- Whether to standardize the names (remove - punctuation, etc) + - ``base`` -- an algebraic structure considered to be the "base" of + this parent (e.g. the base field for a vector space) + + - ``category`` -- a category or list/tuple of categories. The category + in which this parent lies (or list or tuple thereof). Since + categories support more general super-categories, this should be the + most specific category possible. If category is a list or tuple, a + ``JoinCategory`` is created out of them. If category is not + specified, the category will be guessed (see + :class:`~sage.structure.category_object.CategoryObject`), but will + not be used to inherit parent's or element's code from this category. + + - ``names`` -- names of generators + + - ``normalize`` -- whether to standardize the names (remove + punctuation, etc.) - ``facade`` -- a parent, or tuple thereof, or ``True`` @@ -411,7 +408,6 @@ cdef class Parent(sage.structure.category_object.CategoryObject): True sage: hash(a) != h_a True - """ cdef Py_hash_t hash_old = -1 if debug.refine_category_hash_check: @@ -506,7 +502,6 @@ cdef class Parent(sage.structure.category_object.CategoryObject): sage: P._init_category_(Rings()) sage: type(P) == C True - """ self._category = None if can_assign_class(self): @@ -541,7 +536,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): @lazy_attribute def element_class(self): """ - The (default) class for the elements of this parent + The (default) class for the elements of this parent. FIXME's and design issues: @@ -565,7 +560,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): It used to be the case that this did not work for extension types, which used to never support a ``__dict__`` for instances. So for backwards compatibility, we only use dynamic classes by - default if the class has a non-zero ``__dictoffset__``. But it + default if the class has a nonzero ``__dictoffset__``. But it works regardless: just pass ``inherit=True`` to ``__make_element_class__``. See also :issue:`24715`. @@ -812,8 +807,8 @@ cdef class Parent(sage.structure.category_object.CategoryObject): INPUT: - - ``key`` -- string. A key for different metadata informations - that can be inquired about. + - ``key`` -- string; a key for different metadata informations + that can be inquired about Valid ``key`` arguments are: @@ -828,9 +823,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): is, parenthesis are not required when *printing* out any of `x - y`, `x + y`, `x^y` and `x/y`. - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -979,7 +972,6 @@ cdef class Parent(sage.structure.category_object.CategoryObject): [0 2] ) of Full MatrixSpace of 2 by 2 dense matrices over Rational Field - """ # generic multiplication method. It defers to # _mul_, which may be defined via categories. @@ -1067,12 +1059,13 @@ cdef class Parent(sage.structure.category_object.CategoryObject): ############################################################################# def __contains__(self, x): r""" - True if there is an element of self that is equal to x under - ==, or if x is already an element of self. Also, True in other - cases involving the Symbolic Ring, which is handled specially. + ``True`` if there is an element of ``self`` that is equal to ``x`` + under ``==``, or if ``x`` is already an element of ``self``. Also, + ``True`` in other cases involving the Symbolic Ring, which is handled + specially. For many structures we test this by using :meth:`__call__` and - then testing equality between x and the result. + then testing equality between ``x`` and the result. The Symbolic Ring is treated differently because it is ultra-permissive about letting other rings coerce in, but @@ -1197,8 +1190,8 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef coerce(self, x): """ - Return x as an element of self, if and only if there is a canonical - coercion from the parent of x to self. + Return x as an element of ``self``, if and only if there is a + canonical coercion from the parent of x to ``self``. EXAMPLES:: @@ -1245,8 +1238,8 @@ cdef class Parent(sage.structure.category_object.CategoryObject): # Should be moved and merged into the EnumeratedSets() category (#12955) def __getitem__(self, n): """ - Returns the `n^{th}` item or slice `n` of self, - by getting self as a list. + Return the `n`-th item or slice `n` of ``self``, + by getting ``self`` as a list. EXAMPLES:: @@ -1295,12 +1288,12 @@ cdef class Parent(sage.structure.category_object.CategoryObject): def _is_valid_homomorphism_(self, codomain, im_gens, base_map=None): r""" - Return True if ``im_gens`` defines a valid homomorphism - from self to codomain; otherwise return False. + Return ``True`` if ``im_gens`` defines a valid homomorphism + from ``self`` to ``codomain``; otherwise return ``False``. If determining whether or not a homomorphism is valid has not - been implemented for this ring, then a NotImplementedError exception - is raised. + been implemented for this ring, then a :exc:`NotImplementedError` + exception is raised. """ raise NotImplementedError("Verification of correctness of homomorphisms from %s not yet implemented." % self) @@ -1349,10 +1342,10 @@ cdef class Parent(sage.structure.category_object.CategoryObject): def hom(self, im_gens, codomain=None, check=None, base_map=None, category=None, **kwds): r""" - Return the unique homomorphism from self to codomain that + Return the unique homomorphism from ``self`` to ``codomain`` that sends ``self.gens()`` to the entries of ``im_gens``. - This raises a :class:`TypeError` if there is no such homomorphism. + This raises a :exc:`TypeError` if there is no such homomorphism. INPUT: @@ -1361,15 +1354,13 @@ cdef class Parent(sage.structure.category_object.CategoryObject): - ``codomain`` -- the codomain of the homomorphism - - ``base_map`` -- a map from the base ring to the codomain. - If not given, coercion is used. + - ``base_map`` -- a map from the base ring to the codomain; if not + given, coercion is used - ``check`` -- whether to verify that the images of generators - extend to define a map (using only canonical coercions). + extend to define a map (using only canonical coercions) - OUTPUT: - - A homomorphism self --> codomain + OUTPUT: a homomorphism ``self --> codomain`` .. NOTE:: @@ -1418,7 +1409,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): To: Finite Field of size 5 There might not be a natural morphism, in which case a - :class:`TypeError` is raised:: + :exc:`TypeError` is raised:: sage: QQ.hom(ZZ) Traceback (most recent call last): @@ -1466,24 +1457,23 @@ cdef class Parent(sage.structure.category_object.CategoryObject): INPUT: - - ``coerce_list`` -- a list of coercion Morphisms to self and - parents with canonical coercions to self + - ``coerce_list`` -- list of coercion Morphisms to ``self`` and + parents with canonical coercions to ``self`` - - ``action_list`` -- a list of actions on and by self + - ``action_list`` -- list of actions on and by ``self`` - - ``convert_list`` -- a list of conversion Maps to self and - parents with conversions to self + - ``convert_list`` -- list of conversion Maps to ``self`` and + parents with conversions to ``self`` - - ``embedding`` -- a single Morphism from self + - ``embedding`` -- a single Morphism from ``self`` - ``convert_method_name`` -- a name to look for that other elements - can implement to create elements of self (e.g. _integer_) + can implement to create elements of ``self`` (e.g. ``_integer_``) - - ``init_no_parent`` -- if True omit passing self in as the + - ``init_no_parent`` -- if ``True`` omit passing ``self`` in as the first argument of element_constructor for conversion. This is useful if parents are unique, or element_constructor is a - bound method (this latter case can be detected - automatically). + bound method (this latter case can be detected automatically). """ self.init_coerce(False) @@ -1585,7 +1575,8 @@ cdef class Parent(sage.structure.category_object.CategoryObject): def _remove_from_coerce_cache(self, domain): r""" - Remove the coercion and the conversion from ``domain`` to self from the cache. + Remove the coercion and the conversion from ``domain`` to ``self`` from + the cache. EXAMPLES:: @@ -1673,7 +1664,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef register_action(self, action): r""" - Update the coercion model to use ``action`` to act on self. + Update the coercion model to use ``action`` to act on ``self``. ``action`` should be of type ``sage.categories.action.Action``. @@ -1909,7 +1900,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef _generic_coerce_map(self, S): r""" - Returns a default coercion map based on the data provided to + Return a default coercion map based on the data provided to :meth:`_populate_coercion_lists_`. This method differs from :meth:`_generic_convert_map` only in setting @@ -1940,7 +1931,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef _generic_convert_map(self, S, category=None): r""" - Returns the default conversion map based on the data provided to + Return the default conversion map based on the data provided to :meth:`_populate_coercion_lists_`. This is called when :meth:`_coerce_map_from_` returns ``True``. @@ -2014,18 +2005,18 @@ cdef class Parent(sage.structure.category_object.CategoryObject): def _coerce_map_via(self, v, S): """ - This attempts to construct a morphism from S to self by passing through - one of the items in v (tried in order). + This attempts to construct a morphism from ``S`` to ``self`` by passing + through one of the items in ``v`` (tried in order). - S may appear in the list, in which case algorithm will never progress - beyond that point. + ``S`` may appear in the list, in which case algorithm will never + progress beyond that point. - This is useful when defining _coerce_map_from_. + This is useful when defining ``_coerce_map_from_``. INPUT: - - ``v`` -- A list (iterator) of parents with coercions into self. There - MUST be maps provided from each item in the list to self. + - ``v`` -- list (iterator) of parents with coercions into ``self``; + there *must* be maps provided from each item in the list to ``self`` - ``S`` -- the starting parent @@ -2100,11 +2091,11 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef _coerce_map_from_(self, S): """ Override this method to specify coercions beyond those specified - in coerce_list. + in ``coerce_list``. - If no such coercion exists, return None or False. Otherwise, it may - return either an actual Map to use for the coercion, a callable - (in which case it will be wrapped in a Map), or True (in which case + If no such coercion exists, return ``None`` or ``False``. Otherwise, it + may return either an actual Map to use for the coercion, a callable + (in which case it will be wrapped in a Map), or ``True`` (in which case a generic map will be provided). """ try: @@ -2276,11 +2267,11 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cdef discover_coerce_map_from(self, S): """ - Precedence for discovering a coercion S -> self goes as follows: + Precedence for discovering a coercion ``S -> self`` goes as follows: - 1. If S has an embedding into self, return that embedding. + 1. If ``S`` has an embedding into ``self``, return that embedding. - 2. If self._coerce_map_from_(S) is NOT exactly one of + 2. If ``self._coerce_map_from_(S)`` is not exactly one of - DefaultConvertMap - DefaultConvertMap_unique @@ -2291,8 +2282,8 @@ cdef class Parent(sage.structure.category_object.CategoryObject): 3. Traverse the coercion lists looking for another map returning the map from step (2) if none is found. - 4. If S has an embedding into some parent T, look for T -> self and - return composition. + 4. If ``S`` has an embedding into some parent ``T``, look for + ``T -> self`` and return composition. In the future, multiple paths may be discovered and compared. @@ -2453,14 +2444,14 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef convert_map_from(self, S): """ - This function returns a :class:`Map` from `S` to `self`, + This function returns a :class:`Map` from `S` to ``self``, which may or may not succeed on all inputs. - If a coercion map from S to self exists, - then the it will be returned. If a coercion from `self` to `S` exists, + If a coercion map from S to ``self`` exists, + then the it will be returned. If a coercion from ``self`` to `S` exists, then it will attempt to return a section of that map. Under the new coercion model, this is the fastest way to convert - elements of `S` to elements of `self` (short of manually constructing + elements of `S` to elements of ``self`` (short of manually constructing the elements) and is used by :meth:`__call__`. EXAMPLES:: @@ -2479,14 +2470,14 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef _internal_convert_map_from(self, S): """ - This function returns a :class:`Map` from `S` to `self`, + This function returns a :class:`Map` from `S` to ``self``, which may or may not succeed on all inputs. - If a coercion map from S to self exists, - then the it will be returned. If a coercion from `self` to `S` exists, + If a coercion map from S to ``self`` exists, + then the it will be returned. If a coercion from ``self`` to `S` exists, then it will attempt to return a section of that map. Under the new coercion model, this is the fastest way to convert - elements of `S` to elements of `self` (short of manually constructing + elements of `S` to elements of ``self`` (short of manually constructing the elements) and is used by :func:`__call__`. EXAMPLES:: @@ -2554,20 +2545,20 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef _convert_map_from_(self, S): """ Override this method to provide additional conversions beyond those - given in convert_list. + given in ``convert_list``. This function is called after coercions are attempted. If there is a coercion morphism in the opposite direction, one should consider adding a section method to that. - This MUST return a Map from S to self, or None. If None is returned - then a generic map will be provided. + This MUST return a Map from ``S`` to ``self``, or ``None``. If ``None`` + is returned then a generic map will be provided. """ return None cpdef get_action(self, S, op=operator.mul, bint self_on_left=True, self_el=None, S_el=None): """ - Returns an action of self on S or S on self. + Return an action of ``self`` on ``S`` or ``S`` on ``self``. To provide additional actions, override :meth:`_get_action_`. @@ -2759,11 +2750,11 @@ cdef class Parent(sage.structure.category_object.CategoryObject): cpdef _get_action_(self, S, op, bint self_on_left): """ - Override this method to provide an action of self on S or S on self - beyond what was specified in action_list. + Override this method to provide an action of ``self`` on ``S`` or ``S`` + on ``self`` beyond what was specified in ``action_list``. - This must return an action which accepts an element of self and an - element of S (in the order specified by self_on_left). + This must return an action which accepts an element of ``self`` and an + element of ``S`` (in the order specified by ``self_on_left``). """ return None @@ -2771,11 +2762,11 @@ cdef class Parent(sage.structure.category_object.CategoryObject): # Sets().ParentMethods.an_element cpdef an_element(self): r""" - Returns a (preferably typical) element of this parent. + Return a (preferably typical) element of this parent. This is used both for illustration and testing purposes. If the set ``self`` is empty, :meth:`an_element` raises the - exception :class:`EmptySetError`. + exception :exc:`EmptySetError`. This calls :meth:`_an_element_` (which see), and caches the result. Parent are thus encouraged to override :meth:`_an_element_`. @@ -2787,7 +2778,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): sage: ZZ[['t']].an_element() t - In case the set is empty, an :class:`EmptySetError` is raised:: + In case the set is empty, an :exc:`EmptySetError` is raised:: sage: Set([]).an_element() Traceback (most recent call last): @@ -2880,7 +2871,7 @@ cdef class Parent(sage.structure.category_object.CategoryObject): OUTPUT: - Return True if elements of this ring are represented exactly, i.e., + Return ``True`` if elements of this ring are represented exactly, i.e., there is no precision loss when doing arithmetic. EXAMPLES:: @@ -2986,7 +2977,6 @@ cdef class Set_generic(Parent): sage: Set(QQ).category() Category of infinite sets - """ def object(self): """ @@ -3001,8 +2991,8 @@ cdef class Set_generic(Parent): def __bool__(self): """ - A set is considered True unless it is empty, in which case it is - considered to be False. + A set is considered ``True`` unless it is empty, in which case it is + considered to be ``False``. EXAMPLES:: diff --git a/src/sage/structure/parent_gens.pyx b/src/sage/structure/parent_gens.pyx index 6f12c36670f..b27002d1254 100644 --- a/src/sage/structure/parent_gens.pyx +++ b/src/sage/structure/parent_gens.pyx @@ -11,7 +11,7 @@ Base class for old-style parent objects with generators Many parent objects in Sage are equipped with generators, which are special elements of the object. For example, the polynomial ring -`\ZZ[x,y,z]` is generated by `x`, `y`, and `z`. In Sage the `i^{th}` +`\ZZ[x,y,z]` is generated by `x`, `y`, and `z`. In Sage the `i`-th generator of an object ``X`` is obtained using the notation ``X.gen(i)``. From the Sage interactive prompt, the shorthand notation ``X.i`` is also allowed. @@ -127,7 +127,6 @@ cdef class ParentWithGens(ParentWithBase): This can only be done once because objects with generators are immutable, and is typically done during creation of the object. - EXAMPLES: When we create this polynomial ring, self._assign_names is called by the constructor: @@ -204,7 +203,7 @@ cdef class ParentWithGens(ParentWithBase): sends ``self.gens()`` to the entries of ``im_gens`` and induces the map ``base_map`` on the base ring. - This raises a :class:`TypeError` if there is no such homomorphism. + This raises a :exc:`TypeError` if there is no such homomorphism. INPUT: @@ -221,9 +220,7 @@ cdef class ParentWithGens(ParentWithBase): - ``check`` -- whether to verify that the images of generators extend to define a map (using only canonical coercions) - OUTPUT: - - - a homomorphism self --> codomain + OUTPUT: a homomorphism ``self --> codomain`` .. NOTE:: @@ -275,7 +272,7 @@ cdef class ParentWithGens(ParentWithBase): To: Finite Field of size 5 There might not be a natural morphism, in which case a - :class:`TypeError` exception is raised. + :exc:`TypeError` exception is raised. :: diff --git a/src/sage/structure/parent_old.pyx b/src/sage/structure/parent_old.pyx index a34928ff8a2..202e8247fe1 100644 --- a/src/sage/structure/parent_old.pyx +++ b/src/sage/structure/parent_old.pyx @@ -203,16 +203,16 @@ cdef class Parent(parent.Parent): cdef _coerce_c_impl(self, x): # OVERRIDE THIS FOR CYTHON CLASSES """ - Canonically coerce x in assuming that the parent of x is not - equal to self. + Canonically coerce ``x`` in assuming that the parent of ``x`` is not + equal to ``self``. """ check_old_coerce(self) raise TypeError def _coerce_impl(self, x): # OVERRIDE THIS FOR PYTHON CLASSES """ - Canonically coerce x in assuming that the parent of x is not - equal to self. + Canonically coerce ``x`` in assuming that the parent of ``x`` is not + equal to ``self``. """ check_old_coerce(self) return self._coerce_c_impl(x) diff --git a/src/sage/structure/proof/all.py b/src/sage/structure/proof/all.py index d3a72dc1400..0db573b93ce 100644 --- a/src/sage/structure/proof/all.py +++ b/src/sage/structure/proof/all.py @@ -8,7 +8,7 @@ def arithmetic(t=None): INPUT: - t -- boolean or ``None`` + - ``t`` -- boolean or ``None`` OUTPUT: @@ -46,7 +46,7 @@ def elliptic_curve(t=None): INPUT: - t -- boolean or ``None`` + - ``t`` -- boolean or ``None`` OUTPUT: @@ -84,7 +84,7 @@ def linear_algebra(t=None): INPUT: - t -- boolean or ``None`` + - ``t`` -- boolean or ``None`` OUTPUT: @@ -122,7 +122,7 @@ def number_field(t=None): INPUT: - t -- boolean or ``None`` + - ``t`` -- boolean or ``None`` OUTPUT: @@ -159,7 +159,7 @@ def polynomial(t=None): INPUT: - t -- boolean or ``None`` + - ``t`` -- boolean or ``None`` OUTPUT: @@ -196,7 +196,7 @@ def all(t=None): INPUT: - t -- boolean or ``None`` + - ``t`` -- boolean or ``None`` OUTPUT: diff --git a/src/sage/structure/proof/proof.py b/src/sage/structure/proof/proof.py index 4a459551837..6da86141cc6 100644 --- a/src/sage/structure/proof/proof.py +++ b/src/sage/structure/proof/proof.py @@ -5,9 +5,17 @@ class _ProofPref(SageObject): """ - An object that holds global proof preferences. For now these are merely True/False flags for various parts of Sage that use probabilistic algorithms. - A True flag means that the subsystem (such as linear algebra or number fields) should return results that are true unconditionally: the correctness should not depend on an algorithm with a nonzero probability of returning an incorrect answer or on the truth of any unproven conjectures. - A False flag means that the subsystem can use faster methods to return answers that have a very small probability of being wrong. + An object that holds global proof preferences. For now these are merely + boolean flags for various parts of Sage that use probabilistic + algorithms. + + A ``True`` flag means that the subsystem (such as linear algebra or number + fields) should return results that are true unconditionally: the + correctness should not depend on an algorithm with a nonzero probability of + returning an incorrect answer or on the truth of any unproven conjectures. + + A ``False`` flag means that the subsystem can use faster methods to return + answers that have a very small probability of being wrong. """ def __init__(self, proof=True): self._require_proof = {} @@ -24,13 +32,20 @@ def arithmetic(self, t=None): INPUT: - t -- boolean or None + - ``t`` -- boolean or ``None`` OUTPUT: - If t == True, requires integer arithmetic operations to (by default) return results that are true unconditionally: the correctness will not depend on an algorithm with a nonzero probability of returning an incorrect answer or on the truth of any unproven conjectures. - If t == False, allows integer arithmetic operations to (by default) return results that may depend on unproven conjectures or on probabilistic algorithms. Such algorithms often have a substantial speed improvement over those requiring proof. - If t is None, returns the integer arithmetic proof status. + - if ``t == True``, requires integer arithmetic operations to (by + default) return results that are true unconditionally: the + correctness will not depend on an algorithm with a nonzero + probability of returning an incorrect answer or on the truth of any + unproven conjectures. + - if ``t == False``, allows integer arithmetic operations to (by + default) return results that may depend on unproven conjectures or on + probabilistic algorithms. Such algorithms often have a substantial + speed improvement over those requiring proof. + - if ``t == None``, returns the integer arithmetic proof status. EXAMPLES:: @@ -53,13 +68,19 @@ def elliptic_curve(self, t=None): INPUT: - t -- boolean or None + - ``t`` -- boolean or ``None`` OUTPUT: - If t == True, requires elliptic curve algorithms to (by default) return results that are true unconditionally: the correctness will not depend on an algorithm with a nonzero probability of returning an incorrect answer or on the truth of any unproven conjectures. - If t == False, allows elliptic curve algorithms to (by default) return results that may depend on unproven conjectures or on probabilistic algorithms. Such algorithms often have a substantial speed improvement over those requiring proof. - If t is None, returns the current elliptic curve proof status. + - if ``t == True``, requires elliptic curve algorithms to (by default) + return results that are true unconditionally: the correctness will + not depend on an algorithm with a nonzero probability of returning an + incorrect answer or on the truth of any unproven conjectures. + - if ``t == False``, allows elliptic curve algorithms to (by default) + return results that may depend on unproven conjectures or on + probabilistic algorithms. Such algorithms often have a substantial + speed improvement over those requiring proof. + - if ``t == None``, returns the current elliptic curve proof status. EXAMPLES:: @@ -82,13 +103,19 @@ def linear_algebra(self, t=None): INPUT: - t -- boolean or None + - ``t`` -- boolean or ``None`` OUTPUT: - If t == True, requires linear algebra algorithms to (by default) return results that are true unconditionally: the correctness will not depend on an algorithm with a nonzero probability of returning an incorrect answer or on the truth of any unproven conjectures. - If t == False, allows linear algebra algorithms to (by default) return results that may depend on unproven conjectures or on probabilistic algorithms. Such algorithms often have a substantial speed improvement over those requiring proof. - If t is None, returns the current linear algebra proof status. + - if ``t == True``, requires linear algebra algorithms to (by default) + return results that are true unconditionally: the correctness will + not depend on an algorithm with a nonzero probability of returning an + incorrect answer or on the truth of any unproven conjectures. + - if ``t == False``, allows linear algebra algorithms to (by default) + return results that may depend on unproven conjectures or on + probabilistic algorithms. Such algorithms often have a substantial + speed improvement over those requiring proof. + - if ``t == None``, returns the current linear algebra proof status. EXAMPLES:: @@ -111,13 +138,19 @@ def number_field(self, t=None): INPUT: - t -- boolean or None + - ``t`` -- boolean or ``None`` OUTPUT: - If t == True, requires number field algorithms to (by default) return results that are true unconditionally: the correctness will not depend on an algorithm with a nonzero probability of returning an incorrect answer or on the truth of any unproven conjectures. - If t == False, allows number field algorithms to (by default) return results that may depend on unproven conjectures or on probabilistic algorithms. Such algorithms often have a substantial speed improvement over those requiring proof. - If t is None, returns the current number field proof status. + - if ``t == True``, requires number field algorithms to (by default) + return results that are true unconditionally: the correctness will + not depend on an algorithm with a nonzero probability of returning an + incorrect answer or on the truth of any unproven conjectures. + - if ``t == False``, allows number field algorithms to (by default) + return results that may depend on unproven conjectures or on + probabilistic algorithms. Such algorithms often have a substantial + speed improvement over those requiring proof. + - if ``t == None``, returns the current number field proof status. EXAMPLES:: @@ -140,13 +173,19 @@ def polynomial(self, t=None): INPUT: - t -- boolean or None + - ``t`` -- boolean or ``None`` OUTPUT: - If t == True, requires polynomial algorithms to (by default) return results that are true unconditionally: the correctness will not depend on an algorithm with a nonzero probability of returning an incorrect answer or on the truth of any unproven conjectures. - If t == False, allows polynomial algorithms to (by default) return results that may depend on unproven conjectures or on probabilistic algorithms. Such algorithms often have a substantial speed improvement over those requiring proof. - If t is None, returns the current polynomial proof status. + - if ``t == True``, requires polynomial algorithms to (by default) + return results that are true unconditionally: the correctness will + not depend on an algorithm with a nonzero probability of returning an + incorrect answer or on the truth of any unproven conjectures. + - if ``t == False``, allows polynomial algorithms to (by default) + return results that may depend on unproven conjectures or on + probabilistic algorithms. Such algorithms often have a substantial + speed improvement over those requiring proof. + - if ``t == None``, returns the current polynomial proof status. EXAMPLES:: diff --git a/src/sage/structure/richcmp.pxd b/src/sage/structure/richcmp.pxd index ecbeaef391e..1ff9c16dee0 100644 --- a/src/sage/structure/richcmp.pxd +++ b/src/sage/structure/richcmp.pxd @@ -13,8 +13,8 @@ cpdef inline richcmp(x, y, int op): - ``x``, ``y`` -- arbitrary Python objects - - ``op`` -- comparison operator (one of ``op_LT`, ``op_LE``, - ``op_EQ``, ``op_NE``, ``op_GT``, ``op_GE``). + - ``op`` -- comparison operator (one of ``op_LT``, ``op_LE``, + ``op_EQ``, ``op_NE``, ``op_GT``, ``op_GE``) EXAMPLES:: @@ -127,7 +127,7 @@ cpdef inline bint rich_to_bool(int op, int c) noexcept: - ``op`` -- a rich comparison operation (e.g. ``Py_EQ``) - - ``c`` -- the result of an old-style comparison: -1, 0 or 1. + - ``c`` -- the result of an old-style comparison: -1, 0 or 1 OUTPUT: 1 or 0 (corresponding to ``True`` and ``False``) diff --git a/src/sage/structure/richcmp.pyx b/src/sage/structure/richcmp.pyx index 934a49e7600..d3e8cb3e41d 100644 --- a/src/sage/structure/richcmp.pyx +++ b/src/sage/structure/richcmp.pyx @@ -78,15 +78,13 @@ cpdef richcmp_item(x, y, int op): INPUT: - - ``x``, ``y`` -- arbitrary Python objects. Typically, these are - ``X[i]`` and ``Y[i]`` for sequences ``X`` and ``Y``. + - ``x``, ``y`` -- arbitrary Python objects; typically, these are + ``X[i]`` and ``Y[i]`` for sequences ``X`` and ``Y`` - - ``op`` -- comparison operator (one of ``op_LT`, ``op_LE``, + - ``op`` -- comparison operator (one of ``op_LT``, ``op_LE``, ``op_EQ``, ``op_NE``, ``op_GT``, ``op_GE``) - OUTPUT: - - Assuming that ``x = X[i]`` and ``y = Y[i]``: + OUTPUT: assuming that ``x = X[i]`` and ``y = Y[i]``: - if the comparison ``X {op} Y`` (where ``op`` is the given operation) could not be decided yet (i.e. we should compare the diff --git a/src/sage/structure/sage_object.pyx b/src/sage/structure/sage_object.pyx index 4c4bd56678e..fb6d4d0f686 100644 --- a/src/sage/structure/sage_object.pyx +++ b/src/sage/structure/sage_object.pyx @@ -67,7 +67,7 @@ cdef class SageObject: def rename(self, x=None): r""" - Change self so it prints as x, where x is a string. + Change ``self`` so it prints as x, where x is a string. If x is ``None``, the existing custom name is removed. @@ -362,7 +362,7 @@ cdef class SageObject: def __hash__(self): r""" - Not implemented: mutable objects inherit from this class + Not implemented: mutable objects inherit from this class. EXAMPLES:: @@ -431,7 +431,6 @@ cdef class SageObject: sage: d = a + O(2) # needs sage.rings.padics sage: b._cache_key() == d._cache_key() # this would be True if the parents were not included # needs sage.rings.padics False - """ try: hash(self) @@ -446,7 +445,7 @@ cdef class SageObject: def save(self, filename=None, compress=True): """ - Save self to the given filename. + Save ``self`` to the given filename. EXAMPLES:: @@ -454,7 +453,7 @@ cdef class SageObject: sage: x = SR.var("x") sage: f = x^3 + 5 sage: from tempfile import NamedTemporaryFile - sage: with NamedTemporaryFile(suffix=".sobj") as t: + sage: with NamedTemporaryFile(suffix='.sobj') as t: ....: f.save(t.name) ....: load(t.name) x^3 + 5 @@ -606,7 +605,7 @@ cdef class SageObject: def _test_not_implemented_methods(self, **options): """ - Checks that all required methods for this object are implemented + Check that all required methods for this object are implemented. TESTS:: @@ -653,7 +652,7 @@ cdef class SageObject: def _test_pickling(self, **options): """ - Checks that this object can be pickled and unpickled properly. + Check that this object can be pickled and unpickled properly. EXAMPLES:: @@ -689,11 +688,10 @@ cdef class SageObject: def _interface_(self, I): """ - Return coercion of self to an object of the interface I. + Return coercion of ``self`` to an object of the interface I. - The result of coercion is cached, unless self is a C - extension class or ``self._interface_is_cached_()`` returns - False. + The result of coercion is cached, unless ``self`` is a C extension + class or ``self._interface_is_cached_()`` returns ``False``. """ c = self._interface_is_cached_() if c: @@ -735,7 +733,7 @@ cdef class SageObject: def _interface_is_cached_(self): """ - Return True if the interface objects are cached. + Return ``True`` if the interface objects are cached. If you have an object x and do gp(x), the result is cached if this function returns True. @@ -831,16 +829,14 @@ cdef class SageObject: def _magma_init_(self, magma): """ Given a Magma interpreter M, return a string that evaluates in - that interpreter to the Magma object corresponding to self. + that interpreter to the Magma object corresponding to ``self``. This function may call the magma interpreter when it runs. INPUT: - ``magma`` -- a Magma interface - OUTPUT: - - - string + OUTPUT: string EXAMPLES:: @@ -946,9 +942,7 @@ cdef class SageObject: Return default string expression that evaluates in R to this object. - OUTPUT: - - - string + OUTPUT: string EXAMPLES:: diff --git a/src/sage/structure/sequence.py b/src/sage/structure/sequence.py index 0a4563d27e4..cc9fcedadfe 100644 --- a/src/sage/structure/sequence.py +++ b/src/sage/structure/sequence.py @@ -85,33 +85,29 @@ def Sequence(x, universe=None, check=True, immutable=False, cr=False, cr_str=Non INPUT: - - ``x`` -- a list or tuple instance + - ``x`` -- list or tuple instance - - ``universe`` -- (default: None) the universe of elements; if None - determined using canonical coercions and the entire list of - elements. If list is empty, is category Objects() of all - objects. + - ``universe`` -- (default: ``None``) the universe of elements; if ``None`` + determined using canonical coercions and the entire list of elements. + If list is empty, is category ``Objects()`` of all objects. - - ``check`` -- (default: ``True``) whether to coerce the elements of x + - ``check`` -- boolean (default: ``True``); whether to coerce the elements of x into the universe - - ``immutable`` -- (default: ``True``) whether or not this sequence is + - ``immutable`` -- boolean (default: ``True``); whether or not this sequence is immutable - - ``cr`` -- (default: ``False``) if True, then print a carriage return - after each comma when printing this sequence. + - ``cr`` -- boolean (default: ``False``); if ``True``, then print a carriage return + after each comma when printing this sequence - - ``cr_str`` -- (default: ``False``) if True, then print a carriage return - after each comma when calling ``str()`` on this sequence. + - ``cr_str`` -- boolean (default: ``False``); if ``True``, then print a carriage return + after each comma when calling ``str()`` on this sequence - - ``use_sage_types`` -- (default: ``False``) if True, coerce the - built-in Python numerical types int, float, complex to the - corresponding Sage types (this makes functions like vector() - more flexible) + - ``use_sage_types`` -- boolean (default: ``False``); if ``True``, coerce the + built-in Python numerical types int, float, complex to the corresponding + Sage types (this makes functions like ``vector()`` more flexible) - OUTPUT: - - - a sequence + OUTPUT: a sequence EXAMPLES:: @@ -256,12 +252,12 @@ def Sequence(x, universe=None, check=True, immutable=False, cr=False, cr_str=Non try: from sage.rings.polynomial.multi_polynomial_sequence import PolynomialSequence from sage.rings.polynomial.pbori.pbori import BooleanMonomialMonoid - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing - from sage.rings.quotient_ring import is_QuotientRing + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base + from sage.rings.quotient_ring import QuotientRing_nc except ImportError: pass else: - if is_MPolynomialRing(universe) or isinstance(universe, BooleanMonomialMonoid) or (is_QuotientRing(universe) and is_MPolynomialRing(universe.cover_ring())): + if isinstance(universe, MPolynomialRing_base) or isinstance(universe, BooleanMonomialMonoid) or (isinstance(universe, QuotientRing_nc) and isinstance(universe.cover_ring(), MPolynomialRing_base)): return PolynomialSequence(x, universe, immutable=immutable, cr=cr, cr_str=cr_str) return Sequence_generic(x, universe, check, immutable, cr, cr_str, use_sage_types) @@ -277,30 +273,26 @@ class Sequence_generic(sage.structure.sage_object.SageObject, list): INPUT: - - ``x`` -- a list or tuple instance + - ``x`` -- list or tuple instance - - ``universe`` -- (default: None) the universe of elements; if None - determined using canonical coercions and the entire list of - elements. If list is empty, is category Objects() of all - objects. + - ``universe`` -- (default: ``None``) the universe of elements; if ``None`` + determined using canonical coercions and the entire list of elements. + If list is empty, is category ``Objects()`` of all objects. - - ``check`` -- (default: ``True``) whether to coerce the elements of x + - ``check`` -- boolean (default: ``True``); whether to coerce the elements of x into the universe - - ``immutable`` -- (default: ``True``) whether or not this sequence is + - ``immutable`` -- boolean (default: ``True``); whether or not this sequence is immutable - - ``cr`` -- (default: ``False``) if True, then print a carriage return - after each comma when printing this sequence. - - - ``use_sage_types`` -- (default: ``False``) if True, coerce the - built-in Python numerical types int, float, complex to the - corresponding Sage types (this makes functions like vector() - more flexible) + - ``cr`` -- boolean (default: ``False``); if ``True``, then print a carriage return + after each comma when printing this sequence - OUTPUT: + - ``use_sage_types`` -- boolean (default: ``False``); if ``True``, coerce the + built-in Python numerical types int, float, complex to the corresponding + Sage types (this makes functions like ``vector()`` more flexible) - - a sequence + OUTPUT: a sequence EXAMPLES:: @@ -402,7 +394,6 @@ class Sequence_generic(sage.structure.sage_object.SageObject, list): [1, 2, 1, 3] sage: v.universe() Finite Field of size 5 - """ def __init__(self, x, universe=None, check=True, immutable=False, cr=False, cr_str=None, use_sage_types=False): @@ -584,7 +575,7 @@ def insert(self, index, object): def pop(self, index=-1): """ - Remove and return item at index (default last) + Remove and return item at index ``index`` (default: last). EXAMPLES:: @@ -599,7 +590,7 @@ def pop(self, index=-1): def remove(self, value): """ - Remove first occurrence of value + Remove first occurrence of ``value``. EXAMPLES:: @@ -753,8 +744,8 @@ def set_immutable(self): def is_immutable(self): """ - Return True if this object is immutable (can not be changed) - and False if it is not. + Return ``True`` if this object is immutable (can not be changed) + and ``False`` if it is not. To make this object immutable use :meth:`set_immutable`. @@ -821,7 +812,7 @@ def __reduce__(self): def __copy__(self): """ - Return a copy of this sequence + Return a copy of this sequence. EXAMPLES:: @@ -833,7 +824,6 @@ def __copy__(self): True sage: t.is_mutable() == s.is_mutable() True - """ return Sequence(self, universe=self.__universe, check=False, @@ -842,7 +832,7 @@ def __copy__(self): def __getattr__(self, name): """ - Strictly for unpickling old 'Sequences' + Strictly for unpickling old 'Sequences'. INPUT: diff --git a/src/sage/structure/set_factories.py b/src/sage/structure/set_factories.py index 46d8870379c..c65a31089e8 100644 --- a/src/sage/structure/set_factories.py +++ b/src/sage/structure/set_factories.py @@ -625,7 +625,7 @@ class TopMostParentPolicy(SetFactoryPolicy): INPUT: - ``factory`` -- an instance of :class:`SetFactory` - - ``top_constraints`` -- the empty set of constraints. + - ``top_constraints`` -- the empty set of constraints - ``Element`` -- a subclass of :class:`~.element.Element` Given a factory ``F`` and a class ``E``, returns a policy for @@ -871,9 +871,9 @@ class ParentWithSetFactory(Parent): INPUT: - - ``constraints`` -- a set of constraints + - ``constraints`` -- set of constraints - ``policy`` -- the policy for element construction - - ``category`` -- the category of the parent (default to ``None``) + - ``category`` -- the category of the parent (default: ``None``) Depending on the constraints and the policy, initialize the parent in a proper category to set up element construction. @@ -1018,8 +1018,7 @@ def subset(self, *args, **options): def _test_subset(self, **options): r""" - Tests that subsets with no extra parameters returns - ``self``. + Test that subsets with no extra parameters returns ``self``. Currently, only the test that one gets the same parent when no more constraints are given, is performed. @@ -1045,10 +1044,10 @@ def check_element(self, x, check): INPUT: - - ``x`` -- an instance of ``self.element_class``. + - ``x`` -- an instance of ``self.element_class`` - ``check`` -- the level of checking to be performed (usually a - boolean). + boolean) This method may assume that ``x`` was properly constructed by ``self`` or a possible super-set of ``self`` for which diff --git a/src/sage/structure/set_factories_example.py b/src/sage/structure/set_factories_example.py index 860137250e9..df4db63ef89 100644 --- a/src/sage/structure/set_factories_example.py +++ b/src/sage/structure/set_factories_example.py @@ -63,9 +63,9 @@ def __call__(self, x=None, y=None, policy=None): INPUT: - - ``x=a`` -- where ``a`` is an integer (default to ``None``). - - ``y=b`` -- where ``b`` is an integer (default to ``None``). - - ``policy`` -- the policy passed to the created set. + - ``x=a`` -- where ``a`` is an integer (default: ``None``) + - ``y=b`` -- where ``b`` is an integer (default: ``None``) + - ``policy`` -- the policy passed to the created set .. SEEALSO:: @@ -91,7 +91,6 @@ def __call__(self, x=None, y=None, policy=None): TESTS:: sage: TestSuite(P).run() - """ if policy is None: policy = self._default_policy @@ -248,10 +247,9 @@ def __init__(self, policy): def pairs_y(self, letter): r""" - Construct the parent for the disjoint union + Construct the parent for the disjoint union. - Construct a parent in :class:`Pairs_Y` as a facade parent for - ``self``. + Construct a parent in :class:`Pairs_Y` as a facade parent for ``self``. This is an internal function which should be hidden from the user (typically under the name ``_pairs_y``. We put it here for @@ -432,7 +430,7 @@ def an_element(self): def single_pair(self, letter): r""" - Construct the singleton pair parent + Construct the singleton pair parent. Construct a singleton pair for ``(self.y, letter)`` as a facade parent for ``self``. diff --git a/src/sage/structure/support_view.py b/src/sage/structure/support_view.py index bebae1a31f5..5daf8c2e496 100644 --- a/src/sage/structure/support_view.py +++ b/src/sage/structure/support_view.py @@ -10,7 +10,8 @@ class SupportView(MappingView, Sequence, Set): r""" - Dynamic view of the set of keys of a dictionary that are associated with nonzero values + Dynamic view of the set of keys of a dictionary that are associated with + nonzero values. It behaves like the objects returned by the :meth:`keys`, :meth:`values`, :meth:`items` of a dictionary (or other :class:`collections.abc.Mapping` @@ -18,9 +19,9 @@ class SupportView(MappingView, Sequence, Set): INPUT: - - ``mapping`` -- a :class:`dict` or another :class:`collections.abc.Mapping`. + - ``mapping`` -- a :class:`dict` or another :class:`collections.abc.Mapping` - - ``zero`` -- (optional) test for zeroness by comparing with this value. + - ``zero`` -- (optional) test for zeroness by comparing with this value EXAMPLES:: diff --git a/src/sage/structure/unique_representation.py b/src/sage/structure/unique_representation.py index 7f769522caf..c7bb3783658 100644 --- a/src/sage/structure/unique_representation.py +++ b/src/sage/structure/unique_representation.py @@ -343,7 +343,7 @@ class will by default also be used as keys for the cache:: ....: return C(key) Now, we define an instance of the factory, stating that it can be found under -the name ``"F"`` in the ``__main__`` module. By consequence, pickling works:: +the name ``'F'`` in the ``__main__`` module. By consequence, pickling works:: sage: F = MyFactory("__main__.F") sage: __main__.F = F # not needed in an interactive session @@ -1201,7 +1201,7 @@ def _clear_cache_(cls): del cache[k] -class UniqueRepresentation(CachedRepresentation, WithEqualityById): +class UniqueRepresentation(WithEqualityById, CachedRepresentation): r""" Classes derived from ``UniqueRepresentation`` inherit a unique representation behavior for their instances. diff --git a/src/sage/symbolic/assumptions.py b/src/sage/symbolic/assumptions.py index 755f5b89a4f..9eef304c6fc 100644 --- a/src/sage/symbolic/assumptions.py +++ b/src/sage/symbolic/assumptions.py @@ -96,11 +96,10 @@ class GenericDeclaration(UniqueRepresentation): INPUT: - - ``var`` -- the variable about which assumptions are - being made + - ``var`` -- the variable about which assumptions are being made - - ``assumption`` -- a string containing a Maxima feature, either user - defined or in the list given by ``maxima('features')`` + - ``assumption`` -- string containing a Maxima feature, either user + defined or in the list given by ``maxima('features')`` EXAMPLES:: @@ -127,7 +126,6 @@ class GenericDeclaration(UniqueRepresentation): sage: GenericDeclaration(x, 'integer') is GenericDeclaration(SR.var("x"), 'integer') True - """ def __init__(self, var, assumption): @@ -139,11 +137,10 @@ def __init__(self, var, assumption): INPUT: - - ``var`` -- the variable about which assumptions are - being made + - ``var`` -- the variable about which assumptions are being made - - ``assumption`` -- a Maxima feature, either user - defined or in the list given by ``maxima('features')`` + - ``assumption`` -- a Maxima feature, either user + defined or in the list given by ``maxima('features')`` EXAMPLES:: @@ -197,7 +194,7 @@ def has(self, arg): def _validate_feature(self): """ - Check if this assumption is a known maxima feature, raise an error otherwise + Check if this assumption is a known maxima feature, raise an error otherwise. EXAMPLES:: @@ -330,8 +327,8 @@ def contradicts(self, soln): INPUT: - - ``soln`` -- Either a dictionary with variables as keys or a symbolic - relation with a variable on the left hand side. + - ``soln`` -- either a dictionary with variables as keys or a symbolic + relation with a variable on the left hand side EXAMPLES:: @@ -456,16 +453,14 @@ def assume(*args): The two types can be combined, but a symbolic inequality cannot appear in the middle of a list of variables. - OUTPUT: - - If everything goes as planned, there is no output. + OUTPUT: if everything goes as planned, there is no output If you assume something that is not one of the two forms above, then - an :class:`AttributeError` is raised as we try to call its ``assume`` + an :exc:`AttributeError` is raised as we try to call its ``assume`` method. If you make inconsistent assumptions (for example, that ``x`` is - both even and odd), then a :class:`ValueError` is raised. + both even and odd), then a :exc:`ValueError` is raised. .. WARNING:: @@ -630,7 +625,7 @@ def assume(*args): True sage: forget() - Ensure that an :class:`AttributeError` is raised if we are given junk:: + Ensure that an :exc:`AttributeError` is raised if we are given junk:: sage: assume(3) Traceback (most recent call last): @@ -686,8 +681,7 @@ def forget(*args): INPUT: - - ``*args`` -- assumptions (default: forget all - assumptions) + - ``*args`` -- assumptions (default: forget all assumptions) EXAMPLES: @@ -735,11 +729,9 @@ def assumptions(*args): INPUT: - - ``args`` -- list of variables which can be empty. - - OUTPUT: + - ``args`` -- list of variables which can be empty - - list of assumptions on variables. If args is empty it returns all + OUTPUT: list of assumptions on variables; if ``args`` is empty it returns all assumptions EXAMPLES:: @@ -861,11 +853,11 @@ class assuming: INPUT: - - ``*args`` -- assumptions (same format as for :func:`assume`). + - ``*args`` -- assumptions (same format as for :func:`assume`) - - ``replace`` -- a boolean (default : ``False``). - Specifies whether the new assumptions are added to (default) - or replace (if ``replace=True``) the current assumption set. + - ``replace`` -- boolean (default: ``False``); specifies whether the new + assumptions are added to (default) or replace (if ``replace=True``) the + current assumption set OUTPUT: diff --git a/src/sage/symbolic/callable.py b/src/sage/symbolic/callable.py index 41ae61bfc72..a8678861b91 100644 --- a/src/sage/symbolic/callable.py +++ b/src/sage/symbolic/callable.py @@ -146,10 +146,9 @@ def arguments(self): def unify_arguments(self, x): r""" - Takes the variable list from another - ``CallableSymbolicExpression`` object and compares it with the - current ``CallableSymbolicExpression`` object's variable list, - combining them according to the following rules: + Take the variable list from another ``CallableSymbolicExpression`` + object and compare it with the current ``CallableSymbolicExpression`` + object's variable list, combining them according to the following rules: Let ``a`` be ``self``'s variable list, let ``b`` be ``y``'s variable list. @@ -176,9 +175,9 @@ def unify_arguments(self, x): INPUT: - - ``x`` -- A CallableSymbolicExpression + - ``x`` -- a ``CallableSymbolicExpression`` - OUTPUT: A tuple of variables. + OUTPUT: a tuple of variables EXAMPLES:: @@ -348,7 +347,6 @@ def _repr_element_(self, x): (y, x) |--> x + y sage: f.parent() Callable function ring with arguments (y, x) - """ args = self.arguments() repr_x = SymbolicRing._repr_element_(self, x) diff --git a/src/sage/symbolic/comparison_impl.pxi b/src/sage/symbolic/comparison_impl.pxi index 00cbe88964f..8d1bd2e03d6 100644 --- a/src/sage/symbolic/comparison_impl.pxi +++ b/src/sage/symbolic/comparison_impl.pxi @@ -52,7 +52,7 @@ cpdef int print_order(lhs, rhs) except -2: INPUT: - ``lhs``, ``rhs`` -- two symbolic expressions or something that - can be converted to one. + can be converted to one OUTPUT: @@ -95,7 +95,7 @@ class _print_key(): INPUT: - ``ex`` -- symbolic expression or something that can be - converted into one. + converted into one EXAMPLES:: @@ -114,11 +114,9 @@ class _print_key(): INPUT: - - ``other`` -- another :class:`_print_key` instance. + - ``other`` -- another :class:`_print_key` instance - OUTPUT: - - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -137,16 +135,14 @@ class _print_key(): cpdef print_sorted(expressions): """ - Sort a list in print order + Sort a list in print order. INPUT: - - ``expressions`` -- a list/tuple/iterable of symbolic - expressions, or something that can be converted to one. - - OUTPUT: + - ``expressions`` -- list/tuple/iterable of symbolic + expressions, or something that can be converted to one - The list sorted by :meth:`print_order`. + OUTPUT: the list sorted by :meth:`print_order` EXAMPLES:: @@ -166,7 +162,7 @@ class _math_key(): INPUT: - ``ex`` -- symbolic expression or something that can be - converted into one. + converted into one EXAMPLES:: @@ -185,12 +181,10 @@ class _math_key(): INPUT: - - ``other`` -- another :class:`_print_key` instance. + - ``other`` -- another :class:`_print_key` instance - OUTPUT: - - Boolean. A :class:`ValueError` is raised if we do not know how to - perform the comparison. + OUTPUT: boolean; a :exc:`ValueError` is raised if we do not know how to + perform the comparison EXAMPLES:: @@ -221,18 +215,18 @@ class _math_key(): cpdef math_sorted(expressions): """ - Sort a list of symbolic numbers in the "Mathematics" order + Sort a list of symbolic numbers in the "Mathematics" order. INPUT: - - ``expressions`` -- a list/tuple/iterable of symbolic - expressions, or something that can be converted to one. + - ``expressions`` -- list/tuple/iterable of symbolic + expressions, or something that can be converted to one OUTPUT: The list sorted by ascending (real) value. If an entry does not define a real value (or plus/minus infinity), or if the comparison - is not known, a :class:`ValueError` is raised. + is not known, a :exc:`ValueError` is raised. EXAMPLES:: @@ -250,7 +244,7 @@ cpdef int mixed_order(lhs, rhs) except -2: INPUT: - ``lhs``, ``rhs`` -- two symbolic expressions or something that - can be converted to one. + can be converted to one OUTPUT: @@ -285,7 +279,6 @@ cpdef int mixed_order(lhs, rhs) except -2: 1 sage: mixed_order(log2, 0) 1 - """ if lhs is rhs: return 0 @@ -318,7 +311,7 @@ class _mixed_key(): INPUT: - ``ex`` -- symbolic expression or something that can be - converted into one. + converted into one EXAMPLES:: @@ -337,12 +330,10 @@ class _mixed_key(): INPUT: - - ``other`` -- another :class:`_mixed_key` instance. - - OUTPUT: + - ``other`` -- another :class:`_mixed_key` instance - Boolean. A :class:`ValueError` is raised if we do not know how to - perform the comparison. + OUTPUT: boolean; a :exc:`ValueError` is raised if we do not know how to + perform the comparison EXAMPLES:: @@ -411,12 +402,12 @@ class _mixed_key(): cpdef mixed_sorted(expressions): """ - Sort a list of symbolic numbers in the "Mixed" order + Sort a list of symbolic numbers in the "Mixed" order. INPUT: - - ``expressions`` -- a list/tuple/iterable of symbolic - expressions, or something that can be converted to one. + - ``expressions`` -- list/tuple/iterable of symbolic + expressions, or something that can be converted to one OUTPUT: @@ -424,7 +415,7 @@ cpdef mixed_sorted(expressions): and the expressions with variables according to print order. If an entry does not define a real value (or plus/minus infinity), or if the comparison - is not known, a :class:`ValueError` is raised. + is not known, a :exc:`ValueError` is raised. EXAMPLES:: diff --git a/src/sage/symbolic/complexity_measures.py b/src/sage/symbolic/complexity_measures.py index 528d1bf6906..a7b66fa5db0 100644 --- a/src/sage/symbolic/complexity_measures.py +++ b/src/sage/symbolic/complexity_measures.py @@ -9,15 +9,13 @@ def string_length(expr): """ - Returns the length of ``expr`` after converting it to a string. + Return the length of ``expr`` after converting it to a string. INPUT: - - ``expr`` -- the expression whose complexity we want to measure. + - ``expr`` -- the expression whose complexity we want to measure - OUTPUT: - - A real number representing the complexity of ``expr``. + OUTPUT: a real number representing the complexity of ``expr`` RATIONALE: @@ -32,6 +30,5 @@ def string_length(expr): sage: f = x^2 sage: string_length(f) 3 - """ return len(str(expr)) diff --git a/src/sage/symbolic/constants.py b/src/sage/symbolic/constants.py index f00cb29eedb..f7177a24994 100644 --- a/src/sage/symbolic/constants.py +++ b/src/sage/symbolic/constants.py @@ -274,7 +274,7 @@ def unpickle_Constant(class_name, name, conversions, latex, mathml, domain): @richcmp_method class Constant(): - def __init__(self, name, conversions=None, latex=None, mathml="", + def __init__(self, name, conversions=None, latex=None, mathml='', domain='complex'): """ EXAMPLES:: @@ -323,7 +323,7 @@ def __richcmp__(self, other, op): def __reduce__(self): """ - Adds support for pickling constants. + Add support for pickling constants. EXAMPLES:: @@ -345,7 +345,6 @@ def __reduce__(self): 'positive')) sage: loads(dumps(pi.pyobject())) pi - """ return (unpickle_Constant, (self.__class__.__name__, self._name, self._conversions, self._latex, @@ -353,7 +352,7 @@ def __reduce__(self): def domain(self): """ - Returns the domain of this constant. This is either positive, + Return the domain of this constant. This is either positive, real, or complex, and is used by Pynac to make inferences about expressions containing this constant. @@ -370,7 +369,7 @@ def domain(self): def expression(self): """ - Returns an expression for this constant. + Return an expression for this constant. EXAMPLES:: @@ -387,7 +386,7 @@ def expression(self): def _symbolic_(self, SR): """ - Returns an expression for this constant. + Return an expression for this constant. INPUT: @@ -407,7 +406,7 @@ def _symbolic_(self, SR): def name(self): """ - Returns the name of this constant. + Return the name of this constant. EXAMPLES:: @@ -469,7 +468,6 @@ def _generic_interface(self, value, I): sage: m = partial(p._generic_interface, '%pi') sage: m(maxima) %pi - """ return I(value) @@ -491,7 +489,6 @@ def _generic_interface_init(self, value): sage: mi = partial(p._generic_interface_init, '%pi') sage: mi() '%pi' - """ return value @@ -519,7 +516,7 @@ def _interface_(self, I): def _gap_(self, gap): """ - Returns the constant as a string in GAP. Since GAP does not + Return the constant as a string in GAP. Since GAP does not have floating point numbers, we simply return the constant as a string. @@ -534,7 +531,7 @@ def _gap_(self, gap): def _singular_(self, singular): """ - Returns the constant as a string in Singular. Since Singular + Return the constant as a string in Singular. Since Singular does not always support floating point numbers, we simply return the constant as a string. (Singular allows floating point numbers if the current ring has floating point coefficients, @@ -551,7 +548,7 @@ def _singular_(self, singular): class Pi(Constant): - def __init__(self, name="pi"): + def __init__(self, name='pi'): r""" TESTS:: @@ -739,7 +736,7 @@ def _real_double_(self, R): def _sympy_(self): """ - Converts NaN to SymPy NaN. + Convert ``NaN`` to SymPy NaN. EXAMPLES:: @@ -758,7 +755,7 @@ def _sympy_(self): class GoldenRatio(Constant): """ - The number (1+sqrt(5))/2 + The number (1+sqrt(5))/2. EXAMPLES:: @@ -845,7 +842,7 @@ def _algebraic_(self, field): def _sympy_(self): """ - Converts golden_ratio to SymPy GoldenRation. + Convert ``golden_ratio`` to SymPy GoldenRatio. EXAMPLES:: @@ -1002,7 +999,7 @@ def _real_double_(self, R): def _sympy_(self): """ - Converts euler_gamma to SymPy EulerGamma. + Convert ``euler_gamma`` to SymPy EulerGamma. EXAMPLES:: @@ -1072,7 +1069,7 @@ def __float__(self): def _sympy_(self): """ - Converts catalan to SymPy Catalan. + Convert ``catalan`` to SymPy Catalan. EXAMPLES:: @@ -1123,7 +1120,6 @@ def _mpfr_(self, R): 2.6854520010653064453097148355 sage: RealField(100)(khinchin) 2.6854520010653064453097148355 - """ import sage.libs.mpmath.all as a return a.eval_constant('khinchin', R) @@ -1152,7 +1148,6 @@ class TwinPrime(Constant): 0.6601618158468696 sage: twinprime.n(digits=60) 0.660161815846869573927812110014555778432623360284733413319448 - """ def __init__(self, name='twinprime'): """ @@ -1201,7 +1196,6 @@ class Mertens(Constant): 0.26149721284764277 sage: mertens.n(digits=60) 0.261497212847642783755426838608695859051566648261199206192064 - """ def __init__(self, name='mertens'): """ @@ -1222,7 +1216,6 @@ def _mpfr_(self, R): 0.26149721284764278375542683861 sage: RealField(100)(mertens) 0.26149721284764278375542683861 - """ import sage.libs.mpmath.all as a return a.eval_constant('mertens', R) @@ -1255,7 +1248,6 @@ class Glaisher(Constant): glaisher + 2 sage: parent(a) Symbolic Ring - """ def __init__(self, name='glaisher'): """ @@ -1277,7 +1269,6 @@ def _mpfr_(self, R): 1.2824271291006226368753425689 sage: RealField(100)(glaisher) 1.2824271291006226368753425689 - """ import sage.libs.mpmath.all as a return a.eval_constant('glaisher', R) diff --git a/src/sage/symbolic/expression.pyx b/src/sage/symbolic/expression.pyx index 7671338feaa..5e3098b0542 100644 --- a/src/sage/symbolic/expression.pyx +++ b/src/sage/symbolic/expression.pyx @@ -156,8 +156,8 @@ Test that :issue:`20784` is fixed (equations should stay unevaluated):: Many tests about comparison. -Use :func:`sage.symbolic.expression.mixed_order`` instead of -the operators <=, <, etc. to compare symbolic expressions when +Use :func:`sage.symbolic.expression.mixed_order` instead of +the operators ``<=``, ``<``, etc. to compare symbolic expressions when you do not want to get a formal inequality:: sage: from sage.symbolic.expression import mixed_order @@ -410,7 +410,7 @@ from sage.symbolic.symbols import symbol_table, register_symbol # used to be de cpdef bint is_SymbolicEquation(x) noexcept: """ - Return True if *x* is a symbolic equation. + Return ``True`` if ``x`` is a symbolic equation. This function is deprecated. @@ -441,7 +441,6 @@ cpdef bint is_SymbolicEquation(x) noexcept: sage: is_SymbolicEquation(SR(2) == SR(3)) True - """ from sage.misc.superseded import deprecation deprecation(35505, @@ -484,7 +483,7 @@ def _dict_update_check_duplicate(dict d1, dict d2): Merge the dictionary ``d2`` into ``d1`` and check for duplicates. The two dictionaries must be of the form ``{expr: replacement}``. This - function throws a :class:`ValueError` if any expressions are substituted + function throws a :exc:`ValueError` if any expressions are substituted for twice. EXAMPLES: @@ -519,7 +518,6 @@ def _dict_update_check_duplicate(dict d1, dict d2): Traceback (most recent call last): ... ValueError: duplicate substitution for a, got values 1 and 2 - """ # We need to check for duplicates in a predictable order so that # errors are reported reliably. We only need to sort one of the @@ -552,11 +550,9 @@ def _subs_make_dict(s): INPUT: - - ``s`` -- A representation of a substitution. - - OUTPUT: + - ``s`` -- a representation of a substitution - A dictionary of substitutions. + OUTPUT: a dictionary of substitutions EXAMPLES: @@ -587,7 +583,7 @@ def _subs_make_dict(s): sage: actual == expected True - Check that a :class:`TypeError` is raised if the input is not valid:: + Check that a :exc:`TypeError` is raised if the input is not valid:: sage: _subs_make_dict(1) Traceback (most recent call last): @@ -629,11 +625,9 @@ def _subs_fun_make_dict(s): INPUT: - - ``s`` -- A representation of a substitution. + - ``s`` -- a representation of a substitution - OUTPUT: - - A dictionary of substitutions. + OUTPUT: a dictionary of substitutions EXAMPLES: @@ -666,7 +660,7 @@ def _subs_fun_make_dict(s): sage: actual == expected True - Check that a :class:`TypeError` is raised if the input is not valid:: + Check that a :exc:`TypeError` is raised if the input is not valid:: sage: _subs_fun_make_dict(1) Traceback (most recent call last): @@ -711,7 +705,7 @@ cdef class Expression(Expression_abc): The Python object corresponding to this expression, assuming this expression is a single numerical value or an infinity - representable in Python. Otherwise, a :class:`TypeError` is raised. + representable in Python. Otherwise, a :exc:`TypeError` is raised. EXAMPLES:: @@ -804,7 +798,7 @@ cdef class Expression(Expression_abc): * 0 - as pickle version number in case we decide to change the pickle format in the feature * names of symbols of this expression - * a string representation of self stored in a Pynac archive. + * a string representation of ``self`` stored in a Pynac archive. TESTS:: @@ -963,7 +957,6 @@ cdef class Expression(Expression_abc): sage: with SR.temp_var() as t: pass sage: symbols_copy == SR.symbols True - """ from sage.symbolic.ring import SR SR.cleanup_var(self) @@ -1066,12 +1059,10 @@ cdef class Expression(Expression_abc): INPUT: - - ``use_unicode`` -- boolean. Whether to allow unicode instead - of 7-bit clean output. + - ``use_unicode`` -- boolean; whether to allow unicode instead + of 7-bit clean output - OUTPUT: - - String. + OUTPUT: string EXAMPLES:: @@ -1218,7 +1209,6 @@ cdef class Expression(Expression_abc): sage: var('ξ')._maxima_() _SAGE_VAR_ξ - """ if session is None: # This chooses the Maxima interface used by calculus @@ -1463,7 +1453,6 @@ cdef class Expression(Expression_abc): π sage: mathml(pi+2) MATHML version of the string pi + 2 - """ from sage.misc.mathml import mathml try: @@ -1925,11 +1914,9 @@ cdef class Expression(Expression_abc): """ Return float conversion of ``self``, assuming ``self`` is constant. - Otherwise, raise a :class:`TypeError`. - - OUTPUT: + Otherwise, raise a :exc:`TypeError`. - A ``float``. Double precision evaluation of ``self``. + OUTPUT: a ``float``. Double precision evaluation of ``self`` EXAMPLES:: @@ -1989,7 +1976,6 @@ cdef class Expression(Expression_abc): pi sage: type(_) - """ from sage.symbolic.expression_conversions import sympy_converter return sympy_converter(self) @@ -2002,7 +1988,6 @@ cdef class Expression(Expression_abc): sage: pi._fricas_() # optional - fricas %pi - """ from sage.symbolic.expression_conversions import fricas_converter return fricas_converter(self) @@ -2308,7 +2293,7 @@ cdef class Expression(Expression_abc): sage: x == 0 x == 0 - In particular, it does not return a bool, so the following check does + In particular, it does not return a boolean, so the following check does not hold anymore:: sage: (not x) == (x != 0) @@ -2317,7 +2302,6 @@ cdef class Expression(Expression_abc): TESTS:: sage: x._test_nonzero_equal() - """ pass @@ -2330,8 +2314,8 @@ cdef class Expression(Expression_abc): sage: (x > 2).assume() - Bool returns True below if the inequality is *definitely* known to - be True. + ``bool`` returns ``True`` below if the inequality is *definitely* known + to be true. :: @@ -2340,7 +2324,7 @@ cdef class Expression(Expression_abc): sage: bool(x < 0) False - This may or may not be True, so bool returns False:: + This may or may not be True, so ``bool`` returns False:: sage: bool(x > 3) False @@ -2523,7 +2507,7 @@ cdef class Expression(Expression_abc): def is_algebraic(self): """ - Return True if this expression is known to be algebraic. + Return ``True`` if this expression is known to be algebraic. EXAMPLES:: @@ -2582,7 +2566,7 @@ cdef class Expression(Expression_abc): def is_real(self): """ - Return True if this expression is known to be a real number. + Return ``True`` if this expression is known to be a real number. EXAMPLES:: @@ -2657,7 +2641,7 @@ cdef class Expression(Expression_abc): def is_positive(self): """ - Return True if this expression is known to be positive. + Return ``True`` if this expression is known to be positive. EXAMPLES:: @@ -2753,7 +2737,7 @@ cdef class Expression(Expression_abc): def is_negative(self): """ - Return True if this expression is known to be negative. + Return ``True`` if this expression is known to be negative. EXAMPLES:: @@ -2784,7 +2768,7 @@ cdef class Expression(Expression_abc): def is_integer(self): """ - Return True if this expression is known to be an integer. + Return ``True`` if this expression is known to be an integer. EXAMPLES:: @@ -2811,7 +2795,7 @@ cdef class Expression(Expression_abc): def is_symbol(self): """ - Return True if this symbolic expression consists of only a symbol, i.e., + Return ``True`` if this symbolic expression consists of only a symbol, i.e., a symbolic variable. EXAMPLES:: @@ -2898,7 +2882,7 @@ cdef class Expression(Expression_abc): """ A Pynac numeric is an object you can do arithmetic with that is not a symbolic variable, function, or constant. - Return True if this expression only consists of a numeric object. + Return ``True`` if this expression only consists of a numeric object. EXAMPLES:: @@ -2915,17 +2899,15 @@ cdef class Expression(Expression_abc): def is_terminating_series(self): """ - Return True if ``self`` is a series without order term. + Return ``True`` if ``self`` is a series without order term. A series is terminating if it can be represented exactly, without requiring an order term. You can explicitly request terminating series by setting the order to positive infinity. - OUTPUT: - - Boolean. Whether ``self`` was constructed by :meth:`series` - and has no order term. + OUTPUT: boolean; whether ``self`` was constructed by :meth:`series` + and has no order term EXAMPLES:: @@ -3134,7 +3116,6 @@ cdef class Expression(Expression_abc): ... NotImplementedError: is_square() not implemented for non-constant or relational elements of Symbolic Ring - """ if self.is_constant() and not self.is_relational(): # The square root of any "number" is in SR... just call @@ -3167,7 +3148,7 @@ cdef class Expression(Expression_abc): def left_hand_side(self): """ If ``self`` is a relational expression, return the left hand side - of the relation. Otherwise, raise a :class:`ValueError`. + of the relation. Otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -3189,7 +3170,7 @@ cdef class Expression(Expression_abc): def right_hand_side(self): """ If ``self`` is a relational expression, return the right hand side - of the relation. Otherwise, raise a :class:`ValueError`. + of the relation. Otherwise, raise a :exc:`ValueError`. EXAMPLES:: @@ -3301,7 +3282,7 @@ cdef class Expression(Expression_abc): def __bool__(self): """ - Return True unless this symbolic expression can be shown by Sage + Return ``True`` unless this symbolic expression can be shown by Sage to be zero. Note that deciding if an expression is zero is undecidable in general. @@ -3541,28 +3522,26 @@ cdef class Expression(Expression_abc): test this relation after casting into the domain. Because the interval fields never return false positives, we can be - assured that if True or False is returned (and proof is False) then - the answer is correct. + assured that if ``True`` or ``False`` is returned (and proof is + ``False``) then the answer is correct. INPUT: - - ``ntests`` -- (default ``20``) the number of iterations to run + - ``ntests`` -- (default: 20) the number of iterations to run - ``domain`` -- (optional) the domain from which to draw the random values defaults to ``CIF`` for equality testing and ``RIF`` for order testing - - ``proof`` -- (default ``True``) if ``False`` and the domain is an + - ``proof`` -- (default: ``True``) if ``False`` and the domain is an interval field, regard overlapping (potentially equal) intervals as equal, and return ``True`` if all tests succeeded. - OUTPUT: - - Boolean or ``NotImplemented``, meaning + OUTPUT: boolean or ``NotImplemented``, meaning - - ``True`` -- this relation holds in the domain and has no variables. + - ``True`` -- this relation holds in the domain and has no variables - - ``False`` -- a contradiction was found. + - ``False`` -- a contradiction was found - - ``NotImplemented`` -- no contradiction found. + - ``NotImplemented`` -- no contradiction found EXAMPLES:: @@ -3623,7 +3602,6 @@ cdef class Expression(Expression_abc): sage: v = -53985/17179869184 sage: bool(abs(t) < 1.213*2^-56*v^4) True - """ cdef int k, eq_count = 0 cdef bint is_interval @@ -3727,7 +3705,7 @@ cdef class Expression(Expression_abc): """ Return the negated version of ``self``. - This is the relation that is ``False`` iff self is ``True``. + This is the relation that is ``False`` iff ``self`` is ``True``. EXAMPLES:: @@ -3777,7 +3755,7 @@ cdef class Expression(Expression_abc): def is_unit(self): """ - Return True if this expression is a unit of the symbolic ring. + Return ``True`` if this expression is a unit of the symbolic ring. Note that a proof may be attempted to get the result. To avoid this use ``(ex-1).is_trivial_zero()``. @@ -4250,11 +4228,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``right`` -- A :class:`Expression` instance. - - OUTPUT: + - ``right`` -- a :class:`Expression` instance - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -4278,11 +4254,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``right`` -- A :class:`Expression` instance. - - OUTPUT: + - ``right`` -- a :class:`Expression` instance - Boolean. + OUTPUT: boolean EXAMPLES:: @@ -4304,9 +4278,7 @@ cdef class Expression(Expression_abc): r""" Return ``self`` raised to the power ``other``. - OUTPUT: - - A symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -4492,7 +4464,7 @@ cdef class Expression(Expression_abc): Check that :issue:`31137` is also fixed:: - sage: _ = var('A, L, G, R, f, k, n, q, u, beta, gamma', domain="positive") + sage: _ = var('A, L, G, R, f, k, n, q, u, beta, gamma', domain='positive') sage: a = I*R^2*f^3*k*q*A*u sage: b = 2*pi*L*R^2*G*f^4*k^2*q - 2*pi*L*R^2*G*f^4*q - 2*pi*L*R^2*beta^2*G*q sage: c = (2*I*pi*L*R^2*beta*gamma*q + 2*I*pi*L*R*(beta + q))*G*f^3 @@ -4758,7 +4730,6 @@ cdef class Expression(Expression_abc): of scalar fields on Euclidean spaces (and more generally pseudo-Riemannian manifolds), in particular for computing the gradient in curvilinear coordinates. - """ from sage.modules.free_module_element import vector if variables is None: @@ -4797,13 +4768,11 @@ cdef class Expression(Expression_abc): such as ``x == 5``; if an equality is given, the expansion is around the value on the right hand side of the equality - - ``order`` -- an integer; if nothing given, it is set + - ``order`` -- integer; if nothing given, it is set to the global default (``20``), which can be changed using :func:`set_series_precision` - OUTPUT: - - A power series. + OUTPUT: a power series To truncate the power series and obtain a normal expression, use the :meth:`truncate` command. @@ -4938,9 +4907,7 @@ cdef class Expression(Expression_abc): around the value on the right hand side of the equality, otherwise at ``0``. - OUTPUT: - - The residue of ``self``. + OUTPUT: the residue of ``self`` Say, ``symbol`` is ``x == a``, then this function calculates the residue of ``self`` at `x=a`, i.e., the coefficient of @@ -5008,7 +4975,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``*args`` -- the following notation is supported + - ``*args`` -- the following notation is supported - ``x``, ``a``, ``n`` -- variable, point, degree @@ -5084,11 +5051,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``self`` -- a series as output by the :meth:`series` command. + - ``self`` -- a series as output by the :meth:`series` command - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -5252,26 +5217,24 @@ cdef class Expression(Expression_abc): INPUT: - - ``full`` -- (default: ``False``) To enhance user control - of simplification, this function expands only one level at a time - by default, expanding sums of angles or multiple angles. To obtain - full expansion into sines and cosines immediately, set the optional - parameter full to ``True``. - - - ``half_angles`` -- (default: ``False``) If ``True``, causes - half-angles to be simplified away. + - ``full`` -- boolean (default: ``False``); to enhance user control + of simplification, this function expands only one level at a time + by default, expanding sums of angles or multiple angles. To obtain + full expansion into sines and cosines immediately, set the optional + parameter full to ``True``. - - ``plus`` -- (default: ``True``) Controls the sum rule; - expansion of sums (e.g. `\sin(x + y)`) will take place only - if ``plus`` is ``True``. + - ``half_angles`` -- boolean (default: ``False``); if ``True``, causes + half-angles to be simplified away - - ``times`` -- (default: ``True``) Controls the product - rule, expansion of products (e.g. `\sin(2 x)`) will take place only - if ``times`` is ``True``. + - ``plus`` -- boolean (default: ``True``); controls the sum rule. + Expansion of sums (e.g. `\sin(x + y)`) will take place only if + ``plus`` is ``True``. - OUTPUT: + - ``times`` -- boolean (default: ``True``); controls the product + rule, expansion of products (e.g. `\sin(2 x)`) will take place only + if ``times`` is ``True``. - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -5339,9 +5302,7 @@ cdef class Expression(Expression_abc): these transformations. If not specified, all variables are used. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -5377,13 +5338,11 @@ cdef class Expression(Expression_abc): INPUT: - - ``pattern`` -- a symbolic expression, possibly containing wildcards - to match for + - ``pattern`` -- a symbolic expression, possibly containing wildcards + to match for OUTPUT: - One of - ``None`` if there is no match, or a dictionary mapping the wildcards to the matching values if a match was found. Note that the dictionary is empty if there were no wildcards in the @@ -6133,18 +6092,15 @@ cdef class Expression(Expression_abc): INPUT: - - ``pattern`` -- an :class:`Expression`, usually - containing wildcards. + - ``pattern`` -- an :class:`Expression`, usually containing wildcards - - ``replacement`` -- a function. Its argument is a dictionary + - ``replacement`` -- a function; its argument is a dictionary mapping the wildcard occurring in ``pattern`` to the actual values. If it returns ``None``, this occurrence of ``pattern`` is not replaced. Otherwise, it is replaced by the output of ``replacement``. - OUTPUT: - - An :class:`Expression`. + OUTPUT: an :class:`Expression` EXAMPLES:: @@ -6200,7 +6156,6 @@ cdef class Expression(Expression_abc): (x, y) sage: sin(x+y^z).variables() (x, y, z) - """ from sage.symbolic.ring import SR cdef GExSet sym_set @@ -6258,7 +6213,6 @@ cdef class Expression(Expression_abc): sage: g = f.function(x) sage: g.arguments() (x,) - """ try: return self._parent.arguments() @@ -6812,7 +6766,6 @@ cdef class Expression(Expression_abc): sage: a = (x^2).power(2, hold=True); a.unhold() x^4 - """ cdef Expression nexp = self.coerce_in(exp) return new_Expression_from_GEx(self._parent, @@ -6874,7 +6827,6 @@ cdef class Expression(Expression_abc): sage: a = x.mul(x, hold=True); a.unhold() x^2 - """ nargs = [self.coerce_in(x) for x in args] cdef GExVector vec @@ -6897,9 +6849,7 @@ cdef class Expression(Expression_abc): - ``n`` -- expression, default 1 - OUTPUT: - - A symbolic expression. The coefficient of `s^n`. + OUTPUT: a symbolic expression. The coefficient of `s^n` Sometimes it may be necessary to expand or factor first, since this is not done automatically. @@ -6996,17 +6946,15 @@ cdef class Expression(Expression_abc): INPUT: - - ``x`` -- optional variable. - - OUTPUT: + - ``x`` -- (optional) variable - Depending on the value of ``sparse``, + OUTPUT: depending on the value of ``sparse``, - A list of pairs ``(expr, n)``, where ``expr`` is a symbolic expression and ``n`` is a power (``sparse=True``, default) - A list of expressions where the ``n``-th element is the coefficient of - ``x^n`` when self is seen as polynomial in ``x`` (``sparse=False``). + ``x^n`` when ``self`` is seen as polynomial in ``x`` (``sparse=False``). EXAMPLES:: @@ -7123,12 +7071,12 @@ cdef class Expression(Expression_abc): INPUT: - - ``x`` -- optional variable. + - ``x`` -- (optional) variable OUTPUT: A list of expressions where the ``n``-th element is the coefficient of - ``x^n`` when self is seen as polynomial in ``x``. + ``x^n`` when ``self`` is seen as polynomial in ``x``. EXAMPLES:: @@ -7180,8 +7128,8 @@ cdef class Expression(Expression_abc): def trailing_coefficient(self, s): """ - Return the trailing coefficient of s in self, i.e., the coefficient - of the smallest power of s in self. + Return the trailing coefficient of s in ``self``, i.e., the coefficient + of the smallest power of s in ``self``. EXAMPLES:: @@ -7211,9 +7159,7 @@ cdef class Expression(Expression_abc): """ Return the exponent of the lowest power of ``s`` in ``self``. - OUTPUT: - - An integer + OUTPUT: integer EXAMPLES:: @@ -7244,9 +7190,7 @@ cdef class Expression(Expression_abc): """ Return the exponent of the highest power of ``s`` in ``self``. - OUTPUT: - - An integer + OUTPUT: integer EXAMPLES:: @@ -7283,7 +7227,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``s`` -- a symbolic expression. + - ``s`` -- a symbolic expression OUTPUT: @@ -7322,7 +7266,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``s`` -- a symbolic expression. + - ``s`` -- a symbolic expression OUTPUT: @@ -7367,7 +7311,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``s`` -- a symbolic expression. + - ``s`` -- a symbolic expression OUTPUT: @@ -7496,9 +7440,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``base_ring`` -- (optional) the base ring for the polynomial + - ``base_ring`` -- (optional) the base ring for the polynomial - - ``ring`` -- (optional) the parent for the polynomial + - ``ring`` -- (optional) the parent for the polynomial .. warning:: @@ -7588,7 +7532,6 @@ cdef class Expression(Expression_abc): sage: B = f.polynomial(ring=SR['x,y']) sage: B.coefficients() [a, 3] - """ from sage.symbolic.expression_conversions import polynomial return polynomial(self, base_ring=base_ring, ring=ring) @@ -7600,9 +7543,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``base_ring`` -- (optional) the base ring for the polynomial + - ``base_ring`` -- (optional) the base ring for the polynomial - - ``ring`` -- (optional) the parent for the polynomial + - ``ring`` -- (optional) the parent for the polynomial You can specify either the base ring (``base_ring``) you want the output Laurent polynomial to be over, or you can specify the full @@ -7710,10 +7653,10 @@ cdef class Expression(Expression_abc): TypeError: y is not a variable of Multivariate Polynomial Ring in x over Ring of integers modulo 4 """ from sage.symbolic.ring import SR - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base base_ring = R.base_ring() if base_ring == SR: - if is_MPolynomialRing(R): + if isinstance(R, MPolynomialRing_base): return R({tuple([0]*R.ngens()):self}) else: return R([self]) @@ -8027,15 +7970,14 @@ cdef class Expression(Expression_abc): """ Return the lcm of ``self`` and ``b``. - The lcm is computed from the gcd of ``self`` and ``b`` - implicitly from the - relation self * b = gcd(self, b) * lcm(self, b). + The lcm is computed from the gcd of ``self`` and ``b`` implicitly from + the relation ``self * b = gcd(self, b) * lcm(self, b)``. .. NOTE:: In agreement with the convention in use for integers, if - self * b == 0, then gcd(self, b) == max(self, b) and - lcm(self, b) == 0. + ``self * b == 0``, then ``gcd(self, b) == max(self, b)`` and + ``lcm(self, b) == 0``. .. NOTE:: @@ -8086,7 +8028,6 @@ cdef class Expression(Expression_abc): (x, 0) sage: gcd(SR(0), SR(0)), lcm(SR(0), SR(0)) (0, 0) - """ sb = self * b try: @@ -8132,7 +8073,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``s`` -- the symbol whose coefficients will be collected. + - ``s`` -- the symbol whose coefficients will be collected OUTPUT: @@ -8430,20 +8371,19 @@ cdef class Expression(Expression_abc): 1 sage: SR(2).step(hold=True) unit_step(2) - """ return new_Expression_from_GEx(self._parent, g_hold_wrapper(g_step, self._gobj, hold)) def csgn(self, hold=False): """ - Return the sign of self, which is -1 if self < 0, 0 if self == - 0, and 1 if self > 0, or unevaluated when self is a nonconstant - symbolic expression. + Return the sign of ``self``, which is -1 if ``self < 0``, 0 if + ``self == 0``, and 1 if ``self > 0``, or unevaluated when ``self`` is a + nonconstant symbolic expression. - If self is not real, return the complex half-plane (left or right) - in which the number lies. If self is pure imaginary, return the sign - of the imaginary part of self. + If ``self`` is not real, return the complex half-plane (left or right) + in which the number lies. If ``self`` is pure imaginary, return the sign + of the imaginary part of ``self``. EXAMPLES:: @@ -8476,7 +8416,6 @@ cdef class Expression(Expression_abc): sage: SR(I).csgn(hold=True) csgn(I) - """ return new_Expression_from_GEx(self._parent, g_hold_wrapper(g_csgn, self._gobj, hold)) @@ -8525,7 +8464,6 @@ cdef class Expression(Expression_abc): sage: a = SR(I).conjugate(hold=True); a.unhold() -I - """ return new_Expression_from_GEx(self._parent, g_hold_wrapper(g_conjugate, self._gobj, hold)) @@ -8709,7 +8647,7 @@ cdef class Expression(Expression_abc): def sqrt(self, hold=False): """ - Return the square root of this expression + Return the square root of this expression. EXAMPLES:: @@ -8830,7 +8768,7 @@ cdef class Expression(Expression_abc): def cos(self, hold=False): """ - Return the cosine of self. + Return the cosine of ``self``. EXAMPLES:: @@ -8996,7 +8934,7 @@ cdef class Expression(Expression_abc): def arccos(self, hold=False): """ - Return the arc cosine of self. + Return the arc cosine of ``self``. EXAMPLES:: @@ -9046,7 +8984,7 @@ cdef class Expression(Expression_abc): def arctan(self, hold=False): """ - Return the arc tangent of self. + Return the arc tangent of ``self``. EXAMPLES:: @@ -9095,7 +9033,7 @@ cdef class Expression(Expression_abc): def arctan2(self, x, hold=False): """ - Return the inverse of the 2-variable tan function on self and x. + Return the inverse of the 2-variable tan function on ``self`` and ``x``. EXAMPLES:: @@ -9199,7 +9137,7 @@ cdef class Expression(Expression_abc): def sinh(self, hold=False): r""" - Return sinh of self. + Return sinh of ``self``. We have `\sinh(x) = (e^{x} - e^{-x})/2`. @@ -9257,7 +9195,7 @@ cdef class Expression(Expression_abc): def cosh(self, hold=False): r""" - Return cosh of self. + Return cosh of ``self``. We have `\cosh(x) = (e^{x} + e^{-x})/2`. @@ -9313,7 +9251,7 @@ cdef class Expression(Expression_abc): def tanh(self, hold=False): r""" - Return tanh of self. + Return tanh of ``self``. We have `\tanh(x) = \sinh(x) / \cosh(x)`. @@ -9367,7 +9305,7 @@ cdef class Expression(Expression_abc): def arcsinh(self, hold=False): """ - Return the inverse hyperbolic sine of self. + Return the inverse hyperbolic sine of ``self``. EXAMPLES:: @@ -9469,7 +9407,7 @@ cdef class Expression(Expression_abc): def arctanh(self, hold=False): """ - Return the inverse hyperbolic tangent of self. + Return the inverse hyperbolic tangent of ``self``. EXAMPLES:: @@ -9525,9 +9463,9 @@ cdef class Expression(Expression_abc): g_hold_wrapper(g_atanh, self._gobj, hold)) def exp(self, hold=False): - """ - Return exponential function of self, i.e., e to the - power of self. + r""" + Return exponential function of ``self``, i.e., `e` to the + power of ``self``. EXAMPLES:: @@ -9582,7 +9520,7 @@ cdef class Expression(Expression_abc): def log(self, b=None, hold=False): """ - Return the logarithm of self. + Return the logarithm of ``self``. EXAMPLES:: @@ -9687,11 +9625,9 @@ cdef class Expression(Expression_abc): def factorial(self, hold=False): """ - Return the factorial of self. - - OUTPUT: + Return the factorial of ``self``. - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -9733,9 +9669,7 @@ cdef class Expression(Expression_abc): """ Return binomial coefficient "self choose k". - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -9787,9 +9721,7 @@ cdef class Expression(Expression_abc): """ Return the order of the expression, as in big oh notation. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -9809,7 +9741,7 @@ cdef class Expression(Expression_abc): def gamma(self, *, hold=False): """ - Return the Gamma function evaluated at self. + Return the Gamma function evaluated at ``self``. EXAMPLES:: @@ -9919,7 +9851,7 @@ cdef class Expression(Expression_abc): def default_variable(self): """ Return the default variable, which is by definition the first - variable in self, or `x` is there are no variables in self. + variable in ``self``, or `x` if there are no variables in ``self``. The result is cached. EXAMPLES:: @@ -9985,7 +9917,7 @@ cdef class Expression(Expression_abc): def normalize(self): """ - Return this expression normalized as a fraction + Return this expression normalized as a fraction. .. SEEALSO:: @@ -10031,7 +9963,6 @@ cdef class Expression(Expression_abc): (e^(4*pi) - 1)/e^(2*pi) ALGORITHM: Uses GiNaC. - """ cdef GEx r sig_on() @@ -10043,11 +9974,11 @@ cdef class Expression(Expression_abc): def numerator(self, bint normalize = True): """ - Return the numerator of this symbolic expression + Return the numerator of this symbolic expression. INPUT: - - ``normalize`` -- (default: ``True``) a boolean. + - ``normalize`` -- boolean (default: ``True``) If ``normalize`` is ``True``, the expression is first normalized to have it as a fraction before getting the numerator. @@ -10139,11 +10070,11 @@ cdef class Expression(Expression_abc): def denominator(self, bint normalize=True): """ - Return the denominator of this symbolic expression + Return the denominator of this symbolic expression. INPUT: - - ``normalize`` -- (default: ``True``) a boolean. + - ``normalize`` -- boolean (default: ``True``) If ``normalize`` is ``True``, the expression is first normalized to have it as a fraction before getting the denominator. @@ -10230,11 +10161,11 @@ cdef class Expression(Expression_abc): def numerator_denominator(self, bint normalize=True): """ - Return the numerator and the denominator of this symbolic expression + Return the numerator and the denominator of this symbolic expression. INPUT: - - ``normalize`` -- (default: ``True``) a boolean. + - ``normalize`` -- boolean (default: ``True``) If ``normalize`` is ``True``, the expression is first normalized to have it as a fraction before getting the numerator and denominator. @@ -10339,11 +10270,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``var`` -- variable name or string (default: first variable) - - OUTPUT: + - ``var`` -- variable name or string (default: first variable) - A symbolic expression + OUTPUT: a symbolic expression .. SEEALSO:: :meth:`partial_fraction_decomposition` @@ -10381,11 +10310,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``var`` -- variable name or string (default: first variable) + - ``var`` -- variable name or string (default: first variable) - OUTPUT: - - A list of symbolic expressions + OUTPUT: list of symbolic expressions .. SEEALSO:: :meth:`partial_fraction` @@ -10449,7 +10376,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``self`` -- the expression to convert. + - ``self`` -- the expression to convert OUTPUT: @@ -10531,7 +10458,7 @@ cdef class Expression(Expression_abc): INPUT: - ``self`` -- an expression with held operations - - ``exclude`` -- (default: None) a list of operators to exclude from + - ``exclude`` -- (default: ``None``) a list of operators to exclude from evaluation. Excluding arithmetic operators does not yet work (see :issue:`10169`). @@ -10622,11 +10549,11 @@ cdef class Expression(Expression_abc): 1/2*I*x + 1/2*I*sqrt(x^2 - 1) + 1/2/(I*x + I*sqrt(x^2 - 1)) sage: ex.simplify() 1/2*I*x + 1/2*I*sqrt(x^2 - 1) + 1/(2*I*x + 2*I*sqrt(x^2 - 1)) - sage: ex.simplify(algorithm="sympy") + sage: ex.simplify(algorithm='sympy') I*(x^2 + sqrt(x^2 - 1)*x - 1)/(x + sqrt(x^2 - 1)) - sage: ex.simplify(algorithm="giac") + sage: ex.simplify(algorithm='giac') I*sqrt(x^2 - 1) - sage: ex.simplify(algorithm="fricas") # optional - fricas + sage: ex.simplify(algorithm='fricas') # optional - fricas (I*x^2 + I*sqrt(x^2 - 1)*x - I)/(x + sqrt(x^2 - 1)) TESTS: @@ -10658,7 +10585,7 @@ cdef class Expression(Expression_abc): """ Apply :meth:`simplify_factorial`, :meth:`simplify_rectform`, :meth:`simplify_trig`, :meth:`simplify_rational`, and - then :meth:`expand_sum` to self (in that order). + then :meth:`expand_sum` to ``self`` (in that order). ALIAS: ``simplify_full`` and ``full_simplify`` are the same. @@ -10776,7 +10703,6 @@ cdef class Expression(Expression_abc): -2*((x + 1)*e^(-x) - 1)*e^x/x^2 sage: (2 * hypergeometric_U(1, 3, x)).simplify_hypergeometric() 2*(x + 1)/x^2 - """ from sage.functions.hypergeometric import (hypergeometric, hypergeometric_M, @@ -10827,7 +10753,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``self`` -- the expression to simplify. + - ``self`` -- the expression to simplify - ``complexity_measure`` -- (default: ``sage.symbolic.complexity_measures.string_length``) a @@ -10883,7 +10809,6 @@ cdef class Expression(Expression_abc): sage: g = f.simplify_rectform(complexity_measure = None) sage: bool(g == f.rectform()) True - """ simplified_expr = self.rectform() @@ -10903,7 +10828,7 @@ cdef class Expression(Expression_abc): INPUT: - - ``self`` -- the expression to convert. + - ``self`` -- the expression to convert OUTPUT: @@ -10971,7 +10896,6 @@ cdef class Expression(Expression_abc): x sage: assumptions() [] - """ from sage.symbolic.assumptions import assume, assumptions, forget from sage.calculus.calculus import maxima @@ -11016,9 +10940,9 @@ cdef class Expression(Expression_abc): - ``self`` -- symbolic expression - - ``expand`` -- (default: ``True``) if True, expands trigonometric - and hyperbolic functions of sums of angles and of multiple - angles occurring in ``self`` first. For best results, + - ``expand`` -- boolean (default: ``True``); if ``True``, expands + trigonometric and hyperbolic functions of sums of angles and of + multiple angles occurring in ``self`` first. For best results, ``self`` should be expanded. See also :meth:`expand_trig` to get more controls on this expansion. @@ -11064,18 +10988,18 @@ cdef class Expression(Expression_abc): - ``self`` -- symbolic expression - - ``algorithm`` -- (default: 'full') string which switches the + - ``algorithm`` -- (default: ``'full'``) string which switches the algorithm for simplifications. Possible values are - - 'simple' (simplify rational functions into quotient of two - polynomials), + - ``'simple'`` (simplify rational functions into quotient of two + polynomials) - - 'full' (apply repeatedly, if necessary) + - ``'full'`` (apply repeatedly, if necessary) - - 'noexpand' (convert to common denominator and add) + - ``'noexpand'`` (convert to common denominator and add) - - ``map`` -- (default: ``False``) if ``True``, the result is an - expression whose leading operator is the same as that of the + - ``map`` -- boolean (default: ``False``); if ``True``, the result is + an expression whose leading operator is the same as that of the expression ``self`` but whose subparts are the results of applying simplification rules to the corresponding subparts of the expressions. @@ -11212,7 +11136,6 @@ cdef class Expression(Expression_abc): gamma(4/3) sage: gamma(4/3).full_simplify() 1/3*gamma(1/3) - """ return self.parent()(self._maxima_().makefact().factcomb().minfactorial()) @@ -11507,7 +11430,7 @@ cdef class Expression(Expression_abc): - ``self`` -- expression to be simplified - - ``algorithm`` -- (default: None) optional, governs the condition + - ``algorithm`` -- (default: ``None``) governs the condition on `a` and `c` which must be satisfied to contract expression `a \log(b) + c \log(d)`. Values are @@ -11655,16 +11578,16 @@ cdef class Expression(Expression_abc): - ``self`` -- expression to be simplified - - ``algorithm`` -- (default: 'products') optional, governs which + - ``algorithm`` -- (default: ``'products'``) governs which expression is expanded. Possible values are - - 'nothing' (no expansion), + - ``'nothing'`` (no expansion), - - 'powers' (log(a^r) is expanded), + - ``'powers'`` (log(a^r) is expanded), - - 'products' (like 'powers' and also log(a*b) are expanded), + - ``'products'`` (like 'powers' and also log(a*b) are expanded), - - 'all' (all possible expansion). + - ``'all'`` (all possible expansion). See also examples below. @@ -11778,12 +11701,12 @@ cdef class Expression(Expression_abc): INPUT: - - ``recursive`` -- (default : True) the distribution proceeds - along the subtrees of the expression. + - ``recursive`` -- (default: ``True``) the distribution proceeds + along the subtrees of the expression TESTS: - sage: var("j,k,p,q", domain="integer") + sage: var("j,k,p,q", domain='integer') (j, k, p, q) sage: X,Y,Z,f,g = function("X,Y,Z,f,g") sage: var("x,a,b") @@ -11874,15 +11797,13 @@ cdef class Expression(Expression_abc): INPUT: + - ``self`` -- a symbolic expression - - ``self`` -- a symbolic expression - - - ``dontfactor`` -- list (default: ``[]``), a list of - variables with respect to which factoring is not to occur. - Factoring also will not take place with respect to any variables - which are less important (using the variable ordering assumed for - CRE form) than those on the 'dontfactor' list. - + - ``dontfactor`` -- list (default: ``[]``); a list of + variables with respect to which factoring is not to occur. + Factoring also will not take place with respect to any variables + which are less important (using the variable ordering assumed for + CRE form) than those on the 'dontfactor' list. EXAMPLES:: @@ -11964,9 +11885,9 @@ cdef class Expression(Expression_abc): INPUT: - - ``self`` -- a symbolic expression + - ``self`` -- a symbolic expression - - ``dontfactor`` -- see docs for :meth:`factor` + - ``dontfactor`` -- see docs for :meth:`factor` .. NOTE:: @@ -12060,12 +11981,10 @@ cdef class Expression(Expression_abc): INPUT: - ``self`` -- the symbolic expression converting from - - ``target`` -- (default None) the symbolic expression + - ``target`` -- (default: ``None``) the symbolic expression converting to - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -12080,7 +11999,7 @@ cdef class Expression(Expression_abc): sage: a - a.convert() 0 - Raises ValueError if self and target are not convertible:: + Raises :exc:`ValueError` if ``self`` and ``target`` are not convertible:: sage: units.mass.kilogram.convert(units.length.foot) Traceback (most recent call last): @@ -12149,13 +12068,13 @@ cdef class Expression(Expression_abc): - ``x`` -- variable to view the function in terms of (use default variable if not given) - - ``explicit_solutions`` -- bool (default ``True``); require that + - ``explicit_solutions`` -- boolean (default: ``True``); require that roots be explicit rather than implicit - - ``multiplicities`` -- bool (default ``True``); when ``True``, return + - ``multiplicities`` -- boolean (default: ``True``); when ``True``, return multiplicities - - ``ring`` -- a ring (default ``None``): if not ``None``, convert + - ``ring`` -- a ring (default: ``None``); if not ``None``, convert ``self`` to a polynomial over ``ring`` and find roots over ``ring`` OUTPUT: @@ -12324,28 +12243,28 @@ cdef class Expression(Expression_abc): INPUT: - - ``x`` -- variable(s) to solve for + - ``x`` -- variable(s) to solve for - - ``multiplicities`` -- bool (default: ``False``); if ``True``, - return corresponding multiplicities. This keyword is - incompatible with ``to_poly_solve=True`` and does not make - any sense when solving an inequality. + - ``multiplicities`` -- boolean (default: ``False``); if ``True``, + return corresponding multiplicities. This keyword is + incompatible with ``to_poly_solve=True`` and does not make + any sense when solving an inequality. - - ``solution_dict`` -- bool (default: ``False``); if ``True`` or non-zero, - return a list of dictionaries containing solutions. Not used - when solving an inequality. + - ``solution_dict`` -- boolean (default: ``False``); if ``True`` or nonzero, + return a list of dictionaries containing solutions. Not used + when solving an inequality. - - ``explicit_solutions`` -- bool (default: ``False``); require that - all roots be explicit rather than implicit. Not used - when solving an inequality. + - ``explicit_solutions`` -- boolean (default: ``False``); require that + all roots be explicit rather than implicit. Not used + when solving an inequality. - - ``to_poly_solve`` -- bool (default: ``False``) or string; use - Maxima's ``to_poly_solver`` package to search for more possible - solutions, but possibly encounter approximate solutions. - This keyword is incompatible with ``multiplicities=True`` - and is not used when solving an inequality. Setting ``to_poly_solve`` - to ``'force'`` omits Maxima's solve command (useful when - some solutions of trigonometric equations are lost). + - ``to_poly_solve`` -- boolean (default: ``False``) or string; use + Maxima's ``to_poly_solver`` package to search for more possible + solutions, but possibly encounter approximate solutions. + This keyword is incompatible with ``multiplicities=True`` + and is not used when solving an inequality. Setting ``to_poly_solve`` + to ``'force'`` omits Maxima's solve command (useful when + some solutions of trigonometric equations are lost). EXAMPLES:: @@ -12511,22 +12430,22 @@ cdef class Expression(Expression_abc): INPUT: - - ``a``, ``b`` -- endpoints of the interval + - ``a``, ``b`` -- endpoints of the interval - - ``var`` -- optional variable + - ``var`` -- (optional) variable - - ``xtol, rtol`` -- the routine converges when a root - is known to lie within ``xtol`` of the value return. Should be >= 0. The - routine modifies this to take into account the relative precision - of doubles. + - ``xtol, rtol`` -- the routine converges when a root is known to lie + within ``xtol`` of the value return. Should be nonnegative. The + routine modifies this to take into account the relative precision of + doubles. - - ``maxiter`` -- integer; if convergence is not - achieved in maxiter iterations, an error is raised. Must be >= 0. + - ``maxiter`` -- integer; if convergence is not achieved in maxiter + iterations, an error is raised. Must be nonnegative. - - ``full_output`` -- bool (default: ``False``), if ``True``, - also return object that contains information about convergence. + - ``full_output`` -- boolean (default: ``False``); if ``True``, + also return object that contains information about convergence - - ``imaginary_tolerance`` -- (default: ``1e-8``); if an imaginary + - ``imaginary_tolerance`` -- (default: ``1e-8``) if an imaginary number arises (due, for example, to numerical issues), this tolerance specifies how large it has to be in magnitude before we raise an error. In other words, imaginary parts smaller than @@ -12640,7 +12559,6 @@ cdef class Expression(Expression_abc): sage: f = (sqrt(x) - I).abs() sage: f.find_root(-2, 2, rtol=1e-6) # abs tol 1e-6 # needs scipy -1.0000000049668551 - """ if is_a_relational(self._gobj) and self.operator() is not operator.eq: raise ValueError("Symbolic equation must be an equality.") @@ -12697,22 +12615,20 @@ cdef class Expression(Expression_abc): INPUT: - - ``a`` -- real number; left endpoint of interval on which to - minimize + - ``a`` -- real number; left endpoint of interval on which to minimize - - ``b`` -- real number; right endpoint of interval on which to - minimize + - ``b`` -- real number; right endpoint of interval on which to minimize - - ``var`` -- variable (default: first variable in self); the - variable in self to maximize over + - ``var`` -- variable (default: first variable in ``self``); the + variable in ``self`` to maximize over - - ``tol`` -- positive real (default: 1.48e-08); the convergence - tolerance + - ``tol`` -- positive real (default: 1.48e-08); the convergence + tolerance - - ``maxfun`` -- natural number (default: 500); maximum function - evaluations + - ``maxfun`` -- natural number (default: 500); maximum function + evaluations - - ``imaginary_tolerance`` -- (default: ``1e-8``); if an imaginary + - ``imaginary_tolerance`` -- (default: ``1e-8``) if an imaginary number arises (due, for example, to numerical issues), this tolerance specifies how large it has to be in magnitude before we raise an error. In other words, imaginary parts smaller than @@ -12722,11 +12638,11 @@ cdef class Expression(Expression_abc): A tuple ``(minval, x)``, where - - ``minval`` -- float. The minimum value that self takes on in - the interval ``[a,b]``. + - ``minval`` -- float; the minimum value that ``self`` takes on in + the interval ``[a,b]`` - - ``x`` -- float. The point at which self takes on the minimum - value. + - ``x`` -- float; the point at which ``self`` takes on the minimum + value EXAMPLES:: @@ -12977,18 +12893,18 @@ cdef class Expression(Expression_abc): ############ def sum(self, *args, **kwds): r""" - Return the symbolic sum `\sum_{v = a}^b` ``self`` + Return the symbolic sum `\sum_{v = a}^b` ``self``. with respect to the variable `v` with endpoints `a` and `b`. INPUT: - - ``v`` -- a variable or variable name + - ``v`` -- a variable or variable name - - ``a`` -- lower endpoint of the sum + - ``a`` -- lower endpoint of the sum - - ``b`` -- upper endpoint of the sum + - ``b`` -- upper endpoint of the sum - ``algorithm`` -- (default: ``'maxima'``) one of @@ -13177,7 +13093,7 @@ cdef class Expression(Expression_abc): - ``'giac'`` -- (optional) use Giac - ``'sympy'`` -- use SymPy - - ``hold`` -- (default: ``False``) if ``True``, don't evaluate + - ``hold`` -- boolean (default: ``False``); if ``True``, don't evaluate TESTS: @@ -13462,15 +13378,17 @@ cdef class Expression(Expression_abc): def implicit_derivative(self, Y, X, n=1): """ - Return the `n`-th derivative of `Y` with respect to `X` given implicitly by this expression. + Return the `n`-th derivative of `Y` with respect to `X` given + implicitly by this expression. INPUT: - - ``Y`` -- The dependent variable of the implicit expression. + - ``Y`` -- the dependent variable of the implicit expression - - ``X`` -- The independent variable with respect to which the derivative is taken. + - ``X`` -- the independent variable with respect to which the + derivative is taken - - ``n`` -- (default: 1) the order of the derivative. + - ``n`` -- (default: 1) the order of the derivative EXAMPLES:: @@ -13826,15 +13744,15 @@ cpdef new_Expression_from_pyobject(parent, x, bint force=True, bint recursive=Tr INPUT: - - ``parent`` -- a symbolic ring. + - ``parent`` -- a symbolic ring - - ``x`` -- a Python object. + - ``x`` -- a Python object - - ``force`` -- bool, default ``True``, if True, the Python object - is taken as is without attempting coercion or list traversal. + - ``force`` -- boolean (default: ``True``); if ``True``, the Python object + is taken as is without attempting coercion or list traversal - - ``recursive`` -- bool, default ``True``, disables recursive - traversal of lists. + - ``recursive`` -- boolean (default: ``True``); disables recursive + traversal of lists EXAMPLES:: @@ -13896,13 +13814,11 @@ cpdef new_Expression_wild(parent, unsigned int n=0): INPUT: - - ``parent`` -- a symbolic ring. - - - ``n`` -- a nonnegative integer. + - ``parent`` -- a symbolic ring - OUTPUT: + - ``n`` -- nonnegative integer - - ``n``-th wildcard expression. + OUTPUT: n-th wildcard expression EXAMPLES:: diff --git a/src/sage/symbolic/expression_conversion_algebraic.py b/src/sage/symbolic/expression_conversion_algebraic.py index a8b932c75f2..9772fb8d94a 100644 --- a/src/sage/symbolic/expression_conversion_algebraic.py +++ b/src/sage/symbolic/expression_conversion_algebraic.py @@ -264,8 +264,8 @@ def composition(self, ex, operator): def algebraic(ex, field): """ - Returns the symbolic expression *ex* as a element of the algebraic - field *field*. + Return the symbolic expression ``ex`` as a element of the algebraic + field ``field``. EXAMPLES:: diff --git a/src/sage/symbolic/expression_conversion_sympy.py b/src/sage/symbolic/expression_conversion_sympy.py index e7aaf3bd656..ecfffc6841d 100644 --- a/src/sage/symbolic/expression_conversion_sympy.py +++ b/src/sage/symbolic/expression_conversion_sympy.py @@ -28,7 +28,7 @@ ######### class SympyConverter(Converter): """ - Converts any expression to SymPy. + Convert any expression to SymPy. EXAMPLES:: @@ -52,7 +52,6 @@ class SympyConverter(Converter): True sage: (x+I)._sympy_() x + I - """ def __init__(self): """ @@ -60,7 +59,7 @@ def __init__(self): sage: from sage.symbolic.expression_conversions import SympyConverter sage: s = SympyConverter() # indirect doctest - sage: TestSuite(s).run(skip="_test_pickling") + sage: TestSuite(s).run(skip='_test_pickling') """ from sage.interfaces.sympy import sympy_init sympy_init() diff --git a/src/sage/symbolic/expression_conversions.py b/src/sage/symbolic/expression_conversions.py index 486bb4324b1..245660de06a 100644 --- a/src/sage/symbolic/expression_conversions.py +++ b/src/sage/symbolic/expression_conversions.py @@ -278,7 +278,7 @@ def pyobject(self, ex, obj): The input to this method is the result of calling :meth:`pyobject` on a symbolic expression. - .. note:: + .. NOTE:: Note that if a constant such as ``pi`` is encountered in the expression tree, its corresponding pyobject which is an @@ -400,7 +400,6 @@ def __init__(self, interface): 'sin((%pi)+(2))' sage: m(exp(x^2) + pi + 2) '(%pi)+(exp((_SAGE_VAR_x)^(2)))+(2)' - """ self.name_init = "_%s_init_" % interface.name() self.interface = interface @@ -662,7 +661,7 @@ def composition(self, ex, operator): ########## class FriCASConverter(InterfaceInit): """ - Converts any expression to FriCAS. + Convert any expression to FriCAS. EXAMPLES:: @@ -675,7 +674,6 @@ class FriCASConverter(InterfaceInit): y %e - asin(x + %pi) ---------------------- y - """ def __init__(self): import sage.interfaces.fricas @@ -729,7 +727,6 @@ def pyobject(self, ex, obj): sage: (ex^2)._fricas_() # optional - fricas +-+ (4 + 2 %i)\|2 + 5 + 4 %i - """ try: result = getattr(obj, self.name_init)() @@ -764,7 +761,6 @@ def symbol(self, ex): sage: (2*x)._fricas_().integrate(x) # optional - fricas 2 x - """ return repr(ex) @@ -780,7 +776,6 @@ def derivative(self, ex, operator): Note that ``ex.operator() == operator``. - EXAMPLES:: sage: var('x,y,z') @@ -797,10 +792,10 @@ def derivative(self, ex, operator): sage: var('x') x sage: F = function('F') - sage: integrate(F(x), x, algorithm="fricas") # optional - fricas + sage: integrate(F(x), x, algorithm='fricas') # optional - fricas integral(F(x), x) - sage: integrate(diff(F(x), x)*sin(F(x)), x, algorithm="fricas") # optional - fricas + sage: integrate(diff(F(x), x)*sin(F(x)), x, algorithm='fricas') # optional - fricas -cos(F(x)) Check that :issue:`27310` is fixed:: @@ -813,7 +808,6 @@ def derivative(self, ex, operator): sage: fricas(ex) # optional - fricas F (x,y + x) ,1,1,2 - """ args = ex.operands() # the arguments the derivative is evaluated at params = operator.parameter_set() @@ -914,7 +908,7 @@ def __init__(self, ex, base_ring=None, ring=None): def symbol(self, ex): """ - Returns a variable in the polynomial ring. + Return a variable in the polynomial ring. EXAMPLES:: @@ -1034,15 +1028,13 @@ def polynomial(ex, base_ring=None, ring=None): - ``ex`` -- a symbolic expression - - ``base_ring``, ``ring`` -- Either a + - ``base_ring``, ``ring`` -- either a ``base_ring`` or a polynomial ``ring`` can be specified for the parent of result. If just a ``base_ring`` is given, then the variables of the ``base_ring`` will be the variables of the expression ``ex``. - OUTPUT: - - A polynomial. + OUTPUT: a polynomial EXAMPLES:: @@ -1123,15 +1115,13 @@ def laurent_polynomial(ex, base_ring=None, ring=None): - ``ex`` -- a symbolic expression - - ``base_ring``, ``ring`` -- Either a + - ``base_ring``, ``ring`` -- either a ``base_ring`` or a Laurent polynomial ``ring`` can be specified for the parent of result. If just a ``base_ring`` is given, then the variables of the ``base_ring`` will be the variables of the expression ``ex``. - OUTPUT: - - A Laurent polynomial. + OUTPUT: a Laurent polynomial EXAMPLES:: @@ -1338,7 +1328,6 @@ def fast_callable(ex, etb): sage: f = (2*x^3+2*x-1)/((x-2)*(x+1)) sage: f._fast_callable_(etb) div(add(add(mul(ipow(v_0, 3), 2), mul(v_0, 2)), -1), mul(add(v_0, 1), add(v_0, -2))) - """ return FastCallableConverter(ex, etb)() @@ -1648,7 +1637,6 @@ def derivative(self, ex, operator): sage: g = function('g') sage: f(g(x)).diff(x).substitute_function({g: sin}) cos(x)*D[0](f)(sin(x)) - """ new = self.substitutions.get(operator.function()) if new is not None: diff --git a/src/sage/symbolic/function.pyx b/src/sage/symbolic/function.pyx index cd89ad2a256..362d01ea297 100644 --- a/src/sage/symbolic/function.pyx +++ b/src/sage/symbolic/function.pyx @@ -267,7 +267,6 @@ cdef class Function(SageObject): f(x) sage: deepcopy(f) f(x) - """ self._serial = register_or_update_function(self, self._name, self._latex_name, self._nargs, self._evalf_params_first, @@ -397,7 +396,6 @@ cdef class Function(SageObject): False sage: foo(1, 2).operator() == foo True - """ try: return richcmp((self)._serial, @@ -610,7 +608,7 @@ cdef class Function(SageObject): def _is_numerical(self, x): """ - Return True if `x` is a numerical object. + Return ``True`` if `x` is a numerical object. This is used to determine whether to call the :meth:`_evalf_` method instead of the :meth:`_eval_` method. @@ -805,7 +803,6 @@ cdef class Function(SageObject): sage: with mpmath.workprec(64): noMpmathFn(sqrt(mpmath.mpf('2'))) 123 sage: del mpmath.noMpmathFn - """ import mpmath from sage.libs.mpmath.utils import mpmath_to_sage, sage_to_mpmath diff --git a/src/sage/symbolic/function_factory.py b/src/sage/symbolic/function_factory.py index 7c5b660f3bb..d626eb9bd65 100644 --- a/src/sage/symbolic/function_factory.py +++ b/src/sage/symbolic/function_factory.py @@ -159,11 +159,11 @@ def function(s, **kwds) -> Union[SymbolicFunction, list[SymbolicFunction]]: - ``nargs=0`` -- number of arguments the function accepts, defaults to variable number of arguments, or 0 - ``latex_name`` -- name used when printing in latex mode - - ``conversions`` -- a dictionary specifying names of this function in + - ``conversions`` -- dictionary specifying names of this function in other systems, this is used by the interfaces internally during conversion - ``eval_func`` -- method used for automatic evaluation - ``evalf_func`` -- method used for numeric evaluation - - ``evalf_params_first`` -- bool to indicate if parameters should be + - ``evalf_params_first`` -- boolean to indicate if parameters should be evaluated numerically before calling the custom evalf function - ``conjugate_func`` -- method used for complex conjugation - ``real_part_func`` -- method used when taking real parts diff --git a/src/sage/symbolic/ginac/pseries.h b/src/sage/symbolic/ginac/pseries.h index 17a85f258b9..6073d1d360f 100644 --- a/src/sage/symbolic/ginac/pseries.h +++ b/src/sage/symbolic/ginac/pseries.h @@ -29,7 +29,7 @@ namespace GiNaC { /** This class holds a extended truncated power series (positive and negative - * integer powers). It consists of expression coefficients (only non-zero + * integer powers). It consists of expression coefficients (only nonzero * coefficients are stored), an expansion variable and an expansion point. * Other classes must provide members to convert into this type. */ class pseries : public basic diff --git a/src/sage/symbolic/integration/external.py b/src/sage/symbolic/integration/external.py index ea73c69ff74..968d0e7e7c3 100644 --- a/src/sage/symbolic/integration/external.py +++ b/src/sage/symbolic/integration/external.py @@ -12,7 +12,7 @@ def maxima_integrator(expression, v, a=None, b=None): """ - Integration using Maxima + Integration using Maxima. EXAMPLES:: @@ -49,7 +49,7 @@ def maxima_integrator(expression, v, a=None, b=None): def sympy_integrator(expression, v, a=None, b=None): """ - Integration using SymPy + Integration using SymPy. EXAMPLES:: @@ -71,7 +71,7 @@ def sympy_integrator(expression, v, a=None, b=None): def mma_free_integrator(expression, v, a=None, b=None): """ - Integration using Mathematica's online integrator + Integration using Mathematica's online integrator. EXAMPLES:: @@ -96,19 +96,17 @@ def mma_free_integrator(expression, v, a=None, b=None): Check that :issue:`14764` is resolved:: - sage: integrate(x^2, x, 0, 1, algorithm="mathematica_free") # optional - internet + sage: integrate(x^2, x, 0, 1, algorithm='mathematica_free') # optional - internet 1/3 - sage: integrate(sin(x), [x, 0, pi], algorithm="mathematica_free") # optional - internet + sage: integrate(sin(x), [x, 0, pi], algorithm='mathematica_free') # optional - internet 2 - sage: integrate(sqrt(x), (x, 0, 1), algorithm="mathematica_free") # optional - internet + sage: integrate(sqrt(x), (x, 0, 1), algorithm='mathematica_free') # optional - internet 2/3 :: sage: mma_free_integrator(exp(-x^2)*log(x), x) # optional - internet 1/2*sqrt(pi)*erf(x)*log(x) - x*hypergeometric((1/2, 1/2), (3/2, 3/2), -x^2) - - """ from sage.interfaces.mathematica import request_wolfram_alpha, parse_moutput_from_json, symbolic_expression_from_mathematica_string math_expr = expression._mathematica_init_() @@ -132,7 +130,7 @@ def mma_free_integrator(expression, v, a=None, b=None): def fricas_integrator(expression, v, a=None, b=None, noPole=True): """ - Integration using FriCAS + Integration using FriCAS. EXAMPLES:: @@ -151,7 +149,7 @@ def fricas_integrator(expression, v, a=None, b=None, noPole=True): Check that :issue:`25220` is fixed:: - sage: integral(sqrt(1-cos(x)), x, 0, 2*pi, algorithm="fricas") # optional - fricas + sage: integral(sqrt(1-cos(x)), x, 0, 2*pi, algorithm='fricas') # optional - fricas 4*sqrt(2) Check that in case of failure one gets unevaluated integral:: @@ -164,13 +162,13 @@ def fricas_integrator(expression, v, a=None, b=None, noPole=True): Check that :issue:`28641` is fixed:: - sage: integrate(sqrt(2)*x^2 + 2*x, x, algorithm="fricas") # optional - fricas + sage: integrate(sqrt(2)*x^2 + 2*x, x, algorithm='fricas') # optional - fricas 1/3*sqrt(2)*x^3 + x^2 - sage: integrate(sqrt(2), x, algorithm="fricas") # optional - fricas + sage: integrate(sqrt(2), x, algorithm='fricas') # optional - fricas sqrt(2)*x - sage: integrate(1, x, algorithm="fricas") # optional - fricas + sage: integrate(1, x, algorithm='fricas') # optional - fricas x Check that :issue:`28630` is fixed:: @@ -183,7 +181,7 @@ def fricas_integrator(expression, v, a=None, b=None, noPole=True): sage: var("a c d"); f = (I*a*tan(d*x + c) + a)*sec(d*x + c)^10 (a, c, d) - sage: ii = integrate(f, x, algorithm="fricas") # optional - fricas + sage: ii = integrate(f, x, algorithm='fricas') # optional - fricas sage: 1/315*(64512*I*a*e^(10*I*d*x + 10*I*c) + 53760*I*a*e^(8*I*d*x + 8*I*c) + 30720*I*a*e^(6*I*d*x + 6*I*c) + 11520*I*a*e^(4*I*d*x + 4*I*c) + 2560*I*a*e^(2*I*d*x + 2*I*c) + 256*I*a)/(d*e^(20*I*d*x + 20*I*c) + 10*d*e^(18*I*d*x + 18*I*c) + 45*d*e^(16*I*d*x + 16*I*c) + 120*d*e^(14*I*d*x + 14*I*c) + 210*d*e^(12*I*d*x + 12*I*c) + 252*d*e^(10*I*d*x + 10*I*c) + 210*d*e^(8*I*d*x + 8*I*c) + 120*d*e^(6*I*d*x + 6*I*c) + 45*d*e^(4*I*d*x + 4*I*c) + 10*d*e^(2*I*d*x + 2*I*c) + d) - ii # optional - fricas 0 """ @@ -218,7 +216,7 @@ def fricas_integrator(expression, v, a=None, b=None, noPole=True): def giac_integrator(expression, v, a=None, b=None): r""" - Integration using Giac + Integration using Giac. EXAMPLES:: @@ -259,7 +257,7 @@ def giac_integrator(expression, v, a=None, b=None): def libgiac_integrator(expression, v, a=None, b=None): r""" - Integration using libgiac + Integration using libgiac. EXAMPLES:: diff --git a/src/sage/symbolic/integration/integral.py b/src/sage/symbolic/integration/integral.py index ebf0048dfe8..70bb877e5a1 100644 --- a/src/sage/symbolic/integration/integral.py +++ b/src/sage/symbolic/integration/integral.py @@ -60,7 +60,7 @@ def __init__(self): Check for :issue:`28913`:: sage: Ex = (1-2*x^(1/3))^(3/4)/x - sage: integrate(Ex, x, algorithm="giac") # long time + sage: integrate(Ex, x, algorithm='giac') # long time 4*(-2*x^(1/3) + 1)^(3/4) + 6*arctan((-2*x^(1/3) + 1)^(1/4)) - 3*log((-2*x^(1/3) + 1)^(1/4) + 1) + 3*log(abs((-2*x^(1/3) + 1)^(1/4) - 1)) Check for :issue:`29833`:: @@ -68,7 +68,7 @@ def __init__(self): sage: (x,a,b)=var('x a b') sage: assume(b > 0) sage: f = (exp((x-a)/b) + 1)**(-1) - sage: (f*f).integrate(x, algorithm="mathematica_free") # optional -- internet + sage: (f*f).integrate(x, algorithm='mathematica_free') # optional -- internet -b*log(e^(a/b) + e^(x/b)) + x + b/(e^(-(a - x)/b) + 1) Check for :issue:`25119`:: @@ -392,9 +392,7 @@ def _normalize_integral_input(f, v, a=None, b=None): If the input contains endpoints, both endpoints must be given. - OUTPUT: - - - a tuple of ``f``, ``v``, ``a``, and ``b``. + OUTPUT: a tuple of ``f``, ``v``, ``a``, and ``b`` EXAMPLES:: @@ -452,8 +450,8 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): INPUT: - - ``v`` -- a variable or variable name. This can also be a tuple of - the variable (optional) and endpoints (i.e., ``(x,0,1)`` or ``(0,1)``). + - ``v`` -- a variable or variable name; this can also be a tuple of + the variable (optional) and endpoints (i.e., ``(x,0,1)`` or ``(0,1)``) - ``a`` -- (optional) lower endpoint of definite integral @@ -615,7 +613,7 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): sage: _ = var('x, y, z') # optional - internet sage: f = sin(x^2) + y^z # optional - internet - sage: f.integrate(x, algorithm="mathematica_free") # optional - internet + sage: f.integrate(x, algorithm='mathematica_free') # optional - internet x*y^z + sqrt(1/2)*sqrt(pi)*fresnel_sin(sqrt(2)*x/sqrt(pi)) We can also use Sympy:: @@ -627,7 +625,7 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): sage: _ = var('y, z') sage: (x^y - z).integrate(y) -y*z + x^y/log(x) - sage: (x^y - z).integrate(y, algorithm="sympy") # needs sympy + sage: (x^y - z).integrate(y, algorithm='sympy') # needs sympy -y*z + cases(((log(x) != 0, x^y/log(x)), (1, y))) We integrate the above function in Maple now:: @@ -661,7 +659,7 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): An example of an integral that fricas can integrate:: sage: f(x) = sqrt(x+sqrt(1+x^2))/x - sage: integrate(f(x), x, algorithm="fricas") # optional - fricas + sage: integrate(f(x), x, algorithm='fricas') # optional - fricas 2*sqrt(x + sqrt(x^2 + 1)) - 2*arctan(sqrt(x + sqrt(x^2 + 1))) - log(sqrt(x + sqrt(x^2 + 1)) + 1) + log(sqrt(x + sqrt(x^2 + 1)) - 1) @@ -685,9 +683,9 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): Both fricas and sympy give the correct result:: - sage: integrate(f(x), x, 1, 2, algorithm="fricas") # optional - fricas + sage: integrate(f(x), x, 1, 2, algorithm='fricas') # optional - fricas -1/2*pi + arctan(8) + arctan(5) + arctan(2) + arctan(1/2) - sage: integrate(f(x), x, 1, 2, algorithm="sympy") # needs sympy + sage: integrate(f(x), x, 1, 2, algorithm='sympy') # needs sympy -1/2*pi + arctan(8) + arctan(5) + arctan(2) + arctan(1/2) Using Giac to integrate the absolute value of a trigonometric expression:: @@ -872,7 +870,7 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): sage: N(integrate(sin(x^2)/(x^2), x, 1, infinity), prec=54) 0.285736646322853 - sage: N(integrate(sin(x^2)/(x^2), x, 1, infinity)) # known bug (non-zero imag part) + sage: N(integrate(sin(x^2)/(x^2), x, 1, infinity)) # known bug (nonzero imag part) 0.285736646322853 Check that :issue:`14209` is fixed:: @@ -1047,7 +1045,7 @@ def integrate(expression, v=None, a=None, b=None, algorithm=None, hold=False): sage: var('a d x c') (a, d, x, c) sage: f = (I*a*tan(d*x + c) + a)^3*tan(d*x + c) - sage: integrate(f, x, algorithm="fricas") # optional - fricas + sage: integrate(f, x, algorithm='fricas') # optional - fricas -2/3*(24*a^3*e^(4*I*d*x + 4*I*c) + 33*a^3*e^(2*I*d*x + 2*I*c) + 13*a^3 + 6*(a^3*e^(6*I*d*x + 6*I*c) + 3*a^3*e^(4*I*d*x + 4*I*c) + 3*a^3*e^(2*I*d*x + 2*I*c) + a^3)*log(e^(2*I*d*x + 2*I*c) + 1))/(d*e^(6*I*d*x + 6*I*c) + 3*d*e^(4*I*d*x + 4*I*c) + 3*d*e^(2*I*d*x + 2*I*c) + d) The fundamental theorem of calculus holds for elliptic integrals diff --git a/src/sage/symbolic/operators.py b/src/sage/symbolic/operators.py index 07add13f71e..4e1debed2b7 100644 --- a/src/sage/symbolic/operators.py +++ b/src/sage/symbolic/operators.py @@ -123,7 +123,6 @@ def __call__(self, *args): sage: op = FDerivativeOperator(f, [0]) sage: op(1) D[0](f)(1) - """ if (not all(isinstance(x, Expression) and x.is_symbol() for x in args) or len(args) != len(set(args))): @@ -226,7 +225,6 @@ class DerivativeOperator(): diff(f(x, y), x, y) sage: D[0, 1](f)(x, x^2) D[0, 1](f)(x, x^2) - """ class DerivativeOperatorWithParameters(): def __init__(self, parameter_set): diff --git a/src/sage/symbolic/pynac_constant_impl.pxi b/src/sage/symbolic/pynac_constant_impl.pxi index 442afbafbc3..a158bbae1d9 100644 --- a/src/sage/symbolic/pynac_constant_impl.pxi +++ b/src/sage/symbolic/pynac_constant_impl.pxi @@ -25,7 +25,7 @@ cdef class PynacConstant: def __cinit__(self, name, texname, domain_string): """ - Creates a constant in Pynac. + Create a constant in Pynac. EXAMPLES:: @@ -75,7 +75,7 @@ cdef class PynacConstant: def serial(self): """ - Returns the underlying Pynac serial for this constant. + Return the underlying Pynac serial for this constant. EXAMPLES:: @@ -88,7 +88,7 @@ cdef class PynacConstant: def name(self): """ - Returns the name of this constant. + Return the name of this constant. EXAMPLES:: @@ -111,7 +111,7 @@ cdef class PynacConstant: def expression(self): """ - Returns this constant as an Expression. + Return this constant as an Expression. EXAMPLES:: diff --git a/src/sage/symbolic/pynac_function_impl.pxi b/src/sage/symbolic/pynac_function_impl.pxi index 1cc496ca213..a9faf2e7de7 100644 --- a/src/sage/symbolic/pynac_function_impl.pxi +++ b/src/sage/symbolic/pynac_function_impl.pxi @@ -13,7 +13,7 @@ cpdef call_registered_function(unsigned serial, - ``nargs`` -- declared number of args (0 is variadic) - - ``args`` -- a list of arguments to pass to the function; + - ``args`` -- list of arguments to pass to the function; each must be an :class:`Expression` - ``hold`` -- whether to leave the call unevaluated @@ -66,11 +66,9 @@ cpdef unsigned find_registered_function(name, int nargs) except -1: r""" Look up a function registered with Pynac (GiNaC). - This raises a :class:`ValueError` if the function is not registered. + Raise a :exc:`ValueError` if the function is not registered. - OUTPUT: - - - serial number of the function, for use in :func:`call_registered_function` + OUTPUT: serial number of the function, for use in :func:`call_registered_function` EXAMPLES:: @@ -93,9 +91,7 @@ cpdef unsigned register_or_update_function(self, name, latex_name, int nargs, r""" Register the function ``self`` with Pynac (GiNaC). - OUTPUT: - - - serial number of the function, for use in :func:`call_registered_function` + OUTPUT: serial number of the function, for use in :func:`call_registered_function` EXAMPLES:: diff --git a/src/sage/symbolic/pynac_impl.pxi b/src/sage/symbolic/pynac_impl.pxi index f31a5498218..fbf51f4d7ec 100644 --- a/src/sage/symbolic/pynac_impl.pxi +++ b/src/sage/symbolic/pynac_impl.pxi @@ -136,7 +136,7 @@ def unpack_operands(Expression ex): cdef exvector_to_PyTuple(GExVector seq): """ - Converts arguments list given to a function to a PyTuple. + Convert arguments list given to a function to a PyTuple. Used to pass arguments to python methods assigned to custom evaluation, derivative, etc. functions of symbolic functions. @@ -167,7 +167,6 @@ cdef exvector_to_PyTuple(GExVector seq): len(args): 2, types: [, ] len(args): 2, types: [, ] tfunc(sin(x), tfunc(1, x^2)) - """ from sage.symbolic.ring import SR res = [] @@ -182,7 +181,7 @@ cdef exvector_to_PyTuple(GExVector seq): cdef GEx pyExpression_to_ex(res) except *: """ - Converts an Expression object to a GiNaC::ex. + Convert an Expression object to a GiNaC::ex. Used to pass return values of custom python evaluation, derivation functions back to C++ level. @@ -198,7 +197,7 @@ cdef GEx pyExpression_to_ex(res) except *: cdef paramset_to_PyTuple(const_paramset_ref s): """ - Converts a std::multiset to a PyTuple. + Convert a std::multiset to a PyTuple. Used to pass a list of parameter numbers with respect to which a function is differentiated to the printing functions py_print_fderivative and @@ -238,7 +237,7 @@ cdef set_ginac_fn_serial(): cdef int py_get_ginac_serial() noexcept: """ - Returns the number of C++ level functions defined by GiNaC. + Return the number of C++ level functions defined by GiNaC. EXAMPLES:: @@ -378,7 +377,7 @@ cdef stdstring* py_latex(o, int level) noexcept: cdef stdstring* string_from_pystr(py_str) except NULL: """ - Creates a C++ string with the same contents as the given python string. + Create a C++ string with the same contents as the given python string. Used when passing string output to Pynac for printing, since we don't want to mess with reference counts of the python objects and we cannot guarantee @@ -448,10 +447,10 @@ def py_print_function_pystring(id, args, fname_paren=False): INPUT: - - id -- serial number of the corresponding symbolic function - - params -- Set of parameter numbers with respect to which to take the - derivative. - - args -- arguments of the function. + - ``id`` -- serial number of the corresponding symbolic function + - ``params`` -- set of parameter numbers with respect to which to take the + derivative + - ``args`` -- arguments of the function EXAMPLES:: @@ -558,8 +557,6 @@ def py_latex_function_pystring(id, args, fname_paren=False): True sage: py_latex_function_pystring(i, (x,y^z)) 'my args are: x, y^z' - - """ cdef Function func = get_sfunction_from_serial(id) # This function is called from two places, from function::print in Pynac @@ -635,10 +632,10 @@ cdef stdstring* py_print_fderivative(unsigned id, params, INPUT: - - id -- serial number of the corresponding symbolic function - - params -- Set of parameter numbers with respect to which to take the - derivative. - - args -- arguments of the function. + - ``id`` -- serial number of the corresponding symbolic function + - ``params`` -- set of parameter numbers with respect to which to take the + derivative + - ``args`` -- arguments of the function """ if all(tolerant_is_symbol(a) for a in args) and len(set(args)) == len(args): diffvarstr = ', '.join(repr(args[i]) for i in params) @@ -681,7 +678,6 @@ def py_print_fderivative_for_doctests(id, params, args): True sage: py_print_fderivative(i, (0, 1, 0, 1), (x, y^z)) D[0, 1, 0, 1]func_with_args(x, y^z) - """ cdef stdstring* ostr = py_print_fderivative(id, params, args) print(char_to_str(ostr.c_str())) @@ -695,7 +691,6 @@ cdef stdstring* py_latex_fderivative(unsigned id, params, symbolic function specified by the given id, lists of params and args. See documentation of py_print_fderivative for more information. - """ if all(tolerant_is_symbol(a) for a in args) and len(set(args)) == len(args): param_iter = iter(params) @@ -927,11 +922,9 @@ def test_binomial(n, k): INPUT: - - n, k -- integers, with k >= 0. - - OUTPUT: + - ``n``, ``k`` -- integers, with ``k >= 0`` - integer + OUTPUT: integer EXAMPLES:: @@ -989,7 +982,7 @@ cdef py_lcm(n, k): ################################################################# cdef py_real(x): """ - Returns the real part of x. + Return the real part of x. TESTS:: @@ -1118,14 +1111,14 @@ cdef bint py_is_rational(x) noexcept: cdef bint py_is_equal(x, y) noexcept: """ - Return True precisely if x and y are equal. + Return ``True`` precisely if x and y are equal. """ return bool(x == y) cdef bint py_is_integer(x) noexcept: r""" - Returns True if pynac should treat this object as an integer. + Return ``True`` if pynac should treat this object as an integer. EXAMPLES:: @@ -1195,7 +1188,7 @@ cdef bint py_is_crational(x) noexcept: def py_is_crational_for_doctest(x): r""" - Return True if pynac should treat this object as an element of `\QQ(i)`. + Return ``True`` if pynac should treat this object as an element of `\QQ(i)`. TESTS:: @@ -1341,7 +1334,7 @@ cdef bint py_is_cinteger(x) noexcept: def py_is_cinteger_for_doctest(x): r""" - Returns True if pynac should treat this object as an element of `\ZZ(i)`. + Return ``True`` if pynac should treat this object as an element of `\ZZ(i)`. TESTS:: @@ -1481,8 +1474,8 @@ cdef py_factorial(x): sage: py_factorial(-2/3) 2.67893853470775 """ - # factorial(x) is only defined for non-negative integers x - # so we first test if x can be coerced into ZZ and is non-negative. + # factorial(x) is only defined for nonnegative integers x + # so we first test if x can be coerced into ZZ and is nonnegative. # If this is not the case then we return the symbolic expression gamma(x+1) # This fixes Issue 9240 try: @@ -1525,7 +1518,7 @@ def doublefactorial(n): INPUT: - - n -- an integer > = 1 + - ``n`` -- integer ``>= 1`` EXAMPLES:: @@ -1611,7 +1604,7 @@ cdef py_stieltjes(x): """ Return the Stieltjes constant of the given index. - The value is expected to be a non-negative integer. + The value is expected to be a nonnegative integer. TESTS:: @@ -2117,7 +2110,7 @@ cdef int py_int_length(x) except -1: cdef py_li(x, n, parent): """ - Returns a numerical approximation of polylog(n, x) with precision given + Return a numerical approximation of polylog(n, x) with precision given by the ``parent`` argument. EXAMPLES:: @@ -2251,9 +2244,8 @@ def py_li2_for_doctests(x): cdef GConstant py_get_constant(const char* name) noexcept: """ - Returns a constant given its name. This is called by - constant::unarchive in constant.cpp in Pynac and is used for - pickling. + Return a constant given its name. This is called by constant::unarchive in + constant.cpp in Pynac and is used for pickling. """ from sage.symbolic.constants import constants_name_table cdef PynacConstant pc @@ -2271,7 +2263,7 @@ cdef py_eval_constant(unsigned serial, kwds): cdef py_eval_unsigned_infinity(): """ - Returns unsigned_infinity. + Return ``unsigned_infinity``. """ from sage.rings.infinity import unsigned_infinity return unsigned_infinity @@ -2290,7 +2282,7 @@ def py_eval_unsigned_infinity_for_doctests(): cdef py_eval_infinity(): """ - Returns positive infinity, i.e., oo. + Return positive infinity, i.e., oo. """ from sage.rings.infinity import infinity return infinity @@ -2309,7 +2301,7 @@ def py_eval_infinity_for_doctests(): cdef py_eval_neg_infinity(): """ - Returns minus_infinity. + Return ``minus_infinity``. """ from sage.rings.infinity import minus_infinity return minus_infinity @@ -2385,7 +2377,7 @@ def init_pynac_I(): sage: symbolic_I^2 -1 - Note that conversions to real fields will give :class:`TypeError`:: + Note that conversions to real fields will give :exc:`TypeError`:: sage: float(symbolic_I) Traceback (most recent call last): @@ -2472,7 +2464,7 @@ def init_pynac_I(): def init_function_table(): """ - Initializes the function pointer table in Pynac. This must be + Initialize the function pointer table in Pynac. This must be called before Pynac is used; otherwise, there will be segfaults. """ diff --git a/src/sage/symbolic/random_tests.py b/src/sage/symbolic/random_tests.py index fd49cc4cdd9..cba2493de95 100644 --- a/src/sage/symbolic/random_tests.py +++ b/src/sage/symbolic/random_tests.py @@ -80,11 +80,11 @@ def normalize_prob_list(pl, extra=()): r""" INPUT: - - ``pl`` -- A list of tuples, where the first element of each tuple is + - ``pl`` -- list of tuples, where the first element of each tuple is a floating-point number (representing a relative probability). The second element of each tuple may be a list or any other kind of object. - - ``extra`` -- A tuple which is to be appended to every tuple in ``pl``. + - ``extra`` -- tuple which is to be appended to every tuple in ``pl`` This function takes such a list of tuples (a "probability list") and normalizes the probabilities so that they sum to one. If any of the @@ -131,9 +131,9 @@ def choose_from_prob_list(lst): r""" INPUT: - - ``lst`` -- A list of tuples, where the first element of each tuple + - ``lst`` -- list of tuples, where the first element of each tuple is a nonnegative float (a probability), and the probabilities sum - to one. + to one OUTPUT: @@ -250,7 +250,6 @@ def random_expr_helper(n_nodes, internal, leaves, verbose): sage: our_exprs = set() sage: while our_exprs != all_exprs: ....: our_exprs.add(next_expr()) - """ if n_nodes == 1: return choose_from_prob_list(leaves)[1] @@ -311,7 +310,6 @@ def random_expr(size, nvars=1, ncoeffs=None, var_frac=0.5, About to apply sgn to [v1] About to apply to [1/31, sgn(v1)] sgn(v1) + 1/31 - """ vars = [(1.0, SR.var('v%d' % (n + 1))) for n in range(nvars)] if ncoeffs is None: @@ -349,14 +347,14 @@ def assert_strict_weak_order(a, b, c, cmp_func): INPUT: - - ``a``, ``b``, ``c`` -- anything that can be compared by ``cmp_func``. + - ``a``, ``b``, ``c`` -- anything that can be compared by ``cmp_func`` - ``cmp_func`` -- function of two arguments that returns their - comparison (i.e. either ``True`` or ``False``). + comparison (i.e. either ``True`` or ``False``) OUTPUT: - Nothing. This raises a :class:`ValueError` if ``cmp_func`` + Nothing. Raises a :exc:`ValueError` if ``cmp_func`` is not a strict weak order on the three given elements. REFERENCES: @@ -423,7 +421,7 @@ def incomparable(i, j): def test_symbolic_expression_order(repetitions=100): r""" - Tests whether the comparison of random symbolic expressions + Test whether the comparison of random symbolic expressions satisfies the strict weak order axioms. This is important because the C++ extension class uses diff --git a/src/sage/symbolic/relation.py b/src/sage/symbolic/relation.py index 5e2b3bd7c9f..59605d2e72b 100644 --- a/src/sage/symbolic/relation.py +++ b/src/sage/symbolic/relation.py @@ -362,9 +362,8 @@ def test_relation_maxima(relation): """ - Return True if this (in)equality is definitely true. Return False - if it is false or the algorithm for testing (in)equality is - inconclusive. + Return ``True`` if this (in)equality is definitely true. Return ``False`` + if it is false or the algorithm for testing (in)equality is inconclusive. EXAMPLES:: @@ -590,42 +589,41 @@ def solve(f, *args, **kwds): INPUT: - - ``f`` -- equation or system of equations (given by a - list or tuple) + - ``f`` -- equation or system of equations (given by a list or tuple) - - ``*args`` -- variables to solve for. + - ``*args`` -- variables to solve for - - ``solution_dict`` -- bool (default: ``False``); if True or non-zero, - return a list of dictionaries containing the solutions. If there - are no solutions, return an empty list (rather than a list containing - an empty dictionary). Likewise, if there's only a single solution, - return a list containing one dictionary with that solution. + - ``solution_dict`` -- boolean (default: ``False``); if ``True`` or nonzero, + return a list of dictionaries containing the solutions. If there + are no solutions, return an empty list (rather than a list containing + an empty dictionary). Likewise, if there's only a single solution, + return a list containing one dictionary with that solution. There are a few optional keywords if you are trying to solve a single equation. They may only be used in that context. - - ``multiplicities`` -- bool (default: ``False``); if True, - return corresponding multiplicities. This keyword is - incompatible with ``to_poly_solve=True`` and does not make - any sense when solving inequalities. + - ``multiplicities`` -- boolean (default: ``False``); if True, + return corresponding multiplicities. This keyword is + incompatible with ``to_poly_solve=True`` and does not make + any sense when solving inequalities. - - ``explicit_solutions`` -- bool (default: ``False``); require that - all roots be explicit rather than implicit. Not used - when solving inequalities. + - ``explicit_solutions`` -- boolean (default: ``False``); require that + all roots be explicit rather than implicit. Not used + when solving inequalities. - - ``to_poly_solve`` -- bool (default: ``False``) or string; use - Maxima's ``to_poly_solver`` package to search for more possible - solutions, but possibly encounter approximate solutions. - This keyword is incompatible with ``multiplicities=True`` - and is not used when solving inequalities. Setting ``to_poly_solve`` - to 'force' (string) omits Maxima's solve command (useful when - some solutions of trigonometric equations are lost). + - ``to_poly_solve`` -- boolean (default: ``False``) or string; use + Maxima's ``to_poly_solver`` package to search for more possible + solutions, but possibly encounter approximate solutions. + This keyword is incompatible with ``multiplicities=True`` + and is not used when solving inequalities. Setting ``to_poly_solve`` + to 'force' (string) omits Maxima's solve command (useful when + some solutions of trigonometric equations are lost). - - ``algorithm`` -- string (default: 'maxima'); to use SymPy's + - ``algorithm`` -- string (default: ``'maxima'``); to use SymPy's solvers set this to 'sympy'. Note that SymPy is always used for diophantine equations. Another choice is 'giac'. - - ``domain`` -- string (default: 'complex'); setting this to 'real' + - ``domain`` -- string (default: ``'complex'``); setting this to 'real' changes the way SymPy solves single equations; inequalities are always solved in the real domain. @@ -1432,7 +1430,7 @@ def _giac_solver(f, x, solution_dict=False): - ``f`` -- equation or list of equations - ``x`` -- variable or list of variables - - ``solution_dict`` -- optional boolean (default ``False``) + - ``solution_dict`` -- boolean (default: ``False``) EXAMPLES:: @@ -1477,17 +1475,15 @@ def solve_mod(eqns, modulus, solution_dict=False): INPUT: + - ``eqns`` -- equation or list of equations - - ``eqns`` -- equation or list of equations - - - ``modulus`` -- an integer - - - ``solution_dict`` -- bool (default: ``False``); if True or non-zero, - return a list of dictionaries containing the solutions. If there - are no solutions, return an empty list (rather than a list containing - an empty dictionary). Likewise, if there's only a single solution, - return a list containing one dictionary with that solution. + - ``modulus`` -- integer + - ``solution_dict`` -- boolean (default: ``False``); if ``True`` or nonzero, + return a list of dictionaries containing the solutions. If there + are no solutions, return an empty list (rather than a list containing + an empty dictionary). Likewise, if there's only a single solution, + return a list containing one dictionary with that solution. EXAMPLES:: @@ -1625,15 +1621,13 @@ def _solve_mod_prime_power(eqns, p, m, vars): INPUT: + - ``eqns`` -- equation or list of equations - - ``eqns`` -- equation or list of equations - - - ``p`` -- a prime - - - ``i`` -- an integer > 0 + - ``p`` -- a prime - - ``vars`` -- a list of variables to solve for + - ``i`` -- integer > 0 + - ``vars`` -- list of variables to solve for EXAMPLES:: @@ -1753,7 +1747,7 @@ def solve_ineq_univar(ineq): def solve_ineq_fourier(ineq, vars=None): """ - Solves system of inequalities using Maxima and Fourier elimination + Solve system of inequalities using Maxima and Fourier elimination. Can be used for system of linear inequalities and for some types of nonlinear inequalities. For examples, see the example section @@ -1764,7 +1758,7 @@ def solve_ineq_fourier(ineq, vars=None): - ``ineq`` -- list with system of inequalities - - ``vars`` -- optionally list with variables for Fourier elimination. + - ``vars`` -- optionally list with variables for Fourier elimination OUTPUT: @@ -1827,7 +1821,7 @@ def solve_ineq_fourier(ineq, vars=None): def solve_ineq(ineq, vars=None): """ - Solves inequalities and systems of inequalities using Maxima. + Solve inequalities and systems of inequalities using Maxima. Switches between rational inequalities (sage.symbolic.relation.solve_ineq_rational) and Fourier elimination (sage.symbolic.relation.solve_ineq_fouried). @@ -1849,7 +1843,7 @@ def solve_ineq(ineq, vars=None): http://maxima.cvs.sourceforge.net/viewvc/maxima/maxima/share/contrib/fourier_elim/rtest_fourier_elim.mac for a big gallery of problems covered by this algorithm. - - ``vars`` -- optional parameter with list of variables. This list + - ``vars`` -- (optional) parameter with list of variables. This list is used only if Fourier elimination is used. If omitted or if rational inequality is solved, then variables are determined automatically. diff --git a/src/sage/symbolic/ring.pyx b/src/sage/symbolic/ring.pyx index 5b007d9e5fd..32afe8d3a62 100644 --- a/src/sage/symbolic/ring.pyx +++ b/src/sage/symbolic/ring.pyx @@ -83,7 +83,6 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): sage: isinstance(SR, sage.symbolic.ring.SymbolicRing) True sage: TestSuite(SR).run(skip=['_test_divides']) - """ if base_ring is None: base_ring = self @@ -208,8 +207,8 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): return False else: from sage.rings.fraction_field import FractionField_generic - from sage.rings.polynomial.polynomial_ring import is_PolynomialRing - from sage.rings.polynomial.multi_polynomial_ring import is_MPolynomialRing + from sage.rings.polynomial.polynomial_ring import PolynomialRing_general + from sage.rings.polynomial.multi_polynomial_ring import MPolynomialRing_base from sage.rings.polynomial.laurent_polynomial_ring_base import LaurentPolynomialRing_generic from sage.rings.infinity import InfinityRing, UnsignedInfinityRing from sage.rings.real_lazy import RLF, CLF @@ -220,7 +219,7 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): if R._is_numerical(): # Almost anything with a coercion into any precision of CC return R not in (RLF, CLF) - elif is_PolynomialRing(R) or is_MPolynomialRing(R) or isinstance(R, FractionField_generic) or isinstance(R, LaurentPolynomialRing_generic): + elif isinstance(R, PolynomialRing_general) or isinstance(R, MPolynomialRing_base) or isinstance(R, FractionField_generic) or isinstance(R, LaurentPolynomialRing_generic): base = R.base_ring() return base is not self and self.has_coerce_map_from(base) elif (R is InfinityRing or R is UnsignedInfinityRing @@ -384,13 +383,13 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): INPUT: - - ``x`` -- a Python object. + - ``x`` -- a Python object - - ``force`` -- bool, default ``False``, if True, the Python object - is taken as is without attempting coercion or list traversal. + - ``force`` -- boolean (default: ``False``); if ``True``, the Python object + is taken as is without attempting coercion or list traversal - - ``recursive`` -- bool, default ``True``, disables recursive - traversal of lists. + - ``recursive`` -- boolean (default: ``True``); disables recursive + traversal of lists EXAMPLES:: @@ -442,11 +441,9 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): INPUT: - - ``n`` -- a nonnegative integer - - OUTPUT: + - ``n`` -- nonnegative integer - - ``n``-th wildcard expression + OUTPUT: n-th wildcard expression EXAMPLES:: @@ -477,7 +474,7 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): def __contains__(self, x): r""" - True if there is an element of the symbolic ring that is equal to x + ``True`` if there is an element of the symbolic ring that is equal to x under ``==``. EXAMPLES: @@ -511,9 +508,7 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): """ Return the characteristic of the symbolic ring, which is 0. - OUTPUT: - - - a Sage integer + OUTPUT: a Sage integer EXAMPLES:: @@ -538,7 +533,7 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): def is_field(self, proof=True): """ - Returns True, since the symbolic expression ring is (for the most + Return ``True``, since the symbolic expression ring is (for the most part) a field. EXAMPLES:: @@ -766,9 +761,7 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): by default, and possible options are (non-exhaustive list, see note below): ``'real'``, ``'complex'``, ``'positive'``, ``'integer'`` and ``'noninteger'`` - OUTPUT: - - Symbolic expression or tuple of symbolic expressions. + OUTPUT: symbolic expression or tuple of symbolic expressions .. SEEALSO:: @@ -1052,22 +1045,20 @@ cdef class SymbolicRing(sage.rings.abc.SymbolicRing): Choose one of the following keywords to create a subring. - - ``accepting_variables`` (default: ``None``) -- a tuple or other + - ``accepting_variables`` -- (default: ``None``) a tuple or other iterable of variables. If specified, then a symbolic subring of expressions in only these variables is created. - - ``rejecting_variables`` (default: ``None``) -- a tuple or other + - ``rejecting_variables`` -- (default: ``None``) a tuple or other iterable of variables. If specified, then a symbolic subring of expressions in variables distinct to these variables is created. - - ``no_variables`` (default: ``False``) -- a boolean. If set, + - ``no_variables`` -- boolean (default: ``False``); if set, then a symbolic subring of constant expressions (i.e., expressions without a variable) is created. - OUTPUT: - - A ring. + OUTPUT: a ring EXAMPLES: @@ -1342,11 +1333,9 @@ def isidentifier(x): INPUT: - - ``x`` -- a string - - OUTPUT: + - ``x`` -- string - Boolean. Whether the string ``x`` can be used as a variable name. + OUTPUT: boolean; whether the string ``x`` can be used as a variable name This function should return ``False`` for keywords, so we can not just use the ``isidentifier`` method of strings, diff --git a/src/sage/symbolic/series_impl.pxi b/src/sage/symbolic/series_impl.pxi index 3f869920d6b..b66e43aae86 100644 --- a/src/sage/symbolic/series_impl.pxi +++ b/src/sage/symbolic/series_impl.pxi @@ -141,16 +141,14 @@ cdef class SymbolicSeries(Expression): def is_terminating_series(self): """ - Return True if the series is without order term. + Return ``True`` if the series is without order term. A series is terminating if it can be represented exactly, without requiring an order term. You can explicitly request terminating series by setting the order to positive infinity. - OUTPUT: - - Boolean. ``True`` if the series has no order term. + OUTPUT: boolean; ``True`` if the series has no order term EXAMPLES:: @@ -170,9 +168,7 @@ cdef class SymbolicSeries(Expression): Given a power series or expression, return the corresponding expression without the big oh. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression EXAMPLES:: @@ -209,20 +205,18 @@ cdef class SymbolicSeries(Expression): INPUT: - - ``x`` -- optional variable. - - - ``sparse`` -- Boolean. If ``False`` return a list with as much - entries as the order of the series. + - ``x`` -- (optional) variable - OUTPUT: + - ``sparse`` -- boolean (default: ``True``); if ``False`` return a list + with as much entries as the order of the series - Depending on the value of ``sparse``, + OUTPUT: depending on the value of ``sparse``, - A list of pairs ``(expr, n)``, where ``expr`` is a symbolic expression and ``n`` is a power (``sparse=True``, default) - A list of expressions where the ``n``-th element is the coefficient of - ``x^n`` when self is seen as polynomial in ``x`` (``sparse=False``). + ``x^n`` when ``self`` is seen as polynomial in ``x`` (``sparse=False``). EXAMPLES:: diff --git a/src/sage/symbolic/subring.py b/src/sage/symbolic/subring.py index 2db60e8f915..20f5bf62287 100644 --- a/src/sage/symbolic/subring.py +++ b/src/sage/symbolic/subring.py @@ -111,16 +111,16 @@ class SymbolicSubringFactory(UniqueFactory): Specify one of the following keywords to create a subring. - - ``accepting_variables`` (default: ``None``) -- a tuple or other + - ``accepting_variables`` -- (default: ``None``) a tuple or other iterable of variables. If specified, then a symbolic subring of expressions in only these variables is created. - - ``rejecting_variables`` (default: ``None``) -- a tuple or other + - ``rejecting_variables`` -- (default: ``None``) a tuple or other iterable of variables. If specified, then a symbolic subring of expressions in variables distinct to these variables is created. - - ``no_variables`` (default: ``False``) -- a boolean. If set, + - ``no_variables`` -- boolean (default: ``False``); if set, then a symbolic subring of constant expressions (i.e., expressions without a variable) is created. @@ -254,7 +254,7 @@ def __init__(self, vars): INPUT: - - ``vars`` -- a tuple of symbolic variables. + - ``vars`` -- tuple of symbolic variables TESTS:: @@ -286,9 +286,7 @@ def _repr_variables_(self): r""" Return a representation string of the variables. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -314,11 +312,9 @@ def has_valid_variable(self, variable): INPUT: - - ``variable`` -- a symbolic variable. - - OUTPUT: + - ``variable`` -- a symbolic variable - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -332,15 +328,13 @@ def has_valid_variable(self, variable): def _element_constructor_(self, x): r""" - Creates the element of this subring specified by the input ``x``. + Create the element of this subring specified by the input ``x``. INPUT: - - ``x`` -- an object. - - OUTPUT: + - ``x`` -- an object - An element of this symbolic subring. + OUTPUT: an element of this symbolic subring TESTS:: @@ -368,11 +362,9 @@ def _coerce_map_from_(self, P): INPUT: - - ``P`` -- a parent. + - ``P`` -- a parent - OUTPUT: - - A boolean or ``None``. + OUTPUT: boolean or ``None`` TESTS:: @@ -487,7 +479,7 @@ class GenericSymbolicSubringFunctor(ConstructionFunctor): INPUT: - - ``vars`` -- a tuple, set, or other iterable of symbolic variables. + - ``vars`` -- tuple, set, or other iterable of symbolic variables EXAMPLES:: @@ -528,9 +520,7 @@ def _repr_variables_(self): r""" Return a representation string of the variables. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -545,9 +535,7 @@ def _repr_(self): r""" Return a representation string of this functor. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -569,11 +557,9 @@ def merge(self, other): INPUT: - - ``other`` -- a functor. + - ``other`` -- a functor - OUTPUT: - - A functor or ``None``. + OUTPUT: a functor or ``None`` EXAMPLES:: @@ -591,11 +577,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -612,11 +596,9 @@ def __ne__(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -637,9 +619,7 @@ def _repr_(self): r""" Return a representation string of this symbolic subring. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -656,11 +636,9 @@ def has_valid_variable(self, variable): INPUT: - - ``variable`` -- a symbolic variable. - - OUTPUT: + - ``variable`` -- a symbolic variable - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -698,11 +676,9 @@ def _coerce_map_from_(self, P): INPUT: - - ``P`` -- a parent. - - OUTPUT: + - ``P`` -- a parent - A boolean or ``None``. + OUTPUT: boolean or ``None`` TESTS:: @@ -722,9 +698,7 @@ def _an_element_(self): r""" Return an element of this symbolic subring. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression TESTS:: @@ -749,11 +723,9 @@ def merge(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A functor or ``None``. + OUTPUT: a functor or ``None`` EXAMPLES:: @@ -779,11 +751,9 @@ def _apply_functor(self, R): INPUT: - - ``R`` -- a symbolic ring. - - OUTPUT: + - ``R`` -- a symbolic ring - A subring of ``R``. + OUTPUT: a subring of ``R`` EXAMPLES:: @@ -816,9 +786,7 @@ def _repr_(self): r""" Return a representation string of this symbolic subring. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -835,11 +803,9 @@ def has_valid_variable(self, variable): INPUT: - - ``variable`` -- a symbolic variable. - - OUTPUT: + - ``variable`` -- a symbolic variable - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -877,11 +843,9 @@ def _coerce_map_from_(self, P): INPUT: - - ``P`` -- a parent. - - OUTPUT: + - ``P`` -- a parent - A boolean or ``None``. + OUTPUT: boolean or ``None`` TESTS:: @@ -908,9 +872,7 @@ def _an_element_(self): r""" Return an element of this symbolic subring. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression TESTS:: @@ -950,11 +912,9 @@ def merge(self, other): INPUT: - - ``other`` -- a functor. - - OUTPUT: + - ``other`` -- a functor - A functor or ``None``. + OUTPUT: a functor or ``None`` EXAMPLES:: @@ -980,11 +940,9 @@ def _apply_functor(self, R): INPUT: - - ``R`` -- a symbolic ring. - - OUTPUT: + - ``R`` -- a symbolic ring - A subring of ``R``. + OUTPUT: a subring of ``R`` EXAMPLES:: @@ -1016,9 +974,7 @@ def _repr_(self): r""" Return a representation string of this symbolic subring. - OUTPUT: - - A string. + OUTPUT: string TESTS:: @@ -1034,11 +990,9 @@ def has_valid_variable(self, variable): INPUT: - - ``variable`` -- a symbolic variable. - - OUTPUT: + - ``variable`` -- a symbolic variable - A boolean. + OUTPUT: boolean EXAMPLES:: @@ -1057,9 +1011,7 @@ def _an_element_(self): r""" Return an element of this symbolic subring. - OUTPUT: - - A symbolic expression. + OUTPUT: a symbolic expression TESTS:: diff --git a/src/sage/symbolic/substitution_map_impl.pxi b/src/sage/symbolic/substitution_map_impl.pxi index 7d9e35cf630..4db772ec930 100644 --- a/src/sage/symbolic/substitution_map_impl.pxi +++ b/src/sage/symbolic/substitution_map_impl.pxi @@ -57,11 +57,9 @@ cdef SubstitutionMap new_SubstitutionMap_from_GExMap(const GExMap& smap): INPUT: - - ``smap`` -- a Pynac ``exmap``. + - ``smap`` -- a Pynac ``exmap`` - OUTPUT: - - A new Python :class:`SubstitutionMap` + OUTPUT: a new Python :class:`SubstitutionMap` EXAMPLES:: @@ -79,9 +77,7 @@ cpdef SubstitutionMap make_map(subs_dict): """ Construct a new substitution map. - OUTPUT: - - A new :class:`SubstitutionMap` for doctesting + OUTPUT: a new :class:`SubstitutionMap` for doctesting EXAMPLES:: diff --git a/src/sage/symbolic/symbols.py b/src/sage/symbolic/symbols.py index 7fe7cdb4472..1669aee6e67 100644 --- a/src/sage/symbolic/symbols.py +++ b/src/sage/symbolic/symbols.py @@ -22,14 +22,14 @@ def register_symbol(obj, conversions, nargs=None): INPUT: - - ``obj`` -- a symbolic object or function. + - ``obj`` -- a symbolic object or function - - ``conversions`` -- a dictionary of conversions, where the keys + - ``conversions`` -- dictionary of conversions, where the keys are the names of interfaces (e.g., ``'maxima'``), and the values - are the string representation of ``obj`` in that system. + are the string representation of ``obj`` in that system - - ``nargs`` -- optional number of arguments. For most functions, - this can be deduced automatically. + - ``nargs`` -- (optional) number of arguments; for most functions, + this can be deduced automatically EXAMPLES:: diff --git a/src/sage/symbolic/tests.py b/src/sage/symbolic/tests.py index a7c6a9a6cb2..6743f0b4205 100644 --- a/src/sage/symbolic/tests.py +++ b/src/sage/symbolic/tests.py @@ -15,11 +15,9 @@ def rational_powers_memleak(): """ - Check that there is no memory leak in rational powers + Check that there is no memory leak in rational powers. - OUTPUT: - - Boolean. Whether the memory leak was detected. + OUTPUT: boolean; whether the memory leak was detected See :issue:`9129`. diff --git a/src/sage/symbolic/units.py b/src/sage/symbolic/units.py index 5e1abf675c9..899b8087b96 100644 --- a/src/sage/symbolic/units.py +++ b/src/sage/symbolic/units.py @@ -928,16 +928,14 @@ def evalunitdict(): def vars_in_str(s): """ - Given a string like 'mass/(length*time)', return the list - ['mass', 'length', 'time']. + Given a string like ``'mass/(length*time)'``, return the list + ``['mass', 'length', 'time']``. INPUT: - - ``s`` -- a string + - ``s`` -- string - OUTPUT: - - - a list of strings (unit names) + OUTPUT: list of strings (unit names) EXAMPLES:: @@ -949,17 +947,16 @@ def vars_in_str(s): def unit_derivations_expr(v): """ - Given derived units name, returns the corresponding units - expression. For example, given 'acceleration' output the symbolic - expression length/time^2. + Given derived units name, returns the corresponding units expression. - INPUT: + For example, given ``'acceleration'`` output the symbolic expression + ``length/time^2``. - - ``v`` -- a string, name of a unit type such as 'area', 'volume', etc. + INPUT: - OUTPUT: + - ``v`` -- string; name of a unit type such as ``'area'``, ``'volume'``, etc. - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -968,7 +965,7 @@ def unit_derivations_expr(v): sage: sage.symbolic.units.unit_derivations_expr('electric_potential') length^2*mass/(current*time^3) - If the unit name is unknown, a :class:`KeyError` is raised:: + If the unit name is unknown, a :exc:`KeyError` is raised:: sage: sage.symbolic.units.unit_derivations_expr('invalid') Traceback (most recent call last): @@ -1024,12 +1021,9 @@ class that derives from symbolic expression, and has a specialized INPUT: - - ``name`` -- a string - - OUTPUT: - - - a :class:`UnitExpression` + - ``name`` -- string + OUTPUT: a :class:`UnitExpression` EXAMPLES:: @@ -1168,7 +1162,6 @@ def __getattr__(self, name): sage: units.area.acre is units.area.acre True - """ if name in self.__units: return self.__units[name] @@ -1205,15 +1198,13 @@ def __repr__(self): def unitdocs(unit): r""" - Returns docstring for the given unit. + Return docstring for the given unit. INPUT: - ``unit`` -- a unit - OUTPUT: - - - a string + OUTPUT: string EXAMPLES:: @@ -1242,9 +1233,7 @@ def is_unit(s) -> bool: - ``s`` -- an object - OUTPUT: - - - a boolean + OUTPUT: boolean EXAMPLES:: @@ -1269,17 +1258,16 @@ def is_unit(s) -> bool: def convert(expr, target): """ - Converts units between expr and target. If target is None then converts to SI base units. + Convert units between ``expr`` and ``target``. If ``target`` is ``None`` + then converts to SI base units. INPUT: - ``expr`` -- the symbolic expression converting from - - ``target`` -- (default None) the symbolic expression converting to - - OUTPUT: + - ``target`` -- (default: ``None``) the symbolic expression converting to - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -1288,7 +1276,7 @@ def convert(expr, target): sage: sage.symbolic.units.convert(units.mass.kilogram, units.mass.pound) 100000000/45359237*pound - Raises ValueError if expr and target are not convertible:: + Raises :exc:`ValueError` if expr and target are not convertible:: sage: sage.symbolic.units.convert(units.mass.kilogram, units.length.foot) Traceback (most recent call last): @@ -1362,15 +1350,13 @@ def convert(expr, target): def base_units(unit): """ - Converts unit to base SI units. + Convert unit to base SI units. INPUT: - ``unit`` -- a unit - OUTPUT: - - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -1420,9 +1406,7 @@ def convert_temperature(expr, target): - ``expr`` -- a unit of temperature - ``target`` -- a units of temperature - OUTPUT: - - - a symbolic expression + OUTPUT: a symbolic expression EXAMPLES:: @@ -1437,7 +1421,7 @@ def convert_temperature(expr, target): sage: t.convert() 273.150000000000*kelvin - Raises ValueError when either input is not a unit of temperature:: + Raises :exc:`ValueError` when either input is not a unit of temperature:: sage: t.convert(units.length.foot) Traceback (most recent call last): diff --git a/src/sage/tensor/modules/alternating_contr_tensor.py b/src/sage/tensor/modules/alternating_contr_tensor.py index a2cacf8492f..515b315175c 100644 --- a/src/sage/tensor/modules/alternating_contr_tensor.py +++ b/src/sage/tensor/modules/alternating_contr_tensor.py @@ -176,7 +176,6 @@ class AlternatingContrTensor(FreeModuleTensor): module M over the Integer Ring sage: s.display(e) b∧b = 0 - """ def __init__(self, fmodule, degree, name=None, latex_name=None): r""" @@ -189,7 +188,7 @@ def __init__(self, fmodule, degree, name=None, latex_name=None): sage: e = M.basis('e') sage: a = AlternatingContrTensor(M, 2, name='a') sage: a[e,0,1] = 2 - sage: TestSuite(a).run(skip="_test_category") # see below + sage: TestSuite(a).run(skip='_test_category') # see below In the above test suite, _test_category fails because a is not an instance of a.parent().category().element_class. Actually alternating @@ -199,7 +198,6 @@ def __init__(self, fmodule, degree, name=None, latex_name=None): sage: a1 = M.exterior_power(2).element_class(M, 2, name='a') sage: a1[e,0,1] = 2 sage: TestSuite(a1).run() - """ FreeModuleTensor.__init__(self, fmodule, (degree,0), name=name, latex_name=latex_name, @@ -251,7 +249,6 @@ def _new_instance(self): module M over the Integer Ring sage: a._new_instance().parent() is a.parent() True - """ return self.__class__(self._fmodule, self._tensor_rank) @@ -284,7 +281,6 @@ def _new_comp(self, basis): sage: a._new_comp(e) 1-index components w.r.t. Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring - """ fmodule = self._fmodule # the base free module if self._tensor_rank == 1: @@ -306,7 +302,6 @@ def degree(self): sage: a = M.alternating_contravariant_tensor(2, name='a') sage: a.degree() 2 - """ return self._tensor_rank @@ -392,7 +387,6 @@ def display(self, basis=None, format_spec=None): sage: a.display(format_spec=10) # 10 bits of precision a = 0.33 e_1∧e_2 + 2.5 e_1∧e_3 + 4.0 e_2∧e_3 - """ from sage.misc.latex import latex from sage.typeset.unicode_characters import unicode_wedge @@ -532,7 +526,6 @@ def wedge(self, other): True sage: d.wedge(c) == c.wedge(d) True - """ from sage.typeset.unicode_characters import unicode_wedge from .format_utilities import is_atomic @@ -712,7 +705,6 @@ def interior_product(self, form): -240 sage: c == a.contract(0, 1, 2, 3, b, 0, 1, 2, 3) True - """ from .format_utilities import is_atomic from .free_module_alt_form import FreeModuleAltForm diff --git a/src/sage/tensor/modules/comp.py b/src/sage/tensor/modules/comp.py index d6a3572c143..12682ea4552 100644 --- a/src/sage/tensor/modules/comp.py +++ b/src/sage/tensor/modules/comp.py @@ -211,7 +211,7 @@ [ 0 0 0] Internally, the components are stored as a dictionary (:attr:`_comp`) whose -keys are the indices; only the non-zero components are stored:: +keys are the indices; only the nonzero components are stored:: sage: a[:] [0.000000000000000 0.000000000000000 0.000000000000000] @@ -402,7 +402,7 @@ class Components(SageObject): [ 0 0 0] Internally, the components are stored as a dictionary (:attr:`_comp`) whose - keys are the indices; only the non-zero components are stored:: + keys are the indices; only the nonzero components are stored:: sage: a[:] [0.000000000000000 0.000000000000000 0.000000000000000] @@ -490,7 +490,6 @@ class Components(SageObject): [[-6, 0, 18], [-3, 0, 9], [-12, 0, 36]]] sage: d[0,1,2] == a[0]*b[1]*a[2] True - """ def __init__(self, ring, frame, nb_indices, start_index=0, output_formatter=None): @@ -500,7 +499,6 @@ def __init__(self, ring, frame, nb_indices, start_index=0, sage: from sage.tensor.modules.comp import Components sage: Components(ZZ, [1,2,3], 2) 2-indices components w.r.t. [1, 2, 3] - """ # For efficiency, no test is performed regarding the type and range of # the arguments: @@ -562,13 +560,12 @@ def _repr_symmetry(self): sage: c = Components(ZZ, [1,2,3], 2) sage: c._repr_symmetry() ('', '') - """ return "", "" def _new_instance(self): r""" - Creates a :class:`Components` instance of the same number of indices + Create a :class:`Components` instance of the same number of indices and w.r.t. the same frame. This method must be redefined by derived classes of @@ -580,7 +577,6 @@ def _new_instance(self): sage: c = Components(ZZ, [1,2,3], 2) sage: c._new_instance() 2-indices components w.r.t. [1, 2, 3] - """ return Components(self._ring, self._frame, self._nid, self._sindex, self._output_formatter) @@ -609,7 +605,6 @@ def copy(self): True sage: b is a # b is a distinct object False - """ result = self._new_instance() for ind, val in self._comp.items(): @@ -621,7 +616,7 @@ def copy(self): def _del_zeros(self): r""" - Deletes all the zeros in the dictionary :attr:`_comp` + Delete all the zeros in the dictionary :attr:`_comp`. NB: The use case of this method must be rare because zeros are not stored in :attr:`_comp`. @@ -634,7 +629,6 @@ def _del_zeros(self): sage: c._del_zeros() sage: c._comp {(0, 1): 3, (1, 2): -5} - """ # The zeros are first searched; they are deleted in a second stage, to # avoid changing the dictionary while it is read @@ -647,16 +641,14 @@ def _del_zeros(self): def _check_indices(self, indices): r""" - Check the validity of a list of indices and returns a tuple from it + Check the validity of a list of indices and returns a tuple from it. INPUT: - ``indices`` -- list of indices (possibly a single integer if - self is a 1-index object) + ``self`` is a 1-index object) - OUTPUT: - - - a tuple containing valid indices + OUTPUT: a tuple containing valid indices EXAMPLES:: @@ -680,7 +672,6 @@ def _check_indices(self, indices): Traceback (most recent call last): ... ValueError: wrong number of indices: 2 expected, while 3 are provided - """ if isinstance(indices, (int, Integer)): ind = (indices,) @@ -700,12 +691,12 @@ def _check_indices(self, indices): def __getitem__(self, args): r""" - Returns the component corresponding to the given indices. + Return the component corresponding to the given indices. INPUT: - ``args`` -- list of indices (possibly a single integer if - self is a 1-index object) or the character ``:`` for the full list + ``self`` is a 1-index object) or the character ``:`` for the full list of components OUTPUT: @@ -737,7 +728,6 @@ def __getitem__(self, args): [ 0 0 0] [ 0 0 -4] [ 0 0 0] - """ no_format = self._output_formatter is None format_type = None # default value, possibly redefined below @@ -788,9 +778,9 @@ def _get_list(self, ind_slice, no_format=True, format_type=None): INPUT: - - ``ind_slice`` -- a slice object. Unless the dimension is 1, - this must be ``[:]``. - - ``no_format`` -- (default: ``True``) determines whether some + - ``ind_slice`` -- a slice object; unless the dimension is 1, + this must be ``[:]`` + - ``no_format`` -- boolean (default: ``True``); determines whether some formatting of the components is to be performed - ``format_type`` -- (default: ``None``) argument to be passed to the formatting function ``self._output_formatter``, as the @@ -879,7 +869,6 @@ def _gen_list(self, ind, no_format=True, format_type=None): [0, 0, 0] sage: c._gen_list([0,1]) 5 - """ if len(ind) == self._nid: if no_format: @@ -895,12 +884,12 @@ def _gen_list(self, ind, no_format=True, format_type=None): def __setitem__(self, args, value): r""" - Sets the component corresponding to the given indices. + Set the component corresponding to the given indices. INPUT: - ``args`` -- list of indices (possibly a single integer if - self is a 1-index object); if ``[:]`` is provided, all the + ``self`` is a 1-index object); if ``[:]`` is provided, all the components are set - ``value`` -- the value to be set or a list of values if ``args = [:]`` (``slice(None)``) @@ -924,7 +913,6 @@ def __setitem__(self, args, value): [0 1 2] [3 4 5] [6 7 8] - """ format_type = None # default value, possibly redefined below if isinstance(args, list): # case of [[...]] syntax @@ -980,7 +968,7 @@ def _set_list(self, ind_slice, format_type, values): INPUT: - - ``ind_slice`` -- a slice object + - ``ind_slice`` -- a slice object - ``format_type`` -- format possibly used to construct a ring element - ``values`` -- list of values for the components : the full list if ``ind_slice = [:]``, in the form ``T[i][j]...`` for the @@ -996,7 +984,6 @@ def _set_list(self, ind_slice, format_type, values): [0 1 2] [3 4 5] [6 7 8] - """ si = self._sindex nsi = si + self._dim @@ -1043,7 +1030,6 @@ def _set_value_list(self, ind, format_type, val): [-1 -2 -3] [ 4 5 6] [ 7 -8 9] - """ if len(ind) == self._nid: if format_type is not None: @@ -1078,7 +1064,6 @@ def items(self): ((1, 0, 1), 5), ((1, 1, 0), 5), ((1, 1, 1), 3)] - """ for ind in self.index_generator(): val = self[ind] @@ -1120,9 +1105,9 @@ def display(self, symbol, latex_symbol=None, index_positions=None, ``None``, integers labels are used - ``format_spec`` -- (default: ``None``) format specification passed to the output formatter declared at the construction of the object - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero components are displayed - - ``only_nonredundant`` -- (default: ``False``) boolean; if ``True``, + - ``only_nonredundant`` -- boolean (default: ``False``); if ``True``, only nonredundant components are displayed in case of symmetries EXAMPLES: @@ -1238,7 +1223,6 @@ def display(self, symbol, latex_symbol=None, index_positions=None, sage: c[0] = SR.var('t', domain='real') # needs sage.symbolic sage: c.display('c') # needs sage.symbolic c_0 = t - """ from sage.misc.latex import latex from sage.tensor.modules.format_utilities import FormattedExpansion @@ -1337,9 +1321,7 @@ def swap_adjacent_indices(self, pos1, pos2, pos3): position of the last index of set 1 (since the two sets are adjacent) - ``pos3`` -- 1 plus position of the last index of set 2 - OUTPUT: - - - Components with index set 1 permuted with index set 2. + OUTPUT: components with index set 1 permuted with index set 2 EXAMPLES: @@ -1374,7 +1356,6 @@ def swap_adjacent_indices(self, pos1, pos2, pos3): 24 sage: d[1,2,0,1] 24 - """ result = self._new_instance() for ind, val in self._comp.items(): @@ -1423,7 +1404,6 @@ def is_zero(self): Traceback (most recent call last): ... TypeError: cannot compare a set of components to a number - """ if not self._comp: return True @@ -1443,11 +1423,9 @@ def __eq__(self, other): INPUT: - - ``other`` -- a set of components or 0 - - OUTPUT: + - ``other`` -- set of components or 0 - - ``True`` if ``self`` is equal to ``other``, or ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other``, or ``False`` otherwise EXAMPLES:: @@ -1468,7 +1446,6 @@ def __eq__(self, other): sage: v = Components(ZZ, [1,2,3], 1) sage: c.__eq__(v) False - """ if isinstance(other, (int, Integer)): # other is 0 if other == 0: @@ -1494,11 +1471,10 @@ def __ne__(self, other): INPUT: - - ``other`` -- a set of components or 0 - - OUTPUT: + - ``other`` -- set of components or 0 - - True if ``self`` is different from ``other``, or False otherwise + OUTPUT: ``True`` if ``self`` is different from ``other``, or ``False`` + otherwise EXAMPLES:: @@ -1514,7 +1490,6 @@ def __ne__(self, other): True sage: c.__ne__(c1) True - """ return not self == other @@ -1522,9 +1497,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of ``self`` + OUTPUT: an exact copy of ``self`` EXAMPLES:: @@ -1539,7 +1512,6 @@ def __pos__(self): True sage: a == c True - """ return self.copy() @@ -1547,9 +1519,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the opposite of the components represented by ``self`` + OUTPUT: the opposite of the components represented by ``self`` EXAMPLES:: @@ -1562,7 +1532,6 @@ def __neg__(self): [-5, 0, 4] sage: a == -c True - """ result = self._new_instance() for ind, val in self._comp.items(): @@ -1578,9 +1547,7 @@ def __add__(self, other): - ``other`` -- components of the same number of indices and defined on the same frame as ``self`` - OUTPUT: - - - components resulting from the addition of ``self`` and ``other`` + OUTPUT: components resulting from the addition of ``self`` and ``other`` EXAMPLES:: @@ -1608,7 +1575,6 @@ def __add__(self, other): sage: b.__add__(a) == s # test of commutativity of parallel comput. True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if isinstance(other, (int, Integer)) and other == 0: return +self @@ -1659,7 +1625,7 @@ def paral_sum(a, b, local_list_ind): def __radd__(self, other): r""" - Reflected addition (addition on the right to `other``) + Reflected addition (addition on the right to ``other``). EXAMPLES:: @@ -1678,7 +1644,6 @@ def __radd__(self, other): 1-index components w.r.t. [1, 2, 3] sage: s == a True - """ return self + other @@ -1690,9 +1655,7 @@ def __sub__(self, other): - ``other`` -- components, of the same type as ``self`` - OUTPUT: - - - components resulting from the subtraction of ``other`` from ``self`` + OUTPUT: components resulting from the subtraction of ``other`` from ``self`` EXAMPLES:: @@ -1722,7 +1685,6 @@ def __sub__(self, other): sage: b.__sub__(a) == -s # test of parallel comput. True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if isinstance(other, (int, Integer)) and other == 0: return +self @@ -1752,7 +1714,6 @@ def __rsub__(self, other): [-1, 0, 3] sage: s == -a True - """ return (-self) + other @@ -1764,9 +1725,7 @@ def __mul__(self, other): - ``other`` -- components, on the same frame as ``self`` - OUTPUT: - - - the tensor product of ``self`` by ``other`` + OUTPUT: the tensor product of ``self`` by ``other`` EXAMPLES:: @@ -1824,7 +1783,6 @@ def __mul__(self, other): sage: s_par[:] == s[:] True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if not isinstance(other, Components): raise TypeError("the second argument for the tensor product " + @@ -1936,7 +1894,6 @@ def __rmul__(self, other): True sage: a.__rmul__(0) == 0 True - """ if isinstance(other, Components): raise NotImplementedError("left tensor product not implemented") @@ -1965,7 +1922,6 @@ def __truediv__(self, other): True sage: 3*s == a True - """ if isinstance(other, Components): raise NotImplementedError("division by an object of type " + @@ -2030,7 +1986,6 @@ def trace(self, pos1, pos2): [12, 24, 36] sage: [sum(a[i,j,j] for j in range(3)) for i in range(3)] # check [12, 24, 36] - """ if self._nid < 2: raise ValueError("contraction can be performed only on " + @@ -2080,9 +2035,7 @@ def contract(self, *args): is not provided, a single contraction on the first index position of ``other`` is assumed - OUTPUT: - - - set of components resulting from the contraction + OUTPUT: set of components resulting from the contraction EXAMPLES: @@ -2218,7 +2171,6 @@ def contract(self, *args): sage: a.contract(1, 0, b, 1, 0) 4 sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ # # Treatment of the input @@ -2454,9 +2406,7 @@ def index_generator(self): r""" Generator of indices. - OUTPUT: - - - an iterable index + OUTPUT: an iterable index EXAMPLES: @@ -2474,7 +2424,6 @@ def index_generator(self): sage: list(c.index_generator()) [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2), (2, 0), (2, 1), (2, 2)] - """ si = self._sindex imax = self._dim - 1 + si @@ -2499,9 +2448,7 @@ def non_redundant_index_generator(self): Only versions for derived classes with symmetries or antisymmetries are not trivial. - OUTPUT: - - - an iterable index + OUTPUT: an iterable index EXAMPLES: @@ -2631,7 +2578,6 @@ def symmetrize(self, *pos): sage: all(s[i,j,k] == (c[i,j,k]+c[k,j,i])/2 # Check of the result: ....: for i in range(3) for j in range(3) for k in range(3)) True - """ from sage.groups.perm_gps.permgroup_named import SymmetricGroup if not pos: @@ -2664,7 +2610,7 @@ def symmetrize(self, *pos): def antisymmetrize(self, *pos): r""" - Antisymmetrization over the given index positions + Antisymmetrization over the given index positions. INPUT: @@ -2672,10 +2618,8 @@ def antisymmetrize(self, *pos): (with the convention position=0 for the first slot); if none, the antisymmetrization is performed over all the indices - OUTPUT: - - - an instance of :class:`CompWithSym` describing the antisymmetrized - components. + OUTPUT: an instance of :class:`CompWithSym` describing the + antisymmetrized components EXAMPLES: @@ -2782,7 +2726,6 @@ def antisymmetrize(self, *pos): True sage: c.antisymmetrize(2,0) == c.antisymmetrize(0,2) True - """ from sage.groups.perm_gps.permgroup_named import SymmetricGroup if not pos: @@ -2833,7 +2776,6 @@ def _matrix_(self): sage: matrix(c) == c._matrix_() True - """ from sage.matrix.constructor import matrix if self._nid != 2: @@ -3051,7 +2993,6 @@ def __init__(self, ring, frame, nb_indices, start_index=0, sage: from sage.tensor.modules.comp import CompWithSym sage: C = CompWithSym(ZZ, [1,2,3], 4, sym=(0,1), antisym=(2,3)) sage: TestSuite(C).run() - """ Components.__init__(self, ring, frame, nb_indices, start_index, output_formatter) @@ -3189,7 +3130,6 @@ def _new_instance(self): sage: c = CompWithSym(ZZ, [1,2,3], 4, sym=(0,1)) sage: a = c._new_instance() ; a 4-indices components w.r.t. [1, 2, 3], with symmetry on the index positions (0, 1) - """ return CompWithSym(self._ring, self._frame, self._nid, self._sindex, self._output_formatter, self._sym, self._antisym) @@ -3203,7 +3143,7 @@ def _ordered_indices(self, indices): INPUT: - ``indices`` -- list of indices (possibly a single integer if - self is a 1-index object) + ``self`` is a 1-index object) OUTPUT: @@ -3230,7 +3170,6 @@ def _ordered_indices(self, indices): (-1, (0, 1, 1, 2)) sage: c._ordered_indices([0,1,2,2]) (0, None) - """ from sage.combinat.permutation import Permutation ind = list(self._check_indices(indices)) @@ -3271,7 +3210,7 @@ def __getitem__(self, args): INPUT: - ``args`` -- list of indices (possibly a single integer if - self is a 1-index object) or the character ``:`` for the full list + ``self`` is a 1-index object) or the character ``:`` for the full list of components OUTPUT: @@ -3295,7 +3234,6 @@ def __getitem__(self, args): -5 sage: c[0,1,2,1] -5 - """ no_format = self._output_formatter is None format_type = None # default value, possibly redefined below @@ -3332,7 +3270,7 @@ def __getitem__(self, args): else: return self._output_formatter(self._ring.zero(), format_type) - else: # non zero value + else: # nonzero value if no_format: if sign == 1: return self._comp[ind] @@ -3353,12 +3291,12 @@ def __getitem__(self, args): def __setitem__(self, args, value): r""" - Sets the component corresponding to the given indices. + Set the component corresponding to the given indices. INPUT: - ``args`` -- list of indices (possibly a single integer if - self is a 1-index object) ; if ``[:]`` is provided, all the + ``self`` is a 1-index object) ; if ``[:]`` is provided, all the components are set - ``value`` -- the value to be set or a list of values if ``args = [:]`` @@ -3382,7 +3320,6 @@ def __setitem__(self, args, value): Traceback (most recent call last): ... ValueError: by antisymmetry, the component cannot have a nonzero value for the indices (2, 2) - """ format_type = None # default value, possibly redefined below if isinstance(args, list): # case of [[...]] syntax @@ -3456,9 +3393,7 @@ def swap_adjacent_indices(self, pos1, pos2, pos3): the last index of set 1 (since the two sets are adjacent) - ``pos3`` -- 1 + position of the last index of set 2 - OUTPUT: - - - Components with index set 1 permuted with index set 2. + OUTPUT: components with index set 1 permuted with index set 2 EXAMPLES: @@ -3487,7 +3422,6 @@ def swap_adjacent_indices(self, pos1, pos2, pos3): 3 sage: c1[2,1,0] -3 - """ result = self._new_instance() # The symmetries: @@ -3518,9 +3452,7 @@ def __add__(self, other): - ``other`` -- components of the same number of indices and defined on the same frame as ``self`` - OUTPUT: - - - components resulting from the addition of ``self`` and ``other`` + OUTPUT: components resulting from the addition of ``self`` and ``other`` EXAMPLES:: @@ -3566,7 +3498,6 @@ def __add__(self, other): sage: s_par[:] == s[:] True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if isinstance(other, (int, Integer)) and other == 0: return +self @@ -3679,9 +3610,7 @@ def __mul__(self, other): - ``other`` -- components, on the same frame as ``self`` - OUTPUT: - - - the tensor product of ``self`` by ``other`` + OUTPUT: the tensor product of ``self`` by ``other`` EXAMPLES:: @@ -3727,7 +3656,6 @@ def __mul__(self, other): sage: s2_par[:] == s2[:] True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if not isinstance(other, Components): raise TypeError("the second argument for the tensor product " + @@ -3888,7 +3816,6 @@ def trace(self, pos1, pos2): [-3 3 -1] sage: [[sum(c[i,k,k,j] for k in range(3)) for j in range(3)] for i in range(3)] # check [[0, 0, 0], [-2, 1, 0], [-3, 3, -1]] - """ if self._nid < 2: raise TypeError("contraction can be performed only on " + @@ -3994,9 +3921,7 @@ def non_redundant_index_generator(self): Generator of indices, with only ordered indices in case of symmetries, so that only non-redundant indices are generated. - OUTPUT: - - - an iterable index + OUTPUT: an iterable index EXAMPLES: @@ -4063,7 +3988,6 @@ def non_redundant_index_generator(self): sage: c = CompFullyAntiSym(QQ, V.basis(), 5) sage: list(c.non_redundant_index_generator()) # nothing since c is identically zero in this case (for 5 > 4) [] - """ if self._nid == 0 or self._dim == 0: return @@ -4334,7 +4258,6 @@ def symmetrize(self, *pos): ], with symmetry on the index positions (1, 2) sage: s == 0 # because (1,2) are involved in the original antisymmetry True - """ from sage.groups.perm_gps.permgroup_named import SymmetricGroup if not pos: @@ -4595,7 +4518,6 @@ def antisymmetrize(self, *pos): -2 sage: s[2,1,0,1] # the antisymmetry (0,2) holds -27/2 - """ from sage.groups.perm_gps.permgroup_named import SymmetricGroup if not pos: @@ -4740,7 +4662,7 @@ class CompFullySym(CompWithSym): [-2 0 3] [ 0 3 0] - Internally, only non-redundant and non-zero components are stored:: + Internally, only non-redundant and nonzero components are stored:: sage: c._comp # random output order of the component dictionary {(0, 0): 1, (0, 1): -2, (1, 2): 3} @@ -4827,7 +4749,6 @@ class CompFullySym(CompWithSym): ], with symmetry on the index positions (0, 1) sage: 2*b1 + a == a + 2*b1 True - """ def __init__(self, ring, frame, nb_indices, start_index=0, output_formatter=None): @@ -4837,7 +4758,6 @@ def __init__(self, ring, frame, nb_indices, start_index=0, sage: from sage.tensor.modules.comp import CompFullySym sage: C = CompFullySym(ZZ, (1,2,3), 2) sage: TestSuite(C).run() - """ CompWithSym.__init__(self, ring, frame, nb_indices, start_index, output_formatter, sym=range(nb_indices)) @@ -4852,13 +4772,12 @@ def _repr_symmetry(self): sage: c = CompFullySym(ZZ, (1,2,3), 4) sage: c._repr_symmetry() ('Fully symmetric ', '') - """ return "Fully symmetric ", "" def _new_instance(self): r""" - Creates a :class:`CompFullySym` instance w.r.t. the same frame, + Create a :class:`CompFullySym` instance w.r.t. the same frame, and with the same number of indices. EXAMPLES:: @@ -4867,7 +4786,6 @@ def _new_instance(self): sage: c = CompFullySym(ZZ, (1,2,3), 4) sage: c._new_instance() Fully symmetric 4-indices components w.r.t. (1, 2, 3) - """ return CompFullySym(self._ring, self._frame, self._nid, self._sindex, self._output_formatter) @@ -4879,7 +4797,7 @@ def __getitem__(self, args): INPUT: - ``args`` -- list of indices (possibly a single integer if - self is a 1-index object) or the character ``:`` for the full list + ``self`` is a 1-index object) or the character ``:`` for the full list of components OUTPUT: @@ -4901,7 +4819,6 @@ def __getitem__(self, args): [0 4 0] [4 0 0] [0 0 0] - """ no_format = self._output_formatter is None format_type = None # default value, possibly redefined below @@ -4931,7 +4848,7 @@ def __getitem__(self, args): return self._get_list(indices, no_format, format_type) ind = self._ordered_indices(indices)[1] # [0]=sign is not used - if ind in self._comp: # non zero value + if ind in self._comp: # nonzero value if no_format: return self._comp[ind] elif format_type is None: @@ -4950,13 +4867,13 @@ def __getitem__(self, args): def __setitem__(self, args, value): r""" - Sets the component corresponding to the given indices. + Set the component corresponding to the given indices. INPUT: - ``indices`` -- list of indices (possibly a single integer if - self is a 1-index object) ; if [:] is provided, all the components - are set. + ``self`` is a 1-index object); if [:] is provided, all the components + are set - ``value`` -- the value to be set or a list of values if ``args = [:]`` @@ -4979,7 +4896,6 @@ def __setitem__(self, args, value): [1 2 3] [2 4 5] [3 5 6] - """ format_type = None # default value, possibly redefined below if isinstance(args, list): # case of [[...]] syntax @@ -5033,9 +4949,7 @@ def __add__(self, other): - ``other`` -- components of the same number of indices and defined on the same frame as ``self`` - OUTPUT: - - - components resulting from the addition of ``self`` and ``other`` + OUTPUT: components resulting from the addition of ``self`` and ``other`` EXAMPLES:: @@ -5100,7 +5014,6 @@ def __add__(self, other): sage: s_par == c.__add__(a) # test of commutativity of parallel comput. True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if isinstance(other, (int, Integer)) and other == 0: return +self @@ -5194,7 +5107,7 @@ class CompFullyAntiSym(CompWithSym): [ -3 0 -1] [-1/2 1 0] - Internally, only non-redundant and non-zero components are stored:: + Internally, only non-redundant and nonzero components are stored:: sage: c._comp # random output order of the component dictionary {(0, 1): 3, (0, 2): 1/2, (1, 2): -1} @@ -5286,7 +5199,6 @@ class CompFullyAntiSym(CompWithSym): ], with antisymmetry on the index positions (0, 1) sage: 2*b1 + a == a + 2*b1 True - """ def __init__(self, ring, frame, nb_indices, start_index=0, output_formatter=None): @@ -5296,7 +5208,6 @@ def __init__(self, ring, frame, nb_indices, start_index=0, sage: from sage.tensor.modules.comp import CompFullyAntiSym sage: C = CompFullyAntiSym(ZZ, (1,2,3), 2) sage: TestSuite(C).run() - """ CompWithSym.__init__(self, ring, frame, nb_indices, start_index, output_formatter, antisym=range(nb_indices)) @@ -5311,13 +5222,12 @@ def _repr_symmetry(self): sage: c = CompFullyAntiSym(ZZ, (1,2,3), 4) sage: c._repr_symmetry() ('Fully antisymmetric ', '') - """ return "Fully antisymmetric ", "" def _new_instance(self): r""" - Creates a :class:`CompFullyAntiSym` instance w.r.t. the same frame, + Create a :class:`CompFullyAntiSym` instance w.r.t. the same frame, and with the same number of indices. EXAMPLES:: @@ -5326,7 +5236,6 @@ def _new_instance(self): sage: c = CompFullyAntiSym(ZZ, (1,2,3), 4) sage: c._new_instance() Fully antisymmetric 4-indices components w.r.t. (1, 2, 3) - """ return CompFullyAntiSym(self._ring, self._frame, self._nid, self._sindex, self._output_formatter) @@ -5340,9 +5249,7 @@ def __add__(self, other): - ``other`` -- components of the same number of indices and defined on the same frame as ``self`` - OUTPUT: - - - components resulting from the addition of ``self`` and ``other`` + OUTPUT: components resulting from the addition of ``self`` and ``other`` EXAMPLES:: @@ -5399,7 +5306,6 @@ def __add__(self, other): sage: s_par == a + c True sage: Parallelism().set('tensor', nproc=1) # switch off parallelization - """ if isinstance(other, (int, Integer)) and other == 0: return +self @@ -5554,7 +5460,6 @@ def interior_product(self, other): 360 sage: c == a.contract(0, 1, 2, 3, b, 0, 1, 2, 3) True - """ from sage.arith.misc import factorial # Sanity checks: @@ -5655,7 +5560,6 @@ class KroneckerDelta(CompFullySym): sage: d = KroneckerDelta(QQ, V.basis(), output_formatter=str) sage: d[:] [['1', '0', '0'], ['0', '1', '0'], ['0', '0', '1']] - """ def __init__(self, ring, frame, start_index=0, output_formatter=None): r""" @@ -5664,7 +5568,6 @@ def __init__(self, ring, frame, start_index=0, output_formatter=None): sage: from sage.tensor.modules.comp import KroneckerDelta sage: d = KroneckerDelta(ZZ, (1,2,3)) sage: TestSuite(d).run() - """ CompFullySym.__init__(self, ring, frame, 2, start_index, output_formatter) @@ -5680,14 +5583,13 @@ def _repr_(self): sage: from sage.tensor.modules.comp import KroneckerDelta sage: KroneckerDelta(ZZ, (1,2,3)) Kronecker delta of size 3x3 - """ n = str(self._dim) return "Kronecker delta of size " + n + "x" + n def __setitem__(self, args, value): r""" - Should not be used (the components of a Kronecker delta are constant) + Should not be used (the components of a Kronecker delta are constant). EXAMPLES:: @@ -5697,6 +5599,5 @@ def __setitem__(self, args, value): Traceback (most recent call last): ... TypeError: the components of a Kronecker delta cannot be changed - """ raise TypeError("the components of a Kronecker delta cannot be changed") diff --git a/src/sage/tensor/modules/ext_pow_free_module.py b/src/sage/tensor/modules/ext_pow_free_module.py index fb708df8345..f9250e59e35 100644 --- a/src/sage/tensor/modules/ext_pow_free_module.py +++ b/src/sage/tensor/modules/ext_pow_free_module.py @@ -159,7 +159,7 @@ class ExtPowerFreeModule(FiniteRankFreeModule_abstract): sage: A(0) is A.zero() True - while non-zero elements are constructed by providing their components in a + while nonzero elements are constructed by providing their components in a given basis:: sage: e @@ -217,7 +217,6 @@ class ExtPowerFreeModule(FiniteRankFreeModule_abstract): no symmetry; antisymmetry: (0, 1) sage: ta == a # equality as type-(2,0) tensors True - """ Element = AlternatingContrTensor @@ -233,7 +232,6 @@ def __init__(self, fmodule, degree, name=None, latex_name=None): 2nd exterior power of the Rank-3 free module M over the Integer Ring sage: TestSuite(A).run() - """ from sage.arith.misc import binomial from sage.typeset.unicode_characters import unicode_bigwedge @@ -290,7 +288,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, sage: a[e,0,2], a[e,1,2] = 3, -1 sage: a.display() a = 3 e_0∧e_2 - e_1∧e_2 - """ if isinstance(comp, (int, Integer)) and comp == 0: return self.zero() @@ -338,7 +335,6 @@ def _an_element_(self): on the 4-dimensional vector space M2 over the Rational Field sage: M2.default_basis() Basis (e_0,e_1,e_2,e_3) on the 4-dimensional vector space M2 over the Rational Field - """ resu = self.element_class(self._fmodule, self._degree) # Make sure that the base module has a default basis @@ -365,7 +361,6 @@ def zero(self): module M over the Integer Ring sage: A(0) is A.zero() True - """ resu = self._element_constructor_(name='zero', latex_name='0') for basis in self._fmodule._known_bases: @@ -414,7 +409,6 @@ def base_module(self): Rank-5 free module M over the Integer Ring sage: A.base_module() is M True - """ return self._fmodule @@ -435,7 +429,6 @@ def degree(self): 2 sage: M.exterior_power(4).degree() 4 - """ return self._degree @@ -539,7 +532,7 @@ class ExtPowerDualFreeModule(FiniteRankFreeModule_abstract): sage: A(0) is A.zero() True - while non-zero elements are constructed by providing their components in a + while nonzero elements are constructed by providing their components in a given basis:: sage: e @@ -601,7 +594,6 @@ class ExtPowerDualFreeModule(FiniteRankFreeModule_abstract): a = 3 e^0∧e^1 - e^0∧e^2 + 4 e^1∧e^2 sage: ta.symmetries() # the antisymmetry is of course preserved no symmetry; antisymmetry: (0, 1) - """ Element = FreeModuleAltForm @@ -617,7 +609,6 @@ def __init__(self, fmodule, degree, name=None, latex_name=None): 2nd exterior power of the dual of the Rank-3 free module M over the Integer Ring sage: TestSuite(A).run() - """ from sage.arith.misc import binomial from sage.typeset.unicode_characters import unicode_bigwedge @@ -674,7 +665,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, sage: a[e,0,2], a[e,1,2] = 3, -1 sage: a.display() a = 3 e^0∧e^2 - e^1∧e^2 - """ if isinstance(comp, (int, Integer)) and comp == 0: return self.zero() @@ -734,7 +724,6 @@ def _an_element_(self): Alternating form of degree 2 on the 4-dimensional vector space M2 over the Rational Field sage: M2.default_basis() Basis (e_0,e_1,e_2,e_3) on the 4-dimensional vector space M2 over the Rational Field - """ resu = self.element_class(self._fmodule, self._degree) # Make sure that the base module has a default basis @@ -761,7 +750,6 @@ def zero(self): the Integer Ring sage: A(0) is A.zero() True - """ resu = self._element_constructor_(name='zero', latex_name='0') for basis in self._fmodule._known_bases: @@ -788,7 +776,6 @@ def _repr_(self): '5th exterior power of the dual of the Rank-5 free module M over the Integer Ring' sage: M.dual_exterior_power(21)._repr_() '21st exterior power of the dual of the Rank-5 free module M over the Integer Ring' - """ description = "{}".format(self._degree.ordinal_str()) description += " exterior power of the dual of the {}".format( @@ -812,7 +799,6 @@ def base_module(self): Rank-5 free module M over the Integer Ring sage: A.base_module() is M True - """ return self._fmodule @@ -832,6 +818,5 @@ def degree(self): 2 sage: M.dual_exterior_power(4).degree() 4 - """ return self._degree diff --git a/src/sage/tensor/modules/finite_rank_free_module.py b/src/sage/tensor/modules/finite_rank_free_module.py index 3525745f331..0a979fd6b6f 100644 --- a/src/sage/tensor/modules/finite_rank_free_module.py +++ b/src/sage/tensor/modules/finite_rank_free_module.py @@ -582,7 +582,6 @@ def __init__( sage: TestSuite(M).run() sage: f = M.basis('f') sage: TestSuite(M).run() - """ # This duplicates the normalization done in __classcall_private__, # but it is needed for various subclasses. @@ -620,7 +619,6 @@ def _latex_(self): '\\mathcal{M}' sage: latex(M1) \mathcal{M} - """ if self._latex_name is None: return r'\mbox{' + str(self) + r'}' @@ -654,7 +652,6 @@ def rank(self) -> int: 27 sage: M.tensor_module(2,2).rank() 81 - """ return self._rank @@ -697,7 +694,6 @@ def zero(self): [[[0, 0, 0], [0, 0, 0], [0, 0, 0]], [[0, 0, 0], [0, 0, 0], [0, 0, 0]], [[0, 0, 0], [0, 0, 0], [0, 0, 0]]] - """ resu = self._element_constructor_(name='zero', latex_name='0') for basis in self._known_bases: @@ -1234,7 +1230,6 @@ class :class:`~sage.modules.module.Module`. 0.333333333333333 e_0 - 2.00000000000000 e_2 sage: v.display(e, format_spec=10) # 10 bits of precision 0.33 e_0 - 2.0 e_2 - """ Element = FiniteRankFreeModuleElement @@ -1244,7 +1239,7 @@ class :class:`~sage.modules.module.Module`. def __classcall_private__(cls, ring, rank, name=None, latex_name=None, start_index=0, output_formatter=None, category=None, ambient=None): r""" - Normalize init arguments for ``UniqueRepresentation`` + Normalize init arguments for ``UniqueRepresentation``. TESTS:: @@ -1289,7 +1284,6 @@ def __init__( sage: TestSuite(M).run() sage: f = M.basis('f') sage: TestSuite(M).run() - """ super().__init__(ring, rank, name=name, latex_name=latex_name, category=category, ambient=ambient) @@ -1320,7 +1314,7 @@ def __init__( def construction(self): """ - The construction functor and base ring for self. + The construction functor and base ring for ``self``. EXAMPLES:: @@ -1373,7 +1367,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, Element zero of the Rank-3 free module M over the Integer Ring sage: v = M._element_constructor_() ; v Element of the Rank-3 free module M over the Integer Ring - """ if isinstance(comp, (int, Integer)) and comp == 0: return self.zero() @@ -1398,7 +1391,6 @@ def _an_element_(self): True sage: v.parent() Rank-3 free module M over the Integer Ring - """ if self._def_basis is None: self.basis('e') @@ -1418,7 +1410,6 @@ def _repr_(self): sage: FiniteRankFreeModule(ZZ, 3, name='M') Rank-3 free module M over the Integer Ring - """ if self._ring in Fields(): description = "{}-dimensional vector space ".format(self._rank) @@ -1456,7 +1447,6 @@ def _Hom_(self, other, category=None): Set of Morphisms from Rank-3 free module M over the Integer Ring to Rank-2 free module N over the Integer Ring in Category of finite dimensional modules over Integer Ring - """ from .free_module_homset import FreeModuleHomset return FreeModuleHomset(self, other) @@ -1468,9 +1458,9 @@ def tensor_module(self, k, l, *, sym=None, antisym=None): INPUT: - - ``k`` -- non-negative integer; the contravariant rank, the tensor + - ``k`` -- nonnegative integer; the contravariant rank, the tensor type being `(k, l)` - - ``l`` -- non-negative integer; the covariant rank, the tensor type + - ``l`` -- nonnegative integer; the covariant rank, the tensor type being `(k, l)` - ``sym`` -- (default: ``None``) a symmetry or a list of symmetries among the tensor arguments: each symmetry is described by a tuple @@ -1650,7 +1640,7 @@ def exterior_power(self, p): INPUT: - - ``p`` -- non-negative integer + - ``p`` -- nonnegative integer OUTPUT: @@ -1690,7 +1680,6 @@ def exterior_power(self, p): See :class:`~sage.tensor.modules.ext_pow_free_module.ExtPowerFreeModule` for more documentation. - """ try: return self._exterior_powers[p] @@ -1725,7 +1714,7 @@ def dual_exterior_power(self, p): INPUT: - - ``p`` -- non-negative integer + - ``p`` -- nonnegative integer OUTPUT: @@ -1831,7 +1820,6 @@ def general_linear_group(self): See :class:`~sage.tensor.modules.free_module_linear_group.FreeModuleLinearGroup` for more documentation. - """ from sage.tensor.modules.free_module_linear_group import \ FreeModuleLinearGroup @@ -1999,7 +1987,6 @@ def basis(self, symbol, latex_symbol=None, from_family=None, For more documentation on bases see :class:`~sage.tensor.modules.free_module_basis.FreeModuleBasis`. - """ from .free_module_basis import FreeModuleBasis for other in self._known_bases: @@ -2053,7 +2040,6 @@ def _test_basis(self, tester=None, **options): running ._test_not_implemented_methods() . . . pass running ._test_pickling() . . . pass running ._test_some_elements() . . . pass - """ from sage.misc.sage_unittest import TestSuite # The intention is to raise an exception only if this is @@ -2288,7 +2274,6 @@ def tensor_from_comp(self, tensor_type, comp, name=None, latex_name=None): Rank-3 free module M over the Integer Ring sage: t.display(e) 4 e^0∧e^1 + 5 e^1∧e^2 - """ from .comp import CompWithSym, CompFullyAntiSym @@ -2378,7 +2363,6 @@ def alternating_contravariant_tensor(self, degree, name=None, See :class:`~sage.tensor.modules.alternating_contr_tensor.AlternatingContrTensor` for more documentation. - """ if degree == 1: return self.element_class(self, name=name, @@ -2438,7 +2422,6 @@ def alternating_form(self, degree, name=None, latex_name=None): See :class:`~sage.tensor.modules.free_module_alt_form.FreeModuleAltForm` for more documentation. - """ if degree == 0: try: @@ -2498,7 +2481,6 @@ def linear_form(self, name=None, latex_name=None): See :class:`~sage.tensor.modules.free_module_alt_form.FreeModuleAltForm` for more documentation. - """ return self.dual_exterior_power(1).element_class(self, 1, name=name, latex_name=latex_name) @@ -2584,7 +2566,6 @@ def automorphism(self, matrix=None, basis=None, name=None, See :class:`~sage.tensor.modules.free_module_automorphism.FreeModuleAutomorphism` for more documentation. - """ resu = self.general_linear_group().element_class(self, name=name, latex_name=latex_name) @@ -2689,7 +2670,6 @@ def sym_bilinear_form(self, name=None, latex_name=None): See :class:`~sage.tensor.modules.free_module_tensor.FreeModuleTensor` for more documentation. - """ return self.tensor_module(0,2).element_class(self, (0,2), name=name, latex_name=latex_name, sym=(0,1)) @@ -2733,7 +2713,6 @@ def dual(self): sage: e = M.basis('e') sage: e.dual_basis()[0] in M.dual() True - """ return self.dual_exterior_power(1) @@ -2770,7 +2749,6 @@ def irange(self, start: Optional[int] = None) -> Generator[int, None, None]: sage: M2 = FiniteRankFreeModule(ZZ, 3, start_index=-4) sage: list(M2.irange()) [-4, -3, -2] - """ si = self._sindex imax = self._rank + si @@ -2815,7 +2793,6 @@ def default_basis(self): Basis (f_1,f_2) on the Rank-2 free module M over the Integer Ring sage: M.default_basis() Basis (e_1,e_2) on the Rank-2 free module M over the Integer Ring - """ if self._def_basis is None: print("No default basis has been defined on the {}".format(self)) @@ -2823,7 +2800,7 @@ def default_basis(self): def set_default_basis(self, basis): r""" - Sets the default basis of ``self``. + Set the default basis of ``self``. The *default basis* is simply a basis whose name can be skipped in methods requiring a basis as an argument. By default, it is the first @@ -2849,7 +2826,6 @@ def set_default_basis(self, basis): sage: M.set_default_basis(f) sage: M.default_basis() Basis (f_1,f_2,f_3) on the Rank-3 free module M over the Integer Ring - """ from .free_module_basis import FreeModuleBasis if not isinstance(basis, FreeModuleBasis): @@ -2925,7 +2901,6 @@ def bases(self): sage: M.bases() [Basis (e_1,e_2,e_3) on the Rank-3 free module M_3 over the Integer Ring, Basis (f_1,f_2,f_3) on the Rank-3 free module M_3 over the Integer Ring] - """ return list(self._known_bases) @@ -3030,7 +3005,6 @@ def change_of_basis(self, basis1, basis2): sage: R == Q*P^(-1) True - """ if basis1 == basis2: return self.identity_map() @@ -3084,8 +3058,8 @@ def set_change_of_basis(self, basis1, basis2, change_of_basis, :class:`~sage.tensor.modules.free_module_automorphism.FreeModuleAutomorphism` describing the automorphism `P` that relates the basis `(e_i)` to the basis `(f_i)` according to `f_i = P(e_i)` - - ``compute_inverse`` (default: ``True``) -- if set to ``True``, the - inverse automorphism is computed and the change from basis `(f_i)` + - ``compute_inverse`` -- boolean (default: ``True``); if set to ``True``, + the inverse automorphism is computed and the change from basis `(f_i)` to `(e_i)` is set to it in the internal dictionary ``self._basis_changes`` @@ -3115,7 +3089,6 @@ def set_change_of_basis(self, basis1, basis2, change_of_basis, f_0 = e_0 - e_1 sage: e[0].display(f) e_0 = 3/5 f_0 + 1/5 f_1 - """ if basis1 not in self._known_bases: raise TypeError("{} is not a basis of the {}".format(basis1, @@ -3167,7 +3140,7 @@ def hom(self, codomain, matrix_rep, bases=None, name=None, - ``name`` -- (default: ``None``) string; name given to the homomorphism - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote - the homomorphism; if None, ``name`` will be used. + the homomorphism. If ``None``, ``name`` will be used. OUTPUT: @@ -3211,7 +3184,6 @@ def hom(self, codomain, matrix_rep, bases=None, name=None, See class :class:`~sage.tensor.modules.free_module_morphism.FiniteRankFreeModuleMorphism` for more documentation. - """ homset = Hom(self, codomain) return homset(matrix_rep, bases=bases, name=name, @@ -3238,7 +3210,7 @@ def endomorphism(self, matrix_rep, basis=None, name=None, latex_name=None): - ``name`` -- (default: ``None``) string; name given to the endomorphism - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote - the endomorphism; if none is provided, ``name`` will be used. + the endomorphism. If none is provided, ``name`` will be used. OUTPUT: @@ -3277,7 +3249,6 @@ def endomorphism(self, matrix_rep, basis=None, name=None, latex_name=None): See :class:`~sage.tensor.modules.free_module_morphism.FiniteRankFreeModuleMorphism` for more documentation. - """ from sage.categories.homset import End if basis is None: @@ -3355,7 +3326,6 @@ def identity_map(self, name='Id', latex_name=None): Identity map of the Rank-3 free module N over the Integer Ring sage: latex(Id) \mathrm{Id}_N - """ if self._identity_map is None: self._identity_map = self.general_linear_group().one() @@ -3432,7 +3402,7 @@ class FiniteRankDualFreeModule(ReflexiveModule_dual, FiniteRankFreeModule_abstra sage: A(0) is A.zero() True - while non-zero elements are constructed by providing their components in a + while nonzero elements are constructed by providing their components in a given basis:: sage: e @@ -3481,7 +3451,6 @@ def __init__(self, fmodule, name=None, latex_name=None): sage: A = FiniteRankDualFreeModule(M) ; A Dual of the Rank-3 free module M over the Integer Ring sage: TestSuite(A).run() - """ self._fmodule = fmodule rank = fmodule._rank @@ -3559,7 +3528,6 @@ def _an_element_(self): Linear form on the 4-dimensional vector space M2 over the Rational Field sage: M2.default_basis() Basis (e_0,e_1,e_2,e_3) on the 4-dimensional vector space M2 over the Rational Field - """ resu = self.element_class(self._fmodule, 1) # Make sure that the base module has a default basis @@ -3585,7 +3553,6 @@ def zero(self): Linear form zero on the Rank-3 free module M over the Integer Ring sage: A(0) is A.zero() True - """ resu = self._element_constructor_(name='zero', latex_name='0') for basis in self._fmodule._known_bases: @@ -3624,6 +3591,5 @@ def base_module(self): Rank-5 free module M over the Integer Ring sage: A.base_module() is M True - """ return self._fmodule diff --git a/src/sage/tensor/modules/format_utilities.py b/src/sage/tensor/modules/format_utilities.py index 1cc0e383f1e..d00e00f8071 100644 --- a/src/sage/tensor/modules/format_utilities.py +++ b/src/sage/tensor/modules/format_utilities.py @@ -70,7 +70,6 @@ def is_atomic(expr, sep=['+', '-']): False sage: is_atomic("(a mod b)", sep=['mod']) True - """ if not isinstance(expr, str): raise TypeError("The argument must be a string") @@ -125,7 +124,6 @@ def is_atomic_wedge_txt(expression): False sage: is_atomic_wedge_txt(r"(a∧b∧c)") True - """ return is_atomic(expression, sep=['∧']) @@ -171,7 +169,6 @@ def is_atomic_wedge_latex(expression): True sage: is_atomic_wedge_latex(r"\omega\wedge(\theta+a)") False - """ return is_atomic(expression, sep=['\\wedge']) @@ -194,7 +191,6 @@ def format_mul_txt(name1, operator, name2): '(a+b)*(c+d)' sage: format_mul_txt(None, '*', 'b') sage: format_mul_txt('a', '*', None) - """ if name1 is None or name2 is None: return None @@ -223,7 +219,6 @@ def format_mul_latex(name1, operator, name2): '\\left(a+b\\right)*\\left(c+d\\right)' sage: format_mul_latex(None, '*', 'b') sage: format_mul_latex('a', '*', None) - """ if name1 is None or name2 is None: return None @@ -248,7 +243,6 @@ def format_unop_txt(operator, name): sage: format_unop_txt('-', '(a+b)') '-(a+b)' sage: format_unop_txt('-', None) - """ if name is None: return None @@ -272,7 +266,6 @@ def format_unop_latex(operator, name): sage: format_unop_latex('-', '(a+b)') '-(a+b)' sage: format_unop_latex('-', None) - """ if name is None: return None @@ -299,7 +292,6 @@ class FormattedExpansion(SageObject): x/2 sage: latex(f) \frac{x}{2} - """ def __init__(self, txt=None, latex=None): r""" @@ -309,7 +301,6 @@ def __init__(self, txt=None, latex=None): sage: f = FormattedExpansion('v', r'\tilde v') sage: f v - """ self._txt = txt self._latex = latex @@ -324,7 +315,6 @@ def _repr_(self): sage: f = FormattedExpansion('v', r'\tilde v') sage: f._repr_() 'v' - """ return self._txt @@ -338,6 +328,5 @@ def _latex_(self) -> LatexExpr: sage: f = FormattedExpansion('v', r'\tilde v') sage: f._latex_() '\\tilde v' - """ return self._latex diff --git a/src/sage/tensor/modules/free_module_alt_form.py b/src/sage/tensor/modules/free_module_alt_form.py index 994980e02c8..68ebdb9fd66 100644 --- a/src/sage/tensor/modules/free_module_alt_form.py +++ b/src/sage/tensor/modules/free_module_alt_form.py @@ -210,7 +210,6 @@ class FreeModuleAltForm(FreeModuleTensor): Integer Ring sage: s.display(e) zero = 0 - """ def __init__(self, fmodule, degree, name=None, latex_name=None): r""" @@ -223,7 +222,7 @@ def __init__(self, fmodule, degree, name=None, latex_name=None): sage: e = M.basis('e') sage: a = FreeModuleAltForm(M, 2, name='a') sage: a[e,0,1] = 2 - sage: TestSuite(a).run(skip="_test_category") # see below + sage: TestSuite(a).run(skip='_test_category') # see below In the above test suite, _test_category fails because a is not an instance of a.parent().category().element_class. Actually alternating @@ -233,7 +232,6 @@ def __init__(self, fmodule, degree, name=None, latex_name=None): sage: a1 = M.dual_exterior_power(2).element_class(M, 2, name='a') sage: a1[e,0,1] = 2 sage: TestSuite(a1).run() - """ FreeModuleTensor.__init__(self, fmodule, (0,degree), name=name, latex_name=latex_name, @@ -289,7 +287,6 @@ def _new_instance(self): Rank-3 free module M over the Integer Ring sage: b._new_instance().parent() is b.parent() True - """ return self.__class__(self._fmodule, self._tensor_rank) @@ -322,7 +319,6 @@ def _new_comp(self, basis): sage: a._new_comp(e) 1-index components w.r.t. Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring - """ fmodule = self._fmodule # the base free module if self._tensor_rank == 1: @@ -344,7 +340,6 @@ def degree(self): sage: a = M.alternating_form(2, name='a') sage: a.degree() 2 - """ return self._tensor_rank @@ -382,7 +377,6 @@ def _display_expansion(self, basis=None, format_spec=None): e^0 - 3 e^1 + 4 e^2 sage: latex(a._display_expansion()) # display in the notebook e^{0} -3 e^{1} + 4 e^{2} - """ from sage.misc.latex import latex from sage.typeset.unicode_characters import unicode_wedge @@ -560,7 +554,6 @@ def display(self, basis=None, format_spec=None): sage: a[0,1] = SR.var('t', domain='real') sage: a.display() t e^0∧e^1 - """ from sage.misc.latex import latex from sage.tensor.modules.format_utilities import FormattedExpansion @@ -641,7 +634,6 @@ def wedge(self, other): True sage: d.wedge(c) == c.wedge(d) True - """ from sage.typeset.unicode_characters import unicode_wedge from .format_utilities import is_atomic @@ -809,7 +801,6 @@ def interior_product(self, alt_tensor): -60 sage: c == a.contract(0, 1, 2, b, 0, 1, 2) True - """ from .format_utilities import is_atomic from .alternating_contr_tensor import AlternatingContrTensor diff --git a/src/sage/tensor/modules/free_module_automorphism.py b/src/sage/tensor/modules/free_module_automorphism.py index e8a779482f4..3a826b1e0ef 100644 --- a/src/sage/tensor/modules/free_module_automorphism.py +++ b/src/sage/tensor/modules/free_module_automorphism.py @@ -56,7 +56,7 @@ class FreeModuleAutomorphism(FreeModuleTensor, MultiplicativeGroupElement): - ``name`` -- (default: ``None``) name given to the automorphism - ``latex_name`` -- (default: ``None``) LaTeX symbol to denote the automorphism; if none is provided, the LaTeX symbol is set to ``name`` - - ``is_identity`` -- (default: ``False``) determines whether the + - ``is_identity`` -- boolean (default: ``False``); determines whether the constructed object is the identity automorphism, i.e. the identity map of `M` considered as an automorphism (the identity element of the general linear group) @@ -254,7 +254,6 @@ class FreeModuleAutomorphism(FreeModuleTensor, MultiplicativeGroupElement): True sage: s.matrix(f) == a.matrix(f) + b.matrix(f) True - """ def __init__(self, fmodule, name=None, latex_name=None): r""" @@ -265,7 +264,7 @@ def __init__(self, fmodule, name=None, latex_name=None): sage: from sage.tensor.modules.free_module_automorphism import FreeModuleAutomorphism sage: a = FreeModuleAutomorphism(M, name='a') sage: a[e,:] = [[-1,0,0],[0,1,2],[0,1,3]] - sage: TestSuite(a).run(skip="_test_category") # see below + sage: TestSuite(a).run(skip='_test_category') # see below In the above test suite, _test_category fails because a is not an instance of a.parent().category().element_class. Actually automorphism @@ -285,7 +284,6 @@ def __init__(self, fmodule, name=None, latex_name=None): sage: b = M.general_linear_group().an_element() sage: TestSuite(b).run() - """ FreeModuleTensor.__init__(self, fmodule, (1,1), name=name, latex_name=latex_name, @@ -312,7 +310,6 @@ def _repr_(self): Automorphism a of the 3-dimensional vector space M over the Rational Field sage: M.identity_map() Identity map of the 3-dimensional vector space M over the Rational Field - """ if self._is_identity: description = "Identity map " @@ -340,7 +337,6 @@ def _new_instance(self): sage: Id = M.identity_map() sage: Id._new_instance() Automorphism of the Rank-3 free module M over the Integer Ring - """ return self.__class__(self._fmodule) @@ -360,7 +356,6 @@ def _del_derived(self): Rational Field sage: a._del_derived() sage: a._inverse # has been reset to None - """ # First delete the derived quantities pertaining to FreeModuleTensor: FreeModuleTensor._del_derived(self) @@ -479,7 +474,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such Kronecker delta of size 3x3 sage: id.comp(f) Kronecker delta of size 3x3 - """ if self._is_identity: raise ValueError("the components of the identity map cannot be " @@ -551,7 +545,6 @@ class :class:`~sage.tensor.modules.comp.Components`; Kronecker delta of size 3x3 sage: id.comp(f) Kronecker delta of size 3x3 - """ if self._is_identity: raise ValueError("the components of the identity map cannot be " @@ -613,7 +606,6 @@ def __call__(self, *arg): True sage: id(b,v) == b(v) True - """ from .free_module_element import FiniteRankFreeModuleElement if len(arg) > 1: @@ -752,7 +744,6 @@ def __invert__(self): sage: c.inverse() Automorphism (a^(-1)*b)^(-1) of the Rank-3 free module M over the Integer Ring - """ from .comp import Components if self._is_identity: @@ -845,7 +836,6 @@ def _mul_(self, other): True sage: a.inverse()._mul_(a) == id True - """ # No need for consistency check since self and other are guaranteed # to have the same parent. In particular, they are defined on the same @@ -1027,7 +1017,6 @@ def matrix(self, basis1=None, basis2=None): [1 0 0] [0 1 0] [0 0 1] - """ from sage.matrix.constructor import matrix fmodule = self._fmodule @@ -1131,7 +1120,6 @@ def det(self): sage: id = M.identity_map() sage: id.det() 1 - """ return self._some_matrix().det @@ -1213,6 +1201,5 @@ def trace(self): sage: id = M.identity_map() sage: id.trace() 2 - """ return self._some_matrix().trace diff --git a/src/sage/tensor/modules/free_module_basis.py b/src/sage/tensor/modules/free_module_basis.py index 1f67d8b2e81..4e531b54e6e 100644 --- a/src/sage/tensor/modules/free_module_basis.py +++ b/src/sage/tensor/modules/free_module_basis.py @@ -174,7 +174,6 @@ def _test_iter_len(self, **options): sage: M = FiniteRankFreeModule(ZZ, 3, name='M') sage: e = M.basis('e') sage: e._test_iter_len() - """ tester = self._tester(**options) g = iter(self) @@ -257,7 +256,6 @@ def __getitem__(self, index): Element e_2 of the Rank-3 free module M over the Integer Ring sage: e1.__getitem__(3) Element e_3 of the Rank-3 free module M over the Integer Ring - """ si = self._fmodule._sindex if isinstance(index, slice): @@ -300,7 +298,6 @@ def _latex_(self): sage: f = e.dual_basis() sage: f._latex_() '\\left(e^{0},e^{1},e^{2}\\right)' - """ return self._latex_name @@ -371,7 +368,6 @@ def set_name(self, symbol, latex_symbol=None, indices=None, sage: latex(e) \left(E_{\alpha},E_{\beta},E_{\gamma}\right) sage: e.set_name('e') # back to the default - """ n = self._fmodule._rank if index_position == "down": @@ -486,7 +482,6 @@ class FreeModuleCoBasis(Basis_abstract): TESTS:: sage: TestSuite(f).run() - """ def __init__(self, basis, symbol, latex_symbol=None, indices=None, latex_indices=None): @@ -498,7 +493,6 @@ def __init__(self, basis, symbol, latex_symbol=None, indices=None, sage: e = M.basis('e') sage: f = FreeModuleCoBasis(e, 'f') sage: TestSuite(f).run() - """ self._basis = basis Basis_abstract.__init__(self, basis._fmodule, symbol, latex_symbol, @@ -550,7 +544,6 @@ def _repr_(self): sage: f Dual basis (e^0,e^1,e^2) on the Rank-3 free module M over the Integer Ring - """ return "Dual basis {} on the {}".format(self._name, self._fmodule) @@ -663,7 +656,6 @@ class FreeModuleBasis(Basis_abstract): sage: TestSuite(e).run() sage: TestSuite(f).run() sage: TestSuite(g).run() - """ # The following class attribute must be redefined by any derived class: _cobasis_class = FreeModuleCoBasis @@ -718,7 +710,6 @@ def __init__(self, fmodule, symbol, latex_symbol=None, indices=None, sage: M = FiniteRankFreeModule(ZZ, 3, name='M') sage: e = FreeModuleBasis(M, 'e', latex_symbol=r'\epsilon') sage: TestSuite(e).run() - """ Basis_abstract.__init__(self, fmodule, symbol, latex_symbol, indices, latex_indices) @@ -786,7 +777,6 @@ def _repr_(self): sage: e1 = M1.basis('e') sage: e1 Basis (e_1,e_2,e_3) on the Rank-3 free module M over the Integer Ring - """ return "Basis {} on the {}".format(self._name, self._fmodule) @@ -820,9 +810,7 @@ def _new_instance(self, symbol, latex_symbol=None, indices=None, - ``latex_symbol_dual`` -- (default: ``None``) same as ``latex_symbol`` but for the dual basis - OUTPUT: - - - instance of :class:`FreeModuleBasis` + OUTPUT: instance of :class:`FreeModuleBasis` EXAMPLES:: @@ -838,7 +826,6 @@ def _new_instance(self, symbol, latex_symbol=None, indices=None, Basis (E_x,E_y,E_z) on the Rank-3 free module M over the Integer Ring sage: _.dual_basis() Dual basis (E^x,E^y,E^z) on the Rank-3 free module M over the Integer Ring - """ return FreeModuleBasis(self._fmodule, symbol, latex_symbol=latex_symbol, indices=indices, latex_indices=latex_indices, @@ -854,7 +841,7 @@ def _init_from_family(self, family): INPUT: - - ``family``: a family of elements of ``self.free_module()`` that are + - ``family`` -- a family of elements of ``self.free_module()`` that are linearly independent and spanning ``self.free_module()`` EXAMPLES:: @@ -875,7 +862,6 @@ def _init_from_family(self, family): e_1 = 1/2 f_1 + 1/2 f_2 sage: e[2].display(f) e_2 = 1/2 f_1 - 1/2 f_2 - """ fmodule = self._fmodule n = fmodule.rank() @@ -922,7 +908,6 @@ def module(self): Rank-3 free module M over the Integer Ring sage: e.module() is M True - """ return self._fmodule @@ -960,7 +945,6 @@ def dual_basis(self): (0, 1, 0) sage: f[3](e[1]), f[3](e[2]), f[3](e[3]) (0, 0, 1) - """ return self._dual_basis @@ -1035,7 +1019,6 @@ def new_basis(self, change_of_basis, symbol, latex_symbol=None, sage: b.dual_basis() Dual basis (A,B) on the 2-dimensional vector space M over the Rational Field - """ from .free_module_automorphism import FreeModuleAutomorphism if not isinstance(change_of_basis, FreeModuleAutomorphism): diff --git a/src/sage/tensor/modules/free_module_element.py b/src/sage/tensor/modules/free_module_element.py index 3acba1a9fb0..2f783c57eb5 100644 --- a/src/sage/tensor/modules/free_module_element.py +++ b/src/sage/tensor/modules/free_module_element.py @@ -191,7 +191,6 @@ class FiniteRankFreeModuleElement(AlternatingContrTensor): module M over the Integer Ring sage: s.display() a∧b = -2 e_0∧e_1 - 6 e_0∧e_2 + 7 e_1∧e_2 - """ def __init__( @@ -208,7 +207,7 @@ def __init__( sage: e = M.basis('e') sage: v = FiniteRankFreeModuleElement(M, name='v') sage: v[e,:] = (-2, 1, 3) - sage: TestSuite(v).run(skip="_test_category") # see below + sage: TestSuite(v).run(skip='_test_category') # see below In the above test suite, _test_category fails because v is not an instance of v.parent().category().element_class. Actually module @@ -218,7 +217,6 @@ def __init__( sage: v1 = M.element_class(M, name='v') sage: v1[e,:] = (-2, 1, 3) sage: TestSuite(v1).run() - """ AlternatingContrTensor.__init__(self, fmodule, 1, name=name, latex_name=latex_name) @@ -233,7 +231,6 @@ def _repr_(self) -> str: sage: e = M.basis('e') sage: M([1,-2,3], name='v') Element v of the Rank-3 free module M over the Integer Ring - """ description = "Element " if self._name is not None: @@ -252,9 +249,7 @@ def _new_comp(self, basis: FreeModuleBasis) -> Components: - ``basis`` -- basis of the free module on which ``self`` is defined - OUTPUT: - - - an instance of :class:`~sage.tensor.modules.comp.Components` + OUTPUT: an instance of :class:`~sage.tensor.modules.comp.Components` EXAMPLES:: @@ -266,7 +261,6 @@ def _new_comp(self, basis: FreeModuleBasis) -> Components: Rank-3 free module M over the Integer Ring sage: type(v._new_comp(e)) - """ fmodule = self._fmodule # the base free module return Components(fmodule._ring, basis, 1, start_index=fmodule._sindex, @@ -285,6 +279,5 @@ def _new_instance(self): Element of the Rank-3 free module M over the Integer Ring sage: v._new_instance().parent() is v.parent() True - """ return self.__class__(self._fmodule) diff --git a/src/sage/tensor/modules/free_module_homset.py b/src/sage/tensor/modules/free_module_homset.py index 5ea2ffb4427..18311ae3373 100644 --- a/src/sage/tensor/modules/free_module_homset.py +++ b/src/sage/tensor/modules/free_module_homset.py @@ -179,7 +179,6 @@ def __init__(self, fmodule1, fmodule2, name, latex_name): ....: latex_name=r'\mathcal{L}(M,N)') sage: latex(H) \mathcal{L}(M,N) - """ Homset.__init__(self, fmodule1, fmodule2) self._name = name @@ -198,7 +197,6 @@ def _latex_(self): '\\mathrm{Hom}\\left(M,N\\right)' sage: latex(H) # indirect doctest \mathrm{Hom}\left(M,N\right) - """ if self._latex_name is None: return r'\mbox{' + str(self) + r'}' @@ -237,7 +235,6 @@ def __call__(self, *args, **kwds): [5 6] sage: a == H([[1,2],[3,4],[5,6]], bases=(e,f)) True - """ from sage.structure.parent import Parent return Parent.__call__(self, *args, **kwds) @@ -262,10 +259,10 @@ def _element_constructor_(self, matrix_rep, bases=None, name=None, by the default bases of each module is assumed. - ``name`` -- (default: ``None``) string; name given to the homomorphism - - ``latex_name`` -- (default: ``None``)string; LaTeX symbol to denote - the homomorphism; if none is provided, ``name`` will be used. - - ``is_identity`` -- (default: ``False``) determines whether the - constructed object is the identity endomorphism; if set to ``True``, + - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote + the homomorphism. If none is provided, ``name`` will be used. + - ``is_identity`` -- boolean (default: ``False``); determines whether the + constructed object is the identity endomorphism. If set to ``True``, then N must be M and the entry ``matrix_rep`` is not used. EXAMPLES: @@ -318,7 +315,6 @@ def _element_constructor_(self, matrix_rep, bases=None, name=None, Generic endomorphism of Rank-3 free module M over the Integer Ring sage: phi_a1 == phi True - """ # Standard construction: return self.element_class(self, matrix_rep, bases=bases, name=name, @@ -343,7 +339,6 @@ def _an_element_(self): [1 1 1] sage: phi == Hom(M,N).an_element() True - """ ring = self.base_ring() m = self.domain().rank() @@ -469,7 +464,6 @@ def __init__(self, fmodule, name, latex_name): ....: latex_name=r'\mathcal{L}(M,N)') sage: latex(H) \mathcal{L}(M,N) - """ FreeModuleHomset.__init__(self, fmodule, fmodule, name, latex_name) self._one = None # to be set by self.one() @@ -495,7 +489,6 @@ def _coerce_map_from_(self, other): sage: End(M)._coerce_map_from_(M.general_linear_group()) True - """ from sage.tensor.modules.tensor_free_module import TensorFreeModule from sage.tensor.modules.free_module_linear_group import \ @@ -531,10 +524,10 @@ def _element_constructor_(self, matrix_rep, bases=None, name=None, by the default bases of each module is assumed. - ``name`` -- (default: ``None``) string; name given to the homomorphism - - ``latex_name`` -- (default: ``None``)string; LaTeX symbol to denote - the homomorphism; if none is provided, ``name`` will be used. - - ``is_identity`` -- (default: ``False``) determines whether the - constructed object is the identity endomorphism; if set to ``True``, + - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote + the homomorphism. If none is provided, ``name`` will be used. + - ``is_identity`` -- boolean (default: ``False``); determines whether the + constructed object is the identity endomorphism. If set to ``True``, then N must be M and the entry ``matrix_rep`` is not used. EXAMPLES: @@ -570,7 +563,6 @@ def _element_constructor_(self, matrix_rep, bases=None, name=None, Generic endomorphism of Rank-3 free module M over the Integer Ring sage: phi_a1 == phi True - """ if isinstance(matrix_rep, FreeModuleTensor): # coercion of a type-(1,1) tensor to an endomorphism @@ -651,7 +643,6 @@ def one(self): sage: GL = M.general_linear_group() sage: M.identity_map() == GL(H.one()) True - """ if self._one is None: self._one = self.element_class(self, [], is_identity=True) diff --git a/src/sage/tensor/modules/free_module_linear_group.py b/src/sage/tensor/modules/free_module_linear_group.py index e9a6ac60655..bb9ccf74e9a 100644 --- a/src/sage/tensor/modules/free_module_linear_group.py +++ b/src/sage/tensor/modules/free_module_linear_group.py @@ -258,7 +258,6 @@ class FreeModuleLinearGroup(UniqueRepresentation, Parent): ... TypeError: the Type-(1,1) tensor t_0 on the Rank-3 free module M over the Integer Ring is not invertible - """ Element = FreeModuleAutomorphism @@ -277,7 +276,6 @@ def __init__(self, fmodule): sage: GL.category() Category of groups sage: TestSuite(GL).run() - """ if not isinstance(fmodule, FiniteRankFreeModule): raise TypeError("{} is not a free module of finite rank".format( @@ -357,7 +355,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, Automorphism t of the Rank-2 free module M over the Integer Ring sage: a.matrix(e) == t[e,:] True - """ from sage.tensor.modules.free_module_tensor import FreeModuleTensor from sage.tensor.modules.free_module_morphism import \ @@ -425,7 +422,6 @@ def _an_element_(self): sage: a.matrix(e) [ 1 0] [ 0 -1] - """ resu = self.element_class(self._fmodule) # Make sure that the base module has a default basis @@ -503,7 +499,6 @@ def one(self): sage: GL.one().matrix(f) [1 0] [0 1] - """ resu = self._element_constructor_(name='Id', latex_name=r'\mathrm{Id}') # Initialization of the components (Kronecker delta) in some basis: @@ -529,7 +524,6 @@ def _repr_(self): sage: GL = M.general_linear_group() sage: GL._repr_() 'General linear group of the Rank-2 free module M over the Integer Ring' - """ return "General linear group of the {}".format(self._fmodule) @@ -543,7 +537,6 @@ def _latex_(self): sage: GL = M.general_linear_group() sage: GL._latex_() \mathrm{GL}\left( M \right) - """ from sage.misc.latex import latex return r"\mathrm{GL}\left(" + latex(self._fmodule) + r"\right)" @@ -565,6 +558,5 @@ def base_module(self): Rank-2 free module M over the Integer Ring sage: GL.base_module() is M True - """ return self._fmodule diff --git a/src/sage/tensor/modules/free_module_morphism.py b/src/sage/tensor/modules/free_module_morphism.py index d575601392b..cb119b3eecb 100644 --- a/src/sage/tensor/modules/free_module_morphism.py +++ b/src/sage/tensor/modules/free_module_morphism.py @@ -59,7 +59,7 @@ class FiniteRankFreeModuleMorphism(Morphism): INPUT: - - ``parent`` -- hom-set Hom(M,N) to which the homomorphism belongs + - ``parent`` -- Hom-set Hom(M,N) to which the homomorphism belongs - ``matrix_rep`` -- matrix representation of the homomorphism with respect to the bases ``bases``; this entry can actually be any material from which a matrix of size rank(N)*rank(M) of @@ -71,7 +71,7 @@ class FiniteRankFreeModuleMorphism(Morphism): default bases of each module is assumed. - ``name`` -- (default: ``None``) string; name given to the homomorphism - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the - homomorphism; if ``None``, ``name`` will be used. + homomorphism. If ``None``, ``name`` will be used. EXAMPLES: @@ -268,7 +268,6 @@ def _latex_(self): sage: phi = M.hom(N, [[-1,2,0], [5,1,2]]) sage: phi._latex_() '\\mbox{Generic morphism:\n From: Rank-3 free module M over the Integer Ring\n To: Rank-2 free module N over the Integer Ring}' - """ if self._latex_name is None: return r'\mbox{' + str(self) + r'}' @@ -283,9 +282,7 @@ def __eq__(self, other): - ``other`` -- a free module morphism (or 0) - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise EXAMPLES:: @@ -341,7 +338,6 @@ def __eq__(self, other): True sage: phi.__eq__(Hom(M,N).zero()) True - """ if isinstance(other, (int, Integer)): # other should be 0 if other == 0: @@ -391,7 +387,6 @@ def __ne__(self, other): True sage: Hom(M,N).zero().__ne__(0) False - """ return not self == other @@ -435,9 +430,7 @@ def _add_(self, other): - ``other`` -- a free module morphism (same parent as ``self``) - OUTPUT: - - - the homomorphism resulting from the addition of ``self`` and ``other`` + OUTPUT: the homomorphism resulting from the addition of ``self`` and ``other`` EXAMPLES:: @@ -482,7 +475,6 @@ def _add_(self, other): sage: phi._add_(Hom(M,N).zero()) == phi True - """ # No need for consistency checks since self and other are guaranteed # to have the same parents @@ -563,7 +555,6 @@ def _sub_(self, other): True sage: phi._sub_(phi).is_zero() True - """ # No need for consistency checks since self and other are guaranteed # to have the same parents @@ -591,12 +582,10 @@ def _lmul_(self, scalar): INPUT: - ``scalar`` -- element of the ring over which the parent of ``self`` - is a module. - - OUTPUT: + is a module - - the homomorphism resulting from the multiplication of ``self`` by - ``scalar`` + OUTPUT: the homomorphism resulting from the multiplication of ``self`` + by ``scalar`` EXAMPLES:: @@ -628,9 +617,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of ``self`` + OUTPUT: an exact copy of ``self`` EXAMPLES:: @@ -649,7 +636,6 @@ def __pos__(self): True sage: s is phi False - """ resu = self.__class__(self.parent(), 0, is_identity=self._is_identity) # 0 = provisory value @@ -665,9 +651,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the homomorphism `-f`, where `f` is ``self`` + OUTPUT: the homomorphism `-f`, where `f` is ``self`` EXAMPLES:: @@ -687,7 +671,6 @@ def __neg__(self): [-5 -1 -2] sage: s.matrix() == -phi.matrix() True - """ resu = self.__class__(self.parent(), 0) # 0 = provisory value for bases, mat in self._matrices.items(): @@ -712,9 +695,7 @@ def _call_( - ``element`` -- element of the domain of ``self`` - OUTPUT: - - - the image of ``element`` by ``self`` + OUTPUT: the image of ``element`` by ``self`` EXAMPLES: @@ -761,7 +742,6 @@ def _call_( sage: phi(M.zero()) == N.zero() True - """ if self._is_identity: return element @@ -847,7 +827,6 @@ def is_injective(self): True sage: End(N).one().is_injective() True - """ # Some matrix representation is picked at random: matrix_rep = next(iter(self._matrices.values())) @@ -882,7 +861,6 @@ def is_surjective(self): True sage: End(N).one().is_surjective() True - """ if self._is_identity: return True @@ -931,7 +909,6 @@ def is_identity(self): sage: phi.matrix(ep) [1 0] [0 1] - """ if self._is_identity: return True @@ -1089,7 +1066,6 @@ def matrix(self, basis1=None, basis2=None): [ 1 -3 1] [-18 39 -18] [-25 54 -25] - """ from sage.matrix.constructor import matrix fmodule1, fmodule2, basis1, basis2 = self._modules_and_bases(basis1, basis2) @@ -1198,7 +1174,6 @@ def _common_bases(self, other): sage: psi._common_bases(phi) # matrix of phi w.r.t. (ep,f) computed (Basis (ep_0,ep_1,ep_2) on the Rank-3 free module M over the Integer Ring, Basis (f_0,f_1) on the Rank-2 free module N over the Integer Ring) - """ resu = None for bases in self._matrices: @@ -1306,7 +1281,7 @@ class FiniteRankFreeModuleEndomorphism(FiniteRankFreeModuleMorphism): INPUT: - - ``parent`` -- hom-set Hom(M,M) to which the endomorphism belongs + - ``parent`` -- Hom-set Hom(M,M) to which the endomorphism belongs - ``matrix_rep`` -- matrix representation of the endomorphism with respect to the basis ``bases``; this entry can actually be any material from which a matrix of size rank(N)*rank(M) of @@ -1318,9 +1293,9 @@ class FiniteRankFreeModuleEndomorphism(FiniteRankFreeModuleMorphism): the default basis of `M` is used for both. - ``name`` -- (default: ``None``) string; name given to the endomorphism - ``latex_name`` -- (default: ``None``) string; LaTeX symbol to denote the - endomorphism; if ``None``, ``name`` will be used. - - ``is_identity`` -- (default: ``False``) determines whether the - constructed object is the identity endomorphism; if set to ``True``, + endomorphism. If ``None``, ``name`` will be used. + - ``is_identity`` -- boolean (default: ``False``); determines whether the + constructed object is the identity endomorphism. If set to ``True``, then the entry ``matrix_rep`` is not used. EXAMPLES: @@ -1602,6 +1577,5 @@ def trace(self): sage: id = M.identity_map() sage: id.trace() 3 - """ return self._some_matrix().trace diff --git a/src/sage/tensor/modules/free_module_tensor.py b/src/sage/tensor/modules/free_module_tensor.py index 5dbc661fa53..d293d0516c0 100644 --- a/src/sage/tensor/modules/free_module_tensor.py +++ b/src/sage/tensor/modules/free_module_tensor.py @@ -145,7 +145,7 @@ class being: sage: type(t.comp(e)) -Only non-zero components are actually stored, in the dictionary :attr:`_comp` +Only nonzero components are actually stored, in the dictionary :attr:`_comp` of class :class:`~sage.tensor.modules.comp.Components`, whose keys are the indices:: @@ -263,7 +263,6 @@ class FreeModuleTensor(ModuleElementWithMutability): Rank-3 free module M over the Integer Ring sage: t.parent() is M.tensor_module(1,1) True - """ _fmodule: FiniteRankFreeModule @@ -285,7 +284,7 @@ def __init__( sage: e = M.basis('e') sage: t = FreeModuleTensor(M, (2,1), name='t', latex_name=r'\tau', sym=(0,1)) sage: t[e,0,0,0] = -3 - sage: TestSuite(t).run(skip="_test_category") # see below + sage: TestSuite(t).run(skip='_test_category') # see below In the above test suite, _test_category fails because t is not an instance of t.parent().category().element_class. Actually tensors @@ -297,7 +296,6 @@ def __init__( ....: sym=(0,1)) sage: t1[e,0,0,0] = -3 sage: TestSuite(t1).run() - """ if parent is None: parent = fmodule.tensor_module(*tensor_type) @@ -342,7 +340,7 @@ def __bool__(self): False sage: t == 0 True - sage: t[e,1,0,2] = 4 # setting a non-zero component in basis e + sage: t[e,1,0,2] = 4 # setting a nonzero component in basis e sage: t.display() 4 e_1⊗e_0⊗e^2 sage: bool(t) @@ -376,7 +374,6 @@ def _repr_(self): sage: t = M.tensor((2,1), name='t') sage: t Type-(2,1) tensor t on the Rank-3 free module M over the Integer Ring - """ # Special cases if self._tensor_type == (0,2) and self._sym == ((0,1),): @@ -410,7 +407,6 @@ def _latex_(self): sage: t = M.tensor((2,1)) # unnamed tensor sage: t._latex_() '\\mbox{Type-(2,1) tensor on the Rank-3 free module M over the Integer Ring}' - """ if self._latex_name is None: return r'\mbox{' + str(self) + r'}' @@ -418,27 +414,25 @@ def _latex_(self): def _init_derived(self): r""" - Initialize the derived quantities + Initialize the derived quantities. EXAMPLES:: sage: M = FiniteRankFreeModule(ZZ, 3, name='M') sage: t = M.tensor((2,1), name='t') sage: t._init_derived() - """ pass # no derived quantities def _del_derived(self): r""" - Delete the derived quantities + Delete the derived quantities. EXAMPLES:: sage: M = FiniteRankFreeModule(ZZ, 3, name='M') sage: t = M.tensor((2,1), name='t') sage: t._del_derived() - """ pass # no derived quantities @@ -461,7 +455,6 @@ def tensor_type(self): sage: t = M.tensor((2,1)) sage: t.tensor_type() (2, 1) - """ return self._tensor_type @@ -482,7 +475,6 @@ def tensor_rank(self): sage: t = M.tensor((2,1)) sage: t.tensor_rank() 3 - """ return self._tensor_rank @@ -505,7 +497,6 @@ def base_module(self): Rank-3 free module M over the Integer Ring sage: t.base_module() is M True - """ return self._fmodule @@ -530,7 +521,6 @@ def symmetries(self): sage: t = M.tensor((4,0), name='T', sym=(0,1), antisym=(2,3)) sage: t.symmetries() symmetry: (0, 1); antisymmetry: (2, 3) - """ if len(self._sym) == 0: s = "no symmetry; " @@ -567,7 +557,6 @@ def _preparse_display(self, basis=None, format_spec=None): (Basis (e_0,e_1) on the Rank-2 free module M over the Integer Ring, 10) sage: v._preparse_display(format_spec=10) (Basis (e_0,e_1) on the Rank-2 free module M over the Integer Ring, 10) - """ if basis is None: basis = self._fmodule._def_basis @@ -685,7 +674,6 @@ def display(self, basis=None, format_spec=None): sage: t = SR.var('t', domain='real') sage: (t*e[0]).display() t e_0 - """ from sage.misc.latex import latex from sage.typeset.unicode_characters import unicode_otimes @@ -796,9 +784,9 @@ def display_comp(self, basis=None, format_spec=None, symbol=None, - ``index_latex_labels`` -- (default: ``None``) list of strings representing the LaTeX labels of each of the individual indices; if ``None``, integers labels are used - - ``only_nonzero`` -- (default: ``True``) boolean; if ``True``, only + - ``only_nonzero`` -- boolean (default: ``True``); if ``True``, only nonzero components are displayed - - ``only_nonredundant`` -- (default: ``False``) boolean; if ``True``, + - ``only_nonredundant`` -- boolean (default: ``False``); if ``True``, only nonredundant components are displayed in case of symmetries EXAMPLES: @@ -875,7 +863,6 @@ def display_comp(self, basis=None, format_spec=None, symbol=None, T^21_2 = 3/4 T^22_1 = 7/24 T^22_2 = 23/24 - """ if basis is None: basis = self._fmodule._def_basis @@ -923,7 +910,6 @@ def set_name(self, name: Optional[str] = None, latex_name: Optional[str] = None) Type-(2,1) tensor t on the Rank-3 free module M over the Integer Ring sage: latex(t) \tau - """ if name is not None: self._name = name @@ -945,7 +931,6 @@ def _new_instance(self): Type-(2,1) tensor on the Rank-3 free module M over the Integer Ring sage: t._new_instance().parent() is t.parent() True - """ return self.__class__(self._fmodule, self._tensor_type, sym=self._sym, antisym=self._antisym) @@ -981,7 +966,6 @@ def _new_comp(self, basis): 3-indices components w.r.t. Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring, with symmetry on the index positions (0, 1) - """ fmodule = self._fmodule # the base free module if not self._sym and not self._antisym: @@ -1071,7 +1055,6 @@ class :class:`~sage.tensor.modules.comp.Components` [ 0 0 0] [ 0 2 0] [-3 0 0] - """ fmodule = self._fmodule if basis is None: @@ -1232,7 +1215,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such sage: sorted(t._components, key=repr) [Basis (e_0,e_1,e_2) on the Rank-3 free module M over the Integer Ring, Basis (f_0,f_1,f_2) on the Rank-3 free module M over the Integer Ring] - """ if basis is None: basis = self._fmodule._def_basis @@ -1311,7 +1293,6 @@ class :class:`~sage.tensor.modules.comp.Components`; if such Traceback (most recent call last): ... ValueError: the components of an immutable element cannot be changed - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1371,7 +1352,6 @@ class :class:`~sage.tensor.modules.comp.Components`; t = 4 f_0⊗f^1 sage: t.display(e) t = -3 e_0⊗e^1 + 2 e_1⊗e^2 - """ if basis is None: basis = self._fmodule._def_basis @@ -1448,7 +1428,6 @@ class :class:`~sage.tensor.modules.comp.Components`; Traceback (most recent call last): ... ValueError: the components of an immutable element cannot be changed - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1490,7 +1469,6 @@ def del_other_comp(self, basis=None): sage: u.del_other_comp() # default argument: basis = e sage: list(u._components) [Basis (e_1,e_2,e_3) on the Rank-3 free module M over the Integer Ring] - """ if basis is None: basis = self._fmodule._def_basis @@ -1539,7 +1517,6 @@ def __getitem__(self, args) -> Components: True sage: v.__getitem__((e, slice(None))) [3, -5, 2] - """ if isinstance(args, str): # tensor with specified indices return TensorWithIndices(self, args).update() @@ -1593,7 +1570,6 @@ def __setitem__(self, args, value): [ 1 -2 3] [-4 5 -6] [ 7 -8 9] - """ if isinstance(args, list): # case of [[...]] syntax if isinstance(args[0], (int, Integer, slice, tuple)): @@ -1650,7 +1626,6 @@ def copy_from(self, other): [ 0 0 2] sage: s == t False - """ if self.is_immutable(): raise ValueError("the components of an immutable element " @@ -1765,7 +1740,6 @@ def common_basis(self, other): sage: sorted(v._components, key=repr) [Basis (e_1,e_2,e_3) on the Rank-3 free module M over the Integer Ring, Basis (f_1,f_2,f_3) on the Rank-3 free module M over the Integer Ring] - """ # Compatibility checks: if not isinstance(other, FreeModuleTensor): @@ -1859,7 +1833,6 @@ def pick_a_basis(self): sage: t.set_comp(f)[2,1] = -4 # the components in basis e not erased sage: t.pick_a_basis() Basis (f_0,f_1,f_2) on the Rank-3 free module M over the Integer Ring - """ if self._fmodule._def_basis in self._components: return self._fmodule._def_basis # the default basis is privileged @@ -1875,9 +1848,7 @@ def __eq__(self, other): - ``other`` -- a tensor or 0 - OUTPUT: - - - ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise + OUTPUT: ``True`` if ``self`` is equal to ``other`` and ``False`` otherwise EXAMPLES:: @@ -1905,7 +1876,6 @@ def __eq__(self, other): sage: a[0,1] = 7 sage: t.__eq__(a) True - """ if self is other: return True @@ -1960,7 +1930,6 @@ def __ne__(self, other): sage: t[0,1] = 7 sage: t.__ne__(a) False - """ return not self == other @@ -1968,9 +1937,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of ``self`` + OUTPUT: an exact copy of ``self`` EXAMPLES:: @@ -1986,7 +1953,6 @@ def __pos__(self): True sage: p is t False - """ result = self._new_instance() for basis in self._components: @@ -2001,9 +1967,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - the tensor `-T`, where `T` is ``self`` + OUTPUT: the tensor `-T`, where `T` is ``self`` EXAMPLES:: @@ -2019,7 +1983,6 @@ def __neg__(self): -t = -7 e_0⊗e_1 + 4 e_1⊗e_2 sage: a == -t True - """ result = self._new_instance() for basis in self._components: @@ -2040,9 +2003,7 @@ def _add_(self, other): - ``other`` -- a tensor, of the same type as ``self`` - OUTPUT: - - - the tensor resulting from the addition of ``self`` and ``other`` + OUTPUT: the tensor resulting from the addition of ``self`` and ``other`` EXAMPLES:: @@ -2061,7 +2022,6 @@ def _add_(self, other): True sage: a._add_(a) == 2*a True - """ # No need for consistency check since self and other are guaranteed # to belong to the same tensor module @@ -2091,9 +2051,7 @@ def _sub_(self, other): - ``other`` -- a tensor, of the same type as ``self`` - OUTPUT: - - - the tensor resulting from the subtraction of ``other`` from ``self`` + OUTPUT: the tensor resulting from the subtraction of ``other`` from ``self`` EXAMPLES:: @@ -2123,7 +2081,6 @@ def _sub_(self, other): sage: t = M.tensor((2,1), name='t') sage: t == t True - """ # No need for consistency check since self and other are guaranteed # to belong to the same tensor module @@ -2170,7 +2127,6 @@ def _rmul_(self, other): True sage: a._rmul_(-1) == -a True - """ #!# The following test is probably not necessary: if isinstance(other, FreeModuleTensor): @@ -2211,7 +2167,6 @@ def __mul__(self, other): sage: s[:] [[[[0, 12], [-12, 0]], [[0, 0], [0, 0]]], [[[0, -6], [6, 0]], [[0, 15], [-15, 0]]]] - """ from sage.typeset.unicode_characters import unicode_otimes from .format_utilities import format_mul_txt, format_mul_latex @@ -2259,7 +2214,6 @@ def __truediv__(self, other): True sage: s == a/4 True - """ result = self._new_instance() for basis in self._components: @@ -2319,7 +2273,6 @@ def __call__(self, *args) -> Expression: 0 sage: v.__call__(b) -7 - """ # Consistency checks: p = len(args) @@ -2579,7 +2532,6 @@ def trace( True sage: t['^k_..k'] == t.trace(0,3) True - """ if using is not None: if self.tensor_type() != (0, 2): @@ -2799,7 +2751,6 @@ def contract(self, *args): [-204 170 85] sage: s == a['^.k_l']*b['^l_k.'] # the same thing in index notation True - """ # # Treatment of the input @@ -3068,7 +3019,6 @@ def symmetrize(self, *pos, **kwargs): sage: t['^{i}_{(jk)}'] == t.symmetrize(1,2) True - """ if not pos: pos = range(self._tensor_rank) @@ -3308,7 +3258,6 @@ def antisymmetrize(self, *pos, **kwargs): sage: t['i_[jk]'] == t.antisymmetrize(1,2) True - """ if not pos: pos = range(self._tensor_rank) diff --git a/src/sage/tensor/modules/tensor_free_module.py b/src/sage/tensor/modules/tensor_free_module.py index e12b0f0b756..7e44a076694 100644 --- a/src/sage/tensor/modules/tensor_free_module.py +++ b/src/sage/tensor/modules/tensor_free_module.py @@ -159,7 +159,7 @@ class TensorFreeModule(ReflexiveModule_tensor, FiniteRankFreeModule_abstract): sage: T(0) is T.zero() True - while non-zero elements are constructed by providing their components in + while nonzero elements are constructed by providing their components in a given basis:: sage: e @@ -333,7 +333,6 @@ class TensorFreeModule(ReflexiveModule_tensor, FiniteRankFreeModule_abstract): sage: GL.has_coerce_map_from(T11) False - """ Element = FreeModuleTensor @@ -345,7 +344,6 @@ def __init__(self, fmodule, tensor_type, name=None, latex_name=None, category=No sage: M = FiniteRankFreeModule(ZZ, 3, name='M') sage: T = M.tensor_module(2, 3) sage: TestSuite(T).run() - """ self._fmodule = fmodule self._tensor_type = tuple(tensor_type) @@ -393,7 +391,6 @@ def _element_constructor_(self, comp=[], basis=None, name=None, space M over the Rational Field sage: t.parent() is T True - """ from sage.rings.integer import Integer if isinstance(comp, (int, Integer)) and comp == 0: @@ -501,7 +498,6 @@ def zero(self): sage: T11.zero() is T11(0) True - """ resu = self._element_constructor_(name='zero', latex_name='0') for basis in self._fmodule._known_bases: @@ -600,7 +596,6 @@ def _coerce_map_from_(self, other): sage: Sym01M = M.tensor_module(2, 0, sym=((0, 1))) sage: M.tensor_module(2,0)._coerce_map_from_(Sym01M) True - """ from .free_module_homset import FreeModuleHomset from .ext_pow_free_module import (ExtPowerFreeModule, @@ -645,7 +640,6 @@ def _repr_(self): sage: M.tensor_module(1,1) Free module of type-(1,1) tensors on the 2-dimensional vector space M over the Rational Field - """ description = "Free module of type-({},{}) tensors on the {}".format( self._tensor_type[0], self._tensor_type[1], self._fmodule) @@ -670,7 +664,6 @@ def base_module(self): Rank-3 free module M over the Integer Ring sage: T.base_module() is M True - """ return self._fmodule @@ -689,7 +682,6 @@ def tensor_type(self): sage: T = M.tensor_module(1,2) sage: T.tensor_type() (1, 2) - """ return self._tensor_type @@ -759,7 +751,6 @@ def basis(self, symbol, latex_symbol=None, from_family=None, f_0⊗f_0 f_0⊗f_1 + f_1⊗f_0 f_1⊗f_1 - """ return TensorFreeSubmoduleBasis_sym(self, symbol=symbol, latex_symbol=latex_symbol, indices=indices, latex_indices=latex_indices, @@ -781,7 +772,6 @@ def _basis_sym(self): sage: T = M.tensor_module(1,1) sage: c = T._basis_sym(); c 2-indices components w.r.t. (0, 1, 2) - """ frame = tuple(self.base_module().irange()) tensor = self.ambient()() diff --git a/src/sage/tensor/modules/tensor_free_submodule.py b/src/sage/tensor/modules/tensor_free_submodule.py index 97d0446bc55..576d411fd8c 100644 --- a/src/sage/tensor/modules/tensor_free_submodule.py +++ b/src/sage/tensor/modules/tensor_free_submodule.py @@ -95,7 +95,6 @@ class TensorFreeSubmodule_sym(TensorFreeModule): 'T^{2,3}(M)⊗T^{6,7}(M*)⊗Sym^{0,1}(M)⊗ASym^{4,5}(M*)' sage: latex(T) T^{\{2,3\}}(M) \otimes T^{\{6,7\}}(M^*) \otimes \mathrm{Sym}^{\{0,1\}}(M) \otimes \mathrm{ASym}^{\{4,5\}}(M^*) - """ def __init__(self, fmodule, tensor_type, name=None, latex_name=None, sym=None, antisym=None, *, category=None, ambient=None): @@ -211,7 +210,6 @@ def _basis_sym(self): Free module of fully symmetric type-(2,0) tensors on the Rank-3 free module M over the Integer Ring sage: c = Sym2M._basis_sym(); c Fully symmetric 2-indices components w.r.t. (0, 1, 2) - """ frame = tuple(self.base_module().irange()) # Need to call _element_constructor_ explicitly, or the passed arguments are dropped @@ -228,7 +226,6 @@ def _repr_(self): sage: Sym2M = M.tensor_module(2, 0, sym=range(2)); Sym2M Free module of fully symmetric type-(2,0) tensors on the Rank-3 free module M over the Integer Ring - """ prefix, suffix = self._basis_sym()._repr_symmetry() return "Free module of {}type-({},{}) tensors on the {}{}".format( @@ -240,7 +237,7 @@ def _is_symmetry_coarsening_of(self, coarser_comp, finer_comp): INPUT: - - ``coarser_comp``, ``finer_comp``: :class:`~sage.tensor.modules.comp.Components` + - ``coarser_comp``, ``finer_comp`` -- :class:`~sage.tensor.modules.comp.Components` EXAMPLES:: @@ -386,7 +383,6 @@ def is_submodule(self, other): False sage: all(S.is_submodule(T60M) for S in (Sym0123x45M, Sym012x345M, Sym012345M)) True - """ if super().is_submodule(other): return True diff --git a/src/sage/tensor/modules/tensor_free_submodule_basis.py b/src/sage/tensor/modules/tensor_free_submodule_basis.py index 6c88b05af23..8cf2602e4ab 100644 --- a/src/sage/tensor/modules/tensor_free_submodule_basis.py +++ b/src/sage/tensor/modules/tensor_free_submodule_basis.py @@ -37,7 +37,6 @@ class TensorFreeSubmoduleBasis_sym(Basis_abstract): e_2⊗e^0 e_2⊗e^1 e_2⊗e^2 - """ def __init__(self, tensor_module, symbol, latex_symbol=None, indices=None, @@ -132,7 +131,6 @@ def __getitem__(self, index): e_1⊗e_1 sage: eSym2M[1, 2].display() e_1⊗e_2 + e_2⊗e_1 - """ tensor_module = self._fmodule base_module_basis = self._base_module_basis diff --git a/src/sage/tensor/modules/tensor_with_indices.py b/src/sage/tensor/modules/tensor_with_indices.py index 97e46cb9bd1..f6e5104ea14 100644 --- a/src/sage/tensor/modules/tensor_with_indices.py +++ b/src/sage/tensor/modules/tensor_with_indices.py @@ -224,7 +224,7 @@ class TensorWithIndices(SageObject): a^μξ Conventions are checked and non acceptable indices raise - :class:`ValueError`, for instance:: + :exc:`ValueError`, for instance:: sage: a['([..])'] # nested symmetries Traceback (most recent call last): @@ -246,7 +246,6 @@ class TensorWithIndices(SageObject): Traceback (most recent call last): ... ValueError: index conventions not satisfied - """ @staticmethod @@ -257,19 +256,19 @@ def _parse_indices(indices, tensor_type=None, allow_contraction=True, indices. Parse ``indices`` checking usual conventions on repeating indices, - wildcard, balanced parentheses/brackets and raises a :class:`ValueError` + wildcard, balanced parentheses/brackets and raises a :exc:`ValueError` if not. Return a couple contravariant/covariant indices. INPUT: - - ``indices`` -- a string of index notation - - ``tensor_type`` -- (default : ``None``) a valid tensor type - (a couple of non-negative integers). If not ``None``, the indices + - ``indices`` -- string of index notation + - ``tensor_type`` -- (default: ``None``) a valid tensor type + (a couple of nonnegative integers). If not ``None``, the indices are checked to have the correct type. - - ``allow_contraction`` -- (default : ``True``) Determines if - repeated indices are allowed in the index notation. - - ``allow_symmetries`` -- (default : ``True``) Determines if - symmetries ()/[] are allowed in the index notation. + - ``allow_contraction`` -- (default: ``True``) determines if + repeated indices are allowed in the index notation + - ``allow_symmetries`` -- (default: ``True``) determines if + symmetries ()/[] are allowed in the index notation OUTPUT: @@ -329,7 +328,6 @@ def _parse_indices(indices, tensor_type=None, allow_contraction=True, Traceback (most recent call last): ... IndexError: no symmetry allowed - """ # Suppress all '{' and '}' coming from LaTeX notations: indices = indices.replace('{','').replace('}','') @@ -395,7 +393,7 @@ def __init__(self, tensor, indices): We need to skip the pickling test because we can't check equality unless the tensor was defined w.r.t. a basis:: - sage: TestSuite(ti).run(skip="_test_pickling") + sage: TestSuite(ti).run(skip='_test_pickling') :: @@ -405,7 +403,6 @@ def __init__(self, tensor, indices): ....: [[19,-20,-21], [-22,23,24], [25,26,-27]]] sage: ti = TensorWithIndices(t, 'ab_c') sage: TestSuite(ti).run() - """ self._tensor = tensor # may be changed below self._changed = False # indicates whether self contains an altered @@ -504,7 +501,6 @@ def _repr_(self): sage: ti = TensorWithIndices(t, '_{ij}') sage: ti._repr_() 't_ij' - """ name = 'X' if hasattr(self._tensor, '_name'): @@ -542,7 +538,6 @@ def update(self): scalar sage: a_ind.update() 15 - """ if self._changed: return self._tensor @@ -568,7 +563,6 @@ def __eq__(self, other): Traceback (most recent call last): ... ValueError: no common basis for the comparison - """ if not isinstance(other, TensorWithIndices): return False @@ -590,7 +584,6 @@ def __ne__(self, other): False sage: ti != TensorWithIndices(t, 'ac_b') True - """ return not self == other @@ -673,7 +666,6 @@ def __rmul__(self, other): X^ij_k sage: s._tensor == 3*a True - """ return TensorWithIndices(other*self._tensor, self._con + '_' + self._cov) @@ -685,7 +677,7 @@ def __add__(self, other): The underlying tensor of the output is the sum of the underlying tensor of ``self`` with the underlying tensor of ``other`` whose entries have be permuted to respect Einstein summation usual conventions. The - indices names of the output are those of self. + indices names of the output are those of ``self``. TESTS:: @@ -701,7 +693,6 @@ def __add__(self, other): sage: 1/4*(T["ijkl_abcd"] + T["jikl_abcd"] + T["ijkl_abdc"]\ + T["jikl_abdc"]) == T["(..).._..(..)"]["ijkl_abcd"] True - """ # Check tensor types are compatible if self._tensor.tensor_type() != other._tensor.tensor_type(): @@ -744,7 +735,7 @@ def __sub__(self, other): The underlying tensor of the output is the underlying tensor of ``self`` minus the underlying tensor of ``other`` whose entries have be permuted to respect Einstein summation usual conventions. The - indices names of the output are those of self. + indices names of the output are those of ``self``. EXAMPLES:: @@ -780,7 +771,6 @@ def __sub__(self, other): sage: 1/4*(T["ijkl_abcd"]-T["jikl_abcd"] - T["ijkl_abdc"]\ + T["jikl_abdc"] ) == T["[..].._..[..]"]["ijkl_abcd"] True - """ return self + (-other) @@ -823,7 +813,6 @@ def __getitem__(self, args): [1 3 5] [3 5 7] [5 7 9] - """ if isinstance(args, str): result = +self @@ -858,7 +847,6 @@ def __setitem__(self, args, value): sage: b["ij"] = a["ji"] sage: b[:] == a[:].transpose() True - """ if isinstance(args, str): if not isinstance(value,TensorWithIndices): @@ -1012,9 +1000,7 @@ def __pos__(self): r""" Unary plus operator. - OUTPUT: - - - an exact copy of ``self`` + OUTPUT: an exact copy of ``self`` EXAMPLES:: @@ -1028,7 +1014,6 @@ def __pos__(self): +a^ij_k sage: s._tensor == a True - """ return TensorWithIndices(+self._tensor, self._con + '_' + self._cov) @@ -1037,9 +1022,7 @@ def __neg__(self): r""" Unary minus operator. - OUTPUT: - - - negative of ``self`` + OUTPUT: negative of ``self`` EXAMPLES:: @@ -1053,7 +1036,6 @@ def __neg__(self): -a^ij_k sage: s._tensor == -a True - """ return TensorWithIndices(-self._tensor, self._con + '_' + self._cov) diff --git a/src/sage/tests/arxiv_0812_2725.py b/src/sage/tests/arxiv_0812_2725.py index cfeb7321e71..9bacb5c18aa 100644 --- a/src/sage/tests/arxiv_0812_2725.py +++ b/src/sage/tests/arxiv_0812_2725.py @@ -44,7 +44,7 @@ def CompleteMatchings(n): INPUT: - n -- nonnegative integer + - ``n`` -- nonnegative integer OUTPUT: @@ -85,8 +85,8 @@ def matchingsset(L): INPUT: - L -- a sequence. Lists, tuples, et cetera; anything that - supports len() and slicing should work. + - ``L`` -- a sequence. Lists, tuples, et cetera; anything that + supports ``len()`` and slicing should work. OUTPUT: @@ -121,10 +121,10 @@ def dcrossing(m_): INPUT: - m -- a matching or set partition, as a list of 2-element tuples - representing the edges. You'll need to call setp_to_edges() on - the objects returned by SetPartitions() to put them into the - proper format. + - ``m`` -- a matching or set partition, as a list of 2-element tuples + representing the edges. You'll need to call ``setp_to_edges()`` on + the objects returned by ``SetPartitions()`` to put them into the + proper format. OUTPUT: @@ -188,7 +188,7 @@ def setp_to_edges(p): INPUT: - p -- a Sage set partition. + - ``p`` -- a Sage set partition OUTPUT: @@ -213,7 +213,7 @@ def dcrossvec_setp(n): INPUT: - n -- a nonnegative integer. + - ``n`` -- nonnegative integer OUTPUT: @@ -255,7 +255,7 @@ def dcrossvec_cm(n): INPUT: - n -- a nonnegative integer. + - ``n`` -- nonnegative integer OUTPUT: @@ -310,10 +310,10 @@ def tablecolumn(n, k): INPUT: - n -- positive integer. + - ``n`` -- positive integer - k -- integer for which table you want: Table 1 is complete - matchings, Table 2 is set partitions. + - ``k`` -- integer for which table you want: Table 1 is complete + matchings, Table 2 is set partitions OUTPUT: diff --git a/src/sage/tests/benchmark.py b/src/sage/tests/benchmark.py index 8fcc8772b40..8a481a2b959 100644 --- a/src/sage/tests/benchmark.py +++ b/src/sage/tests/benchmark.py @@ -81,7 +81,6 @@ class Benchmark: sage.tests.benchmark.Benchmark instance System min avg max trials cpu or wall * python ... - """ def run(self, systems=None, timeout=60, trials=1, sort=False, optional=False): """ @@ -90,15 +89,14 @@ def run(self, systems=None, timeout=60, trials=1, sort=False, optional=False): INPUT: - - systems -- optional list of strings of which systems to run tests on; + - ``systems`` -- (optional) list of strings of which systems to run tests on; if ``None``, runs the standard systems - - timeout -- optional integer (default 60); how long (in seconds) + - ``timeout`` -- integer (default: 60); how long (in seconds) to run each test for - - trials -- optional integer (default 1); number of trials - - sort -- optional boolean (default ``False``); whether to sort - system names - - optional -- optional boolean (default ``False``); - if systems is ``None``, whether to test optional systems + - ``trials`` -- integer (default: 1); number of trials + - ``sort`` -- boolean (default: ``False``); whether to sort system names + - ``optional`` -- boolean (default: ``False``); if systems is ``None``, + whether to test optional systems EXAMPLES:: @@ -108,7 +106,6 @@ def run(self, systems=None, timeout=60, trials=1, sort=False, optional=False): System min avg max trials cpu or wall * sage ... * gp ... - """ if sort: systems.sort() @@ -219,7 +216,6 @@ def magma(self): sage: B = Divpoly(3) sage: isinstance(B.magma(), float) # optional - magma True - """ n = self.__n t = magma.cputime() @@ -278,7 +274,6 @@ def maple(self): sage: B = PolySquare(3, QQ) sage: isinstance(B.maple()[1], float) # optional - maple True - """ R = self.__R if not (R == ZZ or R == QQ): @@ -312,7 +307,6 @@ def sage(self): sage: B = MPolynomialPower() sage: isinstance(B.sage()[1], float) True - """ R = PolynomialRing(self.base, self.nvars, 'x') z = sum(R.gens()) @@ -335,7 +329,6 @@ def macaulay2(self): sage: B = MPolynomialPower() sage: isinstance(B.macaulay2()[1], float) # optional - macaulay2 True - """ R = PolynomialRing(self.base, self.nvars, 'x') z = macaulay2(sum(R.gens())) @@ -353,7 +346,6 @@ def maxima(self): sage: B = MPolynomialPower() sage: isinstance(B.maxima()[1], float) True - """ R = PolynomialRing(self.base, self.nvars, 'x') z = maxima(str(sum(R.gens()))) @@ -371,7 +363,6 @@ def maple(self): sage: B = MPolynomialPower() sage: isinstance(B.maple()[1], float) # optional - maple True - """ R = PolynomialRing(self.base, self.nvars, 'x') z = maple(str(sum(R.gens()))) @@ -389,7 +380,6 @@ def mathematica(self): sage: B = MPolynomialPower() sage: isinstance(B.mathematica()[1], float) # optional - mathematica True - """ R = PolynomialRing(self.base, self.nvars, 'x') z = mathematica(str(sum(R.gens()))) @@ -416,7 +406,6 @@ def magma(self): sage: B = MPolynomialPower() sage: isinstance(B.magma(), float) # optional - magma True - """ R = magma.PolynomialRing(self.base, self.nvars) z = R.gen(1) @@ -488,7 +477,6 @@ def mathematica(self): sage: B = MPolynomialMult() sage: isinstance(B.mathematica()[1], float) # optional - mathematica True - """ R = PolynomialRing(self.base, self.nvars, 'x') k = self.nvars // 2 @@ -517,7 +505,6 @@ def sage(self): sage: B = MPolynomialMult() sage: isinstance(B.sage()[1], float) True - """ R = PolynomialRing(self.base, self.nvars, 'x') k = self.nvars // 2 @@ -563,7 +550,6 @@ def magma(self): sage: B = MPolynomialMult() sage: isinstance(B.magma(), float) # optional - magma True - """ R = magma.PolynomialRing(self.base, self.nvars) z0 = R.gen(1) @@ -717,7 +703,6 @@ def sage(self): sage: B = MPolynomialMult2() sage: isinstance(B.sage()[1], float) True - """ R = PolynomialRing(self.base, self.nvars, 'x') k = self.nvars // 2 @@ -787,7 +772,6 @@ def sage(self): sage: B = CharPolyTp() sage: isinstance(B.sage(), float) True - """ m = self.matrix() t = cputime() @@ -804,7 +788,6 @@ def gp(self): sage: B = CharPolyTp() sage: isinstance(B.gp(), float) True - """ m = gp(self.matrix()) gp.eval('gettime') @@ -821,7 +804,6 @@ def pari(self): sage: B = CharPolyTp() sage: isinstance(B.pari(), float) True - """ m = pari(self.matrix()) t = cputime() @@ -838,7 +820,6 @@ def magma(self): sage: B = CharPolyTp() sage: isinstance(B.magma(), float) # optional - magma True - """ m = magma(self.matrix()) t = magma.cputime() @@ -928,7 +909,6 @@ def sage(self): sage: B = SquareInts() sage: isinstance(B.sage(), float) True - """ n = Integer(self.base)**self.__ndigits t = cputime() @@ -993,7 +973,6 @@ def python(self): sage: B = SquareInts() sage: isinstance(B.python(), float) True - """ n = self.base**self.__ndigits t = cputime() @@ -1143,7 +1122,6 @@ def sage(self): sage: B = Factorial(10) sage: isinstance(B.sage(), float) True - """ t = cputime() factorial(self.__n) @@ -1174,7 +1152,6 @@ def maple(self): sage: B = Factorial(10) sage: isinstance(B.maple()[1], float) # optional - maple True - """ n = maple(self.__n) t = walltime() @@ -1212,7 +1189,6 @@ def sage(self): sage: B = Fibonacci(10) sage: isinstance(B.sage(), float) True - """ t = cputime() fibonacci(self.__n) @@ -1464,7 +1440,6 @@ def sage(self): sage: B = ModularSymbols1(11) sage: isinstance(B.sage(), float) True - """ t = cputime() ModularSymbols(self.__N, self.__k) @@ -1601,7 +1576,6 @@ def magma(self): sage: B = EllipticCurvePointMul(11) sage: isinstance(B.magma(), float) # optional - magma True - """ E = magma.EllipticCurve('[0, 0, 1, -1, 0]') P = E('[0,0]') @@ -1659,7 +1633,6 @@ def sage(self): sage: B = EllipticCurveMW([1,2,3,4,5]) sage: isinstance(B.sage()[1], float) True - """ E = EllipticCurve(self.ainvs) t = walltime() @@ -1676,7 +1649,6 @@ def magma(self): sage: B = EllipticCurveMW([1,2,3,4,5]) sage: isinstance(B.magma(), float) # optional - magma True - """ E = magma.EllipticCurve(str(self.ainvs)) t = magma.cputime() @@ -1883,7 +1855,7 @@ def mpoly(): def mpoly_all(include_maple=False): """ - Runs benchmarks for multipoly arithmetic on all systems (except + Run benchmarks for multipoly arithmetic on all systems (except Maxima, since it is very very slow). You must have mathematica, maple, and magma. @@ -1903,7 +1875,6 @@ def mpoly_all(include_maple=False): ...System min avg max trials cpu or wall ... * sage... - """ systems = ['sage', 'magma', 'mathematica', 'macaulay2'] if include_maple: diff --git a/src/sage/tests/books/computational-mathematics-with-sagemath/float_doctest.py b/src/sage/tests/books/computational-mathematics-with-sagemath/float_doctest.py index 49fb2b34db5..7b6587ecaf6 100644 --- a/src/sage/tests/books/computational-mathematics-with-sagemath/float_doctest.py +++ b/src/sage/tests/books/computational-mathematics-with-sagemath/float_doctest.py @@ -262,7 +262,7 @@ sage: r3 = RIF(sqrt(3)); r3 1.732050807568877? - sage: print(r3.str(style="brackets")) + sage: print(r3.str(style='brackets')) [1.7320508075688769 .. 1.7320508075688775] Sage example in ./float.tex, line 1602:: diff --git a/src/sage/tests/books/computational-mathematics-with-sagemath/graphtheory_doctest.py b/src/sage/tests/books/computational-mathematics-with-sagemath/graphtheory_doctest.py index b66c6d0c88f..cd467529f20 100644 --- a/src/sage/tests/books/computational-mathematics-with-sagemath/graphtheory_doctest.py +++ b/src/sage/tests/books/computational-mathematics-with-sagemath/graphtheory_doctest.py @@ -158,7 +158,7 @@ sage: L = [graphs.CompleteGraph(i) for i in range(3,3+10)] sage: for number, G in enumerate(L): - ....: G.plot().save(tmp_filename(ext=".png")) + ....: G.plot().save(tmp_filename(ext='.png')) Sage example in ./graphtheory.tex, line 782:: diff --git a/src/sage/tests/books/computational-mathematics-with-sagemath/linsolve_doctest.py b/src/sage/tests/books/computational-mathematics-with-sagemath/linsolve_doctest.py index 7c9e0183efe..e5f90964e0c 100644 --- a/src/sage/tests/books/computational-mathematics-with-sagemath/linsolve_doctest.py +++ b/src/sage/tests/books/computational-mathematics-with-sagemath/linsolve_doctest.py @@ -398,7 +398,7 @@ sage: n = 1000 sage: m = 5 sage: # build a stochastic matrix of size n - sage: # with m non-zero coefficients per row + sage: # with m nonzero coefficients per row sage: A1 = sparse.lil_matrix((n, n)) sage: for i in range(0,n): ....: for j in range(0,m): diff --git a/src/sage/tests/books/computational-mathematics-with-sagemath/sol/domaines_doctest.py b/src/sage/tests/books/computational-mathematics-with-sagemath/sol/domaines_doctest.py index b71053c71ea..8746bdf0a1e 100644 --- a/src/sage/tests/books/computational-mathematics-with-sagemath/sol/domaines_doctest.py +++ b/src/sage/tests/books/computational-mathematics-with-sagemath/sol/domaines_doctest.py @@ -39,12 +39,12 @@ Sage example in ./sol/domaines.tex, line 80:: sage: E = CombinatorialFreeModule(QQ, [1,2,3]) - sage: H = Hom(E,E); H.rename("H") + sage: H = Hom(E,E); H.rename('H') sage: C = E.category(); C Category of finite dimensional vector spaces with basis over Rational Field sage: phi1 = E.module_morphism(on_basis=lambda i: E.term(i), codomain=E) sage: phi2 = E.module_morphism(on_basis=lambda i: E.term(i), - ....: triangular="lower", codomain=E) + ....: triangular='lower', codomain=E) sage: phi3 = E.module_morphism(diagonal=lambda i: 1, codomain=E, ....: category=C) sage: phi1.parent() == phi2.parent() == phi3.parent() == H diff --git a/src/sage/tests/cmdline.py b/src/sage/tests/cmdline.py index 5bfe85f6e4c..406bf1befab 100644 --- a/src/sage/tests/cmdline.py +++ b/src/sage/tests/cmdline.py @@ -57,21 +57,21 @@ import select -def test_executable(args, input="", timeout=100.0, pydebug_ignore_warnings=False, **kwds): +def test_executable(args, input='', timeout=100.0, pydebug_ignore_warnings=False, **kwds): r""" Run the program defined by ``args`` using the string ``input`` on the standard input. INPUT: - - ``args`` -- a list of program arguments, the first being the - executable. + - ``args`` -- list of program arguments, the first being the + executable - - ``input`` -- a string serving as standard input. Usually, this - should end with a newline. + - ``input`` -- string serving as standard input; usually, this + should end with a newline - ``timeout`` -- if the program produces no output for ``timeout`` - seconds, a :class:`RuntimeError` is raised. + seconds, a :exc:`RuntimeError` is raised - ``pydebug_ignore_warnings`` -- boolean. Set the PYTHONWARNINGS environment variable to ignore Python warnings when on a Python debug build (`--with-pydebug`, e.g. from building with @@ -80,13 +80,12 @@ def test_executable(args, input="", timeout=100.0, pydebug_ignore_warnings=False so the filter will catch a bit more than the default filters. Hence we only enable it on debug builds. - - ``**kwds`` -- Additional keyword arguments passed to the - :class:`Popen` constructor. + - ``**kwds`` -- additional keyword arguments passed to the + :class:`Popen` constructor OUTPUT: a tuple ``(out, err, ret)`` with the standard output, standard error and exitcode of the program run. - EXAMPLES:: sage: from sage.tests.cmdline import test_executable diff --git a/src/sage/tests/modular_group_cohomology.py b/src/sage/tests/modular_group_cohomology.py index 35bc8b5387f..0ef6d7f2b96 100644 --- a/src/sage/tests/modular_group_cohomology.py +++ b/src/sage/tests/modular_group_cohomology.py @@ -63,7 +63,7 @@ characteristic 2:: sage: H = CohomologyRing(libgap.AlternatingGroup(6), - ....: GroupName="A(6)", prime=2, + ....: GroupName='A(6)', prime=2, ....: from_scratch=True) sage: H.make() sage: print(H) diff --git a/src/sage/tests/stl_vector.pyx b/src/sage/tests/stl_vector.pyx index 88de4fac4cd..e7b3ec06cb6 100644 --- a/src/sage/tests/stl_vector.pyx +++ b/src/sage/tests/stl_vector.pyx @@ -38,7 +38,7 @@ from sage.cpython.string cimport char_to_str cdef class stl_int_vector(SageObject): """ - Example class wrapping an STL vector + Example class wrapping an STL vector. EXAMPLES:: diff --git a/src/sage/topology/cell_complex.py b/src/sage/topology/cell_complex.py index 48f5eb66f6f..38caf541192 100644 --- a/src/sage/topology/cell_complex.py +++ b/src/sage/topology/cell_complex.py @@ -122,9 +122,10 @@ def cells(self, subcomplex=None): optional argument ``subcomplex`` is present, then return only the cells which are *not* in the subcomplex. - :param subcomplex: a subcomplex of this cell complex. Return - the cells which are not in this subcomplex. - :type subcomplex: optional, default None + INPUT: + + - ``subcomplex`` -- subcomplex (default: ``None``); a subcomplex of + this cell complex; return the cells which are not in this subcomplex This is not implemented in general; it should be implemented in any derived class. When implementing, see the warning in @@ -174,16 +175,16 @@ def dimension(self): def n_cells(self, n, subcomplex=None): """ - List of cells of dimension ``n`` of this cell complex. + List of cells of dimension `n` of this cell complex. If the optional argument ``subcomplex`` is present, then - return the ``n``-dimensional cells which are *not* in the + return the `n`-dimensional cells which are *not* in the subcomplex. - :param n: the dimension - :type n: non-negative integer - :param subcomplex: a subcomplex of this cell complex. Return - the cells which are not in this subcomplex. - :type subcomplex: optional, default ``None`` + INPUT: + + - ``n`` -- nonnegative integer; the dimension + - ``subcomplex`` -- (optional) a subcomplex of this cell complex; + return the cells which are not in this subcomplex .. NOTE:: @@ -205,16 +206,16 @@ def n_cells(self, n, subcomplex=None): def _n_cells_sorted(self, n, subcomplex=None): """ - Sorted list of cells of dimension ``n`` of this cell complex. + Sorted list of cells of dimension `n` of this cell complex. If the optional argument ``subcomplex`` is present, then - return the ``n``-dimensional cells which are *not* in the + return the `n`-dimensional cells which are *not* in the subcomplex. - :param n: the dimension - :type n: non-negative integer - :param subcomplex: a subcomplex of this cell complex. Return - the cells which are not in this subcomplex. - :type subcomplex: optional, default ``None`` + INPUT: + + - ``n`` -- the dimension + - ``subcomplex`` -- (default: ``None``) a subcomplex of this cell + complex; return the cells which are not in this subcomplex EXAMPLES:: @@ -241,7 +242,7 @@ def _n_cells_sorted(self, n, subcomplex=None): def f_vector(self): """ - The `f`-vector of this cell complex: a list whose `n^{th}` + The `f`-vector of this cell complex: a list whose `n`-th item is the number of `(n-1)`-cells. Note that, like all lists in Sage, this is indexed starting at 0: the 0th element in this list is the number of `(-1)`-cells (which is 1: the @@ -322,7 +323,9 @@ def disjoint_union(self, right): """ The disjoint union of this cell complex with another one. - :param right: the other cell complex (the right-hand factor) + INPUT: + + - ``right`` -- the other cell complex (the right-hand factor) Disjoint unions are not implemented for general cell complexes. @@ -342,7 +345,9 @@ def wedge(self, right): The wedge (one-point union) of this cell complex with another one. - :param right: the other cell complex (the right-hand factor) + INPUT: + + - ``right`` -- the other cell complex (the right-hand factor) Wedges are not implemented for general cell complexes. @@ -365,7 +370,9 @@ def join(self, right): """ The join of this cell complex with another one. - :param right: the other cell complex (the right-hand factor) + INPUT: + + - ``right`` -- the other cell complex (the right-hand factor) Joins are not implemented for general cell complexes. They may be implemented in some derived classes (like simplicial @@ -400,8 +407,7 @@ def join(self, right): # # INPUT: # - # - ``n`` -- positive integer (default: 1): suspend this - # many times. + # - ``n`` -- positive integer (default: 1); suspend this many times. # """ # raise NotImplementedError @@ -429,14 +435,14 @@ def chain_complex(self, subcomplex=None, augmented=False, - ``check`` -- a bool: whether to check that the each composite of two consecutive differentials is zero - ``dimensions`` -- if ``None``, compute the chain complex in all - dimensions. If a list or tuple of integers, compute the - chain complex in those dimensions, setting the chain groups - in all other dimensions to zero. + dimensions. If a list or tuple of integers, compute the + chain complex in those dimensions, setting the chain groups + in all other dimensions to zero. Definitely implement the following: - - ``base_ring`` -- commutative ring (default: ZZ) - - ``cochain`` -- a bool: whether to return the cochain complex + - ``base_ring`` -- commutative ring (default: ZZ) + - ``cochain`` -- a bool: whether to return the cochain complex EXAMPLES:: @@ -454,31 +460,29 @@ def homology(self, dim=None, base_ring=ZZ, subcomplex=None, r""" The (reduced) homology of this cell complex. - :param dim: If None, then return the homology in every - dimension. If ``dim`` is an integer or list, return the - homology in the given dimensions. (Actually, if ``dim`` is - a list, return the homology in the range from ``min(dim)`` - to ``max(dim)``.) - :type dim: integer or list of integers or None; optional, - default None - :param base_ring: commutative ring, must be ZZ or a field. - :type base_ring: optional, default ZZ - :param subcomplex: a subcomplex of this simplicial complex. - Compute homology relative to this subcomplex. - :type subcomplex: optional, default empty - :param generators: If ``True``, return generators for the homology - groups along with the groups. - :type generators: boolean; optional, default: ``False`` - :param cohomology: If True, compute cohomology rather than homology. - :type cohomology: boolean; optional, default: ``False`` - :param algorithm: The options are 'auto', 'dhsw', or 'pari'. - See below for a description of what they mean. - :type algorithm: string; optional, default 'pari' - :param verbose: If True, print some messages as the homology is - computed. - :type verbose: boolean; optional, default: ``False`` - :param reduced: If ``True``, return the reduced homology. - :type reduced: boolean; optional, default ``True`` + INPUT: + + - ``dim`` -- integer or list of integers or ``None`` (default: + ``None``); if ``None``, then return the homology in every + dimension. If ``dim`` is an integer or list, return the + homology in the given dimensions. (Actually, if ``dim`` is + a list, return the homology in the range from ``min(dim)`` + to ``max(dim)``.) + - ``base_ring`` -- commutative ring (default: ``ZZ``); must be `\ZZ` or + a field + - ``subcomplex`` -- (default: empty) a subcomplex of this simplicial + complex. Compute the homology relative to this subcomplex. + - ``generators`` -- boolean (default: ``False``); if ``True``, return + generators for the homology groups along with the groups. + - ``cohomology`` -- boolean (default: ``False``); if ``True``, compute + cohomology rather than homology + - ``algorithm`` -- string (default: ``'pari'``); the algorithm options + are 'auto', 'dhsw', or 'pari'. See below for a description of what + they mean. + - ``verbose`` -- boolean (default: ``False``); if True, print some + messages as the homology is computed + - ``reduced`` -- boolean (default: ``True``); if ``True``, return the + reduced homology ALGORITHM: @@ -610,12 +614,14 @@ def cohomology(self, dim=None, base_ring=ZZ, subcomplex=None, automatically true here. Indeed, this function just calls :meth:`homology` with ``cohomology`` set to ``True``. - :param dim: - :param base_ring: - :param subcomplex: - :param algorithm: - :param verbose: - :param reduced: + INPUT: + + - ``dim`` + - ``base_ring`` + - ``subcomplex`` + - ``algorithm`` + - ``verbose`` + - ``reduced`` EXAMPLES:: @@ -662,20 +668,21 @@ def betti(self, dim=None, subcomplex=None): r""" The Betti numbers of this simplicial complex as a dictionary (or a single Betti number, if only one dimension is given): - the ith Betti number is the rank of the ith homology group. - - :param dim: If ``None``, then return every Betti number, as - a dictionary with keys the non-negative integers. If - ``dim`` is an integer or list, return the Betti number for - each given dimension. (Actually, if ``dim`` is a list, - return the Betti numbers, as a dictionary, in the range - from ``min(dim)`` to ``max(dim)``. If ``dim`` is a number, - return the Betti number in that dimension.) - :type dim: integer or list of integers or ``None``; optional, - default ``None`` - :param subcomplex: a subcomplex of this cell complex. Compute - the Betti numbers of the homology relative to this subcomplex. - :type subcomplex: optional, default ``None`` + the `i`-th Betti number is the rank of the `i`-th homology group. + + INPUT: + + - ``dim`` -- integer or list of integers or ``None`` (default: + ``None``); if ``None``, then return every Betti number, as + a dictionary with keys the non-negative integers. If + ``dim`` is an integer or list, return the Betti number for + each given dimension. (Actually, if ``dim`` is a list, + return the Betti numbers, as a dictionary, in the range + from ``min(dim)`` to ``max(dim)``. If ``dim`` is a number, + return the Betti number in that dimension.) + - ``subcomplex`` -- a subcomplex (default: ``None``) of this cell + complex; compute the Betti numbers of the homology relative to this + subcomplex EXAMPLES: @@ -715,13 +722,13 @@ def betti(self, dim=None, subcomplex=None): def is_acyclic(self, base_ring=ZZ): """ - True if the reduced homology with coefficients in ``base_ring`` of - this cell complex is zero. + Return ``True`` if the reduced homology with coefficients in + ``base_ring`` of this cell complex is zero. INPUT: - - ``base_ring`` -- optional, default ``ZZ``. Compute homology - with coefficients in this ring. + - ``base_ring`` -- (default: ``ZZ``) compute homology + with coefficients in this ring EXAMPLES:: @@ -1005,7 +1012,7 @@ def alexander_whitney(self, cell, dim_left): - ``dim_left`` -- the dimension of the left-hand factors in the decomposition - OUTPUT: a list containing triples ``(c, left, right)``. + OUTPUT: list containing triples ``(c, left, right)``. ``left`` and ``right`` should be cells in this complex, and ``c`` an integer. In the cellular approximation of the diagonal map, the chain represented by ``cell`` should get @@ -1098,7 +1105,7 @@ def graph(self): def is_connected(self): """ - True if this cell complex is connected. + Return ``True`` if this cell complex is connected. EXAMPLES:: @@ -1133,7 +1140,9 @@ def n_skeleton(self, n): complex obtained by discarding all of the simplices in dimensions larger than `n`. - :param n: non-negative integer + INPUT: + + - ``n`` -- nonnegative integer This is not implemented for general cell complexes. @@ -1153,7 +1162,7 @@ def _string_constants(self): singular and plural of the name of the cells from which it is built. This is used in constructing the string representation. - :return: tuple of strings + OUTPUT: tuple of strings This returns ``('Cell', 'cell', 'cells')``, as in "Cell complex", "1 cell", and "24 cells", but in other classes it @@ -1178,7 +1187,7 @@ def _repr_(self): """ Print representation. - :return: string + OUTPUT: string EXAMPLES:: diff --git a/src/sage/topology/cubical_complex.py b/src/sage/topology/cubical_complex.py index 8a6bde9abf1..055a597776e 100644 --- a/src/sage/topology/cubical_complex.py +++ b/src/sage/topology/cubical_complex.py @@ -59,7 +59,7 @@ ``S1`` (in fact, they're "cubically equivalent"), and this is reflected in the fact that they have isomorphic homology groups. -.. note:: +.. NOTE:: This class derives from :class:`~sage.homology.cell_complex.GenericCellComplex`, and so @@ -99,14 +99,17 @@ class Cube(SageObject): is a 3-dimensional cube (since one of the intervals is degenerate) embedded in `\RR^4`. - :param data: list or tuple of terms of the form ``(i,i+1)`` or - ``(i,i)`` or ``(i,)`` -- the last two are degenerate intervals. - :return: an elementary cube + INPUT: + + - ``data`` -- list or tuple of terms of the form ``(i,i+1)`` or + ``(i,i)`` or ``(i,)``; the last two are degenerate intervals + + OUTPUT: an elementary cube Each cube is stored in a standard form: a tuple of tuples, with a nondegenerate interval ``[j,j]`` represented by ``(j,j)``, not ``(j,)``. (This is so that for any interval ``I``, ``I[1]`` will - produce a value, not an :class:`IndexError`.) + produce a value, not an :exc:`IndexError`.) EXAMPLES:: @@ -178,7 +181,7 @@ def tuple(self): def is_face(self, other): """ - Return True iff this cube is a face of other. + Return ``True`` iff this cube is a face of other. EXAMPLES:: @@ -209,9 +212,11 @@ def _translate(self, vec): """ Translate ``self`` by ``vec``. - :param vec: anything which can be converted to a tuple of integers - :return: the translation of ``self`` by ``vec`` - :rtype: Cube + INPUT: + + - ``vec`` -- anything which can be converted to a tuple of integers + + OUTPUT: cube; the translation of ``self`` by ``vec`` If ``vec`` is shorter than the list of intervals forming the cube, pad with zeroes, and similarly if the cube's defining @@ -237,10 +242,13 @@ def _translate(self, vec): def __getitem__(self, n): """ - Return the nth interval in this cube. + Return the `n`-th interval in this cube. - :param n: an integer - :return: tuple representing the `n`-th interval in the cube. + INPUT: + + - ``n`` -- integer + + OUTPUT: tuple representing the `n`-th interval in the cube EXAMPLES:: @@ -271,8 +279,11 @@ def __add__(self, other): Cube obtained by concatenating the underlying tuples of the two arguments. - :param other: another cube - :return: the product of ``self`` and ``other``, as a Cube + INPUT: + + - ``other`` -- another cube + + OUTPUT: the product of ``self`` and ``other``, as a Cube EXAMPLES:: @@ -333,15 +344,18 @@ def dimension(self): def face(self, n, upper=True): """ - The nth primary face of this cube. + The `n`-th primary face of this cube. + + INPUT: - :param n: an integer between 0 and one less than the dimension + - ``n`` -- integer between 0 and one less than the dimension of this cube - :param upper: if True, return the "upper" nth primary face; - otherwise, return the "lower" nth primary face. - :type upper: boolean; optional, default=True - :return: the cube obtained by replacing the nth non-degenerate - interval with either its upper or lower endpoint. + - ``upper`` -- boolean (default=True);if ``True``, return the "upper" + `n`-th primary face; otherwise, return the "lower" `n`-th primary + face + + OUTPUT: the cube obtained by replacing the `n`-th non-degenerate + interval with either its upper or lower endpoint. EXAMPLES:: @@ -359,10 +373,10 @@ def face(self, n, upper=True): sage: C.face(3) Traceback (most recent call last): ... - ValueError: can only compute the nth face if 0 <= n < dim + ValueError: can only compute the n-th face if 0 <= n < dim """ if n < 0 or n >= self.dimension(): - raise ValueError("can only compute the nth face if 0 <= n < dim") + raise ValueError("can only compute the n-th face if 0 <= n < dim") idx = self.nondegenerate_intervals()[n] t = self.__tuple if upper: @@ -407,12 +421,15 @@ def _compare_for_gluing(self, other): Given two cubes ``self`` and ``other``, describe how to transform them so that they become equal. - :param other: a cube of the same dimension as ``self`` - :return: a triple ``(insert_self, insert_other, translate)``. - ``insert_self`` is a tuple with entries ``(index, (list of - degenerate intervals))``. ``insert_other`` is similar. - ``translate`` is a tuple of integers, suitable as a second - argument for the ``_translate`` method. + INPUT: + + - ``other`` -- a cube of the same dimension as ``self`` + + OUTPUT: a triple ``(insert_self, insert_other, translate)``. + ``insert_self`` is a tuple with entries ``(index, (list of + degenerate intervals))``. ``insert_other`` is similar. + ``translate`` is a tuple of integers, suitable as a second + argument for the ``_translate`` method. To do this, ``self`` and ``other`` must have the same dimension; degenerate intervals from ``other`` are added to @@ -615,11 +632,13 @@ def alexander_whitney(self, dim): def __eq__(self, other): """ - Return True iff this cube is the same as ``other``: that is, + Return ``True`` iff this cube is the same as ``other``: that is, if they are the product of the same intervals in the same order. - :param other: another cube + INPUT: + + - ``other`` -- another cube EXAMPLES:: @@ -636,9 +655,11 @@ def __eq__(self, other): def __ne__(self, other): """ - Return True iff this cube is not equal to ``other``. + Return ``True`` iff this cube is not equal to ``other``. + + INPUT: - :param other: another cube + - ``other`` -- another cube EXAMPLES:: @@ -655,10 +676,12 @@ def __ne__(self, other): def __lt__(self, other): """ - Return True iff the tuple for this cube is less than that for + Return ``True`` iff the tuple for this cube is less than that for ``other``. - :param other: another cube + INPUT: + + - ``other`` -- another cube EXAMPLES:: @@ -741,10 +764,12 @@ class CubicalComplex(GenericCellComplex): r""" Define a cubical complex. - :param maximal_faces: set of maximal faces - :param maximality_check: see below - :type maximality_check: boolean; optional, default: ``True`` - :return: a cubical complex + INPUT: + + - ``maximal_faces`` -- set of maximal faces + - ``maximality_check`` -- boolean (default: ``True``); see below + + OUTPUT: a cubical complex ``maximal_faces`` should be a list or tuple or set (or anything which may be converted to a set) of "cubes": instances of the @@ -918,7 +943,7 @@ def maximal_cells(self): The set of maximal cells (with respect to inclusion) of this cubical complex. - :return: Set of maximal cells + OUTPUT: set of maximal cells This just returns the set of cubes used in defining the cubical complex, so if the complex was defined with no @@ -938,12 +963,12 @@ def maximal_cells(self): def __eq__(self, other): r""" - Return True if the set of maximal cells is the same for + Return ``True`` if the set of maximal cells is the same for ``self`` and ``other``. - :param other: another cubical complex - :return: True if the set of maximal cells is the same for ``self`` and ``other`` - :rtype: bool + INPUT: + + - ``other`` -- another cubical complex EXAMPLES:: @@ -961,11 +986,11 @@ def __eq__(self, other): def __ne__(self, other): r""" - Return True if ``self`` and ``other`` are not equal. + Return ``True`` if ``self`` and ``other`` are not equal. + + INPUT: - :param other: another cubical complex - :return: True if the complexes are not equal - :rtype: bool + - ``other`` -- another cubical complex EXAMPLES:: @@ -996,9 +1021,11 @@ def __hash__(self): def is_subcomplex(self, other): r""" - Return True if ``self`` is a subcomplex of ``other``. + Return ``True`` if ``self`` is a subcomplex of ``other``. - :param other: a cubical complex + INPUT: + + - ``other`` -- a cubical complex Each maximal cube of ``self`` must be a face of a maximal cube of ``other`` for this to be True. @@ -1048,10 +1075,13 @@ def cells(self, subcomplex=None): If the optional argument ``subcomplex`` is present, then return only the faces which are *not* in the subcomplex. - :param subcomplex: a subcomplex of this cubical complex - :type subcomplex: a cubical complex; optional, default None - :return: cells of this complex not contained in ``subcomplex`` - :rtype: dictionary + INPUT: + + - ``subcomplex`` -- a subcomplex of this cubical complex (default: + ``None``) + + OUTPUT: dictionary; the cells of this complex not contained in + ``subcomplex`` EXAMPLES:: @@ -1107,12 +1137,13 @@ def n_cubes(self, n, subcomplex=None): return the ``n``-dimensional cubes which are *not* in the subcomplex. - :param n: dimension - :type n: integer - :param subcomplex: a subcomplex of this cubical complex - :type subcomplex: a cubical complex; optional, default None - :return: cells in dimension ``n`` - :rtype: set + INPUT: + + - ``n`` -- integer; dimension + - ``subcomplex`` -- a subcomplex of this cubical complex (default: + ``None``) + + OUTPUT: set; cells in dimension ``n`` EXAMPLES:: @@ -1135,33 +1166,29 @@ def chain_complex(self, subcomplex=None, augmented=False, r""" The chain complex associated to this cubical complex. - :param dimensions: if None, compute the chain complex in all - dimensions. If a list or tuple of integers, compute the - chain complex in those dimensions, setting the chain groups - in all other dimensions to zero. NOT IMPLEMENTED YET: this - function always returns the entire chain complex - :param base_ring: commutative ring - :type base_ring: optional, default ZZ - :param subcomplex: a subcomplex of this cubical complex. - Compute the chain complex relative to this subcomplex. - :type subcomplex: optional, default empty - :param augmented: If True, return the augmented chain complex - (that is, include a class in dimension `-1` corresponding - to the empty cell). This is ignored if ``dimensions`` is - specified. - :type augmented: boolean; optional, default: ``False`` - :param cochain: If True, return the cochain complex (that is, - the dual of the chain complex). - :type cochain: boolean; optional, default: ``False`` - :param verbose: If True, print some messages as the chain - complex is computed. - :type verbose: boolean; optional, default: ``False`` - :param check: If True, make sure that the chain complex - is actually a chain complex: the differentials are - composable and their product is zero. - :type check: boolean; optional, default: ``False`` - - .. note:: + INPUT: + + - ``dimensions`` -- if ``None``, compute the chain complex in all + dimensions. If a list or tuple of integers, compute the + chain complex in those dimensions, setting the chain groups + in all other dimensions to zero. NOT IMPLEMENTED YET: this + function always returns the entire chain complex + - ``base_ring`` -- commutative ring (default: ZZ) + - ``subcomplex`` -- a subcomplex of this cubical complex (default: empty). + Compute the chain complex relative to this subcomplex. + - ``augmented`` -- boolean (default: ``False``); if ``True``, return + the augmented chain complex (that is, include a class in dimension + `-1` corresponding to the empty cell). This is ignored if + ``dimensions`` is specified. + - ``cochain`` -- boolean (default: ``False``); if ``True``, return the + cochain complex (that is, the dual of the chain complex). + - ``verbose`` -- boolean (default: ``False``); if ``True``, print some + messages as the chain complex is computed. + - ``check`` -- boolean (default: ``False``); if ``True``, make sure + that the chain complex is actually a chain complex: the differentials + are composable and their product is zero. + + .. NOTE:: If subcomplex is nonempty, then the argument ``augmented`` has no effect: the chain complex relative to a nonempty @@ -1292,7 +1319,7 @@ def alexander_whitney(self, cube, dim_left): - ``dim`` -- integer between 0 and one more than the dimension of this cube - OUTPUT: a list containing triples ``(coeff, left, right)`` + OUTPUT: list containing triples ``(coeff, left, right)`` EXAMPLES:: @@ -1310,9 +1337,11 @@ def n_skeleton(self, n): r""" The n-skeleton of this cubical complex. - :param n: dimension - :type n: non-negative integer - :return: cubical complex + INPUT: + + - ``n`` -- nonnegative integer; dimension + + OUTPUT: cubical complex EXAMPLES:: @@ -1355,10 +1384,10 @@ def graph(self): def is_pure(self): """ - True iff this cubical complex is pure: that is, + Return ``True`` iff this cubical complex is pure: that is, all of its maximal faces have the same dimension. - .. warning:: + .. WARNING:: This may give the wrong answer if the cubical complex was constructed with ``maximality_check`` set to False. @@ -1381,7 +1410,9 @@ def join(self, other): NOT IMPLEMENTED. - :param other: another cubical complex + INPUT: + + - ``other`` -- another cubical complex EXAMPLES:: @@ -1424,8 +1455,9 @@ def suspension(self, n=1): NOT IMPLEMENTED - :param n: suspend this many times - :type n: positive integer; optional, default 1 + INPUT: + + - ``n`` -- positive integer (default: 1); suspend this many times The suspension is the complex formed by taking the join of the original complex with a two-point complex (the 0-sphere). @@ -1441,7 +1473,7 @@ def suspension(self, n=1): NotImplementedError: suspensions are not implemented for cubical complexes """ # if n<0: -# raise ValueError, "n must be non-negative." +# raise ValueError, "n must be nonnegative." # if n==0: # return self # if n==1: @@ -1453,7 +1485,9 @@ def product(self, other): r""" Return the product of this cubical complex with another one. - :param other: another cubical complex + INPUT: + + - ``other`` -- another cubical complex EXAMPLES:: @@ -1469,7 +1503,9 @@ def disjoint_union(self, other): """ The disjoint union of this cubical complex with another one. - :param right: the other cubical complex (the right-hand factor) + INPUT: + + - ``right`` -- the other cubical complex (the right-hand factor) Algorithm: first embed both complexes in d-dimensional Euclidean space. Then embed in (1+d)-dimensional space, @@ -1499,7 +1535,9 @@ def wedge(self, other): The wedge (one-point union) of this cubical complex with another one. - :param right: the other cubical complex (the right-hand factor) + INPUT: + + - ``right`` -- the other cubical complex (the right-hand factor) Algorithm: if ``self`` is embedded in `d` dimensions and ``other`` in `n` dimensions, embed them in `d+n` dimensions: @@ -1507,7 +1545,7 @@ def wedge(self, other): last `n`, translating them so that they have the origin as a common vertex. - .. note:: + .. NOTE:: This operation is not well-defined if ``self`` or ``other`` is not path-connected. @@ -1532,14 +1570,17 @@ def wedge(self, other): def connected_sum(self, other): """ - Return the connected sum of self with other. + Return the connected sum of ``self`` with ``other``. - :param other: another cubical complex - :return: the connected sum ``self # other`` + INPUT: + + - ``other`` -- another cubical complex + + OUTPUT: the connected sum ``self # other`` .. warning:: - This does not check that self and other are manifolds, only + This does not check that ``self`` and ``other`` are manifolds, only that their facets all have the same dimension. Since a (more or less) random facet is chosen from each complex and then glued together, this method may return random @@ -1609,9 +1650,11 @@ def _translate(self, vec): """ Translate ``self`` by ``vec``. - :param vec: anything which can be converted to a tuple of integers - :return: the translation of ``self`` by ``vec`` - :rtype: cubical complex + INPUT: + + - ``vec`` -- anything which can be converted to a tuple of integers + + OUTPUT: cubical complex; the translation of ``self`` by ``vec`` If ``vec`` is shorter than the list of intervals forming the complex, pad with zeroes, and similarly if the complexes @@ -1640,8 +1683,7 @@ def algebraic_topological_model(self, base_ring=None): INPUT: - - ``base_ring`` -- coefficient ring (default: - ``QQ``). Must be a field. + - ``base_ring`` -- coefficient ring (default: ``QQ``); must be a field Denote by `C` the chain complex associated to this cubical complex. The algebraic topological model is a chain complex @@ -1691,7 +1733,7 @@ def algebraic_topological_model(self, base_ring=None): def _simplicial_(self): r""" - Simplicial complex constructed from self. + Simplicial complex constructed from ``self``. ALGORITHM: @@ -1794,8 +1836,9 @@ def Sphere(self, n): A cubical complex representation of the `n`-dimensional sphere, formed by taking the boundary of an `(n+1)`-dimensional cube. - :param n: the dimension of the sphere - :type n: non-negative integer + INPUT: + + - ``n`` -- nonnegative integer; the dimension of the sphere EXAMPLES:: @@ -1866,12 +1909,13 @@ def KleinBottle(self): def SurfaceOfGenus(self, g, orientable=True): """ - A surface of genus g as a cubical complex. + A surface of genus `g` as a cubical complex. - :param g: the genus - :type g: non-negative integer - :param orientable: whether the surface should be orientable - :type orientable: bool, optional, default: ``True`` + INPUT: + + - ``g`` -- nonnegative integer; the genus + - ``orientable`` -- boolean (default: ``True``); whether the surface + should be orientable In the orientable case, return a sphere if `g` is zero, and otherwise return a `g`-fold connected sum of a torus with @@ -1891,9 +1935,9 @@ def SurfaceOfGenus(self, g, orientable=True): try: g = Integer(g) except TypeError: - raise ValueError("genus must be a non-negative integer") + raise ValueError("genus must be a nonnegative integer") if g < 0: - raise ValueError("genus must be a non-negative integer") + raise ValueError("genus must be a nonnegative integer") if g == 0: if not orientable: raise ValueError("no non-orientable surface of genus zero") @@ -1912,8 +1956,9 @@ def Cube(self, n): r""" A cubical complex representation of an `n`-dimensional cube. - :param n: the dimension - :type n: non-negative integer + INPUT: + + - ``n`` -- nonnegative integer; the dimension EXAMPLES:: diff --git a/src/sage/topology/delta_complex.py b/src/sage/topology/delta_complex.py index a02002adcb3..6cd2ee7acc6 100644 --- a/src/sage/topology/delta_complex.py +++ b/src/sage/topology/delta_complex.py @@ -14,7 +14,7 @@ A `\Delta`-complex is a generalization of a :mod:`simplicial complex `; a `\Delta`-complex `X` consists -of sets `X_n` for each non-negative integer `n`, the elements of which +of sets `X_n` for each nonnegative integer `n`, the elements of which are called *n-simplices*, along with *face maps* between these sets of simplices: for each `n` and for all `0 \leq i \leq n`, there are functions `d_i` from `X_n` to `X_{n-1}`, with `d_i(s)` equal to the @@ -40,7 +40,7 @@ representation of a torus using only 2 triangles, 3 edges, and 1 vertex. -.. note:: +.. NOTE:: This class derives from :class:`~sage.homology.cell_complex.GenericCellComplex`, and so @@ -66,10 +66,13 @@ class DeltaComplex(GenericCellComplex): r""" Define a `\Delta`-complex. - :param data: see below for a description of the options - :param check_validity: If True, check that the simplicial identities hold. - :type check_validity: boolean; optional, default: ``True`` - :return: a `\Delta`-complex + INPUT: + + - ``data`` -- see below for a description of the options + - ``check_validity`` -- boolean (default: ``True``); if ``True``, check + that the simplicial identities hold + + OUTPUT: a `\Delta`-complex Use ``data`` to define a `\Delta`-complex. It may be in any of three forms: @@ -77,16 +80,15 @@ class DeltaComplex(GenericCellComplex): - ``data`` may be a dictionary indexed by simplices. The value associated to a d-simplex `S` can be any of: - - a list or tuple of (d-1)-simplices, where the ith entry is the - ith face of S, given as a simplex, + - a list or tuple of (d-1)-simplices, where the i-th entry is the + i-th face of S, given as a simplex, - - another d-simplex `T`, in which case the ith face of `S` is - declared to be the same as the ith face of `T`: `S` and `T` + - another d-simplex `T`, in which case the i-th face of `S` is + declared to be the same as the i-th face of `T`: `S` and `T` are glued along their entire boundary, - - None or True or False or anything other than the previous two - options, in which case the faces are just the ordinary faces - of `S`. + - ``None`` or ``True`` or ``False`` or anything other than the previous two + options, in which case the faces are just the ordinary faces of `S`. For example, consider the following:: @@ -139,8 +141,8 @@ class DeltaComplex(GenericCellComplex): by omitting the lowest numbered vertex, etc., and so the boundary consists of the edges ``[1,2]``, ``[0,2]``, and ``[0,1]``, in that order. The boundary of the second is, on the - one hand, computed the same way: the nth face is obtained by - omitting the nth vertex. On the other hand, the boundary is + one hand, computed the same way: the n-th face is obtained by + omitting the n-th vertex. On the other hand, the boundary is explicitly declared to be edges ``[0,1]``, ``[0,2]``, and ``[1,2]``, in that order. This glues the second triangle to the first in the prescribed way. The three edges each start and end @@ -148,10 +150,10 @@ class DeltaComplex(GenericCellComplex): .. image:: ../../media/torus_labelled.png - - ``data`` may be nested lists or tuples. The nth entry in the + - ``data`` may be nested lists or tuples. The n-th entry in the list is a list of the n-simplices in the complex, and each - n-simplex is encoded as a list, the ith entry of which is its - ith face. Each face is represented by an integer, giving its + n-simplex is encoded as a list, the i-th entry of which is its + i-th face. Each face is represented by an integer, giving its index in the list of (n-1)-faces. For example, consider this:: sage: P = DeltaComplex( [ [(), ()], [(1,0), (1,0), (0,0)], @@ -392,10 +394,12 @@ def subcomplex(self, data): r""" Create a subcomplex. - :param data: a dictionary indexed by dimension or a list (or + INPUT: + + - ``data`` -- dictionary indexed by dimension or a list (or tuple); in either case, data[n] should be the list (or tuple or set) of the indices of the simplices to be included in - the subcomplex. + the subcomplex This automatically includes all faces of the simplices in ``data``, so you only have to specify the simplices which are @@ -515,14 +519,15 @@ def cells(self, subcomplex=None): r""" The cells of this `\Delta`-complex. - :param subcomplex: a subcomplex of this complex - :type subcomplex: optional, default None + INPUT: + + - ``subcomplex`` -- a subcomplex of this complex (default: ``None``) The cells of this `\Delta`-complex, in the form of a dictionary: the keys are integers, representing dimension, and the value associated to an integer d is the list of d-cells. Each - d-cell is further represented by a list, the ith entry of - which gives the index of its ith face in the list of + d-cell is further represented by a list, the i-th entry of + which gives the index of its i-th face in the list of (d-1)-cells. If the optional argument ``subcomplex`` is present, then @@ -573,33 +578,29 @@ def chain_complex(self, subcomplex=None, augmented=False, r""" The chain complex associated to this `\Delta`-complex. - :param dimensions: if None, compute the chain complex in all - dimensions. If a list or tuple of integers, compute the - chain complex in those dimensions, setting the chain groups - in all other dimensions to zero. NOT IMPLEMENTED YET: this - function always returns the entire chain complex - :param base_ring: commutative ring - :type base_ring: optional, default ZZ - :param subcomplex: a subcomplex of this simplicial complex. - Compute the chain complex relative to this subcomplex. - :type subcomplex: optional, default empty - :param augmented: If True, return the augmented chain complex - (that is, include a class in dimension `-1` corresponding - to the empty cell). This is ignored if ``dimensions`` is - specified or if ``subcomplex`` is nonempty. - :type augmented: boolean; optional, default: ``False`` - :param cochain: If True, return the cochain complex (that is, - the dual of the chain complex). - :type cochain: boolean; optional, default: ``False`` - :param verbose: If True, print some messages as the chain - complex is computed. - :type verbose: boolean; optional, default: ``False`` - :param check: If True, make sure that the chain complex - is actually a chain complex: the differentials are - composable and their product is zero. - :type check: boolean; optional, default: ``False`` - - .. note:: + INPUT: + + - ``dimensions`` -- if ``None``, compute the chain complex in all + dimensions. If a list or tuple of integers, compute the + chain complex in those dimensions, setting the chain groups + in all other dimensions to zero. NOT IMPLEMENTED YET: this + function always returns the entire chain complex + - ``base_ring`` -- commutative ring (default: ``ZZ``) + - ``subcomplex`` -- a subcomplex of this simplicial complex (default: + empty). Compute the chain complex relative to this subcomplex. + - ``augmented`` -- boolean (default: ``False``); if ``True``, return the + augmented chain complex (that is, include a class in dimension `-1` + corresponding to the empty cell). This is ignored if ``dimensions`` + is specified or if ``subcomplex`` is nonempty. + - ``cochain`` -- boolean (default: ``False``); if ``True``, return the + cochain complex (that is, the dual of the chain complex) + - ``verbose`` -- boolean (default: ``False``); if ``True``, print some + messages as the chain complex is computed + - ``check`` -- boolean (default: ``False``); if ``True``, make sure that + the chain complex is actually a chain complex: the differentials are + composable and their product is zero + + .. NOTE:: If subcomplex is nonempty, then the argument ``augmented`` has no effect: the chain complex relative to a nonempty @@ -709,7 +710,7 @@ def alexander_whitney(self, cell, dim_left): - ``dim_left`` -- integer between 0 and one more than the dimension of this simplex - OUTPUT: a list containing just the triple ``(1, left, + OUTPUT: list containing just the triple ``(1, left, right)``, where ``left`` and ``right`` are the two cells described above, each given as pairs ``(idx, tuple)``. @@ -742,8 +743,7 @@ def n_skeleton(self, n): r""" The n-skeleton of this `\Delta`-complex. - :param n: dimension - :type n: non-negative integer + - ``n`` -- nonnegative integer; dimension EXAMPLES:: @@ -788,15 +788,17 @@ def join(self, other): r""" The join of this `\Delta`-complex with another one. - :param other: another `\Delta`-complex (the right-hand - factor) - :return: the join ``self * other`` + INPUT: + + - ``other`` -- another `\Delta`-complex (the right-hand factor) + + OUTPUT: the join ``self * other`` The join of two `\Delta`-complexes `S` and `T` is the `\Delta`-complex `S*T` with simplices of the form `[v_0, ..., v_k, w_0, ..., w_n]` for all simplices `[v_0, ..., v_k]` in `S` and `[w_0, ..., w_n]` in `T`. The faces are computed - accordingly: the ith face of such a simplex is either `(d_i S) + accordingly: the i-th face of such a simplex is either `(d_i S) * T` if `i \leq k`, or `S * (d_{i-k-1} T)` if `i > k`. EXAMPLES:: @@ -902,8 +904,7 @@ def suspension(self, n=1): r""" The suspension of this `\Delta`-complex. - :param n: suspend this many times. - :type n: positive integer; optional, default 1 + - ``n`` -- positive integer (default: 1); suspend this many times The suspension is the complex formed by adding two new vertices `S_0` and `S_1` and simplices of the form `[S_0, v_0, @@ -920,7 +921,7 @@ def suspension(self, n=1): {0: 0, 1: 0, 2: 0, 3: Z} """ if n < 0: - raise ValueError("n must be non-negative") + raise ValueError("n must be nonnegative") if n == 0: return self if n == 1: @@ -931,11 +932,13 @@ def product(self, other): r""" The product of this `\Delta`-complex with another one. - :param other: another `\Delta`-complex (the right-hand - factor) - :return: the product ``self x other`` + INPUT: - .. warning:: + - ``other`` -- another `\Delta`-complex (the right-hand factor) + + OUTPUT: the product ``self x other`` + + .. WARNING:: If ``X`` and ``Y`` are `\Delta`-complexes, then ``X*Y`` returns their join, not their product. @@ -1060,7 +1063,9 @@ def disjoint_union(self, right): r""" The disjoint union of this `\Delta`-complex with another one. - :param right: the other `\Delta`-complex (the right-hand factor) + INPUT: + + - ``right`` -- the other `\Delta`-complex (the right-hand factor) EXAMPLES:: @@ -1087,9 +1092,9 @@ def wedge(self, right): The wedge (one-point union) of this `\Delta`-complex with another one. - :param right: the other `\Delta`-complex (the right-hand factor) + - ``right`` -- the other `\Delta`-complex (the right-hand factor) - .. note:: + .. NOTE:: This operation is not well-defined if ``self`` or ``other`` is not path-connected. @@ -1114,15 +1119,18 @@ def wedge(self, right): def connected_sum(self, other): r""" - Return the connected sum of self with other. + Return the connected sum of ``self`` with ``other``. - :param other: another `\Delta`-complex - :return: the connected sum ``self # other`` + INPUT: + + - ``other`` -- another `\Delta`-complex + + OUTPUT: the connected sum ``self # other`` .. warning:: - This does not check that self and other are manifolds. It - doesn't even check that their facets all have the same + This does not check that ``self`` and ``other`` are manifolds. + It doesn't even check that their facets all have the same dimension. It just chooses top-dimensional simplices from each complex, checks that they have the same dimension, removes them, and glues the remaining pieces together. @@ -1219,9 +1227,12 @@ def elementary_subdivision(self, idx=-1): top-dimensional simplices) of the simplex to subdivide. If not present, subdivide the last entry in this list. - :param idx: index specifying which simplex to subdivide - :type idx: integer; optional, default -1 - :return: `\Delta`-complex with one simplex subdivided. + INPUT: + + - ``idx`` -- integer (default: -1); index specifying which simplex to + subdivide + + OUTPUT: `\Delta`-complex with one simplex subdivided *Elementary subdivision* of a simplex means replacing that simplex with the cone on its boundary. That is, given a @@ -1331,12 +1342,15 @@ def _epi_from_standard_simplex(self, idx=-1, dim=None): This is used by :meth:`elementary_subdivision`. - :param idx: index specifying which simplex to examine - :type idx: integer; optional, default -1 - :return: boolean, True if the boundary of the simplex has any - identifications - :param dim: dimension of simplex to consider - :type dim: integer; optional, default = dim of complex + INPUT: + + - ``idx`` -- integer (default: -1); index specifying which simplex to + examine + - ``dim`` -- integer (default: dimension of complex); dimension of simplex + to consider + + OUTPUT: boolean; whether the boundary of the simplex has any + identifications Suppose that the dimension is `d`. The map is given by a dictionary indexed by dimension: in dimension `i`, its value @@ -1367,7 +1381,7 @@ def _epi_from_standard_simplex(self, idx=-1, dim=None): """ if dim is None: dim = self.dimension() - # the output is easier to read if the entries are non-negative. + # the output is easier to read if the entries are nonnegative. if idx == -1: idx = len(self.n_cells(dim)) - 1 simplex = SimplicialComplex([Simplex(dim)]).delta_complex(sort_simplices=True) @@ -1398,7 +1412,7 @@ def _epi_from_standard_simplex(self, idx=-1, dim=None): def _is_glued(self, idx=-1, dim=None): r""" - ``True`` if there is any gluing along the boundary of a + Return ``True`` if there is any gluing along the boundary of a top-dimensional simplex in this `\Delta`-complex. If the optional argument ``idx`` is present, it specifies @@ -1410,12 +1424,15 @@ def _is_glued(self, idx=-1, dim=None): This is used by :meth:`connected_sum`. - :param idx: index specifying which simplex to examine - :type idx: integer; optional, default -1 - :return: boolean, True if the boundary of the simplex has any - identifications - :param dim: dimension of simplex to consider - :type dim: integer; optional, default = dim of complex + INPUT: + + - ``idx`` -- integer (default: -1); index specifying which simplex to + examine + - ``dim`` -- integer (default: dimension of complex); dimension of simplex + to consider + + OUTPUT: boolean; whether the boundary of the simplex has any + identifications EXAMPLES:: @@ -1551,8 +1568,7 @@ def algebraic_topological_model(self, base_ring=None): INPUT: - - ``base_ring`` -- coefficient ring (default: - ``QQ``). Must be a field. + - ``base_ring`` -- coefficient ring (default: ``QQ``); must be a field Denote by `C` the chain complex associated to this `\Delta`-complex. The algebraic topological model is a chain complex @@ -1647,7 +1663,9 @@ def Sphere(self, n): except in dimension 1, in which case it is a single 1-simplex starting and ending at the same vertex. - :param n: dimension of the sphere + INPUT: + + - ``n`` -- dimension of the sphere EXAMPLES:: @@ -1729,10 +1747,11 @@ def SurfaceOfGenus(self, g, orientable=True): r""" A surface of genus g as a `\Delta`-complex. - :param g: the genus - :type g: non-negative integer - :param orientable: whether the surface should be orientable - :type orientable: bool, optional, default ``True`` + INPUT: + + - ``g`` -- nonnegative integer; the genus + - ``orientable`` -- boolean (default: ``True``); whether the surface + should be orientable In the orientable case, return a sphere if `g` is zero, and otherwise return a `g`-fold connected sum of a torus with @@ -1765,9 +1784,9 @@ def SurfaceOfGenus(self, g, orientable=True): try: g = Integer(g) except TypeError: - raise ValueError("genus must be a non-negative integer") + raise ValueError("genus must be a nonnegative integer") if g < 0: - raise ValueError("genus must be a non-negative integer") + raise ValueError("genus must be a nonnegative integer") if g == 0: if not orientable: raise ValueError("no non-orientable surface of genus zero") diff --git a/src/sage/topology/filtered_simplicial_complex.py b/src/sage/topology/filtered_simplicial_complex.py index 95191dd1cd4..1354e7a8fb6 100644 --- a/src/sage/topology/filtered_simplicial_complex.py +++ b/src/sage/topology/filtered_simplicial_complex.py @@ -101,7 +101,7 @@ class FilteredSimplicialComplex(SageObject): INPUT: - ``simplices`` -- list of simplices and filtration values - - ``verbose`` -- (default: ``False``) if ``True``, any change to + - ``verbose`` -- boolean (default: ``False``); if ``True``, any change to the filtration value of a simplex will be printed ``simplices`` should be a list of tuples ``(l, v)``, where @@ -381,9 +381,9 @@ def _persistent_homology(self, field=2, strict=True, verbose=False): - ``field`` -- (default: 2) prime number modulo which the homology is computed - - ``strict`` -- (default: ``True``) if ``False``, takes into account + - ``strict`` -- boolean (default: ``True``); if ``False``, takes into account intervals of persistence 0 - - ``verbose`` -- (default: ``False``) if ``True``, prints the + - ``verbose`` -- boolean (default: ``False``); if ``True``, prints the progress of computation This method is called whenever Betti numbers or intervals are @@ -582,7 +582,7 @@ def _remove_pivot_rows(self, s, simplices): # Reduce d until it is empty or until the simplex # with maximum index in the complex among all - # non-zero terms is not in T. + # nonzero terms is not in T. while d != 0: max_index = self._max_index(d) t = simplices[max_index] @@ -634,7 +634,7 @@ def persistence_intervals(self, dimension, field=2, strict=True, verbose=None): return intervals - ``field`` -- prime number (default: 2); modulo which persistent homology is computed - - ``strict`` -- (default: ``True``) if ``False``, takes into account + - ``strict`` -- boolean (default: ``True``); if ``False``, takes into account intervals of persistence 0 - ``verbose`` -- (optional) if ``True``, print the steps of the persistent homology computation; the default is the verbosity @@ -665,7 +665,7 @@ def betti_number(self, k, a, b, field=2, strict=True, verbose=None): - ``b`` -- the size of the interval - ``field`` -- prime number (default: 2); modulo which persistent homology is computed - - ``strict`` -- (default: ``True``) if ``False``, takes into account + - ``strict`` -- boolean (default: ``True``); if ``False``, takes into account intervals of persistence 0 - ``verbose`` -- (optional) if ``True``, print the steps of the persistent homology computation; the default is the verbosity diff --git a/src/sage/topology/moment_angle_complex.py b/src/sage/topology/moment_angle_complex.py index d2b986a6a1d..04e14ef1ce4 100644 --- a/src/sage/topology/moment_angle_complex.py +++ b/src/sage/topology/moment_angle_complex.py @@ -513,7 +513,7 @@ def homology(self, dim=None, base_ring=ZZ, cohomology=False, INPUT: - - ``dim`` -- integer, or a list of integers; represents the + - ``dim`` -- integer or a list of integers; represents the homology (or homologies) we want to compute - ``base_ring`` -- commutative ring (default: ``ZZ``); must be ``ZZ`` or a field diff --git a/src/sage/topology/simplicial_complex.py b/src/sage/topology/simplicial_complex.py index a6d5cbf56f3..241b56a0ff6 100644 --- a/src/sage/topology/simplicial_complex.py +++ b/src/sage/topology/simplicial_complex.py @@ -55,10 +55,10 @@ For any simplicial complex `K` and any commutative ring `R` there is an associated chain complex, with differential of degree `-1`. The -`n^{th}` term is the free `R`-module with basis given by the +`n`-th term is the free `R`-module with basis given by the `n`-simplices of `K`. The differential is determined by its value on any simplex: on the `n`-simplex with vertices `(v_0, v_1, ..., v_n)`, -the differential is the alternating sum with `i^{th}` summand `(-1)^i` +the differential is the alternating sum with `i`-th summand `(-1)^i` multiplied by the `(n-1)`-simplex obtained by omitting vertex `v_i`. In the implementation here, the vertex set must be finite. To define a @@ -192,15 +192,14 @@ def lattice_paths(t1, t2, length=None): ``(t1[last], t2[last])``, and at each grid point, going either right or up. See the examples. - :param t1: labeling for vertices - :param t2: labeling for vertices - :param length: if not ``None``, then an integer, the length of the desired - path. - :type length: integer or ``None``; optional, default ``None`` - :type t1: list, other iterable - :type t2: list, other iterable - :return: list of lists of vertices making up the paths as described above - :rtype: list of lists + INPUT: + + - ``t1`` -- list or other iterable; labeling for vertices + - ``t2`` -- list or other iterable; labeling for vertices + - ``length`` -- integer or ``None`` (default: ``None``); if not ``None``, then + an integer, the length of the desired path + + OUTPUT: list of lists of vertices making up the paths This is used when triangulating the product of simplices. The optional argument ``length`` is used for `\Delta`-complexes, to @@ -301,10 +300,12 @@ def rename_vertex(n, keep, left=True): renamed to by prepending an 'L' or an 'R' (thus to either 'L4' or 'R4'), depending on whether the argument left is ``True`` or ``False``. - :param n: a 'vertex': either an integer or a string - :param keep: a list of three vertices - :param left: if ``True``, rename for use in left factor - :type left: boolean; optional, default ``True`` + INPUT: + + - ``n`` -- a 'vertex'; either an integer or a string + - ``keep`` -- list of three vertices + - ``left`` -- boolean (default: ``True``); if ``True``, rename for use in + left factor This is used by the :meth:`~SimplicialComplex.connected_sum` method for simplicial complexes. @@ -336,11 +337,13 @@ class Simplex(SageObject): by specifying a set of vertices. It is represented in Sage by the tuple of the vertices. - :param X: set of vertices - :type X: integer, list, other iterable - :return: simplex with those vertices + INPUT: - ``X`` may be a non-negative integer `n`, in which case the + - ``X`` -- set of vertices (integer, list, or other iterable) + + OUTPUT: simplex with those vertices + + ``X`` may be a nonnegative integer `n`, in which case the simplicial complex will have `n+1` vertices `(0, 1, ..., n)`, or it may be anything which may be converted to a tuple, in which case the vertices will be that tuple. In the second case, each @@ -486,7 +489,9 @@ def __add__(self, other): Simplex obtained by concatenating the underlying tuples of the two arguments. - :param other: another simplex + INPUT: + + - ``other`` -- another simplex EXAMPLES:: @@ -499,10 +504,12 @@ def face(self, n): """ The `n`-th face of this simplex. - :param n: an integer between 0 and the dimension of this simplex - :type n: integer - :return: the simplex obtained by removing the `n`-th vertex from this - simplex + INPUT: + + - ``n`` -- integer between 0 and the dimension of this simplex + + OUTPUT: the simplex obtained by removing the `n`-th vertex from this + simplex EXAMPLES:: @@ -515,7 +522,7 @@ def face(self, n): if n >= 0 and n <= self.dimension(): return Simplex(self.__tuple[:n] + self.__tuple[n+1:]) else: - raise IndexError("{} does not have an nth face for n={}".format(self, n)) + raise IndexError("{} does not have an n-th face for n={}".format(self, n)) def faces(self): """ @@ -564,17 +571,17 @@ def join(self, right, rename_vertices=True): The join of two simplices `[v_0, ..., v_k]` and `[w_0, ..., w_n]` is the simplex `[v_0, ..., v_k, w_0, ..., w_n]`. - :param right: the other simplex (the right-hand factor) + INPUT: - :param rename_vertices: If this is ``True``, the vertices in the - join will be renamed by this formula: vertex "v" in the - left-hand factor --> vertex "Lv" in the join, vertex "w" - in the right-hand factor --> vertex "Rw" in the join. If - this is false, this tries to construct the join without - renaming the vertices; this may cause problems if the two - factors have any vertices with names in common. + - ``right`` -- the other simplex (the right-hand factor) - :type rename_vertices: boolean; optional, default ``True`` + - ``rename_vertices`` -- boolean (default: ``True``); if this is ``True``, + the vertices in the join will be renamed by this formula: vertex "v" + in the left-hand factor --> vertex "Lv" in the join, vertex "w" in + the right-hand factor --> vertex "Rw" in the join. If this is + ``False``, this tries to construct the join without renaming the + vertices; this may cause problems if the two factors have any + vertices with names in common. EXAMPLES:: @@ -596,27 +603,26 @@ def product(self, other, rename_vertices=True): r""" The product of this simplex with another one, as a list of simplices. - :param other: the other simplex + INPUT: - :param rename_vertices: If this is ``False``, then the vertices in - the product are the set of ordered pairs `(v,w)` where `v` - is a vertex in the left-hand factor (``self``) and `w` is - a vertex in the right-hand factor (``other``). If this is - ``True``, then the vertices are renamed as "LvRw" (e.g., the - vertex (1,2) would become "L1R2"). This is useful if you - want to define the Stanley-Reisner ring of the complex: - vertex names like (0,1) are not suitable for that, while - vertex names like "L0R1" are. + - ``other`` -- the other simplex - :type rename_vertices: boolean; optional, default ``True`` + - ``rename_vertices`` -- boolean (default: ``True``); if this is + ``False``, then the vertices in the product are the set of ordered + pairs `(v,w)` where `v` is a vertex in the left-hand factor + (``self``) and `w` is a vertex in the right-hand factor (``other``). + If this is ``True``, then the vertices are renamed as "LvRw" (e.g., + the vertex (1,2) would become "L1R2"). This is useful if you want to + define the Stanley-Reisner ring of the complex: vertex names like + (0,1) are not suitable for that, while vertex names like "L0R1" are. - Algorithm: see Hatcher, p. 277-278 [Hat2002]_ (who in turn refers to + ALGORITHM: see Hatcher, p. 277-278 [Hat2002]_ (who in turn refers to Eilenberg-Steenrod, p. 68): given ``S = Simplex(m)`` and ``T = Simplex(n)``, then `S \times T` can be triangulated as follows: for each path `f` from `(0,0)` to `(m,n)` along the integer grid in the plane, going up or right at each lattice point, associate an `(m+n)`-simplex with - vertices `v_0`, `v_1`, ..., where `v_k` is the `k^{th}` vertex + vertices `v_0`, `v_1`, ..., where `v_k` is the `k`-th vertex in the path `f`. Note that there are `m+n` choose `n` such paths. Note also @@ -697,7 +703,9 @@ def __eq__(self, other): is, if the vertices of the two are the same, even with a different ordering - :param other: the other simplex + INPUT: + + - ``other`` -- the other simplex EXAMPLES:: @@ -718,7 +726,9 @@ def __ne__(self, other): """ Return ``True`` iff this simplex is not equal to ``other``. - :param other: the other simplex + INPUT: + + - ``other`` -- the other simplex EXAMPLES:: @@ -734,7 +744,9 @@ def __lt__(self, other): Return ``True`` iff the sorted tuple for this simplex is less than that for ``other``. - :param other: the other simplex + INPUT: + + - ``other`` -- the other simplex EXAMPLES:: @@ -821,25 +833,25 @@ class SimplicialComplex(Parent, GenericCellComplex): r""" Define a simplicial complex. - :param maximal_faces: set of maximal faces - :param from_characteristic_function: see below - :param maximality_check: see below - :type maximality_check: boolean; optional, default ``True`` - :param sort_facets: see below - :type sort_facets: dict - :param name_check: see below - :type name_check: boolean; optional, default ``False`` - :param is_mutable: Set to ``False`` to make this immutable - :type is_mutable: boolean; optional, default ``True`` - :param category: the category of the simplicial complex - :type category: category; optional, default finite simplicial complexes - :return: a simplicial complex + INPUT: + + - ``maximal_faces`` -- set of maximal faces + - ``from_characteristic_function`` -- see below + - ``maximality_check`` -- boolean (default: ``True``); see below + - ``sort_facets`` -- dictionary; see below + - ``name_check`` -- boolean (default: ``False``); see below + - ``is_mutable`` -- boolean (default: ``True``); set to ``False`` to make + this immutable + - ``category`` -- the category of the simplicial complex (default: finite + simplicial complexes) + + OUTPUT: a simplicial complex ``maximal_faces`` should be a list or tuple or set (indeed, anything which may be converted to a set) whose elements are lists (or tuples, etc.) of vertices. Maximal faces are also known as 'facets'. ``maximal_faces`` can also be a list containing a single - non-negative integer `n`, in which case this constructs the + nonnegative integer `n`, in which case this constructs the simplicial complex with a single `n`-simplex as the only facet. Alternatively, the maximal faces can be defined from a monotone boolean @@ -1025,7 +1037,7 @@ def __init__(self, # Convert it into a list (in case it is an iterable) maximal_faces = list(maximal_faces) if len(maximal_faces) == 1 and isinstance(maximal_faces[0], (int, Integer)): - # list containing a single non-negative integer n; + # list containing a single nonnegative integer n; # construct the simplicial complex with a single n-simplex as the only facet. vertices = tuple(range(maximal_faces[0] + 1)) maximal_faces = [vertices] @@ -1247,7 +1259,7 @@ def _an_element_(self): def __contains__(self, x): """ - True if ``x`` is a simplex which is contained in this complex. + Return ``True`` if ``x`` is a simplex which is contained in this complex. EXAMPLES:: @@ -1268,7 +1280,7 @@ def __call__(self, simplex): """ If ``simplex`` is a simplex in this complex, return it. - Otherwise, this raises a :class:`ValueError`. + Otherwise, this raises a :exc:`ValueError`. EXAMPLES:: @@ -1315,10 +1327,10 @@ def faces(self, subcomplex=None): argument ``subcomplex`` is present, then return only the faces which are *not* in the subcomplex. - :param subcomplex: a subcomplex of this simplicial complex. - Return faces which are not in this subcomplex. + INPUT: - :type subcomplex: optional, default ``None`` + - ``subcomplex`` -- a subcomplex of this simplicial complex (default: + ``None``); return faces which are not in this subcomplex EXAMPLES:: @@ -1373,7 +1385,7 @@ def face_iterator(self, increasing=True): INPUT: - - ``increasing`` -- (default: ``True``) if ``True``, return + - ``increasing`` -- boolean (default: ``True``); if ``True``, return faces in increasing order of dimension, thus starting with the empty face. Otherwise it returns faces in decreasing order of dimension. @@ -1501,7 +1513,7 @@ def g_vector(self): def face(self, simplex, i): """ - The `i`-th face of ``simplex`` in this simplicial complex + The `i`-th face of ``simplex`` in this simplicial complex. INPUT: @@ -1600,9 +1612,7 @@ def F_triangle(self, S): This is the bivariate generating polynomial of all faces, according to the number of elements in ``S`` and outside ``S``. - OUTPUT: - - an :class:`~sage.combinat.triangles_FHM.F_triangle` + OUTPUT: an :class:`~sage.combinat.triangles_FHM.F_triangle` .. SEEALSO:: @@ -1711,7 +1721,7 @@ def flip_graph(self): def is_pseudomanifold(self): """ - Return True if ``self`` is a pseudomanifold. + Return ``True`` if ``self`` is a pseudomanifold. A pseudomanifold is a simplicial complex with the following properties: @@ -1768,25 +1778,24 @@ def product(self, right, rename_vertices=True, is_mutable=True): """ The product of this simplicial complex with another one. - :param right: the other simplicial complex (the right-hand - factor) + INPUT: - :param rename_vertices: If this is False, then the vertices in - the product are the set of ordered pairs `(v,w)` where `v` - is a vertex in ``self`` and `w` is a vertex in - ``right``. If this is ``True``, then the vertices are renamed - as "LvRw" (e.g., the vertex (1,2) would become "L1R2"). - This is useful if you want to define the Stanley-Reisner - ring of the complex: vertex names like (0,1) are not - suitable for that, while vertex names like "L0R1" are. + - ``right`` -- the other simplicial complex (the right-hand factor) - :type rename_vertices: boolean; optional, default ``True`` + - ``rename_vertices`` -- boolean (default: ``True``); if this is + ``False``, then the vertices in the product are the set of ordered + pairs `(v,w)` where `v` is a vertex in ``self`` and `w` is a vertex + in ``right``. If this is ``True``, then the vertices are renamed as + "LvRw" (e.g., the vertex (1,2) would become "L1R2"). This is useful + if you want to define the Stanley-Reisner ring of the complex: vertex + names like (0,1) are not suitable for that, while vertex names like + "L0R1" are. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + - ``is_mutable`` -- boolean (default: ``True``); determines whether the + output is mutable The vertices in the product will be the set of ordered pairs - `(v,w)` where `v` is a vertex in self and `w` is a vertex in + `(v,w)` where `v` is a vertex in ``self`` and `w` is a vertex in right. .. WARNING:: @@ -1848,20 +1857,20 @@ def join(self, right, rename_vertices=True, is_mutable=True): ..., v_k, w_0, ..., w_n]` for all simplices `[v_0, ..., v_k]` in `S` and `[w_0, ..., w_n]` in `T`. - :param right: the other simplicial complex (the right-hand factor) + INPUT: - :param rename_vertices: If this is True, the vertices in the - join will be renamed by the formula: vertex "v" in the - left-hand factor --> vertex "Lv" in the join, vertex "w" in - the right-hand factor --> vertex "Rw" in the join. If this - is false, this tries to construct the join without renaming - the vertices; this will cause problems if the two factors - have any vertices with names in common. + - ``right`` -- the other simplicial complex (the right-hand factor) - :type rename_vertices: boolean; optional, default ``True`` + - ``rename_vertices`` -- boolean (default: ``True``); if this is + ``True``, the vertices in the join will be renamed by the formula: + vertex "v" in the left-hand factor --> vertex "Lv" in the join, + vertex "w" in the right-hand factor --> vertex "Rw" in the join. + If this is ``False``, this tries to construct the join without + renaming the vertices; this will cause problems if the two factors + have any vertices with names in common. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + - ``is_mutable`` -- boolean (default: ``True``); determine whether the + output is mutable EXAMPLES:: @@ -1893,8 +1902,10 @@ def cone(self, is_mutable=True): """ The cone on this simplicial complex. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + INPUT: + + - ``is_mutable`` -- boolean (default: ``True``); determines whether + the output is mutable The cone is the simplicial complex formed by adding a new vertex `C` and simplices of the form `[C, v_0, ..., v_k]` for @@ -1920,12 +1931,12 @@ def suspension(self, n=1, is_mutable=True): r""" The suspension of this simplicial complex. - :param n: positive integer -- suspend this many times. + INPUT: - :type n: optional, default 1 + - ``n`` -- positive integer (default: 1); suspend this many times - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + - ``is_mutable`` -- boolean (default: ``True``); determine whether + the output is mutable The suspension is the simplicial complex formed by adding two new vertices `S_0` and `S_1` and simplices of the form `[S_0, @@ -1967,7 +1978,7 @@ def suspension(self, n=1, is_mutable=True): (0, 1, 2, 3, 4, 5, 6, 7) """ if n < 0: - raise ValueError("n must be non-negative") + raise ValueError("n must be nonnegative") if n == 0: return self if n == 1: @@ -1996,18 +2007,17 @@ def disjoint_union(self, right, rename_vertices=None, is_mutable=True): """ The disjoint union of this simplicial complex with another one. - :param right: the other simplicial complex (the right-hand factor) + INPUT: - :param rename_vertices: If this is True, the vertices in the - disjoint union will be renamed by the formula: vertex "v" - in the left-hand factor --> vertex "Lv" in the disjoint - union, vertex "w" in the right-hand factor --> vertex "Rw" - in the disjoint union. If this is false, this tries to - construct the disjoint union without renaming the vertices; - this will cause problems if the two factors have any - vertices with names in common. + - ``right`` -- the other simplicial complex (the right-hand factor) - :type rename_vertices: boolean; optional, default: ``True`` + - ``rename_vertices`` -- boolean (default: ``True``); if this is + ``True``, the vertices in the disjoint union will be renamed by the + formula: vertex "v" in the left-hand factor --> vertex "Lv" in the + disjoint union, vertex "w" in the right-hand factor --> vertex "Rw" + in the disjoint union. If this is false, this tries to construct the + disjoint union without renaming the vertices; this will cause + problems if the two factors have any vertices with names in common. EXAMPLES:: @@ -2032,21 +2042,21 @@ def wedge(self, right, rename_vertices=True, is_mutable=True): The wedge (one-point union) of this simplicial complex with another one. - :param right: the other simplicial complex (the right-hand factor) + INPUT: - :param rename_vertices: If this is ``True``, the vertices in the - wedge will be renamed by the formula: first vertex in each - are glued together and called "0". Otherwise, each vertex - "v" in the left-hand factor --> vertex "Lv" in the wedge, - vertex "w" in the right-hand factor --> vertex "Rw" in the - wedge. If this is ``False``, this tries to construct the wedge - without renaming the vertices; this will cause problems if - the two factors have any vertices with names in common. + - ``right`` -- the other simplicial complex (the right-hand factor) - :type rename_vertices: boolean; optional, default ``True`` + - ``rename_vertices`` -- boolean (default: ``True``); if this is + ``True``, the vertices in the wedge will be renamed by the formula: + first vertex in each are glued together and called "0". Otherwise, + each vertex "v" in the left-hand factor --> vertex "Lv" in the wedge, + vertex "w" in the right-hand factor --> vertex "Rw" in the wedge. If + this is ``False``, this tries to construct the wedge without renaming + the vertices; this will cause problems if the two factors have any + vertices with names in common. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + - ``is_mutable`` -- boolean (default: ``True``); determine whether + the output is mutable .. NOTE:: @@ -2087,30 +2097,26 @@ def chain_complex(self, subcomplex=None, augmented=False, r""" The chain complex associated to this simplicial complex. - :param dimensions: if ``None``, compute the chain complex in all - dimensions. If a list or tuple of integers, compute the - chain complex in those dimensions, setting the chain groups - in all other dimensions to zero. - :param base_ring: commutative ring - :type base_ring: optional, default ``ZZ`` - :param subcomplex: a subcomplex of this simplicial complex. - Compute the chain complex relative to this subcomplex. - :type subcomplex: optional, default empty - :param augmented: If ``True``, return the augmented chain complex - (that is, include a class in dimension `-1` corresponding - to the empty cell). This is ignored if ``dimensions`` is - specified. - :type augmented: boolean; optional, default ``False`` - :param cochain: If ``True``, return the cochain complex (that is, - the dual of the chain complex). - :type cochain: boolean; optional, default ``False`` - :param verbose: If ``True``, print some messages as the chain - complex is computed. - :type verbose: boolean; optional, default ``False`` - :param check: If ``True``, make sure that the chain complex - is actually a chain complex: the differentials are - composable and their product is zero. - :type check: boolean; optional, default ``False`` + INPUT: + + - ``dimensions`` -- if ``None``, compute the chain complex in all + dimensions. If a list or tuple of integers, compute the + chain complex in those dimensions, setting the chain groups + in all other dimensions to zero. + - ``base_ring`` -- commutative ring (default: ``ZZ``) + - ``subcomplex`` -- a subcomplex of this simplicial complex (default: + empty); compute the chain complex relative to this subcomplex + - ``augmented`` -- boolean (default: ``False``); if ``True``, return + the augmented chain complex (that is, include a class in dimension + `-1` corresponding to the empty cell). This is ignored if + ``dimensions`` is specified + - ``cochain`` -- boolean (default: ``False``); if ``True``, return the + cochain complex (that is, the dual of the chain complex) + - ``verbose`` -- boolean (default: ``False``); if ``True``, print some + messages as the chain complex is computed + - ``check`` -- boolean (default: ``False``); if ``True``, make sure + that the chain complex is actually a chain complex: the differentials + are composable and their product is zero .. NOTE:: @@ -2249,62 +2255,47 @@ def _homology_(self, dim=None, base_ring=ZZ, subcomplex=None, """ The (reduced) homology of this simplicial complex. - :param dim: If ``None``, then return the homology in every - dimension. If ``dim`` is an integer or list, return the - homology in the given dimensions. (Actually, if ``dim`` is - a list, return the homology in the range from ``min(dim)`` - to ``max(dim)``.) - - :type dim: integer or list of integers or ``None``; optional, - default ``None`` - - :param base_ring: commutative ring. Must be ``ZZ`` or a field. - - :type base_ring: optional, default ``ZZ`` - - :param subcomplex: a subcomplex of this simplicial complex. - Compute homology relative to this subcomplex. - - :type subcomplex: optional, default ``None`` - - :param cohomology: If ``True``, compute cohomology rather than - homology. - - :type cohomology: boolean; optional, default ``False`` - - :param enlarge: If ``True``, find a new subcomplex homotopy - equivalent to, and probably larger than, the given one. - - :type enlarge: boolean; optional, default ``True`` + INPUT: - :param algorithm: The options are ``'auto'``, ``'dhsw'``, or - ``'pari'``. (``'no_chomp'`` is a synomym for ``'auto'``, - maintained for backward compatibility.) If ``'auto'``, - use the Dumas, Heckenbach, Saunders, and Welker elimination - algorithm for large matrices, Pari for small ones. - If ``'pari'``, then compute elementary divisors - using Pari. If ``'dhsw'``, then use the DHSW algorithm to - compute elementary divisors. (As of this writing, ``'pari'`` - is the fastest standard option.) + - ``dim`` -- integer or list of integers or ``None`` (default: + ``None``); if ``None``, then return the homology in every dimension. + If ``dim`` is an integer or list, return the homology in the given + dimensions. (Actually, if ``dim`` is a list, return the homology in + the range from ``min(dim)`` to ``max(dim)``.) - :type algorithm: string; optional, default ``'pari'`` + - ``base_ring`` -- commutative ring (default: ``ZZ``); must be ``ZZ`` + or a field - :param verbose: If ``True``, print some messages as the homology - is computed. + - ``subcomplex`` -- a subcomplex of this simplicial complex (default: + ``None``); compute homology relative to this subcomplex - :type verbose: boolean; optional, default ``False`` + - ``cohomology`` -- boolean (default: ``False``); if ``True``, compute + cohomology rather than homology - :param reduced: If ``True``, return the reduced homology. + - ``enlarge`` -- boolean (default: ``True``); if ``True``, find a new + subcomplex homotopy equivalent to, and probably larger than, the + given one - :type reduced: boolean; optional, default ``True`` + - ``algorithm`` -- string (default: ``'pari'``); the options are + ``'auto'``, ``'dhsw'``, or ``'pari'``. (``'no_chomp'`` is a synonym + for ``'auto'``, maintained for backward compatibility.) If + ``'auto'``, use the Dumas, Heckenbach, Saunders, and Welker + elimination algorithm for large matrices, Pari for small ones. If + ``'pari'``, then compute elementary divisors using Pari. If + ``'dhsw'``, then use the DHSW algorithm to compute elementary + divisors. (As of this writing, ``'pari'`` is the fastest standard + option.) - :param generators: If ``True``, return the homology groups and - also generators for them. + - ``verbose`` -- boolean (default: ``False``); if ``True``, print some + messages as the homology is computed - :type reduced: boolean; optional, default ``False`` + - ``reduced`` -- boolean (default: ``Trues``); if ``True``, return the + reduced homology + - ``generators`` -- boolean (default: ``False``); if ``True``, return + the homology groups and also generators for them - Algorithm: if ``generators`` is ``True``, directly compute the + ALGORITHM: if ``generators`` is ``True``, directly compute the chain complex, compute its homology along with its generators, and then convert the chain complex generators to chains in the simplicial complex. @@ -2472,8 +2463,7 @@ def algebraic_topological_model(self, base_ring=None): INPUT: - - ``base_ring`` -- coefficient ring (default: - ``QQ``). Must be a field. + - ``base_ring`` -- coefficient ring (default: ``QQ``); must be a field Denote by `C` the chain complex associated to this simplicial complex. The algebraic topological model is a chain complex @@ -2538,7 +2528,7 @@ def alexander_whitney(self, simplex, dim_left): - ``dim`` -- integer between 0 and one more than the dimension of this simplex - OUTPUT: a list containing just the triple ``(1, left, + OUTPUT: list containing just the triple ``(1, left, right)``, where ``left`` and ``right`` are the two simplices described above. @@ -2557,7 +2547,9 @@ def add_face(self, face): """ Add a face to this simplicial complex. - :param face: a subset of the vertex set + INPUT: + + - ``face`` -- a subset of the vertex set This *changes* the simplicial complex, adding a new face and all of its subfaces. @@ -2690,11 +2682,13 @@ def remove_face(self, face, check=False): """ Remove a face from this simplicial complex. - :param face: a face of the simplicial complex + INPUT: + + - ``face`` -- a face of the simplicial complex - :param check: boolean; optional, default ``False``. If - ``True``, raise an error if ``face`` is not a - face of this simplicial complex + - ``check`` -- boolean (default: ``False``); if + ``True``, raise an error if ``face`` is not a + face of this simplicial complex This does not return anything; instead, it *changes* the simplicial complex. @@ -2819,12 +2813,14 @@ def remove_faces(self, faces, check=False): """ Remove a collection of faces from this simplicial complex. - :param faces: a list (or any iterable) of faces of the - simplicial complex + INPUT: + + - ``faces`` -- list (or any iterable) of faces of the simplicial + complex - :param check: boolean; optional, default ``False``. If - ``True``, raise an error if any element of ``faces`` is not a - face of this simplicial complex + - ``check`` -- boolean (default: ``False``); if ``True``, raise an + error if any element of ``faces`` is not a face of this simplicial + complex This does not return anything; instead, it *changes* the simplicial complex. @@ -2867,7 +2863,9 @@ def is_subcomplex(self, other): """ Return ``True`` if this is a subcomplex of ``other``. - :param other: another simplicial complex + INPUT: + + - ``other`` -- another simplicial complex EXAMPLES:: @@ -2896,10 +2894,13 @@ def connected_sum(self, other, is_mutable=True): """ The connected sum of this simplicial complex with another one. - :param other: another simplicial complex - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` - :return: the connected sum ``self # other`` + INPUT: + + - ``other`` -- another simplicial complex + - ``is_mutable`` -- boolean (default: ``True``); determine whether + the output is mutable + + OUTPUT: the connected sum ``self # other`` .. WARNING:: @@ -2960,9 +2961,11 @@ def link(self, simplex, is_mutable=True): all simplices `G` which are disjoint from `F` but for which `F \cup G` is a simplex. - :param simplex: a simplex in this simplicial complex. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + INPUT: + + - ``simplex`` -- a simplex in this simplicial complex + - ``is_mutable`` -- boolean (default: ``True``); determine whether + the output is mutable EXAMPLES:: @@ -2992,7 +2995,7 @@ def star(self, simplex, is_mutable=True): INPUT: - ``simplex`` -- a simplex in this simplicial complex - - ``is_mutable`` -- (default: ``True``) boolean; determines if the output + - ``is_mutable`` -- boolean (default: ``True``); determines if the output is mutable EXAMPLES:: @@ -3026,7 +3029,7 @@ def is_cohen_macaulay(self, base_ring=QQ, ncpus=0): INPUT: - - ``base_ring`` -- (default: ``QQ``) the base ring. + - ``base_ring`` -- (default: ``QQ``) the base ring - ``ncpus`` -- (default: 0) number of cpus used for the computation. If this is 0, determine the number of cpus @@ -3091,9 +3094,11 @@ def generated_subcomplex(self, sub_vertex_set, is_mutable=True): Return the largest sub-simplicial complex of ``self`` containing exactly ``sub_vertex_set`` as vertices. - :param sub_vertex_set: The sub-vertex set. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + INPUT: + + - ``sub_vertex_set`` -- the sub-vertex set + - ``is_mutable`` -- boolean (default: ``True``); determine whether + the output is mutable EXAMPLES:: @@ -3102,7 +3107,6 @@ def generated_subcomplex(self, sub_vertex_set, is_mutable=True): Minimal triangulation of the 2-sphere sage: S.generated_subcomplex([0,1,2]) Simplicial complex with vertex set (0, 1, 2) and facets {(0, 1, 2)} - """ if not set(self.vertices()).issuperset(sub_vertex_set): raise ValueError("input must be a subset of the vertex set") @@ -3132,7 +3136,7 @@ def is_shelling_order(self, shelling_order, certificate=False): INPUT: - ``shelling_order`` -- an ordering of the facets of ``self`` - - ``certificate`` -- (default: ``False``) if ``True`` then returns + - ``certificate`` -- boolean (default: ``False``); if ``True`` then returns the index of the first facet that violate the condition .. SEEALSO:: @@ -3205,7 +3209,7 @@ def is_shellable(self, certificate=False): INPUT: - - ``certificate`` -- (default: ``False``) if ``True`` then + - ``certificate`` -- boolean (default: ``False``); if ``True`` then returns the shelling order (if it exists) EXAMPLES:: @@ -3341,7 +3345,9 @@ def _complement(self, simplex): Return the complement of a simplex in the vertex set of this simplicial complex. - :param simplex: a simplex (need not be in the simplicial complex) + INPUT: + + - ``simplex`` -- a simplex (need not be in the simplicial complex) OUTPUT: its complement: the simplex formed by the vertices not contained in ``simplex``. @@ -3367,7 +3373,9 @@ def _transpose_simplices(self, *simplices): simplex is formed by taking a vertex from each simplex from ``L``. - :param simplices: a bunch of simplices + INPUT: + + - ``simplices`` -- a bunch of simplices If ``simplices`` consists of `(f_0, f_1, f_2, ...)`, then the output consists of all possible simplices of the form `(v_0, @@ -3505,10 +3513,12 @@ def _stanley_reisner_base_ring(self, base_ring=ZZ): The polynomial algebra of which the Stanley-Reisner ring is a quotient. - :param base_ring: a commutative ring - :type base_ring: optional, default ``ZZ`` - :return: a polynomial algebra with coefficients in base_ring, - with one generator for each vertex in the simplicial complex. + INPUT: + + - ``base_ring`` -- a commutative ring (default: ``ZZ``) + + OUTPUT: a polynomial algebra with coefficients in base_ring, + with one generator for each vertex in the simplicial complex. See the documentation for :meth:`stanley_reisner_ring` for a warning about the names of the vertices. @@ -3533,12 +3543,14 @@ def stanley_reisner_ring(self, base_ring=ZZ): """ The Stanley-Reisner ring of this simplicial complex. - :param base_ring: a commutative ring - :type base_ring: optional, default ``ZZ`` - :return: a quotient of a polynomial algebra with coefficients - in ``base_ring``, with one generator for each vertex in the - simplicial complex, by the ideal generated by the products - of those vertices which do not form faces in it. + INPUT: + + - ``base_ring`` -- a commutative ring (default: ``ZZ``) + + OUTPUT: a quotient of a polynomial algebra with coefficients + in ``base_ring``, with one generator for each vertex in the + simplicial complex, by the ideal generated by the products + of those vertices which do not form faces in it Thus the ideal is generated by the products corresponding to the minimal nonfaces of the simplicial complex. @@ -3553,7 +3565,7 @@ def stanley_reisner_ring(self, base_ring=ZZ): More precisely, this is a quotient of a polynomial ring with one generator for each vertex. If the name of a - vertex is a non-negative integer, then the corresponding + vertex is a nonnegative integer, then the corresponding polynomial generator is named ``'x'`` followed by that integer (e.g., ``'x2'``, ``'x3'``, ``'x5'``, ...). Otherwise, the polynomial generators are given the same names as the vertices. @@ -3589,8 +3601,10 @@ def alexander_dual(self, is_mutable=True): Thus find the minimal nonfaces and take their complements to find the facets in the Alexander dual. - :param is_mutable: Determines if the output is mutable - :type is_mutable: boolean; optional, default ``True`` + INPUT: + + - ``is_mutable`` -- boolean (default: ``True``); determine whether + the output is mutable EXAMPLES:: @@ -3643,9 +3657,9 @@ def stellar_subdivision(self, simplex, inplace=False, is_mutable=True): INPUT: - ``simplex`` -- a simplex face of ``self`` - - ``inplace`` -- (default: ``False``) boolean; determines if the + - ``inplace`` -- boolean (default: ``False``); determines if the operation is done on ``self`` or on a copy - - ``is_mutable`` -- (default: ``True``) boolean; determines if the + - ``is_mutable`` -- boolean (default: ``True``); determines if the output is mutable OUTPUT: @@ -3772,9 +3786,10 @@ def delta_complex(self, sort_simplices=False): simplicial complex: it has same simplices with the same boundaries. - :param sort_simplices: if ``True``, sort the list of simplices in - each dimension - :type sort_simplices: boolean; optional, default ``False`` + INPUT: + + - ``sort_simplices`` -- boolean (default: ``False``); if ``True``, sort + the list of simplices in each dimension EXAMPLES:: @@ -3831,7 +3846,9 @@ def n_skeleton(self, n): The `n`-skeleton of a simplicial complex is obtained by discarding all of the simplices in dimensions larger than `n`. - :param n: non-negative integer + INPUT: + + - ``n`` -- nonnegative integer EXAMPLES:: @@ -3859,9 +3876,10 @@ def _contractible_subcomplex(self, verbose=False): Find a contractible subcomplex `L` of this simplicial complex, preferably one which is as large as possible. - :param verbose: If ``True``, print some messages as the simplicial - complex is computed. - :type verbose: boolean; optional, default ``False`` + INPUT: + + - ``verbose`` -- boolean (default: ``False``); if ``True``, print some + messages as the simplicial complex is computed Motivation: if `K` is the original complex and if `L` is contractible, then the relative homology `H_*(K,L)` is @@ -3905,12 +3923,14 @@ def _enlarge_subcomplex(self, subcomplex, verbose=False): `H_{*}(K,L)` will be smaller than that for computing `H_{*}(K,S)`, so the computations should be faster. - :param subcomplex: a subcomplex of this simplicial complex - :param verbose: If ``True``, print some messages as the simplicial - complex is computed. - :type verbose: boolean; optional, default ``False`` - :return: a complex `L` containing ``subcomplex`` and contained - in ``self``, homotopy equivalent to ``subcomplex``. + INPUT: + + - ``subcomplex`` -- a subcomplex of this simplicial complex + - ``verbose`` -- boolean (default: ``False``); if ``True``, print some + messages as the simplicial complex is computed + + OUTPUT: a complex `L` containing ``subcomplex`` and contained + in ``self``, homotopy equivalent to ``subcomplex`` Algorithm: start with the subcomplex `S` and loop through the facets of `K` which are not in `S`. For each one, see whether @@ -4096,16 +4116,16 @@ def fundamental_group(self, base_point=None, simplify=True): INPUT: - - ``base_point`` (default: None) -- if this complex is + - ``base_point`` -- (default: ``None``) if this complex is not path-connected, then specify a vertex; the fundamental group is computed with that vertex as a base point. If the complex is path-connected, then you may specify a vertex or leave this as its default setting of ``None``. (If this complex is path-connected, then this argument is ignored.) - - ``simplify`` (bool, optional True) -- if False, then return a + - ``simplify`` -- boolean (default: ``True``); then return a presentation of the group in terms of generators and - relations. If True, the default, simplify as much as GAP is + relations. If ``True``, the default, simplify as much as GAP is able to. Algorithm: we compute the edge-path group -- see @@ -4420,12 +4440,10 @@ def _Hom_(self, other, category=None): # @cached_method when we switch to immutable SimplicialComplex def _is_numeric(self): """ - Test whether all vertices are labeled by integers - - OUTPUT: + Test whether all vertices are labeled by integers. - Boolean. Whether all vertices are labeled by (not necessarily - consecutive) integers. + OUTPUT: boolean; whether all vertices are labeled by (not necessarily + consecutive) integers EXAMPLES:: @@ -4442,7 +4460,7 @@ def _is_numeric(self): # @cached_method when we switch to immutable SimplicialComplex def _translation_to_numeric(self): """ - Return a dictionary enumerating the vertices + Return a dictionary enumerating the vertices. See also :meth:`_translation_from_numeric`, which returns the inverse map. @@ -4470,7 +4488,7 @@ def _translation_to_numeric(self): # @cached_method when we switch to immutable SimplicialComplex def _translation_from_numeric(self): """ - Return a dictionary mapping vertex indices to vertices + Return a dictionary mapping vertex indices to vertices. See also :meth:`_translation_to_numeric`, which returns the inverse map. @@ -4644,11 +4662,11 @@ def is_balanced(self, check_purity=False, certificate=False): INPUT: - - ``check_purity`` -- (default: ``False``) if this is ``True``, + - ``check_purity`` -- boolean (default: ``False``); if this is ``True``, require that ``self`` be pure as well as balanced - - ``certificate`` -- (default: ``False``) if this is ``True`` and - ``self`` is balanced, then return a `d`-coloring of the 1-skeleton. + - ``certificate`` -- boolean (default: ``False``); if this is ``True`` and + ``self`` is balanced, then return a `d`-coloring of the 1-skeleton EXAMPLES: @@ -4712,11 +4730,11 @@ def is_partitionable(self, certificate=False, INPUT: - - ``certificate`` -- (default: ``False``) If ``True``, + - ``certificate`` -- boolean (default: ``False``); if ``True``, and ``self`` is partitionable, then return a list of pairs `(R,F)` that form a partitioning. - - ``solver`` -- (default: ``None``) Specify a Mixed Integer Linear Programming + - ``solver`` -- (default: ``None``) specifies a Mixed Integer Linear Programming (MILP) solver to be used. If set to ``None``, the default one is used. For more information on MILP solvers and which default solver is used, see the method @@ -4725,7 +4743,7 @@ def is_partitionable(self, certificate=False, :class:`MixedIntegerLinearProgram `. - ``integrality_tolerance`` -- parameter for use with MILP solvers over an - inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values`. + inexact base ring; see :meth:`MixedIntegerLinearProgram.get_values` EXAMPLES: @@ -4817,7 +4835,7 @@ def bigraded_betti_numbers(self, base_ring=ZZ, verbose=False): - ``base_ring`` -- (default: ``ZZ``) the base ring used when computing homology - - ``verbose`` -- (default: ``False``) if ``True``, print + - ``verbose`` -- boolean (default: ``False``); if ``True``, print messages during the computation, which indicate in which subcomplexes non-trivial homologies appear @@ -4923,7 +4941,7 @@ def bigraded_betti_number(self, a, b, base_ring=ZZ, verbose=False): - ``base_ring`` -- (default: ``ZZ``) the base ring used when computing homology - - ``verbose`` -- (default: ``False``) if ``True``, print + - ``verbose`` -- boolean (default: ``False``); if ``True``, print messages during the computation, which indicate in which subcomplexes non-trivial homologies appear diff --git a/src/sage/topology/simplicial_complex_examples.py b/src/sage/topology/simplicial_complex_examples.py index aa9c704f765..c51954d7d9a 100644 --- a/src/sage/topology/simplicial_complex_examples.py +++ b/src/sage/topology/simplicial_complex_examples.py @@ -168,8 +168,8 @@ def matching(A, B): INPUT: - - ``A``, ``B`` -- list, tuple, or indeed anything which can be - converted to a set. + - ``A``, ``B`` -- list, tuple, or indeed anything which can be + converted to a set EXAMPLES:: @@ -204,7 +204,7 @@ class UniqueSimplicialComplex(SimplicialComplex, UniqueRepresentation): ``is_mutable`` and ``is_immutable`` are ignored: all instances of this class are immutable. The addition: - - ``name`` -- string (optional), the string representation for this complex. + - ``name`` -- string (optional); the string representation for this complex EXAMPLES:: @@ -274,7 +274,7 @@ def __init__(self, maximal_faces=None, name=None, **kwds): def _repr_(self): """ - Print representation + Print representation. If the argument ``name`` was specified when defining the complex, use that. Otherwise, use the print representation @@ -301,7 +301,7 @@ def Sphere(n): INPUT: - - ``n`` -- positive integer + - ``n`` -- positive integer EXAMPLES:: @@ -331,7 +331,7 @@ def Simplex(n): INPUT: - - ``n`` -- a non-negative integer + - ``n`` -- nonnegative integer OUTPUT: the simplicial complex consisting of the `n`-simplex on vertices `(0, 1, ..., n)` and all of its faces. @@ -435,11 +435,11 @@ def SurfaceOfGenus(g, orientable=True): INPUT: - - ``g`` -- a non-negative integer. The desired genus + - ``g`` -- nonnegative integer; the desired genus - - ``orientable`` -- boolean (default: ``True``). If - ``True``, return an orientable surface, and if ``False``, - return a non-orientable surface. + - ``orientable`` -- boolean (default: ``True``); if + ``True``, return an orientable surface, and if ``False``, + return a non-orientable surface. In the orientable case, return a sphere if `g` is zero, and otherwise return a `g`-fold connected sum of a torus with itself. @@ -481,7 +481,7 @@ def MooreSpace(q): INPUT: - - ``q`` -- integer, at least 2 + - ``q`` -- integer; at least 2 This is a simplicial complex with simplices of dimension 0, 1, and 2, such that its reduced homology is isomorphic to @@ -674,7 +674,7 @@ def RealProjectiveSpace(n): INPUT: - - ``n`` -- integer, the dimension of the real projective space + - ``n`` -- integer; the dimension of the real projective space to construct The first few cases are pretty trivial: @@ -1069,7 +1069,7 @@ def NotIConnectedGraphs(n, i): INPUT: - - ``n``, ``i`` -- non-negative integers with `i` at most `n` + - ``n``, ``i`` -- nonnegative integers with `i` at most `n` See Dumas et al. [DHSW2003]_ for information on computing its homology by computer, and see Babson et al. [BBLSW1999]_ for theory. For @@ -1124,7 +1124,7 @@ def MatchingComplex(n): INPUT: - - ``n`` -- positive integer. + - ``n`` -- positive integer See Dumas et al. [DHSW2003]_ for information on computing its homology by computer, and see Wachs [Wac2003]_ for an expository article about @@ -1201,7 +1201,7 @@ def ChessboardComplex(n, i): INPUT: - - ``n, i`` -- positive integers. + - ``n``, ``i`` -- positive integers See Dumas et al. [DHSW2003]_ for information on computing its homology by computer, and see Wachs [Wac2003]_ for an expository article about @@ -1234,7 +1234,7 @@ def ChessboardComplex(n, i): def RandomComplex(n, d, p=0.5): """ - A random ``d``-dimensional simplicial complex on ``n`` vertices. + A random `d`-dimensional simplicial complex on `n` vertices. INPUT: @@ -1242,8 +1242,7 @@ def RandomComplex(n, d, p=0.5): - ``d`` -- dimension of the complex - - ``p`` -- floating point number between 0 and 1 - (default: 0.5) + - ``p`` -- floating point number between 0 and 1 (default: 0.5) A random `d`-dimensional simplicial complex on `n` vertices, as defined for example by Meshulam and Wallach [MW2009]_, is @@ -1308,7 +1307,7 @@ def SumComplex(n, A): INPUT: - - ``n`` -- a positive integer + - ``n`` -- positive integer - ``A`` -- a subset of `\ZZ/(n)` @@ -1387,7 +1386,7 @@ def RandomTwoSphere(n): INPUT: - `n` -- an integer + - ``n`` -- integer OUTPUT: @@ -1466,7 +1465,7 @@ def ShiftedComplex(generators): INPUT: - - ``generators`` -- a list of generators of the order ideal, which may + - ``generators`` -- list of generators of the order ideal, which may be lists, tuples or simplices EXAMPLES:: @@ -1586,9 +1585,9 @@ def FareyMap(p): INPUT: - - `p` -- a prime number + - ``p`` -- a prime number - The vertices are the non-zero pairs `(x,y)` in `\GF(p)^2` modulo + The vertices are the nonzero pairs `(x,y)` in `\GF(p)^2` modulo the identification of `(-x, -y)` with `(x,y)`. The triangles are the images of the base triangle ((1,0),(0,1),(1,1)) diff --git a/src/sage/topology/simplicial_complex_homset.py b/src/sage/topology/simplicial_complex_homset.py index 5a8052eeb4d..7b9aceb8b64 100644 --- a/src/sage/topology/simplicial_complex_homset.py +++ b/src/sage/topology/simplicial_complex_homset.py @@ -92,7 +92,7 @@ def __call__(self, f): """ INPUT: - - ``f`` -- a dictionary with keys exactly the vertices of the domain + - ``f`` -- dictionary with keys exactly the vertices of the domain and values vertices of the codomain EXAMPLES:: diff --git a/src/sage/topology/simplicial_complex_morphism.py b/src/sage/topology/simplicial_complex_morphism.py index e1f87f3ddd2..02fbef2402e 100644 --- a/src/sage/topology/simplicial_complex_morphism.py +++ b/src/sage/topology/simplicial_complex_morphism.py @@ -131,7 +131,6 @@ def is_SimplicialComplexMorphism(x): use 'isinstance(..., SimplicialComplexMorphism)' instead. See https://github.com/sagemath/sage/issues/38103 for details. True - """ from sage.misc.superseded import deprecation deprecation(38103, @@ -461,7 +460,7 @@ def associated_chain_complex_morphism(self, base_ring=ZZ, def image(self): """ - Computes the image simplicial complex of `f`. + Compute the image simplicial complex of `f`. EXAMPLES:: @@ -499,7 +498,6 @@ def image(self): Simplicial complex with vertex set (0, 1) and facets {(0, 1)} sage: z.image() Simplicial complex with vertex set (0, 2) and facets {(0, 2)} - """ fa = [self(i) for i in self.domain().facets()] return SimplicialComplex(fa, maximality_check=True) @@ -550,7 +548,6 @@ def is_injective(self): False sage: y.is_injective() True - """ v = [self._vertex_dictionary[i[0]] for i in self.domain().faces()[0]] for i in v: @@ -648,7 +645,7 @@ def fiber_product(self, other, rename_vertices=True): def mapping_torus(self): r""" - The mapping torus of a simplicial complex endomorphism + The mapping torus of a simplicial complex endomorphism. The mapping torus is the simplicial complex formed by taking the product of the domain of ``self`` with a `4` point @@ -701,8 +698,8 @@ def induced_homology_morphism(self, base_ring=None, cohomology=False): - ``base_ring`` -- must be a field (default: ``QQ``) - - ``cohomology`` -- boolean (default: ``False``). If - ``True``, the map induced in cohomology rather than homology. + - ``cohomology`` -- boolean (default: ``False``); if + ``True``, the map induced in cohomology rather than homology EXAMPLES:: diff --git a/src/sage/topology/simplicial_set.py b/src/sage/topology/simplicial_set.py index 346de85f0b7..920df5e0437 100644 --- a/src/sage/topology/simplicial_set.py +++ b/src/sage/topology/simplicial_set.py @@ -9,7 +9,7 @@ This module implements simplicial sets. A *simplicial set* `X` is a collection of sets `X_n` indexed by the -non-negative integers; the set `X_n` is called the set of +nonnegative integers; the set `X_n` is called the set of `n`-simplices. These sets are connected by maps .. MATH:: @@ -284,12 +284,12 @@ class AbstractSimplex_class(SageObject): INPUT: - - ``dim`` -- integer, the dimension - - ``degeneracies`` (optional) -- iterable, the indices of the + - ``dim`` -- integer; the dimension + - ``degeneracies`` -- (optional) iterable, the indices of the degeneracy maps - - ``underlying`` (optional) -- a non-degenerate simplex - - ``name`` (optional) -- string - - ``latex_name`` (optional) -- string + - ``underlying`` -- (optional) a non-degenerate simplex + - ``name`` -- (optional) string + - ``latex_name`` -- (optional) string Users should not call this directly, but instead use :func:`AbstractSimplex`. See that function for more documentation. @@ -302,11 +302,11 @@ def __init__(self, dim, degeneracies=(), underlying=None, name=None, INPUT: - - ``dim`` -- integer, the dimension - - ``degeneracies`` (optional) -- iterable, the indices of the degeneracy maps - - ``underlying`` (optional) -- a non-degenerate simplex - - ``name`` (optional) -- string - - ``latex_name`` (optional) -- string + - ``dim`` -- integer; the dimension + - ``degeneracies`` -- (optional) iterable, the indices of the degeneracy maps + - ``underlying`` -- (optional) a non-degenerate simplex + - ``name`` -- (optional) string + - ``latex_name`` -- (optional) string Users should not call this directly, but instead use :func:`AbstractSimplex`. See that function for more @@ -334,7 +334,7 @@ def __init__(self, dim, degeneracies=(), underlying=None, name=None, sage: AbstractSimplex(-3, None) Traceback (most recent call last): ... - ValueError: the dimension must be non-negative + ValueError: the dimension must be nonnegative sage: AbstractSimplex(0, (1,)) Traceback (most recent call last): @@ -378,7 +378,7 @@ def __init__(self, dim, degeneracies=(), underlying=None, name=None, except TypeError: raise ValueError('the dimension must be an integer') if dim < 0: - raise ValueError('the dimension must be non-negative') + raise ValueError('the dimension must be nonnegative') self._dim = dim if degeneracies: self._degens = standardize_degeneracies(*degeneracies) @@ -667,7 +667,7 @@ def degeneracies(self): def is_degenerate(self): """ - True if this simplex is degenerate. + Return ``True`` if this simplex is degenerate. EXAMPLES:: @@ -681,7 +681,7 @@ def is_degenerate(self): def is_nondegenerate(self): """ - True if this simplex is non-degenerate. + Return ``True`` if this simplex is non-degenerate. EXAMPLES:: @@ -717,7 +717,7 @@ def apply_degeneracies(self, *args): INPUT: - - ``args`` -- integers + - ``args`` -- integer EXAMPLES:: @@ -748,7 +748,7 @@ def apply_degeneracies(self, *args): sage: e.apply_degeneracies([1,0]) Traceback (most recent call last): ... - TypeError: degeneracies are indexed by non-negative integers; do not use an explicit list or tuple + TypeError: degeneracies are indexed by nonnegative integers; do not use an explicit list or tuple """ if not args: return self @@ -922,12 +922,12 @@ def __init__(self, dim, name=None, latex_name=None): INPUT: - - ``dim`` -- non-negative integer, the dimension + - ``dim`` -- nonnegative integer; the dimension - - ``name`` (optional) -- string, a name for this simplex. + - ``name`` -- (optional) string; a name for this simplex - - ``latex_name`` (optional) -- string, a name for this simplex to - use in the LaTeX representation. + - ``latex_name`` -- (optional) string; a name for this simplex to + use in the LaTeX representation EXAMPLES:: @@ -970,19 +970,19 @@ def AbstractSimplex(dim, degeneracies=(), underlying=None, INPUT: - - ``dim`` -- a non-negative integer, the dimension of the - underlying non-degenerate simplex. + - ``dim`` -- nonnegative integer; the dimension of the + underlying non-degenerate simplex - - ``degeneracies`` (default: ``None``) -- a list or tuple of - non-negative integers, the degeneracies to be applied. + - ``degeneracies`` -- (default: ``None``) list or tuple of + nonnegative integers, the degeneracies to be applied - - ``underlying`` (optional) -- a non-degenerate simplex to which - the degeneracies are being applied. + - ``underlying`` -- (optional) a non-degenerate simplex to which + the degeneracies are being applied - - ``name`` (optional) -- string, a name for this simplex. + - ``name`` -- (optional) string; a name for this simplex - - ``latex_name`` (optional) -- string, a name for this simplex to - use in the LaTeX representation. + - ``latex_name`` -- (optional) string; a name for this simplex to + use in the LaTeX representation So to define a simplex formed by applying the degeneracy maps `s_2 s_1` to a 1-simplex, call ``AbstractSimplex(1, (2, 1))``. @@ -1099,7 +1099,7 @@ class SimplicialSet_arbitrary(Parent): A simplicial set. A simplicial set `X` is a collection of sets `X_n`, the - *n-simplices*, indexed by the non-negative integers, together with + *n-simplices*, indexed by the nonnegative integers, together with maps .. MATH:: @@ -1278,9 +1278,9 @@ def alexander_whitney(self, simplex, dim_left): INPUT: - - ``dim_left`` -- integer, the dimension of the left-hand factor + - ``dim_left`` -- integer; the dimension of the left-hand factor - OUTPUT: a list containing the triple ``(c, left, right)``, + OUTPUT: list containing the triple ``(c, left, right)``, where ``left`` and ``right`` are the two simplices described above. If either ``left`` or ``right`` is degenerate, ``c`` is 0; otherwise, ``c`` is 1. This is so that, when used to @@ -1318,7 +1318,7 @@ def nondegenerate_simplices(self, max_dim=None): INPUT: - - ``max_dim`` -- optional, default ``None``. If specified, + - ``max_dim`` -- (default: ``None``) if specified, return the non-degenerate simplices of this dimension or smaller. This argument is required if this simplicial set is infinite. @@ -1388,11 +1388,11 @@ def cells(self, subcomplex=None, max_dim=None): INPUT: - - ``subcomplex`` (optional) -- a subsimplicial set of this + - ``subcomplex`` -- (optional) a subsimplicial set of this simplicial set. If ``subcomplex`` is specified, then return the simplices in the quotient by the subcomplex. - - ``max_dim`` -- optional, default ``None``. If specified, + - ``max_dim`` -- (default: ``None``) if specified, return the non-degenerate simplices of this dimension or smaller. This argument is required if this simplicial set is infinite. @@ -1469,7 +1469,7 @@ def n_cells(self, n, subcomplex=None): - ``n`` -- the dimension - - ``subcomplex`` (default: ``None``) -- a subcomplex + - ``subcomplex`` -- (default: ``None``) a subcomplex of this cell complex. Return the cells which are in the quotient by this subcomplex. @@ -1603,14 +1603,14 @@ def constant_map(self, codomain=None, point=None): INPUT: - - ``codomain`` -- optional, default ``None``. If ``None``, the + - ``codomain`` -- (default: ``None``) if ``None``, the codomain is the standard one-point space constructed by :func:`Point`. Otherwise, either the codomain must be a pointed simplicial set, in which case the map is constant at the base point, or ``point`` must be specified. - - ``point`` -- optional, default ``None``. If specified, it + - ``point`` -- (default: ``None``) if specified, it must be a 0-simplex in the codomain, and it will be the - target of the constant map. + target of the constant map EXAMPLES:: @@ -1896,24 +1896,24 @@ def chain_complex(self, dimensions=None, base_ring=ZZ, augmented=False, chain complex in those dimensions, setting the chain groups in all other dimensions to zero. - - ``base_ring`` (default: ``ZZ``) -- commutative ring + - ``base_ring`` -- (default: `\ZZ`) commutative ring - - ``augmented`` (default: ``False``) -- if ``True``, + - ``augmented`` -- boolean (default: ``False``); if ``True``, return the augmented chain complex (that is, include a class - in dimension `-1` corresponding to the empty cell). + in dimension `-1` corresponding to the empty cell) - - ``cochain`` (default: ``False``) -- if ``True``, + - ``cochain`` -- boolean (default: ``False``); if ``True``, return the cochain complex (that is, the dual of the chain - complex). + complex) - - ``verbose`` (default: ``False``) -- ignored. + - ``verbose`` -- boolean (default: ``False``); ignored - - ``subcomplex`` (default: ``None``) -- if present, - compute the chain complex relative to this subcomplex. + - ``subcomplex`` -- (default: ``None``) if present, + compute the chain complex relative to this subcomplex - - ``check`` (default: ``False``) -- If ``True``, make + - ``check`` -- boolean (default: ``False``); if ``True``, make sure that the chain complex is actually a chain complex: - the differentials are composable and their product is zero. + the differentials are composable and their product is zero .. NOTE:: @@ -1959,14 +1959,14 @@ def homology(self, dim=None, **kwds): INPUT: - - ``dim`` (default: ``None`` -- If ``None``, then + - ``dim`` -- (default: ``None``) if ``None``, then return the homology in every dimension. If ``dim`` is an integer or list, return the homology in the given dimensions. (Actually, if ``dim`` is a list, return the homology in the range from ``min(dim)`` to ``max(dim)``.) - - ``base_ring`` (default: ``ZZ``) -- commutative - ring, must be ``ZZ`` or a field. + - ``base_ring`` -- (default: ``ZZ``) commutative + ring; must be ``ZZ`` or a field Other arguments are also allowed: see the documentation for :meth:`.cell_complex.GenericCellComplex.homology`. @@ -2037,14 +2037,14 @@ def cohomology(self, dim=None, **kwds): INPUT: - - ``dim`` (default: ``None`` -- If ``None``, then + - ``dim`` -- (default: ``None``) if ``None``, then return the homology in every dimension. If ``dim`` is an integer or list, return the homology in the given dimensions. (Actually, if ``dim`` is a list, return the homology in the range from ``min(dim)`` to ``max(dim)``.) - - ``base_ring`` (default: ``ZZ``) -- commutative - ring, must be ``ZZ`` or a field. + - ``base_ring`` -- (default: ``ZZ``) commutative + ring; must be ``ZZ`` or a field Other arguments are also allowed, the same as for the :meth:`homology` method -- see @@ -2086,19 +2086,19 @@ def betti(self, dim=None, subcomplex=None): r""" The Betti numbers of this simplicial complex as a dictionary (or a single Betti number, if only one dimension is given): - the ith Betti number is the rank of the ith homology group. + the `i`-th Betti number is the rank of the `i`-th homology group. INPUT: - - ``dim`` (default: ``None`` -- If ``None``, then + - ``dim`` -- (default: ``None``) if ``None``, then return the homology in every dimension. If ``dim`` is an integer or list, return the homology in the given dimensions. (Actually, if ``dim`` is a list, return the homology in the range from ``min(dim)`` to ``max(dim)``.) - - ``subcomplex`` (default: ``None``) -- a subcomplex - of this cell complex. Compute the Betti numbers of the - homology relative to this subcomplex. + - ``subcomplex`` -- (default: ``None``) a subcomplex + of this cell complex. Compute the Betti numbers of the + homology relative to this subcomplex. .. NOTE:: @@ -2147,7 +2147,7 @@ def n_chains(self, n, base_ring=ZZ, cochains=False): The only difference between chains and cochains is notation: the generator corresponding to the dual of a simplex - ``sigma`` is written as ``"\chi_sigma"`` in the group of + ``sigma`` is written as ``'\chi_sigma'`` in the group of cochains. EXAMPLES:: @@ -2188,10 +2188,10 @@ def quotient(self, subcomplex, vertex_name='*'): - ``subcomplex`` -- subsimplicial set of this simplicial set, or a list, tuple, or set of simplices defining a - subsimplicial set. + subsimplicial set - - ``vertex_name`` (optional) -- string, name to be given to the new - vertex. By default, use ``'*'``. + - ``vertex_name`` -- string (default: ``'*'``); name to be given to the + new vertex In Sage, from a quotient simplicial set, you can recover the ambient space, the subcomplex, and (if the ambient space is @@ -2898,8 +2898,7 @@ def suspension(self, n=1): INPUT: - - ``n`` (default: 1) -- integer, suspend this many - times. + - ``n`` -- integer (default: 1); suspend this many times If this simplicial set `X` is not pointed, return the suspension: the quotient `CX/X`, where `CX` is the (ordinary, @@ -2930,12 +2929,12 @@ def suspension(self, n=1): sage: RP4.suspension(-3) # needs sage.groups Traceback (most recent call last): ... - ValueError: n must be non-negative + ValueError: n must be nonnegative """ from .simplicial_set_constructions import \ SuspensionOfSimplicialSet, SuspensionOfSimplicialSet_finite if n < 0: - raise ValueError('n must be non-negative') + raise ValueError('n must be nonnegative') if n == 0: return self if self.is_finite(): @@ -3020,7 +3019,7 @@ def _Hom_(self, other, category=None): INPUT: - ``other`` -- another simplicial set - - ``category`` -- optional, the category in which to compute + - ``category`` -- (optional) the category in which to compute the maps. By default this is ``SimplicialSets``, and it must be a subcategory of this or else an error is raised. @@ -3059,7 +3058,7 @@ def rename_latex(self, s): INPUT: - - ``s`` -- string, the LaTeX representation. Or ``s`` can be + - ``s`` -- string; the LaTeX representation. Or ``s`` can be ``None``, in which case the LaTeX name is unset. EXAMPLES:: @@ -3140,7 +3139,7 @@ class SimplicialSet_finite(SimplicialSet_arbitrary, GenericCellComplex): A finite simplicial set. A simplicial set `X` is a collection of sets `X_n`, the - *n-simplices*, indexed by the non-negative integers, together with + *n-simplices*, indexed by the nonnegative integers, together with face maps `d_i` and degeneracy maps `s_j`. A simplex is *degenerate* if it is in the image of some `s_j`, and a simplicial set is *finite* if there are only finitely many non-degenerate @@ -3148,26 +3147,26 @@ class SimplicialSet_finite(SimplicialSet_arbitrary, GenericCellComplex): INPUT: - - ``data`` -- the data defining the simplicial set. See below for - details. + - ``data`` -- the data defining the simplicial set; see below for + details - - ``base_point`` (default: ``None``) -- 0-simplex in this + - ``base_point`` -- (default: ``None``) 0-simplex in this simplicial set, its base point - - ``name`` (default: ``None``) -- string, the name of the + - ``name`` -- string (default: ``None``); the name of the simplicial set - - ``check`` (default: ``True``) -- boolean. If ``True``, + - ``check`` -- boolean (default: ``True``); if ``True``, check the simplicial identity on the face maps when defining the - simplicial set. + simplicial set - - ``category`` (default: ``None``) -- the category in + - ``category`` -- (default: ``None``) the category in which to define this simplicial set. The default is either finite simplicial sets or finite pointed simplicial sets, depending on whether a base point is defined. - - ``latex_name`` (default: ``None``) -- string, the LaTeX - representation of the simplicial set. + - ``latex_name`` -- string (default: ``None``); the LaTeX + representation of the simplicial set ``data`` should have one of the following forms: it could be a simplicial complex or `\Delta`-complex, in case it is converted to @@ -3617,22 +3616,22 @@ def chain_complex(self, dimensions=None, base_ring=ZZ, augmented=False, chain complex in those dimensions, setting the chain groups in all other dimensions to zero. - - ``base_ring`` (default: ``ZZ``) -- commutative ring + - ``base_ring`` -- commutative ring (default: `\ZZ`) - - ``augmented`` (default: ``False``) -- if ``True``, + - ``augmented`` -- boolean (default: ``False``); if ``True``, return the augmented chain complex (that is, include a class in dimension `-1` corresponding to the empty cell). - - ``cochain`` (default: ``False``) -- if ``True``, + - ``cochain`` -- boolean (default: ``False``); if ``True``, return the cochain complex (that is, the dual of the chain complex). - - ``verbose`` (default: ``False``) -- ignored. + - ``verbose`` -- boolean (default: ``False``); ignored - - ``subcomplex`` (default: ``None``) -- if present, - compute the chain complex relative to this subcomplex. + - ``subcomplex`` -- (default: ``None``) if present, + compute the chain complex relative to this subcomplex - - ``check`` (default: ``False``) -- If ``True``, make + - ``check`` -- boolean (default: ``False``); if ``True``, make sure that the chain complex is actually a chain complex: the differentials are composable and their product is zero. @@ -3784,8 +3783,7 @@ def algebraic_topological_model(self, base_ring=None): INPUT: - - ``base_ring`` -- coefficient ring (default: - ``QQ``). Must be a field. + - ``base_ring`` -- coefficient ring (default: ``QQ``); must be a field Denote by `C` the chain complex associated to this simplicial set. The algebraic topological model is a chain complex `M` @@ -3850,8 +3848,8 @@ def standardize_degeneracies(*L): INPUT: - - ``L`` -- list of integers, representing a composition of - degeneracies in a simplicial set. + - ``L`` -- list of integers representing a composition of + degeneracies in a simplicial set OUTPUT: @@ -3881,21 +3879,21 @@ def standardize_degeneracies(*L): sage: standardize_degeneracies(2, -1) Traceback (most recent call last): ... - ValueError: degeneracies are indexed by non-negative integers + ValueError: degeneracies are indexed by nonnegative integers sage: standardize_degeneracies([2, 1]) Traceback (most recent call last): ... - TypeError: degeneracies are indexed by non-negative integers; do not use an explicit list or tuple + TypeError: degeneracies are indexed by nonnegative integers; do not use an explicit list or tuple """ J = list(L) for m in J: try: if Integer(m) < 0: - raise ValueError('degeneracies are indexed by non-negative integers') + raise ValueError('degeneracies are indexed by nonnegative integers') except TypeError: # Likely if called via standard_degeneracies([1,2,3]) # rather than standard_degeneracies(1,2,3). - raise TypeError('degeneracies are indexed by non-negative integers; do not use an explicit list or tuple') + raise TypeError('degeneracies are indexed by nonnegative integers; do not use an explicit list or tuple') inadmissible = True while inadmissible: inadmissible = False @@ -3958,8 +3956,8 @@ def standardize_face_maps(*L): INPUT: - - ``L`` -- list of integers, representing a composition of - face maps in a simplicial set. + - ``L`` -- list of integers representing a composition of + face maps in a simplicial set OUTPUT: @@ -3985,7 +3983,7 @@ def standardize_face_maps(*L): J = list(L) for m in J: if Integer(m) < 0: - raise ValueError('faces are indexed by non-negative integers') + raise ValueError('faces are indexed by nonnegative integers') inadmissible = True while inadmissible: inadmissible = False @@ -4006,8 +4004,8 @@ def face_degeneracies(m, I): INPUT: - ``m`` -- integer - - ``I`` -- tuple ``(i_1, i_2, ..., i_n)`` of integers. We assume - that this sequence is strictly decreasing. + - ``I`` -- tuple ``(i_1, i_2, ..., i_n)`` of integers; we assume + that this sequence is strictly decreasing Using the simplicial identities (see :mod:`.simplicial_set`), we can rewrite @@ -4023,9 +4021,8 @@ def face_degeneracies(m, I): s_{j_1} s_{j_2} ... s_{j_n} d_t, \quad s_{j_1} s_{j_2} ... s_{j_{n-1}}. - - OUTPUT: the pair ``(J, t)`` or ``(J, None)``. ``J`` is returned as - a list. + OUTPUT: the pair ``(J, t)`` or ``(J, None)``; ``J`` is returned as + a list EXAMPLES:: diff --git a/src/sage/topology/simplicial_set_constructions.py b/src/sage/topology/simplicial_set_constructions.py index 13f7c27e4f6..4e17179e8bf 100644 --- a/src/sage/topology/simplicial_set_constructions.py +++ b/src/sage/topology/simplicial_set_constructions.py @@ -247,7 +247,7 @@ def __init__(self, maps=None): INPUT: - - ``maps`` -- a list or tuple of morphisms of simplicial sets + - ``maps`` -- list or tuple of morphisms of simplicial sets If only a single map `f: X \to Y` is given, then return `X`. If no maps are given, return the one-point simplicial @@ -381,7 +381,7 @@ def defining_map(self, i): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -437,7 +437,7 @@ def __init__(self, maps=None): INPUT: - - ``maps`` -- a list or tuple of morphisms of simplicial sets + - ``maps`` -- list or tuple of morphisms of simplicial sets EXAMPLES:: @@ -663,7 +663,7 @@ def universal_property(self, *maps): INPUT: - ``maps`` -- maps from a simplicial set `Z` to the "factors" - `X_i` forming the pullback. + `X_i` forming the pullback If the pullback `P` is formed by maps `f_i: X_i \to Y`, then given maps `g_i: Z \to X_i` such that `f_i g_i = f_j g_j` for @@ -741,7 +741,7 @@ def factor(self, i): INPUT: - - ``i`` -- integer, the index of the factor + - ``i`` -- integer; the index of the factor EXAMPLES:: @@ -784,7 +784,7 @@ def __init__(self, factors=None): INPUT: - - ``factors`` -- a list or tuple of simplicial sets + - ``factors`` -- list or tuple of simplicial sets Return the product of the simplicial sets in ``factors``. @@ -922,9 +922,9 @@ def factor(self, i, as_subset=False): INPUT: - - ``i`` -- integer, the index of the factor + - ``i`` -- integer; the index of the factor - - ``as_subset`` -- boolean, optional (default ``False``) + - ``as_subset`` -- boolean (default: ``False``) If ``as_subset`` is ``True``, return the `i`-th factor as a subsimplicial set of the product, identifying it with its @@ -972,7 +972,7 @@ def factor(self, i, as_subset=False): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -989,7 +989,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -1051,7 +1051,7 @@ def projection_map(self, i): INPUT: - - ``i`` -- integer, the index of the projection map + - ``i`` -- integer; the index of the projection map EXAMPLES:: @@ -1158,8 +1158,8 @@ def __init__(self, maps=None, vertex_name=None): INPUT: - - ``maps`` -- a list or tuple of morphisms of simplicial sets - - ``vertex_name`` -- optional, default ``None`` + - ``maps`` -- list or tuple of morphisms of simplicial sets + - ``vertex_name`` -- (default: ``None``) If only a single map `f: X \to Y` is given, then return `Y`. If no maps are given, return the empty simplicial @@ -1366,7 +1366,7 @@ def defining_map(self, i): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -1427,8 +1427,8 @@ def __init__(self, maps=None, vertex_name=None): INPUT: - - ``maps`` -- a list or tuple of morphisms of simplicial sets - - ``vertex_name`` -- optional, default ``None`` + - ``maps`` -- list or tuple of morphisms of simplicial sets + - ``vertex_name`` -- (default: ``None``) EXAMPLES:: @@ -1623,12 +1623,12 @@ def structure_map(self, i): def universal_property(self, *maps): r""" - Return the map induced by ``maps`` + Return the map induced by ``maps``. INPUT: - ``maps`` -- maps "factors" `Y_i` forming the pushout to a - fixed simplicial set `Z`. + fixed simplicial set `Z` If the pushout `P` is formed by maps `f_i: X \to Y_i`, then given maps `g_i: Y_i \to Z` such that `g_i f_i = g_j f_j` for @@ -1697,7 +1697,7 @@ def __init__(self, inclusion, vertex_name='*'): - ``inclusion`` -- inclusion map of a subcomplex (= subsimplicial set) of a simplicial set - - ``vertex_name`` -- optional, default ``'*'`` + - ``vertex_name`` -- string (default: ``'*'``) A subcomplex `A` comes equipped with the inclusion map `A \to X` to its ambient complex `X`, and this constructs the @@ -1829,7 +1829,7 @@ def n_skeleton(self, n): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -1841,7 +1841,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -1937,7 +1937,7 @@ def __init__(self, factors=None): INPUT: - - ``factors`` -- a list or tuple of simplicial sets + - ``factors`` -- list or tuple of simplicial sets Return the smash product of the simplicial sets in ``factors``: the smash product `X \wedge Y` is defined to be @@ -1964,7 +1964,7 @@ def __init__(self, factors=None): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -1980,7 +1980,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2013,7 +2013,7 @@ def __init__(self, factors=None): INPUT: - - ``factors`` -- a list or tuple of simplicial sets + - ``factors`` -- list or tuple of simplicial sets Return the wedge of the simplicial sets in ``factors``: the wedge sum `X \vee Y` is formed by taking the disjoint @@ -2071,7 +2071,7 @@ def __init__(self, factors=None): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -2086,7 +2086,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2108,7 +2108,7 @@ def __init__(self, factors=None): INPUT: - - ``factors`` -- a tuple of simplicial sets + - ``factors`` -- tuple of simplicial sets If there are no factors, a point is returned. @@ -2210,7 +2210,7 @@ def __init__(self, factors=None): INPUT: - - ``factors`` -- a list or tuple of simplicial sets + - ``factors`` -- list or tuple of simplicial sets Discard any factors which are empty and return the disjoint union of the remaining simplicial sets in ``factors``. The @@ -2280,7 +2280,7 @@ def n_skeleton(self, n): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -2296,7 +2296,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2319,7 +2319,7 @@ def __init__(self, factors=None): INPUT: - - ``factors`` -- a tuple of simplicial sets + - ``factors`` -- tuple of simplicial sets Return the disjoint union of the simplicial sets in ``factors``. The disjoint union comes equipped with a map @@ -2372,7 +2372,7 @@ def __init__(self, base): INPUT: - - ``base`` -- return the cone on this simplicial set. + - ``base`` -- return the cone on this simplicial set Add a point `*` (which will become the base point) and for each simplex `\sigma` in ``base``, add both `\sigma` and a @@ -2439,7 +2439,7 @@ def n_skeleton(self, n): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -2450,7 +2450,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2467,7 +2467,7 @@ def __init__(self, base): INPUT: - - ``base`` -- return the cone on this simplicial set. + - ``base`` -- return the cone on this simplicial set Add a point `*` (which will become the base point) and for each simplex `\sigma` in ``base``, add both `\sigma` and a @@ -2561,7 +2561,7 @@ def __init__(self, base): INPUT: - - ``base`` -- return the cone on this simplicial set. + - ``base`` -- return the cone on this simplicial set Start with the unreduced cone: take ``base`` and add a point `*` (which will become the base point) and for each simplex @@ -2629,7 +2629,7 @@ def n_skeleton(self, n): def _repr_(self): """ - Print representation + Print representation. EXAMPLES:: @@ -2641,7 +2641,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -2659,7 +2659,7 @@ def __init__(self, base): INPUT: - - ``base`` -- return the cone on this simplicial set. + - ``base`` -- return the cone on this simplicial set Start with the unreduced cone: take ``base`` and add a point `*` (which will become the base point) and for each simplex @@ -2728,7 +2728,7 @@ def __init__(self, base): INPUT: - - ``base`` -- return the suspension of this simplicial set. + - ``base`` -- return the suspension of this simplicial set If this simplicial set ``X=base`` is not pointed, or if it is itself an unreduced suspension, return the unreduced @@ -2827,8 +2827,8 @@ def __repr_or_latex__(self, output_type=None): INPUT: - - ``output_type`` -- either ``"latex"`` for LaTeX output or - anything else for ``str`` output. + - ``output_type`` -- either ``'latex'`` for LaTeX output or + anything else for ``str`` output We use `S` to denote unreduced suspension, `\Sigma` for reduced suspension. @@ -2869,7 +2869,7 @@ def __repr_or_latex__(self, output_type=None): def _repr_(self): r""" - Print representation + Print representation. We use `S` to denote unreduced suspension, `\Sigma` for reduced suspension. @@ -2889,7 +2889,7 @@ def _repr_(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. We use `S` to denote unreduced suspension, `\Sigma` for reduced suspension. @@ -2919,7 +2919,7 @@ def __init__(self, base): r""" INPUT: - - ``base`` -- return the suspension of this finite simplicial set. + - ``base`` -- return the suspension of this finite simplicial set See :class:`SuspensionOfSimplicialSet` for more information. diff --git a/src/sage/topology/simplicial_set_examples.py b/src/sage/topology/simplicial_set_examples.py index 1fc85df3f6e..498284e9816 100644 --- a/src/sage/topology/simplicial_set_examples.py +++ b/src/sage/topology/simplicial_set_examples.py @@ -717,7 +717,7 @@ def simplicial_data_from_kenzo_output(filename): def HopfMap(): r""" - Return a simplicial model of the Hopf map `S^3 \to S^2` + Return a simplicial model of the Hopf map `S^3 \to S^2`. This is taken from Exemple II.1.19 in the thesis of Clemens Berger [Ber1991]_. @@ -813,7 +813,7 @@ def PresentationComplex(G): INPUT: - - "G" -- a finitely presented group + - ``G`` -- a finitely presented group EXAMPLES:: diff --git a/src/sage/topology/simplicial_set_morphism.py b/src/sage/topology/simplicial_set_morphism.py index 483fe4adef6..c5285335a22 100644 --- a/src/sage/topology/simplicial_set_morphism.py +++ b/src/sage/topology/simplicial_set_morphism.py @@ -81,11 +81,11 @@ def __call__(self, f, check=True): r""" INPUT: - - ``f`` -- a dictionary with keys the simplices of the domain + - ``f`` -- dictionary with keys the simplices of the domain and values simplices of the codomain - - ``check`` -- optional, default ``True``. Pass this to the - morphism constructor. + - ``check`` -- boolean (default ``True``); pass this to the + morphism constructor EXAMPLES:: @@ -151,9 +151,8 @@ def constant_map(self, point=None): INPUT: - - ``point`` -- optional, default ``None``. If specified, it - must be a 0-simplex in the codomain, and it will be the - target of the constant map. + - ``point`` -- (default: ``None``) if specified, it must be a 0-simplex + in the codomain, and it will be the target of the constant map If ``point`` is specified, it is the target of the constant map. Otherwise, if the codomain is pointed, the target is its @@ -300,7 +299,7 @@ def __iter__(self): def _latex_(self): r""" - LaTeX representation + LaTeX representation. EXAMPLES:: @@ -321,17 +320,16 @@ def __init__(self, data=None, domain=None, codomain=None, INPUT: - - ``data`` -- optional. Dictionary defining the map. + - ``data`` -- (optional) dictionary defining the map - ``domain`` -- simplicial set - ``codomain`` -- simplicial set - - ``constant`` -- optional: if not ``None``, then this should + - ``constant`` -- (default: ``None``) if not ``None``, then this should be a vertex in the codomain, in which case return the - constant map with this vertex as the target. - - ``identity`` -- optional: if ``True``, return the identity - morphism. - - ``check`` -- optional, default ``True``. If ``True``, check - that this is actually a morphism: it commutes with the face - maps. + constant map with this vertex as the target + - ``identity`` -- boolean (default: ``False``); if ``True``, return the + identity morphism + - ``check`` -- boolean (default: ``True``); if ``True``, check + that this is actually a morphism: it commutes with the face maps So to define a map, you must specify ``domain`` and ``codomain``. If the map is constant, specify the target (a @@ -600,9 +598,11 @@ def __ne__(self, other): def __call__(self, x): """ - INPUT: a simplex of the domain. + Return the image of ``x`` under this morphism. + + INPUT: - Return its image under this morphism. + - ``x`` -- a simplex of the domain EXAMPLES:: @@ -911,7 +911,7 @@ def pushout(self, *others): INPUT: - ``others`` -- morphisms of simplicial sets, the domains of - which must all equal that of ``self``. + which must all equal that of ``self`` This returns the pushout as a simplicial set. See :class:`sage.topology.simplicial_set_constructions.PushoutOfSimplicialSets` @@ -946,7 +946,7 @@ def pullback(self, *others): INPUT: - ``others`` -- morphisms of simplicial sets, the codomains of - which must all equal that of ``self``. + which must all equal that of ``self`` This returns the pullback as a simplicial set. See :class:`sage.topology.simplicial_set_constructions.PullbackOfSimplicialSets` @@ -1126,7 +1126,7 @@ def product(self, *others): r""" Return the product of this map with ``others``. - - ``others`` -- morphisms of simplicial sets. + - ``others`` -- morphisms of simplicial sets If the relevant maps are `f_i: X_i \to Y_i`, this returns the natural map `\prod X_i \to \prod Y_i`. @@ -1152,7 +1152,7 @@ def coproduct(self, *others): r""" Return the coproduct of this map with ``others``. - - ``others`` -- morphisms of simplicial sets. + - ``others`` -- morphisms of simplicial sets If the relevant maps are `f_i: X_i \to Y_i`, this returns the natural map `\amalg X_i \to \amalg Y_i`. @@ -1179,7 +1179,7 @@ def suspension(self, n=1): INPUT: - - ``n`` (optional) -- non-negative integer, default 1 + - ``n`` -- nonnegative integer (default: 1) EXAMPLES:: @@ -1244,7 +1244,7 @@ def n_skeleton(self, n, domain=None, codomain=None): - ``n`` -- the dimension - - ``domain`` -- optional, the domain. Specify this to + - ``domain`` -- (optional) the domain. Specify this to explicitly specify the domain; otherwise, Sage will attempt to compute it. Specifying this can be useful if the domain is built as a pushout or pullback, so trying to compute it @@ -1252,7 +1252,7 @@ def n_skeleton(self, n, domain=None, codomain=None): infinite recursion. (Users should not have to specify this, but it may be useful for developers.) - - ``codomain`` -- optional, the codomain. + - ``codomain`` -- (optional) the codomain EXAMPLES:: @@ -1303,10 +1303,10 @@ def associated_chain_complex_morphism(self, base_ring=ZZ, INPUT: - ``base_ring`` -- default ``ZZ`` - - ``augmented`` -- boolean, default ``False``. If ``True``, - return the augmented complex. - - ``cochain`` -- boolean, default ``False``. If ``True``, - return the cochain complex. + - ``augmented`` -- boolean (default: ``False``); if ``True``, + return the augmented complex + - ``cochain`` -- boolean (default: ``False``); if ``True``, + return the cochain complex EXAMPLES:: @@ -1373,14 +1373,14 @@ def associated_chain_complex_morphism(self, base_ring=ZZ, def induced_homology_morphism(self, base_ring=None, cohomology=False): """ - Return the map in (co)homology induced by this map + Return the map in (co)homology induced by this map. INPUT: - ``base_ring`` -- must be a field (default: ``QQ``) - - ``cohomology`` -- boolean (default: ``False``). If - ``True``, the map induced in cohomology rather than homology. + - ``cohomology`` -- boolean (default: ``False``); if + ``True``, the map induced in cohomology rather than homology EXAMPLES:: diff --git a/src/sage/typeset/ascii_art.py b/src/sage/typeset/ascii_art.py index 28024405d27..83d92af8959 100644 --- a/src/sage/typeset/ascii_art.py +++ b/src/sage/typeset/ascii_art.py @@ -196,14 +196,14 @@ class AsciiArt(CharacterArt): def ascii_art(*obj, **kwds): r""" - Return an ASCII art representation + Return an ASCII art representation. INPUT: - ``*obj`` -- any number of positional arguments, of arbitrary type. The objects whose ascii art representation we want. - - ``sep`` -- optional ``'sep=...'`` keyword argument (or ``'separator'``). + - ``sep`` -- (optional) ``'sep=...'`` keyword argument (or ``'separator'``). Anything that can be converted to ascii art (default: empty ascii art). The separator in-between a list of objects. Only used if more than one object given. @@ -212,9 +212,7 @@ def ascii_art(*obj, **kwds): - ``sep_baseline`` -- (default: 0) the baseline for the separator - OUTPUT: - - :class:`AsciiArt` instance. + OUTPUT: :class:`AsciiArt` instance EXAMPLES:: diff --git a/src/sage/typeset/character_art.py b/src/sage/typeset/character_art.py index 389584f3bcf..e85e1143c7d 100644 --- a/src/sage/typeset/character_art.py +++ b/src/sage/typeset/character_art.py @@ -39,7 +39,7 @@ class CharacterArt(SageObject): def __init__(self, lines=[], breakpoints=[], baseline=None): r""" - Abstract base class for character art + Abstract base class for character art. INPUT: @@ -96,7 +96,7 @@ def __init__(self, lines=[], breakpoints=[], baseline=None): @classmethod def empty(cls): """ - Return the empty character art object + Return the empty character art object. EXAMPLES:: @@ -242,9 +242,7 @@ def _isatty(self): connected to a terminal. Otherwise you should treat ``stdout`` as being redirected to a file. - OUTPUT: - - Boolean + OUTPUT: boolean EXAMPLES:: @@ -292,7 +290,7 @@ def _splitting_points(self, size, offset=0): - ``size`` -- the maximum width of each chunk - - ``offset`` -- (default: ``0``); the first chunk has width at most + - ``offset`` -- (default: ``0``) the first chunk has width at most ``size - offset`` TESTS:: @@ -560,9 +558,7 @@ def width(self): r""" Return the length (width) of the ASCII art object. - OUTPUT: - - Integer. The number of characters in each line. + OUTPUT: integer; the number of characters in each line TESTS:: @@ -582,9 +578,7 @@ def height(self): r""" Return the height of the ASCII art object. - OUTPUT: - - Integer. The number of lines. + OUTPUT: integer; the number of lines TESTS:: diff --git a/src/sage/typeset/character_art_factory.py b/src/sage/typeset/character_art_factory.py index cbde3611858..eb268f3228a 100644 --- a/src/sage/typeset/character_art_factory.py +++ b/src/sage/typeset/character_art_factory.py @@ -26,7 +26,7 @@ def __init__(self, art_type, string_type, magic_method_name, parenthesis, square_bracet, curly_brace): r""" - Abstract base class for character art factory + Abstract base class for character art factory. This class is the common implementation behind :func:`~sage.typeset.ascii_art.ascii_art` and @@ -38,10 +38,10 @@ def __init__(self, :class:`~sage.typeset.character_art.CharacterArt`) - ``string_type`` -- type of strings (the lines in the - character art, e.g. ``str`` or ``unicode``). + character art, e.g. ``str`` or ``unicode``) - ``magic_method_name`` -- name of the Sage magic method (e.g. - ``'_ascii_art_'`` or ``'_unicode_art_'``). + ``'_ascii_art_'`` or ``'_unicode_art_'``) - ``parenthesis`` -- left/right pair of two multi-line symbols. The parenthesis, a.k.a. round brackets (used for printing @@ -78,9 +78,7 @@ def build(self, obj, baseline=None): we want - ``baseline`` -- (optional) the baseline of the object - OUTPUT: - - Character art object. + OUTPUT: character art object EXAMPLES:: @@ -136,11 +134,9 @@ def build(self, obj, baseline=None): def build_empty(self): """ - Return the empty character art object - - OUTPUT: + Return the empty character art object. - Character art instance. + OUTPUT: character art instance EXAMPLES:: @@ -152,11 +148,9 @@ def build_empty(self): def build_from_magic_method(self, obj, baseline=None): """ - Return the character art object created by the object's magic method + Return the character art object created by the object's magic method. - OUTPUT: - - Character art instance. + OUTPUT: character art instance EXAMPLES:: @@ -183,9 +177,7 @@ def build_from_string(self, obj, baseline=0): - ``obj`` -- utf-8 encoded byte string or unicode - ``baseline`` -- (default: 0) the baseline of the object - OUTPUT: - - Character art instance. + OUTPUT: character art instance EXAMPLES:: @@ -416,7 +408,7 @@ def build_tuple(self, t, baseline=0): def concatenate(self, iterable, separator, empty=None, baseline=0, nested=False): r""" - Concatenate multiple character art instances + Concatenate multiple character art instances. The breakpoints are set as the breakpoints of the ``separator`` together with the breakpoints of the objects in ``iterable``. @@ -531,7 +523,7 @@ def parse_keywords(self, kwds): INPUT: - - ``kwds`` -- a dict + - ``kwds`` -- dictionary OUTPUT: diff --git a/src/sage/typeset/symbols.py b/src/sage/typeset/symbols.py index 1701603b408..7643880373f 100644 --- a/src/sage/typeset/symbols.py +++ b/src/sage/typeset/symbols.py @@ -63,36 +63,36 @@ def __init__(self, character, top, extension, bottom, middle_top=None, middle_bottom=None, top_2=None, bottom_2=None): """ - A multi-character (ascii/unicode art) symbol + A multi-character (ascii/unicode art) symbol. INPUT: - Instead of string, each of these can be unicode in Python 2: + Instead of a string, each of these can be unicode in Python 2: - - ``character`` -- string. The single-line version of the symbol. + - ``character`` -- string; the single-line version of the symbol - - ``top`` -- string. The top line of a multi-line symbol. + - ``top`` -- string; the top line of a multi-line symbol - - ``extension`` -- string. The extension line of a multi-line symbol (will - be repeated). + - ``extension`` -- string; the extension line of a multi-line symbol (will + be repeated) - - ``bottom`` -- string. The bottom line of a multi-line symbol. + - ``bottom`` -- string; the bottom line of a multi-line symbol - - ``middle`` -- optional string. The middle part, for example + - ``middle`` -- (optional) string; the middle part, for example in curly braces. Will be used only once for the symbol, and only if its height is odd. - - ``middle_top`` -- optional string. The upper half of the + - ``middle_top`` -- (optional) string; the upper half of the 2-line middle part if the height of the symbol is even. Will be used only once for the symbol. - - ``middle_bottom`` -- optional string. The lower half of the + - ``middle_bottom`` -- (optional) string; the lower half of the 2-line middle part if the height of the symbol is even. Will be used only once for the symbol. - - ``top_2`` -- optional string. The upper half of a 2-line symbol. + - ``top_2`` -- (optional) string; the upper half of a 2-line symbol - - ``bottom_2`` -- optional string. The lower half of a 2-line symbol. + - ``bottom_2`` -- (optional) string; the lower half of a 2-line symbol EXAMPLES:: @@ -117,7 +117,7 @@ def __init__(self, character, top, extension, bottom, def _repr_(self): """ - Return string representation + Return string representation. EXAMPLES:: @@ -129,15 +129,13 @@ def _repr_(self): def __call__(self, num_lines): r""" - Return the lines for a multi-line symbol + Return the lines for a multi-line symbol. INPUT: - - ``num_lines`` -- integer. The total number of lines. + - ``num_lines`` -- integer; the total number of lines - OUTPUT: - - List of strings / unicode strings. + OUTPUT: list of strings / unicode strings EXAMPLES:: @@ -162,13 +160,13 @@ def __call__(self, num_lines): def print_to_stdout(self, num_lines): """ - Print the multi-line symbol + Print the multi-line symbol. This method is for testing purposes. INPUT: - - ``num_lines`` -- integer. The total number of lines. + - ``num_lines`` -- integer; the total number of lines EXAMPLES:: @@ -195,7 +193,7 @@ class CompoundAsciiSymbol(CompoundSymbol): def character_art(self, num_lines): """ - Return the ASCII art of the symbol + Return the ASCII art of the symbol. EXAMPLES:: @@ -213,7 +211,7 @@ class CompoundUnicodeSymbol(CompoundSymbol): def character_art(self, num_lines): """ - Return the unicode art of the symbol + Return the unicode art of the symbol. EXAMPLES:: diff --git a/src/sage/typeset/unicode_art.py b/src/sage/typeset/unicode_art.py index 1d8e0933b5b..1fa4243304a 100644 --- a/src/sage/typeset/unicode_art.py +++ b/src/sage/typeset/unicode_art.py @@ -65,15 +65,14 @@ class UnicodeArt(CharacterArt): def unicode_art(*obj, **kwds): r""" - Return an unicode art representation + Return an unicode art representation. INPUT: - - ``*obj`` -- any number of positional arguments, of arbitrary type. The objects whose ascii art representation we want. - - ``sep`` -- optional ``'sep=...'`` keyword argument (or ``'separator'``). + - ``sep`` -- (optional) ``'sep=...'`` keyword argument (or ``'separator'``). Anything that can be converted to unicode art (default: empty unicode art). The separator in-between a list of objects. Only used if more than one object given. @@ -82,9 +81,7 @@ def unicode_art(*obj, **kwds): - ``sep_baseline`` -- (default: 0) the baseline for the separator - OUTPUT: - - :class:`UnicodeArt` instance. + OUTPUT: :class:`UnicodeArt` instance EXAMPLES:: diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 50d56ccfd05..914426eb1be 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -447,10 +447,11 @@ def linkcode_resolve(domain, info): match = re.search(r'refs/pull/(\d+)/merge', github_ref) if match: pr_number = match.group(1) -is_develop_version = not version.split('.')[-1].isnumeric() +is_for_develop = github_ref.startswith('refs/heads/develop') is_for_github_pr = github_ref and match and pr_number +is_stable_release = version.split('.')[-1].isnumeric() -if is_develop_version or is_for_github_pr: # condition for announcement banner +if is_for_develop or is_for_github_pr or not is_stable_release: # condition for announcement banner # This URL is hardcoded in the file .github/workflows/doc-publish.yml. # See NETLIFY_ALIAS of the "Deploy to Netlify" step. ver = f'{version}' diff --git a/src/sage_setup/find.py b/src/sage_setup/find.py index 8762e08ad0f..5447f6418a4 100644 --- a/src/sage_setup/find.py +++ b/src/sage_setup/find.py @@ -53,7 +53,9 @@ def find_python_sources(src_dir, modules=['sage'], distributions=None, ``distribution`` (from a ``# sage_setup: distribution = PACKAGE`` directive in the module source file) is in ``exclude_distributions``. - OUTPUT: Triple consisting of + OUTPUT: + + Triple consisting of - the list of package names (corresponding to ordinary packages or namespace packages, according to @@ -184,7 +186,7 @@ def filter_cython_sources(src_dir, distributions, exclude_distributions=None): directive in the module source file) is an element of ``distributions``. - OUTPUT: List of absolute paths to Cython files (``*.pyx``). + OUTPUT: list of absolute paths to Cython files (``*.pyx``) EXAMPLES:: diff --git a/tox.ini b/tox.ini index 0d5efe81af6..3e3d2656553 100644 --- a/tox.ini +++ b/tox.ini @@ -283,16 +283,12 @@ setenv = # as of 2024-01, latest=39, rawhide=40 fedora: SYSTEM=fedora fedora: BASE_IMAGE=fedora + fedora: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-26: BASE_TAG=26 - fedora-26: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-27: BASE_TAG=27 - fedora-27: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-28: BASE_TAG=28 - fedora-28: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-29: BASE_TAG=29 - fedora-29: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-30: BASE_TAG=30 - fedora-30: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-31: BASE_TAG=31 fedora-32: BASE_TAG=32 fedora-33: BASE_TAG=33 @@ -300,13 +296,9 @@ setenv = fedora-35: BASE_TAG=35 fedora-36: BASE_TAG=36 fedora-37: BASE_TAG=37 - fedora-37: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-38: BASE_TAG=38 - fedora-38: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-39: BASE_TAG=39 - fedora-39: IGNORE_MISSING_SYSTEM_PACKAGES=yes fedora-40: BASE_TAG=40 - fedora-40: IGNORE_MISSING_SYSTEM_PACKAGES=yes # # https://hub.docker.com/r/scientificlinux/sl #